fix(platform-objects): Rotate Client Secret result dialog states the immediate cut-off, not a grace period

[objectstack-fleet]

Fixes #24774

Clause-②: no (text only: no accept set, served shape or behaviour moves)

Dispatched by the domain:engine seat 1 PM (session_01JtSQQ3EWsbNPzyYMug1tXy, claim 6289452299). Developer session: session_01MrvwG9BMeMc4oCSG9FsV95.

What rotation does to the previous secret (read first)

• POST /api/v1/auth/oauth2/client/rotate-secret is better-auth's own route. plugin-auth only lists it in auth-route-ledger.ts, and nothing in this repository wraps it.
• In the pinned @better-auth/oauth-provider 1.7.3, rotateClientSecretEndpoint (dist/authorize-9whjxVLJ.mjs) generates a new secret and runs one adapter.update that overwrites the client's single clientSecret column. No previous secret is stored anywhere.
• Client authentication, validateClientCredentials (dist/utils-oOcdCCVw.mjs), checks a presented secret against that one stored client.clientSecret through verifyStoredClientSecret. There is no second value to match.
• Result: an immediate cut-off. The old secret is refused from the moment the rotation's update commits. No grace period exists. The code leaves no doubt, so no booted measurement was made.
• No document promises a window. content/docs/protocol/objectui/actions.mdx already says "The current secret stops working immediately". So the confirmation was true and the result dialog was false. The behaviour itself is not in question here.

Change

• sys-oauth-application.object.ts, rotate_client_secret:
  • description (the confirmation) is unchanged. It was already true.
  • resultDialog.description now reads "Save the new secret now — it is shown only once. The previous secret has already stopped working: update every integration with the new secret." The shown-once sentence, the title, the acknowledgement and the client_secret field are kept.
  • A comment names the handler and why there is no grace period.
• Translation bundles:
  • en.objects.generated.ts was regenerated with pnpm i18n:extract, and only that one line moved.
  • zh-CN, ja-JP and es-ES all carried a translated grace-period sentence. These are hand-written translated values, not byte copies, so they have no source-hash entry. The extractor keeps them in merge mode, and the staleness rule ("a path with no entry is LEGACY-TRUSTED and never reported stale") would never flag them. So I re-translated the value by hand in each locale. No keys were added or dropped. check:i18n is in sync.

Pins

• New packages/platform-objects/src/identity/rotate-client-secret-copy.test.ts:
  • in the source, the confirmation says the previous secret "will stop working immediately", the result dialog says it "has already stopped working", and neither text mentions a grace period, a window or an expiry;
  • the result dialog keeps its shown-once sentence, its acknowledgement and its secret field;
  • the en bundle mirrors the source;
  • in each of the four locales, neither text promises a grace period (宽限, 猶予, gracia and similar words), and each translated result dialog is a real translation, not the English text.
• Normally this repo does not pin copy. It does here because the card's defect is the wording itself, and the card asked for the pins.
• Ablation, with the fix committed, through scripts/ablation-replace.mjs. Each mutation was confirmed on disk, and each restore was proven by blob hash against HEAD. There is no dist leg: the test imports src relatively.
  • Source leg: the old grace-period sentence put back into resultDialog.description (blob d5ffc56c6b52 to 4f08d6f86141). 2 failed, 2 passed (4). The source-agreement test and the en-mirror test went red. Restored to d5ffc56c6b52.
  • Locale leg: the old zh-CN grace-period sentence put back (blob 65c34bca849d to 0b3f3e584462). 1 failed, 3 passed (4): zh-CN resultDialog.description promises a grace period. Restored to 65c34bca849d.
• Pin sweep: I searched every package, qa/, docs/qa/platform-checklist/ and content/docs/ for the old and new strings and for rotate_client_secret.
  • action-confirm-one-dialog.test.ts pins the unchanged confirmation ("stop working immediately", "shown only once"). It stays green and does not move.
  • No other pin reads the result-dialog text. No docs/qa/platform-checklist/** item names this action.

Verification record

Base abd5acdaf7, merged with origin/main 9a06f0be0 before opening (the merge touched nothing in platform-objects). All results are on head c41eb1949.

Command	Result
pnpm --filter @objectstack/platform-objects typecheck	exit 0. The new test is in tsconfig.test.json's program (--listFiles: 1 hit).
pnpm --filter @objectstack/platform-objects test (full suite)	exit 0, 80 files, 1203 tests passed
pnpm --filter @objectstack/core test:repo	exit 0, 6 files, 82 tests passed
pnpm exec turbo run build --concurrency=2 (whole workspace, docs excluded, after the merge)	exit 0, 76 of 76 tasks
vitest run of runtime's src/action-execution-destructive.test.ts (this action's consumer test), against the rebuilt platform-objects dist	exit 0, 63 passed
vitest run of cli's test/platform-page-i18n-parity.test.ts and test/i18n-extract-action-description.test.ts	exit 0, 34 passed
dispatch-gates.mjs --commands --repo objectstack-ai/objectstack: 66 derived commands, each run with its exit code captured before any pipe	66 of 66 exit 0. --ran (each line recorded as COMMAND :: exit CODE): "66 derived famil(ies) accounted for — 66 run, 0 NOT-MEASURED (a DERIVED zero — all 66 recorded an exit code and none of them is 3)"

On the first run, check:i18n and check:dual-build-cjs-loads exited 3 (PREREQUISITE NOT MET: no dist/). I built the whole workspace, and both then exited 0.

Siblings

This PR regenerates one line of the platform-objects en bundle and changes one value in each of the three translated bundles. Whichever of #24758, #24765 and this one lands second re-derives the bundles with scripts/pm/os-regen-merge.sh.

Acceptance notes

• The YAML example in content/docs/protocol/objectui/actions.mdx ("Create via API with secret reveal") gives target: /api/v1/auth/sys-oauth-application/rotate-secret. That is not the route the shipped action calls (/api/v1/auth/oauth2/client/rotate-secret). It is an illustrative docs example, and its own copy already says the cut-off is immediate. Noted, not filed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MrvwG9BMeMc4oCSG9FsV95

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/platform-objects, touching 1 documentable anchor(s).

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/permissions/authorization.mdx (via sys_oauth_application (symbol, a field of const object enObjects; a field of const object esESObjects; a field of const object jaJPObjects; a field of const object zhCNObjects))
• content/docs/protocol/objectui/actions.mdx (via sys_oauth_application (symbol, a field of const object enObjects; a field of const object esESObjects; a field of const object jaJPObjects; a field of const object zhCNObjects))
• content/docs/ui/setup-app.mdx (via sys_oauth_application (symbol, a field of const object enObjects; a field of const object esESObjects; a field of const object jaJPObjects; a field of const object zhCNObjects))

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 3 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 6b9e6df909dade0e2e2f2e4ee90de22fefff2a91 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 49e6550ad08256b76573ea0bb6e97d912a297dbc — the merge of head c41eb194965fe4833bcf55aded03474e5ed79bf3 into base 6b9e6df909dade0e2e2f2e4ee90de22fefff2a91, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 49e6550ad08256b76573ea0bb6e97d912a297dbc && git checkout 49e6550ad08256b76573ea0bb6e97d912a297dbc
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 6b9e6df909dade0e2e2f2e4ee90de22fefff2a91 c41eb194965fe4833bcf55aded03474e5ed79bf3 && git checkout -B drift-repro 6b9e6df909dade0e2e2f2e4ee90de22fefff2a91 && git merge --no-ff c41eb194965fe4833bcf55aded03474e5ed79bf3

node scripts/docs-audit/affected-docs.mjs --json 6b9e6df909dade0e2e2f2e4ee90de22fefff2a91

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 6b9e6df909dade0e2e2f2e4ee90de22fefff2a91 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: TIER_DEFAULT
Head-sha: c41eb194965fe4833bcf55aded03474e5ed79bf3
Local-runs: probe — read @better-auth/oauth-provider 1.7.3 (the version pnpm-lock.yaml pins) from its npm tarball into the seat's scratch space, to check the PR's one behavioural claim
Scope: the net diff (7 files, +101/−5): .changeset/24774-rotate-secret-cut-off-copy.md, packages/platform-objects/src/identity/sys-oauth-application.object.ts, the four packages/platform-objects/src/apps/translations/*.objects.generated.ts, and packages/platform-objects/src/identity/rotate-client-secret-copy.test.ts. Read with them: @better-auth/oauth-provider 1.7.3, rotateClientSecretEndpoint (dist/authorize-*.mjs) and validateClientCredentials (dist/utils-*.mjs). Also the card #24774 with the claim 6289452299 and the dispatch 6289515613, the dev's os-dev-report 6290624826 (read as claims), the PR body, and the 41 check-runs on the head.

① Derived judgments

• What rotation does: there is no grace period. Right, read in code.

  • rotateClientSecretEndpoint generates a new secret and writes it with one adapter.update on oauthClient, setting clientSecret to the stored new value. No previous secret is kept.
  • validateClientCredentials checks a presented secret against client.clientSecret alone (verifyStoredClientSecret).
  • So the old secret is refused from the moment the update commits. The confirmation ("will stop working immediately") was already true, and the result dialog's grace-period sentence was the false one.

• The fix: right.

  • resultDialog.description now says the previous secret has already stopped working. The confirmation, the dialog's title, its acknowledgement and its client_secret field are byte-identical.
  • The new code comment states the handler's behaviour, and the reading above makes it true.

• The translations: right.

  • en is regenerated (one line, byte-equal to the source, pinned).
  • zh-CN, ja-JP and es-ES carried a translated grace-period sentence, and the extractor keeps translated values in merge mode, so they were re-translated by hand, value only. Each new value says the old secret has already stopped working.
  • No other key in any bundle moves.

• The pins have teeth:

  • both source texts say the secret stops at once, and neither carries a grace term;
  • the dialog's other parts are kept;
  • en mirrors the source;
  • no locale promises a grace period in either text.

  The dev's two ablation legs (source, and zh-CN) go red as read.

② Semver level

• patch for @objectstack/platform-objects: right for a text-only change.
• Clause-②: no (text only: …) is at a line start in the changeset and the PR body. Check Changeset is green.
• Nothing widens.

③ Boundary flags

• Deviation 1 (three translated values edited by hand): accepted. The tool keeps translated values in merge mode, AGENTS.md permits a value edit, and leaving them would ship the false sentence in three locales.
• Deviation 2 (dependent suites narrowed to the consumers that read this action: runtime and cli): accepted. Nothing structural moved, and CI's Test Core is green.
• Deviation 3 (the pin asserts copy): accepted. The wording is the defect here.
• Deviation 4 (no booted measurement): accepted. The code leaves no doubt.
• Open question: A, copy follows the handler. B, a grace window in plugin-auth, would be a new auth capability with no pull. A is right on the four axes.
• The out-of-scope note (content/docs/protocol/objectui/actions.mdx shows an illustrative target that is not the shipped route): no producer reads it. No filing gate is met, and it is noted in the PR only.
• Siblings: this PR is the only one of Setup: the Create User and Set Password params are declared type text, so the admin's typed password shows in clear text #24758, Setup: a team record lists Sessions with "Sign out other devices", which signs out the admin's own sessions #24765 and Setup → OAuth applications: Rotate Client Secret's confirmation says the old secret stops working immediately, while its result dialog speaks of a grace period #24774 that touches the translation bundles, so nothing needs re-deriving. Its merge with PR fix(platform-objects): credential action params declare type password, so the dialog masks what is typed #24867 is clean.
• Check-runs on c41eb194965fe4833bcf55aded03474e5ed79bf3: ci-failure GREEN, all 41 completed, none failed.

Implemented-by: claude/issue-24774-rotate-secret-copy
Reviewed-by: session_01JtSQQ3EWsbNPzyYMug1tXy

VERDICT: PASS

---

Generated by Claude Code

[objectstack-fleet]

席位核对 · domain:engine seat 1 · session_01JtSQQ3EWsbNPzyYMug1tXy · 2026-10-20T12:45Z · ACCEPT

Head: c41eb19496. It carries the copy fix, the regenerated and re-translated bundles, the pin, the changeset and a merge of main.

Card #24774 (p2, bug, area:identity; from objectstack-ai/hotcrm#2188's Setup pass, F-23's objectstack half): claim 6289452299, dispatch 6289515613. Dev report: 6290624826.

Item	Reading
Shape	Draft PR → main. The body opens Fixes #24774. 7 files, +101/−5. Not governed: check-governed-merges matched 0 of 7 paths.
Scope	Rotate Client Secret's result dialog no longer promises a grace period. It now says the previous secret has already stopped working, as the confirmation already said. The four locales agree. The confirmation, the dialog's title, its acknowledgement and its secret field are unchanged.
Seat's own read	Read in @better-auth/oauth-provider 1.7.3, the pinned version: rotateClientSecretEndpoint overwrites oauthClient.clientSecret in one update and keeps no previous secret, and validateClientCredentials checks only that column. So the cut-off is immediate. git merge-tree is clean against main and against sibling PR #24867.
Review	TIER_DEFAULT, in-seat. Record 6291126289 is PASS on this head.
Declaration	One changeset, @objectstack/platform-objects patch, Clause-②: no (text only: …) at a line start, as on the claim and the PR body. No behaviour, accept set or served shape moves.
Cross-lane	None: packages/platform-objects is this lane's. plugin-auth was read only. No objection on the card or the seat posts.
Gates	Dev at c41eb1949: 66 derived, 66 run, all exit 0. platform-objects 1203 passed, core test:repo 82 passed, and the runtime and cli consumer tests 63 and 34 passed. Ablation: source and zh-CN legs, each red, restored to HEAD.
CI	At this read on c41eb19496: ci-failure GREEN, all 41 check-runs completed, none failed.

Disposition:

• open_questions: A, copy follows the handler (record ③). A grace window would be a new auth capability with no pull.
• deviations: all accepted (record ③). The three translated values were edited by hand because the extractor keeps translated values in merge mode. The dependent suites were narrowed to the action's consumers. The pin asserts copy, and here the copy is the defect.
• out_of_scope_findings: the illustrative target in content/docs/protocol/objectui/actions.mdx meets no filing gate; it is noted in the PR.
• Siblings: this is the only one of the three sibling PRs that touches the translation bundles, so nothing needs re-deriving.

Landing: ordinary queue (pr_ready + automerge_enable through the relay). Fixes #24774 then closes the card.

---

Generated by Claude Code