# `@shade/recovery`

Social key recovery for Shade — V3.10.

Shamir Secret Sharing over GF(2^8) splits the user's identity backup
key into `n` shares; any threshold-many `k` together reconstruct the
identity onto a new device. Distribution and reconstruction ride
existing 1:1 Shade sessions — no centralized recovery agent.

## Install

```bash
bun add @shade/recovery
```

## Quick wire-up

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

// Primary (Alice's existing device)
await setupRecovery({
  shade,
  guardians: ['bob', 'carol', 'dan', 'eve', 'faythe'],
  threshold: 3,
  deliver: async (to, envelope) => myOutbox.send(to, envelope),
});

// Each guardian
attachGuardian({
  shade,
  store: new MemoryRecoveryStore(),    // swap for persistent store in prod
  approve: async (ctx) => askUser(ctx),
  deliver: async (to, envelope) => myOutbox.send(to, envelope),
});

// New device (Alice on a fresh phone)
await requestRecovery({
  shade: tempShade,
  originalAddress: 'alice',
  setupId: '<from recovery card>',
  threshold: 3,
  guardians: ['bob', 'carol', 'dan', 'eve', 'faythe'],
  deliver: async (to, envelope) => myOutbox.send(to, envelope),
});
```

See [`docs/recovery.md`](../../docs/recovery.md) for the full
threat model, persistence recommendations, and guardian-UX guidance.

## Tests

```bash
bun test                    # all
bun test tests/shamir       # Shamir primitives
bun test tests/integration  # 3-of-5 end-to-end
bun test tests/adversarial  # k-1 collusion + forged shares + OOB-gate
```