Nuxt 3 Server‑Side Middleware: A Minimal, Secure Route‑Protection Blueprint

Problem & Takeaway

When building a Nuxt 3 application that renders pages on the server, the simplest way to keep sensitive routes hidden from unauthenticated users is to use a global server‑side middleware that checks an HTTP‑only cookie before rendering. This approach guarantees that no protected content ever reaches the browser unless the user has a valid token, and it keeps the authentication logic out of the client bundle.

Requirements

• Nuxt 3 project with SSR enabled (not fully static or client‑side only).
• Authentication provider that issues a signed JWT or opaque token.
• Secure, HTTP‑only, SameSite cookie named auth_token.
• Environment variables for AUTH_SECRET (token signing key) and AUTH_COOKIE_NAME.
• Basic logging library (e.g., pino) for audit trails.

Smallest Suitable Design

The minimal architecture uses a single global middleware file, middleware/auth.ts, that runs on every request. The middleware performs these steps:

1. Read the auth_token cookie from the incoming request.
2. Verify the token’s signature and expiry against AUTH_SECRET.
3. If valid, attach the decoded payload to event.context.auth for downstream use.
4. If invalid or missing, redirect to /login (or return 401 if the request is an API call).

This single file satisfies route protection for all SSR pages without adding per‑page guards or client‑side checks. The design is minimal because it leverages Nuxt’s built‑in middleware system and the browser’s cookie handling.

Trust & Data Boundaries

Key boundaries:

• Client‑to‑Server: The token is stored in an HTTP‑only cookie, so JavaScript cannot read it, preventing XSS‑based token theft.
• Server‑to‑Auth Service: Token validation is performed against a trusted secret or public key. The secret must never leave the server environment.
• Server‑to‑Client: Only the middleware decides whether to render the page or redirect. No sensitive data is exposed in the rendered HTML unless the user is authenticated.

Operational Checks

To keep the system reliable, implement the following checks:

Check	What to Verify	How to Verify
Authentication Failure Logging	All failed token validations are logged with IP and user agent.	Review logs for patterns; use a log aggregator.
Token Expiry Monitoring	Expired tokens trigger a 401 or redirect.	Send a request with a known expired token and confirm the response.
Latency Measurement	Middleware adds < 50 ms to request time.	Use a simple Node script to benchmark the middleware on a test server.
Environment Variable Presence	Required env vars are defined.	Run npm run dev and check for startup errors.

Failure Modes & Mitigation

• Missing Cookie: User sees the login page. Mitigation: clear any stale cookies before redirect.
• Invalid Signature: Token tampering detected; redirect to /login. Mitigation: rotate AUTH_SECRET regularly and invalidate old tokens.
• **Token Replay**: If the same token is reused after logout, it remains valid until expiry. Mitigation: implement a token revocation list or short token lifespan.
• **Serverless Cold Start**: Middleware may add latency on cold starts. Mitigation: keep the validation logic lightweight and cache public keys if using asymmetric signing.

When the Design Needs to Change

Consider altering the architecture under these conditions:

• Fully Static Deployment: If the app is deployed to a static CDN, server‑side middleware cannot run. Switch to client‑side route guards with a composable that reads a token from document.cookie or localStorage.
• High Traffic / Serverless Constraints: If latency becomes a bottleneck, move token validation to a dedicated auth gateway or use JWT verification libraries that support caching.
• Multi‑Tenant Auth: When different tenants require separate secrets, the middleware must route validation based on a tenant identifier in the cookie.
• API‑First Architecture: For pure API routes, replace redirects with JSON error responses (status 401) and move validation to a separate auth.api.ts middleware.

Concrete Example

Below is a minimal middleware/auth.ts implementation. Run it on the server side (Nuxt will automatically detect it as global middleware).

// middleware/auth.ts
import { defineNuxtMiddleware } from '#app'
import { verify } from 'jsonwebtoken'

export default defineNuxtMiddleware((event) => {
  const tokenName = process.env.AUTH_COOKIE_NAME || 'auth_token'
  const token = event.node.req.headers.cookie?.split('; ').find(c => c.startsWith(`${tokenName}=`))?.split('=')[1]

  if (!token) {
    // API request: 401
    if (event.res?.statusCode === 200) {
      event.res.statusCode = 401
      event.res.end('Unauthorized')
      return
    }
    // SSR request: redirect
    event.res.writeHead(302, { Location: '/login' })
    event.res.end()
    return
  }

  try {
    const payload = verify(token, process.env.AUTH_SECRET as string)
    // Attach to context for downstream use
    event.context.auth = payload
  } catch (e) {
    // Invalid token
    event.res.writeHead(302, { Location: '/login' })
    event.res.end()
  }
})

**Verification Steps**

1. Start the dev server: npm run dev.
2. Open http://localhost:3000/protected without a cookie – you should be redirected to /login.
3. Set a valid cookie manually in the browser DevTools (Name: auth_token, Value: <valid JWT>, HttpOnly: unchecked, SameSite: Lax).
4. Refresh the page – the protected content should render.
5. Expire the token (change its exp claim) and repeat – the middleware should redirect again.

**Performance Check**: Run a simple benchmark script that sends 1000 requests to the protected route and calculates average latency. Ensure it stays under your threshold.

Conclusion

Using a global server‑side middleware in Nuxt 3 with an HTTP‑only SameSite cookie gives you a lean, secure route‑protection mechanism that works out of the box for SSR applications. Keep the token short‑lived, rotate secrets, and monitor logs to detect abuse. If your deployment model shifts (static, serverless, API‑first), revisit the design to match the new constraints.