Security-Header
securityHeaders() ergänzt ein sinnvolles Set an Security-Response-Headern.
Jeder Header ist einzeln überschreibbar, false lässt einen weg, und ein
vom Handler bereits gesetzter Header gewinnt immer.
Abgedeckt ist der gesamte Teilbaum, Ablehnungen eingeschlossen: Eine
Schicht darunter, die per HttpError kurzschließt — CSRF, Auth, ein
Rate-Limit —, erzeugt eine Response, die die Header ebenfalls trägt.
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 und X-XSS-Protection: 0 (der
Legacy-Filter ist fehlerhaft — aus ist am sichersten). COEP,
Permissions-Policy und HSTS sind opt-in.
Konfiguration
Abschnitt betitelt „Konfiguration“| Builder-Methode | Default |
|---|---|
withContentTypeOptions(flag?) | nosniff an |
withFrameOptions('DENY' | 'SAMEORIGIN' | false) | 'DENY' |
withReferrerPolicy(value | false) | 'no-referrer' |
withCrossOriginOpenerPolicy(v | false) | 'same-origin' |
withCrossOriginResourcePolicy(v | false) | 'same-origin' |
withCrossOriginEmbedderPolicy(v | false) | false (bricht 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 ist bewusst nicht Teil des Bündels — es ist zu app-spezifisch;
konfiguriere es mit contentSecurityPolicy.
Das Bündel ist nur im Code erreichbar: Es gibt keinen Konfigurationsblock
dafür, weder für securityHeaders(...) noch für withSecurityHeaders(...),
und das ist eine Entscheidung, keine Lücke. Serverweit hat
withSecurityHeaders(...) drei Zustände — nie aufgerufen, dann bleibt das
eigene nosniff des Backends; false, dann gar kein Header; Optionen, dann
das volle Bündel —, und ein Block in der application.conf müsste sich unter
alle drei schieben, ohne auf einem Server, der das Bündel nie verlangt hat,
die Defaults des Backends zu ersetzen. Das hsts-Feld ist mit dem Rest nur im
Code erreichbar: Was ein Deployment aus einer Datei setzen kann, ist die Policy,
die hsts() sendet, über actor-ts.http.hsts — siehe unten.
HSTS allein — strictTransportSecurity
Abschnitt betitelt „HSTS allein — strictTransportSecurity“import { strictTransportSecurity, HstsOptions, withMiddleware } from 'actor-ts/http';
const hsts = strictTransportSecurity( HstsOptions.create().withMaxAge(31_536_000).withIncludeSubDomains().withPreload(),);Defaults: max-age 180 Tage + includeSubDomains. Der Header wird
bedingungslos gesetzt — ein Browser ignoriert ihn über reines HTTP, ein
Dev-Server ist also ein harmloser No-op, und Framework-Server sitzen ohnehin
meist hinter einem TLS-terminierenden Proxy.
Aus der Konfigurationsdatei
Abschnitt betitelt „Aus der Konfigurationsdatei“Jedes Feld der Policy hat auch einen Key in actor-ts.http.hsts —
max-age (in Sekunden, eine blanke Ganzzahl), include-sub-domains und
preload. Was hsts(options) im Code nennt, gewinnt pro Feld, dann der
Block, dann der eingebaute Default, und die gemergte Policy wird einmal
validiert, wenn bind() den Route-Baum kompiliert:
actor-ts.http.hsts { max-age = 63072000 # seconds — two years, not a duration string}Ein max-age unter 86400 — einem Tag — wird dort mit einem ConfigError
abgelehnt, der den Key und die Untergrenze nennt: 0 würde jeden Client jeder
hsts()-Route im Prozess sofort entpinnen, und ein kürzerer Pin als ein Tag
läuft ab, bevor ein Besucher am nächsten Tag wiederkommt. Code darf weiterhin
jeden Wert setzen (withMaxAge(0) schaltet HSTS ab). Die Keys und ihre Defaults stehen in
Konfiguration → actor-ts.http.
Der Block erreicht hsts() über einen Hook, den compile() auflöst — gib die
Middleware also so, wie sie ist, an withMiddleware(...). In eine eigene
Funktion verpackt — (request, next) => hsts()(request, next) — ist sie für
compile() unsichtbar und sendet die Code-Optionen über den eingebauten
Defaults. bind() schreibt eine Warnung mit dem Block ins Log, wenn er
konfiguriert ist und kein hsts() im Baum ihn gelesen hat.
Zwei Wege zum Header
Abschnitt betitelt „Zwei Wege zum Header“HSTS erreicht eine Response auf einem von zwei Wegen, und der Block steuert nur einen davon:
| Weg | Konfiguriert aus |
|---|---|
hsts() / strictTransportSecurity() | Code-Optionen, dann actor-ts.http.hsts, dann der eingebaute Default |
das hsts-Feld von securityHeaders() und von withSecurityHeaders(...) | nur Code |
Wo beide den Header senden, gewinnt die Routenebene. Eine Middleware
überschreibt nie einen Header, den die Response schon trägt; von den
Middlewares auf Routenebene setzt ihn also die, die dem Handler am nächsten
ist, und die serverweite Map von withSecurityHeaders(...) wird unter das
geschrieben, was die Response trägt. Eine Route unter hsts() bekommt die
konfigurierte Policy also auch auf einem Server, dessen
withSecurityHeaders({ hsts }) eine andere nennt, und nur die Responses, die
kein HSTS auf Routenebene erreicht — ein 413 aus dem Body-Parsing etwa —,
tragen die serverweite Policy. Der eigene 404 des Backends für einen Pfad,
auf den keine Route passt, trägt keine, auf keinem Backend: Er wird außerhalb
jedes Decorators beantwortet. Ein Baum, der mit einem fallback(...) endet,
beantwortet diesen 404 selbst, und dann trägt er die Policy
(#1059).
Über einer WebSocket-Route
Abschnitt betitelt „Über einer WebSocket-Route“securityHeaders() darf eine websocket()-Route umschließen wie jede
andere — das Upgrade kommt zustande. Dekoriert wird dort die
Ablehnung: Ein Handshake, den eine innere Auth-Middleware abweist,
kommt mit diesen Headern zurück. Ein angenommener Handshake nicht, denn
diese 101-Antwort schreibt das Backend selbst. Wickle also den ganzen
Baum ein, Socket eingeschlossen, statt den Socket auszuschneiden. Siehe
WebSocket.
Wie weiter
Abschnitt betitelt „Wie weiter“- CSP — Content-Security-Policy.
- CORS — Cross-Origin-Requests.
- Sicherheit — der vollständige empfohlene Stack.
