feat(auth): implement RBAC, user lifecycle, staff administration, and modular architecture

[GabGP]

Summary

This PR expands the backend authentication and user management subsystems for TutorBox (Week 1 Milestone).
It introduces full Role-Based Access Control (RBAC), student self-service onboarding, staff account administration, forced PIN rotation, append-only audit logging, and a modular architecture mirroring across src/ and tests/.

---

Key Changes

1. Database Migrations (migrations/004 – 006)

• 004_add_must_change_pin.sql: Adds must_change_pin column to enforce temporary-PIN rotation.
• 005_add_users_deleted_at.sql: Adds deleted_at and former_username columns for soft-deletion with
  username freeing and telemetry preservation.
• 006_add_audit_logs.sql: Creates append-only audit_logs table with indexed actor and target lookups.

2. Security & RBAC Infrastructure (src/security/)

• Role Enforcement: Reusable FastAPI dependencies (require_roles("student", "teacher", "admin")).
• Session Authentication: Bearer token resolution into typed AuthContext with active session checking (is_active = 1).
• Rotation Gate: Prevents access to privileged/operational routes when must_change_pin = 1 until PIN rotation is completed.
• Rate Limiting:
  • InMemoryRateLimiter: Thread-safe, bounded capacity, exponential backoff lockout for credential attempts.
  • SlidingWindowLimiter: Event-queue rate limiter for global signup flood prevention.
• Field Validation: Centralized Pydantic types (UsernameField, PinField, RoleField) enforcing boundaries and log-injection safety.

3. API Surface (src/api/)

• Auth (src/api/auth/):
  • POST /login: Authenticate username + PIN, return session token and must_change_pin status.
  • POST /logout: Invalidate caller's session token in SQLite.
• User Self-Service (src/api/users/):
  • POST /signup: Self-registration for student accounts (rate-limited).
  • GET /users/me: Profile retrieval for authenticated caller.
  • PATCH /users/me/pin: Change PIN (clears rotation flag, verifies current PIN, deactivates old session).
  • PATCH /users/me/username: Rename account (frees old username immediately).
• Staff Administration (src/api/staff/):
  • GET /users: Roster view of active users, or soft-deleted accounts (?include_deleted=true).
  • POST /users: Staff user creation (Teachers create students/teachers; Admins create any role).
  • POST /users/{id}/reset-pin: Issues 6-digit temp PIN, flags must_change_pin = 1, and invalidates all target sessions.
  • DELETE /users/{id}: Soft-deletes user, anonymizes username, preserves telemetry turn logs, and enforces last-admin guard.
  • POST /users/{id}/recover: Restores soft-deleted account under a new username with temporary PIN.
  • GET /audit-logs: Admin-only reverse chronological view of up to 500 audit entries.

4. Modular Refactor & Test Breakdown (tests/)

• Reorganized tests/ into 1:1 subpackages mirroring src/ (api/auth, api/users, api/staff, db, security).
• Deconstructed monolithic test files so all test files are $< 300$ LoC.
• Deduplicated shared fixtures (auth_headers, get_user_id) in tests/conftest.py.

---

Verification & Quality Gates

• Test Suite: 134 / 134 passed (68.3s runtime)
• Test Coverage: 100.00% statement coverage across all 25 source files (--cov-fail-under=80)
• Linting & Formatting: Clean (ruff check . and ruff format --check . return 0 errors)
• Security Proofs: 7 verified security proofs (no plain-text PIN/token logging, anti-oracle ordering, unusable anonymized hashes).

---

Branch Details

• Source Branch: week1_expanded
• Target Branch: main