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.
- Export the public recipient. This command needs no running Vault server.
- Back up the private key separately from Vault backups. Verify the backup through a recovery drill against a copy of the Vault.
- Move the private key to secure offline storage.
- 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-orphanscan 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.