fix(plugin-auth): /auth/change-password clears the force-change flag and enforces password-reuse on the bearer lane (#8049)

[os-zhuang]

Fixes#8049

An admin-provisioned user (mustChangePassword defaults to true) is gated out of every protected route with 403 PASSWORD_EXPIRED until they rotate their password. On the bearer lane — the documented API/agent/CLI lane — that escape hatch did not work: POST /auth/change-password answered 200, the password really rotated, and the caller stayed locked out forever.

Measured on origin/main before editing (both lanes, real HTTP)

	change-password	password rotated	must_change_password	password_changed_at	protected read	reuse of previous password
Cookie	200	yes	→ false	stamped	200	refused400 PASSWORD_REUSE
Bearer	200	yes	stays true	stays null	403 PASSWORD_EXPIRED	accepted, 200

The filer's premise is confirmed in full, including the security half.

Why this carries security, not just "a lockout"

One stash — ctx.context.__osPwChangeUserId, set by the before-hook when it resolves the acting user — gates three behaviours: the password_changed_at / must_change_password stamp, ADR-0069 D1's password-reuse rejection, and the history append. No principal resolved ⇒ none of them run. So the bearer lane did not merely stay flagged: password history was neither checked nor recorded there, and a user could immediately set their password back to the one just rotated away and be told 200. A control enforced on one transport and silently absent on the other is worse than one absent on both, because the console and every pre-existing pin exercise the working lane.

Cause

better-auth's getHooks (api/dispatch.mjs) pushes options.hooks.before — the auth manager's global before-hook — ahead of every plugin before-hook, and bearer()'s before-hook is what rewrites Authorization: Bearer into a session cookie. resolvePasswordChangeUserId used a bare getSessionFromCtx(ctx), which reads that cookie. On the bearer lane the cookie does not exist yet, so it resolved null — while better-auth's own password write, running after the conversion, succeeded. That is the 200 with nothing stamped.

Fix — one resolution site, not a second stamp site

1. /change-password now resolves through resolveActor, the pipeline's existing hook-order-independent resolver (cookie session first, explicit token lookup as fallback). All three behaviours hang off that one id, so both halves are fixed together.
2. resolveActor now strips the signature from a bearer credential the way it always did for cookies. bearer() hands clients the signed token.signature form in set-auth-token (the credential the issue's reproduction used) and accepts it back, while sys_session.token stores the unsigned value — so the credential the documented lane actually issues resolved nothing.

Point 2 is not cosmetic. See ablation B below: routing through resolveActor alone leaves the signed-bearer lane completely unfixed.

This also repairs the same lookup for the /sso/register admin gate, which shares the resolver.

Regression gate — both transports, same post-conditions

packages/qa/dogfood/test/bearer-lane-password-change.dogfood.test.ts drives /auth/change-password over cookie and over both accepted bearer spellings, asserting the same post-conditions on each: flag cleared, password_changed_at stamped, old password rejected, protected read 200, history appended, and a reused password refused. Rejection cases assert codeandstatus, and the two refusals are asserted distinctly — the gate refusal is the ADR-0112 REST envelope (403, error.code), the reuse refusal is better-auth's own APIError (400, code).

passwordHistoryCount defaults to 0 (off), which would make every reuse assertion vacuously green, so the suite arms it through applyConfigPatch — the same seam the settings service writes.

Predict-then-mutate ablation

Predictions were written down before running. Both matched exactly.

ablation	predicted	measured
A — both edits removed	6 green / 6 red; cookie lane whole, each bearer lane green only on the 403 gate test	6 passed / 6 failed, exactly those
B — only the signature normalization removed	9 green / 3 red; failures confined to the signed bearer lane	9 passed / 3 failed, exactly those

Ablation A failure text: must_change_password not cleared: expected true to be false, no password history recorded: expected [] to have a length of 1, expected 403 to be 200. Ablation B proves edit 2 is load-bearing rather than tidying.

Verification

• @objectstack/dogfood full suite: 96 passed | 1 skipped (97 files), 636 passed | 3 skipped
• @objectstack/plugin-auth full suite: 45 files, 1063 passed
• typecheck green for both packages
• check:nul-bytes, check:docs-audit-scope, check:test-source-alias, check:cross-package-test-inputs green
• check:type-check-debt green — plugin-auth TEST_DEBT measures 108 against the recorded ceiling of 131 (the −23 gap is pre-existing and repo-wide, tracked by [finding][devx] check:type-check-debt 的 ledger 余量会让新写的 pin 变哑：mongodb 曾有 33 条余量吞掉一次真实回退，另有 5 条目前带 4–19 余量 #6376; not moved here)

No behaviour change on the cookie lane.

Generated by Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 12, 2026 3:24pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-auth.

8 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/deployment/cli.mdx(via @objectstack/plugin-auth)
• content/docs/deployment/production-readiness.mdx(via @objectstack/plugin-auth)
• content/docs/kernel/contracts/cache-service.mdx(via @objectstack/plugin-auth)
• content/docs/kernel/services-checklist.mdx(via @objectstack/plugin-auth)
• content/docs/permissions/authentication.mdx(via @objectstack/plugin-auth)
• content/docs/permissions/sso.mdx(via @objectstack/plugin-auth)
• content/docs/plugins/index.mdx(via @objectstack/plugin-auth)
• content/docs/plugins/packages.mdx(via @objectstack/plugin-auth)

⛔ 2 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/plugin-auth)
• content/docs/releases/v9.mdx(via @objectstack/plugin-auth)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.