Ask Claude to rename token exchange callback return properties.

This seems easier to understand.

(Transcript included in previous commit.)

Author: kentonv

README.md

@@ -218,12 +218,12 @@ new OAuthProvider({
 
       return {
         // Update the props stored in the access token
-        tokenProps: {
+        accessTokenProps: {
           ...options.props,
           upstreamAccessToken: upstreamTokens.access_token
         },
         // Update the props stored in the grant (for future token refreshes)
-        grantProps: {
+        newProps: {
           ...options.props,
           upstreamRefreshToken: upstreamTokens.refresh_token
         }
@@ -235,11 +235,11 @@ new OAuthProvider({
       const upstreamTokens = await refreshUpstreamToken(options.props.upstreamRefreshToken);
 
       return {
-        tokenProps: {
+        accessTokenProps: {
           ...options.props,
           upstreamAccessToken: upstreamTokens.access_token
         },
-        grantProps: {
+        newProps: {
           ...options.props,
           upstreamRefreshToken: upstreamTokens.refresh_token || options.props.upstreamRefreshToken
         }
@@ -250,8 +250,9 @@ new OAuthProvider({
 ```
 
 The callback can:
-- Return both `tokenProps` and `grantProps` to update both
-- Return only `tokenProps` or `grantProps` to update just one
+- 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 nothing to keep the original props unchanged
 
 The `props` values are end-to-end encrypted, so they can safely contain sensitive information.

__tests__/oauth-provider.test.ts

@@ -1037,24 +1037,24 @@ describe('OAuthProvider', () => {
         // Return different props based on the grant type
         if (options.grantType === 'authorization_code') {
           return {
-            tokenProps: {
+            accessTokenProps: {
               ...options.props,
               tokenSpecific: true,
               tokenUpdatedAt: 'auth_code_flow'
             },
-            grantProps: {
+            newProps: {
               ...options.props,
               grantUpdated: true
             }
           };
         } else if (options.grantType === 'refresh_token') {
           return {
-            tokenProps: {
+            accessTokenProps: {
               ...options.props,
               tokenSpecific: true,
               tokenUpdatedAt: 'refresh_token_flow'
             },
-            grantProps: {
+            newProps: {
               ...options.props,
               grantUpdated: true,
               refreshCount: (options.props.refreshCount || 0) + 1
@@ -1305,17 +1305,17 @@ describe('OAuthProvider', () => {
     });
 
     it('should update token props during refresh when explicitly provided', async () => {
-      // Create a provider with a callback that returns both tokenProps and grantProps
+      // Create a provider with a callback that returns both accessTokenProps and newProps
       // but with different values for each
       const differentPropsCallback = async (options: any) => {
         if (options.grantType === 'refresh_token') {
           return {
-            tokenProps: {
+            accessTokenProps: {
               ...options.props,
               refreshed: true,
               tokenOnly: true
             },
-            grantProps: {
+            newProps: {
               ...options.props,
               grantUpdated: true
             }
@@ -1416,19 +1416,19 @@ describe('OAuthProvider', () => {
       expect(apiData.user).not.toHaveProperty('grantUpdated');
     });
 
-    it('should handle callback that returns only tokenProps or only grantProps', async () => {
-      // Create a provider with a callback that returns only tokenProps for auth code
-      // and only grantProps for refresh token
-      // Note: With the enhanced implementation, when only grantProps is returned
-      // without tokenProps, the token props will inherit from grantProps
-      const tokenPropsOnlyCallback = async (options: any) => {
+    it('should handle callback that returns only accessTokenProps or only newProps', async () => {
+      // Create a provider with a callback that returns only accessTokenProps for auth code
+      // and only newProps for refresh token
+      // Note: With the enhanced implementation, when only newProps is returned
+      // without accessTokenProps, the token props will inherit from newProps
+      const propsCallback = async (options: any) => {
         if (options.grantType === 'authorization_code') {
           return {
-            tokenProps: { ...options.props, tokenOnly: true }
+            accessTokenProps: { ...options.props, tokenOnly: true }
           };
         } else if (options.grantType === 'refresh_token') {
           return {
-            grantProps: { ...options.props, grantOnly: true }
+            newProps: { ...options.props, grantOnly: true }
           };
         }
       };
@@ -1441,7 +1441,7 @@ describe('OAuthProvider', () => {
         tokenEndpoint: '/oauth/token',
         clientRegistrationEndpoint: '/oauth/register',
         scopesSupported: ['read', 'write'],
-        tokenExchangeCallback: tokenPropsOnlyCallback
+        tokenExchangeCallback: propsCallback
       });
 
       // Create a client
@@ -1531,7 +1531,7 @@ describe('OAuthProvider', () => {
       const api2Data = await api2Response.json();
 
       // With the enhanced implementation, the token props now inherit from grant props
-      // when only grantProps is returned but tokenProps is not specified
+      // when only newProps is returned but accessTokenProps is not specified
       expect(api2Data.user).toEqual({
         userId: "test-user-123",
         username: "TestUser",
@@ -1622,7 +1622,7 @@ describe('OAuthProvider', () => {
     it('should correctly handle the previous refresh token when callback updates grant props', async () => {
       // This test verifies fixes for two bugs:
       // 1. previousRefreshTokenWrappedKey not being re-wrapped when grant props change
-      // 2. tokenProps not inheriting from grantProps when only grantProps is returned
+      // 2. accessTokenProps not inheriting from newProps when only newProps is returned
       let callCount = 0;
       const propUpdatingCallback = async (options: any) => {
         callCount++;
@@ -1632,11 +1632,11 @@ describe('OAuthProvider', () => {
             updatedCount: (options.props.updatedCount || 0) + 1
           };
 
-          // Only return grantProps to test that tokenProps will inherit from it
+          // Only return newProps to test that accessTokenProps will inherit from it
           return {
-            // Return new grant props to trigger the re-encryption with a new key
-            grantProps: updatedProps
-            // Intentionally not setting tokenProps to verify inheritance works
+            // Return new props to trigger the re-encryption with a new key
+            newProps: updatedProps
+            // Intentionally not setting accessTokenProps to verify inheritance works
           };
         }
         return undefined;

src/oauth-provider.ts

@@ -37,16 +37,19 @@ type WorkerEntrypointWithFetch = WorkerEntrypoint & Pick<Required<WorkerEntrypoi
  */
 export interface TokenExchangeCallbackResult {
   /**
-   * New props to be stored with the access token.
-   * If not provided, the original props will be used.
+   * New props to be stored specifically with the access token.
+   * If not provided but newProps is, the access token will use newProps.
+   * If neither is provided, the original props will be used.
    */
-  tokenProps?: any;
+  accessTokenProps?: any;
 
   /**
    * New props to replace the props stored in the grant itself.
+   * These props will be used for all future token refreshes.
+   * If accessTokenProps is not provided, these props will also be used for the current access token.
    * If not provided, the original props will be used.
    */
-  grantProps?: any;
+  newProps?: any;
 }
 
 /**
@@ -1255,19 +1258,19 @@ class OAuthProviderImpl {
 
       if (callbackResult) {
         // Use the returned props if provided, otherwise keep the original props
-        if (callbackResult.grantProps) {
-          grantProps = callbackResult.grantProps;
+        if (callbackResult.newProps) {
+          grantProps = callbackResult.newProps;
 
-          // If tokenProps wasn't explicitly specified, use the updated grantProps for the token too
-          // This ensures token props are updated when only grant props are specified
-          if (!callbackResult.tokenProps) {
-            accessTokenProps = callbackResult.grantProps;
+          // If accessTokenProps wasn't explicitly specified, use the updated newProps for the token too
+          // This ensures token props are updated when only newProps are specified
+          if (!callbackResult.accessTokenProps) {
+            accessTokenProps = callbackResult.newProps;
           }
         }
 
-        // If tokenProps was explicitly specified, use those
-        if (callbackResult.tokenProps) {
-          accessTokenProps = callbackResult.tokenProps;
+        // If accessTokenProps was explicitly specified, use those
+        if (callbackResult.accessTokenProps) {
+          accessTokenProps = callbackResult.accessTokenProps;
         }
       }
 
@@ -1461,20 +1464,20 @@ class OAuthProviderImpl {
       let grantPropsChanged = false;
       if (callbackResult) {
         // Use the returned props if provided, otherwise keep the original props
-        if (callbackResult.grantProps) {
-          grantProps = callbackResult.grantProps;
+        if (callbackResult.newProps) {
+          grantProps = callbackResult.newProps;
           grantPropsChanged = true;
 
-          // If tokenProps wasn't explicitly specified, use the updated grantProps for the token too
-          // This ensures token props are updated when only grant props are specified
-          if (!callbackResult.tokenProps) {
-            accessTokenProps = callbackResult.grantProps;
+          // If accessTokenProps wasn't explicitly specified, use the updated newProps for the token too
+          // This ensures token props are updated when only newProps are specified
+          if (!callbackResult.accessTokenProps) {
+            accessTokenProps = callbackResult.newProps;
           }
         }
 
-        // If tokenProps was explicitly specified, use those
-        if (callbackResult.tokenProps) {
-          accessTokenProps = callbackResult.tokenProps;
+        // If accessTokenProps was explicitly specified, use those
+        if (callbackResult.accessTokenProps) {
+          accessTokenProps = callbackResult.accessTokenProps;
         }
       }