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

`sys_api_key` declared two row actions — `revoke_api_key` / `restore_api_key`
— as `PATCH /api/v1/data/sys_api_key/{id}` with `bodyExtra: {revoked}`, while
the same object set `enable.apiMethods = ['get','list']`. The declared PATCH
died at the ADR-0049 method gate with 405 before any authorization ran, so no
product route revoked an API key: the Setup UI's Revoke button errored, the row
kept `revoked = false`, and the key kept authenticating.

The write path had two gates, not one:

- the method gate — `enable.apiMethods` now carries `update` (`create` /
  `delete` stay off: minting is `POST /api/v1/keys`, and keys are retired by
  revoking rather than deleting);
- ADR-0103's `reconcileManagedApiMethods`, which strips any write verb a
  `managedBy` object's affordances do not grant and only warns. `apiMethods`
  alone would still have served 405 while the source read correctly, so
  `userActions: { edit: true }` declares the affordance — the ADR-0092 D4
  pattern `sys_user` already uses.

Opening the method does not open the columns. The object stays
`managedBy: 'better-auth'`, so ADR-0092 D2's identity write guard still
fail-closed rejects user-context writes and its per-object update whitelist
stays the only opening; `revoked` is registered there and nothing else is. The
guard itself is untouched — no general weakening, and every other identity
table keeps its default-deny. Per D4's form-rendering constraint the columns
outside the whitelist are now `readonly`, so the edit form this affordance
turns on cannot offer a write the server refuses.

Nothing pinned any of this: the existing tests exercise key resolution against
a pre-revoked row and never call the route the actions declare. The new
dogfood suite drives the real PATCH, asserts 200, then asserts the consequence
— the key stops authenticating — and pins the refusals with code AND status.


Claude-Session: https://claude.ai/code/session_01SqARTSYRvgutYHaLXbx6f7

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/api-key-revoke-product-route.md

@@ -0,0 +1,54 @@
+---
+"@objectstack/platform-objects": patch
+"@objectstack/plugin-auth": patch
+---
+
+fix(platform-objects,plugin-auth): let the API-key revoke/restore actions actually run (#7727)
+
+`sys_api_key` contradicted itself. It declared two row actions —
+`revoke_api_key` / `restore_api_key` — as `PATCH /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. A leaked key could only be
+retired by writing the row out of band.
+
+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, and it
+had **two** gates, not one:
+
+- **The method gate.** `enable.apiMethods` now carries `update`. `create` and
+  `delete` stay off: minting is `POST /api/v1/keys` (the only path that ever
+  returns the raw secret) and keys are retired by revoking, not deleting.
+- **The affordance reconciler.** ADR-0103's `reconcileManagedApiMethods` strips
+  any write verb a `managedBy` object's resolved affordances do not grant —
+  warning, not failing. So `apiMethods` alone would still have served 405 while
+  the source read correctly. `userActions: { edit: true }` declares the
+  affordance, exactly as `sys_user` does under ADR-0092 D4.
+
+**Opening the method does not open the columns.** `sys_api_key` stays
+`managedBy: 'better-auth'`, so ADR-0092 D2's identity write guard still
+fail-closed rejects user-context writes, and its per-object update whitelist
+remains the only opening. `revoked` is registered there and nothing else is:
+`key` stays unwritable (a rotated hash would mint a credential nobody holds),
+`user_id` stays unwritable (re-owning a key is privilege transfer), and
+`expires_at` stays on the mint path. A PATCH carrying only non-whitelisted
+columns is refused `403 PERMISSION_DENIED` rather than degrading into a
+timestamp touch, and a mixed patch applies `revoked` while stripping the rest.
+The guard itself is unchanged — no general weakening, and every other identity
+table keeps its default-deny.
+
+Per ADR-0092 D4's form-rendering constraint, the columns outside the whitelist
+(`name`, `prefix`, `user_id`, `scopes`, `expires_at`) are now `readonly`, so the
+edit form this affordance turns on cannot offer a write the server refuses —
+the declared-≠-enforced shape that caused the original defect.
+
+Nothing pinned any of this before: the existing tests exercise key *resolution*
+against a pre-revoked row and never call the route the actions declare, which is
+how a declared action and a method gate cancelled out unnoticed. The new
+`api-key-revoke-lifecycle` dogfood suite drives the real PATCH, asserts `200`,
+and then asserts the consequence — the key stops authenticating — because a 200
+that leaves the key working is the defect wearing a success code.

packages/platform-objects/src/identity/sys-api-key.object.ts

@@ -20,6 +20,22 @@ export const SysApiKey = ObjectSchema.create({
   icon: 'key-round',
   isSystem: true,
   managedBy: 'better-auth',
+  // [ADR-0092 D4 / ADR-0103] Declares the generic EDIT affordance, which is
+  // what lets `enable.apiMethods` keep `update` below: `managedBy` objects run
+  // through `reconcileManagedApiMethods`, which strips any write verb the
+  // resolved affordances do not grant. Without this line the declaration and
+  // the runtime disagree again — silently, one layer deeper than #7727's
+  // method gate. `create` / `delete` stay bucket-default (off): minting is
+  // `POST /api/v1/keys` and rows are retired by revoking, not deleting.
+  //
+  // The affordance is safe to open only because the enforcement it fronts
+  // already exists (D4's sequencing rule — affordance never ships ahead of
+  // the guard): ADR-0092 D2's guard clamps every user-context update on this
+  // table to the registered column whitelist, which lists `revoked` alone.
+  // Per D4's form-rendering constraint, every column outside that whitelist
+  // is marked `readonly` below, so the edit form cannot offer a write the
+  // server will refuse.
+  userActions: { edit: true },
   // ADR-0010 §3.7 — managed by better-auth; tenants may not edit schema,
   // but may add overlay row-level config. Use `no-overlay` if you need to
   // forbid sys_metadata overlays entirely.
@@ -36,8 +52,9 @@ export const SysApiKey = ObjectSchema.create({
 
   // Custom actions — sys_api_key is managed-by 'better-auth' but the
   // `revoked` boolean is a column we control via the data API. These row
-  // actions use the generic PATCH /api/v1/sys_api_key/{id} endpoint with
-  // `bodyExtra` to set the `revoked` flag explicitly.
+  // actions use the generic PATCH /api/v1/data/sys_api_key/{id} endpoint with
+  // `bodyExtra` to set the `revoked` flag explicitly. The `target` below is
+  // the authority on that path; this comment used to omit `/data/`.
   actions: [
     {
       name: 'revoke_api_key',
@@ -117,9 +134,16 @@ export const SysApiKey = ObjectSchema.create({
 
   fields: {
     // ── Identity ─────────────────────────────────────────────────
+    // The five fields below are `readonly` for one reason (ADR-0092 D4's
+    // form-rendering constraint): they are set on the mint path and are NOT on
+    // the identity write guard's column whitelist, so a user-context write to
+    // any of them is refused 403. With `userActions.edit` open, leaving them
+    // writable in the form would advertise an edit the server rejects — the
+    // declared-≠-enforced shape this object already paid for once (#7727).
     name: Field.text({
       label: 'Name',
       required: true,
+      readonly: true,
       searchable: true,
       maxLength: 255,
       description: 'Human-readable label for the API key',
@@ -129,6 +153,7 @@ export const SysApiKey = ObjectSchema.create({
     prefix: Field.text({
       label: 'Prefix',
       required: false,
+      readonly: true,
       maxLength: 16,
       description: 'Visible prefix for identifying the key (e.g., "osk_")',
       group: 'Identity',
@@ -137,6 +162,7 @@ export const SysApiKey = ObjectSchema.create({
     user_id: Field.lookup('sys_user', {
       label: 'Owner',
       required: true,
+      readonly: true,
       description: 'User who owns this API key',
       group: 'Identity',
     }),
@@ -145,6 +171,7 @@ export const SysApiKey = ObjectSchema.create({
     scopes: Field.textarea({
       label: 'Scopes',
       required: false,
+      readonly: true,
       description: 'JSON array of permission scopes',
       group: 'Access',
     }),
@@ -153,6 +180,7 @@ export const SysApiKey = ObjectSchema.create({
     expires_at: Field.datetime({
       label: 'Expires At',
       required: false,
+      readonly: true,
       group: 'Lifecycle',
     }),
 
@@ -214,8 +242,23 @@ export const SysApiKey = ObjectSchema.create({
     trackHistory: true,
     searchable: false,
     apiEnabled: true,
-    // #1591 — reads only: writes are refused by the identity write guard
-    // (ADR-0092 D2) and owned by better-auth. HTTP answers 405 before the 403.
-    apiMethods: ['get', 'list'],
+    // #1591 / #7727 — reads, plus `update` for the revoke/restore lifecycle.
+    //
+    // `create` and `delete` stay off: minting is `POST /api/v1/keys` (the only
+    // path that can return the raw secret once) and rows are retired by
+    // revoking, not deleting, so history survives.
+    //
+    // `update` is here because the two row actions above declare a PATCH
+    // against the data API, and a method gate that answers 405 first makes
+    // those actions dead on arrival — a declared affordance the runtime never
+    // honours (#7727). Opening the METHOD does not open the COLUMNS: this
+    // object is `managedBy: 'better-auth'`, so ADR-0092 D2's identity write
+    // guard still fail-closed rejects user-context writes, and the only
+    // opening is its per-object update whitelist. `revoked` is registered
+    // there (plugin-auth `managed-extension-fields.ts`); every other column —
+    // `key`, `user_id`, `expires_at`, `name`, … — is stripped, and a PATCH
+    // that touches nothing else is refused 403 `PERMISSION_DENIED` rather
+    // than degrading into a silent no-op.
+    apiMethods: ['get', 'list', 'update'],
   },
 });

packages/plugins/plugin-auth/src/managed-extension-fields.ts

@@ -58,6 +58,15 @@ export const MANAGED_EXTENSION_FIELDS: Readonly<Record<string, ReadonlySet<strin
     'parent_organization_id',
     'sort_order',
   ]),
+  sys_api_key: new Set([
+    // #7727 — the revoke/restore lifecycle flag. `sys_api_key` is
+    // `managedBy: 'better-auth'` (which is what puts it under the D2 guard),
+    // but the table is hand-rolled ObjectStack: `packages/core/src/security/
+    // api-key.ts` mints and verifies it and better-auth's `apiKey` plugin is
+    // not loaded, so EVERY column here is an extension field. `revoked` is
+    // the only one a generic write surface may touch — see the editable map.
+    'revoked',
+  ]),
   sys_invitation: new Set([
     // ADR-0105 D8 — placement intent. NOT generically editable (absent from
     // the editable map below): these decide RBAC placement, so they are set
@@ -86,6 +95,17 @@ export const MANAGED_EXTENSION_EDITABLE_FIELDS: Readonly<Record<string, Readonly
     'parent_organization_id',
     'sort_order',
   ]),
+  // #7727 — revoking a leaked API key is a product operation, and before this
+  // entry no product route performed it: `sys_api_key`'s own row actions
+  // declare a PATCH, the object's method gate answered 405, and behind that
+  // the guard had no whitelist to consult, so the 403 was equally certain.
+  // Scoping the opening to this ONE column is the point — `key` stays
+  // unwritable (a rotated hash would silently mint a key nobody holds),
+  // `user_id` stays unwritable (re-owning a key is privilege transfer), and
+  // `expires_at` stays on the mint path. Enforcement of the flag already
+  // works: the verifier filters `revoked: false` and re-checks the row, so a
+  // flipped bit takes effect on the very next `x-api-key` call.
+  sys_api_key: new Set(['revoked']),
 };
 
 /** The extension fields declared on `object`, or an empty set. */