Expand store-and-forward: open couriers, spray-and-wait, persistent outbox, 6h public history (#1372)

Store-and-forward previously delivered to an out-of-range peer only if a
mutual favorite happened to be connected at send time and later met the
recipient directly, and everything except courier envelopes died with the
app process. This closes those gaps end to end:

- Persist the MessageRouter outbox to disk, sealed with a ChaChaPoly key
  held only in the Keychain (no plaintext at rest); queued private
  messages now survive an app kill and flush on next launch.
- Deposit retry: queued messages are re-deposited whenever a new eligible
  courier connects, tracked per message so the same courier is never
  double-burned, until 3 distinct couriers carry it or it expires.
- Tiered open couriering: signature-verified strangers can now carry mail
  (2 envelopes/depositor into a 20-slot pool) alongside mutual favorites
  (5 each); overflow evicts verified-tier mail before favorites'.
- Spray-and-wait: envelopes carry a copy budget (4, capped 8, new TLV,
  wire-compatible with old clients); couriers split half their remaining
  budget with each newly encountered courier so mail diffuses through a
  moving crowd.
- Remote handover: a verified relayed announce now floods a copy toward
  the multi-hop recipient (directed-relay treatment, 10-min per-envelope
  cooldown) while the carried original stays put for a direct encounter.
- Public history: gossip-sync window for whole public messages widened
  from 15 min to 6 h, matched on the receive-acceptance side, and the
  message store persists to disk so devices bridge partitions and
  restarts ("town crier").
- Privacy-safe local delivery counters (bare tallies, log-only) so the
  store-and-forward stack is measurable on-device.
- Panic wipe now also clears the sealed outbox, gossip archive, and
  counters.
- Rewrite WHITEPAPER.md to describe the app as implemented (Noise XX/X,
  actual flood control, courier system, gossip sync, Nostr path); the old
  document described a bloom filter, three fragment types, and a
  MessageRetryService that don't exist.

1037 macOS tests pass (17 new); iOS builds.

Co-authored-by: jack <jackjackbits@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

localPackages/BitFoundation/Sources/BitFoundation/CourierEnvelope.swift

@@ -24,23 +24,37 @@ public struct CourierEnvelope: Equatable {
     public let expiry: UInt64
     /// Opaque one-way Noise X ciphertext (sender identity rides inside).
     public let ciphertext: Data
+    /// Spray-and-wait copy budget: how many redundant copies of this envelope
+    /// the holder may still hand to other couriers (binary split on each
+    /// spray). 1 means carry-only — deliver to the recipient, never re-spray.
+    public let copies: UInt8
 
     public static let tagLength = 16
     /// Couriered messages are text-sized; media transfers are out of scope.
     public static let maxCiphertextBytes = 16 * 1024
     /// Matches the outbox retention policy in MessageRouter.
     public static let maxLifetimeSeconds: TimeInterval = 24 * 60 * 60
+    /// Cap on the copy budget a depositor can claim, so a malicious envelope
+    /// cannot turn the courier network into an amplifier.
+    public static let maxCopies: UInt8 = 8
 
     private enum TLVType: UInt8 {
         case recipientTag = 0x01
         case expiry = 0x02
         case ciphertext = 0x03
+        case copies = 0x04
     }
 
-    public init(recipientTag: Data, expiry: UInt64, ciphertext: Data) {
+    public init(recipientTag: Data, expiry: UInt64, ciphertext: Data, copies: UInt8 = 1) {
         self.recipientTag = recipientTag
         self.expiry = expiry
         self.ciphertext = ciphertext
+        self.copies = min(max(copies, 1), Self.maxCopies)
+    }
+
+    /// The same envelope with a different remaining copy budget.
+    public func withCopies(_ copies: UInt8) -> CourierEnvelope {
+        CourierEnvelope(recipientTag: recipientTag, expiry: expiry, ciphertext: ciphertext, copies: copies)
     }
 
     public var isExpired: Bool {
@@ -75,6 +89,14 @@ public struct CourierEnvelope: Equatable {
         appendBE(UInt16(ciphertext.count), into: &encoded)
         encoded.append(ciphertext)
 
+        // Omitted when 1 so carry-only envelopes stay byte-identical to the
+        // pre-spray wire format (old clients skip the TLV as unknown anyway).
+        if copies > 1 {
+            encoded.append(TLVType.copies.rawValue)
+            appendBE(UInt16(1), into: &encoded)
+            encoded.append(copies)
+        }
+
         return encoded
     }
 
@@ -85,6 +107,7 @@ public struct CourierEnvelope: Equatable {
         var recipientTag: Data?
         var expiry: UInt64?
         var ciphertext: Data?
+        var copies: UInt8 = 1
 
         while cursor < end {
             let typeRaw = data[cursor]
@@ -107,6 +130,9 @@ public struct CourierEnvelope: Equatable {
             case .ciphertext:
                 guard length > 0, length <= maxCiphertextBytes else { return nil }
                 ciphertext = Data(value)
+            case .copies:
+                guard length == 1 else { return nil }
+                copies = value.first ?? 1
             case nil:
                 // Unknown TLV: skip for forward compatibility.
                 continue
@@ -114,7 +140,7 @@ public struct CourierEnvelope: Equatable {
         }
 
         guard let recipientTag, let expiry, let ciphertext else { return nil }
-        return CourierEnvelope(recipientTag: recipientTag, expiry: expiry, ciphertext: ciphertext)
+        return CourierEnvelope(recipientTag: recipientTag, expiry: expiry, ciphertext: ciphertext, copies: copies)
     }
 
     // MARK: - Recipient Tags

localPackages/BitFoundation/Tests/BitFoundationTests/CourierEnvelopeTests.swift

@@ -20,6 +20,38 @@ struct CourierEnvelopeTests {
         CourierEnvelope(recipientTag: tag, expiry: expiry, ciphertext: ciphertext)
     }
 
+    // MARK: - Spray copies
+
+    @Test func copiesRoundTrip() throws {
+        let envelope = makeEnvelope().withCopies(4)
+        let encoded = try #require(envelope.encode())
+        let decoded = try #require(CourierEnvelope.decode(encoded))
+        #expect(decoded.copies == 4)
+        #expect(decoded == envelope)
+    }
+
+    @Test func carryOnlyEnvelopeEncodesIdenticallyToLegacyFormat() throws {
+        // copies == 1 must be byte-identical to the pre-spray wire format so
+        // old and new clients dedup the same envelope the same way.
+        let envelope = makeEnvelope()
+        #expect(envelope.copies == 1)
+        let encoded = try #require(envelope.encode())
+        let withExplicitOne = try #require(envelope.withCopies(1).encode())
+        #expect(encoded == withExplicitOne)
+        #expect(!encoded.contains(0x04) || CourierEnvelope.decode(encoded)?.copies == 1)
+    }
+
+    @Test func decodeWithoutCopiesTLVDefaultsToCarryOnly() throws {
+        let encoded = try #require(makeEnvelope().encode())
+        let decoded = try #require(CourierEnvelope.decode(encoded))
+        #expect(decoded.copies == 1)
+    }
+
+    @Test func copiesAreClampedToPolicyBounds() {
+        #expect(makeEnvelope().withCopies(0).copies == 1)
+        #expect(makeEnvelope().withCopies(200).copies == CourierEnvelope.maxCopies)
+    }
+
     // MARK: - Codec
 
     @Test func roundTrip() throws {