docs(docs): V1-2.5 start, prerequisites and owner answers

Contract §17.10 (V1-2.1 VERIFIED at ac71c5b, V1-2.2, V1-2.4 approved), §3 EN « Permission », §12.3 M7 admin reads, §16.6 SQL and working-copy action, §16.2 state; step contract and plan.
This commit is contained in:
bchanot committed 2026-11-02 16:06:54 +01:00
1 parent 994b04ee73
commit 3d80812cdb
3 files changed
+109 -3

No files matched your search

@@ -0,0 +1,68 @@
# Contract: V1-2.5 administration space, rights, species, MFA, catalogue (owner, 2026-11-02)
Brief « Validation propriétaire V1-2.4 » (2026-11-02): V1-2.5 authorised once its dependencies are VERIFIED,
within the existing contract, no new scope. Prerequisites checked on `994b04e` (V1-2 contract §17.10). Plan:
V1-2 contract §16.6, with §5.2 to §5.7, §7.2, §10, §11, §15; owner answers BDR-097 (M7 admin reads,
working-copy action, EN « Permission »); design reference `docs/design/v1-2-4/` (approved, BDR-096).
Step plan: `.claude/tasks/plans/2026-11-02-v1-2-5.md`.
Kept from the brief: no merge into develop, main or a release; no Supabase DEV operation; no worker on DEV;
tests and an independent review fit for the step; commits and pushes on `feature/v1-2-anatomical-sheets`; STOP
at the V1-2.5 checkpoint (gates; the owner tries the result at V1-2.6). Sandbox stack only (`pnpm db:sandbox`),
never DEV; every command runs from the V1-2 worktree, never from the main checkout. The graphic design is not
reopened.
## Criteria
- C1 MFA behaviour proven on the sandbox (real GoTrue, §5.6, §5.7.1, §5.7.3, §5.7.4): first factor enrolled
at `aal1`; verify reaches `aal2`; a second factor from `aal1` refused; removal of a verified factor from
`aal1` refused; removal from `aal2` and what it does to the account's other sessions recorded; a dormant
unverified factor verified later recorded; a password change or reset never reaches `aal2`; refresh keeps
`aal2`; a new sign-in starts at `aal1`. Expectations are what the pinned image does; if `aal1` can enrol a
second factor or remove a verified one, the step STOPS for an owner decision.
- C2 Mon compte, Sécurité: add a TOTP factor (QR code, secret shown once, never stored, logged or sent
anywhere by the app), verify it with a code, name it, list and remove factors; the `aal2` requirements of
GoTrue surfaced as messages, never bypassed; a step-up challenge entering `/app/admin` at `aal1`, no admin
data requested before it succeeds.
- C3 Navigation (§11.1, BDR-094): « Fiches anatomiques » only for catalogue readers (hint from the caller's own
grant rows), one « Administration » entry for capability holders and the owner role, sidebar and drawer; a
direct `/app/anatomy` URL without the right shows « Accès non autorisé » (L32) acting on the server's
refusal, the same whether the sheet exists or not; signed out → login. Hidden entries protect nothing.
- C4 Administration (board 10, §11.1): the page lists the caller's permissions and session state; cards
« Fiches officielles », « Espèces », and « Accès et habilitations » for the owner only; each account sees only
the entries and actions its capabilities allow (reviewer-only: no « Nouvelle fiche », « Créer une copie de
travail », « Accès et habilitations », species creation or activation).
- C5 Sheets (A1, W1 start): `/app/admin/sheets` every official sheet with the historical and working-copy
badges and the filters species, sheet status, version status, round status, through M7; `/new` species
(inline creation of an inactive species), names, slug, from the core's empty document; `/:sheetId` overview
with versions and rounds; « Créer une copie de travail » on the historical sheet, disabled with its
explanation while a copy is active; creation and copy land on the overview (editor in V1-2.6).
- C6 Species (S1, §7.2): `/app/admin/species` active and inactive species; creation and editing of an
inactive species (E); activation and renaming (O); the animal forms unchanged until activation.
- C7 Rights (A0, §5.2): `/app/admin/access` (owner): find an account by e-mail, grant with reason,
verification note (capabilities) and optional expiry, revoke with a reason; active, expiring (30 days),
expired and revoked grants with their reason and note; `aal1` attempts refused in the UI and in SQL.
- C8 Catalogue (P1, boards 01 to 03, complementary page): `/app/anatomy` published sheets by species, search by
sheet name only, species filter; `/:sheetId` current version (views, zones, findings, references, disclaimer,
earlier versions); `/:sheetId/versions/:number`; loaded through `get_sheet_version` and `PreviewSheet`
(hash, fingerprint, caps checked by the core); whole drawing at opening on a phone, zoom and pan after;
drafts never listed; archived sheets absent from the list and readable by id; Supabase or core unavailable
→ the unavailable notice.
- C9 M7 `sheet_admin_reads`: read RPCs only, capability holders at `aal2` (`caller_can_see_official_sheet`),
one answer for unknown and forbidden ids; no write path, grant widening, policy or rule change; pgTAP allowed
and denied cases (anonymous, reader, admin without capability, capability at `aal1`); types regenerated; a
fresh install and an upgrade from the M6 state on the sandbox.
- C10 Labels: ratified wordings used verbatim (V1-2 contract §3 with BDR-097, REVUE.md tables); every new
FR/EN string goes through i18n and is listed at the checkpoint as a proposal; every failure kind the screens
meet has an FR and an EN message.
- C11 Tests and gates: unit; `e2e:shell` A0, A1, S1, P1, access per right, MFA required, refresh keeps `aal2`,
no `aal1` enrolment of a second factor, axe, 320 to 430 px for the catalogue, 375 px for admin screens, FR
and EN; `pnpm check:all`; fresh verifier against this contract; fresh security audit. Nothing reported as
passed that did not run.
- C12 Docs: IDENTITY.md (MFA screens, step-up, recorded GoTrue behaviour), V1-2 contract state, CLAUDE.md
folder map, design README owning steps, TODO, memory.
## Out of scope
The editor (V1-2.6), the review and publication screens (V1-2.7), deprecation and archive actions (V1-2.7),
the equine working copy content work (V1-2.8), any DEV operation (§16.11), recovery runbook rehearsal (V1-2.9).
+19
View File
@@ -0,0 +1,19 @@
# Plan: V1-2.5 administration space, rights, species, MFA, catalogue
Contract `.claude/tasks/contracts/2026-11-02-v1-2-5-admin-catalogue.md` (C1 to C12). Branch
`feature/v1-2-anatomical-sheets`, sandbox only. One slice = one coherent change, committed and pushed when its
own checks pass. Slices A, B and C have no dependency on each other; D needs B and C; E to I need D.
| Slice | Content | Criteria | Checks |
|---|---|---|---|
| A | GoTrue MFA behaviour on the sandbox: `packages/supabase/tests/sandbox/mfa-behaviour.sandbox.ts` with the existing `mfa.ts` / `totp.ts`; findings written into IDENTITY.md. STOP for the owner if `aal1` enrols a second factor or removes a verified one | C1 | sandbox suite |
| B | M7 `supabase/migrations/20261102100000_sheet_admin_reads.sql`: `list_official_sheets_admin()`, `get_official_sheet_admin(sheet_id)`; pgTAP `022`; types; sandbox fresh + upgrade from M6 | C9 | PGlite, `db:sandbox test-db`, `db:types --check` |
| C | Core op `sheet.empty` (wraps `create_empty_sheet_document`: species, names, slug), wasm facade, ts-rs types | C5 | `rust:check`, `wasm:build`, core-wasm proofs |
| D | `packages/supabase`: MFA wrappers (list, enrol, challenge and verify, unenrol, assurance level), species, working copy, account lookup, M7 reads, catalogue reads (versions of a sheet, drawing download), closed failure kinds; unit tests | C1-C9 | `test:run`, typecheck, lint |
| E | Shell: nav entries and their hints (own grants + roles), guards `RequireCatalog` and `RequireAdmin` (step-up), « Accès non autorisé » page, routes | C3, C4 | unit, e2e |
| F | Mon compte, Sécurité: factor list, enrolment (QR, secret once), verification, naming, removal; step-up screen | C2 | unit, e2e |
| G | Administration page (board 10), species screens, rights screen | C4, C6, C7 | unit, e2e |
| H | Sheets list with filters, creation (inline species), overview, working copy action | C5 | unit, e2e |
| I | Catalogue list (board 01), sheet page (board 02, 03), version page; `PreviewSheet` load path, canvas with zoom and pan | C8 | unit, e2e |
| J | `e2e:shell` journeys A0, A1, S1, P1, access per right, MFA, refresh, axe, viewports, FR/EN | C11 | `pnpm e2e:shell` |
| K | Docs, `check:all`, fresh verifier + security, memory, checkpoint report with the label proposals | C10-C12 | all gates |
+22 -3
View File
@@ -136,7 +136,7 @@ sources.
| Vérification en cours, à relire, approuvée, modifications demandées, soumission retirée, vérification échouée | Verifying, awaiting review, approved, changes requested, submission withdrawn, verification failed | round status `verifying`, `open`, `approved`, `changes_requested`, `withdrawn`, `verification_failed` |
| Groupe de revue, groupe lu | Review group, group read | review group, acknowledgment (§6.3) |
| Accès au catalogue | Catalogue access | right `catalog_reader` (§5.3) |
| Habilitation | Capability | right `sheet_editor`, `sheet_reviewer`, `sheet_publisher` (§5.2) |
| Habilitation | Permission (owner, 2026-11-02, BDR-097: `capability` stays the technical term) | right `sheet_editor`, `sheet_reviewer`, `sheet_publisher` (§5.2) |
| Relecteur, relectrice | Reviewer | `sheet_reviewer` |
| Éditeur de fiches | Sheet editor | `sheet_editor` |
| Responsable de publication | Publisher | `sheet_publisher` |
@@ -1751,6 +1751,7 @@ of the document's JSON text in one form, the same for every layer:
| M4 `sheet_access_hardening` | V1-2.1 | `anatomical_catalog_grants` and its RPCs; `has_mfa`, `grant_active`, `caller_has`; `can_read_official_catalog` and the reader row predicate; `can_edit_sheet` redefined (F14); AR-1 B on the platform role RPCs and the private write functions (F19, §5.7), F17, F18; F1, F2, F3 (fork closed), F5, F6, F8, F9, F12 (every catalogue table), F13, F15; asset-row immutability trigger (F16); historical-sheet protection trigger (§14.2); reader column grants narrowed; personal creation and visibility changes refused | no row changes |
| M5 `sheet_review_workflow` | V1-2.1 | version columns `revision`, `authors`, `source_version_id`, `published_review_id`, `document_fingerprint`; sheet column `working_copy_source_version_id`; revision, author and freeze triggers, the historical-sheet write rule; extended immutability guard (§6.8); rounds, comments, acknowledgments; `create_official_sheet`, `create_sheet_draft` adapted, `save_sheet_draft`, submit, withdraw, comment, acknowledge, decide, publish; `create_sheet_working_copy`; species RPCs; catalogue and version read RPCs; upload: `register_sheet_asset` extended, `confirm_sheet_asset_upload` with the storage check (F7), INSERT policy, bucket limit 2 MiB; mirror removal and status check (§12.2); superseded signatures dropped; the content-size CHECK replaced by the text measure (`octet_length(content::text)`, §12.2) | new columns take their defaults on the equine v1 row (`revision` 0, empty author set); its document, status, number and assets unchanged; the new size CHECK is validated against the existing rows when M5 is applied (the equine document measures 184 105 bytes as `content::text`, measured on the sandbox); bucket limit lowered; no round, no grant |
| M6 `sheet_verification_jobs` | V1-2.3 | worker RPCs (claim, input, complete with the verdict structure check, fail), service role only, with the retry delay (hidden `not_before` column on the round, `private.sheet_verification_retry_delay`: owner decision 2026-11-01, replaces « without backoff ») and the retry by cause (definitive codes close at the first occurrence, `private.sheet_worker_final_codes`); written as `20261101100000_sheet_verification_jobs.sql`, pgTAP `021`, rehearsed on the sandbox from the state before M4 (M4 to M6 in one `migration up`) and from the state before M6 | none |
| M7 `sheet_admin_reads` | V1-2.5 | read RPCs of the admin space (owner decision 2026-11-02, BDR-097): the official sheet list with its badges (historical, working copy), statuses and round counts, and one sheet's overview (versions, rounds); capability holders at `aal2` only (`caller_can_see_official_sheet`); no write path, no grant, no policy or rule change; pgTAP allowed and denied cases | none |
Each migration ships its pgTAP file (allowed and denied cases), regenerated
`database.types.ts`, a `db:sandbox up upgrade` run from the DEV state (with a
@@ -2179,6 +2180,8 @@ V1-2.7 on.
`profile_roles`.
- Rollback: branch revert; sandbox rebuilt.
- Checkpoint: gates only (owner at V1-2.3).
- State 2026-10-29: VERIFIED by the owner at `ac71c5b` (brief « Autorisation de
démarrer V1-2.2 »); M4 and M5 unchanged since.
### 16.3 V1-2.2 Core: verdict, preview handle, edit primitives, SVG cleaning
@@ -2251,8 +2254,12 @@ V1-2.7 on.
- Security prerequisites: server rules of V1-2.1 in place; the UI is never
the boundary.
- Application changes: routes and screens of §11.1 except the editor and the
review screen; Mon compte, Sécurité; the TOTP test helper (from V1-2.1). SQL changes:
none. Scope split: M4 (V1-2.1) holds every server control of AR-1 B; this
review screen; Mon compte, Sécurité; the TOTP test helper (from V1-2.1).
« Créer une copie de travail » on the Administration page and the
historical sheet's overview (W1 start, owner decision 2026-11-02, BDR-097):
the copy lands on its overview, the editor link arrives with V1-2.6; a new
sheet (A1) also lands on its overview until V1-2.6. SQL changes: M7 admin
reads only (§12.3, owner decision 2026-11-02, BDR-097; was « none »). Scope split: M4 (V1-2.1) holds every server control of AR-1 B; this
step holds the frontend journey only (enrolment, step-up, factor list, the
`mfa_required` message in FR and EN).
- Tests: unit; `e2e:shell` A0, A1, S1, P1; access per right; MFA required;
@@ -2557,6 +2564,18 @@ its `REVUE.md`). **V1-2.4 GRAPHICAL APPROVED.** This record changes no board, no
| Minor documentary remarks | fixed without a new graphic review, provided the boards are not modified | `REVUE.md` |
| Next step | V1-2.5 authorised once the steps it depends on (§16.6) are VERIFIED, within this contract | §16.6 |
### 17.10 V1-2.5 start (owner, 2026-11-02)
Prerequisites of §16.6 checked on `994b04e`: V1-2.1 VERIFIED at `ac71c5b` (M4 and M5 unchanged since), V1-2.2
VERIFIED (BDR-092), V1-2.4 approved (§17.9); V1-2.3 VERIFIED as well (BDR-093). V1-2.5 started under the brief
« Validation propriétaire V1-2.4 ». Owner answers to the questions raised at the start (BDR-097):
| Item | Decision | Where |
|---|---|---|
| Admin reads | the admin list needs the working-copy badge and round counts, which no table grant gives (§5.3) and no RPC returned: one read migration M7, capability holders at `aal2`, no write path | §12.3, §16.6 |
| Working copy action | « Créer une copie de travail » built in V1-2.5 (board 10), landing on the copy's overview; the editor link arrives with V1-2.6 | §11.1, §16.6 |
| EN term | « Habilitation » reads « Permission » in the English interface; `capability` stays the technical term | §3 |
---
## 18. Documents touched by V1-2.0