Security headers
Ce contenu n’est pas encore disponible dans votre langue.
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.
It covers its whole subtree, rejections included: a layer below it that
short-circuits by throwing HttpError — CSRF, auth, a rate limit — produces
a response that carries the headers 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
Section titled “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.
The bundle is code-only: there is no configuration block for it, in
securityHeaders(...) or in withSecurityHeaders(...), and that is a decision
rather than a gap. Server-wide, withSecurityHeaders(...) has three states —
never called, so the backend’s own nosniff stands; false, so no header at
all; options, so the full bundle — and a block in application.conf would
have to layer under all three without replacing a backend’s defaults on a
server that never asked for the bundle. The hsts field is code-only with the
rest: what a deployment can set from a file is the policy hsts() sends,
through actor-ts.http.hsts — see below.
HSTS on its own — strictTransportSecurity
Section titled “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.
From the configuration file
Section titled “From the configuration file”Every field of the policy also has a key in actor-ts.http.hsts —
max-age (in seconds, a bare integer), include-sub-domains and preload.
What hsts(options) names in code wins per field, then the block, then the
built-in default, and the merged policy is validated once, when bind()
compiles the route tree:
actor-ts.http.hsts { max-age = 63072000 # seconds — two years, not a duration string}A max-age below 86400 — one day — is refused there with a ConfigError
naming the key and the floor: 0 would un-pin every client of every hsts()
route in the process at once, and a shorter pin than a day lapses before a
visitor comes back the next day. Code may still set any value (withMaxAge(0)
switches HSTS off). The keys and their defaults are in
Configuration → actor-ts.http.
The block reaches hsts() through a hook that compile() resolves, so hand
the middleware to withMiddleware(...) as it is. Wrapped in a function of your
own — (request, next) => hsts()(request, next) — it is out of compile()’s
sight and sends the code options over the built-in defaults. bind() logs a
warning naming the block when it is configured and no hsts() in the tree
read it.
Two emission paths
Section titled “Two emission paths”HSTS reaches a response one of two ways, and the block governs only one:
| Path | Configured from |
|---|---|
hsts() / strictTransportSecurity() | code options, then actor-ts.http.hsts, then the built-in default |
the hsts field of securityHeaders() and of withSecurityHeaders(...) | code only |
Where both send the header, the route level wins. A middleware never
overwrites a header the response already carries, so of the route-level
middleware the one closest to the handler sets it, and the server-wide
withSecurityHeaders(...) map is written underneath whatever the response
carries. So a route under hsts() gets the configured policy even on a server
whose withSecurityHeaders({ hsts }) names another one, and only the responses
no route-level HSTS reaches — a body-parse 413, say — carry the server-wide
policy. The backend’s own 404 for a path no route matches carries none, on
every backend: it is answered outside every decorator. A tree that ends in a
fallback(...) answers that 404 itself, and then it carries the policy
(#1059).
Over a WebSocket route
Section titled “Over a WebSocket route”securityHeaders() may wrap a websocket() route like any other — the
upgrade completes. What it decorates there is the rejection: a
handshake an inner auth middleware refuses comes back carrying these
headers. An accepted handshake does not, because the backend writes that
101 response itself. So wrap the whole tree, socket included, rather than
carving the socket out. See WebSocket.
