Skip to content
Hidden Logic Lab

Review Next.js middleware auth before merge

Cursor or Claude Code applies a SKILL.md on middleware/proxy PRs: public path allowlists, matcher gaps, header spoofing, redirect loops, and missing session checks — with merge-blocking findings.

·Coding·40 min·Deep

A middleware-auth SKILL.md linked from AGENTS.md, a PR comment mapping protected routes to checks, and no new bypass paths merged as refactors.

  1. 1

    Run the skill on a middleware-heavy PR

    Include a route rename or new app/api handler. The skill should catch matcher gaps your manual review misses.

  2. 2

    Document public routes beside the skill

    Maintain a single list of intentionally public paths. The agent compares PR diffs against that list, not memory.

  3. 3

    Add an unauthenticated smoke test

    One test or script that curls protected URLs without cookies and expects 401/302 to login. Wire the skill to require that test green when middleware changes.

The prompt to paste

Write SKILL.md for reviewing Next.js middleware (or proxy.ts in newer layouts) before merge. Focus on auth bypass, not general performance tuning.

Repository context:
[middleware file path: middleware.ts, src/middleware.ts, or proxy.ts]
[auth provider: NextAuth, Clerk, Auth0, custom JWT — names only]
[public routes policy: which paths must stay unauthenticated]
[Next.js version and whether App Router, Pages Router, or both]

PR context (paste when using):
[PR link, changed files, list of new or renamed routes]

SKILL.md must include:
1. Purpose — middleware is the outer gate; a gap here exposes admin and account routes without hitting server components.
2. When to use — any PR touching middleware/proxy, matcher config, auth helpers used only in middleware, or route renames that might fall outside the matcher. When not to use — client-only UI with no routing or auth changes.
3. Hard rules for findings:
   - Block: protected paths missing from auth check (matcher too narrow or allowlist too broad); trusting x-forwarded-* or x-middleware-subrequest without framework guardrails (include CVE-style middleware skip via forged internal headers where applicable); session read without signature/secret verification; redirect to login that loops on the login path; API routes with sensitive handlers excluded from middleware matcher.
   - Warn: public prefix allowlist using startsWith that also exposes sibling paths (e.g. /api/public vs /api/public-admin); copying session from cookie without httpOnly/secure flags review; edge vs node runtime split where one path skips checks; matcher regex that omits new dynamic segments.
   - Note: matcher performance, logging verbosity — never block on style alone.
4. Review steps the agent must execute:
   - Export matcher config and list every path pattern; compare to app directory or pages tree for routes not covered.
   - Trace auth decision: which cookie/header/token is read, where validated, and what happens on failure (redirect URL, status code).
   - Map public allowlist entries to actual routes; flag overly broad globs.
   - Check for header-based bypass: internal request headers, middleware skip flags, or custom bypass env readable in edge.
   - Follow redirect chains for unauthenticated users; detect loops and open redirects via next= query params.
   - Confirm server actions and route handlers still enforce auth if middleware is best-effort only [state team pattern or placeholder].
5. PR comment template: protected route table (path — middleware applies? — session check? — notes), findings by severity, merge recommendation.
6. Safe patterns section: default-deny with explicit public list; duplicate session check in route handler for high-risk mutations.
7. Two example prompts: add /dashboard route vs widen public allowlist for /api/webhooks.
8. Pitfalls: assuming layout.tsx auth replaces middleware, testing only logged-in happy path, matcher copied from docs without repo-specific routes, ignoring Route Handlers under app/api.
9. Done means: every Block resolved, Warns acknowledged by someone who knows auth, no session secrets pasted in review, redirect targets validated.

Rules:
- Do not invent route paths; use only repo tree or PR paste.
- Do not suggest disabling auth to debug locally in the merged code path.
- Output only SKILL.md markdown.

Forged internal middleware headers have been used to skip auth entirely. The skill must Block header-trust patterns unless your Next.js version and config explicitly prevent skip attacks.

Sample case written by Hidden Logic Lab. Not affiliated with Cursor or Claude Code.

More in Coding

Get new cases in your inbox

Weekly notes on new use cases and agent workflows. No product pitches.

Occasional notes on new cases. No product pitches in the first note.