Authentication

Rule

Scope: Projects using Clerk (@clerk/nextjs), WorkOS (@workos-inc/authkit-nextjs), or any auth provider. The security-engineer agent loads these rules when auth packages are detected.

General (All Providers)

  • MUSTPerform auth checks server-side for all data access. Client-side auth is for UX gating only.
  • MUSTInvalidate sessions server-side on logout — don't rely on cookie deletion alone.
  • MUSTVerify webhook signatures before processing payloads. Use the provider's SDK verification, not manual HMAC.
  • MUSTReturn 401 for unauthenticated requests and 403 for insufficient permissions. Never return 404 to hide resources from unauthorized users without explicit reason.
  • MUSTEnforce RBAC at the data layer (queries/mutations), not just at route or middleware level. Middleware can be bypassed; data-layer checks cannot.
  • SHOULDRate-limit auth endpoints (login, signup, password reset, token refresh).
  • SHOULDRotate refresh tokens on each use (one-time use tokens).
  • SHOULDInclude userId in cache keys for any user-specific cached data.
  • NEVERTrust auth state from client components for data decisions. Always re-verify server-side.

Clerk

  • MUSTawait auth() — it's async in Next.js 15+ (App Router). Forgetting await returns a pending Promise that's always truthy.
  • MUSTUse auth.protect() in Server Actions, not just auth(). protect() throws on failure; auth() returns null.
  • MUSTKeep webhook routes public in Clerk middleware matcher. Webhook endpoints must not require auth.
  • MUSTHandle all user lifecycle webhook events (user.created, user.updated, user.deleted) when syncing to a database.
  • MUSTUse pk_test_* / sk_test_* keys in development. Production keys in dev environments create real user records.
  • SHOULDConfigure proxy matcher to protect routes explicitly. Default publicRoutes approach is error-prone — prefer matcher config. (Note: Next.js renamed middleware.ts to proxy.ts.)
  • SHOULDUse setupClerkTestingToken() in Playwright tests for fast auth without UI login.
  • NEVERExpose CLERK_SECRET_KEY in client bundles. It starts with sk_ — any env without NEXT_PUBLIC_ prefix is safe, but verify bundler config.
  • NEVERUse useAuth() for page-load access control. It runs client-side after render — use auth() in Server Components or middleware instead.

WorkOS

  • MUSTWrap root layout with AuthKitProvider. Missing provider causes silent auth failures — no error, just no auth.
  • MUSTAdd authkitMiddleware() to proxy.ts (formerly middleware.ts). Without it, auth state is never populated. It fails silently.
  • MUSTSet WORKOS_COOKIE_PASSWORD to 32+ characters. Shorter values cause cryptic runtime errors.
  • MUSTEnsure WORKOS_REDIRECT_URI matches the redirect URI configured in the WorkOS dashboard exactly, including trailing slashes.
  • MUSTUse the correct env prefix for your build tool: NEXT_PUBLIC_ for Next.js, VITE_ for Vite, REACT_APP_ for CRA.
  • SHOULDUse await createClient() — it's async. Missing await returns a Promise, not a client.
  • SHOULDUse withAuth() for page-level protection instead of manual redirect logic.
  • NEVERUse authLoader for fetching user data. It's only for handling OAuth callbacks.

Further Reading

For complete patterns, code examples, and anti-patterns, see references/authentication.md.