Vauchi DocsContact Exchange Sequence
Interaction Type: 🤝 IN-PERSON (Proximity Required)
Two users exchange contact cards by scanning QR codes while physically present together. Proximity is verified via ultrasonic audio handshake to prevent remote/screenshot attacks.
Participants
- Alice - User initiating exchange (displays QR)
- Alice's Device - Mobile/Desktop running Vauchi
- Bob - User completing exchange (scans QR)
- Bob's Device - Mobile/Desktop running Vauchi
- Relay - WebSocket relay server (fallback only)
Sequence Diagram
┌───────┐ ┌────────────────┐ ┌──────────────┐ ┌─────┐ ┌───────┐
│ Alice │ │ Alice's Device │ │ Bob's Device │ │ Bob │ │ Relay │
└───┬───┘ └────────┬───────┘ └───────┬──────┘ └──┬──┘ └───┬───┘
│ │ │ │ │
│ Tap "Share Contact" │ │ │ │
│────────────────────────▶ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Generate ephemeral X25519 keypair │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Create exchange token (expires 5 min) │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Generate audio challenge seed │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Encode QR: [public_key, token, audio_challenge] │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ Display QR code │ │ │ │
◀────────────────────────│ │ │ │
│ │ │ │ │
│ │ │ Open camera, scan QR │ │
│ │ ◀─────────────────────────│ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Decode QR data │ │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Validate token not expired │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Extract Alice's public key │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ ┌───────────────────────────────────────────┐ │ │ │
│ │ │ PROXIMITY VERIFICATION (Ultrasonic Audio) │ │ │ │
│ │ └───────────────────────────────────────────┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Emit ultrasonic challenge (18-20 kHz) │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Detect ultrasonic challenge │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Sign challenge with Bob's key │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Emit ultrasonic response │
│ │ ◀───┘ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Detect and verify response │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Confirm proximity │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Confirm proximity │ │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ ┌────────────────────┐ │ │ │
│ │ │ X3DH KEY AGREEMENT │ │ │ │
│ │ └────────────────────┘ │ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Generate ephemeral X25519 keypair
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ Send: [Bob's identity key, ephemeral key] │ │ │
│ ◀────────────────────────────────────────────────│ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ X3DH: Derive shared secret │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ │ Send: [Alice's identity key, ephemeral key] │ │ │
│ │────────────────────────────────────────────────▶ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ X3DH: Derive shared secret │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ ┌───────────────────────────────────┐ │ │ │
│ │ │ Both have identical shared secret │ │ │ │
│ │ └───────────────────────────────────┘ │ │ │
│ │ │ │ │
│ │ ┌───────────────────────┐ │ │ │
│ │ │ CONTACT CARD EXCHANGE │ │ │ │
│ │ └───────────────────────┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Encrypt Alice's card with shared secret │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ │ Send encrypted contact card │ │ │
│ │────────────────────────────────────────────────▶ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Decrypt Alice's card│ │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Store Alice as contact │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Encrypt Bob's card with shared secret
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ Send encrypted contact card │ │ │
│ ◀────────────────────────────────────────────────│ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Decrypt Bob's card │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Store Bob as contact │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ Exchange Successful │ │ │ │
◀────────────────────────│ │ │ │
│ │ │ │ │
│ │ │ Exchange Successful │ │
│ │ │─────────────────────────▶ │
│ │ │ │ │
│ ┌───────────────────────────────────────────────────┐ │ │
│ ││Alice and Bob now have each other's contact cards │ │ │
│ └───────────────────────────────────────────────────┘ │ │
│ │ │ │ │
┌───┴───┐ ┌────────┴───────┐ ┌───────┴──────┐ ┌──┴──┐ ┌───┴───┐
│ Alice │ │ Alice's Device │ │ Bob's Device │ │ Bob │ │ Relay │
└───────┘ └────────────────┘ └──────────────┘ └─────┘ └───────┘
Data Exchanged
QR Code Contents
Binary format (v3) with WBEX magic
bytes:
WBEX (4 bytes magic)
version (1 byte) = 0x03
Ed25519 public key (32 bytes)
X25519 exchange key (32 bytes)
exchange token (32 bytes)
audio_challenge seed (16 bytes)
creation timestamp (8 bytes)
name_len (2 bytes, big-endian)
name (N bytes, UTF-8)
flags (1 byte, bitfield)
[if bit 0] relay_url_len (2 bytes) + relay_url (M bytes)
[if bit 1] relay_noise_pubkey (32 bytes)
signature (64 bytes, Ed25519 over all preceding fields)
Minimum size (empty name, no relay fields): 192 bytes.
Contact Card (Encrypted)
{
"display_name": "Alice Smith",
"fields": [
{"type": "phone", "label": "Mobile", "value": "+1-555-1234"},
{"type": "email", "label": "Personal", "value": "alice@example.com"}
],
"signature": "Ed25519 signature of card"
}
Security Properties
| Property | Mechanism |
|---|---|
| Proximity | Ultrasonic audio (18-20 kHz) |
| No MITM | X3DH with identity keys |
| Forward Secrecy | Ephemeral keys discarded |
| Replay Prevention | One-time token, 5-min expiry |
| Card Authenticity | Ed25519 signature |
Failure Scenarios
Proximity Verification Fails
┌────────────────┐ ┌──────────────┐
│ Alice's Device │ │ Bob's Device │
└────────┬───────┘ └───────┬──────┘
│ │
├───┐ │
│ │ Emit ultrasonic challenge
◀───┘ │
│ │
│ ├╌╌╌┐
│ │ │ No ultrasonic detected (too far)
│ ◀╌╌╌┘
│ │
│ ├───┐
│ │ │ Proximity verification FAILED
│ ◀───┘
│ │
│ ├───┐
│ │ │ Proximity verification failed
│ ◀───┘
│ │
┌───────────────────────────────────────┐
│ Exchange blocked - no cards exchanged │
└───────────────────────────────────────┘
│ │
┌────────┴───────┐ ┌───────┴──────┐
│ Alice's Device │ │ Bob's Device │
└────────────────┘ └──────────────┘
QR Code Expired
┌────────────────┐ ┌──────────────┐
│ Alice's Device │ │ Bob's Device │
└────────┬───────┘ └───────┬──────┘
│ │
│ ├───┐
│ │ │ Decode QR, check expiry
│ ◀───┘
│ │
│ ├───┐
│ │ │ Token expired
│ ◀───┘
│ │
│ ├───┐
│ │ │ QR code expired
│ ◀───┘
│ │
┌────────────────────────────┐
│ Alice must generate new QR │
└────────────────────────────┘
│ │
┌────────┴───────┐ ┌───────┴──────┐
│ Alice's Device │ │ Bob's Device │
└────────────────┘ └──────────────┘
Platform Variations
| Platform | Proximity Method | Fallback |
|---|---|---|
| iOS ↔ iOS | Ultrasonic | Manual confirm |
| Android ↔ Android | Ultrasonic | Manual confirm |
| iOS ↔ Android | Ultrasonic | Manual confirm |
| Desktop ↔ Mobile | N/A (no mic) | Manual confirm |
| Desktop ↔ Desktop | N/A | Manual confirm |
Related Features
- Device Linking - Similar QR flow for linking devices
- Sync Updates - How card updates propagate after exchange