@cloudflare/workers-oauth-provider 0.8.3 → 0.9.0

package/dist/oauth-provider.d.ts

@@ -39,6 +39,9 @@ type EmaValidationError = {
   reason: 'aud_mismatch';
   expected: string;
   got: string | string[];
+} | {
+  reason: 'unsupported_claim';
+  claim: 'authorization_details' | 'cnf';
 } | {
   reason: 'expired';
   exp: number;
@@ -295,6 +298,9 @@ interface EmaOptions<Env = Cloudflare.Env> {
   allowPublicClients?: boolean;
 }
 //#endregion
+//#region src/oauth-capabilities.d.ts
+declare function isValidOAuthScopeToken(scopeToken: string): boolean;
+//#endregion
 //#region src/oauth-provider.d.ts
 /**
  * Enum representing OAuth grant types
@@ -446,7 +452,7 @@ interface ClientRegistrationCallbackResult {
 /**
  * Input parameters for the resolveExternalToken callback function
  */
-interface ResolveExternalTokenInput {
+interface ResolveExternalTokenInput<Env = Cloudflare.Env> {
   /**
    * The token string that was provided in the Authorization header
    */
@@ -458,21 +464,25 @@ interface ResolveExternalTokenInput {
   /**
    * Cloudflare Worker environment variables
    */
-  env: any;
+  env: Env;
 }
 /**
  * Result returned from the resolveExternalToken callback function
  */
 interface ResolveExternalTokenResult {
   /**
-   * Application-specific properties that will be passed to the API handlers
-   * These properties are set in the execution context (ctx.props) when the external token is validated
+   * Application-specific properties that will be passed to the API handlers.
+   * These properties are set in the execution context (`ctx.props`) after the
+   * external bearer credential is validated.
    */
   props: any;
   /**
-   * Audience claim from the external token (RFC 7519 Section 4.1.3)
-   * If provided, will be validated against the resource server identity
+   * Protected resource audience established by the external validator.
    *
+   * A JWT may carry this value as an `aud` claim. For an opaque API token or
+   * PAT, the callback can supply the local resource URI as policy after
+   * successful validation. When `resourceMetadata.resource` is configured,
+   * this value is required and must match it exactly.
    */
   audience?: string | string[];
 }
@@ -548,8 +558,9 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    */
   clientRegistrationTTL?: number;
   /**
-   * List of scopes supported by this OAuth provider.
-   * If not provided, the 'scopes_supported' field will be omitted from the OAuth metadata.
+   * Scopes supported by the authorization server.
+   * These are advertised only in authorization server metadata; configure
+   * `resourceMetadata.scopes_supported` separately for protected resource requirements.
    */
   scopesSupported?: string[];
   /**
@@ -559,10 +570,9 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    */
   allowImplicitFlow?: boolean;
   /**
-   * Controls whether the plain PKCE method is allowed.
-   * OAuth 2.1 recommends using S256 exclusively as plain offers no cryptographic protection.
-   * When set to false, only the S256 code_challenge_method will be accepted.
-   * Defaults to true for backward compatibility.
+   * Controls whether the legacy plain PKCE method is allowed.
+   * Defaults to false so PKCE challenges use S256 exclusively.
+   * Set to true only for compatibility with clients that cannot use S256.
    */
   allowPlainPKCE?: boolean;
   /**
@@ -604,15 +614,18 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    */
   tokenExchangeCallback?: (options: TokenExchangeCallbackOptions) => Promise<TokenExchangeCallbackResult | void> | TokenExchangeCallbackResult | void;
   /**
-   * Optional callback function that is called when a provided token was not found in the internal KV.
-   * This allows authentication through external OAuth servers.
-   * For example, if a request includes an authenticated token from a different OAuth authentication server,
-   * the callback can be used to authenticate it and set the context props through it.
+   * Optional callback called when a provided bearer credential was not found
+   * in the internal KV. It can validate an external OAuth access token, opaque
+   * API token, personal access token (PAT), or another bearer credential and
+   * set the application props passed to the protected handler.
    *
-   * The callback can optionally return props values that will passed-through to the apiHandlers.
-   * The callback can return `null` to signal resolution failure.
+   * Return props to authenticate the request, or `null` for a generic `invalid_token` response.
+   * Throw this package's exported {@link ExternalTokenError} to return an intentional
+   * structured error response for an upstream validation failure.
+   * All other thrown errors, including {@link OAuthError}, remain unexpected
+   * failures and are re-thrown for backwards compatibility.
    */
-  resolveExternalToken?: (input: ResolveExternalTokenInput) => Promise<ResolveExternalTokenResult | null>;
+  resolveExternalToken?: (input: ResolveExternalTokenInput<Env>) => Promise<ResolveExternalTokenResult | null>;
   /**
    * 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.
@@ -623,6 +636,11 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    * 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.
+   *
+   * `request` (when present) is the HTTP request that produced the error response, so the
+   * callback can correlate the error with per-request state such as request-keyed telemetry.
+   * Currently populated for CIMD metadata fetch failures at the token endpoint. Backwards
+   * compatible in the same way as `internal`.
    */
   onError?: (error: {
     code: string;
@@ -634,6 +652,7 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
       reason: string;
       detail?: unknown;
     };
+    request?: Request;
   }) => Response | void;
   /**
    * Explicitly enable Client ID Metadata Document (CIMD) support.
@@ -648,6 +667,7 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    * with an origin-only resource (e.g. `https://server.com`) to be used with
    * path-aware resource requests (e.g. `https://server.com/mcp`), enabling seamless
    * migration from pre-0.4.0 versions that stored origin-only resource URIs.
+   * Explicit `resourceMetadata.resource` configuration always uses exact matching.
    *
    * Defaults to false (strict exact matching per RFC 8707).
    */
@@ -662,7 +682,11 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
   resourceMetadata?: {
     /**
      * The protected resource identifier URL (RFC 9728 `resource` field).
-     * If not set, defaults to the request URL's origin.
+     *
+     * Configuring this value pins authorization requests, token requests, and
+     * access-token audiences to this exact resource. If omitted, the provider
+     * accepts valid RFC 8707 resource indicators and uses the authorization
+     * request origin as the default when the client does not send one.
      */
     resource?: string;
     /**
@@ -672,8 +696,10 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
      */
     authorization_servers?: string[];
     /**
-     * Scopes supported by this protected resource.
-     * If not set, falls back to the top-level scopesSupported option.
+     * Minimal scopes required for basic protected resource functionality.
+     * These scopes are advertised in Protected Resource Metadata and used as
+     * baseline bearer challenge guidance. `offline_access` is omitted because
+     * refresh-token issuance is an authorization server capability.
      */
     scopes_supported?: string[];
     /**
@@ -695,18 +721,23 @@ interface OAuthHelpers {
    * Parses an OAuth authorization request from the HTTP request
    * @param request - The HTTP request containing OAuth parameters
    * @returns The parsed authorization request parameters
+   * @throws Error when the response type is missing, unsupported, or not registered for the client
+   * @throws {@link CimdFetchError} when the client ID is a CIMD URL whose document cannot be resolved
    */
   parseAuthRequest(request: Request): Promise<AuthRequest>;
   /**
    * Looks up a client by its client ID
    * @param clientId - The client ID to look up
-   * @returns A Promise resolving to the client info, or null if not found
+   * @returns A Promise resolving to the client info, or null if the client does not exist
+   * @throws {@link CimdFetchError} when the client ID is a CIMD URL whose document cannot be resolved
    */
   lookupClient(clientId: string): Promise<ClientInfo | null>;
   /**
    * Completes an authorization request by creating a grant and authorization code
    * @param options - Options specifying the grant details
    * @returns A Promise resolving to an object containing the redirect URL
+   * @throws Error when the request's response type is not permitted
+   * @throws {@link CimdFetchError} when the client ID is a CIMD URL whose document cannot be resolved
    */
   completeAuthorization(options: CompleteAuthorizationOptions): Promise<{
     redirectTo: string;
@@ -762,6 +793,7 @@ interface OAuthHelpers {
    * Implements OAuth 2.0 Token Exchange (RFC 8693)
    * @param options - Options for token exchange including subject token and optional modifications
    * @returns Promise resolving to token response with new access token
+   * @throws {@link CimdFetchError} when the grant's client ID is a CIMD URL whose document cannot be resolved
    */
   exchangeToken(options: ExchangeTokenOptions): Promise<TokenResponse>;
   /**
@@ -838,6 +870,11 @@ interface AuthRequest {
    * Resource parameter indicating target resource(s) (RFC 8707)
    */
   resource?: string | string[];
+  /**
+   * Authorization server issuer recorded while parsing this request.
+   * Include it as `iss` in successful and error authorization responses.
+   */
+  issuer?: string;
 }
 /**
  * OAuth client registration information
@@ -1317,11 +1354,10 @@ interface OAuthErrorOptions {
   headers?: Record<string, string>;
 }
 /**
- * Structured OAuth 2.0 error.
+ * Structured OAuth 2.0 token-endpoint error.
  *
- * Throw from a `tokenExchangeCallback` (or any code it calls — the error
- * propagates naturally up through deep call stacks) to surface a standard
- * `/token` error response (`{ error, error_description }`) instead of a
+ * Throw from a `tokenExchangeCallback` or any code it calls to surface a
+ * standard OAuth token response (`{ error, error_description }`) instead of a
  * generic `500 Internal Server Error`.
  *
  * Anything thrown that is **not** an `OAuthError` continues to surface as
@@ -1371,6 +1407,82 @@ declare class OAuthError extends Error {
   readonly headers?: Record<string, string>;
   constructor(code: string, options: OAuthErrorOptions);
 }
+/** Options accepted by the {@link ExternalTokenError} constructor. */
+interface ExternalTokenErrorOptions {
+  /**
+   * Public description returned in the OAuth `error_description` field.
+   * Do not include credentials, upstream response bodies, or private diagnostics.
+   */
+  description: string;
+  /** HTTP status returned to the protected-resource client. */
+  statusCode: number;
+  /** Additional public response headers, such as `Retry-After`. */
+  headers?: Record<string, string>;
+  /**
+   * Minimum scopes needed for the protected-resource operation.
+   *
+   * For `403 insufficient_scope`, these values are validated, deduplicated,
+   * and added to the synthesized `WWW-Authenticate` challenge. Each value must
+   * use the OAuth scope-token grammar from RFC 6749 §3.3.
+   */
+  requiredScopes?: string[];
+}
+/**
+ * Intentional public error from an external bearer-token validator.
+ *
+ * Throw only from `resolveExternalToken` when an expected validation outcome
+ * should become a structured protected-resource response. Ordinary errors and
+ * {@link OAuthError} retain their pre-existing behavior and propagate as
+ * unexpected failures.
+ */
+declare class ExternalTokenError extends Error {
+  /** OAuth error code returned in the response body and, when applicable, challenge. */
+  readonly code: OAuthTokenErrorCode;
+  /** Public description returned as `error_description`. */
+  readonly description: string;
+  /** HTTP status returned to the protected-resource client. */
+  readonly statusCode: number;
+  /** Additional public response headers. */
+  readonly headers?: Record<string, string>;
+  /** Minimum scopes for an `insufficient_scope` challenge. */
+  readonly requiredScopes?: string[];
+  /**
+   * Creates an intentional external-token validation error.
+   * @param code - Standard OAuth error code to return
+   * @param options - Public response details
+   */
+  constructor(code: OAuthTokenErrorCode, options: ExternalTokenErrorOptions);
+}
+/**
+ * Thrown when fetching a Client ID Metadata Document (CIMD) fails — the
+ * server-to-server fetch errored, timed out, or returned an invalid document.
+ * Distinct from a client that simply does not exist, which is reported as a
+ * null client lookup result.
+ *
+ * At the token endpoint the provider handles this itself: the wire response
+ * stays a generic `invalid_client` / "Client not found", and the failure is
+ * reported through the `onError` hook's `internal` field (category
+ * `client-id-metadata-document`) together with the originating `request`.
+ *
+ * `OAuthHelpers` methods that look up clients (`lookupClient`, and methods
+ * built on it such as `exchangeToken`) let this error propagate to the
+ * caller. Callers that previously relied on a `null` result for these
+ * failures should catch it to preserve their error contract.
+ */
+declare class CimdFetchError extends Error {
+  /** Stable reason slug suitable for telemetry and control flow. */
+  readonly reason: "metadata_resolution_failed";
+  /** The CIMD URL whose fetch or validation failed. */
+  readonly metadataUrl: string;
+  /** The underlying failure message (e.g. "Failed to fetch client metadata: HTTP 403"). */
+  readonly detail: string;
+  /**
+   * Creates an error for a failed CIMD fetch or validation.
+   * @param metadataUrl - The CIMD URL that could not be resolved
+   * @param cause - The underlying fetch or validation failure
+   */
+  constructor(metadataUrl: string, cause: unknown);
+}
 /**
  * Validates a resource URI per RFC 8707 Section 2
  * @param uri - The URI string to validate
@@ -1391,7 +1503,6 @@ 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.
  */
@@ -1400,4 +1511,4 @@ declare function getJwtCryptoAlgorithms(alg: string): {
   verifyAlgorithm: Parameters<SubtleCrypto['verify']>[0];
 };
 //#endregion
-export { AuthRequest, ClientInfo, ClientRegistrationCallbackOptions, ClientRegistrationCallbackResult, 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 };
+export { AuthRequest, CimdFetchError, ClientInfo, ClientRegistrationCallbackOptions, ClientRegistrationCallbackResult, CompleteAuthorizationOptions, type EmaClaimsMapper, type EmaClaimsMapperInput, type EmaClaimsMapperResult, type EmaIdJagClaims, type EmaOptions, type EmaTrustedIssuer, type EmaTrustedIssuerResolver, type EmaTrustedIssuerResolverInput, type EmaValidationError, ExchangeTokenOptions, ExternalTokenError, ExternalTokenErrorOptions, 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 };