docs(supabase): V1-2.5 checkpoint decisions, TOTP reuse measured, lost-factor review

IDENTITY 4.1 asserted reuse span (step N and N+1), 4.2 lost authenticator paths and gaps, production prerequisite; V1-2 contract 12.3, 13, 17.10, 17.11; design README accepted deviations; REVUE L15 and object_conflict EN; M7 header.
This commit is contained in:
bchanot committed 2026-11-02 22:57:22 +01:00
1 parent 0499a39389
commit dcb1a94ee4
9 files changed
+161 -16

No files matched your search

+36 -3
View File
@@ -121,7 +121,7 @@ right (`V1-2_ANATOMICAL_SHEETS.md` §5.6, §5.7). State since V1-2.5:
(§4.1).
Still open: the recovery runbook for a lost factor (V1-2 contract §5.7.7) is
rehearsed at V1-2.9.
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)
@@ -156,8 +156,41 @@ rehearsed at V1-2.9.
- 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).
- 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 once by another password-holding
session 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)
+51 -2
View File
@@ -1756,7 +1756,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); `get_sheet_version` redefined to return the fingerprint of deprecated versions too (BDR-098); the admin reads for 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 |
| 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); `get_sheet_version` redefined to return the fingerprint of deprecated versions too (BDR-098); the admin reads for capability holders at `aal2` only (`caller_can_see_official_sheet`); no write path, no new grant, no policy change; the one rule change is the species sort order: `create_species` and `update_inactive_species` are redefined to refuse an order outside 0..9 999 with `invalid_input` (null keeps today's meaning, owner 2026-11-02), `security definer`, `search_path = ''` and their privileges restated; 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
@@ -1827,6 +1827,13 @@ Residual risks:
not detectable (§5.5);
- a stolen `aal2` session stays usable until it ends, since no freshness
window or session limit is set (§5.6);
- TOTP code reuse within its window (measured, `IDENTITY.md` §4.1): GoTrue
accepts a used code again, from the same or another session of the account,
in its own 30 s step and the next, and refuses it from the step after; no
mitigation is added, the span is 30 to 60 s;
- production prerequisite: the lost-factor recovery is not rehearsed and no
recovery code exists (`IDENTITY.md` §4.2); the runbook of §5.7.7 is rehearsed
on the sandbox and written before any production use of MFA-protected rights;
- a capability holder can still ask Storage for a signed URL to a draft
drawing through the API; such a URL outlives a later revocation until it
expires;
@@ -2570,7 +2577,7 @@ its `REVUE.md`). **V1-2.4 GRAPHICAL APPROVED.** This record changes no board, no
| Item | Decision | Where |
|---|---|---|
| Approval | the twelve boards `01` to `12` and the complementary page « Accès non autorisé » are approved; they are the design reference of V1-2.5 to V1-2.7 (§11.3); a redesign needs a demonstrated defect or a new owner decision | `docs/design/README.md`, `docs/design/v1-2-4/` |
| `object_conflict` | FR « Le contenu du fichier de l'illustration ne correspond pas à son empreinte SHA-256 enregistrée. »; EN checked at integration with the other messages; board 12 keeps the earlier proposal | §9.3, board 12 |
| `object_conflict` | FR « Le contenu du fichier de l'illustration ne correspond pas à son empreinte SHA-256 enregistrée. »; EN ratified 2026-11-02 (§17.11); board 12 keeps the earlier proposal | §9.3, board 12 |
| L14 | « Access and permissions » in the interface; `capability` stays a technical term | board 10 |
| L20 | « Corriger le brouillon » / « Fix the draft » (content failure); « Modifier le brouillon » / « Edit the draft » (size limit) | board 06 |
| L32 | « Accès non autorisé » / « Access denied », with the explanation and the « Retour au tableau de bord » / « Back to dashboard » link already decided (wordings of board 12) | complementary page, §5.3 |
@@ -2591,6 +2598,48 @@ VERIFIED (BDR-092), V1-2.4 approved (§17.9); V1-2.3 VERIFIED as well (BDR-093).
| 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 |
| Deprecated fingerprint | found while building the catalogue: `PreviewSheet` checks the fingerprint of published and deprecated versions, `get_sheet_version` returned it for published only, so no withdrawn version could open; `get_sheet_version` now returns it for both (redefined in M7, BDR-098) | §10, §12.3 |
| Species RPCs | M7 also redefines `create_species` and `update_inactive_species` with the 0..9 999 order range (§17.11), privileges restated; M5 and earlier migrations untouched (forward-only) | §12.3 |
### 17.11 V1-2.5 checkpoint decisions (owner, 2026-11-02)
The owner accepted the technical results of V1-2.5 at `14ff890` and ratified the following; corrections built
in V1-2.5 lots 1 to 3.
**Permission states.** Three situations are told apart, never one deduced from a technical error. On
`/app/admin/sheets/new` the order is: own grants `loading` (waiting status); the server refused (the species
read answered a `rights.*` kind): « Accès non autorisé » (BDR-094), the server's refusal wins over a failed
client read; own grants `failed`: « Impossible de vérifier vos autorisations », a short explanation and
« Réessayer », never the form; `ready` with an active `sheet_editor` grant: the form; `ready` without it
(reviewer-only, publisher-only, owner without the capability): « Accès non autorisé ». Retry re-reads the
platform roles and the own grants (and the species list when it failed) and keeps the profile, roles and
workspace already held when it fails again. The Administration home replaces its « Vos habilitations » line
with the same notice and Retry while the read failed (waiting status while loading, never « aucune »). The
sheet and species lists keep their grant-dependent actions hidden on a failed read, without a notice. Server
checks and RLS stay mandatory.
**Accepted UX deviations** (the historical boards are unchanged, no graphic redesign; `docs/design/README.md`):
the selection is shown in the zone panel instead of a tag over the drawing, on condition that it stays
identifiable and accessible (an `aria-live` region mounted before any pick, naming the picked zone); the
« Références » card is not collapsible on a phone, on condition that it does not hide the anatomical area
(it starts at or below the drawing's bottom, measured at 320 and 375 px).
**Ratified choices.** MFA factor name: 64 characters at most. TOTP setup key: no Copy button, displayed readable
and selectable while enrolment is open. Capability expiry: valid until the end of the chosen day in
Europe/Paris (the instant stored is 23:59:59.999 of that day with the offset in force then, DST-aware; the
date picker and the display use Paris dates; the backend compares instants, `expires_at > now()`; historical
rows untouched). Species order: an integer from 0 to 9 999, checked server-side (M7). Terminology:
« relecteur ou relectrice ».
**Labels.** L14: « Access and permissions » in the interface, `capability` stays technical. L15: the title
alone, the redundant second sentence is dropped (for V1-2.6). `object_conflict` (EN): « The illustration
file's contents do not match its recorded SHA-256 hash. ». The roughly 350 new labels of V1-2.5 are NOT
approved: they get a separate owner review (`.claude/audits/2026-11-02-v1-2-5-label-proposals.md`). The
wordings ratified in V1-2.4 are kept.
**MFA.** TOTP code reuse is recorded as measured (`IDENTITY.md` §4.1, §13). The lost-authenticator paths are
reviewed in `IDENTITY.md` §4.2; no safe, rehearsed recovery exists yet, which is a production prerequisite
(§13). No MFA bypass, no `aal2` weakening, no new path that resets a factor.
---