# The secret broker

Let the agent use an API token or password in a command without ever seeing its value, limited to the commands and hosts you choose.

Blocking `.env` keeps secrets out of the agent's context, but agents still need to call APIs, publish packages and log in to tools. The secret broker lets the agent **use** a secret without **seeing** it.

## How it works

1. You store the secret in Warden. The value goes into the macOS Keychain.
2. The agent writes a placeholder in a shell command: `{{secret:NPM_TOKEN}}`.
3. Warden checks the command against your rules and the secret's own limits. Only if it is allowed (or you approve it) does Warden put the value into that one command's environment and run it.
4. The value is scrubbed from the output, including common encodings of it, before the agent reads it.

Every use is recorded by name, never by value, and shows a **SECRET** chip in Decisions.

```bash title="What the agent writes"
$ npm publish --//registry.npmjs.org/:_authToken={{secret:NPM_TOKEN}}
$ curl -H "Authorization: Bearer {{secret:STRIPE_KEY}}" https://api.stripe.com/v1/charges
```

## Add a secret

:::steps
1. Open **Policies → Secrets**, for Global or one project. A project secret shadows a Global one with the same name.
2. **Add a secret**: a name in capitals (`NPM_TOKEN`, `STRIPE_KEY`) and the value (at least 8 characters, so it can be scrubbed reliably). Or **Import from .env** to bring several in at once.
3. Choose **which commands** may use it without asking (for example `npm publish*` or `gh api`), and **which hosts** it may be sent to (for example `*.stripe.com`).
4. Choose what happens otherwise: **Ask me first** or **Block it**.
:::

## Rules for secrets

The `secret` key matches a command that uses a brokered secret:

```yaml
default: allow
rules:
  - ask: { secret: "*" }
    when: { trigger_mode: automated }
    reason: "Unattended runs ask before using any secret"
  - deny: { secret: PROD_DB_PASSWORD }
    unless: { command: psql }
    reason: "The production database password is only for psql"
```

A command that names the secret's environment variable directly is denied, so the agent can't read the value through the back door.