@vantageos/mcp-boilerplate 0.3.0 → 0.5.0

package/dist/toolRecord.d.ts

@@ -1,3 +1,4 @@
+import type { ContextCeiling } from "./serverManifest.js";
 /**
  * The typed tool record (mcp-standard C-4, C-8, C-9, C-10, C-11, C-12, C-13, C-15): everything
  * a caller reads from `tools/list` WITHOUT reading the source, declared once per tool as a
@@ -26,8 +27,13 @@ export type ToolVerb = "list" | "get" | "search" | "aggregate" | "create" | "upd
 /**
  * mcp-standard.md §3 point 3 — search mechanisms, closed set. `unindexed-scan` is deliberately
  * absent: it is refused at publication, so the type refuses it at compile time.
+ *
+ * `upstream-delegated(<upstream>)` is the honest value for a tool answered by a LIVE call to a
+ * third-party API: this server keeps no index for it, and the upstream is named. It is allowed
+ * only together with `openWorldHint: true`, and a list/search tool with `openWorldHint: true`
+ * must declare it (`checkToolRecord`).
  */
-export type SearchMechanism = "indexed-range" | "indexed-bm25" | `indexed-vector(${string})` | "indexed-hybrid-rrf";
+export type SearchMechanism = "indexed-range" | "indexed-bm25" | `indexed-vector(${string})` | "indexed-hybrid-rrf" | `upstream-delegated(${string})`;
 /** The four behavioural annotations (C-15), explicit booleans on every tool. */
 interface BehaviourHints {
     readOnlyHint: boolean;
@@ -87,8 +93,32 @@ export declare const LIST_ITEMS_ANNOTATIONS: {
     readonly paginationMax: 100;
     readonly tokensEstimeContexte: 640;
 };
-export declare const CONTEXT_CEILING: {
-    readonly global: 1200;
-    readonly perTool: 700;
-};
+/** One tool's declared context cost, as `checkContextCeiling` reads it. */
+export interface ContextEstimate {
+    name: string;
+    tokens: number;
+}
+/** Every problem found, each naming the tool; empty when the ceiling holds. Never skips a tool. */
+export declare function checkContextCeiling(estimates: readonly ContextEstimate[], ceiling: ContextCeiling): string[];
+/**
+ * Problems with ONE tool's served record; empty when it is sound. Reads a loose record because the
+ * same check runs on the declared literals and on the annotations as served.
+ *
+ * A list/search tool must declare a mechanism of the closed set: an indexed one when it reads
+ * data this server holds (`openWorldHint: false`), `upstream-delegated(<upstream>)` when it calls
+ * out (`openWorldHint: true`). The two slots must agree, so a live-call tool cannot pass for an
+ * indexed one, nor an indexed one claim to be delegated. `unindexed-scan` and any other value are
+ * refused. A tool that is not a list/search is not asked for a mechanism.
+ */
+export declare function checkToolRecord(name: string, record: Record<string, unknown>): string[];
+/** Thrown at start when a tool record or the ceiling is unsound. `problems` name every tool. */
+export declare class ToolRecordError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/**
+ * Refuses at start: every record passes `checkToolRecord`, and the declared estimates fit the
+ * server's own ceiling (from its manifest). A derived server passes ALL its tools' records.
+ */
+export declare function assertToolRecords(records: Readonly<Record<string, Record<string, unknown>>>, ceiling: ContextCeiling): void;
 export {};

package/dist/toolRecord.js

@@ -1,24 +1,4 @@
-/**
- * The typed tool record (mcp-standard C-4, C-8, C-9, C-10, C-11, C-12, C-13, C-15): everything
- * a caller reads from `tools/list` WITHOUT reading the source, declared once per tool as a
- * literal object and served as its `annotations`.
- *
- *   authRead, authWrite     C-8   the (read, write) pair, from the closed five-tier set, distinct
- *   verb                    C-9   the operation, from the closed verb set (`rpc` is not a verb)
- *   table                   C-12  the data it touches, beside the verb
- *   searchMechanism         C-10  how a list/search is served; `unindexed-scan` does not publish
- *   paginationCursor/Default/Max  C-11  declared here, applied by src/pagination.ts
- *   tokensEstimeContexte    C-13  the estimated context cost of the served tool
- *
- * The sets are closed UNIONS, so a value outside them is a compile error, and the verb decides
- * which other slots are required (a list/search tool cannot omit its mechanism or its pagination).
- * Each tool's record is a plain `const` object of string/number/boolean literals on purpose:
- * mcp-doctor reads the registration site statically and resolves `annotations: NAME` to the
- * literals below; a computed or spread value would read as "could not judge".
- *
- * SDK 2.3.1 serves unknown annotation keys on the wire (tests/toolAuthorityDeclared.test.ts
- * reads them there); its `Client` drops them, which is why those tests read the raw result.
- */
+import { tBoth } from "./i18n.js";
 // Authority decisions (C-8). The seed tools read; none writes anything, so the write side
 // is `master`, the strictest tier: no caller gains a write through them. `ping` touches no data
 // and is `public`; the item tool is scoped to the caller's organisation on the OAuth tier.
@@ -47,6 +27,88 @@ export const LIST_ITEMS_ANNOTATIONS = {
     paginationMax: 100,
     tokensEstimeContexte: 640,
 };
-// Context ceiling (C-13), global AND per tool, in estimated tokens. The sum of the per-tool
-// estimates above must not pass `global`; no single estimate may pass `perTool`.
-export const CONTEXT_CEILING = { global: 1200, perTool: 700 };
+/** Every problem found, each naming the tool; empty when the ceiling holds. Never skips a tool. */
+export function checkContextCeiling(estimates, ceiling) {
+    const problems = [];
+    let sum = 0;
+    for (const { name, tokens } of estimates) {
+        if (!Number.isInteger(tokens) || tokens < 0) {
+            problems.push(`${name}: tokensEstimeContexte ${String(tokens)} is not a non-negative integer`);
+            continue;
+        }
+        sum += tokens;
+        if (tokens > ceiling.perTool) {
+            problems.push(`${name}: ${tokens} tokens pass the per-tool ceiling ${ceiling.perTool}`);
+        }
+    }
+    if (sum > ceiling.global) {
+        problems.push(`global: ${sum} tokens pass the global ceiling ${ceiling.global}`);
+    }
+    return problems;
+}
+const LIST_VERBS = ["list", "search"];
+// The closed indexed set, exactly: the three parameterless forms, and `indexed-vector(<metric>)`.
+const INDEXED_EXACT = ["indexed-range", "indexed-bm25", "indexed-hybrid-rrf"];
+const INDEXED_VECTOR = /^indexed-vector\([^()\s][^()]*\)$/;
+const DELEGATED = /^upstream-delegated\(\s*[^\s)][^)]*\)$/;
+/** True for a mechanism of the closed indexed set, matched whole (no prefix, no open paren). */
+function isIndexedMechanism(value) {
+    return INDEXED_EXACT.includes(value) || INDEXED_VECTOR.test(value);
+}
+/**
+ * Problems with ONE tool's served record; empty when it is sound. Reads a loose record because the
+ * same check runs on the declared literals and on the annotations as served.
+ *
+ * A list/search tool must declare a mechanism of the closed set: an indexed one when it reads
+ * data this server holds (`openWorldHint: false`), `upstream-delegated(<upstream>)` when it calls
+ * out (`openWorldHint: true`). The two slots must agree, so a live-call tool cannot pass for an
+ * indexed one, nor an indexed one claim to be delegated. `unindexed-scan` and any other value are
+ * refused. A tool that is not a list/search is not asked for a mechanism.
+ */
+export function checkToolRecord(name, record) {
+    if (!LIST_VERBS.includes(record.verb))
+        return [];
+    const mechanism = record.searchMechanism;
+    if (typeof mechanism !== "string") {
+        return [`${name}: a ${String(record.verb)} tool declares no searchMechanism`];
+    }
+    const openWorld = record.openWorldHint === true;
+    if (DELEGATED.test(mechanism)) {
+        return openWorld
+            ? []
+            : [`${name}: ${mechanism} is a live upstream call, but openWorldHint is not true`];
+    }
+    if (isIndexedMechanism(mechanism)) {
+        return openWorld
+            ? [
+                `${name}: ${mechanism} claims an index, but openWorldHint is true (a live call must declare upstream-delegated(<upstream>))`,
+            ]
+            : [];
+    }
+    return [`${name}: searchMechanism "${mechanism}" is not in the closed set`];
+}
+/** Thrown at start when a tool record or the ceiling is unsound. `problems` name every tool. */
+export class ToolRecordError extends Error {
+    problems;
+    constructor(problems) {
+        super(tBoth("toolRecord.unsound", { problems: problems.join("; ") }));
+        this.name = "ToolRecordError";
+        this.problems = problems;
+    }
+}
+/**
+ * Refuses at start: every record passes `checkToolRecord`, and the declared estimates fit the
+ * server's own ceiling (from its manifest). A derived server passes ALL its tools' records.
+ */
+export function assertToolRecords(records, ceiling) {
+    const problems = Object.entries(records).flatMap(([name, record]) => [
+        ...checkToolRecord(name, record),
+    ]);
+    const estimates = Object.entries(records).map(([name, record]) => ({
+        name,
+        tokens: record.tokensEstimeContexte,
+    }));
+    problems.push(...checkContextCeiling(estimates, ceiling));
+    if (problems.length > 0)
+        throw new ToolRecordError(problems);
+}

package/dist/upstream/clientCredentials.d.ts

@@ -58,6 +58,8 @@ export interface ClientCredentialsOptions {
     refreshSkewSeconds?: number;
     /** Time budget of one token request. Default 10 s. */
     timeoutMs?: number;
+    /** Time budget of one API request through `fetchWithToken`. Default: `UPSTREAM_TIMEOUT_MS` (30 s). */
+    requestTimeoutMs?: number;
     /** Default: the global fetch. Also used by `fetchWithToken` for the upstream API. */
     fetchImpl?: typeof fetch;
     /** Milliseconds since the epoch. Default `Date.now`. */

package/dist/upstream/clientCredentials.js

@@ -43,6 +43,7 @@
  * localised tool message.
  */
 import { rawKnob } from "../envKnobs.js";
+import { boundedFetch, configuredUpstreamTimeoutMs } from "./timeout.js";
 /** A failure of the upstream token endpoint. Carries no credential and no token. */
 export class UpstreamTokenError extends Error {
     /** HTTP status of the token endpoint, when it answered. */
@@ -86,7 +87,7 @@ function validateTokenUrl(tokenUrl) {
     }
 }
 export function createClientCredentialsTokenSource(options) {
-    const { tokenUrl, clientId, clientSecret, scope, audience, authMethod = "client_secret_basic", refreshSkewSeconds = DEFAULT_SKEW_SECONDS, timeoutMs = DEFAULT_TIMEOUT_MS, fetchImpl = fetch, now = Date.now, } = options;
+    const { tokenUrl, clientId, clientSecret, scope, audience, authMethod = "client_secret_basic", refreshSkewSeconds = DEFAULT_SKEW_SECONDS, timeoutMs = DEFAULT_TIMEOUT_MS, fetchImpl: rawFetch = fetch, requestTimeoutMs = configuredUpstreamTimeoutMs(), now = Date.now, } = options;
     validateTokenUrl(tokenUrl);
     if (!clientId)
         throw new Error("client_credentials: clientId is empty");
@@ -101,6 +102,12 @@ export function createClientCredentialsTokenSource(options) {
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         throw new Error("client_credentials: timeoutMs must be a positive number");
     }
+    if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+        throw new Error("client_credentials: requestTimeoutMs must be a positive number");
+    }
+    // S-13: the token request and the API requests each carry a timeout, whatever fetch they use.
+    const tokenFetch = boundedFetch(rawFetch, timeoutMs);
+    const apiFetch = boundedFetch(rawFetch, requestTimeoutMs);
     // Each part is form-encoded first (RFC 6749 §2.3.1), so the input to btoa is ASCII.
     const basicCredentials = btoa(`${formEncode(clientId)}:${formEncode(clientSecret)}`);
     const basicHeader = `Basic ${basicCredentials}`;
@@ -137,14 +144,13 @@ export function createClientCredentialsTokenSource(options) {
         }
         let res;
         try {
-            res = await fetchImpl(tokenUrl, {
+            res = await tokenFetch(tokenUrl, {
                 method: "POST",
                 headers,
                 body: form.toString(),
                 // A redirect is refused, never followed: a 307/308 would re-send this body, which carries
                 // the client secret under client_secret_post, to whatever host the Location names.
                 redirect: "error",
-                signal: AbortSignal.timeout(timeoutMs),
             });
         }
         catch (err) {
@@ -242,7 +248,7 @@ export function createClientCredentialsTokenSource(options) {
             const target = input instanceof Request && !last ? input.clone() : input;
             // The caller's init is spread as given, redirect mode included: the caller decides whether
             // its API request follows redirects (the paginated client passes redirect: "error").
-            return fetchImpl(target, { ...init, headers });
+            return apiFetch(target, { ...init, headers });
         };
         const token = await getToken();
         const first = await send(token, !replayable);

package/dist/upstream/paginatedClient.d.ts

@@ -11,15 +11,20 @@
  *   `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.
+ *   `{ rows, nextCursor?, exhausted }`. The cursor carries a version, the upstream offset and a
+ *   fingerprint of path + params, and it is SIGNED (src/signedCursor.ts): the token is the
+ *   base64url payload and its HMAC-SHA256 tag under the client's `cursorSigner` key. The HMAC is
+ *   the guard; the fingerprint only binds the cursor to its request INSIDE the signed payload.
+ *   What it guarantees: a cursor this client did not issue (an edited offset, a fingerprint
+ *   recomputed for other params, a token minted from the public format, one signed under another
+ *   key) is refused with the `invalid_cursor` semantics of `src/pagination.ts`
+ *   (`InvalidCursorError`) BEFORE any upstream request, never read as page one; and an issued
+ *   cursor replayed against another path or other params is refused the same way. The ceiling
+ *   check on the decoded offset stays, as defence in depth for whoever holds the key.
+ *   Declared limit: the default signer's key is 32 random bytes drawn once per client, so a
+ *   process restart invalidates every outstanding cursor (the caller starts again without one),
+ *   and instances of a multi-instance deployment reject each other's cursors unless they are
+ *   given one shared key (`cursorSigner: createCursorSigner({ key })`, 32 bytes or more).
  *
  * ```ts
  * // src/upstream.ts — evaluated once per process, beside the token source
@@ -60,6 +65,7 @@
  *
  * Errors are operator-facing (logged server-side), in English like `clientCredentials.ts`.
  */
+import { type CursorSigner } from "../signedCursor.js";
 export type PaginationPlacement = "query" | "jsonBody";
 /** Any `fetch`-compatible function: the global fetch, or G1's `tokenSource.fetchWithToken`. */
 export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
@@ -94,7 +100,7 @@ export interface PaginatedUpstreamOptions<Row = unknown> {
     baseDelayMs?: number;
     /** Cap on any one delay, `Retry-After` included. Default 30 000 ms. */
     maxDelayMs?: number;
-    /** Time budget of one request. Default 30 s. */
+    /** Time budget of one request. Default: `UPSTREAM_TIMEOUT_MS` (30 s when unset). */
     timeoutMs?: number;
     /** Default: a `setTimeout` promise. */
     sleep?: (ms: number) => Promise<void>;
@@ -102,6 +108,12 @@ export interface PaginatedUpstreamOptions<Row = unknown> {
     random?: () => number;
     /** Milliseconds since the epoch, for `Retry-After` dates. Default `Date.now`. */
     now?: () => number;
+    /**
+     * Signs and verifies `readPage` cursors (src/signedCursor.ts). Default: a signer of this client
+     * with a random key, so a restart invalidates outstanding cursors. Inject one signer built on a
+     * shared key (`createCursorSigner({ key })`) into every instance of a multi-instance deployment.
+     */
+    cursorSigner?: CursorSigner;
 }
 export type ParamValue = string | number | boolean | null | ParamValue[] | ParamObject;
 export interface ParamObject {

package/dist/upstream/paginatedClient.js

@@ -11,15 +11,20 @@
  *   `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.
+ *   `{ rows, nextCursor?, exhausted }`. The cursor carries a version, the upstream offset and a
+ *   fingerprint of path + params, and it is SIGNED (src/signedCursor.ts): the token is the
+ *   base64url payload and its HMAC-SHA256 tag under the client's `cursorSigner` key. The HMAC is
+ *   the guard; the fingerprint only binds the cursor to its request INSIDE the signed payload.
+ *   What it guarantees: a cursor this client did not issue (an edited offset, a fingerprint
+ *   recomputed for other params, a token minted from the public format, one signed under another
+ *   key) is refused with the `invalid_cursor` semantics of `src/pagination.ts`
+ *   (`InvalidCursorError`) BEFORE any upstream request, never read as page one; and an issued
+ *   cursor replayed against another path or other params is refused the same way. The ceiling
+ *   check on the decoded offset stays, as defence in depth for whoever holds the key.
+ *   Declared limit: the default signer's key is 32 random bytes drawn once per client, so a
+ *   process restart invalidates every outstanding cursor (the caller starts again without one),
+ *   and instances of a multi-instance deployment reject each other's cursors unless they are
+ *   given one shared key (`cursorSigner: createCursorSigner({ key })`, 32 bytes or more).
  *
  * ```ts
  * // src/upstream.ts — evaluated once per process, beside the token source
@@ -61,7 +66,8 @@
  * Errors are operator-facing (logged server-side), in English like `clientCredentials.ts`.
  */
 import { createHash } from "node:crypto";
-import { InvalidCursorError } from "../pagination.js";
+import { InvalidCursorError, createCursorSigner } from "../signedCursor.js";
+import { boundedFetch, configuredUpstreamTimeoutMs, upstreamSignal } from "./timeout.js";
 /** A refused or failed upstream page read. Carries no header, token, parameter or body. */
 export class UpstreamPageError extends Error {
     code;
@@ -87,14 +93,14 @@ 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
+ * Cursor format. It mirrors `src/pagination.ts` (a signed JSON payload 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.
+ * differs (2) so a `list_items` cursor is never read as an upstream cursor, nor the reverse, even
+ * when both are signed under one shared key.
  */
 const CURSOR_VERSION = 2;
 const isPositiveInteger = (n) => typeof n === "number" && Number.isSafeInteger(n) && n > 0;
@@ -134,27 +140,29 @@ function fingerprint(path, params) {
         .subarray(0, 16)
         .toString("base64url");
 }
-function encodeOffsetCursor(offset, print) {
-    return Buffer.from(JSON.stringify({ v: CURSOR_VERSION, o: offset, f: print })).toString("base64url");
+function encodeOffsetCursor(signer, offset, print) {
+    return signer.sign(JSON.stringify({ v: CURSOR_VERSION, o: offset, f: print }));
 }
-function decodeOffsetCursor(cursor, print) {
+/** The offset of a cursor this client issued for this request, or `InvalidCursorError`. */
+function decodeOffsetCursor(signer, cursor, print) {
+    // Verified first: nothing in an unsigned or edited token is read.
+    const payload = signer.verify(cursor);
     let decoded;
     try {
-        decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        decoded = JSON.parse(payload);
     }
     catch {
-        throw new InvalidCursorError();
+        throw new InvalidCursorError("malformed_payload");
     }
-    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();
+    if (typeof decoded !== "object" || decoded === null) {
+        throw new InvalidCursorError("malformed_payload");
     }
-    // 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();
+    const { v, o } = decoded;
+    if (v !== CURSOR_VERSION || !isPositiveInteger(o)) {
+        throw new InvalidCursorError("malformed_payload");
+    }
+    if (decoded.f !== print)
+        throw new InvalidCursorError("other_request");
     return o;
 }
 /** `Retry-After` (RFC 9110 §10.2.3) in ms, from delay-seconds or an HTTP date; else undefined. */
@@ -173,7 +181,12 @@ 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;
+    const { fetchImpl: rawFetch = fetch, 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 = configuredUpstreamTimeoutMs(), sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), random = Math.random, now = Date.now, cursorSigner = createCursorSigner(), } = options;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error("paginated upstream: timeoutMs must be a positive number");
+    }
+    // S-13: every page request, whatever fetch it goes through, carries the timeout.
+    const fetchImpl = boundedFetch(rawFetch, timeoutMs);
     if (!Array.isArray(allowedOrigins) || allowedOrigins.length === 0) {
         throw new Error("paginated upstream: allowedOrigins is required and must not be empty");
     }
@@ -224,8 +237,11 @@ export function createPaginatedUpstreamClient(options) {
             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");
+    if (cursorSigner === null ||
+        typeof cursorSigner !== "object" ||
+        typeof cursorSigner.sign !== "function" ||
+        typeof cursorSigner.verify !== "function") {
+        throw new Error("paginated upstream: cursorSigner must be a signer from createCursorSigner");
     }
     /** Resolves the path and refuses, before any network call, an origin not allowed. */
     const resolveUrl = (path) => {
@@ -303,7 +319,9 @@ export function createPaginatedUpstreamClient(options) {
                     body,
                     // A redirect is refused, never followed: the origin check above must stay total.
                     redirect: "error",
-                    signal: AbortSignal.timeout(timeoutMs),
+                    // Explicit at the call so the budget is readable (and statically checkable) here;
+                    // `boundedFetch` above bounds every other path to `fetchImpl` the same way.
+                    signal: upstreamSignal(timeoutMs),
                 });
             }
             catch (err) {
@@ -401,7 +419,7 @@ export function createPaginatedUpstreamClient(options) {
         const url = resolveUrl(path);
         checkParams(params, url.pathname);
         const print = fingerprint(url.pathname + url.search, params);
-        const offset = cursor === undefined ? 0 : decodeOffsetCursor(cursor, print);
+        const offset = cursor === undefined ? 0 : decodeOffsetCursor(cursorSigner, 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);
@@ -415,7 +433,7 @@ export function createPaginatedUpstreamClient(options) {
             page.exhausted = true;
             return page;
         }
-        page.nextCursor = encodeOffsetCursor(offset + rows.length, print);
+        page.nextCursor = encodeOffsetCursor(cursorSigner, offset + rows.length, print);
         return page;
     };
     return { readAll, readPage };

package/dist/upstream/timeout.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one mechanism behind S-13 ("every request the server emits carries a configured timeout").
+ *
+ * CENSUS of outbound call sites in src/ (`rg -n '\bfetch\(|fetchImpl\(|undici|http\.request|https\.request' src`,
+ * plus the one site that hands `fetch` to a library, `ConvexHttpClient`). Each carries an
+ * AbortSignal timeout:
+ *   upstream/paginatedClient.ts  page request (fetchImpl, default global fetch)  boundedFetch, UPSTREAM_TIMEOUT_MS
+ *   upstream/clientCredentials.ts token request                                  boundedFetch, option timeoutMs (10 s)
+ *   upstream/clientCredentials.ts fetchWithToken (API request)                   boundedFetch, UPSTREAM_TIMEOUT_MS
+ *   oauth/clerk.ts               Backend API + JWKS (2 sites)                    per-call + total deadline (own signal)
+ *   oauth/clientRegistry.ts      CIMD metadata fetch                             own signal, option timeoutMs (5 s)
+ *   config.ts                    external-issuer JWKS fetch                      upstreamSignal, UPSTREAM_TIMEOUT_MS
+ *   lake/convex.ts               ConvexHttpClient `fetch` option                 boundedFetch, UPSTREAM_TIMEOUT_MS
+ * src/nodeAdapter.ts and src/httpApp.ts `.fetch(` are the INBOUND handler, not a request emitted.
+ * A new outbound site belongs in this list and uses `boundedFetch` or `upstreamSignal`.
+ */
+/** The configured budget: `UPSTREAM_TIMEOUT_MS`, validated at read (ConfigurationError if bad). */
+export declare function configuredUpstreamTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/** A timeout signal, combined with the caller's own signal when there is one (first to fire wins). */
+export declare function upstreamSignal(timeoutMs: number, callerSignal?: AbortSignal | null): AbortSignal;
+/**
+ * `fetchImpl` such that EVERY call carries the timeout, whatever the caller passed. A caller
+ * signal (in `init`, or on a `Request` input) still applies: the earlier of the two aborts.
+ * The abort surfaces as the fetch's own rejection (`TimeoutError`), for the call site to type.
+ */
+export declare function boundedFetch(fetchImpl: typeof fetch, timeoutMs: number): typeof fetch;

package/dist/upstream/timeout.js

@@ -0,0 +1,37 @@
+/**
+ * The one mechanism behind S-13 ("every request the server emits carries a configured timeout").
+ *
+ * CENSUS of outbound call sites in src/ (`rg -n '\bfetch\(|fetchImpl\(|undici|http\.request|https\.request' src`,
+ * plus the one site that hands `fetch` to a library, `ConvexHttpClient`). Each carries an
+ * AbortSignal timeout:
+ *   upstream/paginatedClient.ts  page request (fetchImpl, default global fetch)  boundedFetch, UPSTREAM_TIMEOUT_MS
+ *   upstream/clientCredentials.ts token request                                  boundedFetch, option timeoutMs (10 s)
+ *   upstream/clientCredentials.ts fetchWithToken (API request)                   boundedFetch, UPSTREAM_TIMEOUT_MS
+ *   oauth/clerk.ts               Backend API + JWKS (2 sites)                    per-call + total deadline (own signal)
+ *   oauth/clientRegistry.ts      CIMD metadata fetch                             own signal, option timeoutMs (5 s)
+ *   config.ts                    external-issuer JWKS fetch                      upstreamSignal, UPSTREAM_TIMEOUT_MS
+ *   lake/convex.ts               ConvexHttpClient `fetch` option                 boundedFetch, UPSTREAM_TIMEOUT_MS
+ * src/nodeAdapter.ts and src/httpApp.ts `.fetch(` are the INBOUND handler, not a request emitted.
+ * A new outbound site belongs in this list and uses `boundedFetch` or `upstreamSignal`.
+ */
+import { UPSTREAM_TIMEOUT_DEFAULT_MS, loadUpstreamSettings } from "../settings.js";
+/** The configured budget: `UPSTREAM_TIMEOUT_MS`, validated at read (ConfigurationError if bad). */
+export function configuredUpstreamTimeoutMs(env = process.env) {
+    return loadUpstreamSettings(env).upstreamTimeoutMs ?? UPSTREAM_TIMEOUT_DEFAULT_MS;
+}
+/** A timeout signal, combined with the caller's own signal when there is one (first to fire wins). */
+export function upstreamSignal(timeoutMs, callerSignal) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return callerSignal ? AbortSignal.any([timeout, callerSignal]) : timeout;
+}
+/**
+ * `fetchImpl` such that EVERY call carries the timeout, whatever the caller passed. A caller
+ * signal (in `init`, or on a `Request` input) still applies: the earlier of the two aborts.
+ * The abort surfaces as the fetch's own rejection (`TimeoutError`), for the call site to type.
+ */
+export function boundedFetch(fetchImpl, timeoutMs) {
+    return ((input, init) => {
+        const caller = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+        return fetchImpl(input, { ...init, signal: upstreamSignal(timeoutMs, caller) });
+    });
+}

package/examples/oauth.env.example

@@ -38,5 +38,12 @@ MCP_OAUTH_SIGNING_JWK=
 # 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
+# Browser origins allowed to call /mcp (S-22; comma-separated, scheme://host[:port]; default none =
+# every request carrying an Origin header is refused 403; no Origin header = not a browser, passes).
+# A wildcard or a path stops the server at start. /register keeps its own list above.
+# MCP_ALLOWED_ORIGINS=https://claude.ai
+# Time budget of one outbound request to an upstream (S-13; integer milliseconds, 1000 to 300000,
+# default 30000). A value that is not an integer or is out of range stops the server at start.
+# UPSTREAM_TIMEOUT_MS=30000
 # Display name shown above the consent page title (default: none).
 # AUTHORIZE_BRAND_NAME=Acme MCP

package/mcp-server.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-boilerplate",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "capabilities": {
     "tools": {},
     "resources": {}
@@ -9,5 +9,6 @@
     "stdio": { "bin": "mcp-boilerplate" },
     "streamableHttp": { "path": "/mcp", "stateless": true }
   },
-  "features": {}
+  "features": {},
+  "contextCeiling": { "global": 1200, "perTool": 700 }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/mcp-boilerplate",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Clonable MCP server skeleton on the official @modelcontextprotocol/server SDK v2 (protocol 2026-07-28 + 2025 legacy, stdio + stateless Streamable HTTP), with its own OAuth 2.1 authorization server (Clerk person + organisation, cloud-identity), MCP Apps UI, tenant scoping, FR/EN i18n and a declarative eval harness.",
   "description_fr": "Squelette de serveur MCP clonable sur le SDK officiel @modelcontextprotocol/server v2 (protocole 2026-07-28 + héritage 2025, stdio + Streamable HTTP sans état), avec son propre serveur d'autorisation OAuth 2.1 (personne + organisation Clerk, cloud-identity), UI MCP Apps, scoping tenant, i18n FR/EN et un harnais d'évaluations déclaratif.",
   "type": "module",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "vantage-mcp-boilerplate",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Clonable MCP server template: SDK v2 on protocol 2026-07-28 (stdio + stateless Streamable HTTP), its own OAuth 2.1 authorization server (Clerk person + organisation), MCP Apps UI, FR/EN i18n and a declarative eval harness. Scaffold, extend, publish.",
   "author": {
     "name": "ElPi Corp / Laurent Perello"