Skip to content
The Handover

Services

Clerk

What we tell an AI agent working on a project that uses Clerk —2 rules, 1 from cases others reported.

Build a rootnote set for a Clerk projectPlain text

Clerk publishes its own file for agents — clerk.com/llms.txt. That is what the tool is and where its documentation lives. This page is the other half: where it catches agents out. Why both.

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 it is not repeated here:

  • Sign-in: verify on the server, never trust the client, never log a token

All of it is included when you build a set.

Auth.jsSupabaseCloudflare Access