Persistence & SQLite DB

Overview

Wiltkey implements strict encryption at rest to protect chat histories if a physical device is seized. Plaintext messages are never stored in the database. Instead, they are encrypted with a 256-bit AES master key derived on-the-fly from the user's PIN. When the app is locked or closed, the master key is purged from RAM, making the database undecryptable.

How it Works

1. Master Key Derivation (KDF): When a user enters their PIN, the app derives the master key via a custom key derivation function (KDF) that hashes the concatenated PIN + Salt with 5000 iterations of SHA-256:
   lib/core/state_auth.dart DART

   static String deriveKey(String pin, String saltHex) {
     List<int> key = utf8.encode(pin + saltHex);
     for (int i = 0; i < 5000; i++) {
       key = sha256.convert(key).bytes;
     }
     return hexEncode(key);
   }

2. AES-256-CBC Encryption at Rest: Wiltkey uses AES-256 in Cipher Block Chaining (CBC) mode with a secure random 16-byte initialization vector (IV) prefixed to the ciphertext (format: iv_base64:ciphertext_base64). The derived key encrypts the message payload before it is written to the SQLite column:
   text_encrypted_master = AES_Encrypt(plaintext, key=masterKeyHex)
3. SQLite DB Schema: The SQLite database (currently version 13) contains 5 tables. Key details:
   • contacts: Stores unified 1:1 and group profiles, offsets, slot information, and equipped avatar borders (DB v10).
   • messages: Stores message IDs, timestamps, content type, raw OTP ciphertext (text_otp), local master-encrypted plaintext (text_encrypted_master), sidecar media paths for large bodies (DB v12), and pending on-demand remote file references (DB v13).
   • group_info, group_lanes, group_profiles: Store shared-pad lane slot indices and peer arrival orders. group_profiles also caches each member's broadcast profile (name, avatar, and equipped avatar-border id, DB v11) received over the full-mesh group_member_profile channel.
   • A member's equipped avatar-border id is a local-only cosmetic that rides the profile channels alongside the avatar: stored on contacts.avatar_border for 1:1 peers (DB v10) and group_profiles.avatar_border for group members (DB v11). It never touches the OTP pad and renders for everyone (a peer's border always shows; ownership only gates whether you may equip it).

SQLite Schema Fields Reference

Gotchas & Edge Cases