Files
faunosteo/.claude/tasks/plans/2026-11-11-trial-owner-one-factor-2050.md

45 lines
6.5 KiB
Markdown

# PLAN — db:trial owner grant with one verified TOTP factor
Contract: .claude/tasks/contracts/2026-11-11-trial-owner-one-factor-2050.md
## Facts (investigated)
- scripts/db-trial.sh `grant_platform_role` (≈1719-1747): `local need=1 factors count`, then `[ "$2" != owner ] || need=2`; `factor_count` before the typed confirmation; the grant transaction recounts verified TOTP factors (`>= :need`) and `\gset` fails on zero rows → ON_ERROR_STOP → rollback; operator path `private.assign_platform_role(null, …)` + `private.log_event` audit row.
- SQL never requires two: `private.assign_platform_role` checks `has_verified_totp` (≥1) for a non-null actor only; aal2 lives in the RPCs and policies. Nothing SQL changes.
- The two-factor rule elsewhere: V1-2_ANATOMICAL_SHEETS.md §5.7.1 (≈416 "two factors on two devices before the first grant on any stack"), §5.7.2 (≈551, ≈591), §5.7.7 (≈688, ≈699); IDENTITY.md ≈189 (recommendation). Production/operator procedure: unchanged.
- Harness stub (db-trial-check.sh ≈258-264): `txn-factors` file = the count the transaction finds; `< need` → "no rows returned for \gset", exit 3.
## Changes
1. scripts/db-trial.sh
- `grant_platform_role`: drop the owner branch; `local need=1 factors count` stays (owner and admin both need one). Keep `-v need="$need"` and `>= :need` (the recount stays in the transaction). Messages unchanged in shape ("$1 holds $count verified TOTP factor(s), $2 needs $need: …").
- [challenge] SQL comment inside the grant heredoc (≈1736-1737) "when one went away since the check, no row comes back" → "when fewer than :need remain since the check, no row comes back" (comment line only).
- Comment above `factor_count` (≈1696-1700): "Owner needs two verified TOTP factors, admin one" → one verified factor for owner and admin (owner decision 2026-11-11, db:trial only; a second factor is an optional backup; the rule for other stacks is V1-2 §5.7.1, unchanged).
- `cmd_account` hint (≈1693): "(two factors for the owner account)" → "(one factor; a second one is an optional backup)".
2. scripts/db-trial-check.sh
- ≈1213-1216: `set_factors 0`; owner refused: "owner needs 1" + "nothing was granted"; no role SQL ran. Rename the check names accordingly ("grant owner with no factor: refused (one needed), nothing assigned").
- [challenge: placement] Do NOT add the success case right after the zero-factor refusal (its grant SQL would stay in the stub stdin and break the `no_role_assigned` checks at ≈1220/1223). Add it right after the existing `set_factors 1` at ≈1236 and BEFORE the admin grant at ≈1237: `fresh_stdin; fresh_log; trial_tty 'grant owner' grant owner@trial.test owner`, check granted ("owner granted to owner@trial.test", rc 0) and `log_has "-v email=owner@trial.test -v role=owner -v need=1 -v operator="`; then `fresh_stdin` before the existing admin case so the admin checks stay as they are.
- ≈1217 `set_factors 2` and the following owner cases stay (wrong phrase, piped phrase, unreadable factors, failing role SQL, granted with factors shown): owner with two factors still granted (the optional backup case).
- ≈1234: `need=2` → `need=1`.
- ≈1316-1322: `echo 0 > txn-factors` (the transaction finds none: count 1 or 2 before, 0 inside) → nothing granted; check name "count then 0"; then `echo 1 > txn-factors` → granted ("one factor still there in the transaction: granted").
- No other check changes; no new helper; no shellcheck directive.
3. docs/development/SUPABASE.md §5.2
- grant row (≈867): "two for owner, one for admin" → "one for owner and for admin (owner decision 2026-11-11; a second factor is an optional backup)".
- first-use step 1 (≈874): "enrol two TOTP factors" → "enrol one TOTP factor (a second is an optional backup)", plus one sentence [challenge]: with one factor, a lost device means the operator recovery of V1-2 §5.7.7 at the trial database, or a new account granted through `grant`.
4. docs/development/V1-2_ANATOMICAL_SHEETS.md [challenge: anchor]: the dated note goes right after §5.7.1 step 2 (≈551-552, "the future owner signs in, enrols two TOTP factors on two devices…"), the procedure db:trial cites (script comment, audit reason "V1-2 contract 5.7.1", SUPABASE.md, TRIAL_STACK.md); the §5.6 sentence at ≈415-416 ("The owner enrols two factors on two devices before the first grant on any stack.") gets only a short pointer "(db:trial exception: §5.7.1)". Note text: "db:trial exception (owner, 2026-11-11): on the persistent trial stack of `pnpm db:trial` one verified TOTP factor suffices for the owner grant, as for admin; a second factor is an optional backup. This rule, for every other stack, production included, is unchanged until a distinct study and authorisation." No other contract line changes.
## Edge cases
- Zero factors / no account / unreadable count: refused before the confirmation (unchanged paths).
- A factor removed between the check and the transaction: recount `>= 1` → zero rows → rollback (pinned by the txn-factors=0 case).
- Admin, catalogue rights (has_verified_totp, is_platform_admin for editor/publisher), sanitised factor names: unchanged.
## Precondition (orchestrator, owner-approved 2026-11-11)
The harness refuses while the trial ports (58xxx, 5194) listen. Before dispatch the orchestrator stops the app and runs `pnpm db:trial stop` (data kept); after the gates it runs `pnpm db:trial start` and the app on 192.168.1.100. The executor never stops or starts anything; grants resume only after ALL PASS.
## Tests
- `bash -n`, `shellcheck -x` on both scripts.
- `bash scripts/db-trial-check.sh </dev/null` (fake Docker, ≈2.5 min; the real trial stack's ports must be free: if the harness refuses for a port in use, report BLOCKED, never stop anything).
## Disposition
- [challenge] BDR-083 (ratified 2026-10-28, decisions.md:611) says "first owner: enrol 2 factors first, role assigned last by operator", no stack carve-out: narrowed for db:trial only by a new BDR at CAPITALIZE (owner decision 2026-11-11); production and every other stack keep BDR-083 as is.
- `need` stays (fixed at 1) for the in-transaction recount and the stub's txn-factors emulation: the smaller diff.
- honors BDR-107..110 (trial stack design) by changing only the trial script's operator gate; honors the owner's "no production rule change" by leaving SQL, IDENTITY.md and the §5.7 procedure text intact with a scoped note; no in-force BDR requires two factors on the trial stack (the rule was a V1-2 §5.7.1 procedure line applied by the script).