Move additional files/tests to BitFoundation (#1102)

localPackages/BitFoundation/Tests/BitFoundationTests/BinaryProtocolPaddingTests.swift

@@ -0,0 +1,33 @@
+//
+// BinaryProtocolPaddingTests.swift
+// bitchatTests
+//
+// This is free and unencumbered software released into the public domain.
+//
+
+import Testing
+@testable import BitFoundation
+
+struct BinaryProtocolPaddingTests {
+    @Test func padded_vs_unpadded_length() throws {
+        // Use helper to create a small test packet
+        let packet = TestHelpers.createTestPacket()
+        let padded = try #require(BinaryProtocol.encode(packet, padding: true), "encode padded")
+        let unpadded = try #require(BinaryProtocol.encode(packet, padding: false), "encode unpadded")
+        #expect(padded.count >= unpadded.count, "Padded frame should be >= unpadded")
+    }
+
+    @Test func decode_padded_and_unpadded_round_trip() throws {
+        let packet = TestHelpers.createTestPacket()
+
+        let padded = try #require(BinaryProtocol.encode(packet, padding: true), "encode padded")
+        let dec1 = try #require(BinaryProtocol.decode(padded), "decode padded")
+        #expect(dec1.type == packet.type)
+        #expect(dec1.payload == packet.payload)
+
+        let unpadded = try #require(BinaryProtocol.encode(packet, padding: false), "encode unpadded")
+        let dec2 = try #require(BinaryProtocol.decode(unpadded), "decode unpadded")
+        #expect(dec2.type == packet.type)
+        #expect(dec2.payload == packet.payload)
+    }
+}

localPackages/BitFoundation/Tests/BitFoundationTests/BinaryProtocolTests.swift

@@ -0,0 +1,817 @@
+//
+// BinaryProtocolTests.swift
+// bitchatTests
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import Testing
+import Foundation
+@testable import BitFoundation
+
+struct BinaryProtocolTests {
+    
+    // MARK: - Basic Encoding/Decoding Tests
+    
+    @Test func basicPacketEncodingDecoding() throws {
+        let originalPacket = TestHelpers.createTestPacket()
+        
+        let encodedData = try #require(BinaryProtocol.encode(originalPacket), "Failed to encode packet")
+        let decodedPacket = try #require(BinaryProtocol.decode(encodedData), "Failed to decode packet")
+        
+        // Verify
+        #expect(decodedPacket.type == originalPacket.type)
+        #expect(decodedPacket.ttl == originalPacket.ttl)
+        #expect(decodedPacket.timestamp == originalPacket.timestamp)
+        #expect(decodedPacket.payload == originalPacket.payload)
+        
+        // Sender ID should match (accounting for padding)
+        let originalSenderID = originalPacket.senderID.prefix(BinaryProtocol.senderIDSize)
+        let decodedSenderID = decodedPacket.senderID.trimmingNullBytes()
+        #expect(decodedSenderID == originalSenderID)
+    }
+
+    @Test func trimmingNullBytesReturnsOriginalDataWhenNoNullsPresent() {
+        let raw = Data([0x41, 0x42, 0x43])
+        #expect(raw.trimmingNullBytes() == raw)
+    }
+    
+    @Test func packetWithRecipient() throws {
+        let recipientID = PeerID(str: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789")
+        let packet = TestHelpers.createTestPacket(recipientID: recipientID)
+        let encodedData = try #require(BinaryProtocol.encode(packet), "Failed to encode packet with recipient")
+        let decodedPacket = try #require(BinaryProtocol.decode(encodedData), "Failed to decode packet with recipient")
+        
+        // Verify recipient
+        #expect(decodedPacket.recipientID != nil)
+        let decodedRecipientID = decodedPacket.recipientID?.trimmingNullBytes()
+        // TODO: Check if this is intended that the decoding only gets the first 8
+        #expect(String(data: decodedRecipientID!, encoding: .utf8) == "abcdef01")
+    }
+    
+    @Test func packetWithSignature() throws {
+        let packet = TestHelpers.createTestPacket(signature: TestConstants.testSignature)
+        let encodedData = try #require(BinaryProtocol.encode(packet), "Failed to encode packet with signature")
+        let decodedPacket = try #require(BinaryProtocol.decode(encodedData), "Failed to decode packet with signature")
+        
+        // Verify signature
+        #expect(decodedPacket.signature != nil)
+        #expect(decodedPacket.signature == TestConstants.testSignature)
+    }
+
+    // MARK: - Source-Based Routing Tests (v2 only)
+    
+    @Test func packetWithRouteRoundTrip() throws {
+        let route: [Data] = [
+            try #require(Data(hexString: "0102030405060708")),
+            try #require(Data(hexString: "1112131415161718")),
+            try #require(Data(hexString: "2122232425262728"))
+        ]
+
+        // Route is only supported for v2+ packets
+        var packet = BitchatPacket(
+            type: 0x01,
+            senderID: route[0],
+            recipientID: route.last,
+            timestamp: 1_720_000_000_000,
+            payload: Data("route-test".utf8),
+            signature: nil,
+            ttl: 6,
+            version: 2
+        )
+        packet.route = route
+
+        let encoded = try #require(BinaryProtocol.encode(packet), "Failed to encode packet with route")
+        let flagsByte = encoded[BinaryProtocol.Offsets.flags]
+        #expect((flagsByte & BinaryProtocol.Flags.hasRoute) != 0)
+
+        let decoded = try #require(BinaryProtocol.decode(encoded), "Failed to decode packet with route")
+        #expect(decoded.version == 2)
+        let decodedRoute = try #require(decoded.route)
+        #expect(decodedRoute.count == route.count)
+        for (expected, actual) in zip(route, decodedRoute) {
+            #expect(actual == expected)
+        }
+    }
+
+    @Test func packetWithRoutePadsShortHop() throws {
+        let sender = try #require(Data(hexString: "0011223344556677"))
+        let destination = try #require(Data(hexString: "8899aabbccddeeff"))
+        let shortHop = Data([0xAA, 0xBB, 0xCC])
+
+        // Route is only supported for v2+ packets
+        var packet = BitchatPacket(
+            type: 0x02,
+            senderID: sender,
+            recipientID: destination,
+            timestamp: 1_730_000_000_000,
+            payload: Data("pad-test".utf8),
+            signature: nil,
+            ttl: 5,
+            version: 2
+        )
+        packet.route = [shortHop, destination]
+
+        let encoded = try #require(BinaryProtocol.encode(packet), "Failed to encode packet with short hop route")
+        let decoded = try #require(BinaryProtocol.decode(encoded), "Failed to decode packet with short hop route")
+        let decodedRoute = try #require(decoded.route)
+        let firstHop = try #require(decodedRoute.first)
+        #expect(firstHop.count == BinaryProtocol.senderIDSize)
+        #expect(firstHop.prefix(shortHop.count) == shortHop)
+        let paddingBytes = firstHop.suffix(firstHop.count - shortHop.count)
+        #expect(paddingBytes.allSatisfy { $0 == 0 })
+    }
+
+    @Test func packetWithRouteAndCompressedPayload() throws {
+        let route: [Data] = [
+            try #require(Data(hexString: "0101010101010101")),
+            try #require(Data(hexString: "0202020202020202"))
+        ]
+        let repeatedString = String(repeating: "compress-me", count: 150)
+        // Route is only supported for v2+ packets
+        var packet = BitchatPacket(
+            type: 0x03,
+            senderID: route[0],
+            recipientID: route.last,
+            timestamp: 1_740_000_000_000,
+            payload: Data(repeatedString.utf8),
+            signature: nil,
+            ttl: 7,
+            version: 2
+        )
+        packet.route = route
+
+        let encoded = try #require(BinaryProtocol.encode(packet), "Failed to encode packet with route and compression")
+        let decoded = try #require(BinaryProtocol.decode(encoded), "Failed to decode packet with route and compression")
+        #expect(decoded.payload == Data(repeatedString.utf8))
+        let decodedRoute = try #require(decoded.route)
+        #expect(decodedRoute == route)
+    }
+    
+    @Test func v1PacketIgnoresRouteOnEncode() throws {
+        // v1 packets should NOT include route even if route is set on the packet object
+        let route: [Data] = [
+            try #require(Data(hexString: "0102030405060708")),
+            try #require(Data(hexString: "1112131415161718"))
+        ]
+        
+        var packet = BitchatPacket(
+            type: 0x01,
+            senderID: route[0],
+            recipientID: route.last,
+            timestamp: 1_720_000_000_000,
+            payload: Data("v1-no-route".utf8),
+            signature: nil,
+            ttl: 6
+            // version defaults to 1 (v1 packet)
+        )
+        packet.route = route  // route is set but should be ignored for v1
+        
+        let encoded = try #require(BinaryProtocol.encode(packet), "Failed to encode v1 packet")
+        
+        // HAS_ROUTE flag should NOT be set for v1 packets
+        let flagsByte = encoded[BinaryProtocol.Offsets.flags]
+        #expect((flagsByte & BinaryProtocol.Flags.hasRoute) == 0, "v1 packet should not have HAS_ROUTE flag set")
+        
+        // Decoded packet should have no route
+        let decoded = try #require(BinaryProtocol.decode(encoded), "Failed to decode v1 packet")
+        #expect(decoded.version == 1)
+        #expect(decoded.route == nil, "v1 packet should decode with nil route")
+        #expect(decoded.payload == Data("v1-no-route".utf8))
+    }
+    
+    @Test func v2PacketIncludesRouteOnEncode() throws {
+        // v2 packets SHOULD include route when route is set
+        let route: [Data] = [
+            try #require(Data(hexString: "0102030405060708")),
+            try #require(Data(hexString: "1112131415161718"))
+        ]
+        
+        var packet = BitchatPacket(
+            type: 0x01,
+            senderID: route[0],
+            recipientID: route.last,
+            timestamp: 1_720_000_000_000,
+            payload: Data("v2-with-route".utf8),
+            signature: nil,
+            ttl: 6,
+            version: 2
+        )
+        packet.route = route
+        
+        let encoded = try #require(BinaryProtocol.encode(packet), "Failed to encode v2 packet")
+        
+        // HAS_ROUTE flag SHOULD be set for v2 packets with route
+        let flagsByte = encoded[BinaryProtocol.Offsets.flags]
+        #expect((flagsByte & BinaryProtocol.Flags.hasRoute) != 0, "v2 packet should have HAS_ROUTE flag set")
+        
+        // Decoded packet should have route
+        let decoded = try #require(BinaryProtocol.decode(encoded), "Failed to decode v2 packet")
+        #expect(decoded.version == 2)
+        let decodedRoute = try #require(decoded.route, "v2 packet should decode with route")
+        #expect(decodedRoute.count == route.count)
+        #expect(decoded.payload == Data("v2-with-route".utf8))
+    }
+    
+    @Test func v2PacketWithoutRouteDecodesCorrectly() throws {
+        // v2 packet without route should still work
+        let sender = try #require(Data(hexString: "0011223344556677"))
+        let recipient = try #require(Data(hexString: "8899aabbccddeeff"))
+        
+        let packet = BitchatPacket(
+            type: 0x02,
+            senderID: sender,
+            recipientID: recipient,
+            timestamp: 1_750_000_000_000,
+            payload: Data("v2-no-route".utf8),
+            signature: nil,
+            ttl: 5,
+            version: 2
+        )
+        // route is nil by default
+        
+        let encoded = try #require(BinaryProtocol.encode(packet), "Failed to encode v2 packet without route")
+        
+        // HAS_ROUTE flag should NOT be set when no route
+        let flagsByte = encoded[BinaryProtocol.Offsets.flags]
+        #expect((flagsByte & BinaryProtocol.Flags.hasRoute) == 0, "v2 packet without route should not have HAS_ROUTE flag")
+        
+        let decoded = try #require(BinaryProtocol.decode(encoded), "Failed to decode v2 packet without route")
+        #expect(decoded.version == 2)
+        #expect(decoded.route == nil)
+        #expect(decoded.payload == Data("v2-no-route".utf8))
+    }
+    
+    @Test func v1AndV2PayloadLengthDifference() throws {
+        // Verify that payloadLength does NOT include route bytes
+        // by comparing encoded sizes
+        let route: [Data] = [
+            try #require(Data(hexString: "0102030405060708"))
+        ]
+        let payloadData = Data("test-payload".utf8)
+        
+        // v1 packet (route ignored)
+        var v1Packet = BitchatPacket(
+            type: 0x01,
+            senderID: route[0],
+            recipientID: nil,
+            timestamp: 1_720_000_000_000,
+            payload: payloadData,
+            signature: nil,
+            ttl: 6
+            // version defaults to 1
+        )
+        v1Packet.route = route  // will be ignored for v1
+        
+        // v2 packet with same payload but route included
+        var v2Packet = BitchatPacket(
+            type: 0x01,
+            senderID: route[0],
+            recipientID: nil,
+            timestamp: 1_720_000_000_000,
+            payload: payloadData,
+            signature: nil,
+            ttl: 6,
+            version: 2
+        )
+        v2Packet.route = route
+        
+        let v1Encoded = try #require(BinaryProtocol.encode(v1Packet, padding: false))
+        let v2Encoded = try #require(BinaryProtocol.encode(v2Packet, padding: false))
+        
+        // v2 should be larger by: 2 bytes (header length field difference) + 1 byte (route count) + 8 bytes (one hop)
+        // Header: v1=14, v2=16 -> +2 bytes
+        // Route: 1 + 8 = 9 bytes
+        // Total expected difference: 11 bytes
+        let expectedDiff = 2 + 1 + 8  // header diff + route count + one hop
+        #expect(v2Encoded.count - v1Encoded.count == expectedDiff, 
+                "v2 packet should be \(expectedDiff) bytes larger than v1 (actual diff: \(v2Encoded.count - v1Encoded.count))")
+    }
+    
+    // MARK: - Compression Tests
+    
+    @Test("Create a large, compressible payload above current threshold (2048B)")
+    func payloadCompression() throws {
+        let repeatedString = String(repeating: "This is a test message. ", count: 200)
+        let largePayload = repeatedString.data(using: .utf8)!
+        
+        let packet = TestHelpers.createTestPacket(payload: largePayload)
+        
+        // Encode (should compress)
+        let encodedData = try #require(BinaryProtocol.encode(packet), "Failed to encode packet with large payload")
+        
+        // The encoded size should be smaller than uncompressed due to compression
+        let headerSize = try #require(BinaryProtocol.headerSize(for: packet.version), "Invalid packet version")
+        let uncompressedSize = headerSize + BinaryProtocol.senderIDSize + largePayload.count
+        #expect(encodedData.count < uncompressedSize, "Compressed packet should be smaller than uncompressed form")
+        
+        // Decode and verify
+        let decodedPacket = try #require(BinaryProtocol.decode(encodedData), "Failed to decode compressed packet")
+        
+        #expect(decodedPacket.payload == largePayload)
+    }
+    
+    @Test("Small payloads should not be compressed")
+    func smallPayloadNoCompression() throws {
+        let smallPayload = "Hi".data(using: .utf8)!
+        let packet = TestHelpers.createTestPacket(payload: smallPayload)
+        let encodedData = try #require(BinaryProtocol.encode(packet), "Failed to encode small packet")
+        let decodedPacket = try #require(BinaryProtocol.decode(encodedData), "Failed to decode small packet")
+        #expect(decodedPacket.payload == smallPayload)
+    }
+
+    @Test("Reject payloads larger than the framed file cap")
+    func oversizedPayloadIsRejected() throws {
+        let targetSize = FileTransferLimits.maxFramedFileBytes + 1
+        var oversized = Data()
+        oversized.reserveCapacity(targetSize)
+        let byteRun = Data((0...255).map { UInt8($0) })
+        while oversized.count < targetSize {
+            let remaining = targetSize - oversized.count
+            if remaining >= byteRun.count {
+                oversized.append(byteRun)
+            } else {
+                oversized.append(byteRun.prefix(remaining))
+            }
+        }
+        let packet = BitchatPacket(
+            type: MessageType.message.rawValue,
+            senderID: Data(hexString: "0011223344556677") ?? Data(),
+            recipientID: nil,
+            timestamp: UInt64(Date().timeIntervalSince1970 * 1000),
+            payload: oversized,
+            signature: nil,
+            ttl: 1,
+            version: 2
+        )
+        let encoded = try #require(BinaryProtocol.encode(packet), "Failed to encode oversized packet")
+        #expect(BinaryProtocol.decode(encoded) == nil)
+    }
+    
+    // MARK: - Message Padding Tests
+    
+    @Test func messagePadding() throws {
+        let payloads = [
+            "Short",
+            String(repeating: "Medium length message content ", count: 10), // ~300 bytes  
+            String(repeating: "Long message content that should exceed the 512 byte limit ", count: 20), // ~1200+ bytes
+            String(repeating: "Very long message content that should definitely exceed the 2048 byte limit for sure ", count: 30) // ~2700+ bytes
+        ]
+        
+        var encodedSizes = Set<Int>()
+        
+        for payload in payloads {
+            let packet = TestHelpers.createTestPacket(payload: payload.data(using: .utf8)!)
+            let encodedData = try #require(BinaryProtocol.encode(packet), "Failed to encode packet")
+            
+            // Verify padding creates standard block sizes up to configured limit (no 4096 bucket currently)
+            let blockSizes = [256, 512, 1024, 2048]
+            if encodedData.count <= 2048 {
+                #expect(blockSizes.contains(encodedData.count), "Encoded size \(encodedData.count) is not a standard block size")
+            } else {
+                // For very large payloads we expect no additional padding beyond raw size
+                #expect(encodedData.count > 2048)
+            }
+            
+            encodedSizes.insert(encodedData.count)
+            
+            // Verify decoding works
+            let decodedPacket = try #require(BinaryProtocol.decode(encodedData), "Failed to decode padded packet")
+            #expect(String(data: decodedPacket.payload, encoding: .utf8) == payload)
+        }
+        
+        // Different payload sizes (within <=2048) may map to the same bucket depending on compression.
+        // Require at least one padded size to be present.
+        #expect(encodedSizes.filter { $0 <= 2048 }.count >= 1, "Expected at least one padded size up to 2048, got \(encodedSizes)")
+    }
+
+    @Test func invalidPKCS7PaddingIsRejected() throws {
+        let pkt = TestHelpers.createTestPacket(payload: Data(repeating: 0x41, count: 50)) // small
+        let enc0 = try #require(BinaryProtocol.encode(pkt), "encode failed")
+        // Force padding to known block for test stability
+        var enc = MessagePadding.pad(enc0, toSize: 256)
+        let unpadded = MessagePadding.unpad(enc)
+        let padLen = enc.count - unpadded.count
+        if padLen > 0 {
+            // Set last pad byte to wrong value (padLen-1) to break PKCS#7
+            enc[enc.count - 1] = UInt8((padLen - 1) & 0xFF)
+            let maybe = BinaryProtocol.decode(enc)
+            // If decode still succeeds (nested pad edge case), at least ensure payload integrity
+            if let pkt2 = maybe {
+                #expect(pkt2.payload == pkt.payload)
+            } else {
+                #expect(maybe == nil)
+            }
+        } else {
+            // If no padding was applied, just assert decode succeeds (nothing to test)
+            #expect(BinaryProtocol.decode(enc) != nil)
+        }
+    }
+    
+    // MARK: - Message Encoding/Decoding Tests
+    
+    @Test func messageEncodingDecoding() throws {
+        let message = TestHelpers.createTestMessage()
+        
+        let payload = try #require(message.toBinaryPayload(), "Failed to encode message to binary")
+        
+        let decodedMessage = try #require(BitchatMessage(payload), "Failed to decode message from binary")
+        
+        #expect(decodedMessage.content == message.content)
+        #expect(decodedMessage.sender == message.sender)
+        #expect(decodedMessage.senderPeerID == message.senderPeerID)
+        #expect(decodedMessage.isPrivate == message.isPrivate)
+        
+        // Timestamp should be close (within 1 second due to conversion)
+        let timeDiff = abs(decodedMessage.timestamp.timeIntervalSince(message.timestamp))
+        #expect(timeDiff < 1)
+    }
+    
+    func testPrivateMessageEncoding() throws {
+        let message = TestHelpers.createTestMessage(
+            isPrivate: true,
+            recipientNickname: TestConstants.testNickname2
+        )
+        
+        let payload = try #require(message.toBinaryPayload(), "Failed to encode private message")
+        let decodedMessage = try #require(BitchatMessage(payload), "Failed to decode private message")
+        
+        #expect(decodedMessage.isPrivate)
+        #expect(decodedMessage.recipientNickname == TestConstants.testNickname2)
+    }
+    
+    @Test func messageWithMentions() throws {
+        let mentions = [TestConstants.testNickname2, TestConstants.testNickname3]
+        let message = TestHelpers.createTestMessage(mentions: mentions)
+        let payload = try #require(message.toBinaryPayload(), "Failed to encode message with mentions")
+        let decodedMessage = try #require(BitchatMessage(payload), "Failed to decode message with mentions")
+        #expect(decodedMessage.mentions == mentions)
+    }
+    
+    @Test func relayMessageEncoding() throws {
+        let message = BitchatMessage(
+            id: UUID().uuidString,
+            sender: TestConstants.testNickname1,
+            content: TestConstants.testMessage1,
+            timestamp: Date(),
+            isRelay: true,
+            originalSender: TestConstants.testNickname3,
+            isPrivate: false,
+            recipientNickname: nil,
+            mentions: nil
+        )
+        let payload = try #require(message.toBinaryPayload(), "Failed to encode relay message")
+        let decodedMessage = try #require(BitchatMessage(payload), "Failed to decode relay message")
+        #expect(decodedMessage.isRelay)
+        #expect(decodedMessage.originalSender == TestConstants.testNickname3)
+    }
+    
+    // MARK: - Edge Cases and Error Handling
+    
+    @Test("Too small data")
+    func invalidDataDecoding() throws {
+        let tooSmall = Data(repeating: 0, count: 5)
+        #expect(BinaryProtocol.decode(tooSmall) == nil)
+        
+        // Random data
+        let random = TestHelpers.generateRandomData(length: 100)
+        #expect(BinaryProtocol.decode(random) == nil)
+        
+        // Corrupted header
+        let packet = TestHelpers.createTestPacket()
+        var encoded = try #require(BinaryProtocol.encode(packet), "Failed to encode test packet")
+        
+        // Corrupt the version byte
+        encoded[0] = 0xFF
+        #expect(BinaryProtocol.decode(encoded) == nil)
+    }
+    
+    @Test("Test maximum size handling")
+    func largeMessageHandling() throws {
+        let largeContent = String(repeating: "X", count: 65535) // Max uint16
+        let message = TestHelpers.createTestMessage(content: largeContent)
+        let payload = try #require(message.toBinaryPayload(), "Failed to handle large message")
+        let decodedMessage = try #require(BitchatMessage(payload), "Failed to handle large message")
+        #expect(decodedMessage.content == largeContent)
+    }
+    
+    @Test("Test message with empty content")
+    func emptyFieldsHandling() throws {
+        let emptyMessage = TestHelpers.createTestMessage(content: "")
+        let payload = try #require(emptyMessage.toBinaryPayload(), "Failed to handle empty message")
+        let decodedMessage = try #require(BitchatMessage(payload), "Failed to handle empty message")
+        #expect(decodedMessage.content.isEmpty)
+    }
+    
+    // MARK: - Protocol Version Tests
+    
+    @Test("Test with supported version (version is always 1 in init)")
+    func protocolVersionHandling() throws {
+        let packet = TestHelpers.createTestPacket()
+        let encoded = try #require(BinaryProtocol.encode(packet), "Failed to encode packet with version")
+        let decoded = try #require(BinaryProtocol.decode(encoded), "Failed to decode packet with version")
+        #expect(decoded.version == 1)
+    }
+    
+    @Test("Create packet data with unsupported version")
+    func unsupportedProtocolVersion() throws {
+        let packet = TestHelpers.createTestPacket()
+        var encoded = try #require(BinaryProtocol.encode(packet), "Failed to encode packet")
+        
+        // Manually change version byte to unsupported value
+        encoded[0] = 99 // Unsupported version
+        
+        // Should fail to decode
+        #expect(BinaryProtocol.decode(encoded) == nil)
+    }
+    
+    // MARK: - Bounds Checking Tests (Crash Prevention)
+    
+    @Test("Test the specific crash scenario: payloadLength = 193 (0xc1) but only 30 bytes available")
+    func malformedPacketWithInvalidPayloadLength() throws {
+        var malformedData = Data()
+        
+        // Valid header (13 bytes)
+        malformedData.append(1) // version
+        malformedData.append(1) // type  
+        malformedData.append(10) // ttl
+        
+        // Timestamp (8 bytes)
+        for _ in 0..<8 {
+            malformedData.append(0)
+        }
+        
+        malformedData.append(0) // flags (no recipient, no signature, not compressed)
+        
+        // Invalid payload length: 193 (0x00c1) but we'll only provide 8 bytes total data
+        malformedData.append(0x00) // high byte
+        malformedData.append(0xc1) // low byte (193)
+        
+        // SenderID (8 bytes) - this brings us to 21 bytes total
+        for _ in 0..<8 {
+            malformedData.append(0x01)
+        }
+        
+        // Only provide 8 more bytes instead of the claimed 193
+        for _ in 0..<8 {
+            malformedData.append(0x02)
+        }
+        
+        // Total data is now 30 bytes, but payloadLength claims 193
+        #expect(malformedData.count == 30)
+        
+        // This should not crash - should return nil gracefully
+        let result = BinaryProtocol.decode(malformedData)
+        #expect(result == nil, "Malformed packet with invalid payload length should return nil, not crash")
+    }
+    
+    @Test("Test various truncation scenarios")
+    func truncatedPacketHandling() throws {
+        let packet = TestHelpers.createTestPacket()
+        let validEncoded = try #require(BinaryProtocol.encode(packet), "Failed to encode test packet")
+        
+        // Test truncation at various points
+        let truncationPoints = [0, 5, 10, 15, 20, 25]
+        
+        for point in truncationPoints {
+            let truncated = validEncoded.prefix(point)
+            let result = BinaryProtocol.decode(truncated)
+            #expect(result == nil, "Truncated packet at \(point) bytes should return nil, not crash")
+        }
+    }
+    
+    @Test("Test compressed packet with invalid original size")
+    func malformedCompressedPacket() throws {
+        var malformedData = Data()
+        
+        // Valid header
+        malformedData.append(1) // version
+        malformedData.append(1) // type
+        malformedData.append(10) // ttl
+        
+        // Timestamp (8 bytes)
+        for _ in 0..<8 {
+            malformedData.append(0)
+        }
+        
+        malformedData.append(0x04) // flags: isCompressed = true
+        
+        // Small payload length that's insufficient for compression
+        malformedData.append(0x00) // high byte  
+        malformedData.append(0x01) // low byte (1 byte - insufficient for 2-byte original size)
+        
+        // SenderID (8 bytes)
+        for _ in 0..<8 {
+            malformedData.append(0x01)
+        }
+        
+        // Only 1 byte of "compressed" data (should need at least 2 for original size)
+        malformedData.append(0x99)
+        
+        // Should handle this gracefully
+        let result = BinaryProtocol.decode(malformedData)
+        #expect(result == nil, "Malformed compressed packet should return nil, not crash")
+    }
+    
+    @Test("Test packet claiming extremely large payload")
+    func excessivelyLargePayloadLength() throws {
+        var malformedData = Data()
+        
+        // Valid header
+        malformedData.append(1) // version
+        malformedData.append(1) // type
+        malformedData.append(10) // ttl
+        
+        // Timestamp (8 bytes)
+        for _ in 0..<8 {
+            malformedData.append(0)
+        }
+        
+        malformedData.append(0) // flags
+        
+        // Maximum payload length (65535)
+        malformedData.append(0xFF) // high byte
+        malformedData.append(0xFF) // low byte
+        
+        // SenderID (8 bytes)
+        for _ in 0..<8 {
+            malformedData.append(0x01)
+        }
+        
+        // Provide only a tiny amount of actual data
+        malformedData.append(contentsOf: [0x01, 0x02, 0x03])
+        
+        // Should handle this gracefully without trying to allocate massive amounts of memory
+        let result = BinaryProtocol.decode(malformedData)
+        #expect(result == nil, "Packet with excessive payload length should return nil, not crash")
+    }
+    
+    @Test("Test compressed packet with unreasonable original size")
+    func compressedPacketWithInvalidOriginalSize() throws {
+        var malformedData = Data()
+        
+        // Valid header
+        malformedData.append(1) // version
+        malformedData.append(1) // type
+        malformedData.append(10) // ttl
+        
+        // Timestamp (8 bytes)
+        for _ in 0..<8 {
+            malformedData.append(0)
+        }
+        
+        malformedData.append(0x04) // flags: isCompressed = true
+        
+        // Reasonable payload length
+        malformedData.append(0x00) // high byte
+        malformedData.append(0x10) // low byte (16 bytes)
+        
+        // SenderID (8 bytes)
+        for _ in 0..<8 {
+            malformedData.append(0x01)
+        }
+        
+        // Original size claiming to be extremely large (2MB)
+        malformedData.append(0x20) // high byte of original size
+        malformedData.append(0x00) // low byte of original size (0x2000 = 8192, but let's make it larger with more bytes)
+        
+        // Add more bytes to make it claim larger size - but this will be invalid
+        // because our validation should catch unreasonable sizes
+        malformedData.append(contentsOf: [0x01, 0x02, 0x03, 0x04]) // Some compressed data
+        
+        // Pad to match payload length
+        while malformedData.count < 21 + 16 { // header + senderID + payload
+            malformedData.append(0x00)
+        }
+        
+        let result = BinaryProtocol.decode(malformedData)
+        #expect(result == nil, "Compressed packet with invalid original size should return nil, not crash")
+    }
+
+    @Test("Test compressed packet with suspicious compression ratio")
+    func compressedPacketWithSuspiciousCompressionRatio() {
+        var malformedData = Data()
+
+        malformedData.append(1)     // version
+        malformedData.append(1)     // type
+        malformedData.append(10)    // ttl
+
+        for _ in 0..<8 {
+            malformedData.append(0)
+        }
+
+        malformedData.append(0x04)  // isCompressed
+        malformedData.append(0x00)
+        malformedData.append(0x03)  // payloadLength = 3 (2 original-size bytes + 1 compressed byte)
+
+        for _ in 0..<8 {
+            malformedData.append(0x01)
+        }
+
+        malformedData.append(0xFF)
+        malformedData.append(0xFF)  // originalSize = 65535
+        malformedData.append(0x99)  // compressed payload length = 1 => ratio > 50_000
+
+        #expect(BinaryProtocol.decode(malformedData) == nil)
+    }
+    
+    @Test("Test packet designed to cause integer overflow")
+    func maliciousPacketWithIntegerOverflow() throws {
+        var maliciousData = Data()
+        
+        // Valid header
+        maliciousData.append(1) // version
+        maliciousData.append(1) // type
+        maliciousData.append(10) // ttl
+        
+        // Timestamp (8 bytes)
+        for _ in 0..<8 {
+            maliciousData.append(0)
+        }
+        
+        // Set flags to have recipient and signature (increase expected size)
+        maliciousData.append(0x03) // hasRecipient | hasSignature
+        
+        // Very large payload length
+        maliciousData.append(0xFF) // high byte
+        maliciousData.append(0xFE) // low byte (65534)
+        
+        // SenderID (8 bytes)
+        for _ in 0..<8 {
+            maliciousData.append(0x01)
+        }
+        
+        // RecipientID (8 bytes - required due to flag)
+        for _ in 0..<8 {
+            maliciousData.append(0x02)
+        }
+        
+        // Provide minimal payload data - should trigger bounds check failure
+        maliciousData.append(contentsOf: [0x01, 0x02])
+        
+        // Should handle gracefully without integer overflow issues
+        let result = BinaryProtocol.decode(maliciousData)
+        #expect(result == nil, "Malicious packet designed for integer overflow should return nil, not crash")
+    }
+    
+    @Test("Test packets with incomplete headers")
+    func partialHeaderData() throws {
+        let headerSizes = [0, 1, 5, 10, 12] // Various incomplete header sizes
+        
+        for size in headerSizes {
+            let partialData = Data(repeating: 0x01, count: size)
+            let result = BinaryProtocol.decode(partialData)
+            #expect(result == nil, "Partial header data (\(size) bytes) should return nil, not crash")
+        }
+    }
+    
+    @Test("Test exact boundary conditions")
+    func boundaryConditions() throws {
+        let packet = TestHelpers.createTestPacket()
+        let validEncoded = try #require(BinaryProtocol.encode(packet), "Failed to encode test packet")
+        
+        // If truncation only removes padding, decode may still succeed. Compute unpadded size.
+        let unpadded = MessagePadding.unpad(validEncoded)
+        // Truncate within the unpadded frame to guarantee corruption
+        let cut = max(1, unpadded.count - 10)
+        let truncatedCore = unpadded.prefix(cut)
+        let result = BinaryProtocol.decode(truncatedCore)
+        #expect(result == nil, "Truncated core frame should return nil, not crash")
+        
+        // Test minimum valid size - create a valid minimal packet
+        var minData = Data()
+        minData.append(1) // version
+        minData.append(1) // type
+        minData.append(10) // ttl
+        
+        // Timestamp (8 bytes)
+        for _ in 0..<8 {
+            minData.append(0)
+        }
+        
+        minData.append(0) // flags (no optional fields)
+        minData.append(0) // payload length high byte
+        minData.append(0) // payload length low byte (0 payload)
+        
+        // SenderID (8 bytes)
+        for _ in 0..<8 {
+            minData.append(0x01)
+        }
+        
+        // This should be exactly the minimum size and should decode without crashing
+        _ = BinaryProtocol.decode(minData)
+        // The important thing is no crash occurs - result might be nil or valid
+        // We don't assert the result, just that no crash happens
+    }
+}
+
+private extension Data {
+    func trimmingNullBytes() -> Data {
+        // Find the first null byte
+        if let nullIndex = self.firstIndex(of: 0) {
+            return self.prefix(nullIndex)
+        }
+        return self
+    }
+}

localPackages/BitFoundation/Tests/BitFoundationTests/KeychainErrorHandlingTests.swift

@@ -0,0 +1,155 @@
+//
+// KeychainErrorHandlingTests.swift
+// bitchatTests
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+// BCH-01-009: Tests for proper keychain error classification and handling
+
+import Testing
+import Foundation
+import BitFoundation
+
+struct KeychainErrorHandlingTests {
+
+    // MARK: - Error Classification Tests
+
+    @Test func keychainReadResult_successIsNotRecoverable() throws {
+        let result = KeychainReadResult.success(Data([1, 2, 3]))
+        #expect(result.isRecoverableError == false)
+    }
+
+    @Test func keychainReadResult_itemNotFoundIsNotRecoverable() throws {
+        let result = KeychainReadResult.itemNotFound
+        #expect(result.isRecoverableError == false)
+    }
+
+    @Test func keychainReadResult_deviceLockedIsRecoverable() throws {
+        let result = KeychainReadResult.deviceLocked
+        #expect(result.isRecoverableError == true)
+    }
+
+    @Test func keychainReadResult_authenticationFailedIsRecoverable() throws {
+        let result = KeychainReadResult.authenticationFailed
+        #expect(result.isRecoverableError == true)
+    }
+
+    @Test func keychainReadResult_accessDeniedIsNotRecoverable() throws {
+        let result = KeychainReadResult.accessDenied
+        #expect(result.isRecoverableError == false)
+    }
+
+    @Test func keychainSaveResult_successIsNotRecoverable() throws {
+        let result = KeychainSaveResult.success
+        #expect(result.isRecoverableError == false)
+    }
+
+    @Test func keychainSaveResult_duplicateItemIsRecoverable() throws {
+        let result = KeychainSaveResult.duplicateItem
+        #expect(result.isRecoverableError == true)
+    }
+
+    @Test func keychainSaveResult_deviceLockedIsRecoverable() throws {
+        let result = KeychainSaveResult.deviceLocked
+        #expect(result.isRecoverableError == true)
+    }
+
+    @Test func keychainSaveResult_storageFullIsNotRecoverable() throws {
+        let result = KeychainSaveResult.storageFull
+        #expect(result.isRecoverableError == false)
+    }
+
+    // MARK: - Mock Keychain Error Simulation Tests
+
+    @Test func mockKeychain_canSimulateReadErrors() throws {
+        let keychain = MockKeychain()
+
+        // Simulate access denied error
+        keychain.simulatedReadError = .accessDenied
+        let result = keychain.getIdentityKeyWithResult(forKey: "testKey")
+
+        switch result {
+        case .accessDenied:
+            // Expected
+            break
+        default:
+            throw KeychainTestError("Expected accessDenied, got \(result)")
+        }
+    }
+
+    @Test func mockKeychain_canSimulateSaveErrors() throws {
+        let keychain = MockKeychain()
+
+        // Simulate storage full error
+        keychain.simulatedSaveError = .storageFull
+        let result = keychain.saveIdentityKeyWithResult(Data([1, 2, 3]), forKey: "testKey")
+
+        switch result {
+        case .storageFull:
+            // Expected
+            break
+        default:
+            throw KeychainTestError("Expected storageFull, got \(result)")
+        }
+    }
+
+    @Test func mockKeychain_returnsItemNotFoundForMissingKey() throws {
+        let keychain = MockKeychain()
+        let result = keychain.getIdentityKeyWithResult(forKey: "nonExistentKey")
+
+        switch result {
+        case .itemNotFound:
+            // Expected
+            break
+        default:
+            throw KeychainTestError("Expected itemNotFound, got \(result)")
+        }
+    }
+
+    @Test func mockKeychain_returnsSuccessForExistingKey() throws {
+        let keychain = MockKeychain()
+        let testData = Data([1, 2, 3, 4, 5])
+
+        // First save the key
+        _ = keychain.saveIdentityKey(testData, forKey: "existingKey")
+
+        // Now read it back
+        let result = keychain.getIdentityKeyWithResult(forKey: "existingKey")
+
+        switch result {
+        case .success(let data):
+            #expect(data == testData)
+        default:
+            throw KeychainTestError("Expected success, got \(result)")
+        }
+    }
+
+    @Test func mockKeychain_saveWithResultStoresData() throws {
+        let keychain = MockKeychain()
+        let testData = Data([10, 20, 30])
+
+        let saveResult = keychain.saveIdentityKeyWithResult(testData, forKey: "newKey")
+
+        switch saveResult {
+        case .success:
+            // Verify data was stored
+            let readResult = keychain.getIdentityKeyWithResult(forKey: "newKey")
+            switch readResult {
+            case .success(let data):
+                #expect(data == testData)
+            default:
+                throw KeychainTestError("Expected to read back saved data")
+            }
+        default:
+            throw KeychainTestError("Expected save success, got \(saveResult)")
+        }
+    }
+}
+
+// Helper error type for tests
+private struct KeychainTestError: Error, CustomStringConvertible {
+    let message: String
+    init(_ message: String) { self.message = message }
+    var description: String { message }
+}

localPackages/BitFoundation/Tests/BitFoundationTests/MockKeychain.swift

@@ -0,0 +1,201 @@
+//
+// MockKeychain.swift
+// bitchat
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import Foundation
+import BitFoundation
+
+// TODO: Create a module for test helpers
+final class MockKeychain: KeychainManagerProtocol {
+    private var storage: [String: Data] = [:]
+    private var serviceStorage: [String: [String: Data]] = [:]
+
+    // BCH-01-009: Configurable error simulation for testing
+    var simulatedReadError: KeychainReadResult?
+    var simulatedSaveError: KeychainSaveResult?
+
+    func saveIdentityKey(_ keyData: Data, forKey key: String) -> Bool {
+        storage[key] = keyData
+        return true
+    }
+
+    func getIdentityKey(forKey key: String) -> Data? {
+        storage[key]
+    }
+
+    func deleteIdentityKey(forKey key: String) -> Bool {
+        storage.removeValue(forKey: key)
+        return true
+    }
+
+    func deleteAllKeychainData() -> Bool {
+        storage.removeAll()
+        serviceStorage.removeAll()
+        return true
+    }
+
+    func secureClear(_ data: inout Data) {
+        data = Data()
+    }
+
+    func secureClear(_ string: inout String) {
+        string = ""
+    }
+
+    func verifyIdentityKeyExists() -> Bool {
+        storage["identity_noiseStaticKey"] != nil
+    }
+
+    // BCH-01-009: New methods with proper error classification
+    func getIdentityKeyWithResult(forKey key: String) -> KeychainReadResult {
+        if let simulated = simulatedReadError {
+            return simulated
+        }
+        if let data = storage[key] {
+            return .success(data)
+        }
+        return .itemNotFound
+    }
+
+    func saveIdentityKeyWithResult(_ keyData: Data, forKey key: String) -> KeychainSaveResult {
+        if let simulated = simulatedSaveError {
+            return simulated
+        }
+        storage[key] = keyData
+        return .success
+    }
+
+    // MARK: - Generic Data Storage (consolidated from KeychainHelper)
+
+    func save(key: String, data: Data, service: String, accessible: CFString?) {
+        if serviceStorage[service] == nil {
+            serviceStorage[service] = [:]
+        }
+        serviceStorage[service]?[key] = data
+    }
+
+    func load(key: String, service: String) -> Data? {
+        serviceStorage[service]?[key]
+    }
+
+    func delete(key: String, service: String) {
+        serviceStorage[service]?.removeValue(forKey: key)
+    }
+}
+
+/// Typealias for backwards compatibility with tests using MockKeychainHelper
+typealias MockKeychainHelper = MockKeychain
+
+/// Mock keychain that tracks secureClear calls for testing DH secret clearing
+final class TrackingMockKeychain: KeychainManagerProtocol {
+    private var storage: [String: Data] = [:]
+    private var serviceStorage: [String: [String: Data]] = [:]
+
+    /// Thread-safe counter for secureClear calls
+    private let lock = NSLock()
+    private var _secureClearDataCallCount = 0
+    private var _secureClearStringCallCount = 0
+
+    // BCH-01-009: Configurable error simulation for testing
+    var simulatedReadError: KeychainReadResult?
+    var simulatedSaveError: KeychainSaveResult?
+
+    var secureClearDataCallCount: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return _secureClearDataCallCount
+    }
+
+    var secureClearStringCallCount: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return _secureClearStringCallCount
+    }
+
+    var totalSecureClearCallCount: Int {
+        return secureClearDataCallCount + secureClearStringCallCount
+    }
+
+    func resetCounts() {
+        lock.lock()
+        defer { lock.unlock() }
+        _secureClearDataCallCount = 0
+        _secureClearStringCallCount = 0
+    }
+
+    func saveIdentityKey(_ keyData: Data, forKey key: String) -> Bool {
+        storage[key] = keyData
+        return true
+    }
+
+    func getIdentityKey(forKey key: String) -> Data? {
+        storage[key]
+    }
+
+    func deleteIdentityKey(forKey key: String) -> Bool {
+        storage.removeValue(forKey: key)
+        return true
+    }
+
+    func deleteAllKeychainData() -> Bool {
+        storage.removeAll()
+        serviceStorage.removeAll()
+        return true
+    }
+
+    func secureClear(_ data: inout Data) {
+        lock.lock()
+        _secureClearDataCallCount += 1
+        lock.unlock()
+        data = Data()
+    }
+
+    func secureClear(_ string: inout String) {
+        lock.lock()
+        _secureClearStringCallCount += 1
+        lock.unlock()
+        string = ""
+    }
+
+    func verifyIdentityKeyExists() -> Bool {
+        storage["identity_noiseStaticKey"] != nil
+    }
+
+    // BCH-01-009: New methods with proper error classification
+    func getIdentityKeyWithResult(forKey key: String) -> KeychainReadResult {
+        if let simulated = simulatedReadError {
+            return simulated
+        }
+        if let data = storage[key] {
+            return .success(data)
+        }
+        return .itemNotFound
+    }
+
+    func saveIdentityKeyWithResult(_ keyData: Data, forKey key: String) -> KeychainSaveResult {
+        if let simulated = simulatedSaveError {
+            return simulated
+        }
+        storage[key] = keyData
+        return .success
+    }
+
+    func save(key: String, data: Data, service: String, accessible: CFString?) {
+        if serviceStorage[service] == nil {
+            serviceStorage[service] = [:]
+        }
+        serviceStorage[service]?[key] = data
+    }
+
+    func load(key: String, service: String) -> Data? {
+        serviceStorage[service]?[key]
+    }
+
+    func delete(key: String, service: String) {
+        serviceStorage[service]?.removeValue(forKey: key)
+    }
+}

localPackages/BitFoundation/Tests/BitFoundationTests/TestConstants.swift

@@ -0,0 +1,28 @@
+//
+// TestConstants.swift
+// bitchatTests
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import Foundation
+
+// TODO: Create a module for test helpers
+struct TestConstants {
+    static let defaultTimeout: TimeInterval = 5.0
+    static let shortTimeout: TimeInterval = 1.0
+    static let longTimeout: TimeInterval = 10.0
+    
+    static let testNickname1 = "Alice"
+    static let testNickname2 = "Bob"
+    static let testNickname3 = "Charlie"
+    static let testNickname4 = "David"
+    
+    static let testMessage1 = "Hello, World!"
+    static let testMessage2 = "How are you?"
+    static let testMessage3 = "This is a test message"
+    static let testLongMessage = String(repeating: "This is a long message. ", count: 100)
+    
+    static let testSignature = Data(repeating: 0xAB, count: 64)
+}

localPackages/BitFoundation/Tests/BitFoundationTests/TestHelpers.swift

@@ -0,0 +1,143 @@
+//
+// TestHelpers.swift
+// bitchatTests
+//
+// This is free and unencumbered software released into the public domain.
+// For more information, see <https://unlicense.org>
+//
+
+import Foundation
+import CryptoKit
+@testable import BitFoundation
+
+// TODO: Create a module for test helpers
+final class TestHelpers {
+    
+    // MARK: - Key Generation
+    
+    static func generateTestKeyPair() -> (privateKey: Curve25519.KeyAgreement.PrivateKey, publicKey: Curve25519.KeyAgreement.PublicKey) {
+        let privateKey = Curve25519.KeyAgreement.PrivateKey()
+        let publicKey = privateKey.publicKey
+        return (privateKey, publicKey)
+    }
+    
+    static func generateTestIdentity(peerID: String, nickname: String) -> (peerID: String, nickname: String, privateKey: Curve25519.KeyAgreement.PrivateKey, publicKey: Curve25519.KeyAgreement.PublicKey) {
+        let (privateKey, publicKey) = generateTestKeyPair()
+        return (peerID: peerID, nickname: nickname, privateKey: privateKey, publicKey: publicKey)
+    }
+    
+    // MARK: - Message Creation
+    
+    static func createTestMessage(
+        content: String = TestConstants.testMessage1,
+        sender: String = TestConstants.testNickname1,
+        senderPeerID: PeerID = PeerID(str: UUID().uuidString),
+        isPrivate: Bool = false,
+        recipientNickname: String? = nil,
+        mentions: [String]? = nil
+    ) -> BitchatMessage {
+        return BitchatMessage(
+            id: UUID().uuidString,
+            sender: sender,
+            content: content,
+            timestamp: Date(),
+            isRelay: false,
+            originalSender: nil,
+            isPrivate: isPrivate,
+            recipientNickname: recipientNickname,
+            senderPeerID: senderPeerID,
+            mentions: mentions
+        )
+    }
+    
+    static func createTestPacket(
+        type: UInt8 = 0x01,
+        senderID: PeerID = PeerID(str: UUID().uuidString),
+        recipientID: PeerID? = nil,
+        payload: Data = "test payload".data(using: .utf8)!,
+        signature: Data? = nil,
+        ttl: UInt8 = 3
+    ) -> BitchatPacket {
+        return BitchatPacket(
+            type: type,
+            senderID: senderID.id.data(using: .utf8)!,
+            recipientID: recipientID?.id.data(using: .utf8),
+            timestamp: UInt64(Date().timeIntervalSince1970 * 1000),
+            payload: payload,
+            signature: signature,
+            ttl: ttl
+        )
+    }
+    
+    // MARK: - Data Generation
+    
+    static func generateRandomData(length: Int) -> Data {
+        var data = Data(count: length)
+        _ = data.withUnsafeMutableBytes { bytes in
+            SecRandomCopyBytes(kSecRandomDefault, length, bytes.baseAddress!)
+        }
+        return data
+    }
+    
+    static func generateTestPeerID() -> String {
+        return "PEER" + UUID().uuidString.prefix(8)
+    }
+    
+    // MARK: - Async Helpers
+    
+    static func waitFor(_ condition: @escaping () -> Bool, timeout: TimeInterval = TestConstants.defaultTimeout) async throws {
+        let start = Date()
+        while !condition() {
+            if Date().timeIntervalSince(start) > timeout {
+                throw TestError.timeout
+            }
+            try await sleep(0.01)
+        }
+    }
+
+    @MainActor
+    static func waitUntil(
+        _ condition: @escaping () -> Bool,
+        timeout: TimeInterval = TestConstants.defaultTimeout,
+        pollInterval: TimeInterval = 0.01
+    ) async -> Bool {
+        let start = Date()
+        while !condition() {
+            if Date().timeIntervalSince(start) > timeout {
+                return condition()
+            }
+            try? await sleep(pollInterval)
+        }
+        return true
+    }
+    
+    static func expectAsync<T>(
+        timeout: TimeInterval = TestConstants.defaultTimeout,
+        operation: @escaping () async throws -> T
+    ) async throws -> T {
+        return try await withThrowingTaskGroup(of: T.self) { group in
+            group.addTask {
+                return try await operation()
+            }
+            
+            group.addTask {
+                try await sleep(1)
+                throw TestError.timeout
+            }
+            
+            let result = try await group.next()!
+            group.cancelAll()
+            return result
+        }
+    }
+}
+
+enum TestError: Error {
+    case timeout
+    case unexpectedValue
+    case testFailure(String)
+}
+
+func sleep(_ seconds: TimeInterval) async throws {
+    try await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000))
+}