@angelky7/dsh-browser-control 0.0.0-stage → 1.1.0

package/lib/types/ws.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Server-side RFC 6455 frame codec for the single local extension link. The
+ * extension always masks its frames and never sends binary payloads; the
+ * server replies unmasked. Fragmented text messages accumulate across
+ * continuation frames, so a multi-megabyte screenshot result survives socket
+ * chunk boundaries.
+ * @module @deepseek-ai/dsh-browser-bridge/ws
+ */
+/** Hard ceiling on one frame's payload; a larger frame is a protocol error. */
+export declare const MAX_FRAME_BYTES: number;
+/** One parsed WebSocket frame. `opcode` follows RFC 6455: 1 text, 8 close, 9 ping, 10 pong, 0 continuation. */
+export interface WsFrame {
+    readonly fin: boolean;
+    readonly opcode: number;
+    readonly payload: Buffer;
+}
+/**
+ * Incremental frame parser over arbitrary TCP chunks. `drain` parses every
+ * complete frame currently buffered and keeps the remainder; an oversized or
+ * unmasked data frame throws, and the caller closes the link.
+ */
+export declare class FrameReader {
+    private buffer;
+    /** Append one TCP chunk to the parse buffer. */
+    push(chunk: Buffer): void;
+    /** Parse and consume every complete frame, invoking `onFrame` per frame in order. */
+    drain(onFrame: (frame: WsFrame) => void): void;
+    private readFrame;
+}
+/** Encode one unmasked text frame carrying a UTF-8 JSON message. */
+export declare function encodeTextFrame(text: string): Buffer;
+/** Encode one control frame (opcode 0x8 close, 0x9 ping, 0xA pong); payload stays ≤ 125 bytes. */
+export declare function encodeControlFrame(opcode: number, payload?: Buffer): Buffer;
+/** Build the close-frame bytes for a status code plus a UTF-8 reason within the 125-byte limit. */
+export declare function encodeCloseFrame(code: number, reason: string): Buffer;

package/lib/types/ws.js

@@ -0,0 +1,106 @@
+/**
+ * Server-side RFC 6455 frame codec for the single local extension link. The
+ * extension always masks its frames and never sends binary payloads; the
+ * server replies unmasked. Fragmented text messages accumulate across
+ * continuation frames, so a multi-megabyte screenshot result survives socket
+ * chunk boundaries.
+ * @module @deepseek-ai/dsh-browser-bridge/ws
+ */
+/** Hard ceiling on one frame's payload; a larger frame is a protocol error. */
+export const MAX_FRAME_BYTES = 64 * 1024 * 1024;
+/**
+ * Incremental frame parser over arbitrary TCP chunks. `drain` parses every
+ * complete frame currently buffered and keeps the remainder; an oversized or
+ * unmasked data frame throws, and the caller closes the link.
+ */
+export class FrameReader {
+    buffer = Buffer.alloc(0);
+    /** Append one TCP chunk to the parse buffer. */
+    push(chunk) {
+        this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
+    }
+    /** Parse and consume every complete frame, invoking `onFrame` per frame in order. */
+    drain(onFrame) {
+        for (;;) {
+            const frame = this.readFrame();
+            if (!frame)
+                return;
+            onFrame(frame);
+        }
+    }
+    readFrame() {
+        const buf = this.buffer;
+        if (buf.length < 2)
+            return null;
+        const fin = (buf[0] & 0x80) !== 0;
+        const opcode = buf[0] & 0x0f;
+        const masked = (buf[1] & 0x80) !== 0;
+        let length = buf[1] & 0x7f;
+        let offset = 2;
+        if (length === 126) {
+            if (buf.length < offset + 2)
+                return null;
+            length = buf.readUInt16BE(offset);
+            offset += 2;
+        }
+        else if (length === 127) {
+            if (buf.length < offset + 8)
+                return null;
+            const extended = buf.readBigUInt64BE(offset);
+            offset += 8;
+            if (extended > BigInt(MAX_FRAME_BYTES))
+                throw new Error(`websocket frame too large: ${extended} bytes`);
+            length = Number(extended);
+        }
+        let maskKey = null;
+        if (masked) {
+            if (buf.length < offset + 4)
+                return null;
+            maskKey = buf.subarray(offset, offset + 4);
+            offset += 4;
+        }
+        if (buf.length < offset + length)
+            return null;
+        if (!masked && (opcode === 0x1 || opcode === 0x0 || opcode === 0x2)) {
+            throw new Error('websocket client sent an unmasked data frame');
+        }
+        const payload = Buffer.from(buf.subarray(offset, offset + length));
+        if (maskKey) {
+            for (let i = 0; i < payload.length; i++)
+                payload[i] = payload[i] ^ maskKey[i & 3];
+        }
+        this.buffer = buf.subarray(offset + length);
+        return { fin, opcode, payload };
+    }
+}
+/** Encode one unmasked text frame carrying a UTF-8 JSON message. */
+export function encodeTextFrame(text) {
+    const payload = Buffer.from(text, 'utf8');
+    if (payload.length < 126) {
+        return Buffer.from([0x81, payload.length, ...payload]);
+    }
+    if (payload.length < 65_536) {
+        const header = Buffer.alloc(4);
+        header[0] = 0x81;
+        header[1] = 126;
+        header.writeUInt16BE(payload.length, 2);
+        return Buffer.concat([header, payload]);
+    }
+    const header = Buffer.alloc(10);
+    header[0] = 0x81;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(payload.length), 2);
+    return Buffer.concat([header, payload]);
+}
+/** Encode one control frame (opcode 0x8 close, 0x9 ping, 0xA pong); payload stays ≤ 125 bytes. */
+export function encodeControlFrame(opcode, payload = Buffer.alloc(0)) {
+    return Buffer.concat([Buffer.from([0x80 | opcode, payload.length]), payload]);
+}
+/** Build the close-frame bytes for a status code plus a UTF-8 reason within the 125-byte limit. */
+export function encodeCloseFrame(code, reason) {
+    const reasonBytes = Buffer.from(reason, 'utf8').subarray(0, 123);
+    const body = Buffer.alloc(2 + reasonBytes.length);
+    body.writeUInt16BE(code, 0);
+    reasonBytes.copy(body, 2);
+    return encodeControlFrame(0x8, body);
+}

package/llms.txt

@@ -0,0 +1,43 @@
+# DSH Browser Control
+
+Chrome 浏览器扩展 + DeepSeek Harness 插件，让 AI Agent 通过 CDP 驱动用户的真实浏览器。
+
+## 文件结构
+
+- `extension/` - Chrome MV3 扩展（background.js Service Worker + popup UI）
+- `src/` - dsh 插件源码（WebSocket 桥 + HTTP 面 + `browser_*` 工具）
+- `lib/` - 构建产物，按约定提交（npm 包只含宿主侧这一份，没有浏览器端模块）
+- `verify/` - 纯 node 实测台，`npm run verify` 跑完（见 `verify/README.md`）
+- `install.sh` - 旧「复制进 harness 源码树」方式的安装脚本（v1.0.2 及以前）
+- `cordis.patch.yml` - 插件挂载配置（`enabled: true`，与 schema 默认保持一致）
+- `dsh-config/` - dsh 配置项参考
+
+## 技术栈
+
+- Chrome DevTools Protocol（CDP）via chrome.debugger API
+- WebSocket（扩展 → 桥，JSON 文本帧）
+- Node.js HTTP（状态页 + 命令面 + 清理 API）
+- RFC 6455 帧编解码
+- TypeScript（strict 模式）
+- Cordis 插件系统（DeepSeek Harness 生态）
+
+## 信任边界
+
+- 只绑 `127.0.0.1`；**Token 才是真正的边界，回环绑定不是**
+- `/api/command`、`/api/cleanup` 要求 Token（`Authorization: Bearer` / `X-Token` / `?token=`），与 WS 同一个凭据，常数时间比较
+- WS 升级校验 `Host` 必须是回环（挡 DNS 重绑定）并拒绝网页 `Origin`，只放行 `*-extension://` 与无 Origin 的本机客户端
+- 所有 HTTP 响应都不带 `Access-Control-Allow-Origin`
+- `/` 与 `/api/status` 免鉴权，只报链路状态
+- 两个本机策略开关（profile 的 `browser-bridge` 配置）：`readOnly: true` 拒绝一切会改变页面/浏览器状态或删本机文件的命令，`allowScript: false` 单独关掉 `browser_evaluate`（它能做其它所有工具能做的事）。闸门在把命令发给扩展**之前**，所以被拒的调用零副作用；它们只约束模型那条工具面，HTTP 面按同一 token 走、不受影响，也**不是**防有权限的人
+- 扩展弹窗里的「锁定」是另一层：只有人工通道能开与关，冻结期间命令在扩展的 `runCommand` 入口就被拒绝（连接保持），读不出锁状态时按冻结处理（fail-closed）
+- `browser_hold`（接管浮层）是**软层**：它告诉用户模型在操作这一页并挡住误触，用户双击即可关掉；卡片上按「中止操作」后扩展拒绝 `click`/`input`/`press`/`nav`，但模型可以调 `hold action=off` 解除。它不是安全边界，也不是防逃逸手段——要冻住浏览器用扩展弹窗里的「锁定」
+
+## 关键文件
+
+- `src/index.ts` - 21 个 `browser_*` 工具注册 + settings 接线的版本兼容分支
+- `src/policy.ts` - 三张互不相同的表：只读白名单、脚本命令、插件本地破坏性命令（`browser_cleanup` 不经过 `execute()`，必须自己站闸门）
+- `src/server.ts` - WebSocket 服务 + HTTP 面（鉴权、来源校验、状态页）
+- `src/ws.ts` - RFC 6455 帧编解码
+- `src/errors.ts` - 失败分类：`code` / `effectState` / `hint` 写进模型读得到的那句话
+- `extension/background.js` - CDP 命令分发 + 持久 debugger 附着 + 本地硬锁 + 接管浮层（`hold`）
+- `extension/popup.js` - 弹窗状态 UI 与「锁定」按钮

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "@angelky7/dsh-browser-control",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Local WebSocket bridge between dsh and the DSH Browser Control browser extension, with model-facing browser_* tools and a Settings-managed on/off switch",
+  "version": "1.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "cordis.patch.yml",
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "README.md",
+    "README.en.md",
+    "llms.txt",
+    "LICENSE"
+  ],
+  "license": "AGPL-3.0-only",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check": "npm run typecheck && npm run build && publint",
+    "verify": "node verify/verify_config_patch.mjs && node verify/verify_peers.mjs && node verify/verify_surface.mjs && node verify/verify_tab_groups.mjs && node verify/verify_tabs_close_many.mjs && node verify/verify_cdp_retry.mjs && node verify/verify_snapshot_ax.mjs && node verify/verify_hard_lock.mjs && node verify/verify_policy.mjs && node verify/verify_extension_e2e.mjs && node verify/verify_plugin.mjs legacy && node verify/verify_plugin.mjs conflict && node verify/verify_plugin.mjs new && node verify/verify_http.mjs && node verify/verify_errors.mjs && node verify/verify_hold.mjs && node verify/verify_protocol.mjs && node verify/verify_bundle_http.mjs && node verify/verify_nav_report.mjs && node verify/verify_nav_landing.mjs && node verify/verify_render_contract.mjs && node verify/verify_press_events.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/angelky7/dsh-browser-control.git"
+  },
+  "bugs": {
+    "url": "https://github.com/angelky7/dsh-browser-control/issues"
+  },
+  "homepage": "https://github.com/angelky7/dsh-browser-control#readme",
+  "keywords": [
+    "deepseek-harness",
+    "deepseek",
+    "dsh",
+    "dsh-plugin",
+    "browser",
+    "browser-automation",
+    "cdp",
+    "chrome-extension",
+    "websocket"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-invariants": "0.2.0-rc.2 || >=0.1.0-rc.1 <0.3.0-0",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.2 || >=0.1.0-rc.1 <0.3.0-0",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2 || >=0.1.0-rc.1 <0.3.0-0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-invariants": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@types/node": "^22.20.0",
+    "publint": "^0.3.21",
+    "semver": "^7.8.5",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3"
+  }
+}