Next.js: analyze Server Actions, route groups/parallel routes, and layout-level auth inheritance

[bjcorder]

Problem

Modern Next.js (13+) apps concentrate sensitive mutations in Server Actions ('use server'), which AuthMap currently detects but does not analyze at all — arguably the largest single blind spot for the Next.js adapter, since these functions mutate data with no route-level auth in front of them. Additionally, route groups (group) and parallel routes @slot are standard App Router layout conventions, and auth enforced in a parent layout.tsx is a common protection pattern that is currently invisible.

Current behavior

• Files containing 'use server' emit nextjs_server_action_not_analyzed and return no routes or evidence (crates/authmap-adapters/src/nextjs.rs, early in analyze).
• route_path_for_file (crates/authmap-adapters/src/nextjs.rs) converts file paths to URL paths with no special handling for (group) or @slot segments.
• Auth helpers are recognized from a hardcoded list (NEXTJS_MIDDLEWARE_AUTH_HELPERS: getServerSession/auth/getAuth/currentUser/clerk/etc.); custom wrappers fall through.
• Layouts are not inspected; only route.ts handlers, pages/api/**, and middleware.ts matchers.

Proposed implementation

1. Server Actions
   • Inventory exported async functions in 'use server' files (and inline 'use server' function bodies) as routes of a new kind (e.g., kind: "server_action", method ACTION, path = module path + export name). This requires a route-kind/method extension in authmap-core — update schemas/ and docs/SCHEMA.md accordingly, and gate JSON consumers via the documented contract (docs/JSON_CONSUMERS.md).
   • Extract auth evidence from action bodies using the existing auth-helper rules (getServerSession, auth(), currentUser, clerk helpers...) — same matching used for route handlers; ORM mutation extraction (Prisma etc.) already works on function bodies, enabling action→mutation linking for free.
   • Replace nextjs_server_action_not_analyzed with per-action analysis; keep a diagnostic for dynamic/unresolvable action exports.
2. Route groups and parallel routes
   • In route_path_for_file: strip (group) segments from the URL path (they do not affect the URL) while retaining them in route metadata; strip @slot segments similarly and flag with a low-severity note. Add nextjs_unusual_route_segment coverage where conventions are ambiguous (intercepting routes (.), (..)).
3. Layout-level auth inheritance
   • When a layout.tsx in a segment (or a (group) directory) calls a recognized auth helper with a redirect/guard shape, emit inherited, lower-confidence evidence for routes and pages beneath that segment. Record the layout file in the evidence rationale so reviewers can verify.
4. Extensible auth-helper list
   • Allow config custom rules (crates/authmap-config) to extend NEXTJS_MIDDLEWARE_AUTH_HELPERS so projects with wrapper helpers (requireUser, withAuth) classify correctly without code changes. (Complements the cross-framework synonym work tracked separately.)

Acceptance criteria

• Server Action fixture (exported async fns + Prisma mutations, one guarded via getServerSession, one unguarded) produces action routes with correct classification and route→mutation links.
• Schema/docs updated for the new route kind; JSON consumers contract notes the addition.
• (marketing)/(app) route-group fixture produces correct URL paths; parallel-route fixture does not produce bogus paths.
• Layout guard fixture classifies child routes as guarded (lower confidence, layout cited).
• Config-extended helper name is honored by both middleware and handler classification.
• Unit tests + golden fixtures; docs/PARSERS_AND_ADAPTERS.md Next.js Not yet list and docs/DIAGNOSTICS.md updated; CHANGELOG entry.

References

• docs/PARSERS_AND_ADAPTERS.md Next.js limitations paragraph
• crates/authmap-adapters/src/nextjs.rs (route_path_for_file, NEXTJS_MIDDLEWARE_AUTH_HELPERS, server-action diagnostic emission)
• docs/SCHEMA.md, docs/JSON_CONSUMERS.md for the schema-impacting route kind