workos 0.0.24 → 0.1.0

package/skills/workos-authkit-base/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: workos-authkit-base
+description: Architectural reference for WorkOS AuthKit integrations. Fetch README first for implementation details.
+---
+
+# WorkOS AuthKit Base Template
+
+## First Action: Fetch README
+
+Before any implementation, fetch the framework-specific README:
+
+```
+WebFetch: {sdk-package-name} README from npmjs.com or GitHub
+```
+
+README is the source of truth for: install commands, imports, API usage, code patterns.
+
+## Task Structure (Required)
+
+| Phase | Task | Blocked By | Purpose |
+|-------|------|------------|---------|
+| 1 | preflight | - | Verify env vars, detect framework |
+| 2 | install | preflight | Install SDK package |
+| 3 | callback | install | Create OAuth callback route |
+| 4 | provider | install | Setup auth context/middleware |
+| 5 | ui | callback, provider | Add sign-in/out UI |
+| 6 | verify | ui | Build confirmation |
+
+## Decision Trees
+
+### Package Manager Detection
+
+```
+pnpm-lock.yaml? → pnpm
+yarn.lock? → yarn
+bun.lockb? → bun
+else → npm
+```
+
+### Provider vs Middleware
+
+```
+Client-side framework? → AuthKitProvider wraps app
+Server-side framework? → Middleware handles sessions
+Hybrid (Next.js)? → Both may be needed
+```
+
+### Callback Route Location
+
+Extract path from `WORKOS_REDIRECT_URI` → create route at that exact path.
+
+## Environment Variables
+
+| Variable | Purpose | When Required |
+|----------|---------|---------------|
+| `WORKOS_API_KEY` | Server authentication | Server SDKs |
+| `WORKOS_CLIENT_ID` | Client identification | All SDKs |
+| `WORKOS_REDIRECT_URI` | OAuth callback URL | Server SDKs |
+| `WORKOS_COOKIE_PASSWORD` | Session encryption (32+ chars) | Server SDKs |
+
+Note: Some frameworks use prefixed variants (e.g., `NEXT_PUBLIC_*`). Check README.
+
+## Verification Checklists
+
+### After Install
+- [ ] SDK package installed in node_modules
+- [ ] No install errors in output
+
+### After Callback Route
+- [ ] Route file exists at path matching `WORKOS_REDIRECT_URI`
+- [ ] Imports SDK callback handler (not custom OAuth)
+
+### After Provider/Middleware
+- [ ] Provider wraps entire app (client-side)
+- [ ] Middleware configured in correct location (server-side)
+
+### After UI
+- [ ] Home page shows conditional auth state
+- [ ] Uses SDK functions for sign-in/out URLs
+
+### Final Verification
+- [ ] Build completes with exit code 0
+- [ ] No import resolution errors
+
+## Error Recovery
+
+### Module not found
+- [ ] Verify install completed successfully
+- [ ] Verify SDK exists in node_modules
+- [ ] Re-run install if missing
+
+### Build import errors
+- [ ] Delete `node_modules`, reinstall
+- [ ] Verify package.json has SDK dependency
+
+### Invalid redirect URI
+- [ ] Compare route path to `WORKOS_REDIRECT_URI`
+- [ ] Paths must match exactly
+
+### Cookie password error
+- [ ] Verify `WORKOS_COOKIE_PASSWORD` is 32+ characters
+- [ ] Generate new: `openssl rand -base64 32`
+
+### Auth state not persisting
+- [ ] Verify provider wraps entire app
+- [ ] Check middleware is in correct location
+
+## Critical Rules
+
+1. **Install SDK before writing imports** - never create import statements for uninstalled packages
+2. **Use SDK functions** - never construct OAuth URLs manually
+3. **Follow README patterns** - SDK APIs change between versions
+4. **Extract callback path from env** - don't hardcode `/auth/callback`

package/skills/workos-authkit-nextjs/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: workos-authkit-nextjs
+description: Integrate WorkOS AuthKit with Next.js App Router (13+). Server-side rendering required.
+---
+
+# WorkOS AuthKit for Next.js
+
+## Step 1: Fetch SDK Documentation (BLOCKING)
+
+**STOP. Do not proceed until complete.**
+
+WebFetch: `https://github.com/workos/authkit-nextjs/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 `next.config.js` or `next.config.mjs` exists
+- Confirm `package.json` contains `"next"` dependency
+
+### Environment Variables
+Check `.env.local` for:
+- `WORKOS_API_KEY` - starts with `sk_`
+- `WORKOS_CLIENT_ID` - starts with `client_`
+- `NEXT_PUBLIC_WORKOS_REDIRECT_URI` - valid callback URL
+- `WORKOS_COOKIE_PASSWORD` - 32+ characters
+
+## Step 3: Install SDK
+
+Detect package manager, install SDK package from README.
+
+**Verify:** SDK package exists in node_modules before continuing.
+
+## Step 4: Version Detection (Decision Tree)
+
+Read Next.js version from `package.json`:
+
+```
+Next.js version?
+  |
+  +-- 16+ --> Create proxy.ts at project root
+  |
+  +-- 13-15 --> Create middleware.ts at project root
+```
+
+**Critical:** File MUST be at project root (or `src/` if using src directory). Never in `app/`.
+
+Middleware/proxy code: See README for `authkitMiddleware()` export pattern.
+
+## Step 5: Create Callback Route
+
+Parse `NEXT_PUBLIC_WORKOS_REDIRECT_URI` to determine route path:
+
+```
+URI path          --> Route location
+/auth/callback    --> app/auth/callback/route.ts
+/callback         --> app/callback/route.ts
+```
+
+Use `handleAuth()` from SDK. Do not write custom OAuth logic.
+
+## Step 6: Provider Setup
+
+Wrap app in `AuthKitProvider` in `app/layout.tsx`. See README for import path.
+
+## Step 7: UI Integration
+
+Add auth UI to `app/page.tsx` using SDK functions. See README for `getUser`, `getSignInUrl`, `signOut` usage.
+
+## Verification Checklist
+
+Run these commands to confirm integration:
+
+```bash
+# Check middleware/proxy exists (one should match)
+ls proxy.ts middleware.ts src/proxy.ts src/middleware.ts 2>/dev/null
+
+# Check provider is wrapped
+grep -l "AuthKitProvider" app/layout.tsx
+
+# Check callback route exists
+find app -name "route.ts" -path "*/callback/*"
+
+# Build succeeds
+npm run build
+```
+
+All checks must pass before marking complete.
+
+## Error Recovery
+
+### "middleware.ts not found"
+- Check: File at project root or `src/`, not inside `app/`
+- Check: Filename matches Next.js version (proxy.ts for 16+, middleware.ts for 13-15)
+
+### "Cannot use getUser in client component"
+- Check: Component has no `'use client'` directive, or
+- Check: Move auth logic to server component/API route
+
+### "Module not found" for SDK import
+- Check: SDK installed before writing imports
+- Check: SDK package directory exists in node_modules
+
+### "withAuth route not covered by middleware"
+- Check: Middleware/proxy file exists at correct location
+- Check: Matcher config includes the route path
+
+### Build fails after AuthKitProvider
+- Check: README for correct import path (may be subpath export)
+- Check: No client/server boundary violations
+
+### NEXT_PUBLIC_ prefix issues
+- Client components need `NEXT_PUBLIC_*` prefix
+- Server components use plain env var names

package/skills/workos-authkit-react/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: workos-authkit-react
+description: Integrate WorkOS AuthKit with React single-page applications. Client-side only authentication. Use when the project is a React SPA without Next.js or React Router.
+---
+
+# WorkOS AuthKit for React (SPA)
+
+## Decision Tree
+
+```
+START
+  │
+  ├─► Fetch README (BLOCKING)
+  │   github.com/workos/authkit-react/blob/main/README.md
+  │   README is source of truth. Stop if fetch fails.
+  │
+  ├─► Detect Build Tool
+  │   ├─ vite.config.ts exists? → Vite
+  │   └─ otherwise → Create React App
+  │
+  ├─► Set Env Var Prefix
+  │   ├─ Vite → VITE_WORKOS_CLIENT_ID
+  │   └─ CRA  → REACT_APP_WORKOS_CLIENT_ID
+  │
+  └─► Implement per README
+```
+
+## Critical: Build Tool Detection
+
+| Marker File | Build Tool | Env Prefix | Access Pattern |
+|-------------|------------|------------|----------------|
+| `vite.config.ts` | Vite | `VITE_` | `import.meta.env.VITE_*` |
+| `craco.config.js` or none | CRA | `REACT_APP_` | `process.env.REACT_APP_*` |
+
+**Wrong prefix = undefined values at runtime.** This is the #1 integration failure.
+
+## Key Clarification: No Callback Route
+
+The React SDK handles OAuth callbacks **internally** via AuthKitProvider.
+
+- No server-side callback route needed
+- SDK intercepts redirect URI client-side
+- Token exchange happens automatically
+
+Just ensure redirect URI env var matches WorkOS Dashboard exactly.
+
+## Required Environment Variables
+
+```
+{PREFIX}WORKOS_CLIENT_ID=client_...
+{PREFIX}WORKOS_REDIRECT_URI=http://localhost:5173/callback
+```
+
+No `WORKOS_API_KEY` needed. Client-side only SDK.
+
+## Verification Checklist
+
+- [ ] README fetched and read
+- [ ] Build tool detected correctly
+- [ ] Env var prefix matches build tool
+- [ ] `.env` or `.env.local` has required vars
+- [ ] No `next` dependency (wrong skill)
+- [ ] No `react-router` dependency (wrong skill)
+- [ ] AuthKitProvider wraps app root
+- [ ] `pnpm build` exits 0
+
+## Error Recovery
+
+### "clientId is required"
+
+**Cause:** Env var inaccessible (wrong prefix)
+
+Check: Does prefix match build tool? Vite needs `VITE_`, CRA needs `REACT_APP_`.
+
+### Auth state lost on refresh
+
+**Cause:** Token persistence issue
+
+Check: Browser dev tools → Application → Local Storage. SDK stores tokens here automatically.
+
+### useAuth returns undefined
+
+**Cause:** Component outside provider tree
+
+Check: Entry file (`main.tsx` or `index.tsx`) wraps `<App />` in `<AuthKitProvider>`.
+
+### Callback redirect fails
+
+**Cause:** URI mismatch
+
+Check: Env var redirect URI exactly matches WorkOS Dashboard → Redirects configuration.

package/skills/workos-authkit-react-router/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: workos-authkit-react-router
+description: Integrate WorkOS AuthKit with React Router applications. Supports v6 and v7 (Framework, Data, Declarative modes). Use when project uses react-router, react-router-dom, or mentions React Router authentication.
+---
+
+# WorkOS AuthKit for React Router
+
+## Decision Tree
+
+```
+1. Fetch README (BLOCKING)
+2. Detect router mode
+3. Follow README for that mode
+4. Verify with checklist below
+```
+
+## Phase 1: Fetch SDK Documentation (BLOCKING)
+
+**STOP - Do not write any code until this completes.**
+
+WebFetch: `https://github.com/workos/authkit-react-router/blob/main/README.md`
+
+The README is the source of truth. If this skill conflicts with README, **follow the README**.
+
+## Phase 2: Detect Router Mode
+
+| Mode           | Detection Signal                | Key Indicator               |
+| -------------- | ------------------------------- | --------------------------- |
+| v7 Framework   | `react-router.config.ts` exists | Routes in `app/routes/`     |
+| v7 Data        | `createBrowserRouter` in source | Loaders in route config     |
+| v7 Declarative | `<BrowserRouter>` component     | Routes as JSX, no loaders   |
+| v6             | package.json version `"6.x"`    | Similar to v7 Declarative   |
+
+**Detection order:**
+1. Check for `react-router.config.ts` (Framework mode)
+2. Grep for `createBrowserRouter` (Data mode)
+3. Check package.json version (v6 vs v7)
+4. Default to Declarative if v7 with `<BrowserRouter>`
+
+## Phase 3: Follow README
+
+Based on detected mode, apply the corresponding README section. The README contains current API signatures and code patterns.
+
+## Critical Distinctions
+
+### authLoader vs authkitLoader
+
+| Function       | Purpose                          | Where to use            |
+| -------------- | -------------------------------- | ----------------------- |
+| `authLoader`   | OAuth callback handler           | Callback route ONLY     |
+| `authkitLoader`| Fetch user data in routes        | Any route needing auth  |
+
+**Common mistake:** Using `authkitLoader` for callback route. Use `authLoader()`.
+
+### Root Route Requirement
+
+Auth loader MUST be on root route for child routes to access auth context.
+
+**Wrong:** Auth loader only on `/dashboard`
+**Right:** Auth loader on `/` (root), children inherit context
+
+## Environment Variables
+
+Required in `.env` or `.env.local`:
+
+- `WORKOS_API_KEY` - starts with `sk_`
+- `WORKOS_CLIENT_ID` - starts with `client_`
+- `WORKOS_REDIRECT_URI` - full URL (e.g., `http://localhost:3000/auth/callback`)
+- `WORKOS_COOKIE_PASSWORD` - 32+ chars (server modes only)
+
+## Verification Checklist
+
+After implementation, verify:
+
+- [ ] SDK installed in node_modules (package name from README)
+- [ ] Callback route path matches `WORKOS_REDIRECT_URI` path segment
+- [ ] Auth loader/provider on root route (not just child routes)
+- [ ] Build succeeds: `npm run build` exits 0
+- [ ] Correct mode pattern applied (loaders vs hooks)
+
+## Error Recovery
+
+### "loader is not a function"
+
+**Cause:** Using loader pattern in Declarative/v6 mode
+**Fix:** Declarative/v6 modes use `AuthKitProvider` + `useAuth` hook, not loaders
+
+### Auth state not available in child routes
+
+**Cause:** Auth loader missing from root route
+**Fix:** Add `authkitLoader` (or `AuthKitProvider`) to root route so children inherit context
+
+### useAuth returns undefined
+
+**Cause:** Missing `AuthKitProvider` wrapper
+**Fix:** Wrap app with `AuthKitProvider` (required for Declarative/v6 modes)
+
+### Callback route 404
+
+**Cause:** Route path mismatch with `WORKOS_REDIRECT_URI`
+**Fix:** Extract exact path from env var, create route at that path
+
+### "Module not found" for SDK
+
+**Cause:** SDK not installed
+**Fix:** Install SDK, wait for completion, verify `node_modules` before writing imports

package/skills/workos-authkit-tanstack-start/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: workos-authkit-tanstack-start
+description: Integrate WorkOS AuthKit with TanStack Start applications. Full-stack TypeScript with server functions. Use when project uses TanStack Start, @tanstack/start, or vinxi.
+---
+
+# WorkOS AuthKit for TanStack Start
+
+## Decision Tree
+
+```
+1. Fetch README (BLOCKING)
+   ├── Extract package name from install command
+   └── README is source of truth for ALL code patterns
+
+2. Verify TanStack Start project
+   ├── @tanstack/start or @tanstack/react-start in package.json
+   └── app.config.ts exists (vinxi)
+
+3. Follow README install/setup exactly
+   └── Do not invent commands or patterns
+```
+
+## Fetch SDK Documentation (BLOCKING)
+
+**STOP - Do not proceed until complete.**
+
+WebFetch: `https://github.com/workos/authkit-tanstack-start/blob/main/README.md`
+
+From README, extract:
+1. Package name from install command (e.g., `pnpm add @workos/...`)
+2. Use that exact name for all imports
+
+**README overrides this skill if conflict.**
+
+## Pre-Flight Checklist
+
+- [ ] README fetched and package name extracted
+- [ ] `@tanstack/start` or `@tanstack/react-start` in package.json
+- [ ] `app.config.ts` exists
+- [ ] Environment variables set (see below)
+
+## Environment Variables
+
+| Variable | Format | Required |
+|----------|--------|----------|
+| `WORKOS_API_KEY` | `sk_...` | Yes |
+| `WORKOS_CLIENT_ID` | `client_...` | Yes |
+| `WORKOS_REDIRECT_URI` | Full URL | Yes |
+| `WORKOS_COOKIE_PASSWORD` | 32+ chars | Yes |
+
+Generate password if missing: `openssl rand -base64 32`
+
+## Middleware Configuration (CRITICAL)
+
+**authkitMiddleware MUST be configured or auth will fail.**
+
+Find file with `createRouter` (typically `app/router.tsx` or `app.tsx`).
+
+### Verification Checklist
+
+- [ ] `authkitMiddleware` imported from SDK package
+- [ ] `middleware: [authkitMiddleware()]` in createRouter config
+- [ ] Array syntax used: `[authkitMiddleware()]` not `authkitMiddleware()`
+
+Verify: `grep "authkitMiddleware" app/router.tsx app.tsx src/router.tsx`
+
+## Logout Route Pattern
+
+Logout requires `signOut()` followed by redirect in a route loader. See README for exact implementation.
+
+## Callback Route
+
+Path must match `WORKOS_REDIRECT_URI`. If URI is `/api/auth/callback`:
+- File: `app/routes/api/auth/callback.tsx`
+- Use `handleAuth()` from SDK - do not write custom OAuth logic
+
+## Error Recovery
+
+### "AuthKit middleware is not configured"
+
+**Cause:** `authkitMiddleware()` not added to router
+**Fix:** Add `middleware: [authkitMiddleware()]` to createRouter config
+**Verify:** `grep "authkitMiddleware" app/router.tsx app.tsx`
+
+### "Module not found" for SDK
+
+**Cause:** Wrong package name or not installed
+**Fix:** Re-read README, extract correct package name, reinstall
+**Verify:** `ls node_modules/` + package name from README
+
+### Callback 404
+
+**Cause:** Route path doesn't match WORKOS_REDIRECT_URI
+**Fix:** File path must mirror URI path under `app/routes/`
+
+### getAuth returns undefined
+
+**Cause:** Middleware not configured
+**Fix:** Same as "AuthKit middleware not configured" above
+
+### "Cookie password too short"
+
+**Cause:** WORKOS_COOKIE_PASSWORD < 32 chars
+**Fix:** `openssl rand -base64 32`, update .env

package/skills/workos-authkit-vanilla-js/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: workos-authkit-vanilla-js
+description: Integrate WorkOS AuthKit with vanilla JavaScript applications. No framework required, browser-only. Use when project is plain HTML/JS, doesn't use React/Vue/etc, or mentions vanilla JavaScript authentication.
+---
+
+# WorkOS AuthKit for Vanilla JavaScript
+
+## Decision Tree
+
+### Step 1: Fetch README (BLOCKING)
+
+WebFetch: `https://github.com/workos/authkit-js/blob/main/README.md`
+
+**README is source of truth.** If this skill conflicts, follow README.
+
+### Step 2: Detect Project Type
+
+```
+Has package.json with build tool (Vite, webpack, Parcel)?
+  YES -> Bundled project (npm install)
+  NO  -> CDN/Static project (script tag)
+```
+
+### Step 3: Follow README Installation
+
+- **Bundled**: Use package manager install from README
+- **CDN**: Use unpkg script tag from README
+
+### Step 4: Implement Per README
+
+Follow README examples for:
+- Client initialization
+- Sign in/out handlers
+- User state management
+
+## Critical API Quirk
+
+`createClient()` is **async** - returns a Promise, not a client directly.
+
+```javascript
+// CORRECT
+const authkit = await createClient(clientId);
+```
+
+## Verification Checklist
+
+- [ ] README fetched and read before writing code
+- [ ] Project type detected (bundled vs CDN)
+- [ ] SDK installed/script added
+- [ ] `createClient()` called with `await`
+- [ ] Client ID provided (env var or hardcoded)
+- [ ] Sign in called from user gesture (click handler)
+- [ ] No console errors on page load
+- [ ] Auth UI updates on sign in/out
+
+## Environment Variables
+
+**Bundled projects only:**
+- Vite: `VITE_WORKOS_CLIENT_ID`
+- Webpack: `REACT_APP_WORKOS_CLIENT_ID` or custom
+- No `WORKOS_API_KEY` needed (client-side SDK)
+
+## Error Recovery
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `WorkOS is not defined` | CDN not loaded | Add script to `<head>` before your code |
+| `createClient is not a function` | Wrong import | npm: check import path; CDN: use `WorkOS.createClient` |
+| `clientId is required` | Undefined env var | Check env prefix matches build tool |
+| CORS errors | `file://` protocol | Use local dev server (`npx serve`) |
+| Popup blocked | Not user gesture | Call `signIn()` only from click handler |
+| Auth state lost | Token not persisted | Check localStorage in dev tools |
+
+## Task Flow
+
+1. **preflight**: Fetch README, detect project type, verify env vars
+2. **install**: Add SDK per project type
+3. **callback**: SDK handles internally (no server route needed)
+4. **provider**: Initialize client with `await createClient()`
+5. **ui**: Add auth buttons and state display
+6. **verify**: Build (if bundled), check console

package/build/apps/index.js

@@ -1,50 +0,0 @@
-"use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : new P(function (resolve) { resolve(result.value); }).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
-    function verb(n) { return function (v) { return step([n, v]); }; }
-    function step(op) {
-        if (f) throw new TypeError("Generator is already executing.");
-        while (_) try {
-            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
-            if (y = 0, t) op = [op[0] & 2, t.value];
-            switch (op[0]) {
-                case 0: case 1: t = op; break;
-                case 4: _.label++; return { value: op[1], done: false };
-                case 5: _.label++; y = op[1]; op = [0]; continue;
-                case 7: op = _.ops.pop(); _.trys.pop(); continue;
-                default:
-                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
-                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
-                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
-                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
-                    if (t[2]) _.ops.pop();
-                    _.trys.pop(); continue;
-            }
-            op = body.call(thisArg, _);
-        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
-        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
-    }
-};
-var _this = this;
-Object.defineProperty(exports, "__esModule", { value: true });
-var slack_1 = require("./slack");
-exports.appCommand = function () { return __awaiter(_this, void 0, void 0, function () {
-    return __generator(this, function (_a) {
-        switch (_a.label) {
-            case 0: return [4 /*yield*/, slack_1.authSlack()];
-            case 1:
-                _a.sent();
-                return [2 /*return*/];
-        }
-    });
-}); };
-//# sourceMappingURL=index.js.map