@zuplo/runtime 6.71.26 → 6.71.27

package/out/types/mcp-gateway/index.d.ts

@@ -1,5 +1,57 @@
 import { z } from "zod/v4";
 
+/**
+ * Optional per-caller access control. Defaults to mode 'allPublic' (no access control). Set mode to 'rolesAndGroups' to match the caller's role/group claims against each capability's markup (every capability must then set roles/groups or public: true), or 'function' to delegate to a custom resolver.
+ * @public
+ */
+declare interface AccessControl {
+  /**
+   * Access-control strategy. 'allPublic' (default): no access control; roles/groups/public markup is not allowed. 'rolesAndGroups': match the caller's role and group claims against each capability's markup. 'function': delegate to the resolver named by 'identifier'.
+   */
+  mode?: "allPublic" | "rolesAndGroups" | "function";
+  /**
+   * Property on request.user.data holding the caller's roles (commonly a JWT 'roles' claim, but request.user.data is set by whichever auth policy ran — JWT, API key, etc.), matched against each capability's 'roles'. Supports a dot-path for nested values, e.g. 'realm_access.roles'. Used in mode 'rolesAndGroups'. Defaults to 'roles'.
+   */
+  roleClaim?: string;
+  /**
+   * Property on request.user.data holding the caller's groups (commonly a JWT 'groups' claim, but request.user.data is set by whichever auth policy ran — JWT, API key, etc.), matched against each capability's 'groups'. Supports a dot-path for nested values, e.g. 'cognito:groups'. Used in mode 'rolesAndGroups'. Defaults to 'groups'.
+   */
+  groupClaim?: string;
+  /**
+   * Custom capability resolver, required when mode is 'function'. It fully replaces built-in roles/groups matching.
+   */
+  identifier?: {
+    /**
+     * Module to load the resolver from, e.g. $import(./modules/mcp-access-control).
+     */
+    module: string;
+    /**
+     * Named export of the resolver function, e.g. 'default'.
+     */
+    export: string;
+  };
+}
+
+/**
+ * The set of MCP capabilities a caller is permitted to see and invoke, returned
+ * by an {@link McpCapabilityResolver}. Each array lists the allowed identifiers
+ * (tool/prompt names, resource/template URIs).
+ *
+ * Omit a property to leave that capability type unrestricted (it falls back to
+ * the static allowlist). Return an empty array to expose none of that type.
+ * Returned identifiers are always clamped to the policy's configured catalog, so
+ * a resolver can only ever narrow access, never widen it — a capability type
+ * left as passthrough (no static allowlist) is therefore not narrowed at all.
+ *
+ * @public
+ */
+export declare interface AllowedCapabilities {
+  tools?: string[];
+  prompts?: string[];
+  resources?: string[];
+  resourceTemplates?: string[];
+}
+
 /**
  * MCP tool annotations to expose downstream.
  * @public
@@ -68,6 +120,22 @@ declare interface BuildRouteConfiguration {
   /* Excluded from this release type: raw */
 }
 
+/**
+ * Built-in resolver for `accessControl.mode: "rolesAndGroups"`.
+ *
+ * Reads the caller's roles and groups from two properties on `request.user.data`
+ * (`accessControl.roleClaim` / `accessControl.groupClaim`, defaulting to
+ * `roles`/`groups`, each allowing a dot-path such as `realm_access.roles`).
+ * `request.user.data` is populated by whichever auth policy ran (JWT claims,
+ * API-key metadata, etc.). A capability marked `public: true` is allowed for
+ * everyone; otherwise the caller must match any listed role or group. In this
+ * mode every capability must be classified (see {@link assertClassified}), so
+ * nothing is public by omission.
+ *
+ * @public
+ */
+export declare const claimsCapabilityResolver: McpCapabilityResolver;
+
 /**
  * The 2-letter continent codes Cloudflare uses
  * @public
@@ -135,6 +203,14 @@ declare const EventType: {
 
 declare type EventType = (typeof EventType)[keyof typeof EventType];
 
+/**
+ * Access control: groups allowed to see and invoke this capability. Matched against the caller's groups on request.user.data (accessControl.groupClaim, default 'groups'). Used when accessControl.mode is 'rolesAndGroups'.
+ *
+ * @minItems 1
+ * @public
+ */
+declare type Groups = [string, ...string[]];
+
 /**
  * @public
  */
@@ -1138,6 +1214,10 @@ declare const mcpAuth0OAuthOptionsSchema: z.ZodObject<
  * with a customer-facing `ConfigurationError` instead of failing at module
  * load.
  *
+ * Optional per-caller access control (`accessControl`) narrows the curated
+ * catalog. See {@link claimsCapabilityResolver} for built-in role/group matching
+ * and {@link McpCapabilityResolver} for custom resolvers.
+ *
  * @public
  * @title MCP Capability Filter
  * @product mcp-gateway
@@ -1173,6 +1253,7 @@ export declare interface McpCapabilityFilterInboundPolicyOptions {
    * Resource templates to expose. Use a string for URI-template-only filtering, or an object to expose and project template name, description, MIME type, and _meta. Omit to pass through all upstream resource templates; use an empty array to expose no resource templates.
    */
   resourceTemplates?: (string | ResourceTemplateProjection)[];
+  accessControl?: AccessControl;
 }
 
 declare const mcpCapabilityFilterOptionsSchema: z.ZodObject<
@@ -1190,6 +1271,9 @@ declare const mcpCapabilityFilterOptionsSchema: z.ZodObject<
                   z.ZodRecord<z.ZodString, z.ZodUnknown>
                 >;
                 _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                public: z.ZodOptional<z.ZodBoolean>;
               },
               z.core.$strict
             >,
@@ -1207,6 +1291,9 @@ declare const mcpCapabilityFilterOptionsSchema: z.ZodObject<
                 name: z.ZodString;
                 description: z.ZodOptional<z.ZodString>;
                 _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                public: z.ZodOptional<z.ZodBoolean>;
               },
               z.core.$strict
             >,
@@ -1226,6 +1313,9 @@ declare const mcpCapabilityFilterOptionsSchema: z.ZodObject<
                 description: z.ZodOptional<z.ZodString>;
                 mimeType: z.ZodOptional<z.ZodString>;
                 _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                public: z.ZodOptional<z.ZodBoolean>;
               },
               z.core.$strict
             >,
@@ -1245,6 +1335,9 @@ declare const mcpCapabilityFilterOptionsSchema: z.ZodObject<
                 description: z.ZodOptional<z.ZodString>;
                 mimeType: z.ZodOptional<z.ZodString>;
                 _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                public: z.ZodOptional<z.ZodBoolean>;
               },
               z.core.$strict
             >,
@@ -1252,10 +1345,53 @@ declare const mcpCapabilityFilterOptionsSchema: z.ZodObject<
         >
       >
     >;
+    accessControl: z.ZodOptional<
+      z.ZodObject<
+        {
+          mode: z.ZodOptional<
+            z.ZodEnum<{
+              function: "function";
+              allPublic: "allPublic";
+              rolesAndGroups: "rolesAndGroups";
+            }>
+          >;
+          roleClaim: z.ZodOptional<z.ZodString>;
+          groupClaim: z.ZodOptional<z.ZodString>;
+          identifier: z.ZodOptional<
+            z.ZodObject<
+              {
+                module: z.ZodUnknown;
+                export: z.ZodString;
+              },
+              z.core.$strict
+            >
+          >;
+        },
+        z.core.$strict
+      >
+    >;
   },
   z.core.$strict
 >;
 
+/**
+ * Resolves, per request, which MCP capabilities a caller may see and invoke.
+ *
+ * The built-in {@link claimsCapabilityResolver} (used for
+ * `accessControl.mode: "rolesAndGroups"`) matches the caller's role and group
+ * claims against each capability's `roles`/`groups` markup. Provide a custom
+ * resolver with `accessControl.mode: "function"` and
+ * `accessControl.identifier: { module, export }` to derive access any other way,
+ * e.g. from an external entitlements API.
+ *
+ * @public
+ */
+export declare type McpCapabilityResolver = (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: McpCapabilityFilterInboundPolicyOptions
+) => AllowedCapabilities | Promise<AllowedCapabilities>;
+
 /**
  * Authenticate MCP gateway requests using a gateway-issued OAuth access token,
  * with browser login delegated to Clerk.
@@ -3217,8 +3353,17 @@ declare interface PromptProjection {
    */
   description?: string;
   _meta?: Metadata;
+  roles?: Roles;
+  groups?: Groups;
+  public?: Public;
 }
 
+/**
+ * Access control: mark this capability as available to all callers. In mode 'rolesAndGroups' every capability must set roles/groups OR public: true (not both) — an unclassified capability is a configuration error, so nothing is ever exposed by omission.
+ * @public
+ */
+declare type Public = boolean;
+
 /**
  * Generic type parameters for a request.
  * Extends RequestInitGeneric and adds query parameter typing.
@@ -3298,6 +3443,9 @@ declare interface ResourceProjection {
    */
   mimeType?: string;
   _meta?: Metadata;
+  roles?: Roles;
+  groups?: Groups;
+  public?: Public;
 }
 
 declare interface ResourceTemplateProjection {
@@ -3318,6 +3466,9 @@ declare interface ResourceTemplateProjection {
    */
   mimeType?: string;
   _meta?: Metadata;
+  roles?: Roles;
+  groups?: Groups;
+  public?: Public;
 }
 
 /**
@@ -3336,6 +3487,14 @@ declare type ResponsesDefinition = Record<
   >
 >;
 
+/**
+ * Access control: roles allowed to see and invoke this capability. Matched against the caller's roles on request.user.data (accessControl.roleClaim, default 'roles'). Used when accessControl.mode is 'rolesAndGroups'.
+ *
+ * @minItems 1
+ * @public
+ */
+declare type Roles = [string, ...string[]];
+
 /**
  * @public
  */
@@ -3449,6 +3608,9 @@ declare interface ToolProjection {
   description?: string;
   annotations?: Annotations;
   _meta?: Metadata;
+  roles?: Roles;
+  groups?: Groups;
+  public?: Public;
 }
 
 declare type UpstreamTokenExchangePolicyOptions = z.infer<

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zuplo/runtime",
   "type": "module",
-  "version": "6.71.26",
+  "version": "6.71.27",
   "repository": "https://github.com/zuplo/zuplo",
   "author": "Zuplo, Inc.",
   "exports": {