Security headers

securityHeaders() adds a sensible set of security response headers. Every header is individually overridable, false leaves one out, and a header the handler already set always wins.

`false` omits a header, it does not remove one

The bundle only ever adds headers. As a middleware it runs on top of what the backend already writes, so false means “this middleware does not add it” — not “this response will not carry it”.

That distinction is visible in exactly one place today. X-Content-Type-Options: nosniff is written by every backend ahead of every response it emits, so securityHeaders({ contentTypeOptions: false }) leaves the header in place. To stop sending it, replace the backend’s defaults server-wide with newServerAt(…).withSecurityHeaders({ contentTypeOptions: false }) — or withSecurityHeaders(false) for none of them at all.

There is no per-subtree opt-out, deliberately: the backend’s copy is the last word precisely so that the 404s, body-parse 413s and error short-circuits which never reach a middleware are covered too.

import { securityHeaders, withMiddleware } from 'actor-ts/http';

const routes = withMiddleware(securityHeaders(), appRoutes);

Defaults: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer, Cross-Origin-Opener-Policy: same-origin, Cross-Origin-Resource-Policy: same-origin, and X-XSS-Protection: 0 (the legacy filter is buggy — off is safest). COEP, Permissions-Policy, and HSTS are opt-in.

Configuration

Builder method	Default
withContentTypeOptions(flag?)	nosniff on
withFrameOptions('DENY' | 'SAMEORIGIN' | false)	'DENY'
withReferrerPolicy(value | false)	'no-referrer'
withCrossOriginOpenerPolicy(v | false)	'same-origin'
withCrossOriginResourcePolicy(v | false)	'same-origin'
withCrossOriginEmbedderPolicy(v | false)	false (breaks embeds; opt-in)
withPermissionsPolicy(map | false)	false
withHsts(options | false)	false (opt-in)

const options = SecurityHeadersOptions.create()
  .withFrameOptions('SAMEORIGIN')
  .withHsts({ maxAge: 31_536_000, preload: true });

CSP is deliberately not part of the bundle — it is too app-specific; configure it with contentSecurityPolicy.

HSTS on its own — strictTransportSecurity

import { strictTransportSecurity, HstsOptions, withMiddleware } from 'actor-ts/http';

const hsts = strictTransportSecurity(
  HstsOptions.create().withMaxAge(31_536_000).withIncludeSubDomains().withPreload(),
);

Defaults: max-age 180 days + includeSubDomains. The header is set unconditionally — a browser ignores it over plain HTTP, so a dev server is a harmless no-op, and framework servers usually sit behind a TLS-terminating proxy anyway.

preload is a commitment

withPreload() requires maxAge ≥ 1 year + includeSubDomains (the hstspreload.org rules — enforced at construction). Submitting to the preload list is hard to undo; be sure every subdomain serves HTTPS first.

Where to next

• CSP — Content-Security-Policy.
• CORS — cross-origin requests.
• Security — the full recommended stack.