# Phase 8 — Admin Authentication and RBAC Report

## Status

Phase 8 is complete. The running web application now has a distinct Admin identity boundary with native Argon2id passwords, encrypted TOTP, single-use recovery codes, staged login challenges, opaque database-backed sessions, CSRF binding, route throttling, optional network allowlisting, server-loaded permissions, login/security evidence, and immutable audit integration.

## Delivered components

- `src/core/security/password.js`: asynchronous native Argon2id hashing, strict PHC parsing, parameter bounds, verification, and rehash detection.
- `src/core/security/encryption.js`: versioned AES-256-GCM authenticated encryption with associated-data binding.
- `src/modules/auth/two-factor.service.js`: RFC 6238 TOTP, Base32, replay-step enforcement, authenticator URI, and recovery-code digests.
- `src/modules/auth/admin-auth.*`: generic two-stage login, failure evidence, exponential lockout, TOTP/recovery completion, and Admin HTTP endpoints.
- `src/modules/auth/admin-session.*`: five-minute pending challenges and permission-bearing Admin sessions using opaque tokens hashed at rest.
- `src/http/middleware/admin-auth.middleware.js`: trusted Admin request identity.
- `src/http/middleware/permission.middleware.js`: explicit all-required RBAC gate.
- `src/http/middleware/admin-ip-allowlist.middleware.js`: startup-validated exact/CIDR network policy.
- `src/modules/audit/*`: persistent mutation audit provider.
- `src/modules/auth/admin-bootstrap.*` and `bin/create-super-admin.js`: database-locked, one-time 2FA Super Admin creation.
- `src/bootstrap/bootstrap-admin-auth.js`: production composition with login/sensitive rate limits and security providers.

## State transitions

| Current state | Input                      | Next state                  | Atomic evidence                                                    |
| ------------- | -------------------------- | --------------------------- | ------------------------------------------------------------------ |
| No session    | Valid email/password       | Five-minute 2FA challenge   | Hashed opaque challenge row                                        |
| Challenge     | Fresh valid TOTP           | Authenticated Admin session | `last_used_step`, session promotion, login attempt, security event |
| Challenge     | Valid unused recovery code | Authenticated Admin session | `used_at`, session promotion, login attempt, security event        |
| Challenge     | Invalid factor             | Revoked challenge           | Failure counter, login attempt, security event                     |
| Authenticated | Logout + CSRF              | Revoked session             | Revoke reason and Admin audit record                               |

## Security decisions

1. Admin and Telegram identities are separate request properties, cookies, session tables, and authorization models.
2. A password match alone never authorizes an Admin request.
3. Unknown-account login executes the same Argon2id work using a valid dummy hash and returns the same public error.
4. Accepted TOTP steps advance under the same row-locked transaction as session promotion, preventing concurrent replay.
5. Server-side role mappings are read for each authenticated request, so revoked permissions take effect without trusting cached browser claims.
6. All SQL values are parameterized; dynamic permission codes are never interpolated into SQL.
7. Authentication failures commit their evidence before a public error is thrown.
8. Corrupt encrypted security state fails as a server error and is never mistaken for a user credential failure.
9. Native Argon2id makes Node.js 24.11+ the minimum runtime for Phase 8.

## Verification result

The complete suite contains 117 passing tests at the implementation checkpoint: the original 101 Phase 7 tests plus 16 Phase 8 Admin security tests. Final `npm run check` remains the release gate and additionally covers formatting, environment validation, schema verification, CSS build, and project manifest verification.

No live MySQL data, Telegram configuration, Admin account, or deployment environment was modified while building Phase 8.

**Phase 8 status: COMPLETE AND VERIFIED.**