@iqauth/sdk 2.3.0 → 2.6.0

package/dist/ws.js

@@ -0,0 +1,397 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/ws.ts
+var ws_exports = {};
+__export(ws_exports, {
+  _resetWsVerifierCache: () => _resetWsVerifierCache,
+  verifyWsUpgrade: () => verifyWsUpgrade
+});
+module.exports = __toCommonJS(ws_exports);
+
+// src/modules/tokens.ts
+var import_jose = require("jose");
+
+// src/errors.ts
+var IQAuthError = class extends Error {
+  constructor(code, message, status, raw) {
+    super(message);
+    this.name = "IQAuthError";
+    this.code = code;
+    this.status = status;
+    this.raw = raw;
+  }
+};
+
+// src/modules/tokens.ts
+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: 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;
+    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 (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");
+    }
+  }
+  /**
+   * 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: 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. */
+  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 = (0, import_jose.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;
+  }
+};
+
+// src/publishableKey.ts
+function b64urlDecode(input) {
+  const pad = input.length % 4 === 0 ? "" : "=".repeat(4 - input.length % 4);
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/") + pad;
+  if (typeof atob === "function") {
+    const bin = atob(normalized);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+  }
+  const { Buffer: Buffer2 } = require("buffer");
+  return Buffer2.from(normalized, "base64").toString("utf8");
+}
+function isValidIssuerUrl(iss) {
+  if (typeof iss !== "string" || iss.length === 0) return false;
+  if (!iss.startsWith("http://") && !iss.startsWith("https://")) return false;
+  try {
+    const u = new URL(iss);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return false;
+    if (!u.hostname) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+function assertPublishableKey(raw, opts) {
+  const ctx = opts?.context ? `${opts.context}: ` : "";
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new IQAuthError(
+      "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",
+      `${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.`
+    );
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(b64urlDecode(shapeMatch[2]));
+  } catch {
+    throw new IQAuthError(
+      "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",
+      `${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",
+      `${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 };
+}
+function isPublishableKeyPayload(value) {
+  if (!value || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.iss === "string" && typeof v.appId === "string" && typeof v.tenantId === "string" && typeof v.kid === "string";
+}
+
+// src/ws.ts
+var DEFAULT_COOKIE = "iqauth_at";
+var DEFAULT_SUBPROTOCOL_PREFIX = "iqauth.bearer.";
+var JWT_SHAPE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+var tokensByIssuer = /* @__PURE__ */ new Map();
+function getTokens(issuer) {
+  let mod = tokensByIssuer.get(issuer);
+  if (!mod) {
+    mod = new TokensModule(issuer);
+    tokensByIssuer.set(issuer, mod);
+  }
+  return mod;
+}
+function firstHeader(value) {
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+function readCookie(cookieHeader, name) {
+  if (!cookieHeader) return void 0;
+  const target = `${name}=`;
+  for (const seg of cookieHeader.split(";")) {
+    const t = seg.trim();
+    if (t.startsWith(target)) {
+      try {
+        return decodeURIComponent(t.slice(target.length));
+      } catch {
+        return t.slice(target.length);
+      }
+    }
+  }
+  return void 0;
+}
+function extractToken(req, cookieName, subprotocolPrefix) {
+  let authHeader;
+  let cookieHeader;
+  let subprotoHeader;
+  if ("headers" in req && req.headers && typeof req.headers === "object") {
+    authHeader = firstHeader(req.headers.authorization);
+    cookieHeader = firstHeader(req.headers.cookie);
+    subprotoHeader = firstHeader(req.headers["sec-websocket-protocol"]);
+  } else {
+    const r = req;
+    authHeader = r.authorization;
+    cookieHeader = r.cookie;
+    subprotoHeader = r.secWebSocketProtocol;
+  }
+  if (authHeader && /^Bearer /i.test(authHeader)) {
+    return authHeader.slice(7).trim();
+  }
+  if (cookieName && cookieHeader) {
+    const fromCookie = readCookie(cookieHeader, cookieName);
+    if (fromCookie) return fromCookie;
+  }
+  if (subprotocolPrefix !== null && subprotoHeader) {
+    const protos = subprotoHeader.split(",").map((s) => s.trim()).filter(Boolean);
+    for (const proto of protos) {
+      if (subprotocolPrefix && proto.startsWith(subprotocolPrefix)) {
+        return proto.slice(subprotocolPrefix.length);
+      }
+      if (JWT_SHAPE.test(proto)) return proto;
+    }
+  }
+  return void 0;
+}
+async function verifyWsUpgrade(req, options) {
+  const parsed = assertPublishableKey(options.publishableKey, {
+    context: "@iqauth/sdk/ws"
+  });
+  const issuer = (options.issuer && typeof options.issuer === "string" ? options.issuer : parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`).replace(/\/+$/, "");
+  const cookieName = options.cookieName === void 0 ? DEFAULT_COOKIE : options.cookieName;
+  const subprotocolPrefix = options.subprotocolPrefix === void 0 ? DEFAULT_SUBPROTOCOL_PREFIX : options.subprotocolPrefix;
+  const token = extractToken(req, cookieName, subprotocolPrefix);
+  if (!token) return null;
+  const tokens = getTokens(issuer);
+  try {
+    const verifyOpts = {};
+    if (options.audience !== void 0) verifyOpts.audience = options.audience;
+    verifyOpts.issuer = options.issuer ?? issuer;
+    if (options.clockTolerance !== void 0)
+      verifyOpts.clockTolerance = options.clockTolerance;
+    if (options.algorithms !== void 0) verifyOpts.algorithms = options.algorithms;
+    const claims = await tokens.verify(token, verifyOpts);
+    return { claims };
+  } catch (err) {
+    if (err instanceof IQAuthError) return null;
+    return null;
+  }
+}
+function _resetWsVerifierCache() {
+  tokensByIssuer.clear();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  _resetWsVerifierCache,
+  verifyWsUpgrade
+});

package/dist/ws.mjs

@@ -0,0 +1,12 @@
+import {
+  _resetWsVerifierCache,
+  verifyWsUpgrade
+} from "./chunk-3JULWS6F.mjs";
+import "./chunk-WQWBJSSS.mjs";
+import "./chunk-UNYDG2L4.mjs";
+import "./chunk-6I6RM4MN.mjs";
+import "./chunk-Y6FXYEAI.mjs";
+export {
+  _resetWsVerifierCache,
+  verifyWsUpgrade
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iqauth/sdk",
-  "version": "2.3.0",
+  "version": "2.6.0",
   "description": "TypeScript SDK for IQAuth — the canonical way for all IQ projects to integrate with IQAuthService",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -68,6 +68,26 @@
       "types": "./dist/service.d.ts",
       "import": "./dist/service.mjs",
       "require": "./dist/service.js"
+    },
+    "./ws": {
+      "types": "./dist/ws.d.ts",
+      "import": "./dist/ws.mjs",
+      "require": "./dist/ws.js"
+    },
+    "./test": {
+      "types": "./dist/test.d.ts",
+      "import": "./dist/test.mjs",
+      "require": "./dist/test.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.ts",
+      "import": "./dist/webhooks.mjs",
+      "require": "./dist/webhooks.js"
+    },
+    "./locales": {
+      "types": "./dist/locales.d.ts",
+      "import": "./dist/locales.mjs",
+      "require": "./dist/locales.js"
     }
   },
   "files": [
@@ -76,7 +96,7 @@
     "docs"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/browser-session.ts src/browser.ts src/react.ts src/server.ts src/server/handlers.ts src/express.ts src/fastify.ts src/hono.ts src/next.ts src/mobile.ts src/service.ts src/cli/index.ts --format cjs,esm --dts --clean --external react --external react-dom --external next/headers",
+    "build": "tsup src/index.ts src/browser-session.ts src/browser.ts src/react.ts src/server.ts src/server/handlers.ts src/express.ts src/fastify.ts src/hono.ts src/next.ts src/mobile.ts src/service.ts src/ws.ts src/test.ts src/webhooks.ts src/locales.ts src/cli/index.ts --format cjs,esm --dts --clean --external react --external react-dom --external next/headers",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",

package/dist/doctor-A5E7LSFW.mjs

@@ -1,90 +0,0 @@
-import {
-  loadEnv,
-  parseFlags,
-  symbol
-} from "./chunk-X3K3WOBR.mjs";
-import {
-  parsePublishableKey
-} from "./chunk-WQWBJSSS.mjs";
-import "./chunk-6I6RM4MN.mjs";
-import "./chunk-Y6FXYEAI.mjs";
-
-// src/cli/doctor.ts
-async function runDoctor(argv) {
-  const { flags } = parseFlags(argv);
-  const envFile = flags.get("env-file") || ".env";
-  const env = await loadEnv(envFile);
-  const probes = [];
-  const pkRaw = env.IQAUTH_PUBLISHABLE_KEY;
-  const issuerEnv = env.IQAUTH_ISSUER;
-  const redirect = env.IQAUTH_REDIRECT_URI;
-  probes.push({
-    name: ".env present",
-    ok: !!pkRaw,
-    detail: pkRaw ? `${envFile} loaded; IQAUTH_PUBLISHABLE_KEY=${pkRaw.slice(0, 10)}\u2026` : `IQAUTH_PUBLISHABLE_KEY missing in ${envFile}`
-  });
-  const parsed = pkRaw ? parsePublishableKey(pkRaw) : null;
-  probes.push({
-    name: "publishable key parses",
-    ok: !!parsed,
-    detail: parsed ? `mode=${parsed.mode} appId=${parsed.appId} tenantId=${parsed.tenantId} kid=${parsed.kid}` : "key did not match pk_<test|live>_<base64> format"
-  });
-  const issuer = (issuerEnv || (parsed?.iss.startsWith("http") ? parsed.iss : parsed ? `https://${parsed.iss}` : "")).replace(/\/+$/, "");
-  if (issuer) {
-    try {
-      const res = await fetch(`${issuer}/.well-known/openid-configuration`);
-      probes.push({
-        name: "issuer reachable",
-        ok: res.ok,
-        detail: `${issuer}/.well-known/openid-configuration \u2192 ${res.status}`
-      });
-    } catch (err) {
-      probes.push({
-        name: "issuer reachable",
-        ok: false,
-        detail: `fetch failed: ${err.message}`
-      });
-    }
-  } else {
-    probes.push({ name: "issuer reachable", ok: false, detail: "issuer URL unknown (no IQAUTH_ISSUER and no key)" });
-  }
-  if (issuer) {
-    try {
-      const res = await fetch(`${issuer}/.well-known/jwks.json`);
-      const json = await res.json().catch(() => ({}));
-      const keys = json.keys;
-      probes.push({
-        name: "JWKS reachable",
-        ok: res.ok && Array.isArray(keys) && keys.length > 0,
-        detail: `${issuer}/.well-known/jwks.json \u2192 ${res.status} (${Array.isArray(keys) ? keys.length : 0} keys)`
-      });
-    } catch (err) {
-      probes.push({ name: "JWKS reachable", ok: false, detail: `fetch failed: ${err.message}` });
-    }
-  }
-  if (redirect) {
-    try {
-      const res = await fetch(redirect, { method: "GET" });
-      probes.push({
-        name: "redirect URI reachable",
-        ok: res.status > 0 && res.status < 500,
-        detail: `${redirect} \u2192 ${res.status}`
-      });
-    } catch (err) {
-      probes.push({ name: "redirect URI reachable", ok: false, detail: `fetch failed: ${err.message}` });
-    }
-  } else {
-    probes.push({ name: "redirect URI reachable", ok: false, detail: "IQAUTH_REDIRECT_URI not set" });
-  }
-  let allOk = true;
-  for (const p of probes) {
-    console.log(`${symbol(p.ok)} ${p.name.padEnd(28)} ${p.detail}`);
-    if (!p.ok) allOk = false;
-  }
-  console.log("");
-  console.log(allOk ? "\u2705 All checks passed." : "\u274C One or more checks failed \u2014 see above.");
-  process.exit(allOk ? 0 : 1);
-}
-export {
-  runDoctor
-};