From 9d22c75016323dc566c8af7b49f3fba229930583 Mon Sep 17 00:00:00 2001
From: lilleman <lilleman@larvit.se>
Date: Sat, 20 Jun 2026 01:18:24 +0200
Subject: [PATCH] =?UTF-8?q?=C2=A79=20response=20security=20headers=20(todo?=
 =?UTF-8?q?=20=C2=A79);=20the=20cookies/CSRF/clock-skew=20parts=20of=20thi?=
 =?UTF-8?q?s=20item=20all=20landed=20in=20=C2=A74=20(HttpOnly/SameSite/Sec?=
 =?UTF-8?q?ure=20cookies=20in=20cookie.ts,=20the=20signed=20double-submit?=
 =?UTF-8?q?=20in=20csrf.ts,=20JWT=5FCLOCK=5FSKEW=5FSEC=20leeway=20on=20exp?=
 =?UTF-8?q?+nbf=20in=20jwt-middleware)=20=E2=80=94=20the=20open=20gap=20wa?=
 =?UTF-8?q?s=20response=20security=20headers,=20now=20closed.=20New=20pure?=
 =?UTF-8?q?=20src/security-headers.ts=20(securityHeaders({secure})):=20a?=
 =?UTF-8?q?=20strict=20CSP=20for=20the=20zero-JS=20core=20=E2=80=94=20scri?=
 =?UTF-8?q?pt-src=20'self'=20with=20NO=20'unsafe-inline'=20(an=20injected?=
 =?UTF-8?q?=20<script>=20can't=20run;=20core=20ships=20none,=20a=20plugin?=
 =?UTF-8?q?=20may=20still=20serve=20its=20own=20/public/<id>/*.js),=20styl?=
 =?UTF-8?q?e-src=20adds=20'unsafe-inline'=20for=20the=20partials'=20inline?=
 =?UTF-8?q?=20style=3D,=20img-src=20'self'=20data:,=20frame-ancestors=20'n?=
 =?UTF-8?q?one',=20object-src=20'none';=20form-action=20deliberately=20omi?=
 =?UTF-8?q?tted=20(the=20themed=20login=20POSTs=20to=20Kratos'=20often-cro?=
 =?UTF-8?q?ss-origin=20action=20URL)=20=E2=80=94=20plus=20X-Content-Type-O?=
 =?UTF-8?q?ptions=20nosniff,=20X-Frame-Options=20DENY,=20Referrer-Policy?=
 =?UTF-8?q?=20strict-origin-when-cross-origin,=20Cross-Origin-Opener-Polic?=
 =?UTF-8?q?y=20same-origin,=20and=20HSTS=20only=20when=20secureCookies=20(?=
 =?UTF-8?q?https;=20ignored=20on=20dev=20http).=20Wired=20in=20app.ts:=20p?=
 =?UTF-8?q?recomputed=20once=20at=20boot,=20res.setHeader'd=20at=20the=20v?=
 =?UTF-8?q?ery=20top=20of=20the=20handler=20before=20any=20branch,=20so=20?=
 =?UTF-8?q?every=20response=20(page/json/redirect/static/error/plugin)=20i?=
 =?UTF-8?q?nherits=20them=20via=20writeHead's=20merge;=20a=20plugin=20over?=
 =?UTF-8?q?rides=20per-route=20via=20RouteResult.headers.=20Verified=20no?=
 =?UTF-8?q?=20view/CSS=20loads=20cross-origin=20(no=20<script>=20anywhere,?=
 =?UTF-8?q?=20no=20external=20fonts/CDNs),=20so=20default-src=20'self'=20b?=
 =?UTF-8?q?reaks=20nothing.=20Tests-first:=20security-headers.test.ts=20(s?=
 =?UTF-8?q?trict=20defaults,=20script-src=20has=20no=20'unsafe-inline',=20?=
 =?UTF-8?q?HSTS-only-on-secure)=20+=20an=20app.test.ts=20integration=20(th?=
 =?UTF-8?q?e=20page=20and=20a=20static=20asset=20both=20carry=20the=20head?=
 =?UTF-8?q?ers;=20HSTS=20toggles=20with=20SECURE=5FCOOKIES).=20Stability-r?=
 =?UTF-8?q?eviewer=20on=20the=20diff:=20APPROVE,=20no=20Critical/High=20(L?=
 =?UTF-8?q?ow:=20a=20CDN/absolute=20branding=20logo=20would=20be=20CSP-blo?=
 =?UTF-8?q?cked=20=E2=86=92=20documented=20the=20same-origin-logo=20constr?=
 =?UTF-8?q?aint).=20README=20Status=20+=20Production=20+=20Layout=20update?=
 =?UTF-8?q?d.=20typecheck=20+=20312=20units=20green.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                    | 15 +++++++++++---
 src/app.test.ts              | 19 ++++++++++++++++++
 src/app.ts                   |  7 +++++++
 src/security-headers.test.ts | 26 ++++++++++++++++++++++++
 src/security-headers.ts      | 39 ++++++++++++++++++++++++++++++++++++
 todo.md                      |  2 +-
 6 files changed, 104 insertions(+), 4 deletions(-)
 create mode 100644 src/security-headers.test.ts
 create mode 100644 src/security-headers.ts

diff --git a/README.md b/README.md
index 549c9e5..fd8d361 100644
--- a/README.md
+++ b/README.md
@@ -52,9 +52,9 @@ only where the platform leaves a gap (see [AGENTS.md](AGENTS.md)).
 > `config/menu.ts` override + branding), the **Ory stack** (Postgres, Kratos + the session→JWT
 > tokenizer, Keto, Hydra), the **auth** wiring that consumes it (themed sign-in / register / reset /
 > SSO, the session→JWT hot path, the users/groups/roles admin screens) and **Hydra's login / consent
-> / logout handlers** — all driven end-to-end by the Playwright suites. What's left is mainly
-> **production & ops hardening** (the prod compose profile, security headers, observability, a
-> key-rotation runbook) — tracked in `todo.md` (§9).
+> / logout handlers** — all driven end-to-end by the Playwright suites, plus **production & ops
+> hardening** (the prod compose profile, response security headers). What's left is mainly
+> **observability and a key-rotation runbook** — tracked in `todo.md` (§9).
 
 ## The MVP — "clone, one command, hack on a plugin"
 
@@ -578,6 +578,14 @@ Before going live, supply the production secrets and any SSO credentials — the
 manual prep ([What you must supply](#what-you-must-supply-the-only-manual-prep)); the rest
 is auto-generated.
 
+Every response carries security headers (`src/security-headers.ts`, set once per request): a
+strict `Content-Security-Policy` (the core is **zero-JS** — `script-src 'self'`, no inline
+scripts, so an injected `<script>` can't run), `X-Content-Type-Options: nosniff`,
+`X-Frame-Options: DENY` + `frame-ancestors 'none'`, `Referrer-Policy`, and — when
+`SECURE_COOKIES=true` (https) — HSTS. The CSP allows **same-origin** assets only, so a branding
+logo must live under `/public/` (or be a `data:` URI); a plugin route can override any header
+per-response via `RouteResult.headers` (e.g. to ship its own JS).
+
 The server drains in-flight requests on `SIGTERM`/`SIGINT` rather than cutting them
 mid-response, so container restarts are clean.
 
@@ -602,6 +610,7 @@ src/gen-jwks.ts      generateJwks() + CLI: mint the ES256 session-tokenizer sign
 src/bootstrap.ts     One-command bootstrap (§3): idempotent first-boot seed — JWKS-if-absent, demo admin in Kratos, admin role in Keto
 src/cookie.ts        Cookie parse + secure Set-Cookie build (session/CSRF cookies, §4)
 src/csrf.ts          CSRF for our own POST forms (§4): signed double-submit token — issue/verify, cookie, request gate
+src/security-headers.ts Response security headers set on every reply (§9): strict CSP (zero-JS), nosniff, X-Frame-Options/frame-ancestors, Referrer-Policy, HSTS over https
 src/body.ts          readFormBody(): read + size-cap an x-www-form-urlencoded request body (CSRF gate + §5 forms)
 src/context.ts       RequestContext handed to handlers + buildContext()
 src/config.ts        Env loader — Ory endpoints, cookie/CSRF secrets, JWKS, port; validated at boot
diff --git a/src/app.test.ts b/src/app.test.ts
index 8bd50c2..deb1436 100644
--- a/src/app.test.ts
+++ b/src/app.test.ts
@@ -82,6 +82,25 @@ test("static serving: GET sends body + content-type, HEAD headers only, unsafe p
   assert.equal((await fetch(base + "/public/%00")).status, 403);
 });
 
+test("every response carries the security headers; HSTS follows SECURE_COOKIES (§9)", async (t) => {
+  // Default app (secureCookies off): a page and a static asset both carry the hardening headers,
+  // proving they're set once up front and survive each writeHead (the html + static paths merge).
+  for (const path of ["/", "/public/css/styles.css"]) {
+    const res = await fetch(base + path);
+    assert.equal(res.headers.get("x-content-type-options"), "nosniff", path);
+    assert.equal(res.headers.get("x-frame-options"), "DENY", path);
+    assert.match(res.headers.get("content-security-policy") ?? "", /default-src 'self'/, path);
+    assert.equal(res.headers.get("strict-transport-security"), null, path); // http dev → no HSTS
+  }
+
+  // A https deployment (SECURE_COOKIES=true) adds HSTS.
+  const secure = createApp({ secureCookies: true });
+  await new Promise<void>((r) => secure.listen(0, r));
+  t.after(() => secure.close());
+  const res = await fetch(`http://localhost:${(secure.address() as AddressInfo).port}/`);
+  assert.match(res.headers.get("strict-transport-security") ?? "", /max-age=\d+/);
+});
+
 // Production caches compiled templates; rendering must stay correct across repeated requests.
 test("renders correctly with template caching enabled", async () => {
   const app = createApp({ cache: true });
diff --git a/src/app.ts b/src/app.ts
index a7e1a48..1008127 100644
--- a/src/app.ts
+++ b/src/app.ts
@@ -29,6 +29,7 @@ import { acceptConsent, rejectConsent, resolveConsentChallenge } from "./oauth-c
 import { DEFAULT_MENU, type MenuConfig } from "./menu-config.ts";
 import type { Plugin, RouteResult } from "./plugin.ts";
 import { allowedMethods, isAuthorized, matchRoute } from "./router.ts";
+import { securityHeaders } from "./security-headers.ts";
 import { routePublic, serveStatic } from "./static.ts";
 import { renderPluginView } from "./view-resolver.ts";
 
@@ -72,6 +73,8 @@ export function createApp(options: AppOptions = {}): Server {
   const pluginsDir = options.pluginsDir ?? PLUGINS_DIR;
   const publicDir = options.publicDir ?? join(rootDir, "public");
   const viewsDir = options.viewsDir ?? join(rootDir, "views");
+  // Response security headers, fixed at boot (only HSTS depends on the https deployment signal).
+  const secHeaderEntries = Object.entries(securityHeaders({ secure: secureCookies }));
 
   // `views: [viewsDir]` lets a view in a subfolder (e.g. admin/users.ejs) include() the shared
   // partials/ by the same root-relative name top-level views use (EJS tries relative first).
@@ -101,6 +104,10 @@ export function createApp(options: AppOptions = {}): Server {
       const method = req.method ?? "GET";
       const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
 
+      // Set before any branch so every response — static/redirect/error included — inherits them
+      // (writeHead merges these with its own headers; a plugin's RouteResult.headers can override).
+      for (const [name, value] of secHeaderEntries) res.setHeader(name, value);
+
       if (pathname.startsWith("/public/") && (method === "GET" || method === "HEAD")) {
         // /public/<id>/… serves a plugin's public/; everything else the core public/.
         // Before auth: assets don't need a verified user, and the JWT cookie rides every request.
diff --git a/src/security-headers.test.ts b/src/security-headers.test.ts
new file mode 100644
index 0000000..52cf489
--- /dev/null
+++ b/src/security-headers.test.ts
@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { securityHeaders } from "./security-headers.ts";
+
+test("securityHeaders: strict zero-JS defaults; HSTS only over https", () => {
+  const h = securityHeaders();
+  // Always-on hardening, independent of scheme.
+  assert.equal(h["x-content-type-options"], "nosniff");
+  assert.equal(h["x-frame-options"], "DENY");
+  assert.equal(h["referrer-policy"], "strict-origin-when-cross-origin");
+  assert.equal(h["cross-origin-opener-policy"], "same-origin");
+
+  const csp = h["content-security-policy"] ?? "";
+  assert.match(csp, /default-src 'self'/);
+  assert.match(csp, /script-src 'self'/); // a plugin may ship its own JS; the core ships none
+  assert.doesNotMatch(csp, /script-src[^;]*'unsafe-inline'/); // an injected <script> can't run
+  assert.match(csp, /style-src 'self' 'unsafe-inline'/); // a few partials use inline style= attrs
+  assert.match(csp, /frame-ancestors 'none'/); // clickjacking guard (modern X-Frame-Options)
+  assert.match(csp, /object-src 'none'/);
+  assert.doesNotMatch(csp, /form-action/); // omitted: the themed login posts to Kratos' (cross-origin) action
+
+  // No HSTS on the dev http origin…
+  assert.equal(h["strict-transport-security"], undefined);
+  // …but present once the deployment is https.
+  assert.match(securityHeaders({ secure: true })["strict-transport-security"] ?? "", /max-age=\d+; includeSubDomains/);
+});
diff --git a/src/security-headers.ts b/src/security-headers.ts
new file mode 100644
index 0000000..e00e185
--- /dev/null
+++ b/src/security-headers.ts
@@ -0,0 +1,39 @@
+// Response security headers (todo §9): set once per request in app.ts so every response — page,
+// JSON, redirect, static, or error — carries them (writeHead merges with setHeader). A plugin route
+// may override any of them per-response via RouteResult.headers (e.g. relax the CSP to ship its own JS).
+
+// Strict default CSP for the zero-JS, server-rendered core:
+//  - script-src 'self'  : the core ships no JS; a plugin may still serve its own /public/<id>/*.js for
+//                         opt-in progressive enhancement. No 'unsafe-inline' ⇒ an injected <script>
+//                         can't run (the main XSS sink).
+//  - style-src adds 'unsafe-inline' : a few partials carry inline style= attributes.
+//  - img-src adds data:             : favicon + inline data URIs.
+//  - no form-action     : the themed login form posts to Kratos' (often cross-origin) action URL.
+//  - frame-ancestors 'none' : clickjacking guard (the modern X-Frame-Options).
+const CSP = [
+  "base-uri 'self'",
+  "default-src 'self'",
+  "frame-ancestors 'none'",
+  "img-src 'self' data:",
+  "object-src 'none'",
+  "script-src 'self'",
+  "style-src 'self' 'unsafe-inline'",
+].join("; ");
+
+export interface SecurityHeaderOptions {
+  secure?: boolean; // https deployment (mirrors SECURE_COOKIES) → also emit HSTS
+}
+
+// The header set applied to every response.
+export function securityHeaders(options: SecurityHeaderOptions = {}): Record<string, string> {
+  const headers: Record<string, string> = {
+    "content-security-policy": CSP,
+    "cross-origin-opener-policy": "same-origin",
+    "referrer-policy": "strict-origin-when-cross-origin",
+    "x-content-type-options": "nosniff",
+    "x-frame-options": "DENY",
+  };
+  // HSTS only over https — ignored (and meaningless) on the dev http origin.
+  if (options.secure) headers["strict-transport-security"] = "max-age=31536000; includeSubDomains";
+  return headers;
+}
diff --git a/todo.md b/todo.md
index 1fad5b1..8fa6e04 100644
--- a/todo.md
+++ b/todo.md
@@ -126,7 +126,7 @@ everything via Docker.
 
 ## 9. Production, security, ops
 - [x] `compose.yml` prod: Ory + Postgres, secrets via env, no source mount. → The base file was already the full prod stack (web + Postgres + Kratos/Keto/Hydra + migrations + the one-shot bootstrap; `.:/app` lives only in the dev override), built during §3. **The real gap, now closed:** it set `REQUIRE_SECURE_SECRETS=true` but never wired `CSRF_SECRET` into `web`, so `docker compose -f compose.yml up` couldn't boot. Added `CSRF_SECRET: ${CSRF_SECRET:-dev-insecure-csrf-secret}` — env-supplied with the throwaway as the only fallback; `config.ts`'s existing `REQUIRE_SECURE_SECRETS` logic rejects that throwaway, so a forgotten prod secret **fails loud** (verified all three paths: prod-unset→reject, prod-set→real secret, dev→throwaway + toggle off → boots). Used `:-` not `:?` because compose interpolates the base file per-file *before* merging the override (confirmed empirically), so a `:?` in the base would also break the zero-config dev `docker compose up`. Tests-first: extended `compose.test.ts` (secret-via-env + no-source-mount + the prod/dev toggle split + postgres-creds-via-env). README prod section corrected (dropped the stale "_(… Ory + Postgres — planned)_"). typecheck + 310 units green.
-- [ ] Security headers; secure/HttpOnly/SameSite cookies; CSRF; clock-skew tolerance.
+- [x] Security headers; secure/HttpOnly/SameSite cookies; CSRF; clock-skew tolerance. → Cookies (HttpOnly · SameSite=Lax · Secure-when-`SECURE_COOKIES`, `src/cookie.ts`), the signed double-submit CSRF (`src/csrf.ts`), and JWT clock-skew leeway (`JWT_CLOCK_SKEW_SEC`, applied to exp+nbf in `validateClaims`) all landed in §4 — the open gap was **response security headers**, now closed. New pure `src/security-headers.ts` (`securityHeaders({secure})`): a strict CSP for the zero-JS core — `default-src 'self'`, `script-src 'self'` with **no** `'unsafe-inline'` (an injected `<script>` can't run; core ships none, a plugin may still serve its own `/public/<id>/*.js`), `style-src` adds `'unsafe-inline'` for the partials' inline `style=`, `img-src 'self' data:`, `frame-ancestors 'none'`, `object-src 'none'`; **`form-action` deliberately omitted** (the themed login POSTs to Kratos' often-cross-origin action URL) — plus `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`, `Cross-Origin-Opener-Policy: same-origin`, and HSTS only when `secureCookies` (https; ignored on dev http). Wired in `app.ts`: precomputed once at boot, `res.setHeader`'d at the very top of the handler before any branch, so **every** response (page/json/redirect/static/error/plugin) inherits them via `writeHead`'s merge; a plugin overrides per-route via `RouteResult.headers`. Verified no view/CSS loads cross-origin (no `<script>` anywhere, no external fonts/CDNs), so `default-src 'self'` breaks nothing. Tests-first: `security-headers.test.ts` (strict defaults, `script-src` has no `'unsafe-inline'`, HSTS-only-on-secure) + an `app.test.ts` integration (the page **and** a static asset both carry the headers; HSTS toggles with `SECURE_COOKIES`). Stability-reviewer on the diff: **APPROVE, no Critical/High** (Low: a CDN/absolute branding logo would be CSP-blocked → documented the same-origin-logo constraint). README Status + Production + Layout updated. typecheck + 312 units green.
 - [ ] Optional revocation denylist for instant role/session revoke.
 - [ ] Structured logging / basic observability. use @larvit/log for OTLP compability dig down in how to use it properly.
 - [ ] JWT signing-key rotation runbook.