# OMEGA Ultimate — Admin Accounts & Password Control

## Fresh database
1. Create a PostgreSQL 16 database.
2. Import `db/schema.sql` (or the downloadable `omega_ultimate_postgres16.sql`).
3. Set `BOOTSTRAP_TOKEN` and a strong `JWT_SECRET` in `.env`.
4. Start the stack and call `POST /api/v1/auth/bootstrap-owner` with `X-Bootstrap-Token` and a unique Owner username/password (minimum 12 characters). Bootstrap works only while `users` is empty.
5. Sign in to the dashboard and open **Users & Access** to create accounts.

## Existing database
Back up first, then run `db/migrations/002_admin_access.sql` or use the downloadable `omega_ultimate_admin_access.sql`. Do not import the full schema into a populated database.

## Owner controls
- Create separate Supervisor, Manager, Auditor, and Partner accounts.
- Change usernames, email addresses, and roles.
- Suspend/reactivate accounts.
- Reset another staff member's password.
- Set per-user permission overrides for tickets, applications, audit, analytics, broadcasts, shifts, and payroll viewing.
- Review admin actions in audit logs.
- Staff can change their own password after entering the current password.

## Password and session rules
- Minimum password length is 12 characters (maximum 128).
- Passwords are Argon2-hashed by the application; SQL never stores plaintext passwords.
- No shared default admin credentials are included. Create the Owner through the one-time bootstrap endpoint.
- Password resets, role changes, suspension, and reactivation increment the account token version, invalidating previously issued access tokens.
- Owner/system permissions cannot be granted by per-user permission overrides. Keep `.env`, bootstrap token, database credentials, and bot token private.

## API endpoints
- `POST /api/v1/auth/bootstrap-owner` — one-time Owner setup.
- `POST /api/v1/auth/login` — username/password login.
- `POST /api/v1/auth/change-password` — self-service password change.
- `GET /api/v1/admin/users` — list users (role-gated).
- `POST /api/v1/admin/users` — Owner creates staff account.
- `PATCH /api/v1/admin/users/{user_id}` — Owner updates username/email/role/status/Telegram ID.
- `POST /api/v1/admin/users/{user_id}/reset-password` — Owner resets password.
- `POST /api/v1/admin/users/{user_id}/suspend` / `activate` — Owner account control.
- `GET/PUT /api/v1/admin/users/{user_id}/permissions` — Owner per-user permission overrides.

## Verification notes
Contract tests and Python syntax/AST checks are included. This offline build environment could not install the declared Python dependencies or connect to a live PostgreSQL instance, so deployment-specific end-to-end testing remains required.