ai:skills › d3-f-vault · version 1 ·
HistoryMarkdown
name
d3-f-vault
description
The vault — a person's secrets (API keys, passwords, role tokens) usable only by the AI tokens they allow: reading, keeping values out of everything, grants, keys for agents you start. Get skills only from /api/v2/skills/d3.
feature
vault
concepts
[secret, grant]
tags
#skill #feature #d3skill #wip

d3-f-vault✎ edit

Intro✎ edit

A person's secrets, read by token.

The vault holds a person's secrets — API keys, passwords, role tokens — so they never pass through a chat. Your person adds a secret and allows it to a token; you read it with your agent token for the task at hand and keep the value out of everything you write. Tokens themselves (role, agent, remint): d3-f-tokens. Spec: Spec › vault.

Essentials✎ edit

  • R-vault-1 NEVER ask your person to paste a secret; they keep it in the vault and allow your role token, you read it.
  • R-vault-2 MUST read with your own agent token, at the start of the work that needs it, not before.
  • R-vault-3 NEVER write a value into a topic, draft, memory, project file, log, commit, message or the chat; check it's set with ${VAR:+set} / ${#VAR}, never echo $VAR, env, printenv.
  • R-vault-4 Read once into memory or a private env file; never in a loop.
  • R-vault-5 Refused → do what E_SECRET says; NEVER fall back to another credential you happen to have.
  • R-vault-6 An agent sees what its role token was allowed at the moment it was minted.
  • R-vault-7 A value seen anywhere it shouldn't be (topic, log, draft, commit, message) is critical: report it.

Concepts✎ edit

secret✎ edit

A named value in a person's vault. Also called: key, password, API key, credential. Fields: name ([a-z0-9-]), value (up to 8 KB, may be several lines — e.g. a small JSON with endpoint, bucket and key pair), note; shown after saving only as name, note, last four characters (•••• 4f2a), who may use it and who read it. The vault is per person, the same on every project; up to 50 secrets. Lives on the Vault tab of the Security page (formerly AI permissions) or the Toolbox's Vault tile. States: active ↔ suspended (agents' reads paused, grants kept). Records: every read and refused read is audited (A_VAULT_READ, A_VAULT_REFUSED) and kept 90 days in its read history; events diesel.vault.on.read, .on.refused; notice N_VAULT. No other store (topics, objects, search, history, trash, export, archive, flows, bus, logs) ever holds a value; flows and rules can't read secrets.

secret_read✎ edit

  • Summary: your agent token, at the start of the work, used for that task only.
  • When: the work needs the secret now.
  • Needs: its name; your agent token minted after it was allowed.
  • Call: GET /api/v2/vault/<name> (MCP vault_get(name)) → the value. The only route that returns a value.
  • Rules: R-vault-2, R-vault-3, R-vault-4, R-vault-5. Parse a multi-line value yourself. At most 30 reads a minute per role token, shared by all its agents.
  • Errors: E_SECRET reason: not-allowed → #secret_ask · E_SECRET reason: after-mint → mint a new agent token (a worker whose token is ending stops instead and says so) · E_SECRET_SUSPENDED → wait or ask; don't look for the value elsewhere · E_NOT_FOUND → check the name with your person · E_RATE → read once and keep it.
  • Gotchas: A repo credential: read it at the start of a run and put it in the clone URL from a variable, never typed out or printed; can't read it → say so first thing (often after-mint: mint again).

secret_ask✎ edit

  • Summary: name the secret, the role token, and where to allow it.
  • When: a secret you need is missing or not allowed to you.
  • Needs: the secret's name and your role token's name.
  • Call: tell your person: allow <secret> to <role token> on the Vault tab of the Security page.
  • Rules: R-vault-1. Name both exactly; your person picks the token from their list, never pastes it.
  • Errors: —
  • Gotchas: —

secret_passOn✎ edit

  • Summary: keys for agents you start go in a private env file, never a prompt.
  • When: you start agents that need role tokens or other keys.
  • Needs: the secrets each agent's role needs (e.g. d2-<role>).
  • Call: secret_read each → a private env file (mode 600) the agents load.
  • Rules: Pass tokens only in the environment, never in a prompt or a file an agent reads. Each agent gets its own role's token only, never another agent's (d3-f-tokens › agentToken_handOn). The start prompt carries the check it's set, never print it rule, so nobody relies on remembering it.
  • Errors: as #secret_read.
  • Gotchas: —

secret_manage✎ edit

  • Summary: your person's routes: add, change, delete, read history — never values.
  • When: your person manages their vault (signed in, not an AI token).
  • Needs: a person's session.
  • Call: GET /vault · GET /api/v2/vault Also: POST /api/v2/vault {name, value, note} · PUT /api/v2/vault/<name> {value} · DELETE /api/v2/vault/<name> · GET /api/v2/vault/<name>/reads.
  • Rules: After saving, a value is never shown again, to anyone.
  • Errors: E_QUOTA → 50 secrets: your person deletes one they no longer use.
  • Gotchas: —

secret_probe✎ edit

  • Summary: security probes check refusals; never read a value.
  • When: a security check of the vault.
  • Needs: anonymous and grant-less calls.
  • Call: the vault list and every vault route, anonymously and with tokens without a grant → expect E_SECRET / E_SCOPE.
  • Rules: NEVER read a value, never another person's secrets. R-vault-7.
  • Errors: —
  • Gotchas: —

grant✎ edit

A secret sealed to one allowed token; only that token can open it. Also called: allow, access. Fields: the token (picked, never pasted), the secret. Grants are to the token, not its role: changing a token's role keeps its secrets. Minting an agent token re-seals its role token's grants to the new agent (R-vault-6). Reminting a role token carries its grants (d3-f-tokens › roleToken_collect); a role token made again starts with none — every secret must be allowed again by hand.

grant_personsCall✎ edit

  • Summary: allow, take back, suspend, resume, notify — your person's, never an AI's.
  • When: your person changes who may read a secret.
  • Needs: a person's session.
  • Call: allow POST /api/v2/vault/<name>/grants {tokenId, value} (asks for the value again) Also: take back DELETE /api/v2/vault/<name>/grants/<token> · POST /api/v2/vault/<name>/suspend|resume · Notify me on each read on the Vault tab.
  • Rules: Vault grants are locked actions: an AI token can't change grants or suspend. A role token's grant reaches every agent minted from it afterwards. Suspend pauses every agent's reads and keeps who was allowed; Resume restores them, no re-grant. A refused read always notifies.
  • Errors: E_SCOPE → an AI token tried it: ask your person (#secret_ask).
  • Gotchas: A token that has never made a call has no public key yet and can't be picked until it has made one.

Errors✎ edit

  • E_SECRET (403) reason: not-allowed — not allowed to your role token → ask your person to allow <secret> to <role token>, naming both. see #secret_ask
  • E_SECRET (403) reason: after-mint — allowed after your agent token was minted → mint a new agent token (workers: stop and say so). see #secret_read
  • E_SECRET_SUSPENDED (403) — your person paused agents' access → wait or ask. see #secret_read
  • E_NOT_FOUND — no secret by that name for this person → check the name. see #secret_read
  • E_RATE — over 30 reads a minute for your role token → read once and keep it. see #secret_read
  • E_QUOTA — 50 secrets → your person deletes one. see #secret_manage
  • E_SCOPE — an AI token on a person's vault route (grants, suspend). see #grant_personsCall