Operators Guide

Vault recovery

Provision a dedicated recovery key, protect collections, and restore ownership after owner loss.

Vault recovery

Recovery lets you decrypt a collection or grant a replacement owner when its original owner is no longer available. It uses a dedicated X25519 recovery identity, separate from normal Vault clients. Each protected collection has an additional encrypted copy of its collection key for that identity.

Recovery must be provisioned before access is lost. A controller flag cannot recover an existing collection without recovery wrapping or a surviving authorized client. Recovery does not grant ordinary secret access to rescile-controller.

Recovery is available in all deployment modes. Use builds whose --help lists the recovery options.

Deployment Recovery bootstrap Offline recovery commands
CE all-in-one rescile-ce --vault … --vault-controller-recovery … serve rescile-ce vault recovery …
EE all-in-one rescile-ee --vault … --vault-controller-recovery … serve rescile-ee vault recovery …
Standalone Vault rescile-vault-server --vault … --vault-controller-recovery … --vault-schema … rescile-vault recovery …

The standalone client is distributed as rescile-vault. All clients and servers share recovery operations, persisted types, and key-file formats. A key created with one client works with the other clients. The standalone client does not depend on a running controller or its library.

First launch

Create a private directory for the key. Its parent directory must already exist.

install -d -m 700 ./recovery
rescile-ce --vault ./vault.json \
  --vault-controller-recovery ./recovery/vault-recovery.key serve

For EE:

rescile-ee --vault ./vault.json \
  --vault-controller-recovery ./recovery/vault-recovery.key serve

For a standalone Vault server, supply its desired Vault schema as usual:

rescile-vault-server --vault ./vault.json \
  --vault-schema ./vault-schema.json \
  --vault-controller-recovery ./recovery/vault-recovery.key \
  --host 127.0.0.1 --port 8002

The schema file is the normal exported Vault schema, not a recovery-key file. The standalone server also supports its existing --artifact-url schema source instead of --vault-schema.

The key argument names a private key file, not a public recipient file.

Vault file Private key file Result
Missing Missing Generate and persist the key, then create a Vault bound to its public identity.
Missing Present Create a Vault using that recovery identity.
Present Present Require the stored recovery identity to match.
Present Missing Fail. Restore the original key; do not generate a replacement.

An existing Vault with no recovery identity must be enrolled by an authorized owner with vault recovery enable. Startup never silently enrolls or replaces its identity. Malformed keys, identity mismatches, symlink file paths, and insecure private-key permissions fail closed. On Unix, generated key files have mode 0600; reading a private key accessible to group or others is refused.

Key and Vault writes are atomic. The private key is made durable before the Vault is created. If initialization stops after key creation, the next launch reuses it. Neither initialization nor export overwrites an existing output file.

Keep the private key offline

A private key readable by the controller is online recovery. A compromised controller account could use it to recover every protected collection.

  1. Export the public recipient. This command needs no running Vault server.
  2. Back up the private key separately from Vault backups. Verify the backup through a recovery drill against a copy of the Vault.
  3. Move the private key to secure offline storage.
  4. Start normal service operation with only the public recipient file.
rescile-ce vault recovery public-key \
  --private-key ./recovery/vault-recovery.key \
  --output ./recovery/vault-recovery.pub

rescile-ce --vault ./vault.json \
  --vault-recovery-recipient ./recovery/vault-recovery.pub serve

Standalone server equivalent:

rescile-vault-server --vault ./vault.json \
  --vault-schema ./vault-schema.json \
  --vault-recovery-recipient ./recovery/vault-recovery.pub \
  --host 127.0.0.1 --port 8002

Every server validates the public recipient against the identity stored in the Vault. It does not need the private key to protect newly created collections. The two startup flags are mutually exclusive. CE/EE require --vault; the standalone server also accepts its default Vault file path.

To create a keypair separately, before creating a Vault:

rescile-ce vault recovery init \
  --private-key ./recovery/vault-recovery.key \
  --public-key ./recovery/vault-recovery.pub

Offline client commands

The standalone client provides the same subcommands and options:

rescile-vault recovery init \
  --private-key ./recovery/vault-recovery.key \
  --public-key ./recovery/vault-recovery.pub

rescile-vault recovery public-key \
  --private-key ./recovery/vault-recovery.key \
  --output ./recovery/exported-recipient.pub

rescile-vault recovery status --vault-file ./vault.json

rescile-vault --clientname existing-owner recovery enable \
  --vault-file ./vault.json --recipient ./recovery/vault-recovery.pub --all

rescile-vault recovery promote-owner \
  --vault-file ./vault.json --collection production --client replacement-admin \
  --private-key /secure/offline/vault-recovery.key

rescile-vault recovery export \
  --vault-file ./vault.json --collection production \
  --private-key /secure/offline/vault-recovery.key \
  --output /secure/recovered-secrets.json

These examples show separate operations, not a batch script. Do not initialize a second keypair if you already generated one during server startup. Replace rescile-vault with rescile-ce vault or rescile-ee vault to use an integrated client. All offline recovery commands work directly with the local Vault file; no server URL or session is required.

Recovery-key operations do not use TPM keys. Owner-based recovery enable currently requires a password-based owner; --tpm is refused for enrollment. A dedicated recovery key can still recover a protected collection whose former owner used TPM.

Enroll existing collections

Stop all services using the Vault file. These commands operate locally and offline; --url is not used. They acquire the same exclusive file lock as the Vault server and refuse access while another process holds it.

Set RESCILE_VAULT_PASSWORD through your secure credential mechanism to the existing owner’s password. Avoid placing it in shell history or process arguments.

rescile-ce vault --clientname existing-owner recovery enable \
  --vault-file ./vault.json \
  --recipient ./recovery/vault-recovery.pub \
  --all

Use --collection production instead of --all to select one collection. The client must have the Owner role and decrypt the key of every selected collection. If any selected collection fails validation, nothing is enrolled. Different owners can enroll their collections separately using the same recovery recipient. Re-enrollment refreshes the selected recovery wrappings without changing ordinary membership. Replacing the configured recovery identity is refused; recovery-identity rotation is not implemented by these commands.

rescile-ce vault recovery status --vault-file ./vault.json

Status prints the public identity fingerprint and collection coverage: Missing or Wrapped (not verified). Wrapping metadata alone does not prove that your private-key backup works or that a client supplied the correct collection key.

Restore ownership

Stop the Vault service and back up its state before making a recovery change. The replacement client must already be enrolled in the Vault, with a known public key. Check its identity before promoting it.

rescile-ce vault recovery promote-owner \
  --vault-file ./vault.json \
  --collection production \
  --client replacement-admin \
  --private-key /secure/offline/vault-recovery.key

This unwraps the collection key, verifies that existing collection ciphers decrypt, and wraps the key for the replacement client’s public key with role Owner. It does not export plaintext secrets, remove existing owners, or grant the controller access.

Before restarting with --prune-orphans, update graph-managed client topology to retain the replacement owner. Otherwise synchronization can prune its membership. Revoke obsolete clients separately through normal owner operations.

Export secrets when necessary

rescile-ce vault recovery export \
  --vault-file ./vault.json \
  --collection production \
  --private-key /secure/offline/vault-recovery.key \
  --output /secure/recovered-secrets.json

The output is a new private JSON file containing the collection name and a secrets array. Each entry contains id, name, and value_base64 (URL-safe Base64 without padding). This supports binary secret values. Legacy unframed payloads use their cipher ID as the name. Base64 is not encryption: treat this file as plaintext secrets. Export never sends values to standard output and refuses an existing output path. A decryption failure aborts export.

Retention, audit, and compatibility

  • Collections with recovery wrapping survive automatic cleanup when their last client is deleted, reset, removed, or missing at startup. Their ciphers remain.
  • Recovery is not a backup or protection against deliberate deletion. Explicit collection deletion and --prune-orphans can delete protected collections.
  • Enrollment, ownership recovery, and export write metadata-only audit records to <vault-file>.recovery-audit.jsonl. Records include operation phase, timestamp, recovery fingerprint, collection, and target client when applicable. An attempt without completion needs investigation. Audit storage must be writable.
  • Updated integrated and standalone Vault clients obtain the server’s public recovery policy when creating collections. Recovery-enabled servers refuse creation or collection-key rotation without a recovery wrapping (412). Old clients may therefore need upgrading. The server validates wrapping structure; only a recovery drill verifies decryption end to end.
  • Back up both the Vault and recovery private key, but store them separately. Losing either can make recovery impossible. Use recovery-capable server versions for all writers; older servers do not preserve the new recovery metadata.
  • File-permission and locking tests cover Linux. Other operating systems need platform-specific permission and deployment verification.

See Secrets & Vault for normal roles, invitations, and secret access.