@boopkit/cap-oauth-server 0.1.0

package/dist/revocation-controller.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRevocationHandlers = createRevocationHandlers;
+exports.createRevocationRouter = createRevocationRouter;
+const express_1 = require("express");
+const body_field_js_1 = require("./body-field.js");
+const oauth_error_js_1 = require("./oauth-error.js");
+const request_client_js_1 = require("./request-client.js");
+const revocation_service_js_1 = require("./revocation-service.js");
+const token_service_js_1 = require("./token-service.js");
+/**
+ * `POST /oauth/revoke` — RFC 7009, the third and last way a connection ends.
+ *
+ * The other two were already here. A person disconnecting in the application
+ * goes through `/connections` and its confirmation page; an operator retiring a
+ * compromised client calls `revocationService.revokeClient`. This is the
+ * **client-driven** case: a connector handing a token back because the user
+ * disconnected on its side, which is the only one of the three that a piece of
+ * software rather than a person initiates.
+ *
+ * It exists because the discovery document advertises `revocation_endpoint`, and
+ * this package's own rule — argued in `discovery.ts`, and enforced on the device
+ * grant type by `OAUTH_DEVICE_CODE_ENABLED` — is that advertising an endpoint
+ * which answers 404 is a lie a client cannot interpret: having read the
+ * metadata, it reads the 404 as a server fault rather than as an unsupported
+ * feature. The alternative was taking the field back out. Mounting it is better,
+ * because a connector that cannot hand a token back leaves the user to discover
+ * the still-live connection in an application they may never open again.
+ *
+ * ## Which token ends what, which is the decision this file exists to record
+ *
+ * RFC 7009 §2.1 leaves it open in both directions: revoking a refresh token
+ * SHOULD also invalidate the access tokens issued from it, and revoking an
+ * access token MAY invalidate the refresh token. This server answers the two
+ * halves differently, and the second answer is the non-obvious one.
+ *
+ * **A refresh token ends the whole grant.** Take the SHOULD. The grant is this
+ * server's unit of connection — it is what the guard reads, what `/connections`
+ * lists, and what carries the revocation reason — and a connector calling this
+ * on user-disconnect wants the connection gone rather than one credential of it.
+ * So the presented refresh token routes to `revocationService`, which end-dates
+ * the grant with `REVOKED_BY_CLIENT` and sweeps every live token row the client
+ * holds for that user.
+ *
+ * **An access token ends only its own row. Decline the MAY.** This server
+ * rotates the refresh token on every use but deliberately does *not* end-date
+ * the superseded **access** row, so the access token from before a refresh stays
+ * live until its TTL runs out. A tidy client that revokes that old access token
+ * right after refreshing is doing exactly the housekeeping RFC 7009 exists for —
+ * and under the MAY it would destroy the grant it had just refreshed. That is a
+ * self-inflicted outage the specification permits and we should not build.
+ *
+ * **An already-ended grant still gets the presented row swept.**
+ * `revokeClientForUser` looks for an *active* grant and answers `null` when
+ * there is none, and rotation leaves superseded refresh rows deliberately
+ * active — so a live refresh row under a dead grant is a reachable state, and
+ * the fall-through to `revokeByKey` is what ends it. Without that, the answer
+ * would still be 200 and the row would still be there.
+ *
+ * ## §2.2, and the rule that everything is 200
+ *
+ * A revocation response says nothing about the token. Revoked, already invalid,
+ * expired, never existed, or belonging to a different client — all of them are
+ * **200 with an empty body**, because any other answer tells an unauthenticated
+ * caller (every client here is public) whether a string it holds is a real
+ * credential. The last of those is the one that feels wrong and is not: there is
+ * no way to report "that token is not yours" without first confirming the token
+ * exists.
+ *
+ * The errors are only about the request itself: `400 invalid_request` for a
+ * missing `token` or `client_id`, `400 unsupported_token_type` for a
+ * `token_type_hint` naming a species this server does not issue (§2.2.1), and
+ * `401 invalid_client` for a client that is unknown or suspended.
+ *
+ * ## The hint is advisory, so both domains are tried
+ *
+ * §2.1 says the hint is an optimisation and a server MUST fall back to searching
+ * the other types. It is honoured as an ordering and nothing more: a client that
+ * mislabels a correctly-presented token still gets it revoked. A given token
+ * exists in at most one domain — the raw value is hashed into the key — so the
+ * order only ever saves a lookup, never changes the outcome.
+ */
+/**
+ * RFC 7009 §2.1's registered hints, mapped to this server's token domains.
+ *
+ * A `Map` rather than an object literal, because the hint is attacker-supplied
+ * and an object's keys include the ones it inherited: `token_type_hint=toString`
+ * would read back a function from `Object.prototype` and pass for a recognised
+ * hint. A `Map` knows only what was put in it.
+ */
+const DOMAIN_BY_HINT = new Map([
+    ['access_token', token_service_js_1.OAUTH_ACCESS_DOMAIN],
+    ['refresh_token', token_service_js_1.OAUTH_REFRESH_DOMAIN],
+]);
+function createRevocationHandlers(deps) {
+    const { clientRegistry, tokenService, revocationService } = deps;
+    /** The hint's domain first, then the other. See the header: advisory only. */
+    function searchOrder(hint) {
+        const hinted = hint === undefined ? undefined : DOMAIN_BY_HINT.get(hint);
+        if (hint !== undefined && hinted === undefined) {
+            // §2.2.1. An unrecognised hint is the one thing about the token itself
+            // that is safe to refuse, because it says nothing about whether the token
+            // is real — it is a statement about the request's vocabulary.
+            throw new oauth_error_js_1.OAuthError('unsupported_token_type', `this server issues access_token and refresh_token, not ${hint}`);
+        }
+        if (hinted === token_service_js_1.OAUTH_REFRESH_DOMAIN)
+            return [token_service_js_1.OAUTH_REFRESH_DOMAIN, token_service_js_1.OAUTH_ACCESS_DOMAIN];
+        return [token_service_js_1.OAUTH_ACCESS_DOMAIN, token_service_js_1.OAUTH_REFRESH_DOMAIN];
+    }
+    /** End what this token stands for. See the header for why the two differ. */
+    async function endCredential(domain, userId, identityKey, clientPublicId) {
+        if (domain === token_service_js_1.OAUTH_ACCESS_DOMAIN) {
+            await tokenService.revokeByKey(token_service_js_1.OAUTH_ACCESS_DOMAIN, identityKey);
+            return;
+        }
+        const revoked = await revocationService.revokeClientForUser(userId, clientPublicId, revocation_service_js_1.REVOKED_BY_CLIENT);
+        // No active grant to end — but the row that was presented is live, or it
+        // would not have resolved a moment ago. Sweep it on its own.
+        if (!revoked) {
+            await tokenService.revokeByKey(token_service_js_1.OAUTH_REFRESH_DOMAIN, identityKey);
+        }
+    }
+    const revoke = async (req, res, next) => {
+        // §2.2 sends no body worth caching, and the request carried a credential.
+        res.set('Cache-Control', 'no-store');
+        res.set('Pragma', 'no-cache');
+        try {
+            const presented = (0, body_field_js_1.required)(req.body, 'token');
+            const order = searchOrder((0, body_field_js_1.field)(req.body, 'token_type_hint'));
+            const client = await (0, request_client_js_1.resolveRequestClient)(clientRegistry, req.body);
+            // The client prefix is readable off the token before any lookup, so a
+            // token belonging to somebody else is dropped without touching the
+            // database — and, per §2.2, without being distinguishable from success.
+            const parsed = tokenService.parseToken(presented);
+            if (parsed && parsed.clientPublicId === client.publicId) {
+                for (const domain of order) {
+                    const resolved = await tokenService.resolve(domain, presented);
+                    if (!resolved)
+                        continue;
+                    await endCredential(domain, resolved.userId, resolved.identityKey, client.publicId);
+                    break;
+                }
+            }
+            // §2.2: 200 and nothing else, whatever happened above.
+            res.status(200).end();
+        }
+        catch (err) {
+            if ((0, oauth_error_js_1.isOAuthError)(err)) {
+                if (err.error === 'invalid_client') {
+                    res.set('WWW-Authenticate', 'Bearer');
+                }
+                res.status(err.status).json(err.toBody());
+                return;
+            }
+            next(err);
+        }
+    };
+    return { revoke };
+}
+/**
+ * `POST /oauth/revoke`, with both body parsers attached.
+ *
+ * Form and JSON, for the reason `createTokenRouter` mounts both: the RFC says
+ * form and the ecosystem sends JSON, and a client that gets this wrong on the
+ * revocation endpoint has already got it right on the token endpoint. The
+ * router parses its own body so the endpoint behaves the same whatever order the
+ * host application mounts its middleware in.
+ */
+function createRevocationRouter(options) {
+    const handlers = createRevocationHandlers(options);
+    const router = (0, express_1.Router)();
+    const limit = options.bodyLimit ?? '16kb';
+    router.post('/oauth/revoke', (0, express_1.urlencoded)({ extended: false, limit }), (0, express_1.json)({ limit }), handlers.revoke);
+    return router;
+}
+//# sourceMappingURL=revocation-controller.js.map

package/dist/revocation-controller.js.map

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

package/dist/revocation-service.d.ts

@@ -0,0 +1,113 @@
+import { type GrantService, type OAuthGrantRecord } from './grant-service.js';
+import type { TokenService } from './token-service.js';
+import type { StoredIdentity } from './user-store.js';
+/**
+ * Disconnecting a client — the write behind the disconnect button, and behind
+ * the operator's answer to a compromised client.
+ *
+ * ## Soft revocation, and why the signal lives on the grant
+ *
+ * Nothing is deleted. The grant record is end-dated with a reason and the
+ * client's token rows are end-dated too, so cap-users' active-only resolution
+ * refuses the very next request whatever the token's stated lifetime says. The
+ * rows that are left behind are the audit trail, which is the point: a user who
+ * has just disconnected something wants to see that it stuck, and an operator
+ * investigating an incident wants to see what was once connected.
+ *
+ * **But the identity rows cannot carry the answer, in either direction.** An
+ * ended row does not mean revoked: `tokenService.resolve` end-dates a row the
+ * first time it reads an expired one, so ordinary expiry produces the same
+ * tombstone that revocation does. And a *live* row does not mean connected:
+ * rotation leaves the superseded refresh row deliberately active, so that
+ * presenting it again is recognisable as reuse rather than as a typo, and a
+ * connector in daily use therefore accumulates live rows it will never use
+ * again. Neither the presence nor the absence of a row is the signal.
+ *
+ * The signal is the **grant record**, which carries `ended_at` and a reason, and
+ * that is what the connected-clients screen and the resource-server guard both
+ * read. A test covers exactly this: a client that rotated three times and was
+ * then revoked still reads as revoked, and every one of the token rows those
+ * rotations left behind stops working.
+ *
+ * ## The order of the two writes
+ *
+ * The grant is ended **first**, then the tokens. Both orders leave the client
+ * locked out — the guard needs a live grant *and* a live token row, so ending
+ * either one is enough — but ending the grant first makes the lockout a single
+ * write. If the token sweep then fails halfway, access is already refused and
+ * the sweep is safe to retry, whereas the other order leaves a window in which
+ * some tokens still resolve against a live grant.
+ *
+ * ## Client-wide revocation finds its own users
+ *
+ * `revokeClient` takes a client and nothing else. It asks cap-users for every
+ * identity row whose key starts with `"<publicId>|"` — the scan the token wire
+ * format was shaped to make cheap — and sweeps the users that come back, one
+ * grant at a time. The operator answering a compromised client therefore does
+ * not have to already know the blast radius, which was the old shape's real
+ * cost: `revokeClientForUsers(userIds, ...)` was correct and swept exactly the
+ * accounts somebody had thought to name.
+ *
+ * The scan is still cap-users' query rather than ours (`IdentityStore`, backed
+ * by `findAllByDomainAndKeyPrefix`), so the one hard invariant is unchanged —
+ * this capability does not reach into the identity table, by prefix or
+ * otherwise.
+ *
+ * Two things it deliberately does **not** do. It does not read revocation off
+ * the identity rows: they say who this client once reached, and the grant
+ * record says whether anything is still connected. And it does not narrow the
+ * scan to live rows, because an idle connection's rows are all end-dated by the
+ * expiry sweep while its grant is perfectly alive.
+ */
+/** The reason recorded when a person disconnects a client themselves. */
+export declare const REVOKED_BY_USER = "user_revoked";
+/** The reason recorded when an operator retires a client for everybody. */
+export declare const REVOKED_CLIENT_WIDE = "client_revoked";
+/**
+ * The reason recorded when the client itself hands a refresh token back at
+ * `POST /oauth/revoke` — RFC 7009's case, and the third of the three.
+ *
+ * It is a distinct word from `REVOKED_BY_USER` on purpose. Both are somebody
+ * choosing to disconnect, but only one of them was a person standing in front
+ * of this application's confirmation page; an operator reading the audit trail
+ * afterwards wants to know which door the disconnect came through.
+ */
+export declare const REVOKED_BY_CLIENT = "client_requested";
+/** What one revocation did. */
+export interface RevokedGrant {
+    /** The grant as it now stands, carrying `ended_at` and `ended_reason`. */
+    grant: OAuthGrantRecord;
+    /**
+     * The token rows this revocation end-dated.
+     *
+     * Empty is an ordinary outcome, not a failure: a grant whose access token has
+     * already expired and whose refresh token was rotated out has no live rows
+     * left to end.
+     */
+    endedTokens: StoredIdentity[];
+}
+export interface RevocationService {
+    /** Disconnect one grant by its id. `null` when this user has no such grant. */
+    revokeGrant(userId: number, grantId: string, reason?: string): Promise<RevokedGrant | null>;
+    /** The same, addressed by client instead. `null` when nothing is connected. */
+    revokeClientForUser(userId: number, clientPublicId: string, reason?: string): Promise<RevokedGrant | null>;
+    /**
+     * Retire one client across the whole deployment — the compromised-client case.
+     *
+     * Finds its own users, through the token service's key-prefix scan. Answers
+     * with one entry per user that actually had a live grant, so the result's
+     * length is how many connections were broken rather than how many users the
+     * scan turned up.
+     *
+     * Throws when `clientPublicId` is not a well-formed public id, rather than
+     * quietly sweeping nothing: during an incident, a typo that reads as "no
+     * users are affected" is the worst answer available.
+     */
+    revokeClient(clientPublicId: string, reason?: string): Promise<RevokedGrant[]>;
+}
+export interface RevocationServiceOptions {
+    grantService: GrantService;
+    tokenService: TokenService;
+}
+export declare function createRevocationService(options: RevocationServiceOptions): RevocationService;
+//# sourceMappingURL=revocation-service.d.ts.map

package/dist/revocation-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revocation-service.d.ts","sourceRoot":"","sources":["../src/revocation-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC7F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,yEAAyE;AACzE,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAE9C,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAEpD,+BAA+B;AAC/B,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;;;OAMG;IACH,WAAW,EAAE,cAAc,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC5F,+EAA+E;IAC/E,mBAAmB,CACjB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAChC;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAmD5F"}

package/dist/revocation-service.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVOKED_BY_CLIENT = exports.REVOKED_CLIENT_WIDE = exports.REVOKED_BY_USER = void 0;
+exports.createRevocationService = createRevocationService;
+const grant_service_js_1 = require("./grant-service.js");
+/**
+ * Disconnecting a client — the write behind the disconnect button, and behind
+ * the operator's answer to a compromised client.
+ *
+ * ## Soft revocation, and why the signal lives on the grant
+ *
+ * Nothing is deleted. The grant record is end-dated with a reason and the
+ * client's token rows are end-dated too, so cap-users' active-only resolution
+ * refuses the very next request whatever the token's stated lifetime says. The
+ * rows that are left behind are the audit trail, which is the point: a user who
+ * has just disconnected something wants to see that it stuck, and an operator
+ * investigating an incident wants to see what was once connected.
+ *
+ * **But the identity rows cannot carry the answer, in either direction.** An
+ * ended row does not mean revoked: `tokenService.resolve` end-dates a row the
+ * first time it reads an expired one, so ordinary expiry produces the same
+ * tombstone that revocation does. And a *live* row does not mean connected:
+ * rotation leaves the superseded refresh row deliberately active, so that
+ * presenting it again is recognisable as reuse rather than as a typo, and a
+ * connector in daily use therefore accumulates live rows it will never use
+ * again. Neither the presence nor the absence of a row is the signal.
+ *
+ * The signal is the **grant record**, which carries `ended_at` and a reason, and
+ * that is what the connected-clients screen and the resource-server guard both
+ * read. A test covers exactly this: a client that rotated three times and was
+ * then revoked still reads as revoked, and every one of the token rows those
+ * rotations left behind stops working.
+ *
+ * ## The order of the two writes
+ *
+ * The grant is ended **first**, then the tokens. Both orders leave the client
+ * locked out — the guard needs a live grant *and* a live token row, so ending
+ * either one is enough — but ending the grant first makes the lockout a single
+ * write. If the token sweep then fails halfway, access is already refused and
+ * the sweep is safe to retry, whereas the other order leaves a window in which
+ * some tokens still resolve against a live grant.
+ *
+ * ## Client-wide revocation finds its own users
+ *
+ * `revokeClient` takes a client and nothing else. It asks cap-users for every
+ * identity row whose key starts with `"<publicId>|"` — the scan the token wire
+ * format was shaped to make cheap — and sweeps the users that come back, one
+ * grant at a time. The operator answering a compromised client therefore does
+ * not have to already know the blast radius, which was the old shape's real
+ * cost: `revokeClientForUsers(userIds, ...)` was correct and swept exactly the
+ * accounts somebody had thought to name.
+ *
+ * The scan is still cap-users' query rather than ours (`IdentityStore`, backed
+ * by `findAllByDomainAndKeyPrefix`), so the one hard invariant is unchanged —
+ * this capability does not reach into the identity table, by prefix or
+ * otherwise.
+ *
+ * Two things it deliberately does **not** do. It does not read revocation off
+ * the identity rows: they say who this client once reached, and the grant
+ * record says whether anything is still connected. And it does not narrow the
+ * scan to live rows, because an idle connection's rows are all end-dated by the
+ * expiry sweep while its grant is perfectly alive.
+ */
+/** The reason recorded when a person disconnects a client themselves. */
+exports.REVOKED_BY_USER = 'user_revoked';
+/** The reason recorded when an operator retires a client for everybody. */
+exports.REVOKED_CLIENT_WIDE = 'client_revoked';
+/**
+ * The reason recorded when the client itself hands a refresh token back at
+ * `POST /oauth/revoke` — RFC 7009's case, and the third of the three.
+ *
+ * It is a distinct word from `REVOKED_BY_USER` on purpose. Both are somebody
+ * choosing to disconnect, but only one of them was a person standing in front
+ * of this application's confirmation page; an operator reading the audit trail
+ * afterwards wants to know which door the disconnect came through.
+ */
+exports.REVOKED_BY_CLIENT = 'client_requested';
+function createRevocationService(options) {
+    const { grantService, tokenService } = options;
+    /** End the grant, then sweep its tokens. See the header for the order. */
+    async function revoke(userId, grant, reason) {
+        const ended = (await grantService.end(userId, grant.grant_id, reason)) ?? grant;
+        const endedTokens = await tokenService.revokeTokensForClient(userId, grant.client_public_id);
+        return { grant: ended, endedTokens };
+    }
+    return {
+        async revokeGrant(userId, grantId, reason = exports.REVOKED_BY_USER) {
+            const grant = await grantService.findById(userId, grantId);
+            if (!grant)
+                return null;
+            // An already-ended grant still gets its tokens swept. `grantService.end`
+            // keeps the original reason and timestamp, so this is idempotent rather
+            // than a second revocation, and it repairs a run that failed partway.
+            return revoke(userId, grant, reason);
+        },
+        async revokeClientForUser(userId, clientPublicId, reason = exports.REVOKED_BY_USER) {
+            const grant = await grantService.findActive(userId, clientPublicId);
+            if (!grant)
+                return null;
+            return revoke(userId, grant, reason);
+        },
+        async revokeClient(clientPublicId, reason = exports.REVOKED_CLIENT_WIDE) {
+            // Ended rows included, so a user whose tokens have all expired is still
+            // found — their grant is what says they are connected. See the header.
+            const userIds = await tokenService.findUserIdsForClient(clientPublicId);
+            const revoked = [];
+            for (const userId of userIds) {
+                const grants = await grantService.list(userId);
+                // Only this client's grants, matched on the full `client_public_id`
+                // rather than on a prefix of it: a `startsWith` here would be the
+                // too-broad scan that ends a neighbouring client's connections.
+                const mine = grants.filter((grant) => grant.client_public_id === clientPublicId && (0, grant_service_js_1.isGrantActive)(grant));
+                for (const grant of mine) {
+                    revoked.push(await revoke(userId, grant, reason));
+                }
+            }
+            return revoked;
+        },
+    };
+}
+//# sourceMappingURL=revocation-service.js.map

package/dist/revocation-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revocation-service.js","sourceRoot":"","sources":["../src/revocation-service.ts"],"names":[],"mappings":";;;AA2HA,0DAmDC;AA9KD,yDAA6F;AAI7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,yEAAyE;AAC5D,QAAA,eAAe,GAAG,cAAc,CAAC;AAE9C,2EAA2E;AAC9D,QAAA,mBAAmB,GAAG,gBAAgB,CAAC;AAEpD;;;;;;;;GAQG;AACU,QAAA,iBAAiB,GAAG,kBAAkB,CAAC;AA6CpD,SAAgB,uBAAuB,CAAC,OAAiC;IACvE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IAE/C,0EAA0E;IAC1E,KAAK,UAAU,MAAM,CACnB,MAAc,EACd,KAAuB,EACvB,MAAc;QAEd,MAAM,KAAK,GAAG,CAAC,MAAM,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC;QAChF,MAAM,WAAW,GAAG,MAAM,YAAY,CAAC,qBAAqB,CAAC,MAAM,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAC7F,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IACvC,CAAC;IAED,OAAO;QACL,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,uBAAe;YACzD,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC3D,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;YACxB,yEAAyE;YACzE,wEAAwE;YACxE,sEAAsE;YACtE,OAAO,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QACvC,CAAC;QAED,KAAK,CAAC,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,uBAAe;YACxE,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;YACpE,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;YACxB,OAAO,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QACvC,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,2BAAmB;YAC7D,wEAAwE;YACxE,uEAAuE;YACvE,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,oBAAoB,CAAC,cAAc,CAAC,CAAC;YAExE,MAAM,OAAO,GAAmB,EAAE,CAAC;YACnC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC/C,oEAAoE;gBACpE,kEAAkE;gBAClE,gEAAgE;gBAChE,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CACxB,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,gBAAgB,KAAK,cAAc,IAAI,IAAA,gCAAa,EAAC,KAAK,CAAC,CAC7E,CAAC;gBACF,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;oBACzB,OAAO,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;gBACpD,CAAC;YACH,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/token-controller.d.ts

@@ -0,0 +1,79 @@
+import { Router, type RequestHandler } from 'express';
+import type { AuthorizationCodeService } from './authorization-code-service.js';
+import type { ClientRegistryService } from './client-registry-service.js';
+import type { GrantService } from './grant-service.js';
+import { type TokenService } from './token-service.js';
+/**
+ * `POST /oauth/token` — the two grants a boop application issues tokens for.
+ *
+ * ## Both body encodings, and only one of them is the specification's
+ *
+ * RFC 6749 §4.1.3 says `application/x-www-form-urlencoded`, full stop. ChatGPT
+ * sends JSON. So both parsers are mounted, and that is **tolerated input rather
+ * than a second supported format**: a client that reads the metadata and
+ * follows the RFC sends a form, and one that does not still connects. The
+ * umbrella spec lists "JSON-only token endpoints" among the donor defects; the
+ * mirror-image defect — form-only, in an ecosystem that demonstrably sends JSON
+ * — costs a user a connection they cannot debug.
+ *
+ * ## Reuse of a rotated refresh token revokes the whole grant
+ *
+ * Presenting a refresh token that has already been rotated is evidence of
+ * theft, because the legitimate client holds the newer one. The alternative —
+ * refusing the request and leaving the grant alive — lets an attacker who lost
+ * the race keep trying, and lets a compromised client keep working beside the
+ * real one. So all of the grant's `oauth-access` and `oauth-refresh` rows are
+ * end-dated, the grant is end-dated with `reason: "refresh_reuse"`, and the
+ * answer is `400 invalid_grant`.
+ *
+ * **How reuse is detected, since it is not obvious.** A rotated refresh token's
+ * identity row is left *active* rather than end-dated, and the grant records
+ * the identity key of the token that is currently valid. Presenting an old
+ * token therefore still resolves — which is the point, because resolution is
+ * the only thing that yields a user id, and without a user id there is no way
+ * to reach the grant at all (grants are user properties, and cap-users'
+ * `(domain, key)` lookup is active-only). The old row grants nothing: its key
+ * does not match `grant.refresh_key`, so it takes the theft branch. End-dating
+ * the row instead would make the presented token resolve to nothing, and a
+ * stolen token would then be indistinguishable from a typo — which is precisely
+ * the case this design exists to tell apart.
+ *
+ * Superseded rows are bounded: they age out under the same
+ * `createdAt + refresh ttl` rule as any other token, and revoking the grant
+ * end-dates all of them at once.
+ */
+/** RFC 6749 §5.1's success body. */
+export interface TokenResponse {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    refresh_token?: string;
+    scope: string;
+}
+export interface TokenHandlerDeps {
+    clientRegistry: ClientRegistryService;
+    tokenService: TokenService;
+    grantService: GrantService;
+    authorizationCodeService: AuthorizationCodeService;
+}
+/** The scope that earns a refresh token, per the discovery document. */
+export declare const OFFLINE_ACCESS_SCOPE = "offline_access";
+/** RFC 6749 §3.3: scopes are space-delimited. Tolerate any run of whitespace. */
+export declare function parseScopes(raw: string | undefined): string[];
+export declare function createTokenHandlers(deps: TokenHandlerDeps): {
+    token: RequestHandler;
+};
+export interface TokenRouterOptions extends TokenHandlerDeps {
+    /** Maximum accepted body size. A token request is a handful of fields. */
+    bodyLimit?: string;
+}
+/**
+ * `POST /oauth/token`, with both body parsers attached.
+ *
+ * The router parses its own body rather than relying on an app-level
+ * `express.urlencoded()`, so the endpoint behaves the same whatever order the
+ * host application mounts its middleware in — and so the limit here is the one
+ * that applies.
+ */
+export declare function createTokenRouter(options: TokenRouterOptions): Router;
+//# sourceMappingURL=token-controller.d.ts.map

package/dist/token-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-controller.d.ts","sourceRoot":"","sources":["../src/token-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAkC,KAAK,cAAc,EAAiB,MAAM,SAAS,CAAC;AAErG,OAAO,KAAK,EAAE,wBAAwB,EAAiB,MAAM,iCAAiC,CAAC;AAE/F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,oBAAoB,CAAC;AAIzE,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAI5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,QAAQ,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,qBAAqB,CAAC;IACtC,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,YAAY,CAAC;IAC3B,wBAAwB,EAAE,wBAAwB,CAAC;CACpD;AAED,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AAWrD,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAG7D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG;IAAE,KAAK,EAAE,cAAc,CAAA;CAAE,CAiMrF;AAED,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAarE"}