@iqauth/sdk 2.0.0

package/docs/V1_TO_V2_UPGRADE_GUIDE.md

@@ -0,0 +1,318 @@
+# V1 to V2 Authorization Upgrade Guide
+
+This guide covers migrating from V1 (flat JWT roles) to V2 (scoped memberships + permission groups).
+
+## What Changed
+
+| Aspect | V1 (Flat Roles) | V2 (Scoped Auth) |
+|--------|-----------------|-------------------|
+| Role storage | `roles[]` in JWT | Memberships table + JWT `scopeContext` |
+| Scope | Tenant-wide | Vendor / Source / Client scoped |
+| Permission model | Implicit (role name checks) | Explicit permission groups with inheritance |
+| SDK modules | `client.permissions` | `client.memberships` + `client.scope` + `client.permissionGroups` |
+| Tenant flag | — | `enableScopedAuth: true` |
+
+## Prerequisites
+
+- SDK version with `memberships`, `scope`, and `permissionGroups` modules
+- IQAuth server supporting the V2 scoped auth endpoints
+
+## Environment Note
+
+Any examples in this guide that manipulate bearer tokens directly assume a trusted runtime or secure mobile storage.
+
+For first-party browser apps, keep the token lifecycle in your backend session layer.
+
+## Step 1: Enable Scoped Auth on Your Tenant
+
+```typescript
+await client.tenants.update(tenantId, {
+  enableScopedAuth: true,
+});
+```
+
+This flag enables the scoped authorization system for that tenant. V1 role checks (`roles[]` in JWT) continue to work — V2 is additive.
+
+## Step 2: Create Your Entity Hierarchy
+
+V2 authorization scopes down through a three-level hierarchy: **Vendor → Source → Client**.
+
+```typescript
+// Create a vendor
+const vendor = await client.vendors.create({
+  name: "Acme Disposal",
+  slug: "acme-disposal",
+});
+
+// Create a source under the vendor
+const source = await client.sources.create(vendor.id, {
+  name: "Acme MRF North",
+  slug: "acme-mrf-north",
+});
+
+// Create a client under the source
+const clientEntity = await client.sources.createClient(source.id, {
+  name: "City of Springfield",
+  slug: "springfield",
+});
+
+// Link them in the hierarchy
+await client.hierarchy.linkVendorSource(vendor.id, source.id);
+await client.hierarchy.linkSourceClient(source.id, clientEntity.id);
+```
+
+## Step 3: Define Roles
+
+Create tenant-scoped roles if you need custom ones beyond the system roles:
+
+```typescript
+await client.roles.create(tenantId, {
+  name: "site_manager",
+  description: "Manages operations at a specific source",
+  hierarchyLevel: 30,
+});
+```
+
+System roles (`platform_admin`, `tenant_admin`, `vendor_admin`) are already available.
+
+## Step 4: Grant Scoped Memberships
+
+Replace flat role assignments with scoped memberships:
+
+**Before (V1):**
+```typescript
+// V1: flat role — user is "vendor_admin" for the entire tenant
+await client.roles.assignRole(tenantId, userId, { roleName: "vendor_admin" });
+```
+
+**After (V2):**
+```typescript
+// V2: scoped membership — user is "vendor_admin" for a specific vendor
+await client.memberships.grant({
+  userId,
+  roleName: "vendor_admin",
+  scopeType: "vendor",
+  scopeId: vendorId,
+});
+```
+
+Valid `scopeType` values: `"tenant"`, `"vendor"`, `"source"`, `"client"`.
+
+## Step 5: Set Up Permission Groups
+
+Permission groups give fine-grained control beyond role-based access:
+
+```typescript
+// Create a group
+const group = await client.permissionGroups.create(
+  tenantId,
+  "Capture Operators",
+  "Can operate IQCapture at assigned sources",
+);
+
+// Add permissions to the group
+await client.permissionGroups.addPermission(tenantId, group.id, {
+  appKey: "iqcapture",
+  nodeKey: "capture.operate",
+  effect: "allow",
+});
+
+await client.permissionGroups.addPermission(tenantId, group.id, {
+  appKey: "iqcapture",
+  nodeKey: "capture.reports.view",
+  effect: "allow",
+});
+
+// Assign user to the group
+await client.permissionGroups.assignUserToGroup(tenantId, userId, group.id);
+```
+
+### Permission Group Inheritance
+
+Groups can inherit permissions from other groups:
+
+```typescript
+const baseGroup = await client.permissionGroups.create(tenantId, "Base Viewer");
+const adminGroup = await client.permissionGroups.create(tenantId, "Admin");
+
+// Admin inherits all permissions from Base Viewer
+await client.permissionGroups.addInheritance(tenantId, adminGroup.id, baseGroup.id);
+```
+
+### User Permission Overrides
+
+Override group permissions for specific users:
+
+```typescript
+// Deny a specific permission for one user (overrides group "allow")
+await client.permissionGroups.addUserOverride(tenantId, userId, {
+  appKey: "iqcapture",
+  nodeKey: "capture.delete",
+  effect: "deny",
+  weight: 100, // Higher weight wins
+});
+```
+
+## Step 6: Check Effective Permissions
+
+```typescript
+// Get all effective permissions for a user in an app
+const perms = await client.permissionGroups.getEffectivePermissions(
+  tenantId,
+  userId,
+  { appKey: "iqcapture" },
+);
+
+// Check a specific permission
+const check = await client.permissionGroups.checkPermission(
+  tenantId,
+  userId,
+  "iqcapture",
+  "capture.operate",
+);
+if (check.allowed) {
+  // User can operate
+}
+```
+
+## Step 7: Scope Switching
+
+In V2, users can switch their active scope context to work within a specific vendor, source, or client:
+
+```typescript
+// See available scopes (hierarchical tree)
+const tree = await client.scope.getAvailable();
+// tree.vendors[0].sources[0].clients[0]
+
+// Switch to a specific vendor scope
+const { accessToken, scopeContext } = await client.scope.switchScope(
+  "vendor",
+  vendorId,
+);
+
+// The new token has scopeContext embedded
+// Update the client with the new token
+client.setTokens({ accessToken, refreshToken: client.getRefreshToken()! });
+
+// Now all API calls are scoped to that vendor
+```
+
+The `scopeContext` in the JWT contains:
+
+```typescript
+interface ScopeContext {
+  type: string;   // "vendor" | "source" | "client"
+  id: string;     // Entity ID
+  role: string;   // User's role in that scope
+  membershipId: string;
+}
+```
+
+## Step 8: Update Your Middleware
+
+V1 middleware only checked `roles[]`. For V2, also check scoped permissions:
+
+```typescript
+import { iqAuthMiddleware } from "@iqauth/sdk";
+
+// V1 style (still works)
+app.use(iqAuthMiddleware(client, {
+  requiredRoles: ["vendor_admin"],
+}));
+
+// V2 style — check entitlements + scoped role in route handler
+app.get("/api/sources/:sourceId/data", async (req, res) => {
+  const { auth } = req;
+  if (!auth) return res.status(401).json({ error: "Not authenticated" });
+
+  // Check the scope context in the JWT
+  if (auth.scopeContext?.type === "source" && auth.scopeContext.id === req.params.sourceId) {
+    // User has switched to this source scope — proceed
+  } else {
+    // Check membership server-side
+    const { memberships } = await client.memberships.listForScope("source", req.params.sourceId);
+    const userMembership = memberships.find(m => m.userId === auth.sub && m.isActive);
+    if (!userMembership) {
+      return res.status(403).json({ error: "No access to this source" });
+    }
+  }
+});
+```
+
+## Migration Checklist
+
+- [ ] Enable `enableScopedAuth` on target tenants
+- [ ] Create entity hierarchy (vendors, sources, clients)
+- [ ] Link hierarchy entities
+- [ ] Create any custom roles needed
+- [ ] Grant scoped memberships for existing users
+- [ ] Set up permission groups for fine-grained control
+- [ ] Register your app manifest with permission nodes
+- [ ] Update API route handlers to check `scopeContext` or memberships
+- [ ] Update frontend to handle scope switching UI
+- [ ] Test effective permissions with `checkPermission`
+
+## Dual-Write Period
+
+During migration, V1 and V2 coexist. Follow these rules:
+
+**Coexistence rules:**
+1. Keep V1 role assignments active while granting V2 memberships — don't remove V1 roles until V2 is fully verified
+2. Any new user provisioning must create both V1 role assignment AND V2 scoped membership
+3. Any role change must be applied in both systems during the transition
+4. Keep V1 middleware (`requiredRoles`) on existing routes while adding V2 checks to new routes
+
+**Rollback guardrails:**
+- Setting `enableScopedAuth: false` reverts the tenant to V1-only mode; V2 membership data is preserved but inactive
+- `client.permissions.hasRole()` continues to work even with V2 enabled, so V1 route guards are always safe
+- If a V2 permission check returns unexpected results, fall back to V1 role check while investigating
+
+```typescript
+// Dual-write: grant both V1 role and V2 membership
+await client.roles.assignRole(tenantId, userId, { roleName: "vendor_admin" });
+await client.memberships.grant({
+  userId, roleName: "vendor_admin", scopeType: "vendor", scopeId: vendorId,
+});
+```
+
+## Verify Migration Complete
+
+Run these checks before removing V1 role logic:
+
+- [ ] **No V1-only route guards remain**: Search codebase for `requiredRoles` without a parallel V2 `scopeContext` check
+- [ ] **All users have memberships**: `client.memberships.listForTenant()` returns at least one membership per active user
+- [ ] **scopeContext coverage**: Decode a sample of JWTs and confirm `scopeContext` is present after login + scope selection
+- [ ] **Permission group parity**: For each V1 role-gated feature, verify `client.permissionGroups.checkPermission()` returns the expected result
+- [ ] **No dual-write code**: Remove all V1 role assignment calls (`client.roles.assignRole`) that shadow V2 membership grants
+- [ ] **Frontend scope switching works**: Confirm users can switch scope and the UI reflects the correct entity context
+
+```typescript
+// Automated migration verification
+async function verifyMigrationComplete(tenantId: string) {
+  const users = await client.tenants.getUsers(tenantId);
+  const { memberships } = await client.memberships.listForTenant();
+
+  const usersWithMemberships = new Set(memberships.map(m => m.userId));
+  const missing = users.filter(u => u.isActive && !usersWithMemberships.has(u.id));
+
+  if (missing.length > 0) {
+    console.error("Users missing V2 memberships:", missing.map(u => u.userId));
+    return false;
+  }
+
+  const groups = await client.permissionGroups.list(tenantId);
+  if (groups.length === 0) {
+    console.warn("No permission groups defined — V2 fine-grained permissions not configured");
+  }
+
+  console.log("Migration verification passed");
+  return true;
+}
+```
+
+## Backward Compatibility
+
+- V1 `roles[]` continues to appear in JWTs even with V2 enabled
+- `client.permissions.hasRole()` still works for tenant-wide role checks
+- V2 is additive — you don't need to migrate all routes at once
+- The `entitlements[]` claim is unchanged between V1 and V2

package/docs/guides/api-keys.md

@@ -0,0 +1,130 @@
+# API Keys
+
+## Purpose
+
+Create, list, revoke, and introspect API keys for service-to-service authentication. API keys are sent as `X-API-Key` headers instead of Bearer tokens.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- `tenant_admin` or `platform_admin` role for API key management
+
+## Environment Note
+
+The admin client examples in this guide assume a trusted runtime, such as a backend service, CLI, or secure mobile context.
+
+For first-party browser apps, manage the admin session through your backend cookie session instead of exposing raw refresh tokens to browser JavaScript.
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `apiKeys` | `create(data)` | Create API key → `{ key, rawKey }` |
+| `apiKeys` | `list(params?)` | List API keys → `ApiKeyInfo[]` |
+| `apiKeys` | `revoke(id)` | Revoke API key |
+| `apiKeys` | `introspect(apiKey)` | Introspect key metadata |
+
+## Step-by-Step
+
+### 1. Create an API Key
+
+```typescript
+const { key, rawKey } = await client.apiKeys.create({
+  name: "CI Pipeline Key",
+  scopes: ["users:read", "tenants:read"],
+  expiresAt: "2027-01-01T00:00:00Z",
+  tenantId: "tenant-uuid",
+});
+// IMPORTANT: rawKey is only shown once — store it securely
+```
+
+### 2. Use an API Key
+
+```typescript
+const serviceClient = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  apiKey: rawKey,
+});
+// All requests now use X-API-Key header
+const users = await serviceClient.users.list();
+```
+
+When both `apiKey` and `accessToken` are set, the SDK prefers `apiKey`.
+
+### 3. List / Revoke
+
+```typescript
+const allKeys = await client.apiKeys.list();
+const tenantKeys = await client.apiKeys.list({ tenantId: "tenant-uuid" });
+await client.apiKeys.revoke(keyId);
+```
+
+### 4. Introspect
+
+```typescript
+const info = await client.apiKeys.introspect("iqk_live_abc123...");
+// { tenantId, scopes, name, ... }
+```
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `API_KEY_INVALID` | Key is invalid or expired | Use valid key |
+| `API_KEY_REQUIRED` | Endpoint requires API key | Set `apiKey` on client |
+| `INSUFFICIENT_PERMISSIONS` | Caller lacks admin role | Requires `tenant_admin`+ |
+| `NOT_FOUND` | Key ID not found | Check key ID |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.apiKeys.introspect(apiKey);
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.API_KEY_INVALID) {
+    console.error("Invalid or expired API key");
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient, IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+const adminClient = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  // Trusted runtime example
+  accessToken: adminToken,
+  refreshToken: adminRefreshToken,
+});
+
+async function setupServiceKey(name: string, scopes: string[]) {
+  const { key, rawKey } = await adminClient.apiKeys.create({
+    name,
+    scopes,
+    expiresAt: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString(),
+  });
+  console.log("Created key:", key.id, "prefix:", key.prefix);
+  // Store rawKey in your secrets manager
+
+  const serviceClient = new IQAuthClient({
+    baseUrl: "https://auth.dispositioniq.com",
+    apiKey: rawKey,
+  });
+
+  const users = await serviceClient.users.list();
+  console.log("Service key works — found", users.length, "users");
+
+  return { keyId: key.id, rawKey };
+}
+```
+
+## API Reference
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `create(data)` | POST | `/api/v1/api-keys` |
+| `list(params?)` | GET | `/api/v1/api-keys` |
+| `revoke(id)` | DELETE | `/api/v1/api-keys/:id` |
+| `introspect(apiKey)` | POST | `/api/v1/api-keys/introspect` |

package/docs/guides/app-registration.md

@@ -0,0 +1,149 @@
+# App Registration
+
+## Purpose
+
+Register applications and their permission node trees with IQAuth. Used by the V2 permission system to define what permissions exist for each application.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- `platform_admin` role
+- `apps.manage` permission on the `iqauth-admin` app
+
+## Environment Note
+
+These examples assume a trusted administrative runtime. Do not treat them as guidance to persist admin refresh tokens in first-party browser JavaScript.
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `apps` | `list()` | List registered apps → `AppInfo[]` |
+| `apps` | `get(appKey)` | Get app with permission nodes |
+| `apps` | `register(manifest)` | Register/sync app manifest (idempotent) |
+| `apps` | `isRegistered(appKey)` | Check if app exists → `boolean` |
+
+## Step-by-Step
+
+### 1. Define Your Manifest
+
+```typescript
+const manifest = {
+  key: "iqcapture",
+  name: "IQ Capture",
+  description: "Image capture and classification tool",
+  version: "2.1.0",
+  permissions: [
+    {
+      key: "capture",
+      label: "Capture",
+      children: [
+        { key: "capture.operate", label: "Operate Capture Station" },
+        { key: "capture.configure", label: "Configure Capture Settings" },
+        {
+          key: "capture.reports",
+          label: "Reports",
+          children: [
+            { key: "capture.reports.view", label: "View Reports" },
+            { key: "capture.reports.export", label: "Export Reports" },
+          ],
+        },
+      ],
+    },
+  ],
+};
+```
+
+### 2. Register
+
+```typescript
+const result = await client.apps.register(manifest);
+// { appId: "uuid", nodesUpserted: 5 }
+```
+
+This is idempotent — calling again updates the existing app and upserts permission nodes. Maps to `POST /api/v1/apps/sync`. See [DECISION-010](../../DECISIONS.md).
+
+### 3. List / Get
+
+```typescript
+const apps = await client.apps.list();
+const app = await client.apps.get("iqcapture");
+// app.permissionNodes contains the full tree
+```
+
+### 4. Check Registration
+
+```typescript
+const exists = await client.apps.isRegistered("iqcapture"); // catches 404
+```
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `INSUFFICIENT_PERMISSIONS` | Not `platform_admin` | Requires elevated role |
+| `VALIDATION_ERROR` | Invalid manifest | Check required fields |
+| `NOT_FOUND` | App key doesn't exist (for `get`) | Register first |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.apps.register(manifest);
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.INSUFFICIENT_PERMISSIONS) {
+    console.error("Requires platform_admin role");
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  // Trusted runtime example
+  accessToken: platformAdminToken,
+  refreshToken: platformAdminRefreshToken,
+});
+
+async function registerMyApp() {
+  const isAlreadyRegistered = await client.apps.isRegistered("myapp");
+
+  const result = await client.apps.register({
+    key: "myapp",
+    name: "My Application",
+    version: "1.0.0",
+    permissions: [
+      {
+        key: "data",
+        label: "Data Access",
+        children: [
+          { key: "data.read", label: "Read Data" },
+          { key: "data.write", label: "Write Data" },
+          { key: "data.delete", label: "Delete Data" },
+        ],
+      },
+    ],
+  });
+
+  console.log(
+    isAlreadyRegistered ? "Updated" : "Created",
+    `app ${result.appId} with ${result.nodesUpserted} permission nodes`,
+  );
+
+  const app = await client.apps.get("myapp");
+  console.log("Permission nodes:", app.permissionNodes.map(n => n.key));
+}
+```
+
+## API Reference
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `list()` | GET | `/api/v1/apps` |
+| `get(appKey)` | GET | `/api/v1/apps/:appKey` |
+| `register(manifest)` | POST | `/api/v1/apps/sync` |
+| `isRegistered(appKey)` | GET | `/api/v1/apps/:appKey` (catches 404) |