Skip to main content
Cordon performs TLS man-in-the-middle (MITM) for configured route hosts so it can inspect HTTPS requests and decide whether they are eligible for credential injection. This is the same technique used by tools like mitmproxy and Charles Proxy. HTTPS traffic to unconfigured hosts 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 evaluates the inner request’s path and method filters. On a full route match, it strips and replaces auth headers before forwarding the request. Inner requests that miss path or method filters pass through without credential changes.

​
CA certificate setup

The cordon setup command generates CA certificates automatically:
cordon.toml stores absolute paths to the generated CA files. Use the real paths from your generated config; see Scopes for certificate storage locations.

​
Trusting the CA

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

​
System trust store

This adds the CA to the system trust store. To remove it later:
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:
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.