Skip to content

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.

  • 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).

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.

Terminal window
vaultfold member list
vaultfold member revoke bob
vaultfold epoch list

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.

Terminal window
vaultfold device list gil
vaultfold device revoke 144e8ff6 --grade compromised

A 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:

Terminal window
vaultfold epoch new prod

epoch 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.

Both revoke commands finish by printing the audit command to run next (--member <name> or --device <key id>). Sync, then run it:

Terminal window
vaultfold sync
vaultfold audit exposure --member bob

Sync 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:

Terminal window
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.

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.

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 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.

Terminal window
vaultfold rotate
printf '%s' "db-pass-2-FAKE" | vaultfold rotate --done app/db#password --stdin
vaultfold rotate
vaultfold sync

To replace your own identity's key, for example to move it into the OS keychain, use vaultfold key rotate.

  • Vault commands start the agent daemon and unlock once. Set VAULTFOLD_NO_AGENT=1 to 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 lost leaves 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 prod collection, the audit asks you to confirm once for each epoch of it you hold, as get does for each read.
  • key rotate is refused in an AI agent session.