Vauchi DocsContact Recovery Sequence
Interaction Type: 🤝 + ☁️ MIXED (In-Person Vouching + Remote Distribution)
When a user loses all devices, they can recover their contact relationships through social vouching. Existing contacts vouch for the user in-person, and the recovery proof is distributed remotely via relay.
Participants
- Alice - User who lost their device
- Alice's New Device - Fresh install, new identity
- Bob, Charlie, Betty - Alice's contacts who will vouch
- John, David - Alice's contacts who will receive recovery proof
- Relay - WebSocket relay server
Overview
┌────────────────────────────────────────────────────────────────────┐
│ PHASE 1: Vouching (In-Person) │
│ │
│ │
│ ┌─────────────────────────────────┐ ┌─────────┐ ┌────────┐ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ Bob │ │ Charlie │ │ Betty │ │
│ │ Vouch │ │ Vouch │ │ Vouch │ │
│ │ │ │ │ │ │ │
│ └────────────────┬────────────────┘ └────┬────┘ └────┬───┘ │
│ │ │ │ │
│ │ │ │ │
│ ├───────────────────────────┴───────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ │ │
│ │ │ │
│ │ Alice (new) │ │
│ │ Threshold: 3 vouchers │ │
│ │ │ │
│ └────────────────┬────────────────┘ │
│ │ │
└──────────────────┼─────────────────────────────────────────────────┘
│
│
│
┌──────────────────┼──────────────────────────────────────────────────────────────────────────────────┐
│ │ PHASE 2: Distribution (Remote) │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ │ │
│ │ │ │
│ │ OHTTP Gateway │ │
│ │ (strips client IP) │ │
│ │ │ │
│ └─────────────────────────────────┘ │
│ │ │
│ │ │
│ ├───────────────────────────┬───────────────┬───────────────────────┐ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────┐ ┌─────────┐ ┌────────┐ ┌──────────────────────────┐ │
│ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ Relay │ │ John │ │ David │ │ Others │ │
│ │ Stores proof under hash(pk_old) │ │ Accept │ │ Verify │ │ Discover via relay query │ │
│ │ │ │ │ │ │ │ │ │
│ └─────────────────────────────────┘ └─────────┘ └────────┘ └──────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────────────────┘
Note: All client↔relay traffic in Phase 2 is routed through an OHTTP gateway per ADR-037. The detailed sequence diagrams below omit the gateway hop for clarity — they describe the protocol layer, not the transport. Operationally, the relay never sees client IP addresses; the gateway never sees request content.
Phase 1: In-Person Vouching
┌─────────────────────┐ ┌──────────────────┐ ┌──────────────┐ ┌─────┐
│ Alice (Lost Device) │ │ Alice New Device │ │ Bob's Device │ │ Bob │
└──────────┬──────────┘ └─────────┬────────┘ └───────┬──────┘ └──┬──┘
│ │ │ │
│ Install Vauchi on new device │ │ │
│─────────────────────────────────▶ │ │
│ │ │ │
│ ├───┐ │ │
│ │ │ Create new identity (pk_new) │
│ ◀───┘ │ │
│ │ │ │
│ I had identity pk_old │ │ │
│─────────────────────────────────▶ │ │
│ │ │ │
│ ├───┐ │ │
│ │ │ Store recovery claim: pk_old → pk_new │
│ ◀───┘ │ │
│ │ │ │
│ Generate recovery QR │ │ │
│─────────────────────────────────▶ │ │
│ │ │ │
│ ├───┐ │ │
│ │ │ Create recovery claim QR │
│ ◀───┘ │ │
│ │ │ │
│ │ ┌────────────────────────┐ │
│ │ │ QR contains: │ │
│ │ │ - type: recovery_claim │ │
│ │ │ - old_pk: pk_old │ │
│ │ │ - new_pk: pk_new │ │
│ │ │ - timestamp │ │
│ │ └────────────────────────┘ │
│ │ │ │
│ Display recovery QR │ │ │
◀─────────────────────────────────│ │ │
│ │ │ │
│ │ │ Scan Alice's recovery QR │
│ │ ◀─────────────────────────────────────│
│ │ │ │
│ │ ├───┐ │
│ │ │ │ Decode recovery claim │
│ │ ◀───┘ │
│ │ │ │
│ │ ├───┐ │
│ │ │ │ Lookup pk_old in contacts │
│ │ ◀───┘ │
│ │ │ │
│ │ ├───┐ │
│ │ │ │ Found: "Alice" with pk_old │
│ │ ◀───┘ │
│ │ │ │
│ │ │ Alice claims device loss │
│ │ │─────────────────────────────────────▶
│ │ │ │
│ │ │ Show Alice's stored name & photo │
│ │ │─────────────────────────────────────▶
│ │ │ │
│ │ ┌──────────────────────────────────────────┐
│ │ │ Bob verifies Alice is physically present │
│ │ └──────────────────────────────────────────┘
│ │ │ │
│ │ │ Yes, this is Alice, I confirm │
│ │ ◀─────────────────────────────────────│
│ │ │ │
│ │ ├───┐ │
│ │ │ │ Create voucher │
│ │ ◀───┘ │
│ │ │ │
│ │ │ ┌─────────────────────┐ │
│ │ │ │ Voucher: │ │
│ │ │ │ - old_pk │ │
│ │ │ │ - new_pk │ │
│ │ │ │ - voucher_pk (Bob) │ │
│ │ │ │ - timestamp │ │
│ │ │ │ - Ed25519 signature │ │
│ │ │ └─────────────────────┘ │
│ │ │ │
│ │ Send voucher to Alice │ │
│ ◀──────────────────────────│ │
│ │ │ │
│ ├───┐ │ │
│ │ │ Store Bob's voucher (1 of 3) │
│ ◀───┘ │ │
│ │ │ │
│ Bob vouched for you (1/3) │ │ │
◀─────────────────────────────────│ │ │
│ │ │ │
│ ┌───────────────────────────────────────┐ │
│ │ Alice now has 1 voucher, needs 2 more │ │
│ └───────────────────────────────────────┘ │
│ │ │ │
┌──────────┴──────────┐ ┌─────────┴────────┐ ┌───────┴──────┐ ┌──┴──┐
│ Alice (Lost Device) │ │ Alice New Device │ │ Bob's Device │ │ Bob │
└─────────────────────┘ └──────────────────┘ └──────────────┘ └─────┘
Collecting Multiple Vouchers
┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐
│ Alice New Device │ │ Charlie's Device │ │ Betty's Device │
└─────────┬────────┘ └─────────┬────────┘ └────────┬───────┘
│ │ │
┌rect [rgb(240, 248, 255)]────┐ │
│ │ │ │ │
│ │ Show recovery QR │ │ │
│ │─────────────────────▶ │ │
│ │ │ │ │
│ │ ├───│ │
│ │ │ │ Verify pk_old is contact "Alice"
│ │ ◀───│ │
│ │ │ │ │
│ │ Send voucher │ │ │
│ ◀─────────────────────│ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Store Charlie's vouc│er (2 of 3) │
│ ◀───┘ │ │ │
│ │ │ │ │
│ │ ┌───────────────────┐ │
│ │ │ Alice meets Betty │ │
│ │ └───────────────────┘ │
│ │ │ │ │
└─────────────────────────────┘ │
│ │ │
┌rect [rgb(240, 255, 240)]─────────────────────────┐
│ │ │ │ │
│ │ Show recovery QR │ │
│ │──────────────────────────────────────────▶ │
│ │ │ │ │
│ │ │ ├───│
│ │ │ │ │ Verify pk_old is contact "Alice"
│ │ │ ◀───│
│ │ │ │ │
│ │ Send voucher │ │
│ ◀──────────────────────────────────────────│ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Store Betty's voucher (3 of 3) │ │
│ ◀───┘ │ │ │
│ │ │ │ │
┌─────────────────────────────────────┐ │ │
│ THRESHOLD MET: 3 vouchers collected │ │ │
└─────────────────────────────────────┘ │ │
│ │ │ │ │
└──────────────────────────────────────────────────┘
│ │ │
├───┐ │ │
│ │ Create recovery proof │
◀───┘ │ │
│ │ │
│ ┌───────────────────────────────────┐ │
│ │ Recovery Proof: │ │ │
│ │ - old_pk │ │ │
│ │ - new_pk │ │ │
│ │ - threshold: 3 │ │ │
│ │ - vouchers: [Bob, Charlie, Betty] │ │
│ └───────────────────────────────────┘ │
│ │ │
┌─────────┴────────┐ ┌─────────┴────────┐ ┌────────┴───────┐
│ Alice New Device │ │ Charlie's Device │ │ Betty's Device │
└──────────────────┘ └──────────────────┘ └────────────────┘
Phase 2: Remote Distribution
┌──────────────────┐ ┌───────┐ ┌───────────────┐ ┌────────────────┐
│ Alice New Device │ │ Relay │ │ John's Device │ │ David's Device │
└─────────┬────────┘ └───┬───┘ └───────┬───────┘ └────────┬───────┘
│ │ │ │
│ Upload recovery proof │ │ │
│──────────────────────────▶ │ │
│ │ │ │
│ ├───┐ │ │
│ │ │ Store under key: hash(pk_old) │ │
│ ◀───┘ │ │
│ │ │ │
│ Stored │ │ │
◀╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌│ │ │
│ │ │ │
│ ┌──────────────────────────┐ │ │
│ │ Proof stored for 90 days │ │ │
│ └──────────────────────────┘ │ │
│ │ │ │
│ │ Batch query for contact recovery proofs │ │
│ ◀────────────────────────────────────────────│ │
│ │ │ │
│ │ │ ┌──────────────────────────────────────────────────┐
│ │ │ │ Query: [hash(pk1), hash(pk2), hash(pk_old), ...] │
│ │ │ └──────────────────────────────────────────────────┘
│ │ │ │
│ │ Found proof for hash(pk_old) │ │
│ │╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌▶ │
│ │ │ │
│ │ ├───┐ │
│ │ │ │ Decode recovery proof
│ │ ◀───┘ │
│ │ │ │
│ │ ├───┐ │
│ │ │ │ Verify: pk_old is contact "Alice"
│ │ ◀───┘ │
│ │ │ │
│ │ ├───┐ │
│ │ │ │ Check vouchers for mutual contacts
│ │ ◀───┘ │
│ │ │ │
│ │ ┌alt [Ha┐ │
│ │ │ │ │ │
│ │ │ ├───│ │
│ │ │ │ │ Bob is my contact
│ │ │ ◀───│ │
│ │ │ │ │ │
│ │ │ ├───│ │
│ │ │ │ │ Charlie is my contact
│ │ │ ◀───│ │
│ │ │ │ │ │
│ │ │ ├───│ │
│ │ │ │ │ 2 mutual vouchers ≥ threshold
│ │ │ ◀───│ │
│ │ │ │ │ │
│ │ │ ├───│ │
│ │ │ │ │ High confidence recovery
│ │ │ ◀───│ │
│ │ │ │ │ │
│ │ ├[No Mut┤ │
│ │ │ │ │ │
│ │ │ ├───│ │
│ │ │ │ │ No vouchers are my contacts
│ │ │ ◀───│ │
│ │ │ │ │ │
│ │ │ ├───│ │
│ │ │ │ │ Cannot verify - meet Alice in person
│ │ │ ◀───│ │
│ │ │ │ │ │
│ │ └───────┘ │
│ │ │ │
│ │ Query for recovery proofs│ │
│ ◀────────────────────────────────────────────────────────────────│
│ │ │ │
│ │ Found proof for Alice │ │
│ │╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌▶
│ │ │ │
│ │ │ ├───┐
│ │ │ │ │ Check vouchers: Bob, Charlie, Betty
│ │ │ ◀───┘
│ │ │ │
│ │ │ ├───┐
│ │ │ │ │ None are David's contacts
│ │ │ ◀───┘
│ │ │ │
│ │ │ ├───┐
│ │ │ │ │ Warning: Unknown vouchers
│ │ │ ◀───┘
│ │ │ │
│ │ │ ├───┐
│ │ │ │ │ Options: Meet in person / Verify another way / Accept anyway
│ │ │ ◀───┘
│ │ │ │
┌─────────┴────────┐ ┌───┴───┐ ┌───────┴───────┐ ┌────────┴───────┐
│ Alice New Device │ │ Relay │ │ John's Device │ │ David's Device │
└──────────────────┘ └───────┘ └───────────────┘ └────────────────┘
Data Structures
Recovery Claim QR
{
"type": "recovery_claim",
"old_pk": "Ed25519 public key (lost)",
"new_pk": "Ed25519 public key (new)",
"timestamp": "2026-01-21T10:00:00Z"
}
Voucher
{
"old_pk": "Alice's old public key",
"new_pk": "Alice's new public key",
"voucher_pk": "Bob's public key",
"timestamp": "2026-01-21T10:05:00Z",
"signature": "Ed25519 signature of above fields"
}
Recovery Proof
{
"old_pk": "Alice's old public key",
"new_pk": "Alice's new public key",
"threshold": 3,
"vouchers": [
{ /* Bob's voucher */ },
{ /* Charlie's voucher */ },
{ /* Betty's voucher */ }
],
"expires": "2026-04-21T10:00:00Z"
}
Security Properties
| Property | Mechanism |
|---|---|
| In-Person Vouching | Vouchers must physically verify the person |
| Threshold Security | Requires N vouchers (configurable, default 3) |
| Mutual Contact Verification | Recipients verify via contacts they trust |
| Relay Privacy | Relay stores proof under hash, learns nothing |
| Replay Prevention | Timestamps, signatures, 90-day expiry |
| Attack Detection | Conflicting claims trigger warnings |
Related Features
- Contact Exchange - Original key exchange
- Device Linking - Recovery not needed if devices linked
- Sync Updates - How reconnected contacts sync