@iqauth/sdk 2.0.3 → 2.0.5

package/README.md

@@ -1,287 +1,490 @@
 # @iqauth/sdk
 
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
-[![License](https://img.shields.io/badge/license-proprietary-lightgrey.svg)]()
-[![Module Format](https://img.shields.io/badge/format-CJS%20%2B%20ESM-blue.svg)]()
-[![Docs](https://img.shields.io/badge/docs-environment--specific-blue.svg)](./docs/)
+[![npm](https://img.shields.io/npm/v/@iqauth/sdk.svg)](https://www.npmjs.com/package/@iqauth/sdk)
+[![Node](https://img.shields.io/node/v/@iqauth/sdk.svg)](https://nodejs.org)
+[![Types](https://img.shields.io/npm/types/@iqauth/sdk.svg)](https://www.typescriptlang.org/)
+[![Module Format](https://img.shields.io/badge/format-CJS%20%2B%20ESM-blue.svg)](https://www.npmjs.com/package/@iqauth/sdk)
+[![License](https://img.shields.io/badge/license-proprietary-lightgrey.svg)](#license)
 
-Type-safe TypeScript SDK for IQAuthService.
+The canonical TypeScript SDK for **IQAuthService** — DispositionIQ's multi-tenant identity and authorization platform. One package covers the React client, the four major Node frameworks (Express, Fastify, Hono, Next.js), native mobile, and headless service automation.
+
+> **New in 2.0.3** — `SessionManager` gains `serverManagedSession: true` for confidential-client apps, and the cookie-managed `/refresh` helper no longer wipes cookies on transient failures. See [What's new in 2.0.3](#whats-new-in-203).
+
+---
+
+## Table of contents
+
+- [Install](#install)
+- [Five-line integration](#five-line-integration)
+- [Pick your environment](#pick-your-environment)
+- [What's new in 2.0.3](#whats-new-in-203)
+- [Browser apps with a backend (recommended)](#browser-apps-with-a-backend-recommended)
+- [Server reference (Express, Fastify, Hono, Next.js)](#server-reference)
+- [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)
+- [Hosted auth pages and branding](#hosted-auth-pages-and-branding)
+- [CLI](#cli)
+- [Error handling](#error-handling)
+- [Troubleshooting](#troubleshooting)
+- [Bundled docs](#bundled-docs)
+- [License](#license)
+
+---
+
+## Install
+
+```bash
+npm install @iqauth/sdk
+```
+
+- Node **>= 18** (the SDK uses native `fetch` and Web Crypto).
+- Ships **CJS + ESM + .d.ts** for every entry point.
+- React is an **optional** peer (`>=18`). You only need it if you import from `@iqauth/sdk/react`.
+
+You'll need two values from the IQAuth admin dashboard for any app you integrate:
+
+- **Publishable key** (`pk_live_…` / `pk_test_…`) — safe to ship to the browser. Self-describes `{iss, appId, tenantId, kid}`, so the SDK auto-discovers your issuer; you almost never need to set it manually.
+- **Secret key** (`sk_live_…` / `sk_test_…`) — server-only. Keep it in env vars, never in client code.
+
+Create both in one call from the admin Quickstart wizard, or run `npx iqauth init` (see [CLI](#cli)).
+
+---
 
 ## Five-line integration
 
-**React (client):**
+### React (browser)
+
 ```tsx
 import { IQAuthProvider, SignedIn, SignedOut, RedirectToSignIn } from "@iqauth/sdk/react";
 
-<IQAuthProvider publishableKey={import.meta.env.VITE_IQAUTH_PUBLISHABLE_KEY}>
-  <SignedIn><App /></SignedIn>
-  <SignedOut><RedirectToSignIn /></SignedOut>
-</IQAuthProvider>
+export default function App() {
+  return (
+    <IQAuthProvider publishableKey={import.meta.env.VITE_IQAUTH_PUBLISHABLE_KEY}>
+      <SignedIn><Dashboard /></SignedIn>
+      <SignedOut><RedirectToSignIn /></SignedOut>
+    </IQAuthProvider>
+  );
+}
 ```
 
-**Express / Fastify / Hono / Next.js (server):**
-```js
+Available hooks: `useUser()`, `useSession()`, `useAuth()`, `useOrganization()`. Each returns `{ data, isLoading, error }`.
+Drop-in components: `<SignIn/>`, `<SignUp/>`, `<UserButton/>`, `<UserProfile/>`, `<OrganizationSwitcher/>`, `<AuthCallback/>`.
+
+### Express
+
+```ts
 import express from "express";
-import { iqAuth } from "@iqauth/sdk/express"; // or /fastify, /hono, /next
+import { iqAuth } from "@iqauth/sdk/express";
 
 const app = express();
 app.use(express.json());
-const auth = iqAuth({ publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY, secretKey: process.env.IQAUTH_SECRET_KEY });
-auth.attachHelpers(app);  // mounts /api/iqauth/{callback,refresh,signout} (httpOnly cookies)
-app.use(auth);            // verifies Bearer or iqauth_at cookie; populates req.auth
-```
 
-The middleware is **cookie-aware** (Bearer header OR `iqauth_at` cookie) and the issuer is **auto-discovered from your publishable key** — no extra config.
+const auth = iqAuth({
+  publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!,
+  secretKey: process.env.IQAUTH_SECRET_KEY!,
+});
 
-Working examples live in `examples/{react-vite,express,fastify,hono,next}/`.
+auth.attachHelpers(app);  // mounts /api/iqauth/{callback,refresh,signout} (HttpOnly cookies)
+app.use(auth);            // verifies Bearer header OR iqauth_at cookie; populates req.auth
+```
 
-## CLI
+### Fastify
 
-```sh
-npx iqauth init      # bootstrap a new app + write IQAUTH_* keys to .env
-npx iqauth doctor    # check .env, issuer reachability, JWKS, redirect URI
-npx iqauth keys list --app <id>
-npx iqauth keys rotate --app <id> --key-id <id> --yes
-npx iqauth dev       # run the bundled React example with your key
+```ts
+import Fastify from "fastify";
+import { iqAuth } from "@iqauth/sdk/fastify";
+
+const app = Fastify();
+const auth = iqAuth({ publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!, secretKey: process.env.IQAUTH_SECRET_KEY! });
+await app.register(auth.plugin);   // mounts helpers + decorates request.auth
 ```
 
----
+### Hono
 
-## Environment Matrix
+```ts
+import { Hono } from "hono";
+import { iqAuth } from "@iqauth/sdk/hono";
 
-This package is not one auth model for every environment. The safe integration pattern depends on where credentials live.
+const app = new Hono();
+const auth = iqAuth({ publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!, secretKey: process.env.IQAUTH_SECRET_KEY! });
+app.route("/api/iqauth", auth.helpers);
+app.use("*", auth.middleware);
+```
 
-| Environment | Recommended pattern | Refresh token owner | Primary SDK fit |
-|--------|--------|--------|--------|
-| First-party browser app | Backend proxy + `httpOnly` cookies | Backend only | Resource calls, server verification, shared API modules |
-| Native mobile app | Authorization code + PKCE + secure OS storage | Mobile app secure storage | Token-owning client patterns |
-| Server-side app | Direct token handling or request-scoped bearer verification | Server | Strong fit |
-| Service / automation | API key or dedicated service credentials | Service | Strong fit |
+### Next.js (App Router)
 
-## Start Here
+```ts
+// app/api/iqauth/[...iqauth]/route.ts
+import { iqAuth } from "@iqauth/sdk/next";
+const auth = iqAuth({ publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!, secretKey: process.env.IQAUTH_SECRET_KEY! });
+export const { GET, POST } = auth.handlers;
+```
 
-### First-party browser apps
+```ts
+// In any Server Component / Route Handler / Server Action
+import { getAuth } from "@iqauth/sdk/next";
+const session = await getAuth();   // null when signed-out
+```
 
-Do not treat this SDK's token-owning client as the default browser integration path.
+The middleware is **cookie-aware** (Bearer header OR `iqauth_at` cookie) and the issuer is **auto-discovered from your publishable key** — no extra config.
 
-For first-party web applications:
+---
 
-- proxy login, MFA, tenant selection, refresh, and logout through your backend
-- store access and refresh tokens in `httpOnly` cookies
-- restore session with a backend endpoint such as `/auth/me`
-- do not store refresh tokens in `localStorage`, `sessionStorage`, or browser-readable memory as your durable session model
+## Pick your environment
 
-The browser should call your backend. Your backend should call IQAuth.
+The SDK is not "one auth model for every environment". The safe pattern depends on where credentials live.
 
-### Native mobile apps
+| Environment | Recommended pattern | Refresh-token owner | Entry point |
+|---|---|---|---|
+| First-party browser app **with a backend** | Backend proxy + HttpOnly cookies | Backend only | `@iqauth/sdk/{express,fastify,hono,next}` + `@iqauth/sdk/react` (with `serverManagedSession`) |
+| First-party browser app **without a backend** (SPA only) | Authorization-code + PKCE in-browser, refresh in JS-readable cookie | Browser (in cookie) | `@iqauth/sdk/browser` + `@iqauth/sdk/react` |
+| Native mobile | Authorization-code + PKCE, secure OS storage | Mobile app secure storage | `@iqauth/sdk/mobile` |
+| Server-side / API resource server | Bearer verification via JWKS | Server (per request) | `@iqauth/sdk/server` |
+| Service / automation / cron | API key | Service | `@iqauth/sdk/service` |
 
-Use authorization code flow with PKCE:
+> **Rule of thumb:** if your app has its own backend, use a framework adapter and turn on `serverManagedSession: true` in the React provider. Don't store refresh tokens in `localStorage`/`sessionStorage` as your durable session model.
 
-- generate `state`, `nonce`, and PKCE verifier/challenge on device
-- complete auth in the system browser
-- exchange the authorization code
-- store tokens only in Keychain / Keystore / secure OS-backed storage
+---
 
-### Server-side apps
+## What's new in 2.0.3
 
-This SDK is a good fit for:
+### 1. `serverManagedSession: true` for `SessionManager` / `IQAuthProvider`
 
-- trusted backend services
-- Express resource servers
-- admin tooling
-- request-scoped token handling
-- bearer-token verification through JWKS
+For any app whose backend uses one of the framework adapters (`@iqauth/sdk/{express,fastify,hono,next}`), the backend owns the HttpOnly `iqauth_at` + `iqauth_rt` cookies and should be the **sole** authority on token rotation. Opt into that explicitly:
 
-### Service clients
+```tsx
+<IQAuthProvider
+  publishableKey={import.meta.env.VITE_IQAUTH_PUBLISHABLE_KEY}
+  serverManagedSession
+>
+  …
+</IQAuthProvider>
+```
 
-Prefer API keys or dedicated service credentials over interactive user session flows.
+What changes when this is on:
 
-## Current SDK Shape
+- `bootstrap()` learns session state with a single read-only `GET /api/v1/auth/me` (override with `userinfoPath`) instead of POSTing to `/refresh`. **No rotation, no race surface.**
+- The proactive-refresh timer is suppressed — the server middleware refreshes on real navigation, single-flight per request.
+- The browser `tokenStore` defaults to a no-op store, so JS never tries to read the (HttpOnly, invisible) refresh cookie.
 
-The current package surface is still token-oriented. That is acceptable for server, mobile, and service contexts, but it should not be read as a recommendation to store refresh tokens directly in first-party browser JavaScript.
+This eliminates the multi-tab + React StrictMode + proactive-timer race that previously produced silent forced sign-outs.
 
-Use the package today with that distinction in mind:
+### 2. `clearCookiesOnRefreshFailure: "terminal-only" | "always" | "never"`
 
-- server: recommended
-- mobile: acceptable with PKCE + secure storage discipline
-- browser first-party: use only behind a backend session boundary
-- service: recommended with API keys
+The cookie helper `handleRefresh` (used by every framework adapter) now defaults to `"terminal-only"`. Cookies are only cleared when the issuer signals the session is unrecoverable:
 
-## Install
+- `TOKEN_REVOKED`, `SESSION_REVOKED`, `INVALID_GRANT`
+- `USER_DEACTIVATED`, `USER_DISABLED`, `TENANT_SUSPENDED`
+- HTTP `410 Gone`
 
-```bash
-npm install @iqauth/sdk
+Transient failures — `TOKEN_INVALID` from a rotated-out token, `TOKEN_EXPIRED`, network blips, 5xx — return 401 with cookies intact, so the next legitimate request can either succeed against a still-valid access cookie or be redirected to sign-in cleanly by the middleware.
+
+```ts
+iqAuth({
+  publishableKey, secretKey,
+  clearCookiesOnRefreshFailure: "terminal-only", // default; "always" restores pre-2.0.3 behavior
+});
 ```
 
-Supports both CommonJS and ES Modules. Ships with TypeScript declarations.
+### 3. Next.js 15+ async cookies
 
-## Entry Points
+`getAuth()` in `@iqauth/sdk/next` now `await`s `next/headers#cookies()` — fixes the runtime warning and the occasional null-session on the first request after build on Next 15 / 16.
 
-Use the entry point that matches your environment:
+---
 
-```typescript
-import { createBrowserSessionClient } from "@iqauth/sdk/browser-session";
-import { createServerClient, ServerIQAuthClient } from "@iqauth/sdk/server";
-import { createMobileClient } from "@iqauth/sdk/mobile";
-import { createServiceClient } from "@iqauth/sdk/service";
-```
+## Browser apps with a backend (recommended)
 
-## Server Quick Start
+This is the integration path you want for any product with its own server. The browser never sees a refresh token; the backend owns rotation; cookies are HttpOnly.
+
+```tsx
+// client/src/main.tsx
+import { IQAuthProvider, SignedIn, SignedOut, RedirectToSignIn } from "@iqauth/sdk/react";
 
-Use the provided middleware by default for Express resource servers.
+createRoot(document.getElementById("root")!).render(
+  <IQAuthProvider
+    publishableKey={import.meta.env.VITE_IQAUTH_PUBLISHABLE_KEY}
+    serverManagedSession
+  >
+    <SignedIn><App /></SignedIn>
+    <SignedOut><RedirectToSignIn /></SignedOut>
+  </IQAuthProvider>
+);
+```
 
-```typescript
+```ts
+// server/index.ts
 import express from "express";
-import { createServerClient } from "@iqauth/sdk/server";
+import { iqAuth } from "@iqauth/sdk/express";
 
-const client = createServerClient({
-  baseUrl: "https://auth.dispositioniq.com",
+const app = express();
+app.use(express.json());
+
+const auth = iqAuth({
+  publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!,
+  secretKey: process.env.IQAUTH_SECRET_KEY!,
 });
+auth.attachHelpers(app); // mounts /api/iqauth/{callback,refresh,signout}
+app.use(auth);           // populates req.auth on every request
 
-const app = express();
+app.get("/api/me", (req, res) => res.json(req.auth));
+```
+
+That's the whole integration. The hosted sign-in page on `auth.dispositioniq.com` redirects back to `/api/iqauth/callback`, which sets HttpOnly cookies and bounces the user to your `return_to`. Subsequent API calls succeed against the access cookie; on the rare expiry the same cookie endpoint refreshes silently.
+
+### Calling your own API from the browser
+
+Use `auth.fetch()` from the React provider — it adds credentials and retries once on 401:
 
-app.use("/api", client.middleware());
+```tsx
+import { useAuth } from "@iqauth/sdk/react";
 
-app.get("/api/me", (req, res) => {
-  res.json({
-    sub: req.auth!.sub,
-    email: req.auth!.email,
-    tenantId: req.auth!.tenantId,
-    roles: req.auth!.roles,
+function ProductList() {
+  const { fetch } = useAuth();
+  const { data } = useQuery({
+    queryKey: ["products"],
+    queryFn: () => fetch("/api/products").then(r => r.json()),
   });
-});
+  // …
+}
+```
+
+### Calling **another** IQAuth-protected API (cross-origin)
+
+Add the calling app's origin to the target app's `app_allowed_origins` in the admin dashboard. The unified CORS allow-list (per-app origins ∪ global `cors_origins` ∪ `CORS_ORIGINS` env) refreshes within 60 seconds.
+
+---
+
+## Server reference
+
+### Middleware behavior
+
+- Accepts `Authorization: Bearer <jwt>` **or** the `iqauth_at` HttpOnly cookie.
+- Verifies RS256 against the issuer's JWKS (cached with stale-while-revalidate).
+- Populates `req.auth` (Express/Fastify), `c.get("auth")` (Hono), or `getAuth()` return value (Next).
+- The shape of `req.auth` is the verified JWT claims plus normalized `{ sub, email, tenantId, roles, permissions, scopes }`.
+
+> The SDK uses `req.auth` (not `req.user`) so it never collides with Passport.
+
+### Requiring roles or entitlements
+
+```ts
+app.use("/admin",
+  auth.require({
+    roles: ["tenant_admin", "platform_admin"],
+    entitlements: ["iqcapture"],
+  }),
+);
 ```
 
-If you are building an Express API that accepts bearer tokens, the platform should use the SDK middleware rather than re-implementing token verification manually unless there is a concrete framework constraint.
+`auth.require()` is composable — chain it on individual routes, route groups, or globally. Failures throw `IQAuthError` with `code: "INSUFFICIENT_PERMISSIONS"` and the middleware returns 403.
 
-## Browser Quick Start
+### Helper routes mounted by `attachHelpers` / `register` / `auth.handlers`
 
-Use a backend proxy. Example shape:
+| Method | Path | Purpose |
+|---|---|---|
+| `GET`  | `/api/iqauth/callback` | Receives the OIDC redirect, exchanges the code, sets `iqauth_at` + `iqauth_rt`, redirects to `return_to` |
+| `POST` | `/api/iqauth/refresh`  | Reads `iqauth_rt`, rotates, sets new cookies. Honors `clearCookiesOnRefreshFailure` |
+| `POST` | `/api/iqauth/signout`  | Revokes the refresh token upstream and clears both cookies |
 
-```typescript
-// frontend
-await fetch("/auth/login", {
-  method: "POST",
-  credentials: "include",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ email, password }),
-});
+All three set cookies with `HttpOnly; Secure; SameSite=lax; Path=/` by default. Override per-app:
 
-const me = await fetch("/auth/me", {
-  credentials: "include",
-}).then((res) => res.json());
+```ts
+iqAuth({
+  publishableKey, secretKey,
+  cookieDomain: ".example.com",  // for cross-subdomain SSO
+  sameSite: "none",              // pair with secure: true
+  secure: true,
+  cookiePath: "/",
+  accessCookieName: "iqauth_at",
+  refreshCookieName: "iqauth_rt",
+});
 ```
 
-```typescript
-// backend
-app.post("/auth/login", async (req, res) => {
-  const result = await iqauth.auth.login(req.body.email, req.body.password);
-  // set httpOnly cookies here, not localStorage in the browser
+---
+
+## Token verification without a framework adapter
+
+If you're not using Express/Fastify/Hono/Next (custom Node server, AWS Lambda, Cloudflare Worker, etc.):
+
+```ts
+import { createServerClient } from "@iqauth/sdk/server";
+
+const client = createServerClient({
+  publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!, // issuer auto-discovered
 });
+
+const claims = await client.tokens.verify(bearerToken);
+// → { sub, email, tenantId, roles, permissions, scopes, iss, aud, exp, … }
 ```
 
-For the full backend-proxy pattern, see the Fresh Implementation Guide.
+`tokens.verify()` enforces RS256, checks `exp` / `nbf` / `iss` / `aud`, and uses the cached JWKS. Throws `IQAuthError` with codes like `TOKEN_EXPIRED`, `TOKEN_INVALID`, `TOKEN_REVOKED`.
 
-## Mobile Quick Start
+---
 
-```typescript
-import { IQAuthClient } from "@iqauth/sdk";
+## Native mobile (PKCE)
 
-const client = new IQAuthClient({
-  baseUrl: "https://auth.dispositioniq.com",
-  accessToken: await secureStore.get("accessToken"),
-  refreshToken: await secureStore.get("refreshToken"),
-  onTokenRefresh: async (tokens) => {
-    await secureStore.set("accessToken", tokens.accessToken);
-    await secureStore.set("refreshToken", tokens.refreshToken);
+```ts
+import { createMobileClient } from "@iqauth/sdk/mobile";
+
+const client = createMobileClient({
+  publishableKey: PUBLISHABLE_KEY,
+  redirectUri: "myapp://auth/callback",
+  storage: {
+    get: (k) => SecureStore.getItemAsync(k),
+    set: (k, v) => SecureStore.setItemAsync(k, v),
+    delete: (k) => SecureStore.deleteItemAsync(k),
   },
 });
+
+// 1. begin
+const { url } = await client.signIn.start();
+await WebBrowser.openAuthSessionAsync(url, "myapp://auth/callback");
+
+// 2. handle redirect
+await client.signIn.complete(redirectUrl);
+
+// 3. use the session
+const me = await client.users.me();
 ```
 
-This is only appropriate when the tokens are stored in secure OS-backed storage and the login flow uses PKCE.
+Tokens are written to whichever `storage` adapter you provide — use Keychain on iOS, Keystore / EncryptedSharedPreferences on Android. Never persist them to AsyncStorage / `localStorage`.
+
+---
+
+## Service automation / API keys
 
-## API Key Quick Start
+For cron jobs, batch scripts, server-to-server calls — anything that isn't acting on behalf of an interactive user:
 
-```typescript
-import { IQAuthClient } from "@iqauth/sdk";
+```ts
+import { createServiceClient } from "@iqauth/sdk/service";
 
-const client = new IQAuthClient({
-  baseUrl: "https://auth.dispositioniq.com",
-  apiKey: process.env.IQAUTH_API_KEY,
+const client = createServiceClient({
+  publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!,
+  apiKey: process.env.IQAUTH_API_KEY!,
 });
 
-const keys = await client.apiKeys.list();
+const users = await client.users.list({ tenantId: "…" });
+const key = await client.apiKeys.create({ name: "nightly-sync", scopes: ["users:read"] });
 ```
 
-## Main Modules
+API-key calls are scoped to the permissions granted at creation time and are subject to per-key rate limits. Rotate with `client.apiKeys.rotate({ id })`; revoke with `client.apiKeys.revoke({ id })`.
 
-| Module | Access | Purpose |
-|--------|--------|---------|
-| `auth` | `client.auth` | Login, MFA, tenant selection, logout, password reset, OAuth |
-| `tokens` | `client.tokens` | JWT verification (RS256/JWKS), decode, expiry checks |
-| `sessions` | `client.sessions` | List and revoke sessions |
-| `users` | `client.users` | Profile and user management |
-| `permissions` | `client.permissions` | Role and entitlement helpers |
-| `oidc` | `client.oidc` | Discovery, JWKS, authorization helpers, code exchange |
-| `apiKeys` | `client.apiKeys` | API key create/list/revoke/introspect |
-| `webhooks` | `client.webhooks` | Endpoint CRUD, deliveries, test, secret rotation |
-| `mfa` | `client.mfa` | MFA enrollment, backup codes |
-| `branding` | `client.branding` | Branding config CRUD |
+---
 
-## Express Middleware
+## Hosted auth pages and branding
 
-```typescript
-import { createServerClient } from "@iqauth/sdk/server";
+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:
 
-const client = createServerClient({
-  baseUrl: "https://auth.dispositioniq.com",
-});
+- `--brand-primary`
+- `--brand-accent`
+- `--brand-bg`
+- `--brand-surface`
+- `--brand-text`
 
-app.use(
-  "/admin",
-  client.middleware({
-    requiredRoles: ["tenant_admin", "platform_admin"],
-    requiredEntitlements: ["iqcapture"],
-  }),
-);
+Validate the redirect contract from your own page with `GET /api/public/apps/:appKey/sign-in-context` — only `return_to` origins listed in your app's allowlist will be accepted.
+
+If you'd rather embed the same components in your own app shell, the React entry point publishes them directly:
+
+```tsx
+import { SignIn, SignUp, UserButton, UserProfile, OrganizationSwitcher } from "@iqauth/sdk/react";
 ```
 
-The middleware attaches verified claims to `req.auth` and is the recommended integration path for platforms consuming bearer tokens.
+---
 
-## Error Handling
+## CLI
 
-All API errors throw `IQAuthError`.
+```sh
+npx iqauth init                              # bootstrap a new app + write IQAUTH_* keys to .env
+npx iqauth doctor                            # check .env, issuer reachability, JWKS, redirect URI
+npx iqauth keys list   --app <id>
+npx iqauth keys rotate --app <id> --key-id <id> --yes
+npx iqauth keys revoke --app <id> --key-id <id> --yes
+npx iqauth dev                               # run the bundled React example with your key
+```
+
+`init` is the fastest way to provision a new app end-to-end: it creates the OIDC client, manifest, per-app origin allowlist, and a `pk_/sk_` keypair, then writes them to `.env`. Key rotation has a 24-hour grace window — old and new keys both validate during that window.
+
+---
+
+## Error handling
 
-```typescript
+Every API failure throws `IQAuthError` with a stable `code`.
+
+```ts
 import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
 
 try {
   await client.auth.login(email, password);
 } catch (err) {
-  if (err instanceof IQAuthError && err.code === ErrorCodes.ACCOUNT_LOCKED) {
-    // handle lockout
+  if (err instanceof IQAuthError) {
+    switch (err.code) {
+      case ErrorCodes.ACCOUNT_LOCKED:        return showLockoutBanner();
+      case ErrorCodes.MFA_REQUIRED:          return promptMfa(err.details);
+      case ErrorCodes.TENANT_SELECTION_REQUIRED: return promptTenant(err.details.tenants);
+      case ErrorCodes.INVALID_CREDENTIALS:   return showWrongPassword();
+      default:                               return showGenericError(err.message);
+    }
   }
+  throw err;
 }
 ```
 
-## Documentation
-
-- [App Integration Matrix](./docs/APP_INTEGRATION_MATRIX.md)
-- [Fresh Implementation Guide](./docs/FRESH_IMPLEMENTATION_GUIDE.md)
-- [Browser Session Migration Guide](./docs/BROWSER_SESSION_MIGRATION.md)
-- [Tarball Release Workflow](./docs/TARBALL_RELEASE_WORKFLOW.md)
-- [Auth Flows](./docs/guides/auth-flows.md)
-- [Session Management](./docs/guides/session-management.md)
-- [Mobile / Native Guide](./docs/guides/mobile-native.md)
-- [Server Platform Integration](./docs/guides/server-platform-integration.md)
-- [Service Automation Integration](./docs/guides/service-automation-integration.md)
-- [Token Verification](./docs/guides/token-verification.md)
-- [API Keys](./docs/guides/api-keys.md)
-- [Middleware Reference](./docs/guides/middleware-reference.md)
-- [Error Handling](./docs/guides/error-handling.md)
-- [V1 to V2 Upgrade Guide](./docs/V1_TO_V2_UPGRADE_GUIDE.md)
-- [Integration Prompts](./docs/integration-prompts/)
+Common codes you'll handle:
+
+| Code | When |
+|---|---|
+| `INVALID_CREDENTIALS` | Wrong email/password |
+| `ACCOUNT_LOCKED` | Too many failures; show cool-off |
+| `MFA_REQUIRED` | Continue to MFA step with `details.mfaToken` |
+| `TENANT_SELECTION_REQUIRED` | User belongs to >1 tenant; pick one |
+| `TOKEN_EXPIRED` | Access token aged out; refresh handled by SDK helpers |
+| `TOKEN_INVALID` | Token malformed or rotated out (transient under multi-tab) |
+| `TOKEN_REVOKED` / `SESSION_REVOKED` | Terminal — sign the user out |
+| `USER_DEACTIVATED` / `USER_DISABLED` / `TENANT_SUSPENDED` | Terminal — sign out |
+| `INSUFFICIENT_PERMISSIONS` | 403 — caller lacks required role/entitlement |
+
+---
+
+## Troubleshooting
+
+**`npx iqauth doctor` is the first stop.** It validates that the `IQAUTH_*` env vars are present and well-formed, the issuer responds, the JWKS endpoint serves keys, and your registered redirect URI matches what the SDK will send.
+
+| Symptom | Likely cause |
+|---|---|
+| Silent sign-out within ~60s of login | Pre-2.0.3 cookie-clearing on transient `TOKEN_INVALID`. Upgrade to ≥ 2.0.3, set `serverManagedSession: true` on the React side. |
+| `getAuth()` returns null after first navigation in Next 15+ | Pre-2.0.2 sync-cookies bug. Upgrade to ≥ 2.0.2. |
+| `/api/iqauth/callback` returns 400 "redirect_uri mismatch" | Your registered redirect URI doesn't match the host the browser is on. Add it in the admin app config. |
+| Cross-origin call to a sister IQAuth-protected app gets CORS-blocked | Add the caller's origin to the target app's `app_allowed_origins`. Allow up to 60s for the cache to refresh. |
+| `req.auth` is undefined under Passport | Verify you're reading `req.auth`, not `req.user`. The SDK deliberately uses `req.auth` to avoid Passport collision. |
+| Hosted sign-in page won't accept your `return_to` | The origin isn't in this app's allowlist. Add it in the admin dashboard. |
+
+---
+
+## Bundled docs
+
+Long-form integration guides ship **inside the npm tarball** at `node_modules/@iqauth/sdk/docs/`. List them with:
+
+```sh
+ls node_modules/@iqauth/sdk/docs
+ls node_modules/@iqauth/sdk/docs/guides
+ls node_modules/@iqauth/sdk/docs/integration-prompts
+```
+
+Highlights:
+
+- `docs/APP_INTEGRATION_MATRIX.md` — which entry point + pattern for which app archetype
+- `docs/FRESH_IMPLEMENTATION_GUIDE.md` — green-field walkthrough for a new app
+- `docs/BROWSER_SESSION_MIGRATION.md` — moving a browser-token-owning app to cookie-managed sessions (now includes the 2.0.3 `serverManagedSession` recipe)
+- `docs/V1_TO_V2_UPGRADE_GUIDE.md` — upgrading from `1.x`
+- `docs/TARBALL_RELEASE_WORKFLOW.md` — internal: shipping prebuilt tarballs to consumer apps
+- `docs/guides/auth-flows.md`, `session-management.md`, `mfa-enrollment.md`, `roles-and-permissions.md`, `scoped-authorization.md`, `entity-hierarchy.md`, `tenant-management.md`, `user-management.md`, `invitations.md`, `branding.md`, `webhooks.md`, `entitlements.md`, `api-keys.md`, `mobile-native.md`, `server-platform-integration.md`, `service-automation-integration.md`, `token-verification.md`, `middleware-reference.md`, `error-handling.md`, `gdpr-compliance.md`, `app-registration.md`
+- `docs/integration-prompts/{first-party-browser-app,native-mobile-app,server-platform-app,service-automation-app,install-from-tarball,migrate-from-local-packages-source}.md` — drop-in prompts for AI-assisted integration
+
+These are also kept on the IQAuth admin dashboard's documentation tab.
+
+---
 
 ## License
 
-Private — DispositionIQ internal use.
+Proprietary — DispositionIQ internal use. See the LICENSE/usage terms in the bundled docs.