Deep Dive: ksp - the command-line interface¶
Overview¶
crates/ksp is the foreground entry point of the whole system. Every
operation is one invocation that starts, does its work and exits. There is no
daemon, no listener and no session.
The crate has two halves:
src/commands.rs- the clap tree. It defines the surface: which commands exist and which flags they take. Nothing else decides that.src/app.rsand the per-feature modules - the implementation. Each feature owns its own module with its own typed error and its own rendering.
That split is enforced by a test. commands.rs carries a test that walks the
clap tree and compares it against a hand-written list of every expected path.
A command that is missing is a capability the product does not have; one that
is extra is a surface nobody specified.
Responsibilities¶
- Own the complete command surface, and keep it pinned by a test.
- Own the exit-code vocabulary, in one file, with no other module allowed to choose an integer.
- Own the output shapes: one
Reportenum, two renderings, one data source. - Own the redaction rule: a plaintext value has no route into the report or the audit path.
- Own the protected-root table and the probe that measures it.
- Wire the seven domain crates together, and refuse rather than improvise.
Architecture¶
graph TB
MAIN["main.rs<br/>parse, resolve the home, map the outcome to a code"]
COMMANDS["commands.rs<br/>the clap tree and its surface test"]
APP["app.rs<br/>dispatch and per-group handlers"]
EXIT["exit.rs<br/>the constants and the mapping functions"]
subgraph Feature["Feature modules, one per area"]
direction TB
ADMIN["admin.rs"]
SECRET["secret.rs"]
TOKEN["token.rs"]
AGENT["agent.rs"]
VAULT["vault.rs"]
BACKEND["backend.rs"]
ARM["arm.rs"]
SWEEP["sweep.rs"]
AUDITV["audit_view.rs"]
AUDITV2["audit_verify.rs"]
end
subgraph Grantpath["The grant path"]
direction TB
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 prints"]
LEDGERS["ledgers.rs<br/>issuance and policy events"]
end
subgraph Runpath["The run path"]
direction TB
RUN["run.rs<br/>load, verify, sign the proof"]
GATE["run_gate.rs<br/>verify, confine, launch"]
CONSUME["consume.rs<br/>authorise, spend, delete, journal"]
DELIVER["deliver.rs<br/>the hidden child delivery"]
PROCESS["process.rs<br/>the real command launcher"]
end
subgraph Host["The host-facing half"]
direction TB
LAYOUT["layout.rs<br/>the protected-root table"]
ESTABLISH["establish.rs<br/>adapter selection"]
PROBE["probe.rs<br/>measure and configure"]
CONFIG["config.rs<br/>the layout and the backend choice"]
CAPCFG["capability_config.rs<br/>the closed configuration schema"]
STOREGRP["storegroup/<br/>resolve and join the store group"]
end
OUTPUT["output.rs<br/>the Report enum and both renderings"]
MAIN --> COMMANDS
MAIN --> APP
MAIN --> EXIT
COMMANDS --> APP
APP --> EXIT
APP --> OUTPUT
APP --> GRANT
APP ~~~ Feature
APP ~~~ Runpath
APP ~~~ Host
RUN --> GATE
GATE --> PROCESS
CONSUME --> DELIVER
GRANT --> EDGESTORE
GRANT --> PUBLICATION
GRANT --> LEDGERS
POLICYVIEW --> EDGESTORE
POLICYVIEW --> PUBLICATION
Feature ~~~ Runpath
Runpath ~~~ Host
Runpath ~~~ Grantpath
Feature ~~~ Grantpath
The Command Surface¶
Forty-four public paths, plus one hidden internal command. The complete list is
pinned by the_command_surface_matches_the_design_specification.
Setup and status¶
| Command | What it does |
|---|---|
ksp init |
The first-run path: probe the host and write the capability configuration |
ksp config init [--force] |
The same probe, as a repair path |
ksp status |
Disclose the effective backend, the host posture and the layout drift |
ksp version |
The version |
Administration¶
| Command | What it does |
|---|---|
ksp admin init --vault <id> --user <name> |
Create the deployment, the admin key and the layout |
ksp admin user add [--signing-key-id] [--recipient-key-id] [--unix-user] [--passphrase-file] |
Enrol the user, seal her vault, optionally bind a UNIX account |
ksp admin policy [--agent <id>] [--secret <id>] [--replace] [--show] |
Merge, replace or read back the grant set |
ksp admin policy create --user <uuid> --secret <id> [--version N] (--agent <id> \| --any) |
Sign one grant as its own edge: the decision, the publication entry and the token |
ksp admin policy update <id> [--agent <id> \| --any] [--expires-at <secs>] |
Re-sign one grant at the next revision; a target change re-publishes, a window move does not |
ksp admin policy delete <id> |
Withdraw one grant: record the decision, remove the artifact, release the entry |
ksp admin policy list [--user] [--secret] [--state] [--limit] |
Every policy, filtered and bounded, with the unprinted total |
ksp admin policy show <id> |
One policy joined with its verification, tokens, agent keys, publication and withdrawal |
ksp admin seal-vault |
Create the admin's own sealed vault, which every publication entry's content key is sealed to |
ksp admin put <id> --name <name> [--own] |
Write a secret at the admin level; the value on stdin. --own seals to the admin vault, otherwise to the user's key |
ksp admin list |
List the records this deployment holds |
ksp admin audit |
Report the deletion acknowledgement journal - a different store from ksp audit |
ksp admin revoke [--secret <id> \| --agent <id>] |
Withdraw a grant |
Vault and agents¶
| Command | What it does |
|---|---|
ksp vault init |
Exists and refuses with exit 7; a vault is created by admin user add |
ksp vault status |
The vault's state |
ksp vault rekey [--threshold N] [--shares N] |
Re-seal the vault and cut a Shamir share set |
ksp agent enroll --agent <name> |
Generate the agent's two keys and write its enrolment record |
ksp agent pubkey --agent <name> |
Print the public material for out-of-band verification |
ksp agent list |
Every agent this host holds: principal UUID, display name, both key IDs, fingerprint |
ksp agent rotate --agent <name> --signing-key-id <id> --recipient-key-id <id> |
Rotate the agent's identity |
Secrets and leases¶
| Command | What it does |
|---|---|
ksp secret set <id> --name <name> |
Store a secret; the value on stdin |
ksp secret get <id> [--version N] [--reveal] |
Read it back; redacted unless --reveal |
ksp secret rm <id> [--version N] |
Remove a version |
ksp secret ls |
List the secrets at this level |
ksp secret share <id> --agent <name> --name <name> [--ttl] [--uses N] --out <path> |
Mint a lease for an agent |
ksp secret share <id> --policy <id> --out <path> |
Export the token a grant authorised: no password, because the token carries no content key |
ksp secret purge-expired [--limit N] |
The admin-signed sweep |
ksp secret gc [--user-arming] [--passphrase-file] |
The user-signed sweep |
The scoped grant read¶
| Command | What it does |
|---|---|
ksp policy list |
The same join as admin policy list, scoped to the calling principal |
ksp policy show <id> |
The same join for one grant, as the caller may see it |
Tokens and runs¶
| Command | What it does |
|---|---|
ksp token mint --agent --secret --name [--ttl] [--uses] --out <path> |
The mint path |
ksp token lease |
Exists and refuses; unwrapping an agent-level record at the user level is the escrow the levels exist to prevent |
ksp token list |
The issuance ledger |
ksp token inspect --token <path> |
What a lease says about itself |
ksp token revoke <token_id> |
Withdraw a lease |
ksp run [--token <path> \| --agent <name>] [--env NAME] [--env-all] [--consume] -- <child>... |
Verify, confine, launch |
Backends and audit¶
| Command | What it does |
|---|---|
ksp backend list |
The selectable backends |
ksp backend test [--ttl <secs>] |
Test the store through the same admission gate a mint uses |
ksp backend arm-sweep --kind <kind> --interval <dur> --scope <scope> --credential <c> --grant <right>:<scope>... [--install] |
Record the cleanup schedule |
ksp audit [--admin] [--principal <uuid>] [--limit N] [--since 30m\|1h\|7d] |
The scoped log view |
ksp audit verify --head <64-hex>... |
Verify the chain against pinned public material |
The hidden command¶
ksp __deliver --env NAME --level <path> -- <child>... exists, is hidden,
and is the only __-prefixed name. A test asserts both that it exists and
that it stays hidden.
It exists because confinement is irreversible. The process that applies a Landlock ruleset cannot un-confine itself, so it cannot also delete the record afterwards. The delivery therefore runs in a second process.
Dispatch¶
flowchart TD
A["main"] --> B["Cli::parse"]
B --> C["home_from_env<br/>KSP_HOME, else HOME/.ksp"]
C --> D{"neither set?"}
D -->|"yes"| E["refuse, exit 6"]
D -->|"no"| F["dispatch"]
F --> G{"match on the command enum"}
G --> H["run_admin / run_secret / run_token /<br/>run_vault / run_status /<br/>run_probe / run_sweep / run_sweep_as"]
H --> I["the feature module"]
I --> J{"outcome"}
J -->|"typed error"| K["print the typed reason to stderr"]
K --> L["Outcome::Failed(code)"]
I -->|"success"| M["Emitter::report or records"]
M --> N["Outcome::Success"]
L --> O["main prints one generic sentence"]
N --> O
Two details in that diagram are deliberate:
- The dispatch match has no catch-all arm. A newly added command cannot
silently succeed; the compiler forces a decision, and an unreachable path
returns
1rather than0. - The specific reason is printed by the handler, and
mainprints one generic sentence.mainprintsrefused (exit {code}: {describe}), and the typed reason was already on stderr. The generic sentence is the machine-readable part; the typed message is the human part.
Output¶
One report type, two renderings¶
output.rs defines a single Report enum, internally tagged with
kind. The JSON form is one object per report; the text form is a function
per variant.
flowchart LR
R["Report enum<br/>one variant per printable shape"] --> J["--json<br/>one tagged JSON object"]
R --> T["text<br/>one render function per variant"]
J --> E["the agent contract"]
T --> H["the human"]
Because both renderings read the same value, they cannot disagree. That is
the point of the design: an agent parsing --json and a person reading the
text see the same facts.
Records and Agents are struct variants rather than newtype variants,
because serde cannot tag a newtype over a sequence.
The redaction boundary¶
There is no Report variant that carries a plaintext value. That is not
an omission; it is the mechanism. 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, therefore
bypasses Report entirely and builds its own document:
Without --reveal, the value is the four-character redaction ••••. The
exception is visible in exactly one place, which is what makes it auditable.
The audit records¶
ksp audit prints one JSON object per line, after a summary line that
reports the counts: total, emitted, unreadable, malformed, withheld, and
whether the read was truncated. A truncated read says so.
The Exit-Code Contract¶
exit.rs holds every constant. Each subsystem maps its own typed failure to
one of them through a function in that module, so a command never chooses an
integer.
flowchart TD
subgraph Subsystems["Each subsystem owns its own typed error"]
direction TB
SE["SecretError"]
TE["TokenError"]
RE["RunError"]
AE["AdminError"]
VE["VaultError"]
CE["ConsumeFailure"]
SE ~~~ TE
TE ~~~ RE
RE ~~~ AE
AE ~~~ VE
VE ~~~ CE
end
MAP["from_mint, from_run, from_consume,<br/>from_admission, from_policy"]
EXIT["exit.rs<br/>the only constants"]
OUT["the integer the process returns"]
Subsystems ~~~ MAP
MAP --> EXIT
EXIT --> OUT
Three of the codes exist because collapsing them would tell a calling agent the wrong thing:
9and10.9means the delete failed and the record may still be there, so a retry may succeed.10means the child failed after a successful removal, so the record is gone and a retry cannot help.12and8.12means the audit log did not verify.8means a proof of possession was invalid. An agent debugging its key and an operator reading a tampered log need different next steps, and one integer cannot say both.13and1/2.13means the invocation was malformed, and the message names the accepted form. Collapsing a typo into1told a caller to report a crash; collapsing it into2told it a policy had decided something.
The Layout Table¶
layout.rs holds one table of protected roots. Creation reads it;
measurement compares against it. Each row carries the mode and the reason it
is not more open.
flowchart LR
T["the layout table<br/>path, mode, kind, reason, refusal flag"]
T --> E["ensure<br/>creates what is missing"]
T --> M["measured_rows<br/>compares what is there"]
T --> R["refusal<br/>a drift that refuses a delivery"]
T --> L["the layout record<br/>what was created, and with what mode"]
The modes are set with fchmod and set_permissions, never with
open(2)'s mode or DirBuilder::mode. Both are masked by the caller's
umask, and a principal running under umask 077 once made the shared arm
record unreadable, so the sweep refused every lease.
Configuration¶
The capability configuration is a closed schema: StoredConfiguration is
#[serde(deny_unknown_fields)], and validated() converts it into the
closed CapabilityConfiguration while reporting an unknown adapter or a
capability mismatch with the exact key.
The file is opened with O_NONBLOCK. A FIFO at the configuration path would
otherwise block forever, and a configuration read that hangs is worse than one
that refuses.
Reading the configuration is deliberately unrestricted; it holds no secret. The mode check rejects group and other write bits, so an unprivileged process cannot change what the next run will enforce.
Key Files¶
| File | What it owns |
|---|---|
main.rs |
Parse, resolve the home, map the outcome to a code |
commands.rs |
The clap tree and the surface test that pins it |
app.rs |
Dispatch, the per-group handlers, the password reader |
exit.rs |
The exit-code contract |
output.rs |
The Report enum and both renderings |
layout.rs |
The protected-root table, the layout record, the drift measurement |
capability_config.rs |
The closed configuration schema and its refusals |
config.rs |
The Layout struct and the backend selection |
establish.rs |
Adapter selection and the capability disclosures |
probe.rs |
The host probe, the write policy, the configuration writer |
grant.rs |
One grant's lifecycle: the decision, the artifact, the publication, the token |
edges.rs |
The signed grant store: load, write, withdraw, never re-derive a decision |
publication.rs |
The granted level: one artifact per (admin, secret, version), sealed per grant |
policy_view.rs |
The join every read surface prints, so a read cannot disagree with the write |
ledgers.rs |
issuance.jsonl and policy-events.jsonl, the two append-only decisions |
run.rs |
Loading a lease, verifying it, signing the proof of possession |
consume.rs |
Authorising the intent, spending a use, the delete, the journal |
deliver.rs |
The hidden delivery process |
process.rs |
The real std::process::Command launcher |
secret.rs, token.rs, agent.rs, vault.rs, admin.rs, backend.rs |
One module per command group |
sweep.rs, arm.rs, install.rs |
The sweep, the arming, the launchd installer |
audit.rs, audit_view.rs, audit_verify.rs |
Appending, viewing and verifying the chain |
storegroup/ |
Resolving the store group and joining the account to it |
lifecycle.rs |
The order a withdrawal happens in, held in one place: ledger, artifact, publication |
registry.rs |
The principal registry - who belongs to this deployment, and which account is who |
agent_index.rs |
The public half of each agent's enrolment, where the admin can read it |
admission.rs |
The one place a recorded schedule and a proof become a capability |
deployment.rs |
The three identifiers every record path and every policy names |
keys.rs |
What this host pinned, and what a later process reloads against |
Design Decisions¶
The surface is pinned by a test¶
The expected list is written out by hand in commands.rs, not generated from
the implementation. A generated list would always agree with the
implementation, which is exactly what the test exists to catch.
The hidden command is hidden by assertion¶
the_internal_delivery_command_exists_and_stays_hidden asserts that
__deliver exists, is hidden, and is the only __-prefixed name. A hidden
command still exists, so the test has to pin the property, not just the
presence.
Absent commands are absent, not hidden¶
The phase-four session agent verbs - agent start, agent stop, agent
status, agent lock-timeout - are absent from the parser, and a test
asserts their absence. A hidden command still exists; these are out of scope
rather than discouraged.
The home is resolved once¶
home_from_env resolves KSP_HOME, then $HOME/.ksp, and passes the
resolved path down. A step that re-reads the environment variable writes an
empty path into the plist. This is the "a resolved value re-read from its
source is a second answer" rule.
Testing¶
The crate carries three kinds of test:
- Surface tests in
commands.rs- the command tree, the hidden command, the absent commands, and that--jsonis accepted both before and after the subcommand. - Unit tests beside the code, including a test that re-executes a throwaway child to ask the kernel a question the harness cannot.
- Integration tests under
crates/ksp/tests/, one file per feature:agent_contract.rs,wired_surface.rs,audit_scope.rs,use_bound.rs,policy_provenance.rs,arming.rs,refusals.rs,policy_read_back.rs,policy_merge.rs,agent_list.rs,principals.rs.
The principals.rs test needs two UNIX accounts and refuses to run without
root on purpose. It is the only target that needs privilege, and the gate
script runs it separately with its own target directory, because a
root-owned target/ breaks every later non-root build.
Potential Improvements¶
- The
--jsonshape is an internally tagged enum with about thirty variants. It is stable enough for the agents that consume it today, but there is no version field, so a future addition to the surface cannot be distinguished from a change in an existing shape. secret lsandadmin listshare a listing mechanism but not a presentation, so the two lists do not look alike.- The password reader is duplicated across the five arms that need one, and the difference between "no password source" and "the named file could not be opened" is only in the message.
See Also¶
- Deep Dive: ksp-identity - enrolment, PoP, delivery
- Deep Dive: ksp-backend - admission and arming
- Workflow Overview