forkoff 1.1.1 → 1.1.3

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/cloud-client.js

@@ -118,7 +118,8 @@ class CloudRelayClient extends events_1.EventEmitter {
             });
             // Handle mobile connected notification from relay
             this.socket.on('mobile_connected', (data) => {
-                console.log(`[CloudRelay] Mobile connected: ${data.deviceId || 'unknown'}`);
+                const id = data.deviceId || 'unknown';
+                console.log(`[CloudRelay] Mobile connected: ${id.length > 8 ? id.substring(0, 8) + '...' : id}`);
                 this.emit('mobile_connected', { deviceId: data.deviceId || data.mobileDeviceId });
             });
             // Handle mobile disconnected notification from relay

package/dist/crypto/e2eeManager.js

@@ -200,10 +200,7 @@ class E2EEManager {
         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)}`);
+        console.log(`[E2EE] Key exchange init processed — session established with peer ${init.senderDeviceId.substring(0, 8)}...`);
         // Store session
         const sessionId = `session-${init.senderDeviceId}-${this.deviceId}-${Date.now()}`;
         this.sessions.set(init.senderDeviceId, {
@@ -249,7 +246,7 @@ class E2EEManager {
         // 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}`);
+            console.log(`[E2EE] Pending exchange not found for ${peerId.substring(0, 8)}..., using fallback`);
             pendingEntry = fallbackEntry;
             pendingKey = fallbackKey;
         }
@@ -262,10 +259,7 @@ class E2EEManager {
         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)}`);
+        console.log(`[E2EE] Key exchange ack processed — session established with peer ${peerId.substring(0, 8)}...`);
         // Store session
         const sessionId = `session-${this.deviceId}-${peerId}-${Date.now()}`;
         this.sessions.set(peerId, {
@@ -338,10 +332,8 @@ class E2EEManager {
         }
         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}`);
+            console.log(`[E2EE] First encrypted message sent to ${recipientDeviceId.substring(0, 8)}...`);
         }
         return {
             senderDeviceId: this.deviceId,
@@ -374,7 +366,7 @@ class E2EEManager {
         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`);
+            console.warn(`[E2EE] Session with ${senderDeviceId.substring(0, 8)}... has expired — re-key required`);
         }
         return plaintext;
     }

package/dist/server.js

@@ -71,7 +71,8 @@ class EmbeddedRelayServer extends events_1.EventEmitter {
                 next();
             });
             this.io.on('connection', (socket) => {
-                console.log(`[Server] Mobile connected: ${socket.data.deviceId}`);
+                const devId = socket.data.deviceId || 'unknown';
+                console.log(`[Server] Mobile connected: ${devId.length > 8 ? devId.substring(0, 8) + '...' : devId}`);
                 // Track the mobile socket (only one active connection)
                 if (this.mobileSocket) {
                     console.log(`[Server] Replacing existing mobile connection`);

package/dist/websocket.js

@@ -158,7 +158,7 @@ class WebSocketClient extends events_1.EventEmitter {
             return;
         // When mobile connects, emit connected + start heartbeat + initiate E2EE
         this.server.on('mobile_connected', (data) => {
-            console.log(`[WS] Mobile connected: ${data.deviceId}`);
+            console.log(`[WS] Mobile connected: ${data.deviceId?.substring(0, 8)}...`);
             this.emit('connected');
             this.startHeartbeat();
             // SECURITY: Clear stale E2EE peer state on every mobile connect.
@@ -167,7 +167,7 @@ class WebSocketClient extends events_1.EventEmitter {
             // that mobile can't decrypt, causing "No session established" errors.
             // A fresh key exchange will re-establish the session after debounce.
             if (this.e2eePeerDeviceId) {
-                console.log(`[E2EE] Clearing stale peer state for ${this.e2eePeerDeviceId} (mobile reconnected)`);
+                console.log(`[E2EE] Clearing stale peer state (mobile reconnected)`);
                 this.e2eeManager?.clearSession(this.e2eePeerDeviceId);
                 this.e2eePeerDeviceId = null;
             }
@@ -188,7 +188,7 @@ class WebSocketClient extends events_1.EventEmitter {
                     return;
                 try {
                     this._keyExchangePending = true;
-                    console.log(`[E2EE] Initiating key exchange with ${targetId} (after debounce)`);
+                    console.log(`[E2EE] Initiating key exchange with ${targetId.substring(0, 8)}...`);
                     this.e2eeManager.clearSession(targetId);
                     const initPayload = this.e2eeManager.createKeyExchangeInit(targetId);
                     this.server?.emitToMobile('encrypted_key_exchange_init', {
@@ -249,7 +249,7 @@ class WebSocketClient extends events_1.EventEmitter {
                 return;
             }
             try {
-                console.log(`[E2EE] Received key exchange init from ${data.senderDeviceId}`);
+                console.log(`[E2EE] Received key exchange init from ${data.senderDeviceId.substring(0, 8)}...`);
                 const ack = this.e2eeManager.handleKeyExchangeInit(data);
                 this.e2eePeerDeviceId = data.senderDeviceId;
                 this.server?.emitToMobile('encrypted_key_exchange_ack', {
@@ -270,11 +270,11 @@ class WebSocketClient extends events_1.EventEmitter {
             if (!this.e2eeManager)
                 return;
             try {
-                console.log(`[E2EE] Received key exchange ack from ${data.senderDeviceId}`);
+                console.log(`[E2EE] Received key exchange ack from ${data.senderDeviceId.substring(0, 8)}...`);
                 this.e2eeManager.handleKeyExchangeAck(data);
                 this._keyExchangePending = false;
                 this.e2eePeerDeviceId = data.senderDeviceId;
-                console.log(`[E2EE] Key exchange complete — session established with ${data.senderDeviceId}`);
+                console.log(`[E2EE] Key exchange complete — session established`);
                 this.emit('e2ee_established', { peerDeviceId: data.senderDeviceId });
                 this.flushSensitiveQueue();
                 this.sendAllUsageStats();
@@ -283,7 +283,7 @@ class WebSocketClient extends events_1.EventEmitter {
                 const msg = err instanceof Error ? err.message : String(err);
                 // Only suppress if it's truly a duplicate ack (pending exchange already consumed)
                 if (msg.includes('No pending key exchange')) {
-                    console.log(`[E2EE] Duplicate ack from ${data.senderDeviceId} — ignored`);
+                    console.log(`[E2EE] Duplicate ack — ignored`);
                 }
                 else {
                     console.error(`[E2EE] Key exchange ack failed: ${msg}`);
@@ -520,7 +520,7 @@ class WebSocketClient extends events_1.EventEmitter {
         if (sessions.length > 0) {
             const peer = this.e2eePeerDeviceId;
             const hasE2EE = peer ? this.e2eeManager?.hasSessionKey(peer) : false;
-            console.log(`[WS] sendClaudeSessions: ${sessions.length} sessions, peer=${peer || 'none'}, e2ee=${hasE2EE}, queue=${this.pendingSensitiveMessages.length}`);
+            console.log(`[WS] sendClaudeSessions: ${sessions.length} sessions, e2ee=${hasE2EE}`);
             const withDeviceId = sessions.map(s => ({ ...s, deviceId: config_1.config.deviceId }));
             this.emitSensitive('claude_session_batch_update', { sessions: withDeviceId }, peer ?? undefined);
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "forkoff",
-  "version": "1.1.1",
-  "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.3",
+  "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

package/eas.json

@@ -1,21 +0,0 @@
-{
-  "cli": {
-    "version": ">= 16.26.0",
-    "appVersionSource": "remote"
-  },
-  "build": {
-    "development": {
-      "developmentClient": true,
-      "distribution": "internal"
-    },
-    "preview": {
-      "distribution": "internal"
-    },
-    "production": {
-      "autoIncrement": true
-    }
-  },
-  "submit": {
-    "production": {}
-  }
-}