Files
faunosteo/docs/development/IDENTITY.md
T
bchanot 78791bfb6b test(supabase): GoTrue MFA behaviour proven on the sandbox (V1-2.5 A)
Ten cases on the pinned GoTrue: aal1 cannot enrol a second factor or remove a verified one (no STOP); removal downgrades only the sessions verified with that factor; password change and reset need aal2 once a factor is verified. Findings in IDENTITY.md §4.1.
2026-11-02 16:19:47 +01:00

10 KiB
Raw Blame History

Identity: auth, profile, /app shell (Step 7)

Validated by the owner on 2026-10-12. Graphic reference: docs/design/faunosteo-etape7-maquettes-validees.png (see docs/design/README.md for what the mockup shows beyond this step).

Source of truth for the signed-in space added in Step 7. The local tool (/, /new, /editor) is untouched and needs no account; the two live side by side until the plan's Step 14 decides what goes behind authentication.

1. Routes

Route Guard Screen
/login visitor only (RedirectIfSignedIn) email + password, OAuth buttons per authProviders, link to signup / forgot
/signup visitor only display name, email, password ×2 → "check your inbox" step
/forgot-password visitor only email → "link sent" step
/reset-password none; needs the recovery session new password ×2; "invalid or expired link" otherwise
/auth/callback none landing of OAuth redirects and confirmation links; waits for the session then goes to /app (or ?next=)
/app RequireAuth dashboard: greeting, profile completeness card, local tool card, account card
/app/account RequireAuth Mon compte: profile photo (Step 8, STORAGE.md §4), personal, professional, preferences (language, timezone), security (password, MFA note, sign out)

RequireAuth waits for the client to read the persisted session, then sends a visitor to /login?next=<path>; next is honoured only when it is a same-origin path (safeNextPath). /app/* under the guard renders inside AppLayout (desktop sidebar, light top bar, mobile drawer).

A deployment without Supabase (APP_SUPABASE_URL empty) shows an "unavailable" notice on the auth screens; /app redirects to /login; the Home header shows no entry to the space. With Supabase configured, the Home header shows "Se connecter" or "Mon espace".

2. Session and profile in the app

  • state/authStore.ts subscribes to client.auth.onAuthStateChange after client.auth.initialize() (which also exchanges the PKCE code found in the URL). Status: loading | unavailable | signed_out | signed_in. On sign-in it loads profiles (own row) and the active profile_roles.
  • services/localeSync.ts: when a profile loads, its locale wins over the device choice (once per sign-in); while signed in, switching the language (header toggle or the Preferences select) writes profiles.locale.
  • Profile writes go through updateOwnProfile (packages/supabase), one PATCH per account section; the columns are the ones the migrations grant (display_name, first_name, last_name, phone, locale, timezone, practice_name, professional_title, siret). active, phone_verified_at and roles are server-only.
  • Platform roles are read-only badges (shell.role.*); no admin screen yet.
  • GoTrue errors never reach the screen: classifyAuthError folds codes into a closed AuthFailureKind, phrased by auth.failure.*.

3. Server configuration

supabase/config.toml:

  • email/password with confirmation mandatory, password policy 12 chars + lower/upper/digit (mirrored client-side in src/auth/validation.ts);
  • [auth.external.google] / [auth.external.apple] read their ids from env(SUPABASE_AUTH_EXTERNAL_<PROVIDER>_CLIENT_ID|SECRET); both are enabled = false until the ids exist (put them in supabase/.env, gitignored, then flip enabled). Google needs an OAuth client with the redirect http://127.0.0.1:54321/auth/v1/callback (local) or https://<project>.supabase.co/auth/v1/callback; Apple needs a paid developer account and a Services ID (BACKEND_ARCHITECTURE §2);
  • [auth.mfa.totp] enrolment and verification are on server-side;
  • redirect URLs allow http://127.0.0.1:5173/** and http://localhost:5173/** (local only). On the hosted project the allowlist is exact, never a host wildcard: Site URL https://<prod-origin>, Redirect URLs https://<prod-origin>/auth/callback and https://<prod-origin>/reset-password. A broad pattern there turns emailRedirectTo / redirectTo into a server-side open redirect.

The app side: APP_AUTH_PROVIDERS=google,apple (Docker) or VITE_AUTH_PROVIDERS (dev) lists the buttons to show. Showing a button for a provider the server has not enabled yields the phrased error "this sign-in method is not enabled".

PKCE pitfall: a confirmation or recovery link must be opened in the browser that made the request (the code verifier lives in its localStorage). Opened elsewhere, the email is still confirmed server-side but no session opens; the callback page says so and the user signs in normally.

4. MFA: what the foundations have, what is missing

Architecture §2 wants TOTP mandatory for owner/admin/moderator/support, enforced by an RLS helper has_mfa() on admin tables. Today:

  • server: TOTP enrolment/verification enabled (this step); nothing enforces it;
  • SQL: no private.has_mfa() helper (would read auth.jwt() ->> 'aal' = 'aal2'); the role helpers private.is_platform_* ignore the assurance level;
  • app: no enrolment UI (QR + code), no aal2 step-up on sign-in;
  • there is no admin table or screen yet to protect.

V1-2 decision (BDR-083): aal2 is required for every platform role change, see V1-2_ANATOMICAL_SHEETS.md §5.7 (rule, bootstrap, recovery).

The Security section shows a note instead. To close the gap (a later step): migration adding private.has_mfa() and folding it into is_platform_* (or into the policies of the first admin table) with pgTAP allowed/denied cases; enrolment + challenge screens in Mon compte; step-up at sign-in for accounts holding a platform role.

4.1 GoTrue v2.197.0 behaviour, measured on the sandbox (V1-2.5)

packages/supabase/tests/sandbox/mfa-behaviour.sandbox.ts (real GoTrue, run by pnpm db:sandbox test) asserts what the pinned image does; V1-2 contract §5.6, §5.7.1, §5.7.3, §5.7.4. None of it is assumed elsewhere.

  • First factor: enrolled from aal1, stored unverified; until verified a new sign-in stays aal1.
  • Verify: challenge and verify upgrade the same session (same session_id) to aal2, amr password + totp, and delete the account's other aal1 sessions. GoTrue refuses their tokens at once; PostgREST keeps accepting their access token until it expires.
  • Second factor from aal1: 403 insufficient_aal; from aal2: allowed.
  • Removing a verified factor from aal1: 422 insufficient_aal; an unverified one: allowed. The STOP condition of §5.6 did not fire.
  • Removing a verified factor from aal2: only the sessions last verified with that factor drop to aal1. Their access token keeps its aal2 claim until it expires: has_mfa() stays true for it, has_aal2_session() turns false, so the role and rights RPCs refuse it at once. Their next refresh is aal1.
  • Dormant unverified factor: one left before any verification is deleted when another factor is verified. One enrolled from aal2 after verification is kept and can later be verified from a password-only session, reaching aal2. Planting it needs an aal2 session and its secret (shown once), so it stays within the stolen-session residual (§5.7.8). Factor lists show unverified factors.
  • Password change or reset with a verified factor: refused at aal1 (401 insufficient_aal), including from a recovery-link session (amr otp). From aal2 it succeeds, keeps that session and deletes the account's others. The recovery screens and the §5.7.7 runbook must reach aal2 first. Without a factor, aal1 changes the password and stays aal1.
  • Refresh keeps aal2; a new password sign-in starts at aal1.
  • Email change: refused at aal1; from aal2 the confirmation link opens a new aal1 session. Identity linking: 404 manual_linking_disabled.
  • A TOTP code accepted twice within its 30 s window by two sessions of one factor (observed, not asserted).

5. Manual validation (local stack)

pnpm db:start                      # stack on the DEV origin (LAN address); Mailpit at http://<host>:54325 (basic auth, pnpm dev:gateway)
VITE_AUTH_PROVIDERS=google pnpm dev   # http://<host>:5173 from any device of the private network (ENVIRONMENTS.md)
  1. /app while signed out → /login?next=%2Fapp. The login card shows a Google button (not functional until the provider is enabled: expect the "not enabled" message).
  2. Wrong password → "E-mail ou mot de passe incorrect". Seeded account alice@faunosteo.local / LocalDev-only-password-1 → lands on /app.
  3. Dashboard: greeting, "À compléter : Prénom, Nom", "Adresse confirmée", no platform role (owner@ shows "Propriétaire plateforme").
  4. Mon compte: fill professional title / practice / SIRET → "Modifications enregistrées"; SIRET 1234 → inline error, nothing saved. Language select or the FR/EN toggle → the UI switches; reload → the account language is applied (profiles.locale in Studio).
  5. Mobile (375 px): hamburger opens the drawer; navigation closes it; no horizontal scroll on login, dashboard, account.
  6. Home shows "Mon espace" while signed in; sidebar "Se déconnecter" → Home with "Se connecter"; /app guarded again.
  7. /signup with a new address → "Vérifiez votre boîte mail"; open Mailpit, click the confirmation link in the same browser → /app signed in, "Adresse confirmée".
  8. /forgot-password → Mailpit recovery link → /reset-password → new password → /app; sign out and sign in with the new password.
  9. REST: anon cannot read profiles (42501), alice reads one row only (SUPABASE.md §8).
  10. Profile photo (Step 8, worker container running: pnpm worker:image then docker compose --profile worker up worker or the container of pnpm e2e:avatar on the sandbox): Mon compte → Modifier la photo with a phone JPEG → preview → Enregistrer → "Traitement en cours…" → the photo in the circle, the sidebar, the drawer (mobile) and the top bar (name beside it on desktop, alone on mobile) linking to Mon compte; a renamed PNG is accepted, an HTML or SVG file is refused at the picker; replace, then Supprimer la photo → confirmation → monogram; sign in as bob: nothing of alice shows; open the object path of alice's photo in a private window → 400.

Automated: pnpm test:run (auth store, locale sync, forms, guards, shell, dashboard, account, pgTAP 009), plus the headless end-to-end run described in the Step 7 report (not part of CI).