cuora

Secrets broker for agents — sealed, not spilled.

Named for the box turtle Cuora — it seals itself with a hinged shell, and so does this. Agents need API keys, but every plaintext handoff is a leak surface: prompts, tool output, logs, .env pasted into configs. cuora removes the handoff — code carries cuora:// references, never values; the CLI materializes secrets as env vars at run time; every materialization emits an audit event — ndjson on stderr, plus OTLP spans when OTEL_EXPORTER_OTLP_ENDPOINT is set.

agent ──► cuora run -- cmd ──► resolve refs ──► inject env ──► child process
                │                                  (agent never sees the key)
                └──► --json everywhere + manifest/schema self-discovery

Quickstart

# the `cuora` command is a tamias pack (libraries/cuora) — a
generated bins[] shim → tamias-driver-cuora → the engine lib.
# From a cuora checkout:
cargo xtask pack                              # stage the driver payload
tamias install --allow-drivers ./libraries/cuora   # deploys `cuora`
# (release path: `tamias bundle pack libraries/cuora` → pinned tgz ref)

cuora init                                   # age identity (keyring, fail closed), once
printf '%s' "$STRIPE_KEY" | cuora put cuora://billing/stripe

# the agent path — the value exists only inside the child
# (one string arg → bash -c, so $STRIPE_KEY expands there)
cuora run -- 'curl -H "Authorization: Bearer $STRIPE_KEY" \
    https://api.stripe.com/v1/charges'

# the human path
eval "$(cuora env -s STRIPE_KEY=cuora://billing/stripe)"

Values never enter via CLI args — put/rotate read stdin or a hidden prompt. cuora get is the escape hatch; prefer run so values never enter agent context.

Verbs

Verb	What it does
cuora init	Generate the age identity (0600) if missing; verify the vault opens
cuora put <ref>	Store a secret — value via stdin or hidden /dev/tty prompt, never args
cuora get <ref>	Print a secret's value (the escape hatch)
cuora list	Refs stored in the selected env — names only, never values
cuora rm <ref>	Remove a secret
cuora rotate <ref>	New value via stdin/prompt; version bump + rotated_at
cuora run [-s VAR=ref] -- cmd	Inject [secrets] + ad-hoc pairs into a child. One arg → bash -c; several → argv exec, no shell
cuora env [-s VAR=ref]	export VAR='…' lines for eval — the human path
cuora check	Validate config, vault readability, declared-surface resolution; exit 1 on findings
cuora serve	ndjson IPC mode for orchestrators — the Vault port over stdin/stdout, optional [serve.pdp] policy consult
cuora deploy <ref>	Push a secret to a write-only sink (e.g. CF Secrets Store)
cuora migrate	Vault migrations — e.g. --private-refs re-keys cf rows to HMAC storage keys
cuora manifest / cuora schema	Machine-readable capabilities / cuora.toml JSON Schema

--json works on every verb (stable shapes in cuora manifest); --env, --config, --actor are global. Audit = ndjson events on stderr: {ts, actor, op, rref?, env, outcome} — one per materialization, denied on guardrail refusal, error on failure.

Interactive browsing lives in pavo, not a cuora TUI: tamias-driver-cuora (built from crates/cuora-driver) answers pavo's manifest/views/view/query wire with vault metadata views — vaults, envs, refs, per-ref detail, check — and never renders secret values (see the crate README).

Config — cuora.toml

Searched at --config → $CUORA_CONFIG → ./cuora.toml → ~/.config/cuora/cuora.toml. cuora schema emits the spec; examples/cuora.toml.example is the commented tour.

[vaults.local]                # the built-in age vault ("local" is implicit)
kind = "age"
# path, identity, recipients  # optional overrides

[vaults.cloud]                # a remote vault (self-hosted Worker + D1)
kind = "cf"
url = "https://cuora-vault.you.workers.dev"
cache = ["dev"]               # optional read-through local cache at
                              # ~/.cache/cuora/ — dev cached, prod live

[envs]                        # env → vault routing; unlisted envs → "local"
prod = { vault = "cloud" }

[secrets]                     # the declared surface run/env may inject
STRIPE_KEY = "cuora://billing/stripe"

[aliases]                     # ref-path prefix → replacement ref —
"tamias" = "cuora://secrets-9aia"   # retired names / namespace moves,
                              # applied at resolve time before lookup

[guardrails]                  # advisory op table — accident prevention,
deny = ["get"]                # not policy (CUORA_ACTOR is self-claimed)

[serve.pdp]                   # `cuora serve`'s external policy decision
exec = "peregrin policy"      # point: request on stdin, verdict on
allow_on_error = false        # stdout; unreachable fails closed

Refs: cuora://ns/name names the secret; --env/CUORA_ENV picks the resolution context (dev default); cuora://prod/ns/name pins the env explicitly. Envs are also the routing axis — same ref, different backend per env.

[aliases] remaps ref paths at resolution time: keys are bare ref paths (quoted in TOML when they contain /), values are cuora:// refs. The longest key that equals the path or prefixes it at a / boundary wins; the target's path replaces the matched segments and any tail is appended — "tamias" = "cuora://secrets-9aia" sends cuora://tamias/registry-token to cuora://secrets-9aia/registry-token, vault or sealed pack. Aliases chain transitively; self-aliases and cycles fail config load. Env pins strip first, so cuora://prod/tamias/x still resolves under prod, and alias materializations audit with an alias_from field naming the requested path.

This is the beginning of the README. Read the rest at the original. Read the full README ↗