@hawcx/oauth-client 4.0.1 → 5.1.0

package/dist/errors.js

@@ -3,27 +3,71 @@
  * Hawcx OAuth Errors
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TokenVerificationError = exports.TokenExchangeError = exports.HawcxOAuthError = void 0;
-class HawcxOAuthError extends Error {
+exports.DiscoveryError = exports.TokenVerificationError = exports.TokenExchangeError = exports.HawcxOAuthError = exports.HawcxError = void 0;
+/**
+ * Canonical root for every Hawcx SDK error, aligned with the Java/Python SDKs
+ * (`HawcxError`). Catch this to handle any SDK-originated failure.
+ */
+class HawcxError extends Error {
     constructor(message) {
+        super(message);
+        this.name = 'HawcxError';
+    }
+}
+exports.HawcxError = HawcxError;
+/**
+ * Historical base, retained for back-compat. Now a subclass of {@link HawcxError};
+ * every SDK error is catchable via either. New code can catch `HawcxError`.
+ *
+ * Carries optional structured {@link HawcxOAuthErrorFields} (`error` /
+ * `errorDescription`) so callers can dispatch on a stable code without parsing
+ * `.message`. These are populated at the relevant raise sites and never alter
+ * the thrown message string.
+ */
+class HawcxOAuthError extends HawcxError {
+    constructor(message, fields) {
         super(message);
         this.name = 'HawcxOAuthError';
+        if (fields?.error !== undefined)
+            this.error = fields.error;
+        if (fields?.errorDescription !== undefined)
+            this.errorDescription = fields.errorDescription;
     }
 }
 exports.HawcxOAuthError = HawcxOAuthError;
 class TokenExchangeError extends HawcxOAuthError {
-    constructor(message, statusCode) {
-        super(message);
+    constructor(message, statusCode, fields) {
+        super(message, fields);
         this.name = 'TokenExchangeError';
         this.statusCode = statusCode;
     }
 }
 exports.TokenExchangeError = TokenExchangeError;
 class TokenVerificationError extends HawcxOAuthError {
-    constructor(message) {
-        super(message);
+    constructor(message, fields) {
+        super(message, fields);
         this.name = 'TokenVerificationError';
     }
 }
 exports.TokenVerificationError = TokenVerificationError;
+/**
+ * Thrown when OIDC discovery (`HawcxOAuth.fromIssuer`) cannot resolve a usable
+ * provider configuration — DNS / TLS / network failure, non-2xx response from
+ * `/.well-known/openid-configuration`, malformed JSON, or a discovery document
+ * missing required fields (`token_endpoint`, `jwks_uri`,
+ * `id_token_signing_alg_values_supported`).
+ *
+ * The original failure (when present) is attached as `cause`, so the full
+ * diagnostic stack survives.
+ */
+class DiscoveryError extends HawcxOAuthError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'DiscoveryError';
+        if (options?.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+}
+exports.DiscoveryError = DiscoveryError;
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,MAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AALD,0CAKC;AAED,MAAa,kBAAmB,SAAQ,eAAe;IAGrD,YAAY,OAAe,EAAE,UAAmB;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AARD,gDAQC;AAED,MAAa,sBAAuB,SAAQ,eAAe;IACzD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AALD,wDAKC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAgBH;;;GAGG;AACH,MAAa,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AALD,gCAKC;AAED;;;;;;;;GAQG;AACH,MAAa,eAAgB,SAAQ,UAAU;IAM7C,YAAY,OAAe,EAAE,MAA8B;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,MAAM,EAAE,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3D,IAAI,MAAM,EAAE,gBAAgB,KAAK,SAAS;YAAE,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAC9F,CAAC;CACF;AAZD,0CAYC;AAED,MAAa,kBAAmB,SAAQ,eAAe;IAGrD,YAAY,OAAe,EAAE,UAAmB,EAAE,MAA8B;QAC9E,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AARD,gDAQC;AAED,MAAa,sBAAuB,SAAQ,eAAe;IACzD,YAAY,OAAe,EAAE,MAA8B;QACzD,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AALD,wDAKC;AAED;;;;;;;;;GASG;AACH,MAAa,cAAe,SAAQ,eAAe;IACjD,YAAY,OAAe,EAAE,OAAqD;QAChF,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;YAChC,IAA4B,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QACtD,CAAC;IACH,CAAC;CACF;AARD,wCAQC"}

package/dist/index.d.ts

@@ -13,9 +13,11 @@
  * ```
  */
 export { HawcxOAuth } from './oauth';
-export type { HawcxOAuthConfig, ExchangeResult, JwtClaims } from './oauth';
-export { HawcxOAuthError, TokenExchangeError, TokenVerificationError } from './errors';
+export type { HawcxOAuthConfig, HawcxOAuthIssuerConfig, ExchangeResult, JwtClaims, DiscoveryMetadata, VerifyTokenOptions, } from './oauth';
+export { HawcxError, HawcxOAuthError, TokenExchangeError, TokenVerificationError, DiscoveryError, } from './errors';
+export type { HawcxOAuthErrorFields } from './errors';
+export { ClientAssertionSigner, CLIENT_ASSERTION_TYPE } from './client-assertion';
 export * from './delegation';
 export * from './stepup';
-export declare const VERSION = "4.0.1";
+export declare const VERSION = "5.1.0";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGvF,cAAc,cAAc,CAAC;AAG7B,cAAc,UAAU,CAAC;AAEzB,eAAO,MAAM,OAAO,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEtD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAGlF,cAAc,cAAc,CAAC;AAG7B,cAAc,UAAU,CAAC;AAEzB,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/index.js

@@ -28,16 +28,21 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.TokenVerificationError = exports.TokenExchangeError = exports.HawcxOAuthError = exports.HawcxOAuth = void 0;
+exports.VERSION = exports.CLIENT_ASSERTION_TYPE = exports.ClientAssertionSigner = exports.DiscoveryError = exports.TokenVerificationError = exports.TokenExchangeError = exports.HawcxOAuthError = exports.HawcxError = exports.HawcxOAuth = void 0;
 var oauth_1 = require("./oauth");
 Object.defineProperty(exports, "HawcxOAuth", { enumerable: true, get: function () { return oauth_1.HawcxOAuth; } });
 var errors_1 = require("./errors");
+Object.defineProperty(exports, "HawcxError", { enumerable: true, get: function () { return errors_1.HawcxError; } });
 Object.defineProperty(exports, "HawcxOAuthError", { enumerable: true, get: function () { return errors_1.HawcxOAuthError; } });
 Object.defineProperty(exports, "TokenExchangeError", { enumerable: true, get: function () { return errors_1.TokenExchangeError; } });
 Object.defineProperty(exports, "TokenVerificationError", { enumerable: true, get: function () { return errors_1.TokenVerificationError; } });
+Object.defineProperty(exports, "DiscoveryError", { enumerable: true, get: function () { return errors_1.DiscoveryError; } });
+var client_assertion_1 = require("./client-assertion");
+Object.defineProperty(exports, "ClientAssertionSigner", { enumerable: true, get: function () { return client_assertion_1.ClientAssertionSigner; } });
+Object.defineProperty(exports, "CLIENT_ASSERTION_TYPE", { enumerable: true, get: function () { return client_assertion_1.CLIENT_ASSERTION_TYPE; } });
 // Delegation module
 __exportStar(require("./delegation"), exports);
 // Step-up module
 __exportStar(require("./stepup"), exports);
-exports.VERSION = '4.0.1';
+exports.VERSION = '5.1.0';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;;;;;;;;;;;;;;;AAEH,iCAAqC;AAA5B,mGAAA,UAAU,OAAA;AAEnB,mCAAuF;AAA9E,yGAAA,eAAe,OAAA;AAAE,4GAAA,kBAAkB,OAAA;AAAE,gHAAA,sBAAsB,OAAA;AAEpE,oBAAoB;AACpB,+CAA6B;AAE7B,iBAAiB;AACjB,2CAAyB;AAEZ,QAAA,OAAO,GAAG,OAAO,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;;;;;;;;;;;;;;;AAEH,iCAAqC;AAA5B,mGAAA,UAAU,OAAA;AASnB,mCAMkB;AALhB,oGAAA,UAAU,OAAA;AACV,yGAAA,eAAe,OAAA;AACf,4GAAA,kBAAkB,OAAA;AAClB,gHAAA,sBAAsB,OAAA;AACtB,wGAAA,cAAc,OAAA;AAIhB,uDAAkF;AAAzE,yHAAA,qBAAqB,OAAA;AAAE,yHAAA,qBAAqB,OAAA;AAErD,oBAAoB;AACpB,+CAA6B;AAE7B,iBAAiB;AACjB,2CAAyB;AAEZ,QAAA,OAAO,GAAG,OAAO,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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"}