> Clerk: what your AI agent should know — from The Handover, the-handover.org/services/clerk
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence

# Clerk

What we tell an AI agent working on a project that uses Clerk: 2 rules, 0 learned the hard way.

Build a full rootnote set for a Clerk project: https://the-handover.org/build?areas=working-agreement,auth&auth=clerk

The vendor's own file for agents (what Clerk is, where its documentation lives): https://clerk.com/llms.txt. This page covers where it catches agents out.

### Clerk and Auth.js on Next.js: middleware is not where the sign-in check ends

> Reported by Next.js (Vercel); reported by Rachid Allam and Yassir Alam, "Authorization Bypass in Next.js Middleware (CVE-2025-29927)" — github.com/vercel/next.js/security/advisories/GHSA-f82v-jwr5-mffw; Ty Sbano, Vercel, "Postmortem on Next.js Middleware bypass" — vercel.com/blog/postmortem-on-next-js-middleware-bypass; Colin Sidoti and Braden Sidoti, Clerk, "Next.js CVE-2025-29927" — clerk.com/blog/cve-2025-29927; Auth.js, "Protecting Resources" — authjs.dev/getting-started/session-management/protecting · distilled by Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-24

Applies when the project uses Next.js. In March 2025, Next.js disclosed that a
single request header could make a self-hosted app skip its middleware entirely.
Any sign-in check that lived only in middleware was skipped with it. Apps run with
`next start` or `output: 'standalone'` were affected. Vercel, Netlify and
Cloudflare Workers were not. Clerk first said on X that no Clerk app was affected,
and retracted that in a post on 23 March: apps were exposed if middleware was
their only check on a route, or if they ran `@clerk/nextjs` older than 5.2.

The lesson outlived the patch. Vercel's post-mortem says it does not recommend
middleware as the sole method of protecting routes. Auth.js's documentation says
not to rely on it exclusively, and to verify the session as close to the data as
possible. Since Next.js 16 the file is called `proxy.ts`; the advice is the same.

- **Check the session in the page, route handler or server action that reads the
  data**, not only in middleware or `proxy.ts`. With Clerk that means calling
  `auth()`, `currentUser()` or `protect()` there; with Auth.js, `auth()`.
- **Treat middleware as an early redirect, not as the check itself.** A route that
  is safe only because middleware ran is not safe.
- **Keep `next` on a supported, patched release.** The fixes were 15.2.3,
  14.2.25, 13.5.9 and 12.3.5.

### Clerk: the publishable key is public, the secret key never leaves the server

> General guidance · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-19

- **The publishable key is public by design; the secret key never reaches the
  browser, a log or a fixture.**
- **Verify the session on the server for every protected request.** A signed-in
  interface is not authorisation for an API call.
- **Verify the signature on every Clerk webhook before acting on it.**

Also applies to every sign-in choice, so not repeated here: Sign-in: verify on the server, never trust the client, never log a token.