headershield

Audit HTTP headers in Node.js and Next.js.

headershield focuses on two things:

• response header audits like CSP, HSTS, cookies, and CORS
• request header inspection for spoofing, injection, CSRF, smuggling, and scanner traffic

Install

npm install headershield

Quick Start

Response headers

import { checkSecurityHeaders, getFailingFindings } from "headershield";

const report = checkSecurityHeaders({
  "Content-Security-Policy": "default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self'",
  "Strict-Transport-Security": "max-age=31536000; includeSubDomains; preload",
  "X-Content-Type-Options": "nosniff",
  "X-Frame-Options": "DENY",
  "Referrer-Policy": "strict-origin-when-cross-origin",
  "Permissions-Policy": "geolocation=(), camera=()",
});

console.log(report.ok);
console.log(report.score, report.maxScore);
console.log(getFailingFindings(report));

Request headers

import { inspectRequestHeaders } from "headershield";

const report = inspectRequestHeaders(
  {
    Cookie: "session=abc123",
    Origin: "https://app.example.com",
    Referer: "https://app.example.com/profile",
    "X-CSRF-Token": "token-123456",
    "User-Agent": "Mozilla/5.0",
  },
  {
    method: "POST",
    trustedOrigins: ["https://app.example.com"],
  },
);

console.log(report.riskLevel);
console.log(report.suggestedAction);
console.log(report.findings);

Common Use Cases

Next.js middleware

import { NextResponse } from "next/server";
import { decideNextRequest } from "headershield";

export function middleware(request: Request) {
  const decision = decideNextRequest(request, {
    trustedOrigins: ["https://app.example.com"],
  });

  if (decision.action === "block") {
    return new NextResponse("Forbidden", {
      status: decision.status,
      headers: decision.responseHeaders,
    });
  }

  if (decision.action === "challenge") {
    return new NextResponse("Too Many Suspicious Signals", {
      status: decision.status,
      headers: decision.responseHeaders,
    });
  }

  return NextResponse.next();
}

Next.js route handler

import { NextRequest, NextResponse } from "next/server";
import { decideNextRequestAuto } from "headershield";

export async function GET(request: NextRequest) {
  const decision = await decideNextRequestAuto(request, {
    decision: {
      blockOnCategories: ["smuggling", "traversal", "injection"],
    },
  });

  return NextResponse.json({
    action: decision.action,
    risk: decision.report.riskLevel,
  });
}

Response + cookies + CORS together

import { cookiePlugin, corsPlugin, createHeaderInspector } from "headershield";

const result = createHeaderInspector()
  .use(cookiePlugin)
  .use(corsPlugin)
  .checkResponseHeaders({
    "Content-Security-Policy": "default-src 'self'",
    "Set-Cookie": "session=abc123; Secure; HttpOnly; SameSite=Lax; Path=/",
    "Access-Control-Allow-Origin": "https://app.example.com",
  })
  .result();

console.log(result.response);
console.log(result.cookies);
console.log(result.cors);

Summaries for logs or CI

import {
  createHeaderInspector,
  collectFindings,
  formatFindingSummary,
  summarizeFindings,
} from "headershield";

const result = createHeaderInspector()
  .checkResponseHeaders({
    "Content-Security-Policy": "default-src * 'unsafe-inline'",
  })
  .checkRequestHeaders(
    {
      Origin: "https://app.example",
      "Sec-Fetch-Site": "cross-site",
    },
    {
      method: "POST",
      trustedOrigins: ["https://app.example.com"],
    },
  )
  .result();

const findings = collectFindings(result);
const summary = summarizeFindings(result);

console.log(findings.length);
console.log(summary.errors, summary.warnings);
console.log(formatFindingSummary(summary));

Automatic Rules

Use automatic helpers when you want headershield to fetch remote rules for you:

import { inspectRequestHeadersAuto, checkSecurityHeadersAuto } from "headershield";

const requestReport = await inspectRequestHeadersAuto({
  "User-Agent": "BadCrawler/1.0",
});

const responseReport = await checkSecurityHeadersAuto({
  "Content-Security-Policy": "default-src 'self'",
});

Notes:

• remote rules are cached in memory
• fetch failures fall back to the last successful cached ruleset
• loadRemoteRuleSet() supports JSON, ESM, and simple TypeScript module responses in Node.js

Main Exports

Core checks

• checkSecurityHeaders(headers, options?)
• inspectRequestHeaders(headers, options?)
• checkCookies(headers, options?)
• checkCorsHeaders(headers, options?)

Helpers

• getFailingFindings(report)
• getSuspiciousRequestFindings(report)
• getSuggestedRequestAction(report, options?)
• decideRequestAction(findings, options?)
• normalizeHeaders(headers)

Next.js helpers

• analyzeNextRequest(request, options?)
• decideNextRequest(request, options?)
• analyzeNextRequestAuto(request, options?)
• decideNextRequestAuto(request, options?)
• withNextRequestShield(request, handlers, options?)
• withNextRequestShieldAuto(request, handlers, options?)
• analyzeNextResponse(response, options?)
• getNextResponseReportHeaders(report, options?)

Remote rules

• compileRemoteRuleSet(ruleSet)
• getRemoteRules(options?)
• refreshRemoteRules(options?)
• clearRemoteRuleCache(url?)
• inspectRequestHeadersAuto(headers, options?)
• checkSecurityHeadersAuto(headers, options?)

Inspector API

• createHeaderInspector()
• cookiePlugin
• corsPlugin

What Gets Checked

Response side

• CSP, HSTS, X-Content-Type-Options, X-Frame-Options
• Referrer-Policy, Permissions-Policy
• Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy
• cookie flags like Secure, HttpOnly, SameSite, __Host-, __Secure-
• risky CORS combinations like wildcard origins with credentials

Request side

• CRLF and header injection markers
• SQLi, XSS, traversal, command injection, and template injection patterns
• CSRF-related risk signals for state-changing requests
• request smuggling hints around Content-Length and Transfer-Encoding
• suspicious forwarding headers like localhost or metadata IPs
• common scanner user agents like sqlmap, nikto, and nmap

Development

npm run build
npm test