fix(sessionTransferToken): align with auth0-server-js — id_token expiry check, empty issued_token_type fallback, extra params over reason

Author: cschetan77

index.d.ts

@@ -258,10 +258,11 @@ interface SessionTransferTokenOptions {
   /** Scopes for the established session's tokens. */
   scope?: string;
   /**
-   * Optional reason for the exchange. Included in the `act` claim when your CTE Action
-   * passes it to `setActor(...)`.
+   * Additional parameters forwarded to the token endpoint and available in your CTE Action
+   * via `event.request.body` (e.g. `{ reason: 'Investigating TCK-1234' }`).
+   * Cannot override reserved OAuth parameters.
    */
-  reason?: string;
+  extra?: Record<string, string | string[] | number | boolean>;
 }
 
 /**
@@ -376,7 +377,7 @@ interface RequestContext {
    *   const result = await req.oidc.requestSessionTransferToken({
    *     subject_token: req.body.customerToken,
    *     subject_token_type: 'urn:mycompany:customer-subject',
-   *     reason: 'Investigating ticket TCK-1234',
+   *     extra: { reason: 'Investigating ticket TCK-1234' },
    *   });
    *   res.redirect(req.oidc.buildSessionTransferRedirect('https://app.example.com/login', result));
    * });

lib/context.js

@@ -37,6 +37,7 @@ const {
   extractSessionExpiry,
   isSessionExpiryReached,
   isSessionExpiryInPast,
+  isIdTokenExpired,
 } = require('./utils/sessionExpiry');
 
 // Caches one RemoteJWKSet instance per auth() configuration for backchannel logout token verification.
@@ -456,7 +457,7 @@ class RequestContext {
       actor_token_type,
       organization,
       scope,
-      reason,
+      extra,
     } = options;
 
     validateSubjectToken(subject_token);
@@ -475,7 +476,6 @@ class RequestContext {
       resolvedActorTokenType = actor_token_type || ID_TOKEN_IDENTIFIER;
     } else {
       // Source actor from the current session id_token.
-      // If the token set is expired and there's a refresh token, refresh first.
       const ts = tokenSet.call(this);
 
       if (!ts) {
@@ -486,7 +486,24 @@ class RequestContext {
         );
       }
 
-      if (ts.expired() && ts.refresh_token) {
+      const idToken = this.idToken;
+      if (!idToken) {
+        throw createError(
+          400,
+          'No actor available: session exists but contains no id_token. Ensure the session was established with the openid scope, or pass an explicit actor_token.',
+          { error: 'actor_unavailable' },
+        );
+      }
+
+      const { exp } = ts.claims();
+      if (isIdTokenExpired(exp)) {
+        if (!ts.refresh_token) {
+          throw createError(
+            400,
+            'No actor available: id_token has expired and no refresh token is available.',
+            { error: 'actor_unavailable' },
+          );
+        }
         debug(
           'requestSessionTransferToken: id_token expired, refreshing session',
         );
@@ -501,14 +518,7 @@ class RequestContext {
         }
       }
 
-      const idToken = this.idToken;
-      if (!idToken) {
-        throw createError(400, 'No actor available: no id_token in session.', {
-          error: 'actor_unavailable',
-        });
-      }
-
-      resolvedActorToken = idToken;
+      resolvedActorToken = this.idToken;
       resolvedActorTokenType = ID_TOKEN_IDENTIFIER;
     }
 
@@ -532,7 +542,7 @@ class RequestContext {
       audience,
       ...(scope !== undefined && { scope }),
       ...(organization !== undefined && { organization }),
-      ...(reason !== undefined && { reason }),
+      ...validateTokenExchangeExtras(extra),
     };
 
     try {
@@ -544,8 +554,7 @@ class RequestContext {
 
       return {
         session_transfer_token: exchanged.access_token,
-        issued_token_type:
-          exchanged.issued_token_type || SESSION_TRANSFER_TOKEN_IDENTIFIER,
+        issued_token_type: exchanged.issued_token_type || '',
         expires_in: exchanged.expires_in,
         token_type: exchanged.token_type,
         ...(exchanged.scope !== undefined && { scope: exchanged.scope }),

lib/utils/sessionExpiry.js

@@ -50,9 +50,19 @@ function isSessionExpiryInPast(sessionExpiresAt, issuedAt) {
   return isSessionExpiryReached(sessionExpiresAt, reference);
 }
 
+/**
+ * Returns whether an ID token's `exp` claim is expired, applying a forward skew so a token
+ * about to expire is treated as already expired and refreshed before being sent as an actor token.
+ * @param {number} exp - the `exp` claim from the decoded ID token
+ */
+function isIdTokenExpired(exp) {
+  return exp <= epoch() + SESSION_EXPIRY_LEEWAY;
+}
+
 module.exports = {
   SESSION_EXPIRY_LEEWAY,
   extractSessionExpiry,
   isSessionExpiryReached,
   isSessionExpiryInPast,
+  isIdTokenExpired,
 };

test/sessionTransferToken.tests.js

@@ -176,6 +176,84 @@ describe('requestSessionTransferToken', () => {
     assert.equal(response.body.err.error, 'actor_unavailable');
   });
 
+  it('throws 400 with actor_unavailable when id_token is expired and no refresh_token', async () => {
+    const expiredIdToken = makeIdToken({
+      exp: Math.floor(Date.now() / 1000) - 3600,
+    });
+    const { response } = await setup({
+      sttOptions: {
+        subject_token: '__test_subject__',
+        subject_token_type: 'urn:mycompany:test-token',
+      },
+      sessionData: {
+        id_token: expiredIdToken,
+        access_token: '__test_access_token__',
+        token_type: 'Bearer',
+        expires_at: Math.floor(Date.now() / 1000) - 3600,
+      },
+      mockTokenResponse: false,
+    });
+    assert.equal(response.statusCode, 400);
+    assert.equal(response.body.err.error, 'actor_unavailable');
+  });
+
+  it('refreshes expired id_token and uses the fresh one as actor when refresh_token is available', async () => {
+    const expiredIdToken = makeIdToken({
+      exp: Math.floor(Date.now() / 1000) - 3600,
+    });
+    const freshIdToken = makeIdToken();
+
+    const router = express.Router();
+    router.use(auth({ ...defaultConfig }));
+    router.get('/stt', async (req, res, next) => {
+      try {
+        const result = await req.oidc.requestSessionTransferToken({
+          subject_token: '__test_subject__',
+          subject_token_type: 'urn:mycompany:test-token',
+        });
+        res.json(result);
+      } catch (err) {
+        next(err);
+      }
+    });
+
+    server = await createServer(router);
+    const jar = request.jar();
+    await request.post('/session', {
+      baseUrl,
+      jar,
+      json: {
+        id_token: expiredIdToken,
+        access_token: '__test_access_token__',
+        refresh_token: '__test_refresh_token__',
+        token_type: 'Bearer',
+        expires_at: Math.floor(Date.now() / 1000) - 3600,
+      },
+    });
+
+    let capturedSttBody;
+    // First call: refresh grant; second call: STT exchange
+    nock('https://op.example.com')
+      .post('/oauth/token')
+      .reply(200, {
+        access_token: '__new_access_token__',
+        id_token: freshIdToken,
+        refresh_token: '__new_refresh_token__',
+        token_type: 'Bearer',
+        expires_in: 86400,
+      })
+      .post('/oauth/token')
+      .reply(200, function (uri, body) {
+        capturedSttBody = qs.parse(body);
+        return defaultSTTResponse();
+      });
+
+    const response = await request.get('/stt', { baseUrl, jar, json: true });
+    assert.equal(response.statusCode, 200);
+    assert.equal(capturedSttBody.actor_token, freshIdToken);
+    assert.equal(capturedSttBody.actor_token_type, ID_TOKEN_IDENTIFIER);
+  });
+
   // -------------------------------------------------------------------------
   // subject_token validation (reuses validateSubjectToken)
   // -------------------------------------------------------------------------
@@ -268,18 +346,18 @@ describe('requestSessionTransferToken', () => {
     assert.equal(capturedBody.organization, 'org_abc123');
   });
 
-  it('sends reason when provided', async () => {
+  it('forwards extra params to the token endpoint', async () => {
     const { capturedBody } = await setup({
       sttOptions: {
         subject_token: '__test_subject__',
         subject_token_type: 'urn:mycompany:test-token',
-        reason: 'Investigating TCK-4821',
+        extra: { reason: 'Investigating TCK-4821' },
       },
     });
     assert.equal(capturedBody.reason, 'Investigating TCK-4821');
   });
 
-  it('omits scope, organization, and reason when not provided', async () => {
+  it('omits scope, organization, and extra when not provided', async () => {
     const { capturedBody } = await setup({
       sttOptions: {
         subject_token: '__test_subject__',
@@ -288,7 +366,6 @@ describe('requestSessionTransferToken', () => {
     });
     assert.isUndefined(capturedBody.scope);
     assert.isUndefined(capturedBody.organization);
-    assert.isUndefined(capturedBody.reason);
   });
 
   // -------------------------------------------------------------------------
@@ -319,7 +396,7 @@ describe('requestSessionTransferToken', () => {
     );
   });
 
-  it('falls back to SESSION_TRANSFER_TOKEN_IDENTIFIER when issued_token_type is absent', async () => {
+  it('returns empty string for issued_token_type when absent in AS response', async () => {
     const { response } = await setup({
       sttOptions: {
         subject_token: '__test_subject__',
@@ -336,10 +413,7 @@ describe('requestSessionTransferToken', () => {
       },
     });
     assert.equal(response.statusCode, 200);
-    assert.equal(
-      response.body.issued_token_type,
-      SESSION_TRANSFER_TOKEN_IDENTIFIER,
-    );
+    assert.equal(response.body.issued_token_type, '');
   });
 
   it('result has no access_token field — STT is in session_transfer_token', async () => {