chore/backend/scripts/README.md

Backend Scripts

Utility scripts for backend management tasks.

create_admin.py

Creates an admin user account with elevated privileges.

Usage

cd backend
python scripts/create_admin.py

The script will prompt you for:

• Email address
• Password (minimum 8 characters)
• First name
• Last name

Security Notes

• Admin users can only be created through this script or direct database manipulation
• The admin role cannot be assigned through the signup API
• Existing email addresses will be rejected
• Passwords are hashed using werkzeug's secure hash algorithm

Example

$ python scripts/create_admin.py
=== Create Admin User ===

Email: admin@example.com
Password: ********
First name: Admin
Last name: User

Create admin user 'admin@example.com'? (yes/no): yes
✓ Admin user created successfully!
  Email: admin@example.com
  Name: Admin User
  Role: admin

hash_passwords.py

Migrates existing plain text passwords in the database to secure hashed passwords.

Usage

cd backend
python scripts/hash_passwords.py

Description

This script should be run once after deploying password hashing to convert any existing plain text passwords to secure hashes. It:

• Reads all users from the database
• Identifies plain text passwords (those not starting with hash prefixes)
• Hashes plain text passwords using werkzeug's secure algorithm
• Updates user records in the database
• Skips already-hashed passwords
• Reports the number of users updated

Security Notes

• Run this script only once after password hashing deployment
• Execute in a secure environment (admin access only)
• Verify a few users can log in after migration
• Delete or secure the script after use to prevent accidental re-execution
• The script is idempotent - running it multiple times is safe but unnecessary

Example

$ python scripts/hash_passwords.py
Password already hashed for user admin@example.com
Hashed password for user user1@example.com
Hashed password for user user2@example.com
Migration complete. Updated 2 users.

Requirements

These scripts require the backend virtual environment to be activated:

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate