Notifications & Background Modes

Overview

Wiltkey ships in two build flavors (Gradle product flavors from a single codebase) that differ only in how the app wakes for background messages:

• FOSS (GitHub / website, applicationId xyz.artfacility.wiltkey.foss) — zero Google Play Services. Background detection runs entirely in client isolates.
• Play (Google Play, xyz.artfacility.wiltkey) — adds Firebase Cloud Messaging only as a content-free wake-up trigger. No message content ever passes through Google; the encrypted payload stays queued on the relay and is pulled by the client on its next connection.

Both flavors expose the same three user-facing modes: Instant, Low Power (periodic HTTP polling), and Off. The only difference is what backs Instant: a persistent foreground WebSocket on FOSS, versus an FCM wake-up ping on Play (no persistent service, lighter on battery, and immune to the Android 15 6-hour dataSync timeout). The flavor is selected at build time via a Gradle flavor + the --dart-define=WK_FCM= flag, which gates every Firebase touchpoint on the Dart side (kFcmEnabled).

Background Sync Architectures

1. Instant Mode (Foreground Service)

Instant Mode spawns a persistent background isolate (_MessageTaskHandler) using flutter_foreground_task. It maintains an active, authenticated WebSocket connection to the relay, streaming messages as they arrive.

Secure Flat-File Buffering: When a message arrives while the device is locked, the master key is not in RAM, meaning the SQLite database cannot be decrypted or updated. To prevent dropping messages (the relay deletes messages once delivered), the background isolate appends the raw, encrypted envelope to a flat, append-only JSON lines file:

2. Low Power Mode (Periodic Polling)

Low Power Mode utilizes Android's WorkManager to run a periodic background task (callbackDispatcher) approximately every 10 minutes. Rather than establishing a full WebSocket session or downloading messages (which would violate privacy and drain battery), it calls a signature-authenticated endpoint on the server:

Future<bool> _pollQueueStatus(_BgCreds creds) async {
  final ts = (DateTime.now().millisecondsSinceEpoch ~/ 1000).toString();
  // Sign identity with Ed25519 key stashed in secure storage
  final sig = _sign(creds.privKeyHex, '${creds.userId}:$ts');
  final response = await client.get("/api/v1/queue/status?id=${creds.userId}×tamp=$ts&sig=$sig");
  return response.json['has_payload'] == true;
}

If has_payload is true, a local notification is shown. Messages are not downloaded until the user opens the application, ensuring decryption keys remain locked.

3. FCM Wake-up Push (Play Flavor Only)

On the Play build, Instant mode drops the persistent foreground service entirely and lets Firebase Cloud Messaging do the waking. The relay stores each Play user's FCM registration token (in Redis, keyed push:{userId}, 60-day TTL, refreshed on every connect); the FOSS build never registers one.

In-place upgrade healing: a user who ran the old foreground-service Instant build and updated in place keeps a stored notificationMode == instant, but the FCM token/permission setup only ever ran inside setNotificationMode — which they never re-triggered — so Instant looked selected yet stayed silent until they toggled the mode off, killed the app, and back on. reconcileInstantModeAfterUpgrade() now does that once automatically on the first unlock after the update (request permission + register token), gated by a persisted flag so it never re-nags. No-op on FOSS.

Delivery flow:

1. Register: the client fetches its FCM token over the native wiltkey/push MethodChannel and registers it with the relay (POST /api/v1/push/register), authenticated with the same Ed25519 signature scheme as queue/status — so a device can only set its own token.
2. Ping: when a message is queued for an offline recipient that has a token, the relay sends a data-only, high-priority FCM message carrying nothing but the sender's key hash (a one-way hash, for deep-linking) — never message content.
3. Notify: a native service (WiltkeyFirebaseService, compiled into the Play flavor only) receives the ping and posts a content-free "New secure message" notification — a genuine, user-perceptible alert (no policy-dodging placeholder tricks).
4. Pull: the encrypted payload is still sitting in the relay's offline queue. It's delivered normally the next time the app connects (foreground), decrypted with the master key, and written to SQLite — exactly like the FOSS pull path.

// fcm.go — service-account JWT → OAuth2 token → FCM HTTP v1 data-only push.
// Disabled/no-op unless FCM_CREDENTIALS_FILE is set, so the self-hosted /
// FOSS relay is unaffected. Only sender_id (a hash) is ever transmitted.
"message": { "token": token, "data": {"sender_id": senderID},
             "android": {"priority": "HIGH"} }

Key Files & Symbols

Gotchas & Edge Cases