@boopkit/cap-oauth-server 0.1.4 → 0.3.0

package/capability.json

@@ -13,6 +13,7 @@
     "src/services/oauth-server.service.ts",
     "src/middleware/oauth-server.ts",
     "src/scripts/seed-oauth-clients.ts",
+    "src/scripts/prune-oauth-clients.ts",
     "views/oauth-consent.hbs",
     "views/oauth-consent-error.hbs",
     "views/oauth-connected-clients.hbs",
@@ -32,7 +33,7 @@
       "phase": "preRoutes",
       "order": 13,
       "code": "app.use(oauthDiscoveryRoutes);",
-      "description": "serve /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource \u2014 mounted outside /api, and first among this app's capability mounts (the free slot between cap-web's requestLogger at 12 and cap-users' cookieParser at 14), because a client reads these before it holds any credential and must never meet a 401 here. The order sequences capability mounts against each other; an application whose own middleware sits above the @boopkit:preRoutes marker still runs that middleware first, so check that these two answer 200 to a caller holding nothing \u2014 which is what the verify step below does"
+      "description": "serve /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource (also at the RFC 9728 path-suffixed location, e.g. /.well-known/oauth-protected-resource/api/mcp, when OAUTH_RESOURCE_URL has a path) \u2014 mounted outside /api, and first among this app's capability mounts (the free slot between cap-web's requestLogger at 12 and cap-users' cookieParser at 14), because a client reads these before it holds any credential and must never meet a 401 here. The order sequences capability mounts against each other; an application whose own middleware sits above the @boopkit:preRoutes marker still runs that middleware first, so check that these two answer 200 to a caller holding nothing \u2014 which is what the verify step below does"
     },
     {
       "phase": "preRoutes",
@@ -45,6 +46,10 @@
     "oauth:seed-clients": {
       "cmd": "tsx src/scripts/seed-oauth-clients.ts",
       "description": "Register the static OAuth clients this deployment trusts. Idempotent."
+    },
+    "oauth:prune-clients": {
+      "cmd": "tsx src/scripts/prune-oauth-clients.ts",
+      "description": "Delete abandoned client registrations \u2014 unauthenticated rows over 30 days old that nobody has connected. Schedule it daily."
     }
   },
   "env": [
@@ -78,7 +83,7 @@
     },
     {
       "name": "OAUTH_MAX_REGISTERED_CLIENTS",
-      "description": "Ceiling on rows created by open dynamic registration (default: 1000). /oauth/register is unauthenticated by design, so this is the hard bound on what an abusive caller can write; the per-IP rate limit only makes reaching it slow.",
+      "description": "Ceiling on rows created by open dynamic registration (default: 1000). /oauth/register is unauthenticated by design, so this is the hard bound on what an abusive caller can write; the per-IP rate limit only makes reaching it slow. It is a bound, not a collector \u2014 schedule npm run oauth:prune-clients, or rows nobody ever connected hold their slots forever and the ceiling eventually refuses legitimate registrations.",
       "default": "1000",
       "required": "runtime"
     },
@@ -88,6 +93,12 @@
       "default": "10",
       "required": "runtime"
     },
+    {
+      "name": "OAUTH_METADATA_RESOLUTION_RATE_LIMIT",
+      "description": "First-sight Client ID Metadata Document resolutions allowed per hour, per source address (default: 10). GET /oauth/authorize registers a CIMD client the first time it sees one, which is an unauthenticated write and an outbound fetch, so it carries the same per-IP limit /oauth/register does. Only a client_id with no row yet is charged, so an ordinary visitor to a connector this server already knows never spends any of it.",
+      "default": "10",
+      "required": "runtime"
+    },
     {
       "name": "OAUTH_DEVICE_CODE_ENABLED",
       "description": "Set to the string \"true\" to enable the RFC 8628 device-code grant. Off by default. When off the endpoints are not mounted at all and the grant type is absent from the discovery metadata, rather than advertised against an endpoint that answers 404 \u2014 a client that read the metadata would treat that 404 as a server fault rather than as an unsupported feature. Not yet implemented; declared here so the flag has one name.",
@@ -112,6 +123,7 @@
       "Add styles/oauth-server.css to your stylesheet entry point and rebuild Tailwind, or the consent screen and the connected-clients screen render unstyled.",
       "Protect the surface you are exposing to connectors: app.use('/api/mcp', resolveOAuthBearer, requireOAuth('profile'), yourRoutes). Both are exported from src/middleware/oauth-server.ts, which also mounts GET /api/oauth/whoami as a worked example you can curl with a fresh access token. Do not mount resolveOAuthBearer on a router that already carries cap-users' resolveBearer \u2014 pick the door that router's callers use.",
       "Edit src/scripts/seed-oauth-clients.ts with the clients you want to trust by name, then run npm run oauth:seed-clients. Clients that register themselves \u2014 anything supporting RFC 7591 or publishing a Client ID Metadata Document \u2014 need no entry there.",
+      "Schedule npm run oauth:prune-clients to run daily \u2014 Heroku Scheduler, cron, or a cap-background-jobs consumer. It deletes unauthenticated registrations over 30 days old that nobody has connected. Unscheduled, OAUTH_MAX_REGISTERED_CLIENTS is the only bound on registry growth, and a deployment that reaches the ceiling starts refusing legitimate registrations.",
       "Decide whether open registration suits you. POST /oauth/register is unauthenticated by design, which is what the Claude ecosystem expects; if you would rather only vouch for clients yourself, remove the preRoutes hook that mounts oauthServerRoutes and keep the seed script.",
       "Link to /connections from wherever your account settings live. The screen lists what a user has connected, states that a connected application reaches every account they belong to, and sends a disconnect through its own confirmation page. It is mounted already and gated by requireAuth; what it needs from you is a way in."
     ],

package/dist/authorization-code-service.d.ts

@@ -1,5 +1,5 @@
 import { type TokenService } from './token-service.js';
-import type { PropertyStore } from './user-store.js';
+import { type PropertyStore } from './user-store.js';
 /**
  * The authorization code: one identity row, one property entry.
  *
@@ -14,14 +14,34 @@ import type { PropertyStore } from './user-store.js';
  * is a SHA-256 digest, which is what the identity row already stores; the raw
  * code exists only in the redirect the browser followed, and nowhere at rest.
  *
- * ## The entry survives redemption, and that is the point
+ * ## The entry survives redemption, and the identity row stays live
  *
- * Redeeming stamps `redeemed_at` on the entry and end-dates the identity row —
- * it does not delete the entry. A deleted entry leaves nothing behind, so a
- * replay is an unexplained failed request; a retained one records that the code
- * was redeemed and when, which is what makes the replay an observable event
- * rather than merely an unsuccessful one. The entry is dropped only once it has
- * expired, on the next write that passes over it.
+ * Redeeming stamps `redeemed_at` on the entry. It does not delete the entry,
+ * and — since boop-hnbv — it does not end-date the identity row either. Both
+ * halves of that are one decision, and the second half is the surprising one.
+ *
+ * `redeemed_at` is the single-use gate. The row is what carries the **user id**,
+ * and cap-users' `(domain, key)` lookup is active-only, so end-dating the row at
+ * redemption threw the owner away: a replay arriving a second later resolved to
+ * nothing and could only be answered `unknown_code`. The retained entry was
+ * never read, because there was no user to read it under — which made the
+ * replay-detection apparatus this data model was shaped around dead code.
+ *
+ * Leaving the row live until its own 120-second expiry keeps the owner
+ * reachable, so a replay resolves, finds the stamped entry, and is answered
+ * `already_redeemed` **with the user id and the client it was issued to** — which
+ * is what the token endpoint needs to do what RFC 6749 §4.1.2 and §10.5 require:
+ * revoke the tokens the first redemption minted. Single-use is unchanged; it is
+ * enforced by `redeemed_at` now rather than by the tombstone.
+ *
+ * The live row grants nothing on its own. Every path to it goes through this
+ * service, and this service refuses a stamped entry. It is the same shape the
+ * refresh-token rotation uses one domain over, and for the same reason: a
+ * credential whose row is gone is indistinguishable from one that never existed,
+ * and telling those apart is the entire point.
+ *
+ * The entry is dropped once it has expired, on the next write that passes over
+ * it, and `resolve` end-dates the row the next time it reads it past expiry.
  *
  * ## Expiry here is `expires_at`, not the identity-row rule
  *
@@ -45,7 +65,7 @@ export interface AuthorizationCodeRecord {
     resource: string | null;
     issued_at: string;
     expires_at: string;
-    /** Set on redemption; the entry stays so a replay is visible. */
+    /** Set on redemption. The single-use gate, and the record of the replay. */
     redeemed_at: string | null;
 }
 /** What redemption needs to know, beyond the code itself. */
@@ -64,7 +84,15 @@ export type RedeemResult = {
 } | {
     ok: false;
     reason: RedeemFailure;
+    /** Present whenever the code resolved to somebody — see `redeem`. */
     userId?: number;
+    /**
+     * The client the code was ISSUED to, which is not always the one that
+     * presented it. A replay answered on a `client_id` of the attacker's
+     * choosing must still revoke the grant the code actually belongs to,
+     * and never a bystander's.
+     */
+    clientPublicId?: string;
 };
 export interface IssueCodeInput {
     userId: number;
@@ -83,8 +111,9 @@ export interface AuthorizationCodeService {
         record: AuthorizationCodeRecord;
     }>;
     /**
-     * Redeem once. End-dates the identity row and stamps `redeemed_at`; a second
-     * call answers `already_redeemed` rather than `unknown_code`.
+     * Redeem once. Stamps `redeemed_at` and leaves the identity row live, so a
+     * second call answers `already_redeemed` — carrying the owner and the client,
+     * so the caller can revoke what the first redemption issued.
      */
     redeem(input: RedeemCodeInput): Promise<RedeemResult>;
     /** The entries a user currently holds. Used by the credentials-at-rest test. */

package/dist/authorization-code-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authorization-code-service.d.ts","sourceRoot":"","sources":["../src/authorization-code-service.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAClD,eAAO,MAAM,uBAAuB,+BAA+B,CAAC;AAEpE,MAAM,WAAW,uBAAuB;IACtC,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GACrB,cAAc,GACd,kBAAkB,GAClB,SAAS,GACT,iBAAiB,GACjB,uBAAuB,CAAC;AAE5B,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAC7D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,uBAAuB,CAAA;KAAE,CAAC,CAAC;IACzF;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACtD,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,+BAA+B;IAC9C,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,aAAa,CAAC;IAC7B;;;;OAIG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACjE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,wBAAwB,CA2I1B"}
+{"version":3,"file":"authorization-code-service.d.ts","sourceRoot":"","sources":["../src/authorization-code-service.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAClD,eAAO,MAAM,uBAAuB,+BAA+B,CAAC;AAEpE,MAAM,WAAW,uBAAuB;IACtC,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GACrB,cAAc,GACd,kBAAkB,GAClB,SAAS,GACT,iBAAiB,GACjB,uBAAuB,CAAC;AAE5B,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAC7D;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,aAAa,CAAC;IACtB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEN,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,uBAAuB,CAAA;KAAE,CAAC,CAAC;IACzF;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACtD,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,+BAA+B;IAC9C,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,aAAa,CAAC;IAC7B;;;;OAIG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACjE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,wBAAwB,CAuK1B"}

package/dist/authorization-code-service.js

@@ -4,6 +4,7 @@ exports.OAUTH_CODES_INFO_SCHEMA = exports.OAUTH_CODES_PROPERTY = void 0;
 exports.createAuthorizationCodeService = createAuthorizationCodeService;
 const property_array_js_1 = require("./property-array.js");
 const token_service_js_1 = require("./token-service.js");
+const user_store_js_1 = require("./user-store.js");
 /**
  * The authorization code: one identity row, one property entry.
  *
@@ -18,14 +19,34 @@ const token_service_js_1 = require("./token-service.js");
  * is a SHA-256 digest, which is what the identity row already stores; the raw
  * code exists only in the redirect the browser followed, and nowhere at rest.
  *
- * ## The entry survives redemption, and that is the point
+ * ## The entry survives redemption, and the identity row stays live
  *
- * Redeeming stamps `redeemed_at` on the entry and end-dates the identity row —
- * it does not delete the entry. A deleted entry leaves nothing behind, so a
- * replay is an unexplained failed request; a retained one records that the code
- * was redeemed and when, which is what makes the replay an observable event
- * rather than merely an unsuccessful one. The entry is dropped only once it has
- * expired, on the next write that passes over it.
+ * Redeeming stamps `redeemed_at` on the entry. It does not delete the entry,
+ * and — since boop-hnbv — it does not end-date the identity row either. Both
+ * halves of that are one decision, and the second half is the surprising one.
+ *
+ * `redeemed_at` is the single-use gate. The row is what carries the **user id**,
+ * and cap-users' `(domain, key)` lookup is active-only, so end-dating the row at
+ * redemption threw the owner away: a replay arriving a second later resolved to
+ * nothing and could only be answered `unknown_code`. The retained entry was
+ * never read, because there was no user to read it under — which made the
+ * replay-detection apparatus this data model was shaped around dead code.
+ *
+ * Leaving the row live until its own 120-second expiry keeps the owner
+ * reachable, so a replay resolves, finds the stamped entry, and is answered
+ * `already_redeemed` **with the user id and the client it was issued to** — which
+ * is what the token endpoint needs to do what RFC 6749 §4.1.2 and §10.5 require:
+ * revoke the tokens the first redemption minted. Single-use is unchanged; it is
+ * enforced by `redeemed_at` now rather than by the tombstone.
+ *
+ * The live row grants nothing on its own. Every path to it goes through this
+ * service, and this service refuses a stamped entry. It is the same shape the
+ * refresh-token rotation uses one domain over, and for the same reason: a
+ * credential whose row is gone is indistinguishable from one that never existed,
+ * and telling those apart is the entire point.
+ *
+ * The entry is dropped once it has expired, on the next write that passes over
+ * it, and `resolve` end-dates the row the next time it reads it past expiry.
  *
  * ## Expiry here is `expires_at`, not the identity-row rule
  *
@@ -71,26 +92,23 @@ function createAuthorizationCodeService(options) {
             if (!identityKey)
                 return { ok: false, reason: 'unknown_code' };
             // Resolving through the token service applies the identity row's
-            // active-only lookup, so a code redeemed a moment ago (row end-dated)
-            // misses here — and the property entry below is what turns that miss into
-            // `already_redeemed` rather than `unknown_code`.
+            // active-only lookup. Redemption no longer end-dates the row, so a code
+            // redeemed a moment ago still resolves and reaches the `redeemed_at`
+            // check below — which is the whole point of the change (see the header).
             const resolved = await tokenService.resolve(token_service_js_1.OAUTH_CODE_DOMAIN, input.code);
             const at = now();
             if (!resolved) {
-                // The row is gone: never issued, already redeemed and end-dated, or
-                // expired and swept. All three are `unknown_code` here, and that is the
-                // honest answer rather than a shortcut. The row is what carries the
-                // user id, so once it is end-dated there is nothing left to look the
-                // owner up by — cap-users' lookup is active-only and the identity
-                // boundary forbids reaching past it. RFC 6749 gives all three the same
-                // wire answer (`invalid_grant`) for the same reason: telling a caller
-                // which one it hit tells it whether the code was ever real.
+                // The row is gone: never issued, malformed, or past its 120 seconds and
+                // swept. All of them are `unknown_code`, and RFC 6749 gives all of them
+                // the same wire answer (`invalid_grant`) for the same reason — telling a
+                // caller which one it hit tells it whether the code was ever real.
                 //
-                // What the retained entry buys is the record. A deleted entry leaves
-                // nothing behind; the entry kept with `redeemed_at` set means an
-                // operator reading `oauth-codes` can see that this code WAS redeemed,
-                // and when — which is what turns a replay from an unexplained failed
-                // request into an observable event.
+                // A replay is NOT in that list any more. Once the code's own window has
+                // closed there is no user id left to look the owner up by, so there is
+                // nothing this branch could revoke even if it wanted to; but by then the
+                // tokens the first redemption minted are the attacker's problem, not an
+                // undetected replay — a code two minutes stale is an expiry, and every
+                // replay worth catching arrives inside the window.
                 return { ok: false, reason: 'unknown_code' };
             }
             const snapshot = await (0, property_array_js_1.readArray)(propertyStore, resolved.userId, exports.OAUTH_CODES_PROPERTY);
@@ -100,12 +118,22 @@ function createAuthorizationCodeService(options) {
             // scope set, so there is nothing to check the request against.
             if (!record)
                 return { ok: false, reason: 'unknown_code', userId: resolved.userId };
-            // Reachable while the row is still live: a second redemption that arrives
-            // between the property write and the end-date below, which is exactly the
-            // concurrent-replay case. Across time the row is already ended and the
-            // branch above answers instead.
+            // The replay branch, and the reason the row is left live. It answers every
+            // second presentation inside the code's window, whether it arrives a
+            // millisecond or a minute after the first.
+            //
+            // It is checked BEFORE the client and redirect-URI comparisons on purpose:
+            // a code that has already been spent is spent whatever the replay claims
+            // about itself, and an attacker must not be able to dodge the revocation
+            // by presenting a stolen code under some other client's name. The client
+            // reported back is the one the code was ISSUED to, for the same reason.
             if (record.redeemed_at !== null) {
-                return { ok: false, reason: 'already_redeemed', userId: resolved.userId };
+                return {
+                    ok: false,
+                    reason: 'already_redeemed',
+                    userId: resolved.userId,
+                    clientPublicId: record.client_public_id,
+                };
             }
             if (Date.parse(record.expires_at) <= at.getTime()) {
                 return { ok: false, reason: 'expired', userId: resolved.userId };
@@ -116,21 +144,45 @@ function createAuthorizationCodeService(options) {
             if (!matchRedirectUri(record.redirect_uri, input.redirectUri)) {
                 return { ok: false, reason: 'redirect_uri_mismatch', userId: resolved.userId };
             }
-            // Order matters, and this is the order.
+            // The single-use claim, and the only one there is: `redeemed_at` on the
+            // entry, written under `expectedRevision` so a second redemption that read
+            // the same snapshot is refused rather than silently applied.
             //
-            // The property write goes first because it is the ATOMIC claim: it quotes
-            // `expectedRevision`, so two simultaneous redemptions of one code cannot
-            // both succeed — the loser is refused by the revision check rather than
-            // silently applied. End-dating the row first would leave that race open,
-            // because `endDate` has no compare-and-set of its own.
+            // With one honest caveat, since a comment here used to call this atomic
+            // without qualification. cap-services' `put` compares the revision and
+            // then updates in a separate statement, so two writers that interleave
+            // between the two can both land (boop-8fcd). That is a defect one layer
+            // down and it is not specific to codes — every property write in every
+            // capability shares it. What this code can promise is the sequential case,
+            // which is the replay an attacker can actually aim: present the code
+            // again, any time inside its window, and it is refused and the grant is
+            // revoked.
             const redeemed = { ...record, redeemed_at: at.toISOString() };
-            await (0, property_array_js_1.writeArray)(propertyStore, resolved.userId, exports.OAUTH_CODES_PROPERTY, 
-            // The redeemed entry is kept until its own window closes; `live` drops
-            // only entries that have actually expired.
-            [...live(snapshot.entries, at).filter((e) => e.code_key !== identityKey), redeemed], snapshot, { infoSchema: exports.OAUTH_CODES_INFO_SCHEMA });
-            // And then the tombstone, so the code is spent across time as well as
-            // within the request.
-            await tokenService.revokeByKey(token_service_js_1.OAUTH_CODE_DOMAIN, identityKey);
+            try {
+                await (0, property_array_js_1.writeArray)(propertyStore, resolved.userId, exports.OAUTH_CODES_PROPERTY, 
+                // The redeemed entry is kept until its own window closes; `live` drops
+                // only entries that have actually expired.
+                [...live(snapshot.entries, at).filter((e) => e.code_key !== identityKey), redeemed], snapshot, { infoSchema: exports.OAUTH_CODES_INFO_SCHEMA });
+            }
+            catch (err) {
+                if (!(0, user_store_js_1.isStaleWriteError)(err))
+                    throw err;
+                // The dead heat: two redemptions of one code both read the entry before
+                // either wrote it, and this one lost the revision check. That is a
+                // replay like any other — the only difference is that it was detected by
+                // the write rather than by the read — so it is answered the same way,
+                // with the owner and the client, rather than thrown for the caller to
+                // translate into a bare `invalid_grant` it can do nothing about.
+                return {
+                    ok: false,
+                    reason: 'already_redeemed',
+                    userId: resolved.userId,
+                    clientPublicId: record.client_public_id,
+                };
+            }
+            // No tombstone on the row. `redeemed_at` above is the single-use gate now,
+            // and the row stays live so the owner is still reachable when the replay
+            // comes — see the header.
             return { ok: true, userId: resolved.userId, record: redeemed };
         },
         async list(userId) {

package/dist/authorization-code-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"authorization-code-service.js","sourceRoot":"","sources":["../src/authorization-code-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"authorization-code-service.js","sourceRoot":"","sources":["../src/authorization-code-service.ts"],"names":[],"mappings":"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"}

package/dist/bearer.d.ts

@@ -1,5 +1,5 @@
 import type { RequestHandler } from 'express';
-import type { AuthMiddlewareDeps, BaseUserInfo, User } from '@boopkit/cap-users';
+import type { BaseUserInfo, User } from '@boopkit/cap-users';
 import './express.js';
 import type { GrantService, OAuthGrantRecord } from './grant-service.js';
 import { type TokenService } from './token-service.js';
@@ -49,10 +49,33 @@ export interface ResolvedOAuthPrincipal {
     grant: OAuthGrantRecord;
     clientPublicId: string;
 }
+/**
+ * Everything the resource server needs, and nothing else.
+ *
+ * The user read is a single injected function. It used to be that **and** a
+ * separate `AuthMiddlewareDeps` argument — cap-users' `{ authService,
+ * identityService, userService }` trio — which was handed to
+ * `createBearerMiddleware` and never read by it (boop-9ral). An application
+ * therefore supplied its user layer twice: once as `findUserById`, which the
+ * lookup below actually calls, and once as a `userService` inside a parameter
+ * nobody touched.
+ *
+ * Dropping it is the same narrowing `user-store.ts` applies to the identity and
+ * property services: what this capability can ask for stays smaller than what
+ * cap-users offers, so an application resolving users through a cache, a test
+ * harness or a service of its own owes this package one function rather than a
+ * fully constructed installation.
+ */
 export interface OAuthBearerOptions {
     tokenService: TokenService;
     grantService: GrantService;
-    /** cap-users' `userService.findById`, injected rather than reached for. */
+    /**
+     * How this application turns a user id into the principal `req.user` carries.
+     *
+     * cap-users' `userService.findById` is the usual answer and the one the
+     * scaffold passes — but it is injected rather than reached for, so it need not
+     * be cap-users' at all.
+     */
     findUserById(userId: number): Promise<User<BaseUserInfo> | null>;
     /**
      * The `WWW-Authenticate` value on a 401.
@@ -83,7 +106,7 @@ export declare function createOAuthTokenResolver(options: OAuthBearerOptions): (
  * the binding is made per request. That is a closure allocation, not work; the
  * three reads inside it are the cost of the request either way.
  */
-export declare function createOAuthBearerMiddleware(deps: AuthMiddlewareDeps, options: OAuthBearerOptions): RequestHandler;
+export declare function createOAuthBearerMiddleware(options: OAuthBearerOptions): RequestHandler;
 /** The challenge sent when the request carried no usable OAuth token at all. */
 export declare const DEFAULT_BEARER_CHALLENGE = "Bearer";
 /**
@@ -142,5 +165,5 @@ export interface OAuthResourceServer {
     /** Then gate them: `requireOAuth('profile')`. */
     requireOAuth(...scopes: string[]): RequestHandler;
 }
-export declare function createOAuthResourceServer(deps: AuthMiddlewareDeps, options: OAuthBearerOptions): OAuthResourceServer;
+export declare function createOAuthResourceServer(options: OAuthBearerOptions): OAuthResourceServer;
 //# sourceMappingURL=bearer.d.ts.map

package/dist/bearer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bearer.d.ts","sourceRoot":"","sources":["../src/bearer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAE/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAEjF,OAAO,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACzB,KAAK,EAAE,gBAAgB,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,YAAY,CAAC;IAC3B,2EAA2E;IAC3E,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC;IACjE;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,kBAAkB,GAC1B,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAe3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,kBAAkB,GAC1B,cAAc,CAwBhB;AAED,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAEjD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAG/F;AAcD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,GAAG,cAAc,EAAE,MAAM,EAAE,GAAG,cAAc,CAgCxE;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,aAAa,EAAE,cAAc,CAAC;IAC9B,iDAAiD;IACjD,YAAY,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC;CACnD;AAED,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,kBAAkB,GAC1B,mBAAmB,CAMrB"}
+{"version":3,"file":"bearer.d.ts","sourceRoot":"","sources":["../src/bearer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACzB,KAAK,EAAE,gBAAgB,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,YAAY,CAAC;IAC3B;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC;IACjE;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,kBAAkB,GAC1B,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAe3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAwBvF;AAED,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAEjD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAG/F;AAcD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,GAAG,cAAc,EAAE,MAAM,EAAE,GAAG,cAAc,CAgCxE;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,aAAa,EAAE,cAAc,CAAC;IAC9B,iDAAiD;IACjD,YAAY,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC;CACnD;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,kBAAkB,GAAG,mBAAmB,CAM1F"}

package/dist/bearer.js

@@ -42,7 +42,7 @@ function createOAuthTokenResolver(options) {
  * the binding is made per request. That is a closure allocation, not work; the
  * three reads inside it are the cost of the request either way.
  */
-function createOAuthBearerMiddleware(deps, options) {
+function createOAuthBearerMiddleware(options) {
     const resolveOAuthToken = createOAuthTokenResolver(options);
     const challenge = options.challenge ?? 'Bearer';
     return function oauthBearer(req, res, next) {
@@ -51,7 +51,7 @@ function createOAuthBearerMiddleware(deps, options) {
         // caller who presented nothing at all — the path on which the resolver
         // itself never refuses anybody.
         req.oauthChallenge = challenge;
-        const middleware = (0, cap_users_1.createBearerMiddleware)(deps, {
+        const middleware = (0, cap_users_1.createBearerMiddleware)({
             strategy: 'oauth',
             challenge,
             resolve: async (token) => {
@@ -140,10 +140,10 @@ function requireOAuth(...requiredScopes) {
         next();
     };
 }
-function createOAuthResourceServer(deps, options) {
+function createOAuthResourceServer(options) {
     const challenge = options.challenge ?? exports.DEFAULT_BEARER_CHALLENGE;
     return {
-        resolveBearer: createOAuthBearerMiddleware(deps, { ...options, challenge }),
+        resolveBearer: createOAuthBearerMiddleware({ ...options, challenge }),
         requireOAuth,
     };
 }

package/dist/bearer.js.map

@@ -1 +1 @@
-{"version":3,"file":"bearer.js","sourceRoot":"","sources":["../src/bearer.ts"],"names":[],"mappings":";;;AAgFA,4DAiBC;AAYD,kEA2BC;AAaD,sCAGC;AAsCD,oCAgCC;AAyBD,8DASC;AA/PD,kDAA4D;AAG5D,wBAAsB;AAEtB,yDAA4E;AAkE5E;;;;;;;GAOG;AACH,SAAgB,wBAAwB,CACtC,OAA2B;IAE3B,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IAE7D,OAAO,KAAK,UAAU,iBAAiB,CAAC,KAAK;QAC3C,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,sCAAmB,EAAE,KAAK,CAAC,CAAC;QACxE,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAE3B,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;QACtF,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAExB,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QAEvB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,CAAC,cAAc,EAAE,CAAC;IAClE,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,2BAA2B,CACzC,IAAwB,EACxB,OAA2B;IAE3B,MAAM,iBAAiB,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,QAAQ,CAAC;IAEhD,OAAO,SAAS,WAAW,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;QACzE,wEAAwE;QACxE,wEAAwE;QACxE,uEAAuE;QACvE,gCAAgC;QAChC,GAAG,CAAC,cAAc,GAAG,SAAS,CAAC;QAE/B,MAAM,UAAU,GAAG,IAAA,kCAAsB,EAAC,IAAI,EAAE;YAC9C,QAAQ,EAAE,OAAO;YACjB,SAAS;YACT,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;gBACvB,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,KAAK,CAAC,CAAC;gBAChD,IAAI,CAAC,QAAQ;oBAAE,OAAO,IAAI,CAAC;gBAC3B,GAAG,CAAC,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC;gBAChC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;YACjC,CAAC;SACF,CAAC,CAAC;QAEH,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC;AACJ,CAAC;AAED,gFAAgF;AACnE,QAAA,wBAAwB,GAAG,QAAQ,CAAC;AAEjD;;;;;;;GAOG;AACH,SAAgB,aAAa,CAAC,OAA0B,EAAE,QAA2B;IACnF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,YAAY,CAAC,GAAG,cAAwB;IACtD,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;IAE9C,OAAO,SAAS,SAAS,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;QACvE,MAAM,SAAS,GAAG,GAAG,CAAC,cAAc,IAAI,gCAAwB,CAAC;QACjE,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC;QAE7B,IAAI,GAAG,CAAC,YAAY,KAAK,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;YAC3C,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACtD,KAAK,EAAE,eAAe;gBACtB,iBAAiB,EAAE,wCAAwC;aAC5D,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACtD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACjC,MAAM,WAAW,GAAG,yCAAyC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACjF,GAAG;iBACA,GAAG,CACF,kBAAkB,EAClB,GAAG,SAAS,gCAAgC;gBAC1C,sBAAsB,UAAU,CAAC,WAAW,CAAC,aAAa,UAAU,CAAC,KAAK,CAAC,GAAG,CACjF;iBACA,MAAM,CAAC,GAAG,CAAC;iBACX,IAAI,CAAC,EAAE,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;YAChF,OAAO;QACT,CAAC;QAED,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC;AAyBD,SAAgB,yBAAyB,CACvC,IAAwB,EACxB,OAA2B;IAE3B,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,gCAAwB,CAAC;IAChE,OAAO;QACL,aAAa,EAAE,2BAA2B,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,CAAC;QAC3E,YAAY;KACb,CAAC;AACJ,CAAC"}
+{"version":3,"file":"bearer.js","sourceRoot":"","sources":["../src/bearer.ts"],"names":[],"mappings":"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"}

package/dist/client-prune.d.ts

@@ -0,0 +1,102 @@
+import type { ClientRegistryService } from './client-registry-service.js';
+import { type GrantService } from './grant-service.js';
+import type { TokenService } from './token-service.js';
+import type { OauthClient } from './types.js';
+/**
+ * Garbage collection for the client registry — the caller `pruneAbandonedClients`
+ * was always waiting for.
+ *
+ * ## The two halves the registry deliberately does not own
+ *
+ * `ClientRegistryService.pruneAbandonedClients({ before, isInUse })` knows how to
+ * pick candidates: stranger-created rows (`dynamic` and `metadata_document`)
+ * older than a cutoff. It knows nothing about grants, and it must not — the
+ * registry's whole discipline is that a client is software and a grant is a
+ * relationship between a person and that software, and the registry never learns
+ * who consented. So it takes the "is this in use?" question as a parameter and
+ * answers "no" by default, which is safe only in a deployment that has no grants
+ * at all.
+ *
+ * This file supplies the missing half, and a call site for it. Both live here
+ * rather than in the registry for the same reason the registry asked: answering
+ * the question means reading `oauth-grants`, which is a user-shaped read.
+ *
+ * ## What "in use" means, and why it is the grant rather than the token
+ *
+ * A client is in use when **somebody still has it connected** — that is, when
+ * some user's `oauth-grants` holds a live entry naming its `publicId`.
+ *
+ * The identity rows cannot carry that answer, in either direction, and
+ * `revocation-service.ts` makes the whole argument: an ended row does not mean
+ * disconnected, because ordinary expiry end-dates rows too, and a live row does
+ * not mean connected, because rotation leaves the superseded refresh row
+ * deliberately active. Reading tokens would delete a client half the deployment
+ * uses, or keep one nobody has used in a year. The grant record is the signal.
+ *
+ * Token rows are still how the *users* are found — `findUserIdsForClient` scans
+ * the `"<publicId>|"` key prefix the wire format was shaped to make cheap — and
+ * that is sound because a grant is only ever written at redemption, in the same
+ * request that mints the first token. A grant with no token row behind it is not
+ * a state this server can reach.
+ *
+ * ## What it deliberately does not protect
+ *
+ * An authorization code issued against a client whose row is about to be swept.
+ * Codes live for a minute and the cutoff is thirty days, so the window is a
+ * client that registered a month ago, never connected, and is mid-flow at the
+ * exact moment the sweep runs; it loses that one redemption and can register
+ * again. Closing it properly would mean scanning `oauth-codes`, which is a
+ * per-user property with no cross-user read — the cost is a full user scan to buy
+ * a minute of protection for a client that has never completed a grant.
+ *
+ * ## Deleting a row a grant still points at is fine, and intended
+ *
+ * An *ended* grant is not in use, so its client may be swept. The
+ * connected-clients screen already renders a grant whose registry row has gone —
+ * it falls back to the `client_id` the client presented and says the application
+ * is no longer registered here — because a connection the screen does not list is
+ * a connection nobody can disconnect.
+ */
+export interface ClientInUseOptions {
+    grantService: GrantService;
+    tokenService: TokenService;
+}
+/**
+ * The real `isInUse` predicate: is anybody still connected to this client?
+ *
+ * Suitable for passing straight to `pruneAbandonedClients`. It is `false` for a
+ * client nobody ever connected and for one every user has disconnected, and
+ * `true` the moment one live grant names the client's `publicId`.
+ */
+export declare function createClientInUsePredicate(options: ClientInUseOptions): (client: OauthClient) => Promise<boolean>;
+/** What one sweep did, in the shape a log line or a job result wants. */
+export interface ClientPruneResult {
+    /** The cutoff actually used. Rows created before this were candidates. */
+    before: Date;
+    /** The `client_id` of every row deleted, in the order they were deleted. */
+    removed: string[];
+}
+export interface ClientPruneOptions extends ClientInUseOptions {
+    clientRegistry: ClientRegistryService;
+    /**
+     * How old an unconnected row has to be before it is garbage. Defaults to the
+     * plan's thirty days (`DEFAULT_ABANDONED_CLIENT_TTL_MS`).
+     */
+    ttlMs?: number;
+    /** Injectable clock, so a test does not have to wait a month. */
+    now?: () => Date;
+}
+export interface ClientPruneJob {
+    /** Sweep once. Safe to run concurrently with the rest of the server. */
+    run(): Promise<ClientPruneResult>;
+}
+/**
+ * The scheduled sweep, as one callable object.
+ *
+ * A job rather than a loose function because the thing that was missing was a
+ * *call site*: a scaffolded application schedules `run()` — from its own cron,
+ * from Heroku Scheduler, or from a cap-background-jobs consumer — and the
+ * capability owns which rows go and which stay.
+ */
+export declare function createClientPruneJob(options: ClientPruneOptions): ClientPruneJob;
+//# sourceMappingURL=client-prune.d.ts.map

package/dist/client-prune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-prune.d.ts","sourceRoot":"","sources":["../src/client-prune.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAE1E,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,kBAAkB,GAC1B,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAmB3C;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,MAAM,EAAE,IAAI,CAAC;IACb,4EAA4E;IAC5E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,cAAc,EAAE,qBAAqB,CAAC;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,GAAG,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAahF"}