Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.codezero.io/llms.txt

Use this file to discover all available pages before exploring further.

To inject credentials into HTTPS requests, cordon performs TLS man-in-the-middle (MITM) using a locally-generated CA certificate. This is the same technique used by tools like mitmproxy and Charles Proxy.

​
How it works

  1. Your app sends a CONNECT request to the proxy for the target host
  2. Cordon responds with 200 Connection Established
  3. Cordon generates a certificate for the target hostname, signed by the local CA
  4. Your app establishes a TLS connection with cordon (trusting the local CA)
  5. Cordon establishes a separate TLS connection with the upstream API (using the system trust store)
  6. Cordon can now read and modify the request before forwarding it

​
CA certificate setup

The cordon setup command generates CA certificates automatically: 
cordon setup
Certificates are stored under ~/.config/cordon/projects/<namespace>/certs/. cordon.toml stores absolute paths to those files. Use the real paths from your generated config (below uses the same /path/to/... placeholder style as elsewhere in these docs): 
[tls]
enabled = true
# Substitute paths from your real `cordon.toml` (typically under ~/.config/cordon/projects/<namespace>/certs/).
ca_cert_path = "/path/to/ca-cert.pem"
ca_key_path = "/path/to/ca-key.pem"

​
Trusting the CA

Your system and tools need to trust the CA certificate for HTTPS interception to work without certificate errors.

​
System trust store

cordon trust
This adds the CA to the system trust store. To remove it later: 
cordon untrust
Tools that use the system trust store work automatically after this:
  • curl, wget
  • Go, Rust, Python, Ruby, C#/.NET applications
  • gh (GitHub CLI)
  • Most CLI tools

​
Node.js

Node.js does not use the system trust store. You must set an environment variable: 
export NODE_EXTRA_CA_CERTS=$HOME/.config/cordon/projects/my-app-abc123/certs/ca-cert.pem

​
Java

Java uses its own trust store (cacerts): 
keytool -importcert -alias cordon \
  -file $HOME/.config/cordon/projects/my-app-abc123/certs/ca-cert.pem \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit -noprompt

​
Security considerations

  • The CA private key is stored on disk with 0600 permissions (owner-only read/write)
  • The CA certificate must be explicitly trusted — cordon never modifies trust stores without user action
  • Per-host certificates include SubjectAltName: DNS:<hostname> as required by modern TLS clients
  • The downstream connection (app to cordon) uses the local CA; the upstream connection (cordon to API) uses the system trust store — these are never mixed
The CA private key grants the ability to intercept any HTTPS traffic on the machine. Keep it secure and don’t share it. Treat it like an SSH private key.