Multi-Device Support

Identity Key (IK)
    │
    ├── Device Key 1 (Phone)
    │       ├── Signed Pre-Key 1
    │       └── One-Time Pre-Keys [100]
    │
    ├── Device Key 2 (Desktop)
    │       ├── Signed Pre-Key 2
    │       └── One-Time Pre-Keys [100]
    │
    └── Device Key 3 (Tablet)
            ├── Signed Pre-Key 3
            └── One-Time Pre-Keys [100]

1. Primary device generates linking request:
   - Ephemeral X25519 keypair (EK_P)
   - Random session ID
   - Timestamp

2. QR code contains:
   QR = Base64(EK_P_pub || session_id || timestamp || signature)

3. New device scans QR:
   - Generates own ephemeral key (EK_N)
   - Computes shared secret: SS = X25519(EK_N, EK_P_pub)

4. New device sends to primary:
   - EK_N_pub
   - Device public keys (encrypted with SS)

5. Primary verifies and responds:
   - Identity Key (encrypted with SS)
   - Existing session states (encrypted)
   - Contact list (encrypted)

6. Both devices verify via numeric code:
   - code = HKDF(SS, "verify")[0:6]
   - User confirms codes match

Device Key Bundle:
┌─────────────────────────────────────────┐
│ Identity Key (shared)                   │
├─────────────────────────────────────────┤
│ Device Key (unique)                     │
├─────────────────────────────────────────┤
│ Signed Pre-Key (unique)                 │
├─────────────────────────────────────────┤
│ One-Time Pre-Keys [100] (unique)        │
└─────────────────────────────────────────┘

1. Alice fetches Bob's device list (3 devices)

2. For each device, Alice:
   - Performs X3DH with device's key bundle
   - Creates/updates session for that device
   - Encrypts message with device-specific key

3. Server stores 3 encrypted copies
   - One for each of Bob's devices
   - Each decryptable only by target device

4. Each device receives and decrypts independently

1. Alice sends message from Phone
2. Phone encrypts for:
   - Bob's devices (recipients)
   - Alice's Desktop (self-sync)
   - Alice's Tablet (self-sync)
3. All Alice's devices receive copy

Vector Clock Structure:
┌─────────────────────────────────────────┐
│ { device_id: counter }                  │
│                                         │
│ Phone:   { phone: 5, desktop: 3 }       │
│ Desktop: { phone: 4, desktop: 4 }       │
│                                         │
│ Conflict detected: Neither dominates    │
└─────────────────────────────────────────┘

1. Compare vector clocks
   - If V1 > V2: V1 wins
   - If V2 > V1: V2 wins
   - If concurrent: proceed to step 2

2. Compare wall-clock timestamps
   - Higher timestamp wins
   - If equal: proceed to step 3

3. Compare device IDs (lexicographic)
   - Higher device ID wins
   - Deterministic, reproducible on all devices

Event A happens-before Event B if:
  1. A and B on same device, A sent first
  2. A is send, B is corresponding receive
  3. Transitive: A→C and C→B implies A→B

Double Ratchet Message Keys:
┌─────────────────────────────────────────┐
│ Chain Key (n) → Message Key (n)         │
│      ↓                                  │
│ Chain Key (n+1) → Message Key (n+1)     │
│      ↓                                  │
│ Chain Key (n+2) → Message Key (n+2)     │
└─────────────────────────────────────────┘

Counter (n) provides strict ordering per session.
Out-of-order messages buffered until gap filled.

Push Sync (real-time):
  Device A modifies state
      ↓
  Encrypt delta with self-sync key
      ↓
  Send to all linked devices
      ↓
  Devices apply delta immediately

Pull Sync (reconnection):
  Device comes online
      ↓
  Send vector clock to sync service
      ↓
  Receive list of missing updates
      ↓
  Fetch and apply in causal order

Merkle Tree Structure:
                    Root Hash
                   /         \
             Hash(A-M)     Hash(N-Z)
             /      \       /      \
        Hash(A-F) Hash(G-M) ...   ...
           |
     Contact entries

Sync process:
1. Exchange root hashes
2. If match: fully synced
3. If mismatch: descend tree
4. Identify changed subtrees only
5. Transfer only divergent data

1. Device reconnects after extended offline period
2. Compare local vector clock with server state
3. If divergence < threshold (1000 ops):
   - Incremental sync via Merkle tree diff
4. If divergence >= threshold:
   - Full state download required
   - Local-only changes merged with conflict resolution
5. Message history:
   - Fetch missing messages by timestamp range
   - Double Ratchet sessions renegotiated if needed

1. Sync message sent with sequence number
2. Recipient acknowledges receipt
3. If no ACK within timeout (30s):
   - Retry up to 3 times with exponential backoff
4. If all retries fail:
   - Mark device as potentially stale
   - Next heartbeat triggers full sync check
5. Idempotent operations prevent duplicate application

1. User initiates removal from primary device
2. Primary sends revocation to:
   - Server (remove device registration)
   - Other linked devices (update device list)
3. Contacts notified of device change (optional)
4. Sessions with removed device marked stale

1. User logs into remaining device (or recovers via backup)
2. Marks lost device as compromised
3. Rotates all session keys
4. Server removes lost device's registration
5. New sessions established with contacts

1. User enters recovery passphrase
2. Fetch encrypted backup from mesh
3. Derive key: K = PBKDF2(passphrase, salt, 600000)
4. Decrypt Identity Key
5. Generate new Device Key for this device
6. Re-establish sessions with contacts

1. BIP-39 word list
2. Encodes 128 bits of entropy
3. Used as PBKDF2 input
4. Stored securely by user (offline)

Revocation from Trusted Device:

1. User authenticates on remaining trusted device
   - Biometric or PIN verification required
   - Rate limited: max 3 attempts per hour

2. Select device to revoke from device list
   - Device identified by: name, last seen, device ID prefix
   - Confirmation required with explicit device name

3. Generate revocation certificate
   RevokeCert = Sign(IK_priv, {
     device_id: target_device_id,
     timestamp: current_time,
     reason: revocation_reason,
     initiator: revoking_device_id
   })

4. Submit to server
   - Server validates signature against Identity Key
   - Server validates initiator is registered device
   - Revocation recorded with timestamp

5. Propagate to network
   - Other linked devices notified immediately
   - Contact key servers updated
   - Prekey bundles invalidated

Recovery-Based Revocation:

1. User enters 12-word recovery phrase
   - Derives Identity Key: IK = KDF(mnemonic, "identity")
   - No device access required

2. Authenticate to revocation service
   - Challenge-response using derived IK
   - Additional verification (email/SMS if configured)

3. Select revocation scope
   - Single device revocation
   - All devices revocation (nuclear option)

4. Generate emergency revocation certificate
   EmergencyRevokeCert = Sign(IK_priv, {
     scope: "single" | "all",
     device_ids: [target_devices],
     timestamp: current_time,
     emergency: true
   })

5. Execute revocation
   - All selected devices immediately invalidated
   - Sessions terminated server-side
   - User must re-register at least one device

Contact Notification Message:

NotifyMsg = Encrypt(session_key, {
  type: "device_change",
  event: "revocation",
  device_count: new_count,
  timestamp: revocation_time,
  requires_verification: boolean
})

- Sent to all active contacts
- Delivered to all their devices
- UI displays security notification

Session Invalidation Process:

1. Server marks device sessions as revoked
   session.status = "revoked"
   session.revoked_at = timestamp

2. Pending messages for device
   - Messages in queue: deleted
   - Messages in transit: delivery fails

3. Session ratchet state
   - Server cannot access (E2EE)
   - Other devices: remove peer session
   - Contacts: session marked stale

Message Routing After Revocation:

Before (3 devices):
  Sender → Server → [Device A, Device B, Device C]

After Device C revoked (2 devices):
  Sender → Server → [Device A, Device B]

Server behavior:
  - Device C removed from routing table
  - Messages encrypted for Device C: rejected at send time
  - Senders fetching device list: Device C excluded

Local Data State Post-Revocation:

Revoked device attempts operation:

  Send message → Server rejects (device not registered)
  Fetch messages → Server rejects (invalid device)
  Refresh prekeys → Server rejects (device revoked)

Device cannot:
  - Send or receive new messages
  - Establish new sessions
  - Access account resources

Device retains:
  - Previously decrypted messages
  - Contact information
  - Private key material (until wiped)

Identity Key Rotation Protocol:

1. Generate new Identity Key pair
   IK_new = Ed25519_KeyGen()

2. Create rotation certificate (signed by old key)
   RotationCert = Sign(IK_old_priv, {
     old_identity: IK_old_pub,
     new_identity: IK_new_pub,
     timestamp: current_time,
     reason: rotation_reason
   })

3. Submit rotation to server
   - Server validates old key signature
   - Server validates user authentication
   - Atomic update: old key → new key

4. Update all device keys
   For each linked device:
     DK_new = Ed25519_KeyGen()
     DeviceCert = Sign(IK_new_priv, DK_new_pub)
     Upload new prekey bundle

5. Notify contacts of key change
   - Safety numbers invalidated
   - Re-verification required

Session Renegotiation After Rotation:

1. Contact receives rotation notification
   - Old safety number marked invalid
   - New safety number computed

2. Next message triggers X3DH
   - Fetches new prekey bundle (new Identity Key)
   - Establishes fresh Double Ratchet session

3. Both parties see verification prompt
   - "Safety number changed"
   - Manual verification recommended

Safety Number Computation:

SafetyNumber = Truncate(
  SHA-256(
    Sort(IK_A_pub, IK_B_pub) ||
    Sort(UserID_A, UserID_B)
  ),
  30 bytes
)

Displayed as: 60 digits in groups of 5
Example: 12345 67890 12345 67890 12345 67890 ...

Any Identity Key change → New safety number

Emergency Account Reset:

1. Authenticate identity
   - Phone number verification
   - Email verification (if configured)
   - Waiting period (24-72 hours) for abuse prevention

2. Server-side cleanup
   - All devices deregistered
   - All prekey bundles deleted
   - Account metadata purged
   - Message queues cleared

3. Generate new identity
   IK_new = Ed25519_KeyGen()
   - No cryptographic link to old identity
   - Old safety numbers permanently invalid

4. Re-register account
   - New device registered
   - New prekey bundle uploaded
   - Account operational

5. Contact implications
   - All contacts see "new user" warning
   - No automatic session continuity
   - Manual re-verification required for all

Contact Re-establishment:

After reset, contacts see:
  "This contact has reset their account"
  "Verify their identity before continuing"

Re-establishment process:
1. Reset user sends message to contact
2. Contact receives with warning banner
3. X3DH establishes new session (no history)
4. Both parties should verify safety numbers
5. Previous conversation: inaccessible

Revocation Propagation Flow:

T+0ms:    User initiates revocation
T+10ms:   Server validates and records
T+50ms:   Server updates device registry
T+100ms:  Push notification to linked devices
T+100ms:  Revocation logged to audit trail
T+500ms:  Contact key servers updated
T+1000ms: Active contacts notified (online)
T+varies: Offline contacts notified on reconnect

Timing Guarantees Detail:

Hard guarantees:
  - Device cannot authenticate after: 100ms
  - Prekeys unavailable after: 100ms
  - New sessions impossible after: 100ms

Soft guarantees (best effort):
  - Linked device UI update: typically < 5s
  - Contact notification delivery: typically < 10s
  - Full network propagation: typically < 60s

Offline Contact Notification:

1. Server queues revocation notification
   Queue entry: {
     recipient: contact_id,
     type: "device_revoked",
     payload: encrypted_notification,
     created_at: timestamp,
     expires_at: timestamp + 30d
   }

2. Contact comes online
   - Fetches queued notifications
   - Processes revocation notice
   - Updates local session state

3. Contact's next message to user
   - Fetches fresh device list (revoked device excluded)
   - Encrypts only for valid devices

Revocation Authentication Chain:

Device-initiated revocation:
  1. Device unlock (biometric/PIN)
  2. In-app authentication
  3. Confirmation prompt with device name
  4. Cryptographic signature with Device Key
  5. Server validates against registered keys

Recovery-initiated revocation:
  1. Recovery phrase verification
  2. Secondary factor (email/SMS)
  3. Time delay (configurable, default 1 hour)
  4. Cryptographic signature with derived key
  5. Server validates + logs for audit

Authentication Escalation:

Level 1 - View only:
  Requirement: Device unlock
  Allows: View device list, activity

Level 2 - Single device action:
  Requirement: Device unlock + confirmation
  Allows: Revoke one device

Level 3 - Account-wide action:
  Requirement: Recovery phrase + secondary factor
  Allows: Revoke all, rotate identity

Level 4 - Destructive action:
  Requirement: Full verification + waiting period
  Allows: Account reset

Revocation Finality Properties:

Once revoked:
  - Device ID permanently blacklisted for account
  - Same device can re-register as NEW device only
  - Original sessions cannot be restored
  - Original prekeys cannot be recovered

Re-linking a revoked physical device:
  1. Device must be wiped/reset
  2. Fresh device key generated
  3. New linking process required
  4. No session continuity from before revocation
  5. New device ID assigned

Audit Record Structure:

AuditRecord = {
  event_id: UUID,
  timestamp: ISO8601,
  event_type: "device_revocation",
  account_id: hashed_identifier,
  initiator: {
    type: "device" | "recovery" | "admin",
    device_id: initiator_id (if device),
    ip_hash: SHA256(ip_address)
  },
  target: {
    device_id: revoked_device_id,
    device_name_hash: SHA256(device_name)
  },
  reason: enum(lost, stolen, compromised, sold, other),
  certificate: base64(signed_revocation_cert),
  propagation: {
    linked_devices_notified: count,
    contacts_notified: count,
    completion_time_ms: duration
  }
}

Retention: 2 years minimum
Access: User can request own audit log