Skip to content

0044: Exposure audit after revocations

  • Status: accepted
  • Date: 2026-10-26
  • Change: audit-exposure (archived; design in openspec/changes/archive/2026-10-26-audit-exposure/design.md)

Context

Offboarding without guessing is a product promise: after a member or a device is revoked, vaultfold says which secrets that party could have read, so they can be rotated at the source. The main specs promised the audit but defined "rotated" two ways (a rotation marker, and the needs_rotation meta the revocation itself writes), neither of which is the security fact, and the fold kept only current values. Several rulings made during the change are durable product rules, so they are recorded here.

Decision

  1. Exposure is judged per value by epoch. A value is exposed to a revoked party when the put that wrote it was written under an epoch the party held. A snapshot that re-encrypts state does not change a value's epoch. A put clears exposure only when written under an epoch the party never held, so a stale-epoch put, or any put after a lost revocation (which mints no epoch), is still exposed. Rotation markers drive the checklist but neither establish nor clear exposure. Superseded keys (key rotate) are not revoked parties.
  2. Listing is by secret field. The primary field, hidden fields, notes on every type, and any undefined field or field of an unknown type count as secret. A login with a rotated password and an unchanged TOTP seed is still listed. The audit is the authority on exposure; the checklist is a to-do list.
  3. Value provenance (decision 11). A live secret is also exposed, with reason reused-value, when its plaintext equals a value the party could decrypt or wrote (any put, even rejected). The audit compares only the caller's own decryptable history, as HMAC digests under a per-run random key, keeping no plaintext. Because a match is an equality oracle, the audit and --mark are refused in agent sessions (exit 2, no override).
  4. Unchanged values are refused (decision 9). add on a secret field of an existing entry and rotate --done refuse a value equal to the current one, since the put would clear the marker or epoch row and change nothing at the source. G4-11: rotate --done refuses an unchanged value in any field, secret or not; add refuses only when the field it writes is secret.
  5. Removed while exposed (decision 12). Entries and secret fields removed while their last value was exposed stay in a separate section, permanently, with the remedy "revoke or rotate at the source"; every removal cycle is judged and --mark never touches them.
  6. Visibility. The audit lists entries from the caller's own fold only, and for epochs the caller does not hold it reports the collection (by name if readable, else id) and epoch numbers, never a count or path. Every run prints the honest limit: what the party saw outside the vault, or re-entered from a differing outside copy, cannot be detected.
  7. Touch confirmations (G3-Q1). A collection with touch policy always asks one confirmation per held epoch during an audit, the same as get, ls and rotate, as agent-daemon "Touch re-prompt" requires. Batching needs a daemon protocol change and is a follow-up ticket (01M5V9R3A9).
  8. Report, not gate. The audit exits 0 whatever it finds; scripts read outstanding from --json. vaultfold epoch new exists so a lost revocation has a remedy.

Consequences

  • No vault format change and no new policy record kind; one core API, vault.ForEachPut.
  • The audit lists what this copy of the vault can show was exposed. It cannot see compacted or unfetched history, so "nothing still exposed" is never "safe".
  • member ungrant (role removal without revocation) is not covered; a follow-up change is planned.