@adonis-agora/authkit-client 0.18.9 → 0.19.0

package/build/src/authorization.js

@@ -0,0 +1,142 @@
+/**
+ * Authorization-code flow in two calls: one to start it, one to finish it.
+ *
+ * `buildAuthorizeUrl` + `exchangeCode` are the raw steps; these two wrap them
+ * with everything a callback must check and is easy to forget — `state`, the
+ * RFC 9207 `iss` parameter, PKCE and the id_token (signature, `aud`, `nonce`…).
+ *
+ * ```ts
+ * const { url, pending } = await createAuthorizationRequest({ issuer, clientId, redirectUri, scopes, endpoints })
+ * session.put('oidc_pending', pending)
+ * // ...IdP redirects back...
+ * const { tokens, claims } = await completeAuthorization({
+ *   issuer, clientId, clientSecret, redirectUri, endpoints,
+ *   pending: session.pull('oidc_pending'),
+ *   callbackParams: request.qs(),
+ * })
+ * ```
+ *
+ * Inside an AdonisJS app, prefer the `AuthkitClientManager` methods of the same
+ * name — they fill the config and the discovered endpoints in for you.
+ */
+import { randomBytes } from 'node:crypto';
+import { base64url } from 'jose';
+import { conventionEndpoints } from './discovery.js';
+import { InvalidIdTokenError, validateIdToken, } from './id_token.js';
+import { buildAuthorizeUrl, exchangeCode, generatePkce } from './oidc_login.js';
+const random = () => base64url.encode(randomBytes(32));
+/** Builds the authorize URL with fresh `state`, `nonce` and PKCE (S256). */
+export async function createAuthorizationRequest(p) {
+    const { verifier, challenge } = await generatePkce();
+    const state = random();
+    const nonce = random();
+    const extraParams = { ...p.extraParams };
+    if (p.maxAge !== undefined)
+        extraParams.max_age = p.maxAge;
+    const url = buildAuthorizeUrl({
+        issuer: p.issuer,
+        clientId: p.clientId,
+        redirectUri: p.redirectUri,
+        scopes: p.scopes,
+        state,
+        nonce,
+        codeChallenge: challenge,
+        authorizationEndpoint: p.endpoints?.authorizationEndpoint,
+        extraParams,
+    });
+    const pending = { state, nonce, codeVerifier: verifier };
+    if (p.maxAge !== undefined)
+        pending.maxAge = p.maxAge;
+    return { url, pending };
+}
+export class OidcCallbackError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, { cause: options?.cause });
+        this.code = code;
+        this.name = 'OidcCallbackError';
+        this.idpError = options?.idpError;
+    }
+    idpError;
+    /**
+     * True when the right answer is to send the user back to login: the callback is
+     * stale or did not belong to this browser, or the IdP sent the user back with an
+     * error (`access_denied`, `login_required`…; see `idpError` to tell them apart).
+     * False for real failures — a mix-up, a failed token exchange or id_token check.
+     */
+    get restartable() {
+        return (this.code === 'missing_pending' ||
+            this.code === 'state_mismatch' ||
+            this.code === 'idp_error' ||
+            this.code === 'missing_code');
+    }
+}
+/**
+ * Finishes the authorization-code flow: checks `state` and `iss`, exchanges the
+ * code (with the PKCE verifier) and validates the id_token, `nonce` included.
+ *
+ * Throws {@link OidcCallbackError}; `error.restartable` tells "send the user back
+ * to login" from a real failure.
+ */
+export async function completeAuthorization(p) {
+    const q = p.callbackParams;
+    const str = (v) => (typeof v === 'string' && v ? v : undefined);
+    const { issuer, tokenEndpoint, jwksUri } = p.endpoints ?? conventionEndpoints(p.issuer);
+    const pending = p.pending;
+    if (!pending?.state || !pending.nonce || !pending.codeVerifier) {
+        throw new OidcCallbackError('missing_pending', 'No pending authorization for this callback');
+    }
+    if (str(q.state) !== pending.state) {
+        throw new OidcCallbackError('state_mismatch', 'Callback state does not match');
+    }
+    const iss = str(q.iss);
+    if (iss !== undefined && iss !== issuer) {
+        throw new OidcCallbackError('issuer_mismatch', `Callback iss ${iss} is not ${issuer}`);
+    }
+    const idpError = str(q.error);
+    if (idpError) {
+        const description = str(q.error_description);
+        throw new OidcCallbackError('idp_error', `IdP returned ${idpError}${description ? `: ${description}` : ''}`, { idpError: { error: idpError, description } });
+    }
+    const code = str(q.code);
+    if (!code)
+        throw new OidcCallbackError('missing_code', 'Callback has no code');
+    let tokens;
+    try {
+        tokens = await exchangeCode({
+            issuer: p.issuer,
+            clientId: p.clientId,
+            clientSecret: p.clientSecret,
+            redirectUri: p.redirectUri,
+            code,
+            codeVerifier: pending.codeVerifier,
+            tokenEndpoint,
+            fetchImpl: p.fetchImpl,
+            resilience: p.resilience,
+        });
+    }
+    catch (error) {
+        throw new OidcCallbackError('token_exchange_failed', error.message, {
+            cause: error,
+        });
+    }
+    if (!tokens.idToken) {
+        throw new OidcCallbackError('missing_id_token', 'Token endpoint returned no id_token — is "openid" in the scopes?');
+    }
+    let claims;
+    try {
+        claims = await validateIdToken(tokens.idToken, {
+            ...p.idToken,
+            issuer,
+            clientId: p.clientId,
+            jwksUri,
+            nonce: pending.nonce,
+            maxAge: pending.maxAge,
+        });
+    }
+    catch (error) {
+        const message = error instanceof InvalidIdTokenError ? error.message : String(error);
+        throw new OidcCallbackError('invalid_id_token', message, { cause: error });
+    }
+    return { tokens, claims };
+}

package/build/src/backchannel_logout.d.ts

@@ -16,7 +16,7 @@ export interface ValidateLogoutTokenOptions {
      */
     jwksUri?: string;
     /**
-     * Função de chave já resolvida (ex.: `createRemoteJWKSet` ou `createLocalJWKSet`).
+     * Função de chave já resolvida (ex.: `createLocalJWKSet`).
      * Tem precedência sobre `jwksUri`; útil em testes para injetar uma chave local.
      */
     keys?: JWTVerifyGetKey;

package/build/src/backchannel_logout.js

@@ -1,19 +1,7 @@
-import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { jwtVerify } from 'jose';
+import { DEFAULT_ALGS, getJwks } from './jwks.js';
 /** Event type da claim `events` exigido pelo OIDC Back-Channel Logout. */
 export const BACKCHANNEL_LOGOUT_EVENT = 'http://schemas.openid.net/event/backchannel-logout';
-/** Algoritmos de assinatura aceitos no logout_token (defesa contra alg-confusion). */
-const DEFAULT_ALGS = [
-    'RS256',
-    'RS384',
-    'RS512',
-    'PS256',
-    'PS384',
-    'PS512',
-    'ES256',
-    'ES384',
-    'ES512',
-    'EdDSA',
-];
 /** Erro tipado lançado quando o logout_token não satisfaz as regras do spec. */
 export class InvalidLogoutTokenError extends Error {
     constructor(message) {
@@ -34,7 +22,7 @@ export class InvalidLogoutTokenError extends Error {
  * Lança {@link InvalidLogoutTokenError} em qualquer violação.
  */
 export async function validateLogoutToken(token, opts) {
-    const keys = opts.keys ?? createRemoteJWKSet(new URL(opts.jwksUri ?? `${opts.issuer}/jwks`));
+    const keys = opts.keys ?? getJwks(opts.jwksUri ?? `${opts.issuer}/jwks`);
     let payload;
     try {
         const verified = await jwtVerify(token, keys, {

package/build/src/define_config.d.ts

@@ -1,5 +1,6 @@
 import type { Identity } from '@adonis-agora/authkit-core';
 import type { SessionIndex } from './backchannel_logout.js';
+import type { OidcEndpoints } from './discovery.js';
 import type { ResiliencePolicy } from './http/resilient_fetch.js';
 import { type ResolverFactory, resolvers } from './resolvers/factory.js';
 import type { RevocationStore } from './revocation/revocation_store.js';
@@ -55,6 +56,23 @@ export interface ClientConfigInput {
      * estruturalmente — o authkit-client não importa o pacote de resiliência.
      */
     resilience?: ResiliencePolicy;
+    /**
+     * Resolve the IdP endpoints from `{issuer}/.well-known/openid-configuration`.
+     * Default: `true` — works with authkit-server and any third-party IdP
+     * (Keycloak, Auth0, Okta, Entra…).
+     *
+     * Discovery runs lazily, on first use, so the app boots while the IdP is down.
+     * A failure throws `OidcDiscoveryError` and is retried on the next request; a
+     * previously discovered document keeps being served while refetches fail.
+     *
+     * `false` skips the network and uses `endpoints` on top of the authkit-server
+     * convention (`/auth`, `/token`, `/jwks`, `/session/end`).
+     */
+    discovery?: boolean | {
+        cacheTtlMs?: number;
+    };
+    /** Per-field endpoint overrides; always win over discovery. */
+    endpoints?: Partial<OidcEndpoints>;
 }
 export interface ResolvedClientConfig {
     issuer: string;
@@ -74,5 +92,11 @@ export interface ResolvedClientConfig {
     backchannelStore?: RevocationStore;
     /** Política de resiliência opcional p/ chamadas HTTP de saída ao IdP. Ver {@link ClientConfigInput.resilience}. */
     resilience?: ResiliencePolicy;
+    /** `false` when discovery is off; otherwise its options. See {@link ClientConfigInput.discovery}. */
+    discovery: false | {
+        cacheTtlMs?: number;
+    };
+    /** Endpoint overrides. See {@link ClientConfigInput.endpoints}. */
+    endpoints?: Partial<OidcEndpoints>;
 }
 export declare function defineConfig(config: ClientConfigInput): import("@adonisjs/core/types").ConfigProvider<ResolvedClientConfig>;

package/build/src/define_config.js

@@ -29,6 +29,12 @@ export function defineConfig(config) {
             sessionIndex: config.sessionIndex,
             backchannelStore: store,
             resilience: config.resilience,
+            discovery: config.discovery === false
+                ? false
+                : typeof config.discovery === 'object'
+                    ? config.discovery
+                    : {},
+            endpoints: config.endpoints,
         };
     });
 }

package/build/src/discovery.d.ts

@@ -1,23 +1,28 @@
 /**
  * OIDC Discovery (RFC 8414 / OpenID Connect Discovery 1.0).
  *
- * Os helpers de fluxo deste pacote historicamente assumiam as rotas do
- * oidc-provider (`/auth`, `/token`, `/jwks`…) — convenção do authkit-server.
- * IdPs de terceiros (Keycloak, Auth0, Okta, Entra…) usam caminhos próprios,
- * publicados em `{issuer}/.well-known/openid-configuration`.
+ * The flow helpers in this package historically assumed oidc-provider's routes
+ * (`/auth`, `/token`, `/jwks`…) — the authkit-server convention. Third-party IdPs
+ * (Keycloak, Auth0, Okta, Entra…) use their own paths, published at
+ * `{issuer}/.well-known/openid-configuration`.
  *
- * `discoverEndpoints()` resolve os endpoints reais do IdP (com cache por
- * issuer) e cai na convenção do oidc-provider quando o documento não está
- * disponível — então authkit-server continua funcionando offline/sem rede.
+ * `discoverEndpoints()` resolves the IdP's real endpoints (cached per issuer).
  *
  * ```ts
- * const endpoints = await discoverEndpoints(issuer)
+ * const endpoints = await discoverEndpoints(issuer, { onError: 'throw' })
  * const url = buildAuthorizeUrl({ issuer, authorizationEndpoint: endpoints.authorizationEndpoint, ... })
  * const tokens = await exchangeCode({ issuer, tokenEndpoint: endpoints.tokenEndpoint, ... })
  * ```
  */
 import { type ResiliencePolicy } from './http/resilient_fetch.js';
 export interface OidcEndpoints {
+    /**
+     * The issuer tokens are checked against (`iss`). From a discovery document it
+     * is the document's exact value, so an IdP whose issuer carries a trailing
+     * slash (Auth0: `https://tenant.auth0.com/`) validates no matter how the issuer
+     * was written in the config; otherwise it is the configured issuer.
+     */
+    issuer: string;
     authorizationEndpoint: string;
     tokenEndpoint: string;
     jwksUri: string;
@@ -26,30 +31,57 @@ export interface OidcEndpoints {
     introspectionEndpoint?: string;
 }
 /**
- * Convenção do oidc-provider (authkit-server) — usada como fallback quando o
- * documento de discovery não está acessível.
+ * The oidc-provider (authkit-server) convention — used when discovery is off, and
+ * as the per-field fallback of `onError: 'fallback'`.
  */
 export declare function conventionEndpoints(issuer: string): OidcEndpoints;
+/**
+ * Layers endpoint sources, later ones winning field by field. `undefined` never
+ * overwrites, so a layer only contributes what it actually has.
+ */
+export declare function mergeEndpoints<T extends Partial<OidcEndpoints>>(base: T, ...layers: Array<Partial<OidcEndpoints> | undefined>): T;
+/** Thrown by `discoverEndpoints(..., { onError: 'throw' })` when discovery fails. */
+export declare class OidcDiscoveryError extends Error {
+    readonly issuer: string;
+    readonly url: string;
+    constructor(message: string, issuer: string, url: string, options?: {
+        cause?: unknown;
+    });
+}
 export interface DiscoverOptions {
-    /** Overrides manuais — precedem o documento de discovery, campo a campo. */
+    /** Manual overrides — win over the discovery document, field by field. */
     overrides?: Partial<OidcEndpoints>;
-    /** TTL do cache por issuer. Default: 15 min. */
+    /** Per-issuer cache TTL. Default: 15 min. */
     cacheTtlMs?: number;
     fetchImpl?: typeof fetch;
     /**
-     * Política de resiliência OPCIONAL p/ a chamada de discovery. Sem ela, é um
-     * `fetch` puro (nenhuma mudança de comportamento).
+     * OPTIONAL resilience policy for the discovery call. Without it, it is a plain
+     * `fetch` (no behaviour change).
      */
     resilience?: ResiliencePolicy;
+    /**
+     * What to do when the document cannot be used (network error, non-2xx, invalid
+     * JSON, `issuer` mismatch, missing required endpoint):
+     *
+     * - `'fallback'` (default, back-compat): fall back to the authkit-server
+     *   convention. Fields missing from a valid document also fall back.
+     * - `'throw'`: throw {@link OidcDiscoveryError}. Optional fields missing from
+     *   the document stay `undefined` instead of being guessed.
+     *
+     * Either way a failure is never cached — the next call retries — and a
+     * previously discovered document keeps being served while refetches fail.
+     */
+    onError?: 'fallback' | 'throw';
 }
 /**
- * Resolve os endpoints do IdP via `/.well-known/openid-configuration`.
+ * Resolves the IdP endpoints via `/.well-known/openid-configuration`.
  *
- * - Resultado cacheado por issuer (TTL 15 min) — seguro de chamar por request.
- * - Falha de rede/404 → fallback silencioso para a convenção do oidc-provider
- *   (o cache também guarda o fallback, evitando refetch em loop).
- * - `overrides` sempre vencem, campo a campo.
+ * - Successful documents are cached per issuer (TTL 15 min) — safe to call per request.
+ * - The document's `issuer` must match the configured one (OIDC Discovery §4.3;
+ *   a trailing-slash difference is tolerated and the document's exact value is
+ *   returned in `issuer`).
+ * - `overrides` always win, field by field.
  */
 export declare function discoverEndpoints(issuer: string, options?: DiscoverOptions): Promise<OidcEndpoints>;
-/** Limpa o cache de discovery (testes). */
+/** Clears the discovery cache (tests). */
 export declare function __clearDiscoveryCacheForTests(): void;

package/build/src/discovery.js

@@ -1,29 +1,28 @@
 /**
  * OIDC Discovery (RFC 8414 / OpenID Connect Discovery 1.0).
  *
- * Os helpers de fluxo deste pacote historicamente assumiam as rotas do
- * oidc-provider (`/auth`, `/token`, `/jwks`…) — convenção do authkit-server.
- * IdPs de terceiros (Keycloak, Auth0, Okta, Entra…) usam caminhos próprios,
- * publicados em `{issuer}/.well-known/openid-configuration`.
+ * The flow helpers in this package historically assumed oidc-provider's routes
+ * (`/auth`, `/token`, `/jwks`…) — the authkit-server convention. Third-party IdPs
+ * (Keycloak, Auth0, Okta, Entra…) use their own paths, published at
+ * `{issuer}/.well-known/openid-configuration`.
  *
- * `discoverEndpoints()` resolve os endpoints reais do IdP (com cache por
- * issuer) e cai na convenção do oidc-provider quando o documento não está
- * disponível — então authkit-server continua funcionando offline/sem rede.
+ * `discoverEndpoints()` resolves the IdP's real endpoints (cached per issuer).
  *
  * ```ts
- * const endpoints = await discoverEndpoints(issuer)
+ * const endpoints = await discoverEndpoints(issuer, { onError: 'throw' })
  * const url = buildAuthorizeUrl({ issuer, authorizationEndpoint: endpoints.authorizationEndpoint, ... })
  * const tokens = await exchangeCode({ issuer, tokenEndpoint: endpoints.tokenEndpoint, ... })
  * ```
  */
 import { resilientFetch } from './http/resilient_fetch.js';
 /**
- * Convenção do oidc-provider (authkit-server) — usada como fallback quando o
- * documento de discovery não está acessível.
+ * The oidc-provider (authkit-server) convention — used when discovery is off, and
+ * as the per-field fallback of `onError: 'fallback'`.
  */
 export function conventionEndpoints(issuer) {
     const base = issuer.replace(/\/$/, '');
     return {
+        issuer,
         authorizationEndpoint: `${base}/auth`,
         tokenEndpoint: `${base}/token`,
         jwksUri: `${base}/jwks`,
@@ -32,59 +31,122 @@ export function conventionEndpoints(issuer) {
         introspectionEndpoint: `${base}/token/introspection`,
     };
 }
+/**
+ * Layers endpoint sources, later ones winning field by field. `undefined` never
+ * overwrites, so a layer only contributes what it actually has.
+ */
+export function mergeEndpoints(base, ...layers) {
+    const merged = { ...base };
+    for (const layer of layers) {
+        for (const [key, value] of Object.entries(layer ?? {})) {
+            if (value !== undefined)
+                merged[key] = value;
+        }
+    }
+    return merged;
+}
+/** Thrown by `discoverEndpoints(..., { onError: 'throw' })` when discovery fails. */
+export class OidcDiscoveryError extends Error {
+    issuer;
+    url;
+    constructor(message, issuer, url, options) {
+        super(message, options);
+        this.issuer = issuer;
+        this.url = url;
+        this.name = 'OidcDiscoveryError';
+    }
+}
 const DEFAULT_TTL_MS = 15 * 60_000;
 const cache = new Map();
 /**
- * Resolve os endpoints do IdP via `/.well-known/openid-configuration`.
+ * Resolves the IdP endpoints via `/.well-known/openid-configuration`.
  *
- * - Resultado cacheado por issuer (TTL 15 min) — seguro de chamar por request.
- * - Falha de rede/404 → fallback silencioso para a convenção do oidc-provider
- *   (o cache também guarda o fallback, evitando refetch em loop).
- * - `overrides` sempre vencem, campo a campo.
+ * - Successful documents are cached per issuer (TTL 15 min) — safe to call per request.
+ * - The document's `issuer` must match the configured one (OIDC Discovery §4.3;
+ *   a trailing-slash difference is tolerated and the document's exact value is
+ *   returned in `issuer`).
+ * - `overrides` always win, field by field.
  */
 export async function discoverEndpoints(issuer, options = {}) {
     const base = issuer.replace(/\/$/, '');
     const ttl = options.cacheTtlMs ?? DEFAULT_TTL_MS;
+    const onError = options.onError ?? 'fallback';
     const cached = cache.get(base);
-    let endpoints;
+    let doc;
     if (cached && Date.now() - cached.fetchedAt < ttl) {
-        endpoints = cached.endpoints;
+        doc = cached.doc;
     }
     else {
-        endpoints = await fetchDiscovery(base, options.fetchImpl ?? fetch, options.resilience);
-        cache.set(base, { endpoints, fetchedAt: Date.now() });
+        try {
+            doc = await fetchDiscovery(base, options.fetchImpl ?? fetch, options.resilience);
+            cache.set(base, { doc, fetchedAt: Date.now() });
+        }
+        catch (error) {
+            // Stale-while-error: an IdP blip must not break a client that already knows
+            // the endpoints. Nothing is written, so the next call retries.
+            if (cached)
+                doc = cached.doc;
+            else if (onError === 'throw')
+                throw error;
+        }
     }
-    if (!options.overrides)
-        return endpoints;
-    const merged = { ...endpoints };
-    for (const [key, value] of Object.entries(options.overrides)) {
-        if (value !== undefined)
-            merged[key] = value;
+    // Lowest to highest priority: the convention (fallback mode only — `throw`
+    // mode guesses nothing), what the document publishes, the overrides.
+    if (onError === 'fallback') {
+        return mergeEndpoints(conventionEndpoints(issuer), doc, options.overrides);
     }
-    return merged;
+    const endpoints = mergeEndpoints({ issuer }, doc, options.overrides);
+    assertRequired(base, endpoints);
+    return endpoints;
 }
 async function fetchDiscovery(base, fetchImpl, resilience) {
-    const fallback = conventionEndpoints(base);
+    const url = `${base}/.well-known/openid-configuration`;
+    const fail = (message, cause) => {
+        throw new OidcDiscoveryError(`OIDC discovery failed for ${base}: ${message}`, base, url, {
+            cause,
+        });
+    };
+    let raw;
     try {
-        const res = await resilientFetch(`${base}/.well-known/openid-configuration`, { headers: { accept: 'application/json' } }, resilience, fetchImpl);
+        const res = await resilientFetch(url, { headers: { accept: 'application/json' } }, resilience, fetchImpl);
         if (!res.ok)
-            return fallback;
-        const doc = (await res.json());
-        const str = (v) => (typeof v === 'string' && v ? v : undefined);
-        return {
-            authorizationEndpoint: str(doc.authorization_endpoint) ?? fallback.authorizationEndpoint,
-            tokenEndpoint: str(doc.token_endpoint) ?? fallback.tokenEndpoint,
-            jwksUri: str(doc.jwks_uri) ?? fallback.jwksUri,
-            endSessionEndpoint: str(doc.end_session_endpoint) ?? fallback.endSessionEndpoint,
-            userinfoEndpoint: str(doc.userinfo_endpoint) ?? fallback.userinfoEndpoint,
-            introspectionEndpoint: str(doc.introspection_endpoint) ?? fallback.introspectionEndpoint,
-        };
+            fail(`${url} returned ${res.status}`);
+        raw = (await res.json());
+    }
+    catch (error) {
+        if (error instanceof OidcDiscoveryError)
+            throw error;
+        return fail(`could not fetch ${url} (${error?.message ?? error})`, error);
     }
-    catch {
-        return fallback;
+    const str = (v) => (typeof v === 'string' && v ? v : undefined);
+    const docIssuer = str(raw?.issuer);
+    // OIDC Discovery §4.3: the document must be about the issuer we asked for —
+    // otherwise tokens from another issuer would validate against its keys.
+    if (!docIssuer || docIssuer.replace(/\/$/, '') !== base) {
+        return fail(`document issuer ${JSON.stringify(docIssuer)} does not match the configured issuer`);
+    }
+    return {
+        issuer: docIssuer,
+        authorizationEndpoint: str(raw.authorization_endpoint),
+        tokenEndpoint: str(raw.token_endpoint),
+        jwksUri: str(raw.jwks_uri),
+        endSessionEndpoint: str(raw.end_session_endpoint),
+        userinfoEndpoint: str(raw.userinfo_endpoint),
+        introspectionEndpoint: str(raw.introspection_endpoint),
+    };
+}
+/**
+ * Throws when neither the document nor the overrides provide an endpoint the
+ * login flow cannot work without. Only `onError: 'throw'` needs it — the
+ * fallback mode fills the gap with the convention, as it always did.
+ */
+function assertRequired(base, endpoints) {
+    const missing = ['authorizationEndpoint', 'tokenEndpoint', 'jwksUri'].filter((key) => !endpoints[key]);
+    if (missing.length) {
+        throw new OidcDiscoveryError(`OIDC discovery failed for ${base}: document is missing ${missing.join(', ')}`, base, `${base}/.well-known/openid-configuration`);
     }
 }
-/** Limpa o cache de discovery (testes). */
+/** Clears the discovery cache (tests). */
 export function __clearDiscoveryCacheForTests() {
     cache.clear();
 }

package/build/src/id_token.d.ts

@@ -0,0 +1,57 @@
+import { type JWTPayload, type JWTVerifyGetKey } from 'jose';
+/** Typed error thrown when an id_token does not satisfy OIDC Core §3.1.3.7. */
+export declare class InvalidIdTokenError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface ValidateIdTokenOptions {
+    /** Expected issuer — compared exactly with the `iss` claim. */
+    issuer: string;
+    /** The RP's client_id; must be in `aud` (and equal `azp` when present). */
+    clientId: string;
+    /** IdP `jwks_uri`. Default: `${issuer}/jwks` (authkit-server convention). */
+    jwksUri?: string;
+    /** Pre-resolved key function (e.g. `createLocalJWKSet` in tests). Wins over `jwksUri`. */
+    keys?: JWTVerifyGetKey;
+    /** Accepted algorithms. Default: asymmetric only. */
+    algorithms?: string[];
+    /**
+     * The nonce sent in the authorization request. When given, the token's `nonce`
+     * claim must equal it. Leave it out only where no nonce was sent (refresh).
+     */
+    nonce?: string;
+    /**
+     * The `max_age` sent in the authorization request, in seconds. When given, the
+     * token must carry `auth_time` and the authentication must be at most this old.
+     */
+    maxAge?: number;
+    /**
+     * Expected `sub`. On refresh, OIDC Core §12.2 requires the new id_token to be
+     * about the same end-user as the one it replaces.
+     */
+    subject?: string;
+    /** Clock skew tolerance in seconds. Default: 5. */
+    clockTolerance?: number;
+    /** Current time (tests). */
+    currentDate?: Date;
+}
+/** Claims of a validated id_token. `sub`, `iat` and `exp` are guaranteed. */
+export interface IdTokenClaims extends JWTPayload {
+    sub: string;
+    iat: number;
+    exp: number;
+    nonce?: string;
+    auth_time?: number;
+    sid?: string;
+    azp?: string;
+}
+/**
+ * Validates an id_token as required by OIDC Core §3.1.3.7:
+ * signature against the IdP JWKS, `iss`, `aud` ∋ clientId, `azp` (when `aud`
+ * has several entries or `azp` is present), `exp`, `iat`, and — when the caller
+ * passes them — `nonce`, `auth_time`/`max_age` and `sub`.
+ *
+ * Throws {@link InvalidIdTokenError} on any violation.
+ */
+export declare function validateIdToken(token: string, opts: ValidateIdTokenOptions): Promise<IdTokenClaims>;

package/build/src/id_token.js

@@ -0,0 +1,61 @@
+import { jwtVerify } from 'jose';
+import { DEFAULT_ALGS, getJwks } from './jwks.js';
+/** Typed error thrown when an id_token does not satisfy OIDC Core §3.1.3.7. */
+export class InvalidIdTokenError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'InvalidIdTokenError';
+    }
+}
+/**
+ * Validates an id_token as required by OIDC Core §3.1.3.7:
+ * signature against the IdP JWKS, `iss`, `aud` ∋ clientId, `azp` (when `aud`
+ * has several entries or `azp` is present), `exp`, `iat`, and — when the caller
+ * passes them — `nonce`, `auth_time`/`max_age` and `sub`.
+ *
+ * Throws {@link InvalidIdTokenError} on any violation.
+ */
+export async function validateIdToken(token, opts) {
+    const keys = opts.keys ?? getJwks(opts.jwksUri ?? `${opts.issuer.replace(/\/$/, '')}/jwks`);
+    const clockTolerance = opts.clockTolerance ?? 5;
+    let payload;
+    try {
+        const verified = await jwtVerify(token, keys, {
+            issuer: opts.issuer,
+            audience: opts.clientId,
+            algorithms: opts.algorithms ?? DEFAULT_ALGS,
+            requiredClaims: ['sub', 'iat', 'exp'],
+            clockTolerance,
+            currentDate: opts.currentDate,
+        });
+        payload = verified.payload;
+    }
+    catch (error) {
+        throw new InvalidIdTokenError(`Invalid id_token: ${error.message}`, {
+            cause: error,
+        });
+    }
+    const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+    if (aud.length > 1 && payload.azp === undefined) {
+        throw new InvalidIdTokenError('id_token has several audiences but no azp claim');
+    }
+    if (payload.azp !== undefined && payload.azp !== opts.clientId) {
+        throw new InvalidIdTokenError('id_token azp does not match the client_id');
+    }
+    if (opts.nonce !== undefined && payload.nonce !== opts.nonce) {
+        throw new InvalidIdTokenError('id_token nonce does not match the authorization request');
+    }
+    if (opts.subject !== undefined && payload.sub !== opts.subject) {
+        throw new InvalidIdTokenError('id_token sub does not match the current session');
+    }
+    if (opts.maxAge !== undefined) {
+        if (typeof payload.auth_time !== 'number') {
+            throw new InvalidIdTokenError('id_token is missing auth_time, required by max_age');
+        }
+        const now = Math.floor((opts.currentDate ?? new Date()).getTime() / 1000);
+        if (now - payload.auth_time > opts.maxAge + clockTolerance) {
+            throw new InvalidIdTokenError('id_token auth_time is older than max_age');
+        }
+    }
+    return payload;
+}