CA and trust
STATIC intercepts supported HTTPS requests. That requires a local certificate authority (CA): the browser trusts a public root certificate, while STATIC keeps the corresponding private signing key and issues a leaf certificate for each intercepted hostname. Trust is a deliberate host change. It allows this instance of STATIC to read and modify HTTPS traffic from applications that send traffic through it.
Two independent TLS connections
On the client side, STATIC presents a leaf certificate signed by its local CA. On the origin side, STATIC establishes a separate TLS session and verifies the website through its upstream TLS client. The local CA certificate is installed on the browser’s host; its private key stays with STATIC.
The CA does not replace the website’s real certificate in the origin-facing handshake. A trusted root alone also does not route traffic: the browser must use STATIC’s proxy listener. Conversely, a configured proxy without CA trust produces certificate errors. See TLS and certificates for the outbound profile plan and CLI installation for the complete per-platform setup.
Generation, reuse, and mismatch
When the proxy starts, TlsProvider loads the managed CA or generates one if neither certificate nor key exists. The public static-ca.crt lives under STATIC’s OS-specific local app-data directory. The key is read and written through the configured keystore backend. The managed certificate, key-storage path, and leaf cache cannot be arbitrarily moved with legacy tls.ca_cert_path, tls.ca_key_path, or tls.cache_dir config fields.
If the public certificate exists but its private key cannot be recovered, or the reverse, STATIC refuses to regenerate silently. A new root would invalidate previously installed trust. If both exist but the public certificate differs from the certificate reconstructed from the stored key, STATIC rewrites the public file to match the key. After it loads the CA, it issues per-host leaf certificates on demand and caches them in memory with a 24-hour cache lifetime. The CA key is not returned by the local API.
GET /ca/status returns the public PEM, its current path, and whether a certificate file exists. POST /ca/init initializes the same material if needed. Those endpoints belong to the API reference; this page covers the trust lifecycle.
What stores the private key
| Runtime and config | Keystore behavior in STATIC | Trust on the browser host |
|---|---|---|
| Windows CLI distro in WSL2 | Linux file mode inside the distro. The filename static-ca.key.dpapi is a legacy managed-path name; it is not Windows DPAPI encryption in WSL. | Windows certificate store and, where needed, Firefox’s Authorities store. |
| macOS operator bundle | keychain mode via the Rust keyring backend. The public .crt remains a managed local file. | macOS keychain trust and, where needed, Firefox. |
| Linux standalone CLI defaults | file mode. The key is file-backed, not a desktop keychain secret. | Distribution-specific system trust and, where needed, Firefox. |
Native Windows STATIC in keychain mode | CryptProtectData/CryptUnprotectData protect the managed key blob with Windows DPAPI. | Windows trust store. This is a code path distinct from the WSL CLI runtime. |
file mode writes key bytes to the managed path without DPAPI or keychain encryption in STATIC’s implementation. Restrict access to that directory and back it up only under a deliberate key-custody plan. Moving just the certificate to a new machine will not move the signing identity. See keystore source, CA source, and managed paths.
Windows CLI: WSL CA to Windows trust
The self-hosted WSL distribution generates the CA inside Linux. The Windows guide obtains its public certificate via \\wsl.localhost\404-cli\root\.local\share\static_proxy\certs\static-ca.crt for the documented root-user path, then imports that certificate into the Windows Current User → Trusted Root Certification Authorities store. If the path differs, query /ca/status on the control port with the bundle’s control token; use the returned certificate path rather than guessing.
Windows has its own trust decision even though STATIC runs in WSL2. Firefox can use a separate certificate database and may need an explicit Authorities import. Keep the *.key.dpapi file in WSL private; the .crt is the file to distribute for trust. The fixed token included in the public operator bundle is an example shared value, not a unique secret issued to each installation; change it for an installation exposed beyond the local host and keep the control listener restricted.
macOS CLI: Keychain key and trusted root
The published macOS bundle config selects STATIC’s keychain mode. STATIC stores the CA signing key through the platform keyring backend and writes the public certificate to managed local data. The macOS guide uses /ca/status to locate that exact .crt and security add-trusted-cert to trust it in the System keychain. That command needs administrator approval and changes trust for applications using that store. Firefox may need a separate import. The keychain item that holds a private key is distinct from the certificate trust entry.
Linux CLI: File key and distro trust
The no-config Linux CLI defaults to a file-backed key. Locate the public certificate with /ca/status on the CLI control port; the Linux guide shows Debian/Ubuntu installation under /usr/local/share/ca-certificates/ followed by update-ca-certificates. Other distributions use different mechanisms. Firefox may again require its own import. Do not copy the file-backed private key into a system CA directory.
Desktop application: documented host integration
The published desktop guide describes the app as orchestrating STATIC, asking for host privileges, installing the public root into LocalMachine\\Root on Windows and login/System keychains on macOS, configuring the host proxy, and offering cleanup. On Windows it describes a managed WSL distro named 404; that is distinct from the 404-cli name in our self-hosted guide. STATIC still owns CA generation and its private key. These app operations are documented behavior, not independently verified against sethzhonda/404-APP source in this revision, because that repository was unavailable to the connected GitHub account. In particular, do not infer that the native Windows DPAPI keystore path is used by the app’s WSL process: the packaged Linux path is configured for file mode.
Rotation, removal, and diagnosis
Stop routing through STATIC before removing trust. If you retire an installation, remove the corresponding public root from every host/browser store where you installed it, then remove the instance’s CA state through an intentional cleanup. Deleting only the .crt while retaining the key can cause STATIC to refuse startup; deleting only the key can do the same. A fresh CA requires new host trust. If you run more than one instance, compare the certificate returned by each instance’s /ca/status with the root you actually installed.
For certificate errors, check the proxy address, the active instance, the CA status, the host trust store, and Firefox’s separate trust behavior. A successful GET /status verifies process readiness, not that the browser trusts the correct CA or uses the proxy. The Windows, macOS, and Linux guides provide the operator steps.