feat: add req.oidc.getAccessToken() with multi-resource refresh token support

Adds `req.oidc.getAccessToken(options?)` to `RequestContext`. The method
returns a valid access token for any resource server by:

- Returning a cached token from `session.tokenSets` when it exists and has
  not expired.
- Performing a refresh token grant (including MRRT for alternate audiences)
  when the cached entry is missing or stale, then caching the result.

New helpers:
- `lib/utils/tokenSets.js` — `getOrInitTokenSets` / `updateTokenSets` manage
  the per-audience token cache in the session.
- `lib/utils/compareScopes.js` — returns true when cached scopes are a superset
  of the requested scopes, avoiding unnecessary token exchanges.

Backward compatibility: sessions created before this change are transparently
migrated on the first `getAccessToken()` call; no re-login is required.

TypeScript: adds `GetAccessTokenOptions` interface and `Session.tokenSets`
field to `index.d.ts`.

Tests: 11 new tests in `test/getAccessToken.tests.js` covering cache hits,
expiry-driven refreshes, MRRT exchange, scope superset matching, legacy
session hydration, and error paths.

Author: cschetan77

index.d.ts

@@ -68,6 +68,17 @@ interface Session {
    * hard expiry on every session read and before any token refresh.
    */
   sessionExpiresAt?: number;
+  /**
+   * Per-audience token cache used by {@link RequestContext.getAccessToken}.
+   * Populated automatically on the first `getAccessToken()` call. Pre-existing
+   * sessions without this field are migrated transparently — no re-login required.
+   */
+  tokenSets?: Array<{
+    audience: string;
+    access_token: string;
+    scope?: string;
+    expires_at?: number;
+  }>;
   [key: string]: any;
 }
 
@@ -295,6 +306,32 @@ interface RequestContext {
   customTokenExchange?: (
     options?: CustomTokenExchangeOptions,
   ) => Promise<TokenExchangeResponse>;
+
+  /**
+   * Retrieves an access token from the session cache, or performs a refresh token
+   * grant (including Multi-Resource Refresh Token exchange) when the cached token
+   * is absent or expired.
+   *
+   * ```js
+   * // Default audience — equivalent to req.oidc.accessToken but async and cache-aware
+   * const { access_token } = await req.oidc.getAccessToken();
+   *
+   * // MRRT: exchange the session's refresh token for a different resource server
+   * const { access_token } = await req.oidc.getAccessToken({
+   *   audience: 'https://api-b.example.com',
+   *   scope: 'read:reports',
+   * });
+   * ```
+   *
+   * Tokens are cached per audience+scope in `session.tokenSets` and reused on
+   * subsequent calls until they expire.
+   *
+   * **Errors thrown:**
+   * - `Error` — user has no active session
+   * - `Error` — token is expired and no refresh token is available
+   * - `SessionExpiredError` — IdP session ceiling has been reached
+   */
+  getAccessToken(options?: GetAccessTokenOptions): Promise<AccessToken>;
 }
 
 /**
@@ -466,8 +503,7 @@ interface BackchannelLogoutOptions {
    * (See {@link https://github.com/auth0/express-openid-connect/tree/master/examples/examples/backchannel-logout-custom-genid.js} or {@link https://github.com/auth0/express-openid-connect/tree/master/examples/examples/backchannel-logout-custom-query-store.js})
    */
   onLogin?:
-    | false
-    | ((req: Request, config: ConfigParams) => Promise<void> | void);
+    false | ((req: Request, config: ConfigParams) => Promise<void> | void);
 }
 
 /**
@@ -1047,6 +1083,25 @@ interface CookieConfigParams {
   sameSite?: string;
 }
 
+/**
+ * Options for {@link RequestContext.getAccessToken}.
+ */
+interface GetAccessTokenOptions {
+  /**
+   * The audience (resource server identifier) to request an access token for.
+   * When different from the audience used at login, the SDK performs a
+   * Multi-Resource Refresh Token (MRRT) exchange using the session's refresh token.
+   * If omitted, falls back to `authorizationParams.audience` or the default audience.
+   */
+  audience?: string;
+
+  /**
+   * Space-separated scopes to request.
+   * If omitted, falls back to `authorizationParams.scope`.
+   */
+  scope?: string;
+}
+
 interface AccessToken {
   /**
    * The access token itself, can be an opaque string, JWT, or non-JWT token.

lib/context.js

@@ -38,6 +38,8 @@ const {
   isSessionExpiryReached,
   isSessionExpiryInPast,
 } = require('./utils/sessionExpiry');
+const compareScopes = require('./utils/compareScopes');
+const { getOrInitTokenSets, updateTokenSets } = require('./utils/tokenSets');
 
 // Caches one RemoteJWKSet instance per auth() configuration for backchannel logout token verification.
 const jwksClientCache = new Map();
@@ -442,6 +444,104 @@ class RequestContext {
       });
     }
   }
+
+  async getAccessToken(options = {}) {
+    const { config, req } = weakRef(this);
+    const session = req[config.session.name];
+
+    if (!session || !('id_token' in session)) {
+      throw new Error('The user does not have an active session.');
+    }
+
+    if (isSessionExpiryReached(session.sessionExpiresAt)) {
+      throw new SessionExpiredError();
+    }
+
+    const requestedAudience =
+      options.audience ?? config.authorizationParams?.audience;
+    const audience = requestedAudience ?? 'default';
+    const scope = options.scope ?? config.authorizationParams?.scope;
+
+    // Hydrate tokenSets from flat session fields for pre-MRRT sessions.
+    if (!session.tokenSets) {
+      session.tokenSets = getOrInitTokenSets(session, audience);
+    }
+
+    // Cache hit: valid, non-expired token for this audience+scope.
+    // When ts.scope is undefined (hydrated from a pre-MRRT flat session) we
+    // treat it as a match — we don't know what scopes that token has, so we
+    // let it through and let Auth0 enforce scope constraints.
+    const cached = session.tokenSets.find(
+      (ts) =>
+        ts.audience === audience &&
+        (ts.scope === undefined || !scope || compareScopes(ts.scope, scope)),
+    );
+    if (cached && cached.expires_at > Math.floor(Date.now() / 1000)) {
+      const cachedExpiresIn = cached.expires_at - Math.floor(Date.now() / 1000);
+      return {
+        access_token: cached.access_token,
+        token_type: session.token_type || 'Bearer',
+        expires_in: cachedExpiresIn > 0 ? cachedExpiresIn : 0,
+        isExpired: isExpired.bind(this),
+        refresh: refresh.bind(this),
+      };
+    }
+
+    if (!session.refresh_token) {
+      throw new Error(
+        'The access token has expired and a refresh token was not found in the session. The user needs to re-authenticate.',
+      );
+    }
+
+    debug(
+      'getAccessToken() cache miss for audience=%s, exchanging refresh token',
+      audience,
+    );
+
+    const { configuration } = await getClient(config);
+    const parameters = {
+      ...(requestedAudience && { audience: requestedAudience }),
+      ...(scope && { scope }),
+      ...config.tokenEndpointParams,
+    };
+
+    const newTokenSet = await oidcClient.refreshTokenGrant(
+      configuration,
+      session.refresh_token,
+      Object.keys(parameters).length ? parameters : undefined,
+    );
+
+    // Update the per-audience token cache.
+    session.tokenSets = updateTokenSets(
+      session.tokenSets,
+      audience,
+      newTokenSet,
+    );
+    // Preserve rotated refresh token.
+    session.refresh_token = newTokenSet.refresh_token || session.refresh_token;
+
+    // Keep flat fields in sync when refreshing the config/default audience
+    // so req.oidc.accessToken continues to reflect the latest token.
+    const configAudience = config.authorizationParams?.audience ?? 'default';
+    if (audience === configAudience) {
+      session.access_token = newTokenSet.access_token;
+      session.token_type = normalizeTokenType(newTokenSet.token_type);
+      session.expires_at = newTokenSet.expires_in
+        ? epoch() + newTokenSet.expires_in
+        : undefined;
+      // Invalidate the internal TokenSet wrapper so accessToken re-reads from session.
+      const cachedTokenSet = weakRef(session);
+      delete cachedTokenSet.value;
+    }
+
+    return {
+      access_token: newTokenSet.access_token,
+      token_type: normalizeTokenType(newTokenSet.token_type),
+      expires_in: newTokenSet.expires_in ?? 0,
+      isExpired: isExpired.bind(this),
+      refresh: refresh.bind(this),
+    };
+  }
 }
 
 class ResponseContext {

lib/utils/compareScopes.js

@@ -0,0 +1,20 @@
+'use strict';
+
+/**
+ * Returns true if cachedScope contains every scope token in requestedScope.
+ * Used to determine whether a cached token satisfies a narrower scope request.
+ *
+ * @param {string|undefined} cachedScope - space-separated scopes on the cached token
+ * @param {string|undefined} requestedScope - space-separated scopes being requested
+ * @returns {boolean}
+ */
+function compareScopes(cachedScope, requestedScope) {
+  if (cachedScope === requestedScope) return true;
+  if (!cachedScope || !requestedScope) return false;
+
+  const cached = new Set(cachedScope.trim().split(/\s+/).filter(Boolean));
+  const requested = requestedScope.trim().split(/\s+/).filter(Boolean);
+  return requested.every((s) => cached.has(s));
+}
+
+module.exports = compareScopes;

lib/utils/tokenSets.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const { epoch } = require('./epoch');
+
+/**
+ * Initialises the tokenSets array from an existing flat session.
+ * Called once when an old session (pre-MRRT) is encountered so the new
+ * cache structure is bootstrapped without requiring a fresh token exchange.
+ *
+ * @param {object} session - the raw session object
+ * @param {string} audience - the synthetic audience key ('default' or real audience)
+ * @returns {Array}
+ */
+function getOrInitTokenSets(session, audience) {
+  if (session.tokenSets) return session.tokenSets;
+
+  if (session.access_token) {
+    return [
+      {
+        audience,
+        access_token: session.access_token,
+        scope: undefined,
+        expires_at: session.expires_at,
+      },
+    ];
+  }
+
+  return [];
+}
+
+/**
+ * Merges a newly-fetched token into the tokenSets array.
+ * Replaces an existing entry for the same audience+scope, or appends a new one.
+ *
+ * @param {Array} tokenSets - existing tokenSets from session
+ * @param {string} audience - audience key for the new token
+ * @param {object} tokenResponse - raw token endpoint response from openid-client
+ * @returns {Array} updated tokenSets (new array reference)
+ */
+function updateTokenSets(tokenSets, audience, tokenResponse) {
+  const scope = tokenResponse.scope;
+  const entry = {
+    audience,
+    access_token: tokenResponse.access_token,
+    scope,
+    expires_at: tokenResponse.expires_in
+      ? epoch() + tokenResponse.expires_in
+      : undefined,
+  };
+
+  const idx = tokenSets.findIndex(
+    (ts) => ts.audience === audience && ts.scope === scope,
+  );
+
+  if (idx === -1) {
+    return [...tokenSets, entry];
+  }
+
+  const updated = [...tokenSets];
+  updated[idx] = entry;
+  return updated;
+}
+
+module.exports = { getOrInitTokenSets, updateTokenSets };