@iqauth/sdk 2.0.0

package/docs/APP_INTEGRATION_MATRIX.md

@@ -0,0 +1,59 @@
+# App Integration Matrix
+
+Canonical integration matrix for applications adopting `@iqauth/sdk`.
+
+Use this document before implementing or upgrading any app.
+
+## Environment Matrix
+
+| App type | Runtime trust level | Auth model | SDK entry point | Credential owner | Required platform pattern |
+| --- | --- | --- | --- | --- | --- |
+| First-party browser admin or product app | Untrusted browser | Backend-managed cookie session | `@iqauth/sdk/browser-session` behind backend proxy | Backend only | `/auth/login`, `/auth/select-tenant`, `/auth/mfa/verify`, `/auth/refresh`, `/auth/logout`, `/auth/me` |
+| Native mobile app | Secure mobile runtime | Authorization code + PKCE | `@iqauth/sdk/mobile` | Secure OS storage | PKCE, system browser, deep/universal links, Keychain/Keystore |
+| Server platform app / resource server | Trusted backend | Bearer token verification and request-scoped auth | `@iqauth/sdk/server` | Server | Use `client.middleware()` by default |
+| Service / automation worker | Trusted backend | API key or service credential | `@iqauth/sdk/service` | Service | Prefer API keys, not interactive user sessions |
+
+## Non-Negotiable Rules
+
+### First-party browser apps
+
+- Do not store refresh tokens in `localStorage`, `sessionStorage`, or durable browser-readable state.
+- Do not treat browser JavaScript as the system of record for session state.
+- Restore auth through `/auth/me`.
+- Let the backend own refresh, logout, and invalidation.
+
+### Mobile apps
+
+- Use PKCE.
+- Use secure OS-backed token storage only.
+- Do not copy browser session patterns into mobile.
+
+### Server apps
+
+- Use the provided middleware when accepting bearer tokens.
+- Do not re-implement token verification unless the framework forces it.
+- Keep token state request-scoped or service-scoped, not shared across unrelated users.
+
+### Service apps
+
+- Prefer API keys.
+- Avoid interactive login flows unless a product requirement explicitly demands it.
+
+## Required Deliverables Per App
+
+Before an app is considered aligned, it should have:
+
+- the correct SDK entry point for its environment
+- the correct auth ownership model
+- a documented session/refresh/logout strategy
+- environment-specific tests or verification notes
+- a migration note if it previously used browser-owned tokens
+
+## Recommended Companion Docs
+
+- [Fresh Implementation Guide](./FRESH_IMPLEMENTATION_GUIDE.md)
+- [Browser Session Migration Guide](./BROWSER_SESSION_MIGRATION.md)
+- [Auth Flows](./guides/auth-flows.md)
+- [Mobile / Native Guide](./guides/mobile-native.md)
+- [Server Platform Integration](./guides/server-platform-integration.md)
+- [Service Automation Integration](./guides/service-automation-integration.md)

package/docs/BROWSER_SESSION_MIGRATION.md

@@ -0,0 +1,69 @@
+# Browser Session Migration Guide
+
+Use this guide when a first-party web app currently owns IQAuth tokens in browser code and needs to move to the supported session model.
+
+## Target Model
+
+- browser talks to app backend
+- app backend talks to IQAuth
+- backend stores access and refresh tokens in `httpOnly` cookies
+- browser restores session from `/auth/me`
+
+## Migration Checklist
+
+### 1. Stop durable browser token ownership
+
+Remove any pattern that:
+
+- stores refresh tokens in `localStorage`
+- restores auth by reading JWTs from browser storage on page load
+- refreshes directly from browser-owned refresh tokens as the default session model
+
+### 2. Add backend auth proxy routes
+
+Your backend should own:
+
+- `POST /auth/login`
+- `POST /auth/select-tenant`
+- `POST /auth/mfa/verify`
+- `POST /auth/mfa/verify-backup`
+- `POST /auth/refresh`
+- `POST /auth/logout`
+- `GET /auth/me`
+
+### 3. Use the browser-session SDK entry point where appropriate
+
+```ts
+import { createBrowserSessionClient } from "@iqauth/sdk/browser-session";
+
+const client = createBrowserSessionClient({
+  baseUrl: process.env.IQAUTH_BASE_URL!,
+});
+```
+
+This is for backend/session-aware browser flows. It is not a license to move refresh tokens back into browser state.
+
+### 4. Update frontend boot logic
+
+On app startup:
+
+1. call `/auth/me`
+2. if authenticated, hydrate user/session state
+3. if not authenticated, render signed-out state
+
+### 5. Update MFA and tenant-selection handling
+
+The browser should still handle the UX, but the backend should own the IQAuth exchange and cookie updates.
+
+### 6. Update logout and invalidation handling
+
+- logout should call backend logout
+- revoked or inactive sessions should force a clean signed-out state
+- session-expired UX should come from backend session truth, not stale browser state
+
+## Success Criteria
+
+- no refresh token is stored in durable browser-readable storage
+- page refresh restores auth through `/auth/me`
+- login, MFA, tenant selection, refresh, and logout all work through the backend boundary
+- revoked sessions do not strand the UI in a fake authenticated state

package/docs/FRESH_IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,188 @@
+# Fresh Implementation Guide
+
+Step-by-step integration guide for `@iqauth/sdk`, organized by environment.
+
+Do not start with code samples until you first choose the client model.
+
+## 1. Choose Your Environment
+
+| Environment | Recommended integration model |
+|--------|--------|
+| First-party web app | Backend proxy + `httpOnly` cookies |
+| Native mobile app | Authorization code + PKCE + secure storage |
+| Server-side app | Direct tokens or bearer-token verification |
+| Service / automation | API key |
+
+If you are building a browser application that you control, the default answer is: do not let browser JavaScript own the refresh token.
+
+## 2. First-Party Browser Apps
+
+### Recommended architecture
+
+- frontend talks to your backend
+- your backend talks to IQAuth
+- backend sets `httpOnly` cookies
+- frontend restores session from `/auth/me`
+
+### Backend responsibilities
+
+- `/auth/login`
+- `/auth/select-tenant`
+- `/auth/mfa/verify`
+- `/auth/mfa/verify-backup`
+- `/auth/refresh`
+- `/auth/logout`
+- `/auth/me`
+
+### Browser responsibilities
+
+- submit credentials to your backend
+- handle MFA and tenant selection UX
+- call `/auth/me` on app boot
+- let the backend own refresh and session invalidation
+
+### Minimal frontend shape
+
+```typescript
+async function login(email: string, password: string) {
+  const res = await fetch("/auth/login", {
+    method: "POST",
+    credentials: "include",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ email, password }),
+  });
+
+  return res.json();
+}
+
+async function loadSession() {
+  const res = await fetch("/auth/me", {
+    credentials: "include",
+  });
+
+  if (!res.ok) return null;
+  return res.json();
+}
+```
+
+### What not to do
+
+- do not store refresh tokens in `localStorage`
+- do not make the browser the source of truth for durable auth state
+- do not normalize direct token persistence as the default first-party pattern
+
+## 3. Native Mobile Apps
+
+### Recommended architecture
+
+- authorization code flow with PKCE
+- system browser / ASWebAuthenticationSession / Custom Tabs
+- deep link or universal link callback
+- secure storage only
+
+### Required elements
+
+- `state`
+- `nonce`
+- PKCE code verifier
+- PKCE code challenge (`S256`)
+
+### Token storage
+
+Allowed:
+
+- iOS Keychain
+- Android Keystore
+- an equivalent secure-storage abstraction
+
+Not acceptable:
+
+- plaintext async storage
+- shared preferences without secure wrapping
+- browser-style storage assumptions
+
+### Minimal mobile client shape
+
+```typescript
+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);
+  },
+});
+```
+
+Use this only after a PKCE-based login.
+
+## 4. Server-Side Applications
+
+This is the strongest current fit for the SDK.
+
+### Typical use cases
+
+- Express resource server
+- internal admin service
+- backend calling IQAuth APIs directly
+- request-scoped bearer verification
+
+### Example
+
+```typescript
+import { createServerClient } from "@iqauth/sdk/server";
+
+const client = createServerClient({
+  baseUrl: process.env.IQAUTH_BASE_URL!,
+});
+
+app.use("/api", client.middleware());
+```
+
+### Guidance
+
+- prefer request-scoped auth context
+- avoid shared mutable multi-user token state
+- use the provided `client.middleware()` for incoming bearer tokens by default
+- only drop to manual token verification when your framework cannot use the middleware shape
+
+## 5. Service / Automation Clients
+
+Use API keys whenever possible.
+
+```typescript
+const client = new IQAuthClient({
+  baseUrl: process.env.IQAUTH_BASE_URL!,
+  apiKey: process.env.IQAUTH_API_KEY!,
+});
+```
+
+Do not model services like interactive user sessions unless there is a specific product requirement.
+
+## 6. Authentication State Machine
+
+The login state machine still has three outcomes:
+
+```typescript
+type LoginResult =
+  | { status: "authenticated"; authMode: "token"; tokens: TokenPair; user: UserProfile }
+  | { status: "authenticated"; authMode: "session"; user: SessionUser }
+  | { status: "mfa_required"; mfaChallengeToken: string; availableMethods: string[] }
+  | { status: "tenant_selection"; tenantSelectionToken: string; tenants: Tenant[] };
+```
+
+That state machine is most directly usable in:
+
+- server-side apps
+- native mobile flows
+- controlled backend proxies
+
+It should not be read as permission to store the resulting refresh token in browser-readable storage for first-party web apps.
+
+## 7. Where To Go Next
+
+- Browser apps: [Auth Flows](./guides/auth-flows.md)
+- Mobile apps: [Mobile / Native Guide](./guides/mobile-native.md)
+- Session lifecycle: [Session Management](./guides/session-management.md)
+- Server verification: [Token Verification](./guides/token-verification.md)

package/docs/TARBALL_RELEASE_WORKFLOW.md

@@ -0,0 +1,98 @@
+# Tarball Release Workflow
+
+Use this workflow if you want `@iqauth/sdk` to be consumable by private application repos without publishing to public npm and without requiring each app to use registry auth tokens.
+
+## Recommended Flow
+
+1. bump the SDK version
+2. build the SDK
+3. generate a `.tgz` with `npm pack`
+4. distribute that tarball to the consuming app
+5. install the tarball into the app
+6. if the installed version changed, run the environment-specific setup prompt for that app
+
+## Release Commands
+
+From `packages/iqauth-sdk`:
+
+```bash
+npm version patch
+npm run build
+npm pack --cache /tmp/iqauth-npm-cache
+```
+
+That produces a tarball like:
+
+```bash
+iq-auth-sdk-1.0.1.tgz
+```
+
+## Install Commands
+
+### Local file path
+
+```bash
+npm install ./vendor/iq-auth-sdk-1.0.1.tgz
+```
+
+### Relative path during local development
+
+```bash
+npm install ../iq-auth-sdk-1.0.1.tgz
+```
+
+## Suggested App-Repo Layout
+
+If you want the app to carry the tarball directly:
+
+```text
+your-app/
+  vendor/
+    iq-auth-sdk-1.0.1.tgz
+```
+
+Then install from that path and commit the dependency reference in `package.json` or the lockfile.
+
+## Required Handoff After Install
+
+After installing a new tarball version:
+
+- identify the app type
+- run the matching setup prompt
+- verify the app against the current integration matrix
+
+App types:
+
+- first-party browser app
+- native mobile app
+- server platform app
+- service automation app
+
+See:
+
+- [App Integration Matrix](./APP_INTEGRATION_MATRIX.md)
+- [Integration Prompts](./integration-prompts/)
+
+## Version-Change Rule
+
+If the tarball version changed, do not stop at install.
+
+You should also:
+
+1. review the release notes or migration notes
+2. run the matching environment prompt
+3. verify that the app still follows the supported auth model
+
+## Why this flow exists
+
+This approach avoids:
+
+- public npm publication
+- self-hosted registry overhead
+- per-project registry auth tokens
+
+while still preserving:
+
+- versioned releases
+- reproducible installs
+- a clear migration path for app teams