@vantageos/mcp-boilerplate 0.2.3 → 0.3.0

package/dist/upstream/paginatedClient.js

@@ -0,0 +1,422 @@
+/**
+ * Paginated upstream client, for a server derived from this boilerplate that reads a third-party
+ * endpoint paginated by OFFSET and LIMIT. The upstream is configuration: the parameter names,
+ * where they travel (query string or JSON body) and the HTTP method are options, nothing here
+ * names a vendor.
+ *
+ * Two reads:
+ * - `readAll(path, params)` walks the offset pages until a short or empty page (or, when the
+ *   response declares a total, until the total is reached) and returns every row. It is bounded
+ *   by a REQUIRED finite `rowCeiling`: a set that would exceed it is refused with an
+ *   `UpstreamPageError` (`row_ceiling_exceeded`) naming the ceiling. A truncated set is never
+ *   returned as if it were complete.
+ * - `readPage(path, params, cursor?)` reads ONE upstream page per MCP call and returns
+ *   `{ rows, nextCursor?, exhausted }`. The cursor is opaque: base64url of a small JSON object
+ *   carrying a version, the upstream offset and a fingerprint of path + params. A cursor that
+ *   does not decode, is replayed against another path or other params, or was altered without
+ *   recomputing its fingerprint is refused with the `invalid_cursor` semantics of
+ *   `src/pagination.ts` (`InvalidCursorError`), never read as page one. The fingerprint is an
+ *   UNKEYED hash: it detects misuse, not forgery. Anyone can mint a well-formed cursor at any
+ *   offset, which is acceptable because the offset carries no authority (the caller could ask
+ *   for that offset anyway): a minted offset above the ceiling is refused before any request,
+ *   and the same ceiling bounds the page-by-page walk.
+ *
+ * ```ts
+ * // src/upstream.ts — evaluated once per process, beside the token source
+ * export const things = createPaginatedUpstreamClient({
+ *   fetchImpl: upstream.fetchWithToken, // G1's token source; default: the global fetch
+ *   baseUrl: "https://api.upstream.example/v1/",
+ *   allowedOrigins: ["https://api.upstream.example"],
+ *   offsetParam: "offset",
+ *   limitParam: "limit",
+ *   placement: "jsonBody", // or "query"
+ *   rowCeiling: 5000,
+ *   extractRows: (body) => (body as { data: unknown[] }).data,
+ * });
+ * ```
+ *
+ * Safety:
+ * - Every request URL is resolved against `baseUrl` and its origin must be in `allowedOrigins`,
+ *   checked BEFORE any network call: a path (possibly from a tool argument) naming another host
+ *   never receives the bearer token. Origins are https, or http on loopback only (as G1).
+ * - Redirects are never followed (`redirect: "error"`): a 30x from an allowed origin cannot carry
+ *   the request to another host. The refused redirect surfaces as `unreachable`, by error kind.
+ * - 429 and 503 are retried with exponential backoff and jitter, honouring `Retry-After`
+ *   (seconds or HTTP date) capped by `maxDelayMs`; after `maxAttempts` the error names the
+ *   status and the attempt count. No other status is retried, and neither is a transport
+ *   failure (its error KIND is reported, never its message).
+ * - A body that is not JSON, an extractor that throws or does not return an array, an unreadable
+ *   total, or a page longer than the limit asked for is refused (fail closed). There is no
+ *   silent empty page: an empty page before a declared total is `inconsistent_page`, so a walk
+ *   can never re-request the same offset forever.
+ * - Errors may name the request PATH (pathname only) and the HTTP status. They never carry a
+ *   header, a token, the query string, a parameter value or the response body.
+ *
+ * Offset pagination over an order the upstream does not declare can skip or repeat rows when the
+ * data moves between two pages. This client cannot detect that; pass a sort parameter in
+ * `params` when the upstream offers one. And when the upstream silently caps the page below
+ * `pageSize`, a short page reads as the end of the set: keep `pageSize` within the upstream's
+ * real maximum, or supply `extractTotal`, which then decides the end instead.
+ *
+ * Errors are operator-facing (logged server-side), in English like `clientCredentials.ts`.
+ */
+import { createHash } from "node:crypto";
+import { InvalidCursorError } from "../pagination.js";
+/** A refused or failed upstream page read. Carries no header, token, parameter or body. */
+export class UpstreamPageError extends Error {
+    code;
+    /** The request pathname (no query string), when a request was built. */
+    path;
+    /** HTTP status, when the upstream answered. */
+    status;
+    /** Attempts made, on `rate_limited`. */
+    attempts;
+    /** The ceiling, on `row_ceiling_exceeded`. */
+    rowCeiling;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "UpstreamPageError";
+        this.code = code;
+        this.path = details.path;
+        this.status = details.status;
+        this.attempts = details.attempts;
+        this.rowCeiling = details.rowCeiling;
+    }
+}
+const DEFAULT_PAGE_SIZE = 100;
+const DEFAULT_MAX_ATTEMPTS = 5;
+const DEFAULT_BASE_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 30_000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const RETRYABLE = new Set([429, 503]);
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * Cursor format. It mirrors `src/pagination.ts` (opaque base64url JSON with a version, refused as
+ * `InvalidCursorError`) but cannot reuse its `encodeCursor`/`decodeCursor`: those carry one
+ * string key (`after`), and this cursor carries a numeric offset plus a fingerprint. The version
+ * differs (2) so a `list_items` cursor is never read as an upstream cursor, nor the reverse.
+ */
+const CURSOR_VERSION = 2;
+const isPositiveInteger = (n) => typeof n === "number" && Number.isSafeInteger(n) && n > 0;
+function validateOrigin(entry) {
+    let url;
+    try {
+        url = typeof entry === "string" ? new URL(entry) : undefined;
+    }
+    catch {
+        url = undefined;
+    }
+    if (!url || url.origin !== entry) {
+        throw new Error("paginated upstream: allowedOrigins entries must be origins like https://api.example (scheme, host, optional port; no path) (value not shown)");
+    }
+    const loopbackHttp = url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+    if (url.protocol !== "https:" && !loopbackHttp) {
+        throw new Error("paginated upstream: allowedOrigins entries must use https (http is accepted on loopback only) (value not shown)");
+    }
+    return url.origin;
+}
+/** JSON with object keys sorted at every depth, so the fingerprint ignores key order. */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function fingerprint(path, params) {
+    return createHash("sha256")
+        .update(canonicalJson({ path, params }))
+        .digest()
+        .subarray(0, 16)
+        .toString("base64url");
+}
+function encodeOffsetCursor(offset, print) {
+    return Buffer.from(JSON.stringify({ v: CURSOR_VERSION, o: offset, f: print })).toString("base64url");
+}
+function decodeOffsetCursor(cursor, print) {
+    let decoded;
+    try {
+        decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new InvalidCursorError();
+    }
+    if (typeof decoded !== "object" || decoded === null)
+        throw new InvalidCursorError();
+    const { v, o, f } = decoded;
+    if (v !== CURSOR_VERSION || !isPositiveInteger(o) || f !== print) {
+        throw new InvalidCursorError();
+    }
+    // Only the exact string this client issues is accepted: base64url decoding is lenient
+    // (trailing characters, extra fields), so the cursor is re-encoded and compared.
+    if (encodeOffsetCursor(o, print) !== cursor)
+        throw new InvalidCursorError();
+    return o;
+}
+/** `Retry-After` (RFC 9110 §10.2.3) in ms, from delay-seconds or an HTTP date; else undefined. */
+function retryAfterMs(header, now) {
+    if (header === null)
+        return undefined;
+    const value = header.trim();
+    if (/^\d+$/.test(value))
+        return Number(value) * 1000;
+    const date = Date.parse(value);
+    if (Number.isNaN(date))
+        return undefined;
+    return Math.max(0, date - now);
+}
+function isScalar(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+export function createPaginatedUpstreamClient(options) {
+    const { fetchImpl = (input, init) => fetch(input, init), baseUrl, allowedOrigins, offsetParam, limitParam, placement, pageSize = DEFAULT_PAGE_SIZE, rowCeiling, extractRows, extractTotal, headers: extraHeaders = {}, maxAttempts = DEFAULT_MAX_ATTEMPTS, baseDelayMs = DEFAULT_BASE_DELAY_MS, maxDelayMs = DEFAULT_MAX_DELAY_MS, timeoutMs = DEFAULT_TIMEOUT_MS, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), random = Math.random, now = Date.now, } = options;
+    if (!Array.isArray(allowedOrigins) || allowedOrigins.length === 0) {
+        throw new Error("paginated upstream: allowedOrigins is required and must not be empty");
+    }
+    const origins = new Set(allowedOrigins.map(validateOrigin));
+    let base;
+    try {
+        base = new URL(baseUrl);
+    }
+    catch {
+        throw new Error("paginated upstream: baseUrl is not a valid URL (value not shown)");
+    }
+    if (!origins.has(base.origin)) {
+        throw new Error("paginated upstream: the baseUrl origin is not in allowedOrigins");
+    }
+    if (placement !== "query" && placement !== "jsonBody") {
+        throw new Error('paginated upstream: placement must be "query" or "jsonBody"');
+    }
+    const method = (options.method ?? (placement === "query" ? "GET" : "POST")).toUpperCase();
+    if (placement === "jsonBody" && (method === "GET" || method === "HEAD")) {
+        throw new Error("paginated upstream: method GET or HEAD cannot carry a jsonBody placement");
+    }
+    if (typeof offsetParam !== "string" || offsetParam === "") {
+        throw new Error("paginated upstream: offsetParam must be a non-empty string");
+    }
+    if (typeof limitParam !== "string" || limitParam === "") {
+        throw new Error("paginated upstream: limitParam must be a non-empty string");
+    }
+    if (offsetParam === limitParam) {
+        throw new Error("paginated upstream: offsetParam and limitParam must differ");
+    }
+    if (!isPositiveInteger(pageSize)) {
+        throw new Error("paginated upstream: pageSize must be a positive integer");
+    }
+    if (!isPositiveInteger(rowCeiling)) {
+        throw new Error("paginated upstream: rowCeiling is required and must be a positive integer");
+    }
+    if (typeof extractRows !== "function") {
+        throw new Error("paginated upstream: extractRows must be a function");
+    }
+    if (!isPositiveInteger(maxAttempts)) {
+        throw new Error("paginated upstream: maxAttempts must be a positive integer");
+    }
+    for (const [name, value] of [
+        ["baseDelayMs", baseDelayMs],
+        ["maxDelayMs", maxDelayMs],
+    ]) {
+        if (!Number.isFinite(value) || value < 0) {
+            throw new Error(`paginated upstream: ${name} must be a non-negative number`);
+        }
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error("paginated upstream: timeoutMs must be a positive number");
+    }
+    /** Resolves the path and refuses, before any network call, an origin not allowed. */
+    const resolveUrl = (path) => {
+        let url;
+        try {
+            url = new URL(path, base);
+        }
+        catch {
+            throw new UpstreamPageError("origin_not_allowed", "Upstream path does not resolve to a URL");
+        }
+        if (!origins.has(url.origin)) {
+            throw new UpstreamPageError("origin_not_allowed", `Upstream request refused: origin not in allowedOrigins (path ${url.pathname})`, { path: url.pathname });
+        }
+        return url;
+    };
+    const checkParams = (params, path) => {
+        if (params === null || typeof params !== "object" || Array.isArray(params)) {
+            throw new UpstreamPageError("invalid_params", `Upstream params must be an object (${path})`, {
+                path,
+            });
+        }
+        for (const reserved of [offsetParam, limitParam]) {
+            if (Object.hasOwn(params, reserved)) {
+                throw new UpstreamPageError("invalid_params", `Upstream params must not set the pagination parameter "${reserved}" (${path})`, { path });
+            }
+        }
+        if (placement === "query") {
+            for (const [key, value] of Object.entries(params)) {
+                if (value === undefined || isScalar(value))
+                    continue;
+                if (Array.isArray(value) && value.every(isScalar))
+                    continue;
+                throw new UpstreamPageError("invalid_params", `Upstream query param "${key}" must be a string, number, boolean or an array of those (${path})`, { path });
+            }
+        }
+    };
+    const buildRequest = (url, params, offset) => {
+        const target = new URL(url);
+        const headers = { Accept: "application/json", ...extraHeaders };
+        let body;
+        if (placement === "query") {
+            for (const [key, value] of Object.entries(params)) {
+                if (value === undefined)
+                    continue;
+                for (const item of Array.isArray(value) ? value : [value]) {
+                    target.searchParams.append(key, String(item));
+                }
+            }
+            target.searchParams.set(offsetParam, String(offset));
+            target.searchParams.set(limitParam, String(pageSize));
+        }
+        else {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify({ ...params, [offsetParam]: offset, [limitParam]: pageSize });
+        }
+        return { target: target.toString(), headers, body };
+    };
+    const backoffMs = (retry, response) => {
+        const told = retryAfterMs(response.headers.get("retry-after"), now());
+        if (told !== undefined)
+            return Math.min(told, maxDelayMs);
+        const ceiling = Math.min(maxDelayMs, baseDelayMs * 2 ** (retry - 1));
+        // Equal jitter: half the exponential delay, plus a random share of the other half.
+        return ceiling / 2 + random() * (ceiling / 2);
+    };
+    /** One upstream page at `offset`, with the 429/503 retry loop. */
+    const fetchPage = async (url, params, offset) => {
+        const path = url.pathname;
+        const { target, headers, body } = buildRequest(url, params, offset);
+        const send = async () => {
+            try {
+                return await fetchImpl(target, {
+                    method,
+                    headers,
+                    body,
+                    // A redirect is refused, never followed: the origin check above must stay total.
+                    redirect: "error",
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (err) {
+                // Only the error's NAME travels: a transport message is not ours to vouch for. A refused
+                // redirect lands here too (fetch rejects with a TypeError): its target never travels.
+                const kind = err instanceof Error ? err.name : "unknown error";
+                throw new UpstreamPageError("unreachable", `Upstream unreachable (${kind}) (path ${path})`, { path });
+            }
+        };
+        let response = await send();
+        for (let attempt = 1; RETRYABLE.has(response.status); attempt++) {
+            if (attempt >= maxAttempts) {
+                await response.body?.cancel().catch(() => { });
+                throw new UpstreamPageError("rate_limited", `Upstream answered ${response.status} after ${attempt} attempts (path ${path})`, { path, status: response.status, attempts: attempt });
+            }
+            const delay = backoffMs(attempt, response);
+            await response.body?.cancel().catch(() => { });
+            await sleep(delay);
+            response = await send();
+        }
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => { });
+            throw new UpstreamPageError("upstream_status", `Upstream answered ${response.status} (path ${path})`, { path, status: response.status });
+        }
+        const status = response.status;
+        const refuse = (what) => new UpstreamPageError("unreadable_page", `Upstream answered ${status} with ${what} (path ${path})`, { path, status });
+        let parsed;
+        try {
+            parsed = await response.json();
+        }
+        catch {
+            throw refuse("a body that is not JSON");
+        }
+        let rows;
+        try {
+            rows = extractRows(parsed);
+        }
+        catch {
+            // The extractor's message may quote the body: it does not travel.
+            throw refuse("a page the row extractor could not read");
+        }
+        if (!Array.isArray(rows))
+            throw refuse("rows that are not an array");
+        if (rows.length > pageSize) {
+            throw new UpstreamPageError("inconsistent_page", `Upstream returned ${rows.length} rows for a page of ${pageSize}: the limit parameter was not applied (path ${path})`, { path, status });
+        }
+        let total;
+        if (extractTotal) {
+            let raw;
+            try {
+                raw = extractTotal(parsed);
+            }
+            catch {
+                throw refuse("a page the total extractor could not read");
+            }
+            if (raw !== undefined) {
+                if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw < 0) {
+                    throw refuse("an unreadable total");
+                }
+                total = raw;
+            }
+        }
+        return { rows: rows, total };
+    };
+    /** Whether the page at `offset` is the last one. */
+    const isLast = (offset, count, total, path) => {
+        if (total === undefined)
+            return count < pageSize;
+        if (offset + count >= total)
+            return true;
+        if (count === 0) {
+            throw new UpstreamPageError("inconsistent_page", `Upstream returned an empty page before its declared total (path ${path})`, { path });
+        }
+        return false;
+    };
+    const ceilingError = (path) => new UpstreamPageError("row_ceiling_exceeded", `Upstream result exceeds the row ceiling of ${rowCeiling} rows (path ${path}); narrow the query`, { path, rowCeiling });
+    const readAll = async (path, params) => {
+        const url = resolveUrl(path);
+        checkParams(params, url.pathname);
+        const collected = [];
+        let offset = 0;
+        for (;;) {
+            const { rows, total } = await fetchPage(url, params, offset);
+            if (collected.length + rows.length > rowCeiling)
+                throw ceilingError(url.pathname);
+            if (total !== undefined && total > rowCeiling)
+                throw ceilingError(url.pathname);
+            collected.push(...rows);
+            if (isLast(offset, rows.length, total, url.pathname))
+                return collected;
+            offset += rows.length;
+        }
+    };
+    const readPage = async (path, params, cursor) => {
+        const url = resolveUrl(path);
+        checkParams(params, url.pathname);
+        const print = fingerprint(url.pathname + url.search, params);
+        const offset = cursor === undefined ? 0 : decodeOffsetCursor(cursor, print);
+        // A cursor at the ceiling may still meet an empty page (exact fit); beyond it, nothing is read.
+        if (offset > rowCeiling)
+            throw ceilingError(url.pathname);
+        const { rows, total } = await fetchPage(url, params, offset);
+        if (offset + rows.length > rowCeiling)
+            throw ceilingError(url.pathname);
+        const page = { rows, exhausted: false };
+        if (total !== undefined)
+            page.total = total;
+        if (isLast(offset, rows.length, total, url.pathname)) {
+            page.exhausted = true;
+            return page;
+        }
+        page.nextCursor = encodeOffsetCursor(offset + rows.length, print);
+        return page;
+    };
+    return { readAll, readPage };
+}

package/dist/verifiedPerson.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The caller's verified PERSON, for tool handlers.
+ *
+ * The person is resolved by @vantageos/cloud-identity's `resolveCallerFromClaims` (tagged
+ * `@callerResolver`), from the same verified session claims the tenant comes from, ONCE per /mcp
+ * request (src/httpApp.ts). This module never reads a claim itself: the claim record goes to the
+ * package whole, and only the package's result comes back.
+ *
+ * The stores the package reads (the organisation mapping and the people of each organisation)
+ * and the roles that make a person an admin of their organisation are INJECTED by the deployment
+ * (`AppDeps.identity`). The boilerplate builds no store and names no role.
+ *
+ * A tool that needs the person wraps its handler with `withVerifiedPerson`. Every member of
+ * `CallerResolution` other than `ok: true` refuses it, before the handler runs, with the stable
+ * code `PERSON_UNRESOLVED_CODE` and a message in the caller's language:
+ *  - `identity_not_configured` — the deployment injected no `identity`;
+ *  - `no_verified_session`     — no verified session exists: the public HTTP tier, and stdio,
+ *                                 where there is no bearer at all, so no person, ever;
+ *  - `refused`                 — the package refused; its refusal code and reason are carried,
+ *                                 never a claim value nor its free-text detail.
+ * A tool that does not wrap its handler is untouched and runs with no person.
+ */
+import type { CallToolResult, ServerContext } from "@modelcontextprotocol/server";
+import { type CallerFromClaimsResult, type IdentityRefusalCode, type IdentityRefusalReason, type OrgMappingLookups, type PrincipalLookups } from "@vantageos/cloud-identity";
+import { type McpLocale } from "./i18n.js";
+/** What a deployment injects so the person can be resolved. `adminRoles` has no default. */
+export interface IdentityDeps {
+    /** The organisation mapping store (the package reads `orgById`). */
+    readonly orgLookups: OrgMappingLookups;
+    /** The people of each organisation (the package reads `personById`, `organisationById`, `orgKindOf`). */
+    readonly principalLookups: PrincipalLookups;
+    /** The org roles that make a person an admin of their organisation, compared byte for byte. Non-empty. */
+    readonly adminRoles: readonly string[];
+}
+type CallerResolved = Extract<CallerFromClaimsResult, {
+    ok: true;
+}>;
+/** Read-only at every level. */
+type DeepReadonly<T> = T extends (infer E)[] ? readonly DeepReadonly<E>[] : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/** The verified person, exactly the fields the package returns, frozen. */
+export type VerifiedPerson = DeepReadonly<Pick<CallerResolved, "subject" | "actorName" | "org" | "principal" | "role" | "isOrgAdmin">>;
+export type PersonUnresolvedReason = "identity_not_configured" | "no_verified_session" | "refused";
+/** The per-request outcome, carried beside the tenant in the server deps. */
+export type CallerResolution = {
+    readonly ok: true;
+    readonly person: VerifiedPerson;
+} | {
+    readonly ok: false;
+    readonly reason: PersonUnresolvedReason;
+    /** Present only when `reason` is `refused`: the package's code and reason, nothing else. */
+    readonly refusal?: {
+        readonly code: IdentityRefusalCode;
+        readonly reason: IdentityRefusalReason;
+    };
+};
+/** Stable machine code of the refusal a requiring tool returns. */
+export declare const PERSON_UNRESOLVED_CODE = "person_unresolved";
+/** This server's name for the door, carried on every package refusal. */
+export declare const PERSON_DOOR = "mcp-tool-call";
+/**
+ * Refuses an `identity` that cannot resolve anyone: called when the app is built, so a
+ * misconfiguration fails at start, never per request and never as a defaulted role.
+ */
+export declare function assertIdentityDeps(identity: IdentityDeps): void;
+/**
+ * Resolves the person behind a verified session through the package. `claims` is the verified
+ * session's claim record, or undefined when no session was verified.
+ */
+export declare function resolveVerifiedPerson(claims: Readonly<Record<string, unknown>> | undefined, identity: IdentityDeps | undefined): Promise<CallerResolution>;
+/** The per-request context a requiring tool reads: the same deps object the tenant travels in. */
+export interface PersonContext {
+    caller?: CallerResolution;
+    locale?: McpLocale;
+}
+export type PersonRefusalResult = CallToolResult & {
+    isError: true;
+};
+/**
+ * Declares that a tool needs the verified person: the handler runs only with one, and receives it
+ * as its second argument. No caller resolution in the context (stdio) is `no_verified_session`.
+ */
+export declare function withVerifiedPerson<A, R extends CallToolResult>(context: PersonContext, handler: (args: A, person: VerifiedPerson, ctx: ServerContext) => R | Promise<R>): (args: A, ctx: ServerContext) => Promise<R | PersonRefusalResult>;
+export {};

package/dist/verifiedPerson.js

@@ -0,0 +1,112 @@
+/**
+ * The caller's verified PERSON, for tool handlers.
+ *
+ * The person is resolved by @vantageos/cloud-identity's `resolveCallerFromClaims` (tagged
+ * `@callerResolver`), from the same verified session claims the tenant comes from, ONCE per /mcp
+ * request (src/httpApp.ts). This module never reads a claim itself: the claim record goes to the
+ * package whole, and only the package's result comes back.
+ *
+ * The stores the package reads (the organisation mapping and the people of each organisation)
+ * and the roles that make a person an admin of their organisation are INJECTED by the deployment
+ * (`AppDeps.identity`). The boilerplate builds no store and names no role.
+ *
+ * A tool that needs the person wraps its handler with `withVerifiedPerson`. Every member of
+ * `CallerResolution` other than `ok: true` refuses it, before the handler runs, with the stable
+ * code `PERSON_UNRESOLVED_CODE` and a message in the caller's language:
+ *  - `identity_not_configured` — the deployment injected no `identity`;
+ *  - `no_verified_session`     — no verified session exists: the public HTTP tier, and stdio,
+ *                                 where there is no bearer at all, so no person, ever;
+ *  - `refused`                 — the package refused; its refusal code and reason are carried,
+ *                                 never a claim value nor its free-text detail.
+ * A tool that does not wrap its handler is untouched and runs with no person.
+ */
+import { resolveCallerFromClaims, } from "@vantageos/cloud-identity";
+import { t } from "./i18n.js";
+/** Stable machine code of the refusal a requiring tool returns. */
+export const PERSON_UNRESOLVED_CODE = "person_unresolved";
+/** This server's name for the door, carried on every package refusal. */
+export const PERSON_DOOR = "mcp-tool-call";
+/**
+ * Refuses an `identity` that cannot resolve anyone: called when the app is built, so a
+ * misconfiguration fails at start, never per request and never as a defaulted role.
+ */
+export function assertIdentityDeps(identity) {
+    const roles = Array.isArray(identity.adminRoles) ? identity.adminRoles : [];
+    if (roles.length === 0 || !roles.every((r) => typeof r === "string" && r.length > 0)) {
+        throw new Error("identity.adminRoles must name at least one role: the boilerplate never defaults an admin role.");
+    }
+}
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+function unresolved(reason) {
+    const outcome = { ok: false, reason };
+    return Object.freeze(outcome);
+}
+/**
+ * Resolves the person behind a verified session through the package. `claims` is the verified
+ * session's claim record, or undefined when no session was verified.
+ */
+export async function resolveVerifiedPerson(claims, identity) {
+    if (!identity)
+        return unresolved("identity_not_configured");
+    if (!claims)
+        return unresolved("no_verified_session");
+    const result = await resolveCallerFromClaims(claims, { orgLookups: identity.orgLookups, principalLookups: identity.principalLookups }, { adminRoles: identity.adminRoles, door: PERSON_DOOR });
+    if (!result.ok) {
+        const refused = {
+            ok: false,
+            reason: "refused",
+            refusal: { code: result.refusal.code, reason: result.refusal.reason },
+        };
+        return deepFreeze(refused);
+    }
+    // A copy (structuredClone), then frozen: the store's own objects are never frozen or shared.
+    const person = structuredClone({
+        subject: result.subject,
+        actorName: result.actorName,
+        org: result.org,
+        principal: result.principal,
+        role: result.role,
+        isOrgAdmin: result.isOrgAdmin,
+    });
+    const resolved = { ok: true, person: deepFreeze(person) };
+    return Object.freeze(resolved);
+}
+const MESSAGE_KEYS = {
+    identity_not_configured: "person.identityNotConfigured",
+    no_verified_session: "person.noVerifiedSession",
+    refused: "person.refused",
+};
+function personRefusal(caller, locale) {
+    const message = t(locale, MESSAGE_KEYS[caller.reason]);
+    return {
+        content: [{ type: "text", text: message }],
+        structuredContent: {
+            error: {
+                code: PERSON_UNRESOLVED_CODE,
+                message,
+                reason: caller.reason,
+                ...(caller.refusal ? { refusal: { ...caller.refusal } } : {}),
+            },
+        },
+        isError: true,
+    };
+}
+/**
+ * Declares that a tool needs the verified person: the handler runs only with one, and receives it
+ * as its second argument. No caller resolution in the context (stdio) is `no_verified_session`.
+ */
+export function withVerifiedPerson(context, handler) {
+    return async (args, ctx) => {
+        const caller = context.caller ?? unresolved("no_verified_session");
+        if (!caller.ok)
+            return personRefusal(caller, context.locale ?? "en");
+        return handler(args, caller.person, ctx);
+    };
+}

package/docs/oauth-stores.md

@@ -14,7 +14,8 @@ both `codeStore` and `clientRegistry` are injected, or `MCP_ALLOW_IN_MEMORY_STOR
 single-instance deployment that accepts forgetting codes and DCR clients on restart (for example
 a verification instance). The in-memory adapters are bounded: codes expire out of memory and the
 used set is pruned past each code's expiry; registered clients expire after 30 days and the oldest
-is evicted at the cap.
+is NOT evicted at the cap: a new registration is refused (`RegistryFullError`, answered `503`
+with `Retry-After`) after expired clients are pruned. A durable adapter may throw the same error.
 
 ## `AuthorizationCodeStore` (cloud-identity type, `src/oauth/codeStore.ts`)
 

package/examples/oauth.env.example

@@ -26,10 +26,17 @@ MCP_OAUTH_SIGNING_JWK=
 
 # Number of trusted reverse proxies in front of this server (default 0): the /register rate limit
 # keys on the socket address, or on the X-Forwarded-For entry the N-th proxy appended.
+# N = proxy HOPS that append to X-Forwarded-For (Railway: 2, measured). Too LOW fails silently
+# (the limiter keys on a shared proxy). Measure: 21 registrations from one client, 429 on the 21st.
 # MCP_TRUSTED_PROXY_COUNT=1
+# /register budget shared by every /64 inside one IPv6 /48, per minute (default 100). A /48 holds
+# 65536 /64s; without this budget one /48 could fill the client registry to its 503.
+# MCP_REGISTER_LIMIT_PER_48_PER_MINUTE=100
 # NODE_ENV=production refuses the in-memory stores; exactly "1" accepts them (single instance).
 # MCP_ALLOW_IN_MEMORY_STORES=1
 # Largest request body the Node entry accepts, in bytes (default 1048576); over it answers 413.
 # MCP_MAX_BODY_BYTES=1048576
 # Browser origins allowed to call /register cross-origin (comma-separated; default none).
 # MCP_REGISTER_CORS_ORIGINS=https://inspector.example.com
+# Display name shown above the consent page title (default: none).
+# AUTHORIZE_BRAND_NAME=Acme MCP

package/mcp-server.json

@@ -0,0 +1,13 @@
+{
+  "name": "mcp-boilerplate",
+  "version": "0.3.0",
+  "capabilities": {
+    "tools": {},
+    "resources": {}
+  },
+  "transport": {
+    "stdio": { "bin": "mcp-boilerplate" },
+    "streamableHttp": { "path": "/mcp", "stateless": true }
+  },
+  "features": {}
+}