Skip to content

Record Cryptography and Version Integrity

The subsystem that turns a secret into an immutable, bound, tamper-evident stored record, and that decides whether a recipient key is safe to encrypt to. It owns the key schedule, the associated data, and the version-commit write path. It never decides who may read a record and never talks to a backend policy.

Identifier and encoding terms live in the shared-types context; this context owns only the concepts specific to sealing and committing a record. The shared Record Path is built and parsed in src/path.rs, and nothing else formats its five segments.

Language

Record: An immutable stored unit holding signed metadata, an AEAD content blob and an HPKE envelope. The version, not the record, is the unit a lease deletes. Avoid: secret, entry, row, document Subsystems: Record Cryptography and Version Integrity Files: crates/ksp-record/src/envelope.rs Relates to: Record Version (is instance of), Content Key (is sealed in), Bound Metadata (names) History: - 2026-10-21 (001-keyspout-mvp): Term introduced.

Content Key: A fresh random 256-bit symmetric key that encrypts one record version's payload. It exists in the clear only inside the sealing process; every saved artifact carries it sealed to a recipient key. Avoid: sk, secret key, data key, DEK, master key Subsystems: Record Cryptography and Version Integrity, Identity Sealed Delivery and Policy Verification Files: crates/ksp-record/src/envelope.rs, crates/ksp-identity/src/delivery.rs Relates to: Record (encrypts), Recipient Key (is sealed to), Bound Metadata (binds) History: - 2026-10-21 (001-keyspout-mvp): Term introduced. "sk" is retained as an explicit avoidance because the design spec uses it for the same thing.

KEM Validation Gate: The check that rejects a recipient or encapsulated key whose X25519 shared secret would be all zero, in both directions, before any envelope exists. Avoid: low-order check, point validation, sanity check Subsystems: Record Cryptography and Version Integrity Files: crates/ksp-record/src/kem.rs Relates to: Recipient Key (validates), HPKE Envelope (gates creation of) History: - 2026-10-21 (001-keyspout-mvp): Term introduced.

HPKE Envelope: The RFC 9180 ciphertext sealing a content key to one recipient key under a named info label and a bound associated-data value. Avoid: wrapped key, sealed key, box, capsule Subsystems: Record Cryptography and Version Integrity, Identity Sealed Delivery and Policy Verification Files: crates/ksp-record/src/envelope.rs, crates/ksp-identity/src/delivery.rs Relates to: Content Key (contains), Recipient Key (sealed to), KEM Validation Gate (is gated by) History: - 2026-10-21 (001-keyspout-mvp): Term introduced.

Content Blob: The AEAD ciphertext over a record's name and value, bound to the same associated data as the record envelope. Avoid: ciphertext, payload, encrypted value Subsystems: Record Cryptography and Version Integrity Files: crates/ksp-record/src/blob.rs Relates to: Bound Metadata (is bound to), Content Key (encrypts) History: - 2026-10-21 (001-keyspout-mvp): Term introduced.

Conditional Publication: The write that commits a complete record version and makes it the current head only if no competing writer already holds that version or head. Avoid: atomic write, compare-and-swap, last-write-wins Subsystems: Record Cryptography and Version Integrity Files: crates/ksp-record/src/version.rs Relates to: Record Version (publishes), Blob Store (writes to) History: - 2026-10-21 (001-keyspout-mvp): Term introduced.

Version Conflict: The refusal that occurs when a competing writer already holds the version or head being published. The conflict is refused, never overwritten. Avoid: clash, collision, EEXIST Subsystems: Record Cryptography and Version Integrity Files: crates/ksp-record/src/version.rs Relates to: Conditional Publication (is raised by) History: - 2026-10-21 (001-keyspout-mvp): Term introduced.

Blob Store: The storage contract the record subsystem writes through: get, put, list and delete over opaque blobs, with no decrypt method. The conditional publication is expressed through the store's own compare-and-set write. Avoid: backend, storage adapter, blob client Subsystems: Record Cryptography and Version Integrity, Backend Admission and Durable Arming Files: crates/ksp-record/src/version.rs Relates to: Conditional Publication (is written through), Record (is stored in) History: - 2026-10-21 (001-keyspout-mvp): Term introduced. "backend" is avoided because the concrete backends are a later work package, while the contract is what this subsystem owns.

Provider Guard: The build-time check that refuses an HPKE provider below the version whose dh implementation performs the all-zero shared-secret check. It reads the resolved version, not the declared minimum, so a downgrade fails the build rather than passing silently. Avoid: version pin, dependency check, cargo audit Subsystems: Record Cryptography and Version Integrity Files: crates/ksp-record/src/provider_guard.rs, crates/ksp-record/build.rs Relates to: KEM Validation Gate (guards the provider behind) History: - 2026-10-21 (001-keyspout-mvp): Term introduced.

Relationships

  • A Record Version is a Record at one version number
  • A KEM Validation Gate guards creation of an HPKE Envelope
  • Conditional Publication makes a Record Version current
  • A Version Conflict is refused, never resolved by overwriting
  • A Blob Store holds Record versions and expresses Conditional Publication
  • A Provider Guard protects the KEM Validation Gate from a downgraded provider

Flagged Ambiguities

  • "secret" was used to mean both the value a user stores and the content key that protects it — resolved: "value" is the user's plaintext; "Content Key" is the cryptographic key. A "secret" in a path or filename is neither.
  • "head" was used for both the current version pointer and the record's payload header — resolved: the pointer is written "head"; a payload header is written "header".
  • "audit" was used for both a security review of dependencies and a log of what happened — resolved: the Provider Guard is a build check; a log of what happened is an "audit event".