@hawcx/oauth-client 4.0.1 → 5.2.0

package/dist/management/jwt_transport.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * JWT-bearer transport for the Hawcx management API (Path A: private_key_jwt).
+ *
+ * Each request is authenticated with a per-request EdDSA JWT whose `aud` is
+ * the full request URL, carrying a `body_sha256` claim over the EXACT bytes
+ * sent.  This mirrors the wire contract verified end-to-end against hx_auth
+ * (see spec.md §management-api-auth / Python SDK Path A implementation).
+ *
+ * Construction:
+ *   const transport = new JwtBearerTransport({
+ *     baseUrl: 'https://api.hawcx.com',
+ *     configId: 'your-config-id',
+ *     clientId: 'your-client-id',
+ *     oidcSigningKey: pkcs8Pem,   // Ed25519 PKCS#8 PEM — same key registered in admin console
+ *     kid: 'key-id',
+ *   });
+ *
+ * The `http` constructor option accepts an injectable fetch-compatible function
+ * (same signature as the global `fetch`) for testing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwtBearerTransport = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_crypto_2 = require("node:crypto");
+const jose_1 = require("jose");
+const exceptions_1 = require("../delegation/exceptions");
+/**
+ * Drop-in transport for the management API that authenticates via a per-request
+ * EdDSA JWT (`private_key_jwt`, Path A).
+ *
+ * The `send` method has the same name and signature as `DelegationTransport.send`
+ * so the factory can swap transports behind `StepUpClient` without any change to
+ * the business-method layer.
+ */
+class JwtBearerTransport {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.configId = options.configId;
+        this.kid = options.kid;
+        this.clientId = options.clientId;
+        this.jwtTtlSeconds = options.jwtTtlSeconds ?? 60;
+        this.timeoutMs = (options.timeoutSeconds ?? 15) * 1000;
+        this.http = options.http ?? ((...args) => fetch(...args));
+        const key = options.oidcSigningKey;
+        if (typeof key === 'string') {
+            // PKCS#8 PEM
+            this.importKeyFn = () => (0, jose_1.importPKCS8)(key, 'EdDSA');
+        }
+        else if (isJwk(key)) {
+            // Plain JWK object
+            this.importKeyFn = () => (0, jose_1.importJWK)(key, 'EdDSA');
+        }
+        else {
+            // Already a jose KeyLike / CryptoKey — wrap in a resolved promise.
+            const resolved = Promise.resolve(key);
+            this.importKeyFn = () => resolved;
+        }
+    }
+    // ── Key loading ────────────────────────────────────────────────────────────
+    importKey() {
+        if (!this.keyPromise) {
+            // Don't memoise a rejection — reset so the next call retries.
+            this.keyPromise = this.importKeyFn().catch((err) => {
+                this.keyPromise = undefined;
+                throw err;
+            });
+        }
+        return this.keyPromise;
+    }
+    // ── JWT minting ────────────────────────────────────────────────────────────
+    /**
+     * Mint a per-request EdDSA JWT.
+     *
+     * @param audience - full request URL (`baseUrl + endpoint`), pinned per-call
+     * @param bodySha256 - base64url (no-padding) of SHA-256 over the exact body bytes
+     */
+    async mintJwt(audience, bodySha256) {
+        const key = await this.importKey();
+        const nowSec = Math.floor(Date.now() / 1000);
+        return new jose_1.SignJWT({ body_sha256: bodySha256 })
+            .setProtectedHeader({ alg: 'EdDSA', kid: this.kid, typ: 'JWT' })
+            .setIssuer(this.clientId)
+            .setSubject(this.clientId)
+            .setAudience(audience)
+            .setIssuedAt(nowSec)
+            .setExpirationTime(nowSec + this.jwtTtlSeconds)
+            .setJti((0, node_crypto_1.randomUUID)())
+            .sign(key);
+    }
+    // ── Transport ──────────────────────────────────────────────────────────────
+    /**
+     * Send an authenticated POST to `endpoint` with `payload` serialised as JSON.
+     *
+     * Matches the signature of `DelegationTransport.send` so the two transports
+     * are drop-in substitutes behind `StepUpClient`.
+     *
+     * @param options.endpoint - API path, e.g. `/v1/management/stepup/start-token`
+     * @param options.payload  - request body; serialised once and hashed; the
+     *   EXACT same bytes are sent and hashed — no double-serialisation.
+     * @param options.headers  - optional extra headers merged last (win over built-ins)
+     */
+    async send(options) {
+        const { endpoint, payload, headers: extraHeaders = {} } = options;
+        // Canonicalise body ONCE.  The same Buffer is both hashed and sent.
+        const bodyBytes = Buffer.from(JSON.stringify(payload));
+        // SHA-256 → base64url without padding (RFC 7515 §2).
+        const hash = (0, node_crypto_2.createHash)('sha256').update(bodyBytes).digest();
+        const bodySha256 = hash.toString('base64url').replace(/=+$/, '');
+        const url = this.baseUrl + endpoint;
+        let jwt;
+        try {
+            jwt = await this.mintJwt(url, bodySha256);
+        }
+        catch (err) {
+            throw new exceptions_1.DelegationRequestError('Failed to sign management request', { cause: err });
+        }
+        // Extra headers are merged first so the transport's own auth/routing
+        // headers (Authorization, X-Config-Id, X-Hawcx-Protocol-Version) cannot
+        // be accidentally overridden by the caller's header bag.
+        const requestHeaders = {
+            ...extraHeaders,
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${jwt}`,
+            'X-Config-Id': this.configId,
+            'X-Hawcx-Protocol-Version': '2',
+        };
+        let response;
+        let responseData;
+        // Bound every request with a timeout: a connected-but-silent server would
+        // otherwise hang the call indefinitely and can exhaust connection pools.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            response = await this.http(url, {
+                method: 'POST',
+                headers: requestHeaders,
+                body: bodyBytes,
+                signal: controller.signal,
+            });
+            responseData = Buffer.from(await response.arrayBuffer());
+        }
+        catch (err) {
+            if (err instanceof exceptions_1.DelegationRequestError)
+                throw err;
+            throw new exceptions_1.DelegationRequestError('Request to management API failed', { cause: err });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = responseData.toString('utf-8');
+        // Check the HTTP status BEFORE parsing JSON. A non-JSON error body (e.g. a
+        // WAF/proxy HTML 403) must still surface its status as a
+        // DelegationRequestError — not get masked as a JSON parse failure that the
+        // caller can't distinguish from a malformed 200.
+        if (response.status >= 400) {
+            let errorBody = text;
+            try {
+                const errJson = JSON.parse(text);
+                if (errJson?.detail)
+                    errorBody = String(errJson.detail);
+            }
+            catch {
+                // Non-JSON error body — keep the raw text.
+            }
+            throw new exceptions_1.DelegationRequestError(`Management API returned ${response.status}`, {
+                statusCode: response.status,
+                responseBody: errorBody,
+            });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (err) {
+            throw new exceptions_1.DelegationResponseError('Failed to parse management API response', { cause: err });
+        }
+        return parsed;
+    }
+}
+exports.JwtBearerTransport = JwtBearerTransport;
+// ── helpers ──────────────────────────────────────────────────────────────────
+/** Narrow check: is this value a plain JWK object (has `kty` string)? */
+function isJwk(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.kty === 'string');
+}
+//# sourceMappingURL=jwt_transport.js.map

package/dist/management/jwt_transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt_transport.js","sourceRoot":"","sources":["../../src/management/jwt_transport.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAEH,6CAAyC;AACzC,6CAAyC;AACzC,+BAAiE;AAEjE,yDAA2F;AAgD3F;;;;;;;GAOG;AACH,MAAa,kBAAkB;IAa7B,YAAY,OAAkC;QAC5C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;QACjD,IAAI,CAAC,SAAS,GAAG,CAAC,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QAE1D,MAAM,GAAG,GAAG,OAAO,CAAC,cAAc,CAAC;QACnC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,aAAa;YACb,IAAI,CAAC,WAAW,GAAG,GAAG,EAAE,CAAC,IAAA,kBAAW,EAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC;aAAM,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,mBAAmB;YACnB,IAAI,CAAC,WAAW,GAAG,GAAG,EAAE,CAAC,IAAA,gBAAS,EAAC,GAAU,EAAE,OAAO,CAAC,CAAC;QAC1D,CAAC;aAAM,CAAC;YACN,mEAAmE;YACnE,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAkB,CAAC,CAAC;YACrD,IAAI,CAAC,WAAW,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC;QACpC,CAAC;IACH,CAAC;IAED,8EAA8E;IAEtE,SAAS;QACf,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,8DAA8D;YAC9D,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBAC1D,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;gBAC5B,MAAM,GAAG,CAAC;YACZ,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,8EAA8E;IAE9E;;;;;OAKG;IACK,KAAK,CAAC,OAAO,CAAC,QAAgB,EAAE,UAAkB;QACxD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAE7C,OAAO,IAAI,cAAO,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;aAC5C,kBAAkB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;aAC/D,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC;aACxB,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC;aACzB,WAAW,CAAC,QAAQ,CAAC;aACrB,WAAW,CAAC,MAAM,CAAC;aACnB,iBAAiB,CAAC,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC;aAC9C,MAAM,CAAC,IAAA,wBAAU,GAAE,CAAC;aACpB,IAAI,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IAED,8EAA8E;IAE9E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,IAAI,CAAmD,OAI5D;QACC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;QAElE,oEAAoE;QACpE,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QAEvD,qDAAqD;QACrD,MAAM,IAAI,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC;QAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAEjE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC;QAEpC,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,mCAAsB,CAAC,mCAAmC,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QACxF,CAAC;QAED,qEAAqE;QACrE,wEAAwE;QACxE,yDAAyD;QACzD,MAAM,cAAc,GAA2B;YAC7C,GAAG,YAAY;YACf,cAAc,EAAE,kBAAkB;YAClC,eAAe,EAAE,UAAU,GAAG,EAAE;YAChC,aAAa,EAAE,IAAI,CAAC,QAAQ;YAC5B,0BAA0B,EAAE,GAAG;SAChC,CAAC;QAEF,IAAI,QAAkB,CAAC;QACvB,IAAI,YAAoB,CAAC;QAEzB,0EAA0E;QAC1E,yEAAyE;QACzE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACnE,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;gBAC9B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,cAAc;gBACvB,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,mCAAsB;gBAAE,MAAM,GAAG,CAAC;YACrD,MAAM,IAAI,mCAAsB,CAAC,kCAAkC,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QACvF,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAE5C,2EAA2E;QAC3E,yDAAyD;QACzD,2EAA2E;QAC3E,iDAAiD;QACjD,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;YAC3B,IAAI,SAAS,GAAW,IAAI,CAAC;YAC7B,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;gBAC5D,IAAI,OAAO,EAAE,MAAM;oBAAE,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC1D,CAAC;YAAC,MAAM,CAAC;gBACP,2CAA2C;YAC7C,CAAC;YACD,MAAM,IAAI,mCAAsB,CAAC,2BAA2B,QAAQ,CAAC,MAAM,EAAE,EAAE;gBAC7E,UAAU,EAAE,QAAQ,CAAC,MAAM;gBAC3B,YAAY,EAAE,SAAS;aACxB,CAAC,CAAC;QACL,CAAC;QAED,IAAI,MAAY,CAAC;QACjB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAS,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,oCAAuB,CAAC,yCAAyC,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/F,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AA1KD,gDA0KC;AAED,gFAAgF;AAEhF,yEAAyE;AACzE,SAAS,KAAK,CAAC,KAAc;IAC3B,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAAiC,CAAC,GAAG,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC"}

package/dist/oauth.d.ts

@@ -1,16 +1,71 @@
 /**
  * Hawcx OAuth Client
  *
- * Simple, clean implementation using the jose library for JWT verification.
+ * Two construction paths:
+ *
+ *   1. OIDC discovery (recommended) — `HawcxOAuth.fromIssuer(...)` fetches
+ *      `<issuer>/.well-known/openid-configuration` once at startup and wires
+ *      up a verifier that enforces signature + iss + aud + exp + nbf on every
+ *      subsequent `verifyToken` call.
+ *
+ *   2. Legacy — `new HawcxOAuth({ configId, baseUrl })` hits the fixed
+ *      endpoints `/oauth2/token` and `/keys` directly. Backward-compatible
+ *      with v4.x callers, but does NOT verify `iss` or `aud` — the JWT's
+ *      signature is the only check.
+ *
+ * Both modes are safe to share across requests.
  */
 import { type JWTPayload } from 'jose';
+import { ClientAssertionSigner } from './client-assertion';
 export interface HawcxOAuthConfig {
-    /** Your Hawcx API key (X-Config-Id) */
+    /** Your Hawcx config-id (sent as the `X-Config-Id` header on token exchange) */
     configId: string;
     /** Base URL override (default: https://api.hawcx.com) */
     baseUrl?: string;
     /** Request timeout in ms (default: 10000) */
     timeout?: number;
+    /**
+     * Tolerated clock skew in seconds when verifying `exp` and `nbf` claims.
+     * Default 10. Set to 0 to require exact-time validation; raise above 10
+     * if you regularly see NTP drift between the issuer and this host.
+     * Spec.md §3.3.
+     */
+    clockToleranceSeconds?: number;
+}
+/**
+ * Options for the discovery-mode factory.
+ *
+ * **configId vs clientId.** Hawcx separates the tenant routing key from the
+ * audience claim — the SDK forwards each to the right place:
+ *
+ *   - `configId` — opaque per-tenant routing key. Sent verbatim as the
+ *     `X-Config-Id` header on the token-exchange POST so the OAuth server can
+ *     look up the tenant.
+ *   - `clientId` — whatever value the tenant has configured (in the Hawcx admin
+ *     console) as the `aud` claim on issued id_tokens. The verifier checks the
+ *     token's `aud` against this exact string.
+ *
+ * Passing the same value for both fails verification with an audience-mismatch
+ * error unless the tenant has configured them identically.
+ */
+export interface HawcxOAuthIssuerConfig {
+    /** Hawcx issuer URL (e.g. `https://api.hawcx.com`). Used for OIDC discovery and as the expected `iss` claim. */
+    issuer: string;
+    /** Hawcx tenant config-id; sent as the `X-Config-Id` header on token exchange. */
+    configId: string;
+    /** Hawcx project / tenant client-id; matched as the expected `aud` claim on id_tokens. */
+    clientId: string;
+    /** Per-request timeout in ms for token exchange and JWKS fetch (default: 10000) */
+    timeout?: number;
+    /** Timeout in ms for the one-shot discovery fetch (default: 5000) */
+    discoveryTimeout?: number;
+    /**
+     * Tolerated clock skew in seconds when verifying `exp` and `nbf` claims.
+     * Default 10. Set to 0 to require exact-time validation; raise above 10
+     * if you regularly see NTP drift between the issuer and this host.
+     * Spec.md §3.3.
+     */
+    clockToleranceSeconds?: number;
 }
 export interface JwtClaims extends JWTPayload {
     /** Subject (user ID) */
@@ -44,55 +99,167 @@ export interface ExchangeResult {
     /** Verified JWT claims */
     claims: JwtClaims;
 }
+/**
+ * Subset of the OIDC discovery document the SDK actually consumes.
+ * The raw response may include additional fields; they're preserved on
+ * `HawcxOAuth.discoveryMetadata` but the SDK only relies on these.
+ */
+export interface DiscoveryMetadata {
+    issuer: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    id_token_signing_alg_values_supported: string[];
+    [key: string]: unknown;
+}
+export interface VerifyTokenOptions {
+    /**
+     * If set, the JWT's `nonce` claim must equal this value. Use when your
+     * authorization request bound a nonce. Checked in both discovery and
+     * legacy modes — legacy mode skips `iss` / `aud` but the explicit nonce
+     * comparison applies unconditionally when this option is provided.
+     */
+    nonce?: string;
+}
 /**
  * Hawcx OAuth Client
  *
- * Handles code exchange and JWT verification using the jose library.
+ * Discovery-mode usage (recommended):
  *
- * @example
  * ```typescript
- * const oauth = new HawcxOAuth({ configId: 'your-api-key' });
- *
- * // Exchange authorization code for tokens
+ * const oauth = await HawcxOAuth.fromIssuer({
+ *   issuer: 'https://api.hawcx.com',
+ *   configId: process.env.HAWCX_CONFIG_ID!,
+ *   clientId: process.env.HAWCX_CLIENT_ID!,
+ * });
  * const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
- * console.log(claims.sub); // user ID
+ * ```
+ *
+ * Legacy usage (no discovery; aud/iss are not checked):
  *
- * // Later, verify an existing token
- * const claims = await oauth.verifyToken(idToken);
+ * ```typescript
+ * const oauth = new HawcxOAuth({ configId: process.env.HAWCX_CONFIG_ID! });
+ * const { idToken, claims } = await oauth.exchangeCode(code, codeVerifier);
  * ```
  */
 export declare class HawcxOAuth {
     private readonly configId;
-    private readonly baseUrl;
+    private readonly tokenEndpoint;
+    private readonly jwksUrl;
     private readonly timeout;
+    private readonly clockToleranceSeconds;
+    /** Expected `aud` claim. `null` in legacy mode (audience is not checked). */
+    private readonly expectedAudience;
+    /** Expected `iss` claim. `null` in legacy mode (issuer is not checked). */
+    private readonly expectedIssuer;
+    /**
+     * id_token signing algorithms accepted by `verifyToken`. In discovery mode
+     * this is the intersection of the issuer's advertised algs with the SDK's
+     * closed allowlist ({@link DEFAULT_ID_TOKEN_ALGS}). `null` in legacy mode
+     * (we have no discovery doc to constrain against, so jose's default
+     * "accept whatever the JWKS provides" remains — same as 4.x).
+     */
+    private readonly allowedAlgorithms;
+    /** Resolved OIDC discovery document. `null` in legacy mode. */
+    readonly discoveryMetadata: DiscoveryMetadata | null;
     private jwks;
+    /**
+     * Optional `private_key_jwt` signer (discovery mode only). `null` ⇒ the
+     * token exchange stays public-client + PKCE. Set via {@link withClientAssertion},
+     * which returns a *new* configured client (this field is `readonly`).
+     */
+    private readonly clientAssertionSigner;
+    /**
+     * Construct a legacy-mode client. For discovery mode, prefer
+     * {@link HawcxOAuth.fromIssuer}.
+     */
     constructor(config: HawcxOAuthConfig);
+    /**
+     * Construct a client via OIDC discovery.
+     *
+     * Fetches `<issuer>/.well-known/openid-configuration`, reads the token
+     * endpoint, JWKS URI, and supported id_token signing algorithm, and wires
+     * a verifier that enforces signature + `iss` + `aud` + `exp` + `nbf` on
+     * subsequent {@link verifyToken} calls.
+     *
+     * **Discovery is bounded** at `discoveryTimeout` ms (default 5000) so an
+     * unreachable issuer fails fast with {@link DiscoveryError} rather than
+     * hanging your bootstrap.
+     *
+     * @throws {DiscoveryError} if discovery fails to resolve or the document
+     *   is missing required fields (`token_endpoint`, `jwks_uri`,
+     *   `id_token_signing_alg_values_supported`).
+     */
+    static fromIssuer(config: HawcxOAuthIssuerConfig): Promise<HawcxOAuth>;
+    /**
+     * Opt into `private_key_jwt` client authentication (discovery mode only).
+     * When set, the token exchange signs and attaches an RFC 7523
+     * `client_assertion` (in addition to PKCE). Without it, the exchange stays
+     * public-client + PKCE.
+     *
+     * Intended to be called once right after {@link fromIssuer}, before the
+     * client is shared. Returns `this` for chaining.
+     */
+    /**
+     * @beta Experimental `private_key_jwt` surface; may change before stable.
+     *
+     * Returns a **new** discovery-mode client configured with the signer (sharing
+     * this client's resolved discovery state); the original is unchanged, so a
+     * configured client is immutable. Chained usage
+     * (`(await fromIssuer(...)).withClientAssertion(...)`) is unaffected.
+     *
+     * Refuses if the OP's discovery doc advertises
+     * `token_endpoint_auth_methods_supported` without `private_key_jwt`
+     * (the assertion would be silently ignored).
+     */
+    withClientAssertion(signer: ClientAssertionSigner): HawcxOAuth;
     /**
      * Exchange authorization code for id_token and verified claims.
      *
      * @param code - Authorization code from auth flow
      * @param codeVerifier - PKCE code verifier
-     * @returns id_token and verified claims
+     * @param redirectUri - Optional. If your original authorization request
+     *   registered a `redirect_uri`, RFC 6749 §4.1.3 requires the token
+     *   request to carry the same value. Omit if the auth request also omitted it.
+     * @param expectedNonce - Optional. If your authorization request bound a
+     *   `nonce`, pass it here so the returned id_token's `nonce` is verified.
+     *   Required whenever the token carries a nonce (verification refuses
+     *   otherwise — OIDC Core §3.1.3.7).
      */
-    exchangeCode(code: string, codeVerifier: string): Promise<ExchangeResult>;
+    exchangeCode(code: string, codeVerifier: string, redirectUri?: string, expectedNonce?: string): Promise<ExchangeResult>;
     /**
      * Verify a JWT token and return its claims.
      *
-     * Uses the jose library which handles all signature formats automatically,
-     * including ECDSA signature conversion between P1363 and DER formats.
+     * In **discovery mode**, enforces signature + `iss` + `aud` + `exp` + `nbf`
+     * (and the optional `nonce` claim if `options.nonce` is provided).
      *
-     * @param token - JWT token to verify
-     * @returns Verified claims
+     * In **legacy mode**, only the signature is verified. Audience and issuer
+     * claims are not checked, matching the pre-5.x behavior.
      */
-    verifyToken(token: string): Promise<JwtClaims>;
+    verifyToken(token: string, options?: VerifyTokenOptions): Promise<JwtClaims>;
     /**
-     * Get or create the remote JWKS.
-     * The jose library handles caching internally.
+     * Get or create the remote JWKS. jose handles caching + concurrent-fetch
+     * coalescing internally.
+     *
+     * No single-flight guard is needed here: this method is fully synchronous
+     * (no `await` between the null-check and the assignment), so within Node's
+     * single-threaded event loop the first caller assigns `this.jwks` before any
+     * other code runs. Two concurrent `verifyToken` calls therefore cannot create
+     * duplicate `RemoteJWKSet` instances.
      */
     private getJwks;
     /**
-     * Clear the JWKS cache (useful for testing or key rotation).
+     * Drop the cached JWKS so the next `verifyToken` re-fetches it. Useful after
+     * an operator-triggered signing-key rotation, or in tests.
+     *
+     * Canonical name, aligned with the Java (`refreshJwks`) and Python
+     * (`refresh_jwks`) SDKs.
+     */
+    refreshJwks(): void;
+    /**
+     * @deprecated since 5.1.0 — renamed to {@link refreshJwks} for cross-SDK
+     *   consistency. Will be removed in 6.0.0. Behaviour is identical.
      */
     clearCache(): void;
+    private clearCacheWarned;
 }
 //# sourceMappingURL=oauth.d.ts.map

package/dist/oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AAKtE,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe;IACf,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,sBAAsB;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,MAAM,EAAE,SAAS,CAAC;CACnB;AAQD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,IAAI,CAAsD;gBAEtD,MAAM,EAAE,gBAAgB;IASpC;;;;;;OAMG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAkD/E;;;;;;;;OAQG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IA+BpD;;;OAGG;IACH,OAAO,CAAC,OAAO;IAaf;;OAEG;IACH,UAAU,IAAI,IAAI;CAGnB"}
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}