@etiennepasteur/jean-claude 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Etienne Pasteur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,422 @@
+# jean-claude
+
+A CLI MITM HTTPS proxy that intercepts a tool's API traffic and rewrites it from a
+YAML file. The tool being intercepted never knows.
+
+It was built for one job in particular: **freezing the settings Claude Code
+fetches at startup**, so the ones you control apply instead of the ones the API
+hands back. Everything else it does — capture, stub, patch, redirect — falls out
+of the same machinery and works against any HTTPS client.
+
+```
+Claude Code  ──►  jean-claude  ──►  api.anthropic.com
+                  ▲
+                  └── ~/.config/jean-claude/jean-claude.yaml
+                      + responses/settings.GET.json
+```
+
+## Freezing Claude Code's settings
+
+On startup, Claude Code calls `GET https://api.anthropic.com/api/claude_code/settings`
+and applies the managed settings attached to your account. The response looks like
+this:
+
+```json
+{
+  "uuid": "…",
+  "checksum": "sha256:…",
+  "settings": {
+    "env": { "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1" },
+    "permissions": { "defaultMode": "plan" }
+  }
+}
+```
+
+jean-claude answers that one request from a local file. It never leaves the
+machine, and the settings stop moving under you between sessions. Every other call
+Claude Code makes — the actual conversation — is relayed untouched.
+
+### 1. Set it up
+
+```bash
+npm install -g @etiennepasteur/jean-claude
+jean-claude init --claude-code
+```
+
+The package is scoped, but the command it installs is plain `jean-claude` — that
+is what every example below uses.
+
+Or without installing anything — `npx` works the same way:
+
+```bash
+npx @etiennepasteur/jean-claude init --claude-code
+npx @etiennepasteur/jean-claude run -- claude
+```
+
+Installing globally is the better default for something you launch every session:
+the dependency tree is ~55 MB, so the first `npx` run is a real download, and even
+warm it adds about half a second of resolution. `npx` is the right call for trying
+it once, or for a throwaway CI step.
+
+Either way, that writes `~/.config/jean-claude/` with a CA, a starter stub, and
+this config:
+
+```yaml
+host: api.anthropic.com
+
+rules:
+  - name: frozen claude_code settings
+    method: GET
+    path: /api/claude_code/settings
+    respond: ./responses/settings.GET.json
+```
+
+### 2. Edit the settings
+
+Open `~/.config/jean-claude/responses/settings.GET.json` and put what you want
+in the `settings` object. The file is re-read on **every request**, so a change
+applies the next time Claude Code starts — no proxy restart, no reload.
+
+To start from what your account actually sends rather than from the scaffolded
+stub, record it once:
+
+```bash
+jean-claude run --record ./captures -- claude
+cp ./captures/api.anthropic.com/api/claude_code/settings.GET.json \
+   ~/.config/jean-claude/responses/settings.GET.json
+```
+
+### 3. Run it
+
+```bash
+jean-claude run -- claude
+```
+
+Add `-v` the first time, to see every request rather than only the ones a rule
+touched:
+
+```
+  GET   api.anthropic.com/api/claude_code/settings   200  → stub responses/settings.GET.json
+  POST  api.anthropic.com/v1/messages                200
+```
+
+A `→ stub` on the settings line means it worked. If you would rather keep the log
+out of Claude Code's output, run the proxy in its own terminal —
+see [Two terminals](#two-terminals-start--env).
+
+## Where everything lives
+
+```
+~/.config/jean-claude/          # $XDG_CONFIG_HOME/jean-claude if set
+├── jean-claude.yaml
+├── responses/
+├── ca/  ca.pem  ca.key  bundle.pem
+└── session.json                # only while `start` is running
+```
+
+The config is resolved in this order:
+
+1. `--config <path>`
+2. `jean-claude.yaml` (or `.yml`) in the current directory, then walking up
+3. `~/.config/jean-claude/jean-claude.yaml`
+
+So the global rule applies wherever you launch Claude Code from, and a repo that
+drops its own `jean-claude.yaml` at the root overrides it for that project. Paths
+inside a config (`respond:`, `patch: { file: }`) are always relative to that
+config file.
+
+`--home <dir>` relocates the whole directory — for a throwaway setup, or to run
+two proxies side by side.
+
+## Beyond Claude Code
+
+Nothing in the machinery is Anthropic-specific. `jean-claude init` without
+`--claude-code` scaffolds a generic config, and the same rules work against any
+HTTPS client that honours the proxy environment variables:
+
+```bash
+jean-claude init
+jean-claude run -- npx your-tool
+```
+
+The problem it solves in general: you are developing against a third-party API and
+you need to _see_ and _falsify_ what a tool receives, without touching either the
+tool or the server. Reproduce a 500. Test a business case that is absent from the
+dataset. Freeze a flaky response. Or simply find out what the tool actually calls.
+
+### 1. Replace the response with a file
+
+The request never leaves the machine. This is what the Claude Code rule uses.
+
+```yaml
+rules:
+  - path: /api/todos
+    method: GET
+    respond: ./responses/todos.json
+```
+
+The stub file is re-read on **every request**, so editing it takes effect
+immediately — no restart, no reload.
+
+Longer form, with status, headers and latency:
+
+```yaml
+rules:
+  - path: /api/todos
+    respond:
+      file: ./responses/todos.json
+      status: 201
+      headers: { x-jean-claude: stub }
+      delay: 500
+```
+
+Or an inline body, with no file at all:
+
+```yaml
+rules:
+  - path: /api/health
+    respond:
+      body: { status: 'ok' }
+```
+
+### 2. Patch the real response
+
+The request _does_ reach the server; jean-claude edits what comes back. Useful
+when you want the live payload with one field bent, rather than a frozen copy
+that goes stale.
+
+```yaml
+rules:
+  # Precise edit, and the only option that works on an array response.
+  - path: /api/todos
+    patch:
+      jsonPatch: [{ op: replace, path: /0/title, value: Dining }]
+
+  # Deep merge, for object responses.
+  - path: /api/users/:id
+    patch:
+      merge: { verified: true }
+
+  # Simulate a failing, slow server. The original body is preserved
+  # unless you replace it.
+  - path: /api/flaky
+    patch:
+      status: 500
+      body: { error: 'boom' }
+      delay: 2000
+```
+
+`patch` accepts `status`, `headers` (merged), `replaceHeaders` (wholesale),
+`merge`, `jsonPatch`, `body`, `file` and `delay`.
+
+### 3. Rewrite the outgoing request
+
+```yaml
+rules:
+  - host: auth.example.com
+    path: /oauth/token
+    request:
+      host: staging-auth.example.com
+      path: /v2/token
+      headers: { authorization: 'Bearer TEST' }
+      removeHeaders: [cookie]
+```
+
+`request` combines with `patch` — you can redirect a call _and_ doctor its
+response. It cannot combine with `respond`, which short circuits the request
+before it goes anywhere.
+
+## Matching
+
+```yaml
+host: api.example.com # default host for every rule below
+port: 8888 # optional, otherwise a free port is picked
+
+rules:
+  - host: auth.example.com # overrides the default
+    method: [POST, PUT] # one method or a list, case-insensitive
+    path: /api/users/:id # exact, :param, or a bare * wildcard
+    query: { page: '2' } # required params; extra ones are ignored
+```
+
+- A rule with no `host` matches **any** host.
+- `*.example.com` matches any subdomain.
+- `path` is compiled by `path-to-regexp`: `/api/todos`, `/api/users/:id`, `/api/*`.
+  Use `pathRegex` when you need a raw regular expression.
+- Captured parameters interpolate into the stub path:
+  `respond: ./responses/users/{id}.json`.
+- Rules are tried in file order and **the first match wins**. `jean-claude check`
+  prints them as resolved.
+- Anything matching no rule is still decrypted, logged and relayed untouched.
+
+## Discovering and capturing traffic
+
+```bash
+jean-claude run --record ./captures -- npx your-tool
+```
+
+```
+  GET   api.example.com/api/todos      200  → stub responses/todos.json
+  GET   api.example.com/api/users/42   200  ⇒ captures/api.example.com/api/users/42.GET.json
+  POST  api.example.com/api/login      401  ⇒ captures/api.example.com/api/login.POST.json
+```
+
+Captures contain the **body only**, re-indented, so a captured file drops
+straight into a `respond:` rule — that is the shortcut used to seed the Claude
+Code stub above. When a rule patches a response, the capture is still the
+untouched server response, not what the client saw.
+
+By default only affected traffic is logged. Add `-v` to see everything, `-q` to
+see nothing.
+
+## Certificates
+
+On first run, jean-claude generates a CA in `~/.config/jean-claude/ca/`:
+
+| File                | Role                                                                           |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `ca.pem` / `ca.key` | the authority that signs per-host certificates on the fly (`ca.key` is `0600`) |
+| `bundle.pem`        | `ca.pem` + the system trust store + any inherited corporate CA                 |
+
+The bundle exists because `SSL_CERT_FILE` and `CURL_CA_BUNDLE` **replace** the
+trust store rather than adding to it — handing a target only our own CA would cut
+it off from every other authority.
+
+`jean-claude run` points the child at the bundle, so **no root access and no
+system-wide trust change is needed**. If you do want the CA in the system store
+(for a GUI app, say), `jean-claude ca --install` prints the commands for you to
+run yourself. jean-claude never invokes `sudo` on its own.
+
+### Behind a corporate proxy
+
+jean-claude reads the environment before rewriting it for the child, and chains
+onto whatever it finds:
+
+- `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` → relayed traffic goes out through
+  your corporate proxy. Override with `upstream:` in the config (`auto`, `off`,
+  or an explicit URL).
+- `NODE_EXTRA_CA_CERTS` → your corporate CA is trusted on outbound connections
+  _and_ folded into `bundle.pem` for the child.
+
+### When a target refuses the CA
+
+A client that pins its certificates will fail the handshake. jean-claude says so
+explicitly rather than leaving you guessing, and the fix is to tunnel that host
+without interception:
+
+```yaml
+tlsPassthrough:
+  - pinned.example.com
+```
+
+## How the target is pointed at the proxy
+
+`jean-claude run` injects these into the child environment:
+
+| Variable                                                                                   | Why                                                 |
+| ------------------------------------------------------------------------------------------ | --------------------------------------------------- |
+| `HTTP_PROXY`, `HTTPS_PROXY` (+ lowercase)                                                  | the universal convention                            |
+| `NODE_USE_ENV_PROXY=1`                                                                     | **required**: Node ignores `HTTPS_PROXY` without it |
+| `NODE_EXTRA_CA_CERTS`                                                                      | Node targets                                        |
+| `SSL_CERT_FILE`, `CURL_CA_BUNDLE`, `REQUESTS_CA_BUNDLE`, `AWS_CA_BUNDLE`, `GIT_SSL_CAINFO` | OpenSSL, curl, python/requests, AWS CLI, git        |
+
+`NO_PROXY` is **unset**, not narrowed. The tempting default is
+`localhost,127.0.0.1,::1`, but that makes every localhost target bypass
+jean-claude silently — and intercepting a local dev API is one of the main reasons
+to reach for this tool. A bypass that still produces plausible traffic is the
+worst possible failure mode, so exclusions are opt-in:
+
+```yaml
+noProxy:
+  - metrics.internal
+```
+
+Exclusions are printed in the startup banner, because they are the one setting
+that makes traffic invisible.
+
+`NODE_USE_ENV_PROXY` only exists in Node **≥ 22.21** or **≥ 24.5**. Below that, a
+Node-based target silently ignores the proxy; jean-claude warns you at startup.
+Claude Code ships as a Node CLI, so this applies to it too.
+
+Known gaps worth knowing rather than fighting: Java uses its own keystore
+(`keytool`), Rust tools built on `rustls` embed their roots and ignore every
+environment variable, and anything with pinned certificates needs
+`tlsPassthrough`.
+
+## Two terminals: `start` + `env`
+
+For a GUI app, a service that is already running, or simply to keep jean-claude's
+log out of your tool's output:
+
+```bash
+# terminal 1 - the proxy and its log live here
+jean-claude start -v
+
+# terminal 2 - your tool
+eval "$(jean-claude env)"
+claude
+```
+
+`start` records the live session (port, bundle path, pid) in
+`~/.config/jean-claude/session.json`, and `env` reads it — so the second shell
+needs no arguments and no copy-pasting. The file is removed when `start` exits,
+and `env` refuses a stale one rather than handing out a dead port.
+
+Note that `eval "$(jean-claude start --export)"` **cannot** work: `start` runs in
+the foreground, so the command substitution would never return. That is exactly
+why `env` exists.
+
+Use `jean-claude env -p 8899` to target a session started elsewhere, `--json` for
+machine-readable output. One session is recorded per home; with several
+concurrent proxies, pass `-p` (or a separate `--home`).
+
+## Commands
+
+```
+jean-claude run -- <command>   run a command with its HTTPS traffic intercepted
+jean-claude start              run the proxy alone, in its own terminal
+jean-claude env                print the environment for a running `start`
+jean-claude check              validate the config, print the rules as resolved
+jean-claude ca                 show the certificate store, and how to trust it
+jean-claude init               set up the jean-claude directory: config, stub, CA
+```
+
+Shared flags: `-c/--config`, `-p/--port`, `-r/--record`, `--home`,
+`-v/--verbose`, `-q/--quiet`, `--no-watch`.
+
+`init` takes `--home <dir>` and `--claude-code`.
+
+`run` exits with the child's exit code, so it drops into a CI pipeline unchanged.
+
+The config file is watched and reloaded on save. A config that fails to parse is
+reported and the previous rules stay in effect. Changing `tlsPassthrough` is the
+one setting that needs a restart.
+
+## Development
+
+```bash
+npm install
+npm test           # 130 tests, including an end-to-end MITM suite
+npm run typecheck
+npm run lint
+npm run build
+npm run jc -- --help    # run from source
+```
+
+The end-to-end suite runs a plain `node:https` server as the fake upstream,
+holding a leaf certificate minted by jean-claude's own CA, so it needs no network
+access. It asserts the things that actually matter: that a `respond` rule never
+reaches the server, that `patch` does, and that a status-only patch leaves the
+body intact.
+
+One gotcha worth knowing if you extend the suite: pointing jean-claude at a
+_second mockttp instance_ stalls for ~15s on the first upstream connection. It is
+an artefact of mockttp talking to mockttp, not of jean-claude — against a real
+HTTPS server the relay costs ~25ms. Hence the plain `node:https` upstream.
+
+Built on [mockttp](https://github.com/httptoolkit/mockttp), which does the heavy
+lifting: CONNECT tunnelling, per-host certificate minting, HTTP/2 and WebSockets.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).