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

[nicknisi]

Summary

When running workos install on a Next.js B2B app, the installer agent could generate auth UI with three failure modes:

1. Server Component cookie violation — generating nav-auth.tsx as a Server Component calling getSignInUrl(), which sets PKCE cookies. Next.js 16 forbids cookie modification during render.
2. [object Object] redirect — SDK's actions.js calls getAuthorizationUrl() which returns { url, sealedState }, not a string.
3. OAuth state mismatch — sealedState discarded when using raw getAuthorizationUrl(), so PKCE cookie never set.

Bugs 2-3 are SDK bugs (out of scope here). Bug 1 is fixed by strengthening the skill reference that guides the installer agent.

Changes

Reference guide (workos-authkit-nextjs.md)

Step 8 rewrite — the old Step 8 ended with "See README for the recommended approach", which was too vague for the agent to follow reliably. The new version:

• Adds an explicit NavAuth client component example using useAuth() + refreshAuth({ ensureSignedIn: true }) with the correct import from @workos-inc/authkit-nextjs/components
• Splits guidance into "Server Components (safe)" vs "Shared nav/header auth UI (preferred)" sections
• Adds "Critical auth URL gotchas" section warning against raw getAuthorizationUrl() (returns object, not string; drops PKCE cookie)
• Adds verification checks 4-5 that rg for unsafe patterns in generated code
• Adds error recovery sections for [object Object] redirect and OAuth state mismatch

Eval cases (authkit-nextjs.yaml)

• authkit-nextjs-protected — removed getSignInUrl from expected methods (it shouldn't appear in server component answers) and added it as an anti-pattern for server component usage. Added form action={await getSignInUrl()} anti-pattern.
• authkit-nextjs-nav-auth-pkce (new) — regression case that directly encodes the three-bug scenario. Tests for AuthKitProvider, useAuth, refreshAuth, ensureSignedIn, and penalizes getSignInUrl in server components, raw getAuthorizationUrl, window.location.href = auth.signInUrl, and discarded sealedState.

Scorer regression test (eval-scorer.spec.ts)

Compares a broken implementation (the exact bug pattern) against the fixed implementation. Broken scores ≤60, fixed scores ≥80, and the broken pattern triggers security_issue error category.

Eval results

Case	With skill	Without	Delta
authkit-nextjs-nav-auth-pkce	91%	65%	+26% ±1
authkit-nextjs-protected	84%	72%	+12% ±6.5

Companion PR: workos/cli#110 (NextjsGrader structural check)