@iqauth/sdk 2.6.4 → 2.8.1

package/docs/guides/effective-permissions.md

@@ -0,0 +1,171 @@
+# Effective permissions: `useEffectivePermissions` + wildcard utilities
+
+Some IQAuth apps have hundreds of permission nodes. Stuffing the full set
+into the JWT `entitlements` claim is impractical — tokens grow past header
+limits and rotation gets expensive. The canonical pattern is:
+
+1. Keep the JWT small. Carry only the **roles** + a *coarse* subset of
+   `entitlements` for instant first-paint gating.
+2. Fetch the **full** effective permission set on demand from the issuer
+   and use it for fine-grained UI gating.
+3. Use the **same** wildcard semantics on the client and the server so the
+   two halves can never drift and produce the classic "user can see the
+   page but every API call 403s" foot-gun.
+
+The SDK ships:
+
+- `hasPermission(set, id)` and `expandPermissions(set)` — pure utilities
+  re-exported from `@iqauth/sdk`.
+- `useEffectivePermissions({ appKey })` — React hook in `@iqauth/sdk/react/permissions` (separate sub-entry so the main React entry never pulls in TanStack Query unless you actually use this hook). Re-exported from
+  `@iqauth/sdk/react`.
+
+## Wildcard semantics
+
+Permission ids are dot-separated keys: `metrics`, `metrics.read`,
+`billing.invoices.delete`. Two wildcard forms are supported:
+
+| Pattern         | Matches                                                       |
+| --------------- | ------------------------------------------------------------- |
+| `*`             | Every permission id (root wildcard).                          |
+| `<prefix>.*`    | `<prefix>` itself **and** every descendant.                   |
+
+Examples:
+
+- `metrics.*` matches `metrics`, `metrics.read`, `metrics.foo.bar`.
+- `metrics.*` does **not** match `metric`, `metricsX`, or
+  `billing.metrics`.
+- `*` matches everything, including any wildcard query.
+
+Wildcards in the middle of an id (e.g. `metrics.*.read`) are treated as
+literal strings and match nothing useful — keep wildcards at the leaf.
+
+`expandPermissions(set)` normalizes a set: dedupes, sorts, and strips
+entries already implied by a broader wildcard. It does **not** enumerate
+descendants of a wildcard (that set is open-ended).
+
+```ts
+import { expandPermissions, hasPermission } from "@iqauth/sdk";
+
+expandPermissions(["metrics.*", "metrics.read", "billing.read"]);
+// → ["billing.read", "metrics.*"]
+
+hasPermission(["metrics.*"], "metrics.foo.bar"); // true
+hasPermission(["metrics.read"], "metrics.write"); // false
+```
+
+## When to use the hook vs raw `entitlements`
+
+- **JWT `entitlements`** — instant, sync, available the moment the user is
+  authenticated. Good for top-level navigation gating where a small,
+  hand-picked subset is enough. **Hard size budget: keep `entitlements`
+  under ~50 entries to stay well under header limits across proxies.**
+- **`useEffectivePermissions()`** — async, network-backed, returns the
+  *complete* per-app set. Good for granular feature gating, action
+  buttons, admin-only fields. Cached for 5 minutes per
+  `(user, tenant, appKey)`.
+
+The hook automatically falls back to `claims.entitlements` while the
+fetch is in flight, so first paint is never blocked.
+
+## React usage
+
+The hook is backed by [TanStack Query](https://tanstack.com/query). The
+SDK declares `@tanstack/react-query` as an **optional** peer dependency
+— install it (`npm i @tanstack/react-query`) and mount a
+`QueryClientProvider` somewhere above `<IQAuthProvider/>`:
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { IQAuthProvider } from "@iqauth/sdk/react";
+
+const queryClient = new QueryClient();
+
+<QueryClientProvider client={queryClient}>
+  <IQAuthProvider publishableKey={…}>
+    <App />
+  </IQAuthProvider>
+</QueryClientProvider>
+```
+
+Then anywhere inside:
+
+```tsx
+import { SignedIn } from "@iqauth/sdk/react";
+import { useEffectivePermissions } from "@iqauth/sdk/react/permissions";
+
+function BillingPanel() {
+  const { permissions, hasPermission, isLoading, error, refetch } =
+    useEffectivePermissions({ appKey: "iqreuse" });
+
+  if (error) return <p>Couldn't load permissions: {error.message}</p>;
+
+  return (
+    <section aria-busy={isLoading}>
+      {hasPermission("billing.invoices.read") && <InvoiceList />}
+      {hasPermission("billing.invoices.write") && <NewInvoiceButton />}
+      {/* Wildcards work too — granted via `billing.*` or `*` */}
+      {hasPermission("billing.invoices.delete") && <DeleteInvoiceButton />}
+    </section>
+  );
+}
+```
+
+### What the hook returns
+
+```ts
+{
+  permissions: string[];                       // normalized set
+  hasPermission: (id: string) => boolean;      // wildcard-aware
+  isLoading: boolean;
+  error: { code: string; message: string } | null;
+  refetch: () => Promise<void>;                // bypass staleTime
+}
+```
+
+### Behaviour
+
+- **Caching.** Results are cached in-memory for 5 minutes per
+  `(issuer, tenantId, userId, appKey)`. Repeat mounts within the window
+  do not refetch. Override with `staleTime` (ms).
+- **Single-flight.** Concurrent renders/mounts share one in-flight
+  request — you will not see a thundering herd of `/permissions/effective`
+  calls when many components mount at once.
+- **No focus refetch.** The hook does **not** refetch on window focus.
+  Trigger `refetch()` after a mutation that changes permissions
+  (group assignment, role change, override write).
+- **Platform admin short-circuit.** If the JWT carries
+  `roles: ["platform_admin", …]` the hook returns `permissions: ["*"]`
+  and `hasPermission` always returns `true` without a network round trip.
+- **Entitlements fallback.** While the first fetch is in flight,
+  `permissions` is seeded from `claims.entitlements` so first paint isn't
+  blocked. The fetch result replaces this on success.
+
+### Endpoint shape
+
+The hook calls the existing issuer endpoint:
+
+```
+GET /api/v1/tenants/{tenantId}/users/{userId}/permissions/effective?appKey=<appKey>
+```
+
+It expects an `ApiResponse.success(...)` body whose `data` is an array of
+`{ scope: string; effect: "allow" | "deny"; … }` rows (the same shape
+returned by `permissionService.resolveEffectivePermissions`). Rows with
+`effect === "deny"` are stripped and the remaining `scope` strings are
+fed through `expandPermissions()`.
+
+No new server route is required.
+
+### Server-side parity
+
+Use the **same** utilities for server-side authorization checks so the
+two halves cannot drift:
+
+```ts
+import { hasPermission } from "@iqauth/sdk";
+
+// Inside an Express/Fastify/Hono route handler:
+if (!hasPermission(grantedPermissionSet, "billing.invoices.delete")) {
+  return res.status(403).json({ error: { code: "PERMISSION_DENIED" } });
+}
+```

package/docs/guides/invitations.md

@@ -33,11 +33,76 @@ const result = await client.invites.create({
   role: "user",
   vendorId: "vendor-uuid",        // optional
   products: ["iqcapture"],         // optional product access
+
+  // Optional: auto-land the invitee in your app after they accept
+  // (new users only — see "Auto-redirect after accept" below).
+  redirectUri: "https://app.example.com/iqauth/callback",
+  clientId: "oidc-client-id-for-your-app",
 });
 // result.inviteToken — for programmatic flows
 // In production, user receives email with invite link
 ```
 
+### Auto-redirect after accept (opt-in)
+
+Pass `redirectUri` + `clientId` together when creating the invite to have
+the hosted accept page mint an OIDC authorization code and `302` straight
+into your app after acceptance. The inviter app's existing
+`/api/iqauth/callback` adapter (Express / Fastify / Hono / Next) handles
+the code exchange — no SDK code changes required on the consumer side.
+
+**Constraints (validated at create time):**
+
+- Both fields must be present, or both omitted (half-pairs return `400`).
+- `clientId` must reference an **active OIDC client bound to the same tenant**
+  as the invite. Platform-wide clients (`tenant_id IS NULL`) are rejected.
+- `redirectUri` must match one of the client's registered redirect URIs,
+  using the same normalizing comparator as `/oidc/authorize` (trailing-slash
+  and case-insensitive host).
+- Both checks re-run at accept time; if the client/redirect config drifted
+  after the invite was sent, the accept silently falls back to the default
+  post-accept landing.
+
+**Response shape on `accept()`:**
+
+The `redirectTo` key is **omitted from the response entirely** (not `null`) when:
+
+- the invite was created without `redirectUri` + `clientId` (byte-for-byte back-compat),
+- the accepting user already had an IQAuth account (`existedUser === true`) — see
+  *Known limitations* below,
+- or the client/redirect config changed between create and accept.
+
+When present, `redirectTo` is a fully-qualified URL of the form
+`<redirectUri>?code=<oidc_code>&state=<random>`. Treat it as optional and
+only act on it when present.
+
+**Known limitations (v1):**
+
+- **Existing users.** When the invitee already has an IQAuth account, `redirectTo`
+  is suppressed. The accept endpoint is anonymous (the invite token is the only
+  credential) — minting an OIDC code for a pre-existing account would be an
+  auth-assurance downgrade for any account that has MFA configured.
+- **Multi-membership / scope picker.** Deferred for the same reason.
+- **PKCE / public clients.** The minted code is a confidential-client OIDC code.
+  Public-client / SPA flows that require PKCE are out of scope in v1.
+
+### Bulk-invite redirect
+
+`/api/v1/invites/bulk` accepts a single bulk-level `redirectUri` + `clientId`
+pair applied to every row, validated once before any rows are created:
+
+```typescript
+await client.invites.createBulk({
+  tenantId: "tenant-uuid",
+  invitations: [
+    { email: "alice@example.com", role: "user" },
+    { email: "bob@example.com", role: "user" },
+  ],
+  redirectUri: "https://app.example.com/iqauth/callback",
+  clientId: "oidc-client-id-for-your-app",
+});
+```
+
 ### 2. Validate Token
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iqauth/sdk",
-  "version": "2.6.4",
+  "version": "2.8.1",
   "description": "TypeScript SDK for IQAuth — the canonical way for all IQ projects to integrate with IQAuthService",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -29,6 +29,11 @@
       "import": "./dist/react.mjs",
       "require": "./dist/react.js"
     },
+    "./react/permissions": {
+      "types": "./dist/react-permissions.d.ts",
+      "import": "./dist/react-permissions.mjs",
+      "require": "./dist/react-permissions.js"
+    },
     "./server": {
       "types": "./dist/server.d.ts",
       "import": "./dist/server.mjs",
@@ -96,8 +101,10 @@
     "docs"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/browser-session.ts src/browser.ts src/react.ts src/server.ts src/server/handlers.ts src/express.ts src/fastify.ts src/hono.ts src/next.ts src/mobile.ts src/service.ts src/ws.ts src/test.ts src/webhooks.ts src/locales.ts src/cli/index.ts --format cjs,esm --dts --clean --external react --external react-dom --external next/headers",
-    "test": "vitest run",
+    "build": "tsup src/index.ts src/browser-session.ts src/browser.ts src/react.ts src/react-permissions.ts src/server.ts src/server/handlers.ts src/express.ts src/fastify.ts src/hono.ts src/next.ts src/mobile.ts src/service.ts src/ws.ts src/test.ts src/webhooks.ts src/locales.ts src/cli/index.ts --format cjs,esm --dts --clean --external react --external react-dom --external next/headers --external @tanstack/react-query",
+    "test": "vitest run && vitest run --config vitest.dom.config.mts",
+    "test:node": "vitest run",
+    "test:dom": "vitest run --config vitest.dom.config.mts",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit"
@@ -108,7 +115,8 @@
   },
   "peerDependencies": {
     "react": ">=18",
-    "react-dom": ">=18"
+    "react-dom": ">=18",
+    "@tanstack/react-query": ">=4"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -116,13 +124,20 @@
     },
     "react-dom": {
       "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@tanstack/react-query": "^5.60.5",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/jsonwebtoken": "^9.0.7",
     "@types/node": "^20.0.0",
     "@types/react": "^18.0.0",
     "@types/react-dom": "^18.0.0",
+    "jsdom": "^29.1.1",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
     "tsup": "^8.0.0",

package/dist/chunk-6TDJJER7.mjs

@@ -1,217 +0,0 @@
-import {
-  assertPublishableKey
-} from "./chunk-WQWBJSSS.mjs";
-
-// src/server/handlers.ts
-var TERMINAL_REFRESH_ERROR_CODES = /* @__PURE__ */ new Set([
-  "TOKEN_REVOKED",
-  "SESSION_REVOKED",
-  "INVALID_GRANT",
-  "invalid_grant",
-  "USER_DEACTIVATED",
-  "USER_DISABLED",
-  "TENANT_SUSPENDED"
-]);
-function shouldClearCookiesOnFailure(policy, status, errorCode) {
-  if (policy === "always") return true;
-  if (policy === "never") return false;
-  if (status === 410) return true;
-  if (errorCode && TERMINAL_REFRESH_ERROR_CODES.has(errorCode)) return true;
-  return false;
-}
-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"
-  };
-}
-function makeCookie(cfg, name, value, maxAge, httpOnly = true) {
-  return {
-    name,
-    value,
-    maxAge,
-    httpOnly,
-    secure: cfg.secure,
-    sameSite: cfg.sameSite,
-    path: cfg.cookiePath,
-    domain: cfg.cookieDomain
-  };
-}
-function clearCookies(cfg) {
-  return [
-    makeCookie(cfg, cfg.accessCookieName, "", 0),
-    makeCookie(cfg, cfg.refreshCookieName, "", 0)
-  ];
-}
-function serializeCookie(d) {
-  const parts = [`${d.name}=${encodeURIComponent(d.value)}`];
-  parts.push(`Path=${d.path}`);
-  if (d.domain) parts.push(`Domain=${d.domain}`);
-  parts.push(`Max-Age=${d.maxAge}`);
-  if (d.secure) parts.push("Secure");
-  if (d.httpOnly) parts.push("HttpOnly");
-  parts.push(`SameSite=${d.sameSite}`);
-  return parts.join("; ");
-}
-async function handleCallback(config, input) {
-  const cfg = resolve(config);
-  if (!input.code || !input.redirectUri) {
-    return {
-      status: 400,
-      body: { success: false, error: { code: "VALIDATION_ERROR", message: "code and redirectUri are required" } },
-      cookies: []
-    };
-  }
-  if (!cfg.secretKey) {
-    return {
-      status: 500,
-      body: { success: false, error: { code: "INTERNAL_ERROR", message: "secretKey is required for the callback handler" } },
-      cookies: []
-    };
-  }
-  const body = new URLSearchParams({
-    grant_type: "authorization_code",
-    code: input.code,
-    redirect_uri: input.redirectUri,
-    client_id: cfg.appId
-  });
-  if (input.codeVerifier) body.set("code_verifier", input.codeVerifier);
-  const res = await cfg.fetchImpl(`${cfg.issuer}${cfg.tokenPath}`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/x-www-form-urlencoded",
-      Authorization: `Basic ${typeof btoa === "function" ? btoa(`${cfg.appId}:${cfg.secretKey}`) : Buffer.from(`${cfg.appId}:${cfg.secretKey}`).toString("base64")}`
-    },
-    body: body.toString()
-  });
-  const json = await res.json().catch(() => ({}));
-  if (!res.ok || !json.access_token) {
-    return {
-      status: res.status || 502,
-      body: {
-        success: false,
-        error: {
-          code: json.error || "OIDC_EXCHANGE_FAILED",
-          message: json.error_description || "Authorization code exchange failed"
-        }
-      },
-      cookies: []
-    };
-  }
-  const cookies = [];
-  cookies.push(
-    makeCookie(cfg, cfg.accessCookieName, json.access_token, json.expires_in ?? ACCESS_TOKEN_TTL_SECONDS)
-  );
-  if (json.refresh_token) {
-    cookies.push(makeCookie(cfg, cfg.refreshCookieName, json.refresh_token, REFRESH_TOKEN_TTL_SECONDS));
-  }
-  return {
-    status: 200,
-    body: { success: true, data: { authenticated: true } },
-    cookies
-  };
-}
-async function handleRefresh(config, input) {
-  const cfg = resolve(config);
-  const refreshToken = input.refreshToken;
-  if (!refreshToken) {
-    return {
-      status: 401,
-      body: { success: false, error: { code: "TOKEN_INVALID", message: "Missing refresh token" } },
-      cookies: cfg.clearCookiesOnRefreshFailure === "always" ? clearCookies(cfg) : []
-    };
-  }
-  const res = await cfg.fetchImpl(`${cfg.issuer}${cfg.refreshPath}`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ refreshToken })
-  });
-  const json = await res.json().catch(() => ({}));
-  if (!res.ok || !json.success || !json.data?.accessToken) {
-    const status = res.status || 401;
-    const errorCode = json.error?.code || "TOKEN_INVALID";
-    const shouldClear = shouldClearCookiesOnFailure(
-      cfg.clearCookiesOnRefreshFailure,
-      status,
-      errorCode
-    );
-    return {
-      status,
-      body: {
-        success: false,
-        error: {
-          code: errorCode,
-          message: json.error?.message || "Refresh failed"
-        }
-      },
-      cookies: shouldClear ? clearCookies(cfg) : []
-    };
-  }
-  const cookies = [
-    makeCookie(cfg, cfg.accessCookieName, json.data.accessToken, ACCESS_TOKEN_TTL_SECONDS)
-  ];
-  if (json.data.refreshToken) {
-    cookies.push(makeCookie(cfg, cfg.refreshCookieName, json.data.refreshToken, REFRESH_TOKEN_TTL_SECONDS));
-  }
-  return {
-    status: 200,
-    body: { success: true, data: { accessToken: json.data.accessToken } },
-    cookies
-  };
-}
-async function handleSignout(config, input) {
-  const cfg = resolve(config);
-  if (input.accessToken) {
-    try {
-      await cfg.fetchImpl(`${cfg.issuer}${cfg.logoutPath}`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${input.accessToken}`
-        }
-      });
-    } catch {
-    }
-  }
-  if (input.endSsoSession !== false && input.ssoCookieHeader) {
-    try {
-      await cfg.fetchImpl(`${cfg.issuer}/oidc/sso-logout`, {
-        method: "POST",
-        headers: { Cookie: input.ssoCookieHeader }
-      });
-    } catch {
-    }
-  }
-  return {
-    status: 200,
-    body: { success: true, data: { signedOut: true } },
-    cookies: clearCookies(cfg)
-  };
-}
-
-export {
-  serializeCookie,
-  handleCallback,
-  handleRefresh,
-  handleSignout
-};

package/dist/chunk-UKZLOHZG.mjs

@@ -1,83 +0,0 @@
-// src/webhooks.ts
-import crypto from "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 crypto.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 = crypto.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;
-  }
-}
-
-export {
-  WebhookSignatureError,
-  verifyWebhookSignature,
-  isValidWebhookSignature
-};

package/dist/errors-CDdl24MP.d.mts

@@ -1,52 +0,0 @@
-/**
- * SOURCE REFS:
- * - Route file: src/lib/response.ts (error envelope: { success: false, error: { code, message } })
- * - All route files for error code extraction
- * - Verified claims: N/A (error module)
- * - Last verified: Phase 0 Research Summary
- */
-declare class IQAuthError extends Error {
-    code: string;
-    status?: number;
-    raw?: unknown;
-    constructor(code: string, message: string, status?: number, raw?: unknown);
-}
-declare const ErrorCodes: {
-    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
-    readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
-    readonly ACCOUNT_INACTIVE: "ACCOUNT_INACTIVE";
-    readonly ACCOUNT_LOCKED: "ACCOUNT_LOCKED";
-    readonly INSUFFICIENT_PERMISSIONS: "INSUFFICIENT_PERMISSIONS";
-    readonly TOKEN_INVALID: "TOKEN_INVALID";
-    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
-    readonly TOKEN_REVOKED: "TOKEN_REVOKED";
-    readonly USER_INACTIVE: "USER_INACTIVE";
-    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
-    readonly NOT_FOUND: "NOT_FOUND";
-    readonly SESSION_INVALID: "SESSION_INVALID";
-    readonly SESSION_EXPIRED: "SESSION_EXPIRED";
-    readonly REFRESH_TOKEN_REUSED: "REFRESH_TOKEN_REUSED";
-    readonly PASSWORD_EXPIRED: "PASSWORD_EXPIRED";
-    readonly PIN_EXPIRED: "PIN_EXPIRED";
-    readonly PASSWORD_POLICY_VIOLATION: "PASSWORD_POLICY_VIOLATION";
-    readonly MFA_INVALID_CODE: "MFA_INVALID_CODE";
-    readonly MFA_METHOD_UNAVAILABLE: "MFA_METHOD_UNAVAILABLE";
-    readonly MFA_RATE_LIMITED: "MFA_RATE_LIMITED";
-    readonly MFA_ENROLLMENT_REQUIRED: "MFA_ENROLLMENT_REQUIRED";
-    readonly API_KEY_REQUIRED: "API_KEY_REQUIRED";
-    readonly API_KEY_INVALID: "API_KEY_INVALID";
-    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
-    readonly ALREADY_EXISTS: "ALREADY_EXISTS";
-    readonly FORBIDDEN: "FORBIDDEN";
-    readonly OAUTH_NOT_CONFIGURED: "OAUTH_NOT_CONFIGURED";
-    readonly UPLOAD_ERROR: "UPLOAD_ERROR";
-    readonly EMAIL_SERVICE_UNAVAILABLE: "EMAIL_SERVICE_UNAVAILABLE";
-    readonly INVALID_CODE: "INVALID_CODE";
-    readonly CODE_ALREADY_USED: "CODE_ALREADY_USED";
-    readonly CODE_EXPIRED: "CODE_EXPIRED";
-    readonly CODE_IP_MISMATCH: "CODE_IP_MISMATCH";
-    readonly UNKNOWN_PAYLOAD: "UNKNOWN_PAYLOAD";
-};
-type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
-
-export { ErrorCodes as E, IQAuthError as I, type ErrorCode as a };