@zuplo/runtime 6.66.11 → 6.66.13

package/out/types/index.d.ts

@@ -1870,6 +1870,8 @@ export declare interface ClerkJwtInboundPolicyOptions {
   oAuthResourceMetadataEnabled?: boolean;
 }
 
+/* Excluded from this release type: ClientConfig */
+
 /**
  * Authentication options for OIDC authentication.
  * @public
@@ -2577,12 +2579,16 @@ export declare class DataDogMetricsPlugin extends MetricsPlugin {
   static setContext(context: ZuploContext, data: DataDogMetricsContext): void;
 }
 
+/* Excluded from this release type: DcrClientRegistration */
+
 /**
  * Default function to generate Hydrolix log entries
  * @public
  */
 export declare const defaultGenerateHydrolixEntry: GenerateRequestLoggerEntry<HydrolixDefaultEntry>;
 
+/* Excluded from this release type: deleteUpstreamToken */
+
 /* Excluded from this release type: DevPortalRuntimeConfig */
 
 declare type DevPortalType = "legacy" | "zudoku";
@@ -2854,6 +2860,8 @@ declare interface GeoSpec {
   asns?: string;
 }
 
+/* Excluded from this release type: getDcrClient */
+
 /* Excluded from this release type: getIdForParameterSchema */
 
 /* Excluded from this release type: getIdForRefSchema */
@@ -2888,6 +2896,10 @@ declare interface GetQuotaResult {
 
 /* Excluded from this release type: getRawOperationDataIdentifierName */
 
+/* Excluded from this release type: getUpstreamMetadata */
+
+/* Excluded from this release type: getUpstreamToken */
+
 declare interface GoogleCloudLoggingOptions {
   serviceAccountJson: string;
   logName: string;
@@ -2982,6 +2994,41 @@ declare interface HeaderCredentialsConfig {
   headerName: string;
 }
 
+/**
+ * Sets HTTP deprecation headers on the outgoing response following the IETF
+ * HTTP Deprecation Header standard. Supports the Deprecation, Sunset, and Link
+ * headers.
+ *
+ * @title HTTP Deprecation
+ * @public
+ * @param response - The Response
+ * @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 Response with deprecation headers
+ */
+export declare const HttpDeprecationOutboundPolicy: OutboundPolicyHandler<HttpDeprecationOutboundPolicyOptions>;
+
+/**
+ * The options for the HTTP Deprecation outbound policy.
+ * @public
+ */
+export declare interface HttpDeprecationOutboundPolicyOptions {
+  /**
+   * The deprecation value. Use `true` for already deprecated, an ISO 8601 date string for a specific date, or a Unix timestamp number.
+   */
+  deprecation: true | string | number;
+  /**
+   * An ISO 8601 date string indicating when the endpoint will be removed. Sets the Sunset header.
+   */
+  sunset?: string;
+  /**
+   * A URL to documentation about the deprecation or migration guide. Sets the Link header.
+   */
+  link?: string;
+}
+
 /**
  * @public
  */
@@ -4516,6 +4563,8 @@ export declare interface HydrolixRequestLoggerPluginOptions<T> {
   batchPeriodSeconds?: number;
 }
 
+/* Excluded from this release type: IdpConfig */
+
 /**
  * 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
@@ -5330,6 +5379,16 @@ declare interface McpGatewayServerConfig {
    * Array of origin configurations for this server
    */
   origins: McpGatewayOrigin[];
+  /**
+   * OAuth resource name for this MCP server.
+   * When set, the gateway will look up upstream tokens using userId:resource
+   * and inject them into requests to the origin.
+   * This should match a resource key configured in the MCP OAuth Gateway plugin.
+   * @example "jira"
+   *
+   * // TODO: Make sure these are unique per origin
+   */
+  oauthResource?: string;
 }
 
 declare interface McpGatewayTool {
@@ -5338,6 +5397,98 @@ declare interface McpGatewayTool {
   inputSchema: object;
 }
 
+/**
+ * MCP OAuth Gateway Plugin
+ *
+ * This plugin implements an OAuth 2.0 Authorization Server that acts as a gateway
+ * between MCP clients and upstream OAuth providers. It enables a two-phase OAuth
+ * flow:
+ *
+ * 1. **Gateway IDP Authentication**: The client first authenticates with the gateway's
+ *    identity provider to establish user identity.
+ *
+ * 2. **Upstream Provider Authorization**: After IDP authentication, if the user hasn't
+ *    previously authorized the upstream resource (e.g., Jira, GitHub), they are
+ *    redirected to complete upstream OAuth authorization.
+ *
+ * The gateway maintains tokens for upstream providers and can skip the upstream
+ * authorization step on subsequent requests if valid tokens exist.
+ *
+ * ## Registered Routes
+ *
+ * - `GET /.well-known/oauth-authorization-server` - OAuth Authorization Server Metadata (RFC 8414)
+ * - `GET /oauth/:resource/authorize` - Authorization endpoint (entry point)
+ * - `GET /oauth/idp-callback` - IDP callback (receives auth code from gateway IDP)
+ * - `GET /oauth/upstream-callback` - Upstream callback (receives auth code from upstream)
+ * - `POST /oauth/token` - Token endpoint (exchanges codes for tokens)
+ * - `POST /oauth/register` - Dynamic Client Registration proxy (if IDP supports DCR)
+ *
+ * ## Configuration Example
+ *
+ * ```typescript
+ * import { McpOAuthGatewayPlugin, RuntimeExtensions } from "@zuplo/runtime";
+ *
+ * export function runtimeInit(runtime: RuntimeExtensions) {
+ *   runtime.addPlugin(
+ *     new McpOAuthGatewayPlugin({
+ *       idp: {
+ *         baseUrl: "https://zuplo-playground.us.auth0.com",
+ *         clientId: process.env.IDP_CLIENT_ID,
+ *         clientSecret: process.env.IDP_CLIENT_SECRET,
+ *       },
+ *       upstreams: {
+ *         jira: {
+ *           baseUrl: "https://mcp.atlassian.com",
+ *           scopes: ["read:jira-work", "write:jira-work"],
+ *           clientName: "My MCP Gateway",
+ *         },
+ *       },
+ *       clients: {
+ *         "my-mcp-client": {
+ *           redirectUris: ["http://localhost:3000/callback"],
+ *         },
+ *       },
+ *     })
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare class McpOAuthGatewayPlugin extends SystemRuntimePlugin {
+  #private;
+  private readonly options;
+  constructor(options: McpOAuthGatewayPluginOptions);
+  /* Excluded from this release type: registerRoutes */
+}
+
+/**
+ * Options for the MCP OAuth Gateway plugin.
+ * @public
+ */
+export declare interface McpOAuthGatewayPluginOptions {
+  /**
+   * Gateway IDP configuration (Zuplo's auth or another identity provider).
+   */
+  idp: IdpConfig;
+  /**
+   * Upstream provider configurations keyed by resource name.
+   * @example { jira: { ... }, github: { ... } }
+   */
+  upstreams: Record<string, UpstreamConfig>;
+  /**
+   * Registered client configurations keyed by client ID.
+   * For POC, this is static configuration. In production, this would be
+   * backed by Dynamic Client Registration (DCR).
+   */
+  clients: Record<string, ClientConfig>;
+  /**
+   * Authorization endpoint path to advertise in OAuth metadata.
+   * Defaults to "/oauth/:resource/authorize".
+   */
+  authorizationEndpointPath?: string;
+}
+
 /**
  * An MCP Server handler for Zuplo
  * Only POST requests are supported for the HTTP streamable MCP transport.
@@ -7261,7 +7412,9 @@ declare type RateLimitFunction<T extends CustomRateLimitDetailsBase> = (
   policyName: string
 ) =>
   | (Partial<T> & CustomRateLimitDetailsBase)
-  | Promise<Partial<T> & CustomRateLimitDetailsBase>;
+  | undefined
+  | null
+  | Promise<(Partial<T> & CustomRateLimitDetailsBase) | undefined | null>;
 
 /**
  * Adds the retry-after header.
@@ -7360,6 +7513,24 @@ declare type RateLimitHeaderMode_2 = "none" | "retry-after";
  *   }
  * };
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Skip rate limiting for specific conditions (return undefined)
+ * import { CustomRateLimitFunction, CustomRateLimitDetails } from "@zuplo/runtime";
+ *
+ * export const customRateLimitWithSkip: CustomRateLimitFunction = async (
+ *   request,
+ *   context
+ * ): Promise<CustomRateLimitDetails | undefined> => {
+ *   // Skip rate limiting for whitelisted IPs or internal services
+ *   const clientIp = request.headers.get("cf-connecting-ip");
+ *   if (isWhitelisted(clientIp)) {
+ *     return undefined;  // Skip rate limiting entirely - no Redis call
+ *   }
+ *   return { key: `user-${request.user?.sub}` };
+ * };
+ * ```
  */
 declare const RateLimitInboundPolicy: InboundPolicyHandler<RateLimitInboundPolicyOptions>;
 export { RateLimitInboundPolicy as BasicRateLimitInboundPolicy };
@@ -8261,6 +8432,8 @@ export declare interface SetBodyInboundPolicyOptions {
   body: string;
 }
 
+/* Excluded from this release type: setDcrClient */
+
 /**
  * Adds or sets headers on the incoming request.
  *
@@ -8411,6 +8584,10 @@ export declare interface SetStatusOutboundPolicyOptions {
   statusText?: string;
 }
 
+/* Excluded from this release type: setUpstreamMetadata */
+
+/* Excluded from this release type: setUpstreamToken */
+
 /**
  * Function type for determining if a request should be logged
  * @public
@@ -8773,6 +8950,8 @@ declare interface UnauthenticatedCredentialConfig {
   method: "none";
 }
 
+/* Excluded from this release type: UpstreamAuthServerMetadata */
+
 /**
  * Uses Azure Active Directory to add an Authorization header to the request
  * in order to authenticate requests using Azure identity.
@@ -8814,6 +8993,8 @@ export declare interface UpstreamAzureAdServiceAuthInboundPolicyOptions {
   expirationOffsetSeconds?: number;
 }
 
+/* Excluded from this release type: UpstreamConfig */
+
 /**
  * Creates a Firebase Admin token and attaches it to the outgoing request.
  * Useful when calling Firebase services as an administrator.
@@ -9044,6 +9225,8 @@ export declare interface UpstreamGcpServiceAuthInboundPolicyOptions {
   version?: 1 | 2;
 }
 
+/* Excluded from this release type: UpstreamTokens */
+
 /**
  * Generates a Zuplo JWT token and attaches it to the outgoing request. This
  * policy creates a self-signed JWT using the Zuplo JWT plugin and adds it

package/package.json

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