Central vs per-route token validation in Astro middleware for expired credentials

Answer

Use central token expiry validation in src/middleware.ts for all SSR routes and Astro endpoints, and keep per-route authorization only. Attach a minimal identity to context.locals in middleware. That gives uniform rejection of expired credentials for SSR pages and endpoints while preserving least-privilege, because routes never re-validate expiry, only scope access using the minimal identity.

For mixed static + SSR output, treat prerendered pages as a build-time boundary: any route with prerender: true must be public or guarded client-side. Document that explicitly. Central middleware alone does not protect prerendered pages.

Confirmed facts

• Astro has no built-in authentication.
• Middleware in src/middleware.ts runs only for SSR-rendered routes and API endpoints, not for prerendered static pages.
• Middleware can validate a session/token, return a Response for 401/403, and attach data to context.locals.
• Endpoints can return raw Response objects.
• Static prerendered pages do not execute middleware per request.

Likely explanation and recommended pattern

Central expiry enforcement is the reliable way to ensure uniform rejection. Per-route expiry checks create inconsistency and drift.

A hybrid is least-privilege compatible:

1. Middleware: parse token, check expiry and signature, return 401/403 immediately on failure. On success, set context.locals.user = { userId, role } only. No full profile.
2. Route handler / endpoint: assume expiry already checked. Use context.locals.user for fine-grained authorization, e.g., role or resource ownership.
3. Prerendered routes: disable prerendering for protected pages, or add a client-side auth guard that redirects when the token is missing/expired. Document this as a routing rule.

Attaching a minimal identity removes the need for per-route expiry re-checks for SSR routes, because expiry is guaranteed by middleware before the handler runs. Per-route checks remain only for authorization scope, not authentication validity.

Documentation for mixed output

• Mark any auth-protected page as SSR: do not set export const prerender = true.
• If a page must be prerendered, declare it public in docs and add a client-side check that mirrors the server 401 behavior.
• Document the contract: context.locals.user is present only after successful central validation; handlers must not assume it exists for prerendered routes.

Verification steps

• Create a short-lived test token, request an SSR page after expiry, assert 401/403 and no user in locals.
• Inspect context.locals in a handler to confirm only userId and role are present.
• Build with astro build and serve output, request a prerendered protected page with an expired cookie; confirm static HTML is served, demonstrating the middleware gap.

Missing diagnostic detail that would change the recommendation: are the protected pages currently configured with prerender: true or served via static output? If yes, central middleware cannot protect them and a client-side guard or SSR switch is required.