feat(sessionTransferToken): add CTE impersonation via Session Transfer Token

[cschetan77]

Summary

Adds Custom Token Exchange (CTE) — Impersonation via Session Transfer.

This extends the existing req.oidc.customTokenExchange surface with two new methods that implement the initiator role of the session transfer flow: an application requests a short-lived, single-use Session Transfer Token (STT) via CTE, then redirects the user's browser to a target app's login URL carrying that STT, which is redeemed at /authorize to establish an ephemeral web session as the subject user with the actor recorded in the act claim.

New methods on req.oidc

requestSessionTransferToken(options)

Performs a token exchange against the urn:{domain}:session_transfer audience and returns a SessionTransferTokenResult. The SDK handles the protocol plumbing automatically:

• Builds the audience from the configured issuerBaseURL hostname
• Sources the actor_token from the current session id_token, checking the id_token's own exp claim (with a 30s skew). If expired and a refresh token is available, the session is refreshed automatically; if the refresh returns no new id_token, raises actor_unavailable. If expired with no refresh token, raises actor_unavailable before any network call. An explicit actor_token override is accepted to bypass session sourcing entirely.
• Raises actor_unavailable (HTTP 400) client-side before any network call when no actor can be resolved.
• Validates that the AS response carries issued_token_type === "urn:auth0:params:oauth:token-type:session_transfer_token" — an unexpected or missing value raises HTTP 500 (invalid_token_response).
• The returned STT is never written to the session — it is a one-shot handle to be forwarded immediately.

app.post('/impersonate', requiresAuth(), async (req, res) => {
  const result = await req.oidc.requestSessionTransferToken({
    subject_token: req.body.customerToken,
    subject_token_type: 'urn:mycompany:customer-subject',
    extra: { reason: 'Investigating ticket TCK-1234' },
  });
  res.redirect(req.oidc.buildSessionTransferRedirect('https://app.example.com/login', result));
});

buildSessionTransferRedirect(targetLoginUrl, result, opts?)

Pure URL builder — appends session_transfer_token (and optionally organization) as query parameters to targetLoginUrl. Makes no network call and writes nothing to the session. The caller passes the returned string to res.redirect().

Security: targetLoginUrl must be a trusted, app-controlled value — never derive it from untrusted input (e.g. a query parameter), as the STT would be forwarded to an attacker-controlled host. The URL must use https: — http: is accepted only for localhost, 127.0.0.1, and [::1] for local development; any other scheme or non-loopback http: host throws a TypeError.

Target side (no SDK changes needed)

The existing login path already forwards authorizationParams to /authorize, so redeeming an inbound STT requires no new SDK code:

app.get('/login', (req, res) =>
  res.oidc.login({
    authorizationParams: {
      session_transfer_token: req.query.session_transfer_token,
    },
  })
);

New TypeScript types

• SessionTransferTokenResult — result type returned by requestSessionTransferToken
• SessionTransferTokenOptions — input options for requestSessionTransferToken
• SessionTransferRedirectOptions — options for buildSessionTransferRedirect

Error codes

Code	HTTP	Where	When
actor_unavailable	400	client-side	No actor passed and no usable session id_token (not logged in, expired with no refresh token, refresh returned no new id_token, or no id_token in session)
setactor_required	400	server	CTE Action did not call setActor
session_transfer_disabled	400	server	Tenant feature flag is off
invalid_token_response	500	client-side	AS returned an unexpected or missing issued_token_type

Implementation notes

• Fully additive — no existing types, methods, or behavior changed. All existing customTokenExchange tests continue to pass.
• Reuses validateSubjectToken, validateTokenExchangeExtras, TOKEN_EXCHANGE_GRANT_TYPE, and the genericGrantRequest CTE machinery.
• isIdTokenExpired(exp) added to lib/utils/sessionExpiry.js, reusing the existing SESSION_EXPIRY_LEEWAY (30s skew). Guards against non-numeric exp (fails closed — treats as expired).
• SESSION_TRANSFER_TOKEN_IDENTIFIER defined as an internal constant in lib/context.js — not exported; the URN is documented in EXAMPLES.md and the type declarations for developers who need to branch on issued_token_type.

Test plan

• 35 tests in test/sessionTransferToken.tests.js covering: actor resolution (session sourcing, explicit override, blank actor, no session, no id_token in session, expired id_token with and without refresh token, refresh returning no new id_token, non-numeric exp), subject_token validation, audience construction, optional params (scope, organization, extra), result shape (STT in session_transfer_token, no access_token, no act), issued_token_type validation at exchange (unexpected and missing both throw 500), no-persistence guarantee, server error code mapping, and buildSessionTransferRedirect URL construction (including https enforcement and all three loopback variants).
• All existing tests pass without modification.

[kishore7snehil]

new URL(targetLoginUrl) accepts any scheme, so an http: (or javascript:/data:) target parses fine and the STT gets appended as a query param. The JSDoc already says to use https: in production, and since this helper is the one place that hardening can live, an http:/https: allowlist (with a localhost exception for dev) would make that guidance actually hold.

[cschetan77]

Done. buildSessionTransferRedirect now rejects any targetLoginUrl that isn't https:, with an exception for http: on localhost, 127.0.0.1, and [::1] to support local development. Any other scheme (http: on a non-loopback host, ftp:, javascript:, data:, etc.) throws a TypeError. Aligns with the same check in auth0-server-js.
Five tests added covering the rejection cases and all three loopback variants.

[kishore7snehil]

We can avoid calling out the flag name as it's an internal detail