Architecture Overview¶
This document develops the three-zone picture from the project overview into the three C4 levels: what the system is in relation to the world, what it is made of, and how the crates relate.
System Context - C4 Level 1¶
Keyspout is a contract-based secret manager. There is no Keyspout service. The only parties are the people who hold keys and the agent processes that consume leased copies.
flowchart TD
Admin["Admin principal<br/>the account that holds the signing key<br/>and her own sealed vault"]
User["Principal<br/>the enrolled user<br/>holds a vault sealed to her own key"]
Agent["Agent process<br/>an LLM-driven tool or script<br/>holds its own Ed25519 and X25519 keys"]
subgraph External["External systems - all operator-owned"]
FS["File store<br/>a local directory<br/>or a network filesystem"]
VK["Valkey<br/>a Redis-protocol server"]
S3["S3-compatible object store"]
SCHED["Scheduler<br/>launchd, cron or a timer unit<br/>runs the sweep"]
end
Admin -->|"enrols, publishes, signs and withdraws grants"| KEYSPOUT
User -->|"reads her own records, exports a grant token"| KEYSPOUT
Agent -->|"opens a publication, or consumes a leased copy"| KEYSPOUT
KEYSPOUT -->|"stores ciphertext and audit records"| FS
KEYSPOUT -->|"stores ciphertext"| VK
KEYSPOUT -->|"stores ciphertext"| S3
SCHED -->|"invokes the sweep"| KEYSPOUT
The trust boundary is the store. Keyspout holds no service, so the store is the only thing an attacker needs to reach. Everything the store holds is sealed to a named key, and the audit chain is signed by the writer.
One deployment holds one vault and N principals. The admin and the users are separate UNIX accounts behind filesystem permissions, and they are not interchangeable: the admin signs grants and cannot read a user's records, the user reads her own records and cannot sign. A grant is the one object that crosses between them - the admin signs it, the user exports the token it authorised, and the agent opens the publication it names.
The scheduler is configuration, not trust. A schedule decides when the sweep runs. Whether it did run is answered by a signed proof the sweep writes, and a lease is admitted only against a fresh proof.
Container Architecture - C4 Level 2¶
There is exactly one deployable container: the ksp binary. It is invoked in
the foreground, does one job and exits. The other containers are the store and
the operator's own machine.
flowchart TD
Client["Operator or agent shell"]
subgraph Host["The operator's host"]
BIN["ksp binary<br/>Rust, single executable<br/>clap CLI, dispatch, output"]
end
subgraph Storage["The sealed store"]
BLOBS[("Record blobs<br/>file, valkey or s3<br/>HPKE-sealed ciphertext")]
ARMS[("Arm records<br/>signed deletion intents<br/>create-only")]
AUDIT[("Audit chain<br/>per-writer append-only segments")]
PROOFS[("Sweep proofs<br/>signed evidence a sweep ran")]
PUBS[("Publications<br/>granted level under the admin<br/>one sealed entry per grant")]
EDGES[("Policy edges<br/>signed grants and their decisions<br/>policy-events.jsonl")]
end
subgraph Keys["Key material - never in the store"]
ADMINKEY["Admin signing key<br/>owner-only file<br/>cannot decrypt"]
USERKEY["User key pair<br/>owner-only file<br/>vault key is sealed to it"]
AGENTKEY["Agent key pair<br/>owner-only file<br/>on the agent's host"]
end
Client -->|"one invocation"| BIN
BIN -->|"seals the blobs, arms before publishing,<br/>signs grants and publications,<br/>appends the signed records,<br/>writes a proof after a sweep"| Storage
BIN -->|"reads the keys"| Keys
Storage ~~~ Keys
Host ~~~ Storage
Three properties of this diagram are load-bearing:
- The admin key cannot decrypt. It is an Ed25519 signing key only. There is no code path that converts it to an X25519 key.
- The store never holds a private key. It holds ciphertext, signed intents and signed audit records. Every private half lives in an owner-only file on a host the operator chose.
- The proof directory is outside the store. A reader must be able to reach a proof without entering the store's level hierarchy, because a proof is what authorises a lease.
Component Architecture - C4 Level 3¶
Eight crates. The CLI is the only place they are wired together.
graph TB
subgraph CLI["ksp - the CLI and application layer"]
direction TB
COMMANDS["commands.rs<br/>the clap tree"]
APP["app.rs<br/>dispatch and per-group handlers"]
OUTPUT["output.rs<br/>Report enum, text and JSON rendering"]
EXIT["exit.rs<br/>the exit-code contract"]
RUN["run.rs and run_gate.rs<br/>verify, confine, launch"]
CONSUME["consume.rs<br/>deliver, delete, journal, report"]
GRANT["grant.rs<br/>create, update, withdraw"]
EDGESTORE["edges.rs<br/>the signed grant store"]
PUBLICATION["publication.rs<br/>the fourth level"]
POLICYVIEW["policy_view.rs<br/>the join every read surface prints"]
LEDGERS["ledgers.rs<br/>issuance and policy events"]
ADMIN["admin.rs<br/>the admin vault and the admin's own writes"]
COMMANDS --> APP
APP --> OUTPUT
APP --> EXIT
APP --> RUN
APP --> GRANT
APP --> ADMIN
RUN --> CONSUME
GRANT --> EDGESTORE
GRANT --> PUBLICATION
GRANT --> LEDGERS
POLICYVIEW --> EDGESTORE
POLICYVIEW --> PUBLICATION
end
subgraph IDENTITY["ksp-identity - who is speaking"]
direction TB
ENROL["enrolment.rs<br/>fingerprint-bound enrolment, rotation"]
POP["pop.rs<br/>proof of possession, argv hash, time buckets"]
DELIV["delivery.rs<br/>sealed delivery artifact"]
POLICY["policy.rs<br/>policy, trust anchors, verification"]
EDGE["policy_edge.rs<br/>one grant as a signed edge"]
MINT["mint.rs<br/>arm, then publish"]
ISSUANCE["issuance.rs<br/>the issuance ledger"]
ENROL --> POP
ENROL --> DELIV
ENROL --> POLICY
POLICY --> EDGE
ENROL --> MINT
MINT --> ISSUANCE
end
subgraph RECORD["ksp-record - record cryptography"]
direction TB
ENV["envelope.rs<br/>the HPKE envelope"]
KEM["kem.rs<br/>the KEM validation gate"]
VERSION["version.rs<br/>immutable versions, conditional head"]
PATH["path.rs<br/>the one record path definition"]
ENV --> KEM
VERSION --> PATH
end
subgraph STORAGE["ksp-backend - the store"]
direction TB
FILE["file.rs<br/>the local filesystem store"]
VALKEY["valkey.rs<br/>the Redis-protocol store"]
S3["s3.rs<br/>the object store"]
ADMISSION["admission.rs<br/>evidence-based classification"]
ARMING["arming.rs<br/>durable, create-only arm records"]
PROOF["proof.rs<br/>the signed sweep proof gate"]
SWEEP["sweep.rs<br/>the foreground sweep"]
ADMISSION --> PROOF
PROOF --> SWEEP
ARMING --> SWEEP
end
subgraph EVIDENCE["ksp-deletion - what is known"]
direction TB
INTENT["intent.rs<br/>the signed, key-free intent"]
REPORT["report.rs<br/>the actor's signed report"]
OBSERVE["observation.rs<br/>the absence observation"]
JOURNAL["journal.rs<br/>the acknowledgement journal"]
AUDITCHAIN["audit.rs<br/>the per-writer chain"]
JOURNAL --> AUDITCHAIN
end
subgraph HOST["ksp-posture - what the host can do"]
direction TB
CONF["confinement.rs<br/>Landlock path confinement"]
BARRIER["barrier.rs<br/>memfd_secret, mlock"]
DESC["descriptors.rs<br/>descriptor sanitation"]
RESOLVE["resolver.rs<br/>which adapter runs"]
CONF --> RESOLVE
BARRIER --> RESOLVE
DESC --> CONF
end
CLI ~~~ IDENTITY
IDENTITY ~~~ RECORD
RECORD ~~~ STORAGE
STORAGE ~~~ EVIDENCE
EVIDENCE ~~~ HOST
The diagram stacks the crates in dependency order, and the chain edges are the dependency edges. The edges within a crate are the ones that matter inside it.
The grant path is the newest seam, and it is the only one that writes into two
places whose owners differ: the edge is a signed artifact at the admin's
principal, and the publication is a sealed entry in the fourth level beside
it. grant.rs owns the order - ledger, artifact, publication, token - and
policy_view.rs owns the join that every read surface prints. A read never
re-derives the order; it calls the same join the write used.
Three cross-crate calls are worth naming, because the diagram's chain cannot show them without becoming unreadably wide:
ksp-identitycallsksp-record, to seal a delivery. The delivery seal usesksp-record's HPKE adapter, so the low-order-point rejection is one implementation and not a second copy.ksp-identitycallsksp-backend, because the mint path needs the admission decision and the arming store. The dependency does not run the other way.ksp-backendcallsksp-deletion, because the sweep must journal its acknowledgement and write its report. Deletion does not depend on the backend.crates/kspreadsksp-identity's edge type rather than re-declaring it, so the artifact the admin signs and the artifact a verifier reads are one definition. The target, the identifier and the canonical encoding live in the identity crate; the store, the publication and the token live in the CLI.
A diagram that draws every edge is not a diagram that can be read; these three are the ones a reader would otherwise have to read the source for.
Architectural Patterns¶
A contract with three opaque methods¶
The storage backend is a contract, not a plugin host. A backend implements three opaque operations - put, get, delete - and Keyspout adds the parts that make a lease safe: admission, arming and sweeping. The backend never learns what it is storing.
Why it matters: a backend that understood keys or policy would become a
trust decision it has no business making. The s3 backend cannot tell the
difference between "expired" and "not yet expired"; Keyspout decides that
outside the backend, from evidence.
Evidence, not declaration¶
This is the pattern the whole system is built around, and it appears in three places:
| Domain | Declaration (not evidence) | Evidence |
|---|---|---|
| Backend expiry | A configured lifecycle rule, a declared sweep interval | A signed, fresh sweep proof |
| Host confinement | A configured adapter order | The adapter that ran and the guarantee it established |
| Deletion | An intent that authorises an attempt | An actor's signed report, or an absence observation |
The rule is the same each time: a declaration is not evidence. The code says so in a comment at the point where the distinction is decided.
Arm before publish¶
A lease is published only after its deletion intent is durably recorded. The mint path is a two-step sequence with no atomic transaction between them, and the sequence is deliberately ordered so the failure mode is safe: an uncertain arming publishes no token.
Trade-off: there is a window in which a record exists with no token. The sweep finds it and removes it. The opposite ordering would publish a token whose cleanup was never armed.
One grant is one signed edge¶
A policy used to be one document naming a set of grants, so a write rewrote the
whole set and two writers raced on one file. A grant is now its own artifact: a
PolicyEdge names one (user, secret, version, target), carries a revision and a
validity window, and is signed by the admin. A write adds one, and --replace is
the only operation that touches the others.
The consequence is that read-back works on one grant at a time. admin policy
show prints the edge, its verification, its tokens, the agent's keys, the
publication it names and the withdrawal that ended it - and a grant whose
publication is missing reads dangling rather than active. A join that
reported health for a grant that cannot deliver would be the read surface lying
about the write surface.
Publish the reference, never the value¶
A leased copy is a real record at the agent's level: a fresh content key, a sealed blob, an arm record and a deadline. It is deletable because it exists. A grant delivers something else - one artifact under the admin's principal, and a token that names it and carries no key.
The artifact holds the blob once and its content key twice: sealed to each grant's target, and sealed to the admin vault so a second grant against the same publication recovers the key instead of re-sealing the blob. Neither seal travels in the token, which is why exporting one needs no password: there is nothing in it to unlock.
That is why the two deliveries have different verbs. secret share --agent
mints a copy and needs the vault; secret share --policy exports a token and
needs nothing, because the agent opens the publication with its own recipient
key. And it is why --consume is refused for a policy token: there is no copy
to delete, and pretending otherwise would delete nothing while reporting
success.
One output point¶
Every command's result is a Report variant. The JSON form and the text form
are two renderings of the same value, so they cannot disagree.
Why it matters: the output shape is the redaction boundary. There is no
Report variant that carries a plaintext value, so a secret cannot reach the
audit path or a JSON response without someone adding a variant that does. The
one command that must print a value - secret get --reveal - deliberately
bypasses Report and builds its own document, so the exception is visible in
one place.
Fail closed, disclose honestly¶
Every check in the key and permission paths fails closed. And every disclosure distinguishes three things that are easy to conflate:
- a capability that was not selected,
- a capability that was selected but unavailable, with the host's reason,
- a capability that was selected and established, with its guarantee level.
A host that enforces nothing says none. It does not go quiet.
Key Design Decisions¶
1. No service, no daemon, no session¶
Every operation is one foreground invocation.
- Rationale: a secret manager with a long-lived process is a secret manager with a long-lived attack surface. There is no session to lock, no unsealed vault to keep in memory between commands, and no socket to authenticate.
- Trade-off: every command re-derives its context, re-reads its configuration and re-unseals what it needs. It costs milliseconds and buys the absence of a resident secret.
2. Independent Ed25519 and X25519 pairs¶
Every agent and every user has a signing key and a recipient key, generated separately. They are never derived from one another.
- Rationale: a single key pair serving both roles means a signing
compromise becomes a decryption compromise. The distinct Rust types make the
substitution a compile error, enforced by
compile_faildoctests. - Trade-off: two keys per identity to store, back up and rotate.
3. Confinement is separate from authentication¶
Landlock restricts paths. A signature establishes which key is speaking. The two are independent controls and the code keeps them in separate crates.
- Rationale: conflating them produces a system where a signature inside the confined tree could be forged, or where confinement is assumed to imply authorisation.
- Trade-off: a run must do both, and the failure modes are reported separately so a reader can tell a confinement refusal from a signature refusal.
4. Best-effort deletion, stated as such¶
The sweep removes a record. It does not erase a copy that was taken earlier.
- Rationale: the research is unambiguous - a saved key/ciphertext pair cannot be recalled, and neither deletion nor a cryptographic primitive invalidates a copy already in someone else's hands. A system that promised otherwise would be lying about its own guarantees.
- Trade-off: the guarantee is weaker than operators expect from "secret with an expiry". The documentation compensates by stating it everywhere.
5. Arming is create-only¶
An arm record is written once. A retry with the same identity finds the existing record and continues; it never replaces it.
- Rationale: the arm record's identity is the idempotency key. Replacing it would let a second mint for the same lease replace the first lease's cleanup authorisation.
6. The use counter lives inside the signed preimage¶
The remaining-uses counter is signed as part of the arm record, not stored next to it.
- Rationale: a counter outside the signature could be raised by anyone who can write the journal. Inside the preimage, raising it requires the private key.
7. macOS is supported with a smaller guarantee¶
The workspace builds and the suite runs on Darwin. macOS provides no path
confinement and no memfd_secret.
- Rationale: refusing macOS would exclude a large share of the operators who would use this. Reporting a smaller guarantee honestly is better than either pretending or refusing.
- Trade-off: on macOS the confinement capability is reported as
noneand the child runs unconfined, in its own output as well as inksp status. The barrier falls back tomlock, reported asweakened.
Module Breakdown¶
ksp - the CLI and application layer¶
- Purpose: the foreground entry point; owns the command surface, the exit codes, the output shapes and the redaction rule.
- Key components:
commands.rs(the clap tree),app.rs(dispatch),output.rs(rendering),exit.rs(the exit-code contract),run.rsandrun_gate.rs(verify, confine, launch),consume.rs(deliver, delete, journal, report),layout.rs(the protected-root table),establish.rs(adapter selection). - Dependencies: all seven other crates.
- Deep dive: ksp - the command-line interface
The crate gained the grant path in feature 014, and the files are worth naming because the order between them is the control:
grant.rs- create, update and withdraw. One ordering: the ledger entry, then the artifact, then the publication, then the token. A withdrawal records the decision before it removes anything, so a retry can finish it and an operator can tell a withdrawn grant from one that never existed.edges.rs- the signed-edge store. It verifies the issuer against the pinned anchor on every load, so a grant this host cannot attribute is absent rather than trusted.publication.rs- the fourth level: one derived path per (vault, admin, secret, version),0750directories, a sealed entry per policy and a reference set that keeps an entry alive while any grant names it.policy_view.rs- the join. Every surface that renders a grant calls it, including the write commands' read-back, so a write cannot describe itself differently from how a reader prints it.lifecycle.rs- the record-then-write transaction over the admin ledger.admin.rs- the admin vault (seal-vault), the admin's own record writer (put --own) and the transfer to a user. Two verbs, one key decision: which recipient the record is sealed to.registry.rsandagent_index.rs- who is in the deployment, and which agent identities a principal has published. Both are public material: the registry names principals and their public halves, never a private one.ledgers.rs- the two ledgers and their owners:issuance.jsonlfor the principal,policy-events.jsonlfor the admin, each with one writer.
ksp-identity - who is speaking¶
- Purpose: enrolment, key pairs, proof of possession, policy verification, sealed delivery and the mint sequence.
- Key components:
enrolment.rs,fingerprint.rs,pop.rs,delivery.rs,policy.rs,mint.rs,issuance.rs,key_bundle.rs. - Dependencies:
ksp-types,ksp-record,ksp-backend. - Deep dive: ksp-identity
policy_edge.rs is feature 014's other half: the PolicyEdge type, the
canonical target (agent:<uuid> or the cooperative any-enrolled), the
identifier that names a path, and the digest that binds a ledger entry to the
exact bytes the admin signed. The CLI stores and publishes it; the identity crate
defines what it means.
ksp-backend - the store and its admission¶
- Purpose: the three storage backends, evidence-based admission, durable arming and the foreground sweep.
- Key components:
file.rs,valkey.rs,s3.rs,admission.rs,arming.rs,proof.rs,sweep.rs,sweeper.rs,usbound.rs. - Dependencies:
ksp-types,ksp-record,ksp-posture,ksp-deletion. - Deep dive: ksp-backend
ksp-posture - what the host can enforce¶
- Purpose: state, before a run, what the host can actually enforce - path confinement, descriptor sanitation and a memory barrier - and report both facts honestly.
- Key components:
confinement.rs,barrier.rs,memlock.rs,descriptors.rs,permissions.rs,rights.rs,resolver.rs,adapters/. - Dependencies:
ksp-typesonly. - Deep dive: ksp-posture
ksp-deletion - what is actually known¶
- Purpose: keep deletion evidence apart from deletion knowledge: a signed key-free intent, an actor's signed report, an absence observation, a durable acknowledgement journal and the per-writer audit chain.
- Key components:
intent.rs,report.rs,observation.rs,journal.rs,audit.rs,consume.rs,signing.rs,verify.rs. - Dependencies:
ksp-typesonly. - Deep dive: ksp-deletion
ksp-record - record cryptography¶
- Purpose: the KEM validation gate, the bound context, the content blob, the HPKE envelope and conditional publication.
- Key components:
envelope.rs,blob.rs,kem.rs,path.rs,version.rs,provider_guard.rs. - Dependencies:
ksp-types. - Deep dive: ksp-record
ksp-types - the shared vocabulary¶
- Purpose: the identifiers, encodings, domain strings and evidence structures that subsystems must agree on byte for byte. No behaviour, no policy, no I/O.
- Key components:
metadata.rs,cbor.rs,domains.rs,evidence.rs,capability.rs,capability_config.rs,content_key.rs,shamir.rs. - Dependencies: none internal.
- Deep dive: ksp-types
ksp-key-lifecycle - the durable key file¶
- Purpose: keep one enrolled identity available across foreground invocations, without giving the CLI raw private keys.
- Key components:
file.rs(the filesystem mechanics) and theKeyStoreinlib.rs. - Dependencies:
ksp-types,ksp-identity. - Deep dive: ksp-key-lifecycle
The Layout Table¶
The protected roots are one table, not a set of per-call-site modes. Creation reads the table; measurement compares against it. Each row carries the mode and the reason it is not more open.
| Path | Mode | Why it is not more open |
|---|---|---|
$KSP_HOME |
0711 |
Non-owners traverse known paths but cannot enumerate the deployment |
admin/ |
0700 |
Holds the admin signing identity |
agent/ |
0700 |
Holds agent key bundles; a sibling account must not read them |
enrolments/ |
0755 |
Public pins a reload is verified against; readable without a key file |
store/ |
0755 |
Traversable by every principal; each level carries its own owner |
store/intents/ |
1770 |
The arm journal; the sticky bit keeps a sibling from removing a record it did not write |
sweeper/ and sweeper/proofs/ |
0755 |
One writer, every principal a reader: a proof authorises a lease |
audit/ |
0711 |
Append-only writer segments; another principal must not rewrite them |
journal/ |
0700 |
This host's own deletion acknowledgements |
admin-anchor.cbor, deployment.cbor |
0644 |
Public material every principal must read |
vault.cbor |
0600 |
The sealed vault; readable only by its owner |
policy.cbor |
0644 |
Signed policy; replaceable only with the admin key |
admin-vault.cbor |
0600 |
The key every publication entry's content key is sealed to |
issuance.jsonl, policy-events.jsonl |
0640 |
One writer each; a ledger a third party can rewrite is a mint history that party can forge |
store/p/<vault>/ |
0711 |
The vault's principals: nameable, not enumerable |
store/p/<vault>/<principal>/ |
0711 |
One principal's root; the levels beside it are hers |
principals.cbor |
0644 |
The registry: names and public halves, nothing private |
level user/ |
0700 |
One principal's records |
level admin/ |
0700 |
The admin's own records, sealed to her vault |
level agent-<id>/ |
0730 |
The sweep group may unlink a copy it cannot list |
level granted/ |
0750 |
The publication a grant delivers from: the store group reads it, nobody else |
level policies/ |
0755 |
The token a grant minted is 0640 inside it, so the user exports what the admin wrote |
Two rows deserve attention:
store/intents/is1770, sticky. A group member who can rewrite the journal can forge a history: appending a revocation is how a token stops working, and removing one is how it starts again. The sticky bit keeps a sibling from removing a record it did not write.- A level directory
fsyncneeds read permission. The arm journal is group-writable and world-readable precisely because a write-only journal cannot acknowledge durability.
See Also¶
- Workflow Overview - the eight workflows, step by step
- Deep Dive: ksp - the command-line interface
- Design specification