@iqauth/sdk 2.3.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:
@@ -501,6 +574,24 @@ This is the single most common bug we see when teams add IQAuth to an app that a
 
 ---
 
+## 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:
@@ -528,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,6 +1,7 @@
-import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-Cxl3bQHt.mjs';
-import { I as IQAuthClient } from './client-vdh2a9fJ.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 './tokens-DCyzzn8L.mjs';
 
 declare class BrowserSessionIQAuthClient extends IQAuthClient {
     constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);

package/dist/browser-session.d.ts

@@ -1,6 +1,7 @@
-import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-Cxl3bQHt.js';
-import { I as IQAuthClient } from './client-DTX4hNdS.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 './tokens-aHiGFr_E.js';
 
 declare class BrowserSessionIQAuthClient extends IQAuthClient {
     constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);

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-Cd0P4y9d.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-DKakyzeu.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 };