You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit ca2a708
Browse filesBrowse the repository at this point in the historyBrowse files
feat(express): add default domain-scoped CA trust for BitGo connections
Restrict outbound HTTPS connections to official BitGo domains
(*.bitgo.com, *.bitgo-test.com, *.bitgo-staging.com, *.bitgo-dev.com,
and their apex domains) to a bundled multi-provider root CA store
(Google Trust Services, Amazon Trust Services, DigiCert, Let's
Encrypt/ISRG, and Sectigo) while keeping the system trust store for all
non-BitGo destinations:
- sdk-api: add createBitGoTlsPolicy({ ca, hosts }) and enforce it in
BitGoAPI.getAgentRequest (refusing redirects and plain http on covered
hosts)
- express: enable the bundled 18-root CA policy by default at startup,
with a single opt-out flag (--disablepincerts /
BITGO_DISABLE_PIN_CERTS)
and automatic proxy fallback when BITGO_USE_PROXY is set
- scripts/verify-bitgo-policy-data.sh: CI check verifying all bundled
roots are self-signed, valid (>30d), and cover all BitGo domains
(plus --live handshake verification)
TICKET: WCN-3731
Copy file name to clipboardExpand all lines: modules/express/README.md
+21Lines changed: 21 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -198,6 +198,26 @@ BitGo Express currently supports the following proxy protocols:
198
198
- SOCKSv5
199
199
- PAC
200
200
201
+
### Domain-scoped CA trust for BitGo connections
202
+
203
+
By default, BitGo Express restricts outbound HTTPS connections to official BitGo domains (`*.bitgo.com`, `*.bitgo-test.com`, `*.bitgo-staging.com`, `*.bitgo-dev.com`, and their apex domains) to a bundled set of root certificate authorities (`modules/express/bitgo-ca.pem`: Google Trust Services, Amazon Trust Services, DigiCert, Let's Encrypt/ISRG, and Sectigo). Every other outbound destination (external signer, block explorers, webhooks, KMS) continues to use the Node.js / system trust store.
204
+
205
+
This is **enabled by default** to shrink the blast radius of a compromise of any unrelated CA in the global trust store without requiring manual certificate-pin maintenance across routine BitGo certificate renewals or CA migrations.
206
+
207
+
- To opt out, pass `--disablepincerts` or set `BITGO_DISABLE_PIN_CERTS=true`.
208
+
- When `BITGO_USE_PROXY` is set, Express logs a startup warning and skips the bundled CA policy because the proxy agent owns the TLS connection.
209
+
- If your network uses a **transparent TLS-inspecting firewall/proxy** (no `BITGO_USE_PROXY`) whose CA you trust via `NODE_EXTRA_CA_CERTS`: note that the policy agent replaces the trust store for BitGo domains, so `NODE_EXTRA_CA_CERTS` is **ignored** for them. Express logs a startup warning in this case; either pass `--disablepincerts` / `BITGO_DISABLE_PIN_CERTS=true`, or the connections fail with `unable to get local issuer certificate` / `SELF_SIGNED_CERT_IN_CHAIN`. This is a behavior change from prior releases (BitGo domains previously trusted `NODE_EXTRA_CA_CERTS`).
210
+
- Redirects are validated on each hop for covered BitGo hostnames: redirects to other covered `https://` BitGo hosts are followed, while redirects to uncovered hosts or plain `http://` are refused.
211
+
- At startup, Express warns if any root CA in `bitgo-ca.pem` expires within 30 days.
212
+
- The bundle is **not** self-updating. Regenerate it from the current Node.js root store (e.g. when BitGo switches CA providers or a root nears expiry) and re-verify against live endpoints:
cd modules/express && yarn test:data:live # offline checks + live handshakes to all BitGo endpoints
216
+
```
217
+
If BitGo ever moves `*.bitgo.com` to a CA provider outside the bundled roots, update `bitgo-ca.pem`**before** the cutover (deployed customers run older images).
218
+
219
+
> The underlying policy helper (`createBitGoTlsPolicy` in `@bitgo/sdk-api`) is Node-only: it relies on the Node `crypto` and `tls` modules and refuses to build in a browser bundle.
220
+
201
221
### External Signing Mode
202
222
203
223
BitGo Express can be run in an external signing mode, where the signing of transactions is performed in a separate instance of BitGo Express that has access to the private keys.
@@ -241,6 +261,7 @@ BitGo Express is able to take configuration options from either command line arg
241
261
| N/A | --lightningSignerFileSystemPath |`BITGO_LIGHTNING_SIGNER_FILE_SYSTEM_PATH`| N/A | Local path specifying how to contact the lightning signer node. |
| N/A | --disablepincerts |`BITGO_DISABLE_PIN_CERTS`| false | Disable the default domain-scoped CA bundle restriction for BitGo hostnames. See [Domain-scoped CA trust for BitGo connections](#domain-scoped-ca-trust-for-bitgo-connections). |
244
265
245
266
\[0]: BitGo will also check the additional environment variables for some options for backwards compatibility, but these environment variables should be considered deprecated:
0 commit comments