csp-report.mjs

Functions

Imports

It imports body.mjs. Imported by index.mjs.

Source

1/**
2 * The one receiver for Content-Security-Policy violation reports, for every site that names a report sink in its
3 * policy (buildContentSecurityPolicy requires one):
4 *
5 * - A POST always gets 204, even when it is too large, unreadable or rate-limited: an error status makes browsers
6 *   send the report again.
7 * - The body is read up to 16 KB and no further, whatever Content-Length claims; a real report is well under 2 kB.
8 * - At most 10 violations are logged from one request, one JSON line each, with every URL cut to its origin and
9 *   path, so no query string reaches the log, and no address, user agent or cookie is ever logged.
10 * - The site's own limiter, when it passes one, is asked first, so nobody can fill the logs.
11 * - Nothing is stored: a store the internet can write to is a storage-exhaustion primitive.
12 *
13 * Both wire formats are read: report-uri's `{"csp-report": {...}}` (application/csp-report) and the Reporting API's
14 * array of `{type: "csp-violation", body}` (application/reports+json).
15 */
16
17import { readCapped } from "./body.mjs";
18
19/** The largest body read; the rest is never read. */
20export const MAX_REPORT_BYTES = 16_384;
21
22/** The most violations logged from one request. */
23export const MAX_REPORTS = 10;
24
25/** @param {unknown} v @returns {v is Record<string, unknown>} */
26const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
27
28/**
29 * A URL cut to its origin and path. A keyword such as "inline", "eval" or "data" is kept, to 64 characters.
30 * @param {unknown} value
31 * @returns {string | undefined}
32 */
33export function trimReportUrl(value) {
34  if (typeof value !== "string" || value === "") return undefined;
35  try {
36    const url = new URL(value);
37    return `${url.origin}${url.pathname}`;
38  } catch {
39    return value.slice(0, 64);
40  }
41}
42
43/**
44 * The violations in a parsed report body, in either format; anything else is no violations.
45 * @param {unknown} parsed
46 * @returns {Record<string, unknown>[]}
47 */
48export function cspViolations(parsed) {
49  if (Array.isArray(parsed)) {
50    return parsed.filter((r) => isObject(r) && r.type === "csp-violation" && isObject(r.body)).map((r) => /** @type {Record<string, unknown>} */ (r.body));
51  }
52  if (isObject(parsed) && isObject(parsed["csp-report"])) return [/** @type {Record<string, unknown>} */ (parsed["csp-report"])];
53  return [];
54}
55
56/**
57 * One violation as the line the receiver logs: the directive, what was blocked, the page, the script and line, and
58 * whether it was enforced or only reported. Each field is read under the Reporting API's name or report-uri's.
59 * @param {Record<string, unknown>} body
60 */
61export function summarizeViolation(body) {
62  const field = (/** @type {string[]} */ ...names) => names.map((n) => body[n]).find((v) => v !== undefined);
63  const line = field("lineNumber", "line-number");
64  const disposition = field("disposition");
65  return {
66    event: "csp-violation",
67    directive: String(field("effectiveDirective", "effective-directive", "violatedDirective", "violated-directive") ?? "").slice(0, 64) || undefined,
68    blocked: trimReportUrl(field("blockedURL", "blocked-uri")),
69    page: trimReportUrl(field("documentURL", "document-uri")),
70    source: trimReportUrl(field("sourceFile", "source-file")),
71    line: typeof line === "number" ? line : undefined,
72    disposition: disposition === "enforce" || disposition === "report" ? disposition : undefined,
73  };
74}
75
76/**
77 * The body as text, at most `max` bytes; null when it is longer or unreadable (a report that cannot be read is
78 * dropped, never retried).
79 * @param {Request} request @param {number} max
80 * @returns {Promise<string | null>}
81 */
82async function readReport(request, max) {
83  try {
84    return await readCapped(request, max);
85  } catch {
86    return null;
87  }
88}
89
90/**
91 * @typedef {{
92 *   allow?: (request: Request) => boolean | Promise<boolean>,
93 *   allowOrigin?: string,
94 *   headers?: Readonly<Record<string, string>>,
95 *   log?: (line: Record<string, unknown>) => void,
96 * }} ReceiveOptions
97 *   `allow`: the site's rate limiter; false drops the report, still with 204. `allowOrigin`: the one origin whose
98 *   pages report here from another host (Carrel's pages report to its AI door); it gets the Reporting API's CORS
99 *   preflight. `headers`: the site's security set, put on every response. `log`: where lines go (console.log).
100 */
101
102/**
103 * Receives one report request and answers it. POST is 204, OPTIONS is the preflight (204, CORS only for
104 * `allowOrigin`), anything else is 405.
105 * @param {Request} request
106 * @param {ReceiveOptions} [options]
107 * @returns {Promise<Response>}
108 */
109export async function receiveCspReport(request, { allow, allowOrigin, headers = {}, log = (line) => console.log(JSON.stringify(line)) } = {}) {
110  /** @type {Record<string, string>} */
111  const cors = allowOrigin && request.headers.get("Origin") === allowOrigin
112    ? { "Access-Control-Allow-Origin": allowOrigin, "Access-Control-Allow-Methods": "POST", "Access-Control-Allow-Headers": "Content-Type", Vary: "Origin" }
113    : {};
114  const answer = (/** @type {number} */ status, /** @type {Record<string, string>} */ extra = {}) =>
115    new Response(null, { status, headers: { ...headers, ...cors, "Cache-Control": "no-store", ...extra } });
116
117  if (request.method === "OPTIONS") return answer(204);
118  if (request.method !== "POST") return answer(405, { Allow: "POST, OPTIONS" });
119  const declared = Number(request.headers.get("Content-Length") ?? 0);
120  if (Number.isFinite(declared) && declared > MAX_REPORT_BYTES) return answer(204);
121  if (allow && !(await allow(request))) return answer(204);
122  const text = await readReport(request, MAX_REPORT_BYTES);
123  if (text === null) return answer(204);
124  let parsed;
125  try {
126    parsed = JSON.parse(text);
127  } catch {
128    return answer(204);
129  }
130  for (const body of cspViolations(parsed).slice(0, MAX_REPORTS)) log(summarizeViolation(body));
131  return answer(204);
132}