Key management

In an encrypted version-control system your keys are not a convenience — they are the only thing that can decrypt your protected files. This page explains where your keys live, why they never leave your machine in the clear, how recovery keys save you from lock-out, and how rotation works.

Losing your key is a data-loss event

In Git, if you lose access you re-clone. In TOVIO, a protected file you can no longer decrypt stays opaque ciphertext forever. This is why a Team repository generates a recovery key alongside its identity, and why you must escrow it. Treat your identity key and recovery key with the same care you would a master password — because that is effectively what they are.

Where keys live

Every TOVIO identity holds two private keys: an Ed25519 signing key and an X25519 key-agreement key. Both are stored on disk, and both are encrypted at rest.

• Identity private keys live under .tovio/identity/; cached wrapped or derived content keys live under .tovio/keys/.
• On disk, each key is sealed with authenticated encryption (AES-256-GCM in the shipped keystore; the specification also permits ChaCha20-Poly1305). The wrapping key for that seal is held in your operating system's keychain — macOS Keychain, Windows Credential Manager, or Linux Secret Service. The keychain stores the wrapping key, not your TOVIO keys themselves.
• Secret material is zeroized from memory as soon as it is no longer needed, and is never written to logs or the op-log.

This means that to recover a key from a powered-off or locked stolen device, an attacker must first defeat the OS keychain and your full-disk encryption.

The one rule: no key material in objects/

This is the hard invariant that makes the whole model safe to sync:

Key material never enters the synced object store

No private key, recovery key, or unwrapped content key is ever written into objects/ — the content-addressed store that replicates to peers and the relay. If it never enters objects/, it never syncs and never reaches the wire. tovio fsck scans the store for leaked private-key material as a backstop — an advisory warning by default, a failure under --strict — and the invariant itself is held by the write paths and their regression tests.

The practical consequence: the relay or Forge object store holds protected ciphertext and per-recipient wrapped keys, without the recipient secret needed to unwrap them. Compromising that storage/API view alone does not directly decrypt the payload. Authorized endpoints, Tier-1 KA recipient decisions, explicit runner/agent disclosures, metadata, and plaintext copied outside TOVIO remain separate risks.

Recovery keys — don't skip this

Because losing your key loses your data, TOVIO generates a recovery key at the moment a repository gains a cryptographic identity — tovio init --mode team or --mode agentic, tovio clone, or tovio identity init upgrading a Simple repository. It is an independent X25519 keypair added as an extra recipient of every protected object, so it can re-derive your access. Its secret is shown once, as a 64-character hex recovery phrase: printed on an interactive terminal, or — when the command runs non-interactively, piped, or with --json — written to .tovio/tovio-recovery-key.txt (owner-only, inside the never-committed .tovio/ directory) with the path reported. Only the public half stays on disk afterwards, at .tovio/identity-recovery.pub.

A Simple (Solo) repository has no recovery key

tovio init --mode simple is keyless: it mints no identity and therefore no recovery key, and a Tier-0 seal has exactly one recipient — you. Losing that single key is already total, unrecoverable loss of every protected file; there is no second key to fall back on. If you protect anything you cannot afford to lose, run tovio identity init to upgrade to Team, which mints the identity and the recovery key together. Everything in the rest of this section — recovery phrases, key export/import, devices — begins at that upgrade.

Escrow your recovery phrase before your first protected commit

Move the phrase somewhere safe — a printed copy or a password manager — before you commit your first protected file, and delete the escrow file once you have. A Key-Authority-held or KMS/HSM escrow for Team/Enterprise is a later, evidence-gated target, not a current option. The recovery key, like any identity key, never enters objects/.

To restore access after losing your identity key, point recover at the file holding the phrase:

tovio key recover --from <recovery-phrase-file>

This installs a fresh identity and re-wraps the protected content at HEAD to it, so you can read your files again. Three consequences are worth knowing before you run it:

• The audit chain starts a new segment. Entries signed by the lost key cannot be bridged to the new one, so they are kept but orphaned; tovio audit verify succeeds on the fresh segment.
• Teammates and devices may be dropped. On a Team repository, access claims signed by the lost key no longer verify, so the re-seal reaches only you (and the recovery key). recover names every dropped recipient; re-grant them with tovio access grant and re-approve devices with tovio device approve.
• Rotated-away content stays lost. Recovery restores currently-held and future access; it cannot recover content whose keys were rotated away while your key was lost.

A different pair of commands covers the planned case: tovio key export writes a passphrase-encrypted backup of the root device key (AES-256-GCM under an Argon2id-derived key, passphrase read from a file), and tovio key import restores the same identity on another machine. Use export/import for moves and escrow; use recover only when the key itself is gone.

Losing both keys is unrecoverable

Nobody escrows your recovery phrase for you — on a Team repository you hold both the identity key and the recovery phrase, and losing both means the data is gone for good. Enrolling a second device (tovio device enroll on the new machine, tovio device approve on a trusted one) gives another machine its own key, so one lost laptop is not the only key holder. A Key-Authority-held or threshold/KMS-backed Enterprise escrow is a future, evidence-gated target, not a currently available recovery option.

Identity key rotation

Rotating your own identity keys — for hygiene, or because a device may be compromised — works through a signed rotation statement that proves continuity:

1. TOVIO generates a new keypair and a rotation statement naming the old and new public keys, signed by the old signing key.
2. The statement is published to the Key-Authority registry (Team mode) or recorded locally (Solo mode).
3. New signatures use the new key; new content-key wraps target the new key-agreement key.
4. Your old key is retained, encrypted at rest, until no still-needed object is wrapped only to it — so you can still read older content during the transition.

Rotation history is kept as a verified chain anchored at the repository's genesis key: each statement's signature must verify under its outgoing key, and a reader will refuse an old key from a rotation chain that fails to verify — closing a planted-chain attack. Rotation is also crash-resumable: at every interruption point the repository stays fully readable and the rotation can be resumed or rolled back.

Rotating the Key-Authority key re-issues teammate claims

When the rotated identity is also the repository's owner/Key Authority, rotation does more than swap your keys: every still-valid attribute claim issued under the old owner key is re-issued (re-signed) under the new key, and the per-actor audit chain is continued — not rewritten — across the rotation. Otherwise every teammate's claim, signed by the now-retired key, would silently stop verifying.

DEK rotation — how revocation actually works

Removing a reader is a different operation from rotating your own identity. To revoke someone's read access to a policy, TOVIO rotates the data encryption key: it generates a fresh key, re-encrypts the affected content, and re-wraps the new key for the remaining recipients only.

Revocation protects future content, not past disclosures

Re-encrypt-on-rotate is the same tradeoff every envelope-encryption system makes. The revoked reader can no longer decrypt future content. But anything they already decrypted is outside TOVIO's control and cannot be un-decrypted. Revoking does not — cannot — reach into a copy someone already holds. Plan revocations with that reality in mind; for genuinely burned secrets, rotate the secret itself (e.g. issue a new API key), not just its TOVIO encryption.

Granting access, by contrast, is cheap and additive: it only adds a wrapped key copy, with no re-encryption.

If a device is lost or stolen

Treat a lost unlocked device as a key compromise and act fast:

1. Revoke the device and any tokens it held. tovio device revoke drops the enrolled device and re-seals HEAD's protected content to the remaining device set; tovio agent revoke revokes a token together with everything delegated from it (agent tokens additionally self-expire via their required expiry, which bounds the window); tovio access revoke is the equivalent for a whole teammate identity.
2. Rotate the identity's keys with tovio key rotate — an outgoing-key-signed rotation statement that re-issues claims and re-seals HEAD before swapping the key.
3. Rotate the secrets themselves where the device may already have decrypted them — every re-seal above protects future content only.

For a powered-off or locked device, your exposure reduces to the platform's at-rest protections plus your passphrase hygiene. The irreducible residual is that content the device already decrypted is exposed and cannot be recalled — rotation only protects content produced afterward.

A short checklist

• [x] Escrow your recovery phrase as soon as the repository has one, before your first protected commit, and back up the root device key with tovio key export. Both are Team-repository commands — on a Simple repository they have no identity to work with, so upgrade with tovio identity init first.
• [x] Keep full-disk encryption on — it is the second lock under the OS keychain.
• [x] Rotate keys on a schedule and immediately on any suspected device compromise.
• [x] Remember that revocation is forward-only — for a leaked secret, rotate the secret, not just its encryption.
• [x] Never try to "protect" a secret with .tovioignore — use a read policy so it lives encrypted in the repo. See cryptography.

Related: the trust model that makes untrusted servers safe is in the threat model; the audit record of grants, revocations, and rotations is in compliance.

Last reviewed September 9, 2026

Suggest an improvement to this page  ·  Not for security reports — see disclosure