@zuplo/runtime 6.70.24 → 6.70.26

package/out/types/index.d.ts

@@ -6106,16 +6106,24 @@ export declare const MTLSAuthInboundPolicy: InboundPolicyHandler<MTLSAuthInbound
  * The options for this policy.
  * @public
  */
-export declare interface MTLSAuthInboundPolicyOptions {
+export declare type MTLSAuthInboundPolicyOptions = (
+  | {
+      [k: string]: unknown;
+    }
+  | {
+      allowUnauthenticatedRequests: true;
+      [k: string]: unknown;
+    }
+) & {
   /**
    * Allows requests to continue even when mTLS verification fails, no client certificate is presented, or the certificate metadata cannot be parsed. Defaults to false.
    */
   allowUnauthenticatedRequests?: boolean;
   /**
-   * Optional fully qualified issuer distinguished name to require on the client certificate. When set, the policy rejects certificates whose parsed issuer DN does not match this string exactly. The expected format matches the parsed metadata issuer, e.g. "CN=example-ca, O=Example, C=US".
+   * Fully qualified issuer distinguished name to require on the client certificate. The policy rejects certificates whose parsed issuer DN does not match this string exactly. Required unless `allowUnauthenticatedRequests` is `true`. The expected format matches the parsed metadata issuer, e.g. "CN=example-ca, O=Example, C=US".
    */
   certIssuerDN?: string;
-}
+};
 
 /**
  * Parsed client certificate metadata attached by the mTLS auth policy.
@@ -7410,6 +7418,7 @@ declare interface ParsedCorsPolicyConfiguration {
  */
 declare interface ParsedRouteData extends Omit<RouteData, "corsPolicies"> {
   corsPolicies: ParsedCorsPolicyConfiguration[];
+  /* Excluded from this release type: getInboundPolicyInstance */
 }
 
 /**

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

@@ -504,52 +504,62 @@ declare type HttpStatusCodeRangeDefinition =
   | "5XX";
 
 /**
- * A function-based inbound policy that can modify the incoming HTTP request.
- * This is the simplest way to create custom policies without extending a class.
- *
- * @param request - The incoming Request
- * @param context - The current context of the Request
- * @param options - The configuration options for the policy
- * @param policyName - The name set on the policy in the configuration
- * @returns A Response to short-circuit or a Request to continue
+ * A policy that can modify the incoming HTTP request before it is sent to
+ * the handler. If a response is returned, the request is short-circuited and
+ * the response is returned to the client. If a Request is returned, policies
+ * or a handler that follow are executed.
  *
  * @public
  * @example
  * ```typescript
- * import { InboundPolicyHandler } from "@zuplo/runtime";
+ * import { InboundPolicy, ZuploContext, ZuploRequest } from "@zuplo/runtime";
  *
- * interface RateLimitOptions {
- *   requests: number;
- *   windowMs: number;
+ * interface MyPolicyOptions {
+ *   headerName: string;
+ *   headerValue: string;
  * }
  *
- * export const rateLimitPolicy: InboundPolicyHandler<RateLimitOptions> = async (
- *   request,
- *   context,
- *   options,
- *   policyName
- * ) => {
- *   const key = request.headers.get("x-api-key") || "anonymous";
- *   const count = await incrementCounter(key, options.windowMs);
+ * export class AddHeaderPolicy extends InboundPolicy<MyPolicyOptions> {
+ *   async handler(request: ZuploRequest, context: ZuploContext) {
+ *     // Add a custom header
+ *     request.headers.set(this.options.headerName, this.options.headerValue);
  *
- *   if (count > options.requests) {
- *     return new Response("Too Many Requests", { status: 429 });
- *   }
+ *     // Log the action
+ *     context.log.info(`Added header ${this.options.headerName}`);
  *
- *   // Add rate limit headers
- *   request.headers.set("X-RateLimit-Limit", options.requests.toString());
- *   request.headers.set("X-RateLimit-Remaining", (options.requests - count).toString());
+ *     // Continue to next policy/handler
+ *     return request;
+ *   }
+ * }
  *
- *   return request;
- * };
+ * // Usage in policies.json:
+ * // {
+ * //   "name": "add-custom-header",
+ * //   "policyType": "custom-add-header-policy",
+ * //   "handler": {
+ * //     "export": "AddHeaderPolicy",
+ * //     "module": "$import(./policies/add-header)",
+ * //     "options": {
+ * //       "headerName": "X-Custom-Header",
+ * //       "headerValue": "My Value"
+ * //     }
+ * //   }
+ * // }
  * ```
  */
-declare interface InboundPolicyHandler<TOptions = any> {
-  (
+declare abstract class InboundPolicy<
+  TOptions = any,
+> extends PolicyBase<TOptions> {
+  /**
+   * The handler that is called each time this policy is invoked
+   *
+   * @param request - The incoming Request
+   * @param context - The current context of the Request
+   * @returns A Response or Request object
+   */
+  abstract handler(
     request: ZuploRequest,
-    context: ZuploContext,
-    options: TOptions,
-    policyName: string
+    context: ZuploContext
   ): Promise<ZuploRequest | Response>;
 }
 
@@ -937,22 +947,27 @@ declare interface Logger extends BaseLogger {
  * 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 wrapper derives the OIDC issuer, JWKS URL,
- * and Auth0 authorize/token endpoints automatically. The resolved options are
- * translated into the generic `McpOAuthRuntimeConfig` at gateway initialization
- * time (see `setupRoutes`); this request-time entry point delegates straight
- * to the underlying OAuth implementation.
+ * 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.
  *
  * @hidden
  * @title MCP Auth0 OAuth
- * @param request - The ZuploRequest
- * @param context - The ZuploContext
- * @param _options - The policy options set in policies.json
- * @param _policyName - The name of the policy as set in policies.json
- * @returns A Request or a Response
  */
-export declare const McpAuth0OAuthInboundPolicy: InboundPolicyHandler<McpAuth0OAuthInboundPolicyOptions>;
+export declare class McpAuth0OAuthInboundPolicy extends InboundPolicy<McpAuth0OAuthInboundPolicyOptions> {
+  #private;
+  constructor(rawOptions: unknown, policyName: string);
+  handler(
+    request: ZuploRequest,
+    context: ZuploContext
+  ): Promise<ZuploRequest | Response>;
+}
 
 /**
  * The options for this policy.
@@ -964,9 +979,9 @@ export declare interface McpAuth0OAuthInboundPolicyOptions {
    */
   auth0Domain: string;
   /**
-   * Expected audience claim on tokens issued for the gateway. Surfaces both as the OIDC token audience and as the Auth0 authorize?audience= parameter.
+   * Optional Auth0 API audience. When set, the gateway sends it as the Auth0 authorize?audience= parameter and validates returned provider access tokens against it. Leave unset when Auth0 is only used for browser identity.
    */
-  audience: string;
+  audience?: string;
   /**
    * The Auth0 client_id registered for the gateway's browser login flow.
    */
@@ -1042,21 +1057,22 @@ export declare class McpGatewayPlugin extends SystemRuntimePlugin {
  * to the OpenID Connect identity provider configured via the `oidc` and
  * `browserLogin` policy options.
  *
- * The runtime resolves the policy options into a `McpOAuthRuntimeConfig` at
- * gateway-initialization time and threads them into the underlying OAuth
- * implementation. This policy's request-time job is to validate the bearer
- * token presented by the MCP client and hydrate the principal onto the
- * request context.
+ * 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.
  *
  * @hidden
  * @title MCP OAuth
- * @param request - The ZuploRequest
- * @param context - The ZuploContext
- * @param _options - The policy options set in policies.json
- * @param _policyName - The name of the policy as set in policies.json
- * @returns A Request or a Response
  */
-export declare const McpOAuthInboundPolicy: InboundPolicyHandler<McpOAuthInboundPolicyOptions>;
+export declare class McpOAuthInboundPolicy extends InboundPolicy<McpOAuthInboundPolicyOptions> {
+  #private;
+  constructor(rawOptions: unknown, policyName: string);
+  handler(
+    request: ZuploRequest,
+    context: ZuploContext
+  ): Promise<ZuploRequest | Response>;
+}
 
 /**
  * The options for this policy.
@@ -1141,19 +1157,27 @@ export declare interface McpOAuthInboundPolicyOptions {
 }
 
 /**
- * Bind a route to an upstream MCP server. Stores the resolved upstream binding
- * on the request context for `McpVirtualServerHandler`, which resolves
- * credentials during capability dispatch.
+ * Bind a route to an upstream MCP server. Resolves the upstream connection
+ * config plus per-request credential and appends a
+ * `ResolvedUpstreamBindingContext` onto the request context for
+ * `McpVirtualServerHandler` to pick up during capability dispatch.
+ *
+ * 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.
  *
  * @hidden
  * @title MCP Upstream Connection
- * @param request - The ZuploRequest
- * @param context - The ZuploContext
- * @param options - The policy options set in policies.json
- * @param policyName - The name of the policy as set in policies.json
- * @returns A Request or a Response
  */
-export declare const McpUpstreamConnectionInboundPolicy: InboundPolicyHandler<McpUpstreamConnectionInboundPolicyOptions>;
+export declare class McpUpstreamConnectionInboundPolicy extends InboundPolicy<McpUpstreamConnectionInboundPolicyOptions> {
+  #private;
+  constructor(rawOptions: unknown, policyName: string);
+  handler(
+    request: ZuploRequest,
+    context: ZuploContext
+  ): Promise<ZuploRequest | Response>;
+}
 
 /**
  * The options for this policy.
@@ -1247,6 +1271,58 @@ export declare interface McpUpstreamConnectionInboundPolicyOptions {
   };
 }
 
+/**
+ * Thin MCP upstream proxy. Pair this with `McpOAuthInboundPolicy` (or
+ * `McpAuth0OAuthInboundPolicy`) plus `McpUpstreamConnectionInboundPolicy`:
+ * the OAuth policy authenticates the request, the upstream-connection
+ * policy resolves a single upstream binding onto the request context, and
+ * this handler:
+ *
+ * 1. Reads the resolved binding off the context.
+ * 2. Resolves the per-request upstream credential (handling user OAuth
+ *    via the connection's auth provider when configured).
+ * 3. Builds a new `Request` targeting the upstream's MCP HTTP endpoint
+ *    with the customer's body and headers, plus the resolved credential
+ *    translated to `Authorization` / custom request headers.
+ * 4. `fetch`-es the upstream and returns the response untouched.
+ *
+ * Use this for the common single-upstream pass-through case (the new
+ * recommended shape). For multi-upstream aggregation or curated catalogs,
+ * use `McpVirtualServerHandler` instead.
+ *
+ * Any customer-supplied policy attached between the upstream-connection
+ * policy and this handler can observe or transform the rewritten
+ * `Request` before it leaves the gateway.
+ *
+ * @beta
+ *
+ * @example
+ * ```json
+ * // routes.oas.json — single-upstream MCP proxy
+ * {
+ *   "paths": {
+ *     "/mcp/linear": {
+ *       "post": {
+ *         "x-zuplo-route": {
+ *           "handler": {
+ *             "module": "$import(@zuplo/runtime)",
+ *             "export": "mcpUpstreamHandler"
+ *           },
+ *           "policies": {
+ *             "inbound": ["mcp-oauth", "mcp-upstream-linear"]
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function mcpUpstreamHandler(
+  request: ZuploRequest,
+  context: ZuploContext
+): Promise<Response>;
+
 /**
  * Implements the server-side MCP request lifecycle for the gateway. Pair with
  * `McpOAuthInboundPolicy` (or `McpAuth0OAuthInboundPolicy`) plus an
@@ -1911,6 +1987,20 @@ declare interface ParsedCorsPolicyConfiguration {
  */
 declare interface ParsedRouteData extends Omit<RouteData, "corsPolicies"> {
   corsPolicies: ParsedCorsPolicyConfiguration[];
+  /* Excluded from this release type: getInboundPolicyInstance */
+}
+
+/**
+ * The base class for inbound and outbound policies.
+ * Provides common functionality for all policy types.
+ *
+ * @public
+ */
+declare abstract class PolicyBase<TOptions = any> {
+  options: TOptions;
+  policyName: string;
+  policyType: string;
+  /* Excluded from this release type: __constructor */
 }
 
 /**

package/package.json

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