@vantageos/mcp-boilerplate 0.6.2 → 0.7.0

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 {

package/dist/tenancy.d.ts

@@ -5,20 +5,10 @@
  * rows. This module never re-verifies the token and never reimplements
  * cloud-identity's authorization logic — it only adapts shapes.
  *
- * API-shape note (first real consumer of `requireTenantId`, new in
- * cloud-identity 0.3.0 with zero prior callers): the package's "bearer"
- * entry path expects a full `TenantContext` ({ workspaceId, userId, roles })
- * — the shape cloud-identity's OWN workspace-membership layer produces
- * (`decodeUnverifiedBearer`), not a generic OAuth JWT. This boilerplate's
- * verified claims (a plain claims record, Clerk-as-AS) carries no
- * `workspaceId`/`roles` claims, so it is NOT a `TenantContext` and cannot
- * go through the "bearer" path without inventing fields cloud-identity
- * never asked for. It goes through the "session" path instead
- * (`identity: { orgId }`), which matches the JWT's `org_id` claim exactly
- * as Clerk mints it. Both entry paths converge on the same
- * refuse-on-absence contract (`requireTenantId` throws when there is no
- * organization, on either path) — this is a compatible substitution
- * documented at the one call site it affects, never a bypass of the guard.
+ * The organisation is read by cloud-identity's one claim reader (`requireTenantFromIdentity`: the same
+ * claim names and the same Clerk `org_` shape as `resolveTenantFromAccessToken`), never by this module.
+ * No claim, or a claim that is not an organisation id, refuses (throws); there is no fallback to a slug, a
+ * name or a default tenant.
  */
 export interface ResolvedTenant {
     tenantId: string;

package/dist/tenancy.js

@@ -5,22 +5,12 @@
  * rows. This module never re-verifies the token and never reimplements
  * cloud-identity's authorization logic — it only adapts shapes.
  *
- * API-shape note (first real consumer of `requireTenantId`, new in
- * cloud-identity 0.3.0 with zero prior callers): the package's "bearer"
- * entry path expects a full `TenantContext` ({ workspaceId, userId, roles })
- * — the shape cloud-identity's OWN workspace-membership layer produces
- * (`decodeUnverifiedBearer`), not a generic OAuth JWT. This boilerplate's
- * verified claims (a plain claims record, Clerk-as-AS) carries no
- * `workspaceId`/`roles` claims, so it is NOT a `TenantContext` and cannot
- * go through the "bearer" path without inventing fields cloud-identity
- * never asked for. It goes through the "session" path instead
- * (`identity: { orgId }`), which matches the JWT's `org_id` claim exactly
- * as Clerk mints it. Both entry paths converge on the same
- * refuse-on-absence contract (`requireTenantId` throws when there is no
- * organization, on either path) — this is a compatible substitution
- * documented at the one call site it affects, never a bypass of the guard.
+ * The organisation is read by cloud-identity's one claim reader (`requireTenantFromIdentity`: the same
+ * claim names and the same Clerk `org_` shape as `resolveTenantFromAccessToken`), never by this module.
+ * No claim, or a claim that is not an organisation id, refuses (throws); there is no fallback to a slug, a
+ * name or a default tenant.
  */
-import { isRowInTenant, requireTenantId } from "@vantageos/cloud-identity";
+import { isRowInTenant, requireTenantFromIdentity } from "@vantageos/cloud-identity";
 /**
  * Resolve the caller's tenant from the verified session claims. Refuses
  * (throws) when the token carries no organization — never falls through to
@@ -28,9 +18,8 @@ import { isRowInTenant, requireTenantId } from "@vantageos/cloud-identity";
  * (an explicit permission-denied response), never silently grant access.
  */
 export function resolveTenantFromJwtPayload(payload) {
-    const orgId = typeof payload.org_id === "string" ? payload.org_id : undefined;
-    const tenantId = requireTenantId({ kind: "session", identity: { orgId } });
-    return { tenantId };
+    // The organisation claim is read by the identity layer's one claim reader, never here (DLocalIdentity).
+    return { tenantId: requireTenantFromIdentity(payload, { door: "mcp" }) };
 }
 /**
  * Filter rows by the caller's tenant with cloud-identity's `isRowInTenant`: a row is visible

package/dist/toolRecord.d.ts

@@ -10,6 +10,8 @@ import type { ContextCeiling } from "./serverManifest.js";
  *   searchMechanism         C-10  how a list/search is served; `unindexed-scan` does not publish
  *   paginationCursor/Default/Max  C-11  declared here, applied by src/pagination.ts
  *   tokensEstimeContexte    C-13  the estimated context cost of the served tool
+ *   domain, mode            Agent tool roles rule 2: the business domain the tool belongs to, and `read` | `write`;
+ *                           what `decideToolRole` (@vantageos/cloud-identity) reads to allow or deny it per role
  *
  * The sets are closed UNIONS, so a value outside them is a compile error, and the verb decides
  * which other slots are required (a list/search tool cannot omit its mechanism or its pagination).
@@ -34,6 +36,11 @@ export type ToolVerb = "list" | "get" | "search" | "aggregate" | "create" | "upd
  * must declare it (`checkToolRecord`).
  */
 export type SearchMechanism = "indexed-range" | "indexed-bm25" | `indexed-vector(${string})` | "indexed-hybrid-rrf" | `upstream-delegated(${string})`;
+/**
+ * Agent tool roles rule 2 (mcp-server-standard "Agent tool roles"): exactly `read` or `write`. `read` must agree with
+ * `readOnlyHint: true`, `write` with `readOnlyHint: false` (C-15). Same union as cloud-identity's `ToolMode`.
+ */
+export type ToolMode = "read" | "write";
 /** The four behavioural annotations (C-15), explicit booleans on every tool. */
 interface BehaviourHints {
     readOnlyHint: boolean;
@@ -44,6 +51,10 @@ interface BehaviourHints {
 interface CommonSlots extends BehaviourHints {
     authRead: AuthTier;
     authWrite: AuthTier;
+    /** The business domain a role grants (rule 1); a non-empty name. */
+    domain: string;
+    /** read | write (rule 2); agrees with readOnlyHint. */
+    mode: ToolMode;
     /** Estimated context tokens of the served tool (C-13); tests/contextCeiling.test.ts checks it. */
     tokensEstimeContexte: number;
 }
@@ -75,8 +86,22 @@ export declare const PING_ANNOTATIONS: {
     readonly openWorldHint: false;
     readonly authRead: "public";
     readonly authWrite: "master";
+    readonly domain: "system";
+    readonly mode: "read";
     readonly verb: "pure";
-    readonly tokensEstimeContexte: 200;
+    readonly tokensEstimeContexte: 280;
+};
+export declare const WHOAMI_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+    readonly authRead: "public";
+    readonly authWrite: "master";
+    readonly domain: "identity";
+    readonly mode: "read";
+    readonly verb: "introspect";
+    readonly tokensEstimeContexte: 330;
 };
 export declare const LIST_ITEMS_ANNOTATIONS: {
     readonly readOnlyHint: true;
@@ -85,13 +110,15 @@ export declare const LIST_ITEMS_ANNOTATIONS: {
     readonly openWorldHint: false;
     readonly authRead: "org-member";
     readonly authWrite: "master";
+    readonly domain: "items";
+    readonly mode: "read";
     readonly verb: "list";
     readonly table: "items";
     readonly searchMechanism: "indexed-range";
     readonly paginationCursor: true;
     readonly paginationDefault: 20;
     readonly paginationMax: 100;
-    readonly tokensEstimeContexte: 640;
+    readonly tokensEstimeContexte: 690;
 };
 /** One tool's declared context cost, as `checkContextCeiling` reads it. */
 export interface ContextEstimate {
@@ -111,6 +138,12 @@ export declare function checkContextCeiling(estimates: readonly ContextEstimate[
  * refused. A tool that is not a list/search is not asked for a mechanism.
  */
 export declare function checkToolRecord(name: string, record: Record<string, unknown>): string[];
+/**
+ * Agent tool roles rule 2: every tool declares a non-empty `domain` and a `mode` of exactly `read` or `write`, and the
+ * mode agrees with `readOnlyHint` (read <-> true, write <-> false). A tool missing either, or with any other value, is
+ * served to no one: the start refuses, naming it.
+ */
+export declare function checkToolRole(name: string, record: Record<string, unknown>): string[];
 /** Thrown at start when a tool record or the ceiling is unsound. `problems` name every tool. */
 export declare class ToolRecordError extends Error {
     readonly problems: readonly string[];

package/dist/toolRecord.js

@@ -9,8 +9,24 @@ export const PING_ANNOTATIONS = {
     openWorldHint: false,
     authRead: "public",
     authWrite: "master",
+    domain: "system",
+    mode: "read",
     verb: "pure",
-    tokensEstimeContexte: 200,
+    tokensEstimeContexte: 280,
+};
+// The identity tool (C-33; agent tool roles rule 6): the caller's own identity and granted tools. It reveals nothing
+// beyond the caller's own standing, so it is `public` to read; it writes nothing.
+export const WHOAMI_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    authRead: "public",
+    authWrite: "master",
+    domain: "identity",
+    mode: "read",
+    verb: "introspect",
+    tokensEstimeContexte: 330,
 };
 export const LIST_ITEMS_ANNOTATIONS = {
     readOnlyHint: true,
@@ -19,13 +35,15 @@ export const LIST_ITEMS_ANNOTATIONS = {
     openWorldHint: false,
     authRead: "org-member",
     authWrite: "master",
+    domain: "items",
+    mode: "read",
     verb: "list",
     table: "items",
     searchMechanism: "indexed-range",
     paginationCursor: true,
     paginationDefault: 20,
     paginationMax: 100,
-    tokensEstimeContexte: 640,
+    tokensEstimeContexte: 690,
 };
 /** Every problem found, each naming the tool; empty when the ceiling holds. Never skips a tool. */
 export function checkContextCeiling(estimates, ceiling) {
@@ -66,6 +84,30 @@ function isIndexedMechanism(value) {
  * refused. A tool that is not a list/search is not asked for a mechanism.
  */
 export function checkToolRecord(name, record) {
+    return [...checkToolRole(name, record), ...checkMechanism(name, record)];
+}
+/**
+ * Agent tool roles rule 2: every tool declares a non-empty `domain` and a `mode` of exactly `read` or `write`, and the
+ * mode agrees with `readOnlyHint` (read <-> true, write <-> false). A tool missing either, or with any other value, is
+ * served to no one: the start refuses, naming it.
+ */
+export function checkToolRole(name, record) {
+    const problems = [];
+    const { domain, mode, readOnlyHint } = record;
+    if (typeof domain !== "string" || domain.trim() === "") {
+        problems.push(`${name}: declares no domain (agent tool roles rule 2)`);
+    }
+    if (mode !== "read" && mode !== "write") {
+        problems.push(mode === undefined
+            ? `${name}: declares no mode (agent tool roles rule 2: "read" or "write")`
+            : `${name}: mode ${JSON.stringify(mode)} is not "read" or "write"`);
+    }
+    else if ((mode === "read") !== (readOnlyHint === true)) {
+        problems.push(`${name}: mode "${mode}" disagrees with readOnlyHint ${String(readOnlyHint)} (read <-> true, write <-> false)`);
+    }
+    return problems;
+}
+function checkMechanism(name, record) {
     if (!LIST_VERBS.includes(record.verb))
         return [];
     const mechanism = record.searchMechanism;

package/dist/toolRoleGate.d.ts

@@ -0,0 +1,41 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { type StandingScope, type ToolDeclaration, type ToolRoleLookup } from "@vantageos/cloud-identity";
+import { type McpLocale } from "./i18n.js";
+import { type CallerResolution, type VerifiedPerson } from "./verifiedPerson.js";
+/**
+ * The two enforcement points of agent tool roles (mcp-server-standard "Agent tool roles", rule 4), both calling the
+ * same decision of @vantageos/cloud-identity:
+ *   - tools/call is REFUSED: every registered handler is wrapped; a denied call returns a tool result with
+ *     `isError: true` and `structuredContent.error.code` = TOOL_ROLE_DENIED (or TOOL_ROLE_UNRESOLVED when the role could
+ *     not be read), and the handler does not run. Never a protocol error, never an empty success.
+ *   - tools/list is FILTERED: the SDK's own tools/list handler runs, then the denied tools are removed. The SDK's
+ *     `disable()` cannot be used: a disabled tool answers tools/call with a protocol error, which rule 4 forbids.
+ *
+ * The identity tool is outside the gate (rule 6: a caller with no role still gets `role: null` and an empty list,
+ * never an error); it is named in `exempt`, here and nowhere else.
+ */
+/** The per-request role context the server is built with. */
+export type ToolRolesContext = {
+    applicable: false;
+} | {
+    applicable: true;
+    lookup: ToolRoleLookup;
+    /** The caller's member scope, or null when the person was not resolved (every tool is then denied). */
+    caller: StandingScope | null;
+    /** The identity layer's resolution of the caller: an unresolved one is refused with its own code (callerRefusal). */
+    resolution: CallerResolution | undefined;
+    /** The display name of a role, for the identity tool. */
+    roleName: (roleId: string) => string | undefined;
+};
+/** The caller's member scope from the person the identity layer resolved, or null. Never built from a claim here. */
+export declare function callerScopeOf(person: VerifiedPerson | undefined): StandingScope | null;
+/**
+ * Wraps `server.registerTool` so every handler registered AFTER this call is gated, and returns the declarations seen
+ * (for the list filter and the identity tool). With roles not applicable, nothing is wrapped and nothing is filtered.
+ */
+export declare function installToolRoleGate(server: McpServer, roles: ToolRolesContext, locale: McpLocale, exempt: ReadonlySet<string>): {
+    declarations: ToolDeclaration[];
+    filterList: () => void;
+};
+/** The tools the caller is granted, by the same decision as the list (for the identity tool's `grantedTools`). */
+export declare function grantedToolNames(roles: ToolRolesContext, declarations: readonly ToolDeclaration[]): string[];

package/dist/toolRoleGate.js

@@ -0,0 +1,94 @@
+import { decideToolRole, filterGrantedTools, memberScopeFrom, } from "@vantageos/cloud-identity";
+import { t } from "./i18n.js";
+import { callerRefusal } from "./verifiedPerson.js";
+/** A scope `scopeStanding` reads as "refused": the decision denies with caller-not-resolved. */
+const UNRESOLVED_CALLER = { isMaster: false, fleetWide: false, refused: true };
+/** The caller's member scope from the person the identity layer resolved, or null. Never built from a claim here. */
+export function callerScopeOf(person) {
+    if (!person)
+        return null;
+    // The person is deep-readonly; the package reads the org row without mutating it, so a shallow copy of its arrays
+    // satisfies the mutable parameter type.
+    const org = {
+        id: person.org.id,
+        label: person.org.label,
+        allowedAgentIds: person.org.allowedAgentIds ? [...person.org.allowedAgentIds] : undefined,
+        scopes: [...person.org.scopes],
+    };
+    const r = memberScopeFrom(org, {
+        userId: person.subject,
+        orgRole: person.role,
+        orgId: person.org.id,
+    });
+    return r.ok ? r.scope : null;
+}
+function declarationOf(name, annotations) {
+    const a = (annotations ?? {});
+    return { toolId: name, domain: a.domain, mode: a.mode };
+}
+/**
+ * Wraps `server.registerTool` so every handler registered AFTER this call is gated, and returns the declarations seen
+ * (for the list filter and the identity tool). With roles not applicable, nothing is wrapped and nothing is filtered.
+ */
+export function installToolRoleGate(server, roles, locale, exempt) {
+    const declarations = [];
+    if (!roles.applicable)
+        return { declarations, filterList: () => { } };
+    const register = server.registerTool.bind(server);
+    server.registerTool = ((name, config, callback) => {
+        if (exempt.has(name))
+            return register(name, config, callback);
+        const declaration = declarationOf(name, config.annotations);
+        declarations.push(declaration);
+        const gated = async (...args) => {
+            const refused = callerRefusal(roles.resolution, locale);
+            if (refused)
+                return refused;
+            const decision = decideToolRole(roles.lookup, declaration, roles.caller ?? UNRESOLVED_CALLER, { door: name });
+            if (!decision.ok) {
+                const { code, reason } = decision.refusal;
+                const message = code === "TOOL_ROLE_UNRESOLVED"
+                    ? t(locale, "toolRoles.unresolved")
+                    : t(locale, "toolRoles.denied")
+                        .replace("{tool}", () => name)
+                        .replace("{reason}", () => reason);
+                return {
+                    content: [{ type: "text", text: message }],
+                    structuredContent: { error: { code, reason, message } },
+                    isError: true,
+                };
+            }
+            return callback(...args);
+        };
+        return register(name, config, gated);
+    });
+    const filterList = () => {
+        // The SDK keeps its handlers in a map; the tools/list entry is wrapped in place so the SDK's own listing (schemas,
+        // eras, pagination) runs unchanged and only its result is narrowed. A missing entry refuses the start: a server
+        // that cannot filter its list must not serve it unfiltered.
+        const handlers = server.server
+            ._requestHandlers;
+        const inner = handlers?.get("tools/list");
+        if (!handlers || typeof inner !== "function")
+            throw new Error("agent tool roles: the SDK's tools/list handler was not found; the list cannot be filtered");
+        handlers.set("tools/list", async (req, ctx) => {
+            // Only `tools` is narrowed: every other field of the SDK's page, `nextCursor` included, is carried unchanged, so
+            // pagination is the SDK's (and src/listCursor.ts's) exactly as without the gate.
+            const result = (await inner(req, ctx));
+            // Decided at list time, over every declaration seen so far: a tool registered after the gate was installed is
+            // listed by the same decision that gates its calls.
+            const granted = new Set(filterGrantedTools(roles.lookup, declarations, roles.caller ?? UNRESOLVED_CALLER).map((d) => d.toolId));
+            return {
+                ...result,
+                tools: (result.tools ?? []).filter((tool) => exempt.has(tool.name) || granted.has(tool.name)),
+            };
+        });
+    };
+    return { declarations, filterList };
+}
+/** The tools the caller is granted, by the same decision as the list (for the identity tool's `grantedTools`). */
+export function grantedToolNames(roles, declarations) {
+    if (!roles.applicable)
+        return [];
+    return filterGrantedTools(roles.lookup, declarations, roles.caller ?? UNRESOLVED_CALLER).map((d) => d.toolId);
+}