header-middleware-next/src/utils/checkUserAgent.js

A lightweight and flexible middleware utility for managing HTTP headers in Next.js applications. Supports header extraction, transformation, masking, and safe injection for Edge and API routes.

/**
 * Function to analyze and categorize the User-Agent header from an HTTP request.
 * It detects if the User-Agent belongs to common command-line clients, bots, browsers, or is unknown.
 *
 * @param {Object} req - The HTTP request object containing headers.
 * @returns {Object} - An object indicating the type, name, message, and meta information with User-Agent and category.
 */
export default async function checkUserAgent(req) {
  // Retrieve and trim the User-Agent header; default to empty string if missing.
  const ua = req.headers?.['user-agent']?.trim() || '';

  // Handle missing User-Agent header with a warning response.
  if (!ua) {
    return {
      type: 'warning',
      name: 'User-Agent',
      message: 'Missing User-Agent header',
      meta: {
        'user-agent': '',
        category: 'missing'
      }
    };
  }

  // Convert User-Agent string to lowercase for case-insensitive checks.
  const uaLower = ua.toLowerCase();

  /**
   * Regular expressions to identify common command-line HTTP clients.
   * These clients are often used for scripting, automation, or testing.
   */
  const cliUserAgents = [
    /curl/i,
    /wget/i,
    /httpie/i,
    /python-requests/i,
    /java/i,
    /libwww-perl/i
  ];

  /**
   * Keywords frequently found in bot or crawler User-Agent strings.
   * Detecting these helps identify automated traffic that may require special handling.
   */
  const botKeywords = ['bot', 'crawler', 'spider', 'scrapy', 'fetch'];

  // Determine if the User-Agent matches any known command-line client patterns.
  const isCLI = cliUserAgents.some(re => re.test(ua));

  // Check if the User-Agent string contains any common bot keywords.
  const isBot = botKeywords.some(kw => uaLower.includes(kw));

  // If User-Agent is identified as a command-line client, return an error type response.
  if (isCLI) {
    return {
      type: 'error',
      name: 'User-Agent',
      message: `Command-line client detected: ${ua}`,
      meta: {
        'user-agent': ua,
        category: 'cli'
      }
    };
  }

  // If User-Agent is recognized as a potential bot, return an error type response.
  if (isBot) {
    return {
      type: 'error',
      name: 'User-Agent',
      message: `Potential bot detected: ${ua}`,
      meta: {
        'user-agent': ua,
        category: 'bot'
      }
    };
  }

  /**
   * Basic browser User-Agent pattern matching.
   * This is a simplified approach and may not cover all browser variations.
   */
  const isBrowserUA = /mozilla\/|chrome\/|safari\/|firefox\/|edg\//i.test(ua);

  // Return success if User-Agent is recognized as a common browser.
  if (isBrowserUA) {
    return {
      type: 'success',
      name: 'User-Agent',
      message: 'Valid browser User-Agent',
      meta: {
        'user-agent': ua,
        category: 'browser'
      }
    };
  }

  // If User-Agent does not match any known patterns, return informational response.
  return {
    type: 'info',
    name: 'User-Agent',
    message: `Unrecognized User-Agent format: ${ua}`,
    meta: {
      'user-agent': ua,
      category: 'unknown'
    }
  };
}