Wilting Messages

Overview

A wilting message is a text or image that self-destructs a set number of seconds after the recipient opens it. It arrives behind a tap-to-reveal gate; on reveal a countdown starts; when it lapses the message wilts — its stored ciphertext is destroyed in place and only a "Wilted message" tombstone remains.

How it Works

1. Config on the wire, timing on the device: The sender can't know when a recipient will open a message, so the OTP envelope carries only the config — eph: 1 and ttl: <seconds> (1–60). All timing is resolved locally on the recipient: opened_at / expires_at are stamped the moment they tap to reveal.
2. Reveal-gated: A received wilting message is never decrypted until revealed. The bubble renders a "Tap to see wilting message" gate; the tap calls revealEphemeral(), which stamps the open/expiry instants, persists them, and arms a countdown timer. Unopened messages persist indefinitely (there is no delivery-side max).
3. Per-recipient countdown: Each recipient's timer starts on their reveal. In a group, every member wilts on their own schedule. The countdown is a self-ticking bar rendered beside the message.
4. Destroy-in-place: On expiry, wiltMessageRow() blanks both ciphertext copies (text_otp = '', text_encrypted_master = null), scrambles offset to -1, and sets wilted = 1. This is true destruction, not a flag: flagging alone would leave recoverable ciphertext on disk that a retained pad could still decrypt.
5. Sender copy + confirmation: When a recipient wilts a message, they emit a wilt_done confirmation on the AES metadata channel (never the OTP pad). In 1-on-1 the sender then wilts their own copy too; in a group the sender accrues a wilted_by set ("n/m wilted") and wilts once every other member has confirmed.

The Wilt Engine

state_wilting.dart (an extension AppStateWilting, part of state.dart) is the local engine. Timers live in AppState (wiltTimers) because extensions can't hold state.

• revealEphemeral() — stamps opened_at/expires_at once, persists, and arms the countdown.
• wiltMessage() — destroys the row, clears the in-memory copy, drops the timer, and (for a received real message only) emits wilt_done.
• sweepAndArmWilting() — runs once per unlock and again on resume (timers don't survive backgrounding). It destroys anything whose countdown lapsed while the app was closed and re-arms live timers for the rest; unopened messages are left alone.

Persistence (schema v8)

Six columns were added to the messages table (DB bumped v7 → v8 via ALTER TABLE). Legacy rows default to non-ephemeral. See Persistence & SQLite for the full table.

• ephemeral, ttl_seconds — sender config (mirror the envelope eph/ttl).
• opened_at, expires_at — recipient-local timing (epoch ms), null until revealed.
• wilted — 1 once destroyed; the body columns are blanked in place.
• wilted_by — JSON list of peers who confirmed wilt (sender-side tally), synced like reactions.

UI & Composition

• Send text: long-press the send button → a duration sheet (slider 1–60s, default 5). A plain tap still sends a normal message; backing out of the sheet sends nothing. The send button is an InkWell (not an IconButton with a tooltip, whose own long-press recognizer would steal the gesture).
• Send image: the compression dialog has a "Wilting image" toggle + slider. Enabling it force-disables the Allow saving and Send hidden toggles — both contradict a self-destructing image (a downloadable wilt isn't wilting, and the reveal gate is the spoiler).
• Reveal → countdown → tombstone: received wilting content renders as a gate, then (on reveal) the content with a draining _WiltCountdownBar, then a "Wilted message" tombstone. Your own copy shows a small "Wilting message" tag and wilts on the peer's confirmation.
• Notifications stay content-free: wilting messages reuse the generic background alert (see Notifications & BG) — never a body preview, so the notification shade is not a retention hole.

Screenshot Request Cards

Consensual screenshots (state_screenshot.dart) also ride the wilt engine. FLAG_SECURE blocks OS captures, so a requester's app renders the chat to an image itself (a RepaintBoundary — a layer-tree render, not a window-buffer read) — but only after the other side(s) consent.

When a request arrives, in addition to the modal consent dialog, an in-history request card is inserted (content_type: 'screenshot_request', id ssreq_<reqId>, attributed to the requester) with Accept / Decline buttons — so a request missed while offline still leaves an answerable record. The card is marked ephemeral and expires via the wilt engine into "Screenshot request expired". Answering (via card or dialog) resolves it to accepted/declined and clears its expiry.

Key Files & Symbols

Gotchas & Edge Cases