0044: Exposure audit after revocations
- Status: accepted
- Date: 2026-10-26
- Change:
audit-exposure(archived; design inopenspec/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
- 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
lostrevocation (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. - Listing is by secret field. The primary field, hidden fields,
noteson 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. - 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--markare refused in agent sessions (exit 2, no override). - Unchanged values are refused (decision 9).
addon a secret field of an existing entry androtate --donerefuse 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 --donerefuses an unchanged value in any field, secret or not;addrefuses only when the field it writes is secret. - 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
--marknever touches them. - 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.
- Touch confirmations (G3-Q1). A collection with touch policy
alwaysasks one confirmation per held epoch during an audit, the same asget,lsandrotate, as agent-daemon "Touch re-prompt" requires. Batching needs a daemon protocol change and is a follow-up ticket (01M5V9R3A9). - Report, not gate. The audit exits 0 whatever it finds; scripts
read
outstandingfrom--json.vaultfold epoch newexists so alostrevocation 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.