From 7afdd0033de11516a0807f53ed35e121516c99e1 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Thu, 22 Oct 2026 17:31:34 +0200 Subject: [PATCH 1/3] fix: trust certificate authorities from the OS certificate store Compile the binary with --compile-exec-argv=--use-system-ca so Bun trusts the Windows certificate store, the macOS Keychain and the Linux system CA bundle. Corporate CAs used for TLS inspection then work once they are installed in the OS store, without NODE_EXTRA_CA_CERTS. The TLS hint and the login troubleshooting docs point at the OS store first and keep NODE_EXTRA_CA_CERTS as the fallback. Signed-off-by: Rhuan Barreto --- .github/workflows/release-binaries.yml | 2 +- .github/workflows/smoke-test-linux.yml | 2 +- .github/workflows/smoke-test-windows.yml | 2 +- docs/src/content/docs/nb/reference/cli/login.mdx | 4 +++- docs/src/content/docs/pt-br/reference/cli/login.mdx | 4 +++- docs/src/content/docs/reference/cli/login.mdx | 4 +++- package.json | 2 +- src/helpers/tls.ts | 4 +++- tests/helpers/tls.test.ts | 4 ++++ 9 files changed, 20 insertions(+), 8 deletions(-) diff --git a/.github/workflows/release-binaries.yml b/.github/workflows/release-binaries.yml index 124059ff..ac0bbd28 100644 --- a/.github/workflows/release-binaries.yml +++ b/.github/workflows/release-binaries.yml @@ -63,7 +63,7 @@ jobs: - name: Build binary run: | - bun build src/cli.ts --compile --bytecode --minify --target ${{ matrix.target }} --outfile dist/${{ matrix.artifact }} + bun build src/cli.ts --compile --bytecode --compile-exec-argv=--use-system-ca --minify --target ${{ matrix.target }} --outfile dist/${{ matrix.artifact }} - name: Prepare release asset (Unix) if: runner.os != 'Windows' diff --git a/.github/workflows/smoke-test-linux.yml b/.github/workflows/smoke-test-linux.yml index 06863b7c..04dacf2f 100644 --- a/.github/workflows/smoke-test-linux.yml +++ b/.github/workflows/smoke-test-linux.yml @@ -24,7 +24,7 @@ jobs: - uses: $/.github/actions/setup-bun-project - name: Build Linux binary - run: bun build src/cli.ts --compile --bytecode --outfile dist/archgate-smoke-test + run: bun build src/cli.ts --compile --bytecode --compile-exec-argv=--use-system-ca --outfile dist/archgate-smoke-test - name: Smoke test binary run: | diff --git a/.github/workflows/smoke-test-windows.yml b/.github/workflows/smoke-test-windows.yml index 38d3abb8..c41ed765 100644 --- a/.github/workflows/smoke-test-windows.yml +++ b/.github/workflows/smoke-test-windows.yml @@ -47,7 +47,7 @@ jobs: retention-days: 1 - name: Build Windows binary - run: bun build src/cli.ts --compile --bytecode --outfile dist/archgate-smoke-test + run: bun build src/cli.ts --compile --bytecode --compile-exec-argv=--use-system-ca --outfile dist/archgate-smoke-test - name: Smoke test binary shell: pwsh diff --git a/docs/src/content/docs/nb/reference/cli/login.mdx b/docs/src/content/docs/nb/reference/cli/login.mdx index 7b96d751..8128cc02 100644 --- a/docs/src/content/docs/nb/reference/cli/login.mdx +++ b/docs/src/content/docs/nb/reference/cli/login.mdx @@ -62,7 +62,9 @@ Run `archgate check` to validate your project against its ADRs. ### TLS/bedriftsproxy-feil -Hvis `archgate login` feiler med en TLS-sertifikatfeil (vanlig bak bedriftsproxyer), pek kjøretidsmiljøet mot organisasjonens CA-sertifikatpakke ved å bruke miljøvariabelen `NODE_EXTRA_CA_CERTS`. +Archgate stoler på sertifikatutstederne som er installert i operativsystemets sertifikatlager (Windows-sertifikatlageret, macOS-nøkkelringen eller systemets CA-pakke på Linux), så en bedrifts-CA som utfører TLS-inspeksjon fungerer når IT-avdelingen har installert den der. + +Hvis `archgate login` fortsatt feiler med en TLS-sertifikatfeil (vanlig bak bedriftsproxyer), ligger ikke CA-en i systemlageret. Installer den der, eller pek Archgate mot organisasjonens CA-sertifikatpakke ved å bruke miljøvariabelen `NODE_EXTRA_CA_CERTS`. På macOS/Linux: diff --git a/docs/src/content/docs/pt-br/reference/cli/login.mdx b/docs/src/content/docs/pt-br/reference/cli/login.mdx index 1a76dd8d..932a5384 100644 --- a/docs/src/content/docs/pt-br/reference/cli/login.mdx +++ b/docs/src/content/docs/pt-br/reference/cli/login.mdx @@ -62,7 +62,9 @@ Run `archgate check` to validate your project against its ADRs. ### Erros de TLS/proxy corporativo -Se `archgate login` falhar com um erro de certificado TLS (comum em redes com proxy corporativo), aponte o runtime para o certificado CA da sua organização usando a variável de ambiente `NODE_EXTRA_CA_CERTS`. +O Archgate confia nas autoridades certificadoras instaladas no repositório de certificados do sistema operacional (o repositório de certificados do Windows, o Keychain do macOS ou o pacote de CAs do sistema no Linux), então uma CA corporativa que faz inspeção TLS funciona assim que a equipe de TI a instala ali. + +Se `archgate login` ainda falhar com um erro de certificado TLS (comum em redes com proxy corporativo), a CA não está no repositório do sistema. Instale-a ali ou aponte o Archgate para o certificado CA da sua organização usando a variável de ambiente `NODE_EXTRA_CA_CERTS`. No macOS/Linux: diff --git a/docs/src/content/docs/reference/cli/login.mdx b/docs/src/content/docs/reference/cli/login.mdx index 1ea2b62f..181a3526 100644 --- a/docs/src/content/docs/reference/cli/login.mdx +++ b/docs/src/content/docs/reference/cli/login.mdx @@ -62,7 +62,9 @@ Run `archgate check` to validate your project against its ADRs. ### TLS/corporate proxy errors -If `archgate login` fails with a TLS certificate error (common behind corporate proxies), point your runtime at your organization's CA bundle using the `NODE_EXTRA_CA_CERTS` environment variable. +Archgate trusts the certificate authorities installed in your operating system's certificate store (the Windows certificate store, the macOS Keychain, or the system CA bundle on Linux), so a corporate CA that performs TLS inspection works once your IT team has installed it there. + +If `archgate login` still fails with a TLS certificate error (common behind corporate proxies), the CA is not in the system store. Install it there, or point Archgate at your organization's CA bundle using the `NODE_EXTRA_CA_CERTS` environment variable. On macOS/Linux: diff --git a/package.json b/package.json index d8c8f62c..94849640 100644 --- a/package.json +++ b/package.json @@ -37,7 +37,7 @@ "type": "module", "scripts": { "audit": "bun audit --ignore=GHSA-vfj7-8cjw-p6xm", - "build:check": "bun build src/cli.ts --compile --bytecode --outfile dist/.build-check && rm -f dist/.build-check dist/.build-check.exe", + "build:check": "bun build src/cli.ts --compile --bytecode --compile-exec-argv=--use-system-ca --outfile dist/.build-check && rm -f dist/.build-check dist/.build-check.exe", "build:winget": "bun run shims/winget/build.ts", "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0", "check": "bun run src/cli.ts check", diff --git a/src/helpers/tls.ts b/src/helpers/tls.ts index 157406ff..82298fa3 100644 --- a/src/helpers/tls.ts +++ b/src/helpers/tls.ts @@ -44,7 +44,9 @@ export function tlsHintMessage(): string { "TLS certificate verification failed.", "This typically happens behind a corporate proxy that performs SSL inspection.", "", - "To fix this, set the NODE_EXTRA_CA_CERTS environment variable to your corporate CA certificate:", + "Archgate trusts the certificate authorities installed in your operating system's", + "certificate store. Ask your IT team to install the corporate CA certificate there,", + "or set the NODE_EXTRA_CA_CERTS environment variable to its path:", "", ...examples, "", diff --git a/tests/helpers/tls.test.ts b/tests/helpers/tls.test.ts index 1cf4a061..71271855 100644 --- a/tests/helpers/tls.test.ts +++ b/tests/helpers/tls.test.ts @@ -46,6 +46,10 @@ describe("tlsHintMessage", () => { expect(tlsHintMessage()).toContain("NODE_EXTRA_CA_CERTS"); }); + test("mentions the operating system certificate store", () => { + expect(tlsHintMessage()).toContain("operating system"); + }); + test("mentions corporate proxy", () => { expect(tlsHintMessage()).toContain("corporate proxy"); }); From 9f01c198fb26c5777a094bd995c78629e361f796 Mon Sep 17 00:00:00 2001 From: rhuanbarreto <283004+rhuanbarreto@users.noreply.github.com> Date: Thu, 22 Oct 2026 15:32:13 +0000 Subject: [PATCH 2/3] docs: regenerate llms-full.txt Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/public/llms-full.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index bf5e4743..0c1af587 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -4777,7 +4777,9 @@ Run `archgate check` to validate your project against its ADRs. ### TLS/corporate proxy errors -If `archgate login` fails with a TLS certificate error (common behind corporate proxies), point your runtime at your organization's CA bundle using the `NODE_EXTRA_CA_CERTS` environment variable. +Archgate trusts the certificate authorities installed in your operating system's certificate store (the Windows certificate store, the macOS Keychain, or the system CA bundle on Linux), so a corporate CA that performs TLS inspection works once your IT team has installed it there. + +If `archgate login` still fails with a TLS certificate error (common behind corporate proxies), the CA is not in the system store. Install it there, or point Archgate at your organization's CA bundle using the `NODE_EXTRA_CA_CERTS` environment variable. On macOS/Linux: From 4942818d0ab0779cfaf5fecf39fa6b7c69a7e76f Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Thu, 22 Oct 2026 17:44:09 +0200 Subject: [PATCH 3/3] fix: scope the OS certificate store claim to the archgate binary Signed-off-by: Rhuan Barreto --- src/helpers/tls.ts | 2 +- tests/helpers/tls.test.ts | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/src/helpers/tls.ts b/src/helpers/tls.ts index 82298fa3..1dd9fabb 100644 --- a/src/helpers/tls.ts +++ b/src/helpers/tls.ts @@ -44,7 +44,7 @@ export function tlsHintMessage(): string { "TLS certificate verification failed.", "This typically happens behind a corporate proxy that performs SSL inspection.", "", - "Archgate trusts the certificate authorities installed in your operating system's", + "The archgate binary trusts the certificate authorities installed in your operating system's", "certificate store. Ask your IT team to install the corporate CA certificate there,", "or set the NODE_EXTRA_CA_CERTS environment variable to its path:", "", diff --git a/tests/helpers/tls.test.ts b/tests/helpers/tls.test.ts index 71271855..c4081bb7 100644 --- a/tests/helpers/tls.test.ts +++ b/tests/helpers/tls.test.ts @@ -48,6 +48,7 @@ describe("tlsHintMessage", () => { test("mentions the operating system certificate store", () => { expect(tlsHintMessage()).toContain("operating system"); + expect(tlsHintMessage()).toContain("certificate store"); }); test("mentions corporate proxy", () => {