feat: protocol-aware proxy validation with HTTPS support

.gitignore

@@ -16,3 +16,7 @@ CLAUDE.local.md
 
 # internal research docs (not for public)
 docs/internal/
+
+.claude/
+
+package-lock.json

.tmp-ca-test/ca_cert.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFYDCCA0igAwIBAgIUHpzjz7Wb9mKQyzMQm4j7wOiy2fIwDQYJKoZIhvcNAQEL
+BQAwNjEXMBUGA1UEAwwOY2FjLXByaXZhY3ktY2ExDDAKBgNVBAoMA2NhYzENMAsG
+A1UECwwEbXRsczAeFw0yNjA0MDkxODQyMTNaFw0zNjA0MDYxODQyMTNaMDYxFzAV
+BgNVBAMMDmNhYy1wcml2YWN5LWNhMQwwCgYDVQQKDANjYWMxDTALBgNVBAsMBG10
+bHMwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQCiubhU40/bpW1DFsqu
+y3w5K6P2lu0foYJGDQ6v0+/9XGDk1C/UPvduhFJPBgl64TuWVmZBtc71PGINhJL+
+VfaviGvgro1kvoOAoFDMMXA3nJyvNyjYRgidJbndltsS5VN4AJBUQeOAN4gWW6He
+rvkIE4e0m+T0WyWKVh9PCsuqpNzEa9BQY47rBNuGUcOCck3ZvXb7fDW9y9tSCrTW
+eibFI68fvi5oDAclridFV1UUxYvgBh6GFJkL0hpkI71JEjAB7W1dgwLyuF7pEhM0
+Y5rC4y1CqxLqOkNHpuNVC/nmbqkPn2seFrOuuz5Fqill2yqJJvEbfQqjluhtMMw9
+xrlXe5PL6r8UMSGgmvEVgkduZKsORKC7hPl6bvwINt+lbpWkJv8dPk9buhEQJ80/
+diBxmi/DwQLrOiec3LDHvGN+6bCUY0SrH9/buPCDVQmctfOdkwS1siezLb5HTiFB
+MXKArwqFtY4K3ZCi/nzFmjIwlw4UDO5h0MBD6IRczbE1v3Q5VyJpIgAdcs7AT8EI
+NhMZNhLUhKuAJG1LDCTD3r9fDOpnGBU4CvuBSin+GGPsLZn30sv20nJ8R6vpHIh3
+U+aWQpMHyrQ85wFa6AuEw49WwO/cbKsBXEspt4lFGfvPA/VoNvwpVrzR0QYBTZxT
+wBmKRED58PKjmhg9Xntlc10W3wIDAQABo2YwZDAdBgNVHQ4EFgQUNoBWe2hvuZ5Z
+rYB0/EDBX814GHQwHwYDVR0jBBgwFoAUNoBWe2hvuZ5ZrYB0/EDBX814GHQwEgYD
+VR0TAQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQELBQAD
+ggIBAD1azExREtHea0XVcBGjBlNvoNR3cPUBzfS4J5HgkJhAcN0m9o3vBsvF1rOu
+cg1t5l8KBPJ1LgaWmVFXUQ5XsXEM3OYYmE027yzyk/vqt2U7h0CsOzascF3Vrh4N
+skIyOYdzQQj2ftWj5CWFAWRMR15RYf1jN2adY1M4ILDkybqBHf9Y1lxwSGJ08f4W
+pHJtVe2cUwOfWhGDInhVyze6D2JxngNFrOnc4cZtd1tkxG91sRX3+mbU3q3J7DOc
+DtDyRvqBibv6hEltdPjwrT23Tc2Knzr88/2waTS6Vo2uv51x26zxbsRcpanHo37A
+1klOQDA8mNqtRWE1oAJwOfu4u90htIqLg+pxp4Tt1FNME18geVG1o3lSQYQMDplz
+e4m0h+KvvvXmPONVXE2LwS0c9MoxsGmgoJy2sndrHGeMyxW0jnFe7opcV/vbdqrx
+aVIeir95sUwqLZGLU+4bph0pwdT2BsRGo+XbP0kq5CALzI7R3qcq05mYumRc67WS
+QU9xskyOXgX3fWItQIzO2B+el6qMkjs9BAwNXrETsOa1WO9iiI6NbE6LSSwx2DGA
+X49uCJlBIts9zQSXGLHRb8wj3bpK8RZH+pA3NsYgy6GWkhH9f2R9Va7QQSqoW4jq
+MShKMm3haxn9ivJrm5R7lTNekAkxrKlOgVpLSxa5OmBzJiNZ
+-----END CERTIFICATE-----

.tmp-ca-test/ca_key.pem

@@ -0,0 +1,52 @@
+-----BEGIN PRIVATE KEY-----
+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
+Hf0zVO5XVeQnOuCllIL9nrz5aEC7Hgzcsvosblx5AoIBAGs4ZldWLNPZxpWhQLOt
+qth1guqTpHZjAXRN3/H5ugj8CDE2AFZjb0BCWFdHc7tjPSoclW0QlRWrQ8/VlP3B
+DO3pZ2ZzYIXRPeVlrTQQIhqrahZzjrl2h5r6V3X69QDxohBUtco6o7DDrTNJkPBO
+8/X32+yNDrmNsAI67kOquAcjO3GFTnmmlJf52Ecn8vKYmBifJmQ57bfyHd3yL0dt
+D6xbeo62nGNUy5ezIc0kkU97LbiylP5vNokzb+O6OGAhU60MhzXnULFqFKAizsuy
+QZv2z5NjTAus/bcBdFf4EwjkcXGF1WJD3C78ce6C+mpKUSswgHrJHHXoz1ZGPjNf
+/0kCggEAOeqZ4fBOdCkpsMV9nWsS6bSua9V2cUEfSgAdxxBN3ABy3K8DKsCGcjv/
+nmgfruNtWKdB4khgJUcWhWXFfzs2+XClmMaGC7MycCVLGSs7/OlVXi14YCqjixZE
+2lVXUn/pJKAnkC736XptvWYNmEKjpIfG/X6z+nC0RpdHS+u3bTqIT1iQLs573F7T
+FimMvYIBd+Q+pU5jHvNz+g8LKxIQfebVPgZzUwlyJQuDz+9cAW2V26oCygRiISBp
+gXBRDj33L5BTEhSzWVJDHC7E0jumfwX8HB2PshJhN5ojE7nxOTRHhEdnGUCsnOYA
+te4Qgsc90gmX3tgfC15rkXU29Msivw==
+-----END PRIVATE KEY-----

AGENTS.md

@@ -0,0 +1,34 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+`src/` contains the canonical implementation: modular Bash commands such as `cmd_env.sh`, shared helpers in `utils.sh`, and runtime JS hooks in `fingerprint-hook.js` and `relay.js`. `build.sh` concatenates these sources into the generated root executable `cac`; do not edit `cac` directly. `scripts/postinstall.js` handles npm install-time setup and migration. `tests/` contains shell smoke tests (`test-*.sh`). `docker/` holds container assets, and `docs/` stores user-facing documentation, including Windows-specific guides.
+
+## Build, Test, and Development Commands
+Use Node.js 14+ and Bash; Windows contributors should run shell tests from Git Bash.
+
+```bash
+bash build.sh
+shellcheck -s bash -S warning src/utils.sh src/cmd_*.sh src/dns_block.sh src/mtls.sh src/templates.sh src/main.sh build.sh
+node --check src/relay.js
+node --check src/fingerprint-hook.js
+bash tests/test-cmd-entry.sh
+bash tests/test-windows.sh
+```
+
+`bash build.sh` regenerates `cac`, `relay.js`, `fingerprint-hook.js`, and `cac-dns-guard.js`. Run it after every `src/` change and commit the rebuilt `cac` with the source edit.
+
+## Coding Style & Naming Conventions
+Follow existing Bash style: `#!/usr/bin/env bash`, `set -euo pipefail`, small helper functions, and 4-space indentation inside blocks. Name command modules `cmd_<topic>.sh`; internal helpers use `_snake_case`. Keep comments brief and operational. For JS, match the current CommonJS/Node-14-compatible style: `var`, semicolons, and minimal syntax. Prefer extending existing files over adding new entrypoints unless the command surface changes.
+
+## Testing Guidelines
+There is no formal coverage gate, but every change should pass the shell and JS checks above. Add or update shell smoke tests in `tests/test-*.sh` when behavior changes, especially for Windows wrappers, path handling, or generated files. If you touch `src/templates.sh`, `cac.cmd`, or install flows, run both test scripts.
+
+## Commit & Pull Request Guidelines
+Recent history uses Conventional Commit prefixes such as `fix:`, `feat(utils):`, and `test:`. Keep subjects imperative and scoped when useful. For pull requests targeting `master`, include:
+
+- a short description of the behavior change
+- the commands you ran to validate it
+- any platform coverage (`macOS`, `Linux`, `Windows`)
+- confirmation that `bash build.sh` was run and the generated `cac` is included
+
+Screenshots are only needed for documentation or docs-site changes.

CLAUDE.md

@@ -0,0 +1,107 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**cac** (Claude Anti-fingerprint Cloak) is a CLI environment manager for Claude Code. It provides version management, environment isolation, device fingerprint spoofing, telemetry blocking, and proxy routing. Published as `claude-cac` on npm. Supports macOS, Linux, and Windows.
+
+## Build System
+
+The project uses a **single-file concatenation build**. Source lives in modular shell scripts under `src/`, and `build.sh` concatenates them in a fixed order into the root `cac` executable. Both source files AND the built `cac` must be committed — CI verifies they match.
+
+```bash
+# Build (regenerates cac, fingerprint-hook.js, relay.js, cac-dns-guard.js)
+bash build.sh
+
+# Lint (ShellCheck on all bash sources)
+shellcheck -s bash -S warning src/utils.sh src/cmd_*.sh src/dns_block.sh src/mtls.sh src/templates.sh src/main.sh build.sh
+
+# JS syntax check
+node --check src/relay.js
+node --check src/fingerprint-hook.js
+
+# Shell smoke tests (run from Git Bash on Windows)
+bash tests/test-cmd-entry.sh
+bash tests/test-windows.sh
+```
+
+**After editing any file in `src/`, always run `bash build.sh` and commit the rebuilt `cac` alongside the source changes.** CI will fail otherwise. When touching `src/templates.sh`, `cac.cmd`, or install flows, run both test scripts.
+
+## Architecture
+
+### Build Concatenation Order
+
+`build.sh` assembles `cac` from `src/` in this order:
+1. `utils.sh` — core utilities, version constant (`CAC_VERSION`), UUID generation, proxy parsing, color output
+2. `dns_block.sh` — DNS interception, telemetry domain blocking, embeds `cac-dns-guard.js` via heredoc
+3. `mtls.sh` — mTLS certificate generation (self-signed CA + per-env client certs)
+4. `templates.sh` — generates shell wrapper and shim-bin scripts at runtime
+5. `cmd_setup.sh` — initial setup command
+6. `cmd_env.sh` — `cac env` commands (create/list/set/activate/check)
+7. `cmd_relay.sh` — TCP relay management, TUN proxy detection
+8. `cmd_check.sh` — `cac env check` environment verification
+9. `cmd_stop.sh` — stop command
+10. `cmd_claude.sh` — `cac claude` version management (install/uninstall/ls/pin)
+11. `cmd_self.sh` — self-update and uninstall
+12. `cmd_docker.sh` — Docker container mode
+13. `cmd_delete.sh` — deletion/cleanup
+14. `cmd_version.sh` — version display
+15. `cmd_help.sh` — help text
+16. `main.sh` — command dispatcher (entry point)
+
+### Key JavaScript Files
+
+- `src/fingerprint-hook.js` — injected via `NODE_OPTIONS --require`, overrides `os.hostname()`, `os.networkInterfaces()`, etc.
+- `src/relay.js` — local TCP relay for proxy routing
+- `cac-dns-guard.js` — extracted from heredoc in `dns_block.sh` during build; blocks DNS lookups to telemetry domains and replaces `global.fetch()`
+
+### Wrapper Execution Flow
+
+When the user types `claude`, the wrapper at `~/.cac/bin/claude` (generated by `templates.sh`):
+1. Reads `~/.cac/current` for active environment name
+2. Loads identity files from `~/.cac/envs/<name>/` (proxy, version, uuid, hostname, etc.)
+3. Sets `CLAUDE_CONFIG_DIR` to the isolated `.claude/` directory
+4. Resolves Claude binary from `~/.cac/versions/<ver>/claude`
+5. Injects environment variables: proxy, 12 telemetry kill vars, identity vars
+6. Sets `NODE_OPTIONS` to `--require fingerprint-hook.js cac-dns-guard.js`
+7. Prepends `~/.cac/shim-bin` to `PATH` (intercepts `hostname`, `ifconfig`, `ioreg`, `cat`)
+8. Starts relay if TUN-mode proxy detected
+9. Execs the real Claude binary
+
+### Privacy Protection Layers
+
+Protection is multi-layered and fail-closed (connection stops if any layer fails):
+- **Shell shims** in `shim-bin/` intercept system commands (`hostname`, `ioreg`, `ifconfig`, `cat /etc/machine-id`) — **macOS/Linux only**; the shimmed commands do not exist on Windows and `shim-bin/` is inert there
+- **Node.js hooks** via `fingerprint-hook.js` override `os.hostname()`, `os.networkInterfaces()`, and on Windows additionally intercept `wmic csproduct get uuid` and `reg query …MachineGuid` across `execSync`/`exec`/`execFileSync` — this is the **sole** process-level interception layer on Windows
+- **DNS guard** blocks telemetry domains at DNS level and intercepts `fetch()`
+- **Environment variables** (12 vars: `DO_NOT_TRACK=1`, `OTEL_SDK_DISABLED=true`, etc.)
+- **HOSTALIASES** maps telemetry domains to `0.0.0.0`
+- **Health check bypass** intercepts `api.anthropic.com/api/hello` in-process
+
+Windows protection boundary: any native subprocess that reads fingerprint data **without** going through Node.js (e.g. a `.exe` that calls WMI directly) bypasses the Node hook and is not covered. See `docs/windows/windows-support-assessment.md` for the full gap analysis.
+
+### Windows Support
+
+`cac.ps1` is the PowerShell equivalent of the bash `cac` script. `cac.cmd` is a batch wrapper that delegates to `cac.ps1`.
+
+## CI/CD
+
+- **ci.yml** — runs on push/PR to master: ShellCheck, build consistency check, JS syntax validation
+- **npm-publish.yml** — triggered by `v*` tags: updates version in `package.json` and `src/utils.sh`, runs `build.sh`, publishes to npm
+- **docker.yml** — builds Docker image to ghcr.io (manual/scheduled)
+
+## Key Conventions
+
+- Version constant lives in `src/utils.sh` as `CAC_VERSION` — updated automatically by the npm-publish workflow
+- All bash scripts must pass `shellcheck -S warning`
+- The `cac` root file is auto-generated — **never edit it directly**, always edit `src/` files
+- Zero npm runtime dependencies; the package ships only bash + vendored JS
+- `scripts/postinstall.js` handles npm post-install: makes binaries executable, syncs runtime JS files, patches wrappers, migrates old environments
+
+## Coding Style
+
+- Bash: `#!/usr/bin/env bash` + `set -euo pipefail`, 4-space indentation inside blocks, small helper functions, internal helpers use `_snake_case`
+- Command modules are named `cmd_<topic>.sh`; prefer extending existing files over adding new entrypoints unless the command surface changes
+- JS must remain Node-14 compatible CommonJS: `var`, semicolons, minimal modern syntax (no ESM, no top-level await)
+- Commit subjects follow Conventional Commits (`fix:`, `feat(utils):`, `test:`) — imperative and scoped