From 60087bab30e10c48c8162ed98879d1d042354eb6 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 10 Nov 2026 13:36:14 +0100 Subject: [PATCH] docs(docs): db:trial implementation plan and gated contract --- .../2026-11-09-db-trial-stack-1809.md | 262 ++ .../tasks/plans/2026-11-09-db-trial-stack.md | 3541 +++++++++++++++++ 2 files changed, 3803 insertions(+) create mode 100644 .claude/tasks/contracts/2026-11-09-db-trial-stack-1809.md create mode 100644 .claude/tasks/plans/2026-11-09-db-trial-stack.md diff --git a/.claude/tasks/contracts/2026-11-09-db-trial-stack-1809.md b/.claude/tasks/contracts/2026-11-09-db-trial-stack-1809.md new file mode 100644 index 00000000..ac56fb48 --- /dev/null +++ b/.claude/tasks/contracts/2026-11-09-db-trial-stack-1809.md @@ -0,0 +1,262 @@ +# CONTRACT — db-trial-stack +- date: 2026-11-09 | flow: ship-feature | branch: feature/v1-2-anatomical-sheets +- status: active +- worktree: /home/bchanot/Documents/faunosteo-v1-2 (every command from this absolute path, LRN-110; never the main + checkout /home/bchanot/Documents/faunosteo, whose old scripts reach DEV). Commit in place on the working branch, + push each commit; no sub-branch, no merge, no `gitflow.sh finish`. +- base: b215b89 +- untracked files kept: `faunosteo-v1-2-6-revue-ux-chatgpt.md` (this worktree), + `/home/bchanot/Documents/faunosteo/faunosteo-v1-2-4-revue-chatgpt.md` (main checkout). +- design reference: `docs/development/TRIAL_STACK.md` (arbitrations A11-A15 settled, BDR-107 to BDR-110), + `docs/development/V1-2_ANATOMICAL_SHEETS.md` §5.7.1 (first owner bootstrap order). + +## REQUEST (verbatim — IMMUTABLE) + +# FAUNOSTEO — Après R0 — Implémentation technique de la pile d'essai dédiée + +Le propriétaire prend acte de la clôture graphique de R0, du verdict indépendant CONFORME et de BDR-110. + +Les maquettes R0 sont définitivement validées. Ne pas rouvrir leur conception. + +## 1. Autorisation + +Autorisation ciblée pour implémenter les scripts, configurations et tests nécessaires à la pile d'essai dédiée, selon docs/development/TRIAL_STACK.md et les arbitrages A11 à A15. + +Cette autorisation ne couvre PAS le démarrage effectif de la pile ni la création de données. + +## 2. Isolation + +Créer une pile distincte de la sandbox automatisée et de Supabase DEV : + +- Préfixe des conteneurs : faunosteo_trial_. +- Commandes : pnpm db:trial. +- Ports séparés, selon le plan validé. +- Base de données, stockage, secrets, réseaux et volumes distincts. +- Volumes persistants et sauvegardes contrôlées. +- Limites mémoire adaptées aux ressources de l'hôte. +- Aucune réutilisation des volumes, secrets ou noms de conteneurs de DEV ou de la sandbox. + +Conserver les commandes db:sandbox trial* existantes, sans redirection implicite. + +## 3. Sécurité + +Mettre en place des garde-fous empêchant les suites E2E, Vitest ou les outils de réinitialisation de la sandbox d'utiliser la pile d'essai. + +Privilégier des vérifications bloquantes : tout environnement ambigu doit provoquer un refus d'exécution. + +Ne pas exposer les ports internes de PostgreSQL, Auth ou Storage au réseau local. + +Prévoir la rotation des secrets sans perte de données. + +Ne jamais écrire de secrets dans Git, les journaux ou les rapports. + +## 4. Comptes d'essai + +Prévoir deux comptes distincts : + +- Owner/admin, pour les essais administratifs. +- Praticien d'essai avec rôle admin technique et habilitation sheet_editor, sans owner, reviewer ou publisher. + +Ne pas modifier la règle O1. + +Documenter clairement que le second compte ne représente pas encore les autorisations d'un praticien de production. + +Préserver les exigences MFA. + +## 5. Cheval historique + +Préparer une méthode reproductible pour charger la fiche équine de référence et ses illustrations. + +Ne pas copier silencieusement des données de la sandbox actuelle. + +Vérifier les empreintes, la présence des illustrations et l'intégrité du document importé. + +Éviter les doublons en cas de relancement. + +Ne pas modifier la fiche équine historique ni les données de DEV. + +## 6. Tests + +Exécuter uniquement les contrôles ne nécessitant pas de création ou de destruction d'environnement. + +Vérifier : +- Le ciblage exclusif des ressources trial. +- Les collisions de ports et de noms. +- Les garde-fous contre les tests automatisés. +- La persistance prévue. +- La sécurité des secrets. +- Les chemins de sauvegarde et de restauration. +- La compatibilité avec les commandes sandbox existantes. + +Effectuer une revue indépendante du code et une revue de sécurité. + +Commiter et pousser chaque lot validé. + +## 7. Checkpoint avant création + +Avant de lancer pnpm db:trial up ou une commande équivalente, fournir : + +1. La liste exacte des ressources Docker qui seraient créées. +2. Les ports réellement disponibles et les éventuels conflits. +3. L'emplacement des volumes et sauvegardes. +4. Les limites mémoire prévues. +5. Les commandes de démarrage, arrêt, sauvegarde et rotation. +6. La procédure de chargement de l'équin et des illustrations. +7. Les résultats des tests et revues. +8. La preuve que les commandes de test automatiques ne peuvent pas cibler cette pile. + +S'arrêter et attendre l'accord explicite du propriétaire avant toute création effective. + +## 8. Restrictions + +Ne pas démarrer, réinitialiser ou supprimer de conteneur. + +Ne pas toucher à la sandbox existante ni à ses 219 fiches. + +Ne pas intervenir sur Supabase DEV. + +Aucune migration SQL applicative, modification Rust, worker ou format documentaire. + +Ne pas commencer R1 à R4, U2, U2b ou V1-2.7. + +Aucune fusion ni déploiement. + +Préserver les fichiers non suivis, notamment la revue ChatGPT. + +S'arrêter au checkpoint de création de la pile d'essai. + +## CLARIFICATIONS +Q: backup format and restore? / A: cold physical copy (stack stopped a few seconds, both volumes archived through a +`--rm` helper container, secrets copy, restart) + new command `pnpm db:trial restore ` with typed +confirmation and an automatic backup first; same Postgres image required. Supersedes TRIAL_STACK.md §3.4 `pg_dump -Fc`. +[gated 2026-11-09] +Q: read-only dry run for the checkpoint? / A: new command `pnpm db:trial plan`: exact containers, volumes, network, +each port free or taken, volume and backup locations, memory limits; no docker call that creates or changes anything. +[gated 2026-11-09] +Q: how far to change `scripts/db-sandbox.sh`? / A: guard only (refuse a trial state folder); `db-trial.sh` self-contained +with its own image pins; no shared helper extraction (TRIAL_STACK.md §4 sentence superseded). [gated 2026-11-09] +Q: public sign-up on the trial stack? / A: closed (`GOTRUE_DISABLE_SIGNUP=true`); accounts only through +`pnpm db:trial account`. [gated 2026-11-09] +Q: plan approval? / A: owner 2026-11-10 « Décision sur le plan db:trial »: architecture, lots A, B1, B2, B3, C and +closure approved, conditional on R13 fixed in the plan (exact target identification, no ambiguous destination, no +fallback, db:sandbox trial* preserved with non-regression tests) and an independent targeted counter-check; validated: +exact interactive confirmations, piped or automated confirmations refused, harness outside check:all, grant without +implicit admin, FAUNOSTEO_TRIAL_DIR checked on its canonical path incl. symlinks, no secrets.prev given a restorable +protected prior backup, app address recomputed at each launch, ss checked explicitly. Authorisation covers writing and +static or simulated checks only: no real create/start/stop/migration/restore/destroy/rotation, no DEV or sandbox, no +merge or deploy; a script's interactive confirmation is never the owner's prior authorisation. [gated 2026-11-10] + +## ACCEPTANCE CRITERIA +1. `pnpm db:trial` (root `package.json`) runs `scripts/db-trial.sh` with the commands of TRIAL_STACK.md §4 (`create`, + `start`, `stop`, `status`, `migrate`, `backup`, `rotate-keys`, `rotate-secrets`, `app`, `account `, + `grant `, `assets`, `destroy`); `pnpm db:sandbox` keeps every existing command, `trial`, + `trial-account` and `trial-grant` included, with unchanged behaviour (no redirection to the trial stack). +2. Docker resources of the trial stack are literal names only: containers `faunosteo_trial_db`, `_auth`, `_rest`, + `_storage`, `_mail`, `_gateway`, network `faunosteo_trial_net`, volumes `faunosteo_trial_db` and + `faunosteo_trial_storage`; every docker call of `db-trial.sh` that starts, stops, recreates or removes names one of + them (helper containers excepted, prefixed `faunosteo_trial_` and `--rm`), never a filter or a pattern; no name, + port, volume, network or secret is shared with DEV (`supabase_*_faunosteo`, 54321-54324) or the sandbox + (`faunosteo_dbsandbox_*`, 57xxx, 5193). +3. Ports: Postgres 127.0.0.1:58432, GoTrue :58999, PostgREST :58300, Storage :58500, Mailpit :58025, gateway :58801, + all published on 127.0.0.1 only; the app on the validated trial host :5194 (`--strictPort`); every start refuses a + taken port before any docker call and checks after start that each container publishes on 127.0.0.1 only. +4. Persistence: Postgres data in volume `faunosteo_trial_db` at `PGDATA`, Storage files in `faunosteo_trial_storage` + at `/mnt`; restart policy `no`; `start`/`stop`/rotation keep both volumes; a volume is removed only by `destroy` + (and by the restore path if the gate adds one), after a typed confirmation. +5. Resources: per container `--memory`, `--cpus 1`, `--pids-limit` as TRIAL_STACK.md §3.7 (Postgres 1 GiB with + `shared_buffers` 128 MB, PostgREST 384 MiB, Storage 256 MiB, GoTrue 128 MiB, Mailpit and gateway 64 MiB); the app + runs with `NODE_OPTIONS=--max-old-space-size=768`; `create` refuses when the host lacks the memory budget. +6. Secrets: state folder `~/.cache/faunosteo-trial` (override `FAUNOSTEO_TRIAL_DIR`), mode 700, refused inside the + repository and refused when it is (or holds) the sandbox state; files 600; values reach containers and tools through + env files or stdin, never argv, script output, logs or Git; keys signed with the trial's own JWT secret, issuer + distinct from `db-sandbox`, valid one year; `rotate-keys` re-signs both keys, `rotate-secrets` renews JWT secret, + keys and role passwords without data loss, account passwords untouched; neither prints a secret. +7. Isolation guards, blocking and fail-closed: `db-trial.sh` refuses to run when any `SANDBOX_*` variable is set; the + sandbox suites (`packages/supabase/tests/sandbox/stack.ts` and every importer, the shell and LAN Playwright + configs) refuse any target that is not the sandbox's exact container, loopback ports and key issuer before their + first request; `db-sandbox.sh` refuses a state folder that belongs to the trial stack; `e2e:avatar` and + `e2e:sheet-assets` still refuse anything but the sandbox. +8. Accounts: `account ` creates a confirmed account through GoTrue's admin API, password at a hidden prompt + (twice, 12 characters min.), never printed; `grant` assigns platform roles `owner` / `admin` only through + `private.assign_platform_role(null, …)` from a JWT-less session after the operator check of §5.7.1 (verified TOTP + factors present) and catalogue rights as the sandbox does; O1 and every migration unchanged; no MFA factor, aal or + session is written by the script; docs state that the practitioner account (technical `admin` + `sheet_editor`) is + not a production practitioner profile. +9. Equine sheet: `create` applies the branch's migrations and `equine_draft.sql` only (never `seed.sql`), after + checking the seed folder's hashes; it then checks in the database that the historical sheet is the only official + sheet and that its draft content equals `document.json`; `assets` uploads the drawings with the existing + `upload-sheet-assets` tool through the trial gateway (no overwrite, rerun = nothing to do) and checks every asset + row uploaded; no data copied from the sandbox; seed files untouched. +10. `migrate` takes a backup first (A15), refuses when a migration already applied differs from its file, applies the + new ones with `--db-url` on 58432 only, and reloads PostgREST's schema. +11. `backup` writes into `/backups/` (700/600, never pruned by the script) what a restore needs, secrets copy + included; the restore path follows the gate's decision. +12. Environment-free checks only (no container, volume or network created, started, stopped or removed during the + run): `shellcheck` clean on the new and changed scripts; a stub harness proves criteria 2-7, 10-11 on the docker + and curl calls the script would make, with no daemon reachable; the guard's unit tests run in `pnpm test:run`; + `pnpm typecheck`, `pnpm lint`, `pnpm test:run` green. +13. Untouched: `supabase/migrations/`, `supabase/seed/`, `crates/`, document and archive formats, DEV, the sandbox's + containers and data, the untracked review files. +14. Docs: `SUPABASE.md` (trial stack section, rotation procedure), `V1-2-6_OWNER_TRIAL.md`, `TRIAL_STACK.md` status, + `CLAUDE.md` commands, `.claude/tasks/TODO.md`. +15. Stop at the creation checkpoint with the 8 items of §7 of the request; no `create` run. +16. [gated 2026-11-10] R13: the trial dev server (`apps/app/vite/trial.config.ts`, shared with `db:sandbox trial`) + serves exactly one of two literal targets (`apps/app/vite/trial-targets.ts`): sandbox = app 5193, gateway + `http://127.0.0.1:57801`, key issuer `db-sandbox`; trial = app 5194, gateway `http://127.0.0.1:58801`, issuer + `faunosteo-trial`, gateway identity `faunosteo_trial`; any other gateway, port, app URL, issuer or role is refused, + no default, no fallback; the exact values `db-sandbox.sh` passes today stay accepted (non-regression tests). + `db-trial.sh` checks before each operation the target container's exact loopback publication, the trial gateway's + identity, and every key it hands over (issuer, role, HMAC with the trial secret, values never in argv). The + independent R13 counter-check returned CONFORME (or every finding it raised is closed in the plan) before lot A2. + CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && pnpm --filter @faunosteo/app exec vitest run tests/unit/vite.trialTargets.test.ts tests/unit/vite.trialConfig.test.ts && pnpm --filter @faunosteo/app exec tsc -p tsconfig.node.json --noEmit && pnpm --filter @faunosteo/supabase exec vitest run tests/sandbox-target.test.ts && echo GUARD-TESTS-OK + EXPECT: GUARD-TESTS-OK + EVIDENCE: pending +17. [gated 2026-11-10] The stub harness passes in full with simulated services only (docker, curl, ss, node and env + wrapped; no daemon reachable), including: typed confirmations of `destroy` (`faunosteo_trial`), `restore` + (`restore `) and `grant` (`grant `) through a terminal only, piped phrases refused; `grant` never adds + `admin` implicitly; `FAUNOSTEO_TRIAL_DIR` refused on its canonical path (symlink into the repository or onto the + sandbox state, any git work tree); `ss` missing or failing refuses (never read as a free port); `rotate-keys` and + `rotate-secrets` take a verified backup first (700/600, checksums, previous `secrets.env` inside); no secret in + any logged argv. bash -n and shellcheck are never offered as proof of real behaviour. + CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && bash scripts/db-trial-check.sh + EXPECT: db-trial-check: ALL PASS + EVIDENCE: pending +18. [gated 2026-11-10] Static checks: shellcheck clean on `db-trial.sh`, the harness and `db-sandbox.sh`. + CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && shellcheck scripts/db-trial.sh scripts/db-trial-check.sh && shellcheck -e SC1090,SC1091,SC2016 scripts/db-sandbox.sh && echo SHELLCHECK-OK + EXPECT: SHELLCHECK-OK + EVIDENCE: pending +19. [gated 2026-11-10] Project suites green. + CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && pnpm typecheck && pnpm lint && pnpm test:run && echo SUITES-GREEN + EXPECT: SUITES-GREEN + EVIDENCE: pending +20. [gated 2026-11-10] `scripts/db-sandbox.sh` gains lines and loses none since b215b89 (its commands unchanged). + CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && test "$(git diff --numstat b215b89 -- scripts/db-sandbox.sh | awk '{print ($1>0 && $2==0) ? "ok" : "bad"}')" = ok && echo SANDBOX-ADDITIONS-ONLY + EXPECT: SANDBOX-ADDITIONS-ONLY + EVIDENCE: pending +21. [gated 2026-11-10] Untouched: migrations, seed and crates (committed and working tree). + CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && git diff --quiet b215b89 -- supabase/migrations supabase/seed crates && test -z "$(git status --porcelain -- supabase/migrations supabase/seed crates)" && echo UNTOUCHED + EXPECT: UNTOUCHED + EVIDENCE: pending +22. [gated 2026-11-10] Nothing real created: no `faunosteo_trial*` container, volume or network, no state folder + (the pattern is first proven on a fixture line, the listings must succeed). + CHECK: printf 'faunosteo_trial_db\n' | grep -q '^faunosteo_trial' && c=$(docker ps -a --format '{{.Names}}') && v=$(docker volume ls --format '{{.Name}}') && n=$(docker network ls --format '{{.Name}}') && ! printf '%s\n%s\n%s\n' "$c" "$v" "$n" | grep -q '^faunosteo_trial' && test ! -e "$HOME/.cache/faunosteo-trial" && echo NOTHING-CREATED + EXPECT: NOTHING-CREATED + EVIDENCE: pending +23. [gated 2026-11-10] The untracked review files are kept. + CHECK: test -f /home/bchanot/Documents/faunosteo-v1-2/faunosteo-v1-2-6-revue-ux-chatgpt.md && test -f /home/bchanot/Documents/faunosteo/faunosteo-v1-2-4-revue-chatgpt.md && echo REVIEWS-KEPT + EXPECT: REVIEWS-KEPT + EVIDENCE: pending +24. [gated 2026-11-10] Each lot (A, A2, B1, B2, B3, C) tested, reviewed, committed and pushed before the next; no + merge, no deploy, no real create/start/stop/migrate/restore/destroy/rotation, DEV and the sandbox untouched; the + closure report gives the exact R13 counter-check verdict, test results, security review, the 8 checkpoint items + and the read-only `pnpm db:trial plan` output, then stops for the owner's explicit go. + +## FILE SCOPE +- new: `scripts/db-trial.sh`, the stub harness under `scripts/`, the guard module and its unit test under + `packages/supabase/tests/` +- changed: `package.json` (one script), `scripts/db-sandbox.sh` (state-folder guard), + `packages/supabase/tests/sandbox/stack.ts`, `apps/app/e2e/playwright.shell.config.ts`, + `apps/app/e2e/playwright.lan.config.ts`, `apps/app/vite/trial.config.ts` (target table checks, R13 [gated + 2026-11-10]); new `apps/app/vite/trial-targets.ts`, `apps/app/tests/unit/vite.trialTargets.test.ts` and + `apps/app/tests/unit/vite.trialConfig.test.ts` +- docs: `docs/development/{SUPABASE,V1-2-6_OWNER_TRIAL,TRIAL_STACK}.md`, `CLAUDE.md`, `.claude/tasks/TODO.md` diff --git a/.claude/tasks/plans/2026-11-09-db-trial-stack.md b/.claude/tasks/plans/2026-11-09-db-trial-stack.md new file mode 100644 index 00000000..f6e9815e --- /dev/null +++ b/.claude/tasks/plans/2026-11-09-db-trial-stack.md @@ -0,0 +1,3541 @@ +# db:trial stack Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: subagent-driven-development (ship-feature STEP 4). Lots run in order; +> each lot is one coherent change, checked, then committed and pushed by the orchestrator. Steps use checkbox +> (`- [ ]`) syntax for tracking. + +**Goal:** a dedicated persistent manual trial stack, `pnpm db:trial`, isolated from DEV and from the sandbox, with +guards that keep every automated suite off it, built and tested without creating any Docker resource. + +**Architecture:** one self-contained bash tool `scripts/db-trial.sh` (own image pins, literal `faunosteo_trial_*` +names, loopback ports 58xxx, named volumes, secrets in a 700 state folder outside the repository, cold backups); +a pure TypeScript guard `packages/supabase/tests/sandbox/target.ts` called by every sandbox suite entry point; an +environment-free stub harness `scripts/db-trial-check.sh` that runs both bash scripts from a throwaway copy with +docker, curl, the CLI, Vite and the Rust tools replaced by logging stubs and no reachable daemon. + +**Tech Stack:** bash 5 (`set -euo pipefail`), Docker rootless 29 (only through stubs in this run), Node 24 (key +generation, JSON), TypeScript 5 + vitest 3, shellcheck 0.11. + +**Spec:** contract `.claude/tasks/contracts/2026-11-09-db-trial-stack-1809.md` (REQUEST verbatim, 15 criteria, +4 gated clarifications); design `docs/development/TRIAL_STACK.md`; first-owner order +`docs/development/V1-2_ANATOMICAL_SHEETS.md` §5.7.1. + +**Contract changes at the gate (owner 2026-11-10, R13 fixed, no longer deferred):** FILE SCOPE gains +`apps/app/vite/trial-targets.ts` (new) and `apps/app/tests/unit/vite.trialTargets.test.ts` (new); +`apps/app/vite/trial.config.ts` changes from "comment only" to the target table checks (lot A2); `scripts/db-sandbox.sh` +stays additions-only (lot A2 does not touch it); FILE SCOPE also gains `apps/app/tests/unit/vite.trialConfig.test.ts` +(the wiring test of the shared config, which also ties its sandbox constants to `scripts/db-sandbox.sh`). Criterion 7 +gains: the trial dev server serves exactly one of the two +known stacks (gateway, app port, app URL, anon key issuer, and for db:trial the gateway's identity), and +`db-trial.sh` checks the identity of each operation's target (lot B1 table) and of every key it hands over. + +## Global Constraints + +- Worktree `/home/bchanot/Documents/faunosteo-v1-2`, branch `feature/v1-2-anatomical-sheets`, base b215b89. Every + shell command starts with `cd /home/bchanot/Documents/faunosteo-v1-2 &&` (LRN-110). Never read, run or edit + anything under `/home/bchanot/Documents/faunosteo` (other checkout, old scripts that reach DEV). +- NEVER run `scripts/db-trial.sh`, `pnpm db:trial …`, `pnpm db:sandbox …`, `pnpm db:*`, `pnpm supabase …`, + `pnpm e2e:*`, `pnpm check:all`, `pnpm worker:*`, or any `docker` command that is not `ps`, `inspect -f `, `volume ls`, `network ls`, `info`. Never a bare `docker inspect` / `container inspect`: it + prints the env-file values (database password, JWT secret, keys) into the output; the script follows the same rule + (`-f '{{.Name}}'`, `{{.State.Running}}`, `{{.State.Status}} {{.Config.Image}}` only). The trial script runs ONLY + inside `bash scripts/db-trial-check.sh`, which is run by hand (never a `check:all` stage: it probes the host's real + ports and memory). No container, volume or network is created, started, stopped or removed. The sandbox + (`faunosteo_dbsandbox_*`, 219 sheets) and DEV (`supabase_*_faunosteo`) are never touched. +- Typed confirmations (`destroy`, `restore`, `grant owner|admin`) need a terminal: `confirm` refuses piped stdin, so + no agent can feed a phrase through a pipe; the harness drives them through a python3 pty. +- No change under `supabase/migrations/`, `supabase/seed/`, `crates/`; no document or archive format change. +- Every heredoc delimiter quoted (`<<'EOF'`) unless expansion is wanted (LRN-110). No secret in argv, output, logs, + Git: containers read 600 env files, tools their environment (bash prefix assignment, never `env K=V`), psql its + stdin; `printf` is a builtin. +- Untracked files kept: `faunosteo-v1-2-6-revue-ux-chatgpt.md` (this worktree). +- Executors write code and run checks; they never commit, push, merge or run `gitflow.sh`. The orchestrator commits + each lot (Conventional Commits, scopes of CLAUDE.md) and pushes. +- Line length: bash follows `db-sandbox.sh` (long lines accepted); TypeScript per Prettier (`pnpm format` on the + changed files only). + +## Review Focus + +1. A state folder left half-written (secrets file truncated or edited, wrong mode, a create that died before its + first resource) must make every command refuse with a way out, never guess: lot B1 adds the malformed-secrets, + wrong-mode, daemon-down and failed-create cases; `destroy` with no resource clears the live files. +2. A port held by a process outside Docker when the stack starts, or a container published on 0.0.0.0: `start` + refuses before starting any container (all ports checked first, `ss`), and after start on a non-loopback + publication: lot B1 cases. A missing service container is recreated by `start` from stack.conf and secrets.env. +3. A migration file edited after being applied, or a new file older than the last applied one: `migrate` refuses + before any backup or stop (kept although the CLI would also refuse: the refusal comes before the cold backup's + stop/start); a migrate that stops part-way names its pre-migrate backup: lot B2 cases. +4. A backup folder tampered with, partial (no SHA256SUMS) or whose archive does not list: `restore` refuses before + any change; a failed backup leaves no folder; `restore`/`destroy` never remove a volume without a backup of it: + lot B2 cases. +5. Password probes over 127.0.0.1 inside the database container are `trust` in this image's `pg_hba.conf`: they + succeed whatever the password and never prove one. The rotation's commit is proven by the `app.trial_rotation` + marker it writes in the same transaction: lot B2 cases (committed, not committed, database silent). +6. A wrong or empty answer at a confirmation prompt, or a phrase piped without a terminal: nothing changed (lot B2 + and B3 cases, through the harness's pty driver). + +7. A destination that is only "some loopback port" (R13, fixed by owner decision 2026-11-10): the trial dev + server accepts exactly the sandbox's or the trial stack's gateway, with that stack's app port, app URL and anon + key issuer, and the trial gateway must answer its identity (lot A2 tests, both directions of a mix-up, plus the + unchanged db:sandbox values); `db-trial.sh` checks the container, port, identity and keys of each operation's + target (lot B1 table; lot B3 cases: identity wrong or absent, gateway or GoTrue published elsewhere, a key of + the sandbox issuer or signed with another secret). + +--- + +### Lot A: sandbox target guard for the automated suites + +**Files:** +- Create: `packages/supabase/tests/sandbox/target.ts` +- Create: `packages/supabase/tests/sandbox-target.test.ts` +- Modify: `packages/supabase/tests/sandbox/stack.ts:1-16` (docstring + guard call) +- Modify: `apps/app/e2e/playwright.shell.config.ts:9-19` +- Modify: `apps/app/e2e/playwright.lan.config.ts:1-12` + +**Interfaces:** +- Produces: `SANDBOX_TARGET`, `jwtIssuer(token)`, `sandboxTargetProblems(env): string[]`, + `assertSandboxTarget(env = process.env): void`. Exact string equality on every value (house pattern of + `avatar-flow.e2e.ts` and `sheet-assets-e2e.sh`): no URL normalisation, no trailing-slash tolerance. + +- [ ] **Step 1: write the failing test** `packages/supabase/tests/sandbox-target.test.ts` + +```ts +import { describe, expect, it } from 'vitest' +import { assertSandboxTarget, sandboxTargetProblems } from './sandbox/target' + +const b64 = (value: unknown) => + Buffer.from(JSON.stringify(value)).toString('base64url') +const key = (claims: Record) => + `${b64({ alg: 'HS256', typ: 'JWT' })}.${b64(claims)}.signature` + +/** What scripts/db-sandbox.sh exports through with_sandbox_env. */ +const SANDBOX: Record = { + SANDBOX_DB_CONTAINER: 'faunosteo_dbsandbox_db', + SANDBOX_AUTH_URL: 'http://127.0.0.1:57999', + SANDBOX_REST_URL: 'http://127.0.0.1:57300', + SANDBOX_STORAGE_URL: 'http://127.0.0.1:57500', + SANDBOX_MAIL_URL: 'http://127.0.0.1:57025', + SANDBOX_ANON_KEY: key({ role: 'anon', iss: 'db-sandbox' }), + SANDBOX_SERVICE_KEY: key({ role: 'service_role', iss: 'db-sandbox' }), +} +const TRIAL_SERVICE_KEY = key({ role: 'service_role', iss: 'faunosteo-trial' }) + +describe('sandbox target guard', () => { + it('accepts the environment db-sandbox.sh writes', () => { + expect(sandboxTargetProblems(SANDBOX)).toEqual([]) + expect(() => assertSandboxTarget(SANDBOX)).not.toThrow() + }) + + // One refusal per value: the db:trial stack's own value in each variable. + it.each([ + ['SANDBOX_DB_CONTAINER', 'faunosteo_trial_db'], + ['SANDBOX_AUTH_URL', 'http://127.0.0.1:58999'], + ['SANDBOX_REST_URL', 'http://127.0.0.1:58300'], + ['SANDBOX_STORAGE_URL', 'http://127.0.0.1:58500'], + ['SANDBOX_MAIL_URL', 'http://127.0.0.1:58025'], + ['SANDBOX_ANON_KEY', key({ role: 'anon', iss: 'faunosteo-trial' })], + ['SANDBOX_SERVICE_KEY', TRIAL_SERVICE_KEY], + ])('refuses the trial value of %s', (name, value) => { + const env = { ...SANDBOX, [name]: value } + expect(sandboxTargetProblems(env)).toHaveLength(1) + expect(() => assertSandboxTarget(env)).toThrow(/db:sandbox stack only/) + }) + + it('refuses a missing value and a key that is not a JWT', () => { + expect( + sandboxTargetProblems({ ...SANDBOX, SANDBOX_REST_URL: undefined }), + ).toHaveLength(1) + expect( + sandboxTargetProblems({ ...SANDBOX, SANDBOX_ANON_KEY: 'not-a-jwt' }), + ).toHaveLength(1) + }) + + it('names variables, never the values it refused', () => { + let message = '' + try { + assertSandboxTarget({ ...SANDBOX, SANDBOX_SERVICE_KEY: TRIAL_SERVICE_KEY }) + } catch (error) { + message = (error as Error).message + } + expect(message).toMatch(/SANDBOX_SERVICE_KEY/) + expect(message).not.toContain(TRIAL_SERVICE_KEY) + }) +}) +``` + +- [ ] **Step 2: run it, expect FAIL** (module missing) + +Run: `cd /home/bchanot/Documents/faunosteo-v1-2 && pnpm --filter @faunosteo/supabase exec vitest run tests/sandbox-target.test.ts` +Expected: FAIL, `Failed to resolve import "./sandbox/target"`. + +- [ ] **Step 3: create** `packages/supabase/tests/sandbox/target.ts` + +```ts +/** + * The one stack the sandbox suites may reach: the throwaway stack of `pnpm db:sandbox` + * (scripts/db-sandbox.sh), whose runner passes exactly these values. Anything else, such as the + * persistent trial stack of `pnpm db:trial` (containers faunosteo_trial_*, ports 58xxx, keys + * signed for the issuer faunosteo-trial), DEV (54321) or a look-alike address, stops a suite + * before its first request (docs/development/TRIAL_STACK.md §3.6). Exact string equality, as + * avatar-flow.e2e.ts and sheet-assets-e2e.sh do. Messages name variables, never their values. + */ + +/** The exact values scripts/db-sandbox.sh writes (`with_sandbox_env`, `new_secrets`). */ +export const SANDBOX_TARGET = { + container: 'faunosteo_dbsandbox_db', + issuer: 'db-sandbox', + urls: { + SANDBOX_AUTH_URL: 'http://127.0.0.1:57999', + SANDBOX_REST_URL: 'http://127.0.0.1:57300', + SANDBOX_STORAGE_URL: 'http://127.0.0.1:57500', + SANDBOX_MAIL_URL: 'http://127.0.0.1:57025', + }, +} as const + +type Env = Readonly> + +const KEY_VARIABLES = ['SANDBOX_ANON_KEY', 'SANDBOX_SERVICE_KEY'] as const + +/** The `iss` claim of a JWT, or null when the value is not a readable JWT payload. */ +export function jwtIssuer(token: string | undefined): string | null { + const payload = token?.split('.')[1] + if (!payload) return null + try { + const claims: unknown = JSON.parse( + Buffer.from(payload, 'base64url').toString('utf8'), + ) + if (typeof claims !== 'object' || claims === null || Array.isArray(claims)) + return null + const iss = (claims as { iss?: unknown }).iss + return typeof iss === 'string' ? iss : null + } catch { + return null + } +} + +/** Every way `env` differs from the sandbox runner's environment; empty when it is that environment. */ +export function sandboxTargetProblems(env: Env): string[] { + const problems: string[] = [] + if (env.SANDBOX_DB_CONTAINER !== SANDBOX_TARGET.container) + problems.push(`SANDBOX_DB_CONTAINER is not ${SANDBOX_TARGET.container}`) + for (const [name, expected] of Object.entries(SANDBOX_TARGET.urls)) + if (env[name] !== expected) problems.push(`${name} is not ${expected}`) + for (const name of KEY_VARIABLES) + if (jwtIssuer(env[name]) !== SANDBOX_TARGET.issuer) + problems.push(`${name} is not signed for the issuer ${SANDBOX_TARGET.issuer}`) + return problems +} + +/** Throws before any request when the environment is not the sandbox runner's. */ +export function assertSandboxTarget(env: Env = process.env): void { + const problems = sandboxTargetProblems(env) + if (problems.length > 0) + throw new Error( + `Refused: this suite runs against the db:sandbox stack only (pnpm db:sandbox ...). ${problems.join('; ')}.`, + ) +} +``` + + Before writing the constants, confirm them against `scripts/db-sandbox.sh` (`with_sandbox_env`, the port + variables, the key issuer): `grep -n 'SANDBOX_.*_URL\|iss' scripts/db-sandbox.sh`. If any URL is exported with a + trailing slash or a path, copy it exactly as exported and report the difference. + +- [ ] **Step 4: run the test, expect PASS** (same command as step 2). Expected: all tests pass. + +- [ ] **Step 5: wire the guard** in `packages/supabase/tests/sandbox/stack.ts`: docstring gains one sentence, the + call runs before the first `need()`: + +```ts +/** + * Access to the throwaway stack of `pnpm db:sandbox` (scripts/db-sandbox.sh): + * real GoTrue, PostgREST and PostgreSQL sessions, never the DEV stack. The + * script passes the endpoints and the generated keys through the environment; + * the database password reaches `docker exec` through the environment too, + * never through a command argument. Any other target (the db:trial stack, DEV, + * a look-alike) stops the suite here, before its first request (./target.ts). + */ +import { execFile } from 'node:child_process' +import { randomBytes, randomUUID } from 'node:crypto' +import { assertSandboxTarget } from './target' + +assertSandboxTarget(process.env) +``` + + `apps/app/e2e/playwright.shell.config.ts`: after the imports, replace the presence check by the guard and keep a + typed anon key for the web server env: + +```ts +import { defineConfig } from '@playwright/test' +import { assertSandboxTarget } from '../../../packages/supabase/tests/sandbox/target' +import type { GuardOptions } from './support/browser' +import { PROJECTS } from './support/browser' + +const ORIGIN = 'http://127.0.0.1:5192' +const FAKE_SUPABASE_ORIGIN = 'http://sandbox.faunosteo.invalid' +// The sandbox's exact values or nothing starts (the db:trial stack, DEV and look-alikes are refused). +assertSandboxTarget(process.env) +const anonKey = process.env.SANDBOX_ANON_KEY +if (!anonKey) + throw new Error( + 'SANDBOX_ANON_KEY missing: run pnpm e2e:shell (the sandbox must be up)', + ) +``` + + `apps/app/e2e/playwright.lan.config.ts`: the docstring names the guard; the origin is checked: + +```ts +/** + * `playwright test -c e2e/playwright.lan.config.ts` (docs/development/V1-2-6_OWNER_TRIAL.md): + * the owner's trial reached through its LAN origin, which is a non-secure context like a + * phone's browser. It needs a running `pnpm db:sandbox trial` and a trial account; the + * page may reach that origin only, and the origin must be that trial's app (port 5193): the + * persistent db:trial stack is never a test target. No trace, no report: they would hold the + * session tokens and the password. Run by hand, never part of check:all. + */ +import { defineConfig } from '@playwright/test' +import type { GuardOptions } from './support/browser' + +const ORIGIN = process.env.TRIAL_ORIGIN ?? 'http://192.168.1.100:5193' +// The app of pnpm db:sandbox trial only (5193): the db:trial app (5194) is never a test target. +// An unparsable origin throws here too. +if (new URL(ORIGIN).port !== '5193') + throw new Error( + 'Refused: TRIAL_ORIGIN must be the app of pnpm db:sandbox trial (port 5193)', + ) +``` + +- [ ] **Step 6: checks** + +Run: `cd /home/bchanot/Documents/faunosteo-v1-2 && pnpm exec prettier --write packages/supabase/tests/sandbox/target.ts packages/supabase/tests/sandbox-target.test.ts packages/supabase/tests/sandbox/stack.ts apps/app/e2e/playwright.shell.config.ts apps/app/e2e/playwright.lan.config.ts && pnpm typecheck && pnpm lint && pnpm test:run` +Expected: all green (the new test file inside `pnpm test:run` of `@faunosteo/supabase`). If the core-wasm +global setup reports a stale module, run `pnpm wasm:build` first (environment-free) and say so in the report. +Also: `pnpm --filter @faunosteo/app exec tsc -p e2e --noEmit` if an `e2e/tsconfig.json` exists (else state that the +e2e configs are type-checked by Playwright only). + +- [ ] **Step 7: orchestrator commits** `test(supabase): sandbox suites refuse every target but the sandbox` + push. + +--- + +### Lot A2: R13, the trial dev server targets exactly one known stack + +Owner decision 2026-11-10 (plan approval condition): R13 is fixed before any execution, no longer deferred. « Ne +pas accepter une passerelle arbitraire simplement parce qu'elle utilise 127.0.0.1 … Refuser toute destination +ambiguë. Ne pas permettre de repli automatique vers la sandbox, DEV ou un autre service local. Préserver les +commandes db:sandbox trial* existantes. » + +`apps/app/vite/trial.config.ts` is shared by `pnpm db:sandbox trial` and `pnpm db:trial app`. It now names its +two allowed targets in a literal table and identifies the one it serves from four values that must all agree: + +| Element | `pnpm db:sandbox trial` (unchanged, A12) | `pnpm db:trial app` | +|---|---|---| +| Destination: `FAUNOSTEO_TRIAL_GATEWAY`, exact string | `http://127.0.0.1:57801` | `http://127.0.0.1:58801` | +| App port: Vite's resolved `server.port`, `strictPort` true | 5193 | 5194 | +| Configuration: `VITE_SUPABASE_URL`, exact | `http://:5193` | `http://:5194` | +| Key identity: `VITE_SUPABASE_ANON_KEY` payload `role`, `iss` | `anon`, `db-sandbox` | `anon`, `faunosteo-trial` | +| Service: gateway's `GET /__faunosteo_stack` body, exact | no probe (gateway of db-sandbox.sh, untouched) | `faunosteo_trial\n` | + +No default, no fallback: an unknown gateway, a trailing slash, `localhost`, another port (57800, 54321, 58802…), +a key of the other stack, a missing key or a wrong role stops the server before it listens. The Vite side reads +the key's payload only (it holds no secret); `db-trial.sh` checks the signature with the stack's JWT secret before +it hands any key over (lot B1 `key_identity`). The identity endpoint is a static nginx answer of the trial gateway, +not authentication: it tells the trial gateway apart from any other local service on that port, while the exact +port, the key issuer and the container checks of `db-trial.sh` do the rest. The values db-sandbox.sh passes +(`scripts/db-sandbox.sh:59-60, 105, 446-449`: gateway 57801, `--port 5193 --strictPort`, URL `http://:5193`, +anon key `iss` `db-sandbox`) are accepted unchanged; `scripts/db-sandbox.sh` is not touched by this lot. + +**Files:** +- Create: `apps/app/vite/trial-targets.ts` (pure, no Node-only API: `atob`, `fetch`, `AbortSignal.timeout` exist in + both `tsconfig.json` (DOM) and `tsconfig.node.json` (`@types/node`), since the test imports it under the app config) +- Create: `apps/app/tests/unit/vite.trialTargets.test.ts` (vitest of the app: `include: tests/**/*.test.ts`) +- Create: `apps/app/tests/unit/vite.trialConfig.test.ts` (node environment: the shared config resolved by Vite under + each stack's values, and the sandbox constants tied to `scripts/db-sandbox.sh`) +- Modify: `apps/app/vite/trial.config.ts` (docstring, gateway check replaced by `trialTarget`, port guard plugin, + async config with the identity probe) + +**Interfaces:** +- Produces: `TrialTarget`, `TRIAL_TARGETS`, `jwtClaims(token)`, `trialTarget(env): TrialTarget` (throws), + `appPortProblem(target, port, strictPort): string | null`, `targetPortGuard(target)` (the Vite plugin, structural + type, tested with a fake resolved config), `checkGatewayIdentity(target): Promise` (throws; tested with a + stubbed `fetch`). +- Consumed by lot B1: the trial gateway answers `location = /__faunosteo_stack` with `faunosteo_trial\n`. + +- [ ] **Step 1: write the failing test** `apps/app/tests/unit/vite.trialTargets.test.ts` + +```ts +import { afterEach, describe, expect, it, vi } from 'vitest' +import { + appPortProblem, + checkGatewayIdentity, + jwtClaims, + targetPortGuard, + TRIAL_TARGETS, + trialTarget, +} from '../../vite/trial-targets' + +const b64 = (value: unknown) => + btoa(JSON.stringify(value)) + .replace(/\+/g, '-') + .replace(/\//g, '_') + .replace(/=+$/, '') +const key = (claims: Record) => + `${b64({ alg: 'HS256', typ: 'JWT' })}.${b64(claims)}.signature` + +const HOST = '192.168.1.100' +/** Exactly what scripts/db-sandbox.sh cmd_trial passes (non-regression, A12). */ +const SANDBOX = { + FAUNOSTEO_TRIAL_GATEWAY: 'http://127.0.0.1:57801', + FAUNOSTEO_TRIAL_HOST: HOST, + VITE_SUPABASE_URL: `http://${HOST}:5193`, + VITE_SUPABASE_ANON_KEY: key({ role: 'anon', iss: 'db-sandbox' }), +} +/** What scripts/db-trial.sh cmd_app passes. */ +const TRIAL = { + FAUNOSTEO_TRIAL_GATEWAY: 'http://127.0.0.1:58801', + FAUNOSTEO_TRIAL_HOST: HOST, + VITE_SUPABASE_URL: `http://${HOST}:5194`, + VITE_SUPABASE_ANON_KEY: key({ role: 'anon', iss: 'faunosteo-trial' }), +} +const [sandbox, trial] = TRIAL_TARGETS + +describe('trial dev server target', () => { + it('holds exactly the two stacks, sandbox first', () => { + expect(TRIAL_TARGETS.map((t) => t.name)).toEqual(['sandbox', 'trial']) + }) + + it('accepts the values db:sandbox trial passes, unchanged, without a probe', () => { + expect(trialTarget(SANDBOX)).toBe(sandbox) + expect(sandbox.identity).toBeUndefined() + expect(appPortProblem(sandbox, 5193, true)).toBeNull() + }) + + it('accepts the values db:trial app passes, with the gateway identity', () => { + expect(trialTarget(TRIAL)).toBe(trial) + expect(trial.identity).toBe('faunosteo_trial\n') + expect(appPortProblem(trial, 5194, true)).toBeNull() + }) + + it.each([ + ['the DEV gateway', { ...TRIAL, FAUNOSTEO_TRIAL_GATEWAY: 'http://127.0.0.1:54321' }], + ['the sandbox\'s other gateway (avatar and sheet-assets e2e)', { ...SANDBOX, FAUNOSTEO_TRIAL_GATEWAY: 'http://127.0.0.1:57800' }], + ['another loopback port', { ...TRIAL, FAUNOSTEO_TRIAL_GATEWAY: 'http://127.0.0.1:58802' }], + ['a trailing slash', { ...TRIAL, FAUNOSTEO_TRIAL_GATEWAY: 'http://127.0.0.1:58801/' }], + ['localhost', { ...TRIAL, FAUNOSTEO_TRIAL_GATEWAY: 'http://localhost:58801' }], + ['no gateway', { ...TRIAL, FAUNOSTEO_TRIAL_GATEWAY: undefined }], + ['the trial gateway with the sandbox app URL', { ...TRIAL, VITE_SUPABASE_URL: `http://${HOST}:5193` }], + ['the sandbox gateway with a trial key', { ...SANDBOX, VITE_SUPABASE_ANON_KEY: TRIAL.VITE_SUPABASE_ANON_KEY }], + ['the trial gateway with a sandbox key', { ...TRIAL, VITE_SUPABASE_ANON_KEY: SANDBOX.VITE_SUPABASE_ANON_KEY }], + ['a missing key', { ...TRIAL, VITE_SUPABASE_ANON_KEY: undefined }], + ['a service key', { ...TRIAL, VITE_SUPABASE_ANON_KEY: key({ role: 'service_role', iss: 'faunosteo-trial' }) }], + ['an app URL on another host', { ...TRIAL, VITE_SUPABASE_URL: 'http://10.0.0.9:5194' }], + ])('refuses %s', (_label, env) => { + expect(() => trialTarget(env)).toThrow() + }) + + it.each([ + ['the trial gateway behind the sandbox app port', trial, 5193, true], + ['the sandbox gateway behind the trial app port', sandbox, 5194, true], + ['a port Vite may change', trial, 5194, false], + ] as const)('refuses %s', (_label, target, port, strict) => { + expect(appPortProblem(target, port, strict)).not.toBeNull() + }) + + it('reads a JWT payload only when it is one', () => { + expect(jwtClaims(TRIAL.VITE_SUPABASE_ANON_KEY)?.iss).toBe('faunosteo-trial') + expect(jwtClaims('not-a-jwt')).toBeNull() + expect(jwtClaims(`x.${b64(['iss'])}.y`)).toBeNull() + }) +}) + +describe('trial gateway identity probe', () => { + afterEach(() => { + vi.unstubAllGlobals() + }) + + it('accepts exactly faunosteo_trial and a newline, asked without redirects', async () => { + const fetch = vi.fn(async () => new Response('faunosteo_trial\n')) + vi.stubGlobal('fetch', fetch) + await expect(checkGatewayIdentity(trial)).resolves.toBeUndefined() + expect(fetch).toHaveBeenCalledWith( + 'http://127.0.0.1:58801/__faunosteo_stack', + expect.objectContaining({ redirect: 'error' }), + ) + }) + + it.each([ + ['a body without its newline', async () => new Response('faunosteo_trial')], + ['another service', async () => new Response('other\n')], + ['a 404', async () => new Response('faunosteo_trial\n', { status: 404 })], + ['a redirect', async () => new Response(null, { status: 302, headers: { location: 'http://127.0.0.1:57801/' } })], + ['a refused redirect', async () => Promise.reject(new TypeError('unexpected redirect'))], + ['no answer', async () => Promise.reject(new TypeError('fetch failed'))], + ])('refuses %s', async (_label, answer) => { + vi.stubGlobal('fetch', vi.fn(answer)) + await expect(checkGatewayIdentity(trial)).rejects.toThrow(/does not answer/) + }) + + it('never probes the sandbox gateway (db-sandbox.sh unchanged, A12)', async () => { + const fetch = vi.fn() + vi.stubGlobal('fetch', fetch) + await expect(checkGatewayIdentity(sandbox)).resolves.toBeUndefined() + expect(fetch).not.toHaveBeenCalled() + }) +}) + +describe('trial dev server port guard (configResolved)', () => { + const resolved = (port: number | undefined, strictPort: boolean | undefined) => ({ + server: { port, strictPort }, + }) + + it('accepts each stack on its own port with strictPort', () => { + expect(() => targetPortGuard(trial).configResolved(resolved(5194, true))).not.toThrow() + expect(() => targetPortGuard(sandbox).configResolved(resolved(5193, true))).not.toThrow() + }) + + it.each([ + ['the trial stack on the sandbox port', trial, 5193, true], + ['the sandbox on the trial port', sandbox, 5194, true], + ['no strictPort', trial, 5194, false], + ['no port', trial, undefined, true], + ] as const)('refuses %s', (_label, target, port, strict) => { + expect(() => targetPortGuard(target).configResolved(resolved(port, strict))).toThrow(/Refused/) + }) +}) +``` + +- [ ] **Step 2: run it, expect FAIL** (module missing): + `cd /home/bchanot/Documents/faunosteo-v1-2 && pnpm --filter @faunosteo/app exec vitest run tests/unit/vite.trialTargets.test.ts` + +- [ ] **Step 3: create** `apps/app/vite/trial-targets.ts` + +```ts +/** + * The two stacks the trial dev server (vite/trial.config.ts) may proxy to, and nothing else + * (docs/development/TRIAL_STACK.md §3.6, R13): `pnpm db:sandbox trial` (app 5193, sandbox + * gateway 57801, keys of the issuer db-sandbox) and `pnpm db:trial app` (app 5194, trial gateway + * 58801, keys of the issuer faunosteo-trial, a gateway that names itself). The exact gateway + * string picks the target; every other value it implies must match, or the server does not + * start. No default, no fallback to another stack. + */ +export interface TrialTarget { + readonly name: 'sandbox' | 'trial' + readonly appPort: number + readonly gateway: string + readonly issuer: string + /** The exact body of the gateway's GET /__faunosteo_stack; absent: no probe (the sandbox gateway, A12). */ + readonly identity?: string +} + +export const TRIAL_TARGETS: readonly TrialTarget[] = [ + { + name: 'sandbox', + appPort: 5193, + gateway: 'http://127.0.0.1:57801', + issuer: 'db-sandbox', + }, + { + name: 'trial', + appPort: 5194, + gateway: 'http://127.0.0.1:58801', + issuer: 'faunosteo-trial', + identity: 'faunosteo_trial\n', + }, +] + +type Env = Readonly> + +/** + * The claims of a JWT payload, or null. Identity only: no secret here, so no signature check + * (scripts/db-trial.sh checks it with the stack's secret before it hands a key to Vite). + */ +export function jwtClaims( + token: string | undefined, +): Record | null { + const payload = token?.split('.')[1] + if (!payload || !/^[A-Za-z0-9_-]+$/.test(payload)) return null + try { + const base64 = payload.replace(/-/g, '+').replace(/_/g, '/') + const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=') + const claims: unknown = JSON.parse(atob(padded)) + return typeof claims === 'object' && claims !== null && !Array.isArray(claims) + ? (claims as Record) + : null + } catch { + return null + } +} + +/** The one target `env` names, every value it implies checked; throws otherwise. */ +export function trialTarget(env: Env): TrialTarget { + const target = TRIAL_TARGETS.find( + (entry) => entry.gateway === env.FAUNOSTEO_TRIAL_GATEWAY, + ) + if (!target) + throw new Error( + 'FAUNOSTEO_TRIAL_GATEWAY is neither the gateway of pnpm db:sandbox trial (http://127.0.0.1:57801) nor that of pnpm db:trial app (http://127.0.0.1:58801)', + ) + const claims = jwtClaims(env.VITE_SUPABASE_ANON_KEY) + if (claims?.role !== 'anon' || claims.iss !== target.issuer) + throw new Error( + `VITE_SUPABASE_ANON_KEY is not an anon key of the issuer ${target.issuer} (${target.name} stack)`, + ) + const host = env.FAUNOSTEO_TRIAL_HOST ?? '' + if (!host || env.VITE_SUPABASE_URL !== `http://${host}:${target.appPort}`) + throw new Error( + `VITE_SUPABASE_URL must be http://:${target.appPort} (${target.name} stack)`, + ) + return target +} + +/** Why Vite's resolved port does not fit the target, or null (the CLI's --port is resolved in). */ +export function appPortProblem( + target: TrialTarget, + port: number | undefined, + strictPort: boolean | undefined, +): string | null { + if (port === target.appPort && strictPort === true) return null + return `the ${target.name} trial app runs on port ${target.appPort} with --strictPort only` +} + +/** The part of Vite's resolved config the guard reads (structural: no import of Vite's types here). */ +export interface ResolvedServerPort { + readonly server: { readonly port?: number; readonly strictPort?: boolean } +} + +/** A Vite plugin that refuses, once the CLI is resolved in, any port but the target's. */ +export function targetPortGuard(target: TrialTarget): { + name: string + configResolved(config: ResolvedServerPort): void +} { + return { + name: 'faunosteo-trial-target-port', + configResolved(config) { + const problem = appPortProblem( + target, + config.server.port, + config.server.strictPort, + ) + if (problem) throw new Error(`Refused: ${problem}`) + }, + } +} + +/** Throws unless the target's gateway answers its identity body exactly, within 3 s. */ +export async function checkGatewayIdentity(target: TrialTarget): Promise { + if (target.identity === undefined) return + let body = '' + try { + const res = await fetch(`${target.gateway}/__faunosteo_stack`, { + signal: AbortSignal.timeout(3000), + redirect: 'error', + }) + body = res.ok ? await res.text() : '' + } catch { + body = '' + } + if (body !== target.identity) + throw new Error( + `${target.gateway} does not answer as the ${target.name} stack's gateway: refused`, + ) +} +``` + +- [ ] **Step 4: run the test, expect PASS** (same command as step 2). + +- [ ] **Step 5: rewrite the head of** `apps/app/vite/trial.config.ts` (lines 1-28) and its default export; the + `trialHostOnly` plugin and the `server` block stay as they are, except `proxy` now targets `target.gateway`: + +```ts +import { fileURLToPath } from 'node:url' +import { defineConfig, mergeConfig, type Plugin } from 'vite' +import base from '../vite.config' +import { + checkGatewayIdentity, + targetPortGuard, + trialTarget, +} from './trial-targets' + +/** + * Dev server of `pnpm db:sandbox trial` (docs/development/V1-2-6_OWNER_TRIAL.md) and of + * `pnpm db:trial app` (docs/development/SUPABASE.md §5.2). + * The browser talks to this origin only: the three Supabase routes are + * forwarded to the stack's gateway on loopback, so the app itself needs no CORS (the proxied + * routes keep the stack's own CORS headers). + * The server binds the one host the calling script validated (loopback or a private address of + * this machine) and refuses any other Host header. It serves exactly one of the two stacks of + * ./trial-targets.ts: gateway, app port, app URL and anon key issuer must all name the same one, + * and the db:trial gateway must answer its identity; anything else stops it before it listens. + */ +const host = process.env.FAUNOSTEO_TRIAL_HOST ?? '' +const PRIVATE_IPV4 = + /^(127\.0\.0\.1|10(\.\d{1,3}){3}|172\.(1[6-9]|2\d|3[01])(\.\d{1,3}){2}|192\.168(\.\d{1,3}){2})$/ +if (!PRIVATE_IPV4.test(host)) + throw new Error( + 'FAUNOSTEO_TRIAL_HOST must be 127.0.0.1 or a private IPv4 address', + ) +const target = trialTarget(process.env) + +const SUPABASE_ROUTES = ['/auth/v1', '/rest/v1', '/storage/v1'] +const REPO = fileURLToPath(new URL('../../../', import.meta.url)) + +// The CLI's --port and --strictPort are part of the resolved config: checked there. +const targetPortOnly = targetPortGuard(target) +``` + + and the export (the identity probe runs before any listener): + +```ts +export default defineConfig(async (env) => { + await checkGatewayIdentity(target) + return mergeConfig(base(env), { + plugins: [trialHostOnly, targetPortOnly], + // One validated host, never 0.0.0.0: the proxy carries the trial account's session. + server: { + host, + strictPort: true, + allowedHosts: [host], + // Same origin through the proxy: Vite adds no CORS header, and no hot-reload socket + // (its upgrade skips the middlewares above) on a manual trial. + cors: false, + ws: false, + // The LAN sees the app's own sources only: never the repository's notes, seed or builds. + fs: { allow: ['apps/app', 'packages', 'node_modules'].map((dir) => REPO + dir) }, + proxy: Object.fromEntries( + SUPABASE_ROUTES.map((route) => [route, { target: target.gateway }]), + ), + }, + }) +}) +``` + + If `plugins: [trialHostOnly, targetPortOnly]` does not type-check against Vite's `PluginOption` (the structural + type should be assignable: `ResolvedConfig` has `server.port` and `server.strictPort`), report the exact error + rather than casting. Before editing, check that `base` is a function config (`base(env)` is what the file already calls) and that + Vite 7's `defineConfig` accepts an async function (it does: `UserConfigFnPromise`); report if either differs. + +- [ ] **Step 5b: the wiring test** `apps/app/tests/unit/vite.trialConfig.test.ts`: the real shared config resolved + by Vite (`resolveConfig`, command `serve`: it loads the file, runs every `config` and `configResolved` hook, and + opens no listener) under each stack's values. `mergeConfig` types the overrides loosely, so only this proves the + wiring. No package.json `type` here: Vite loads the config as CJS in memory (vite 7.3.6 `config.js:2048-2056`, + `:36005-36009`), so there is no temporary file to report or clean; each `resolveConfig` call re-bundles and clears + the require cache, so the stubbed environment is re-read. + +```ts +// @vitest-environment node +import { readFileSync } from 'node:fs' +import { fileURLToPath } from 'node:url' +import { resolveConfig } from 'vite' +import { afterEach, describe, expect, it, vi } from 'vitest' + +const CONFIG = fileURLToPath(new URL('../../vite/trial.config.ts', import.meta.url)) +const SANDBOX_SCRIPT = fileURLToPath(new URL('../../../../scripts/db-sandbox.sh', import.meta.url)) +const ROUTES = ['/auth/v1', '/rest/v1', '/storage/v1'] +const HOST = '127.0.0.1' + +const b64 = (value: unknown) => + Buffer.from(JSON.stringify(value)).toString('base64url') +const key = (iss: string) => + `${b64({ alg: 'HS256', typ: 'JWT' })}.${b64({ role: 'anon', iss })}.signature` + +function stubStack(gateway: string, appPort: number, iss: string) { + vi.stubEnv('FAUNOSTEO_TRIAL_GATEWAY', gateway) + vi.stubEnv('FAUNOSTEO_TRIAL_HOST', HOST) + vi.stubEnv('VITE_SUPABASE_URL', `http://${HOST}:${appPort}`) + vi.stubEnv('VITE_SUPABASE_ANON_KEY', key(iss)) +} +const resolveOn = (port: number) => + resolveConfig( + { configFile: CONFIG, server: { host: HOST, port, strictPort: true } }, + 'serve', + ) +const proxyTargets = (config: Awaited>) => + ROUTES.map((route) => { + const entry = config.server.proxy?.[route] + return typeof entry === 'string' ? entry : entry?.target + }) + +afterEach(() => { + vi.unstubAllEnvs() + vi.unstubAllGlobals() +}) + +describe('shared trial dev server config, as Vite resolves it', () => { + it('db:sandbox trial: proxies to 57801 on 5193, never probes', async () => { + const fetch = vi.fn() + vi.stubGlobal('fetch', fetch) + stubStack('http://127.0.0.1:57801', 5193, 'db-sandbox') + const config = await resolveOn(5193) + expect(proxyTargets(config)).toEqual(Array(3).fill('http://127.0.0.1:57801')) + expect(config.server.port).toBe(5193) + expect(fetch).not.toHaveBeenCalled() + }) + + it('db:trial app: proxies to 58801 on 5194 once the gateway names itself', async () => { + vi.stubGlobal('fetch', vi.fn(async () => new Response('faunosteo_trial\n'))) + stubStack('http://127.0.0.1:58801', 5194, 'faunosteo-trial') + const config = await resolveOn(5194) + expect(proxyTargets(config)).toEqual(Array(3).fill('http://127.0.0.1:58801')) + }) + + it('refuses the trial stack on the sandbox port', async () => { + vi.stubGlobal('fetch', vi.fn(async () => new Response('faunosteo_trial\n'))) + stubStack('http://127.0.0.1:58801', 5194, 'faunosteo-trial') + await expect(resolveOn(5193)).rejects.toThrow(/Refused/) + }) + + it('refuses a trial gateway that does not name itself', async () => { + vi.stubGlobal('fetch', vi.fn(async () => new Response('other\n'))) + stubStack('http://127.0.0.1:58801', 5194, 'faunosteo-trial') + await expect(resolveOn(5194)).rejects.toThrow(/does not answer/) + }) +}) + +describe('the sandbox values above are the ones scripts/db-sandbox.sh passes', () => { + it('keeps its trial gateway, app port, key issuer and the way it passes them to Vite', () => { + const script = readFileSync(SANDBOX_SCRIPT, 'utf8') + expect(script).toContain('PORT_TRIAL_GATEWAY=57801') + expect(script).toContain('PORT_TRIAL_APP=5193') + expect(script).toContain('iss: "db-sandbox"') + expect(script).toContain( + 'FAUNOSTEO_TRIAL_GATEWAY="http://127.0.0.1:$PORT_TRIAL_GATEWAY"', + ) + expect(script).toContain( + 'VITE_SUPABASE_URL="http://$TRIAL_HOST:$PORT_TRIAL_APP"', + ) + expect(script).toContain('--port $PORT_TRIAL_APP --strictPort') + }) +}) +``` + + +- [ ] **Step 6: checks**: `cd /home/bchanot/Documents/faunosteo-v1-2 && pnpm exec prettier --write + apps/app/vite/trial-targets.ts apps/app/vite/trial.config.ts apps/app/tests/unit/vite.trialTargets.test.ts + apps/app/tests/unit/vite.trialConfig.test.ts && + pnpm typecheck && pnpm lint && pnpm test:run && pnpm --filter @faunosteo/app exec tsc -p tsconfig.node.json + --noEmit`, all green (the last one compiles `vite/*.ts` under lib ES2022 + node types; it passes on the current + tree, checked 2026-11-10). `git diff --stat b215b89 -- scripts/db-sandbox.sh` + shows nothing from this lot. The real Vite start of either command is not run (owner brief); the first + `pnpm db:trial app` after the go, and the next `pnpm db:sandbox trial`, prove the async config and the port guard. + +- [ ] **Step 7: orchestrator commits** `fix(app): trial dev server serves exactly one known stack (R13)` + push. + +--- + +### Lot B1: db-trial.sh foundation, plan, create, start, stop, status; sandbox state guard; harness + +**Files:** +- Create: `scripts/db-trial.sh` (sections 1-6 below, in this order) +- Create: `scripts/db-trial-check.sh` (harness sections H1-H4) +- Modify: `scripts/db-sandbox.sh` after line 70 (guard only, additions only) +- Modify: `package.json` scripts (one line after `"db:sandbox"`): `"db:trial": "bash scripts/db-trial.sh",` + +**Interfaces:** +- Produces (used by B2, B3): `die`, `say`, `CONTAINERS`, `STOP_ORDER`, `STATE`, `SECRETS`, `CONF`, `MANIFEST`, + `BACKUPS`, `MARKER`, `LIVE_FILES`, `IMAGE_*`, `TR_PW TR_JWT_SECRET TR_ANON_KEY TR_SERVICE_KEY`, `parse_secrets + `, `load_secrets`, `parse_conf `, `load_conf`, `write_private ` (stdin → `.new` 600 → + `mv`), `remove_live_files`, `KEYGEN`, `new_secrets_file `, `KEYCHECK`, `key_check`, `key_identity`, `client_key`, + `require_trial_keys`, `published_exactly`, `gateway_identity`, `write_env_files`, `key_expiry`, + `daemon_ok`, `container_exists|container_running|volume_exists|network_exists `, `existing_resources`, + `port_of|limits_of|image_of|mount_of `, `port_listening `, `ports_free ...`, + `valid_host `, `trial_host`, `wait_for`, `db_ready `, `sb_psql [psql args]`, `run_service `, + `ensure_network`, `restart_gateway`, `start_containers` (starts stopped, recreates missing), `stop_containers`, + `remove_containers`, `check_loopback`, `require_state|require_created|require_running`, `refuse_while_app_runs`, + `take_lock`, `applied_versions`, `write_manifest`, `check_manifest`, `pending_migrations`, `expected_assets`, + `uploaded_count`, `inventory_counts`, `list_backups`. Harness: `new_case`, `trial` (stdin `/dev/null`), + `trial_input` (stdin from the caller), `trial_tty ` (pty), `pass/fail/check`, `changes`, `refused`, + `refused_early`, `secrets_absent`, `values_absent_from`, `run_line`, `expect_run`, `only_trial_names`, + `hold_port`, `release_port`. +- Every SQL text the script sends starts with a tag line `-- db-trial:` (the stub answers by tag). +- Identity checked per operation (R13, owner 2026-11-10; any failure refuses, never a fallback to another stack): + + | Operation | What must hold before it acts | + |---|---| + | `app` | `faunosteo_trial_gateway` running and `docker port` exactly `8000/tcp -> 127.0.0.1:58801`; `GET http://127.0.0.1:58801/__faunosteo_stack` answers exactly `faunosteo_trial`; the anon key passes `client_key … anon`; then Vite's own checks (lot A2) | + | `assets` | the same gateway checks; the service key passes `client_key … service_role` | + | `account` | `faunosteo_trial_auth` published exactly on `127.0.0.1:58999`; the service key passes `client_key … service_role` and is the one sent | + | `create` | `faunosteo_trial_db` published exactly on `127.0.0.1:58432` before `migrate_up` | + | `migrate` | `faunosteo_trial_db` published exactly on `127.0.0.1:58432`, before any backup | + | every `write_env_files` (create, start's recreation, restore, rotations) | both keys pass `key_identity` (no expiry) before any env file is written | + | `restore ` | the backup's keys pass `key_check … any` with the backup's own secret, before any change | + | `rotate-keys`, `rotate-secrets` | both keys pass `require_trial_keys` before the backup stops anything (refusal names `pnpm db:trial restore `); the backup just taken passes `check_backup` (checksums, archives, keys, image) before any key or secret changes | + | every command | DOCKER_HOST unset or `unix://…`, else the current context's endpoint `unix://…` (`require_local_daemon`); `plan` and `status` print it | + | every curl | `curl -q --noproxy '*'`: no `~/.curlrc`, no proxy variable; Vite starts with every proxy variable unset (`NODE_USE_ENV_PROXY` included); the upload tool already refuses proxies (`crates/core/src/bin/upload_sheet_assets/storage.rs:52-53`, `.proxy(None)`) | + + `key_identity `: issuer `faunosteo-trial`, the expected role, HMAC-SHA256 valid with `TR_JWT_SECRET` + (node, key and secret through its environment, never argv), expiry not checked: an expired key never blocks + `start` or `rotate-keys`. `client_key ` (app, assets, account) adds the expiry, with a message naming + `pnpm db:trial rotate-keys`; `status` reports expired keys. `rotate-keys` needs a created stack, running or + stopped. The `account` header is built from the checked key itself (no `service-header` file). + +- [ ] **Step 1: write the harness first** (H1-H4 below) and the db-sandbox.sh guard; run + `cd /home/bchanot/Documents/faunosteo-v1-2 && bash scripts/db-trial-check.sh`; expected: FAIL lines (db-trial.sh + missing), never a docker call outside the stubs. +- [ ] **Step 2: write `scripts/db-trial.sh` sections 1-6**, `chmod 755`, add the package.json line. +- [ ] **Step 3: run the harness until `db-trial-check: ALL PASS`**; fix the script, not the expectations, unless an + expectation contradicts this plan (report each such case). +- [ ] **Step 4: positive controls** (then revert each): remove `--restart no` from `base_opts` → the create checks + FAIL; change `127.0.0.1:$host` to `0.0.0.0:$host` → FAIL; delete the SANDBOX_* loop → FAIL; delete the + db-sandbox.sh guard → FAIL; drop the `daemon_ok` dispatch line → FAIL; drop the `command -v ss` dispatch line → + "ss absent from PATH" FAILS; drop `published_exactly "$DB"` from `cmd_create` → "create: Postgres published beyond + 127.0.0.1" FAILS; drop `realpath -m` from the STATE line → the state-symlink-repo, state-symlink-sandbox and state-symlink-ok cases + FAIL; drop `-q --noproxy '*'` from one `wait_service` curl → "create: every curl pinned" FAILS; drop + `require_local_daemon` from the dispatch → both endpoint cases FAIL; drop `refuse_while_app_runs` from `cmd_stop` → + "stop while port 5194 is in use" FAILS; + remove the `location = /__faunosteo_stack` line → "create: gateway names itself" FAILS. Report each failure. + If the harness stops with exit 2 (`cannot run while …`), the host holds a trial port or lacks memory: report it, + never stop a container to make room. +- [ ] **Step 5: `pnpm r5:import-equine --check`** (environment-free, compiles once) → exit 0, report its last line. +- [ ] **Step 6: orchestrator commits** `feat(supabase): db:trial foundation, plan, create, start, stop, status` + + push. + +#### db-sandbox.sh guard (insert after line 70, before `load_secrets`) + +```bash +# The db:trial state folder (scripts/db-trial.sh) is never the sandbox's: `down` would delete +# files there while the trial volumes keep the matching passwords. +TRIAL_STATE="$(realpath -m "${FAUNOSTEO_TRIAL_DIR:-$HOME/.cache/faunosteo-trial}")" +if [ "$(realpath -m "$STATE")" = "$TRIAL_STATE" ] || [ -e "$STATE/.faunosteo-trial-state" ]; then + die "FAUNOSTEO_SANDBOX_DIR is the db:trial state folder: refused, nothing was run" +fi +``` + +#### Section 1: header, constants, refusals + +```bash +#!/usr/bin/env bash +# Dedicated persistent manual trial stack (docs/development/TRIAL_STACK.md, SUPABASE.md §5.2): +# Postgres, GoTrue, PostgREST, Storage, Mailpit and a gateway under the literal names +# faunosteo_trial_*, published on 127.0.0.1 only, the data in two named volumes, secrets of its +# own. Nothing starts at boot. No automated suite reaches it: this script refuses a shell that +# carries SANDBOX_* variables, and the suites accept the sandbox's exact values only. +# +# pnpm db:trial plan read-only: what create would make, ports, places, limits, refusals +# pnpm db:trial create secrets, network, volumes, services, migrations, equine_draft.sql only +# pnpm db:trial start | stop the same containers, data kept +# pnpm db:trial status read-only: containers, keys, migrations, equine sheet, accounts, backups +# pnpm db:trial migrate a backup first (A15), then the branch's new migrations +# pnpm db:trial backup cold copy of both volumes and the secrets (the stack stops a few seconds) +# pnpm db:trial restore typed confirmation, a backup first, then 's volumes and secrets +# pnpm db:trial rotate-keys new anon and service keys signed with the same JWT secret, one year +# pnpm db:trial rotate-secrets a backup first, then a new JWT secret, keys and role passwords +# pnpm db:trial app the app on http://:5194; Ctrl+C stops it, the stack stays +# pnpm db:trial account a confirmed account, password at a hidden prompt (12 characters min.) +# pnpm db:trial grant +# pnpm db:trial assets the equine drawings through the trial gateway, then checked +# pnpm db:trial destroy inventory, typed confirmation, a backup, then containers, network, volumes +# +# State: $FAUNOSTEO_TRIAL_DIR (default ~/.cache/faunosteo-trial), 700, outside every git work tree: +# secrets.env and the services' env files (600, written whole then renamed), stack.conf (images), +# migrations.sha256, backups/ (never pruned here). No secret is printed, logged, written to the +# repository or put on a command line: containers read env files, tools their environment, psql its +# standard input. Never `docker inspect` a trial container without -f: it would print the env files. +# Typed confirmations need a terminal. Every command but plan needs a reachable Docker daemon. +set -euo pipefail +cd "$(dirname "$0")/.." +# shellcheck source=scripts/dev-env.sh +. scripts/dev-env.sh + +# Pinned here, apart from the sandbox: an image change on this persistent stack is a deliberate +# step. create records the images in stack.conf; every later recreation reuses the recorded ones. +IMAGE_DB=public.ecr.aws/supabase/postgres:17.11.0.004 +IMAGE_AUTH=public.ecr.aws/supabase/gotrue:v2.197.0 +IMAGE_REST=public.ecr.aws/supabase/postgrest:v16.4 +IMAGE_STORAGE=public.ecr.aws/supabase/storage-api:v1.79.36 +IMAGE_MAIL=public.ecr.aws/supabase/mailpit:v1.31.3 +IMAGE_GATEWAY=nginx:1.31-alpine +NET=faunosteo_trial_net +DB=faunosteo_trial_db +MAIL=faunosteo_trial_mail +AUTH=faunosteo_trial_auth +STORAGE=faunosteo_trial_storage +REST=faunosteo_trial_rest +GATEWAY=faunosteo_trial_gateway +HELPER=faunosteo_trial_helper +VOL_DB=faunosteo_trial_db +VOL_STORAGE=faunosteo_trial_storage +CONTAINERS=("$DB" "$MAIL" "$AUTH" "$STORAGE" "$REST" "$GATEWAY") +STOP_ORDER=("$GATEWAY" "$REST" "$STORAGE" "$AUTH" "$MAIL" "$DB") +PORT_DB=58432 PORT_AUTH=58999 PORT_REST=58300 PORT_STORAGE=58500 PORT_MAIL=58025 PORT_GATEWAY=58801 +PORT_APP=5194 +# The six caps add up to 1 920 MiB (TRIAL_STACK.md §3.7); about 650 MiB are used in practice. +MEMORY_FLOOR_MIB=2048 +SEED=supabase/seed/anatomical-sheets/equine/draft +HISTORICAL_SHEET=503dc301-a8b1-50d4-9e44-0919b2fc2916 +CLI=node_modules/.bin/supabase +# Canonical from the start (symlinks resolved): the guard, every mode check and every state path +# below read the real folder, never a link (whose own mode stat would report as 777). +STATE="$(realpath -m "${FAUNOSTEO_TRIAL_DIR:-$HOME/.cache/faunosteo-trial}")" +MARKER="$STATE/.faunosteo-trial-state" +SECRETS="$STATE/secrets.env" +CONF="$STATE/stack.conf" +MANIFEST="$STATE/migrations.sha256" +BACKUPS="$STATE/backups" +# Everything in the state folder but the marker, the lock and backups/: what destroy (and a create +# that died before its first resource) removes. +LIVE_FILES=(secrets.env secrets.next.env db.env auth.env storage.env rest.env stack.conf migrations.sha256) +JWT_RE='^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$' + +die() { echo "db-trial: $*" >&2; exit 1; } +say() { echo "== $*"; } +usage() { grep '^# pnpm db:trial' "$0" | cut -c2-; } + +# Refusals that come before anything else, whatever the command (TRIAL_STACK.md §3.6). +guard_environment() { + local name repo state sandbox parent + for name in $(compgen -e); do + case "$name" in + SANDBOX_*) die "$name is set: this shell is wired to the sandbox suites; open a clean shell (nothing was run)" ;; + esac + done + repo="$(realpath "$PWD")" + state="$STATE" + sandbox="$(realpath -m "${FAUNOSTEO_SANDBOX_DIR:-$HOME/.cache/faunosteo-db-sandbox}")" + case "$state" in + "$repo" | "$repo"/*) die "FAUNOSTEO_TRIAL_DIR must be outside the repository" ;; + esac + # Any git work tree, not only this one (the other checkout, a dotfiles repository): the secrets + # and backups would sit one `git add` away from a commit. + parent="$state" + while [ ! -e "$parent" ]; do parent="$(dirname "$parent")"; done + if git -C "$parent" rev-parse --is-inside-work-tree >/dev/null 2>&1; then + die "FAUNOSTEO_TRIAL_DIR must be outside every git work tree: refused" + fi + [ "$state" != "$sandbox" ] || die "FAUNOSTEO_TRIAL_DIR is the sandbox's state folder: refused" + if [ -e "$STATE" ] && [ ! -e "$MARKER" ] && [ -n "$(ls -A "$STATE" 2>/dev/null || echo unreadable)" ]; then + die "$STATE is not empty and holds no db:trial state: refused" + fi +} + +check_private() { # path mode + [ "$(stat -c %u "$1")" = "$(id -u)" ] && [ "$(stat -c %a "$1")" = "$2" ] \ + || die "$1 must belong to $(id -un) with mode $2: refused" +} +``` + +#### Section 2: state files (parsed, never sourced) + +```bash +# KEY=value lines, read without `source`: only these keys, each value checked against its shape. +parse_secrets() { # file → TR_PW TR_JWT_SECRET TR_ANON_KEY TR_SERVICE_KEY + local key value + TR_PW='' TR_JWT_SECRET='' TR_ANON_KEY='' TR_SERVICE_KEY='' + while IFS='=' read -r key value; do + case "$key" in + TR_PW) if [[ "$value" =~ ^[0-9a-f]{48}$ ]]; then TR_PW="$value"; fi ;; + TR_JWT_SECRET) if [[ "$value" =~ ^[0-9a-f]{64}$ ]]; then TR_JWT_SECRET="$value"; fi ;; + TR_ANON_KEY) if [[ "$value" =~ $JWT_RE ]]; then TR_ANON_KEY="$value"; fi ;; + TR_SERVICE_KEY) if [[ "$value" =~ $JWT_RE ]]; then TR_SERVICE_KEY="$value"; fi ;; + esac + done < "$1" + [ -n "$TR_PW" ] && [ -n "$TR_JWT_SECRET" ] && [ -n "$TR_ANON_KEY" ] && [ -n "$TR_SERVICE_KEY" ] +} +load_secrets() { + [ -f "$SECRETS" ] || die "not created: no $SECRETS (pnpm db:trial plan, then create)" + check_private "$SECRETS" 600 + parse_secrets "$SECRETS" || die "secrets.env is incomplete or malformed: nothing was run (pnpm db:trial restore )" +} + +# A state file is written whole under .new (600) then renamed: an interrupted write never +# leaves half a file behind the real name. Content on stdin (printf is a builtin: no argv). +write_private() { # file + ( umask 077; cat > "$1.new" ) && mv -f "$1.new" "$1" +} +remove_live_files() { # never backups/, the marker or the lock + local f + for f in "${LIVE_FILES[@]}"; do rm -f -- "$STATE/$f" "$STATE/$f.new"; done +} + +# The six IMAGE_* recorded at create. The app host is not recorded: `app` decides it at each run. +parse_conf() { # file + local key value seen=0 + while IFS='=' read -r key value; do + case "$key" in + IMAGE_DB | IMAGE_AUTH | IMAGE_REST | IMAGE_STORAGE | IMAGE_MAIL | IMAGE_GATEWAY) + if [[ "$value" =~ ^[a-z0-9./_-]+:[A-Za-z0-9._-]+$ ]]; then printf -v "$key" '%s' "$value"; seen=$((seen + 1)); fi ;; + esac + done < "$1" + [ "$seen" -eq 6 ] +} +load_conf() { + [ -f "$CONF" ] || die "not created: no $CONF (pnpm db:trial plan, then create)" + check_private "$CONF" 600 + parse_conf "$CONF" || die "stack.conf is incomplete or malformed: nothing was run (pnpm db:trial restore )" +} +write_conf() { + printf 'IMAGE_DB=%s\nIMAGE_AUTH=%s\nIMAGE_REST=%s\nIMAGE_STORAGE=%s\nIMAGE_MAIL=%s\nIMAGE_GATEWAY=%s\n' \ + "$IMAGE_DB" "$IMAGE_AUTH" "$IMAGE_REST" "$IMAGE_STORAGE" "$IMAGE_MAIL" "$IMAGE_GATEWAY" | write_private "$CONF" +} + +# Fresh values (`new`) or new keys for the current secret (`keys`, the secret in TR_JWT_SECRET), +# as KEY=value lines for a 600 file, never for the terminal. Keys: issuer faunosteo-trial (the +# sandbox suites refuse it), one year, a random jti so every rotation yields new keys. +KEYGEN=' +const c = require("crypto"); +const fresh = process.argv[1] === "new"; +const secret = fresh ? c.randomBytes(32).toString("hex") : process.env.TR_JWT_SECRET; +if (!/^[0-9a-f]{64}$/.test(secret || "")) process.exit(2); +const b64 = (o) => Buffer.from(JSON.stringify(o)).toString("base64url"); +const jwt = (p) => { const h = b64({ alg: "HS256", typ: "JWT" }), b = b64(p); + return h + "." + b + "." + c.createHmac("sha256", secret).update(h + "." + b).digest("base64url"); }; +const iat = Math.floor(Date.now() / 1000), exp = iat + 365 * 86400; +if (fresh) console.log("TR_PW=" + c.randomBytes(24).toString("hex") + "\nTR_JWT_SECRET=" + secret); +for (const [name, role] of [["TR_ANON_KEY", "anon"], ["TR_SERVICE_KEY", "service_role"]]) + console.log(name + "=" + jwt({ role, iss: "faunosteo-trial", iat, exp, jti: c.randomUUID() })); +' +new_secrets_file() { ( umask 077; node -e "$KEYGEN" new > "$1" ); } +# A key is handed over (Vite, the upload tool, GoTrue's admin API, Storage's env) only when it is +# this stack's: issuer faunosteo-trial, the role asked, not expired, signed with TR_JWT_SECRET. +# Exit 0: this stack's key; 1: not this stack's (issuer, role, signature); 3 (mode fresh only): +# this stack's but expired. Identity and expiry are apart on purpose: an expired key must never +# block start or rotate-keys (the way to renew it), only its use by a client. +KEYCHECK=' +const c = require("crypto"); +const [role, mode] = process.argv.slice(1); +const [h, b, s] = (process.env.KEY || "").split("."); +let p = null; +try { p = JSON.parse(Buffer.from(b, "base64url").toString("utf8")); } catch { process.exit(1); } +const mac = c.createHmac("sha256", process.env.SECRET || "").update(h + "." + b).digest("base64url"); +const own = p !== null && typeof p === "object" && s === mac && p.iss === "faunosteo-trial" + && p.role === role && typeof p.exp === "number"; +if (!own) process.exit(1); +process.exit(mode === "fresh" && p.exp <= Date.now() / 1000 ? 3 : 0); +' +key_check() { # key role any|fresh [secret]: the status of KEYCHECK + KEY="$1" SECRET="${4:-$TR_JWT_SECRET}" node -e "$KEYCHECK" "$2" "$3" +} +key_identity() { # key role: this stack's key, expired or not (env files, Storage) + key_check "$1" "$2" any \ + || die "the $2 key in secrets.env is not this stack's (issuer faunosteo-trial, signed with its secret): refused, nothing was done (pnpm db:trial restore )" +} +client_key() { # key role: what a client receives (Vite, the upload tool, GoTrue's admin API) is also valid now + local status=0 + key_check "$1" "$2" fresh || status=$? + case "$status" in + 0) ;; + 3) die "the $2 key expired: pnpm db:trial rotate-keys renews it; nothing was done" ;; + *) die "the $2 key in secrets.env is not this stack's (issuer faunosteo-trial, signed with its secret): refused, nothing was done (pnpm db:trial restore )" ;; + esac +} +require_trial_keys() { + key_identity "$TR_ANON_KEY" anon + key_identity "$TR_SERVICE_KEY" service_role +} +key_expiry() { + TR_ANON_KEY="$TR_ANON_KEY" node -e ' + const p = JSON.parse(Buffer.from(process.env.TR_ANON_KEY.split(".")[1], "base64url")); + console.log(new Date(p.exp * 1000).toISOString().slice(0, 10));' +} + +# The values reach the containers through 600 env files, never through argv. Always derived from +# secrets.env, so they can be rewritten at any time (start rewrites them before recreating a +# missing container). Both keys are this stack's first. +write_env_files() { + require_trial_keys + printf 'POSTGRES_PASSWORD=%s\nPGPASSWORD=%s\nJWT_SECRET=%s\n' "$TR_PW" "$TR_PW" "$TR_JWT_SECRET" \ + | write_private "$STATE/db.env" + printf 'GOTRUE_DB_DATABASE_URL=postgresql://supabase_auth_admin:%s@%s:5432/postgres\nGOTRUE_JWT_SECRET=%s\n' \ + "$TR_PW" "$DB" "$TR_JWT_SECRET" | write_private "$STATE/auth.env" + printf 'ANON_KEY=%s\nSERVICE_KEY=%s\nAUTH_JWT_SECRET=%s\nDATABASE_URL=postgresql://supabase_storage_admin:%s@%s:5432/postgres\n' \ + "$TR_ANON_KEY" "$TR_SERVICE_KEY" "$TR_JWT_SECRET" "$TR_PW" "$DB" | write_private "$STATE/storage.env" + printf 'PGRST_DB_URI=postgresql://authenticator:%s@%s:5432/postgres\nPGRST_JWT_SECRET=%s\n' \ + "$TR_PW" "$DB" "$TR_JWT_SECRET" | write_private "$STATE/rest.env" +} +``` + +#### Section 3: host checks, Docker helpers, services + +```bash +# The daemon this script talks to is the local one: DOCKER_HOST unset or a unix socket, else the +# current context's endpoint a unix socket (a named, non-secret field of the context). +daemon_endpoint() { + if [ -n "${DOCKER_HOST:-}" ]; then printf '%s' "$DOCKER_HOST" + else docker context inspect -f '{{.Endpoints.docker.Host}}' 2>/dev/null; fi +} +require_local_daemon() { + local endpoint + endpoint="$(daemon_endpoint)" || die "the current Docker context cannot be read: refused, nothing was run" + case "$endpoint" in + unix://?*) ;; + *) die "the Docker endpoint '$endpoint' is not a local unix socket (DOCKER_HOST or the current context): refused, nothing was run" ;; + esac +} +# Checked at dispatch for every command but plan: past it, "absent" means absent, not "daemon down". +daemon_ok() { docker info --format '{{.ServerVersion}}' >/dev/null 2>&1; } +# Always -f with a named field: a bare inspect prints the containers' env-file values. +container_exists() { docker container inspect -f '{{.Name}}' "$1" >/dev/null 2>&1; } +container_running() { [ "$(docker container inspect -f '{{.State.Running}}' "$1" 2>/dev/null)" = true ]; } +volume_exists() { docker volume inspect -f '{{.Name}}' "$1" >/dev/null 2>&1; } +network_exists() { docker network inspect -f '{{.Name}}' "$1" >/dev/null 2>&1; } +existing_resources() { # the literal names of this stack that exist now, one per line + local name + for name in "${CONTAINERS[@]}"; do if container_exists "$name"; then echo "container $name"; fi; done + if network_exists "$NET"; then echo "network $NET"; fi + for name in "$VOL_DB" "$VOL_STORAGE"; do if volume_exists "$name"; then echo "volume $name"; fi; done +} + +port_of() { # name → host port, container port + case "$1" in + "$DB") echo "$PORT_DB 5432" ;; "$MAIL") echo "$PORT_MAIL 8025" ;; "$AUTH") echo "$PORT_AUTH 9999" ;; + "$STORAGE") echo "$PORT_STORAGE 5000" ;; "$REST") echo "$PORT_REST 3000" ;; "$GATEWAY") echo "$PORT_GATEWAY 8000" ;; + esac +} +limits_of() { # name → memory, pids (TRIAL_STACK.md §3.7; --cpus 1 for all) + case "$1" in + "$DB") echo "1g 512" ;; "$REST") echo "384m 256" ;; "$STORAGE") echo "256m 256" ;; + "$AUTH") echo "128m 256" ;; "$MAIL" | "$GATEWAY") echo "64m 64" ;; + esac +} +image_of() { + case "$1" in + "$DB") echo "$IMAGE_DB" ;; "$MAIL") echo "$IMAGE_MAIL" ;; "$AUTH") echo "$IMAGE_AUTH" ;; + "$STORAGE") echo "$IMAGE_STORAGE" ;; "$REST") echo "$IMAGE_REST" ;; "$GATEWAY") echo "$IMAGE_GATEWAY" ;; + esac +} +mount_of() { + case "$1" in + "$DB") echo "$VOL_DB:/var/lib/postgresql/data" ;; "$STORAGE") echo "$VOL_STORAGE:/mnt" ;; *) echo - ;; + esac +} +# What every service container shares: its name, the stack network, no restart at boot, its caps +# and its one loopback port. +base_opts() { # name → one option per line + local host inner memory pids + read -r host inner <<<"$(port_of "$1")" + read -r memory pids <<<"$(limits_of "$1")" + printf '%s\n' --name "$1" --network "$NET" --restart no --memory "$memory" --cpus 1 \ + --pids-limit "$pids" -p "127.0.0.1:$host:$inner" +} + +# True when any local address listens on the port (rootless Docker's forwarders show in ss too, +# checked 2026-11-10). Fails closed: no ss answer, no command goes on. +port_listening() { # port + local out status=0 + out="$(ss -Hltn "sport = :$1" 2>&1)" || status=$? + # Fail closed: an ss error is never read as "nothing listens". + [ "$status" -eq 0 ] || die "ss cannot list the listening ports (exit $status): nothing was done" + [ -n "$out" ] +} +ports_free() { # container...: each one's host port, all checked before any docker call + local name host inner + for name in "$@"; do + read -r host inner <<<"$(port_of "$name")" + if port_listening "$host"; then die "port 127.0.0.1:$host is taken: nothing was started or changed (pnpm db:trial plan)"; fi + done +} +available_mib() { awk '/^MemAvailable:/ { print int($2 / 1024) }' /proc/meminfo; } +memory_ok() { + local mib + mib="$(available_mib)" + [ "$mib" -ge "$MEMORY_FLOOR_MIB" ] || die "only $mib MiB of memory available, the stack's caps need $MEMORY_FLOOR_MIB: nothing was started" +} + +# The trial app host: loopback or a private IPv4 of an interface of this machine, nothing else +# (same rule as db-sandbox.sh trial_host). Prints the normalised address. +valid_host() { # address + local host="$1" a b c d + [[ "$host" =~ ^([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})$ ]] \ + || die "FAUNOSTEO_TRIAL_HOST must be an IPv4 address (not a name, not 0.0.0.0): $host" + a=$((10#${BASH_REMATCH[1]})) b=$((10#${BASH_REMATCH[2]})) + c=$((10#${BASH_REMATCH[3]})) d=$((10#${BASH_REMATCH[4]})) + [ "$a" -le 255 ] && [ "$b" -le 255 ] && [ "$c" -le 255 ] && [ "$d" -le 255 ] \ + || die "FAUNOSTEO_TRIAL_HOST is not an IPv4 address: $host" + [ "$host" = "$a.$b.$c.$d" ] || die "FAUNOSTEO_TRIAL_HOST: write the address without leading zeros" + if [ "$a" -eq 127 ]; then host=127.0.0.1 + elif [ "$a" -eq 10 ] || { [ "$a" -eq 172 ] && [ "$b" -ge 16 ] && [ "$b" -le 31 ]; } \ + || { [ "$a" -eq 192 ] && [ "$b" -eq 168 ]; }; then : + else die "FAUNOSTEO_TRIAL_HOST must be loopback or a private address (10/8, 172.16/12, 192.168/16): $host" + fi + ip -4 -o addr | grep -qF "inet $host/" || die "FAUNOSTEO_TRIAL_HOST $host is not an address of this machine" + printf '%s' "$host" +} +# Decided at each use, never recorded: a DHCP change of the LAN address needs no state edit. Call +# it as `host="$(trial_host)"` (a plain assignment, so a refusal stops the script). +trial_host() { valid_host "${FAUNOSTEO_TRIAL_HOST:-$FAUNOSTEO_DEV_HOST}"; } + +wait_for() { # what command... + local what="$1" + shift + for _ in $(seq 1 120); do + if "$@" >/dev/null 2>&1; then return 0; fi + sleep 1 + done + die "timeout waiting for $what" +} +# psql inside the database container; the password reaches it through the environment. +db_ready() { # role + PGPASSWORD="$TR_PW" docker exec -e PGPASSWORD "$DB" psql -X -h 127.0.0.1 -U "$1" -d postgres -c 'select 1' +} +sb_psql() { + PGPASSWORD="$TR_PW" docker exec -i -e PGPASSWORD "$DB" \ + psql -X -q -h 127.0.0.1 -U postgres -d postgres -v ON_ERROR_STOP=1 "$@" +} + +# The role passwords the CLI sets at its first database start (/etc/postgresql.schema.sql, run +# once on an empty data folder), for the roles this stack uses, supabase_admin included so that +# rotate-secrets can renew every password through it. A failing ALTER would log its statement, +# password included, at the default log_min_error_statement: the session turns that off first. +# shellcheck disable=SC2016 +DB_INIT='cat <<'"'"'EOF'"'"' > /etc/postgresql.schema.sql && exec docker-entrypoint.sh postgres -D /etc/postgresql -c shared_buffers=128MB +set log_min_error_statement = panic; +\set pgpass `echo "$PGPASSWORD"` +\set jwt_secret `echo "$JWT_SECRET"` +ALTER DATABASE postgres SET "app.settings.jwt_secret" TO :'"'"'jwt_secret'"'"'; +ALTER DATABASE postgres SET "app.settings.jwt_exp" TO '"'"'3600'"'"'; +ALTER USER supabase_admin WITH PASSWORD :'"'"'pgpass'"'"'; +ALTER USER postgres WITH PASSWORD :'"'"'pgpass'"'"'; +ALTER USER authenticator WITH PASSWORD :'"'"'pgpass'"'"'; +ALTER USER supabase_auth_admin WITH PASSWORD :'"'"'pgpass'"'"'; +ALTER USER supabase_storage_admin WITH PASSWORD :'"'"'pgpass'"'"'; +EOF' + +# The CLI stack's Kong routes on the trial network. GoTrue's admin API is not routed: the account +# command calls GoTrue on its loopback port, so the app's LAN proxy never reaches it. The static +# /__faunosteo_stack answer names this gateway (R13: app, assets and the trial Vite config check +# it); it carries no data, and Vite proxies only the three Supabase routes, so the LAN never sees it. +GATEWAY_CONF='server { + listen 8000; + client_max_body_size 8m; + proxy_http_version 1.1; + location = /__faunosteo_stack { default_type text/plain; return 200 "faunosteo_trial\n"; } + location /auth/v1/admin/ { return 403; } + location /auth/v1/ { proxy_pass http://'"$AUTH"':9999/; } + location /rest/v1/ { proxy_pass http://'"$REST"':3000/; } + location /storage/v1/ { proxy_pass http://'"$STORAGE"':5000/; } + location / { return 404; } +}' + +# Every curl of this script: -q first (no ~/.curlrc: no proxy, connect-to or resolve from it) and +# --noproxy '*' (no http_proxy / ALL_PROXY): the destination is the literal 127.0.0.1 port, always. +wait_service() { # name + case "$1" in + "$DB") + wait_for "database roles" db_ready supabase_auth_admin + wait_for "database" db_ready postgres ;; + "$MAIL") wait_for "mailpit" curl -q --noproxy '*' -fsS -o /dev/null "http://127.0.0.1:$PORT_MAIL/" ;; + "$AUTH") wait_for "auth" curl -q --noproxy '*' -fsS -o /dev/null "http://127.0.0.1:$PORT_AUTH/health" ;; + "$STORAGE") wait_for "storage" curl -q --noproxy '*' -fsS -o /dev/null "http://127.0.0.1:$PORT_STORAGE/status" ;; + "$REST") wait_for "postgrest" curl -q --noproxy '*' -fsS -o /dev/null "http://127.0.0.1:$PORT_REST/" ;; + "$GATEWAY") wait_for "gateway" curl -q --noproxy '*' -fsS -o /dev/null "http://127.0.0.1:$PORT_GATEWAY/rest/v1/" ;; + esac +} + +run_db() { + local opts + mapfile -t opts < <(base_opts "$DB") + docker run -d "${opts[@]}" -v "$(mount_of "$DB")" --env-file "$STATE/db.env" \ + -e POSTGRES_HOST=/var/run/postgresql -e JWT_EXP=3600 \ + -e POSTGRES_INITDB_ARGS="--allow-group-access --locale-provider=icu --encoding=UTF-8 --icu-locale=en_US.UTF-8" \ + --entrypoint sh "$IMAGE_DB" -c "$DB_INIT" >/dev/null +} +run_mail() { + local opts + mapfile -t opts < <(base_opts "$MAIL") + docker run -d "${opts[@]}" "$IMAGE_MAIL" >/dev/null +} +# Sign-up closed (accounts come from `account` only); mail links lead to the app origin of the +# trial host at the time GoTrue starts (create, restore, rotate-secrets, a recreation by start), +# whose proxy forwards /auth/v1 to GoTrue. +run_auth() { + local opts host origin + host="$(trial_host)" + origin="http://$host:$PORT_APP" + mapfile -t opts < <(base_opts "$AUTH") + docker run -d "${opts[@]}" --env-file "$STATE/auth.env" \ + -e GOTRUE_API_HOST=0.0.0.0 -e GOTRUE_API_PORT=9999 -e API_EXTERNAL_URL="$origin/auth/v1" \ + -e GOTRUE_DB_DRIVER=postgres -e GOTRUE_DB_MIGRATIONS_PATH=/usr/local/etc/auth/migrations \ + -e GOTRUE_SITE_URL="$origin" -e GOTRUE_URI_ALLOW_LIST="$origin/**" -e GOTRUE_DISABLE_SIGNUP=true \ + -e GOTRUE_JWT_EXP=3600 -e GOTRUE_JWT_AUD=authenticated -e GOTRUE_JWT_DEFAULT_GROUP_NAME=authenticated \ + -e GOTRUE_JWT_ADMIN_ROLES=service_role \ + -e GOTRUE_EXTERNAL_EMAIL_ENABLED=true -e GOTRUE_EXTERNAL_PHONE_ENABLED=false \ + -e GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED=false -e GOTRUE_MAILER_AUTOCONFIRM=false \ + -e GOTRUE_MAILER_URLPATHS_CONFIRMATION="$origin/auth/v1/verify" \ + -e GOTRUE_SMTP_HOST="$MAIL" -e GOTRUE_SMTP_PORT=1025 \ + -e GOTRUE_SMTP_ADMIN_EMAIL=admin@trial.local -e GOTRUE_SMTP_SENDER_NAME=faunosteo-trial \ + -e GOTRUE_PASSWORD_MIN_LENGTH=12 "$IMAGE_AUTH" >/dev/null +} +run_storage() { + local opts + mapfile -t opts < <(base_opts "$STORAGE") + docker run -d "${opts[@]}" -v "$(mount_of "$STORAGE")" --env-file "$STATE/storage.env" \ + -e FILE_SIZE_LIMIT=52428800 -e STORAGE_BACKEND=file -e FILE_STORAGE_BACKEND_PATH=/mnt \ + -e TENANT_ID=stub -e STORAGE_S3_REGION=local -e GLOBAL_S3_BUCKET=stub \ + -e ENABLE_IMAGE_TRANSFORMATION=false -e IMAGE_TRANSFORMATION_ENABLED=false \ + -e S3_PROTOCOL_ENABLED=false -e DB_MIGRATIONS_FREEZE_AT= "$IMAGE_STORAGE" >/dev/null +} +run_rest() { + local opts + mapfile -t opts < <(base_opts "$REST") + docker run -d "${opts[@]}" --env-file "$STATE/rest.env" \ + -e PGRST_DB_SCHEMAS=public -e PGRST_DB_EXTRA_SEARCH_PATH=public,extensions \ + -e PGRST_DB_ANON_ROLE=anon -e PGRST_DB_MAX_ROWS=1000 "$IMAGE_REST" >/dev/null +} +run_gateway() { + local opts + mapfile -t opts < <(base_opts "$GATEWAY") + # "$0" is the inner shell's, expanded in the container: + # shellcheck disable=SC2016 + docker run -d "${opts[@]}" --security-opt no-new-privileges:true \ + --entrypoint sh "$IMAGE_GATEWAY" -c 'printf "%s\n" "$0" > /etc/nginx/conf.d/default.conf && exec nginx -g "daemon off;"' \ + "$GATEWAY_CONF" >/dev/null +} +run_service() { # name: run, then wait until it answers + case "$1" in + "$DB") run_db ;; "$MAIL") run_mail ;; "$AUTH") run_auth ;; + "$STORAGE") run_storage ;; "$REST") run_rest ;; "$GATEWAY") run_gateway ;; + esac + wait_service "$1" +} + +published_exactly() { # name: its one port, on 127.0.0.1, and nothing else + local host inner + read -r host inner <<<"$(port_of "$1")" + [ "$(docker port "$1" 2>/dev/null)" = "$inner/tcp -> 127.0.0.1:$host" ] \ + || die "$1 is not published on 127.0.0.1:$host only: refused (pnpm db:trial stop, then check Docker)" +} +check_loopback() { + local name + for name in "${CONTAINERS[@]}"; do published_exactly "$name"; done +} +# The gateway a tool or the app is pointed at is this stack's container, on its port, answering +# its name; never another local service on 58801. +STACK_IDENTITY=faunosteo_trial +gateway_identity() { + local body + published_exactly "$GATEWAY" + body="$(curl -q --noproxy '*' -fsS --max-time 3 "http://127.0.0.1:$PORT_GATEWAY/__faunosteo_stack" 2>/dev/null)" || body='' + [ "$body" = "$STACK_IDENTITY" ] \ + || die "127.0.0.1:$PORT_GATEWAY does not answer as the faunosteo_trial gateway: refused, nothing was done" +} +ensure_network() { + if ! network_exists "$NET"; then docker network create --label faunosteo.stack=trial "$NET" >/dev/null; fi +} +# nginx resolves the services' names once, at its start: a service started or recreated under a +# running gateway means a gateway restart. +restart_gateway() { + docker restart -t 10 "$GATEWAY" >/dev/null + wait_service "$GATEWAY" +} +# Every port of a stopped or missing container is checked before the first start. A missing +# container is recreated from stack.conf and secrets.env (env files rewritten first), so a failed +# recreation (rotate-keys, restore, a daemon hiccup) is repaired by `start`, never by a restore. +start_containers() { + local name todo=() missing=no + for name in "${CONTAINERS[@]}"; do + if container_running "$name"; then continue; fi + todo+=("$name") + if ! container_exists "$name"; then missing=yes; fi + done + ports_free "${todo[@]}" + if [ "$missing" = yes ]; then write_env_files; ensure_network; fi + for name in "${todo[@]}"; do + if container_exists "$name"; then + docker start "$name" >/dev/null + wait_service "$name" + else + run_service "$name" + fi + done + # CONTAINERS ends with the gateway: when it was not started last, it ran over the others. + if [ "${#todo[@]}" -gt 0 ] && [ "${todo[-1]}" != "$GATEWAY" ]; then restart_gateway; fi + check_loopback +} +stop_containers() { + local name + for name in "${STOP_ORDER[@]}"; do + if container_running "$name"; then docker stop -t 60 "$name" >/dev/null; fi + done +} +remove_containers() { # stopped first by the caller; volumes untouched + local name + for name in "${CONTAINERS[@]}"; do + if container_exists "$name"; then docker rm "$name" >/dev/null; fi + done +} + +require_state() { + [ -e "$MARKER" ] || die "no db:trial state in $STATE (pnpm db:trial plan, then create)" + check_private "$STATE" 700 +} +# The data volume is the stack: containers can be recreated (start), the volume cannot. +require_created() { + require_state + load_conf + load_secrets + volume_exists "$VOL_DB" || die "$VOL_DB does not exist (pnpm db:trial status)" +} +require_running() { + local name + require_created + for name in "${CONTAINERS[@]}"; do + container_running "$name" || die "$name is not running (pnpm db:trial start)" + done +} +# Before the commands that change keys or data under a running app (rotate-keys, rotate-secrets, +# restore, destroy) and before stop (the app would proxy to whatever then answers 58801). A local +# listener check: no probe of a LAN address. +refuse_while_app_runs() { + if port_listening "$PORT_APP"; then + die "port $PORT_APP is in use (the trial app, or another process): stop it first; nothing was changed" + fi +} +take_lock() { + exec 9>"$STATE/.lock" + flock -n 9 || die "another pnpm db:trial command is running" +} +``` + +#### Section 4: migrations and the equine seed + +```bash +db_url() { printf 'postgresql://postgres@127.0.0.1:%s/postgres?sslmode=disable' "$PORT_DB"; } +# The CLI's own runner, always against the trial URL; the password through PGPASSWORD only. +migrate_up() { PGPASSWORD="$TR_PW" "$CLI" --workdir . migration up --db-url "$(db_url)"; } +applied_versions() { + sb_psql -t -A -c "-- db-trial:applied +select version from supabase_migrations.schema_migrations order by version" +} +file_version() { basename "$1" | cut -d_ -f1; } +file_sum() { sha256sum < "$1" | cut -d' ' -f1; } +# One line per applied migration: version, sha256 of its file, file name. A persistent stack +# replays nothing, so an applied file edited later must be noticed (TRIAL_STACK.md §3.4). +write_manifest() { + local applied f + applied="$(applied_versions)" + ( umask 077 + for f in supabase/migrations/*.sql; do + if grep -qx "$(file_version "$f")" <<<"$applied"; then + printf '%s %s %s\n' "$(file_version "$f")" "$(file_sum "$f")" "$(basename "$f")" + fi + done > "$MANIFEST.new" ) + [ "$(cut -d' ' -f1 "$MANIFEST.new")" = "$applied" ] \ + || die "an applied migration has no file in this branch: migrations.sha256 not written" + mv -f "$MANIFEST.new" "$MANIFEST" +} +check_manifest() { + local version sum file + [ -f "$MANIFEST" ] || die "migrations.sha256 missing: the applied migrations cannot be checked (pnpm db:trial restore )" + while read -r version sum file; do + [[ "$version" =~ ^[0-9]{14}$ && "$sum" =~ ^[0-9a-f]{64}$ && "$file" =~ ^[0-9]{14}_[A-Za-z0-9_]+\.sql$ ]] \ + || die "migrations.sha256 is malformed" + [ -f "supabase/migrations/$file" ] || die "applied migration $file is missing from this branch: refused" + [ "$(file_sum "supabase/migrations/$file")" = "$sum" ] \ + || die "applied migration $file was edited after it was applied: refused (migrations are forward-only)" + done < "$MANIFEST" + [ "$(cut -d' ' -f1 "$MANIFEST")" = "$(applied_versions)" ] \ + || die "the database's migration history differs from migrations.sha256 (a migrate stopped part-way?): refused; pnpm db:trial restore (pnpm db:trial status lists them)" +} +# Kept although `migration up` would refuse too: this refusal comes before migrate's cold backup +# and its stop/start of the stack. +pending_migrations() { # the branch's files not applied yet; refuses one older than the last applied + local last f + last="$(tail -n 1 "$MANIFEST" | cut -d' ' -f1)" + for f in supabase/migrations/*.sql; do + if grep -q "^$(file_version "$f") " "$MANIFEST"; then continue; fi + [ "$(file_version "$f")" \> "$last" ] || die "$(basename "$f") is older than the last applied migration $last: refused" + basename "$f" + done +} + +# The seed folder's own consistency: sheet id, every drawing's size and sha256 against +# assets.json, both declared by equine_draft.sql. Prints "sha256 size" per drawing. +SEED_CHECK=' +const fs = require("fs"), path = require("path"), c = require("crypto"); +const [dir, sheet] = process.argv.slice(1); +const fail = (why) => { console.error(why); process.exit(1); }; +const ref = JSON.parse(fs.readFileSync(path.join(dir, "sheet-ref.json"), "utf8")); +const assets = JSON.parse(fs.readFileSync(path.join(dir, "assets.json"), "utf8")); +const seed = fs.readFileSync(path.join(dir, "equine_draft.sql"), "utf8"); +if (ref.sheet_id !== sheet || !seed.includes(sheet)) fail("the seed does not name the historical sheet"); +if (!Array.isArray(assets) || assets.length === 0) fail("assets.json lists no drawing"); +for (const a of assets) { + if (!/^[0-9a-f]{64}$/.test(a.sha256) || !Number.isInteger(a.byte_size)) fail("assets.json entry malformed"); + const bytes = fs.readFileSync(path.join(dir, "assets", path.basename(String(a.file)))); + if (bytes.length !== a.byte_size || c.createHash("sha256").update(bytes).digest("hex") !== a.sha256) + fail(a.file + " differs from assets.json"); + if (!seed.includes(a.sha256)) fail("equine_draft.sql does not declare " + a.file); + console.log(a.sha256 + " " + a.byte_size); +} +' +check_seed_sources() { + node -e "$SEED_CHECK" "$SEED" "$HISTORICAL_SHEET" >/dev/null || die "the equine seed folder fails its own hashes: nothing was created" +} +expected_assets() { node -e "$SEED_CHECK" "$SEED" "$HISTORICAL_SHEET" | LC_ALL=C sort; } +# The Rust pipeline regenerates the seed from the legacy sources and compares it byte for byte +# (R5.6 fingerprint convention): what is loaded is what the pipeline produces. Both checks stay: +# check_seed_sources (folder vs its own hashes, cheap, also in plan) then this one (folder vs +# pipeline); verify_equine_db then checks the database against the folder. +check_seed_pipeline() { + say "equine seed: the Rust pipeline regenerates it and compares (the first run compiles)" + ( unset INIT_CWD; bash scripts/import-equine.sh --check ) \ + || die "the equine seed differs from what the pipeline produces: nothing was created" +} +seed_equine() { sb_psql --single-transaction < "$SEED/equine_draft.sql" >/dev/null; } +asset_rows() { + sb_psql -t -A -c "-- db-trial:asset-rows +select sha256 || ' ' || byte_size from public.anatomical_sheet_assets +where sheet_id = private.historical_sheet_id() order by sha256 collate \"C\"" +} +uploaded_count() { + sb_psql -t -A -c "-- db-trial:assets-uploaded +select count(*) from public.anatomical_sheet_assets a +where a.sheet_id = private.historical_sheet_id() and a.uploaded_at is not null + and exists (select 1 from storage.objects o + where o.bucket_id = 'anatomical-sheet-assets' and o.name = a.sha256 || '.svg')" +} +# Right after the seed: the historical sheet is the only official one, its single version is a +# draft equal to document.json (jsonb equality, so the canonical fingerprint recorded in +# sheet-ref.json holds), its drawing rows match assets.json, and no account exists. +# A dollar-quote tag, never expanded: +# shellcheck disable=SC2016 +DOC_TAG='$faunosteo_trial_doc$' +verify_equine_db() { + local got want="official=1 historical=1 versions=1 draft_equal=true accounts=0" + ! grep -qF "$DOC_TAG" "$SEED/document.json" || die "document.json contains $DOC_TAG: cannot compare" + got="$( { cat <<'SQL' +-- db-trial:equine +select concat_ws(' ', + 'official=' || (select count(*) from public.anatomical_sheets where is_official), + 'historical=' || (select count(*) from public.anatomical_sheets s + where s.id = private.historical_sheet_id() and s.id = :'sheet'::uuid and s.is_official), + 'versions=' || (select count(*) from public.anatomical_sheet_versions v + where v.sheet_id = private.historical_sheet_id()), + 'draft_equal=' || coalesce((select (v.content = +SQL + printf '%s' "$DOC_TAG" + cat "$SEED/document.json" + printf '%s' "$DOC_TAG" + cat <<'SQL' +::jsonb)::text from public.anatomical_sheet_versions v + where v.sheet_id = private.historical_sheet_id() and v.status = 'draft'), 'none'), + 'accounts=' || (select count(*) from auth.users)); +SQL + } | sb_psql -t -A -v sheet="$HISTORICAL_SHEET")" + [ "$got" = "$want" ] || die "the equine sheet in the database is not the seed's ($got; expected $want)" + [ "$(asset_rows)" = "$(expected_assets)" ] || die "the equine drawing rows differ from assets.json" + say "equine sheet loaded: $got; drawing rows match assets.json" +} +inventory_counts() { + sb_psql -t -A -F ': ' <<'SQL' +-- db-trial:inventory +select 'accounts', count(*) from auth.users +union all select 'official sheets', count(*) from public.anatomical_sheets where is_official +union all select 'sheet versions', count(*) from public.anatomical_sheet_versions +union all select 'workspaces', count(*) from public.workspaces; +SQL +} +list_backups() { # a folder without SHA256SUMS never finished: listed, marked, never restored + local dir kind + say "backups in $BACKUPS" + [ -d "$BACKUPS" ] || return 0 + for dir in "$BACKUPS"/*/; do + [ -d "$dir" ] || continue + if [ -f "$dir/SHA256SUMS" ]; then kind=complete; else kind=incomplete; fi + printf ' %s %s %s\n' "$(basename "$dir")" "$(du -sh "$dir" | cut -f1)" "$kind" + done +} +``` + +#### Section 5: plan, create, start, stop, status + +```bash +cmd_plan() { + [ $# -eq 0 ] || die "plan takes no argument" + local refusals=() name host inner memory pids vol image root owner where mib + say "db:trial plan: read-only, nothing is created, started or changed" + echo "Docker endpoint: $(daemon_endpoint) (a local unix socket, checked at dispatch)" + if daemon_ok; then echo "Docker daemon: reachable" + else refusals+=("the Docker daemon is unreachable (every Docker answer below is unknown)"); fi + echo "Containers (network $NET, restart policy no, --cpus 1):" + for name in "${CONTAINERS[@]}"; do + read -r host inner <<<"$(port_of "$name")" + read -r memory pids <<<"$(limits_of "$name")" + printf ' %-24s %-46s 127.0.0.1:%s -> %-5s --memory %-5s --pids-limit %-4s volume %s\n' \ + "$name" "$(image_of "$name")" "$host" "$inner" "$memory" "$pids" "$(mount_of "$name")" + if container_exists "$name"; then refusals+=("container $name already exists"); fi + done + echo " $HELPER (create's image check, backup, restore, destroy only): --rm, --network none, image $IMAGE_DB" + echo "Network: $NET" + if network_exists "$NET"; then refusals+=("network $NET already exists"); fi + root="$(docker info --format '{{.DockerRootDir}}' 2>/dev/null || echo '')" + echo "Volumes:" + for vol in "$VOL_DB" "$VOL_STORAGE"; do + printf ' %-24s %s/volumes/%s/_data\n' "$vol" "$root" "$vol" + if volume_exists "$vol"; then refusals+=("volume $vol already exists"); fi + done + echo "Images:" + for image in "$IMAGE_DB" "$IMAGE_AUTH" "$IMAGE_REST" "$IMAGE_STORAGE" "$IMAGE_MAIL" "$IMAGE_GATEWAY"; do + if docker image inspect -f '{{.Id}}' "$image" >/dev/null 2>&1; then where=present; else where='not pulled yet (create pulls it)'; fi + printf ' %-46s %s\n' "$image" "$where" + done + echo "Ports (127.0.0.1 only):" + for name in "${CONTAINERS[@]}"; do + read -r host inner <<<"$(port_of "$name")" + if port_listening "$host"; then + owner="$(docker ps --format '{{.Names}} {{.Ports}}' 2>/dev/null | grep -F ":$host->" | cut -d' ' -f1 | head -n 1 || true)" + printf ' %-6s taken by %s\n' "$host" "${owner:-a process outside Docker}" + refusals+=("port 127.0.0.1:$host is taken") + else + printf ' %-6s free\n' "$host" + fi + done + if host="$( (trial_host) 2>&1)"; then + if port_listening "$PORT_APP"; then where=taken; else where=free; fi + echo "App (pnpm db:trial app): http://$host:$PORT_APP, $where; the host is decided again at each app run" + else + refusals+=("$host") + fi + echo "State folder: $STATE (700, secrets 600)" + if [ -f "$SECRETS" ]; then refusals+=("$STATE already holds a stack"); fi + echo "Backups: $BACKUPS (cold copies, never pruned by the script; each needs free space of 110 % of the volumes)" + where="$STATE" + while [ ! -e "$where" ]; do where="$(dirname "$where")"; done + echo "Free disk there: $(df -h --output=avail "$where" | tail -n 1 | tr -d ' ')" + mib="$(available_mib)" + echo "Memory: caps 1920 MiB in all (about 650 MiB used in practice), $mib MiB available, floor $MEMORY_FLOOR_MIB MiB; the app's Node heap is capped at 768 MiB" + if [ "$mib" -lt "$MEMORY_FLOOR_MIB" ]; then refusals+=("only $mib MiB of memory available"); fi + if (check_seed_sources) 2>/dev/null; then echo "Equine seed folder: sheet id and drawing hashes match" + else refusals+=("the equine seed folder fails its hashes"); fi + echo "At create, before anything is made: the Rust pipeline regenerates the seed and compares it (pnpm r5:import-equine --check), then a --rm helper with no network checks that $IMAGE_DB holds tar and du" + if [ "${#refusals[@]}" -eq 0 ]; then + say "create would proceed" + else + say "create would refuse:" + printf ' - %s\n' "${refusals[@]}" + fi +} + +# The backups run tar and du in the database image: proven before anything is made. +check_helper_image() { + docker run --rm --name "$HELPER" --network none --entrypoint sh "$IMAGE_DB" -c 'command -v tar && command -v du' >/dev/null \ + || die "$IMAGE_DB lacks tar or du for the backups: nothing was created" +} +# Before the first Docker resource, the files this create wrote are removed (none existed: create +# refuses a folder holding secrets.env); after it, nothing is removed and the way out is named. +create_stopped() { + local status=$? + [ "$status" -ne 0 ] || return 0 + if [ "$FIRST_RESOURCE" = no ]; then + remove_live_files + echo "db-trial: create stopped before any Docker resource existed; the state files it wrote are removed" >&2 + return 0 + fi + echo "db-trial: create stopped before the end; nothing was removed. Present now:" >&2 + existing_resources | sed 's/^/ /' >&2 + echo "pnpm db:trial status shows the state; pnpm db:trial destroy (after the owner's go) clears it." >&2 +} +FIRST_RESOURCE=no +cmd_create() { + [ $# -eq 0 ] || die "create takes no argument" + local found name + [ ! -f "$SECRETS" ] || die "$STATE already holds a trial stack (pnpm db:trial status)" + found="$(existing_resources | tr '\n' ' ')" + [ -z "$found" ] || die "these faunosteo_trial_ resources already exist, nothing was created: $found" + ports_free "${CONTAINERS[@]}" + memory_ok + trial_host >/dev/null + check_seed_sources + check_seed_pipeline + check_helper_image + ( umask 077; mkdir -p "$STATE" "$BACKUPS" ) + chmod 700 "$STATE" "$BACKUPS" + ( umask 077; : > "$MARKER" ) + take_lock + trap create_stopped EXIT + new_secrets_file "$SECRETS" + load_secrets + write_conf + write_env_files + docker network create --label faunosteo.stack=trial "$NET" >/dev/null + FIRST_RESOURCE=yes + docker volume create --label faunosteo.stack=trial "$VOL_DB" >/dev/null + docker volume create --label faunosteo.stack=trial "$VOL_STORAGE" >/dev/null + for name in "$DB" "$MAIL" "$AUTH" "$STORAGE"; do run_service "$name"; done + published_exactly "$DB" + migrate_up + write_manifest + seed_equine + verify_equine_db + for name in "$REST" "$GATEWAY"; do run_service "$name"; done + check_loopback + trap - EXIT + say "trial stack created and running (gateway http://127.0.0.1:$PORT_GATEWAY)" + echo "Next: pnpm db:trial assets, then the accounts (SUPABASE.md §5.2), then pnpm db:trial app" +} + +cmd_start() { + [ $# -eq 0 ] || die "start takes no argument" + require_created + take_lock + memory_ok + start_containers + say "trial stack running; the app: pnpm db:trial app" +} +cmd_stop() { + [ $# -eq 0 ] || die "stop takes no argument" + require_created + take_lock + # A running app would keep proxying session tokens to whatever answers 58801 next. + refuse_while_app_runs + stop_containers + say "trial stack stopped; data kept in $VOL_DB and $VOL_STORAGE" +} + +status_database() { + local check pending + say "migrations: $(applied_versions | grep -c .) applied, $(find supabase/migrations -maxdepth 1 -name '*.sql' | wc -l) files in this branch" + if check="$( (check_manifest) 2>&1)"; then + # A refusal of pending_migrations is printed as it is, never fatal here. + pending="$( (pending_migrations) 2>&1 | tr '\n' ' ' || true)" + echo " applied files unchanged; new: ${pending:-none}" + else + echo " $check" + fi + say "equine sheet (versions by status)" + sb_psql -t -A -c "-- db-trial:equine-status +select status::text || ' ' || count(*) from public.anatomical_sheet_versions +where sheet_id = private.historical_sheet_id() group by status order by 1" | sed 's/^/ /' + echo " drawings uploaded and confirmed: $(uploaded_count)/$(expected_assets | grep -c .)" + say "accounts (email | platform roles | catalogue rights | verified TOTP factors)" + sb_psql -t -A -F ' | ' <<'SQL' | sed 's/^/ /' +-- db-trial:accounts +select u.email, + coalesce((select string_agg(r.role::text, ',' order by r.role::text) from public.profile_roles r + where r.user_id = u.id and r.revoked_at is null), '-'), + coalesce((select string_agg(g.grant_kind::text, ',' order by g.grant_kind::text) + from public.anatomical_catalog_grants g + where g.user_id = u.id and g.revoked_at is null + and (g.expires_at is null or g.expires_at > now())), '-'), + (select count(*) from auth.mfa_factors f + where f.user_id = u.id and f.factor_type = 'totp' and f.status = 'verified') +from auth.users u order by u.email; +SQL + say "content" + inventory_counts | sed 's/^/ /' +} +cmd_status() { + [ $# -eq 0 ] || die "status takes no argument" + local name host + if [ ! -e "$MARKER" ] || [ ! -f "$SECRETS" ]; then + say "no trial stack in $STATE (pnpm db:trial plan shows what create would make)" + existing_resources | sed 's/^/ present anyway: /' + list_backups + return 0 + fi + check_private "$STATE" 700 + load_conf + load_secrets + say "containers" + for name in "${CONTAINERS[@]}"; do + printf ' %-24s %s\n' "$name" "$(docker container inspect -f '{{.State.Status}} {{.Config.Image}}' "$name" 2>/dev/null || echo absent)" + done + say "Docker endpoint: $(daemon_endpoint)" + say "keys valid until $(key_expiry) (pnpm db:trial rotate-keys renews them)" + if [ "$(key_check "$TR_ANON_KEY" anon fresh >/dev/null 2>&1; echo $?)" = 3 ]; then + say "the keys have EXPIRED: app, assets and account refuse until pnpm db:trial rotate-keys" + fi + host="$( (trial_host) 2>&1 || true)" + say "app host now: $host (pnpm db:trial app serves http://:$PORT_APP)" + if container_running "$DB"; then status_database; else say "database stopped: pnpm db:trial start"; fi + list_backups +} +``` + +#### Section 6: dispatch (B2 and B3 add their lines) + +```bash +# Every command's arguments are checked before any Docker call (a refusal here logs nothing). +# The commands keep their own checks too, so each stays safe if called on its own. +check_arguments() { # action args... + local action="$1" + shift + case "$action" in + plan | create | start | stop | status) + [ $# -eq 0 ] || die "$action takes no argument" ;; + *) usage; exit 1 ;; + esac +} + +guard_environment +action="${1:-}" +[ $# -eq 0 ] || shift +case "$action" in + '' | help | -h | --help) usage; exit 1 ;; +esac +check_arguments "$action" "$@" +command -v docker >/dev/null || die "docker is not installed" +command -v ss >/dev/null || die "ss (iproute2) is not installed: the ports cannot be checked, nothing was run" +require_local_daemon +# Past this line a Docker "absent" is an answer, not a dead daemon (plan reports the daemon itself). +if [ "$action" != plan ]; then + daemon_ok || die "Docker daemon unreachable: nothing was run (systemctl --user status docker)" +fi +case "$action" in + plan) cmd_plan "$@" ;; + create) cmd_create "$@" ;; + start) cmd_start "$@" ;; + stop) cmd_stop "$@" ;; + status) cmd_status "$@" ;; + *) usage; exit 1 ;; +esac +``` + +#### Harness H1: frame, preflight, fake repository, stubs + +```bash +#!/usr/bin/env bash +# shellcheck disable=SC2016 +# (file-wide: the `bash -c '…'` snippets of the checks expand their own positional parameters) +# +# `bash scripts/db-trial-check.sh`, run by hand (never a check:all stage): environment-free checks +# of scripts/db-trial.sh and of the state-folder guard of scripts/db-sandbox.sh (TRIAL_STACK.md, +# SUPABASE.md §5.2). Each case runs a script from a throwaway copy of the files it reads, under a +# temporary HOME, with docker, curl, the Supabase CLI, Vite and the Rust tools replaced by stubs +# that log their arguments and keep one file per pretend resource; ss, node and env pass through +# wrappers that log their arguments, so no secret can hide in any argv. DOCKER_HOST names a socket +# that does not exist, so no daemon is reachable even past a stub. The script reads the host's +# real listening ports (ss) and memory: the preflight refuses to run (exit 2, never a FAIL) while +# a trial port is in use or memory is short. Nothing is created, started, stopped or removed +# outside the temporary folder. Prints "db-trial-check: ALL PASS" only when every check passed. +set -uo pipefail + +preflight() { + local port out mib + for port in 58432 58999 58300 58500 58025 58801 5194; do + out="$(ss -Hltn "sport = :$port")" || { echo "db-trial-check: cannot run while ss cannot list the ports: stop the trial stack/app first" >&2; exit 2; } + if [ -n "$out" ]; then + echo "db-trial-check: cannot run while port $port is in use: stop the trial stack/app first" >&2 + exit 2 + fi + done + mib="$(awk '/^MemAvailable:/ { print int($2 / 1024) }' /proc/meminfo)" + if [ "$mib" -lt 2048 ]; then + echo "db-trial-check: cannot run while only $mib MiB of memory are available (create needs 2048): stop the trial stack/app first" >&2 + exit 2 + fi +} +preflight + +REPO="$(cd "$(dirname "$0")/.." && pwd -P)" +TMP_ROOT="${TMPDIR:-/tmp}" +WORK="$(mktemp -d "$TMP_ROOT/db-trial-check.XXXXXX")" || exit 1 +# Every later path hangs off WORK: it must be the fresh folder mktemp just made, nothing else. +case "$WORK" in + "$TMP_ROOT"/db-trial-check.?*) [ -d "$WORK" ] || exit 1 ;; + *) echo "db-trial-check: unexpected temporary folder '$WORK': nothing was run" >&2; exit 1 ;; +esac +cleanup() { ( cd "$WORK" && rm -rf -- ./repo ./bin ./bin-no-ss ./path-no-ss ./cases ./docker-config ); rmdir -- "$WORK" 2>/dev/null || true; } +trap cleanup EXIT +PASS=0 FAIL=0 +pass() { echo "PASS $1"; PASS=$((PASS + 1)); } +fail() { echo "FAIL $1"; FAIL=$((FAIL + 1)); } +check() { local name="$1"; shift; if "$@"; then pass "$name"; else fail "$name"; fi; } + +SEED_REL=supabase/seed/anatomical-sheets/equine/draft +mkdir -p "$WORK/repo/scripts" "$WORK/repo/$SEED_REL/assets" "$WORK/repo/node_modules/.bin" \ + "$WORK/repo/apps/app/node_modules/.bin" "$WORK/bin" "$WORK/cases" "$WORK/docker-config" +cp "$REPO/scripts/db-trial.sh" "$REPO/scripts/db-sandbox.sh" "$REPO/scripts/dev-env.sh" "$WORK/repo/scripts/" +cp "$REPO/supabase/config.toml" "$REPO/supabase/seed.sql" "$WORK/repo/supabase/" +cp -R "$REPO/supabase/migrations" "$WORK/repo/supabase/migrations" +for f in equine_draft.sql document.json sheet-ref.json assets.json; do cp "$REPO/$SEED_REL/$f" "$WORK/repo/$SEED_REL/"; done +cp "$REPO/$SEED_REL/assets/"*.svg "$WORK/repo/$SEED_REL/assets/" + +cat > "$WORK/bin/docker" <<'STUB' +#!/usr/bin/env bash +# docker stand-in: one log line per call (newlines shown as \n), one file per pretend resource. +# Files under $STUB_STATE/fail/ make one answer fail: daemon, networks-create, archive, . +set -uo pipefail +st="$STUB_STATE" +{ printf 'docker'; for a in "$@"; do printf ' %s' "${a//$'\n'/\\n}"; done; printf '\n'; } >> "$STUB_LOG" +save_stdin() { local f; f="$st/stdin/$(date +%s%N)"; cat > "$f"; printf '%s' "$f"; } +sub="${1:-}" +[ $# -eq 0 ] || shift +case "$sub" in + info) [ ! -f "$st/fail/daemon" ] || exit 1; echo /stub/docker-root ;; + context) + [ "${1:-}" = inspect ] || exit 97 + [ ! -f "$st/fail/context" ] || exit 1 + if [ -f "$st/answers/context" ]; then cat "$st/answers/context"; else echo unix:///stub/docker.sock; fi ;; + ps) exit 0 ;; + image) [ "${1:-}" = inspect ] || exit 97; [ ! -f "$st/fail/image" ] || exit 1 ;; + network | volume) + kind="${sub}s" op="${1:-}" + shift + case "$op" in + inspect) if [ "${1:-}" = -f ]; then shift 2; fi; [ -f "$st/$kind/$1" ] ;; + create) + [ ! -f "$st/fail/$kind-create" ] || exit 1 + name="${*: -1}"; [ ! -f "$st/$kind/$name" ] || exit 1; : > "$st/$kind/$name"; echo "$name" ;; + rm) for n in "$@"; do [ -f "$st/$kind/$n" ] || exit 1; rm -f "$st/$kind/$n"; done ;; + *) exit 97 ;; + esac ;; + container) + [ "${1:-}" = inspect ] || exit 97 + shift + fmt='' + if [ "${1:-}" = -f ]; then fmt="$2"; shift 2; fi + [ -f "$st/containers/$1" ] || exit 1 + case "$fmt" in + '{{.State.Running}}') if [ "$(cat "$st/containers/$1")" = running ]; then echo true; else echo false; fi ;; + '{{.Name}}') echo "/$1" ;; + '') echo "stub: a bare inspect would print the env files" >&2; exit 98 ;; + *) echo "$(cat "$st/containers/$1") stub-image" ;; + esac ;; + run) + name='' port='' remove=0 input=0 args=("$@") i=0 + while [ "$i" -lt "${#args[@]}" ]; do + case "${args[$i]}" in + --name) name="${args[$((i + 1))]}"; i=$((i + 1)) ;; + -p) port="${args[$((i + 1))]}"; i=$((i + 1)) ;; + --rm) remove=1 ;; + -i) input=1 ;; + esac + i=$((i + 1)) + done + if [ "$remove" -eq 1 ]; then + if [ "$input" -eq 1 ]; then save_stdin >/dev/null; fi + # Measure: 100 KiB and 2 entries ("." and "./content"), what the archive below lists. + if printf '%s\n' "$@" | grep -q -- 'du -sk /volume'; then printf '100\n2\n'; fi + if printf '%s\n' "$@" | grep -qx -- -cf; then + [ ! -f "$st/fail/archive" ] || exit 3 + # A real (tiny) tar, so that the script's read-back has something to list. short-archive: + # the root entry only, exit 0 (an archive cut at a member boundary). + mkdir -p "$st/archive"; printf '%s\n' "$*" > "$st/archive/content" + if [ -f "$st/short-archive" ]; then tar -cf - -C "$st/archive" --no-recursion . + else tar -cf - -C "$st/archive" .; fi + fi + exit 0 + fi + [ -n "$name" ] && [ ! -f "$st/containers/$name" ] || exit 1 + echo running > "$st/containers/$name" + if [ -n "$port" ]; then + IFS=: read -r ip host inner <<<"$port" + # publish-wide-: Docker publishes that container on 0.0.0.0 whatever -p said. + if [ -f "$st/publish-wide-$name" ]; then ip=0.0.0.0; fi + echo "$inner/tcp -> $ip:$host" > "$st/ports/$name" + fi + echo "stub-id-$name" ;; + start) for n in "$@"; do [ -f "$st/containers/$n" ] || exit 1; echo running > "$st/containers/$n"; done ;; + restart) + while [ "${1:-}" = -t ]; do shift 2; done + for n in "$@"; do [ -f "$st/containers/$n" ] || exit 1; echo running > "$st/containers/$n"; done ;; + stop) + while [ "${1:-}" = -t ]; do shift 2; done + for n in "$@"; do [ -f "$st/containers/$n" ] || exit 1; echo exited > "$st/containers/$n"; done ;; + rm) + if [ "${1:-}" = -f ]; then shift; fi + for n in "$@"; do [ -f "$st/containers/$n" ] || exit 1; rm -f "$st/containers/$n" "$st/ports/$n"; done ;; + port) + [ -f "$st/ports/$1" ] || exit 1 + if [ $# -ge 2 ]; then sed 's/^.* -> //' "$st/ports/$1"; else cat "$st/ports/$1"; fi ;; + exec) + input=0 + while [ $# -gt 0 ]; do + case "$1" in -i) input=1; shift ;; -e | -u) shift 2 ;; *) break ;; esac + done + [ "$(cat "$st/containers/$1" 2>/dev/null)" = running ] || exit 1 + shift + # psql reads -c when given (stdin untouched, as the real psql does), else its stdin. + query='' prev='' has_c=0 + for a in "$@"; do if [ "$prev" = -c ]; then query="$a"; has_c=1; fi; prev="$a"; done + if [ "$input" -eq 1 ] && [ "$has_c" -eq 0 ]; then query="$(head -c 65536 "$(save_stdin)")"; fi + tag="$(printf '%s\n' "$query" | sed -n 's/^-- db-trial:\([a-z-]*\)$/\1/p' | head -n 1)" + # commit-then-fail: the rotation commits (its marker becomes the digest), then the exec stream + # is lost. Without it, fail/rotate leaves the marker empty: not committed. + if [ "$tag" = rotate ] && [ -f "$st/commit-then-fail" ]; then + printf '%s\n' "${ROT_DIGEST:-}" > "$st/answers/rotation-marker"; echo "stub: stream lost" >&2; exit 3 + fi + if [ -n "$tag" ] && [ -f "$st/fail/$tag" ]; then echo "stub: $tag refused" >&2; exit 3; fi + if [ -n "$tag" ] && [ -f "$st/answers/$tag" ]; then cat "$st/answers/$tag"; fi + exit 0 ;; + *) echo "stub docker: unsupported $sub" >&2; exit 97 ;; +esac +STUB +cat > "$WORK/bin/curl" <<'STUB' +#!/usr/bin/env bash +# curl stand-in. The trial gateway's identity endpoint answers faunosteo_trial, or +# answers/identity, or fails (fail/identity, curl -f's exit 22). +{ printf 'curl'; for a in "$@"; do printf ' %s' "$a"; done; printf '\n'; } >> "$STUB_LOG" +for a in "$@"; do + case "$a" in + @-) cat > "$STUB_STATE/stdin/curl-$(date +%s%N)" ;; + # A header file (a process substitution): only a digest of what was sent is kept. + @/dev/fd/*) sha256sum < "${a#@}" | cut -c1-16 > "$STUB_STATE/curl-header-sha" ;; + esac +done +case "${*: -1}" in + */__faunosteo_stack) + [ ! -f "$STUB_STATE/fail/identity" ] || exit 22 + if [ -f "$STUB_STATE/answers/identity" ]; then cat "$STUB_STATE/answers/identity"; else echo faunosteo_trial; fi ;; +esac +exit 0 +STUB +# ss runs for real unless the case asks it to fail (it must then never read as "port free"). +cat > "$WORK/bin/ss" <<'STUB' +#!/usr/bin/env bash +if [ -f "$STUB_STATE/fail/ss" ]; then echo "ss: cannot open netlink socket" >&2; exit 1; fi +exec "$(cat "$(dirname "$0")/real-ss")" "$@" +STUB +command -v ss > "$WORK/bin/real-ss" +# node and env run for real behind a wrapper that logs their argv (newlines as \n). +cat > "$WORK/bin/passthrough" <<'STUB' +#!/usr/bin/env bash +tool="$(basename "$0")" +{ printf '%s' "$tool"; for a in "$@"; do printf ' %s' "${a//$'\n'/\\n}"; done; printf '\n'; } >> "$STUB_LOG" +exec "$(cat "$(dirname "$0")/real-$tool")" "$@" +STUB +for tool in node env; do + command -v "$tool" > "$WORK/bin/real-$tool" + cp "$WORK/bin/passthrough" "$WORK/bin/$tool" +done +cat > "$WORK/repo/node_modules/.bin/supabase" <<'STUB' +#!/usr/bin/env bash +{ printf 'supabase'; for a in "$@"; do printf ' %s' "$a"; done; printf ' PGPASSWORD=%s\n' "${PGPASSWORD:+set}"; } >> "$STUB_LOG" +if [ "$*" = "--workdir . migration up --db-url postgresql://postgres@127.0.0.1:58432/postgres?sslmode=disable" ]; then + for f in supabase/migrations/*.sql; do basename "$f" | cut -d_ -f1; done > "$STUB_STATE/answers/applied" + if [ -f "$STUB_STATE/fail/migrate" ]; then echo "stub: a migration failed after the others applied" >&2; exit 3; fi + exit 0 +fi +exit 97 +STUB +cat > "$WORK/repo/apps/app/node_modules/.bin/vite" <<'STUB' +#!/usr/bin/env bash +{ printf 'vite'; for a in "$@"; do printf ' %s' "$a"; done; printf '\n' + printf 'vite-env anon-sha=%s pgpassword=%s node-options=%s gateway=%s host=%s url=%s proxies=%s\n' \ + "$(printf '%s' "${VITE_SUPABASE_ANON_KEY:-}" | sha256sum | cut -c1-16)" "${PGPASSWORD:+set}" \ + "${NODE_OPTIONS:-}" "${FAUNOSTEO_TRIAL_GATEWAY:-}" "${FAUNOSTEO_TRIAL_HOST:-}" "${VITE_SUPABASE_URL:-}" \ + "${http_proxy:-}${HTTP_PROXY:-}${https_proxy:-}${HTTPS_PROXY:-}${all_proxy:-}${ALL_PROXY:-}${NODE_USE_ENV_PROXY:-}"; } >> "$STUB_LOG" +STUB +cat > "$WORK/repo/scripts/upload-sheet-assets.sh" <<'STUB' +#!/usr/bin/env bash +{ printf 'upload'; for a in "$@"; do printf ' %s' "$a"; done; printf '\n' + printf 'upload-env url=%s key-sha=%s dev-host=%s init-cwd=%s\n' "${SUPABASE_URL:-}" \ + "$(printf '%s' "${SUPABASE_SERVICE_ROLE_KEY:-}" | sha256sum | cut -c1-16)" \ + "${FAUNOSTEO_DEV_HOST:+set}" "${INIT_CWD:+set}"; } >> "$STUB_LOG" +if [ "${1:-}" = --check ]; then + echo "horse.svg 0ea5202fa3b95bac167b87c12ee969ab0272e085b60c2d34dbca6202c5f08541.svg: would object verified, row confirmed, nothing to do" +else + echo "horse.svg done" +fi +echo ok +STUB +cat > "$WORK/repo/scripts/import-equine.sh" <<'STUB' +#!/usr/bin/env bash +{ printf 'import-equine'; for a in "$@"; do printf ' %s' "$a"; done; printf '\n'; } >> "$STUB_LOG" +STUB +chmod +x "$WORK/bin/docker" "$WORK/bin/curl" "$WORK/bin/ss" "$WORK/bin/node" "$WORK/bin/env" \ + "$WORK/repo/node_modules/.bin/supabase" "$WORK/repo/apps/app/node_modules/.bin/vite" +BASE_PATH="$PATH" +for tool in docker curl ss node env; do + if [ "$(PATH="$WORK/bin:$BASE_PATH" command -v "$tool")" != "$WORK/bin/$tool" ]; then + echo "db-trial-check: the stubs do not shadow $tool: nothing was run" >&2 + exit 1 + fi +done +# A PATH with every tool but ss: the stubs (no ss wrapper), then a link to each executable of the +# real PATH except ss. Used by the "ss is not installed" case only. +mkdir -p "$WORK/bin-no-ss" "$WORK/path-no-ss" +cp -p "$WORK/bin/docker" "$WORK/bin/curl" "$WORK/bin/node" "$WORK/bin/env" "$WORK/bin/real-node" "$WORK/bin/real-env" "$WORK/bin-no-ss/" +IFS=: read -ra PATH_DIRS <<<"$BASE_PATH" +for dir in "${PATH_DIRS[@]}"; do + for exe in "$dir"/*; do + name="${exe##*/}" + if [ "$name" != ss ] && [ -x "$exe" ] && [ ! -e "$WORK/path-no-ss/$name" ]; then ln -s "$exe" "$WORK/path-no-ss/$name"; fi + done +done +``` + +#### Harness H2: case machinery and assertions + +```bash +ASSET_LINE="$(node -e 'for (const a of require(process.argv[1])) console.log(a.sha256 + " " + a.byte_size)' "$WORK/repo/$SEED_REL/assets.json")" +new_case() { # name + CASE="$WORK/cases/$1" + mkdir -p "$CASE/home" "$CASE/stub/containers" "$CASE/stub/ports" "$CASE/stub/volumes" "$CASE/stub/networks" \ + "$CASE/stub/answers" "$CASE/stub/fail" "$CASE/stub/stdin" + : > "$CASE/log" + STATE_DIR="$CASE/home/.cache/faunosteo-trial" + echo 'official=1 historical=1 versions=1 draft_equal=true accounts=0' > "$CASE/stub/answers/equine" + printf '%s\n' "$ASSET_LINE" > "$CASE/stub/answers/asset-rows" + echo 1 > "$CASE/stub/answers/assets-uploaded" + echo 'granted false' > "$CASE/stub/answers/grant-catalog" + EXTRA=() + CASE_PATH="$WORK/bin:$BASE_PATH" + # The no-daemon barrier: a unix socket that does not exist (so the script's local-daemon guard + # accepts it and a real docker, were a stub missing, would still reach nothing), and a context + # that does not exist for the cases that clear DOCKER_HOST. + CASE_DOCKER_HOST="unix://$WORK/no-daemon.sock" +} +# Gives a script a terminal (a pty), types its stdin there, copies the output, returns the exit code. +PTY_DRIVER=' +import os, pty, sys +pid, fd = pty.fork() +if pid == 0: + os.execvp(sys.argv[1], sys.argv[1:]) +try: + os.write(fd, sys.stdin.buffer.read()) +except OSError: + pass +while True: + try: + chunk = os.read(fd, 4096) + except OSError: + break + if not chunk: + break + sys.stdout.buffer.write(chunk) +sys.stdout.flush() +_, status = os.waitpid(pid, 0) +sys.exit(os.waitstatus_to_exitcode(status)) +' +LAUNCH=() +run_script() { # script args... → RC, output in $CASE/out; stdin as the caller set it + local script="$1" + shift + ( cd "$WORK/repo" && env -i HOME="$CASE/home" PATH="$CASE_PATH" LANG=C.UTF-8 \ + DOCKER_HOST="$CASE_DOCKER_HOST" DOCKER_CONTEXT=faunosteo-check-no-such-context DOCKER_CONFIG="$WORK/docker-config" \ + STUB_LOG="$CASE/log" STUB_STATE="$CASE/stub" FAUNOSTEO_TRIAL_HOST=127.0.0.1 "${EXTRA[@]}" \ + "${LAUNCH[@]}" bash "scripts/$script" "$@" ) > "$CASE/out" 2>&1 + RC=$? +} +trial() { LAUNCH=(); run_script db-trial.sh "$@" < /dev/null; } +trial_input() { LAUNCH=(); run_script db-trial.sh "$@"; } # stdin from the caller (a pipe: no terminal) +trial_tty() { # input args...: the input typed at the script's terminal + local input="$1" + shift + LAUNCH=(python3 -c "$PTY_DRIVER") + run_script db-trial.sh "$@" <<<"$input" + LAUNCH=() +} +sandbox() { LAUNCH=(); run_script db-sandbox.sh "$@" < /dev/null; } +fresh_log() { : > "$CASE/log"; } + +docker_calls() { grep '^docker ' "$CASE/log" || true; } +# Calls that change something: Docker writes, the CLI, the upload tool, Vite. +changes() { + grep -E '^(docker (run|start|restart|stop|rm|volume (create|rm)|network (create|rm))|supabase |upload |vite )' "$CASE/log" || true +} +out_has() { grep -qF -- "$1" "$CASE/out"; } +log_has() { grep -qF -- "$1" "$CASE/log"; } +refused() { [ "$RC" -ne 0 ] && [ -z "$(changes)" ] && out_has "$1"; } +refused_early() { [ "$RC" -ne 0 ] && [ ! -s "$CASE/log" ] && out_has "$1"; } +mode_is() { [ "$(stat -c %a "$1")" = "$2" ]; } +values_absent_from() { # secrets file, files... + local value file + [ -f "$1" ] || return 1 + while IFS='=' read -r _ value; do + [ -n "$value" ] || continue + for file in "${@:2}"; do + if [ -f "$file" ] && grep -qF -- "$value" "$file"; then return 1; fi + done + done < "$1" +} +# The log holds every argv of docker, curl, node, env, the CLI, Vite and the tools. +secrets_absent() { values_absent_from "$1" "$CASE/log" "$CASE/out"; } +stdin_files() { find "$CASE/stub/stdin" -type f; } +stdin_has() { stdin_files | xargs -r grep -lF -- "$1" | grep -q .; } +run_line() { docker_calls | grep -E "^docker run -d --name $1 " || true; } +expect_run() { # name port inner memory pids [volume] + local line + line="$(run_line "$1")" + [ "$(grep -c . <<<"$line")" -eq 1 ] || return 1 + grep -qF -- "--network faunosteo_trial_net --restart no --memory $4 --cpus 1 --pids-limit $5 -p 127.0.0.1:$2:$3 " <<<"$line" || return 1 + [ "$(grep -oE -- ' -p [^ ]+' <<<"$line" | wc -l)" -eq 1 ] || return 1 + if [ -n "${6:-}" ]; then grep -qF -- " -v $6 " <<<"$line"; else ! grep -qE -- ' -v ' <<<"$line"; fi +} +# Resource names plus the Supabase roles and the migrations schema that SQL text in argv may name. +ALLOWED_NAMES='faunosteo_trial_(db|mail|auth|storage|rest|gateway|helper|net)|supabase_(admin|auth_admin|storage_admin|migrations)' +only_trial_names() { ! docker_calls | grep -oE '(faunosteo|supabase)_[A-Za-z0-9_]+' | grep -vxE "$ALLOWED_NAMES" | grep -q .; } +no_volume_removal() { ! log_has 'docker volume rm'; } +line_of() { grep -nF -- "$1" "$CASE/log" | head -n 1 | cut -d: -f1; } +before() { local a b; a="$(line_of "$1")"; b="$(line_of "$2")"; [ -n "$a" ] && [ -n "$b" ] && [ "$a" -lt "$b" ]; } +hold_port() { # port → LISTENER pid, or returns 1 when the port cannot be held + python3 -c 'import socket, sys, time +s = socket.socket(); s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) +s.bind(("127.0.0.1", int(sys.argv[1]))); s.listen(1); print("up", flush=True); time.sleep(30)' "$1" > "$CASE/listener" 2>&1 & + LISTENER=$! + for _ in $(seq 1 50); do if grep -q up "$CASE/listener"; then return 0; fi; sleep 0.1; done + kill "$LISTENER" 2>/dev/null + return 1 +} +release_port() { kill "$LISTENER" 2>/dev/null; wait "$LISTENER" 2>/dev/null; } +# Every logged curl starts with -q (no ~/.curlrc) and --noproxy '*' (no proxy variable). +curls_pinned() { grep -q '^curl ' "$CASE/log" && ! grep '^curl ' "$CASE/log" | grep -v "^curl -q --noproxy \* " | grep -q .; } +backup_count() { find "$STATE_DIR/backups" -mindepth 1 -maxdepth 1 -type d | wc -l; } +# Rewrites one key line of a secrets file (default the case's secrets.env) with a key of the given +# issuer and role, signed with that file's own secret or a random one, expiring in s. +forge() { # var issuer own|other role [offset] [file] + FORGE_FILE="${6:-$STATE_DIR/secrets.env}" node -e ' + const fs = require("fs"), c = require("crypto"); + const [name, iss, source, role, offset] = process.argv.slice(1); + const file = process.env.FORGE_FILE; + const lines = fs.readFileSync(file, "utf8").trim().split("\n"); + const own = lines.find((l) => l.startsWith("TR_JWT_SECRET=")).slice(14); + const secret = source === "own" ? own : c.randomBytes(32).toString("hex"); + const b64 = (o) => Buffer.from(JSON.stringify(o)).toString("base64url"); + const h = b64({ alg: "HS256", typ: "JWT" }), now = Math.floor(Date.now() / 1000); + const b = b64({ role, iss, iat: now - 7200, exp: now + Number(offset) }); + const jwt = h + "." + b + "." + c.createHmac("sha256", secret).update(h + "." + b).digest("base64url"); + fs.writeFileSync(file, lines.map((l) => l.startsWith(name + "=") ? name + "=" + jwt : l).join("\n") + "\n", { mode: 0o600 }); + ' "$1" "$2" "$3" "$4" "${5:-3600}" +} +env_file_state() { # file → digest and mtime, to prove a refusal wrote nothing + printf '%s %s\n' "$(sha256sum < "$1" | cut -d' ' -f1)" "$(stat -c %Y "$1")" +} +``` + +#### Harness H3: static checks and B1 cases + +```bash +echo "-- static" +if command -v shellcheck >/dev/null; then + check "shellcheck: db-trial.sh and this harness" bash -c 'cd "$1" && shellcheck -x scripts/db-trial.sh scripts/db-trial-check.sh' _ "$REPO" + check "shellcheck: db-sandbox.sh (pre-existing SC1090, SC1091, SC2016 excluded)" shellcheck -e SC1090,SC1091,SC2016 "$REPO/scripts/db-sandbox.sh" +else + fail "shellcheck is not installed" +fi +check "db-sandbox.sh: additions only since b215b89 (its commands unchanged)" bash -c 'cd "$1" && [ "$(git diff --numstat b215b89 -- scripts/db-sandbox.sh | cut -f2)" = 0 ]' _ "$REPO" +TRIAL_PORTS="$(grep -oE 'PORT_[A-Z_]+=[0-9]+' "$REPO/scripts/db-trial.sh" | cut -d= -f2 | sort -u)" +SANDBOX_PORTS="$(grep -oE 'PORT_[A-Z_]+=[0-9]+' "$REPO/scripts/db-sandbox.sh" | cut -d= -f2 | sort -u)" +DEV_PORTS="$(printf '%s\n' 5173 5191 5192 54321 54322 54323 54324 54325 | sort -u)" +check "trial ports are the ratified ones" [ "$TRIAL_PORTS" = "$(printf '%s\n' 5194 58025 58300 58432 58500 58801 58999 | sort -u)" ] +check "no trial port is a sandbox or DEV port" [ -z "$(comm -12 <(printf '%s\n' "$TRIAL_PORTS") <(printf '%s\n%s\n' "$SANDBOX_PORTS" "$DEV_PORTS" | sort -u))" ] +check "db-trial.sh never runs a bare inspect" bash -c '! grep -nE "docker (container |volume |network |image )?inspect [^-]" "$1"' _ "$REPO/scripts/db-trial.sh" + +echo "-- refusals before anything" +new_case sandbox-env; EXTRA=(SANDBOX_AUTH_URL=http://127.0.0.1:57999); trial plan +check "a SANDBOX_* variable stops every command before any call" refused_early "SANDBOX_AUTH_URL is set" +new_case state-in-repo; EXTRA=(FAUNOSTEO_TRIAL_DIR="$WORK/repo/trial-state"); trial create +check "a state folder inside the repository is refused" refused_early "outside the repository" +new_case state-in-git; git init -q "$CASE/gitrepo"; EXTRA=(FAUNOSTEO_TRIAL_DIR="$CASE/gitrepo/state"); trial create +check "a state folder inside any git work tree is refused" refused_early "outside every git work tree" +new_case state-symlink-repo; ln -s "$WORK/repo/trial-state" "$CASE/link"; EXTRA=(FAUNOSTEO_TRIAL_DIR="$CASE/link"); trial create +check "a state folder that is a symlink into the repository is refused (canonical path)" refused_early "outside the repository" +new_case state-symlink-sandbox; mkdir -p "$CASE/sbstate"; ln -s "$CASE/sbstate" "$CASE/link" +EXTRA=(FAUNOSTEO_TRIAL_DIR="$CASE/link" FAUNOSTEO_SANDBOX_DIR="$CASE/sbstate"); trial create +check "a state folder that is a symlink to the sandbox's state is refused" refused_early "sandbox's state folder" +new_case ss-fails; : > "$CASE/stub/fail/ss"; trial create +check "ss failing: create refuses, a port is never read as free" refused "ss cannot list the listening ports" +new_case ss-absent; CASE_PATH="$WORK/bin-no-ss:$WORK/path-no-ss"; trial create +check "ss absent from PATH: every command refuses before any call" refused_early "ss (iproute2) is not installed" +new_case state-symlink-ok; mkdir -p "$CASE/real"; ln -s "$CASE/real" "$CASE/link"; EXTRA=(FAUNOSTEO_TRIAL_DIR="$CASE/link") +trial create; RC_CREATE=$RC; trial status; RC_STATUS=$RC; trial stop +check "a state folder reached through a symlink works: create, status, stop on the real folder (700)" bash -c '[ "$1" -eq 0 ] && [ "$2" -eq 0 ] && [ "$3" -eq 0 ] && [ "$(stat -c %a "$4")" = 700 ] && [ -f "$4/secrets.env" ]' _ "$RC_CREATE" "$RC_STATUS" "$RC" "$CASE/real" +new_case create-db-wide; : > "$CASE/stub/publish-wide-faunosteo_trial_db"; trial create +check "create: Postgres published beyond 127.0.0.1 stops it before any migration" bash -c '[ "$1" -ne 0 ] && grep -qF "faunosteo_trial_db is not published on 127.0.0.1:58432 only" "$2" && ! grep -q "^supabase " "$3"' _ "$RC" "$CASE/out" "$CASE/log" +new_case foreign-state; mkdir -p "$CASE/foreign"; : > "$CASE/foreign/secrets.sh"; EXTRA=(FAUNOSTEO_TRIAL_DIR="$CASE/foreign"); trial create +check "a non-empty folder without the trial marker is refused" refused_early "holds no db:trial state" +new_case sandbox-state; EXTRA=(FAUNOSTEO_TRIAL_DIR="$CASE/shared" FAUNOSTEO_SANDBOX_DIR="$CASE/shared"); trial create +check "the sandbox's state folder is refused" refused_early "sandbox's state folder" +new_case usage; trial +check "no command prints the usage and runs nothing" refused_early "pnpm db:trial create" +new_case remote-docker-host; CASE_DOCKER_HOST=tcp://10.0.0.1:2375; trial status +check "a DOCKER_HOST that is not a unix socket is refused before any call" refused_early "is not a local unix socket" +new_case remote-context; CASE_DOCKER_HOST=''; echo tcp://10.0.0.1:2376 > "$CASE/stub/answers/context"; trial status +check "a current context that is not a unix socket is refused before any change" refused "is not a local unix socket" +new_case local-context; CASE_DOCKER_HOST=''; trial plan +check "no DOCKER_HOST and a unix context: plan answers and prints that endpoint" bash -c '[ "$1" -eq 0 ] && grep -qF "Docker endpoint: unix:///stub/docker.sock" "$2"' _ "$RC" "$CASE/out" +new_case unreadable-context; CASE_DOCKER_HOST=''; : > "$CASE/stub/fail/context"; trial status +check "a current context that cannot be read is refused before any change" refused "cannot be read" +new_case daemon-down; : > "$CASE/stub/fail/daemon"; trial create +check "Docker daemon down: create refuses, no state written" bash -c '[ "$1" -ne 0 ] && grep -qF "Docker daemon unreachable" "$2" && [ ! -e "$3" ]' _ "$RC" "$CASE/out" "$STATE_DIR" +trial plan +check "Docker daemon down: plan still answers and names it" bash -c '[ "$1" -eq 0 ] && grep -qF "Docker daemon is unreachable" "$2" && grep -qF "create would refuse" "$2"' _ "$RC" "$CASE/out" +new_case existing-volume; : > "$CASE/stub/volumes/faunosteo_trial_db"; trial create +check "an existing faunosteo_trial_ volume: create refuses, nothing changed" refused "already exist" +new_case port-taken +if hold_port 58801; then trial create; check "a taken port: create refuses, nothing changed" refused "58801 is taken"; release_port +else fail "could not hold 127.0.0.1:58801 for the port case"; fi + +echo "-- plan" +new_case plan; trial plan +check "plan: read-only, proceeds on a clean host" bash -c '[ "$1" -eq 0 ]' _ "$RC" +check "plan: names the Docker endpoint" out_has "Docker endpoint: unix://" +check "plan: no change" [ -z "$(changes)" ] +check "plan: names every container, limit and volume place" bash -c 'grep -qF "faunosteo_trial_db" "$1" && grep -qF -- "--memory 1g" "$1" && grep -qF "/stub/docker-root/volumes/faunosteo_trial_storage/_data" "$1" && grep -qF "create would proceed" "$1"' _ "$CASE/out" + +echo "-- create" +new_case create-fails-early; : > "$CASE/stub/fail/networks-create"; trial create +check "create dying before its first resource removes the state files it wrote" bash -c '[ "$1" -ne 0 ] && grep -qF "state files it wrote are removed" "$2" && [ ! -e "$3/secrets.env" ] && [ ! -e "$3/db.env" ] && [ ! -e "$3/stack.conf" ]' _ "$RC" "$CASE/out" "$STATE_DIR" +check "create dying early: nothing to undo in Docker" bash -c '! grep -qE "^docker (volume create|run -d)" "$1"' _ "$CASE/log" +new_case equine-mismatch; echo 'official=2 historical=1 versions=1 draft_equal=true accounts=0' > "$CASE/stub/answers/equine"; trial create +check "create: an equine sheet that is not the seed's stops it, resources named" bash -c '[ "$1" -ne 0 ] && grep -qF "is not the seed" "$2" && grep -qF "nothing was removed" "$2" && ! grep -q "^docker run -d --name faunosteo_trial_rest " "$3"' _ "$RC" "$CASE/out" "$CASE/log" +new_case asset-rows-mismatch; printf '%s\n' "0000 1" > "$CASE/stub/answers/asset-rows"; trial create +check "create: drawing rows that differ from assets.json stop it" bash -c '[ "$1" -ne 0 ] && grep -qF "drawing rows differ" "$2"' _ "$RC" "$CASE/out" +new_case create; trial create +check "create succeeds on an empty host" [ "$RC" -eq 0 ] +check "create: the Rust pipeline check runs before any change" before 'import-equine --check' 'docker network create' +check "create: the helper image holds tar and du, checked before any resource" before 'docker run --rm --name faunosteo_trial_helper --network none --entrypoint sh public.ecr.aws/supabase/postgres:17.11.0.004 -c command -v tar && command -v du' 'docker network create' +check "create: network and volumes under literal trial names" bash -c 'grep -qx "docker network create --label faunosteo.stack=trial faunosteo_trial_net" "$1" && grep -qx "docker volume create --label faunosteo.stack=trial faunosteo_trial_db" "$1" && grep -qx "docker volume create --label faunosteo.stack=trial faunosteo_trial_storage" "$1"' _ "$CASE/log" +check "create: db name, loopback port, caps, volume" expect_run faunosteo_trial_db 58432 5432 1g 512 faunosteo_trial_db:/var/lib/postgresql/data +check "create: mail" expect_run faunosteo_trial_mail 58025 8025 64m 64 +check "create: auth" expect_run faunosteo_trial_auth 58999 9999 128m 256 +check "create: storage with its volume" expect_run faunosteo_trial_storage 58500 5000 256m 256 faunosteo_trial_storage:/mnt +check "create: rest" expect_run faunosteo_trial_rest 58300 3000 384m 256 +check "create: gateway" expect_run faunosteo_trial_gateway 58801 8000 64m 64 +check "create: GoTrue sign-up closed" bash -c 'grep -E "^docker run -d --name faunosteo_trial_auth " "$1" | grep -qF GOTRUE_DISABLE_SIGNUP=true' _ "$CASE/log" +check "create: GoTrue mail links on the trial host's app origin" bash -c 'grep -E "^docker run -d --name faunosteo_trial_auth " "$1" | grep -qF "GOTRUE_SITE_URL=http://127.0.0.1:5194"' _ "$CASE/log" +check "create: gateway refuses GoTrue's admin API" log_has 'location /auth/v1/admin/ { return 403; }' +check "create: gateway names itself on /__faunosteo_stack" log_has 'location = /__faunosteo_stack { default_type text/plain; return 200 "faunosteo_trial\n"; }' +check "create: the database init turns statement logging on errors off first" log_has 'set log_min_error_statement = panic;' +check "create: migrations through the CLI on the trial URL only" log_has 'supabase --workdir . migration up --db-url postgresql://postgres@127.0.0.1:58432/postgres?sslmode=disable PGPASSWORD=set' +check "create: equine_draft.sql loaded, seed.sql never" bash -c 'stdin=$(find "$1" -type f); grep -lF -- "-- Official equine anatomical sheet" $stdin >/dev/null && ! grep -lF "faunosteo.local" $stdin >/dev/null' _ "$CASE/stub/stdin" +check "create: the seeded draft is compared with document.json" stdin_has '$faunosteo_trial_doc$' +check "create: only trial names (and Supabase roles) in docker calls" only_trial_names +check "create: no volume removal" no_volume_removal +check "create: every curl pinned to its destination (-q, --noproxy)" curls_pinned +check "create: every container checked on 127.0.0.1 only" log_has 'docker port faunosteo_trial_gateway' +check "create: node ran behind the argv logger" log_has 'node -e ' +check "create: state folder 700, backups 700, files 600" bash -c 'for f in "$1" "$1/backups"; do [ "$(stat -c %a "$f")" = 700 ] || exit 1; done; for f in secrets.env db.env auth.env storage.env rest.env stack.conf migrations.sha256 .faunosteo-trial-state; do [ "$(stat -c %a "$1/$f")" = 600 ] || exit 1; done; ! ls "$1"/*.new >/dev/null 2>&1' _ "$STATE_DIR" +check "create: keys for the issuer faunosteo-trial, one year" node -e ' + const lines = Object.fromEntries(require("fs").readFileSync(process.argv[1], "utf8").trim().split("\n").map((l) => [l.slice(0, l.indexOf("=")), l.slice(l.indexOf("=") + 1)])); + for (const [name, role] of [["TR_ANON_KEY", "anon"], ["TR_SERVICE_KEY", "service_role"]]) { + const p = JSON.parse(Buffer.from(lines[name].split(".")[1], "base64url")); + if (p.iss !== "faunosteo-trial" || p.role !== role || p.exp - p.iat !== 31536000) process.exit(1); + }' "$STATE_DIR/secrets.env" +check "create: stack.conf records the six images, no host" bash -c '! grep -q "^TRIAL_HOST=" "$1" && [ "$(grep -c "^IMAGE_" "$1")" -eq 6 ]' _ "$STATE_DIR/stack.conf" +check "create: one manifest line per migration file" [ "$(wc -l < "$STATE_DIR/migrations.sha256")" -eq "$(find "$WORK/repo/supabase/migrations" -name '*.sql' | wc -l)" ] +check "create: no secret in any argv (docker, curl, node, env, tools) or output" secrets_absent "$STATE_DIR/secrets.env" +fresh_log; trial create +check "a second create refuses, nothing changed" refused "already holds a trial stack" + +echo "-- stop, start, status" +if hold_port 5194; then fresh_log; trial stop; check "stop while port 5194 is in use (the app): refused, nothing stopped" refused "5194 is in use"; release_port +else fail "could not hold 127.0.0.1:5194 for the stop case"; fi +fresh_log; trial stop +check "stop: each container stopped, reverse order, nothing else" bash -c '[ "$1" -eq 0 ] && [ "$2" = "$(printf "docker stop -t 60 %s\n" faunosteo_trial_gateway faunosteo_trial_rest faunosteo_trial_storage faunosteo_trial_auth faunosteo_trial_mail faunosteo_trial_db)" ]' _ "$RC" "$(changes)" +if hold_port 58300; then fresh_log; trial start; check "start: a taken port refuses before any container starts" refused "58300 is taken"; release_port +else fail "could not hold 127.0.0.1:58300 for the start case"; fi +cp -p "$CASE/stub/ports/faunosteo_trial_rest" "$CASE/rest.port" +echo '3000/tcp -> 0.0.0.0:58300' > "$CASE/stub/ports/faunosteo_trial_rest" +fresh_log; trial start +check "start: a container published on 0.0.0.0 is refused" bash -c '[ "$1" -ne 0 ] && grep -qF "faunosteo_trial_rest is not published on 127.0.0.1:58300 only" "$2"' _ "$RC" "$CASE/out" +cp -p "$CASE/rest.port" "$CASE/stub/ports/faunosteo_trial_rest" +fresh_log; trial stop; fresh_log; trial start +check "start: same containers in order, nothing created" bash -c '[ "$1" -eq 0 ] && [ "$2" = "$(printf "docker start %s\n" faunosteo_trial_db faunosteo_trial_mail faunosteo_trial_auth faunosteo_trial_storage faunosteo_trial_rest faunosteo_trial_gateway)" ]' _ "$RC" "$(changes)" +rm -f "$CASE/stub/containers/faunosteo_trial_rest" "$CASE/stub/ports/faunosteo_trial_rest" +fresh_log; trial start +check "start: a missing container is recreated, then the running gateway restarted" bash -c '[ "$1" -eq 0 ] && [ "$(printf "%s\n" "$2" | grep -c .)" -eq 2 ] && printf "%s\n" "$2" | head -n 1 | grep -q "^docker run -d --name faunosteo_trial_rest " && printf "%s\n" "$2" | tail -n 1 | grep -qx "docker restart -t 10 faunosteo_trial_gateway"' _ "$RC" "$(changes)" +check "start: the recreation leaves no secret in argv" secrets_absent "$STATE_DIR/secrets.env" +fresh_log; trial status +check "status: read-only, keys' expiry, no secret" bash -c '[ "$1" -eq 0 ] && [ -z "$2" ] && grep -qF "keys valid until" "$3"' _ "$RC" "$(changes)" "$CASE/out" +check "status: no secret in its output" secrets_absent "$STATE_DIR/secrets.env" + +echo "-- half-written state" +cp -p "$STATE_DIR/secrets.env" "$CASE/secrets.good" +printf 'TR_PW=short\n' > "$STATE_DIR/secrets.env" +for action in start stop status; do + fresh_log; trial "$action" + check "malformed secrets: $action refuses, nothing changed" refused "malformed" +done +cp -p "$CASE/secrets.good" "$STATE_DIR/secrets.env" +chmod 644 "$STATE_DIR/secrets.env"; fresh_log; trial status +check "secrets readable by others: refused" refused "mode 600" +chmod 600 "$STATE_DIR/secrets.env" + +echo "-- db:sandbox state guard" +new_case sandbox-guard; mkdir -p "$CASE/trialstate"; : > "$CASE/trialstate/.faunosteo-trial-state" +EXTRA=(FAUNOSTEO_SANDBOX_DIR="$CASE/trialstate"); sandbox down +check "db:sandbox down refuses a folder holding the trial marker, nothing run" refused_early "db:trial state folder" +EXTRA=(FAUNOSTEO_SANDBOX_DIR="$CASE/same" FAUNOSTEO_TRIAL_DIR="$CASE/same"); sandbox down +check "db:sandbox down refuses the db:trial state folder by path" refused_early "db:trial state folder" +fresh_log; EXTRA=(FAUNOSTEO_SANDBOX_DIR="$CASE/sandbox-state"); sandbox down +check "db:sandbox down on its own folder names faunosteo_dbsandbox_ resources only" bash -c '[ "$1" -eq 0 ] && grep -q "^docker rm -f faunosteo_dbsandbox_" "$2" && ! grep -oE "faunosteo_[a-z_]+" "$2" | grep -qv "^faunosteo_dbsandbox_"' _ "$RC" "$CASE/log" +``` + +#### Harness H4: summary (always last) + +```bash +echo "-- $PASS passed, $FAIL failed" +if [ "$FAIL" -eq 0 ] && [ "$PASS" -gt 0 ]; then echo "db-trial-check: ALL PASS"; else exit 1; fi +``` + +--- + +### Lot B2: backup, restore, destroy, migrate, rotate-keys, rotate-secrets + +**Files:** +- Modify: `scripts/db-trial.sh` (section 7 before the dispatch; dispatch lines) +- Modify: `scripts/db-trial-check.sh` (cases H5 inserted before H4) + +**Interfaces:** +- Consumes: all of B1. +- Produces: `confirm ` (terminal only), `backup_now