Skip to content

0003: Envelope encryption with epoch KEKs and derived per-event DEKs

  • Status: accepted
  • Date: 2026-09-22
  • Amended by: 0052 (a wrap is stored under the link that calls for it; see the path below)

Context

Encrypting each secret directly to every member's public key means that adding or removing a member rewrites every file in the vault. That is the operation that produces git conflicts and inconsistent states in existing tools, and it forces "everyone stop working" ceremonies.

Decision

Three layers of keys:

  1. DEK (data encryption key), one per event, never stored. It is derived as HKDF-SHA-256(KEK_epoch, salt, info) where salt is 32 random bytes stored in the event header and info is "vaultfold/dek/v1" bound to the vault id, collection id and epoch number (see the crypto-suites spec).
  2. KEK (key encryption key), one per epoch of a collection. A vault that does not use additional collections has one collection, named default, and all its epochs belong to it. A new epoch is created only on revocation (ADR 0007). Epoch numbers are monotonically increasing integers.
  3. Device public keys, one per device of each member (ADR 0008). Each epoch KEK is wrapped to each authorised device key and stored at epochs/<collection-id>/<epoch>/<link>/<keyid>.wrap, where <link> is the first 16 hex characters of the id of the policy link that first gives that device key that epoch (ADR 0052; before it the path had no <link> segment).

Consequences of the layering:

  • Adding a device is purely additive: one new wrap file per epoch that the device is granted. Granting from a later epoch onward is possible and means the device cannot read events written before that epoch.
  • There are no per-event wrap files. An event is readable by anyone holding the KEK for the epoch named in its header.
  • Collections (top-level namespaces such as prod/) may have their own KEK lineage, giving real read scoping: a device that holds only the staging collection's KEKs cannot decrypt prod events.
  • The event header records epoch and collection in the clear; everything else, including the entry path, is inside the ciphertext.

Consequences

  • Membership changes never touch event files and can never conflict.
  • A single compromised device key reveals every KEK it was wrapped for, and therefore every event in those epochs. This is inherent to any group encryption scheme and is addressed by device revocation (ADR 0008) and rotation (ADR 0007).
  • Moving an entry between collections requires writing a new event under the target collection's KEK; the old event is tombstoned.
  • Compaction writes a snapshot event under the current epoch (ADR 0007).

Alternatives considered

  • Per-event DEK wrapped to each recipient. Rejected: O(members) files per event and rewrites on membership change.
  • Per-event DEK stored as a separate wrap file under the epoch KEK. Rejected after review: doubles the file count and introduces an "event exists but its wrap does not" failure mode. Since re-wrapping old events to a new epoch is not a security gain (ADR 0007), the separate file has no purpose.
  • Backward hash chain of epochs so one wrap unlocks all earlier epochs. Rejected: the holder of the chain seed can derive every future epoch, which makes the vault creator unrevocable.