Astro Middleware vs. Adapter Static Asset Serving: Auth Bypass Risk in Hybrid Rendering

Middleware Execution Boundaries

No deployment adapter guarantees middleware execution for every single request path. By design, Astro separates the application runtime from the static asset server. Assets located in the public/ directory are served directly by the adapter (or the underlying CDN/web server), bypassing the Astro middleware pipeline entirely. Similarly, in output: 'hybrid' mode, pages marked with export const prerender = true are generated as static HTML files at build time; these are served as static assets and do not trigger server-side middleware during runtime requests.

Likely Explanations for Bypass Behavior

The divergence in behavior stems from the architectural goal of maximizing performance. Serving a static file from a CDN or a filesystem is significantly faster than booting a server-side function to execute middleware. Consequently, the "Integration Boundary" is a hard line: if the adapter identifies a request as a static file (whether from public/ or a prerendered route), it fulfills the request before the Astro runtime is ever invoked.

Implementation Patterns for Asset Exclusion

Because there is no declarative configuration to "opt-in" static assets to middleware, developers must handle exclusion logic within the middleware function itself. To avoid hardcoding exhaustive lists, use pattern matching against the request.url:

export const onRequest = defineMiddleware(({ request }, next) => {
  const url = new URL(request.url);
  
  // Exclude common static asset extensions or the /favicon.ico path
  if (url.pathname.includes('.') || url.pathname.startsWith('/_astro')) {
    return next();
  }

  // Perform auth checks for remaining routes
  return handleAuth(request, next);
});

Documentation Guidelines for Library Authors

Since Astro lacks a stable protected route convention, library authors should document security requirements using a "Shared Responsibility Model":

• Explicit Warning: State clearly that middleware does not protect the public/ directory or prerendered pages.
• Verification Step: Advise users to verify their security boundary by attempting to access a dummy file in public/ while unauthenticated.
• Client-Side Fallbacks: Recommend implementing client-side guards (e.g., useEffect or onMount checks) for prerendered pages that require a session, while emphasizing that this is for UX, not hard security.

Verification and Diagnostics

To confirm if your current adapter is bypassing middleware for specific routes, add a temporary logging statement to your middleware and test the following:

1. Request a file in public/ (e.g., /robots.txt).
2. Request a page with prerender = true.
3. Request a standard SSR page.

If the log does not appear for the first two, your adapter is serving them statically.

Missing Diagnostic: To provide a more specific adapter recommendation, please specify if you are using a Node-based server or an Edge-based provider (Vercel, Netlify, Cloudflare).