Yield during main actor stress testing

* fix: use country-level resolution for low-precision geohashes (#887)

* fix: skip admin fallback when country exists but is duplicate

Prevents mixed labels like "United Kingdom and Scotland" for
single-country geohashes. Admin fallback now only triggers when
no country is available from the placemark.

* fix: migrate stale low-precision bookmark names so country-first logic applies

Users who bookmarked a <=2-char geohash before the country-first resolver
kept the old administrativeArea cache (e.g. "England" for `gc`) because
resolveBookmarkNameIfNeeded bails when bookmarkNames[gh] is non-nil. Add a
one-shot, versioned migration that drops cached names for <=2-char geohashes
on load; the next LocationChannelsSheet .onAppear re-resolves them via the
fixed logic. Higher-precision entries are untouched.

* Fix low-precision geohash country names

---------

Co-authored-by: jack <212554440+jackjackbits@users.noreply.github.com>
Co-authored-by: jack <jackjackbits@users.noreply.github.com>

.github/workflows/arti-provenance.yml

@@ -0,0 +1,85 @@
+name: Arti Binary Provenance
+
+# The Arti xcframework is a vendored binary; these checks turn the policy in
+# docs/ARTI-BINARY-PROVENANCE.md into an enforced gate:
+#  1. The checked-in binary must match the hash manifest in the provenance doc.
+#  2. A PR that changes the binary must also change at least one provenance
+#     input (Rust source, lockfile, build script, or the doc itself).
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "localPackages/Arti/**"
+      - "docs/ARTI-BINARY-PROVENANCE.md"
+  pull_request:
+    paths:
+      - "localPackages/Arti/**"
+      - "docs/ARTI-BINARY-PROVENANCE.md"
+
+jobs:
+  verify-hashes:
+    name: Verify xcframework hashes against provenance doc
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Compare artifact hashes with manifest
+        run: |
+          set -euo pipefail
+          doc="docs/ARTI-BINARY-PROVENANCE.md"
+
+          # Extract the manifest: lines of "<sha256>  <path>" from the doc.
+          grep -E '^[0-9a-f]{64}  localPackages/Arti/Frameworks/arti\.xcframework/' "$doc" \
+            | sort -k2 > expected.txt
+
+          if [ ! -s expected.txt ]; then
+            echo "::error::No hash manifest found in $doc"
+            exit 1
+          fi
+
+          # Hash the same file set the doc documents.
+          find localPackages/Arti/Frameworks/arti.xcframework -maxdepth 3 -type f -print0 \
+            | sort -z | xargs -0 sha256sum | sed 's/  \.\//  /' | sort -k2 > actual.txt
+
+          if ! diff -u expected.txt actual.txt; then
+            echo "::error::Checked-in arti.xcframework does not match the manifest in $doc. If the binary change is intentional, rebuild per the doc and update the manifest in the same PR."
+            exit 1
+          fi
+          echo "All $(wc -l < actual.txt) artifact hashes match the provenance manifest."
+
+  require-provenance-evidence:
+    name: Binary changes must ship with provenance inputs
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Check changed files
+        run: |
+          set -euo pipefail
+          base="origin/${{ github.base_ref }}"
+          git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
+          changed=$(git diff --name-only "$base"...HEAD)
+          echo "Changed files:"
+          echo "$changed"
+
+          if ! echo "$changed" | grep -q '^localPackages/Arti/Frameworks/arti\.xcframework/'; then
+            echo "No binary artifact changes; nothing to verify."
+            exit 0
+          fi
+
+          if echo "$changed" | grep -Eq '^(localPackages/Arti/(Cargo\.(toml|lock)|build-ios\.sh|arti-bitchat/)|docs/ARTI-BINARY-PROVENANCE\.md)'; then
+            echo "Binary change is accompanied by provenance inputs."
+            exit 0
+          fi
+
+          echo "::error::arti.xcframework changed without matching source, lockfile, build-script, or provenance-doc changes. See docs/ARTI-BINARY-PROVENANCE.md (\"Do not accept an xcframework-only update\")."
+          exit 1

.github/workflows/periphery.yml

@@ -0,0 +1,30 @@
+name: Dead Code
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  periphery:
+    name: Periphery scan
+    runs-on: macos-latest
+    timeout-minutes: 30
+    # Advisory, like SwiftLint (#1361): findings annotate the PR but don't
+    # block merges. Drop continue-on-error once the baseline proves stable.
+    continue-on-error: true
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Install Periphery
+        # homebrew-core formula; the peripheryapp tap lags years behind.
+        run: brew install periphery
+
+      - name: Scan for dead code
+        # Config comes from .periphery.yml; known findings (mostly iOS-only
+        # code invisible to a macOS scan) are suppressed by the committed
+        # baseline. --strict fails the step when NEW dead code appears.
+        run: periphery scan --strict --disable-update-check

.github/workflows/swift-tests.yml

@@ -10,6 +10,12 @@ jobs:
   test:
     name: Run Swift Tests (${{ matrix.name }})
     runs-on: macos-latest
+    # A hung test must fail fast, not hold a runner for GitHub's 360-minute
+    # default (observed: intermittent app-suite hangs starving the queue).
+    # The long steps carry tighter individual bounds (5-minute test watchdog,
+    # 6-minute benchmark step, 10-minute floor gate that may re-run the
+    # benchmarks up to twice on a noisy runner); this is the backstop.
+    timeout-minutes: 25
 
     strategy:
       fail-fast: false # Don't cancel other matrix jobs when one fails
@@ -26,17 +32,163 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v5
 
-      - name: Set up Swift
+      # Use the Xcode-bundled Swift toolchain: it always matches the SDK on
-        uses: swift-actions/setup-swift@v2
+      # the runner image. A standalone swift.org toolchain (setup-swift) broke
+      # whenever the image's Xcode moved ahead of it ("this SDK is not
+      # supported by the compiler").
+      - name: Note toolchain version (cache key)
+        id: swift-version
+        run: echo "version=$(swift --version 2>/dev/null | head -1 | shasum | cut -c1-12)" >> "$GITHUB_OUTPUT"
 
       - name: Cache build artifacts
         uses: actions/cache@v4
         with:
           path: ${{ matrix.path }}/.build
-          key: ${{ runner.os }}-${{ matrix.name }}-${{ hashFiles(format('{0}/**/*.swift', matrix.path), format('{0}/**/Package.resolved', matrix.path)) }}
+          key: ${{ runner.os }}-${{ steps.swift-version.outputs.version }}-${{ matrix.name }}-${{ hashFiles(format('{0}/**/*.swift', matrix.path), format('{0}/**/Package.resolved', matrix.path)) }}
           restore-keys: |
-            ${{ runner.os }}-${{ matrix.name }}-${{ hashFiles(format('{0}/**/Package.resolved', matrix.path)) }}
+            ${{ runner.os }}-${{ steps.swift-version.outputs.version }}-${{ matrix.name }}-${{ hashFiles(format('{0}/**/Package.resolved', matrix.path)) }}
-            ${{ runner.os }}-${{ matrix.name }}-
+            ${{ runner.os }}-${{ steps.swift-version.outputs.version }}-${{ matrix.name }}-
+
+      - name: Build tests
+        # Built separately so the hang watchdog below times only test
+        # execution: a cold-cache coverage build on a slow runner can
+        # legitimately take several minutes, and is already bounded by the
+        # 15-minute job timeout.
+        run: swift build --build-tests --enable-code-coverage --package-path ${{ matrix.path }}
 
       - name: Run Tests
-        run: swift test --parallel --quiet --package-path ${{ matrix.path }}
+        # Perf benchmarks are excluded here and run in their own serial step
+        # below: measuring while parallel test processes contend for cores
+        # produces noisy numbers, and the XCTest measure machinery has hung
+        # intermittently under parallel workers on loaded runners. Excluded
+        # via --skip (not just the env guard): every app run since the
+        # baselines landed timed out at the 15-minute job limit with the
+        # baseline tests dispatched into the parallel phase.
+        #
+        # The watchdog samples any still-running test processes after 5
+        # minutes (the suite passes in seconds when healthy; the build is
+        # done by this step) and kills the run, so a hang fails fast with
+        # stacks in the log instead of a silent timeout.
+        env:
+          BITCHAT_SKIP_PERF_BASELINES: "1"
+        run: |
+          swift test --skip-build --parallel --quiet --enable-code-coverage \
+            --skip PerformanceBaselineTests \
+            --package-path ${{ matrix.path }} &
+          test_pid=$!
+          (
+            sleep 300
+            if kill -0 "$test_pid" 2>/dev/null; then
+              echo "::group::Tests still running after 5 minutes — sampling before kill"
+              for pid in $(pgrep -if 'swiftpm-testing|xctest|PackageTests' || true); do
+                echo "--- sample of pid $pid ---"
+                sample "$pid" 5 2>/dev/null || true
+              done
+              echo "::endgroup::"
+              pkill -KILL -P "$test_pid" 2>/dev/null || true
+              kill -KILL "$test_pid" 2>/dev/null || true
+            fi
+          ) &
+          watchdog_pid=$!
+          wait "$test_pid" && status=0 || status=$?
+          kill "$watchdog_pid" 2>/dev/null || true
+          exit "$status"
+
+      # Benchmarks run serially on an otherwise idle runner for stable
+      # numbers; BITCHAT_PERF_LOG captures the PERF[...] lines for the gate.
+      - name: Run performance benchmarks (serial)
+        if: matrix.name == 'app'
+        timeout-minutes: 6
+        env:
+          BITCHAT_PERF_LOG: ${{ github.workspace }}/perf-output.log
+        run: swift test --quiet --filter PerformanceBaselineTests
+
+      # Order-of-magnitude performance regression gate. Floors are deliberately
+      # generous (see bitchatTests/Performance/perf-floors.json) so this
+      # catches algorithmic regressions, never runner variance. If a metric
+      # still lands below floor (a saturated runner can dip one), the script
+      # re-runs the benchmarks — appending to the same log and keeping each
+      # benchmark's best value per metric — so noise clears on retry while a
+      # real regression fails every attempt. Floors are never lowered by this.
+      - name: Performance floor gate
+        if: matrix.name == 'app'
+        timeout-minutes: 10
+        run: ./scripts/check-perf-floors.sh perf-output.log
+
+      # Informational only: surfaces per-file and total line coverage in the
+      # job log so coverage trends are visible on every PR. No thresholds —
+      # this must never be the reason a build goes red.
+      - name: Coverage summary
+        run: |
+          BIN_PATH=$(swift build --show-bin-path --package-path ${{ matrix.path }})
+          PROF="$BIN_PATH/codecov/default.profdata"
+          XCTEST=$(find "$BIN_PATH" -maxdepth 1 -name '*.xctest' | head -1)
+          BINARY="$XCTEST/Contents/MacOS/$(basename "$XCTEST" .xctest)"
+          if [ -f "$PROF" ] && [ -f "$BINARY" ]; then
+            xcrun llvm-cov report "$BINARY" -instr-profile "$PROF" \
+              -ignore-filename-regex='(Tests|\.build|checkouts|Mocks|_PreviewHelpers)' || true
+          else
+            echo "No coverage data found; skipping summary."
+          fi
+
+  # SPM tests do not link the shipping app targets. This job covers the
+  # iOS-conditional paths and both universal Release link configurations.
+  ios-build:
+    name: Build Release apps (universal)
+    runs-on: macos-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Build iOS (simulator, no signing)
+        # Build both simulator architectures so CI validates every vendored
+        # Arti simulator slice and the configuration that ships.
+        run: |
+          set -o pipefail
+          xcodebuild -project bitchat.xcodeproj \
+            -scheme "bitchat (iOS)" \
+            -configuration Release \
+            -sdk iphonesimulator \
+            -destination 'generic/platform=iOS Simulator' \
+            ARCHS='arm64 x86_64' \
+            ONLY_ACTIVE_ARCH=NO \
+            CODE_SIGNING_ALLOWED=NO \
+            build
+
+      - name: Build macOS (universal, no signing)
+        run: |
+          set -o pipefail
+          xcodebuild -project bitchat.xcodeproj \
+            -scheme "bitchat (macOS)" \
+            -configuration Release \
+            -destination 'generic/platform=macOS' \
+            ARCHS='arm64 x86_64' \
+            ONLY_ACTIVE_ARCH=NO \
+            CODE_SIGNING_ALLOWED=NO \
+            build
+
+  # Advisory only: SwiftLint reports style violations without ever failing the
+  # build. Runs in a pinned container (no Xcode plugin, no pbxproj changes) so
+  # it can never break the documented xcodebuild path or block a merge.
+  lint:
+    name: SwiftLint (advisory)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # This job runs a third-party container image, so give it the least
+    # privilege we can: a read-only token, and no credentials left in the
+    # checkout for the container to find.
+    permissions:
+      contents: read
+    container:
+      # Tag for readability, digest for immutability (tags can be repointed).
+      # Bump both together, deliberately — never a floating tag.
+      image: ghcr.io/realm/swiftlint:0.65.0@sha256:a482729f4b58741875af1566f23397f3f6db300372756fc31606d0a4527fab9e
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - name: Run SwiftLint
+        run: swiftlint lint --reporter github-actions-logging

.periphery.baseline.json

@@ -0,0 +1 @@
+{"v1":{"usrs":["param-buf-arti_bootstrap_summary(_:_:)-s:3Tor22arti_bootstrap_summary33_954FD7701B4E47ABB5F166D1CF862DC9LLys5Int32VSpys4Int8VG_AEtF","param-dataDir-arti_start(_:_:)-s:3Tor10arti_start33_954FD7701B4E47ABB5F166D1CF862DC9LLys5Int32VSPys4Int8VG_s6UInt16VtF","param-len-arti_bootstrap_summary(_:_:)-s:3Tor22arti_bootstrap_summary33_954FD7701B4E47ABB5F166D1CF862DC9LLys5Int32VSpys4Int8VG_AEtF","param-socksPort-arti_start(_:_:)-s:3Tor10arti_start33_954FD7701B4E47ABB5F166D1CF862DC9LLys5Int32VSPys4Int8VG_s6UInt16VtF","s:13BitFoundation16PeerCapabilitiesV8wifiBulkACvpZ","s:13BitFoundation18KeychainReadResultO18isRecoverableErrorSbvp","s:13BitFoundation23KeychainManagerProtocolP11secureClearyySSzF","s:18bitchatTests_macOS12MockKeychainC11secureClearyySSzF","s:18bitchatTests_macOS20TrackingMockKeychainC11resetCountsyyF","s:18bitchatTests_macOS20TrackingMockKeychainC11secureClearyySSzF","s:18bitchatTests_macOS20TrackingMockKeychainC25totalSecureClearCallCountSivp","s:18bitchatTests_macOS20TrackingMockKeychainC26secureClearStringCallCountSivp","s:18bitchatTests_macOS20TrackingMockKeychainC27_secureClearStringCallCount06_AB6D1M24FD239F2969C82F4108818260LLSivp","s:18bitchatTests_macOS24FailingCacheSaveKeychain33_22380C7A11A569A0B83FA83F34C498A7LLC11secureClearyySSzF","s:18bitchatTests_macOS24MockGeohashPresenceTimer33_483587EFB96650EE130EFB09BBA2A1AALLC7handleryycvp","s:3Tor0A7ManagerC21goDormantOnBackgroundyyF","s:7bitchat10AppRuntimeC24handleScreenshotCaptured33_C8B369AD8BC1D9963A50CEDA77A4332ALLyyF","s:7bitchat10AppRuntimeC33handleDidBecomeActiveNotificationyyF","s:7bitchat10BLEServiceC18logBluetoothStatus33_69191C53E68500C17D98DBCF2BDA7100LLyySSF","s:7bitchat10BLEServiceC20centralRestorationID33_69191C53E68500C17D98DBCF2BDA7100LLSSvpZ","s:7bitchat10BLEServiceC22captureBluetoothStatus33_69191C53E68500C17D98DBCF2BDA7100LL7contextySS_tF","s:7bitchat10BLEServiceC23peripheralRestorationID33_69191C53E68500C17D98DBCF2BDA7100LLSSvpZ","s:7bitchat10BLEServiceC29scheduleBluetoothStatusSample33_69191C53E68500C17D98DBCF2BDA7100LL5after7contextySd_SStF","s:7bitchat10QRScanViewV8isActiveSbvp","s:7bitchat15BLEPeerRegistryV5countSivp","s:7bitchat15KeychainManagerC11secureClearyySSzF","s:7bitchat15PaymentChipViewV7openURL33_10AC50641B1EBCD52E5092A2E521D236LL7SwiftUI13OpenURLActionVvp","s:7bitchat15TransportConfigO29uiBatchDispatchStaggerSecondsSdvpZ","s:7bitchat15TransportConfigO35uiShareExtensionDismissDelaySecondsSdvpZ","s:7bitchat15TransportConfigO38bleBackgroundPendingConnectSlotReserveSivpZ","s:7bitchat17GossipSyncManagerC10persistNowyyF","s:7bitchat17NostrRelayManagerC15InboundEventKey33_E4160FE8A9A2C9D6308EAAD5A8B5CB07LLV7eventIDSSvp","s:7bitchat25LocationNotesDependenciesV3now10Foundation4DateVycvp","s:7bitchat25NWPathReachabilityMonitorC7monitor33_84633C9DBCAF57538179C1E04DB8E015LL7Network0bD0CSgvp"]}}

.periphery.yml

@@ -0,0 +1,21 @@
+# Periphery dead-code scan configuration (https://github.com/peripheryapp/periphery)
+#
+# CI runs the macOS scheme only (an iOS scan needs a device destination and
+# doubles the build time). macOS-only scans falsely flag iOS-only code —
+# state restoration, screenshot handlers, background BLE sampling — so those
+# findings live in .periphery.baseline.json rather than being "fixed".
+# When auditing by hand, scan BOTH schemes and intersect:
+#   periphery scan --schemes "bitchat (iOS)" -- -destination 'generic/platform=iOS' ARCHS=arm64
+project: bitchat.xcodeproj
+schemes:
+  - bitchat (macOS)
+retain_swift_ui_previews: true
+# Codable properties are (de)serialized via synthesized conformances the
+# indexer doesn't always attribute reads to: PrekeyBundleStore.StoredBundle
+# .noiseKey flaked CI as "assign-only" even while read in loadFromDisk —
+# and slipped past its baselined USR. Retaining Codable properties outright
+# is deterministic; a truly-dead Codable field is a persisted-format change
+# anyway, never a safe mechanical delete.
+retain_codable_properties: true
+relative_results: true
+baseline: .periphery.baseline.json

.swiftlint.yml

@@ -0,0 +1,34 @@
+# Build artifacts and generated sources; keeps local `swiftlint` runs clean
+# (CI checkouts are fresh, so this only matters in a working tree).
+excluded:
+  - .build
+  - .claude
+  - .swiftpm
+  - .DerivedData
+  - DerivedData
+  - build
+  - localPackages/*/.build
+
+disabled_rules:
+  - line_length
+  - type_name
+  - identifier_name
+  - statement_position
+  - implicit_optional_initialization
+  - force_try
+  - vertical_whitespace
+  - for_where
+  - control_statement
+  - void_function_in_ternary
+  - redundant_discardable_let  # SwiftUI breaks without it
+  # To be enabled as we fix the issues
+  - trailing_whitespace
+  - cyclomatic_complexity
+  - function_body_length
+  - function_parameter_count
+  - type_body_length
+  - file_length
+  - large_tuple
+  - force_cast
+  - multiple_closures_with_trailing_closure
+  - nesting

Configs/Release.xcconfig

@@ -1,4 +1,4 @@
-MARKETING_VERSION = 1.5.1
+MARKETING_VERSION = 1.7.1
 CURRENT_PROJECT_VERSION = 1
 
 IPHONEOS_DEPLOYMENT_TARGET = 16.0

PRIVACY_POLICY.md

@@ -1,139 +1,155 @@
 # bitchat Privacy Policy
 
-*Last updated: January 2025*
+*Last updated: July 2026*
 
 ## Our Commitment
 
-bitchat is designed with privacy as its foundation. We believe private communication is a fundamental human right. This policy explains how bitchat protects your privacy.
+bitchat is designed for private, account-free communication. This policy describes what the app keeps on your device, what it sends when you use mesh or optional internet features, and how long local data can remain.
 
 ## Summary
 
-- **No personal data collection** - We don't collect names, emails, or phone numbers
+- **No project-operated accounts or messaging servers** — Bluetooth mesh is peer-to-peer; optional internet features use public or user-selected Nostr relays.
-- **No servers** - Everything happens on your device and through peer-to-peer connections
+- **No analytics, advertising, telemetry, or tracking** — the app does not contain an analytics or advertising SDK.
-- **No tracking** - We have no analytics, telemetry, or user tracking
+- **No sale of data** — the project does not sell user data or build advertising profiles.
-- **Open source** - You can verify these claims by reading our code
+- **Open source** — the storage, networking, and cryptography described here can be inspected in the source code.
 
-## What Information bitchat Stores
+## What bitchat Stores on Your Device
 
-### On Your Device Only
+1. **Identity and cryptographic keys**
+   - Noise, signing, group, prekey, and optional Nostr identity material is generated locally.
+   - Secret keys are stored in the system keychain. Public keys are shared when required for messaging, verification, groups, or Nostr events.
+   - Keys remain until they are rotated, removed by the relevant feature, erased with panic wipe, or removed with the app.
 
-1. **Identity Key** 
+2. **Nickname, preferences, and relationships**
-   - A cryptographic key generated on first launch
+   - Your nickname, settings, favorites, petnames, read-receipt identifiers, and bounded operational metadata are stored locally.
-   - Stored locally in your device's secure storage
+   - The share extension briefly places content you choose to share in the app-group preferences so the main app can import it.
-   - Allows you to maintain "favorite" relationships across app restarts
-   - Never leaves your device
 
-2. **Nickname**
+3. **Private group state**
-   - The display name you choose (or auto-generated)
+   - Group names, rosters, creator identity, and key epoch are stored as protected files in Application Support.
-   - Stored only on your device
+   - Current group keys are stored in the keychain. Group state remains until you leave or remove the group, panic-wipe the app, or remove the app.
-   - Shared with peers you communicate with
 
-3. **Message History** (if enabled)
+4. **Queued and carried private messages**
-   - When room owners enable retention, messages are saved locally
+   - An outgoing private message that has not been acknowledged may remain for up to 24 hours in a bounded, encrypted outbox. The outbox is sealed with ChaCha20-Poly1305 and its key is stored in the keychain.
-   - Stored encrypted on your device
+   - A device acting as a courier may store a bounded opaque end-to-end encrypted envelope for another user for up to 24 hours. The courier cannot read its message content.
-   - You can delete this at any time
+   - A panic wipe deletes both stores.
 
-4. **Favorite Peers**
+5. **Recent public mesh messages and notices**
-   - Public keys of peers you mark as favorites
+   - Signed public mesh messages may be kept in a protected local gossip archive for up to 15 minutes so they can cross mesh partitions and survive a short relaunch.
-   - Stored only on your device
+   - Public bulletin-board posts and deletion tombstones persist until the post's author-selected expiry, at most seven days. Both stores are bounded and panic-wipeable.
-   - Allows you to recognize these peers in future sessions
+   - These items are public to the mesh or board where they are posted; they are not confidential messages.
 
-### Temporary Session Data
+6. **Media attachments**
+   - Voice notes and images you send or receive can be stored under Application Support so they remain playable while referenced by the app.
+   - Incoming media is subject to a 100 MB quota with oldest-file eviction. Media is deleted by panic wipe or app removal; some outgoing media can otherwise remain on disk.
 
-During each session, bitchat temporarily maintains:
+7. **Optional location-channel state**
-- Active peer connections (forgotten when app closes)
+   - Your selected geohash channel, bookmarks, teleport flags, and bookmark display names are stored locally so the UI can restore them.
-- Routing information for message delivery
+   - Per-geohash Nostr identities are derived locally from a device seed stored in the keychain.
-- Cached messages for offline peers (12 hours max)
+   - bitchat does not persist exact latitude or longitude and does not include exact coordinates in mesh or Nostr messages.
 
-## What Information is Shared
+## Temporary Session Data
 
-### With Other bitchat Users
+While running, bitchat maintains active connections, routing state, deduplication state, and bounded in-memory conversation timelines. Closing the app clears the in-memory timelines and active connections, but it does not erase the persistent stores listed above.
 
-When you use bitchat, nearby peers can see:
+## What Is Shared
-- Your chosen nickname
-- Your ephemeral public key (changes each session)
-- Messages you send to public rooms or directly to them
-- Your approximate Bluetooth signal strength (for connection quality)
 
-### With Room Members
+### With Nearby Mesh Users
 
-When you join a password-protected room:
+Depending on the feature you use, nearby peers can receive:
-- Your messages are visible to others with the password
-- Your nickname appears in the member list
-- Room owners can see you've joined
 
-## What We DON'T Do
+- Your chosen nickname and public Noise/signing identity material.
+- Announce metadata such as supported capability flags and a bounded list of short direct-neighbor identifiers. When the bridge is enabled, an announce can also include its coarse rendezvous geohash cell.
+- Public mesh messages, public notices, and group-control packets you intentionally send.
+- Private ciphertext addressed to them, or opaque courier ciphertext they agree to carry.
+- Radio metadata available to the receiver, such as approximate Bluetooth signal strength.
 
-bitchat **never**:
+Noise identity keys can persist across sessions; do not treat them as anonymous identifiers. Panic wipe rotates local identity state.
-- Collects personal information
-- Tracks your location
-- Stores data on servers
-- Shares data with third parties
-- Uses analytics or telemetry
-- Creates user profiles
-- Requires registration
 
-## Encryption
+### With Private Group Members
 
-All private messages use end-to-end encryption:
+Private group members receive the group's name, roster, key epoch, and encrypted group traffic needed to participate. Group messages are confidential to devices holding the current group key, subject to the security of those devices and members.
-- **X25519** for key exchange
-- **AES-256-GCM** for message encryption
-- **Ed25519** for digital signatures
-- **Argon2id** for password-protected rooms
 
-## Your Rights
+### With Nostr Relays and Internet Gateways
 
-You have complete control:
+Internet-backed features are optional. When enabled or used:
-- **Delete Everything**: Triple-tap the logo to instantly wipe all data
-- **Leave Anytime**: Close the app and your presence disappears
-- **No Account**: Nothing to delete from servers because there are none
-- **Portability**: Your data never leaves your device unless you export it
 
-## Bluetooth & Permissions
+- Private fallback messages use encrypted NIP-17 gift wraps. Relays can observe event and network metadata but not the message plaintext.
+- Public location-channel messages, notes, notices, and presence include a geohash tag, event kind, timestamp, and a public key. A geohash reveals an approximate area; finer precision reveals a smaller area.
+- The optional mesh bridge publishes bridge-enabled public mesh messages and presence to a neighborhood rendezvous cell. Those messages are public to participants and relays for that cell. A per-message “nearby only” choice prevents that message from crossing the bridge.
+- Bridge courier drops contain opaque end-to-end encrypted envelopes and a rotating recipient tag. Relays still observe timing and network metadata.
+- A device with gateway features enabled may relay signed bridge/location traffic or opaque courier envelopes for nearby mesh devices.
 
-bitchat requires Bluetooth permission to function:
+Nostr relays are operated by third parties. Their retention, logging, availability, and privacy practices are outside the project's control. Public events and encrypted events may remain on relays according to each relay's policy.
-- Used only for peer-to-peer communication
+
-- No location data is accessed or stored
+## Location and Apple Services
-- Bluetooth is not used for tracking
+
-- You can revoke this permission at any time in system settings
+Location permission is optional and requested as when-in-use access. It is used to compute geohash channels, bridge rendezvous cells, and nearby place labels.
+
+- Exact coordinates are not included in bitchat mesh or Nostr payloads and are not persisted by bitchat.
+- A selected geohash can still reveal an approximate area to peers and relays.
+- When bitchat asks the operating system for a friendly place name, Apple's `CLGeocoder` service may process the location under Apple's privacy terms.
+- Revoking location permission stops live location sampling. Saved bookmarks remain until you remove them, panic-wipe the app, or remove the app.
+
+## Microphone, Camera, and Media Permissions
+
+- Microphone access is used only while you record a voice note or actively hold live push-to-talk. The resulting audio is sent to the mesh conversation you selected; public-conversation audio is public to that mesh, while private-conversation audio uses the private transport protections described below.
+- Voice-note and live-audio files can remain in Application Support under the media retention rules above.
+- Camera access is used to scan peer-verification QR codes. Photo-library access is used when you choose an image to send.
+- These permissions can be revoked in system settings. bitchat does not record microphone or camera input while the related capture UI is inactive.
+
+## Cryptography
+
+Private and public features use different protections:
+
+- Mesh private sessions use Noise XX with X25519, ChaCha20-Poly1305, and SHA-256.
+- Private group messages use ChaCha20-Poly1305; group state and relevant mesh packets use Ed25519 signatures.
+- Nostr events use secp256k1 Schnorr signatures. NIP-44 v2 private payloads use secp256k1 key agreement, HKDF-SHA256, and XChaCha20-Poly1305.
+- The persistent private-message outbox uses ChaCha20-Poly1305 with a key held in the keychain. Some other protected local identity state uses AES-GCM.
+- Public mesh, bridge, geohash, and board content is signed or authenticated as appropriate but is intentionally not confidential.
+
+No cryptographic system can protect content after a recipient reads, copies, screenshots, or exports it.
+
+## Data Retention Summary
+
+- **In-memory chat timelines and active connections:** until the app closes or state is cleared.
+- **Queued outgoing private messages:** until acknowledged, dropped by bounded policy, or 24 hours, whichever comes first.
+- **Opaque courier envelopes:** until handed off, evicted by bounded policy, or 24 hours, whichever comes first.
+- **Recent public mesh gossip:** up to 15 minutes.
+- **Public board posts and tombstones:** until expiry, at most seven days.
+- **Groups, favorites, preferences, identity keys, bookmarks, and media:** until removed by the feature, panic wipe, quota eviction where applicable, or app removal.
+- **Nostr data:** according to the policies of the relays that receive it.
+
+## Your Controls
+
+- **Panic wipe:** Triple-tap the logo to clear local keys, sessions, preferences, groups, queues, carried mail, public archives, board data, and media managed by the app.
+- **Feature controls:** Location channels, mesh bridge, internet gateway, and related internet behaviors can be disabled in the app. Some already-published relay data cannot be recalled.
+- **System permissions:** Bluetooth, location, microphone, camera, and photo-library access can be revoked in system settings.
+- **No account:** The project operates no account record for you to request or export.
+
+## What the Project Does Not Do
+
+bitchat does not:
+
+- Operate an account database or project-owned messaging backend.
+- Include advertising, analytics, or tracking SDKs.
+- Sell user data or create advertising profiles.
+- Include exact GPS coordinates in bitchat mesh or Nostr message payloads.
 
 ## Children's Privacy
 
-bitchat does not knowingly collect information from children. The app has no age verification because it collects no personal information from anyone.
+The project does not knowingly operate a service that collects children's personal data. The app has no account registration or age-verification system. Users and guardians should understand that public mesh, board, bridge, and location-channel posts are visible to other participants and may be relayed.
-
-## Data Retention
-
-- **Messages**: Deleted from memory when app closes (unless room retention is enabled)
-- **Identity Key**: Persists until you delete the app
-- **Favorites**: Persist until you remove them or delete the app
-- **Everything Else**: Exists only during active sessions
-
-## Security Measures
-
-- All communication is encrypted
-- No data transmitted to servers (there are none)
-- Open source code for public audit
-- Regular security updates
-- Cryptographic signatures prevent tampering
 
 ## Changes to This Policy
 
-If we update this policy:
+Material behavior changes will be reflected in this document and its “Last updated” date. Updating this policy cannot retroactively retrieve data that remained only on a user's device.
-- The "Last updated" date will change
-- The updated policy will be included in the app
-- No retroactive changes can affect data (since we don't collect any)
 
 ## Contact
 
 bitchat is an open source project. For privacy questions:
-- View our source code: [https://github.com/permissionlesstech/bitchat/tree/main](https://github.com/permissionlesstech/bitchat/tree/main)
-- Open an issue on GitHub
-- Join the discussion in public rooms
 
-## Philosophy
+- View the source: [https://github.com/permissionlesstech/bitchat](https://github.com/permissionlesstech/bitchat)
-
+- Open an issue on GitHub.
-Privacy isn't just a feature—it's the entire point. bitchat proves that modern communication doesn't require surrendering your privacy. No accounts, no servers, no surveillance. Just people talking freely.
 
 ---
 
-*This policy is released into the public domain under The Unlicense, just like bitchat itself.*
+*This policy is released into the public domain under The Unlicense, like the project itself.*

Package.swift

@@ -13,7 +13,7 @@ let package = Package(
         .executable(
             name: "bitchat",
             targets: ["bitchat"]
-        ),
+        )
     ],
     dependencies: [
         .package(path: "localPackages/Arti"),
@@ -53,11 +53,17 @@ let package = Package(
             path: "bitchatTests",
             exclude: [
                 "Info.plist",
-                "README.md"
+                "README.md",
+                // CI perf gate data (read by scripts/check-perf-floors.sh),
+                // not a test resource.
+                "Performance/perf-floors.json"
             ],
             resources: [
                 .process("Localization"),
-                .process("Noise")
+                // Only the vector fixture: declaring the whole "Noise"
+                // directory would claim its .swift test files as resources
+                // and silently drop them from compilation.
+                .process("Noise/NoiseTestVectors.json")
             ]
         )
     ]

WHITEPAPER.md

@@ -1,309 +1,141 @@
-# BitChat Protocol Whitepaper
+# bitchat Protocol Whitepaper
 
-**Version 1.1**
+**Version 2.0**
 
-**Date: July 25, 2025**
+**Date: July 6, 2026**
 
 ---
 
 ## Abstract
 
-BitChat is a decentralized, peer-to-peer messaging application designed for secure, private, and censorship-resistant communication over ephemeral, ad-hoc networks. This whitepaper details the BitChat Protocol Stack, a layered architecture that combines a modern cryptographic foundation with a flexible application protocol. At its core, BitChat leverages the Noise Protocol Framework (specifically, the `XX` pattern) to establish mutually authenticated, end-to-end encrypted sessions between peers. This document provides a technical specification of the identity management, session lifecycle, message framing, and security considerations that underpin the BitChat network.
+bitchat is a decentralized, peer-to-peer messaging application for secure, private, censorship-resistant communication that works with or without the internet. Nearby devices form an ad-hoc Bluetooth Low Energy (BLE) mesh; distant peers are reached over the Nostr protocol when a connection exists. A layered store-and-forward stack — a persistent sender outbox, opportunistic couriers with a spray-and-wait copy budget, gossip-synced public history, and Nostr relay mailboxes — delivers messages to peers who are out of range at send time. This document describes the protocol and its delivery guarantees as implemented.
 
 ---
 
-## 1. Introduction
+## 1. Design Goals
 
-In an era of centralized communication platforms, BitChat offers a resilient alternative by operating without central servers. It is designed for scenarios where internet connectivity is unavailable or untrustworthy, such as protests, natural disasters, or remote areas. Communication occurs directly between devices over transports like Bluetooth Low Energy (BLE).
+* **Confidentiality:** all private communication is end-to-end encrypted; intermediate nodes and couriers carry only opaque ciphertext.
+* **Authentication:** peers are identified by cryptographic keys; announcements are signed and verified.
+* **Resilience:** the network functions in lossy, low-bandwidth, partitioned environments with churning membership.
+* **Eventual delivery:** a message to an out-of-range peer should still arrive — relayed by the mesh, carried by a moving person, or resting on an internet relay — within a bounded retention window.
+* **Ephemerality by default:** no plaintext message content is ever written to disk. Everything the store-and-forward stack persists is either sealed ciphertext or already-public broadcast traffic, and all of it dies with the panic wipe.
 
-The design goals of the BitChat Protocol are:
+## 2. Architecture Overview
 
-*   **Confidentiality:** All communication must be unreadable to third parties.
+Two transports implement a common `Transport` interface and are coordinated by a `MessageRouter`:
-*   **Authentication:** Users must be able to verify the identity of their correspondents.
-*   **Integrity:** Messages cannot be tampered with in transit.
-*   **Forward Secrecy:** The compromise of long-term identity keys must not compromise past session keys.
-*   **Deniability:** It should be difficult to cryptographically prove that a specific user sent a particular message.
-*   **Resilience:** The protocol must function reliably in lossy, low-bandwidth environments.
 
-This paper specifies the technical details of the protocol designed to meet these goals.
+* **BLE mesh** — every device is simultaneously a GATT central and peripheral, relaying packets in a controlled flood. No infrastructure, pairing, or accounts.
+* **Nostr** — private messages to mutual favorites travel as NIP-17 gift-wrapped events over public relays (over Tor where enabled), bridging separate meshes through the internet.
 
----
+The router prefers a live mesh link, falls back to Nostr, and engages the courier system when neither can deliver promptly.
 
-## 2. Protocol Stack
+## 3. Identity
 
-The BitChat Protocol is a four-layer stack. This layered approach separates concerns, allowing for modularity and future extensibility.
+Each device holds two long-term key pairs in the Keychain:
 
-```mermaid
+* a **Curve25519 static key** for Noise key agreement — its SHA-256 fingerprint is the peer's stable identity, and
-graph TD
+* an **Ed25519 signing key** for packet signatures.
-    A[Application Layer] --> B[Session Layer];
-    B --> C[Encryption Layer];
-    C --> D[Transport Layer];
 
-    subgraph "BitChat Application"
+On the mesh, peers appear under short ephemeral IDs derived per session; favoriting pins the full Noise public key so identity survives across sessions. Mutual favorites also exchange Nostr public keys for the internet path. Optional QR verification binds a nickname to a fingerprint in person.
-        A
-    end
 
-    subgraph "Message Framing & State"
+## 4. BLE Mesh Layer
-        B
-    end
 
-    subgraph "Noise Protocol Framework"
+### 4.1 Packet Format
-        C
-    end
 
-    subgraph "BLE, Wi-Fi Direct, etc."
+A compact binary header (version, type, TTL, timestamp, flags) is followed by an 8-byte sender ID, an optional 8-byte recipient ID, the payload, and an optional Ed25519 signature. Version 2 packets may carry an explicit source route. Signatures exclude the TTL byte so relays can decrement it without invalidating them. Packets other than fragments are padded toward uniform sizes.
-        D
-    end
 
-    style A fill:#cde4ff
+### 4.2 Flood Control
-    style B fill:#b5d8ff
-    style C fill:#9ac2ff
-    style D fill:#7eadff
-```
 
-*   **Application Layer:** Defines the structure of user-facing messages (`BitchatMessage`), acknowledgments (`DeliveryAck`), and other application-level data.
+Relaying is a deterministic controlled flood tuned by local connection degree:
-*   **Session Layer:** Manages the overall communication packet (`BitchatPacket`). This includes routing information (TTL), message typing, fragmentation, and serialization into a compact binary format.
-*   **Encryption Layer:** Establishes and manages secure channels using the Noise Protocol Framework. It is responsible for the cryptographic handshake, session management, and transport message encryption/decryption.
-*   **Transport Layer:** The underlying physical medium used for data transmission, such as Bluetooth Low Energy (BLE). This layer is abstracted away from the core protocol.
 
----
+* **TTL:** packets originate with TTL 7. Relays clamp: dense graphs (≥ 6 links) cap broadcast TTL at 5; thin chains (≤ 2 links) relay at full incoming depth.
+* **Deduplication:** an LRU seen-set (1000 entries, 5-minute expiry) keyed by sender, timestamp, type, and a payload digest drops duplicates. A scheduled relay is cancelled when a duplicate arrives first from another relay.
+* **Jitter:** relays wait a random 10–220 ms (wider when dense) so duplicate suppression wins often.
+* **Fanout subsetting:** broadcast messages are re-sent to a deterministic, message-ID-seeded subset of links (~log₂ of degree) rather than all of them; announces, fragments, and sync packets use full fanout. The ingress link is always excluded (split horizon).
+* **Directed traffic** (handshakes, private messages, courier envelopes) relays deterministically with TTL − 1 and tight jitter, and is never subset.
 
-## 3. Identity and Key Management
+### 4.3 Routing
 
-A peer's identity in BitChat is defined by two persistent cryptographic key pairs, which are generated on first launch and stored securely in the device's Keychain.
+Announcements carry up to 10 direct-neighbor IDs, giving each node a shallow topology map (60 s freshness). When a bidirectionally-confirmed path exists, packets are source-routed along it; otherwise — and whenever a route fails — delivery falls back to flooding.
 
-1.  **Noise Static Key Pair (`Curve25519`):** This is the long-term identity key used for the Noise Protocol handshake. The public part of this key is shared with peers to establish secure sessions.
+### 4.4 Fragmentation
-2.  **Signing Key Pair (`Ed25519`):** This key is used to sign announcements and other protocol messages where non-repudiation is required, such as binding a public key to a nickname.
 
-### 3.1. Fingerprint
+Packets exceeding the link MTU split into ~469-byte fragments (8-byte fragment ID, index/total header) that relay independently and reassemble at each receiving node (128 concurrent assemblies, 30 s timeout, 1 MiB cap).
 
-A user's unique, verifiable fingerprint is the **SHA-256 hash** of their **Noise static public key**. This provides a user-friendly and secure way to verify an identity out-of-band (e.g., by reading it aloud or scanning a QR code).
+### 4.5 Presence
 
-`Fingerprint = SHA256(StaticPublicKey_Curve25519)`
+Signed announcements propagate multi-hop: every 4 s while isolated, backing off to ~15–30 s (jittered) when connected. A verified announce retains a peer as *reachable* for 60 s after last contact. Connection scheduling is RSSI-gated with duty-cycled scanning to bound battery drain.
 
-### 3.2. Identity Management
+## 5. Encryption
 
-The `SecureIdentityStateManager` class is responsible for managing all cryptographic identity material and social metadata (petnames, trust levels, etc.). It uses an in-memory cache for performance and persists this cache to the Keychain after encrypting it with a separate AES-GCM key.
+### 5.1 Live Sessions: Noise XX
 
----
+Connected peers establish sessions with the Noise `XX` pattern (Curve25519 / ChaCha20-Poly1305 / SHA-256), providing mutual authentication and forward secrecy. All private payloads — messages, delivery acks, read receipts — ride inside the session as typed ciphertext. Intermediate relays see only opaque `noiseEncrypted` packets.
 
-## 4. The Social Trust Layer
+### 5.2 Offline Seals: Noise X
 
-Beyond cryptographic identity, BitChat incorporates a social trust layer, allowing users to manage their relationships with peers. This functionality is handled by the `SecureIdentityStateManager`.
+Courier envelopes are sealed to the recipient's *static* key with the one-way Noise `X` pattern; the sender's identity is authenticated inside the ciphertext. **This path has no forward secrecy** — compromise of the recipient's static key exposes sealed-but-undelivered mail. A prekey scheme is future work.
 
-### 4.1. Peer Verification
+### 5.3 Nostr Path
 
-While the Noise handshake cryptographically authenticates a peer's key, it doesn't confirm the real-world identity of the person holding the device. To solve this, users can perform out-of-band (OOB) verification by comparing fingerprints. Once a user confirms that a peer's fingerprint matches the one they expect, they can mark that peer as "verified". This status is stored locally and displayed in the UI, providing a strong assurance of identity for future conversations.
+Private messages to mutual favorites are wrapped per NIP-17/NIP-59: a rumor (kind 14) sealed (kind 13) and gift-wrapped (kind 1059) under a throwaway ephemeral key, so relays learn neither sender nor content.
 
-### 4.2. Favorites and Blocking
+## 6. Store and Forward
 
-To improve the user experience and provide control over interactions, the protocol supports:
+Four mechanisms cover the "recipient is not here right now" problem. All persisted state is wiped by panic mode.
-*   **Favorites:** Users can mark trusted or frequently contacted peers as "favorites". This is a local designation that can be used by the application to prioritize notifications or display peers more prominently.
-*   **Blocking:** Users can block peers. When a peer is blocked, the application will discard any incoming packets from that peer's fingerprint at the earliest possible stage, effectively silencing them without notifying the blocked peer.
 
----
+### 6.1 Sender Outbox
 
-## 5. The Noise Protocol Layer
+Private messages without a prompt route are retained per peer (100 messages/peer, 24 h TTL) and re-sent on reconnect events until a delivery or read ack clears them, or a resend cap (8 attempts) drops them with visible failure. The outbox persists to disk sealed under a ChaChaPoly key held only in the Keychain, so queued mail survives an app kill without ever storing plaintext.
 
-BitChat implements the Noise Protocol Framework to provide strong, authenticated end-to-end encryption.
+### 6.2 Couriers
 
-### 5.1. Protocol Name
+When no transport can deliver promptly, the message is sealed (§5.2) into a **courier envelope** and handed to up to 3 connected peers who may physically encounter the recipient:
 
-The specific Noise protocol implemented is:
+* **Opaque addressing.** The only routing information is a 16-byte rotating recipient tag — an HMAC of the recipient's static key and the UTC day — computable solely by parties who already know that key. Couriers learn neither sender, recipient, nor content, and tags do not correlate across days.
+* **Trust tiers.** Mutual favorites may deposit 5 envelopes each; any peer with a signature-verified announce may deposit 2, into a bounded pool (20 of 40 slots) that can never crowd out favorites' mail. Envelopes are capped at 16 KiB and 24 h; overflow evicts oldest verified-tier mail first.
+* **Deposit retry.** Queued messages are re-deposited whenever a new eligible courier connects, until 3 distinct couriers carry the message or it expires.
+* **Spray and wait.** Envelopes carry a copy budget (initially 4, capped at 8). A courier meeting another eligible courier hands over half its remaining budget, so mail diffuses through a moving crowd instead of riding one person. Budgets, spray history, and carried mail persist across app restarts (iOS file protection).
+* **Handover.** On a verified *direct* announce from the recipient, matching envelopes are delivered over the live link and removed. On a verified *relayed* announce, a copy floods toward the recipient as a directed packet while the carried original stays put, throttled to one attempt per envelope per 10 minutes.
+* Receivers dedup by message ID, so redundant copies and the retained outbox original are harmless. Couriered mail from blocked senders is dropped at decryption time.
 
-**`Noise_XX_25519_ChaChaPoly_SHA256`**
+### 6.3 Public History (Gossip Sync)
 
-*   **`XX` Pattern:** This handshake pattern provides mutual authentication and forward secrecy. It does not require either party to know the other's static public key before the handshake begins. The keys are exchanged and authenticated during the three-part handshake. This is ideal for a decentralized P2P environment.
+Public broadcast messages are cached (1000 packets) and reconciled between peers every ~15 s using compact GCS filters: each side advertises what it holds, the other returns what is missing. Messages stay sync-able for **6 hours** and the cache persists to disk, so a device that walks between two partitions — or relaunches later — serves the room's recent history to whoever missed it. Fragments and file transfers keep a short 15-minute window.
-*   **`25519`:** The Diffie-Hellman function used is Curve25519.
-*   **`ChaChaPoly`:** The AEAD (Authenticated Encryption with Associated Data) cipher is ChaCha20-Poly1305.
-*   **`SHA256`:** The hash function used for all cryptographic hashing operations is SHA-256.
 
-### 5.2. The `XX` Handshake
+### 6.4 Nostr Mailboxes
 
-The `XX` handshake consists of three messages exchanged between an Initiator and a Responder to establish a shared secret and derive transport encryption keys.
+Gift-wrapped messages rest on Nostr relays; clients re-subscribe with a 24-hour lookback on reconnect, covering the both-devices-offline case for mutual favorites whenever either side touches the internet.
 
-```mermaid
+### 6.5 Delivery Metrics
-sequenceDiagram
-    participant I as Initiator
-    participant R as Responder
 
-    Note over I, R: Pre-computation: h = SHA256(protocol_name)
+Bare local counters (deposits, handovers, sprays, opens, outbox flushes and drops — no identities, message IDs, or timestamps) let delivery behavior be measured on-device. They never leave the device and are cleared by the panic wipe.
 
-    I->>R: -> e
+## 7. Application Layer
-    Note right of I: I generates ephemeral key `e_i`.<br/>h = SHA256(h + e_i.pub)
 
-    R->>I: <- e, ee, s, es
+* **Public chat** — signed broadcast messages within the mesh, backed by the gossip-synced history above.
-    Note left of R: R generates ephemeral key `e_r`.<br/>h = SHA256(h + e_r.pub)<br/>MixKey(DH(e_i, e_r))<br/>R sends static key `s_r`, encrypted.<br/>h = SHA256(h + ciphertext)<br/>MixKey(DH(e_i, s_r))
+* **Private chat** — end-to-end encrypted messages with delivery and read receipts, over mesh, courier, or Nostr.
-
+* **Location channels** — geohash-scoped public rooms carried over Nostr relays for regional chat beyond radio range.
-    I->>R: -> s, se
+* **Favorites** — the mutual-trust relationship that unlocks Nostr delivery and the larger courier quota.
-    Note right of I: I decrypts and verifies `s_r`.<br/>I sends static key `s_i`, encrypted.<br/>h = SHA256(h + ciphertext)<br/>MixKey(DH(s_i, e_r))
+* **Media** — files and images fragment over the mesh (1 MiB cap, explicit accept before anything touches disk); couriers carry text only.
-
+* **Panic wipe** — clears identity keys, favorites, carried courier mail, the sealed outbox, archived public history, and metrics.
-    Note over I, R: Handshake complete. Transport keys derived.
-```
-
-**Handshake Flow:**
-
-1.  **Initiator -> Responder:** The initiator generates a new ephemeral key pair (`e_i`) and sends the public part to the responder.
-2.  **Responder -> Initiator:** The responder receives the initiator's ephemeral public key. It then generates its own ephemeral key pair (`e_r`), performs a DH exchange with the initiator's ephemeral key (`ee`), sends its own static public key (`s_r`) encrypted with the resulting symmetric key, and performs another DH exchange between the initiator's ephemeral key and its own static key (`es`).
-3.  **Initiator -> Responder:** The initiator receives the responder's message, decrypts the responder's static key, and authenticates it. The initiator then sends its own static key (`s_i`) encrypted and performs a final DH exchange between its static key and the responder's ephemeral key (`se`).
-
-Upon completion, both parties share a set of symmetric keys for bidirectional transport message encryption. The final handshake hash is used for channel binding.
-
-### 5.3. Session Management
-
-The `NoiseSessionManager` class manages all active Noise sessions. It handles:
-*   Creating sessions for new peers.
-*   Coordinating the handshake process to prevent race conditions.
-*   Storing the resulting transport ciphers (`sendCipher`, `receiveCipher`).
-*   Periodically checking if sessions need to be re-keyed for enhanced security.
-
----
-
-## 6. The BitChat Session and Application Protocol
-
-Once a Noise session is established, peers exchange `BitchatPacket` structures, which are encrypted as the payload of Noise transport messages.
-
-### 6.1. Binary Packet Format (`BitchatPacket`)
-
-To minimize bandwidth, `BitchatPacket`s are serialized into a compact binary format. The structure is designed to be fixed-size where possible to resist traffic analysis.
-
-| Field           | Size (bytes) | Description                                                                                             |
-|-----------------|--------------|---------------------------------------------------------------------------------------------------------|
-| **Header**      | **13**       | **Fixed-size header**                                                                                   |
-| Version         | 1            | Protocol version (currently `1`).                                                                       |
-| Type            | 1            | Message type (e.g., `message`, `deliveryAck`, `noiseHandshakeInit`). See `MessageType` enum.            |
-| TTL             | 1            | Time-To-Live for mesh network routing. Decremented at each hop.                                         |
-| Timestamp       | 8            | `UInt64` millisecond timestamp of packet creation.                                                      |
-| Flags           | 1            | Bitmask for optional fields (`hasRecipient`, `hasSignature`, `isCompressed`).                           |
-| Payload Length  | 2            | `UInt16` length of the payload field.                                                                   |
-| **Variable**    | **...**      | **Variable-size fields**                                                                                |
-| Sender ID       | 8            | 8-byte truncated peer ID of the sender.                                                                 |
-| Recipient ID    | 8 (optional) | 8-byte truncated peer ID of the recipient. Present if `hasRecipient` flag is set. Broadcast if `0xFF..FF`. |
-| Payload         | Variable     | The actual content of the packet, as defined by the `Type` field.                                       |
-| Signature       | 64 (optional)| `Ed25519` signature of the packet. Present if `hasSignature` flag is set.                               |
-
-**Padding:** All packets are padded to the next standard block size (256, 512, 1024, or 2048 bytes) using a PKCS#7-style scheme to obscure the true message length from network observers.
-
-```mermaid
----
-config:
-  theme: dark
----
----
-title: "BitchatPacket"
----
-packet
-+8: "Version"
-+8: "Type"
-+8: "TTL"
-+64: "Timestamp"
-+8: "Flags"
-+16: "Payload Length"
-+64: "Sender ID"
-+64: "Recipient ID (optional)"
-+48: "Payload (variable)"
-+64: "Signature (optional)"
-```
-_A representation of the sizes of the fields in `BitchatPacket`_
-
-### 6.2. Application Message Format (`BitchatMessage`)
-
-For packets of type `message`, the payload is a binary-serialized `BitchatMessage` containing the chat content.
-
-| Field               | Size (bytes) | Description                                                              |
-|---------------------|--------------|--------------------------------------------------------------------------|
-| Flags               | 1            | Bitmask for optional fields (`isRelay`, `isPrivate`, `hasOriginalSender`). |
-| Timestamp           | 8            | `UInt64` millisecond timestamp of message creation.                      |
-| ID                  | 1 + len      | `UUID` string for the message.                                           |
-| Sender              | 1 + len      | Nickname of the sender.                                                  |
-| Content             | 2 + len      | The UTF-8 encoded message content.                                       |
-| Original Sender     | 1 + len (opt)| Nickname of the original sender if the message is a relay.               |
-| Recipient Nickname  | 1 + len (opt)| Nickname of the recipient for private messages.                          |
-
-```mermaid
----
-config:
-  theme: dark
----
----
-title: "BitchatMessage"
----
-packet
-+8: "Flags"
-+64: "Timestamp"
-+24: "ID (variable)"
-+32: "Sender (variable)"
-+32: "Content (variable)"
-+32: "Original Sender (variable) (optional)"
-+32: "Recipient Nickname (variable) (optional)"
-```
-_A representation of the sizes of the fields in `BitchatMessage`_
-
----
-
-## 7. Message Routing and Propagation
-
-BitChat operates as a decentralized mesh network, meaning there are no central servers to route messages. Packets are propagated through the network from peer to peer. The protocol supports several modes of message delivery.
-
-### 7.1. Direct Connection
-
-This is the simplest case. If Peer A and Peer B are directly connected, they can exchange packets after establishing a mutually authenticated Noise session. All packets are encrypted using the transport ciphers derived from the handshake.
-
-### 7.2. Efficient Gossip with Bloom Filters
-
-To send messages to peers that are not directly connected, BitChat employs a "flooding" or "gossip" protocol. When a peer receives a packet that is not destined for it, it acts as a relay. To prevent infinite routing loops and minimize memory usage, the protocol uses an `OptimizedBloomFilter` to track recently seen packet IDs.
-
-The logic is as follows:
-
-1.  A peer receives a packet.
-2.  It checks the Bloom filter to see if the packet's ID has likely been seen before. If so, the packet is discarded. Bloom filters can have false positives (though they are rare), but they guarantee no false negatives. This means that while some packets may be incorrectly discarded due to false positives, the gossip protocol's redundancy ensures these packets will eventually be received through subsequent exchanges with other peers.
-3.  If the packet is new, its ID is added to the Bloom filter.
-4.  The peer decrements the packet's Time-To-Live (TTL) field.
-5.  If the TTL is greater than zero, the peer re-broadcasts the packet to all of its connected peers, *except* for the peer from which it received the packet.
-
-This mechanism allows packets to "flood" through the network efficiently, maximizing the chance of reaching their destination while using minimal resources to prevent loops.
-
-### 7.3. Time-To-Live (TTL)
-
-Every `BitchatPacket` contains an 8-bit TTL field. This value is set by the originating peer and is decremented by one at each relay hop. If a peer receives a packet and decrements its TTL to 0, it will process the packet (if it is the recipient) but will not relay it further. This is a crucial mechanism to prevent packets from circulating endlessly in the mesh.
-
-### 7.4. Private vs. Broadcast Messages
-
-The routing logic respects the confidentiality of private messages:
-
-*   **Private Messages:** A packet with a specific `recipientID` is a private message. Relay nodes forward the entire, encrypted Noise message without being able to access the inner `BitchatPacket` or its payload. Only the final recipient, who shares the correct Noise session keys with the sender, can decrypt the packet.
-*   **Broadcast Messages:** A packet with the special broadcast `recipientID` (`0xFFFFFFFFFFFFFFFF`) is intended for all peers. Any peer that receives and decrypts a broadcast message will process its content. It will still be relayed according to the flooding algorithm to ensure it reaches the entire network.
-
-### 7.5. Message Reliability and Lifecycle
-
-To function in unreliable, lossy networks, the protocol includes features to track the lifecycle of a message and ensure its delivery.
-
-*   **Delivery Acknowledgments (`DeliveryAck`):** When a private message reaches its final destination, the recipient's device sends a `DeliveryAck` packet back to the original sender. This acknowledgment contains the ID of the original message.
-*   **Read Receipts (`ReadReceipt`):** After a message is displayed on the recipient's screen, the application can send a `ReadReceipt`, also containing the original message ID, to inform the sender that the message has been seen.
-*   **Message Retry Service:** Senders maintain a `MessageRetryService` which tracks outgoing messages. If a `DeliveryAck` is not received for a message within a certain time window, the service will automatically re-send the message, creating a more resilient user experience.
-
-### 7.6. Fragmentation
-
-Transport layers like BLE have a Maximum Transmission Unit (MTU) that limits the size of a single packet. To handle messages larger than this limit, BitChat implements a fragmentation protocol.
-
-*   **`fragmentStart`:** A packet with this type marks the beginning of a fragmented message. It contains metadata about the total size and number of fragments.
-*   **`fragmentContinue`:** These packets carry the intermediate chunks of the message data.
-*   **`fragmentEnd`:** This packet carries the final chunk of the message and signals the receiver to begin reassembly.
-
-Receiving peers collect all fragments and reassemble them in the correct order before passing the complete message up to the application layer.
-
----
 
 ## 8. Security Considerations
 
-*   **Replay Attacks:** The Noise transport messages include a nonce that is incremented for each message. The `NoiseCipherState` implements a sliding window replay protection mechanism to detect and discard replayed or out-of-order messages.
+* **Relay nodes** cannot read private traffic; they forward padded, opaque ciphertext.
-*   **Denial of Service:** The `NoiseRateLimiter` is implemented to prevent resource exhaustion from rapid, repeated handshake attempts from a single peer.
+* **Couriers** are quota-bounded mailbags. A malicious courier can drop mail (redundant copies and deposit retry mitigate this) but cannot read it, link it across days, or amplify it — copy budgets are capped and every envelope is validated against size and lifetime policy on deposit.
-*   **Key-Compromise Impersonation:** The `XX` pattern authenticates both parties, preventing an attacker from impersonating one party to the other.
+* **Flooding abuse** is bounded by TTL clamps, deduplication, per-depositor quotas, connect-rate limits, and announce-rate limiting.
-*   **Identity Binding:** While the Noise handshake authenticates the cryptographic keys, binding those keys to a human-readable nickname is handled at the application layer. Users must verify fingerprints out-of-band to prevent man-in-the-middle attacks.
+* **Replay** of public broadcasts is bounded by the 6-hour acceptance window plus deduplication; private payloads are protected by Noise nonces.
-*   **Traffic Analysis:** The use of fixed-size padding for all packets helps to obscure the exact nature and content of the communication, making it harder for a network-level adversary to infer information based on message size.
+* **Metadata.** BLE proximity is inherently observable; ephemeral IDs and daily-rotating courier tags limit long-term correlation. Nostr traffic can ride Tor.
+* **No forward secrecy for sealed mail** (§5.2) is the main cryptographic trade-off of the offline path.
+
+## 9. Future Work
+
+* Prekey-based forward secrecy for courier envelopes.
+* Couriered media beyond the 16 KiB text cap.
+* Probabilistic relay and edge-of-network TTL boosting for very dense and very sparse graphs.
+* Multi-hop courier routing informed by encounter history.
 
 ---
 
-## 9. Conclusion
+*This document describes the protocol as implemented in the current release. The implementation is free and unencumbered software released into the public domain.*
-
-The BitChat Protocol provides a robust and secure foundation for decentralized, peer-to-peer communication. By layering a flexible application protocol on top of the well-regarded Noise Protocol Framework, it achieves strong confidentiality, authentication, and forward secrecy. The use of a compact binary format and thoughtful security considerations like rate limiting and traffic analysis resistance make it suitable for use in challenging network environments.

bitchat.xcodeproj/project.pbxproj

@@ -92,7 +92,8 @@
 		A6E32D232E762EAB0032EA8A /* Exceptions for "bitchatShareExtension" folder in "bitchatShareExtension" target */ = {
 			isa = PBXFileSystemSynchronizedBuildFileExceptionSet;
 			membershipExceptions = (
-				ShareViewController.swift,
+				Info.plist,
+				bitchatShareExtension.entitlements,
 			);
 			target = 57CA17A36A2532A6CFF367BB /* bitchatShareExtension */;
 		};
@@ -258,9 +259,13 @@
 			buildConfigurationList = E4EA6DC648DF55FF84032EB5 /* Build configuration list for PBXNativeTarget "bitchatShareExtension" */;
 			buildPhases = (
 				0A08E70F08F55FD5BA8C7EF3 /* Sources */,
+				7E9B64F63F93443FB7BA12DF /* Resources */,
 			);
 			buildRules = (
 			);
+			fileSystemSynchronizedGroups = (
+				A6E32D212E762EAB0032EA8A /* bitchatShareExtension */,
+			);
 			name = bitchatShareExtension;
 			productName = bitchatShareExtension;
 			productReference = 61F92EBA29C47C0FCC482F1F /* bitchatShareExtension.appex */;
@@ -321,7 +326,7 @@
 			isa = PBXProject;
 			attributes = {
 				BuildIndependentTargetsInParallel = YES;
-				LastUpgradeCheck = 1640;
+				LastUpgradeCheck = 2650;
 			};
 			buildConfigurationList = 3EA424CBD51200895D361189 /* Build configuration list for PBXProject "bitchat" */;
 			developmentRegion = en;
@@ -388,6 +393,13 @@
 				E0A1B2C3D4E5F6012345678E /* relays/online_relays_gps.csv in Resources */,
 			);
 		};
+		7E9B64F63F93443FB7BA12DF /* Resources */ = {
+			isa = PBXResourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
 /* End PBXResourcesBuildPhase section */
 
 /* Begin PBXSourcesBuildPhase section */
@@ -446,7 +458,6 @@
 				CODE_SIGNING_ALLOWED = YES;
 				CODE_SIGNING_REQUIRED = YES;
 				CODE_SIGN_STYLE = "$(CODE_SIGN_STYLE)";
-				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				INFOPLIST_FILE = bitchatTests/Info.plist;
 				IPHONEOS_DEPLOYMENT_TARGET = "$(IPHONEOS_DEPLOYMENT_TARGET)";
 				LD_RUNPATH_SEARCH_PATHS = (
@@ -471,7 +482,6 @@
 				CODE_SIGNING_ALLOWED = YES;
 				CODE_SIGNING_REQUIRED = YES;
 				CODE_SIGN_STYLE = "$(CODE_SIGN_STYLE)";
-				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				INFOPLIST_FILE = bitchatTests/Info.plist;
 				IPHONEOS_DEPLOYMENT_TARGET = "$(IPHONEOS_DEPLOYMENT_TARGET)";
 				LD_RUNPATH_SEARCH_PATHS = (
@@ -498,7 +508,6 @@
 				CODE_SIGN_STYLE = "$(CODE_SIGN_STYLE)";
 				COMBINE_HIDPI_IMAGES = YES;
 				DEAD_CODE_STRIPPING = YES;
-				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				INFOPLIST_FILE = bitchatTests/Info.plist;
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
@@ -523,7 +532,6 @@
 				CODE_SIGN_ALLOW_ENTITLEMENTS_MODIFICATION = YES;
 				CODE_SIGN_ENTITLEMENTS = bitchatShareExtension/bitchatShareExtension.entitlements;
 				CODE_SIGN_STYLE = "$(CODE_SIGN_STYLE)";
-				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				INFOPLIST_FILE = bitchatShareExtension/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = bitchat;
 				IPHONEOS_DEPLOYMENT_TARGET = "$(IPHONEOS_DEPLOYMENT_TARGET)";
@@ -532,7 +540,6 @@
 					"@executable_path/Frameworks",
 					"@executable_path/../../Frameworks",
 				);
-				MARKETING_VERSION = "$(MARKETING_VERSION)";
 				PRODUCT_BUNDLE_IDENTIFIER = "$(PRODUCT_BUNDLE_IDENTIFIER).ShareExtension";
 				SDKROOT = iphoneos;
 				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator";
@@ -556,7 +563,6 @@
 				CODE_SIGN_ENTITLEMENTS = bitchat/bitchat.entitlements;
 				CODE_SIGN_STYLE = "$(CODE_SIGN_STYLE)";
 				DEVELOPMENT_ASSET_PATHS = bitchat/_PreviewHelpers;
-				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				ENABLE_PREVIEWS = NO;
 				INFOPLIST_FILE = bitchat/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = bitchat;
@@ -566,7 +572,6 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 1.5.1;
 				PRODUCT_BUNDLE_IDENTIFIER = "$(PRODUCT_BUNDLE_IDENTIFIER)";
 				PRODUCT_NAME = bitchat;
 				SDKROOT = iphoneos;
@@ -590,7 +595,6 @@
 				CODE_SIGN_STYLE = "$(CODE_SIGN_STYLE)";
 				COMBINE_HIDPI_IMAGES = YES;
 				DEAD_CODE_STRIPPING = YES;
-				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				INFOPLIST_FILE = bitchatTests/Info.plist;
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
@@ -617,7 +621,6 @@
 				CODE_SIGN_ENTITLEMENTS = bitchat/bitchat.entitlements;
 				CODE_SIGN_STYLE = "$(CODE_SIGN_STYLE)";
 				DEVELOPMENT_ASSET_PATHS = bitchat/_PreviewHelpers;
-				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				ENABLE_PREVIEWS = YES;
 				INFOPLIST_FILE = bitchat/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = bitchat;
@@ -627,7 +630,6 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 1.5.1;
 				PRODUCT_BUNDLE_IDENTIFIER = "$(PRODUCT_BUNDLE_IDENTIFIER)";
 				PRODUCT_NAME = bitchat;
 				SDKROOT = iphoneos;
@@ -653,7 +655,6 @@
 				CODE_SIGN_STYLE = "$(CODE_SIGN_STYLE)";
 				COMBINE_HIDPI_IMAGES = YES;
 				DEAD_CODE_STRIPPING = YES;
-				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				ENABLE_PREVIEWS = YES;
 				INFOPLIST_FILE = bitchat/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = bitchat;
@@ -663,7 +664,6 @@
 					"@executable_path/../Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = "$(MACOSX_DEPLOYMENT_TARGET)";
-				MARKETING_VERSION = 1.5.1;
 				PRODUCT_BUNDLE_IDENTIFIER = "$(PRODUCT_BUNDLE_IDENTIFIER)";
 				PRODUCT_NAME = bitchat;
 				REGISTER_APP_GROUPS = YES;
@@ -676,6 +676,7 @@
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				ALWAYS_SEARCH_USER_PATHS = NO;
+				CLANG_ANALYZER_LOCALIZABILITY_NONLOCALIZED = YES;
 				CLANG_ANALYZER_NONNULL = YES;
 				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
 				CLANG_CXX_LANGUAGE_STANDARD = "gnu++14";
@@ -709,6 +710,7 @@
 				CURRENT_PROJECT_VERSION = "$(CURRENT_PROJECT_VERSION)";
 				DEAD_CODE_STRIPPING = YES;
 				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
+				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				ENABLE_NS_ASSERTIONS = NO;
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				ENABLE_USER_SCRIPT_SANDBOXING = YES;
@@ -722,10 +724,10 @@
 				GCC_WARN_UNUSED_VARIABLE = YES;
 				IPHONEOS_DEPLOYMENT_TARGET = "$(IPHONEOS_DEPLOYMENT_TARGET)";
 				MACOSX_DEPLOYMENT_TARGET = "$(MACOSX_DEPLOYMENT_TARGET)";
-				MARKETING_VERSION = "$(MARKETING_VERSION)";
 				MTL_ENABLE_DEBUG_INFO = NO;
 				MTL_FAST_MATH = YES;
 				PRODUCT_NAME = "$(TARGET_NAME)";
+				STRING_CATALOG_GENERATE_SYMBOLS = NO;
 				SWIFT_COMPILATION_MODE = wholemodule;
 				SWIFT_OPTIMIZATION_LEVEL = "-O";
 				SWIFT_VERSION = "$(SWIFT_VERSION)";
@@ -745,7 +747,6 @@
 				CODE_SIGN_STYLE = "$(CODE_SIGN_STYLE)";
 				COMBINE_HIDPI_IMAGES = YES;
 				DEAD_CODE_STRIPPING = YES;
-				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				ENABLE_PREVIEWS = NO;
 				INFOPLIST_FILE = bitchat/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = bitchat;
@@ -755,7 +756,6 @@
 					"@executable_path/../Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = "$(MACOSX_DEPLOYMENT_TARGET)";
-				MARKETING_VERSION = 1.5.1;
 				PRODUCT_BUNDLE_IDENTIFIER = "$(PRODUCT_BUNDLE_IDENTIFIER)";
 				PRODUCT_NAME = bitchat;
 				REGISTER_APP_GROUPS = YES;
@@ -768,6 +768,7 @@
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				ALWAYS_SEARCH_USER_PATHS = NO;
+				CLANG_ANALYZER_LOCALIZABILITY_NONLOCALIZED = YES;
 				CLANG_ANALYZER_NONNULL = YES;
 				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
 				CLANG_CXX_LANGUAGE_STANDARD = "gnu++14";
@@ -801,6 +802,7 @@
 				CURRENT_PROJECT_VERSION = "$(CURRENT_PROJECT_VERSION)";
 				DEAD_CODE_STRIPPING = YES;
 				DEBUG_INFORMATION_FORMAT = dwarf;
+				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				ENABLE_TESTABILITY = YES;
 				ENABLE_USER_SCRIPT_SANDBOXING = YES;
@@ -820,11 +822,11 @@
 				GCC_WARN_UNUSED_VARIABLE = YES;
 				IPHONEOS_DEPLOYMENT_TARGET = "$(IPHONEOS_DEPLOYMENT_TARGET)";
 				MACOSX_DEPLOYMENT_TARGET = "$(MACOSX_DEPLOYMENT_TARGET)";
-				MARKETING_VERSION = "$(MARKETING_VERSION)";
 				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
 				MTL_FAST_MATH = YES;
 				ONLY_ACTIVE_ARCH = YES;
 				PRODUCT_NAME = "$(TARGET_NAME)";
+				STRING_CATALOG_GENERATE_SYMBOLS = NO;
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
 				SWIFT_VERSION = "$(SWIFT_VERSION)";
@@ -841,7 +843,6 @@
 				CODE_SIGN_ALLOW_ENTITLEMENTS_MODIFICATION = YES;
 				CODE_SIGN_ENTITLEMENTS = bitchatShareExtension/bitchatShareExtension.entitlements;
 				CODE_SIGN_STYLE = "$(CODE_SIGN_STYLE)";
-				DEVELOPMENT_TEAM = "$(DEVELOPMENT_TEAM)";
 				INFOPLIST_FILE = bitchatShareExtension/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = bitchat;
 				IPHONEOS_DEPLOYMENT_TARGET = "$(IPHONEOS_DEPLOYMENT_TARGET)";
@@ -850,7 +851,6 @@
 					"@executable_path/Frameworks",
 					"@executable_path/../../Frameworks",
 				);
-				MARKETING_VERSION = "$(MARKETING_VERSION)";
 				PRODUCT_BUNDLE_IDENTIFIER = "$(PRODUCT_BUNDLE_IDENTIFIER).ShareExtension";
 				SDKROOT = iphoneos;
 				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator";

bitchat.xcodeproj/xcshareddata/xcschemes/bitchat (iOS).xcscheme

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <Scheme
-   LastUpgradeVersion = "1640"
+   LastUpgradeVersion = "2650"
    version = "1.3">
    <BuildAction
       parallelizeBuildables = "YES"

bitchat.xcodeproj/xcshareddata/xcschemes/bitchat (macOS).xcscheme

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <Scheme
-   LastUpgradeVersion = "1640"
+   LastUpgradeVersion = "2650"
    version = "1.3">
    <BuildAction
       parallelizeBuildables = "YES"

bitchat/App/AppArchitecture.swift

@@ -36,42 +36,20 @@ enum AppEvent: Sendable, Equatable {
 actor AppEventStream {
     private var continuations: [UUID: AsyncStream<AppEvent>.Continuation] = [:]
 
-    func stream() -> AsyncStream<AppEvent> {
-        let id = UUID()
-        return AsyncStream { continuation in
-            continuations[id] = continuation
-            continuation.onTermination = { [id] _ in
-                Task {
-                    await self.removeContinuation(id)
-                }
-            }
-        }
-    }
-
     func emit(_ event: AppEvent) {
         for continuation in continuations.values {
             continuation.yield(event)
         }
     }
 
-    func finish() {
-        for continuation in continuations.values {
-            continuation.finish()
-        }
-        continuations.removeAll()
-    }
-
-    private func removeContinuation(_ id: UUID) {
-        continuations.removeValue(forKey: id)
-    }
 }
 
+/// Identity key for a direct conversation. Equality and hashing use the
+/// canonical `id` only; `routingPeerID` carries the transport-level peer ID
+/// the conversation is keyed under (see `ConversationID.directPeer`).
 struct PeerHandle: Sendable, Identifiable {
     let id: String
     let routingPeerID: PeerID
-    let displayName: String?
-    let noisePublicKeyHex: String?
-    let nostrPublicKey: String?
 }
 
 extension PeerHandle: Equatable {
@@ -100,264 +78,3 @@ enum ConversationID: Hashable, Sendable {
         }
     }
 }
-
-@MainActor
-final class IdentityResolver {
-    private var handlesByRoutingPeerID: [PeerID: PeerHandle] = [:]
-    private var handlesByNoiseKey: [String: PeerHandle] = [:]
-    private var handlesByNostrKey: [String: PeerHandle] = [:]
-
-    func register(peers: [BitchatPeer]) {
-        for peer in peers {
-            _ = register(peer: peer)
-        }
-    }
-
-    @discardableResult
-    func register(peer: BitchatPeer) -> PeerHandle {
-        let handle = buildHandle(
-            routingPeerID: peer.peerID,
-            displayName: peer.displayName,
-            noisePublicKeyHex: peer.noisePublicKey.isEmpty ? nil : peer.noisePublicKey.hexEncodedString().lowercased(),
-            nostrPublicKey: normalizedNostrKey(peer.nostrPublicKey)
-        )
-        cache(handle)
-        return handle
-    }
-
-    func canonicalHandle(for peerID: PeerID, displayName: String? = nil) -> PeerHandle {
-        if let handle = handlesByRoutingPeerID[peerID] {
-            return handle
-        }
-
-        if peerID.isNoiseKeyHex, let handle = handlesByNoiseKey[peerID.bare] {
-            return handle
-        }
-
-        if (peerID.isGeoDM || peerID.isGeoChat), let handle = handlesByNostrKey[peerID.bare] {
-            return handle
-        }
-
-        let handle = buildHandle(
-            routingPeerID: peerID,
-            displayName: displayName,
-            noisePublicKeyHex: peerID.isNoiseKeyHex ? peerID.bare : nil,
-            nostrPublicKey: (peerID.isGeoDM || peerID.isGeoChat) ? peerID.bare : nil
-        )
-        cache(handle)
-        return handle
-    }
-
-    private func buildHandle(
-        routingPeerID: PeerID,
-        displayName: String?,
-        noisePublicKeyHex: String?,
-        nostrPublicKey: String?
-    ) -> PeerHandle {
-        let canonicalID: String
-        if let noisePublicKeyHex {
-            canonicalID = "noise:\(noisePublicKeyHex)"
-        } else if let nostrPublicKey {
-            canonicalID = "nostr:\(nostrPublicKey)"
-        } else {
-            canonicalID = "mesh:\(routingPeerID.id)"
-        }
-
-        let normalizedDisplayName: String?
-        if let displayName, !displayName.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-            normalizedDisplayName = displayName
-        } else {
-            normalizedDisplayName = nil
-        }
-
-        return PeerHandle(
-            id: canonicalID,
-            routingPeerID: routingPeerID,
-            displayName: normalizedDisplayName,
-            noisePublicKeyHex: noisePublicKeyHex,
-            nostrPublicKey: nostrPublicKey
-        )
-    }
-
-    private func normalizedNostrKey(_ nostrPublicKey: String?) -> String? {
-        guard let nostrPublicKey else { return nil }
-        let trimmed = nostrPublicKey.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
-        return trimmed.isEmpty ? nil : trimmed
-    }
-
-    private func cache(_ handle: PeerHandle) {
-        handlesByRoutingPeerID[handle.routingPeerID] = handle
-        if let noisePublicKeyHex = handle.noisePublicKeyHex {
-            handlesByNoiseKey[noisePublicKeyHex] = handle
-        }
-        if let nostrPublicKey = handle.nostrPublicKey {
-            handlesByNostrKey[nostrPublicKey] = handle
-        }
-    }
-}
-
-@MainActor
-final class ConversationStore: ObservableObject {
-    @Published private(set) var activeChannel: ChannelID = .mesh
-    @Published private(set) var selectedPrivatePeerID: PeerID?
-    @Published private(set) var selectedConversationID: ConversationID = .mesh
-    @Published private(set) var unreadConversations: Set<ConversationID> = []
-    @Published private(set) var messagesByConversation: [ConversationID: [BitchatMessage]] = [:]
-
-    private var directHandlesByConversation: [ConversationID: PeerHandle] = [:]
-
-    func setActiveChannel(_ channelID: ChannelID) {
-        activeChannel = channelID
-        if selectedPrivatePeerID == nil {
-            selectedConversationID = ConversationID(channelID: channelID)
-        }
-    }
-
-    func setSelectedPeerID(
-        _ peerID: PeerID?,
-        activeChannel: ChannelID,
-        identityResolver: IdentityResolver
-    ) {
-        self.activeChannel = activeChannel
-        selectedPrivatePeerID = peerID
-
-        if let peerID {
-            selectedConversationID = directConversationID(
-                for: peerID,
-                identityResolver: identityResolver
-            )
-        } else {
-            selectedConversationID = ConversationID(channelID: activeChannel)
-        }
-    }
-
-    func replaceMessages(_ messages: [BitchatMessage], for conversationID: ConversationID) {
-        messagesByConversation[conversationID] = normalized(messages)
-    }
-
-    func replaceMessages(_ messages: [BitchatMessage], for channelID: ChannelID) {
-        replaceMessages(messages, for: ConversationID(channelID: channelID))
-    }
-
-    func synchronizePublicConversation(_ messages: [BitchatMessage], activeChannel: ChannelID) {
-        setActiveChannel(activeChannel)
-        replaceMessages(messages, for: activeChannel)
-    }
-
-    func messages(for conversationID: ConversationID) -> [BitchatMessage] {
-        messagesByConversation[conversationID] ?? []
-    }
-
-    func directMessages(
-        for peerID: PeerID,
-        identityResolver: IdentityResolver
-    ) -> [BitchatMessage] {
-        messages(for: directConversationID(for: peerID, identityResolver: identityResolver))
-    }
-
-    func directMessagesByPeerID() -> [PeerID: [BitchatMessage]] {
-        var messagesByPeerID: [PeerID: [BitchatMessage]] = [:]
-
-        for (conversationID, handle) in directHandlesByConversation {
-            messagesByPeerID[handle.routingPeerID] = messages(for: conversationID)
-        }
-
-        return messagesByPeerID
-    }
-
-    func unreadDirectPeerIDs() -> Set<PeerID> {
-        unreadConversations.reduce(into: Set<PeerID>()) { result, conversationID in
-            guard case .direct(let handle) = conversationID else { return }
-            result.insert(directHandlesByConversation[conversationID]?.routingPeerID ?? handle.routingPeerID)
-        }
-    }
-
-    func synchronizeSelection(
-        activeChannel: ChannelID,
-        selectedPeerID: PeerID?,
-        identityResolver: IdentityResolver
-    ) {
-        setSelectedPeerID(
-            selectedPeerID,
-            activeChannel: activeChannel,
-            identityResolver: identityResolver
-        )
-    }
-
-    func synchronizePrivateChats(
-        _ privateChats: [PeerID: [BitchatMessage]],
-        unreadPeerIDs: Set<PeerID>,
-        identityResolver: IdentityResolver
-    ) {
-        var liveConversations = Set<ConversationID>()
-
-        for (peerID, messages) in privateChats {
-            let handle = identityResolver.canonicalHandle(for: peerID, displayName: messages.last?.sender)
-            let conversationID = ConversationID.direct(handle)
-            liveConversations.insert(conversationID)
-            directHandlesByConversation[conversationID] = handle
-            messagesByConversation[conversationID] = normalized(messages)
-        }
-
-        let staleDirectConversations = messagesByConversation.keys.filter { conversationID in
-            guard case .direct = conversationID else { return false }
-            return !liveConversations.contains(conversationID)
-        }
-
-        for conversationID in staleDirectConversations {
-            messagesByConversation.removeValue(forKey: conversationID)
-            unreadConversations.remove(conversationID)
-            directHandlesByConversation.removeValue(forKey: conversationID)
-        }
-
-        let publicUnread = unreadConversations.filter { conversationID in
-            switch conversationID {
-            case .mesh, .geohash:
-                return true
-            case .direct:
-                return false
-            }
-        }
-
-        unreadConversations = unreadPeerIDs.reduce(into: publicUnread) { result, peerID in
-            let handle = identityResolver.canonicalHandle(for: peerID)
-            result.insert(.direct(handle))
-        }
-    }
-
-    func markRead(_ conversationID: ConversationID) {
-        unreadConversations.remove(conversationID)
-    }
-
-    func markRead(
-        peerID: PeerID,
-        identityResolver: IdentityResolver
-    ) {
-        markRead(directConversationID(for: peerID, identityResolver: identityResolver))
-    }
-
-    private func normalized(_ messages: [BitchatMessage]) -> [BitchatMessage] {
-        var uniqueMessages: [String: BitchatMessage] = [:]
-
-        for message in messages {
-            uniqueMessages[message.id] = message
-        }
-
-        return uniqueMessages.values.sorted { lhs, rhs in
-            if lhs.timestamp != rhs.timestamp {
-                return lhs.timestamp < rhs.timestamp
-            }
-            return lhs.id < rhs.id
-        }
-    }
-
-    private func directConversationID(
-        for peerID: PeerID,
-        identityResolver: IdentityResolver
-    ) -> ConversationID {
-        let handle = identityResolver.canonicalHandle(for: peerID)
-        let conversationID = ConversationID.direct(handle)
-        directHandlesByConversation[conversationID] = handle
-        return conversationID
-    }
-}

bitchat/App/AppChromeModel.swift

@@ -10,6 +10,10 @@ final class AppChromeModel: ObservableObject {
     @Published var showingFingerprintFor: PeerID?
     @Published var isAppInfoPresented = false
     @Published var isLocationChannelsSheetPresented = false
+    @Published var isNoticesSheetPresented = false
+    /// When the sheet is opened for "notes left here" (empty mesh timeline),
+    /// it should land on the geo tab instead of the channel-derived default.
+    @Published var noticesSheetPrefersGeoTab = false
     @Published var showBluetoothAlert = false
     @Published var bluetoothAlertMessage = ""
     @Published var bluetoothState: CBManagerState = .unknown
@@ -18,6 +22,9 @@ final class AppChromeModel: ObservableObject {
     private let chatViewModel: ChatViewModel
     private var cancellables = Set<AnyCancellable>()
 
+    /// Bulletin-board coordinator, created on first use of the board sheet.
+    private(set) lazy var boardManager = BoardManager(transport: chatViewModel.meshService)
+
     init(chatViewModel: ChatViewModel, privateInboxModel: PrivateInboxModel) {
         self.chatViewModel = chatViewModel
         self.nickname = chatViewModel.nickname
@@ -59,6 +66,33 @@ final class AppChromeModel: ObservableObject {
         isAppInfoPresented = true
     }
 
+    func presentNotices(geoTab: Bool = false) {
+        noticesSheetPrefersGeoTab = geoTab
+        isNoticesSheetPresented = true
+    }
+
+    /// Builds the mesh topology map model from the transport's gossiped
+    /// graph plus the live nickname table. Unknown nodes (heard about via a
+    /// neighbor claim but never announced to us) fall back to a short ID.
+    func meshTopologyDisplayModel() -> MeshTopologyDisplayModel {
+        let mesh = chatViewModel.meshService
+        guard let snapshot = mesh.currentMeshTopology() else { return .empty }
+        let nicknames = mesh.getPeerNicknames()
+
+        let nodes = snapshot.nodes.map { peerID -> MeshTopologyDisplayModel.Node in
+            let isSelf = peerID == snapshot.localPeerID
+            let label: String
+            if isSelf {
+                label = chatViewModel.nickname
+            } else {
+                label = nicknames[peerID] ?? "\(peerID.id.prefix(8))…"
+            }
+            return MeshTopologyDisplayModel.Node(id: peerID.id, label: label, isSelf: isSelf)
+        }
+        let edges = snapshot.edges.map { ($0.a.id, $0.b.id) }
+        return MeshTopologyDisplayModel(nodes: nodes, edges: edges)
+    }
+
     func triggerScreenshotPrivacyWarning() {
         showScreenshotPrivacyWarning = true
     }

bitchat/App/AppRuntime.swift

@@ -14,9 +14,10 @@ import AppKit
 final class AppRuntime: ObservableObject {
     let chatViewModel: ChatViewModel
     let events = AppEventStream()
-    let conversationStore: ConversationStore
+    /// Single source of truth for conversation message state and selection
-    let peerIdentityStore: PeerIdentityStore
+    /// (docs/CONVERSATION-STORE-DESIGN.md). Owned here; the feature models
-    let locationPresenceStore: LocationPresenceStore
+    /// and `ChatViewModel` observe and mutate it through its intent API.
+    let conversations: ConversationStore
     let publicChatModel: PublicChatModel
     let privateInboxModel: PrivateInboxModel
     let privateConversationModel: PrivateConversationModel
@@ -25,6 +26,7 @@ final class AppRuntime: ObservableObject {
     let locationChannelsModel: LocationChannelsModel
     let peerListModel: PeerListModel
     let appChromeModel: AppChromeModel
+    let boardAlertsModel: BoardAlertsModel
 
     private let idBridge: NostrIdentityBridge
     private var cancellables = Set<AnyCancellable>()
@@ -38,34 +40,30 @@ final class AppRuntime: ObservableObject {
     #endif
 
     init(
-        keychain: KeychainManagerProtocol = KeychainManager(),
+        keychain: KeychainManagerProtocol = KeychainManager.makeDefault(),
         idBridge: NostrIdentityBridge = NostrIdentityBridge()
     ) {
         self.idBridge = idBridge
-        let identityResolver = IdentityResolver()
+        let conversations = ConversationStore()
-        let conversationStore = ConversationStore()
         let peerIdentityStore = PeerIdentityStore()
         let locationPresenceStore = LocationPresenceStore()
         let locationManager = LocationChannelManager.shared
-        self.conversationStore = conversationStore
+        self.conversations = conversations
-        self.peerIdentityStore = peerIdentityStore
-        self.locationPresenceStore = locationPresenceStore
         self.chatViewModel = ChatViewModel(
             keychain: keychain,
             idBridge: idBridge,
             identityManager: SecureIdentityStateManager(keychain),
-            conversationStore: conversationStore,
+            conversations: conversations,
-            identityResolver: identityResolver,
             peerIdentityStore: peerIdentityStore,
             locationPresenceStore: locationPresenceStore,
             locationManager: locationManager
         )
-        self.publicChatModel = PublicChatModel(conversationStore: conversationStore)
+        self.publicChatModel = PublicChatModel(conversations: conversations)
-        self.privateInboxModel = PrivateInboxModel(conversationStore: conversationStore)
+        self.privateInboxModel = PrivateInboxModel(conversations: conversations)
         self.locationChannelsModel = LocationChannelsModel(manager: locationManager)
         self.privateConversationModel = PrivateConversationModel(
             chatViewModel: self.chatViewModel,
-            conversationStore: conversationStore,
+            conversations: conversations,
             locationChannelsModel: self.locationChannelsModel,
             peerIdentityStore: peerIdentityStore
         )
@@ -77,11 +75,11 @@ final class AppRuntime: ObservableObject {
         self.conversationUIModel = ConversationUIModel(
             chatViewModel: self.chatViewModel,
             privateConversationModel: self.privateConversationModel,
-            conversationStore: conversationStore
+            conversations: conversations
         )
         self.peerListModel = PeerListModel(
             chatViewModel: self.chatViewModel,
-            conversationStore: conversationStore,
+            conversations: conversations,
             locationChannelsModel: self.locationChannelsModel,
             peerIdentityStore: peerIdentityStore,
             locationPresenceStore: locationPresenceStore
@@ -90,6 +88,24 @@ final class AppRuntime: ObservableObject {
             chatViewModel: self.chatViewModel,
             privateInboxModel: self.privateInboxModel
         )
+        let chatViewModel = self.chatViewModel
+        self.boardAlertsModel = BoardAlertsModel(
+            arrivals: BoardStore.shared.postArrivals.eraseToAnyPublisher(),
+            wipes: BoardStore.shared.didWipe.eraseToAnyPublisher(),
+            dependencies: BoardAlertsModel.Dependencies(
+                isOwnPost: { post in
+                    let key = chatViewModel.meshService.noiseSigningPublicKeyData()
+                    return !key.isEmpty && key == post.authorSigningKey
+                },
+                emitSystemLine: { content, geohash in
+                    if geohash.isEmpty {
+                        chatViewModel.addMeshOnlySystemMessage(content)
+                    } else {
+                        chatViewModel.addGeohashSystemMessage(content, geohash: geohash)
+                    }
+                }
+            )
+        )
 
         GeoRelayDirectory.shared.prefetchIfNeeded()
         bindRuntimeObservers()
@@ -104,7 +120,7 @@ final class AppRuntime: ObservableObject {
 
         started = true
         NotificationDelegate.shared.runtime = self
-        VerificationService.shared.configure(with: chatViewModel.meshService.getNoiseService())
+        VerificationService.shared.configure(with: chatViewModel.meshService)
         announceInitialTorStatusIfNeeded()
 
         Task(priority: .utility) { [weak self] in
@@ -201,7 +217,16 @@ final class AppRuntime: ObservableObject {
         chatViewModel.applicationWillTerminate()
     }
 
-    func handleNotificationResponse(identifier: String, userInfo: [AnyHashable: Any]) {
+    func handleNotificationResponse(
+        identifier: String,
+        actionIdentifier: String = UNNotificationDefaultActionIdentifier,
+        userInfo: [AnyHashable: Any]
+    ) {
+        if actionIdentifier == NotificationService.waveActionID {
+            chatViewModel.sendMeshWave()
+            return
+        }
+
         if identifier.hasPrefix("private-"), let peerID = PeerID(str: userInfo["peerID"] as? String) {
             record(.notificationOpened(peerID: peerID))
             chatViewModel.startPrivateChat(with: peerID)
@@ -218,7 +243,7 @@ final class AppRuntime: ObservableObject {
         userInfo: [AnyHashable: Any]
     ) async -> UNNotificationPresentationOptions {
         if identifier.hasPrefix("private-"), let peerID = PeerID(str: userInfo["peerID"] as? String) {
-            if conversationStore.selectedPrivatePeerID == peerID {
+            if conversations.selectedPrivatePeerID == peerID {
                 return []
             }
             return [.banner, .sound]
@@ -288,21 +313,29 @@ private extension AppRuntime {
     }
 
     func checkForSharedContent() {
-        guard let userDefaults = UserDefaults(suiteName: BitchatApp.groupID),
+        guard let userDefaults = UserDefaults(suiteName: BitchatApp.groupID) else { return }
-              let sharedContent = userDefaults.string(forKey: "sharedContent"),
+        let clearSharedContent = {
+            userDefaults.removeObject(forKey: "sharedContent")
+            userDefaults.removeObject(forKey: "sharedContentType")
+            userDefaults.removeObject(forKey: "sharedContentDate")
+        }
+
+        guard let sharedContent = userDefaults.string(forKey: "sharedContent"),
               let sharedDate = userDefaults.object(forKey: "sharedContentDate") as? Date else {
+            // A partial or malformed handoff must not linger in the shared
+            // app-group container indefinitely.
+            clearSharedContent()
             return
         }
 
         guard Date().timeIntervalSince(sharedDate) < TransportConfig.uiShareAcceptWindowSeconds else {
+            clearSharedContent()
             return
         }
 
         let contentKind = SharedContentKind(rawValue: userDefaults.string(forKey: "sharedContentType") ?? "") ?? .text
 
-        userDefaults.removeObject(forKey: "sharedContent")
+        clearSharedContent()
-        userDefaults.removeObject(forKey: "sharedContentType")
-        userDefaults.removeObject(forKey: "sharedContentDate")
 
         switch contentKind {
         case .url:

bitchat/App/ConversationStore.swift

@@ -0,0 +1,941 @@
+//
+// ConversationStore.swift
+// bitchat
+//
+// Single source of truth for conversation message state (see
+// docs/CONVERSATION-STORE-DESIGN.md). One `Conversation` object per
+// `ConversationID`; all mutations flow through the store's intent API and
+// every mutation emits a `ConversationChange` after state is consistent.
+//
+// The store also owns conversation selection: the active public channel and
+// the selected private peer (the two UI selection axes) plus the derived
+// `selectedConversationID`.
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import BitFoundation
+import BitLogger
+import Combine
+import Foundation
+
+// MARK: - Conversation
+
+/// A single conversation timeline (`.mesh`, `.geohash`, or `.direct`).
+///
+/// Publishing granularity is per conversation: views observe ONE
+/// `Conversation` object, so an append to chat A never invalidates observers
+/// of chat B.
+///
+/// Mutations are `fileprivate` by design — only `ConversationStore`'s intent
+/// API may mutate a conversation, keeping the store the sole writer.
+@MainActor
+final class Conversation: ObservableObject, Identifiable {
+    let id: ConversationID
+    /// Maximum retained messages; oldest are trimmed on overflow.
+    let cap: Int
+
+    @Published private(set) var messages: [BitchatMessage] = []
+    @Published private(set) var isUnread: Bool = false
+
+    /// Incrementally-maintained message-ID → logical-index map for O(1)
+    /// dedup and delivery-status lookup. Logical indexes are physical array
+    /// indexes plus `indexOffset`; trimming from the head advances the offset
+    /// instead of rewriting every surviving dictionary entry. This matters
+    /// after the 1337-message cap is reached, when every steady-state tail
+    /// append evicts one old row.
+    ///
+    /// Out-of-order inserts and middle removals still reindex only the
+    /// affected suffix. Full filtering resets the offset while rebuilding.
+    private var indexByMessageID: [String: Int] = [:]
+    private var indexOffset = 0
+
+    fileprivate init(id: ConversationID, cap: Int) {
+        self.id = id
+        self.cap = max(1, cap)
+    }
+
+    // MARK: Reads
+
+    func containsMessage(withID messageID: String) -> Bool {
+        indexByMessageID[messageID] != nil
+    }
+
+    func message(withID messageID: String) -> BitchatMessage? {
+        guard let index = physicalIndex(forMessageID: messageID) else { return nil }
+        return messages[index]
+    }
+
+    /// All message IDs currently in this conversation (unordered).
+    var messageIDs: Dictionary<String, Int>.Keys {
+        indexByMessageID.keys
+    }
+
+    // MARK: Store-internal mutations
+
+    /// Result of an ordered insert. `trimmedMessageIDs` reports messages
+    /// evicted by the cap so the store can keep its message-ID →
+    /// conversation map exact.
+    fileprivate struct InsertResult {
+        let inserted: Bool
+        let trimmedMessageIDs: [String]
+
+        static let duplicate = InsertResult(inserted: false, trimmedMessageIDs: [])
+    }
+
+    fileprivate enum UpsertOutcome {
+        case appended(trimmedMessageIDs: [String])
+        case updated
+    }
+
+    /// Inserts a message in timestamp order, deduplicating by message ID.
+    /// Fast path appends when the timestamp is >= the current tail;
+    /// otherwise a binary search finds the upper-bound insertion point so
+    /// arrival order is preserved among equal timestamps.
+    /// Reports `inserted: false` if a message with the same ID already exists.
+    fileprivate func insert(_ message: BitchatMessage) -> InsertResult {
+        guard indexByMessageID[message.id] == nil else { return .duplicate }
+
+        if let last = messages.last, message.timestamp < last.timestamp {
+            let index = insertionIndex(for: message.timestamp)
+            messages.insert(message, at: index)
+            reindex(from: index)
+        } else {
+            messages.append(message)
+            indexByMessageID[message.id] = indexOffset + messages.count - 1
+        }
+
+        return InsertResult(inserted: true, trimmedMessageIDs: trimIfNeeded())
+    }
+
+    /// Replace-or-append by message ID. An existing message keeps its
+    /// timeline position (in-place updates like media progress reuse the
+    /// original timestamp); a new message goes through ordered insertion.
+    fileprivate func upsert(_ message: BitchatMessage) -> UpsertOutcome {
+        if let index = physicalIndex(forMessageID: message.id) {
+            messages[index] = message
+            return .updated
+        }
+        let result = insert(message)
+        return .appended(trimmedMessageIDs: result.trimmedMessageIDs)
+    }
+
+    /// Applies a delivery status keyed by message ID, honoring the
+    /// no-downgrade rule (the SOLE enforcement point — every delivery
+    /// update flows through the store): equal statuses are skipped, and
+    /// `.read` is never downgraded to `.delivered` or `.sent`.
+    /// Returns `true` when the status was applied.
+    fileprivate func applyDeliveryStatus(_ status: DeliveryStatus, forMessageID messageID: String) -> Bool {
+        guard let index = physicalIndex(forMessageID: messageID) else { return false }
+        let message = messages[index]
+        guard !Self.shouldSkipStatusUpdate(current: message.deliveryStatus, new: status) else { return false }
+
+        message.deliveryStatus = status
+        // BitchatMessage is a reference type; write back through the
+        // subscript so the @Published wrapper emits.
+        messages[index] = message
+        return true
+    }
+
+    /// Republishes a message without changing state. Used for mirrored
+    /// copies that share a BitchatMessage instance: the first conversation's
+    /// status apply mutated the shared object, so this conversation's
+    /// observers still need an @Published emission to re-render.
+    @discardableResult
+    fileprivate func republishMessage(withID messageID: String) -> Bool {
+        guard let index = physicalIndex(forMessageID: messageID) else { return false }
+        messages[index] = messages[index]
+        return true
+    }
+
+    @discardableResult
+    fileprivate func setUnread(_ unread: Bool) -> Bool {
+        guard isUnread != unread else { return false }
+        isUnread = unread
+        return true
+    }
+
+    /// Removes a single message by ID. Returns the removed message, or
+    /// `nil` when no message with that ID exists.
+    fileprivate func remove(messageID: String) -> BitchatMessage? {
+        guard let index = physicalIndex(forMessageID: messageID) else { return nil }
+        let removed = messages.remove(at: index)
+        indexByMessageID.removeValue(forKey: messageID)
+        if index == 0 {
+            indexOffset += 1
+        } else {
+            reindex(from: index)
+        }
+        return removed
+    }
+
+    /// Removes every message matching `predicate`. Returns the removed
+    /// message IDs (empty when nothing matched).
+    fileprivate func removeAll(where predicate: (BitchatMessage) -> Bool) -> [String] {
+        var removedIDs: [String] = []
+        messages.removeAll { message in
+            guard predicate(message) else { return false }
+            removedIDs.append(message.id)
+            return true
+        }
+        guard !removedIDs.isEmpty else { return [] }
+        for id in removedIDs {
+            indexByMessageID.removeValue(forKey: id)
+        }
+        indexOffset = 0
+        reindex(from: 0)
+        return removedIDs
+    }
+
+    fileprivate func clearMessages() {
+        messages.removeAll()
+        indexByMessageID.removeAll()
+        indexOffset = 0
+    }
+
+    // MARK: Diagnostics
+
+    /// Appends human-readable invariant violations for this conversation
+    /// (empty when healthy): the ID index must be the exact inverse of the
+    /// messages array, the cap must hold, and timestamps must be
+    /// non-decreasing (equal timestamps keep arrival order, so only strict
+    /// inversions are violations). O(messages); allocates only on violation.
+    fileprivate func collectInvariantViolations(into violations: inout [String], label: String) {
+        if indexByMessageID.count != messages.count {
+            violations.append("\(label): index has \(indexByMessageID.count) entries for \(messages.count) messages")
+        }
+        if messages.count > cap {
+            violations.append("\(label): \(messages.count) messages exceeds cap \(cap)")
+        }
+        var previousTimestamp: Date?
+        for position in messages.indices {
+            let message = messages[position]
+            // Count equality + every message resolving to its own position
+            // proves the index is exactly the inverse map (no stale extras).
+            if let logicalIndex = indexByMessageID[message.id] {
+                let expectedIndex = indexOffset + position
+                if logicalIndex != expectedIndex {
+                    violations.append("\(label): message \(message.id.prefix(8))… at \(position) indexed at \(logicalIndex - indexOffset)")
+                }
+            } else {
+                violations.append("\(label): message \(message.id.prefix(8))… at \(position) missing from index")
+            }
+            if let previousTimestamp, message.timestamp < previousTimestamp {
+                violations.append("\(label): timestamp order violated at \(position)")
+            }
+            previousTimestamp = message.timestamp
+        }
+    }
+
+    // MARK: Internals
+
+    static func shouldSkipStatusUpdate(current: DeliveryStatus?, new: DeliveryStatus) -> Bool {
+        guard let current else { return false }
+        if current == new { return true }
+
+        // Never downgrade to a weaker delivery state. Ordering of certainty:
+        // sending < sent < carried < delivered < read. A late `.sent` write
+        // (e.g. the optimistic stamp after routing) must not clobber the
+        // `.carried` the router already set when it handed a copy to a
+        // courier/bridge, nor a `.delivered`/`.read` ack. A late asynchronous
+        // failure is weaker than a confirmed recipient receipt too, so it may
+        // not replace `.delivered`/`.read`. Same for the
+        // `.sending` stamp a pre-handshake resend emits asynchronously: it
+        // can land after the message already reached `.sent`, and "Sent" was
+        // already truthful. (`.failed` → `.sending` stays allowed so a real
+        // failure retry is visible.)
+        switch (current, new) {
+        case (.read, .delivered), (.read, .carried), (.read, .sent), (.read, .sending), (.read, .failed):
+            return true
+        case (.delivered, .carried), (.delivered, .sent), (.delivered, .sending), (.delivered, .failed):
+            return true
+        case (.carried, .sent), (.carried, .sending):
+            return true
+        case (.sent, .sending):
+            return true
+        default:
+            return false
+        }
+    }
+
+    /// Upper-bound binary search: first index whose timestamp is strictly
+    /// greater than `timestamp`, so equal-timestamp messages keep arrival
+    /// order.
+    private func insertionIndex(for timestamp: Date) -> Int {
+        var low = 0
+        var high = messages.count
+        while low < high {
+            let mid = (low + high) / 2
+            if messages[mid].timestamp <= timestamp {
+                low = mid + 1
+            } else {
+                high = mid
+            }
+        }
+        return low
+    }
+
+    private func reindex(from start: Int) {
+        for index in start..<messages.count {
+            indexByMessageID[messages[index].id] = indexOffset + index
+        }
+    }
+
+    private func physicalIndex(forMessageID messageID: String) -> Int? {
+        guard let logicalIndex = indexByMessageID[messageID] else { return nil }
+        let index = logicalIndex - indexOffset
+        guard messages.indices.contains(index) else { return nil }
+        return index
+    }
+
+    /// Trims oldest messages over the cap; returns the trimmed message IDs.
+    private func trimIfNeeded() -> [String] {
+        guard messages.count > cap else { return [] }
+        let overflow = messages.count - cap
+        let trimmedIDs = messages.prefix(overflow).map(\.id)
+        for id in trimmedIDs {
+            indexByMessageID.removeValue(forKey: id)
+        }
+        messages.removeFirst(overflow)
+        indexOffset += overflow
+        return trimmedIDs
+    }
+}
+
+// MARK: - ConversationChange
+
+/// Typed mutation events for non-UI consumers (delivery tracking,
+/// notifications, sync) that need "something changed in conversation X"
+/// without subscribing to whole message arrays. Emitted on the store's
+/// `changes` subject AFTER the corresponding state is consistent.
+enum ConversationChange {
+    case appended(ConversationID, BitchatMessage)
+    case updated(ConversationID, messageID: String)
+    case statusChanged(ConversationID, messageID: String, DeliveryStatus)
+    case messageRemoved(ConversationID, messageID: String)
+    case cleared(ConversationID)
+    case removed(ConversationID)
+    case migrated(from: ConversationID, to: ConversationID)
+    case unreadChanged(ConversationID, isUnread: Bool)
+}
+
+// MARK: - ConversationStore
+
+/// Sole writer and sole holder of conversation message state. All mutations
+/// go through the intent API below; backing collections are `private(set)`.
+/// Reads are synchronous — writers and readers share the main actor, so
+/// after an intent returns every observer sees the result.
+@MainActor
+final class ConversationStore: ObservableObject {
+    /// Conversation creation order; published so list-style consumers can
+    /// observe conversations appearing/disappearing without rebuilding from
+    /// the dictionary.
+    @Published private(set) var conversationIDs: [ConversationID] = []
+    @Published private(set) var selectedConversationID: ConversationID?
+    @Published private(set) var unreadConversations: Set<ConversationID> = []
+
+    // MARK: Selection state
+    // The two UI selection axes: which public channel is active, and which
+    // private chat (if any) is open on top of it. `selectedConversationID`
+    // is derived: the open private chat wins, otherwise the active public
+    // channel's conversation. Mutate via `setActiveChannel` /
+    // `setSelectedPrivatePeer` only.
+
+    @Published private(set) var activeChannel: ChannelID = .mesh
+    @Published private(set) var selectedPrivatePeerID: PeerID?
+
+    private(set) var conversationsByID: [ConversationID: Conversation] = [:]
+
+    /// Store-level message-ID → conversation-membership map for ID-only
+    /// lookups (delivery receipts arrive with a message ID, not a
+    /// conversation). Maintained incrementally at every mutation point —
+    /// all mutation is centralized in the intent API below, so the map is
+    /// exact, never scanned or rebuilt.
+    ///
+    /// The value is a `Set` because a private message can legitimately live
+    /// in TWO direct conversations: step 2's raw per-peer keying mirrors a
+    /// message into both the stable-key and ephemeral-peer chats
+    /// (`mirrorToEphemeralIfNeeded`). A delivery update must reach both
+    /// copies.
+    private var conversationIDsByMessageID: [String: Set<ConversationID>] = [:]
+
+    /// Monotonic count of messages inserted into any conversation (appends,
+    /// upsert-appends, migration inserts). Field-observability only: the
+    /// periodic store audit folds the delta into its heartbeat line so logs
+    /// carry throughput context. Never read on a hot path.
+    private(set) var appendCount: Int = 0
+
+    /// Sample counter for the mirrored-republish debug log in the ID-only
+    /// `setDeliveryStatus` fan-out (first + every Nth occurrence).
+    private var mirroredRepublishLogCount = 0
+
+    let changes = PassthroughSubject<ConversationChange, Never>()
+
+    // MARK: Intent API
+
+    /// Returns the conversation for `id`, creating it (with the cap policy
+    /// for its kind) on first access.
+    @discardableResult
+    func conversation(for id: ConversationID) -> Conversation {
+        if let existing = conversationsByID[id] {
+            return existing
+        }
+        let conversation = Conversation(id: id, cap: Self.cap(for: id))
+        conversationsByID[id] = conversation
+        conversationIDs.append(id)
+        return conversation
+    }
+
+    /// Appends a message in timestamp order. Returns `false` (and emits
+    /// nothing) if a message with the same ID is already present.
+    @discardableResult
+    func append(_ message: BitchatMessage, to id: ConversationID) -> Bool {
+        let conversation = conversation(for: id)
+        let result = conversation.insert(message)
+        guard result.inserted else { return false }
+        registerMessageID(message.id, in: id)
+        unregisterMessageIDs(result.trimmedMessageIDs, from: id)
+        changes.send(.appended(id, message))
+        return true
+    }
+
+    /// Replace-or-append by message ID (media progress, edits).
+    func upsertByID(_ message: BitchatMessage, in id: ConversationID) {
+        let conversation = conversation(for: id)
+        switch conversation.upsert(message) {
+        case .appended(let trimmedMessageIDs):
+            registerMessageID(message.id, in: id)
+            unregisterMessageIDs(trimmedMessageIDs, from: id)
+            changes.send(.appended(id, message))
+        case .updated:
+            changes.send(.updated(id, messageID: message.id))
+        }
+    }
+
+    /// Applies a delivery status keyed by message ID. Returns `false` when
+    /// the message is unknown or the update would downgrade the status
+    /// (read beats delivered beats sent).
+    @discardableResult
+    func setDeliveryStatus(_ status: DeliveryStatus, forMessageID messageID: String, in id: ConversationID) -> Bool {
+        guard let conversation = conversationsByID[id],
+              conversation.applyDeliveryStatus(status, forMessageID: messageID) else {
+            return false
+        }
+        changes.send(.statusChanged(id, messageID: messageID, status))
+        return true
+    }
+
+    /// Applies a delivery status to EVERY conversation containing
+    /// `messageID` (ID-only — delivery receipts don't know conversations;
+    /// mirrored private copies live in two direct chats). Returns `false`
+    /// when the message is unknown or no copy changed (equal status or
+    /// downgrade — read beats delivered beats sent).
+    ///
+    /// `BitchatMessage` is a reference type, so mirrored copies sharing one
+    /// instance are mutated by the first conversation's apply. The skipped
+    /// conversations still hold the changed message, so they get an explicit
+    /// republish and `.statusChanged` event - otherwise a view observing the
+    /// mirrored conversation would render stale status. Distinct copies whose
+    /// update was genuinely rejected (downgrade) are left untouched, guarded
+    /// by status equality.
+    @discardableResult
+    func setDeliveryStatus(_ status: DeliveryStatus, forMessageID messageID: String) -> Bool {
+        guard let ids = conversationIDsByMessageID[messageID] else { return false }
+        var applied = false
+        var skipped: [ConversationID] = []
+        for id in ids {
+            if setDeliveryStatus(status, forMessageID: messageID, in: id) {
+                applied = true
+            } else {
+                skipped.append(id)
+            }
+        }
+        guard applied else { return false }
+        for id in skipped {
+            guard let conversation = conversationsByID[id],
+                  conversation.message(withID: messageID)?.deliveryStatus == status,
+                  conversation.republishMessage(withID: messageID) else { continue }
+            // Field proof the mirrored-copy republish path actually fires;
+            // sampled (first + every Nth) so mirrored chats can't spam logs.
+            mirroredRepublishLogCount += 1
+            if mirroredRepublishLogCount == 1
+                || mirroredRepublishLogCount.isMultiple(of: TransportConfig.conversationStoreMirroredRepublishLogInterval) {
+                SecureLogger.debug(
+                    "mirrored republish #\(mirroredRepublishLogCount) for \(messageID.prefix(8))… in \(id.auditDescription)",
+                    category: .session
+                )
+            }
+            changes.send(.statusChanged(id, messageID: messageID, status))
+        }
+        return true
+    }
+
+    /// Current delivery status of `messageID` in whichever conversation
+    /// holds it (mirrored copies share status — see `setDeliveryStatus`).
+    func deliveryStatus(forMessageID messageID: String) -> DeliveryStatus? {
+        guard let ids = conversationIDsByMessageID[messageID] else { return nil }
+        for id in ids {
+            if let status = conversationsByID[id]?.message(withID: messageID)?.deliveryStatus {
+                return status
+            }
+        }
+        return nil
+    }
+
+    /// Every conversation currently containing `messageID` (empty when the
+    /// message is unknown).
+    func conversationIDs(forMessageID messageID: String) -> Set<ConversationID> {
+        conversationIDsByMessageID[messageID] ?? []
+    }
+
+    func markRead(_ id: ConversationID) {
+        guard unreadConversations.contains(id) else { return }
+        unreadConversations.remove(id)
+        conversationsByID[id]?.setUnread(false)
+        changes.send(.unreadChanged(id, isUnread: false))
+    }
+
+    func markUnread(_ id: ConversationID) {
+        guard !unreadConversations.contains(id) else { return }
+        let conversation = conversation(for: id)
+        unreadConversations.insert(id)
+        conversation.setUnread(true)
+        changes.send(.unreadChanged(id, isUnread: true))
+    }
+
+    /// Selects a conversation (creating it if needed) or clears the
+    /// selection with `nil`.
+    func select(_ id: ConversationID?) {
+        if let id {
+            conversation(for: id)
+        }
+        guard selectedConversationID != id else { return }
+        selectedConversationID = id
+    }
+
+    /// Switches the active public channel. While no private chat is open
+    /// the selection follows the channel.
+    func setActiveChannel(_ channelID: ChannelID) {
+        if activeChannel != channelID {
+            activeChannel = channelID
+        }
+        refreshDerivedSelection()
+    }
+
+    /// Opens a private chat (`nil` closes it, returning the selection to the
+    /// active public channel's conversation).
+    func setSelectedPrivatePeer(_ peerID: PeerID?) {
+        if selectedPrivatePeerID != peerID {
+            selectedPrivatePeerID = peerID
+        }
+        refreshDerivedSelection()
+    }
+
+    private func refreshDerivedSelection() {
+        if let peerID = selectedPrivatePeerID {
+            select(.directPeer(peerID))
+        } else {
+            select(ConversationID(channelID: activeChannel))
+        }
+    }
+
+    /// Moves all messages from `source` into `destination` (the
+    /// ephemeral↔stable peer-ID handoff): dedups by message ID, preserves
+    /// timestamp order, carries unread state over, and hands off the
+    /// selection — mirroring `ChatPrivateConversationCoordinator`'s
+    /// migration semantics. The source conversation is removed. Emits a
+    /// single `.migrated(from:to:)` once the whole move is consistent.
+    func migrateConversation(from source: ConversationID, to destination: ConversationID) {
+        guard source != destination, let sourceConversation = conversationsByID[source] else { return }
+
+        let destinationConversation = conversation(for: destination)
+        for message in sourceConversation.messages {
+            let result = destinationConversation.insert(message)
+            guard result.inserted else { continue }
+            registerMessageID(message.id, in: destination)
+            unregisterMessageIDs(result.trimmedMessageIDs, from: destination)
+        }
+        for messageID in sourceConversation.messageIDs {
+            unregisterMessageID(messageID, from: source)
+        }
+
+        let wasUnread = unreadConversations.contains(source)
+        let wasSelected = selectedConversationID == source
+
+        conversationsByID.removeValue(forKey: source)
+        conversationIDs.removeAll { $0 == source }
+        unreadConversations.remove(source)
+
+        if wasUnread, !unreadConversations.contains(destination) {
+            unreadConversations.insert(destination)
+            destinationConversation.setUnread(true)
+        }
+        if wasSelected {
+            selectedConversationID = destination
+            // Keep the private-peer selection axis consistent with the
+            // handed-off selection.
+            if let peerID = selectedPrivatePeerID,
+               source == .directPeer(peerID),
+               case .direct(let destinationHandle) = destination {
+                selectedPrivatePeerID = destinationHandle.routingPeerID
+            }
+        }
+
+        changes.send(.migrated(from: source, to: destination))
+    }
+
+    /// Removes a single message by ID from a conversation. Returns the
+    /// removed message, or `nil` (emitting nothing) when the conversation or
+    /// message is unknown.
+    @discardableResult
+    func removeMessage(withID messageID: String, from id: ConversationID) -> BitchatMessage? {
+        guard let conversation = conversationsByID[id],
+              let removed = conversation.remove(messageID: messageID) else {
+            return nil
+        }
+        unregisterMessageID(messageID, from: id)
+        changes.send(.messageRemoved(id, messageID: messageID))
+        return removed
+    }
+
+    /// Removes every message matching `predicate` from a conversation,
+    /// emitting one `.messageRemoved` per removed message after the
+    /// conversation is consistent. No-op for unknown conversations.
+    func removeMessages(from id: ConversationID, where predicate: (BitchatMessage) -> Bool) {
+        guard let conversation = conversationsByID[id] else { return }
+        let removedIDs = conversation.removeAll(where: predicate)
+        unregisterMessageIDs(removedIDs, from: id)
+        for messageID in removedIDs {
+            changes.send(.messageRemoved(id, messageID: messageID))
+        }
+    }
+
+    /// Empties a conversation's timeline but keeps the conversation (and
+    /// its unread/selection state) alive.
+    func clear(_ id: ConversationID) {
+        guard let conversation = conversationsByID[id] else { return }
+        for messageID in conversation.messageIDs {
+            unregisterMessageID(messageID, from: id)
+        }
+        conversation.clearMessages()
+        changes.send(.cleared(id))
+    }
+
+    /// Removes a conversation entirely, including unread state; clears the
+    /// selection if it pointed at the removed conversation.
+    func removeConversation(_ id: ConversationID) {
+        guard let conversation = conversationsByID.removeValue(forKey: id) else { return }
+        for messageID in conversation.messageIDs {
+            unregisterMessageID(messageID, from: id)
+        }
+        conversationIDs.removeAll { $0 == id }
+        unreadConversations.remove(id)
+        if selectedConversationID == id {
+            selectedConversationID = nil
+        }
+        changes.send(.removed(id))
+    }
+
+    func clearAll() {
+        let removedIDs = conversationIDs
+        guard !removedIDs.isEmpty || selectedConversationID != nil else { return }
+
+        conversationsByID.removeAll()
+        conversationIDs.removeAll()
+        unreadConversations.removeAll()
+        conversationIDsByMessageID.removeAll()
+        if selectedConversationID != nil {
+            selectedConversationID = nil
+        }
+
+        for id in removedIDs {
+            changes.send(.removed(id))
+        }
+    }
+
+    // MARK: Diagnostics
+
+    /// Total messages across all conversations. O(#conversations) — heartbeat
+    /// logging only, never a hot path.
+    var totalMessageCount: Int {
+        conversationsByID.values.reduce(0) { $0 + $1.messages.count }
+    }
+
+    /// Number of distinct message IDs in the store-level membership map.
+    var messageIDMapCount: Int {
+        conversationIDsByMessageID.count
+    }
+
+    /// Verifies the store's correctness invariants and returns human-readable
+    /// violations (empty = healthy). Intended for a periodic field audit:
+    /// O(total messages) and allocation-free while healthy. Checks:
+    /// - the `conversationIDs` ordering array matches `conversationsByID`
+    /// - per conversation: ID index exact, cap held, timestamp order
+    ///   (see `Conversation.collectInvariantViolations`)
+    /// - the message-ID → conversation map matches reality exactly: every
+    ///   mapped membership points at a live conversation actually holding
+    ///   the message, and total memberships equal total messages (with the
+    ///   forward check, equality proves no conversation message is missing
+    ///   from the map)
+    /// - `unreadConversations` only references existing conversations
+    /// - `selectedConversationID`, when set, references an existing
+    ///   conversation (`select(_:)` creates on selection and
+    ///   `removeConversation`/`clearAll` clear it, so existence is the
+    ///   invariant for both the channel-derived and direct-peer cases)
+    func auditInvariants() -> [String] {
+        var violations: [String] = []
+
+        if conversationIDs.count != conversationsByID.count {
+            violations.append("conversationIDs lists \(conversationIDs.count) conversations but dictionary holds \(conversationsByID.count)")
+        }
+        for id in conversationIDs where conversationsByID[id] == nil {
+            violations.append("conversationIDs lists \(id.auditDescription) but no conversation exists")
+        }
+
+        var totalMessages = 0
+        for (id, conversation) in conversationsByID {
+            totalMessages += conversation.messages.count
+            conversation.collectInvariantViolations(into: &violations, label: id.auditDescription)
+        }
+
+        var totalMappedMemberships = 0
+        for (messageID, ids) in conversationIDsByMessageID {
+            totalMappedMemberships += ids.count
+            if ids.isEmpty {
+                violations.append("message map: \(messageID.prefix(8))… has an empty membership set")
+            }
+            for id in ids {
+                guard let conversation = conversationsByID[id] else {
+                    violations.append("message map: \(messageID.prefix(8))… claims unknown conversation \(id.auditDescription)")
+                    continue
+                }
+                if !conversation.containsMessage(withID: messageID) {
+                    violations.append("message map: \(messageID.prefix(8))… not present in claimed conversation \(id.auditDescription)")
+                }
+            }
+        }
+        if totalMappedMemberships != totalMessages {
+            violations.append("message map holds \(totalMappedMemberships) memberships but conversations hold \(totalMessages) messages")
+        }
+
+        for id in unreadConversations where conversationsByID[id] == nil {
+            violations.append("unreadConversations contains unknown conversation \(id.auditDescription)")
+        }
+
+        if let selected = selectedConversationID, conversationsByID[selected] == nil {
+            violations.append("selectedConversationID \(selected.auditDescription) has no conversation")
+        }
+
+        return violations
+    }
+
+    // MARK: Internals
+
+    private func registerMessageID(_ messageID: String, in id: ConversationID) {
+        conversationIDsByMessageID[messageID, default: []].insert(id)
+        // Single choke point for every successful insertion (append, upsert
+        // append, migration insert) — the audit heartbeat's throughput delta.
+        appendCount += 1
+    }
+
+    private func unregisterMessageID(_ messageID: String, from id: ConversationID) {
+        guard var ids = conversationIDsByMessageID[messageID] else { return }
+        ids.remove(id)
+        if ids.isEmpty {
+            conversationIDsByMessageID.removeValue(forKey: messageID)
+        } else {
+            conversationIDsByMessageID[messageID] = ids
+        }
+    }
+
+    private func unregisterMessageIDs(_ messageIDs: [String], from id: ConversationID) {
+        for messageID in messageIDs {
+            unregisterMessageID(messageID, from: id)
+        }
+    }
+
+    private static func cap(for id: ConversationID) -> Int {
+        switch id {
+        case .mesh:
+            return TransportConfig.meshTimelineCap
+        case .geohash:
+            return TransportConfig.geoTimelineCap
+        case .direct:
+            return TransportConfig.privateChatCap
+        }
+    }
+}
+
+// MARK: - Direct-conversation keying + derived views
+
+extension ConversationID {
+    /// Direct-conversation ID keyed by the *raw* routing peer ID.
+    ///
+    /// Direct conversations are deliberately keyed per `PeerID`, not per
+    /// resolved identity: the private-chat coordinators mirror messages into
+    /// both the ephemeral and stable peer's conversations
+    /// (`mirrorToEphemeralIfNeeded`) and consolidate/migrate between them
+    /// explicitly, so a raw lookup by whichever peer ID is selected always
+    /// finds the right timeline without an identity-resolution layer.
+    static func directPeer(_ peerID: PeerID) -> ConversationID {
+        .direct(PeerHandle(id: "peer:\(peerID.id)", routingPeerID: peerID))
+    }
+}
+
+extension ConversationStore {
+    /// All direct conversations' messages keyed by routing peer ID — the
+    /// shape `ChatViewModel.privateChats` exposes to the coordinators.
+    /// Values are the conversations' backing arrays (COW), so building this
+    /// is O(#conversations), not O(#messages).
+    func directMessagesByRoutingPeerID() -> [PeerID: [BitchatMessage]] {
+        var messagesByPeerID: [PeerID: [BitchatMessage]] = [:]
+        messagesByPeerID.reserveCapacity(conversationsByID.count)
+        for (id, conversation) in conversationsByID {
+            guard case .direct(let handle) = id else { continue }
+            messagesByPeerID[handle.routingPeerID] = conversation.messages
+        }
+        return messagesByPeerID
+    }
+
+    /// Unread direct conversations as routing peer IDs — the shape
+    /// `ChatViewModel.unreadPrivateMessages` exposes to the coordinators.
+    func unreadDirectRoutingPeerIDs() -> Set<PeerID> {
+        var peerIDs = Set<PeerID>()
+        for id in unreadConversations {
+            guard case .direct(let handle) = id else { continue }
+            peerIDs.insert(handle.routingPeerID)
+        }
+        return peerIDs
+    }
+
+    /// `true` when any direct conversation contains a message with `messageID`
+    /// (O(1) via the store-level message-ID → conversation map).
+    func directConversationsContainMessage(withID messageID: String) -> Bool {
+        conversationIDs(forMessageID: messageID).contains { id in
+            if case .direct = id { return true }
+            return false
+        }
+    }
+
+    /// Message IDs across all direct conversations (read-receipt pruning
+    /// keeps only receipts whose messages still exist).
+    func directMessageIDs() -> Set<String> {
+        var messageIDs = Set<String>()
+        for (id, conversation) in conversationsByID {
+            guard case .direct = id else { continue }
+            messageIDs.formUnion(conversation.messageIDs)
+        }
+        return messageIDs
+    }
+
+}
+
+// MARK: - Diagnostics support
+
+extension ConversationID {
+    /// Short, log-safe description for audit/diagnostic lines. Direct
+    /// conversations truncate the handle so full peer keys never hit logs.
+    fileprivate var auditDescription: String {
+        switch self {
+        case .mesh:
+            return "mesh"
+        case .geohash(let geohash):
+            return "geo:\(geohash)"
+        case .direct(let handle):
+            return "direct:\(handle.id.prefix(13))…"
+        }
+    }
+}
+
+#if DEBUG
+// Test-only corruption hooks for `auditInvariants()` tests. The store is the
+// sole writer by design — `Conversation`'s mutators are fileprivate and the
+// store's backing collections are private — so the inconsistent states the
+// audit exists to catch CANNOT be manufactured through the intent API. These
+// DEBUG-only hooks deliberately bypass that lockdown to inject exactly those
+// impossible states. Never call them outside tests.
+extension Conversation {
+    /// Points an existing message's index entry at the wrong position
+    /// (positions 0 and 1 swap their index entries). Requires >= 2 messages.
+    func _testCorruptIndexEntries() {
+        guard messages.count >= 2 else { return }
+        indexByMessageID[messages[0].id] = indexOffset + 1
+        indexByMessageID[messages[1].id] = indexOffset
+    }
+
+    /// Drops a message's index entry entirely (count mismatch + missing).
+    func _testRemoveIndexEntry(forMessageID messageID: String) {
+        indexByMessageID.removeValue(forKey: messageID)
+    }
+
+    /// Swaps the first and last messages while keeping the index consistent,
+    /// so ONLY the timestamp-order invariant is violated (requires the two
+    /// messages to have distinct timestamps).
+    func _testCorruptOrderingPreservingIndex() {
+        guard messages.count >= 2 else { return }
+        messages.swapAt(0, messages.count - 1)
+        indexByMessageID[messages[0].id] = indexOffset
+        indexByMessageID[messages[messages.count - 1].id] = indexOffset + messages.count - 1
+    }
+}
+
+extension ConversationStore {
+    /// Adds a map membership that the conversation does not actually hold.
+    func _testRegisterPhantomMessageID(_ messageID: String, in id: ConversationID) {
+        conversationIDsByMessageID[messageID, default: []].insert(id)
+    }
+
+    /// Drops a real map membership (conversation message missing from map).
+    func _testUnregisterMessageID(_ messageID: String, from id: ConversationID) {
+        conversationIDsByMessageID[messageID]?.remove(id)
+        if conversationIDsByMessageID[messageID]?.isEmpty == true {
+            conversationIDsByMessageID.removeValue(forKey: messageID)
+        }
+    }
+
+    /// Appends past the conversation cap, bypassing trim (map kept exact so
+    /// only the cap invariant is violated).
+    func _testAppendBypassingCap(_ message: BitchatMessage, to id: ConversationID) {
+        let conversation = conversation(for: id)
+        conversation._testAppendBypassingTrim(message)
+        conversationIDsByMessageID[message.id, default: []].insert(id)
+    }
+
+    /// Marks a nonexistent conversation unread without creating it.
+    func _testInsertUnreadConversationID(_ id: ConversationID) {
+        unreadConversations.insert(id)
+    }
+
+    /// Sets the selection directly, without `select(_:)`'s create-on-select.
+    func _testSetSelectedConversationID(_ id: ConversationID?) {
+        selectedConversationID = id
+    }
+}
+
+extension Conversation {
+    fileprivate func _testAppendBypassingTrim(_ message: BitchatMessage) {
+        messages.append(message)
+        indexByMessageID[message.id] = indexOffset + messages.count - 1
+    }
+}
+#endif
+
+// MARK: - Public timeline derived views
+
+extension ConversationStore {
+    /// Removes a message by ID from whichever public (mesh/geohash)
+    /// conversation contains it. Returns the removed message, if any.
+    @discardableResult
+    func removePublicMessage(withID messageID: String) -> BitchatMessage? {
+        for id in conversationIDs(forMessageID: messageID) {
+            switch id {
+            case .mesh, .geohash:
+                return removeMessage(withID: messageID, from: id)
+            case .direct:
+                continue
+            }
+        }
+        return nil
+    }
+}

bitchat/App/ConversationUIModel.swift

@@ -12,22 +12,25 @@ final class ConversationUIModel: ObservableObject {
     @Published private(set) var currentNickname: String
     @Published private(set) var isBatchingPublic = false
     @Published private(set) var canSendMediaInCurrentContext = true
+    /// Who is talking live in the public mesh channel right now (floor
+    /// courtesy: the composer mic tints "busy" while someone holds the floor).
+    @Published private(set) var activeLiveVoiceTalker: String?
 
     private let chatViewModel: ChatViewModel
     private let privateConversationModel: PrivateConversationModel
-    private let conversationStore: ConversationStore
+    private let conversations: ConversationStore
     private var activeChannel: ChannelID
     private var cancellables = Set<AnyCancellable>()
 
     init(
         chatViewModel: ChatViewModel,
         privateConversationModel: PrivateConversationModel,
-        conversationStore: ConversationStore
+        conversations: ConversationStore
     ) {
         self.chatViewModel = chatViewModel
         self.privateConversationModel = privateConversationModel
-        self.conversationStore = conversationStore
+        self.conversations = conversations
-        self.activeChannel = conversationStore.activeChannel
+        self.activeChannel = conversations.activeChannel
         self.currentNickname = chatViewModel.nickname
         self.isBatchingPublic = chatViewModel.isBatchingPublic
         self.showAutocomplete = chatViewModel.showAutocomplete
@@ -41,10 +44,22 @@ final class ConversationUIModel: ObservableObject {
         chatViewModel.currentColorScheme = colorScheme
     }
 
+    func setCurrentTheme(_ theme: AppTheme) {
+        chatViewModel.currentTheme = theme
+    }
+
     func sendMessage(_ message: String) {
         chatViewModel.sendMessage(message)
     }
 
+    /// Resends a failed private message through the normal send path,
+    /// removing the failed original so the re-submission replaces it
+    /// instead of stacking a duplicate under the red bubble.
+    func resendFailedPrivateMessage(_ message: BitchatMessage) {
+        chatViewModel.removePrivateMessage(withID: message.id)
+        chatViewModel.sendMessage(message.content)
+    }
+
     func clearCurrentConversation() {
         chatViewModel.sendMessage("/clear")
     }
@@ -63,11 +78,23 @@ final class ConversationUIModel: ObservableObject {
         if let peerID, peerID.isGeoChat,
            let full = chatViewModel.fullNostrHex(forSenderPeerID: peerID) {
             chatViewModel.blockGeohashUser(pubkeyHexLowercased: full, displayName: displayName)
+        } else if let peerID, !peerID.isGeoDM, !peerID.isGeoChat {
+            // Mesh: block the peer's stable Noise identity resolved from the
+            // tapped peerID rather than re-resolving a display-name string.
+            chatViewModel.blockMeshPeer(peerID: peerID, displayName: displayName)
         } else {
             chatViewModel.sendMessage("/block \(displayName)")
         }
     }
 
+    /// Mesh counterpart of `block(peerID:displayName:)`. Resolves the unblock by
+    /// the tapped peer's stable identity so the exact row is unblocked — this
+    /// also works for offline peers, which the `/unblock <displayName>` command
+    /// cannot resolve.
+    func unblock(peerID: PeerID, displayName: String) {
+        chatViewModel.unblockMeshPeer(peerID: peerID, displayName: displayName)
+    }
+
     func updateAutocomplete(for text: String, cursorPosition: Int) {
         chatViewModel.updateAutocomplete(for: text, cursorPosition: cursorPosition)
     }
@@ -76,12 +103,12 @@ final class ConversationUIModel: ObservableObject {
         chatViewModel.completeNickname(nickname, in: &text)
     }
 
-    func formatMessage(_ message: BitchatMessage, colorScheme: ColorScheme) -> AttributedString {
+    func formatMessage(_ message: BitchatMessage, colorScheme: ColorScheme, theme: AppTheme? = nil) -> AttributedString {
-        chatViewModel.formatMessageAsText(message, colorScheme: colorScheme)
+        chatViewModel.formatMessageAsText(message, colorScheme: colorScheme, theme: theme)
     }
 
-    func formatMessageHeader(_ message: BitchatMessage, colorScheme: ColorScheme) -> AttributedString {
+    func formatMessageHeader(_ message: BitchatMessage, colorScheme: ColorScheme, theme: AppTheme? = nil) -> AttributedString {
-        chatViewModel.formatMessageHeader(message, colorScheme: colorScheme)
+        chatViewModel.formatMessageHeader(message, colorScheme: colorScheme, theme: theme)
     }
 
     func mediaAttachment(for message: BitchatMessage) -> BitchatMessage.Media? {
@@ -126,6 +153,17 @@ final class ConversationUIModel: ObservableObject {
         chatViewModel.sendVoiceNote(at: url)
     }
 
+    /// Capture backend for the mic gesture: live PTT when the current DM
+    /// peer can hear it now, classic voice note otherwise.
+    func makeVoiceCaptureSession() -> VoiceCaptureSession {
+        chatViewModel.makeVoiceCaptureSession()
+    }
+
+    /// Whether this message is a live voice burst still streaming in.
+    func isLiveVoiceMessage(_ message: BitchatMessage) -> Bool {
+        chatViewModel.liveVoiceCoordinator.isLiveVoiceMessage(message)
+    }
+
     func cancelMediaSend(messageID: String) {
         chatViewModel.cancelMediaSend(messageID: messageID)
     }
@@ -151,7 +189,11 @@ final class ConversationUIModel: ObservableObject {
             .receive(on: DispatchQueue.main)
             .assign(to: &$isBatchingPublic)
 
-        conversationStore.$activeChannel
+        chatViewModel.$activePublicVoiceTalker
+            .receive(on: DispatchQueue.main)
+            .assign(to: &$activeLiveVoiceTalker)
+
+        conversations.$activeChannel
             .receive(on: DispatchQueue.main)
             .sink { [weak self] channel in
                 self?.activeChannel = channel
@@ -169,7 +211,9 @@ final class ConversationUIModel: ObservableObject {
 
     private func refreshComputedState() {
         if let selectedPeerID = privateConversationModel.selectedPeerID {
-            canSendMediaInCurrentContext = !(selectedPeerID.isGeoDM || selectedPeerID.isGeoChat)
+            // Media transfer is not wired for groups in v1; keep it off so the
+            // composer can't strand a media placeholder that never sends.
+            canSendMediaInCurrentContext = !(selectedPeerID.isGeoDM || selectedPeerID.isGeoChat || selectedPeerID.isGroup)
             return
         }
 

bitchat/App/LocationChannelsModel.swift

@@ -1,4 +1,3 @@
-import BitFoundation
 import Combine
 import Foundation
 
@@ -12,20 +11,25 @@ final class LocationChannelsModel: ObservableObject {
     @Published private(set) var bookmarkNames: [String: String]
     @Published private(set) var locationNames: [GeohashChannelLevel: String]
     @Published private(set) var userTorEnabled: Bool
+    @Published private(set) var gatewayEnabled: Bool
 
     private let manager: LocationChannelManager
     private let network: NetworkActivationService
-    private var cancellables = Set<AnyCancellable>()
+    private let gateway: GatewayService
 
     init(
         manager: LocationChannelManager? = nil,
-        network: NetworkActivationService? = nil
+        network: NetworkActivationService? = nil,
+        gateway: GatewayService? = nil
     ) {
         let manager = manager ?? .shared
         let network = network ?? .shared
+        let gateway = gateway ?? .shared
 
         self.manager = manager
         self.network = network
+        self.gateway = gateway
+        self.gatewayEnabled = gateway.isEnabled
         self.permissionState = manager.permissionState
         self.availableChannels = manager.availableChannels
         self.selectedChannel = manager.selectedChannel
@@ -160,6 +164,10 @@ final class LocationChannelsModel: ObservableObject {
         network.$userTorEnabled
             .receive(on: DispatchQueue.main)
             .assign(to: &$userTorEnabled)
+
+        gateway.$isEnabled
+            .receive(on: DispatchQueue.main)
+            .assign(to: &$gatewayEnabled)
     }
 
     private func level(forLength length: Int) -> GeohashChannelLevel {

bitchat/App/NearbyNotesCounter.swift

@@ -0,0 +1,138 @@
+//
+// NearbyNotesCounter.swift
+// bitchat
+//
+// Counts unexpired location notes left at the user's current building-level
+// geohash so the empty mesh timeline can say "📍 3 notes left here". Only
+// subscribes while a view holds it active, and only when location notes are
+// enabled and location permission is already granted (it never prompts).
+// This is free and unencumbered software released into the public domain.
+//
+
+import Combine
+import Foundation
+
+@MainActor
+final class NearbyNotesCounter: ObservableObject {
+    static let shared = NearbyNotesCounter()
+
+    @Published private(set) var noteCount = 0
+    /// Whether an explicit notes act (the empty-timeline "check for notes"
+    /// tap, opening the notices sheet's geo tab, or a successful /drop) has
+    /// unlocked the counter this session. Until then nothing subscribes:
+    /// merely looking at the mesh timeline must not open a building-precision
+    /// relay REQ that leaks location passively.
+    @Published private(set) var revealed = false
+
+    private var manager: LocationNotesManager?
+    private var managerCancellable: AnyCancellable?
+    private var channelsCancellable: AnyCancellable?
+    private var permissionCancellable: AnyCancellable?
+    private var settingCancellable: AnyCancellable?
+    private var activeHolders = 0
+    private let locationManager: LocationChannelManager
+    private let managerFactory: @MainActor (String) -> LocationNotesManager
+    private let releaseManager: @MainActor (LocationNotesManager?) -> Void
+
+    init(
+        locationManager: LocationChannelManager = .shared,
+        managerFactory: @escaping @MainActor (String) -> LocationNotesManager = { LocationNotesPool.shared.acquire($0) },
+        releaseManager: @escaping @MainActor (LocationNotesManager?) -> Void = { LocationNotesPool.shared.release($0) }
+    ) {
+        self.locationManager = locationManager
+        self.managerFactory = managerFactory
+        self.releaseManager = releaseManager
+    }
+
+    /// Whether the empty-timeline "check for notes" hint should render.
+    /// The permission gate matters: `retarget()` never subscribes without
+    /// location authorization, so offering the hint to an unauthorized
+    /// install would be a silent dead-end — tap, `revealed` flips, the hint
+    /// vanishes, and nothing else happens for the session. The hint never
+    /// prompts; it simply stays hidden until permission exists. The caller
+    /// passes its own observed permission state so the hint re-renders when
+    /// authorization changes.
+    func offersRevealHint(permissionState: LocationChannelManager.PermissionState) -> Bool {
+        !revealed && LocationNotesSettings.enabled && permissionState == .authorized
+    }
+
+    /// Marks the one explicit act that lets the counter subscribe. Sticky for
+    /// the rest of the session (the singleton's lifetime); `deactivate()`
+    /// deliberately does not reset it.
+    func reveal() {
+        guard !revealed else { return }
+        revealed = true
+        retarget()
+    }
+
+    /// Begins (or keeps) the notes subscription for the current building
+    /// geohash. Balanced by `deactivate()`; ref-counted so multiple views can
+    /// hold it.
+    func activate() {
+        activeHolders += 1
+        guard activeHolders == 1 else { return }
+        channelsCancellable = locationManager.$availableChannels
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] _ in self?.retarget() }
+        // CoreLocation can revoke authorization while the view remains
+        // mounted. `availableChannels` deliberately retains its last value,
+        // so permission must be an independent invalidation signal or the
+        // building REQ survives on stale coordinates.
+        permissionCancellable = locationManager.$permissionState
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] _ in self?.retarget() }
+        // The app-info kill switch must take effect immediately, not on the
+        // next location change or remount.
+        settingCancellable = NotificationCenter.default
+            .publisher(for: LocationNotesSettings.didChangeNotification)
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] _ in self?.retarget() }
+        retarget()
+    }
+
+    func deactivate() {
+        activeHolders = max(0, activeHolders - 1)
+        guard activeHolders == 0 else { return }
+        channelsCancellable = nil
+        permissionCancellable = nil
+        settingCancellable = nil
+        managerCancellable = nil
+        releaseManager(manager)
+        manager = nil
+        noteCount = 0
+    }
+
+    private func retarget() {
+        guard activeHolders > 0,
+              revealed,
+              LocationNotesSettings.enabled,
+              locationManager.permissionState == .authorized,
+              let geohash = locationManager.availableChannels
+                  .first(where: { $0.level == .building })?.geohash
+        else {
+            managerCancellable = nil
+            releaseManager(manager)
+            manager = nil
+            noteCount = 0
+            return
+        }
+
+        if let manager {
+            guard manager.geohash != geohash.lowercased() else { return }
+            // Pooled managers are shared; never retarget one in place —
+            // release the old cell and acquire the new one.
+            managerCancellable = nil
+            releaseManager(manager)
+            self.manager = nil
+        }
+
+        let fresh = managerFactory(geohash)
+        manager = fresh
+        managerCancellable = fresh.$notes
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] notes in
+                let now = Date()
+                self?.noteCount = notes.filter { $0.expiresAt.map { $0 > now } ?? true }.count
+            }
+    }
+}

bitchat/App/PeerIdentityStore.swift

@@ -25,10 +25,6 @@ final class PeerIdentityStore: ObservableObject {
         stablePeerIDsByShortID[peerID] = stablePeerID
     }
 
-    func replaceStablePeerIDs(_ mappings: [PeerID: PeerID]) {
-        stablePeerIDsByShortID = mappings
-    }
-
     func fingerprint(for peerID: PeerID) -> String? {
         peerFingerprintsByPeerID[peerID]
     }
@@ -94,10 +90,6 @@ final class PeerIdentityStore: ObservableObject {
         invalidateEncryptionCache(for: peerID)
     }
 
-    func replaceEncryptionStatuses(_ statuses: [PeerID: EncryptionStatus]) {
-        encryptionStatuses = statuses
-    }
-
     func setVerifiedFingerprints(_ fingerprints: Set<String>) {
         verifiedFingerprints = fingerprints
     }

bitchat/App/PeerListModel.swift

@@ -14,6 +14,9 @@ struct MeshPeerRow: Identifiable, Equatable {
     let isMutualFavorite: Bool
     let encryptionStatus: EncryptionStatus
     let showsVerifiedBadgeWhenOffline: Bool
+    /// Vouched-for by someone I verified, without an explicit verification of
+    /// mine — rendered as the unfilled seal (verified gets the filled one).
+    let showsVouchedBadge: Bool
 
     var id: String { peerID.id }
 }
@@ -26,18 +29,29 @@ struct GeohashPersonRow: Identifiable, Equatable {
     let isBlocked: Bool
 }
 
+struct GroupChatRow: Identifiable, Equatable {
+    let peerID: PeerID
+    let name: String
+    let memberCount: Int
+    let isCreator: Bool
+    let hasUnread: Bool
+
+    var id: String { peerID.id }
+}
+
 @MainActor
 final class PeerListModel: ObservableObject {
     @Published private(set) var allPeers: [BitchatPeer] = []
     @Published private(set) var meshRows: [MeshPeerRow] = []
     @Published private(set) var geohashPeople: [GeohashPersonRow] = []
+    @Published private(set) var groupRows: [GroupChatRow] = []
     @Published private(set) var reachableMeshPeerCount = 0
     @Published private(set) var connectedMeshPeerCount = 0
     @Published private(set) var visibleGeohashPeerCount = 0
     @Published private(set) var renderID = ""
 
     private let chatViewModel: ChatViewModel
-    private let conversationStore: ConversationStore
+    private let conversations: ConversationStore
     private let locationChannelsModel: LocationChannelsModel
     private let peerIdentityStore: PeerIdentityStore
     private let locationPresenceStore: LocationPresenceStore
@@ -45,13 +59,13 @@ final class PeerListModel: ObservableObject {
 
     init(
         chatViewModel: ChatViewModel,
-        conversationStore: ConversationStore,
+        conversations: ConversationStore,
         locationChannelsModel: LocationChannelsModel? = nil,
         peerIdentityStore: PeerIdentityStore? = nil,
         locationPresenceStore: LocationPresenceStore? = nil
     ) {
         self.chatViewModel = chatViewModel
-        self.conversationStore = conversationStore
+        self.conversations = conversations
         self.locationChannelsModel = locationChannelsModel ?? LocationChannelsModel()
         self.peerIdentityStore = peerIdentityStore ?? chatViewModel.peerIdentityStore
         self.locationPresenceStore = locationPresenceStore ?? chatViewModel.locationPresenceStore
@@ -122,7 +136,14 @@ final class PeerListModel: ObservableObject {
             }
             .store(in: &cancellables)
 
-        conversationStore.$unreadConversations
+        conversations.$unreadConversations
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] _ in
+                self?.refresh()
+            }
+            .store(in: &cancellables)
+
+        chatViewModel.groupStore.$groups
             .receive(on: DispatchQueue.main)
             .sink { [weak self] _ in
                 self?.refresh()
@@ -183,13 +204,12 @@ final class PeerListModel: ObservableObject {
         let myPeerID = chatViewModel.meshService.myPeerID
         let meshRows = allPeers.map { peer in
             let isMe = peer.peerID == myPeerID
-            let verifiedBadge: Bool
+            let fingerprint = isMe ? nil : chatViewModel.getFingerprint(for: peer.peerID)
-            if !isMe && !peer.isConnected,
+            let isVerifiedFingerprint = fingerprint.map { peerIdentityStore.isVerified($0) } ?? false
-               let fingerprint = chatViewModel.getFingerprint(for: peer.peerID) {
+            let verifiedBadge = !peer.isConnected && isVerifiedFingerprint
-                verifiedBadge = peerIdentityStore.isVerified(fingerprint)
+            // Vouched is subordinate to verified: never show both seals.
-            } else {
+            let vouchedBadge = !isVerifiedFingerprint
-                verifiedBadge = false
+                && (fingerprint.map { chatViewModel.isVouchedFingerprint($0) } ?? false)
-            }
 
             return MeshPeerRow(
                 peerID: peer.peerID,
@@ -202,7 +222,8 @@ final class PeerListModel: ObservableObject {
                 isReachable: peer.isReachable,
                 isMutualFavorite: peer.isMutualFavorite,
                 encryptionStatus: chatViewModel.getEncryptionStatus(for: peer.peerID),
-                showsVerifiedBadgeWhenOffline: verifiedBadge
+                showsVerifiedBadgeWhenOffline: verifiedBadge,
+                showsVouchedBadge: vouchedBadge
             )
         }
 
@@ -217,22 +238,40 @@ final class PeerListModel: ObservableObject {
         }
 
         let geohashPeople = buildGeohashPeople()
+        let groupRows = buildGroupRows()
 
         self.meshRows = meshRows
         reachableMeshPeerCount = meshCounts.reachable
         connectedMeshPeerCount = meshCounts.connected
         self.geohashPeople = geohashPeople
         visibleGeohashPeerCount = geohashPeople.count
+        self.groupRows = groupRows
         renderID = (
             meshRows.map {
                 "\($0.id)-\($0.isConnected)-\($0.isReachable)-\($0.hasUnread)-\($0.isFavorite)-\($0.isBlocked)"
             } +
             geohashPeople.map {
                 "geo:\($0.id)-\($0.isTeleported)-\($0.isBlocked)-\($0.displayName)"
+            } +
+            groupRows.map {
+                "group:\($0.id)-\($0.name)-\($0.memberCount)-\($0.hasUnread)"
             }
         ).joined(separator: "|")
     }
 
+    private func buildGroupRows() -> [GroupChatRow] {
+        let myFingerprint = chatViewModel.meshService.noiseIdentityFingerprint()
+        return chatViewModel.groupStore.groups.map { group in
+            GroupChatRow(
+                peerID: group.peerID,
+                name: group.name,
+                memberCount: group.members.count,
+                isCreator: group.creatorFingerprint == myFingerprint,
+                hasUnread: chatViewModel.hasUnreadMessages(for: group.peerID)
+            )
+        }
+    }
+
     private func buildGeohashPeople() -> [GeohashPersonRow] {
         let myHex = currentGeohashIdentityHex()
         let teleportedSet = Set(locationPresenceStore.teleportedGeo.map { $0.lowercased() })

bitchat/App/PrivateConversationModels.swift

@@ -2,68 +2,93 @@ import BitFoundation
 import Combine
 import Foundation
 
+/// Feature model for private (direct) conversations.
+///
+/// Reads the single-writer `ConversationStore` directly: `messages(for:)`
+/// returns the peer's conversation backing array (no mirror dictionary), and
+/// the store's typed `changes` subject drives invalidation — a change in the
+/// SELECTED peer's conversation republishes this model, while appends to
+/// other private chats only surface through the unread set. Direct
+/// conversations are keyed by raw routing peer ID; the coordinators'
+/// ephemeral/stable mirroring guarantees the selected peer's key always
+/// holds the full timeline (see `ConversationID.directPeer`).
 @MainActor
 final class PrivateInboxModel: ObservableObject {
     @Published private(set) var selectedPeerID: PeerID?
     @Published private(set) var unreadPeerIDs: Set<PeerID> = []
-    @Published private(set) var messagesByPeerID: [PeerID: [BitchatMessage]] = [:]
 
-    private let conversationStore: ConversationStore
+    private let conversations: ConversationStore
     private var cancellables = Set<AnyCancellable>()
 
-    init(conversationStore: ConversationStore) {
+    init(conversations: ConversationStore) {
-        self.conversationStore = conversationStore
+        self.conversations = conversations
+        self.selectedPeerID = conversations.selectedPrivatePeerID
+        self.unreadPeerIDs = conversations.unreadDirectRoutingPeerIDs()
 
         bind()
-        refreshMessages()
     }
 
     func messages(for peerID: PeerID?) -> [BitchatMessage] {
         guard let peerID else { return [] }
-        return messagesByPeerID[peerID] ?? []
+        return conversations.conversationsByID[.directPeer(peerID)]?.messages ?? []
     }
 
     private func bind() {
-        conversationStore.$selectedPrivatePeerID
+        conversations.$selectedPrivatePeerID
-            .receive(on: DispatchQueue.main)
+            .dropFirst()
             .sink { [weak self] peerID in
-                self?.selectedPeerID = peerID
+                guard let self, self.selectedPeerID != peerID else { return }
-                self?.refreshMessages()
+                self.selectedPeerID = peerID
             }
             .store(in: &cancellables)
 
-        conversationStore.$unreadConversations
+        conversations.changes
-            .receive(on: DispatchQueue.main)
+            .sink { [weak self] change in
-            .sink { [weak self] _ in
+                self?.apply(change)
-                self?.unreadPeerIDs = self?.conversationStore.unreadDirectPeerIDs() ?? []
-                self?.refreshMessages()
             }
             .store(in: &cancellables)
-
-        conversationStore.$messagesByConversation
-            .receive(on: DispatchQueue.main)
-            .sink { [weak self] _ in
-                self?.refreshMessages()
-            }
-            .store(in: &cancellables)
-
-        selectedPeerID = conversationStore.selectedPrivatePeerID
-        unreadPeerIDs = conversationStore.unreadDirectPeerIDs()
     }
 
-    private func refreshMessages() {
+    private func apply(_ change: ConversationChange) {
-        var nextMessagesByPeerID = conversationStore.directMessagesByPeerID()
+        switch change {
-        var peerIDs = Set(nextMessagesByPeerID.keys)
+        case .appended(let id, _),
-        peerIDs.formUnion(conversationStore.unreadDirectPeerIDs())
+             .updated(let id, _),
-        if let selectedPeerID = conversationStore.selectedPrivatePeerID {
+             .statusChanged(let id, _, _),
-            peerIDs.insert(selectedPeerID)
+             .messageRemoved(let id, _),
+             .cleared(let id):
+            republishIfSelected(id)
+
+        case .unreadChanged(let id, _):
+            guard isDirect(id) else { return }
+            refreshUnreadPeerIDs()
+
+        case .removed(let id):
+            guard isDirect(id) else { return }
+            refreshUnreadPeerIDs()
+            republishIfSelected(id)
+
+        case .migrated(let source, let destination):
+            guard isDirect(source) || isDirect(destination) else { return }
+            refreshUnreadPeerIDs()
+            republishIfSelected(source)
+            republishIfSelected(destination)
+        }
     }
 
-        for peerID in peerIDs where nextMessagesByPeerID[peerID] == nil {
+    private func republishIfSelected(_ id: ConversationID) {
-            nextMessagesByPeerID[peerID] = []
+        guard let selectedPeerID, id == .directPeer(selectedPeerID) else { return }
+        objectWillChange.send()
     }
 
-        messagesByPeerID = nextMessagesByPeerID
+    private func refreshUnreadPeerIDs() {
+        let next = conversations.unreadDirectRoutingPeerIDs()
+        guard unreadPeerIDs != next else { return }
+        unreadPeerIDs = next
+    }
+
+    private func isDirect(_ id: ConversationID) -> Bool {
+        if case .direct = id { return true }
+        return false
     }
 }
 
@@ -83,7 +108,13 @@ struct PrivateConversationHeaderState: Equatable {
     let encryptionStatus: EncryptionStatus?
 
     var supportsFavoriteToggle: Bool {
-        !conversationPeerID.isGeoDM
+        !conversationPeerID.isGeoDM && !conversationPeerID.isGroup
+    }
+
+    /// Group chats have no single peer identity behind the header: no
+    /// fingerprint screen, no per-peer encryption badge.
+    var isGroupConversation: Bool {
+        conversationPeerID.isGroup
     }
 }
 
@@ -93,22 +124,22 @@ final class PrivateConversationModel: ObservableObject {
     @Published private(set) var selectedHeaderState: PrivateConversationHeaderState?
 
     private let chatViewModel: ChatViewModel
-    private let conversationStore: ConversationStore
+    private let conversations: ConversationStore
     private let locationChannelsModel: LocationChannelsModel
     private let peerIdentityStore: PeerIdentityStore
     private var cancellables = Set<AnyCancellable>()
 
     init(
         chatViewModel: ChatViewModel,
-        conversationStore: ConversationStore,
+        conversations: ConversationStore,
         locationChannelsModel: LocationChannelsModel? = nil,
         peerIdentityStore: PeerIdentityStore? = nil
     ) {
         self.chatViewModel = chatViewModel
-        self.conversationStore = conversationStore
+        self.conversations = conversations
         self.locationChannelsModel = locationChannelsModel ?? LocationChannelsModel()
         self.peerIdentityStore = peerIdentityStore ?? chatViewModel.peerIdentityStore
-        let initialPeerID = conversationStore.selectedPrivatePeerID
+        let initialPeerID = conversations.selectedPrivatePeerID
         self.selectedPeerID = initialPeerID
         self.selectedHeaderState = initialPeerID.flatMap { peerID in
             makeHeaderState(for: peerID)
@@ -153,7 +184,7 @@ final class PrivateConversationModel: ObservableObject {
     }
 
     private func bind() {
-        conversationStore.$selectedPrivatePeerID
+        conversations.$selectedPrivatePeerID
             .receive(on: DispatchQueue.main)
             .sink { [weak self] _ in
                 self?.refreshSelectedConversation()
@@ -181,6 +212,13 @@ final class PrivateConversationModel: ObservableObject {
             }
             .store(in: &cancellables)
 
+        chatViewModel.groupStore.$groups
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] _ in
+                self?.refreshSelectedConversation()
+            }
+            .store(in: &cancellables)
+
         NotificationCenter.default.publisher(for: Notification.Name("peerStatusUpdated"))
             .receive(on: DispatchQueue.main)
             .sink { [weak self] _ in
@@ -197,17 +235,43 @@ final class PrivateConversationModel: ObservableObject {
     }
 
     private func refreshSelectedConversation() {
-        selectedPeerID = conversationStore.selectedPrivatePeerID
+        selectedPeerID = conversations.selectedPrivatePeerID
         selectedHeaderState = selectedPeerID.flatMap { peerID in
             makeHeaderState(for: peerID)
         }
     }
 
     private func makeHeaderState(for conversationPeerID: PeerID) -> PrivateConversationHeaderState {
+        // Group chats: the "peer" is the whole crew. Name + member count in
+        // the header; availability reads as mesh since group traffic floods
+        // the local mesh, and the per-peer encryption badge does not apply.
+        if conversationPeerID.isGroup {
+            let displayName: String
+            if let group = chatViewModel.groupStore.group(for: conversationPeerID) {
+                displayName = "#\(group.name) (\(group.members.count))"
+            } else {
+                displayName = String(localized: "common.unknown", comment: "Fallback label for unknown peer")
+            }
+            return PrivateConversationHeaderState(
+                conversationPeerID: conversationPeerID,
+                headerPeerID: conversationPeerID,
+                displayName: displayName,
+                availability: .meshReachable,
+                isFavorite: false,
+                encryptionStatus: nil
+            )
+        }
+
         let headerPeerID = chatViewModel.getShortIDForNoiseKey(conversationPeerID)
         let peer = chatViewModel.getPeer(byID: headerPeerID)
         let displayName = resolveDisplayName(for: conversationPeerID, headerPeerID: headerPeerID, peer: peer)
-        let availability = resolveAvailability(for: headerPeerID, peer: peer)
+        // Geo DMs are always routed over Nostr (NIP-17); their nostr_ keys
+        // never resolve to a reachable mesh peer, so resolveAvailability would
+        // report .offline. Report .nostrAvailable so the header shows the
+        // globe instead of a misleading "offline" tag.
+        let availability = conversationPeerID.isGeoDM
+            ? .nostrAvailable
+            : resolveAvailability(for: headerPeerID, peer: peer)
         let encryptionStatus: EncryptionStatus? = conversationPeerID.isGeoDM
             ? nil
             : chatViewModel.getEncryptionStatus(for: headerPeerID)

bitchat/App/PublicChatModel.swift

@@ -2,40 +2,76 @@ import BitFoundation
 import Combine
 import SwiftUI
 
+/// Feature model for the active public (mesh/geohash) timeline.
+///
+/// Observes ONE `Conversation` object in the single-writer
+/// `ConversationStore` — the active channel's — so appends to background
+/// conversations (other geohashes, private chats) never invalidate it.
+/// `messages` reads the observed conversation's backing array directly;
+/// there is no mirror copy.
 @MainActor
 final class PublicChatModel: ObservableObject {
     @Published private(set) var activeChannel: ChannelID
-    @Published private(set) var messages: [BitchatMessage] = []
 
-    private let conversationStore: ConversationStore
+    /// The active public conversation's timeline.
+    var messages: [BitchatMessage] { activeConversation.messages }
+
+    private let conversations: ConversationStore
+    private var activeConversation: Conversation
+    private var activeConversationCancellable: AnyCancellable?
     private var cancellables = Set<AnyCancellable>()
 
-    init(conversationStore: ConversationStore) {
+    init(conversations: ConversationStore) {
-        self.activeChannel = conversationStore.activeChannel
+        let channel = conversations.activeChannel
-        self.conversationStore = conversationStore
+        self.conversations = conversations
+        self.activeChannel = channel
+        self.activeConversation = conversations.conversation(for: ConversationID(channelID: channel))
 
+        observeActiveConversation()
         bind()
-        refreshMessages()
     }
 
     private func bind() {
-        conversationStore.$activeChannel
+        conversations.$activeChannel
-            .receive(on: DispatchQueue.main)
+            .dropFirst()
             .sink { [weak self] channel in
-                self?.activeChannel = channel
+                guard let self else { return }
-                self?.refreshMessages()
+                self.activeChannel = channel
+                self.retargetActiveConversation(to: channel)
             }
             .store(in: &cancellables)
 
-        conversationStore.$messagesByConversation
+        // The store replaces a conversation's object when it is removed
-            .receive(on: DispatchQueue.main)
+        // (panic clear); retarget to the fresh instance so the observation
+        // never goes stale.
+        conversations.changes
+            .sink { [weak self] change in
+                guard let self,
+                      case .removed(let id) = change,
+                      id == self.activeConversation.id else { return }
+                self.retargetActiveConversation(to: self.activeChannel)
+            }
+            .store(in: &cancellables)
+    }
+
+    private func retargetActiveConversation(to channel: ChannelID) {
+        let conversation = conversations.conversation(for: ConversationID(channelID: channel))
+        guard conversation !== activeConversation else {
+            // Same object (e.g. re-selected channel): keep the existing
+            // observation, but `messages` may still differ from what views
+            // last rendered, so republish.
+            objectWillChange.send()
+            return
+        }
+        objectWillChange.send()
+        activeConversation = conversation
+        observeActiveConversation()
+    }
+
+    private func observeActiveConversation() {
+        activeConversationCancellable = activeConversation.objectWillChange
             .sink { [weak self] _ in
-                self?.refreshMessages()
+                self?.objectWillChange.send()
             }
-            .store(in: &cancellables)
-    }
-
-    private func refreshMessages() {
-        messages = conversationStore.messages(for: ConversationID(channelID: activeChannel))
     }
 }

bitchat/App/VerificationModel.swift

@@ -3,12 +3,19 @@ import Combine
 import Foundation
 
 struct FingerprintPresentationState: Equatable {
-    let statusPeerID: PeerID
     let peerNickname: String
     let encryptionStatus: EncryptionStatus
     let theirFingerprint: String?
     let myFingerprint: String
     let isVerified: Bool
+    /// Number of currently-valid vouches from peers the user verified
+    /// (0 when the peer is explicitly verified — the stronger badge wins).
+    let voucherCount: Int
+    /// Display names of the (verified) vouchers, where known.
+    let voucherNames: [String]
+
+    /// Vouched for by ≥1 peer the user verified (and not explicitly verified).
+    var isVouched: Bool { voucherCount > 0 }
 
     var canToggleVerification: Bool {
         encryptionStatus == .noiseSecured || encryptionStatus == .noiseVerified
@@ -48,10 +55,6 @@ final class VerificationModel: ObservableObject {
         return VerificationService.shared.buildMyQRString(nickname: currentNickname, npub: npub) ?? ""
     }
 
-    func beginQRVerification(with qr: VerificationService.VerificationQR) -> Bool {
-        chatViewModel.beginQRVerification(with: qr)
-    }
-
     func verifyScannedPayload(_ payload: String) -> VerificationScanOutcome {
         guard let qr = VerificationService.shared.verifyScannedQR(payload) else {
             return .invalid
@@ -82,14 +85,33 @@ final class VerificationModel: ObservableObject {
         let encryptionStatus = chatViewModel.getEncryptionStatus(for: statusPeerID)
         let theirFingerprint = chatViewModel.getFingerprint(for: statusPeerID)
         let peerNickname = resolveDisplayName(for: peerID, statusPeerID: statusPeerID)
+        let isVerified = theirFingerprint.map { peerIdentityStore.isVerified($0) } ?? false
+
+        // Vouch state is recomputed on read: only vouchers still in the
+        // verified set count, so removing a verification silently retires the
+        // vouches that peer gave.
+        let vouchers: [VouchRecord]
+        if !isVerified, let theirFingerprint {
+            vouchers = chatViewModel.identityManager.validVouchers(for: theirFingerprint)
+        } else {
+            vouchers = []
+        }
+        let voucherNames = vouchers.compactMap { record -> String? in
+            guard let social = chatViewModel.identityManager.getSocialIdentity(for: record.voucherFingerprint) else {
+                return nil
+            }
+            if let petname = social.localPetname, !petname.isEmpty { return petname }
+            return social.claimedNickname.isEmpty ? nil : social.claimedNickname
+        }
 
         return FingerprintPresentationState(
-            statusPeerID: statusPeerID,
             peerNickname: peerNickname,
             encryptionStatus: encryptionStatus,
             theirFingerprint: theirFingerprint,
             myFingerprint: chatViewModel.getMyFingerprint(),
-            isVerified: theirFingerprint.map { peerIdentityStore.isVerified($0) } ?? false
+            isVerified: isVerified,
+            voucherCount: vouchers.count,
+            voucherNames: voucherNames
         )
     }
 
@@ -122,6 +144,17 @@ final class VerificationModel: ObservableObject {
                 self?.objectWillChange.send()
             }
             .store(in: &cancellables)
+
+        // Vouch state changes (ChatVouchCoordinator.notifyPeerTrustChanged)
+        // are signalled via this notification rather than a published
+        // property, so an open fingerprint sheet refreshes its vouched badge
+        // live when a vouch batch is accepted.
+        NotificationCenter.default.publisher(for: Notification.Name("peerStatusUpdated"))
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] _ in
+                self?.objectWillChange.send()
+            }
+            .store(in: &cancellables)
     }
 
     private func resolveDisplayName(for peerID: PeerID, statusPeerID: PeerID) -> String {

bitchat/Assets.xcassets/AppIconDebug.appiconset/Contents.json

@@ -27,6 +27,66 @@
       "idiom" : "universal",
       "platform" : "ios",
       "size" : "1024x1024"
+    },
+    {
+      "filename" : "mac_16x16.png",
+      "idiom" : "mac",
+      "scale" : "1x",
+      "size" : "16x16"
+    },
+    {
+      "filename" : "mac_16x16@2x.png",
+      "idiom" : "mac",
+      "scale" : "2x",
+      "size" : "16x16"
+    },
+    {
+      "filename" : "mac_32x32.png",
+      "idiom" : "mac",
+      "scale" : "1x",
+      "size" : "32x32"
+    },
+    {
+      "filename" : "mac_32x32@2x.png",
+      "idiom" : "mac",
+      "scale" : "2x",
+      "size" : "32x32"
+    },
+    {
+      "filename" : "mac_128x128.png",
+      "idiom" : "mac",
+      "scale" : "1x",
+      "size" : "128x128"
+    },
+    {
+      "filename" : "mac_128x128@2x.png",
+      "idiom" : "mac",
+      "scale" : "2x",
+      "size" : "128x128"
+    },
+    {
+      "filename" : "mac_256x256.png",
+      "idiom" : "mac",
+      "scale" : "1x",
+      "size" : "256x256"
+    },
+    {
+      "filename" : "mac_256x256@2x.png",
+      "idiom" : "mac",
+      "scale" : "2x",
+      "size" : "256x256"
+    },
+    {
+      "filename" : "mac_512x512.png",
+      "idiom" : "mac",
+      "scale" : "1x",
+      "size" : "512x512"
+    },
+    {
+      "filename" : "mac_512x512@2x.png",
+      "idiom" : "mac",
+      "scale" : "2x",
+      "size" : "512x512"
     }
   ],
   "info" : {

bitchat/BitchatApp.swift

@@ -15,6 +15,7 @@ struct BitchatApp: App {
     static let groupID = "group.\(bundleID)"
 
     @StateObject private var runtime: AppRuntime
+    @AppStorage(AppTheme.storageKey) private var appThemeRawValue = AppTheme.matrix.rawValue
     #if os(iOS)
     @Environment(\.scenePhase) var scenePhase
     @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
@@ -30,6 +31,7 @@ struct BitchatApp: App {
     var body: some Scene {
         WindowGroup {
             ContentView()
+                .environment(\.appTheme, AppTheme(rawValue: appThemeRawValue) ?? .matrix)
                 .environmentObject(runtime.publicChatModel)
                 .environmentObject(runtime.privateInboxModel)
                 .environmentObject(runtime.privateConversationModel)
@@ -38,6 +40,7 @@ struct BitchatApp: App {
                 .environmentObject(runtime.locationChannelsModel)
                 .environmentObject(runtime.peerListModel)
                 .environmentObject(runtime.appChromeModel)
+                .environmentObject(runtime.boardAlertsModel)
                 .onAppear {
                     appDelegate.runtime = runtime
                     runtime.start()
@@ -101,13 +104,21 @@ final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
 
     func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
         let identifier = response.notification.request.identifier
+        let actionIdentifier = response.actionIdentifier
         let userInfo = response.notification.request.content.userInfo
 
+        // Complete only after the response is handled: for a background
+        // action (👋 wave) the system may suspend the app the moment the
+        // completion handler runs, which would drop the queued send.
         Task { @MainActor in
-            self.runtime?.handleNotificationResponse(identifier: identifier, userInfo: userInfo)
+            self.runtime?.handleNotificationResponse(
-        }
+                identifier: identifier,
+                actionIdentifier: actionIdentifier,
+                userInfo: userInfo
+            )
             completionHandler()
         }
+    }
 
     func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
         let identifier = notification.request.identifier

bitchat/Features/voice/AudioSessionCoordinator.swift

@@ -0,0 +1,472 @@
+//
+// AudioSessionCoordinator.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import AVFoundation
+import BitLogger
+import Foundation
+
+/// The raw audio-session calls the coordinator makes, abstracted so the
+/// state machine is unit-testable with a mock (and compiles on the macOS
+/// test host, where `AVAudioSession` doesn't exist).
+///
+/// Calls arrive on the coordinator's private serial queue — never the main
+/// thread. `setCategory`/`setActive` block on IPC to the audio server
+/// (observed >1 s under contention on device, tripping the system gesture
+/// gate), and Apple explicitly recommends activating the session off the
+/// main thread.
+protocol SessionApplying: Sendable {
+    func setCategory(_ category: AudioSessionCoordinator.Category) throws
+    func setActive(_ active: Bool, notifyOthersOnDeactivation: Bool) throws
+}
+
+/// Sole owner of `AVAudioSession` category/activation for voice features.
+///
+/// Talk-over means capture (push-to-talk) and playback (inbound bursts,
+/// voice notes) can be live simultaneously; letting each engine configure
+/// the shared session directly made them stomp each other's category and
+/// route mid-flight (the AURemoteIO -10851 dead-input class). Instead every
+/// client acquires a `Token` and the coordinator:
+///
+/// - reference-counts activation: `setActive(true)` only on the first
+///   holder, `setActive(false, notifyOthersOnDeactivation:)` only when the
+///   last one releases — no client can deactivate another's session;
+/// - keeps one escalating category: playback-only holders get `.playback`,
+///   any capture holder escalates to `.playAndRecord`, and the category is
+///   never downgraded while anyone still holds a token (capture ending must
+///   not yank the route out from under live playback);
+/// - fans out `onInterrupted` on system interruptions and when the active
+///   route's device disappears (no auto-resume: bursts are transient, the
+///   next press or burst simply re-acquires). The escalating category change
+///   fans out separately as `onCategoryEscalated` — the session stays live,
+///   so holders that can rebuild their engine against the new configuration
+///   keep playing (talk-over is bidirectional); holders that don't provide
+///   it fall back to `onInterrupted`.
+///
+/// Threading: all state lives on a private serial queue, which both
+/// serializes rapid acquire/release pairs and keeps the blocking session IPC
+/// off the main thread (`acquire` is `async` for exactly that hop; `release`
+/// is fire-and-forget onto the queue). Holder callbacks always run on the
+/// main actor.
+///
+/// Microphone *permission* queries stay with their callers; this type owns
+/// only category and activation.
+///
+/// `@unchecked Sendable`: every mutable property is confined to `queue`.
+final class AudioSessionCoordinator: @unchecked Sendable {
+    enum Use {
+        case playback
+        case capture
+    }
+
+    /// The session category the coordinator has applied (the `SessionApplying`
+    /// adapter maps these to concrete `AVAudioSession` category/mode/options).
+    enum Category {
+        case playback
+        case playAndRecord
+    }
+
+    /// Opaque handle for one client's hold on the session. Release exactly
+    /// once when done (extra releases are ignored).
+    ///
+    /// `@unchecked` because the stored callbacks are `@MainActor`-isolated
+    /// closures (non-Sendable as stored types). Lifecycle state is protected
+    /// by `stateLock`, and callbacks are only ever invoked on the main actor.
+    final class Token: @unchecked Sendable {
+        fileprivate enum CallbackKind: Sendable {
+            case interrupted
+            case categoryEscalated
+        }
+
+        /// A callback snapshot is only valid for the lifecycle epoch in which
+        /// it was captured. `release` advances the epoch synchronously before
+        /// its queue work, so a callback already headed to the main actor can't
+        /// reach a client that has since released this token and reacquired a
+        /// different one.
+        fileprivate struct CallbackTicket: Sendable {
+            let token: Token
+            let kind: CallbackKind
+            let lifecycleEpoch: UInt64
+        }
+
+        private enum Lifecycle {
+            /// Registered on the session queue, but `acquire` has not yet
+            /// returned into the client's main-actor call frame.
+            case acquiring
+            case ready
+            case released
+        }
+
+        fileprivate let onInterrupted: @MainActor () -> Void
+        fileprivate let onCategoryEscalated: (@MainActor () -> Void)?
+        private let stateLock = NSLock()
+        private var lifecycle = Lifecycle.acquiring
+        private var lifecycleEpoch: UInt64 = 0
+        /// A terminal event that lands while the token is registered but not
+        /// yet handed off invalidates the acquire before its caller can start.
+        private var terminalEventPendingHandoff = false
+
+        fileprivate init(
+            onInterrupted: @escaping @MainActor () -> Void,
+            onCategoryEscalated: (@MainActor () -> Void)?
+        ) {
+            self.onInterrupted = onInterrupted
+            self.onCategoryEscalated = onCategoryEscalated
+        }
+
+        /// Records an event at the same linearization point at which the
+        /// coordinator snapshots its holders. An acquiring token cannot safely
+        /// receive a callback yet: terminal events invalidate the acquire,
+        /// while category escalation needs no callback because its engine will
+        /// start against the already-escalated configuration.
+        fileprivate func record(_ kind: CallbackKind) -> CallbackTicket? {
+            stateLock.withLock {
+                switch lifecycle {
+                case .acquiring:
+                    switch kind {
+                    case .interrupted:
+                        terminalEventPendingHandoff = true
+                    case .categoryEscalated:
+                        break
+                    }
+                    return nil
+                case .ready:
+                    return CallbackTicket(token: self, kind: kind, lifecycleEpoch: lifecycleEpoch)
+                case .released:
+                    return nil
+                }
+            }
+        }
+
+        /// Completes the main-actor ownership handoff if no terminal event
+        /// invalidated it. Because `acquire` itself is main-actor isolated, a
+        /// successful handoff returns directly into the caller without another
+        /// actor hop; no callback can interleave before the caller stores the
+        /// returned token.
+        fileprivate func completeHandoff() -> Bool {
+            stateLock.withLock {
+                guard lifecycle == .acquiring,
+                      !terminalEventPendingHandoff
+                else { return false }
+                lifecycle = .ready
+                return true
+            }
+        }
+
+        /// Marks the token dead synchronously, before the asynchronous holder
+        /// removal. Returns false for an already-released token.
+        fileprivate func markReleased() -> Bool {
+            stateLock.withLock {
+                guard lifecycle != .released else { return false }
+                lifecycle = .released
+                lifecycleEpoch &+= 1
+                terminalEventPendingHandoff = false
+                return true
+            }
+        }
+
+        /// Revalidates a queue snapshot at the main-actor delivery boundary.
+        /// The lock is deliberately released before invoking client code: real
+        /// callbacks commonly call `release` on this same token.
+        @MainActor
+        fileprivate func deliver(_ ticket: CallbackTicket) {
+            let isLive = stateLock.withLock {
+                lifecycle == .ready && lifecycleEpoch == ticket.lifecycleEpoch
+            }
+            guard isLive else { return }
+            switch ticket.kind {
+            case .interrupted:
+                onInterrupted()
+            case .categoryEscalated:
+                (onCategoryEscalated ?? onInterrupted)()
+            }
+        }
+    }
+
+    /// Deterministic suspension points for lifecycle race tests. Production
+    /// instances use the nil defaults; the hooks never move session calls off
+    /// the coordinator queue or callback execution off the main actor.
+    struct TestingHooks: Sendable {
+        let beforeAcquireHandoff: (@Sendable () async -> Void)?
+        let beforeCallbackDelivery: (@Sendable () async -> Void)?
+
+        init(
+            beforeAcquireHandoff: (@Sendable () async -> Void)? = nil,
+            beforeCallbackDelivery: (@Sendable () async -> Void)? = nil
+        ) {
+            self.beforeAcquireHandoff = beforeAcquireHandoff
+            self.beforeCallbackDelivery = beforeCallbackDelivery
+        }
+    }
+
+    static let shared = AudioSessionCoordinator(session: SystemAudioSession())
+
+    private let session: SessionApplying
+    private let testingHooks: TestingHooks
+    /// Confines all mutable state, serializes whole acquire/release
+    /// operations (two rapid presses can't interleave their category and
+    /// activation calls), and hosts the blocking session IPC off main.
+    private let queue = DispatchQueue(label: "chat.bitchat.audio-session", qos: .userInitiated)
+
+    // Queue-confined state.
+    private var holders: [ObjectIdentifier: Token] = [:]
+    private var currentCategory: Category?
+    private var sessionActive = false
+    /// Written once in init, read in deinit — never touched concurrently.
+    private var observers: [NSObjectProtocol] = []
+
+    init(session: SessionApplying, testingHooks: TestingHooks = TestingHooks()) {
+        self.session = session
+        self.testingHooks = testingHooks
+        observeSystemNotifications()
+    }
+
+    deinit {
+        for observer in observers {
+            NotificationCenter.default.removeObserver(observer)
+        }
+    }
+
+    /// Configures + activates the session for `use` and registers the caller
+    /// as a holder. The blocking `AVAudioSession` calls run on the session
+    /// queue — the caller suspends instead of stalling its thread (a PTT
+    /// press used to block main >1 s in `setActive`, tripping the system
+    /// gesture gate). `onInterrupted` fires (on the main actor) when the
+    /// client must stop using the session: a system interruption began or
+    /// its route's device went away. The client should stop its engine,
+    /// finalize any artifacts, and release — resuming means acquiring again.
+    ///
+    /// `onCategoryEscalated` fires instead when the session category
+    /// escalated underneath the holder (a capture client joined): the session
+    /// stays active, so a holder that can rebuild its engine against the new
+    /// configuration should restart and keep going. Holders that pass `nil`
+    /// get `onInterrupted` for escalation too. Escalation is delivered before
+    /// `acquire` returns, so the new holder starts its engine strictly after
+    /// existing ones were told to rebuild. Main-actor isolation is also the
+    /// ownership handoff boundary: if interruption or route loss lands after
+    /// queue registration but before that boundary, the provisional holder is
+    /// removed and `acquire` throws `CancellationError` instead of returning a
+    /// token whose callback already fired.
+    @MainActor
+    func acquire(
+        _ use: Use,
+        onInterrupted: @escaping @MainActor () -> Void,
+        onCategoryEscalated: (@MainActor () -> Void)? = nil
+    ) async throws -> Token {
+        let token = Token(onInterrupted: onInterrupted, onCategoryEscalated: onCategoryEscalated)
+        let reconfigured: [Token.CallbackTicket] = try await withCheckedThrowingContinuation { continuation in
+            queue.async {
+                do {
+                    continuation.resume(returning: try self.activateOnQueue(use, registering: token))
+                } catch {
+                    continuation.resume(throwing: error)
+                }
+            }
+        }
+
+        // Escalating playback -> playAndRecord reconfigures the hardware
+        // route; engines started against the old configuration must restart.
+        if !reconfigured.isEmpty {
+            SecureLogger.info("AudioSession: category escalated to playAndRecord with \(reconfigured.count) live holder(s)", category: .session)
+            await deliver(reconfigured)
+        }
+        if let beforeAcquireHandoff = testingHooks.beforeAcquireHandoff {
+            await beforeAcquireHandoff()
+        }
+        guard token.completeHandoff() else {
+            // A call/Siri interruption or route loss landed after registration
+            // but before ownership handoff. Remove the provisional holder and
+            // fail instead of starting a client engine after the stop event.
+            release(token)
+            throw CancellationError()
+        }
+        return token
+    }
+
+    /// Drops one holder. Deactivates the session (notifying other apps) only
+    /// when the last holder releases. Safe to call more than once, from any
+    /// thread (including `deinit` paths): the work is fire-and-forget onto
+    /// the session queue, so the blocking deactivation IPC never runs on the
+    /// caller.
+    func release(_ token: Token) {
+        guard token.markReleased() else { return }
+        queue.async {
+            self.releaseOnQueue(token)
+        }
+    }
+
+    // MARK: - Queue-confined core
+
+    /// Returns callback tickets for pre-existing live holders whose engines
+    /// must restart because this acquire escalated the category.
+    private func activateOnQueue(_ use: Use, registering token: Token) throws -> [Token.CallbackTicket] {
+        let target: Category = (use == .capture || currentCategory == .playAndRecord) ? .playAndRecord : .playback
+        let categoryChanged = target != currentCategory
+        let previousCategory = currentCategory
+        if categoryChanged {
+            try session.setCategory(target)
+            currentCategory = target
+        }
+        if !sessionActive {
+            do {
+                try session.setActive(true, notifyOthersOnDeactivation: false)
+            } catch {
+                // Activation failed (e.g. a phone call owns the hardware):
+                // with no holder registered, an escalated category recorded
+                // here would stick and pin later playback-only acquires to
+                // .playAndRecord. Existing holders keep the category the
+                // hardware really has.
+                if categoryChanged, holders.isEmpty {
+                    currentCategory = previousCategory
+                }
+                throw error
+            }
+            sessionActive = true
+        }
+
+        let reconfigured = categoryChanged
+            ? holders.values.compactMap { $0.record(.categoryEscalated) }
+            : []
+        holders[ObjectIdentifier(token)] = token
+        return reconfigured
+    }
+
+    private func releaseOnQueue(_ token: Token) {
+        guard holders.removeValue(forKey: ObjectIdentifier(token)) != nil else { return }
+        guard holders.isEmpty else { return }
+        currentCategory = nil
+        guard sessionActive else { return }
+        sessionActive = false
+        do {
+            try session.setActive(false, notifyOthersOnDeactivation: true)
+        } catch {
+            SecureLogger.error("AudioSession: deactivation failed: \(error)", category: .session)
+        }
+    }
+
+    private func onQueue<T: Sendable>(_ body: @escaping @Sendable () -> T) async -> T {
+        await withCheckedContinuation { continuation in
+            queue.async {
+                continuation.resume(returning: body())
+            }
+        }
+    }
+
+    @MainActor
+    private func deliver(_ tickets: [Token.CallbackTicket]) async {
+        guard !tickets.isEmpty else { return }
+        if let beforeCallbackDelivery = testingHooks.beforeCallbackDelivery {
+            await beforeCallbackDelivery()
+        }
+        for ticket in tickets {
+            ticket.token.deliver(ticket)
+        }
+    }
+
+    // MARK: - System events (internal so tests can drive them directly)
+
+    /// A system interruption began: the session is already deactivated by the
+    /// OS, so just mark it inactive and tell every ready holder (on the main
+    /// actor) to stop. A provisional acquiring holder is invalidated instead.
+    /// No auto-resume — the next acquire re-activates.
+    func handleInterruptionBegan() async {
+        let tickets = await onQueue { () -> [Token.CallbackTicket] in
+            self.sessionActive = false
+            return self.holders.values.compactMap { $0.record(.interrupted) }
+        }
+        await deliver(tickets)
+    }
+
+    /// The active route's input/output device disappeared (e.g. BT headset
+    /// off): ready holders' engines are wedged against a dead route — stop
+    /// them; invalidate a holder whose acquire has not returned yet.
+    func handleRouteDeviceUnavailable() async {
+        let tickets = await onQueue {
+            self.holders.values.compactMap { $0.record(.interrupted) }
+        }
+        await deliver(tickets)
+    }
+
+    /// Test hook: suspends until every session operation enqueued before this
+    /// call — including fire-and-forget `release`s — has completed.
+    func drain() async {
+        await onQueue {}
+    }
+
+    private func observeSystemNotifications() {
+        #if os(iOS)
+        let center = NotificationCenter.default
+        observers.append(center.addObserver(
+            forName: AVAudioSession.interruptionNotification,
+            object: AVAudioSession.sharedInstance(),
+            queue: .main
+        ) { [weak self] note in
+            guard let raw = note.userInfo?[AVAudioSessionInterruptionTypeKey] as? UInt,
+                  AVAudioSession.InterruptionType(rawValue: raw) == .began,
+                  let self
+            else { return }
+            SecureLogger.info("AudioSession: interruption began", category: .session)
+            Task { await self.handleInterruptionBegan() }
+        })
+        observers.append(center.addObserver(
+            forName: AVAudioSession.routeChangeNotification,
+            object: AVAudioSession.sharedInstance(),
+            queue: .main
+        ) { [weak self] note in
+            guard let raw = note.userInfo?[AVAudioSessionRouteChangeReasonKey] as? UInt,
+                  AVAudioSession.RouteChangeReason(rawValue: raw) == .oldDeviceUnavailable,
+                  let self
+            else { return }
+            SecureLogger.info("AudioSession: route device became unavailable", category: .session)
+            Task { await self.handleRouteDeviceUnavailable() }
+        })
+        #endif
+    }
+}
+
+// MARK: - Production adapter
+
+#if os(iOS)
+private struct SystemAudioSession: SessionApplying {
+    func setCategory(_ category: AudioSessionCoordinator.Category) throws {
+        let session = AVAudioSession.sharedInstance()
+        switch category {
+        case .playback:
+            try session.setCategory(.playback, mode: .spokenAudio, options: [.mixWithOthers])
+        case .playAndRecord:
+            // allowBluetoothHFP is not available on iOS Simulator
+            #if targetEnvironment(simulator)
+            try session.setCategory(
+                .playAndRecord,
+                mode: .default,
+                options: [.defaultToSpeaker, .allowBluetoothA2DP, .mixWithOthers]
+            )
+            #else
+            try session.setCategory(
+                .playAndRecord,
+                mode: .default,
+                options: [.defaultToSpeaker, .allowBluetoothA2DP, .allowBluetoothHFP, .mixWithOthers]
+            )
+            #endif
+        }
+    }
+
+    func setActive(_ active: Bool, notifyOthersOnDeactivation: Bool) throws {
+        try AVAudioSession.sharedInstance().setActive(
+            active,
+            options: notifyOthersOnDeactivation ? [.notifyOthersOnDeactivation] : []
+        )
+    }
+}
+#else
+/// macOS has no app-level audio session; the coordinator still runs its
+/// bookkeeping so client code is identical across platforms.
+private struct SystemAudioSession: SessionApplying {
+    func setCategory(_ category: AudioSessionCoordinator.Category) throws {}
+    func setActive(_ active: Bool, notifyOthersOnDeactivation: Bool) throws {}
+}
+#endif

bitchat/Features/voice/PTTAudioCodec.swift

@@ -0,0 +1,175 @@
+//
+// PTTAudioCodec.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import AVFoundation
+import BitLogger
+import Foundation
+
+/// Streaming PCM -> AAC-LC encoder for live voice. Stateful (the AAC encoder
+/// carries a bit reservoir across frames); one instance per burst.
+/// Not thread-safe — confine to one queue.
+final class PTTFrameEncoder {
+    private let converter: AVAudioConverter
+    private var pendingInput: [AVAudioPCMBuffer] = []
+
+    init?() {
+        guard let pcm = PTTAudioFormat.pcmFormat,
+              let aac = PTTAudioFormat.aacFormat,
+              let converter = AVAudioConverter(from: pcm, to: aac)
+        else { return nil }
+        converter.bitRate = PTTAudioFormat.bitRate
+        self.converter = converter
+    }
+
+    /// Feeds PCM (16 kHz mono float) and returns every complete AAC frame the
+    /// encoder produced. Frames come out ~130 bytes each at 16 kbps.
+    func encode(_ buffer: AVAudioPCMBuffer) -> [Data] {
+        pendingInput.append(buffer)
+        return drainConverter()
+    }
+
+    private func drainConverter() -> [Data] {
+        var frames: [Data] = []
+        while true {
+            let output = AVAudioCompressedBuffer(
+                format: converter.outputFormat,
+                packetCapacity: 8,
+                maximumPacketSize: max(converter.maximumOutputPacketSize, 1)
+            )
+            var error: NSError?
+            let status = converter.convert(to: output, error: &error) { [weak self] _, outStatus in
+                guard let self, let next = self.pendingInput.first else {
+                    outStatus.pointee = .noDataNow
+                    return nil
+                }
+                self.pendingInput.removeFirst()
+                outStatus.pointee = .haveData
+                return next
+            }
+            if status == .error {
+                SecureLogger.error("PTT encode failed: \(error?.localizedDescription ?? "unknown")", category: .session)
+                return frames
+            }
+            frames.append(contentsOf: Self.extractPackets(from: output))
+            // .haveData means the output buffer filled and more may be ready;
+            // anything else means the converter wants more input.
+            if status != .haveData { return frames }
+        }
+    }
+
+    private static func extractPackets(from buffer: AVAudioCompressedBuffer) -> [Data] {
+        guard buffer.packetCount > 0, let descriptions = buffer.packetDescriptions else { return [] }
+        var frames: [Data] = []
+        frames.reserveCapacity(Int(buffer.packetCount))
+        for index in 0..<Int(buffer.packetCount) {
+            let description = descriptions[index]
+            guard description.mDataByteSize > 0 else { continue }
+            let start = buffer.data.advanced(by: Int(description.mStartOffset))
+            frames.append(Data(bytes: start, count: Int(description.mDataByteSize)))
+        }
+        return frames
+    }
+}
+
+/// Streaming AAC-LC -> PCM decoder for live voice. Stateful; one instance per
+/// inbound burst. Not thread-safe — confine to one queue/actor.
+final class PTTFrameDecoder {
+    private let converter: AVAudioConverter
+    private let pcmFormat: AVAudioFormat
+    private let aacFormat: AVAudioFormat
+
+    init?() {
+        guard let pcm = PTTAudioFormat.pcmFormat,
+              let aac = PTTAudioFormat.aacFormat,
+              let converter = AVAudioConverter(from: aac, to: pcm)
+        else { return nil }
+        self.converter = converter
+        self.pcmFormat = pcm
+        self.aacFormat = aac
+    }
+
+    /// Decodes one raw AAC frame to PCM. Returns nil for malformed input or
+    /// while the decoder is still priming (the first frame of a stream).
+    func decode(_ frame: Data) -> AVAudioPCMBuffer? {
+        guard !frame.isEmpty, frame.count <= 8 * 1024 else { return nil }
+
+        let input = AVAudioCompressedBuffer(format: aacFormat, packetCapacity: 1, maximumPacketSize: frame.count)
+        frame.withUnsafeBytes { raw in
+            guard let base = raw.baseAddress else { return }
+            input.data.copyMemory(from: base, byteCount: frame.count)
+        }
+        input.byteLength = UInt32(frame.count)
+        input.packetCount = 1
+        input.packetDescriptions?.pointee = AudioStreamPacketDescription(
+            mStartOffset: 0,
+            mVariableFramesInPacket: 0,
+            mDataByteSize: UInt32(frame.count)
+        )
+
+        guard let output = AVAudioPCMBuffer(
+            pcmFormat: pcmFormat,
+            frameCapacity: PTTAudioFormat.samplesPerFrame * 2
+        ) else { return nil }
+
+        var consumed = false
+        var error: NSError?
+        let status = converter.convert(to: output, error: &error) { _, outStatus in
+            if consumed {
+                outStatus.pointee = .noDataNow
+                return nil
+            }
+            consumed = true
+            outStatus.pointee = .haveData
+            return input
+        }
+        guard status != .error else {
+            SecureLogger.debug("PTT decode failed: \(error?.localizedDescription ?? "unknown")", category: .session)
+            return nil
+        }
+        return output.frameLength > 0 ? output : nil
+    }
+}
+
+/// Sample-rate/channel converter from the microphone's native format to the
+/// 16 kHz mono processing format. Stateful; not thread-safe.
+final class PTTInputResampler {
+    private let converter: AVAudioConverter
+    private let outputFormat: AVAudioFormat
+    private let ratio: Double
+
+    init?(inputFormat: AVAudioFormat) {
+        guard let pcm = PTTAudioFormat.pcmFormat,
+              let converter = AVAudioConverter(from: inputFormat, to: pcm)
+        else { return nil }
+        self.converter = converter
+        self.outputFormat = pcm
+        self.ratio = PTTAudioFormat.sampleRate / inputFormat.sampleRate
+    }
+
+    func resample(_ buffer: AVAudioPCMBuffer) -> AVAudioPCMBuffer? {
+        let capacity = AVAudioFrameCount(Double(buffer.frameLength) * ratio) + 64
+        guard let output = AVAudioPCMBuffer(pcmFormat: outputFormat, frameCapacity: capacity) else { return nil }
+
+        var consumed = false
+        var error: NSError?
+        let status = converter.convert(to: output, error: &error) { _, outStatus in
+            if consumed {
+                outStatus.pointee = .noDataNow
+                return nil
+            }
+            consumed = true
+            outStatus.pointee = .haveData
+            return buffer
+        }
+        guard status != .error else {
+            SecureLogger.debug("PTT resample failed: \(error?.localizedDescription ?? "unknown")", category: .session)
+            return nil
+        }
+        return output.frameLength > 0 ? output : nil
+    }
+}

bitchat/Features/voice/PTTAudioFormat.swift

@@ -0,0 +1,84 @@
+//
+// PTTAudioFormat.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import AVFoundation
+import Foundation
+
+/// Shared audio parameters for live push-to-talk: AAC-LC, 16 kHz, mono,
+/// ~16 kbps — deliberately identical to `VoiceRecorder`'s voice-note settings
+/// so a burst's finalized `.m4a` and its live frames sound the same.
+enum PTTAudioFormat {
+    static let sampleRate: Double = 16_000
+    static let channelCount: AVAudioChannelCount = 1
+    static let bitRate = 16_000
+    /// AAC-LC frame size is fixed by the codec: 1024 samples = 64 ms at 16 kHz.
+    static let samplesPerFrame: AVAudioFrameCount = 1024
+    static var frameDuration: TimeInterval { Double(samplesPerFrame) / sampleRate }
+
+    /// Uncompressed processing format (deinterleaved float PCM).
+    static var pcmFormat: AVAudioFormat? {
+        AVAudioFormat(standardFormatWithSampleRate: sampleRate, channels: channelCount)
+    }
+
+    /// Compressed wire format.
+    static var aacFormat: AVAudioFormat? {
+        var description = AudioStreamBasicDescription(
+            mSampleRate: sampleRate,
+            mFormatID: kAudioFormatMPEG4AAC,
+            mFormatFlags: 0,
+            mBytesPerPacket: 0,
+            mFramesPerPacket: samplesPerFrame,
+            mBytesPerFrame: 0,
+            mChannelsPerFrame: channelCount,
+            mBitsPerChannel: 0,
+            mReserved: 0
+        )
+        return AVAudioFormat(streamDescription: &description)
+    }
+
+    /// Voice-note container settings for the finalized `.m4a`, mirroring
+    /// `VoiceRecorder.startRecording()`.
+    static var voiceNoteFileSettings: [String: Any] {
+        [
+            AVFormatIDKey: kAudioFormatMPEG4AAC,
+            AVSampleRateKey: sampleRate,
+            AVNumberOfChannelsKey: Int(channelCount),
+            AVEncoderBitRateKey: bitRate
+        ]
+    }
+}
+
+/// Builds ADTS-framed AAC so a receiver can persist a burst progressively:
+/// unlike `.m4a` (whose moov atom only exists after close), an ADTS `.aac`
+/// stream is playable at any prefix — a partially received burst is still a
+/// replayable voice note.
+enum ADTSFramer {
+    private static let headerSize = 7
+    /// MPEG-4 sampling frequency index for 16 kHz.
+    private static let samplingFrequencyIndex: UInt8 = 8
+    private static let channelConfiguration: UInt8 = 1
+
+    /// Wraps one raw AAC-LC frame in an ADTS header.
+    static func frame(_ aacFrame: Data) -> Data {
+        let frameLength = aacFrame.count + headerSize
+        var data = Data(capacity: frameLength)
+        // Syncword 0xFFF, MPEG-4, layer 00, no CRC.
+        data.append(0xFF)
+        data.append(0xF1)
+        // Profile AAC-LC (audio object type 2 -> bits 01), frequency index,
+        // private bit 0, channel config high bit.
+        data.append((0b01 << 6) | (samplingFrequencyIndex << 2) | ((channelConfiguration >> 2) & 0x1))
+        data.append(((channelConfiguration & 0x3) << 6) | UInt8((frameLength >> 11) & 0x3))
+        data.append(UInt8((frameLength >> 3) & 0xFF))
+        data.append(UInt8((frameLength & 0x7) << 5) | 0x1F)
+        // Buffer fullness 0x7FF (VBR), one AAC frame per ADTS frame.
+        data.append(0xFC)
+        data.append(aacFrame)
+        return data
+    }
+}

bitchat/Features/voice/PTTBurstPlayer.swift

@@ -0,0 +1,509 @@
+//
+// PTTBurstPlayer.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+@preconcurrency import AVFoundation
+import BitLogger
+import Foundation
+
+/// The engine operations behind live-burst playback, abstracted so the
+/// player's lifecycle (jitter start, category-escalation restart, stop) is
+/// unit-testable without real audio hardware.
+@MainActor
+protocol PTTPlaybackEngine: AnyObject {
+    /// The object `AVAudioEngineConfigurationChange` notifications are posted
+    /// for (nil for mocks — no observer is registered).
+    var configChangeObject: AnyObject? { get }
+    func start() throws
+    func play()
+    func stop()
+    func schedule(
+        _ buffer: AVAudioPCMBuffer,
+        completionType: PTTPlaybackCompletionType,
+        completionHandler: @escaping @Sendable (PTTPlaybackCompletionEvent) -> Void
+    )
+}
+
+/// The lifecycle point requested from `AVAudioPlayerNode` for a scheduled
+/// buffer. `dataConsumed` only means the node no longer needs the bytes; it
+/// may arrive before the render pipeline has made the audio audible.
+enum PTTPlaybackCompletionType: Equatable, Sendable {
+    case dataConsumed
+    case dataPlayedBack
+}
+
+enum PTTPlaybackCompletionEvent: Equatable, Sendable {
+    case dataConsumed
+    case dataPlayedBack
+    /// AVAudioPlayerNode invokes the requested callback when the node is
+    /// stopped too. That is not audible completion and must remain replayable.
+    case playbackStopped
+}
+
+/// One `AVAudioEngine` + `AVAudioPlayerNode` pair. Created fresh per (re)start:
+/// an engine instantiated against an earlier audio-session configuration keeps
+/// rendering to the stale route (same class of failure as the capture side's
+/// fresh-engine-per-press rule).
+@MainActor
+private final class SystemPTTPlaybackEngine: PTTPlaybackEngine {
+    private let engine = AVAudioEngine()
+    private let node = AVAudioPlayerNode()
+
+    init(format: AVAudioFormat) {
+        engine.attach(node)
+        engine.connect(node, to: engine.mainMixerNode, format: format)
+    }
+
+    var configChangeObject: AnyObject? { engine }
+
+    func start() throws {
+        engine.prepare()
+        try engine.start()
+    }
+
+    func play() {
+        node.play()
+    }
+
+    func stop() {
+        node.stop()
+        engine.stop()
+    }
+
+    func schedule(
+        _ buffer: AVAudioPCMBuffer,
+        completionType: PTTPlaybackCompletionType,
+        completionHandler: @escaping @Sendable (PTTPlaybackCompletionEvent) -> Void
+    ) {
+        let callbackType: AVAudioPlayerNodeCompletionCallbackType = switch completionType {
+        case .dataConsumed: .dataConsumed
+        case .dataPlayedBack: .dataPlayedBack
+        }
+        let scheduledEngine = engine
+        node.scheduleBuffer(buffer, completionCallbackType: callbackType) { [weak scheduledEngine] callbackType in
+            // The API invokes this callback when the player is stopped as
+            // well. A configuration change can stop the engine before its
+            // notification reaches MainActor, so do not misclassify that
+            // flushed tail as audible playback.
+            guard scheduledEngine?.isRunning == true else {
+                completionHandler(.playbackStopped)
+                return
+            }
+            switch callbackType {
+            case .dataConsumed:
+                completionHandler(.dataConsumed)
+            case .dataRendered:
+                completionHandler(.dataConsumed)
+            case .dataPlayedBack:
+                completionHandler(.dataPlayedBack)
+            @unknown default:
+                completionHandler(.playbackStopped)
+            }
+        }
+    }
+}
+
+/// Completion callbacks arrive off the main actor, while engine rebuilds are
+/// serialized on it. This small lock-backed latch lets a rebuild atomically
+/// claim only buffers whose completion has not already fired — even when the
+/// callback's hop back to the main actor is still queued.
+private final class PTTPlaybackCompletionState: @unchecked Sendable {
+    private enum State {
+        case scheduled
+        case completed
+        case retired
+    }
+
+    private let lock = NSLock()
+    private var state: State = .scheduled
+
+    /// Returns true exactly once when playback completion wins the race with
+    /// an engine rebuild or stop.
+    func complete() -> Bool {
+        lock.withLock {
+            guard case .scheduled = state else { return false }
+            state = .completed
+            return true
+        }
+    }
+
+    /// Returns true exactly once when a rebuild or stop claims this
+    /// still-pending schedule. Later callbacks from that engine are stale.
+    func retireIfPending() -> Bool {
+        lock.withLock {
+            guard case .scheduled = state else { return false }
+            state = .retired
+            return true
+        }
+    }
+}
+
+/// Plays one inbound live voice burst with a small jitter buffer.
+///
+/// Frames are decoded and scheduled back-to-back on an `AVAudioPlayerNode`;
+/// an underrun (missing/late packets) simply pauses output until the next
+/// buffer arrives, which self-heals timing without explicit silence
+/// insertion. Playback starts once `TransportConfig.pttJitterBufferSeconds`
+/// of audio is queued or `pttJitterDeadlineSeconds` has elapsed.
+///
+/// Talk-over is bidirectional: when push-to-talk capture starts while this
+/// burst plays, the session category escalates underneath the engine — the
+/// player rebuilds a fresh engine against the new configuration and keeps
+/// streaming instead of dying. Real interruptions (phone call, route device
+/// gone) still stop it; the burst keeps assembling to file either way.
+@MainActor
+final class PTTBurstPlayer {
+    /// Restart-on-reconfigure ceiling: a burst is at most ~2 minutes, so a
+    /// handful of category/route changes is plenty — beyond it something is
+    /// thrashing and stopping cleanly beats an engine-rebuild loop.
+    private static let maxEngineRestarts = 8
+
+    private let makeEngine: @MainActor () -> PTTPlaybackEngine
+    private var engine: PTTPlaybackEngine
+    private let decoder: PTTFrameDecoder
+    private let coordinator: AudioSessionCoordinator
+    /// Injectable so tests don't fight over the app-wide exclusive-playback
+    /// slot (a parallel test's `play()` would stop this player mid-test).
+    private let exclusivity: VoiceNotePlaybackCoordinator
+
+    private var queuedBuffers: [AVAudioPCMBuffer] = []
+    private var queuedDuration: TimeInterval = 0
+    private struct ScheduledBuffer {
+        let id: UInt64
+        let buffer: AVAudioPCMBuffer
+        let completionState: PTTPlaybackCompletionState
+    }
+    /// Buffers handed to the current engine whose completion has not yet
+    /// been processed on the main actor. Keeping the buffers themselves lets
+    /// a category-escalation rebuild replay the unfinished tail in order.
+    private var scheduledBuffers: [ScheduledBuffer] = []
+    private var nextScheduledBufferID: UInt64 = 0
+    /// Bumped on every engine rebuild or stop so completion tasks from a
+    /// torn-down engine cannot mutate the current generation's pending list.
+    private var engineGeneration = 0
+    private var engineRestarts = 0
+    private var engineStarted = false
+    private var finished = false
+    /// Latched off (internal read so tests can await the async failure path).
+    private(set) var stopped = false
+    /// A session acquire is in flight (it suspends off-main for the blocking
+    /// session IPC); gates `startIfReady` against double acquisition.
+    private var acquiringSession = false
+    private var deadlineTask: Task<Void, Never>?
+    private var sessionToken: AudioSessionCoordinator.Token?
+    /// Reserved before the session acquire suspends. Activation succeeds only
+    /// if no newer playback request claimed the floor in the meantime.
+    private var playbackReservation: VoiceNotePlaybackCoordinator.Reservation?
+    private var configChangeObserver: NSObjectProtocol?
+
+    private(set) var isPlaying = false
+
+    /// Fires exactly once when the player stops for good (drain-out, cancel,
+    /// interruption, failure). `ChatLiveVoiceCoordinator` uses it to unpark
+    /// the draining player it keeps alive after the assembly — the player's
+    /// only long-lived owner — is discarded on burst END.
+    var onStopped: (() -> Void)?
+
+    init?(
+        coordinator: AudioSessionCoordinator? = nil,
+        exclusivity: VoiceNotePlaybackCoordinator? = nil,
+        makeEngine: (@MainActor () -> PTTPlaybackEngine)? = nil
+    ) {
+        guard let format = PTTAudioFormat.pcmFormat, let decoder = PTTFrameDecoder() else { return nil }
+        self.decoder = decoder
+        self.coordinator = coordinator ?? .shared
+        self.exclusivity = exclusivity ?? .shared
+        let factory = makeEngine ?? { SystemPTTPlaybackEngine(format: format) }
+        self.makeEngine = factory
+        self.engine = factory()
+
+        deadlineTask = Task { [weak self] in
+            try? await Task.sleep(nanoseconds: UInt64(TransportConfig.pttJitterDeadlineSeconds * 1_000_000_000))
+            self?.startIfReady(force: true)
+        }
+    }
+
+    deinit {
+        // Backstop for an owner dropping the player before it stopped: the
+        // session coordinator retains registered tokens strongly, so a token
+        // leaked here would keep the session active (and pin any escalated
+        // category) for the app's lifetime. `release` is fire-and-forget
+        // onto the coordinator's queue, so it is deinit-safe.
+        if let token = sessionToken {
+            coordinator.release(token)
+        }
+        if let observer = configChangeObserver {
+            NotificationCenter.default.removeObserver(observer)
+        }
+        deadlineTask?.cancel()
+    }
+
+    /// Decodes and queues frames (in burst order). Starts playback when the
+    /// jitter buffer fills.
+    func enqueue(_ frames: [Data]) {
+        guard !stopped else { return }
+        for frame in frames {
+            guard let pcm = decoder.decode(frame) else { continue }
+            if engineStarted {
+                schedule(pcm)
+            } else {
+                queuedBuffers.append(pcm)
+                queuedDuration += Double(pcm.frameLength) / PTTAudioFormat.sampleRate
+            }
+        }
+        startIfReady(force: false)
+    }
+
+    /// The burst ended: stop once everything scheduled has played out.
+    func finishAfterDrain() {
+        finished = true
+        // The complete burst is queued — no jitter left to wait for. This
+        // also matters when END lands while the async session acquire is
+        // still in flight: the queued audio must play out, not be treated
+        // as already drained.
+        startIfReady(force: true)
+        stopIfDrained()
+    }
+
+    /// Immediate stop (cancel, another playback taking over, interruption,
+    /// teardown).
+    func stop() {
+        guard !stopped else { return }
+        stopped = true
+        deadlineTask?.cancel()
+        removeConfigObserver()
+        queuedBuffers = []
+        retireScheduledBuffers()
+        if engineStarted {
+            engine.stop()
+        }
+        isPlaying = false
+        releaseSessionToken()
+        exclusivity.deactivate(self)
+        onStopped?()
+    }
+
+    private func startIfReady(force: Bool) {
+        guard !engineStarted, !acquiringSession, !stopped, !queuedBuffers.isEmpty else { return }
+        guard force || queuedDuration >= TransportConfig.pttJitterBufferSeconds else { return }
+
+        // Acquiring the session suspends for its blocking IPC (off the main
+        // actor); frames arriving meanwhile keep queueing and are flushed
+        // onto the engine once it starts.
+        acquiringSession = true
+        playbackReservation = exclusivity.reserve(self)
+        Task { [weak self] in
+            await self?.acquireSessionAndStart()
+        }
+    }
+
+    private func acquireSessionAndStart() async {
+        let token: AudioSessionCoordinator.Token
+        do {
+            token = try await coordinator.acquire(
+                .playback,
+                onInterrupted: { [weak self] in self?.stop() },
+                onCategoryEscalated: { [weak self] in self?.restartEngine() }
+            )
+        } catch {
+            acquiringSession = false
+            SecureLogger.error("PTT playback session activation failed: \(error)", category: .session)
+            // Playing unregistered would leave the engine exposed: another
+            // holder's last release deactivates the session mid-play, and no
+            // interruption/escalation fan-out ever reaches us. Bail like the
+            // engine-start failure below; the burst still assembles to file.
+            // (stop() also fires onStopped so a parked draining player is
+            // unparked instead of leaking.)
+            stop()
+            return
+        }
+        acquiringSession = false
+        // stop() (cancel, exclusivity, teardown) may have landed while the
+        // session was activating: hand the token straight back.
+        guard !stopped else {
+            coordinator.release(token)
+            return
+        }
+        sessionToken = token
+        guard let playbackReservation,
+              exclusivity.isCurrent(playbackReservation, for: self)
+        else {
+            // The request was superseded while audio-session activation was
+            // suspended. Do not even start the retired engine.
+            stop()
+            return
+        }
+
+        // Observe reconfiguration before starting so nothing lands between.
+        registerConfigObserver()
+        do {
+            try engine.start()
+        } catch {
+            // A capture racing this start can reconfigure the session while
+            // the engine spins up (its escalation fan-out no-ops on a player
+            // that never started): rebuild once against the settled
+            // configuration — counted against the restart cap — before
+            // giving up.
+            SecureLogger.warning("PTT playback engine failed to start (\(error)) — rebuilding once", category: .session)
+            removeConfigObserver()
+            engineRestarts += 1
+            engine = makeEngine()
+            registerConfigObserver()
+            do {
+                try engine.start()
+            } catch {
+                SecureLogger.error("PTT playback engine failed to start: \(error)", category: .session)
+                // stop() removes the observer, hands the token back, and
+                // fires onStopped for any parked draining owner.
+                stop()
+                return
+            }
+        }
+        engineStarted = true
+        guard exclusivity.activate(self, reservation: playbackReservation)
+        else {
+            // A newer user-initiated playback reserved the floor while this
+            // older PTT request was suspended in audio-session activation.
+            // Never let the late completion steal playback back.
+            stop()
+            return
+        }
+        isPlaying = true
+        engine.play()
+
+        let buffered = queuedBuffers
+        queuedBuffers = []
+        queuedDuration = 0
+        for buffer in buffered {
+            schedule(buffer)
+        }
+    }
+
+    /// The audio session was reconfigured underneath the running engine
+    /// (category escalation for talk-over, or an engine configuration
+    /// change): rebuild a fresh engine against the new configuration and
+    /// keep streaming. Buffers already completed stay completed; the
+    /// unfinished scheduled tail is replayed in order on the fresh engine,
+    /// and frames still arriving continue scheduling after it.
+    private func restartEngine() {
+        guard engineStarted, !stopped else { return }
+        engineRestarts += 1
+        guard engineRestarts <= Self.maxEngineRestarts else {
+            SecureLogger.warning("PTT playback: engine reconfigured \(engineRestarts) times in one burst — stopping", category: .session)
+            stop()
+            return
+        }
+
+        removeConfigObserver()
+        // Claim the unfinished tail before stopping the old engine. Stopping
+        // a player node may itself invoke its completion handlers; retiring
+        // the claimed entries first makes those callbacks unambiguously stale.
+        // A completion that fired just before this rebuild wins the latch and
+        // is excluded even if its MainActor task has not run yet.
+        let buffersToReplay = scheduledBuffers.compactMap { scheduled in
+            scheduled.completionState.retireIfPending() ? scheduled.buffer : nil
+        }
+        scheduledBuffers = []
+        engineGeneration += 1
+        engine.stop()
+        engine = makeEngine()
+        registerConfigObserver()
+        do {
+            try engine.start()
+        } catch {
+            SecureLogger.error("PTT playback engine failed to restart after session reconfigure: \(error)", category: .session)
+            stop()
+            return
+        }
+        engine.play()
+        for buffer in buffersToReplay {
+            schedule(buffer)
+        }
+        SecureLogger.info("PTT playback: engine restarted after session reconfigure", category: .session)
+        // If every old buffer completed before the rebuild, a finished burst
+        // can stop now. Otherwise the replayed tail keeps it alive until its
+        // new-generation completions arrive.
+        stopIfDrained()
+    }
+
+    private func registerConfigObserver() {
+        guard let object = engine.configChangeObject else { return }
+        configChangeObserver = NotificationCenter.default.addObserver(
+            forName: .AVAudioEngineConfigurationChange,
+            object: object,
+            queue: .main
+        ) { [weak self] _ in
+            Task { @MainActor [weak self] in
+                self?.restartEngine()
+            }
+        }
+    }
+
+    private func removeConfigObserver() {
+        if let observer = configChangeObserver {
+            NotificationCenter.default.removeObserver(observer)
+            configChangeObserver = nil
+        }
+    }
+
+    private func schedule(_ buffer: AVAudioPCMBuffer) {
+        let id = nextScheduledBufferID
+        nextScheduledBufferID &+= 1
+        let completionState = PTTPlaybackCompletionState()
+        scheduledBuffers.append(ScheduledBuffer(
+            id: id,
+            buffer: buffer,
+            completionState: completionState
+        ))
+        let generation = engineGeneration
+        engine.schedule(buffer, completionType: .dataPlayedBack) { [weak self, completionState] event in
+            guard event == .dataPlayedBack else { return }
+            // Mark completion before hopping to MainActor. A rebuild can then
+            // distinguish already-completed audio from an unfinished tail
+            // even when this task has not run yet.
+            guard completionState.complete() else { return }
+            Task { @MainActor [weak self] in
+                guard let self, self.engineGeneration == generation else { return }
+                self.scheduledBuffers.removeAll { $0.id == id }
+                self.stopIfDrained()
+            }
+        }
+    }
+
+    private func retireScheduledBuffers() {
+        engineGeneration += 1
+        for scheduled in scheduledBuffers {
+            _ = scheduled.completionState.retireIfPending()
+        }
+        scheduledBuffers = []
+    }
+
+    private func stopIfDrained() {
+        guard finished, scheduledBuffers.isEmpty else { return }
+        // Started: everything scheduled has played out. Never started with
+        // nothing queued or in flight (e.g. no decodable frames): nothing
+        // will ever play. Otherwise the engine start is still pending (the
+        // async session acquire) and the queued audio must play out first.
+        guard engineStarted || (!acquiringSession && queuedBuffers.isEmpty) else { return }
+        stop()
+    }
+
+    private func releaseSessionToken() {
+        sessionToken.map(coordinator.release)
+        sessionToken = nil
+    }
+}
+
+extension PTTBurstPlayer: ExclusivePlayback {
+    /// A live stream can't meaningfully pause; yielding the floor stops it.
+    /// The burst keeps assembling to file, so nothing is lost.
+    nonisolated func pauseForExclusivity() {
+        Task { @MainActor [weak self] in
+            self?.stop()
+        }
+    }
+}

bitchat/Features/voice/PTTCaptureEngine.swift

@@ -0,0 +1,326 @@
+//
+// PTTCaptureEngine.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import AVFoundation
+import BitLogger
+import Foundation
+
+/// Owns one capture token and returns it even when the capture engine's owner
+/// disappears without reaching its normal stop/cancel path. The coordinator
+/// retains registered tokens strongly, so relying on `Token.deinit` cannot
+/// reclaim an abandoned hold.
+final class PTTCaptureSessionLease: @unchecked Sendable {
+    private let coordinator: AudioSessionCoordinator
+    private let lock = NSLock()
+    private var token: AudioSessionCoordinator.Token?
+
+    init(coordinator: AudioSessionCoordinator) {
+        self.coordinator = coordinator
+    }
+
+    func install(_ token: AudioSessionCoordinator.Token) {
+        let previous = lock.withLock {
+            let previous = self.token
+            self.token = token
+            return previous
+        }
+        previous.map(coordinator.release)
+    }
+
+    func release() {
+        let token = lock.withLock {
+            let token = self.token
+            self.token = nil
+            return token
+        }
+        token.map(coordinator.release)
+    }
+
+    deinit {
+        release()
+    }
+}
+
+/// Monotonic capture identity shared by main-actor lifecycle code and queued
+/// engine callbacks. Removing a notification observer does not cancel a block
+/// already enqueued on the main queue, so every callback must also prove it
+/// still belongs to the current hold before mutating capture state.
+final class PTTCaptureGeneration: @unchecked Sendable {
+    private let lock = NSLock()
+    private var value: UInt = 0
+
+    func begin() -> UInt {
+        lock.withLock {
+            value &+= 1
+            return value
+        }
+    }
+
+    func invalidate() {
+        lock.withLock { value &+= 1 }
+    }
+
+    func invalidate(ifCurrent generation: UInt) -> Bool {
+        lock.withLock {
+            guard value == generation else { return false }
+            value &+= 1
+            return true
+        }
+    }
+
+    func isCurrent(_ generation: UInt) -> Bool {
+        lock.withLock { value == generation }
+    }
+}
+
+/// Captures microphone audio for a live push-to-talk burst, producing both:
+/// - live AAC frames via `onFrames` (called on the capture queue), and
+/// - a finalized `.m4a` voice note on `stop()` — the same artifact
+///   `VoiceRecorder` produces, so the existing voice-note send pipeline
+///   handles delivery to receivers that missed the live stream.
+/// `@unchecked Sendable`: every mutable property is confined to one executor —
+/// the capture `queue` (resampler/encoder/file/counters) or the main actor
+/// (`engine`, `engineStarted`, `sessionLease`, `configChangeObserver`) — so
+/// weak references may cross the `@Sendable` tap/notification closures, which
+/// immediately hop back to the owning executor.
+final class PTTCaptureEngine: @unchecked Sendable {
+    /// Hard cap matching `VoiceRecorder.maxRecordingDuration`: past it the
+    /// engine keeps running (the UI owns the gesture) but stops encoding.
+    private static let maxCaptureDuration: TimeInterval = 120
+
+    /// Recreated on every `start()`: an engine whose input unit was
+    /// instantiated against an earlier (playback-only or inactive) audio
+    /// session keeps reporting a dead 0 Hz / 2 ch input format and fails to
+    /// enable the mic (AURemoteIO -10851, observed on iPhone field tests).
+    private var engine = AVAudioEngine()
+    private let queue = DispatchQueue(label: "chat.bitchat.ptt.capture", qos: .userInitiated)
+    private let coordinator: AudioSessionCoordinator
+    private let sessionLease: PTTCaptureSessionLease
+    private let captureGeneration = PTTCaptureGeneration()
+
+    // Capture-queue-confined state.
+    private var resampler: PTTInputResampler?
+    private var encoder: PTTFrameEncoder?
+    private var file: AVAudioFile?
+    private var fileURL: URL?
+    private var encodedFrameCount = 0
+    private var running = false
+    private var captureStart = Date()
+    /// Whether `engine.start()` succeeded for the current capture
+    /// (see `stopEngineIfStarted`).
+    @MainActor private var engineStarted = false
+    @MainActor private var configChangeObserver: NSObjectProtocol?
+    /// Called on the capture queue with each batch of encoded AAC frames.
+    var onFrames: (([Data]) -> Void)?
+
+    enum CaptureError: Error {
+        case inputUnavailable
+        case audioSetupFailed
+    }
+
+    init(coordinator: AudioSessionCoordinator = .shared) {
+        self.coordinator = coordinator
+        self.sessionLease = PTTCaptureSessionLease(coordinator: coordinator)
+    }
+
+    deinit {
+        sessionLease.release()
+    }
+
+    /// Async because acquiring the session hops its blocking IPC off the main
+    /// actor (a PTT press used to stall main >1 s in `setActive`); the engine
+    /// itself still starts back on main once the session is configured.
+    @MainActor
+    func start(outputURL: URL) async throws {
+        let generation = captureGeneration.begin()
+        let token = try await coordinator.acquire(.capture) { [weak self] in
+            self?.handleInterruption(for: generation)
+        }
+        // The hold ended (stop/cancel) while the session was activating:
+        // starting the engine now would leave a hot mic after release.
+        guard captureGeneration.isCurrent(generation) else {
+            coordinator.release(token)
+            throw CancellationError()
+        }
+        sessionLease.install(token)
+        do {
+            try beginCapture(outputURL: outputURL, generation: generation)
+        } catch {
+            releaseSessionToken()
+            throw error
+        }
+    }
+
+    @MainActor
+    private func beginCapture(outputURL: URL, generation: UInt) throws {
+        // Fresh engine per capture so its input unit binds to the session
+        // that is active *now* (see `engine` doc comment).
+        engine = AVAudioEngine()
+        let inputFormat = engine.inputNode.outputFormat(forBus: 0)
+        guard inputFormat.sampleRate > 0, inputFormat.channelCount > 0 else {
+            SecureLogger.error("PTT: capture input unavailable (input reports \(Int(inputFormat.sampleRate)) Hz, \(inputFormat.channelCount) ch)", category: .session)
+            throw CaptureError.inputUnavailable
+        }
+        guard let resampler = PTTInputResampler(inputFormat: inputFormat),
+              let encoder = PTTFrameEncoder(),
+              let pcmFormat = PTTAudioFormat.pcmFormat
+        else { throw CaptureError.audioSetupFailed }
+
+        let file = try AVAudioFile(
+            forWriting: outputURL,
+            settings: PTTAudioFormat.voiceNoteFileSettings,
+            commonFormat: pcmFormat.commonFormat,
+            interleaved: pcmFormat.isInterleaved
+        )
+
+        queue.sync {
+            self.resampler = resampler
+            self.encoder = encoder
+            self.file = file
+            self.fileURL = outputURL
+            self.encodedFrameCount = 0
+            self.captureStart = Date()
+            self.running = true
+        }
+
+        engine.inputNode.installTap(onBus: 0, bufferSize: 4096, format: inputFormat) { [weak self] buffer, _ in
+            self?.queue.async { self?.process(buffer, generation: generation) }
+        }
+        // Route/category changes reconfigure the engine underneath the tap;
+        // stop and finalize cleanly — the .m4a captured so far still sends.
+        // Registered before start() so no reconfigure lands unobserved
+        // (handleInterruption also validates this capture generation).
+        configChangeObserver = NotificationCenter.default.addObserver(
+            forName: .AVAudioEngineConfigurationChange,
+            object: engine,
+            queue: .main
+        ) { [weak self] _ in
+            Task { @MainActor [weak self] in
+                self?.handleInterruption(for: generation)
+            }
+        }
+        engine.prepare()
+        do {
+            try engine.start()
+        } catch {
+            SecureLogger.error("PTT: capture engine failed to start (input: \(Int(inputFormat.sampleRate)) Hz, \(inputFormat.channelCount) ch): \(error)", category: .session)
+            if let observer = configChangeObserver {
+                NotificationCenter.default.removeObserver(observer)
+                configChangeObserver = nil
+            }
+            engine.inputNode.removeTap(onBus: 0)
+            queue.sync { self.teardown(deleteFile: true) }
+            throw error
+        }
+        engineStarted = true
+        SecureLogger.info("PTT: capture engine running (input: \(Int(inputFormat.sampleRate)) Hz, \(inputFormat.channelCount) ch)", category: .session)
+    }
+
+    /// Stops capture and finalizes the `.m4a`. Returns the file URL and the
+    /// number of encoded AAC frames (each `PTTAudioFormat.frameDuration` long).
+    @MainActor
+    func stop() -> (url: URL?, encodedFrames: Int) {
+        captureGeneration.invalidate()
+        stopEngineIfStarted()
+        let result: (URL?, Int) = queue.sync {
+            let url = fileURL
+            let frames = encodedFrameCount
+            teardown(deleteFile: false)
+            return (url, frames)
+        }
+        releaseSessionToken()
+        return result
+    }
+
+    @MainActor
+    func cancel() {
+        captureGeneration.invalidate()
+        stopEngineIfStarted()
+        queue.sync { teardown(deleteFile: true) }
+        releaseSessionToken()
+    }
+
+    /// Audio session interrupted (call, Siri) or the engine was reconfigured
+    /// mid-capture: behave like `stop()` — finalize the `.m4a` container but
+    /// keep `fileURL`/`encodedFrameCount` so the caller's pending `stop()`
+    /// still returns the note for delivery.
+    @MainActor
+    private func handleInterruption(for generation: UInt) {
+        // Also invalidate a start whose acquire has registered its token but
+        // has not returned to this actor yet. Without this bump the callback
+        // is lost while `engineStarted == false`, and the resumed start can
+        // open the mic after the stop signal.
+        guard captureGeneration.invalidate(ifCurrent: generation) else { return }
+        guard engineStarted else {
+            releaseSessionToken()
+            return
+        }
+        stopEngineIfStarted()
+        queue.sync {
+            running = false
+            // Releasing the AVAudioFile finalizes the .m4a container.
+            file = nil
+            encoder = nil
+            resampler = nil
+        }
+        releaseSessionToken()
+        SecureLogger.info("PTT: capture interrupted — burst finalized early", category: .session)
+    }
+
+    /// Touching `inputNode` on an engine that never started instantiates its
+    /// input unit against whatever session is active and spams AURemoteIO
+    /// errors — a canceled-before-start hold must not touch the engine.
+    @MainActor
+    private func stopEngineIfStarted() {
+        if let observer = configChangeObserver {
+            NotificationCenter.default.removeObserver(observer)
+            configChangeObserver = nil
+        }
+        guard engineStarted else { return }
+        engineStarted = false
+        engine.inputNode.removeTap(onBus: 0)
+        engine.stop()
+    }
+
+    @MainActor
+    private func releaseSessionToken() {
+        sessionLease.release()
+    }
+
+    // MARK: - Capture queue
+
+    private func process(_ buffer: AVAudioPCMBuffer, generation: UInt) {
+        guard captureGeneration.isCurrent(generation),
+              running,
+              Date().timeIntervalSince(captureStart) < Self.maxCaptureDuration,
+              let resampled = resampler?.resample(buffer)
+        else { return }
+
+        do {
+            try file?.write(from: resampled)
+        } catch {
+            SecureLogger.error("PTT capture file write failed: \(error)", category: .session)
+        }
+
+        guard let frames = encoder?.encode(resampled), !frames.isEmpty else { return }
+        encodedFrameCount += frames.count
+        onFrames?(frames)
+    }
+
+    private func teardown(deleteFile: Bool) {
+        running = false
+        // Releasing the AVAudioFile finalizes the .m4a container.
+        file = nil
+        encoder = nil
+        resampler = nil
+        if deleteFile, let url = fileURL {
+            try? FileManager.default.removeItem(at: url)
+        }
+        fileURL = nil
+    }
+}

bitchat/Features/voice/PTTSettings.swift

@@ -0,0 +1,39 @@
+//
+// PTTSettings.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import Foundation
+#if os(iOS)
+import UIKit
+#elseif os(macOS)
+import AppKit
+#endif
+
+/// User preference for live push-to-talk voice. One switch controls both
+/// directions: streaming your holds live, and auto-playing inbound bursts.
+/// Off means voice messages behave exactly like classic voice notes.
+enum PTTSettings {
+    private static let liveVoiceEnabledKey = "ptt.liveVoiceEnabled"
+
+    static var liveVoiceEnabled: Bool {
+        get { UserDefaults.standard.object(forKey: liveVoiceEnabledKey) as? Bool ?? true }
+        set { UserDefaults.standard.set(newValue, forKey: liveVoiceEnabledKey) }
+    }
+
+    /// Autoplay is foreground-only: audio must never start from the
+    /// background.
+    @MainActor
+    static var isAppActive: Bool {
+        #if os(iOS)
+        return UIApplication.shared.applicationState == .active
+        #elseif os(macOS)
+        return NSApplication.shared.isActive
+        #else
+        return true
+        #endif
+    }
+}

bitchat/Features/voice/VoiceCaptureSession.swift

@@ -0,0 +1,237 @@
+//
+// VoiceCaptureSession.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import BitFoundation
+import BitLogger
+import Foundation
+
+/// Capture backend behind the composer's hold-to-record gesture.
+/// `VoiceRecordingViewModel` drives one session per press; the concrete type
+/// decides *how* audio leaves the device: `VoiceNoteCaptureSession` records a
+/// note delivered on release (today's behavior), `PTTLiveVoiceSession`
+/// additionally streams frames live while the button is held.
+@MainActor
+protocol VoiceCaptureSession: AnyObject {
+    /// Whether audio is leaving the device in real time while recording —
+    /// drives the composer's LIVE treatment.
+    var isLive: Bool { get }
+    func requestPermission() async -> Bool
+    func start() async throws
+    /// Stops capture and returns the finalized voice-note file, or nil when
+    /// nothing valid was captured.
+    func finish() async -> URL?
+    func cancel() async
+}
+
+/// The classic record-then-send backend, wrapping the shared `VoiceRecorder`.
+@MainActor
+final class VoiceNoteCaptureSession: VoiceCaptureSession {
+    private let recorder: VoiceRecorder
+    private let owner = VoiceRecorder.RecordingOwner()
+
+    var isLive: Bool { false }
+
+    init(recorder: VoiceRecorder = .shared) {
+        self.recorder = recorder
+    }
+
+    func requestPermission() async -> Bool {
+        await recorder.requestPermission()
+    }
+
+    func start() async throws {
+        try await recorder.startRecording(owner: owner)
+    }
+
+    func finish() async -> URL? {
+        await recorder.stopRecording(owner: owner)
+    }
+
+    func cancel() async {
+        await recorder.cancelRecording(owner: owner)
+    }
+}
+
+/// Testable surface of the live capture engine. Production uses
+/// `PTTCaptureEngine`; tests can supply captured-frame counts without opening
+/// real audio hardware.
+@MainActor
+protocol PTTCapturing: AnyObject {
+    var onFrames: (([Data]) -> Void)? { get set }
+    func start(outputURL: URL) async throws
+    func stop() -> (url: URL?, encodedFrames: Int)
+    func cancel()
+}
+
+extension PTTCaptureEngine: PTTCapturing {}
+
+/// Live push-to-talk backend: streams `VoiceBurstPacket`s to one peer while
+/// recording, then finalizes the same audio as a standard voice note whose
+/// file name carries the burst ID (`voice_<burstID>.m4a`) so receivers that
+/// heard the live stream absorb the note silently instead of seeing a
+/// duplicate.
+@MainActor
+final class PTTLiveVoiceSession: VoiceCaptureSession {
+    let burstID: Data
+
+    private let sendPacket: (Data) -> Void
+    private let capture: any PTTCapturing
+    private let now: () -> Date
+    /// Capture-queue-confined stream state: packetizes frames and lazily
+    /// emits START so packet order is guaranteed by queue serialization.
+    private final class StreamState {
+        var packetizer: VoiceBurstPacketizer
+        var sentStart = false
+        init(burstID: Data) {
+            packetizer = VoiceBurstPacketizer(burstID: burstID)
+        }
+    }
+    private let stream: StreamState
+    private var startDate: Date?
+    private var completed = false
+
+    var isLive: Bool { true }
+
+    /// - Parameter sendPacket: delivers one encoded `VoiceBurstPacket` to the
+    ///   target peer; must be safe to call from any queue (BLEService hops to
+    ///   its own message queue internally).
+    init(
+        sendPacket: @escaping (Data) -> Void,
+        capture: (any PTTCapturing)? = nil,
+        now: @escaping () -> Date = Date.init,
+        burstID: Data? = nil
+    ) {
+        self.burstID = burstID ?? VoiceBurstPacket.makeBurstID()
+        self.sendPacket = sendPacket
+        self.capture = capture ?? PTTCaptureEngine()
+        self.now = now
+        self.stream = StreamState(burstID: self.burstID)
+    }
+
+    func requestPermission() async -> Bool {
+        await VoiceRecorder.shared.requestPermission()
+    }
+
+    func start() async throws {
+        let outputURL = try Self.makeOutputURL(burstID: burstID)
+        let sendPacket = sendPacket
+        let stream = stream
+        capture.onFrames = { frames in
+            if !stream.sentStart {
+                stream.sentStart = true
+                if let start = VoiceBurstPacket(
+                    burstID: stream.packetizer.burstID,
+                    seq: 0,
+                    kind: .start(codec: .aacLC16kMono)
+                ) {
+                    sendPacket(start.encode())
+                }
+            }
+            for frame in frames {
+                for packet in stream.packetizer.add(frame) {
+                    sendPacket(packet)
+                }
+            }
+            // Flush per callback batch: at ~130-byte frames the budget fits
+            // one frame per packet anyway, and holding residue would add
+            // ~100 ms of avoidable latency.
+            for packet in stream.packetizer.flush() {
+                sendPacket(packet)
+            }
+        }
+        do {
+            try await capture.start(outputURL: outputURL)
+        } catch is CancellationError {
+            // The hold was released/canceled while the session acquire was
+            // in flight: the engine never started and the capture already
+            // handed its token back — nothing to retry. A coordinator-side
+            // interruption during handoff also cancels acquire, but that is
+            // not a successful start and must propagate to the view model.
+            guard completed else { throw CancellationError() }
+            return
+        } catch {
+            // The HAL can briefly report a dead input right after the audio
+            // session (re)activates while the route settles; one retry after
+            // a short pause covers it (observed on iPhone field tests).
+            SecureLogger.warning("PTT: capture start failed (\(error)) — retrying once after route settle", category: .session)
+            try? await Task.sleep(nanoseconds: 150_000_000)
+            // The hold may have been released/canceled during the retry pause.
+            // Starting the mic now would leave it live and streaming after the
+            // user let go, so bail instead of opening a hot mic.
+            guard !completed else {
+                capture.cancel()
+                return
+            }
+            try await capture.start(outputURL: outputURL)
+        }
+        startDate = now()
+        SecureLogger.info("PTT: live burst \(burstID.hexEncodedString()) capture started", category: .session)
+    }
+
+    func finish() async -> URL? {
+        guard !completed else { return nil }
+        completed = true
+
+        let elapsed = startDate.map { now().timeIntervalSince($0) } ?? 0
+        let (url, encodedFrames) = capture.stop()
+        // stop() drained the capture queue, so touching `stream` is safe now.
+
+        let capturedDuration = Double(encodedFrames) * PTTAudioFormat.frameDuration
+
+        guard elapsed >= VoiceRecorder.minRecordingDuration,
+              capturedDuration >= VoiceRecorder.minRecordingDuration,
+              let url
+        else {
+            sendControlPacket(.canceled)
+            if let url {
+                try? FileManager.default.removeItem(at: url)
+            }
+            return nil
+        }
+
+        for packet in stream.packetizer.flush() {
+            sendPacket(packet)
+        }
+        let durationMs = UInt32((capturedDuration * 1000).rounded())
+        sendControlPacket(.end(totalDataPackets: stream.packetizer.dataPacketCount, durationMs: durationMs))
+        SecureLogger.info("PTT: live burst \(burstID.hexEncodedString()) finished — \(stream.packetizer.dataPacketCount) data packets, \(encodedFrames) frames, \(durationMs) ms", category: .session)
+        return url
+    }
+
+    func cancel() async {
+        let alreadyCompleted = completed
+        completed = true
+        // Always tear down the capture, even if a quick-release already marked
+        // us completed: the engine can start late (during start()'s retry
+        // pause), and only capture.cancel() stops the mic and deactivates the
+        // session. It is idempotent, so a redundant call is harmless.
+        capture.cancel()
+        if !alreadyCompleted {
+            sendControlPacket(.canceled)
+        }
+    }
+
+    private func sendControlPacket(_ kind: VoiceBurstPacket.Kind) {
+        guard let packet = VoiceBurstPacket(burstID: burstID, seq: stream.packetizer.nextSeq, kind: kind) else { return }
+        sendPacket(packet.encode())
+    }
+
+    private static func makeOutputURL(burstID: Data) throws -> URL {
+        let base = try FileManager.default.url(
+            for: .applicationSupportDirectory,
+            in: .userDomainMask,
+            appropriateFor: nil,
+            create: true
+        )
+        let directory = base
+            .appendingPathComponent("files", isDirectory: true)
+            .appendingPathComponent("voicenotes/outgoing", isDirectory: true)
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true, attributes: nil)
+        return directory.appendingPathComponent("voice_\(burstID.hexEncodedString()).m4a")
+    }
+}

bitchat/Features/voice/VoiceNotePlaybackController.swift

@@ -9,6 +9,9 @@ final class VoiceNotePlaybackController: NSObject, ObservableObject, AVAudioPlay
     @Published private(set) var duration: TimeInterval = 0
     @Published private(set) var progress: Double = 0
 
+    /// Internal lifecycle visibility for deterministic acquisition tests.
+    var isPlaybackStartPending: Bool { sessionAcquireInFlight }
+
     /// rounded so 4.9s shows "00:05"
     var roundedDuration: Int {
         guard duration.isFinite else { return 0 }
@@ -24,9 +27,24 @@ final class VoiceNotePlaybackController: NSObject, ObservableObject, AVAudioPlay
     private var player: AVAudioPlayer?
     private var timer: Timer?
     private var url: URL
+    /// Test seam; `AudioSessionCoordinator.shared` when nil.
+    private let sessionCoordinatorOverride: AudioSessionCoordinator?
+    /// Injectable so tests don't fight over the app-wide exclusive-playback
+    /// slot (a parallel test's `play()` would pause this controller mid-test).
+    private let exclusivity: VoiceNotePlaybackCoordinator
+    private var sessionToken: AudioSessionCoordinator.Token?
+    /// A session acquire is in flight (it suspends off-main for the blocking
+    /// session IPC); gates against double acquisition on rapid play taps.
+    private var sessionAcquireInFlight = false
 
-    init(url: URL) {
+    init(
+        url: URL,
+        sessionCoordinator: AudioSessionCoordinator? = nil,
+        exclusivity: VoiceNotePlaybackCoordinator? = nil
+    ) {
         self.url = url
+        self.sessionCoordinatorOverride = sessionCoordinator
+        self.exclusivity = exclusivity ?? .shared
         super.init()
         // Don't load anything eagerly - wait until user interaction or view is fully displayed
     }
@@ -51,6 +69,16 @@ final class VoiceNotePlaybackController: NSObject, ObservableObject, AVAudioPlay
 
     deinit {
         timer?.invalidate()
+        player?.stop()
+        // A per-row @StateObject can be discarded mid-playback (navigating
+        // away). Leaking the token here would hold the session forever —
+        // never deactivating it, and pinning any escalated category for the
+        // app's lifetime. `release` is fire-and-forget onto the coordinator's
+        // queue, so it is deinit-safe: only the Sendable token crosses.
+        if let token = sessionToken {
+            sessionToken = nil
+            (sessionCoordinatorOverride ?? .shared).release(token)
+        }
     }
 
     func replaceURL(_ url: URL) {
@@ -68,11 +96,15 @@ final class VoiceNotePlaybackController: NSObject, ObservableObject, AVAudioPlay
 
     func play() {
         guard ensurePlayerReady() else { return }
-        VoiceNotePlaybackCoordinator.shared.activate(self)
+        exclusivity.activate(self)
-        player?.play()
+        isPlaying = true
         startTimer()
         updateProgress()
-        isPlaying = true
+        // Acquired here (not in ensurePlayerReady): scrubbing a paused note
+        // must not hold the session while nothing is audible. The session
+        // calls block on audio-server IPC, so they run off the main thread;
+        // the player starts once the session is configured.
+        startPlayerAfterAcquiringSession()
     }
 
     func pause() {
@@ -80,6 +112,7 @@ final class VoiceNotePlaybackController: NSObject, ObservableObject, AVAudioPlay
         stopTimer()
         updateProgress()
         isPlaying = false
+        releaseSession()
     }
 
     func stop() {
@@ -88,7 +121,8 @@ final class VoiceNotePlaybackController: NSObject, ObservableObject, AVAudioPlay
         stopTimer()
         updateProgress()
         isPlaying = false
-        VoiceNotePlaybackCoordinator.shared.deactivate(self)
+        releaseSession()
+        exclusivity.deactivate(self)
     }
 
     func seek(to fraction: Double) {
@@ -96,8 +130,11 @@ final class VoiceNotePlaybackController: NSObject, ObservableObject, AVAudioPlay
         let clamped = max(0, min(1, fraction))
         if let player = player {
             player.currentTime = clamped * player.duration
-            if isPlaying {
+            // While the session acquire is still in flight, don't start
-                player.play()
+            // audio pre-activation — the pending acquire's completion starts
+            // playback (from the new position) once the session resolves.
+            if isPlaying, !sessionAcquireInFlight {
+                startPreparedPlayer()
             }
             updateProgress()
         }
@@ -112,18 +149,20 @@ final class VoiceNotePlaybackController: NSObject, ObservableObject, AVAudioPlay
             self.stopTimer()
             self.updateProgress()
             self.isPlaying = false
-            VoiceNotePlaybackCoordinator.shared.deactivate(self)
+            self.releaseSession()
+            self.exclusivity.deactivate(self)
         }
     }
 
     // MARK: - Private Helpers
 
     private func preparePlayer(for url: URL) {
-        // Prepare player synchronously (only called when playback is requested)
+        // Load metadata synchronously, but do not call prepareToPlay here:
+        // paused scrubbing reaches this path and must not acquire playback
+        // hardware outside the AudioSessionCoordinator token lifetime.
         do {
             let player = try AVAudioPlayer(contentsOf: url)
             player.delegate = self
-            player.prepareToPlay()
             self.player = player
             duration = player.duration
             currentTime = player.currentTime
@@ -141,16 +180,79 @@ final class VoiceNotePlaybackController: NSObject, ObservableObject, AVAudioPlay
         if player == nil {
             preparePlayer(for: url)
         }
-        #if os(iOS)
+        return player != nil
-        let session = AVAudioSession.sharedInstance()
+    }
+
+    /// All entry points (SwiftUI actions, `pauseForExclusivity`, the
+    /// delegate's main-queue hop) run on the main thread; the acquire itself
+    /// suspends while the blocking session IPC runs on the coordinator's
+    /// queue, and the player starts when it resolves. An acquire failure
+    /// leaves playback stopped: starting without a registered token would
+    /// bypass interruption fan-out and the coordinator's refcount. A
+    /// pause/stop landing mid-acquire hands the token straight back.
+    private func startPlayerAfterAcquiringSession() {
+        if sessionToken != nil {
+            startPreparedPlayer()
+            return
+        }
+        guard !sessionAcquireInFlight else { return }
+        sessionAcquireInFlight = true
+        let coordinator = sessionCoordinatorOverride ?? AudioSessionCoordinator.shared
+        Task { @MainActor [weak self] in
+            var token: AudioSessionCoordinator.Token?
             do {
-            try session.setCategory(.playback, mode: .spokenAudio, options: [.mixWithOthers])
+                token = try await coordinator.acquire(.playback) { [weak self] in
-            try session.setActive(true, options: [])
+                    self?.pause()
+                }
             } catch {
                 SecureLogger.error("Failed to activate audio session: \(error)", category: .session)
             }
-        #endif
+            guard let self else {
-        return player != nil
+                // The row was discarded while acquiring; deinit had no token
+                // to release yet.
+                token.map(coordinator.release)
+                return
+            }
+            self.sessionAcquireInFlight = false
+            guard self.isPlaying else {
+                // Paused/stopped while the session was activating.
+                token.map(coordinator.release)
+                return
+            }
+            guard let token else {
+                self.failPlaybackStart()
+                return
+            }
+            self.sessionToken = token
+            self.startPreparedPlayer()
+        }
+    }
+
+    @discardableResult
+    private func startPreparedPlayer() -> Bool {
+        guard let player,
+              player.prepareToPlay(),
+              player.play()
+        else {
+            SecureLogger.error("Voice note player refused to start " + url.lastPathComponent, category: .session)
+            failPlaybackStart()
+            return false
+        }
+        return true
+    }
+
+    private func failPlaybackStart() {
+        player?.pause()
+        stopTimer()
+        updateProgress()
+        isPlaying = false
+        releaseSession()
+        exclusivity.deactivate(self)
+    }
+
+    private func releaseSession() {
+        sessionToken.map((sessionCoordinatorOverride ?? .shared).release)
+        sessionToken = nil
     }
 
     private func startTimer() {
@@ -181,25 +283,75 @@ final class VoiceNotePlaybackController: NSObject, ObservableObject, AVAudioPlay
     }
 }
 
-/// Ensures only one voice note plays at a time.
+/// Something that can hold the app's single audio-playback slot and yield it
+/// when another playback starts (voice notes pause; live bursts stop).
+protocol ExclusivePlayback: AnyObject {
+    func pauseForExclusivity()
+}
+
+extension VoiceNotePlaybackController: ExclusivePlayback {
+    func pauseForExclusivity() {
+        pause()
+    }
+}
+
+/// Ensures only one voice playback (note or live burst) runs at a time.
 final class VoiceNotePlaybackCoordinator {
     static let shared = VoiceNotePlaybackCoordinator()
 
-    private weak var activeController: VoiceNotePlaybackController?
+    struct Reservation: Equatable {
+        fileprivate let generation: UInt64
+    }
 
-    private init() {}
+    private weak var activeController: (any ExclusivePlayback)?
+    private weak var latestReservedController: (any ExclusivePlayback)?
+    private var latestReservation = Reservation(generation: 0)
 
-    func activate(_ controller: VoiceNotePlaybackController) {
+    /// Internal so tests can isolate their own exclusivity slot; the app
+    /// uses `shared`.
+    init() {}
+
+    /// Records playback intent without interrupting audio that is already
+    /// audible. Async starters reserve before suspension, then activate only
+    /// after their audio resource is ready.
+    func reserve(_ controller: any ExclusivePlayback) -> Reservation {
+        latestReservation = Reservation(generation: latestReservation.generation &+ 1)
+        latestReservedController = controller
+        return latestReservation
+    }
+
+    /// Immediate activation for synchronous/user-initiated playback.
+    @discardableResult
+    func activate(_ controller: any ExclusivePlayback) -> Reservation {
+        let reservation = reserve(controller)
+        _ = activate(controller, reservation: reservation)
+        return reservation
+    }
+
+    /// Commits an earlier reservation only when it is still the newest
+    /// playback request. This prevents an older async acquire from stealing
+    /// the floor after a newer play gesture.
+    @discardableResult
+    func activate(_ controller: any ExclusivePlayback, reservation: Reservation) -> Bool {
+        guard isCurrent(reservation, for: controller) else { return false }
         if activeController === controller {
-            return
+            return true
         }
-        activeController?.pause()
+        activeController?.pauseForExclusivity()
         activeController = controller
+        return true
     }
 
-    func deactivate(_ controller: VoiceNotePlaybackController) {
+    func isCurrent(_ reservation: Reservation, for controller: any ExclusivePlayback) -> Bool {
+        latestReservation == reservation && latestReservedController === controller
+    }
+
+    func deactivate(_ controller: any ExclusivePlayback) {
         if activeController === controller {
             activeController = nil
         }
+        if latestReservedController === controller {
+            latestReservedController = nil
+        }
     }
 }

bitchat/Features/voice/VoiceRecorder.swift

@@ -1,22 +1,95 @@
 import Foundation
 import AVFoundation
 
+/// The small surface of `AVAudioRecorder` that `VoiceRecorder` owns. Keeping
+/// it behind a protocol lets lifecycle races be tested without opening the
+/// microphone on the test host.
+protocol VoiceAudioRecording: AnyObject {
+    var isRecording: Bool { get }
+    var isMeteringEnabled: Bool { get set }
+    func prepareToRecord() -> Bool
+    func record(forDuration duration: TimeInterval) -> Bool
+    func stop()
+}
+
+extension AVAudioRecorder: VoiceAudioRecording {}
+
+protocol VoiceAudioRecorderCreating {
+    func makeRecorder(url: URL) throws -> any VoiceAudioRecording
+}
+
+private struct SystemVoiceAudioRecorderFactory: VoiceAudioRecorderCreating {
+    func makeRecorder(url: URL) throws -> any VoiceAudioRecording {
+        let settings: [String: Any] = [
+            AVFormatIDKey: kAudioFormatMPEG4AAC,
+            AVSampleRateKey: 16_000,
+            AVNumberOfChannelsKey: 1,
+            AVEncoderBitRateKey: 16_000
+        ]
+        return try AVAudioRecorder(url: url, settings: settings)
+    }
+}
+
 /// Manages audio capture for mesh voice notes with predictable encoding settings.
 actor VoiceRecorder {
-    enum RecorderError: Error {
+    enum RecorderError: Error, Equatable {
         case microphoneAccessDenied
-        case recorderInitializationFailed
         case recordingInProgress
+        case failedToStartRecording
     }
 
     static let shared = VoiceRecorder()
 
-    private let paddingInterval: TimeInterval = 0.5
-    private let maxRecordingDuration: TimeInterval = 120
     static let minRecordingDuration: TimeInterval = 1
 
-    private var recorder: AVAudioRecorder?
+    /// Identity of one press/hold. Every lifecycle mutation must present the
+    /// same owner that started the recorder, so a stale finish or cancel from
+    /// another hold cannot stop or delete the current recording.
+    final class RecordingOwner: @unchecked Sendable {}
+
+    /// Test-only scheduling seams for lifecycle boundaries that otherwise rely
+    /// on wall-clock sleeps. Production uses the real padding delay.
+    struct TestingHooks: Sendable {
+        let waitForStopPadding: (@Sendable (TimeInterval) async -> Void)?
+
+        init(waitForStopPadding: (@Sendable (TimeInterval) async -> Void)? = nil) {
+            self.waitForStopPadding = waitForStopPadding
+        }
+    }
+
+    private let sessionCoordinator: AudioSessionCoordinator
+    private let recorderFactory: any VoiceAudioRecorderCreating
+    private let permissionGranted: () -> Bool
+    private let paddingInterval: TimeInterval
+    private let maxRecordingDuration: TimeInterval
+    private let outputDirectory: URL?
+    private let testingHooks: TestingHooks
+
+    private var recorder: (any VoiceAudioRecording)?
     private var currentURL: URL?
+    private var sessionToken: AudioSessionCoordinator.Token?
+    private var activeOwner: RecordingOwner?
+    /// True only while `startRecording()` is suspended in session acquire.
+    /// A second start is rejected instead of superseding the first one.
+    private var startInFlight = false
+
+    init(
+        sessionCoordinator: AudioSessionCoordinator = .shared,
+        recorderFactory: any VoiceAudioRecorderCreating = SystemVoiceAudioRecorderFactory(),
+        permissionGranted: (() -> Bool)? = nil,
+        paddingInterval: TimeInterval = 0.5,
+        maxRecordingDuration: TimeInterval = 120,
+        outputDirectory: URL? = nil,
+        testingHooks: TestingHooks = TestingHooks()
+    ) {
+        self.sessionCoordinator = sessionCoordinator
+        self.recorderFactory = recorderFactory
+        self.permissionGranted = permissionGranted ?? Self.hasSystemPermission
+        self.paddingInterval = paddingInterval
+        self.maxRecordingDuration = maxRecordingDuration
+        self.outputDirectory = outputDirectory
+        self.testingHooks = testingHooks
+    }
 
     // MARK: - Permissions
 
@@ -42,82 +115,130 @@ actor VoiceRecorder {
     // MARK: - Recording Lifecycle
 
     @discardableResult
-    func startRecording() throws -> URL {
+    func startRecording(owner: RecordingOwner) async throws -> URL {
-        if recorder?.isRecording == true {
+        if activeOwner != nil {
             throw RecorderError.recordingInProgress
         }
 
-        #if os(iOS)
+        guard permissionGranted() else {
-        let session = AVAudioSession.sharedInstance()
-        guard session.recordPermission == .granted else {
             throw RecorderError.microphoneAccessDenied
         }
-        #if targetEnvironment(simulator)
+
-        // allowBluetoothHFP is not available on iOS Simulator
+        activeOwner = owner
-        try session.setCategory(
+        startInFlight = true
-            .playAndRecord,
+
-            mode: .default,
+        // The acquire suspends while the blocking session IPC runs on the
-            options: [.defaultToSpeaker, .allowBluetoothA2DP]
+        // coordinator's queue (never this actor's thread or main).
-        )
+        let token: AudioSessionCoordinator.Token
-        #else
+        do {
-        try session.setCategory(
+            token = try await sessionCoordinator.acquire(.capture) { [weak self] in
-            .playAndRecord,
+                Task { await self?.handleSessionInterruption(for: owner) }
-            mode: .default,
+            }
-            options: [.defaultToSpeaker, .allowBluetoothA2DP, .allowBluetoothHFP]
+        } catch {
-        )
+            guard activeOwner === owner else {
-        #endif
+                throw CancellationError()
-        try session.setActive(true, options: .notifyOthersOnDeactivation)
+            }
-        #endif
+            startInFlight = false
-        #if os(macOS)
+            activeOwner = nil
-        guard AVCaptureDevice.authorizationStatus(for: .audio) == .authorized else {
+            throw error
-            throw RecorderError.microphoneAccessDenied
         }
-        #endif
 
-        let outputURL = try makeOutputURL()
+        // Actor reentrancy: release/cancel may have ended this hold while the
-        let settings: [String: Any] = [
+        // blocking session activation was still in progress.
-            AVFormatIDKey: kAudioFormatMPEG4AAC,
+        guard activeOwner === owner, startInFlight else {
-            AVSampleRateKey: 16_000,
+            sessionCoordinator.release(token)
-            AVNumberOfChannelsKey: 1,
+            throw CancellationError()
-            AVEncoderBitRateKey: 16_000
+        }
-        ]
+        startInFlight = false
+        sessionToken = token
 
-        let audioRecorder = try AVAudioRecorder(url: outputURL, settings: settings)
+        var outputURL: URL?
+        do {
+            let newURL = try makeOutputURL()
+            outputURL = newURL
+            let audioRecorder = try recorderFactory.makeRecorder(url: newURL)
             audioRecorder.isMeteringEnabled = true
-        audioRecorder.prepareToRecord()
+            guard audioRecorder.prepareToRecord() else {
-        audioRecorder.record(forDuration: maxRecordingDuration)
+                throw RecorderError.failedToStartRecording
+            }
+            guard audioRecorder.record(forDuration: maxRecordingDuration) else {
+                throw RecorderError.failedToStartRecording
+            }
 
             recorder = audioRecorder
-        currentURL = outputURL
+            currentURL = newURL
-        return outputURL
+            return newURL
+        } catch {
+            releaseSessionToken()
+            recorder = nil
+            currentURL = nil
+            activeOwner = nil
+            if let outputURL {
+                try? FileManager.default.removeItem(at: outputURL)
+            }
+            throw error
+        }
     }
 
-    func stopRecording() async -> URL? {
+    func stopRecording(owner: RecordingOwner) async -> URL? {
-        guard let recorder, recorder.isRecording else {
+        guard activeOwner === owner else { return nil }
-            return currentURL
+
+        // `finish()` can race a still-suspended start on a direct caller even
+        // though the UI normally routes quick releases through cancel().
+        if startInFlight {
+            activeOwner = nil
+            startInFlight = false
+            return nil
+        }
+
+        guard let activeRecorder = recorder else {
+            let sessionURL = currentURL
+            releaseSessionToken()
+            currentURL = nil
+            activeOwner = nil
+            return sessionURL
         }
 
         let sessionURL = currentURL
 
+        if activeRecorder.isRecording, paddingInterval > 0 {
+            if let waitForStopPadding = testingHooks.waitForStopPadding {
+                await waitForStopPadding(paddingInterval)
+            } else {
                 try? await Task.sleep(nanoseconds: UInt64(paddingInterval * 1_000_000_000))
+            }
+        }
 
-        recorder.stop()
+        // Cancellation or interruption may have run during the padding sleep.
+        // Only the recorder whose stop began here may be finalized by it.
+        guard activeOwner === owner,
+              let recorder = self.recorder,
+              recorder === activeRecorder
+        else { return nil }
 
-        // A new session may have started during the sleep — don't touch its state
+        if activeRecorder.isRecording {
-        if self.recorder === recorder {
+            activeRecorder.stop()
-            cleanupSession()
+        }
+        releaseSessionToken()
         self.recorder = nil
         currentURL = nil
-        }
+        activeOwner = nil
 
         return sessionURL
     }
 
-    func cancelRecording() {
+    func cancelRecording(owner: RecordingOwner) async {
+        guard activeOwner === owner else { return }
+
+        // Invalidate ownership before cleanup. An actor-reentrant start whose
+        // session acquire resumes later will observe the mismatch and release
+        // its token without opening the microphone.
+        activeOwner = nil
+        startInFlight = false
         if let recorder, recorder.isRecording {
             recorder.stop()
         }
-        cleanupSession()
+        releaseSessionToken()
         if let currentURL {
             try? FileManager.default.removeItem(at: currentURL)
         }
@@ -125,14 +246,45 @@ actor VoiceRecorder {
         currentURL = nil
     }
 
+    /// The audio session was interrupted (call, Siri) or reconfigured: stop
+    /// the recorder but keep `recorder`/`currentURL` so the caller's pending
+    /// `stopRecording()` still returns the partial note.
+    private func handleSessionInterruption(for owner: RecordingOwner) async {
+        // A callback captured for a released token must never stop a newer
+        // recording. Conversely, an interruption delivered while acquire is
+        // still suspended invalidates that acquire before it can open the mic.
+        guard activeOwner === owner else { return }
+        if startInFlight {
+            activeOwner = nil
+            startInFlight = false
+            return
+        }
+        startInFlight = false
+        if let recorder, recorder.isRecording {
+            recorder.stop()
+        }
+        releaseSessionToken()
+    }
+
     // MARK: - Helpers
 
+    private static func hasSystemPermission() -> Bool {
+        #if os(iOS)
+        AVAudioSession.sharedInstance().recordPermission == .granted
+        #elseif os(macOS)
+        AVCaptureDevice.authorizationStatus(for: .audio) == .authorized
+        #else
+        true
+        #endif
+    }
+
     private func makeOutputURL() throws -> URL {
         let formatter = DateFormatter()
         formatter.dateFormat = "yyyyMMdd_HHmmss"
-        let fileName = "voice_\(formatter.string(from: Date())).m4a"
+        let fileName = "voice_\(formatter.string(from: Date()))_\(UUID().uuidString).m4a"
 
-        let baseDirectory = try applicationFilesDirectory().appendingPathComponent("voicenotes/outgoing", isDirectory: true)
+        let baseDirectory = try outputDirectory
+            ?? applicationFilesDirectory().appendingPathComponent("voicenotes/outgoing", isDirectory: true)
         try FileManager.default.createDirectory(at: baseDirectory, withIntermediateDirectories: true, attributes: nil)
         return baseDirectory.appendingPathComponent(fileName)
     }
@@ -147,9 +299,11 @@ actor VoiceRecorder {
         #endif
     }
 
-    private func cleanupSession() {
+    /// Fire-and-forget: the coordinator hops the blocking deactivation IPC
-        #if os(iOS)
+    /// onto its own queue.
-        try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
+    private func releaseSessionToken() {
-        #endif
+        guard let token = sessionToken else { return }
+        sessionToken = nil
+        sessionCoordinator.release(token)
     }
 }

bitchat/Features/voice/Waveform.swift

@@ -56,12 +56,6 @@ final class WaveformCache {
         }
     }
 
-    func purgeAll() {
-        queue.async(flags: .barrier) { [weak self] in
-            self?.cache.removeAll()
-        }
-    }
-
     private func computeWaveform(url: URL, bins: Int) -> [Float]? {
         guard bins > 0 else { return nil }
         // Use autoreleasepool to manage memory from audio buffer allocations

bitchat/Identity/IdentityModels.swift

@@ -88,8 +88,6 @@ import BitFoundation
 /// Represents the ephemeral layer of identity - short-lived peer IDs that provide network privacy.
 /// These IDs rotate periodically to prevent tracking while maintaining cryptographic relationships.
 struct EphemeralIdentity {
-    let peerID: PeerID          // 8 random bytes
-    let sessionStart: Date
     var handshakeState: HandshakeState
 }
 
@@ -98,7 +96,6 @@ enum HandshakeState {
     case initiated
     case inProgress
     case completed(fingerprint: String)
-    case failed(reason: String)
 }
 
 /// Represents the cryptographic layer of identity - the stable Noise Protocol static key pair.
@@ -110,7 +107,6 @@ struct CryptographicIdentity: Codable {
     // Optional Ed25519 signing public key (used to authenticate public messages)
     var signingPublicKey: Data? = nil
     let firstSeen: Date
-    let lastHandshake: Date?
 }
 
 /// Represents the social layer of identity - user-assigned names and trust relationships.
@@ -126,11 +122,35 @@ struct SocialIdentity: Codable {
     var notes: String?
 }
 
+/// Trust ladder: unknown → casual → vouched → trusted → verified.
+///
+/// Persistence compatibility: `TrustLevel` is stored by its *String* raw
+/// value ("unknown", "casual", …), not by ordinal position, so inserting
+/// `vouched` mid-ladder cannot corrupt previously persisted values — every
+/// pre-existing case keeps the exact raw value it was written with. The
+/// `vouched` tier is additionally never persisted into `SocialIdentity`
+/// (it's recomputed on read from stored vouches), so downgraded builds never
+/// encounter the unfamiliar raw value.
 enum TrustLevel: String, Codable {
-    case unknown = "unknown"
+    case unknown
-    case casual = "casual"
+    case casual
-    case trusted = "trusted"
+    /// Transitively trusted: vouched for by at least one peer *I* verified.
-    case verified = "verified"
+    /// Derived at read time — never written to persistent storage.
+    case vouched
+    case trusted
+    case verified
+}
+
+// MARK: - Vouching (transitive verification)
+
+/// One accepted vouch: a peer I verified (the voucher) attested that they
+/// verified the vouchee. Validity is recomputed on read — a record only
+/// counts while its voucher remains in `verifiedFingerprints` and its
+/// timestamp is within `VouchAttestation.maxAge` — so unverifying a voucher
+/// silently invalidates the vouches they gave without a cascade delete.
+struct VouchRecord: Codable, Equatable {
+    let voucherFingerprint: String
+    let timestamp: Date
 }
 
 // MARK: - Identity Cache
@@ -155,8 +175,20 @@ struct IdentityCache: Codable {
     // Blocked Nostr pubkeys (lowercased hex) for geohash chats
     var blockedNostrPubkeys: Set<String> = []
 
-    // Schema version for future migrations
+    // Vouching (transitive verification). All three fields are Optional so
-    var version: Int = 1
+    // caches persisted before this feature decode cleanly — the synthesized
+    // decoder uses decodeIfPresent for optionals, and a missing key must not
+    // trip the "unreadable cache" recovery path that discards everything.
+
+    // Vouchee fingerprint -> accepted vouches (capped per vouchee)
+    var vouchesByVouchee: [String: [VouchRecord]]? = nil
+
+    // Peer fingerprint -> when we last sent them a vouch batch (rate limit)
+    var vouchBatchSentAt: [String: Date]? = nil
+
+    // Fingerprint -> when we verified it (orders outgoing vouch batches;
+    // entries verified before this field exists sort as oldest)
+    var verifiedAt: [String: Date]? = nil
 }
 
 //

bitchat/Identity/SecureIdentityStateManager.swift

@@ -108,8 +108,6 @@ protocol SecureIdentityStateManagerProtocol {
     func updateSocialIdentity(_ identity: SocialIdentity)
     
     // MARK: Favorites Management
-    func getFavorites() -> Set<String>
-    func setFavorite(_ fingerprint: String, isFavorite: Bool)
     func isFavorite(fingerprint: String) -> Bool
     
     // MARK: Blocked Users Management
@@ -123,7 +121,6 @@ protocol SecureIdentityStateManagerProtocol {
     
     // MARK: Ephemeral Session Management
     func registerEphemeralSession(peerID: PeerID, handshakeState: HandshakeState)
-    func updateHandshakeState(peerID: PeerID, state: HandshakeState)
 
     // MARK: Cleanup
     func clearAllIdentityData()
@@ -133,6 +130,16 @@ protocol SecureIdentityStateManagerProtocol {
     func setVerified(fingerprint: String, verified: Bool)
     func isVerified(fingerprint: String) -> Bool
     func getVerifiedFingerprints() -> Set<String>
+
+    // MARK: Vouching (transitive verification)
+    @discardableResult
+    func recordVouch(voucheeFingerprint: String, voucherFingerprint: String, timestamp: Date) -> Bool
+    func validVouchers(for fingerprint: String) -> [VouchRecord]
+    func isVouched(fingerprint: String) -> Bool
+    func lastVouchBatchSent(to fingerprint: String) -> Date?
+    func markVouchBatchSent(to fingerprint: String, at date: Date)
+    func signingPublicKey(forFingerprint fingerprint: String) -> Data?
+    func mostRecentlyVerifiedFingerprints(limit: Int, excluding fingerprint: String) -> [String]
 }
 
 /// Singleton manager for secure identity state persistence and retrieval.
@@ -151,39 +158,69 @@ final class SecureIdentityStateManager: SecureIdentityStateManagerProtocol {
     // Thread safety
     private let queue = DispatchQueue(label: "bitchat.identity.state", attributes: .concurrent)
     
-    // Debouncing for keychain saves
+    // Pending-save coalescing flag. Reads/writes are serialized on `queue`.
-    private var saveTimer: Timer?
+    // Persistence is done with a fire-and-forget `queue.async(.barrier)` rather
-    private let saveDebounceInterval: TimeInterval = 2.0  // Save at most once every 2 seconds
+    // than a retained DispatchSourceTimer: a lingering, never-cancelled timer
+    // keeps the dispatch machinery alive and prevents the unit-test process from
+    // exiting. (The original code used Timer.scheduledTimer on a GCD queue with
+    // no run loop, so saves never actually fired.)
     private var pendingSave = false
 
     // Encryption key
     private let encryptionKey: SymmetricKey
+    /// True when `encryptionKey` is a throwaway generated this session because the
+    /// persisted key could not be read (device locked / access denied). In that
+    /// state we must NOT persist (it would overwrite the real cache with data the
+    /// next launch can't decrypt) and must NOT delete the existing cache.
+    private let encryptionKeyIsEphemeral: Bool
     
     init(_ keychain: KeychainManagerProtocol) {
         self.keychain = keychain
 
-        // Generate or retrieve encryption key from keychain
+        // Retrieve (or, only on genuine first run, generate) the cache
+        // encryption key. We MUST distinguish "key doesn't exist yet" from a
+        // transient failure (device locked / access denied): the legacy
+        // getIdentityKey(forKey:) collapses both to nil, and generating+saving a
+        // new key deletes the existing one first — permanently orphaning the
+        // encrypted cache on a launch that merely couldn't read the key.
         let loadedKey: SymmetricKey
+        let keyIsEphemeral: Bool
 
-        // Try to load from keychain
+        switch keychain.getIdentityKeyWithResult(forKey: encryptionKeyName) {
-        if let keyData = keychain.getIdentityKey(forKey: encryptionKeyName) {
+        case .success(let keyData):
             loadedKey = SymmetricKey(data: keyData)
+            keyIsEphemeral = false
             SecureLogger.logKeyOperation(.load, keyType: "identity cache encryption key", success: true)
-        }
+
-        // Generate new key if needed
+        case .itemNotFound:
-        else {
+            // Genuine first run: generate and persist a new key.
-            loadedKey = SymmetricKey(size: .bits256)
+            let newKey = SymmetricKey(size: .bits256)
-            let keyData = loadedKey.withUnsafeBytes { Data($0) }
+            let keyData = newKey.withUnsafeBytes { Data($0) }
-            // Save to keychain
             let saved = keychain.saveIdentityKey(keyData, forKey: encryptionKeyName)
+            loadedKey = newKey
+            // If even the save failed, treat the key as ephemeral so we don't
+            // later try to persist a cache the next launch can't read.
+            keyIsEphemeral = !saved
             SecureLogger.logKeyOperation(.generate, keyType: "identity cache encryption key", success: saved)
+
+        case .deviceLocked, .authenticationFailed, .accessDenied, .otherError:
+            // Transient/critical read failure. Do NOT overwrite the persisted
+            // key. Use a session-only ephemeral key; the real key and cache are
+            // left intact for a healthy launch.
+            SecureLogger.warning("Identity cache key unavailable; using ephemeral key for this session (not persisting)", category: .security)
+            loadedKey = SymmetricKey(size: .bits256)
+            keyIsEphemeral = true
         }
 
         self.encryptionKey = loadedKey
+        self.encryptionKeyIsEphemeral = keyIsEphemeral
 
-        // Load identity cache on init
+        // Only read the persisted cache when we hold the real key; with an
+        // ephemeral key the decrypt would fail and discard the real cache.
+        if !keyIsEphemeral {
             loadIdentityCache()
         }
+    }
     
     deinit {
         forceSave()
@@ -211,23 +248,28 @@ final class SecureIdentityStateManager: SecureIdentityStateManagerProtocol {
         }
     }
     
+    /// Persists the cache. Always invoked on `queue` under a barrier (its callers
+    /// run inside `queue.async(.barrier)`), so it simply marks the cache dirty
+    /// and persists it on the same serialized context — no timer, nothing left
+    /// scheduled to keep the process alive.
     private func saveIdentityCache() {
-        // Mark that we need to save
         pendingSave = true
-        
+        performSave()
-        // Cancel any existing timer
-        saveTimer?.invalidate()
-        
-        // Schedule a new save after the debounce interval
-        saveTimer = Timer.scheduledTimer(withTimeInterval: saveDebounceInterval, repeats: false) { [weak self] _ in
-            self?.performSave()
-        }
     }
 
+    /// Writes the cache to the keychain. Must run on `queue` with exclusive
+    /// (barrier) access.
     private func performSave() {
         guard pendingSave else { return }
         pendingSave = false
 
+        // Never persist under an ephemeral key — it would overwrite the real
+        // cache with data the next launch cannot decrypt.
+        guard !encryptionKeyIsEphemeral else {
+            SecureLogger.debug("Skipping identity cache save (ephemeral key this session)", category: .security)
+            return
+        }
+
         do {
             let data = try JSONEncoder().encode(cache)
             let sealedBox = try AES.GCM.seal(data, using: encryptionKey)
@@ -240,9 +282,13 @@ final class SecureIdentityStateManager: SecureIdentityStateManagerProtocol {
         }
     }
 
-    // Force immediate save (for app termination)
+    // Force immediate save (for app termination / lifecycle events). Mutations
+    // already persist synchronously via saveIdentityCache, so this is normally a
+    // no-op (performSave early-returns when nothing is pending). Runs directly on
+    // the caller's thread — deliberately NOT a `queue.sync(barrier)`, which is
+    // reachable from `deinit` and from async tests on the swift-concurrency
+    // cooperative pool where a blocking barrier-sync can starve/deadlock it.
     func forceSave() {
-        saveTimer?.invalidate()
         performSave()
     }
     
@@ -272,21 +318,13 @@ final class SecureIdentityStateManager: SecureIdentityStateManagerProtocol {
                         fingerprint: fingerprint,
                         publicKey: noisePublicKey,
                         signingPublicKey: signingPublicKey ?? existing.signingPublicKey,
-                        firstSeen: existing.firstSeen,
+                        firstSeen: existing.firstSeen
-                        lastHandshake: now
                     )
                     self.cryptographicIdentities[fingerprint] = existing
                 } else {
-                    // Update signing key and lastHandshake
+                    // Update signing key
                     existing.signingPublicKey = signingPublicKey ?? existing.signingPublicKey
-                    let updated = CryptographicIdentity(
+                    self.cryptographicIdentities[fingerprint] = existing
-                        fingerprint: existing.fingerprint,
-                        publicKey: existing.publicKey,
-                        signingPublicKey: existing.signingPublicKey,
-                        firstSeen: existing.firstSeen,
-                        lastHandshake: now
-                    )
-                    self.cryptographicIdentities[fingerprint] = updated
                 }
                 // Persist updated state (already assigned in branches above)
             } else {
@@ -295,8 +333,7 @@ final class SecureIdentityStateManager: SecureIdentityStateManagerProtocol {
                     fingerprint: fingerprint,
                     publicKey: noisePublicKey,
                     signingPublicKey: signingPublicKey,
-                    firstSeen: now,
+                    firstSeen: now
-                    lastHandshake: now
                 )
                 self.cryptographicIdentities[fingerprint] = entry
             }
@@ -461,11 +498,7 @@ final class SecureIdentityStateManager: SecureIdentityStateManagerProtocol {
     
     func registerEphemeralSession(peerID: PeerID, handshakeState: HandshakeState = .none) {
         queue.async(flags: .barrier) {
-            self.ephemeralSessions[peerID] = EphemeralIdentity(
+            self.ephemeralSessions[peerID] = EphemeralIdentity(handshakeState: handshakeState)
-                peerID: peerID,
-                sessionStart: Date(),
-                handshakeState: handshakeState
-            )
         }
     }
     
@@ -511,8 +544,12 @@ final class SecureIdentityStateManager: SecureIdentityStateManagerProtocol {
         queue.async(flags: .barrier) {
             if verified {
                 self.cache.verifiedFingerprints.insert(fingerprint)
+                var verifiedAt = self.cache.verifiedAt ?? [:]
+                verifiedAt[fingerprint] = Date()
+                self.cache.verifiedAt = verifiedAt
             } else {
                 self.cache.verifiedFingerprints.remove(fingerprint)
+                self.cache.verifiedAt?.removeValue(forKey: fingerprint)
             }
 
             // Update trust level if social identity exists
@@ -537,6 +574,159 @@ final class SecureIdentityStateManager: SecureIdentityStateManagerProtocol {
         }
     }
 
+    // MARK: - Vouching (transitive verification)
+
+    /// Maximum vouchers retained per vouchee (most recent kept).
+    static let maxVouchersPerVouchee = 8
+
+    /// Records an accepted vouch, enforcing every accept-policy gate that can
+    /// be evaluated against stored state (signature verification is the
+    /// caller's job — it needs the sender's announce-bound signing key):
+    /// - the voucher must be a fingerprint *I* verified
+    /// - self-vouches are ignored
+    /// - vouches for peers I already verified are ignored (nothing to add)
+    /// - attestations outside the validity window are ignored
+    /// - at most `maxVouchersPerVouchee` vouchers are kept per vouchee
+    ///
+    /// Returns true when the vouch was stored (or refreshed).
+    @discardableResult
+    func recordVouch(voucheeFingerprint: String, voucherFingerprint: String, timestamp: Date) -> Bool {
+        recordVouch(
+            voucheeFingerprint: voucheeFingerprint,
+            voucherFingerprint: voucherFingerprint,
+            timestamp: timestamp,
+            now: Date()
+        )
+    }
+
+    @discardableResult
+    func recordVouch(voucheeFingerprint: String, voucherFingerprint: String, timestamp: Date, now: Date) -> Bool {
+        queue.sync(flags: .barrier) {
+            guard voucheeFingerprint != voucherFingerprint,
+                  self.cache.verifiedFingerprints.contains(voucherFingerprint),
+                  !self.cache.verifiedFingerprints.contains(voucheeFingerprint) else {
+                return false
+            }
+            let age = now.timeIntervalSince(timestamp)
+            guard age <= VouchAttestation.maxAge, age >= -VouchAttestation.maxClockSkew else {
+                return false
+            }
+
+            var records = self.cache.vouchesByVouchee?[voucheeFingerprint] ?? []
+            if let index = records.firstIndex(where: { $0.voucherFingerprint == voucherFingerprint }) {
+                let newest = max(records[index].timestamp, timestamp)
+                records[index] = VouchRecord(voucherFingerprint: voucherFingerprint, timestamp: newest)
+            } else {
+                records.append(VouchRecord(voucherFingerprint: voucherFingerprint, timestamp: timestamp))
+            }
+            // Keep the most recent vouchers up to the cap.
+            records.sort { $0.timestamp > $1.timestamp }
+            let capped = Array(records.prefix(Self.maxVouchersPerVouchee))
+            guard capped.contains(where: { $0.voucherFingerprint == voucherFingerprint }) else {
+                return false // Full of fresher vouches; nothing changed.
+            }
+
+            var vouches = self.cache.vouchesByVouchee ?? [:]
+            vouches[voucheeFingerprint] = capped
+            self.cache.vouchesByVouchee = vouches
+            self.saveIdentityCache()
+            return true
+        }
+    }
+
+    /// The vouches that currently count for `fingerprint`. Validity is
+    /// recomputed here rather than maintained by cascade deletes: a record
+    /// only counts while its voucher is still verified-by-me and its
+    /// timestamp is within the expiry window.
+    func validVouchers(for fingerprint: String) -> [VouchRecord] {
+        validVouchers(for: fingerprint, now: Date())
+    }
+
+    func validVouchers(for fingerprint: String, now: Date) -> [VouchRecord] {
+        queue.sync {
+            self.validVouchersLocked(for: fingerprint, now: now)
+        }
+    }
+
+    /// Requires `queue`.
+    private func validVouchersLocked(for fingerprint: String, now: Date) -> [VouchRecord] {
+        guard let records = cache.vouchesByVouchee?[fingerprint] else { return [] }
+        return records.filter { record in
+            record.voucherFingerprint != fingerprint
+                && cache.verifiedFingerprints.contains(record.voucherFingerprint)
+                && now.timeIntervalSince(record.timestamp) <= VouchAttestation.maxAge
+        }
+    }
+
+    /// True when the peer has at least one valid vouch and no explicit
+    /// verification of ours.
+    func isVouched(fingerprint: String) -> Bool {
+        isVouched(fingerprint: fingerprint, now: Date())
+    }
+
+    func isVouched(fingerprint: String, now: Date) -> Bool {
+        queue.sync {
+            guard !self.cache.verifiedFingerprints.contains(fingerprint) else { return false }
+            return !self.validVouchersLocked(for: fingerprint, now: now).isEmpty
+        }
+    }
+
+    /// The trust level to display: explicit verification wins, then the
+    /// persisted level, with `vouched` layered in (derived, never persisted)
+    /// between `casual` and `trusted`.
+    func effectiveTrustLevel(for fingerprint: String) -> TrustLevel {
+        effectiveTrustLevel(for: fingerprint, now: Date())
+    }
+
+    func effectiveTrustLevel(for fingerprint: String, now: Date) -> TrustLevel {
+        queue.sync {
+            if self.cache.verifiedFingerprints.contains(fingerprint) { return .verified }
+            let stored = self.cache.socialIdentities[fingerprint]?.trustLevel ?? .unknown
+            let vouched = !self.validVouchersLocked(for: fingerprint, now: now).isEmpty
+            switch stored {
+            case .verified, .trusted:
+                return stored
+            case .vouched, .casual, .unknown:
+                if vouched { return .vouched }
+                // `.vouched` should never be persisted; degrade defensively.
+                return stored == .vouched ? .casual : stored
+            }
+        }
+    }
+
+    func lastVouchBatchSent(to fingerprint: String) -> Date? {
+        queue.sync { cache.vouchBatchSentAt?[fingerprint] }
+    }
+
+    func markVouchBatchSent(to fingerprint: String, at date: Date) {
+        queue.async(flags: .barrier) {
+            var sentAt = self.cache.vouchBatchSentAt ?? [:]
+            sentAt[fingerprint] = date
+            self.cache.vouchBatchSentAt = sentAt
+            self.saveIdentityCache()
+        }
+    }
+
+    /// The peer's announce-bound Ed25519 signing key, if seen this session.
+    func signingPublicKey(forFingerprint fingerprint: String) -> Data? {
+        queue.sync { cryptographicIdentities[fingerprint]?.signingPublicKey }
+    }
+
+    /// Verified fingerprints ordered most recently verified first (entries
+    /// without a recorded verification time sort last), excluding the given
+    /// fingerprint. Feeds the outgoing vouch batch.
+    func mostRecentlyVerifiedFingerprints(limit: Int, excluding fingerprint: String) -> [String] {
+        queue.sync {
+            let verifiedAt = cache.verifiedAt ?? [:]
+            let ordered = cache.verifiedFingerprints
+                .filter { $0 != fingerprint }
+                .sorted {
+                    (verifiedAt[$0] ?? .distantPast, $0) > (verifiedAt[$1] ?? .distantPast, $1)
+                }
+            return Array(ordered.prefix(limit))
+        }
+    }
+
     var debugNicknameIndex: [String: Set<String>] {
         queue.sync { cache.nicknameIndex }
     }

bitchat/Info.plist

@@ -31,6 +31,8 @@
 	</array>
 	<key>CFBundleVersion</key>
 	<string>$(CURRENT_PROJECT_VERSION)</string>
+	<key>LSApplicationCategoryType</key>
+	<string>public.app-category.social-networking</string>
 	<key>LSMinimumSystemVersion</key>
 	<string>$(MACOSX_DEPLOYMENT_TARGET)</string>
 	<key>NSBluetoothAlwaysUsageDescription</key>
@@ -40,9 +42,9 @@
 	<key>NSCameraUsageDescription</key>
 	<string>bitchat uses the camera to scan QR codes to verify peers.</string>
 	<key>NSLocationWhenInUseUsageDescription</key>
-	<string>bitchat uses your approximate location to compute local geohash channels for optional public chats. Exact GPS is never shared.</string>
+	<string>bitchat uses your location to compute optional geohash channels, bridge cells, and nearby place labels. Exact coordinates are not included in bitchat messages.</string>
 	<key>NSMicrophoneUsageDescription</key>
-	<string>bitchat uses the microphone to record voice notes that relay across the mesh.</string>
+	<string>bitchat uses the microphone while you record voice notes or hold live push-to-talk, then sends that audio to your selected mesh conversation.</string>
 	<key>NSPhotoLibraryUsageDescription</key>
 	<string>bitchat lets you pick images from your photo library to share with nearby peers.</string>
 	<key>UIBackgroundModes</key>

bitchat/Models/BitchatMessage+Media.swift

@@ -13,13 +13,6 @@ extension BitchatMessage {
     enum Media {
         case voice(URL)
         case image(URL)
-
-        var url: URL {
-            switch self {
-            case .voice(let url), .image(let url):
-                return url
-            }
-        }
     }
 
     // Cache the directory lookup to avoid repeated FileManager calls during view rendering

bitchat/Models/BitchatPeer.swift

@@ -7,7 +7,6 @@ struct BitchatPeer: Equatable {
     let peerID: PeerID // Hex-encoded peer ID
     let noisePublicKey: Data
     let nickname: String
-    let lastSeen: Date
     let isConnected: Bool
     let isReachable: Bool
     
@@ -77,14 +76,13 @@ struct BitchatPeer: Equatable {
         peerID: PeerID,
         noisePublicKey: Data,
         nickname: String,
-        lastSeen: Date = Date(),
+        lastSeen _: Date = Date(),
         isConnected: Bool = false,
         isReachable: Bool = false
     ) {
         self.peerID = peerID
         self.noisePublicKey = noisePublicKey
         self.nickname = nickname
-        self.lastSeen = lastSeen
         self.isConnected = isConnected
         self.isReachable = isReachable
         

bitchat/Models/CommandInfo.swift

@@ -11,15 +11,24 @@ import Foundation
 // MARK: - CommandInfo Enum
 
 enum CommandInfo: String, Identifiable {
+    // Raw values must match the aliases CommandProcessor actually accepts —
+    // the suggestion panel is the app's only command-discovery surface, and
+    // suggesting a spelling the processor rejects teaches users dead ends.
     case block
     case clear
+    case group
+    case help
     case hug
-    case message = "dm"
+    case message = "msg"
     case slap
+    case pay
     case unblock
     case who
-    case favorite
+    case favorite = "fav"
-    case unfavorite
+    case unfavorite = "unfav"
+    case ping
+    case trace
+    case drop
 
     var id: String { rawValue }
 
@@ -27,9 +36,15 @@ enum CommandInfo: String, Identifiable {
 
     var placeholder: String? {
         switch self {
-        case .block, .hug, .message, .slap, .unblock, .favorite, .unfavorite:
+        case .block, .hug, .message, .slap, .unblock, .favorite, .unfavorite, .ping, .trace:
             return "<" + String(localized: "content.input.nickname_placeholder") + ">"
-        case .clear, .who:
+        case .group:
+            return "<" + String(localized: "content.input.group_placeholder") + ">"
+        case .pay:
+            return "<" + String(localized: "content.input.token_placeholder") + ">"
+        case .drop:
+            return "<" + String(localized: "content.input.note_placeholder") + ">"
+        case .clear, .help, .who:
             return nil
         }
     }
@@ -38,21 +53,36 @@ enum CommandInfo: String, Identifiable {
         switch self {
         case .block:        String(localized: "content.commands.block")
         case .clear:        String(localized: "content.commands.clear")
+        case .group:        String(localized: "content.commands.group")
+        case .help:         String(localized: "content.commands.help")
         case .hug:          String(localized: "content.commands.hug")
         case .message:      String(localized: "content.commands.message")
+        case .pay:          String(localized: "content.commands.pay")
         case .slap:         String(localized: "content.commands.slap")
         case .unblock:      String(localized: "content.commands.unblock")
         case .who:          String(localized: "content.commands.who")
         case .favorite:     String(localized: "content.commands.favorite")
         case .unfavorite:   String(localized: "content.commands.unfavorite")
+        case .ping:         String(localized: "content.commands.ping")
+        case .trace:        String(localized: "content.commands.trace")
+        case .drop:         String(localized: "content.commands.drop")
         }
     }
 
     static func all(isGeoPublic: Bool, isGeoDM: Bool) -> [CommandInfo] {
-        let baseCommands: [CommandInfo] = [.block, .unblock, .clear, .hug, .message, .slap, .who]
+        var commands: [CommandInfo] = [.block, .unblock, .clear, .drop, .help, .hug, .message, .slap, .who]
+        // Cashu tokens are bearer instruments: in a public geohash any nearby
+        // stranger can redeem one, so don't *suggest* /pay there (the
+        // processor still allows it behind an explicit "public" confirm).
+        // Payments make sense in every DM and in mesh public.
+        if !isGeoPublic {
+            commands.append(.pay)
+        }
+        // The processor rejects favorites, groups, and mesh diagnostics in
+        // geohash contexts, so only suggest them where they work: mesh.
         if isGeoPublic || isGeoDM {
-            return baseCommands + [.favorite, .unfavorite]
+            return commands
         }
-        return baseCommands
+        return commands + [.favorite, .unfavorite, .ping, .trace, .group]
     }
 }

bitchat/Models/RequestSyncPacket.swift

@@ -1,10 +1,21 @@
+import BitFoundation
 import Foundation
 
 // REQUEST_SYNC payload TLV (type, length16, value)
 //  - 0x01: P (uint8) — Golomb-Rice parameter
 //  - 0x02: M (uint32, big-endian) — hash range (N * 2^P)
 //  - 0x03: data (opaque) — GR bitstream bytes (MSB-first)
+//  - 0x04: types (SyncTypeFlags) — packet types the filter covers
+//  - 0x05: sinceTimestamp (uint64, big-endian) — filter coverage cursor
+//  - 0x06: fragmentIdFilter (UTF-8) — comma-separated 16-hex-char (8-byte)
+//          fragment stream IDs; restricts the fragment diff to exactly those
+//          streams (targeted resync for stalled reassemblies)
 struct RequestSyncPacket {
+    /// Maximum fragment IDs one 0x06 filter may carry. Each ID encodes as
+    /// 16 hex chars plus a comma separator, so the largest encoded value is
+    /// 60 * 17 - 1 = 1019 bytes, which fits the 1024-byte decoder cap.
+    static let maxFragmentIdFilterCount = 60
+
     let p: Int
     let m: UInt32
     let data: Data
@@ -12,6 +23,29 @@ struct RequestSyncPacket {
     let sinceTimestamp: UInt64?
     let fragmentIdFilter: String?
 
+    /// Encodes 8-byte fragment stream IDs as the 0x06 filter string,
+    /// dropping malformed IDs and capping at `maxFragmentIdFilterCount`.
+    static func encodeFragmentIdFilter(_ fragmentIDs: [Data]) -> String? {
+        let tokens = fragmentIDs
+            .filter { $0.count == 8 }
+            .prefix(maxFragmentIdFilterCount)
+            .map { $0.hexEncodedString() }
+        guard !tokens.isEmpty else { return nil }
+        return tokens.joined(separator: ",")
+    }
+
+    /// Decodes a 0x06 filter string back into 8-byte fragment stream IDs,
+    /// ignoring malformed tokens and capping at `maxFragmentIdFilterCount`.
+    static func decodeFragmentIdFilter(_ filter: String?) -> Set<Data>? {
+        guard let filter else { return nil }
+        var ids: Set<Data> = []
+        for token in filter.split(separator: ",").prefix(maxFragmentIdFilterCount) {
+            guard token.count == 16, let id = Data(hexString: String(token)) else { continue }
+            ids.insert(id)
+        }
+        return ids.isEmpty ? nil : ids
+    }
+
     init(p: Int, m: UInt32, data: Data, types: SyncTypeFlags? = nil, sinceTimestamp: UInt64? = nil, fragmentIdFilter: String? = nil) {
         self.p = p
         self.m = m
@@ -88,7 +122,9 @@ struct RequestSyncPacket {
                     sinceTimestamp = ts
                 }
             case 0x06:
-                if let fid = String(data: v, encoding: .utf8) {
+                // Same acceptance cap as the GCS payload; an oversized filter
+                // is ignored rather than failing the whole request.
+                if v.count <= maxAcceptBytes, let fid = String(data: v, encoding: .utf8) {
                     fragmentIdFilter = fid
                 }
             default:
@@ -96,7 +132,7 @@ struct RequestSyncPacket {
             }
         }
 
-        guard let pp = p, let mm = m, let dd = payload, pp >= 1, mm > 0 else { return nil }
+        guard let pp = p, let mm = m, let dd = payload, pp >= 1, pp <= GCSFilter.maxP, mm > 0 else { return nil }
         return RequestSyncPacket(p: pp, m: mm, data: dd, types: types, sinceTimestamp: sinceTimestamp, fragmentIdFilter: fragmentIdFilter)
     }
 }

bitchat/Noise/NoiseProtocol.swift

@@ -93,6 +93,7 @@ enum NoisePattern {
     case XX  // Most versatile, mutual authentication
     case IK  // Initiator knows responder's static key
     case NK  // Anonymous initiator
+    case X   // One-way: single message to a known static key (no response)
 }
 
 enum NoiseRole {
@@ -322,6 +323,13 @@ final class NoiseCipherState {
                 throw NoiseError.replayDetected
             }
             
+            // The 4-byte nonce prefix has been stripped, so the remaining bytes
+            // must still hold at least the 16-byte Poly1305 tag. The up-front
+            // `ciphertext.count >= 16` guard is not sufficient here (it counts
+            // the nonce), and `prefix(count - 16)` would trap on a short payload.
+            guard actualCiphertext.count >= 16 else {
+                throw NoiseError.invalidCiphertext
+            }
             // Split ciphertext and tag
             encryptedData = actualCiphertext.prefix(actualCiphertext.count - 16)
             tag = actualCiphertext.suffix(16)
@@ -594,7 +602,7 @@ final class NoiseHandshakeState {
         switch pattern {
         case .XX:
             break // No pre-message keys
-        case .IK, .NK:
+        case .IK, .NK, .X:
             if role == .initiator, let remoteStatic = remoteStaticPublic {
                 symmetricState.mixHash(remoteStatic.rawRepresentation)
             } else if role == .responder, let localStatic = localStaticPublic {
@@ -715,7 +723,7 @@ final class NoiseHandshakeState {
         return messageBuffer
     }
     
-    func readMessage(_ message: Data, expectedPayloadLength: Int = 0) throws -> Data {
+    func readMessage(_ message: Data, expectedPayloadLength _: Int = 0) throws -> Data {
         
         guard currentPattern < messagePatterns.count else {
             throw NoiseError.handshakeComplete
@@ -897,6 +905,7 @@ extension NoisePattern {
         case .XX: return "XX"
         case .IK: return "IK"
         case .NK: return "NK"
+        case .X: return "X"
         }
     }
     
@@ -918,6 +927,10 @@ extension NoisePattern {
                 [.e, .es],      // -> e, es
                 [.e, .ee]       // <- e, ee
             ]
+        case .X:
+            return [
+                [.e, .es, .s, .ss] // -> e, es, s, ss (single one-way message)
+            ]
         }
     }
 }

bitchat/Noise/NoiseSecurityConstants.swift

@@ -21,12 +21,6 @@ enum NoiseSecurityConstants {
     // Maximum number of messages before rekey (2^64 - 1 is the nonce limit)
     static let maxMessagesPerSession: UInt64 = 1_000_000_000 // 1 billion messages
     
-    // Handshake timeout - abandon incomplete handshakes
-    static let handshakeTimeout: TimeInterval = 60 // 1 minute
-    
-    // Maximum concurrent sessions per peer
-    static let maxSessionsPerPeer = 3
-    
     // Rate limiting
     static let maxHandshakesPerMinute = 10
     static let maxMessagesPerSecond = 100

bitchat/Noise/NoiseSecurityError.swift

@@ -14,5 +14,4 @@ enum NoiseSecurityError: Error {
     case messageTooLarge
     case invalidPeerID
     case rateLimitExceeded
-    case handshakeTimeout
 }

bitchat/Noise/NoiseSessionManager.swift

@@ -13,8 +13,6 @@ import BitFoundation
 
 final class NoiseSessionManager {
     private var sessions: [PeerID: NoiseSession] = [:]
-    private let localStaticKey: Curve25519.KeyAgreement.PrivateKey
-    private let keychain: KeychainManagerProtocol
     private let sessionFactory: (PeerID, NoiseRole) -> NoiseSession
     private let managerQueue = DispatchQueue(label: "chat.bitchat.noise.manager", attributes: .concurrent)
     
@@ -23,8 +21,6 @@ final class NoiseSessionManager {
     var onSessionFailed: ((PeerID, Error) -> Void)?
     
     init(localStaticKey: Curve25519.KeyAgreement.PrivateKey, keychain: KeychainManagerProtocol) {
-        self.localStaticKey = localStaticKey
-        self.keychain = keychain
         self.sessionFactory = { peerID, role in
             SecureNoiseSession(
                 peerID: peerID,
@@ -37,12 +33,10 @@ final class NoiseSessionManager {
 
     #if DEBUG
     init(
-        localStaticKey: Curve25519.KeyAgreement.PrivateKey,
+        localStaticKey _: Curve25519.KeyAgreement.PrivateKey,
-        keychain: KeychainManagerProtocol,
+        keychain _: KeychainManagerProtocol,
         sessionFactory: @escaping (PeerID, NoiseRole) -> NoiseSession
     ) {
-        self.localStaticKey = localStaticKey
-        self.keychain = keychain
         self.sessionFactory = sessionFactory
     }
     #endif

bitchat/Nostr/GeoRelayDirectory.swift

@@ -7,6 +7,11 @@ import UIKit
 import AppKit
 #endif
 
+extension Notification.Name {
+    /// Posted after the geo relay directory successfully refreshes its entries.
+    static let geoRelayDirectoryDidRefresh = Notification.Name("bitchat.geoRelayDirectoryDidRefresh")
+}
+
 /// Directory of online Nostr relays with approximate GPS locations, used for geohash routing.
 struct GeoRelayDirectoryDependencies {
     var userDefaults: UserDefaults
@@ -165,33 +170,16 @@ final class GeoRelayDirectory {
     }
 
     /// Returns up to `count` relay URLs (wss://) closest to the given coordinate.
+    /// Ties break by host so every device with the same directory picks the
+    /// same relay set — publishers and subscribers must agree on relays.
     func closestRelays(toLat lat: Double, lon: Double, count: Int = 5) -> [String] {
         guard !entries.isEmpty, count > 0 else { return [] }
 
-        if entries.count <= count {
         return entries
-                .sorted { a, b in
+            .map { (entry: $0, distance: haversineKm(lat, lon, $0.lat, $0.lon)) }
-                    haversineKm(lat, lon, a.lat, a.lon) < haversineKm(lat, lon, b.lat, b.lon)
+            .sorted { ($0.distance, $0.entry.host) < ($1.distance, $1.entry.host) }
-                }
+            .prefix(count)
-                .map { "wss://\($0.host)" }
+            .map { "wss://\($0.entry.host)" }
-        }
-
-        var best: [(entry: Entry, distance: Double)] = []
-        best.reserveCapacity(count)
-
-        for entry in entries {
-            let distance = haversineKm(lat, lon, entry.lat, entry.lon)
-            if best.count < count {
-                let idx = best.firstIndex { $0.distance > distance } ?? best.count
-                best.insert((entry, distance), at: idx)
-            } else if let worstDistance = best.last?.distance, distance < worstDistance {
-                let idx = best.firstIndex { $0.distance > distance } ?? best.count
-                best.insert((entry, distance), at: idx)
-                best.removeLast()
-            }
-        }
-
-        return best.map { "wss://\($0.entry.host)" }
     }
 
     // MARK: - Remote Fetch
@@ -289,6 +277,8 @@ final class GeoRelayDirectory {
         isFetching = false
         retryAttempt = 0
         cancelRetry()
+        // Let waiters (e.g. location notes stuck in a "no relays" state) retry.
+        dependencies.notificationCenter.post(name: .geoRelayDirectoryDidRefresh, object: nil)
     }
 
     @MainActor

bitchat/Nostr/NostrIdentity.swift

@@ -6,14 +6,12 @@ struct NostrIdentity: Codable {
     let privateKey: Data
     let publicKey: Data
     let npub: String // Bech32-encoded public key
-    let createdAt: Date
 
     /// Memberwise initializer
-    init(privateKey: Data, publicKey: Data, npub: String, createdAt: Date) {
+    init(privateKey: Data, publicKey: Data, npub: String, createdAt _: Date) {
         self.privateKey = privateKey
         self.publicKey = publicKey
         self.npub = npub
-        self.createdAt = createdAt
     }
     
     /// Generate a new Nostr identity
@@ -39,12 +37,6 @@ struct NostrIdentity: Codable {
         self.privateKey = privateKeyData
         self.publicKey = xOnlyPubkey
         self.npub = try Bech32.encode(hrp: "npub", data: xOnlyPubkey)
-        self.createdAt = Date()
-    }
-    
-    /// Get signing key for event signatures
-    func signingKey() throws -> P256K.Signing.PrivateKey {
-        try P256K.Signing.PrivateKey(dataRepresentation: privateKey)
     }
     
     /// Get Schnorr signing key for Nostr event signatures

bitchat/Nostr/NostrIdentityBridge.swift

@@ -15,7 +15,7 @@ final class NostrIdentityBridge {
 
     private let keychain: KeychainManagerProtocol
 
-    init(keychain: KeychainManagerProtocol = KeychainManager()) {
+    init(keychain: KeychainManagerProtocol = KeychainManager.makeDefault()) {
         self.keychain = keychain
     }
     
@@ -37,14 +37,6 @@ final class NostrIdentityBridge {
         return nostrIdentity
     }
     
-    /// Associate a Nostr identity with a Noise public key (for favorites)
-    func associateNostrIdentity(_ nostrPubkey: String, with noisePublicKey: Data) {
-        let key = "nostr-noise-\(noisePublicKey.base64EncodedString())"
-        if let data = nostrPubkey.data(using: .utf8) {
-            keychain.save(key: key, data: data, service: keychainService, accessible: nil)
-        }
-    }
-    
     /// Get Nostr public key associated with a Noise public key
     func getNostrPublicKey(for noisePublicKey: Data) -> String? {
         let key = "nostr-noise-\(noisePublicKey.base64EncodedString())"
@@ -57,31 +49,19 @@ final class NostrIdentityBridge {
     
     /// Clear all Nostr identity associations and current identity
     func clearAllAssociations() {
-        let query: [String: Any] = [
+        // Must go through the injected keychain, not raw SecItem calls:
-            kSecClass as String: kSecClassGenericPassword,
+        // under test that keychain is in-memory, and a direct delete here
-            kSecAttrService as String: keychainService,
+        // would wipe the developer's real Nostr identity on every test run.
-            kSecMatchLimit as String: kSecMatchLimitAll,
+        keychain.deleteAll(service: keychainService)
-            kSecReturnAttributes as String: true
-        ]
-
-        var result: AnyObject?
-        let status = SecItemCopyMatching(query as CFDictionary, &result)
-        if status == errSecSuccess, let items = result as? [[String: Any]] {
-            for item in items {
-                var deleteQuery: [String: Any] = [
-                    kSecClass as String: kSecClassGenericPassword,
-                    kSecAttrService as String: keychainService
-                ]
-                if let account = item[kSecAttrAccount as String] as? String {
-                    deleteQuery[kSecAttrAccount as String] = account
-                }
-                SecItemDelete(deleteQuery as CFDictionary)
-            }
-        } else if status == errSecItemNotFound {
-            // nothing persisted; no action needed
-        }
 
         deviceSeedCache = nil
+        // Also drop the in-memory derived per-geohash identities. These hold the
+        // actual secp256k1 private keys; if left cached, post-panic geohash
+        // messages would still be signed with pre-panic keys (linkable across the
+        // wipe) until the app is force-quit.
+        cacheLock.lock()
+        derivedIdentityCache.removeAll()
+        cacheLock.unlock()
     }
 
     // MARK: - Per-Geohash Identities (Location Channels)
@@ -106,6 +86,13 @@ final class NostrIdentityBridge {
         return seed
     }
 
+    /// Derive a deterministic, unlinkable Nostr identity for a mesh-bridge
+    /// rendezvous cell. Distinct HMAC label keeps it unlinkable from the
+    /// geohash-chat identity for the same cell string.
+    func deriveIdentity(forBridgeRendezvous cell: String) throws -> NostrIdentity {
+        try deriveIdentity(forGeohash: "bridge|" + cell)
+    }
+
     /// Derive a deterministic, unlinkable Nostr identity for a given geohash.
     /// Uses HMAC-SHA256(deviceSeed, geohash) as private key material, with fallback rehashing
     /// if the candidate is not a valid secp256k1 private key.

bitchat/Nostr/NostrPoW.swift

@@ -0,0 +1,215 @@
+import BitFoundation
+import CryptoKit
+import Foundation
+
+/// NIP-13 proof-of-work for Nostr events.
+///
+/// Outgoing kind-20000 geohash messages mine a `["nonce", "<value>", "<target>"]`
+/// tag so the event ID carries at least `target` leading zero bits. Inbound
+/// events are scored (never hard-rejected — the network has clients that do
+/// not mine): validated PoW at or above `rateLimitBypassBits` relaxes the
+/// per-sender public rate limit, everything else keeps the strict limits.
+enum NostrPoW {
+
+    // MARK: - Tuning
+
+    /// Difficulty (leading zero bits of the event ID) mined onto outgoing
+    /// geohash messages. 8 bits is ~256 hash attempts — typically well under
+    /// 100 ms on any supported device.
+    static let targetBits = 8
+
+    /// Inbound events whose validated NIP-13 difficulty is at least this many
+    /// bits skip the per-sender rate-limit bucket (the content-flood bucket
+    /// still applies). See `MessageRateLimiter.allow`.
+    static let rateLimitBypassBits = 8
+
+    /// Hard cap on mining wall-clock time. When it hits, the committed target
+    /// steps down until a difficulty reachable in a small extra budget is
+    /// found and the message is sent anyway — mining never blocks sending.
+    static let miningTimeCap: TimeInterval = 2.0
+
+    /// Budget for each stepped-down attempt after the main cap (or a task
+    /// cancellation) hits.
+    private static let fallbackTimeCap: TimeInterval = 0.15
+
+    /// The hot loop checks the deadline and task cancellation every this many
+    /// hash attempts.
+    private static let checkInterval: UInt64 = 1024
+
+    /// The nonce value is a fixed-width hex counter so the serialized event
+    /// template can be mutated in place without reallocation.
+    private static let nonceLength = 16
+
+    // MARK: - Scoring
+
+    /// Number of leading zero bits in a byte sequence (NIP-13 difficulty of
+    /// an event-ID hash).
+    static func leadingZeroBits<Bytes: Sequence<UInt8>>(_ bytes: Bytes) -> Int {
+        var total = 0
+        for byte in bytes {
+            if byte == 0 {
+                total += 8
+            } else {
+                total += byte.leadingZeroBitCount
+                break
+            }
+        }
+        return total
+    }
+
+    /// Validated NIP-13 difficulty of an inbound event.
+    ///
+    /// The committed target in the nonce tag is what counts: the actual
+    /// leading zero bits of the ID must meet it (otherwise the claim is void
+    /// and the event scores 0), and work beyond the commitment earns no extra
+    /// credit — this stops spammers who mine a low target from getting lucky
+    /// high scores. Events without a well-formed commitment score 0.
+    static func validatedDifficulty(idHex: String, tags: [[String]]) -> Int {
+        guard let nonceTag = tags.last(where: { $0.first == "nonce" }),
+              nonceTag.count >= 3,
+              let committed = Int(nonceTag[2]),
+              committed > 0, committed <= 256,
+              let idData = Data(hexString: idHex)
+        else {
+            return 0
+        }
+        return leadingZeroBits(idData) >= committed ? committed : 0
+    }
+
+    // MARK: - Mining
+
+    /// Mine a `["nonce", value, target]` tag for the given unsigned-event
+    /// fields. Nonisolated async: runs off the calling actor.
+    ///
+    /// Bounded by `miningTimeCap`: when the cap hits — or the surrounding
+    /// task is cancelled — the committed target steps down (halving to 0,
+    /// which any hash satisfies) so the event still ships promptly with an
+    /// honest commitment at the difficulty actually reached. Returns nil only
+    /// if canonical serialization fails; the caller then sends unmined.
+    static func mineNonceTag(
+        pubkey: String,
+        createdAt: Int,
+        kind: Int,
+        tags: [[String]],
+        content: String,
+        targetBits: Int = NostrPoW.targetBits
+    ) async -> [String]? {
+        var target = min(max(targetBits, 0), 256)
+        var budget = miningTimeCap
+        while true {
+            if let tag = mineAttempt(
+                pubkey: pubkey,
+                createdAt: createdAt,
+                kind: kind,
+                baseTags: tags,
+                content: content,
+                targetBits: target,
+                budget: budget
+            ) {
+                return tag
+            }
+            // Target 0 succeeds on the first hash, so reaching it with nil
+            // means serialization itself failed — give up on mining.
+            if target == 0 { return nil }
+            target /= 2
+            budget = fallbackTimeCap
+        }
+    }
+
+    /// One bounded mining pass at a fixed committed target. Allocation-light:
+    /// the canonical serialization is built once and only the fixed-width
+    /// nonce bytes are rewritten per attempt (the event ID is recomputed for
+    /// every attempt, per NIP-13). Returns nil on timeout/cancellation or if
+    /// the template could not be built.
+    private static func mineAttempt(
+        pubkey: String,
+        createdAt: Int,
+        kind: Int,
+        baseTags: [[String]],
+        content: String,
+        targetBits: Int,
+        budget: TimeInterval
+    ) -> [String]? {
+        let targetString = String(targetBits)
+        guard let template = serializedTemplate(
+            pubkey: pubkey,
+            createdAt: createdAt,
+            kind: kind,
+            baseTags: baseTags,
+            content: content,
+            targetString: targetString
+        ) else {
+            return nil
+        }
+        var buffer = template.buffer
+        let nonceRange = template.nonceRange
+
+        let deadline = DispatchTime.now().uptimeNanoseconds &+ UInt64(budget * 1_000_000_000)
+        let hexDigits = [UInt8]("0123456789abcdef".utf8)
+        var nonce = UInt64.random(in: .min ... .max)
+        var attempts: UInt64 = 0
+
+        while true {
+            // Write the nonce as 16 lowercase hex chars, in place.
+            var value = nonce
+            var index = nonceRange.upperBound
+            while index > nonceRange.lowerBound {
+                index -= 1
+                buffer[index] = hexDigits[Int(value & 0xF)]
+                value >>= 4
+            }
+
+            if leadingZeroBits(SHA256.hash(data: buffer)) >= targetBits {
+                // Identical to the bytes just written into the buffer.
+                return ["nonce", String(format: "%016llx", nonce), targetString]
+            }
+
+            nonce &+= 1
+            attempts &+= 1
+            if attempts % checkInterval == 0,
+               Task.isCancelled || DispatchTime.now().uptimeNanoseconds >= deadline {
+                return nil
+            }
+        }
+    }
+
+    /// Canonical NIP-01 serialization of the event with a placeholder nonce,
+    /// plus the byte range of the nonce value inside it.
+    ///
+    /// The range is located by serializing twice with two same-length
+    /// placeholders and diffing the buffers — the only differing bytes are
+    /// the nonce value, so this stays correct however `JSONSerialization`
+    /// escapes the surrounding fields (and even if the content contains the
+    /// placeholder text itself).
+    private static func serializedTemplate(
+        pubkey: String,
+        createdAt: Int,
+        kind: Int,
+        baseTags: [[String]],
+        content: String,
+        targetString: String
+    ) -> (buffer: Data, nonceRange: Range<Int>)? {
+        func serialize(noncePlaceholder: String) -> Data? {
+            var tags = baseTags
+            tags.append(["nonce", noncePlaceholder, targetString])
+            let serialized: [Any] = [0, pubkey, createdAt, kind, tags, content]
+            return try? JSONSerialization.data(withJSONObject: serialized, options: [.withoutEscapingSlashes])
+        }
+
+        guard let zeros = serialize(noncePlaceholder: String(repeating: "0", count: nonceLength)),
+              let effs = serialize(noncePlaceholder: String(repeating: "f", count: nonceLength)),
+              zeros.count == effs.count
+        else {
+            return nil
+        }
+
+        var firstDiff = -1
+        var lastDiff = -1
+        for index in 0..<zeros.count where zeros[index] != effs[index] {
+            if firstDiff < 0 { firstDiff = index }
+            lastDiff = index
+        }
+        guard firstDiff >= 0, lastDiff - firstDiff + 1 == nonceLength else { return nil }
+        return (zeros, firstDiff..<(firstDiff + nonceLength))
+    }
+}

bitchat/Nostr/NostrProtocol.swift

@@ -19,6 +19,11 @@ struct NostrProtocol {
         case giftWrap = 1059 // NIP-59 gift wrap
         case ephemeralEvent = 20000
         case geohashPresence = 20001
+        case deletion = 5 // NIP-09 event deletion request
+        /// Sealed courier envelope parked on relays under its rotating
+        /// recipient tag (`#x`). Regular (stored) kind so it survives until
+        /// its NIP-40 expiration — the whole point is store-and-forward.
+        case courierDrop = 1401
     }
     
     /// Create a NIP-17 private message
@@ -39,22 +44,23 @@ struct NostrProtocol {
             content: content
         )
         
-        // 2. Create ephemeral key for this message
+        // 2. Seal the rumor (encrypt to recipient) and sign it with the SENDER'S
-        let ephemeralKey = try P256K.Schnorr.PrivateKey()
+        //    real identity key. NIP-17 requires the seal be signed by the sender
-        // Created ephemeral key for seal
+        //    so the recipient can authenticate who sent the message; signing with
-        
+        //    a throwaway key leaves DMs forgeable/impersonatable.
-        // 3. Seal the rumor (encrypt to recipient)
+        let senderKey = try senderIdentity.schnorrSigningKey()
         let sealedEvent = try createSeal(
             rumor: rumor,
             recipientPubkey: recipientPubkey,
-            senderKey: ephemeralKey
+            senderKey: senderKey
         )
 
-        // 4. Gift wrap the sealed event (encrypt to recipient again)
+        // 3. Gift wrap the sealed event with a throwaway ephemeral key (the wrap
+        //    layer hides the sender's identity from relays; createGiftWrap mints
+        //    its own ephemeral key internally).
         let giftWrap = try createGiftWrap(
             seal: sealedEvent,
-            recipientPubkey: recipientPubkey,
+            recipientPubkey: recipientPubkey
-            senderKey: ephemeralKey
         )
         
         // Created gift wrap
@@ -84,7 +90,15 @@ struct NostrProtocol {
             throw error
         }
         
-        // 2. Open the seal
+        // 2. Authenticate the seal. The seal MUST be signed by the sender's real
+        //    identity key (NIP-17); without this check a DM is forgeable by anyone
+        //    who knows the recipient's npub. Verify the seal's own signature.
+        guard seal.isValidSignature() else {
+            SecureLogger.error("❌ Rejecting DM: seal signature is missing or invalid", category: .session)
+            throw NostrError.invalidEvent
+        }
+
+        // 3. Open the seal
         let rumor: NostrEvent
         do {
             rumor = try openSeal(
@@ -97,9 +111,62 @@ struct NostrProtocol {
             throw error
         }
 
-        return (content: rumor.content, senderPubkey: rumor.pubkey, timestamp: rumor.created_at)
+        // 4. The sender claimed inside the rumor must match the key that actually
+        //    signed the seal, otherwise the sender field is unauthenticated and
+        //    spoofable.
+        guard seal.pubkey == rumor.pubkey else {
+            SecureLogger.error("❌ Rejecting DM: rumor pubkey does not match seal signer", category: .session)
+            throw NostrError.invalidEvent
         }
 
+        // Return the seal signer's pubkey as the authenticated sender.
+        return (content: rumor.content, senderPubkey: seal.pubkey, timestamp: rumor.created_at)
+    }
+
+    #if DEBUG
+    static func createPrivateMessageWithInvalidSealSignatureForTesting(
+        content: String,
+        recipientPubkey: String,
+        senderIdentity: NostrIdentity
+    ) throws -> NostrEvent {
+        let rumor = NostrEvent(
+            pubkey: senderIdentity.publicKeyHex,
+            createdAt: Date(),
+            kind: .dm,
+            tags: [],
+            content: content
+        )
+        var seal = try createSeal(
+            rumor: rumor,
+            recipientPubkey: recipientPubkey,
+            senderKey: senderIdentity.schnorrSigningKey()
+        )
+        seal.sig = String(repeating: "0", count: 128)
+        return try createGiftWrap(seal: seal, recipientPubkey: recipientPubkey)
+    }
+
+    static func createPrivateMessageWithMismatchedSealRumorPubkeyForTesting(
+        content: String,
+        recipientPubkey: String,
+        rumorIdentity: NostrIdentity,
+        sealSignerIdentity: NostrIdentity
+    ) throws -> NostrEvent {
+        let rumor = NostrEvent(
+            pubkey: rumorIdentity.publicKeyHex,
+            createdAt: Date(),
+            kind: .dm,
+            tags: [],
+            content: content
+        )
+        let seal = try createSeal(
+            rumor: rumor,
+            recipientPubkey: recipientPubkey,
+            senderKey: sealSignerIdentity.schnorrSigningKey()
+        )
+        return try createGiftWrap(seal: seal, recipientPubkey: recipientPubkey)
+    }
+    #endif
+
     /// Create a geohash-scoped ephemeral public message (kind 20000)
     static func createEphemeralGeohashEvent(
         content: String,
@@ -108,6 +175,63 @@ struct NostrProtocol {
         nickname: String? = nil,
         teleported: Bool = false
     ) throws -> NostrEvent {
+        let event = NostrEvent(
+            pubkey: senderIdentity.publicKeyHex,
+            createdAt: Date(),
+            kind: .ephemeralEvent,
+            tags: ephemeralGeohashTags(geohash: geohash, nickname: nickname, teleported: teleported),
+            content: content
+        )
+        let schnorrKey = try senderIdentity.schnorrSigningKey()
+        return try event.sign(with: schnorrKey)
+    }
+
+    /// Create a kind-20000 geohash message carrying a NIP-13 proof-of-work
+    /// nonce tag (see `NostrPoW`). Mining runs off the calling actor and is
+    /// bounded by `NostrPoW.miningTimeCap`; when the cap hits (or the
+    /// surrounding task is cancelled) the event ships at the highest
+    /// committed difficulty still met, and if mining is impossible it ships
+    /// unmined — sending is never blocked.
+    static func createMinedEphemeralGeohashEvent(
+        content: String,
+        geohash: String,
+        senderIdentity: NostrIdentity,
+        nickname: String? = nil,
+        teleported: Bool = false,
+        powTargetBits: Int = NostrPoW.targetBits
+    ) async throws -> NostrEvent {
+        var tags = ephemeralGeohashTags(geohash: geohash, nickname: nickname, teleported: teleported)
+        // Fix created_at up front: the mined nonce commits to the full
+        // serialized event, so the signed event must reuse the exact value.
+        let createdAt = Int(Date().timeIntervalSince1970)
+        if let nonceTag = await NostrPoW.mineNonceTag(
+            pubkey: senderIdentity.publicKeyHex,
+            createdAt: createdAt,
+            kind: EventKind.ephemeralEvent.rawValue,
+            tags: tags,
+            content: content,
+            targetBits: powTargetBits
+        ) {
+            tags.append(nonceTag)
+        }
+        let event = NostrEvent(
+            pubkey: senderIdentity.publicKeyHex,
+            createdAt: Date(timeIntervalSince1970: TimeInterval(createdAt)),
+            kind: .ephemeralEvent,
+            tags: tags,
+            content: content
+        )
+        let schnorrKey = try senderIdentity.schnorrSigningKey()
+        return try event.sign(with: schnorrKey)
+    }
+
+    /// Tags for a kind-20000 geohash message (shared by the plain and mined
+    /// variants).
+    private static func ephemeralGeohashTags(
+        geohash: String,
+        nickname: String?,
+        teleported: Bool
+    ) -> [[String]] {
         var tags = [["g", geohash]]
         if let nickname = nickname?.trimmedOrNilIfEmpty {
             tags.append(["n", nickname])
@@ -115,15 +239,7 @@ struct NostrProtocol {
         if teleported {
             tags.append(["t", "teleport"])
         }
-        let event = NostrEvent(
+        return tags
-            pubkey: senderIdentity.publicKeyHex,
-            createdAt: Date(),
-            kind: .ephemeralEvent,
-            tags: tags,
-            content: content
-        )
-        let schnorrKey = try senderIdentity.schnorrSigningKey()
-        return try event.sign(with: schnorrKey)
     }
 
     /// Create a geohash presence heartbeat (kind 20001)
@@ -144,17 +260,115 @@ struct NostrProtocol {
         return try event.sign(with: schnorrKey)
     }
 
+    // MARK: - Mesh bridge (rendezvous) events
+
+    /// Create a mesh-bridge public message (kind 20000) for a geohash-cell
+    /// rendezvous. The distinct `r` tag keeps bridge traffic out of geohash
+    /// channel subscriptions (which filter on `#g`); `m` is
+    /// `[stable ID, mesh sender ID, wire timestamp in ms]`. Element 1 is the
+    /// content-stable mesh message ID (`MeshMessageIdentity`) for v1.7.0
+    /// parsers, which key their dedup on `m[1]` unconditionally and need it
+    /// per-message-unique. Current parsers key bridge rows by the authenticated
+    /// event ID and recompute elements 2-3 only as a radio-copy hint; the mesh
+    /// coordinates are public and cannot authenticate the Nostr signer.
+    static func createBridgeMeshEvent(
+        content: String,
+        cell: String,
+        senderIdentity: NostrIdentity,
+        nickname: String? = nil,
+        meshSenderID: String? = nil,
+        meshTimestampMs: UInt64? = nil
+    ) throws -> NostrEvent {
+        var tags = [["r", cell]]
+        if let nickname = nickname?.trimmedOrNilIfEmpty {
+            tags.append(["n", nickname])
+        }
+        if let meshSenderID = meshSenderID?.trimmedOrNilIfEmpty, let meshTimestampMs {
+            let stableID = MeshMessageIdentity.stableID(
+                senderIDHex: meshSenderID,
+                timestampMs: meshTimestampMs,
+                content: content
+            )
+            tags.append(["m", stableID, meshSenderID, String(meshTimestampMs)])
+        }
+        let event = NostrEvent(
+            pubkey: senderIdentity.publicKeyHex,
+            createdAt: Date(),
+            kind: .ephemeralEvent,
+            tags: tags,
+            content: content
+        )
+        let schnorrKey = try senderIdentity.schnorrSigningKey()
+        return try event.sign(with: schnorrKey)
+    }
+
+    /// Create a mesh-bridge presence heartbeat (kind 20001) on a rendezvous
+    /// cell: empty content, `r` tag only — the bridge analogue of geohash
+    /// presence, counted into "people across the bridge".
+    static func createBridgePresenceEvent(
+        cell: String,
+        senderIdentity: NostrIdentity
+    ) throws -> NostrEvent {
+        let event = NostrEvent(
+            pubkey: senderIdentity.publicKeyHex,
+            createdAt: Date(),
+            kind: .geohashPresence,
+            tags: [["r", cell]],
+            content: ""
+        )
+        let schnorrKey = try senderIdentity.schnorrSigningKey()
+        return try event.sign(with: schnorrKey)
+    }
+
+    /// Create a courier drop (kind 1401): an opaque sealed courier envelope
+    /// parked on relays. `x` is the hex recipient tag the recipient (or a
+    /// gateway acting for them) subscribes for; the NIP-40 expiration tracks
+    /// the envelope expiry so honoring relays garbage-collect the drop. The
+    /// signing identity should be a throwaway — the envelope authenticates
+    /// its sender internally via Noise-X, and linking drops to a stable
+    /// publisher key would leak courier traffic patterns.
+    static func createCourierDropEvent(
+        envelope: Data,
+        recipientTagHex: String,
+        expiresAt: Date,
+        senderIdentity: NostrIdentity
+    ) throws -> NostrEvent {
+        let tags = [
+            ["x", recipientTagHex],
+            ["expiration", String(Int(expiresAt.timeIntervalSince1970))]
+        ]
+        let event = NostrEvent(
+            pubkey: senderIdentity.publicKeyHex,
+            createdAt: Date(),
+            kind: .courierDrop,
+            tags: tags,
+            content: envelope.base64EncodedString()
+        )
+        let schnorrKey = try senderIdentity.schnorrSigningKey()
+        return try event.sign(with: schnorrKey)
+    }
+
     /// Create a persistent location note (kind 1: text note) tagged to a street-level geohash.
+    /// An optional `expiresAt` adds a NIP-40 expiration tag so honoring relays
+    /// drop the note in step with a bridged board post's expiry.
     static func createGeohashTextNote(
         content: String,
         geohash: String,
         senderIdentity: NostrIdentity,
-        nickname: String? = nil
+        nickname: String? = nil,
+        expiresAt: Date? = nil,
+        urgent: Bool = false
     ) throws -> NostrEvent {
         var tags = [["g", geohash]]
         if let nickname = nickname?.trimmedOrNilIfEmpty {
             tags.append(["n", nickname])
         }
+        if let expiresAt {
+            tags.append(["expiration", String(Int(expiresAt.timeIntervalSince1970))])
+        }
+        if urgent {
+            tags.append(["t", "urgent"])
+        }
         let event = NostrEvent(
             pubkey: senderIdentity.publicKeyHex,
             createdAt: Date(),
@@ -166,6 +380,24 @@ struct NostrProtocol {
         return try event.sign(with: schnorrKey)
     }
 
+    /// Create a NIP-09 deletion request for one of our own events. Relays that
+    /// honor NIP-09 drop the referenced event; it must be signed by the same
+    /// key that signed the original.
+    static func createDeleteEvent(
+        ofEventID eventID: String,
+        senderIdentity: NostrIdentity
+    ) throws -> NostrEvent {
+        let event = NostrEvent(
+            pubkey: senderIdentity.publicKeyHex,
+            createdAt: Date(),
+            kind: .deletion,
+            tags: [["e", eventID]],
+            content: ""
+        )
+        let schnorrKey = try senderIdentity.schnorrSigningKey()
+        return try event.sign(with: schnorrKey)
+    }
+
     // MARK: - Private Methods
     
     private static func createSeal(
@@ -195,8 +427,7 @@ struct NostrProtocol {
     
     private static func createGiftWrap(
         seal: NostrEvent,
-        recipientPubkey: String,
+        recipientPubkey: String
-        senderKey: P256K.Schnorr.PrivateKey  // This is the ephemeral key used for the seal
     ) throws -> NostrEvent {
 
         let sealJSON = try seal.jsonString()
@@ -413,37 +644,6 @@ struct NostrProtocol {
         return sharedSecretData
     }
     
-    // Direct version that doesn't try to add prefixes
-    private static func deriveSharedSecretDirect(
-        privateKey: P256K.Schnorr.PrivateKey,
-        publicKey: Data
-    ) throws -> Data {
-        // Direct shared secret calculation
-        
-        // Convert Schnorr private key to KeyAgreement private key
-        let keyAgreementPrivateKey = try P256K.KeyAgreement.PrivateKey(
-            dataRepresentation: privateKey.dataRepresentation
-        )
-        
-        // Use the public key as-is (should already have prefix)
-        let keyAgreementPublicKey = try P256K.KeyAgreement.PublicKey(
-            dataRepresentation: publicKey,
-            format: .compressed
-        )
-        
-        // Perform ECDH
-        let sharedSecret = try keyAgreementPrivateKey.sharedSecretFromKeyAgreement(
-            with: keyAgreementPublicKey,
-            format: .compressed
-        )
-        
-        // Convert SharedSecret to Data
-        let sharedSecretData = sharedSecret.withUnsafeBytes { Data($0) }
-        
-        // Return raw ECDH shared secret; HKDF is applied by deriveNIP44V2Key
-        return sharedSecretData
-    }
-    
     private static func randomizedTimestamp() -> Date {
         // Add random offset to current time for privacy
         // This prevents timing correlation attacks while the actual message timestamp
@@ -573,11 +773,8 @@ struct NostrEvent: Codable {
 
 enum NostrError: Error {
     case invalidPublicKey
-    case invalidPrivateKey
     case invalidEvent
     case invalidCiphertext
-    case signingFailed
-    case encryptionFailed
 }
 
 // MARK: - NIP-44 v2 helpers (XChaCha20-Poly1305)
@@ -587,7 +784,7 @@ private extension NostrProtocol {
         let derivedKey = HKDF<CryptoKit.SHA256>.deriveKey(
             inputKeyMaterial: SymmetricKey(data: sharedSecretData),
             salt: Data(),
-            info: "nip44-v2".data(using: .utf8)!,
+            info: Data("nip44-v2".utf8),
             outputByteCount: 32
         )
         return derivedKey.withUnsafeBytes { Data($0) }

bitchat/Nostr/NostrRelayManager.swift

@@ -66,6 +66,9 @@ struct NostrRelayManagerDependencies {
     var makeSession: () -> NostrRelaySessionProtocol
     var scheduleAfter: @Sendable (TimeInterval, @escaping @Sendable () -> Void) -> Void
     var now: () -> Date
+    /// Uniform random value in [0, 1) used to jitter reconnect backoff.
+    /// Injectable so tests can pin or sweep the jitter deterministically.
+    var jitterUnit: () -> Double
 }
 
 private extension NostrRelayManagerDependencies {
@@ -93,7 +96,8 @@ private extension NostrRelayManagerDependencies {
             scheduleAfter: { delay, action in
                 DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: action)
             },
-            now: Date.init
+            now: Date.init,
+            jitterUnit: { Double.random(in: 0..<1) }
         )
     }
 }
@@ -113,7 +117,6 @@ final class NostrRelayManager: ObservableObject {
         let url: String
         var isConnected: Bool = false
         var lastError: Error?
-        var lastConnectedAt: Date?
         var messagesSent: Int = 0
         var messagesReceived: Int = 0
         var reconnectAttempts: Int = 0
@@ -133,6 +136,10 @@ final class NostrRelayManager: ObservableObject {
     
     @Published private(set) var relays: [Relay] = []
     @Published private(set) var isConnected = false
+    /// Whether a relay that carries private messages is connected. DMs
+    /// target the default (gift-wrap-capable) relay set, so a connected
+    /// geohash/custom relay alone must not count — sends would still queue.
+    @Published private(set) var isDMRelayConnected = false
     
     private let dependencies: NostrRelayManagerDependencies
     private var allowDefaultRelays: Bool = false
@@ -140,13 +147,34 @@ final class NostrRelayManager: ObservableObject {
     private var hasLocationPermission: Bool = false
     private var connections: [String: NostrRelayConnectionProtocol] = [:]
     private var subscriptions: [String: Set<String>] = [:] // relay URL -> active subscription IDs
-    private var pendingSubscriptions: [String: [String: String]] = [:] // relay URL -> (subscription id -> encoded REQ JSON)
+    // Not-yet-flushed REQs per relay, bounded by a per-relay cap (oldest by
+    // insertion order evicted) and an age sweep on connect attempts. Dicts are
+    // unordered, so each entry carries an insertion sequence and queue time.
+    private struct PendingSubscription {
+        let messageString: String // encoded REQ JSON
+        let queuedAt: Date
+        let sequence: UInt64
+    }
+    private var pendingSubscriptions: [String: [String: PendingSubscription]] = [:] // relay URL -> (subscription id -> pending REQ)
+    private var pendingSubscriptionSequence: UInt64 = 0
     private var messageHandlers: [String: (NostrEvent) -> Void] = [:]
+    private struct InboundEventKey: Hashable {
+        let subscriptionID: String
+        let eventID: String
+    }
+    private let recentInboundEventKeyLimit = TransportConfig.nostrInboundEventDedupCap
+    private let recentInboundEventKeyTrimTarget = TransportConfig.nostrInboundEventDedupTrimTarget
+    private var recentInboundEventKeys = Set<InboundEventKey>()
+    private var recentInboundEventKeyOrder: [InboundEventKey] = []
+    private var duplicateInboundEventDropCount = 0
+    private var duplicateInboundEventDropCountBySubscription: [String: Int] = [:]
+    private var inboundEventLogCount = 0
     // Coalesce duplicate subscribe requests for the same id within a short window.
     private let subscribeCoalesceInterval: TimeInterval = 1.0
     private var subscribeCoalesce: [String: Date] = [:]
     private var pendingTorConnectionURLs = Set<String>()
     private var awaitingTorForConnections = false
+    private var torReadyWaitAttempts = 0
     private var cancellables = Set<AnyCancellable>()
 
     private struct SubscriptionRequestState: Equatable {
@@ -155,13 +183,29 @@ final class NostrRelayManager: ObservableObject {
     }
     private var subscriptionRequestState: [String: SubscriptionRequestState] = [:]
 
-    // Track EOSE per subscription to signal when initial stored events are done
+    // Track EOSE per subscription to signal when initial stored events are
+    // done. Completion is scoped to relays the REQ actually reached: targets
+    // still mid-connect must not hold the callback hostage until the fallback
+    // timer (a dead relay of five used to pin "loading" for the full 10s).
     private struct EOSETracker {
-        var pendingRelays: Set<String>
+        /// Targets the REQ has not been delivered to yet (still connecting).
+        var awaitingSend: Set<String>
+        /// Relays that received the REQ and have not sent EOSE yet.
+        var awaitingEOSE: Set<String>
+        /// True once any relay received the REQ (or answered with EOSE) —
+        /// completion with zero sends would mean "done" without ever asking.
+        var didSend = false
         var callback: () -> Void
-        var timer: Timer?
+        let epoch: Int
+
+        /// Done when every relay that got the REQ has resolved, provided at
+        /// least one did — or when every target dropped out entirely.
+        var isComplete: Bool {
+            (didSend && awaitingEOSE.isEmpty) || (awaitingSend.isEmpty && awaitingEOSE.isEmpty)
+        }
     }
     private var eoseTrackers: [String: EOSETracker] = [:]
+    private var eoseTrackerEpoch = 0
     private var pendingEOSECallbacks: [String: () -> Void] = [:]
     
     // Message queue for reliability
@@ -172,6 +216,18 @@ final class NostrRelayManager: ObservableObject {
     }
     private var messageQueue: [PendingSend] = []
     private let messageQueueLock = NSLock()
+    /// Non-queued sends whose callers require relay durability. A WebSocket
+    /// write only proves bytes left this process; NIP-20 OK is the relay's
+    /// accept/reject acknowledgment.
+    private struct ConfirmedSendState {
+        let token: UUID
+        var awaitingRelays: Set<String>
+        let completion: (Bool) -> Void
+    }
+    private var confirmedSends: [String: ConfirmedSendState] = [:]
+    // Total pending sends dropped at the queue cap; drives the sampled
+    // overflow warning (first + every Nth drop).
+    private var pendingSendDropCount = 0
     private let encoder = JSONEncoder()
     private var shouldUseTor: Bool { dependencies.userTorEnabled() }
     
@@ -252,20 +308,82 @@ final class NostrRelayManager: ObservableObject {
             task.cancel(with: .goingAway, reason: nil)
         }
         connections.removeAll()
-        // Clear known subscriptions and any queued subs since connections are gone
+        markRelaySocketsClosed(resetState: false)
+        // Sockets are gone, so per-relay subscription state is cleared — but
+        // durable intent (subscriptionRequestState, messageHandlers, parked
+        // EOSE callbacks) is kept so REQs replay when relays reconnect
+        // (e.g. background → foreground).
         subscriptions.removeAll()
         pendingSubscriptions.removeAll()
-        subscriptionRequestState.removeAll()
+        // Settle in-flight initial loads instead of leaving callers hanging.
-        pendingEOSECallbacks.removeAll()
+        let trackers = eoseTrackers
-        for (_, tracker) in eoseTrackers {
-            tracker.timer?.invalidate()
-        }
         eoseTrackers.removeAll()
+        for (_, tracker) in trackers {
+            tracker.callback()
+        }
+        let confirmed = confirmedSends.values.map(\.completion)
+        confirmedSends.removeAll()
+        confirmed.forEach { $0(false) }
         pendingTorConnectionURLs.removeAll()
         awaitingTorForConnections = false
+        torReadyWaitAttempts = 0
         updateConnectionStatus()
     }
 
+    /// Panic wipe reset: close sockets and drop every user/session-specific
+    /// relay intent without invoking old callbacks. Unlike `disconnect()`, this
+    /// must not preserve subscription replay state because geohash DM handlers
+    /// can capture pre-wipe Nostr private keys.
+    func resetForPanicWipe() {
+        connectionGeneration &+= 1
+        for (_, task) in connections {
+            task.cancel(with: .goingAway, reason: nil)
+        }
+        connections.removeAll()
+        markRelaySocketsClosed(resetState: true)
+        subscriptions.removeAll()
+        pendingSubscriptions.removeAll()
+        messageHandlers.removeAll()
+        subscriptionRequestState.removeAll()
+        subscribeCoalesce.removeAll()
+        eoseTrackers.removeAll()
+        pendingEOSECallbacks.removeAll()
+        pendingTorConnectionURLs.removeAll()
+        awaitingTorForConnections = false
+        torReadyWaitAttempts = 0
+        recentInboundEventKeys.removeAll()
+        recentInboundEventKeyOrder.removeAll()
+        duplicateInboundEventDropCount = 0
+        duplicateInboundEventDropCountBySubscription.removeAll()
+        inboundEventLogCount = 0
+        Self.pendingGiftWrapIDs.removeAll()
+        confirmedSends.removeAll()
+
+        messageQueueLock.lock()
+        messageQueue.removeAll()
+        pendingSendDropCount = 0
+        messageQueueLock.unlock()
+
+        updateConnectionStatus()
+    }
+
+    private func markRelaySocketsClosed(resetState: Bool) {
+        let now = dependencies.now()
+        for index in relays.indices {
+            relays[index].isConnected = false
+            relays[index].nextReconnectTime = nil
+            if resetState {
+                relays[index].lastError = nil
+                relays[index].lastDisconnectedAt = nil
+                relays[index].messagesSent = 0
+                relays[index].messagesReceived = 0
+                relays[index].reconnectAttempts = 0
+            } else {
+                relays[index].lastDisconnectedAt = now
+            }
+        }
+    }
+    
     /// Ensure connections exist to the given relay URLs (idempotent).
     func ensureConnections(to relayUrls: [String]) {
         // Global network policy gate
@@ -285,11 +403,14 @@ final class NostrRelayManager: ObservableObject {
         // Global network policy gate
         guard dependencies.activationAllowed() else { return }
         if shouldUseTor && dependencies.torEnforced() && !dependencies.torIsReady() {
-            // Defer sends until Tor is ready to avoid premature queueing
+            // Fail-closed: nothing touches the network until Tor is up. Queue the
-            dependencies.awaitTorReady { [weak self] ready in
+            // event locally so it survives a slow bootstrap (queued sends flush
-                guard let self = self else { return }
+            // when relays connect), then kick off connection setup, which itself
-                if ready { self.sendEvent(event, to: relayUrls) }
+            // waits for Tor readiness.
-            }
+            let targetRelays = allowedRelayList(from: relayUrls ?? Self.defaultRelays)
+            guard !targetRelays.isEmpty else { return }
+            enqueuePendingSend(event, pendingRelays: Set(targetRelays))
+            ensureConnections(to: targetRelays)
             return
         }
         let requestedRelays = relayUrls ?? Self.defaultRelays
@@ -307,9 +428,120 @@ final class NostrRelayManager: ObservableObject {
             }
         }
         if !stillPending.isEmpty {
+            enqueuePendingSend(event, pendingRelays: stillPending)
+        }
+    }
+
+    /// Attempts an event only on currently connected target relays and
+    /// reports whether at least one relay explicitly accepted it via NIP-20
+    /// OK. A successful WebSocket write alone is not durable acceptance.
+    /// Unlike `sendEvent`, this never enters the process-local pending queue;
+    /// callers use it when success unlocks durable state or user-visible
+    /// delivery progress.
+    func sendEventImmediately(
+        _ event: NostrEvent,
+        to relayUrls: [String]? = nil,
+        completion: @escaping (Bool) -> Void
+    ) {
+        guard dependencies.activationAllowed() else {
+            completion(false)
+            return
+        }
+        guard !(shouldUseTor && dependencies.torEnforced() && !dependencies.torIsReady()) else {
+            completion(false)
+            return
+        }
+
+        let requestedRelays = relayUrls ?? Self.defaultRelays
+        let targetRelays = allowedRelayList(from: requestedRelays)
+        let connectedTargets = targetRelays.compactMap { relayUrl -> (String, NostrRelayConnectionProtocol)? in
+            guard let connection = connectedConnection(for: relayUrl) else { return nil }
+            return (relayUrl, connection)
+        }
+        guard !connectedTargets.isEmpty else {
+            completion(false)
+            return
+        }
+
+        let token = UUID()
+        let eventID = event.id
+        if let replaced = confirmedSends.removeValue(forKey: eventID) {
+            replaced.completion(false)
+        }
+        confirmedSends[eventID] = ConfirmedSendState(
+            token: token,
+            awaitingRelays: Set(connectedTargets.map(\.0)),
+            completion: completion
+        )
+        dependencies.scheduleAfter(TransportConfig.nostrConfirmedSendAckTimeoutSeconds) { [weak self] in
+            Task { @MainActor [weak self] in
+                self?.timeoutConfirmedSend(eventID: eventID, token: token)
+            }
+        }
+
+        for (relayUrl, connection) in connectedTargets {
+            sendToRelay(event: event, connection: connection, relayUrl: relayUrl) { [weak self] succeeded in
+                guard let self else { return }
+                // Success only means the bytes reached the socket; wait for
+                // the matching relay OK. A failed write settles this target
+                // as rejected because no OK can arrive for it.
+                if !succeeded {
+                    self.resolveConfirmedSend(
+                        eventID: eventID,
+                        relayURL: relayUrl,
+                        accepted: false,
+                        token: token
+                    )
+                }
+            }
+        }
+    }
+
+    private func resolveConfirmedSend(
+        eventID: String,
+        relayURL: String,
+        accepted: Bool,
+        token: UUID? = nil
+    ) {
+        guard var state = confirmedSends[eventID],
+              token == nil || state.token == token,
+              state.awaitingRelays.remove(relayURL) != nil else { return }
+        if accepted {
+            confirmedSends.removeValue(forKey: eventID)
+            state.completion(true)
+        } else if state.awaitingRelays.isEmpty {
+            confirmedSends.removeValue(forKey: eventID)
+            state.completion(false)
+        } else {
+            confirmedSends[eventID] = state
+        }
+    }
+
+    private func timeoutConfirmedSend(eventID: String, token: UUID) {
+        guard let state = confirmedSends[eventID], state.token == token else { return }
+        confirmedSends.removeValue(forKey: eventID)
+        state.completion(false)
+    }
+
+    private func enqueuePendingSend(_ event: NostrEvent, pendingRelays: Set<String>) {
         messageQueueLock.lock()
-            messageQueue.append(PendingSend(event: event, pendingRelays: stillPending))
+        messageQueue.append(PendingSend(event: event, pendingRelays: pendingRelays))
+        let overflow = messageQueue.count - TransportConfig.nostrPendingSendQueueCap
+        if overflow > 0 {
+            messageQueue.removeFirst(overflow)
+        }
         messageQueueLock.unlock()
+        guard overflow > 0 else { return }
+        // Dropped events are ephemeral (presence/geo), so no status surfacing
+        // is needed — but the drops should be visible. Sampled so a sustained
+        // relay stall can't flood the log.
+        pendingSendDropCount += overflow
+        if pendingSendDropCount == 1 ||
+            pendingSendDropCount.isMultiple(of: TransportConfig.nostrPendingSendDropLogInterval) {
+            SecureLogger.warning(
+                "📤 Relay send queue full — dropped \(pendingSendDropCount) oldest event(s)",
+                category: .session
+            )
         }
     }
 
@@ -404,16 +636,14 @@ final class NostrRelayManager: ObservableObject {
                 existingSet.insert(url)
             }
             for url in urls {
-                var map = self.pendingSubscriptions[url] ?? [:]
+                queuePendingSubscription(id: id, messageString: messageString, for: url)
-                map[id] = messageString
-                self.pendingSubscriptions[url] = map
             }
             // Initialize EOSE tracking if requested
             if let onEOSE = onEOSE {
                 if urls.isEmpty {
                     onEOSE()
                 } else if shouldWaitForTorBeforeConnecting {
-                    pendingEOSECallbacks[id] = onEOSE
+                    parkEOSECallbackUntilTorReady(id: id, callback: onEOSE)
                 } else {
                     startEOSETracking(id: id, relayURLs: Set(urls), callback: onEOSE)
                 }
@@ -486,11 +716,12 @@ final class NostrRelayManager: ObservableObject {
     /// Unsubscribe from a subscription
     func unsubscribe(id: String) {
         messageHandlers.removeValue(forKey: id)
+        removeRecentInboundEvents(forSubscriptionID: id)
+        duplicateInboundEventDropCountBySubscription.removeValue(forKey: id)
         // Allow immediate re-subscription by clearing coalescer timestamp
         subscribeCoalesce.removeValue(forKey: id)
         subscriptionRequestState.removeValue(forKey: id)
         pendingEOSECallbacks.removeValue(forKey: id)
-        eoseTrackers[id]?.timer?.invalidate()
         eoseTrackers.removeValue(forKey: id)
         for url in Array(pendingSubscriptions.keys) {
             pendingSubscriptions[url]?.removeValue(forKey: id)
@@ -521,6 +752,7 @@ final class NostrRelayManager: ObservableObject {
 
     private func connectToRelays(_ relayUrls: [String], shouldLog: Bool = false) {
         guard dependencies.activationAllowed() else { return }
+        sweepStalePendingSubscriptions()
         let targets = allowedRelayList(from: relayUrls).filter {
             connections[$0] == nil && !isPermanentlyFailed($0)
         }
@@ -561,38 +793,136 @@ final class NostrRelayManager: ObservableObject {
             self.awaitingTorForConnections = false
 
             guard ready else {
-                SecureLogger.error("❌ Tor not ready; aborting relay connections (fail-closed)", category: .session)
+                self.torReadyWaitAttempts += 1
+                if self.torReadyWaitAttempts < TransportConfig.nostrTorReadyMaxWaitAttempts {
+                    SecureLogger.warning("Tor not ready; re-queueing \(pending.count) relay connection(s) (attempt \(self.torReadyWaitAttempts))", category: .session)
+                    self.queueConnectionsUntilTorReady(pending)
+                } else {
+                    // Still fail-closed (no network), but unblock any callers
+                    // waiting on EOSE so the UI doesn't hang indefinitely.
+                    // Queued subscriptions/sends are kept and flush if a later
+                    // trigger (e.g. app foreground) brings Tor up.
+                    SecureLogger.error("❌ Tor not ready after \(self.torReadyWaitAttempts) wait(s); aborting relay connections (fail-closed)", category: .session)
+                    self.torReadyWaitAttempts = 0
+                    self.unblockPendingEOSECallbacks(reason: "tor-unavailable")
+                }
                 return
             }
 
+            self.torReadyWaitAttempts = 0
             self.connectToRelays(pending, shouldLog: true)
         }
     }
 
+    /// Park an EOSE callback while Tor is not yet ready, and schedule the same
+    /// fallback timeout `startEOSETracking` uses. Without it, a parked callback
+    /// would only be unblocked by Tor-readiness retry exhaustion (several
+    /// awaitReady timeouts, i.e. minutes), leaving callers hanging far past the
+    /// normal EOSE fallback. If Tor recovers first the callback is promoted to
+    /// a real EOSE tracker (`startPendingEOSETrackingIfNeeded`), and if retry
+    /// exhaustion fires first it is drained by `unblockPendingEOSECallbacks`;
+    /// either way it leaves `pendingEOSECallbacks` and this timer is a no-op.
+    private func parkEOSECallbackUntilTorReady(id: String, callback: @escaping () -> Void) {
+        pendingEOSECallbacks[id] = callback
+        let generation = connectionGeneration
+        dependencies.scheduleAfter(TransportConfig.nostrSubscriptionEOSEFallbackSeconds) { [weak self] in
+            Task { @MainActor [weak self] in
+                guard let self else { return }
+                // Stale timers from a previous connection generation are void.
+                guard generation == self.connectionGeneration else { return }
+                // Already fired (unsubscribe, retry-exhaustion unblock) or
+                // promoted to a real EOSE tracker: nothing to do.
+                guard let callback = self.pendingEOSECallbacks.removeValue(forKey: id) else { return }
+                SecureLogger.warning("Unblocking Tor-parked EOSE callback for \(id) after fallback timeout", category: .session)
+                callback()
+            }
+        }
+    }
+
+    /// Fire and clear all EOSE callbacks that are parked waiting for Tor.
+    /// Callers treat EOSE as "initial fetch finished"; firing with no data is
+    /// safe and prevents indefinite hangs when Tor cannot bootstrap.
+    private func unblockPendingEOSECallbacks(reason: String) {
+        guard !pendingEOSECallbacks.isEmpty else { return }
+        let callbacks = pendingEOSECallbacks
+        pendingEOSECallbacks.removeAll()
+        SecureLogger.warning("Unblocking \(callbacks.count) pending EOSE callback(s) without data (\(reason))", category: .session)
+        for (_, callback) in callbacks {
+            callback()
+        }
+    }
+
     private func subscriptionStateExists(id: String, requestState: SubscriptionRequestState) -> Bool {
         guard !requestState.relayURLs.isEmpty else { return true }
         return requestState.relayURLs.allSatisfy { url in
-            pendingSubscriptions[url]?[id] == requestState.messageString ||
+            pendingSubscriptions[url]?[id]?.messageString == requestState.messageString ||
                 subscriptions[url]?.contains(id) == true
         }
     }
 
+    private func queuePendingSubscription(id: String, messageString: String, for url: String) {
+        var map = pendingSubscriptions[url] ?? [:]
+        pendingSubscriptionSequence &+= 1
+        map[id] = PendingSubscription(
+            messageString: messageString,
+            queuedAt: dependencies.now(),
+            sequence: pendingSubscriptionSequence
+        )
+        // Bound per-relay pending REQs; evict oldest by insertion order. The
+        // durable intent stays in subscriptionRequestState, so an evicted REQ
+        // is still replayed if its subscription is active when the relay
+        // (re)connects.
+        var evictedCount = 0
+        while map.count > TransportConfig.nostrPendingSubscriptionsPerRelayCap,
+              let oldest = map.min(by: { $0.value.sequence < $1.value.sequence }) {
+            map.removeValue(forKey: oldest.key)
+            evictedCount += 1
+        }
+        if evictedCount > 0 {
+            // Bounds proof: the cap eviction actually removed entries.
+            SecureLogger.warning(
+                "📋 Evicted \(evictedCount) pending sub(s) over cap for \(url)",
+                category: .session
+            )
+        }
+        pendingSubscriptions[url] = map
+    }
+
+    /// Drop pending REQs older than the TTL. Runs on connect attempts (the
+    /// natural maintenance path: connect/ensureConnections/reconnects all
+    /// funnel through connectToRelays) so stale entries for relays that never
+    /// come up cannot accumulate without bound.
+    private func sweepStalePendingSubscriptions() {
+        let now = dependencies.now()
+        for (url, map) in pendingSubscriptions {
+            let fresh = map.filter {
+                now.timeIntervalSince($0.value.queuedAt) <= TransportConfig.nostrPendingSubscriptionTTLSeconds
+            }
+            guard fresh.count != map.count else { continue }
+            // Bounds proof: the age sweep actually removed entries. Warning
+            // (not debug) — stale pending REQs mean a relay never came up.
+            SecureLogger.warning(
+                "📋 Swept \(map.count - fresh.count) stale pending sub(s) for \(url)",
+                category: .session
+            )
+            pendingSubscriptions[url] = fresh.isEmpty ? nil : fresh
+        }
+    }
+
     private func startEOSETracking(id: String, relayURLs: Set<String>, callback: @escaping () -> Void) {
-        eoseTrackers[id]?.timer?.invalidate()
+        eoseTrackerEpoch += 1
-        var tracker = EOSETracker(pendingRelays: relayURLs, callback: callback, timer: nil)
+        let epoch = eoseTrackerEpoch
+        eoseTrackers[id] = EOSETracker(awaitingSend: relayURLs, awaitingEOSE: [], callback: callback, epoch: epoch)
         // Fallback timeout to avoid hanging if a relay never sends EOSE.
-        tracker.timer = Timer.scheduledTimer(withTimeInterval: 2.0, repeats: false) { [weak self] _ in
+        dependencies.scheduleAfter(TransportConfig.nostrSubscriptionEOSEFallbackSeconds) { [weak self] in
-            Task { @MainActor in
+            Task { @MainActor [weak self] in
                 guard let self else { return }
-                if let tracker = self.eoseTrackers[id] {
+                guard let tracker = self.eoseTrackers[id], tracker.epoch == epoch else { return }
-                    tracker.timer?.invalidate()
                 self.eoseTrackers.removeValue(forKey: id)
-                    callback()
+                tracker.callback()
             }
         }
     }
-        eoseTrackers[id] = tracker
-    }
 
     private func startPendingEOSETrackingIfNeeded(id: String) {
         guard eoseTrackers[id] == nil,
@@ -609,6 +939,53 @@ final class NostrRelayManager: ObservableObject {
         }
     }
 
+    private func shouldDeliverInboundEvent(subscriptionID: String, eventID: String) -> Bool {
+        guard !eventID.isEmpty else { return true }
+        let key = InboundEventKey(subscriptionID: subscriptionID, eventID: eventID)
+        guard recentInboundEventKeys.insert(key).inserted else {
+            recordDuplicateInboundEventDrop(subscriptionID: subscriptionID)
+            return false
+        }
+        recentInboundEventKeyOrder.append(key)
+
+        if recentInboundEventKeyOrder.count > recentInboundEventKeyLimit {
+            let removeCount = recentInboundEventKeyOrder.count - recentInboundEventKeyTrimTarget
+            for staleKey in recentInboundEventKeyOrder.prefix(removeCount) {
+                recentInboundEventKeys.remove(staleKey)
+            }
+            recentInboundEventKeyOrder.removeFirst(removeCount)
+        }
+        return true
+    }
+
+    private func recordDuplicateInboundEventDrop(subscriptionID: String) {
+        duplicateInboundEventDropCount += 1
+        let subscriptionCount = (duplicateInboundEventDropCountBySubscription[subscriptionID] ?? 0) + 1
+        duplicateInboundEventDropCountBySubscription[subscriptionID] = subscriptionCount
+
+        if duplicateInboundEventDropCount == 1 ||
+            duplicateInboundEventDropCount.isMultiple(of: TransportConfig.nostrDuplicateEventLogInterval) {
+            SecureLogger.debug(
+                "Dropped duplicate Nostr event deliveries total=\(duplicateInboundEventDropCount) sub=\(subscriptionID) sub_total=\(subscriptionCount)",
+                category: .session
+            )
+        }
+    }
+
+    private func removeRecentInboundEvents(forSubscriptionID subscriptionID: String) {
+        guard !recentInboundEventKeyOrder.isEmpty else { return }
+        var retainedKeys: [InboundEventKey] = []
+        retainedKeys.reserveCapacity(recentInboundEventKeyOrder.count)
+        for key in recentInboundEventKeyOrder {
+            if key.subscriptionID == subscriptionID {
+                recentInboundEventKeys.remove(key)
+            } else {
+                retainedKeys.append(key)
+            }
+        }
+        recentInboundEventKeyOrder = retainedKeys
+    }
+    
     private func connectToRelay(_ urlString: String) {
         // Global network policy gate
         guard dependencies.activationAllowed() else { return }
@@ -650,6 +1027,7 @@ final class NostrRelayManager: ObservableObject {
         // Send initial ping to verify connection
         task.sendPing { [weak self] error in
             DispatchQueue.main.async {
+                guard self?.connections[urlString] === task else { return }
                 if error == nil {
                     SecureLogger.debug("✅ Connected to Nostr relay: \(urlString)", category: .session)
                     self?.updateRelayStatus(urlString, isConnected: true)
@@ -659,32 +1037,56 @@ final class NostrRelayManager: ObservableObject {
                     SecureLogger.error("❌ Failed to connect to Nostr relay \(urlString): \(error?.localizedDescription ?? "Unknown error")", category: .session)
                     self?.updateRelayStatus(urlString, isConnected: false, error: error)
                     // Trigger disconnection handler for proper backoff
-                    self?.handleDisconnection(relayUrl: urlString, error: error ?? NSError(domain: "NostrRelay", code: -1, userInfo: nil))
+                    self?.handleDisconnection(
+                        relayUrl: urlString,
+                        error: error ?? NSError(domain: "NostrRelay", code: -1, userInfo: nil),
+                        connection: task
+                    )
                 }
             }
         }
     }
 
-    /// Send any queued subscriptions for a relay that just connected.
+    /// Send queued subscriptions and replay durable ones for a relay that just
+    /// (re)connected. Relays drop subscriptions with the socket, so every
+    /// active subscription targeting this relay must be re-sent.
     private func flushPendingSubscriptions(for relayUrl: String) {
-        guard let map = pendingSubscriptions[relayUrl], !map.isEmpty else { return }
         guard let connection = connections[relayUrl] else { return }
-        for (id, messageString) in map {
+        var toSend = (pendingSubscriptions[relayUrl] ?? [:]).mapValues(\.messageString)
-            if self.subscriptions[relayUrl]?.contains(id) == true { continue }
+        for (id, state) in subscriptionRequestState where state.relayURLs.contains(relayUrl) && toSend[id] == nil {
+            toSend[id] = state.messageString
+        }
+        for (id, messageString) in toSend {
+            if self.subscriptions[relayUrl]?.contains(id) == true {
+                // Already subscribed on this relay (e.g. a tracker promoted
+                // after an earlier flush): its EOSE is coming, count it.
+                markEOSESubscribed(id: id, relayUrl: relayUrl)
+                continue
+            }
             startPendingEOSETrackingIfNeeded(id: id)
-            connection.send(.string(messageString)) { error in
+            // Mark at send *initiation*, not in the async completion: a fast
+            // relay's EOSE could otherwise complete the tracker while this
+            // relay — REQ already on the wire — still sat in awaitingSend.
+            // If the send fails the socket is going down with it, and the
+            // disconnect settle (or the fallback timer) releases the wait.
+            markEOSESubscribed(id: id, relayUrl: relayUrl)
+            connection.send(.string(messageString)) { [weak self, weak connection] error in
+                Task { @MainActor [weak self] in
+                    guard let self else { return }
                     if let error = error {
+                        // Keep the pending entry; the next (re)connect retries it.
                         SecureLogger.error("❌ Failed to send pending subscription to \(relayUrl): \(error)", category: .session)
                     } else {
-                    Task { @MainActor in
+                        // A stale completion from a socket that has since been
-                        var subs = self.subscriptions[relayUrl] ?? Set<String>()
+                        // replaced must not mark the subscription active, or
-                        subs.insert(id)
+                        // the next connection would skip replaying it.
-                        self.subscriptions[relayUrl] = subs
+                        guard let connection, self.connections[relayUrl] === connection else { return }
+                        self.subscriptions[relayUrl, default: []].insert(id)
+                        self.pendingSubscriptions[relayUrl]?.removeValue(forKey: id)
                     }
                 }
             }
         }
-        pendingSubscriptions[relayUrl] = nil
     }
     
     private func receiveMessage(from task: NostrRelayConnectionProtocol, relayUrl: String) {
@@ -697,18 +1099,20 @@ final class NostrRelayManager: ObservableObject {
                 Task.detached(priority: .utility) {
                     guard let parsed = ParsedInbound(message) else { return }
                     await MainActor.run {
+                        guard self.connections[relayUrl] === task else { return }
                         self.handleParsedMessage(parsed, from: relayUrl)
                     }
                 }
                 
                 // Continue receiving
                 Task { @MainActor in
+                    guard self.connections[relayUrl] === task else { return }
                     self.receiveMessage(from: task, relayUrl: relayUrl)
                 }
                 
             case .failure(let error):
                 DispatchQueue.main.async {
-                    self.handleDisconnection(relayUrl: relayUrl, error: error)
+                    self.handleDisconnection(relayUrl: relayUrl, error: error, connection: task)
                 }
             }
         }
@@ -722,12 +1126,26 @@ final class NostrRelayManager: ObservableObject {
     private func handleParsedMessage(_ parsed: ParsedInbound, from relayUrl: String) {
         switch parsed {
         case .event(let subId, let event):
-            if event.kind != 1059 {
-                SecureLogger.debug("📥 Event kind=\(event.kind) id=\(event.id.prefix(16))… relay=\(relayUrl)", category: .session)
-            }
             if let index = self.relays.firstIndex(where: { $0.url == relayUrl }) {
                 self.relays[index].messagesReceived += 1
             }
+            guard event.isValidSignature() else {
+                SecureLogger.warning(
+                    "⚠️ Dropped invalid Nostr event id=\(event.id.prefix(16))… sub=\(subId) relay=\(relayUrl)",
+                    category: .session
+                )
+                return
+            }
+            guard shouldDeliverInboundEvent(subscriptionID: subId, eventID: event.id) else {
+                return
+            }
+            if event.kind != 1059 {
+                // Per-event logging floods dev builds in busy geohashes; sample it.
+                inboundEventLogCount += 1
+                if inboundEventLogCount == 1 || inboundEventLogCount.isMultiple(of: TransportConfig.nostrInboundEventLogInterval) {
+                    SecureLogger.debug("📥 Event #\(inboundEventLogCount) kind=\(event.kind) id=\(event.id.prefix(16))… relay=\(relayUrl)", category: .session)
+                }
+            }
             if let handler = self.messageHandlers[subId] {
                 handler(event)
             } else {
@@ -735,9 +1153,12 @@ final class NostrRelayManager: ObservableObject {
             }
         case .eose(let subId):
             if var tracker = eoseTrackers[subId] {
-                tracker.pendingRelays.remove(relayUrl)
+                // An EOSE proves the relay received the REQ even if the local
-                if tracker.pendingRelays.isEmpty {
+                // send completion hasn't run yet.
-                    tracker.timer?.invalidate()
+                tracker.awaitingSend.remove(relayUrl)
+                tracker.awaitingEOSE.remove(relayUrl)
+                tracker.didSend = true
+                if tracker.isComplete {
                     eoseTrackers.removeValue(forKey: subId)
                     tracker.callback()
                 } else {
@@ -745,6 +1166,7 @@ final class NostrRelayManager: ObservableObject {
                 }
             }
         case .ok(let eventId, let success, let reason):
+            resolveConfirmedSend(eventID: eventId, relayURL: relayUrl, accepted: success)
             if success {
                 _ = Self.pendingGiftWrapIDs.remove(eventId)
                 SecureLogger.debug("✅ Accepted id=\(eventId.prefix(16))… relay=\(relayUrl)", category: .session)
@@ -761,7 +1183,12 @@ final class NostrRelayManager: ObservableObject {
         }
     }
     
-    private func sendToRelay(event: NostrEvent, connection: NostrRelayConnectionProtocol, relayUrl: String) {
+    private func sendToRelay(
+        event: NostrEvent,
+        connection: NostrRelayConnectionProtocol,
+        relayUrl: String,
+        completion: ((Bool) -> Void)? = nil
+    ) {
         let req = NostrRequest.event(event)
         
         do {
@@ -774,17 +1201,20 @@ final class NostrRelayManager: ObservableObject {
                 DispatchQueue.main.async {
                     if let error = error {
                         SecureLogger.error("❌ Failed to send event to \(relayUrl): \(error)", category: .session)
+                        completion?(false)
                     } else {
                         // SecureLogger.debug("✅ Event sent to relay: \(relayUrl)", category: .session)
                         // Update relay stats
                         if let index = self?.relays.firstIndex(where: { $0.url == relayUrl }) {
                             self?.relays[index].messagesSent += 1
                         }
+                        completion?(true)
                     }
                 }
             }
         } catch {
             SecureLogger.error("Failed to encode event: \(error)", category: .session)
+            completion?(false)
         }
     }
     
@@ -793,7 +1223,6 @@ final class NostrRelayManager: ObservableObject {
             relays[index].isConnected = isConnected
             relays[index].lastError = error
             if isConnected {
-                relays[index].lastConnectedAt = dependencies.now()
                 relays[index].reconnectAttempts = 0  // Reset on successful connection
                 relays[index].nextReconnectTime = nil
             } else {
@@ -809,19 +1238,66 @@ final class NostrRelayManager: ObservableObject {
     
     private func updateConnectionStatus() {
         isConnected = relays.contains { $0.isConnected }
+        // Relay URLs are normalized before entries are created, so direct
+        // set membership is sound.
+        isDMRelayConnected = relays.contains { $0.isConnected && Self.defaultRelaySet.contains($0.url) }
     }
     
-    private func handleDisconnection(relayUrl: String, error: Error) {
+    /// A relay that drops before sending EOSE must not stall initial-load
+    /// callbacks; treat it as done and let the remaining relays (or the
+    /// fallback timeout) drive completion.
+    private func settleEOSETrackers(droppingRelay relayUrl: String) {
+        for (id, var tracker) in eoseTrackers
+        where tracker.awaitingSend.contains(relayUrl) || tracker.awaitingEOSE.contains(relayUrl) {
+            tracker.awaitingSend.remove(relayUrl)
+            tracker.awaitingEOSE.remove(relayUrl)
+            if tracker.isComplete {
+                eoseTrackers.removeValue(forKey: id)
+                tracker.callback()
+            } else {
+                eoseTrackers[id] = tracker
+            }
+        }
+    }
+
+    /// Whether any of `relayUrls` currently holds a live connection. Lets
+    /// subscribers distinguish "loaded, empty" from "never reached a relay"
+    /// when an EOSE fallback fires.
+    func isAnyRelayConnected(among relayUrls: [String]) -> Bool {
+        let targets = Set(relayUrls)
+        return relays.contains { targets.contains($0.url) && $0.isConnected }
+    }
+
+    /// Marks the REQ as delivered to `relayUrl`: EOSE completion now waits on
+    /// this relay instead of the never-connected remainder.
+    private func markEOSESubscribed(id: String, relayUrl: String) {
+        guard var tracker = eoseTrackers[id],
+              tracker.awaitingSend.remove(relayUrl) != nil else { return }
+        tracker.awaitingEOSE.insert(relayUrl)
+        tracker.didSend = true
+        eoseTrackers[id] = tracker
+    }
+
+    private func handleDisconnection(
+        relayUrl: String,
+        error: Error,
+        connection: NostrRelayConnectionProtocol? = nil
+    ) {
+        if let connection, connections[relayUrl] !== connection { return }
+        connections.removeValue(forKey: relayUrl)
+        subscriptions.removeValue(forKey: relayUrl)
+        let awaitingConfirmation = confirmedSends.compactMap { eventID, state in
+            state.awaitingRelays.contains(relayUrl) ? eventID : nil
+        }
+        for eventID in awaitingConfirmation {
+            resolveConfirmedSend(eventID: eventID, relayURL: relayUrl, accepted: false)
+        }
+        updateRelayStatus(relayUrl, isConnected: false, error: error)
+        settleEOSETrackers(droppingRelay: relayUrl)
         // If networking is disallowed, do not schedule reconnection
         if !dependencies.activationAllowed() {
-            connections.removeValue(forKey: relayUrl)
-            subscriptions.removeValue(forKey: relayUrl)
-            updateRelayStatus(relayUrl, isConnected: false, error: error)
             return
         }
-        connections.removeValue(forKey: relayUrl)
-        subscriptions.removeValue(forKey: relayUrl)
-        updateRelayStatus(relayUrl, isConnected: false, error: error)
         
         // Check if this is a DNS or handshake error; treat as permanent
         let errorDescription = error.localizedDescription.lowercased()
@@ -852,15 +1328,25 @@ final class NostrRelayManager: ObservableObject {
             return
         }
         
-        // Calculate backoff interval
+        // Calculate backoff interval with ±jitterRatio random jitter so relays
-        let backoffInterval = min(
+        // that dropped together don't all reconnect at the same instant.
+        let baseBackoffInterval = min(
             initialBackoffInterval * pow(backoffMultiplier, Double(relays[index].reconnectAttempts - 1)),
             maxBackoffInterval
         )
+        let jitterRatio = TransportConfig.nostrRelayBackoffJitterRatio
+        let jitterFactor = 1.0 + (dependencies.jitterUnit() * 2.0 - 1.0) * jitterRatio
+        let backoffInterval = baseBackoffInterval * jitterFactor
 
         let nextReconnectTime = dependencies.now().addingTimeInterval(backoffInterval)
         relays[index].nextReconnectTime = nextReconnectTime
 
+        // Reconnects are bounded by maxReconnectAttempts and exponentially
+        // backed off, so this is low-frequency: plain debug, no sampling.
+        SecureLogger.debug(
+            "🔄 Reconnect \(relayUrl) in \(String(format: "%.1f", backoffInterval))s (base \(String(format: "%.1f", baseBackoffInterval))s, attempt \(relays[index].reconnectAttempts)/\(maxReconnectAttempts))",
+            category: .session
+        )
 
         // Schedule reconnection with exponential backoff
         let gen = connectionGeneration
@@ -919,6 +1405,31 @@ final class NostrRelayManager: ObservableObject {
         pendingSubscriptions[relayUrl]?.count ?? 0
     }
 
+    func debugPendingSubscriptionIDs(for relayUrl: String) -> Set<String> {
+        guard let map = pendingSubscriptions[relayUrl] else { return [] }
+        return Set(map.keys)
+    }
+
+    var debugMessageHandlerCount: Int {
+        messageHandlers.count
+    }
+
+    var debugSubscriptionRequestCount: Int {
+        subscriptionRequestState.count
+    }
+
+    var debugPendingEOSECallbackCount: Int {
+        pendingEOSECallbacks.count
+    }
+
+    var debugDuplicateInboundEventDropCount: Int {
+        duplicateInboundEventDropCount
+    }
+
+    func debugDuplicateInboundEventDropCount(forSubscriptionID subscriptionID: String) -> Int {
+        duplicateInboundEventDropCountBySubscription[subscriptionID] ?? 0
+    }
+
     func debugFlushMessageQueue() {
         flushMessageQueue(for: nil)
     }
@@ -943,6 +1454,13 @@ final class NostrRelayManager: ObservableObject {
     // MARK: - Failure classification
     private func isPermanentlyFailed(_ url: String) -> Bool {
         guard let r = relays.first(where: { $0.url == url }) else { return false }
+        // Failures decay: after a cooldown the relay gets another chance, so a
+        // long network outage or transient relay trouble can't blacklist it
+        // for the rest of the process lifetime.
+        if let lastDisconnect = r.lastDisconnectedAt,
+           dependencies.now().timeIntervalSince(lastDisconnect) >= TransportConfig.nostrRelayFailureCooldownSeconds {
+            return false
+        }
         if r.reconnectAttempts >= maxReconnectAttempts { return true }
         if let ns = r.lastError as NSError?, ns.domain == NSURLErrorDomain {
             if ns.code == NSURLErrorBadServerResponse || ns.code == NSURLErrorCannotFindHost {
@@ -974,8 +1492,7 @@ private enum ParsedInbound {
             if array.count >= 3,
                let subId = array[1] as? String,
                let eventDict = array[2] as? [String: Any],
-               let event = try? NostrEvent(from: eventDict),
+               let event = try? NostrEvent(from: eventDict) {
-               event.isValidSignature() {
                 self = .event(subId: subId, event: event)
                 return
             }
@@ -1124,6 +1641,29 @@ struct NostrFilter: Encodable {
         filter.limit = limit
         return filter
     }
+
+    // For the mesh bridge: rendezvous messages (kind 20000) and presence
+    // (kind 20001) tagged `#r` with one or more cells (own + neighbors).
+    static func bridgeRendezvous(_ cells: [String], since: Date? = nil, limit: Int = 200) -> NostrFilter {
+        var filter = NostrFilter()
+        filter.kinds = [20000, 20001]
+        filter.since = since?.timeIntervalSince1970.toInt()
+        filter.tagFilters = ["r": cells]
+        filter.limit = limit
+        return filter
+    }
+
+    // For courier drops: sealed envelopes (kind 1401) parked under rotating
+    // recipient tags (`#x`, hex). Callers pass every candidate tag (adjacent
+    // UTC days x recipients) in one filter.
+    static func courierDrops(recipientTagsHex: [String], since: Date? = nil, limit: Int = 100) -> NostrFilter {
+        var filter = NostrFilter()
+        filter.kinds = [NostrProtocol.EventKind.courierDrop.rawValue]
+        filter.since = since?.timeIntervalSince1970.toInt()
+        filter.tagFilters = ["x": recipientTagsHex]
+        filter.limit = limit
+        return filter
+    }
 }
 
 // Dynamic coding key for tag filters

bitchat/Nostr/XChaCha20Poly1305Compat.swift

@@ -132,4 +132,3 @@ private extension Data {
         replaceSubrange(offset..<(offset+4), with: bytes)
     }
 }
-

bitchat/PrivacyInfo.xcprivacy

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>NSPrivacyTracking</key>
+	<false/>
+	<key>NSPrivacyTrackingDomains</key>
+	<array/>
+	<key>NSPrivacyCollectedDataTypes</key>
+	<array/>
+	<key>NSPrivacyAccessedAPITypes</key>
+	<array>
+		<dict>
+			<key>NSPrivacyAccessedAPIType</key>
+			<string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
+			<key>NSPrivacyAccessedAPITypeReasons</key>
+			<array>
+				<string>C617.1</string>
+				<string>3B52.1</string>
+			</array>
+		</dict>
+		<dict>
+			<key>NSPrivacyAccessedAPIType</key>
+			<string>NSPrivacyAccessedAPICategorySystemBootTime</string>
+			<key>NSPrivacyAccessedAPITypeReasons</key>
+			<array>
+				<string>35F9.1</string>
+			</array>
+		</dict>
+		<dict>
+			<key>NSPrivacyAccessedAPIType</key>
+			<string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+			<key>NSPrivacyAccessedAPITypeReasons</key>
+			<array>
+				<string>CA92.1</string>
+				<string>1C8F.1</string>
+			</array>
+		</dict>
+	</array>
+</dict>
+</plist>

bitchat/Protocols/BitchatProtocol.swift

@@ -18,7 +18,7 @@
 /// - Efficient binary message encoding
 /// - Message fragmentation for large payloads
 /// - TTL-based routing for mesh networks
-/// - Privacy features like padding and timing obfuscation
+/// - Privacy features: message padding and randomized relay jitter
 /// - Integration points for end-to-end encryption
 ///
 /// ## Protocol Design
@@ -38,18 +38,20 @@
 /// 7. **Decoding**: Binary data parsed back to message objects
 ///
 /// ## Security Considerations
-/// - Message padding obscures actual content length
+/// - Message padding (to 256/512/1024/2048-byte blocks) obscures actual content length
-/// - Timing obfuscation prevents traffic analysis
+/// - Randomized relay jitter reduces the traffic-analysis signal; there is no
+///   cover traffic or per-message timing obfuscation
 /// - Integration with Noise Protocol for E2E encryption
 /// - No persistent identifiers in protocol headers
 ///
 /// ## Message Types
 /// - **Announce/Leave**: Peer presence notifications
-/// - **Message**: User chat messages (broadcast or directed)
+/// - **Message**: Public chat messages
 /// - **Fragment**: Multi-part message handling
-/// - **Delivery/Read**: Message acknowledgments
+/// - **NoiseHandshake/NoiseEncrypted**: Encrypted channel establishment and
-/// - **Noise**: Encrypted channel establishment
+///   all private payloads (messages, delivery acks, read receipts)
-/// - **Version**: Protocol version negotiation
+/// - **CourierEnvelope**: Sealed store-and-forward mail
+/// - **RequestSync/FileTransfer**: Gossip history sync and media transfer
 ///
 /// ## Future Extensions
 /// The protocol is designed to be extensible:
@@ -72,17 +74,28 @@ enum NoisePayloadType: UInt8 {
     case privateMessage = 0x01      // Private chat message
     case readReceipt = 0x02         // Message was read
     case delivered = 0x03           // Message was delivered
+    // Private groups (0x04/0x05 reserved by other features)
+    case groupInvite = 0x06         // Creator-signed group state (invite)
+    case groupKeyUpdate = 0x07      // Creator-signed group state (key rotation / roster update)
+    // Live voice (push-to-talk)
+    case voiceFrame = 0x08          // One live voice-burst packet (see VoiceBurstPacket)
     // Verification (QR-based OOB binding)
     case verifyChallenge = 0x10     // Verification challenge
     case verifyResponse  = 0x11     // Verification response
+    // Transitive verification (web of trust)
+    case vouch = 0x12               // Batch of vouch attestations
 
     var description: String {
         switch self {
         case .privateMessage: return "privateMessage"
         case .readReceipt: return "readReceipt"
         case .delivered: return "delivered"
+        case .groupInvite: return "groupInvite"
+        case .groupKeyUpdate: return "groupKeyUpdate"
+        case .voiceFrame: return "voiceFrame"
         case .verifyChallenge: return "verifyChallenge"
         case .verifyResponse: return "verifyResponse"
+        case .vouch: return "vouch"
         }
     }
 }
@@ -114,6 +127,12 @@ protocol BitchatDelegate: AnyObject {
     // Low-level events for better separation of concerns
     func didReceiveNoisePayload(from peerID: PeerID, type: NoisePayloadType, payload: Data, timestamp: Date)
 
+    // Encrypted group broadcast (opaque envelope; decrypted by the group coordinator)
+    func didReceiveGroupMessage(payload: Data, timestamp: Date)
+
+    // Public live-voice burst packet (signature-verified by the transport)
+    func didReceivePublicVoiceFrame(from peerID: PeerID, nickname: String, payload: Data, timestamp: Date)
+
     // Bluetooth state updates for user notifications
     func didUpdateBluetoothState(_ state: CBManagerState)
     func didReceivePublicMessage(from peerID: PeerID, nickname: String, content: String, timestamp: Date, messageID: String?)
@@ -133,6 +152,14 @@ extension BitchatDelegate {
         // Default empty implementation
     }
 
+    func didReceiveGroupMessage(payload: Data, timestamp: Date) {
+        // Default empty implementation
+    }
+
+    func didReceivePublicVoiceFrame(from peerID: PeerID, nickname: String, payload: Data, timestamp: Date) {
+        // Default empty implementation
+    }
+
     func didReceivePublicMessage(from peerID: PeerID, nickname: String, content: String, timestamp: Date, messageID: String?) {
         // Default empty implementation
     }

bitchat/Protocols/BoardPackets.swift

@@ -0,0 +1,348 @@
+//
+// BoardPackets.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import CryptoKit
+import Foundation
+
+// MARK: - Board wire format (MessageType.boardPost payloads)
+//
+// TLV layout (type u8, length u16 big-endian, value), matching REQUEST_SYNC:
+//  - 0x01: kind (u8) — 0x01 post, 0x02 tombstone
+//  - 0x02: postID (16B random)
+//  - 0x03: geohash (UTF-8, empty = mesh-local board, max 12 chars)
+//  - 0x04: content (UTF-8, 1...512 bytes) [post]
+//  - 0x05: authorSigningKey (32B Ed25519 public key)
+//  - 0x06: authorNickname (UTF-8, max 64 bytes)
+//  - 0x07: createdAt (u64 big-endian, ms) [post]
+//  - 0x08: expiresAt (u64 big-endian, ms, max 7 days after createdAt) [post]
+//  - 0x09: flags (u8, bit0 = urgent) [post]
+//  - 0x0A: signature (64B Ed25519)
+//  - 0x0B: deletedAt (u64 big-endian, ms) [tombstone]
+// Unknown TLVs are skipped for forward compatibility.
+
+enum BoardWireConstants {
+    static let postIDLength = 16
+    static let signingKeyLength = 32
+    static let signatureLength = 64
+    static let contentMaxBytes = 512
+    static let nicknameMaxBytes = 64
+    static let geohashMaxLength = 12
+    /// Posts may live at most 7 days past their creation timestamp.
+    static let maxLifetimeMs: UInt64 = 7 * 24 * 60 * 60 * 1000
+    static let postSigningContext = "bitchat-board-v1"
+    static let tombstoneSigningContext = "bitchat-board-del-v1"
+    static let geohashAlphabet = Set("0123456789bcdefghjkmnpqrstuvwxyz")
+}
+
+private enum BoardTLVType: UInt8 {
+    case kind = 0x01
+    case postID = 0x02
+    case geohash = 0x03
+    case content = 0x04
+    case authorSigningKey = 0x05
+    case authorNickname = 0x06
+    case createdAt = 0x07
+    case expiresAt = 0x08
+    case flags = 0x09
+    case signature = 0x0A
+    case deletedAt = 0x0B
+}
+
+private enum BoardWireKind: UInt8 {
+    case post = 0x01
+    case tombstone = 0x02
+}
+
+/// A signed, persistent bulletin-board notice.
+struct BoardPostPacket: Equatable {
+    let postID: Data
+    /// Empty string scopes the post to the mesh-local board.
+    let geohash: String
+    let content: String
+    let authorSigningKey: Data
+    let authorNickname: String
+    let createdAt: UInt64
+    let expiresAt: UInt64
+    let flags: UInt8
+    let signature: Data
+
+    static let urgentFlag: UInt8 = 0x01
+
+    var isUrgent: Bool { flags & Self.urgentFlag != 0 }
+
+    /// Canonical bytes covered by the Ed25519 signature. Variable-length
+    /// fields are length-prefixed so no two field combinations can collide.
+    static func signingBytes(
+        postID: Data,
+        geohash: String,
+        content: String,
+        authorSigningKey: Data,
+        authorNickname: String,
+        createdAt: UInt64,
+        expiresAt: UInt64,
+        flags: UInt8
+    ) -> Data {
+        var out = Data()
+        BoardWireEncoding.appendContext(BoardWireConstants.postSigningContext, to: &out)
+        out.append(postID)
+        BoardWireEncoding.appendLengthPrefixed(Data(geohash.utf8), to: &out)
+        BoardWireEncoding.appendLengthPrefixed(Data(content.utf8), to: &out)
+        out.append(authorSigningKey)
+        BoardWireEncoding.appendLengthPrefixed(Data(authorNickname.utf8), to: &out)
+        BoardWireEncoding.appendUInt64(createdAt, to: &out)
+        BoardWireEncoding.appendUInt64(expiresAt, to: &out)
+        out.append(flags)
+        return out
+    }
+
+    var signingBytes: Data {
+        Self.signingBytes(
+            postID: postID,
+            geohash: geohash,
+            content: content,
+            authorSigningKey: authorSigningKey,
+            authorNickname: authorNickname,
+            createdAt: createdAt,
+            expiresAt: expiresAt,
+            flags: flags
+        )
+    }
+
+    func verifySignature() -> Bool {
+        BoardWireEncoding.verify(signature: signature, over: signingBytes, publicKey: authorSigningKey)
+    }
+}
+
+/// A signed deletion marker. Only the author's key can produce one; receivers
+/// keep it until the post's original expiry so the delete outruns the post.
+struct BoardTombstonePacket: Equatable {
+    let postID: Data
+    let authorSigningKey: Data
+    let deletedAt: UInt64
+    let signature: Data
+
+    static func signingBytes(postID: Data, deletedAt: UInt64) -> Data {
+        var out = Data()
+        BoardWireEncoding.appendContext(BoardWireConstants.tombstoneSigningContext, to: &out)
+        out.append(postID)
+        BoardWireEncoding.appendUInt64(deletedAt, to: &out)
+        return out
+    }
+
+    var signingBytes: Data {
+        Self.signingBytes(postID: postID, deletedAt: deletedAt)
+    }
+
+    func verifySignature() -> Bool {
+        BoardWireEncoding.verify(signature: signature, over: signingBytes, publicKey: authorSigningKey)
+    }
+}
+
+/// Decoded board payload: either a live post or a tombstone.
+enum BoardWire: Equatable {
+    case post(BoardPostPacket)
+    case tombstone(BoardTombstonePacket)
+
+    func encode() -> Data {
+        var out = Data()
+        func putTLV(_ t: BoardTLVType, _ v: Data) {
+            out.append(t.rawValue)
+            let len = UInt16(v.count)
+            out.append(UInt8((len >> 8) & 0xFF))
+            out.append(UInt8(len & 0xFF))
+            out.append(v)
+        }
+        switch self {
+        case .post(let post):
+            putTLV(.kind, Data([BoardWireKind.post.rawValue]))
+            putTLV(.postID, post.postID)
+            putTLV(.geohash, Data(post.geohash.utf8))
+            putTLV(.content, Data(post.content.utf8))
+            putTLV(.authorSigningKey, post.authorSigningKey)
+            putTLV(.authorNickname, Data(post.authorNickname.utf8))
+            putTLV(.createdAt, BoardWireEncoding.uint64Data(post.createdAt))
+            putTLV(.expiresAt, BoardWireEncoding.uint64Data(post.expiresAt))
+            putTLV(.flags, Data([post.flags]))
+            putTLV(.signature, post.signature)
+        case .tombstone(let tombstone):
+            putTLV(.kind, Data([BoardWireKind.tombstone.rawValue]))
+            putTLV(.postID, tombstone.postID)
+            putTLV(.authorSigningKey, tombstone.authorSigningKey)
+            putTLV(.deletedAt, BoardWireEncoding.uint64Data(tombstone.deletedAt))
+            putTLV(.signature, tombstone.signature)
+        }
+        return out
+    }
+
+    /// Structural decode; the caller must still verify the signature before
+    /// ingesting (`verifySignature()`).
+    static func decode(from data: Data) -> BoardWire? {
+        var off = data.startIndex
+        var kind: BoardWireKind?
+        var postID: Data?
+        var geohash: String?
+        var content: String?
+        var contentBytes = 0
+        var authorSigningKey: Data?
+        var authorNickname: String?
+        var nicknameBytes = 0
+        var createdAt: UInt64?
+        var expiresAt: UInt64?
+        var flags: UInt8?
+        var signature: Data?
+        var deletedAt: UInt64?
+
+        while off + 3 <= data.endIndex {
+            let t = data[off]; off += 1
+            let len = (Int(data[off]) << 8) | Int(data[off + 1]); off += 2
+            guard off + len <= data.endIndex else { return nil }
+            let v = data.subdata(in: off..<(off + len)); off += len
+            switch BoardTLVType(rawValue: t) {
+            case .kind:
+                guard v.count == 1 else { return nil }
+                kind = BoardWireKind(rawValue: v[v.startIndex])
+            case .postID:
+                guard v.count == BoardWireConstants.postIDLength else { return nil }
+                postID = v
+            case .geohash:
+                guard v.count <= BoardWireConstants.geohashMaxLength else { return nil }
+                geohash = String(data: v, encoding: .utf8)
+            case .content:
+                guard v.count <= BoardWireConstants.contentMaxBytes else { return nil }
+                contentBytes = v.count
+                content = String(data: v, encoding: .utf8)
+            case .authorSigningKey:
+                guard v.count == BoardWireConstants.signingKeyLength else { return nil }
+                authorSigningKey = v
+            case .authorNickname:
+                guard v.count <= BoardWireConstants.nicknameMaxBytes else { return nil }
+                nicknameBytes = v.count
+                authorNickname = String(data: v, encoding: .utf8)
+            case .createdAt:
+                createdAt = BoardWireEncoding.uint64(from: v)
+            case .expiresAt:
+                expiresAt = BoardWireEncoding.uint64(from: v)
+            case .flags:
+                guard v.count == 1 else { return nil }
+                flags = v[v.startIndex]
+            case .signature:
+                guard v.count == BoardWireConstants.signatureLength else { return nil }
+                signature = v
+            case .deletedAt:
+                deletedAt = BoardWireEncoding.uint64(from: v)
+            case nil:
+                continue // forward compatible; ignore unknown TLVs
+            }
+        }
+
+        guard let postID, let authorSigningKey, let signature else { return nil }
+
+        switch kind {
+        case .post:
+            guard let geohash, let content, let authorNickname,
+                  let createdAt, let expiresAt, let flags,
+                  contentBytes >= 1,
+                  nicknameBytes <= BoardWireConstants.nicknameMaxBytes,
+                  isValidGeohashField(geohash),
+                  expiresAt > createdAt,
+                  expiresAt - createdAt <= BoardWireConstants.maxLifetimeMs else {
+                return nil
+            }
+            return .post(BoardPostPacket(
+                postID: postID,
+                geohash: geohash,
+                content: content,
+                authorSigningKey: authorSigningKey,
+                authorNickname: authorNickname,
+                createdAt: createdAt,
+                expiresAt: expiresAt,
+                flags: flags,
+                signature: signature
+            ))
+        case .tombstone:
+            guard let deletedAt else { return nil }
+            return .tombstone(BoardTombstonePacket(
+                postID: postID,
+                authorSigningKey: authorSigningKey,
+                deletedAt: deletedAt,
+                signature: signature
+            ))
+        case nil:
+            return nil
+        }
+    }
+
+    func verifySignature() -> Bool {
+        switch self {
+        case .post(let post): return post.verifySignature()
+        case .tombstone(let tombstone): return tombstone.verifySignature()
+        }
+    }
+
+    /// Cheap TLV peek for relay policy: is this payload an urgent post?
+    /// Avoids a full decode on the hot relay path.
+    static func urgentFlag(in data: Data) -> Bool {
+        var off = data.startIndex
+        while off + 3 <= data.endIndex {
+            let t = data[off]; off += 1
+            let len = (Int(data[off]) << 8) | Int(data[off + 1]); off += 2
+            guard off + len <= data.endIndex else { return false }
+            if t == BoardTLVType.flags.rawValue, len == 1 {
+                return data[off] & BoardPostPacket.urgentFlag != 0
+            }
+            off += len
+        }
+        return false
+    }
+
+    /// Empty geohash = mesh-local board; otherwise 1-12 chars of the geohash
+    /// base32 alphabet.
+    private static func isValidGeohashField(_ geohash: String) -> Bool {
+        geohash.isEmpty || geohash.allSatisfy { BoardWireConstants.geohashAlphabet.contains($0) }
+    }
+}
+
+enum BoardWireEncoding {
+    static func appendContext(_ context: String, to out: inout Data) {
+        let bytes = Data(context.utf8)
+        out.append(UInt8(min(bytes.count, 255)))
+        out.append(bytes.prefix(255))
+    }
+
+    static func appendLengthPrefixed(_ value: Data, to out: inout Data) {
+        let len = UInt16(min(value.count, Int(UInt16.max)))
+        out.append(UInt8((len >> 8) & 0xFF))
+        out.append(UInt8(len & 0xFF))
+        out.append(value.prefix(Int(UInt16.max)))
+    }
+
+    static func appendUInt64(_ value: UInt64, to out: inout Data) {
+        var be = value.bigEndian
+        withUnsafeBytes(of: &be) { out.append(contentsOf: $0) }
+    }
+
+    static func uint64Data(_ value: UInt64) -> Data {
+        var out = Data()
+        appendUInt64(value, to: &out)
+        return out
+    }
+
+    static func uint64(from data: Data) -> UInt64? {
+        guard data.count == 8 else { return nil }
+        var value: UInt64 = 0
+        for byte in data { value = (value << 8) | UInt64(byte) }
+        return value
+    }
+
+    static func verify(signature: Data, over message: Data, publicKey: Data) -> Bool {
+        guard let key = try? Curve25519.Signing.PublicKey(rawRepresentation: publicKey) else {
+            return false
+        }
+        return key.isValidSignature(signature, for: message)
+    }
+}

bitchat/Protocols/Geohash.swift

@@ -10,11 +10,11 @@ enum Geohash {
         return map
     }()
 
-    /// Validates a geohash string for building-level precision (8 characters).
+    /// Validates a geohash string at any channel precision (1-12 characters).
     /// - Parameter geohash: The geohash string to validate
-    /// - Returns: true if valid 8-character base32 geohash, false otherwise
+    /// - Returns: true if a non-empty base32 geohash of at most 12 characters
-    static func isValidBuildingGeohash(_ geohash: String) -> Bool {
+    static func isValidGeohash(_ geohash: String) -> Bool {
-        guard geohash.count == 8 else { return false }
+        guard (1...12).contains(geohash.count) else { return false }
         return geohash.lowercased().allSatisfy { base32Map[$0] != nil }
     }
 

bitchat/Protocols/MeshMessageIdentity.swift

@@ -0,0 +1,32 @@
+//
+// MeshMessageIdentity.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import BitFoundation
+import Foundation
+
+/// Content-derived identity for public mesh messages.
+///
+/// The BLE wire carries no message ID for public broadcasts, so every device
+/// recomputes the same stable ID from the signed wire fields (sender ID,
+/// millisecond timestamp, content). That gives the mesh bridge a
+/// cross-device-consistent radio identity with zero wire change. Bridge events
+/// carry this value only as a hint for detecting a radio copy that is already
+/// present: sender/timestamp/content are public, so a different Nostr signer
+/// can copy them and must never be allowed to reserve the genuine event's
+/// authenticated dedup slot.
+enum MeshMessageIdentity {
+    /// Matches the wire truncation in `BLEService.sendMessage`.
+    static func millisecondTimestamp(_ date: Date) -> UInt64 {
+        UInt64(date.timeIntervalSince1970 * 1000)
+    }
+
+    static func stableID(senderIDHex: String, timestampMs: UInt64, content: String) -> String {
+        let input = senderIDHex.lowercased() + "|" + String(timestampMs) + "|" + content.trimmed
+        return String(Data(input.utf8).sha256Hex().prefix(32))
+    }
+}

bitchat/Protocols/NostrCarrierPacket.swift

@@ -0,0 +1,144 @@
+//
+// NostrCarrierPacket.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import BitFoundation
+import Foundation
+
+/// Wire payload for `MessageType.nostrCarrier` (0x28): a complete, signed
+/// Nostr event ferried over the mesh between a mesh-only peer and an
+/// internet gateway peer.
+///
+/// - `toGateway` rides a DIRECTED packet (recipientID = the gateway peer):
+///   a mesh-only sender asks the gateway to publish its locally signed
+///   geohash event to Nostr relays.
+/// - `fromGateway` rides a BROADCAST packet (default TTL): the gateway
+///   rebroadcasts inbound relay events so mesh-only peers see the channel.
+///
+/// The carried event is public geohash chat — already plaintext on Nostr —
+/// so the carrier adds no encryption. It IS signed by the originator's
+/// per-geohash identity, so neither the gateway nor any mesh relay can forge
+/// or alter it undetected: gateways and receivers verify the Schnorr
+/// signature before acting on it.
+///
+/// TLV encoding with 2-byte big-endian lengths (the event JSON exceeds the
+/// 1-byte TLV range used by smaller packets). Unknown TLV types are skipped
+/// for forward compatibility.
+struct NostrCarrierPacket: Equatable {
+    enum Direction: UInt8 {
+        case toGateway = 0x01
+        case fromGateway = 0x02
+        /// Mesh-bridge uplink: a mesh-only peer asks a bridge gateway to
+        /// publish its signed rendezvous event. Directed, like `toGateway`.
+        case toBridge = 0x03
+        /// Mesh-bridge downlink: a bridge gateway rebroadcasts a rendezvous
+        /// event from a remote island. Broadcast, like `fromGateway`.
+        /// Old clients fail the Direction decode on 0x03/0x04 and drop the
+        /// carrier quietly — bridge traffic degrades to invisible, not junk.
+        case fromBridge = 0x04
+    }
+
+    let direction: Direction
+    let geohash: String
+    /// Complete signed Nostr event JSON (id, pubkey, created_at, kind, tags,
+    /// content, sig).
+    let eventJSON: Data
+
+    /// BLE airtime cap for a carried event.
+    static let maxEventJSONBytes = 16 * 1024
+    static let maxGeohashLength = 12
+
+    private enum TLVType: UInt8 {
+        case direction = 0x01
+        case geohash = 0x02
+        case eventJSON = 0x03
+    }
+
+    init?(direction: Direction, geohash: String, eventJSON: Data) {
+        let geohashBytes = Data(geohash.utf8)
+        guard !geohashBytes.isEmpty,
+              geohashBytes.count <= Self.maxGeohashLength,
+              !eventJSON.isEmpty,
+              eventJSON.count <= Self.maxEventJSONBytes else {
+            return nil
+        }
+        self.direction = direction
+        self.geohash = geohash
+        self.eventJSON = eventJSON
+    }
+
+    init?(direction: Direction, geohash: String, event: NostrEvent) {
+        guard let json = try? event.jsonString(), !json.isEmpty else { return nil }
+        self.init(direction: direction, geohash: geohash, eventJSON: Data(json.utf8))
+    }
+
+    /// Decodes the carried event. Callers MUST still verify
+    /// `event.isValidSignature()` before publishing or displaying it.
+    func event() -> NostrEvent? {
+        guard let dict = try? JSONSerialization.jsonObject(with: eventJSON) as? [String: Any] else {
+            return nil
+        }
+        return try? NostrEvent(from: dict)
+    }
+
+    func encode() -> Data? {
+        var data = Data()
+        data.reserveCapacity(eventJSON.count + geohash.utf8.count + 12)
+
+        func appendTLV(_ type: TLVType, _ value: Data) {
+            data.append(type.rawValue)
+            data.append(UInt8((value.count >> 8) & 0xFF))
+            data.append(UInt8(value.count & 0xFF))
+            data.append(value)
+        }
+
+        appendTLV(.direction, Data([direction.rawValue]))
+        appendTLV(.geohash, Data(geohash.utf8))
+        appendTLV(.eventJSON, eventJSON)
+        return data
+    }
+
+    static func decode(_ data: Data) -> NostrCarrierPacket? {
+        // Defensive slice re-base (Data slices keep parent indices).
+        let data = Data(data)
+        var offset = 0
+        var direction: Direction?
+        var geohash: String?
+        var eventJSON: Data?
+
+        while offset + 3 <= data.count {
+            let typeRaw = data[offset]
+            let length = (Int(data[offset + 1]) << 8) | Int(data[offset + 2])
+            offset += 3
+            guard offset + length <= data.count else { return nil }
+            let value = data.subdata(in: offset..<offset + length)
+            offset += length
+
+            switch TLVType(rawValue: typeRaw) {
+            case .direction:
+                guard value.count == 1, let parsed = Direction(rawValue: value[0]) else { return nil }
+                direction = parsed
+            case .geohash:
+                guard let parsed = String(data: value, encoding: .utf8) else { return nil }
+                geohash = parsed
+            case .eventJSON:
+                eventJSON = value
+            case nil:
+                // Unknown TLV; skip (tolerant decoder for forward compatibility).
+                continue
+            }
+        }
+
+        guard offset == data.count,
+              let direction,
+              let geohash,
+              let eventJSON else {
+            return nil
+        }
+        return NostrCarrierPacket(direction: direction, geohash: geohash, eventJSON: eventJSON)
+    }
+}

bitchat/Protocols/Packets.swift

@@ -1,3 +1,4 @@
+import BitFoundation
 import Foundation
 
 // MARK: - Protocol TLV Packets
@@ -7,12 +8,35 @@ struct AnnouncementPacket {
     let noisePublicKey: Data            // Noise static public key (Curve25519.KeyAgreement)
     let signingPublicKey: Data          // Ed25519 public key for signing
     let directNeighbors: [Data]?        // 8-byte peer IDs
+    let capabilities: PeerCapabilities? // advertised feature bits; nil when absent (old clients)
+    /// Rendezvous geohash cell this peer bridges, when advertising `.bridge`.
+    /// Coarse (cell-level) by design; lets mesh-only peers compose correctly
+    /// tagged rendezvous events without their own location fix.
+    let bridgeGeohash: String?
+
+    init(
+        nickname: String,
+        noisePublicKey: Data,
+        signingPublicKey: Data,
+        directNeighbors: [Data]?,
+        capabilities: PeerCapabilities? = nil,
+        bridgeGeohash: String? = nil
+    ) {
+        self.nickname = nickname
+        self.noisePublicKey = noisePublicKey
+        self.signingPublicKey = signingPublicKey
+        self.directNeighbors = directNeighbors
+        self.capabilities = capabilities
+        self.bridgeGeohash = bridgeGeohash
+    }
 
     private enum TLVType: UInt8 {
         case nickname = 0x01
         case noisePublicKey = 0x02
         case signingPublicKey = 0x03
         case directNeighbors = 0x04
+        case capabilities = 0x05
+        case bridgeGeohash = 0x06
     }
 
     func encode() -> Data? {
@@ -48,6 +72,24 @@ struct AnnouncementPacket {
             }
         }
 
+        // TLV for capabilities (optional)
+        if let capabilities = capabilities {
+            let capabilityBytes = capabilities.encoded()
+            guard capabilityBytes.count <= 255 else { return nil }
+            data.append(TLVType.capabilities.rawValue)
+            data.append(UInt8(capabilityBytes.count))
+            data.append(capabilityBytes)
+        }
+
+        // TLV for bridge rendezvous cell (optional; old clients skip it)
+        if let bridgeGeohash = bridgeGeohash,
+           let cellData = bridgeGeohash.data(using: .utf8),
+           !cellData.isEmpty, cellData.count <= 12 {
+            data.append(TLVType.bridgeGeohash.rawValue)
+            data.append(UInt8(cellData.count))
+            data.append(cellData)
+        }
+
         return data
     }
 
@@ -57,6 +99,8 @@ struct AnnouncementPacket {
         var noisePublicKey: Data?
         var signingPublicKey: Data?
         var directNeighbors: [Data]?
+        var capabilities: PeerCapabilities?
+        var bridgeGeohash: String?
 
         while offset + 2 <= data.count {
             let typeRaw = data[offset]
@@ -87,6 +131,12 @@ struct AnnouncementPacket {
                         }
                         directNeighbors = neighbors
                     }
+                case .capabilities:
+                    capabilities = PeerCapabilities(encoded: Data(value))
+                case .bridgeGeohash:
+                    if length <= 12 {
+                        bridgeGeohash = String(data: value, encoding: .utf8)
+                    }
                 }
             } else {
                 // Unknown TLV; skip (tolerant decoder for forward compatibility)
@@ -99,7 +149,9 @@ struct AnnouncementPacket {
             nickname: nickname,
             noisePublicKey: noisePublicKey,
             signingPublicKey: signingPublicKey,
-            directNeighbors: directNeighbors
+            directNeighbors: directNeighbors,
+            capabilities: capabilities,
+            bridgeGeohash: bridgeGeohash
         )
     }
 }

bitchat/Protocols/PeerCapabilities+Local.swift

@@ -0,0 +1,7 @@
+import BitFoundation
+
+extension PeerCapabilities {
+    /// Capabilities this build advertises in its announce packets.
+    /// Each feature adds its bit here when it ships.
+    static let localSupported: PeerCapabilities = [.vouch, .prekeys, .groups]
+}

bitchat/Protocols/VoiceBurstPacket.swift

@@ -0,0 +1,220 @@
+//
+// VoiceBurstPacket.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import Foundation
+import Security
+
+/// Audio codec of a live voice burst. START packets carry it so receivers can
+/// reject bursts they can't decode instead of feeding garbage to the decoder.
+enum VoiceBurstCodec: UInt8 {
+    /// AAC-LC, 16 kHz, mono, ~16 kbps — matches the voice-note recorder, so
+    /// the finalized `.m4a` and the live frames come from the same encoder
+    /// settings.
+    case aacLC16kMono = 0x01
+}
+
+/// One packet of a live push-to-talk voice burst (the inner payload of
+/// `NoisePayloadType.voiceFrame`, and — for public mesh bursts — the payload
+/// of `MessageType.voiceFrame`).
+///
+/// Wire format:
+/// ```
+/// [burstID: 8][seq: UInt16 BE][flags: UInt8][payload…]
+/// ```
+/// - flags 0x01 (START): payload = [codec: UInt8]
+/// - flags 0x02 (END):   payload = [totalDataPackets: UInt16 BE][durationMs: UInt32 BE]
+/// - flags 0x04 (CANCELED): empty payload; receivers discard the burst
+/// - flags 0x00 (data):  payload = repeated [length: UInt16 BE][AAC frame]
+struct VoiceBurstPacket: Equatable {
+    enum Kind: Equatable {
+        case start(codec: VoiceBurstCodec)
+        case frames([Data])
+        case end(totalDataPackets: UInt16, durationMs: UInt32)
+        case canceled
+    }
+
+    static let burstIDSize = 8
+    private static let headerSize = burstIDSize + 2 + 1
+    /// Sanity cap on frames per packet; real packets carry 1-2 frames.
+    static let maxFramesPerPacket = 8
+
+    private enum Flags {
+        static let start: UInt8 = 0x01
+        static let end: UInt8 = 0x02
+        static let canceled: UInt8 = 0x04
+    }
+
+    let burstID: Data
+    let seq: UInt16
+    let kind: Kind
+
+    init?(burstID: Data, seq: UInt16, kind: Kind) {
+        guard burstID.count == Self.burstIDSize else { return nil }
+        if case .frames(let frames) = kind {
+            guard !frames.isEmpty,
+                  frames.count <= Self.maxFramesPerPacket,
+                  frames.allSatisfy({ !$0.isEmpty && $0.count <= Int(UInt16.max) })
+            else { return nil }
+        }
+        self.burstID = burstID
+        self.seq = seq
+        self.kind = kind
+    }
+
+    func encode() -> Data {
+        var data = Data(capacity: Self.headerSize + payloadSize)
+        data.append(burstID)
+        data.append(UInt8((seq >> 8) & 0xFF))
+        data.append(UInt8(seq & 0xFF))
+        switch kind {
+        case .start(let codec):
+            data.append(Flags.start)
+            data.append(codec.rawValue)
+        case .frames(let frames):
+            data.append(0)
+            for frame in frames {
+                let length = UInt16(frame.count)
+                data.append(UInt8((length >> 8) & 0xFF))
+                data.append(UInt8(length & 0xFF))
+                data.append(frame)
+            }
+        case .end(let totalDataPackets, let durationMs):
+            data.append(Flags.end)
+            data.append(UInt8((totalDataPackets >> 8) & 0xFF))
+            data.append(UInt8(totalDataPackets & 0xFF))
+            for shift in stride(from: 24, through: 0, by: -8) {
+                data.append(UInt8((durationMs >> UInt32(shift)) & 0xFF))
+            }
+        case .canceled:
+            data.append(Flags.canceled)
+        }
+        return data
+    }
+
+    static func decode(_ data: Data) -> VoiceBurstPacket? {
+        // Work on a re-based copy so subscripting is offset-safe.
+        let data = Data(data)
+        guard data.count >= headerSize else { return nil }
+
+        let burstID = data.prefix(burstIDSize)
+        let seq = (UInt16(data[burstIDSize]) << 8) | UInt16(data[burstIDSize + 1])
+        let flags = data[burstIDSize + 2]
+        let payload = data.dropFirst(headerSize)
+
+        let kind: Kind
+        switch flags {
+        case Flags.start:
+            guard let codecByte = payload.first,
+                  let codec = VoiceBurstCodec(rawValue: codecByte)
+            else { return nil }
+            kind = .start(codec: codec)
+        case Flags.end:
+            guard payload.count >= 6 else { return nil }
+            let bytes = Array(payload)
+            let total = (UInt16(bytes[0]) << 8) | UInt16(bytes[1])
+            let duration = bytes[2...5].reduce(UInt32(0)) { ($0 << 8) | UInt32($1) }
+            kind = .end(totalDataPackets: total, durationMs: duration)
+        case Flags.canceled:
+            kind = .canceled
+        case 0:
+            var frames: [Data] = []
+            var offset = payload.startIndex
+            while offset < payload.endIndex {
+                guard payload.distance(from: offset, to: payload.endIndex) >= 2 else { return nil }
+                let length = (Int(payload[offset]) << 8) | Int(payload[payload.index(after: offset)])
+                offset = payload.index(offset, offsetBy: 2)
+                guard length > 0,
+                      payload.distance(from: offset, to: payload.endIndex) >= length,
+                      frames.count < maxFramesPerPacket
+                else { return nil }
+                let end = payload.index(offset, offsetBy: length)
+                frames.append(Data(payload[offset..<end]))
+                offset = end
+            }
+            guard !frames.isEmpty else { return nil }
+            kind = .frames(frames)
+        default:
+            return nil
+        }
+
+        return VoiceBurstPacket(burstID: Data(burstID), seq: seq, kind: kind)
+    }
+
+    static func makeBurstID() -> Data {
+        var bytes = Data(count: burstIDSize)
+        let result = bytes.withUnsafeMutableBytes {
+            SecRandomCopyBytes(kSecRandomDefault, burstIDSize, $0.baseAddress!)
+        }
+        guard result == errSecSuccess else {
+            return Data((0..<burstIDSize).map { _ in UInt8.random(in: .min ... .max) })
+        }
+        return bytes
+    }
+
+    private var payloadSize: Int {
+        switch kind {
+        case .start: return 1
+        case .frames(let frames): return frames.reduce(0) { $0 + 2 + $1.count }
+        case .end: return 6
+        case .canceled: return 0
+        }
+    }
+}
+
+/// Greedy packetizer for outgoing bursts: batches encoded frames into
+/// `VoiceBurstPacket`s without exceeding the byte budget that keeps each
+/// packet in a single BLE frame after Noise encryption and padding.
+/// Not thread-safe — confine to one queue.
+struct VoiceBurstPacketizer {
+    let burstID: Data
+    private let budget: Int
+    private var pendingFrames: [Data] = []
+    private var pendingSize = 0
+    /// seq 0 is reserved for START; data packets start at 1.
+    private(set) var nextSeq: UInt16 = 1
+    private(set) var dataPacketCount: UInt16 = 0
+
+    init(burstID: Data, budget: Int = TransportConfig.pttMaxBurstContentBytes) {
+        self.burstID = burstID
+        self.budget = budget
+    }
+
+    /// Adds one encoded frame, returning any packets that became full.
+    /// Frames larger than the budget are dropped (the encoder's ~130-byte
+    /// frames never hit this; it guards against misconfiguration looping).
+    mutating func add(_ frame: Data) -> [Data] {
+        let frameCost = 2 + frame.count
+        guard VoiceBurstPacket.burstIDSize + 3 + frameCost <= budget else { return [] }
+
+        var packets: [Data] = []
+        if !pendingFrames.isEmpty,
+           VoiceBurstPacket.burstIDSize + 3 + pendingSize + frameCost > budget
+            || pendingFrames.count >= VoiceBurstPacket.maxFramesPerPacket {
+            packets.append(contentsOf: flush())
+        }
+        pendingFrames.append(frame)
+        pendingSize += frameCost
+        return packets
+    }
+
+    /// Emits any buffered frames as a final data packet.
+    mutating func flush() -> [Data] {
+        guard !pendingFrames.isEmpty,
+              let packet = VoiceBurstPacket(burstID: burstID, seq: nextSeq, kind: .frames(pendingFrames))
+        else {
+            pendingFrames = []
+            pendingSize = 0
+            return []
+        }
+        pendingFrames = []
+        pendingSize = 0
+        nextSeq &+= 1
+        dataPacketCount &+= 1
+        return [packet.encode()]
+    }
+}

bitchat/Protocols/VouchAttestation.swift

@@ -0,0 +1,225 @@
+//
+// VouchAttestation.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import CryptoKit
+import Foundation
+
+/// A signed statement that the *sender of the enclosing Noise payload* has
+/// verified the identity described here ("transitive verification").
+///
+/// The voucher's identity is deliberately implicit: attestations only travel
+/// inside an authenticated Noise session (`NoisePayloadType.vouch`), so the
+/// receiver verifies the Ed25519 signature against the session peer's
+/// announce-bound signing key and stores the vouch keyed by that peer's
+/// fingerprint. Nothing in the attestation names the voucher, so a captured
+/// attestation cannot be replayed by a third party whose signing key doesn't
+/// match.
+///
+/// Wire format — single attestation (TLV, 1-byte type + 1-byte length):
+/// - `0x01` voucheeFingerprint: 32 bytes, SHA-256 of the vouchee's Noise static key
+/// - `0x02` voucheeSigningKey: 32 bytes, Ed25519; anchors the vouch to a concrete identity
+/// - `0x03` timestamp: 8 bytes big-endian, milliseconds since 1970
+/// - `0x04` signature: 64 bytes, Ed25519 by the VOUCHER's signing key over
+///   `"bitchat-vouch-v1" | voucheeFingerprint | voucheeSigningKey | timestamp`
+///
+/// Unknown TLV types are skipped for forward compatibility.
+///
+/// Batch format (the `vouch` Noise payload body):
+/// `[count: UInt8]` then per attestation `[length: UInt16 BE][attestation TLV]`.
+struct VouchAttestation: Equatable {
+    static let signingContext = "bitchat-vouch-v1"
+    /// Receiver-side expiry for attestations.
+    static let maxAge: TimeInterval = 30 * 24 * 60 * 60
+    /// Tolerated clock skew for attestations timestamped in the future.
+    static let maxClockSkew: TimeInterval = 60 * 60
+    /// Upper bound of attestations carried/accepted in one batch payload.
+    static let maxBatchCount = 16
+
+    static let fingerprintSize = 32
+    static let signingKeySize = 32
+    static let signatureSize = 64
+
+    let voucheeFingerprint: Data  // 32 bytes
+    let voucheeSigningKey: Data   // 32 bytes
+    let timestampMs: UInt64
+    let signature: Data           // 64 bytes
+
+    private enum TLVType: UInt8 {
+        case voucheeFingerprint = 0x01
+        case voucheeSigningKey = 0x02
+        case timestamp = 0x03
+        case signature = 0x04
+    }
+
+    var voucheeFingerprintHex: String { voucheeFingerprint.hexEncodedString() }
+
+    var timestamp: Date { Date(timeIntervalSince1970: TimeInterval(timestampMs) / 1000) }
+
+    /// The exact bytes the voucher signs.
+    static func signableBytes(
+        voucheeFingerprint: Data,
+        voucheeSigningKey: Data,
+        timestampMs: UInt64
+    ) -> Data {
+        var message = Data(signingContext.utf8)
+        message.append(voucheeFingerprint)
+        message.append(voucheeSigningKey)
+        var timestampBE = timestampMs.bigEndian
+        withUnsafeBytes(of: &timestampBE) { message.append(contentsOf: $0) }
+        return message
+    }
+
+    var signableBytes: Data {
+        Self.signableBytes(
+            voucheeFingerprint: voucheeFingerprint,
+            voucheeSigningKey: voucheeSigningKey,
+            timestampMs: timestampMs
+        )
+    }
+
+    /// Builds and signs an attestation. `sign` is the voucher's Ed25519
+    /// signing primitive (e.g. `Transport.noiseSignData`).
+    static func build(
+        voucheeFingerprint: Data,
+        voucheeSigningKey: Data,
+        timestampMs: UInt64 = UInt64(Date().timeIntervalSince1970 * 1000),
+        sign: (Data) -> Data?
+    ) -> VouchAttestation? {
+        guard voucheeFingerprint.count == fingerprintSize,
+              voucheeSigningKey.count == signingKeySize else { return nil }
+        let message = signableBytes(
+            voucheeFingerprint: voucheeFingerprint,
+            voucheeSigningKey: voucheeSigningKey,
+            timestampMs: timestampMs
+        )
+        guard let signature = sign(message), signature.count == signatureSize else { return nil }
+        return VouchAttestation(
+            voucheeFingerprint: voucheeFingerprint,
+            voucheeSigningKey: voucheeSigningKey,
+            timestampMs: timestampMs,
+            signature: signature
+        )
+    }
+
+    /// Verifies the Ed25519 signature against the voucher's announce-bound
+    /// signing key.
+    func verifySignature(voucherSigningKey: Data) -> Bool {
+        guard let publicKey = try? Curve25519.Signing.PublicKey(rawRepresentation: voucherSigningKey) else {
+            return false
+        }
+        return publicKey.isValidSignature(signature, for: signableBytes)
+    }
+
+    /// Whether the attestation is outside its validity window (older than
+    /// `maxAge`, or timestamped implausibly far in the future).
+    func isExpired(now: Date = Date()) -> Bool {
+        let age = now.timeIntervalSince(timestamp)
+        return age > Self.maxAge || age < -Self.maxClockSkew
+    }
+
+    // MARK: - Encoding
+
+    func encode() -> Data? {
+        guard voucheeFingerprint.count == Self.fingerprintSize,
+              voucheeSigningKey.count == Self.signingKeySize,
+              signature.count == Self.signatureSize else { return nil }
+        var data = Data()
+        func appendTLV(_ type: TLVType, _ value: Data) {
+            data.append(type.rawValue)
+            data.append(UInt8(value.count))
+            data.append(value)
+        }
+        appendTLV(.voucheeFingerprint, voucheeFingerprint)
+        appendTLV(.voucheeSigningKey, voucheeSigningKey)
+        var timestampBE = timestampMs.bigEndian
+        appendTLV(.timestamp, withUnsafeBytes(of: &timestampBE) { Data($0) })
+        appendTLV(.signature, signature)
+        return data
+    }
+
+    static func decode(from data: Data) -> VouchAttestation? {
+        var fingerprint: Data?
+        var signingKey: Data?
+        var timestampMs: UInt64?
+        var signature: Data?
+
+        var offset = data.startIndex
+        while offset < data.endIndex {
+            guard data.index(offset, offsetBy: 2, limitedBy: data.endIndex) != nil,
+                  offset + 1 < data.endIndex else { return nil }
+            let type = data[offset]
+            let length = Int(data[offset + 1])
+            let valueStart = offset + 2
+            guard let valueEnd = data.index(valueStart, offsetBy: length, limitedBy: data.endIndex) else {
+                return nil
+            }
+            let value = Data(data[valueStart..<valueEnd])
+            switch TLVType(rawValue: type) {
+            case .voucheeFingerprint:
+                guard value.count == fingerprintSize else { return nil }
+                fingerprint = value
+            case .voucheeSigningKey:
+                guard value.count == signingKeySize else { return nil }
+                signingKey = value
+            case .timestamp:
+                guard value.count == 8 else { return nil }
+                timestampMs = value.reduce(UInt64(0)) { ($0 << 8) | UInt64($1) }
+            case .signature:
+                guard value.count == signatureSize else { return nil }
+                signature = value
+            case nil:
+                break // Unknown TLV: skip for forward compatibility.
+            }
+            offset = valueEnd
+        }
+
+        guard let fingerprint, let signingKey, let timestampMs, let signature else { return nil }
+        return VouchAttestation(
+            voucheeFingerprint: fingerprint,
+            voucheeSigningKey: signingKey,
+            timestampMs: timestampMs,
+            signature: signature
+        )
+    }
+
+    // MARK: - Batch encoding
+
+    /// Encodes up to `maxBatchCount` attestations into one payload body.
+    static func encodeList(_ attestations: [VouchAttestation]) -> Data? {
+        guard !attestations.isEmpty, attestations.count <= maxBatchCount else { return nil }
+        var data = Data()
+        data.append(UInt8(attestations.count))
+        for attestation in attestations {
+            guard let encoded = attestation.encode(), encoded.count <= Int(UInt16.max) else { return nil }
+            var lengthBE = UInt16(encoded.count).bigEndian
+            withUnsafeBytes(of: &lengthBE) { data.append(contentsOf: $0) }
+            data.append(encoded)
+        }
+        return data
+    }
+
+    /// Decodes a batch payload, dropping malformed entries and ignoring
+    /// anything beyond `maxBatchCount` (sender-declared count is not trusted).
+    static func decodeList(from data: Data) -> [VouchAttestation] {
+        guard data.count > 1 else { return [] }
+        let declaredCount = Int(data[data.startIndex])
+        let limit = min(declaredCount, maxBatchCount)
+        var attestations: [VouchAttestation] = []
+        var offset = data.startIndex + 1
+        while attestations.count < limit, offset < data.endIndex {
+            guard let lengthEnd = data.index(offset, offsetBy: 2, limitedBy: data.endIndex) else { break }
+            let length = Int(data[offset]) << 8 | Int(data[offset + 1])
+            guard let entryEnd = data.index(lengthEnd, offsetBy: length, limitedBy: data.endIndex) else { break }
+            if let attestation = decode(from: Data(data[lengthEnd..<entryEnd])) {
+                attestations.append(attestation)
+            }
+            offset = entryEnd
+        }
+        return attestations
+    }
+}

bitchat/Services/AutocompleteService.swift

@@ -11,13 +11,6 @@ import Foundation
 /// Manages autocomplete functionality for chat
 final class AutocompleteService {
     private let mentionRegex = try? NSRegularExpression(pattern: "@([\\p{L}0-9_]*)$", options: [])
-    private let commandRegex = try? NSRegularExpression(pattern: "^/([a-z]*)$", options: [])
-    
-    private let commands = [
-        "/msg", "/who", "/clear",
-        "/hug", "/slap", "/fav", "/unfav",
-        "/block", "/unblock"
-    ]
 
     /// Get autocomplete suggestions for current text
     func getSuggestions(for text: String, peers: [String], cursorPosition: Int) -> (suggestions: [String], range: NSRange?) {
@@ -73,26 +66,6 @@ final class AutocompleteService {
         return suggestions.isEmpty ? nil : (Array(suggestions), fullRange)
     }
     
-    private func getCommandSuggestions(_ text: String) -> ([String], NSRange)? {
-        guard let regex = commandRegex else { return nil }
-        
-        let nsText = text as NSString
-        let matches = regex.matches(in: text, options: [], range: NSRange(location: 0, length: nsText.length))
-        
-        guard let match = matches.last else { return nil }
-        
-        let fullRange = match.range(at: 0)
-        let captureRange = match.range(at: 1)
-        let prefix = nsText.substring(with: captureRange).lowercased()
-        
-        let suggestions = commands
-            .filter { $0.hasPrefix("/\(prefix)") }
-            .sorted()
-            .prefix(5)
-        
-        return suggestions.isEmpty ? nil : (Array(suggestions), fullRange)
-    }
-    
     private func needsArgument(command: String) -> Bool {
         switch command {
         case "/who", "/clear":

bitchat/Services/BLE/BLEAnnounceHandler.swift

@@ -0,0 +1,254 @@
+import BitFoundation
+import BitLogger
+import Foundation
+
+/// Narrow environment for `BLEAnnounceHandler`.
+///
+/// All queue hops (collections barrier, BLE-queue link-state reads, main-actor
+/// UI notification, delayed re-announce) live inside the closures supplied by
+/// `BLEService`, keeping the handler queue-agnostic and synchronously testable.
+struct BLEAnnounceHandlerEnvironment {
+    /// Local peer identity at the time the announce is handled.
+    let localPeerID: () -> PeerID
+    /// TTL value used for direct (non-relayed) packets.
+    let messageTTL: UInt8
+    /// Current time source.
+    let now: () -> Date
+    /// Noise public key already recorded for the peer, if any (registry read).
+    let existingNoisePublicKey: (PeerID) -> Data?
+    /// Verifies the packet signature against the announced signing key.
+    let verifySignature: (_ packet: BitchatPacket, _ signingPublicKey: Data) -> Bool
+    /// Direct link state for the peer (BLE-queue read).
+    let linkState: (PeerID) -> (hasPeripheral: Bool, hasCentral: Bool)
+    /// Whether the link this packet arrived on is already bound to a
+    /// different peer ID (ingress-registry + BLE-queue read). Directness
+    /// rides on the unsigned TTL, so a replayed announce can look "direct"
+    /// on the replayer's link; that link must not shortcut an absent peer
+    /// into "connected".
+    let linkBoundToOtherPeer: (_ packet: BitchatPacket, _ peerID: PeerID) -> Bool
+    /// Runs the registry mutation phase under the collections barrier.
+    let withRegistryBarrier: (() -> Void) -> Void
+    /// Upserts the verified announce into the peer registry.
+    /// Must only be called from inside `withRegistryBarrier`.
+    let upsertVerifiedAnnounce: (
+        _ peerID: PeerID,
+        _ announcement: AnnouncementPacket,
+        _ isConnected: Bool,
+        _ now: Date
+    ) -> BLEPeerAnnounceUpdate
+    /// Debounced reconnect-log decision.
+    /// Must only be called from inside `withRegistryBarrier`.
+    let shouldEmitReconnectLog: (_ peerID: PeerID, _ now: Date) -> Bool
+    /// Records verified direct-neighbor claims in the mesh topology.
+    let updateTopology: (_ peerID: PeerID, _ neighbors: [Data]) -> Void
+    /// Persists the announced cryptographic identity for offline verification.
+    let persistIdentity: (AnnouncementPacket) -> Void
+    /// Announce-back dedup check.
+    let dedupContains: (String) -> Bool
+    /// Announce-back dedup marking.
+    let dedupMarkProcessed: (String) -> Void
+    /// Delivers the announce UI events as one ordered main-actor hop:
+    /// `.peerConnected` (if flagged) → initial gossip sync scheduling (if
+    /// flagged) → peer-ID snapshot + data publish + `.peerListUpdated`.
+    /// A single closure keeps the original in-order delivery guarantee that
+    /// separate unstructured tasks would not provide.
+    let deliverAnnounceUIEvents: (
+        _ peerID: PeerID,
+        _ notifyPeerConnected: Bool,
+        _ scheduleInitialSync: Bool
+    ) -> Void
+    /// Tracks the announce packet for gossip sync.
+    let trackPacketSeen: (BitchatPacket) -> Void
+    /// Reciprocates the announce for bidirectional discovery.
+    let sendAnnounceBack: () -> Void
+    /// Schedules a delayed re-announce (afterglow) after the given delay.
+    let scheduleAfterglow: (TimeInterval) -> Void
+}
+
+/// Outcome of an accepted announce, surfaced so the service can run
+/// follow-up work (e.g. courier handover) that keys off the announce.
+struct BLEAnnounceHandlingResult {
+    let peerID: PeerID
+    let announcement: AnnouncementPacket
+    let isDirectAnnounce: Bool
+    let isVerified: Bool
+}
+
+/// Orchestrates inbound announce packets: preflight validation, signature
+/// trust, registry/topology updates, identity persistence, UI notification,
+/// gossip tracking, and the reciprocal announce response.
+final class BLEAnnounceHandler {
+    private let environment: BLEAnnounceHandlerEnvironment
+
+    init(environment: BLEAnnounceHandlerEnvironment) {
+        self.environment = environment
+    }
+
+    @discardableResult
+    func handle(_ packet: BitchatPacket, from peerID: PeerID) -> BLEAnnounceHandlingResult? {
+        let env = environment
+        let now = env.now()
+        let preflight = BLEAnnouncePreflightPolicy.evaluate(
+            packet: packet,
+            from: peerID,
+            localPeerID: env.localPeerID(),
+            now: now
+        )
+
+        let announcement: AnnouncementPacket
+        switch preflight {
+        case .accept(let acceptance):
+            announcement = acceptance.announcement
+        case .reject(.malformed):
+            SecureLogger.error("❌ Failed to decode announce packet from \(peerID.id.prefix(8))…", category: .session)
+            return nil
+        case .reject(.senderMismatch(let derivedFromKey)):
+            SecureLogger.warning("⚠️ Announce sender mismatch: derived \(derivedFromKey.id.prefix(8))… vs packet \(peerID.id.prefix(8))…", category: .security)
+            return nil
+        case .reject(.selfAnnounce):
+            return nil
+        case .reject(.stale(let ageSeconds)):
+            SecureLogger.debug("⏰ Ignoring stale announce from \(peerID.id.prefix(8))… (age: \(ageSeconds)s)", category: .session)
+            return nil
+        }
+
+        // Suppress announce logs to reduce noise
+
+        // Precompute signature verification outside barrier to reduce contention
+        let existingNoisePublicKey = env.existingNoisePublicKey(peerID)
+        let hasSignature = packet.signature != nil
+        let signatureValid: Bool
+        if hasSignature {
+            signatureValid = env.verifySignature(packet, announcement.signingPublicKey)
+            if !signatureValid {
+                SecureLogger.warning("⚠️ Signature verification for announce failed \(peerID.id.prefix(8))", category: .security)
+            }
+        } else {
+            signatureValid = false
+        }
+        let trustDecision = BLEAnnounceTrustPolicy.evaluate(
+            hasSignature: hasSignature,
+            signatureValid: signatureValid,
+            existingNoisePublicKey: existingNoisePublicKey,
+            announcedNoisePublicKey: announcement.noisePublicKey
+        )
+        if case .reject(.keyMismatch) = trustDecision {
+            SecureLogger.warning("⚠️ Announce key mismatch for \(peerID.id.prefix(8))… — keeping unverified", category: .security)
+        }
+        let verifiedAnnounce = trustDecision.isVerified
+
+        var isNewPeer = false
+        var isReconnectedPeer = false
+        let directLinkState = env.linkState(peerID)
+        let isDirectAnnounce = packet.ttl == env.messageTTL
+        // A "direct" announce arriving on a link that another peer already
+        // owns is either a rotation heal or a replay with its TTL restored;
+        // both are ambiguous, so only the rebind (which containment-checks
+        // the claimed identity) may promote it — never this shortcut.
+        //
+        // Known limitation: denying the shortcut cannot prevent forged
+        // presence outright. A rebind that passes the containment checks
+        // promotes the claimed peer to connected — it must, or a legitimate
+        // rotation on an open link would read as disconnected — so a replay
+        // that wins the rebind (absent victim, cooldown clear) still forges
+        // presence. That residue is presence display only: DMs stay gated on
+        // canDeliverSecurely (no Noise session means retain + courier, see
+        // MessageRouter.sendPrivate). What this check buys: the ambiguous
+        // announce alone never flips presence — forging requires winning the
+        // containment-checked rebind (never steals an identity that owns a
+        // live link; at most one rebind per link per cooldown window).
+        let linkBoundToOtherPeer = isDirectAnnounce && env.linkBoundToOtherPeer(packet, peerID)
+
+        env.withRegistryBarrier {
+            let hasPeripheralConnection = directLinkState.hasPeripheral
+            let hasCentralSubscription = directLinkState.hasCentral
+
+            // Require verified announce; ignore otherwise (no backward compatibility)
+            if !verifiedAnnounce {
+                SecureLogger.warning("❌ Ignoring unverified announce from \(peerID.id.prefix(8))…", category: .security)
+                // Reset flags to prevent post-barrier code from acting on unverified announces
+                isNewPeer = false
+                isReconnectedPeer = false
+                return
+            }
+
+            let update = env.upsertVerifiedAnnounce(
+                peerID,
+                announcement,
+                hasPeripheralConnection || hasCentralSubscription || (isDirectAnnounce && !linkBoundToOtherPeer),
+                now
+            )
+            isNewPeer = update.isNewPeer
+            isReconnectedPeer = update.wasDisconnected
+
+            // Log connection status only for direct connectivity changes; debounce to reduce spam
+            if isDirectAnnounce || hasPeripheralConnection || hasCentralSubscription {
+                let now = env.now()
+                if update.isNewPeer {
+                    SecureLogger.debug("🆕 New peer: \(announcement.nickname)", category: .session)
+                } else if update.wasDisconnected {
+                    if env.shouldEmitReconnectLog(peerID, now) {
+                        SecureLogger.debug("🔄 Peer \(announcement.nickname) reconnected", category: .session)
+                    }
+                } else if let previousNickname = update.previousNickname, previousNickname != announcement.nickname {
+                    SecureLogger.debug("🔄 Peer \(peerID.id.prefix(8))… changed nickname: \(previousNickname) -> \(announcement.nickname)", category: .session)
+                }
+            }
+        }
+
+        // Update topology with verified neighbor claims (only for authenticated announces)
+        if verifiedAnnounce, let neighbors = announcement.directNeighbors {
+            env.updateTopology(peerID, neighbors)
+        }
+
+        // Persist cryptographic identity and signing key for robust offline
+        // verification — only for verified announces. Persisting unverified
+        // announces would let an attacker who replays a victim's noisePublicKey
+        // overwrite the victim's stored signing key/nickname (identity poisoning).
+        if verifiedAnnounce {
+            env.persistIdentity(announcement)
+        }
+
+        let announceBackID = "announce-back-\(peerID)"
+        let shouldSendBack = !env.dedupContains(announceBackID)
+        if shouldSendBack {
+            env.dedupMarkProcessed(announceBackID)
+        }
+        let responsePlan = BLEAnnounceResponsePolicy.plan(
+            isDirectAnnounce: isDirectAnnounce,
+            isNewPeer: isNewPeer,
+            isReconnectedPeer: isReconnectedPeer,
+            shouldSendAnnounceBack: shouldSendBack
+        )
+
+        // Only notify of connection for new or reconnected peers when it is a
+        // direct announce; the list update always follows in the same hop.
+        env.deliverAnnounceUIEvents(
+            peerID,
+            responsePlan.shouldNotifyPeerConnected,
+            responsePlan.shouldNotifyPeerConnected && responsePlan.shouldScheduleInitialSync
+        )
+
+        // Track for sync (include our own and others' announces)
+        env.trackPacketSeen(packet)
+
+        if responsePlan.shouldSendAnnounceBack {
+            // Reciprocate announce for bidirectional discovery
+            // Force send to ensure the peer receives our announce
+            env.sendAnnounceBack()
+        }
+
+        // Afterglow: on first-seen peers, schedule a short re-announce to push presence one more hop
+        if responsePlan.shouldScheduleAfterglow {
+            let delay = Double.random(in: 0.3...0.6)
+            env.scheduleAfterglow(delay)
+        }
+
+        return BLEAnnounceHandlingResult(
+            peerID: peerID,
+            announcement: announcement,
+            isDirectAnnounce: isDirectAnnounce,
+            isVerified: verifiedAnnounce
+        )
+    }
+}

bitchat/Services/BLE/BLEConnectionScheduler.swift

@@ -41,13 +41,16 @@ final class BLEConnectionScheduler<Peripheral> {
     private let candidateCap: Int
     private let weakLinkCooldownSeconds: TimeInterval
     private let weakLinkRSSICutoff: Int
-    private let recentTimeoutWindowSeconds: TimeInterval
-    private let recentTimeoutCountThreshold: Int
 
     private var lastGlobalConnectAttempt: Date = .distantPast
     private var candidates: [BLEConnectionCandidate<Peripheral>] = []
     private var failureCounts: [String: Int] = [:]
     private var recentConnectTimeouts: [String: Date] = [:]
+    // Tracked separately from connect timeouts: a peer we held a connection
+    // with and lost (walked out of range) usually comes back, so it only gets
+    // a brief rediscovery ignore — not the timeout backoff/cooldown treatment
+    // reserved for peers that never answered a connect attempt.
+    private var recentDisconnects: [String: Date] = [:]
     private var lastIsolatedAt: Date?
 
     private let initialDynamicRSSIThreshold: Int
@@ -63,8 +66,6 @@ final class BLEConnectionScheduler<Peripheral> {
         candidateCap: Int = TransportConfig.bleConnectionCandidatesMax,
         weakLinkCooldownSeconds: TimeInterval = TransportConfig.bleWeakLinkCooldownSeconds,
         weakLinkRSSICutoff: Int = TransportConfig.bleWeakLinkRSSICutoff,
-        recentTimeoutWindowSeconds: TimeInterval = TransportConfig.bleRecentTimeoutWindowSeconds,
-        recentTimeoutCountThreshold: Int = TransportConfig.bleRecentTimeoutCountThreshold,
         dynamicRSSIThreshold: Int = TransportConfig.bleDynamicRSSIThresholdDefault
     ) {
         self.maxCentralLinks = maxCentralLinks
@@ -72,8 +73,6 @@ final class BLEConnectionScheduler<Peripheral> {
         self.candidateCap = candidateCap
         self.weakLinkCooldownSeconds = weakLinkCooldownSeconds
         self.weakLinkRSSICutoff = weakLinkRSSICutoff
-        self.recentTimeoutWindowSeconds = recentTimeoutWindowSeconds
-        self.recentTimeoutCountThreshold = recentTimeoutCountThreshold
         self.initialDynamicRSSIThreshold = dynamicRSSIThreshold
         self.dynamicRSSIThreshold = dynamicRSSIThreshold
     }
@@ -114,7 +113,12 @@ final class BLEConnectionScheduler<Peripheral> {
         }
 
         if let lastTimeout = recentConnectTimeouts[candidate.peripheralID],
-           now.timeIntervalSince(lastTimeout) < 15 {
+           now.timeIntervalSince(lastTimeout) < TransportConfig.bleTimeoutDiscoveryIgnoreSeconds {
+            return .ignore
+        }
+
+        if let lastDisconnect = recentDisconnects[candidate.peripheralID],
+           now.timeIntervalSince(lastDisconnect) < TransportConfig.bleDisconnectDiscoveryIgnoreSeconds {
             return .ignore
         }
 
@@ -163,6 +167,11 @@ final class BLEConnectionScheduler<Peripheral> {
                 return .retryAfter(delay)
             }
 
+            if let delay = disconnectSettleDelay(for: candidate, now: now) {
+                enqueue(candidate)
+                return .retryAfter(delay)
+            }
+
             if isAlreadyConnectingOrConnected(candidate.peripheralID) {
                 continue
             }
@@ -180,6 +189,7 @@ final class BLEConnectionScheduler<Peripheral> {
     func recordConnectionSuccess(peripheralID: String) {
         failureCounts[peripheralID] = 0
         recentConnectTimeouts.removeValue(forKey: peripheralID)
+        recentDisconnects.removeValue(forKey: peripheralID)
     }
 
     func recordConnectionFailure(peripheralID: String) {
@@ -187,7 +197,7 @@ final class BLEConnectionScheduler<Peripheral> {
     }
 
     func recordDisconnectError(peripheralID: String, at now: Date) {
-        recentConnectTimeouts[peripheralID] = now
+        recentDisconnects[peripheralID] = now
     }
 
     func recordConnectionTimeout(peripheralID: String, at now: Date) {
@@ -197,6 +207,7 @@ final class BLEConnectionScheduler<Peripheral> {
 
     func pruneConnectionTimeouts(before cutoff: Date) {
         recentConnectTimeouts = recentConnectTimeouts.filter { $0.value >= cutoff }
+        recentDisconnects = recentDisconnects.filter { $0.value >= cutoff }
     }
 
     func reset() {
@@ -204,6 +215,7 @@ final class BLEConnectionScheduler<Peripheral> {
         candidates.removeAll()
         failureCounts.removeAll()
         recentConnectTimeouts.removeAll()
+        recentDisconnects.removeAll()
         lastIsolatedAt = nil
         dynamicRSSIThreshold = initialDynamicRSSIThreshold
     }
@@ -225,18 +237,14 @@ final class BLEConnectionScheduler<Peripheral> {
         }
 
         lastIsolatedAt = nil
+        // Flaky links are handled per-peripheral (weak-link cooldown, discovery
+        // ignore window, score bias) — never globally, so one flaky distant peer
+        // can't blind us to every other edge-of-range peer.
         var threshold = TransportConfig.bleDynamicRSSIThresholdDefault
         if connectedOrConnectingLinkCount >= maxCentralLinks || candidates.count >= candidateCap {
             threshold = TransportConfig.bleRSSIConnectedThreshold
         }
 
-        let recentTimeouts = recentConnectTimeouts.filter {
-            now.timeIntervalSince($0.value) < recentTimeoutWindowSeconds
-        }.count
-        if recentTimeouts >= recentTimeoutCountThreshold {
-            threshold = max(threshold, TransportConfig.bleRSSIHighTimeoutThreshold)
-        }
-
         dynamicRSSIThreshold = threshold
         return threshold
     }
@@ -258,6 +266,20 @@ final class BLEConnectionScheduler<Peripheral> {
         return min(max(2.0, remaining), 15.0)
     }
 
+    // The disconnect settle window must hold on the queue path too: a stale
+    // candidate enqueued while the peripheral was still connected would
+    // otherwise reconnect immediately via the post-disconnect queue drain,
+    // bypassing the window and recreating reconnect/cancel thrash.
+    private func disconnectSettleDelay(
+        for candidate: BLEConnectionCandidate<Peripheral>,
+        now: Date
+    ) -> TimeInterval? {
+        guard let lastDisconnect = recentDisconnects[candidate.peripheralID] else { return nil }
+        let remaining = TransportConfig.bleDisconnectDiscoveryIgnoreSeconds - now.timeIntervalSince(lastDisconnect)
+        guard remaining > 0 else { return nil }
+        return remaining + 0.05
+    }
+
     private func score(_ candidate: BLEConnectionCandidate<Peripheral>, now: Date) -> Int {
         let failures = failureCounts[candidate.peripheralID] ?? 0
         let penalty = min(20, 1 << min(4, failures))

bitchat/Services/BLE/BLEFanoutSelector.swift

@@ -13,17 +13,61 @@ enum BLEFanoutSelector {
         centralIDs: [String],
         ingressLink: BLEIngressLinkID?,
         excludedLinks: Set<BLEIngressLinkID> = [],
+        peripheralPeerBindings: [String: PeerID] = [:],
+        centralPeerBindings: [String: PeerID] = [:],
+        preferredPeripheralPerPeer: [PeerID: String] = [:],
+        collapseDuplicatePeerLinks: Bool = true,
         directedPeerHint: PeerID?,
+        requireDirectPeerLink: Bool = false,
         packetType: UInt8,
         messageID: String
     ) -> BLEFanoutSelection {
-        let allowed = allowedLinks(
+        let rawAllowed = allowedLinks(
             peripheralIDs: peripheralIDs,
             centralIDs: centralIDs,
             ingressLink: ingressLink,
             excludedLinks: excludedLinks
         )
 
+        if let directedPeerHint,
+           let directedSelection = directLinks(
+               to: directedPeerHint,
+               links: rawAllowed,
+               peripheralPeerBindings: peripheralPeerBindings,
+               centralPeerBindings: centralPeerBindings,
+               preferredPeripheralPerPeer: preferredPeripheralPerPeer
+           ) {
+            return directedSelection
+        }
+        if directedPeerHint != nil, requireDirectPeerLink {
+            return BLEFanoutSelection(peripheralIDs: [], centralIDs: [])
+        }
+        if let directedPeerHint,
+           hasBoundLink(
+               to: directedPeerHint,
+               peripheralIDs: peripheralIDs,
+               centralIDs: centralIDs,
+               peripheralPeerBindings: peripheralPeerBindings,
+               centralPeerBindings: centralPeerBindings
+           ) {
+            return BLEFanoutSelection(peripheralIDs: [], centralIDs: [])
+        }
+
+        // Direct announces are the packet that binds a link to its peer
+        // (BLEService's raw bind and verified rebind). Collapsing them per
+        // peer starves duplicate same-peer links of the announce they need to
+        // become bound — the duplicates then look "pre-announce" forever and
+        // every broadcast sprays down all of them. Announces are small and
+        // throttled, so they go on every live link.
+        let allowed = collapseDuplicatePeerLinks
+            ? collapseDuplicateLinksPerPeer(
+                rawAllowed,
+                peripheralPeerBindings: peripheralPeerBindings,
+                centralPeerBindings: centralPeerBindings,
+                preferredPeripheralPerPeer: preferredPeripheralPerPeer
+            )
+            : rawAllowed
+
         guard shouldSubset(packetType: packetType, directedPeerHint: directedPeerHint) else {
             return BLEFanoutSelection(
                 peripheralIDs: Set(allowed.peripheralIDs),
@@ -65,6 +109,99 @@ enum BLEFanoutSelector {
         return (allowedPeripheralIDs, allowedCentralIDs)
     }
 
+    private static func directLinks(
+        to peerID: PeerID,
+        links: (peripheralIDs: [String], centralIDs: [String]),
+        peripheralPeerBindings: [String: PeerID],
+        centralPeerBindings: [String: PeerID],
+        preferredPeripheralPerPeer: [PeerID: String]
+    ) -> BLEFanoutSelection? {
+        let directLinks = collapseDuplicateLinksPerPeer(
+            (
+                peripheralIDs: links.peripheralIDs.filter { peripheralPeerBindings[$0] == peerID },
+                centralIDs: links.centralIDs.filter { centralPeerBindings[$0] == peerID }
+            ),
+            peripheralPeerBindings: peripheralPeerBindings,
+            centralPeerBindings: centralPeerBindings,
+            preferredPeripheralPerPeer: preferredPeripheralPerPeer
+        )
+
+        guard !directLinks.peripheralIDs.isEmpty || !directLinks.centralIDs.isEmpty else {
+            return nil
+        }
+
+        return BLEFanoutSelection(
+            peripheralIDs: Set(directLinks.peripheralIDs),
+            centralIDs: Set(directLinks.centralIDs)
+        )
+    }
+
+    private static func hasBoundLink(
+        to peerID: PeerID,
+        peripheralIDs: [String],
+        centralIDs: [String],
+        peripheralPeerBindings: [String: PeerID],
+        centralPeerBindings: [String: PeerID]
+    ) -> Bool {
+        peripheralIDs.contains { peripheralPeerBindings[$0] == peerID }
+            || centralIDs.contains { centralPeerBindings[$0] == peerID }
+    }
+
+    // Dual-role pairs hold two live links (we-as-central writing to their
+    // peripheral, and they-as-central subscribed to ours). Sending the same
+    // packet down both doubles airtime for nothing — the receiver's assembler
+    // and deduplicator just discard the copy. Keep one link per bound peer,
+    // preferring the peripheral (write) side: it has per-link flow control
+    // via canSendWriteWithoutResponse, while notifications share the
+    // peripheral manager's update queue across all centrals. Links with no
+    // bound peer yet (pre-announce) pass through untouched.
+    private static func collapseDuplicateLinksPerPeer(
+        _ links: (peripheralIDs: [String], centralIDs: [String]),
+        peripheralPeerBindings: [String: PeerID],
+        centralPeerBindings: [String: PeerID],
+        preferredPeripheralPerPeer: [PeerID: String]
+    ) -> (peripheralIDs: [String], centralIDs: [String]) {
+        guard !peripheralPeerBindings.isEmpty || !centralPeerBindings.isEmpty else {
+            return links
+        }
+
+        var seenPeers = Set<PeerID>()
+        var keptPeripheralIDs: [String] = []
+        // When a peer has several bound peripheral links (duplicate
+        // connections after a restore), collapse onto its preferred one (the
+        // most recently bound) instead of dictionary order — an arbitrary
+        // pick could route a peer's single collapsed copy down a stale link.
+        for id in links.peripheralIDs {
+            guard let peer = peripheralPeerBindings[id],
+                  preferredPeripheralPerPeer[peer] == id,
+                  seenPeers.insert(peer).inserted else { continue }
+            keptPeripheralIDs.append(id)
+        }
+        for id in links.peripheralIDs {
+            if let peer = peripheralPeerBindings[id] {
+                if preferredPeripheralPerPeer[peer] == id { continue }
+                if !seenPeers.insert(peer).inserted { continue }
+            }
+            keptPeripheralIDs.append(id)
+        }
+
+        // Known limitation: centrals collapse in subscription order (oldest
+        // first) — there is no recency signal like the peripheral reverse
+        // map. A central-only peer with duplicate subscriptions rides the
+        // oldest one until the remote side (which owns those connections)
+        // consolidates on its next verified announce (bounded by its
+        // retirement cooldown).
+        var keptCentralIDs: [String] = []
+        for id in links.centralIDs {
+            if let peer = centralPeerBindings[id], !seenPeers.insert(peer).inserted {
+                continue
+            }
+            keptCentralIDs.append(id)
+        }
+
+        return (keptPeripheralIDs, keptCentralIDs)
+    }
+
     private static func shouldSubset(packetType: UInt8, directedPeerHint: PeerID?) -> Bool {
         directedPeerHint == nil
             && packetType != MessageType.fragment.rawValue

bitchat/Services/BLE/BLEFileTransferHandler.swift

@@ -0,0 +1,187 @@
+import BitFoundation
+import BitLogger
+import Foundation
+
+/// Narrow environment for `BLEFileTransferHandler`.
+///
+/// All queue hops (collections registry reads/writes, main-actor UI
+/// notification) live inside the closures supplied by `BLEService`, keeping
+/// the handler queue-agnostic and synchronously testable.
+struct BLEFileTransferHandlerEnvironment {
+    /// Local peer identity at the time the transfer is handled.
+    let localPeerID: () -> PeerID
+    /// Local nickname used for sender resolution and collision checks.
+    let localNickname: () -> String
+    /// Snapshot of known peers keyed by ID (registry read).
+    let peersSnapshot: () -> [PeerID: BLEPeerInfo]
+    /// Verifies a packet's signature against a candidate signing key (registry path).
+    let verifyPacketSignature: (_ packet: BitchatPacket, _ signingPublicKey: Data) -> Bool
+    /// Resolves a display name from a verified packet signature for peers missing from the registry.
+    let signedSenderDisplayName: (_ packet: BitchatPacket, _ peerID: PeerID) -> String?
+    /// Tracks the broadcast file packet for gossip sync.
+    let trackPacketSeen: (BitchatPacket) -> Void
+    /// Enforces the incoming-media storage quota before saving (BCH-01-002).
+    let enforceStorageQuota: (_ reservingBytes: Int) -> Void
+    /// Persists the validated file to the incoming-media store; returns the destination URL.
+    let saveIncomingFile: (
+        _ data: Data,
+        _ preferredName: String?,
+        _ subdirectory: String,
+        _ fallbackExtension: String?,
+        _ defaultPrefix: String
+    ) -> URL?
+    /// Updates the registry last-seen timestamp for the peer (async barrier write).
+    let updatePeerLastSeen: (PeerID) -> Void
+    /// Delivers `.messageReceived` to the UI as one main-actor hop.
+    let deliverMessage: (BitchatMessage) -> Void
+}
+
+/// Orchestrates inbound file transfers: self-echo policy, sender display-name
+/// resolution, delivery planning, payload validation, quota-checked storage,
+/// and UI delivery.
+final class BLEFileTransferHandler {
+    private let environment: BLEFileTransferHandlerEnvironment
+
+    init(environment: BLEFileTransferHandlerEnvironment) {
+        self.environment = environment
+    }
+
+    /// Returns `false` when the packet fails sender authentication and must
+    /// not be relayed onward. Every other outcome returns `true`: files
+    /// directed to another peer are forwarded untouched, and local-only drops
+    /// (malformed payload, quota, save failure) don't affect multi-hop
+    /// delivery to nodes that may handle them fine.
+    @discardableResult
+    func handle(_ packet: BitchatPacket, from peerID: PeerID) -> Bool {
+        let env = environment
+        if BLEFileTransferPolicy.isSelfEcho(packet: packet, from: peerID, localPeerID: env.localPeerID()) { return true }
+
+        guard let deliveryPlan = BLEFileTransferPolicy.deliveryPlan(packet: packet, localPeerID: env.localPeerID()) else {
+            return true
+        }
+
+        let peersSnapshot = env.peersSnapshot()
+        guard let senderNickname = resolveSenderNickname(
+            packet: packet,
+            from: peerID,
+            isBroadcast: !deliveryPlan.isPrivateMessage,
+            peers: peersSnapshot,
+            env: env
+        ) else {
+            SecureLogger.warning("🚫 Dropping file transfer from unverified or unknown peer \(peerID.id.prefix(8))…", category: .security)
+            return false
+        }
+
+        if deliveryPlan.shouldTrackForSync {
+            env.trackPacketSeen(packet)
+        }
+
+        let filePacket: BitchatFilePacket
+        let mime: MimeType
+        switch BLEIncomingFileValidator.validate(payload: packet.payload) {
+        case .success(let acceptance):
+            filePacket = acceptance.filePacket
+            mime = acceptance.mime
+        case .failure(.malformedPayload):
+            SecureLogger.error("❌ Failed to decode file transfer payload", category: .session)
+            return true
+        case .failure(.payloadTooLarge(let bytes)):
+            SecureLogger.warning("🚫 Dropping file transfer exceeding size cap (\(bytes) bytes)", category: .security)
+            return true
+        case .failure(.unsupportedMime(let mimeType, let bytes)):
+            SecureLogger.warning("🚫 MIME REJECT: '\(mimeType ?? "<empty>")' not supported. Size=\(bytes)b from \(peerID.id.prefix(8))...", category: .security)
+            return true
+        case .failure(.magicMismatch(let mime, let bytes, let prefixHex)):
+            SecureLogger.warning("🚫 MAGIC REJECT: MIME='\(mime)' size=\(bytes)b prefix=[\(prefixHex)] from \(peerID.id.prefix(8))...", category: .security)
+            return true
+        }
+
+        // BCH-01-002: Enforce storage quota before saving
+        env.enforceStorageQuota(filePacket.content.count)
+
+        guard let destination = env.saveIncomingFile(
+            filePacket.content,
+            filePacket.fileName,
+            "\(mime.category.mediaDir)/incoming",
+            mime.defaultExtension,
+            mime.category.rawValue
+        ) else {
+            return true
+        }
+
+        if deliveryPlan.isPrivateMessage {
+            env.updatePeerLastSeen(peerID)
+        }
+
+        let ts = Date(timeIntervalSince1970: Double(packet.timestamp) / 1000)
+        let message = BitchatMessage(
+            sender: senderNickname,
+            content: "\(mime.category.messagePrefix)\(destination.lastPathComponent)",
+            timestamp: ts,
+            isRelay: false,
+            originalSender: nil,
+            isPrivate: deliveryPlan.isPrivateMessage,
+            recipientNickname: nil,
+            senderPeerID: peerID,
+            // Received messages need an explicit status: BitchatMessage
+            // defaults private messages to .sending, which the media views
+            // render as an in-flight send (empty reveal mask, disabled tap).
+            deliveryStatus: deliveryPlan.isPrivateMessage
+                ? .delivered(to: env.localNickname(), at: ts)
+                : nil
+        )
+
+        SecureLogger.debug("📁 Stored incoming media from \(peerID.id.prefix(8))… -> \(destination.lastPathComponent)", category: .session)
+
+        env.deliverMessage(message)
+        return true
+    }
+
+    /// Resolves the authenticated display name for a file transfer's sender.
+    ///
+    /// Directed (private) transfers are addressed to us specifically and keep
+    /// the lenient connected-peer path. Broadcast transfers carry an
+    /// attacker-controllable `senderID` exactly like public messages and public
+    /// voice frames — registry membership alone is NOT proof of identity, so a
+    /// valid packet signature from the claimed sender is required before we
+    /// trust it. Without this, a peer that observed a public voice burst could
+    /// spoof a broadcast `voice_<burstID>.m4a` note under the talker's ID and
+    /// overwrite the signature-verified live bubble with attacker audio.
+    private func resolveSenderNickname(
+        packet: BitchatPacket,
+        from peerID: PeerID,
+        isBroadcast: Bool,
+        peers: [PeerID: BLEPeerInfo],
+        env: BLEFileTransferHandlerEnvironment
+    ) -> String? {
+        guard isBroadcast else {
+            return BLEPeerSenderDisplayName.resolveKnownPeer(
+                peerID: peerID,
+                localPeerID: env.localPeerID(),
+                localNickname: env.localNickname(),
+                peers: peers,
+                allowConnectedUnverified: true
+            ) ?? env.signedSenderDisplayName(packet, peerID)
+        }
+
+        // Our own broadcasts replayed back via gossip sync (ttl==0) are
+        // trivially authentic and cannot be verified against the peer registry
+        // or identity cache, so exempt self exactly as `BLEPublicMessageHandler`
+        // does. Verify against the signing key already in the
+        // (synchronously-updated) registry first, then fall back to the
+        // persisted-identity signature lookup for peers not yet cached there.
+        let isSelf = peerID == env.localPeerID()
+        let registrySigningKey = peers[peerID]?.signingPublicKey
+        let verifiedViaRegistry = !isSelf && (registrySigningKey.map { env.verifyPacketSignature(packet, $0) } ?? false)
+        let signedDisplayName = (isSelf || verifiedViaRegistry) ? nil : env.signedSenderDisplayName(packet, peerID)
+        guard isSelf || verifiedViaRegistry || signedDisplayName != nil else { return nil }
+
+        return BLEPeerSenderDisplayName.resolveKnownPeer(
+            peerID: peerID,
+            localPeerID: env.localPeerID(),
+            localNickname: env.localNickname(),
+            peers: peers,
+            allowConnectedUnverified: false
+        ) ?? signedDisplayName
+    }
+}

bitchat/Services/BLE/BLEFragmentAssemblyBuffer.swift

@@ -61,9 +61,11 @@ struct BLEFragmentAssemblyBuffer {
     }
 
     private struct Metadata {
-        let type: UInt8
         let total: Int
         let timestamp: Date
+        let isBroadcast: Bool
+        var lastFragmentAt: Date
+        var lastResyncRequestAt: Date?
     }
 
     private var fragmentsByKey: [BLEFragmentKey: [Int: Data]] = [:]
@@ -105,7 +107,15 @@ struct BLEFragmentAssemblyBuffer {
             return .oversized(header: header, projectedSize: projectedSize, limit: limit, started: started)
         }
 
+        // Only actual progress resets the stall clock: fragment packets
+        // bypass the packet deduplicator, so relayed duplicates of an
+        // already-held index must not keep suppressing the targeted
+        // REQUEST_SYNC for a stalled stream.
+        let isNewIndex = fragmentsByKey[header.key]?[header.index] == nil
         fragmentsByKey[header.key]?[header.index] = header.fragmentData
+        if isNewIndex {
+            metadataByKey[header.key]?.lastFragmentAt = now
+        }
 
         guard let fragments = fragmentsByKey[header.key],
               fragments.count == header.total else {
@@ -138,10 +148,58 @@ struct BLEFragmentAssemblyBuffer {
         }
 
         fragmentsByKey[header.key] = [:]
-        metadataByKey[header.key] = Metadata(type: header.originalType, total: header.total, timestamp: now)
+        metadataByKey[header.key] = Metadata(
+            total: header.total,
+            timestamp: now,
+            isBroadcast: header.isBroadcastFragment,
+            lastFragmentAt: now
+        )
         return true
     }
 
+    /// Fragment stream IDs (8-byte, big-endian) of incomplete broadcast
+    /// reassemblies that have not seen a new fragment for `stalledAfter`
+    /// seconds — candidates for a targeted REQUEST_SYNC. Each returned
+    /// stream is marked so it is not re-requested within `retryAfter`.
+    /// At most `RequestSyncPacket.maxFragmentIdFilterCount` streams are
+    /// returned per pass — the wire filter cannot carry more — selected
+    /// oldest-stall first; overflow streams stay unmarked and eligible for
+    /// the next pass. Directed reassemblies are excluded: peers only archive
+    /// broadcast fragments for gossip sync, so a targeted request cannot
+    /// recover them.
+    mutating func stalledBroadcastFragmentIDs(
+        stalledAfter: TimeInterval,
+        retryAfter: TimeInterval,
+        now: Date = Date()
+    ) -> [Data] {
+        var candidates: [(key: BLEFragmentKey, lastFragmentAt: Date)] = []
+        for (key, metadata) in metadataByKey {
+            guard metadata.isBroadcast,
+                  let fragments = fragmentsByKey[key],
+                  fragments.count < metadata.total,
+                  now.timeIntervalSince(metadata.lastFragmentAt) >= stalledAfter else { continue }
+            if let lastRequest = metadata.lastResyncRequestAt,
+               now.timeIntervalSince(lastRequest) < retryAfter { continue }
+            candidates.append((key: key, lastFragmentAt: metadata.lastFragmentAt))
+        }
+
+        // Mark only the streams that will actually go on the wire, so the
+        // overflow is not silently suppressed for `retryAfter`.
+        let selected = candidates
+            .sorted {
+                if $0.lastFragmentAt != $1.lastFragmentAt {
+                    return $0.lastFragmentAt < $1.lastFragmentAt
+                }
+                return ($0.key.sender, $0.key.id) < ($1.key.sender, $1.key.id)
+            }
+            .prefix(RequestSyncPacket.maxFragmentIdFilterCount)
+
+        return selected.map { candidate in
+            metadataByKey[candidate.key]?.lastResyncRequestAt = now
+            return withUnsafeBytes(of: candidate.key.id.bigEndian) { Data($0) }
+        }
+    }
+
     private static func assemblyLimit(for originalType: UInt8) -> Int {
         if originalType == MessageType.fileTransfer.rawValue {
             // Allow headroom for TLV metadata and binary framing overhead.

bitchat/Services/BLE/BLEFragmentHandler.swift

@@ -0,0 +1,102 @@
+import BitFoundation
+import BitLogger
+import Foundation
+
+/// Narrow environment for `BLEFragmentHandler`.
+///
+/// All queue hops (the message-queue entry hop and the collections barrier
+/// around the assembly buffer) live on the `BLEService` side — the entry hop
+/// in `BLEService.handleFragment`, the barrier inside the supplied closures —
+/// keeping the handler queue-agnostic and synchronously testable.
+struct BLEFragmentHandlerEnvironment {
+    /// Local peer identity at the time the fragment is handled.
+    let localPeerID: () -> PeerID
+    /// Tracks broadcast fragments for gossip sync.
+    let trackPacketSeen: (BitchatPacket) -> Void
+    /// Appends the fragment to the assembly buffer (collections barrier write).
+    let appendFragment: (BLEFragmentHeader) -> BLEFragmentAssemblyBuffer.AppendResult
+    /// Ingress acceptance check for the reassembled inner packet.
+    let isAcceptedIngressPayload: (_ packet: BitchatPacket, _ innerSender: PeerID) -> Bool
+    /// Re-enters the receive pipeline with the reassembled packet (TTL already zeroed).
+    let processReassembledPacket: (_ packet: BitchatPacket, _ from: PeerID) -> Void
+}
+
+/// Orchestrates inbound fragments: self-fragment suppression, gossip tracking,
+/// assembly-buffer appends, and reassembled-packet validation and re-injection
+/// into the receive pipeline.
+final class BLEFragmentHandler {
+    private let environment: BLEFragmentHandlerEnvironment
+
+    init(environment: BLEFragmentHandlerEnvironment) {
+        self.environment = environment
+    }
+
+    func handle(_ packet: BitchatPacket, from peerID: PeerID) {
+        let env = environment
+        guard let header = BLEFragmentHeader(packet: packet) else { return }
+
+        // Sync replay legitimately hands us our own fragments back (the RSR
+        // ttl=0 restore path): after a relaunch the fragment store starts
+        // empty, so our sync filter doesn't cover them and peers re-offer
+        // them. Record them as seen — the next round's filter then covers
+        // them and the redelivery stops — but skip assembly: we authored
+        // the original, there is nothing to reassemble.
+        if peerID == env.localPeerID() {
+            if header.isBroadcastFragment {
+                env.trackPacketSeen(packet)
+            }
+            return
+        }
+
+        if header.isBroadcastFragment {
+            env.trackPacketSeen(packet)
+        }
+
+        let assemblyResult = env.appendFragment(header)
+
+        logFragmentAssemblyResult(assemblyResult)
+
+        guard case let .complete(completedHeader, reassembled, _) = assemblyResult else { return }
+
+        // Decode the original packet bytes we reassembled, so flags/compression are preserved
+        if var originalPacket = BinaryProtocol.decode(reassembled) {
+
+            // Reassembled packet validation
+            let innerSender = PeerID(hexData: originalPacket.senderID)
+            if !env.isAcceptedIngressPayload(originalPacket, innerSender) {
+                // Cleanup below
+            } else {
+                SecureLogger.debug("✅ Reassembled packet id=\(completedHeader.idLogString) type=\(originalPacket.type) bytes=\(reassembled.count)", category: .session)
+                originalPacket.ttl = 0
+                env.processReassembledPacket(originalPacket, peerID)
+            }
+        } else {
+            SecureLogger.error("❌ Failed to decode reassembled packet (type=\(completedHeader.originalType), total=\(completedHeader.total))", category: .session)
+        }
+    }
+
+    private func logFragmentAssemblyResult(_ result: BLEFragmentAssemblyBuffer.AppendResult) {
+        func logStartedIfNeeded(header: BLEFragmentHeader, started: Bool) {
+            if started {
+                SecureLogger.debug("📦 Started fragment assembly id=\(header.idLogString) total=\(header.total)", category: .session)
+            }
+        }
+
+        switch result {
+        case let .stored(header, started):
+            logStartedIfNeeded(header: header, started: started)
+            SecureLogger.debug("📦 Fragment \(header.index + 1)/\(header.total) (len=\(header.fragmentData.count)) for id=\(header.idLogString)", category: .session)
+
+        case let .complete(header, _, started):
+            logStartedIfNeeded(header: header, started: started)
+            SecureLogger.debug("📦 Fragment \(header.index + 1)/\(header.total) (len=\(header.fragmentData.count)) for id=\(header.idLogString)", category: .session)
+
+        case let .oversized(header, projectedSize, limit, started):
+            logStartedIfNeeded(header: header, started: started)
+            SecureLogger.warning(
+                "🚫 Fragment assembly exceeds size limit (\(projectedSize) bytes > \(limit)), evicting. Type=\(header.originalType) Index=\(header.index)/\(header.total)",
+                category: .security
+            )
+        }
+    }
+}

bitchat/Services/BLE/BLEIncomingFileStore.swift

@@ -5,7 +5,16 @@ import Foundation
 struct BLEIncomingFileStore {
     private static let quotaBytes: Int64 = 100 * 1024 * 1024
 
-    private let fileManager: FileManager
+    /// Name prefix of in-flight live voice captures (progressively written by
+    /// `ChatLiveVoiceCoordinator`). Quota eviction skips them by pattern —
+    /// deleting one mid-stream unlinks the inode under an open `FileHandle`
+    /// and kills playback — and the coordinator's startup sweep deletes any
+    /// orphans a previous session left behind.
+    static let liveCapturePrefix = "voice_live_"
+
+    /// Exposed so callers that write progressively into the store's
+    /// directories (live voice captures) share the same file manager.
+    let fileManager: FileManager
     private let baseDirectory: URL?
     private let dateProvider: () -> Date
 
@@ -15,6 +24,14 @@ struct BLEIncomingFileStore {
         self.dateProvider = dateProvider
     }
 
+    /// Resolves (and creates) an incoming-media directory for callers that
+    /// write progressively instead of via `save` (live voice captures).
+    func incomingDirectory(subdirectory: String) throws -> URL {
+        let directory = try filesDirectory().appendingPathComponent(subdirectory, isDirectory: true)
+        try fileManager.createDirectory(at: directory, withIntermediateDirectories: true, attributes: nil)
+        return directory
+    }
+
     func save(
         data: Data,
         preferredName: String?,
@@ -39,6 +56,11 @@ struct BLEIncomingFileStore {
         }
     }
 
+    /// Frees least-recently-modified incoming files until `reservingBytes`
+    /// fits under the quota. Files named `voice_live_*` (in-flight live
+    /// captures) are never evicted regardless of who triggers enforcement —
+    /// a finalized transfer can arrive at quota while a burst is still
+    /// streaming — but they still count toward usage.
     func enforceQuota(reservingBytes: Int) {
         do {
             let base = try filesDirectory()
@@ -72,6 +94,7 @@ struct BLEIncomingFileStore {
             var freedSpace: Int64 = 0
             for file in allFiles.sorted(by: { $0.modified < $1.modified }) {
                 guard freedSpace < needToFree else { break }
+                guard !file.url.lastPathComponent.hasPrefix(Self.liveCapturePrefix) else { continue }
                 do {
                     try fileManager.removeItem(at: file.url)
                     freedSpace += file.size

bitchat/Services/BLE/BLEIngressLinkRegistry.swift

@@ -78,11 +78,22 @@ struct BLEIngressLinkRegistry {
             return .failure(.selfLoopback(packetType: packet.type))
         }
 
-        if let boundPeerID,
+        if let boundPeerID, boundPeerID != claimedSenderID {
-           boundPeerID != claimedSenderID,
+            if requiresDirectSenderBinding(packet) {
-           requiresDirectSenderBinding(packet, directAnnounceTTL: directAnnounceTTL) {
                 return .failure(.directSenderMismatch(boundPeerID: boundPeerID, claimedSenderID: claimedSenderID))
             }
+            // A direct announce claiming a new sender on a bound link is either
+            // a spoof or a legitimate peer-ID rotation on a connection that
+            // outlived the old ID. Attribute it to the claimed sender and let
+            // it through: announces are self-authenticating, and only a
+            // signature-verified announce may rebind the link (BLEService).
+            if isDirectAnnounce(packet, directAnnounceTTL: directAnnounceTTL) {
+                return .success(BLEIngressPacketContext(
+                    receivedFromPeerID: claimedSenderID,
+                    validationPeerID: claimedSenderID
+                ))
+            }
+        }
 
         let receivedFromPeerID = boundPeerID ?? claimedSenderID
         let validationPeerID = packet.isRSR ? receivedFromPeerID : claimedSenderID
@@ -98,7 +109,14 @@ struct BLEIngressLinkRegistry {
         return "\(senderID)-\(packet.timestamp)-\(packet.type)-\(digestPrefix)"
     }
 
-    private static func requiresDirectSenderBinding(_ packet: BitchatPacket, directAnnounceTTL: UInt8) -> Bool {
+    private static func requiresDirectSenderBinding(_ packet: BitchatPacket) -> Bool {
+        // REQUEST_SYNC is never relayed, so on a bound link the claimed sender
+        // must be the link peer — it elicits a full store replay, and the
+        // response is addressed to whoever the sender claims to be.
+        packet.type == MessageType.requestSync.rawValue
+    }
+
+    static func isDirectAnnounce(_ packet: BitchatPacket, directAnnounceTTL: UInt8) -> Bool {
         packet.type == MessageType.announce.rawValue && packet.ttl == directAnnounceTTL
     }
 

bitchat/Services/BLE/BLELinkStateStore.swift

@@ -26,36 +26,69 @@ struct BLESubscribedCentralSnapshot {
     }
 }
 
+/// Owns all BLE link state (peripheral connections we hold as central, and
+/// central subscriptions we serve as peripheral). The store has no internal
+/// locking: every access must happen on the single owning queue (the BLE
+/// queue). Other queues must go through BLEService's `readLinkState`, which
+/// hops to that queue. Call `assumeOwnership(of:)` to have debug builds trap
+/// any access from the wrong queue.
 final class BLELinkStateStore {
     private(set) var peripherals: [String: BLEPeripheralLinkState] = [:]
     private(set) var peerToPeripheralUUID: [PeerID: String] = [:]
     private(set) var subscribedCentrals: [CBCentral] = []
     private(set) var centralToPeerID: [String: PeerID] = [:]
 
+    #if DEBUG
+    private var ownerQueue: DispatchQueue?
+    #endif
+
+    /// Pin the store to its owning queue. Debug-only enforcement; release
+    /// builds are unchanged.
+    func assumeOwnership(of queue: DispatchQueue) {
+        #if DEBUG
+        ownerQueue = queue
+        #endif
+    }
+
+    @inline(__always)
+    private func assertOwned() {
+        #if DEBUG
+        if let queue = ownerQueue {
+            dispatchPrecondition(condition: .onQueue(queue))
+        }
+        #endif
+    }
+
     var peripheralStates: [BLEPeripheralLinkState] {
-        Array(peripherals.values)
+        assertOwned()
+        return Array(peripherals.values)
     }
 
     var subscribedCentralSnapshot: BLESubscribedCentralSnapshot {
-        BLESubscribedCentralSnapshot(
+        assertOwned()
+        return BLESubscribedCentralSnapshot(
             centrals: subscribedCentrals,
             peerIDsByCentralUUID: centralToPeerID
         )
     }
 
     var subscribedCentralCount: Int {
-        subscribedCentrals.count
+        assertOwned()
+        return subscribedCentrals.count
     }
 
     var connectedOrConnectingPeripheralCount: Int {
-        peripherals.values.filter { $0.isConnected || $0.isConnecting }.count
+        assertOwned()
+        return peripherals.values.filter { $0.isConnected || $0.isConnecting }.count
     }
 
     func state(forPeripheralID peripheralID: String) -> BLEPeripheralLinkState? {
-        peripherals[peripheralID]
+        assertOwned()
+        return peripherals[peripheralID]
     }
 
     func setPeripheralState(_ state: BLEPeripheralLinkState, for peripheralID: String) {
+        assertOwned()
         peripherals[peripheralID] = state
     }
 
@@ -64,6 +97,7 @@ final class BLELinkStateStore {
         _ peripheralID: String,
         _ update: (inout BLEPeripheralLinkState) -> Void
     ) -> BLEPeripheralLinkState? {
+        assertOwned()
         guard var state = peripherals[peripheralID] else { return nil }
         update(&state)
         peripherals[peripheralID] = state
@@ -113,10 +147,12 @@ final class BLELinkStateStore {
     }
 
     func directPeripheralState(for peerID: PeerID) -> BLEPeripheralLinkState? {
-        peerToPeripheralUUID[peerID].flatMap { peripherals[$0] }
+        assertOwned()
+        return peerToPeripheralUUID[peerID].flatMap { peripherals[$0] }
     }
 
     func directLinkState(for peerID: PeerID) -> BLEDirectLinkState {
+        assertOwned()
         let peripheralUUID = peerToPeripheralUUID[peerID]
         let hasPeripheral = peripheralUUID.flatMap { peripherals[$0]?.isConnected } ?? false
         let hasCentral = centralToPeerID.values.contains(peerID)
@@ -124,10 +160,15 @@ final class BLELinkStateStore {
     }
 
     func links(to peerID: PeerID?) -> Set<BLEIngressLinkID> {
+        assertOwned()
         guard let peerID else { return [] }
 
         var links: Set<BLEIngressLinkID> = []
-        if let peripheralUUID = peerToPeripheralUUID[peerID] {
+        // Scan all states rather than the 1:1 reverse map: after a state
+        // restoration the same device can hold several live peripheral links
+        // bound to one peer (it reappears under a fresh UUID while the
+        // restored connection lives on).
+        for (peripheralUUID, state) in peripherals where state.peerID == peerID {
             links.insert(.peripheral(peripheralUUID))
         }
         for (centralUUID, mappedPeerID) in centralToPeerID where mappedPeerID == peerID {
@@ -136,44 +177,80 @@ final class BLELinkStateStore {
         return links
     }
 
+    /// The peer's most recently bound peripheral link, per peer. Used to keep
+    /// duplicate-link fanout collapse deterministic (see BLEFanoutSelector).
+    var preferredPeripheralBindings: [PeerID: String] {
+        assertOwned()
+        return peerToPeripheralUUID
+    }
+
     func peerID(forPeripheralID peripheralID: String) -> PeerID? {
-        peripherals[peripheralID]?.peerID
+        assertOwned()
+        return peripherals[peripheralID]?.peerID
     }
 
     func peerID(forCentralUUID centralUUID: String) -> PeerID? {
-        centralToPeerID[centralUUID]
+        assertOwned()
+        return centralToPeerID[centralUUID]
     }
 
     func addSubscribedCentral(_ central: CBCentral) {
+        assertOwned()
         guard !subscribedCentrals.contains(central) else { return }
         subscribedCentrals.append(central)
     }
 
     func removeSubscribedCentral(_ central: CBCentral) -> PeerID? {
+        assertOwned()
         let centralUUID = central.identifier.uuidString
         subscribedCentrals.removeAll { $0.identifier == central.identifier }
         return centralToPeerID.removeValue(forKey: centralUUID)
     }
 
     func bindCentral(_ centralUUID: String, to peerID: PeerID) {
+        assertOwned()
         centralToPeerID[centralUUID] = peerID
     }
 
     func bindPeripheral(_ peripheralUUID: String, to peerID: PeerID) {
-        if updatePeripheral(peripheralUUID, { $0.peerID = peerID }) != nil {
+        assertOwned()
-            peerToPeripheralUUID[peerID] = peripheralUUID
+        var previousPeerID: PeerID?
+        let updated = updatePeripheral(peripheralUUID) {
+            previousPeerID = $0.peerID
+            $0.peerID = peerID
         }
+        guard updated != nil else { return }
+        // Rebinding (peer-ID rotation): drop the retired ID's reverse mapping
+        // so the old peer no longer claims this link.
+        if let previousPeerID, previousPeerID != peerID,
+           peerToPeripheralUUID[previousPeerID] == peripheralUUID {
+            peerToPeripheralUUID.removeValue(forKey: previousPeerID)
+        }
+        peerToPeripheralUUID[peerID] = peripheralUUID
     }
 
     func removePeripheral(_ peripheralID: String) -> PeerID? {
+        assertOwned()
         let peerID = peripherals.removeValue(forKey: peripheralID)?.peerID
-        if let peerID {
+        // Only clear (or repair) the reverse map when it points at the removed
+        // link: with duplicate links to one peer, removing a stale duplicate
+        // must not strand the peer's surviving bound link.
+        if let peerID, peerToPeripheralUUID[peerID] == peripheralID {
+            // Prefer a writable survivor: repairing onto a link that is
+            // mid-service-rediscovery would strand directed sends until the
+            // characteristic comes back.
+            let survivors = peripherals.filter { $0.value.peerID == peerID && $0.value.isConnected }
+            if let survivorUUID = survivors.first(where: { $0.value.characteristic != nil })?.key ?? survivors.first?.key {
+                peerToPeripheralUUID[peerID] = survivorUUID
+            } else {
                 peerToPeripheralUUID.removeValue(forKey: peerID)
             }
+        }
         return peerID
     }
 
     func clearPeripherals() -> [PeerID] {
+        assertOwned()
         let peerIDs = peripherals.compactMap { $0.value.peerID }
         peripherals.removeAll()
         peerToPeripheralUUID.removeAll()
@@ -181,6 +258,7 @@ final class BLELinkStateStore {
     }
 
     func clearCentrals() -> [PeerID] {
+        assertOwned()
         let peerIDs = Array(centralToPeerID.values)
         subscribedCentrals.removeAll()
         centralToPeerID.removeAll()
@@ -188,6 +266,7 @@ final class BLELinkStateStore {
     }
 
     func clearAll() {
+        assertOwned()
         peripherals.removeAll()
         peerToPeripheralUUID.removeAll()
         subscribedCentrals.removeAll()

bitchat/Services/BLE/BLELogRateLimiter.swift

@@ -25,9 +25,4 @@ final class BLELogRateLimiter {
         }
     }
 
-    func removeAll() {
-        queue.sync {
-            lastLogTimeByKey.removeAll()
-        }
-    }
 }

bitchat/Services/BLE/BLENoisePacketHandler.swift

@@ -0,0 +1,132 @@
+import BitFoundation
+import BitLogger
+import Foundation
+
+/// Narrow environment for `BLENoisePacketHandler`.
+///
+/// All queue hops (collections barrier writes, main-actor UI notification)
+/// and every `noiseService.*` crypto call live inside the closures supplied by
+/// `BLEService`, keeping the handler queue-agnostic and synchronously testable.
+struct BLENoisePacketHandlerEnvironment {
+    /// Local peer identity at the time the packet is handled.
+    let localPeerID: () -> PeerID
+    /// Local peer ID bytes used as the sender of handshake responses.
+    let localPeerIDData: () -> Data
+    /// TTL value used for direct (non-relayed) packets.
+    let messageTTL: UInt8
+    /// Current time source.
+    let now: () -> Date
+    /// Processes an inbound handshake message, returning an optional response payload (crypto).
+    let processHandshakeMessage: (_ peerID: PeerID, _ message: Data) throws -> Data?
+    /// Whether any Noise session (established or pending) exists for the peer (crypto).
+    let hasNoiseSession: (PeerID) -> Bool
+    /// Initiates a fresh Noise handshake with the peer (crypto + send).
+    let initiateHandshake: (PeerID) -> Void
+    /// Broadcasts a packet on the mesh (caller is already on the message queue).
+    let broadcastPacket: (BitchatPacket) -> Void
+    /// Updates the registry last-seen timestamp for the peer (async barrier write).
+    let updatePeerLastSeen: (PeerID) -> Void
+    /// Decrypts an encrypted payload from the peer (crypto).
+    let decrypt: (_ payload: Data, _ peerID: PeerID) throws -> Data
+    /// Clears the peer's Noise session after an unrecoverable decrypt failure (crypto).
+    let clearSession: (PeerID) -> Void
+    /// Delivers `.noisePayloadReceived` to the UI as one main-actor hop.
+    let deliverNoisePayload: (
+        _ peerID: PeerID,
+        _ type: NoisePayloadType,
+        _ payload: Data,
+        _ timestamp: Date
+    ) -> Void
+}
+
+/// Orchestrates the Noise session domain for inbound packets: handshake
+/// processing (with response), encrypted payload decryption and dispatch,
+/// and session recovery on decrypt failure.
+final class BLENoisePacketHandler {
+    private let environment: BLENoisePacketHandlerEnvironment
+
+    init(environment: BLENoisePacketHandlerEnvironment) {
+        self.environment = environment
+    }
+
+    func handleHandshake(_ packet: BitchatPacket, from peerID: PeerID) {
+        let env = environment
+        // Use NoiseEncryptionService for handshake processing
+        if PeerID(hexData: packet.recipientID) == env.localPeerID() {
+            // Handshake is for us
+            do {
+                if let response = try env.processHandshakeMessage(peerID, packet.payload) {
+                    // Send response
+                    let responsePacket = BitchatPacket(
+                        type: MessageType.noiseHandshake.rawValue,
+                        senderID: env.localPeerIDData(),
+                        recipientID: Data(hexString: peerID.id),
+                        timestamp: UInt64(env.now().timeIntervalSince1970 * 1000),
+                        payload: response,
+                        signature: nil,
+                        ttl: env.messageTTL
+                    )
+                    // We're on messageQueue from delegate callback
+                    env.broadcastPacket(responsePacket)
+                }
+
+                // Session establishment will trigger onPeerAuthenticated callback
+                // which will send any pending messages at the right time
+            } catch {
+                SecureLogger.error("Failed to process handshake: \(error)")
+                // Try initiating a new handshake
+                if !env.hasNoiseSession(peerID) {
+                    env.initiateHandshake(peerID)
+                }
+            }
+        }
+    }
+
+    func handleEncrypted(_ packet: BitchatPacket, from peerID: PeerID) {
+        let env = environment
+        guard let recipientID = PeerID(hexData: packet.recipientID) else {
+            SecureLogger.warning("⚠️ Encrypted message has no recipient ID", category: .session)
+            return
+        }
+
+        if recipientID != env.localPeerID() {
+            SecureLogger.debug("🔐 Encrypted message not for me (for \(recipientID.id.prefix(8))…, I am \(env.localPeerID().id.prefix(8))…)", category: .session)
+            return
+        }
+
+        // Update lastSeen for the peer we received from (important for private messages)
+        env.updatePeerLastSeen(peerID)
+
+        do {
+            let decrypted = try env.decrypt(packet.payload, peerID)
+            guard decrypted.count > 0 else { return }
+
+            // First byte indicates the payload type
+            let payloadType = decrypted[0]
+            let payloadData = decrypted.dropFirst()
+
+            guard let noisePayloadType = NoisePayloadType(rawValue: payloadType) else {
+                SecureLogger.warning("⚠️ Unknown noise payload type: \(payloadType)")
+                return
+            }
+
+            SecureLogger.debug("🔐 Decrypted noise payload type \(noisePayloadType.description) from \(peerID.id.prefix(8))…", category: .session)
+
+            let ts = Date(timeIntervalSince1970: Double(packet.timestamp) / 1000)
+            env.deliverNoisePayload(peerID, noisePayloadType, Data(payloadData), ts)
+        } catch NoiseEncryptionError.sessionNotEstablished {
+            // We received an encrypted message before establishing a session with this peer.
+            // Trigger a handshake so future messages can be decrypted.
+            SecureLogger.debug("🔑 Encrypted message from \(peerID.id.prefix(8))… without session; initiating handshake")
+            if !env.hasNoiseSession(peerID) {
+                env.initiateHandshake(peerID)
+            }
+        } catch {
+            // Decryption failed - clear the corrupted session and re-initiate handshake
+            // This handles cases where session state got out of sync (nonce mismatch, etc.)
+            SecureLogger.error("❌ Failed to decrypt message from \(peerID.id.prefix(8))…: \(error) - clearing session and re-initiating handshake")
+            env.clearSession(peerID)
+            env.initiateHandshake(peerID)
+        }
+    }
+}

bitchat/Services/BLE/BLEOutboundFragmentTransferScheduler.swift

@@ -7,11 +7,54 @@ struct BLEOutboundFragmentTransferRequest {
     let maxChunk: Int?
     let directedPeer: PeerID?
     let transferId: String?
+    let requireDirectPeerLink: Bool
+    let requireNoiseAuthenticatedPeerLink: Bool
+
+    init(
+        packet: BitchatPacket,
+        pad: Bool,
+        maxChunk: Int?,
+        directedPeer: PeerID?,
+        transferId: String?,
+        requireDirectPeerLink: Bool = false,
+        requireNoiseAuthenticatedPeerLink: Bool = false
+    ) {
+        self.packet = packet
+        self.pad = pad
+        self.maxChunk = maxChunk
+        self.directedPeer = directedPeer
+        self.transferId = transferId
+        self.requireDirectPeerLink = requireDirectPeerLink
+        self.requireNoiseAuthenticatedPeerLink = requireNoiseAuthenticatedPeerLink
+    }
 
     var resolvedTransferId: String? {
         guard packet.type == MessageType.fileTransfer.rawValue else { return nil }
         return transferId ?? packet.payload.sha256Hex()
     }
+
+    /// Content identity independent of the caller-chosen transfer ID: the
+    /// same file resent through another path (gossip-sync replay, retry)
+    /// arrives with a different explicit transferId but identical payload.
+    var contentKey: String? {
+        guard packet.type == MessageType.fileTransfer.rawValue else { return nil }
+        return packet.payload.sha256Hex()
+    }
+}
+
+/// Transactional admission for strict fragment trains. Durable callers may
+/// commit only when every fragment was accepted; the first rejection stops
+/// the train and reports failure so the original remains retryable.
+enum BLEStrictFragmentAdmission {
+    static func admitAll<Fragment>(
+        _ fragments: [Fragment],
+        accepting: (Fragment) -> Bool
+    ) -> Bool {
+        for fragment in fragments where !accepting(fragment) {
+            return false
+        }
+        return true
+    }
 }
 
 struct BLEOutboundFragmentTransferScheduler {
@@ -23,6 +66,16 @@ struct BLEOutboundFragmentTransferScheduler {
     enum SubmitResult {
         case start(request: BLEOutboundFragmentTransferRequest, reservedTransferId: String?)
         case queued(request: BLEOutboundFragmentTransferRequest, transferId: String?, position: QueuePosition)
+        /// Strict direct-link requests are transactional: returning false to
+        /// their durable owner must mean no process-local copy remains that
+        /// can transmit later. They are therefore start-or-reject, never
+        /// admitted to `pendingTransfers`.
+        case rejectedStrict(request: BLEOutboundFragmentTransferRequest, transferId: String?)
+        /// The same file is already being (or waiting to be) fragmented out
+        /// to an audience covering this request; sending it again would just
+        /// double the airtime (field-verified: one 41KB voice file went out
+        /// as two complete fragment streams).
+        case droppedDuplicate(request: BLEOutboundFragmentTransferRequest, activeTransferId: String?)
     }
 
     enum CancelResult {
@@ -38,14 +91,34 @@ struct BLEOutboundFragmentTransferScheduler {
     }
 
     private struct ActiveTransferState {
-        let totalFragments: Int
+        var totalFragments: Int
         var sentFragments: Int
         var workItems: [DispatchWorkItem]
+        var contentKey: String?
+        var directedPeer: PeerID?
     }
 
     private var activeTransfers: [String: ActiveTransferState] = [:]
     private var pendingTransfers: [BLEOutboundFragmentTransferRequest] = []
 
+    /// A transfer of the same content whose audience covers `directedPeer`:
+    /// a broadcast covers every peer; a directed transfer covers only its
+    /// recipient. A directed resend to a peer NOT covered by what's in
+    /// flight (different recipient of a private file) is never a duplicate.
+    private func coveringDuplicate(contentKey: String, directedPeer: PeerID?) -> String? {
+        for (transferId, state) in activeTransfers where state.contentKey == contentKey {
+            if state.directedPeer == nil || state.directedPeer == directedPeer {
+                return transferId
+            }
+        }
+        for request in pendingTransfers where request.contentKey == contentKey {
+            if request.directedPeer == nil || request.directedPeer == directedPeer {
+                return request.resolvedTransferId
+            }
+        }
+        return nil
+    }
+
     var activeCount: Int {
         activeTransfers.count
     }
@@ -69,17 +142,39 @@ struct BLEOutboundFragmentTransferScheduler {
             return .start(request: request, reservedTransferId: nil)
         }
 
+        // Only requests without an explicit transferId are dropped as
+        // duplicates: those are resend paths (gossip-sync replay, directed
+        // spool) with no UI waiting on them. An app-initiated send carries a
+        // transferId whose progress events the UI tracks, so it always runs.
+        if request.transferId == nil,
+           let contentKey = request.contentKey,
+           let coveringId = coveringDuplicate(contentKey: contentKey, directedPeer: request.directedPeer) {
+            return .droppedDuplicate(request: request, activeTransferId: coveringId)
+        }
+
         guard activeTransfers.count < maxConcurrentTransfers else {
+            if request.requireDirectPeerLink {
+                return .rejectedStrict(request: request, transferId: transferId)
+            }
             pendingTransfers.append(request)
             return .queued(request: request, transferId: transferId, position: .back)
         }
 
         guard activeTransfers[transferId] == nil else {
+            if request.requireDirectPeerLink {
+                return .rejectedStrict(request: request, transferId: transferId)
+            }
             pendingTransfers.insert(request, at: 0)
             return .queued(request: request, transferId: transferId, position: .front)
         }
 
-        activeTransfers[transferId] = ActiveTransferState(totalFragments: 0, sentFragments: 0, workItems: [])
+        activeTransfers[transferId] = ActiveTransferState(
+            totalFragments: 0,
+            sentFragments: 0,
+            workItems: [],
+            contentKey: request.contentKey,
+            directedPeer: request.directedPeer
+        )
         return .start(request: request, reservedTransferId: transferId)
     }
 
@@ -88,12 +183,11 @@ struct BLEOutboundFragmentTransferScheduler {
         totalFragments: Int,
         workItems: [DispatchWorkItem]
     ) -> Bool {
-        guard activeTransfers[transferId] != nil else { return false }
+        guard var state = activeTransfers[transferId] else { return false }
-        activeTransfers[transferId] = ActiveTransferState(
+        state.totalFragments = totalFragments
-            totalFragments: totalFragments,
+        state.sentFragments = 0
-            sentFragments: 0,
+        state.workItems = workItems
-            workItems: workItems
+        activeTransfers[transferId] = state
-        )
         return true
     }
 
@@ -149,13 +243,25 @@ struct BLEOutboundFragmentTransferScheduler {
 
         while availableSlots > 0, !pendingTransfers.isEmpty {
             let request = pendingTransfers.removeFirst()
-            availableSlots -= 1
 
             guard let transferId = request.resolvedTransferId else {
+                availableSlots -= 1
                 results.append(.start(request: request, reservedTransferId: nil))
                 continue
             }
 
+            // A queued duplicate of content that started while it waited
+            // must not resend the whole file once the slot frees up (same
+            // explicit-transferId exemption as submit).
+            if request.transferId == nil,
+               let contentKey = request.contentKey,
+               let coveringId = coveringDuplicate(contentKey: contentKey, directedPeer: request.directedPeer) {
+                results.append(.droppedDuplicate(request: request, activeTransferId: coveringId))
+                continue
+            }
+
+            availableSlots -= 1
+
             guard activeTransfers.count < maxConcurrentTransfers else {
                 pendingTransfers.insert(request, at: 0)
                 results.append(.queued(request: request, transferId: transferId, position: .front))
@@ -168,7 +274,13 @@ struct BLEOutboundFragmentTransferScheduler {
                 continue
             }
 
-            activeTransfers[transferId] = ActiveTransferState(totalFragments: 0, sentFragments: 0, workItems: [])
+            activeTransfers[transferId] = ActiveTransferState(
+                totalFragments: 0,
+                sentFragments: 0,
+                workItems: [],
+                contentKey: request.contentKey,
+                directedPeer: request.directedPeer
+            )
             results.append(.start(request: request, reservedTransferId: transferId))
         }
 

bitchat/Services/BLE/BLEOutboundLinkPlanner.swift

@@ -18,32 +18,55 @@ enum BLEOutboundLinkPlanner {
         centralNotifyLimits: [Int],
         ingressRecord: BLEIngressLinkRecord?,
         excludedLinks: Set<BLEIngressLinkID>,
-        directedOnlyPeer: PeerID?
+        peripheralPeerBindings: [String: PeerID] = [:],
+        centralPeerBindings: [String: PeerID] = [:],
+        preferredPeripheralPerPeer: [PeerID: String] = [:],
+        directAnnounceTTL: UInt8 = TransportConfig.messageTTLDefault,
+        directedOnlyPeer: PeerID?,
+        requireDirectPeerLink: Bool = false
     ) -> BLEOutboundLinkPlan {
-        if let minLimit = minimumLinkLimit(
-            peripheralWriteLimits: peripheralWriteLimits,
-            centralNotifyLimits: centralNotifyLimits
-        ), packet.type != MessageType.fragment.rawValue,
-           dataCount > minLimit {
-            return BLEOutboundLinkPlan(
-                directedPeerHint: directedPeerHint(for: packet, explicitPeer: directedOnlyPeer),
-                fragmentChunkSize: BLEOutboundPacketPolicy.fragmentChunkSize(forLinkLimit: minLimit),
-                selectedLinks: BLEFanoutSelection(peripheralIDs: [], centralIDs: []),
-                shouldSpoolDirectedPacket: false
-            )
-        }
-
         let directedPeerHint = directedPeerHint(for: packet, explicitPeer: directedOnlyPeer)
+        // Direct announces bypass the per-peer duplicate-link collapse so
+        // every live link gets bound (see BLEFanoutSelector.selectLinks).
+        let isDirectAnnounce = packet.type == MessageType.announce.rawValue && packet.ttl == directAnnounceTTL
         let selectedLinks = BLEFanoutSelector.selectLinks(
             peripheralIDs: peripheralIDs,
             centralIDs: centralIDs,
             ingressLink: ingressRecord?.link,
             excludedLinks: excludedLinks,
+            peripheralPeerBindings: peripheralPeerBindings,
+            centralPeerBindings: centralPeerBindings,
+            preferredPeripheralPerPeer: preferredPeripheralPerPeer,
+            collapseDuplicatePeerLinks: !isDirectAnnounce,
             directedPeerHint: directedPeerHint,
+            requireDirectPeerLink: requireDirectPeerLink,
             packetType: packet.type,
             messageID: BLEOutboundPacketPolicy.messageID(for: packet)
         )
 
+        // Fragment only for links that this packet can actually use. Looking
+        // at every connected link before directed-peer selection lets an
+        // unrelated peer's MTU make an oversized directed send look routable,
+        // even though every resulting fragment will select zero target links.
+        let selectedPeripheralLimits = zip(peripheralIDs, peripheralWriteLimits).compactMap { id, limit in
+            selectedLinks.peripheralIDs.contains(id) ? limit : nil
+        }
+        let selectedCentralLimits = zip(centralIDs, centralNotifyLimits).compactMap { id, limit in
+            selectedLinks.centralIDs.contains(id) ? limit : nil
+        }
+        if let minLimit = minimumLinkLimit(
+            peripheralWriteLimits: selectedPeripheralLimits,
+            centralNotifyLimits: selectedCentralLimits
+        ), packet.type != MessageType.fragment.rawValue,
+           dataCount > minLimit {
+            return BLEOutboundLinkPlan(
+                directedPeerHint: directedPeerHint,
+                fragmentChunkSize: BLEOutboundPacketPolicy.fragmentChunkSize(forLinkLimit: minLimit),
+                selectedLinks: selectedLinks,
+                shouldSpoolDirectedPacket: false
+            )
+        }
+
         return BLEOutboundLinkPlan(
             directedPeerHint: directedPeerHint,
             fragmentChunkSize: nil,