Files
faunosteo/docs/development/IDENTITY.md
T
bchanot 431999e45c docs(docs): V1-2.5 checkpoint corrections in browser tests, identity, contract
Eight phone skips by design, the unreadable-permissions and live-region checks, species order and Paris expiry restated in contract 7.2 and 4, PermissionsUnavailable in the folder map.
2026-11-03 00:14:19 +01:00

243 lines
16 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). When the caller's own grant rows cannot
be read, the sheet creation page and the administration home show
« Impossible de vérifier vos autorisations » with « Réessayer »
(`PermissionsUnavailable`; `authStore.reloadAccess` reads the roles and
grants again), never an absence of right (V1-2 contract §17.11). 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; the paths and gaps are reviewed in §4.2.
### 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`.
- TOTP code reuse (case 11, asserted): GoTrue keeps no record of used codes.
A code C taken in a fresh 30 s step N is accepted by session A, then by a
second `aal1` session B signed in after A's verify (B proven alive first,
and it reaches `aal2`), then by A again. A session D verifying C in step
N+1 is accepted too (one step of skew); a session E verifying C in step N+2
is refused (422 `mfa_verification_failed`). Measured span of one code: its
own step and the next, 30 to 60 s. Consequence: a code seen over a shoulder
or relayed by a phishing page can be replayed by any session holding the
password, more than once, within that span; it does not outlive it. Configuration that ran
the measurement: the sandbox GoTrue (`scripts/db-sandbox.sh`, image
`gotrue:v2.197.0`), which sets no MFA variable, so the image defaults apply.
The CLI and DEV stacks are configured by `supabase/config.toml` `[auth.mfa]`
(`max_enrolled_factors = 10`) and `[auth.mfa.totp]` (enrolment and
verification on), no replay setting either; the same behaviour is expected
there but only the sandbox was measured. No mitigation is added: the span is
a residual risk (V1-2 contract §13).
### 4.2 Lost authenticator: paths and gaps
Review of what happens when a person loses the device holding their TOTP
factor (V1-2 contract §5.6, §5.7.7). It describes; it adds no path and does
not weaken `aal2`.
| Path | What exists | Gap |
|---|---|---|
| Second factor | A factor is enrolled from `aal2`, then any verified factor reaches `aal2`. Recommended for every capability holder, two factors on two independent devices for the owner (§5.6, §5.7.7). | Nothing forces a second factor on a capability holder; a person with one factor and a lost device has no second path. |
| Self-service recovery | None. GoTrue issues no recovery codes. Password change and reset, and removal of a verified factor, need `aal2` (case 7, 4), so a lost factor cannot be removed or bypassed by the person. An ordinary account keeps its `aal1` use of the application; a capability holder loses the administration until recovery. | No recovery code or backup channel. By design. |
| Authorised administrative intervention | Operator procedure of V1-2 §5.6 and §5.7.7, run with server access: sign out every session, delete the factors, ban, new password with the person present, lift the ban, two new factors, list the factors. Never an application path: no RPC, screen or service path resets a factor. | A procedure on paper: not rehearsed (V1-2.9). |
| Identity checks | Out of band, the owner present, the reason recorded before anything changes. | Human control only; nothing in the system verifies it. |
| Audit trail | The operator writes the `auth.mfa_factor_reset` row in the same session; GoTrue keeps its own audit log of the factor and session changes. | The row depends on the operator writing it; a forgotten row is not detected. On a single-owner platform the operator is the owner, so there is no second person to check (the real control is server access). |
Production prerequisite: a recovery runbook rehearsed on the sandbox and
written here before any production use of MFA-protected rights. Until it
exists, the safe lost-factor recovery is missing, and capabilities must not
be granted in production.
## 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).