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) for hosts with matching routes. This is the same technique used by tools like mitmproxy and Charles Proxy. Unmatched HTTPS traffic is not decrypted. It passes through as a transparent CONNECT tunnel, so the upstream server’s real certificate is presented to the client.

​
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 strip and replace auth headers before forwarding the request

​
CA certificate setup

The cordon setup command generates CA certificates automatically: 
cordon setup
cordon.toml stores absolute paths to the generated CA files. Use the real paths from your generated config; see Scopes for certificate storage locations. 
[tls]
enabled = true
# Substitute paths from your real `cordon.toml`.
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
System trust is enough for clients that read the OS trust store. Other runtimes need their own proxy or CA settings:

​
Troubleshooting certificate errors

Certificate failures usually mean the calling process either is not using Cordon’s CA configuration or is using the raw CA cert where it needs the combined bundle. Use the same source of truth for all manual setups: 
cordon env
Common checks:
  • NODE_EXTRA_CA_CERTS points to ca-cert.pem for Node.js.
  • SSL_CERT_FILE, REQUESTS_CA_BUNDLE, and CURL_CA_BUNDLE point to combined-ca.pem, not ca-cert.pem.
  • cordon trust has been run for tools that use the system trust store.
  • Runtime-specific proxy handling is covered in SDK Compatibility.

​
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.