@vantageos/mcp-boilerplate 0.4.0 → 0.5.0

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.4.0",
+  "version": "0.5.0",
   "capabilities": {
     "tools": {},
     "resources": {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/mcp-boilerplate",
-  "version": "0.4.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.4.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"