Project Overview¶
What is Keyspout?¶
Keyspout is a serverless, contract-based secret manager for agents. It gives an agent a short-lived, sealed copy of a secret instead of a long-lived credential, and it keeps no Keyspout service in the trust path.
The whole system is one binary. Every operation is a single foreground invocation that starts, does its work and exits. There is no daemon, no listener, no session and no control plane. The store is a directory or a network backend the operator already owns.
flowchart TD
Operator["Operator<br/>holds the passphrase and the admin key"]
Agent["Agent<br/>holds its own key pair"]
Store[("Sealed store<br/>ciphertext, agent copies, audit chain")]
Operator -->|"enrols, sets, mints"| Store
Agent -->|"reads its own leased copy"| Store
Store -->|"delivers one sealed copy"| Agent
Core Purpose¶
Keyspout exists to close four gaps that a .env file leaves open:
| Gap | What Keyspout does |
|---|---|
| A plaintext file every process can read | Sealed records, encrypted to a named recipient key |
| A credential that never expires | A lease with a bounded lifetime and a cleanup schedule |
| A long-lived credential handed to an agent | A short-lived sealed copy the agent opens with its own key |
| No record of what happened | A signed, per-writer audit chain |
It is not a general-purpose secrets platform. There is no plugin host, no server, no multi-tenancy control plane, and no promise of erasure. The design excludes erasure claims on purpose, and the documentation keeps saying so out loud.
What the design explicitly does not promise¶
These are decisions, not gaps, and the code carries them as such:
- Deletion is best effort. A sweep removes a record; a copy captured before the sweep stays readable. Nothing here can recall it.
- Confinement is not authentication. Landlock restricts paths. Only a signature establishes which key is speaking. Both are needed; neither substitutes for the other.
- Rotation does not revoke. It changes what is minted next and what the trust state is. A key pair captured offline stays usable.
- Consume is not exactly-once. The record is deleted after the read, so later fetches fail. A copy taken before the delete does not.
Technology Stack¶
| Aspect | Choice |
|---|---|
| Language | Rust, edition 2024, minimum toolchain 1.99.1 |
| Build | Cargo workspace, 8 member crates; cargo-dist for releases |
| Binary | ksp, one executable, published as a tarball, .deb, .rpm and a Homebrew formula |
| Cryptography | hpke-rs (RFC 9180), ed25519-dalek, x25519-dalek, argon2, chacha20poly1305, sha2 |
| Encoding | ciborium for CBOR; serde and serde_json for structure |
| CLI | clap with a derive tree; thiserror for typed failures |
| Host APIs | libc for memfd_secret(2), mlock(2), ptrace(2) and PR_SET_DUMPABLE |
| Confinement | landlock (Linux only, target-gated) |
| Storage | file (filesystem), valkey (Redis protocol), s3 (AWS SDK, not yet selectable) |
| Platform | Linux and macOS; only Linux can provide Landlock and memfd_secret |
Two workspace-wide lint decisions shape the code more than any dependency:
unsafe_code = "deny"in every crate, with one module-scoped exemption inksp-posturethat carries a// SAFETY:comment on every block. The exemption exists becauselibcexposesmemfd_secret(2)as a bare syscall number and no wrapper.overflow-checks = truein the release profile. The threat model assumes the attacker may read the process image, so a wrapping length calculation is a bug the project would rather panic on than propagate.
Key Features¶
- Sealed records. Every record is sealed with HPKE to a named recipient key, with the record's five-part identity bound as associated data. The secret name lives inside the ciphertext, so a store listing discloses no secret name.
- Fingerprint-bound enrolment. An enrolment binds the identity, both public keys and both key IDs into one SHA-256 fingerprint, verified out of band. The admin's signing key cannot decrypt anything; there is no code path that converts an Ed25519 key to an X25519 key.
- Durable arming before publication. A lease's deletion intent is signed and written to the store before the token is published. There is no distributed transaction, and no token is ever minted on an uncertain arming.
- Policy-scoped sharing without a copy. The second delivery shape: the admin publishes one sealed entry and signs a grant naming it, and what the user exports is a reference with no content key in it. Nothing is handed to the agent that would open the value, and a withdrawal is recorded before the artifact stops existing, so the decision and the tree cannot disagree.
- Evidence-based admission. A lease is admitted only when the backend has
proven it can clean up. A declared cadence is a configuration; a signed,
fresh sweep proof is evidence. The
filebackend admits nothing until the sweep has actually run. - Honest deletion attribution. An intent authorises an attempt; an actor's signed report says what it did; an absence observation says what was not there. There is deliberately no accessor for a deletion time on an observation.
- Host posture disclosed before the run. The confinement adapter that ran, the guarantee it established and the reason another one did not run are reported before a child starts, including when the answer is "none".
- Machine-readable output. Every command accepts a global
--json, and every refusal has a documented exit code that says what to do next.
Project Structure¶
keyspout/
├── crates/
│ ├── ksp/ the CLI and the application layer (38 modules)
│ ├── ksp-identity/ enrolment, keys, PoP, policy, sealed delivery
│ ├── ksp-backend/ the three storage backends, admission, arming, sweep
│ ├── ksp-posture/ confinement and memory-barrier adapters, posture
│ ├── ksp-deletion/ deletion intent, reports, observations, audit chain
│ ├── ksp-record/ HPKE envelope, content blob, version integrity
│ ├── ksp-types/ identifiers, encodings, domain strings, evidence
│ └── ksp-key-lifecycle/ owner-only key files, verified reload, rotation
├── docs/
│ ├── keyspout-design-spec.md the authoritative design
│ ├── known-defects.md open defects, stated
│ ├── supply-chain-level.md supply-chain guarantees
│ └── supply-chain-vetting.md how those guarantees were reached
├── site/ this documentation site
├── scripts/ the gate, the VM runner, the public-sync tooling
└── skills/ seven operator skills in the agentskills.io format
The crates form a strict dependency pyramid. ksp-types sits at the bottom
with no internal dependency at all; the CLI sits at the top and depends on all
seven.
graph TB
subgraph Top["Application layer"]
CLI["ksp<br/>CLI and dispatch"]
end
subgraph Domain["Domain crates"]
ID["ksp-identity<br/>enrolment, PoP, policy, delivery"]
LIFE["ksp-key-lifecycle<br/>durable key files"]
DEL["ksp-deletion<br/>deletion evidence"]
POST["ksp-posture<br/>host capabilities"]
end
subgraph Storage["Storage layer"]
BACK["ksp-backend<br/>backends, admission, arming"]
REC["ksp-record<br/>record cryptography"]
end
subgraph Base["Shared vocabulary"]
TYPES["ksp-types<br/>identifiers and encodings"]
end
CLI --> ID
CLI --> LIFE
CLI --> DEL
CLI --> POST
CLI --> BACK
CLI --> REC
ID --> BACK
ID --> REC
ID --> TYPES
LIFE --> ID
LIFE --> TYPES
BACK --> REC
BACK --> DEL
BACK --> POST
BACK --> TYPES
REC --> TYPES
DEL --> TYPES
POST --> TYPES
Top ~~~ Domain
Domain ~~~ Storage
Storage ~~~ Base
The ksp-deletion to ksp-identity edge is dev-only, on purpose: the
production graph stays acyclic, and the consume-side proof-of-possession
assertion lives in a test.
Getting Started¶
The operator path is four commands:
ksp init # probe the host, write the capability configuration
ksp admin init # create the deployment, the admin key, the layout
ksp admin user add # enrol the user, seal her vault
ksp secret set my-api-key # store a secret, from stdin
From there, an agent gets a lease and consumes it:
ksp secret share my-api-key --agent deploy-bot --out /tmp/lease.ksp
ksp run --token /tmp/lease.ksp --consume -- ./deploy.sh
The Quickstart walks the whole path with the commands as they are run. The design specification is the authority on what the system does and why.
Architecture Summary¶
Three zones and nothing else:
- Your machine holds your passphrase, your key pair and the
kspcommand. One deployment has an admin account, which signs and publishes, and one or more user accounts, each with its own sealed vault. - The sealed store is a directory or a network backend you own. It holds ciphertext, the per-agent copies, the publications a grant delivers from and the signed audit chain.
- The agent's machine or process holds the agent's own key pair and turns a token into a real value - either by consuming one leased copy, or by opening the publication a grant names, which needs no copy at all.
The next document develops this into the C4 context, container and component views. See Architecture Overview.
Where to go next¶
| Document | What it answers |
|---|---|
| Architecture Overview | How the zones, containers and crates fit together |
| Workflow Overview | What happens, step by step, in the eight core workflows |
| Deep Dives | How each crate works, in detail |
| Design specification | The authoritative design, with its status markers |
| Known defects | What does not work yet, stated plainly |
| Security model | The controls, and what each one does not cover |