forkoff 1.0.17 → 1.0.19

package/LICENSE

@@ -1,12 +1,16 @@
-Copyright (c) 2026 ForkOff. All rights reserved.
+MIT License
 
-This software and associated documentation files (the "Software") are the
-proprietary property of ForkOff. The Software is provided for viewing and
-reference purposes only.
+Copyright (c) 2026 ForkOff
 
-No part of the Software may be copied, modified, merged, published,
-distributed, sublicensed, sold, or otherwise used without the prior written
-permission of ForkOff.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

package/README.md

@@ -5,37 +5,31 @@
 <h1 align="center">ForkOff CLI</h1>
 
 <p align="center">
-  <strong>Bridge your AI coding tools to your mobile device</strong>
+  <strong>Control your AI coding sessions from your phone</strong>
 </p>
 
-> ## 🚀 **OPEN BETA**
->
-> ForkOff is now in **open beta**! Download the mobile app and get started:
->
-> 📱 **[Join the TestFlight Beta](https://testflight.apple.com/join/dhh5FrN7)**
-
----
+<p align="center">
+  <a href="https://www.npmjs.com/package/forkoff"><img src="https://img.shields.io/npm/v/forkoff.svg" alt="npm version"></a>
+  <a href="https://github.com/Forkoff-app/forkoff-cli/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/forkoff.svg" alt="MIT License"></a>
+  <a href="https://www.npmjs.com/package/forkoff"><img src="https://img.shields.io/npm/dm/forkoff.svg" alt="npm downloads"></a>
+</p>
 
 <p align="center">
-  <a href="https://forkoff.app">Website</a> •
-  <a href="#installation">Installation</a> •
-  <a href="#quick-start">Quick Start</a> •
-  <a href="#commands">Commands</a> •
-  <a href="#programmatic-usage">API</a> •
-  <a href="#configuration">Configuration</a>
+  <a href="https://forkoff.app">Website</a> &bull;
+  <a href="#installation">Installation</a> &bull;
+  <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#commands">Commands</a> &bull;
+  <a href="#programmatic-usage">API</a> &bull;
+  <a href="#security">Security</a>
 </p>
 
 ---
 
-## Overview
+ForkOff CLI connects [Claude Code](https://claude.ai/code) on your laptop to the ForkOff mobile app, giving you real-time monitoring, interactive approvals, and usage analytics from anywhere.
 
-ForkOff CLI connects your development machine to the ForkOff mobile app, enabling you to:
-
-- **Control AI coding sessions** from your phone
-- **Approve code changes** on the go
-- **Send prompts** to Claude, Cursor, and other AI tools
-- **Monitor progress** in real-time
-- **Get notifications** for permission requests
+> **Open Source** &mdash; ForkOff CLI is now MIT licensed. Contributions welcome!
+>
+> **Open Beta** &mdash; [Join the iOS TestFlight](https://testflight.apple.com/join/dhh5FrN7)
 
 ## Installation
 
@@ -45,24 +39,35 @@ npm install -g forkoff
 
 ## Quick Start
 
-### 1. Pair with Mobile App
+### 1. Pair with your phone
 
 ```bash
 forkoff pair
 ```
 
-Scan the QR code with your ForkOff mobile app to link your device.
+Scan the QR code with the ForkOff mobile app to link your device.
 
-### 2. Stay Connected
+### 2. Stay connected
 
 ```bash
 forkoff connect
 ```
 
-Keep this running to receive commands from your mobile app.
+Keep this running to stream sessions to your phone in real-time.
 
 ---
 
+## Features
+
+- **Real-time session monitoring** &mdash; See Claude Code output on your phone as it happens
+- **Interactive approvals** &mdash; Approve or deny tool use (file edits, bash commands) from mobile
+- **Configurable permission rules** &mdash; Auto-approve safe tools, require approval for destructive ones
+- **End-to-end encryption** &mdash; All session data encrypted between CLI and mobile
+- **Usage analytics** &mdash; Track token usage, session counts, and streaks across devices
+- **Multi-device support** &mdash; Connect multiple CLI instances, analytics aggregate automatically
+- **Auto-start** &mdash; Optionally launch on login so your phone is always connected
+- **Direct P2P connection** &mdash; Embedded relay server, no cloud dependency for session data
+
 ## Commands
 
 | Command | Description |
@@ -70,31 +75,18 @@ Keep this running to receive commands from your mobile app.
 | `forkoff pair` | Generate QR code to pair with mobile app |
 | `forkoff connect` | Connect and listen for commands |
 | `forkoff status` | Check connection status |
-| `forkoff disconnect` | Disconnect from server |
+| `forkoff disconnect` | Disconnect and unpair device |
 | `forkoff config` | View/modify configuration |
 | `forkoff startup` | Manage automatic startup on login |
-| `forkoff startup --enable` | Enable automatic startup |
-| `forkoff startup --disable` | Disable automatic startup |
-| `forkoff startup --status` | Show startup registration status |
-| `forkoff help` | Show available commands and usage |
+| `forkoff tools` | Detect AI coding tools on your machine |
+| `forkoff logs` | List debug log files for troubleshooting |
 
-### Configuration Options
+### Configuration
 
 ```bash
-# Show current configuration
-forkoff config --show
-
-# Set custom API URL
-forkoff config --api https://your-server.com/api
-
-# Set custom WebSocket URL
-forkoff config --ws wss://your-server.com
-
-# Set device name
-forkoff config --name "My MacBook Pro"
-
-# Reset all configuration
-forkoff config --reset
+forkoff config --show            # Show current config
+forkoff config --name "My MBP"   # Set device name
+forkoff config --reset           # Reset to defaults
 ```
 
 ### Global Options
@@ -102,93 +94,64 @@ forkoff config --reset
 | Option | Description |
 |--------|-------------|
 | `-q, --quiet` | Suppress all output (for background operation) |
-
-### Background Operation
-
-Run ForkOff silently in the background with no console output:
-
-```bash
-forkoff connect --quiet
-```
-
-This is used by the automatic startup feature and is useful for running ForkOff as a background service.
+| `--debug` | Enable debug logging to file (`~/.forkoff-cli/logs/`) |
 
 ### Automatic Startup
 
-ForkOff automatically starts on login so your device stays connected without manual intervention. Startup is **enabled by default** — when you run `forkoff pair` or `forkoff connect`, it registers itself to launch `forkoff connect --quiet` on login.
+Startup is enabled by default &mdash; `forkoff pair` and `forkoff connect` register the CLI to launch on login.
 
-- **Windows**: Adds a `ForkOffCLI` entry to the `HKCU\...\Run` registry key (no admin required)
-- **macOS**: Installs a launchd agent (`~/Library/LaunchAgents/app.forkoff.cli.plist`) with the explicit node binary path for nvm/fnm compatibility
-
-To disable automatic startup:
+- **Windows**: Registry key (`HKCU\...\Run`)
+- **macOS**: launchd agent (`~/Library/LaunchAgents/app.forkoff.cli.plist`)
 
 ```bash
-forkoff startup --disable
+forkoff startup --disable   # Disable auto-start
+forkoff startup --enable    # Re-enable
+forkoff startup --status    # Check registration
 ```
 
-Once disabled, `pair` and `connect` will not re-register startup. To re-enable:
+---
+
+## Security
 
-```bash
-forkoff startup --enable
-```
+All communication between the CLI and mobile app is end-to-end encrypted. The relay server never sees plaintext session data.
+
+| Layer | Implementation |
+|-------|---------------|
+| **Key exchange** | X25519 ECDH with Ed25519 identity signatures |
+| **Encryption** | XSalsa20-Poly1305 authenticated encryption (NaCl) |
+| **Identity** | TOFU (Trust On First Use) with key pinning |
+| **Replay protection** | Per-peer monotonic message counters |
+| **Key storage** | OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret) |
+| **Enforcement** | Sensitive events (session content, approvals, files) never sent in plaintext |
 
-Running `forkoff disconnect` also removes the startup registration.
+No additional setup required &mdash; E2EE is enabled automatically when you pair.
 
 ---
 
 ## Programmatic Usage
 
-Integrate ForkOff into your AI coding tools:
+Integrate ForkOff into your own AI coding tools:
 
 ```typescript
 import { createIntegration } from 'forkoff';
 
 const forkoff = createIntegration();
-
-// Connect to ForkOff server
 await forkoff.connect();
 
-// Handle incoming messages from mobile app
-forkoff.onMessageReceived((sessionId, content, requestedBy) => {
-  console.log(`Message from ${requestedBy}: ${content}`);
-
-  // Send a response
-  forkoff.sendMessage(sessionId, 'Processing your request...');
-});
-
-// Stream responses in real-time
-const stream = forkoff.startStreaming(sessionId);
-stream.write('Here is ');
-stream.write('a streaming ');
-stream.write('response.');
-stream.end();
-
 // Request approval for code changes
 const approval = await forkoff.requestApproval(
-  sessionId,
-  messageId,
-  'CODE_CHANGE',
-  'Add authentication middleware',
+  sessionId, messageId, 'CODE_CHANGE',
+  'Add auth middleware',
   { filePath: 'src/middleware/auth.ts', diff: '...' }
 );
 
-if (approval.status === 'approved') {
-  // Apply the changes
-}
-
-// Send terminal output
-forkoff.sendTerminalOutput(sessionId, '> npm install\n Done', 'stdout');
-forkoff.sendTerminalExit(sessionId, 0);
-
-// Update device status
-forkoff.setStatus('busy');
+// Stream terminal output
+forkoff.sendTerminalOutput(sessionId, '> npm install\nDone', 'stdout');
 ```
 
 ---
 
-## Configuration
-
-Configuration files are stored at:
+## Configuration Files
 
 | Platform | Location |
 |----------|----------|
@@ -196,26 +159,22 @@ Configuration files are stored at:
 | **macOS** | `~/Library/Preferences/forkoff-cli/config.json` |
 | **Linux** | `~/.config/forkoff-cli/config.json` |
 
----
-
-## Security
-
-Your data stays yours. All communication between the ForkOff CLI and your mobile device is protected with **end-to-end encryption (E2EE)**:
-
-- Messages, code, and commands are encrypted on-device before leaving your machine
-- The ForkOff server never sees your plaintext data — it only relays encrypted payloads
-- Each device pair establishes a unique encrypted channel using ephemeral key exchange
-- Session keys are derived per-connection, so even if one session is compromised, others remain secure
+## Development
 
-No additional setup required — E2EE is enabled automatically when you pair your device.
+```bash
+git clone https://github.com/Forkoff-app/forkoff-cli.git
+cd forkoff-cli
+npm install
+npm run dev       # Run with ts-node
+npm run build     # Compile TypeScript
+npm test          # Run tests
+```
 
 ## Requirements
 
 - Node.js 18+
-- ForkOff mobile app
+- [ForkOff mobile app](https://testflight.apple.com/join/dhh5FrN7) (iOS)
 
----
+## License
 
-<p align="center">
-  Made with ❤️ by the ForkOff team
-</p>
+[MIT](LICENSE)

package/dist/approval.d.ts

@@ -10,6 +10,7 @@ export interface PendingApproval {
     status: 'pending' | 'approved' | 'rejected';
 }
 declare class ApprovalManager extends EventEmitter {
+    private static readonly MAX_PENDING_APPROVALS;
     private pendingApprovals;
     private approvalCounter;
     /**

package/dist/approval.js

@@ -24,6 +24,14 @@ class ApprovalManager extends events_1.EventEmitter {
             createdAt: new Date(),
             status: 'pending',
         };
+        // Evict oldest if at cap
+        while (this.pendingApprovals.size >= ApprovalManager.MAX_PENDING_APPROVALS) {
+            const oldestKey = this.pendingApprovals.keys().next().value;
+            if (oldestKey)
+                this.pendingApprovals.delete(oldestKey);
+            else
+                break;
+        }
         this.pendingApprovals.set(id, approval);
         // Send to mobile app via WebSocket
         websocket_1.wsClient.sendApprovalRequest({
@@ -114,6 +122,7 @@ class ApprovalManager extends events_1.EventEmitter {
         }
     }
 }
+ApprovalManager.MAX_PENDING_APPROVALS = 50;
 exports.approvalManager = new ApprovalManager();
 exports.default = exports.approvalManager;
 //# sourceMappingURL=approval.js.map

package/dist/config.d.ts

@@ -23,7 +23,10 @@ declare class Config {
     set startupEnabled(value: boolean | null);
     get startupBinaryPath(): string | null;
     set startupBinaryPath(value: string | null);
+    get relayPort(): number;
+    set relayPort(value: number);
     get isPaired(): boolean;
+    ensureDeviceId(): string;
     getMachineId(): string;
     getDeviceInfo(): {
         name: string;

package/dist/config.js

@@ -44,17 +44,17 @@ function isLocalUrl(url) {
     try {
         const parsed = new URL(url);
         const host = parsed.hostname.toLowerCase();
-        return host === 'localhost' ||
-            host === '127.0.0.1' ||
-            host.startsWith('192.168.') ||
-            host.startsWith('10.') ||
-            host.startsWith('172.16.') ||
-            host.startsWith('172.17.') ||
-            host.startsWith('172.18.') ||
-            host.startsWith('172.19.') ||
-            host.startsWith('172.2') ||
-            host.startsWith('172.30.') ||
-            host.startsWith('172.31.');
+        if (host === 'localhost' || host === '127.0.0.1' ||
+            host.startsWith('192.168.') || host.startsWith('10.')) {
+            return true;
+        }
+        // Check 172.16.0.0 - 172.31.255.255
+        if (host.startsWith('172.')) {
+            const secondOctet = parseInt(host.split('.')[1], 10);
+            if (secondOctet >= 16 && secondOctet <= 31)
+                return true;
+        }
+        return false;
     }
     catch {
         return false;
@@ -81,6 +81,7 @@ const defaultConfig = {
     deviceName: os.hostname(),
     apiUrl: 'https://api.forkoff.app/api',
     wsUrl: 'wss://api.forkoff.app',
+    relayPort: 3000,
     pairingCode: null,
     pairedAt: null,
     userId: null,
@@ -97,15 +98,30 @@ class Config {
             ? path.join(process.env.APPDATA || os.homedir(), 'forkoff-cli')
             : path.join(os.homedir(), '.config', 'forkoff-cli');
         if (!fs.existsSync(configDir)) {
-            fs.mkdirSync(configDir, { recursive: true });
+            fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
         }
         return path.join(configDir, 'config.json');
     }
     load() {
         try {
             if (fs.existsSync(this.configPath)) {
-                const content = fs.readFileSync(this.configPath, 'utf-8');
-                return { ...defaultConfig, ...JSON.parse(content) };
+                // SECURITY: Atomic symlink check — open fd then fstat to avoid TOCTOU
+                const fd = fs.openSync(this.configPath, 'r');
+                try {
+                    const stat = fs.fstatSync(fd);
+                    // If the file was replaced with a symlink between open and fstat,
+                    // fstat returns the symlink target info. Check lstat separately.
+                    const lstat = fs.lstatSync(this.configPath);
+                    if (lstat.isSymbolicLink()) {
+                        console.error('[Security] Symlink detected at config file, refusing to read');
+                        return { ...defaultConfig };
+                    }
+                    const content = fs.readFileSync(fd, 'utf-8');
+                    return { ...defaultConfig, ...JSON.parse(content) };
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
             }
         }
         catch (error) {
@@ -114,7 +130,22 @@ class Config {
         return { ...defaultConfig };
     }
     save() {
-        fs.writeFileSync(this.configPath, JSON.stringify(this.data, null, 2));
+        // SECURITY: Atomic write via temp file + rename to prevent TOCTOU
+        const tmpPath = this.configPath + '.tmp.' + process.pid;
+        try {
+            // Write to temp file with restrictive permissions
+            fs.writeFileSync(tmpPath, JSON.stringify(this.data, null, 2), { encoding: 'utf-8', mode: 0o600 });
+            // Atomic rename (same filesystem)
+            fs.renameSync(tmpPath, this.configPath);
+        }
+        catch (err) {
+            // Clean up temp file on error
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch { /* ignore */ }
+            console.error('[Security] Failed to save config:', err.message);
+        }
     }
     get deviceId() {
         return this.data.deviceId;
@@ -183,8 +214,23 @@ class Config {
         this.data.startupBinaryPath = value;
         this.save();
     }
+    get relayPort() {
+        return this.data.relayPort;
+    }
+    set relayPort(value) {
+        this.data.relayPort = value;
+        this.save();
+    }
     get isPaired() {
-        return !!this.userId && !!this.deviceId;
+        return !!this.deviceId && !!this.pairedAt;
+    }
+    // Ensure deviceId exists, generating one if needed
+    ensureDeviceId() {
+        if (!this.data.deviceId) {
+            this.data.deviceId = this.getMachineId();
+            this.save();
+        }
+        return this.data.deviceId;
     }
     // Get unique machine identifier
     getMachineId() {

package/dist/crypto/e2eeManager.d.ts

@@ -1,82 +1,79 @@
 import { KeyExchangeInit, KeyExchangeAck, EncryptedMessage } from './types';
-/**
- * E2EE Manager for CLI
- * Orchestrates all end-to-end encryption operations
- */
 export declare class E2EEManager {
     private deviceId;
-    private apiUrl;
-    private authToken;
     private keyPair;
+    private signingKeyPair;
     private initialized;
-    private pendingKeyExchanges;
-    private outgoingCounters;
-    private incomingCounters;
-    private axiosInstance;
-    constructor(deviceId: string, apiUrl: string, authToken: string);
+    private sessions;
+    private static readonly MAX_PENDING_EXCHANGES;
+    private static readonly PENDING_EXCHANGE_TTL_MS;
+    private pendingExchanges;
+    constructor(deviceId: string);
     /**
-     * Initializes E2EE manager
-     * - Loads or generates key pair
-     * - Uploads public key to backend
+     * Initializes E2EE manager: loads or generates identity key pairs (DH + signing).
      */
     initialize(): Promise<void>;
+    /** Get the public key (for uploading to server) */
+    getPublicKey(): string | null;
+    /** Get the signing public key */
+    getSigningPublicKey(): string | null;
+    /** Check if manager is initialized */
+    isInitialized(): boolean;
     /**
-     * Derives X25519 public key from private key
+     * Sign a key exchange payload with our Ed25519 identity key.
+     * The signed message is: "prefix:senderDeviceId:ephemeralPublicKey[:recipientDeviceId]"
      */
-    private derivePublicKeyFromPrivateKey;
+    private signPayload;
     /**
-     * Uploads public key to backend
+     * Verify a peer's signature on a key exchange payload.
+     * Returns true if signature is valid OR if peer has no identity key (unsigned exchange accepted with warning).
+     * Throws if the peer's identity key doesn't match TOFU record (potential MITM).
      */
-    private uploadPublicKey;
+    private verifyPeerSignature;
     /**
-     * Initiates key exchange with target device
-     * Returns payload to send via WebSocket
+     * Create a key exchange initiation to send to a remote device.
+     * Generates an ephemeral key pair and signs it with our identity key.
      */
-    initiateKeyExchange(targetDeviceId: string): Promise<KeyExchangeInit>;
     /**
-     * Handles incoming key exchange init from sender
-     * Returns ack payload to send back via WebSocket
+     * Evict expired or excess pending key exchanges.
      */
-    handleKeyExchangeInit(senderDeviceId: string, senderEphemeralPublicKey: string): Promise<KeyExchangeAck>;
+    private cleanupPendingExchanges;
+    createKeyExchangeInit(targetDeviceId: string): KeyExchangeInit;
     /**
-     * Handles incoming key exchange ack from recipient
-     * Completes the key exchange by deriving the final session key
+     * Handle an incoming key exchange init from a remote device.
+     * Verifies the peer's identity signature (TOFU), computes shared key,
+     * and returns a signed ack.
      */
-    handleKeyExchangeAck(recipientDeviceId: string, recipientEphemeralPublicKey: string): Promise<void>;
+    handleKeyExchangeInit(init: KeyExchangeInit): KeyExchangeAck;
     /**
-     * Attempts to restore a persisted session after reconnection
-     * Useful when IP changes cause WebSocket disconnection
+     * Handle an incoming key exchange ack from a remote device.
+     * Verifies the peer's identity signature (TOFU) and completes the key exchange.
      */
-    restorePersistedSession(targetDeviceId: string): Promise<boolean>;
+    handleKeyExchangeAck(ack: KeyExchangeAck): void;
     /**
-     * Lists all devices with persisted sessions
-     * Useful for auto-reconnection after network changes
+     * Attempts to restore a persisted session after reconnection.
      */
+    restorePersistedSession(targetDeviceId: string): Promise<boolean>;
+    /** Lists all devices with persisted sessions */
     listPersistedDevices(): string[];
-    /**
-     * Encrypts a message for a target device
-     */
-    encryptMessage(plaintext: string, targetDeviceId: string, sessionId: string): EncryptedMessage;
-    /**
-     * Decrypts a message from a sender device
-     */
-    decryptMessage(encryptedMessage: EncryptedMessage, senderDeviceId: string): string;
-    /**
-     * Checks if a session key exists for a device
-     */
+    /** Check if an encrypted session is established with a device */
     hasSessionKey(deviceId: string): boolean;
+    /** Encrypt a message for a specific device */
+    encryptMessage(plaintext: string, recipientDeviceId: string, sessionId: string): EncryptedMessage;
+    /** Decrypt an incoming encrypted message */
+    decryptMessage(message: EncryptedMessage, senderDeviceId: string): string;
+    /** Clear session for a specific device */
+    clearSession(deviceId: string): void;
     /**
-     * Checks if manager is initialized
-     */
-    isInitialized(): boolean;
-    /**
-     * Cleans up all session keys and pending exchanges
-     * @param deletePersisted - Whether to delete persisted sessions from disk (default: false)
+     * Cleans up all session keys and pending exchanges.
+     * @param deletePersisted - Whether to delete persisted sessions from disk
      */
     cleanup(deletePersisted?: boolean): void;
-    /**
-     * Removes a specific persisted session
-     */
+    /** Removes a specific persisted session */
     removePersistedSession(targetDeviceId: string): void;
+    /** Reset TOFU trust for a peer (used on re-pair so new keys are accepted) */
+    resetPeerTrust(targetDeviceId: string): void;
+    /** Light trust reset — only clears TOFU key, preserves pending exchanges in-flight */
+    clearTrustOnly(targetDeviceId: string): void;
 }
 //# sourceMappingURL=e2eeManager.d.ts.map