feat(security): collect CSP violation reports so report-only means something

docs/api-reference/veryfront/security.md

@@ -55,7 +55,7 @@ applySecurityHeaders(response.headers, false, generateNonce(), null);
 | `applyCORSHeaders`           |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/cors/headers.ts#L86)               |
 | `applyCORSHeadersSync`       | Apply CORS synchronously. Promise-returning values still fail closed at runtime.                                                                                                                                   | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/cors/headers.ts#L112)              |
 | `applyCsrfCookie`            | Set CSRF cookie on GET/HEAD responses when not already present. Uses httpOnly: false so client JS can read the cookie for double-submit.                                                                           | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/csrf/helpers.ts#L150)                   |
-| `applySecurityHeaders`       |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/response/security-handler.ts#L337) |
+| `applySecurityHeaders`       |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/response/security-handler.ts#L343) |
 | `buildCacheControl`          |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/response/cache-handler.ts#L86)     |
 | `cors`                       | Create CORS middleware.                                                                                                                                                                                            | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/cors/middleware.ts#L10)            |
 | `corsSimple`                 |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/cors/middleware.ts#L39)            |
@@ -65,8 +65,8 @@ applySecurityHeaders(response.headers, false, generateNonce(), null);
 | `createValidationError`      | Create an input validation error. Convenience wrapper around INPUT_VALIDATION_FAILED.create().                                                                                                                     | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/input-validation/errors.ts#L12)         |
 | `createValidator`            |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/path-validation/index.ts#L446)          |
 | `generateCsrfToken`          | Generate a CSRF token and return value + Set-Cookie header string                                                                                                                                                  | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/csrf/helpers.ts#L70)                    |
-| `generateNonce`              |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/response/security-handler.ts#L69)  |
-| `getSecurityHeader`          |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/response/security-handler.ts#L324) |
+| `generateNonce`              |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/response/security-handler.ts#L71)  |
+| `getSecurityHeader`          |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/response/security-handler.ts#L330) |
 | `handleCORSPreflight`        |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/cors/preflight.ts#L126)            |
 | `isPreflightRequest`         |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/cors/preflight.ts#L186)            |
 | `isRequestBodyTooLargeError` |                                                                                                                                                                                                                    | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/input-validation/limits.ts#L100)        |
@@ -94,9 +94,9 @@ applySecurityHeaders(response.headers, false, generateNonce(), null);
 
 | Name                   | Description | Source                                                                                                     |
 | ---------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
-| `AuthHandler`          |             | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/auth.ts#L155)             |
+| `AuthHandler`          |             | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/auth.ts#L156)             |
 | `BaseHandler`          |             | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/base-handler.ts#L45)      |
-| `CsrfHandler`          |             | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/csrf/csrf-handler.ts#L55) |
+| `CsrfHandler`          |             | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/csrf/csrf-handler.ts#L56) |
 | `ResponseBuilder`      |             | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/response/builder.ts#L9)   |
 | `SecureFs`             |             | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/secure-fs.ts#L645)             |
 | `SecurityConfigLoader` |             | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/http/config.ts#L292)           |

docs/guides/security-headers.md

@@ -24,10 +24,12 @@ object-src 'none';
 frame-src 'self';
 frame-ancestors 'none';
 base-uri 'self';
-form-action 'self'
+form-action 'self';
+report-to veryfront-csp;
+report-uri /_vf/csp-report
 ```
 
-Alongside it: `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`, `Strict-Transport-Security`, and `Cross-Origin-Opener-Policy` / `Cross-Origin-Resource-Policy` set to `same-origin`.
+Alongside it: `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`, `Strict-Transport-Security`, `Cross-Origin-Opener-Policy` / `Cross-Origin-Resource-Policy` set to `same-origin`, and `Reporting-Endpoints: veryfront-csp="/_vf/csp-report"`, which defines the group the two reporting directives name.
 
 Development serves no CSP at all, so HMR and dev tooling are never blocked and a local allowance can never widen your production policy.
 
@@ -37,6 +39,14 @@ Three directives are worth understanding:
 - **`style-src` and `font-src` include the Google Fonts origins** because `veryfront/fonts` writes those tags into the document itself. Google Fonts therefore works with no configuration. If your project never uses it, see [Tightening the policy](#tightening-the-policy).
 - **`frame-ancestors`** is `'none'` on your own domain. On `*.veryfront.com` addresses it instead allows the Studio origins, so the Studio preview iframe works.
 
+## Violation reports
+
+The policy asks browsers to report what it blocks, to `/_vf/csp-report` on your own origin. Both spellings are sent because `report-to` is the current one and `report-uri` is still the only one several shipping browsers honour.
+
+You do not configure this and cannot switch it off. Reports are recorded with the violating document, the directive, the blocked URL and the status — with query strings removed, so identifiers in a URL do not reach a log. They are rate-limited, and the endpoint always answers `204`.
+
+The endpoint is exempt from `security.auth` and `security.csrf`. A browser reports a violation without credentials and without a CSRF token, because a report is not a user action, so a protected project would otherwise report nothing at all. Exempting it discloses nothing: it reads no credentials, changes no state, and its response never varies.
+
 ## Adding an origin
 
 Set `security.csp` in `veryfront.config.ts`. Values are **added to** the defaults, so you never restate them:

src/security/http/auth.ts

@@ -1,3 +1,4 @@
+import { isCspReportRequest } from "#veryfront/security/http/csp-report-endpoint.ts";
 import { BaseHandler } from "./base-handler.ts";
 import type {
   HandlerContext,
@@ -162,6 +163,13 @@ export class AuthHandler extends BaseHandler {
   handle(req: Request, ctx: HandlerContext): Promise<HandlerResult> {
     if (req.method.toUpperCase() === "OPTIONS") return Promise.resolve(this.continue());
 
+    // Same reasoning as the CSRF gate: a browser reports a violation without
+    // credentials, so a protected project would collect nothing. See
+    // `isCspReportRequest` for why exempting it discloses nothing.
+    if (isCspReportRequest(req.method, new URL(req.url).pathname)) {
+      return Promise.resolve(this.continue());
+    }
+
     const auth = this.resolveAuth(ctx);
     if (!auth) return Promise.resolve(this.continue());
 

src/security/http/csp-report-endpoint.ts

@@ -0,0 +1,33 @@
+/**
+ * Where the platform CSP asks browsers to send violation reports.
+ *
+ * The policy is built in the security module and the reports are received by a
+ * server handler, so the path and the group name live here, on the side both
+ * can depend on. They have to agree: a `report-to` directive naming a group the
+ * `Reporting-Endpoints` header does not define makes the browser send nothing,
+ * and it fails silently.
+ */
+
+/** Path serving {@link CSP_REPORT_ENDPOINT_NAME}, on the project's own origin. */
+export const CSP_REPORT_PATH = "/_vf/csp-report";
+
+/** Reporting group tying the CSP `report-to` directive to `Reporting-Endpoints`. */
+export const CSP_REPORT_ENDPOINT_NAME = "veryfront-csp";
+
+/**
+ * Whether a request is the platform's own CSP report submission.
+ *
+ * The auth and CSRF gates both run ahead of the handler and both refuse a
+ * browser-generated report: it carries no credentials and no CSRF token,
+ * because a violation report is not a user action. Left alone, any project
+ * enabling either feature advertises a reporting endpoint that silently
+ * collects nothing.
+ *
+ * Exempting it is safe on the terms those gates exist for. The endpoint reads
+ * no credentials, changes no state, and answers 204 regardless of the body, so
+ * it discloses nothing about a protected project; what it writes is a bounded,
+ * sanitized, rate-limited log line.
+ */
+export function isCspReportRequest(method: string, pathname: string): boolean {
+  return method.toUpperCase() === "POST" && pathname === CSP_REPORT_PATH;
+}

src/security/http/csrf/csrf-handler.test.ts

@@ -4,6 +4,7 @@ import { assertEquals } from "#veryfront/testing/assert.ts";
 import { CsrfHandler } from "./csrf-handler.ts";
 import { generateCsrfToken } from "../../csrf/helpers.ts";
 import type { HandlerContext } from "#veryfront/types";
+import { CSP_REPORT_PATH } from "#veryfront/security/http/csp-report-endpoint.ts";
 
 function createCtx(csrf?: boolean | Record<string, unknown>): HandlerContext {
   return {
@@ -32,6 +33,35 @@ describe("security/http/csrf/csrf-handler", () => {
     });
   });
 
+  describe("platform CSP report endpoint", () => {
+    it("passes a browser report through even with CSRF enabled", async () => {
+      // A violation report is not a user action: the browser sends no token, so
+      // a project enabling CSRF would advertise a reporting endpoint that
+      // silently collects nothing.
+      const result = await handler.handle(
+        new Request(`https://acme.veryfront.com${CSP_REPORT_PATH}`, {
+          method: "POST",
+          body: '{"csp-report":{}}',
+        }),
+        createCtx(true),
+      );
+
+      assertEquals(result.response, undefined);
+    });
+
+    it("still rejects a token-less POST to any other path", async () => {
+      const result = await handler.handle(
+        new Request("https://acme.veryfront.com/_vf/csp-report-other", {
+          method: "POST",
+          body: "{}",
+        }),
+        createCtx(true),
+      );
+
+      assertEquals(result.response?.status, 403);
+    });
+  });
+
   describe("when CSRF is not configured", () => {
     it("should pass through all requests when securityConfig is null", async () => {
       const ctx = createCtx();

src/security/http/csrf/csrf-handler.ts

@@ -41,6 +41,7 @@
  * @module security/http/csrf/csrf-handler
  */
 
+import { isCspReportRequest } from "#veryfront/security/http/csp-report-endpoint.ts";
 import { BaseHandler } from "../base-handler.ts";
 import { validateCsrf } from "../../csrf/helpers.ts";
 import type {
@@ -73,6 +74,11 @@ export class CsrfHandler extends BaseHandler {
 
     const { pathname } = new URL(req.url);
 
+    // A CSP violation report is not a user action and carries no token. See
+    // `isCspReportRequest`; relying on a project to add it to `excludePaths`
+    // would make reporting another thing a project has to configure first.
+    if (isCspReportRequest(method, pathname)) return this.continue();
+
     // Check exclude paths
     if (typeof csrfConfig === "object" && csrfConfig.excludePaths?.length) {
       for (const excludePath of csrfConfig.excludePaths) {

src/security/http/response/security-handler.test.ts

@@ -1,3 +1,4 @@
+import { CSP_REPORT_PATH } from "#veryfront/security/http/csp-report-endpoint.ts";
 import "#veryfront/schemas/_test-setup.ts";
 import { describe, it } from "#veryfront/testing/bdd.ts";
 import { assert, assertEquals } from "#veryfront/testing/assert.ts";
@@ -638,6 +639,30 @@ describe("security/http/response/security-handler", () => {
       );
     });
 
+    it("points the policy at a reporting group the response actually defines", () => {
+      // The failure mode this guards is silent: a `report-to` naming a group
+      // that `Reporting-Endpoints` does not define makes the browser send
+      // nothing at all, and the policy still looks correct in devtools.
+      const headers = applyHeaders();
+      const policy = headers.get("Content-Security-Policy") ??
+        headers.get("Content-Security-Policy-Report-Only") ?? "";
+
+      const group = /report-to ([^;]+)/.exec(policy)?.[1]?.trim();
+      assert(group, "policy must carry a report-to directive");
+
+      const endpoints = headers.get("Reporting-Endpoints") ?? "";
+      assert(
+        endpoints.includes(`${group}=`),
+        `Reporting-Endpoints (${endpoints}) must define the group named by report-to (${group})`,
+      );
+
+      // The deprecated spelling is still the only one some browsers honour, and
+      // it takes a path rather than a group name.
+      const reportUri = /report-uri ([^;]+)/.exec(policy)?.[1]?.trim();
+      assertEquals(reportUri, CSP_REPORT_PATH);
+      assert(endpoints.includes(`"${CSP_REPORT_PATH}"`), "both spellings must aim at one path");
+    });
+
     it("should set X-Content-Type-Options", () => {
       const headers = applyHeaders();
       assertEquals(headers.get("X-Content-Type-Options"), "nosniff");