@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

package/lib/src/providers/MagicLinkAuthProvider.js

@@ -0,0 +1,333 @@
+/**
+ * MagicLinkAuthProvider — passwordless authentication via one-time email links.
+ *
+ * Registered by AuthManager when `ngdpbase.auth.magic-link.enabled` is true.
+ *
+ * Flow:
+ *   1. initiate()  — look up user by email, generate token, send link via mail transport
+ *   2. verify()    — validate token (exists + not expired), return AuthResult
+ *   3. consumeToken() — delete token; its return value gates the session (#1021)
+ *
+ * `verify()` being side-effect free is load-bearing, not incidental (#1019): the
+ * route layer calls it twice, once on the GET that renders the sign-in
+ * confirmation page and again on the POST that completes the login. Only the
+ * POST consumes. Moving consumption into verify() would reintroduce the bug
+ * where a mail scanner's link pre-fetch burns the token before the user clicks.
+ *
+ * Tokens are in-memory only — lost on restart, acceptable for the default 15-min TTL.
+ *
+ * A shared address (#2073): two or more accounts may hold one email. The link
+ * then names no account; the person opening it chooses one of the accounts on
+ * the address, and the link alone is enough for any of them (the mailbox is
+ * the shared trust, operator 2026-10-25).
+ *
+ * @see AuthManager
+ * @see BaseAuthProvider
+ */
+import * as crypto from 'crypto';
+import { jobContextFromRequestWithReason } from '../context/JobContext.js';
+import { systemPrincipalOf } from '../context/bootActions.js';
+import { deriveUsername } from '../utils/deriveUsername.js';
+import logger from '../utils/logger.js';
+import { emailDomain, errorForLog } from '../utils/emailForLog.js';
+/**
+ * What an email link gives, in either role — starting a sign-in or confirming
+ * one as a second factor (#1523: one email-link factor). Email is never
+ * phishing-resistant and never above AAL1 (SP 800-63B §5.1.3.1).
+ */
+export const EMAIL_FACTOR = { amr: ['email'], aal: 1 };
+export class MagicLinkAuthProvider {
+    engine;
+    config;
+    id = 'magic-link';
+    displayName = 'Magic Link';
+    /** Email is never phishing-resistant and never above AAL1: SP 800-63B §5.1.3.1 bars it as out-of-band (#1523). */
+    factor = { ...EMAIL_FACTOR, primary: true };
+    /** token → entry */
+    tokens;
+    /** email → timestamp of last request (rate-limit) */
+    rateLimitMap;
+    constructor(engine, config) {
+        this.engine = engine;
+        this.config = config;
+        this.tokens = new Map();
+        this.rateLimitMap = new Map();
+    }
+    /**
+     * Initiate the magic-link flow: look up the user, generate a token, send the email.
+     * Silently succeeds if the email is not registered — prevents user enumeration.
+     */
+    async initiate(context) {
+        try {
+            const email = context.email?.trim().toLowerCase();
+            if (!email)
+                return;
+            // Rate limit: 1 request per email per 60 seconds
+            if (this.isRateLimited(email)) {
+                logger.debug(`[MagicLinkAuthProvider] Rate limited: an address at ${emailDomain(email)}`);
+                return;
+            }
+            const userManager = this.engine.getManager('UserManager');
+            if (!userManager)
+                return;
+            // #2073: an address may be shared; the accounts on it that may sign in.
+            const holders = await userManager.getUsersByEmail(email);
+            const active = holders.filter((u) => u.isActive !== false);
+            const choices = active.length > 1 ? active.map((u) => u.username) : undefined;
+            const user = choices ? undefined : holders.length === 1 ? holders[0] : active[0];
+            if (!user && !choices && (holders.length > 0 || !this.isAutoProvisionEnabled())) {
+                // Silent — do not reveal whether email is registered
+                logger.debug(`[MagicLinkAuthProvider] No user for an address at ${emailDomain(email)} (silent)`);
+                return;
+            }
+            // #1026: with auto-provision on, an unknown email still gets a link — but
+            // the account is NOT created here. It is created when the link is
+            // verified, so an address nobody controls never becomes an account and a
+            // spray of requests at other people's addresses leaves nothing behind.
+            // The caller-visible response is identical either way, which is what
+            // keeps the anti-enumeration property intact.
+            const isNewUser = !user && !choices;
+            const username = choices
+                ? ''
+                : user
+                    ? user.username
+                    : await deriveUsername(email, userManager);
+            const token = crypto.randomBytes(32).toString('hex');
+            const expiresAt = Date.now() + this.config.ttlMs;
+            this.tokens.set(token, {
+                username,
+                email,
+                ...(choices ? { choices } : {}),
+                redirect: context.redirect || '/',
+                expiresAt,
+                isNewUser,
+                // #1022: undefined when the caller did not supply one, which reads as
+                // 'unknown' at redemption rather than as a mismatch.
+                deviceState: context.deviceState
+            });
+            this.rateLimitMap.set(email, Date.now());
+            // #642 Iteration 3: derive baseUrl from canonical config at runtime.
+            // AuthManager.initialize() already refused to register this provider
+            // unless ngdpbase.application.base-url is explicit, so getBaseURL()
+            // here always returns the operator-configured value.
+            const configManager = this.engine.getManager('ConfigurationManager');
+            const baseUrl = (configManager?.getBaseURL() ?? '').replace(/\/$/, '');
+            const verifyUrl = `${baseUrl}/auth/magic-link/verify?token=${token}`;
+            const ttlMinutes = Math.round(this.config.ttlMs / 60_000);
+            // #1916: a failed send is reported once, by EmailManager (the mail
+            // provider here); logging its error again would repeat it.
+            const sent = await this.config.mailProvider.send({
+                to: email,
+                subject: 'Your login link',
+                text: [
+                    'Click the link below to log in.',
+                    '',
+                    verifyUrl,
+                    '',
+                    `This link expires in ${ttlMinutes} minutes and can only be used once.`,
+                    '',
+                    'If you did not request this link, you can ignore this email.'
+                ].join('\n'),
+                html: [
+                    '<p>Click the link below to log in.</p>',
+                    `<p><a href="${verifyUrl}">${verifyUrl}</a></p>`,
+                    `<p>This link expires in ${ttlMinutes} minutes and can only be used once.</p>`,
+                    '<p>If you did not request this link, you can ignore this email.</p>'
+                ].join('\n')
+            }).then(() => true, () => false);
+            if (!sent)
+                return;
+            this.cleanupExpired();
+            logger.info(`[MagicLinkAuthProvider] Link sent to an address at ${emailDomain(email)} ` +
+                (choices ? `for ${choices.length} accounts sharing it (the person chooses one)` : user ? `for user ${user.username}` : '(new account — provisioned on verify)'));
+        }
+        catch (err) {
+            logger.error(`[MagicLinkAuthProvider] Error in initiate: ${errorForLog(err)}`);
+        }
+    }
+    /**
+     * Verify a token. Returns AuthResult on success, null if invalid or expired.
+     * Does NOT consume the token — call consumeToken() after the session is created.
+     */
+    async verify(credentials) {
+        const { token } = credentials;
+        if (!token)
+            return null;
+        const entry = this.liveEntry(token);
+        if (!entry)
+            return null;
+        if (!entry.choices)
+            return { username: entry.username };
+        // #2073: a shared address — the account chosen must be one the link offered, still hold the address, and still be on.
+        const account = credentials.account;
+        if (!account || !entry.choices.includes(account))
+            return null;
+        const holders = await this.engine.getManager('UserManager')?.getUsersByEmail(entry.email) ?? [];
+        return holders.some((u) => u.username === account && u.isActive !== false) ? { username: account } : null;
+    }
+    /**
+     * The accounts a link to a shared address offers (#2073), by username, or
+     * null for a link to one account (or an unknown or expired one). Read
+     * without consuming, so the page asking which account can be shown.
+     */
+    accountChoices(token) {
+        return this.liveEntry(token)?.choices ?? null;
+    }
+    liveEntry(token) {
+        const entry = this.tokens.get(token);
+        if (!entry)
+            return null;
+        if (Date.now() > entry.expiresAt) {
+            this.tokens.delete(token);
+            return null;
+        }
+        return entry;
+    }
+    /**
+     * Delete the token and report whether THIS caller was the one that did.
+     *
+     * #1021: the return value is the single-use gate, not a courtesy. The route
+     * used to verify, then consume, with an `await` between the two — so two
+     * POSTs carrying the same token (a double-clicked confirmation button, a
+     * client retry, a prefetch racing the real submit) could both clear
+     * verification before either consumed, and both would then establish a
+     * session. #1019's CSRF-protected POST does not close that: both submits
+     * come from the same session with the same valid token.
+     *
+     * `Map.delete` returns true only for the call that found an entry, and it is
+     * synchronous so it cannot interleave. Exactly one caller can ever see true,
+     * which makes consumption — not verification — the thing a session is gated
+     * on.
+     */
+    consumeToken(token) {
+        return this.tokens.delete(token);
+    }
+    /**
+     * The requesting browser's state value for this token (#1022), or null.
+     *
+     * Must be read BEFORE consumeToken(), which deletes the entry — same
+     * constraint as getFlowRedirect below, and for the same reason.
+     */
+    getDeviceState(token) {
+        return this.tokens.get(token)?.deviceState ?? null;
+    }
+    /**
+     * Where the user was headed before the link was issued (#1049).
+     *
+     * Named for the capability rather than the mechanism: GoogleOIDCProvider
+     * answers the same question keyed by a state nonce, and the two used to be
+     * `getTokenRedirect` / `getStateRedirect`, which is why AuthManager needed a
+     * method per provider to ask it.
+     *
+     * Must be read BEFORE consumeToken(), which deletes the entry.
+     */
+    getFlowRedirect(token) {
+        return this.tokens.get(token)?.redirect || '/';
+    }
+    /**
+     * Create the account behind a new-user token (#1026).
+     *
+     * Called from the POST that completes sign-in, never from the GET — so a mail
+     * scanner pre-fetching the link cannot bring an account into existence, for
+     * the same reason it cannot consume the token (#1019).
+     *
+     * The account is created with `isExternal: true`, which stores an empty
+     * password hash. `UserManager.verifyPassword` refuses an empty stored hash
+     * outright (#1042), so these accounts cannot be logged into with a password
+     * by any input — magic link is structurally their only way in.
+     *
+     * Idempotent: a token whose account already exists is a no-op, so a double
+     * submit cannot fail the second time.
+     *
+     * @returns true if the token is usable (existing user, or newly created)
+     */
+    async provisionIfNew(token) {
+        const entry = this.tokens.get(token);
+        if (!entry)
+            return false;
+        if (!entry.isNewUser)
+            return true;
+        const userManager = this.engine.getManager('UserManager');
+        if (!userManager)
+            return false;
+        // Re-check: the name was derived when the link was requested and something
+        // else may have claimed it since. #2073: accounts made for the address
+        // meanwhile are not guessed between; the link is refused instead.
+        const existing = await userManager.getUsersByEmail(entry.email);
+        if (existing.length > 1)
+            return false;
+        if (existing.length === 1) {
+            entry.username = existing[0].username;
+            entry.isNewUser = false;
+            return true;
+        }
+        const username = await deriveUsername(entry.email, userManager);
+        const role = this.resolveDefaultRole();
+        let created;
+        try {
+            created = await userManager.createUser({
+                username,
+                email: entry.email,
+                displayName: username,
+                password: '',
+                roles: [role],
+                isExternal: true,
+                isActive: true
+            }, jobContextFromRequestWithReason({ username: systemPrincipalOf(this.engine) }, 'provisioned by magic-link')); // #1204: provisioned, not registered; #1179: the system principal acts, the reason names the provider
+        }
+        catch (err) {
+            logger.error(`[MagicLinkAuthProvider] Failed to provision an account for an address at ${emailDomain(entry.email)}: ${errorForLog(err)}`);
+            return false;
+        }
+        entry.username = created.username; // #1882: the account as stored
+        entry.isNewUser = false;
+        logger.info(`[MagicLinkAuthProvider] Provisioned new user: ${username} (an address at ${emailDomain(entry.email)}) role=${role}`);
+        return true;
+    }
+    /** Whether an unknown email may create an account by verifying a link (#1026). */
+    isAutoProvisionEnabled() {
+        const configManager = this.engine.getManager('ConfigurationManager');
+        // `ngdpbase.application.registration` is the master override — when self-
+        // registration is off, no path may create an account, exactly as
+        // GoogleOIDCProvider treats it. The provider toggle sits below it.
+        const allowReg = configManager?.getProperty?.('ngdpbase.application.registration', true) ?? true;
+        if (!allowReg)
+            return false;
+        return configManager?.getProperty?.('ngdpbase.auth.magic-link.auto-provision', false) ?? false;
+    }
+    /**
+     * Role for auto-provisioned users. An unknown role name falls back to
+     * `reader` with a warning — a typo should degrade to read-only, not throw
+     * mid-signup or silently mint a more privileged account than intended.
+     */
+    resolveDefaultRole() {
+        const configManager = this.engine.getManager('ConfigurationManager');
+        const configured = configManager?.getProperty?.('ngdpbase.auth.magic-link.registration.default-role', 'reader') ?? 'reader';
+        if (configured === 'reader')
+            return 'reader';
+        const declared = configManager?.getProperty?.('ngdpbase.roles.definitions', {});
+        if (!Object.hasOwn(declared ?? {}, configured)) {
+            logger.warn(`[MagicLinkAuthProvider] Unknown role "${configured}" in ` +
+                'ngdpbase.auth.magic-link.registration.default-role — falling back to "reader"');
+            return 'reader';
+        }
+        return configured;
+    }
+    isRateLimited(email) {
+        const last = this.rateLimitMap.get(email);
+        if (!last)
+            return false;
+        return Date.now() - last < 60_000;
+    }
+    cleanupExpired() {
+        const now = Date.now();
+        for (const [token, entry] of this.tokens) {
+            if (now > entry.expiresAt)
+                this.tokens.delete(token);
+        }
+    }
+    /** Exposed for testing */
+    getTokenCount() {
+        return this.tokens.size;
+    }
+}

package/lib/src/providers/OidcAuthProvider.js

@@ -0,0 +1,350 @@
+/**
+ * OidcAuthProvider — signing in through an outside OpenID Connect provider (#1743).
+ *
+ * One class, one registered instance per configured issuer (`oidc:<name>`),
+ * registered by AuthManager from `ngdpbase.auth.oidc.providers` (and the old
+ * `ngdpbase.auth.google-oidc.*` keys, read as the `google` entry). Routes never
+ * call it: AuthManager is the one door.
+ *
+ * What an outside sign-in may do (decided 2026-10-10, docs/planning/authentication.md):
+ * - The identity is the issuer plus the subject (`iss` + `sub`, OIDC Core §5.7),
+ *   stored as a credentials-store row of kind `identity`. Only an identity
+ *   already connected to an account signs anyone in. Email never matches or
+ *   signs anyone in here.
+ * - It gives no roles: a provider's groups and roles claims are never read.
+ * - No access or refresh token is kept; nothing needs them.
+ *
+ * Each flow is protected as `GoogleOIDCProvider` was (#1630): a single-use
+ * `state` bound to the starting browser by an HTTP-only cookie, PKCE (S256),
+ * an OIDC `nonce`, and the ID token's signature, issuer, audience and expiry.
+ *
+ * Apple (slice 4b) differs in two ways handled here: its client secret is a
+ * JWT signed per exchange (`SignedClientSecret`), and it POSTs the callback
+ * (`responseMode: 'form_post'`), which `middleware/outsideCallbackRelay.ts`
+ * turns into the usual GET before the session and CSRF see it.
+ *
+ * Discovery (`/.well-known/openid-configuration`) and the issuer's keys are
+ * fetched through `guardedFetch`, like every outbound request (#1133), and
+ * cached. Flow state is in memory: a restart drops a sign-in in progress.
+ *
+ * @see AuthManager
+ * @see BaseAuthProvider
+ */
+import * as crypto from 'crypto';
+import { createLocalJWKSet, jwtVerify, SignJWT, errors as joseErrors } from 'jose';
+import { guardedFetch } from '../http/guardedFetch.js';
+import { evaluateDeviceBinding } from '../utils/magicLinkDeviceState.js';
+import logger from '../utils/logger.js';
+const FLOW_TTL_MS = 10 * 60_000;
+const CACHE_TTL_MS = 60 * 60_000;
+const MAX_DOC_BYTES = 512 * 1024;
+const FETCH_TIMEOUT_MS = 10_000;
+/** How long a signed client secret is valid; Apple allows up to six months, a code exchange needs seconds. */
+const SIGNED_SECRET_TTL_S = 5 * 60;
+/** Google's ID tokens may name their issuer without the scheme (Google's OIDC documentation). */
+const ISSUER_ALIASES = {
+    'https://accounts.google.com': ['accounts.google.com']
+};
+export class OidcAuthProvider {
+    config;
+    identities;
+    id;
+    displayName;
+    icon;
+    /**
+     * AAL1 with no `amr`: what is offered, and what a sign-in counts for unless
+     * the admin trusts this provider's own second factor (`trust-mfa`, #1633),
+     * when AuthManager maps the reported `amr` / `acr` instead
+     * (`outsideLevel`). Primary: it starts a sign-in on its own.
+     */
+    factor = { amr: [], aal: 1, primary: true };
+    flows = new Map();
+    discovery = null;
+    keys = null;
+    constructor(config, identities) {
+        this.config = config;
+        this.identities = identities;
+        this.id = `oidc:${config.name}`;
+        this.displayName = config.displayName;
+        this.icon = config.icon;
+    }
+    /** The configured issuer; an identity row's subject starts with it and `#`. */
+    get issuer() {
+        return this.config.issuer;
+    }
+    /** The entry's name, as in its URLs. */
+    get name() {
+        return this.config.name;
+    }
+    /** Whether the issuer POSTs the callback (`response_mode=form_post`) instead of redirecting to it. */
+    get callbackIsPosted() {
+        return this.config.responseMode === 'form_post';
+    }
+    /**
+     * Begin a sign-in, or a connection when `connectFor` names the signed-in
+     * account: keep the flow's state and return the provider's authorization URL.
+     */
+    async startFlow({ redirect = '/', deviceState, connectFor } = {}) {
+        const doc = await this.discover();
+        const state = crypto.randomBytes(16).toString('hex');
+        const codeVerifier = crypto.randomBytes(32).toString('base64url');
+        const oidcNonce = crypto.randomBytes(16).toString('hex');
+        this.sweep();
+        this.flows.set(state, {
+            redirect,
+            expiresAt: Date.now() + FLOW_TTL_MS,
+            deviceState,
+            codeVerifier,
+            oidcNonce,
+            ...(connectFor ? { connectFor } : {})
+        });
+        const url = new URL(doc.authorization_endpoint);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('client_id', this.config.clientId);
+        url.searchParams.set('redirect_uri', this.config.redirectUri);
+        url.searchParams.set('scope', 'openid email');
+        url.searchParams.set('state', state);
+        url.searchParams.set('nonce', oidcNonce);
+        url.searchParams.set('code_challenge', crypto.createHash('sha256').update(codeVerifier).digest('base64url'));
+        url.searchParams.set('code_challenge_method', 'S256');
+        if (this.config.responseMode)
+            url.searchParams.set('response_mode', this.config.responseMode);
+        return url.toString();
+    }
+    /** Where the person was headed when the flow began; read before `consumeToken`. */
+    getFlowRedirect(state) {
+        return this.flows.get(state)?.redirect ?? '/';
+    }
+    /** The account this flow is connecting an identity to, or null for a sign-in or an unknown flow. */
+    getFlowConnectFor(state) {
+        return this.flows.get(state)?.connectFor ?? null;
+    }
+    /**
+     * Finish a sign-in: the account whose connected identity this is, or null.
+     * A flow started to connect never signs in. An identity connected to no
+     * account is refused, and kept on the flow until it is consumed, so
+     * AuthManager can decide what happens next (`unconnectedIdentity`);
+     * nothing here says whether an account exists.
+     */
+    async verify(credentials) {
+        const identity = await this.redeem(credentials, null);
+        if (!identity)
+            return null;
+        const row = this.identities.find(identity.subject);
+        if (!row) {
+            logger.info(`[OidcAuthProvider:${this.config.name}] an identity connected to no account was refused`);
+            const flow = credentials.state ? this.flows.get(credentials.state) : undefined;
+            if (flow)
+                flow.unconnected = identity;
+            return null;
+        }
+        try {
+            await this.identities.used(row.id, new Date().toISOString(), identity.email);
+        }
+        catch (err) {
+            logger.warn(`[OidcAuthProvider:${this.config.name}] could not record the sign-in on the connection:`, err);
+        }
+        return { username: row.username, reported: identity.reported };
+    }
+    /**
+     * Finish a connection for `username`: the identity the provider vouched
+     * for, or null. Only a flow started to connect that same account counts.
+     */
+    async verifyIdentity(credentials, username) {
+        return this.redeem(credentials, username);
+    }
+    /**
+     * The verified identity a refused sign-in brought that no account has
+     * connected, or null; read before `consumeToken` (#1743 slice 3).
+     */
+    unconnectedIdentity(state) {
+        return this.flows.get(state)?.unconnected ?? null;
+    }
+    /** Spend the flow's state; true only for the caller that did (#1021). */
+    consumeToken(state) {
+        return this.flows.delete(state);
+    }
+    /**
+     * The state, the browser, the code exchange and the ID token, checked in
+     * that order. `connectFor` is the account a connection is for, or null for
+     * a sign-in; a flow of the other kind is refused.
+     */
+    async redeem(credentials, connectFor) {
+        const code = credentials.token;
+        const state = credentials.state;
+        const tag = `[OidcAuthProvider:${this.config.name}]`;
+        if (!code || !state)
+            return null;
+        const flow = this.flows.get(state);
+        if (!flow) {
+            logger.warn(`${tag} unknown or used state`);
+            return null;
+        }
+        if (Date.now() > flow.expiresAt) {
+            this.flows.delete(state);
+            logger.warn(`${tag} the sign-in took too long; its state expired`);
+            return null;
+        }
+        // #1630: the callback must come back to the browser that started the
+        // flow, or an attacker's own code and state could finish in a victim's
+        // browser (login CSRF). Always enforced: there is no cross-device case.
+        const binding = evaluateDeviceBinding({ stored: flow.deviceState, presented: credentials.deviceState, enforce: true });
+        if (!binding.allowed) {
+            this.flows.delete(state);
+            logger.warn(`${tag} callback from a different browser than the one that started (${binding.outcome})`);
+            return null;
+        }
+        if ((flow.connectFor ?? null) !== connectFor) {
+            logger.warn(`${tag} the flow was started for ${flow.connectFor ? 'a connection' : 'a sign-in'}, not this`);
+            return null;
+        }
+        let idToken;
+        try {
+            idToken = await this.exchange(code, flow.codeVerifier);
+        }
+        catch (err) {
+            logger.warn(`${tag} the code exchange failed: ${err.message}`);
+            return null;
+        }
+        let claims;
+        try {
+            claims = await this.verifyIdToken(idToken);
+        }
+        catch (err) {
+            logger.warn(`${tag} the ID token was refused: ${err.message}`);
+            return null;
+        }
+        if (claims.nonce !== flow.oidcNonce) {
+            logger.warn(`${tag} the ID token answers another sign-in (nonce)`);
+            return null;
+        }
+        if (Array.isArray(claims.aud) && claims.aud.length > 1 && claims.azp !== this.config.clientId) {
+            logger.warn(`${tag} the ID token was issued to another party (azp)`);
+            return null;
+        }
+        if (typeof claims.sub !== 'string' || claims.sub === '') {
+            logger.warn(`${tag} the ID token names no subject`);
+            return null;
+        }
+        // Only a verified address is kept; it never identifies anyone here. Apple
+        // may send the flag as a string; elsewhere only the boolean counts.
+        const verified = claims.email_verified === true || (this.config.emailVerifiedMayBeString === true && claims.email_verified === 'true');
+        const email = verified && typeof claims.email === 'string' ? claims.email.trim().toLowerCase() : '';
+        // #1633: how the provider says it signed the person in, passed on unread.
+        return { subject: `${this.config.issuer}#${claims.sub}`, email, reported: { amr: claims.amr, acr: claims.acr } };
+    }
+    /** Exchange the code for the ID token. No access or refresh token is kept. */
+    async exchange(code, codeVerifier) {
+        const doc = await this.discover();
+        const form = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: this.config.redirectUri,
+            code_verifier: codeVerifier
+        });
+        const headers = {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'application/json'
+        };
+        // RFC 6749 §2.3.1: Basic unless the issuer says it takes only the form;
+        // OIDC Discovery: an absent list means client_secret_basic.
+        const methods = doc.token_endpoint_auth_methods_supported;
+        const clientSecret = await this.clientSecret();
+        if (methods && !methods.includes('client_secret_basic') && methods.includes('client_secret_post')) {
+            form.set('client_id', this.config.clientId);
+            form.set('client_secret', clientSecret);
+        }
+        else {
+            const pair = `${encodeURIComponent(this.config.clientId)}:${encodeURIComponent(clientSecret)}`;
+            headers.Authorization = `Basic ${Buffer.from(pair).toString('base64')}`;
+        }
+        const res = await guardedFetch(doc.token_endpoint, {
+            policy: this.config.policy,
+            method: 'POST',
+            headers,
+            body: form.toString(),
+            maxBytes: MAX_DOC_BYTES,
+            timeoutMs: FETCH_TIMEOUT_MS
+        });
+        if (res.status !== 200)
+            throw new Error(`token endpoint answered ${res.status}`);
+        const body = JSON.parse(res.body.toString('utf8'));
+        if (typeof body.id_token !== 'string')
+            throw new Error('no id_token in the token response');
+        return body.id_token;
+    }
+    /** The client secret for one code exchange: the shared one, or a freshly signed JWT (Apple). */
+    async clientSecret() {
+        const secret = this.config.clientSecret;
+        if (typeof secret === 'string')
+            return secret;
+        const now = Math.floor(Date.now() / 1000);
+        return new SignJWT({})
+            .setProtectedHeader({ alg: 'ES256', kid: secret.keyId })
+            .setIssuer(secret.teamId)
+            .setSubject(this.config.clientId)
+            .setAudience(this.config.issuer)
+            .setIssuedAt(now)
+            .setExpirationTime(now + SIGNED_SECRET_TTL_S)
+            .sign(secret.privateKey);
+    }
+    /** Signature, issuer, audience and expiry; the keys are fetched again once if none matches (rotation). */
+    async verifyIdToken(idToken) {
+        const options = {
+            issuer: [this.config.issuer, ...(ISSUER_ALIASES[this.config.issuer] ?? [])],
+            audience: this.config.clientId,
+            clockTolerance: 60
+        };
+        try {
+            return (await jwtVerify(idToken, await this.keySet(false), options)).payload;
+        }
+        catch (err) {
+            if (!(err instanceof joseErrors.JWKSNoMatchingKey))
+                throw err;
+            return (await jwtVerify(idToken, await this.keySet(true), options)).payload;
+        }
+    }
+    async keySet(refresh) {
+        if (!refresh && this.keys && Date.now() - this.keys.at < CACHE_TTL_MS)
+            return this.keys.set;
+        const doc = await this.discover();
+        const jwks = await this.getJson(doc.jwks_uri);
+        if (!jwks || !Array.isArray(jwks.keys))
+            throw new Error('the issuer\'s key set is malformed');
+        this.keys = { set: createLocalJWKSet(jwks), at: Date.now() };
+        return this.keys.set;
+    }
+    /** The issuer's discovery document, cached; its `issuer` must be the configured one (OIDC Discovery §4.3). */
+    async discover() {
+        if (this.discovery && Date.now() - this.discovery.at < CACHE_TTL_MS)
+            return this.discovery.doc;
+        const url = `${this.config.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`;
+        const doc = await this.getJson(url);
+        if (doc.issuer !== this.config.issuer) {
+            throw new Error(`the discovery document names issuer ${String(doc.issuer)}, not ${this.config.issuer}`);
+        }
+        for (const field of ['authorization_endpoint', 'token_endpoint', 'jwks_uri']) {
+            if (typeof doc[field] !== 'string')
+                throw new Error(`the discovery document has no ${field}`);
+        }
+        this.discovery = { doc: doc, at: Date.now() };
+        return this.discovery.doc;
+    }
+    async getJson(url) {
+        const res = await guardedFetch(url, {
+            policy: this.config.policy,
+            headers: { Accept: 'application/json' },
+            maxBytes: MAX_DOC_BYTES,
+            timeoutMs: FETCH_TIMEOUT_MS
+        });
+        if (res.status !== 200)
+            throw new Error(`${url} answered ${res.status}`);
+        return JSON.parse(res.body.toString('utf8'));
+    }
+    sweep() {
+        const now = Date.now();
+        for (const [state, flow] of this.flows)
+            if (now > flow.expiresAt)
+                this.flows.delete(state);
+    }
+}