Aller au contenu
Français

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.

Builder methodDefault
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.

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.

HSTS reaches a response one of two ways, and the block governs only one:

PathConfigured 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).

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.

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