screenhand 0.1.1 → 0.3.0

package/dist/src/test-mcp-protocol.js

@@ -0,0 +1,154 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// This file is part of ScreenHand.
+//
+// ScreenHand is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, version 3.
+//
+// ScreenHand is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, "..");
+const tsxBin = path.join(projectRoot, "node_modules", ".bin", "tsx");
+const TIMEOUT_MS = 10_000;
+const proc = spawn(tsxBin, [path.join(projectRoot, "src/mcp-entry.ts")], {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: { ...process.env, SCREENHAND_ADAPTER: "placeholder" },
+    cwd: projectRoot,
+});
+let stderrBuf = "";
+proc.stderr.on("data", (d) => { stderrBuf += d.toString(); });
+// MCP SDK v1.27 uses newline-delimited JSON (NDJSON), not Content-Length framing
+function send(msg) {
+    proc.stdin.write(JSON.stringify(msg) + "\n");
+}
+const rl = createInterface({ input: proc.stdout });
+const lineQueue = [];
+let lineWaiter = null;
+rl.on("line", (line) => {
+    if (lineWaiter) {
+        const w = lineWaiter;
+        lineWaiter = null;
+        w(line);
+    }
+    else {
+        lineQueue.push(line);
+    }
+});
+function readResponse() {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            lineWaiter = null;
+            reject(new Error(`Timeout. stderr: ${stderrBuf.slice(-300)}`));
+        }, TIMEOUT_MS);
+        const handle = (line) => {
+            clearTimeout(timer);
+            resolve(JSON.parse(line));
+        };
+        const queued = lineQueue.shift();
+        if (queued) {
+            clearTimeout(timer);
+            resolve(JSON.parse(queued));
+        }
+        else {
+            lineWaiter = handle;
+        }
+    });
+}
+function fail(msg) {
+    console.error("FAIL:", msg);
+    proc.kill();
+    process.exit(1);
+}
+try {
+    // Wait for server to start
+    await new Promise((r) => setTimeout(r, 2000));
+    // 1. Initialize
+    console.log("Sending initialize...");
+    send({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "test-client", version: "1.0" },
+        },
+    });
+    const initResp = await readResponse();
+    const initResult = initResp.result;
+    if (!initResult)
+        fail(`No init result: ${JSON.stringify(initResp)}`);
+    console.log("=== Initialize ===");
+    console.log(`  Protocol: ${initResult.protocolVersion}`);
+    console.log(`  Server: ${JSON.stringify(initResult.serverInfo)}`);
+    // 2. Send initialized notification
+    send({ jsonrpc: "2.0", method: "notifications/initialized" });
+    await new Promise((r) => setTimeout(r, 300));
+    // 3. List tools
+    console.log("\nListing tools...");
+    send({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
+    const toolsResp = await readResponse();
+    const toolsResult = toolsResp.result;
+    if (!toolsResult)
+        fail(`No tools result: ${JSON.stringify(toolsResp)}`);
+    const tools = toolsResult.tools ?? [];
+    console.log("=== Tools ===");
+    for (const tool of tools) {
+        console.log(`  ${tool.name}: ${(tool.description ?? "").slice(0, 70)}`);
+    }
+    console.log(`\n  Total: ${tools.length} tools`);
+    if (tools.length < 10)
+        fail(`Expected 16 tools, got ${tools.length}`);
+    // 4. Test session_start
+    console.log("\nCalling session_start...");
+    send({
+        jsonrpc: "2.0",
+        id: 3,
+        method: "tools/call",
+        params: { name: "session_start", arguments: {} },
+    });
+    const sessionResp = await readResponse();
+    const sessionResult = sessionResp.result;
+    if (!sessionResult)
+        fail(`No session result: ${JSON.stringify(sessionResp)}`);
+    const sessionContent = sessionResult.content;
+    const sessionData = JSON.parse(sessionContent?.[0]?.text ?? "{}");
+    console.log("=== session_start ===");
+    console.log(`  Session ID: ${sessionData.sessionId}`);
+    console.log(`  Profile: ${sessionData.profile}`);
+    if (!sessionData.sessionId)
+        fail("No sessionId returned");
+    // 5. Test app_list (should work with placeholder)
+    console.log("\nCalling app_list...");
+    send({
+        jsonrpc: "2.0",
+        id: 4,
+        method: "tools/call",
+        params: { name: "app_list", arguments: { sessionId: sessionData.sessionId } },
+    });
+    const appResp = await readResponse();
+    const appResult = appResp.result;
+    console.log("=== app_list ===");
+    const appContent = appResult?.content;
+    const isError = appResult?.isError;
+    console.log(`  isError: ${isError ?? false}`);
+    console.log(`  Response: ${(appContent?.[0]?.text ?? "").slice(0, 100)}`);
+    proc.kill();
+    console.log("\nAll tests passed!");
+    process.exit(0);
+}
+catch (e) {
+    fail(e instanceof Error ? e.message : String(e));
+}

package/dist/src/types.js

@@ -0,0 +1,17 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// This file is part of ScreenHand.
+//
+// ScreenHand is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, version 3.
+//
+// ScreenHand is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
+export {};

package/dist/src/util/atomic-write.js

@@ -0,0 +1,133 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// This file is part of ScreenHand.
+//
+// ScreenHand is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, version 3.
+//
+// ScreenHand is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
+/**
+ * Atomic file writes — temp file + rename to prevent corruption on crash.
+ *
+ * Also provides corrupt-file recovery: if the primary file is unreadable,
+ * falls back to the `.bak` backup created on the previous successful write.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+/**
+ * Write data atomically: write to a temp file in the same directory,
+ * then rename over the target. On POSIX, rename is atomic within the
+ * same filesystem, so readers always see either the old or new content.
+ *
+ * Also keeps a single `.bak` of the previous version for recovery.
+ */
+export function writeFileAtomicSync(filePath, data) {
+    const dir = path.dirname(filePath);
+    const tmp = path.join(dir, `.${path.basename(filePath)}.${crypto.randomBytes(4).toString("hex")}.tmp`);
+    try {
+        fs.writeFileSync(tmp, data, { mode: 0o644 });
+        // Back up current file before overwriting (ignore if it doesn't exist yet)
+        // V3: Check for symlinks before backup to prevent data exfiltration
+        try {
+            const stat = fs.lstatSync(filePath);
+            if (stat.isSymbolicLink()) {
+                // Target is a symlink — skip backup and remove the symlink before writing
+                fs.unlinkSync(filePath);
+            }
+            else {
+                fs.copyFileSync(filePath, filePath + ".bak");
+            }
+        }
+        catch {
+            // No existing file to back up (ENOENT) — fine
+        }
+        fs.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        // Clean up temp file on failure
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+/**
+ * Async variant — same temp+rename approach but non-blocking.
+ * Falls back to sync rename (rename is fast, effectively atomic).
+ */
+export function writeFileAtomic(filePath, data, callback) {
+    const dir = path.dirname(filePath);
+    const tmp = path.join(dir, `.${path.basename(filePath)}.${crypto.randomBytes(4).toString("hex")}.tmp`);
+    fs.writeFile(tmp, data, { mode: 0o644 }, (writeErr) => {
+        if (writeErr) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* ignore */ }
+            callback(writeErr);
+            return;
+        }
+        // Back up current file (best-effort, sync is fine for a copy)
+        // V3: Check for symlinks before backup to prevent data exfiltration
+        try {
+            const stat = fs.lstatSync(filePath);
+            if (stat.isSymbolicLink()) {
+                fs.unlinkSync(filePath);
+            }
+            else {
+                fs.copyFileSync(filePath, filePath + ".bak");
+            }
+        }
+        catch { /* ignore — ENOENT means no file to back up */ }
+        fs.rename(tmp, filePath, (renameErr) => {
+            if (renameErr) {
+                try {
+                    fs.unlinkSync(tmp);
+                }
+                catch { /* ignore */ }
+            }
+            callback(renameErr);
+        });
+    });
+}
+/**
+ * Read a JSON file with corrupt-file recovery.
+ * If the primary file fails to parse, tries the `.bak` backup.
+ * Returns the parsed object, or null if both are unreadable.
+ */
+export function readJsonWithRecovery(filePath) {
+    // Try primary file
+    const primary = tryParseJsonFile(filePath);
+    if (primary !== null)
+        return primary;
+    // Primary is missing or corrupt — try backup
+    const backup = tryParseJsonFile(filePath + ".bak");
+    if (backup !== null) {
+        // Restore backup as primary so next read is fast
+        try {
+            fs.copyFileSync(filePath + ".bak", filePath);
+        }
+        catch { /* ignore */ }
+        return backup;
+    }
+    return null;
+}
+function tryParseJsonFile(filePath) {
+    try {
+        const data = fs.readFileSync(filePath, "utf-8");
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/util/sanitize.js

@@ -0,0 +1,146 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Shared sanitization utilities for redacting sensitive data from tool outputs.
+ * Used by both the world model (state persistence) and MCP tool responses.
+ */
+import { execSync } from "node:child_process";
+import os from "node:os";
+const MAX_STRING_LENGTH = 1000;
+const ALLOWED_URL_PROTOCOLS = new Set(["http:", "https:", "about:", "chrome:", "chrome-extension:"]);
+const SENSITIVE_URL_PARAMS = new Set([
+    "code", "token", "access_token", "refresh_token", "id_token",
+    "secret", "password", "key", "api_key", "apikey", "auth",
+    "session", "session_id", "sessionid", "state", "nonce",
+]);
+const SENSITIVE_LABEL_PATTERNS = [
+    // email:password in window titles (e.g. "user@example.com:P@ssw0rd! - Chrome")
+    [/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+:[^\s]+/g, "[CREDENTIALS_REDACTED]"],
+    // Bearer tokens
+    [/Bearer\s+[A-Za-z0-9\-._~+/]+=*/g, "[BEARER_REDACTED]"],
+];
+/**
+ * Sanitize untrusted strings: truncate + strip control characters.
+ */
+export function sanitizeString(s) {
+    // eslint-disable-next-line no-control-regex
+    const stripped = s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+    return stripped.length > MAX_STRING_LENGTH
+        ? stripped.slice(0, MAX_STRING_LENGTH)
+        : stripped;
+}
+/**
+ * Sanitize a URL: validate protocol + redact sensitive query params.
+ */
+export function sanitizeUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (!ALLOWED_URL_PROTOCOLS.has(parsed.protocol))
+            return "about:blocked";
+        let redacted = false;
+        for (const paramName of parsed.searchParams.keys()) {
+            if (SENSITIVE_URL_PARAMS.has(paramName.toLowerCase())) {
+                parsed.searchParams.set(paramName, "[REDACTED]");
+                redacted = true;
+            }
+        }
+        return redacted ? parsed.toString() : url;
+    }
+    catch {
+        return "about:blocked";
+    }
+}
+/**
+ * Check if a string looks like a token/key (32+ chars, 3+ character classes).
+ */
+function looksLikeToken(s) {
+    if (s.length < 32)
+        return false;
+    const hasUpper = /[A-Z]/.test(s);
+    const hasLower = /[a-z]/.test(s);
+    const hasDigit = /[0-9]/.test(s);
+    const hasSpecial = /[\-._~+/]/.test(s);
+    const classes = [hasUpper, hasLower, hasDigit, hasSpecial].filter(Boolean).length;
+    return classes >= 3;
+}
+/**
+ * Redact sensitive patterns from labels/titles: credentials, bearer tokens, long token strings.
+ */
+export function redactSensitiveLabel(label) {
+    let result = label;
+    for (const [pattern, replacement] of SENSITIVE_LABEL_PATTERNS) {
+        result = result.replace(pattern, replacement);
+    }
+    result = result.replace(/[A-Za-z0-9\-._~+/]{32,}={0,2}/g, (match) => looksLikeToken(match) ? "[TOKEN_REDACTED]" : match);
+    return result;
+}
+/**
+ * Redact PII patterns from text for persistence paths (Option C: redact on write, not on read).
+ * Catches: email addresses, phone numbers, and the local user's name parts.
+ * Applied to: memory actions/strategies, playbook exports, timeline logs.
+ * NOT applied to: live tool responses (ocr, ui_tree, screenshot, browser_dom, world_state).
+ */
+export function redactPII(text) {
+    let result = text;
+    // Email addresses
+    result = result.replace(/[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}/g, "[EMAIL_REDACTED]");
+    // Phone numbers — international and domestic formats
+    result = result.replace(/(?:\+\d{1,3}[\s\-]?)?\(?\d{3}\)?[\s.\-]?\d{3}[\s.\-]?\d{4}/g, "[PHONE_REDACTED]");
+    // Local user name parts (from OS)
+    result = redactUsername(result);
+    // Credential patterns already handled by redactSensitiveLabel
+    result = redactSensitiveLabel(result);
+    return result;
+}
+/**
+ * Redact the macOS username from strings (e.g. menu labels like "Log Out username").
+ */
+let _cachedNameParts = null;
+/** Collect all name parts to redact: short username, full name from id -F, home dir name. */
+function getNameParts() {
+    if (_cachedNameParts !== null)
+        return _cachedNameParts;
+    const parts = new Set();
+    // Short username from env
+    const username = process.env.USER || process.env.USERNAME || "";
+    if (username.length >= 2)
+        parts.add(username);
+    // Home directory basename (e.g. /Users/khushi → khushi)
+    try {
+        const home = os.homedir();
+        const homeName = home.split("/").pop() || "";
+        if (homeName.length >= 2)
+            parts.add(homeName);
+    }
+    catch { /* ignore */ }
+    // Full display name from id -F (macOS only)
+    try {
+        const fullName = execSync("id -F", { encoding: "utf-8", timeout: 2000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+        if (fullName.length >= 2) {
+            parts.add(fullName);
+            // Also add individual name words (e.g. "khushi goyal" → "khushi", "goyal")
+            for (const word of fullName.split(/\s+/)) {
+                if (word.length >= 2)
+                    parts.add(word);
+            }
+        }
+    }
+    catch { /* not macOS or id -F unavailable */ }
+    // Sort longest first so longer matches take priority
+    _cachedNameParts = [...parts].sort((a, b) => b.length - a.length);
+    return _cachedNameParts;
+}
+/**
+ * Redact the macOS username, full display name, and individual name parts from strings.
+ * Also catches common patterns like "Log Out <name>" where the name may not match env vars.
+ */
+export function redactUsername(text) {
+    let result = text;
+    for (const part of getNameParts()) {
+        result = result.replaceAll(part, "[USER]");
+    }
+    // Catch "Log Out <name>" pattern — macOS always formats this as "Log Out <full display name>"
+    // The name part may already be partially redacted (e.g. "[USER] goyal"), so match everything after "Log Out "
+    result = result.replace(/Log Out [^\n:]+/g, "Log Out [USER]");
+    return result;
+}