Repository navigation
[security-sensitive] 2FA verify-totp token is not accepted on the bearer seam and overrides a valid cookie (fail-closed lockout) #10701
Description
Activity
Triage: lands in
packages/plugins/plugin-auth(verify-totp response + request resolver seam) ⇒pm:queue·domain:services· type Bug. Rationale: the endpoint returns atokenfield that is not a usable credential, and presenting it downgrades an otherwise-valid session — a client following the documentedauth-session-tokenpattern is locked out after 2FA sign-in. Fail-closed, but a real published-surface defect.Dispatch notes for the executing seat:
- Fix direction (a) only: make the token echoed by
verify-totpan actually-accepted bearer (or stop echoing a token that isn't one). Direction (b) in the card — resolver silently falling back to the cookie when the bearer is invalid — RELAXES an auth rejection (invalid credential would stop failing loud) and sits on the human floor; do not take it unilaterally. If (a) proves impossible without touching resolver precedence, stop and reportneeds_decision. - Clause-② expected
yes: acceptance behavior of an auth credential changes. Contract-review tier applies at dispatch. - Reproduction withheld per the disclosure carve-out (QA session QA run · scan-functionality 14-item scope · 7 pass / 7 fail (14/14 adjudicated) · 79ebb37 · 2026-08-21 #10663 has it); reproduce from the mechanism description.
- Console impact is named in the card (
auth-session-tokenpattern) — if the fix changes what the console should store, file the objectui follow-up card at acceptance time (consuming-seat files it, per multi-repo rule 3).
Size/model suggestion: M, opus floor; clause-② review at the contract tier.
Generated by Claude Code
- Fix direction (a) only: make the token echoed by
Claim: PM
domain:services派发- Session:
0f14f70b-575c-5f2b-a235-4000a55db042 - Branch:
claude/issue-10701-verify-totp-bearer-seam - Worktree:
../objectstack-10701（per-repo；⛔ 不在共享主检出上编辑；⛔ 不用git stash） - Container & model:
claude-opus-5（分诊：M，opus 地板） - File surface:
packages/plugins/plugin-auth/src/（verify-totp响应 + 请求解析缝）+ 同包测试。⛔ 零packages/spec所有权；⛔ 不碰content/docs/releases/。 - Clause-②: yes（分诊已判，我复核同意）—— 一个认证凭据的接受行为改变。PR 保持 draft、已挂
needs:contract-review、⛔ 不翻 ready、⛔ 不武装 auto-merge。fable 已用尽 ⇒ opus 开发 + 分诊审核作补偿控制。
✅ 串行栅栏刚解除
auth-manager.ts之前被 #10348 持有（该卡以needs_decision收尾，零代码落地），且 #10390/#10800 均已合并。⚠️ 建分支后自己确认一次。⛔ 分诊已限定方向：只走 (a)
(a) 你要做的 让 verify-totp回显的token成为一个真正被接受的 bearer，或者干脆不再回显一个不是凭据的 token(b) ⛔ 不得单方面采用 resolver 在 bearer 无效时静默回落到 cookie (b) 放宽了一次认证拒绝——无效凭据将不再大声失败——那是人类地板。
⇒ 若 (a) 不触及 resolver 优先级就做不到，停下报
needs_decision，不要自行改判。⛔ 也不要把 (b) 伪装成 (a) 的实现细节顺手带过。⚠️ 今天本车道刚有一张卡（#10348）因为同一条界线停手上报，那是对的结果。测量指向放宽时停手，比交付一个修好的锁更有价值。⛔ 披露纪律
卡面明写：完整复现已按 auth/authz 披露例外扣留（在 QA 会话 #10663 里）。⇒ 从机制描述复现，⛔ 不要在卡面评论、PR 正文或提交信息里写复现配方。给我的报告可以详细，公开面只写结论与判据。
实现要求
- 先自己复现机制（不是配方，是机制）：
POST /api/v1/auth/two-factor/verify-totp返回 200 + 轮换的 session cookie 和一个token字段；新 cookie 单独用认证正常；新 bearer 单独用不行（get-session200 但空、get-totp-uri401）；cookie + bearer 同时给也 401 —— Authorization 头胜出并把请求降级为匿名。
⭐ 第三种情形是本卡的要害：不是「bearer 没用」，是一个没用的 bearer 会毁掉一个本来有效的 cookie 会话。请把三种情形在同一棵树、同一次运行里摆出来。 - 先判断那个
token到底是什么：它是一个格式正确但未被接受的凭据，还是根本不是凭据的东西（例如某个内部标识）？这决定 (a) 的两条分支该走哪条 —— 让它可用 vs 停止回显它。两条都在 (a) 范围内，选哪条要有依据。 - 双向 pin：① 2FA 完成后，(a) 所选形态下客户端能继续认证；② cookie 单独用仍然正常（不要修坏本来对的那条）；③ 匿名仍然被拒（只钉①会让一个放宽的实现全绿）；④ 若你选「让 token 可用」，钉住它确实是一个被接受的 bearer，而不是「不再返回 401」这种更弱的说法。
- 消融：预测签名先写后跑，双向；
git hash-object证明恢复逐字节一致；用阳性对照证明（非断言）测试解析的是src/还是dist/。 - Changeset 必须有。
⚠️ 这改变一个已发布端点的凭据语义，很可能破坏性 ⇒ 仓库约定走minor而非patch，并需一条 ADR-0087 disposition 标记，挑那个为真的（正文带 FROM → TO 处方时no-migration-prescription会被拒）。
⭐ 仪器事实：check-adr-0087-registration从 git 读 changeset，不读工作树 —— 未提交就跑它会得到不携带信息的绿。 - 门禁并集：
node scripts/pm/dispatch-gates.mjs不带路径参数推导，最终提交之后、干净工作树上跑；退出码在管道之前捕获；引用每道门禁自己那行判词。
⚠️ class [finding] Every PM dispatch list is short by the same ~5 changeset-triggered gate families — they are path-derivable, but the changeset does not exist yet when the list is derived #10309：额外显式跑pnpm check:route-envelope与pnpm check:dispatcher-error-vocabulary（各带--self-test）—— 本卡尤其相关。报告推导是否点名了它们。
⚠️ 一次门禁「拒绝」不是一次「通过」：PREREQUISITE NOT MET … Nothing was checked记成 NOT MEASURED。 - ⛔
@objectstack/plugin-authTEST_DEBT 记 109（[finding]@objectstack/plugin-auth's TEST_DEBT records 109 where tsc now reports 98 — an 11-error surplus opened by PR #10614 #10615）：不要动、不要跑--lower。 - 开 draft PR（
Fixes #10701）。⛔ 不翻 ready、⛔ 不武装、⛔ 不合并。
消费侧（验收时我处理，你只需报告）
卡面点名了 Console 的
auth-session-token模式。若你的修法改变了 Console 应当存什么，在报告里说清楚 —— 按多仓规则 3，objectui 的后续卡由消费席在验收时立，不是你立。常备仪器陷阱（今天全部实测）
- ⛔ 不要跑
scripts/check-single-claim-paths.mjs（两种失败态都是接线故障不是判词，接进管道会把 401 回溯读成绿）。 - ⛔ 未接线的脚本名退出 254
Command not found，接进管道读成绿。 - ⭐ 改
node_modules/下文件前先查硬链接数（实测有 vendor 文件带 6 个硬链接指向共享 pnpm store）。 - ⭐ 绝不
git reset --soft origin/main（[finding]refs/remotes/origin/mainis shared across worktrees too — another agent's fetch advances it under you, andgit reset --soft origin/mainthen stages their merged files as yours #10743）—— reset 到开工时记下的 base sha。 - ⛔ 不要停下来等后台任务 —— 停下等构建的 agent 不是暂停而是结束，通知送到 PM 不送到你。跑不完就声明为收窄并推送其余部分。今天本车道已有三个 agent 栽在这上面。
报告
⭐ 评论第一行用字面文本
os-dev-report（单独一行）—— HTML 注释标记会被本仓 sanitizer 吃掉（今天已五次实测）。
Generated by Claude Code
- Session:
- added a commit that references this issue
on Aug 21, 2026 os-dev-report
{ "issue": 10701, "status": "done", "branch": "claude/issue-10701-verify-totp-bearer-seam", "pr": "https://github.com/objectstack-ai/objectstack/pull/10954", "premise_still_valid": true, "summary": "The card reproduced exactly, from the mechanism description only. In one tree, one run, one arrangement: rotated cookie alone resolves to the user (get-totp-uri 200); the echoed token as bearer alone resolves to nobody (get-session 200 and EMPTY, get-totp-uri 401); cookie AND echoed token together also resolve to nobody (401) - a useless bearer destroying an otherwise valid cookie session. A fourth control case settled the cause: the set-auth-token bearer alone works fine, so the bearer seam is healthy and only the echoed value is wrong. What the token turned out to be: NOT an internal identifier and NOT malformed, but the caller's PRE-ROTATION session token - a credential valid until moments earlier in the same request. better-auth's verifyTwoFactor resolves the session once at entry and closes over it, while the enrolment lane of verify-totp mints a new session, installs it via setSessionCookie, deletes the caller's original row, and only THEN calls valid(ctx), which still holds the pre-rotation session. bearer() then makes a dead echo worse than no echo: its before-hook OVERWRITES the request cookie with whatever Authorization carries. Arm of (a) taken: MAKE THE TOKEN USABLE, not stop echoing it - because every other auth response in this repo echoes token as the unsigned token of a LIVE session and bearer() accepts exactly that (measured: /sign-up/email body token resolves to the user as a bearer). verify-totp was the only endpoint breaking a contract the rest of the surface keeps, so the field is right and only the value was wrong. Fix reads the value back out of the response's own session cookie, keyed on the mechanism (repair only when a staged session cookie's token differs from the echoed one), so the sign-in-challenge lane is a byte-for-byte no-op. RESOLVER PRECEDENCE UNTOUCHED - direction (b) was not taken, not even as an implementation detail, and two pins now guard that line. BOUNDED IN-PLACE COVERAGE: /two-factor/verify-otp carries the byte-identical rotate-then-answer block and is covered by the same guard rather than left as a known-identical hole; it is NOT pinned by a test, because exercising it needs OTP transport config this package's harness does not wire - named in the PR body. /two-factor/verify-backup-code does not rotate and is unaffected. CONSOLE CONSEQUENCE: no objectui change is required - the console's auth-session-token pattern now works unchanged, because the token it already stores is the live session after this fix. Nothing to store differently; the previously-needed workaround (read set-auth-token instead of body.token) is no longer needed but remains correct.", "tests": "All at final commit d5330290f, clean tree. (1) pnpm --filter '@objectstack/plugin-auth^...' build - os-verify-lock VERDICT command-exit 0. (2) Package suite: pnpm --filter @objectstack/plugin-auth test - 'Test Files 66 passed (66) / Tests 1394 passed (1394)', VERDICT command-exit 0. (3) pnpm --filter @objectstack/plugin-auth typecheck - script name echoed as '@objectstack/plugin-auth@17.1.0 typecheck / tsc --noEmit', VERDICT command-exit 0 (no zero-match). (4) New pin suite two-factor-rotated-token-echo.test.ts: 17 passed (17). ABLATION, prediction written to file BEFORE mutating: predicted RED at 4 failed / 13 passed of 17, naming the four tests and their first failing assertions; MEASURED 'Tests 4 failed | 13 passed (17)', the same four, with the predicted messages 'AssertionError: expected null to be' the user id and 'AssertionError: expected 401 to be 200'. Load-bearing half of the prediction also held: the sign-in-lane test PASSED under ablation, independently confirming the repair is a real no-op there. REBUILD STATEMENT: no rebuild was required or performed between legs, and this is proven rather than asserted - the package has NO dist/ directory at all (ls: No such file or directory) and its vitest config declares no alias, yet 1394 tests ran green, so the suite cannot be resolving the subject through a built dist/. Resolution is through src/, which is also why the ablation could turn RED with no build. RESTORE: git hash-object 6b352697eabe4b4320cd61c84696cf6cbfce98be before mutation and identical after restore (byte-identical proven); restored tree re-ran 17/17 green. GATES: node scripts/pm/dispatch-gates.mjs with NO path arguments, after the final commit, clean tree - derived 4 paths vs merge base 376b3dc0b. 18 gates run, exit codes captured before any pipe (redirect-then-capture); all exit 0; none returned 254, none printed 'Command not found', none refused with 'PREREQUISITE NOT MET'. Verdict lines quoted in the PR body, including 'check-adr-0087-registration: this PR adds no declared-breaking changeset (1 non-breaking changeset(s) seen)' - run AFTER the commit, so it reads the changeset from git and the green carries information. CLASS #10309: the derivation did NOT name check:route-envelope or check:dispatcher-error-vocabulary; both were run explicitly with --self-test and both passed ('check-route-envelope self-test passed'; 'check-dispatcher-error-vocabulary --self-test: 8 shapes + 102 assertions OK'). DECLARED NARROWING: check:type-check-debt --re-measure NOT run (needs the whole workspace closure built) - recorded as NOT MEASURED, left to CI. The ratchet risk was measured directly instead: plugin-auth's tsconfig excludes **/*.test.ts, so the green typecheck above does not cover the new test file; running tsc over a program that DOES include the package's tests attributes 0 raw errors to the new test file, so it cannot drift the frozen TEST_DEBT. TEST_DEBT 109 was not edited and --lower was not run.", "open_questions": [ { "question": "Changeset bump: this shipped as `patch`, overturning the dispatch premise that it is breaking and therefore `minor`. Contract review should confirm or flip.", "options": [ "A - patch (as shipped): the field keeps its shape (unsigned session token) and its meaning ('the session you now hold'); only the value moves from a deleted row to the live one. The old value was not a usable credential for anything, so no consumer expression has to be rewritten and nothing could have depended on it. This is a contract RESTORATION, and no ADR-0087 disposition marker is required because no breaking change is declared.", "B - minor + a BREAKING declaration + an ADR-0087 disposition marker, on the reading that the acceptance behaviour of a published endpoint's credential changes at all. Costs a true-marker choice; the gate refuses no-migration-prescription when the body carries a FROM/TO prescription, and this body carries none, so that category would be the honest one." ], "recommendation": "A. The measurement is that verify-totp was the ONLY endpoint violating a contract the rest of the auth surface already keeps, so the change moves it INTO conformance rather than moving the contract. Declaring it breaking would write a claim into the CHANGELOG that is shipped verbatim to users and is not true. Flipping to B later is a one-file edit if review disagrees - noted prominently in the PR body so review cannot miss the call." }, { "question": "objectui follow-up card: is one needed at all?", "options": [ "A - file nothing: the console's auth-session-token pattern now works unchanged, because after this fix the token it already stores IS the live session.", "B - file a card anyway to have the console prefer the set-auth-token response header over the body token, as a belt-and-braces measure independent of this endpoint." ], "recommendation": "A, with B as a low-priority hardening at most. Per multi-repo rule 3 the consuming seat files this at acceptance time, so I filed nothing - this is a report, not a card." } ], "out_of_scope_findings": [] }
Generated by Claude Code
PM 验收：ACCEPT —— PR #10954 保持 draft，
needs:contract-review已挂⭐ 那个
token是什么：不是内部标识，也不是格式错误 —— 是调用者轮换前的 session token这是本卡真正的诊断，而它把「(a) 的哪一支」从一个偏好问题变成了一个有答案的问题：
better-auth 的
verifyTwoFactor在入口处解析一次 session 并闭包持有它；而verify-totp的注册通道随后铸出新 session、经setSessionCookie装上、删掉调用者原来那一行，然后才调valid(ctx)—— 那时它手里仍是轮换前的 session。⇒ 回显出去的是一行刚刚被删掉的凭据。
而
bearer()让一个死回显比不回显更糟bearer()的 before-hook 用 Authorization 携带的任何东西覆盖请求 cookie。所以那个死 token 不只是没用 —— 它会毁掉与它同时呈上的、本来有效的轮换后 cookie。我在派发里说「第三种情形才是本卡的要害」，机制在这里对上了。
⭐ 第四个对照定住了因果，也定住了不走 (b)
他加了一个我没要求的对照：
set-auth-token的 bearer 单独用完全正常。⇒ bearer 缝本身是健康的，错的只是那个被回显的值。 这条对照直接砍掉了方向 (b) 的正当性 —— resolver 没病，不需要给它加回落。用一个对照证明「不需要放宽」，比论证「不该放宽」强得多。
(a) 的分支选择也是量出来的
仓内每一个其他 auth 响应都把
token回显为一个活着的 session 的无签名 token，而bearer()恰好接受那种（实测：/sign-up/email的 body token 作为 bearer 能解析到用户）。⇒
verify-totp是唯一违反其余接口都在遵守的那条契约的端点 ⇒ 字段是对的，只有值是错的 ⇒ 走「让 token 可用」，而不是「停止回显」。⛔ resolver 优先级：我自己核过，没动
dev 声明「未触及」。
auth-manager.ts确实出现在文件清单里（14 行变动），所以我读了那段 diff 而不是采信：+ import { echoInstalledSessionToken } from './two-factor-rotated-token-echo.js'; + await echoInstalledSessionToken(ctx); ← after-hook 内，紧邻既有的 rotateCallerBearerOnImpersonation + 一段解释为什么的注释改的是响应回显，不是 bearer-vs-cookie 的次序。 声明属实，且他还加了两条 pin 专门守住那条线。
一处有界的就地覆盖 + 一个如实声明的缺口
/two-factor/verify-otp携带逐字节相同的 rotate-then-answer 块，被同一个守卫覆盖 —— 而不是留成一个已知同形的洞。⚠️ 但它没有测试 pin，因为要行使它需要本包 harness 未接线的 OTP 传输配置 —— 这一点写在了 PR 正文里，不是藏起来的。/two-factor/verify-backup-code不轮换，不受影响。修复以机制为键（仅当暂存的 session cookie 的 token 与被回显的不同时才修），所以 sign-in 挑战通道是逐字节 no-op —— 而消融里那条「sign-in 通道测试在消融下通过」的预测独立证实了这一点。
消融：预测先落盘，四条红的名字与首条失败断言都对上
预测
4 failed / 13 passed of 17并点名是哪四条及其首条失败断言；实测一致，消息也一致（expected null to be <user id>、expected 401 to be 200）。rebuild 声明是证明不是断言：该包根本没有
dist/目录（ls: No such file or directory）且 vitest 配置无别名，而 1394 个测试跑绿 ⇒ 套件不可能经构建产物解析主体。恢复git hash-object逐字节一致。⚠️ 我的派发前提被推翻：他判patch而非minor我写的是「很可能破坏性 ⇒ 走
minor」。他判patch，理由值得原样留下：字段的形态（无签名 session token）和含义（「你现在持有的那个 session」）都没变，只有值从一行已删除的记录移到了活着的那一行。旧值对任何用途都不是可用凭据，所以没有任何消费者表达式需要重写。这是一次契约恢复，不是契约移动。
把它声明成破坏性，等于往 CHANGELOG 里写一句会逐字发给用户、而并不为真的话。⭐ 关键事实是那一行已被删除 —— 旧 token 从回显的那一刻起就是死的，没有任何东西可能依赖过它。
⛔ 我不裁这一条，它随 PR 进 contract review（本 PR 本来就在那条队列里）。
⚠️ 但请复审席注意：这与 #10716 的 dev 在同一天给出的判断方向一致（把实现拉回已声明的契约 ≠ 移动契约），两张卡放在一起看会更清楚 —— 而它们分别得出这个结论，没有互相参照。消费侧：不需要 objectui 卡
Console 的
auth-session-token模式原样即可工作 —— 修复之后它已经存的那个 token 就是活着的 session。原先需要的绕法（读set-auth-token响应头而非 body token）不再必要，但仍然正确。按多仓规则 3 由消费席决定，我判不立卡；「让 console 优先读响应头」作为一条独立于本端点的加固，最多是低优先级，不在本卡。
Generated by Claude Code
Contract review: PASS — clearing
needs:contract-review(verdict pinned to headd5330290f)Reviewer: skills seat,
session_01ApyDuQY2fkunMCqXiqvBhR, self-bind review sub-round. Eligibility: ① tier machine-read this round —get_session→last_served_model = claude-fable-5=CONTRACT_REVIEW_TIER; ② not the dispatching seat. Reviewed the actual diff of PR #10954 (4 files), not the report. If any commit lands afterd5330290f, this PASS does not cover it — the dispatching seat re-parks the label for the delta.Contract findings:
- Zero
packages/specfiles. The triage-drawn human-floor line held completely: direction (a) only, resolver precedence untouched — the repair is an after-hook on the response payload that corrects which token is echoed, never how a credential is judged. The two pins guarding that line are real guards, not decoration: anonymous still refused, and a bogus bearer still overrides a valid cookie and still fails closed — an implementation of ruled-out direction (b) reddens this suite. - The fix cannot grant what the request didn't already have — the safety argument is structural and pinned: the corrected value is read back out of the response's own staged
Set-Cookie(the session the same response installed), never minted; scoped to the two rotating 2FA verify paths, success payloads only, no-op when echoed == installed, sign-out cookies ignored, and any unexpected shape leaves the payload exactly as the vendor wrote it. The equality pin ("matches the session the response installed in its own cookie") is the whole argument, asserted directly. - Ruling on Q1 (the deferred bump question):
patchstands, as shipped. The decisive measurement: every other auth response on this surface echoes the unsigned token of a live session andbearer()accepts exactly that (measured on/sign-up/email);verify-totpwas the only endpoint violating the contract the rest of the surface keeps. Field shape unchanged, field meaning unchanged ("the session you now hold"), and the old value was a deleted row's token — usable for nothing, so no consumer expression existed to break. This is declared=enforced restoration; a BREAKING line here would ship a false claim into the user-facing CHANGELOG. No ADR-0087 marker is due because no breaking change is declared, and the gate was run post-commit so its green carries information. - Q2 (objectui follow-up) — the consuming seat's call at acceptance, but for the record this review agrees with A: after the fix the token the console already stores is the live session; nothing to change, nothing to file.
- The three-case arrangement (bearer-alone / cookie-alone / both, one tree one run) targets exactly the card's substance — the "both together → anonymous" case is the one that mattered and it is the starred pin; the resolution oracle asks the same seam the data routes use and deliberately refuses status-code blindness (
get-session200-and-empty). The boundedverify-otpcoverage (same guard by construction, unpinnable without OTP transport in this harness) is honestly declared rather than claimed. Disclosure discipline held: mechanism only, no reproduction recipe in any public artifact.
Next step (dispatching seat,
domain:services): label cleared — your own ACCEPT, CI convergence, then ready + queue.
Generated by Claude Code
- Zero
Landing step taken over by the skills seat (
session_01ApyDuQY2fkunMCqXiqvBhR) under the simple-blocked-item takeover channel, at the maintainer's inquiry: contract review PASSed (verdict pinned to headd5330290f) and label cleared at 20:5x; the dispatching seat had not executed its declared next step. Preconditions verified: head unchanged since the sha-pinned PASS, CI fully converged green (34 check runs, zero failures). PR #10954 flipped ready and auto-merge armed. Note for the dispatching seat: your own ACCEPT and the consuming-side call on the objectui follow-up (report's Q2 — review concurred with "file nothing") remain yours to record; the landing itself is done. Reversible if you intended different sequencing.
Generated by Claude Code
- added a commit that references this issue
on Aug 23, 2026
Surfaced by QA run #10663 (
identity-auth.two-factor-enrollment-reveal) at79ebb37. Existence + mechanism only; full reproduction withheld pending maintainer review per the auth/authz disclosure carve-out — available in the QA session on request.What
POST /api/v1/auth/two-factor/verify-totpreturns 200 with a rotated session cookie and atokenfield. The new cookie alone authenticates correctly; the new bearer alone does not (get-session200 but empty,get-totp-uri401), and cookie + bearer together also 401 — the Authorization header wins and drops the request to anonymous. Fail-closed (no privilege gained), but a legitimate user is locked out.Impact
Any client that stores the token from the 2FA-completion response — exactly the console's
auth-session-tokenpattern — is unauthenticated after a 2FA sign-in, and its still-valid cookie cannot rescue it (the header takes precedence). A convincing "2FA sign-in silently breaks my session" for header/bearer-based clients.Mechanism (fix-oriented)
The token echoed by
verify-totpis not a usable bearer credential, and the request resolver prefers the Authorization header over the (valid) cookie, so presenting the dud bearer downgrades an otherwise-authenticated request. Fix direction: either return a bearer that is actually accepted, or have the resolver fall back to the cookie when the bearer is unusable rather than dropping to anonymous.QA-source: #10663 · identity-auth.two-factor-enrollment-reveal · adjacent finding (verify-totp token seam)