beachviber 1.0.34

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.0.10
+
+Initial open-source release.
+
+### Features
+
+- **Remote Claude Code control** — send prompts and monitor sessions from your phone
+- **End-to-end encryption** — NaCl public-key cryptography (Curve25519 + XSalsa20-Poly1305) between phone and desktop
+- **QR code pairing** — scan to pair, verify with a code, reconnect automatically
+- **Tool approval** — approve or deny Claude's file writes and shell commands from your phone
+- **Multi-project support** — scan a directory tree for projects with `.git/` or `.claude/`
+- **Session management** — create, resume, and browse Claude Code sessions remotely
+- **Session history** — read Claude CLI transcripts with tool use details
+- **Image attachments** — attach images from your phone to prompts
+- **Auto-reconnect** — exponential backoff with automatic re-pairing on token revocation
+- **Fail-closed security** — tool use denied if approval socket is unreachable or phone doesn't respond

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Krokosz
+
+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,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# BeachViber
+
+Control [Claude Code](https://docs.anthropic.com/en/docs/claude-code) from your phone. Send prompts, approve tools, and monitor sessions remotely through an end-to-end encrypted connection.
+
+```
+Phone App ←—(encrypted)—→ Relay Server ←—(encrypted)—→ Computer Agent ←—→ Claude Code
+```
+
+## Install
+
+```bash
+npm install -g beachviber
+```
+
+Requires Node.js 20+ and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) on your PATH.
+
+## Quick Start
+
+```bash
+beachviber
+```
+
+On first run:
+
+1. A QR code appears — scan it with the [BeachViber App](https://app.beachviber.com)
+3. In your terminal, enter the verification code shown on your BeachViber App
+4. Done — you're paired and encrypted end-to-end
+
+On subsequent runs, the agent reconnects automatically.
+
+## What You Can Do
+
+From your phone:
+
+- Browse projects on your machine
+- Start Claude Code sessions and send prompts
+- Approve or deny tool use (file writes, shell commands, etc.)
+- View session history and transcripts
+- Manage multiple desktops from one phone
+
+## Security
+
+**End-to-end encrypted.** All sensitive messages (prompts, responses, tool approvals) are encrypted with X25519 + AES-256-GCM. The relay server cannot read message contents.
+
+**Keys stay on your machine.** Private keys are stored in the OS keychain (macOS Keychain, Linux Secret Service, or Windows DPAPI fallback) as PKCS8 DER — never in plaintext config files.
+
+**Tool approval.** A `PreToolUse` hook intercepts Claude Code tool calls. Tools already in your Claude allow list are auto-approved. Everything else is sent to your phone for approval. If the agent isn't running, the hook is a no-op.
+
+## Configuration
+
+The agent stores config in `~/.beachviber/`.
+
+```
+.beachviber/
+```
+
+## Uninstall
+
+```bash
+npm uninstall -g beachviber
+```
+
+This removes the `PreToolUse` hook from `~/.claude/settings.json` automatically.
+
+## Protocol
+
+The agent communicates over WebSocket using JSON messages. Each message has a `type`, optional `sessionId`, `timestamp`, and `payload`. When paired, the `payload` is replaced with an `encrypted` field containing an AES-256-GCM envelope.
+
+| Type | Direction | Description |
+|------|-----------|-------------|
+| `register` | Desktop → Relay | Register with device token and public key |
+| `registered` | Relay → Desktop | Registration confirmed |
+| `projects_request` | Phone → Desktop | List available projects |
+| `projects_response` | Desktop → Phone | Project list with git info |
+| `session_create` | Phone → Desktop | Start a Claude Code session |
+| `session_created` | Desktop → Phone | Session started confirmation |
+| `session_end` | Phone → Desktop | End a session |
+| `prompt` | Phone → Desktop | Send a prompt to Claude |
+| `stream_start` | Desktop → Phone | Claude started responding |
+| `stream_delta` | Desktop → Phone | Streaming text/tool-use chunk |
+| `stream_end` | Desktop → Phone | Claude finished responding |
+| `tool_approval_request` | Desktop → Phone | Tool needs approval |
+| `tool_approval_response` | Phone → Desktop | Approve/deny tool use |
+| `sessions_request` | Phone → Desktop | List all sessions |
+| `sessions_response` | Desktop → Phone | Session list with metadata |
+| `session_history_request` | Phone → Desktop | Get session transcript |
+| `session_history_response` | Desktop → Phone | Transcript messages |
+| `verify_code` | Desktop → Phone | Pairing verification code |
+| `verify_code_ack` | Phone → Desktop | Verification result + public key |
+| `heartbeat` | Desktop → Relay | Keep-alive |
+
+## Learn More
+https://www.beachviber.com
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and guidelines.
+
+## License
+
+MIT

package/dist/api.js

@@ -0,0 +1,28 @@
+import { DEFAULT_API_URL } from "./config.js";
+// API_URL is set after config is loaded; env var takes precedence
+let API_URL = DEFAULT_API_URL;
+export function setApiUrl(url) {
+    API_URL = url;
+}
+export function getApiUrl() {
+    return API_URL;
+}
+export async function requestPairing(publicKey, deviceId) {
+    const res = await fetch(`${API_URL}/v1/pairing/request`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ publicKey, deviceId }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) {
+        throw new Error(`Pairing request failed: ${res.status} ${res.statusText}`);
+    }
+    return res.json();
+}
+export async function pollPairingStatus(code, token) {
+    const res = await fetch(`${API_URL}/v1/pairing/status?code=${encodeURIComponent(code)}&token=${encodeURIComponent(token)}`, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) {
+        throw new Error(`Pairing status check failed: ${res.status} ${res.statusText}`);
+    }
+    return res.json();
+}

package/dist/approval-hook.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// PreToolUse hook — asks phone for approval via desktop agent's IPC channel
+// (Unix domain socket on macOS/Linux, named pipe on Windows)
+// Respects Claude's own permission settings: tools the user has already
+// allowed in their Claude settings are auto-approved without going to the phone.
+
+import net from "net";
+import fs from "fs";
+import path from "path";
+import { homedir } from "os";
+
+const SOCKET_PATH = process.env.BEACHVIBER_SOCKET_PATH;
+const SESSION_ID = process.env.BEACHVIBER_SESSION_ID;
+const AUTH_TOKEN = process.env.BEACHVIBER_APPROVAL_TOKEN;
+
+// hookEventName is REQUIRED for Claude Code to recognize the output
+const ALLOW = JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "allow",
+  },
+});
+
+// If not running in BeachViber context, let Claude handle permissions normally
+if (!SOCKET_PATH || !SESSION_ID || !AUTH_TOKEN) {
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Load Claude's permission settings from all config layers
+// ---------------------------------------------------------------------------
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function loadPermissions(cwd) {
+  const allow = [];
+  const deny = [];
+
+  // User-level settings (lowest precedence for allow, but we collect all)
+  const userSettings = readJsonSafe(path.join(homedir(), ".claude", "settings.json"));
+  if (userSettings?.permissions?.allow) allow.push(...userSettings.permissions.allow);
+  if (userSettings?.permissions?.deny) deny.push(...userSettings.permissions.deny);
+
+  // Project-level settings
+  const projectSettings = readJsonSafe(path.join(cwd, ".claude", "settings.json"));
+  if (projectSettings?.permissions?.allow) allow.push(...projectSettings.permissions.allow);
+  if (projectSettings?.permissions?.deny) deny.push(...projectSettings.permissions.deny);
+
+  // Local project settings (gitignored, personal overrides)
+  const localSettings = readJsonSafe(path.join(cwd, ".claude", "settings.local.json"));
+  if (localSettings?.permissions?.allow) allow.push(...localSettings.permissions.allow);
+  if (localSettings?.permissions?.deny) deny.push(...localSettings.permissions.deny);
+
+  return { allow, deny };
+}
+
+// ---------------------------------------------------------------------------
+// Pattern matching — mirrors Claude's permission pattern format
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a tool call matches a permission pattern.
+ *
+ * Pattern formats:
+ *   "Read"                → matches all Read tool uses
+ *   "Bash(npm test *)"    → matches Bash where command starts with "npm test "
+ *   "Bash(*)"             → matches all Bash commands
+ *   "Edit(/src/**)"       → matches Edit on paths under /src/
+ */
+function matchesPattern(pattern, toolName, toolInput) {
+  // Parse "ToolName(arg pattern)" or just "ToolName"
+  const parenIdx = pattern.indexOf("(");
+  if (parenIdx === -1) {
+    // Bare tool name — matches all uses of this tool
+    return pattern === toolName;
+  }
+
+  const patternTool = pattern.slice(0, parenIdx);
+  if (patternTool !== toolName) return false;
+
+  // Extract the argument pattern inside parentheses
+  const argPattern = pattern.slice(parenIdx + 1, -1); // strip ( and )
+
+  // Determine the relevant input value to match against
+  let inputValue = "";
+  if (toolName === "Bash" && toolInput?.command) {
+    inputValue = toolInput.command;
+  } else if (toolInput?.file_path) {
+    inputValue = toolInput.file_path;
+  } else if (toolInput?.pattern) {
+    inputValue = toolInput.pattern;
+  }
+
+  return globMatch(argPattern, inputValue);
+}
+
+/**
+ * Simple glob matching: * matches any sequence of characters within a segment.
+ * Handles patterns like "npm test *", "git *", "*.ts", etc.
+ */
+function globMatch(pattern, str) {
+  // Convert glob to regex: escape regex chars, then replace * with .*
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const regexStr = "^" + escaped.replace(/\*/g, ".*") + "$";
+  try {
+    return new RegExp(regexStr).test(str);
+  } catch {
+    return false;
+  }
+}
+
+function isAllowedBySettings(toolName, toolInput, permissions) {
+  // Deny takes precedence — if explicitly denied, do NOT auto-allow
+  for (const pattern of permissions.deny) {
+    if (matchesPattern(pattern, toolName, toolInput)) {
+      return false;
+    }
+  }
+
+  // Check allow list
+  for (const pattern of permissions.allow) {
+    if (matchesPattern(pattern, toolName, toolInput)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Main hook logic
+// ---------------------------------------------------------------------------
+
+// Read JSON from stdin
+const chunks = [];
+for await (const chunk of process.stdin) chunks.push(chunk);
+const input = JSON.parse(Buffer.concat(chunks).toString());
+
+// Load Claude's permission settings
+const cwd = input.cwd || process.cwd();
+const permissions = loadPermissions(cwd);
+
+// If Claude's settings already allow this tool, auto-approve
+if (isAllowedBySettings(input.tool_name, input.tool_input, permissions)) {
+  process.stdout.write(ALLOW);
+  process.exit(0);
+}
+
+// Connect to desktop agent via IPC (Unix socket or named pipe) for phone approval
+try {
+  const response = await new Promise((resolve, reject) => {
+    const client = net.createConnection(SOCKET_PATH, () => {
+      client.write(JSON.stringify({
+        token: AUTH_TOKEN,
+        sessionId: SESSION_ID,
+        tool: input.tool_name,
+        toolInput: input.tool_input,
+      }));
+      client.end(); // half-close: done writing, still reading
+    });
+
+    let data = "";
+    client.on("data", (chunk) => (data += chunk));
+    client.on("end", () => {
+      try { resolve(JSON.parse(data)); }
+      catch { reject(new Error("bad response")); }
+    });
+    client.on("error", reject);
+  });
+
+  if (response.approved) {
+    // Explicitly grant permission
+    process.stdout.write(ALLOW);
+    process.exit(0);
+  }
+
+  // Denied by phone user
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: response.reason || "Denied by phone user",
+    },
+  }));
+} catch (err) {
+  // Desktop agent not reachable — fall through to Claude's normal permissions
+  process.exit(0);
+}

package/dist/approval-server.js

@@ -0,0 +1,186 @@
+import net from "net";
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { getBeachViberDir, getProfileSuffix } from "./config.js";
+import { createLogger } from "./logger.js";
+const log = createLogger("approval");
+const APPROVAL_TIMEOUT_MS = 300_000; // 5 minutes
+const MAX_REQUEST_BYTES = 64 * 1024; // 64 KB
+const CONN_TIMEOUT_MS = 30_000; // 30 seconds
+const MAX_CONCURRENT_CONNS = 10;
+const isWin = process.platform === "win32";
+// Random token generated per desktop agent session — only processes
+// spawned by the desktop agent (Claude CLI → hook) know this token
+const AUTH_TOKEN = crypto.randomBytes(32).toString("hex");
+let socketPath = "";
+export function getSocketPath() {
+    return socketPath;
+}
+export function getAuthToken() {
+    return AUTH_TOKEN;
+}
+/** Build the IPC endpoint path — named pipe on Windows, Unix socket elsewhere */
+function buildIpcPath() {
+    const suffix = getProfileSuffix();
+    if (isWin) {
+        // Named pipes are globally namespaced; include a hash of the user's
+        // BeachViber directory to avoid collisions between users on the same machine
+        const id = crypto
+            .createHash("sha256")
+            .update(getBeachViberDir())
+            .digest("hex")
+            .slice(0, 8);
+        return `\\\\.\\pipe\\beachviber-approval-${id}${suffix}`;
+    }
+    return path.join(getBeachViberDir(), `approval${suffix}.sock`);
+}
+export function startApprovalServer(sessionMgr, sendFn) {
+    socketPath = buildIpcPath();
+    if (!isWin) {
+        const bvDir = getBeachViberDir();
+        // Ensure directory exists with owner-only permissions
+        fs.mkdirSync(bvDir, { recursive: true, mode: 0o700 });
+        // Clean up stale socket from a previous crash
+        try {
+            fs.unlinkSync(socketPath);
+        }
+        catch { }
+    }
+    const activeConns = new Set();
+    const server = net.createServer({ allowHalfOpen: true }, (conn) => {
+        // Reject if too many concurrent connections
+        if (activeConns.size >= MAX_CONCURRENT_CONNS) {
+            conn.destroy();
+            return;
+        }
+        activeConns.add(conn);
+        conn.on("close", () => activeConns.delete(conn));
+        let data = "";
+        let totalBytes = 0;
+        // Connection timeout — destroy if client doesn't finish within limit
+        conn.setTimeout(CONN_TIMEOUT_MS, () => {
+            conn.destroy();
+        });
+        conn.on("data", (chunk) => {
+            totalBytes += chunk.length;
+            if (totalBytes > MAX_REQUEST_BYTES) {
+                conn.write(JSON.stringify({ approved: false, reason: "request too large" }));
+                conn.end();
+                return;
+            }
+            data += chunk.toString();
+        });
+        conn.on("end", () => {
+            // Full request received (hook called conn.end() after writing)
+            let request;
+            try {
+                request = JSON.parse(data);
+            }
+            catch {
+                conn.write(JSON.stringify({ approved: false, reason: "invalid request" }));
+                conn.end();
+                return;
+            }
+            // Validate auth token (constant-time comparison to prevent timing attacks)
+            const tokenBuf = Buffer.from(String(request.token || ""));
+            const expectedBuf = Buffer.from(AUTH_TOKEN);
+            if (tokenBuf.length !== expectedBuf.length || !crypto.timingSafeEqual(tokenBuf, expectedBuf)) {
+                conn.write(JSON.stringify({ approved: false, reason: "unauthorized" }));
+                conn.end();
+                return;
+            }
+            const approvalId = `apr_${crypto.randomBytes(12).toString("hex")}`;
+            // Build human-readable description
+            let description = request.tool;
+            let command;
+            const input = request.toolInput || {};
+            if (request.tool === "Bash" && input.command) {
+                description = `Run: ${input.command}`;
+                command = input.command;
+            }
+            else if (input.file_path) {
+                description = `${request.tool}: ${input.file_path}`;
+            }
+            // Send tool_approval_request to phone via existing WSS connection
+            log.info(`Sending tool_approval_request: approvalId=${approvalId} session=${request.sessionId} tool=${request.tool}`);
+            const sent = sendFn({
+                type: "tool_approval_request",
+                sessionId: request.sessionId,
+                timestamp: Date.now(),
+                payload: { approvalId, tool: request.tool, description, command },
+            });
+            // Phone not connected — deny immediately instead of waiting 5 minutes
+            if (!sent) {
+                log.warn(`Phone not connected — auto-denying approvalId=${approvalId}`);
+                conn.write(JSON.stringify({ approved: false, reason: "phone not connected" }));
+                conn.end();
+                return;
+            }
+            // Timeout: deny if phone doesn't respond in 5 minutes
+            const timer = setTimeout(() => {
+                sessionMgr.resolveApproval(approvalId, false);
+            }, APPROVAL_TIMEOUT_MS);
+            // Register callback — fires when phone responds via WSS
+            // (handleMessage in index.ts receives tool_approval_response,
+            //  calls sessionMgr.resolveApproval, which triggers this callback)
+            sessionMgr.registerApprovalCallback(approvalId, (approved) => {
+                clearTimeout(timer);
+                log.info(`Approval resolved: approvalId=${approvalId} approved=${approved}`);
+                conn.write(JSON.stringify({ approved }));
+                conn.end();
+            }, { approvalId, sessionId: request.sessionId, tool: request.tool, description, command });
+        });
+        conn.on("error", () => {
+            // Hook process died, nothing to do
+        });
+    });
+    if (isWin) {
+        // Windows named pipes don't use file permissions — just listen.
+        // Handle EADDRINUSE: a previous instance may still hold the pipe.
+        server.on("error", (err) => {
+            if (err.code !== "EADDRINUSE")
+                throw err;
+            // Probe the existing pipe to check if something is actually listening
+            const probe = net.createConnection(socketPath, () => {
+                // Connection succeeded — another instance is genuinely running
+                probe.destroy();
+                log.error("Another BeachViber instance is already running (pipe in use). " +
+                    "Stop the other instance first, or restart your terminal.");
+                process.exit(1);
+            });
+            probe.on("error", () => {
+                // Pipe exists but nobody is listening — stale. Retry after brief delay.
+                log.info("Stale pipe detected, retrying...");
+                setTimeout(() => server.listen(socketPath), 500);
+            });
+        });
+        server.listen(socketPath);
+    }
+    else {
+        // Set restrictive umask before creating socket to eliminate TOCTOU race
+        const oldUmask = process.umask(0o177);
+        server.listen(socketPath, () => {
+            process.umask(oldUmask);
+        });
+    }
+    // Cleanup on process exit (Unix sockets need file removal; named pipes do not)
+    if (!isWin) {
+        const cleanup = () => {
+            try {
+                fs.unlinkSync(socketPath);
+            }
+            catch { }
+        };
+        process.on("exit", cleanup);
+        process.on("SIGINT", () => {
+            cleanup();
+            process.exit(0);
+        });
+        process.on("SIGTERM", () => {
+            cleanup();
+            process.exit(0);
+        });
+    }
+    return server;
+}

package/dist/config.js

@@ -0,0 +1,60 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { randomBytes } from "crypto";
+export const DEFAULT_RELAY_URL = "wss://relay.beachviber.com";
+export const DEFAULT_API_URL = "https://api.beachviber.com";
+// --- Profile support ---
+const PROFILE_RE = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,30}[a-zA-Z0-9])?$/;
+let _profile = null;
+export function setProfile(name) {
+    if (!PROFILE_RE.test(name)) {
+        throw new Error(`Invalid profile name "${name}": must be 1-32 alphanumeric/hyphen chars, no leading/trailing hyphen`);
+    }
+    _profile = name;
+}
+export function getProfile() {
+    return _profile;
+}
+export function getProfileSuffix() {
+    return _profile ? `-${_profile}` : "";
+}
+/** Test-only: reset profile state between tests */
+export function _resetProfile() {
+    _profile = null;
+}
+export function getBeachViberDir() {
+    return join(homedir(), ".beachviber");
+}
+function getConfigFile() {
+    return join(getBeachViberDir(), `config${getProfileSuffix()}.json`);
+}
+export function loadConfig() {
+    const file = getConfigFile();
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConfig(config) {
+    const dir = getBeachViberDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    writeFileSync(getConfigFile(), JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+}
+export function deleteConfig() {
+    const file = getConfigFile();
+    if (existsSync(file)) {
+        unlinkSync(file);
+        return true;
+    }
+    return false;
+}
+export function generateDeviceId() {
+    return `dev_${randomBytes(6).toString("hex")}`;
+}