Global

Members

(constant) ASYMMETRIC_JWS_ALGS

Asymmetric JWS algorithms this library can verify (via jose, in browsers and Node.js).

Source:

(constant) CAEP

OpenID CAEP 1.0 event types.

Source:

(constant) DEFINITE_JOSE_ERRORS

jose errors that say the SET itself is bad. Anything else (fetching the JWKS, a key it doesn't hold yet) may pass.

Source:

(constant) DELIVERY

SSF delivery methods.

Source:

(constant) DPOP_ALGS

DPoP proof algorithms this library can create, in preference order.

Source:

(constant) ENDPOINTS

Endpoints whose URLs must use TLS.

Source:

(constant) FRONT_CHANNEL_TOKENS

Parameters that must never arrive at a code-flow redirect URI (tokens in the front channel).

Source:

(constant) INTERACTION_REQUIRED

Errors the OP answers a prompt=none request with when it would have to show the person a screen (OpenID Connect Core §3.1.2.6). account_selection_required is what an OP holding several signed-in accounts answers when nothing in the request says which one.

Source:

(constant) MUST_MATCH

Client metadata values the server must honour exactly as requested; if it registers something else (OIDC Dynamic Client Registration 1.0 §3.2 allows substitution) the registration is rejected.

Source:

(constant) NAMED_HANDLERS

Named handler slots. Each maps to one event type URI and gets a matching on<Name>(handler) method.

Source:

(constant) PROFILE_CLAIMS

ID token claims an account record keeps, for display and for naming the account to the OP. No tokens.

Source:

(constant) RESERVED_AUTHORIZATION_PARAMS

Authorization request parameters extraParams may not set: the client sets them, and the callback relies on them.

Source:

(constant) RISC

OpenID RISC 1.0 event types (receivable through onEvent(RISC.X, handler)).

Source:

(constant) SSF

OpenID Shared Signals Framework 1.0 stream-control event types.

Source:

(constant) SSF_URL_MEMBERS

SSF transmitter metadata members that are URLs, all of which must use TLS.

Source:

(constant) SUPPORTED_ID_TOKEN_ALGS

ID token algorithms this library can verify. A public client has no secret, so HS* (MACed with the client secret) is not among them.

Source:

(constant) Subject

Helpers for RFC 9493 Subject Identifiers, as carried in the SET sub_id claim.

Source:

Methods

accountKey(iss, sub) → {Promise.<string>}

The account key for an iss and sub: stable, opaque, and safe in a storage key or a URL.

Parameters:
Name Type Description
iss string
sub string
Source:
Returns:
Type
Promise.<string>

base64url()

base64url without padding.

Source:

clearDiscoveryCache()

Clears the in-process metadata cache (mostly useful in tests).

Source:

codeChallengeS256()

RFC 7636 §4.2 S256 transformation.

Source:

complex()

SSF complex subject, e.g. { user: Subject.issSub(...), session: Subject.opaque(sid) }

Source:

deleteClientRegistration(registration, optsopt)

Deletes a registration (RFC 7592 §2.3).

Parameters:
Name Type Attributes Description
registration ClientRegistration
opts Object <optional>

(TypeScript: { allowInsecureRequests?: boolean, timeoutMs?: number, fetch?: typeof fetch })
Source:

digest()

SHA-256/384/512 digest of a string.

Source:

discoverOpenIdProvider(issuer, optsopt)

Retrieves and validates OpenID Provider metadata from <issuer>/.well-known/openid-configuration.

Parameters:
Name Type Attributes Description
issuer string
opts Object <optional>

(TypeScript: { timeoutMs?: number, fetch?: typeof fetch, cacheTtlMs?: number })
Source:

discoverSSFTransmitter(issuer, optsopt)

Retrieves SSF 1.0 transmitter metadata from /.well-known/ssf-configuration (RFC 8414-style path insertion first, then the appended form).

Parameters:
Name Type Attributes Description
issuer string
opts Object <optional>

(TypeScript: { timeoutMs?: number, fetch?: typeof fetch, cacheTtlMs?: number })
Source:

eventName()

Short name ("session-revoked") for an event type URI.

Source:

fetchMetadata(urls, expectedIssuer, optsopt)

Fetches metadata from the first URL that answers 2xx and checks that its issuer matches exactly.

Parameters:
Name Type Attributes Description
urls Array.<string>
expectedIssuer string
opts Object <optional>

(TypeScript: { timeoutMs?: number, fetch?: typeof fetch, cacheTtlMs?: number })
Source:

generateCodeVerifier()

RFC 7636 §4.1: 43–128 chars; 32 random bytes → 43 base64url chars.

Source:

httpRequest(url, optsopt)

Thin fetch wrapper with timeout and consistent error handling.

Parameters:
Name Type Attributes Description
url string | URL
opts * <optional>

(TypeScript: RequestInit & { timeoutMs?: number, fetch?: typeof fetch })
Source:

htuOf(url) → {string}

The htu of a request: its URL without query and fragment (RFC 9449 §4.2).

Parameters:
Name Type Description
url string | URL
Source:
Returns:
Type
string

isLoopback()

Loopback hosts, where plain http is acceptable (RFC 8252 §7.3, RFC 9700 §2.6).

Source:

isSecureUrl()

https, or plain http to a loopback host. Anything unparseable is not secure.

Source:

logEventReceived(event) → {void}

The default onEventReceived hook: prints one line per accepted event to the console, naming the event and its jti only. The payload and subject can carry personal data (email, phone, session id, IP address), and a console is read by extensions and error reporters, so they are left out. Call it from your own hook to keep the line.

Parameters:
Name Type Description
event SecurityEvent
Source:
Returns:
Type
void

needsInteraction(err) → {boolean}

True when err is an OAuthError that a request showing the sign-in screen (no prompt=none) would get past.

Parameters:
Name Type Description
err unknown
Source:
Returns:
Type
boolean

oidcDiscoveryUrl(issuer)

Builds the OpenID Connect Discovery 1.0 §4 URL: the well-known suffix is appended to the issuer.

Parameters:
Name Type Description
issuer string
Source:

onceEvent()

Resolves when emitter next emits event, with the event's arguments.

Source:

opaqueIs()

An opaque identifier naming exactly id: both must be non-empty strings.

Source:

randomToken()

A cryptographically random base64url string (default 256 bits).

Source:

readClientRegistration(registration, optsopt)

Reads the current registration (OIDC DCR §4 / RFC 7592 §2.1).

Parameters:
Name Type Attributes Description
registration ClientRegistration
opts Object <optional>

(TypeScript: { allowInsecureRequests?: boolean, timeoutMs?: number, fetch?: typeof fetch })
Source:

readJson(res, ErrorClassopt)

Reads a JSON body; turns OAuth error bodies and non-2xx responses into errors.

Parameters:
Name Type Attributes Description
res Response
ErrorClass * <optional>

(TypeScript: typeof OIDCClientError)
Source:

refreshLock()

The lock one key's refreshes and deletes share, across this origin's tabs.

Source:

registerClient(providerMetadata, clientMetadata, optsopt) → {Promise.<ClientRegistration>}

Registers a client with an OpenID Provider (OpenID Connect Dynamic Client Registration 1.0, RFC 7591).

Parameters:
Name Type Attributes Description
providerMetadata Record.<string, any>

OP metadata; must advertise registration_endpoint.
clientMetadata Record.<string, any>

e.g. { redirect_uris, id_token_signed_response_alg, grant_types, ... }
opts Object <optional>

(TypeScript: { initialAccessToken?: string, allowInsecureRequests?: boolean, timeoutMs?: number, fetch?: typeof fetch })
Source:
Returns:
Type
Promise.<ClientRegistration>

subjectMatches(subId, identity) → {boolean}

Tests whether a subject identifier refers to a known identity.

identity fields: iss, sub, sid (session id), email and email_verified, phone_number and phone_number_verified, plus any of device/application/tenant/org_unit/group as opaque ids.

  • An email or phone number identifies somebody only when the OP said it was verified (email_verified / phone_number_verified true): OIDC Core §5.7 makes neither a stable or unique identifier, and an unverified one may be anybody's.
  • A top-level opaque id is compared with sub. A session is named inside a complex subject.
  • In a complex subject every member must match, and the members this identity can't be checked against count as a non-match: an event about one session matches only an identity holding that sid.
Parameters:
Name Type Description
subId Record.<string, any>

An RFC 9493 subject identifier, e.g. a SET's sub_id
identity Record.<string, any>
Source:
Returns:
Type
boolean

timingSafeEqual()

Compares two strings in time independent of where they differ, so a response's state or a logout state cannot be guessed byte by byte from timing. Both sides are hashed first so their lengths match.

Source:

(async) tokenHash()

at_hash: left-most half of the hash of the ASCII value, base64url encoded (OIDC Core §3.1.3.6).

Source:

validateOpenIdProviderMetadata(metadata, expectedIssueropt) → {Record.<string, any>}

Validates an OpenID Provider metadata document (OIDC Discovery 1.0 §3) for use by a code-flow RP.

Parameters:
Name Type Attributes Description
metadata Record.<string, any>
expectedIssuer string <optional>

When given, issuer must match exactly (§4.3).
Source:
Returns:

the same metadata

Type
Record.<string, any>

wantsDpopNonce(response) → {boolean}

Whether a resource server's 401 asks for a (new) DPoP nonce (RFC 9449 §9).

Parameters:
Name Type Description
response Response
Source:
Returns:
Type
boolean

wellKnownUrls(issuer, suffix)

Builds RFC 8414 §3-style well-known URLs: the suffix is inserted between host and path. Some deployments instead append it (OIDC style), so both are returned in preference order.

Parameters:
Name Type Description
issuer string
suffix string

e.g. "ssf-configuration"
Source:

withLock(name, fn) → {Promise.<T>}

Runs fn holding the lock name: across every tab of this origin where the Web Locks API exists (navigator.locks), otherwise within this JavaScript realm only.

Parameters:
Name Type Description
name string
fn function

(TypeScript: () => Promise<T>)
Source:
Returns:
Type
Promise.<T>

Type Definitions

Account

One person signed in through this client in this browser. Holds no token.

Type:
  • object
Properties:
Name Type Attributes Description
key string

Stable id derived from iss and sub.
iss string
sub string
sid string <optional>

The OP session (OpenID Connect Front-/Back-Channel Logout sid).
name string <optional>
email string <optional>
preferred_username string <optional>
status 'signed-in' | 'tokens-missing' | 'signed-out' | 'ended'

signed-in: its tokens are in the cache. tokens-missing: not signed out, but its cached tokens could not be used (e.g. expired with no refresh token); resume() asks the OP for new ones without a screen while its session there lasts. ended: ended by the OP, a security event or a refused refresh; see endedReason.
endedReason string <optional>
addedAt number
lastUsedAt number
changedAt number <optional>

When the status last left signed-in.
Source:

Account

(TypeScript: import('./accounts.js').Account)

Type:
  • *
Source:

AccountHook(account, access) → {unknown}

Parameters:
Name Type Description
account Account
access function

(TypeScript: { getTokenSet: (opts?: { forceRefresh?: boolean }) => Promise<import('./token-set.js').TokenSet> }) Reaches this account's tokens during the hook (and, for onActivate, for as long as it stays active).
Source:
Returns:

Anything; a promise is awaited.

Type
unknown

AccountHook

(TypeScript: import('./accounts.js').AccountHook)

Type:
  • *
Source:

AccountManagerOptions

Type:
  • object
Properties:
Name Type Attributes Description
store * <optional>

(TypeScript: import('./stores.js').TokenStore) The cache shared by every tab: the account list and each account's tokens. Default: IndexedDB (IndexedDBTokenStore) when the client has a DPoP key, else memory. A persistent store without DPoP is allowed, with a console warning.
tabStore * <optional>

(TypeScript: import('./stores.js').TokenStore) Where this tab remembers its active account. Default: sessionStorage where it exists, else memory.
storeKey string <optional>

Default "accounts".
refreshSkewSec number <optional>

Default 60.
maxAccounts number <optional>

Default 10. Past it the account signed out longest ago is forgotten; when every place is held by a signed-in account, a further sign-in is refused.
rememberSignedOutDays number <optional>

How long a signed-out account stays listed. Default 30.
loginHint function <optional>

(TypeScript: (account: Account) => string|undefined) What names an account to the OP in login_hint. Default: preferred_username, else email.
onActivate AccountHook <optional>

Runs when an account is about to become this tab's active account, after its tokens are refreshed if due and before "activated" is emitted — e.g. to poll its CAEP stream and act on the signals queued while it was dormant. Throwing aborts the activation.
onDeactivate function <optional>

(TypeScript: (account: Account) => void|Promise<void>) Runs when an account stops being this tab's active account (e.g. to stop polling its stream).
onLeave AccountHook <optional>

Runs before an account's tokens are deleted by signOut() or end() (e.g. to delete its CAEP stream while its tokens still work).
broadcast boolean <optional>

Tell this origin's other tabs about changes (BroadcastChannel). Default true.
Source:

AccountManagerOptions

(TypeScript: import('./accounts.js').AccountManagerOptions)

Type:
  • *
Source:

ClientRegistration

(TypeScript: import('./registration.js').ClientRegistration)

Type:
  • *
Source:

ClientRegistration

Client Information Response (RFC 7591 §3.2.1 / OIDC DCR §3.2)

Type:
  • object
Properties:
Name Type Attributes Description
client_id string
client_secret string <optional>
client_secret_expires_at number <optional>
registration_access_token string <optional>

RFC 7592 / OIDC DCR §3.2
registration_client_uri string <optional>
id_token_signed_response_alg string <optional>
token_endpoint_auth_method string <optional>
Source:

KeyStore

Where a DPoP key pair is kept between page loads. extractable: true says the store can only hold an extractable key (Web Storage holds strings), so DPoPKey.loadOrCreate generates one.

Type:
  • object
Properties:
Name Type Attributes Description
get function

(TypeScript: () => Promise<StoredKey|undefined>)
set function

(TypeScript: (value: StoredKey) => Promise<void>)
delete function

(TypeScript: () => Promise<void>)
extractable boolean <optional>
Source:

KeyStore

(TypeScript: import('./dpop.js').KeyStore)

Type:
  • *
Source:

OIDCClientConfig

(TypeScript: import('./oidc-client.js').OIDCClientConfig)

Type:
  • *
Source:

OIDCClientConfig

Type:
  • object
Properties:
Name Type Attributes Description
issuer string <optional>

Issuer; metadata is loaded from <issuer>/.well-known/openid-configuration.
metadata Record.<string, any> <optional>

A provider metadata document to use instead of discovery.
clientId string

A PUBLIC client (token_endpoint_auth_method "none").
redirectUri string <optional>
postLogoutRedirectUri string <optional>
scope string <optional>

Default "openid profile email offline_access" (offline_access only if supported).
resource string | Array.<string> <optional>

RFC 8707 resource indicator(s): audience-restricts the tokens.
idTokenSignedResponseAlg string <optional>

Expected ID token alg (default RS256).
par 'auto' | 'always' | 'never' <optional>

Pushed Authorization Requests (RFC 9126). Default "auto": used when advertised.
dpop * <optional>

(TypeScript: boolean|{ key?: DPoPKey, keyStore?: import('./dpop.js').KeyStore, alg?: string }) DPoP (RFC 9449). true generates a non-extractable key kept in memory; pass keyStore (e.g. new IndexedDBKeyStore()) to keep it across page loads.
userinfoSignedResponseAlg string <optional>

The only alg a signed UserInfo response may use. Default: any asymmetric algorithm.
requireDpop boolean <optional>

With DPoP enabled, refuse a token response whose token_type is Bearer (RFC 9449 §5: the AS may fall back, but this client asked for bound tokens). Default: true when dpop is set. A refresh of DPoP-bound tokens never accepts Bearer, whatever this says.
transactionStore TransactionStore <optional>

Where state/nonce/PKCE verifier wait for the callback (default sessionStorage).
transactionTtlSec number <optional>

How long an authorization request stays redeemable (default 600).
maxIdTokenAgeSec number <optional>

Reject ID tokens whose iat is older than this (default 600).
enforceAcr boolean <optional>

When acr_values were requested, require the ID token's acr to be one of them (default true).
requireAuthTime boolean <optional>

Require auth_time in every ID token (default false).
allowInsecureRequests boolean <optional>

Allow non-TLS endpoints and redirect URIs other than loopback (default false).
clockToleranceSec number <optional>

Allowed clock skew (default 30).
httpTimeoutMs number <optional>

Per-request timeout (default 10000).
discoveryCacheTtlMs number <optional>

How long discovered metadata is cached (default 1h).
fetch * <optional>

(TypeScript: typeof fetch) Custom fetch implementation.
Source:

SSFErrorContext

Where an error came from.

Type:
  • object
Properties:
Name Type Attributes Description
phase 'poll' | 'handler' | 'hook' | 'stop' | 'error'

poll: polling or validating a SET; handler: a handler threw; hook: onEventReceived threw; stop: sending the last acknowledgements failed.
jti string <optional>

The SET concerned, when there is one.
event SecurityEvent <optional>

The event whose handler threw.
willRetry boolean <optional>

The SET was left for the transmitter to send again.
Source:

SSFErrorContext

(TypeScript: import('./caep/ssf-receiver.js').SSFErrorContext)

Type:
  • *
Source:

SSFErrorHandler(error, context) → {void}

Parameters:
Name Type Description
error *

(TypeScript: Error & { code?: string })
context SSFErrorContext
Source:
Returns:
Type
void

SSFErrorHandler

(TypeScript: import('./caep/ssf-receiver.js').SSFErrorHandler)

Type:
  • *
Source:

SSFReceiverConfig

Type:
  • object
Properties:
Name Type Attributes Description
transmitterIssuer string

SSF transmitter issuer; metadata is loaded from its /.well-known/ssf-configuration. Delivery is RFC 8936 POLL: a browser cannot receive a push. (SETs obtained any other way can still be handed to receiveSet().)
audience string | Array.<string> <optional>

Expected SET aud. Defaults to the aud in the stream configuration.
eventsRequested Array.<string> <optional>

Default: all CAEP event types.
accessToken function <optional>

(TypeScript: () => Promise<string>|string) Bearer token for the transmitter's management and poll endpoints.
authorizationHeaders function <optional>

(TypeScript: (req: { method: string, url: string, nonce?: string }) => Promise<Record<string,string>>) Alternative to accessToken: returns the Authorization (and DPoP) headers for one request, e.g. (r) => oidcClient.resourceHeaders(tokenSet, r) for a DPoP-bound token.
streamId string <optional>

Use an existing stream instead of creating one.
description string <optional>
pollIntervalMs number <optional>

Default 5000.
maxEvents number <optional>

Max SETs per poll. Default 25.
clockToleranceSec number <optional>

Default 60.
maxSetAgeSec number <optional>

Reject SETs whose iat is older than this (seconds). Default 0: no limit. A polled SET waits at the transmitter until it is read, so an age limit would throw away the signals a stopped receiver catches up on. A replay is caught by its jti whatever its age.
maxDeliveryAttempts number <optional>

How many times a SET whose handlers throw is left for the transmitter to send again before it is acknowledged anyway (onError gets handler_failed). Default 5. A SET that can't be checked for a reason that may pass (a network error, a signing key not yet in the JWKS) is never reported as an error: it is left for redelivery until it can.
allowInsecureRequests boolean <optional>

Allow non-TLS SSF URLs other than loopback. Default false.
deleteOnPageHide boolean <optional>

Delete the stream, best effort, when the page is unloaded for good (pagehide that is not entering the back/forward cache). Default false: a stream kept across visits holds the events that arrive while no tab is open, which start({ catchUp: true }) delivers, and a browser may drop a request sent while a page unloads. Leave it off and let the transmitter time an abandoned stream out (iya-sts: ssf.personStreamInactivityTimeoutS).
pageEvents Object <optional>

Where pagehide is listened for. Default globalThis (the window).
trustedPollOrigins Array.<string> <optional>

Origins besides the transmitter's issuer and configuration_endpoint that the stream's poll endpoint_url may be at. The poll request carries the person's access token, so it is refused anywhere else.
requireTyp boolean <optional>

Require the typ: secevent+jwt header (SSF §4.1.9). Default true.
jtiCacheSize number <optional>

Replay-protection window size. Default 10000.
httpTimeoutMs number <optional>
fetch * <optional>

(TypeScript: typeof fetch)
handlers * <optional>

(TypeScript: Partial<Record<keyof typeof NAMED_HANDLERS, SecurityEventHandler>>)
onEventReceived SecurityEventHandler | null <optional>

Your logic for every accepted event: called once per event, before the typed handlers, and awaited. Default logEventReceived, which prints the event to the console. null turns it off. A throw goes to onError with phase: 'hook', and the typed handlers still run.
Source:

SSFReceiverConfig

(TypeScript: import('./caep/ssf-receiver.js').SSFReceiverConfig)

Type:
  • *
Source:

SecurityEvent

What every handler receives.

Type:
  • object
Properties:
Name Type Description
type string

Event type URI.
name string

Short name, e.g. "session-revoked".
payload Record.<string, any>

The event-specific object from the SET events claim.
subject Record.<string, any> | undefined

RFC 9493 subject identifier (sub_id, or legacy subject inside the event).
eventTimestamp number | undefined

CAEP event_timestamp (seconds), falling back to SET toe/iat.
initiatingEntity string | undefined

"admin" | "user" | "policy" | "system"
reasonAdmin Record.<string, string> | undefined
reasonUser Record.<string, string> | undefined
jti string
iss string
aud string | Array.<string>
iat number
txn string | undefined
set Record.<string, any>

All validated SET claims.
raw string

The SET as received (compact JWS).
Source:

SecurityEvent

(TypeScript: import('./caep/ssf-receiver.js').SecurityEvent)

Type:
  • *
Source:

SecurityEventHandler(event) → {unknown}

Parameters:
Name Type Description
event SecurityEvent
Source:
Returns:

Anything; a promise is awaited before the SET is acknowledged.

Type
unknown

SecurityEventHandler

(TypeScript: import('./caep/ssf-receiver.js').SecurityEventHandler)

Type:
  • *
Source:

StoredKey

Type:
  • object
Properties:
Name Type Description
alg string
keyPair CryptoKeyPair
Source:

StoredKey

(TypeScript: import('./dpop.js').StoredKey)

Type:
  • *
Source:

StoredTokens

(TypeScript: import('./stores.js').StoredTokens)

Type:
  • *
Source:

StoredTokens

A token set as a store keeps it (TokenSet#toJSON()).

Type:
  • Record.<string, any>
Source:

TokenStore

(TypeScript: import('./stores.js').TokenStore)

Type:
  • *
Source:

TokenStore

Storage for tokens and for in-flight authorization transactions.

Token store interface (async or sync methods):

Type:
  • object
Properties:
Name Type Description
get function

(TypeScript: (key: string) => Promise<object|undefined>|object|undefined)
set function

(TypeScript: (key: string, value: object) => Promise<void>|void)
delete function

(TypeScript: (key: string) => Promise<void>|void)
Source: