Security best practices
The framework ships the pieces; this page is how to assemble them. The
runnable counterpart is examples/http/secure-service.ts.
The recommended stack
Section titled “The recommended stack”Order matters — outermost first:
import { concat, cors, csrfProtection, fallback, handleErrors, path, requestId, requestTimeout, securityHeaders, withMiddleware, CorsOptions, CsrfOptions,} from 'actor-ts/http';
const corsOptions = CorsOptions.create().withOrigins('https://app.example').withCredentials();const csrf = csrfProtection(CsrfOptions.create().withSecret(process.env.CSRF_SECRET!));
const routes = withMiddleware(requestId(), withMiddleware(securityHeaders(), cors(corsOptions, withMiddleware(requestTimeout(15_000), handleErrors(errorMapper, withMiddleware(csrf, concat( appRoutes, fallback(notFound), )))))));| Layer | Why here |
|---|---|
requestId | outermost, so every log line (including errors) has an id |
securityHeaders | above everything that rejects, so those responses carry the headers too |
cors | outside auth — preflights are anonymous by spec |
requestTimeout | bound latency before doing real work |
handleErrors | outside csrf, so it maps that middleware’s own 403 — and inside the header layers, so what it hands back still flows through them |
csrf | browser apps only; after CORS, before handlers |
fallback | at the root — answers anything unmatched |
What every response already carries
Section titled “What every response already carries”X-Content-Type-Options: nosniff needs no setup. The backend writes it,
not a middleware, so it also reaches the responses no middleware sees: the
backend’s own error mapping, the fallback 404 and the body-too-large 413.
A handler’s own header still wins.
It is the only one on by default, deliberately — it is the only header of
the bundle that cannot change how an existing application is embedded,
framed or referred to. X-Frame-Options and
Cross-Origin-Resource-Policy would break iframes, cross-origin embedding
and OAuth popups, so they stay opt-in.
To put the whole bundle on every response — including those same middleware-invisible paths — configure it on the server rather than the route tree:
import { SecurityHeadersOptions } from 'actor-ts/http';
const securityHeadersOptions = SecurityHeadersOptions.create() .withFrameOptions('SAMEORIGIN') .withReferrerPolicy('strict-origin-when-cross-origin');
await http.newServerAt('0.0.0.0', 8080) .withSecurityHeaders(securityHeadersOptions) .bind(routes);Passing options opts into the full bundle, its own defaults included — so
the two headers above arrive alongside Cross-Origin-Resource-Policy: same-origin and the rest. A plain object works as well
(withSecurityHeaders({ frameOptions: 'SAMEORIGIN' })), and
withSecurityHeaders(false) turns the mechanism off entirely.
Server-wide or as securityHeaders() middleware — both stamp the same set.
The middleware covers its own subtree, and that includes a short-circuit
that throws: an HttpError from a layer below it — a CSRF 403, an auth
401 — carries the headers out with it. What it never sees is a response
raised outside its subtree: the backend’s own 404, the body-too-large 413,
and the generic 500 that a non-HttpError throw maps to. Reach for the
middleware when only a route subtree needs it; reach for the builder when
the whole server does.
Operational environment
Section titled “Operational environment”-
TLS terminates at a proxy — or in the process, and the page never said which. Behind nginx, Caddy or an ingress the app speaks plain HTTP and that stays the production answer: the terminator holds the certificate, and the app sees
X-Forwarded-Proto, which it never trusts for anything security-relevant on its own. Two things in this layer assume the https world exists regardless:Csrfcompares origins againsthttpsby default, and the__Host-cookie prefix it uses requiresSecure, which is meaningless over plain HTTP. Both are correct behind a terminator and both fail loudly on a bare quickstart — which is whatwithTlsexists for: the process itself terminates, on Bun, Node and Deno, so aSecurecookie can be exercised without standing up a proxy. Set HSTS either way — browsers ignore it over plain HTTP. Don’t gate security headers on a scheme the app can’t see.The whole of a minimal terminator, for an app bound with
system.http(8080)— Caddy provisions the certificate itself and setsX-Forwarded-Protoon its own:Caddyfile example.com {reverse_proxy 127.0.0.1:8080}nginx.conf (server block) server {listen 443 ssl;server_name example.com;ssl_certificate /etc/ssl/example.com.pem;ssl_certificate_key /etc/ssl/example.com.key;location / {proxy_pass http://127.0.0.1:8080;proxy_set_header X-Forwarded-Proto $scheme;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;}}What the forwarded headers do here:
X-Forwarded-Foris read only byIpAllowlist, and only once you have named the proxies;X-Forwarded-Protois read by nothing —Csrfgets the scheme fromexpectedSchemeinstead, precisely because a forwarded scheme is set by whoever sends the request. -
Trusting client IPs.
req.remoteAddressis the socket peer, not a spoofableX-Forwarded-For— and “does my proxy overwrite the header” is the wrong question, because NGINX, AWS ALB and Cloudflare all append to it. The client’s own text stays at the left of the chain forever. Name the proxies instead (IpAllowlist’strustedProxies) and the client address is resolved from the socket end inwards, which is the only end infrastructure controls. Never trust every hop: on Express and Fastifytrust proxy: trueresolves to that leftmost, client-chosen entry. -
Secrets from the environment, not HOCON files — the CSRF secret, Basic credentials, and bearer tokens all take values you load at startup.
Cookies
Section titled “Cookies”Prefer the __Host- prefix (requires Secure, Path=/, no Domain) and
SameSite=Lax or Strict. The CSRF cookie uses
that prefix by default — it is what stops a sibling subdomain from planting
a token — and is deliberately not HttpOnly (double-submit needs JS to read
it); your session/auth cookie should be HttpOnly.
serializeCookie gets you there by omission. An attribute you don’t
mention resolves to the strict end — Secure, HttpOnly, SameSite=Lax,
Path=/ — so the two-argument call is already shippable, and what it
produces satisfies the __Host- rules without a word about them.
Loosening is the part you write down:
import { serializeCookie } from 'actor-ts/http';
// __Host-session=<id>; Path=/; HttpOnly; Secure; SameSite=Laxconst sessionCookie = serializeCookie('__Host-session', sessionId);
// Plain-HTTP local dev, and a cookie same-origin JS has to read.const readableCookie = serializeCookie('token', value, { secure: false, httpOnly: false });Path is always emitted, because the alternative is worse: without it a
browser derives the scope from the request URI, so the same cookie covers
/account when minted from /account/login and / when minted from the
root.
It also refuses anything that could break out of the cookie it is
building — an illegal name or value, and a Path or Domain that is not
one. Those two reach the header verbatim, so an unchecked Path of
'/;Domain=evil.example' would append an attribute of somebody else’s
choosing, and the last Domain is the one that counts: it would override
yours rather than lose to it.
Error hygiene
Section titled “Error hygiene”Don’t leak internals. Use withErrorHandler (or a top-level handleErrors)
to return a generic body, and log the detail server-side keyed by the
request id. Keep 403/404 responses unspecific — the static-file layer
returns a uniform 404 for every rejected path so it never reveals what
exists.
The server-side copy needs hygiene too, and the usual leak there is a
connection URL: a rejected option value and the WebSocket client’s
oversize-frame warning both name one, and both are written with the
userinfo masked. When you log a URL yourself, run it through
redactUrlCredentials or redactedUrlLabel,
or through redactParsedUrlCredentials when you hold the URL a request
was made with — a password that has reached a log aggregator has to be
rotated, not deleted.
Redirects
Section titled “Redirects”redirect(target) takes same-origin targets only — a relative
reference. An absolute URL, a protocol-relative //host, or a control
character throws HttpError(400), so forwarding a ?next= parameter
straight into a redirect fails closed instead of becoming an open redirect.
When leaving the origin is the intent, say so: redirectExternal(...) is
the same helper without the origin rule, and being a separate name makes
every deliberate off-origin hop greppable in one command. Hand it a
constant or a target you allowlisted — never a raw request parameter. See
the Route DSL.
Capping untrusted input
Section titled “Capping untrusted input”-
Request bodies are capped at 1 MiB on every backend, and a body over it is refused with the same
413 Payload Too Largewhichever backend serves it — before the handler runs, and without consultingwithErrorHandler, because a size cap is a transport decision rather than an application error. Move it withactor-ts.http.server.max-content-length(withMaxContentLengthin code), which holds on every backend and runtime — lower it where your endpoints take less, raise it where one genuinely takes more. The per-backend knobs remain —withMaxBodyBytes(bytes)on the Express and Hono backend options,bodyLimitin the options bag ofFastifyBackend— but beside a set key they must agree with it, orbind()refuses the backend rather than hold one cap and ignore the other. A body that declares an over-capContent-Lengthis refused before a byte of it is read; a chunked body declares no length, so all three backends count it as it arrives and abandon the read at the cap — the bytes past it are never received. -
Request headers are capped by the runtime at 16 KiB on
node:httpand on Bun, whose cap is the process-wide--max-http-header-size.actor-ts.http.server.max-header-bytes(withMaxHeaderBytesin code) moves it per server wherever actor-ts builds the server — Fastify, Express, and Hono on Node — and a request past it never reaches a handler. Two gaps remain. Hono on Bun or Deno has no per-server header cap to set, so there the key is reported not in effect andbind()warns;Deno.serve’s own limit let a 256 KiB header block through (deno 2.6.8). And on an HTTP/2 listener under Node the cap binds the HTTP/1.1 requests on the port but not an HTTP/2 stream’s header list — 900 bytes, 4 KiB and 60 KiB lists all passed a 1 KiB cap on node v26.10.0, bounded only by Node’s own 64 KiB limit, which neither the cap norsettings.maxHeaderListSizelowers — so there the key is reported held for HTTP/1.1 only andbind()warns. Bun caps the stream too, counting each field the HTTP/2 way (name, value and 32 bytes, pseudo-headers included), so a header block near the cap that HTTP/1.1 admits can be refused over HTTP/2: under 1 KiB a 900-byte header passed HTTP/1.1 and was reset over HTTP/2 (bun 1.4.2). A reverse proxy in front closes both gaps. -
A connection’s own time, which is the bound the rest of this list does not cover: a peer that never finishes sending has no request to time out, so no size cap and no route-level
requestTimeout()ever sees it. A server bounds the header phase at 60 s (actor-ts.http.server.header-timeout— the slowloris guard, answered408) and the whole receive at 300 s (request-timeout). Both bound receiving only, so a slow handler, a long poll and an SSE stream are untouched by them. Hono under Bun is the exception, and not because of these keys: thereidle-timeoutisBun.serve’s own whole-connection idle timeout, which counts a request whose handler has not written a byte as idle, so a handler or stream silent for that long is closed without a response. Unset, it is derived from the request deadline so that arequestTimeout()503 is written first — 36 s for the built-in 30 s, rather than Bun’s own 10 s, which cut such a request at about 12 s — and a value above255sfailsbind(); see the Hono backend.max-connectionscaps how many connections the process accepts at once, andidle-timeouthow long a quiet connection is held — a keep-alive socket between requests, and an HTTP/2 session with no stream open; both ship unset, so nothing is capped until you say so. These reach a connection through anode:httpserver, so Fastify, Express and Hono-on-Node carry them, Hono on Bun carriesidle-timeoutalone — so there it is the only bound on a request whose body stops arriving and on an idle connection, and0leaves such a connection open until the client closes it — and Hono on Deno neither — see the configuration reference for the table. Where one cannot,bind()says so: every bound you set that the backend reports not in effect is named in one warning when the server binds — a bound that holds for only one of the two protocols an HTTP/2 listener speaks with the protocol it does hold for — and the built-inheader-timeoutandrequest-timeoutare never among them. On HTTP/1.1,request-timeoutis enforced on a periodic sweep —http.createServer’sconnectionsCheckingInterval, 30 s by default and not set by actor-ts — so a connection is closed no later than one sweep past the value you set. A barenode:httpserver answers it408; the default Fastify backend under Bun closes it with no status line at all. An HTTP/2 stream carries a deadline of its own instead, held to the value — see below. The headers are part of the request, so arequest-timeoutshorter thanheader-timeoutis the header deadline as well: actor-ts writes the shorter one to the runtime and arms its own guard with it, which also keeps Node from quietly holding the request open until the longer one.On HTTP/2, both bounds are held by timers of actor-ts’s own.
keepAliveTimeoutandrequestTimeout, the properties that carry them to an HTTP/1.1 connection, are ones no HTTP/2 session or stream reads: measured on node v26.10.0 and bun 1.4.2, an HTTP/2 session that had finished its only request was still open past 5 s under an 800 msidle-timeout, and a stream whose body stopped after 10 of 1000 announced bytes was still open 12 s later under a 2 srequest-timeout— as was one trickled a byte every 500 ms.request-timeoutbounds each stream’s receive. A stream whose request is still arriving when the deadline passes is answered408and reset; measured at 2.0 s for2son both runtimes, stalled or trickled. The deadline ends as soon as the client has finished sending, read or not, so a request received in full is never cut, however long its handler takes — the HTTP/1.1 rule. The stream goes; the session stays for its other streams.idle-timeoutbounds a session with no stream open. The timer runs while nothing is open and the session is closed with a GOAWAY when it fires; a stream in flight holds it, as a request does an HTTP/1.1 keep-alive connection, so a slow handler, a long poll or an SSE stream is never interrupted by it and the bound starts when it ends. It is the same value on both runtimes — 0.81 s and 0.80 s for800ms— and a PING frame does not reset it: a client pinging every 300 ms has its idle session closed on time.
Left unset, an idle HTTP/2 session on the default backend is bounded by Fastify’s own session timer: 72 s on Node, but 144 s on Bun, which fires it at twice its value — and on Bun that timer counts a PING frame as activity, so a client pinging once a second held a session with no request on it open for as long as it kept pinging (still open at 170 s, bun 1.4.2). On Hono over Node an unset
idle-timeoutleaves an idle HTTP/2 session bounded by nothing at all. Setidle-timeouton any HTTP/2 listener.On Bun, an HTTP/1.1 connection on the HTTP/2 listener is bounded by neither. The listener keeps HTTP/1.1 available on the same port, and Bun hands such a connection to handling that reads neither
keepAliveTimeoutnorrequestTimeout: a keep-alive HTTP/1.1 connection was still open 8 s after its response under an 800 msidle-timeout, and a stalled HTTP/1.1 body 40 s in under a 2 srequest-timeout(bun 1.4.2) — where Node closes the first at 1.8 s and answers the second408at the next sweep. So on Bun the two are reported held for HTTP/2 only andbind()warns;header-timeoutandmax-connectionshold for both protocols there. Where untrusted clients can reach an HTTP/2 listener on Bun, terminate HTTP/1.1 in front of the process or keep the listener HTTP/1.1-only.header-timeoutis different, and deliberately so: actor-ts arms the deadline itself rather than handing the number to the runtime and hoping. The property is still written — where a runtime honours it the work happens earlier and more cheaply — but the bound does not depend on that. It cannot:server.headersTimeoutis accepted and ignored by two of the three supported runtimes. Measured on a barenode:httpserver against a socket that sends a header block and never the terminating blank line, node v26.7.0 answers408and closes, bun 1.4.0 enforces nothing at any value — including the0documented as disabling it; all of them closed at ~12 s with no408, which is Bun’s own idle timeout and not this guard — and deno 2.6.8 never closes the connection at all. So the deadline runs from the accepted connection and is cleared the moment a request or a WebSocket upgrade completes its headers, which is what makes the408above true on the runtime you are most likely to be on, and makes the number exact rather than rounded up to a sweep.On a listener that terminates TLS the handshake counts against the deadline too — a peer that never finishes negotiating is the same attack one layer down, and is hung up on without a status line — and once the handshake is done the
408goes out inside TLS. On HTTP/2 the first stream’s headers clear the deadline, and a session that never opens a stream is closed with a GOAWAY. Node hands the TCP and the TLS socket out as two objects, and an HTTP/2 session arrives as a third on both runtimes, so actor-ts carries the deadline across them by the connection’s address and port pair — which is what keeps a healthy HTTPS keep-alive connection or HTTP/2 session from being cut when its deadline would have passed. Bun’s HTTPS listener reports a connection only once its handshake is done; there a stalled handshake is bounded by Bun’s own ~12 s idle close instead.max-connectionsis the same decision, arrived at from the other direction: actor-ts counts the connections itself. The property is still set — where a runtime honours it the socket is refused before it reaches us, which is cheaper — but the bound does not depend on that. It cannot: the same runtime release was measured honouring the property on one operating system and ignoring it on another, which is a fine outcome for a tuning hint and not one for the control this page offers as the answer to a connection flood.Both rest on the server reporting its accepted connections, which is where they run out. Where a backend exposes no server object at all (Hono on Bun or Deno) there is nothing to hook, and Deno’s
node:httpshim emits noconnectionevent even where a server object exists — so on Deno neither the header deadline nor the connection cap is installed by any backend.A connection that says nothing is the gap that remains, and it is platform-shaped. Measured on bun 1.4.0 with the runtime installed on both: an
http.Serveremitsconnectionfor an accepted socket immediately on Windows and on Node, and on Linux only once that socket’s first byte arrives — until thengetConnections()answers0too, so the connection is invisible to the process rather than merely uncounted. On that pair neither enforcement can act on a silent client: the property is ignored there, and the event has not fired yet.That also settles why the header deadline held on the same runner while the cap did not (#1409): a slow-loris writes a partial header block, so its socket speaks and the event fires for it. A cap test that connects and says nothing is asking the Linux server about a connection it does not have.
So a connection that speaks is capped identically everywhere — every real client — and one that never speaks is bounded by nothing actor-ts can see on that pair. If idle sockets are part of your threat model, pair the cap with a limit that sits below the runtime: an OS-level connection limit, or a reverse proxy (#1505).
-
WebSocket frames are capped by
maxFrameBytes(1 MiB default). The framework always refuses an oversize frame before it reaches your actor; on most runtime/backend pairs the resolved cap is also handed to the runtime’s own socket, so the frame is refused while it arrives rather than after the process has buffered it — otherwise a peer could force 16 MiB (Bun) or 100 MiB (ws) of buffering per frame that the framework would then discard. Lowering the cap — per route or viaactor-ts.http.websocket.max-frame-bytes— narrows that buffering window with it. Three places have no transport cap and buffer the frame before rejecting it: Hono on Deno, whoseupgradeWebSocketexposes no payload limit at all; Bun with the Express or Fastify backend, wherewsresolves to Bun’s built-in shim, which acceptsmaxPayloadand reports it back but does not enforce it; and the outboundWebsocketClientActoron every runtime — no native clientWebSockethonours a payload limit passed to its constructor, measured on Bun, Node and Deno, where the option is accepted, reads backundefined, and a 4 MiB frame is still delivered whole. On the client the cap is therefore post-hoc only, and what it buys is that the breach is terminal: an oversize frame closes the connection with 1009, so the peer cannot repeat the allocation on that socket. Note the threat model differs there — the peer is an endpoint you chose to dial, or a MITM on a plaintextws://link. See WebSocket. -
Untrusted HTML — escape with the
htmltemplate; to accept rich markup, sanitise with a dedicated library beforerawHtml. -
Responses you fetch are untrusted input too, and the direction this list is easiest to forget.
HttpClientmaterialises a whole response body in memory before a caller sees it, so without a bound the peer decides how much of this process’s heap it takes — aContent-Lengthis a claim rather than a limit, and a chunked response declares no length at all. Every call carries a 30 s deadline and an 8 MiB response ceiling; the body is counted as it is read and abandoned while it arrives, with the connection torn down so the rest never lands, and the call throwsHttpResponseTooLargeError. Raise either per call (maxResponseBytes,timeoutMs), per integration (newClient(...)), or fleet-wide underactor-ts.http.client. Redirects are bounded with them — 5 hops, andauthorization/cookiedropped on any hop that crosses origins, so one hostileLocationcannot walk a bearer token to a host of its choosing. See the HTTP client.
Static files
Section titled “Static files”Keep the dotfiles: 'deny' and symlinks: 'within-root' defaults. Enable
browse only for internal tools — a public listing exposes your directory
structure. See Static files.
WebSocket
Section titled “WebSocket”A websocket() route rejects a cross-origin upgrade by default —
requireSameOrigin compares the browser’s Origin against the request’s own
Host and answers 403 before the handshake. Name other origins with
withAllowedOrigins([...]), or wrap the route in cors(...) for the same
effect from the middleware side. A client that sends no Origin at all — a
Node, Bun or Deno WebSocket, or any server-to-server dialer — is unaffected,
because Cross-Site WebSocket Hijacking needs a browser and a browser always
sends the header.
Know what that default does not cover. Origin and Host are both client
headers, so a page that reaches this server under a name of its own — DNS
rebinding — presents a matching pair and passes the same-origin arm; the
comparison is also scheme-blind, an http:// page on the same host:port
passing it. It buys reachability rather than a session, since no cookies for
the real host go with it, so what it exposes is a route whose auth is the
network — IpAllowlist, or trusting loopback. Pin withAllowedOrigins([...])
on such a route rather than relying on the default alone.
Put auth middleware around the route too — withMiddleware runs at upgrade
time, so it gates the handshake. What it attaches to the request, such as the
claims JwtAuth verified, stays on the HTTP side and
does not reach the connection. And bind the server to loopback unless it is
meant to be reached from elsewhere.
A websocket() route needs no special treatment in the hardening stack
above: securityHeaders(), requestId() and the rest may sit over it like
they sit over any other route, and the upgrade still completes. Their
headers land on a rejected handshake, not an accepted one — the backend
writes the 101 itself. See WebSocket.
Checklist
Section titled “Checklist”| Measure | How |
|---|---|
| MIME-sniffing disabled on every response | nothing — on by default |
| Security headers on every response | withSecurityHeaders(...) server-wide — securityHeaders() covers a subtree, rejections included |
| HTTPS enforced by the browser | strictTransportSecurity() / withHsts |
| Cross-origin controlled | cors(...) |
| WebSocket upgrade origin controlled | nothing — same-origin by default; withAllowedOrigins(...) to widen, withRequireSameOrigin(false) to opt out |
| CSRF (browser forms) | csrfProtection(...) |
| API authentication | JwtAuth(...) — signature, exp, iss and aud checked against your issuer’s keys; BearerTokenAuth(...) for a pre-shared operator token |
| No internal error leaks | withErrorHandler + generic bodies |
| No open redirects | redirect(...) — same-origin by default |
| Request correlation | requestId() |
| Bounded latency | requestTimeout(...) — its deadline also from actor-ts.http.request-timeout |
| Safe file serving | getFromDirectory defaults (dotfiles deny, symlink confinement) |
| Outbound responses bounded | nothing — 30 s and 8 MiB on every HttpClient call; per call, per newClient(...), or actor-ts.http.client |
| Outbound redirects bounded | nothing — 5 hops, credentials dropped cross-origin; redirect: 'error' to refuse them |
