@idpartners/client-attestation-sdk 0.0.0-stage → 1.0.0

package/dist/token-source.js

@@ -0,0 +1,510 @@
+/**
+ * One call to get an access token with client attestation.
+ *
+ * Point it at an attester (PingFederate by default) and call `.token()`. It runs the whole flow:
+ *
+ *     discover -> get platform identity (evidence) -> get a challenge -> mint the attestation ->
+ *     call the token endpoint with the attestation headers -> cache the access token
+ *
+ * The workload sends no client secret and no client_id. Its only credential is the attestation, built
+ * from the identity its runtime already gives it (auto-detected; see `evidence.ts`).
+ *
+ *     import { ClientAttestation } from "@idpartners/client-attestation-sdk";
+ *
+ *     const ca = new ClientAttestation("pf.example.com");
+ *     const token = await ca.token();                       // cached until it nears expiry
+ *
+ *     // the fetch wrapper attaches the token (and a DPoP proof for a DPoP-bound token):
+ *     await ca.fetch("https://api.example.com/things");
+ *     // or build the headers for any other client:
+ *     const headers = await ca.requestHeaders("GET", "https://api.example.com/things");
+ */
+import { base64url } from "jose";
+import { DpopProofBuilder } from "./builders.js";
+import { ClientAttestationCredential, DPOP_HEADER } from "./credential.js";
+import { ClientAttestationError, TransportError } from "./errors.js";
+import { autoDetectEvidence } from "./evidence.js";
+import { MintRequest, PingFederateProfile, metadataDocument, } from "./attester.js";
+import { jsonOk, request } from "./http.js";
+import { emit, failureReason, hostOf, NOOP_LOGGER, urlParts } from "./logging.js";
+import { utf8Decode } from "./runtime.js";
+import { SigningKeyPair } from "./signing-key-pair.js";
+export const ATTESTATION_HEADER = "OAuth-Client-Attestation";
+export const POP_HEADER = "OAuth-Client-Attestation-PoP";
+/** Refresh this many seconds before the token actually expires, so a token is never used at the edge. */
+export const DEFAULT_EXPIRY_SKEW_SECONDS = 30;
+export { ClientAttestationError, TransportError } from "./errors.js";
+const USE_DPOP_NONCE = "use_dpop_nonce";
+const DPOP_NONCE_HEADER = "DPoP-Nonce";
+/** What the https check calls the URL a profile's call goes to, by step. */
+const STEP_LABELS = {
+    discover: "attesterUrl",
+    mint: "attestation_endpoint",
+    challenge: "challenge_endpoint",
+};
+/**
+ * Gets and caches an access token using client attestation.
+ *
+ * `new ClientAttestation(attesterUrl, opts)`, or `new ClientAttestation(opts)` with `opts.metadata` (no
+ * discovery) or a custom `opts.profile`.
+ *
+ * @param attesterUrl the attester's host — `"pf.example.com"`, or a full base URL
+ *   `"https://pf.example.com"`. Plain hostnames default to https. Optional when `metadata` or `profile`
+ *   is given.
+ */
+export class ClientAttestation {
+    /** The normalised attester URL, or `""` when the client was built from static metadata alone. */
+    baseUrl;
+    #profile;
+    #evidence;
+    #authorizationDetails;
+    #operator;
+    #challengeAtToken;
+    #algorithm;
+    #skew;
+    #timeoutMs;
+    #popMethod;
+    #requireChallenge;
+    #allowInsecure;
+    #logger;
+    /** The token, its type and its bound key: always replaced together, never one without the others. */
+    #state = null;
+    #metadata;
+    #refreshing = null;
+    /** The last `DPoP-Nonce` each origin returned. */
+    #nonces = new Map();
+    constructor(attesterUrl, opts = {}) {
+        if (typeof attesterUrl === "object" && attesterUrl !== null) {
+            opts = attesterUrl;
+            attesterUrl = undefined;
+        }
+        const url = attesterUrl ?? opts.attesterUrl;
+        this.#profile = opts.profile ?? new PingFederateProfile();
+        this.#metadata = opts.metadata ?? null;
+        this.#evidence = opts.evidence;
+        this.#authorizationDetails = opts.authorizationDetails;
+        this.#operator = opts.operator && Object.keys(opts.operator).length > 0 ? opts.operator : undefined;
+        this.#challengeAtToken = opts.challengeAtToken ?? true;
+        this.#algorithm = opts.algorithm ?? "ES256";
+        this.#skew = opts.expirySkewSeconds ?? DEFAULT_EXPIRY_SKEW_SECONDS;
+        this.#timeoutMs = opts.timeoutMs ?? 20_000;
+        this.#popMethod = opts.popMethod ?? "attestation_pop_jwt";
+        this.#requireChallenge = opts.requireChallenge ?? true;
+        this.#allowInsecure = opts.allowInsecure ?? false;
+        this.#logger = opts.logger ?? NOOP_LOGGER;
+        if (url === undefined && (opts.metadata || opts.profile)) {
+            this.baseUrl = "";
+        }
+        else {
+            this.baseUrl = normalizeBaseUrl(url);
+            this.#checkSecure(this.baseUrl, "attesterUrl");
+        }
+    }
+    // ── public API ──────────────────────────────────────────────────────────────────────────────────
+    /** Return a valid access token, minting a new one only when the cached one is near expiry. */
+    async token(opts = {}) {
+        return (await this.#current(opts)).accessToken;
+    }
+    /**
+     * `{ Authorization: "<scheme> <token>" }`. For a Bearer token that is all a resource needs. For a
+     * DPoP-bound token (`token_type` DPoP) the scheme is `DPoP` and every request ALSO needs a fresh
+     * DPoP proof — use {@link requestHeaders} (or {@link fetch}) instead, which adds it.
+     */
+    async authorizationHeader(opts = {}) {
+        const state = await this.#current(opts);
+        return { Authorization: `${scheme(state)} ${state.accessToken}` };
+    }
+    /**
+     * The headers to send to a resource for one request, obtaining or refreshing the token as needed.
+     *
+     * - Bearer token: `{ Authorization: "Bearer <t>" }`
+     * - DPoP token: `{ Authorization: "DPoP <t>", DPoP: <proof> }` — a fresh proof signed by the key the
+     *   token is bound to, for this `method` and `url`, carrying `ath` and the last `DPoP-Nonce` the
+     *   url's origin returned, if any.
+     */
+    async requestHeaders(method, url, opts = {}) {
+        const state = await this.#current(opts);
+        const headers = { Authorization: `${scheme(state)} ${state.accessToken}` };
+        if (isDpop(state)) {
+            headers[DPOP_HEADER] = await new DpopProofBuilder(state.key)
+                .method(method)
+                .uri(url)
+                .accessToken(state.accessToken)
+                .nonce(this.#nonces.get(originOf(url)) ?? null)
+                .build();
+        }
+        return headers;
+    }
+    /**
+     * A `fetch` wrapper that attaches the token (refreshing it as needed) to the request. Same signature
+     * as global `fetch`. For a DPoP-bound token it adds a fresh proof and, when the resource answers with
+     * a `use_dpop_nonce` challenge and a `DPoP-Nonce`, resends ONCE with a proof carrying that nonce —
+     * unless the body is a one-shot stream, which cannot be resent (the challenge response is returned).
+     */
+    async fetch(input, init = {}) {
+        const isRequest = typeof Request !== "undefined" && input instanceof Request;
+        const url = isRequest ? input.url : String(input);
+        const method = (init.method ?? (isRequest ? input.method : "GET")).toUpperCase();
+        // A Request's own body is cloned so the retry can send it again.
+        const nextInput = () => (isRequest ? input.clone() : input);
+        let dpopBound = false;
+        const send = async () => {
+            const headers = new Headers(init.headers ?? (isRequest ? input.headers : undefined));
+            const auth = await this.requestHeaders(method, url);
+            dpopBound = DPOP_HEADER in auth;
+            for (const [name, value] of Object.entries(auth))
+                headers.set(name, value);
+            return fetch(nextInput(), { ...init, headers });
+        };
+        const first = await send();
+        if (!dpopBound)
+            return first;
+        const nonce = first.headers.get(DPOP_NONCE_HEADER);
+        if (nonce)
+            this.#nonces.set(originOf(url), nonce);
+        if (!nonce || !replayable(init.body) || !(await isNonceChallenge(first)))
+            return first;
+        emit(this.#logger, "info", "dpop.nonce_retry", { host: hostOf(url), status: first.status, at: "resource" });
+        await first.body?.cancel().catch(() => undefined);
+        return send();
+    }
+    /**
+     * The attester's discovery document (PingFederate: `/.well-known/client-attester`), fetched once and
+     * then cached. With static `metadata`, the fields that were given, in the document's snake_case.
+     */
+    async discovery() {
+        return metadataDocument(await this.attesterMetadata());
+    }
+    /** The attester's endpoints: the static `metadata`, or what the profile discovered (once, then cached). */
+    async attesterMetadata() {
+        const host = this.baseUrl ? hostOf(this.baseUrl) : undefined;
+        if (this.#metadata === null) {
+            this.#metadata = await this.#profile.discover(this.#transport(), this.baseUrl || undefined);
+            emit(this.#logger, "debug", "discovery.fetched", { host });
+        }
+        else {
+            emit(this.#logger, "debug", "discovery.cached", { host });
+        }
+        return this.#metadata;
+    }
+    /** The transport handed to the profile: this client's https rule, timeout and logging. */
+    #transport() {
+        return {
+            requestJson: (step, method, url, body) => {
+                this.#checkSecure(url, STEP_LABELS[step] ?? `${step} URL`);
+                return this.#getJson(step, method, url, body);
+            },
+        };
+    }
+    // ── the flow ────────────────────────────────────────────────────────────────────────────────────
+    /** The cached token state, or a freshly minted one. Concurrent callers share one refresh. */
+    async #current(opts) {
+        const state = this.#state;
+        if (!opts.forceRefresh && state && Date.now() < state.expiresAt) {
+            emit(this.#logger, "debug", "token.cache_hit", {
+                expires_in: Math.max(0, Math.round((state.expiresAt - Date.now()) / 1000)),
+            });
+            return state;
+        }
+        if (!this.#refreshing) {
+            emit(this.#logger, "debug", "token.refreshing", {
+                reason: opts.forceRefresh ? "forced" : state ? "expired" : "initial",
+            });
+            this.#refreshing = this.#refresh().finally(() => {
+                this.#refreshing = null;
+            });
+        }
+        return this.#refreshing;
+    }
+    async #refresh() {
+        const { response, key } = await this.#runFlow();
+        const expiresIn = response.expires_in;
+        const state = {
+            accessToken: response.access_token,
+            tokenType: typeof response.token_type === "string" && response.token_type ? response.token_type : "Bearer",
+            key,
+            expiresAt: expiresIn ? Date.now() + (Number(expiresIn) - this.#skew) * 1000 : 0,
+        };
+        this.#state = state;
+        return state;
+    }
+    async #runFlow() {
+        const meta = await this.attesterMetadata();
+        const audience = meta.evidenceAudience;
+        if (!audience) {
+            throw new ClientAttestationError("attester discovery document has no evidence_audience");
+        }
+        const evidenceSource = this.#evidence ?? (await autoDetectEvidence());
+        const svid = await evidenceSource.fetch(audience);
+        emit(this.#logger, "debug", "evidence.obtained", { source: evidenceSource.constructor?.name });
+        const instanceKey = await SigningKeyPair.generate(this.#algorithm);
+        const challenge = await this.#fetchChallenge(meta.challengeEndpoint);
+        const { attestation } = await this.#profile.mint(this.#transport(), meta, new MintRequest({
+            instanceKey,
+            evidence: svid,
+            challenge,
+            authorizationDetails: this.#authorizationDetails,
+            operator: this.#operator,
+        }));
+        // The profile resolves the token endpoint (PingFederate: the advertised one, else the standard path
+        // on the attester host).
+        const tokenEndpoint = meta.tokenEndpoint;
+        if (!tokenEndpoint)
+            throw new ClientAttestationError("attester metadata has no token_endpoint");
+        this.#checkSecure(tokenEndpoint, "token_endpoint");
+        const clientId = jwtSub(attestation);
+        emit(this.#logger, "debug", "attestation.minted", {
+            host: meta.attestationEndpoint ? hostOf(meta.attestationEndpoint) : undefined,
+            client_id: clientId,
+            alg: this.#algorithm,
+        });
+        // The PoP audience must be PF's configured issuer, which the attester advertises as pop_audience.
+        // Falling back to the token endpoint URL only works when the dialed URL matches PF's issuer (no
+        // proxy in between) — so prefer the advertised value.
+        const popAudience = meta.popAudience || tokenEndpoint;
+        // See `challengeAtToken`: some attesters consume the challenge the moment the mint's instance
+        // proof uses it, and reject a token request that presents the same value a second time. Against
+        // one of those, only the mint gets the challenge.
+        const tokenChallenge = this.#challengeAtToken ? challenge : undefined;
+        const credential = new ClientAttestationCredential(attestation, instanceKey);
+        const obtained = (response) => {
+            const expiresIn = Number(response.expires_in);
+            emit(this.#logger, "info", "token.obtained", {
+                host: hostOf(tokenEndpoint),
+                client_id: clientId,
+                token_type: typeof response.token_type === "string" && response.token_type ? response.token_type : "Bearer",
+                expires_in: response.expires_in != null && Number.isFinite(expiresIn) ? expiresIn : undefined,
+                pop_method: this.#popMethod,
+            });
+            return { response, key: instanceKey };
+        };
+        if (this.#popMethod !== "dpop_combined") {
+            const headers = await credential.popHeaders(clientId, popAudience, tokenChallenge ?? null);
+            return obtained(this.#tokenResponse(tokenEndpoint, await this.#postToken(tokenEndpoint, headers)));
+        }
+        // DPoP combined: the attester challenge rides as the DPoP nonce. If the AS demands its own nonce
+        // (400 use_dpop_nonce + DPoP-Nonce), retry once with that — the server's demand wins.
+        let res = await this.#postToken(tokenEndpoint, await credential.dpopHeaders("POST", tokenEndpoint, tokenChallenge ?? null));
+        const serverNonce = res.headers.get(DPOP_NONCE_HEADER);
+        if (serverNonce)
+            this.#nonces.set(originOf(tokenEndpoint), serverNonce);
+        if (res.status === 400 && serverNonce && jsonError(res.body) === USE_DPOP_NONCE) {
+            emit(this.#logger, "info", "dpop.nonce_retry", { host: hostOf(tokenEndpoint), status: res.status, at: "token_endpoint" });
+            res = await this.#postToken(tokenEndpoint, await credential.dpopHeaders("POST", tokenEndpoint, serverNonce));
+        }
+        return obtained(this.#tokenResponse(tokenEndpoint, res));
+    }
+    async #fetchChallenge(endpoint) {
+        if (!endpoint)
+            return undefined;
+        this.#checkSecure(endpoint, "challenge_endpoint");
+        // The attester advertised a challenge, so minting without one weakens replay protection: fail
+        // closed unless the caller opted out with requireChallenge: false.
+        let body;
+        try {
+            body = await this.#getJson("challenge", "POST", endpoint);
+        }
+        catch (err) {
+            if (!(err instanceof ClientAttestationError))
+                throw err;
+            if (!this.#requireChallenge) {
+                emit(this.#logger, "warn", "challenge.skipped", { host: hostOf(endpoint) });
+                return undefined;
+            }
+            throw new ClientAttestationError(`could not fetch the attestation challenge from ${endpoint}: ${err.message}`, {
+                status: err.status,
+                body: err.body,
+                cause: err,
+            });
+        }
+        const challenge = body.attestation_challenge;
+        if (typeof challenge === "string" && challenge) {
+            emit(this.#logger, "debug", "challenge.fetched", { host: hostOf(endpoint) });
+            return challenge;
+        }
+        if (!this.#requireChallenge) {
+            emit(this.#logger, "warn", "challenge.skipped", { host: hostOf(endpoint) });
+            return undefined;
+        }
+        throw new ClientAttestationError(`challenge endpoint ${endpoint} returned no attestation_challenge`);
+    }
+    /** The parsed token response; a failure is logged as `http.failed` before it is thrown. */
+    #tokenResponse(endpoint, res) {
+        try {
+            return tokenResponse(res);
+        }
+        catch (err) {
+            const reason = err instanceof TransportError ? failureReason(err) : res.ok ? "malformed" : "status";
+            this.#failed("token", "POST", endpoint, reason, res.status);
+            throw err;
+        }
+    }
+    #failed(step, method, url, reason, status) {
+        emit(this.#logger, "warn", "http.failed", { step, method, ...urlParts(url), status, reason });
+    }
+    #postToken(endpoint, authHeaders) {
+        const params = new URLSearchParams({ grant_type: "client_credentials" });
+        // Extension parameter, sent only when configured: the attestation is the authoritative carrier,
+        // this repeats the operator on the wire for an AS that maps it into may_act.
+        if (this.#operator)
+            params.set("operator", canonicalJson(this.#operator));
+        const form = params.toString();
+        return this.#send("token", endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+                ...authHeaders,
+            },
+            body: form,
+        });
+    }
+    /** Refuse a non-https URL unless it is loopback or the caller passed `allowInsecure`. */
+    #checkSecure(url, what) {
+        if (this.#allowInsecure)
+            return;
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new ClientAttestationError(`${what} is not a valid URL: ${url}`);
+        }
+        if (parsed.protocol === "https:" || LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase()))
+            return;
+        throw new ClientAttestationError(`${what} must use https: ${url} (loopback hosts are exempt; pass allowInsecure: true to override)`);
+    }
+    async #getJson(step, method, url, jsonBody) {
+        const headers = { Accept: "application/json" };
+        let body;
+        if (jsonBody !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(jsonBody);
+        }
+        const res = await this.#send(step, url, { method, headers, body });
+        try {
+            return jsonOk(res, { allowEmpty: true });
+        }
+        catch (err) {
+            this.#failed(step, method, url, failureReason(err), res.status);
+            throw err;
+        }
+    }
+    /**
+     * Every call the flow makes goes through the shared transport, with this client's timeout. A call that
+     * gets no usable response is logged as `http.failed`.
+     */
+    async #send(step, url, opts) {
+        try {
+            return await request(url, { ...opts, timeoutMs: this.#timeoutMs });
+        }
+        catch (err) {
+            const status = err instanceof ClientAttestationError ? err.status : undefined;
+            this.#failed(step, opts.method ?? "GET", url, failureReason(err), status);
+            throw err;
+        }
+    }
+}
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+function tokenResponse(res) {
+    if (!res.ok) {
+        throw new ClientAttestationError(`token endpoint returned HTTP ${res.status}`, {
+            status: res.status,
+            body: res.body,
+        });
+    }
+    const parsed = jsonOk(res, { allowEmpty: true });
+    if (!parsed.access_token) {
+        throw new ClientAttestationError("token endpoint returned no access_token", { body: res.body });
+    }
+    return parsed;
+}
+function isDpop(state) {
+    return state.tokenType.toLowerCase() === "dpop";
+}
+function scheme(state) {
+    return isDpop(state) ? "DPoP" : "Bearer";
+}
+/** `scheme://host[:port]` of a URL, the key DPoP nonces are remembered under. */
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    }
+}
+/** The `error` member of a JSON object body, or undefined. */
+function jsonError(body) {
+    try {
+        return JSON.parse(body)?.error;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Can this fetch body be sent a second time? One-shot streams cannot. */
+function replayable(body) {
+    if (body == null)
+        return true;
+    return !(typeof ReadableStream !== "undefined" && body instanceof ReadableStream) &&
+        !(typeof body[Symbol.asyncIterator] === "function");
+}
+/**
+ * RFC 9449 section 9: a resource asks for a nonce with 401 + `WWW-Authenticate: DPoP error="use_dpop_nonce"`;
+ * section 8 (and some resources) use a 400 JSON `{"error":"use_dpop_nonce"}`.
+ */
+async function isNonceChallenge(res) {
+    if (res.status === 401) {
+        const challenge = res.headers.get("WWW-Authenticate") ?? "";
+        return /(^|,)\s*DPoP\b/i.test(challenge) && /error\s*=\s*"?use_dpop_nonce"?/i.test(challenge);
+    }
+    if (res.status === 400) {
+        return jsonError(await res.clone().text()) === USE_DPOP_NONCE;
+    }
+    return false;
+}
+/**
+ * Compact JSON with object keys sorted at every depth and non-ASCII escaped as `\uXXXX` - the same
+ * bytes as Python's `json.dumps(value, separators=(",", ":"), sort_keys=True)`.
+ *
+ * @internal
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value)).replace(/[\u0080-\uffff]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object") {
+        const obj = value;
+        return Object.fromEntries(Object.keys(obj).sort().map((k) => [k, sortKeys(obj[k])]));
+    }
+    return value;
+}
+/** @internal */
+export function normalizeBaseUrl(attesterUrl) {
+    let host = (attesterUrl ?? "").trim().replace(/\/+$/, "");
+    if (!host) {
+        throw new Error("attesterUrl is required");
+    }
+    if (!host.includes("://")) {
+        host = "https://" + host;
+    }
+    return host;
+}
+/** @internal */
+export function jwtSub(compactJwt) {
+    const payload = compactJwt.split(".")[1] ?? "";
+    let claims;
+    try {
+        claims = JSON.parse(utf8Decode(base64url.decode(payload)));
+    }
+    catch {
+        throw new ClientAttestationError("minted attestation is not a well-formed JWT");
+    }
+    if (!claims?.sub) {
+        throw new ClientAttestationError("minted attestation has no sub (client id)");
+    }
+    return claims.sub;
+}

package/dist/validator/config.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Validator configuration.
+ */
+import type { JSONWebKeySet } from "jose";
+/** Default accepted JWS algorithms: EC / RSA / RSA-PSS at 256/384/512. Frozen, so it can't be widened. */
+export declare const DEFAULT_ALGORITHMS: readonly string[];
+/** RFC 9068 section 2.1: a JWT access token's `typ` is `at+jwt` (the `application/` prefix is optional). */
+export declare const DEFAULT_TOKEN_TYPES: readonly string[];
+/** How the resource server authenticates to the AS when introspecting. */
+export type IntrospectionAuthMethod = "client_secret_basic" | "client_secret_post";
+/**
+ * RFC 7662 introspection endpoint + client credentials (the resource server authenticating to the AS).
+ */
+export interface IntrospectionConfig {
+    endpoint: string;
+    clientId: string;
+    clientSecret: string;
+    /** Defaults to `"client_secret_basic"`. */
+    authMethod?: IntrospectionAuthMethod;
+}
+/**
+ * What this resource server accepts: the trusted issuer, its own audience identifier(s), the signing
+ * keys (static `jwks` or a `jwksUri` to fetch), required scopes, accepted algorithms, clock leeway,
+ * and optional introspection.
+ *
+ * `issuer` and `audiences` are required: a validator that skips either accepts tokens minted for someone
+ * else. `acceptedTokenTypes` is checked against the JWT `typ` header when the token carries one, so an ID
+ * token can't stand in for an access token. Pass `null` to turn that check off for an issuer that stamps
+ * something other than `at+jwt`.
+ *
+ * An explicitly empty `acceptedAlgorithms` or `acceptedTokenTypes` accepts nothing, and `leewaySeconds: 0`
+ * allows no clock skew: only an omitted field takes the default. `none` and the `HS*` algorithms are
+ * refused even when listed (see validation/SEMANTICS.md).
+ */
+export interface ValidatorConfig {
+    issuer: string;
+    audiences: string | string[];
+    jwks?: JSONWebKeySet;
+    jwksUri?: string;
+    requiredScopes?: string[];
+    /** Defaults to {@link DEFAULT_ALGORITHMS}. */
+    acceptedAlgorithms?: string[];
+    /** Clock skew allowed on `exp` / `nbf` / `iat`, in seconds. Defaults to 60. */
+    leewaySeconds?: number;
+    introspection?: IntrospectionConfig;
+    /** Defaults to {@link DEFAULT_TOKEN_TYPES}; `null` disables the `typ` check. */
+    acceptedTokenTypes?: string[] | null;
+}
+/** A {@link ValidatorConfig} with every optional field defaulted. */
+export interface ResolvedConfig {
+    issuer: string;
+    audiences: string[];
+    jwks?: JSONWebKeySet;
+    jwksUri?: string;
+    requiredScopes: string[];
+    acceptedAlgorithms: string[];
+    leewaySeconds: number;
+    introspection?: IntrospectionConfig;
+    /** Normalised with {@link normaliseType}; `null` when the check is off. */
+    acceptedTokenTypes: string[] | null;
+}

package/dist/validator/config.js

@@ -0,0 +1,61 @@
+/** Default accepted JWS algorithms: EC / RSA / RSA-PSS at 256/384/512. Frozen, so it can't be widened. */
+export const DEFAULT_ALGORITHMS = Object.freeze([
+    "ES256",
+    "ES384",
+    "ES512",
+    "RS256",
+    "RS384",
+    "RS512",
+    "PS256",
+    "PS384",
+    "PS512",
+]);
+/** RFC 9068 section 2.1: a JWT access token's `typ` is `at+jwt` (the `application/` prefix is optional). */
+export const DEFAULT_TOKEN_TYPES = Object.freeze(["at+jwt"]);
+/**
+ * `none` (in any case) and the HMAC algorithms are refused whatever `acceptedAlgorithms` says: an unsigned
+ * token proves nothing, and an HMAC "signature" checked against an issuer's public key is forgeable by
+ * anyone who has that key.
+ *
+ * @internal
+ */
+export function isForbiddenAlgorithm(alg) {
+    const lowered = alg.toLowerCase();
+    return lowered === "none" || lowered.startsWith("hs");
+}
+/**
+ * Compare JOSE `typ` values the way RFC 7515 section 4.1.9 says to: case-insensitively, with an optional
+ * `application/` prefix.
+ *
+ * @internal
+ */
+export function normaliseType(value) {
+    const lower = value.toLowerCase();
+    return lower.startsWith("application/") ? lower.slice("application/".length) : lower;
+}
+/**
+ * Normalize a caller-supplied config, applying defaults (mirrors Python's `ValidatorConfig`).
+ *
+ * @internal
+ */
+export function resolveConfig(config) {
+    if (!config.issuer) {
+        throw new Error("issuer is required");
+    }
+    const audiences = typeof config.audiences === "string" ? [config.audiences] : [...(config.audiences ?? [])];
+    if (audiences.length === 0) {
+        throw new Error("at least one audience is required");
+    }
+    const types = config.acceptedTokenTypes === undefined ? DEFAULT_TOKEN_TYPES : config.acceptedTokenTypes;
+    return {
+        issuer: config.issuer,
+        audiences,
+        jwks: config.jwks,
+        jwksUri: config.jwksUri,
+        requiredScopes: [...(config.requiredScopes ?? [])],
+        acceptedAlgorithms: [...(config.acceptedAlgorithms ?? DEFAULT_ALGORITHMS)],
+        leewaySeconds: config.leewaySeconds ?? 60,
+        introspection: config.introspection,
+        acceptedTokenTypes: types === null ? null : types.map(normaliseType),
+    };
+}

package/dist/validator/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Stable validation outcome codes, shared across the Python / TypeScript / Go ports so their verdicts
+ * can be compared directly.
+ */
+export declare const VALID = "valid";
+export declare const EXPIRED = "expired";
+export declare const NOT_YET_VALID = "not_yet_valid";
+export declare const INVALID_SIGNATURE = "invalid_signature";
+export declare const INVALID_ISSUER = "invalid_issuer";
+export declare const INVALID_AUDIENCE = "invalid_audience";
+export declare const INSUFFICIENT_SCOPE = "insufficient_scope";
+export declare const INVALID_TOKEN = "invalid_token";
+export declare const UNSUPPORTED_ALGORITHM = "unsupported_algorithm";
+export declare const KEY_NOT_FOUND = "key_not_found";
+export declare const INACTIVE = "inactive";
+export declare const MISSING_EXPIRY = "missing_expiry";
+export declare const ISSUED_IN_FUTURE = "issued_in_future";
+export declare const INVALID_TOKEN_TYPE = "invalid_token_type";
+/** Every stable error code a validation can report. */
+export type ValidationError = typeof EXPIRED | typeof NOT_YET_VALID | typeof INVALID_SIGNATURE | typeof INVALID_ISSUER | typeof INVALID_AUDIENCE | typeof INSUFFICIENT_SCOPE | typeof INVALID_TOKEN | typeof UNSUPPORTED_ALGORITHM | typeof KEY_NOT_FOUND | typeof INACTIVE | typeof MISSING_EXPIRY | typeof ISSUED_IN_FUTURE | typeof INVALID_TOKEN_TYPE;

package/dist/validator/errors.js

@@ -0,0 +1,18 @@
+/**
+ * Stable validation outcome codes, shared across the Python / TypeScript / Go ports so their verdicts
+ * can be compared directly.
+ */
+export const VALID = "valid";
+export const EXPIRED = "expired";
+export const NOT_YET_VALID = "not_yet_valid";
+export const INVALID_SIGNATURE = "invalid_signature";
+export const INVALID_ISSUER = "invalid_issuer";
+export const INVALID_AUDIENCE = "invalid_audience";
+export const INSUFFICIENT_SCOPE = "insufficient_scope";
+export const INVALID_TOKEN = "invalid_token";
+export const UNSUPPORTED_ALGORITHM = "unsupported_algorithm";
+export const KEY_NOT_FOUND = "key_not_found";
+export const INACTIVE = "inactive";
+export const MISSING_EXPIRY = "missing_expiry";
+export const ISSUED_IN_FUTURE = "issued_in_future";
+export const INVALID_TOKEN_TYPE = "invalid_token_type";