Architecture and specification
This page is a readable overview of how MiraServe is built. It covers the crates in the source tree, the path a request takes through them, and the libraries they rely on. The full specification and threat model are in the repository, linked at the end.
Design rules
A few rules apply to the whole code base and explain many of the choices below:
- Every crate uses
#![forbid(unsafe_code)]. MiraServe does not call operating system functions through raw FFI. For example, it does not switch users itself. You start it as an unprivileged user, and it refuses to start as root when a sandbox user is configured. - Library and runtime code may not use
unwrap,expectorpanic. Malformed input from the network or a config file becomes a typed error. - OpenSSL is not linked. All TLS and signing goes through
rustlsandaws-lc-rs. - Settings fail closed. Unknown or mistyped config settings are errors, and features that are not finished, such as ECH, are rejected rather than silently ignored.
The workspace crates
The source tree is a Rust workspace with 15 crates. A crate is a Rust library or program, compiled as a unit.
| Crate | What it does |
|---|---|
miraserve-bin | The miraserve program: run, check, reload, cert, version, import, publish, keyd and service. See CLI commands. |
miraserve-config | Parses the KDL config (both KDL v2 #true and v1 true syntax), validates it against the schema and the security rules, and holds the live config so a reload can swap it in one step. |
miraserve-core | Opens the listeners: TCP for HTTP/1.1 and HTTP/2, UDP for HTTP/3 over QUIC, and plain HTTP redirect listeners. It also chooses the TLS settings per host name (SNI), caps connections, runs hot reload on SIGHUP, and lets connections drain on shutdown. |
miraserve-tls | TLS 1.3 with the X25519MLKEM768 post-quantum hybrid key exchange, certificate selection per host name, development certificates, ACME v2 with renewal information (RFC 9773), and the client side of the split-key signer. |
miraserve-http | The HTTP/1.1, HTTP/2 and HTTP/3 server engine, the router that maps a request to a site and route, the HTTPS redirector, security headers, and the built-in error pages. |
miraserve-security | Request checks that block HTTP request smuggling, HTTP/2 and HTTP/3 flood guards, slow-body (Slowloris) protection, the GCRA rate limiter, and the presets wordpress-hardened, static-strict and api-gateway. |
miraserve-static | Serves files from a document root opened through cap-std, so paths cannot leave the root. Dotfiles are refused. It also handles ETags, ranges, precompressed files, Brotli and gzip, and try-files. |
miraserve-proxy | Reverse proxy with weighted load balancing, active health checks, unbuffered streaming for server-sent events, WebSocket upgrades, and TLS or mutual TLS to upstreams. |
miraserve-fastcgi | An async FastCGI client written in Rust that talks to PHP-FPM. PHP runs in its own process, never inside MiraServe. |
miraserve-sandbox | Works out a confinement policy from the config. On Linux it applies Landlock filesystem rules and a seccomp-bpf system call filter to all worker threads. On macOS and Windows it reports what is and is not enforced. |
miraserve-wasm | Runs WebAssembly plugins under wasmtime with wasi:http. Each plugin has fixed limits on CPU (fuel), memory and time, and gets no files, environment or network access. |
miraserve-ai | Verifies signed requests from AI agents (RFC 9421, Web Bot Auth) and runs the MCP gateway, which checks OAuth JWTs, enforces per-tool allow and deny lists and writes redacted audit logs. It also serves Markdown to clients that ask for text/markdown, and llms.txt. |
miraserve-publish | Signed, versioned site releases: Ed25519 signatures, pre-flight checks (secrets, inline scripts, CSP, size), an unchangeable release store, atomic switch-over, rollback, and an authenticated publishing endpoint for agents. |
miraserve-migrate | The importers behind miraserve import for Nginx, Apache, Caddy and OpenLiteSpeed configs. See Migrating. |
miraserve-telemetry | Prometheus metrics, OTLP/HTTP export, and access and audit logs with secrets removed. |
How a request flows
This is the path of an HTTPS request, in the order the code handles it.
- Connection.
miraserve-coreaccepts a TCP connection, or a QUIC connection on UDP for HTTP/3, and applies the per-IP connection cap. It reads the host name from the TLS handshake (SNI) and asksmiraserve-tlsfor that host's certificate and TLS policy. If keys live inmiraserve keyd, the handshake signature is requested from the daemon over a local socket. - HTTP.
hyper(HTTP/1.1 and HTTP/2) orquinnwithh3(HTTP/3) decodes the request. Timeouts and flood guards frommiraserve-securityapply to the whole connection. - Request checks. The
miraserve-httprouter first rejects ambiguous framing that could be used for request smuggling, such as conflictingContent-LengthandTransfer-Encodingheaders. It then decodes the path once into a canonical form, so later checks and the file system see the same path. - Site checks. The router answers ACME HTTP-01 challenges, checks that the
Hostheader matches the TLS host name and the site's TLS policy, and then runs the site's preset, the Web Bot Auth policy and the site rate limit, in that order. - Built-in endpoints. If configured, OAuth protected-resource metadata for the MCP gateway and the publishing endpoint are handled next. They run after the preset and rate limit.
- Route. The first route that matches is chosen, and its own rate limit is checked. The route then hands the request to its handler: static files or
try-files(miraserve-static), PHP over FastCGI (miraserve-fastcgi), a reverse proxy (miraserve-proxy), the MCP gateway (miraserve-ai) or a WebAssembly plugin (miraserve-wasm). A site with a publishing store and no matching route serves the active release. - Response. Security headers for the site's policy are added, MiraServe's own error responses are replaced by the built-in or custom error pages, and
miraserve-telemetryrecords the request with secrets removed from the log.
Configuration sits beside this path. miraserve-config validates a new file completely before it is used, and on reload the router and TLS settings are swapped in one step. Requests in flight finish on the old config.
Main building blocks
MiraServe is assembled from established Rust libraries rather than writing protocol code from scratch:
| Library | Used for |
|---|---|
rustls | TLS 1.3 (and opt-in TLS 1.2) |
aws-lc-rs | Cryptography, including ML-KEM and Ed25519 |
hyper | HTTP/1.1 and HTTP/2 |
quinn and h3 | QUIC and HTTP/3 |
cap-std | File access confined to a directory |
wasmtime | WebAssembly plugin sandbox |
tokio | Async runtime |
kdl | Config file parsing |
landlock and seccompiler | Linux confinement |
Dependencies are checked with cargo-deny, which also bans openssl and openssl-sys. The parsers that read untrusted input have cargo-fuzz targets.
Trust boundaries
The threat model splits the system into a worker process that faces the internet and the things it talks to. Each link is a boundary with its own control: the network edge (TLS 1.3, QUIC limits), the key daemon (sign-only socket), WebAssembly plugins (fuel, memory and capability limits), the file system (cap-std), the publishing gate (signatures and pre-flight checks), and backends (mutual TLS or PHP-FPM over FastCGI). The Threat model page explains each one, and what MiraServe does not try to protect against.
Full documents
These documents are kept with the source code and will be published with it. They are more detailed than this site. Note that some of them describe features that are not active yet, such as ECH.
SPEC.md: product pillars, crate layout and milestones.THREAT_MODEL.md: assets, trust boundaries, threats and required mitigations.DEPLOYMENT.md: systemd, packages, containers, macOS and Windows.MIGRATION.md:miraserve importper source server.SECURITY_AUDIT_PREP.md: security audit preparation and verification record.BENCHMARKS.md: how baseline measurements are taken.