@iqauth/sdk 2.0.0

package/docs/guides/middleware-reference.md

@@ -0,0 +1,205 @@
+# Middleware Reference
+
+## Purpose
+
+Protect Express routes by verifying Bearer tokens via RS256/JWKS. Supports optional auth, role checks, entitlement checks, and custom error handlers.
+
+This is the recommended integration path for platforms using the SDK in Express-style resource servers.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- Express.js application
+- IQAuthService base URL for JWKS verification
+
+## SDK Methods
+
+| Export | Description |
+|--------|-------------|
+| `iqAuthMiddleware(client, options?)` | Creates Express middleware |
+
+### Options
+
+```typescript
+interface ExpressMiddlewareOptions {
+  requireAuth?: boolean;             // Default: true
+  requiredRoles?: string[];          // OR logic
+  requiredEntitlements?: string[];   // AND logic
+  onUnauthorized?: (res, reason) => void;
+  onForbidden?: (res, reason) => void;
+}
+```
+
+## Step-by-Step
+
+### 1. Basic Protection
+
+```typescript
+import { createServerClient } from "@iqauth/sdk/server";
+
+const client = createServerClient({
+  baseUrl: "https://auth.dispositioniq.com",
+});
+
+app.use("/api", client.middleware());
+```
+
+### 2. Access Claims
+
+```typescript
+app.get("/api/me", (req, res) => {
+  res.json({
+    userId: req.auth!.sub,
+    email: req.auth!.email,
+    tenantId: req.auth!.tenantId,
+    roles: req.auth!.roles,
+  });
+});
+```
+
+Claims are attached to `req.auth` (not `req.user`). See [DECISION-006](../../DECISIONS.md).
+
+### 3. Optional Auth
+
+```typescript
+app.use(client.middleware({ requireAuth: false }));
+
+app.get("/api/resource", (req, res) => {
+  if (req.auth) {
+    // Authenticated
+  } else {
+    // Anonymous
+  }
+});
+```
+
+### 4. Role Checks (OR Logic)
+
+```typescript
+app.use("/admin", client.middleware({
+  requiredRoles: ["tenant_admin", "platform_admin"],
+}));
+// User needs ANY ONE of the listed roles
+```
+
+### 5. Entitlement Checks (AND Logic)
+
+```typescript
+app.use("/capture", client.middleware({
+  requiredEntitlements: ["iqcapture"],
+}));
+// User needs ALL listed entitlements
+```
+
+### 6. Custom Error Handlers
+
+```typescript
+app.use(client.middleware({
+  onUnauthorized: (res, reason) => {
+    (res as any).status(401).json({ error: "Login required", detail: reason });
+  },
+  onForbidden: (res, reason) => {
+    (res as any).status(403).json({ error: "Access denied", detail: reason });
+  },
+}));
+```
+
+### How It Works
+
+1. Extracts token from `Authorization: Bearer <token>` header
+2. Verifies signature using RS256 via JWKS (`/.well-known/jwks.json`)
+3. Validates issuer (`auth.dispositioniq.com`) and audience
+4. Checks expiration
+5. Attaches decoded claims to `req.auth`
+6. Checks `requiredRoles` (OR logic) if specified
+7. Checks `requiredEntitlements` (AND logic) if specified
+
+### TypeScript Augmentation
+
+```typescript
+declare global {
+  namespace Express {
+    interface Request {
+      auth?: JwtClaims;
+    }
+  }
+}
+```
+
+## Error Handling
+
+### Default 401 Response
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "TOKEN_INVALID",
+    "message": "Missing or invalid authorization header"
+  }
+}
+```
+
+### Default 403 Response
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "INSUFFICIENT_PERMISSIONS",
+    "message": "Missing required role. Required one of: tenant_admin, platform_admin"
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import express from "express";
+import { createServerClient } from "@iqauth/sdk/server";
+
+const app = express();
+const client = createServerClient({
+  baseUrl: "https://auth.dispositioniq.com",
+});
+
+// Public routes
+app.get("/health", (req, res) => res.json({ ok: true }));
+
+// Any authenticated user
+app.use("/api", client.middleware());
+
+app.get("/api/me", (req, res) => {
+  res.json({
+    userId: req.auth!.sub,
+    email: req.auth!.email,
+    tenantId: req.auth!.tenantId,
+    roles: req.auth!.roles,
+    entitlements: req.auth!.entitlements,
+    scopeContext: req.auth!.scopeContext,
+  });
+});
+
+// Admin only
+app.use("/api/admin", client.middleware({
+  requiredRoles: ["tenant_admin", "platform_admin"],
+}));
+
+app.get("/api/admin/users", async (req, res) => {
+  const users = await client.users.list({ tenantId: req.auth!.tenantId });
+  res.json(users);
+});
+
+// Product-gated with custom error
+app.use("/api/capture", client.middleware({
+  requiredEntitlements: ["iqcapture"],
+  onForbidden: (res, reason) => {
+    (res as any).status(403).json({
+      error: "IQCapture license required",
+      upgrade: "https://dispositioniq.com/pricing",
+    });
+  },
+}));
+
+app.listen(3000);
+```

package/docs/guides/mobile-native.md

@@ -0,0 +1,110 @@
+# Mobile / Native Guide
+
+Use this guide for iOS, Android, React Native, or Expo-style native applications.
+
+## Recommended Model
+
+Native apps are public clients.
+
+Use:
+
+- authorization code flow
+- PKCE
+- system browser authentication
+- secure OS-backed token storage
+
+Do not embed a client secret in the app.
+
+## Required Security Elements
+
+Every mobile login should generate:
+
+- `state`
+- `nonce`
+- PKCE code verifier
+- PKCE code challenge with `S256`
+
+Validate `state` on return before exchanging the authorization code.
+
+## Redirect Handling
+
+Supported callback patterns should be:
+
+- deep links
+- universal links
+- app links
+
+The redirect URI must be registered and validated by IQAuth.
+
+## Token Storage
+
+Allowed:
+
+- iOS Keychain
+- Android Keystore
+- secure-storage wrappers over those primitives
+
+Not acceptable:
+
+- plaintext async storage
+- browser-style `localStorage` assumptions
+- shipping long-lived credentials in bundled config
+
+## Session Lifecycle
+
+Typical mobile flow:
+
+1. open the authorization URL in the system browser
+2. user authenticates
+3. app receives authorization code
+4. exchange code for tokens
+5. persist tokens in secure storage
+6. attach access token to API requests
+7. refresh when needed
+8. clear secure storage on logout or revocation
+
+## SDK Fit
+
+The current SDK can be used in mobile only if:
+
+- login uses PKCE
+- tokens live in secure storage
+- the app treats refresh tokens as protected credentials
+
+Example 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);
+  },
+});
+```
+
+## Logout and Revocation
+
+On logout:
+
+- call the logout endpoint
+- clear secure storage
+- clear in-memory auth state
+
+On reuse detection or revocation:
+
+- force full re-authentication
+- do not silently continue with cached session assumptions
+
+## Summary
+
+Mobile should not reuse the browser cookie-session model.
+
+The correct model is:
+
+- PKCE login
+- secure storage
+- deep link callback
+- explicit logout and revocation handling

package/docs/guides/roles-and-permissions.md

@@ -0,0 +1,220 @@
+# Roles & Permissions
+
+## Purpose
+
+Check user roles and entitlements from JWT claims (client-side, no network), and manage role definitions and assignments on the server.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- For `permissions` module: authenticated user with tokens set on client
+- For `roles` module: `tenant_admin` or `platform_admin` role
+
+## Environment Note
+
+Direct token examples in this guide assume a trusted runtime, secure mobile storage, or server-side context.
+
+For first-party browser apps, consume roles and permissions through your backend session model.
+
+## SDK Methods
+
+### PermissionsModule (Client-Side, No Network)
+
+| Method | Description |
+|--------|-------------|
+| `getRoles()` | Get roles from JWT → `string[]` |
+| `getEntitlements()` | Get entitlements from JWT → `string[]` |
+| `hasRole(role)` | Check single role → `boolean` |
+| `hasEntitlement(ent)` | Check single entitlement → `boolean` |
+| `hasAllRoles(roles)` | All roles present (AND) → `boolean` |
+| `hasAnyRole(roles)` | Any role present (OR) → `boolean` |
+| `hasAllEntitlements(ents)` | All entitlements (AND) → `boolean` |
+| `hasAnyEntitlement(ents)` | Any entitlement (OR) → `boolean` |
+
+### RolesModule (Server-Side API)
+
+| Method | Description |
+|--------|-------------|
+| `list(tenantId)` | List roles → `Role[]` |
+| `create(tenantId, data)` | Create role → `Role` |
+| `update(tenantId, roleId, data)` | Update role → `Role` |
+| `delete(tenantId, roleId)` | Delete role |
+| `getUserRoles(tenantId, userId)` | Get user's roles → `Role[]` |
+| `assignRole(tenantId, userId, data)` | Assign role → `UserRoleAssignment` |
+| `removeRole(tenantId, userId, roleId)` | Remove role |
+
+## Step-by-Step
+
+### 1. Check Roles/Entitlements (Client-Side)
+
+```typescript
+client.permissions.getRoles();       // ["tenant_admin", "user"]
+client.permissions.getEntitlements(); // ["iqcapture", "iqreuse"]
+
+client.permissions.hasRole("tenant_admin");          // true
+client.permissions.hasEntitlement("iqcapture");      // true
+client.permissions.hasAllRoles(["tenant_admin", "vendor_admin"]); // false
+client.permissions.hasAnyRole(["tenant_admin", "vendor_admin"]);  // true
+client.permissions.hasAllEntitlements(["iqcapture", "iqreuse"]); // true
+```
+
+These read from the current access token's claims. If no token is set, arrays return `[]` and checks return `false`.
+
+### 2. System Roles
+
+| Role | Level | Scope |
+|------|-------|-------|
+| `platform_admin` | Global | All tenants, all operations |
+| `tenant_admin` | Tenant | Full control within a tenant |
+| `vendor_admin` | Vendor | Manage vendor and its sources/clients |
+| `user` | User | Standard user operations |
+
+### 3. Create Custom Roles
+
+```typescript
+const role = await client.roles.create(tenantId, {
+  name: "site_operator",
+  description: "Operates capture equipment at a site",
+  hierarchyLevel: 20,
+});
+```
+
+### 4. Assign Roles
+
+```typescript
+const assignment = await client.roles.assignRole(tenantId, userId, {
+  roleName: "site_operator",
+  scopeType: "source",  // optional V2 scoping
+  scopeId: sourceId,    // optional V2 scoping
+});
+```
+
+### 5. Remove Roles
+
+```typescript
+await client.roles.removeRole(tenantId, userId, roleId);
+```
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `INSUFFICIENT_PERMISSIONS` | Caller lacks admin role | Requires `tenant_admin` |
+| `NOT_FOUND` | Role or user not found | Check IDs |
+| `ALREADY_EXISTS` | Role name exists in tenant | Use different name |
+| `VALIDATION_ERROR` | Invalid role data | Check required fields |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.roles.create(tenantId, { name: "admin", hierarchyLevel: 50 });
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.ALREADY_EXISTS) {
+    console.log("Role already exists");
+  }
+}
+```
+
+### 6. Permission Groups (V2)
+
+Permission groups provide fine-grained access control beyond flat roles. See also [Scoped Authorization](./scoped-authorization.md).
+
+```typescript
+// Create a group
+const group = await client.permissionGroups.create(tenantId, "Operators", "Field operators");
+
+// Add permission to group
+await client.permissionGroups.addPermission(tenantId, group.id, {
+  appKey: "iqcapture",
+  nodeKey: "capture.operate",
+  effect: "allow",
+  weight: 10,
+});
+
+// Assign user to group
+await client.permissionGroups.assignUserToGroup(tenantId, userId, group.id);
+
+// Check effective permissions
+const effective = await client.permissionGroups.getEffectivePermissions(
+  tenantId, userId, { appKey: "iqcapture" },
+);
+console.log("Effective permissions:", effective);
+
+// Check a single permission
+const check = await client.permissionGroups.checkPermission(
+  tenantId, userId, "iqcapture", "capture.operate",
+);
+console.log("Can operate:", check.allowed);
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient, IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  accessToken: adminToken,
+  refreshToken: adminRefreshToken,
+});
+
+async function setupRolesAndPermissions(tenantId: string, operatorUserId: string) {
+  // V1: Create and assign flat roles
+  const operator = await client.roles.create(tenantId, {
+    name: "site_operator",
+    description: "Operates equipment at a facility",
+    hierarchyLevel: 20,
+  });
+
+  await client.roles.assignRole(tenantId, operatorUserId, { roleName: "site_operator" });
+  const userRoles = await client.roles.getUserRoles(tenantId, operatorUserId);
+  console.log("Operator roles:", userRoles.map(r => r.name));
+
+  // V2: Fine-grained permission groups
+  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); // true
+
+  // Client-side checks (reads from JWT, no network)
+  const isAdmin = client.permissions.hasAnyRole(["tenant_admin", "platform_admin"]);
+  const hasCapture = client.permissions.hasEntitlement("iqcapture");
+  console.log("Is admin:", isAdmin, "Has capture:", hasCapture);
+}
+```
+
+## API Reference
+
+### RolesModule
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `list(tenantId)` | GET | `/api/v1/tenants/:tenantId/roles` |
+| `create(tenantId, data)` | POST | `/api/v1/tenants/:tenantId/roles` |
+| `update(tenantId, roleId, data)` | PATCH | `/api/v1/tenants/:tenantId/roles/:roleId` |
+| `delete(tenantId, roleId)` | DELETE | `/api/v1/tenants/:tenantId/roles/:roleId` |
+| `getUserRoles(tenantId, userId)` | GET | `/api/v1/tenants/:tenantId/users/:userId/roles` |
+| `assignRole(tenantId, userId, data)` | POST | `/api/v1/tenants/:tenantId/users/:userId/roles` |
+| `removeRole(tenantId, userId, roleId)` | DELETE | `/api/v1/tenants/:tenantId/users/:userId/roles/:roleId` |
+
+### PermissionGroupsModule
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `list(tenantId)` | GET | `/api/v1/tenants/:tenantId/permission-groups` |
+| `create(tenantId, name, desc?)` | POST | `/api/v1/tenants/:tenantId/permission-groups` |
+| `addPermission(tenantId, groupId, data)` | POST | `.../:groupId/permissions` |
+| `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` |