secret-guard

Secret Guard

Core Principle

You never possess a secret value. You only pass references (names).

A secret must never enter the model's context window. Do not read secret files, do not print values, do not reconstruct them. To authenticate, you emit a credential reference by name and let a trusted, non-LLM broker resolve→inject→scrub. This is architectural, not advisory: the value stays inside the broker process and is never returned to you.

Secrets live in the OS keyring (Keychain / libsecret / Windows Credential Manager). They are stored out-of-band by a human, e.g.:

keyring set agent-secrets github_token
keyring set agent-secrets openai_api_key

You reference them by name only — e.g. github_token. You never see the value.

---

Mechanism (a): Resolve-and-Inject — PRIMARY

Use this for all API and MCP token use. The broker resolves the named credential, injects it into the request header, performs the call, scrubs the response, and returns only the scrubbed body. The secret exists only inside the broker process for the duration of one request.

python3 scripts/keyring_broker.py request \
    --name github_token \
    --url https://api.github.com/user \
    --header "Authorization: Bearer {secret}"

• --name is a reference, never a value.
• {secret} is a placeholder the broker fills internally; you never type the token.
• Output is scrubbed before you see it.

For MCP servers: put the credential in the MCP server's environment/config, resolved by the client runtime — never in tool arguments, conversation, or files. Prefer OAuth flows where the server holds the token and the client gets a short-lived, scoped handle. Use ${input:...}/env indirection so no literal appears in committed config.

---

Mechanism (b): Env-Injecting Exec — DISCOURAGED FALLBACK

Only when a legacy CLI can read a credential solely from its environment and (a) is impossible. The broker injects the value into a single child process's environment (never yours), runs one command, and scrubs its output.