CLAUDE.md overview and folder map, IDENTITY §1 and §4, BROWSER_TESTS shell specs, V1-2 contract §16.6 state and §5.7.3-§5.7.4 pointers, design README owning steps with two deviations.
12 KiB
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, TOTP factors since V1-2.5 (§4), sign out) |
/app/anatomy, /:sheetId, /:sheetId/versions/:number |
RequireAuth, RequireCatalog (V1-2.5) |
catalogue of official sheets, a sheet's current version, an earlier version; « Accès non autorisé » on the server's refusal, the same for an unknown sheet |
/app/admin, /sheets, /sheets/new, /sheets/:sheetId, /species, /access |
RequireAuth, RequireAdmin (V1-2.5, step-up to aal2) |
administration home, official sheets, species, rights (owner); each page shows what the caller's capabilities allow |
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).
RequireCatalog decides nothing: the pages ask the server and show
« Accès non autorisé » (AccessDenied) when it refuses. RequireAdmin
renders the admin pages only on an aal2 session, so no admin data is
requested before the step-up (§4). The « Fiches anatomiques » and
« Administration » entries of the sidebar and drawer follow a hint built from
the caller's own grant rows and roles (auth/navigationHint.ts): a hidden
entry protects nothing, every RPC checks the capability and aal2 itself.
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.tssubscribes toclient.auth.onAuthStateChangeafterclient.auth.initialize()(which also exchanges the PKCE code found in the URL). Status:loading | unavailable | signed_out | signed_in. On sign-in it loadsprofiles(own row) and the activeprofile_roles.services/localeSync.ts: when a profile loads, itslocalewins over the device choice (once per sign-in); while signed in, switching the language (header toggle or the Preferences select) writesprofiles.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_atand roles are server-only. - Platform roles are read-only badges (
shell.role.*). The administration space (V1-2.5) manages catalogue rights and species, never platform roles. - GoTrue errors never reach the screen:
classifyAuthErrorfolds codes into a closedAuthFailureKind, phrased byauth.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 fromenv(SUPABASE_AUTH_EXTERNAL_<PROVIDER>_CLIENT_ID|SECRET); both areenabled = falseuntil the ids exist (put them insupabase/.env, gitignored, then flipenabled). Google needs an OAuth client with the redirecthttp://127.0.0.1:54321/auth/v1/callback(local) orhttps://<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/**andhttp://localhost:5173/**(local only). On the hosted project the allowlist is exact, never a host wildcard: Site URLhttps://<prod-origin>, Redirect URLshttps://<prod-origin>/auth/callbackandhttps://<prod-origin>/reset-password. A broad pattern there turnsemailRedirectTo/redirectTointo 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 (TOTP)
Architecture §2 wants TOTP mandatory for platform roles; V1-2 decision
BDR-083 requires aal2 for every platform role change and every catalogue
right (V1-2_ANATOMICAL_SHEETS.md §5.6, §5.7). State since V1-2.5:
- server: TOTP enrolment and verification on (
[auth.mfa.totp]). Since M4 (20261028100000_sheet_access_hardening.sql)private.has_mfa()reads the token'saalclaim, andprivate.has_aal2_session()also requires the token's session to still beaal2inauth.sessions; the role and rights RPCs use the second, the catalogue policies and RPCs the first. Theis_platform_*helpers still ignore the level: the RPCs that need it call the helpers above. - Mon compte, Sécurité (
components/account/{MfaFactors,EnrolTotp}.tsx): the factor list (verified and unverified), adding a factor (name, QR code, secret for manual entry shown once and kept in the component's state only, then a code), removal after a confirmation. An unverified factor the enrolment made is removed on cancel or unmount (a dormant factor is a path, V1-2 contract §5.7.3).packages/supabase/src/mfa.tsfolds GoTrue's answers into the closedMfaFailurekinds (mfa.failure.*). - Step-up at
/app/admin(RequireAdmin): anaal1session is asked for a code from one of its verified factors; without one, it is sent to Sécurité. - Step-up inside an action (
auth/useStepUp.ts,components/auth/InlineStepUp): when GoTrue refuses belowaal2(aal2_required: a second factor, the removal of a verified one, a password change), the challenge opens in place and the action is sent to GoTrue again once it succeeds, never bypassed. - Password reset (
/reset-password): an account with a verified factor steps up before the new password is sent, the recovery session included (§4.1).
Still open: the recovery runbook for a lost factor (V1-2 contract §5.7.7) is rehearsed at V1-2.9.
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, storedunverified; until verified a new sign-in staysaal1. - Verify: challenge and verify upgrade the same session (same
session_id) toaal2,amrpassword + totp, and delete the account's otheraal1sessions. GoTrue refuses their tokens at once; PostgREST keeps accepting their access token until it expires. - Second factor from
aal1: 403insufficient_aal; fromaal2: allowed. - Removing a verified factor from
aal1: 422insufficient_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 toaal1. Their access token keeps itsaal2claim 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 isaal1. - Dormant unverified factor: one left before any verification is deleted when
another factor is verified. One enrolled from
aal2after verification is kept and can later be verified from a password-only session, reachingaal2. Planting it needs anaal2session 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(401insufficient_aal), including from a recovery-link session (amrotp). Fromaal2it succeeds, keeps that session and deletes the account's others. The recovery screens and the §5.7.7 runbook must reachaal2first. Without a factor,aal1changes the password and staysaal1. - Refresh keeps
aal2; a new password sign-in starts ataal1. - Email change: refused at
aal1; fromaal2the confirmation link opens a newaal1session. Identity linking: 404manual_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)
/appwhile signed out →/login?next=%2Fapp. The login card shows a Google button (not functional until the provider is enabled: expect the "not enabled" message).- Wrong password → "E-mail ou mot de passe incorrect". Seeded account
alice@faunosteo.local/LocalDev-only-password-1→ lands on/app. - Dashboard: greeting, "À compléter : Prénom, Nom", "Adresse confirmée", no platform role (owner@ shows "Propriétaire plateforme").
- 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). - Mobile (375 px): hamburger opens the drawer; navigation closes it; no horizontal scroll on login, dashboard, account.
- Home shows "Mon espace" while signed in; sidebar "Se déconnecter" → Home with
"Se connecter";
/appguarded again. /signupwith a new address → "Vérifiez votre boîte mail"; open Mailpit, click the confirmation link in the same browser →/appsigned in, "Adresse confirmée"./forgot-password→ Mailpit recovery link →/reset-password→ new password →/app; sign out and sign in with the new password.- REST: anon cannot read profiles (
42501), alice reads one row only (SUPABASE.md §8). - Profile photo (Step 8, worker container running:
pnpm worker:imagethendocker compose --profile worker up workeror the container ofpnpm e2e:avataron 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).