Merge pull request #22 from cloudflare/glen/onerror-callback

Added onError callback

Author: geelen

README.md

@@ -262,6 +262,35 @@ 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.
 
+## Custom Error Responses
+
+By using the `onError` option, you can emit notifications or take other actions when an error response was to be emitted:
+
+```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
 
 ### End-to-end encryption

__tests__/oauth-provider.test.ts

@@ -1856,6 +1856,108 @@ describe('OAuthProvider', () => {
     });
   });
 
+  describe('Error Handling with onError Callback', () => {
+    it('should use the default onError callback that logs a warning', async () => {
+      // Spy on console.warn to check default behavior
+      const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      // Create a request that will trigger an error
+      const invalidTokenRequest = createMockRequest('https://example.com/api/test', 'GET', {
+        Authorization: 'Bearer invalid-token',
+      });
+
+      const response = await oauthProvider.fetch(invalidTokenRequest, mockEnv, mockCtx);
+
+      // Verify the error response
+      expect(response.status).toBe(401);
+      const error = await response.json();
+      expect(error.error).toBe('invalid_token');
+
+      // Verify the default onError callback was triggered and logged a warning
+      expect(consoleWarnSpy).toHaveBeenCalledWith(expect.stringContaining('OAuth error response: 401 invalid_token'));
+
+      // Restore the spy
+      consoleWarnSpy.mockRestore();
+    });
+
+    it('should allow custom onError callback to modify the error response', async () => {
+      // Create a provider with custom onError callback
+      const customErrorProvider = new OAuthProvider({
+        apiRoute: ['/api/'],
+        apiHandler: TestApiHandler,
+        defaultHandler: testDefaultHandler,
+        authorizeEndpoint: '/authorize',
+        tokenEndpoint: '/oauth/token',
+        scopesSupported: ['read', 'write'],
+        onError: ({ code, description, status }) => {
+          // Return a completely different response
+          return new Response(
+            JSON.stringify({
+              custom_error: true,
+              original_code: code,
+              custom_message: `Custom error handler: ${description}`,
+            }),
+            {
+              status,
+              headers: {
+                'Content-Type': 'application/json',
+                'X-Custom-Error': 'true',
+              },
+            }
+          );
+        },
+      });
+
+      // Create a request that will trigger an error
+      const invalidTokenRequest = createMockRequest('https://example.com/api/test', 'GET', {
+        Authorization: 'Bearer invalid-token',
+      });
+
+      const response = await customErrorProvider.fetch(invalidTokenRequest, mockEnv, mockCtx);
+
+      // Verify the custom error response
+      expect(response.status).toBe(401); // Status should be preserved
+      expect(response.headers.get('X-Custom-Error')).toBe('true');
+
+      const error = await response.json();
+      expect(error.custom_error).toBe(true);
+      expect(error.original_code).toBe('invalid_token');
+      expect(error.custom_message).toContain('Custom error handler');
+    });
+
+    it('should use standard error response when onError returns void', async () => {
+      // Create a provider with a callback that performs a side effect but doesn't return a response
+      let callbackInvoked = false;
+      const sideEffectProvider = new OAuthProvider({
+        apiRoute: ['/api/'],
+        apiHandler: TestApiHandler,
+        defaultHandler: testDefaultHandler,
+        authorizeEndpoint: '/authorize',
+        tokenEndpoint: '/oauth/token',
+        scopesSupported: ['read', 'write'],
+        onError: () => {
+          callbackInvoked = true;
+          // No return - should use standard error response
+        },
+      });
+
+      // Create a request that will trigger an error
+      const invalidRequest = createMockRequest('https://example.com/oauth/token', 'POST', {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      });
+
+      const response = await sideEffectProvider.fetch(invalidRequest, mockEnv, mockCtx);
+
+      // Verify the standard error response
+      expect(response.status).toBe(401);
+      const error = await response.json();
+      expect(error.error).toBe('invalid_client');
+
+      // Verify callback was invoked
+      expect(callbackInvoked).toBe(true);
+    });
+  });
+
   describe('OAuthHelpers', () => {
     it('should allow listing and revoking grants', async () => {
       // Create a client

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 ."
   },