Contributing to Keyspout¶
Read this before your first change. It covers the build, the test gate, and the rules that are not stylistic — the design decisions that cost something real and must not be quietly reversed.
The authoritative design is docs/keyspout-design-spec.md.
That document wins over anything you infer from the code. If the code and the
spec disagree about what should happen, that is a design change and it needs
agreement in an issue before you write it. A status marker in the spec is not
that agreement.
1. Build¶
rust-toolchain.toml pins the toolchain. Cargo.toml sets resolver = "3" and
edition = "2024", so an older cargo fails before it compiles anything.
macOS and Linux both build. The Linux-only adapters (landlock,
memfd_secret, sealed_memfd) are target-gated. macOS enforces no path
confinement and its memory barrier is mlock, reported as weakened — never as
memfd_secret. Every run discloses which one it got.
DEVELOPMENT.md covers the VM, the backend services (Valkey,
RustFS, Garage), and the places where an assumed API differs from the real one.
2. Test¶
scripts/ksp-gate.sh host < /dev/null # fmt, clippy, audit, the unprivileged suite
scripts/ksp-gate.sh # both halves; re-executes into the Linux VM
Two things about that script are deliberate and should not be "simplified":
- It is one script, not four commands. The obvious four-command list can
never be green here, and a gate that is permanently red teaches contributors
to ignore it.
cargo test --workspacefails oncrates/ksp-cli/tests/principals.rs, which needs two UNIX accounts and refuses to run without root on purpose.cargo teststops at the first failing binary, so that one by-design failure would skip every target after it. - Redirect stdin.
bash scripts/ksp-gate.sh < /dev/null. One test reads stdin; with stdin left as an open pipe the suite blocks for thirty minutes instead of failing.
Never call the suite green from a fail-fast run. Never run the whole suite as
root — root bypasses umask, 0600 modes and CAP_IPC_LOCK, so the tests
that assert those properties fail as root.
A test exists that would fail without your change, and it fails for the right reason. Prove it discriminates: break the code the test covers and confirm the test goes red. A test that passes both before and after the change tests nothing.
3. Rules that are not stylistic¶
The design reached these by argument. Most of them cost something real, and each one is a place where the obvious implementation is wrong.
Deletion is best effort, never a guarantee¶
Use NativeExpiry for configured logical expiry and
Scheduled { declared_interval } for configured cleanup cadence.
D >= 2 × declared_interval is conservative admission policy, not proof of a
sweep or a maximum lag. Do not describe deletion as erasure, and do not claim a
deletion time.
A missing mechanism is None¶
file is None. Valkey needs acknowledged durability and configuration gates.
Unversioned S3 needs configured cleanup and a declared cadence. A known mismatch
fails admission. Status discloses unknown lag and retention.
Hiding is not erasing, and a probe cannot prove erasure¶
Versioned S3, soft-delete configurations and B2 hiding remain None. A delete
marker is not an erasure.
Seal every saved or transferred delivery artifact¶
Independent agent Ed25519 and X25519 pairs. The user verifies a fingerprint
binding identity, both public keys and key IDs. No implicit key conversion, no
raw sk in tokens, no optional sealing. Proof of possession authenticates a
compliant invocation; it is not a decryption policy.
Arm durably before token publication¶
There is no distributed atomic output transaction. Publish no token while arming is uncertain. Reconcile with idempotent identity.
Attribute deletion honestly¶
An intent contains no keys and is not a tombstone. Prefer authorized per-version
actor reports after a delete acknowledgement. Native absence without a report is
missing or unconfirmed. An observer records observed_at, not an invented
deletion time. Retry reports without resurrecting the record.
Consume is not exactly once¶
Retrieve, decrypt, hand to the child, delete, report. Only subsequent fresh fetches are prevented after removal, absent restoration or replay. Concurrent reads and copies survive. There is no automatic remint.
Rotation does not revoke old offline pairs¶
Rotation changes future minting and new trust state. Revoking the upstream credential is a separate action.
Never eval(), and never shell-interpolate a path¶
Validate inputs with a schema. Pass non-secret runtime values through env.
Never return a raw err.stack or err.message in a response body.
No plaintext secret in argv, logs or environment¶
A deliberate child --env delivery is an output exception. Never audit raw
tokens or successful proof-of-possession material. Shamir restores a sealed
bundle, not a lost phrase. The unseal key is symmetric.
Public upstream credentials go through a resolver¶
Never a string literal.
Backend admission is evidence-based¶
SSHFS, DNS and static HTTP are refused, each for a specific measured reason:
SSHFS has no .lock op, writes asynchronously by default and cannot rename
atomically; a DNS TTL is not a deadline and AXFR can dump the zone; static HTTP
has no put. Do not re-admit one without a mechanism that addresses the
specific reason it was refused.
Enforcement beats convention¶
A level tree is real only when something enforces it — kernel permissions behind
per-agent accounts on sftp, or Landlock in-process on file. Code that merely
named the levels would enforce nothing, and a test that asserts a client-side
check proves nothing about containment.
Landlock confines only the opted-in process tree; sanitize inherited descriptors. It does not confine same-UID outsiders or remote keys. Warn if optional file confinement is unavailable; refuse required confinement.
Confinement is not authentication¶
Landlock restricts paths; only a signature establishes which key is speaking. Both are required and neither substitutes for the other.
4. Traps that have already cost time¶
Each of these shipped or nearly shipped a bug.
- A mode that crosses an account boundary is set by
fchmodorset_permissions, never byopen(2)'smode. Both are masked by the caller'sumask. - A signed artifact must name the key that signed it. Changing who signs
means grepping every
issuer_key_idandsigner_key_id. - A directory is a capability, not just a level. Creating
agent-<id>/besideuser/needs write on the parent, not onuser/. - A directory
fsyncneeds read permission. A write-only journal cannot acknowledge durability. - A
list(prefix)must descend both ways — above the prefix to reach it, and below it when the prefix names a directory. cfg(target_os = "darwin")is never true. rustc setstarget_os = "macos", so a Darwin branch written the other way compiles out silently.- Applying a confinement ruleset confines the calling process,
irreversibly. A refusal is decided after the restriction is in force, so
establish()returningErrdoes not mean nothing happened. A test that needs the kernel's answer re-executes a throwaway child. - Never byte-scan a signed or hashed artifact. A random signature contains
/about one time in five, so a scan for a path fails at random. - A test that compares a value against another value the same expression produced cannot fail. Take the expected value from the code that produces it.
- A fixture already in canonical order cannot prove order. Give the wrong answer a different shape than the right one.
- A fixture that supplies a precondition hides the code that produces it. If a command's job is to create X, at least one test must start without X.
- A surface that reports a measurement must also report the policy behind it, or the label is read as the policy.
- A hint appended to an error must name a command that can act on that state.
- A parser's
Displayis a debugging aid, not a user-facing message. A TOML error renders the offending source line, which may be a passphrase.
5. Commits¶
Conventional Commits:
feat(seal): add HPKE envelope with low-order-point rejection
fix(authz): reject token bound to a sibling agent level
docs: correct the admission rule for versioned buckets
Branch prefixes: feat/, fix/, refactor/, docs/, test/, chore/.
Merge target is main.
Before you commit:
- The gate passes, and you can say which parts you ran.
git statusshows no secrets, no.env, no vault state, no key files.- The spec's status markers still match the tree. If your change moves one, update it in the same commit. A marker is a claim about the merged tree, and a stale marker tells a reader a control exists when it does not.
6. The documentation site¶
site/ is a MkDocs Material site. It publishes the project's architecture —
the overview, the workflow walkthroughs and a deep dive per crate — and the
tree's own public documents, which it assembles at build time.
python3.14 scripts/site/prepare-docs.py --source . # assemble the reference section
python3.14 scripts/site/check-links.py --root site/docs
python3.14 scripts/site/check-mermaid.py site/docs
# Stack each wide diagram's subgraphs one below the next. This one renders,
# because which layout is narrowest differs per diagram and cannot be decided
# by a rule; CI runs it with --check to catch an unstacked diagram.
python3.14 scripts/site/stack-subgraphs.py --puppeteer-config site/puppeteer.json
mkdocs build --strict --site-dir "$PWD/site/build" -f site/mkdocs.yml
The site directory is absolute on purpose. MkDocs resolves a relative
--site-dir against the configuration file's directory, not the working
directory, so --site-dir site/site writes to site/site/site. The uploaded
artifact would then hold the site one level too deep, and Pages — which
serves the artifact's root — would answer every page with a 404.
site/docs/ holds the site's own pages and is tracked. site/docs/reference/
and site/docs/assets/ are generated and are not: the reference section is
the design specification, the quickstart, the security model, the known
defects and the eight crate context files, read from this tree at build time.
Tracking them would ship a second copy of the design specification, and two
copies drift.
.github/workflows/pages.yml builds and deploys the site on every push to
main. It runs the link check and the Mermaid check first, so a diagram that
does not parse fails the build rather than shipping as an empty box.
A page that documents a mechanism names the file that implements it. A marker without a path is an assertion, and an assertion about a security control is worth very little.
7. Design vocabulary¶
Source comments and the context files use a few shorthand labels. They are defined here so a reader does not have to guess.
S1–S6 name the six subsystems, one per context in
CONTEXT-MAP.md:
| Label | Subsystem | Crate |
|---|---|---|
S1 |
Record Cryptography and Version Integrity | ksp-record |
S2 |
Identity, Sealed Delivery and Policy Verification | ksp-identity |
S3 |
Backend Admission and Durable Arming | ksp-backend |
S4 |
Deletion Evidence and Consume Outcome | ksp-deletion |
S5 |
Host Confinement and Key Material Posture | ksp-posture |
S6 |
Durable Key Lifecycle | ksp-key-lifecycle |
S3 also names the Amazon S3 storage service. Where the meaning matters, the
comment says which — S3's arm record is the subsystem, an S3 bucket is the
service.
Misfit <letter> names a specific failure mode the design has to survive.
Each use states the failure in the same sentence, because the letters are
scoped per design document and do not carry across all of them. Read the
sentence, not the letter.
8. Reporting a security issue¶
Do not open a public issue for a vulnerability. Email the maintainer directly and allow time for a fix before disclosure.