Roles, goals, permissions, and expected behavior for every consumer of the Auth module.
Permission values are exact from rbac/schemas/role.schema.ts:8 (DEFAULT_ROLES) and
rbac/permissions.constants.ts (ALL_PERMISSIONS). Auth self-service endpoints
(/auth/sessions, /auth/api-keys, /auth/2fa/*, /auth/logout-all) require only a
valid JWT — no permission metadata (OQ-5). What differs is which permissions a role
carries in the rest of the product.
Attribute Value
Frequency One-time; 10–15 min journey Goal Register their school + admin account, get tokens, verify email, enable 2FA Pain points Typo'd emails, lost verification emails, rate-limit 429 on retry storms Core job POST /auth/register (firstName,lastName,email,password≥8,tenantId) → tokens in data.accessToken/refreshTokenRestrictions Rate auth 5/min (auth.controller.ts:31); unknown tenantId accepted (created with that id) Expected behaviour Immediate login after submit; "verify your email" prompt (target contract), 2FA onboarding nudge Mental model "Fill form → I'm in → I'll confirm email from inbox"
Attribute Detail
Frequency Several times/day, many devices Permissions ALL_PERMISSIONS (role.schema.ts:23) — org ownerGoal Fast secure login, full device visibility, harden account with 2FA, API keys for integrations Pain point Account lockouts, 2FA device loss, "unknown device" logins they didn't make Expected Login → home; sessions screen lists all devices w/ browser/os/ip/location; per-device logout (DELETE /auth/sessions/:id), logout-all (POST /auth/logout-all), 2FA enable/verify/disable, API-key create→show-once Restrictions Revocation is by session id with no ownership check (OQ-5); keys revoked individually Mental model "Who's currently me? What to cancel?"
Attribute Detail
Permissions (from roles) teacher ['student.read','attendance.mark','attendance.edit']; staff ['student.read']; accountant ['fees.collect','student.read']; parent ['student.read']; student [] (role.schema.ts:31-42) Frequency 1–3 logins/day phone/tablet Goal "Just let me in", password reset without losing the day Pain points Forgot password over weekends; refresh expiry mid-work → single silent refresh; push→deep link login Expected Remembered device → auto-login (secure storage + refresh); reset flow intuitive step 1→2→3 Restrictions Registration flow is opaque (their account is created by admin via users); no tenant selection necessary — token carries tenant Mental model "One account, don't ask me again if possible" Auth-specific note These roles never touch sessions/2FA/API keys normally (UI hides the Security section except self-service password).
Attribute Detail
Permissions permissions: [] but JwtAuthGuard sets isPlatformAdmin=true when role present (jwt-auth.guard.ts:54) — bypass seedFrequency On-demand support; diagnostics Goal Resolve tenant issues; impersonation (planned); never logged into spec-touched accounts Restrictions Must hold a real tenant token; cross-tenant token on a tenant → tenantId mismatch → guard re-scopes ctx.tenantId from token (jwt-auth.guard.ts:44-55) Expected Session revocation on a user's behalf is not provided by AuthController today (future impersonate/unlock endpoints (planned) IMPLEMENTATION_PLAN.md)
Attribute Detail
Auth Authorization: Bearer <apiKey> (raw key); keys never loggedGoal Scoped machine access: library sync, fee batch, report pull, transport Permissions Key scopes[] free-form strings from CreateApiKeyDto (create-api-key.dto.ts:12); not yet checked by any guard — scoping is metadata today (OQ) Restrictions POST /auth/api-keys (name, scopes?) returns {id,prefix,key} — key visible once only (auth.service.ts:414); revoke via DELETE /auth/api-keys/:idLifecycle listApiKeys → {id,name,prefix,scopes,createdAt,lastUsedAt} (never full key); lastUsedAt updated elsewhere (api-key.repository.ts:35)
Attribute Detail
Frequency Registration abandons Behavior May return via /verify-email token; may retry register → 409 duplicate; may reset password on the pre-verify account
Value org_admin teacher/staff/accountant/parent/student platform_admin API-key consumer
Login screen ✓ ✓ ✓ — (uses key) Email verify interstitial (target) ✓ (on register) via invite flow — — 2FA onboarding recommended optional n/a — Sessions screen ✓ ✓ (self) ✓ — API keys screen ✓ admin may ✓ views on behalf? no Security settings (change password, etc.) ✓ ✓ (self) ✓ — Use PATCH /users/:id/preferences for theme/language ✓ ✓ ✓ —
Roles/goal frequency: shared baseline 00-shared/01 . Every persona's auth-facing needs collapse
to: log me in, keep me in (silent refresh), let me back in (reset), and don't scare me.
The module's killer features (session map, 2FA, key vault) are the admin-facing differentiators.