UI & Customization

Profiles & Social Contacts

Separation of social contacts from ephemeral chat sessions, instant decor and status synchronization, 100-character limits, status emojis, and zero-pad metadata transport.

1. Conceptual Model: Social Contacts vs. Active Chats

Wiltkey maintains a strict architectural boundary between a Social Contact (a persistent cryptographic relationship / contact card) and a Contact Chat (an active, byte-budgeted or Time-Wilt communication session):

  • SocialContact (social_contacts table): Represents a verified acquaintance. Stored independently so that archiving, nuking, or expiring an individual chat pad does not erase your contact list or safety fingerprint.
  • Contact (contacts table): Represents a specific chat channel (1:1 pad, Time Wilt stream, or group chat) with active cryptographic write offsets and ephemeral lifetime gauges.
🔒 SECURITY INVARIANT — METADATA SPLIT
Profile updates, custom statuses, avatar borders, and nickname updates ride exclusively over the AES metadata control channel (content_type: 'profile_update'). They never consume one-time pad bytes or keystream material.

2. Instant Profile & Decor Synchronization

Rather than waiting for a manual profile edit or periodic 7-day refresh, Wiltkey triggers an immediate bidirectional profile exchange upon every connection event:

PROFILE SYNC TRIGGERS 
// 1. Contact Request Approved (Receiver & Requester)
AppStateContacts.respondToContactRequest() -> sendProfileUpdateTo(peerKeyHash);
AppStateContacts._handleContactResponse()   -> sendProfileUpdateTo(senderId);

// 2. BLE Proximity Pairing / Recharge
AppStateLifecycle.addOrRechargeContact()         -> sendProfileUpdateTo(keyHash);
AppStateLifecycle.addOrRechargeTimeWiltContact() -> sendProfileUpdateTo(keyHash);

// 3. Emergency Chat Handshake
AppStateContacts._handleEmergencyChatAck() -> sendProfileUpdateTo(senderId);

When an incoming profile_update frame arrives, _handleProfileUpdate instantly updates the stored SocialContact row and patches the active Contact in the chat list in real time.

3. Rich Status Messages & Ephemeral Expiry

Users can set custom profile statuses with strict length guards, emoji accents, and optional auto-expiration:

100-Character Limit

Status messages enforce a hard 100-character maximum with a live interactive counter (N/100) in the editor and state clamps on the payload.

Status Emoji & Avatar Badge

Users can choose a status emoji via a categorized picker. The selected emoji renders as a prominent badge on the profile avatar and in contact list items.

Auto-Clear Expiration

Statuses can be configured to clear after 1 hour, 4 hours, 24 hours, 48 hours, or Never. The wire payload transmits an absolute unix millisecond timestamp (status_expires_at_ms).

Live Expiry Countdown

When viewing a contact's profile, Wiltkey computes remaining duration (e.g. Expires in 3h 12m). Expired statuses are automatically suppressed across UI components.

4. Wire Format & Database Schema (v24 Migration)

AES META CHANNEL — PROFILE_UPDATE PAYLOAD 
{
  "v": 1,
  "name": "Alice Cooper",
  "short_nick": "alice",
  "status": "Writing secure encryption protocols",
  "status_emoji": "⚡",
  "status_expires_at_ms": 1755355200000,
  "theme_id": "phosphor",
  "avatar_border_id": "gold_crown",
  "profile_image_b64": "..."
}

In SQLite (Database Schema v24–v26), new columns were added to the social_contacts table:

  • status_emoji TEXT: Holds the UTF-8 emoji string.
  • status_expires_at INTEGER: Absolute epoch milliseconds when the status expires, or NULL if permanent.
  • attestation_token TEXT / attestation_expires_at INTEGER (v26): Stores the Ed25519-signed client integrity attestation token.

5. Client Integrity Attestation & Verification Badges

Starting in v1.3.5, WiltKey allows users to cryptographically verify the authenticity and build origin of their peers:

🛡️✨ Play Store · Plus

Verified official Google Play Store build with an active WiltKey Plus supporter membership.

🛡️ Play Store Verified

Official unmodified Google Play build cryptographically verified through Google Play Integrity API.

🔧 Open Source / Community

Community, FOSS, or custom tinkerer build. Because it runs zero Google services, it is treated as open-source. All cryptographic protections remain 100% active.

🔏 OFFLINE PEER VERIFICATION
Attestations are signed with Ed25519 by the relay using the envelope format WILTKEY_ATTESTATION:<userId>:<clientType>:<issuedAt>:<expiresAt>. Peers verify signatures locally against the trusted relay public key with zero network round-trips.

6. Local Private Notes & Custom Nicknames (v27 Migration)

Starting in v1.4.0, users can assign confidential local notes and custom display nicknames to any contact:

📝 Private Contact Notes

Personal plaintext notes attached to a contact. Stored 100% locally on device in SQLite and never transmitted over the network or revealed to the contact.

🏷️ Custom Local Nicknames

Overrides the peer's self-selected broadcast name locally across chat headers, message bubbles, and contact lists. Preserves the original peer identity securely underneath.

🔒 ZERO NETWORK EXPOSURE
In SQLite schema v27, private_notes TEXT and custom_nickname TEXT columns were added to the contacts and social_contacts tables. These fields are strictly excluded from all outbound metadata sync frames.