Workflow Overview¶
Every workflow below is a sequence of foreground invocations. Nothing runs in the background except the sweep, and the sweep is a batch job the operator's own scheduler starts.
Core Workflows¶
Workflow 1: Enrol a user and an agent¶
The operator creates the deployment, enrols the user, enrols the agent, and then grants the agent permission to read one secret. This is the setup phase and it happens once per principal.
sequenceDiagram
participant Op as Operator
participant Ksp as ksp binary
participant Store as Sealed store
participant FS as Host filesystem
Op->>Ksp: ksp init
Ksp->>FS: probe the host, write config.toml
Op->>Ksp: ksp admin init --vault main --user alice
Ksp->>FS: create the protected roots from the layout table
Ksp->>FS: generate the admin signing key, owner-only
Ksp->>FS: write the pinned anchor and the deployment record
Op->>Ksp: ksp admin user add --unix-user alice
Ksp->>FS: seal the user vault to her key pair
Ksp->>Store: write the enrolment record
Op->>Ksp: ksp agent enroll --agent deploy-bot
Ksp->>FS: generate the agent key pair, owner-only
Ksp->>Store: write the agent enrolment record
Op->>Ksp: ksp admin policy --agent deploy-bot --secret my-api-key
Ksp->>Store: sign and write the policy
Ksp-->>Op: print the agent fingerprint for out-of-band verification
Steps:
ksp initprobes the host. It measures what the host can enforce and writes a capability configuration. The probe validates in memory before it writes, so it cannot produce a file the reader would reject.ksp admin initcreates the deployment identifiers, the admin signing key, the pinned anchor and every protected root. The roots come from one table; the modes are set withfchmod, never withopen(2)'smode, because the caller'sumaskmasks that.ksp admin user addseals the user's vault. The vault holds her signing key, her recipient key and the vault key, encrypted under an Argon2id-derived key. The enrolment record is written with the fingerprint that binds her identity, both public keys and both key IDs.ksp agent enrollgenerates the agent's two keys and writes its enrolment record. The private halves never leave the owner-only file.ksp admin policysigns the grants. A write merges: the grants it names are added and the others are kept.--replaceis the whole-set write that withdraws everything it does not name. The signed policy is read by every principal and replaceable only with the admin key.
Two grant surfaces exist, and they answer different questions. The grant set
above authorises a leased copy (secret share --agent). A policy edge
(admin policy create) authorises one publication and is what workflow 4
delivers through - one signed artifact per grant, so a read-back can report on
that grant alone.
The last step of the policy is the important one: the operator reads the agent's fingerprint aloud, or sends it over another channel, and the agent side confirms it out of band. Nothing in the system substitutes for that step.
Workflow 2: Store a secret¶
sequenceDiagram
participant Op as Operator
participant Ksp as ksp binary
participant Vault as Sealed vault
participant Store as Sealed store
Op->>Ksp: ksp secret set my-api-key --name api-key
Op->>Ksp: the value on stdin
Ksp->>Ksp: read the passphrase, unseal the vault
Ksp->>Ksp: derive the content key for the level
Ksp->>Ksp: seal the content blob, name inside the ciphertext
Ksp->>Ksp: seal the content key to the recipient
Ksp->>Store: write the version, then advance the head
Ksp->>Store: append the audit record
Ksp-->>Op: the version number
Steps:
- The value arrives on stdin, never in argv and never in an environment variable. A trailing newline is stripped and an empty value is refused.
- The passphrase is read from stdin or from
--passphrase-file. The vault is unsealed inside this process, used, and discarded when the process exits. - The content blob is sealed with ChaCha20-Poly1305 under a fresh content key. The name is inside the ciphertext, so a store listing discloses no secret name.
- The content key is sealed with HPKE to the recipient, with the record's five-part identity - vault, principal, level, secret id, version - bound as associated data.
- The version is written with a create-only put. An identical retry continues; a different body at the same version is refused.
- The head advances with a compare-and-set, so a concurrent writer cannot silently lose an update.
- The audit record is appended before the success report.
Workflow 3: Mint a lease¶
This is the workflow with the most steps, because it is the one that has to be safe under an uncertain failure.
sequenceDiagram
participant Op as Operator
participant Ksp as ksp binary
participant Admit as Admission
participant Store as Sealed store
Op->>Ksp: ksp secret share my-api-key --agent deploy-bot --out lease.ksp
Ksp->>Ksp: read the pinned admin public key
Ksp->>Admit: classify the backend with the fresh sweep proof
Admit-->>Ksp: Scheduled, interval 15m
Ksp->>Ksp: check the agent binding and the policy grant
Ksp->>Ksp: unseal the user vault
Ksp->>Ksp: re-seal the content key at the agent level
Ksp->>Store: write the arm record, create-only
Ksp->>Store: write the leased version
Ksp->>Store: append to the issuance ledger
Ksp-->>Op: the lease path
Steps:
- Admission first. The backend is classified against evidence, not
configuration. On
file, that means a signed sweep proof that is present, verified, in scope and fresh. A declared cadence on its own admits nothing. - The anchor is pinned locally. The admin's public key is read from the host's own pinned anchor file, never from the policy or the token.
- The policy grant is verified against that anchor, and the agent's enrolment fingerprint is confirmed.
- The record is re-sealed at the agent level. The content key is sealed to the agent's recipient key. The agent-level record is a copy, not the original: the user's durable record stays where it is.
- The arm is written before the publication. The signed, key-free deletion intent goes into the store first, create-only. An uncertain arming publishes no token.
- The issuance ledger is appended. One row per minted lease, by
publish_recorded, sotoken listandtoken revokehave a subject.
Workflow 4: Publish a grant and deliver without a copy¶
The second delivery shape, and the one that keeps the admin's secret out of the user's reach. Nothing is copied: the admin publishes one sealed entry, signs a grant that names it, and the token the user exports carries a reference instead of a key.
sequenceDiagram
participant Admin as Admin principal
participant Ksp as ksp binary
participant Store as Sealed store
participant User as User principal
participant Agent as Agent process
Admin->>Ksp: ksp admin seal-vault
Ksp->>Store: admin-vault.cbor, 0600
Admin->>Ksp: ksp admin put published --name published --own
Ksp->>Store: the admin-level record, sealed to the admin vault
Admin->>Ksp: ksp admin policy create --user U --secret published --agent A
Ksp->>Store: append the decision to policy-events.jsonl
Ksp->>Store: write the signed edge at the admin principal
Ksp->>Store: seal one publication entry to the agent's recipient key
Ksp->>Store: write the token beside the edge
Ksp-->>Admin: the grant, and where the token is
User->>Ksp: ksp secret share published --policy ID --out pub.token
Ksp-->>User: the token, copied out: no password, no key
User->>Agent: hand over pub.token
Agent->>Ksp: ksp run --token pub.token --env VAR -- child
Ksp->>Store: verify the grant, open the entry with the agent's key
Ksp->>Agent: one environment variable, never argv
Steps:
admin seal-vaultcreates the admin's own sealed vault. Every publication entry's content key is sealed to it, so it is created once and cannot be replaced: re-sealing would leave every existing entry naming a key nobody holds.admin put --ownwrites the record the publication is made from, sealed to the admin's public recipient key - no password, because writing needs no private half. Without--ownthe same verb is the transfer to the user, which is a different record at a different principal.admin policy createsigns one edge. The order is the control: the decision is appended topolicy-events.jsonl, then the edge is written, then the publication entry is sealed to the agent, then the token is minted last. A failure before the publication leaves an edge that readsdangling, not a token that names nothing.- The grant is verified before anything is opened. The anchor, the target, the secret version and both ends of the validity window are checked against the signed edge. A withdrawal removes the edge, so a withdrawn grant stops at "no such grant" rather than decrypting first.
secret share --policycopies the token out and reads no vault. The token has no content key, so there is nothing for the user to unlock - and nothing for her to hand on that would open the value.runopens the publication with the agent's own recipient key. The delivery is recorded in her chain, because the agent acts for the principal the grant names.
Two refusals keep this delivery honest. --consume is refused: there is no
agent-level copy to delete, and deleting nothing while reporting a deletion would
be a false claim. And a grant whose publication is missing renders dangling
with the missing path, because a grant that cannot deliver is not a healthy one.
Workflow 5: Consume a lease¶
The workflow an agent runs. It has two processes, and that is not an accident.
sequenceDiagram
participant Agent as Agent host
participant Run as ksp run
participant Deliver as ksp __deliver
participant Child as The child process
Agent->>Run: ksp run --token lease.ksp --consume -- ./deploy.sh
Run->>Run: read the leased version from the store
Run->>Run: verify the issuer against the pinned user key
Run->>Run: confine the process tree
Run->>Deliver: spawn the delivery process with the value on stdin
Deliver->>Child: launch with the value in one named env var
Child-->>Deliver: exit
Deliver-->>Run: exit
Run->>Run: delete the version, journal it, append the audit record
Run-->>Agent: the outcome
Steps:
- Verify before anything else. The issuer's signature is checked against the pinned user key on this host. A key inside the artifact under verification is data, never an anchor.
- Confine. The Landlock ruleset is applied to the process tree before the child starts. Confinement is irreversible, so the confined process is a different process from the one that has to delete afterwards.
- Deliver through a second process. The plaintext crosses one pipe into
ksp __deliver, a hidden internal command, which reads it from stdin, re-resolves the capability configuration, applies the confinement and hands it to the child as one named environment variable. The plaintext is zeroized on every exit path. - Delete after the read. The version is removed from the store.
- Journal, then report. The acknowledgement is journalled before the report is written. A journal failure stops the operation; a report failure does not.
What this workflow does not promise. The record is gone, so a later fetch
fails. A copy taken before the delete does not. The exit code distinguishes
the two cases: 9 means the delete failed and a retry may help, 10 means
the child failed after a successful removal and a retry cannot help.
Workflow 6: Arm and run the sweep¶
sequenceDiagram
participant Op as Operator
participant Ksp as ksp binary
participant Sched as Scheduler
participant Store as Sealed store
Op->>Ksp: ksp backend arm-sweep --kind launchd --interval 15m --scope p/main
Ksp->>Store: record the schedule
Op->>Ksp: ksp backend arm-sweep ... --install
Ksp->>Op: write the launchd property list under the operator's home
Sched->>Ksp: ksp secret purge-expired
Ksp->>Store: read the arm records
Ksp->>Store: remove the due versions
Ksp->>Store: journal each acknowledgement
Ksp->>Store: write a signed sweep proof
Ksp->>Store: append the audit record
Steps:
- Arming is configuration. The schedule says when the sweep should run. It is never evidence that it did.
--installwrites under the operator's own home. A system-wide target is refused rather than escalated. The property list carries the real binary path, because a hardcoded one once produced a plist that failed withENOENTwhile the install reported success.- The scope is a level, never a record. A deeper
--scopeis refused, and the refusal names the accepted shape. Normalisingagent-<uuid>toagent-*would silently widen what a sweep may delete. - The proof is the output that matters. After a successful sweep, the sweep writes a signed proof. A lease is admitted only against a fresh, verified, in-scope proof.
Workflow 7: Read the audit log¶
Two commands, two different questions, over the same log.
sequenceDiagram
participant Op as Operator
participant View as ksp audit
participant Verify as ksp audit verify
participant Log as Audit chain
Op->>View: ksp audit --limit 50 --since 1h
View->>Log: read the segments this caller may see
Log-->>View: the records
View-->>Op: a summary, then one line per record
Op->>Verify: ksp audit verify --head abc123...
Verify->>Log: walk the chain against the pinned public material
Verify-->>Op: valid, revoked, broken, or a torn tail
Steps:
- The scope is the caller's own records. An admin sees the admin's chain; a tenant sees her own, through her unsealed vault. A refusal does not disclose whether a UUID exists.
- The view is bounded.
--limitbounds the record lines and--sincefilters by each record's ownobserved_at. The header reports the total after the window and before the bound, so a truncated read is visible as a truncated read. - Verification answers a different question. The view projects what is
there; verification checks who wrote it. The exit code
12means the log did not verify, which is distinct from8, which means a proof of possession was invalid.
Workflow 8: Create, revise and withdraw a grant¶
The admin's side of the policy lifecycle. Workflow 4 runs the delivery once a grant exists; this is how the grant comes to exist, how it is narrowed, and how it stops existing. Four verbs, and every one of them writes the decision before it writes the thing the decision is about.
sequenceDiagram
participant Admin as Admin principal
participant Ksp as ksp binary
participant Ledger as policy-events.jsonl
participant Store as Sealed store
Admin->>Ksp: ksp admin policy create --user U --secret S --agent A
Ksp->>Ledger: append the decision (created, revision 1)
Ksp->>Store: write the signed edge
Ksp->>Store: seal the publication entry to A's recipient key
Ksp->>Store: write the token beside the edge
Ksp-->>Admin: the joined view, and where the token went
Admin->>Ksp: ksp admin policy update ID --expires-at T
Ksp->>Ledger: append the decision (updated, revision 2)
Ksp->>Store: replace the edge at revision 2
Admin->>Ksp: ksp admin policy delete ID
Ksp->>Ledger: append the decision (withdrawn)
Ksp->>Store: remove the edge artifact
Ksp->>Store: release the publication entry
Admin->>Ksp: ksp admin policy list --state dangling
Ksp-->>Admin: rows in a fixed order, with the unprinted total
Steps:
admin policy createsigns one grant and is the only verb that mints a token. It stages the artifact, records the decision inpolicy-events.jsonl, and only then publishes — so a crash after the append leaves a grant a retry completes, and a crash before it leaves a tree and a ledger that agree. The publication is written last because its entry is keyed by the policy id, and a publication written first could not know the id the grant would carry.- The grant needs no password to be signed. The admin key is her enrolled
signing key, and a grant is public material. A publication does need one,
because the plaintext comes from the admin's own
--ownrecord — so a--anycooperative grant writes no publication, issues no token, and therefore reads no password it would not use. admin policy updatere-signs at the next revision. Naming a target re-publishes, because the old entry is sealed to a key that must no longer open it; moving only the window does not, because the entry is unchanged. The artifact's content key, name and value are carried over rather than regenerated, since regenerating them would stop every entry already made from opening. A window that has already passed is refused rather than written.admin policy deleteis a withdrawal, and it is one decision with three effects in a fixed order: ledger, artifact, publication. Any other order turns the ledger into a description of what happened rather than a control over what may happen. Each step asks what is already true before acting, so a crash anywhere is completable: the append is idempotent, removing an absent artifact succeeds because the aim is its absence, and releasing a released reference writes nothing.- A withdrawal does not delete the publication. Releasing the last reference leaves the entry where it is, because an artifact that vanishes before its entry is written is a change nobody can account for. Removing it is a separate decision with its own record, not a side effect of a count reaching zero.
admin policy listandshowread one join. Both go through the same projection, so a read cannot disagree with the write. The sort key is user, then secret, then version, then identifier: two runs over one tree print the same rows in the same order, so--limitcuts a prefix of a fixed order and the header can report the total before the bound.- A policy is in one of five states, and the precedence is what makes the
state useful rather than decorative:
unverifiedfirst (the signature does not verify against the pinned anchor, or the artifact's digest is not the one the ledger recorded for its revision, so nothing it says is evidence), thenwithdrawn(the decision stands even if what it named has since gone), thendangling(the edge names a user, agent or secret version that is not there), thenexpired(the window has passed), andactiveotherwise.
Two properties make this surface checkable rather than merely plausible. A
show for another principal's policy is reported absent, not forbidden, so
the answer does not confirm that someone else holds one. And an artifact whose
digest no longer matches its recorded revision reads unverified even though
its signature verifies against the anchor — the admin signed something, and it
is not what the ledger decided.
Data Flow¶
The path a secret takes, from the operator's keystroke to the child's environment variable. The dashed edges are the two boundaries where the plaintext crosses into a process that must not be trusted.
flowchart TD
Input["Value on stdin"] --> Seal["Seal the content blob<br/>name inside the ciphertext"]
Seal --> Env["Seal the content key<br/>HPKE to the recipient"]
Env --> Store[("Store the version")]
Store --> Mint["Re-seal at the agent level"]
Mint --> Arm["Write the arm record<br/>before the publication"]
Arm --> Lease["The leased version"]
Lease --> Open["Open the record<br/>agent's private key only"]
Open --> Pipe["One pipe into<br/>ksp __deliver"]
Pipe --> EnvVar["One named env var<br/>in the child's environment"]
EnvVar --> Child["The child process"]
The second delivery shape takes a shorter path, and the difference is the point: the value never leaves the admin's side, and what travels is a reference.
flowchart TD
Own["Admin's own record<br/>sealed to the admin vault"] --> Entry["Publication entry<br/>re-sealed to the agent's key"]
Entry --> Ref["Token<br/>a reference, no content key"]
Ref --> Agent2["Agent process<br/>opens with its own key"]
Agent2 --> Value["The value<br/>in memory, then the child"]
Three things this diagram is designed to make visible:
- The content key is separated from the content. The store holds the sealed content key; only the recipient's private key can unwrap it.
- The arm record is written before the leased version, not after.
- The plaintext crosses one pipe, into a process whose only job is to hand it over, and it is zeroized on every exit path.
State Management¶
There is no in-memory session state that outlives a command, and no cache of an unsealed vault. Every piece of state is a file, and each one has a single writer:
| State | Where | Written by |
|---|---|---|
| Deployment identifiers | deployment.cbor, admin-anchor.cbor |
admin init |
| The sealed vault | vault.cbor |
admin user add, vault rekey |
| Records and versions | The store, under the level hierarchy | secret set, admin put |
| Arm records | store/intents/<identity> |
The mint path |
| The grant set | policy.cbor |
admin policy |
| Policy edges | store/p/<vault>/<admin>/ beside policy-events.jsonl |
admin policy create, update; delete removes one |
| Publications | The granted/ level under the admin |
admin policy create, update; a withdrawal releases that grant's entry beside it |
| Tokens | The policies/ level under the admin |
admin policy create |
| The principal registry | store/p/<vault>/principals.cbor |
admin init, admin user add |
| Mint history | issuance.jsonl, policy-events.jsonl |
The mint path, and the admin's decisions |
| The audit chain | audit/ segments |
Every operation |
| Key material | admin/, agent/ |
admin init, agent enroll |
The rule is that a resolved value is taken from the resolution, never
re-read from its source. The layout resolves KSP_HOME once; a step that
re-reads the environment variable writes an empty path into the plist. That
class of bug is why the layout is a single struct passed down.
Error Handling¶
Typed errors, one exit-code owner¶
Every subsystem defines its own thiserror enum with an exit_code() method.
The constants live in exactly one place, exit.rs, and a command never
chooses an integer.
| Code | Meaning | What the caller should do |
|---|---|---|
0 |
Success | - |
1 |
Internal failure | Report a bug |
2 |
Policy denial | Ask for a grant |
6 |
Missing key material | Enrol, or unlock |
7 |
Capability or admission refusal | Change the configuration or the host |
8 |
Proof of possession invalid or missing | Check the clock and the key |
9 |
The delete failed; the record may still be there | Retry |
10 |
The child failed after a successful removal; the record is gone | Request a new delivery |
11 |
A compliant run was refused because the backend requires consumption | Add --consume |
12 |
The audit log did not verify | Investigate the log |
13 |
The invocation was malformed | Fix the invocation; the message names the accepted form |
Codes 3, 4 and 5 are deliberately reserved by the design for token
expiry, an unreachable backend and a sealed vault. A future implementation of
those features must not contradict a shipped contract, so the current code
skips them.
No catch-all success¶
The dispatch match over the command enum has no catch-all arm, on purpose: a
newly added command cannot silently succeed. Every unreachable path returns
1, not 0.
Refusals name the fix¶
A refusal message names the accepted shape, not just the rejected one. When
arm-sweep refuses a scope, the message names the shape it accepts. A family
of refusals that each read correctly but contradict one another leaves the
reader unable to derive the accepted form.
Errors never suggest escalation¶
A tool's own error text can tell the reader to run as root. Passing that through verbatim defeats a refusal that exists to prevent escalation, so any surface that forwards another program's stderr strips the escalation hints before it prints them.
The redaction rule¶
A secret value, a key, a raw token or successful proof-of-possession material never reaches stdout, stderr, an audit event or a JSON output. And a raw error stack or message never reaches a response body.
See Also¶
- Architecture Overview - the C4 views
- Deep Dive: ksp - the command-line interface
- Deep Dive: ksp-deletion - the evidence model