@vantageos/mcp-boilerplate 0.2.4 → 0.4.0

package/dist/oauth/authorizationServer.js

@@ -20,20 +20,24 @@
  * FAIL-CLOSED: any missing configuration value answers 503 `temporarily_unavailable`.
  * No refresh tokens are issued; access tokens live one hour.
  */
-import { buildDiscoveryDocument, buildUserInfo, exchangeAuthorizationCode, oauthErrorFor, resumeAuthorize, startAuthorize, resolveClerkSessionFromRequest, } from "@vantageos/cloud-identity";
+import { buildDiscoveryDocument, buildUserInfo, exchangeAuthorizationCode, oauthErrorFor, resolveClerkSessionFromRequest, resumeAuthorize, startAuthorize, } from "@vantageos/cloud-identity";
 import { getCookie } from "hono/cookie";
 import { cors } from "hono/cors";
 import { flagKnob, integerKnob, originListKnob } from "../envKnobs.js";
-import { detectLocaleFromAcceptLanguage, t } from "../i18n.js";
+import { detectLocale, detectLocaleFromAcceptLanguage, t } from "../i18n.js";
 import { createClerkBackendCollaborators } from "./clerk.js";
 import { ASSERTION_SIGNING_ALGS, createClientAssertionVerifier } from "./clientAssertion.js";
-import { createInMemoryClientRegistry, isAllowedRedirectUri, isUrlShapedClientId, resolveCimdClient, } from "./clientRegistry.js";
+import { RegistryFullError, createInMemoryClientRegistry, isAllowedRedirectUri, isUrlShapedClientId, resolveCimdClient, } from "./clientRegistry.js";
 import { createInMemoryCodeStore } from "./codeStore.js";
 import { pickerContentSecurityPolicy, renderOrgPicker } from "./picker.js";
+import { createRegisterLimiter } from "./registerLimiter.js";
 import { DEFAULT_SCOPE, OAUTH_ENV, SUPPORTED_SCOPES, isDevClerkInstanceOnRemoteServer, readAuthorizeSettings, } from "./settings.js";
 import { ACCESS_TOKEN_TTL_SECONDS, createTokenIssuer } from "./tokenIssuer.js";
 const REGISTER_LIMIT_PER_MINUTE = 20;
+/** Default of OAUTH_ENV.registerLimitPer48: five /64 budgets for a whole /48. */
+const REGISTER_LIMIT_PER_48_PER_MINUTE = 100;
 const MAX_REDIRECT_URIS = 10;
+const REGISTRY_FULL_RETRY_AFTER_SECONDS = 300;
 function noStore(c) {
     c.header("Cache-Control", "no-store");
     c.header("Pragma", "no-cache");
@@ -84,11 +88,16 @@ export function createAuthorizationServer(deps = {}) {
     const env = deps.env ?? process.env;
     // Operator knobs are validated here, at construction: a bad value stops the boot.
     const trustedProxyCount = integerKnob(env, OAUTH_ENV.trustedProxyCount, 0, 10) ?? 0;
+    const registerLimitPer48 = integerKnob(env, OAUTH_ENV.registerLimitPer48, 1) ?? REGISTER_LIMIT_PER_48_PER_MINUTE;
     const registerOrigins = originListKnob(env, OAUTH_ENV.registerCorsOrigins);
     const allowInMemory = flagKnob(env, OAUTH_ENV.allowInMemoryStores) === true;
     const now = deps.now ?? (() => Date.now());
     // Fail at boot, loudly, rather than lose every code and client on the first restart.
     if (!deps.codeStore || !deps.clientRegistry) {
+        if (env.NODE_ENV !== "production" && !allowInMemory) {
+            // Development, test or unset: start, but never silently. One line, both languages.
+            console.warn(`[oauth] ${t("en", "oauth.inMemoryWarning").replace("{knob}", OAUTH_ENV.allowInMemoryStores)} / ${t("fr", "oauth.inMemoryWarning").replace("{knob}", OAUTH_ENV.allowInMemoryStores)}`);
+        }
         if (env.NODE_ENV === "production") {
             if (!allowInMemory) {
                 throw new Error(`NODE_ENV=production refuses the in-memory OAuth stores (codes and registered clients are lost on restart and not shared between instances). Inject durable adapters (docs/oauth-stores.md), or set ${OAUTH_ENV.allowInMemoryStores}=1 to accept a single-instance deployment that forgets them on restart.`);
@@ -177,6 +186,18 @@ export function createAuthorizationServer(deps = {}) {
             error_description: t("en", "oauth.unavailable"),
         }, 503);
     };
+    /**
+     * The redirect URI(s) the picker's form may end up at. cloud-identity hands the page only the
+     * ORIGIN of the validated redirect_uri: for http(s) that is the destination itself; for a
+     * custom scheme the origin is the opaque "null", so the scheme is read from the client's
+     * registered URIs of that scheme (the validated one is among them).
+     */
+    const redirectTargetsOf = async (model) => {
+        if (/^https?:\/\//.test(model.redirectOrigin))
+            return [model.redirectOrigin];
+        const client = await lookupClient(model.client.clientId);
+        return (client?.redirectUris ?? []).filter((u) => !/^https?:/i.test(u));
+    };
     const respond = async (c, outcome, settings) => {
         noStore(c);
         c.header("Referrer-Policy", "no-referrer");
@@ -190,7 +211,16 @@ export function createAuthorizationServer(deps = {}) {
                 return c.redirect(back.toString(), 302);
             }
             case "org-picker": {
-                c.header("Content-Security-Policy", await pickerContentSecurityPolicy());
+                let csp;
+                try {
+                    csp = await pickerContentSecurityPolicy(await redirectTargetsOf(outcome.model));
+                }
+                catch (err) {
+                    // Fail closed: without a parseable destination the page is not rendered at all.
+                    console.error("[oauth] picker refused:", err instanceof Error ? err.message : err);
+                    return c.json({ error: "server_error", error_description: "picker unavailable" }, 500);
+                }
+                c.header("Content-Security-Policy", csp);
                 const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
                 return c.html(renderOrgPicker(outcome.model, locale, {
                     // Only a URL-shaped (CIMD) client_id is bound to a domain its owner controls.
@@ -204,19 +234,11 @@ export function createAuthorizationServer(deps = {}) {
             }
         }
     };
-    const registerHits = new Map();
-    const registerAllowed = (key) => {
-        const t0 = now();
-        const hit = registerHits.get(key);
-        if (!hit || t0 - hit.windowStart >= 60_000) {
-            registerHits.set(key, { windowStart: t0, count: 1 });
-            if (registerHits.size > 5000)
-                registerHits.clear();
-            return true;
-        }
-        hit.count += 1;
-        return hit.count <= REGISTER_LIMIT_PER_MINUTE;
-    };
+    const registerLimiter = createRegisterLimiter({
+        limitPerMinute: REGISTER_LIMIT_PER_MINUTE,
+        prefix48LimitPerMinute: registerLimitPer48,
+        now,
+    });
     return {
         async resourceServer() {
             const result = await settingsNow();
@@ -282,7 +304,7 @@ export function createAuthorizationServer(deps = {}) {
             });
             app.post("/register", async (c) => {
                 const key = clientKeyOf(c, trustedProxyCount);
-                if (!registerAllowed(key)) {
+                if (!registerLimiter.allow(key)) {
                     c.header("Retry-After", "60");
                     return c.json({ error: "too_many_requests" }, 429);
                 }
@@ -326,6 +348,19 @@ export function createAuthorizationServer(deps = {}) {
                     });
                 }
                 catch (err) {
+                    if (err instanceof RegistryFullError) {
+                        // RFC 7591 style JSON error; the caller retries, no live client was displaced.
+                        const locale = c.req.header("x-mcp-locale")
+                            ? detectLocale(c.req.header("x-mcp-locale"))
+                            : detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
+                        console.error("[oauth] /register refused: client registry is full");
+                        c.header("Retry-After", String(REGISTRY_FULL_RETRY_AFTER_SECONDS));
+                        noStore(c);
+                        return c.json({
+                            error: "temporarily_unavailable",
+                            error_description: t(locale, "oauth.registryFull"),
+                        }, 503);
+                    }
                     console.error("[oauth] /register failed:", err instanceof Error ? err.message : err);
                     return c.json({ error: "server_error", error_description: "failed to persist client" }, 500);
                 }
@@ -409,6 +444,16 @@ export function createAuthorizationServer(deps = {}) {
                 // session, then answers the redirect-to-client with error=access_denied and the
                 // client's state. `respond` appends `iss` to it like to every authorization response.
                 if (field("approved") === "false") {
+                    // The denial is a state-changing POST like the approval. An absent token is
+                    // refused here with a localized 400; a present one is verified by the package
+                    // (cloud-identity >= 0.18) with the approve-path function, and a forged one is
+                    // refused with no redirect.
+                    if (!field("consentToken")) {
+                        return c.json({
+                            error: "invalid_request",
+                            error_description: t(detectLocaleFromAcceptLanguage(c.req.header("accept-language")), "oauth.consentTokenRequired"),
+                        }, 400);
+                    }
                     const denied = await resumeAuthorize({
                         state: field("state") ?? "",
                         sessionToken: sessionTokenFrom(c),

package/dist/oauth/clerk.d.ts

@@ -15,5 +15,7 @@ export interface ClerkCollaborators {
 export interface ClerkBackendOptions {
     /** Per-call time budget (JWKS, memberships, user). Default 5 s. */
     timeoutMs?: number;
+    /** Total budget of ONE lookup across all its pages and calls. Default 15 s. */
+    totalTimeoutMs?: number;
 }
 export declare function createClerkBackendCollaborators(secretKey: string, fetchImpl?: typeof fetch, options?: ClerkBackendOptions): ClerkCollaborators;

package/dist/oauth/clerk.js

@@ -12,13 +12,22 @@ const MEMBERSHIP_PAGE_LIMIT = 100;
 /** 50 pages x 100 = 5 000 memberships: past it the lookup FAILS rather than truncate. */
 const MEMBERSHIP_MAX_PAGES = 50;
 const CLERK_TIMEOUT_MS = 5000;
+const CLERK_TOTAL_TIMEOUT_MS = 15_000;
 export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch, options = {}) {
     const timeoutMs = options.timeoutMs ?? CLERK_TIMEOUT_MS;
     let cachedJwks = null;
-    const api = async (path) => {
+    const totalMs = options.totalTimeoutMs ?? CLERK_TOTAL_TIMEOUT_MS;
+    /** Per-call timeout AND what is left of the lookup's total deadline, whichever is sooner. */
+    const signalFor = (deadline) => {
+        const left = deadline - Date.now();
+        if (left <= 0)
+            throw new Error(`Clerk lookup exceeded its total deadline of ${totalMs} ms`);
+        return AbortSignal.any([AbortSignal.timeout(timeoutMs), AbortSignal.timeout(left)]);
+    };
+    const api = async (path, deadline) => {
         const res = await fetchImpl(`${CLERK_API}${path}`, {
             headers: { Authorization: `Bearer ${secretKey}`, Accept: "application/json" },
-            signal: AbortSignal.timeout(timeoutMs),
+            signal: signalFor(deadline),
         });
         if (!res.ok)
             throw new Error(`Clerk Backend API answered ${res.status}`);
@@ -31,7 +40,7 @@ export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch, op
                 return cachedJwks.keys;
             }
             const res = await fetchImpl(`${issuer}/.well-known/jwks.json`, {
-                signal: AbortSignal.timeout(timeoutMs),
+                signal: signalFor(now + totalMs),
             });
             if (!res.ok)
                 throw new Error(`Clerk JWKS answered ${res.status}`);
@@ -41,9 +50,10 @@ export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch, op
         },
         async listMemberships(userId) {
             const all = [];
+            const deadline = Date.now() + totalMs;
             for (let page = 0; page < MEMBERSHIP_MAX_PAGES; page++) {
                 const offset = page * MEMBERSHIP_PAGE_LIMIT;
-                const body = await api(`/users/${encodeURIComponent(userId)}/organization_memberships?limit=${MEMBERSHIP_PAGE_LIMIT}&offset=${offset}`);
+                const body = await api(`/users/${encodeURIComponent(userId)}/organization_memberships?limit=${MEMBERSHIP_PAGE_LIMIT}&offset=${offset}`, deadline);
                 all.push(...body.data);
                 const last = body.data.length < MEMBERSHIP_PAGE_LIMIT ||
                     (typeof body.total_count === "number" && all.length >= body.total_count);
@@ -62,7 +72,7 @@ export function createClerkBackendCollaborators(secretKey, fetchImpl = fetch, op
             throw new Error(`Clerk memberships exceed ${MEMBERSHIP_MAX_PAGES * MEMBERSHIP_PAGE_LIMIT}`);
         },
         async getUser(userId) {
-            const user = await api(`/users/${encodeURIComponent(userId)}`);
+            const user = await api(`/users/${encodeURIComponent(userId)}`, Date.now() + totalMs);
             return {
                 id: user.id,
                 primaryEmailAddressId: user.primary_email_address_id ?? null,

package/dist/oauth/clientRegistry.d.ts

@@ -25,20 +25,35 @@ export interface ClientRegistry {
     register(client: RegisteredClient): Promise<void>;
 }
 export interface InMemoryClientRegistryOptions {
-    /** Hard cap on stored clients; at the cap the OLDEST client is evicted. Default 10 000. */
+    /** Hard cap on stored clients; at the cap a new registration is REFUSED. Default 10 000. */
     maxClients?: number;
     /** Lifetime of a registration, counted from `issuedAt`. Default 30 days. */
     ttlSeconds?: number;
     now?: () => number;
 }
 /**
- * Bounded in-memory registry. DCR is unauthenticated, so it can never grow without limit and
- * never stops accepting registrations either: expired clients are swept on every registration,
- * and at the cap the oldest client is evicted (an evicted client re-registers).
+ * Thrown by `register` when the registry is full of live clients. The route answers 503 with
+ * `Retry-After`; a durable adapter may throw the same error for its own quota.
+ */
+export declare class RegistryFullError extends Error {
+    readonly code = "registry_full";
+    constructor();
+}
+/**
+ * Bounded in-memory registry. DCR is unauthenticated, so it can never grow without limit.
+ * Expired clients are pruned on every registration BEFORE the cap is judged; at the cap a new
+ * registration is refused with `RegistryFullError`. A live client is never evicted: an
+ * unauthenticated flood must not be able to push a real client out (eviction, introduced for
+ * issue #9, allowed exactly that).
  */
 export declare function createInMemoryClientRegistry(options?: InMemoryClientRegistryOptions): ClientRegistry;
 /** True for an https URL, or an http URL on a loopback host (native-app redirects). */
 export declare function isAllowedRedirectUri(raw: unknown): raw is string;
+/**
+ * The eight 16-bit groups of a SYNTACTICALLY VALID IPv6 literal (`isIP` has already accepted
+ * it). Only used to read bits that no BlockList prefix can express.
+ */
+export declare function ipv6Groups(ip: string): number[];
 /** True only for a globally routable address. Fail-closed: anything unrecognised is refused. */
 export declare function isPublicAddress(ip: string): boolean;
 export declare function defaultResolveHost(host: string): Promise<string[]>;

package/dist/oauth/clientRegistry.js

@@ -13,9 +13,22 @@
 import { lookup } from "node:dns/promises";
 import { BlockList, isIP } from "node:net";
 /**
- * Bounded in-memory registry. DCR is unauthenticated, so it can never grow without limit and
- * never stops accepting registrations either: expired clients are swept on every registration,
- * and at the cap the oldest client is evicted (an evicted client re-registers).
+ * Thrown by `register` when the registry is full of live clients. The route answers 503 with
+ * `Retry-After`; a durable adapter may throw the same error for its own quota.
+ */
+export class RegistryFullError extends Error {
+    code = "registry_full";
+    constructor() {
+        super("client registry is full");
+        this.name = "RegistryFullError";
+    }
+}
+/**
+ * Bounded in-memory registry. DCR is unauthenticated, so it can never grow without limit.
+ * Expired clients are pruned on every registration BEFORE the cap is judged; at the cap a new
+ * registration is refused with `RegistryFullError`. A live client is never evicted: an
+ * unauthenticated flood must not be able to push a real client out (eviction, introduced for
+ * issue #9, allowed exactly that).
  */
 export function createInMemoryClientRegistry(options = {}) {
     const maxClients = options.maxClients ?? 10_000;
@@ -38,12 +51,9 @@ export function createInMemoryClientRegistry(options = {}) {
             for (const [id, row] of clients)
                 if (expired(row))
                     clients.delete(id);
-            clients.delete(client.clientId); // re-registering moves it to the newest position
-            while (clients.size >= maxClients) {
-                const oldest = clients.keys().next();
-                if (oldest.done)
-                    break;
-                clients.delete(oldest.value);
+            // Re-registering an id already held replaces it: that is not a new slot.
+            if (!clients.has(client.clientId) && clients.size >= maxClients) {
+                throw new RegistryFullError();
             }
             clients.set(client.clientId, client);
         },
@@ -132,7 +142,7 @@ for (const [addr, len] of BLOCKED_V6)
  * The eight 16-bit groups of a SYNTACTICALLY VALID IPv6 literal (`isIP` has already accepted
  * it). Only used to read bits that no BlockList prefix can express.
  */
-function ipv6Groups(ip) {
+export function ipv6Groups(ip) {
     let text = ip.toLowerCase();
     const dotted = /(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(text);
     if (dotted) {

package/dist/oauth/picker.d.ts

@@ -6,8 +6,11 @@
  */
 import type { OrgPickerModel } from "@vantageos/cloud-identity";
 import { type McpLocale } from "../i18n.js";
-/** CSP for the picker page: no scripts, no external assets, one hashed inline style. */
-export declare function pickerContentSecurityPolicy(): Promise<string>;
+/**
+ * CSP for the picker page: no scripts, no external assets, one hashed inline style, and forms
+ * that post to this server and are redirected to the client's `redirect_uri` only.
+ */
+export declare function pickerContentSecurityPolicy(redirectUris: readonly string[]): Promise<string>;
 /** What the consent page must tell the person beyond the model: whether the client is trusted. */
 export interface ConsentContext {
     /** True for a Dynamic Client Registration client: it vouched for itself, nobody else did. */

package/dist/oauth/picker.js

@@ -61,14 +61,44 @@ const PICKER_STYLE = [
     "button.primary{background:var(--primary);color:var(--primary-foreground);border-color:var(--primary)}",
     "button:hover{opacity:.9}button:focus-visible,.org:focus-within{outline:2px solid var(--ring);outline-offset:2px}",
 ].join("");
-/** CSP for the picker page: no scripts, no external assets, one hashed inline style. */
-export async function pickerContentSecurityPolicy() {
+/**
+ * The `form-action` sources for the redirect URIs of THIS authorization. Chromium enforces
+ * `form-action` on the redirect that follows a form POST, and POST /authorize/org answers a
+ * 302 to the client's `redirect_uri` (always another origin), so that destination MUST be
+ * listed or the client never receives its code. Built from `new URL(...)`, never from raw
+ * input: an http(s) URI contributes its origin (loopback keeps its port), any other URI its
+ * scheme (`cursor:`). Fail closed: no URI, or one that does not parse, throws; the page is
+ * never rendered with `'self'` alone.
+ */
+function formActionSources(redirectUris) {
+    if (redirectUris.length === 0)
+        throw new Error("picker CSP: no redirect_uri to permit");
+    const sources = new Set();
+    for (const raw of redirectUris) {
+        let url;
+        try {
+            url = new URL(raw);
+        }
+        catch {
+            throw new Error("picker CSP: redirect_uri does not parse");
+        }
+        sources.add(url.protocol === "https:" || url.protocol === "http:" ? url.origin : url.protocol);
+    }
+    return [...sources];
+}
+/**
+ * CSP for the picker page: no scripts, no external assets, one hashed inline style, and forms
+ * that post to this server and are redirected to the client's `redirect_uri` only.
+ */
+export async function pickerContentSecurityPolicy(redirectUris) {
+    const formAction = ["'self'", ...formActionSources(redirectUris)].join(" ");
     const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(PICKER_STYLE));
     const hash = btoa(String.fromCharCode(...new Uint8Array(digest)));
     return [
         "default-src 'none'",
         `style-src 'sha256-${hash}'`,
         "base-uri 'none'",
+        `form-action ${formAction}`,
         "frame-ancestors 'none'",
     ].join("; ");
 }
@@ -82,8 +112,8 @@ export function renderOrgPicker(model, locale, consent) {
     const orgs = model.organizations
         .map((o, i) => `<label class="org"><input type="radio" name="orgId" value="${escapeHtml(o.id)}" required${only && i === 0 ? " checked" : ""}><span class="name">${escapeHtml(o.name)}</span><span class="role">${escapeHtml(o.role.replace(/^org:/, ""))}</span></label>`)
         .join("\n");
-    const title = escapeHtml(t(locale, "oauth.pickerTitle").replace("{client}", clientName));
-    const intro = escapeHtml(t(locale, "oauth.pickerIntro").replaceAll("{client}", clientName));
+    const title = escapeHtml(t(locale, "oauth.pickerTitle").replace("{client}", () => clientName));
+    const intro = escapeHtml(t(locale, "oauth.pickerIntro").replaceAll("{client}", () => clientName));
     const brand = consent.brandName ? `<p class="brand">${escapeHtml(consent.brandName)}</p>\n` : "";
     return `<!doctype html>
 <html lang="${locale}">

package/dist/oauth/registerLimiter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Rate limiter of the unauthenticated `POST /register`.
+ *
+ * Keys are NORMALISED so one host cannot multiply its budget: an IPv6 client is keyed on its
+ * /64 prefix (a host owns a whole /64, so per-address keys are free), an IPv4-mapped IPv6
+ * address is keyed as the IPv4 address it carries, IPv4 keeps the full address. Parsing is
+ * `node:net`'s (`isIP`) plus the group reader the SSRF guard already uses.
+ *
+ * A /48 holds 65536 /64s, each with its own budget, so an IPv6 client is ALSO counted against
+ * its /48 when a `/48` budget is configured: a request passes only while both its /64 and its
+ * /48 are under their limits. A request already refused by its /64 is not charged to the /48. IPv4 and IPv4-mapped addresses have no /48 and are unaffected.
+ *
+ * Memory is bounded without ever handing an attacker a reset. When the table is full the
+ * least-recently-used key is evicted, but keys still inside a window and not yet limited go
+ * first: a key that already hit the limit is the last thing dropped, so a flood of fresh keys
+ * cannot wipe a counter that is doing its job. (A bare `clear()` did exactly that.)
+ */
+/** The counter key of a client address. A value that is not an IP literal is returned as is. */
+export declare function normaliseClientKey(address: string): string;
+/** The /48 aggregate key of a native IPv6 address, or null for IPv4, IPv4-mapped or non-IP. */
+export declare function prefix48Key(address: string): string | null;
+export interface RegisterLimiter {
+    /** Counts one request for `address`; false when it is over the limit for the window. */
+    allow(address: string): boolean;
+    /** Keys currently tracked (tests and diagnostics). */
+    size(): number;
+}
+export declare function createRegisterLimiter(options: {
+    limitPerMinute: number;
+    /** Aggregate budget of every /64 inside one IPv6 /48; absent means no /48 budget. */
+    prefix48LimitPerMinute?: number;
+    maxKeys?: number;
+    now: () => number;
+}): RegisterLimiter;

package/dist/oauth/registerLimiter.js

@@ -0,0 +1,95 @@
+/**
+ * Rate limiter of the unauthenticated `POST /register`.
+ *
+ * Keys are NORMALISED so one host cannot multiply its budget: an IPv6 client is keyed on its
+ * /64 prefix (a host owns a whole /64, so per-address keys are free), an IPv4-mapped IPv6
+ * address is keyed as the IPv4 address it carries, IPv4 keeps the full address. Parsing is
+ * `node:net`'s (`isIP`) plus the group reader the SSRF guard already uses.
+ *
+ * A /48 holds 65536 /64s, each with its own budget, so an IPv6 client is ALSO counted against
+ * its /48 when a `/48` budget is configured: a request passes only while both its /64 and its
+ * /48 are under their limits. A request already refused by its /64 is not charged to the /48. IPv4 and IPv4-mapped addresses have no /48 and are unaffected.
+ *
+ * Memory is bounded without ever handing an attacker a reset. When the table is full the
+ * least-recently-used key is evicted, but keys still inside a window and not yet limited go
+ * first: a key that already hit the limit is the last thing dropped, so a flood of fresh keys
+ * cannot wipe a counter that is doing its job. (A bare `clear()` did exactly that.)
+ */
+import { isIP } from "node:net";
+import { ipv6Groups } from "./clientRegistry.js";
+const WINDOW_MS = 60_000;
+/** The counter key of a client address. A value that is not an IP literal is returned as is. */
+export function normaliseClientKey(address) {
+    const bare = address.replace(/^\[|\]$/g, "").split("%")[0] ?? address;
+    const version = isIP(bare);
+    if (version === 4)
+        return bare;
+    if (version !== 6)
+        return address;
+    const g = ipv6Groups(bare);
+    const mapped = g.slice(0, 5).every((x) => x === 0) && g[5] === 0xffff;
+    if (mapped)
+        return `${g[6] >> 8}.${g[6] & 255}.${g[7] >> 8}.${g[7] & 255}`;
+    return `${g
+        .slice(0, 4)
+        .map((x) => x.toString(16))
+        .join(":")}::/64`;
+}
+/** The /48 aggregate key of a native IPv6 address, or null for IPv4, IPv4-mapped or non-IP. */
+export function prefix48Key(address) {
+    const bare = address.replace(/^\[|\]$/g, "").split("%")[0] ?? address;
+    if (isIP(bare) !== 6)
+        return null;
+    const g = ipv6Groups(bare);
+    const mapped = g.slice(0, 5).every((x) => x === 0) && g[5] === 0xffff;
+    if (mapped)
+        return null;
+    return `${g
+        .slice(0, 3)
+        .map((x) => x.toString(16))
+        .join(":")}::/48`;
+}
+export function createRegisterLimiter(options) {
+    const { limitPerMinute, prefix48LimitPerMinute, now } = options;
+    const maxKeys = options.maxKeys ?? 5000;
+    // Two LRU tables (Map iteration order = insertion order, re-inserted on every hit): keys
+    // still allowed, and keys already limited. Eviction drains the first before the second.
+    const open = new Map();
+    const limited = new Map();
+    const evictOne = () => {
+        const table = open.size > 0 ? open : limited;
+        const oldest = table.keys().next();
+        if (!oldest.done)
+            table.delete(oldest.value);
+    };
+    /** Counts one hit on `key`; true when that key is now over `limit` for its window. */
+    const bump = (key, limit, t0) => {
+        const prior = open.get(key) ?? limited.get(key);
+        const expired = prior !== undefined && t0 - prior.windowStart >= WINDOW_MS;
+        open.delete(key);
+        limited.delete(key);
+        if (!prior || expired) {
+            while (open.size + limited.size >= maxKeys)
+                evictOne();
+            const fresh = { windowStart: t0, count: 1 };
+            (fresh.count > limit ? limited : open).set(key, fresh);
+            return fresh.count > limit;
+        }
+        prior.count += 1;
+        const over = prior.count > limit;
+        (over ? limited : open).set(key, prior);
+        return over;
+    };
+    return {
+        allow(address) {
+            const t0 = now();
+            const overHost = bump(normaliseClientKey(address), limitPerMinute, t0);
+            // A host already over its own limit is refused without spending the shared /48 budget,
+            // so one hammering /64 cannot lock out the other /64s of its /48.
+            const wide = overHost || prefix48LimitPerMinute === undefined ? null : prefix48Key(address);
+            const overWide = wide === null ? false : bump(wide, prefix48LimitPerMinute, t0);
+            return !overHost && !overWide;
+        },
+        size: () => open.size + limited.size,
+    };
+}

package/dist/oauth/settings.d.ts

@@ -16,6 +16,8 @@ export declare const OAUTH_ENV: {
     readonly signingJwk: "MCP_OAUTH_SIGNING_JWK";
     /** Number of trusted reverse proxies in front of this server (default 0). */
     readonly trustedProxyCount: "MCP_TRUSTED_PROXY_COUNT";
+    /** /register budget shared by every /64 inside one IPv6 /48, per minute (default 100). */
+    readonly registerLimitPer48: "MCP_REGISTER_LIMIT_PER_48_PER_MINUTE";
     /** Comma-separated browser origins allowed to call /register cross-origin (default: none). */
     readonly registerCorsOrigins: "MCP_REGISTER_CORS_ORIGINS";
     /** Exactly "1" lets NODE_ENV=production run on the in-memory stores (single instance only). */

package/dist/oauth/settings.js

@@ -16,6 +16,8 @@ export const OAUTH_ENV = {
     signingJwk: "MCP_OAUTH_SIGNING_JWK",
     /** Number of trusted reverse proxies in front of this server (default 0). */
     trustedProxyCount: "MCP_TRUSTED_PROXY_COUNT",
+    /** /register budget shared by every /64 inside one IPv6 /48, per minute (default 100). */
+    registerLimitPer48: "MCP_REGISTER_LIMIT_PER_48_PER_MINUTE",
     /** Comma-separated browser origins allowed to call /register cross-origin (default: none). */
     registerCorsOrigins: "MCP_REGISTER_CORS_ORIGINS",
     /** Exactly "1" lets NODE_ENV=production run on the in-memory stores (single instance only). */

package/dist/pagination.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Cursor pagination applied by the tool (mcp-standard C-11, S-12, §3 point 4). A list tool
+ * declares a cursor, a default and a finite maximum (src/toolRecord.ts) and THIS module applies
+ * them, so the bound never depends on the store behind:
+ *
+ *   - the page size is the caller's `limit`, else the default, never above the maximum;
+ *   - the cursor is OPAQUE (base64url of a small JSON object) and carries the last key served,
+ *     so it is stable: rows added or removed elsewhere do not shift the next page;
+ *   - exhausted and truncated are told apart: a truncated page carries `nextCursor` and
+ *     `exhausted: false`; the last page carries `exhausted: true` and no `nextCursor` (an exact
+ *     fit is exhausted, never a false truncation);
+ *   - an invalid or expired cursor is refused with the stable code `invalid_cursor`, never read as
+ *     "page one". It is a TOOL INPUT error (a result with `isError: true`, spec 2025-11-25
+ *     SEP-1303), not a JSON-RPC error: -32602 stays with the protocol list methods' cursor.
+ */
+import { type LakeReader, type LakeScope } from "./lake/reader.js";
+/**
+ * The applied bounds, taken from the tool's own declaration so the number is typed once
+ * (tests/paginationApplied.test.ts proves the served annotations agree).
+ */
+export declare const PAGINATION: {
+    readonly default: 20;
+    readonly max: 100;
+};
+/** The stable machine code of an invalid or expired cursor, in `structuredContent.error.code`. */
+export declare const INVALID_CURSOR_CODE = "invalid_cursor";
+/** The cursor did not decode to a position in the collection. */
+export declare class InvalidCursorError extends Error {
+    readonly code = "invalid_cursor";
+    constructor();
+}
+export declare function encodeCursor(afterKey: string): string;
+export declare function decodeCursor(cursor: string): string;
+export interface Page<T> {
+    items: T[];
+    /** Present exactly when the page was truncated. */
+    nextCursor?: string;
+    exhausted: boolean;
+}
+export interface PageRequest {
+    cursor?: string;
+    limit?: number;
+}
+/**
+ * One page of `sortedRows` (sorted ascending by `id`, the collection key). The read is a key
+ * range (src/exampleItems.ts `rangeAfter`: binary search on the key), so its cost follows the
+ * page, not the collection.
+ */
+export declare function paginate<T extends {
+    id: string;
+}>(sortedRows: readonly T[], request: PageRequest, bounds: {
+    default: number;
+    max: number;
+}): Page<T>;
+/**
+ * One page read through a lake reader (src/lake/reader.ts): the same bounds and cursor as
+ * `paginate`, the range read delegated to the reader. The cursor is decoded BEFORE the reader is
+ * asked anything (an invalid cursor never costs a read), the page size is the caller's `limit`,
+ * else the default, never above the maximum, and the reader's answer is checked against the page
+ * contract (`checkLakePage`): an unreadable page is a `LakeReadError`, never an empty page. With
+ * the in-memory reader, the result is exactly `paginate`'s (tests/lakeReader.test.ts).
+ */
+export declare function readPage<Row>(reader: LakeReader<Row>, request: PageRequest, bounds: {
+    default: number;
+    max: number;
+}, scope?: LakeScope): Promise<Page<Row>>;