@cloudflare/workers-oauth-provider 0.0.2 → 0.0.3

package/README.md

@@ -2,9 +2,9 @@
 
 This is a TypeScript library that implements the provider side of the OAuth 2.1 protocol with PKCE support. The library is intended to be used on Cloudflare Workers.
 
-## EXPERIMENTAL
+## Beta
 
-As of March, 2025, this library is very new. Please use with caution as additional security reviews are still in progress.
+As of March, 2025, this library is very new, prerelease software. The API is still subject to change.
 
 ## Benefits of this library
 
@@ -262,11 +262,34 @@ The `accessTokenTTL` override is particularly useful when the application is als
 
 The `props` values are end-to-end encrypted, so they can safely contain sensitive information.
 
-## Written by Claude
+## Custom Error Responses
 
-This library (including the schema documentation) was largely written by [Claude](https://claude.ai), the AI model by Anthropic. Claude's output was thoroughly reviewed by Cloudflare engineers with careful attention paid to security and compliance with standards. Many improvements were made on the initial output, mostly again by prompting Claude (and reviewing the results). Check out the commit history to see how Claude was prompted and what code it produced.
+By using the `onError` option, you can emit notifications or take other actions when an error response was to be emitted:
 
-(@kentonv, the lead engineer, was actually an AI skeptic, and started this project with the intent to prove that LLMs cannot code. He ended up deciding he had proven himself wrong.)
+```ts
+new OAuthProvider({
+  // ... other options ...
+  onError({ code, description, status, headers }) {
+    Sentry.captureMessage(/* ... */)
+  }
+})
+```
+
+By returning a `Response` you can also override what the OAuthProvider returns to your users:
+
+```ts
+new OAuthProvider({
+  // ... other options ...
+  onError({ code, description, status, headers }) {
+    if (code === 'unsupported_grant_type') {
+      return new Response('...', { status, headers })
+    }
+    // returning undefined (i.e. void) uses the default Response generation
+  }
+})
+```
+
+By default, the `onError` callback is set to ``({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`)``.
 
 ## Implementation Notes
 
@@ -286,3 +309,17 @@ OAuth 2.1 requires that refresh tokens are either "cryptographically bound" to t
 This requirement is seemingly fundamentally flawed as it assumes that every refresh request will complete with no errors. In the real world, a transient network error, machine failure, or software fault could mean that the client fails to store the new refresh token after a refresh request. In this case, the client would be permanently unable to make any further requests, as the only token it has is no longer valid.
 
 This library implements a compromise: At any particular time, a grant may have two valid refresh tokens. When the client uses one of them, the other one is invalidated, and a new one is generated and returned. Thus, if the client correctly uses the new refresh token each time, then older refresh tokens are continuously invalidated. But if a transient failure prevents the client from updating its token, it can always retry the request with the token it used previously.
+
+## Written using Claude
+
+This library (including the schema documentation) was largely written with the help of [Claude](https://claude.ai), the AI model by Anthropic. Claude's output was thoroughly reviewed by Cloudflare engineers with careful attention paid to security and compliance with standards. Many improvements were made on the initial output, mostly again by prompting Claude (and reviewing the results). Check out the commit history to see how Claude was prompted and what code it produced.
+
+**"NOOOOOOOO!!!! You can't just use an LLM to write an auth library!"**
+
+"haha gpus go brrr"
+
+In all seriousness, two months ago (January 2025), I ([@kentonv](https://github.com/kentonv)) would have agreed. I was an AI skeptic. I thoughts LLMs were glorified Markov chain generators that didn't actually understand code and couldn't produce anything novel. I started this project on a lark, fully expecting the AI to produce terrible code for me to laugh at. And then, uh... the code actually looked pretty good. Not perfect, but I just told the AI to fix things, and it did. I was shocked.
+
+To emphasize, **this is not "vibe coded"**. Every line was thoroughly reviewed and cross-referenced with relevant RFCs, by security experts with previous experience with those RFCs. I was *trying* to validate my skepticism. I ended up proving myself wrong.
+
+Again, please check out the commit history -- especially early commits -- to understand how this went.

package/dist/oauth-provider.d.ts

@@ -128,6 +128,18 @@ interface OAuthProviderOptions {
      * If the callback returns nothing or undefined for a props field, the original props will be used.
      */
     tokenExchangeCallback?: (options: TokenExchangeCallbackOptions) => Promise<TokenExchangeCallbackResult | void> | TokenExchangeCallbackResult | void;
+    /**
+     * 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.
+     */
+    onError?: (error: {
+        code: string;
+        description: string;
+        status: number;
+        headers: Record<string, string>;
+    }) => Response | void;
 }
 /**
  * Helper methods for OAuth operations provided to handler functions

package/dist/oauth-provider.js

@@ -52,8 +52,9 @@ var OAuthProviderImpl = class {
       this.validateEndpoint(options.clientRegistrationEndpoint, "clientRegistrationEndpoint");
     }
     this.options = {
-      ...options,
-      accessTokenTTL: options.accessTokenTTL || DEFAULT_ACCESS_TOKEN_TTL
+      accessTokenTTL: DEFAULT_ACCESS_TOKEN_TTL,
+      onError: ({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`),
+      ...options
     };
   }
   /**
@@ -298,12 +299,12 @@ var OAuthProviderImpl = class {
    */
   async handleTokenRequest(request, env) {
     if (request.method !== "POST") {
-      return createErrorResponse("invalid_request", "Method not allowed", 405);
+      return this.createErrorResponse("invalid_request", "Method not allowed", 405);
     }
     let contentType = request.headers.get("Content-Type") || "";
     let body = {};
     if (!contentType.includes("application/x-www-form-urlencoded")) {
-      return createErrorResponse("invalid_request", "Content-Type must be application/x-www-form-urlencoded", 400);
+      return this.createErrorResponse("invalid_request", "Content-Type must be application/x-www-form-urlencoded", 400);
     }
     const formData = await request.formData();
     for (const [key, value] of formData.entries()) {
@@ -322,19 +323,19 @@ var OAuthProviderImpl = class {
       clientSecret = body.client_secret || "";
     }
     if (!clientId) {
-      return createErrorResponse("invalid_client", "Client ID is required", 401);
+      return this.createErrorResponse("invalid_client", "Client ID is required", 401);
     }
     const clientInfo = await this.getClient(env, clientId);
     if (!clientInfo) {
-      return createErrorResponse("invalid_client", "Client not found", 401);
+      return this.createErrorResponse("invalid_client", "Client not found", 401);
     }
     const isPublicClient = clientInfo.tokenEndpointAuthMethod === "none";
     if (!isPublicClient) {
       if (!clientSecret) {
-        return createErrorResponse("invalid_client", "Client authentication failed: missing client_secret", 401);
+        return this.createErrorResponse("invalid_client", "Client authentication failed: missing client_secret", 401);
       }
       if (!clientInfo.clientSecret) {
-        return createErrorResponse(
+        return this.createErrorResponse(
           "invalid_client",
           "Client authentication failed: client has no registered secret",
           401
@@ -342,7 +343,7 @@ var OAuthProviderImpl = class {
       }
       const providedSecretHash = await hashSecret(clientSecret);
       if (providedSecretHash !== clientInfo.clientSecret) {
-        return createErrorResponse("invalid_client", "Client authentication failed: invalid client_secret", 401);
+        return this.createErrorResponse("invalid_client", "Client authentication failed: invalid client_secret", 401);
       }
     }
     const grantType = body.grant_type;
@@ -351,7 +352,7 @@ var OAuthProviderImpl = class {
     } else if (grantType === "refresh_token") {
       return this.handleRefreshTokenGrant(body, clientInfo, env);
     } else {
-      return createErrorResponse("unsupported_grant_type", "Grant type not supported");
+      return this.createErrorResponse("unsupported_grant_type", "Grant type not supported");
     }
   }
   /**
@@ -367,38 +368,38 @@ var OAuthProviderImpl = class {
     const redirectUri = body.redirect_uri;
     const codeVerifier = body.code_verifier;
     if (!code) {
-      return createErrorResponse("invalid_request", "Authorization code is required");
+      return this.createErrorResponse("invalid_request", "Authorization code is required");
     }
     const codeParts = code.split(":");
     if (codeParts.length !== 3) {
-      return createErrorResponse("invalid_grant", "Invalid authorization code format");
+      return this.createErrorResponse("invalid_grant", "Invalid authorization code format");
     }
     const [userId, grantId, _] = codeParts;
     const grantKey = `grant:${userId}:${grantId}`;
     const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
     if (!grantData) {
-      return createErrorResponse("invalid_grant", "Grant not found or authorization code expired");
+      return this.createErrorResponse("invalid_grant", "Grant not found or authorization code expired");
     }
     if (!grantData.authCodeId) {
-      return createErrorResponse("invalid_grant", "Authorization code already used");
+      return this.createErrorResponse("invalid_grant", "Authorization code already used");
     }
     const codeHash = await hashSecret(code);
     if (codeHash !== grantData.authCodeId) {
-      return createErrorResponse("invalid_grant", "Invalid authorization code");
+      return this.createErrorResponse("invalid_grant", "Invalid authorization code");
     }
     if (grantData.clientId !== clientInfo.clientId) {
-      return createErrorResponse("invalid_grant", "Client ID mismatch");
+      return this.createErrorResponse("invalid_grant", "Client ID mismatch");
     }
     const isPkceEnabled = !!grantData.codeChallenge;
     if (!redirectUri && !isPkceEnabled) {
-      return createErrorResponse("invalid_request", "redirect_uri is required when not using PKCE");
+      return this.createErrorResponse("invalid_request", "redirect_uri is required when not using PKCE");
     }
     if (redirectUri && !clientInfo.redirectUris.includes(redirectUri)) {
-      return createErrorResponse("invalid_grant", "Invalid redirect URI");
+      return this.createErrorResponse("invalid_grant", "Invalid redirect URI");
     }
     if (isPkceEnabled) {
       if (!codeVerifier) {
-        return createErrorResponse("invalid_request", "code_verifier is required for PKCE");
+        return this.createErrorResponse("invalid_request", "code_verifier is required for PKCE");
       }
       let calculatedChallenge;
       if (grantData.codeChallengeMethod === "S256") {
@@ -411,7 +412,7 @@ var OAuthProviderImpl = class {
         calculatedChallenge = codeVerifier;
       }
       if (calculatedChallenge !== grantData.codeChallenge) {
-        return createErrorResponse("invalid_grant", "Invalid PKCE code_verifier");
+        return this.createErrorResponse("invalid_grant", "Invalid PKCE code_verifier");
       }
     }
     const accessTokenSecret = generateRandomString(TOKEN_LENGTH);
@@ -516,26 +517,26 @@ var OAuthProviderImpl = class {
   async handleRefreshTokenGrant(body, clientInfo, env) {
     const refreshToken = body.refresh_token;
     if (!refreshToken) {
-      return createErrorResponse("invalid_request", "Refresh token is required");
+      return this.createErrorResponse("invalid_request", "Refresh token is required");
     }
     const tokenParts = refreshToken.split(":");
     if (tokenParts.length !== 3) {
-      return createErrorResponse("invalid_grant", "Invalid token format");
+      return this.createErrorResponse("invalid_grant", "Invalid token format");
     }
     const [userId, grantId, _] = tokenParts;
     const providedTokenHash = await generateTokenId(refreshToken);
     const grantKey = `grant:${userId}:${grantId}`;
     const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
     if (!grantData) {
-      return createErrorResponse("invalid_grant", "Grant not found");
+      return this.createErrorResponse("invalid_grant", "Grant not found");
     }
     const isCurrentToken = grantData.refreshTokenId === providedTokenHash;
     const isPreviousToken = grantData.previousRefreshTokenId === providedTokenHash;
     if (!isCurrentToken && !isPreviousToken) {
-      return createErrorResponse("invalid_grant", "Invalid refresh token");
+      return this.createErrorResponse("invalid_grant", "Invalid refresh token");
     }
     if (grantData.clientId !== clientInfo.clientId) {
-      return createErrorResponse("invalid_grant", "Client ID mismatch");
+      return this.createErrorResponse("invalid_grant", "Client ID mismatch");
     }
     const accessTokenSecret = generateRandomString(TOKEN_LENGTH);
     const newAccessToken = `${userId}:${grantId}:${accessTokenSecret}`;
@@ -647,24 +648,24 @@ var OAuthProviderImpl = class {
    */
   async handleClientRegistration(request, env) {
     if (!this.options.clientRegistrationEndpoint) {
-      return createErrorResponse("not_implemented", "Client registration is not enabled", 501);
+      return this.createErrorResponse("not_implemented", "Client registration is not enabled", 501);
     }
     if (request.method !== "POST") {
-      return createErrorResponse("invalid_request", "Method not allowed", 405);
+      return this.createErrorResponse("invalid_request", "Method not allowed", 405);
     }
     const contentLength = parseInt(request.headers.get("Content-Length") || "0", 10);
     if (contentLength > 1048576) {
-      return createErrorResponse("invalid_request", "Request payload too large, must be under 1 MiB", 413);
+      return this.createErrorResponse("invalid_request", "Request payload too large, must be under 1 MiB", 413);
     }
     let clientMetadata;
     try {
       const text = await request.text();
       if (text.length > 1048576) {
-        return createErrorResponse("invalid_request", "Request payload too large, must be under 1 MiB", 413);
+        return this.createErrorResponse("invalid_request", "Request payload too large, must be under 1 MiB", 413);
       }
       clientMetadata = JSON.parse(text);
     } catch (error) {
-      return createErrorResponse("invalid_request", "Invalid JSON payload", 400);
+      return this.createErrorResponse("invalid_request", "Invalid JSON payload", 400);
     }
     const validateStringField = (field) => {
       if (field === void 0) {
@@ -692,7 +693,7 @@ var OAuthProviderImpl = class {
     const authMethod = validateStringField(clientMetadata.token_endpoint_auth_method) || "client_secret_basic";
     const isPublicClient = authMethod === "none";
     if (isPublicClient && this.options.disallowPublicClientRegistration) {
-      return createErrorResponse("invalid_client_metadata", "Public client registration is not allowed");
+      return this.createErrorResponse("invalid_client_metadata", "Public client registration is not allowed");
     }
     const clientId = generateRandomString(16);
     let clientSecret;
@@ -726,7 +727,7 @@ var OAuthProviderImpl = class {
         clientInfo.clientSecret = hashedSecret;
       }
     } catch (error) {
-      return createErrorResponse(
+      return this.createErrorResponse(
         "invalid_client_metadata",
         error instanceof Error ? error.message : "Invalid client metadata"
       );
@@ -766,14 +767,14 @@ var OAuthProviderImpl = class {
   async handleApiRequest(request, env, ctx) {
     const authHeader = request.headers.get("Authorization");
     if (!authHeader || !authHeader.startsWith("Bearer ")) {
-      return createErrorResponse("invalid_token", "Missing or invalid access token", 401, {
+      return this.createErrorResponse("invalid_token", "Missing or invalid access token", 401, {
         "WWW-Authenticate": 'Bearer realm="OAuth", error="invalid_token", error_description="Missing or invalid access token"'
       });
     }
     const accessToken = authHeader.substring(7);
     const tokenParts = accessToken.split(":");
     if (tokenParts.length !== 3) {
-      return createErrorResponse("invalid_token", "Invalid token format", 401, {
+      return this.createErrorResponse("invalid_token", "Invalid token format", 401, {
         "WWW-Authenticate": 'Bearer realm="OAuth", error="invalid_token"'
       });
     }
@@ -782,13 +783,13 @@ var OAuthProviderImpl = class {
     const tokenKey = `token:${userId}:${grantId}:${accessTokenId}`;
     const tokenData = await env.OAUTH_KV.get(tokenKey, { type: "json" });
     if (!tokenData) {
-      return createErrorResponse("invalid_token", "Invalid access token", 401, {
+      return this.createErrorResponse("invalid_token", "Invalid access token", 401, {
         "WWW-Authenticate": 'Bearer realm="OAuth", error="invalid_token"'
       });
     }
     const now = Math.floor(Date.now() / 1e3);
     if (tokenData.expiresAt < now) {
-      return createErrorResponse("invalid_token", "Access token expired", 401, {
+      return this.createErrorResponse("invalid_token", "Access token expired", 401, {
         "WWW-Authenticate": 'Bearer realm="OAuth", error="invalid_token"'
       });
     }
@@ -827,22 +828,32 @@ var OAuthProviderImpl = class {
     const clientKey = `client:${clientId}`;
     return env.OAUTH_KV.get(clientKey, { type: "json" });
   }
+  /**
+   * Helper function to create OAuth error responses
+   * @param code - OAuth error code (e.g., 'invalid_request', 'invalid_token')
+   * @param description - Human-readable error description
+   * @param status - HTTP status code (default: 400)
+   * @param headers - Additional headers to include
+   * @returns A Response object with the error
+   */
+  createErrorResponse(code, description, status = 400, headers = {}) {
+    const customErrorResponse = this.options.onError?.({ code, description, status, headers });
+    if (customErrorResponse) return customErrorResponse;
+    const body = JSON.stringify({
+      error: code,
+      error_description: description
+    });
+    return new Response(body, {
+      status,
+      headers: {
+        "Content-Type": "application/json",
+        ...headers
+      }
+    });
+  }
 };
 var DEFAULT_ACCESS_TOKEN_TTL = 60 * 60;
 var TOKEN_LENGTH = 32;
-function createErrorResponse(code, description, status = 400, headers = {}) {
-  const body = JSON.stringify({
-    error: code,
-    error_description: description
-  });
-  return new Response(body, {
-    status,
-    headers: {
-      "Content-Type": "application/json",
-      ...headers
-    }
-  });
-}
 async function hashSecret(secret) {
   return generateTokenId(secret);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/workers-oauth-provider",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "OAuth provider for Cloudflare Workers",
   "main": "dist/oauth-provider.js",
   "types": "dist/oauth-provider.d.ts",
@@ -15,7 +15,9 @@
   },
   "scripts": {
     "build": "tsup",
+    "build:watch": "tsup --watch",
     "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build",
     "prettier": "prettier -w ."
   },