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

181 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)
```bash
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).