Version: 1.0 Last Updated: February 2026 Status: Living document -- updated as the implementation evolves

1. Overview
2. Architecture & Data Flow
3. End-to-End Encryption (E2EE)
   • Key Exchange
   • Message Encryption
   • Identity & Trust (TOFU)
   • Replay Protection
   • Session Management
4. Relay Blindness: What the Server Can and Cannot See
5. Enforced Encryption Coverage
6. Inbound Enforcement & Event Whitelisting
7. Key Storage
8. Transport Security
9. PRNG & Randomness
10. Threat Model
11. Deliberate Design Decisions
12. Compliance Mapping
13. Known Limitations & Roadmap
14. Responsible Disclosure

ForkOff is a mobile app and CLI toolchain that lets developers control AI coding sessions (Claude Code) on their laptop from their phone. The communication path is:

Mobile App  <-->  API Relay Server  <-->  CLI (on developer's machine)

The relay server exists solely to route WebSocket messages between the mobile app and the CLI. By design, the relay server never sees plaintext session data. All sensitive payloads are encrypted end-to-end between the mobile app and the CLI before reaching the relay.

This document describes the cryptographic design, threat model, and security properties of ForkOff's E2EE implementation.

+----------------+          +------------------+          +----------------+
|   Mobile App   |  <-wss-> |   API Relay      |  <-wss-> |   CLI Tool     |
|  (React Native)|          |  (NestJS/AWS)    |          |  (Node.js)     |
+----------------+          +------------------+          +----------------+
        |                          |                             |
   E2EE Encrypt              Opaque Blob                   E2EE Decrypt
   E2EE Decrypt              Forwarding                    E2EE Encrypt
        |                          |                             |
   Ed25519 Signing           No Key Access               Ed25519 Signing
   X25519 ECDH                                            X25519 ECDH
   TOFU Key Pinning                                       TOFU Key Pinning

The relay server handles:

• WebSocket connection management and room-based routing
• Device pairing code matching
• Push notification delivery
• Session lifecycle metadata (device online/offline)

The relay server does not handle:

• Key exchange negotiation (it forwards opaque key exchange messages)
• Decryption of any payload
• Storage of any cryptographic keys
• Inspection of event types or message content (when E2EE is active)

ForkOff's E2EE is built on TweetNaCl (a JavaScript port of Daniel J. Bernstein's NaCl library), providing a well-analyzed, misuse-resistant cryptographic API.

Algorithm: X25519 Elliptic Curve Diffie-Hellman (ECDH) with ephemeral key pairs.

Each time a CLI and mobile app connect, a fresh X25519 key pair is generated on each side. Neither side reuses ephemeral keys across sessions.

Protocol flow:

CLI                              Relay                           Mobile
 |                                 |                                |
 |  encrypted_key_exchange_init    |                                |
 |  { ephemeralPubKey,             |   (forwards opaque blob)       |
 |    identityPubKey,              | -----------------------------> |
 |    signature }                  |                                |
 |                                 |                                |
 |                                 |   encrypted_key_exchange_ack   |
 |                                 |   { ephemeralPubKey,           |
 |   (forwards opaque blob)        |     identityPubKey,           |
 | <------------------------------ |     signature }                |
 |                                 |                                |
 |  Both sides now compute:        |                                |
 |  sharedKey = nacl.box.before(   |                                |
 |    theirEphemeralPub,           |                                |
 |    myEphemeralPrivate)          |                                |

Shared secret derivation: nacl.box.before() performs X25519 ECDH followed by HSalsa20 key derivation, producing a 32-byte symmetric key suitable for NaCl secretbox encryption.

HKDF key derivation (implemented): HKDF-SHA256 will derive separate directional send/receive keys from the ECDH output, preventing key reuse across directions.

Algorithm: XSalsa20-Poly1305 authenticated encryption (NaCl secretbox).

• Cipher: XSalsa20 stream cipher (256-bit key, 192-bit nonce)
• MAC: Poly1305 message authentication code (128-bit tag)
• Nonce: 24 bytes of cryptographically random data, generated fresh per message via nacl.randomBytes(24)
• Key: 32-byte shared secret from the ECDH key exchange

Each message is encrypted as:

// Encryption (sender)
const nonce = nacl.randomBytes(24);           // Fresh random nonce
const ciphertext = nacl.secretbox(            // XSalsa20-Poly1305
  plaintextBytes, nonce, sharedKey
);
// Transmitted: { ciphertext (base64), nonce (base64) }

// Decryption (recipient)
const plaintext = nacl.secretbox.open(
  ciphertext, nonce, sharedKey
);
// Returns null if MAC verification fails (tampered or wrong key)

The Poly1305 MAC is computed over the ciphertext and verified before decryption. If the MAC check fails (indicating tampering, corruption, or a wrong key), secretbox.open returns null and decryption is rejected. This provides both confidentiality and integrity/authentication in a single operation.

Algorithm: Ed25519 digital signatures for identity verification.

ForkOff uses Trust On First Use (TOFU) to establish device identity. Each device generates a long-lived Ed25519 signing key pair on first initialization. During key exchange, each side signs its ephemeral public key with its Ed25519 identity key:

Signed payload (init):  "KEY_EXCHANGE_INIT:senderDeviceId:ephemeralPublicKey"
Signed payload (ack):   "KEY_EXCHANGE_ACK:senderDeviceId:ephemeralPublicKey:recipientDeviceId"

The signature verification process:

1. First contact: The peer's Ed25519 identity public key is stored (pinned) in secure storage.
2. Subsequent contacts: The presented identity key is compared against the pinned key.
3. Key mismatch: If a peer presents a different identity key than what was previously pinned, the key exchange is rejected with an explicit error: "IDENTITY KEY MISMATCH... This could indicate a man-in-the-middle attack.".
4. Invalid signature: If the Ed25519 signature does not verify, the key exchange is rejected.
5. Missing signature: If a peer sends an unsigned key exchange (e.g., an outdated client), the exchange is rejected with a message requiring the peer to update.

This prevents a man-in-the-middle from substituting their own ephemeral keys during the exchange, since they cannot produce a valid signature under the legitimate peer's Ed25519 identity key.

Each encrypted session maintains per-peer monotonic message counters:

• Outgoing counter: Starts at 0, incremented by 1 for each message sent. Transmitted as messageCounter in every encrypted message.
• Incoming counter: Tracks the highest counter value received from the peer. Initialized to -1 (no messages received).

Validation rules (enforced on every incoming message):

A message with a counter equal to or less than the last received counter is dropped with an explicit replay attack warning. This prevents an attacker (or the relay) from re-delivering captured ciphertext.

Each E2EE session is scoped to a single connection between one mobile device and one CLI instance:

• Ephemeral keys: A fresh X25519 key pair is generated for each session. Compromising a session key does not reveal keys from other sessions.
• Session expiry (implemented): Sessions will expire after 24 hours or 10,000 messages, whichever comes first. Expired sessions force a full re-keying (new ECDH exchange).
• Pending exchange limits: A maximum of 20 pending (incomplete) key exchanges are tracked, with a 5-minute TTL. This prevents resource exhaustion from incomplete handshakes.
• Duplicate exchange protection: If a key exchange init arrives for a peer that already has an established session or a pending exchange, it is silently ignored. This prevents race conditions from relay message re-delivery.
• Session teardown: On disconnect, all sessions and pending exchanges are cleared. The _anyE2EESessionEstablished flag is reset, re-enabling plaintext fallback for the next connection.

When E2EE is active, the API relay server is intentionally blind to application data. Here is exactly what the relay can and cannot observe:

The relay sees only the envelope (who is talking to whom, when, and the message sequence number) and an opaque encrypted blob. The event type itself is encrypted inside the payload, so the relay cannot even distinguish a "user_message" from a "permission_response".

When E2EE is active, 24 sensitive outbound event types are automatically routed through encryption. The application code does not need to opt in -- the WebSocket service intercepts these events and encrypts them transparently:

Outbound (Mobile to CLI):

If encryption fails for any reason, the event falls back to plaintext delivery so the application remains functional. This fallback is logged for debugging.

ForkOff implements two layers of inbound security to prevent event injection:

When E2EE has been established (_anyE2EESessionEstablished flag), inbound events matching the ENFORCED_INBOUND_EVENTS set are silently dropped if they arrive as plaintext. Only the decrypted versions (arriving through the encrypted_message channel) are trusted.

This prevents an attacker who has compromised the relay from injecting fake terminal_output, permission_prompt, or other sensitive events. The set covers 28 peer-originated event types.

When an encrypted message is decrypted, its inner _event field is checked against the ALLOWED_ENCRYPTED_EVENTS whitelist. Events not on this list are dropped. This prevents a compromised CLI from injecting infrastructure events (e.g., connected, error, pair_device_ack) through the E2EE channel.

Only legitimate application events that the CLI would normally produce are allowed through decryption.

Cryptographic keys are stored using platform-appropriate secure storage:

What is stored:

• Ed25519 identity key pair (long-lived, survives app restarts): Used for TOFU identity verification during key exchange.
• Ed25519 signing key pair (long-lived): Used to sign ephemeral keys during key exchange.
• Trusted peer identity keys (long-lived, per device): Pinned Ed25519 public keys for TOFU verification.
• Session keys (optional persistence on CLI): The CLI may persist encrypted session keys to disk; on mobile, session keys are memory-only and cleared on disconnect.

What is NOT stored:

• Ephemeral X25519 private keys are never persisted. They exist only in memory for the duration of a session.
• Shared secrets derived from ECDH are never persisted on mobile. They exist only in the ActiveSession in-memory map.
• Plaintext message content is never written to disk.

In addition to E2EE at the application layer, all network communication uses TLS:

• Production WebSocket: wss:// (TLS 1.2+) is enforced. The service explicitly upgrades ws:// URLs to wss:// for non-local addresses in production builds.
• Development exception: ws:// is allowed only for localhost, 127.0.0.1, and private IP ranges (192.168.*, 10.*, 172.*) in development builds.
• Certificate validation: Standard platform TLS certificate validation applies (system trust store).
• Custom relay URLs: When users configure a self-hosted relay, wss:// is still enforced for non-local addresses in production.

This provides a double encryption layer: TLS protects the connection from network-level eavesdroppers, while E2EE protects the payload from the relay server itself.

Cryptographic randomness is critical for key generation and nonce production. ForkOff addresses this across platforms:

• React Native (Hermes engine): The Hermes JavaScript engine lacks crypto.getRandomValues. ForkOff injects a polyfill using expo-crypto (which delegates to the platform's native CSPRNG) as TweetNaCl's PRNG before any NaCl usage.
• Node.js (CLI): Uses Node's built-in crypto.randomBytes, which delegates to the OS CSPRNG (/dev/urandom on Linux/macOS, CryptGenRandom on Windows).

The polyfill is loaded as the first import in all crypto modules to ensure no NaCl operation ever runs with an uninitialized or weak PRNG:

// polyfill.ts — loaded before any nacl usage
import nacl from 'tweetnacl';
import * as ExpoCrypto from 'expo-crypto';

nacl.setPRNG((x: Uint8Array, n: number) => {
  const bytes = ExpoCrypto.getRandomBytes(n);
  for (let i = 0; i < n; i++) x[i] = bytes[i];
});

Threat: An attacker gains full control of the API relay server.

Mitigation: The relay only sees encrypted blobs, device IDs, counters, and timestamps. The attacker cannot:

• Read message content, event types, or payloads
• Inject fake events (inbound plaintext is dropped when E2EE is established)
• Forge encrypted messages (requires the shared key, which never touches the relay)
• Replay messages (monotonic counter validation rejects duplicates)
• Tamper with messages (Poly1305 MAC detects any modification)

Residual risk: The attacker can observe metadata (which devices communicate, when, and how often) and can deny service by dropping or delaying messages.

Threat: An attacker on the same network intercepts traffic between a device and the relay.

Mitigation: Two layers of encryption:

1. TLS (wss://) encrypts the WebSocket connection, preventing eavesdropping on the wire.
2. E2EE encrypts the application payload, so even if TLS were somehow broken, the attacker sees only ciphertext.

Residual risk: Traffic analysis (message sizes and timing) could reveal communication patterns.

Threat: An attacker intercepts the key exchange and substitutes their own ephemeral keys.

Mitigation:

• Each side signs its ephemeral public key with its Ed25519 identity key.
• The signature covers prefix:senderDeviceId:ephemeralPublicKey[:recipientDeviceId], binding the ephemeral key to a specific identity and exchange direction.
• TOFU key pinning detects if a previously known device presents a different identity key.
• Pairing requires a short code exchanged via QR scan or manual entry (physical proximity).

Residual risk: The very first pairing (before any key is pinned) relies on the pairing code for authentication. An attacker who intercepts the pairing code AND controls the network could theoretically MITM the first connection. This is mitigated by the physical proximity requirement of QR code scanning.

Threat: An attacker captures an encrypted message and re-sends it.

Mitigation: Per-peer monotonic counters. Each message carries a strictly increasing counter. The recipient tracks the highest counter seen and rejects any message with a counter less than or equal to it. Counter validation includes type checks, finiteness checks, integer checks, positivity checks, and upper bound checks.

Residual risk: None for exact replay. An attacker cannot reorder messages (messages with out-of-order counters that are still higher than the last seen will be accepted, but will increment the counter floor, causing the "skipped" messages to be rejected if they arrive later).

Threat: An attacker gains physical access to a mobile device or developer laptop.

Mitigation:

• Cryptographic keys are stored in the OS secure keychain, which is encrypted at rest and requires device unlock (biometric or passcode) to access.
• Ephemeral session keys exist only in memory and are lost when the app is closed or the session disconnects.
• Session expiry (24h / 10k messages, being added) limits the window of exposure.

Residual risk: If the attacker can unlock the device, they can access the secure keychain and extract identity keys. This would allow them to impersonate the device in future key exchanges. Mitigation: users should remotely unpair compromised devices, which invalidates the relay-level routing.

Threat: An attacker obtains the shared session key for an active session.

Mitigation:

• Forward secrecy: Ephemeral X25519 key pairs are generated per session. Compromising long-term Ed25519 identity keys does NOT reveal past session keys (the identity keys are only used for signing, not for deriving shared secrets).
• Session expiry: 24-hour / 10,000-message session limits (implemented) bound the exposure window. After expiry, a new ECDH exchange is required.
• No key reuse: Each session uses a fresh ECDH exchange. Compromising one session key does not help with past or future sessions.

Residual risk: An attacker who obtains a session key can decrypt all messages within that single session until it expires. They cannot decrypt messages from other sessions.

Threat: The CLI on the developer's machine is compromised.

Mitigation: This is largely outside the E2EE threat model -- the CLI is a trusted endpoint. However:

• The ALLOWED_ENCRYPTED_EVENTS whitelist prevents a compromised CLI from injecting infrastructure events through the E2EE channel.
• The mobile app's permission system requires explicit user approval for sensitive tool executions.

Residual risk: A compromised CLI has access to the developer's machine and can execute arbitrary code. E2EE cannot protect against a compromised endpoint.

ForkOff uses static sessions (one ECDH per connection) rather than the Signal Protocol's Double Ratchet Algorithm. This is a deliberate choice:

The 24-hour / 10,000-message session expiry provides forward secrecy boundaries analogous to (though coarser than) the Double Ratchet's per-message forward secrecy. For a synchronous developer tool with short-lived sessions, this tradeoff is appropriate.

ForkOff does not use a Certificate Authority or any form of centralized public key infrastructure. Identity keys are pinned on first contact (TOFU), similar to SSH's known_hosts model. This is acceptable because:

1. Physical proximity at pairing: Devices pair via QR code scan, establishing the initial trust anchor in a setting where the user can verify both devices are theirs.
2. Loud key mismatch warnings: Any change in a previously seen identity key produces an explicit, blocking error that prevents the exchange from completing.
3. Technical audience: ForkOff's users are developers who understand key verification concepts and can evaluate key mismatch warnings.
4. No central trust dependency: There is no CA to compromise, no certificate chain to validate, and no revocation infrastructure to maintain.

ForkOff uses TweetNaCl (a JavaScript port of NaCl) rather than the browser's Web Crypto API:

1. Cross-platform consistency: TweetNaCl provides identical behavior on React Native (Hermes), Node.js, and browsers. Web Crypto API availability and behavior varies across these environments.
2. Misuse resistance: NaCl's API is designed to be hard to misuse. There is no algorithm negotiation (which would enable downgrade attacks), no mode selection, and no padding scheme to get wrong.
3. Well-analyzed construction: XSalsa20-Poly1305 is a Bernstein construction with extensive academic analysis. The box.before() function combines X25519 ECDH with HSalsa20 key derivation in a single, well-studied operation.
4. Deterministic nonce size: NaCl's 24-byte nonces are large enough that random nonce selection has negligible collision probability (birthday bound ~2^96), eliminating the need for nonce counters or nonce-misuse-resistant modes.

ForkOff is not currently certified for any compliance framework. The following mapping is provided for informational purposes to assist organizations evaluating ForkOff against their compliance requirements.

E2EE constitutes an "appropriate technical measure" for ensuring the security of personal data processing. The relay server's inability to access plaintext data limits the scope of any data breach at the infrastructure level.

E2EE makes the relay server a non-BAA entity -- it never accesses, processes, or stores protected health information (PHI). Only the endpoints (mobile app and CLI) handle plaintext data, and these run on devices controlled by the end user.

• ForkOff has not undergone a formal third-party security audit.
• The compliance mappings above are informational and do not constitute certification or attestation.
• Organizations with specific compliance requirements should conduct their own evaluation.

If you discover a security vulnerability in ForkOff, please report it responsibly:

Email: security@forkoff.app

Guidelines:

• Please provide a clear description of the vulnerability, including steps to reproduce if possible.
• Allow reasonable time for the issue to be investigated and patched before public disclosure.
• Do not access, modify, or delete other users' data as part of your research.
• Do not perform denial-of-service attacks against ForkOff infrastructure.

What to expect:

• Acknowledgment of your report within 48 hours.
• Regular updates on the status of the investigation.
• Credit in the security advisory (unless you prefer to remain anonymous).

We appreciate the security research community's efforts in helping keep ForkOff and its users safe.

This document describes the security architecture of ForkOff as implemented. It is not a guarantee of security. The cryptographic implementation uses well-established primitives and constructions, but has not yet been formally audited. Use at your own risk.