Merge pull request #9 from cloudflare/kenton/access-token-callback

Add access token exchange callback

Author: geelen

.github/workflows/tests.yml

@@ -0,0 +1,26 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 20
+        cache: 'npm'
+    
+    - name: Install dependencies
+      run: npm ci
+    
+    - name: Run tests
+      run: npm test

README.md

@@ -196,6 +196,72 @@ The `env.OAUTH_PROVIDER` object available to the fetch handlers provides some me
 
 See the `OAuthHelpers` interface definition for full API details.
 
+## Token Exchange Callback
+
+This library allows you to update the `props` value during token exchanges by configuring a callback function. This is useful for scenarios where the application needs to perform additional processing when tokens are issued or refreshed.
+
+For example, if your application is also a client to some other OAuth API, you might want to perform an equivalent upstream token exchange and store the result in the `props`. The callback can be used to update the props for both the grant record and specific access tokens.
+
+To use this feature, provide a `tokenExchangeCallback` in your OAuthProvider options:
+
+```ts
+new OAuthProvider({
+  // ... other options ...
+  tokenExchangeCallback: async (options) => {
+    // options.grantType is either 'authorization_code' or 'refresh_token'
+    // options.props contains the current props
+    // options.clientId, options.userId, and options.scope are also available
+
+    if (options.grantType === 'authorization_code') {
+      // For authorization code exchange, might want to obtain upstream tokens
+      const upstreamTokens = await exchangeUpstreamToken(options.props.someCode);
+
+      return {
+        // Update the props stored in the access token
+        accessTokenProps: {
+          ...options.props,
+          upstreamAccessToken: upstreamTokens.access_token
+        },
+        // Update the props stored in the grant (for future token refreshes)
+        newProps: {
+          ...options.props,
+          upstreamRefreshToken: upstreamTokens.refresh_token
+        }
+      };
+    }
+
+    if (options.grantType === 'refresh_token') {
+      // For refresh token exchanges, might want to refresh upstream tokens too
+      const upstreamTokens = await refreshUpstreamToken(options.props.upstreamRefreshToken);
+
+      return {
+        accessTokenProps: {
+          ...options.props,
+          upstreamAccessToken: upstreamTokens.access_token
+        },
+        newProps: {
+          ...options.props,
+          upstreamRefreshToken: upstreamTokens.refresh_token || options.props.upstreamRefreshToken
+        },
+        // Optionally override the default access token TTL to match the upstream token
+        accessTokenTTL: upstreamTokens.expires_in
+      };
+    }
+  }
+});
+```
+
+The callback can:
+- Return both `accessTokenProps` and `newProps` to update both
+- Return only `accessTokenProps` to update just the current access token
+- Return only `newProps` to update both the grant and access token (the access token inherits these props)
+- Return `accessTokenTTL` to override the default TTL for this specific access token
+- Return nothing to keep the original props unchanged
+
+The `accessTokenTTL` override is particularly useful when the application is also an OAuth client to another service and wants to match its access token TTL to the upstream access token TTL. This helps prevent situations where the downstream token is still valid but the upstream token has expired.
+
+The `props` values are end-to-end encrypted, so they can safely contain sensitive information.
+
 ## Written by Claude
 
 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.