@boopkit/cap-oauth-server 0.1.0

package/dist/pkce.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODE_CHALLENGE_METHOD = void 0;
+exports.isValidCodeVerifier = isValidCodeVerifier;
+exports.isValidCodeChallenge = isValidCodeChallenge;
+exports.deriveCodeChallenge = deriveCodeChallenge;
+exports.verifyCodeChallenge = verifyCodeChallenge;
+const node_crypto_1 = require("node:crypto");
+/**
+ * PKCE, RFC 7636 — and only `S256`.
+ *
+ * `plain` is not a weaker method, it is the absence of one: the "challenge" is
+ * the verifier, so an attacker who intercepted the authorization response has
+ * everything needed to redeem the code. The discovery document advertises
+ * `["S256"]` and this module is the other half of that promise — a request
+ * carrying `code_challenge_method=plain` is refused rather than downgraded to.
+ *
+ * OAuth 2.1 requires PKCE for public clients, and every client this server will
+ * ever see is public, so the challenge is **required** rather than optional.
+ */
+/** The only method this server accepts. Matches the discovery document. */
+exports.CODE_CHALLENGE_METHOD = 'S256';
+/** RFC 7636 §4.1: 43–128 characters from the unreserved set. */
+const VERIFIER_RE = /^[A-Za-z0-9\-._~]{43,128}$/;
+/**
+ * RFC 7636 §4.2: base64url of a SHA-256 digest — 43 characters, no padding.
+ *
+ * Checked as a shape before it is compared, because a challenge that was stored
+ * from a malformed registration request should fail loudly rather than by never
+ * matching anything.
+ */
+const CHALLENGE_RE = /^[A-Za-z0-9\-_]{43}$/;
+function isValidCodeVerifier(value) {
+    return typeof value === 'string' && VERIFIER_RE.test(value);
+}
+function isValidCodeChallenge(value) {
+    return typeof value === 'string' && CHALLENGE_RE.test(value);
+}
+/** BASE64URL-ENCODE(SHA256(ASCII(verifier))), per RFC 7636 §4.6. */
+function deriveCodeChallenge(verifier) {
+    return (0, node_crypto_1.createHash)('sha256').update(verifier, 'ascii').digest('base64url');
+}
+/**
+ * Does `verifier` satisfy the `challenge` the authorization request carried?
+ *
+ * Compared with `timingSafeEqual` rather than `===`. The challenge is not a
+ * secret — it travelled in a query string — but the comparison is on the
+ * redemption path next to comparisons that are, and a codebase where one string
+ * equality is constant-time and its neighbour is not teaches the wrong habit to
+ * whoever writes the third one.
+ */
+function verifyCodeChallenge(verifier, challenge, method = exports.CODE_CHALLENGE_METHOD) {
+    if (method !== exports.CODE_CHALLENGE_METHOD)
+        return false;
+    if (!isValidCodeVerifier(verifier))
+        return false;
+    if (!isValidCodeChallenge(challenge))
+        return false;
+    const derived = Buffer.from(deriveCodeChallenge(verifier), 'utf8');
+    const expected = Buffer.from(challenge, 'utf8');
+    if (derived.length !== expected.length)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(derived, expected);
+}
+//# sourceMappingURL=pkce.js.map

package/dist/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../src/pkce.ts"],"names":[],"mappings":";;;AA8BA,kDAEC;AAED,oDAEC;AAGD,kDAEC;AAWD,kDAaC;AAjED,6CAA0D;AAE1D;;;;;;;;;;;GAWG;AAEH,2EAA2E;AAC9D,QAAA,qBAAqB,GAAG,MAAM,CAAC;AAE5C,gEAAgE;AAChE,MAAM,WAAW,GAAG,4BAA4B,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAE5C,SAAgB,mBAAmB,CAAC,KAAc;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED,SAAgB,oBAAoB,CAAC,KAAc;IACjD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED,oEAAoE;AACpE,SAAgB,mBAAmB,CAAC,QAAgB;IAClD,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CACjC,QAAiB,EACjB,SAAkB,EAClB,SAAkB,6BAAqB;IAEvC,IAAI,MAAM,KAAK,6BAAqB;QAAE,OAAO,KAAK,CAAC;IACnD,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,CAAC,oBAAoB,CAAC,SAAS,CAAC;QAAE,OAAO,KAAK,CAAC;IAEnD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAChD,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACrD,OAAO,IAAA,6BAAe,EAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAC5C,CAAC"}

package/dist/property-array.d.ts

@@ -0,0 +1,60 @@
+import type { PropertyStore, PropertyWriteOptions, StoredProperty } from './user-store.js';
+/**
+ * The read-modify-write discipline both OAuth user properties are written
+ * under, in one place so the two cannot drift apart.
+ *
+ * ## Why the whole array, every time
+ *
+ * `oauth-grants` and `oauth-codes` are arrays inside a single `info` blob.
+ * Writing one means writing all of it, and that will feel wasteful next to
+ * cap-users' `addAuthenticationMethod`, which updates one entry. Reaching for
+ * that narrower shape is the bug in boop-zj8: it *replaces* an entry rather
+ * than merging it, so it silently destroys every field the write did not name.
+ * The pattern to follow is `setAuthorization`'s.
+ *
+ * The array rewrite is not merely the safe option, it is what makes the
+ * property worth being a property. A concurrent consent and revoke both read
+ * revision N and both write; the second write carries a stale
+ * `expectedRevision` and is **refused**. Without the revision check one of the
+ * two would simply vanish, and nothing anywhere would say so.
+ *
+ * ## No retry here, on purpose
+ *
+ * `write` surfaces the refusal rather than re-reading and trying again. A retry
+ * loop in this module would make the collision invisible to its caller, and the
+ * two callers want different things from it: the token endpoint should answer
+ * the client rather than race a human, and a revocation should be told that
+ * something else changed the grant underneath it.
+ */
+/** A property's current contents plus the revision a write must quote back. */
+export interface ArraySnapshot<T> {
+    entries: T[];
+    /**
+     * `undefined` when the property does not exist yet — which is what a first
+     * write must pass, since quoting a revision for a row that is about to be
+     * created would refuse every first write.
+     */
+    revision: number | undefined;
+    record: StoredProperty<{
+        entries?: unknown;
+    }> | null;
+}
+/**
+ * Read a property whose `info` is `{ entries: [...] }`.
+ *
+ * A missing property, a null `info`, or an `entries` that is not an array all
+ * read as empty rather than throwing. The blob accepts arbitrary JSON and the
+ * database cannot object, so the read path has to treat the shape as a claim.
+ */
+export declare function readArray<T>(store: PropertyStore, userId: number, property: string): Promise<ArraySnapshot<T>>;
+/**
+ * Write the whole array back, quoting the revision the caller read.
+ *
+ * Throws cap-services' `StaleEntityError` when the stored revision has moved
+ * on. Use `isStaleWriteError` to recognise it; see this module's header for why
+ * that is not caught here.
+ */
+export declare function writeArray<T>(store: PropertyStore, userId: number, property: string, entries: T[], snapshot: Pick<ArraySnapshot<T>, 'revision'>, options?: Omit<PropertyWriteOptions, 'expectedRevision'>): Promise<StoredProperty<{
+    entries: T[];
+}>>;
+//# sourceMappingURL=property-array.d.ts.map

package/dist/property-array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-array.d.ts","sourceRoot":"","sources":["../src/property-array.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,EAAE,CAAC,EAAE,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,cAAc,CAAC;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;CACtD;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAQ3B;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,EAAE,EACZ,QAAQ,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAC5C,OAAO,GAAE,IAAI,CAAC,oBAAoB,EAAE,kBAAkB,CAAM,GAC3D,OAAO,CAAC,cAAc,CAAC;IAAE,OAAO,EAAE,CAAC,EAAE,CAAA;CAAE,CAAC,CAAC,CAO3C"}

package/dist/property-array.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readArray = readArray;
+exports.writeArray = writeArray;
+/**
+ * Read a property whose `info` is `{ entries: [...] }`.
+ *
+ * A missing property, a null `info`, or an `entries` that is not an array all
+ * read as empty rather than throwing. The blob accepts arbitrary JSON and the
+ * database cannot object, so the read path has to treat the shape as a claim.
+ */
+async function readArray(store, userId, property) {
+    const record = await store.get(userId, property);
+    const raw = record?.info?.entries;
+    return {
+        entries: Array.isArray(raw) ? raw : [],
+        revision: record?.revision,
+        record: record ?? null,
+    };
+}
+/**
+ * Write the whole array back, quoting the revision the caller read.
+ *
+ * Throws cap-services' `StaleEntityError` when the stored revision has moved
+ * on. Use `isStaleWriteError` to recognise it; see this module's header for why
+ * that is not caught here.
+ */
+async function writeArray(store, userId, property, entries, snapshot, options = {}) {
+    return store.put(userId, property, { entries }, { ...options, expectedRevision: snapshot.revision });
+}
+//# sourceMappingURL=property-array.js.map

package/dist/property-array.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-array.js","sourceRoot":"","sources":["../src/property-array.ts"],"names":[],"mappings":";;AAiDA,8BAYC;AASD,gCAcC;AA1CD;;;;;;GAMG;AACI,KAAK,UAAU,SAAS,CAC7B,KAAoB,EACpB,MAAc,EACd,QAAgB;IAEhB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAwB,MAAM,EAAE,QAAQ,CAAC,CAAC;IACxE,MAAM,GAAG,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC;IAClC,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,GAAW,CAAC,CAAC,CAAC,EAAE;QAC/C,QAAQ,EAAE,MAAM,EAAE,QAAQ;QAC1B,MAAM,EAAE,MAAM,IAAI,IAAI;KACvB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,UAAU,CAC9B,KAAoB,EACpB,MAAc,EACd,QAAgB,EAChB,OAAY,EACZ,QAA4C,EAC5C,UAA0D,EAAE;IAE5D,OAAO,KAAK,CAAC,GAAG,CACd,MAAM,EACN,QAAQ,EACR,EAAE,OAAO,EAAE,EACX,EAAE,GAAG,OAAO,EAAE,gBAAgB,EAAE,QAAQ,CAAC,QAAQ,EAAE,CACpD,CAAC;AACJ,CAAC"}

package/dist/public-id.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The client's `publicId` — the token prefix, in every registration mode.
+ *
+ * Plan, Decision 3: twelve lowercase base36 characters that *we* assign at
+ * registration. It is never the raw `client_id`, because a Client ID Metadata
+ * Document client's `client_id` is a URL containing `/`, `:` and `.`, and all
+ * three of those break something:
+ *
+ *   - `<publicId>.<generateToken()>` is the token wire format, split on the
+ *     first `.`;
+ *   - `<publicId>|<sha256>` is the `user_identities.key`, split on the `|` and
+ *     bounded by that column's `varchar(255)`;
+ *   - `key LIKE '<publicId>|%'` is the prefix scan client-wide revocation
+ *     depends on, which an unbounded URL would make meaningless.
+ *
+ * So the alphabet is the load-bearing part, not the length. Twelve base36
+ * characters is about 62 bits, which is ample for an identifier that is not
+ * itself a secret; the token half carries the entropy that matters.
+ *
+ * This is deliberately *not* `generatePublicId()` from `@boopkit/cap-database`.
+ * The house format (Crockford base32, `xxxxxx-xxxxxx`) would in fact survive
+ * both splits, but it is a 13-character value with a hyphen, and Decision 3
+ * fixed a 12-character `varchar(16)` column against the base36 alphabet. Taking
+ * the dependency to get a different-shaped value than the schema declares would
+ * trade one small module for a mismatch the schema cannot express.
+ */
+/** Lowercase base36. No `.`, no `|`, no `/`, no `:` — see the header. */
+export declare const CLIENT_PUBLIC_ID_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+/** Twelve characters, per Decision 3. The `varchar(16)` column allows headroom. */
+export declare const CLIENT_PUBLIC_ID_LENGTH = 12;
+/** A fresh client `publicId`. Uniqueness is enforced by the column, not here. */
+export declare function generateClientPublicId(): string;
+/** Is this a well-formed client `publicId`? */
+export declare function isValidClientPublicId(value: string): boolean;
+//# sourceMappingURL=public-id.d.ts.map

package/dist/public-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-id.d.ts","sourceRoot":"","sources":["../src/public-id.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,yCAAyC,CAAC;AAEhF,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAiC1C,iFAAiF;AACjF,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED,+CAA+C;AAC/C,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAK5D"}

package/dist/public-id.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIENT_PUBLIC_ID_LENGTH = exports.CLIENT_PUBLIC_ID_ALPHABET = void 0;
+exports.generateClientPublicId = generateClientPublicId;
+exports.isValidClientPublicId = isValidClientPublicId;
+const node_crypto_1 = require("node:crypto");
+/**
+ * The client's `publicId` — the token prefix, in every registration mode.
+ *
+ * Plan, Decision 3: twelve lowercase base36 characters that *we* assign at
+ * registration. It is never the raw `client_id`, because a Client ID Metadata
+ * Document client's `client_id` is a URL containing `/`, `:` and `.`, and all
+ * three of those break something:
+ *
+ *   - `<publicId>.<generateToken()>` is the token wire format, split on the
+ *     first `.`;
+ *   - `<publicId>|<sha256>` is the `user_identities.key`, split on the `|` and
+ *     bounded by that column's `varchar(255)`;
+ *   - `key LIKE '<publicId>|%'` is the prefix scan client-wide revocation
+ *     depends on, which an unbounded URL would make meaningless.
+ *
+ * So the alphabet is the load-bearing part, not the length. Twelve base36
+ * characters is about 62 bits, which is ample for an identifier that is not
+ * itself a secret; the token half carries the entropy that matters.
+ *
+ * This is deliberately *not* `generatePublicId()` from `@boopkit/cap-database`.
+ * The house format (Crockford base32, `xxxxxx-xxxxxx`) would in fact survive
+ * both splits, but it is a 13-character value with a hyphen, and Decision 3
+ * fixed a 12-character `varchar(16)` column against the base36 alphabet. Taking
+ * the dependency to get a different-shaped value than the schema declares would
+ * trade one small module for a mismatch the schema cannot express.
+ */
+/** Lowercase base36. No `.`, no `|`, no `/`, no `:` — see the header. */
+exports.CLIENT_PUBLIC_ID_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+/** Twelve characters, per Decision 3. The `varchar(16)` column allows headroom. */
+exports.CLIENT_PUBLIC_ID_LENGTH = 12;
+/**
+ * Draw `length` characters uniformly from the alphabet.
+ *
+ * Rejection sampling rather than `% alphabet.length`: 256 is not a multiple of
+ * 36, so the naive modulo would make the first four symbols about 14% more
+ * likely than the rest. That is not a break here — a `publicId` is an
+ * identifier rather than a secret — but the same generator shape gets copied
+ * onto things that are, and a biased draw is invisible in every test that does
+ * not go looking for it.
+ *
+ * `Math.random()` is not used anywhere in this package; it is on the umbrella
+ * spec's donor-defect list for exactly this family of function.
+ */
+function draw(length) {
+    const alphabet = exports.CLIENT_PUBLIC_ID_ALPHABET;
+    const limit = Math.floor(256 / alphabet.length) * alphabet.length;
+    const out = [];
+    while (out.length < length) {
+        // Over-read so the common case needs one syscall, not `length` of them.
+        const bytes = (0, node_crypto_1.randomBytes)((length - out.length) * 2);
+        for (const byte of bytes) {
+            if (byte >= limit)
+                continue;
+            out.push(alphabet[byte % alphabet.length]);
+            if (out.length === length)
+                break;
+        }
+    }
+    return out.join('');
+}
+/** A fresh client `publicId`. Uniqueness is enforced by the column, not here. */
+function generateClientPublicId() {
+    return draw(exports.CLIENT_PUBLIC_ID_LENGTH);
+}
+/** Is this a well-formed client `publicId`? */
+function isValidClientPublicId(value) {
+    return (value.length === exports.CLIENT_PUBLIC_ID_LENGTH &&
+        [...value].every((ch) => exports.CLIENT_PUBLIC_ID_ALPHABET.includes(ch)));
+}
+//# sourceMappingURL=public-id.js.map

package/dist/public-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-id.js","sourceRoot":"","sources":["../src/public-id.ts"],"names":[],"mappings":";;;AAmEA,wDAEC;AAGD,sDAKC;AA7ED,6CAA0C;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,yEAAyE;AAC5D,QAAA,yBAAyB,GAAG,sCAAsC,CAAC;AAEhF,mFAAmF;AACtE,QAAA,uBAAuB,GAAG,EAAE,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,SAAS,IAAI,CAAC,MAAc;IAC1B,MAAM,QAAQ,GAAG,iCAAyB,CAAC;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;IAClE,MAAM,GAAG,GAAa,EAAE,CAAC;IAEzB,OAAO,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;QAC3B,wEAAwE;QACxE,MAAM,KAAK,GAAG,IAAA,yBAAW,EAAC,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACrD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,IAAI,KAAK;gBAAE,SAAS;YAC5B,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YAC3C,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM;gBAAE,MAAM;QACnC,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC;AAED,iFAAiF;AACjF,SAAgB,sBAAsB;IACpC,OAAO,IAAI,CAAC,+BAAuB,CAAC,CAAC;AACvC,CAAC;AAED,+CAA+C;AAC/C,SAAgB,qBAAqB,CAAC,KAAa;IACjD,OAAO,CACL,KAAK,CAAC,MAAM,KAAK,+BAAuB;QACxC,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,iCAAyB,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CACjE,CAAC;AACJ,CAAC"}

package/dist/rate-limit.d.ts

@@ -0,0 +1,56 @@
+import type { RequestHandler } from 'express';
+/**
+ * Per-IP rate limiting for the one endpoint that lets a stranger write a row.
+ *
+ * `POST /oauth/register` is unauthenticated by design — RFC 7591 open
+ * registration has no caller to authenticate — so there is no account to hang a
+ * quota on and the source address is the only thing a limiter has to go on.
+ * Neither donor has anything like this: paywalls' registration endpoint
+ * required an authenticated `service-user`, which is a gate this endpoint
+ * cannot have.
+ *
+ * ## What this is, and what it is not
+ *
+ * A fixed-window counter in process memory. That means:
+ *
+ *   - it resets when the process restarts, and
+ *   - each instance of a horizontally-scaled app counts separately.
+ *
+ * Both are acceptable for what it defends. The row ceiling in the registry
+ * (`maxRegisteredClients`) is the hard bound on damage; this limiter exists to
+ * make reaching that ceiling slow and noisy rather than instant. An app that
+ * wants a shared limiter across instances should mount its own in front of the
+ * handler — the router factory takes one — rather than have this one grow a
+ * Redis dependency the capability would then require of everybody.
+ *
+ * A fixed window also lets a caller send `2 × limit` requests across a window
+ * boundary. Named here rather than fixed, because the mitigation (a sliding
+ * window) buys precision this does not need against a ceiling that is already
+ * the real bound.
+ */
+export interface RateLimiterOptions {
+    /** Requests allowed per window, per address. */
+    limit?: number;
+    /** Window length in milliseconds. */
+    windowMs?: number;
+    /** Injectable clock, so the window can be tested without waiting for it. */
+    now?: () => number;
+    /**
+     * How many distinct addresses to track before the oldest window is dropped.
+     * Bounds the memory an attacker can make this hold.
+     */
+    maxTrackedAddresses?: number;
+}
+export declare const DEFAULT_REGISTRATION_RATE_LIMIT = 10;
+export declare const DEFAULT_REGISTRATION_RATE_WINDOW_MS: number;
+export interface RegistrationRateLimiter {
+    middleware: RequestHandler;
+    /** Exposed for tests and for an operator script; not part of the route. */
+    check(address: string): {
+        allowed: boolean;
+        retryAfterSeconds: number;
+    };
+    reset(): void;
+}
+export declare function createRegistrationRateLimiter(options?: RateLimiterOptions): RegistrationRateLimiter;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAClD,eAAO,MAAM,mCAAmC,QAAiB,CAAC;AAQlE,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,cAAc,CAAC;IAC3B,2EAA2E;IAC3E,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,kBAAuB,GAC/B,uBAAuB,CAmDzB"}

package/dist/rate-limit.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REGISTRATION_RATE_WINDOW_MS = exports.DEFAULT_REGISTRATION_RATE_LIMIT = void 0;
+exports.createRegistrationRateLimiter = createRegistrationRateLimiter;
+exports.DEFAULT_REGISTRATION_RATE_LIMIT = 10;
+exports.DEFAULT_REGISTRATION_RATE_WINDOW_MS = 60 * 60 * 1000;
+const DEFAULT_MAX_TRACKED_ADDRESSES = 10000;
+function createRegistrationRateLimiter(options = {}) {
+    const limit = options.limit ?? exports.DEFAULT_REGISTRATION_RATE_LIMIT;
+    const windowMs = options.windowMs ?? exports.DEFAULT_REGISTRATION_RATE_WINDOW_MS;
+    const now = options.now ?? (() => Date.now());
+    const maxTracked = options.maxTrackedAddresses ?? DEFAULT_MAX_TRACKED_ADDRESSES;
+    const windows = new Map();
+    function check(address) {
+        const at = now();
+        const existing = windows.get(address);
+        if (!existing || existing.resetAt <= at) {
+            // Map insertion order is insertion order, so the first key is the least
+            // recently *started* window — good enough for an eviction whose only job
+            // is to bound memory.
+            if (windows.size >= maxTracked) {
+                const oldest = windows.keys().next();
+                if (!oldest.done)
+                    windows.delete(oldest.value);
+            }
+            windows.set(address, { count: 1, resetAt: at + windowMs });
+            return { allowed: true, retryAfterSeconds: 0 };
+        }
+        existing.count += 1;
+        if (existing.count > limit) {
+            return {
+                allowed: false,
+                retryAfterSeconds: Math.max(1, Math.ceil((existing.resetAt - at) / 1000)),
+            };
+        }
+        return { allowed: true, retryAfterSeconds: 0 };
+    }
+    const middleware = (req, res, next) => {
+        const address = req.ip ?? req.socket?.remoteAddress ?? 'unknown';
+        const verdict = check(address);
+        if (verdict.allowed)
+            return next();
+        res.setHeader('Retry-After', String(verdict.retryAfterSeconds));
+        res.status(429).json({
+            error: 'temporarily_unavailable',
+            error_description: 'too many registration requests from this address; try again later',
+        });
+    };
+    return {
+        middleware,
+        check,
+        reset: () => windows.clear(),
+    };
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":";;;AA8DA,sEAqDC;AArEY,QAAA,+BAA+B,GAAG,EAAE,CAAC;AACrC,QAAA,mCAAmC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAClE,MAAM,6BAA6B,GAAG,KAAM,CAAC;AAc7C,SAAgB,6BAA6B,CAC3C,UAA8B,EAAE;IAEhC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,uCAA+B,CAAC;IAC/D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,2CAAmC,CAAC;IACzE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,OAAO,CAAC,mBAAmB,IAAI,6BAA6B,CAAC;IAEhF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1C,SAAS,KAAK,CAAC,OAAe;QAC5B,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC;QACjB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAEtC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;YACxC,wEAAwE;YACxE,yEAAyE;YACzE,sBAAsB;YACtB,IAAI,OAAO,CAAC,IAAI,IAAI,UAAU,EAAE,CAAC;gBAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;gBACrC,IAAI,CAAC,MAAM,CAAC,IAAI;oBAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACjD,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;YAC3D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,EAAE,CAAC;QACjD,CAAC;QAED,QAAQ,CAAC,KAAK,IAAI,CAAC,CAAC;QACpB,IAAI,QAAQ,CAAC,KAAK,GAAG,KAAK,EAAE,CAAC;YAC3B,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,iBAAiB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;aAC1E,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,EAAE,CAAC;IACjD,CAAC;IAED,MAAM,UAAU,GAAmB,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QACrF,MAAM,OAAO,GAAG,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,MAAM,EAAE,aAAa,IAAI,SAAS,CAAC;QACjE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QAC/B,IAAI,OAAO,CAAC,OAAO;YAAE,OAAO,IAAI,EAAE,CAAC;QAEnC,GAAG,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;QAChE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACnB,KAAK,EAAE,yBAAyB;YAChC,iBAAiB,EAAE,mEAAmE;SACvF,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO;QACL,UAAU;QACV,KAAK;QACL,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE;KAC7B,CAAC;AACJ,CAAC"}

package/dist/redirect-uri.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Redirect-URI policy: what may be registered, and what a registered entry
+ * accepts at the authorization endpoint.
+ *
+ * Both questions are answered from one classifier, `classifyRedirectUri`,
+ * because the two halves only work as a pair. A shape registration stores but
+ * the matcher will not parse is worse than a shape neither accepts: the client
+ * registers, believes it is connected, and then fails at the authorization
+ * endpoint with `redirect_uri is not registered`. Keeping the rule in one
+ * function is what makes that disagreement impossible rather than unlikely.
+ *
+ * ## The three shapes
+ *
+ * RFC 8252 (OAuth 2.0 for Native Apps) names exactly three ways a client may be
+ * called back, and this server accepts those three and nothing else:
+ *
+ *   `https`          an absolute https URL — §7.2, the claimed-https redirect
+ *                    a hosted connector such as Claude's web app uses.
+ *   `loopback-http`  `http` on `localhost` or `127.0.0.1` — §7.3, because a
+ *                    native app cannot terminate TLS on the loopback interface.
+ *   `private-use`    a hierarchical URI in an application's own scheme, such as
+ *                    `com.example.app:/oauth2redirect/cb` or
+ *                    `claude://oauth/callback` — §7.1, how a desktop or mobile
+ *                    app is handed the response by its operating system.
+ *
+ * ## The matching rule
+ *
+ * **Exact string match**, with exactly one exception: a registered
+ * `loopback-http` entry matches a presented URI that differs only in port. That
+ * is RFC 8252 §7.3, and it is what Claude Code's published Client ID Metadata
+ * Document requires — it binds an ephemeral loopback port at connect time, so
+ * the port it will present is not knowable at registration.
+ *
+ * The exception is scoped to `loopback-http` and not merely to a loopback
+ * *host*. A private-use scheme has no TCP port to be ephemeral: the operating
+ * system routes it by scheme name, so `myapp://localhost/cb` gets the plain
+ * exact rule even though its host happens to read as loopback.
+ *
+ * The exception lives here, in one function with its own test table, rather
+ * than being threaded through the authorization controller as a special case.
+ * A redirect-URI check that is spread across a controller is how the umbrella
+ * spec's "declared-but-unenforced redirect URI lists" defect happens: the list
+ * is stored, the comparison drifts, and nothing says so.
+ *
+ * Nothing here reads a database or a request. It compares two strings.
+ */
+/** Which of the three accepted shapes a redirect URI is. */
+export type RedirectUriShape = 'https' | 'loopback-http' | 'private-use';
+/**
+ * The verdict on one redirect URI.
+ *
+ * `reason` is a sentence fragment completing "this entry …", so a caller can
+ * prefix it with whatever names the offending value — the client registry says
+ * `redirect_uris entry ${reason}: ${entry}`.
+ */
+export type RedirectUriClassification = {
+    accepted: true;
+    shape: RedirectUriShape;
+    url: URL;
+} | {
+    accepted: false;
+    reason: string;
+};
+/**
+ * Classify one redirect URI, or say why it is refused.
+ *
+ * The single source of the policy. `validateRedirectUris` in the client
+ * registry calls it to decide whether a URI may be **stored**; `matchRedirectUri`
+ * below calls it to decide whether a stored or presented URI may be
+ * **compared**.
+ */
+export declare function classifyRedirectUri(value: string): RedirectUriClassification;
+/**
+ * Does `presented` satisfy the registered entry `registered`?
+ *
+ * @param registered one entry from the client's `redirect_uris`
+ * @param presented  the `redirect_uri` the authorization request carried
+ */
+export declare function matchRedirectUri(registered: string, presented: string): boolean;
+/**
+ * Does any registered entry accept the presented URI?
+ *
+ * The authorization controller's actual question, kept next to the rule it is
+ * built from so a caller never has to write the loop itself.
+ */
+export declare function matchesAnyRedirectUri(registered: readonly string[], presented: string): boolean;
+/** Is this host one the loopback exception applies to? */
+export declare function isLoopbackHost(host: string): boolean;
+//# sourceMappingURL=redirect-uri.d.ts.map

package/dist/redirect-uri.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect-uri.d.ts","sourceRoot":"","sources":["../src/redirect-uri.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAsDH,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,eAAe,GAAG,aAAa,CAAC;AAEzE;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE,GACrD;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA6BxC;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,yBAAyB,CAsC5E;AAiBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CA+C/E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAE/F;AAED,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD"}