hackbrowser: corporate SSL-inspection proxy (Zscaler) breaks worker TLS — auto-CA-trust misses corporate root, cryptic errors

[badchars]

Summary

Behind a corporate SSL-inspection proxy (e.g. Zscaler / Netskope), the hackbrowser worker's outbound TLS connections fail certificate verification, so the crawl degrades badly and stops early. The worker already has trustSystemCertificates() (the in-process equivalent of --use-system-ca), but in a corporate Windows environment it did NOT pick up the corporate root CA, and the resulting errors are cryptic with no guidance.

Symptoms (observed, corporate Windows + Zscaler)

• error: unable_to_get_issuer_cert_locally downloading package manifest @cyberstrike-io/plugin (plugin install)
• service=hackbrowser:navigator err=TypeError: unable to get local issuer certificate — planPage failed, retrying once (repeated very frequently)
• unable to get local issuer certificate — planUnexploredElements failed
• Net effect: planner LLM calls fail TLS → empty plans → few links discovered → crawl stops early (observed 38/100 instead of a full crawl).

Root cause

Corporate proxy presents its own root CA; the runtime doesn't trust it by default. trustSystemCertificates() relies on tls.getCACertificates("system") / setDefaultCACertificates — a no-op if the worker runtime is too old to expose those APIs, or if the system-store read misses the corporate root on Windows. The corporate root IS present in the OS trust store (browsers work), so auto-trust should pick it up but doesn't in this environment.

Workaround (confirmed working)

Set NODE_EXTRA_CA_CERTS to a PEM bundle of the OS trust store (which includes the corporate root). Propagates to the worker via the launcher's inherited spawn env; fixes both the plugin-download and planner TLS errors → full crawl.

Proposed fix

1. Actionable error: when an outbound TLS cert error is detected, emit a single clear message — "TLS verification failed, likely a corporate SSL-inspection proxy; set NODE_EXTRA_CA_CERTS to your corporate root CA (see docs)" — instead of repeating the cryptic error every planner call.
2. Harden auto-trust: verify the worker's fetch honors NODE_EXTRA_CA_CERTS and reads the Windows cert store reliably; provide a fallback when the runtime lacks getCACertificates.
3. Docs: add a "corporate proxy / TLS" page (handled in the docs repo) covering the NODE_EXTRA_CA_CERTS setup + the cert-store export command.

Pending

• Confirm the worker runtime version in the affected environment (bun --version / node --version) to pin whether getCACertificates was the gap.

[badchars]

Resolved via documentation + verified workaround.

Root cause: a corporate SSL-inspection proxy (Zscaler) re-signs HTTPS with the company root CA, which the worker runtime didn't trust → unable to get local issuer certificate on the planner's LLM calls → the crawl degraded and stopped early (observed 38/100 on a corporate Windows machine).

Fix (workaround, verified): point NODE_EXTRA_CA_CERTS at a PEM export of the OS trust store (which already contains the corporate root). Confirmed on the affected corporate Windows + Zscaler machine — the TLS errors cleared and crawls run to completion.

Docs: CyberStrikeus/docs#2 (merged) — Installation → Troubleshooting → "Corporate Networks (SSL Inspection / Zscaler)", with Windows/macOS export commands and a caution against NODE_TLS_REJECT_UNAUTHORIZED=0.

Optional code hardening (emit a single actionable "set NODE_EXTRA_CA_CERTS" message instead of the repeated cryptic error, and make the worker's auto-CA-trust more robust) was deprioritized since the documented workaround fully unblocks affected users. Can be filed as a separate follow-up if desired.