Zum Inhalt springen
Deutsch

CORS

CORS ist eine Route-Direktive, keine gewöhnliche Middleware — ein Preflight-OPTIONS-Request passt nie auf eine methoden-spezifische Route, eine Middleware würde dafür also nie laufen. cors(options, child) ist eine eigene Direktive, die der Compiler expandiert: sie dekoriert die echten Responses mit den CORS-Headern und synthetisiert für jedes Pattern in child eine OPTIONS-Preflight-Route.

import { cors, CorsOptions, concat, get, path, post } from 'actor-ts/http';
const corsOptions = CorsOptions.create()
.withOrigins('https://app.example', 'https://admin.example')
.withCredentials();
const routes = cors(corsOptions, path('api', concat(
get(listHandler),
post(createHandler),
)));

Der Compiler fügt OPTIONS /api automatisch hinzu; ein Browser-Preflight erhält 204 mit den Access-Control-Allow-*-Headern, und die eigentlichen GET/POST-Responses erhalten Access-Control-Allow-Origin + Vary: Origin.

Builder-MethodeFeldZweck
withOrigins(...o)originsExakte Allowlist. Config: origins.
withAnyOrigin()originsJeden Origin erlauben (*). Muss explizit sein — nur im Code.
withOriginPredicate(predicate)originsPro Request entscheiden; ein werfendes Prädikat verweigert. Nur im Code. Ein Prädikat, das einen nicht wohlgeformten Origin akzeptiert, verweigert ebenfalls — siehe unten.
withMethods(...m)methodsAccess-Control-Allow-Methods. Default: die am Pattern registrierten Methoden. Config: methods.
withAllowedHeaders(...h)allowedHeadersDefault: die Header-Namen des Requests echoen, gefiltert auf RFC-7230-Tokens — ein Name mit irgendetwas anderem darin fällt ganz weg, und bleibt nichts übrig, entfällt das Feld. Siehe unten. Config: allowed-headers.
withExposedHeaders(...h)exposedHeadersAccess-Control-Expose-Headers. Config: exposed-headers.
withCredentials(flag?)credentialsAccess-Control-Allow-Credentials: true. Config: credentials.
withMaxAge(seconds)maxAgePreflight-Cache-Dauer. Config: max-age.

Jedes Feld außer der Wildcard und dem Prädikat ist auch über actor-ts.http.cors setzbar, unter demselben Namen in kebab-case — origins, methods, allowed-headers, exposed-headers, credentials, max-age. Es gilt die übliche Reihenfolge, pro Feld: Was die Route im Code nennt, gewinnt, dann der Config-Block, dann der eingebaute Default. Die Allowlist kann also in der application.conf liegen, während withCredentials() im Code bleibt — beides wirkt.

actor-ts.http.cors {
origins = ["https://app.example", "https://admin.example"]
max-age = 600 # Sekunden — kein Duration-String
}

Die beiden oben als nur im Code markierten Arme sind genau das: Für keinen von beiden gibt es einen Key. Ein origins = ["*"] in einer Config-Datei wird mit einem ConfigError abgelehnt, der den Key nennt — eine Zeile, die jede cors()-Route im Prozess auf jeden Origin öffnet, ist genau das, was das „muss explizit sein“ von withAnyOrigin() verhindern soll. Und ein Prädikat ist eine Funktion, die HOCON gar nicht ausdrücken kann.

methods, allowed-headers und max-age liefern in reference.conf keinen Wert aus, weil jedes einen Default hat, den ein publizierter Literalwert zerstören würde: die am Pattern tatsächlich registrierten Methoden, die geechoten Request-Header und „gar kein Access-Control-Max-Age senden“. origins liefert ebenfalls keinen, damit ein cors() ohne jede Allowlist ein lauter Fehler bleibt und kein stilles Deny-all wird. Gelesen werden alle vier trotzdem, sobald ein Deployment sie setzt. Die Tabelle steht unter Konfiguration → actor-ts.http.

Access-Control-Allow-Origin echot den Request-Origin (das literale * wird nur bei withAnyOrigin() ohne Credentials gesendet), und Vary: Origin wird ergänzt, sobald der Origin geechot wird, damit Caches nicht falsch ausliefern. Das Ergänzen ist case-insensitiv und additiv: Ein Handler, der bereits mit Vary: Cookie geantwortet hat, behält dieses Feld — die Response geht als ein einzelnes Vary: Cookie, Origin raus.

  • Security-Header — die begleitenden Response-Header.
  • CSRF — Schutz vor Cross-Site Request Forgery.
  • Sicherheit — der empfohlene Stack + Reihenfolge.