docs(e2e): document the TOTP secret invariant + mismatch recovery (BUNYIP-454) #448

Merged

nrupard merged 1 commit from docs/BUNYIP-454-e2e-totp-invariant into main

2026-08-03 20:56:17 +02:00

nrupard commented

2026-08-03 20:50:56 +02:00

Owner

BUNYIP-454 (relates BUNYIP-445). Closes the E2E 2FA saga with a docs playbook so it does not recur as folklore.

What

docs/e2e.md's 2FA provisioning section gains:

An invariant + recovery callout: the account's enrolled secret (--enable-2fa) and E2E_STAGING_TOTP_SECRET (Forgejo Actions secret -> E2E_TOTP_SECRET) must be byte-identical. A mismatch rejects every code and fails the FIRST 2FA submit (setup + login.spec throw "TOTP rejected on both attempts"). Forgejo secrets are write-only, so pick one base32 S, set the Forgejo secret = S, and re-run BUNYIP_E2E_TOTP_SECRET=S just e2e-bootstrap --enable-2fa. Distinguished from the single-use second-login collision that lib/login.ts retries (BUNYIP-453).
A correction of the stale "survives re-seeds / on every wipe" wording: the c-01 Postgres is a persistent external volume with no reseed mechanism, so one correct enrollment holds (this is why the fix is one-time).

Docs only.

🤖 Generated with Claude Code

BUNYIP-454 (relates BUNYIP-445). Closes the E2E 2FA saga with a docs playbook so it does not recur as folklore. ## What `docs/e2e.md`'s 2FA provisioning section gains: - An **invariant + recovery** callout: the account's enrolled secret (`--enable-2fa`) and `E2E_STAGING_TOTP_SECRET` (Forgejo Actions secret -> `E2E_TOTP_SECRET`) must be byte-identical. A mismatch rejects every code and fails the FIRST 2FA submit (setup + login.spec throw "TOTP rejected on both attempts"). Forgejo secrets are write-only, so pick one base32 `S`, set the Forgejo secret = `S`, and re-run `BUNYIP_E2E_TOTP_SECRET=S just e2e-bootstrap --enable-2fa`. Distinguished from the single-use second-login collision that `lib/login.ts` retries (BUNYIP-453). - A correction of the stale "survives re-seeds / on every wipe" wording: the c-01 Postgres is a persistent external volume with no reseed mechanism, so one correct enrollment holds (this is why the fix is one-time). Docs only. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

nrupard added 1 commit

2026-08-03 20:50:56 +02:00

docs(e2e): document the TOTP secret invariant + mismatch recovery

E2E PR gate / Install + reachability (no deployment secrets) (pull_request) Successful in 22s

Details

Check / fmt + clippy + build + tests (pull_request) Successful in 2m42s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

24c8a60fe9

The E2E 2FA failures (BUNYIP-445 and children) all traced to the account's enrolled 2FA secret not matching E2E_STAGING_TOTP_SECRET, and docs/e2e.md stated the invariant only in passing with no recovery playbook. Add a callout: the enrolled secret and E2E_STAGING_TOTP_SECRET must be byte-identical; a mismatch fails the FIRST 2FA submit every time (setup + login.spec throw "TOTP rejected on both attempts"); Forgejo secrets are write-only so set both to one chosen base32 S and re-run just e2e-bootstrap --enable-2fa. Distinguish that from the single-use second-login collision that lib/login.ts retries (BUNYIP-453). Also correct the stale "survives re-seeds / on every wipe" framing: the c-01 Postgres is a persistent external volume with no reseed, so one correct enrollment holds.

#BUNYIP-454

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>