@iqauth/sdk 2.0.0

package/docs/guides/token-verification.md

@@ -0,0 +1,178 @@
+# Token Verification
+
+## Purpose
+
+Verify JWT access tokens using RS256 with JWKS, decode tokens without verification, and check expiry. This is the recommended approach for server-side token validation.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- IQAuthService base URL (JWKS is fetched from `/.well-known/jwks.json`)
+- A valid JWT access token to verify
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `tokens` | `verify(token)` | Verify JWT via RS256/JWKS → `JwtClaims` |
+| `tokens` | `decode(token)` | Decode without verification → `JwtClaims \| null` |
+| `tokens` | `getClaims(token)` | Decode or throw → `JwtClaims` |
+| `tokens` | `isExpired(token)` | Check `exp` claim → `boolean` |
+| `tokens` | `clearCache()` | Clear JWKS cache (testing only) |
+
+## Step-by-Step
+
+### 1. Verify a Token (Server-Side)
+
+```typescript
+const claims = await client.tokens.verify(bearerToken);
+```
+
+Verification performs:
+1. Decodes the JWT header to extract the `kid` (key ID)
+2. Fetches the public key from JWKS (cached for 1 hour)
+3. Verifies the signature using RS256
+4. Validates the issuer (`auth.dispositioniq.com`)
+5. Validates the audience (`dispositioniq`, `iqcapture`, `iqreuse`, `iqvalidate`)
+6. Checks expiration
+
+### 2. Decode Without Verification (Client-Side)
+
+```typescript
+const claims = client.tokens.decode(token);
+// Returns JwtClaims | null (null if malformed)
+```
+
+### 3. Check Expiry
+
+```typescript
+if (client.tokens.isExpired(token)) {
+  // Refresh or re-authenticate
+}
+```
+
+### JWT Claims Structure
+
+```typescript
+interface JwtClaims {
+  sub: string;                  // User ID
+  email: string;                // User email
+  name: string;                 // Display name
+  tenantId: string;             // Current tenant
+  vendorId: string | null;      // Vendor ID (if vendor user)
+  roles: string[];              // Flat roles array
+  entitlements: string[];       // Product entitlements
+  sessionId: string;            // Current session ID
+  jti: string;                  // Unique token ID
+  iss: string;                  // "auth.dispositioniq.com"
+  aud: string[];                // Audience array
+  exp?: number;                 // Expiration (Unix timestamp)
+  iat?: number;                 // Issued at (Unix timestamp)
+  scopeContext?: ScopeContext;  // V2 scope context
+  loginMethod?: string;         // "password" | "pin" | "google"
+}
+```
+
+### JWKS Caching
+
+- Keys are cached for 1 hour (matches server's `Cache-Control: max-age=3600`)
+- On unknown `kid`, the cache is refreshed once and retried (handles key rotation)
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `TOKEN_INVALID` | Malformed, missing `kid`, or signature failure | Re-authenticate |
+| `TOKEN_EXPIRED` | `exp` claim is in the past | Refresh token |
+| `INTERNAL_ERROR` | Failed to fetch JWKS endpoint | Retry or check connectivity |
+
+```typescript
+import { IQAuthError } from "@iqauth/sdk";
+
+try {
+  const claims = await client.tokens.verify(token);
+} catch (err) {
+  if (err instanceof IQAuthError) {
+    if (err.code === "TOKEN_EXPIRED") {
+      // Attempt refresh
+    }
+    if (err.code === "TOKEN_INVALID") {
+      // Re-authenticate
+    }
+  }
+}
+```
+
+### Middleware Setup
+
+The recommended way to verify tokens in Express is via `iqAuthMiddleware`, which wraps token verification:
+
+```typescript
+import express from "express";
+import { createServerClient } from "@iqauth/sdk/server";
+
+const app = express();
+const client = createServerClient({
+  baseUrl: "https://auth.dispositioniq.com",
+});
+
+// Protect all /api routes — verifies Bearer token via JWKS
+app.use("/api", client.middleware());
+
+// Access verified claims via req.auth
+app.get("/api/me", (req, res) => {
+  res.json({
+    userId: req.auth!.sub,
+    email: req.auth!.email,
+    roles: req.auth!.roles,
+  });
+});
+```
+
+For more middleware options (optional auth, role/entitlement checks, custom error handlers), see [Middleware Reference](./middleware-reference.md).
+
+## Complete Example
+
+```typescript
+import express from "express";
+import { createServerClient } from "@iqauth/sdk/server";
+import { IQAuthError } from "@iqauth/sdk";
+
+const client = createServerClient({
+  baseUrl: "https://auth.dispositioniq.com",
+});
+
+// Option 1: Middleware (recommended for Express apps)
+const app = express();
+app.use("/api", client.middleware());
+app.get("/api/me", (req, res) => res.json(req.auth));
+
+// Option 2: Manual verification (for non-Express or custom flows)
+async function validateRequest(authHeader: string): Promise<{
+  valid: boolean;
+  claims?: import("@iqauth/sdk").JwtClaims;
+  error?: string;
+}> {
+  if (!authHeader?.startsWith("Bearer ")) {
+    return { valid: false, error: "Missing Bearer token" };
+  }
+
+  const token = authHeader.substring(7);
+
+  try {
+    const claims = await client.tokens.verify(token);
+    return { valid: true, claims };
+  } catch (err) {
+    if (err instanceof IQAuthError) {
+      return { valid: false, error: `${err.code}: ${err.message}` };
+    }
+    return { valid: false, error: "Unknown verification error" };
+  }
+}
+
+// Option 3: Client-side decode (no verification)
+function getUserIdFromToken(token: string): string | null {
+  const claims = client.tokens.decode(token);
+  return claims?.sub ?? null;
+}
+```

package/docs/guides/user-management.md

@@ -0,0 +1,184 @@
+# User Management
+
+## Purpose
+
+Manage user profiles, provision new users, and handle account lifecycle (deactivation, reactivation, unlock).
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- Authenticated user with appropriate role:
+  - Any authenticated user: `getCurrent()`, `update()`, `updatePassword()`
+  - `tenant_admin`: `list()`, `deactivate()`, `reactivate()`, `unlock()`
+  - `platform_admin` or admin API key: `create()`
+
+## Environment Note
+
+The token examples in this guide are for trusted runtimes.
+
+If your UI is a first-party browser app, call these operations through your backend session layer instead of storing raw tokens in browser-readable storage.
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `users` | `getCurrent()` | Get current user profile |
+| `users` | `getById(userId)` | Get user by ID |
+| `users` | `list(params?)` | List users (filterable) |
+| `users` | `create(tenantId, data)` | Provision a new user |
+| `users` | `update(data)` | Update current user profile |
+| `users` | `deactivate(userId)` | Deactivate a user |
+| `users` | `reactivate(userId)` | Reactivate a user |
+| `users` | `unlock(userId)` | Unlock a locked account |
+| `users` | `getPermissions(userId, product)` | Get effective permissions |
+| `users` | `updatePassword(current, new)` | Change password |
+
+## Step-by-Step
+
+### 1. Get Current User
+
+```typescript
+const me = await client.users.getCurrent();
+```
+
+Returns `UserProfile`:
+
+```typescript
+interface UserProfile {
+  id: string;
+  email: string;
+  name: string;
+  picture?: string | null;
+  isActive: boolean;
+  tenantId?: string;
+  vendorId?: string | null;
+  roles?: string[];
+  isDemoAccount?: boolean;
+  createdAt?: string;
+  updatedAt?: string;
+  mustChangePassword?: boolean;
+  passwordExpiresAt?: string | null;
+  externalId?: string | null;
+}
+```
+
+### 2. List Users
+
+```typescript
+const allUsers = await client.users.list();
+const tenantUsers = await client.users.list({ tenantId: "tenant-uuid" });
+const filtered = await client.users.list({ email: "user@example.com" });
+```
+
+### 3. Provision a New User
+
+```typescript
+const result = await client.users.create("tenant-uuid", {
+  email: "newuser@example.com",
+  name: "New User",
+  role: "user",
+  vendorId: "vendor-uuid",
+  isActive: true,
+  externalId: "ext-123",
+});
+// { userId, email, tenantId, role, vendorId }
+```
+
+Note: `create()` requires a `tenantId` because user provisioning is tenant-scoped. See [DECISION-003](../../DECISIONS.md).
+
+### 4. Update Profile
+
+```typescript
+await client.users.update({ name: "New Name", picture: "https://example.com/avatar.jpg" });
+```
+
+### 5. Account Lifecycle
+
+```typescript
+await client.users.deactivate("user-uuid");   // Soft disable
+await client.users.reactivate("user-uuid");    // Re-enable
+await client.users.unlock("user-uuid");        // Unlock after lockout
+```
+
+### 6. Change Password
+
+```typescript
+await client.users.updatePassword("currentPassword", "newPassword");
+```
+
+Note: There is no `users.delete()` method. Use `client.tenants.removeUser()` or `users.deactivate()`. See [DECISION-004](../../DECISIONS.md).
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `NOT_FOUND` | User does not exist | Check user ID |
+| `INSUFFICIENT_PERMISSIONS` | Caller lacks admin role | Requires `tenant_admin` |
+| `ALREADY_EXISTS` | Email already registered | Use different email |
+| `VALIDATION_ERROR` | Invalid request data | Check required fields |
+| `PASSWORD_POLICY_VIOLATION` | Password doesn't meet policy | Strengthen password |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.users.create(tenantId, { email, name, role: "user" });
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.ALREADY_EXISTS) {
+    console.log("User already exists with this email");
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient, IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  // Trusted runtime example
+  accessToken: adminAccessToken,
+  refreshToken: adminRefreshToken,
+});
+
+async function provisionAndSetupUser(tenantId: string, email: string, name: string) {
+  try {
+    const result = await client.users.create(tenantId, {
+      email,
+      name,
+      role: "user",
+      isActive: true,
+    });
+    console.log("Provisioned user:", result.userId);
+
+    const user = await client.users.getById(result.userId);
+    console.log("User profile:", user.name, user.email, user.isActive);
+
+    return result;
+  } catch (err) {
+    if (err instanceof IQAuthError) {
+      if (err.code === ErrorCodes.ALREADY_EXISTS) {
+        const users = await client.users.list({ email });
+        return { userId: users[0].id, email, tenantId, role: "user", vendorId: null };
+      }
+    }
+    throw err;
+  }
+}
+```
+
+## API Reference
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `getCurrent()` | GET | `/api/v1/users/me` |
+| `getById(id)` | GET | `/api/v1/users/:id` |
+| `list(params?)` | GET | `/api/v1/users` |
+| `create(tenantId, data)` | POST | `/api/v1/tenants/:tenantId/users/provision` |
+| `update(data)` | PATCH | `/api/v1/users/me` |
+| `deactivate(id)` | PATCH | `/api/v1/users/:id/deactivate` |
+| `reactivate(id)` | PATCH | `/api/v1/users/:id/reactivate` |
+| `unlock(id)` | PATCH | `/api/v1/users/:id/unlock` |
+| `getPermissions(id, product)` | GET | `/api/v1/users/:id/permissions?product=...` |
+| `updatePassword(current, new)` | POST | `/api/v1/auth/password/change` |

package/docs/guides/webhooks.md

@@ -0,0 +1,136 @@
+# Webhooks
+
+## Purpose
+
+Subscribe to IQAuth events and receive HTTP callbacks. Manage webhook endpoints, test connectivity, view delivery history, and rotate signing secrets.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- `tenant_admin` role for webhook management
+- A publicly accessible HTTPS URL to receive webhook events
+
+## Environment Note
+
+The management examples in this guide assume a trusted backend, admin script, or other secure runtime.
+
+For first-party browser apps, keep webhook administration behind your backend session model.
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `webhooks` | `createEndpoint(data)` | Create endpoint → `{ endpoint, secret }` |
+| `webhooks` | `listEndpoints()` | List endpoints → `WebhookEndpoint[]` |
+| `webhooks` | `deleteEndpoint(id)` | Delete endpoint |
+| `webhooks` | `getDeliveries(endpointId)` | Delivery history → `WebhookDelivery[]` |
+| `webhooks` | `testEndpoint(id)` | Send test event → `WebhookTestResult` |
+| `webhooks` | `rotateSecret(id)` | Rotate signing secret → `{ newSecret }` |
+
+## Step-by-Step
+
+### 1. Create Endpoint
+
+```typescript
+const { endpoint, secret } = await client.webhooks.createEndpoint({
+  url: "https://myapp.com/webhooks/iqauth",
+  events: ["user.created", "user.deactivated", "session.created"],
+});
+// IMPORTANT: Store secret securely — used to verify webhook signatures
+```
+
+### 2. Test Endpoint
+
+```typescript
+const result = await client.webhooks.testEndpoint(endpoint.id);
+console.log("Test status:", result.statusCode); // 200
+```
+
+### 3. View Deliveries
+
+```typescript
+const deliveries = await client.webhooks.getDeliveries(endpoint.id);
+for (const d of deliveries) {
+  console.log(`${d.event} → ${d.statusCode} at ${d.deliveredAt}`);
+}
+```
+
+### 4. Rotate Secret
+
+```typescript
+const { newSecret } = await client.webhooks.rotateSecret(endpoint.id);
+// Update your webhook handler with the new secret
+```
+
+### 5. List / Delete
+
+```typescript
+const endpoints = await client.webhooks.listEndpoints();
+await client.webhooks.deleteEndpoint(endpoint.id);
+```
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `NOT_FOUND` | Endpoint doesn't exist | Check endpoint ID |
+| `VALIDATION_ERROR` | Invalid URL or events | Check request format |
+| `INSUFFICIENT_PERMISSIONS` | Caller lacks admin role | Requires `tenant_admin`+ |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.webhooks.createEndpoint({ url, events });
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.VALIDATION_ERROR) {
+    console.error("Invalid webhook URL or events:", err.message);
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  // Trusted runtime example
+  accessToken: adminToken,
+  refreshToken: adminRefreshToken,
+});
+
+async function setupWebhooks(callbackUrl: string) {
+  const { endpoint, secret } = await client.webhooks.createEndpoint({
+    url: callbackUrl,
+    events: ["user.created", "user.deactivated", "session.created", "session.terminated"],
+  });
+  console.log("Webhook endpoint:", endpoint.id);
+  console.log("Secret:", secret); // Store securely!
+
+  const testResult = await client.webhooks.testEndpoint(endpoint.id);
+  if (testResult.statusCode !== 200) {
+    console.error("Webhook test failed:", testResult.statusCode);
+    await client.webhooks.deleteEndpoint(endpoint.id);
+    throw new Error("Webhook endpoint not responding correctly");
+  }
+  console.log("Webhook test passed");
+
+  const deliveries = await client.webhooks.getDeliveries(endpoint.id);
+  console.log(`${deliveries.length} deliveries logged`);
+
+  return { endpointId: endpoint.id, secret };
+}
+```
+
+## API Reference
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `createEndpoint(data)` | POST | `/api/v1/webhooks/endpoints` |
+| `listEndpoints()` | GET | `/api/v1/webhooks/endpoints` |
+| `deleteEndpoint(id)` | DELETE | `/api/v1/webhooks/endpoints/:id` |
+| `getDeliveries(endpointId)` | GET | `/api/v1/webhooks/deliveries?endpointId=...` |
+| `testEndpoint(id)` | POST | `/api/v1/webhooks/endpoints/:id/test` |
+| `rotateSecret(id)` | POST | `/api/v1/webhooks/endpoints/:id/rotate-secret` |

package/docs/integration-prompts/README.md

@@ -0,0 +1,20 @@
+# Integration Prompts
+
+These prompts are intended for downstream application teams adopting `@iqauth/sdk`.
+
+Start here if the SDK is being distributed as a `.tgz`:
+
+- [Install from Tarball](./install-from-tarball.md)
+- [Migrate from Local packages/ Source](./migrate-from-local-packages-source.md)
+
+Choose the prompt that matches the application environment:
+
+- [First-Party Browser App](./first-party-browser-app.md)
+- [Native Mobile App](./native-mobile-app.md)
+- [Server Platform App](./server-platform-app.md)
+- [Service Automation App](./service-automation-app.md)
+
+Use these prompts together with:
+
+- [App Integration Matrix](../APP_INTEGRATION_MATRIX.md)
+- [Fresh Implementation Guide](../FRESH_IMPLEMENTATION_GUIDE.md)

package/docs/integration-prompts/first-party-browser-app.md

@@ -0,0 +1,29 @@
+# Prompt: First-Party Browser App
+
+Use this prompt when updating a first-party web app that integrates with IQAuth.
+
+```md
+You are integrating a first-party browser application with IQAuth.
+
+Requirements:
+- Use a backend-managed cookie session, not browser-owned durable tokens.
+- The browser must not store refresh tokens in localStorage, sessionStorage, or other durable browser-readable storage.
+- The backend must 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
+- On frontend boot, restore auth state from /auth/me.
+- Treat revoked, inactive, and expired sessions as terminal signed-out transitions.
+- If SDK usage is needed in the browser/session-aware layer, use @iqauth/sdk/browser-session.
+- Do not normalize token-owning browser patterns in examples or implementation.
+
+Deliverables:
+- backend auth proxy routes
+- frontend auth/session bootstrap
+- logout/session invalidation handling
+- short verification checklist
+```

package/docs/integration-prompts/install-from-tarball.md

@@ -0,0 +1,41 @@
+# Prompt: Install from Tarball
+
+Use this prompt when a downstream app needs to install or update `@iqauth/sdk` from a `.tgz` release artifact.
+
+```md
+You are installing @iqauth/sdk into an application from a versioned .tgz tarball.
+
+Inputs:
+- tarball path or filename
+- previous installed SDK version, if any
+- app type: first-party browser, native mobile, server platform, or service automation
+
+Requirements:
+- Install the tarball as a package dependency, not by copying SDK source files into the app.
+- Preserve a reproducible dependency reference in package.json and/or the lockfile.
+- Determine whether the installed SDK version changed.
+
+Install step:
+- use npm install <tarball-path>
+
+After install:
+- if the version changed, continue immediately into the environment-specific setup prompt
+- if the app type is first-party browser, use the first-party browser setup prompt
+- if the app type is native mobile, use the native mobile setup prompt
+- if the app type is server platform, use the server platform setup prompt
+- if the app type is service automation, use the service automation setup prompt
+
+Do not stop at “package installed” if the version changed.
+
+Always verify:
+- the app is using the correct SDK entry point
+- the app still matches the supported auth model for its environment
+- any old browser token-owning patterns are removed if this is a first-party web app
+```
+
+## Next Prompt by App Type
+
+- [First-Party Browser App](./first-party-browser-app.md)
+- [Native Mobile App](./native-mobile-app.md)
+- [Server Platform App](./server-platform-app.md)
+- [Service Automation App](./service-automation-app.md)

package/docs/integration-prompts/migrate-from-local-packages-source.md

@@ -0,0 +1,57 @@
+# Prompt: Migrate from Local `packages/` Source
+
+Use this prompt when an application currently consumes `@iqauth/sdk` from a checked-in local `packages/` source folder and needs to move to the tarball-based distribution model.
+
+```md
+You are migrating an application away from a local checked-in `packages/` source dependency for `@iqauth/sdk`.
+
+Current state:
+- the app currently resolves the SDK from a local `packages/` folder or copied source tree
+
+Target state:
+- the app installs a versioned `.tgz` release artifact instead
+- the tarball lives in a committed repo path such as `vendor/iq-auth-sdk-x.y.z.tgz`
+- the dependency is reproducible in local development, CI, and deployment
+
+Requirements:
+- remove the local source-based dependency on `packages/`
+- install the SDK from a `.tgz` artifact instead of copied source files
+- preserve a clean dependency reference in `package.json` and the lockfile
+- do not leave duplicate SDK resolution paths active
+- identify whether the SDK version changed during the migration
+
+Recommended target layout:
+- `vendor/iq-auth-sdk-x.y.z.tgz`
+
+Install step:
+- use `npm install ./vendor/iq-auth-sdk-x.y.z.tgz`
+
+Migration checklist:
+1. identify how the app currently references the local `packages/` SDK
+2. remove that reference cleanly
+3. add the tarball to `vendor/`
+4. install the tarball dependency
+5. verify imports still resolve correctly
+6. verify the app still uses the correct SDK entry point for its environment
+
+After install:
+- if the installed version changed, continue immediately into the matching environment-specific setup prompt
+- if the app is first-party browser, use the first-party browser setup prompt
+- if the app is native mobile, use the native mobile setup prompt
+- if the app is a server platform, use the server platform setup prompt
+- if the app is a service automation app, use the service automation setup prompt
+
+Do not stop at “dependency swapped” if the SDK version changed.
+
+Always verify:
+- only one SDK source remains active
+- the local `packages/` path is no longer part of dependency resolution
+- the app matches the supported auth model for its environment
+```
+
+## Next Prompt by App Type
+
+- [First-Party Browser App](./first-party-browser-app.md)
+- [Native Mobile App](./native-mobile-app.md)
+- [Server Platform App](./server-platform-app.md)
+- [Service Automation App](./service-automation-app.md)

package/docs/integration-prompts/native-mobile-app.md

@@ -0,0 +1,24 @@
+# Prompt: Native Mobile App
+
+Use this prompt when updating a native mobile application that integrates with IQAuth.
+
+```md
+You are integrating a native mobile application with IQAuth.
+
+Requirements:
+- Use authorization code flow with PKCE.
+- Launch authentication in the system browser / ASWebAuthenticationSession / Custom Tabs.
+- Use state, nonce, code_verifier, and S256 code_challenge.
+- Exchange the authorization code securely.
+- Store access and refresh tokens only in secure OS-backed storage such as Keychain or Keystore.
+- If SDK usage is needed, use @iqauth/sdk/mobile.
+- Do not use browser cookie-session assumptions as the primary mobile pattern.
+- Do not store tokens in plaintext async storage or browser-style storage.
+
+Deliverables:
+- PKCE login flow
+- secure token storage implementation
+- refresh handling
+- logout and token-clearing flow
+- short verification checklist
+```

package/docs/integration-prompts/server-platform-app.md

@@ -0,0 +1,20 @@
+# Prompt: Server Platform App
+
+Use this prompt when updating a trusted backend platform or resource server that integrates with IQAuth.
+
+```md
+You are integrating a trusted server-side platform application with IQAuth.
+
+Requirements:
+- Use @iqauth/sdk/server.
+- If the app accepts bearer tokens, use the SDK middleware by default rather than re-implementing token verification manually.
+- Attach verified auth context to incoming requests.
+- Enforce roles, entitlements, and route authorization on the server.
+- Keep token handling request-scoped or service-scoped; do not share mutable multi-user token state.
+
+Deliverables:
+- server client creation
+- middleware integration
+- protected route examples
+- verification checklist showing middleware-backed auth on protected routes
+```