@iqauth/sdk 2.2.0 → 2.5.0

package/README.md

@@ -23,6 +23,8 @@ The canonical TypeScript SDK for **IQAuthService** — DispositionIQ's multi-ten
 - [Token verification without a framework adapter](#token-verification-without-a-framework-adapter)
 - [Native mobile (PKCE)](#native-mobile-pkce)
 - [Service automation / API keys](#service-automation--api-keys)
+- [Realtime: WebSocket upgrade verification](#realtime-websocket-upgrade-verification)
+- [Integration testing with `createTestIssuer`](#integration-testing-with-createtestissuer)
 - [Hosted auth pages and branding](#hosted-auth-pages-and-branding)
 - [CLI](#cli)
 - [Error handling](#error-handling)
@@ -388,6 +390,77 @@ API-key calls are scoped to the permissions granted at creation time and are sub
 
 ---
 
+## Realtime: WebSocket upgrade verification
+
+`@iqauth/sdk/ws` exposes a single `verifyWsUpgrade(req, options)` helper for Node WebSocket servers. Same option shape as the framework middlewares — `publishableKey`, `audience`, `issuer`, `clockTolerance`, cookie name. Returns `{ claims }` on success or `null` on missing/invalid/expired tokens.
+
+It accepts a token from any of:
+
+1. `Authorization: Bearer <jwt>` header.
+2. The `iqauth_at` cookie on the upgrade request (override with `cookieName`).
+3. The `Sec-WebSocket-Protocol` subprotocol value `iqauth.bearer.<jwt>` — browser `WebSocket` can't set custom headers, so the convention is to publish the token as a subprotocol value alongside the real one (e.g. `new WebSocket(url, ["iqauth.bearer." + token, "graphql-transport-ws"])`).
+
+```ts
+import { WebSocketServer } from "ws";
+import { verifyWsUpgrade } from "@iqauth/sdk/ws";
+
+const wss = new WebSocketServer({ noServer: true });
+
+httpServer.on("upgrade", async (req, socket, head) => {
+  const result = await verifyWsUpgrade(req, {
+    publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!,
+    audience: "dispositioniq",
+  });
+  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);
+  });
+});
+```
+
+A consumer can replace IQValidate's hand-rolled `packages/shared/src/websocket-server.ts authenticateUser()` with one import and one call.
+
+---
+
+## Integration testing with `createTestIssuer`
+
+`@iqauth/sdk/test` spawns an in-process HTTP server that exposes a JWKS endpoint, an OIDC discovery doc, a token endpoint that accepts code-exchange calls, and a `/api/v1/auth/me` userinfo endpoint. It mints valid RS256 JWTs against a freshly generated keypair, so integration tests don't need a live IQAuth.
+
+```ts
+import { createTestIssuer } from "@iqauth/sdk/test";
+
+let issuer;
+beforeAll(async () => { issuer = await createTestIssuer({ port: 0 }); });
+afterAll(async () => { await issuer.close(); });
+
+it("admin can list users", async () => {
+  const token = issuer.mintToken({ sub: "u1", roles: ["tenant_admin"] });
+  const r = await fetch("http://localhost:3000/api/users", {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(r.status).toBe(200);
+});
+```
+
+Point your SDK / React provider at `issuer.baseUrl` — or pass `issuer.publishableKey`, which already encodes the right `iss`. To exercise the full code-exchange flow:
+
+```ts
+const code = issuer.mintAuthCode({ sub: "u1", roles: ["tenant_admin"] });
+const tokens = await fetch(`${issuer.baseUrl}/oidc/token`, {
+  method: "POST",
+  headers: { "Content-Type": "application/x-www-form-urlencoded" },
+  body: new URLSearchParams({ grant_type: "authorization_code", code }),
+}).then((r) => r.json());
+```
+
+Out of scope: the test issuer does not mock SSO providers (Google, Microsoft) and does not replicate the full DispositionIQ admin/permissions API surface — it implements exactly enough to satisfy the SDK's verify path and the common code-exchange flow.
+
+---
+
 ## Hosted auth pages and branding
 
 Sign-in, sign-up, forgot-password, and account pages are hosted at `auth.dispositioniq.com`. They render with your app's brand once you set CSS variables in the admin dashboard:
@@ -477,6 +550,48 @@ Common codes you'll handle:
 
 ---
 
+## Don't intercept `/sign-in?code=…`
+
+If your app uses an SSO bridge route (e.g. `your-app.com/sign-in` redirects users to `auth.dispositioniq.com`) and that same route is **also** the configured OAuth `redirect_uri`, your bridge logic will fire on the return trip and immediately bounce the user back to the issuer **before** the SDK can exchange the `?code=` for tokens. Symptoms: an infinite redirect loop, or a successful login that the app never sees.
+
+**Pick one:**
+
+1. **Recommended — use a dedicated callback path.** Configure `redirect_uri` to point at `/api/iqauth/callback` (the helper route mounted by `iqAuth({...}).attachHelpers(app)` for Express, or by `iqAuth({...})` for Next/Fastify/Hono). Your `/sign-in` route stays purely a "send user to the issuer" bridge.
+
+2. **If you must reuse `/sign-in` as the redirect target,** guard the bridge:
+
+   ```ts
+   app.get("/sign-in", (req, res, next) => {
+     // OAuth return trip — let the SDK handle it, don't redirect away.
+     if (req.query.code || req.query.error) return next();
+     return res.redirect(buildIssuerAuthorizeUrl(req));
+   });
+   ```
+
+   …and add `inlineCallback: true` to your `iqAuth({...})` options so a GET handler is mounted on the callback path to complete the exchange and 302 to the final destination.
+
+This is the single most common bug we see when teams add IQAuth to an app that already had its own session redirect logic.
+
+---
+
+## Migrating from Clerk's backend SDK
+
+If you're moving from `@clerk/backend` to `@iqauth/sdk`, the surface is intentionally close but not identical. The full audit lives at [`docs/backend-sdk-parity.md`](../../docs/backend-sdk-parity.md); the high-leverage deltas:
+
+- **Vocabulary.** Clerk's `organization` is IQAuth's `tenant`. `Clerk.users.banUser(id)` ↔ `iqauth.users.deactivate(id)`; `unbanUser` ↔ `reactivate`. The IQAuth modules are `tenants`, `memberships`, `roles`, `invites` — together they cover what Clerk packs into `organizations`.
+- **Tenant scoping is explicit.** `users.create` takes `(tenantId, data)` rather than implying it from the API key. List endpoints (`users.list`, `tenants.list`, `memberships.listForTenant`) accept tenant filters.
+- **Pagination + filters are still partial.** `users.list({ email, tenantId })` and `tenants.list({ vendorId })` work today, but Clerk-style `{ limit, offset, query, orderBy }` is on the near-term roadmap. Bulk-import scripts that page through tens of thousands of users should call the REST API directly until the helpers ship.
+- **Admin-side user mutations.** `users.update(...)` in this SDK currently updates **only the calling user** (name, picture). Admin-on-behalf-of `update` / `delete` / `verifyPassword` and a `passwordDigest` import path for `users.create` are tracked as follow-ups; until then, use the REST API or the admin console.
+- **Invitations.** `invites.create / validate / accept` are present. `invites.list` (pending) and `invites.revoke` are not in the SDK yet — same for the equivalent organization-invitation calls; tracked as follow-ups.
+- **Sessions.** `sessions.list / revoke / revokeAll` are scoped to the **current user**. There is no admin-side `sessions.getSessionList({ userId })` yet; tracked as a follow-up.
+- **Webhook signature verification.** Clerk wraps Svix's `Webhook.verify(payload, headers)`. IQAuth ships endpoint CRUD + delivery history + secret rotation, but receivers must verify HMAC signatures by hand today. A `webhooks.verifySignature(...)` helper is in flight under the existing rotation task.
+- **Actor / impersonation tokens.** Tracked separately (see internal task F23 / #86). Not yet in the SDK.
+- **Won't do.** JWT templates and per-instance domain CRUD are Clerk-specific and don't map to IQAuth's product surface. See the audit doc for documented alternatives.
+
+For anything in the "won't do" / "different shape" rows of the audit, prefer the linked alternative over reaching back into REST — those alternatives are the supported path.
+
+---
+
 ## Bundled docs
 
 Long-form integration guides ship **inside the npm tarball** at `node_modules/@iqauth/sdk/docs/`. List them with:
@@ -504,3 +619,22 @@ These are also kept on the IQAuth admin dashboard's documentation tab.
 ## License
 
 Proprietary — DispositionIQ internal use. See the LICENSE/usage terms in the bundled docs.
+
+
+---
+
+## Deploying with Docker / Next.js (read this before you ship)
+
+The publishable key is baked into your build. NEXT_PUBLIC_* and VITE_* variables are inlined at build time, not run time. A docker image built against your staging issuer will continue to point at staging even when you later run it with -e NEXT_PUBLIC_IQAUTH_PUBLISHABLE_KEY=pk_live_xyz — Next.js / Vite have no way to re-resolve the constant after the bundle is emitted.
+
+Two safe patterns:
+
+1. Build the image per-environment (recommended for separate prod/stage stacks). Use ARG and ENV in the Dockerfile and pass --build-arg NEXT_PUBLIC_IQAUTH_PUBLISHABLE_KEY=pk_live_xyz at docker build time.
+
+2. Read the key at request time on the server (single image, multi-env): fetch the publishable key in getServerSideProps / a Next.js Route Handler / your Express bootstrap and pass it to <IQAuthProvider publishableKey={...}> as a runtime prop. Server-side env vars ARE re-read on every container start, so the same image deploys to any environment.
+
+Verify the build before you push: the iqauth doctor CLI compares the issuer encoded in your publishable key against the issuers discovery document and warns when they disagree:
+
+    npx iqauth doctor --issuer https://auth.example.com --publishable-key $NEXT_PUBLIC_IQAUTH_PUBLISHABLE_KEY
+
+Wire this into CI right after next build and youll catch a wrong-environment publishable key before the image ships.

package/dist/browser-session.d.mts

@@ -1,7 +1,7 @@
-import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-Cxl3bQHt.mjs';
-import { I as IQAuthClient } from './client-Dv4v92Mj.mjs';
+import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-DZAflmmq.mjs';
+import { I as IQAuthClient } from './client-kYlJFgPv.mjs';
 export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
-import 'jsonwebtoken';
+import './tokens-DCyzzn8L.mjs';
 
 declare class BrowserSessionIQAuthClient extends IQAuthClient {
     constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);

package/dist/browser-session.d.ts

@@ -1,7 +1,7 @@
-import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-Cxl3bQHt.js';
-import { I as IQAuthClient } from './client-DXbHb2ul.js';
+import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-DZAflmmq.js';
+import { I as IQAuthClient } from './client-BNQe3AgF.js';
 export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
-import 'jsonwebtoken';
+import './tokens-aHiGFr_E.js';
 
 declare class BrowserSessionIQAuthClient extends IQAuthClient {
     constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);

package/dist/browser-session.js

@@ -446,8 +446,7 @@ function parseMfaResponse(data, browserSessionMode) {
 }
 
 // src/modules/tokens.ts
-var import_crypto = __toESM(require("crypto"));
-var import_jsonwebtoken = __toESM(require("jsonwebtoken"));
+var import_jose = require("jose");
 var JWKS_CACHE_TTL_MS = 60 * 60 * 1e3;
 var DEFAULT_TOKEN_ISSUER = [
   "https://auth.dispositioniq.com",
@@ -460,6 +459,24 @@ var DEFAULT_TOKEN_AUDIENCE = [
   "iqvalidate"
 ];
 var DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+function decodeProtectedHeader(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) return null;
+  try {
+    const padded = parts[0] + "=".repeat((4 - parts[0].length % 4) % 4);
+    const b64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+    let json;
+    if (typeof atob === "function") {
+      json = atob(b64);
+    } else {
+      const { Buffer: Buffer2 } = require("buffer");
+      json = Buffer2.from(b64, "base64").toString("utf8");
+    }
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
 var TokensModule = class {
   constructor(baseUrl, options = {}) {
     this.jwksCache = null;
@@ -470,49 +487,49 @@ var TokensModule = class {
     this.defaultClockTolerance = options.clockTolerance ?? DEFAULT_CLOCK_TOLERANCE_SECONDS;
   }
   /**
-   * Verify a JWT access token using RS256 via JWKS from /.well-known/jwks.json.
-   * Caches JWKS keys for 1 hour. Retries once on unknown `kid`.
-   *
-   * @remarks Validates against /.well-known/jwks.json. Issuer, audience, and
-   * clock tolerance default to client config but can be overridden per call.
+   * Verify a JWT access token using RS256/ES256 via JWKS from
+   * `/.well-known/jwks.json`. Backed by `jose` (Web Crypto) so it runs on
+   * Node, browser, and edge runtimes alike — no `node:crypto` dependency.
+   * Caches JWKS for 1 hour and refetches once on unknown `kid`.
    */
   async verify(token, options = {}) {
-    const decoded = import_jsonwebtoken.default.decode(token, { complete: true });
-    if (!decoded || typeof decoded === "string") {
+    const header = decodeProtectedHeader(token);
+    if (!header) {
       throw new IQAuthError("TOKEN_INVALID", "Unable to decode token");
     }
-    const kid = decoded.header.kid;
+    const kid = header.kid;
     if (!kid) {
       throw new IQAuthError("TOKEN_INVALID", "Token missing kid header");
     }
-    let publicKey = await this.getPublicKey(kid);
-    if (!publicKey) {
-      await this.refreshJwks();
-      publicKey = await this.getPublicKey(kid);
+    let cache = await this.ensureCache();
+    if (!cache.byKid.has(kid)) {
+      this.jwksCache = null;
+      cache = await this.ensureCache();
     }
-    if (!publicKey) {
+    if (!cache.byKid.has(kid)) {
       throw new IQAuthError("TOKEN_INVALID", `Unknown key ID: ${kid}`);
     }
     const issuer = options.issuer ?? this.defaultIssuer;
     const audience = options.audience ?? this.defaultAudience;
     const clockTolerance = options.clockTolerance ?? this.defaultClockTolerance;
-    const algorithms = options.algorithms ?? ["RS256"];
+    const algorithms = options.algorithms ?? ["RS256", "ES256"];
+    const verifyOptions = {
+      algorithms,
+      clockTolerance,
+      issuer,
+      audience
+    };
     try {
-      const verifyOptions = {
-        algorithms,
-        clockTolerance,
-        // The jsonwebtoken types insist on tuple types for arrays; runtime
-        // accepts plain string[] so we cast to satisfy the compiler.
-        issuer,
-        audience
-      };
-      const verified = import_jsonwebtoken.default.verify(token, publicKey, verifyOptions);
-      return verified;
+      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) {
-        if (err.name === "TokenExpiredError") {
-          throw new IQAuthError("TOKEN_EXPIRED", "Token has expired");
-        }
         throw new IQAuthError("TOKEN_INVALID", err.message);
       }
       throw new IQAuthError("TOKEN_INVALID", "Token verification failed");
@@ -520,29 +537,40 @@ var TokensModule = class {
   }
   /**
    * Decode a JWT without verification. Returns null if malformed.
-   *
-   * @remarks Local decode only — no network call
    */
   decode(token) {
-    const decoded = import_jsonwebtoken.default.decode(token);
-    return decoded;
+    try {
+      const parts = token.split(".");
+      if (parts.length < 2) return null;
+      const payload = parts[1];
+      const padded = payload + "=".repeat((4 - payload.length % 4) % 4);
+      const b64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+      let json;
+      if (typeof atob === "function") {
+        json = atob(b64);
+      } else {
+        const { Buffer: Buffer2 } = require("buffer");
+        json = Buffer2.from(b64, "base64").toString("utf8");
+      }
+      try {
+        json = decodeURIComponent(escape(json));
+      } catch {
+      }
+      const claims = JSON.parse(json);
+      if (!claims || typeof claims !== "object") return null;
+      return claims;
+    } catch {
+      return null;
+    }
   }
-  /**
-   * Check if a token is expired based on the `exp` claim.
-   *
-   * @remarks Local check only — no network call
-   */
+  /** Check if a token is expired based on the `exp` claim. */
   isExpired(token) {
     const claims = this.decode(token);
     if (!claims?.exp) return true;
     const now = Math.floor(Date.now() / 1e3);
     return claims.exp <= now;
   }
-  /**
-   * Get the claims from a token without verification.
-   *
-   * @remarks Local decode only — no network call
-   */
+  /** Get the claims from a token without verification. */
   getClaims(token) {
     const claims = this.decode(token);
     if (!claims) {
@@ -550,11 +578,15 @@ var TokensModule = class {
     }
     return claims;
   }
-  async getPublicKey(kid) {
-    if (!this.jwksCache || Date.now() - this.jwksCache.fetchedAt > JWKS_CACHE_TTL_MS) {
-      await this.refreshJwks();
+  async ensureCache() {
+    if (this.jwksCache && Date.now() - this.jwksCache.fetchedAt <= JWKS_CACHE_TTL_MS) {
+      return this.jwksCache;
+    }
+    await this.refreshJwks();
+    if (!this.jwksCache) {
+      throw new IQAuthError("INTERNAL_ERROR", "JWKS cache unavailable after refresh");
     }
-    return this.jwksCache?.keys.get(kid) ?? null;
+    return this.jwksCache;
   }
   async refreshJwks() {
     if (this.inFlightRefresh) {
@@ -581,35 +613,24 @@ var TokensModule = class {
             "Malformed JWKS response: expected { keys: [...] }"
           );
         }
-        const keys = /* @__PURE__ */ new Map();
+        const byKid = /* @__PURE__ */ new Set();
         for (const key of jwks.keys) {
-          if (!key || typeof key.kid !== "string" || typeof key.n !== "string" || typeof key.e !== "string") {
+          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",
               "Malformed JWKS response: key missing required fields"
             );
           }
-          const pem = this.jwkToPem(key);
-          keys.set(key.kid, pem);
+          byKid.add(key.kid);
         }
-        this.jwksCache = { keys, fetchedAt: Date.now() };
+        const verifier = (0, import_jose.createLocalJWKSet)({ keys: jwks.keys });
+        this.jwksCache = { raw: jwks.keys, byKid, verifier, fetchedAt: Date.now() };
       } finally {
         this.inFlightRefresh = null;
       }
     })();
     return this.inFlightRefresh;
   }
-  jwkToPem(jwk) {
-    const keyObject = import_crypto.default.createPublicKey({
-      key: {
-        kty: jwk.kty,
-        n: jwk.n,
-        e: jwk.e
-      },
-      format: "jwk"
-    });
-    return keyObject.export({ type: "spki", format: "pem" });
-  }
   /** @internal Exposed for testing — clears JWKS cache */
   clearCache() {
     this.jwksCache = null;
@@ -817,7 +838,7 @@ var PermissionsModule = class {
 };
 
 // src/modules/oidc.ts
-var import_crypto2 = __toESM(require("crypto"));
+var import_crypto = __toESM(require("crypto"));
 var InMemoryOidcStateStore = class {
   constructor() {
     this.map = /* @__PURE__ */ new Map();
@@ -898,12 +919,12 @@ var OidcModule = class {
    * ready to redirect the user to.
    */
   async createAuthRequest(params) {
-    const codeVerifier = base64UrlEncode(import_crypto2.default.randomBytes(32));
+    const codeVerifier = base64UrlEncode(import_crypto.default.randomBytes(32));
     const codeChallenge = base64UrlEncode(
-      import_crypto2.default.createHash("sha256").update(codeVerifier).digest()
+      import_crypto.default.createHash("sha256").update(codeVerifier).digest()
     );
-    const state = base64UrlEncode(import_crypto2.default.randomBytes(16));
-    const nonce = base64UrlEncode(import_crypto2.default.randomBytes(16));
+    const state = base64UrlEncode(import_crypto.default.randomBytes(16));
+    const nonce = base64UrlEncode(import_crypto.default.randomBytes(16));
     await this.stateStore.set(state, {
       codeVerifier,
       state,

package/dist/browser-session.mjs

@@ -1,6 +1,7 @@
 import {
   IQAuthClient
-} from "./chunk-MDUHPQMM.mjs";
+} from "./chunk-W3F4JYGP.mjs";
+import "./chunk-UNYDG2L4.mjs";
 import {
   ErrorCodes,
   IQAuthError

package/dist/browser.d.mts

@@ -1,33 +1,8 @@
-export { C as CallbackResult, S as SessionManager, d as SessionManagerOptions, a as SessionSnapshot, e as SessionStatus, b as SignInOptions, c as SignOutOptions, f as buildSignInUrl, h as handleAuthCallback, r as redirectToSignIn, s as signIn, g as signOut } from './signIn-D_kP3v-c.mjs';
+import { S as SessionManager } from './signIn-CiIBTJIh.mjs';
+export { n as AccountRecord, A as AccountRegistry, C as CallbackResult, k as LinkProviderInput, L as LinkedIdentity, M as MagicLinkRequestInput, m as MultiAccountTokenStore, j as PasskeyAuthInput, P as PasswordlessOptions, z as REFRESH_COOKIE, R as RefreshTokenStore, a as SessionManagerOptions, b as SessionSnapshot, c as SessionStatus, x as SignInOptions, y as SignOutOptions, U as UnlinkProviderInput, d as beginPasskeyAuthentication, e as beginPasskeyRegistration, o as buildSignInUrl, B as clearCookie, h as enrollPasskey, f as finishPasskeyAuthentication, g as finishPasskeyRegistration, D as getCookie, p as handleAuthCallback, i as linkProvider, l as listLinkedIdentities, q as redirectToSignIn, r as requestMagicLink, E as setCookie, t as signIn, s as signInWithPasskey, w as signOut, u as unlinkProvider, v as verifyMagicLink } from './signIn-CiIBTJIh.mjs';
 export { K as KeyMode, c as ParsedPublishableKey, P as PublishableKeyPayload, e as encodePublishableKey, i as isPublishableKey, b as isSecretKey, p as parsePublishableKey } from './publishableKey-BaR0HoAH.mjs';
 export { a as ErrorCode, E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
-import './types-Cxl3bQHt.mjs';
-
-/**
- * Browser-only storage helpers used by the SessionManager.
- *
- * Storage strategy (Phase B):
- *   - Access token: in memory only (held by SessionManager).
- *   - Refresh token: first-party cookie on the app's own domain. The cookie
- *     is set by the SDK callback handler and cleared on signOut.
- *
- * NOTE: Cookies set from JS cannot be httpOnly. Phase D (cookie-aware
- * middleware) will move refresh-token cookie management into the app's
- * backend so it can be httpOnly. Until then, the SDK uses a `Secure`,
- * `SameSite=Lax` first-party cookie as a pragmatic stopgap. Nothing
- * privileged ever lives in localStorage.
- */
-declare const REFRESH_COOKIE = "iqauth_rt";
-interface CookieOptions {
-    maxAgeSeconds?: number;
-    path?: string;
-    domain?: string;
-    secure?: boolean;
-    sameSite?: "lax" | "strict" | "none";
-}
-declare function setCookie(name: string, value: string, opts?: CookieOptions): void;
-declare function getCookie(name: string): string | null;
-declare function clearCookie(name: string, opts?: CookieOptions): void;
+import './types-DZAflmmq.mjs';
 
 /**
  * Browser-safe PKCE + state/nonce generation using WebCrypto.
@@ -43,4 +18,64 @@ interface PkcePair {
 }
 declare function createPkcePair(): Promise<PkcePair>;
 
-export { REFRESH_COOKIE, clearCookie, createPkcePair, getCookie, randomUrlSafe, s256Challenge, setCookie };
+/**
+ * Step-up reverification helper — Task #90 (F27, SDK side).
+ *
+ * Calls `POST {issuer}/api/v1/auth/reverify` with the user's password or
+ * MFA code, and returns a short-lived single-use token the caller
+ * should attach to subsequent sensitive requests as
+ * `X-Reverification-Token`.
+ *
+ * Designed to pair with `auth.fetch()` — see README:
+ *
+ *   const { token } = await reverify(manager, { level: "password", password });
+ *   await manager.fetch("/api/billing/payouts", {
+ *     method: "POST",
+ *     headers: { "X-Reverification-Token": token },
+ *     body: JSON.stringify({...}),
+ *   });
+ */
+
+/**
+ * Sessionstorage key under which we stash the admin's pre-impersonation
+ * access token so `<ImpersonationBanner/>` can restore it on Exit.
+ * Tab-scoped (sessionStorage) by design — impersonation must not survive
+ * tab close, and we never want the admin's token to leak into other tabs.
+ */
+declare const PRIOR_SESSION_STORAGE_KEY = "iqauth_prior_admin_session";
+/**
+ * Stash the current admin session token, then swap to an impersonation
+ * access token minted by `POST /api/v1/admin/users/:id/actor-token`.
+ * The banner's "Exit" restores the prior session via `exitImpersonation`.
+ */
+declare function enterImpersonation(manager: SessionManager, actorAccessToken: string): void;
+/**
+ * Restore the admin's pre-impersonation access token (if any) and clear
+ * the stash. Returns `true` when a prior session was restored, `false`
+ * when none was found (caller should then `signOut` instead).
+ */
+declare function exitImpersonation(manager: SessionManager): boolean;
+type ReverificationLevel = "password" | "mfa";
+interface ReverifyInput {
+    level: ReverificationLevel;
+    password?: string;
+    totp?: string;
+    method?: "totp" | "sms" | "email";
+    ttlSeconds?: number;
+}
+interface ReverifyResult {
+    token: string;
+    level: ReverificationLevel;
+    expiresAt: Date;
+}
+declare function reverify(manager: SessionManager, input: ReverifyInput, options?: {
+    path?: string;
+}): Promise<ReverifyResult>;
+/**
+ * Convenience wrapper: returns a `fetch`-compatible function that
+ * automatically attaches `X-Reverification-Token` on the next call,
+ * then forgets it (single-use mirror of the server semantics).
+ */
+declare function withReverification(manager: SessionManager, token: string): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+export { PRIOR_SESSION_STORAGE_KEY, type ReverificationLevel, type ReverifyInput, type ReverifyResult, SessionManager, createPkcePair, enterImpersonation, exitImpersonation, randomUrlSafe, reverify, s256Challenge, withReverification };

package/dist/browser.d.ts

@@ -1,33 +1,8 @@
-export { C as CallbackResult, S as SessionManager, d as SessionManagerOptions, a as SessionSnapshot, e as SessionStatus, b as SignInOptions, c as SignOutOptions, f as buildSignInUrl, h as handleAuthCallback, r as redirectToSignIn, s as signIn, g as signOut } from './signIn-BVDTIA_t.js';
+import { S as SessionManager } from './signIn-OCr88Zf8.js';
+export { n as AccountRecord, A as AccountRegistry, C as CallbackResult, k as LinkProviderInput, L as LinkedIdentity, M as MagicLinkRequestInput, m as MultiAccountTokenStore, j as PasskeyAuthInput, P as PasswordlessOptions, z as REFRESH_COOKIE, R as RefreshTokenStore, a as SessionManagerOptions, b as SessionSnapshot, c as SessionStatus, x as SignInOptions, y as SignOutOptions, U as UnlinkProviderInput, d as beginPasskeyAuthentication, e as beginPasskeyRegistration, o as buildSignInUrl, B as clearCookie, h as enrollPasskey, f as finishPasskeyAuthentication, g as finishPasskeyRegistration, D as getCookie, p as handleAuthCallback, i as linkProvider, l as listLinkedIdentities, q as redirectToSignIn, r as requestMagicLink, E as setCookie, t as signIn, s as signInWithPasskey, w as signOut, u as unlinkProvider, v as verifyMagicLink } from './signIn-OCr88Zf8.js';
 export { K as KeyMode, c as ParsedPublishableKey, P as PublishableKeyPayload, e as encodePublishableKey, i as isPublishableKey, b as isSecretKey, p as parsePublishableKey } from './publishableKey-BaR0HoAH.js';
 export { a as ErrorCode, E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
-import './types-Cxl3bQHt.js';
-
-/**
- * Browser-only storage helpers used by the SessionManager.
- *
- * Storage strategy (Phase B):
- *   - Access token: in memory only (held by SessionManager).
- *   - Refresh token: first-party cookie on the app's own domain. The cookie
- *     is set by the SDK callback handler and cleared on signOut.
- *
- * NOTE: Cookies set from JS cannot be httpOnly. Phase D (cookie-aware
- * middleware) will move refresh-token cookie management into the app's
- * backend so it can be httpOnly. Until then, the SDK uses a `Secure`,
- * `SameSite=Lax` first-party cookie as a pragmatic stopgap. Nothing
- * privileged ever lives in localStorage.
- */
-declare const REFRESH_COOKIE = "iqauth_rt";
-interface CookieOptions {
-    maxAgeSeconds?: number;
-    path?: string;
-    domain?: string;
-    secure?: boolean;
-    sameSite?: "lax" | "strict" | "none";
-}
-declare function setCookie(name: string, value: string, opts?: CookieOptions): void;
-declare function getCookie(name: string): string | null;
-declare function clearCookie(name: string, opts?: CookieOptions): void;
+import './types-DZAflmmq.js';
 
 /**
  * Browser-safe PKCE + state/nonce generation using WebCrypto.
@@ -43,4 +18,64 @@ interface PkcePair {
 }
 declare function createPkcePair(): Promise<PkcePair>;
 
-export { REFRESH_COOKIE, clearCookie, createPkcePair, getCookie, randomUrlSafe, s256Challenge, setCookie };
+/**
+ * Step-up reverification helper — Task #90 (F27, SDK side).
+ *
+ * Calls `POST {issuer}/api/v1/auth/reverify` with the user's password or
+ * MFA code, and returns a short-lived single-use token the caller
+ * should attach to subsequent sensitive requests as
+ * `X-Reverification-Token`.
+ *
+ * Designed to pair with `auth.fetch()` — see README:
+ *
+ *   const { token } = await reverify(manager, { level: "password", password });
+ *   await manager.fetch("/api/billing/payouts", {
+ *     method: "POST",
+ *     headers: { "X-Reverification-Token": token },
+ *     body: JSON.stringify({...}),
+ *   });
+ */
+
+/**
+ * Sessionstorage key under which we stash the admin's pre-impersonation
+ * access token so `<ImpersonationBanner/>` can restore it on Exit.
+ * Tab-scoped (sessionStorage) by design — impersonation must not survive
+ * tab close, and we never want the admin's token to leak into other tabs.
+ */
+declare const PRIOR_SESSION_STORAGE_KEY = "iqauth_prior_admin_session";
+/**
+ * Stash the current admin session token, then swap to an impersonation
+ * access token minted by `POST /api/v1/admin/users/:id/actor-token`.
+ * The banner's "Exit" restores the prior session via `exitImpersonation`.
+ */
+declare function enterImpersonation(manager: SessionManager, actorAccessToken: string): void;
+/**
+ * Restore the admin's pre-impersonation access token (if any) and clear
+ * the stash. Returns `true` when a prior session was restored, `false`
+ * when none was found (caller should then `signOut` instead).
+ */
+declare function exitImpersonation(manager: SessionManager): boolean;
+type ReverificationLevel = "password" | "mfa";
+interface ReverifyInput {
+    level: ReverificationLevel;
+    password?: string;
+    totp?: string;
+    method?: "totp" | "sms" | "email";
+    ttlSeconds?: number;
+}
+interface ReverifyResult {
+    token: string;
+    level: ReverificationLevel;
+    expiresAt: Date;
+}
+declare function reverify(manager: SessionManager, input: ReverifyInput, options?: {
+    path?: string;
+}): Promise<ReverifyResult>;
+/**
+ * Convenience wrapper: returns a `fetch`-compatible function that
+ * automatically attaches `X-Reverification-Token` on the next call,
+ * then forgets it (single-use mirror of the server semantics).
+ */
+declare function withReverification(manager: SessionManager, token: string): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+export { PRIOR_SESSION_STORAGE_KEY, type ReverificationLevel, type ReverifyInput, type ReverifyResult, SessionManager, createPkcePair, enterImpersonation, exitImpersonation, randomUrlSafe, reverify, s256Challenge, withReverification };