docs(supabase): db:trial operating guide

This commit is contained in:
bchanot committed 2026-11-10 22:59:29 +01:00
1 parent 3b687a218e
commit f7bf0c85cb
5 files changed
+144 -10

No files matched your search

+1 -1
View File
@@ -694,7 +694,7 @@ Order (BDR-071): P0 docs + decisions → V1-1 clients and animals → V1-2 sheet
- [ ] Test anomaly A (owner 2026-11-09, separate from U1/U2): fictitious fingerprints `'a'.repeat(64)` from worker stand-ins (`packages/supabase/tests/sandbox/sheet-fixtures.ts:115` openRound, `sheets-concurrency.sandbox.ts:168`, `sheets-perf.sandbox.ts:169`); 7 published/deprecated sandbox versions fail `check_published`. Fix: real fingerprint through the core (as e2e `fingerprintOf`, `apps/app/e2e/support/catalogue.ts:88`); never weaken the publish gate or the reader check. Needs its own go. - [ ] Test anomaly A (owner 2026-11-09, separate from U1/U2): fictitious fingerprints `'a'.repeat(64)` from worker stand-ins (`packages/supabase/tests/sandbox/sheet-fixtures.ts:115` openRound, `sheets-concurrency.sandbox.ts:168`, `sheets-perf.sandbox.ts:169`); 7 published/deprecated sandbox versions fail `check_published`. Fix: real fingerprint through the core (as e2e `fingerprintOf`, `apps/app/e2e/support/catalogue.ts:88`); never weaken the publish gate or the reader check. Needs its own go.
- [ ] Test anomaly B (owner 2026-11-09, separate from U1/U2): `packages/supabase/tests/sandbox/sheets-admin.sandbox.ts:181-195` creates the historical working copy and never archives it; slot taken → `admin.spec.ts:717` fails x4. Fix test independence and cleanup; the existing copy `8c315a12-20d4-4432-9db3-7cb88b27a5b4` stays untouched until the owner authorises. Linked: RR-13, the admin.spec confirmation line above. - [ ] Test anomaly B (owner 2026-11-09, separate from U1/U2): `packages/supabase/tests/sandbox/sheets-admin.sandbox.ts:181-195` creates the historical working copy and never archives it; slot taken → `admin.spec.ts:717` fails x4. Fix test independence and cleanup; the existing copy `8c315a12-20d4-4432-9db3-7cb88b27a5b4` stays untouched until the owner authorises. Linked: RR-13, the admin.spec confirmation line above.
- [ ] Test anomaly C (owner 2026-11-09, separate from U1/U2): integrity failure invisible in catalogue cards; implemented as lot R4; failure shown, never hidden or bypassed. - [ ] Test anomaly C (owner 2026-11-09, separate from U1/U2): integrity failure invisible in catalogue cards; implemented as lot R4; failure shown, never hidden or bypassed.
- [ ] Dedicated persistent manual trial stack (owner 2026-11-09, D8): plan `docs/development/TRIAL_STACK.md` (prefix `faunosteo_trial_`, ports 58xxx + 5194, named volumes, own secrets 1-year keys, equine seed only + `pnpm assets:upload`, suite guard in `stack.ts`, memory caps); nothing created; needs arbitrations A11-A15 and its own go. - [ ] Dedicated persistent manual trial stack (owner 2026-11-09, D8; brief « Après R0 — Implémentation technique », contract .claude/tasks/contracts/2026-11-09-db-trial-stack-1809.md): [x] lot A suites' guard · [x] lot A2 trial dev server target (R13) · [x] lot B1 foundation · [x] lot B2 backups, restore, migrate, rotation · [x] lot B3 accounts, grants, drawings, app · [x] lot C docs · [ ] reviews · [ ] creation checkpoint (owner go before any create)
- [ ] Rights screen lists every catalogue grant unbounded (list_catalog_grants, GrantList): 2 306 rows crash axe at 8 workers on a long-lived sandbox. Owner 2026-11-09 (BDR-106): own priority track RR-13, separate from U1 and U2, not implemented now. - [ ] Rights screen lists every catalogue grant unbounded (list_catalog_grants, GrantList): 2 306 rows crash axe at 8 workers on a long-lived sandbox. Owner 2026-11-09 (BDR-106): own priority track RR-13, separate from U1 and U2, not implemented now.
- [ ] V1-2.6 UX complement « annotations ↔ constats » (owner brief 2026-11-06 « Nouvelle exigence UX : navigation bidirectionnelle »; contract `.claude/tasks/contracts/2026-11-06-v1-2-6-findings-nav-design.md`; design only, U1 plan untouched, no code, no DEV): [x] relations audit (one link `finding_zone_id`, no new association, equine draft 1:1) · [x] boards 17-22 `docs/design/v1-2-6-constats/` · [x] study `docs/development/V1-2-6_UX_FINDINGS_NAV.md` (no U1 integration point needed, sub-step U2b proposed, risks, tests, decisions F1-F21) · [x] fresh design review APPROVE WITH FIXES (3 MUST-FIX, 16 SHOULD), fixes applied · [x] fresh verifier ECARTS(4) → ECARTS(2) → CONFORME 9/9 (round 3; 567da67 came after it, not covered) · [x] owner principle validation 2026-11-06 (brief « Validation de principe U2b et préparation des checkpoints », BDR-103): U2b retained after U2 and before U3, F1/F2/F6/F8/F22 approved, F7 for the term « Famille », F3/F4 in part · [x] decisions F1-F22 table (alternatives, consequences, state), F2 groups vs leaves, F3 field list, F4 view semantics, boards with their decisions in study §7.4, U2b entry in `V1-2-6_UX_PLAN.md` §3, LRN-119 (`<Activity>`), contract `.claude/tasks/contracts/2026-11-06-v1-2-6-findings-nav-decisions.md` · [x] fresh verifier on that contract: ECARTS(9) → fixed → CONFORME 11/11 (6 observations outside criteria kept for the owner) · [x] owner 2026-11-06 (brief « U1 / U2b — Derniers arbitrages avant implémentation », BDR-104): F2 leaves, F3, F4 model A, F8, F22 decided; study §6-§7 updated · [x] owner: F5, F9-F21 approved as recommended, precisions F3, F8, F11-F14, F22 (brief « Ratification finale U1 … », 2026-11-06, BDR-105); study header, §6 tests, §7 table, 7.2, 7.3, UX PLAN U2b entry, REVUE, DECISIONS pointer updated; no implementation · [ ] U2b authorisation (after U2, before U3) - [ ] V1-2.6 UX complement « annotations ↔ constats » (owner brief 2026-11-06 « Nouvelle exigence UX : navigation bidirectionnelle »; contract `.claude/tasks/contracts/2026-11-06-v1-2-6-findings-nav-design.md`; design only, U1 plan untouched, no code, no DEV): [x] relations audit (one link `finding_zone_id`, no new association, equine draft 1:1) · [x] boards 17-22 `docs/design/v1-2-6-constats/` · [x] study `docs/development/V1-2-6_UX_FINDINGS_NAV.md` (no U1 integration point needed, sub-step U2b proposed, risks, tests, decisions F1-F21) · [x] fresh design review APPROVE WITH FIXES (3 MUST-FIX, 16 SHOULD), fixes applied · [x] fresh verifier ECARTS(4) → ECARTS(2) → CONFORME 9/9 (round 3; 567da67 came after it, not covered) · [x] owner principle validation 2026-11-06 (brief « Validation de principe U2b et préparation des checkpoints », BDR-103): U2b retained after U2 and before U3, F1/F2/F6/F8/F22 approved, F7 for the term « Famille », F3/F4 in part · [x] decisions F1-F22 table (alternatives, consequences, state), F2 groups vs leaves, F3 field list, F4 view semantics, boards with their decisions in study §7.4, U2b entry in `V1-2-6_UX_PLAN.md` §3, LRN-119 (`<Activity>`), contract `.claude/tasks/contracts/2026-11-06-v1-2-6-findings-nav-decisions.md` · [x] fresh verifier on that contract: ECARTS(9) → fixed → CONFORME 11/11 (6 observations outside criteria kept for the owner) · [x] owner 2026-11-06 (brief « U1 / U2b — Derniers arbitrages avant implémentation », BDR-104): F2 leaves, F3, F4 model A, F8, F22 decided; study §6-§7 updated · [x] owner: F5, F9-F21 approved as recommended, precisions F3, F8, F11-F14, F22 (brief « Ratification finale U1 … », 2026-11-06, BDR-105); study header, §6 tests, §7 table, 7.2, 7.3, UX PLAN U2b entry, REVUE, DECISIONS pointer updated; no implementation · [ ] U2b authorisation (after U2, before U3)
- [ ] follow-up candidates (owner T14): multi-tab notice; RR item for the rollback limit of the category model (new id, reconcile with develop) - [ ] follow-up candidates (owner T14): multi-tab notice; RR item for the rollback limit of the category model (new id, reconcile with develop)
+3
View File
@@ -134,6 +134,8 @@ pnpm db:test # pgTAP on the real stack
pnpm db:types # regenerate packages/supabase/src/database.types.ts pnpm db:types # regenerate packages/supabase/src/database.types.ts
pnpm db:types:check # CI diff pnpm db:types:check # CI diff
pnpm db:sandbox up fresh|up upgrade <version> [<then>]|test-db|types [--check]|test|e2e-shell|verify-e2e|avatar-e2e|down # throwaway stack (SUPABASE.md §5.1): migrations tested without touching DEV pnpm db:sandbox up fresh|up upgrade <version> [<then>]|test-db|types [--check]|test|e2e-shell|verify-e2e|avatar-e2e|down # throwaway stack (SUPABASE.md §5.1): migrations tested without touching DEV
pnpm db:trial plan|create|start|stop|status|migrate|backup|restore <b>|rotate-keys|rotate-secrets|app|account <email>|grant <email> <right>|assets|destroy # dedicated persistent manual trial stack (SUPABASE.md §5.2): faunosteo_trial_*, 127.0.0.1:58xxx, app :5194, own secrets and volumes; created only on the owner's go; never a test target
bash scripts/db-trial-check.sh # environment-free checks of db:trial and the db:sandbox state guard (stubs, no Docker daemon); run by hand, refuses (exit 2) while the trial stack or app holds a port
# Reference sheet in the app: the dev server bundles the curated draft; a build does not # Reference sheet in the app: the dev server bundles the curated draft; a build does not
pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview deployments) pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview deployments)
@@ -302,6 +304,7 @@ faunosteo/
│ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check; V1-2.3 `verify` sandboxed child (framed input → the core's `compute_verdict`) and `run --jobs sheet-verify` (verify_job, VerifyBackend: M6 RPCs + drawing downloads); R1 `run` loop: config, log (JSON lines, allowlist), keys, backend trait + http (ureq, PostgREST rpc + Storage objects), job, sweep, watchdog; Dockerfile, scripts/derive-seccomp.sh │ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check; V1-2.3 `verify` sandboxed child (framed input → the core's `compute_verdict`) and `run --jobs sheet-verify` (verify_job, VerifyBackend: M6 RPCs + drawing downloads); R1 `run` loop: config, log (JSON lines, allowlist), keys, backend trait + http (ureq, PostgREST rpc + Storage objects), job, sweep, watchdog; Dockerfile, scripts/derive-seccomp.sh
├─ scripts/{rust-env,rust-check,wasm-build,check-all,report-compare,import-equine,upload-sheet-assets,sheet-assets-e2e,floor-clarification-check}.sh, wasm-stamp.mjs ← native Rust gate, wasm build (pkg + pkg-proofs + stamp), the pre-merge gate (`pnpm check:all`), the archive check tool (`pnpm report:compare`), the Rust pipeline (`pnpm r5:import-equine`) ├─ scripts/{rust-env,rust-check,wasm-build,check-all,report-compare,import-equine,upload-sheet-assets,sheet-assets-e2e,floor-clarification-check}.sh, wasm-stamp.mjs ← native Rust gate, wasm build (pkg + pkg-proofs + stamp), the pre-merge gate (`pnpm check:all`), the archive check tool (`pnpm report:compare`), the Rust pipeline (`pnpm r5:import-equine`)
├─ scripts/{dev-env,supabase,dev}.sh ← the DEV origin (LAN address) in one place; CLI wrapper; `pnpm dev` on that origin ├─ scripts/{dev-env,supabase,dev}.sh ← the DEV origin (LAN address) in one place; CLI wrapper; `pnpm dev` on that origin
├─ scripts/{db-sandbox,db-trial,db-trial-check}.sh ← throwaway sandbox (suites), persistent trial stack (manual), its stub checks
├─ docker-compose.yml ← `app` service; `worker` and `worker-verify` (V1-2.3, `run --jobs sheet-verify`) services under the `worker` profile (read-only, cap_drop ALL, external Supabase network, `.env.worker`) ├─ docker-compose.yml ← `app` service; `worker` and `worker-verify` (V1-2.3, `run --jobs sheet-verify`) services under the `worker` profile (read-only, cap_drop ALL, external Supabase network, `.env.worker`)
├─ docker/rust-builder.Dockerfile, rust-run.sh, csp-proof/ ← reproducible Rust builder (alternative) + the CSP proofs (R0 module, R2 app image: app-image.sh) ├─ docker/rust-builder.Dockerfile, rust-run.sh, csp-proof/ ← reproducible Rust builder (alternative) + the CSP proofs (R0 module, R2 app image: app-image.sh)
├─ .gitea/workflows/ci.yml ← PREPARED, never executed (no runner): rust job (builder image, scripts/rust-check.sh, types drift, wasm), install, typecheck, test, lint, build, docker (app + worker test stage + runtime) ├─ .gitea/workflows/ci.yml ← PREPARED, never executed (no runner): rust job (builder image, scripts/rust-check.sh, types drift, wasm), install, typecheck, test, lint, build, docker (app + worker test stage + runtime)
+105
View File
@@ -821,6 +821,111 @@ set local role authenticated;
select set_config('request.jwt.claims', '{"sub":"<user uuid>","role":"authenticated"}', true); select set_config('request.jwt.claims', '{"sub":"<user uuid>","role":"authenticated"}', true);
``` ```
### 5.2 Dedicated trial stack (`pnpm db:trial`)
A persistent stack for the owner's manual trials, apart from DEV and from the sandbox, which the
automated suites keep using (`docs/development/TRIAL_STACK.md`, arbitrations A11 to A15). The script
`scripts/db-trial.sh` and its checks exist; the stack is created only on the owner's go, one operation
at a time, and never by a test.
| Container | Image | Port (127.0.0.1 only) | Data | Caps |
|---|---|---|---|---|
| `faunosteo_trial_db` | `supabase/postgres:17.11.0.004` | 58432 | volume `faunosteo_trial_db` (`PGDATA`) | 1 GiB, `shared_buffers` 128 MB, 512 pids |
| `faunosteo_trial_auth` | `supabase/gotrue:v2.197.0` | 58999 | | 128 MiB, 256 pids |
| `faunosteo_trial_rest` | `supabase/postgrest:v16.4` | 58300 | | 384 MiB, 256 pids |
| `faunosteo_trial_storage` | `supabase/storage-api:v1.79.36` | 58500 | volume `faunosteo_trial_storage` (`/mnt`) | 256 MiB, 256 pids |
| `faunosteo_trial_mail` | `supabase/mailpit:v1.31.3` | 58025 | | 64 MiB, 64 pids |
| `faunosteo_trial_gateway` | `nginx:1.31-alpine` | 58801 | | 64 MiB, 64 pids |
Every container: network `faunosteo_trial_net`, `--cpus 1`, restart policy `no`. The app (`pnpm db:trial app`)
runs Vite on `http://<trial host>:5194` with a 768 MiB Node heap; the trial host is the LAN address by default,
`FAUNOSTEO_TRIAL_HOST=127.0.0.1` for host-only, decided again at each run (nothing to edit after a change of the LAN
address). GoTrue's mail links carry the host of the moment GoTrue was started (`create`, `restore`,
`rotate-secrets`). GoTrue's sign-up is closed and the gateway answers 403 on `/auth/v1/admin/`.
State: `~/.cache/faunosteo-trial` (or `FAUNOSTEO_TRIAL_DIR`), 700, refused inside any git work tree:
`secrets.env` and the services' env files (600, written whole then renamed), `stack.conf` (images),
`migrations.sha256` (applied files and their hashes), `backups/`. Keys are signed for the issuer `faunosteo-trial`
and valid one year. Never run a bare `docker inspect` on a trial container: it prints the env-file values (database
password, JWT secret, keys); use `docker inspect -f` with a named non-secret field. Every command but `plan` needs a
reachable Docker daemon. `account`, `grant`, `restore` and `destroy` need a terminal: on a piped stdin they refuse
before any Docker call. Their typed confirmations: `destroy` asks `faunosteo_trial`, `restore <backup>` asks
`restore <backup>`, `grant <email> <right>` asks `grant <right>` for every right, catalogue rights included.
| Command | What it does |
|---|---|
| `plan` | read-only: the exact resources, each port free or taken, volume and backup places, memory, the refusals `create` would meet |
| `create` | after the Rust pipeline check of the equine seed (`pnpm r5:import-equine --check`): secrets, network, volumes, services, the branch's migrations, then `equine_draft.sql` only (never `seed.sql`); checks that the historical sheet is the only official one and that its draft equals `document.json` |
| `start` / `stop` | the same containers, data kept; `start` recreates a missing service container from `stack.conf` and `secrets.env` |
| `status` | containers, keys' expiry, migrations, equine sheet, accounts with roles, rights and verified factors, backups |
| `migrate` | a cold backup, then the branch's new migrations; refuses an applied file edited since, or a new file older than the last applied; a migrate that stops part-way names its backup |
| `backup` | stops the stack a few seconds, refuses when free space is below 110 % of the volumes, archives each volume read-only through a `--rm` helper with no network, then lists it back and compares its entry count with the volume's (an archive cut short is refused), copies the state files, writes checksums last, restarts; a failed backup keeps no folder (a folder without `SHA256SUMS` is listed as incomplete) |
| `restore <backup>` | checksums, archives and the recorded database image checked first, typed confirmation `restore <backup>`, a backup of the current volumes, then the backup's volumes and secrets and the containers recreated; also rebuilds a destroyed stack |
| `rotate-keys` | a backup, then new anon and service keys signed with the same secret (one more year), Storage recreated and the gateway restarted; works on a stopped stack too (Storage is then recreated by the next `start`); the previous keys stay valid until their own expiry. Expired keys never block `start` or `rotate-keys`; `app`, `assets` and `account` refuse them and name `rotate-keys`; `status` reports them |
| `rotate-secrets` | a backup, then a new JWT secret, keys and role passwords set in one transaction as `supabase_admin` (values through psql variables, statement and error-statement logging off, a digest marker proving the commit); the new values wait in `secrets.next.env` (600) until the commit is known; every container recreated; sessions signed with the old secret end, account passwords and TOTP factors stay |
| `account <email>` | a confirmed account through GoTrue's admin API on 58999, password typed twice at a hidden prompt (12 characters min.); the address is lowercased |
| `grant <email> <right>` | `owner` / `admin`: the operator path of the V1-2 contract §5.7.1 (verified TOTP factors shown, two for owner, one for admin; typed confirmation `grant <right>`; `private.assign_platform_role(null, …)` and an audit row); a platform role already active is refused. Catalogue rights mirror `public.grant_catalog_right` in operator SQL (the RPC needs an owner session at aal2): a confirmed active account; a verified TOTP factor for every right but `catalog_reader`; `admin` held first for `sheet_editor` and `sheet_publisher` (the refusal names `pnpm db:trial grant <email> admin`); one active row per right; typed confirmation; the insert and an audit row `catalog_grant.operator_bootstrap` in one transaction; no platform role is granted implicitly. `granted_by` is the holder's own id (the column is NOT NULL and the operator has no profile), so the rights screen shows a self-grant; the audit row names the operator. A catalogue right already active exits 0 with nothing written |
| `assets` | the equine drawings with `pnpm assets:upload` through the gateway (no overwrite, rerun = nothing to do), then every row confirmed with its object |
| `app` | the app, foreground; Ctrl+C stops Vite and waits for it, so 5194 is free on return; the stack keeps running |
| `destroy` | inventory, typed confirmation `faunosteo_trial`, a backup of every trial volume checked as a restorable backup, then the containers, the network, the volumes and the live state files; backups kept. When that backup cannot be made or fails the check, it removes nothing and names the backup kept (or none), the exact `docker rm`, `docker network rm` and `docker volume rm` lines for what exists, then `pnpm db:trial destroy` to clear the state files; the script never runs those lines. With no trial resource left, it removes the live state files only |
First use, after the owner's go: `plan`, `create`, `assets`, then the two accounts.
1. Owner/admin account, for the administration trials: `account <email>`, `app`, sign in, enrol two TOTP
factors in Mon compte > Sécurité, then `grant <email> owner`, `grant <email> admin`, then `grant <email>
sheet_editor`, `sheet_reviewer` and `sheet_publisher`; sign in again and pass the step-up.
2. Practitioner account: `account <email>`, `app`, enrol one TOTP factor, `grant <email> admin`, then `grant <email>
sheet_editor` (refused before `admin`). This is a trial account, not a production practitioner profile: the
technical `admin` role is there only because rule O1 activates `sheet_editor` for a platform admin (hence the
grant asking `admin` first, as `grant_catalog_right` does); O1 is unchanged. A production practitioner
holds neither `admin` nor a catalogue editing right by default.
Rotation and recovery: `rotate-keys` before the keys expire (`status` shows the date); `rotate-secrets` to revoke.
If `rotate-secrets` loses psql, the marker the transaction wrote tells whether it committed and only the matching
file stays `secrets.env` (password probes prove nothing here: loopback connections are `trust` in this image); if a
rotation stops after the commit, `pnpm db:trial start` recreates the containers; if it stops before the commit is
known, the script names the backup taken just before, and `restore <that backup>` returns to the previous secrets
and data. Every backup holds the `secrets.env` of its time: restoring a backup taken before a `rotate-secrets`
brings the old secrets back (the script says so before the confirmation). A restore needs the same Postgres image
as the backup (recorded in its `stack.conf`).
No automated suite reaches this stack: `db-trial.sh` refuses a shell holding `SANDBOX_*` variables; the sandbox
suites (`packages/supabase/tests/sandbox/target.ts`, imported by `stack.ts` and the shell Playwright config)
accept only the sandbox's container, loopback ports and key issuer `db-sandbox`; the LAN Playwright config accepts
port 5193 only; `e2e:avatar` and `e2e:sheet-assets` require the sandbox URL and issuer; `db-sandbox.sh` refuses a
state folder holding the trial marker; every secret differs from the sandbox's. `bash scripts/db-trial-check.sh`,
run by hand, proves these refusals and the script's Docker calls with stubs, no daemon reached; it is not a
`pnpm check:all` stage because it reads the host's real ports and memory, and it refuses to run (exit 2) while the
trial stack or app holds a port.
Identification of the target (owner 2026-11-10): the trial dev server (`apps/app/vite/trial.config.ts`, shared with
`pnpm db:sandbox trial`) serves exactly one of the two stacks listed in `apps/app/vite/trial-targets.ts`. The exact
gateway string picks it; the app port (with `--strictPort`), `VITE_SUPABASE_URL` and the anon key's `role` and
`iss` must then match that same stack, and the db:trial gateway must answer `GET /__faunosteo_stack` with
`faunosteo_trial`; anything else stops Vite before it listens, with no fallback to the sandbox, DEV or another
local service. `db-trial.sh` checks, before acting: for `app` and `assets`, the gateway container published exactly
on 127.0.0.1:58801 and its identity answer; for `account`, GoTrue published exactly on 127.0.0.1:58999; for
`migrate`, Postgres exactly on 127.0.0.1:58432; and every key it hands over (Vite, the upload tool, GoTrue's admin
API, Storage's env) must be signed with this stack's JWT secret for the issuer `faunosteo-trial` and the expected
role. The identity answer is a static name, not authentication: the exact port, the container checks and the key
signatures carry the rest.
Limits: one host; no verification worker on this stack, so a draft submitted for verification stays waiting; the
historical sheet allows one working copy at a time; Mailpit is reachable on the host only; backups sit on the same
disk (copy them elsewhere by hand). `app` takes no lock: `stop`, `destroy`, `restore`, `rotate-keys` or
`rotate-secrets` run in another terminal in the second before Vite listens on 5194 goes ahead. After `rotate-keys`
the app keeps the previous anon key until its expiry; after `rotate-secrets` its requests are refused (401) until
`app` is restarted; after `stop` or `destroy` it proxies to whatever later listens on 127.0.0.1:58801. Launch no
other `db:trial` command while `app` is starting.
Proven only at the first `create` (the stub harness cannot prove them): the database init under a volume, the
`supabase_admin` password used by `rotate-secrets`, the pids caps, `tar` and `du` in the database image (checked by
`create` before anything is made), the image's default logging settings, the backup helper's `tar` restoring
ownership in the database image, `set local pgaudit.log` accepted by the image, loopback `trust` in its `pg_hba.conf`
(the rotation's commit marker relies on it), psql's echo of an error statement (a failing rotation statement must not print a
secret), and the grant and factor SQL, which the harness checks as text and which first
runs at the first real `grant`.
## 6. Generated types ## 6. Generated types
```bash ```bash
+29 -9
View File
@@ -1,12 +1,10 @@
# Dedicated manual trial stack: technical plan # Dedicated manual trial stack: technical plan
Status: PROPOSAL, 2026-11-09 (owner brief « V1-2.6 UX — Arbitrages du premier essai propriétaire », §5), with the Status: IMPLEMENTED 2026-11-10 (scripts and environment-free checks, lots committed 2026-11-09 and 2026-11-10), NOT
decisions of the briefs « R0 — Décisions propriétaire et dernière validation graphique » (BDR-108) and « R0 — Verdict CREATED: the stack is created only after the owner's explicit go (brief « Après R0 — Implémentation technique de la
de revue graphique propriétaire » (BDR-109), both 2026-11-09: name pile d'essai dédiée »). Design from the briefs « V1-2.6 UX — Arbitrages du premier essai propriétaire » §5,
`pnpm db:trial`, two trial accounts, `db:sandbox trial*` kept for now, isolation from the suites, volumes preserved, « R0 — Décisions propriétaire et dernière validation graphique » (BDR-108) and « R0 — Verdict de revue graphique
resources capped, secrets renewable. Plan propriétaire » (BDR-109). Operating guide: `SUPABASE.md` §5.2. Companion of `V1-2-6_U1_CORRECTIONS.md`.
only: no stack is created, started, reset or removed, no script changes, existing data untouched. Implementation
needs its own owner authorisation. Companion of `V1-2-6_U1_CORRECTIONS.md`.
## 1. Why ## 1. Why
@@ -67,8 +65,9 @@ its first initialisation). Keys valid one year instead of 30 days, with a `rotat
keys with the same secret and restarts the services: a persistent stack with the sandbox's 30-day keys would lock keys with the same secret and restarts the services: a persistent stack with the sandbox's 30-day keys would lock
itself out after a month. Full renewal (owner 2026-11-09) is `rotate-secrets`: a new JWT secret and new keys, new role itself out after a month. Full renewal (owner 2026-11-09) is `rotate-secrets`: a new JWT secret and new keys, new role
passwords set in the database (`alter role … password`, values through psql variables, never argv), env files passwords set in the database (`alter role … password`, values through psql variables, never argv), env files
rewritten (600), services restarted in order, the previous secrets file kept as `secrets.prev.sh` (600) until the rewritten (600), services restarted in order; the new values wait in `secrets.next.env` (600) until the commit is
stack answers; account passwords are untouched. Both commands print no secret. Rules (A14, decided 2026-11-09): keys valid one year on this dedicated local stack known, and the previous secrets stay in the backup taken just before (no `secrets.prev` file); account passwords
are untouched. Both commands print no secret. Rules (A14, decided 2026-11-09): keys valid one year on this dedicated local stack
only; no secret in Git, in a command line, in the script's output or in a log (the state folder sits outside the only; no secret in Git, in a command line, in the script's output or in a log (the state folder sits outside the
repository and the script refuses one inside it); the rotation procedure is written in the script's help and in repository and the script refuses one inside it); the rotation procedure is written in the script's help and in
`SUPABASE.md`; the renewal code gets a security review (fresh security gate) before the stack is used. Since every secret differs from the sandbox's, a suite that reached a trial port by mistake `SUPABASE.md`; the renewal code gets a security review (fresh security gate) before the stack is used. Since every secret differs from the sandbox's, a suite that reached a trial port by mistake
@@ -154,3 +153,24 @@ they created; `shellcheck` on both scripts.
| A13 | Trial accounts | DECIDED: two accounts (3.5); practitioner = technical `admin` + `sheet_editor`, not a production profile; O1 unchanged. | | A13 | Trial accounts | DECIDED: two accounts (3.5); practitioner = technical `admin` + `sheet_editor`, not a production profile; O1 unchanged. |
| A14 | Key lifetime and renewal | DECIDED: one year, documented rotation, no secret in Git or logs, security review of the renewal (3.3). | | A14 | Key lifetime and renewal | DECIDED: one year, documented rotation, no secret in Git or logs, security review of the renewal (3.3). |
| A15 | Backup before every `migrate` | RATIFIED: automatic, kept in the state folder, never pruned without the owner. | | A15 | Backup before every `migrate` | RATIFIED: automatic, kept in the state folder, never pruned without the owner. |
## 7. Implementation (2026-11-10)
`scripts/db-trial.sh`, `scripts/db-trial-check.sh`, the suites' guard `packages/supabase/tests/sandbox/target.ts`.
Owner choices made at implementation (contract `.claude/tasks/contracts/2026-11-09-db-trial-stack-1809.md`):
cold physical backups (both volumes and the secrets, the stack stopped a few seconds) and a `restore` command
instead of `pg_dump -Fc` (§3.4); a read-only `plan` command; `db-sandbox.sh` gains a state-folder guard only, no
shared helper file (§4), and `db-trial.sh` pins its own images; GoTrue's public sign-up closed. Also: the gateway
refuses `/auth/v1/admin/`; `grant owner|admin` follows §5.7.1 of the V1-2 contract (factors first, typed
confirmation, audit row); catalogue rights mirror `public.grant_catalog_right` (admin first, no implicit admin
role), and every grant asks a typed confirmation. After the plan challenge (2026-11-10): `account`, `grant`,
`restore` and `destroy` need a terminal; the app host is decided at each run, not recorded (§3.2); `start`
recreates a missing container; backups check free space, list each archive back and write checksums last, and
`restore` and `destroy` never remove a volume without a backup of it: `destroy` refuses without a restorable
backup of what it would remove and names the manual removal commands; the stub harness is run by hand, not by
`check:all` (it reads the host's real ports). R13 (owner 2026-11-10): the shared trial dev server serves exactly
one of two listed stacks (`apps/app/vite/trial-targets.ts`), and `db-trial.sh` checks each operation's target and
every key it hands over (`SUPABASE.md` §5.2). Known limit: `app` takes no lock, so a `stop`, `destroy`, `restore`
or rotation run in another terminal just before Vite listens goes ahead (`SUPABASE.md` §5.2). The tests of §5 that
create a stack under a test prefix were not run (owner brief: environment-free checks only); the stub harness
replaces them until the first `create`.
+6
View File
@@ -15,6 +15,12 @@ Prérequis : Docker, `pnpm install` fait, une application
d'authentification TOTP (téléphone ou gestionnaire de mots de passe) pour l'étape 3, et un écran d'au moins d'authentification TOTP (téléphone ou gestionnaire de mots de passe) pour l'étape 3, et un écran d'au moins
1 024 px de large (en dessous l'éditeur est en lecture seule). 1 024 px de large (en dessous l'éditeur est en lecture seule).
> **Pile d'essai dédiée (`pnpm db:trial`).** Une pile persistante, séparée de la sandbox et de DEV, est préparée
> (scripts et contrôles, `docs/development/SUPABASE.md` §5.2). Elle n'est pas encore créée : sa création attend
> l'accord du propriétaire. Ce guide décrit l'essai sur la sandbox (`pnpm db:sandbox trial`), qui reste disponible.
> Sur la pile dédiée, le compte praticien d'essai reçoit le rôle technique `admin`, puis l'habilitation
> `sheet_editor` (refusée tant que `admin` manque) : ce n'est pas le profil d'un praticien de production.
## 1. Démarrer la pile jetable ## 1. Démarrer la pile jetable
```bash ```bash