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

# Auth.js

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

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

Auth.js published no file for agents when last checked; this page is the only agent-facing guidance for it we know of.

### 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.

### Auth.js: set the secret in production and keep it stable

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

- **Set the auth secret in production and never change it casually.** Changing it
  invalidates every session and signs everybody out.
- **Behind a proxy or a platform host, set the trusted host and canonical URL
  explicitly.** A wrong callback URL breaks sign-in only in production.
- **Choose session strategy deliberately.** A JWT session cannot be revoked on the
  server before it expires; a database session can.

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.