claude-autorouter 0.4.0 → 0.5.0

package/.env.example

@@ -1,7 +1,8 @@
 # Copy to .env and load with: node --env-file=.env bin/autorouter.mjs claude
 AUTOROUTER_AUTH_MODE=subscription
 AUTOROUTER_CLIENT_PROFILE=compatible
-# Jev remains the default evaluator. Ollama is experimental; see settings below.
+# Local Ollama is the default evaluator (experimental; see settings below).
+# Set jev to use TypeSafe's hosted evaluator, which needs TYPESAFE_API_KEY.
 AUTOROUTER_EVALUATOR=jev
 # The launcher enables the router status line for this session. Set 0 to keep your own.
 AUTOROUTER_STATUSLINE=1

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of conduct
+
+Be respectful and constructive in issues, pull requests, reviews and other project spaces. Welcome people with different backgrounds and experience levels, focus criticism on ideas and code, and respect requests to stop unwanted interaction.
+
+Harassment, discriminatory or demeaning remarks, sexualized conduct, threats, personal attacks, and publishing someone's private information without consent are not acceptable. The same expectations apply when representing the project outside its repository.
+
+Report concerns privately to maintainer Fabio Rapposelli at [fabio@rapposelli.org](mailto:fabio@rapposelli.org), with the subject `AutoRouter conduct report`. Include relevant links and enough context to investigate; avoid publishing the report or unrelated private information. Reports will be handled with discretion, sharing information only as needed to investigate and respond.
+
+The maintainer may request changes, remove content, issue warnings, or temporarily or permanently restrict participation according to the severity and pattern of behavior. Requests to review a decision can be sent to the same address. This policy is maintained on a best-effort basis and does not promise a response deadline.

package/CONTRIBUTING.md

@@ -1,6 +1,22 @@
 # Contributing to AutoRouter
 
-Use Node.js 22+ and macOS or Linux. Install pinned development tools, then run the local checks:
+Bug reports, documentation improvements, reproducible routing cases and focused fixes are welcome. Read the [support guide](SUPPORT.md) before opening an issue, and use the [private security reporting process](SECURITY.md) for vulnerabilities. Participation follows the [code of conduct](CODE_OF_CONDUCT.md).
+
+For a substantial behavior change, open an issue describing the problem and proposed scope before implementing it. Fabio Rapposelli ([@frapposelli](https://github.com/frapposelli)) maintains the project and reviews design and release decisions. Review is best effort; there is no guaranteed response time.
+
+Coding agents working in a source checkout should follow [AGENTS.md](https://github.com/frapposelli/claude-autorouter/blob/main/AGENTS.md). [CLAUDE.md](https://github.com/frapposelli/claude-autorouter/blob/main/CLAUDE.md) imports the same guidance for Claude Code.
+
+## Submit a change
+
+Fork the repository, clone your fork and create a branch. While the repository is private, this requires access and permission to fork; existing collaborators can use a branch in their authorized checkout.
+
+```sh
+git clone https://github.com/YOUR-USERNAME/claude-autorouter.git
+cd claude-autorouter
+git switch -c describe-your-change
+```
+
+Use Node.js 22+ and macOS or Linux (including WSL). Install pinned development tools, then run the local checks:
 
 ```sh
 npm ci --ignore-scripts --no-audit --no-fund
@@ -11,6 +27,10 @@ npm run test:package
 
 Tests use synthetic local services and credentials. They require loopback binding, but make no paid provider calls, downloads or user-config changes. The package check installs and exercises the exact distributable archive. Opt-in provider/model canaries are described in [development and validation](docs/development.md).
 
+Open a pull request against `main`. Describe the problem, resulting behavior and relevant validation, linking an issue when one exists. Keep the change focused, include meaningful regressions for behavior changes, and update affected help or documentation. Report any checks you could not run. Real provider calls and model downloads are not required for ordinary contributions; label their results separately if deliberately run.
+
+Use synthetic fixtures. Do not commit credentials, personal configuration, private prompts, transcripts or session logs. Metadata-only logs can still contain identifying information; inspect any material before sharing it. Contributions are accepted under the project's [Apache-2.0 license](LICENSE); submit only work you have the right to contribute. No CLA or sign-off workflow is required.
+
 ## Changing behavior
 
 Follow the [request lifecycle](docs/development.md#request-lifecycle-and-model-continuity). Keep authentication and permission decisions owned by Claude. Preserve provider bytes, signed history and unfamiliar extensions. Routing must check compatibility in every profile; new human tasks remain eligible to switch models. Active task state is separate from disposable classification caches, and only clean, successfully forwarded completion evidence can establish confirmed continuation state.

package/README.md

@@ -1,6 +1,8 @@
-# Claude AutoRouter
+# AutoRouter
 
-Use Haiku, Sonnet and Opus in one Claude Code session. AutoRouter evaluates each coding request, checks model compatibility and context capacity, and forwards it through a local gateway. [TypeSafe Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev) is the default evaluator; native Ollama `/v1/systemone` models provide an experimental local option. Claude owns authentication, tool permissions and safety review.
+An independent local model-routing gateway for Claude Code. AutoRouter is not affiliated with, endorsed by, or sponsored by Anthropic. The existing npm package and command remain `claude-autorouter`.
+
+Use Haiku, Sonnet and Opus in one Claude Code session. AutoRouter evaluates each coding request, checks model compatibility and context capacity, and forwards it through a local gateway. Native Ollama `/v1/systemone` models are the default, experimental local evaluator, so task excerpts stay on your machine; [TypeSafe Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev) is an optional hosted evaluator (`setup --evaluator jev`). Claude owns authentication, tool permissions and safety review.
 
 Requires Node.js 22+, macOS or Linux (including WSL), an installed `claude` command, and a Claude subscription login or Anthropic API key. The default evaluator also needs a [TypeSafe API key](https://console.typesafe.ai). The installed CLI has no runtime dependencies.
 
@@ -16,9 +18,11 @@ cd /path/to/project
 claude-autorouter claude
 ```
 
-Setup defaults to your Claude subscription and prompts privately for the Jev key. Run `claude auth login` if needed. Jev has separate credentials and billing; subscription mode needs no Anthropic API key. For API billing, use `setup --auth-mode api-key`.
+Setup defaults to your Claude subscription and the local Ollama evaluator (Ollama 0.35+ with the default model; add `--pull` to download it), so it asks for no evaluator key. To use hosted Jev instead, run `claude-autorouter setup --evaluator jev`, which prompts privately for its key. Run `claude auth login` if needed. Jev has separate credentials and billing; subscription mode needs no Anthropic API key. For API billing, use `setup --auth-mode api-key`.
+
+AutoRouter launches your installed, unmodified official Claude Code executable. Each user supplies their own login or API credentials. Subscription forwarding is a technical integration, not a claim of provider approval; review the [integration boundaries and current provider-policy notes](docs/subscription-integration.md) for your deployment.
 
-Configuration is saved privately at `~/.config/claude-autorouter/config.json`. Environment variables override it; project `.env` files are not loaded automatically. `setup --force` updates an existing configuration while preserving other settings. Use focused commands for later edits:
+Configuration is saved privately at `~/.config/claude-autorouter/config.json`. On macOS, new setups keep keys in the login Keychain; for an existing plaintext configuration, run `claude-autorouter config set AUTOROUTER_SECRET_STORE keychain` to move them. Environment variables override it; project `.env` files are not loaded automatically. `setup --force` updates an existing configuration while preserving other settings. Use focused commands for later edits:
 
 ```sh
 claude-autorouter config show
@@ -64,7 +68,7 @@ Savings are **API-equivalent estimates using the recorded Opus baseline and toke
 
 ## Local Ollama evaluator
 
-Start Ollama 0.35+ with a model supporting its native decision endpoint, then configure it explicitly:
+Ollama is the default evaluator. Start Ollama 0.35+ with a model supporting its native decision endpoint, then choose a model:
 
 ```sh
 claude-autorouter setup --evaluator ollama --ollama-model tev1:4b-q4_K_M --pull --force
@@ -72,7 +76,7 @@ claude-autorouter doctor --evaluate-local
 claude-autorouter claude
 ```
 
-`--pull` authorizes downloading the chosen model if missing. Setup keeps existing models and settings; ordinary launches download nothing. The default local model is `nimble:9b-q4_K_M`; `tev1:0.8b` is smaller and requires checking its accuracy on your tasks. Local classification needs no Jev key. Claude still answers through Anthropic. [Model choices, deadlines and historical measurements](docs/reference.md#ollama-evaluator).
+`--pull` authorizes downloading the chosen model if missing. Setup keeps existing models and settings; ordinary launches download nothing. The default local model is `nimble:9b-q4_K_M`; `tev1:0.8b` is smaller and requires checking its accuracy on your tasks. Local classification needs no Jev key; Jev remains available with `setup --evaluator jev`. Claude still answers through Anthropic. [Model choices, deadlines and historical measurements](docs/reference.md#ollama-evaluator).
 
 To allow a slower local model to finish without AutoRouter's runtime deadline:
 
@@ -94,6 +98,6 @@ claude-autorouter doctor
 
 Historical integration observations cover Claude Code 2.1.284–2.1.285. The versioned synthetic protocol fixtures test reviewed request/response contracts; they do not certify the current checkout against a live Claude version. Real-provider checks remain explicitly invoked. [Troubleshooting](docs/reference.md#troubleshooting) covers context use, blocked goals and logging. Run ordinary `claude` to bypass routing.
 
-The evaluator receives bounded task/history excerpts that may contain code and tool results: TypeSafe for Jev, or your loopback Ollama service. Anthropic receives the complete request. Model switching can reduce cache reuse. [Data flow and authentication](docs/reference.md#data-flow-and-authentication).
+The evaluator receives bounded task/history excerpts that may contain code and tool results: TypeSafe for Jev, or your loopback Ollama service. Recognizable credentials and personal identifiers are redacted from those excerpts first. Anthropic receives the complete request. Model switching can reduce cache reuse. [Data flow and authentication](docs/reference.md#data-flow-and-authentication).
 
-[Reference](docs/reference.md) · [Contributing](CONTRIBUTING.md) · [Development](docs/development.md) · [Releases](docs/releasing.md) · [Apache-2.0](LICENSE)
+[Reference](docs/reference.md) · [Integration and provider policy](docs/subscription-integration.md) · [Contributing](CONTRIBUTING.md) · [Development](docs/development.md) · [Releases](docs/releasing.md) · [Apache-2.0](LICENSE)

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security policy
+
+## Report privately
+
+Use GitHub's private [Report a vulnerability](https://github.com/frapposelli/claude-autorouter/security/advisories/new) form. Private vulnerability reporting is enabled for this repository. If the form is unavailable, email maintainer Fabio Rapposelli at [fabio@rapposelli.org](mailto:fabio@rapposelli.org) with the subject `AutoRouter security report`.
+
+Do not open a public issue or pull request with exploit details, credentials or sensitive request data. Include the affected AutoRouter and Claude Code versions, operating system, evaluator/client profile, expected security boundary, observed impact and a minimal synthetic reproduction where possible. Do not include real API keys, OAuth tokens, private source code, prompts or transcripts. The maintainer can coordinate any additional evidence privately.
+
+Reports are handled on a best-effort basis; there is no guaranteed response time or bounty program. We will coordinate investigation, remediation and disclosure with the reporter before publishing details.
+
+## Supported versions and scope
+
+Security fixes target the latest stable release. Older releases are not maintained as separate security branches; users may need to upgrade. Reports against `main` are also welcome.
+
+Relevant reports include credential exposure, unauthorized access to the local gateway or saved configuration, unintended disclosure through logs, and routing or request changes that weaken Claude's authentication or permission boundaries. Provider accounts, billing and vulnerabilities in Claude Code, TypeSafe or Ollama should also be reported to the responsible provider when applicable.
+
+## Handling diagnostic data
+
+AutoRouter's default evaluator is local Ollama, which keeps classification on loopback. The optional hosted Jev evaluator (`--evaluator jev`) receives bounded task/history excerpts, which may contain private code or tool results. Recognizable credentials and personal identifiers are redacted from those excerpts first; this pattern-based filter reduces, but does not eliminate, disclosure. Anthropic still receives the full inference request. See [data flow and authentication](docs/reference.md#data-flow-and-authentication).
+
+New macOS setups keep saved keys in the login Keychain. Existing and non-macOS configurations keep plaintext keys in the private configuration file until you run `claude-autorouter config set AUTOROUTER_SECRET_STORE keychain` (macOS only). See [credential storage](docs/reference.md#credential-storage).
+
+Session logging is optional. Enabling only a log directory uses the default `prompts` mode, which includes bounded human-task excerpts with recognizable credentials and personal identifiers redacted (pattern-based, so not exhaustive). Select `AUTOROUTER_SESSION_LOG_MODE=metadata` before enabling a directory to omit those excerpts. Inspect even metadata-only output before sharing it; identifiers, paths or environment details can still be sensitive. Saved logs have no automatic deletion policy. See [history and privacy](docs/reference.md#session-decision-logs).

package/SUPPORT.md

@@ -0,0 +1,18 @@
+# Support
+
+AutoRouter is an independent, community-maintained project. It does not provide official support for Anthropic, TypeSafe or Ollama, and has no response-time guarantee.
+
+For setup and usage, start with the [README](README.md) and [troubleshooting reference](docs/reference.md#troubleshooting). Run `claude-autorouter --version`, `claude --version` and `claude-autorouter doctor` to identify the installation and configuration involved. Ordinary `doctor` performs configuration and local service checks; it does not verify paid-provider access.
+
+Use [GitHub issues](https://github.com/frapposelli/claude-autorouter/issues) for reproducible bugs, feature proposals and questions not answered by the documentation. Repository access is required while the repository is private; if you cannot access it, contact [fabio@rapposelli.org](mailto:fabio@rapposelli.org). For vulnerabilities, follow [SECURITY.md](SECURITY.md) instead of opening an issue. Community conduct reports follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+## Make a report useful
+
+- Include AutoRouter, Claude Code, Node.js and operating-system versions; include the Ollama version and model tag for local evaluation.
+- Identify the authentication mode, evaluator and client profile without sharing credentials or full environment/configuration dumps.
+- Describe expected and actual behavior, and provide minimal steps using a synthetic prompt or fixture when possible. Distinguish the selected model from the provider-confirmed serving model.
+- Share only the relevant, inspected diagnostic excerpt. Remove secrets, private prompts, responses, source code, personal paths and organization identifiers. Screenshots can disclose this information too.
+
+Logging is disabled by default. When enabling optional session history for a reproduction, explicitly choose `AUTOROUTER_SESSION_LOG_MODE=metadata`; the default `prompts` mode includes task excerpts. Metadata-only output still needs review before sharing. Debug stderr can also contain Claude's own diagnostics. See [session logs](docs/reference.md#session-decision-logs) and [troubleshooting](docs/reference.md#troubleshooting).
+
+Account access, subscription/model eligibility, billing and provider outages belong with the responsible provider. AutoRouter reports can investigate how the gateway handles those failures, but cannot change a provider's account policies. Local-model accuracy and performance depend on the workload and hardware; include those conditions when reporting unexpected classifications.

package/docs/reference.md

@@ -1,5 +1,7 @@
 # Reference
 
+AutoRouter is an independent gateway for Claude Code. Its existing `claude-autorouter` package, command, configuration paths, and repository identity remain unchanged. See [integration boundaries and provider policy](subscription-integration.md) for authentication ownership and the distinction between technical operation and provider authorization.
+
 ## Commands
 
 | Command | Purpose |
@@ -29,7 +31,7 @@ The launcher binds an ephemeral port on `127.0.0.1`, creates a temporary local c
 
 ## Configuration
 
-First setup defaults to subscription mode unless `--auth-mode` or `AUTOROUTER_AUTH_MODE` selects another mode. Jev remains the default evaluator; `--evaluator ollama` selects local classification. An existing configuration updated with `--force` keeps its saved choices unless a command-line flag changes them; unrelated environment overrides remain temporary. Setup prompts for required secrets without echoing them and writes a private JSON file. Stored keys are plaintext; keep the file private and out of source control. Supply keys through the environment when interactive input is unavailable. Subscription mode with Ollama requires no API keys. API-key authentication always requires `ANTHROPIC_API_KEY`, regardless of evaluator.
+First setup defaults to subscription mode unless `--auth-mode` or `AUTOROUTER_AUTH_MODE` selects another mode. Local Ollama is the default evaluator (changed from Jev in 0.5.0; configurations created by `setup` always record their evaluator, so existing ones are unchanged, but an environment-only launch with no `AUTOROUTER_EVALUATOR` now selects Ollama); `--evaluator jev` selects TypeSafe's hosted evaluator. An existing configuration updated with `--force` keeps its saved choices unless a command-line flag changes them; unrelated environment overrides remain temporary. Setup prompts for required secrets without echoing them and writes a private JSON file. On macOS, new and `--replace` setups keep keys in the login Keychain by default (see [credential storage](#credential-storage)); elsewhere, and in existing configurations, stored keys are plaintext in that file, so keep it private and out of source control. Supply keys through the environment when interactive input is unavailable. Subscription mode with Ollama requires no API keys. API-key authentication always requires `ANTHROPIC_API_KEY`, regardless of evaluator.
 
 The config path is selected in this order:
 
@@ -43,6 +45,17 @@ The JSON file uses flat environment-style string keys, such as `AUTOROUTER_AUTH_
 node --env-file=.env bin/autorouter.mjs claude
 ```
 
+### Credential storage
+
+`AUTOROUTER_SECRET_STORE` selects where saved `ANTHROPIC_API_KEY`, `TYPESAFE_API_KEY` and `AUTOROUTER_TOKEN` values live. `file` stores them in the private JSON file; it is used on Linux and by configurations created before this option existed. `keychain`, available on macOS and chosen by default there for new setups, stores each one as a generic password in the login Keychain (service `claude-autorouter`, scoped to the configuration file path); the JSON file then contains only settings. Changing the setting moves saved keys:
+
+```sh
+claude-autorouter config set AUTOROUTER_SECRET_STORE keychain   # file → Keychain
+claude-autorouter config set AUTOROUTER_SECRET_STORE file       # Keychain → file
+```
+
+If the Keychain cannot be used during a default setup (locked or headless), setup says so and saves keys to the file instead; an explicit `--secret-store keychain` fails rather than falling back. An existing plaintext configuration is never moved implicitly: `setup --force` and `doctor` flag plaintext keys on macOS and print the command above. Keys are written to the Keychain before the file is rewritten, so an interrupted move leaves a copy in both places rather than neither. Items are removed only after the file is saved. Values pass to the system `security` tool on standard input, never as process arguments, and each write is read back to confirm it. Keychain values must be printable single-line ASCII. Environment variables still take precedence: when the Keychain is locked (for example over SSH), a key supplied in the environment is used instead, but moving keys between stores waits until every saved key can be read. `sessions` never reads the Keychain.
+
 For an environment-only subscription launch, set `AUTOROUTER_AUTH_MODE=subscription` and either supply `TYPESAFE_API_KEY` or select `AUTOROUTER_EVALUATOR=ollama` with a running local model. For API-key mode, also supply `ANTHROPIC_API_KEY`. The shell variables are read by the router; Jev's key is removed from the Claude child environment.
 
 | Variable | Default | Purpose |
@@ -51,7 +64,8 @@ For an environment-only subscription launch, set `AUTOROUTER_AUTH_MODE=subscript
 | `ANTHROPIC_API_KEY` | required in API-key mode | Upstream Anthropic credential |
 | `AUTOROUTER_CONFIG` | see path order above | Explicit user config path |
 | `AUTOROUTER_AUTH_MODE` | `api-key` without saved config; setup selects `subscription` | Authentication mode |
-| `AUTOROUTER_EVALUATOR` | `jev` | `jev` or local `ollama` classification |
+| `AUTOROUTER_EVALUATOR` | `ollama` | local `ollama` (default) or hosted `jev` classification |
+| `AUTOROUTER_SECRET_STORE` | `keychain` for new macOS setups; otherwise `file` | Saved-config setting: `keychain` keeps saved keys in the macOS login Keychain; the environment cannot redirect it |
 | `AUTOROUTER_CLIENT_PROFILE` | `compatible` | `native` retains client model/thinking settings; `auto` starts with Sonnet when no explicit model is set and excludes Haiku from task routing |
 | `AUTOROUTER_STATUSLINE` | enabled | `0` retains your existing status line |
 | `AUTOROUTER_DEBUG` | off | `1` enables launcher metadata logs on stderr |
@@ -93,7 +107,7 @@ Normal startup validates the selected evaluator; stale settings for the inactive
 
 ## Ollama evaluator
 
-The local configuration documented here requires AutoRouter 0.3.2 or newer and remains experimental. It uses Ollama's native `/v1/systemone` decision endpoint for every model, replacing the chat backend from 0.2.0. Jev remains the default remote evaluator, using TypeSafe's `/v1/systemone` endpoint and a TypeSafe API key. Selecting Ollama never silently switches back to Jev. Haiku, Sonnet, or Opus still completes the task through Anthropic.
+The local configuration documented here requires AutoRouter 0.3.2 or newer and remains experimental. It uses Ollama's native `/v1/systemone` decision endpoint for every model, replacing the chat backend from 0.2.0. Jev is the optional hosted evaluator, using TypeSafe's `/v1/systemone` endpoint and a TypeSafe API key. Selecting Ollama never silently switches back to Jev. Haiku, Sonnet, or Opus still completes the task through Anthropic.
 
 Version 0.3.2 excludes Claude's executor system instructions from local excerpts, uses model-specific runtime deadlines, and accepts `0` to disable that deadline. Setup, doctor, and startup show the effective model and deadline; setup accepts `--ollama-timeout-ms`. Jev is unchanged.
 
@@ -186,15 +200,17 @@ Claude Code → authenticated local gateway → Jev or local Ollama classificati
                                         → selected Claude model → streamed response
 ```
 
-AutoRouter uses Claude Code's [gateway integration](https://code.claude.com/docs/en/llm-gateway-protocol), so it sees inference requests and tool continuations. It does not rely on a user-prompt hook.
+AutoRouter launches the user's installed official Claude Code binary without patching it and uses Claude Code's [gateway integration](https://code.claude.com/docs/en/llm-gateway-protocol), so it sees inference requests and tool continuations. It does not rely on a user-prompt hook. Each user uses their own provider credentials; AutoRouter does not provide a Claude sign-in service or a shared provider account.
 
-The selected evaluator receives a bounded state containing the latest human request and excerpts of the original task and recent messages: up to 12,000 serialized characters sent to TypeSafe for Jev, or 3,000 UTF-8 bytes sent to the local Ollama service. Jev also receives system-text excerpts. The local path excludes Claude's top-level executor system instructions. These excerpts can include private source code and tool results. Images, document payloads, and signed thinking are omitted. Full tool schemas and full conversation history are not sent to either classifier. Anthropic receives the complete request, including its tools and attachments. Large or multimodal requests may also go to Anthropic's token-count endpoint before inference, including when classification is local.
+The selected evaluator receives a bounded state containing the latest human request and excerpts of the original task and recent messages: up to 12,000 serialized characters sent to TypeSafe for Jev, or 3,000 UTF-8 bytes sent to the local Ollama service. Jev also receives system-text excerpts. The local path excludes Claude's top-level executor system instructions. These excerpts can include private source code and tool results. Before excerpting, recognizable sensitive values are replaced (the same filter applies to opt-in session-log prompt excerpts, including when old logs are read back) with markers such as `[REDACTED:secret]`: private keys, common provider token formats (Anthropic, OpenAI-style `sk-`, AWS, GitHub, GitLab, Slack, Google, Stripe, npm), JWTs, authorization headers, URL credentials, values assigned to password/secret/token/key-like names, email addresses, and checksum-valid IBANs and payment card numbers. Setting names stay visible. Redaction is pattern-based: unrecognized formats can remain, code resembling an assignment can be over-redacted, and it does not make arbitrary private source code safe to share. Images, document payloads, and signed thinking are omitted. Full tool schemas and full conversation history are not sent to either classifier. Anthropic receives the complete request, including its tools and attachments. Large or multimodal requests may also go to Anthropic's token-count endpoint before inference, including when classification is local.
 
 In subscription mode, Claude Code owns login and OAuth refresh. AutoRouter forwards the current request's authorization and beta headers to Anthropic. It does not read keychain or saved login files, persist subscription tokens, or send them to Jev. A separate temporary `X-Autorouter-Token` authenticates the local connection and is stripped upstream. Subscription forwarding is restricted to `https://api.anthropic.com`. See [subscriptions and gateways](https://code.claude.com/docs/en/llm-gateway#subscriptions-and-gateways).
 
 In API-key mode, the upstream key stays in the proxy and Claude receives a temporary local credential. Requests are billed to the supplied API key. Subscription requests remain subject to the subscription's model access and usage limits. AutoRouter never falls back from subscription authentication to API billing.
 
-Routine logs contain route, model, timing, usage, and error-category metadata, not prompts, raw responses, or credentials. Status snapshots contain routing metadata and token counts in a private temporary directory and are deleted on normal launcher exit. Classification, turn, and token-count caches are held in memory. Claude Code and the external providers have their own storage and logging behavior.
+The proxy processes authenticated requests in memory, including their authorization headers. Preserving Claude's login flow does not by itself establish that every deployment is permitted. The [provider-policy note](subscription-integration.md#provider-guidance-and-unresolved-scope) records the current documentation and the unresolved scope of model-rewriting subscription forwarding. Jev requires its own TypeSafe credentials and billing, separate from Anthropic authentication.
+
+Routine diagnostic logs contain route, model, timing, usage, and error-category metadata, not prompts, raw responses, or credentials. Opt-in session history is separate and includes task excerpts in its default `prompts` mode. Status snapshots contain routing metadata and token counts in a private temporary directory and are deleted on normal launcher exit. Classification, turn, and token-count caches are held in memory. Claude Code and the external providers have their own storage and logging behavior.
 
 ## Routing policy
 

package/docs/releasing.md

@@ -18,7 +18,9 @@ Version `0.3.7` enables automatic Sonnet/Opus switching for compatible Auto-mode
 
 Version `0.4.0` completes the routing, configuration, history and performance improvement plan. Shared compatibility checks and durable task state preserve valid request features and confirmed tool/goal continuity across evaluator cache expiry, provider fallback and concurrent requests. New `config show/set/unset`, `sessions list/show` and `doctor --evaluate-local` commands support focused configuration edits, private metadata-only history and explicit local diagnostics. `setup --force` now merges saved settings; use `--replace` for deliberate replacement. Optional logging remains disabled by default; new schema-2 decision/outcome records separate selected and observed models, while the reader still accepts schema-1 files. Consumers parsing JSONL directly should account for both event kinds and the new schema. Identical concurrent evaluations are coalesced with independent cancellation, responses are bounded, and status persistence is asynchronous. Releases retain the tested archive and verify public npm availability and installation after submission. Actual 16 GiB/64 GiB Ollama results retain failed quality gates and comparison limits; Jev remains the default. See the [configuration/history reference](reference.md) and [hardware comparison](hardware-comparison.md).
 
-The GitHub repository is private. Publishing to npm makes the tarball's runtime source, README, configuration example, license, and shipped documentation public. Model weights, user configuration, credentials, transcripts, session logs, local artifacts, and test fixtures are excluded. Review the archive before the first publication and whenever the package allowlist changes.
+Version `0.5.0` makes local Ollama the default evaluator and TypeSafe Jev an explicit option (`setup --evaluator jev`), so evaluator excerpts stay on the machine unless the user opts in. **Breaking for environment-only launches** that relied on the implicit Jev default; configurations created by `setup` record their evaluator and are unchanged. Evaluator excerpts and opt-in session-log prompt excerpts are now redacted for recognizable credentials and personal identifiers (pattern-based, not exhaustive). On macOS, new `setup` runs keep saved keys in the login Keychain by default; existing plaintext configurations are not moved implicitly, and `doctor` prints the `config set AUTOROUTER_SECRET_STORE keychain` command to move them. See [credential storage](reference.md#credential-storage) and the [data flow](reference.md#data-flow-and-authentication).
+
+The GitHub repository became public on October 6, 2026, after preparation PR #1 merged. That launch created no release tag and published no new npm version. npm publication remains a separate release operation. Its tarball includes runtime source, README, configuration example, license, and shipped documentation; model weights, user configuration, credentials, transcripts, session logs, local artifacts, and test fixtures are excluded. Review each release archive, especially when the package allowlist changes. The public Git repository also exposes history, development scripts and tests; the npm archive allowlist does not govern that material.
 
 ## What runs automatically
 
@@ -35,7 +37,7 @@ Only the publishing job has `id-token: write`; there is no `NPM_TOKEN` or requir
 
 Verification polls uncached version metadata and the package document, checks the downloaded tarball against the tested archive, and installs the exact version from the public registry into a temporary prefix with an empty npm cache/config. It compares the installed file set and bytes with the canonical archive before invoking that executable’s `--version` and `--help` from an unrelated directory, with lifecycle scripts disabled and no evaluator credentials. Only a successful public install and matching artifact produce `verified`.
 
-The project has no package dependencies or lockfile, so CI runs its scripts directly without `npm ci`. Live Claude/Jev calls, Ollama downloads, and private repository probes are not CI checks.
+The installed CLI has no runtime dependencies. Contributor tooling uses pinned development dependencies and a committed `package-lock.json`; CI installs them with `npm ci --ignore-scripts --no-audit --no-fund` before checks. Live Claude/Jev calls, Ollama downloads, and private repository probes are not CI checks.
 
 ## 1. Publish the first version interactively
 
@@ -107,7 +109,7 @@ On npmjs.com, open the `claude-autorouter` package's **Settings → Trusted Publ
 
 Use the filename only, not `.github/workflows/publish.yml`. No GitHub environment or npm token secret needs to be created. The owner, repository, and workflow must match exactly. New trust configurations default to permitting staged publication; **enable direct `npm publish`** for this workflow. See [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/) and [staged publishing](https://docs.npmjs.com/staged-publishing/).
 
-The workflow explicitly disables provenance because npm provenance is unsupported for private source repositories, even when the npm package is public. OIDC authentication still works. If the repository becomes public, review the workflow and metadata before enabling provenance. See [npm provenance requirements](https://docs.npmjs.com/generating-provenance-statements/).
+The publishing workflow selects provenance from repository visibility. With the source now public, the workflow requests provenance on future publication; it would disable provenance for a private source repository. OIDC authentication works independently of provenance. The package preparation job's dry run always disables provenance because it has no OIDC publishing permission. Before the first public-source release, review repository metadata and npm trust settings, then verify the resulting provenance statement. The public launch itself created no attestation, and changing visibility does not add attestations to historical releases. See [npm provenance requirements](https://docs.npmjs.com/generating-provenance-statements/).
 
 After a successful trusted release, npm recommends the optional **Publishing access → Require two-factor authentication and disallow tokens** setting. It does not disable OIDC publishing. See [restricting token access](https://docs.npmjs.com/trusted-publishers/#recommended-restrict-token-access-when-using-trusted-publishers).
 

package/docs/subscription-integration.md

@@ -0,0 +1,27 @@
+# Claude Code integration and provider policy
+
+AutoRouter is an independent, user-operated local gateway for Claude Code. Anthropic does not sponsor or endorse this project. The project name is **AutoRouter**; references to Claude Code describe the software it runs. Existing npm, command, configuration, and repository identifiers remain `claude-autorouter` for compatibility. Those identifiers do not represent provider approval or trademark clearance. Anthropic's names and marks remain subject to its [trademark guidelines](https://www.anthropic.com/legal/trademark-guidelines).
+
+## What the integration does
+
+The launcher starts the official `claude` executable already installed on the user's machine. AutoRouter neither bundles nor patches that binary. It sets a local gateway address and temporary session settings, evaluates eligible inference requests, selects a compatible Claude model, and forwards the provider's response stream. Model-specific request adjustments and continuity checks are described in the [routing reference](reference.md#routing-policy). It does not change Claude's permission verdicts or grant access to unavailable models.
+
+The gateway listens on `127.0.0.1` and authenticates local requests. Standalone `serve` retains that local boundary; it is not a hosted account-sharing service. This project does not supply a shared Anthropic account, resell inference, or pay provider charges on a user's behalf.
+
+## Authentication and data ownership
+
+- **Subscription mode:** each user signs into their own account through Claude Code's official login flow. Claude owns OAuth refresh. AutoRouter receives the authorization header with each proxied request and forwards it to `https://api.anthropic.com`, together with the OAuth capability header. It does not extract login files or keychain entries, persist subscription tokens, or send those tokens to an evaluator. A separate temporary local token is removed before forwarding.
+- **API-key mode:** the user supplies their own Anthropic API key. The proxy forwards that key upstream and gives Claude a separate local credential. API usage is billed to the key owner's account; the router does not switch subscription traffic to API billing after an error.
+- **Evaluation:** the default Ollama evaluator receives bounded, redacted task/history excerpts through its loopback service without Claude or Jev credentials. The optional Jev evaluator uses a separate TypeSafe key and separate billing, and receives the same bounded, redacted excerpts, which can still include private code. Anthropic still receives the complete inference request. See [data flow and authentication](reference.md#data-flow-and-authentication).
+
+Claude Code, Anthropic, TypeSafe, and any downloaded local model have their own terms and data handling. Optional AutoRouter history persists locally when enabled; prompt mode can retain text entered by the user. See [history and privacy](reference.md#session-decision-logs).
+
+## Provider guidance and unresolved scope
+
+Documentation reviewed **October 6, 2026**:
+
+Anthropic's [Claude Code legal guidance](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) allows end users to sign into an unmodified Claude Code binary with their own credentials. It also restricts third-party credential collection or intermediation and certain subscription routing. Its [gateway documentation](https://code.claude.com/docs/en/llm-gateway#subscriptions-and-gateways) describes retaining a saved subscription login when configuring a gateway address without replacing authentication, including forwarding the OAuth capability header.
+
+These statements are relevant technical and policy context; they do not specifically approve AutoRouter's model-rewriting OAuth proxy. This project has not established that every use of subscription forwarding meets the applicable restrictions. Successful authentication or a passing test establishes technical behavior, not provider authorization. Enterprise access does not establish a blanket exception.
+
+Review your account agreement and organization requirements before deployment, and seek clarification from Anthropic about this integration when needed. Anthropic identifies [Commercial Terms](https://www.anthropic.com/legal/commercial-terms) for Team, Enterprise, and API use and [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) for consumer plans in its [license guidance](https://code.claude.com/docs/en/legal-and-compliance#license). API-key mode is available with separate billing and remains subject to its applicable terms. No policy-compliance guarantee is made by this project.

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "claude-autorouter",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "Apache-2.0",
   "type": "module",
-  "description": "A Claude Code model router with Jev and local Ollama System One evaluators",
+  "description": "AutoRouter: a local model-routing gateway for Claude Code with Jev and Ollama System One evaluators",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/frapposelli/claude-autorouter.git"
   },
+  "homepage": "https://github.com/frapposelli/claude-autorouter#readme",
+  "bugs": {
+    "url": "https://github.com/frapposelli/claude-autorouter/issues"
+  },
   "bin": {
     "claude-autorouter": "bin/autorouter.mjs"
   },
@@ -39,6 +43,10 @@
     ".env.example",
     "LICENSE",
     "CONTRIBUTING.md",
+    "SECURITY.md",
+    "SUPPORT.md",
+    "CODE_OF_CONDUCT.md",
+    "docs/subscription-integration.md",
     "docs/router-performance.md",
     "docs/router-performance.json",
     "docs/status-performance.md",

package/src/cli-help.mjs

@@ -1,23 +1,25 @@
 const commands = {
   setup: `Usage: claude-autorouter setup [options]
 
-Configure Jev (default) or an installed local Ollama evaluator.
+Configure the local Ollama evaluator (default) or TypeSafe Jev.
   --auth-mode subscription|api-key   Default: subscription
   --client-profile compatible|native|auto
-  --evaluator jev|ollama
+  --evaluator ollama|jev             Default: ollama (local); jev sends excerpts to TypeSafe
   --ollama-model TAG                 Select a /v1/systemone model
   --ollama-timeout-ms N              0 disables the routing deadline
   --pull                            Download the selected missing Ollama model
   --stop-hook-block-cap N            Optional Claude Stop-hook retry limit
   --session-log-dir DIR              Opt in to private logs with prompt excerpts
   --session-log-mode metadata|prompts Choose whether excerpts are included
-  --force                           Update an existing configuration
+  --secret-store file|keychain       default on macOS for new setups; file is plaintext
+  --force                          Update an existing configuration
   --replace                         Explicitly rebuild the saved configuration
 
 First setup reads environment settings and keys, or prompts for missing keys.
 --force retains saved defaults and applies explicit options; unrelated runtime
 overrides stay temporary. Explicit evaluator/auth selection accepts its supplied key.
-Example: claude-autorouter setup --evaluator ollama --ollama-model tev1:0.8b --pull`,
+Examples: claude-autorouter setup --pull
+          claude-autorouter setup --evaluator jev`,
   doctor: `Usage: claude-autorouter doctor [--evaluate-local] [--json]
 
 Check configuration, installed Claude, and local model availability.
@@ -35,6 +37,7 @@ Show effective settings and their source; secrets are always redacted.
 --check-all also validates settings for the inactive evaluator.
 Set/unset changes only the named saved setting. Environment values still win.
 Secret keys require --stdin or a hidden prompt, never a command-line value.
+Setting AUTOROUTER_SECRET_STORE to keychain or file moves saved keys (macOS).
 
 Example: claude-autorouter config set AUTOROUTER_OLLAMA_TIMEOUT_MS 0`,
   serve: `Usage: claude-autorouter serve
@@ -61,7 +64,7 @@ Claude owns permission checks and subscription authentication.
 };
 
 export function helpText(command = 'help') {
-  return commands[command] ?? `Claude AutoRouter — automatic Claude model routing
+  return commands[command] ?? `AutoRouter — automatic model routing for Claude Code
 
 Usage: claude-autorouter <command> [options]
 
@@ -78,8 +81,8 @@ Start: claude-autorouter setup
        claude-autorouter claude --permission-mode auto
 
 Run claude-autorouter help <command> for options and examples.
-Jev is the default; it receives bounded prompt excerpts. Ollama uses only the
-local /v1/systemone evaluator. Complete requests go to Anthropic.
+Local Ollama is the default evaluator and uses only the local /v1/systemone
+endpoint. Jev is optional; it receives bounded, redacted prompt excerpts. Complete requests go to Anthropic.
 Session logging is off unless AUTOROUTER_SESSION_LOG_DIR is configured.
 Environment variables override ~/.config/claude-autorouter/config.json.
 AUTOROUTER_CONFIG selects another file. Project .env files are not auto-loaded.

package/src/config-command.mjs

@@ -1,5 +1,5 @@
 import { readConfig, parseSessionLogDir, parseStopHookBlockCap } from './config.mjs';
-import { CONFIG_KEYS, SECRET_CONFIG_KEYS, loadUserConfig, saveUserConfig } from './user-config.mjs';
+import { CONFIG_KEYS, SECRET_CONFIG_KEYS, SECRET_STORES, keychainRemovals, loadUserConfig, saveUserConfig } from './user-config.mjs';
 import { modelCapabilities } from './model-catalog.mjs';
 import { askSecret } from './onboarding.mjs';
 
@@ -30,16 +30,20 @@ function effectiveValues(config, env) {
 /** Redacted effective configuration, independent of Claude launch arguments. */
 export function configReport(loaded, env, { checkAll = false } = {}) {
   const config = readConfig(loaded.env);
-  const values = effectiveValues(config, loaded.env);
+  const values = { ...effectiveValues(config, loaded.env), AUTOROUTER_SECRET_STORE: loaded.secretStore ?? 'file' };
   const settings = {};
   for (const key of CONFIG_KEYS) {
-    const source = env[key] !== undefined ? 'environment' : Object.hasOwn(loaded.values, key) ? 'file' : 'default';
+    const saved = loaded.keychainSecrets?.includes(key) ? 'keychain' : 'file';
+    // The saved store setting governs saved secrets; the environment cannot redirect it.
+    const source = env[key] !== undefined && key !== 'AUTOROUTER_SECRET_STORE' ? 'environment'
+      : Object.hasOwn(loaded.values, key) ? saved : 'default';
     const provider = providerFor(key);
     const active = (!provider || provider === config.evaluator)
       && (key !== 'ANTHROPIC_API_KEY' || config.authMode === 'api-key');
     const secret = secretKey(key);
     settings[key] = { source, active,
       ...(source === 'environment' && Object.hasOwn(loaded.values, key) ? { overrides_file: true } : {}),
+      ...(source === 'environment' && loaded.unavailableSecrets?.includes(key) ? { keychain_unavailable: true } : {}),
       ...(secret ? { secret: true, present: typeof loaded.env[key] === 'string' && Boolean(loaded.env[key].trim()) }
         : { value: active ? values[key] ?? null : null }),
     };
@@ -84,19 +88,21 @@ function normalizedValue(key, value) {
   }
   if (key === 'AUTOROUTER_SESSION_LOG_DIR') return parseSessionLogDir(value) ?? '';
   if (key === 'CLAUDE_CODE_STOP_HOOK_BLOCK_CAP') return String(parseStopHookBlockCap(value));
+  if (key === 'AUTOROUTER_SECRET_STORE' && !SECRET_STORES.includes(value)) throw new Error('AUTOROUTER_SECRET_STORE must be file or keychain.');
   if (/[\r\n\0\u001b]/.test(value)) throw new Error(`${key} must be a single-line setting.`);
   return value;
 }
 
 export async function configCommand(args, {
-  env = process.env, write = console.log, input = process.stdin, promptSecret = askSecret,
+  env = process.env, write = console.log, input = process.stdin, promptSecret = askSecret, keychain,
 } = {}) {
+  const store = keychain ? { keychain } : {};
   const [operation, ...rest] = args;
   if (operation === 'show') {
     if (rest.some(arg => !['--json', '--check-all'].includes(arg))) throw new Error('Usage: claude-autorouter config show [--json] [--check-all]');
     let loaded, report;
     try {
-      loaded = loadUserConfig(env, { allowMissing: true });
+      loaded = loadUserConfig(env, { allowMissing: true, ...store });
       report = configReport(loaded, env, { checkAll: rest.includes('--check-all') });
     }
     catch (error) {
@@ -124,7 +130,7 @@ export async function configCommand(args, {
     throw new Error('Secret values are not accepted as command arguments. Use --stdin or the hidden prompt.');
   }
   if (operation === 'set' && !secretKey(key) && (value === undefined || value === '--stdin')) throw new Error('Nonsecret settings require a value argument.');
-  const loaded = loadUserConfig(env, { allowMissing: true });
+  const loaded = loadUserConfig(env, { allowMissing: true, ...store });
   const next = { ...loaded.values };
   if (operation === 'unset') delete next[key];
   else next[key] = normalizedValue(key, secretKey(key)
@@ -134,8 +140,19 @@ export async function configCommand(args, {
   // mask it. An explicitly edited inactive provider is checked too.
   const provider = operation === 'set' ? providerFor(key) : undefined;
   readConfig({ ...next, ...(provider ? { AUTOROUTER_EVALUATOR: provider } : {}) });
-  saveUserConfig(next, { env, overwrite: loaded.exists, expectedRevision: loaded.revision });
-  write(`${operation === 'unset' ? 'Removed saved' : 'Saved'} ${key}. Other saved settings are unchanged.`);
+  const nextStore = next.AUTOROUTER_SECRET_STORE ?? 'file';
+  // Changing the store moves saved secrets; unsetting a secret deletes its item.
+  const removeSecrets = key === 'AUTOROUTER_SECRET_STORE' ? keychainRemovals(loaded, nextStore)
+    : operation === 'unset' && secretKey(key) && loaded.secretStore === 'keychain' ? [key] : [];
+  saveUserConfig(next, { env, overwrite: loaded.exists, expectedRevision: loaded.revision, removeSecrets, ...store });
+  if (key === 'AUTOROUTER_SECRET_STORE') {
+    const moved = SECRET_CONFIG_KEYS.filter(name => Object.hasOwn(next, name)).length;
+    const where = nextStore === 'keychain' ? 'macOS Keychain' : 'configuration file';
+    write(nextStore === loaded.secretStore || !moved ? `Saved ${key}. Saved secrets are stored in the ${where}.`
+      : `Saved ${key}. Moved ${moved} saved secret${moved === 1 ? '' : 's'} to the ${where}.`);
+    return true;
+  }
+  write(`${operation === 'unset' ? 'Removed saved' : 'Saved'} ${key}${secretKey(key) && nextStore === 'keychain' ? ' in the macOS Keychain' : ''}. Other saved settings are unchanged.`);
   if (env[key] !== undefined) write(`The current environment still overrides ${key}; unset that environment variable to use the saved/default value.`);
   return true;
 }

package/src/config.mjs

@@ -63,7 +63,7 @@ export function readConfig(env = process.env, { validateAll = false } = {}) {
   for (const key of ['AUTOROUTER_STATUSLINE', 'AUTOROUTER_DEBUG']) {
     if (env[key] !== undefined && !['0', '1'].includes(env[key])) throw new Error(`${key} must be 0 or 1`);
   }
-  const evaluator = env.AUTOROUTER_EVALUATOR ?? 'jev';
+  const evaluator = env.AUTOROUTER_EVALUATOR ?? 'ollama';
   if (evaluator !== 'jev' && evaluator !== 'ollama') throw new Error('AUTOROUTER_EVALUATOR must be jev or ollama');
   // A stale inactive backend must not stop the selected evaluator. Config
   // inspection can request validation of both providers explicitly.

package/src/keychain.mjs

@@ -0,0 +1,58 @@
+import { spawnSync } from 'node:child_process';
+
+// macOS Keychain access through the system `security` tool. Secret values are
+// passed on stdin to its interactive mode, never as process arguments, and are
+// read back from stdout. Tool output can describe items, so failures report
+// only a generic category.
+const SECURITY = '/usr/bin/security';
+const SERVICE = 'claude-autorouter';
+const NOT_FOUND = 44;
+const PRINTABLE = /^[\x20-\x7e]+$/;
+
+function keychainError(message) {
+  const error = new Error(message);
+  error.code = 'AUTOROUTER_CONFIG_ERROR';
+  return error;
+}
+
+// Quote for the `security -i` command parser, which accepts backslash escapes
+// inside double quotes. Values are validated as printable single-line ASCII.
+const quote = value => `"${value.replace(/[\\"]/g, '\\$&')}"`;
+
+export function createKeychain({ run = spawnSync, platform = process.platform } = {}) {
+  const available = platform === 'darwin';
+  const call = (args, input) => {
+    if (!available) throw keychainError('The macOS Keychain secret store is available only on macOS.');
+    const result = run(SECURITY, args, {
+      input, encoding: 'utf8', timeout: 15000, maxBuffer: 64 * 1024, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.error) throw keychainError('Could not run the macOS Keychain tool.');
+    return result;
+  };
+  const read = account => {
+    const result = call(['find-generic-password', '-s', SERVICE, '-a', account, '-w']);
+    if (result.status === NOT_FOUND) return undefined;
+    if (result.status !== 0) {
+      throw keychainError('Could not read an AutoRouter secret from the macOS Keychain. Unlock the login keychain, or set the key in the environment.');
+    }
+    return String(result.stdout).replace(/\n$/, '');
+  };
+  return {
+    available,
+    read,
+    write(account, value, label) {
+      if (typeof value !== 'string' || !PRINTABLE.test(value)) {
+        throw keychainError('Keychain secrets must be printable single-line ASCII.');
+      }
+      call(['-i'], `add-generic-password -U -s ${quote(SERVICE)} -a ${quote(account)} -l ${quote(label)} -w ${quote(value)}\n`);
+      // Interactive mode exits successfully even when a command fails.
+      if (read(account) !== value) throw keychainError('Could not save an AutoRouter secret to the macOS Keychain.');
+    },
+    remove(account) {
+      const result = call(['delete-generic-password', '-s', SERVICE, '-a', account]);
+      if (result.status !== 0 && result.status !== NOT_FOUND) {
+        throw keychainError('Could not remove an AutoRouter secret from the macOS Keychain.');
+      }
+    },
+  };
+}

package/src/onboarding.mjs

@@ -4,7 +4,7 @@ import { Writable } from 'node:stream';
 import { promisify } from 'node:util';
 import { CLIENT_PROFILES, readConfig, requireKeys, parseStopHookBlockCap, parseSessionLogDir } from './config.mjs';
 import { buildClaudeEnv, conflictingProviders, LOCAL_AUTH_HEADER } from './auth.mjs';
-import { CONFIG_KEYS, SECRET_CONFIG_KEYS, loadUserConfig, saveUserConfig } from './user-config.mjs';
+import { CONFIG_KEYS, SECRET_CONFIG_KEYS, SECRET_STORES, keychainRemovals, loadUserConfig, saveUserConfig } from './user-config.mjs';
 import { DEFAULT_OLLAMA_MODEL, validateOllamaModel } from './ollama-models.mjs';
 import { inspectOllama, setupOllama } from './ollama-setup.mjs';
 
@@ -37,10 +37,12 @@ export async function askSecret(label, { input = process.stdin, output = process
 }
 
 export async function setup(args, {
-  env = process.env, write = console.log, prompt = askSecret, fetchImpl = fetch, signal,
+  env = process.env, write = console.log, prompt = askSecret, fetchImpl = fetch, signal, keychain,
+  platform = process.platform,
 } = {}) {
   if (signal?.aborted) throw new Error('Setup cancelled');
-  const loaded = loadUserConfig(env, { allowMissing: true });
+  const store = keychain ? { keychain } : {};
+  const loaded = loadUserConfig(env, { allowMissing: true, ...store });
   const replace = args.includes('--replace');
   const mergeExisting = loaded.exists && !replace;
   // Updating one preference must not turn unrelated runtime overrides into
@@ -50,12 +52,13 @@ export async function setup(args, {
   let explicitEvaluator = false, explicitAuthMode = false;
   let authMode = effectiveEnv.AUTOROUTER_AUTH_MODE ?? 'subscription';
   let clientProfile = effectiveEnv.AUTOROUTER_CLIENT_PROFILE ?? 'compatible';
-  let evaluator = effectiveEnv.AUTOROUTER_EVALUATOR ?? 'jev';
+  let evaluator = effectiveEnv.AUTOROUTER_EVALUATOR ?? 'ollama';
   let model;
   let ollamaTimeoutMs;
   let stopHookBlockCap = effectiveEnv.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP;
   let sessionLogDir = effectiveEnv.AUTOROUTER_SESSION_LOG_DIR;
   let sessionLogMode = effectiveEnv.AUTOROUTER_SESSION_LOG_MODE;
+  let secretStore;
   let pull = false;
   let overwrite = replace;
   for (let i = 0; i < args.length; i++) {
@@ -82,10 +85,14 @@ export async function setup(args, {
       sessionLogMode = args[++i];
       if (!['metadata', 'prompts'].includes(sessionLogMode)) throw new Error('--session-log-mode must be metadata or prompts');
     }
+    else if (args[i] === '--secret-store') {
+      secretStore = args[++i];
+      if (!SECRET_STORES.includes(secretStore)) throw new Error('--secret-store must be file or keychain');
+    }
     else if (args[i] === '--pull') pull = true;
     else if (args[i] === '--force') overwrite = true;
     else if (args[i] === '--replace') continue;
-    else throw new Error('Usage: claude-autorouter setup [--auth-mode subscription|api-key] [--client-profile compatible|native|auto] [--evaluator jev|ollama] [--ollama-model TAG] [--ollama-timeout-ms N] [--stop-hook-block-cap N] [--session-log-dir DIR] [--session-log-mode metadata|prompts] [--pull] [--force|--replace]');
+    else throw new Error('Usage: claude-autorouter setup [--auth-mode subscription|api-key] [--client-profile compatible|native|auto] [--evaluator jev|ollama] [--ollama-model TAG] [--ollama-timeout-ms N] [--stop-hook-block-cap N] [--session-log-dir DIR] [--session-log-mode metadata|prompts] [--secret-store file|keychain] [--pull] [--force|--replace]');
   }
   if (!['subscription', 'api-key'].includes(authMode)) throw new Error('--auth-mode must be subscription or api-key');
   if (!CLIENT_PROFILES.includes(clientProfile)) throw new Error('--client-profile must be compatible, native or auto');
@@ -108,6 +115,11 @@ export async function setup(args, {
   if (stopHookBlockCap !== undefined) values.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP = String(stopHookBlockCap);
   if (sessionLogDir !== undefined) values.AUTOROUTER_SESSION_LOG_DIR = sessionLogDir;
   if (sessionLogMode !== undefined) values.AUTOROUTER_SESSION_LOG_MODE = sessionLogMode;
+  if (secretStore !== undefined) values.AUTOROUTER_SECRET_STORE = secretStore;
+  // New and rebuilt configurations keep keys in the macOS Keychain. An existing
+  // configuration keeps its store until the user moves it deliberately.
+  const defaultedStore = values.AUTOROUTER_SECRET_STORE === undefined && platform === 'darwin' && (!loaded.exists || replace);
+  if (defaultedStore) values.AUTOROUTER_SECRET_STORE = 'keychain';
   if (evaluator === 'ollama') {
     values.AUTOROUTER_OLLAMA_MODEL = validateOllamaModel(model
       ?? (explicitEvaluator ? env.AUTOROUTER_OLLAMA_MODEL : undefined) ?? effectiveEnv.AUTOROUTER_OLLAMA_MODEL ?? DEFAULT_OLLAMA_MODEL);
@@ -119,6 +131,9 @@ export async function setup(args, {
   const keys = [...(evaluator === 'jev' ? ['TYPESAFE_API_KEY'] : []), ...(authMode === 'api-key' ? ['ANTHROPIC_API_KEY'] : [])];
   // Reject invalid settings before inviting secret input or making local calls.
   readConfig(values);
+  if (values.AUTOROUTER_SECRET_STORE === 'keychain' && platform !== 'darwin') {
+    throw new Error('--secret-store keychain is available only on macOS');
+  }
   for (const key of keys) {
     if (signal?.aborted) throw new Error('Setup cancelled');
     const explicitlySelected = !mergeExisting || (key === 'TYPESAFE_API_KEY' ? explicitEvaluator : explicitAuthMode);
@@ -140,17 +155,43 @@ export async function setup(args, {
     const cancel = () => controller.abort();
     if (!signal) for (const name of ['SIGINT', 'SIGTERM']) process.once(name, cancel);
     try { await setupOllama(config, { pull, warm: true, write, fetchImpl, signal: signal ?? controller.signal }); }
+    catch (error) {
+      // Local evaluation is the default, not a choice the user made, so a
+      // missing or stopped Ollama should say how to pick another evaluator.
+      if (!explicitEvaluator && !mergeExisting && !signal?.aborted) {
+        error.message = `${error.message} Local Ollama is the default evaluator; add --pull to download its model, or use TypeSafe Jev instead: claude-autorouter setup --evaluator jev`;
+      }
+      throw error;
+    }
     finally { if (!signal) for (const name of ['SIGINT', 'SIGTERM']) process.removeListener(name, cancel); }
   }
   if (signal?.aborted) throw new Error('Setup cancelled');
-  saveUserConfig(values, { env, overwrite, expectedRevision: loaded.revision });
+  let savedStore = values.AUTOROUTER_SECRET_STORE ?? 'file';
+  try {
+    saveUserConfig(values, { env, overwrite, expectedRevision: loaded.revision,
+      removeSecrets: keychainRemovals(loaded, savedStore, { replace, values }), ...store });
+  } catch (error) {
+    // The default must not make setup impossible where the Keychain cannot be
+    // used (locked, headless). An explicit request still fails.
+    if (!defaultedStore || !keys.length || error?.code !== 'AUTOROUTER_CONFIG_ERROR' || !/Keychain/.test(error.message)) throw error;
+    write('The macOS Keychain is unavailable; saving keys in the private configuration file instead. Move them later with: claude-autorouter config set AUTOROUTER_SECRET_STORE keychain');
+    delete values.AUTOROUTER_SECRET_STORE;
+    savedStore = 'file';
+    saveUserConfig(values, { env, overwrite, expectedRevision: loaded.revision,
+      removeSecrets: keychainRemovals(loaded, savedStore, { replace, values }), ...store });
+  }
   write(`Saved ${authMode} configuration to ${path}`);
-  write(`${keys.length ? 'Keys and settings are' : 'Settings are'} stored locally in this file with owner-only permissions. Environment variables take precedence.`);
+  if (keys.length && savedStore === 'keychain') {
+    write('Keys are stored in the macOS Keychain; settings are stored in this file with owner-only permissions. Environment variables take precedence.');
+  } else {
+    write(`${keys.length ? 'Keys and settings are' : 'Settings are'} stored locally in this file with owner-only permissions. Environment variables take precedence.`);
+    if (keys.length && platform === 'darwin' && savedStore === 'file' && !defaultedStore) write('Keys are plaintext in this file. Move them into the macOS Keychain: claude-autorouter config set AUTOROUTER_SECRET_STORE keychain');
+  }
   write('Next: claude-autorouter doctor, then claude-autorouter claude from your project.');
 }
 
 export async function doctor({ env = process.env, write = console.log, run = execute, fetchImpl = fetch, signal,
-  evaluateLocal = false, json = false, diagnosticRunner } = {}) {
+  evaluateLocal = false, json = false, diagnosticRunner, keychain, platform = process.platform } = {}) {
   if (evaluateLocal) {
     try {
       const config = readConfig(loadUserConfig(env).env);
@@ -180,9 +221,13 @@ export async function doctor({ env = process.env, write = console.log, run = exe
   let config;
   let effectiveEnv = env;
   try {
-    const loaded = loadUserConfig(env);
+    const loaded = loadUserConfig(env, keychain ? { keychain } : {});
     effectiveEnv = loaded.env;
     write(`Config: ${loaded.path}${loaded.exists ? '' : ' (absent; using environment)'}`);
+    if (loaded.secretStore === 'keychain') write(`Saved secrets: macOS Keychain (${loaded.keychainSecrets.length} found).`);
+    else if (platform === 'darwin' && SECRET_CONFIG_KEYS.some(key => Object.hasOwn(loaded.values, key))) {
+      write('WARN  Saved keys are plaintext in the configuration file. Move them into the macOS Keychain: claude-autorouter config set AUTOROUTER_SECRET_STORE keychain');
+    }
     config = readConfig(effectiveEnv);
     requireKeys(config);
     report(true, `Configuration and required keys present (${config.authMode})`);

package/src/prompt-state.mjs

@@ -1,3 +1,5 @@
+import { redactSensitive } from './redaction.mjs';
+
 // Claude Code prepends these as separate text blocks. Ignore only complete
 // wrapper blocks; a user's text that mentions a tag or mixes it with a task
 // must remain part of the classifier's input.
@@ -51,6 +53,16 @@ function excerpt(text, length) {
 
 const textCost = text => JSON.stringify(text).length - 2;
 
+// Redact before excerpting so a value cannot be split into an unrecognizable
+// fragment. Very long text keeps only end windows wider than any retained
+// excerpt; the margin also keeps a value cut at a window edge out of the result.
+const REDACTION_MARGIN = 4096;
+function classifierText(text, limit) {
+  const span = limit + REDACTION_MARGIN;
+  if (text.length > 2 * span) text = `${text.slice(0, span)}\n[... omitted ...]\n${text.slice(-span)}`;
+  return redactSensitive(text);
+}
+
 // Budget serialized characters, including JSON escaping, rather than just
 // raw text length. The two ends keep both an initial instruction and a final
 // question visible when one long text block must be shortened.
@@ -145,6 +157,9 @@ export function promptExcerpt(body, maxChars = 500) {
     const blocks = typeof content === 'string' ? [{ type: 'text', text: content }]
       : Array.isArray(content) ? content : [];
     const characters = [];
+    // Collect past the retained length: redaction must see a value that
+    // straddles the final boundary, and may shorten the text before the cut.
+    const window = maxChars + REDACTION_MARGIN;
     let nonText = false;
     for (const block of blocks) {
       if (block?.type !== 'text' || typeof block.text !== 'string') {
@@ -157,12 +172,12 @@ export function promptExcerpt(body, maxChars = 500) {
       if (!/\S/.test(value) || isReminderBlock(value)) continue;
       if (characters.length) characters.push('\n');
       for (const character of value) {
-        if (characters.length >= maxChars) break;
+        if (characters.length >= window) break;
         characters.push(character);
       }
-      if (characters.length >= maxChars) break;
+      if (characters.length >= window) break;
     }
-    if (characters.length) return characters.join('').toWellFormed();
+    if (characters.length) return [...redactSensitive(characters.join('').toWellFormed())].slice(0, maxChars).join('').toWellFormed();
     // An image/document-only human turn is a new task with no safe excerpt;
     // do not incorrectly label it with the preceding human task's text.
     if (nonText) return '';
@@ -196,9 +211,9 @@ export function buildState(body, limit = 12000) {
   const remaining = () => Math.max(0, limit - JSON.stringify(state).length);
   // Reserve more than half of the budget for the actual latest human task
   // before considering reminders, original instructions, or tool results.
-  state.current_task = fitText(currentTask, Math.min(remaining(), Math.floor(limit * 0.55)));
-  state.original_task = fitText(firstTask, Math.min(2000, Math.floor(remaining() * 0.3)));
-  state.system = fitText(contentText(body.system, true), Math.min(1000, Math.floor(remaining() * 0.3)));
+  state.current_task = fitText(classifierText(currentTask, limit), Math.min(remaining(), Math.floor(limit * 0.55)));
+  state.original_task = fitText(classifierText(firstTask, limit), Math.min(2000, Math.floor(remaining() * 0.3)));
+  state.system = fitText(classifierText(contentText(body.system, true), limit), Math.min(1000, Math.floor(remaining() * 0.3)));
 
   for (let index = messages.length - 1; index >= 0 && state.recent_messages.length < 8; index--) {
     // current_task already contains this message; leave room for actual
@@ -210,7 +225,7 @@ export function buildState(body, limit = 12000) {
     const overhead = JSON.stringify(entry).length + (state.recent_messages.length ? 1 : 0);
     const budget = Math.min(3000, remaining() - overhead);
     if (budget < 1) break;
-    entry.content = fitText(text, budget);
+    entry.content = fitText(classifierText(text, limit), budget);
     state.recent_messages.unshift(entry);
   }
   return state;

package/src/redaction.mjs

@@ -0,0 +1,97 @@
+// @ts-check
+// Pattern-based redaction for evaluator excerpts. Classification needs the
+// shape of a task, not credentials or personal identifiers, so recognizable
+// values are replaced before any excerpt leaves the inference path. This is a
+// best-effort filter: unrecognized formats can remain, and code that merely
+// resembles an assignment can be over-redacted. Every quantifier is bounded or
+// excludes its delimiter, so scanning stays linear in the input length.
+
+const marker = kind => `[REDACTED:${kind}]`;
+
+function ibanValid(value) {
+  const compact = value.replace(/ /g, '');
+  if (compact.length < 15 || compact.length > 34) return false;
+  const rearranged = compact.slice(4) + compact.slice(0, 4);
+  let remainder = 0;
+  for (const character of rearranged) {
+    const digits = /[0-9]/.test(character) ? character : String(character.charCodeAt(0) - 55);
+    for (const digit of digits) remainder = (remainder * 10 + Number(digit)) % 97;
+  }
+  return remainder === 1;
+}
+
+function luhnValid(value) {
+  const digits = value.replace(/[ -]/g, '');
+  if (digits.length < 13 || digits.length > 19) return false;
+  let sum = 0;
+  for (let i = 0; i < digits.length; i++) {
+    let digit = Number(digits[digits.length - 1 - i]);
+    if (i % 2 === 1) { digit *= 2; if (digit > 9) digit -= 9; }
+    sum += digit;
+  }
+  return sum % 10 === 0;
+}
+
+const base64 = code => (code >= 48 && code <= 57) || (code >= 65 && code <= 90) || (code >= 97 && code <= 122)
+  || code === 43 || code === 47 || code === 61;
+
+// Key material whose BEGIN line was cut off before the excerpt: walk back from
+// each END line over whole base64 lines. A regex line repetition would
+// backtrack quadratically on a long base64 run that is not followed by END.
+function redactKeyTails(text) {
+  const end = /-----END [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----/g;
+  let output = '', copied = 0;
+  for (let match; (match = end.exec(text));) {
+    let start = match.index;
+    while (start > copied && text[start - 1] === '\n') {
+      let lineEnd = start - 1;
+      if (lineEnd > copied && text[lineEnd - 1] === '\r') lineEnd--;
+      let lineStart = lineEnd;
+      while (lineStart > copied && base64(text.charCodeAt(lineStart - 1))) lineStart--;
+      if (lineEnd - lineStart < 16 || (lineStart > copied && text[lineStart - 1] !== '\n')) break;
+      start = lineStart;
+    }
+    if (start === match.index) continue;
+    output += text.slice(copied, start) + marker('private_key');
+    copied = end.lastIndex;
+  }
+  return copied ? output + text.slice(copied) : text;
+}
+
+/** @type {ReadonlyArray<readonly [RegExp, string | ((...match: string[]) => string)] | ((text: string) => string)>} */
+const RULES = Object.freeze([
+  // A block cut off by excerpting is still redacted through the end of text.
+  [/-----BEGIN [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----|$)/g, marker('private_key')],
+  redactKeyTails,
+  [/\b([a-z][a-z0-9+.-]{1,20}:\/\/)[^\s:@/]{1,256}:[^\s@/]{1,256}@/gi, (_, scheme) => `${scheme}${marker('credentials')}@`],
+  [/\bsk-[A-Za-z0-9_-]{20,}/g, marker('secret')],
+  [/\b[rs]k_(?:live|test)_[A-Za-z0-9]{16,}/g, marker('secret')],
+  [/\b(?:AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}\b/g, marker('secret')],
+  [/\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,})/g, marker('secret')],
+  [/\bglpat-[A-Za-z0-9_-]{20,}/g, marker('secret')],
+  [/\bxox[abposr]-[A-Za-z0-9-]{10,}/g, marker('secret')],
+  [/https:\/\/hooks\.slack\.com\/services\/[A-Za-z0-9/]{8,}/g, marker('secret')],
+  [/\bAIza[0-9A-Za-z_-]{35}/g, marker('secret')],
+  [/\bnpm_[A-Za-z0-9]{36}/g, marker('secret')],
+  [/\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, marker('secret')],
+  [/\b((?:proxy-)?authorization["']?[ \t]{0,8}[:=][ \t]{0,8}["']?)(?:(Bearer|Basic|Token|Digest)[ \t]+)?[^\s"',;]{4,}/gi,
+    (_, prefix, scheme) => `${prefix}${scheme ? `${scheme} ` : ''}${marker('secret')}`],
+  [/\b(Bearer[ \t]+)[A-Za-z0-9._~+/-]{16,}=*/g, (_, prefix) => `${prefix}${marker('secret')}`],
+  // Keep the setting name: it tells the classifier what kind of work this is.
+  [/\b([A-Za-z0-9_.-]{0,40}(?:passw(?:or)?d|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|credentials?)[A-Za-z0-9_.-]{0,40})(["']?[ \t]{0,8}[:=][ \t]{0,8})(["']?)[^\s"',;]{4,}/gi,
+    (_, name, separator, quote) => `${name}${separator}${quote}${marker('secret')}`],
+  [/\b[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,253}\.[A-Za-z]{2,24}\b/g, marker('email')],
+  [/\b[A-Z]{2}[0-9]{2}(?: ?[A-Z0-9]{4}){2,7}(?: ?[A-Z0-9]{1,4})?\b/g, match => ibanValid(match) ? marker('iban') : match],
+  // Major card networks only, so millisecond timestamps and IDs survive.
+  [/\b(?:4|5[1-5]|2[2-7]|3[47]|6)(?:[0-9][ -]?){11,17}[0-9]\b/g, match => luhnValid(match) ? marker('card') : match],
+]);
+
+/** @param {string} text */
+export function redactSensitive(text) {
+  let result = text;
+  for (const rule of RULES) {
+    // @ts-ignore String.replace accepts either replacement form.
+    result = typeof rule === 'function' ? rule(result) : result.replace(rule[0], rule[1]);
+  }
+  return result;
+}

package/src/router.mjs

@@ -191,7 +191,7 @@ export class Router {
     // Include live configuration/rubric facts so configuration changes cannot
     // reuse cached decisions from another evaluator, account or confidence rule.
     const c = this.config;
-    const evaluator = c.evaluator ?? 'jev';
+    const evaluator = c.evaluator ?? 'ollama';
     const settings = evaluator === 'ollama'
       ? { evaluator, ollamaEndpoint: c.ollamaEndpoint, ollamaModel: c.ollamaModel, ollamaTimeoutMs: c.ollamaTimeoutMs,
         ollamaStateChars: c.ollamaStateChars, ollamaKeepAlive: c.ollamaKeepAlive }

package/src/session-history.mjs

@@ -231,7 +231,8 @@ export async function sessionsCommand(args, { env = process.env, write = console
     || (operation === 'list' ? positional.length !== 0 : positional.length !== 1)) {
     throw new Error('Usage: claude-autorouter sessions list [--json] | sessions show ID [--json]');
   }
-  const loaded = loadUserConfig(env, { allowMissing: true });
+  // History needs only the log directory; never prompt for keychain access.
+  const loaded = loadUserConfig(env, { allowMissing: true, readSecrets: false });
   const directory = parseSessionLogDir(loaded.env.AUTOROUTER_SESSION_LOG_DIR);
   if (!directory) {
     const report = { schema_version: 1, type: 'session_history', logging_enabled: false, sessions: [],

package/src/telemetry-event.mjs

@@ -1,4 +1,5 @@
 // @ts-check
+import { redactSensitive } from './redaction.mjs';
 // Shared, bounded telemetry contract. Never copy request bodies, headers, raw
 // errors or arbitrary provider fields into status snapshots or saved history.
 export const TELEMETRY_SCHEMA_VERSION = 2;
@@ -161,6 +162,9 @@ export function normalizeTelemetryEvent(entry) {
 function excerpt(value) {
   let text = '', length = 0;
   if (typeof value !== 'string') return { text, truncated: false };
+  // Defense in depth, and it also covers records written before redaction
+  // existed when they are read back. Already-redacted text is unchanged.
+  value = redactSensitive(value);
   for (const character of value) {
     if (length++ === 500) return { text: text.toWellFormed(), truncated: true };
     text += character;

package/src/user-config.mjs

@@ -5,9 +5,10 @@ import {
 import { createHash, randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { createKeychain } from './keychain.mjs';
 
 export const CONFIG_KEYS = Object.freeze([
-  'AUTOROUTER_AUTH_MODE', 'AUTOROUTER_CLIENT_PROFILE',
+  'AUTOROUTER_AUTH_MODE', 'AUTOROUTER_CLIENT_PROFILE', 'AUTOROUTER_SECRET_STORE',
   'ANTHROPIC_API_KEY', 'TYPESAFE_API_KEY', 'AUTOROUTER_TOKEN',
   'AUTOROUTER_UPSTREAM_URL', 'AUTOROUTER_JEV_URL', 'AUTOROUTER_JEV_MODEL',
   'AUTOROUTER_HAIKU_MODEL', 'AUTOROUTER_SONNET_MODEL', 'AUTOROUTER_OPUS_MODEL',
@@ -19,7 +20,13 @@ export const CONFIG_KEYS = Object.freeze([
   'AUTOROUTER_OLLAMA_TIMEOUT_MS', 'AUTOROUTER_OLLAMA_KEEP_ALIVE',
 ]);
 export const SECRET_CONFIG_KEYS = Object.freeze(['ANTHROPIC_API_KEY', 'TYPESAFE_API_KEY', 'AUTOROUTER_TOKEN']);
+export const SECRET_STORES = Object.freeze(['file', 'keychain']);
 const allowedKeys = new Set(CONFIG_KEYS);
+const defaultKeychain = createKeychain();
+// Items are scoped to one configuration file, so separate configurations
+// (including test fixtures) never share or overwrite each other's secrets.
+const keychainAccount = (path, key) => `${key}:${createHash('sha256').update(path).digest('hex').slice(0, 16)}`;
+const keychainLabel = (path, key) => `AutoRouter ${key} (${path})`;
 const revision = content => createHash('sha256').update(content).digest('hex');
 const SAFE_FS_CODES = new Set([
   'EACCES', 'EPERM', 'ENOENT', 'ENOTDIR', 'EISDIR', 'ENOSPC', 'EROFS',
@@ -57,6 +64,9 @@ function validate(values) {
     }
     validated[key] = descriptor.value;
   }
+  if (validated.AUTOROUTER_SECRET_STORE !== undefined && !SECRET_STORES.includes(validated.AUTOROUTER_SECRET_STORE)) {
+    throw configError('AUTOROUTER_SECRET_STORE must be file or keychain.');
+  }
   return validated;
 }
 
@@ -74,14 +84,20 @@ export function getConfigPath(env = process.env) {
   return join(xdg || join(homedir(), '.config'), 'claude-autorouter', 'config.json');
 }
 
-export function loadUserConfig(env = process.env, { allowMissing = false } = {}) {
+// The saved store setting decides where saved secrets live; the environment
+// only overrides values. With the keychain store, `values` includes secrets
+// read from the keychain so callers can update settings without losing them.
+export function loadUserConfig(env = process.env, { allowMissing = false, readSecrets = true, keychain = defaultKeychain } = {}) {
   const path = getConfigPath(env);
   let content;
   try {
     content = readFileSync(path, 'utf8');
   } catch (error) {
     if (error.code === 'ENOENT') {
-      if (env.AUTOROUTER_CONFIG === undefined || allowMissing) return { env: { ...env }, values: {}, path, exists: false, revision: null };
+      if (env.AUTOROUTER_CONFIG === undefined || allowMissing) {
+        return { env: { ...env }, values: {}, path, exists: false, revision: null,
+          secretStore: 'file', keychainSecrets: [], unavailableSecrets: [] };
+      }
       throw configError('AUTOROUTER_CONFIG points to a missing configuration file.');
     }
     throw filesystemError(error, 'read');
@@ -90,7 +106,36 @@ export function loadUserConfig(env = process.env, { allowMissing = false } = {})
   try { parsed = JSON.parse(content); }
   catch { throw configError('AutoRouter configuration must contain valid JSON.'); }
   const values = validate(parsed);
-  return { env: { ...values, ...env }, values, path, exists: true, revision: revision(content) };
+  const secretStore = values.AUTOROUTER_SECRET_STORE ?? 'file';
+  const keychainSecrets = [], unavailableSecrets = [];
+  if (secretStore === 'keychain' && readSecrets) {
+    for (const key of SECRET_CONFIG_KEYS) {
+      if (Object.hasOwn(values, key)) continue;
+      let value;
+      try { value = keychain.read(keychainAccount(path, key)); }
+      catch (error) {
+        // An environment value can stand in for a locked keychain, such as
+        // over SSH. Only a missing required value stops the caller.
+        if (env[key] !== undefined) { unavailableSecrets.push(key); continue; }
+        throw error;
+      }
+      if (value !== undefined) { values[key] = value; keychainSecrets.push(key); }
+    }
+  }
+  return { env: { ...values, ...env }, values, path, exists: true, revision: revision(content),
+    secretStore, keychainSecrets, unavailableSecrets };
+}
+
+// Keychain items to delete when saving `nextStore`, given what was loaded.
+// Moving between stores needs every saved secret, so refuse while one could
+// not be read; deleting it unseen would lose it.
+export function keychainRemovals(loaded, nextStore, { replace = false, values = {} } = {}) {
+  if (loaded.secretStore !== 'keychain') return [];
+  if (nextStore !== 'keychain' && loaded.unavailableSecrets?.length) {
+    throw configError('Could not read every saved secret from the macOS Keychain. Unlock the login keychain and retry.');
+  }
+  if (nextStore !== 'keychain') return [...loaded.keychainSecrets];
+  return replace ? loaded.keychainSecrets.filter(key => !Object.hasOwn(values, key)) : [];
 }
 
 function existingFile(path) {
@@ -102,8 +147,17 @@ function existingFile(path) {
   return stat;
 }
 
-export function saveUserConfig(values, { env = process.env, overwrite = false, expectedRevision } = {}) {
+// With the keychain store, secrets are written to the keychain before the file
+// (an interrupted move leaves both copies, never neither) and stale items are
+// removed only after the file is saved.
+export function saveUserConfig(values, {
+  env = process.env, overwrite = false, expectedRevision, removeSecrets = [], keychain = defaultKeychain,
+} = {}) {
   const validated = validate(values);
+  const store = validated.AUTOROUTER_SECRET_STORE ?? 'file';
+  const keychainKeys = store === 'keychain' ? SECRET_CONFIG_KEYS.filter(key => Object.hasOwn(validated, key)) : [];
+  const fileValues = { ...validated };
+  for (const key of keychainKeys) delete fileValues[key];
   const path = getConfigPath(env);
   const parent = dirname(path);
   let temporary;
@@ -118,13 +172,17 @@ export function saveUserConfig(values, { env = process.env, overwrite = false, e
       throw configError('AutoRouter configuration already exists; use overwrite to replace it.');
     }
     checkRevision();
+    if (store === 'keychain' && !keychain.available) {
+      throw configError('The macOS Keychain secret store is available only on macOS.');
+    }
+    for (const key of keychainKeys) keychain.write(keychainAccount(path, key), validated[key], keychainLabel(path, key));
     // mkdir leaves existing directory permissions unchanged. Only directories
     // created for this configuration receive the private creation mode.
     mkdirSync(parent, { recursive: true, mode: 0o700 });
     temporary = join(parent, `.${basename(path)}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`);
     descriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
     fchmodSync(descriptor, 0o600);
-    writeFileSync(descriptor, `${JSON.stringify(validated, null, 2)}\n`, 'utf8');
+    writeFileSync(descriptor, `${JSON.stringify(fileValues, null, 2)}\n`, 'utf8');
     fsyncSync(descriptor);
     closeSync(descriptor);
     descriptor = undefined;
@@ -143,6 +201,9 @@ export function saveUserConfig(values, { env = process.env, overwrite = false, e
       // symlink can never be replaced by the default save operation.
       linkSync(temporary, path);
     }
+    for (const key of removeSecrets) {
+      if (SECRET_CONFIG_KEYS.includes(key) && !keychainKeys.includes(key)) keychain.remove(keychainAccount(path, key));
+    }
     return path;
   } catch (error) {
     if (error?.code === 'EEXIST') {