csp.mjs

Functions

Imports

It imports no other module of this repo. Imported by check.mjs, index.mjs.

Source

1/**
2 * Content-Security-Policy helpers: a per-request nonce, a hash source for an inline script, and the policy a site's
3 * own list of what it loads builds.
4 *
5 * - generateNonce: 16 random bytes, base64. Call it once per request and give the same value to the rendered
6 *   <script nonce> and to the policy.
7 * - scriptHash: Web Crypto rather than node:crypto, so a Worker and a Node gate run one function.
8 * - buildContentSecurityPolicy takes the hosts a site loads, per kind, plus its nonce or hashes, and returns the
9 *   header (enforced, or Report-Only so a repo can ship the policy before it blocks anything). It is the one place
10 *   the policy's fixed parts (object-src, base-uri, frame-ancestors, form-action, the report sink) and the
11 *   Cloudflare Web Analytics beacon are written.
12 * - buildPolicy is the plain join, for a policy that is not a page's (a sandboxed media route).
13 *
14 * - reportingEndpoints is the Reporting-Endpoints header that names a policy's report-to group.
15 *
16 * Which to use, nonce or hash: a response that is never shared-cached may carry a nonce. A response that is
17 * edge-cached must not, since every reader would share one nonce for the cache lifetime; trust its inline scripts
18 * by hash instead. Only when neither can work (an edge-cached page that streams inline scripts whose text changes
19 * per page, as React Router's hydration data does) does a site opt into `inlineScripts: "unsafe-inline"`.
20 */
21
22/** @returns {string} a fresh nonce, 24 base64 characters */
23export function generateNonce() {
24  const bytes = crypto.getRandomValues(new Uint8Array(16));
25  let binary = "";
26  for (const byte of bytes) binary += String.fromCharCode(byte);
27  return btoa(binary);
28}
29
30/**
31 * @param {string} text an inline script's exact text, as the page renders it
32 * @returns {Promise<string>} `sha256-<base64>`, without the quotes the policy puts round it
33 */
34export async function scriptHash(text) {
35  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
36  return `sha256-${btoa(String.fromCharCode(...new Uint8Array(digest)))}`;
37}
38
39/**
40 * The policy string from directives in the order given: `["default-src 'self'", "object-src 'none'"]`
41 * becomes `default-src 'self'; object-src 'none'`. Order is kept, so a gate comparing strings sees
42 * exactly what the site wrote.
43 *
44 * @param {readonly string[]} directives
45 * @returns {string}
46 */
47export function buildPolicy(directives) {
48  const empty = directives.filter((d) => d.trim() === "");
49  if (empty.length > 0) throw new Error("a CSP directive is empty");
50  return directives.join("; ");
51}
52
53/**
54 * Cloudflare Web Analytics, automatic setup, written once for every site on a Cloudflare-proxied hostname. The edge
55 * injects the beacon from a VERSIONED path (/beacon.min.js/v31..., measured in a browser), which the bare file URL
56 * does not match; a source ending in "/" is a path prefix, so the second entry covers that one directory and nothing
57 * else on the host. It reports to the site's own /cdn-cgi/rum, so connect-src needs 'self' on such a site (the
58 * builder always includes it). The file is named, not hashed: its `integrity` changes whenever Cloudflare ships a
59 * new beacon, and a pinned hash would block it within weeks.
60 */
61export const CLOUDFLARE_WEB_ANALYTICS = Object.freeze({
62  script: Object.freeze([
63    "https://static.cloudflareinsights.com/beacon.min.js",
64    "https://static.cloudflareinsights.com/beacon.min.js/",
65  ]),
66});
67
68/** A source expression as a policy writes it: no space, no semicolon, no comma. @param {string} source */
69function checkSource(source) {
70  if (typeof source !== "string" || source === "" || /[\s;,]/.test(source)) throw new Error(`${JSON.stringify(source)} is not a CSP source`);
71  return source;
72}
73
74/**
75 * @typedef {{
76 *   script?: readonly string[],
77 *   style?: readonly string[],
78 *   img?: readonly string[],
79 *   font?: readonly string[],
80 *   connect?: readonly string[],
81 *   frame?: readonly string[],
82 *   media?: readonly string[],
83 * }} CspSources
84 *   The hosts (or schemes, such as `data:`) a site loads, per kind, beyond 'self'. A kind with nothing extra is
85 *   omitted. A source is written as a policy writes it: `https://cdn.example.com`, `data:`.
86 *
87 * @typedef {{
88 *   sources?: CspSources,
89 *   scriptHashes?: readonly string[],
90 *   styleHashes?: readonly string[],
91 *   nonce?: string,
92 *   nonceStyles?: boolean,
93 *   inlineScripts?: "unsafe-inline",
94 *   styleAttributesInline?: boolean,
95 *   cloudflareWebAnalytics?: boolean,
96 *   reportUri?: string,
97 *   reportTo?: string,
98 *   reportOnly?: boolean,
99 *   framedBySameOrigin?: boolean,
100 *   baseUriSelf?: boolean,
101 *   denyUnlisted?: boolean,
102 *   noForms?: boolean,
103 *   extraDirectives?: readonly string[],
104 * }} SitePolicy
105 *   `scriptHashes` / `styleHashes`: `sha256-...` values (scriptHash), for responses that may not carry a nonce.
106 *   `nonce`: this request's nonce, for a response that is never shared-cached; it goes on script-src and style-src.
107 *   `nonceStyles: false`: the nonce on script-src only, for a page whose styles must run as 'unsafe-inline' (listed in
108 *   `sources.style`), which a nonce on style-src would switch off; styles run no code, scripts keep the nonce.
109 *   `inlineScripts: "unsafe-inline"`: `'unsafe-inline'` on script-src, the explicit opt-in for a page whose inline
110 *   scripts neither a nonce nor hashes can cover (an edge-cached page that streams inline hydration scripts). A nonce
111 *   is preferred, then hashes; this is the last resort, and it is refused beside a nonce or hashes, since a browser
112 *   ignores 'unsafe-inline' when either is present and the page's inline scripts would stop running.
113 *   `styleAttributesInline`: `style-src-attr 'unsafe-inline'`, for pages that emit style attributes, which a nonce
114 *   cannot cover; the one inline allowance offered, scoped to attributes, which run no code.
115 *   `reportUri` / `reportTo`: where violations go. A policy with no sink hides the page it breaks, so one is required.
116 *   `framedBySameOrigin`: `frame-ancestors 'self'` in place of 'none', for a site that shows its own pages in frames
117 *   (a design system's live specimens). No other origin can be allowed to frame a site.
118 *   `denyUnlisted`: `default-src 'none'` in place of 'self', so a kind the policy does not name (media, frames,
119 *   workers, the manifest) is refused rather than allowed from the site; for a static site that wants nothing more.
120 *   `noForms`: `form-action 'none'` in place of 'self', for a site with no forms.
121 *   `baseUriSelf`: `base-uri 'self'` in place of 'none', for a page that writes a same-origin <base> (an EPUB reader
122 *   resolving a book's files); the check accepts either.
123 */
124
125/**
126 * The Content-Security-Policy header a site sends, from what it loads. The fixed parts are the same everywhere
127 * (`default-src 'self'`, `object-src 'none'`, `base-uri 'none'`, `form-action 'self'`, `frame-ancestors 'none'`, or
128 * 'self' when the site frames its own pages);
129 * scripts are 'self', the site's hashes or nonce, its listed hosts and, when asked, the Cloudflare beacon. A script
130 * source that is `*` (or any host-source whose host is `*`), a bare scheme, or 'unsafe-inline' or 'unsafe-eval' in any
131 * case is refused here, so a site cannot list its way to a policy the check would fail; 'unsafe-inline' comes only
132 * from the named opt-in `inlineScripts`, which the check accepts when the site declares the same.
133 *
134 * @param {SitePolicy} site
135 * @returns {{ name: "Content-Security-Policy" | "Content-Security-Policy-Report-Only", value: string }}
136 */
137export function buildContentSecurityPolicy(site) {
138  const { sources = {}, scriptHashes = [], styleHashes = [], nonce, nonceStyles = true, inlineScripts, styleAttributesInline = false, cloudflareWebAnalytics = false, reportUri, reportTo, reportOnly = false, framedBySameOrigin = false, baseUriSelf = false, denyUnlisted = false, noForms = false, extraDirectives = [] } = site;
139  if (!reportUri && !reportTo) throw new Error("a policy needs a report sink (reportUri or reportTo)");
140  if (inlineScripts !== undefined && inlineScripts !== "unsafe-inline") throw new Error(`inlineScripts is "unsafe-inline" or left out, not ${JSON.stringify(inlineScripts)}`);
141  if (inlineScripts && (nonce !== undefined || scriptHashes.length > 0)) {
142    throw new Error("inlineScripts cannot go with a nonce or script hashes: a browser then ignores 'unsafe-inline'; use the nonce or hashes alone");
143  }
144  if (nonce !== undefined && !/^[A-Za-z0-9+/_-]{16,}={0,2}$/.test(nonce)) throw new Error("the nonce is not a base64 value of at least 16 characters");
145  const hashSource = (/** @type {string} */ h) => {
146    if (!/^sha(256|384|512)-[A-Za-z0-9+/_-]+={0,2}$/.test(h)) throw new Error(`${JSON.stringify(h)} is not a hash source`);
147    return `'${h}'`;
148  };
149  const list = (/** @type {readonly string[] | undefined} */ hosts) => (hosts ?? []).map(checkSource);
150
151  const scriptHosts = [...list(sources.script), ...(cloudflareWebAnalytics ? CLOUDFLARE_WEB_ANALYTICS.script : [])];
152  for (const host of scriptHosts) {
153    // A host of `*` matches every host whatever the scheme, port or path; keywords match in any case in a browser.
154    if (/^([a-z][a-z0-9+.-]*:\/\/)?\*(:(\d+|\*))?(\/.*)?$/i.test(host) || /^(https?|data|blob):$/i.test(host) || /^'unsafe-(inline|eval)'$/i.test(host)) {
155      throw new Error(`${host} is not an acceptable script source: name the host`);
156    }
157  }
158  // An extra directive may add a kind (frame-src, worker-src, upgrade-insecure-requests), never restate one of the fixed
159  // ones, and never reopen scripts through script-src-elem or script-src-attr.
160  const written = new Set(["default-src", "script-src", "script-src-elem", "script-src-attr", "object-src", "base-uri", "form-action", "frame-ancestors", "report-uri", "report-to"]);
161  for (const extra of extraDirectives) {
162    const [name = "", ...values] = extra.trim().split(/\s+/);
163    if (written.has(name.toLowerCase())) throw new Error(`${name} is written by the builder; pass its sources instead of an extra directive`);
164    if (name.toLowerCase() === "worker-src" && values.some((v) => /^([a-z][a-z0-9+.-]*:\/\/)?\*/i.test(v) || /^(https?|data):$/i.test(v) || /^'unsafe-(inline|eval)'$/i.test(v))) {
165      throw new Error(`${extra} is not an acceptable worker source: name the host`);
166    }
167  }
168  const nonceSource = nonce === undefined ? [] : [`'nonce-${nonce}'`];
169  const directives = [
170    `default-src ${denyUnlisted ? "'none'" : "'self'"}`,
171    `script-src ${[...nonceSource, ...scriptHashes.map(hashSource), "'self'", ...(inlineScripts ? ["'unsafe-inline'"] : []), ...scriptHosts].join(" ")}`,
172    `style-src ${["'self'", ...(nonceStyles ? nonceSource : []), ...styleHashes.map(hashSource), ...list(sources.style)].join(" ")}`,
173    ...(styleAttributesInline ? ["style-src-attr 'unsafe-inline'"] : []),
174    `font-src ${["'self'", ...list(sources.font)].join(" ")}`,
175    `img-src ${["'self'", ...list(sources.img)].join(" ")}`,
176    ...((sources.media ?? []).length > 0 ? [`media-src ${["'self'", ...list(sources.media)].join(" ")}`] : []),
177    // 'self' is always present: the Cloudflare beacon reports to /cdn-cgi/rum on the site's own origin.
178    `connect-src ${["'self'", ...list(sources.connect)].join(" ")}`,
179    ...((sources.frame ?? []).length > 0 ? [`frame-src ${["'self'", ...list(sources.frame)].join(" ")}`] : []),
180    "object-src 'none'",
181    `base-uri ${baseUriSelf ? "'self'" : "'none'"}`,
182    `form-action ${noForms ? "'none'" : "'self'"}`,
183    `frame-ancestors ${framedBySameOrigin ? "'self'" : "'none'"}`,
184    ...extraDirectives,
185    ...(reportUri ? [`report-uri ${checkSource(reportUri)}`] : []),
186    ...(reportTo ? [`report-to ${checkSource(reportTo)}`] : []),
187  ];
188  return { name: reportOnly ? "Content-Security-Policy-Report-Only" : "Content-Security-Policy", value: buildPolicy(directives) };
189}
190
191/**
192 * The Reporting-Endpoints header value that defines a policy's `report-to` group: `csp-endpoint="https://example.com/csp-report"`.
193 * The URL must be absolute and potentially trustworthy: https, or http on a loopback host (127.0.0.0/8, [::1], localhost or
194 * a name under .localhost), so a local dev server works. A browser skips any other endpoint (Reporting API, "process
195 * reporting endpoints": "If endpoint url's origin is not potentially trustworthy, then continue"; the hosts are Secure
196 * Contexts, https://w3c.github.io/webappsec-secure-contexts/#is-origin-trustworthy), and the group's reports then go nowhere.
197 *
198 * @param {string} group the name the policy's `reportTo` gives
199 * @param {string | URL} url the receiver, absolute: `new URL("/csp-report", origin)`
200 * @returns {string}
201 */
202export function reportingEndpoints(group, url) {
203  if (!/^[a-z*][a-z0-9_.*-]*$/.test(group)) throw new Error(`${JSON.stringify(group)} is not a report-to group name (lower-case letters, digits, _ - . *)`);
204  let parsed;
205  try {
206    parsed = new URL(url);
207  } catch {
208    throw new Error(`${JSON.stringify(String(url))} is not an absolute URL: Reporting-Endpoints ignores a relative endpoint`);
209  }
210  // The URL parser lower-cases the host and writes an IPv4 address as four decimals, so these match every spelling.
211  const local = parsed.protocol === "http:" && /^(127(\.\d{1,3}){3}|\[::1\]|(.+\.)?localhost\.?)$/.test(parsed.hostname);
212  if (parsed.protocol !== "https:" && !local) throw new Error(`${parsed.href} is not https or http on a loopback host: Reporting-Endpoints ignores an endpoint that is not potentially trustworthy`);
213  return `${group}="${parsed.href}"`;
214}