Skip to content

0006: Signed events and a signed policy chain: integrity, not prevention

  • Status: accepted
  • Date: 2026-09-22
  • Amended by: 0043 (the causal-past rule also covers role reductions, for policy records; proposed; superseded by 0046), 0046 (policy is a linear chain replayed in slot order, chain order replaces the causal-past rule for policy records, the demotion quorum is removed, and anti-rollback pins the chain tip)

Context

With client-side cryptography and no server, any member holding a KEK can decrypt, modify and re-encrypt data and push the result. Preventing that is impossible without a server; detecting and ignoring it is not.

Decision

  • Every event and every policy event is signed by the author's device key (Ed25519 for x25519 device keys, ECDSA P-256 over SHA-256 for p256 device keys, ADR 0002). Unsigned or badly signed files are ignored and reported.
  • Roles are assigned by an append-only policy chain of signed events: admin, writer, reader and rotator. There is no machine role: a machine identity is a member carrying a machine flag, holding any one of the four roles, usually reader (ADR 0008). Policy events are themselves ordered in the causal DAG.
  • A client verifies each event's author against the policy state at that event's causal position. Events by unauthorised authors are excluded from the fold and surfaced as rejected, with the author identified.
  • Causal-past rule for revocation. Because an author controls their own parents, "authorised at the event's position" alone permits backdating. Therefore an event by key K is valid only if it is in the causal past of every revocation of K, that is, the revoking admin had already observed it. Events by K concurrent with or after the revocation are rejected. The mirror rule applies to grants: an event is valid only if the grant is in its causal past. Legitimate writes that race a revocation are therefore dropped; clients list them so an admin can review and re-apply.
  • Demoting or removing an admin requires signatures from M of N current admins, counting the proposer's own signature (default: a majority of current admins, and therefore at least 2 when N >= 2), expressed as approval events referencing the proposal.
  • Anti-rollback, local-first. Each client records the head ids it last folded. If a fetched history does not contain those heads, the client refuses to proceed and reports a possible rollback. In-repository head attestations are optional and never relied upon.
  • Where real prevention is wanted, it is provided server-side: a CI check (vaultfold verify) as a required status on the default branch, or the hosted service (ADR 0010), which validates signatures against policy before accepting a write.

Consequences

  • Unauthorised changes never take effect on a correct client and are attributable. This is the honest guarantee and is documented as such.
  • Reads cannot be audited or prevented by the format; only the hosted service can do that (ADR 0010).
  • A reader holds KEKs and can decrypt; the role only governs whose writes are accepted.

Alternatives considered

  • Rely on git commit signing. Rejected: not portable to other backends, and commits can bundle arbitrary files.
  • Server-only enforcement. Rejected as the sole mechanism: the git backend must be usable without any server.