Files
faunosteo/docs/development/IDENTITY.md
T
bchanot 3d2b5a5f1c docs(docs): V1-2.5 administration, MFA, catalogue documented
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.
2026-11-02 17:48:50 +01:00

205 lines
12 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, 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.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.*`). The administration
space (V1-2.5) manages catalogue rights and species, never platform roles.
- 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 (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's `aal` claim, and `private.has_aal2_session()` also requires the
token's session to still be `aal2` in `auth.sessions`; the role and rights
RPCs use the second, the catalogue policies and RPCs the first. The
`is_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.ts` folds GoTrue's answers into the
closed `MfaFailure` kinds (`mfa.failure.*`).
- Step-up at `/app/admin` (`RequireAdmin`): an `aal1` session 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 below `aal2` (`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`, 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).