How cordon intercepts HTTPS traffic using a local CA certificate.
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.
Your app sends a CONNECT request to the proxy for the target host
Cordon responds with 200 Connection Established
Cordon generates a certificate for the target hostname, signed by the local CA
Your app establishes a TLS connection with cordon (trusting the local CA)
Cordon establishes a separate TLS connection with the upstream API (using the system trust store)
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.
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"
This adds the CA to the system trust store. To remove it later:
cordon untrust
cordon trust installs the locally generated Cordon CA certificate, not combined-ca.pem or public CA roots. The October 2026 public-CA incident does not require rotating this local CA or rerunning cordon trust; update Cordon, the public trust sources, and client bundles as described in that checklist.System trust is enough for clients that read the OS trust store. Other runtimes need their own proxy or CA settings:
The generated combined-ca.pem is a snapshot of the installed system roots plus the existing Cordon CA. After updating the system CA source, regenerate the snapshot for the appropriate configuration:
cordon env --refresh-ca-bundle# Or select a user-scope or custom configuration:cordon env --scope user --refresh-ca-bundlecordon env --config /path/to/cordon.toml --refresh-ca-bundle
Refresh preserves the local CA certificate, private key, and config. It uses the same installed PEM source as setup and reports that source on stderr. Update that source first: changing OS trust settings alone may not update a separately installed Homebrew/OpenSSL bundle. See cordon env for discovery and failure behavior.Refresh replaces the entire combined bundle. Put custom roots in the selected system CA source first; manual additions made only to combined-ca.pem are discarded.Restart clients to load the refreshed bundle, and update any separate trust stores those clients use. Unconfigured hosts use opaque CONNECT tunnels, where the client validates the upstream certificate directly; those connections require updated client trust. Refreshing a bundle does not itself implement certificate revocation checking or change Cordon’s upstream TLS validation.
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.
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.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Cordon","colors":{"primary":"#D05C29","light":"#E8712F","dark":"#D05C29"},"logo":{"light":"https://mintcdn.com/codezero/oQtJQj8YChzXSXBb/logo/light.svg?fit=max\u0026auto=format\u0026n=oQtJQj8YChzXSXBb\u0026q=85\u0026s=07fdceef1809b3f17d997c4c5834c640","dark":"https://mintcdn.com/codezero/oQtJQj8YChzXSXBb/logo/dark.svg?fit=max\u0026auto=format\u0026n=oQtJQj8YChzXSXBb\u0026q=85\u0026s=4b8c7e011d2e42c74dcb85758e314b46"},"favicon":"https://mintcdn.com/codezero/8Qb50bdEbTbM91Gi/favicon.ico?fit=max\u0026auto=format\u0026n=8Qb50bdEbTbM91Gi\u0026q=85\u0026s=81f15120a7e36c866b0bc129c0bab724","integrations":{"ga4":{"measurementId":"G-2DXS90S7DY"},"posthog":{"apiKey":"phc_oX8BjqYf4ogcL2rNH5WLb8vLQgWCJScbhtwBTxyqabpR","sessionRecording":true}},"styling":{"latex":false},"navigation":{"global":{"anchors":[{"anchor":"Changelog","href":"https://codezero.io/changelog"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"codezero","hasAudioNarration":false,"actualSubdomain":"codezero","customDomains":["docs.codezero.io"],"gitSource":{"type":"github","owner":"codezero-io","repo":"cordon","deployBranch":"docs","contentDirectory":"developer-docs","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6adeb1fbb7bed53c17af79c6","collectionId":"fc89aba8-587d-4b12-b673-fd2c06eb6f19","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6adeb1fbb7bed53c17af79c6"},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6adeb1fbb7bed53c17af79c6","clientVersion":"0.0.4006","searchFilterCounts":[{"language":"default","tag":"CLI Reference","count":16},{"language":"default","tag":"Guides","count":11},{"language":"default","tag":"Configuration","count":5},{"language":"default","tag":"Getting Started","count":4},{"language":"default","tag":"Security","count":4}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-v7-file-tree","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"pause-universal-search-reconcile","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"per-site-search-delta","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-private-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-nav-generations","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-agent-model-picker","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"configuration/tls","slug":"/configuration/tls","pageMetadata":{"title":"TLS","description":"How cordon intercepts HTTPS traffic using a local CA certificate.","href":"/configuration/tls"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"How cordon intercepts HTTPS traffic using a local CA certificate.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`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.`}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsx(Heading,{level:`2`,id:`how-it-works`,children:`How it works`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[`Your app sends a `,_jsx(_components.code,{children:`CONNECT`}),` request to the proxy for the target host`]}),`\n`,_jsxs(_components.li,{children:[`Cordon responds with `,_jsx(_components.code,{children:`200 Connection Established`})]}),`\n`,_jsx(_components.li,{children:`Cordon generates a certificate for the target hostname, signed by the local CA`}),`\n`,_jsx(_components.li,{children:`Your app establishes a TLS connection with cordon (trusting the local CA)`}),`\n`,_jsx(_components.li,{children:`Cordon establishes a separate TLS connection with the upstream API (using the system trust store)`}),`\n`,_jsx(_components.li,{children:`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.`}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`ca-certificate-setup`,children:`CA certificate setup`}),`\n`,_jsxs(_components.p,{children:[`The `,_jsx(_components.code,{children:`cordon setup`}),` command generates CA certificates automatically:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`cordon`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` setup`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`cordon.toml`}),` stores absolute paths to the generated CA files. Use the real paths from your generated config; see `,_jsx(_components.a,{href:`/configuration/overview#scopes`,children:`Scopes`}),` for certificate storage locations.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`toml`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`toml`,children:_jsxs(_components.code,{language:`toml`,numberOfLines:`5`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`[`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#D4D4D4`},children:`tls`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`enabled`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`true`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:\"# Substitute paths from your real `cordon.toml`.\"})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ca_cert_path`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"/path/to/ca-cert.pem\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ca_key_path`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"/path/to/ca-key.pem\"`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`trusting-the-ca`,children:`Trusting the CA`}),`\n`,_jsx(_components.p,{children:`Your system and tools need to trust the CA certificate for HTTPS interception to work without certificate errors.`}),`\n`,_jsx(Heading,{level:`3`,id:`system-trust-store`,children:`System trust store`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`cordon`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` trust`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`This adds the CA to the system trust store. To remove it later:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`cordon`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` untrust`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`cordon trust`}),` installs the locally generated Cordon CA certificate, not `,_jsx(_components.code,{children:`combined-ca.pem`}),` or public CA roots. The `,_jsx(_components.a,{href:`/security/october-2026-upgrade`,children:`October 2026 public-CA incident`}),` does not require rotating this local CA or rerunning `,_jsx(_components.code,{children:`cordon trust`}),`; update Cordon, the public trust sources, and client bundles as described in that checklist.`]}),`\n`,_jsx(_components.p,{children:`System trust is enough for clients that read the OS trust store. Other runtimes need their own proxy or CA settings:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Use `,_jsx(_components.a,{href:`/cli/env`,children:_jsx(_components.code,{children:`cordon env`})}),` or the `,_jsx(_components.a,{href:`/guides/generic`,children:`generic tool guide`}),` for the standard proxy and CA bundle variables.`]}),`\n`,_jsxs(_components.li,{children:[`Use the `,_jsx(_components.a,{href:`/guides/sdk-compatibility#runtime-ca-and-proxy-notes`,children:`SDK compatibility guide`}),` for runtime-specific details such as Node.js, Java, Ruby, PHP, curl, and wget.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`3`,id:`updating-client-ca-bundles`,children:`Updating client CA bundles`}),`\n`,_jsxs(_components.p,{children:[`The generated `,_jsx(_components.code,{children:`combined-ca.pem`}),` is a snapshot of the installed system roots plus the existing Cordon CA. After updating the system CA source, regenerate the snapshot for the appropriate configuration:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`4`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`cordon`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` env`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --refresh-ca-bundle`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Or select a user-scope or custom configuration:`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`cordon`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` env`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --scope`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` user`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --refresh-ca-bundle`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`cordon`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` env`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --config`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` /path/to/cordon.toml`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --refresh-ca-bundle`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Refresh preserves the local CA certificate, private key, and config. It uses the same installed PEM source as setup and reports that source on stderr. Update that source first: changing OS trust settings alone may not update a separately installed Homebrew/OpenSSL bundle. See `,_jsx(_components.a,{href:`/cli/env#refreshing-the-ca-bundle`,children:_jsx(_components.code,{children:`cordon env`})}),` for discovery and failure behavior.`]}),`\n`,_jsxs(_components.p,{children:[`Refresh replaces the entire combined bundle. Put custom roots in the selected system CA source first; manual additions made only to `,_jsx(_components.code,{children:`combined-ca.pem`}),` are discarded.`]}),`\n`,_jsx(_components.p,{children:`Restart clients to load the refreshed bundle, and update any separate trust stores those clients use. Unconfigured hosts use opaque CONNECT tunnels, where the client validates the upstream certificate directly; those connections require updated client trust. Refreshing a bundle does not itself implement certificate revocation checking or change Cordon’s upstream TLS validation.`}),`\n`,_jsx(Heading,{level:`2`,id:`troubleshooting-certificate-errors`,children:`Troubleshooting certificate errors`}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsx(_components.p,{children:`Use the same source of truth for all manual setups:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`cordon`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` env`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`Common checks:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`NODE_EXTRA_CA_CERTS`}),` points to `,_jsx(_components.code,{children:`ca-cert.pem`}),` for Node.js.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`SSL_CERT_FILE`}),`, `,_jsx(_components.code,{children:`REQUESTS_CA_BUNDLE`}),`, and `,_jsx(_components.code,{children:`CURL_CA_BUNDLE`}),` point to `,_jsx(_components.code,{children:`combined-ca.pem`}),`, not `,_jsx(_components.code,{children:`ca-cert.pem`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`cordon trust`}),` has been run for tools that use the system trust store.`]}),`\n`,_jsxs(_components.li,{children:[`Runtime-specific proxy handling is covered in `,_jsx(_components.a,{href:`/guides/sdk-compatibility`,children:`SDK Compatibility`}),`.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`security-considerations`,children:`Security considerations`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`The CA private key is stored on disk with `,_jsx(_components.code,{children:`0600`}),` permissions (owner-only read/write)`]}),`\n`,_jsx(_components.li,{children:`The CA certificate must be explicitly trusted — cordon never modifies trust stores without user action`}),`\n`,_jsxs(_components.li,{children:[`Per-host certificates include `,_jsx(_components.code,{children:`SubjectAltName: DNS:\u003chostname>`}),` as required by modern TLS clients`]}),`\n`,_jsx(_components.li,{children:`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`}),`\n`]}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`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.`})})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"TLS","description":"How cordon intercepts HTTPS traffic using a local CA certificate.","href":"/configuration/tls"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"How it works","slug":"how-it-works","depth":2,"children":[]},{"title":"CA certificate setup","slug":"ca-certificate-setup","depth":2,"children":[]},{"title":"Trusting the CA","slug":"trusting-the-ca","depth":2,"children":[{"title":"System trust store","slug":"system-trust-store","depth":3,"children":[]},{"title":"Updating client CA bundles","slug":"updating-client-ca-bundles","depth":3,"children":[]}]},{"title":"Troubleshooting certificate errors","slug":"troubleshooting-certificate-errors","depth":2,"children":[]},{"title":"Security considerations","slug":"security-considerations","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"codezero","siteName":"Cordon","title":"TLS - Cordon","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-26T01:26:15.166Z","originalFileLocation":"configuration/tls.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"How cordon intercepts HTTPS traffic using a local CA certificate.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Cordon\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/codezero/1Hvzh0b0AfKeF4Xm/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/codezero/1Hvzh0b0AfKeF4Xm/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/codezero/1Hvzh0b0AfKeF4Xm/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/codezero/1Hvzh0b0AfKeF4Xm/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/codezero/1Hvzh0b0AfKeF4Xm/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/codezero/1Hvzh0b0AfKeF4Xm/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/codezero/1Hvzh0b0AfKeF4Xm/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/codezero/1Hvzh0b0AfKeF4Xm/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/codezero/1Hvzh0b0AfKeF4Xm/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"TLS - Cordon\">\u003cmeta data-mint-head property=\"og:description\" content=\"How cordon intercepts HTTPS traffic using a local CA certificate.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Cordon\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.codezero.io/configuration/tls\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://codezero.mintlify.app/_mintlify/api/og/v2?division=Configuration\u0026amp;title=TLS\u0026amp;description=How+cordon+intercepts+HTTPS+traffic+using+a+local+CA+certificate.\u0026amp;theme=84a94c06642e416e1f593acf\u0026amp;signature=1a4ee5f57100e4f7a104e4d3bbd042c86be2751a502c179b9459b536564cea98\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"TLS - Cordon\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"How cordon intercepts HTTPS traffic using a local CA certificate.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://codezero.mintlify.app/_mintlify/api/og/v2?division=Configuration\u0026amp;title=TLS\u0026amp;description=How+cordon+intercepts+HTTPS+traffic+using+a+local+CA+certificate.\u0026amp;theme=84a94c06642e416e1f593acf\u0026amp;signature=1a4ee5f57100e4f7a104e4d3bbd042c86be2751a502c179b9459b536564cea98\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/codezero/1Hvzh0b0AfKeF4Xm/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Cordon\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#D05C29\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.codezero.io/configuration/tls\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/configuration/tls.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.codezero.io/#organization\",\"name\":\"Cordon\",\"url\":\"https://docs.codezero.io\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/codezero/oQtJQj8YChzXSXBb/logo/light.svg?fit=max\u0026auto=format\u0026n=oQtJQj8YChzXSXBb\u0026q=85\u0026s=07fdceef1809b3f17d997c4c5834c640\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.codezero.io#website\",\"name\":\"Cordon\",\"url\":\"https://docs.codezero.io\",\"publisher\":{\"@id\":\"https://docs.codezero.io/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.codezero.io/configuration/tls#webpage\",\"url\":\"https://docs.codezero.io/configuration/tls\",\"name\":\"TLS\",\"description\":\"How cordon intercepts HTTPS traffic using a local CA certificate.\",\"dateModified\":\"2026-10-26T01:26:15.166Z\",\"isPartOf\":{\"@id\":\"https://docs.codezero.io#website\"},\"breadcrumb\":{\"@id\":\"https://docs.codezero.io/configuration/tls#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.codezero.io/configuration/tls#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Configuration\",\"item\":\"https://docs.codezero.io/configuration/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"TLS\",\"item\":\"https://docs.codezero.io/configuration/tls\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.codezero.io/configuration/tls#article\",\"headline\":\"TLS\",\"name\":\"TLS\",\"description\":\"How cordon intercepts HTTPS traffic using a local CA certificate.\",\"url\":\"https://docs.codezero.io/configuration/tls\",\"mainEntityOfPage\":{\"@id\":\"https://docs.codezero.io/configuration/tls#webpage\"},\"dateModified\":\"2026-10-26T01:26:15.166Z\",\"publisher\":{\"@id\":\"https://docs.codezero.io/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.codezero.io#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Cordon\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Cordon","nav":{"global":{"anchors":[{"anchor":"Changelog","href":"https://codezero.io/changelog"}]},"groups":[{"group":"Getting Started","pages":[{"title":"Introduction","href":"/introduction"},{"title":"Installation","href":"/installation"},{"title":"Quickstart","href":"/quickstart"},{"title":"Support","href":"/support"},{"title":"Developer License Agreement","hidden":true,"href":"/license"}]},{"group":"Configuration","pages":[{"title":"Configuration Overview","href":"/configuration/overview"},{"title":"Routes","href":"/configuration/routes"},{"title":"Listeners","href":"/configuration/listeners"},{"title":"Secret Sources","description":"Configure where cordon fetches credentials — 1Password or the OS keyring.","href":"/configuration/secret-sources"},{"title":"TLS","href":"/configuration/tls"}]},{"group":"Guides","pages":[{"title":"1Password","description":"Use 1Password as Cordon's credential backend — setup, configuration, security model, and operational guidance.","href":"/guides/onepassword"},{"title":"Claude Code","href":"/guides/claude-code"},{"title":"Codex","href":"/guides/codex"},{"title":"Hermes Agent","href":"/guides/hermes"},{"title":"OpenClaw","href":"/guides/openclaw"},{"title":"Any tool (generic)","href":"/guides/generic"},{"title":"Proxy Tokens","href":"/guides/token-migration"},{"title":"MCP Servers","href":"/guides/mcp-servers"},{"title":"Database Connections","href":"/guides/databases"},{"title":"Process Management","href":"/guides/process-management"},{"title":"SDK Compatibility","href":"/guides/sdk-compatibility"}]},{"group":"CLI Reference","pages":[{"title":"cordon start","href":"/cli/start"},{"title":"cordon setup","href":"/cli/setup"},{"title":"cordon integration","href":"/cli/integration"},{"title":"cordon env","href":"/cli/env"},{"title":"cordon token","href":"/cli/token"},{"title":"cordon route","href":"/cli/route"},{"title":"cordon listener","href":"/cli/listener"},{"title":"cordon doctor","href":"/cli/doctor"},{"title":"cordon trust / untrust","href":"/cli/trust"},{"title":"cordon wait","href":"/cli/wait"},{"title":"cordon status","href":"/cli/status"},{"title":"cordon stop","href":"/cli/stop"},{"title":"cordon service","href":"/cli/service"},{"title":"cordon secret","href":"/cli/secret"},{"title":"cordon upgrade","href":"/cli/upgrade"},{"title":"cordon help","href":"/cli/help"}]},{"group":"Security","pages":[{"title":"October 2026 security upgrade","href":"/security/october-2026-upgrade"},{"title":"Security Model","href":"/security/overview"},{"title":"Threat Model","href":"/security/threat-model"},{"title":"OWASP Risk Coverage","href":"/security/owasp"}]}]},"title":"TLS - Cordon","buildId":"dpl_2xiSHD9XEvLsPGPcfoMtkLTB3dy9","deploymentId":"dpl_2xiSHD9XEvLsPGPcfoMtkLTB3dy9","dynamics":[],"chunks":[]}
