@bman654/clodex 1.0.4 → 1.2.0

package/docs/background-agents.md

@@ -12,6 +12,7 @@ This page explains how to bridge **every** Claude Code process on your machine
   - **no live server: env untouched** — `claude` always launches normally, a stopped server never breaks anything.
 - Setting **`CLAUDE_CODE_PROCESS_WRAPPER`** to `clodex-claude` makes Claude Code invoke it as `clodex-claude <claude-binary-path> <args...>` for every process it spawns — agents view sessions and background agents are bridged automatically.
 - For your own terminal sessions, run **`clodex-claude`** instead of `claude` — same auto-discovery, no port or CA path to hardcode anywhere.
+- Set **`CLODEX_REQUIRE_SERVER=1`** in an isolated routed profile when bypassing Clodex must be impossible. `clodex-claude` then exits with an error if no advertised server passes its process and TCP checks. The default remains fail-open for ordinary installations.
 
 ## Setup steps
 
@@ -79,10 +80,14 @@ This page explains how to bridge **every** Claude Code process on your machine
 
 Port and CA discovery are automatic via `~/.clodex/server-runtime.json` — do not hardcode `HTTPS_PROXY`, ports, or certificate paths in your profile.
 
+For service-manager readiness checks, `clodex-claude --check` exits `0` when an
+advertised server passes the process and TCP checks, and exits `1` otherwise.
+It does not launch Claude.
+
 ## Troubleshooting
 
 - **Is my session bridged?** In a session started via `clodex-claude` (or spawned by Claude Code with the wrapper set), `/model` accepts your `clodex:` model names and aliases (run `clodex models --list` to see them). If those models are rejected and you haven't run `clodex patch`, that's expected for unpatched binaries — but a bridged session still routes them; an unbridged one errors at the API instead.
-- **Server not running:** `clodex-claude` silently launches plain `claude`. Check `cat ~/.clodex/server-runtime.json` — a missing file (or records whose `pid` is no longer alive) means no server is advertised; start `clodex server --proxy`. If a server is running but absent from the file, make sure it was not started with `--no-discovery` / `CLODEX_NO_DISCOVERY=1`.
+- **Server not running:** `clodex-claude` launches plain `claude` by default. With `CLODEX_REQUIRE_SERVER=1`, it exits instead. Check `cat ~/.clodex/server-runtime.json` — a missing file (or records whose `pid` is no longer alive) means no server is advertised; start `clodex server --proxy`. If a server is running but absent from the file, make sure it was not started with `--no-discovery` / `CLODEX_NO_DISCOVERY=1`.
 - **Wrapper variable empty or stale:** run `echo "$CLAUDE_CODE_PROCESS_WRAPPER"` in a **new login shell**. If it is empty, a `$(command -v ...)` in your profile ran before your Node version manager initialized (see the warning in step 3) — switch to a literal path. If it points at a path that no longer exists (a Node upgrade moved the global bin, an fnm/nvm shim directory expired, or it still names an old hand-written script), spawned processes fail to start or silently skip bridging. Verify with `[ -x "$CLAUDE_CODE_PROCESS_WRAPPER" ] && echo OK`.
 - **Agents fail to spawn / `env: node: No such file or directory`:** the wrapper's `#!/usr/bin/env node` shebang could not find Node, typically because Claude Code was launched from a GUI (Spotlight, Raycast, an IDE) with a minimal PATH. Use the launcher script from step 3, which resolves Node by absolute path, and test it with `env -i HOME="$HOME" PATH=/usr/bin:/bin "$CLAUDE_CODE_PROCESS_WRAPPER" --version`.
 - **Port conflicts:** the server default is 17645; `clodex server --proxy --port <n>` picks another. `clodex-claude` reads the actual port from the runtime file, so no other change is needed.

package/docs/credential-helpers.md

@@ -0,0 +1,75 @@
+# Credential helpers
+
+Clodex uses the operating system credential store by default. Headless Linux,
+containers, and WSL installations can instead delegate opaque credential
+storage to an external helper:
+
+```bash
+export CLODEX_CREDENTIAL_HELPER=/absolute/path/to/clodex-credential-helper
+clodex providers auth openai
+```
+
+The value must be an absolute path to an executable file. Clodex invokes the
+helper directly without a shell. Provider configuration records a versioned
+`helper:v1:<helper-id>:<account>` reference. The helper ID is a SHA-256 digest
+of the normalized executable path, so the path and username are not written to
+`providers.json`. A helper-backed credential never silently falls back to the
+OS keyring or an environment variable.
+
+Changing `CLODEX_CREDENTIAL_HELPER` to a different path does not redirect old
+references. Clodex refuses the operation before starting the new helper. Restore
+the prior path to read or delete the old credential, or reauthenticate to create
+a reference owned by the new helper.
+
+Clodex verifies the selected store with a disposable write, read, and delete
+before starting device authorization. It also reads back real credential
+writes.
+
+Credential storage is fail-closed. If the selected credential store fails its
+probe, Clodex stops before device authorization and includes the backend
+diagnostic in the error instead of continuing with tokens that cannot be
+durably stored. Set `CLODEX_CREDENTIAL_HELPER` to the absolute path of an
+external helper, then run the authorization command again.
+
+## Protocol
+
+The helper receives one of these invocations:
+
+```text
+helper get clodex <account>
+helper set clodex <account>
+helper delete clodex <account>
+```
+
+- `set` reads the complete opaque credential from standard input and produces
+  no output.
+- `get` writes the exact credential to standard output without adding a
+  newline.
+- `delete` removes the credential.
+- Exit code `0` means success.
+- Exit code `2` means not found for `get` or `delete`.
+- Any other exit code means the credential operation failed.
+
+The service and account arguments are identifiers, not secrets. Credential
+contents are never passed in arguments or environment variables. Helper
+standard error is not copied into Clodex diagnostics, and output and runtime
+are bounded.
+
+## Security responsibilities
+
+The helper owns storage and its security properties. A helper should:
+
+- encrypt credentials at rest using a system or user trust root;
+- serialize concurrent updates when its backend requires it;
+- avoid logging standard input or standard output;
+- make `set` replace the prior value atomically;
+- treat `delete` of a missing entry as success or exit code `2`;
+- return the stored bytes exactly from `get`.
+
+Users who need helper arguments can point `CLODEX_CREDENTIAL_HELPER` at a small
+executable wrapper. Clodex intentionally does not evaluate a shell command from
+this setting.
+
+Existing `keyring:` and `env:` provider references retain their original
+behavior. Enabling a helper affects newly saved credentials; reauthenticate a
+provider to move it to the helper-backed store.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bman654/clodex",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "publishConfig": {
     "access": "public"
   },