@iqauth/sdk 2.6.4 → 2.7.0

package/dist/chunk-GLXSIGVS.mjs

@@ -0,0 +1,66 @@
+// src/permissions/wildcard.ts
+var SUFFIX = ".*";
+function wildcardPrefix(pattern) {
+  return pattern.slice(0, -SUFFIX.length);
+}
+function hasPermission(set, id) {
+  if (!id) return false;
+  if (!set) return false;
+  if (id === "*") {
+    for (const entry of set) if (entry === "*") return true;
+    return false;
+  }
+  const queryIsWildcard = id.endsWith(SUFFIX);
+  const queryPrefix = queryIsWildcard ? wildcardPrefix(id) : null;
+  for (const entry of set) {
+    if (!entry) continue;
+    if (entry === "*") return true;
+    if (entry === id) return true;
+    if (entry.endsWith(SUFFIX)) {
+      const prefix = wildcardPrefix(entry);
+      if (!queryIsWildcard) {
+        if (id === prefix) return true;
+        if (id.startsWith(prefix + ".")) return true;
+      } else {
+        if (queryPrefix === prefix) return true;
+        if (queryPrefix !== null && queryPrefix.startsWith(prefix + ".")) return true;
+      }
+    }
+  }
+  return false;
+}
+function expandPermissions(set) {
+  if (!set) return [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of set) {
+    if (typeof raw !== "string" || raw.length === 0) continue;
+    seen.add(raw);
+  }
+  if (seen.has("*")) return ["*"];
+  const wildcards = [];
+  for (const entry of seen) if (entry.endsWith(SUFFIX)) wildcards.push(entry);
+  const out = [];
+  for (const entry of seen) {
+    let covered = false;
+    for (const w of wildcards) {
+      if (w === entry) continue;
+      const prefix = wildcardPrefix(w);
+      if (entry === prefix) {
+        covered = true;
+        break;
+      }
+      if (entry.startsWith(prefix + ".")) {
+        covered = true;
+        break;
+      }
+    }
+    if (!covered) out.push(entry);
+  }
+  out.sort();
+  return out;
+}
+
+export {
+  hasPermission,
+  expandPermissions
+};

package/dist/{chunk-DJIBN2N7.mjs → chunk-GN37E64I.mjs}

@@ -91,7 +91,7 @@ async function buildSignInUrl(manager, opts = {}) {
     returnTo,
     createdAt: Date.now()
   });
-  const url = new URL(opts.signInPath ?? DEFAULT_SIGN_IN_PATH, manager.issuerUrl);
+  const url = new URL(opts.signInPath ?? DEFAULT_SIGN_IN_PATH, manager.hostedIssuerUrl);
   url.searchParams.set("response_type", "code");
   url.searchParams.set("app", manager.appKey);
   url.searchParams.set("publishable_key", manager.publishableKey.raw);
@@ -106,33 +106,50 @@ async function buildSignInUrl(manager, opts = {}) {
   return url.toString();
 }
 async function redirectToSignIn(manager, opts = {}) {
-  const url = await buildSignInUrl(manager, opts);
-  if (typeof window === "undefined") {
-    throw new Error("redirectToSignIn requires a browser environment");
+  const t0 = Date.now();
+  let ok = false;
+  let code;
+  try {
+    const url = await buildSignInUrl(manager, opts);
+    if (typeof window === "undefined") {
+      code = "NO_WINDOW";
+      throw new Error("redirectToSignIn requires a browser environment");
+    }
+    ok = true;
+    manager.recordTiming("signIn", Date.now() - t0, true);
+    window.location.assign(url);
+  } catch (err) {
+    if (!ok) manager.recordTiming("signIn", Date.now() - t0, false, code ?? (err instanceof Error ? err.message : "ERROR"));
+    throw err;
   }
-  window.location.assign(url);
 }
 async function signIn(manager, opts = {}) {
   return redirectToSignIn(manager, opts);
 }
 async function handleAuthCallback(manager, options = {}) {
+  const t0 = Date.now();
+  const emit = (ok, code2) => manager.recordTiming("signIn", Date.now() - t0, ok, code2);
   const url = new URL(options.url ?? (typeof window !== "undefined" ? window.location.href : ""));
   const code = url.searchParams.get("code");
   const state = url.searchParams.get("state");
   const errorParam = url.searchParams.get("error");
   if (errorParam) {
+    emit(false, errorParam);
     return { ok: false, returnTo: "/", error: errorParam };
   }
   if (!code || !state) {
+    emit(false, "missing_code_or_state");
     return { ok: false, returnTo: "/", error: "missing_code_or_state" };
   }
   const record = loadPkce(state);
   if (!record) {
+    emit(false, "unknown_state");
     return { ok: false, returnTo: "/", error: "unknown_state" };
   }
   clearPkce(state);
   const fetchImpl = options.fetchImpl ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : null);
   if (!fetchImpl) {
+    emit(false, "no_fetch");
     return { ok: false, returnTo: record.returnTo, error: "no_fetch" };
   }
   const tokenUrl = `${manager.issuerUrl}${options.tokenPath ?? DEFAULT_TOKEN_PATH}`;
@@ -151,10 +168,12 @@ async function handleAuthCallback(manager, options = {}) {
   const body = await res.json().catch(() => ({}));
   if (!res.ok) {
     const desc = body.error_description ?? body.error ?? "token_exchange_failed";
+    emit(false, desc);
     return { ok: false, returnTo: record.returnTo, error: desc };
   }
   const tokens = body;
   if (!tokens.access_token) {
+    emit(false, "missing_access_token");
     return { ok: false, returnTo: record.returnTo, error: "missing_access_token" };
   }
   if (tokens.refresh_token) {
@@ -162,21 +181,24 @@ async function handleAuthCallback(manager, options = {}) {
     setCookie(cookieName, tokens.refresh_token, { maxAgeSeconds: 60 * 60 * 24 * 30 });
   }
   manager.applyAccessToken(tokens.access_token, tokens.refresh_token);
+  emit(true);
   return { ok: true, returnTo: record.returnTo };
 }
 async function signOut(manager, opts = {}) {
   if (!opts.localOnly) {
     const issuer = manager.issuerUrl.replace(/\/$/, "");
+    const idempotency = manager.getIdempotencyToken();
     try {
       const url = `${issuer}${opts.logoutPath ?? DEFAULT_LOGOUT_PATH}`;
-      await manager.fetch(url, { method: "POST" }).catch(() => void 0);
+      await manager.fetch(url, { method: "POST", headers: { "X-IQAuth-Idempotency": idempotency } }).catch(() => void 0);
     } catch {
     }
     if (opts.endSsoSession !== false) {
       try {
         await fetch(`${issuer}${DEFAULT_SSO_LOGOUT_PATH}`, {
           method: "POST",
-          credentials: "include"
+          credentials: "include",
+          headers: { "X-IQAuth-Idempotency": idempotency }
         }).catch(() => void 0);
       } catch {
       }

package/dist/{chunk-WQWBJSSS.mjs → chunk-HVHNYPDC.mjs}

@@ -1,6 +1,6 @@
 import {
   IQAuthError
-} from "./chunk-6I6RM4MN.mjs";
+} from "./chunk-6PJRLRB4.mjs";
 import {
   __require
 } from "./chunk-Y6FXYEAI.mjs";
@@ -64,14 +64,14 @@ function assertPublishableKey(raw, opts) {
   const ctx = opts?.context ? `${opts.context}: ` : "";
   if (typeof raw !== "string" || raw.length === 0) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key is missing. Set IQAUTH_PUBLISHABLE_KEY (or pass publishableKey) to a pk_test_\u2026 or pk_live_\u2026 value from the IQAuth admin console.`
     );
   }
   const shapeMatch = raw.match(/^pk_(test|live)_([A-Za-z0-9_-]+)$/);
   if (!shapeMatch) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key is malformed (got ${raw.slice(0, 12)}\u2026). Expected pk_test_\u2026 or pk_live_\u2026; regenerate the key from the IQAuth admin console.`
     );
   }
@@ -80,19 +80,19 @@ function assertPublishableKey(raw, opts) {
     decoded = JSON.parse(b64urlDecode(shapeMatch[2]));
   } catch {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key payload is not valid base64url JSON. Regenerate the key from the IQAuth admin console.`
     );
   }
   if (!isPublishableKeyPayload(decoded)) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key payload is missing required fields {iss, appId, tenantId, kid}. Regenerate the key from the IQAuth admin console.`
     );
   }
   if (!isValidIssuerUrl(decoded.iss)) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "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 \u2014 the new key will encode a valid issuer URL.`
     );
   }

package/dist/{chunk-W3F4JYGP.mjs → chunk-JXQI62A7.mjs}

@@ -1,9 +1,9 @@
 import {
   TokensModule
-} from "./chunk-UNYDG2L4.mjs";
+} from "./chunk-NUO2I65G.mjs";
 import {
   IQAuthError
-} from "./chunk-6I6RM4MN.mjs";
+} from "./chunk-6PJRLRB4.mjs";
 
 // src/modules/auth.ts
 function parseLoginResponse(data, browserSessionMode) {
@@ -484,14 +484,14 @@ var OidcModule = class {
    */
   async handleCallback(params) {
     if (!params.state) {
-      throw new IQAuthError("VALIDATION_ERROR", "OIDC callback missing state parameter");
+      throw new IQAuthError("config_invalid", "OIDC callback missing state parameter");
     }
     if (!params.code) {
-      throw new IQAuthError("VALIDATION_ERROR", "OIDC callback missing code parameter");
+      throw new IQAuthError("config_invalid", "OIDC callback missing code parameter");
     }
     const stored = await this.stateStore.get(params.state);
     if (!stored) {
-      throw new IQAuthError("VALIDATION_ERROR", "Unknown or expired OIDC state");
+      throw new IQAuthError("config_invalid", "Unknown or expired OIDC state");
     }
     let tokens;
     try {
@@ -509,7 +509,7 @@ var OidcModule = class {
     if (tokens.id_token) {
       if (!this.tokensModule) {
         throw new IQAuthError(
-          "INTERNAL_ERROR",
+          "config_invalid",
           "OIDC handleCallback received an id_token but no TokensModule is configured for verification"
         );
       }
@@ -520,7 +520,7 @@ var OidcModule = class {
       const tokenNonce = typeof claimsBag.nonce === "string" ? claimsBag.nonce : void 0;
       if (!tokenNonce || tokenNonce !== stored.nonce) {
         throw new IQAuthError(
-          "TOKEN_INVALID",
+          "token_invalid",
           "OIDC id_token nonce did not match the stored value"
         );
       }
@@ -721,6 +721,9 @@ var AppsModule = class {
    * @remarks Wraps GET /api/v1/apps/:appKey
    */
   async get(appKey) {
+    if (typeof appKey !== "string" || appKey.trim() === "") {
+      throw new IQAuthError("VALIDATION_ERROR", "appKey is required (no env-var fallback).", 400);
+    }
     return this.http.request("GET", `/api/v1/apps/${encodeURIComponent(appKey)}`);
   }
   /**
@@ -740,6 +743,16 @@ var AppsModule = class {
         401
       );
     }
+    if (!manifest || typeof manifest.key !== "string" || manifest.key.trim() === "") {
+      throw new IQAuthError("VALIDATION_ERROR", "manifest.key (appKey) is required for register().", 400);
+    }
+    if (!manifest.environment || !["production", "staging", "development"].includes(manifest.environment)) {
+      throw new IQAuthError(
+        "ENVIRONMENT_REQUIRED",
+        "manifest.environment is required and must be 'production', 'staging', or 'development'. This guards against a dev workstation silently overwriting a production app's permission tree.",
+        400
+      );
+    }
     return this.http.request("POST", "/api/v1/apps/sync", manifest);
   }
   /**
@@ -749,11 +762,14 @@ var AppsModule = class {
    * @remarks Uses GET /api/v1/apps/:appKey — catches 404 errors
    */
   async isRegistered(appKey) {
+    if (typeof appKey !== "string" || appKey.trim() === "") {
+      throw new IQAuthError("VALIDATION_ERROR", "appKey is required (no env-var fallback).", 400);
+    }
     try {
       await this.get(appKey);
       return true;
     } catch (err) {
-      if (err.code === "NOT_FOUND" || err.status === 404) {
+      if (err.code === "app_not_found" || err.code === "NOT_FOUND" || err.status === 404) {
         return false;
       }
       throw err;
@@ -790,6 +806,20 @@ var RolesModule = class {
 };
 
 // src/modules/permissionGroups.ts
+function assertAppKey(appKey, callsite) {
+  if (typeof appKey !== "string" || appKey.trim() === "") {
+    throw new IQAuthError(
+      "VALIDATION_ERROR",
+      `appKey is required for ${callsite} (no env-var fallback, no 'product' alias).`,
+      400
+    );
+  }
+}
+function assertNodeKey(nodeKey, callsite) {
+  if (typeof nodeKey !== "string" || nodeKey.trim() === "") {
+    throw new IQAuthError("VALIDATION_ERROR", `nodeKey is required for ${callsite}.`, 400);
+  }
+}
 var PermissionGroupsModule = class {
   constructor(http) {
     this.http = http;
@@ -810,7 +840,14 @@ var PermissionGroupsModule = class {
     return this.http.request("GET", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions`);
   }
   async addPermission(tenantId, groupId, data) {
-    return this.http.request("POST", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions`, data);
+    assertAppKey(data?.appKey, "permissionGroups.addPermission");
+    assertNodeKey(data?.nodeKey, "permissionGroups.addPermission");
+    return this.http.request("POST", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions`, {
+      appKey: data.appKey,
+      nodeKey: data.nodeKey,
+      effect: data.effect,
+      weight: data.weight
+    });
   }
   async removePermission(tenantId, groupId, permissionId) {
     return this.http.request("DELETE", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions/${permissionId}`);
@@ -834,21 +871,51 @@ var PermissionGroupsModule = class {
     return this.http.request("GET", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides`);
   }
   async addUserOverride(tenantId, userId, data) {
-    return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides`, data);
+    assertAppKey(data?.appKey, "permissionGroups.addUserOverride");
+    assertNodeKey(data?.nodeKey, "permissionGroups.addUserOverride");
+    return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides`, {
+      appKey: data.appKey,
+      nodeKey: data.nodeKey,
+      effect: data.effect,
+      weight: data.weight,
+      expiresAt: data.expiresAt
+    });
   }
   async removeUserOverride(tenantId, userId, overrideId) {
     return this.http.request("DELETE", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides/${overrideId}`);
   }
+  /**
+   * Task #130 — `appKey` is REQUIRED. The legacy `product` query alias is no
+   * longer accepted at the SDK boundary; pass it as `appKey` instead. The
+   * server still accepts `product=` from raw HTTP callers during the
+   * deprecation window, but the SDK will not silently translate it.
+   */
   async getEffectivePermissions(tenantId, userId, params) {
-    const query = new URLSearchParams();
-    if (params.product) query.set("product", params.product);
-    if (params.appKey) query.set("appKey", params.appKey);
-    const qs = query.toString();
-    return this.http.request("GET", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/effective${qs ? `?${qs}` : ""}`);
+    assertAppKey(params?.appKey, "permissionGroups.getEffectivePermissions");
+    const qs = new URLSearchParams({ appKey: params.appKey }).toString();
+    return this.http.request("GET", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/effective?${qs}`);
   }
   async checkPermission(tenantId, userId, appKey, nodeKey) {
+    assertAppKey(appKey, "permissionGroups.checkPermission");
+    assertNodeKey(nodeKey, "permissionGroups.checkPermission");
     return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/check`, { appKey, nodeKey });
   }
+  /**
+   * Task #130 — every entry in `checks` must include a non-empty `appKey`
+   * AND `nodeKey`. The SDK validates the whole batch before sending so a
+   * single misconfigured entry can't slip through and silently report
+   * `allowed: false` from the server's per-entry validation branch.
+   */
+  async batchCheckPermissions(tenantId, userId, checks) {
+    if (!Array.isArray(checks) || checks.length === 0) {
+      throw new IQAuthError("VALIDATION_ERROR", "checks must be a non-empty array of { appKey, nodeKey }.", 400);
+    }
+    checks.forEach((c, i) => {
+      assertAppKey(c?.appKey, `permissionGroups.batchCheckPermissions[${i}]`);
+      assertNodeKey(c?.nodeKey, `permissionGroups.batchCheckPermissions[${i}]`);
+    });
+    return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/batch-check`, { checks });
+  }
 };
 
 // src/modules/apiKeys.ts
@@ -1365,7 +1432,7 @@ var HttpClient = class {
           headers: this.buildHeaders(),
           ...this.isBrowserSession() ? { credentials: "include" } : (() => {
             const refreshToken = this.config.getRefreshToken();
-            if (!refreshToken) throw new IQAuthError("TOKEN_INVALID", "No refresh token available");
+            if (!refreshToken) throw new IQAuthError("config_invalid", "No refresh token available");
             return { body: JSON.stringify({ refreshToken }) };
           })()
         });
@@ -1382,7 +1449,7 @@ var HttpClient = class {
           return;
         }
         if (!body.data.accessToken || !body.data.refreshToken) {
-          throw new IQAuthError("TOKEN_INVALID", "Refresh response did not include a token pair");
+          throw new IQAuthError("token_invalid", "Refresh response did not include a token pair");
         }
         const tokens = {
           accessToken: body.data.accessToken,
@@ -1400,7 +1467,7 @@ var HttpClient = class {
     return this.requestWithRetry(method, path, body, options, false);
   }
   async requestWithRetry(method, path, body, options, hasRetried) {
-    if (this.config.autoRefresh && !options?.skipAutoRefresh && !this.isBrowserSession() && this.config.getRefreshToken() && this.isTokenExpiringSoon()) {
+    if (this.config.autoRefresh && this.config.proactiveRefresh !== false && !options?.skipAutoRefresh && !this.isBrowserSession() && this.config.getRefreshToken() && this.isTokenExpiringSoon()) {
       await this.attemptRefresh();
     }
     const url = `${this.config.baseUrl}${path}`;
@@ -1475,6 +1542,10 @@ var IQAuthClient = class _IQAuthClient {
         this._refreshToken = tokens.refreshToken;
       },
       autoRefresh: "autoRefresh" in config ? config.autoRefresh !== false : true,
+      // `'app-state'` is mobile-only — on any other environment we treat it
+      // as the default `true` (proactive refresh ON). Only the mobile client
+      // disables proactive refresh and replaces it with an AppState listener.
+      proactiveRefresh: "autoRefresh" in config && config.autoRefresh === "app-state" && _IQAuthClient.resolveEnvironment(config) === "mobile" ? false : true,
       onTokenRefresh: "onTokenRefresh" in config ? config.onTokenRefresh : void 0,
       sessionHeaderName: config.sessionHeaderName,
       sessionHeaderValue: config.sessionHeaderValue,
@@ -1515,6 +1586,13 @@ var IQAuthClient = class _IQAuthClient {
   static forServer(config) {
     return new _IQAuthClient({ ...config, environment: "server" });
   }
+  /**
+   * Construct a mobile-environment client. NOTE: this constructor does NOT
+   * subscribe to React Native's `AppState` even when `autoRefresh: 'app-state'`
+   * is passed — it only disables the per-request proactive refresh. Use
+   * `createMobileClient` from `@iqauth/sdk/mobile` if you want the full
+   * AppState-driven refresh behavior (recommended for Expo / React Native).
+   */
   static forMobile(config) {
     return new _IQAuthClient({ ...config, environment: "mobile" });
   }
@@ -1531,6 +1609,18 @@ var IQAuthClient = class _IQAuthClient {
   getRefreshToken() {
     return this._refreshToken;
   }
+  /**
+   * Task #126: Eagerly fetch JWKS + OIDC discovery so the first verify() /
+   * refresh round-trip on the request hot path doesn't pay the discovery
+   * fetch latency. Safe to call repeatedly. Errors are swallowed; callers
+   * may fire-and-forget. Called automatically by `iqAuth({...}).attachHelpers()`.
+   */
+  async prewarm() {
+    await Promise.all([
+      this.tokens.prewarm(),
+      this.oidc.getDiscovery().catch(() => void 0)
+    ]);
+  }
   getCurrentClaims() {
     if (!this._accessToken) return null;
     return this.tokens.decode(this._accessToken);

package/dist/{chunk-UNYDG2L4.mjs → chunk-NUO2I65G.mjs}

@@ -1,6 +1,6 @@
 import {
   IQAuthError
-} from "./chunk-6I6RM4MN.mjs";
+} from "./chunk-6PJRLRB4.mjs";
 import {
   __require
 } from "./chunk-Y6FXYEAI.mjs";
@@ -23,6 +23,18 @@ var DEFAULT_TOKEN_AUDIENCE = [
   "iqvalidate"
 ];
 var DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+function classifyJoseError(err) {
+  if (err instanceof joseErrors.JWTExpired) {
+    return { code: "token_expired", message: "Token has expired" };
+  }
+  if (err instanceof joseErrors.JOSEError) {
+    return { code: "token_invalid", message: err.message };
+  }
+  if (err instanceof Error) {
+    return { code: "token_invalid", message: err.message };
+  }
+  return { code: "token_invalid", message: "Token verification failed" };
+}
 function decodeProtectedHeader(token) {
   const parts = token.split(".");
   if (parts.length < 2) return null;
@@ -59,11 +71,11 @@ var TokensModule = class {
   async verify(token, options = {}) {
     const header = decodeProtectedHeader(token);
     if (!header) {
-      throw new IQAuthError("TOKEN_INVALID", "Unable to decode token");
+      throw new IQAuthError("token_invalid", "Unable to decode token");
     }
     const kid = header.kid;
     if (!kid) {
-      throw new IQAuthError("TOKEN_INVALID", "Token missing kid header");
+      throw new IQAuthError("token_invalid", "Token missing kid header");
     }
     let cache = await this.ensureCache();
     if (!cache.byKid.has(kid)) {
@@ -71,7 +83,7 @@ var TokensModule = class {
       cache = await this.ensureCache();
     }
     if (!cache.byKid.has(kid)) {
-      throw new IQAuthError("TOKEN_INVALID", `Unknown key ID: ${kid}`);
+      throw new IQAuthError("token_invalid", `Unknown key ID: ${kid}`);
     }
     const issuer = options.issuer ?? this.defaultIssuer;
     const audience = options.audience ?? this.defaultAudience;
@@ -87,16 +99,8 @@ var TokensModule = class {
       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");
+      const classified = classifyJoseError(err);
+      throw new IQAuthError(classified.code, classified.message, void 0, err);
     }
   }
   /**
@@ -138,7 +142,7 @@ var TokensModule = class {
   getClaims(token) {
     const claims = this.decode(token);
     if (!claims) {
-      throw new IQAuthError("TOKEN_INVALID", "Unable to decode token claims");
+      throw new IQAuthError("token_invalid", "Unable to decode token claims");
     }
     return claims;
   }
@@ -148,7 +152,7 @@ var TokensModule = class {
     }
     await this.refreshJwks();
     if (!this.jwksCache) {
-      throw new IQAuthError("INTERNAL_ERROR", "JWKS cache unavailable after refresh");
+      throw new IQAuthError("jwks_unavailable", "JWKS cache unavailable after refresh");
     }
     return this.jwksCache;
   }
@@ -158,22 +162,38 @@ var TokensModule = class {
     }
     this.inFlightRefresh = (async () => {
       try {
-        const res = await fetch(`${this.baseUrl}/.well-known/jwks.json`);
+        let res;
+        try {
+          res = await fetch(`${this.baseUrl}/.well-known/jwks.json`);
+        } catch (err) {
+          throw new IQAuthError(
+            "network",
+            err instanceof Error ? err.message : "JWKS fetch network error",
+            void 0,
+            err
+          );
+        }
         if (!res.ok) {
           throw new IQAuthError(
-            "INTERNAL_ERROR",
-            `Failed to fetch JWKS: ${res.status}`
+            "jwks_fetch_failed",
+            `Failed to fetch JWKS: ${res.status}`,
+            res.status
           );
         }
         let jwks;
         try {
           jwks = await res.json();
-        } catch {
-          throw new IQAuthError("INTERNAL_ERROR", "Malformed JWKS response: invalid JSON");
+        } catch (err) {
+          throw new IQAuthError(
+            "jwks_fetch_failed",
+            "Malformed JWKS response: invalid JSON",
+            res.status,
+            err
+          );
         }
         if (!jwks || !Array.isArray(jwks.keys)) {
           throw new IQAuthError(
-            "INTERNAL_ERROR",
+            "jwks_fetch_failed",
             "Malformed JWKS response: expected { keys: [...] }"
           );
         }
@@ -181,7 +201,7 @@ var TokensModule = class {
         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",
+              "jwks_fetch_failed",
               "Malformed JWKS response: key missing required fields"
             );
           }
@@ -199,6 +219,19 @@ var TokensModule = class {
   clearCache() {
     this.jwksCache = null;
   }
+  /**
+   * Task #126: Eagerly populate the JWKS cache so the first verify() call
+   * doesn't pay a network round-trip. Safe to call repeatedly — single-flight
+   * behavior is shared with the lazy refresh path. Errors are swallowed so
+   * callers (e.g. `attachHelpers` auto-prewarm) can fire-and-forget.
+   */
+  async prewarm() {
+    if (this.jwksCache && Date.now() - this.jwksCache.fetchedAt <= JWKS_CACHE_TTL_MS) return;
+    try {
+      await this.refreshJwks();
+    } catch {
+    }
+  }
 };
 
 export {