@iqauth/sdk 2.1.0 → 2.2.0

package/dist/fastify.mjs

@@ -3,10 +3,10 @@ import {
   handleRefresh,
   handleSignout,
   serializeCookie
-} 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";
@@ -52,8 +52,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({

package/dist/hono.js

@@ -1766,20 +1766,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
@@ -1802,12 +1842,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,
@@ -2015,8 +2050,7 @@ function honoResponse(hr) {
   return new Response(JSON.stringify(hr.body), { status: hr.status, headers });
 }
 function iqAuth(options) {
-  const parsed = parsePublishableKey(options.publishableKey);
-  if (!parsed) throw new Error("@iqauth/sdk/hono: invalid publishable key");
+  const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/hono" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const helperConfig = { ...options, issuer };
   const client = new IQAuthClient({ baseUrl: issuer, environment: "server" });

package/dist/hono.mjs

@@ -3,10 +3,10 @@ import {
   handleRefresh,
   handleSignout,
   serializeCookie
-} 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";
@@ -45,8 +45,7 @@ function honoResponse(hr) {
   return new Response(JSON.stringify(hr.body), { status: hr.status, headers });
 }
 function iqAuth(options) {
-  const parsed = parsePublishableKey(options.publishableKey);
-  if (!parsed) throw new Error("@iqauth/sdk/hono: invalid publishable key");
+  const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/hono" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const helperConfig = { ...options, issuer };
   const client = new IQAuthClient({ baseUrl: issuer, environment: "server" });

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 export { o as ApiKeysModule, l as AppsModule, A as AuthModule, B as BrandingModule, r as ClientsModule, C as CreateAppRequest, m as CreateAppResponse, h as DEFAULT_CLOCK_TOLERANCE_SECONDS, g as DEFAULT_TOKEN_AUDIENCE, D as DEFAULT_TOKEN_ISSUER, E as EntitlementsModule, G as GdprModule, H as HierarchyModule, I as IQAuthClient, a as InMemoryOidcStateStore, p as InvitesModule, M as MembershipsModule, u as MfaModule, d as OidcAuthRequest, e as OidcCallbackResult, O as OidcModule, f as OidcModuleOptions, b as OidcStateStore, c as OidcStoredRequest, n as PermissionGroupsModule, P as PermissionsModule, t as PinModule, R as RolesModule, s as ScopeModule, S as SessionsModule, q as SourcesModule, k as TenantsModule, i as TokenVerifyOptions, T as TokensModule, j as TokensModuleOptions, U as UsersModule, V as VendorsModule, W as WebhooksModule } from './client-Dv4v92Mj.mjs';
 export { a as ErrorCode, E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
 export { i as iqAuthMiddleware } from './express-BZmF1llh.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 { K as KeyMode, c as ParsedPublishableKey, P as PublishableKeyPayload, a as assertPublishableKey, e as encodePublishableKey, i as isPublishableKey, b as isSecretKey, p as parsePublishableKey } from './publishableKey-BaR0HoAH.mjs';
 export { an as AcceptInviteRequest, aa as AddGroupPermissionRequest, ad as AddUserOverrideRequest, v as ApiErrorResponse, ag as ApiKeyInfo, aj as ApiKeyIntrospection, w as ApiResponse, A as ApiSuccessResponse, _ as AppInfo, Z as AppManifest, a0 as AppSyncResult, a4 as AssignRoleRequest, aM as AvailableScopesTree, a_ as BackupCodeCountResult, aZ as BackupCodesResult, p as BrandingAsset, B as BrandingConfig, r as BrandingDomainMapping, aB as Client, ah as CreateApiKeyRequest, ai as CreateApiKeyResult, aC as CreateClientRequest, al as CreateInviteRequest, aJ as CreateMembershipRequest, a2 as CreateRoleRequest, az as CreateSourceRequest, C as CreateTenantRequest, aw as CreateVendorRequest, ap as CreateWebhookRequest, aq as CreateWebhookResult, ae as EffectivePermission, aY as EmailEnrollResult, at as Entitlement, N as ExpressMiddlewareOptions, aR as GdprExportData, au as GrantEntitlementRequest, a9 as GroupPermission, aG as HierarchyClient, aH as HierarchyLink, aF as HierarchySource, aE as HierarchyVendor, c as IQAuthBrowserSessionClientConfig, a as IQAuthClientConfig, I as IQAuthEnvironment, V as IQAuthNextFunction, Q as IQAuthRequestLike, R as IQAuthResponseLike, W as IQAuthRetryConfig, b as IQAuthTokenClientConfig, X as IQAuthVerifyConfig, ab as InheritanceRelation, ak as Invitation, l as InviteTenantUserRequest, m as InviteTenantUserResult, am as InviteValidation, s as JwksKey, t as JwksResponse, J as JwtClaims, L as LoginResult, aI as Membership, aL as MembershipWithDetails, aU as MfaAvailableMethods, y as MfaEnrollment, x as MfaMethod, F as MfaPolicy, D as MfaVerifyResult, M as MigrateUserRequest, O as OidcDiscovery, u as OidcTokenResponse, E as PasswordPolicy, af as PermissionCheckResult, a8 as PermissionGroup, $ as PermissionNodeInfo, Y as PermissionNodeManifest, aT as PinLoginResult, aS as PinStatus, P as PromoteToVendorRequest, k as PromoteToVendorResult, H as ProvisionUserRequest, K as ProvisionUserResponse, a1 as Role, S as ScopeContext, aQ as ScopeSwitchResult, aN as ScopeTreeClient, aO as ScopeTreeSource, aP as ScopeTreeVendor, h as Session, g as SessionAuthenticatedLoginResult, d as SessionUser, aX as SmsEnrollResult, ay as Source, e as Tenant, i as TenantInfo, a7 as TenantUser, n as TenantUserRoleUpdate, f as TokenAuthenticatedLoginResult, T as TokenPair, aV as TotpEnrollResult, z as TotpEnrollmentResult, aW as TotpVerifyResult, o as UpdateBrandingRequest, aD as UpdateClientRequest, aK as UpdateMembershipRequest, a3 as UpdateRoleRequest, aA as UpdateSourceRequest, j as UpdateTenantRequest, ax as UpdateVendorRequest, q as UploadAssetRequest, a6 as UserGroupAssignment, ac as UserPermissionOverride, G as UserPermissions, U as UserProfile, a5 as UserRoleAssignment, av as Vendor, ar as WebhookDelivery, ao as WebhookEndpoint, as as WebhookTestResult } from './types-Cxl3bQHt.mjs';
 import 'jsonwebtoken';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { o as ApiKeysModule, l as AppsModule, A as AuthModule, B as BrandingModule, r as ClientsModule, C as CreateAppRequest, m as CreateAppResponse, h as DEFAULT_CLOCK_TOLERANCE_SECONDS, g as DEFAULT_TOKEN_AUDIENCE, D as DEFAULT_TOKEN_ISSUER, E as EntitlementsModule, G as GdprModule, H as HierarchyModule, I as IQAuthClient, a as InMemoryOidcStateStore, p as InvitesModule, M as MembershipsModule, u as MfaModule, d as OidcAuthRequest, e as OidcCallbackResult, O as OidcModule, f as OidcModuleOptions, b as OidcStateStore, c as OidcStoredRequest, n as PermissionGroupsModule, P as PermissionsModule, t as PinModule, R as RolesModule, s as ScopeModule, S as SessionsModule, q as SourcesModule, k as TenantsModule, i as TokenVerifyOptions, T as TokensModule, j as TokensModuleOptions, U as UsersModule, V as VendorsModule, W as WebhooksModule } from './client-DXbHb2ul.js';
 export { a as ErrorCode, E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
 export { i as iqAuthMiddleware } from './express-B4o3P8vK.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 { K as KeyMode, c as ParsedPublishableKey, P as PublishableKeyPayload, a as assertPublishableKey, e as encodePublishableKey, i as isPublishableKey, b as isSecretKey, p as parsePublishableKey } from './publishableKey-BaR0HoAH.js';
 export { an as AcceptInviteRequest, aa as AddGroupPermissionRequest, ad as AddUserOverrideRequest, v as ApiErrorResponse, ag as ApiKeyInfo, aj as ApiKeyIntrospection, w as ApiResponse, A as ApiSuccessResponse, _ as AppInfo, Z as AppManifest, a0 as AppSyncResult, a4 as AssignRoleRequest, aM as AvailableScopesTree, a_ as BackupCodeCountResult, aZ as BackupCodesResult, p as BrandingAsset, B as BrandingConfig, r as BrandingDomainMapping, aB as Client, ah as CreateApiKeyRequest, ai as CreateApiKeyResult, aC as CreateClientRequest, al as CreateInviteRequest, aJ as CreateMembershipRequest, a2 as CreateRoleRequest, az as CreateSourceRequest, C as CreateTenantRequest, aw as CreateVendorRequest, ap as CreateWebhookRequest, aq as CreateWebhookResult, ae as EffectivePermission, aY as EmailEnrollResult, at as Entitlement, N as ExpressMiddlewareOptions, aR as GdprExportData, au as GrantEntitlementRequest, a9 as GroupPermission, aG as HierarchyClient, aH as HierarchyLink, aF as HierarchySource, aE as HierarchyVendor, c as IQAuthBrowserSessionClientConfig, a as IQAuthClientConfig, I as IQAuthEnvironment, V as IQAuthNextFunction, Q as IQAuthRequestLike, R as IQAuthResponseLike, W as IQAuthRetryConfig, b as IQAuthTokenClientConfig, X as IQAuthVerifyConfig, ab as InheritanceRelation, ak as Invitation, l as InviteTenantUserRequest, m as InviteTenantUserResult, am as InviteValidation, s as JwksKey, t as JwksResponse, J as JwtClaims, L as LoginResult, aI as Membership, aL as MembershipWithDetails, aU as MfaAvailableMethods, y as MfaEnrollment, x as MfaMethod, F as MfaPolicy, D as MfaVerifyResult, M as MigrateUserRequest, O as OidcDiscovery, u as OidcTokenResponse, E as PasswordPolicy, af as PermissionCheckResult, a8 as PermissionGroup, $ as PermissionNodeInfo, Y as PermissionNodeManifest, aT as PinLoginResult, aS as PinStatus, P as PromoteToVendorRequest, k as PromoteToVendorResult, H as ProvisionUserRequest, K as ProvisionUserResponse, a1 as Role, S as ScopeContext, aQ as ScopeSwitchResult, aN as ScopeTreeClient, aO as ScopeTreeSource, aP as ScopeTreeVendor, h as Session, g as SessionAuthenticatedLoginResult, d as SessionUser, aX as SmsEnrollResult, ay as Source, e as Tenant, i as TenantInfo, a7 as TenantUser, n as TenantUserRoleUpdate, f as TokenAuthenticatedLoginResult, T as TokenPair, aV as TotpEnrollResult, z as TotpEnrollmentResult, aW as TotpVerifyResult, o as UpdateBrandingRequest, aD as UpdateClientRequest, aK as UpdateMembershipRequest, a3 as UpdateRoleRequest, aA as UpdateSourceRequest, j as UpdateTenantRequest, ax as UpdateVendorRequest, q as UploadAssetRequest, a6 as UserGroupAssignment, ac as UserPermissionOverride, G as UserPermissions, U as UserProfile, a5 as UserRoleAssignment, av as Vendor, ar as WebhookDelivery, ao as WebhookEndpoint, as as WebhookTestResult } from './types-Cxl3bQHt.js';
 import 'jsonwebtoken';

package/dist/index.js

@@ -61,6 +61,7 @@ __export(index_exports, {
   UsersModule: () => UsersModule,
   VendorsModule: () => VendorsModule,
   WebhooksModule: () => WebhooksModule,
+  assertPublishableKey: () => assertPublishableKey,
   encodePublishableKey: () => encodePublishableKey,
   iqAuthMiddleware: () => iqAuthMiddleware,
   isPublishableKey: () => isPublishableKey,
@@ -1851,6 +1852,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_-]+)$/);
@@ -1861,11 +1874,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);
 }
@@ -1908,10 +1965,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" });
 }
@@ -2065,6 +2119,7 @@ function iqAuthMiddleware(clientOrOptions, options = {}) {
   UsersModule,
   VendorsModule,
   WebhooksModule,
+  assertPublishableKey,
   encodePublishableKey,
   iqAuthMiddleware,
   isPublishableKey,

package/dist/index.mjs

@@ -1,12 +1,13 @@
 import {
   iqAuthMiddleware
-} from "./chunk-ZESHDJDU.mjs";
+} from "./chunk-D72UL5HL.mjs";
 import {
+  assertPublishableKey,
   encodePublishableKey,
   isPublishableKey,
   isSecretKey,
   parsePublishableKey
-} from "./chunk-5WFR6Y33.mjs";
+} from "./chunk-QEJB7WEQ.mjs";
 import {
   ApiKeysModule,
   AppsModule,
@@ -75,6 +76,7 @@ export {
   UsersModule,
   VendorsModule,
   WebhooksModule,
+  assertPublishableKey,
   encodePublishableKey,
   iqAuthMiddleware,
   isPublishableKey,

package/dist/next.js

@@ -36,6 +36,17 @@ __export(next_exports, {
 });
 module.exports = __toCommonJS(next_exports);
 
+// 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/publishableKey.ts
 function b64urlDecode(input) {
   const pad = input.length % 4 === 0 ? "" : "=".repeat(4 - input.length % 4);
@@ -49,21 +60,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/server/handlers.ts
 var TERMINAL_REFRESH_ERROR_CODES = /* @__PURE__ */ new Set([
@@ -85,12 +136,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,
@@ -268,17 +314,6 @@ async function handleSignout(config, input) {
   };
 }
 
-// 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/http.ts
 var DEFAULT_RETRY = {
   maxAttempts: 3,
@@ -2009,8 +2044,7 @@ function toResponse(hr) {
   return new Response(JSON.stringify(hr.body), { status: hr.status, headers });
 }
 function handler(options) {
-  const parsed = parsePublishableKey(options.publishableKey);
-  if (!parsed) throw new Error("@iqauth/sdk/next: invalid publishable key");
+  const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/next handler" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const helperConfig = { ...options, issuer };
   const accessCookie = options.accessCookieName ?? "iqauth_at";
@@ -2043,8 +2077,7 @@ function handler(options) {
   };
 }
 function createMiddleware(options) {
-  const parsed = parsePublishableKey(options.publishableKey);
-  if (!parsed) throw new Error("@iqauth/sdk/next: invalid publishable key");
+  const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/next createMiddleware" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const accessCookie = options.accessCookieName ?? "iqauth_at";
   const client = new IQAuthClient({ baseUrl: issuer, environment: "server" });
@@ -2072,8 +2105,7 @@ function createMiddleware(options) {
   };
 }
 async function getAuth(options) {
-  const parsed = parsePublishableKey(options.publishableKey);
-  if (!parsed) throw new Error("@iqauth/sdk/next: invalid publishable key");
+  const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/next getAuth" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const accessCookie = options.accessCookieName ?? "iqauth_at";
   let cookieJar = null;

package/dist/next.mjs

@@ -3,10 +3,10 @@ import {
   handleRefresh,
   handleSignout,
   serializeCookie
-} 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";
@@ -35,8 +35,7 @@ function toResponse(hr) {
   return new Response(JSON.stringify(hr.body), { status: hr.status, headers });
 }
 function handler(options) {
-  const parsed = parsePublishableKey(options.publishableKey);
-  if (!parsed) throw new Error("@iqauth/sdk/next: invalid publishable key");
+  const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/next handler" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const helperConfig = { ...options, issuer };
   const accessCookie = options.accessCookieName ?? "iqauth_at";
@@ -69,8 +68,7 @@ function handler(options) {
   };
 }
 function createMiddleware(options) {
-  const parsed = parsePublishableKey(options.publishableKey);
-  if (!parsed) throw new Error("@iqauth/sdk/next: invalid publishable key");
+  const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/next createMiddleware" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const accessCookie = options.accessCookieName ?? "iqauth_at";
   const client = new IQAuthClient({ baseUrl: issuer, environment: "server" });
@@ -98,8 +96,7 @@ function createMiddleware(options) {
   };
 }
 async function getAuth(options) {
-  const parsed = parsePublishableKey(options.publishableKey);
-  if (!parsed) throw new Error("@iqauth/sdk/next: invalid publishable key");
+  const parsed = assertPublishableKey(options.publishableKey, { context: "@iqauth/sdk/next getAuth" });
   const issuer = (options.issuer ?? (parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`)).replace(/\/+$/, "");
   const accessCookie = options.accessCookieName ?? "iqauth_at";
   let cookieJar = null;

package/dist/{publishableKey-B5DIK81A.d.mts → publishableKey-BaR0HoAH.d.mts}

@@ -18,7 +18,16 @@ interface ParsedPublishableKey extends PublishableKeyPayload {
 }
 declare function encodePublishableKey(mode: KeyMode, payload: PublishableKeyPayload): string;
 declare function parsePublishableKey(raw: string): ParsedPublishableKey | null;
+/**
+ * Strict counterpart to `parsePublishableKey` — throws a typed `IQAuthError`
+ * (`code: "CONFIG_INVALID"`) with an actionable message when the key is
+ * missing, malformed, or encodes a non-URL `iss`. Use this at SDK init so a
+ * bad key fails loudly at boot instead of cryptically at first verify.
+ */
+declare function assertPublishableKey(raw: string | undefined | null, opts?: {
+    context?: string;
+}): ParsedPublishableKey;
 declare function isPublishableKey(raw: string): boolean;
 declare function isSecretKey(raw: string): boolean;
 
-export { type KeyMode as K, type PublishableKeyPayload as P, isSecretKey as a, type ParsedPublishableKey as b, encodePublishableKey as e, isPublishableKey as i, parsePublishableKey as p };
+export { type KeyMode as K, type PublishableKeyPayload as P, assertPublishableKey as a, isSecretKey as b, type ParsedPublishableKey as c, encodePublishableKey as e, isPublishableKey as i, parsePublishableKey as p };

package/dist/{publishableKey-B5DIK81A.d.ts → publishableKey-BaR0HoAH.d.ts}

@@ -18,7 +18,16 @@ interface ParsedPublishableKey extends PublishableKeyPayload {
 }
 declare function encodePublishableKey(mode: KeyMode, payload: PublishableKeyPayload): string;
 declare function parsePublishableKey(raw: string): ParsedPublishableKey | null;
+/**
+ * Strict counterpart to `parsePublishableKey` — throws a typed `IQAuthError`
+ * (`code: "CONFIG_INVALID"`) with an actionable message when the key is
+ * missing, malformed, or encodes a non-URL `iss`. Use this at SDK init so a
+ * bad key fails loudly at boot instead of cryptically at first verify.
+ */
+declare function assertPublishableKey(raw: string | undefined | null, opts?: {
+    context?: string;
+}): ParsedPublishableKey;
 declare function isPublishableKey(raw: string): boolean;
 declare function isSecretKey(raw: string): boolean;
 
-export { type KeyMode as K, type PublishableKeyPayload as P, isSecretKey as a, type ParsedPublishableKey as b, encodePublishableKey as e, isPublishableKey as i, parsePublishableKey as p };
+export { type KeyMode as K, type PublishableKeyPayload as P, assertPublishableKey as a, isSecretKey as b, type ParsedPublishableKey as c, encodePublishableKey as e, isPublishableKey as i, parsePublishableKey as p };

package/dist/react.d.mts

@@ -1,9 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import { ReactNode } from 'react';
-import { S as SessionManager, a as SessionSnapshot, b as SignInOptions, c as SignOutOptions, C as CallbackResult } from './signIn-CEMdUAwd.mjs';
+import { S as SessionManager, a as SessionSnapshot, b as SignInOptions, c as SignOutOptions, C as CallbackResult } from './signIn-D_kP3v-c.mjs';
 import { d as SessionUser, J as JwtClaims } from './types-Cxl3bQHt.mjs';
-import './publishableKey-B5DIK81A.mjs';
+import './publishableKey-BaR0HoAH.mjs';
 
 interface IQAuthContextValue {
     manager: SessionManager;
@@ -89,6 +89,38 @@ declare function SignedOut({ children }: {
 }): React.FunctionComponentElement<{
     children?: ReactNode | undefined;
 }> | null;
+/**
+ * Renders its children only while the SDK is still bootstrapping (i.e.
+ * `useAuth().isLoaded === false`). Mirrors Clerk's `<ClerkLoading/>`.
+ *
+ * Recommended pattern (slow-network-safe):
+ * ```tsx
+ * <IQAuthProvider publishableKey={…}>
+ *   <IQAuthLoading><Spinner /></IQAuthLoading>
+ *   <IQAuthLoaded>
+ *     <SignedIn><App /></SignedIn>
+ *     <SignedOut><SignIn /></SignedOut>
+ *   </IQAuthLoaded>
+ * </IQAuthProvider>
+ * ```
+ */
+declare function IQAuthLoading({ children }: {
+    children?: ReactNode;
+}): React.FunctionComponentElement<{
+    children?: ReactNode | undefined;
+}> | null;
+/**
+ * Renders its children only after the SDK has finished bootstrapping (i.e.
+ * `useAuth().isLoaded === true`). Mirrors Clerk's `<ClerkLoaded/>`. Wrap
+ * `<SignedIn/>` / `<SignedOut/>` in this to avoid a flash of blank UI on
+ * slow connections — see `<IQAuthLoading/>` above for the recommended
+ * full pattern.
+ */
+declare function IQAuthLoaded({ children }: {
+    children?: ReactNode;
+}): React.FunctionComponentElement<{
+    children?: ReactNode | undefined;
+}> | null;
 interface RedirectToSignInProps extends SignInOptions {
 }
 declare function RedirectToSignIn(props?: RedirectToSignInProps): React.DetailedReactHTMLElement<{
@@ -268,4 +300,4 @@ interface OrganizationSwitcherProps {
 declare function OrganizationSwitcher({ iqAuthBaseUrl, onSwitched, className }: OrganizationSwitcherProps): react_jsx_runtime.JSX.Element;
 declare const __version__ = "phase-bc-1.0.0";
 
-export { AuthCallback, type AuthCallbackProps, type IQAuthBranding, IQAuthProvider, type IQAuthProviderProps, type IQAuthSignInContext, OrganizationSwitcher, type OrganizationSwitcherProps, RedirectToSignIn, type RedirectToSignInProps, type SessionError, type SharedComponentProps, SignIn, type SignInProps, SignUp, type SignUpProps, SignedIn, SignedOut, type UseAuthResult, type UseOrganizationResult, type UseSessionResult, type UseUserResult, UserButton, type UserButtonProps, UserProfile, type UserProfileProps, type UserSummary, __version__, isSilentSsoEligible, sanitizeBrandCss, useAuth, useAuthFetch, useIQAuthSignInContext, useOrganization, useResolvedSdkBranding, useSession, useUser };
+export { AuthCallback, type AuthCallbackProps, type IQAuthBranding, IQAuthLoaded, IQAuthLoading, IQAuthProvider, type IQAuthProviderProps, type IQAuthSignInContext, OrganizationSwitcher, type OrganizationSwitcherProps, RedirectToSignIn, type RedirectToSignInProps, type SessionError, type SharedComponentProps, SignIn, type SignInProps, SignUp, type SignUpProps, SignedIn, SignedOut, type UseAuthResult, type UseOrganizationResult, type UseSessionResult, type UseUserResult, UserButton, type UserButtonProps, UserProfile, type UserProfileProps, type UserSummary, __version__, isSilentSsoEligible, sanitizeBrandCss, useAuth, useAuthFetch, useIQAuthSignInContext, useOrganization, useResolvedSdkBranding, useSession, useUser };

package/dist/react.d.ts

@@ -1,9 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import { ReactNode } from 'react';
-import { S as SessionManager, a as SessionSnapshot, b as SignInOptions, c as SignOutOptions, C as CallbackResult } from './signIn-VRNzlNyG.js';
+import { S as SessionManager, a as SessionSnapshot, b as SignInOptions, c as SignOutOptions, C as CallbackResult } from './signIn-BVDTIA_t.js';
 import { d as SessionUser, J as JwtClaims } from './types-Cxl3bQHt.js';
-import './publishableKey-B5DIK81A.js';
+import './publishableKey-BaR0HoAH.js';
 
 interface IQAuthContextValue {
     manager: SessionManager;
@@ -89,6 +89,38 @@ declare function SignedOut({ children }: {
 }): React.FunctionComponentElement<{
     children?: ReactNode | undefined;
 }> | null;
+/**
+ * Renders its children only while the SDK is still bootstrapping (i.e.
+ * `useAuth().isLoaded === false`). Mirrors Clerk's `<ClerkLoading/>`.
+ *
+ * Recommended pattern (slow-network-safe):
+ * ```tsx
+ * <IQAuthProvider publishableKey={…}>
+ *   <IQAuthLoading><Spinner /></IQAuthLoading>
+ *   <IQAuthLoaded>
+ *     <SignedIn><App /></SignedIn>
+ *     <SignedOut><SignIn /></SignedOut>
+ *   </IQAuthLoaded>
+ * </IQAuthProvider>
+ * ```
+ */
+declare function IQAuthLoading({ children }: {
+    children?: ReactNode;
+}): React.FunctionComponentElement<{
+    children?: ReactNode | undefined;
+}> | null;
+/**
+ * Renders its children only after the SDK has finished bootstrapping (i.e.
+ * `useAuth().isLoaded === true`). Mirrors Clerk's `<ClerkLoaded/>`. Wrap
+ * `<SignedIn/>` / `<SignedOut/>` in this to avoid a flash of blank UI on
+ * slow connections — see `<IQAuthLoading/>` above for the recommended
+ * full pattern.
+ */
+declare function IQAuthLoaded({ children }: {
+    children?: ReactNode;
+}): React.FunctionComponentElement<{
+    children?: ReactNode | undefined;
+}> | null;
 interface RedirectToSignInProps extends SignInOptions {
 }
 declare function RedirectToSignIn(props?: RedirectToSignInProps): React.DetailedReactHTMLElement<{
@@ -268,4 +300,4 @@ interface OrganizationSwitcherProps {
 declare function OrganizationSwitcher({ iqAuthBaseUrl, onSwitched, className }: OrganizationSwitcherProps): react_jsx_runtime.JSX.Element;
 declare const __version__ = "phase-bc-1.0.0";
 
-export { AuthCallback, type AuthCallbackProps, type IQAuthBranding, IQAuthProvider, type IQAuthProviderProps, type IQAuthSignInContext, OrganizationSwitcher, type OrganizationSwitcherProps, RedirectToSignIn, type RedirectToSignInProps, type SessionError, type SharedComponentProps, SignIn, type SignInProps, SignUp, type SignUpProps, SignedIn, SignedOut, type UseAuthResult, type UseOrganizationResult, type UseSessionResult, type UseUserResult, UserButton, type UserButtonProps, UserProfile, type UserProfileProps, type UserSummary, __version__, isSilentSsoEligible, sanitizeBrandCss, useAuth, useAuthFetch, useIQAuthSignInContext, useOrganization, useResolvedSdkBranding, useSession, useUser };
+export { AuthCallback, type AuthCallbackProps, type IQAuthBranding, IQAuthLoaded, IQAuthLoading, IQAuthProvider, type IQAuthProviderProps, type IQAuthSignInContext, OrganizationSwitcher, type OrganizationSwitcherProps, RedirectToSignIn, type RedirectToSignInProps, type SessionError, type SharedComponentProps, SignIn, type SignInProps, SignUp, type SignUpProps, SignedIn, SignedOut, type UseAuthResult, type UseOrganizationResult, type UseSessionResult, type UseUserResult, UserButton, type UserButtonProps, UserProfile, type UserProfileProps, type UserSummary, __version__, isSilentSsoEligible, sanitizeBrandCss, useAuth, useAuthFetch, useIQAuthSignInContext, useOrganization, useResolvedSdkBranding, useSession, useUser };