Account Recovery

Entropy Generation:
1. Generate 256 random bits from secure RNG
2. Compute checksum = SHA-256(entropy)[0:8]
3. Concatenate: entropy || checksum = 264 bits
4. Split into 24 groups of 11 bits each
5. Map each 11-bit value to word list index

Seed Derivation (PBKDF2):
  Input: mnemonic phrase (space-separated words)
  Salt: "mnemonic" + optional_passphrase
  Iterations: 2048
  Hash: HMAC-SHA512
  Output: 512-bit seed

seed = PBKDF2-HMAC-SHA512(
    password = normalize(mnemonic),
    salt = "mnemonic" + passphrase,
    iterations = 2048,
    output_length = 64 bytes
)

Key Derivation Path:
  Master Key = HMAC-SHA512("ed25519 seed", seed)

  Path: m/44'/1991'/0'/0/0

  44'  = BIP-44 purpose (hardened)
  1991' = Zentalk coin type (hardened)
  0'   = Account index (hardened)
  0    = Change (external)
  0    = Address index

Identity Key = derive_ed25519(Master Key, path)

1. User enters 24-word phrase
2. Validate each word exists in BIP-39 list
3. Compute checksum from first 23 words + partial 24th
4. Verify checksum matches final word
5. If invalid: display specific error

1. Convert mnemonic to seed (PBKDF2)
2. Derive master key from seed
3. Derive wallet key: m/44'/60'/0'/0/0 (secp256k1)
4. Derive identity key: m/44'/1991'/0'/0/0 (Ed25519)
5. Compute wallet address from public key
6. Generate new device key for this device

1. Generate new signed pre-key
2. Generate 100 new one-time pre-keys
3. Sign pre-key bundle with identity key
4. Publish to DHT and API servers
5. Fetch existing contacts from mesh backup
6. Notify contacts of new device (key unchanged)

1. For each contact:
   - Fetch their current key bundle
   - Perform X3DH key exchange
   - Initialize new Double Ratchet session
2. Old sessions are abandoned
3. Pending messages to old device keys are lost

Backup File Format:
┌─────────────────────────────────────────────────┐
│ Header (32 bytes)                               │
│   Magic: "ZTBK" (4 bytes)                       │
│   Version: 1 (2 bytes)                          │
│   Timestamp: Unix epoch (8 bytes)               │
│   Key derivation params (18 bytes)              │
├─────────────────────────────────────────────────┤
│ Salt (32 bytes)                                 │
├─────────────────────────────────────────────────┤
│ Nonce (12 bytes)                                │
├─────────────────────────────────────────────────┤
│ Encrypted Payload (variable)                    │
│   Identity Key material                         │
│   Contact list                                  │
│   Group memberships                             │
│   Settings                                      │
│   Message history (optional)                    │
├─────────────────────────────────────────────────┤
│ Authentication Tag (16 bytes)                   │
└─────────────────────────────────────────────────┘

Key Derivation:
  password = user_input
  salt = backup_file[32:64]  // 32 bytes
  iterations = header.iterations  // minimum 600,000

  derived_key = PBKDF2-HMAC-SHA256(
      password,
      salt,
      iterations,
      output_length = 32 bytes
  )

Decryption:
  nonce = backup_file[64:76]  // 12 bytes
  ciphertext = backup_file[76:-16]
  tag = backup_file[-16:]  // last 16 bytes

  plaintext = AES-256-GCM-Decrypt(
      key = derived_key,
      nonce = nonce,
      ciphertext = ciphertext,
      associated_data = header,
      tag = tag
  )

1. Check file size minimum (96 bytes header + tag)
2. Verify magic bytes = "ZTBK"
3. Check version is supported (currently 1)
4. Verify timestamp is reasonable (not future, not too old)
5. Validate KDF parameters are secure

1. Derive key from password
2. Attempt AES-GCM decryption
3. Verify authentication tag
   - If tag invalid: wrong password or corrupted
4. Parse decrypted payload
5. Verify internal checksums

1. Deserialize identity key material
2. Derive public key from private key
3. Compute wallet address
4. Compare with embedded address
5. If mismatch: backup may be for different account

On Existing Device:
1. Navigate to Settings → Devices → Add Device
2. Authenticate with biometric/PIN
3. Generate ephemeral X25519 keypair
4. Display QR code containing:
   - Ephemeral public key (32 bytes)
   - Session ID (16 bytes)
   - Timestamp (8 bytes)
   - Signature from Identity Key

On New Device:
1. Select "Recover from existing device"
2. Scan QR code from camera
3. Parse and validate QR data
4. Generate own ephemeral keypair
5. Compute shared secret

On Existing Device:
1. Navigate to Settings → Devices → Add Device
2. Select "Use numeric code"
3. Display 8-digit code + ephemeral public key
4. Code valid for 60 seconds

On New Device:
1. Enter 8-digit code
2. Fetch pairing data from server using code
3. Proceed with key exchange

Phase 1: QR Generation (Existing Device)
  EK_old = generate_x25519_keypair()
  session_id = random(16 bytes)
  timestamp = current_unix_time()

  payload = EK_old.public || session_id || timestamp
  signature = Ed25519_sign(Identity_Key, payload)

  qr_data = Base64(payload || signature)

Phase 2: QR Scan (New Device)
  Parse qr_data
  Verify timestamp not expired (60 second window)
  Extract EK_old_public, session_id, signature

  EK_new = generate_x25519_keypair()
  shared_secret = X25519(EK_new.private, EK_old_public)

  encryption_key = HKDF(shared_secret, "ZentalkDeviceLink")

Phase 3: Key Request (New Device → Server → Existing Device)
  Generate device keypair for new device

  request = {
    session_id: session_id,
    ephemeral_public: EK_new.public,
    device_public_key: new_device_public_key,
    device_info: encrypted(encryption_key, device_name)
  }

  Send request to server

Phase 4: Key Transfer (Existing Device)
  Receive request via push notification
  Verify session_id matches pending pairing

  shared_secret = X25519(EK_old.private, EK_new_public)
  encryption_key = HKDF(shared_secret, "ZentalkDeviceLink")

  transfer_data = {
    identity_key_seed: encrypted(encryption_key, seed),
    contacts: encrypted(encryption_key, contact_list),
    groups: encrypted(encryption_key, group_list),
    settings: encrypted(encryption_key, settings)
  }

  Sign transfer_data with Identity Key
  Send to new device via server

Phase 5: Verification (Both Devices)
  verification_code = HKDF(shared_secret, "verify")[0:6]
  Convert to 6-digit number

  Both devices display same code
  User confirms codes match

  If match confirmed:
    New device finalizes setup
    Add new device to device list

Message Backup Entry:
┌─────────────────────────────────────────────────┐
│ conversation_id: hash(participant_addresses)    │
│ message_id: unique_identifier                   │
│ timestamp: unix_epoch_ms                        │
│ sender: wallet_address                          │
│ type: text | media | system                     │
│ content: encrypted_message_body                 │
│ media_refs: [encrypted_media_keys]              │
│ read_status: boolean                            │
│ delivery_status: sent | delivered | read        │
└─────────────────────────────────────────────────┘

Phase 1: Identify Available Sources
  Check for local encrypted backup file
  Check mesh storage for backup markers
  Check for other linked devices

Phase 2: Priority-Based Recovery
  1. If other device available:
     - Request message sync via encrypted channel
     - Transfer complete conversation history

  2. If encrypted backup available:
     - Decrypt backup file
     - Import message database
     - Verify message signatures

  3. If mesh backup only:
     - Fetch encrypted blobs from mesh
     - Decrypt with recovered Identity Key
     - May have limited history (30 days default)

Phase 3: Session Reconstruction
  For each conversation:
    - Establish new session with contact
    - Link historical messages to new session
    - Mark old session keys as unrecoverable

Forward Secrecy Effect:
  Time T-1: Message encrypted with Key(T-1)
  Time T:   Key(T-1) deleted, Key(T) derived
  Time T+1: Key(T) deleted, Key(T+1) derived

  Attacker at T+1 cannot recover Key(T-1) or Key(T)
  Even with Identity Key compromise

Session Re-establishment Flow:
1. New device generates fresh pre-keys
2. Publishes new key bundle to network
3. For each contact attempting to message you:
   - They detect new key bundle
   - They perform fresh X3DH
   - New Double Ratchet session begins
4. Contacts see "safety number changed" warning
5. High-security contacts should re-verify

1. Check wallet address matches expected
2. View identity fingerprint
3. Compare with recorded fingerprint (if available)
4. Verify contact list matches expectations
5. Check group memberships are correct

When contact sends message after your recovery:
1. They fetch your key bundle
2. Detect Identity Key unchanged but device keys new
3. System message: "User's security info changed"
4. Warning displayed: "Verify if unexpected"

Before Recovery:
  ✓ Official Zentalk app from verified source
  ✓ Device malware scan completed
  ✓ Secure, private location
  ✓ Trusted network (home WiFi or cellular)
  ✓ No screen recording active
  ✓ Clipboard cleared

During Recovery:
  ✓ Do not photograph mnemonic
  ✓ Do not read mnemonic aloud
  ✓ Verify each word carefully
  ✓ Watch for autocorrect interference
  ✓ Confirm address matches expected

After Recovery:
  ✓ Clear clipboard again
  ✓ Lock mnemonic backup securely
  ✓ Verify contact fingerprints
  ✓ Test send/receive with trusted contact
  ✓ Enable device security (biometric, PIN)