workos 0.11.2 → 0.12.0-beta.1

package/README.md

@@ -77,6 +77,10 @@ Resource Management:
   api-key                Manage per-org API keys
   org-domain             Manage organization domains
 
+Local Development:
+  emulate                Start a local WorkOS API emulator
+  dev                    Start emulator + your app in one command
+
 Workflows:
   seed                   Declarative resource provisioning from YAML
   setup-org              One-shot organization onboarding
@@ -192,6 +196,158 @@ Inspects a directory's sync state, user/group counts, recent events, and detects
 workos debug-sync directory_01ABC123
 ```
 
+### Local Development
+
+Test your WorkOS integration locally without hitting the live API. The emulator provides a full in-memory WorkOS API replacement with all major endpoints.
+
+#### `workos dev` — One command to start everything
+
+The fastest way to develop locally. Starts the emulator and your app together, auto-detecting your framework and injecting the right environment variables.
+
+```bash
+# Auto-detects framework (Next.js, Vite, Remix, SvelteKit, etc.) and dev command
+workos dev
+
+# Override the dev command
+workos dev -- npx vite --port 5173
+
+# Custom emulator port and seed data
+workos dev --port 8080 --seed workos-emulate.config.yaml
+```
+
+Your app receives these environment variables automatically:
+
+- `WORKOS_API_BASE_URL` — points to the local emulator (e.g. `http://localhost:4100`)
+- `WORKOS_API_KEY` — `sk_test_default`
+- `WORKOS_CLIENT_ID` — `client_emulate`
+
+#### `workos emulate` — Standalone emulator
+
+Run the emulator on its own for CI, test suites, or when you want manual control.
+
+```bash
+# Start with defaults (port 4100)
+workos emulate
+
+# CI-friendly: JSON output, custom port
+workos emulate --port 9100 --json
+# → {"url":"http://localhost:9100","port":9100,"apiKey":"sk_test_default","health":"http://localhost:9100/health"}
+
+# Pre-load seed data
+workos emulate --seed workos-emulate.config.yaml
+```
+
+The emulator supports `GET /health` for readiness polling and shuts down cleanly on Ctrl+C.
+
+#### Seed configuration
+
+Create a `workos-emulate.config.yaml` (auto-detected) or pass `--seed <path>`:
+
+```yaml
+users:
+  - email: alice@acme.com
+    first_name: Alice
+    password: test123
+    email_verified: true
+
+organizations:
+  - name: Acme Corp
+    domains:
+      - domain: acme.com
+        state: verified
+    memberships:
+      - user_id: <user_id>
+        role: admin
+
+connections:
+  - name: Acme SSO
+    organization: Acme Corp
+    connection_type: GenericSAML
+    domains: [acme.com]
+
+roles:
+  - slug: admin
+    name: Admin
+    permissions: [posts:read, posts:write]
+
+permissions:
+  - slug: posts:read
+    name: Read Posts
+  - slug: posts:write
+    name: Write Posts
+
+webhookEndpoints:
+  - url: http://localhost:3000/webhooks
+    events: [user.created, organization.updated]
+```
+
+#### Programmatic API
+
+Use the emulator directly in test suites without the CLI:
+
+```typescript
+import { createEmulator } from 'workos/emulate';
+
+const emulator = await createEmulator({
+  port: 0, // random available port
+  seed: {
+    users: [{ email: 'test@example.com', password: 'secret' }],
+  },
+});
+
+// Use emulator.url as your WORKOS_API_BASE_URL
+const res = await fetch(`${emulator.url}/user_management/users`, {
+  headers: { Authorization: 'Bearer sk_test_default' },
+});
+
+// Reset between tests (clears data, re-applies seed)
+emulator.reset();
+
+// Clean up
+await emulator.close();
+```
+
+#### Emulated endpoints
+
+The emulator covers the full WorkOS API surface (~84% of OpenAPI spec endpoints). Run `pnpm check:coverage <openapi-spec>` to see exact coverage.
+
+| Endpoint Group           | Routes                                                                                                                                                                 |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Organizations            | CRUD, external_id lookup, domain management                                                                                                                            |
+| Users                    | CRUD, email uniqueness, password management                                                                                                                            |
+| Organization memberships | CRUD, role assignment, deactivate/reactivate                                                                                                                           |
+| Organization domains     | CRUD, verification                                                                                                                                                     |
+| SSO connections          | CRUD, domain-based lookup                                                                                                                                              |
+| SSO flow                 | Authorize, token exchange, profile, JWKS, SSO logout                                                                                                                   |
+| AuthKit                  | OAuth authorize (login_hint, multi-user), authenticate (7 grant types incl. refresh_token, MFA TOTP, org selection, device code), PKCE, sealed sessions, impersonation |
+| Sessions                 | List, revoke, logout redirect, JWKS per client                                                                                                                         |
+| Email verification       | Send code, confirm                                                                                                                                                     |
+| Password reset           | Create token, confirm                                                                                                                                                  |
+| Magic auth               | Create code                                                                                                                                                            |
+| Auth factors             | TOTP enrollment, delete                                                                                                                                                |
+| MFA challenges           | Create challenge, verify code                                                                                                                                          |
+| Invitations              | CRUD, accept, revoke, resend, get by token                                                                                                                             |
+| Config                   | Redirect URIs, CORS origins, JWT template                                                                                                                              |
+| User features            | Authorized apps, connected accounts, data providers                                                                                                                    |
+| Widgets                  | Token generation                                                                                                                                                       |
+| Authorization (RBAC)     | Environment roles, org roles (priority ordering), permissions, role-permission management                                                                              |
+| Authorization (FGA)      | Resources CRUD, permission checks, role assignments                                                                                                                    |
+| Directory Sync           | List/get/delete directories, users, groups                                                                                                                             |
+| Audit Logs               | Actions, schemas, events, exports, org config/retention                                                                                                                |
+| Feature Flags            | List/get, enable/disable, targets, org/user evaluations                                                                                                                |
+| Connect                  | Applications CRUD, client secrets                                                                                                                                      |
+| Data Integrations        | OAuth authorize + token exchange                                                                                                                                       |
+| Radar                    | Attempts list/get, allow/deny lists                                                                                                                                    |
+| API Keys                 | Validate, delete, list by org                                                                                                                                          |
+| Portal                   | Generate admin portal links                                                                                                                                            |
+| Legacy MFA               | Enroll/get/delete factors, challenge/verify                                                                                                                            |
+| Webhook Endpoints        | CRUD with auto-generated secrets, secret masking                                                                                                                       |
+| Events                   | Paginated event stream with type filtering                                                                                                                             |
+| Event Bus                | Auto-emits events on entity CRUD via collection hooks, fire-and-forget webhook delivery with HMAC signatures                                                           |
+| Pipes                    | Connection CRUD, mock `getAccessToken()`                                                                                                                               |
+
+JWT tokens include `role` and `permissions` claims for org-scoped sessions. All list endpoints support cursor pagination (`before`, `after`, `limit`, `order`). Error responses match the WorkOS format (`{ message, code, errors }`).
+
 ### Environment Management
 
 ```bash
@@ -466,12 +622,13 @@ workos install --api-key sk_test_xxx --client-id client_xxx --no-commit 2>/dev/n
 
 ### Environment Variables
 
-| Variable                 | Effect                                                   |
-| ------------------------ | -------------------------------------------------------- |
-| `WORKOS_API_KEY`         | API key for management commands (bypasses stored config) |
-| `WORKOS_NO_PROMPT=1`     | Force non-interactive mode + JSON output                 |
-| `WORKOS_FORCE_TTY=1`     | Force interactive mode even when piped                   |
-| `WORKOS_TELEMETRY=false` | Disable telemetry                                        |
+| Variable                 | Effect                                                    |
+| ------------------------ | --------------------------------------------------------- |
+| `WORKOS_API_KEY`         | API key for management commands (bypasses stored config)  |
+| `WORKOS_API_BASE_URL`    | Override API base URL (set automatically by `workos dev`) |
+| `WORKOS_NO_PROMPT=1`     | Force non-interactive mode + JSON output                  |
+| `WORKOS_FORCE_TTY=1`     | Force interactive mode even when piped                    |
+| `WORKOS_TELEMETRY=false` | Disable telemetry                                         |
 
 ### Command Discovery
 

package/dist/bin.js

@@ -159,6 +159,7 @@ const installerOptions = {
 if (!isJsonMode())
     await checkForUpdates();
 yargs(rawArgs)
+    .parserConfiguration({ 'populate--': true })
     .env('WORKOS_INSTALLER')
     .option('json', {
     type: 'boolean',
@@ -171,7 +172,7 @@ yargs(rawArgs)
     // Excluded: auth/claim/install/dashboard handle their own credential flows;
     // skills/doctor/env/debug are utility commands where the warning is unnecessary.
     const command = String(argv._?.[0] ?? '');
-    if (['auth', 'skills', 'doctor', 'env', 'claim', 'install', 'debug', 'dashboard', ''].includes(command))
+    if (['auth', 'skills', 'doctor', 'env', 'claim', 'install', 'debug', 'dashboard', 'emulate', 'dev', ''].includes(command))
         return;
     await applyInsecureStorage(argv.insecureStorage);
     await maybeWarnUnclaimed();
@@ -1215,6 +1216,24 @@ yargs(rawArgs)
     await resolveInstallCredentials(argv.apiKey, argv.installDir, argv.skipAuth, ensureAuthenticated);
     const { handleInstall } = await import('./commands/install.js');
     await handleInstall(argv);
+})
+    .command('emulate', 'Start a local WorkOS API emulator', (yargs) => yargs.options({
+    port: { type: 'number', default: 4100, describe: 'Port to listen on' },
+    seed: { type: 'string', describe: 'Path to seed config file (YAML or JSON)' },
+}), async (argv) => {
+    const { runEmulate } = await import('./commands/emulate.js');
+    await runEmulate({ port: argv.port, seed: argv.seed, json: argv.json });
+})
+    .command('dev', 'Start emulator + your app in one command', (yargs) => yargs.options({
+    port: { type: 'number', default: 4100, describe: 'Emulator port' },
+    seed: { type: 'string', describe: 'Path to seed config file' },
+}), async (argv) => {
+    const { runDev } = await import('./commands/dev.js');
+    await runDev({
+        port: argv.port,
+        seed: argv.seed,
+        '--': argv['--'],
+    });
 })
     .command('debug', false, (yargs) => {
     yargs.options(insecureStorageOption);