@iqauth/sdk 2.6.3 → 2.7.0

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 {

package/dist/chunk-PMAFENVI.mjs

@@ -0,0 +1,229 @@
+// src/webhooks.ts
+import crypto from "crypto";
+var WebhookSignatureError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "WebhookSignatureError";
+    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;
+  return Buffer.from(p);
+}
+function parseHeader(header) {
+  let t = NaN;
+  const v1 = [];
+  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.toLowerCase());
+  }
+  return { t, v1 };
+}
+function timingSafeEqualHex(a, b) {
+  if (a.length !== b.length) return false;
+  try {
+    return crypto.timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+  } catch {
+    return false;
+  }
+}
+function computeSignatures(secret, body, t) {
+  const modern = crypto.createHmac("sha256", secret).update(body).digest("hex");
+  const legacy = Number.isFinite(t) ? crypto.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") {
+    throw new WebhookSignatureError("MISSING_HEADER", "Missing X-IQAuth-Signature header");
+  }
+  if (!opts.secret) {
+    throw new WebhookSignatureError("MISSING_SECRET", "secret is required");
+  }
+  const { t, v1 } = parseHeader(headerRaw);
+  if (v1.length === 0) {
+    throw new WebhookSignatureError("MALFORMED_HEADER", `Could not parse signature header: ${headerRaw}`);
+  }
+  const tolerance = opts.toleranceSeconds ?? 300;
+  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 { 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");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body.toString("utf8"));
+  } catch {
+    throw new WebhookSignatureError("MALFORMED_BODY", "Webhook body is not valid JSON");
+  }
+  return parsed;
+}
+function isValidWebhookSignature(opts) {
+  try {
+    verifyWebhookSignature(opts);
+    return true;
+  } catch {
+    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
+  };
+}
+
+export {
+  WebhookSignatureError,
+  IQAUTH_SIGNATURE_HEADER,
+  LEGACY_SIGNATURE_HEADERS,
+  verifyWebhookSignature,
+  isValidWebhookSignature,
+  parseWebhookEvent
+};