workos 0.9.0 → 0.10.1

package/skills/workos-management/SKILL.md

@@ -1,250 +0,0 @@
----
-name: workos-management
-description: Manage WorkOS resources (orgs, users, roles, SSO, directories, webhooks, audit logs) via CLI. Use when configuring RBAC, onboarding orgs/users, debugging SSO/DSync, or managing WorkOS settings.
----
-
-# WorkOS Management Commands
-
-Use these commands to manage WorkOS resources directly from the terminal. The CLI must be authenticated via `workos auth login` or `WORKOS_API_KEY` env var.
-
-All commands support `--json` for structured output. Use `--json` when you need to parse output (e.g., extract an ID).
-
-## Quick Reference
-
-| Task                   | Command                                                                      |
-| ---------------------- | ---------------------------------------------------------------------------- |
-| List organizations     | `workos organization list`                                                   |
-| Create organization    | `workos organization create "Acme Corp" acme.com:verified`                   |
-| List users             | `workos user list --email=alice@acme.com`                                    |
-| Create permission      | `workos permission create --slug=read-users --name="Read Users"`             |
-| Create role            | `workos role create --slug=admin --name=Admin`                               |
-| Assign perms to role   | `workos role set-permissions admin --permissions=read-users,write-users`     |
-| Create org-scoped role | `workos role create --slug=admin --name=Admin --org=org_xxx`                 |
-| Add user to org        | `workos membership create --org=org_xxx --user=user_xxx`                     |
-| Send invitation        | `workos invitation send --email=alice@acme.com --org=org_xxx`                |
-| Revoke session         | `workos session revoke <sessionId>`                                          |
-| Add redirect URI       | `workos config redirect add http://localhost:3000/callback`                  |
-| Add CORS origin        | `workos config cors add http://localhost:3000`                               |
-| Set homepage URL       | `workos config homepage-url set http://localhost:3000`                       |
-| Create webhook         | `workos webhook create --url=https://example.com/hook --events=user.created` |
-| List SSO connections   | `workos connection list --org=org_xxx`                                       |
-| List directories       | `workos directory list`                                                      |
-| Toggle feature flag    | `workos feature-flag enable my-flag`                                         |
-| Store a secret         | `workos vault create --name=api-secret --value=sk_xxx --org=org_xxx`         |
-| Generate portal link   | `workos portal generate-link --intent=sso --org=org_xxx`                     |
-| Seed environment       | `workos seed --file=workos-seed.yml`                                         |
-| Debug SSO              | `workos debug-sso conn_xxx`                                                  |
-| Debug directory sync   | `workos debug-sync directory_xxx`                                            |
-| Set up an org          | `workos setup-org "Acme Corp" --domain=acme.com --roles=admin,viewer`        |
-| Onboard a user         | `workos onboard-user alice@acme.com --org=org_xxx --role=admin`              |
-
-## Workflows
-
-### Setting up RBAC
-
-When you see permission checks in the codebase (e.g., `hasPermission('read-users')`), create the matching WorkOS resources:
-
-```bash
-workos permission create --slug=read-users --name="Read Users"
-workos permission create --slug=write-users --name="Write Users"
-workos role create --slug=admin --name=Admin
-workos role set-permissions admin --permissions=read-users,write-users
-workos role create --slug=viewer --name=Viewer
-workos role set-permissions viewer --permissions=read-users
-```
-
-For organization-scoped roles, add `--org=org_xxx` to role commands.
-
-### Organization Onboarding
-
-One-shot setup with the compound command:
-
-```bash
-workos setup-org "Acme Corp" --domain=acme.com --roles=admin,viewer
-```
-
-Or step by step:
-
-```bash
-ORG_ID=$(workos organization create "Acme Corp" --json | jq -r '.data.id')
-workos org-domain create acme.com --org=$ORG_ID
-workos role create --slug=admin --name=Admin --org=$ORG_ID
-workos portal generate-link --intent=sso --org=$ORG_ID
-```
-
-### User Onboarding
-
-```bash
-workos onboard-user alice@acme.com --org=org_xxx --role=admin
-```
-
-Or step by step:
-
-```bash
-workos invitation send --email=alice@acme.com --org=org_xxx --role=admin
-workos membership create --org=org_xxx --user=user_xxx --role=admin
-```
-
-### Local Development Setup
-
-Configure WorkOS for local development:
-
-```bash
-workos config redirect add http://localhost:3000/callback
-workos config cors add http://localhost:3000
-workos config homepage-url set http://localhost:3000
-```
-
-### Environment Seeding
-
-Create a `workos-seed.yml` file in your repo:
-
-```yaml
-permissions:
-  - name: 'Read Users'
-    slug: 'read-users'
-  - name: 'Write Users'
-    slug: 'write-users'
-
-roles:
-  - name: 'Admin'
-    slug: 'admin'
-    permissions: ['read-users', 'write-users']
-  - name: 'Viewer'
-    slug: 'viewer'
-    permissions: ['read-users']
-
-organizations:
-  - name: 'Test Org'
-    domains: ['test.com']
-
-config:
-  redirect_uris: ['http://localhost:3000/callback']
-  cors_origins: ['http://localhost:3000']
-  homepage_url: 'http://localhost:3000'
-```
-
-Then run:
-
-```bash
-workos seed --file=workos-seed.yml   # Create resources
-workos seed --clean                  # Tear down seeded resources
-```
-
-### Debugging SSO
-
-```bash
-workos debug-sso conn_xxx
-```
-
-Shows: connection type/state, organization binding, recent auth events, and common issues (inactive connection, org mismatch).
-
-### Debugging Directory Sync
-
-```bash
-workos debug-sync directory_xxx
-```
-
-Shows: directory type/state, user/group counts, recent sync events, and stall detection.
-
-### Webhook Management
-
-```bash
-workos webhook list
-workos webhook create --url=https://example.com/hook --events=user.created,dsync.user.created
-workos webhook delete we_xxx
-```
-
-### Audit Logs
-
-```bash
-workos audit-log create-event --org=org_xxx --action=user.login --actor-type=user --actor-id=user_xxx
-workos audit-log list-actions
-workos audit-log get-schema user.login
-workos audit-log export --org=org_xxx --range-start=2024-01-01 --range-end=2024-02-01
-workos audit-log get-retention --org=org_xxx
-```
-
-## Using --json for Structured Output
-
-All commands support `--json` for machine-readable output. Use this when you need to extract values:
-
-```bash
-# Get an organization ID
-workos organization list --json | jq '.data[0].id'
-
-# Get a connection's state
-workos connection get conn_xxx --json | jq '.state'
-
-# List all role slugs
-workos role list --json | jq '.data[].slug'
-
-# Chain commands: create org then add domain
-ORG_ID=$(workos organization create "Acme" --json | jq -r '.data.id')
-workos org-domain create acme.com --org=$ORG_ID
-```
-
-JSON output format:
-
-- **List commands**: `{ "data": [...], "listMetadata": { "before": null, "after": "cursor" } }`
-- **Get commands**: Raw object (no wrapper)
-- **Create/Update/Delete**: `{ "status": "ok", "message": "...", "data": {...} }`
-- **Errors**: `{ "error": { "code": "...", "message": "..." } }` on stderr
-
-## Command Reference
-
-### Resource Commands
-
-| Command               | Subcommands                                                                                           |
-| --------------------- | ----------------------------------------------------------------------------------------------------- |
-| `workos organization` | `list`, `get`, `create`, `update`, `delete`                                                           |
-| `workos user`         | `list`, `get`, `update`, `delete`                                                                     |
-| `workos role`         | `list`, `get`, `create`, `update`, `delete`, `set-permissions`, `add-permission`, `remove-permission` |
-| `workos permission`   | `list`, `get`, `create`, `update`, `delete`                                                           |
-| `workos membership`   | `list`, `get`, `create`, `update`, `delete`, `deactivate`, `reactivate`                               |
-| `workos invitation`   | `list`, `get`, `send`, `revoke`, `resend`                                                             |
-| `workos session`      | `list`, `revoke`                                                                                      |
-| `workos connection`   | `list`, `get`, `delete`                                                                               |
-| `workos directory`    | `list`, `get`, `delete`, `list-users`, `list-groups`                                                  |
-| `workos event`        | `list` (requires `--events` flag)                                                                     |
-| `workos audit-log`    | `create-event`, `export`, `list-actions`, `get-schema`, `create-schema`, `get-retention`              |
-| `workos feature-flag` | `list`, `get`, `enable`, `disable`, `add-target`, `remove-target`                                     |
-| `workos webhook`      | `list`, `create`, `delete`                                                                            |
-| `workos config`       | `redirect add`, `cors add`, `homepage-url set`                                                        |
-| `workos portal`       | `generate-link`                                                                                       |
-| `workos vault`        | `list`, `get`, `get-by-name`, `create`, `update`, `delete`, `describe`, `list-versions`               |
-| `workos api-key`      | `list`, `create`, `validate`, `delete`                                                                |
-| `workos org-domain`   | `get`, `create`, `verify`, `delete`                                                                   |
-
-### Workflow Commands
-
-| Command                       | Purpose                                     |
-| ----------------------------- | ------------------------------------------- |
-| `workos seed --file=<yaml>`   | Declarative resource provisioning from YAML |
-| `workos seed --clean`         | Tear down seeded resources                  |
-| `workos setup-org <name>`     | One-shot org onboarding                     |
-| `workos onboard-user <email>` | Send invitation + optional wait             |
-| `workos debug-sso <connId>`   | SSO connection diagnostics                  |
-| `workos debug-sync <dirId>`   | Directory sync diagnostics                  |
-
-### Common Flags
-
-| Flag                                        | Purpose                  | Scope                                               |
-| ------------------------------------------- | ------------------------ | --------------------------------------------------- |
-| `--json`                                    | Structured JSON output   | All commands                                        |
-| `--api-key`                                 | Override API key         | Resource commands                                   |
-| `--org`                                     | Organization scope       | role, membership, invitation, api-key, feature-flag |
-| `--force`                                   | Skip confirmation prompt | connection delete, directory delete                 |
-| `--limit`, `--before`, `--after`, `--order` | Pagination               | All list commands                                   |
-
-## Dashboard-Only Operations
-
-These CANNOT be done from the CLI — tell the user to visit the WorkOS Dashboard:
-
-- **Enable/disable auth methods** — Dashboard > Authentication
-- **Configure session lifetime** — Dashboard > Authentication > Sessions
-- **Set up social login providers** (Google, GitHub, etc.) — Dashboard > Authentication > Social
-- **Create feature flags** — Dashboard > Feature Flags (toggle/target operations work via CLI)
-- **Configure branding** (logos, colors) — Dashboard > Branding
-- **Set up email templates** — Dashboard > Email
-- **Manage billing/plan** — Dashboard > Settings > Billing

package/skills/workos-node/SKILL.md

@@ -1,197 +0,0 @@
----
-name: workos-node
-description: Integrate WorkOS AuthKit with Node.js backend applications. Adapts to Express, Fastify, Hono, Koa, or vanilla Node.js http. Server-side authentication with redirect-based OAuth flow.
----
-
-# WorkOS AuthKit for Node.js
-
-## Step 1: Fetch SDK Documentation (BLOCKING)
-
-**STOP - Do not proceed until complete.**
-
-WebFetch: `https://raw.githubusercontent.com/workos/workos-node/main/README.md`
-
-Also fetch the AuthKit quickstart for reference:
-WebFetch: `https://workos.com/docs/authkit/vanilla/nodejs`
-
-README is the source of truth for all SDK patterns. **README overrides this skill if conflict.**
-
-## Step 2: Detect Framework & Project Structure
-
-```
-package.json has 'express'?              → Express
-package.json has 'fastify'?              → Fastify
-package.json has 'hono'?                 → Hono
-package.json has 'koa'?                  → Koa
-None of the above?                       → Vanilla Node.js http (use Express quickstart pattern)
-
-tsconfig.json exists?                    → TypeScript (.ts files)
-"type": "module" in package.json?        → ESM (import/export)
-else                                     → CJS (require/module.exports)
-```
-
-Detect entry point: `src/index.ts`, `src/app.ts`, `app.js`, `server.js`, `index.js`
-
-Detect package manager: `pnpm-lock.yaml` → `yarn.lock` → `bun.lockb` → npm
-
-**Adapt all subsequent steps to the detected framework and module system.**
-
-## Step 2b: Partial Install Recovery
-
-Before creating new files, check if a previous AuthKit attempt exists:
-
-1. Check if `@workos-inc/node` is already in `package.json`
-2. Check for incomplete auth files — routes/handlers that import `@workos-inc/node` but are non-functional (TODO comments, 501 responses, empty handlers)
-3. If partial install detected:
-   - Do NOT reinstall the SDK (it's already there)
-   - Read existing auth files to understand what's done vs missing
-   - Complete the integration by filling gaps rather than starting fresh
-   - Preserve any working code — only fix what's broken
-   - Check for a missing `/callback` route (most common gap)
-
-## Step 2c: Existing Auth System Detection
-
-Check for existing authentication before integrating:
-
-```
-package.json has 'passport'?                → Passport.js auth
-package.json has 'express-openid-connect'?  → Auth0 / OIDC
-package.json has 'express-session'?         → Session-based auth may exist
-*.js/*.ts files have 'jsonwebtoken'?        → JWT-based auth
-```
-
-If existing auth detected:
-
-- Do NOT remove or disable it
-- Add WorkOS AuthKit alongside the existing system
-- If `express-session` is already configured, reuse it for WorkOS session storage (don't create a second session middleware)
-- Create separate route paths for WorkOS auth (e.g., `/auth/workos/login` if `/login` is taken)
-- Ensure existing auth routes continue to work unchanged
-- Document in code comments how to migrate fully to WorkOS later
-
-## Step 3: Install SDK
-
-```
-pnpm-lock.yaml → pnpm add @workos-inc/node dotenv cookie-parser
-yarn.lock      → yarn add @workos-inc/node dotenv cookie-parser
-bun.lockb      → bun add @workos-inc/node dotenv cookie-parser
-else           → npm install @workos-inc/node dotenv cookie-parser
-```
-
-For TypeScript, also install types: `pnpm add -D @types/cookie-parser`
-
-**Verify:** `@workos-inc/node` in package.json dependencies
-
-## Step 4: Initialize WorkOS Client
-
-Adapt to detected module system (ESM vs CJS):
-
-**ESM/TypeScript:**
-
-```typescript
-import { WorkOS } from '@workos-inc/node';
-const workos = new WorkOS(process.env.WORKOS_API_KEY, {
-  clientId: process.env.WORKOS_CLIENT_ID,
-});
-```
-
-**CJS:**
-
-```javascript
-const { WorkOS } = require('@workos-inc/node');
-const workos = new WorkOS(process.env.WORKOS_API_KEY, {
-  clientId: process.env.WORKOS_CLIENT_ID,
-});
-```
-
-## Step 5: Integrate Authentication
-
-### If Express
-
-Follow the quickstart pattern:
-
-1. **`/login` route** — call `workos.userManagement.getAuthorizationUrl({ provider: 'authkit', redirectUri: ..., clientId: ... })`, redirect
-2. **`/callback` route** — call `workos.userManagement.authenticateWithCode({ code, clientId })`, store session via sealed session or express-session
-3. **`/logout` route** — clear session cookie, redirect
-4. **Cookie middleware** — `app.use(cookieParser())`
-5. **Session-aware home route** — read session, display user info
-
-**Session handling options (pick one):**
-
-- **Sealed sessions** (recommended, from quickstart): use `sealSession: true` in authenticateWithCode, store sealed cookie, use `loadSealedSession` for verification
-- **express-session**: install `express-session`, configure middleware before routes, store user in `req.session`
-
-### If Fastify
-
-1. Register `@fastify/cookie` plugin
-2. Create `/login`, `/callback`, `/logout` routes using Fastify route syntax
-3. Use `reply.redirect()` for redirects
-4. Store session in signed cookie
-
-### If Hono
-
-1. Create `/login`, `/callback`, `/logout` routes using Hono router
-2. Use `c.redirect()` for redirects
-3. Use Hono's cookie helpers for session
-
-### If Koa
-
-1. Install `koa-router` if not present
-2. Create auth routes on router
-3. Use `ctx.redirect()` for redirects
-4. Use `koa-session` for session management
-
-### If Vanilla Node.js (no framework detected)
-
-Install Express and follow the Express pattern above. This matches the official quickstart.
-
-## Step 6: Environment Setup
-
-Create `.env` if it doesn't exist. Do NOT overwrite existing values:
-
-```
-WORKOS_API_KEY=sk_...
-WORKOS_CLIENT_ID=client_...
-WORKOS_REDIRECT_URI=http://localhost:3000/callback
-WORKOS_COOKIE_PASSWORD=<generate with openssl rand -base64 32>
-```
-
-Ensure `.env` is in `.gitignore`.
-
-## Step 7: Verification
-
-**TypeScript:** `npx tsc --noEmit`
-**JavaScript:** `node --check <entry-file>`
-
-### Checklist
-
-- [ ] SDK installed (`@workos-inc/node` in package.json)
-- [ ] WorkOS client initialized
-- [ ] Login route redirects to AuthKit
-- [ ] Callback route exchanges code for user
-- [ ] Logout route clears session
-- [ ] `.env` has required variables
-- [ ] Build/syntax check passes
-
-## Error Recovery
-
-### Module not found: @workos-inc/node
-
-Re-run install for detected package manager.
-
-### Session not persisting
-
-If using express-session: ensure middleware registered BEFORE routes.
-If using sealed sessions: ensure cookie is being set with correct options (httpOnly, secure in prod, sameSite: 'lax').
-
-### Callback returns 404
-
-Route path must match WORKOS_REDIRECT_URI exactly.
-
-### ESM/CJS mismatch
-
-Check `"type"` field in package.json — `"module"` = ESM (import/export), absent = CJS (require).
-
-### TypeScript errors
-
-Install missing types: `@types/express`, `@types/cookie-parser`, `@types/express-session`.

package/skills/workos-php/SKILL.md

@@ -1,160 +0,0 @@
----
-name: workos-php
-description: Integrate WorkOS AuthKit with generic PHP applications. Uses the workos-php SDK directly with standalone auth endpoint files.
----
-
-# WorkOS AuthKit for PHP
-
-## Step 1: Fetch SDK Documentation (BLOCKING)
-
-**STOP. Do not proceed until complete.**
-
-WebFetch: `https://raw.githubusercontent.com/workos/workos-php/main/README.md`
-
-The README is the source of truth. If this skill conflicts with README, follow README.
-
-## Step 2: Pre-Flight Validation
-
-### Project Structure
-
-- Confirm `composer.json` exists at project root
-- If `composer.json` doesn't exist, create a minimal one with `composer init --no-interaction`
-
-### Environment Variables
-
-Check for `.env` file with:
-
-- `WORKOS_API_KEY` - starts with `sk_`
-- `WORKOS_CLIENT_ID` - starts with `client_`
-- `WORKOS_REDIRECT_URI` - valid callback URL (e.g., `http://localhost:8000/callback.php`)
-
-If `.env` doesn't exist, create it with the required variables.
-
-## Step 2b: Partial Install Recovery
-
-Before creating new files, check if a previous AuthKit attempt exists:
-
-1. Check if `workos/workos-php` is already in `composer.json`
-2. Check for incomplete auth files — `login.php` or `callback.php` that import WorkOS but are non-functional (TODO comments, 501 responses, empty handlers)
-3. If partial install detected:
-   - Do NOT reinstall the SDK (it's already there)
-   - Read existing auth files to understand what's done vs missing
-   - Complete the integration by filling gaps rather than starting fresh
-   - Preserve any working code — only fix what's broken
-   - Check for a missing `callback.php` (most common gap)
-
-## Step 2c: Existing Auth System Detection
-
-Check for existing authentication before integrating:
-
-```
-*.php files have 'session_start()' + '$_SESSION'?  → Native PHP session auth
-*.php files have 'password_verify'?                 → Password-based auth
-*.php files have form POST to '/login'?             → Form-based auth
-composer.json has auth libraries?                   → Third-party auth
-```
-
-If existing auth detected:
-
-- Do NOT remove or disable it
-- Add WorkOS AuthKit alongside the existing system
-- If `session_start()` is already used, reuse the session for WorkOS (don't create a second session mechanism)
-- Create separate file paths for WorkOS auth (e.g., `workos-login.php` if `login.php` is taken)
-- Ensure existing auth routes continue to work unchanged
-- Document in code comments how to migrate fully to WorkOS later
-
-## Step 3: Install SDK
-
-```bash
-composer require workos/workos-php
-```
-
-**Verify:** Check `composer.json` contains `workos/workos-php` in require section.
-
-Also install a dotenv library if not present:
-
-```bash
-composer require vlucas/phpdotenv
-```
-
-## Step 4: Create Bootstrap File
-
-Create a bootstrap or config file (e.g., `config.php` or `bootstrap.php`) that:
-
-1. Requires Composer autoloader: `require_once __DIR__ . '/vendor/autoload.php';`
-2. Loads `.env` using phpdotenv
-3. Initializes the WorkOS SDK client with API key
-
-Use SDK initialization from README. Do NOT hardcode credentials.
-
-## Step 5: Create Auth Endpoint Files
-
-### `login.php`
-
-- Initialize WorkOS client (include bootstrap)
-- Generate authorization URL using SDK
-- Redirect user to WorkOS AuthKit
-
-### `callback.php`
-
-- Initialize WorkOS client (include bootstrap)
-- Exchange authorization code from `$_GET['code']` for user profile using SDK
-- Start session, store user data
-- Redirect to home/dashboard
-
-### `logout.php`
-
-- Destroy session
-- Redirect to home page
-
-Use SDK methods from README for all WorkOS API calls. Do NOT construct OAuth URLs manually.
-
-## Step 6: Create Home Page
-
-Create or update `index.php` to show:
-
-- Sign in link (`login.php`) when no session
-- User info and sign out link (`logout.php`) when session exists
-
-## Verification Checklist (ALL MUST PASS)
-
-```bash
-# 1. SDK installed
-composer show workos/workos-php
-
-# 2. Auth files exist
-ls login.php callback.php logout.php
-
-# 3. No syntax errors
-php -l login.php
-php -l callback.php
-php -l logout.php
-php -l index.php
-
-# 4. Autoloader exists
-ls vendor/autoload.php
-```
-
-## Error Recovery
-
-### "Class WorkOS\WorkOS not found"
-
-- Verify `composer require` completed successfully
-- Check `vendor/autoload.php` is required in bootstrap
-- Run `composer dump-autoload`
-
-### Session issues
-
-- Ensure `session_start()` is called before any session access
-- Check PHP session configuration (`session.save_path`)
-
-### Redirect URI mismatch
-
-- Compare callback file path to `WORKOS_REDIRECT_URI` in `.env`
-- URLs must match exactly (including trailing slash)
-
-### Environment variables not loading
-
-- Verify `.env` file exists in project root
-- Verify phpdotenv is installed and loaded in bootstrap
-- Check file permissions on `.env`