@cloudflare/workers-oauth-provider 0.6.0 → 0.7.1

package/README.md

@@ -117,6 +117,10 @@ export default new OAuthProvider({
   // Defaults to false.
   allowTokenExchangeGrant: false,
 
+  // Optional: Experimental MCP Enterprise-Managed Authorization support.
+  // When enabled, the token endpoint accepts ID-JAG JWTs with the JWT bearer grant.
+  enterpriseManagedAuthorization: undefined,
+
   // Optional: Explicitly enable Client ID Metadata Document (CIMD) support.
   // When true, URL-formatted client_ids will be fetched as metadata documents.
   // Requires the 'global_fetch_strictly_public' compatibility flag.
@@ -352,6 +356,42 @@ async function refreshUpstream(props) {
 
 Only `OAuthError` from this package is converted into a structured `/token` response. Plain errors, plain objects with a `code` field, and app-local error classes continue to surface as 500s so unexpected failures stay visible. Import `OAuthError` from `@cloudflare/workers-oauth-provider` rather than copying or re-implementing it.
 
+## Enterprise-Managed Authorization (Experimental)
+
+Accepts ID-JAG assertions at `/token` per the [MCP Enterprise-Managed Authorization extension](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization). The enterprise IdP issues an ID-JAG JWT and the MCP client exchanges it here for an opaque access token.
+
+```ts
+new OAuthProvider({
+  // ... other options ...
+  resourceMetadata: { resource: 'https://mcp.example.com/mcp' },
+  enterpriseManagedAuthorization: {
+    trustedIssuers: async ({ iss }) =>
+      iss === 'https://idp.example.com'
+        ? { issuer: iss, jwksUri: 'https://idp.example.com/.well-known/jwks.json', algorithms: ['RS256'] }
+        : null,
+    async mapClaims({ claims, requestedScope }) {
+      return {
+        // Opaque tokens use ':' as a separator — encode subjects that may contain it.
+        userId: `enterprise-${claims.sub}`,
+        scope: requestedScope,
+        metadata: { enterpriseIssuer: claims.iss, enterpriseSubject: claims.sub },
+        props: { enterprise: true, subject: claims.sub, email: claims.email },
+      };
+    },
+  },
+});
+```
+
+Setup:
+
+1. Configure your IdP as an ID-JAG issuer with this worker's origin as the resource and a public JWKS endpoint.
+2. Set `resourceMetadata.resource` to the MCP endpoint URL (required when EMA is enabled).
+3. Implement `trustedIssuers` as a resolver — for multi-tenant deployments it can read `env` / `clientInfo` to look up per-tenant IdP config without redeploying.
+
+The AS enforces `resolved.issuer === iss` (confused-deputy guard) and validates ID-JAG `typ`, signature, audience, client binding, resource, `exp` / `iat` / `nbf`, max lifetime, and `jti` replay. Refresh tokens are not issued for this grant — the ID-JAG itself is the renewable assertion.
+
+Experimental — the MCP extension is still a draft.
+
 ## Custom Error Responses
 
 By using the `onError` option, you can emit notifications or take other actions when an error response was to be emitted:
@@ -434,6 +474,7 @@ This library implements the following OAuth and MCP specifications:
 - [OAuth 2.0 Protected Resource Metadata (RFC 9728)](https://datatracker.ietf.org/doc/html/rfc9728) — `/.well-known/oauth-protected-resource` discovery endpoint
 - [OAuth 2.0 Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) — Dynamic client registration endpoint
 - [OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document) — HTTPS URLs as client IDs
+- [MCP Enterprise-Managed Authorization extension](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization) — experimental ID-JAG JWT bearer grant support
 
 These are the specifications required by the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
 

package/dist/oauth-provider.d.ts

@@ -1,7 +1,277 @@
 import { WorkerEntrypoint } from "cloudflare:workers";
 
-//#region src/oauth-provider.d.ts
+//#region src/ema/result.d.ts
 
+/**
+ * Tagged union of every validation failure that can occur on the EMA token
+ * endpoint path. Extend by adding a new arm; the exhaustive `switch` in
+ * `emaErrorToWire` will surface unhandled cases at compile time.
+ */
+type EmaValidationError = {
+  reason: 'assertion_missing';
+} | {
+  reason: 'assertion_too_large';
+  size: number;
+  max: number;
+} | {
+  reason: 'assertion_malformed';
+} | {
+  reason: 'invalid_typ';
+  got?: unknown;
+} | {
+  reason: 'invalid_alg';
+  got?: unknown;
+} | {
+  reason: 'issuer_not_trusted';
+  iss: string;
+} | {
+  reason: 'no_matching_key';
+  kid?: string;
+} | {
+  reason: 'signature_failed';
+} | {
+  reason: 'jwks_fetch_failed';
+  status?: number;
+} | {
+  reason: 'invalid_claim';
+  claim: string;
+} | {
+  reason: 'aud_mismatch';
+  expected: string;
+  got: string | string[];
+} | {
+  reason: 'expired';
+  exp: number;
+  now: number;
+} | {
+  reason: 'iat_in_future';
+  iat: number;
+  now: number;
+  skew: number;
+} | {
+  reason: 'nbf_in_future';
+  nbf: number;
+  now: number;
+  skew: number;
+} | {
+  reason: 'lifetime_too_long';
+  lifetime: number;
+  max: number;
+} | {
+  reason: 'replayed';
+  jti: string;
+} | {
+  reason: 'client_id_mismatch';
+  expected: string;
+  got: string;
+} | {
+  reason: 'resource_invalid';
+  resource: string;
+} | {
+  reason: 'resource_mismatch';
+  expected: string;
+  got: string;
+} | {
+  reason: 'invalid_scope_param';
+} | {
+  reason: 'invalid_mapped_user';
+} | {
+  reason: 'invalid_mapped_scope';
+} | {
+  reason: 'invalid_mapped_props';
+} | {
+  reason: 'invalid_mapped_ttl';
+} | {
+  reason: 'mapper_denied';
+} | {
+  reason: 'mapper_threw';
+} | {
+  reason: 'assertion_expired_after_processing';
+};
+//#endregion
+//#region src/ema/types.d.ts
+/**
+ * Claims expected in an MCP Enterprise-Managed Authorization ID-JAG assertion.
+ * Additional issuer-specific claims (e.g. `email`) are preserved verbatim
+ * under the index signature.
+ */
+interface EmaIdJagClaims {
+  /** Identity provider issuer URL. */
+  iss: string;
+  /** Enterprise subject identifier for the resource owner. */
+  sub: string;
+  /** Authorization server issuer URL or URLs for which this assertion is intended. */
+  aud: string | string[];
+  /** RFC 9728 resource identifier of the MCP server. */
+  resource: string;
+  /** OAuth client identifier this assertion was issued to. */
+  client_id: string;
+  /** Unique assertion identifier used for replay protection. */
+  jti: string;
+  /** Assertion expiration time as a Unix timestamp in seconds. */
+  exp: number;
+  /** Assertion issued-at time as a Unix timestamp in seconds. */
+  iat: number;
+  /** Optional space-separated OAuth scope string. */
+  scope?: string;
+  /** Optional email claim supplied by the enterprise IdP. */
+  email?: string;
+  /** Additional enterprise IdP claims. */
+  [claim: string]: unknown;
+}
+/**
+ * Trusted enterprise IdP configuration for ID-JAG validation.
+ */
+interface EmaTrustedIssuer {
+  /** Issuer URL that must exactly match the assertion `iss` claim. */
+  issuer: string;
+  /** HTTPS JWKS endpoint used to validate assertion signatures. */
+  jwksUri: string;
+  /** Allowed JWT signing algorithms for this issuer. Defaults to `['RS256']`. */
+  algorithms?: string[];
+  /** Expected authorization server audience. Defaults to this provider's issuer URL. */
+  audience?: string;
+}
+/**
+ * Input passed to `enterpriseManagedAuthorization.mapClaims` after ID-JAG validation.
+ */
+interface EmaClaimsMapperInput<Env = Cloudflare.Env> {
+  /** Validated ID-JAG claims. */
+  claims: EmaIdJagClaims;
+  /** Authenticated OAuth client that presented the assertion. */
+  clientInfo: ClientInfo;
+  /** Validated MCP resource identifier from the assertion. */
+  resource: string;
+  /** Requested scopes after downscoping to the assertion's scope claim, if present. */
+  requestedScope: string[];
+  /** The original HTTP token request, e.g. for inspecting Host header in multi-tenant routing. */
+  request: Request;
+  /** Cloudflare Worker environment variables. */
+  env: Env;
+}
+/**
+ * Result returned by `enterpriseManagedAuthorization.mapClaims`.
+ */
+interface EmaClaimsMapperResult {
+  /**
+   * User ID to associate with the issued grant and access token.
+   *
+   * Must not contain `:` — the opaque access token format issued by this
+   * provider uses `:` as an internal separator, so a `userId` containing
+   * it will produce tokens that fail to parse on validation. If the IdP
+   * subject may contain `:` (e.g. an email), encode or hash it first
+   * (e.g. ``userId: `enterprise-${encodeURIComponent(claims.sub)}` ``).
+   */
+  userId: string;
+  /** Scopes to grant to the issued access token. */
+  scope: string[];
+  /**
+   * Optional grant metadata used for audit and grant listing. This is not
+   * encrypted. Stored on the grant in KV alongside the user ID — visible to
+   * server-side code via `OAuthHelpers` but never exposed to the MCP client.
+   * Use for audit logs, admin UIs, or "list active sessions" features.
+   */
+  metadata?: unknown;
+  /**
+   * Application props encrypted into the issued access token and exposed to
+   * API handlers on every authenticated request (via `getMcpAuthContext()`
+   * for MCP servers, or `ctx.props` in the underlying OAuth helpers). Use
+   * for per-request data the protected resource needs without hitting the
+   * IdP again — e.g. `enterprise: true`, subject, email, role claims.
+   */
+  props: unknown;
+  /**
+   * Optional access token TTL override in seconds. Overrides the AS's
+   * configured default. Not clamped to the assertion lifetime — the ID-JAG
+   * `exp` governs how long the assertion remains a usable grant, not the
+   * lifetime of the access token it mints (RFC 7523 §3).
+   */
+  accessTokenTTL?: number;
+}
+/**
+ * Maps validated enterprise ID-JAG claims to this provider's local user, scopes,
+ * metadata, and props. Return `null` to deny token issuance.
+ *
+ * Always async — mirrors `EmaTrustedIssuerResolver` so the two enterprise
+ * callbacks have the same shape and downstream lookups (KV, D1, IdP federation)
+ * don't require a later API change to add `Promise<…>` return support.
+ */
+type EmaClaimsMapper<Env = Cloudflare.Env> = (input: EmaClaimsMapperInput<Env>) => Promise<EmaClaimsMapperResult | null>;
+/**
+ * Input passed to a dynamic `EmaTrustedIssuerResolver`.
+ *
+ * The `iss` value comes from the assertion's unverified payload — it is
+ * used here only as a routing key to choose which IdP's JWKS to load.
+ * The cryptographic trust comes from signature verification later, so
+ * the resolver may safely treat `iss` as untrusted input.
+ */
+interface EmaTrustedIssuerResolverInput<Env = Cloudflare.Env> {
+  /** Issuer URL from the assertion's `iss` claim (unverified). */
+  iss: string;
+  /** Cloudflare Worker environment variables (bindings, secrets, KV, D1). */
+  env: Env;
+  /** The original HTTP request, e.g. for inspecting the Host header in multi-tenant routing. */
+  request: Request;
+  /** Authenticated OAuth client that presented the assertion. */
+  clientInfo: ClientInfo;
+}
+/**
+ * Dynamic resolver for `EmaOptions.trustedIssuers`.
+ *
+ * Returns the trusted issuer configuration for an incoming `iss` claim,
+ * or `null` if the issuer is not trusted for this client / tenant. The
+ * returned `issuer` field must equal the input `iss` — the AS enforces
+ * this to prevent a resolver from being tricked into returning a config
+ * for a different IdP than the one the assertion claims to be from.
+ *
+ * Useful for B2B platforms where new tenants onboard their own IdPs
+ * dynamically and the AS cannot ship a static list at deploy time.
+ *
+ * **SSRF warning**: `jwksUri` is fetched outbound by the AS. If your
+ * resolver reads `jwksUri` from tenant-controlled storage (self-service
+ * tenant onboarding, etc.), an attacker who controls a tenant config
+ * can point the AS at arbitrary HTTPS endpoints — internal services,
+ * cloud metadata endpoints, victim hosts for DoS amplification. The
+ * library only enforces `https:`; deployers must validate `jwksUri`
+ * against their own allowlist (e.g. registered IdP vendor domains)
+ * before storing or returning it.
+ */
+type EmaTrustedIssuerResolver<Env = Cloudflare.Env> = (input: EmaTrustedIssuerResolverInput<Env>) => Promise<EmaTrustedIssuer | null>;
+/**
+ * MCP Enterprise-Managed Authorization configuration.
+ *
+ * Presence of this option on `OAuthProviderOptions` enables the EMA grant.
+ * There is intentionally no `enabled` flag — forgetting to set it would
+ * silently disable the feature despite full configuration.
+ */
+interface EmaOptions<Env = Cloudflare.Env> {
+  /**
+   * Resolver that returns the trusted issuer configuration for an
+   * incoming `iss` claim, or `null` to reject the assertion.
+   *
+   * Always a function — for a fixed list of IdPs, write a one-line closure:
+   *
+   * ```ts
+   * const issuers = [{ issuer: 'https://idp.example.com', jwksUri: '...' }];
+   * trustedIssuers: async ({ iss }) => issuers.find((i) => i.issuer === iss) ?? null,
+   * ```
+   *
+   * For B2B / multi-tenant deployments, the resolver can consult `env`,
+   * `request`, or `clientInfo` to look up the issuer dynamically (e.g.
+   * a per-tenant config in KV / D1) without redeploying.
+   */
+  trustedIssuers: EmaTrustedIssuerResolver<Env>;
+  /** Maps validated enterprise claims to local token data. */
+  mapClaims: EmaClaimsMapper<Env>;
+  /** JWKS cache TTL in seconds. Defaults to 300 seconds. */
+  jwksCacheTtlSeconds?: number;
+  /** Allowed clock skew for `exp` and `iat` checks in seconds. Defaults to 60 seconds. */
+  clockSkewSeconds?: number;
+  /** Maximum accepted assertion lifetime in seconds. Defaults to 300 seconds. */
+  maxAssertionLifetimeSeconds?: number;
+}
+//#endregion
+//#region src/oauth-provider.d.ts
 /**
  * Enum representing OAuth grant types
  */
@@ -9,6 +279,7 @@ declare enum GrantType {
   AUTHORIZATION_CODE = "authorization_code",
   REFRESH_TOKEN = "refresh_token",
   TOKEN_EXCHANGE = "urn:ietf:params:oauth:grant-type:token-exchange",
+  JWT_BEARER = "urn:ietf:params:oauth:grant-type:jwt-bearer",
 }
 /**
  * Aliases for either type of Handler that makes .fetch required
@@ -84,6 +355,14 @@ interface TokenExchangeCallbackOptions {
    * User who authorized this grant
    */
   userId: string;
+  /**
+   * Identifier of the grant record this callback is operating on. Stable across
+   * refreshes for the lifetime of the grant. Pass this together with `userId`
+   * to {@link OAuthHelpers.revokeGrant} when the callback decides the grant
+   * should be torn down (for example, after an upstream refresh fails with a
+   * terminal error code).
+   */
+  grantId: string;
   /**
    * List of scopes that were granted
    */
@@ -227,6 +506,15 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    * Defaults to false.
    */
   allowTokenExchangeGrant?: boolean;
+  /**
+   * Experimental support for the MCP Enterprise-Managed Authorization extension.
+   * When enabled, the token endpoint accepts ID-JAG assertions using the JWT bearer
+   * grant type (`urn:ietf:params:oauth:grant-type:jwt-bearer`).
+   *
+   * This feature is opt-in because the MCP extension and underlying OAuth drafts are
+   * still evolving. Trusted issuers and a claim mapper are required.
+   */
+  enterpriseManagedAuthorization?: EmaOptions<Env>;
   /**
    * Controls whether public clients (clients without a secret, like SPAs) can register via the
    * dynamic client registration endpoint. When true, only confidential clients can register.
@@ -255,16 +543,26 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    */
   resolveExternalToken?: (input: ResolveExternalTokenInput) => Promise<ResolveExternalTokenResult | null>;
   /**
-   * Optional callback function that is called whenever the OAuthProvider returns an error response
+   * Optional callback function that is called whenever the OAuthProvider returns an error response.
    * This allows the client to emit notifications or perform other actions when an error occurs.
    *
    * If the function returns a Response, that will be used in place of the OAuthProvider's default one.
+   *
+   * `internal` (when present) carries a tagged, server-side-only reason that the library
+   * deliberately did NOT put on the wire — used for richer diagnostics where the public
+   * response must stay generic (e.g. JWT validation failures on the EMA path). Backwards
+   * compatible: existing callbacks ignoring this field continue to work unchanged.
    */
   onError?: (error: {
     code: string;
     description: string;
     status: number;
     headers: Record<string, string>;
+    internal?: {
+      category: string;
+      reason: string;
+      detail?: unknown;
+    };
   }) => Response | void;
   /**
    * Explicitly enable Client ID Metadata Document (CIMD) support.
@@ -511,6 +809,18 @@ interface ClientInfo {
    * URL to the client's JSON Web Key Set for validating signatures
    */
   jwksUri?: string;
+  /**
+   * RFC 7591 §2.2 internationalized variants of the human-readable client
+   * metadata fields, keyed by the raw member name including its BCP 47 language
+   * tag (e.g. `"client_name#ja"`, `"tos_uri#fr"`).
+   *
+   * Only the human-readable fields the RFC names are captured here:
+   * `client_name`, `client_uri`, `logo_uri`, `tos_uri`, and `policy_uri`.
+   * The canonical (un-tagged) values continue to live in their own typed
+   * fields above; this map holds only the locale-specific variants so that
+   * consumers can perform their own locale selection.
+   */
+  i18n?: Record<string, string>;
   /**
    * List of email addresses for contacting the client developers
    */
@@ -980,5 +1290,33 @@ declare class OAuthError extends Error {
   readonly headers?: Record<string, string>;
   constructor(code: string, options: OAuthErrorOptions);
 }
+/**
+ * Validates a resource URI per RFC 8707 Section 2
+ * @param uri - The URI string to validate
+ * @returns true if valid, false otherwise
+ */
+declare function validateResourceUri(uri: string): boolean;
+/**
+ * Checks if a requested resource matches a granted resource.
+ * When originOnly is true, compares only the origin (scheme + host + port),
+ * allowing path-aware resources to match origin-only grants.
+ */
+declare function resourceMatches(requested: string, granted: string, originOnly: boolean): boolean;
+/**
+ * Decodes a base64url-encoded string to bytes.
+ */
+declare function base64UrlToBytes(base64Url: string): Uint8Array;
+/**
+ * Parses a base64url-encoded JWT JSON part into an object.
+ */
+declare function parseJwtJsonPart(encoded: string): Record<string, unknown>;
+declare function isValidOAuthScopeToken(scopeToken: string): boolean;
+/**
+ * Gets WebCrypto import and verify parameters for supported JOSE algorithms.
+ */
+declare function getJwtCryptoAlgorithms(alg: string): {
+  importAlgorithm: Parameters<SubtleCrypto['importKey']>[2];
+  verifyAlgorithm: Parameters<SubtleCrypto['verify']>[0];
+};
 //#endregion
-export { AuthRequest, ClientInfo, CompleteAuthorizationOptions, ExchangeTokenOptions, Grant, GrantSummary, GrantType, ListOptions, ListResult, OAuthError, OAuthErrorOptions, OAuthHelpers, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, OAuthTokenErrorCode, PurgeOptions, PurgeResult, ResolveExternalTokenInput, ResolveExternalTokenResult, Token, TokenBase, TokenExchangeCallbackOptions, TokenExchangeCallbackResult, TokenSummary, getOAuthApi };
+export { AuthRequest, ClientInfo, CompleteAuthorizationOptions, type EmaClaimsMapper, type EmaClaimsMapperInput, type EmaClaimsMapperResult, type EmaIdJagClaims, type EmaOptions, type EmaTrustedIssuer, type EmaTrustedIssuerResolver, type EmaTrustedIssuerResolverInput, type EmaValidationError, ExchangeTokenOptions, Grant, GrantSummary, GrantType, ListOptions, ListResult, OAuthError, OAuthErrorOptions, OAuthHelpers, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, OAuthTokenErrorCode, PurgeOptions, PurgeResult, ResolveExternalTokenInput, ResolveExternalTokenResult, Token, TokenBase, TokenExchangeCallbackOptions, TokenExchangeCallbackResult, TokenSummary, base64UrlToBytes, getJwtCryptoAlgorithms, getOAuthApi, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };