forkoff 1.0.19 → 1.1.0

package/README.md

@@ -113,18 +113,20 @@ forkoff startup --status    # Check registration
 
 ## Security
 
-All communication between the CLI and mobile app is end-to-end encrypted. The relay server never sees plaintext session data.
+ForkOff uses end-to-end encryption (X25519 ECDH + XSalsa20-Poly1305) so the relay server never sees your code, prompts, or approvals — only opaque encrypted blobs routed between device UUIDs.
 
 | Layer | Implementation |
 |-------|---------------|
-| **Key exchange** | X25519 ECDH with Ed25519 identity signatures |
-| **Encryption** | XSalsa20-Poly1305 authenticated encryption (NaCl) |
+| **Key exchange** | X25519 ECDH with HKDF-SHA256 directional key derivation |
+| **Authentication** | Ed25519 identity signatures on ephemeral keys (MITM protection) |
+| **Encryption** | XSalsa20-Poly1305 authenticated encryption (NaCl secretbox) |
 | **Identity** | TOFU (Trust On First Use) with key pinning |
 | **Replay protection** | Per-peer monotonic message counters |
+| **Session expiry** | Automatic re-key every 24 hours or 10,000 messages |
 | **Key storage** | OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret) |
-| **Enforcement** | Sensitive events (session content, approvals, files) never sent in plaintext |
+| **Enforcement** | 24 sensitive event types encrypted; plaintext fallback only when E2EE unavailable |
 
-No additional setup required — E2EE is enabled automatically when you pair.
+No additional setup required — E2EE is enabled automatically when you pair. See [SECURITY.md](https://github.com/Forkoff-app/forkoff-cli/blob/main/docs/SECURITY.md) for the full whitepaper.
 
 ---
 

package/dist/cloud-client.d.ts

@@ -0,0 +1,30 @@
+import { EventEmitter } from 'events';
+export interface CloudRelayOptions {
+    url: string;
+    deviceId: string;
+    deviceName: string;
+    relayToken?: string | null;
+}
+export declare class CloudRelayClient extends EventEmitter {
+    private socket;
+    private url;
+    private deviceId;
+    private deviceName;
+    private relayToken;
+    /** The pairing code the CLI generated — sent to relay for registration */
+    private currentPairingCode;
+    constructor(options: CloudRelayOptions);
+    /** Set the pairing code — will be registered with the relay on connect */
+    setPairingCode(code: string): void;
+    /** Connect to the cloud relay as a CLI client */
+    start(): Promise<void>;
+    /** Emit an event to the mobile client via the relay */
+    emitToMobile(event: string, data: any): void;
+    /** Check if mobile is connected (based on relay notifications) */
+    hasMobileConnection(): boolean;
+    /** Get the connected mobile device ID (set after pairing or mobile_connected) */
+    getMobileDeviceId(): string | null;
+    /** Graceful shutdown */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=cloud-client.d.ts.map

package/dist/cloud-client.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudRelayClient = void 0;
+/**
+ * Cloud relay client — CLI connects as a Socket.io CLIENT to the relay server
+ * (e.g., wss://api.forkoff.app). The relay routes events to/from the paired mobile.
+ * Same interface as EmbeddedRelayServer so WebSocketClient can use either.
+ */
+const socket_io_client_1 = require("socket.io-client");
+const events_1 = require("events");
+const config_1 = require("./config");
+/** Events the cloud relay forwards from mobile → CLI (same set as EmbeddedRelayServer) */
+const MOBILE_EVENTS = [
+    'terminal_command', 'terminal_create', 'user_message',
+    'claude_start_session', 'claude_resume_session', 'claude_sessions_request',
+    'directory_list', 'read_file', 'transcript_fetch', 'transcript_subscribe',
+    'transcript_unsubscribe', 'approval_response', 'claude_approval_response',
+    'permission_response', 'permission_rules_sync', 'claude_abort', 'tab_complete',
+    'subscribe_device', 'unsubscribe_device',
+    'sdk_session_history', 'usage_stats_request', 'session_settings_update',
+    'transcript_subscribe_sdk',
+    // E2EE key exchange and encrypted messages from mobile
+    'encrypted_key_exchange_init', 'encrypted_key_exchange_ack', 'encrypted_message',
+];
+class CloudRelayClient extends events_1.EventEmitter {
+    constructor(options) {
+        super();
+        this.socket = null;
+        /** The pairing code the CLI generated — sent to relay for registration */
+        this.currentPairingCode = null;
+        this.url = options.url;
+        this.deviceId = options.deviceId;
+        this.deviceName = options.deviceName;
+        this.relayToken = options.relayToken ?? null;
+    }
+    /** Set the pairing code — will be registered with the relay on connect */
+    setPairingCode(code) {
+        this.currentPairingCode = code;
+        // If already connected, register immediately
+        if (this.socket?.connected) {
+            this.socket.emit('register_pairing_code', {
+                code,
+                deviceId: this.deviceId,
+                deviceName: this.deviceName,
+                platform: process.platform,
+            });
+        }
+    }
+    /** Connect to the cloud relay as a CLI client */
+    start() {
+        return new Promise((resolve, reject) => {
+            this.socket = (0, socket_io_client_1.io)(this.url, {
+                auth: {
+                    clientType: 'cli',
+                    deviceId: this.deviceId,
+                    deviceName: this.deviceName,
+                    platform: process.platform,
+                    hostname: require('os').hostname(),
+                    relayToken: this.relayToken,
+                    userId: config_1.config.userId,
+                },
+                transports: ['websocket'],
+                reconnection: true,
+                reconnectionAttempts: Infinity,
+                reconnectionDelay: 1000,
+                reconnectionDelayMax: 15000,
+                timeout: 10000,
+            });
+            let resolved = false;
+            this.socket.on('connect', () => {
+                console.log(`[CloudRelay] Connected to ${this.url}`);
+                // Register pairing code if we have one
+                if (this.currentPairingCode) {
+                    this.socket.emit('register_pairing_code', {
+                        code: this.currentPairingCode,
+                        deviceId: this.deviceId,
+                        deviceName: this.deviceName,
+                        platform: process.platform,
+                    });
+                }
+                if (!resolved) {
+                    resolved = true;
+                    resolve();
+                }
+            });
+            this.socket.on('connect_error', (err) => {
+                console.error(`[CloudRelay] Connection error: ${err.message}`);
+                if (!resolved) {
+                    resolved = true;
+                    reject(new Error(`Failed to connect to cloud relay at ${this.url}: ${err.message}`));
+                }
+            });
+            this.socket.on('disconnect', (reason) => {
+                console.log(`[CloudRelay] Disconnected: ${reason}`);
+            });
+            // Handle cloud pairing flow: relay sends pair_device when mobile enters our code
+            this.socket.on('pair_device', (data) => {
+                console.log(`[CloudRelay] Pairing request received from mobile`);
+                // Emit internally so WebSocketClient can handle it
+                this.emit('pair_device', { mobileDeviceId: data.mobileDeviceId });
+                // Send ack back through relay — relay will forward to mobile with mobileRelayToken
+                this.socket.emit('pair_device_ack', {
+                    deviceId: this.deviceId,
+                    deviceName: this.deviceName,
+                    platform: process.platform,
+                    mobileDeviceId: data.mobileDeviceId,
+                    pairId: data.pairId,
+                    cliRelayToken: data.cliRelayToken,
+                });
+                // Store relay credentials locally
+                if (data.cliRelayToken) {
+                    config_1.config.relayToken = data.cliRelayToken;
+                    this.relayToken = data.cliRelayToken;
+                }
+                if (data.pairId) {
+                    config_1.config.pairId = data.pairId;
+                }
+            });
+            // Handle mobile connected notification from relay
+            this.socket.on('mobile_connected', (data) => {
+                console.log(`[CloudRelay] Mobile connected: ${data.deviceId || 'unknown'}`);
+                this.emit('mobile_connected', { deviceId: data.deviceId || data.mobileDeviceId });
+            });
+            // Handle mobile disconnected notification from relay
+            this.socket.on('mobile_disconnected', (data) => {
+                console.log(`[CloudRelay] Mobile disconnected`);
+                this.emit('mobile_disconnected', { deviceId: data.deviceId, reason: data.reason || 'disconnected' });
+            });
+            // Forward all mobile events → internal EventEmitter (same as EmbeddedRelayServer)
+            for (const event of MOBILE_EVENTS) {
+                this.socket.on(event, (data) => {
+                    this.emit(event, data);
+                });
+            }
+        });
+    }
+    /** Emit an event to the mobile client via the relay */
+    emitToMobile(event, data) {
+        if (this.socket?.connected) {
+            // Relay will route this to the paired mobile client
+            this.socket.emit(event, data);
+        }
+    }
+    /** Check if mobile is connected (based on relay notifications) */
+    hasMobileConnection() {
+        return this.socket?.connected ?? false;
+    }
+    /** Get the connected mobile device ID (set after pairing or mobile_connected) */
+    getMobileDeviceId() {
+        // The relay manages this — we don't track directly in cloud mode
+        return null;
+    }
+    /** Graceful shutdown */
+    stop() {
+        return new Promise((resolve) => {
+            if (this.socket) {
+                this.socket.disconnect();
+                this.socket = null;
+            }
+            resolve();
+        });
+    }
+}
+exports.CloudRelayClient = CloudRelayClient;
+//# sourceMappingURL=cloud-client.js.map

package/dist/config.d.ts

@@ -25,6 +25,12 @@ declare class Config {
     set startupBinaryPath(value: string | null);
     get relayPort(): number;
     set relayPort(value: number);
+    get relayMode(): 'cloud' | 'local';
+    set relayMode(value: 'cloud' | 'local');
+    get relayToken(): string | null;
+    set relayToken(value: string | null);
+    get pairId(): string | null;
+    set pairId(value: string | null);
     get isPaired(): boolean;
     ensureDeviceId(): string;
     getMachineId(): string;

package/dist/config.js

@@ -87,6 +87,9 @@ const defaultConfig = {
     userId: null,
     startupEnabled: true,
     startupBinaryPath: null,
+    relayMode: 'cloud',
+    relayToken: null,
+    pairId: null,
 };
 class Config {
     constructor() {
@@ -221,6 +224,27 @@ class Config {
         this.data.relayPort = value;
         this.save();
     }
+    get relayMode() {
+        return this.data.relayMode;
+    }
+    set relayMode(value) {
+        this.data.relayMode = value;
+        this.save();
+    }
+    get relayToken() {
+        return this.data.relayToken;
+    }
+    set relayToken(value) {
+        this.data.relayToken = value;
+        this.save();
+    }
+    get pairId() {
+        return this.data.pairId;
+    }
+    set pairId(value) {
+        this.data.pairId = value;
+        this.save();
+    }
     get isPaired() {
         return !!this.deviceId && !!this.pairedAt;
     }

package/dist/crypto/e2eeManager.d.ts

@@ -5,6 +5,8 @@ export declare class E2EEManager {
     private signingKeyPair;
     private initialized;
     private sessions;
+    private static readonly SESSION_MAX_AGE_MS;
+    private static readonly SESSION_MAX_MESSAGES;
     private static readonly MAX_PENDING_EXCHANGES;
     private static readonly PENDING_EXCHANGE_TTL_MS;
     private pendingExchanges;
@@ -19,6 +21,11 @@ export declare class E2EEManager {
     getSigningPublicKey(): string | null;
     /** Check if manager is initialized */
     isInitialized(): boolean;
+    /**
+     * Check if a session has expired (age or message count).
+     * Returns true if the session should be torn down and re-keyed.
+     */
+    isSessionExpired(deviceId: string): boolean;
     /**
      * Sign a key exchange payload with our Ed25519 identity key.
      * The signed message is: "prefix:senderDeviceId:ephemeralPublicKey[:recipientDeviceId]"
@@ -52,6 +59,7 @@ export declare class E2EEManager {
     handleKeyExchangeAck(ack: KeyExchangeAck): void;
     /**
      * Attempts to restore a persisted session after reconnection.
+     * If the session has expired, it is deleted from persistence and not restored.
      */
     restorePersistedSession(targetDeviceId: string): Promise<boolean>;
     /** Lists all devices with persisted sessions */

package/dist/crypto/e2eeManager.js

@@ -82,6 +82,25 @@ class E2EEManager {
     isInitialized() {
         return this.initialized;
     }
+    /**
+     * Check if a session has expired (age or message count).
+     * Returns true if the session should be torn down and re-keyed.
+     */
+    isSessionExpired(deviceId) {
+        const session = this.sessions.get(deviceId);
+        if (!session)
+            return false;
+        if (Date.now() - session.createdAt > E2EEManager.SESSION_MAX_AGE_MS) {
+            return true;
+        }
+        if (session.outgoingCounter >= E2EEManager.SESSION_MAX_MESSAGES) {
+            return true;
+        }
+        if (session.lastReceivedCounter >= E2EEManager.SESSION_MAX_MESSAGES) {
+            return true;
+        }
+        return false;
+    }
     /**
      * Sign a key exchange payload with our Ed25519 identity key.
      * The signed message is: "prefix:senderDeviceId:ephemeralPublicKey[:recipientDeviceId]"
@@ -178,22 +197,32 @@ class E2EEManager {
         // Verify peer's signature (TOFU)
         this.verifyPeerSignature(init.senderDeviceId, init.identityPublicKey, init.signature, init.ephemeralPublicKey, 'KEY_EXCHANGE_INIT');
         const ephemeral = (0, keyGeneration_1.generateKeyPair)();
-        const sharedKey = (0, keyExchange_1.computeSharedKey)(ephemeral.privateKey, init.ephemeralPublicKey);
+        const rawSharedKey = (0, keyExchange_1.computeSharedKey)(ephemeral.privateKey, init.ephemeralPublicKey);
+        // Derive directional send/receive keys via HKDF
+        const { sendKey, receiveKey } = (0, keyExchange_1.deriveSessionKeys)(rawSharedKey, this.deviceId, init.senderDeviceId);
+        // Log key fingerprint for debugging key mismatch
+        const sendKeyFP = (0, tweetnacl_util_1.encodeBase64)(sendKey).substring(0, 12);
+        const recvKeyFP = (0, tweetnacl_util_1.encodeBase64)(receiveKey).substring(0, 12);
+        console.log(`[E2EE] Init: sendKey=${sendKeyFP}, recvKey=${recvKeyFP}, peer=${init.senderDeviceId}, myEphPub=${ephemeral.publicKey.substring(0, 12)}, peerEphPub=${init.ephemeralPublicKey.substring(0, 12)}`);
         // Store session
         const sessionId = `session-${init.senderDeviceId}-${this.deviceId}-${Date.now()}`;
         this.sessions.set(init.senderDeviceId, {
-            sharedKey,
+            sendKey,
+            receiveKey,
             outgoingCounter: 0,
             lastReceivedCounter: -1,
+            createdAt: Date.now(),
         });
-        (0, keyStorage_1.storeSessionKey)(init.senderDeviceId, sharedKey, sessionId);
+        (0, keyStorage_1.storeSessionKey)(init.senderDeviceId, sendKey, receiveKey, sessionId);
         // Persist to disk for reconnection resilience
         const sessionKeys = {
-            sharedKey,
+            sendKey,
+            receiveKey,
             sessionId,
             deviceId: init.senderDeviceId,
             messageCounter: 0,
             lastReceivedCounter: -1,
+            createdAt: Date.now(),
         };
         (0, sessionPersistence_1.persistSessionKey)(this.deviceId, init.senderDeviceId, sessionKeys);
         // E2EE session established
@@ -213,36 +242,57 @@ class E2EEManager {
      */
     handleKeyExchangeAck(ack) {
         const peerId = ack.senderDeviceId;
-        const pendingEntry = this.pendingExchanges.get(peerId);
+        let pendingEntry = this.pendingExchanges.get(peerId);
+        let pendingKey = peerId;
+        // Fallback: relay may send mobile_connected with a different ID than the mobile's
+        // real device ID, so the pending exchange may be stored under a different key.
+        // If there's exactly one pending exchange, use it regardless of key.
+        if (!pendingEntry && this.pendingExchanges.size === 1) {
+            const [fallbackKey, fallbackEntry] = this.pendingExchanges.entries().next().value;
+            console.log(`[E2EE] Pending exchange not found for ${peerId}, falling back to ${fallbackKey}`);
+            pendingEntry = fallbackEntry;
+            pendingKey = fallbackKey;
+        }
         if (!pendingEntry) {
             throw new Error(`E2EE: No pending key exchange for device ${peerId}`);
         }
         const pending = pendingEntry.keyPair;
         // Verify peer's signature (TOFU)
         this.verifyPeerSignature(peerId, ack.identityPublicKey, ack.signature, ack.ephemeralPublicKey, 'KEY_EXCHANGE_ACK', ack.recipientDeviceId);
-        const sharedKey = (0, keyExchange_1.computeSharedKey)(pending.privateKey, ack.ephemeralPublicKey);
+        const rawSharedKey = (0, keyExchange_1.computeSharedKey)(pending.privateKey, ack.ephemeralPublicKey);
+        // Derive directional send/receive keys via HKDF
+        const { sendKey, receiveKey } = (0, keyExchange_1.deriveSessionKeys)(rawSharedKey, this.deviceId, peerId);
+        // Log key fingerprint for debugging key mismatch
+        const sendKeyFP = (0, tweetnacl_util_1.encodeBase64)(sendKey).substring(0, 12);
+        const recvKeyFP = (0, tweetnacl_util_1.encodeBase64)(receiveKey).substring(0, 12);
+        console.log(`[E2EE] Ack: sendKey=${sendKeyFP}, recvKey=${recvKeyFP}, peer=${peerId}, myEphPub=${pending.publicKey.substring(0, 12)}, peerEphPub=${ack.ephemeralPublicKey.substring(0, 12)}`);
         // Store session
         const sessionId = `session-${this.deviceId}-${peerId}-${Date.now()}`;
         this.sessions.set(peerId, {
-            sharedKey,
+            sendKey,
+            receiveKey,
             outgoingCounter: 0,
             lastReceivedCounter: -1,
+            createdAt: Date.now(),
         });
-        (0, keyStorage_1.storeSessionKey)(peerId, sharedKey, sessionId);
+        (0, keyStorage_1.storeSessionKey)(peerId, sendKey, receiveKey, sessionId);
         // Persist to disk
         const sessionKeys = {
-            sharedKey,
+            sendKey,
+            receiveKey,
             sessionId,
             deviceId: peerId,
             messageCounter: 0,
             lastReceivedCounter: -1,
+            createdAt: Date.now(),
         };
         (0, sessionPersistence_1.persistSessionKey)(this.deviceId, peerId, sessionKeys);
-        this.pendingExchanges.delete(peerId);
+        this.pendingExchanges.delete(pendingKey);
         // E2EE session established
     }
     /**
      * Attempts to restore a persisted session after reconnection.
+     * If the session has expired, it is deleted from persistence and not restored.
      */
     async restorePersistedSession(targetDeviceId) {
         const persisted = (0, sessionPersistence_1.loadPersistedSessionKey)(this.deviceId, targetDeviceId);
@@ -250,11 +300,20 @@ class E2EEManager {
             return false;
         }
         this.sessions.set(targetDeviceId, {
-            sharedKey: persisted.sharedKey,
+            sendKey: persisted.sendKey,
+            receiveKey: persisted.receiveKey,
             outgoingCounter: persisted.messageCounter,
             lastReceivedCounter: persisted.lastReceivedCounter,
+            createdAt: persisted.createdAt ?? Date.now(),
         });
-        (0, keyStorage_1.storeSessionKey)(targetDeviceId, persisted.sharedKey, persisted.sessionId);
+        // Check if the restored session is already expired
+        if (this.isSessionExpired(targetDeviceId)) {
+            console.log(`[E2EE] Persisted session with ${targetDeviceId} has expired — deleting`);
+            this.sessions.delete(targetDeviceId);
+            (0, sessionPersistence_1.deletePersistedSession)(this.deviceId, targetDeviceId);
+            return false;
+        }
+        (0, keyStorage_1.storeSessionKey)(targetDeviceId, persisted.sendKey, persisted.receiveKey, persisted.sessionId);
         // Restored persisted E2EE session
         return true;
     }
@@ -272,8 +331,18 @@ class E2EEManager {
         if (!session) {
             throw new Error(`E2EE: No session established with device ${recipientDeviceId}`);
         }
-        const payload = (0, encryption_1.encrypt)(plaintext, session.sharedKey);
+        // Check session expiry BEFORE encrypting — force re-key
+        if (this.isSessionExpired(recipientDeviceId)) {
+            this.sessions.delete(recipientDeviceId);
+            throw new Error(`E2EE: Session expired with device ${recipientDeviceId} — re-key required`);
+        }
+        const payload = (0, encryption_1.encrypt)(plaintext, session.sendKey);
         session.outgoingCounter++;
+        // Log encryption key fingerprint (first message only to avoid spam)
+        if (session.outgoingCounter === 1) {
+            const keyFP = (0, tweetnacl_util_1.encodeBase64)(session.sendKey).substring(0, 12);
+            console.log(`[E2EE] Encrypting first message with sendKey fingerprint=${keyFP}, recipient=${recipientDeviceId}`);
+        }
         return {
             senderDeviceId: this.deviceId,
             recipientDeviceId,
@@ -301,8 +370,12 @@ class E2EEManager {
         if (message.messageCounter <= session.lastReceivedCounter) {
             throw new Error('E2EE: Replay attack detected - message counter too low');
         }
-        const plaintext = (0, encryption_1.decrypt)(message.payload, session.sharedKey);
+        const plaintext = (0, encryption_1.decrypt)(message.payload, session.receiveKey);
         session.lastReceivedCounter = message.messageCounter;
+        // Check expiry AFTER decrypting — valid messages still get through, but warn caller
+        if (this.isSessionExpired(senderDeviceId)) {
+            console.warn(`[E2EE] Session with ${senderDeviceId} has expired after decryption — re-key required`);
+        }
         return plaintext;
     }
     /** Clear session for a specific device */
@@ -339,6 +412,9 @@ class E2EEManager {
     }
 }
 exports.E2EEManager = E2EEManager;
+// Session expiry limits — re-key required after either threshold
+E2EEManager.SESSION_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+E2EEManager.SESSION_MAX_MESSAGES = 10000;
 // Ephemeral keys for pending key exchanges (with creation timestamp for TTL)
 E2EEManager.MAX_PENDING_EXCHANGES = 20;
 E2EEManager.PENDING_EXCHANGE_TTL_MS = 5 * 60 * 1000; // 5 minutes

package/dist/crypto/index.d.ts

@@ -2,7 +2,7 @@
  * E2EE Crypto Module - Barrel Export
  */
 export { generateKeyPair } from './keyGeneration';
-export { computeSharedKey } from './keyExchange';
+export { computeSharedKey, deriveSessionKeys } from './keyExchange';
 export { encrypt, decrypt } from './encryption';
 export { storePrivateKey, getPrivateKey, storeSessionKey, getSessionKey, clearSessionKeys } from './keyStorage';
 export { E2EEManager } from './e2eeManager';

package/dist/crypto/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.E2EEManager = exports.clearSessionKeys = exports.getSessionKey = exports.storeSessionKey = exports.getPrivateKey = exports.storePrivateKey = exports.decrypt = exports.encrypt = exports.computeSharedKey = exports.generateKeyPair = void 0;
+exports.E2EEManager = exports.clearSessionKeys = exports.getSessionKey = exports.storeSessionKey = exports.getPrivateKey = exports.storePrivateKey = exports.decrypt = exports.encrypt = exports.deriveSessionKeys = exports.computeSharedKey = exports.generateKeyPair = void 0;
 /**
  * E2EE Crypto Module - Barrel Export
  */
@@ -8,6 +8,7 @@ var keyGeneration_1 = require("./keyGeneration");
 Object.defineProperty(exports, "generateKeyPair", { enumerable: true, get: function () { return keyGeneration_1.generateKeyPair; } });
 var keyExchange_1 = require("./keyExchange");
 Object.defineProperty(exports, "computeSharedKey", { enumerable: true, get: function () { return keyExchange_1.computeSharedKey; } });
+Object.defineProperty(exports, "deriveSessionKeys", { enumerable: true, get: function () { return keyExchange_1.deriveSessionKeys; } });
 var encryption_1 = require("./encryption");
 Object.defineProperty(exports, "encrypt", { enumerable: true, get: function () { return encryption_1.encrypt; } });
 Object.defineProperty(exports, "decrypt", { enumerable: true, get: function () { return encryption_1.decrypt; } });

package/dist/crypto/keyExchange.d.ts

@@ -7,4 +7,22 @@
  * @returns 32-byte shared key suitable for NaCl secretbox encryption
  */
 export declare function computeSharedKey(myPrivateKeyB64: string, theirPublicKeyB64: string): Uint8Array;
+/**
+ * Derive directional send/receive keys from the raw ECDH shared secret using HKDF-SHA256.
+ *
+ * Both sides must derive identical key material. Directionality is determined by
+ * lexicographic ordering of device IDs:
+ * - The device with the lexicographically smaller ID gets bytes 0-31 as sendKey
+ * - The device with the lexicographically larger ID gets bytes 32-63 as sendKey
+ * - receiveKey is always the opposite half
+ *
+ * @param rawSharedKey - 32-byte ECDH output from computeSharedKey
+ * @param myDeviceId - This device's ID
+ * @param peerDeviceId - The remote device's ID
+ * @returns { sendKey, receiveKey } - 32-byte directional keys
+ */
+export declare function deriveSessionKeys(rawSharedKey: Uint8Array, myDeviceId: string, peerDeviceId: string): {
+    sendKey: Uint8Array;
+    receiveKey: Uint8Array;
+};
 //# sourceMappingURL=keyExchange.d.ts.map

package/dist/crypto/keyExchange.js

@@ -4,13 +4,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeSharedKey = computeSharedKey;
+exports.deriveSessionKeys = deriveSessionKeys;
 /**
  * Key Exchange Service
- * Performs X25519 Diffie-Hellman key exchange using NaCl box.before.
+ * Performs X25519 Diffie-Hellman key exchange using NaCl box.before,
+ * then derives directional send/receive keys via HKDF-SHA256.
  * Compatible with mobile app's tweetnacl implementation.
  */
 const tweetnacl_1 = __importDefault(require("tweetnacl"));
 const tweetnacl_util_1 = require("tweetnacl-util");
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha256_1 = require("@noble/hashes/sha256");
 /**
  * Compute a shared secret key from a private key and a remote public key.
  * Uses NaCl's box.before which performs X25519 ECDH + HSalsa20 key derivation.
@@ -24,4 +28,36 @@ function computeSharedKey(myPrivateKeyB64, theirPublicKeyB64) {
     const theirPublicKey = (0, tweetnacl_util_1.decodeBase64)(theirPublicKeyB64);
     return tweetnacl_1.default.box.before(theirPublicKey, myPrivateKey);
 }
+/**
+ * Derive directional send/receive keys from the raw ECDH shared secret using HKDF-SHA256.
+ *
+ * Both sides must derive identical key material. Directionality is determined by
+ * lexicographic ordering of device IDs:
+ * - The device with the lexicographically smaller ID gets bytes 0-31 as sendKey
+ * - The device with the lexicographically larger ID gets bytes 32-63 as sendKey
+ * - receiveKey is always the opposite half
+ *
+ * @param rawSharedKey - 32-byte ECDH output from computeSharedKey
+ * @param myDeviceId - This device's ID
+ * @param peerDeviceId - The remote device's ID
+ * @returns { sendKey, receiveKey } - 32-byte directional keys
+ */
+function deriveSessionKeys(rawSharedKey, myDeviceId, peerDeviceId) {
+    // Salt: sorted concatenation of both device IDs (deterministic regardless of who calls)
+    const sortedIds = [myDeviceId, peerDeviceId].sort();
+    const salt = (0, tweetnacl_util_1.decodeUTF8)(sortedIds[0] + sortedIds[1]);
+    // Info string identifying the protocol version
+    const info = (0, tweetnacl_util_1.decodeUTF8)('forkoff-e2ee-v1');
+    // Derive 64 bytes of key material
+    const derivedKeyMaterial = (0, hkdf_1.hkdf)(sha256_1.sha256, rawSharedKey, salt, info, 64);
+    // Split into two 32-byte keys
+    const firstHalf = derivedKeyMaterial.slice(0, 32);
+    const secondHalf = derivedKeyMaterial.slice(32, 64);
+    // Directionality: device with smaller ID gets firstHalf as sendKey
+    const iAmSmaller = myDeviceId < peerDeviceId;
+    return {
+        sendKey: iAmSmaller ? firstHalf : secondHalf,
+        receiveKey: iAmSmaller ? secondHalf : firstHalf,
+    };
+}
 //# sourceMappingURL=keyExchange.js.map

package/dist/crypto/keyStorage.d.ts

@@ -17,14 +17,15 @@ export declare function getPrivateKey(deviceId: string): Promise<string | null>;
  */
 export declare function deletePrivateKey(deviceId: string): Promise<void>;
 /**
- * Stores session key in memory
+ * Stores session keys in memory
  * Session keys are ephemeral and not persisted to disk
  *
  * @param deviceId - Target device ID
- * @param sharedKey - NaCl secretbox shared key (32 bytes)
+ * @param sendKey - 32-byte directional key for encrypting outgoing messages
+ * @param receiveKey - 32-byte directional key for decrypting incoming messages
  * @param sessionId - Unique session identifier
  */
-export declare function storeSessionKey(deviceId: string, sharedKey: Uint8Array, sessionId: string): void;
+export declare function storeSessionKey(deviceId: string, sendKey: Uint8Array, receiveKey: Uint8Array, sessionId: string): void;
 /**
  * Retrieves session key from memory
  * @param deviceId - Target device ID

package/dist/crypto/keyStorage.js

@@ -105,16 +105,18 @@ async function deletePrivateKey(deviceId) {
     }
 }
 /**
- * Stores session key in memory
+ * Stores session keys in memory
  * Session keys are ephemeral and not persisted to disk
  *
  * @param deviceId - Target device ID
- * @param sharedKey - NaCl secretbox shared key (32 bytes)
+ * @param sendKey - 32-byte directional key for encrypting outgoing messages
+ * @param receiveKey - 32-byte directional key for decrypting incoming messages
  * @param sessionId - Unique session identifier
  */
-function storeSessionKey(deviceId, sharedKey, sessionId) {
+function storeSessionKey(deviceId, sendKey, receiveKey, sessionId) {
     sessionKeyStore.set(deviceId, {
-        sharedKey,
+        sendKey,
+        receiveKey,
         sessionId,
         deviceId,
         messageCounter: 0,