@vantageos/mcp-boilerplate 0.6.3 → 0.7.0

package/dist/locales/fr.json

@@ -12,6 +12,9 @@
       "noVerifiedSession": "permission refusée : cet outil exige la personne vérifiée, et cet appel ne porte aucune session vérifiée",
       "refused": "permission refusée : la personne vérifiée derrière cet appel n'a pas pu être résolue"
     },
+    "rateLimit": {
+      "exceeded": "trop d’appels d’outils : réessayez dans {seconds} s"
+    },
     "validation": {
       "messageTooLong": "le message dépasse la longueur maximale de 200 caractères"
     },
@@ -42,9 +45,17 @@
         "object": "un objet",
         "boolean": "true ou false",
         "positiveInteger": "un entier strictement positif",
-        "atLeastPerTool": "au moins le plafond perTool"
+        "atLeastPerTool": "au moins le plafond perTool",
+        "stringArray": "un tableau de chaînes non vides"
       }
     },
+    "toolRoles": {
+      "identityMissing": "les stores d'identité ne sont pas injectés (AppDeps.identity) : sur le niveau OAuth, le rôle d'un appelant est décidé pour l'organisation que la couche d'identité résout, les deux sont donc requis",
+      "denied": "permission refusée : votre rôle n'accorde pas l'outil {tool} ({reason})",
+      "unresolved": "permission refusée : votre rôle n'a pas pu être lu, aucun outil n'est accordé",
+      "configMissing": "{variable} n'est pas défini : sur le niveau OAuth, chaque outil est décidé par le rôle de l'appelant, lu dans ce fichier de rôles",
+      "configInvalid": "{variable} ({path}) n'est pas un fichier de rôles valide : {problem}"
+    },
     "toolRecord": {
       "unsound": "fiches d'outils ou plafond de contexte invalides : {problems}"
     },

package/dist/mcpServerFactory.d.ts

@@ -32,8 +32,10 @@ import { McpServer } from "@modelcontextprotocol/server";
 import type { ExampleItem } from "./exampleItems.js";
 import { type McpLocale } from "./i18n.js";
 import { type LakeReader } from "./lake/reader.js";
+import { type RateLimiter } from "./rateLimit.js";
 import type { CursorSigner } from "./signedCursor.js";
 import { type ResolvedTenant } from "./tenancy.js";
+import { type ToolRolesContext } from "./toolRoleGate.js";
 import type { CallerResolution } from "./verifiedPerson.js";
 /** Oldest 2025-era protocol revision served; the legacy `initialize` handshake never offers older. */
 export declare const SUPPORTED_LEGACY_PROTOCOL_VERSIONS: string[];
@@ -64,9 +66,11 @@ export interface McpServerDeps {
      * httpApp.ts). Defaults to "en"; the stdio transport (no HTTP headers) uses the default.
      */
     locale?: McpLocale;
+    /** The tool invocation limiter (S-24); default the process-wide `toolRateLimiter`. A test injects its own. */
+    rateLimiter?: RateLimiter;
     /**
-     * Dedicated sandbox origin for the MCP Apps widget (`_meta.ui.domain`). Host-dependent; set
-     * only when the deployment has one (MCP_UI_DOMAIN). Omitted from the resource when unset.
+     * Dedicated sandbox origin for the MCP Apps widget (`_meta.ui.domain`), derived from the served MCP URL by
+     * `claudeSandboxDomain` (src/ui/sandboxDomain.ts, A-11). Omitted from the resource when there is no served URL.
      */
     uiDomain?: string;
     /**
@@ -75,6 +79,11 @@ export interface McpServerDeps {
      * before. A derived server injects its own (e.g. `@vantageos/mcp-boilerplate/lake/convex`).
      */
     lake?: LakeReader<ExampleItem>;
+    /**
+     * Agent tool roles for this request (src/toolRoleGate.ts): on the OAuth tier, the caller's role lookup and member
+     * scope, resolved by httpApp before the server is built; elsewhere `{ applicable: false }`. Default: not applicable.
+     */
+    toolRoles?: ToolRolesContext;
     /**
      * Signs and verifies the `list_items` cursor (src/signedCursor.ts). Default: the process-wide
      * signer of src/pagination.ts, whose key is random per process. A multi-instance deployment

package/dist/mcpServerFactory.js

@@ -34,16 +34,21 @@ import { z } from "zod";
 import { getBuildIdentity } from "./buildIdentity.js";
 import { t } from "./i18n.js";
 import { EXAMPLE_ITEMS_READER, LAKE_UNREADABLE_CODE, LakeReadError, } from "./lake/reader.js";
+import { rejectCursorOnSinglePageLists } from "./listCursor.js";
 import { INVALID_CURSOR_CODE, InvalidCursorError, PAGINATION, readPage } from "./pagination.js";
+import { RATE_LIMITED_CODE, toolRateLimiter } from "./rateLimit.js";
 import { trackToolRecords } from "./servedToolRecords.js";
 import { loadServerManifest } from "./serverManifest.js";
 import { scopeRowsForTenant } from "./tenancy.js";
-import { LIST_ITEMS_ANNOTATIONS, PING_ANNOTATIONS } from "./toolRecord.js";
+import { LIST_ITEMS_ANNOTATIONS, PING_ANNOTATIONS, WHOAMI_ANNOTATIONS } from "./toolRecord.js";
+import { grantedToolNames, installToolRoleGate } from "./toolRoleGate.js";
 import { ITEMS_TOOL_META, ITEMS_UI_RESOURCE_URI, buildItemsUiResourceMeta, buildListItemsResult, buildUiResource, } from "./ui/uiResource.js";
 import { SERVER_NAME, SERVER_VERSION } from "./version.js";
 /** Oldest 2025-era protocol revision served; the legacy `initialize` handshake never offers older. */
 export const SUPPORTED_LEGACY_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18"];
-const itemSchema = z.object({
+// S-44: output objects stay open (z.looseObject): a field added in a later release must not fail a client that
+// validated against the schema it read at connect time.
+const itemSchema = z.looseObject({
     id: z.string(),
     name: z.string(),
     orgId: z.string(),
@@ -54,7 +59,21 @@ const localeSchema = z.enum(["en", "fr"]);
 const pingInput = z.object({
     message: z.string().optional().describe("Optional message echoed back verbatim"),
 });
-const pingOutput = z.object({ reply: z.string() });
+const pingOutput = z.looseObject({ reply: z.string() });
+/** The identity tool takes no argument (C-33): the identity never arrives as an argument. */
+const whoamiInput = z.object({});
+const whoamiOutput = z.looseObject({
+    /** The verified subject behind the credentials; null where there is no caller (public HTTP, stdio). */
+    id: z.string().nullable(),
+    /** The caller's role, or null: no role, or roles not applicable. */
+    role: z.looseObject({ id: z.string(), name: z.string() }).nullable(),
+    /** The tools the caller's role grants, by the same decision as tools/list. */
+    grantedTools: z.array(z.string()),
+    /** False on the public HTTP tier and stdio: there is no caller, so no role is decided. */
+    rolesApplicable: z.boolean(),
+});
+/** The identity tool, outside the role gate (rule 6). */
+const IDENTITY_TOOL = "whoami";
 // Pagination (C-11): the bounds are declared in src/toolRecord.ts and applied in
 // src/pagination.ts; the schema only describes them to the caller.
 const pageInput = {
@@ -66,7 +85,8 @@ const pageInput = {
         .number()
         .int()
         .min(1)
-        .optional()
+        // Served in the inputSchema (C-11): the default is declared where a caller reads it, not only applied.
+        .default(PAGINATION.default)
         .describe(`Page size; default ${PAGINATION.default}, capped at ${PAGINATION.max}`),
 };
 const pageOutput = {
@@ -79,7 +99,7 @@ const listItemsInput = z.object({
         .describe("Widget and fallback language; defaults to the caller's X-MCP-Locale"),
     ...pageInput,
 });
-const listItemsOutput = z.object({
+const listItemsOutput = z.looseObject({
     items: z.array(itemSchema),
     locale: localeSchema,
     ...pageOutput,
@@ -121,26 +141,51 @@ export function createBoilerplateMcpServer(deps = {}) {
         },
     });
     const served = trackToolRecords(server);
+    // Agent tool roles: every tool registered below is gated (call refused) and the list filtered, both by the same
+    // decision; the identity tool is the one exemption.
+    const roles = deps.toolRoles ?? { applicable: false };
+    const gate = installToolRoleGate(server, roles, locale, new Set([IDENTITY_TOOL]));
+    // S-24: every tool invocation takes a token from the caller's bucket (keyed by the resolved organisation, or
+    // "public" on the unscoped tier); an empty bucket is a tool error with a stable code and the wait, never a silent drop.
+    const limiter = deps.rateLimiter ?? toolRateLimiter;
+    const rateKey = deps.tenant?.tenantId ?? "public";
+    const withRateLimit = (handler) => async (args) => {
+        const d = limiter.consume(rateKey);
+        if (d.ok)
+            return handler(args);
+        const message = t(locale, "rateLimit.exceeded").replace("{seconds}", () => String(Math.ceil(d.retryAfterMs / 1000)));
+        return {
+            content: [{ type: "text", text: message }],
+            structuredContent: {
+                error: { code: RATE_LIMITED_CODE, retryAfterMs: d.retryAfterMs, message },
+            },
+            isError: true,
+        };
+    };
     server.registerTool("ping", {
         title: "Ping",
-        description: "Echoes the given message (or 'pong' if none given). Proves the MCP handshake end to end.",
+        // C-19: served in both languages in the one description field ("<en> / <fr>"), with its trigger phrase.
+        description: "Echoes the given message (or 'pong' if none given) and proves the MCP handshake end to end. " +
+            "Use this whenever you need to check that this server answers, even if they don't say 'ping'. / " +
+            "Renvoie le message donné (ou 'pong' sans message) et prouve la poignée de main MCP de bout en bout. " +
+            "À utiliser pour vérifier que ce serveur répond, même sans le mot 'ping'.",
         inputSchema: pingInput,
         outputSchema: pingOutput,
         annotations: PING_ANNOTATIONS,
-    }, async (args) => {
+    }, withRateLimit(async (args) => {
         // Application-level input validation beyond the Zod shape: an overly long echo message
         // is refused as an MCP tool-call error, localized per the caller's X-MCP-Locale.
         if (args.message !== undefined && args.message.length > 200) {
             return refusal(t(locale, "validation.messageTooLong"));
         }
         return structuredResult({ reply: args.message ?? "pong" });
-    });
+    }));
     const lake = deps.lake ?? EXAMPLE_ITEMS_READER;
     // An invalid or expired cursor is a TOOL INPUT error (spec 2025-11-25, SEP-1303: input
     // validation errors are Tool Execution Errors, not Protocol Errors): a result with
     // `isError: true` whose structuredContent carries a STABLE machine code beside a message
     // localized per X-MCP-Locale. It is never a silent first page. (-32602 stays with the protocol
-    // list methods' cursor, which the SDK serves.)
+    // list methods' cursor: src/listCursor.ts refuses it there, since the SDK ignores it.)
     const invalidCursor = () => {
         const message = t(locale, "pagination.invalidCursor");
         return {
@@ -166,10 +211,15 @@ export function createBoilerplateMcpServer(deps = {}) {
     // MCP Apps (mcp-app-standard A-1). The widget renders THIS result.
     server.registerTool("list_items", {
         title: "List items",
-        description: "Lists example items, one page at a time, and shows them as an interactive widget in " +
-            "hosts that support MCP Apps. Use this whenever the user asks to list, see or render " +
-            "the items. On the OAuth tier, results are scoped to the caller's organisation " +
-            "(@vantageos/cloud-identity); on the public tier (no auth gate), results are unscoped.",
+        // C-19: served in both languages in the one description field ("<en> / <fr>"), with its trigger phrase.
+        description: "Lists example items, one page at a time, and shows them as an interactive widget in hosts that " +
+            "support MCP Apps. Use this whenever the user asks to list, see or render the items, even if they " +
+            "don't say 'list'. On the OAuth tier, results are scoped to the caller's organisation; on the public " +
+            "tier (no auth gate), they are unscoped. / " +
+            "Liste les éléments d'exemple, une page à la fois, et les affiche en widget interactif dans les hôtes " +
+            "MCP Apps. À utiliser quand l'utilisateur demande de lister, voir ou afficher les éléments, même sans " +
+            "le mot 'lister'. Sur le niveau OAuth, les résultats sont limités à l'organisation de l'appelant ; sur " +
+            "le niveau public (sans authentification), ils ne le sont pas.",
         inputSchema: listItemsInput,
         outputSchema: listItemsOutput,
         annotations: LIST_ITEMS_ANNOTATIONS,
@@ -178,7 +228,7 @@ export function createBoilerplateMcpServer(deps = {}) {
             ...ITEMS_TOOL_META,
             description_fr: "Liste les éléments d'exemple, une page à la fois, et les affiche en widget interactif dans les hôtes MCP Apps. Utilise cet outil quand l'utilisateur demande de lister, voir ou afficher les éléments.",
         },
-    }, async (args) => {
+    }, withRateLimit(async (args) => {
         if (deps.requireTenant && !deps.tenant) {
             // Refuse explicitly — never fall through to an unscoped/master view just because the
             // caller's token had no organization.
@@ -202,7 +252,7 @@ export function createBoilerplateMcpServer(deps = {}) {
                 return lakeUnreadable(error.code);
             throw error;
         }
-    });
+    }));
     // MCP Apps UI layer (io.modelcontextprotocol/ui, spec 2026-01-26). `list_items` is registered
     // with `server.registerTool` and the GA nested `_meta.ui` form, NOT with ext-apps'
     // `registerAppTool`: that helper back-fills the deprecated flat `_meta["ui/resourceUri"]`
@@ -218,6 +268,38 @@ export function createBoilerplateMcpServer(deps = {}) {
     }, async () => ({
         contents: [buildUiResource({ domain: deps.uiDomain })],
     }));
+    server.registerTool(IDENTITY_TOOL, {
+        title: "Who am I",
+        // C-19: both languages in the one served field ("<en> / <fr>") with its trigger phrase; no separate
+        // `_meta.description_fr`, which would only repeat the French half.
+        description: "Returns who you are to this server: your verified subject, the role your tools are decided by, " +
+            "and the tools it grants. Use this whenever you need to know what you may call, even if they don't " +
+            "say 'whoami'. / Renvoie qui vous êtes pour ce serveur : sujet vérifié, rôle qui décide de vos " +
+            "outils, outils accordés. À utiliser pour savoir ce que vous pouvez appeler, même sans le mot 'whoami'.",
+        inputSchema: whoamiInput,
+        outputSchema: whoamiOutput,
+        annotations: WHOAMI_ANNOTATIONS,
+    }, withRateLimit(async () => {
+        const person = deps.caller?.ok ? deps.caller.person : undefined;
+        const lookup = roles.applicable ? roles.lookup : undefined;
+        const role = lookup?.status === "resolved" && roles.applicable
+            ? {
+                id: lookup.role.roleId,
+                name: roles.roleName(lookup.role.roleId) ?? lookup.role.roleId,
+            }
+            : null;
+        return structuredResult({
+            id: person?.subject ?? null,
+            role,
+            grantedTools: grantedToolNames(roles, gate.declarations),
+            rolesApplicable: roles.applicable,
+        });
+    }));
+    // tools/list narrowed to the granted tools (and the identity tool), once every tool is registered.
+    gate.filterList();
+    // C-11 (a): a cursor sent to a single-page protocol list method is -32602 (src/listCursor.ts). Installed after the
+    // role filter, so it wraps it: the cursor is refused before any list is built (tests/toolRoles.test.ts).
+    rejectCursorOnSinglePageLists(server);
     // Start refusal: every registered tool's record, as registered, must be sound.
     served.assertServed(manifest.contextCeiling);
     return server;

package/dist/oauth/authorizationServer.js

@@ -20,13 +20,15 @@
  * FAIL-CLOSED: any missing configuration value answers 503 `temporarily_unavailable`.
  * No refresh tokens are issued; access tokens live one hour.
  */
-import { buildDiscoveryDocument, buildUserInfo, exchangeAuthorizationCode, oauthErrorFor, resolveClerkSessionFromRequest, resumeAuthorize, startAuthorize, } from "@vantageos/cloud-identity";
+import { buildDiscoveryDocument, buildUserInfo, exchangeAuthorizationCode, oauthErrorFor, resolveClerkSessionFromRequest, resumeAuthorize, startAuthorize, verifyMcpAccessToken, } from "@vantageos/cloud-identity";
+// The private_key_jwt client-assertion verifier lives in the identity layer (DLocalIdentity), as a subpath: it uses
+// node:net / node:dns for its SSRF guard, which the root entry stays free of.
+import { ASSERTION_SIGNING_ALGS, createClientAssertionVerifier, } from "@vantageos/cloud-identity/client-assertion";
 import { getCookie } from "hono/cookie";
 import { cors } from "hono/cors";
 import { flagKnob, integerKnob, originListKnob } from "../envKnobs.js";
 import { detectLocale, detectLocaleFromAcceptLanguage, t } from "../i18n.js";
 import { createClerkBackendCollaborators } from "./clerk.js";
-import { ASSERTION_SIGNING_ALGS, createClientAssertionVerifier } from "./clientAssertion.js";
 import { RegistryFullError, createInMemoryClientRegistry, isAllowedRedirectUri, isUrlShapedClientId, resolveCimdClient, } from "./clientRegistry.js";
 import { createInMemoryCodeStore } from "./codeStore.js";
 import { HANDOFF_CSP, pickerContentSecurityPolicy, renderHandoff, renderOrgPicker, } from "./picker.js";
@@ -36,6 +38,8 @@ import { ACCESS_TOKEN_TTL_SECONDS, createTokenIssuer } from "./tokenIssuer.js";
 const REGISTER_LIMIT_PER_MINUTE = 20;
 /** Default of OAUTH_ENV.registerLimitPer48: five /64 budgets for a whole /48. */
 const REGISTER_LIMIT_PER_48_PER_MINUTE = 100;
+/** Default of OAUTH_ENV.tokenLimitPerMinute: /token requests per client address per minute. */
+const TOKEN_LIMIT_PER_MINUTE = 60;
 const MAX_REDIRECT_URIS = 10;
 const REGISTRY_FULL_RETRY_AFTER_SECONDS = 300;
 function noStore(c) {
@@ -89,6 +93,7 @@ export function createAuthorizationServer(deps = {}) {
     // Operator knobs are validated here, at construction: a bad value stops the boot.
     const trustedProxyCount = integerKnob(env, OAUTH_ENV.trustedProxyCount, 0, 10) ?? 0;
     const registerLimitPer48 = integerKnob(env, OAUTH_ENV.registerLimitPer48, 1) ?? REGISTER_LIMIT_PER_48_PER_MINUTE;
+    const tokenLimitPerMinute = integerKnob(env, OAUTH_ENV.tokenLimitPerMinute, 1) ?? TOKEN_LIMIT_PER_MINUTE;
     const registerOrigins = originListKnob(env, OAUTH_ENV.registerCorsOrigins);
     const allowInMemory = flagKnob(env, OAUTH_ENV.allowInMemoryStores) === true;
     const now = deps.now ?? (() => Date.now());
@@ -270,6 +275,14 @@ export function createAuthorizationServer(deps = {}) {
         prefix48LimitPerMinute: registerLimitPer48,
         now,
     });
+    // /token is unauthenticated until the client is verified, and each private_key_jwt assertion it verifies occupies a
+    // single-use jti slot until it expires: an unbounded caller could fill the jti store. The same address-keyed
+    // limiter as /register (an IPv6 client on its /64, and its /48 at five budgets) bounds every caller.
+    const tokenLimiter = createRegisterLimiter({
+        limitPerMinute: tokenLimitPerMinute,
+        prefix48LimitPerMinute: tokenLimitPerMinute * 5,
+        now,
+    });
     return {
         async resourceServer() {
             const result = await settingsNow();
@@ -513,6 +526,10 @@ export function createAuthorizationServer(deps = {}) {
                 return respond(c, outcome, result.settings);
             });
             app.post("/token", async (c) => {
+                if (!tokenLimiter.allow(clientKeyOf(c, trustedProxyCount))) {
+                    c.header("Retry-After", "60");
+                    return c.json({ error: "too_many_requests" }, 429);
+                }
                 const result = await settingsNow();
                 if (!result.ok)
                     return unavailable(c, result.missing);
@@ -590,22 +607,26 @@ export function createAuthorizationServer(deps = {}) {
                 const result = await settingsNow();
                 if (!result.ok)
                     return unavailable(c, result.missing);
-                const header = c.req.header("authorization") ?? "";
-                const token = header.toLowerCase().startsWith("bearer ") ? header.slice(7).trim() : "";
                 const invalid = () => {
                     c.header("WWW-Authenticate", 'Bearer error="invalid_token"');
                     return c.json({ error: "invalid_token" }, 401);
                 };
-                if (!token)
-                    return invalid();
+                // Our own access token is verified by the identity layer, never here (DLocalIdentity):
+                // issuer = this server, audience = the protected resource, key set = our published JWKS.
                 const issuer = await issuerFor(result.settings);
-                let claims;
-                try {
-                    claims = await issuer.verify(token, result.settings.baseUrl, result.settings.resource);
-                }
-                catch {
+                const verified = await verifyMcpAccessToken(c.req.header("authorization"), {
+                    realm: "mcp",
+                    resourceMetadataUrl: `${result.settings.baseUrl}/.well-known/oauth-protected-resource`,
+                    issuer: result.settings.baseUrl,
+                    audience: result.settings.resource,
+                    jwks: issuer.jwks,
+                }, now());
+                if (!verified.ok)
                     return invalid();
-                }
+                const claims = {
+                    sub: verified.session.userId,
+                    scope: String(verified.session.claims.scope ?? ""),
+                };
                 let user;
                 try {
                     user = await clerkFor().getUser(claims.sub);

package/dist/oauth/picker.js

@@ -92,6 +92,7 @@ function formActionSources(redirectUris) {
  */
 export async function pickerContentSecurityPolicy(redirectUris) {
     const formAction = ["'self'", ...formActionSources(redirectUris)].join(" ");
+    // allow-local-identity: CSP hash of the picker's own constant stylesheet; no credential, caller or tenant
     const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(PICKER_STYLE));
     const hash = btoa(String.fromCharCode(...new Uint8Array(digest)));
     return [

package/dist/oauth/settings.d.ts

@@ -18,6 +18,8 @@ export declare const OAUTH_ENV: {
     readonly trustedProxyCount: "MCP_TRUSTED_PROXY_COUNT";
     /** /register budget shared by every /64 inside one IPv6 /48, per minute (default 100). */
     readonly registerLimitPer48: "MCP_REGISTER_LIMIT_PER_48_PER_MINUTE";
+    /** /token requests per client address per minute (default 60); its /48 gets five times that. */
+    readonly tokenLimitPerMinute: "MCP_TOKEN_LIMIT_PER_MINUTE";
     /** Comma-separated browser origins allowed to call /register cross-origin (default: none). */
     readonly registerCorsOrigins: "MCP_REGISTER_CORS_ORIGINS";
     /** Exactly "1" lets NODE_ENV=production run on the in-memory stores (single instance only). */

package/dist/oauth/settings.js

@@ -18,6 +18,8 @@ export const OAUTH_ENV = {
     trustedProxyCount: "MCP_TRUSTED_PROXY_COUNT",
     /** /register budget shared by every /64 inside one IPv6 /48, per minute (default 100). */
     registerLimitPer48: "MCP_REGISTER_LIMIT_PER_48_PER_MINUTE",
+    /** /token requests per client address per minute (default 60); its /48 gets five times that. */
+    tokenLimitPerMinute: "MCP_TOKEN_LIMIT_PER_MINUTE",
     /** Comma-separated browser origins allowed to call /register cross-origin (default: none). */
     registerCorsOrigins: "MCP_REGISTER_CORS_ORIGINS",
     /** Exactly "1" lets NODE_ENV=production run on the in-memory stores (single instance only). */

package/dist/oauth/tokenIssuer.d.ts

@@ -15,7 +15,6 @@ export interface TokenIssuer {
         keys: JWK[];
     };
     sign(claims: AuthorizedTokenClaims, issuer: string, nowMs: number): Promise<string>;
-    verify(token: string, issuer: string, audience: string): Promise<AuthorizedTokenClaims>;
 }
 export declare function createTokenIssuer(privateJwk: JWK & {
     kid: string;

package/dist/oauth/tokenIssuer.js

@@ -4,7 +4,7 @@
  * deployment's key. The resource server (@vantageos/cloud-identity `verifyMcpAccessToken`)
  * verifies the result against the public half published at /.well-known/jwks.json.
  */
-import { SignJWT, createLocalJWKSet, importJWK, jwtVerify } from "jose";
+import { SignJWT, importJWK } from "jose";
 export const ACCESS_TOKEN_TTL_SECONDS = 3600;
 export async function createTokenIssuer(privateJwk) {
     const key = await importJWK(privateJwk, "RS256");
@@ -18,7 +18,6 @@ export async function createTokenIssuer(privateJwk) {
         use: "sig",
     };
     const jwks = { keys: [publicJwk] };
-    const verifyKey = createLocalJWKSet(jwks);
     return {
         kid: privateJwk.kid,
         publicJwk,
@@ -41,21 +40,5 @@ export async function createTokenIssuer(privateJwk) {
                 .setJti(crypto.randomUUID())
                 .sign(key);
         },
-        async verify(token, issuer, audience) {
-            const { payload } = await jwtVerify(token, verifyKey, {
-                issuer,
-                audience,
-                algorithms: ["RS256"],
-            });
-            return {
-                sub: String(payload.sub),
-                org_id: String(payload.org_id),
-                org_slug: payload.org_slug ?? null,
-                org_role: String(payload.org_role),
-                aud: audience,
-                client_id: String(payload.client_id),
-                scope: String(payload.scope),
-            };
-        },
     };
 }

package/dist/pagination.d.ts

@@ -14,7 +14,8 @@
  *     fit is exhausted, never a false truncation);
  *   - an invalid or expired cursor is refused with the stable code `invalid_cursor`, never read as
  *     "page one". It is a TOOL INPUT error (a result with `isError: true`, spec 2025-11-25
- *     SEP-1303), not a JSON-RPC error: -32602 stays with the protocol list methods' cursor.
+ *     SEP-1303), not a JSON-RPC error: -32602 stays with the protocol list methods' cursor
+ *     (src/listCursor.ts).
  */
 import { type LakeReader, type LakeScope } from "./lake/reader.js";
 import { type CursorSigner } from "./signedCursor.js";

package/dist/pagination.js

@@ -14,7 +14,8 @@
  *     fit is exhausted, never a false truncation);
  *   - an invalid or expired cursor is refused with the stable code `invalid_cursor`, never read as
  *     "page one". It is a TOOL INPUT error (a result with `isError: true`, spec 2025-11-25
- *     SEP-1303), not a JSON-RPC error: -32602 stays with the protocol list methods' cursor.
+ *     SEP-1303), not a JSON-RPC error: -32602 stays with the protocol list methods' cursor
+ *     (src/listCursor.ts).
  */
 import { rangeAfter } from "./exampleItems.js";
 import { checkLakePage } from "./lake/reader.js";

package/dist/rateLimit.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tool invocation rate limiting (mcp-server-standard S-24: every published tool applies rate limiting to its
+ * invocation, a MUST at the rank of input validation). A token bucket per caller: `capacity` calls may burst, then
+ * the bucket refills at `perMinute`. The buckets live for the process, not for one request: the HTTP tier builds a
+ * server per request, so a per-server bucket would never fill.
+ *
+ * Configuration (environment, read once at start): TOOL_RATE_LIMIT_PER_MINUTE (default 60) and TOOL_RATE_LIMIT_BURST
+ * (default 30). A value that is not a positive integer refuses the start, naming the variable.
+ */
+export type RateDecision = {
+    ok: true;
+} | {
+    ok: false;
+    retryAfterMs: number;
+};
+export interface RateLimiter {
+    /** Takes one token from `key`'s bucket, or says how long until one is available. */
+    consume(key: string): RateDecision;
+}
+export declare function createTokenBucketLimiter(opts: {
+    capacity: number;
+    perMinute: number;
+    now?: () => number;
+}): RateLimiter;
+/** The limits read from the environment. */
+export declare function loadToolRateLimit(env?: NodeJS.ProcessEnv): {
+    capacity: number;
+    perMinute: number;
+};
+/** The process-wide limiter every tool invocation goes through, unless a test injects its own. */
+export declare const toolRateLimiter: RateLimiter;
+/** The stable machine code of a refused invocation (beside a message localized per X-MCP-Locale). */
+export declare const RATE_LIMITED_CODE = "rate_limited";

package/dist/rateLimit.js

@@ -0,0 +1,48 @@
+/**
+ * Tool invocation rate limiting (mcp-server-standard S-24: every published tool applies rate limiting to its
+ * invocation, a MUST at the rank of input validation). A token bucket per caller: `capacity` calls may burst, then
+ * the bucket refills at `perMinute`. The buckets live for the process, not for one request: the HTTP tier builds a
+ * server per request, so a per-server bucket would never fill.
+ *
+ * Configuration (environment, read once at start): TOOL_RATE_LIMIT_PER_MINUTE (default 60) and TOOL_RATE_LIMIT_BURST
+ * (default 30). A value that is not a positive integer refuses the start, naming the variable.
+ */
+export function createTokenBucketLimiter(opts) {
+    const now = opts.now ?? Date.now;
+    const refillPerMs = opts.perMinute / 60_000;
+    const buckets = new Map();
+    return {
+        consume(key) {
+            const t = now();
+            const b = buckets.get(key) ?? { tokens: opts.capacity, at: t };
+            b.tokens = Math.min(opts.capacity, b.tokens + (t - b.at) * refillPerMs);
+            b.at = t;
+            buckets.set(key, b);
+            if (b.tokens >= 1) {
+                b.tokens -= 1;
+                return { ok: true };
+            }
+            return { ok: false, retryAfterMs: Math.ceil((1 - b.tokens) / refillPerMs) };
+        },
+    };
+}
+function positiveInt(env, name, fallback) {
+    const raw = env[name];
+    if (raw === undefined || raw === "")
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new Error(`${name} must be a positive integer (got a value that is not)`);
+    return n;
+}
+/** The limits read from the environment. */
+export function loadToolRateLimit(env = process.env) {
+    return {
+        capacity: positiveInt(env, "TOOL_RATE_LIMIT_BURST", 30),
+        perMinute: positiveInt(env, "TOOL_RATE_LIMIT_PER_MINUTE", 60),
+    };
+}
+/** The process-wide limiter every tool invocation goes through, unless a test injects its own. */
+export const toolRateLimiter = createTokenBucketLimiter(loadToolRateLimit());
+/** The stable machine code of a refused invocation (beside a message localized per X-MCP-Locale). */
+export const RATE_LIMITED_CODE = "rate_limited";

package/dist/serverManifest.d.ts

@@ -26,8 +26,16 @@ export interface ServerManifest {
     features: Record<string, boolean>;
     /** The per-server context ceiling. A number cannot ride in `features` (booleans only). */
     contextCeiling: ContextCeiling;
+    /**
+     * The hosts the server is distributed on (mcp-server-standard S-45 / S-46), read from `distribution.targets`.
+     * Absent in the manifest: no target, `[]`. The ids are not validated here: the closed set is the standard's,
+     * checked by mcp-doctor; a fork adds a host by data, never by code.
+     */
+    distribution: {
+        targets: readonly string[];
+    };
 }
-type Expectation = "string" | "semver" | "object" | "boolean" | "positiveInteger" | "atLeastPerTool";
+type Expectation = "string" | "semver" | "object" | "boolean" | "positiveInteger" | "atLeastPerTool" | "stringArray";
 /** Thrown when a manifest field cannot be read. `field` is the dotted path of the offender. */
 export declare class ServerManifestError extends Error {
     readonly field: string;

package/dist/serverManifest.js

@@ -35,7 +35,7 @@ function isPositiveInteger(value) {
 export function parseServerManifest(document, source) {
     if (!isRecord(document))
         throw new ServerManifestError("(document)", source, "object");
-    const { name, version, capabilities, transport, features, contextCeiling } = document;
+    const { name, version, capabilities, transport, features, contextCeiling, distribution } = document;
     if (typeof name !== "string" || name.length === 0) {
         throw new ServerManifestError("name", source, "string");
     }
@@ -65,6 +65,14 @@ export function parseServerManifest(document, source) {
     if (global < perTool) {
         throw new ServerManifestError("contextCeiling.global", source, "atLeastPerTool");
     }
+    let targets = [];
+    if (distribution !== undefined) {
+        const raw = isRecord(distribution) ? distribution.targets : undefined;
+        if (!Array.isArray(raw) || raw.some((t) => typeof t !== "string" || t.length === 0)) {
+            throw new ServerManifestError("distribution.targets", source, "stringArray");
+        }
+        targets = raw;
+    }
     return {
         name,
         version,
@@ -72,6 +80,7 @@ export function parseServerManifest(document, source) {
         transport,
         features: features,
         contextCeiling: { global, perTool },
+        distribution: { targets },
     };
 }
 /**

package/dist/signedCursor.js

@@ -56,7 +56,11 @@ export function createCursorSigner(options = {}) {
     }
     // 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 tagOf = (payloadPart) => 
+    // allow-local-identity: HMAC proving a pagination cursor was issued by this server; it identifies no caller or tenant
+    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.
@@ -89,6 +93,7 @@ export function createCursorSigner(options = {}) {
         // the tag matches. Equal lengths (32 bytes each, checked above): timingSafeEqual cannot throw.
         if (!BASE64URL.test(payloadPart))
             throw new InvalidCursorError("not_base64url");
+        // allow-local-identity: constant-time check of the cursor's own HMAC tag; no credential a caller presented
         if (!timingSafeEqual(tagOf(payloadPart), tag))
             throw new InvalidCursorError("tag_mismatch");
         // Signed by us, so canonical; re-checked so a decode is never lenient.

package/dist/stdio.js

@@ -18,12 +18,12 @@ export function startStdioServer() {
     // Refuses at start, naming the field, a manifest without a readable context ceiling (G6).
     loadServerManifest();
     const requireTenant = process.env.MCP_BOILERPLATE_REQUIRE_TENANT === "1";
-    const uiDomain = process.env.MCP_UI_DOMAIN || undefined;
     // No verified person on stdio, by design: there is no bearer and no verified session on this
     // transport, so `caller` is deliberately left unset and a tool wrapped with
     // `withVerifiedPerson` is refused as `no_verified_session` (src/verifiedPerson.ts). The local
     // process is trusted as the caller, never impersonated as a person.
-    serveStdio(() => createBoilerplateMcpServer({ requireTenant, uiDomain }));
+    // No served URL on stdio, so no Claude sandbox domain to derive (A-11): the widget declares none.
+    serveStdio(() => createBoilerplateMcpServer({ requireTenant }));
     process.stderr.write("[mcp-boilerplate] stdio server started — 2 tools available\n");
 }
 try {