headers.mjs

Functions

Imports

It imports owasp-headers.mjs. Imported by check.mjs, index.mjs.

Source

1/**
2 * The standard response header set every site in the portfolio sends, and one way to apply a set.
3 *
4 * The values are the OWASP Secure Headers Project's own, read by update-owasp.mjs (owasp-headers.mjs says when and
5 * from where), for every header that is the same everywhere. Four of OSHP's recommendations are not in the standard,
6 * each for a reason that is written down next to it (OWASP_SKIPPED); a site that must differ on another header says
7 * so, with a reason, in `overrides`, and the check holds the site to the set it declared.
8 *
9 * What a site adds on top (a Permissions-Policy of its own, say) is its own and is stated as an override or an
10 * extra, never as a copy of this set.
11 */
12
13import { OWASP_RECOMMENDED } from "./owasp-headers.mjs";
14
15/**
16 * The OSHP recommendations this package does not put in the standard set, and why. Each would break a normal site if
17 * sent on every response, or is not one value for every site.
18 *
19 * @type {Readonly<Record<string, string>>}
20 */
21export const OWASP_SKIPPED = Object.freeze({
22  "Cache-Control": "OSHP's `no-store, max-age=0` on every response makes nothing cacheable, edge caches included; a site sets caching per route.",
23  "Clear-Site-Data":
24    "On every response it wipes the reader's cookies, storage and cache at each page load, which logs everyone out of everything; OSHP's own suite tests it on the logout page only, so it is exported as LOGOUT_HEADERS for a site's logout response.",
25  "Cross-Origin-Embedder-Policy":
26    "`require-corp` refuses every cross-origin subresource that does not opt in with Cross-Origin-Resource-Policy or CORS, which breaks images, fonts and scripts a normal site loads from elsewhere; a site turns it on only when it needs cross-origin isolation.",
27  "Content-Security-Policy":
28    "A policy is not one string for every site: it names what that site loads, so the package builds it from the site's own list (buildContentSecurityPolicy) instead of sharing OSHP's `default-src 'self'` example.",
29});
30
31/**
32 * The standard set: OSHP's recommendations minus OWASP_SKIPPED, in OSHP's words.
33 *
34 * @type {Readonly<Record<string, string>>}
35 */
36export const STANDARD_SECURITY_HEADERS = Object.freeze(
37  Object.fromEntries(Object.entries(OWASP_RECOMMENDED).filter(([name]) => !(name in OWASP_SKIPPED))),
38);
39
40/**
41 * The headers OSHP recommends for a logout response only (Clear-Site-Data), for a site that has one.
42 *
43 * @type {Readonly<Record<string, string>>}
44 */
45export const LOGOUT_HEADERS = Object.freeze({ "Clear-Site-Data": OWASP_RECOMMENDED["Clear-Site-Data"] ?? "" });
46
47/**
48 * The override a site that offers passkey sign-in (`./sign-in`) passes to buildSecurityHeaders. OSHP's
49 * Permissions-Policy sets `publickey-credentials-get=()`, which refuses every passkey sign-in on the page; this allows
50 * it for the site's own pages and still for no frame. Every other directive stays OSHP's.
51 *
52 * @type {Readonly<Record<string, HeaderOverride>>}
53 */
54export const PASSKEY_OVERRIDES = Object.freeze({
55  "Permissions-Policy": Object.freeze({
56    value: [
57      ...(STANDARD_SECURITY_HEADERS["Permissions-Policy"] ?? "")
58        .split(",")
59        .map((d) => d.trim())
60        .filter((d) => d && !d.startsWith("publickey-credentials-get=")),
61      "publickey-credentials-get=(self)",
62    ].join(", "),
63    reason: "Passkey sign-in (./sign-in) calls navigator.credentials.get, which OSHP's publickey-credentials-get=() refuses; allowed for the site's own pages only.",
64  }),
65});
66
67/**
68 * @typedef {{ value: string | null, reason: string }} HeaderOverride
69 *   A header a site sends differently from the standard: its own value, or null to send none, and why. A reason is
70 *   required, so a deviation is a decision someone wrote down and not an accident.
71 */
72
73/**
74 * The set a site sends: the standard with the site's overrides applied. An override must carry a reason and must
75 * change something; one that says what the standard already says is refused, so the list stays the list of real
76 * deviations.
77 *
78 * @param {{ overrides?: Readonly<Record<string, HeaderOverride>> }} [site]
79 * @returns {Record<string, string>}
80 */
81export function buildSecurityHeaders({ overrides = {} } = {}) {
82  /** @type {Record<string, string>} */
83  const set = { ...STANDARD_SECURITY_HEADERS };
84  for (const [name, { value, reason }] of Object.entries(overrides)) {
85    if (typeof reason !== "string" || reason.trim().length < 12) throw new Error(`the override of ${name} gives no reason`);
86    if (value === (STANDARD_SECURITY_HEADERS[name] ?? undefined)) throw new Error(`the override of ${name} says what the standard already says`);
87    if (value === null) {
88      if (!(name in set)) throw new Error(`the override of ${name} removes a header the standard does not send`);
89      delete set[name];
90    } else if (value.trim() === "") {
91      throw new Error(`the override of ${name} is empty; use null to send none`);
92    } else {
93      set[name] = value;
94    }
95  }
96  return set;
97}
98
99/**
100 * Stamps a header set onto `headers` in place.
101 *
102 * `overwrite: true` (the default) makes the set authoritative, which is what dustinedwards.info does on
103 * every exit. `overwrite: false` keeps any value a route already chose, which is foxhound's merge. A
104 * Response whose headers are immutable (Response.redirect, the Cache API) throws on `set`; rebuild it
105 * with `new Response(res.body, { ...res, headers: new Headers(res.headers) })` and apply to that.
106 *
107 * @param {Headers} headers
108 * @param {Readonly<Record<string, string>>} [set]
109 * @param {{ overwrite?: boolean }} [options]
110 */
111export function applyHeaderSet(headers, set = STANDARD_SECURITY_HEADERS, { overwrite = true } = {}) {
112  for (const [name, value] of Object.entries(set)) {
113    if (overwrite || !headers.has(name)) headers.set(name, value);
114  }
115}