War Story: A Next.js 15 Middleware Bug Exposed Admin Routes to Unauthenticated Users for 2 Hours

// middleware.ts - Next.js 15.0.2 (BUGGY VERSION)
// This file was intended to protect all /admin/* routes with JWT authentication
// Regression in Next.js 15.0.0-15.0.3 caused matcher to fail for nested paths
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import jwt from 'jsonwebtoken';

// Environment variable validation - fail fast if missing
if (!process.env.JWT_SECRET) {
  throw new Error('JWT_SECRET environment variable is not set');
}

const JWT_SECRET = process.env.JWT_SECRET;

// Matcher config: intended to match all /admin/* routes, including nested paths
// BUG: Next.js 15.0.2 glob expansion incorrectly handles /admin/:path* matcher
// when combined with other matchers, causing this middleware to never execute
export const config = {
  matcher: [
    '/admin/:path*', // Intended to match /admin, /admin/dashboard, /admin/users/edit/123
    '/api/admin/:path*', // Admin API routes
  ],
};

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Log incoming request for debugging (redact sensitive data in production!)
  console.log(`[Middleware] Processing request to ${pathname}`);

  // Extract JWT from Authorization header (Bearer token)
  const authHeader = request.headers.get('authorization');
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    console.warn(`[Middleware] Missing or invalid Authorization header for ${pathname}`);
    return NextResponse.redirect(new URL('/login', request.url));
  }

  const token = authHeader.split(' ')[1];
  if (!token) {
    console.warn(`[Middleware] Empty token for ${pathname}`);
    return NextResponse.redirect(new URL('/login', request.url));
  }

  try {
    // Verify JWT with explicit algorithm allowlist to prevent algorithm confusion attacks
    const decoded = jwt.verify(token, JWT_SECRET, {
      algorithms: ['HS256'],
      issuer: 'urn:myapp:auth',
      audience: 'urn:myapp:admin',
    }) as { userId: string; role: string };

    // Check if user has admin role
    if (decoded.role !== 'admin') {
      console.warn(`[Middleware] Non-admin user ${decoded.userId} attempted to access ${pathname}`);
      return NextResponse.redirect(new URL('/unauthorized', request.url));
    }

    // Attach user info to request headers for downstream handlers
    const response = NextResponse.next();
    response.headers.set('x-user-id', decoded.userId);
    response.headers.set('x-user-role', decoded.role);
    return response;
  } catch (error) {
    // Handle JWT verification errors explicitly
    if (error instanceof jwt.TokenExpiredError) {
      console.warn(`[Middleware] Expired token for ${pathname}`);
      return NextResponse.redirect(new URL('/login?error=token_expired', request.url));
    }
    if (error instanceof jwt.JsonWebTokenError) {
      console.warn(`[Middleware] Invalid token for ${pathname}: ${error.message}`);
      return NextResponse.redirect(new URL('/login?error=invalid_token', request.url));
    }
    // Catch-all for unexpected errors
    console.error(`[Middleware] Unexpected error verifying token for ${pathname}:`, error);
    return NextResponse.redirect(new URL('/login?error=server_error', request.url));
  }
}

// middleware.ts - Next.js 15.0.4 (PATCHED VERSION)
// Fixed matcher config and added additional safety checks to prevent auth bypass
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import jwt from 'jsonwebtoken';

// Strict environment variable validation at module load
const requiredEnvVars = ['JWT_SECRET', 'AUTH_ISSUER', 'AUTH_AUDIENCE'];
for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
}

const JWT_SECRET = process.env.JWT_SECRET!;
const AUTH_ISSUER = process.env.AUTH_ISSUER!;
const AUTH_AUDIENCE = process.env.AUTH_AUDIENCE!;

// Helper function to create redirect responses with consistent error logging
function createAuthRedirect(request: NextRequest, path: string, reason: string) {
  console.warn(`[Middleware] Auth redirect for ${request.nextUrl.pathname}: ${reason}`);
  const redirectUrl = new URL(path, request.url);
  redirectUrl.searchParams.set('error', reason);
  return NextResponse.redirect(redirectUrl);
}

// FIXED: Matcher config uses explicit path arrays instead of glob wildcards
// Next.js 15.0.4 correctly handles array-based matchers for nested paths
export const config = {
  matcher: [
    // Explicitly list all admin route prefixes to avoid glob expansion bugs
    '/admin',
    '/admin/:path*',
    '/api/admin',
    '/api/admin/:path*',
  ],
};

// Pre-compile JWT verify options to avoid recreation on each request
const JWT_VERIFY_OPTIONS = {
  algorithms: ['HS256'] as const,
  issuer: AUTH_ISSUER,
  audience: AUTH_AUDIENCE,
};

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Skip middleware for OPTIONS requests (CORS preflight)
  if (request.method === 'OPTIONS') {
    return NextResponse.next();
  }

  // Log request with truncated path for PII protection
  const truncatedPath = pathname.length > 50 ? `${pathname.slice(0, 47)}...` : pathname;
  console.log(`[Middleware] Processing ${request.method} request to ${truncatedPath}`);

  // Check for Authorization header
  const authHeader = request.headers.get('authorization');
  if (!authHeader) {
    return createAuthRedirect(request, '/login', 'missing_auth_header');
  }

  // Validate Bearer token format
  const [scheme, token] = authHeader.split(' ');
  if (scheme?.toLowerCase() !== 'bearer' || !token) {
    return createAuthRedirect(request, '/login', 'invalid_auth_scheme');
  }

  try {
    // Verify JWT with pre-compiled options
    const decoded = jwt.verify(token, JWT_SECRET, JWT_VERIFY_OPTIONS) as {
      userId: string;
      role: string;
      permissions: string[];
    };

    // Additional role check: ensure user has at least one admin permission
    const hasAdminPermission = decoded.permissions.some((p) => p.startsWith('admin:'));
    if (!hasAdminPermission) {
      return createAuthRedirect(request, '/unauthorized', 'insufficient_permissions');
    }

    // Attach user context to request headers for downstream handlers
    const response = NextResponse.next();
    response.headers.set('x-user-id', decoded.userId);
    response.headers.set('x-user-role', decoded.role);
    response.headers.set('x-user-permissions', JSON.stringify(decoded.permissions));
    // Add cache control header to prevent middleware responses from being cached
    response.headers.set('cache-control', 'no-store, max-age=0');
    return response;
  } catch (error) {
    // Explicit error type handling
    if (error instanceof jwt.TokenExpiredError) {
      return createAuthRedirect(request, '/login', 'token_expired');
    }
    if (error instanceof jwt.JsonWebTokenError) {
      return createAuthRedirect(request, '/login', 'invalid_token');
    }
    if (error instanceof jwt.NotBeforeError) {
      return createAuthRedirect(request, '/login', 'token_not_active');
    }
    // Log unexpected errors and return generic server error
    console.error(`[Middleware] Unexpected error for ${pathname}:`, error);
    return createAuthRedirect(request, '/error', 'server_error');
  }
}

// middleware.integration.test.ts - Jest integration tests for admin route protection
// Uses Next.js 15 test utilities to simulate requests and validate middleware behavior
import { NextResponse } from 'next/server';
import { middleware, config } from '../middleware';
import type { NextRequest } from 'next/server';
import jwt from 'jsonwebtoken';

// Mock jwt module to avoid needing real secrets in tests
jest.mock('jsonwebtoken');
const mockedJwt = jwt as jest.Mocked;

// Test constants
const TEST_JWT_SECRET = 'test-secret-1234567890';
const TEST_ISSUER = 'urn:myapp:auth';
const TEST_AUDIENCE = 'urn:myapp:admin';

// Helper to create a mock NextRequest
function createMockRequest({
  pathname,
  method = 'GET',
  authHeader,
}: {
  pathname: string;
  method?: string;
  authHeader?: string;
}): NextRequest {
  const url = new URL(`http://localhost:3000${pathname}`);
  const headers = new Headers();
  if (authHeader) {
    headers.set('authorization', authHeader);
  }
  return new Request(url, { method, headers }) as NextRequest;
}

// Generate a valid test JWT
function generateTestToken(role: string = 'admin', permissions: string[] = ['admin:dashboard']) {
  return jwt.sign(
    { userId: 'test-user-123', role, permissions },
    TEST_JWT_SECRET,
    { issuer: TEST_ISSUER, audience: TEST_AUDIENCE, expiresIn: '1h' }
  );
}

describe('Admin Middleware Integration Tests', () => {
  // Reset mocks before each test
  beforeEach(() => {
    jest.resetAllMocks();
    process.env.JWT_SECRET = TEST_JWT_SECRET;
    process.env.AUTH_ISSUER = TEST_ISSUER;
    process.env.AUTH_AUDIENCE = TEST_AUDIENCE;
  });

  describe('Matcher Configuration', () => {
    it('should match all /admin/* nested paths', () => {
      const testPaths = [
        '/admin',
        '/admin/dashboard',
        '/admin/users',
        '/admin/users/edit/123',
        '/admin/billing/invoices/456',
      ];
      for (const path of testPaths) {
        const matcher = config.matcher as string[];
        const matches = matcher.some((pattern) => {
          // Simple matcher simulation (Next.js uses path-to-regexp internally)
          const regex = new RegExp(`^${pattern.replace(':path*', '.*')}$`);
          return regex.test(path);
        });
        expect(matches).toBe(true);
      }
    });

    it('should not match non-admin paths', () => {
      const testPaths = ['/', '/login', '/api/public/data', '/user/profile'];
      for (const path of testPaths) {
        const matcher = config.matcher as string[];
        const matches = matcher.some((pattern) => {
          const regex = new RegExp(`^${pattern.replace(':path*', '.*')}$`);
          return regex.test(path);
        });
        expect(matches).toBe(false);
      }
    });
  });

  describe('Authentication Checks', () => {
    it('should redirect unauthenticated requests to /login', async () => {
      const request = createMockRequest({ pathname: '/admin/dashboard' });
      const response = await middleware(request);
      expect(response).toBeInstanceOf(NextResponse);
      expect(response?.status).toBe(307); // Redirect status
      expect(response?.headers.get('location')).toContain('/login?error=missing_auth_header');
    });

    it('should allow authenticated admin users with valid JWT', async () => {
      const token = generateTestToken('admin', ['admin:dashboard']);
      mockedJwt.verify.mockReturnValue({
        userId: 'test-user-123',
        role: 'admin',
        permissions: ['admin:dashboard'],
      } as any);
      const request = createMockRequest({
        pathname: '/admin/dashboard',
        authHeader: `Bearer ${token}`,
      });
      const response = await middleware(request);
      expect(response?.status).toBe(200);
      expect(response?.headers.get('x-user-id')).toBe('test-user-123');
      expect(response?.headers.get('x-user-role')).toBe('admin');
    });

    it('should redirect non-admin users to /unauthorized', async () => {
      const token = generateTestToken('user', ['user:profile']);
      mockedJwt.verify.mockReturnValue({
        userId: 'test-user-456',
        role: 'user',
        permissions: ['user:profile'],
      } as any);
      const request = createMockRequest({
        pathname: '/admin/dashboard',
        authHeader: `Bearer ${token}`,
      });
      const response = await middleware(request);
      expect(response?.status).toBe(307);
      expect(response?.headers.get('location')).toContain('/unauthorized?error=insufficient_permissions');
    });

    it('should handle expired JWT tokens correctly', async () => {
      const token = 'expired-token';
      mockedJwt.verify.mockImplementation(() => {
        throw new jwt.TokenExpiredError('Token expired', new Date());
      });
      const request = createMockRequest({
        pathname: '/admin/dashboard',
        authHeader: `Bearer ${token}`,
      });
      const response = await middleware(request);
      expect(response?.status).toBe(307);
      expect(response?.headers.get('location')).toContain('/login?error=token_expired');
    });
  });
});

{
  \"dependencies\": {
    \"next\": \"15.0.4\", // Pinned to exact patch version, no ^ or ~
    \"react\": \"19.0.0\",
    \"react-dom\": \"19.0.0\"
  },
  \"devDependencies\": {
    \"@types/node\": \"22.0.0\",
    \"jest\": \"29.7.0\",
    \"typescript\": \"5.6.2\"
  }
}

# .github/workflows/middleware-tests.yml
name: Middleware Integration Tests
on: [pull_request]
jobs:
  test-middleware:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'npm'
      - run: npm ci
      - run: npm run test:middleware # Runs Jest with middleware test suite
        env:
          JWT_SECRET: test-secret-1234567890
          AUTH_ISSUER: urn:myapp:auth
          AUTH_AUDIENCE: urn:myapp:admin

import { trace, context } from '@opentelemetry/api';
const tracer = trace.getTracer('next-middleware');

export async function middleware(request: NextRequest) {
  const span = tracer.startSpan('middleware-execution', {
    attributes: {
      'http.method': request.method,
      'http.url': request.url,
      'middleware.type': 'admin-auth',
    },
  });
  return context.with(trace.setSpan(context.active(), span), async () => {
    try {
      // ... existing middleware logic ...
      span.setStatus({ code: 0 }); // OK
      return response;
    } catch (error) {
      span.setStatus({ code: 2, message: (error as Error).message }); // ERROR
      throw error;
    } finally {
      span.end();
    }
  });
}