@vantageos/mcp-boilerplate 0.4.0 → 0.6.0

package/dist/pagination.d.ts

@@ -4,8 +4,11 @@
  * 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;
+ *   - the cursor carries the last key served, so it is stable: rows added or removed elsewhere do
+ *     not shift the next page. It is SIGNED (src/signedCursor.ts: HMAC-SHA256 under a server
+ *     key), so a caller can read it but not edit or mint one: an edited key is `invalid_cursor`.
+ *     The default signer's key is drawn once per process: a restart invalidates outstanding
+ *     cursors, and a multi-instance deployment injects one shared signer (`cursorSigner`);
  *   - 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);
@@ -14,6 +17,8 @@
  *     SEP-1303), not a JSON-RPC error: -32602 stays with the protocol list methods' cursor.
  */
 import { type LakeReader, type LakeScope } from "./lake/reader.js";
+import { type CursorSigner } from "./signedCursor.js";
+export { INVALID_CURSOR_CODE, InvalidCursorError } from "./signedCursor.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).
@@ -22,15 +27,8 @@ 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 declare function encodeCursor(afterKey: string, signer?: CursorSigner): string;
+export declare function decodeCursor(cursor: string, signer?: CursorSigner): string;
 export interface Page<T> {
     items: T[];
     /** Present exactly when the page was truncated. */
@@ -51,16 +49,17 @@ export declare function paginate<T extends {
 }>(sortedRows: readonly T[], request: PageRequest, bounds: {
     default: number;
     max: number;
-}): Page<T>;
+}, signer?: CursorSigner): 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).
+ * the in-memory reader, the result is exactly `paginate`'s (tests/lakeReader.test.ts). `signer`
+ * signs and verifies the cursor; default: the process-wide signer.
  */
 export declare function readPage<Row>(reader: LakeReader<Row>, request: PageRequest, bounds: {
     default: number;
     max: number;
-}, scope?: LakeScope): Promise<Page<Row>>;
+}, scope?: LakeScope, signer?: CursorSigner): Promise<Page<Row>>;

package/dist/pagination.js

@@ -4,8 +4,11 @@
  * 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;
+ *   - the cursor carries the last key served, so it is stable: rows added or removed elsewhere do
+ *     not shift the next page. It is SIGNED (src/signedCursor.ts: HMAC-SHA256 under a server
+ *     key), so a caller can read it but not edit or mint one: an edited key is `invalid_cursor`.
+ *     The default signer's key is drawn once per process: a restart invalidates outstanding
+ *     cursors, and a multi-instance deployment injects one shared signer (`cursorSigner`);
  *   - 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);
@@ -15,7 +18,9 @@
  */
 import { rangeAfter } from "./exampleItems.js";
 import { checkLakePage } from "./lake/reader.js";
+import { InvalidCursorError, createCursorSigner } from "./signedCursor.js";
 import { LIST_ITEMS_ANNOTATIONS } from "./toolRecord.js";
+export { INVALID_CURSOR_CODE, InvalidCursorError } from "./signedCursor.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).
@@ -25,33 +30,30 @@ export const PAGINATION = {
     max: LIST_ITEMS_ANNOTATIONS.paginationMax,
 };
 const CURSOR_VERSION = 1;
-/** The stable machine code of an invalid or expired cursor, in `structuredContent.error.code`. */
-export const INVALID_CURSOR_CODE = "invalid_cursor";
-/** The cursor did not decode to a position in the collection. */
-export class InvalidCursorError extends Error {
-    code = INVALID_CURSOR_CODE;
-    constructor() {
-        super("invalid cursor");
-        this.name = "InvalidCursorError";
-    }
-}
-export function encodeCursor(afterKey) {
-    return Buffer.from(JSON.stringify({ v: CURSOR_VERSION, after: afterKey })).toString("base64url");
+/**
+ * The process-wide signer of tool cursors, used when none is injected. One per process (not per
+ * server): the HTTP transport builds a server per request, and a cursor must outlive the request
+ * that issued it.
+ */
+const DEFAULT_SIGNER = createCursorSigner();
+export function encodeCursor(afterKey, signer = DEFAULT_SIGNER) {
+    return signer.sign(JSON.stringify({ v: CURSOR_VERSION, after: afterKey }));
 }
-export function decodeCursor(cursor) {
+export function decodeCursor(cursor, signer = DEFAULT_SIGNER) {
+    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 ||
         decoded.v !== CURSOR_VERSION ||
         typeof decoded.after !== "string" ||
         decoded.after.length === 0) {
-        throw new InvalidCursorError();
+        throw new InvalidCursorError("malformed_payload");
     }
     return decoded.after;
 }
@@ -60,8 +62,8 @@ export function decodeCursor(cursor) {
  * range (src/exampleItems.ts `rangeAfter`: binary search on the key), so its cost follows the
  * page, not the collection.
  */
-export function paginate(sortedRows, request, bounds) {
-    const afterKey = request.cursor === undefined ? undefined : decodeCursor(request.cursor);
+export function paginate(sortedRows, request, bounds, signer = DEFAULT_SIGNER) {
+    const afterKey = request.cursor === undefined ? undefined : decodeCursor(request.cursor, signer);
     const wanted = request.limit ?? bounds.default;
     const size = Math.max(1, Math.min(Math.floor(wanted), bounds.max));
     // One row more than the page: its existence is what separates truncated from exhausted.
@@ -69,7 +71,7 @@ export function paginate(sortedRows, request, bounds) {
     const items = window.slice(0, size);
     const last = items[items.length - 1];
     if (window.length > size && last) {
-        return { items, nextCursor: encodeCursor(last.id), exhausted: false };
+        return { items, nextCursor: encodeCursor(last.id, signer), exhausted: false };
     }
     return { items, exhausted: true };
 }
@@ -79,10 +81,11 @@ export function paginate(sortedRows, request, bounds) {
  * 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).
+ * the in-memory reader, the result is exactly `paginate`'s (tests/lakeReader.test.ts). `signer`
+ * signs and verifies the cursor; default: the process-wide signer.
  */
-export async function readPage(reader, request, bounds, scope) {
-    const after = request.cursor === undefined ? undefined : decodeCursor(request.cursor);
+export async function readPage(reader, request, bounds, scope, signer = DEFAULT_SIGNER) {
+    const after = request.cursor === undefined ? undefined : decodeCursor(request.cursor, signer);
     const wanted = request.limit ?? bounds.default;
     const limit = Math.max(1, Math.min(Math.floor(wanted), bounds.max));
     const lakeRequest = {
@@ -94,7 +97,7 @@ export async function readPage(reader, request, bounds, scope) {
     const items = [...page.rows];
     const last = items[items.length - 1];
     if (!page.exhausted && last !== undefined) {
-        return { items, nextCursor: encodeCursor(reader.keyOf(last)), exhausted: false };
+        return { items, nextCursor: encodeCursor(reader.keyOf(last), signer), exhausted: false };
     }
     return { items, exhausted: true };
 }

package/dist/settings.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The HTTP transport's operator configuration, declared through the declared-variables mechanism
+ * (src/declaredVariables.ts). Evaluated by the Node entry (src/http.ts) at start.
+ *
+ * `MCP_ALLOWED_ORIGINS` (S-22, MCP Streamable HTTP spec: validate `Origin` to stop DNS rebinding):
+ * the browser origins allowed to call `/mcp`. Data, never a constant. Default: empty, which
+ * refuses every browser origin (a request with no `Origin` header is not a browser and is not
+ * subject to it). A wildcard or an entry with a path is a `ConfigurationError` naming the variable.
+ *
+ * `UPSTREAM_TIMEOUT_MS` (S-13: every request the server emits carries a configured timeout):
+ * the time budget, in milliseconds, of one outbound request to an upstream (API page, API call
+ * through the token source, external-issuer JWKS, lake read). Default 30 000: long enough for a
+ * slow paginated read, short enough that the server answers with a typed error before an MCP
+ * client's own request timeout (commonly 60 s) fires. Range 1 000 to 300 000, enforced at start:
+ * below 1 s every healthy upstream times out, above 5 min a hung upstream pins a worker. An
+ * out-of-range or non-integer value is a `ConfigurationError` naming the variable.
+ */
+export declare const httpVariables: import("./declaredVariables.js").DeclaredVariables<{
+    readonly allowedOrigins: {
+        readonly env: "MCP_ALLOWED_ORIGINS";
+        readonly type: "originList";
+        readonly required: false;
+        readonly default: readonly [];
+        readonly description: {
+            readonly en: "Browser origins allowed to call /mcp (comma-separated, scheme://host[:port]); empty refuses every browser origin";
+            readonly fr: "Origines de navigateur autorisées à appeler /mcp (séparées par des virgules, schéma://hôte[:port]) ; vide refuse toute origine de navigateur";
+        };
+    };
+}>;
+export declare function loadHttpSettings(env?: NodeJS.ProcessEnv): import("./declaredVariables.js").VariablesOf<{
+    readonly allowedOrigins: {
+        readonly env: "MCP_ALLOWED_ORIGINS";
+        readonly type: "originList";
+        readonly required: false;
+        readonly default: readonly [];
+        readonly description: {
+            readonly en: "Browser origins allowed to call /mcp (comma-separated, scheme://host[:port]); empty refuses every browser origin";
+            readonly fr: "Origines de navigateur autorisées à appeler /mcp (séparées par des virgules, schéma://hôte[:port]) ; vide refuse toute origine de navigateur";
+        };
+    };
+}>;
+export declare const UPSTREAM_TIMEOUT_DEFAULT_MS = 30000;
+export declare const UPSTREAM_TIMEOUT_MIN_MS = 1000;
+export declare const UPSTREAM_TIMEOUT_MAX_MS = 300000;
+export declare const upstreamVariables: import("./declaredVariables.js").DeclaredVariables<{
+    readonly upstreamTimeoutMs: {
+        readonly env: "UPSTREAM_TIMEOUT_MS";
+        readonly type: "integer";
+        readonly required: false;
+        readonly min: 1000;
+        readonly max: 300000;
+        readonly default: 30000;
+        readonly description: {
+            readonly en: "Time budget in milliseconds of one outbound request to an upstream (1000 to 300000, default 30000)";
+            readonly fr: "Budget de temps en millisecondes d'une requête sortante vers un amont (1000 à 300000, 30000 par défaut)";
+        };
+    };
+}>;
+export declare function loadUpstreamSettings(env?: NodeJS.ProcessEnv): import("./declaredVariables.js").VariablesOf<{
+    readonly upstreamTimeoutMs: {
+        readonly env: "UPSTREAM_TIMEOUT_MS";
+        readonly type: "integer";
+        readonly required: false;
+        readonly min: 1000;
+        readonly max: 300000;
+        readonly default: 30000;
+        readonly description: {
+            readonly en: "Time budget in milliseconds of one outbound request to an upstream (1000 to 300000, default 30000)";
+            readonly fr: "Budget de temps en millisecondes d'une requête sortante vers un amont (1000 à 300000, 30000 par défaut)";
+        };
+    };
+}>;

package/dist/settings.js

@@ -0,0 +1,53 @@
+/**
+ * The HTTP transport's operator configuration, declared through the declared-variables mechanism
+ * (src/declaredVariables.ts). Evaluated by the Node entry (src/http.ts) at start.
+ *
+ * `MCP_ALLOWED_ORIGINS` (S-22, MCP Streamable HTTP spec: validate `Origin` to stop DNS rebinding):
+ * the browser origins allowed to call `/mcp`. Data, never a constant. Default: empty, which
+ * refuses every browser origin (a request with no `Origin` header is not a browser and is not
+ * subject to it). A wildcard or an entry with a path is a `ConfigurationError` naming the variable.
+ *
+ * `UPSTREAM_TIMEOUT_MS` (S-13: every request the server emits carries a configured timeout):
+ * the time budget, in milliseconds, of one outbound request to an upstream (API page, API call
+ * through the token source, external-issuer JWKS, lake read). Default 30 000: long enough for a
+ * slow paginated read, short enough that the server answers with a typed error before an MCP
+ * client's own request timeout (commonly 60 s) fires. Range 1 000 to 300 000, enforced at start:
+ * below 1 s every healthy upstream times out, above 5 min a hung upstream pins a worker. An
+ * out-of-range or non-integer value is a `ConfigurationError` naming the variable.
+ */
+import { defineVariables, loadVariables } from "./declaredVariables.js";
+export const httpVariables = defineVariables({
+    allowedOrigins: {
+        env: "MCP_ALLOWED_ORIGINS",
+        type: "originList",
+        required: false,
+        default: [],
+        description: {
+            en: "Browser origins allowed to call /mcp (comma-separated, scheme://host[:port]); empty refuses every browser origin",
+            fr: "Origines de navigateur autorisées à appeler /mcp (séparées par des virgules, schéma://hôte[:port]) ; vide refuse toute origine de navigateur",
+        },
+    },
+});
+export function loadHttpSettings(env = process.env) {
+    return loadVariables(httpVariables, env);
+}
+export const UPSTREAM_TIMEOUT_DEFAULT_MS = 30_000;
+export const UPSTREAM_TIMEOUT_MIN_MS = 1_000;
+export const UPSTREAM_TIMEOUT_MAX_MS = 300_000;
+export const upstreamVariables = defineVariables({
+    upstreamTimeoutMs: {
+        env: "UPSTREAM_TIMEOUT_MS",
+        type: "integer",
+        required: false,
+        min: UPSTREAM_TIMEOUT_MIN_MS,
+        max: UPSTREAM_TIMEOUT_MAX_MS,
+        default: UPSTREAM_TIMEOUT_DEFAULT_MS,
+        description: {
+            en: "Time budget in milliseconds of one outbound request to an upstream (1000 to 300000, default 30000)",
+            fr: "Budget de temps en millisecondes d'une requête sortante vers un amont (1000 à 300000, 30000 par défaut)",
+        },
+    },
+});
+export function loadUpstreamSettings(env = process.env) {
+    return loadVariables(upstreamVariables, env);
+}

package/dist/signedCursor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Signed cursors. Every cursor this boilerplate issues (the `list_items` tool cursor in
+ * `src/pagination.ts`, the upstream offset cursor in `src/upstream/paginatedClient.ts`) is a
+ * token `<payload>.<tag>`: the payload is base64url of the cursor's own text, the tag is base64url
+ * of HMAC-SHA256(key, payload part). A caller can read a cursor; it cannot edit one and have it
+ * accepted, because recomputing the tag needs the key.
+ *
+ * `verify` refuses with `InvalidCursorError` (code `invalid_cursor`) and a `reason` naming the
+ * form it met: `empty`, `missing_separator`, `extra_separator`, `empty_part`, `not_base64url`
+ * (a part outside the strict base64url alphabet, or not in its canonical encoding), `tag_length`
+ * (a tag that is not 32 bytes, e.g. truncated) and `tag_mismatch` (an edited payload, or a tag
+ * made under another key). A verified payload the caller cannot read is refused by the caller as
+ * `malformed_payload`, and one issued for another request as `other_request`. There is no unsigned
+ * fallback: a token that does not verify is never read.
+ *
+ * Declared limit. The default key is 32 random bytes drawn once per signer, so per process for
+ * the module-level signers: a process restart invalidates every outstanding cursor (the caller
+ * gets `invalid_cursor` and starts again without one), and two instances behind a load balancer
+ * reject each other's cursors. A multi-instance deployment injects one shared key of at least 32
+ * bytes into every instance (`createCursorSigner({ key })`).
+ */
+/** The stable machine code of an invalid or expired cursor, in `structuredContent.error.code`. */
+export declare const INVALID_CURSOR_CODE = "invalid_cursor";
+/** Why a cursor was refused. Operator-facing: the caller only ever sees `invalid_cursor`. */
+export type InvalidCursorReason = "empty" | "missing_separator" | "extra_separator" | "empty_part" | "not_base64url" | "tag_length" | "tag_mismatch" | "malformed_payload" | "other_request";
+/** The cursor did not decode to a position this server issued. */
+export declare class InvalidCursorError extends Error {
+    readonly code = "invalid_cursor";
+    /** The form the refused token took. */
+    readonly reason: InvalidCursorReason;
+    constructor(reason: InvalidCursorReason);
+}
+/** Minimum (and default) key length, in bytes: the HMAC-SHA256 output size. */
+export declare const CURSOR_KEY_BYTES = 32;
+export interface CursorSigner {
+    /** Returns `<base64url payload>.<base64url tag>`. */
+    sign(payload: string): string;
+    /** Returns the payload `sign` was given, or throws `InvalidCursorError`. */
+    verify(token: string): string;
+}
+export interface CursorSignerOptions {
+    /**
+     * The HMAC key, at least 32 bytes. Default: 32 random bytes, drawn once for this signer. Inject
+     * the same key into every instance of a multi-instance deployment.
+     */
+    key?: Uint8Array;
+}
+export declare function createCursorSigner(options?: CursorSignerOptions): CursorSigner;

package/dist/signedCursor.js

@@ -0,0 +1,98 @@
+/**
+ * Signed cursors. Every cursor this boilerplate issues (the `list_items` tool cursor in
+ * `src/pagination.ts`, the upstream offset cursor in `src/upstream/paginatedClient.ts`) is a
+ * token `<payload>.<tag>`: the payload is base64url of the cursor's own text, the tag is base64url
+ * of HMAC-SHA256(key, payload part). A caller can read a cursor; it cannot edit one and have it
+ * accepted, because recomputing the tag needs the key.
+ *
+ * `verify` refuses with `InvalidCursorError` (code `invalid_cursor`) and a `reason` naming the
+ * form it met: `empty`, `missing_separator`, `extra_separator`, `empty_part`, `not_base64url`
+ * (a part outside the strict base64url alphabet, or not in its canonical encoding), `tag_length`
+ * (a tag that is not 32 bytes, e.g. truncated) and `tag_mismatch` (an edited payload, or a tag
+ * made under another key). A verified payload the caller cannot read is refused by the caller as
+ * `malformed_payload`, and one issued for another request as `other_request`. There is no unsigned
+ * fallback: a token that does not verify is never read.
+ *
+ * Declared limit. The default key is 32 random bytes drawn once per signer, so per process for
+ * the module-level signers: a process restart invalidates every outstanding cursor (the caller
+ * gets `invalid_cursor` and starts again without one), and two instances behind a load balancer
+ * reject each other's cursors. A multi-instance deployment injects one shared key of at least 32
+ * bytes into every instance (`createCursorSigner({ key })`).
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+/** The stable machine code of an invalid or expired cursor, in `structuredContent.error.code`. */
+export const INVALID_CURSOR_CODE = "invalid_cursor";
+/** The cursor did not decode to a position this server issued. */
+export class InvalidCursorError extends Error {
+    code = INVALID_CURSOR_CODE;
+    /** The form the refused token took. */
+    reason;
+    constructor(reason) {
+        super("invalid cursor");
+        this.name = "InvalidCursorError";
+        this.reason = reason;
+    }
+}
+/** Minimum (and default) key length, in bytes: the HMAC-SHA256 output size. */
+export const CURSOR_KEY_BYTES = 32;
+const TAG_BYTES = 32;
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+/** Strict base64url: the alphabet only, and the canonical encoding of what it decodes to. */
+function decodeStrict(part) {
+    if (!BASE64URL.test(part))
+        throw new InvalidCursorError("not_base64url");
+    const bytes = Buffer.from(part, "base64url");
+    if (bytes.toString("base64url") !== part)
+        throw new InvalidCursorError("not_base64url");
+    return bytes;
+}
+export function createCursorSigner(options = {}) {
+    const supplied = options.key;
+    if (supplied !== undefined && !(supplied instanceof Uint8Array)) {
+        throw new Error(`cursor signer: key must be a Uint8Array of at least ${CURSOR_KEY_BYTES} bytes`);
+    }
+    if (supplied !== undefined && supplied.length < CURSOR_KEY_BYTES) {
+        throw new Error(`cursor signer: key must be at least ${CURSOR_KEY_BYTES} bytes (got ${supplied.length})`);
+    }
+    // A copy: the caller zeroing or reusing its buffer must not change what this signer accepts.
+    const key = supplied === undefined ? randomBytes(CURSOR_KEY_BYTES) : Buffer.from(supplied);
+    const tagOf = (payloadPart) => createHmac("sha256", key).update(payloadPart).digest();
+    const sign = (payload) => {
+        // A cursor always says something; an empty one would encode to an empty part, which `verify`
+        // refuses. Refused here, loudly, rather than issued and then rejected.
+        if (typeof payload !== "string" || payload.length === 0) {
+            throw new Error("cursor signer: the payload to sign must be a non-empty string");
+        }
+        const payloadPart = Buffer.from(payload, "utf8").toString("base64url");
+        return `${payloadPart}.${tagOf(payloadPart).toString("base64url")}`;
+    };
+    const verify = (token) => {
+        if (typeof token !== "string" || token.length === 0)
+            throw new InvalidCursorError("empty");
+        const parts = token.split(".");
+        if (parts.length < 2)
+            throw new InvalidCursorError("missing_separator");
+        if (parts.length > 2)
+            throw new InvalidCursorError("extra_separator");
+        const [payloadPart, tagPart] = parts;
+        if (payloadPart.length === 0 || tagPart.length === 0)
+            throw new InvalidCursorError("empty_part");
+        if (!BASE64URL.test(tagPart))
+            throw new InvalidCursorError("not_base64url");
+        // Length before canonical form, so a truncated tag is named as such.
+        const tag = Buffer.from(tagPart, "base64url");
+        if (tag.length !== TAG_BYTES)
+            throw new InvalidCursorError("tag_length");
+        if (tag.toString("base64url") !== tagPart)
+            throw new InvalidCursorError("not_base64url");
+        // The payload is checked for its alphabet before the tag; its content is trusted only once
+        // the tag matches. Equal lengths (32 bytes each, checked above): timingSafeEqual cannot throw.
+        if (!BASE64URL.test(payloadPart))
+            throw new InvalidCursorError("not_base64url");
+        if (!timingSafeEqual(tagOf(payloadPart), tag))
+            throw new InvalidCursorError("tag_mismatch");
+        // Signed by us, so canonical; re-checked so a decode is never lenient.
+        return decodeStrict(payloadPart).toString("utf8");
+    };
+    return { sign, verify };
+}

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 {