@iqauth/sdk 2.1.0 → 2.2.0

package/README.md

@@ -56,18 +56,34 @@ Create both in one call from the admin Quickstart wizard, or run `npx iqauth ini
 ### React (browser)
 
 ```tsx
-import { IQAuthProvider, SignedIn, SignedOut, RedirectToSignIn } from "@iqauth/sdk/react";
+import {
+  IQAuthProvider,
+  IQAuthLoading,
+  IQAuthLoaded,
+  SignedIn,
+  SignedOut,
+  RedirectToSignIn,
+} from "@iqauth/sdk/react";
 
 export default function App() {
   return (
     <IQAuthProvider publishableKey={import.meta.env.VITE_IQAUTH_PUBLISHABLE_KEY}>
-      <SignedIn><Dashboard /></SignedIn>
-      <SignedOut><RedirectToSignIn /></SignedOut>
+      <IQAuthLoading><Spinner /></IQAuthLoading>
+      <IQAuthLoaded>
+        <SignedIn><Dashboard /></SignedIn>
+        <SignedOut><RedirectToSignIn /></SignedOut>
+      </IQAuthLoaded>
     </IQAuthProvider>
   );
 }
 ```
 
+Wrapping the gating components in `<IQAuthLoading/>` / `<IQAuthLoaded/>` is
+the slow-network-safe pattern: until `bootstrap()` finishes, both
+`<SignedIn/>` and `<SignedOut/>` render `null`, which on a slow mobile
+connection is several seconds of blank page. The loading slot fills that
+gap, mirroring Clerk's `<ClerkLoading/>` / `<ClerkLoaded/>`.
+
 Available hooks: `useUser()`, `useSession()`, `useAuth()`, `useOrganization()`. Each returns `{ data, isLoading, error }`.
 Drop-in components: `<SignIn/>`, `<SignUp/>`, `<UserButton/>`, `<UserProfile/>`, `<OrganizationSwitcher/>`, `<AuthCallback/>`.
 

package/dist/browser.d.mts

@@ -1,5 +1,5 @@
-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-CEMdUAwd.mjs';
-export { K as KeyMode, b as ParsedPublishableKey, P as PublishableKeyPayload, e as encodePublishableKey, i as isPublishableKey, a as isSecretKey, p as parsePublishableKey } from './publishableKey-B5DIK81A.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-D_kP3v-c.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,5 +1,5 @@
-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-VRNzlNyG.js';
-export { K as KeyMode, b as ParsedPublishableKey, P as PublishableKeyPayload, e as encodePublishableKey, i as isPublishableKey, a as isSecretKey, p as parsePublishableKey } from './publishableKey-B5DIK81A.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-BVDTIA_t.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

@@ -116,6 +116,18 @@ function encodePublishableKey(mode, payload) {
   if (mode !== "test" && mode !== "live") throw new Error(`Invalid mode: ${mode}`);
   return `pk_${mode}_${b64urlEncode(JSON.stringify(payload))}`;
 }
+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 parsePublishableKey(raw) {
   if (typeof raw !== "string") return null;
   const m = raw.match(/^pk_(test|live)_([A-Za-z0-9_-]+)$/);
@@ -126,11 +138,55 @@ function parsePublishableKey(raw) {
     if (typeof json.iss !== "string" || typeof json.appId !== "string" || typeof json.tenantId !== "string" || typeof json.kid !== "string") {
       return null;
     }
+    if (!isValidIssuerUrl(json.iss)) return null;
     return { mode: m[1], iss: json.iss, appId: json.appId, tenantId: json.tenantId, kid: json.kid, raw };
   } catch {
     return null;
   }
 }
+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, or set IQAUTH_ISSUER to the correct issuer URL as a temporary workaround.`
+    );
+  }
+  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";
+}
 function isPublishableKey(raw) {
   return typeof raw === "string" && /^pk_(test|live)_/.test(raw);
 }
@@ -258,12 +314,7 @@ var SessionManager = class {
     this.remoteRefreshWaiters = [];
     /** Active claims by other tabs (keyed by source tabId). */
     this.foreignClaim = null;
-    const parsed = parsePublishableKey(options.publishableKey);
-    if (!parsed) {
-      throw new Error(
-        `Invalid IQAuth publishable key. Expected pk_test_\u2026 or pk_live_\u2026 (got ${options.publishableKey?.slice(0, 12) ?? "<empty>"}\u2026).`
-      );
-    }
+    const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/browser SessionManager" });
     this.key = parsed;
     const inferred = options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`);
     this.issuer = inferred.replace(/\/+$/, "");

package/dist/browser.mjs

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

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

@@ -1,6 +1,6 @@
 import {
-  parsePublishableKey
-} from "./chunk-5WFR6Y33.mjs";
+  assertPublishableKey
+} from "./chunk-QEJB7WEQ.mjs";
 import {
   IQAuthClient
 } from "./chunk-MDUHPQMM.mjs";
@@ -44,10 +44,7 @@ function readCookie(req, name) {
   return void 0;
 }
 function clientFromPublishableKey(opts) {
-  const parsed = parsePublishableKey(opts.publishableKey);
-  if (!parsed) {
-    throw new Error("iqAuthMiddleware: invalid publishable key");
-  }
+  const parsed = assertPublishableKey(opts.publishableKey, { context: "iqAuthMiddleware" });
   const issuer = (opts.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   return new IQAuthClient({ baseUrl: issuer, environment: "server" });
 }

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

@@ -1,6 +1,6 @@
 import {
-  parsePublishableKey
-} from "./chunk-5WFR6Y33.mjs";
+  assertPublishableKey
+} from "./chunk-QEJB7WEQ.mjs";
 
 // src/server/handlers.ts
 var TERMINAL_REFRESH_ERROR_CODES = /* @__PURE__ */ new Set([
@@ -22,12 +22,7 @@ function shouldClearCookiesOnFailure(policy, status, errorCode) {
 var ACCESS_TOKEN_TTL_SECONDS = 60 * 15;
 var REFRESH_TOKEN_TTL_SECONDS = 60 * 60 * 24 * 30;
 function resolve(config) {
-  const parsed = parsePublishableKey(config.publishableKey);
-  if (!parsed) {
-    throw new Error(
-      "@iqauth/sdk: invalid publishable key passed to iqAuth helpers (expected pk_test_\u2026 or pk_live_\u2026)"
-    );
-  }
+  const parsed = assertPublishableKey(config.publishableKey, { context: "@iqauth/sdk helpers" });
   const inferredIssuer = parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`;
   return {
     publishableKey: config.publishableKey,

package/dist/chunk-QEJB7WEQ.mjs

@@ -0,0 +1,119 @@
+import {
+  IQAuthError
+} from "./chunk-6I6RM4MN.mjs";
+import {
+  __require
+} from "./chunk-Y6FXYEAI.mjs";
+
+// src/publishableKey.ts
+function b64urlEncode(input) {
+  if (typeof btoa === "function") {
+    const bytes = new TextEncoder().encode(input);
+    let bin = "";
+    for (let i = 0; i < bytes.byteLength; i++) bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+  }
+  const { Buffer } = __require("buffer");
+  return Buffer.from(input, "utf8").toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+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 } = __require("buffer");
+  return Buffer.from(normalized, "base64").toString("utf8");
+}
+function encodePublishableKey(mode, payload) {
+  if (mode !== "test" && mode !== "live") throw new Error(`Invalid mode: ${mode}`);
+  return `pk_${mode}_${b64urlEncode(JSON.stringify(payload))}`;
+}
+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 parsePublishableKey(raw) {
+  if (typeof raw !== "string") return null;
+  const m = raw.match(/^pk_(test|live)_([A-Za-z0-9_-]+)$/);
+  if (!m) return null;
+  try {
+    const json = JSON.parse(b64urlDecode(m[2]));
+    if (!json || typeof json !== "object") return null;
+    if (typeof json.iss !== "string" || typeof json.appId !== "string" || typeof json.tenantId !== "string" || typeof json.kid !== "string") {
+      return null;
+    }
+    if (!isValidIssuerUrl(json.iss)) return null;
+    return { mode: m[1], iss: json.iss, appId: json.appId, tenantId: json.tenantId, kid: json.kid, raw };
+  } catch {
+    return null;
+  }
+}
+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, or set IQAUTH_ISSUER to the correct issuer URL as a temporary workaround.`
+    );
+  }
+  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";
+}
+function isPublishableKey(raw) {
+  return typeof raw === "string" && /^pk_(test|live)_/.test(raw);
+}
+function isSecretKey(raw) {
+  return typeof raw === "string" && /^sk_(test|live)_/.test(raw);
+}
+
+export {
+  encodePublishableKey,
+  parsePublishableKey,
+  assertPublishableKey,
+  isPublishableKey,
+  isSecretKey
+};

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

@@ -1,6 +1,6 @@
 import {
-  parsePublishableKey
-} from "./chunk-5WFR6Y33.mjs";
+  assertPublishableKey
+} from "./chunk-QEJB7WEQ.mjs";
 import {
   IQAuthError
 } from "./chunk-6I6RM4MN.mjs";
@@ -125,12 +125,7 @@ var SessionManager = class {
     this.remoteRefreshWaiters = [];
     /** Active claims by other tabs (keyed by source tabId). */
     this.foreignClaim = null;
-    const parsed = parsePublishableKey(options.publishableKey);
-    if (!parsed) {
-      throw new Error(
-        `Invalid IQAuth publishable key. Expected pk_test_\u2026 or pk_live_\u2026 (got ${options.publishableKey?.slice(0, 12) ?? "<empty>"}\u2026).`
-      );
-    }
+    const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/browser SessionManager" });
     this.key = parsed;
     const inferred = options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`);
     this.issuer = inferred.replace(/\/+$/, "");

package/dist/cli/index.js

@@ -278,6 +278,13 @@ var init_util = __esm({
   }
 });
 
+// src/errors.ts
+var init_errors = __esm({
+  "src/errors.ts"() {
+    "use strict";
+  }
+});
+
 // src/publishableKey.ts
 function b64urlDecode(input) {
   const pad = input.length % 4 === 0 ? "" : "=".repeat(4 - input.length % 4);
@@ -291,6 +298,18 @@ function b64urlDecode(input) {
   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 parsePublishableKey(raw) {
   if (typeof raw !== "string") return null;
   const m = raw.match(/^pk_(test|live)_([A-Za-z0-9_-]+)$/);
@@ -301,6 +320,7 @@ function parsePublishableKey(raw) {
     if (typeof json.iss !== "string" || typeof json.appId !== "string" || typeof json.tenantId !== "string" || typeof json.kid !== "string") {
       return null;
     }
+    if (!isValidIssuerUrl(json.iss)) return null;
     return { mode: m[1], iss: json.iss, appId: json.appId, tenantId: json.tenantId, kid: json.kid, raw };
   } catch {
     return null;
@@ -309,6 +329,7 @@ function parsePublishableKey(raw) {
 var init_publishableKey = __esm({
   "src/publishableKey.ts"() {
     "use strict";
+    init_errors();
   }
 });
 

package/dist/cli/index.mjs

@@ -17,7 +17,7 @@ async function run() {
       return;
     }
     case "doctor": {
-      const { runDoctor } = await import("../doctor-OHJRZBBT.mjs");
+      const { runDoctor } = await import("../doctor-XCI77BQS.mjs");
       await runDoctor(rest);
       return;
     }

package/dist/{doctor-OHJRZBBT.mjs → doctor-XCI77BQS.mjs}

@@ -5,7 +5,8 @@ import {
 } from "./chunk-X3K3WOBR.mjs";
 import {
   parsePublishableKey
-} from "./chunk-5WFR6Y33.mjs";
+} from "./chunk-QEJB7WEQ.mjs";
+import "./chunk-6I6RM4MN.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 
 // src/cli/doctor.ts

package/dist/express.js

@@ -1805,21 +1805,61 @@ function b64urlDecode(input) {
   const { Buffer: Buffer2 } = require("buffer");
   return Buffer2.from(normalized, "base64").toString("utf8");
 }
-function parsePublishableKey(raw) {
-  if (typeof raw !== "string") return null;
-  const m = raw.match(/^pk_(test|live)_([A-Za-z0-9_-]+)$/);
-  if (!m) return null;
+function isValidIssuerUrl(iss) {
+  if (typeof iss !== "string" || iss.length === 0) return false;
+  if (!iss.startsWith("http://") && !iss.startsWith("https://")) return false;
   try {
-    const json = JSON.parse(b64urlDecode(m[2]));
-    if (!json || typeof json !== "object") return null;
-    if (typeof json.iss !== "string" || typeof json.appId !== "string" || typeof json.tenantId !== "string" || typeof json.kid !== "string") {
-      return null;
-    }
-    return { mode: m[1], iss: json.iss, appId: json.appId, tenantId: json.tenantId, kid: json.kid, raw };
+    const u = new URL(iss);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return false;
+    if (!u.hostname) return false;
+    return true;
   } catch {
-    return null;
+    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, or set IQAUTH_ISSUER to the correct issuer URL as a temporary workaround.`
+    );
+  }
+  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/middleware/express.ts
 var KNOWN_AUTH_ERROR_CODES = /* @__PURE__ */ new Set([
@@ -1857,10 +1897,7 @@ function readCookie(req, name) {
   return void 0;
 }
 function clientFromPublishableKey(opts) {
-  const parsed = parsePublishableKey(opts.publishableKey);
-  if (!parsed) {
-    throw new Error("iqAuthMiddleware: invalid publishable key");
-  }
+  const parsed = assertPublishableKey(opts.publishableKey, { context: "iqAuthMiddleware" });
   const issuer = (opts.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   return new IQAuthClient({ baseUrl: issuer, environment: "server" });
 }
@@ -2002,12 +2039,7 @@ function shouldClearCookiesOnFailure(policy, status, errorCode) {
 var ACCESS_TOKEN_TTL_SECONDS = 60 * 15;
 var REFRESH_TOKEN_TTL_SECONDS = 60 * 60 * 24 * 30;
 function resolve(config) {
-  const parsed = parsePublishableKey(config.publishableKey);
-  if (!parsed) {
-    throw new Error(
-      "@iqauth/sdk: invalid publishable key passed to iqAuth helpers (expected pk_test_\u2026 or pk_live_\u2026)"
-    );
-  }
+  const parsed = assertPublishableKey(config.publishableKey, { context: "@iqauth/sdk helpers" });
   const inferredIssuer = parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`;
   return {
     publishableKey: config.publishableKey,
@@ -2222,10 +2254,7 @@ function readCookieFromReq(req, name) {
   return void 0;
 }
 function iqAuth(options) {
-  const parsed = parsePublishableKey(options.publishableKey);
-  if (!parsed) {
-    throw new Error("@iqauth/sdk/express: invalid publishable key");
-  }
+  const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/express" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const client = new IQAuthClient({
     baseUrl: issuer,

package/dist/express.mjs

@@ -1,15 +1,15 @@
 import {
   DEFAULT_REFRESH_COOKIE,
   iqAuthMiddleware
-} from "./chunk-ZESHDJDU.mjs";
+} from "./chunk-D72UL5HL.mjs";
 import {
   handleCallback,
   handleRefresh,
   handleSignout
-} from "./chunk-JQRTY5MY.mjs";
+} from "./chunk-M4J6BPK7.mjs";
 import {
-  parsePublishableKey
-} from "./chunk-5WFR6Y33.mjs";
+  assertPublishableKey
+} from "./chunk-QEJB7WEQ.mjs";
 import {
   IQAuthClient
 } from "./chunk-MDUHPQMM.mjs";
@@ -66,10 +66,7 @@ function readCookieFromReq(req, name) {
   return void 0;
 }
 function iqAuth(options) {
-  const parsed = parsePublishableKey(options.publishableKey);
-  if (!parsed) {
-    throw new Error("@iqauth/sdk/express: invalid publishable key");
-  }
+  const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/express" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const client = new IQAuthClient({
     baseUrl: issuer,

package/dist/fastify.js

@@ -1767,20 +1767,60 @@ function b64urlDecode(input) {
   const { Buffer: Buffer2 } = require("buffer");
   return Buffer2.from(normalized, "base64").toString("utf8");
 }
-function parsePublishableKey(raw) {
-  if (typeof raw !== "string") return null;
-  const m = raw.match(/^pk_(test|live)_([A-Za-z0-9_-]+)$/);
-  if (!m) return null;
+function isValidIssuerUrl(iss) {
+  if (typeof iss !== "string" || iss.length === 0) return false;
+  if (!iss.startsWith("http://") && !iss.startsWith("https://")) return false;
   try {
-    const json = JSON.parse(b64urlDecode(m[2]));
-    if (!json || typeof json !== "object") return null;
-    if (typeof json.iss !== "string" || typeof json.appId !== "string" || typeof json.tenantId !== "string" || typeof json.kid !== "string") {
-      return null;
-    }
-    return { mode: m[1], iss: json.iss, appId: json.appId, tenantId: json.tenantId, kid: json.kid, raw };
+    const u = new URL(iss);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return false;
+    if (!u.hostname) return false;
+    return true;
   } catch {
-    return null;
+    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, or set IQAUTH_ISSUER to the correct issuer URL as a temporary workaround.`
+    );
+  }
+  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/server/handlers.ts
@@ -1803,12 +1843,7 @@ function shouldClearCookiesOnFailure(policy, status, errorCode) {
 var ACCESS_TOKEN_TTL_SECONDS = 60 * 15;
 var REFRESH_TOKEN_TTL_SECONDS = 60 * 60 * 24 * 30;
 function resolve(config) {
-  const parsed = parsePublishableKey(config.publishableKey);
-  if (!parsed) {
-    throw new Error(
-      "@iqauth/sdk: invalid publishable key passed to iqAuth helpers (expected pk_test_\u2026 or pk_live_\u2026)"
-    );
-  }
+  const parsed = assertPublishableKey(config.publishableKey, { context: "@iqauth/sdk helpers" });
   const inferredIssuer = parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`;
   return {
     publishableKey: config.publishableKey,
@@ -2023,8 +2058,7 @@ function readCookie(req, name) {
   return void 0;
 }
 async function iqAuth(fastify, options) {
-  const parsed = parsePublishableKey(options.publishableKey);
-  if (!parsed) throw new Error("@iqauth/sdk/fastify: invalid publishable key");
+  const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/fastify" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const helperConfig = { ...options, issuer };
   const client = new IQAuthClient({