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

6.5 KiB

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).