check.mjs

Functions

Imports

It imports csp.mjs, headers.mjs. Imported by bin/check-security-headers.mjs, index.mjs.

Source

1/**
2 * The reusable half of dustinedwards.info's header gate: what a response must carry, checked on the
3 * response itself. A site runs it in CI against its own rendered responses (a Worker test, or the CLI
4 * in bin/ against a preview or deployed origin).
5 *
6 * Every check names the failure it prevents (capsid/research/design-shared-functions.md, point 5):
7 * sites sending no security headers at all, and report-only policies with no report sink, which enforce
8 * nothing and tell nobody.
9 */
10
11import { CLOUDFLARE_WEB_ANALYTICS } from "./csp.mjs";
12import { STANDARD_SECURITY_HEADERS } from "./headers.mjs";
13
14/** @typedef {{ name: string, pass: boolean, detail: string }} CheckResult */
15
16const ONE_YEAR = 31536000;
17const STRICT_REFERRER = new Set(["no-referrer", "same-origin", "strict-origin", "strict-origin-when-cross-origin"]);
18
19/**
20 * @param {string} policy
21 * @returns {Map<string, string[]>} directive name to its sources, lower-cased names
22 */
23export function parsePolicy(policy) {
24  /** @type {Map<string, string[]>} */
25  const out = new Map();
26  for (const part of policy.split(";")) {
27    const [name, ...sources] = part.trim().split(/\s+/);
28    if (!name) continue;
29    // The first occurrence wins, as browsers apply it.
30    if (!out.has(name.toLowerCase())) out.set(name.toLowerCase(), sources);
31  }
32  return out;
33}
34
35/**
36 * The features a Permissions-Policy denies outright (`feature=()`).
37 *
38 * @param {string} value
39 */
40function deniedFeatures(value) {
41  return new Set([...value.matchAll(/([a-z-]+)=\(\s*\)/g)].map((m) => m[1]));
42}
43
44/**
45 * @param {Headers} headers a real response's headers
46 * @param {{ standard?: Readonly<Record<string, string>>, csp?: boolean, cloudflareWebAnalytics?: boolean, inlineScripts?: "unsafe-inline" }} [options]
47 *   `standard`: the floor (default STANDARD_SECURITY_HEADERS; a site passes the set it declared). `csp`: grade the
48 *   policy too; false for a response that carries none by design, such as a feed or an image.
49 *   `cloudflareWebAnalytics`: the site is Cloudflare-proxied with Web Analytics on, so the policy must let the injected
50 *   beacon run (its script path prefix) and report (connect-src with the site itself).
51 *   `inlineScripts`: the site built its policy with the same opt-in (buildContentSecurityPolicy), so `'unsafe-inline'`
52 *   is accepted on script-src alone; script-src-elem, script-src-attr and worker-src are still refused it.
53 * @returns {CheckResult[]}
54 */
55export function checkSecurityHeaders(headers, { standard = STANDARD_SECURITY_HEADERS, csp = true, cloudflareWebAnalytics = false, inlineScripts } = {}) {
56  /** @type {CheckResult[]} */
57  const results = [];
58  const result = (/** @type {string} */ name, /** @type {boolean} */ pass, /** @type {string} */ detail) =>
59    results.push({ name, pass, detail });
60
61  for (const [name, floor] of Object.entries(standard)) {
62    const got = headers.get(name);
63    if (got === null) {
64      result(`${name} is present`, false, "ABSENT");
65      continue;
66    }
67    if (name === "Strict-Transport-Security") {
68      const age = Number(/max-age=(\d+)/i.exec(got)?.[1] ?? 0);
69      const want = Number(/max-age=(\d+)/i.exec(floor)?.[1] ?? ONE_YEAR);
70      result(`${name} lasts at least ${want} seconds`, age >= want, `got ${JSON.stringify(got)}`);
71      if (/includeSubDomains/i.test(floor)) result(`${name} covers subdomains`, /(^|;)\s*includeSubDomains\s*(;|$)/i.test(got), `got ${JSON.stringify(got)}`);
72    } else if (name === "Referrer-Policy") {
73      result(`${name} is a strict policy`, STRICT_REFERRER.has(got.trim().toLowerCase()), `got ${JSON.stringify(got)}`);
74    } else if (name === "X-Frame-Options") {
75      result(`${name} refuses framing`, /^(deny|sameorigin)$/i.test(got.trim()), `got ${JSON.stringify(got)}`);
76    } else if (name === "Permissions-Policy") {
77      const denied = deniedFeatures(got);
78      const missing = [...deniedFeatures(floor)].filter((f) => !denied.has(f));
79      result(`${name} denies ${[...deniedFeatures(floor)].join(", ")}`, missing.length === 0, missing.length ? `allows ${missing.join(", ")}; got ${JSON.stringify(got)}` : "");
80    } else {
81      result(`${name} is ${JSON.stringify(floor)}`, got.trim().toLowerCase() === floor.toLowerCase(), `got ${JSON.stringify(got)}`);
82    }
83  }
84
85  if (!csp) return results;
86
87  const enforced = headers.get("Content-Security-Policy");
88  const reportOnly = headers.get("Content-Security-Policy-Report-Only");
89  result(
90    "the Content-Security-Policy is enforced, not only reported",
91    Boolean(enforced),
92    enforced ? "" : reportOnly ? "only a Report-Only policy is sent, which blocks nothing" : "ABSENT",
93  );
94  if (!enforced) return results;
95
96  const policy = parsePolicy(enforced);
97  const scripts = policy.get("script-src") ?? policy.get("default-src");
98  result("the policy governs scripts (script-src or default-src)", Boolean(scripts), "neither directive is present, so any script runs");
99  // script-src-elem and script-src-attr override script-src for the scripts they govern, and worker-src for workers, so
100  // each one present is held to the same rules.
101  const scriptDirectives = /** @type {Array<[string, string[]]>} */ ([
102    ["scripts", scripts ?? []],
103    ...["script-src-elem", "script-src-attr", "worker-src"].flatMap((d) => (policy.has(d) ? [[d, policy.get(d) ?? []]] : [])),
104  ]);
105  for (const [label, sources] of scripts ? scriptDirectives : scriptDirectives.slice(1)) {
106    // Browsers match keywords in any case, and a host of `*` matches every host whatever the scheme, port or path.
107    const keywords = sources.map((s) => s.toLowerCase());
108    const noun = label === "scripts" ? "script" : label;
109    const inlineDeclared = label === "scripts" && inlineScripts === "unsafe-inline";
110    result(`${label}: no 'unsafe-inline'${inlineDeclared ? " (declared: inlineScripts)" : ""}`, inlineDeclared || !keywords.includes("'unsafe-inline'"), `${noun} sources: ${sources.join(" ")}`);
111    result(`${label}: no 'unsafe-eval'`, !keywords.includes("'unsafe-eval'"), `${noun} sources: ${sources.join(" ")}`);
112    // A worker from a blob: URL is one the page's own script made, which already had to run, so workers may use blob:.
113    const schemes = label === "worker-src" ? /^(https?|data):$/i : /^(https?|data|blob):$/i;
114    const broad = sources.filter((s) => /^([a-z][a-z0-9+.-]*:\/\/)?\*(:(\d+|\*))?(\/.*)?$/i.test(s) || schemes.test(s));
115    result(`${label}: no wildcard or bare scheme source`, broad.length === 0, broad.length ? `allows ${broad.join(" ")}` : "");
116  }
117  const objects = policy.get("object-src") ?? policy.get("default-src");
118  result("object-src is 'none'", objects?.length === 1 && objects[0] === "'none'", `got ${objects ? objects.join(" ") : "ABSENT"}`);
119  const base = policy.get("base-uri");
120  result("base-uri is 'none' or 'self'", base?.length === 1 && (base[0] === "'none'" || base[0] === "'self'"), `got ${base ? base.join(" ") : "ABSENT (it does not fall back to default-src)"}`);
121  const ancestors = policy.get("frame-ancestors");
122  result(
123    "frame-ancestors is 'none' or 'self'",
124    ancestors?.length === 1 && (ancestors[0] === "'none'" || ancestors[0] === "'self'"),
125    `got ${ancestors ? ancestors.join(" ") : "ABSENT (it does not fall back to default-src)"}`,
126  );
127  // form-action may be absent: an OAuth consent page leaves it out on purpose, since browsers apply it to every redirect
128  // hop and the last hop is the client's redirect_uri. When it is present it must keep forms on this origin.
129  const forms = policy.get("form-action");
130  result(
131    "form-action, when set, is 'self' or 'none'",
132    !forms || (forms.length === 1 && (forms[0] === "'self'" || forms[0] === "'none'")),
133    `got ${forms ? forms.join(" ") : "ABSENT"}`,
134  );
135  if (cloudflareWebAnalytics) {
136    const missingScript = CLOUDFLARE_WEB_ANALYTICS.script.filter((source) => !(scripts ?? []).includes(source));
137    const connect = policy.get("connect-src") ?? policy.get("default-src") ?? [];
138    result(
139      "the policy lets the Cloudflare Web Analytics beacon run: its script path prefix",
140      missingScript.length === 0,
141      `script-src lacks ${missingScript.join(" and ")}: the edge injects /beacon.min.js/v..., which the bare file URL does not match`,
142    );
143    result("the policy lets the beacon report: connect-src includes the site itself", connect.includes("'self'"), `connect-src is ${connect.join(" ") || "ABSENT"}`);
144  }
145  result(
146    "violations are reported somewhere (report-uri or report-to)",
147    policy.has("report-uri") || policy.has("report-to"),
148    "no report sink: a blocked script is never heard about",
149  );
150  return results;
151}
152
153/**
154 * @param {CheckResult[]} results
155 * @returns {CheckResult[]}
156 */
157export const failures = (results) => results.filter((r) => !r.pass);