@iqauth/sdk 2.2.0 → 2.3.0

package/README.md

@@ -477,6 +477,30 @@ Common codes you'll handle:
 
 ---
 
+## Don't intercept `/sign-in?code=…`
+
+If your app uses an SSO bridge route (e.g. `your-app.com/sign-in` redirects users to `auth.dispositioniq.com`) and that same route is **also** the configured OAuth `redirect_uri`, your bridge logic will fire on the return trip and immediately bounce the user back to the issuer **before** the SDK can exchange the `?code=` for tokens. Symptoms: an infinite redirect loop, or a successful login that the app never sees.
+
+**Pick one:**
+
+1. **Recommended — use a dedicated callback path.** Configure `redirect_uri` to point at `/api/iqauth/callback` (the helper route mounted by `iqAuth({...}).attachHelpers(app)` for Express, or by `iqAuth({...})` for Next/Fastify/Hono). Your `/sign-in` route stays purely a "send user to the issuer" bridge.
+
+2. **If you must reuse `/sign-in` as the redirect target,** guard the bridge:
+
+   ```ts
+   app.get("/sign-in", (req, res, next) => {
+     // OAuth return trip — let the SDK handle it, don't redirect away.
+     if (req.query.code || req.query.error) return next();
+     return res.redirect(buildIssuerAuthorizeUrl(req));
+   });
+   ```
+
+   …and add `inlineCallback: true` to your `iqAuth({...})` options so a GET handler is mounted on the callback path to complete the exchange and 302 to the final destination.
+
+This is the single most common bug we see when teams add IQAuth to an app that already had its own session redirect logic.
+
+---
+
 ## Bundled docs
 
 Long-form integration guides ship **inside the npm tarball** at `node_modules/@iqauth/sdk/docs/`. List them with:

package/dist/browser-session.d.mts

@@ -1,7 +1,6 @@
 import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-Cxl3bQHt.mjs';
-import { I as IQAuthClient } from './client-Dv4v92Mj.mjs';
+import { I as IQAuthClient } from './client-vdh2a9fJ.mjs';
 export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
-import 'jsonwebtoken';
 
 declare class BrowserSessionIQAuthClient extends IQAuthClient {
     constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);

package/dist/browser-session.d.ts

@@ -1,7 +1,6 @@
 import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-Cxl3bQHt.js';
-import { I as IQAuthClient } from './client-DXbHb2ul.js';
+import { I as IQAuthClient } from './client-DTX4hNdS.js';
 export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
-import 'jsonwebtoken';
 
 declare class BrowserSessionIQAuthClient extends IQAuthClient {
     constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);

package/dist/browser-session.js

@@ -446,8 +446,7 @@ function parseMfaResponse(data, browserSessionMode) {
 }
 
 // src/modules/tokens.ts
-var import_crypto = __toESM(require("crypto"));
-var import_jsonwebtoken = __toESM(require("jsonwebtoken"));
+var import_jose = require("jose");
 var JWKS_CACHE_TTL_MS = 60 * 60 * 1e3;
 var DEFAULT_TOKEN_ISSUER = [
   "https://auth.dispositioniq.com",
@@ -460,6 +459,24 @@ var DEFAULT_TOKEN_AUDIENCE = [
   "iqvalidate"
 ];
 var DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+function decodeProtectedHeader(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) return null;
+  try {
+    const padded = parts[0] + "=".repeat((4 - parts[0].length % 4) % 4);
+    const b64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+    let json;
+    if (typeof atob === "function") {
+      json = atob(b64);
+    } else {
+      const { Buffer: Buffer2 } = require("buffer");
+      json = Buffer2.from(b64, "base64").toString("utf8");
+    }
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
 var TokensModule = class {
   constructor(baseUrl, options = {}) {
     this.jwksCache = null;
@@ -470,49 +487,49 @@ var TokensModule = class {
     this.defaultClockTolerance = options.clockTolerance ?? DEFAULT_CLOCK_TOLERANCE_SECONDS;
   }
   /**
-   * Verify a JWT access token using RS256 via JWKS from /.well-known/jwks.json.
-   * Caches JWKS keys for 1 hour. Retries once on unknown `kid`.
-   *
-   * @remarks Validates against /.well-known/jwks.json. Issuer, audience, and
-   * clock tolerance default to client config but can be overridden per call.
+   * Verify a JWT access token using RS256/ES256 via JWKS from
+   * `/.well-known/jwks.json`. Backed by `jose` (Web Crypto) so it runs on
+   * Node, browser, and edge runtimes alike — no `node:crypto` dependency.
+   * Caches JWKS for 1 hour and refetches once on unknown `kid`.
    */
   async verify(token, options = {}) {
-    const decoded = import_jsonwebtoken.default.decode(token, { complete: true });
-    if (!decoded || typeof decoded === "string") {
+    const header = decodeProtectedHeader(token);
+    if (!header) {
       throw new IQAuthError("TOKEN_INVALID", "Unable to decode token");
     }
-    const kid = decoded.header.kid;
+    const kid = header.kid;
     if (!kid) {
       throw new IQAuthError("TOKEN_INVALID", "Token missing kid header");
     }
-    let publicKey = await this.getPublicKey(kid);
-    if (!publicKey) {
-      await this.refreshJwks();
-      publicKey = await this.getPublicKey(kid);
+    let cache = await this.ensureCache();
+    if (!cache.byKid.has(kid)) {
+      this.jwksCache = null;
+      cache = await this.ensureCache();
     }
-    if (!publicKey) {
+    if (!cache.byKid.has(kid)) {
       throw new IQAuthError("TOKEN_INVALID", `Unknown key ID: ${kid}`);
     }
     const issuer = options.issuer ?? this.defaultIssuer;
     const audience = options.audience ?? this.defaultAudience;
     const clockTolerance = options.clockTolerance ?? this.defaultClockTolerance;
-    const algorithms = options.algorithms ?? ["RS256"];
+    const algorithms = options.algorithms ?? ["RS256", "ES256"];
+    const verifyOptions = {
+      algorithms,
+      clockTolerance,
+      issuer,
+      audience
+    };
     try {
-      const verifyOptions = {
-        algorithms,
-        clockTolerance,
-        // The jsonwebtoken types insist on tuple types for arrays; runtime
-        // accepts plain string[] so we cast to satisfy the compiler.
-        issuer,
-        audience
-      };
-      const verified = import_jsonwebtoken.default.verify(token, publicKey, verifyOptions);
-      return verified;
+      const { payload } = await (0, import_jose.jwtVerify)(token, cache.verifier, verifyOptions);
+      return payload;
     } catch (err) {
+      if (err instanceof import_jose.errors.JWTExpired) {
+        throw new IQAuthError("TOKEN_EXPIRED", "Token has expired");
+      }
+      if (err instanceof import_jose.errors.JOSEError) {
+        throw new IQAuthError("TOKEN_INVALID", err.message);
+      }
       if (err instanceof Error) {
-        if (err.name === "TokenExpiredError") {
-          throw new IQAuthError("TOKEN_EXPIRED", "Token has expired");
-        }
         throw new IQAuthError("TOKEN_INVALID", err.message);
       }
       throw new IQAuthError("TOKEN_INVALID", "Token verification failed");
@@ -520,29 +537,40 @@ var TokensModule = class {
   }
   /**
    * Decode a JWT without verification. Returns null if malformed.
-   *
-   * @remarks Local decode only — no network call
    */
   decode(token) {
-    const decoded = import_jsonwebtoken.default.decode(token);
-    return decoded;
+    try {
+      const parts = token.split(".");
+      if (parts.length < 2) return null;
+      const payload = parts[1];
+      const padded = payload + "=".repeat((4 - payload.length % 4) % 4);
+      const b64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+      let json;
+      if (typeof atob === "function") {
+        json = atob(b64);
+      } else {
+        const { Buffer: Buffer2 } = require("buffer");
+        json = Buffer2.from(b64, "base64").toString("utf8");
+      }
+      try {
+        json = decodeURIComponent(escape(json));
+      } catch {
+      }
+      const claims = JSON.parse(json);
+      if (!claims || typeof claims !== "object") return null;
+      return claims;
+    } catch {
+      return null;
+    }
   }
-  /**
-   * Check if a token is expired based on the `exp` claim.
-   *
-   * @remarks Local check only — no network call
-   */
+  /** Check if a token is expired based on the `exp` claim. */
   isExpired(token) {
     const claims = this.decode(token);
     if (!claims?.exp) return true;
     const now = Math.floor(Date.now() / 1e3);
     return claims.exp <= now;
   }
-  /**
-   * Get the claims from a token without verification.
-   *
-   * @remarks Local decode only — no network call
-   */
+  /** Get the claims from a token without verification. */
   getClaims(token) {
     const claims = this.decode(token);
     if (!claims) {
@@ -550,11 +578,15 @@ var TokensModule = class {
     }
     return claims;
   }
-  async getPublicKey(kid) {
-    if (!this.jwksCache || Date.now() - this.jwksCache.fetchedAt > JWKS_CACHE_TTL_MS) {
-      await this.refreshJwks();
+  async ensureCache() {
+    if (this.jwksCache && Date.now() - this.jwksCache.fetchedAt <= JWKS_CACHE_TTL_MS) {
+      return this.jwksCache;
+    }
+    await this.refreshJwks();
+    if (!this.jwksCache) {
+      throw new IQAuthError("INTERNAL_ERROR", "JWKS cache unavailable after refresh");
     }
-    return this.jwksCache?.keys.get(kid) ?? null;
+    return this.jwksCache;
   }
   async refreshJwks() {
     if (this.inFlightRefresh) {
@@ -581,35 +613,24 @@ var TokensModule = class {
             "Malformed JWKS response: expected { keys: [...] }"
           );
         }
-        const keys = /* @__PURE__ */ new Map();
+        const byKid = /* @__PURE__ */ new Set();
         for (const key of jwks.keys) {
-          if (!key || typeof key.kid !== "string" || typeof key.n !== "string" || typeof key.e !== "string") {
+          if (!key || typeof key.kid !== "string" || typeof key.n !== "string" && typeof key.x !== "string" || key.kty === "RSA" && (typeof key.n !== "string" || typeof key.e !== "string")) {
             throw new IQAuthError(
               "INTERNAL_ERROR",
               "Malformed JWKS response: key missing required fields"
             );
           }
-          const pem = this.jwkToPem(key);
-          keys.set(key.kid, pem);
+          byKid.add(key.kid);
         }
-        this.jwksCache = { keys, fetchedAt: Date.now() };
+        const verifier = (0, import_jose.createLocalJWKSet)({ keys: jwks.keys });
+        this.jwksCache = { raw: jwks.keys, byKid, verifier, fetchedAt: Date.now() };
       } finally {
         this.inFlightRefresh = null;
       }
     })();
     return this.inFlightRefresh;
   }
-  jwkToPem(jwk) {
-    const keyObject = import_crypto.default.createPublicKey({
-      key: {
-        kty: jwk.kty,
-        n: jwk.n,
-        e: jwk.e
-      },
-      format: "jwk"
-    });
-    return keyObject.export({ type: "spki", format: "pem" });
-  }
   /** @internal Exposed for testing — clears JWKS cache */
   clearCache() {
     this.jwksCache = null;
@@ -817,7 +838,7 @@ var PermissionsModule = class {
 };
 
 // src/modules/oidc.ts
-var import_crypto2 = __toESM(require("crypto"));
+var import_crypto = __toESM(require("crypto"));
 var InMemoryOidcStateStore = class {
   constructor() {
     this.map = /* @__PURE__ */ new Map();
@@ -898,12 +919,12 @@ var OidcModule = class {
    * ready to redirect the user to.
    */
   async createAuthRequest(params) {
-    const codeVerifier = base64UrlEncode(import_crypto2.default.randomBytes(32));
+    const codeVerifier = base64UrlEncode(import_crypto.default.randomBytes(32));
     const codeChallenge = base64UrlEncode(
-      import_crypto2.default.createHash("sha256").update(codeVerifier).digest()
+      import_crypto.default.createHash("sha256").update(codeVerifier).digest()
     );
-    const state = base64UrlEncode(import_crypto2.default.randomBytes(16));
-    const nonce = base64UrlEncode(import_crypto2.default.randomBytes(16));
+    const state = base64UrlEncode(import_crypto.default.randomBytes(16));
+    const nonce = base64UrlEncode(import_crypto.default.randomBytes(16));
     await this.stateStore.set(state, {
       codeVerifier,
       state,

package/dist/browser-session.mjs

@@ -1,6 +1,7 @@
 import {
   IQAuthClient
-} from "./chunk-MDUHPQMM.mjs";
+} from "./chunk-W3F4JYGP.mjs";
+import "./chunk-UNYDG2L4.mjs";
 import {
   ErrorCodes,
   IQAuthError

package/dist/browser.d.mts

@@ -1,4 +1,4 @@
-export { C as CallbackResult, S as SessionManager, d as SessionManagerOptions, a as SessionSnapshot, e as SessionStatus, b as SignInOptions, c as SignOutOptions, f as buildSignInUrl, h as handleAuthCallback, r as redirectToSignIn, s as signIn, g as signOut } from './signIn-D_kP3v-c.mjs';
+export { C as CallbackResult, S as SessionManager, d as SessionManagerOptions, a as SessionSnapshot, e as SessionStatus, b as SignInOptions, c as SignOutOptions, f as buildSignInUrl, h as handleAuthCallback, r as redirectToSignIn, s as signIn, g as signOut } from './signIn-Cd0P4y9d.mjs';
 export { K as KeyMode, c as ParsedPublishableKey, P as PublishableKeyPayload, e as encodePublishableKey, i as isPublishableKey, b as isSecretKey, p as parsePublishableKey } from './publishableKey-BaR0HoAH.mjs';
 export { a as ErrorCode, E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
 import './types-Cxl3bQHt.mjs';

package/dist/browser.d.ts

@@ -1,4 +1,4 @@
-export { C as CallbackResult, S as SessionManager, d as SessionManagerOptions, a as SessionSnapshot, e as SessionStatus, b as SignInOptions, c as SignOutOptions, f as buildSignInUrl, h as handleAuthCallback, r as redirectToSignIn, s as signIn, g as signOut } from './signIn-BVDTIA_t.js';
+export { C as CallbackResult, S as SessionManager, d as SessionManagerOptions, a as SessionSnapshot, e as SessionStatus, b as SignInOptions, c as SignOutOptions, f as buildSignInUrl, h as handleAuthCallback, r as redirectToSignIn, s as signIn, g as signOut } from './signIn-DKakyzeu.js';
 export { K as KeyMode, c as ParsedPublishableKey, P as PublishableKeyPayload, e as encodePublishableKey, i as isPublishableKey, b as isSecretKey, p as parsePublishableKey } from './publishableKey-BaR0HoAH.js';
 export { a as ErrorCode, E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
 import './types-Cxl3bQHt.js';

package/dist/browser.js

@@ -177,7 +177,7 @@ function assertPublishableKey(raw, opts) {
   if (!isValidIssuerUrl(decoded.iss)) {
     throw new IQAuthError(
       "CONFIG_INVALID",
-      `${ctx}IQAuth publishable key encodes an invalid issuer (iss=${JSON.stringify(decoded.iss)}). Expected a fully-qualified URL like "https://auth.example.com" (scheme required). Regenerate the key from the IQAuth admin console, or set IQAUTH_ISSUER to the correct issuer URL as a temporary workaround.`
+      `${ctx}IQAuth publishable key encodes an invalid issuer (iss=${JSON.stringify(decoded.iss)}). Expected a fully-qualified URL like "https://auth.example.com" (scheme required). Regenerate the key from the IQAuth admin console \u2014 the new key will encode a valid issuer URL.`
     );
   }
   return { mode: shapeMatch[1], iss: decoded.iss, appId: decoded.appId, tenantId: decoded.tenantId, kid: decoded.kid, raw };
@@ -715,6 +715,7 @@ async function createPkcePair() {
 // src/browser/signIn.ts
 var DEFAULT_SIGN_IN_PATH = "/sign-in";
 var DEFAULT_LOGOUT_PATH = "/api/v1/auth/logout";
+var DEFAULT_SSO_LOGOUT_PATH = "/oidc/sso-logout";
 var DEFAULT_TOKEN_PATH = "/oidc/token";
 var DEFAULT_CALLBACK_PATH = "/auth/callback";
 function defaultRedirectUri() {
@@ -813,11 +814,21 @@ async function handleAuthCallback(manager, options = {}) {
 }
 async function signOut(manager, opts = {}) {
   if (!opts.localOnly) {
+    const issuer = manager.issuerUrl.replace(/\/$/, "");
     try {
-      const url = `${manager.issuerUrl}${opts.logoutPath ?? DEFAULT_LOGOUT_PATH}`;
+      const url = `${issuer}${opts.logoutPath ?? DEFAULT_LOGOUT_PATH}`;
       await manager.fetch(url, { method: "POST" }).catch(() => void 0);
     } catch {
     }
+    if (opts.endSsoSession !== false) {
+      try {
+        await fetch(`${issuer}${DEFAULT_SSO_LOGOUT_PATH}`, {
+          method: "POST",
+          credentials: "include"
+        }).catch(() => void 0);
+      } catch {
+      }
+    }
   }
   clearCookie(REFRESH_COOKIE);
   manager.signOutLocal();

package/dist/browser.mjs

@@ -12,13 +12,13 @@ import {
   setCookie,
   signIn,
   signOut
-} from "./chunk-QZB745C2.mjs";
+} from "./chunk-RACIPVLD.mjs";
 import {
   encodePublishableKey,
   isPublishableKey,
   isSecretKey,
   parsePublishableKey
-} from "./chunk-QEJB7WEQ.mjs";
+} from "./chunk-WQWBJSSS.mjs";
 import {
   ErrorCodes,
   IQAuthError

package/dist/{chunk-D72UL5HL.mjs → chunk-EKTNEZIH.mjs}

@@ -1,9 +1,9 @@
-import {
-  assertPublishableKey
-} from "./chunk-QEJB7WEQ.mjs";
 import {
   IQAuthClient
-} from "./chunk-MDUHPQMM.mjs";
+} from "./chunk-W3F4JYGP.mjs";
+import {
+  assertPublishableKey
+} from "./chunk-WQWBJSSS.mjs";
 import {
   IQAuthError
 } from "./chunk-6I6RM4MN.mjs";

package/dist/{chunk-M4J6BPK7.mjs → chunk-KGEPDXHU.mjs}

@@ -1,6 +1,6 @@
 import {
   assertPublishableKey
-} from "./chunk-QEJB7WEQ.mjs";
+} from "./chunk-WQWBJSSS.mjs";
 
 // src/server/handlers.ts
 var TERMINAL_REFRESH_ERROR_CODES = /* @__PURE__ */ new Set([
@@ -193,6 +193,15 @@ async function handleSignout(config, input) {
     } catch {
     }
   }
+  if (input.endSsoSession !== false && input.ssoCookieHeader) {
+    try {
+      await cfg.fetchImpl(`${cfg.issuer}/oidc/sso-logout`, {
+        method: "POST",
+        headers: { Cookie: input.ssoCookieHeader }
+      });
+    } catch {
+    }
+  }
   return {
     status: 200,
     body: { success: true, data: { signedOut: true } },

package/dist/{chunk-QZB745C2.mjs → chunk-RACIPVLD.mjs}

@@ -1,6 +1,6 @@
 import {
   assertPublishableKey
-} from "./chunk-QEJB7WEQ.mjs";
+} from "./chunk-WQWBJSSS.mjs";
 import {
   IQAuthError
 } from "./chunk-6I6RM4MN.mjs";
@@ -526,6 +526,7 @@ async function createPkcePair() {
 // src/browser/signIn.ts
 var DEFAULT_SIGN_IN_PATH = "/sign-in";
 var DEFAULT_LOGOUT_PATH = "/api/v1/auth/logout";
+var DEFAULT_SSO_LOGOUT_PATH = "/oidc/sso-logout";
 var DEFAULT_TOKEN_PATH = "/oidc/token";
 var DEFAULT_CALLBACK_PATH = "/auth/callback";
 function defaultRedirectUri() {
@@ -624,11 +625,21 @@ async function handleAuthCallback(manager, options = {}) {
 }
 async function signOut(manager, opts = {}) {
   if (!opts.localOnly) {
+    const issuer = manager.issuerUrl.replace(/\/$/, "");
     try {
-      const url = `${manager.issuerUrl}${opts.logoutPath ?? DEFAULT_LOGOUT_PATH}`;
+      const url = `${issuer}${opts.logoutPath ?? DEFAULT_LOGOUT_PATH}`;
       await manager.fetch(url, { method: "POST" }).catch(() => void 0);
     } catch {
     }
+    if (opts.endSsoSession !== false) {
+      try {
+        await fetch(`${issuer}${DEFAULT_SSO_LOGOUT_PATH}`, {
+          method: "POST",
+          credentials: "include"
+        }).catch(() => void 0);
+      } catch {
+      }
+    }
   }
   clearCookie(REFRESH_COOKIE);
   manager.signOutLocal();

package/dist/chunk-UNYDG2L4.mjs

@@ -0,0 +1,209 @@
+import {
+  IQAuthError
+} from "./chunk-6I6RM4MN.mjs";
+import {
+  __require
+} from "./chunk-Y6FXYEAI.mjs";
+
+// src/modules/tokens.ts
+import {
+  createLocalJWKSet,
+  jwtVerify,
+  errors as joseErrors
+} from "jose";
+var JWKS_CACHE_TTL_MS = 60 * 60 * 1e3;
+var DEFAULT_TOKEN_ISSUER = [
+  "https://auth.dispositioniq.com",
+  "auth.dispositioniq.com"
+];
+var DEFAULT_TOKEN_AUDIENCE = [
+  "dispositioniq",
+  "iqcapture",
+  "iqreuse",
+  "iqvalidate"
+];
+var DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+function decodeProtectedHeader(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) return null;
+  try {
+    const padded = parts[0] + "=".repeat((4 - parts[0].length % 4) % 4);
+    const b64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+    let json;
+    if (typeof atob === "function") {
+      json = atob(b64);
+    } else {
+      const { Buffer } = __require("buffer");
+      json = Buffer.from(b64, "base64").toString("utf8");
+    }
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+var TokensModule = class {
+  constructor(baseUrl, options = {}) {
+    this.jwksCache = null;
+    this.inFlightRefresh = null;
+    this.baseUrl = baseUrl;
+    this.defaultIssuer = options.issuer ?? DEFAULT_TOKEN_ISSUER;
+    this.defaultAudience = options.audience ?? DEFAULT_TOKEN_AUDIENCE;
+    this.defaultClockTolerance = options.clockTolerance ?? DEFAULT_CLOCK_TOLERANCE_SECONDS;
+  }
+  /**
+   * Verify a JWT access token using RS256/ES256 via JWKS from
+   * `/.well-known/jwks.json`. Backed by `jose` (Web Crypto) so it runs on
+   * Node, browser, and edge runtimes alike — no `node:crypto` dependency.
+   * Caches JWKS for 1 hour and refetches once on unknown `kid`.
+   */
+  async verify(token, options = {}) {
+    const header = decodeProtectedHeader(token);
+    if (!header) {
+      throw new IQAuthError("TOKEN_INVALID", "Unable to decode token");
+    }
+    const kid = header.kid;
+    if (!kid) {
+      throw new IQAuthError("TOKEN_INVALID", "Token missing kid header");
+    }
+    let cache = await this.ensureCache();
+    if (!cache.byKid.has(kid)) {
+      this.jwksCache = null;
+      cache = await this.ensureCache();
+    }
+    if (!cache.byKid.has(kid)) {
+      throw new IQAuthError("TOKEN_INVALID", `Unknown key ID: ${kid}`);
+    }
+    const issuer = options.issuer ?? this.defaultIssuer;
+    const audience = options.audience ?? this.defaultAudience;
+    const clockTolerance = options.clockTolerance ?? this.defaultClockTolerance;
+    const algorithms = options.algorithms ?? ["RS256", "ES256"];
+    const verifyOptions = {
+      algorithms,
+      clockTolerance,
+      issuer,
+      audience
+    };
+    try {
+      const { payload } = await jwtVerify(token, cache.verifier, verifyOptions);
+      return payload;
+    } catch (err) {
+      if (err instanceof joseErrors.JWTExpired) {
+        throw new IQAuthError("TOKEN_EXPIRED", "Token has expired");
+      }
+      if (err instanceof joseErrors.JOSEError) {
+        throw new IQAuthError("TOKEN_INVALID", err.message);
+      }
+      if (err instanceof Error) {
+        throw new IQAuthError("TOKEN_INVALID", err.message);
+      }
+      throw new IQAuthError("TOKEN_INVALID", "Token verification failed");
+    }
+  }
+  /**
+   * Decode a JWT without verification. Returns null if malformed.
+   */
+  decode(token) {
+    try {
+      const parts = token.split(".");
+      if (parts.length < 2) return null;
+      const payload = parts[1];
+      const padded = payload + "=".repeat((4 - payload.length % 4) % 4);
+      const b64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+      let json;
+      if (typeof atob === "function") {
+        json = atob(b64);
+      } else {
+        const { Buffer } = __require("buffer");
+        json = Buffer.from(b64, "base64").toString("utf8");
+      }
+      try {
+        json = decodeURIComponent(escape(json));
+      } catch {
+      }
+      const claims = JSON.parse(json);
+      if (!claims || typeof claims !== "object") return null;
+      return claims;
+    } catch {
+      return null;
+    }
+  }
+  /** Check if a token is expired based on the `exp` claim. */
+  isExpired(token) {
+    const claims = this.decode(token);
+    if (!claims?.exp) return true;
+    const now = Math.floor(Date.now() / 1e3);
+    return claims.exp <= now;
+  }
+  /** Get the claims from a token without verification. */
+  getClaims(token) {
+    const claims = this.decode(token);
+    if (!claims) {
+      throw new IQAuthError("TOKEN_INVALID", "Unable to decode token claims");
+    }
+    return claims;
+  }
+  async ensureCache() {
+    if (this.jwksCache && Date.now() - this.jwksCache.fetchedAt <= JWKS_CACHE_TTL_MS) {
+      return this.jwksCache;
+    }
+    await this.refreshJwks();
+    if (!this.jwksCache) {
+      throw new IQAuthError("INTERNAL_ERROR", "JWKS cache unavailable after refresh");
+    }
+    return this.jwksCache;
+  }
+  async refreshJwks() {
+    if (this.inFlightRefresh) {
+      return this.inFlightRefresh;
+    }
+    this.inFlightRefresh = (async () => {
+      try {
+        const res = await fetch(`${this.baseUrl}/.well-known/jwks.json`);
+        if (!res.ok) {
+          throw new IQAuthError(
+            "INTERNAL_ERROR",
+            `Failed to fetch JWKS: ${res.status}`
+          );
+        }
+        let jwks;
+        try {
+          jwks = await res.json();
+        } catch {
+          throw new IQAuthError("INTERNAL_ERROR", "Malformed JWKS response: invalid JSON");
+        }
+        if (!jwks || !Array.isArray(jwks.keys)) {
+          throw new IQAuthError(
+            "INTERNAL_ERROR",
+            "Malformed JWKS response: expected { keys: [...] }"
+          );
+        }
+        const byKid = /* @__PURE__ */ new Set();
+        for (const key of jwks.keys) {
+          if (!key || typeof key.kid !== "string" || typeof key.n !== "string" && typeof key.x !== "string" || key.kty === "RSA" && (typeof key.n !== "string" || typeof key.e !== "string")) {
+            throw new IQAuthError(
+              "INTERNAL_ERROR",
+              "Malformed JWKS response: key missing required fields"
+            );
+          }
+          byKid.add(key.kid);
+        }
+        const verifier = createLocalJWKSet({ keys: jwks.keys });
+        this.jwksCache = { raw: jwks.keys, byKid, verifier, fetchedAt: Date.now() };
+      } finally {
+        this.inFlightRefresh = null;
+      }
+    })();
+    return this.inFlightRefresh;
+  }
+  /** @internal Exposed for testing — clears JWKS cache */
+  clearCache() {
+    this.jwksCache = null;
+  }
+};
+
+export {
+  DEFAULT_TOKEN_ISSUER,
+  DEFAULT_TOKEN_AUDIENCE,
+  DEFAULT_CLOCK_TOLERANCE_SECONDS,
+  TokensModule
+};