Skip to content

fix: harden Next.js AuthKit skill against Server Component cookie violations #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nicknisi merged 2 commits into from
Mar 31, 2026
Merged

fix: harden Next.js AuthKit skill against Server Component cookie violations #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e1ef53e
fix: harden Next.js AuthKit skill against Server Component cookie vio…
nicknisi Mar 30, 2026
ceb7343
chore: formatting
nicknisi Mar 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,13 +104,15 @@ pnpm eval:calibrate # scorer vs human agreement repor
## Do / Don't

**Do:**

- Edit topic files (`plugins/workos/skills/workos/references/*.md`) directly -- they are human-maintained
- Start every topic file with doc URLs and "If this file conflicts with fetched docs, follow the docs."
- Add gotcha bullets when you discover the LLM produces incorrect output for a topic
- Update the router table in `plugins/workos/skills/workos/SKILL.md` when adding new topic files
- Write `.spec.ts` tests in `scripts/tests/` for eval framework changes

**Don't:**

- Modify the `workos-widgets` skill when working on reference files
- Add frontmatter to topic files -- the router handles discovery
- Change the plugin directory structure under `plugins/workos/` without considering caching boundaries
Expand Down
122 changes: 61 additions & 61 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,27 +34,27 @@ Path helpers are also available for consumers that need file paths (e.g., skill
import { getReferencePath, getSkillsDir, getSkillPath } from '@workos/skills';

const refPath = getReferencePath('workos-authkit-nextjs'); // absolute path to .md file
const skillsDir = getSkillsDir(); // directory containing workos/ and workos-widgets/
const skillPath = getSkillPath('workos'); // absolute path to SKILL.md
const skillsDir = getSkillsDir(); // directory containing workos/ and workos-widgets/
const skillPath = getSkillPath('workos'); // absolute path to SKILL.md
```

### Exports

| Function | Returns |
| --- | --- |
| `getReference(name)` | `Promise<string>` — reference file content |
| `getSkill(skillName)` | `Promise<string>` — skill SKILL.md content |
| `getReferencePath(name)` | Absolute path to `references/{name}.md` |
| `getSkillsDir()` | Absolute path to the `skills/` directory |
| Function | Returns |
| ------------------------- | ---------------------------------------------- |
| `getReference(name)` | `Promise<string>` — reference file content |
| `getSkill(skillName)` | `Promise<string>` — skill SKILL.md content |
| `getReferencePath(name)` | Absolute path to `references/{name}.md` |
| `getSkillsDir()` | Absolute path to the `skills/` directory |
| `getSkillPath(skillName)` | Absolute path to `skills/{skillName}/SKILL.md` |

## Skills

Two registered skills:

| Skill | Description |
| --- | --- |
| `workos` | Router — identifies which reference to load based on the user's task |
| Skill | Description |
| ---------------- | ----------------------------------------------------------------------- |
| `workos` | Router — identifies which reference to load based on the user's task |
| `workos-widgets` | Multi-framework widget integration with on-demand OpenAPI spec querying |

Everything else is a **reference file** under `references/`. The router dispatches to the right reference via progressive disclosure.
Expand All @@ -63,72 +63,72 @@ Everything else is a **reference file** under `references/`. The router dispatch

#### AuthKit Installation

| Reference | Description |
| --- | --- |
| `workos-authkit-nextjs` | Next.js App Router integration |
| `workos-authkit-react` | React SPA integration |
| `workos-authkit-react-router` | React Router v6/v7 integration |
| `workos-authkit-tanstack-start` | TanStack Start integration |
| `workos-authkit-sveltekit` | SvelteKit integration |
| `workos-authkit-vanilla-js` | Vanilla JS integration |
| `workos-authkit-base` | AuthKit architecture reference |
| Reference | Description |
| ------------------------------- | ------------------------------ |
| `workos-authkit-nextjs` | Next.js App Router integration |
| `workos-authkit-react` | React SPA integration |
| `workos-authkit-react-router` | React Router v6/v7 integration |
| `workos-authkit-tanstack-start` | TanStack Start integration |
| `workos-authkit-sveltekit` | SvelteKit integration |
| `workos-authkit-vanilla-js` | Vanilla JS integration |
| `workos-authkit-base` | AuthKit architecture reference |

#### Backend SDK Installation

| Reference | Description |
| --- | --- |
| `workos-node` | Node.js (Express/Fastify/Hono/Koa) |
| `workos-python` | Python (Django/Flask/FastAPI) |
| `workos-dotnet` | .NET (ASP.NET Core) |
| `workos-go` | Go |
| `workos-ruby` | Ruby (Rails) |
| `workos-php` | PHP |
| `workos-php-laravel` | PHP Laravel |
| `workos-kotlin` | Kotlin |
| `workos-elixir` | Elixir |
| Reference | Description |
| -------------------- | ---------------------------------- |
| `workos-node` | Node.js (Express/Fastify/Hono/Koa) |
| `workos-python` | Python (Django/Flask/FastAPI) |
| `workos-dotnet` | .NET (ASP.NET Core) |
| `workos-go` | Go |
| `workos-ruby` | Ruby (Rails) |
| `workos-php` | PHP |
| `workos-php-laravel` | PHP Laravel |
| `workos-kotlin` | Kotlin |
| `workos-elixir` | Elixir |

#### Features

| Reference | Description |
| --- | --- |
| `workos-sso` | Single Sign-On with SAML/OIDC |
| `workos-directory-sync` | User directory sync from IdPs |
| `workos-rbac` | Role-based access control |
| `workos-vault` | Encrypted data storage |
| `workos-events` | Webhook event handling |
| `workos-audit-logs` | Compliance audit logging |
| `workos-admin-portal` | Self-service admin portal |
| `workos-mfa` | Multi-factor authentication |
| `workos-custom-domains` | Custom domain configuration |
| `workos-email` | Email delivery configuration |
| `workos-integrations` | Provider lookup table for 60+ IdP integrations |
| Reference | Description |
| ----------------------- | ---------------------------------------------- |
| `workos-sso` | Single Sign-On with SAML/OIDC |
| `workos-directory-sync` | User directory sync from IdPs |
| `workos-rbac` | Role-based access control |
| `workos-vault` | Encrypted data storage |
| `workos-events` | Webhook event handling |
| `workos-audit-logs` | Compliance audit logging |
| `workos-admin-portal` | Self-service admin portal |
| `workos-mfa` | Multi-factor authentication |
| `workos-custom-domains` | Custom domain configuration |
| `workos-email` | Email delivery configuration |
| `workos-integrations` | Provider lookup table for 60+ IdP integrations |

#### Migrations

| Reference | Description |
| --- | --- |
| `workos-migrate-auth0` | Migrate from Auth0 |
| `workos-migrate-firebase` | Migrate from Firebase Auth |
| `workos-migrate-clerk` | Migrate from Clerk |
| `workos-migrate-aws-cognito` | Migrate from AWS Cognito |
| `workos-migrate-stytch` | Migrate from Stytch |
| `workos-migrate-supabase-auth` | Migrate from Supabase Auth |
| `workos-migrate-descope` | Migrate from Descope |
| `workos-migrate-better-auth` | Migrate from Better Auth |
| `workos-migrate-other-services` | Migrate from custom auth |
| Reference | Description |
| --------------------------------------- | --------------------------------- |
| `workos-migrate-auth0` | Migrate from Auth0 |
| `workos-migrate-firebase` | Migrate from Firebase Auth |
| `workos-migrate-clerk` | Migrate from Clerk |
| `workos-migrate-aws-cognito` | Migrate from AWS Cognito |
| `workos-migrate-stytch` | Migrate from Stytch |
| `workos-migrate-supabase-auth` | Migrate from Supabase Auth |
| `workos-migrate-descope` | Migrate from Descope |
| `workos-migrate-better-auth` | Migrate from Better Auth |
| `workos-migrate-other-services` | Migrate from custom auth |
| `workos-migrate-the-standalone-sso-api` | Upgrade standalone SSO to AuthKit |

#### API References

| Reference | Description |
| --- | --- |
| `workos-api-authkit` | AuthKit/User Management API endpoints |
| `workos-api-organization` | Organizations API endpoints |
| Reference | Description |
| ------------------------- | ------------------------------------- |
| `workos-api-authkit` | AuthKit/User Management API endpoints |
| `workos-api-organization` | Organizations API endpoints |

#### Management

| Reference | Description |
| --- | --- |
| Reference | Description |
| ------------------- | --------------------------------------------------------------- |
| `workos-management` | CLI resource management (orgs, users, roles, webhooks, seeding) |

## Development
Expand Down
48 changes: 24 additions & 24 deletions plugins/workos/skills/workos/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,30 +19,30 @@ When a user needs help with WorkOS, consult the tables below to route to the rig

### AuthKit Installation (Read `references/{name}.md`)

| User wants to... | Read file |
| ----------------------------------- | ------------------------------------------------- |
| Install AuthKit in Next.js | `references/workos-authkit-nextjs.md` |
| Install AuthKit in React SPA | `references/workos-authkit-react.md` |
| Install AuthKit with React Router | `references/workos-authkit-react-router.md` |
| Install AuthKit with TanStack Start | `references/workos-authkit-tanstack-start.md` |
| Install AuthKit with SvelteKit | `references/workos-authkit-sveltekit.md` |
| Install AuthKit in vanilla JS | `references/workos-authkit-vanilla-js.md` |
| AuthKit architecture reference | `references/workos-authkit-base.md` |
| Add WorkOS Widgets | Load `workos-widgets` skill via Skill tool |
| User wants to... | Read file |
| ----------------------------------- | --------------------------------------------- |
| Install AuthKit in Next.js | `references/workos-authkit-nextjs.md` |
| Install AuthKit in React SPA | `references/workos-authkit-react.md` |
| Install AuthKit with React Router | `references/workos-authkit-react-router.md` |
| Install AuthKit with TanStack Start | `references/workos-authkit-tanstack-start.md` |
| Install AuthKit with SvelteKit | `references/workos-authkit-sveltekit.md` |
| Install AuthKit in vanilla JS | `references/workos-authkit-vanilla-js.md` |
| AuthKit architecture reference | `references/workos-authkit-base.md` |
| Add WorkOS Widgets | Load `workos-widgets` skill via Skill tool |

### Backend SDK Installation (Read `references/{name}.md`)

| User wants to... | Read file |
| ------------------------------------ | -------------------------------------- |
| Install AuthKit in Node.js backend | `references/workos-node.md` |
| Install AuthKit in Python | `references/workos-python.md` |
| Install AuthKit in .NET | `references/workos-dotnet.md` |
| Install AuthKit in Go | `references/workos-go.md` |
| Install AuthKit in Ruby | `references/workos-ruby.md` |
| Install AuthKit in PHP | `references/workos-php.md` |
| Install AuthKit in PHP Laravel | `references/workos-php-laravel.md` |
| Install AuthKit in Kotlin | `references/workos-kotlin.md` |
| Install AuthKit in Elixir | `references/workos-elixir.md` |
| User wants to... | Read file |
| ---------------------------------- | ---------------------------------- |
| Install AuthKit in Node.js backend | `references/workos-node.md` |
| Install AuthKit in Python | `references/workos-python.md` |
| Install AuthKit in .NET | `references/workos-dotnet.md` |
| Install AuthKit in Go | `references/workos-go.md` |
| Install AuthKit in Ruby | `references/workos-ruby.md` |
| Install AuthKit in PHP | `references/workos-php.md` |
| Install AuthKit in PHP Laravel | `references/workos-php-laravel.md` |
| Install AuthKit in Kotlin | `references/workos-kotlin.md` |
| Install AuthKit in Elixir | `references/workos-elixir.md` |

### Features (Read `references/{name}.md`)

Expand Down Expand Up @@ -86,9 +86,9 @@ Feature topic files above include endpoint tables for their respective APIs. Use

### Management (Read `references/{name}.md`)

| User wants to... | Read file |
| ---------------------------------------- | ---------------------------------- |
| Manage WorkOS resources via CLI commands | `references/workos-management.md` |
| User wants to... | Read file |
| ---------------------------------------- | --------------------------------- |
| Manage WorkOS resources via CLI commands | `references/workos-management.md` |

## Routing Decision Tree

Expand Down
5 changes: 4 additions & 1 deletion plugins/workos/skills/workos/references/workos-admin-portal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
# WorkOS Admin Portal

## Docs

- https://workos.com/docs/admin-portal/index
- https://workos.com/docs/admin-portal/example-apps
- https://workos.com/docs/admin-portal/custom-branding
- https://workos.com/docs/reference/admin-portal
- https://workos.com/docs/reference/admin-portal/portal-link
- https://workos.com/docs/reference/admin-portal/portal-link/generate
- https://workos.com/docs/reference/admin-portal/provider-icons
If this file conflicts with fetched docs, follow the docs.
If this file conflicts with fetched docs, follow the docs.

## Gotchas

- Portal links are single-use and time-limited. Visiting an expired or already-used link returns 404. Must generate a new link each time.
- Do NOT email portal links directly from your backend. Links are exposed in email logs. Instead, store the link and have your app's settings page redirect to it.
- The `intent` parameter determines which configuration screens appear. It cannot be changed after link generation — must generate a new link for a different intent.
Expand All @@ -19,6 +21,7 @@ If this file conflicts with fetched docs, follow the docs.
- API key must start with `sk_` (secret key). Using `pk_` (publishable key) returns "Unauthorized."

## Endpoints

| Endpoint | Description |
| ----------------------- | ------------------------------------- |
| `/admin-portal` | admin-portal |
Expand Down
Loading