@x1id/resolve 0.23.0 → 0.43.0

package/dist/oidc.js

@@ -0,0 +1,641 @@
+/**
+ * "Sign in with X1ID" — a relying-party (RP) client for the X1ID OpenID Connect
+ * provider at `https://auth.x1id.io` (services/auth, OpenProject #8842).
+ *
+ * Authorization code flow with PKCE S256, `state` and `nonce`; the ID token is
+ * verified against the provider's JWKS (signature for the algorithms discovery
+ * advertises, `iss`, `aud`, `azp`, `exp`/`iat` with a small clock skew,
+ * `nonce`), then `/me` (UserInfo) is fetched and its `sub` checked against the
+ * ID token's.
+ *
+ * Runs in browsers and in Node 20+: Web Crypto + `fetch` only, no runtime
+ * dependency, no DOM access at import time. Browser SPAs use
+ * {@link beginX1idLogin} / {@link completeX1idLogin} (pending state kept in
+ * `sessionStorage`); servers call {@link X1idOidcClient.createAuthorization}
+ * and {@link X1idOidcClient.handleCallback} and keep the pending state in their
+ * own session.
+ *
+ * What a sign-in proves: the user controlled the wallet (`sub`) at sign-in. It
+ * is NOT proof of legal identity, personhood or KYC. Key accounts on `sub`
+ * (the wallet), never on the handle — handles move.
+ */
+export const X1ID_ISSUER = "https://auth.x1id.io";
+export const X1ID_DEFAULT_SCOPE = "openid profile wallet";
+/** ID-token algorithms this client can verify (the provider's ES256 default,
+ *  EdDSA/Ed25519, and the opt-in RS256 chain). Never `none`, never HS*. */
+export const X1ID_SUPPORTED_ID_TOKEN_ALGS = ["ES256", "EdDSA", "RS256"];
+/** Default tolerance for `exp` / `iat` against the local clock, in seconds. */
+export const X1ID_DEFAULT_CLOCK_SKEW_SECS = 60;
+/** How long a pending login (state/nonce/verifier) stays usable. Matches the
+ *  provider's interaction lifetime. */
+export const X1ID_PENDING_TTL_MS = 15 * 60 * 1000;
+/** Minimum spacing between JWKS refetches triggered by an unknown `kid`. */
+const JWKS_REFETCH_MIN_MS = 30_000;
+/** Cached JWKS lifetime (the provider lets edges cache it for up to 5 min). */
+const JWKS_MAX_AGE_MS = 10 * 60 * 1000;
+export class X1idAuthError extends Error {
+    code;
+    /** The provider's `error_description`, when it sent one. */
+    description;
+    constructor(code, message, description) {
+        super(message);
+        this.name = "X1idAuthError";
+        this.code = code;
+        this.description = description;
+    }
+}
+// ---------------------------------------------------------------------------
+// Encoding helpers
+// ---------------------------------------------------------------------------
+function base64UrlEncode(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(s) {
+    if (!/^[A-Za-z0-9_-]*$/.test(s))
+        throw new Error("not base64url");
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4);
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function getCrypto(c) {
+    const cr = c ?? globalThis.crypto;
+    if (!cr?.subtle || typeof cr.getRandomValues !== "function") {
+        throw new X1idAuthError("no_crypto", "Web Crypto (crypto.subtle) is not available in this runtime");
+    }
+    return cr;
+}
+// ---------------------------------------------------------------------------
+// PKCE, state, nonce
+// ---------------------------------------------------------------------------
+/** `bytes` random bytes, base64url (32 bytes → 43 chars, 256 bits). */
+export function randomUrlSafe(bytes = 32, crypto) {
+    const buf = new Uint8Array(bytes);
+    getCrypto(crypto).getRandomValues(buf);
+    return base64UrlEncode(buf);
+}
+/** A fresh RFC 7636 code verifier: 32 random bytes → 43 base64url chars. */
+export function generateCodeVerifier(crypto) {
+    return randomUrlSafe(32, crypto);
+}
+/** RFC 7636 S256: BASE64URL(SHA-256(ASCII(verifier))). */
+export async function codeChallengeS256(verifier, crypto) {
+    if (!/^[A-Za-z0-9._~-]{43,128}$/.test(verifier)) {
+        throw new X1idAuthError("invalid_config", "code_verifier must be 43-128 unreserved characters (RFC 7636 §4.1)");
+    }
+    const digest = await getCrypto(crypto).subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+    return base64UrlEncode(new Uint8Array(digest));
+}
+// ---------------------------------------------------------------------------
+// ID-token verification (standalone, so servers can verify tokens they
+// receive from elsewhere with their own key source)
+// ---------------------------------------------------------------------------
+function fail(msg) {
+    throw new X1idAuthError("invalid_id_token", `ID token rejected: ${msg}`);
+}
+function parseJson(bytes, what) {
+    let v;
+    try {
+        v = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        fail(`${what} is not valid JSON`);
+    }
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        fail(`${what} is not a JSON object`);
+    return v;
+}
+/** Decode a JWT without verifying it (for logging / inspection only). */
+export function decodeJwtUnverified(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length !== 3)
+        fail("not a compact JWS (three parts)");
+    let h, p;
+    try {
+        h = base64UrlDecode(parts[0]);
+        p = base64UrlDecode(parts[1]);
+    }
+    catch {
+        fail("malformed base64url");
+    }
+    const header = parseJson(h, "header");
+    if (typeof header["alg"] !== "string")
+        fail("header has no alg");
+    return { header: header, payload: parseJson(p, "payload") };
+}
+/** Web Crypto parameters for a JWS alg + matching JWK, or null on mismatch. */
+function importParams(alg, jwk) {
+    if (jwk.use !== undefined && jwk.use !== "sig")
+        return null;
+    if (jwk.alg !== undefined && jwk.alg !== alg)
+        return null;
+    switch (alg) {
+        case "ES256":
+            if (jwk.kty !== "EC" || jwk.crv !== "P-256" || !jwk.x || !jwk.y)
+                return null;
+            return {
+                importAlg: { name: "ECDSA", namedCurve: "P-256" },
+                verifyAlg: { name: "ECDSA", hash: "SHA-256" },
+                publicJwk: { kty: "EC", crv: "P-256", x: jwk.x, y: jwk.y },
+            };
+        case "EdDSA":
+            if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.x)
+                return null;
+            return { importAlg: { name: "Ed25519" }, verifyAlg: { name: "Ed25519" }, publicJwk: { kty: "OKP", crv: "Ed25519", x: jwk.x } };
+        case "RS256": {
+            if (jwk.kty !== "RSA" || !jwk.n || !jwk.e)
+                return null;
+            // Refuse RSA keys under 2048 bits (the provider writes 3072).
+            let bits = 0;
+            try {
+                const n = base64UrlDecode(jwk.n);
+                let i = 0;
+                while (i < n.length && n[i] === 0)
+                    i++;
+                bits = (n.length - i) * 8;
+            }
+            catch {
+                return null;
+            }
+            if (bits < 2048)
+                return null;
+            return {
+                importAlg: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+                verifyAlg: { name: "RSASSA-PKCS1-v1_5" },
+                publicJwk: { kty: "RSA", n: jwk.n, e: jwk.e },
+            };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Verify an X1ID ID token: signature (only `algorithms`, never `none`/HS*),
+ * `iss` exact match, `aud` contains the client, `azp` (if present, or if
+ * several audiences) equals the client, `exp` in the future and `iat` not in
+ * the future (± `clockSkewSecs`), `nonce` equal to the one sent, `sub` a
+ * non-empty string. Returns the claims; throws `X1idAuthError("invalid_id_token")`.
+ */
+export async function verifyX1idIdToken(jwt, o) {
+    const crypto = getCrypto(o.crypto);
+    const { header, payload } = decodeJwtUnverified(jwt);
+    const alg = header.alg;
+    if (!X1ID_SUPPORTED_ID_TOKEN_ALGS.includes(alg) || !o.algorithms.includes(alg)) {
+        fail(`alg "${alg}" is not allowed`);
+    }
+    if (header["crit"] !== undefined)
+        fail("crit header is not supported");
+    const jwk = (await o.getKey(header));
+    if (!jwk)
+        fail(`no matching key for kid "${header.kid ?? ""}"`);
+    const params = importParams(alg, jwk);
+    if (!params)
+        fail(`key "${jwk.kid ?? ""}" does not fit alg ${alg}`);
+    const [h64, p64, s64] = jwt.split(".");
+    let sig;
+    try {
+        sig = base64UrlDecode(s64);
+    }
+    catch {
+        fail("malformed signature");
+    }
+    if (alg === "ES256" && sig.length !== 64)
+        fail("ES256 signature must be 64 bytes (r||s)");
+    if (alg === "EdDSA" && sig.length !== 64)
+        fail("Ed25519 signature must be 64 bytes");
+    let ok = false;
+    try {
+        const key = await crypto.subtle.importKey("jwk", params.publicJwk, params.importAlg, false, ["verify"]);
+        ok = await crypto.subtle.verify(params.verifyAlg, key, sig, new TextEncoder().encode(`${h64}.${p64}`));
+    }
+    catch (e) {
+        fail(`signature check failed (${e.message})`);
+    }
+    if (!ok)
+        fail("bad signature");
+    // Claims (OIDC Core §3.1.3.7).
+    const c = payload;
+    if (c["iss"] !== o.issuer)
+        fail(`iss "${String(c["iss"])}" is not "${o.issuer}"`);
+    const aud = c["aud"];
+    const auds = typeof aud === "string" ? [aud] : Array.isArray(aud) && aud.every((a) => typeof a === "string") ? aud : null;
+    if (!auds || !auds.includes(o.clientId))
+        fail("aud does not contain this client");
+    if (c["azp"] !== undefined && c["azp"] !== o.clientId)
+        fail("azp is not this client");
+    if (auds.length > 1 && c["azp"] === undefined)
+        fail("several audiences and no azp");
+    if (typeof c["sub"] !== "string" || c["sub"] === "")
+        fail("sub missing");
+    const nowS = (o.now ?? Date.now)() / 1000;
+    const skew = o.clockSkewSecs ?? X1ID_DEFAULT_CLOCK_SKEW_SECS;
+    const exp = c["exp"];
+    const iat = c["iat"];
+    if (typeof exp !== "number" || !Number.isFinite(exp))
+        fail("exp missing");
+    if (typeof iat !== "number" || !Number.isFinite(iat))
+        fail("iat missing");
+    if (nowS - skew >= exp)
+        fail("expired");
+    if (iat > nowS + skew)
+        fail("issued in the future (iat)");
+    const nbf = c["nbf"];
+    if (nbf !== undefined && (typeof nbf !== "number" || nbf > nowS + skew))
+        fail("not yet valid (nbf)");
+    if (o.nonce !== undefined) {
+        if (c["nonce"] !== o.nonce)
+            fail("nonce mismatch");
+    }
+    return c;
+}
+// ---------------------------------------------------------------------------
+// The client
+// ---------------------------------------------------------------------------
+function isLoopback(host) {
+    return host === "localhost" || host === "127.0.0.1" || host === "[::1]";
+}
+function checkUrl(u, what, code = "invalid_config") {
+    let url;
+    try {
+        url = new URL(u);
+    }
+    catch {
+        throw new X1idAuthError(code, `${what} is not an absolute URL`);
+    }
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback(url.hostname))) {
+        throw new X1idAuthError(code, `${what} must be https (http only on loopback)`);
+    }
+    return url;
+}
+function scopeString(s) {
+    const list = (typeof s === "string" ? s.split(/\s+/) : s ? [...s] : X1ID_DEFAULT_SCOPE.split(" ")).filter(Boolean);
+    if (!list.includes("openid"))
+        list.unshift("openid");
+    return [...new Set(list)].join(" ");
+}
+const RESERVED_PARAMS = new Set([
+    "client_id",
+    "redirect_uri",
+    "response_type",
+    "scope",
+    "state",
+    "nonce",
+    "code_challenge",
+    "code_challenge_method",
+    "prompt",
+    "max_age",
+    "ui_locales",
+]);
+/** Create an RP client. Nothing is fetched until first use. */
+export function createX1idOidcClient(config) {
+    if (!config.clientId)
+        throw new X1idAuthError("invalid_config", "clientId is required");
+    const issuer = (config.issuer ?? X1ID_ISSUER).replace(/\/+$/, "");
+    checkUrl(issuer, "issuer");
+    checkUrl(config.redirectUri, "redirectUri");
+    // A private-use scheme (native apps) would also be legal, but this client
+    // targets web RPs; checkUrl above enforces https / loopback http.
+    const clientId = config.clientId;
+    const redirectUri = config.redirectUri;
+    const authMethod = config.tokenEndpointAuthMethod ?? "client_secret_basic";
+    const now = config.now ?? Date.now;
+    const doFetch = config.fetch ?? ((...a) => globalThis.fetch(...a));
+    let discovery = null;
+    let jwks = null;
+    let jwksInflight = null;
+    async function getJson(url, init, code, what) {
+        let res;
+        try {
+            res = await doFetch(url, init);
+        }
+        catch (e) {
+            throw new X1idAuthError(code, `${what}: network error (${e.message})`);
+        }
+        let body = null;
+        try {
+            body = await res.json();
+        }
+        catch {
+            /* fallthrough */
+        }
+        const obj = body && typeof body === "object" && !Array.isArray(body) ? body : null;
+        if (!res.ok) {
+            const err = obj && typeof obj["error"] === "string" ? obj["error"] : code;
+            const desc = obj && typeof obj["error_description"] === "string" ? obj["error_description"] : undefined;
+            throw new X1idAuthError(err, `${what} failed (${res.status}${desc ? `: ${desc}` : ""})`, desc);
+        }
+        if (!obj)
+            throw new X1idAuthError(code, `${what}: response is not a JSON object`);
+        return obj;
+    }
+    function discover() {
+        discovery ??= (async () => {
+            const d = await getJson(`${issuer}/.well-known/openid-configuration`, { headers: { accept: "application/json" } }, "discovery_failed", "discovery");
+            // OIDC Discovery §4.3: the document's issuer MUST equal the one we asked.
+            if (d["issuer"] !== issuer)
+                throw new X1idAuthError("discovery_failed", `discovery issuer "${String(d["issuer"])}" is not "${issuer}"`);
+            for (const k of ["authorization_endpoint", "token_endpoint", "jwks_uri"]) {
+                if (typeof d[k] !== "string")
+                    throw new X1idAuthError("discovery_failed", `discovery has no ${k}`);
+                checkUrl(d[k], k, "discovery_failed");
+            }
+            const methods = d["code_challenge_methods_supported"];
+            if (Array.isArray(methods) && !methods.includes("S256"))
+                throw new X1idAuthError("discovery_failed", "provider does not support PKCE S256");
+            return d;
+        })();
+        // A failed discovery is retried on the next call rather than cached.
+        discovery.catch(() => {
+            discovery = null;
+        });
+        return discovery;
+    }
+    async function fetchJwks() {
+        jwksInflight ??= (async () => {
+            try {
+                const d = await discover();
+                const body = await getJson(d.jwks_uri, { headers: { accept: "application/json" } }, "discovery_failed", "jwks");
+                const keys = Array.isArray(body["keys"]) ? body["keys"].filter((k) => k && typeof k === "object") : [];
+                jwks = { keys, fetchedAt: now() };
+                return keys;
+            }
+            finally {
+                jwksInflight = null;
+            }
+        })();
+        return jwksInflight;
+    }
+    function pick(keys, header) {
+        const fitting = keys.filter((k) => importParams(header.alg, k) !== null);
+        if (header.kid !== undefined)
+            return fitting.find((k) => k.kid === header.kid) ?? null;
+        return fitting.length === 1 ? fitting[0] : null; // no kid: only an unambiguous key
+    }
+    async function getKey(header) {
+        // Cached JWKS, refreshed after JWKS_MAX_AGE_MS so a key the provider
+        // dropped (emergency rotation) stops verifying here too.
+        const cached = jwks && now() - jwks.fetchedAt < JWKS_MAX_AGE_MS ? jwks : null;
+        const keys = cached ? cached.keys : await fetchJwks();
+        const hit = pick(keys, header);
+        if (hit || !cached)
+            return hit;
+        // Unknown kid on a cached set: the provider may have rotated. Refetch,
+        // at most once per JWKS_REFETCH_MIN_MS (a forged kid can't hammer it).
+        if (now() - cached.fetchedAt < JWKS_REFETCH_MIN_MS)
+            return null;
+        return pick(await fetchJwks(), header);
+    }
+    async function algorithms() {
+        const d = await discover();
+        const advertised = Array.isArray(d.id_token_signing_alg_values_supported) ? d.id_token_signing_alg_values_supported : [...X1ID_SUPPORTED_ID_TOKEN_ALGS];
+        const usable = advertised.filter((a) => X1ID_SUPPORTED_ID_TOKEN_ALGS.includes(a));
+        if (config.idTokenSigningAlg) {
+            if (!usable.includes(config.idTokenSigningAlg)) {
+                throw new X1idAuthError("invalid_config", `provider does not advertise ${config.idTokenSigningAlg} ID tokens`);
+            }
+            return [config.idTokenSigningAlg];
+        }
+        return usable;
+    }
+    async function verifyIdToken(idToken, opts = {}) {
+        return verifyX1idIdToken(idToken, {
+            issuer,
+            clientId,
+            ...(opts.nonce !== undefined ? { nonce: opts.nonce } : {}),
+            algorithms: await algorithms(),
+            getKey,
+            clockSkewSecs: config.clockSkewSecs ?? X1ID_DEFAULT_CLOCK_SKEW_SECS,
+            now,
+            ...(config.crypto ? { crypto: config.crypto } : {}),
+        });
+    }
+    function clientAuth(body) {
+        const headers = { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
+        if (config.clientSecret === undefined) {
+            body.set("client_id", clientId);
+        }
+        else if (authMethod === "client_secret_post") {
+            body.set("client_id", clientId);
+            body.set("client_secret", config.clientSecret);
+        }
+        else {
+            // RFC 6749 §2.3.1: form-urlencode both parts before base64.
+            const enc = (s) => encodeURIComponent(s).replace(/%20/g, "+");
+            const raw = new TextEncoder().encode(`${enc(clientId)}:${enc(config.clientSecret)}`);
+            let bin = "";
+            raw.forEach((b) => (bin += String.fromCharCode(b)));
+            headers["authorization"] = `Basic ${btoa(bin)}`;
+        }
+        return headers;
+    }
+    function parseTokens(t) {
+        if (typeof t["access_token"] !== "string" || !t["access_token"])
+            throw new X1idAuthError("invalid_token_response", "token response has no access_token");
+        if (typeof t["token_type"] !== "string" || t["token_type"].toLowerCase() !== "bearer") {
+            throw new X1idAuthError("invalid_token_response", "token_type is not Bearer");
+        }
+        const exp = typeof t["expires_in"] === "number" ? now() + t["expires_in"] * 1000 : undefined;
+        return {
+            accessToken: t["access_token"],
+            tokenType: t["token_type"],
+            expiresAt: exp,
+            refreshToken: typeof t["refresh_token"] === "string" ? t["refresh_token"] : undefined,
+            scope: typeof t["scope"] === "string" ? t["scope"] : undefined,
+            idToken: typeof t["id_token"] === "string" ? t["id_token"] : undefined,
+        };
+    }
+    async function tokenRequest(body) {
+        const d = await discover();
+        const headers = clientAuth(body);
+        return getJson(d.token_endpoint, { method: "POST", headers, body: body.toString() }, "token_request_failed", "token request");
+    }
+    function checkPending(pending) {
+        if (pending.issuer !== issuer || pending.redirectUri !== redirectUri) {
+            throw new X1idAuthError("state_mismatch", "pending login belongs to a different issuer or redirect URI");
+        }
+        if (now() - pending.createdAt > X1ID_PENDING_TTL_MS) {
+            throw new X1idAuthError("pending_expired", "the login took too long; start again");
+        }
+    }
+    async function exchangeCode(code, pending) {
+        checkPending(pending);
+        const t = parseTokens(await tokenRequest(new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: redirectUri, code_verifier: pending.codeVerifier })));
+        if (!t.idToken)
+            throw new X1idAuthError("invalid_token_response", "token response has no id_token (is `openid` in the scope?)");
+        const idTokenClaims = await verifyIdToken(t.idToken, { nonce: pending.nonce });
+        return { ...t, idToken: t.idToken, idTokenClaims };
+    }
+    async function fetchUserInfo(accessToken, expectedSub) {
+        const d = await discover();
+        if (!d.userinfo_endpoint)
+            throw new X1idAuthError("userinfo_failed", "provider has no userinfo_endpoint");
+        checkUrl(d.userinfo_endpoint, "userinfo_endpoint", "userinfo_failed");
+        const u = await getJson(d.userinfo_endpoint, { headers: { authorization: `Bearer ${accessToken}`, accept: "application/json" } }, "userinfo_failed", "userinfo");
+        if (typeof u["sub"] !== "string")
+            throw new X1idAuthError("userinfo_failed", "userinfo has no sub");
+        if (expectedSub !== undefined && u["sub"] !== expectedSub)
+            throw new X1idAuthError("userinfo_failed", "userinfo sub does not match the ID token");
+        return u;
+    }
+    return {
+        issuer,
+        clientId,
+        redirectUri,
+        discover,
+        async createAuthorization(opts = {}) {
+            const d = await discover();
+            const state = randomUrlSafe(32, config.crypto);
+            const nonce = randomUrlSafe(32, config.crypto);
+            const codeVerifier = generateCodeVerifier(config.crypto);
+            const url = new URL(d.authorization_endpoint);
+            for (const [k, v] of Object.entries(opts.extraParams ?? {})) {
+                if (RESERVED_PARAMS.has(k))
+                    throw new X1idAuthError("invalid_config", `extraParams may not set "${k}"`);
+                url.searchParams.set(k, v);
+            }
+            url.searchParams.set("client_id", clientId);
+            url.searchParams.set("redirect_uri", redirectUri);
+            url.searchParams.set("response_type", "code");
+            url.searchParams.set("scope", scopeString(opts.scope ?? config.scope));
+            url.searchParams.set("state", state);
+            url.searchParams.set("nonce", nonce);
+            url.searchParams.set("code_challenge", await codeChallengeS256(codeVerifier, config.crypto));
+            url.searchParams.set("code_challenge_method", "S256");
+            if (opts.prompt)
+                url.searchParams.set("prompt", opts.prompt);
+            if (opts.maxAge !== undefined)
+                url.searchParams.set("max_age", String(opts.maxAge));
+            if (opts.uiLocales)
+                url.searchParams.set("ui_locales", opts.uiLocales);
+            return { url: url.toString(), pending: { state, nonce, codeVerifier, redirectUri, issuer, createdAt: now() } };
+        },
+        async handleCallback(callbackUrl, pending, opts = {}) {
+            const url = new URL(String(callbackUrl));
+            // Params arrive in the query (response_mode=query, the default).
+            const p = url.searchParams;
+            const state = p.get("state");
+            if (!state || state !== pending.state) {
+                throw new X1idAuthError("state_mismatch", "state in the callback does not match the login this browser started");
+            }
+            // RFC 9207: reject a response from a different issuer (mix-up attack).
+            const d = await discover();
+            const iss = p.get("iss");
+            if (iss !== null ? iss !== issuer : d.authorization_response_iss_parameter_supported === true) {
+                throw new X1idAuthError("iss_mismatch", "the authorization response's iss is missing or not this issuer");
+            }
+            const err = p.get("error");
+            if (err) {
+                const desc = p.get("error_description") ?? undefined;
+                throw new X1idAuthError(err, `X1ID sign-in failed: ${err}${desc ? ` (${desc})` : ""}`, desc);
+            }
+            const code = p.get("code");
+            if (!code)
+                throw new X1idAuthError("missing_code", "callback has no code");
+            const t = await exchangeCode(code, pending);
+            const userInfo = opts.userInfo === false ? undefined : await fetchUserInfo(t.accessToken, t.idTokenClaims.sub);
+            return { ...t, sub: t.idTokenClaims.sub, userInfo };
+        },
+        exchangeCode,
+        verifyIdToken,
+        fetchUserInfo,
+        async refresh(refreshToken, opts = {}) {
+            const t = parseTokens(await tokenRequest(new URLSearchParams({ grant_type: "refresh_token", refresh_token: refreshToken })));
+            let idTokenClaims;
+            if (t.idToken) {
+                idTokenClaims = await verifyIdToken(t.idToken);
+                if (opts.expectedSub !== undefined && idTokenClaims.sub !== opts.expectedSub) {
+                    throw new X1idAuthError("invalid_id_token", "ID token rejected: refreshed sub differs");
+                }
+            }
+            return { ...t, idTokenClaims };
+        },
+        async revoke(token, hint) {
+            const d = await discover();
+            if (!d.revocation_endpoint)
+                throw new X1idAuthError("invalid_config", "provider has no revocation_endpoint");
+            const body = new URLSearchParams({ token });
+            if (hint)
+                body.set("token_type_hint", hint);
+            const headers = clientAuth(body);
+            const res = await doFetch(d.revocation_endpoint, { method: "POST", headers, body: body.toString() });
+            if (!res.ok)
+                throw new X1idAuthError("token_request_failed", `revocation failed (${res.status})`);
+        },
+        async logoutUrl(opts = {}) {
+            const d = await discover();
+            if (!d.end_session_endpoint)
+                throw new X1idAuthError("invalid_config", "provider has no end_session_endpoint");
+            const url = new URL(d.end_session_endpoint);
+            url.searchParams.set("client_id", clientId);
+            if (opts.idTokenHint)
+                url.searchParams.set("id_token_hint", opts.idTokenHint);
+            if (opts.postLogoutRedirectUri)
+                url.searchParams.set("post_logout_redirect_uri", opts.postLogoutRedirectUri);
+            if (opts.state)
+                url.searchParams.set("state", opts.state);
+            return url.toString();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Browser SPA helpers (sessionStorage + redirect)
+// ---------------------------------------------------------------------------
+const STORAGE_PREFIX = "x1id.oidc.pending.";
+function defaultStorage() {
+    const s = globalThis.sessionStorage;
+    if (!s)
+        throw new X1idAuthError("invalid_config", "no sessionStorage: pass `storage`, or use createAuthorization/handleCallback on a server");
+    return s;
+}
+/**
+ * Start "Sign in with X1ID" in a browser: stores the pending login in
+ * `sessionStorage` (keyed by state, so two tabs don't collide) and navigates
+ * to auth.x1id.io. Pass `navigate` to handle the redirect yourself.
+ */
+export async function beginX1idLogin(client, opts = {}) {
+    const { storage, navigate, ...authOpts } = opts;
+    const { url, pending } = await client.createAuthorization(authOpts);
+    (storage ?? defaultStorage()).setItem(STORAGE_PREFIX + pending.state, JSON.stringify(pending));
+    if (navigate)
+        navigate(url);
+    else
+        globalThis.location.assign(url);
+    return url;
+}
+/**
+ * Finish the login on your redirect page: looks up (and removes — single use)
+ * the pending login for the callback's `state`, then runs
+ * {@link X1idOidcClient.handleCallback}. By default strips `code`/`state` from
+ * the address bar afterwards (`history.replaceState`).
+ */
+export async function completeX1idLogin(client, opts = {}) {
+    const href = String(opts.url ?? globalThis.location.href);
+    const storage = opts.storage ?? defaultStorage();
+    const state = new URL(href).searchParams.get("state");
+    const key = state ? STORAGE_PREFIX + state : null;
+    const raw = key ? storage.getItem(key) : null;
+    if (key)
+        storage.removeItem(key);
+    const g = globalThis;
+    if (opts.cleanUrl !== false && opts.url === undefined && g.history && g.location) {
+        const clean = new URL(g.location.href);
+        for (const k of ["code", "state", "iss", "error", "error_description", "error_uri", "session_state"])
+            clean.searchParams.delete(k);
+        g.history.replaceState(g.history.state, "", clean.toString());
+    }
+    if (!raw)
+        throw new X1idAuthError("state_mismatch", "no pending X1ID login for this callback (already used, or started in another tab/browser)");
+    let pending;
+    try {
+        pending = JSON.parse(raw);
+    }
+    catch {
+        throw new X1idAuthError("state_mismatch", "pending X1ID login is corrupt");
+    }
+    return client.handleCallback(href, pending, opts.userInfo === undefined ? {} : { userInfo: opts.userInfo });
+}