@iqauth/sdk 2.2.0 → 2.5.0

package/dist/types-6bNdxesb.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Catalog of all localizable strings used by the IQAuth SDK UI components and
+ * hosted auth pages. The shape is defined as a strict interface so missing
+ * keys in a contributed locale produce a TypeScript compile error.
+ *
+ * Strings may contain `{placeholder}` tokens that are interpolated at render
+ * time via `t(bundle, key, vars)`.
+ */
+interface IQAuthLocaleBundle {
+    /** BCP-47 tag for this bundle (e.g. "en-US", "fr-FR"). */
+    locale: string;
+    "common.loading": string;
+    "common.submitting": string;
+    "common.cancel": string;
+    "common.continue": string;
+    "common.back": string;
+    "common.close": string;
+    "common.save": string;
+    "common.saving": string;
+    "common.delete": string;
+    "common.confirm": string;
+    "common.email": string;
+    "common.password": string;
+    "common.name": string;
+    "common.or": string;
+    "common.required": string;
+    "common.optional": string;
+    "common.retry": string;
+    "signIn.title": string;
+    "signIn.subtitle": string;
+    "signIn.titleWithApp": string;
+    "signIn.emailLabel": string;
+    "signIn.emailPlaceholder": string;
+    "signIn.passwordLabel": string;
+    "signIn.passwordPlaceholder": string;
+    "signIn.submit": string;
+    "signIn.submitting": string;
+    "signIn.continueWithGoogle": string;
+    "signIn.continueWithMagicLink": string;
+    "signIn.continueWithPasskey": string;
+    "signIn.forgotPassword": string;
+    "signIn.noAccount": string;
+    "signIn.signUp": string;
+    "signIn.resumingSession": string;
+    "signIn.useDifferentAccount": string;
+    "signIn.selectTenant": string;
+    "signIn.selectTenantSubtitle": string;
+    "signIn.dividerOr": string;
+    "signIn.preparingExperience": string;
+    "signIn.applicationUnavailable": string;
+    "signIn.applicationNotFound": string;
+    "signIn.invalidRedirect": string;
+    "signIn.returnUrlNotRegistered": string;
+    "signIn.welcomeBackName": string;
+    "signIn.oneMomentResume": string;
+    "signIn.notYouUseDifferent": string;
+    "signIn.chooseWorkspace": string;
+    "signIn.pickTenantToSignIn": string;
+    "signIn.subtitleHosted": string;
+    "signIn.createAccount": string;
+    "signIn.couldntResume": string;
+    "signUp.title": string;
+    "signUp.subtitle": string;
+    "signUp.nameLabel": string;
+    "signUp.namePlaceholder": string;
+    "signUp.emailLabel": string;
+    "signUp.passwordLabel": string;
+    "signUp.passwordHint": string;
+    "signUp.submit": string;
+    "signUp.submitting": string;
+    "signUp.haveAccount": string;
+    "signUp.signIn": string;
+    "signUp.tenantNameLabel": string;
+    "signUp.tenantNamePlaceholder": string;
+    "signUp.legal": string;
+    "forgotPassword.title": string;
+    "forgotPassword.subtitle": string;
+    "forgotPassword.submit": string;
+    "forgotPassword.submitting": string;
+    "forgotPassword.sent": string;
+    "forgotPassword.backToSignIn": string;
+    "resetPassword.title": string;
+    "resetPassword.newPasswordLabel": string;
+    "resetPassword.confirmPasswordLabel": string;
+    "resetPassword.submit": string;
+    "resetPassword.submitting": string;
+    "resetPassword.success": string;
+    "resetPassword.mismatch": string;
+    "mfa.title": string;
+    "mfa.subtitle": string;
+    "mfa.totpLabel": string;
+    "mfa.totpPlaceholder": string;
+    "mfa.smsLabel": string;
+    "mfa.emailLabel": string;
+    "mfa.submit": string;
+    "mfa.submitting": string;
+    "mfa.useBackupCode": string;
+    "mfa.useAuthenticator": string;
+    "mfa.useSms": string;
+    "mfa.useEmail": string;
+    "mfa.resend": string;
+    "mfa.resent": string;
+    "mfa.backupCodeLabel": string;
+    "userButton.signedInAs": string;
+    "userButton.manageAccount": string;
+    "userButton.switchOrg": string;
+    "userButton.signOut": string;
+    "userProfile.title": string;
+    "userProfile.profileTab": string;
+    "userProfile.securityTab": string;
+    "userProfile.sessionsTab": string;
+    "userProfile.linkedAccountsTab": string;
+    "userProfile.changeName": string;
+    "userProfile.changeEmail": string;
+    "userProfile.changePassword": string;
+    "userProfile.currentPassword": string;
+    "userProfile.newPassword": string;
+    "userProfile.confirmPassword": string;
+    "userProfile.passwordUpdated": string;
+    "userProfile.mfaSection": string;
+    "userProfile.mfaEnable": string;
+    "userProfile.mfaDisable": string;
+    "userProfile.sessionsSection": string;
+    "userProfile.revokeSession": string;
+    "userProfile.revokeAllOthers": string;
+    "userProfile.thisDevice": string;
+    "userProfile.sessionsEmpty": string;
+    "userProfile.linkedAccountsEmpty": string;
+    "userProfile.connectGoogle": string;
+    "userProfile.disconnect": string;
+    "orgSwitcher.label": string;
+    "orgSwitcher.personal": string;
+    "orgSwitcher.createNew": string;
+    "orgSwitcher.manage": string;
+    "orgSwitcher.noOrgs": string;
+    "orgProfile.title": string;
+    "orgProfile.generalTab": string;
+    "orgProfile.membersTab": string;
+    "orgProfile.invitationsTab": string;
+    "orgProfile.dangerTab": string;
+    "orgProfile.invite": string;
+    "orgProfile.inviteEmailLabel": string;
+    "orgProfile.inviteRoleLabel": string;
+    "orgProfile.inviteSend": string;
+    "orgProfile.inviteSent": string;
+    "orgProfile.removeMember": string;
+    "orgProfile.deleteOrg": string;
+    "orgProfile.deleteOrgConfirm": string;
+    "createOrg.title": string;
+    "createOrg.nameLabel": string;
+    "createOrg.submit": string;
+    "createOrg.submitting": string;
+    "waitlist.title": string;
+    "waitlist.subtitle": string;
+    "waitlist.submit": string;
+    "waitlist.submitting": string;
+    "waitlist.success": string;
+    "impersonation.banner": string;
+    "impersonation.exit": string;
+    "magicLink.title": string;
+    "magicLink.subtitle": string;
+    "magicLink.resend": string;
+    "magicLink.changeEmail": string;
+    "errors.generic": string;
+    "errors.network": string;
+    "errors.invalidCredentials": string;
+    "errors.userNotFound": string;
+    "errors.emailInUse": string;
+    "errors.weakPassword": string;
+    "errors.mfaInvalid": string;
+    "errors.mfaExpired": string;
+    "errors.tooManyAttempts": string;
+    "errors.sessionExpired": string;
+    "errors.permissionDenied": string;
+    "errors.notFound": string;
+    "errors.serverError": string;
+    "errors.invalidEmail": string;
+    "errors.passwordTooShort": string;
+    "errors.required": string;
+    "errors.invitationInvalid": string;
+    "validation.emailRequired": string;
+    "validation.emailInvalid": string;
+    "validation.passwordRequired": string;
+    "validation.nameRequired": string;
+    "validation.codeRequired": string;
+    "validation.codeInvalid": string;
+}
+type IQAuthLocaleKey = keyof Omit<IQAuthLocaleBundle, "locale">;
+/**
+ * A partial bundle (used for the `localization` prop on IQAuthProvider) that
+ * may override a subset of keys; missing keys fall back to the default
+ * (en-US) bundle.
+ */
+type IQAuthLocaleOverride = Partial<IQAuthLocaleBundle>;
+
+export type { IQAuthLocaleBundle as I, IQAuthLocaleOverride as a, IQAuthLocaleKey as b };

package/dist/{types-Cxl3bQHt.d.ts → types-DZAflmmq.d.mts}

@@ -69,6 +69,12 @@ interface JwtClaims {
     iat?: number;
     scopeContext?: ScopeContext;
     loginMethod?: string;
+    purpose?: string;
+    act?: {
+        sub: string;
+        email?: string;
+        name?: string;
+    };
 }
 interface UserProfile {
     id: string;

package/dist/{types-Cxl3bQHt.d.mts → types-DZAflmmq.d.ts}

@@ -69,6 +69,12 @@ interface JwtClaims {
     iat?: number;
     scopeContext?: ScopeContext;
     loginMethod?: string;
+    purpose?: string;
+    act?: {
+        sub: string;
+        email?: string;
+        name?: string;
+    };
 }
 interface UserProfile {
     id: string;

package/dist/webhooks.d.mts

@@ -0,0 +1,61 @@
+/**
+ * @iqauth/sdk/webhooks — webhook signature verification.
+ *
+ * Mirrors Stripe's `constructEvent` shape. Verifies the `X-IQAuth-Signature`
+ * header (format `t=<unix>,v1=<hex hmac sha256>`) emitted by IQAuth's
+ * webhook fan-out (src/services/webhook.service.ts). Constant-time compare;
+ * tolerance window in seconds (default 300).
+ *
+ * Usage:
+ *   import { verifyWebhookSignature } from "@iqauth/sdk/webhooks";
+ *   app.post("/webhooks/iqauth", express.raw({ type: "application/json" }), (req, res) => {
+ *     try {
+ *       const evt = verifyWebhookSignature({
+ *         payload: req.body, // Buffer or string of the RAW request body
+ *         header: req.header("X-IQAuth-Signature"),
+ *         secret: process.env.IQAUTH_WEBHOOK_SECRET!,
+ *       });
+ *       // evt is the parsed JSON event
+ *     } catch (err) {
+ *       return res.status(400).send(err.message);
+ *     }
+ *   });
+ */
+interface VerifyWebhookOptions {
+    /** Raw HTTP request body (Buffer, Uint8Array, or string). DO NOT use a
+     * pre-parsed JSON object — the signature is over the exact bytes. */
+    payload: Buffer | Uint8Array | string;
+    /** Value of the `X-IQAuth-Signature` header. */
+    header: string | string[] | null | undefined;
+    /** The endpoint signing secret returned when the endpoint was created. */
+    secret: string;
+    /** How many seconds old a signature may be (default 300). */
+    toleranceSeconds?: number;
+    /** Override the current time (seconds since epoch) — for tests. */
+    nowSeconds?: number;
+}
+interface IQAuthWebhookEvent {
+    id?: string;
+    type?: string;
+    tenantId?: string;
+    data?: Record<string, unknown>;
+    createdAt?: number | string;
+    [key: string]: unknown;
+}
+declare class WebhookSignatureError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Verify the signature on a webhook payload and return the parsed event.
+ * Throws `WebhookSignatureError` on any verification failure.
+ */
+declare function verifyWebhookSignature(opts: VerifyWebhookOptions): IQAuthWebhookEvent;
+/**
+ * Boolean variant — never throws; returns `true` only if the signature is
+ * valid and the timestamp is within tolerance. Useful when you want to
+ * branch on validity rather than catch.
+ */
+declare function isValidWebhookSignature(opts: VerifyWebhookOptions): boolean;
+
+export { type IQAuthWebhookEvent, type VerifyWebhookOptions, WebhookSignatureError, isValidWebhookSignature, verifyWebhookSignature };

package/dist/webhooks.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @iqauth/sdk/webhooks — webhook signature verification.
+ *
+ * Mirrors Stripe's `constructEvent` shape. Verifies the `X-IQAuth-Signature`
+ * header (format `t=<unix>,v1=<hex hmac sha256>`) emitted by IQAuth's
+ * webhook fan-out (src/services/webhook.service.ts). Constant-time compare;
+ * tolerance window in seconds (default 300).
+ *
+ * Usage:
+ *   import { verifyWebhookSignature } from "@iqauth/sdk/webhooks";
+ *   app.post("/webhooks/iqauth", express.raw({ type: "application/json" }), (req, res) => {
+ *     try {
+ *       const evt = verifyWebhookSignature({
+ *         payload: req.body, // Buffer or string of the RAW request body
+ *         header: req.header("X-IQAuth-Signature"),
+ *         secret: process.env.IQAUTH_WEBHOOK_SECRET!,
+ *       });
+ *       // evt is the parsed JSON event
+ *     } catch (err) {
+ *       return res.status(400).send(err.message);
+ *     }
+ *   });
+ */
+interface VerifyWebhookOptions {
+    /** Raw HTTP request body (Buffer, Uint8Array, or string). DO NOT use a
+     * pre-parsed JSON object — the signature is over the exact bytes. */
+    payload: Buffer | Uint8Array | string;
+    /** Value of the `X-IQAuth-Signature` header. */
+    header: string | string[] | null | undefined;
+    /** The endpoint signing secret returned when the endpoint was created. */
+    secret: string;
+    /** How many seconds old a signature may be (default 300). */
+    toleranceSeconds?: number;
+    /** Override the current time (seconds since epoch) — for tests. */
+    nowSeconds?: number;
+}
+interface IQAuthWebhookEvent {
+    id?: string;
+    type?: string;
+    tenantId?: string;
+    data?: Record<string, unknown>;
+    createdAt?: number | string;
+    [key: string]: unknown;
+}
+declare class WebhookSignatureError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Verify the signature on a webhook payload and return the parsed event.
+ * Throws `WebhookSignatureError` on any verification failure.
+ */
+declare function verifyWebhookSignature(opts: VerifyWebhookOptions): IQAuthWebhookEvent;
+/**
+ * Boolean variant — never throws; returns `true` only if the signature is
+ * valid and the timestamp is within tolerance. Useful when you want to
+ * branch on validity rather than catch.
+ */
+declare function isValidWebhookSignature(opts: VerifyWebhookOptions): boolean;
+
+export { type IQAuthWebhookEvent, type VerifyWebhookOptions, WebhookSignatureError, isValidWebhookSignature, verifyWebhookSignature };

package/dist/webhooks.js

@@ -0,0 +1,119 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/webhooks.ts
+var webhooks_exports = {};
+__export(webhooks_exports, {
+  WebhookSignatureError: () => WebhookSignatureError,
+  isValidWebhookSignature: () => isValidWebhookSignature,
+  verifyWebhookSignature: () => verifyWebhookSignature
+});
+module.exports = __toCommonJS(webhooks_exports);
+var import_crypto = __toESM(require("crypto"));
+var WebhookSignatureError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "WebhookSignatureError";
+    this.code = code;
+  }
+};
+function toBuffer(p) {
+  if (typeof p === "string") return Buffer.from(p, "utf8");
+  if (Buffer.isBuffer(p)) return p;
+  return Buffer.from(p);
+}
+function parseHeader(header) {
+  let t = NaN;
+  const v1 = [];
+  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();
+    if (key === "t") t = Number(value);
+    else if (key === "v1") v1.push(value);
+  }
+  return { t, v1 };
+}
+function timingSafeEqualHex(a, b) {
+  if (a.length !== b.length) return false;
+  try {
+    return import_crypto.default.timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+  } catch {
+    return false;
+  }
+}
+function verifyWebhookSignature(opts) {
+  const headerRaw = Array.isArray(opts.header) ? opts.header[0] : opts.header;
+  if (!headerRaw || typeof headerRaw !== "string") {
+    throw new WebhookSignatureError("MISSING_HEADER", "Missing X-IQAuth-Signature header");
+  }
+  if (!opts.secret) {
+    throw new WebhookSignatureError("MISSING_SECRET", "secret is required");
+  }
+  const { t, v1 } = parseHeader(headerRaw);
+  if (!Number.isFinite(t) || 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})`
+    );
+  }
+  const body = toBuffer(opts.payload);
+  const expected = import_crypto.default.createHmac("sha256", opts.secret).update(`${t}.`).update(body).digest("hex");
+  const matched = v1.some((sig) => timingSafeEqualHex(sig, expected));
+  if (!matched) {
+    throw new WebhookSignatureError("SIGNATURE_MISMATCH", "Webhook signature does not match expected value");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body.toString("utf8"));
+  } catch {
+    throw new WebhookSignatureError("MALFORMED_BODY", "Webhook body is not valid JSON");
+  }
+  return parsed;
+}
+function isValidWebhookSignature(opts) {
+  try {
+    verifyWebhookSignature(opts);
+    return true;
+  } catch {
+    return false;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WebhookSignatureError,
+  isValidWebhookSignature,
+  verifyWebhookSignature
+});

package/dist/webhooks.mjs

@@ -0,0 +1,11 @@
+import {
+  WebhookSignatureError,
+  isValidWebhookSignature,
+  verifyWebhookSignature
+} from "./chunk-UKZLOHZG.mjs";
+import "./chunk-Y6FXYEAI.mjs";
+export {
+  WebhookSignatureError,
+  isValidWebhookSignature,
+  verifyWebhookSignature
+};

package/dist/ws.d.mts

@@ -0,0 +1,73 @@
+import { c as TokenVerifyOptions } from './tokens-DCyzzn8L.mjs';
+import { J as JwtClaims } from './types-DZAflmmq.mjs';
+
+/**
+ * @iqauth/sdk/ws — WebSocket upgrade auth helper.
+ *
+ * Realtime apps don't fit the HTTP framework-adapter shape: a Node WS server
+ * sees the original `IncomingMessage` on `upgrade` and must decide accept-or-
+ * reject before swapping protocols. This helper takes the same options shape
+ * as the framework middlewares (`publishableKey`, `audience`, `issuer`,
+ * `clockTolerance`, cookie name) and verifies a token from one of:
+ *
+ *   1. `Authorization: Bearer <jwt>` header on the upgrade request.
+ *   2. The configured access cookie (default `iqauth_at`) on the `Cookie`
+ *      header.
+ *   3. The `Sec-WebSocket-Protocol` subprotocol header. Browser `WebSocket`
+ *      can't set custom headers, so the convention is to publish the token
+ *      as a subprotocol value alongside the real subprotocol — e.g.
+ *      `new WebSocket(url, ["iqauth.bearer.<jwt>", "graphql-transport-ws"])`.
+ *      Any value matching `iqauth.bearer.<jwt>` (or a bare JWT-shaped value)
+ *      is treated as the bearer.
+ *
+ * Returns `{ claims }` on success, `null` on missing/invalid/expired token.
+ * Throws only on programmer error (no publishable key, etc).
+ *
+ *   import { verifyWsUpgrade } from "@iqauth/sdk/ws";
+ *   wss.on("upgrade", async (req, socket, head) => {
+ *     const result = await verifyWsUpgrade(req, { publishableKey });
+ *     if (!result) { socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n"); socket.destroy(); return; }
+ *     wss.handleUpgrade(req, socket, head, ws => wss.emit("connection", ws, req, result.claims));
+ *   });
+ */
+
+interface VerifyWsUpgradeOptions extends TokenVerifyOptions {
+    /** A `pk_test_…` / `pk_live_…` publishable key. Issuer + JWKS auto-discovered. */
+    publishableKey: string;
+    /**
+     * Cookie name carrying an httpOnly access token. Defaults to `iqauth_at`.
+     * Set to `null` to disable cookie-based extraction.
+     */
+    cookieName?: string | null;
+    /**
+     * Subprotocol prefix recognized as a bearer token in
+     * `Sec-WebSocket-Protocol`. Defaults to `iqauth.bearer.`. Set to `null`
+     * to disable subprotocol-based extraction.
+     */
+    subprotocolPrefix?: string | null;
+}
+/**
+ * The minimum shape we read off a Node `IncomingMessage`. Accepting just
+ * `{ headers }` keeps the helper testable and framework-agnostic.
+ */
+interface WsUpgradeRequestLike {
+    headers: Record<string, string | string[] | undefined>;
+}
+interface VerifyWsUpgradeResult {
+    claims: JwtClaims;
+}
+/**
+ * Verify a WebSocket upgrade request. Returns `{ claims }` on success or
+ * `null` when the request lacks a token, the token is malformed, expired,
+ * or fails verification. Throws only when `options.publishableKey` is
+ * missing or malformed (programmer error).
+ */
+declare function verifyWsUpgrade(req: WsUpgradeRequestLike | {
+    cookie?: string;
+    secWebSocketProtocol?: string;
+    authorization?: string;
+}, options: VerifyWsUpgradeOptions): Promise<VerifyWsUpgradeResult | null>;
+/** @internal Test helper — clear the per-issuer TokensModule cache. */
+declare function _resetWsVerifierCache(): void;
+
+export { type VerifyWsUpgradeOptions, type VerifyWsUpgradeResult, type WsUpgradeRequestLike, _resetWsVerifierCache, verifyWsUpgrade };

package/dist/ws.d.ts

@@ -0,0 +1,73 @@
+import { c as TokenVerifyOptions } from './tokens-aHiGFr_E.js';
+import { J as JwtClaims } from './types-DZAflmmq.js';
+
+/**
+ * @iqauth/sdk/ws — WebSocket upgrade auth helper.
+ *
+ * Realtime apps don't fit the HTTP framework-adapter shape: a Node WS server
+ * sees the original `IncomingMessage` on `upgrade` and must decide accept-or-
+ * reject before swapping protocols. This helper takes the same options shape
+ * as the framework middlewares (`publishableKey`, `audience`, `issuer`,
+ * `clockTolerance`, cookie name) and verifies a token from one of:
+ *
+ *   1. `Authorization: Bearer <jwt>` header on the upgrade request.
+ *   2. The configured access cookie (default `iqauth_at`) on the `Cookie`
+ *      header.
+ *   3. The `Sec-WebSocket-Protocol` subprotocol header. Browser `WebSocket`
+ *      can't set custom headers, so the convention is to publish the token
+ *      as a subprotocol value alongside the real subprotocol — e.g.
+ *      `new WebSocket(url, ["iqauth.bearer.<jwt>", "graphql-transport-ws"])`.
+ *      Any value matching `iqauth.bearer.<jwt>` (or a bare JWT-shaped value)
+ *      is treated as the bearer.
+ *
+ * Returns `{ claims }` on success, `null` on missing/invalid/expired token.
+ * Throws only on programmer error (no publishable key, etc).
+ *
+ *   import { verifyWsUpgrade } from "@iqauth/sdk/ws";
+ *   wss.on("upgrade", async (req, socket, head) => {
+ *     const result = await verifyWsUpgrade(req, { publishableKey });
+ *     if (!result) { socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n"); socket.destroy(); return; }
+ *     wss.handleUpgrade(req, socket, head, ws => wss.emit("connection", ws, req, result.claims));
+ *   });
+ */
+
+interface VerifyWsUpgradeOptions extends TokenVerifyOptions {
+    /** A `pk_test_…` / `pk_live_…` publishable key. Issuer + JWKS auto-discovered. */
+    publishableKey: string;
+    /**
+     * Cookie name carrying an httpOnly access token. Defaults to `iqauth_at`.
+     * Set to `null` to disable cookie-based extraction.
+     */
+    cookieName?: string | null;
+    /**
+     * Subprotocol prefix recognized as a bearer token in
+     * `Sec-WebSocket-Protocol`. Defaults to `iqauth.bearer.`. Set to `null`
+     * to disable subprotocol-based extraction.
+     */
+    subprotocolPrefix?: string | null;
+}
+/**
+ * The minimum shape we read off a Node `IncomingMessage`. Accepting just
+ * `{ headers }` keeps the helper testable and framework-agnostic.
+ */
+interface WsUpgradeRequestLike {
+    headers: Record<string, string | string[] | undefined>;
+}
+interface VerifyWsUpgradeResult {
+    claims: JwtClaims;
+}
+/**
+ * Verify a WebSocket upgrade request. Returns `{ claims }` on success or
+ * `null` when the request lacks a token, the token is malformed, expired,
+ * or fails verification. Throws only when `options.publishableKey` is
+ * missing or malformed (programmer error).
+ */
+declare function verifyWsUpgrade(req: WsUpgradeRequestLike | {
+    cookie?: string;
+    secWebSocketProtocol?: string;
+    authorization?: string;
+}, options: VerifyWsUpgradeOptions): Promise<VerifyWsUpgradeResult | null>;
+/** @internal Test helper — clear the per-issuer TokensModule cache. */
+declare function _resetWsVerifierCache(): void;
+
+export { type VerifyWsUpgradeOptions, type VerifyWsUpgradeResult, type WsUpgradeRequestLike, _resetWsVerifierCache, verifyWsUpgrade };