Shade/docs/recovery.md

Social Key Recovery (@shade/recovery)

V3.10 closes the biggest UX hole in any E2EE system: "What happens if I lose my phone?". Shade's social-recovery flow lets a user designate n guardians (family / friends / co-workers) at setup time such that any threshold-many k of them can together restore the user's identity onto a new device — without any single guardian being able to do it alone, and without the prekey server ever seeing the recovered key material.

The whole flow ships entirely over existing 1:1 Shade sessions; no server-side recovery agent, no escrow service, no "cloud guardian".

---

Threat model recap

#	Adversary	Recovered?
1	Coalition of ≤ k-1 guardians	No (information-theoretic, by Shamir construction)
2	Prekey server alone	No (server only relays Double-Ratchet ciphertext)
3	Single malicious guardian who forges a share	Detected — AES-GCM tag mismatch on the backup blob; requestRecovery exhaustively tries threshold-sized subsets and rejects when none authenticate
4	Social engineering (impersonator calls a guardian)	Mitigated, not eliminated — guardians MUST OOB-confirm the new device's safety number before approving (see <RecoveryApprove />)
5	Compromised guardian device	Out of scope — see "Guardian compromise" below
6	Compromised primary device at setup time	Out of scope — recovery only protects the device; if setup material is exfiltrated, all bets are off

---

Setup

What the user does

1. Pick n guardians from their existing peers.
2. Pick a threshold k (typically ⌈n/2⌉ + 1 to avoid pure-majority dominance but still survive losing one or two).
3. Run setupRecovery(...).
4. Print / record a recovery card with:
   • The user's own address
   • setupId
   • k and n
   • The list of guardian addresses
   • Setup-time safety number

The recovery card is the only piece of state the user must remember out-of-band (or store in a password manager). Without it, the user cannot drive recovery on a new device — the new device needs to know who the guardians are.

What happens cryptographically

recoveryKey = random(32 bytes)
backupBlob  = Shade.exportBackup(passphrase = "shade-rk:" + base64url(recoveryKey),
                                 knownAddresses = [...])
shares[i]   = Shamir-split(recoveryKey, k, n)

For each guardian i:

share-deposit envelope:
  shadeRecovery: 1
  type:          "share-deposit"
  flowId, setupId, originalAddress
  threshold (k), guardianCount (n), shareIndex (i)
  shareBytes:    base64url( encodeShare(shares[i]) )
  backupBlob:    Shade.exportBackup output (identical for every guardian)
  setupFingerprint, createdAt

The envelope rides through Shade.send like any other plaintext — double-ratchet encrypted, AAD-bound, replay-safe.

The recoveryKey is zeroized on the primary device immediately after the split returns. The primary therefore retains nothing except setupId and the public roster.

What each guardian stores

Per (originalAddress, setupId):

{
  shareIndex,            // 1..n
  shareBytes,            // base64url-encoded Shamir share
  backupBlob,            // identical for every guardian
  setupFingerprint,      // for sanity-checks at recovery time
  guardianCount, threshold,
  receivedAt
}

The guardian's app provides a RecoveryStore implementation. The package ships MemoryRecoveryStore for tests and small one-shot demos; production guardian apps MUST supply a persistent store (IndexedDB, AsyncStorage, SQLite, etc.). See "Persistence recommendations" below.

---

Recovery

What the user does on the new device

1. Boot a fresh Shade with a temporary identity.
2. Read the recovery card.
3. In the recovery widget, type / paste:
   • originalAddress
   • setupId
   • threshold
   • The guardian roster
4. Read the new device's safety number (the widget displays it prominently) to each guardian over a side channel — phone call, in person, whatever they trust.
5. Wait for ≥ k guardians to approve.

What happens cryptographically

For each guardian, the new device sends:

recovery-request envelope:
  shadeRecovery: 1
  type:          "recovery-request"
  flowId, originalAddress, setupId
  requesterFingerprint  (= safety number of the temporary identity)
  requestedAt

Each guardian's attachGuardian handler:

1. Looks up its stored deposit by (originalAddress, setupId). If missing, replies with share-decline (reason = "unknown setup").
2. Invokes the approve callback with the requester's address + fingerprint + the original device's setup-time fingerprint. The callback is the OOB-confirmation gate — it MUST require an explicit user click after they verified the fingerprint. The <RecoveryApprove /> widget enforces this with a two-checkbox gate.
3. On approve → ships share-grant. On reject → ships share-decline with a short reason.

The new device collects grants, and as soon as k arrive:

1. Combines the k shares via Lagrange interpolation at x = 0 to reconstruct recoveryKey.
2. Derives passphrase = "shade-rk:" + base64url(recoveryKey).
3. Calls Shade.importBackup(backupBlob, passphrase) — the AES-GCM tag in the blob authenticates the reconstruction. A forged share is detected here.
4. If a guardian forged a share, importBackup throws. The reconstruction loop then tries every other threshold-sized subset of grants until one authenticates (the V3.10 acceptance criterion "no coalition of (k-1) guardians can rebuild the secret" is the safety invariant; the AEAD authenticates which subset is honest).
5. If every subset fails, RecoveryReconstructionError is raised and the user is told that at least one guardian is malicious.

After importBackup succeeds, the new device hosts the original identity and immediately calls Shade.rotate() to retire the recovery-recovered key material from the conversation graph (the old session keys persisted in the backup blob are now considered "compromised — used for recovery").

The Shade.beforeBackupImport gate fires automatically. Without a registered handler the SDK falls back to TOFU-with-warning (consistent with the V3.3 contract). Production apps SHOULD register a handler that pops the user one more confirmation before the identity rotates.

---

Acceptance criteria status

• 3-of-5 recovery works end-to-end on two separate Shade instances. See tests/integration.test.ts.
• No coalition of (k-1) guardians can reconstruct recoveryKey. Property test asserts this with fast-check across random k/n configurations. See tests/shamir.test.ts and tests/adversarial.test.ts.
• Guardian-side widget requires fingerprint-confirmation before sending. <RecoveryApprove /> enforces a two-checkbox gate; tests/adversarial.test.ts exercises both the matching-OOB and rejecting-OOB code paths.

---

Persistence recommendations

The RecoveryStore interface is intentionally small (4 methods). Pick the implementation that fits your platform:

Platform	Suggested backing store
Browser (PWA)	IndexedDB (one object store, idb)
Browser (extension)	chrome.storage.local
React Native	AsyncStorage (with crypto-protected blob)
Bun / Node server	SQLite via @shade/storage-sqlite extension table OR a side file
Android (native)	Room / EncryptedSharedPreferences

Whatever you pick, the records ARE NOT secret on their own — without threshold-many other guardians' shares they're useless — but they should still be stored encrypted-at-rest like any other Shade state. Do not commit them to plaintext logs or network-replicated state.

---

Guardian-UX guide

How many guardians?

n	Survives	Comment
3, k=2	1 lost guardian	Minimum useful — one device away from danger
5, k=3	2 lost guardians	Sweet spot for most users
7, k=4	3 lost guardians	Suitable when you genuinely have 7+ trustworthy people
n=k	0 lost	DO NOT USE — single point of failure

The widget defaults to k = ⌈n/2⌉ which is liberal but collusion-resistant for n ≥ 3. Apps targeting paranoid users may want to bump that to ⌈2n/3⌉.

Replacing a guardian

If a guardian dies, loses their device permanently, or you no longer trust them:

1. Pick a replacement.
2. Run setupRecovery again with the new roster — this generates a fresh setupId and a fresh recoveryKey. The old shares become garbage (no guardian set can use them, because the backupBlob is different).

The widget records the new setupId on the recovery card. Treat this as a hard rotation; the user MUST re-record the card.

Guardian health checks

Periodically (the V3.10 plan suggests a quarterly prompt), the user should confirm each guardian is still reachable. Any guardian who can't be reached in two consecutive prompts SHOULD trigger a re-setup with a fresh roster. The widget UX track is to be added in a follow-up release; the primitive is in place.

---

Wiring example

import {
  setupRecovery,
  attachGuardian,
  requestRecovery,
  MemoryRecoveryStore,
} from '@shade/recovery';

// On the primary device:
const result = await setupRecovery({
  shade,
  guardians: ['bob', 'carol', 'dan', 'eve', 'faythe'],
  threshold: 3,
  deliver: async (to, envelope) => {
    // wire to your app's existing message-delivery layer
    await myMessageOutbox.send(to, envelope);
  },
});
console.log(result.setupId);

// On each guardian device:
const stop = attachGuardian({
  shade,
  store: myPersistentStore,             // see "Persistence" above
  approve: async (ctx) => {
    // Show ctx.requesterFingerprint to the user.
    // Block until they confirm OOB and click "Release share".
    return await myUI.askApproval(ctx);
  },
  deliver: myMessageOutbox.send,
});

// On the new device:
const recovered = await requestRecovery({
  shade: temporaryShade,                // fresh identity for now
  originalAddress: 'alice',
  setupId: 'sid-from-recovery-card',
  threshold: 3,
  guardians: ['bob', 'carol', 'dan', 'eve', 'faythe'],
  deliver: myMessageOutbox.send,
  onProgress: (p) => myUI.showProgress(p),
});
// `temporaryShade` now hosts the original identity.

---

Out of scope (V3.10)

• Cloud guardian / Shade-operated recovery agent. Explicit non-goal; the spec rejects any centralized component that can recover on its own.
• Auto-distribution. The user must explicitly pick guardians.
• Multi-share-per-guardian. Each guardian holds exactly one share. Apps that need redundancy should bump n, not give the same guardian multiple shares.
• Guardian ZK-proofs of liveness. A guardian who refuses to respond is treated as offline; we don't try to compel them.