zuplo 6.71.26 → 6.72.0

package/docs/articles/accounts/audit-logs.mdx

@@ -10,13 +10,6 @@ account, helping you track changes and maintain compliance requirements. Every
 change performed in your account is logged with detailed information about who
 performed the change, when it occurred, and what resources were affected.
 
-:::note{title="Beta Feature"}
-
-Audit logs are currently in beta. During the beta period not all events may be
-captured. Full coverage is in progress.
-
-:::
-
 ## Overview
 
 Audit logs capture critical events across your Zuplo infrastructure, including:

package/docs/articles/securing-backend-mtls.mdx

@@ -263,6 +263,9 @@ For more information on securing your backend, see:
   Alternative approach using shared secrets
 - [Secure Tunnels](./secure-tunnel.mdx) - Connect to private backends without
   exposing them to the internet
+- [Client mTLS Authentication](./securing-the-gateway-with-client-mtls.mdx) -
+  The reverse direction, where clients authenticate to your Zuplo gateway with a
+  client certificate
 
 If you need assistance configuring mTLS for your project, contact us at
 [support@zuplo.com](mailto:support@zuplo.com).

package/docs/dedicated/federated-gateways.mdx

@@ -3,13 +3,6 @@ title: "Managed Dedicated: Federated Gateways"
 sidebar_label: Federated Gateways
 ---
 
-:::note{title="Beta Feature"}
-
-This feature is in Beta - please use with care and provide feedback to the team
-if you encounter any issues.
-
-:::
-
 <EnterpriseFeature name="Federated Gateways" />
 
 With a managed dedicated Zuplo instance you can create a federated gateway that
@@ -30,7 +23,7 @@ Federated gateways are useful for several reasons:
 - **Versioning**: You can use federated gateways to manage different versions of
   your API. For example, if you wanted to run a new version of your API
   alongside the old one and route requests to specific versions based on user or
-  other context you can keep different versions in separate Zuplo projects.
+  other context, you can keep different versions in separate Zuplo projects.
 - **Risk Minimization**: By separating different parts of your API into
   different Zuplo projects, you can reduce the risk of causing inadvertent
   changes to other parts of the API. This can be especially useful if your API

package/docs/mcp-gateway/cross-app-access/overview.mdx

@@ -8,13 +8,6 @@ description: |
   have to.
 ---
 
-:::note{title="Beta"}
-
-Cross App Access support is in beta. The configuration model and policy options
-may change before general availability.
-
-:::
-
 Cross App Access (XAA) lets one application reach another application's API on a
 user's behalf **through the identity provider both apps already trust** —
 instead of running a separate, point-to-point OAuth connection between them. For

package/docs/mcp-server/openai-apps-sdk.mdx

@@ -21,13 +21,6 @@ emits the UI.
 
 :::
 
-:::warning
-
-The OpenAI Apps SDK and support for it in Zuplo's `mcpServerHandler` is in beta
-and subject to change!
-
-:::
-
 ## `tools`
 
 MCP tools define the functionality of your app. Zuplo MCP servers support tools

package/docs/policies/_index.md

@@ -17,7 +17,7 @@
 | archive-request-gcp-storage-inbound | Archive Request to GCP Storage | Archive the incoming request to Google Cloud Storage. | api-gateway |
 | archive-response-aws-s3-outbound | Archive Response to AWS S3 | Archive the outgoing response body to AWS S3 storage | api-gateway |
 | archive-response-azure-storage-outbound | Archive Response to Azure Storage | Archive the outgoing response to Azure blob storage. | api-gateway |
-| audit-log-inbound | Audit Logs | Capture detailed logs of requests for auditing purposes. | api-gateway |
+| audit-log-inbound | Audit Logs | Capture detailed logs of requests for auditing purposes. The policy emits one structured CloudEvent per request, and user code can emit additional events via the static `log()` method. | api-gateway |
 | auth0-jwt-auth-inbound | Auth0 JWT Auth | Authenticate users using Auth0 issued JWT tokens. | api-gateway |
 | authzen-inbound | AuthZEN Authorization | Authorize requests using an AuthZEN compatible PDP | api-gateway |
 | cognito-jwt-auth-inbound | AWS Cognito JWT Auth | Authenticate requests with JWT tokens issued by AWS Cognito. | api-gateway |
@@ -57,7 +57,7 @@
 | ldap-auth-inbound | LDAP Auth | Authenticate requests using an LDAP server. | api-gateway |
 | mcp-cognito-oauth-inbound | MCP Amazon Cognito OAuth | Authenticate MCP gateway requests using a gateway-issued OAuth access token, with browser login delegated to Amazon Cognito.  Cognito-friendly wrapper around `McpOAuthInboundPolicy`. Provide an AWS region, user pool id, user pool domain, client id, and client secret; the constructor derives the Cognito issuer, JWKS URL, authorize URL, and token URL. | mcp-gateway |
 | mcp-auth0-oauth-inbound | MCP Auth0 OAuth | Authenticate MCP gateway requests using a gateway-issued OAuth access token, with browser login delegated to Auth0.  Auth0-friendly wrapper around `McpOAuthInboundPolicy`. Provide `auth0Domain` and `clientId`; the constructor derives the OIDC issuer, JWKS URL, and Auth0 authorize/token endpoints automatically and runs the resulting shape through the same Zod schema as the generic policy.  Validation runs lazily inside the policy constructor, which the runtime caches per policy name — so a misconfigured policy fails the first request with a `ConfigurationError` (surfaced in the 500 problem body) rather than crashing boot. | mcp-gateway |
-| mcp-capability-filter-inbound | MCP Capability Filter | Curate MCP capabilities advertised and reachable through `McpProxyHandler`.  Validation runs lazily inside the policy constructor, which the runtime caches per policy name. Misconfigured options therefore fail on first use with a customer-facing `ConfigurationError` instead of failing at module load. | mcp-gateway |
+| mcp-capability-filter-inbound | MCP Capability Filter | Curate MCP capabilities advertised and reachable through `McpProxyHandler`.  Validation runs lazily inside the policy constructor, which the runtime caches per policy name. Misconfigured options therefore fail on first use with a customer-facing `ConfigurationError` instead of failing at module load.  Optional per-caller access control (`accessControl`) narrows the curated catalog. See `claimsCapabilityResolver` for built-in role/group matching and `McpCapabilityResolver` for custom resolvers. | mcp-gateway |
 | mcp-clerk-oauth-inbound | MCP Clerk OAuth | Authenticate MCP gateway requests using a gateway-issued OAuth access token, with browser login delegated to Clerk.  Clerk-friendly wrapper around `McpOAuthInboundPolicy`. Provide Clerk's Frontend API URL plus the OAuth application client id and secret; the constructor derives the Clerk issuer, JWKS URL, authorize URL, and token URL. | mcp-gateway |
 | mcp-google-oauth-inbound | MCP Google OAuth | Authenticate MCP gateway requests using a gateway-issued OAuth access token, with browser login delegated to Google.  Google-friendly wrapper around `McpOAuthInboundPolicy`. Provide `clientId` and `clientSecret`; the constructor uses Google's fixed OIDC issuer, JWKS URL, authorize URL, and token URL, then runs the resulting shape through the same Zod schema as the generic policy. | mcp-gateway |
 | mcp-keycloak-oauth-inbound | MCP Keycloak OAuth | Authenticate MCP gateway requests using a gateway-issued OAuth access token, with browser login delegated to Keycloak.  Keycloak-friendly wrapper around `McpOAuthInboundPolicy`. Provide the Keycloak server root, realm, client id, and client secret; the constructor derives the realm issuer, JWKS URL, authorize URL, and token URL from Keycloak's documented OIDC endpoint layout. | mcp-gateway |

package/docs/policies/audit-log-inbound/doc.md

@@ -1,78 +1,137 @@
-## Adding Custom Metadata
+## Automatic Request Auditing
 
-You can add any additional data to the audit logs with a custom function.
+Once the Audit Logs policy is added to a route, it automatically records one
+structured audit event for every request that passes through it — no extra code
+required. Each event captures who made the request, what they called, and the
+outcome.
 
-:::note
+The automatic event uses the type `com.zuplo.api.request` and includes the
+actor, the HTTP method and path, the response status, and the geolocation of the
+caller.
 
-Custom metadata functions cannot be asynchronous. Due to the frequency of their
-calls, asynchronous functions will add significant latency to your API.
+For very high-volume routes you can record only a fraction of requests by
+setting the `samplingRate` option (for example `0.1` to capture 10% of
+requests).
 
-:::
+## Controlling What's Logged
 
-```ts
-//module - ./modules/audit-logs.ts
+Audit events can contain personal or sensitive data. To keep audit logging
+compliant with your own data-handling and PII policies, use the `include`
+option to turn individual fields off. Everything is captured by default; set a
+flag to `false` to omit it:
 
-import { ZuploRequest } from "@zuplo/runtime";
+- `queryParams` — the request's query-string parameters (in the logged URL).
+- `user` — the authenticated user / actor identity (subject, email,
+  connection). The `user` vs `anonymous` classification is always kept, but the
+  identifying values are omitted when disabled.
+- `ipAddress` — the caller's IP address.
+- `geolocation` — the caller's country, region, and city.
 
-export function auditLogMetadata(request: ZuploRequest): any {
-  const metadata = {
-    accountId: request.user.data.account,
-    customTraceId: request.headers.get("custom-trace-id"),
-  };
-  return metadata;
+```json
+{
+  "name": "audit-logs-inbound",
+  "policyType": "audit-logs",
+  "handler": {
+    "export": "AuditLogInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "include": {
+        "queryParams": false,
+        "ipAddress": false
+      }
+    }
+  }
 }
 ```
 
-## Log Data
+These settings also apply to the geolocation automatically added to custom
+events emitted via `log()`.
 
-The structure of an audit log is shown below.
+## Emitting Custom Events
 
-```json
-{
-  "route": "/customers/:customerId",
-  "method": "GET",
-  "query": {
-    "a": 1,
-    "b": 2
-  },
-  "params": {
-    "customerId": "12345"
-  },
-  "headers": {
-    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.41 Safari/537.36"
-  },
-  "user": {
-    "sub": "user|12356"
-  },
-  "geolocation": {
-    "country": "US",
-    "city": "Seattle",
-    "continent": "NA",
-    "latitude": "1.123",
-    "longitude": "4.567",
-    "postalCode": "29700",
-    "metroCode": "100",
-    "region": "Washington",
-    "timezone": "America/LosAngeles"
-  },
-  "metadata": {
-    // Custom data
-  }
+Beyond the automatic per-request event, you can record your own domain events —
+for example "account deleted" or "API key rotated" — from a handler or custom
+policy using the static `AuditLogInboundPolicy.log()` method. Any fields you
+don't supply are filled in automatically from the request context (event id,
+time, actor, request id, IP address, user agent, and so on).
+
+```ts
+// module - ./modules/audit.ts
+
+import {
+  AuditLogInboundPolicy,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export async function deleteAccount(
+  request: ZuploRequest,
+  context: ZuploContext
+) {
+  const accountId = request.params.accountId;
+
+  // ...perform the delete...
+
+  AuditLogInboundPolicy.log(context, {
+    type: "com.acme.account.deleted",
+    subject: `account|${accountId}`,
+    resources: [{ type: "account", id: accountId }],
+    success: true,
+    data: { reason: "user-initiated" },
+  });
+
+  return new Response(null, { status: 204 });
 }
 ```
 
-## Audit Logs in the Portal
+The event object passed to `log()` supports the following fields. Only `type` is
+required.
 
-Audit logs are not currently surfaced in the Zuplo portal, but the feature is
-planned soon.
+- `type` — the event type, in reverse-DNS form (e.g. `com.acme.account.deleted`).
+- `subject` — the primary entity the event is about.
+- `resources` — an array of `{ type, id, metadata? }` describing the resources
+  the event affected.
+- `success` — whether the operation succeeded.
+- `data` — any additional structured data to attach to the event.
+- `actor` — override the automatically-derived actor
+  (`{ sub, type, email, connection }`).
+- `country`, `region`, `city` — override the caller's geolocation. These
+  default to the current request's location, so you normally don't need to set
+  them.
 
-## Audit Log API
+Audit logging is best-effort: `log()` never throws and never blocks or fails the
+request, even if an event cannot be recorded.
 
-Audit logs can be retrieved using the Zuplo Management API. Logs can be
-retrieved by time span and can be filtered by `tenant`.
+## Audit Log Event Shape
 
-```http
-GET /deployments/:deploymentId/auditlogs?tenant=TENANT
-content-type: application/json
-authorization: Bearer YOUR_TOKEN
+Every audit event follows the [CloudEvents](https://cloudevents.io/) 1.0
+envelope. An automatically-emitted request event looks like this:
+
+```json
+{
+  "specversion": "1.0",
+  "id": "e6c8b1f2-2c3d-4a5b-9e10-1f2a3b4c5d6e",
+  "type": "com.zuplo.api.request",
+  "time": "2026-07-05T18:12:04.123Z",
+  "actorsub": "user|12356",
+  "actortype": "user",
+  "requestid": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
+  "httpmethod": "GET",
+  "httpurl": "/customers/12345?expand=orders",
+  "httpstatus": 200,
+  "success": true,
+  "ipaddress": "203.0.113.7",
+  "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
+  "country": "US",
+  "region": "Washington",
+  "city": "Seattle"
+}
 ```
+
+Custom events emitted via `log()` share the same envelope; the `type`,
+`subject`, `resources`, `success`, and `data` fields come from the event you
+pass, and the remaining fields are populated from the request context.
+
+## Viewing Audit Logs
+
+In-portal viewing and retrieval of audit logs is coming soon.

package/docs/policies/audit-log-inbound/schema.json

@@ -4,14 +4,14 @@
   "type": "object",
   "title": "Audit Logs",
   "isDeprecated": false,
-  "isPaidAddOn": true,
-  "isEnterprise": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
   "isInternal": false,
   "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
   "products": ["api-gateway"],
-  "description": "Capture detailed logs of requests for auditing purposes.",
+  "description": "Capture detailed logs of requests for auditing purposes. The policy emits one structured CloudEvent per request, and user code can emit additional events via the static `log()` method.",
   "deprecatedMessage": "",
   "required": ["handler"],
   "properties": {
@@ -21,7 +21,7 @@
       "required": ["export", "module", "options"],
       "properties": {
         "export": {
-          "const": "AuditLogsInboundPolicy",
+          "const": "AuditLogInboundPolicy",
           "description": "The name of the exported type"
         },
         "module": {
@@ -29,51 +29,71 @@
           "description": "The module containing the policy"
         },
         "options": {
-          "title": "AuditLogsInboundPolicyOptions",
+          "title": "AuditLogInboundPolicyOptions",
           "type": "object",
-          "description": "The options for this policy.",
+          "description": "The options for the Audit Log Inbound policy.",
           "additionalProperties": false,
-          "required": ["blockScoresBelow"],
+          "required": [],
           "properties": {
-            "logIpAddress": {
-              "default": true,
-              "description": "if the IP address should be logged."
+            "eventTypeBase": {
+              "type": "string",
+              "description": "Reverse-DNS prefix used for the auto-emitted request event type. Defaults to 'com.zuplo.api'.",
+              "default": "com.zuplo.api"
             },
-            "logUser": {
-              "default": true,
-              "description": "if the user's `sub` should be logged."
+            "bucketId": {
+              "type": "string",
+              "description": "Override the bucket id this policy emits events for. Defaults to the bucket id from the runtime environment."
             },
-            "logGeolocation": {
-              "default": true,
-              "description": "if the geolocation information should be logged (i.e. state, country, longitude, latitude, etc.)."
+            "samplingRate": {
+              "type": "number",
+              "description": "Fraction of requests to capture, between 0 (none) and 1 (all). Defaults to 1.",
+              "default": 1,
+              "minimum": 0,
+              "maximum": 1
             },
-            "logQueryParameters": {
-              "default": true,
-              "description": "log the values of query parameters."
-            },
-            "logRouteParameters": {
-              "default": true,
-              "description": "The parameters in the route to log."
-            },
-            "tenant": {
-              "description": "if the route parameters should be logged (i.e. the value of `customerId` in the route `/customers/:customerId`)."
-            },
-            "metadata": {
-              "description": "A function to add additional data to the audit logs."
+            "include": {
+              "type": "object",
+              "description": "Controls which potentially-sensitive parts of each request are captured in the auto-emitted audit event. Disable fields to satisfy your own data-handling and PII policies. All are enabled by default.",
+              "additionalProperties": false,
+              "properties": {
+                "queryParams": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Include the request's query-string parameters in the logged URL. Disable if query strings may contain sensitive data."
+                },
+                "user": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Include the authenticated user / actor identity (subject, email, connection)."
+                },
+                "ipAddress": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Include the caller's IP address."
+                },
+                "geolocation": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Include the caller's geolocation (country, region, city)."
+                }
+              }
             }
           }
         }
       },
       "examples": [
         {
-          "export": "AuditLogsInboundPolicy",
+          "export": "AuditLogInboundPolicy",
           "module": "$import(@zuplo/runtime)",
           "options": {
-            "logGeolocation": true,
-            "logIpAddress": true,
-            "logQueryParameters": true,
-            "logRouteParameters": true,
-            "logUser": true
+            "eventTypeBase": "com.zuplo.api",
+            "include": {
+              "geolocation": true,
+              "ipAddress": true,
+              "queryParams": true,
+              "user": true
+            },
+            "samplingRate": 1
           }
         }
       ]

package/docs/policies/mcp-capability-filter-inbound/doc.md

@@ -50,6 +50,138 @@ gateway-managed upstream OAuth credentials. That order lets the token exchange
 policy retry or replace a 401 response first; this policy then filters the final
 upstream JSON-RPC response.
 
+## Access control
+
+`accessControl` narrows the curated catalog **per caller**. Its `mode` selects
+the strategy:
+
+- **`allPublic`** (default): no access control — every curated capability is
+  available to all callers. Setting `roles`/`groups`/`public` on a capability in
+  this mode is a configuration error (it would silently do nothing).
+- **`rolesAndGroups`**: match the caller's roles and groups — read from
+  `request.user.data` (see below) — against each capability's markup.
+- **`function`**: delegate to a custom resolver.
+
+### Mode `rolesAndGroups`
+
+Mark each capability with `roles` and/or `groups`, or `public: true`. **Every
+capability must be classified** — one that sets neither (or both) is rejected at
+load, so nothing is ever exposed by omission:
+
+```json
+{
+  "options": {
+    "tools": [
+      { "name": "search_invoices", "roles": ["billing", "admin"] },
+      { "name": "create_invoice", "roles": ["admin"], "groups": ["finance"] },
+      { "name": "list_products", "public": true }
+    ],
+    "accessControl": { "mode": "rolesAndGroups" }
+  }
+}
+```
+
+A caller may use a capability if it is `public`, or if the caller matches any
+listed role **or** any listed group (so `create_invoice` above is available to
+admins or to the finance team). Anonymous callers get only `public`
+capabilities. `roles`/`groups`/`public` are enforcement markup and are stripped
+from downstream responses — use `_meta` for hints you want clients to see.
+
+The caller's roles and groups come from `request.user.data` — the object an
+upstream authentication policy sets for the authenticated caller. What lands
+there depends on the policy: a JWT auth policy stores the token's claims, an API
+key policy stores the key's metadata, and so on. This policy reads the `roles`
+and `groups` properties by default. For example, behind a JWT auth policy a
+token with these claims:
+
+```json
+{
+  "sub": "user_8f3a",
+  "roles": ["billing"],
+  "groups": ["sales"],
+  "iss": "https://acme.us.auth0.com/",
+  "aud": "https://mcp.acme.com",
+  "exp": 1893456000
+}
+```
+
+`request.user.data.roles` is `["billing"]` and `request.user.data.groups` is
+`["sales"]`. Against the config above, this caller may use `search_invoices`
+(matches the `billing` role) and the public `list_products`, but not
+`create_invoice` (which needs the `admin` role or the `finance` group). A
+request with no authenticated caller (no `request.user`) has no roles or groups,
+so it sees only `public` capabilities.
+
+Use `roleClaim`/`groupClaim` to read different `request.user.data` properties,
+including a dot-path for nested values or a literal namespaced key:
+
+```json
+{
+  "accessControl": { "mode": "rolesAndGroups", "groupClaim": "cognito:groups" }
+}
+```
+
+```json
+{
+  "accessControl": {
+    "mode": "rolesAndGroups",
+    "roleClaim": "realm_access.roles"
+  }
+}
+```
+
+### Mode `function`
+
+For any other mapping — looking up entitlements from an external API, requiring
+both a role AND a group, blocklists, etc. — set `mode: "function"` and point
+`identifier` at a resolver (same `{ module, export }` shape as rate-limit). **It
+fully replaces the built-in roles/groups matching.** It receives
+`(request, context, options)` and returns the allowed identifiers; the result is
+always clamped to the configured catalog, so a resolver can only narrow access.
+A capability type left as passthrough (no static list) is not narrowed. A
+resolver that throws or returns no value fails closed.
+
+```json
+{
+  "accessControl": {
+    "mode": "function",
+    "identifier": {
+      "module": "$import(./modules/mcp-access-control)",
+      "export": "default"
+    }
+  }
+}
+```
+
+```ts
+// modules/mcp-access-control.ts
+import { ZuploRequest, ZuploContext, environment } from "@zuplo/runtime";
+import type {
+  McpCapabilityFilterInboundPolicyOptions,
+  AllowedCapabilities,
+} from "@zuplo/runtime/mcp-gateway";
+
+export default async function resolveCapabilities(
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: McpCapabilityFilterInboundPolicyOptions
+): Promise<AllowedCapabilities> {
+  const subject = request.user?.sub;
+  if (!subject) return { tools: [] }; // fail closed for anonymous
+
+  const res = await fetch(
+    `https://entitlements.example.com/users/${encodeURIComponent(subject)}`,
+    { headers: { authorization: `Bearer ${environment.ENTITLEMENTS_API_KEY}` } }
+  );
+  if (!res.ok) {
+    context.log.warn(`entitlements lookup failed: ${res.status}`);
+    return { tools: [] };
+  }
+  const { allowedTools } = (await res.json()) as { allowedTools: string[] };
+  return { tools: allowedTools };
+}
+```
+
 ## Batch Requests
 
 For JSON-RPC batch requests, list responses are filtered per response item when

package/docs/policies/mcp-capability-filter-inbound/schema.json

@@ -11,7 +11,7 @@
   "isHidden": false,
   "requiresAI": false,
   "products": ["mcp-gateway"],
-  "description": "Curate MCP capabilities advertised and reachable through `McpProxyHandler`.\n\nValidation runs lazily inside the policy constructor, which the runtime caches per policy name. Misconfigured options therefore fail on first use with a customer-facing `ConfigurationError` instead of failing at module load.",
+  "description": "Curate MCP capabilities advertised and reachable through `McpProxyHandler`.\n\nValidation runs lazily inside the policy constructor, which the runtime caches per policy name. Misconfigured options therefore fail on first use with a customer-facing `ConfigurationError` instead of failing at module load.\n\nOptional per-caller access control (`accessControl`) narrows the curated catalog. See `claimsCapabilityResolver` for built-in role/group matching and `McpCapabilityResolver` for custom resolvers.",
   "deprecatedMessage": "",
   "required": ["handler"],
   "properties": {
@@ -67,6 +67,28 @@
                         "type": "object",
                         "additionalProperties": true,
                         "description": "Arbitrary MCP \\_meta fields to expose downstream."
+                      },
+                      "roles": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "description": "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'."
+                      },
+                      "groups": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "description": "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'."
+                      },
+                      "public": {
+                        "type": "boolean",
+                        "description": "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."
                       }
                     }
                   }
@@ -100,6 +122,28 @@
                         "type": "object",
                         "additionalProperties": true,
                         "description": "Arbitrary MCP \\_meta fields to expose downstream."
+                      },
+                      "roles": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "description": "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'."
+                      },
+                      "groups": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "description": "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'."
+                      },
+                      "public": {
+                        "type": "boolean",
+                        "description": "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."
                       }
                     }
                   }
@@ -143,6 +187,28 @@
                         "type": "object",
                         "additionalProperties": true,
                         "description": "Arbitrary MCP \\_meta fields to expose downstream."
+                      },
+                      "roles": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "description": "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'."
+                      },
+                      "groups": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "description": "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'."
+                      },
+                      "public": {
+                        "type": "boolean",
+                        "description": "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."
                       }
                     }
                   }
@@ -186,11 +252,76 @@
                         "type": "object",
                         "additionalProperties": true,
                         "description": "Arbitrary MCP \\_meta fields to expose downstream."
+                      },
+                      "roles": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "description": "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'."
+                      },
+                      "groups": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "description": "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'."
+                      },
+                      "public": {
+                        "type": "boolean",
+                        "description": "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."
                       }
                     }
                   }
                 ]
               }
+            },
+            "accessControl": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "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.",
+              "properties": {
+                "mode": {
+                  "type": "string",
+                  "enum": ["allPublic", "rolesAndGroups", "function"],
+                  "default": "allPublic",
+                  "description": "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'."
+                },
+                "roleClaim": {
+                  "type": "string",
+                  "minLength": 1,
+                  "default": "roles",
+                  "description": "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'."
+                },
+                "groupClaim": {
+                  "type": "string",
+                  "minLength": 1,
+                  "default": "groups",
+                  "description": "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'."
+                },
+                "identifier": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["module", "export"],
+                  "description": "Custom capability resolver, required when mode is 'function'. It fully replaces built-in roles/groups matching.",
+                  "properties": {
+                    "module": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Module to load the resolver from, e.g. $import(./modules/mcp-access-control)."
+                    },
+                    "export": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Named export of the resolver function, e.g. 'default'."
+                    }
+                  }
+                }
+              }
             }
           }
         }
@@ -200,6 +331,12 @@
           "export": "McpCapabilityFilterInboundPolicy",
           "module": "$import(@zuplo/runtime)",
           "options": {
+            "accessControl": {
+              "groupClaim": "groups",
+              "identifier": {},
+              "mode": "allPublic",
+              "roleClaim": "roles"
+            },
             "prompts": [],
             "resourceTemplates": [],
             "resources": [],

package/docs/policies/monetization-inbound/doc.md

@@ -59,6 +59,32 @@ import { MonetizationInboundPolicy } from "@zuplo/runtime";
 const meters = MonetizationInboundPolicy.getMeters(context);
 ```
 
+### Flush (send) runtime meters mid-request
+
+Use `flushMeters` to send accumulated runtime meters immediately and reset their
+counts. This is useful for long-running requests where you want to report
+partial usage before the response is sent (for example, after each chunk of work
+in a streaming handler).
+
+```typescript
+import { MonetizationInboundPolicy } from "@zuplo/runtime";
+
+MonetizationInboundPolicy.addMeters(context, { input_tokens: 500 });
+await MonetizationInboundPolicy.flushMeters(context);
+
+// Runtime meters are cleared before the backend send begins so a concurrent
+// final hook cannot double-count them. Meters are restored if the send fails.
+MonetizationInboundPolicy.addMeters(context, { input_tokens: 300 });
+```
+
+Static `options.meters` are not included in `flushMeters`; they are still sent
+in the final response hook.
+
+Note: `flushMeters` performs entitlement validation and will throw if called
+before the monetization policy runs on the request or if you send meters that
+aren’t present/accessible on the subscription. Wrap in `try/catch` if you want
+to continue the request when a flush fails.
+
 ## Subscription data (for customization)
 
 The monetization policy validates the API key and attaches the **subscription**
@@ -163,4 +189,7 @@ For a meter key like `api` with `options.meters.api = 1`:
 
 - `setMeters` replaces current request meter increments.
 - `addMeters` accumulates values across multiple calls.
+- `flushMeters` sends runtime meters immediately, clears them before the backend
+  send (to avoid duplicate sends if the final hook runs concurrently), and
+  restores them if the send fails.
 - Entitlements are validated before usage is sent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.71.26",
+  "version": "6.72.0",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.71.26",
-    "@zuplo/core": "6.71.26",
-    "@zuplo/runtime": "6.71.26",
+    "@zuplo/cli": "6.72.0",
+    "@zuplo/core": "6.72.0",
+    "@zuplo/runtime": "6.72.0",
     "@zuplo/test": "1.4.0"
   }
 }