@iqauth/sdk 2.0.0

package/docs/guides/scoped-authorization.md

@@ -0,0 +1,247 @@
+# Scoped Authorization (V2)
+
+## Purpose
+
+Implement V2 scoped authorization using entity-scoped memberships, scope switching, and permission groups with inheritance. Extends the V1 flat role model.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- Tenant with `enableScopedAuth: true` (set via `client.tenants.update()`)
+- Entity hierarchy created (vendors, sources, clients)
+- `tenant_admin` or `platform_admin` role
+
+## Environment Note
+
+Scope-switching token examples in this guide assume a trusted runtime or secure mobile storage.
+
+For first-party browser apps, perform scope-sensitive operations through your backend session layer.
+
+## SDK Methods
+
+### MembershipsModule
+
+| Method | Description |
+|--------|-------------|
+| `grant(data)` | Grant scoped membership → `Membership` |
+| `listForUser(userId, tenantId)` | List user's memberships |
+| `listForScope(type, id)` | List memberships for a scope |
+| `listForTenant(params?)` | List all tenant memberships |
+| `update(id, data)` | Update membership |
+| `revoke(id)` | Revoke membership |
+
+### ScopeModule
+
+| Method | Description |
+|--------|-------------|
+| `getAvailable()` | Get available scopes tree |
+| `switchScope(type, id)` | Switch active scope → new access token |
+
+### PermissionGroupsModule
+
+| Method | Description |
+|--------|-------------|
+| `list(tenantId)` | List permission groups |
+| `create(tenantId, name, desc?)` | Create group |
+| `update(tenantId, groupId, data)` | Update group |
+| `delete(tenantId, groupId)` | Delete group |
+| `getPermissions(tenantId, groupId)` | List group permissions |
+| `addPermission(tenantId, groupId, data)` | Add permission to group |
+| `removePermission(tenantId, groupId, permId)` | Remove permission |
+| `addInheritance(tenantId, groupId, fromId)` | Add group inheritance |
+| `removeInheritance(tenantId, groupId, fromId)` | Remove inheritance |
+| `getUserGroups(tenantId, userId)` | Get user's groups |
+| `assignUserToGroup(tenantId, userId, groupId)` | Assign user to group |
+| `removeUserFromGroup(tenantId, userId, groupId)` | Remove from group |
+| `getUserOverrides(tenantId, userId)` | Get user overrides |
+| `addUserOverride(tenantId, userId, data)` | Add override |
+| `removeUserOverride(tenantId, userId, overrideId)` | Remove override |
+| `getEffectivePermissions(tenantId, userId, params)` | Resolved permissions |
+| `checkPermission(tenantId, userId, appKey, nodeKey)` | Check single permission |
+
+## Step-by-Step
+
+### 1. Enable Scoped Auth
+
+```typescript
+await client.tenants.update(tenantId, { enableScopedAuth: true });
+```
+
+### 2. Grant Scoped Memberships
+
+```typescript
+const membership = await client.memberships.grant({
+  userId: "user-uuid",
+  roleName: "vendor_admin",
+  scopeType: "vendor",
+  scopeId: vendorId,
+});
+```
+
+Valid `scopeType`: `"tenant"`, `"vendor"`, `"source"`, `"client"`.
+
+### 3. Query Memberships
+
+```typescript
+const userResult = await client.memberships.listForUser(userId, tenantId);
+const scopeResult = await client.memberships.listForScope("vendor", vendorId);
+const tenantResult = await client.memberships.listForTenant({ scopeType: "source" });
+// Each result has a .memberships array
+```
+
+### 4. Switch Scope
+
+```typescript
+const tree = await client.scope.getAvailable();
+// tree.vendors[0].sources[0].clients[0]
+
+const { accessToken, scopeContext } = await client.scope.switchScope("vendor", vendorId);
+// Trusted runtime example: preserve the refresh token only in a server or secure mobile context
+client.setTokens({ accessToken, refreshToken: client.getRefreshToken()! });
+// JWT now includes scopeContext: { type, id, role, membershipId }
+```
+
+### 5. Set Up Permission Groups
+
+```typescript
+const group = await client.permissionGroups.create(tenantId, "Operators", "Field operators");
+
+await client.permissionGroups.addPermission(tenantId, group.id, {
+  appKey: "iqcapture",
+  nodeKey: "capture.operate",
+  effect: "allow",
+  weight: 10,
+});
+
+await client.permissionGroups.assignUserToGroup(tenantId, userId, group.id);
+```
+
+### 6. Group Inheritance
+
+```typescript
+await client.permissionGroups.addInheritance(tenantId, adminGroupId, baseGroupId);
+```
+
+### 7. User Overrides
+
+```typescript
+await client.permissionGroups.addUserOverride(tenantId, userId, {
+  appKey: "iqcapture",
+  nodeKey: "capture.delete",
+  effect: "deny",
+  weight: 100,
+});
+```
+
+### 8. Check Effective Permissions
+
+```typescript
+const effective = await client.permissionGroups.getEffectivePermissions(
+  tenantId, userId, { appKey: "iqcapture" },
+);
+
+const check = await client.permissionGroups.checkPermission(
+  tenantId, userId, "iqcapture", "capture.operate",
+);
+// { allowed: true, appKey: "iqcapture", nodeKey: "capture.operate" }
+```
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `NOT_FOUND` | Scope entity or user not found | Check IDs |
+| `ALREADY_EXISTS` | Membership or group already exists | Check existing resources |
+| `INSUFFICIENT_PERMISSIONS` | Caller lacks admin role | Requires `tenant_admin`+ |
+| `VALIDATION_ERROR` | Invalid scope type or data | Check request format |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.memberships.grant({
+    userId, roleName: "vendor_admin", scopeType: "vendor", scopeId: vendorId,
+  });
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.ALREADY_EXISTS) {
+    console.log("Membership already exists");
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  accessToken: adminToken,
+  refreshToken: adminRefreshToken,
+});
+
+async function setupScopedAuth(tenantId: string, vendorId: string) {
+  await client.tenants.update(tenantId, { enableScopedAuth: true });
+
+  await client.memberships.grant({
+    userId: operatorUserId,
+    roleName: "user",
+    scopeType: "vendor",
+    scopeId: vendorId,
+  });
+
+  const group = await client.permissionGroups.create(tenantId, "Capture Operators");
+
+  await client.permissionGroups.addPermission(tenantId, group.id, {
+    appKey: "iqcapture",
+    nodeKey: "capture.operate",
+    effect: "allow",
+  });
+
+  await client.permissionGroups.assignUserToGroup(tenantId, operatorUserId, group.id);
+
+  const check = await client.permissionGroups.checkPermission(
+    tenantId, operatorUserId, "iqcapture", "capture.operate",
+  );
+  console.log("Can operate:", check.allowed);
+
+  const tree = await client.scope.getAvailable();
+  console.log("Available scopes:", JSON.stringify(tree, null, 2));
+}
+```
+
+Note: Scope routes are mounted under `/api/v1/auth`, not `/api/v1/scope`. See [DECISION-014](../../DECISIONS.md).
+
+## API Reference
+
+### MembershipsModule
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `grant(data)` | POST | `/api/v1/memberships` |
+| `listForUser(userId, tenantId)` | GET | `/api/v1/users/:userId/memberships?tenantId=...` |
+| `listForScope(type, id)` | GET | `/api/v1/memberships/scope/:type/:id` |
+| `listForTenant(params?)` | GET | `/api/v1/memberships/tenant` |
+| `update(id, data)` | PATCH | `/api/v1/memberships/:id` |
+| `revoke(id)` | DELETE | `/api/v1/memberships/:id` |
+
+### ScopeModule
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `getAvailable()` | GET | `/api/v1/auth/available-scopes` |
+| `switchScope(type, id)` | POST | `/api/v1/auth/switch-scope` |
+
+### PermissionGroupsModule
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `list(tenantId)` | GET | `/api/v1/tenants/:tenantId/permission-groups` |
+| `create(tenantId, name, desc?)` | POST | `/api/v1/tenants/:tenantId/permission-groups` |
+| `getPermissions(tenantId, groupId)` | GET | `.../:groupId/permissions` |
+| `addPermission(tenantId, groupId, data)` | POST | `.../:groupId/permissions` |
+| `removePermission(tenantId, groupId, permId)` | DELETE | `.../:groupId/permissions/:permId` |
+| `addInheritance(tenantId, groupId, fromId)` | POST | `.../:groupId/inherit` |
+| `assignUserToGroup(tenantId, userId, groupId)` | POST | `.../users/:userId/groups` |
+| `getEffectivePermissions(tenantId, userId, params)` | GET | `.../users/:userId/permissions/effective` |
+| `checkPermission(tenantId, userId, appKey, nodeKey)` | POST | `.../users/:userId/permissions/check` |

package/docs/guides/server-platform-integration.md

@@ -0,0 +1,52 @@
+# Server Platform Integration
+
+This guide is for trusted backend platforms that accept IQAuth bearer tokens or need to call IQAuth directly.
+
+## Recommended Pattern
+
+Use the server entry point and the provided middleware:
+
+```ts
+import express from "express";
+import { createServerClient } from "@iqauth/sdk/server";
+
+const client = createServerClient({
+  baseUrl: process.env.IQAUTH_BASE_URL!,
+});
+
+const app = express();
+
+app.use("/api", client.middleware());
+```
+
+## Why this is the default
+
+- it keeps token verification centralized
+- it prevents each app from re-implementing JWT verification and drift-prone auth checks
+- it gives the platform one canonical middleware contract
+
+## Required Practices
+
+- use `client.middleware()` unless your framework cannot support Express-style middleware
+- enforce role and entitlement checks on the server, not only in the UI
+- avoid shared multi-user token state
+- keep service tokens and user tokens separate
+
+## Typical Integration Shapes
+
+### Resource server
+
+- accepts incoming bearer tokens
+- uses middleware to verify and attach auth context
+- authorizes routes from verified claims
+
+### Backend calling IQAuth APIs directly
+
+- uses request-scoped or service-scoped tokens
+- calls `client.users`, `client.sessions`, `client.permissions`, etc.
+
+## Anti-Patterns
+
+- re-implementing token verification without a concrete reason
+- trusting browser role checks without server enforcement
+- sharing one mutable token cache across unrelated user sessions

package/docs/guides/service-automation-integration.md

@@ -0,0 +1,36 @@
+# Service Automation Integration
+
+This guide is for workers, batch jobs, schedulers, and service-to-service integrations.
+
+## Recommended Pattern
+
+Prefer API keys.
+
+```ts
+import { createServiceClient } from "@iqauth/sdk/service";
+
+const client = createServiceClient({
+  baseUrl: process.env.IQAUTH_BASE_URL!,
+  apiKey: process.env.IQAUTH_API_KEY!,
+});
+```
+
+## Why API keys are preferred
+
+- no interactive user lifecycle
+- simpler rotation model
+- lower risk than pretending a headless service is a browser or mobile app
+
+## Required Practices
+
+- scope service credentials as narrowly as possible
+- document rotation and revocation ownership
+- do not use interactive login flows unless a product requirement explicitly demands it
+
+## When not to use this model
+
+Do not use service credentials for:
+
+- first-party browser apps
+- end-user mobile login flows
+- backend routes that should be enforcing user identity

package/docs/guides/session-management.md

@@ -0,0 +1,97 @@
+# Session Management
+
+Session handling differs by environment.
+
+## Browser First-Party Apps
+
+Use backend-managed sessions.
+
+### Recommended pattern
+
+- backend stores access and refresh tokens in `httpOnly` cookies
+- frontend boots with `/auth/me`
+- frontend calls protected APIs with cookies
+- backend performs refresh
+
+### Browser responsibilities
+
+- display session state
+- handle session-expired UX
+- handle logout UX
+
+### Browser non-goals
+
+- do not persist refresh tokens in `localStorage`
+- do not make the browser responsible for durable token lifecycle
+
+## Server and Mobile Token-Owning Clients
+
+If your runtime can safely own tokens, the SDK session APIs are appropriate.
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `sessions` | `list()` | List active sessions |
+| `sessions` | `revoke(sessionId)` | Terminate one session |
+| `sessions` | `revokeAll()` | Terminate all sessions |
+| `auth` | `logout()` | End current session |
+| `auth` | `logoutAll()` | End all sessions for the current user |
+
+## List Sessions
+
+```typescript
+const sessions = await client.sessions.list();
+```
+
+## Identify Current Session
+
+In token-owning environments, the current session ID is available from JWT claims:
+
+```typescript
+const claims = client.tokens.getClaims(client.getAccessToken()!);
+const currentSessionId = claims.sessionId;
+```
+
+## Revoke a Session
+
+```typescript
+await client.sessions.revoke(sessionId);
+```
+
+## Revoke All Sessions
+
+```typescript
+const { terminatedCount } = await client.sessions.revokeAll();
+```
+
+## Mobile Guidance
+
+If mobile owns tokens:
+
+- keep tokens in secure storage
+- clear secure storage on logout
+- treat `REFRESH_TOKEN_REUSED` or revocation as forced re-authentication
+
+## Browser Guidance
+
+If the browser is using a backend cookie session:
+
+- list/revoke session APIs can still back an "active sessions" UI
+- but logout and refresh should still be backend-driven
+- the browser should not need raw refresh-token access to manage session lifecycle
+
+## Error Handling
+
+| Error Code | Meaning |
+|--------|--------|
+| `SESSION_INVALID` | Session not found |
+| `SESSION_EXPIRED` | Session already expired |
+| `TOKEN_INVALID` | Caller not authenticated |
+| `TOKEN_REVOKED` | Session or token was revoked |
+
+## Summary
+
+- browser: session cookies, backend ownership
+- mobile: secure storage
+- server: direct tokens allowed

package/docs/guides/tenant-management.md

@@ -0,0 +1,216 @@
+# Tenant Management
+
+## Purpose
+
+Create, read, update, and delete tenants. Manage tenant users, password policies, MFA policies, and public branding. Handle tenant promotion to vendor status.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- `tenant_admin` role for tenant user management and policies
+- `platform_admin` role for tenant creation/deletion and promotion
+
+## Environment Note
+
+Tenant-management examples are intended for trusted administrative runtimes. Keep these operations behind your backend session boundary for first-party web apps.
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `tenants` | `get(tenantId)` | Get tenant info |
+| `tenants` | `getCurrent(tenantId)` | Get tenant info (alias) |
+| `tenants` | `list(params?)` | List tenants |
+| `tenants` | `create(data)` | Create tenant |
+| `tenants` | `update(tenantId, data)` | Update tenant |
+| `tenants` | `delete(tenantId)` | Delete tenant |
+| `tenants` | `promoteToVendor(tenantId, data)` | Promote to vendor |
+| `tenants` | `getUsers(tenantId)` | List tenant users |
+| `tenants` | `inviteUser(tenantId, data)` | Invite user to tenant |
+| `tenants` | `changeUserRole(tenantId, userId, role)` | Change user role |
+| `tenants` | `migrateUser(tenantId, userId, data)` | Migrate user between tenants |
+| `tenants` | `removeUser(tenantId, userId)` | Remove user from tenant |
+| `tenants` | `getPasswordPolicy(tenantId)` | Get password policy |
+| `tenants` | `updatePasswordPolicy(tenantId, data)` | Update password policy |
+| `tenants` | `getMfaPolicies(tenantId)` | Get MFA policies |
+| `tenants` | `updateMfaPolicy(tenantId, role, data)` | Update MFA policy for role |
+| `tenants` | `getPublicBranding(params?)` | Get public branding (no auth) |
+| `tenants` | `getPublicBrandingBySlug(slug)` | Get branding by vendor slug (no auth) |
+
+## Step-by-Step
+
+### 1. Get a Tenant
+
+```typescript
+const tenant = await client.tenants.get(tenantId);
+```
+
+Returns `TenantInfo`:
+
+```typescript
+interface TenantInfo {
+  id: string;
+  name: string;
+  slug: string;
+  plan?: string;
+  isActive?: boolean;
+  vendorId?: string | null;
+  vendorName?: string | null;
+  allowedDomains?: string[] | null;
+  autoProvisionRole?: string | null;
+  enableScopedAuth?: boolean;
+}
+```
+
+Note: `getCurrent(tenantId)` requires explicit `tenantId`. See [DECISION-007](../../DECISIONS.md).
+
+### 2. Create a Tenant
+
+```typescript
+const tenant = await client.tenants.create({
+  name: "Acme Corp",
+  slug: "acme-corp",
+  vendorId: "vendor-uuid",
+  allowedDomains: ["acme.com"],
+  autoProvisionRole: "user",
+  plan: "enterprise",
+});
+```
+
+### 3. Update a Tenant
+
+```typescript
+await client.tenants.update(tenantId, {
+  name: "Acme Corporation",
+  enableScopedAuth: true,
+});
+```
+
+### 4. Manage Users
+
+```typescript
+const users = await client.tenants.getUsers(tenantId);
+
+await client.tenants.inviteUser(tenantId, {
+  email: "new@example.com",
+  role: "user",
+  products: ["iqcapture"],
+});
+
+await client.tenants.changeUserRole(tenantId, userId, "tenant_admin");
+
+await client.tenants.migrateUser(tenantId, userId, {
+  targetTenantId: "new-tenant-uuid",
+  role: "user",
+});
+
+await client.tenants.removeUser(tenantId, userId);
+```
+
+### 5. Password and MFA Policies
+
+```typescript
+await client.tenants.updatePasswordPolicy(tenantId, {
+  minLength: 12,
+  maxAgeDays: 90,
+  reuseCount: 5,
+  maxFailedAttempts: 5,
+  lockoutDurationMinutes: 30,
+});
+
+await client.tenants.updateMfaPolicy(tenantId, "tenant_admin", {
+  required: true,
+  methods: ["totp", "sms"],
+});
+```
+
+### 6. Public Branding (No Auth)
+
+```typescript
+const vendorBranding = await client.tenants.getPublicBranding({ vendor: "acme" });
+const slugBranding = await client.tenants.getPublicBrandingBySlug("acme-disposal");
+```
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `NOT_FOUND` | Tenant does not exist | Check tenant ID |
+| `ALREADY_EXISTS` | Tenant slug exists | Use different slug |
+| `INSUFFICIENT_PERMISSIONS` | Caller lacks admin role | Requires `tenant_admin` or `platform_admin` |
+| `VALIDATION_ERROR` | Invalid request data | Check required fields |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.tenants.create({ name: "Test", slug: "test" });
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.ALREADY_EXISTS) {
+    console.log("Tenant slug already taken");
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  accessToken: platformAdminToken,
+  refreshToken: platformAdminRefreshToken,
+});
+
+async function setupNewTenant(name: string, slug: string, adminEmail: string) {
+  const tenant = await client.tenants.create({
+    name,
+    slug,
+    plan: "standard",
+    allowedDomains: [slug + ".com"],
+  });
+
+  await client.tenants.updatePasswordPolicy(tenant.id, {
+    minLength: 10,
+    maxAgeDays: 90,
+    maxFailedAttempts: 5,
+    lockoutDurationMinutes: 15,
+  });
+
+  await client.tenants.updateMfaPolicy(tenant.id, "tenant_admin", {
+    required: true,
+    methods: ["totp"],
+  });
+
+  await client.tenants.inviteUser(tenant.id, {
+    email: adminEmail,
+    role: "tenant_admin",
+  });
+
+  console.log("Tenant created:", tenant.id, tenant.slug);
+  return tenant;
+}
+```
+
+## API Reference
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `get(id)` / `getCurrent(id)` | GET | `/api/v1/tenants/:id` |
+| `list(params?)` | GET | `/api/v1/tenants` |
+| `create(data)` | POST | `/api/v1/tenants` |
+| `update(id, data)` | PATCH | `/api/v1/tenants/:id` |
+| `delete(id)` | DELETE | `/api/v1/tenants/:id` |
+| `promoteToVendor(id, data)` | POST | `/api/v1/tenants/:id/promote-to-vendor` |
+| `getUsers(id)` | GET | `/api/v1/tenants/:id/users` |
+| `inviteUser(id, data)` | POST | `/api/v1/tenants/:id/users/invite` |
+| `changeUserRole(id, userId, role)` | PATCH | `/api/v1/tenants/:id/users/:userId/role` |
+| `migrateUser(id, userId, data)` | POST | `/api/v1/tenants/:id/users/:userId/migrate` |
+| `removeUser(id, userId)` | DELETE | `/api/v1/tenants/:id/users/:userId` |
+| `getPasswordPolicy(id)` | GET | `/api/v1/tenants/:id/password-policy` |
+| `updatePasswordPolicy(id, data)` | PATCH | `/api/v1/tenants/:id/password-policy` |
+| `getMfaPolicies(id)` | GET | `/api/v1/tenants/:id/mfa-policies` |
+| `updateMfaPolicy(id, role, data)` | PATCH | `/api/v1/tenants/:id/mfa-policies/:role` |
+| `getPublicBranding(params?)` | GET | `/api/public/branding` |
+| `getPublicBrandingBySlug(slug)` | GET | `/api/public/branding/by-slug/:slug` |