@iqauth/sdk 2.6.3 → 2.7.0

package/dist/webhooks.js

@@ -30,8 +30,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/webhooks.ts
 var webhooks_exports = {};
 __export(webhooks_exports, {
+  IQAUTH_SIGNATURE_HEADER: () => IQAUTH_SIGNATURE_HEADER,
+  LEGACY_SIGNATURE_HEADERS: () => LEGACY_SIGNATURE_HEADERS,
   WebhookSignatureError: () => WebhookSignatureError,
   isValidWebhookSignature: () => isValidWebhookSignature,
+  parseWebhookEvent: () => parseWebhookEvent,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(webhooks_exports);
@@ -43,6 +46,12 @@ var WebhookSignatureError = class extends Error {
     this.code = code;
   }
 };
+var IQAUTH_SIGNATURE_HEADER = "x-iqauth-signature";
+var LEGACY_SIGNATURE_HEADERS = [
+  "x-webhook-signature",
+  "x-iq-auth-signature",
+  "x-signature"
+];
 function toBuffer(p) {
   if (typeof p === "string") return Buffer.from(p, "utf8");
   if (Buffer.isBuffer(p)) return p;
@@ -51,13 +60,19 @@ function toBuffer(p) {
 function parseHeader(header) {
   let t = NaN;
   const v1 = [];
-  for (const part of header.split(",")) {
-    const [k, v] = part.split("=", 2);
-    if (!k || v === void 0) continue;
-    const key = k.trim();
-    const value = v.trim();
+  const trimmed = header.trim();
+  if (/^[0-9a-f]+$/i.test(trimmed)) {
+    v1.push(trimmed.toLowerCase());
+    return { t, v1 };
+  }
+  for (const part of trimmed.split(",")) {
+    const eqIdx = part.indexOf("=");
+    if (eqIdx === -1) continue;
+    const key = part.slice(0, eqIdx).trim().toLowerCase();
+    const value = part.slice(eqIdx + 1).trim();
+    if (!value) continue;
     if (key === "t") t = Number(value);
-    else if (key === "v1") v1.push(value);
+    else if (key === "v1") v1.push(value.toLowerCase());
   }
   return { t, v1 };
 }
@@ -69,6 +84,11 @@ function timingSafeEqualHex(a, b) {
     return false;
   }
 }
+function computeSignatures(secret, body, t) {
+  const modern = import_crypto.default.createHmac("sha256", secret).update(body).digest("hex");
+  const legacy = Number.isFinite(t) ? import_crypto.default.createHmac("sha256", secret).update(`${t}.`).update(body).digest("hex") : null;
+  return { modern, legacy };
+}
 function verifyWebhookSignature(opts) {
   const headerRaw = Array.isArray(opts.header) ? opts.header[0] : opts.header;
   if (!headerRaw || typeof headerRaw !== "string") {
@@ -78,20 +98,27 @@ function verifyWebhookSignature(opts) {
     throw new WebhookSignatureError("MISSING_SECRET", "secret is required");
   }
   const { t, v1 } = parseHeader(headerRaw);
-  if (!Number.isFinite(t) || v1.length === 0) {
+  if (v1.length === 0) {
     throw new WebhookSignatureError("MALFORMED_HEADER", `Could not parse signature header: ${headerRaw}`);
   }
   const tolerance = opts.toleranceSeconds ?? 300;
-  const now = opts.nowSeconds ?? Math.floor(Date.now() / 1e3);
-  if (Math.abs(now - t) > tolerance) {
-    throw new WebhookSignatureError(
-      "TIMESTAMP_OUT_OF_TOLERANCE",
-      `Signature timestamp ${t} is outside the ${tolerance}s tolerance window (now=${now})`
-    );
+  if (Number.isFinite(t)) {
+    const now = opts.nowSeconds ?? Math.floor(Date.now() / 1e3);
+    if (Math.abs(now - t) > tolerance) {
+      throw new WebhookSignatureError(
+        "TIMESTAMP_OUT_OF_TOLERANCE",
+        `Signature timestamp ${t} is outside the ${tolerance}s tolerance window (now=${now})`
+      );
+    }
   }
   const body = toBuffer(opts.payload);
-  const expected = import_crypto.default.createHmac("sha256", opts.secret).update(`${t}.`).update(body).digest("hex");
-  const matched = v1.some((sig) => timingSafeEqualHex(sig, expected));
+  const { modern, legacy } = computeSignatures(opts.secret, body, t);
+  const matched = v1.some((sig) => {
+    const lower = sig.toLowerCase();
+    if (timingSafeEqualHex(lower, modern)) return true;
+    if (legacy && timingSafeEqualHex(lower, legacy)) return true;
+    return false;
+  });
   if (!matched) {
     throw new WebhookSignatureError("SIGNATURE_MISMATCH", "Webhook signature does not match expected value");
   }
@@ -111,9 +138,131 @@ function isValidWebhookSignature(opts) {
     return false;
   }
 }
+function readHeader(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name);
+  }
+  const lower = name.toLowerCase();
+  const obj = headers;
+  if (lower in obj) return obj[lower];
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.toLowerCase() === lower) return v;
+  }
+  return void 0;
+}
+function pickHeaderValue(value) {
+  if (value == null) return null;
+  if (Array.isArray(value)) return value[0] ?? null;
+  return value;
+}
+function envelopeError(message) {
+  throw new WebhookSignatureError("MALFORMED_ENVELOPE", message);
+}
+function parseWebhookEvent(rawBody, headers, secrets, opts = {}) {
+  if (!Array.isArray(secrets) || secrets.length === 0 || secrets.every((s) => !s)) {
+    throw new WebhookSignatureError("MISSING_SECRET", "At least one signing secret is required");
+  }
+  let headerValue = pickHeaderValue(readHeader(headers, IQAUTH_SIGNATURE_HEADER));
+  let usedHeader = IQAUTH_SIGNATURE_HEADER;
+  if (!headerValue) {
+    for (const legacy of LEGACY_SIGNATURE_HEADERS) {
+      const v = pickHeaderValue(readHeader(headers, legacy));
+      if (v) {
+        headerValue = v;
+        usedHeader = legacy;
+        const log = opts.onDeprecation ?? ((m) => console.warn(m));
+        log(
+          `[iqauth] deprecation: webhook delivery used legacy header "${legacy}"; migrate sender to "X-IQAuth-Signature" (back-compat removed in next minor).`
+        );
+        break;
+      }
+    }
+  }
+  if (!headerValue) {
+    throw new WebhookSignatureError(
+      "MISSING_HEADER",
+      `Missing webhook signature header. Expected "X-IQAuth-Signature" (or one of: ${LEGACY_SIGNATURE_HEADERS.join(", ")}).`
+    );
+  }
+  const { t, v1 } = parseHeader(headerValue);
+  if (v1.length === 0) {
+    throw new WebhookSignatureError(
+      "MALFORMED_HEADER",
+      `Could not parse "${usedHeader}" header value: ${headerValue}`
+    );
+  }
+  const body = toBuffer(rawBody);
+  let verifiedIdx = -1;
+  for (let i = 0; i < secrets.length; i++) {
+    const secret = secrets[i];
+    if (!secret) continue;
+    const { modern, legacy } = computeSignatures(secret, body, t);
+    const ok = v1.some((sig) => {
+      const lower = sig.toLowerCase();
+      if (timingSafeEqualHex(lower, modern)) return true;
+      if (legacy && timingSafeEqualHex(lower, legacy)) return true;
+      return false;
+    });
+    if (ok) {
+      verifiedIdx = i;
+      break;
+    }
+  }
+  if (verifiedIdx === -1) {
+    throw new WebhookSignatureError(
+      "SIGNATURE_MISMATCH",
+      "Webhook signature does not match any provided secret"
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body.toString("utf8"));
+  } catch {
+    throw new WebhookSignatureError("MALFORMED_BODY", "Webhook body is not valid JSON");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    envelopeError("Webhook body must be a JSON object");
+  }
+  const { id, type, subject, time, data, tenantId, specversion } = parsed;
+  if (specversion !== "1.0") {
+    envelopeError(`Envelope \`specversion\` must be "1.0" (got: ${JSON.stringify(specversion)})`);
+  }
+  if (typeof id !== "string" || !id) envelopeError("Envelope missing required string `id`");
+  if (typeof type !== "string" || !type) envelopeError("Envelope missing required string `type`");
+  if (typeof subject !== "string" || !subject) envelopeError("Envelope missing required string `subject`");
+  if (typeof time !== "string" || !time) envelopeError("Envelope missing required string `time`");
+  if (typeof tenantId !== "string" || !tenantId) envelopeError("Envelope missing required string `tenantId`");
+  if (data === void 0 || data === null || typeof data !== "object" || Array.isArray(data)) {
+    envelopeError("Envelope `data` must be an object");
+  }
+  const tolerance = opts.toleranceSeconds ?? 300;
+  const eventMs = Date.parse(time);
+  if (!Number.isFinite(eventMs)) envelopeError(`Envelope \`time\` is not a valid ISO timestamp: ${time}`);
+  const nowMs = opts.nowMs ?? Date.now();
+  if (Math.abs(nowMs - eventMs) > tolerance * 1e3) {
+    throw new WebhookSignatureError(
+      "TIMESTAMP_OUT_OF_TOLERANCE",
+      `Envelope time ${time} is outside the ${tolerance}s tolerance window (now=${new Date(nowMs).toISOString()})`
+    );
+  }
+  return {
+    specversion: "1.0",
+    id,
+    type,
+    subject,
+    time,
+    tenantId,
+    data,
+    idempotencyKey: id,
+    verifiedWithSecretIndex: verifiedIdx
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  IQAUTH_SIGNATURE_HEADER,
+  LEGACY_SIGNATURE_HEADERS,
   WebhookSignatureError,
   isValidWebhookSignature,
+  parseWebhookEvent,
   verifyWebhookSignature
 });

package/dist/webhooks.mjs

@@ -1,11 +1,17 @@
 import {
+  IQAUTH_SIGNATURE_HEADER,
+  LEGACY_SIGNATURE_HEADERS,
   WebhookSignatureError,
   isValidWebhookSignature,
+  parseWebhookEvent,
   verifyWebhookSignature
-} from "./chunk-UKZLOHZG.mjs";
+} from "./chunk-PMAFENVI.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 export {
+  IQAUTH_SIGNATURE_HEADER,
+  LEGACY_SIGNATURE_HEADERS,
   WebhookSignatureError,
   isValidWebhookSignature,
+  parseWebhookEvent,
   verifyWebhookSignature
 };

package/dist/ws.d.mts

@@ -1,5 +1,5 @@
-import { c as TokenVerifyOptions } from './tokens-DCyzzn8L.mjs';
-import { J as JwtClaims } from './types-DZAflmmq.mjs';
+import { c as TokenVerifyOptions } from './tokens-CITeoG6P.mjs';
+import { J as JwtClaims } from './types-XOV9XPVi.mjs';
 
 /**
  * @iqauth/sdk/ws — WebSocket upgrade auth helper.

package/dist/ws.d.ts

@@ -1,5 +1,5 @@
-import { c as TokenVerifyOptions } from './tokens-aHiGFr_E.js';
-import { J as JwtClaims } from './types-DZAflmmq.js';
+import { c as TokenVerifyOptions } from './tokens-Bqhmqq_R.js';
+import { J as JwtClaims } from './types-XOV9XPVi.js';
 
 /**
  * @iqauth/sdk/ws — WebSocket upgrade auth helper.

package/dist/ws.js

@@ -29,13 +29,30 @@ module.exports = __toCommonJS(ws_exports);
 var import_jose = require("jose");
 
 // src/errors.ts
-var IQAuthError = class extends Error {
-  constructor(code, message, status, raw) {
+var IQAuthError = class _IQAuthError extends Error {
+  constructor(code, message, status, cause) {
     super(message);
     this.name = "IQAuthError";
     this.code = code;
     this.status = status;
-    this.raw = raw;
+    this.cause = cause;
+    this.raw = cause;
+  }
+  /**
+   * Type guard: true when `value` is an `IQAuthError`. Useful for adapters
+   * that round-trip errors through `unknown` (e.g. fastify's `setErrorHandler`).
+   */
+  static isIQAuthError(value) {
+    return value instanceof _IQAuthError || typeof value === "object" && value !== null && value.name === "IQAuthError" && typeof value.code === "string";
+  }
+  /**
+   * Type-narrowed code check. Lets callers write
+   * `if (err.is("token_expired")) …` with full IntelliSense for the typed
+   * taxonomy without losing the ability to handle server codes via
+   * `err.code === "TOKEN_REVOKED"`.
+   */
+  is(code) {
+    return this.code === code;
   }
 };
 
@@ -52,6 +69,18 @@ var DEFAULT_TOKEN_AUDIENCE = [
   "iqvalidate"
 ];
 var DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+function classifyJoseError(err) {
+  if (err instanceof import_jose.errors.JWTExpired) {
+    return { code: "token_expired", message: "Token has expired" };
+  }
+  if (err instanceof import_jose.errors.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;
@@ -88,11 +117,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)) {
@@ -100,7 +129,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;
@@ -116,16 +145,8 @@ var TokensModule = class {
       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) {
-        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);
     }
   }
   /**
@@ -167,7 +188,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;
   }
@@ -177,7 +198,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;
   }
@@ -187,22 +208,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: [...] }"
           );
         }
@@ -210,7 +247,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"
             );
           }
@@ -228,6 +265,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 {
+    }
+  }
 };
 
 // src/publishableKey.ts
@@ -259,14 +309,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.`
     );
   }
@@ -275,19 +325,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/ws.mjs

@@ -1,10 +1,10 @@
 import {
   _resetWsVerifierCache,
   verifyWsUpgrade
-} from "./chunk-3JULWS6F.mjs";
-import "./chunk-WQWBJSSS.mjs";
-import "./chunk-UNYDG2L4.mjs";
-import "./chunk-6I6RM4MN.mjs";
+} from "./chunk-WCELYTJ3.mjs";
+import "./chunk-HVHNYPDC.mjs";
+import "./chunk-NUO2I65G.mjs";
+import "./chunk-6PJRLRB4.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 export {
   _resetWsVerifierCache,

package/docs/error-handling.md

@@ -0,0 +1,101 @@
+# Error handling (`@iqauth/sdk` ≥ 2.7.0)
+
+The SDK throws a single error class — `IQAuthError` — with a normalized
+`code` field that you can pattern-match exhaustively.
+
+## The taxonomy
+
+```ts
+import { IQAuthError, type IQAuthErrorCode } from "@iqauth/sdk";
+
+type IQAuthErrorCode =
+  | "token_expired"        // jwtVerify said the token is past `exp`
+  | "token_invalid"        // bad signature, wrong issuer/audience, malformed JWT
+  | "jwks_unavailable"     // local JWKS cache could not be populated
+  | "jwks_fetch_failed"    // issuer responded but JWKS payload was bad / non-2xx
+  | "rate_limited"         // upstream returned 429 (server-originated)
+  | "network"              // DNS, TCP, TLS, abort — issuer is unreachable
+  | "config_invalid"       // publishable key / SDK config is malformed
+  | "app_not_found"        // app id/key in the publishable key isn't recognized
+  | "permission_denied"    // claims valid but caller lacks the required scope
+  | "unknown";             // catch-all
+```
+
+Use `IQAuthError.isIQAuthError(value)` for the type guard, and `err.is(code)`
+for narrowed code checks:
+
+```ts
+import { IQAuthError } from "@iqauth/sdk";
+
+try {
+  const claims = await client.tokens.verify(accessToken);
+} catch (err) {
+  if (!IQAuthError.isIQAuthError(err)) throw err;
+
+  if (err.is("token_expired"))     return refreshAndRetry();
+  if (err.is("token_invalid"))     return signOut();
+  if (err.is("jwks_fetch_failed")) return retryAfterBackoff();
+  if (err.is("network"))           return showOfflineBanner();
+  // …
+}
+```
+
+## Backwards compatibility
+
+`IQAuthError.code` is typed as `IQAuthErrorCode | (string & {})` — the
+`(string & {})` widens the union to "any string" while preserving
+auto-complete for the typed values. This matters because:
+
+- **Server-originated errors** (rethrown from `/oidc/token`, `/api/v1/...`,
+  the SAML endpoints, etc.) keep their UPPER_SNAKE codes (`TOKEN_REVOKED`,
+  `MFA_INVALID_CODE`, `SESSION_EXPIRED_INACTIVITY`, …). The SDK does not
+  rewrite them — they are passed through verbatim.
+- **Framework adapters** (`@iqauth/sdk/express`, `/fastify`, `/hono`) map
+  *both* the legacy UPPER_SNAKE codes and the new lowercase typed codes to
+  401, so apps that have a `case "TOKEN_EXPIRED"` switch keep working.
+- **`err.cause`** preserves the originating error (e.g. the underlying
+  `JOSEError` from `jose`, or the `TypeError` from `fetch`). The legacy
+  `err.raw` alias is still populated.
+
+If you only catch `Error`, nothing in your code needs to change. If you
+were string-matching on `err.message`, switch to `err.is("…")`.
+
+## Where each code is thrown
+
+| Code | Throw site |
+| --- | --- |
+| `token_expired` | `tokens.verify` — jose raises `JWTExpired` |
+| `token_invalid` | `tokens.verify` — bad sig / wrong iss / wrong aud / unknown kid / malformed header / `tokens.getClaims` on undecodable input; `oidc.handleCallback` — id_token nonce mismatch; `http.ts` refresh — server returned a malformed token pair |
+| `jwks_unavailable` | `tokens.verify` — JWKS cache still empty after refresh |
+| `jwks_fetch_failed` | `tokens.verify` — JWKS endpoint returned non-2xx, invalid JSON, or a malformed JWKS shape |
+| `network` | `tokens.verify` — `fetch()` itself rejected (DNS, TLS, abort) |
+| `rate_limited` | Reserved for future SDK-side throttling; today this code only appears on server-rethrown 429s |
+| `config_invalid` | `assertPublishableKey()` — bad shape, bad version, missing fields; `oidc.handleCallback` — missing/unknown `state` or `code`, or no `TokensModule` wired up; `http.ts` refresh — caller didn't provide a refresh token |
+| `app_not_found` | Reserved for future use — today the server returns `APP_NOT_FOUND` and the SDK passes it through |
+| `permission_denied` | Reserved for SDK-side scope checks — today the server returns `INSUFFICIENT_PERMISSIONS` |
+| `unknown` | Catch-all |
+
+## Typed claims via `verify<T>()`
+
+`tokens.verify<T>()` is generic over your app's custom JWT-template claims
+and returns `IQAuthClaims<T> & JwtClaims`:
+
+```ts
+import type { IQAuthClaims } from "@iqauth/sdk";
+
+interface MyClaims {
+  plan: "free" | "pro";
+  orgId: string;
+}
+
+const claims = await client.tokens.verify<MyClaims>(accessToken);
+//    ^? IQAuthClaims<MyClaims> & JwtClaims
+
+if (claims.plan === "pro") doProThing(claims.orgId);
+console.log(claims.tenantId, claims.sub); // standard fields still typed
+```
+
+`IQAuthClaims<T>` documents the OIDC standard fields the issuer guarantees
+(`sub`, `iss`, `aud`, `exp`, `iat`) plus IQAuth tenant/vendor/role/session
+claims as optional. The `[key: string]: unknown` index signature lets
+custom claims through at runtime even when no generic is supplied.