SeedPass/docs/agent_security_model.md

Agent Security Model

What the SeedPass session agent protects, what it does not, and why. Written so a reviewer does not have to infer the intended boundary from the code.

Scope: js/packages/cli/src/agent.ts and the token surface it serves. The vault formats and derivations are covered by docs/typescript_port_compatibility_matrix.md.

The problem

A stateless CLI must hold an unlocked seed somewhere to be usable, and an AI agent or automation that drives it should be able to use a credential without being handed the vault. Those are two different principals sharing one machine.

Principals

Principal	Proves itself with	Gets
Owner	The capability secret in a 0600 file beside the socket	Everything: unlock/lock, the parent seed, token issuance, status, shutdown
Token holder	A bearer token issued by the owner	Only what the token's scopes and constraints allow, enforced by the daemon
Anyone else	Nothing	Nothing but a liveness ping

Enforcement lives in the daemon, never in the CLI. The CLI is untrusted from the daemon's point of view: any local process can speak the socket protocol, so a check that exists only in the client is not a check at all. (This was a real defect, found in review: the socket accepted privileged operations from any local process because the restrictions lived in the CLI.)

What the capability does and does not do

The socket is 0600, which proves only "a process running as this user". That does not distinguish the owner's CLI from a scoped agent that was handed a token — both run as you. The capability file raises the bar to "can read the owner's files", which is the same bar as the vault itself.

It does not defend against a same-uid attacker. Anyone who can read that file, read the vault, or ptrace the daemon has already won. Defending against that needs an OS-level boundary (a separate user, a container, a hardware token) that a user-space daemon cannot provide. If your threat model includes hostile code running as you, this design does not save you.

Token scopes

• read — redacted entry metadata only. The daemon filters to entries the token's kind and label constraints cover, so out-of-scope entries are not disclosed at all, and secret-bearing fields are replaced with has_* flags. A read token never receives the decrypted index.
• use — the daemon delivers a secret to a sink (clipboard, a child process's environment, a child's stdin) and returns a receipt. The plaintext does not cross the socket back to the holder.
• reveal — plaintext egress. Distinct from use on purpose.

Constraints: entry kinds, a label regex, a TTL, a use count, and an optional exec allowlist. Denials do not consume uses. Tokens die with a vault lock, a TTL expiry, or a revoke, and do not come back on the next unlock.

The honest limit of use

A use holder that chooses the sink command can read the secret from inside that command. --exec 'sh -c "cat > /tmp/stolen"' is a legitimate use as far as the daemon is concerned.

So use is not "can act without learning". It is:

• containment, when the token carries an exec allowlist — then the holder can only hand the secret to commands you named;
• accountability, always — the audit log records the exact argv that received each secret.

If you need a hard guarantee that an agent cannot learn a credential, do not hand it a use token for that credential. Have it call something that holds the credential itself.

Audit log

Append-only, HMAC-chained (sig = HMAC(key_index, prev_sig || canonical payload)), keyed by the profile's index key, so only the seed holder can extend or verify it. A signed head file records the expected record count and last signature — without it, deleting the log or a suffix of it leaves a shorter file that still verifies perfectly. agent audit-verify walks the chain and fails at the first break. Writes are serialized so concurrent requests cannot interleave and desynchronize it. Recorded: unlocks, token lifecycle, index reads, deliveries (with the sink and argv), and every denial with its reason. Secret values are never recorded.

Known limits, stated rather than hidden

1. Same-uid attackers win — see above. Concretely: a scoped agent is given the app directory, so the capability is deliberately stored outside it (in XDG_RUNTIME_DIR), but a token holder that can read that file can still unset its token and act as the owner. Treat a token as a convenience and an audit trail, not as a sandbox. Real containment needs a separate uid or a container.
2. use can be turned into reveal by a holder that picks the command, unless an exec allowlist is set.
3. Memory is not scrubbed. Seeds live in the daemon's heap while unlocked; JavaScript gives no reliable zeroization. Lock when you are done — that drops the seed, its tokens, and the derived audit key.
4. The capability file lives on disk for the daemon's lifetime, so it survives a crash of the CLI but also a crash of the daemon; a stale file is replaced on the next start.
5. Two protocol-level issues are shared with the Python implementation and cannot be fixed in one implementation without breaking convergence: tombstone retention allows deletion replay once the cap is exceeded, and SSH and PGP entries at the same index derive the same Ed25519 key. Both need a versioned change in both implementations; both are tracked in the compatibility matrix.

Verifying these claims

js/packages/cli/test/agentSecurity.test.ts speaks the wire protocol directly, bypassing the CLI, and asserts: no seed retrieval, token minting, lock, shutdown, status or seed injection without the capability; no decrypted index for a read token; no plaintext for a use token; no owner ops via a token; no SEEDPASS_* inheritance in a sink child; correct rejection of non-string credentials; and that tokens do not survive a lock.

If you change the daemon, add the attack to that file first and watch it fail before you make it pass.