Skip to content

0007: Membership changes are additive; revocation is a new epoch plus rotation

  • Status: accepted
  • Date: 2026-09-22

Context

Under ADR 0001, a revoked member already holds every ciphertext and every KEK wrap they were ever granted. Re-encrypting existing data after revocation does not remove their ability to read it; it only produces a massive, conflict-prone diff. Existing tools do exactly this and suffer for it.

Decision

  • Add member or device: write the device key file and one wrap file per granted epoch. Purely additive. No coordination required.
  • Revoke member or device: write a policy event revoking the key(s), mint a new epoch KEK for each affected collection, and wrap it to every remaining device. Purely additive. All subsequent events use the new epoch. Nothing is deleted and nothing is re-encrypted.
  • On revocation the tool marks every entry the revoked party could read as rotation required and drives a rotation checklist: the human changes the real credential, records the new value (a normal event under the new epoch), and the entry is cleared. Rotation state and reminders are part of the entry metadata.
  • Compaction is the only ceremony. It writes a signed snapshot event under the current epoch containing the current fold, removes superseded event files from the working tree, and optionally rewrites git history so that fresh clones carry no old ciphertext. It is opt-in, requires the admin to confirm that other writers are paused, and is the one operation where the tool asks everyone to pull first. Concurrent events that race a compaction remain valid because their files survive the merge and are not in the snapshot's causal past.

Consequences

  • Revocation is instant, cheap and conflict-free, and it is honest: the interface says "this stops future reads; rotate these N credentials to address past reads".
  • Old epochs remain readable by remaining members without any re-wrap.
  • New devices are normally granted all epochs; granting from the current epoch only is a deliberate choice for post-incident onboarding.
  • The rotation checklist is a product feature that turns revocation from a cryptographic ceremony into an operational task.

Alternatives considered

  • Re-encrypt every file on revocation. Rejected: no security gain against a party who holds history; maximal conflict surface.
  • Delete old epoch wrap directories. Rejected: no security gain, and it removes legitimate members' access to old events unless everything is re-wrapped.