com.vitorpamplona.amethyst/docs/plans/2026-06-30-feat-messaging-privacy-lock-plan.md

title, type, status, date, origin

title	type	status	date	origin
Messaging Privacy Lock	feat	active	2026-06-30	docs/brainstorms/2026-06-30-feat-messaging-privacy-lock-brainstorm.md

Messaging Privacy Lock

Route-scoped lock on the Messages destination + companion defenses (notification redaction, screen-capture block, blur-on-unfocus) that prevent an attentive snooper from reading DMs on an unattended-but-unlocked device. Industry baseline = Signal screen-lock + WhatsApp Chat Lock, collapsed to Messages route only, OS-credential-only (no Amethyst PIN), device-global, off-by-default with a one-time prompt.

All decisions traced back to the brainstorm (see brainstorm: docs/brainstorms/2026-06-30-feat-messaging-privacy-lock-brainstorm.md).

Enhancement Summary

Deepened on: 2026-06-30 Reviewers: security-sentinel, architecture-strategist, code-simplicity-reviewer, performance-oracle, spec-flow-analyzer, pattern-recognition-specialist

Key changes incorporated

1. Security hardening — six previously-missed content-leak paths added to scope: crash-report scrubbing, DM-content log scrub, MessagingStyle history flush on first enable, NotificationListener payload redaction (main builder, not just setPublicVersion), bunker decrypt queue drained on re-lock, deep-link race fixed by synchronous initial-state read.
2. Architecture corrections — CompositionLocal instead of commons/jvmMain → desktopApp import (broke dependency arrow); PrivacyLockPreferences moved to commons/jvmAndroid source set (was breaking iOS); native binaries moved to canonical appResources/{macos,linux,windows}/; SecureScreenEffect relegated to Android-only (no JVM equivalent).
3. Performance — gate uses state.map { it is Locked }.distinctUntilChanged() to keep chat subtree off the recomposition path; SharingStarted.Eagerly; Activity-level FLAG_SECURE so cold-resume thumbnail is blanked from frame 0; blur radius 16dp on overlay layer (not LazyColumn).
4. Scope cuts — Windows Hello native helper deferred (v1 uses CredUIPromptForCredentials = OS password, biometric in v2); Linux entirely deferred (lock toggle shows "Not available on Linux yet" banner in v1); 2-level notification (Generic / Full), no chooser dialog; first-run card buttons collapsed to Enable / Not now (no "Don't ask" persistence).
5. Edge cases formalized as ACs — empty-Messages first-run card, account-switch = leave-route, BiometricPrompt-up + background cancellation, draft persistence via overlay (not unmount), media playback does NOT reset idle timer, in-app DM banner suppressed on Messages route while locked.
6. Naming aligned — PreferencesPrivacyLockSettings (mirrors PreferencesHashtagSpamSettings); JNA under desktopApp/.../service/security/ (mirrors service/media/).

Overview

Five user-visible deliverables, gated behind a single device-global toggle:

1. Messages-route gate — biometric / OS-credential prompt before any DM UI renders. Re-locks on inactivity (default 5 min, configurable Immediate–Never) and on leaving the route.
2. Notification preview redaction — 3-level (Full / Sender-only / Generic). Auto-bumps to Generic on first lock-enable with a chooser.
3. Screen-capture block — Android FLAG_SECURE, macOS NSWindow.sharingType = .none, Windows SetWindowDisplayAffinity(WDA_EXCLUDEFROMCAPTURE). Linux: not available; documented limitation.
4. Desktop blur-on-unfocus — Messages content renders blurred while the window is unfocused; no PIN re-entry on focus regain.
5. First-run inline card — top-of-Messages prompt offering Enable / Not now / Don't ask.

Problem Statement

Amethyst currently has zero protection against snooping on an unattended device. Anyone who walks past a logged-in install can read DM history, including NIP-04 + NIP-17 private chats + Marmot group chats. The existing SecurityFiltersScreen is a misnomer — it gates spam/content filters, not privacy. Notification banners on Android show the sender's name in the title even when the message body is generic. Recents thumbnails and screen-sharing tools capture chat content unrestricted.

The intended user is a person who:

• Leaves their device unlocked for short periods (coffee shop, family living room, shared workstation).
• Wants reasonable, inconvenient-but-tolerable friction guarding the Messages tab specifically.
• Does not expect protection against a fully hostile device-possessor (rooted Android, attached debugger, filesystem-level access).

Proposed Solution

A device-global toggle (PrivacyLockPreferences.lockEnabled) drives a MessagesLockState StateFlow consumed by a shared MessagesLockGate composable. The gate wraps every Messages-route entry composable on both Android and Desktop. When state is Locked, the gate intercepts and shows a lock screen with a single "Unlock" affordance. Tapping the affordance invokes the platform-specific CredentialPrompter, which routes to:

Platform	Primary	Fallback
Android	BiometricPrompt(STRONG | DEVICE_CREDENTIAL)	Device PIN/Pattern (built into the prompt)
macOS	LAContext.evaluatePolicy(.deviceOwnerAuthentication) via ~80-line Swift .dylib shim + JNA	OS password (built into LAPolicy)
Windows	CredUIPromptForCredentials via JNA (User32) → OS password only in v1	Same
Linux	Lock disabled in v1 — settings shows "Not available on Linux yet" banner	—

Why Windows Hello + Linux were deferred (per deepen-plan simplicity review): no maintained JVM WinRT projection (would require a native .exe helper, code-signing, MSI bundling — heavy v1 cost for biometric vs. OS password); polkit Linux flow needs root-installed policy that breaks Flatpak distribution. Both tracked under Future Considerations.

On success the gate transitions to Unlocked; an idle timer drives the re-lock; navigation away from the route flips state to Locked immediately. Companion defenses (FLAG_SECURE, sharing block, blur-on-unfocus, notification redaction) are all conditioned on lockEnabled and applied automatically — no extra UI knobs in v1.

Technical Approach

Architecture

                  ┌─────────────────────────────────┐
                  │   PrivacyLockPreferences        │  java.util.prefs (jvm)
                  │   ─ lockEnabled: Boolean        │   + SharedPreferences (Android)
                  │   ─ inactivityMillis: Long      │
                  │   ─ notificationLevel: …        │
                  │   ─ firstRunPromptDismissed     │
                  │   ─ disabledByMissingCredential │
                  └────────────┬────────────────────┘
                               │
                  ┌────────────▼────────────────────┐
                  │   MessagesLockState              │  StateFlow<LockState>
                  │   ─ Disabled / Locked / Unlocked │
                  │   ─ onUserInteraction()          │
                  │   ─ onLeaveRoute()               │
                  │   ─ onUnlockSuccess()            │
                  │   ─ onCredentialUnavailable()    │
                  └────────────┬────────────────────┘
                               │
            ┌──────────────────┴──────────────────┐
            │                                     │
   ┌────────▼─────────┐                ┌──────────▼────────┐
   │  Android UI       │                │   Desktop UI       │
   │   (amethyst/)     │                │   (desktopApp/)    │
   ├───────────────────┤                ├────────────────────┤
   │  MessagesLockGate │                │  MessagesLockGate  │
   │  (commons/common) │                │  (commons/common)  │
   │  ↓                │                │  ↓                 │
   │  AndroidCredential│                │  Mac / Win / Linux │
   │  Prompter         │                │  CredentialPrompter│
   │  (expect/actual)  │                │  (expect/actual)   │
   │                   │                │                    │
   │  FLAG_SECURE      │                │  NSWindowSharingNone│
   │  on chat screens  │                │  / WDA_EXCLUDE…    │
   │                   │                │                    │
   │  Notification     │                │  WindowFocus → blur│
   │  redaction        │                │                    │
   └───────────────────┘                └────────────────────┘

Single state holder, two UIs subscribed. Mirrors the LocalRelayStore / LocalRelayMaintenance pattern already established in the embedded-relay work (see desktopApp/plans/2026-05-09-embedded-local-relay-plan.md).

Module map

Concern	Module / Source set	Path
PreferencesPrivacyLockSettings (mirrors PreferencesHashtagSpamSettings; node com/vitorpamplona/amethyst/privacylock)	commons/jvmAndroid (shared by Android + Desktop, NOT iOS — per commons/ARCHITECTURE.md §3)	commons/.../privacylock/PreferencesPrivacyLockSettings.kt
MessagesLockState (StateFlow + idle timer)	commons/commonMain	commons/.../privacylock/MessagesLockState.kt
DmRedactionLevel enum (Generic / Full) + redaction policy (CLI-safe data)	commons/commonMain	commons/.../privacylock/DmRedactionPolicy.kt
MessagesLockGate composable + lock-screen UI	commons/commonMain	commons/.../ui/privacylock/MessagesLockGate.kt
interface CredentialPrompter + LocalCredentialPrompter CompositionLocal (no expect/actual — supplied per platform at App root)	commons/commonMain	commons/.../ui/privacylock/CredentialPrompter.kt
Android BiometricCredentialPrompter	amethyst/.../security/	BiometricCredentialPrompter.kt
macOS Touch ID Swift shim source	desktopApp/src/jvmMain/native/macos/	TouchIDShim.swift
macOS Touch ID compiled binary	desktopApp/src/jvmMain/appResources/macos/ (Compose canonical native-resource root, picked up automatically by nativeDistributions)	libAmethystTouchID.dylib
Windows OS password prompter (v1 — no Hello)	desktopApp/.../service/security/	WindowsPasswordPrompter.kt (JNA → User32.CredUIPromptForCredentials)
macOS Touch ID prompter (Kotlin side)	desktopApp/.../service/security/	MacTouchIdPrompter.kt (JNA → libAmethystTouchID.dylib)
Desktop CredentialPrompter provider (selects Mac/Win/no-op)	desktopApp/.../service/security/	DesktopCredentialPrompterFactory.kt (lives in desktopApp, NOT commons/jvmMain — PlatformInfo ownership stays where it is)
FrameWindowScope.applyWindowCaptureBlock(enabled)	desktopApp/.../platform/	WindowCaptureBlock.kt (alongside applyNativeWindowChrome in PlatformTheme.kt)
Desktop window-focus StateFlow + LocalWindowFocus	desktopApp/.../platform/	WindowFocusOwner.kt
LocalMessagesLockState CompositionLocal (provided once at App root on both platforms)	commons/commonMain	commons/.../privacylock/MessagesLockState.kt (companion)
Android settings UI + first-run card	amethyst/.../settings/ + amethyst/.../chats/	PrivacyLockSettingsScreen.kt, MessagesFirstRunCard.kt
Desktop settings UI (Column + Card pattern from LocalRelaySettingsScreen, NO Scaffold) + first-run card	desktopApp/.../settings/ + desktopApp/.../chats/	PrivacyLockSettingsScreen.kt, MessagesFirstRunCard.kt
Notification redaction call site (Android-only — NotificationUtils.kt doesn't exist on Desktop)	amethyst/.../service/notifications/	edit NotificationUtils.kt:370-510 to consume DmRedactionPolicy from commons
Idle-timer modifier (Modifier.resetIdleOnInteraction() — single root attach, not per-composable)	commons/commonMain	commons/.../ui/privacylock/IdleTimerModifier.kt
FLAG_SECURE wrapper (Android-only — no expect/actual; desktop uses window-level WindowCaptureBlock)	amethyst/.../security/	SecureScreenEffect.kt
Crash-report DM scrubber (NEW — security hardening)	amethyst/.../service/crashreports/	edit ReportAssembler.kt to strip Throwable.message when origin package is nip04Dm / nip17Dm / marmot
DM-content log audit (NEW — security hardening)	amethyst/.../service/notifications/ + commons/.../bunker/	grep + edit: EventNotificationConsumer.kt:349,392,435,491,549,695, RemoteSignerManager.kt:53 — strip body fields from Log.d

commons/ARCHITECTURE.md governs package taxonomy — new package commons/.../privacylock/ for state + prefs + policy, commons/.../ui/privacylock/ for Compose surfaces.

Pattern note (new): LocalMessagesLockState + LocalCredentialPrompter introduce app-global CompositionLocals provided once at the App root. Mirrors the existing precedent LocalRelayStore-style provision in desktopApp/Main.kt (single instantiation site, app-global, not per-Window — required so multi-window desktop in the future doesn't bypass the lock).

Implementation Phases

Phase 1: Foundation (state + preferences + tests)

Lay the cross-platform spine before touching either UI. Output: a testable, headless state machine with unit-test coverage.

Critical requirement (per deepen perf finding): initial LockState value MUST be derived synchronously from prefs.lockEnabled BEFORE the first composition runs. setContent {} must see Locked as the seed value the first time it composes — never Unlocked followed by an async update. This is the foundation of the deep-link race fix (see Security Hardening below).

• New files:

  • commons/src/commonMain/.../privacylock/MessagesLockState.kt
    • sealed class LockState { Disabled; Locked; Unlocked }
    • class MessagesLockState(prefs, clock, scope)
      • val state: StateFlow<LockState> — backed by MutableStateFlow(seedFromPrefsSynchronously())
      • Uses SharingStarted.Eagerly (NOT WhileSubscribed — needed because the notification path reads lockEnabled outside any UI collector, per deepen perf finding #4)
    • fun onUserInteraction() — idempotent
    • fun onLeaveRoute() — idempotent; transitions Unlocked→Locked
    • fun onUnlockSuccess() — transitions Locked→Unlocked, restarts idle timer
    • fun onCredentialUnavailable() — single-arg (no reason variants per simplicity review); transitions to Disabled, persists flag, no-op if already Disabled
    • companion object { val LocalMessagesLockState: ProvidableCompositionLocal<MessagesLockState> }
  • commons/src/commonMain/.../privacylock/InactivityTimer.kt
    • enum class InactivityTimer(val millis: Long?): OneMin, FiveMin, FifteenMin, OneHour, Never. Default FiveMin. Immediate dropped (per simplicity review — redundant with leave-route trigger.)
  • commons/src/commonMain/.../privacylock/DmRedactionPolicy.kt
    • enum class DmRedactionLevel { Generic; Full } (2 levels, not 3 — per simplicity review; "Sender only" was niche middle ground)
    • fun resolveLevel(lockEnabled: Boolean, userChoice: DmRedactionLevel?): DmRedactionLevel — when lockEnabled and user hasn't explicitly chosen, returns Generic. When !lockEnabled, returns Full.
  • commons/src/jvmAndroid/.../privacylock/PreferencesPrivacyLockSettings.kt
    • Mirrors PreferencesHashtagSpamSettings shape (class taking prefs, exposes StateFlow mutators).
    • Backing storage: java.util.prefs on Desktop / SharedPreferences on Android (each platform sets up its own Preferences instance and hands it in — jvmAndroid source set doesn't pick the storage backend).
    • Keys: lockEnabled, inactivityTimerOrdinal, redactionLevelOrdinal, firstRunCardSeen. Removed: disabledByMissingCredential (per simplicity review — re-check via BiometricManager.canAuthenticate() on settings render).
  • commons/src/commonTest/.../privacylock/MessagesLockStateTest.kt
    • 5 unit tests (down from 12 per simplicity review — start small):
      1. Idle expiry fires lock
      2. Leave-route locks immediately
      3. Cold-start with lockEnabled=true seeds to Locked
      4. Settings cascade — toggle off transitions Locked→Disabled
      5. Never timer doesn't fire

• Acceptance:

  • ./gradlew :commons:jvmTest --tests "*MessagesLockStateTest*" green
  • State machine is idempotent on duplicate triggers
  • No new deps required; uses kotlinx.coroutines.flow only
  • Initial value seeded synchronously (no flash on cold start)

Phase 2: Android lock + UI + notification redaction + leak audit

Wire the gate, settings, and notification redaction on Android. This phase incorporates the security-hardening leak fixes surfaced during deepen review (crash, logs, MessagingStyle history, NotificationListener payload).

• New files:

  • commons/.../ui/privacylock/MessagesLockGate.kt (commonMain) — gate hosts the lock overlay ONLY; content lambda passed in unchanged. State read uses state.map { it is Locked }.distinctUntilChanged().collectAsStateWithLifecycle(initialValue = state.value is Locked) so the chat subtree never recomposes on idle-tick non-flips. Gate selects branch SYNCHRONOUSLY in composition (when { locked -> LockOverlay(); else -> content() }) — no LaunchedEffect guard (per security finding #1).
  • commons/.../ui/privacylock/CredentialPrompter.kt (commonMain) — interface CredentialPrompter { suspend fun prompt(reason: String): PromptResult }, LocalCredentialPrompter CompositionLocal.
  • amethyst/.../security/BiometricCredentialPrompter.kt — wraps BiometricPrompt(STRONG | DEVICE_CREDENTIAL). Reuse pattern from UpdateZapAmountDialog.kt:428-479. Provided into LocalCredentialPrompter at the AmethystApp composition root. Error mapping (single-reason variant per simplicity review):
    • ERROR_USER_CANCELED → stay locked, no toast
    • ERROR_LOCKOUT → "Try again in 30 sec" toast, stay locked
    • ERROR_LOCKOUT_PERMANENT / ERROR_NO_HARDWARE / ERROR_NONE_ENROLLED → state.onCredentialUnavailable()
  • amethyst/.../security/SecureScreenEffect.kt (Android-only — no expect/actual per architecture review). Toggles WindowManager.LayoutParams.FLAG_SECURE.
  • commons/.../ui/privacylock/IdleTimerModifier.kt (commonMain) — single Modifier.resetIdleOnInteraction(state) using Modifier.pointerInput(Unit) { awaitPointerEventScope { while(true){ awaitPointerEvent(PointerEventPass.Initial); state.onUserInteraction() } } }. Initial pass = observe without consuming. Per-keypress TextField reset wired via a separate onValueChange adapter at the compose sites that have text fields.

• Edited files:

  • amethyst/.../MainActivity.kt — set Window.addFlags(FLAG_SECURE) early in onCreate (window-level, not per-screen DisposableEffect) when prefs.lockEnabled == true. This closes the recents cold-reattach thumbnail leak window (security finding #6 + perf finding #6). Per-screen SecureScreenEffect stays as belt-and-suspenders for when chat is visible but lock toggle was just flipped on.
  • amethyst/.../ui/screen/loggedIn/chats/rooms/MessagesScreen.kt — wrap top-level composable in MessagesLockGate; attach Modifier.resetIdleOnInteraction(state) once at the route root (per architecture review's "single root attach" recommendation).
  • amethyst/.../ui/screen/loggedIn/chats/privateDM/ChatroomScreen.kt — wrap content in SecureScreenEffect(enabled = lockEnabled); treated as inside-gate so deep-link from notification still transits the parent-route gate.
  • amethyst/.../ui/screen/loggedIn/chats/marmotGroup/MarmotGroupScreen.kt — same. Verify gate wraps at route level (not deep inside the composable tree), per architecture review.
  • amethyst/.../service/notifications/NotificationUtils.kt — consume DmRedactionPolicy from commons. Redact the MAIN builder, not just setPublicVersion (security finding #5 — NotificationListener apps see the main Notification.extras):
    • When level == Generic: setContentTitle("Amethyst"), setContentText("New message"), do NOT add MessagingStyle.addMessage(body, …) (which persists across updates and leaks pre-enable history).
    • Disable inline-reply RemoteInput when level=Generic (would otherwise let the system quote the original message — security finding #13).
    • On first lock-enable, call NotificationManagerCompat.cancel(DM_GROUP_KEY) to flush pre-enable MessagingStyle history (security finding #4).
    • Bypass Log.d("$content $title …") style logging in DM paths (security finding #3) — survey lines 349, 392, 435, 491, 549, 695 in EventNotificationConsumer.kt and strip body fields.
  • amethyst/.../service/crashreports/ReportAssembler.kt — NEW security hardening (finding #2). Strip Throwable.message to class-name-only when origin package is nip04Dm, nip17Dm, or marmot. Always-on (not gated on lockEnabled — DM plaintext in crash reports is never a feature).
  • commons/.../bunker/RemoteSignerManager.kt — on MessagesLockState transition Unlocked→Locked, drain the bunker decrypt response queue (security finding #7). Cancel in-flight Channel<Response> subscriptions for DM decrypt requests.

• New settings:

  • amethyst/.../ui/screen/loggedIn/settings/PrivacyLockSettingsScreen.kt
    • Toggle: Lock Messages (calls BiometricManager.canAuthenticate() on render — if unavailable, toggle disabled + banner)
    • Spinner: Lock after [1 min / 5 min / 15 min / 1 hour / Never] (5 values, default 5 min — per simplicity review, Immediate dropped as redundant with leave-route)
    • Toggle: Hide notification preview (2-level: On = Generic, Off = Full — chooser dialog dropped per simplicity review)
    • Inline hint: "Notifications hide content while lock is on."
    • Banner (when canAuthenticate returns NO_HARDWARE / NONE_ENROLLED): "Lock disabled — no biometric or device credential available."
    • Copy: "Lock applies to Messages only. Other parts of the app stay open. Does NOT protect against rooted devices, debuggers, filesystem access, apps with notification-listener permission, or screen-recording apps you've granted access — your nsec is still stored as it is today." (Honest threat-model copy per security finding #15.)
  • Add link from existing SecurityFiltersScreen.kt to PrivacyLockSettingsScreen. Keep SecurityFiltersScreen name to minimize churn; add a "Privacy" sub-link clearly labeled.

• First-run card:

  • amethyst/.../ui/screen/loggedIn/chats/rooms/MessagesFirstRunCard.kt — inline Card at top of MessagesScreen, structurally modeled on OfflineBanner.kt from the embedded-relay work (per pattern review). Two buttons (per simplicity review): Enable / Not now. Auto-suppress after firstRunCardSeen is set OR after lockEnabled flips to true. (No "Don't ask" plumbing.) Renders independently of DM list state — visible even on empty Messages (per spec-flow gap #1).

• Acceptance:

  • ./gradlew :amethyst:assembleDebug succeeds
  • Manual: gate appears, biometric unlocks, idle timer locks, navigation away locks immediately
  • Recents-screen thumbnail blank when in Messages (verify on BOTH cold cold-start and warm resume — security finding #6)
  • Notification preview hidden by default after enable
  • First-enable flushes MessagingStyle history (security AC)
  • NotificationListenerService apps see redacted main builder when level=Generic (verify with a side-loaded NL app)
  • Crash report from an injected DM-decode error contains no plaintext (security AC)
  • logcat | grep -i 'dm\|chat' produces no plaintext while DMs flow (security AC)
  • First-run card displays on empty Messages tab
  • Deep-link from notification: chat content NEVER paints before gate (security AC — write Compose-test screenshot diff on the transition frame)

Phase 3: Desktop lock + UI + macOS Touch ID + Windows OS password

Scope cut per deepen simplicity review: Linux is fully deferred to v2 (toggle disabled with "Not available on Linux yet" banner); Windows ships with OS password only in v1 (Windows Hello deferred — no JVM-native WinRT projection). macOS gets Touch ID via the Swift shim — small enough to justify (~80 LOC).

• New files:

  • desktopApp/.../service/security/DesktopCredentialPrompterFactory.kt — selects MacTouchIdPrompter on macOS, WindowsPasswordPrompter on Windows, returns a no-op disabled prompter on Linux. Provided into LocalCredentialPrompter at the App() root in Main.kt.
  • desktopApp/.../service/security/MacTouchIdPrompter.kt — JNA into libAmethystTouchID.dylib.amethyst_touchid_authenticate.
  • desktopApp/.../service/security/WindowsPasswordPrompter.kt — JNA into User32.CredUIPromptForCredentials. No Windows Hello in v1 — drops native helper + signing + MSI bundling cost. Documented in copy: "Windows uses your account password until we add Windows Hello support."
  • desktopApp/src/jvmMain/native/macos/TouchIDShim.swift — source, ~80 lines:

    import LocalAuthentication
    
    @_cdecl("amethyst_touchid_authenticate")
    public func authenticate(reason: UnsafePointer<CChar>) -> Int32 {
        let ctx = LAContext()
        var err: NSError?
        guard ctx.canEvaluatePolicy(.deviceOwnerAuthentication, error: &err)
        else { return -1 }
        let sem = DispatchSemaphore(value: 0)
        var ok = false
        ctx.evaluatePolicy(.deviceOwnerAuthentication,
            localizedReason: String(cString: reason)) { success, _ in
            ok = success
            sem.signal()
        }
        sem.wait()
        return ok ? 0 : 1
    }
    

    Hardcode reason string on the Kotlin side (security finding #14 — no user-controlled strings to the OS prompt). Compiled with swiftc -emit-library -o libAmethystTouchID.dylib on macOS hosts.
  • desktopApp/src/jvmMain/appResources/macos/libAmethystTouchID.dylib — committed pre-built artifact. Compose Desktop's appResourcesRootDir is the canonical location (already used by VLC bundles per desktopApp/build.gradle.kts:107,173-175), so nativeDistributions picks it up automatically. No new Gradle tasks required (per architecture review #8). Recompile recipe documented separately at desktopApp/plans/2026-06-30-privacy-lock-native-shims-recipe.md.
  • desktopApp/.../platform/WindowFocusOwner.kt — LocalWindowFocus: ProvidableCompositionLocal<StateFlow<Boolean>>. Sourced from window.addWindowFocusListener events emitted into a MutableStateFlow.
  • desktopApp/.../platform/WindowCaptureBlock.kt — fun FrameWindowScope.applyWindowCaptureBlock(enabled: StateFlow<Boolean>):
    • macOS: JNA into NSWindow.setSharingType(0) — extract JNA pattern from existing applyNativeWindowChrome() in PlatformTheme.kt:87. Apply via LaunchedEffect(enabled) { ... } so JNA call fires only on flip, not per recomposition (perf finding #5). Use DisposableEffect to restore sharingType = normal on disable.
    • Windows: JNA into User32.SetWindowDisplayAffinity(hwnd, WDA_EXCLUDEFROMCAPTURE). Same effect plumbing.
    • Linux: no-op.

• Edited files:

  • desktopApp/.../Main.kt — inside Window { ... } block (line 316), invoke applyWindowCaptureBlock(lockEnabledFlow) next to existing applyNativeWindowChrome(). Construct the app-global MessagesLockState ONCE here and provide both LocalMessagesLockState and LocalCredentialPrompter at the App root. Multi-window correctness (architecture review #5).
  • desktopApp/.../ui/chats/DesktopMessagesScreen.kt, ChatPane.kt, ConversationListPane.kt — wrap in MessagesLockGate. Apply Modifier.resetIdleOnInteraction(state) at the route root only.
  • desktopApp/.../ui/chats/ChatPane.kt — apply Modifier.blur(16.dp, BlurredEdgeTreatment.Unbounded) on an OVERLAY layer (not on the LazyColumn), driven by LocalWindowFocus. Cap at 16dp (perf finding #2). On macOS 15+ and Linux, default blur radius even when focused (because the capture block is broken/absent — partial compensation per security findings #9 and #10).
  • desktopApp/build.gradle.kts — only addition is the macOS infoPlist block to add NSFaceIDUsageDescription. Native binaries auto-bundled via appResources/macos/.
  • desktopApp/.../ui/settings/PrivacyLockSettingsScreen.kt — follows LocalRelaySettingsScreen shape (Column + Card, NO Scaffold — pattern review). Same toggles/spinners as Android. On Linux, the whole settings group is replaced by a banner: "Not available on Linux yet." On macOS 15+, an info row: "Screen capture protection is limited on macOS 15+." On Windows, info row: "Windows uses your account password — Hello support coming later."

• Acceptance:

  • ./gradlew :desktopApp:run on macOS: Touch ID prompt appears, success unlocks, cancel keeps locked
  • ./gradlew :desktopApp:run on Windows: OS-password prompt appears (CredUI dialog), success unlocks
  • ./gradlew :desktopApp:run on Linux: lock toggle in settings is disabled with banner; Messages route shows no gate
  • DMG / MSI builds succeed (no new MSI signing required since Hello helper is deferred)

Phase 4: Desktop companion defenses + blur + first-run

• Edited files:

  • desktopApp/.../ui/chats/DesktopMessagesScreen.kt — apply Modifier.blur(...) driven by LocalWindowFocus.
  • desktopApp/.../ui/chats/MessagesFirstRunCard.kt — new inline card composable mirroring Android.

• Window-focus wiring:

  • Main.kt Window block: emit window-focus events into LocalWindowFocus StateFlow via window.addWindowFocusListener { ... }.

• macOS Sequoia/Tahoe caveat:

  • PrivacyLockSettingsScreen shows an info row when running on macOS 15+: "Screen sharing protection is limited on macOS 15+ due to a system-level change — relying on this for hostile environments is not advised."

• Linux caveat:

  • On Linux, the same row reads: "Screen capture protection is not available on Linux. Lock + blur + notification redaction still apply."

• Acceptance:

  • Alt-tab away from window → Messages content blurs
  • Alt-tab back → blur clears, no re-prompt
  • macOS: screenshot via ⌘+Shift+3 produces blank on the Messages window (best-effort on 15+ — verify and document)
  • Windows: PrtScn + clipboard paste shows blank Messages window
  • Linux: row says "not available"

Phase 5: Polish, l10n, docs, manual testing

• Translation strings — add ~20 strings to Android amethyst/src/main/res/values/strings.xml and desktop desktopApp/.../resources/messages.properties:
  • lock_messages_title, lock_messages_subtitle, lock_after, immediate/1min/5min/15min/1hour/never, notification_preview, full/sender_only/hidden, lock_screen_title, lock_screen_unlock_button, first_run_card_title, first_run_card_enable, first_run_card_not_now, first_run_card_dont_ask, lock_disabled_no_credential_banner, capture_protection_linux_unavailable, capture_protection_macos15_caveat
• Crowdin auto-sync handles propagation (PR #3142 just merged translations — verify pipeline)
• Final ./gradlew spotlessApply
• Update commons/ARCHITECTURE.md with new privacylock/ package
• Update MEMORY.md index entry for this work
• Hand-written manual testing sheet (post-implementation deliverable)

Security Hardening Additions (from deepen review)

Six previously-missed leak paths now in scope. Each maps to a concrete edit elsewhere in the plan; this section is the punch list.

#	Leak path	Severity	Mitigation	Status in plan
H1	Deep-link race — LaunchedEffect guard insufficient; chat content can flash 1 frame before gate paints	HIGH	Gate selects branch SYNCHRONOUSLY in composition; MessagesLockState.state seeded synchronously from prefs before setContent; Compose-test screenshot diff asserts no-flash invariant	Phase 1 (seed) + Phase 2 (gate composable + AC)
H2	Crash reports serialize Throwable.message containing decrypted DM plaintext (Jackson parse errors echo input; NIP-44 errors echo bytes)	HIGH	ReportAssembler.kt strips Throwable.message to class-name-only when origin package is nip04Dm, nip17Dm, or marmot. Always-on.	Phase 2 (new edit)
H3	Log.d calls in DM notification path echo decrypted content; Proguard does not reliably strip in release; visible via adb logcat and NotificationListener apps with logging plugins	HIGH	Audit lines 349, 392, 435, 491, 549, 695 in EventNotificationConsumer.kt and RemoteSignerManager.kt:53; strip body fields, keep only event ID + length	Phase 2 (new edit)
H4	NotificationCompat.MessagingStyle.addMessage(...) persists pre-enable history in system NotificationManager; lockscreen redaction does not affect it	HIGH	On first lock-enable, call NotificationManagerCompat.cancel(DM_GROUP_KEY) to flush; do not call addMessage(body, …) when level=Generic	Phase 2 (edit NotificationUtils.kt)
H5	NotificationListenerService apps see the full Notification payload (extras.text, MessagingStyle); setPublicVersion only affects lockscreen	HIGH	Redact the MAIN builder when level=Generic — setContentText("New message"), omit MessagingStyle.addMessage, disable inline-reply RemoteInput (which would otherwise let the system quote the original message — finding #13)	Phase 2 (edit NotificationUtils.kt)
H6	NIP-46 bunker decrypt responses queued on a channel; on re-lock, in-flight responses can deliver plaintext to a recomposed (now-locked) chat scope	MEDIUM	On MessagesLockState Unlocked→Locked transition, cancel in-flight bunker decrypt request subscriptions and clear the response channel	Phase 2 (edit RemoteSignerManager.kt)

These are NOT optional polish — without them the v1 lock fails to deliver even its narrow "cosmetic shoulder-surf" promise honestly.

Alternative Approaches Considered

1. App-wide lock (not just Messages route). Rejected during brainstorm — user explicitly chose Messages-only. Higher friction for low gain.
2. In-app Amethyst PIN. Rejected — OS device credentials are better UX and better security (no PIN reuse, no recovery to build).
3. Per-conversation lock (WhatsApp Chat Lock-style). Rejected for v1 as scope creep. Could layer on later as a per-Chatroom flag.
4. nsec encryption-at-rest with PIN-derived key. Recognized as the cryptographic upgrade that would close the "device-possessor" threat. Explicitly deferred to Phase 2 (separate brainstorm) until v1 ships and we have user feedback.
5. Background / system-lock as trigger. User chose to skip — the inactivity timer (default 5 min) subsumes it within the same window.
6. Rococoa for macOS Touch ID (vs Swift .dylib shim). Rejected — shim is smaller (~80 LOC) and avoids pulling in a 5MB framework dependency. JNA + a single .dylib matches the existing MacOsVlcDiscoverer.kt JNA pattern.

System-Wide Impact

Interaction Graph

User taps Messages tab → NavController.navigate("messages") → MessagesScreen composes → MessagesLockGate consumes MessagesLockState.state →

• If Disabled or Unlocked → render content + apply SecureScreenEffect + (desktop) Modifier.blur(focusState)
• If Locked → render lock screen with "Unlock" button → user taps → CredentialPrompter.prompt(...) → (Android) BiometricPrompt.authenticate(...) → (macOS) JNA → libAmethystTouchID.dylib.amethyst_touchid_authenticate(...) → LAContext.evaluatePolicy(...) → callback success → MessagesLockState.onUnlockSuccess() → state flips to Unlocked → recomposition → content renders.

User receives DM while app foregrounded but on a different route → EventNotificationConsumer.consume(event) →

• If lockEnabled → sendDMNotification(level = current) → NotificationCompat.Builder.setPublicVersion(...) → user sees redacted preview on lock screen.

User taps DM notification → MainActivity.onNewIntent(intent) → NavController deep-link to chatroom → MessagesScreen route entered → gate intercepts (because state was Locked from a prior leave-route event) → unlock prompt → on success → chatroom shows.

Error Propagation

Origin	Error	Handled at	Result
BiometricPrompt	ERROR_USER_CANCELED	CredentialPrompter.android.kt	Swallowed; stay locked
BiometricPrompt	ERROR_LOCKOUT	same	Toast "Try again in 30 sec"; stay locked
BiometricPrompt	ERROR_LOCKOUT_PERMANENT	same	onCredentialUnavailable(LockoutPermanent) → state → Disabled + banner
BiometricPrompt	ERROR_NO_HARDWARE	same	onCredentialUnavailable(NoCredential) → same
TouchIDShim	canEvaluatePolicy = false	MacTouchIdPrompter	onCredentialUnavailable(NoCredential)
TouchIDShim	evaluate → false (user cancel)	same	Stay locked, no toast
WindowsHello helper	ProcessBuilder non-zero exit	WindowsHelloPrompter	If exit code = 2 (WinRT unavailable) → fall back to CredUIPromptForCredentials
Linux password	wrong password	LinuxPasswordPrompter	Toast "Wrong password"; stay locked. Throttle: 5s lockout after 3 attempts.
MessagesLockState	preferences write fails	PrivacyLockPreferences	Log + propagate (caller treats as best-effort)
Notification redaction	level mismatched on platform change	NotificationUtils	Falls back to Generic — safe default

State Lifecycle Risks

Risk	Mitigation
App killed mid-unlock leaves state inconsistent	State is in-memory; cold start re-reads lockEnabled from prefs → if enabled, starts in Locked. Fail-safe by default.
Idle timer fires while user is typing a message	Timer resets on keyboardCharType interaction events; types via Modifier.pointerInput + composing-text interaction.
Switching Nostr accounts mid-session	Setting is device-global → state persists. Users expect this.
Settings change "disable lock" while screen is Locked	State holder receives prefs flow update → transitions Locked → Disabled. Gate transparently shows content.
Deep-link from notification while locked	Notification intent → MainActivity → NavController.handleDeepLink → MessagesScreen route → gate intercepts. Critical: ensure no chat content is rendered before gate paints (use LaunchedEffect initial composition guard).
Restoring app from recents (Android) while Locked	Lock state persists in MessagesLockState. Recents thumbnail is FLAG_SECURE-blanked.
Window-focus oscillation (rapid alt-tab)	Debounce blur transition by 100ms to avoid visual flicker.

API Surface Parity

Surface	Affected?	Notes
amy CLI	No	CLI has no Compose UI. PrivacyLockPreferences is exposed but CLI commands don't gate by it. Future: amy lock status for debugging.
Android Quick-Tile widgets	No widgets today
Wear OS companion	None today
Search (global)	Yes — verify	Audit MessagesSearchScreen / global search results: when locked, must NOT surface DM hits. Add filter isMessagesLocked to search result aggregation.
Notifications service	Yes	EventNotificationConsumer reads lockEnabled + redaction level.
Marmot group chats	Yes	Same gate via commons composable.

Integration Test Scenarios

1. Lock + deep link: Tap DM notification while app cold, lock enabled. Expected: Messages route opens, gate intercepts BEFORE chatroom content visible, unlock → chatroom shows. Failure mode: chatroom flashes content during navigation transition.
2. Lock + spec drift: User toggles lock → toggles inactivity to Never → leaves Messages → returns. Expected: Locked (because leave-route is a separate trigger). Failure: stays Unlocked because timer = Never.
3. Lock + credential revocation: User removes fingerprint in Android settings while app open. Next gate entry expected: prompt appears, fails with NONE_ENROLLED → state → Disabled + banner shows on settings.
4. Lock + multi-window (Android tablet): Lock active, Messages in left pane, Feed in right. Expected: only left pane shows lock.
5. Lock + spam tab: Locked + user navigates Known→New tab inside Messages. Expected: no re-prompt within same Messages route session.
6. Lock + send-receive parity: Lock active, user unlocks, sends a DM, recipient sees it normally. Outbound path unaffected.
7. Notification preview level after lock disable: User enables lock → Generic notifications. Disables lock → notifications revert to Full (no sticky Generic).

Acceptance Criteria

Functional

• Messages route gated by MessagesLockGate on Android + Desktop
• Idle timer (default 5 min) auto-locks while in Messages
• Navigation away from Messages triggers immediate re-lock
• Account switch counts as leave-route (force re-lock — spec-flow #2)
• Inactivity timer ignores incoming DMs (per resolved Q)
• Inactivity timer resets on user input (scroll/tap/keypress) but NOT on media playback (spec-flow #13)
• Marmot group chats inherit the gate (per resolved Q)
• Android: BiometricPrompt(STRONG | DEVICE_CREDENTIAL) succeeds
• macOS: Touch ID via Swift shim succeeds; password fallback works
• Windows: CredUIPromptForCredentials (OS password) succeeds — no Windows Hello in v1
• Linux: lock toggle disabled with "Not available on Linux yet" banner — lock entirely deferred in v1
• Activity-level FLAG_SECURE applied at MainActivity.onCreate when lockEnabled = true (closes cold-resume recents window)
• Per-screen FLAG_SECURE belt-and-suspenders via SecureScreenEffect
• macOS NSWindow sharingType set when lock enabled (with macOS 15+ caveat documented in-app — both ScreenCaptureKit and screencapture(1) ignore it on Sequoia/Tahoe)
• Windows SetWindowDisplayAffinity set when lock enabled
• Desktop blur-on-unfocus active while Messages visible (16dp, overlay layer not LazyColumn)
• macOS 15+ and Linux: blur applied even while focused as partial capture-block compensation
• Notification preview redaction respects level (Generic / Full — 2 levels per simplicity review)
• Notification main builder redacted when level=Generic (not just setPublicVersion) — security H5
• Inline-reply RemoteInput disabled when level=Generic — security H13
• MessagingStyle history flushed on first lock-enable — security H4
• Crash reports strip Throwable.message for DM-origin packages — security H2
• No Log.d calls echo decrypted DM content (verified by logcat | grep audit during testing) — security H3
• Bunker decrypt response queue drained on re-lock — security H6
• First-run inline card appears once; auto-suppresses after Enable or after the card is shown (2 buttons: Enable / Not now — no "Don't ask" persistence per simplicity review)
• First-run card renders on empty Messages tab (spec-flow #1)
• Fallback: credential-unavailable → toggle disabled + banner (no persisted flag — re-checked via BiometricManager.canAuthenticate())
• Settings UI on both platforms (Android Scaffold, Desktop Column + Card per pattern review)
• Global search does not surface DM content while locked (SearchBarViewModel + AdvancedSearchBarState + Desktop search panel — filter aggregation on kinds 4 / 14 / 1059 / 443)
• In-app DM banner suppressed on Messages route while Locked (spec-flow #7)
• Draft persistence — text TextFields keep their value across a lock cycle (gate overlays content, never disposes it — spec-flow #8)
• BiometricPrompt dismissed + state reset on Lifecycle.STOP while prompt is up (spec-flow #4)
• Disable-while-locked: toggle off in settings → state Locked → Disabled within one frame (spec-flow #9)
• Concurrent triggers (leave-route + idle-timer same tick) are idempotent (spec-flow #5)
• Deep-link from notification: chat content NEVER paints before gate — security H1; Compose-test asserts this

Non-Functional

• No measurable startup-time regression (≤ +20ms cold start)
• Gate composition adds ≤1 recomposition per state change
• No new ANRs / dropped frames during lock transitions (verified with macrobenchmark on Android, frame-rate inspection on desktop)
• FLAG_SECURE applied via DisposableEffect, removed on screen exit (no permanent secure-flag leak)
• No credentials cached in memory beyond the unlock callback
• All new code paths spotless-clean and covered where applicable

Quality Gates

• ./gradlew :commons:jvmTest --tests "*privacylock*" green
• ./gradlew :amethyst:assembleDebug green
• ./gradlew :desktopApp:compileKotlin green
• ./gradlew :desktopApp:packageDmg green on macOS host
• ./gradlew :desktopApp:packageMsi green on Windows host
• ./gradlew :desktopApp:packageDeb green on Linux host
• ./gradlew spotlessApply clean
• Manual testing sheet executed and signed off

Success Metrics

• Adoption proxy: prefs node read counts (if telemetry exists; if not, GitHub issue volume tagged privacy-lock)
• Stability proxy: zero "stuck-locked" support reports during the first 30 days post-release
• Discoverability proxy: < 10% of users dismiss the first-run card with "Don't ask" without first trying Enable (intent: card is clear enough that 'Don't ask' is informed, not annoyance-driven)

Dependencies & Prerequisites

• androidx.biometric.ktx 1.2.0-alpha05 (already bundled)
• com.sun.jna:jna (already a transitive dep via existing JNA usage in MacOsVlcDiscoverer.kt)
• Compose Multiplatform 1.11.0 — Modifier.blur supported
• macOS dev host with swiftc (only when changing Touch ID shim source)
• Windows dev host with dotnet SDK (only when changing Hello helper)
• Pre-built .dylib / .exe committed to repo so non-mac/non-win devs can still build

Risk Analysis & Mitigation

Risk	Likelihood	Impact	Mitigation
macOS 15+ NSWindowSharingNone is ignored by ScreenCaptureKit	Verified	Medium	In-app caveat row; document in settings + release notes
Touch ID Swift shim breaks under future macOS update	Low	Medium	Shim is tiny; fix is < 30 LOC. Fallback: password via LAPolicy.deviceOwnerAuthentication works without biometric
Windows Hello helper.exe gets flagged by AV	Medium	Medium	Sign the helper with same code-sign cert as the main MSI; ship as AmethystHello.exe inside the app bundle (not standalone)
Linux distro permutations (Wayland vs X11) — no portable capture block	Verified	Low	Documented limitation; lock + blur + notif redaction still work
Notification deep-link races the gate (chat flash)	Medium	High (privacy leak)	LaunchedEffect initial-composition guard; integration test
BiometricPrompt + Compose lifecycle bug under config-change	Low	Medium	Use existing pattern from UpdateZapAmountDialog.kt:428-479; add lifecycle-aware launch
User disables OS device credentials → permanently locked out	Verified	Low	onCredentialUnavailable → disable + warn banner — no permanent lockout
Spotless config doesn't know about Swift / C# files	Low	Low	Add file globs to .editorconfig only — spotless is Kotlin-scoped
ProGuard strips BiometricPrompt reflection	Medium	Medium	Existing compose-rules.pro already has broad keepnames; add explicit -keep class androidx.biometric.** if needed
Marmot UI extraction blocked / delayed	Low	Low	Gate wraps Marmot Android screen today; Desktop inherits when Marmot extracts. No coupling.

Future Considerations

• Windows Hello in v2. Native helper .exe (C++/WinRT or C#) ~60 LOC over stdio, parented to the JVM HWND via IUserConsentVerifierInterop. Requires the helper to be signed with the same cert as the main MSI to avoid AV flags. Add once the v1 flow has user feedback. (See deepen-plan external research output.)
• Linux lock in v2. Bitwarden's polkit pattern is the proven path but requires a root-installed policy file at /usr/share/polkit-1/actions/com.amethyst.privacy-lock.policy, which breaks Flatpak distribution. Alternative: in-app password prompt stored in libsecret. Decide at v2.
• Phase 2 — nsec encryption-at-rest with PIN-derived key. Separate brainstorm. Closes the cosmetic-vs-cryptographic gap. Would re-encrypt accounts.json.enc with PRF(nsec, PIN-derived key) on lock; decrypt only at unlock. Compatible with NIP-46 bunker (signer never holds nsec). Compatible with NIP-55 (external signer).
• Per-conversation lock (WhatsApp Chat Lock parity). Add Chatroom.locked: Boolean flag and a second gate over individual ChatroomScreen entries.
• Wallet (NWC) gate — reuse the same MessagesLockGate plumbing to gate the Wallet deck column. Already on the feature backlog.
• amy CLI integration — amy messages status could refuse to print DMs while lockEnabled = true to enforce parity even from the headless side. Useful when running amy on a shared machine.
• Hide app from app-switcher entirely (Android) — instead of FLAG_SECURE blanking, fully omit the app from the recents list while Messages is foregrounded. More aggressive UX; opt-in.

Documentation Plan

• commons/ARCHITECTURE.md — add privacylock/ package entry
• desktopApp/CLAUDE.md (if exists) — mention Touch ID shim build step
• New desktopApp/plans/2026-06-30-privacy-lock-native-shims-recipe.md capturing the macOS .dylib / Windows .exe build & signing procedure (so future contributors don't rediscover it)
• Release notes section "Privacy & Security" highlighting the new toggle + caveats (macOS 15+, Linux capture)
• docs/manual-testing-privacy-lock.md — the testing sheet (delivered as part of the final step)

Sources & References

Origin

• Brainstorm document: docs/brainstorms/2026-06-30-feat-messaging-privacy-lock-brainstorm.md — Key decisions carried forward: (a) Messages-only route gate (not app-wide), (b) OS device credentials only (no Amethyst PIN), (c) device-global setting, (d) off by default + inline first-run card, (e) inactivity-timer + leave-route as the two re-lock triggers, (f) auto-bump notification preview to Generic on first enable.

Internal References

• Existing biometric pattern: amethyst/src/main/java/com/vitorpamplona/amethyst/ui/note/UpdateZapAmountDialog.kt:428-479
• DM notification path: amethyst/src/main/java/com/vitorpamplona/amethyst/service/notifications/NotificationUtils.kt:370-510
• Existing JNA usage: desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/service/media/MacOsVlcDiscoverer.kt
• macOS window-chrome extension pattern: desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/platform/PlatformTheme.kt:87
• Desktop window creation: desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/Main.kt:316
• Settings storage on desktop (java.util.prefs precedent): commons/src/jvmMain/kotlin/com/vitorpamplona/amethyst/commons/keystorage/SecureKeyStorage.kt
• DM messaging UI (commons + Android + Desktop) — surveyed in brainstorm research.

External References

• macOS Touch ID via Swift shim: classycodeoss/java-touchid
• Rococoa (Java↔Cocoa bridge, used by Cyberduck): iterate-ch/rococoa
• Apple LAContext.evaluatePolicy: developer.apple.com
• Microsoft UserConsentVerifier: learn.microsoft.com
• IUserConsentVerifierInterop (HWND attach): Microsoft sdk-api
• Bitwarden Linux polkit pattern (rejected for v1): bitwarden/clients PR #4586
• macOS 15+ sharingType regression: Tauri #14200
• Windows SetWindowDisplayAffinity: learn.microsoft.com
• NIST 800-63B session timeouts: pages.nist.gov
• WhatsApp Chat Lock: about.fb.com
• Signal Screen Lock: support.signal.org

Related Work

• Embedded local relay plan (precedent for commons/jvmMain state holder + StateFlow + LocalXyzStore pattern): desktopApp/plans/2026-05-09-embedded-local-relay-plan.md
• Account security hardening (concurrent, deals with nsec storage and forced logout): docs/plans/2026-05-14-fix-account-security-hardening-plan.md
• Hashtag spam filter (precedent for global preferences node): docs/plans/2026-06-29-feat-desktop-hashtag-spam-filter-plan.md

Open Questions (post-brainstorm + post-deepen)

All brainstorm open questions are resolved. Original planning questions reordered + deepen-review additions integrated:

1. macOS code-signing for Touch ID shim. Current desktop build's nativeDistributions { macOS { ... } } block has only bundleID and iconFile. No signing block, no notarization. Touch ID works on unsigned dev builds (research confirms), but for the release DMG we need a Developer ID + notarization. Verify whether the existing DMG release is signed elsewhere; if not, that's a separate workstream (out of this plan's scope but a release-day blocker).
2. ProGuard rules. Compose Desktop release uses ProGuard. Verify compose-rules.pro keeps the new JNA classes, biometric reflection surfaces, and Compose composables. Add -keep class androidx.biometric.** { *; } if not already covered.
3. Search audit — concrete files (refined from spec-flow review): SearchBarViewModel.kt (Android), AdvancedSearchBarState.kt (commons), AdvancedSearchPanel.kt (desktop). Filter aggregation on kinds 4 / 14 / 1059 / 443 when MessagesLockState.state == Locked. Phase 5 deliverable, gated by an acceptance criterion below.
4. commons/jvmAndroid source set name — verify the exact name commons/ARCHITECTURE.md uses (could be jvmAndroidMain or desktopAndroidMain). Source set must exist already (used by shared StateFlow / persistence patterns); confirm during Phase 1.
5. CredentialPrompter interface vs expect class — per pattern review the codebase has no precedent for @Composable expect fun, so the plan uses a plain interface + CompositionLocal. If a wider refactor ever wants expect class CredentialPrompter (matching SecureKeyStorage), follow that idiom — out of scope now.
6. firstRunCardSeen scope — device-global (single flag, not per-npub) per spec-flow gap #2. Acceptable for v1.
7. MessagesLockState.LocalMessagesLockState instantiation site on Android — needs a single owner equivalent to the Desktop Main.kt instantiation. Likely AmethystApp / Application class. Confirm during Phase 2 wiring.
8. Telemetry? Amethyst has no telemetry today. Success metrics above are inferred from issue volume — keep as-is, no telemetry shipped.