ucu-mcp 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.4] - 2026-06-18
+
+4 个独立子 Agent 全面 code review 后的修复（skylight/element/tests/security）。
+
+### P0 Fixed（bugs/security）
+
+- **focusWithoutRaise 返回值检查反转**（skylight/main.swift:170）：`!= 0` 应为 `== 0`（OSStatus 0=success）。原代码导致 focus-without-raise 完全失效——per-pid 点击落到 AppKit 当前认为 active 的窗口，不一定是目标。
+- **runInputChecked cgevent fallback ENOENT**（utils/input.ts）：skylight-only 环境下 skylight 运行时错误会直接 throw ENOENT（cgevent-helper 不存在）。加 isCgeventAvailable 门控 + try/catch。
+- **appNameMatches 过度匹配**（helpers.ts）：双向 includes 导致 `"code"` 匹配 `"vscode"`。改为单向 process.includes(requested) + 最小 3 字符长度。
+- **needCoordinateClick 静默返回 axpress 成功**（element.ts）：JXA 请求坐标点击但 cx/cy 缺失时，原代码 fallthrough 返回 `{method:"axpress"}`（谎报成功）。改为抛 ElementNotFoundError。
+- **normalizeShortcut 别名绕过**（guard.ts）：`escape`→`esc`、`delete`→`del`、`return`→`enter` 不规范化，blocklist 可被长格式键名绕过（如 `cmd+option+escape` 不匹配 `command+esc+option`）。加 KEY_CANONICAL 表。
+- **find_element 密码字段不脱敏**（element-tools.ts）：AXSecureTextField/AXPasswordField 的 value 原样返回给模型。加 SENSITIVE_RE 脱敏为 `[REDACTED]`。
+- **clipboard_read 重分类为 input**（guard.ts）：从 OBSERVE_ACTIONS 移到 INPUT_ACTIONS。clipboard 可能含密码/TOTP，应受 user-activity pause 保护。
+
+### P1 Fixed（correctness/robustness）
+
+- **isSkylightAvailable 不检查 skylight:true**（utils/input.ts）：只查 `"ok"` 不查 `"skylight":true`，SPI 加载失败时仍认为可用。改为 regex 匹配 `/"skylight"\s*:\s*true/`。
+- **keepTargetAxAlive execFileSync 阻塞事件循环 5s**（window.ts）：fire-and-forget 但 execFileSync 同步阻塞。改为 setImmediate 让出 tick + timeout 5s→1s。
+- **doScroll 误报 per-pid**（skylight/main.swift）：scroll 事件无 field-40/window-loc 标记但返回 `method:"per-pid"`，调用方误以为成功。诚实报告 `hid-tap`。
+- **SENSITIVE_PROCESS_HINTS 不含空格变体 + 缺失条目**（input.ts）：`"keychainaccess"` 不匹配 `"keychain access"`（带空格）。改为 normalized 比对（strip 非字母数字）+ 补 keychain/keepassxc/coreauthui/passwords/systemsettings 等。
+
+### Tests
+
+- 328 passed（修复 clipboard_read 分类测试 + jxaOnlyPlatform 加 skylight:null 避免 keepTargetAxAlive 消耗 mock）。
+
 ## [0.6.3] - 2026-06-17
 
 SKILL.md Confirmation Policy + 修 permissions.test.ts CI 在 Ubuntu 全挂的 bug。

package/dist/src/mcp/tools/element-tools.js

@@ -19,6 +19,14 @@ export function registerElementTools(registerTool) {
         const safetyCtx = await getSafetyContext(undefined);
         const response = await withSafety({ action: "find_element", params: { ...safetyCtx }, requiresAccessibility: true,
             execute: () => getPlatform().findElement({ text: params.text, role: params.role, app: effectiveApp, depth: params.depth, includeBounds: params.includeBounds, maxResults: params.maxResults, textMode: params.textMode, visibleOnly: params.visibleOnly, value: params.value, index: params.index, near: params.near }) });
+        // Security: mask password/secret field values before returning to the model.
+        const SENSITIVE_RE = /password|passwd|secret|pincode|pin\b|token|credential|api[_-]?key|access[_-]?key|private[_-]?key/i;
+        const SENSITIVE_ROLES = new Set(["AXSecureTextField", "AXPasswordField"]);
+        for (const r of response.results) {
+            if (SENSITIVE_ROLES.has(r.role) || SENSITIVE_RE.test(r.name || "")) {
+                r.value = "[REDACTED]";
+            }
+        }
         const payload = { results: response.results, metrics: response.metrics };
         if (response.results.length === 0 && effectiveApp && response.metrics.scannedCount === 0) {
             payload.hint =

package/dist/src/platform/macos/element.js

@@ -148,7 +148,10 @@ export async function clickElement(elementId, app) {
     }
     // JXA requested a coordinate click → perform it via the input layer (per-process
     // when a pid is available, so the global cursor does not move).
-    if (result.needCoordinateClick && typeof result.cx === "number" && typeof result.cy === "number") {
+    if (result.needCoordinateClick) {
+        if (typeof result.cx !== "number" || typeof result.cy !== "number") {
+            throw new ElementNotFoundError(`${elementId}: element requested coordinate click but reported no bounds (offscreen?)`);
+        }
         await this.click(Math.round(result.cx), Math.round(result.cy), "left", false);
         return { method: "coordinate", verified: false };
     }
@@ -564,7 +567,10 @@ export async function clickMenuBarExtra(app, selector = {}) {
     if (!result.success) {
         throw new Error(`click_menu_bar_extra failed in ${app}: ${result.error}`);
     }
-    if (result.needCoordinateClick && typeof result.cx === "number" && typeof result.cy === "number") {
+    if (result.needCoordinateClick) {
+        if (typeof result.cx !== "number" || typeof result.cy !== "number") {
+            throw new ElementNotFoundError(`menu bar extra in ${app}: requested coordinate click but no bounds`);
+        }
         await this.click(Math.round(result.cx), Math.round(result.cy), "left", false);
         return { method: "coordinate", verified: false };
     }

package/dist/src/platform/macos/helpers.js

@@ -47,10 +47,14 @@ export function appNameMatches(processName, requestedApp) {
     const requested = normalizeAppName(requestedApp);
     if (!process || !requested)
         return false;
-    // normalizeAppName strips all non-alphanumerics, so equality is the only
-    // meaningful comparison. (Prior startsWith/includes with spaces were dead code
-    // since normalized strings contain no spaces/hyphens.)
-    return process === requested || process.includes(requested) || requested.includes(process);
+    if (process === requested)
+        return true;
+    // Substring match only for requests >= 3 chars to avoid "code"→"vscode".
+    // Only allow process.includes(requested) (not bidirectional) to prevent
+    // short requests greedily absorbing longer unrelated process names.
+    if (requested.length >= 3 && process.includes(requested))
+        return true;
+    return false;
 }
 export function selectWindowForApp(windows, requestedApp) {
     const requested = normalizeAppName(requestedApp);

package/dist/src/platform/macos/input.js

@@ -9,9 +9,12 @@ import { rethrowInputError, errorMessage } from "./helpers.js";
  * manager or auth dialog. These fall back to HID-tap (which at least requires
  * the app to be frontmost / visible to the user).
  */
+// Normalized (non-alphanumeric-stripped) so "Keychain Access" → "keychainaccess" matches.
 const SENSITIVE_PROCESS_HINTS = [
-    "keychainaccess", "1password", "lastpass", "bitwarden", "securityagent",
-    "authd", "loginwindow", "applekeychain", "dashlane",
+    "keychainaccess", "keychain", "1password", "lastpass", "bitwarden", "keepassxc",
+    "securityagent", "coreauthui", "authd", "loginwindow", "applekeychain", "dashlane",
+    "enpass", "keeper", "passwords", // macOS Passwords app (Sequoia+)
+    "systempreferences", "systemsettings", // where ucu-mcp's own permissions live
 ];
 /** Resolve the per-process event target from the active focus_app target (pid + windowNumber). */
 function targetOf() {
@@ -19,7 +22,8 @@ function targetOf() {
     if (!t || !t.pid || t.pid <= 0)
         return undefined;
     // Security: never route per-process events into sensitive apps (password managers / auth).
-    const name = (t.appName || "").toLowerCase();
+    // Normalize by stripping non-alphanumerics so "Keychain Access" → "keychainaccess".
+    const name = (t.appName || "").toLowerCase().replace(/[^a-z0-9]/g, "");
     if (SENSITIVE_PROCESS_HINTS.some((h) => name.includes(h))) {
         return undefined; // forces HID-tap fallback (requires frontmost)
     }

package/dist/src/platform/macos/window.js

@@ -108,16 +108,25 @@ export async function keepTargetAxAlive(pid) {
     const helperPath = resolveNativeHelper.call(this, "skylight", "skylight-helper");
     if (!helperPath)
         return;
-    try {
-        execFileSync(helperPath, [], {
-            input: JSON.stringify({ command: "keepAlive", pid }),
-            encoding: "utf8",
-            timeout: 5000,
+    // Defer to next tick so execFileSync doesn't block the current event loop tick.
+    // Lower timeout (1s) — keepAlive should be near-instant; 5s was too long.
+    await new Promise((resolve) => {
+        setImmediate(() => {
+            try {
+                execFileSync(helperPath, [], {
+                    input: JSON.stringify({ command: "keepAlive", pid }),
+                    encoding: "utf8",
+                    timeout: 1000,
+                });
+            }
+            catch {
+                // keepAlive is best-effort; ignore failures (helper missing / SPI unavailable).
+            }
+            finally {
+                resolve();
+            }
         });
-    }
-    catch {
-        // keepAlive is best-effort; ignore failures (helper missing / SPI unavailable).
-    }
+    });
 }
 export async function getActiveBrowserContext(app) {
     const appName = app || this.activeTarget?.appName;

package/dist/src/safety/guard.d.ts

@@ -24,7 +24,7 @@ export interface SafetyGuardConfig {
 }
 /** Actions that observe UI/system state without altering it. */
 export declare const OBSERVE_ACTIONS: ReadonlySet<string>;
-/** Actions that synthesize user input — need full user-activity protection. */
+/** Actions that synthesize user input OR access sensitive data — need full user-activity protection. */
 export declare const INPUT_ACTIONS: ReadonlySet<string>;
 export declare function classifyAction(action: string): "observe" | "input" | "other";
 export declare class SafetyGuard {

package/dist/src/safety/guard.js

@@ -84,13 +84,21 @@ const MODIFIER_CANONICAL = {
 };
 /** Normalize a shortcut string to lowercase, trimmed, sorted modifiers with
  *  modifier aliases canonicalized (alt→option, ctrl→control, cmd→command). */
+/** Canonical key name aliases — so blocklist entries match all spellings. */
+const KEY_CANONICAL = {
+    escape: "esc",
+    delete: "del",
+    backspace: "del",
+    return: "enter",
+    option: "alt",
+};
 function normalizeShortcut(raw) {
     return raw
         .toLowerCase()
         .split("+")
         .map((s) => {
         const t = s.trim();
-        return MODIFIER_CANONICAL[t] ?? t;
+        return MODIFIER_CANONICAL[t] ?? KEY_CANONICAL[t] ?? t;
     })
         .sort()
         .join("+");
@@ -111,7 +119,6 @@ export const OBSERVE_ACTIONS = new Set([
     "wait",
     "wait_for_element",
     "doctor",
-    "clipboard_read",
     // focus_app only sets the active target context via AppleScript activate
     // and an AX window lookup — it does not synthesize mouse or keyboard input,
     // so the user-activity pause must not block it. (OpenCode 0.3.7 follow-up)
@@ -119,7 +126,7 @@ export const OBSERVE_ACTIONS = new Set([
     // describe_screen reads screen state (OCR + AX), no input synthesis.
     "describe_screen",
 ]);
-/** Actions that synthesize user input — need full user-activity protection. */
+/** Actions that synthesize user input OR access sensitive data — need full user-activity protection. */
 export const INPUT_ACTIONS = new Set([
     "click",
     "double_click",
@@ -132,6 +139,9 @@ export const INPUT_ACTIONS = new Set([
     "type_in_element",
     "set_value",
     "click_menu_bar_extra",
+    // clipboard_read accesses potentially sensitive data (passwords/TOTP copied
+    // by password managers) — treat as input so the user-activity pause applies.
+    "clipboard_read",
     "clipboard_write",
 ]);
 export function classifyAction(action) {

package/dist/src/utils/input.js

@@ -65,7 +65,7 @@ function isSkylightAvailable() {
             encoding: "utf8",
             timeout: 3000,
         });
-        _skylightAvailable = stdout.includes('"ok"');
+        _skylightAvailable = /"skylight"\s*:\s*true/.test(stdout);
     }
     catch {
         _skylightAvailable = false;
@@ -103,17 +103,28 @@ function runInputChecked(payload, target) {
             // skylight crashed/timed out → fall through to cgevent.
         }
     }
-    // cgevent path (HID-tap) — the reliable fallback.
-    const raw = execFileSync(resolvedCgeventPath, [], {
-        input: JSON.stringify(payload),
-        encoding: "utf8",
-        timeout: 10000,
-    }).trim();
-    const resp = JSON.parse(raw);
-    if (resp.error) {
-        throw new Error(`native helper error: ${resp.error}`);
-    }
-    return "hid-tap";
+    // cgevent path (HID-tap) — the reliable fallback. Guard against ENOENT
+    // (cgevent-helper missing) when only skylight was available.
+    if (!isCgeventAvailable()) {
+        throw new Error("input dispatch failed: no native helper available (both cgevent and skylight unavailable or errored)");
+    }
+    try {
+        const raw = execFileSync(resolvedCgeventPath, [], {
+            input: JSON.stringify(payload),
+            encoding: "utf8",
+            timeout: 10000,
+        }).trim();
+        const resp = JSON.parse(raw);
+        if (resp.error) {
+            throw new Error(`native helper error: ${resp.error}`);
+        }
+        return "hid-tap";
+    }
+    catch (e) {
+        if (e instanceof Error && e.message.startsWith("native helper error:"))
+            throw e;
+        throw new Error(`input dispatch failed: cgevent helper unavailable (${e.message})`);
+    }
 }
 /** @deprecated use runInputChecked — kept for external callers/tests. */
 function runNativeChecked(payload) {

package/native/skylight/main.swift

@@ -167,7 +167,7 @@ func focusWithoutRaise(pid: Int32, windowID: Int) {
           windowID > 0 else { return }
     var prevPSN = [UInt32](repeating: 0, count: 2)
     var targetPSN = [UInt32](repeating: 0, count: 2)
-    let prevOk = prevPSN.withUnsafeMutableBytes { raw in frontFn(raw.baseAddress!) != 0 }
+    let prevOk = prevPSN.withUnsafeMutableBytes { raw in frontFn(raw.baseAddress!) == 0 }
     if prevOk {
         let cid = connFn()
         var ownerCid: UInt32 = 0
@@ -342,16 +342,12 @@ func doDrag(_ p: Input) -> String {
 }
 
 func doScroll(_ p: Input) -> String {
-    // Scroll events use CGEventCreateScrollWheelEvent; per-pid scroll posting is
-    // unreliable across app types, so we route via HID-tap but still report method.
+    // Scroll events via SLEventPostToPid lack field-40/window-location stamping
+    // (postPerPid is mouse-click-specific), so per-pid scroll is unreliable.
+    // Honestly report hid-tap so the caller's warning path fires correctly.
     let dy = Int32(-(p.deltaY ?? 0)); let dx = Int32(p.deltaX ?? 0)
     guard let ev = CGEvent(scrollWheelEvent2Source: nil, units: .pixel, wheelCount: 2, wheel1: dy, wheel2: dx, wheel3: 0)
     else { return "{\"error\":\"fail\"}" }
-    // Best-effort per-pid if we have a pid; scroll doesn't move the cursor noticeably anyway.
-    if let pid = p.pid, pid > 0, slPostToPid != nil, !isFrontmost(pid) {
-        slPostToPid?(pid, ev)
-        return "{\"ok\":true,\"method\":\"per-pid\"}"
-    }
     postHidTap(ev)
     return "{\"ok\":true,\"method\":\"hid-tap\"}"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucu-mcp",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "MCP server for Universal Computer Use — desktop automation for AI agents via Model Context Protocol",
   "type": "module",
   "bin": {