01 — Product Overview (Auth Module)

• 1. Purpose
• 2. Business goals
• 3. User goals
• 4. Stakeholders
• 5. Why this exists
• 6. Dependencies
• 7. Success metrics
• 8. Edge cases
• 9. Assumptions (module)
• 10. Open questions (module-level; global ledger in 00-shared/12)
• 11. Glossary (this module)

StudyLyon — multi-tenant ERP / School Management API. This package designs the Auth module client (Flutter, forward-looking spec) against the implemented NestJS backend. All endpoints, DTO fields, schemas, events, rate limits, and wire contracts are derived directly from src/modules/auth/**, src/common/**, src/modules/rbac/**, and src/infrastructure/**. No feature is invented; gaps are flagged in the Assumptions & Open Questions section.

1. Purpose

Auth is the entry gate to every StudyLyon surface. It establishes who you are (identity), which tenant you act in (multi-tenancy), which roles/permissions you carry (RBAC), and manages the security artifacts that keep every subsequent request safe: JWT access/refresh token pairs, session registry, password credentials (Argon2id), email verification, TOTP 2FA, and scoped API keys for machine access.

2. Business goals

3. User goals

• Anonymous visitor: register a new institution + admin account in one step, land inside with working tokens (register returns tokens at institution).
• School admin: daily painless login, device overview + per-device logout, 2FA on, keys to integrations.
• Teacher / Staff / Parent / Student: quiet, reliable login; password reset that survive lost passwords; never re-enter credentials more than once a session.
• Platform admin: cross-tenant tool access via platform_admin role; impersonation is (planned).

4. Stakeholders

Platform operator, institution admins, teachers/staff, parents, students, M2M integrators (API keys), audit/security board, support staff (reset complaints), QA + design + engineering.

5. Why this exists

StudyLyon is multi-tenant: one codebase, thousands of schools. A flawed auth gate is the single highest-risk component (credential leaks, cross-tenant access, account takeover). This module is the flagship because every other module trusts its tokens.

6. Dependencies

7. Success metrics

• Login success rate ≥ 99.5% of attempts (excl. intentional 401).
• Session refresh success ≥ 99% (token rotation works with no user-visible 4xx on interstitial).
• Password reset → logged in within 5 min for ≥ 99% of resets (email delivery + flow).
• 2FA enablement completion rate ≥ 80% of admins within 30 days of onboarding.
• Zero auth-related security incidents (account enumeration, cross-tenant, token reuse).
• Rate-limit 429 correctly shown (never silent retry loops) on auth endpoints.
• API-Key creation → shown once (raw key never recoverable from any list).

8. Edge cases

• Unknown email vs wrong password → identical 401 (auth.service.ts:125,131).
• Locked account → 401 "Account locked. Try again later." (auth.service.ts:133-135) — lock expiry honored but no producer sets lockedUntil (OQ-2).
• Expired refresh used → session deleted → 401 "Session expired." (auth.service.ts:185-190).
• Reused/rotated refresh token → hash not in store → 401 "Session not found." (replay-safe by rotation; family revocation not implemented — OQ-3).
• Reset password → all existing sessions deleted → user must log in on every device (auth.service.ts:306).
• Verify+resend: verify already verified → 200 "Email already verified." (auth.service.ts:215).
• TOTP enable twice → 400; verify w/o enable → general → 400 "Call enable first."; wrong code → 401 (auth.service.ts:326,350-356).
• Register duplicate email → 409 (auth.service.ts:57).
• Logout with missing refresh token → controller throws generic Error → 500 (OQ-4).
• Rate-limit 429 → client countdown; global guard active only in production (rate-limit.guard.ts:30).
• List API keys: only non-revoked returned (api-key.repository.ts:22).

9. Assumptions (module)

• Mobile client is forward-looking: backend is complete; this package is the UI-side spec.
• "Email verification mandatory before first login" is the target FIXED WIRE contract (docs/blueprint security policy) but is not enforced by auth.service.ts today — register() mints tokens immediately and login() never checks emailVerified (auth.service.ts:54,123). UI must anticipate a "verify your email" interstitial and hard log-in gating as soon as the server enforces it (OQ-1).
• 2FA challenge during login (a "2FA step" after password) is not implemented in the backend; login returns tokens directly. Current code only supports 2FA as an account setting (enable/verify/disable). The 2FA-challenge screen is speced as (planned) / (forward-looking) and should only be reached when the server returns a challenge signal.
• Registration carries tenantId in the body (register.dto.ts:26-29) — a deliberate exception to "tenantId from token" for the tenant-bootstrap flow.
• No QR-code backend endpoint exists — the 2FA QR image is generated on-device from the returned secret/qrCodeUri (totp qrCodeUri is an otpauth:// URI, auth.service.ts:330).

10. Open questions (module-level; global ledger in 00-shared/12)

11. Glossary (this module)