workos 0.8.2 → 0.10.0

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

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

@@ -1,247 +0,0 @@
----
-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: Locate the app/ directory (BLOCKING)
-
-**STOP. Do this before creating any files.**
-
-Determine where the `app/` directory lives:
-
-```bash
-# Check for src/app/ first, then root app/
-ls src/app/ 2>/dev/null && echo "APP_DIR=src" || (ls app/ 2>/dev/null && echo "APP_DIR=root")
-```
-
-Set `APP_DIR` for all subsequent steps. All middleware/proxy files MUST be created in `APP_DIR`:
-
-- If `APP_DIR=src` → create files in `src/` (e.g., `src/proxy.ts`)
-- If `APP_DIR=root` → create files at project root (e.g., `proxy.ts`)
-
-Next.js only discovers middleware/proxy files in the parent directory of `app/`. A file at the wrong level is **silently ignored** — no error, just doesn't run.
-
-## Step 5: Version Detection (Decision Tree)
-
-Read Next.js version from `package.json`:
-
-```
-Next.js version?
-  |
-  +-- 16+ --> Create {APP_DIR}/proxy.ts
-  |
-  +-- 15   --> Create {APP_DIR}/middleware.ts (cookies() is async)
-  |
-  +-- 13-14 --> Create {APP_DIR}/middleware.ts (cookies() is sync)
-```
-
-**Next.js 16+ proxy.ts:** `proxy.ts` is the preferred convention. `middleware.ts` still works but shows a deprecation warning. Next.js 16 throws **error E900** if both files exist at the same level.
-
-**Next.js 15+ async note:** All route handlers and middleware accessing cookies must be async and properly await cookie operations. This is a breaking change from Next.js 14.
-
-Middleware/proxy code: See README for `authkitMiddleware()` export pattern.
-
-### Existing Middleware (IMPORTANT)
-
-If `middleware.ts` already exists with custom logic (rate limiting, logging, headers, etc.), use the **`authkit()` composable function** instead of `authkitMiddleware`.
-
-**Pattern for composing with existing middleware:**
-
-```typescript
-import { NextRequest, NextResponse } from 'next/server';
-import { authkit, handleAuthkitHeaders } from '@workos-inc/authkit-nextjs';
-
-export default async function middleware(request: NextRequest) {
-  // 1. Get auth session and headers from AuthKit
-  const { session, headers, authorizationUrl } = await authkit(request);
-  const { pathname } = request.nextUrl;
-
-  // 2. === YOUR EXISTING MIDDLEWARE LOGIC ===
-  // Rate limiting, logging, custom headers, etc.
-  const rateLimitResult = checkRateLimit(request);
-  if (!rateLimitResult.allowed) {
-    return new NextResponse('Too Many Requests', { status: 429 });
-  }
-
-  // 3. Protect routes - redirect to auth if needed
-  if (pathname.startsWith('/dashboard') && !session.user && authorizationUrl) {
-    return handleAuthkitHeaders(request, headers, { redirect: authorizationUrl });
-  }
-
-  // 4. Continue with AuthKit headers properly handled
-  return handleAuthkitHeaders(request, headers);
-}
-```
-
-**Key functions:**
-
-- `authkit(request)` - Returns `{ session, headers, authorizationUrl }` for composition
-- `handleAuthkitHeaders(request, headers, options?)` - Ensures AuthKit headers pass through correctly
-- For rewrites, use `partitionAuthkitHeaders()` and `applyResponseHeaders()` (see README)
-
-**Critical:** Always return via `handleAuthkitHeaders()` to ensure `withAuth()` works in pages.
-
-## Step 6: Create Callback Route
-
-Parse `NEXT_PUBLIC_WORKOS_REDIRECT_URI` to determine route path:
-
-```
-URI path          --> Route location (use APP_DIR from Step 4)
-/auth/callback    --> {APP_DIR}/app/auth/callback/route.ts
-/callback         --> {APP_DIR}/app/callback/route.ts
-```
-
-Use `handleAuth()` from SDK. Do not write custom OAuth logic.
-
-**CRITICAL for Next.js 15+:** The route handler MUST be async and properly await handleAuth():
-
-```typescript
-// CORRECT - Next.js 15+ requires async route handlers
-export const GET = handleAuth();
-
-// If handleAuth returns a function, ensure it's awaited in request context
-```
-
-Check README for exact usage. If build fails with "cookies outside request scope", the handler is likely missing async/await.
-
-## Step 7: Provider Setup (REQUIRED)
-
-**CRITICAL:** You MUST wrap the app in `AuthKitProvider` in `app/layout.tsx`.
-
-This is required for:
-
-- Client-side auth state via `useAuth()` hook
-- Consistent auth UX across client/server boundaries
-- Proper migration from Auth0 (which uses client-side auth)
-
-```tsx
-// app/layout.tsx
-import { AuthKitProvider } from '@workos-inc/authkit-nextjs/components';
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <AuthKitProvider>{children}</AuthKitProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-**Do NOT skip this step** even if using server-side auth patterns elsewhere.
-
-## Step 8: UI Integration
-
-Add auth UI to `app/page.tsx` using SDK functions. See README for auth helper usage (`withAuth`/`getUser`, `getSignInUrl`, `signOut`).
-
-**Note:** The SDK renamed `getUser` to `withAuth` in newer versions. Use whichever function the installed SDK version exports — do NOT rename existing working imports.
-
-## Verification Checklist (ALL MUST PASS)
-
-Run these commands to confirm integration. **Do not mark complete until all pass:**
-
-```bash
-# 1. Check middleware/proxy exists (one should match)
-ls proxy.ts middleware.ts src/proxy.ts src/middleware.ts 2>/dev/null
-
-# 2. CRITICAL: Check AuthKitProvider is in layout (REQUIRED)
-grep "AuthKitProvider" app/layout.tsx || echo "FAIL: AuthKitProvider missing from layout"
-
-# 3. Check callback route exists
-find app -name "route.ts" -path "*/callback/*"
-
-# 4. Build succeeds
-npm run build
-```
-
-**If check #2 fails:** Go back to Step 6 and add AuthKitProvider. This is not optional.
-
-## Error Recovery
-
-### "cookies was called outside a request scope" (Next.js 15+)
-
-**Most common cause:** Route handler not properly async or missing await.
-
-Fix for callback route:
-
-1. Check that `handleAuth()` is exported directly: `export const GET = handleAuth();`
-2. If using custom wrapper, ensure it's `async` and awaits any cookie operations
-3. Verify authkit-nextjs SDK version supports Next.js 15+ (check README for compatibility)
-4. **Never** call `cookies()` at module level - only inside request handlers
-
-This error causes OAuth codes to expire ("invalid_grant"), so fix the handler first.
-
-### "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)
-
-### "Both middleware file and proxy file are detected" (Next.js 16+)
-
-- Next.js 16 throws error E900 if both `middleware.ts` and `proxy.ts` exist
-- Delete `middleware.ts` and use only `proxy.ts`
-- If `middleware.ts` has custom logic, migrate it into `proxy.ts`
-
-### "withAuth route not covered by middleware" but middleware/proxy file exists
-
-- **Most common cause:** File is at the wrong level. Next.js only discovers middleware/proxy files in the parent directory of `app/`. For `src/app/` projects, the file must be in `src/`, not at the project root.
-- Check: Is `app/` at `src/app/`? Then middleware/proxy must be at `src/middleware.ts` or `src/proxy.ts`
-- Check: Matcher config must include the route path being accessed
-
-### "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: Import path matches what README specifies (root export vs `/components` subpath)
-- 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

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

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