workos 0.3.3 → 0.5.0

package/skills/workos-node/SKILL.md

@@ -0,0 +1,164 @@
+---
+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 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

@@ -0,0 +1,127 @@
+---
+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://github.com/workos/workos-php/blob/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 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`

package/skills/workos-php-laravel/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: workos-php-laravel
+description: Integrate WorkOS AuthKit with Laravel applications. Uses the dedicated workos-php-laravel SDK with service provider, middleware, and config publishing.
+---
+
+# WorkOS AuthKit for Laravel
+
+## Step 1: Fetch SDK Documentation (BLOCKING)
+
+**STOP. Do not proceed until complete.**
+
+WebFetch: `https://github.com/workos/workos-php-laravel/blob/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 `artisan` file exists at project root
+- Confirm `composer.json` contains `laravel/framework` dependency
+- Confirm `app/` and `routes/` directories exist
+
+### Environment Variables
+
+Check `.env` for:
+
+- `WORKOS_API_KEY` - starts with `sk_`
+- `WORKOS_CLIENT_ID` - starts with `client_`
+- `WORKOS_REDIRECT_URI` - valid callback URL (e.g., `http://localhost:8000/auth/callback`)
+
+If `.env` exists but is missing these variables, append them. If `.env` doesn't exist, copy `.env.example` and add them.
+
+## Step 3: Install SDK
+
+```bash
+composer require workos/workos-php-laravel
+```
+
+**Verify:** Check `composer.json` contains `workos/workos-php-laravel` in require section before continuing.
+
+## Step 4: Publish Configuration
+
+```bash
+php artisan vendor:publish --provider="WorkOS\Laravel\WorkOSServiceProvider"
+```
+
+This creates `config/workos.php`. Verify the file exists after publishing.
+
+If the artisan command fails, check README for the correct provider class name — it may differ.
+
+## Step 5: Configure Environment
+
+Ensure `.env` contains:
+
+```
+WORKOS_API_KEY=sk_...
+WORKOS_CLIENT_ID=client_...
+WORKOS_REDIRECT_URI=http://localhost:8000/auth/callback
+```
+
+Also ensure `config/workos.php` reads these env vars correctly. Check README for exact config structure.
+
+## Step 6: Create Auth Controller
+
+Create `app/Http/Controllers/AuthController.php` with methods for:
+
+- `login()` — Redirect to WorkOS AuthKit authorization URL
+- `callback()` — Handle OAuth callback, exchange code for user profile
+- `logout()` — Clear session and redirect
+
+Use SDK methods from README. Do NOT construct OAuth URLs manually.
+
+## Step 7: Add Routes
+
+Add to `routes/web.php`:
+
+```php
+use App\Http\Controllers\AuthController;
+
+Route::get('/login', [AuthController::class, 'login'])->name('login');
+Route::get('/auth/callback', [AuthController::class, 'callback']);
+Route::get('/logout', [AuthController::class, 'logout'])->name('logout');
+```
+
+Ensure the callback route path matches `WORKOS_REDIRECT_URI`.
+
+## Step 8: Add Middleware (if applicable)
+
+Check README for any authentication middleware the SDK provides. If available:
+
+1. Register middleware in `app/Http/Kernel.php` or `bootstrap/app.php` (Laravel 11+)
+2. Apply to routes that require authentication
+
+For Laravel 11+, middleware is registered in `bootstrap/app.php` instead of `Kernel.php`.
+
+## Step 9: Add UI Integration
+
+Update the home page or dashboard view to show:
+
+- Sign in link when user is not authenticated
+- User info and sign out link when authenticated
+
+Use Blade directives or SDK helpers from README.
+
+## Verification Checklist (ALL MUST PASS)
+
+```bash
+# 1. Config file exists
+ls config/workos.php
+
+# 2. Controller exists
+ls app/Http/Controllers/AuthController.php
+
+# 3. Routes registered
+php artisan route:list | grep -E "login|callback|logout"
+
+# 4. SDK installed
+composer show workos/workos-php-laravel
+
+# 5. Lint check
+php -l app/Http/Controllers/AuthController.php
+```
+
+## Error Recovery
+
+### "Class WorkOS\Laravel\WorkOSServiceProvider not found"
+
+- Verify `composer require` completed successfully
+- Run `composer dump-autoload`
+- Check `vendor/workos/` directory exists
+
+### "Route not defined"
+
+- Verify routes are in `routes/web.php`
+- Run `php artisan route:clear && php artisan route:cache`
+
+### Config not loading
+
+- Verify `config/workos.php` exists
+- Run `php artisan config:clear`
+- Check `.env` variables match config keys
+
+### Middleware issues (Laravel 11+)
+
+- Laravel 11 removed `Kernel.php` — register middleware in `bootstrap/app.php`
+- Check README for Laravel version-specific instructions

package/skills/workos-python/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: workos-python
+description: Integrate WorkOS AuthKit with Python applications. Adapts to Django, Flask, FastAPI, or vanilla Python. Server-side authentication with redirect-based OAuth flow.
+---
+
+# WorkOS AuthKit for Python
+
+## Step 1: Fetch SDK Documentation (BLOCKING)
+
+**STOP. Do not proceed until complete.**
+
+WebFetch: `https://raw.githubusercontent.com/workos/workos-python/main/README.md`
+
+Also fetch the AuthKit quickstart for reference:
+WebFetch: `https://workos.com/docs/authkit/vanilla/python`
+
+The README is the source of truth for SDK API usage. If this skill conflicts with README, follow README.
+
+## Step 2: Detect Framework
+
+Examine the project to determine which Python web framework is in use:
+
+```
+manage.py exists?                        → Django
+  settings.py has django imports?        → Confirmed Django
+
+Gemfile/requirements has 'fastapi'?      → FastAPI
+  main.py has FastAPI() instance?        → Confirmed FastAPI
+
+requirements has 'flask'?               → Flask
+  server.py/app.py has Flask() instance? → Confirmed Flask
+
+None of the above?                       → Vanilla Python (use Flask quickstart pattern)
+```
+
+**Adapt all subsequent steps to the detected framework.** Do not force one framework onto another.
+
+## Step 3: Pre-Flight Validation
+
+### Package Manager Detection
+
+```
+uv.lock exists?                          → uv add
+pyproject.toml has [tool.poetry]?        → poetry add
+Pipfile exists?                          → pipenv install
+requirements.txt exists?                 → pip install (+ append to requirements.txt)
+else                                     → pip install
+```
+
+### Environment Variables
+
+Check `.env` for:
+
+- `WORKOS_API_KEY` - starts with `sk_`
+- `WORKOS_CLIENT_ID` - starts with `client_`
+
+## Step 4: Install SDK
+
+Install using the detected package manager:
+
+```bash
+# uv
+uv add workos python-dotenv
+
+# poetry
+poetry add workos python-dotenv
+
+# pip
+pip install workos python-dotenv
+```
+
+If using `requirements.txt`, also append `workos` and `python-dotenv` to it.
+
+**Verify:** `python -c "import workos; print('OK')"`
+
+## Step 5: Integrate Authentication
+
+### If Django
+
+1. **Configure settings.py** — add `import os` + `from dotenv import load_dotenv` + `load_dotenv()` at top. Add `WORKOS_API_KEY` and `WORKOS_CLIENT_ID` from `os.environ.get()`.
+2. **Create auth views** — create `auth_views.py` (or add to existing views):
+   - `login_view`: call SDK's `get_authorization_url()` with `provider='authkit'`, redirect
+   - `callback_view`: call `authenticate_with_code()` with the code param, store user in `request.session`
+   - `logout_view`: flush session, redirect
+3. **Add URL patterns** — add `auth/login/`, `auth/callback/`, `auth/logout/` to `urls.py`
+4. **Update templates** — add login/logout links using `{% url %}` tags
+
+### If Flask
+
+Follow the quickstart pattern exactly:
+
+1. **Initialize WorkOS client** in `server.py` / `app.py`:
+   ```python
+   from workos import WorkOSClient
+   workos = WorkOSClient(api_key=os.getenv("WORKOS_API_KEY"), client_id=os.getenv("WORKOS_CLIENT_ID"))
+   ```
+2. **Create `/login` route** — call `workos.user_management.get_authorization_url(provider="authkit", redirect_uri="...")`, redirect
+3. **Create `/callback` route** — call `workos.user_management.authenticate_with_code(code=code)`, set session cookie
+4. **Create `/logout` route** — clear session, redirect
+5. **Update home route** — show user info if session exists
+
+### If FastAPI
+
+1. **Initialize WorkOS client** in main app file
+2. **Create `/login` endpoint** — generate auth URL, return `RedirectResponse`
+3. **Create `/callback` endpoint** — exchange code, store in session/cookie
+4. **Create `/logout` endpoint** — clear session
+5. Use `Depends()` for auth middleware on protected routes
+
+### If Vanilla Python (no framework detected)
+
+Install Flask and follow the Flask pattern above. This matches the official quickstart.
+
+## Step 6: Environment Setup
+
+Create/update `.env` with WorkOS credentials. Do NOT overwrite existing values.
+
+```
+WORKOS_API_KEY=sk_...
+WORKOS_CLIENT_ID=client_...
+```
+
+## Step 7: Verification Checklist
+
+```bash
+# 1. SDK importable
+python -c "import workos; print('OK')"
+
+# 2. Credentials configured
+python -c "
+from dotenv import load_dotenv; import os; load_dotenv()
+assert os.environ.get('WORKOS_API_KEY','').startswith('sk_'), 'Missing WORKOS_API_KEY'
+assert os.environ.get('WORKOS_CLIENT_ID','').startswith('client_'), 'Missing WORKOS_CLIENT_ID'
+print('Credentials OK')
+"
+
+# 3. Framework-specific check
+# Django: python manage.py check
+# Flask: python -m py_compile server.py
+# FastAPI: python -m py_compile main.py
+```
+
+## Error Recovery
+
+### "ModuleNotFoundError: No module named 'workos'"
+
+Re-run the install command for the detected package manager.
+
+### Django: "CSRF verification failed"
+
+Auth callback receives GET requests from WorkOS. Ensure callback view uses GET, not POST. Or add `@csrf_exempt`.
+
+### Flask: Session not persisting
+
+Ensure `app.secret_key` is set (required for Flask sessions).
+
+### Virtual environment not active
+
+Check for `.venv/`, `venv/`, or poetry-managed environments. Activate before running install.