Skip to content

Latest commit

 

History

History
219 lines (180 loc) · 11.6 KB

credential-proxy.md

File metadata and controls

219 lines (180 loc) · 11.6 KB

Credential-injecting proxy ([proxy])

The proxy keeps Anthropic and OpenAI API keys, Claude setup tokens, and Codex workspace tokens on the host. It is opt-in, off by default, and supports Firecracker and Lima.

What it does

With open networking and without proxy mode, coop forwards the raw ANTHROPIC_API_KEY / OPENAI_API_KEY into the guest as SSH SendEnv variables — a prompt-injected or rogue agent can read them from its own environment and exfiltrate them. Isolated Firecracker mode suppresses direct credentials and requires the corresponding managed proxy for Claude or Codex.

With proxy mode, the raw credential never enters the guest. coop runs a small host-side reverse proxy (coop-proxy) — one process per (VM, provider) — for the lifetime of the VM:

  • The proxy binds host loopback and is exposed into the guest by a per-instance ssh -R reverse tunnel; the guest is pointed at http://127.0.0.1:<port> and holds only a per-instance capability token.
    • Claude Code: ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN in the managed ~/.claude/settings.json.
    • Codex: a [model_providers.coop_local] block in ~/.codex/config.toml (base_url at the proxy, wire_api = "responses") with the capability token supplied as the provider's bearer env_key. Proxy mode pins no model — Codex keeps its own, only its egress is redirected.
  • The proxy verifies that token (constant-time), strips it, injects the real credential (x-api-key, or Authorization: Bearer), and streams the request to the pinned upstream (api.anthropic.com, api.openai.com, or the Codex backend on chatgpt.com) over TLS.
  • The raw ANTHROPIC_API_KEY / OPENAI_API_KEY is no longer forwarded, and in proxy mode Codex's ~/.codex/auth.json is not staged onto the guest disk (it holds a refreshable subscription token — the exact at-rest exposure #411 closes). A cached ChatGPT OAuth session is not supported in proxy mode; use an OpenAI API key or a Codex workspace personal access token.

When agent bootstrap runs with an OpenAI proxy, coop also removes any existing ~/.codex/auth.json left by a previous direct-auth boot. If removal fails, proxy bootstrap aborts and tears down the proxy. --no-agents skips this cleanup along with the rest of agent bootstrap.

For workspace entitlements through the proxy, use a Codex personal access token as described below. For interactive account login inside the guest, use [codex] auth = "chatgpt" instead of [proxy.openai]. That mode stores Codex credentials in the guest Linux keyring and cannot be combined with a proxy.

The capability token is worthless off the host — it only authorizes the local proxy, which holds the real key itself — so exfiltrating it gains a compromised guest nothing.

Operation policy

After authenticating the capability token, the proxy default-denies operations before connecting upstream. The only allowed method/path pairs are:

Provider Allowed operation
OpenAI POST /v1/responses
Codex access token POST /v1/responses, translated to POST /backend-api/codex/responses on chatgpt.com
Anthropic POST /v1/messages
Anthropic POST /v1/messages/count_tokens

All other methods, paths, and unknown upstream profiles receive a local 403. This limits a compromised guest to the model calls its configured coding agent needs, and prevents it from using the injected key for account, model, admin, or arbitrary retrieval APIs. Widening this list requires security review and tests for the new agent operation.

The request bodies are intentionally opaque and streamed. In particular, an allowed POST /v1/responses can still reference OpenAI objects by ID (such as existing conversations, responses, prompts, or files) when the injected key is authorized for them. The allowlist is defense in depth against broad API use, not object-level tenant isolation.

The policy is intentionally closed: if a future agent version needs another endpoint, it fails locally with 403 until coop adds and reviews that route. Claude Code may issue HEAD /api/hello and GET /v1/models?limit=1000 for warmup or discovery; proxy mode intentionally refuses both because its normal message and token-count operations do not require gateway discovery. Codex's proxy provider is named coop credential proxy, not OpenAI, so Codex does not currently enable its OpenAI-specific POST /v1/responses/compact behavior. If either client changes this behavior, add the route only with an explicit policy, test, and documentation update.

Enabling it

The easiest path is coop proxy setup: it takes a pasted credential, stores it in a secret backend of your choice (macOS Keychain / Linux secret-service / 1Password / a 0600 file), and writes the [proxy.<provider>] block for you with a cmd: reference — so the credential is never plaintext in the config.

  • Anthropic (default): coop proxy setup takes a Claude setup-token (subscription) or an API key with --api-key. To generate a token first, run claude setup-token on the host (needs a Claude subscription; the token is inference-scoped, ~1 year).
  • OpenAI (Codex): coop proxy setup --openai takes an OpenAI API key (always injected as Authorization: Bearer).
  • Codex workspace access token: coop proxy setup --openai --codex-access-token takes a Codex-scoped personal access token (at-...) from ChatGPT Admin > Access tokens. Requests use the creator's workspace Codex entitlements and controls rather than Platform API billing. Availability and usage charges follow the workspace plan. A Workspace Agents-only token is not a Codex inference credential.

Or configure it by hand:

[proxy.anthropic]
credential = "cmd:op read op://Private/Anthropic/credential"  # or a plain key
auth = "api_key"   # api_key → x-api-key (default); bearer → a Claude setup-token

[proxy.openai]
credential = "cmd:op read op://Private/OpenAI/credential"
auth = "bearer"    # OpenAI keys inject as Authorization: Bearer

For a Codex workspace token, use this OpenAI block instead:

[proxy.openai]
credential = "cmd:op read op://Private/Codex/access-token"
auth = "codex_access_token"

Leave [codex] auth at its default (api_key); in proxy mode the host credential determines billing, and the guest authenticates only with its capability token. No guest codex login is required. Cached OAuth credentials and legacy agent-identity JWTs are not accepted by this mode.

Setup and every proxy start validate the token with a bounded HTTPS metadata request to auth.openai.com. Host curl is required. The proxy then pins chatgpt.com and the workspace headers returned by that lookup, replacing any guest-supplied account or FedRAMP headers. The real token travels through stdin to curl and the proxy; it is never a command-line argument. The guest cannot call metadata, login, refresh, or arbitrary ChatGPT endpoints through the proxy.

The guest provider uses streaming HTTP Responses requests with WebSockets disabled. Model selection stays with Codex; choose a model available to your workspace. This inference-only proxy does not expose ChatGPT plugins or account management. Expired/revoked tokens fail authentication; there is no OAuth refresh or API-key fallback. Rotate the secret, then restart the VM to load it. CODEX_ACCESS_TOKEN, as well as OPENAI_API_KEY, is suppressed from managed environment forwarding whenever the OpenAI proxy is active. Explicit guest_files copies remain a separate credential-exposure opt-in.

The credential uses the same cmd: resolution as every other coop secret and is resolved on the host at VM start. For Claude subscription billing without exposure, run claude setup-token on the host, stash the printed one-year token, reference it via cmd:, and set auth = "bearer".

Per-VM credential overrides

The [proxy.<provider>] blocks are the defaults for every VM. A single VM can use a different credential — for per-project billing, scope, or revocation — with coop proxy setup --openai --vm <name> (or --anthropic --vm <name>). The override is stored in that instance's state (<inst.dir>/proxy.json), not in a growing config table, and its secret is namespaced separately (coop-openai-<vm>).

Resolution per provider is override → default → off: the per-VM override wins, else the config default, else the proxy is off for that provider. This is purely host-side credential selection — the proxy binary and the per-VM capability token are unchanged, so there is no new attack surface.

coop proxy status shows the defaults and every VM's overrides; coop proxy status --vm <name> shows one VM's effective resolution. Credentials are shown as their cmd: reference (a command, not the secret); a hand-written literal is redacted.

Proxy mode applies only in remote model mode. coop model <vm> local takes precedence (the VM routes at your local model server and the proxy is torn down). If credential resolution fails at start, the VM fails closed — it does not come up on a path where the agent silently has no or the wrong key.

What it does and does not guarantee

It stops a rogue agent from reading a usable key from its environment or disk. It does not:

  • Stop use of the credential while the agent runs — the agent still makes model calls through the proxy (that is the point). Non-exposure limits exfiltration of the raw key, not use during the session.
  • Provide egress control — a token-less agent with open egress can still reach arbitrary hosts (issue #2). The proxy composes with, but does not replace, "no route out except the proxy."
  • Provide scope enforcement — the injected key keeps its full account scope (issue #73). Non-exposure and scope are orthogonal.

The proxy itself is new attack surface, mitigated by a fixed per-route upstream (the guest controls only the path, never the host — closing SSRF), TLS verification against a pinned root set, a required capability token, and resource limits. Each proxy allows at most 256 accepted guest TCP connections and 256 concurrent requests; excess connections are closed immediately, so idle sockets cannot bypass the request limit. The listener binds only host loopback and is reverse-tunnelled to exactly one guest — never a non-loopback interface, never the LAN.

It is also jailed to bound the blast radius of a proxy exploit. On Linux, Landlock denies filesystem writes and program execution as a required floor; additional filesystem restrictions apply where the kernel supports them. TCP egress is limited to :443 and :53 on kernels ≥6.7. On kernels 5.13–6.6, the proxy can start with that TCP restriction absent. On macOS, sandbox-exec applies a Seatbelt profile that denies filesystem writes and program execution and limits egress to those ports.

Startup fails closed if the required filesystem/exec floor cannot be applied. The network rules are port-scoped, not host-scoped, and Landlock does not restrict UDP. See trust-model.md for the full threat model and accepted limitations.

Platform support

Firecracker (Linux) and Lima (macOS). The proxy binds 127.0.0.1 on the host and is exposed into the guest with a per-instance ssh -R reverse tunnel, so it works identically on both backends (each already keeps an SSH channel to its guest). The host-side proxy process is jailed on both — Landlock on Linux (enabled on the host; kernel ≥5.13, with TCP scoping from ≥6.7), Seatbelt via sandbox-exec on macOS. GitHub credentials are not supported.