@iqauth/sdk 2.6.4 → 2.7.0

package/dist/index.js

@@ -42,10 +42,13 @@ __export(index_exports, {
   ErrorCodes: () => ErrorCodes,
   GdprModule: () => GdprModule,
   HierarchyModule: () => HierarchyModule,
+  IQAUTH_SIGNATURE_HEADER: () => IQAUTH_SIGNATURE_HEADER,
   IQAuthClient: () => IQAuthClient,
   IQAuthError: () => IQAuthError,
+  IQ_AUTH_ERROR_CODES: () => IQ_AUTH_ERROR_CODES,
   InMemoryOidcStateStore: () => InMemoryOidcStateStore,
   InvitesModule: () => InvitesModule,
+  LEGACY_SIGNATURE_HEADERS: () => LEGACY_SIGNATURE_HEADERS,
   MembershipsModule: () => MembershipsModule,
   MfaModule: () => MfaModule,
   OidcModule: () => OidcModule,
@@ -63,27 +66,61 @@ __export(index_exports, {
   WebhookSignatureError: () => WebhookSignatureError,
   WebhooksModule: () => WebhooksModule,
   assertPublishableKey: () => assertPublishableKey,
+  buildUserinfoResponse: () => buildUserinfoResponse,
   createProvisioningBridge: () => createProvisioningBridge,
   createTestIssuer: () => createTestIssuer,
   encodePublishableKey: () => encodePublishableKey,
+  expandPermissions: () => expandPermissions,
+  handleUserinfo: () => handleUserinfo,
+  hasPermission: () => hasPermission,
   iqAuthMiddleware: () => iqAuthMiddleware,
   isPublishableKey: () => isPublishableKey,
   isSecretKey: () => isSecretKey,
   isValidWebhookSignature: () => isValidWebhookSignature,
   parsePublishableKey: () => parsePublishableKey,
+  parseWebhookEvent: () => parseWebhookEvent,
   verifyWebhookSignature: () => verifyWebhookSignature,
   verifyWsUpgrade: () => verifyWsUpgrade
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
-var IQAuthError = class extends Error {
-  constructor(code, message, status, raw) {
+var IQ_AUTH_ERROR_CODES = [
+  "token_expired",
+  "token_invalid",
+  "jwks_unavailable",
+  "jwks_fetch_failed",
+  "rate_limited",
+  "network",
+  "config_invalid",
+  "app_not_found",
+  "permission_denied",
+  "unknown"
+];
+var IQAuthError = class _IQAuthError extends Error {
+  constructor(code, message, status, cause) {
     super(message);
     this.name = "IQAuthError";
     this.code = code;
     this.status = status;
-    this.raw = raw;
+    this.cause = cause;
+    this.raw = cause;
+  }
+  /**
+   * Type guard: true when `value` is an `IQAuthError`. Useful for adapters
+   * that round-trip errors through `unknown` (e.g. fastify's `setErrorHandler`).
+   */
+  static isIQAuthError(value) {
+    return value instanceof _IQAuthError || typeof value === "object" && value !== null && value.name === "IQAuthError" && typeof value.code === "string";
+  }
+  /**
+   * Type-narrowed code check. Lets callers write
+   * `if (err.is("token_expired")) …` with full IntelliSense for the typed
+   * taxonomy without losing the ability to handle server codes via
+   * `err.code === "TOKEN_REVOKED"`.
+   */
+  is(code) {
+    return this.code === code;
   }
 };
 var ErrorCodes = {
@@ -138,7 +175,7 @@ function resolveRetry(cfg) {
 }
 function sleep(ms) {
   if (ms <= 0) return Promise.resolve();
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 var HttpClient = class {
   constructor(config) {
@@ -234,7 +271,7 @@ var HttpClient = class {
           headers: this.buildHeaders(),
           ...this.isBrowserSession() ? { credentials: "include" } : (() => {
             const refreshToken = this.config.getRefreshToken();
-            if (!refreshToken) throw new IQAuthError("TOKEN_INVALID", "No refresh token available");
+            if (!refreshToken) throw new IQAuthError("config_invalid", "No refresh token available");
             return { body: JSON.stringify({ refreshToken }) };
           })()
         });
@@ -251,7 +288,7 @@ var HttpClient = class {
           return;
         }
         if (!body.data.accessToken || !body.data.refreshToken) {
-          throw new IQAuthError("TOKEN_INVALID", "Refresh response did not include a token pair");
+          throw new IQAuthError("token_invalid", "Refresh response did not include a token pair");
         }
         const tokens = {
           accessToken: body.data.accessToken,
@@ -269,7 +306,7 @@ var HttpClient = class {
     return this.requestWithRetry(method, path, body, options, false);
   }
   async requestWithRetry(method, path, body, options, hasRetried) {
-    if (this.config.autoRefresh && !options?.skipAutoRefresh && !this.isBrowserSession() && this.config.getRefreshToken() && this.isTokenExpiringSoon()) {
+    if (this.config.autoRefresh && this.config.proactiveRefresh !== false && !options?.skipAutoRefresh && !this.isBrowserSession() && this.config.getRefreshToken() && this.isTokenExpiringSoon()) {
       await this.attemptRefresh();
     }
     const url = `${this.config.baseUrl}${path}`;
@@ -497,6 +534,18 @@ var DEFAULT_TOKEN_AUDIENCE = [
   "iqvalidate"
 ];
 var DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+function classifyJoseError(err) {
+  if (err instanceof import_jose.errors.JWTExpired) {
+    return { code: "token_expired", message: "Token has expired" };
+  }
+  if (err instanceof import_jose.errors.JOSEError) {
+    return { code: "token_invalid", message: err.message };
+  }
+  if (err instanceof Error) {
+    return { code: "token_invalid", message: err.message };
+  }
+  return { code: "token_invalid", message: "Token verification failed" };
+}
 function decodeProtectedHeader(token) {
   const parts = token.split(".");
   if (parts.length < 2) return null;
@@ -533,11 +582,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)) {
@@ -545,7 +594,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;
@@ -561,16 +610,8 @@ var TokensModule = class {
       const { payload } = await (0, import_jose.jwtVerify)(token, cache.verifier, verifyOptions);
       return payload;
     } catch (err) {
-      if (err instanceof import_jose.errors.JWTExpired) {
-        throw new IQAuthError("TOKEN_EXPIRED", "Token has expired");
-      }
-      if (err instanceof import_jose.errors.JOSEError) {
-        throw new IQAuthError("TOKEN_INVALID", err.message);
-      }
-      if (err instanceof Error) {
-        throw new IQAuthError("TOKEN_INVALID", err.message);
-      }
-      throw new IQAuthError("TOKEN_INVALID", "Token verification failed");
+      const classified = classifyJoseError(err);
+      throw new IQAuthError(classified.code, classified.message, void 0, err);
     }
   }
   /**
@@ -612,7 +653,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;
   }
@@ -622,7 +663,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;
   }
@@ -632,22 +673,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: [...] }"
           );
         }
@@ -655,7 +712,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"
             );
           }
@@ -673,6 +730,19 @@ var TokensModule = class {
   clearCache() {
     this.jwksCache = null;
   }
+  /**
+   * Task #126: Eagerly populate the JWKS cache so the first verify() call
+   * doesn't pay a network round-trip. Safe to call repeatedly — single-flight
+   * behavior is shared with the lazy refresh path. Errors are swallowed so
+   * callers (e.g. `attachHelpers` auto-prewarm) can fire-and-forget.
+   */
+  async prewarm() {
+    if (this.jwksCache && Date.now() - this.jwksCache.fetchedAt <= JWKS_CACHE_TTL_MS) return;
+    try {
+      await this.refreshJwks();
+    } catch {
+    }
+  }
 };
 
 // src/modules/sessions.ts
@@ -996,14 +1066,14 @@ var OidcModule = class {
    */
   async handleCallback(params) {
     if (!params.state) {
-      throw new IQAuthError("VALIDATION_ERROR", "OIDC callback missing state parameter");
+      throw new IQAuthError("config_invalid", "OIDC callback missing state parameter");
     }
     if (!params.code) {
-      throw new IQAuthError("VALIDATION_ERROR", "OIDC callback missing code parameter");
+      throw new IQAuthError("config_invalid", "OIDC callback missing code parameter");
     }
     const stored = await this.stateStore.get(params.state);
     if (!stored) {
-      throw new IQAuthError("VALIDATION_ERROR", "Unknown or expired OIDC state");
+      throw new IQAuthError("config_invalid", "Unknown or expired OIDC state");
     }
     let tokens;
     try {
@@ -1021,7 +1091,7 @@ var OidcModule = class {
     if (tokens.id_token) {
       if (!this.tokensModule) {
         throw new IQAuthError(
-          "INTERNAL_ERROR",
+          "config_invalid",
           "OIDC handleCallback received an id_token but no TokensModule is configured for verification"
         );
       }
@@ -1032,7 +1102,7 @@ var OidcModule = class {
       const tokenNonce = typeof claimsBag.nonce === "string" ? claimsBag.nonce : void 0;
       if (!tokenNonce || tokenNonce !== stored.nonce) {
         throw new IQAuthError(
-          "TOKEN_INVALID",
+          "token_invalid",
           "OIDC id_token nonce did not match the stored value"
         );
       }
@@ -1233,6 +1303,9 @@ var AppsModule = class {
    * @remarks Wraps GET /api/v1/apps/:appKey
    */
   async get(appKey) {
+    if (typeof appKey !== "string" || appKey.trim() === "") {
+      throw new IQAuthError("VALIDATION_ERROR", "appKey is required (no env-var fallback).", 400);
+    }
     return this.http.request("GET", `/api/v1/apps/${encodeURIComponent(appKey)}`);
   }
   /**
@@ -1252,6 +1325,16 @@ var AppsModule = class {
         401
       );
     }
+    if (!manifest || typeof manifest.key !== "string" || manifest.key.trim() === "") {
+      throw new IQAuthError("VALIDATION_ERROR", "manifest.key (appKey) is required for register().", 400);
+    }
+    if (!manifest.environment || !["production", "staging", "development"].includes(manifest.environment)) {
+      throw new IQAuthError(
+        "ENVIRONMENT_REQUIRED",
+        "manifest.environment is required and must be 'production', 'staging', or 'development'. This guards against a dev workstation silently overwriting a production app's permission tree.",
+        400
+      );
+    }
     return this.http.request("POST", "/api/v1/apps/sync", manifest);
   }
   /**
@@ -1261,11 +1344,14 @@ var AppsModule = class {
    * @remarks Uses GET /api/v1/apps/:appKey — catches 404 errors
    */
   async isRegistered(appKey) {
+    if (typeof appKey !== "string" || appKey.trim() === "") {
+      throw new IQAuthError("VALIDATION_ERROR", "appKey is required (no env-var fallback).", 400);
+    }
     try {
       await this.get(appKey);
       return true;
     } catch (err) {
-      if (err.code === "NOT_FOUND" || err.status === 404) {
+      if (err.code === "app_not_found" || err.code === "NOT_FOUND" || err.status === 404) {
         return false;
       }
       throw err;
@@ -1302,6 +1388,20 @@ var RolesModule = class {
 };
 
 // src/modules/permissionGroups.ts
+function assertAppKey(appKey, callsite) {
+  if (typeof appKey !== "string" || appKey.trim() === "") {
+    throw new IQAuthError(
+      "VALIDATION_ERROR",
+      `appKey is required for ${callsite} (no env-var fallback, no 'product' alias).`,
+      400
+    );
+  }
+}
+function assertNodeKey(nodeKey, callsite) {
+  if (typeof nodeKey !== "string" || nodeKey.trim() === "") {
+    throw new IQAuthError("VALIDATION_ERROR", `nodeKey is required for ${callsite}.`, 400);
+  }
+}
 var PermissionGroupsModule = class {
   constructor(http) {
     this.http = http;
@@ -1322,7 +1422,14 @@ var PermissionGroupsModule = class {
     return this.http.request("GET", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions`);
   }
   async addPermission(tenantId, groupId, data) {
-    return this.http.request("POST", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions`, data);
+    assertAppKey(data?.appKey, "permissionGroups.addPermission");
+    assertNodeKey(data?.nodeKey, "permissionGroups.addPermission");
+    return this.http.request("POST", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions`, {
+      appKey: data.appKey,
+      nodeKey: data.nodeKey,
+      effect: data.effect,
+      weight: data.weight
+    });
   }
   async removePermission(tenantId, groupId, permissionId) {
     return this.http.request("DELETE", `/api/v1/tenants/${tenantId}/permission-groups/${groupId}/permissions/${permissionId}`);
@@ -1346,21 +1453,51 @@ var PermissionGroupsModule = class {
     return this.http.request("GET", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides`);
   }
   async addUserOverride(tenantId, userId, data) {
-    return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides`, data);
+    assertAppKey(data?.appKey, "permissionGroups.addUserOverride");
+    assertNodeKey(data?.nodeKey, "permissionGroups.addUserOverride");
+    return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides`, {
+      appKey: data.appKey,
+      nodeKey: data.nodeKey,
+      effect: data.effect,
+      weight: data.weight,
+      expiresAt: data.expiresAt
+    });
   }
   async removeUserOverride(tenantId, userId, overrideId) {
     return this.http.request("DELETE", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/overrides/${overrideId}`);
   }
+  /**
+   * Task #130 — `appKey` is REQUIRED. The legacy `product` query alias is no
+   * longer accepted at the SDK boundary; pass it as `appKey` instead. The
+   * server still accepts `product=` from raw HTTP callers during the
+   * deprecation window, but the SDK will not silently translate it.
+   */
   async getEffectivePermissions(tenantId, userId, params) {
-    const query = new URLSearchParams();
-    if (params.product) query.set("product", params.product);
-    if (params.appKey) query.set("appKey", params.appKey);
-    const qs = query.toString();
-    return this.http.request("GET", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/effective${qs ? `?${qs}` : ""}`);
+    assertAppKey(params?.appKey, "permissionGroups.getEffectivePermissions");
+    const qs = new URLSearchParams({ appKey: params.appKey }).toString();
+    return this.http.request("GET", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/effective?${qs}`);
   }
   async checkPermission(tenantId, userId, appKey, nodeKey) {
+    assertAppKey(appKey, "permissionGroups.checkPermission");
+    assertNodeKey(nodeKey, "permissionGroups.checkPermission");
     return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/check`, { appKey, nodeKey });
   }
+  /**
+   * Task #130 — every entry in `checks` must include a non-empty `appKey`
+   * AND `nodeKey`. The SDK validates the whole batch before sending so a
+   * single misconfigured entry can't slip through and silently report
+   * `allowed: false` from the server's per-entry validation branch.
+   */
+  async batchCheckPermissions(tenantId, userId, checks) {
+    if (!Array.isArray(checks) || checks.length === 0) {
+      throw new IQAuthError("VALIDATION_ERROR", "checks must be a non-empty array of { appKey, nodeKey }.", 400);
+    }
+    checks.forEach((c, i) => {
+      assertAppKey(c?.appKey, `permissionGroups.batchCheckPermissions[${i}]`);
+      assertNodeKey(c?.nodeKey, `permissionGroups.batchCheckPermissions[${i}]`);
+    });
+    return this.http.request("POST", `/api/v1/tenants/${tenantId}/users/${userId}/permissions/batch-check`, { checks });
+  }
 };
 
 // src/modules/apiKeys.ts
@@ -1785,6 +1922,10 @@ var IQAuthClient = class _IQAuthClient {
         this._refreshToken = tokens.refreshToken;
       },
       autoRefresh: "autoRefresh" in config ? config.autoRefresh !== false : true,
+      // `'app-state'` is mobile-only — on any other environment we treat it
+      // as the default `true` (proactive refresh ON). Only the mobile client
+      // disables proactive refresh and replaces it with an AppState listener.
+      proactiveRefresh: "autoRefresh" in config && config.autoRefresh === "app-state" && _IQAuthClient.resolveEnvironment(config) === "mobile" ? false : true,
       onTokenRefresh: "onTokenRefresh" in config ? config.onTokenRefresh : void 0,
       sessionHeaderName: config.sessionHeaderName,
       sessionHeaderValue: config.sessionHeaderValue,
@@ -1825,6 +1966,13 @@ var IQAuthClient = class _IQAuthClient {
   static forServer(config) {
     return new _IQAuthClient({ ...config, environment: "server" });
   }
+  /**
+   * Construct a mobile-environment client. NOTE: this constructor does NOT
+   * subscribe to React Native's `AppState` even when `autoRefresh: 'app-state'`
+   * is passed — it only disables the per-request proactive refresh. Use
+   * `createMobileClient` from `@iqauth/sdk/mobile` if you want the full
+   * AppState-driven refresh behavior (recommended for Expo / React Native).
+   */
   static forMobile(config) {
     return new _IQAuthClient({ ...config, environment: "mobile" });
   }
@@ -1841,6 +1989,18 @@ var IQAuthClient = class _IQAuthClient {
   getRefreshToken() {
     return this._refreshToken;
   }
+  /**
+   * Task #126: Eagerly fetch JWKS + OIDC discovery so the first verify() /
+   * refresh round-trip on the request hot path doesn't pay the discovery
+   * fetch latency. Safe to call repeatedly. Errors are swallowed; callers
+   * may fire-and-forget. Called automatically by `iqAuth({...}).attachHelpers()`.
+   */
+  async prewarm() {
+    await Promise.all([
+      this.tokens.prewarm(),
+      this.oidc.getDiscovery().catch(() => void 0)
+    ]);
+  }
   getCurrentClaims() {
     if (!this._accessToken) return null;
     return this.tokens.decode(this._accessToken);
@@ -1911,14 +2071,14 @@ function assertPublishableKey(raw, opts) {
   const ctx = opts?.context ? `${opts.context}: ` : "";
   if (typeof raw !== "string" || raw.length === 0) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key is missing. Set IQAUTH_PUBLISHABLE_KEY (or pass publishableKey) to a pk_test_\u2026 or pk_live_\u2026 value from the IQAuth admin console.`
     );
   }
   const shapeMatch = raw.match(/^pk_(test|live)_([A-Za-z0-9_-]+)$/);
   if (!shapeMatch) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key is malformed (got ${raw.slice(0, 12)}\u2026). Expected pk_test_\u2026 or pk_live_\u2026; regenerate the key from the IQAuth admin console.`
     );
   }
@@ -1927,19 +2087,19 @@ function assertPublishableKey(raw, opts) {
     decoded = JSON.parse(b64urlDecode(shapeMatch[2]));
   } catch {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key payload is not valid base64url JSON. Regenerate the key from the IQAuth admin console.`
     );
   }
   if (!isPublishableKeyPayload(decoded)) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key payload is missing required fields {iss, appId, tenantId, kid}. Regenerate the key from the IQAuth admin console.`
     );
   }
   if (!isValidIssuerUrl(decoded.iss)) {
     throw new IQAuthError(
-      "CONFIG_INVALID",
+      "config_invalid",
       `${ctx}IQAuth publishable key encodes an invalid issuer (iss=${JSON.stringify(decoded.iss)}). Expected a fully-qualified URL like "https://auth.example.com" (scheme required). Regenerate the key from the IQAuth admin console \u2014 the new key will encode a valid issuer URL.`
     );
   }
@@ -1959,12 +2119,18 @@ function isSecretKey(raw) {
 
 // src/middleware/express.ts
 var KNOWN_AUTH_ERROR_CODES = /* @__PURE__ */ new Set([
+  // Legacy UPPER_SNAKE codes (server-originated and SDK ≤2.6.x throws).
   "TOKEN_INVALID",
   "TOKEN_EXPIRED",
   "TOKEN_REVOKED",
   "SESSION_EXPIRED",
   "SESSION_INVALID",
-  "AUTH_REQUIRED"
+  "AUTH_REQUIRED",
+  // Task #127 — typed `IQAuthErrorCode` taxonomy thrown by `tokens.verify`.
+  // Mapped to 401 here so framework consumers don't have to learn the new
+  // codes to keep their auth-failure handling working.
+  "token_invalid",
+  "token_expired"
 ]);
 var DEFAULT_ACCESS_COOKIE = "iqauth_at";
 function getAuthorizationHeader(req) {
@@ -2146,6 +2312,185 @@ function iqAuthMiddleware(clientOrOptions, options = {}) {
   };
 }
 
+// src/server/handlers.ts
+async function buildUserinfoResponse(claims, opts = {}) {
+  const baseUser = {
+    sub: claims.sub,
+    email: claims.email,
+    name: claims.name,
+    tenantId: claims.tenantId,
+    vendorId: claims.vendorId,
+    roles: claims.roles ?? [],
+    entitlements: claims.entitlements ?? []
+  };
+  const enriched = opts.enrich ? await opts.enrich(claims) : null;
+  const user = enriched ? { ...baseUser, ...enriched } : baseUser;
+  return {
+    success: true,
+    data: {
+      user,
+      claims,
+      tenantId: claims.tenantId ?? null
+    }
+  };
+}
+var ACCESS_TOKEN_TTL_SECONDS = 60 * 15;
+var REFRESH_TOKEN_TTL_SECONDS = 60 * 60 * 24 * 30;
+function resolve(config) {
+  const parsed = assertPublishableKey(config.publishableKey, { context: "@iqauth/sdk helpers" });
+  const inferredIssuer = parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`;
+  return {
+    publishableKey: config.publishableKey,
+    secretKey: config.secretKey,
+    issuer: (config.issuer ?? inferredIssuer).replace(/\/+$/, ""),
+    accessCookieName: config.accessCookieName ?? config.cookieNames?.access ?? "iqauth_at",
+    refreshCookieName: config.refreshCookieName ?? config.cookieNames?.refresh ?? "iqauth_rt",
+    cookieDomain: config.cookieDomain,
+    sameSite: config.sameSite ?? "lax",
+    secure: config.secure ?? true,
+    cookiePath: config.cookiePath ?? "/",
+    tokenPath: config.tokenPath ?? "/oidc/token",
+    refreshPath: config.refreshPath ?? "/api/v1/auth/refresh",
+    logoutPath: config.logoutPath ?? "/api/v1/auth/logout",
+    fetchImpl: config.fetchImpl ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : (() => {
+      throw new Error("global fetch is unavailable; pass fetchImpl");
+    })),
+    appId: parsed.appId,
+    tenantId: parsed.tenantId,
+    clearCookiesOnRefreshFailure: config.clearCookiesOnRefreshFailure ?? "terminal-only",
+    debug: config.debug,
+    onTimingEvent: config.onTimingEvent,
+    signoutRegistry: config.signoutRegistry ?? defaultSignoutRegistry,
+    signoutMarkerTtlMs: config.signoutMarkerTtlMs ?? DEFAULT_SIGNOUT_TTL_MS
+  };
+}
+var DEFAULT_SIGNOUT_TTL_MS = 6e4;
+var inMemorySignoutMarkers = /* @__PURE__ */ new Map();
+function pruneInMemoryMarkers(now) {
+  if (inMemorySignoutMarkers.size === 0) return;
+  for (const [k, exp] of inMemorySignoutMarkers) {
+    if (exp <= now) inMemorySignoutMarkers.delete(k);
+  }
+}
+var defaultSignoutRegistry = {
+  mark(token, ttlMs) {
+    const now = Date.now();
+    pruneInMemoryMarkers(now);
+    inMemorySignoutMarkers.set(token, now + ttlMs);
+  },
+  has(token) {
+    const now = Date.now();
+    const exp = inMemorySignoutMarkers.get(token);
+    if (!exp) return false;
+    if (exp <= now) {
+      inMemorySignoutMarkers.delete(token);
+      return false;
+    }
+    return true;
+  }
+};
+var TOKENS_CACHE = /* @__PURE__ */ new Map();
+function getTokensFor(issuer) {
+  let m = TOKENS_CACHE.get(issuer);
+  if (!m) {
+    m = new TokensModule(issuer);
+    TOKENS_CACHE.set(issuer, m);
+  }
+  return m;
+}
+async function handleUserinfo(config, input) {
+  const cfg = resolve(config);
+  if (!input.accessToken) {
+    return {
+      status: 401,
+      body: { success: false, error: { code: "TOKEN_INVALID", message: "Missing access token" } },
+      cookies: []
+    };
+  }
+  let claims;
+  try {
+    claims = await getTokensFor(cfg.issuer).verify(input.accessToken, config.verify);
+  } catch (err) {
+    const code = err instanceof IQAuthError ? err.code : err.code || "TOKEN_INVALID";
+    const message = err instanceof Error ? err.message : "Access token verification failed";
+    return {
+      status: 401,
+      body: { success: false, error: { code, message } },
+      cookies: []
+    };
+  }
+  const envelope = await buildUserinfoResponse(claims, {
+    enrich: config.userinfoEnricher ? (c) => config.userinfoEnricher(c, input.req) : void 0
+  });
+  return {
+    status: 200,
+    body: envelope,
+    cookies: []
+  };
+}
+
+// src/permissions/wildcard.ts
+var SUFFIX = ".*";
+function wildcardPrefix(pattern) {
+  return pattern.slice(0, -SUFFIX.length);
+}
+function hasPermission(set, id) {
+  if (!id) return false;
+  if (!set) return false;
+  if (id === "*") {
+    for (const entry of set) if (entry === "*") return true;
+    return false;
+  }
+  const queryIsWildcard = id.endsWith(SUFFIX);
+  const queryPrefix = queryIsWildcard ? wildcardPrefix(id) : null;
+  for (const entry of set) {
+    if (!entry) continue;
+    if (entry === "*") return true;
+    if (entry === id) return true;
+    if (entry.endsWith(SUFFIX)) {
+      const prefix = wildcardPrefix(entry);
+      if (!queryIsWildcard) {
+        if (id === prefix) return true;
+        if (id.startsWith(prefix + ".")) return true;
+      } else {
+        if (queryPrefix === prefix) return true;
+        if (queryPrefix !== null && queryPrefix.startsWith(prefix + ".")) return true;
+      }
+    }
+  }
+  return false;
+}
+function expandPermissions(set) {
+  if (!set) return [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of set) {
+    if (typeof raw !== "string" || raw.length === 0) continue;
+    seen.add(raw);
+  }
+  if (seen.has("*")) return ["*"];
+  const wildcards = [];
+  for (const entry of seen) if (entry.endsWith(SUFFIX)) wildcards.push(entry);
+  const out = [];
+  for (const entry of seen) {
+    let covered = false;
+    for (const w of wildcards) {
+      if (w === entry) continue;
+      const prefix = wildcardPrefix(w);
+      if (entry === prefix) {
+        covered = true;
+        break;
+      }
+      if (entry.startsWith(prefix + ".")) {
+        covered = true;
+        break;
+      }
+    }
+    if (!covered) out.push(entry);
+  }
+  out.sort();
+  return out;
+}
+
 // src/ws.ts
 var DEFAULT_COOKIE = "iqauth_at";
 var DEFAULT_SUBPROTOCOL_PREFIX = "iqauth.bearer.";
@@ -2244,10 +2589,10 @@ function jwkFromPublicKey(publicKey, kid) {
   return { kty: "RSA", use: "sig", alg: "RS256", kid, n: jwk.n, e: jwk.e };
 }
 function readBody(req) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const chunks = [];
     req.on("data", (c) => chunks.push(c));
-    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("end", () => resolve2(Buffer.concat(chunks).toString("utf8")));
     req.on("error", reject);
   });
 }
@@ -2435,11 +2780,11 @@ async function createTestIssuer(options = {}) {
   const server = (0, import_http2.createServer)((req, res) => {
     void handler(req, res);
   });
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve2, reject) => {
     server.once("error", reject);
     server.listen(port, host, () => {
       server.off("error", reject);
-      resolve();
+      resolve2();
     });
   });
   const addr = server.address();
@@ -2463,8 +2808,8 @@ async function createTestIssuer(options = {}) {
       pendingCodes.set(code, { claims: opts, refreshToken });
       return code;
     },
-    close: () => new Promise((resolve, reject) => {
-      server.close((err) => err ? reject(err) : resolve());
+    close: () => new Promise((resolve2, reject) => {
+      server.close((err) => err ? reject(err) : resolve2());
     })
   };
 }
@@ -2478,6 +2823,12 @@ var WebhookSignatureError = class extends Error {
     this.code = code;
   }
 };
+var IQAUTH_SIGNATURE_HEADER = "x-iqauth-signature";
+var LEGACY_SIGNATURE_HEADERS = [
+  "x-webhook-signature",
+  "x-iq-auth-signature",
+  "x-signature"
+];
 function toBuffer(p) {
   if (typeof p === "string") return Buffer.from(p, "utf8");
   if (Buffer.isBuffer(p)) return p;
@@ -2486,13 +2837,19 @@ function toBuffer(p) {
 function parseHeader(header) {
   let t = NaN;
   const v1 = [];
-  for (const part of header.split(",")) {
-    const [k, v] = part.split("=", 2);
-    if (!k || v === void 0) continue;
-    const key = k.trim();
-    const value = v.trim();
+  const trimmed = header.trim();
+  if (/^[0-9a-f]+$/i.test(trimmed)) {
+    v1.push(trimmed.toLowerCase());
+    return { t, v1 };
+  }
+  for (const part of trimmed.split(",")) {
+    const eqIdx = part.indexOf("=");
+    if (eqIdx === -1) continue;
+    const key = part.slice(0, eqIdx).trim().toLowerCase();
+    const value = part.slice(eqIdx + 1).trim();
+    if (!value) continue;
     if (key === "t") t = Number(value);
-    else if (key === "v1") v1.push(value);
+    else if (key === "v1") v1.push(value.toLowerCase());
   }
   return { t, v1 };
 }
@@ -2504,6 +2861,11 @@ function timingSafeEqualHex(a, b) {
     return false;
   }
 }
+function computeSignatures(secret, body, t) {
+  const modern = import_crypto3.default.createHmac("sha256", secret).update(body).digest("hex");
+  const legacy = Number.isFinite(t) ? import_crypto3.default.createHmac("sha256", secret).update(`${t}.`).update(body).digest("hex") : null;
+  return { modern, legacy };
+}
 function verifyWebhookSignature(opts) {
   const headerRaw = Array.isArray(opts.header) ? opts.header[0] : opts.header;
   if (!headerRaw || typeof headerRaw !== "string") {
@@ -2513,20 +2875,27 @@ function verifyWebhookSignature(opts) {
     throw new WebhookSignatureError("MISSING_SECRET", "secret is required");
   }
   const { t, v1 } = parseHeader(headerRaw);
-  if (!Number.isFinite(t) || v1.length === 0) {
+  if (v1.length === 0) {
     throw new WebhookSignatureError("MALFORMED_HEADER", `Could not parse signature header: ${headerRaw}`);
   }
   const tolerance = opts.toleranceSeconds ?? 300;
-  const now = opts.nowSeconds ?? Math.floor(Date.now() / 1e3);
-  if (Math.abs(now - t) > tolerance) {
-    throw new WebhookSignatureError(
-      "TIMESTAMP_OUT_OF_TOLERANCE",
-      `Signature timestamp ${t} is outside the ${tolerance}s tolerance window (now=${now})`
-    );
+  if (Number.isFinite(t)) {
+    const now = opts.nowSeconds ?? Math.floor(Date.now() / 1e3);
+    if (Math.abs(now - t) > tolerance) {
+      throw new WebhookSignatureError(
+        "TIMESTAMP_OUT_OF_TOLERANCE",
+        `Signature timestamp ${t} is outside the ${tolerance}s tolerance window (now=${now})`
+      );
+    }
   }
   const body = toBuffer(opts.payload);
-  const expected = import_crypto3.default.createHmac("sha256", opts.secret).update(`${t}.`).update(body).digest("hex");
-  const matched = v1.some((sig) => timingSafeEqualHex(sig, expected));
+  const { modern, legacy } = computeSignatures(opts.secret, body, t);
+  const matched = v1.some((sig) => {
+    const lower = sig.toLowerCase();
+    if (timingSafeEqualHex(lower, modern)) return true;
+    if (legacy && timingSafeEqualHex(lower, legacy)) return true;
+    return false;
+  });
   if (!matched) {
     throw new WebhookSignatureError("SIGNATURE_MISMATCH", "Webhook signature does not match expected value");
   }
@@ -2546,6 +2915,125 @@ function isValidWebhookSignature(opts) {
     return false;
   }
 }
+function readHeader(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name);
+  }
+  const lower = name.toLowerCase();
+  const obj = headers;
+  if (lower in obj) return obj[lower];
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.toLowerCase() === lower) return v;
+  }
+  return void 0;
+}
+function pickHeaderValue(value) {
+  if (value == null) return null;
+  if (Array.isArray(value)) return value[0] ?? null;
+  return value;
+}
+function envelopeError(message) {
+  throw new WebhookSignatureError("MALFORMED_ENVELOPE", message);
+}
+function parseWebhookEvent(rawBody, headers, secrets, opts = {}) {
+  if (!Array.isArray(secrets) || secrets.length === 0 || secrets.every((s) => !s)) {
+    throw new WebhookSignatureError("MISSING_SECRET", "At least one signing secret is required");
+  }
+  let headerValue = pickHeaderValue(readHeader(headers, IQAUTH_SIGNATURE_HEADER));
+  let usedHeader = IQAUTH_SIGNATURE_HEADER;
+  if (!headerValue) {
+    for (const legacy of LEGACY_SIGNATURE_HEADERS) {
+      const v = pickHeaderValue(readHeader(headers, legacy));
+      if (v) {
+        headerValue = v;
+        usedHeader = legacy;
+        const log = opts.onDeprecation ?? ((m) => console.warn(m));
+        log(
+          `[iqauth] deprecation: webhook delivery used legacy header "${legacy}"; migrate sender to "X-IQAuth-Signature" (back-compat removed in next minor).`
+        );
+        break;
+      }
+    }
+  }
+  if (!headerValue) {
+    throw new WebhookSignatureError(
+      "MISSING_HEADER",
+      `Missing webhook signature header. Expected "X-IQAuth-Signature" (or one of: ${LEGACY_SIGNATURE_HEADERS.join(", ")}).`
+    );
+  }
+  const { t, v1 } = parseHeader(headerValue);
+  if (v1.length === 0) {
+    throw new WebhookSignatureError(
+      "MALFORMED_HEADER",
+      `Could not parse "${usedHeader}" header value: ${headerValue}`
+    );
+  }
+  const body = toBuffer(rawBody);
+  let verifiedIdx = -1;
+  for (let i = 0; i < secrets.length; i++) {
+    const secret = secrets[i];
+    if (!secret) continue;
+    const { modern, legacy } = computeSignatures(secret, body, t);
+    const ok = v1.some((sig) => {
+      const lower = sig.toLowerCase();
+      if (timingSafeEqualHex(lower, modern)) return true;
+      if (legacy && timingSafeEqualHex(lower, legacy)) return true;
+      return false;
+    });
+    if (ok) {
+      verifiedIdx = i;
+      break;
+    }
+  }
+  if (verifiedIdx === -1) {
+    throw new WebhookSignatureError(
+      "SIGNATURE_MISMATCH",
+      "Webhook signature does not match any provided secret"
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body.toString("utf8"));
+  } catch {
+    throw new WebhookSignatureError("MALFORMED_BODY", "Webhook body is not valid JSON");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    envelopeError("Webhook body must be a JSON object");
+  }
+  const { id, type, subject, time, data, tenantId, specversion } = parsed;
+  if (specversion !== "1.0") {
+    envelopeError(`Envelope \`specversion\` must be "1.0" (got: ${JSON.stringify(specversion)})`);
+  }
+  if (typeof id !== "string" || !id) envelopeError("Envelope missing required string `id`");
+  if (typeof type !== "string" || !type) envelopeError("Envelope missing required string `type`");
+  if (typeof subject !== "string" || !subject) envelopeError("Envelope missing required string `subject`");
+  if (typeof time !== "string" || !time) envelopeError("Envelope missing required string `time`");
+  if (typeof tenantId !== "string" || !tenantId) envelopeError("Envelope missing required string `tenantId`");
+  if (data === void 0 || data === null || typeof data !== "object" || Array.isArray(data)) {
+    envelopeError("Envelope `data` must be an object");
+  }
+  const tolerance = opts.toleranceSeconds ?? 300;
+  const eventMs = Date.parse(time);
+  if (!Number.isFinite(eventMs)) envelopeError(`Envelope \`time\` is not a valid ISO timestamp: ${time}`);
+  const nowMs = opts.nowMs ?? Date.now();
+  if (Math.abs(nowMs - eventMs) > tolerance * 1e3) {
+    throw new WebhookSignatureError(
+      "TIMESTAMP_OUT_OF_TOLERANCE",
+      `Envelope time ${time} is outside the ${tolerance}s tolerance window (now=${new Date(nowMs).toISOString()})`
+    );
+  }
+  return {
+    specversion: "1.0",
+    id,
+    type,
+    subject,
+    time,
+    tenantId,
+    data,
+    idempotencyKey: id,
+    verifiedWithSecretIndex: verifiedIdx
+  };
+}
 
 // src/server/provisioningBridge.ts
 function defaultIsUniqueViolation(err) {
@@ -2611,10 +3099,13 @@ function createProvisioningBridge(options) {
   ErrorCodes,
   GdprModule,
   HierarchyModule,
+  IQAUTH_SIGNATURE_HEADER,
   IQAuthClient,
   IQAuthError,
+  IQ_AUTH_ERROR_CODES,
   InMemoryOidcStateStore,
   InvitesModule,
+  LEGACY_SIGNATURE_HEADERS,
   MembershipsModule,
   MfaModule,
   OidcModule,
@@ -2632,14 +3123,19 @@ function createProvisioningBridge(options) {
   WebhookSignatureError,
   WebhooksModule,
   assertPublishableKey,
+  buildUserinfoResponse,
   createProvisioningBridge,
   createTestIssuer,
   encodePublishableKey,
+  expandPermissions,
+  handleUserinfo,
+  hasPermission,
   iqAuthMiddleware,
   isPublishableKey,
   isSecretKey,
   isValidWebhookSignature,
   parsePublishableKey,
+  parseWebhookEvent,
   verifyWebhookSignature,
   verifyWsUpgrade
 });