1. The P2P Bootstrap Paradox

Two mobile phones cannot open a direct TCP socket without prior coordination because:

• Dynamic IP Addresses & Ephemeral Ports: Mobile IPs change on every Wi-Fi/Cellular switch, and the Host binds a temporary free OS port (port: 0) per attempt.
• Asynchronous Availability: Device A and Device B may launch the app at different times and need a lightweight rendezvous signal (wake / request).
• Pre-TCP Session Key Exchange: Both devices must exchange ephemeral 32-byte X25519 public keys before opening the TCP socket so the very first TCP frame (seq: 1) is already encrypted.

2. Two-Stage Handshake & Challenge-Attempt State Machine

3. Why Repeated wake Signals Never Invalidate In-Flight Offers

In ReliableConversation.ts (line 237), when the Guest receives a wake signal from the Host, it checks if (!this.challenge) this.challenge = randomId(). By reusing an outstanding challenge rather than overwriting it, a duplicate wake packet never invalidates an offer that the Host is currently gathering ICE candidates for.

4. Reference Broker Hardening (server/signaling.mjs)

1. Immortal Supervisor vs. Disposable Peers

Raw OS TCP sockets break whenever a mobile user switches between Wi-Fi and Cellular or backgrounds the app. fprot solves this by making P2PTcpPeer strictly single-use and disposable, while ReliableConversation acts as a persistent supervisor that spawns a fresh P2PTcpPeer with a new ++this.generation counter on every reconnect.

Every async callback checks this.current(peer, generation) so late events from a dying socket can never corrupt the new connection.

2. Write-Before-Memory Commit Pipeline (MessageStore)

3. Stop-and-Wait ARQ & Lost-ACK Idempotent Deduplication

• Single In-Flight Lock (this.inFlight): Only the oldest pending outgoing message is transmitted at a time, guarded by a 10-second ackTimer.
• Lost-ACK Recovery: If Device B receives message m1, saves it to disk, and sends { kind: "ack", id: m1 }, but the Wi-Fi drops before Device A receives the ACK, Device A will re-transmit m1 on the next generation's TCP connection.
• Idempotent Receiver: Device B's MessageStore.add() detects that incoming:m1 already exists with identical sentAt and payload, returns false (preventing duplicate UI entries), and re-transmits the ack so Device A marks m1 as delivered!

4. Glare Immunity & Exponential Backoff with Jitter

While state === 'connected', ReliableConversation ignores all incoming signaling packets (if (this.state === 'connected') return;), relying solely on its encrypted TCP heartbeat (10s ping/pong, 35s idleTimeoutMs) to detect if the partner restarted.

1. Three-Layer TCP Packet Encapsulation

// Layer 1: Raw newline-delimited TCP line (EncryptedFrame)
{"v":1,"nonce":"","ciphertext":""}\n

// Layer 2: Decrypted Session Payload (WirePayload in P2PTcpPeer.ts)
{
  "v": 2,
  "sender": "host",       // Verified against expected opposite role to prevent reflection attacks
  "seq": 2,               // Must equal this.rxSequence + 1 (strict anti-replay & anti-drop)
  "kind": "message",
  "message": {
    "id": "xY9zA2bC5dE8fG1h",
    "sentAt": 1780000000000,
    // Layer 3: ReliableConversation Packet (fprot.chat.v1)
    "payload": {
      "protocol": "fprot.chat.v1",
      "conversationId": "main-chat-room",
      "kind": "message",  // "message" | "ack" | "ping" | "pong"
      "id": "18c21a4f9b0d2e3c",
      "payload": "Hello over direct encrypted TCP!",
      "sentAt": 1780000000000
    }
  }
}

2. Security Threat Defense Matrix

1. The SignalTransport Contract

import type { SignalTransport } from '@harbouli/fprot';

export class CustomSocketSignaling implements SignalTransport {
  start(handlers: { onMessage: (msg: string) => void; onOnline: (online: boolean) => void }): void {
    // Subscribe to incoming signals for myPublicKey and report connection status
  }
  send(message: string): boolean {
    // Forward the signed JSON envelope string to the recipient specified in JSON.parse(JSON.parse(message).body).to
    return true;
  }
  stop(): void {
    // Close sockets and clean up listeners
  }
}