Vault

The vault keeps credentials and sensitive personal or financial values (API tokens, OAuth tokens, a card, an IBAN) in your operating system's secret store, records where each one may go, and makes the firewall treat every stored value as a credential wherever it appears.

The agent writes a reference such as vault://github/token or vault://bank/primary#iban where the value would go. The firewall puts the value in only at the moment an allowed action runs, only for destinations that secret is bound to, and scrubs it back to the reference in everything the model reads.

Built: the stores, the signed index, bindings, the commands below, the data-loss rule for stored values (FW-VAULT-EGRESS), the doctor checks, and substitution through the MCP gateway (every client) and through the hooks for shell commands where the agent can rewrite tool input (Claude Code). Upstream OAuth tokens from mcp login live in the vault. launchsafe-firewall run --env NAME=vault://... -- <command> is built with run. Not built: vault import --from-config and vault unlock or lock.

CommandsCopy Anchor Link

The changing commands refuse to run from a script or from inside an agent, and the firewall denies them (FW-TAMPER) when an agent tries. They need an approval passphrase (approver init): it unlocks the key that signs the index.

Names are 1 to 4 parts of lower-case letters, digits, _ and -, joined by / (github/token, bank/primary). A reference is vault://<name> or vault://<name>#<field>, and it must start on a word boundary.

Kinds and their default fields: credential and oauth (value), card (number, expiry, cvc, name), iban (iban, bic, holder), national_id and personal (value).

Where values are storedCopy Anchor Link

On macOS the value is written with /usr/bin/security -i, the command on standard input, so it is never in argv or ps. On Linux it uses secret-tool store, the value on standard input. Helpers run only from fixed root-owned system paths, never through PATH. approver rotate re-signs the index with the new key and re-wraps the file store's data key.

The signed indexCopy Anchor Link

vault/index.json lists each secret's name, kind, fields, store, confirmation setting, bindings and per-field fingerprints (length, two rolling hashes and a SHA-256 prefix; never the value). It is signed with the approver key and verified against the key the hook command pins.

If the signature does not verify, no secret is bound to anything, the values are still recognised and denied everywhere, and doctor fails. If the index cannot be read at all, no stored value could be recognised, so it is not treated as "no vault". In both cases, while the vault is on, every send and every fetch that carries data asks (FW-VAULT-INDEX) until the index is repaired. A change is never built on an index that does not verify, so a forged binding cannot be laundered by the next vault allow.

Bindings live only in the signed index, never in a policy file, so no repository can bind a secret to its own host.

A stored value is always a credential (FW-VAULT-EGRESS)Copy Anchor Link

Any outbound payload (a request body or URL, MCP arguments, a message) that contains a stored value, in the clear or base64, base32, hex, URL or DNS-label encoded, going to a destination that secret is not bound to, is denied. The rule ignores dataAllowHosts and sendAllowHosts: the per-secret binding is the narrower statement. It applies in every session, trusted or not, and is notified like other data blocks. This covers a value that reached the agent some other way, such as a .env file it read. Fields shorter than 12 characters (a CVC, an expiry date) cannot be fingerprinted; vault add says which.

A stored value also counts as a secret elsewhere: tool output that shows one makes the session sensitive and remembers its fingerprint, and a file written with one is a secret file (publishing it later needs you).

The keychain and keyring tools naming the firewall's service, and lookups that do not say which service they mean (so they would reach the vault's items too), are denied from inside an agent (FW-TAMPER): the store is the firewall's data.

SubstitutionCopy Anchor Link

A reference only matters where it would leave the machine: in a request's URL or body, a shell command that sends data, or MCP arguments. Anywhere else (a file the agent writes, a comment) it is just text: nothing is substituted and no rule applies.

Every other rule judges the action exactly as if the reference were text, so a bound substitution in an untrusted session still needs FW-SEND's approval. The question names the reference, the kind and the destination, never the value. Values are read from the store only after the final verdict is allow; nothing is read for a denied or held action. A value that cannot be read (a locked store, a missing item) denies the action: it is never sent with the reference in place of the value.

Where substitution works, per agentCopy Anchor Link

vault.shellRewrite: "off" refuses the shell rewrite everywhere.

The hook rewrite (Claude Code)Copy Anchor Link

A Bash command such as

curl -H "Authorization: Bearer vault://github/token" https://api.github.com/user

is allowed (when bound) with its input rewritten to a single-use ticketed run:

launchsafe-firewall run --ticket <T> --env __LSV_1=vault://github/token -- /bin/sh -c 'curl -H "Authorization: Bearer ${__LSV_1}" https://api.github.com/user'

Only the curl or wget command that carries the references gets the values. Each such simple command is replaced, where it stands, by its own ticketed run; everything around it (pipes, && lists, redirections) stays in the agent's shell as written and reads only the filtered output.

• The values exist only in that one process's environment: no other command of the agent's runs with them, and a command that names __LSV_ is refused before anything runs.
• The program is named by its absolute path, found in the PATH the hook itself was started with or the system directories. Not found: denied.
• curl -q (wget --no-config) comes first, so a .curlrc or .wgetrc the agent wrote cannot add trace or log options.
• The rewrite rebuilds the command from literal words, so it carries no variable or substitution that could be computed at run time. Two sending commands get two tickets.
• wget also gets --max-redirect=0. curl follows no redirects without -L, which is refused.
• The ticketed run drops, from the environment it inherits, every variable that changes routing, name resolution, TLS trust or config (the *_proxy family, HOSTALIASES, LOCALDOMAIN, SSLKEYLOGFILE, CURL_CA_BUNDLE, SSL_CERT_FILE, CURL_HOME, WGETRC, XDG_CONFIG_HOME, LD_*, DYLD_*).

The ticket is stored by the hook with a hash of the exact --env pairs and argv, the references, the session and an expiry (vault.ticketSeconds, ten minutes for an asked action). run takes it atomically and refuses (exit 77, logged as vault_denied) when it is unknown, already used, expired, or issued for another command.

The curl and wget option allowlistCopy Anchor Link

A value travels only in a request to the binding's own host, and curl or wget never write it to disk or to the output. So a curl or wget command that carries a reference is rewritten only when every option is on this list; anything else is FW-VAULT-OPTION, naming the option. Long options are matched by their full name only. Short options may be clustered (-sSf, -XPOST).

• curl: -s, -S, -f, --fail-with-body, --no-progress-meter, --compressed, -i, --show-headers, -I, -X, -H (may carry a reference; -H @file is refused), -d and its --data* and --json forms (may carry a reference; @file is fine, a reference after @ is refused), -u, -G (moves the data into the URL, so a reference there needs --allow-in-url), -A, -m, --connect-timeout, --retry, -w (only %{name} from a fixed list of transfer variables, never %output{}, %header{}, %{url}, %{json} or @file), --url.
• wget: -q, -nv, --content-on-error, --no-config, -S, --method, --header, --post-data, --body-data, --user, --password, --http-user, --http-password, -U, -T, -t, --max-redirect=0.
• Saved responses: -o, -O and wget's -O are refused in a command that carries any vault reference, unless the target is - (stdout) or /dev/null. A saved response is not filtered, and a server that echoes the request would write the value into the file. Plain wget (which saves a file named after the URL) is refused in such a command.
• Refused with a reason of their own: -L, --resolve, --connect-to, -x and --proxy, --preproxy, --socks*, --doh-url, --dns-servers, --unix-socket, --interface, -v, --trace, --trace-ascii, -K, --variable, -k, --next; wget -i, -e, -d, --no-check-certificate, -r, -m.

A reference may appear only in a header, the data, the credentials or a URL. Every URL must be written out as https://host[:port]/... (or http:// with --allow-http), with no user info, no globbing in the host and no backslash, and every URL of the command must be the bound host.

Output scrubbingCopy Anchor Link

What the model reads is scrubbed back to the reference, by the gateway for MCP and by PostToolUse for Claude Code (every fingerprinted value in the clear; output in which a value is still detectable is replaced by a withheld note). Dumps (curl --trace -, hexdump -C, xxd) are judged whole, so a value split over rows, or spelled as spaced hex, is still found. Fields shorter than 12 characters have no fingerprint, so only the gateway, which knows the value for the call in flight, can scrub them.

Upstream OAuth tokensCopy Anchor Link

mcp login stores the tokens as vault://mcp/<server> (kind oauth, bound mcp:<server>) when it can sign the entry. The gateway sends them only as the upstream Authorization header, and refreshes them in the store unattended. See MCP gateway.

At session startCopy Anchor Link

With vault.listInContext, the agent is told which references exist and where each may go, names and destinations only.

AuditCopy Anchor Link

Entries in the signed decision log never hold a value or a fingerprint: vault_change (add, allow, revoke, remove, rotate, re-sign after approver rotate, refresh for an OAuth token), vault_use (session, reference, kind, how, destination, binding, action hash, verdict), vault_denied (the rule or the problem, such as a store that could not be read) and vault_scrub (a gateway answer withheld because a vaulted value could not be scrubbed). Queue items keep the references, never values; notifications are fixed text.

PolicyCopy Anchor Link

These keys belong to schema version 3 and are still read from a version 2 file, with the same meaning.

DoctorCopy Anchor Link

doctor reports whether the index verifies against your approval key; how many secrets and bindings there are, and which secrets are bound to nothing; entries whose store is not available on this machine; values missing from the macOS Keychain (checked without reading them, so no dialog); and the weaker stores and financial or personal items stored without per-use confirmation. It is not part of the protection score.

Honest limitsCopy Anchor Link

• A bound host that echoes a request back can return the value. What comes back is filtered in the clear and in the encodings above, not in arbitrary transformations. Redirects are never followed with a value.
• The host check is on the name: the system's own resolver decides the address. A bound name that resolves somewhere unexpected (your DNS, your /etc/hosts) gets the value. A host binding ignores the port and a trailing dot.
• Only curl and wget get values from a shell command. For other programs, a person binds the secret to the command (vault allow <name> --process) and runs it with run --env.

The vault keeps secrets out of what the agent reads and limits where actions the firewall sees can send them. It is not a hardware boundary: a program running as you, outside the sandbox, that the firewall cannot see into can read your keychain (on Linux always; on macOS only for secrets stored without per-use confirmation). Run the firewall with the agent's sandbox.