Zum Inhalt springen
Deutsch

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.

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

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.

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.

HSTS erreicht eine Response auf einem von zwei Wegen, und der Block steuert nur einen davon:

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

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.

  • CSP — Content-Security-Policy.
  • CORS — Cross-Origin-Requests.
  • Sicherheit — der vollständige empfohlene Stack.