header-grader 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import { H as Headers, R as Report, a as Rule, S as ScanContext, C as CheckResult, G as Grade } from './middleware-BsJGVvzp.js';
+export { M as MiddlewareOptions, b as Status, h as headerGrader } from './middleware-BsJGVvzp.js';
+import 'node:http';
+
+declare function isLocalHttpUrl(url: URL): boolean;
+/** Grade a set of already-collected headers (used by the middleware and tests). */
+declare function gradeHeaders(headers: Headers, opts?: {
+    url?: string;
+    isLocalHttp?: boolean;
+}): Report;
+/** Fetch a URL and grade its response headers. */
+declare function scan(rawUrl: string, opts?: {
+    timeoutMs?: number;
+}): Promise<Report>;
+
+/**
+ * Recommended values used both for grading hints and for the config
+ * generators, so the report and the generated snippets always agree.
+ */
+declare const RECOMMENDED: {
+    readonly "Content-Security-Policy": "default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'self'";
+    readonly "Strict-Transport-Security": "max-age=31536000; includeSubDomains";
+    readonly "X-Content-Type-Options": "nosniff";
+    readonly "X-Frame-Options": "SAMEORIGIN";
+    readonly "Referrer-Policy": "strict-origin-when-cross-origin";
+    readonly "Permissions-Policy": "camera=(), microphone=(), geolocation=()";
+    readonly "Cross-Origin-Opener-Policy": "same-origin";
+    readonly "Cross-Origin-Resource-Policy": "same-origin";
+};
+/**
+ * Concrete attack scenarios, keyed by header. Attached to any check that
+ * doesn't pass, so the report can teach *why* the header matters, not just
+ * that it's missing. Shown by `--explain` and always present in JSON output.
+ */
+declare const EXPLOITS: Record<string, string>;
+declare const rules: Rule[];
+declare function runRules(ctx: ScanContext): CheckResult[];
+
+declare function scoreOf(results: CheckResult[]): number;
+declare function gradeOf(score: number): Grade;
+/** True if `actual` is at least as good as `minimum`. */
+declare function meetsGrade(actual: Grade, minimum: Grade): boolean;
+declare function isGrade(value: string): value is Grade;
+
+interface FormatOptions {
+    /** Include the concrete attack scenario under each failing header. */
+    explain?: boolean;
+}
+declare function formatReport(report: Report, options?: FormatOptions): string;
+
+/**
+ * Generate an Express (helmet) snippet that fixes everything the report
+ * flagged. Only includes config for headers that aren't already passing,
+ * so the snippet is a minimal diff against the user's current setup.
+ */
+declare function generateExpress(report: Report): string;
+
+/**
+ * Generate an nginx `server {}` block fragment that fixes everything the
+ * report flagged. `always` makes the headers apply to error responses too.
+ */
+declare function generateNginx(report: Report): string;
+
+export { CheckResult, EXPLOITS, type FormatOptions, Grade, Headers, RECOMMENDED, Report, Rule, ScanContext, formatReport, generateExpress, generateNginx, gradeHeaders, gradeOf, isGrade, isLocalHttpUrl, meetsGrade, rules, runRules, scan, scoreOf };

package/dist/index.js

@@ -0,0 +1,38 @@
+import {
+  generateExpress,
+  generateNginx
+} from "./chunk-IW5F2ZYM.js";
+import {
+  headerGrader
+} from "./chunk-O3B2LYGP.js";
+import {
+  EXPLOITS,
+  RECOMMENDED,
+  formatReport,
+  gradeHeaders,
+  gradeOf,
+  isGrade,
+  isLocalHttpUrl,
+  meetsGrade,
+  rules,
+  runRules,
+  scan,
+  scoreOf
+} from "./chunk-GQYXZFYW.js";
+export {
+  EXPLOITS,
+  RECOMMENDED,
+  formatReport,
+  generateExpress,
+  generateNginx,
+  gradeHeaders,
+  gradeOf,
+  headerGrader,
+  isGrade,
+  isLocalHttpUrl,
+  meetsGrade,
+  rules,
+  runRules,
+  scan,
+  scoreOf
+};

package/dist/middleware-BsJGVvzp.d.cts

@@ -0,0 +1,64 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/** Lowercased header name → value. Multi-value headers are comma-joined. */
+type Headers = Record<string, string>;
+type Status = "pass" | "warn" | "fail";
+interface CheckResult {
+    /** Canonical header name, e.g. "Content-Security-Policy" */
+    header: string;
+    status: Status;
+    /** Human explanation of what was found (or not). */
+    message: string;
+    /** Points earned toward the score. */
+    earned: number;
+    /** Max points this rule is worth. 0 for penalty-only rules. */
+    weight: number;
+    /** The value we recommend setting, when status != pass. */
+    recommended?: string;
+    /** Concrete attack scenario this header prevents, when status != pass. */
+    exploit?: string;
+}
+interface ScanContext {
+    headers: Headers;
+    /** True when the target is plain HTTP on localhost — dev mode. */
+    isLocalHttp: boolean;
+}
+interface Rule {
+    header: string;
+    weight: number;
+    check(ctx: ScanContext): CheckResult;
+}
+type Grade = "A+" | "A" | "B" | "C" | "D" | "F";
+interface Report {
+    url: string;
+    grade: Grade;
+    /** 0–100 */
+    score: number;
+    results: CheckResult[];
+    fetchedAt: string;
+}
+
+interface MiddlewareOptions {
+    /**
+     * Grade every response, deduped by grade — reprints only when the grade
+     * changes. Default: grade only the first HTML/document response.
+     */
+    watch?: boolean;
+    /** Include the attack scenario for each failing header in the printed report. */
+    explain?: boolean;
+    /** Called with the report instead of printing to the console. */
+    onReport?: (report: Report) => void;
+    /** Treat the server as local HTTP (relaxes HSTS). Default: true — it's a dev tool. */
+    isLocalHttp?: boolean;
+}
+/**
+ * Express/Connect-compatible middleware that grades the security headers
+ * your own app actually sends. Mount it AFTER helmet/header middleware so
+ * it sees the final headers:
+ *
+ *   app.use(helmet());
+ *   if (app.get("env") === "development") app.use(headerGrader());
+ */
+declare function headerGrader(options?: MiddlewareOptions): (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+
+export { type CheckResult as C, type Grade as G, type Headers as H, type MiddlewareOptions as M, type Report as R, type ScanContext as S, type Rule as a, type Status as b, headerGrader as h };

package/dist/middleware-BsJGVvzp.d.ts

@@ -0,0 +1,64 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/** Lowercased header name → value. Multi-value headers are comma-joined. */
+type Headers = Record<string, string>;
+type Status = "pass" | "warn" | "fail";
+interface CheckResult {
+    /** Canonical header name, e.g. "Content-Security-Policy" */
+    header: string;
+    status: Status;
+    /** Human explanation of what was found (or not). */
+    message: string;
+    /** Points earned toward the score. */
+    earned: number;
+    /** Max points this rule is worth. 0 for penalty-only rules. */
+    weight: number;
+    /** The value we recommend setting, when status != pass. */
+    recommended?: string;
+    /** Concrete attack scenario this header prevents, when status != pass. */
+    exploit?: string;
+}
+interface ScanContext {
+    headers: Headers;
+    /** True when the target is plain HTTP on localhost — dev mode. */
+    isLocalHttp: boolean;
+}
+interface Rule {
+    header: string;
+    weight: number;
+    check(ctx: ScanContext): CheckResult;
+}
+type Grade = "A+" | "A" | "B" | "C" | "D" | "F";
+interface Report {
+    url: string;
+    grade: Grade;
+    /** 0–100 */
+    score: number;
+    results: CheckResult[];
+    fetchedAt: string;
+}
+
+interface MiddlewareOptions {
+    /**
+     * Grade every response, deduped by grade — reprints only when the grade
+     * changes. Default: grade only the first HTML/document response.
+     */
+    watch?: boolean;
+    /** Include the attack scenario for each failing header in the printed report. */
+    explain?: boolean;
+    /** Called with the report instead of printing to the console. */
+    onReport?: (report: Report) => void;
+    /** Treat the server as local HTTP (relaxes HSTS). Default: true — it's a dev tool. */
+    isLocalHttp?: boolean;
+}
+/**
+ * Express/Connect-compatible middleware that grades the security headers
+ * your own app actually sends. Mount it AFTER helmet/header middleware so
+ * it sees the final headers:
+ *
+ *   app.use(helmet());
+ *   if (app.get("env") === "development") app.use(headerGrader());
+ */
+declare function headerGrader(options?: MiddlewareOptions): (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+
+export { type CheckResult as C, type Grade as G, type Headers as H, type MiddlewareOptions as M, type Report as R, type ScanContext as S, type Rule as a, type Status as b, headerGrader as h };