forkoff 1.1.0 → 1.1.2

package/README.md

@@ -27,9 +27,7 @@
 
 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.
 
-> **Open Source** — ForkOff CLI is now MIT licensed. Contributions welcome!
->
-> **Open Beta** — [Join the iOS TestFlight](https://testflight.apple.com/join/dhh5FrN7)
+> **Open Source** — MIT licensed. Contributions welcome!
 
 ## Installation
 
@@ -66,29 +64,47 @@ Keep this running to stream sessions to your phone in real-time.
 - **Usage analytics** — Track token usage, session counts, and streaks across devices
 - **Multi-device support** — Connect multiple CLI instances, analytics aggregate automatically
 - **Auto-start** — Optionally launch on login so your phone is always connected
-- **Direct P2P connection** — Embedded relay server, no cloud dependency for session data
+- **Local relay option** — Run with `--local` for a direct P2P connection without cloud dependency
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `forkoff pair` | Generate QR code to pair with mobile app |
-| `forkoff connect` | Connect and listen for commands |
+| `forkoff pair [--local]` | Generate QR code to pair with mobile app |
+| `forkoff connect [--local]` | Reconnect to ForkOff (for previously paired devices) |
 | `forkoff status` | Check connection status |
 | `forkoff disconnect` | Disconnect and unpair device |
 | `forkoff config` | View/modify configuration |
 | `forkoff startup` | Manage automatic startup on login |
-| `forkoff tools` | Detect AI coding tools on your machine |
-| `forkoff logs` | List debug log files for troubleshooting |
+| `forkoff tools` | Detect AI tools, install/uninstall hooks |
+| `forkoff logs` | List, view, or clean debug logs |
 
 ### Configuration
 
 ```bash
 forkoff config --show            # Show current config
 forkoff config --name "My MBP"   # Set device name
+forkoff config --port 8080       # Set relay server port
 forkoff config --reset           # Reset to defaults
 ```
 
+### Tools
+
+```bash
+forkoff tools --detect           # Detect installed AI tools
+forkoff tools --install-hooks    # Install ForkOff hooks for Claude Code
+forkoff tools --uninstall-hooks  # Remove ForkOff hooks
+forkoff tools --watch            # Watch tool status changes
+```
+
+### Logs
+
+```bash
+forkoff logs                     # List debug log files
+forkoff logs --latest            # Print path to most recent log
+forkoff logs --clean             # Delete all log files
+```
+
 ### Global Options
 
 | Option | Description |
@@ -126,7 +142,7 @@ ForkOff uses end-to-end encryption (X25519 ECDH + XSalsa20-Poly1305) so the rela
 | **Key storage** | OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret) |
 | **Enforcement** | 24 sensitive event types encrypted; plaintext fallback only when E2EE unavailable |
 
-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.
+No additional setup required — E2EE is enabled automatically when you pair.
 
 ---
 
@@ -158,7 +174,7 @@ forkoff.sendTerminalOutput(sessionId, '> npm install\nDone', 'stdout');
 | Platform | Location |
 |----------|----------|
 | **Windows** | `%APPDATA%\forkoff-cli\config.json` |
-| **macOS** | `~/Library/Preferences/forkoff-cli/config.json` |
+| **macOS** | `~/.config/forkoff-cli/config.json` |
 | **Linux** | `~/.config/forkoff-cli/config.json` |
 
 ## Development
@@ -175,7 +191,7 @@ npm test          # Run tests
 ## Requirements
 
 - Node.js 18+
-- [ForkOff mobile app](https://testflight.apple.com/join/dhh5FrN7) (iOS)
+- [ForkOff mobile app](https://github.com/Forkoff-app/forkoff-react-native) (iOS/Android)
 
 ## License
 

package/dist/index.js

@@ -454,6 +454,7 @@ function createProgram() {
         const spinner = (0, logger_1.createSpinner)('Initializing...').start();
         try {
             tools_1.PermissionIpcManager.cleanupStaleTempFiles();
+            tools_1.claudeProcessManager.cleanupAllPermissionState();
             spinner.succeed('Ready!\n');
             // Detect connected tools
             spinner.start('Detecting AI coding tools...');
@@ -1097,6 +1098,13 @@ function createProgram() {
             websocket_1.wsClient.on('disconnected', (reason) => {
                 console.log(chalk_1.default.yellow(`\nMobile disconnected: ${reason}`));
                 console.log(chalk_1.default.dim('Waiting for mobile to reconnect...'));
+                tools_1.claudeProcessManager.autoAllowAllPendingPrompts();
+                tools_1.claudeProcessManager.cleanupAllPermissionState();
+                tools_1.claudeProcessManager.clearAllTakenOver();
+            });
+            websocket_1.wsClient.on('session_release', (data) => {
+                console.log(chalk_1.default.dim(`[Session] Mobile released session: ${data.sessionKey}`));
+                tools_1.claudeProcessManager.releaseSession(data.sessionKey);
             });
             websocket_1.wsClient.on('error', (error) => {
                 console.error(chalk_1.default.red(`Connection error: ${error.message}`));

package/dist/tools/claude-process.d.ts

@@ -241,6 +241,11 @@ declare class ClaudeProcessManager extends EventEmitter {
      * Clear all taken-over sessions (e.g., when mobile disconnects).
      */
     clearAllTakenOver(): void;
+    /**
+     * Release a single session — clean up its hooks and IPC.
+     * Called when mobile navigates away from the session screen after taking over.
+     */
+    releaseSession(sessionKey: string): void;
     /**
      * Get all pending permission prompts across all IPC managers.
      * Used to sync pending permissions to mobile on take-over.

package/dist/tools/claude-process.js

@@ -822,6 +822,50 @@ class ClaudeProcessManager extends events_1.EventEmitter {
         this.takenOverSessions.clear();
         console.log(`[Claude Process] All taken-over sessions cleared`);
     }
+    /**
+     * Release a single session — clean up its hooks and IPC.
+     * Called when mobile navigates away from the session screen after taking over.
+     */
+    releaseSession(sessionKey) {
+        // Find the process by sessionKey or terminalSessionId
+        let terminalSessionId;
+        let directory;
+        for (const [id, info] of this.processes) {
+            if (id === sessionKey || info.sessionKey === sessionKey) {
+                terminalSessionId = id;
+                directory = info.directory;
+                break;
+            }
+        }
+        // Also check closed sessions in case the process already exited
+        if (!terminalSessionId) {
+            for (const [id, info] of this.closedSessions) {
+                if (id === sessionKey || info.sessionKey === sessionKey) {
+                    terminalSessionId = id;
+                    directory = info.directory;
+                    break;
+                }
+            }
+        }
+        if (terminalSessionId) {
+            // Stop permission IPC for this session
+            this.stopPermissionIpc(terminalSessionId);
+            // Remove hook from directory if no other active sessions use it
+            if (directory) {
+                const otherSessionsInDir = Array.from(this.processes.values())
+                    .filter(p => p.directory === directory && p.terminalSessionId !== terminalSessionId);
+                if (otherSessionsInDir.length === 0) {
+                    this.removeHook(directory);
+                }
+            }
+            // Clear taken-over state
+            this.takenOverSessions.delete(terminalSessionId);
+            console.log(`[Claude Process] Session released: ${terminalSessionId}`);
+        }
+        else {
+            console.log(`[Claude Process] Session release: no matching session found for ${sessionKey}`);
+        }
+    }
     /**
      * Get all pending permission prompts across all IPC managers.
      * Used to sync pending permissions to mobile on take-over.

package/dist/websocket.js

@@ -89,7 +89,7 @@ const PLAINTEXT_DROP_EVENTS = [
     'directory_list', 'transcript_fetch', 'transcript_subscribe',
     'read_file', 'claude_approval_response', 'permission_response',
     'permission_rules_sync', 'claude_abort', 'tab_complete',
-    'usage_stats_request', 'sdk_session_history',
+    'usage_stats_request', 'sdk_session_history', 'session_release',
 ];
 /** Events forwarded from server that do NOT need plaintext-drop checking */
 const PASSTHROUGH_EVENTS = [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "forkoff",
-  "version": "1.1.0",
-  "description": "CLI tool to connect your AI coding tools to mobile | Open Beta - Download the app: https://testflight.apple.com/join/dhh5FrN7",
+  "version": "1.1.2",
+  "description": "CLI tool to connect Claude Code to the ForkOff mobile app for remote monitoring and approvals",
   "main": "dist/integration.js",
   "types": "dist/integration.d.ts",
   "homepage": "https://forkoff.app",
@@ -39,10 +39,15 @@
     "coding",
     "mobile",
     "claude",
+    "claude-code",
     "forkoff",
-    "beta",
-    "testflight"
+    "remote-control",
+    "developer-tools",
+    "websocket"
   ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "author": {
     "name": "ForkOff",
     "email": "support@forkoff.app",

package/E2EE-COMPLETE.md

@@ -1,290 +0,0 @@
-# ✅ E2EE Implementation Complete
-
-## 🎯 Final Status: PRODUCTION READY
-
-**Total Test Coverage: 185 tests passing**
-- Mobile (React Native): 90 tests ✅
-- Backend (NestJS): 23 tests ✅
-- CLI (Node.js): 72 tests ✅
-
----
-
-## 🔐 Security Features
-
-### Encryption
-- **Algorithm**: X25519 (ECDH) + AES-256-GCM
-- **Key Exchange**: Ephemeral Diffie-Hellman with HKDF key derivation
-- **Authentication**: Authenticated encryption with 16-byte auth tags
-- **Forward Secrecy**: Each session uses unique ephemeral keys
-
-### Security Properties
-✅ End-to-end encryption (backend cannot decrypt)
-✅ Perfect forward secrecy (ephemeral keys)
-✅ Authenticated encryption (tamper detection)
-✅ Replay protection (message counters)
-✅ Key rotation support (version tracking)
-
----
-
-## 🌐 Network Resilience (IP Change Handling)
-
-### Problem
-When a device's IP changes (WiFi → cellular, network switch), the WebSocket connection drops.
-
-### Solution Implemented
-
-#### 1. **Persistent Session Storage**
-- Session keys stored to disk: `~/.forkoff-cli/sessions/`
-- Survives process restarts and IP changes
-- Automatic 24-hour expiration
-
-#### 2. **Session Restoration API**
-```typescript
-// After reconnection, restore previous E2EE sessions
-await e2eeManager.restorePersistedSession(targetDeviceId);
-
-// List all devices with active sessions
-const devices = e2eeManager.listPersistedDevices();
-```
-
-#### 3. **Automatic Reconnection Flow**
-1. IP changes → WebSocket disconnects
-2. WebSocket automatically reconnects (socket.io)
-3. E2EE manager restores persisted sessions
-4. Encrypted communication resumes seamlessly
-
----
-
-## 📁 File Structure
-
-### CLI (`forkoff-cli/src/crypto/`)
-```
-crypto/
-├── types.ts                    # Shared E2EE type definitions
-├── keyGeneration.ts            # X25519 key pair generation (8 tests)
-├── keyStorage.ts               # OS keychain + in-memory storage (10 tests)
-├── encryption.ts               # AES-256-GCM encrypt/decrypt (13 tests)
-├── keyExchange.ts              # ECDH + HKDF key derivation (9 tests)
-├── e2eeManager.ts              # Orchestration layer (12 tests)
-├── sessionPersistence.ts       # Disk-based session storage (NEW)
-└── websocketE2EE.ts            # WebSocket integration (11 tests)
-
-__tests__/crypto/
-├── keyGeneration.test.ts
-├── keyStorage.test.ts
-├── encryption.test.ts
-├── keyExchange.test.ts
-├── e2eeManager.test.ts
-├── websocketIntegration.test.ts
-└── e2e-integration.test.ts     # End-to-end flow verification (9 tests)
-```
-
-### Backend (`forkoff-api/src/crypto/`)
-```
-crypto/
-├── crypto.service.ts           # Public key storage & retrieval (9 tests)
-├── crypto.controller.ts        # REST API endpoints (7 tests)
-└── dto/
-
-websocket/
-└── websocket.gateway.ts        # E2EE message forwarding (7 tests)
-```
-
-### Mobile (`forkoff/services/crypto/`)
-```
-crypto/
-├── keyGeneration.ts            # Key pair generation
-├── keyStorage.ts               # Secure store + session keys
-├── encryption.ts               # AES-256-GCM encryption
-├── keyExchange.ts              # X25519 key exchange
-└── e2eeManager.ts              # E2EE orchestration
-```
-
----
-
-## 🔄 How It Works
-
-### Initial Setup
-1. **Device registers**: Generates X25519 key pair, stores private key in OS keychain
-2. **Upload public key**: Sends public key to backend API
-3. **Backend stores**: Public key stored in PostgreSQL (Device table)
-
-### Key Exchange Flow
-```
-Mobile                     Backend                    CLI
-  |                          |                         |
-  |--[init: ephemeral_pk]--->|---[forward]------------>|
-  |                          |                         |
-  |<-[ack: ephemeral_pk]-----|<--[forward]-------------|
-  |                          |                         |
-Both sides derive shared secret using ECDH
-Both sides derive session key using HKDF
-```
-
-### Encrypted Messaging
-```
-Mobile                     Backend                    CLI
-  |                          |                         |
-  |--[encrypted_message]---->|---[forward]------------>|
-  |  {ciphertext, nonce,     |                         |
-  |   authTag, counter}      |                         |
-  |                          |                         |
-  |<-[encrypted_message]-----|<--[forward]-------------|
-  |                          |                         |
-```
-
-### Reconnection After IP Change
-```
-CLI Reconnects                Backend                  Mobile
-  |                             |                        |
-  | WebSocket reconnects        |                        |
-  |<--------------------------->|                        |
-  |                             |                        |
-  | Restore persisted sessions  |                        |
-  | (load from disk)            |                        |
-  |                             |                        |
-  |--[encrypted_message]------->|---[forward]---------->|
-  | Communication resumes!      |                        |
-```
-
----
-
-## 🧪 Test Verification
-
-### Unit Tests (Crypto Primitives)
-- ✅ Key generation produces valid X25519 keys
-- ✅ Keys are properly Base64-encoded
-- ✅ Encryption/decryption round-trip works
-- ✅ Unicode and emoji preserved
-- ✅ Large messages (10KB+) supported
-- ✅ ECDH produces matching shared secrets
-- ✅ HKDF derives correct session keys
-
-### Integration Tests (E2EE Flow)
-- ✅ Full bidirectional encrypted communication
-- ✅ Key exchange completes successfully
-- ✅ Messages encrypted/decrypted correctly
-- ✅ Replay attacks detected and rejected
-- ✅ Tampered messages rejected
-- ✅ Multiple concurrent sessions supported
-- ✅ Session persistence across reconnections
-
-### Security Tests
-- ✅ Tampered ciphertext rejected
-- ✅ Tampered nonce rejected
-- ✅ Tampered auth tag rejected
-- ✅ Wrong key cannot decrypt
-- ✅ Message counters prevent replay attacks
-
----
-
-## 🚀 Usage Example
-
-### Initialize E2EE
-```typescript
-import { E2EEManager } from './crypto/e2eeManager';
-import { WebSocketE2EEIntegration } from './crypto/websocketE2EE';
-
-// Initialize E2EE manager
-const e2ee = new E2EEManager(deviceId, apiUrl, authToken);
-await e2ee.initialize();
-
-// Integrate with WebSocket
-const wsIntegration = new WebSocketE2EEIntegration(wsClient);
-await wsIntegration.initialize(deviceId, apiUrl, authToken);
-```
-
-### Send Encrypted Message
-```typescript
-// Initiate key exchange (if not already done)
-if (!e2ee.hasSessionKey(targetDeviceId)) {
-  await wsIntegration.initiateKeyExchange(targetDeviceId);
-  // Wait for key exchange to complete...
-}
-
-// Send encrypted message
-wsIntegration.sendEncryptedMessage(
-  'Secret message',
-  targetDeviceId,
-  sessionId
-);
-```
-
-### Handle Reconnection After IP Change
-```typescript
-wsClient.on('reconnect', async () => {
-  // Restore all persisted sessions
-  const devices = e2ee.listPersistedDevices();
-
-  for (const deviceId of devices) {
-    const restored = await e2ee.restorePersistedSession(deviceId);
-    if (restored) {
-      console.log(`Restored E2EE session with ${deviceId}`);
-    }
-  }
-});
-```
-
----
-
-## 📊 Performance Characteristics
-
-- **Key Generation**: ~50ms (X25519)
-- **Encryption**: <5ms (AES-256-GCM, typical message)
-- **Decryption**: <5ms (AES-256-GCM, typical message)
-- **Key Exchange**: ~100ms (includes API calls)
-- **Session Restoration**: <10ms (load from disk)
-
----
-
-## 🔧 Configuration
-
-### Session Expiration
-Sessions automatically expire after 24 hours. Configurable in `sessionPersistence.ts`:
-```typescript
-const hoursSinceCreation = (now.getTime() - timestamp.getTime()) / (1000 * 60 * 60);
-if (hoursSinceCreation > 24) { // Change this value
-  // Session expired
-}
-```
-
-### Storage Location
-Sessions stored at: `~/.forkoff-cli/sessions/`
-
-Private keys stored in OS keychain via `keytar`
-
----
-
-## 🎓 What We Learned
-
-1. **TDD Works**: Writing tests first caught numerous edge cases
-2. **Message Counters Matter**: Replay protection is crucial
-3. **Persistence Is Hard**: Mocking file system for tests is complex
-4. **Network Resilience**: IP changes are common, plan for them
-5. **Security Trade-offs**: Perfect forward secrecy vs. session resumption
-
----
-
-## ✨ Future Enhancements (Not Implemented)
-
-- [ ] Double Ratchet Algorithm (Signal Protocol)
-- [ ] Group messaging encryption
-- [ ] Key rotation on schedule
-- [ ] Post-quantum cryptography (Kyber)
-- [ ] Hardware security module integration
-- [ ] Encrypted file transfers
-
----
-
-## 📖 References
-
-- X25519: RFC 7748
-- AES-GCM: NIST SP 800-38D
-- HKDF: RFC 5869
-- Signal Protocol: https://signal.org/docs/
-
----
-
-**Built with ❤️ using Test-Driven Development**
-
-**Status**: ✅ PRODUCTION READY - All 185 tests passing