@vantageos/mcp-boilerplate 0.6.2 → 0.7.0

package/dist/listCursor.js

@@ -0,0 +1,37 @@
+import { ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/server";
+/**
+ * C-11 (a) (mcp-standard): an invalid cursor sent to a protocol list method is JSON-RPC -32602 Invalid params, never a
+ * silent first page. The SDK serves `tools/list`, `resources/list`, `resources/templates/list` and `prompts/list` as
+ * ONE page and issues no `nextCursor`, so every cursor such a request carries is one this server never issued: invalid.
+ * The SDK itself ignores the cursor and answers page 1, so each of these handlers is wrapped in place (the SDK keeps them
+ * in a map) to refuse first. A list that cannot be wrapped refuses the start: it must not answer a cursor silently.
+ */
+export const SINGLE_PAGE_LISTS = [
+    "tools/list",
+    "resources/list",
+    "resources/templates/list",
+    // The seed registers no prompt, so it serves no prompts/list; a fork that registers one gets it guarded.
+    "prompts/list",
+];
+export function rejectCursorOnSinglePageLists(server) {
+    const handlers = server.server
+        ._requestHandlers;
+    if (!handlers)
+        throw new Error("C-11 (a): the SDK's request handlers were not found; list cursors cannot be checked");
+    for (const method of SINGLE_PAGE_LISTS) {
+        const inner = handlers.get(method);
+        if (typeof inner !== "function")
+            continue; // a list this server does not serve (no resources) has no handler
+        handlers.set(method, async (req, ctx) => {
+            const cursor = req?.params?.cursor;
+            if (cursor !== undefined)
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, `invalid cursor: ${method} is served as one page and issues no cursor`);
+            const result = (await inner(req, ctx));
+            // The refusal above rests on the SDK serving one page. If it ever returns a nextCursor, cursors become valid
+            // and refusing them all would be wrong: fail loud instead of answering a page with a cursor we would refuse.
+            if (result?.nextCursor !== undefined)
+                throw new Error(`C-11 (a): ${method} now returns a nextCursor; src/listCursor.ts must accept its cursors`);
+            return result;
+        });
+    }
+}

package/dist/locales/en.json

@@ -12,12 +12,18 @@
       "noVerifiedSession": "permission denied: this tool needs the verified person, and this call carries no verified session",
       "refused": "permission denied: the verified person behind this call could not be resolved"
     },
+    "rateLimit": {
+      "exceeded": "too many tool calls: retry in {seconds} s"
+    },
     "validation": {
       "messageTooLong": "message exceeds the maximum length of 200 characters"
     },
     "oauth": {
       "pickerTitle": "Connect {client}",
       "pickerIntro": "{client} asks to act on your behalf. Choose the organisation it may reach, then approve or deny.",
+      "handoffTitle": "Returning to the application",
+      "handoffLink": "Continue to the application",
+      "pickerNoAllowedOrganisation": "None of your organisations is authorised on this server.",
       "pickerDestination": "After approval you are sent to:",
       "pickerScope": "Requested access:",
       "pickerUnverified": "Unverified client: it registered itself automatically and nobody has vouched for it. Approve only if you recognise the address above.",
@@ -39,9 +45,17 @@
         "object": "an object",
         "boolean": "true or false",
         "positiveInteger": "a positive whole number",
-        "atLeastPerTool": "at least the perTool ceiling"
+        "atLeastPerTool": "at least the perTool ceiling",
+        "stringArray": "an array of non-empty strings"
       }
     },
+    "toolRoles": {
+      "identityMissing": "the identity stores are not injected (AppDeps.identity): on the OAuth tier a caller's role is decided for the organisation the identity layer resolves, so both are required",
+      "denied": "permission denied: your role does not grant the tool {tool} ({reason})",
+      "unresolved": "permission denied: your role could not be read, so no tool is granted",
+      "configMissing": "{variable} is not set: on the OAuth tier every tool is decided by the caller's role, read from that roles file",
+      "configInvalid": "{variable} ({path}) is not a valid roles file: {problem}"
+    },
     "toolRecord": {
       "unsound": "tool records or the context ceiling are unsound: {problems}"
     },

package/dist/locales/fr.json

@@ -12,12 +12,18 @@
       "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"
     },
     "oauth": {
       "pickerTitle": "Connecter {client}",
       "pickerIntro": "{client} demande à agir en votre nom. Choisissez l'organisation à laquelle il peut accéder, puis approuvez ou refusez.",
+      "handoffTitle": "Retour à l'application",
+      "handoffLink": "Continuer vers l'application",
+      "pickerNoAllowedOrganisation": "Aucune de vos organisations n'est autorisée sur ce serveur.",
       "pickerDestination": "Redirection après validation vers :",
       "pickerScope": "Accès demandé :",
       "pickerUnverified": "Client non vérifié : il s'est enregistré automatiquement et personne ne s'en porte garant. N'approuvez que si vous reconnaissez l'adresse ci-dessus.",
@@ -39,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,22 +20,26 @@
  * 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 { pickerContentSecurityPolicy, renderOrgPicker } from "./picker.js";
+import { HANDOFF_CSP, pickerContentSecurityPolicy, renderHandoff, renderOrgPicker, } from "./picker.js";
 import { createRegisterLimiter } from "./registerLimiter.js";
 import { DEFAULT_SCOPE, OAUTH_ENV, SUPPORTED_SCOPES, isDevClerkInstanceOnRemoteServer, readAuthorizeSettings, } from "./settings.js";
 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());
@@ -198,6 +203,16 @@ export function createAuthorizationServer(deps = {}) {
         const client = await lookupClient(model.client.clientId);
         return (client?.redirectUris ?? []).filter((u) => !/^https?:/i.test(u));
     };
+    /** The organisations this server authorises (AUTHORIZE_ALLOWED_ORG_IDS), or undefined when every membership is. */
+    const allowedOrgIds = () => {
+        const raw = env[OAUTH_ENV.allowedOrgIds]?.trim();
+        if (!raw)
+            return undefined;
+        return new Set(raw
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean));
+    };
     const respond = async (c, outcome, settings) => {
         noStore(c);
         c.header("Referrer-Policy", "no-referrer");
@@ -208,12 +223,33 @@ export function createAuthorizationServer(deps = {}) {
                 // RFC 9207 section 2: identify the issuer in the authorization response.
                 const back = new URL(outcome.url);
                 back.searchParams.set("iss", settings.baseUrl);
+                // The consent form's POST ends here, in a same-origin page, so its form-action does not follow the client's
+                // own redirect hops (renderHandoff). A GET (the return from sign-in) still answers a plain redirect.
+                if (c.req.method === "POST") {
+                    c.header("Content-Security-Policy", HANDOFF_CSP);
+                    const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
+                    return c.html(renderHandoff(back.toString(), locale));
+                }
                 return c.redirect(back.toString(), 302);
             }
             case "org-picker": {
+                // Only this server's authorised organisations are offered (data per server).
+                const allowed = allowedOrgIds();
+                let model = outcome.model;
+                if (allowed) {
+                    const organizations = model.organizations.filter((o) => allowed.has(o.id));
+                    if (organizations.length === 0) {
+                        const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
+                        return c.json({
+                            error: "access_denied",
+                            error_description: t(locale, "oauth.pickerNoAllowedOrganisation"),
+                        }, 403);
+                    }
+                    model = { ...model, organizations };
+                }
                 let csp;
                 try {
-                    csp = await pickerContentSecurityPolicy(await redirectTargetsOf(outcome.model));
+                    csp = await pickerContentSecurityPolicy(await redirectTargetsOf(model));
                 }
                 catch (err) {
                     // Fail closed: without a parseable destination the page is not rendered at all.
@@ -222,9 +258,9 @@ export function createAuthorizationServer(deps = {}) {
                 }
                 c.header("Content-Security-Policy", csp);
                 const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
-                return c.html(renderOrgPicker(outcome.model, locale, {
+                return c.html(renderOrgPicker(model, locale, {
                     // Only a URL-shaped (CIMD) client_id is bound to a domain its owner controls.
-                    unverified: !isUrlShapedClientId(outcome.model.client.clientId),
+                    unverified: !isUrlShapedClientId(model.client.clientId),
                     brandName: env[OAUTH_ENV.brandName]?.trim() || undefined,
                 }));
             }
@@ -239,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();
@@ -463,6 +507,15 @@ export function createAuthorizationServer(deps = {}) {
                     }, cfg, authDeps);
                     return respond(c, denied, result.settings);
                 }
+                // An approval for an organisation this server does not authorise never reaches the code issuer.
+                const allowed = allowedOrgIds();
+                if (allowed && !allowed.has(field("orgId") ?? "")) {
+                    const locale = detectLocaleFromAcceptLanguage(c.req.header("accept-language"));
+                    return c.json({
+                        error: "access_denied",
+                        error_description: t(locale, "oauth.pickerNoAllowedOrganisation"),
+                    }, 403);
+                }
                 const outcome = await resumeAuthorize({
                     state: field("state") ?? "",
                     sessionToken: sessionTokenFrom(c),
@@ -473,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);
@@ -550,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.d.ts

@@ -19,3 +19,14 @@ export interface ConsentContext {
     brandName?: string;
 }
 export declare function renderOrgPicker(model: OrgPickerModel, locale: McpLocale, consent: ConsentContext): string;
+/** The CSP of the hand-off page: nothing runs, nothing is submitted, nothing frames it. */
+export declare const HANDOFF_CSP = "default-src 'none'; form-action 'none'; frame-ancestors 'none'; base-uri 'none'";
+/**
+ * The page that ends the consent form submission inside this origin and sends the browser on to the client.
+ *
+ * A browser applies the consent page's `form-action` to every redirect hop of the form submission, so answering the
+ * POST with a 302 to the client's redirect_uri lets the client's OWN next hop (vscode.dev/redirect -> vscode:// or a
+ * loopback) be blocked by our policy. This page is a 200 response: the navigation to the client is a meta refresh (and
+ * a visible link), not a form submission, so `form-action` no longer follows it.
+ */
+export declare function renderHandoff(target: string, locale: McpLocale): string;

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 [
@@ -148,3 +149,30 @@ ${orgs}
 </html>
 `;
 }
+/** The CSP of the hand-off page: nothing runs, nothing is submitted, nothing frames it. */
+export const HANDOFF_CSP = "default-src 'none'; form-action 'none'; frame-ancestors 'none'; base-uri 'none'";
+/**
+ * The page that ends the consent form submission inside this origin and sends the browser on to the client.
+ *
+ * A browser applies the consent page's `form-action` to every redirect hop of the form submission, so answering the
+ * POST with a 302 to the client's redirect_uri lets the client's OWN next hop (vscode.dev/redirect -> vscode:// or a
+ * loopback) be blocked by our policy. This page is a 200 response: the navigation to the client is a meta refresh (and
+ * a visible link), not a form submission, so `form-action` no longer follows it.
+ */
+export function renderHandoff(target, locale) {
+    const url = escapeHtml(target);
+    const title = escapeHtml(t(locale, "oauth.handoffTitle"));
+    return `<!doctype html>
+<html lang="${locale}">
+<head>
+<meta charset="utf-8">
+<meta http-equiv="refresh" content="0;url=${url}">
+<title>${title}</title>
+</head>
+<body>
+<p>${title}</p>
+<p><a href="${url}">${escapeHtml(t(locale, "oauth.handoffLink"))}</a></p>
+</body>
+</html>
+`;
+}

package/dist/oauth/settings.d.ts

@@ -18,12 +18,19 @@ 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). */
     readonly allowInMemoryStores: "MCP_ALLOW_IN_MEMORY_STORES";
     /** Optional display name shown above the consent page title (default: none). */
     readonly brandName: "AUTHORIZE_BRAND_NAME";
+    /**
+     * Optional comma-separated Clerk organisation ids this server authorises. When set, the consent offers only the
+     * person's memberships in this list and refuses an approval for any other. Data per server, never code.
+     */
+    readonly allowedOrgIds: "AUTHORIZE_ALLOWED_ORG_IDS";
 };
 /** Scope granted when a client names none: MCP access plus the OIDC subject. */
 export declare const MCP_SCOPE = "mcp:full";

package/dist/oauth/settings.js

@@ -18,12 +18,19 @@ 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). */
     allowInMemoryStores: "MCP_ALLOW_IN_MEMORY_STORES",
     /** Optional display name shown above the consent page title (default: none). */
     brandName: "AUTHORIZE_BRAND_NAME",
+    /**
+     * Optional comma-separated Clerk organisation ids this server authorises. When set, the consent offers only the
+     * person's memberships in this list and refuses an approval for any other. Data per server, never code.
+     */
+    allowedOrgIds: "AUTHORIZE_ALLOWED_ORG_IDS",
 };
 /** Scope granted when a client names none: MCP access plus the OIDC subject. */
 export const MCP_SCOPE = "mcp:full";

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;