# Recovery

Witbitz deliberately has no operator recovery key. If the platform could recover a Space, the platform could read a
Space. Recovery must therefore belong to the user or organization, not to Witbitz as operator.

This page explains the current tradeoff and the roadmap. The full lifecycle discussion is in
[The Verified Room](./room-link-auth.md).

---

## Current rule

If every copy of the room key is lost, the Space is lost.

That is not a product flourish; it is the cost of the privacy claim. It is also why the **user-held vault** below
exists — the way out is to hold your own spare key, never for the operator to hold one for you. The production envelope is sealed to the room key,
not to an operator, support, escrow, or beta recipient. There is no backdoor recipient to call later.

You can verify that with the sealed-store check:

```bash
curl -sX POST "$SPACE" \
  -H 'content-type: application/json' \
  -d '{"op":"sealed","room":"<ROOM>"}'
```

The recipients list should name the room, not the operator.

Read: [Verify it yourself](./verify.md)

## What recovery should be

Recovery can exist, but it must be user-held:

| Mechanism | Owner | Status |
|---|---|---|
| Passkey | The user's platform syncs or protects it. | **Shipped** |
| Backup code | The user stores it. | **Shipped** |
| k-of-n social recovery | Several trusted parties hold shares. | Not built |
| Organization key policy | The customer controls it in its own boundary. | On-prem |

None of these require Witbitz to hold a readable recovery recipient.

## The shipped vault

One vault per account, and **either** enrolled method opens it:

1. A random 32-byte **master secret** identifies and encrypts the vault.
2. Each method stores one **wrapper** — the master secret sealed to that method's own secret.
3. Restoring with any enrolled method opens its wrapper, recovers the same master secret, and opens the one backup.

So a passkey and a backup code are not two backups to keep in sync; they are two doors into the same room. Adding or
replacing a method rewrites a wrapper, never the data.

The server stays content-blind throughout: it stores opaque blobs at **derived** ids and never receives the code, the
passkey secret, the vault key, or any plaintext. Wrappers are written *before* the data they unlock, so a half-finished
enrolment can never leave a vault nobody can open.

## The offline export

Recovery that depends on the platform being reachable is not self-sovereign, so a Space can also be exported to a file
you keep, alongside a standalone decryptor page that opens it with no server at all.

The export is **opaque by construction**. An earlier version wrote each Space's `room`, `title` and message `count` in
the clear next to its sealed ledger — the file was handed to iCloud or Drive as "unreadable ciphertext" and was, except
that it announced every conversation's name, id and size to anyone who opened it in a text editor. That metadata is now
sealed under the same room key as the ledger it describes, so the decryptor recovers the real names once you load your
keys file and shows "Conversation N" until you do.

Two things remain visible by construction: **how many** conversations the bundle holds, and **when** it was exported.
Hiding the count would mean padding with decoys, which costs more than it buys for a personal backup.

## What the Companion would add

The optional Companion was originally imagined as a native runtime for notifications, durable keys, and local decrypt.
Much of that is now possible with the installed web app and passkeys, so the Companion is no longer a platform pillar.

It may still improve recovery ergonomics:

- keep room keys in a device keystore
- make rotation less dependent on pasted links
- deliver new epoch keys to devices instead of URLs
- provide more reliable background notifications

Read: [The Companion](./the-companion.md)

## Enterprise/on-prem recovery

In an on-prem deployment, the organization controls the runtime boundary. That can include its own backup policy,
identity provider, secret storage, and recovery procedure. The privacy story changes from "trust Witbitz not to read"
to "verify the image you run and control the boundary yourself."

Read: [Enterprise and on-prem](./on-prem.md)

## What not to promise

Do not promise that Witbitz can recover a lost Space on hosted production. It cannot, by design.

Do not hide the user burden. User-held recovery is safer than operator-held recovery, but it still requires a recovery
artifact, another device, a passkey sync provider, a social recovery set, or an organizational process.