Name authentication middleware and add http.securityHeaders config

[kriszyp]

Summary

Two small core enablers for an upcoming WAF middleware component:

1. Explicitly named authentication middleware — honesty note: this is contract-hardening, not new behavior. Middleware entries already default their name to the registering component's name (name: options?.name ?? getComponentName() in server/http.ts), and the auth plugin loads under the authentication config key — so before: 'authentication' / after: 'authentication' ordering (used today by REST, MQTT, GraphQL, MCP, and static.ts) already resolved correctly. This change makes the name an explicit, test-locked contract so a future rename of the config/registry key can't silently break every consumer that targets 'authentication'. No chain-order behavior changes.

   The operations-API registrations in server/operationsServer.ts are a genuine (if inert) name change: they previously defaulted to the operationsApi component name and now register as authentication. Nothing in-repo targets 'operationsApi' as a middleware name, and those chains are bypassed for real ops traffic (see caveat below), so this is forward-compat consistency only.

2. http.securityHeaders config block — a zero-code way for ops to add response headers like X-Frame-Options / X-Content-Type-Options:

   http:
     securityHeaders:
       X-Frame-Options: SAMEORIGIN
       X-Content-Type-Options: nosniff

   Applied on app ports across all response paths of the Harper-native request handler: the normal writeHead path, handlesHeaders streams (static files — where the send() stream writes its own headers, universal headers are pre-set so the stream can still override its own names), thrown-error responses, and the Fastify status === -1 cascade. Node and Bun handlers both covered.

   • Precedence: app wins. Configured headers are defaults — a header the application/route already set on a response is never overridden (a route's X-Frame-Options: DENY is not loosened by a configured SAMEORIGIN).
   • Validation: names/values validated with node:http's validateHeaderName/validateHeaderValue; invalid entries (and non-object block values) are logged and skipped, never thrown.
   • Hot-reload: via the existing scope.options.on('change') path; the feature tracks exactly the entries it pushed into universalHeaders and splices only those, preserving entries pushed by other components. Only the first (root) http scope owns the config — an application config.yaml with an http: block cannot wipe root-configured headers.
   • Opt-in / no behavior change: absent block ⇒ nothing added; all per-response loops are guarded by universalHeaders.length so unconfigured deployments skip them.

Where to look

• server/http.ts — applySecurityHeaders() (ownership-tracked splice, root-scope guard) and the four response-path application sites.
• Scope caveat: the operations API doesn't carry these headers in normal mode — not because ops requests bypass the request handler (they don't; they cascade to Fastify through it), but because the ops API runs on the main thread, which loads components with resources.isWorker = false, so http's handleApplication never populates the main thread's per-thread universalHeaders. With threads: 0 the ops API shares a worker and would carry them (benign). Detailed in DESIGN.md. Flagging in case ops-API parity is wanted later.
• server/operationsServer.ts — ops-API auth registrations get name: 'authentication' for consistency (forward-compat naming, not a behavior change).

Tests

• unitTests/server/securityHeaders.test.js (new): apply/coerce/validate/non-object-reject/hot-reload-swap semantics, "don't clobber other components' entries", and root-scope ownership vs a second app scope.
• unitTests/server/middlewareChain.test.js: new case proving a before: 'authentication' entry executes before auth regardless of registration order.
• unitTests/security/auth.test.js: asserts handleApplication registers the auth listener under name: 'authentication'.
• unitTests/validation/configValidator.test.js: 4 new schema cases (absent/map/coercible/rejected).
• integrationTests/server/security-headers.test.ts + fixture app (new): real Harper instance — headers on 200 REST, 404 cascade, static-file (handlesHeaders), and thrown-error responses; app-set header wins over config; absent config adds nothing.

---

Generated by KrAIs (Claude, Fable 5 model) via Claude Code.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces the http.securityHeaders configuration option, allowing users to define custom response headers (such as X-Frame-Options) that are appended to REST/app HTTP responses. It includes robust hot-reloading logic to update these headers dynamically without clobbering headers registered by other components, alongside comprehensive unit and integration tests. The review feedback suggests two key improvements: using Object.entries() instead of a for...in loop to avoid iterating over inherited properties, and wrapping test cleanup in a try...finally block to prevent test pollution in case of assertion failures.

[claude]

Reviewed; no blockers found.

[kriszyp]

Cross-model review disposition (Gemini via agy, full diff):

• Accepted + fixed (d405d48): Bun thrown-error path now merges error.headers (previously dropped on Bun — pre-existing gap, fixed while touching the path; error headers win over configured universal headers, mirroring Node); applySecurityHeaders rejects arrays.
• Documented as known limitation: a handler that synchronously calls writeHead before returning handlesHeaders: true cannot receive universal headers (headers already sent; no in-tree component does this).
• Refuted: claimed app-header clobber on the Bun handlesHeaders path — responseHeaders is empty at the point universal headers are set, and the stream's later setHeader calls overwrite, so app/stream wins by ordering.
• Declined (nit): universal headers on the catastrophic Fastify-inject-failure handlers — dead-rare path, not worth the code.

An independent fresh-context review earlier drove commit 6300e32 (response-path coverage + app-wins precedence). — KrAIs (Claude)

🤖 Generated with Claude Code

[heskew]

Header application traced across all four response paths (Node http/http2, Bun, uWS, error); case-mismatch bypass ruled out; the operationsApi→authentication rename has no old-name consumers. Checked the threads: 0 duplicate-registration concern: handleApplication is worker-only with a started idempotency guard, the ops-server registration is main-only (deliberate, per the code comment), and they target different ports — worst case is redundant fail-closed auth, never a bypass. LGTM.

_{🤖 Reviewed via cross-model pipeline; approved by @heskew.}