Revoke access and rotate secrets
Revoking a key stops it reading anything new, but it already holds every secret it could read. So revocation is followed by rotation: replace those secrets at their source and record the new values.
Prerequisites
Section titled “Prerequisites”- You are an admin (or rotator) of the vault.
- You can reach the services behind the secrets, to change the real passwords and keys.
- The vault's remote is reachable. Revoking and minting epochs pull first and publish in the command, so offline they exit 4 and write nothing.
- Everyone else syncs afterwards, so they receive the new epoch (see sync and conflicts).
Revoke a member
Section titled “Revoke a member”Revoking a member revokes all of their devices and mints a new epoch that
they never receive. The output ends with the rotation checklist size. On a
terminal it asks whether the device is lost or compromised and then to
confirm; without a terminal pass --yes. The revocation is final once the
command reports it published: nothing bob signs afterwards counts, whatever
time it claims.
vaultfold member listvaultfold member revoke bobvaultfold epoch listRevoke one device
Section titled “Revoke one device”The argument is a device name or a key id prefix of at least 8 hex characters.
Devices are named after the identity that made them (often default), so a
name can match several members; list the devices and use the key id prefix.
Use the grade that matches what happened. lost means the device is locked
and no new epoch is minted; compromised mints one.
vaultfold device list gilvaultfold device revoke 144e8ff6 --grade compromisedA device revoked as lost mints no new epoch, so anything written from now
on is still readable by whoever can unlock it. Mint one yourself, in each
collection the device could read, before you replace any values:
vaultfold epoch new prodepoch new needs you to be an admin or rotator of the collection (or a root
admin), asks you to confirm on a terminal (pass --yes without one), and is
refused in an AI agent session.
See what they could read
Section titled “See what they could read”Both revoke commands finish by printing the audit command to run next
(--member <name> or --device <key id>). Sync, then run it:
vaultfold syncvaultfold audit exposure --member bobSync first, so the audit includes what other members have written. Use
--device <name or key id prefix> for one device and --since <date> to
look only at recent revocations. The audit is for a person, so it is refused
in an AI agent session.
It lists the entries a revoked party could read and still can, sensitive
collections (prod) first and then the oldest. Each row names the secret
field and the epoch, and says what to do next: vaultfold rotate --done for
an entry on the checklist, vaultfold audit exposure --mark and then
vaultfold rotate for an entry not on it, or vaultfold epoch new <collection> when the party still holds the collection's current epoch, so
a new value would be readable too. A separate section, "removed while exposed", lists entries that
were deleted after the party could read them. The credential still works at
its service, so revoke or rotate it there; nothing in the vault clears the row.
An entry that is exposed but not on the checklist can be added to it:
vaultfold audit exposure --member bob --mark--mark flags those entries as needing rotation, so vaultfold rotate then
shows them. It skips rows where a new epoch is needed first, collections you
cannot write to, and entries whose only exposed values are reused values
written in an AI agent session (check those at their source). Each skipped
entry gets a line saying why.
Why the audit and the checklist can disagree
Section titled “Why the audit and the checklist can disagree”rotate counts an entry as done after one new value. The audit keeps listing
it while any other secret field of the entry is unchanged (a login whose
password was replaced but whose totp seed was not), or when the new value
was written under an epoch the party held (for example by a teammate who had
not synced yet, or after a lost revocation). The row says which.
A row marked reused-value was written under an epoch the party never held,
but its value equals one they could read: the old value written back,
re-added, or copied from another entry. A new key does not help when the
secret itself is the same.
Unchanged values are refused
Section titled “Unchanged values are refused”Because a put of the same value would look rotated while nothing changed at
the service, vaultfold add refuses to write a secret field's current value
back to an existing entry, and vaultfold rotate --done refuses an unchanged
value in any field. Both exit 1, write nothing and print no value. A script
that re-runs add with the same value now fails; treat the "unchanged" error
as success.
What the audit does not say
Section titled “What the audit does not say”The audit lists what this copy of the vault can show was exposed. It cannot see a value the party saw somewhere other than the vault, or one re-entered from an outside copy that differs, and it cannot compare history that was removed by compaction or has not been fetched. An empty audit means nothing more is known, not that nothing was seen. A collection whose earlier epochs you do not hold is reported as not listed; ask a member who holds them to run the audit.
Rotate what they could read
Section titled “Rotate what they could read”rotate lists the entries on the checklist, the ones the revoked keys could read. Change each value at
its service, then record the new value; it is read from a hidden prompt or from
standard input.
vaultfold rotateprintf '%s' "db-pass-2-FAKE" | vaultfold rotate --done app/db#password --stdinvaultfold rotatevaultfold syncTo replace your own identity's key, for example to move it into the OS
keychain, use vaultfold key rotate.
Current limitations
Section titled “Current limitations”- Vault commands start the agent daemon and unlock once. Set
VAULTFOLD_NO_AGENT=1to skip the daemon and unlock in-process for that command only. - Revocation cannot take back what a key already read. Rotating at the source is the only remedy.
- A device revoked as
lostleaves existing entries readable to whoever can unlock it. - The audit reports only what this copy of the vault can show; see "What the audit does not say" above.
- On a
prodcollection, the audit asks you to confirm once for each epoch of it you hold, asgetdoes for each read. key rotateis refused in an AI agent session.