Security & access control

Client identity

Every decision that depends on "the client's IP" starts from one resolved value, produced at connection admission and stored in ReqCtx.client_ip:

flowchart TB
  classDef id fill:#13203a,stroke:#818cf8,color:#fff
  classDef chk fill:#1a1f33,stroke:#fbbf73,color:#e8ecf6
  A["socket peer"] --> B("PROXY protocol listener?")
  B -- yes --> C["peer := header source<br/>(loopback / unspecified claims refused)"]
  B -- no --> D["peer := TCP address<br/>(UDS: fabricated loopback)"]
  C & D --> E("peer in an allow rule marked T?<br/>(useIpInProxyHeader 0–4)")
  E -- "trusted proxy" --> F["client := CF-Connecting-IP / X-Forwarded-For<br/>(rightmost untrusted hop)"]:::id
  E -- "not trusted" --> G["client := peer<br/>(forwarded headers ignored)"]:::id
  F & G --> H["accessControl allow/deny<br/>most-specific wins"]:::chk
  H --> I["geoAllow/Deny · asnAllow/Deny<br/>deny-first, allow-only = whitelist"]:::chk
  I --> J["perIpRate throttle → 429<br/>(fail-open under state pressure)"]:::chk
  J --> K["mTLS trust boundary<br/>plaintext on an mTLS vhost is refused unless loopback"]:::chk
  K --> L["ReqCtx.client_ip → REMOTE_ADDR · logs · cache key"]

The admin write API classifies useIpInProxyHeader and the whole <security> block as restart-required: trust must not change under a running generation without a listener transaction.

Network ACLs

<security><accessControl> evaluates allow/deny CIDR lists most-specific-wins; a trailing T on an allow rule marks a trusted proxy. <accessDenyDir> globs are never served, and a malformed glob is a hard start/reload error rather than a warn-and-skip. <fileAccessControl><followSymbolLink> mode 2 (owner-restricted) fails closed to never-follow. Static opens use openat2(RESOLVE_BENEATH) — plus RESOLVE_NO_SYMLINKS when policy denies symlinks — and refuse non-regular files so a planted FIFO cannot park an executor thread; a kernel without openat2 fails closed to 404.

Per-client-IP throttle

<tuning><perIpRate> (or --per-ip-rate) caps requests per client IP per fixed window (perIpRateWindowSecs, default 1 s); excess requests get 429. The implementation is a sharded fixed-window counter — 64 shards, 4096 tracked IPs per shard — counted exactly once per request at the fast-path serve points and at dispatch.

GeoIP / ASN rules

Country and network membership come from hj-geo, which has no runtime network access: point <security><geoipDBFile> at a CidrList text file and refresh it on your own schedule. Ranges load into sorted, merged interval sets queried by binary search; IPv4-mapped IPv6 addresses are judged in v4 space.

# country <ISO-3166 alpha-2> <CIDR…>
country US 203.0.113.0/24 198.51.100.0/24
country DE 2001:db8::/32
# asn <number> <CIDR…>
asn 13335 203.0.113.0/24

geoAllow/geoDeny (ISO-2 labels) and asnAllow/asnDeny resolve to CIDR sets at state build: deny first; an allow list with no deny list is a fail-closed whitelist; an unknown label or a missing database is a hard build error, not a silent no-op; check warns on geo lists without a database. Both funnels (on-core and bridged) judge the resolved client IP, so CDN-fronted visitors are evaluated by their real address.

PROXY protocol trust

A listener with proxyProtocol=1 requires a PROXY v2/v1 header on every connection, consumed before TLS or the h1/h2c sniff. The listener opt-in is the trust decision — never enable it on a public bind (check warns). Headers claiming a loopback or unspecified source are refused at the parser (2026-09-16), because those addresses would otherwise unlock the mTLS exemption and the loopback purge/ready endpoints. Details: Protocol stacks.

TLS & mTLS

• mTLS — clientVerify 1–3 attaches a webpki verifier to the listener CA; level 2 requires a client certificate (e.g. Cloudflare Authenticated Origin Pulls). A plaintext request for an mTLS vhost is refused unless from loopback. --no-mtls is for local testing only — always confirm the live flags with systemctl show -p ExecStart before reasoning about the boundary.
• Revocation — crlFile adds PEM CRL enforcement; absent means none, stated plainly.
• Cipher and resumption discipline — one TLS 1.3 suite, single-use tickets, 0-RTT off; resumption disabled when OCSP is on. TLS stream splitting was made memory-safe in the 2026-09-06 round.
• One config, two transports — a certificate, verifier or CRL change cannot land on TCP and miss QUIC. See TLS, ACME & OCSP.

Request limits & resource fences

WAF inspection seam

httpjet embeds no rules engine. --waf-sidecar-addr enables a bounded loopback HTTP inspection call that runs after URI normalization and body limits but before rewrite, cache lookup, WebSocket/proxy dispatch, LSAPI, FastCGI and static serving — so a warm cache hit is still inspected. The default failure policy is closed (503); --waf-fail-open must be chosen explicitly and logs every bypass. The full contract is on Extending httpjet.

The PHP jail

suEXEC (<suexec>, off by default, uidMin/gidMin floors; uid 0 always rejected), chroot (chrootMode 0–2) and optional namespaces (pid accepted but not honored). A configured jail that turns out unsafe disables PHP for that vhost with a 503 — never unjailed, never falling through to static. Workers never run as root and a setuid lsphp is refused. See LSAPI & PHP.

Control surfaces

Audit posture

Five whole-codebase review rounds have landed on top of the August hardening pass: 2026-08-30 (issues #362–#368: no exploitable High, five low/informational fixes), 2026-09-06 (five confirmed medium/low findings: H2/H3 body-reservation leaks, retained-body and gzip-expansion accounting, scoped Basic-auth merging, public caching of authenticated static responses, UA-classification memo dependencies), and 2026-09-16 (twelve fixes: h2 monoio deadlines, sendfile stall bounds, unreadable .htaccess fail-closed, PROXY loopback claims, [P] target screening, CGI-var deny-list, never-root and setuid refusal, isolation-mode hard errors, restart-required trust fields, seccomp ptrace gating, Origin-varied cache entries, CPU_SETSIZE clamp and single Content-Length), 2026-10-06 (issues #560–#575, released as 0.0.4: the H3 connection budget is charged at Connected with stateless Retry under handshake pressure, RFC 9112 request-target/Host enforcement at the H1 intake, one rule for which client headers reach PHP (no Proxy, no underscore names, forwarding-authority names only from a trusted peer), AuthUserFile confined to the docroot with constant-cost verification and a bcrypt cost cap, POST-only purge + validated integrity keys + bounded control surfaces, quinn GHSA-53rm-773f-4q8c, new qpack_decode/proxy_protocol_parse/lscache_control fuzz targets, and a daily RustSec dependency-advisory CI job), and a 0.0.5 remediation sweep (15 findings #579–#593: proxy h2 connect budget and failover across reloads, rewrite [S=usize::MAX] saturation, h2 RST_STREAM stream teardown, WAF body restored before the timed sidecar exchange, LSAPI forwarding-header classification and cancellable restart backoff, chroot-without-credentials as a hard error, QPACK :path/Required-Insert-Count rejection, and a tag-purge sweep that can never unlink a live entry's body). Each round's regressions are in the tree; gates re-run after each: full workspace suite, fast-memo parity, cache xurl/scheme/xhost, h2spec 146/146.