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.
205 lines
12 KiB
Markdown
205 lines
12 KiB
Markdown
# 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).
|