Relying-party module

import { createRelyingParty } from '@tdacorp/identity-sdk/rp'const rp = createRelyingParty({  issuer: 'https://identity.tdacorp.in',  clientId,  redirectUri: 'https://app.example.com/api/auth/callback',  key: { kid: 'k1', privateKey: privateJwk },  dpop,})

Clients that authenticate with none or with client certificates are not supported by this module.

startAuthorization input#

In order, and nothing is sent to the token endpoint until all pass: the stored transaction is valid and belongs to this issuer and client; no parameter is repeated; the transaction has not expired; iss is present and equals the issuer the flow started at; state matches; then any error is reported; and last the code is read. After the exchange it verifies the ID token as described in ID token. If that fails the tokens are not returned and the refresh token is revoked.

The transaction holds the PKCE verifier, the nonce and the redirect address. Keep it sealed: encrypted and integrity-protected, or on your server under an opaque session id. See Sealed sessions.

TokenSet: accessToken, tokenType (Bearer or DPoP), expiresAt, scope (array), refreshToken and idToken (each string | null).

VerifiedIdToken: claims, sub, sid, acr, amr, authTime and expiresAt. For a client registered with a pairwise subject type, sub is the per-client value, which differs from the sub in the access token (VerifiedAccessToken.subject). Key your users on one of them, normally this one, and never on both; see Pairwise subjects.

generateDpopKeyPair(alg?) (default ES256), exportDpopKeyPair, importDpopKeyPair, dpopThumbprint and signDpopProof are exported. Generate one key, export it, keep it in your secret store and import it at start-up: a refresh token is bound to its thumbprint. See DPoP.

All errors extend RpError and carry a reason.

A 5xx, a timeout and an OAuth error are surfaced, never retried. The module makes two kinds of retry: the single DPoP nonce retry, and the bounded retry of a 429 described next. Both rebuild the whole request, including a fresh client assertion and a fresh DPoP proof.

A 429 from the issuer is retried for the pushed authorization, token and revocation requests and for the discovery and key-set fetches. Nothing else is retried. The wait honours the Retry-After header (a number of seconds or an HTTP date) plus a little random jitter. Without the header it backs off exponentially with jitter.

When the attempts run out, OAuthEndpointError has reason rate_limited, status 429, retryAfterSeconds from the last answer and attempts, the number of requests made. A discovery or key-set fetch that runs out becomes a DiscoveryError with reason unavailable. A value outside these bounds is refused when the module is created.

// Login routeconst { url, transaction } = await rp.startAuthorization({ scope: 'openid profile offline_access' })await saveSealed(session, transaction)return redirect(url)// Callback routeconst { tokens, idToken } = await rp.handleCallback(new URL(request.url), await loadSealed(session))// Later: rotate. Persist the new refresh token before dropping the old one.const next = await rp.refresh(tokens.refreshToken)

saveSealed and loadSealed are yours.

• Seal the transaction. If a person can edit it, the nonce and redirect checks prove nothing.
• Serialize refreshes per token, and persist the new token first. See Refresh token.
• Never log the result of handleCallback. It holds credentials.

• Quickstart
• Log users in
• Token endpoint