@boopkit/cap-oauth-server 0.1.0

package/capability.json

@@ -0,0 +1,120 @@
+{
+  "name": "oauth-server",
+  "description": "Be an OAuth 2.1 authorization server and resource server, so Claude, Claude Code or any MCP client can act on behalf of one of your users",
+  "type": "application",
+  "package": "@boopkit/cap-oauth-server",
+  "requires": [
+    "users-and-accounts",
+    "web",
+    "database"
+  ],
+  "files": [
+    "prisma/schema/oauth-clients.prisma",
+    "src/services/oauth-server.service.ts",
+    "src/middleware/oauth-server.ts",
+    "src/scripts/seed-oauth-clients.ts",
+    "views/oauth-consent.hbs",
+    "views/oauth-consent-error.hbs",
+    "views/oauth-connected-clients.hbs",
+    "views/oauth-disconnect-confirm.hbs",
+    "styles/oauth-server.css",
+    "reference/oauth-server.ref.md"
+  ],
+  "_plannedFilesNote": "Not read by boop. The scaffold surface still to land; each slice moves its entry into \"files\" as the asset arrives. Slice 2 landed the consent views and stylesheet and dropped the planned src/controllers/oauth-consent.ts: the consent controller lives in the package, where its hostile-input rules are tested, and the scaffold binds a router rather than restating handlers. Slice 3 landed the connected-clients and disconnect-confirmation views the same way, so the list is now empty; the device-flow surface joins it if Slice 5 needs a view of its own.",
+  "plannedFiles": [],
+  "hooks": [
+    {
+      "phase": "imports",
+      "code": "import { oauthDiscoveryRoutes, oauthServerRoutes } from './middleware/oauth-server';",
+      "description": "the two .well-known discovery documents, and the OAuth surface (client registration, the consent screen, POST /oauth/token, POST /oauth/revoke, and the connected-clients screen)"
+    },
+    {
+      "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"
+    },
+    {
+      "phase": "preRoutes",
+      "order": 54,
+      "code": "app.use(oauthServerRoutes);",
+      "description": "mount the OAuth surface \u2014 registration, the consent screen, POST /oauth/token, POST /oauth/revoke and the /connections management screen \u2014 after cap-users' addAuthContext (16), which the consent screen needs to decide whether it is showing a consent card, a login form or a signup form, and which /connections needs so requireAuth can gate it"
+    }
+  ],
+  "scripts": {
+    "oauth:seed-clients": {
+      "cmd": "tsx src/scripts/seed-oauth-clients.ts",
+      "description": "Register the static OAuth clients this deployment trusts. Idempotent."
+    }
+  },
+  "env": [
+    {
+      "name": "OAUTH_ISSUER_URL",
+      "description": "The origin every OAuth endpoint URL is built from, e.g. https://example.com. Must be https (localhost excepted for development). Boot fails without it, because a wrong issuer produces discovery documents that send clients somewhere else.",
+      "required": "boot"
+    },
+    {
+      "name": "OAUTH_RESOURCE_URL",
+      "description": "The protected resource's URL as clients enter it, e.g. https://example.com/api/mcp. This is not the issuer: it is the string a client reads back out of /.well-known/oauth-protected-resource and must match what it connected to. Defaults to OAUTH_ISSUER_URL, which is right only for an app whose protected surface is its root.",
+      "required": "runtime"
+    },
+    {
+      "name": "OAUTH_SCOPES_SUPPORTED",
+      "description": "Space- or comma-separated scopes this server will issue (default: profile email offline_access). Dropping offline_access means no client can request a refresh token, so every connection expires with its access token.",
+      "default": "profile email offline_access",
+      "required": "runtime"
+    },
+    {
+      "name": "OAUTH_ACCESS_TOKEN_TTL_SECONDS",
+      "description": "Access-token lifetime in seconds (default: 900, i.e. 15 minutes). Clamped to 60-3600 with a boot warning naming the value and the bound; an app should not fail to boot over a token lifetime. Revocation does not depend on this \u2014 every request re-reads the identity row, so a revoke takes effect on the client's very next call whatever the stated lifetime.",
+      "default": "900",
+      "required": "runtime"
+    },
+    {
+      "name": "OAUTH_REFRESH_TOKEN_TTL_SECONDS",
+      "description": "Refresh-token lifetime in seconds (default: 7776000, i.e. 90 days), sliding on each rotation so an actively used connector never expires while an abandoned one does. Clamped to 3600-31536000 with a boot warning.",
+      "default": "7776000",
+      "required": "runtime"
+    },
+    {
+      "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.",
+      "default": "1000",
+      "required": "runtime"
+    },
+    {
+      "name": "OAUTH_REGISTRATION_RATE_LIMIT",
+      "description": "Registration requests allowed per hour, per source address (default: 10). In-process and per-instance; put a shared limiter in front if you run more than one instance and need a global bound.",
+      "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.",
+      "default": "false",
+      "required": "runtime"
+    },
+    {
+      "name": "OAUTH_DOCUMENTATION_URL",
+      "description": "Optional human-facing documentation URL, echoed into both discovery documents as service_documentation / resource_documentation.",
+      "required": "runtime"
+    }
+  ],
+  "postInstall": {
+    "prerequisites": [
+      "users-and-accounts is installed and its database migration has been run",
+      "database is installed, so prisma/schema/ exists and db:migrate is available"
+    ],
+    "steps": [
+      "Set OAUTH_ISSUER_URL in .env to the origin clients will reach this app on. Set OAUTH_RESOURCE_URL too if the surface you are protecting is not the app root.",
+      "Run npm run db:migrate -- --name oauth-clients to create the oauth_clients table.",
+      "Describe every scope you advertise. Set app.locals.oauthScopeDescriptions = { profile: 'See your name and email', ... } in server.ts. Without it the consent screen shows raw scope strings, which asks a user to approve something they cannot evaluate; the app logs a boot warning naming each undescribed scope.",
+      "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.",
+      "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."
+    ],
+    "verify": "Start the app and fetch /.well-known/oauth-authorization-server with no credential. You should get 200, a JSON body whose issuer matches OAUTH_ISSUER_URL, code_challenge_methods_supported of exactly [\"S256\"], and client_id_metadata_document_supported true. Then open /oauth/authorize?response_type=code&client_id=<a seeded client>&redirect_uri=<its registered URI>&code_challenge=<an S256 challenge>&code_challenge_method=S256 in a browser: you should see the consent screen, with the client's name, a provenance line, and the scopes described in your own words rather than as raw strings. Finally, sign in and open /connections: a client you have approved appears under Connected applications with the scopes described in your own words, and Disconnect leads to a confirmation page rather than revoking on the spot."
+  }
+}

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

@@ -0,0 +1,105 @@
+import { type TokenService } from './token-service.js';
+import type { PropertyStore } from './user-store.js';
+/**
+ * The authorization code: one identity row, one property entry.
+ *
+ * ## The two-read model, at its smallest
+ *
+ * The identity row in the `oauth-code` domain answers *who this code belongs
+ * to*, and it is the only place the code's hash lives. The `oauth-codes`
+ * property entry answers *what was asked for* — client, redirect URI, PKCE
+ * challenge, scopes, resource — and carries the code's own `expires_at`.
+ *
+ * The entry's `code_key` is the identity key, so the two reads join. That value
+ * 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
+ *
+ * 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.
+ *
+ * ## Expiry here is `expires_at`, not the identity-row rule
+ *
+ * The plan's `createdAt + ttl` correction governs access and refresh tokens,
+ * whose lifetime has no home on the row. The code's lifetime does have a home:
+ * this explicit field, written at issue time. It stays the authority, and the
+ * TTL that produced it is a constant in the package rather than configuration.
+ */
+export declare const OAUTH_CODES_PROPERTY = "oauth-codes";
+export declare const OAUTH_CODES_INFO_SCHEMA = "boop.oauth-server.codes.v1";
+export interface AuthorizationCodeRecord {
+    /** `"<publicId>|<sha256>"` — the join to the identity row. Already a hash. */
+    code_key: string;
+    client_id: string;
+    client_public_id: string;
+    redirect_uri: string;
+    /** The PKCE challenge. Never the verifier — that never reaches the server. */
+    code_challenge: string;
+    code_challenge_method: string;
+    scopes: string[];
+    resource: string | null;
+    issued_at: string;
+    expires_at: string;
+    /** Set on redemption; the entry stays so a replay is visible. */
+    redeemed_at: string | null;
+}
+/** What redemption needs to know, beyond the code itself. */
+export interface RedeemCodeInput {
+    code: string;
+    clientId: string;
+    clientPublicId: string;
+    redirectUri: string;
+}
+/** Why a redemption was refused. The controller maps these to RFC codes. */
+export type RedeemFailure = 'unknown_code' | 'already_redeemed' | 'expired' | 'client_mismatch' | 'redirect_uri_mismatch';
+export type RedeemResult = {
+    ok: true;
+    userId: number;
+    record: AuthorizationCodeRecord;
+} | {
+    ok: false;
+    reason: RedeemFailure;
+    userId?: number;
+};
+export interface IssueCodeInput {
+    userId: number;
+    clientId: string;
+    clientPublicId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    codeChallengeMethod: string;
+    scopes: string[];
+    resource?: string | null;
+}
+export interface AuthorizationCodeService {
+    /** Mint the code, write the row, append the entry. Returns the raw code. */
+    issue(input: IssueCodeInput): Promise<{
+        code: string;
+        record: AuthorizationCodeRecord;
+    }>;
+    /**
+     * Redeem once. End-dates the identity row and stamps `redeemed_at`; a second
+     * call answers `already_redeemed` rather than `unknown_code`.
+     */
+    redeem(input: RedeemCodeInput): Promise<RedeemResult>;
+    /** The entries a user currently holds. Used by the credentials-at-rest test. */
+    list(userId: number): Promise<AuthorizationCodeRecord[]>;
+}
+export interface AuthorizationCodeServiceOptions {
+    tokenService: TokenService;
+    propertyStore: PropertyStore;
+    /**
+     * How the presented `redirect_uri` is compared with the stored one. Injected
+     * so this service does not have to know about RFC 8252's loopback-port
+     * exception, which lives in `matchRedirectUri` with its own test table.
+     */
+    matchRedirectUri(registered: string, presented: string): boolean;
+    now?: () => Date;
+}
+export declare function createAuthorizationCodeService(options: AuthorizationCodeServiceOptions): AuthorizationCodeService;
+//# sourceMappingURL=authorization-code-service.d.ts.map

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

@@ -0,0 +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"}

package/dist/authorization-code-service.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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");
+/**
+ * The authorization code: one identity row, one property entry.
+ *
+ * ## The two-read model, at its smallest
+ *
+ * The identity row in the `oauth-code` domain answers *who this code belongs
+ * to*, and it is the only place the code's hash lives. The `oauth-codes`
+ * property entry answers *what was asked for* — client, redirect URI, PKCE
+ * challenge, scopes, resource — and carries the code's own `expires_at`.
+ *
+ * The entry's `code_key` is the identity key, so the two reads join. That value
+ * 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
+ *
+ * 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.
+ *
+ * ## Expiry here is `expires_at`, not the identity-row rule
+ *
+ * The plan's `createdAt + ttl` correction governs access and refresh tokens,
+ * whose lifetime has no home on the row. The code's lifetime does have a home:
+ * this explicit field, written at issue time. It stays the authority, and the
+ * TTL that produced it is a constant in the package rather than configuration.
+ */
+exports.OAUTH_CODES_PROPERTY = 'oauth-codes';
+exports.OAUTH_CODES_INFO_SCHEMA = 'boop.oauth-server.codes.v1';
+function createAuthorizationCodeService(options) {
+    const { tokenService, propertyStore, matchRedirectUri } = options;
+    const now = options.now ?? (() => new Date());
+    /** Drop entries whose window has closed, so the array stays bounded. */
+    function live(entries, at) {
+        return entries.filter((entry) => Date.parse(entry.expires_at) > at.getTime());
+    }
+    return {
+        async issue(input) {
+            const at = now();
+            const minted = await tokenService.mint(input.userId, token_service_js_1.OAUTH_CODE_DOMAIN, input.clientPublicId);
+            const record = {
+                code_key: minted.identityKey,
+                client_id: input.clientId,
+                client_public_id: input.clientPublicId,
+                redirect_uri: input.redirectUri,
+                code_challenge: input.codeChallenge,
+                code_challenge_method: input.codeChallengeMethod,
+                scopes: [...input.scopes],
+                resource: input.resource ?? null,
+                issued_at: at.toISOString(),
+                // The identity row's own `createdAt + ttl` agrees with this, but this
+                // field is the authority — see the header.
+                expires_at: minted.expiresAt.toISOString(),
+                redeemed_at: null,
+            };
+            const snapshot = await (0, property_array_js_1.readArray)(propertyStore, input.userId, exports.OAUTH_CODES_PROPERTY);
+            await (0, property_array_js_1.writeArray)(propertyStore, input.userId, exports.OAUTH_CODES_PROPERTY, [...live(snapshot.entries, at), record], snapshot, { infoSchema: exports.OAUTH_CODES_INFO_SCHEMA });
+            return { code: minted.token, record };
+        },
+        async redeem(input) {
+            const identityKey = tokenService.identityKeyFor(input.code);
+            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`.
+            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.
+                //
+                // 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.
+                return { ok: false, reason: 'unknown_code' };
+            }
+            const snapshot = await (0, property_array_js_1.readArray)(propertyStore, resolved.userId, exports.OAUTH_CODES_PROPERTY);
+            const record = snapshot.entries.find((entry) => entry.code_key === identityKey);
+            // A live identity row with no entry is a half-written issue. Refusing is
+            // right: without the entry there is no redirect URI, no challenge and no
+            // 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.
+            if (record.redeemed_at !== null) {
+                return { ok: false, reason: 'already_redeemed', userId: resolved.userId };
+            }
+            if (Date.parse(record.expires_at) <= at.getTime()) {
+                return { ok: false, reason: 'expired', userId: resolved.userId };
+            }
+            if (record.client_id !== input.clientId || record.client_public_id !== input.clientPublicId) {
+                return { ok: false, reason: 'client_mismatch', userId: resolved.userId };
+            }
+            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 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.
+            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);
+            return { ok: true, userId: resolved.userId, record: redeemed };
+        },
+        async list(userId) {
+            const snapshot = await (0, property_array_js_1.readArray)(propertyStore, userId, exports.OAUTH_CODES_PROPERTY);
+            return snapshot.entries;
+        },
+    };
+}
+//# sourceMappingURL=authorization-code-service.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,146 @@
+import type { RequestHandler } from 'express';
+import type { AuthMiddlewareDeps, BaseUserInfo, User } from '@boopkit/cap-users';
+import './express.js';
+import type { GrantService, OAuthGrantRecord } from './grant-service.js';
+import { type TokenService } from './token-service.js';
+/**
+ * Resource-server bearer resolution: the OAuth instantiation of cap-users'
+ * `createBearerMiddleware`.
+ *
+ * ## Why this is a resolver and not a second middleware
+ *
+ * Slice 0 widened cap-users so that the bearer path takes its lookup as an
+ * injected callback. Everything about reading an `Authorization: Bearer` header
+ * — the parsing, the pass-through when there is no header, the 401 with a
+ * caller-chosen challenge, the deliberate refusal to fall back to the session
+ * cookie — is cap-users' and is shared with the API-key path. What is OAuth's
+ * is only the lookup, and it is three reads:
+ *
+ *   1. the `oauth-access` identity row, which answers *who*, and which applies
+ *      the `createdAt + ttl` expiry rule and its lazy `endedAt` sweep;
+ *   2. the `oauth-grants` entry for that user and that client, which answers
+ *      *what was approved* — and whose absence or `ended_at` is what makes a
+ *      revoke take effect on the client's very next request;
+ *   3. the user itself, so `req.user` is the same principal a cookie yields.
+ *
+ * The strategy label is `'oauth'`, never `'api-key'`. `requireApiKey` gates on
+ * that literal precisely so an OAuth access token fails a gate whose purpose is
+ * to demand an independently revocable key — by construction, rather than by
+ * somebody remembering.
+ *
+ * ## The gate takes its challenge from the resolver
+ *
+ * `requireOAuth(...scopes)` below is the RFC 6750 gate. It needs the same
+ * `WWW-Authenticate` challenge the resolver sends, because the two refuse
+ * different callers — the resolver refuses a caller with a *bad* token, the
+ * gate refuses one with *no* token — and a client that meets a bare `Bearer`
+ * from one of them is told nothing about where to go next.
+ *
+ * Rather than configure the challenge twice, the resolver **writes it onto the
+ * request** (`req.oauthChallenge`) and the gate reads it back. One value, one
+ * place it is set, and the two halves cannot be given different answers. It
+ * also means a hand-built `req` in a test carries no challenge, which is a
+ * useful nudge toward testing the gate behind the real resolver — the only
+ * arrangement that can catch a resolver that stopped attaching the grant.
+ */
+/** What the OAuth lookup finds, before it is split across the request. */
+export interface ResolvedOAuthPrincipal {
+    user: User<BaseUserInfo>;
+    grant: OAuthGrantRecord;
+    clientPublicId: string;
+}
+export interface OAuthBearerOptions {
+    tokenService: TokenService;
+    grantService: GrantService;
+    /** cap-users' `userService.findById`, injected rather than reached for. */
+    findUserById(userId: number): Promise<User<BaseUserInfo> | null>;
+    /**
+     * The `WWW-Authenticate` value on a 401.
+     *
+     * Defaults to a bare `Bearer`. A deployment that wants RFC 9728's
+     * `resource_metadata` pointer passes the fuller form, which the scaffold
+     * does. Whatever is passed here is also what `requireOAuth` sends, because
+     * the resolver hands it forward on `req.oauthChallenge`.
+     */
+    challenge?: string;
+}
+/**
+ * The lookup itself, exported so it can be tested without a request.
+ *
+ * Returns `null` for every reason a token is not usable — malformed, unknown,
+ * revoked, expired, or belonging to a grant that has been ended. The caller
+ * cannot tell them apart, and should not: the difference is only interesting to
+ * whoever stole the token.
+ */
+export declare function createOAuthTokenResolver(options: OAuthBearerOptions): (token: string) => Promise<ResolvedOAuthPrincipal | null>;
+/**
+ * The middleware an application mounts.
+ *
+ * cap-users' factory takes the lookup as a plain callback with no request in
+ * its signature — deliberately, since resolving a credential has no business
+ * reading one. But this capability has to hand the resolved grant to the
+ * handlers downstream, and the closure is the only place the two can meet, so
+ * 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;
+/** The challenge sent when the request carried no usable OAuth token at all. */
+export declare const DEFAULT_BEARER_CHALLENGE = "Bearer";
+/**
+ * Which of the required scopes this grant does not cover.
+ *
+ * Set membership, so the comparison does not depend on the order either list
+ * happens to be in — a grant approved as `email profile` covers a route that
+ * asks for `profile email`. Duplicates in the requirement collapse, so the
+ * answer is stable enough to put in a header.
+ */
+export declare function missingScopes(granted: readonly string[], required: readonly string[]): string[];
+/**
+ * `requireOAuth(...scopes)` — the resource-server gate.
+ *
+ * The request must have arrived on an OAuth access token backed by a live
+ * grant, and that grant must cover every named scope. Both refusals are RFC
+ * 6750:
+ *
+ *   - **401** with `WWW-Authenticate: <challenge>` when there is no usable
+ *     token. The challenge is the resolver's — see the file header — so it
+ *     carries RFC 9728's `resource_metadata` pointer and an unauthenticated
+ *     caller can find its way to the document that says where to go. Claude
+ *     does not honour that header on a 200, so the 401 is the only place it can
+ *     arrive.
+ *   - **403** with `error="insufficient_scope"` and the required `scope`, in
+ *     the header per §3.1 and in the body so a client that reads JSON errors
+ *     rather than headers gets the same answer.
+ *
+ * The **grant** is the authority, not the token: a token minted under a wider
+ * consent is bound by a narrowed grant on its very next request, with no
+ * revocation involved.
+ *
+ * Mount it behind `resolveBearer`. `createOAuthResourceServer` pairs the two so
+ * an application cannot mount one without the other.
+ */
+export declare function requireOAuth(...requiredScopes: string[]): RequestHandler;
+/**
+ * The resource-server pair, built from one set of options.
+ *
+ * An application needs both halves and they have to agree about one thing: the
+ * `WWW-Authenticate` challenge. A caller with no credential at all is refused
+ * by the *gate* (the resolver passes an unauthenticated request through on
+ * purpose, so it can be mounted on a router that also serves anonymous
+ * traffic), while a caller with a bad credential is refused by the *resolver*.
+ * Both therefore have to carry the pointer, which the resolver arranges by
+ * writing the challenge onto the request for the gate to read.
+ *
+ * So this factory exists for the mounting rather than for the wiring: taking
+ * both halves from one call is what stops an application mounting the gate on a
+ * router that has no resolver in front of it, where every request would be a
+ * 401 with a bare `Bearer`.
+ */
+export interface OAuthResourceServer {
+    /** Mount ahead of the routes you are protecting. */
+    resolveBearer: RequestHandler;
+    /** Then gate them: `requireOAuth('profile')`. */
+    requireOAuth(...scopes: string[]): RequestHandler;
+}
+export declare function createOAuthResourceServer(deps: AuthMiddlewareDeps, options: OAuthBearerOptions): OAuthResourceServer;
+//# sourceMappingURL=bearer.d.ts.map

package/dist/bearer.d.ts.map

@@ -0,0 +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"}