fix(platform-objects,plugin-auth): give API-key revoke/restore a working product route

[claude]

Fixes #7727

What was wrong

sys_api_key contradicted itself. It declared two row actions — revoke_api_key / restore_api_key — as method: 'PATCH' against /api/v1/data/sys_api_key/{id} with bodyExtra: { revoked: true|false }, while the same object set enable.apiMethods = ['get', 'list']. The declared PATCH was refused at the ADR-0049 method gate with 405 OBJECT_API_METHOD_NOT_ALLOWED before any authorization ran, so no product route revoked an API key: the Setup → API Keys → Revoke button produced an error toast, the row still read revoked = false, and the key kept authenticating.

Enforcement of the flag was never the problem. The verifier filters revoked: false and re-checks the row, so a flipped bit takes effect on the very next x-api-key call. The missing piece was purely the write path.

The premise, verified before implementing

The card ruled the in-object, column-scoped fix, hung on this premise: ADR-0092 D2's identity write guard admits a narrowly-scoped write without being weakened. Confirmed, at the ADR and at the implementation.

ADR-0092 D2 states it directly — "Per-object update whitelist is the only opening: plugin-auth exposes a small registry — registerManagedUpdateWhitelist(object, fields) — consulted by the beforeUpdate guard." identity-write-guard.ts implements exactly that: non-whitelisted keys are stripped, and a payload that strips to nothing throws. Registering one column on one object needs no guard change at all, and auth-plugin.ts already loops MANAGED_EXTENSION_EDITABLE_FIELDS into that registry. So the scoped exception is the mechanism's declared purpose, not a hole widened to fit.

revoked qualifies as an ObjectStack extension field under ADR-0105 D7 without ambiguity: this table is hand-rolled (packages/core/src/security/api-key.ts mints and verifies it) and better-auth's apiKey plugin is not loaded, so better-auth owns none of these columns.

The gate the card did not know about

The write path had two gates. Opening enable.apiMethods alone still served 405, because ADR-0103's reconcileManagedApiMethods strips any write verb a managedBy object's resolved affordances do not grant — and it only warns. An object can therefore declare update, serve 405, and look perfectly correct in its own source: the same declared-≠-enforced shape as the original defect, one layer deeper.

userActions: { edit: true } declares the affordance, exactly as sys_user does under ADR-0092 D4. D4's sequencing rule is satisfied — the guard it fronts already shipped.

Scope of the opening

Opening the METHOD does not open the COLUMNS. The object stays managedBy: 'better-auth', the guard still fail-closed rejects user-context writes, and its per-object whitelist stays the only opening — carrying revoked and nothing else:

• key stays unwritable — a rotated hash would mint a credential nobody holds.
• user_id stays unwritable — re-owning a key is privilege transfer.
• expires_at stays on the mint path.
• create / delete stay off — minting is POST /api/v1/keys, and keys are retired by revoking, not deleting.

The guard itself is unchanged. No general weakening; every other identity table keeps its default-deny. Enforcement was not touched either — the card measured it as already correct.

Per D4's form-rendering constraint, the five columns outside the whitelist (name, prefix, user_id, scopes, expires_at) are now readonly, so the edit form this affordance turns on cannot advertise a write the server refuses.

The pin

Nothing pinned this before — the existing tests exercise key resolution against a pre-revoked row and never call the route the actions declare, which is exactly how a declared action and a method gate cancelled out unnoticed. api-key-revoke-lifecycle.dogfood.test.ts drives the real product route and asserts the consequence, not just the status:

1. Revoke — PATCH {revoked:true} → 200, then the key stops authenticating (a 200 that leaves the key working is the defect wearing a success code). Baseline-asserted first, so the post-revoke 401 is falsifiable.
2. Restore — PATCH {revoked:false} → 200, and the key authenticates again.
3. Column scope — a {name} PATCH is refused 403 + PERMISSION_DENIED, the stored value is unchanged, and the key is untouched. If the opening let a general update through, that would be worse than the bug being closed.
4. Smuggling — {revoked, key, user_id} applies revoked only; user_id is unchanged and the ORIGINAL secret still authenticates after restore, which is what proves key was stripped rather than merely unread.
5. Create / delete still 405 + OBJECT_API_METHOD_NOT_ALLOWED.
6. The declarations — the row actions' verb/target/bodyExtra and the REGISTERED (post-reconciler) apiMethods and userActions.edit, read from the live schema. This is what stops the reconciler from silently stripping update again.

Refusal cases assert code and status per ADR-0112 — a status-only or bare-throw assertion cannot separate "refused with the wrong envelope" from "did not refuse at all".

Reverse verification

Direction predicted before running: reverting each half turns the new pins red, and in distinguishable ways. Both confirmed.

Reverted	Result	Reads
the object half	5 red — expected 405 to be 200, expected ['get','list'] to include 'update'	the original bug, exactly as filed
the whitelist half only	3 red — expected 403 to be 200	method gate passes, guard refuses
neither	6 passed	—

The 403 refusal case stays green in both reverted states, correctly: it is a refusal test, and the refusal merely arrives for a broader reason. That is why the positive cases carry the load.

Verification

Gate	Result
@objectstack/dogfood	582 passed, 3 skipped (91 files)
@objectstack/plugin-auth	997 passed (40 files)
@objectstack/platform-objects	311 passed (13 files)
@objectstack/objectql	3237 passed (183 files)
@objectstack/rest	1450 passed (90 files)
@objectstack/plugin-security	973 passed (973)
@objectstack/runtime	2029 passed (129 files)
typecheck (the 3 changed packages)	clean
check:type-check-debt	OK — 1786 raw errors, none above its recorded number; no ledger raised
check:query-options-erasure	OK — 67 unswept sites, none new; test surface at ceiling, unchanged
check:adr-anchors	OK — 48 anchored files (this PR adds one)
check:i18n	in sync, all 9 packages
check:nul-bytes	OK — 7127 files
eslint (changed files)	clean

Consumer-sweep direction: not applicable — no exported type or signature changed. The build closure was rebuilt first (--filter '@objectstack/dogfood^...' build) before any judgement, and the full workspace was built before the debt ratchet.

Also in this PR

• An ADR anchor for sys-api-key.object.ts (ADR-0092, ADR-0103), so the next reader is told which decisions userActions.edit and the readonly stamps are standing on rather than reading them as arbitrary.
• A one-line correction to a pre-existing comment that named the route as /api/v1/sys_api_key/{id}, omitting /data/ — the exact path this card is about.
• A changeset (patch on both packages).

---

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 11, 2026 2:13pm

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/platform-objects, @objectstack/plugin-auth.

9 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/platform-objects, @objectstack/plugin-auth)
• content/docs/ui/setup-app.mdx (via @objectstack/platform-objects)

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