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.
This commit is contained in:
bchanot committed 2026-11-02 17:48:50 +01:00
1 parent c12702bac1
commit 3d2b5a5f1c
5 files changed
+97 -32

No files matched your search

+14 -2
View File
@@ -10,7 +10,7 @@ engines are installed. The suites live in `apps/app/e2e`.
| Command | Backend | Dev server | Content |
|---|---|---|---|
| `pnpm e2e:ui` | none | Vite on `127.0.0.1:5191` | `e2e/ui/dialog.spec.ts`: the D13 contract of the shared Dialog on a test page; `e2e/ui/local-tool.spec.ts`: the disclaimer, edit and replace dialogs on the real local-tool routes |
| `pnpm e2e:shell` | the isolated stack of `pnpm db:sandbox` | Vite on `127.0.0.1:5192` | `e2e/shell/shell.spec.ts`: sign-in, dashboard, the account photo confirmation, the phone drawer; `e2e/shell/clients.spec.ts`: the client journeys (V1-1.5); `e2e/shell/animals.spec.ts`: the animal and relation journeys (V1-1.6, contract §11.8); `e2e/shell/responsive.spec.ts`: no sideways scroll on nine shell pages, the archive confirmations and the drawer at 320, 360, 375, 390 and 430 px (phone project) and 1280 px, long values, the dashboard e-mail shown whole (RESP-01) |
| `pnpm e2e:shell` | the isolated stack of `pnpm db:sandbox` | Vite on `127.0.0.1:5192` | `e2e/shell/shell.spec.ts`: sign-in, dashboard, the account photo confirmation, the phone drawer; `e2e/shell/clients.spec.ts`: the client journeys (V1-1.5); `e2e/shell/animals.spec.ts`: the animal and relation journeys (V1-1.6, contract §11.8); `e2e/shell/responsive.spec.ts`: no sideways scroll on nine shell pages, the archive confirmations and the drawer at 320, 360, 375, 390 and 430 px (phone project) and 1280 px, long values, the dashboard e-mail shown whole (RESP-01); `e2e/shell/admin.spec.ts` (V1-2.5): A0 the owner's bootstrap (two TOTP factors from Sécurité, the step-up at `/app/admin` and inside a factor action, no second factor from `aal1`, refresh keeping `aal1` and `aal2`, rights granted and revoked with their reason), A1 a sheet created by an editor on a new inactive species, S1 a species created inactive then activated by the owner, access per right, axe and no sideways scroll on every admin page; `e2e/shell/catalogue.spec.ts` (V1-2.5): P1 a reader searches, opens a sheet, picks a zone, reads a retired version, drafts and archived sheets never listed, the same refusal for an existing and an unknown sheet without access, 320, 375 and 430 px with the whole drawing in the box at opening |
Each suite runs on two Chromium projects: `chromium-desktop` (1280 × 800) and
`chromium-375` (375 × 667, mobile viewport, touch). A test tagged `@phone`
@@ -33,7 +33,19 @@ fictitious display name, the profile locale of the test), and seeds the clean
avatar the worker would have produced (the `assets` row as postgres, the
object with the service key). Rows around the subject of a test (clients,
animals, relations) are written as postgres by `e2e/support/records.ts`,
every value quoted as an SQL literal. `pnpm db:sandbox down` removes all of it.
every value quoted as an SQL literal. The V1-2.5 suites set up what lies
before the page the same way: platform roles, catalogue grants and other
accounts' verified TOTP factors by `e2e/support/admin.ts` (roles through the
operator path, grants as postgres, a factor enrolled and verified on the real
GoTrue, its secret kept in the test's memory); official sheets by
`e2e/support/catalogue.ts` as SQL fixtures (published, retired, archived and
draft-only versions carrying the curated equine draft under names of their
own, the drawing in the private bucket under its content key), each published
or retired version's fingerprint computed in Node by the shipped core module
(`packages/core-wasm/pkg`, `preview.state`), the one the page runs. A0, A1 and
S1 are desktop journeys, skipped on the phone project (6 skips by design); the
admin screens at 375 px have their own test.
`pnpm db:sandbox down` removes all of it.
`pnpm db:sandbox e2e-shell <args>` passes its arguments to Playwright: one
spec file, `--project`, `--grep`. Every shell suite removes its routes after
each test without waiting for them (`dropLateReplays`), so an answer still in
+42 -18
View File
@@ -18,13 +18,23 @@ by side until the plan's Step 14 decides what goes behind authentication.
| `/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) |
| `/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
@@ -44,7 +54,8 @@ header shows "Se connecter" or "Mon espace".
(`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.
- 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.*`.
@@ -79,25 +90,38 @@ 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
## 4. MFA (TOTP)
Architecture §2 wants TOTP mandatory for `owner/admin/moderator/support`,
enforced by an RLS helper `has_mfa()` on admin tables. Today:
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/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.
- 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).
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.
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)
+17 -3
View File
@@ -605,7 +605,8 @@ management waits, and the first factor can always be enrolled at `aal1`.
#### 5.7.3 Additional, removed and replaced factors
Native behaviour of GoTrue v2.197.0 (source read, V1-2.5 proves it):
Native behaviour of GoTrue v2.197.0 (source read, V1-2.5 proves it; measured
on the sandbox: `IDENTITY.md` §4.1, V1-2.5):
- a second factor: `EnrollFactor` needs `aal2` once a verified factor exists
(403 `insufficient_aal`). A stolen password therefore cannot add a factor;
@@ -629,7 +630,8 @@ Native behaviour of GoTrue v2.197.0 (source read, V1-2.5 proves it):
owner choice under O4, not part of this contract (§5.7.9).
If the sandbox shows `aal1` can enrol a second factor or remove a verified
one, V1-2.5 stops for an owner decision (as §5.6 already says).
one, V1-2.5 stops for an owner decision (as §5.6 already says). It did not
fire (`IDENTITY.md` §4.1).
#### 5.7.4 Password change and reset
@@ -641,7 +643,9 @@ accepted first-factor case, harmless while no role or capability is held, and
the reason the owner role is assigned after enrolment (§5.7.1) and a
capability only to an account with a verified factor (§5.2). Email change and
identity linking stay as configured (`enable_manual_linking = false`); V1-2.5
adds a test that none of them raises a session to `aal2`.
adds a test that none of them raises a session to `aal2` (measured on the
sandbox: `IDENTITY.md` §4.1, V1-2.5; with a verified factor, a password change
or reset is itself refused at `aal1`, so the recovery screens step up first).
#### 5.7.5 Operator path
@@ -2277,6 +2281,16 @@ V1-2.7 on.
and readable by id; every other actor refused in the UI and in SQL.
- Rollback: branch revert.
- Checkpoint: gates only (owner at V1-2.6).
- State 2026-11-02: built and tested on the sandbox, slices A to J of the step
plan: A GoTrue MFA behaviour measured (`IDENTITY.md` §4.1), B M7
`sheet_admin_reads` (with BDR-098), C core op `sheet.empty`, D the
`packages/supabase` accessors (MFA, species, rights, admin and catalogue
reads), E navigation, `RequireCatalog`, `RequireAdmin` and « Accès non
autorisé », F TOTP factors in Mon compte with the step-up, G administration
page, species and rights, H sheet list, creation, overview and working copy,
I catalogue list, sheet and version pages, J the `e2e:shell` journeys.
pgTAP 1941, unit 864, `e2e:shell` 108 passed (6 skipped by design). DEV
untouched; the checkpoint gates are pending.
### 16.7 V1-2.6 Editor level 1