dsh-tabbit 0.2.3 → 0.3.2

package/lib/runtime/net.js

@@ -0,0 +1,143 @@
+/*
+ * ============================================================================
+ * 文件职责：内网/私有目标判定（供"页面读取权限"和 web_fetch 使用）
+ * ============================================================================
+ *
+ * 为什么需要它？—— SSRF 防护（Server-Side Request Forgery，服务端请求伪造）。
+ * web_fetch 是拿【用户的真实浏览器】去抓网页的：如果放任模型抓
+ * `http://192.168.1.1/`（路由器管理页）、`http://localhost:8080/`（本机内部
+ * 服务）这类地址，等于把用户内网暴露给了提示词注入攻击。dsh 官方出厂就是因为
+ * 没有 provider 能负责任地处理这个问题，才把 web_fetch 整个禁用的。
+ * 本插件的方案：抓内网目标不禁止，但走独立的审批门（settings
+ * `tabbit.intranetFetch`，默认逐 origin 询问用户）——判定"是不是内网目标"
+ * 就是本文件的活。
+ *
+ * 设计取向：尽力而为（best-effort），三层判定由快到慢：
+ *   1. 字面 IP：同步判段（10.x、127.x、192.168.x 等私有网段）；
+ *   2. 域名形态：同步判形（localhost、*.local、无点裸主机名等）；
+ *   3. DNS 解析：真的去查这个域名解析到什么 IP，但限时（默认 1.5 秒）——
+ *      查不出来就当"未知非内网"放行（反正解析不了的域名导航自己会失败）。
+ *
+ * 重定向问题：这里只判定【请求发起时】的 URL；公网 URL 302 跳到内网地址的
+ * 情况，由 web-fetch provider 在拿到最终 URL 后【再查一次】兜底（见
+ * src/web-fetch/index.ts 的"redirect containment"段）。
+ */
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+/*
+ * IPv4 私有段判定。命中任何一段即视为私有：
+ *   10.0.0.0/8         企业内网 A 段
+ *   127.0.0.0/8        回环（本机）
+ *   0.0.0.0/8          "本网络"保留段
+ *   169.254.0.0/16     链路本地（DHCP 拿不到地址时的自动配置段）
+ *   172.16.0.0/12      企业内网 B 段（172.16 ~ 172.31）
+ *   192.168.0.0/16     家用路由器最常见段
+ *   100.64.0.0/10      CGNAT（运营商级 NAT，Tailscale 等 VPN 也用它）
+ */
+function ipv4IsPrivate(ip) {
+    const parts = ip.split('.').map(Number);
+    if (parts.length !== 4 || parts.some((n) => Number.isNaN(n)))
+        return false;
+    const [a, b] = parts;
+    if (a === 10 || a === 127 || a === 0)
+        return true;
+    if (a === 169 && b === 254)
+        return true;
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // CGNAT
+    return false;
+}
+/*
+ * IPv6 私有段判定：
+ *   ::1        回环；:: 未指定地址
+ *   fe80::/10  链路本地
+ *   fc00::/7   ULA（唯一本地地址，IPv6 的"内网段"，fc/fd 开头）
+ *   ::ffff:x.x.x.x  IPv4 映射地址——剥掉前缀后按 IPv4 规则复判
+ */
+function ipv6IsPrivate(ip) {
+    const lower = ip.toLowerCase();
+    if (lower === '::1' || lower === '::')
+        return true;
+    if (lower.startsWith('fe80:') || lower.startsWith('fc') || lower.startsWith('fd'))
+        return true;
+    if (lower.startsWith('::ffff:'))
+        return ipv4IsPrivate(lower.slice('::ffff:'.length));
+    return false;
+}
+/* 字面 IP（v4 或 v6）是否属于私有/回环段。isIP 返回 4/6/0（0=不是 IP）。 */
+export function ipIsPrivate(ip) {
+    const version = isIP(ip);
+    if (version === 4)
+        return ipv4IsPrivate(ip);
+    if (version === 6)
+        return ipv6IsPrivate(ip);
+    return false;
+}
+/*
+ * 不查 DNS 的"域名形态"判定：一眼就能看出是本地/内网名字的模式。
+ *   - localhost 及 *.localhost；
+ *   - 常见内网专用后缀：.local（mDNS）/.internal/.lan/.home/.corp；
+ *   - 不含点的裸主机名（如 http://nas/ ——公网域名必有点）。
+ * 末尾的 `.` 是 DNS 的"绝对域名"写法（如 example.com.），先剥掉再比。
+ */
+export function hostnameLooksLocal(hostname) {
+    const name = hostname.replace(/\.$/u, '').toLowerCase();
+    if (name === 'localhost' || name.endsWith('.localhost'))
+        return true;
+    if (name.endsWith('.local') || name.endsWith('.internal') || name.endsWith('.lan') || name.endsWith('.home') || name.endsWith('.corp')) {
+        return true;
+    }
+    if (!name.includes('.') && isIP(name) === 0)
+        return true;
+    return false;
+}
+/*
+ * 综合判定一个 URL 是否指向私有/内网目标。
+ *
+ * @returns 判定为私有时返回【原因描述字符串】（直接用于审批询问的文案里，
+ *          让用户知道为什么被拦）；公网或无法判定时返回 undefined。
+ *
+ * 判定顺序：URL 能不能解析 → 主机是不是字面 IP → 域名形态 → 限时 DNS。
+ * DNS 用 Promise.race 跟一个定时器赛跑：超过 dnsBudgetMs 就放弃等待，
+ * 按"未知"处理——宁可漏判也不让权限检查把每次 fetch 卡住几秒。
+ * （漏判的兜底：navigation 之后 web-fetch 会对最终 URL 的字面形态再查一次。）
+ */
+export async function privateTargetReason(rawUrl, dnsBudgetMs = 1500) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        // 连 URL 都不是：不归这里管（工具那边自会报"非法 URL"）。
+        return undefined;
+    }
+    // IPv6 字面量在 URL 里带方括号（http://[::1]/），先剥掉。
+    const hostname = url.hostname.replace(/^\[|\]$/gu, '');
+    if (isIP(hostname) !== 0) {
+        return ipIsPrivate(hostname) ? `IP address ${hostname} is private/loopback` : undefined;
+    }
+    if (hostnameLooksLocal(hostname)) {
+        return `hostname "${hostname}" looks like a local/intranet name`;
+    }
+    try {
+        // lookup(all:true) 返回该域名的全部解析地址；任何一个落在私有段就算私有
+        // （防"公网域名解析到内网 IP"的 DNS rebinding 变体）。
+        const resolved = await Promise.race([
+            lookup(hostname, { all: true }),
+            new Promise((resolve) => setTimeout(() => resolve(undefined), dnsBudgetMs).unref?.()),
+        ]);
+        if (Array.isArray(resolved)) {
+            const hit = resolved.find((entry) => ipIsPrivate(entry.address));
+            if (hit)
+                return `hostname "${hostname}" resolves to private address ${hit.address}`;
+        }
+    }
+    catch {
+        /* 域名解析不了：交给导航自己失败，这里不拦 */
+    }
+    return undefined;
+}

package/lib/runtime/peer.js

@@ -0,0 +1,132 @@
+/*
+ * ============================================================================
+ * 文件职责：「观看实例」溯源——从一条本机 TCP 连接反查是哪个 Tabbit 在访问我们
+ * ============================================================================
+ *
+ * 解决什么问题？多实例机器上（用户装了好几个 Tabbit），执行浏览器任务时该选
+ * 哪个实例？最符合直觉的答案是：【用户正用哪个 Tabbit 看 dsh 网页界面，
+ * 就在哪个 Tabbit 里执行】——"在哪看，就在哪跑"。
+ *
+ * 但 HTTP 请求本身不会告诉我们"我来自哪个浏览器"。本文件用一套 macOS 系统
+ * 工具链把它侦查出来：
+ *
+ *   ① dsh 网页在浏览器里加载时，前端插件（client/client.js）会向
+ *      `/tabbit/instance-hint` 发一个 POST（见 src/mentions/index.ts）；
+ *   ② 服务端拿到这条 TCP 连接的【对端端口号】（remotePort）——注意我们不信
+ *      请求体里的任何内容，身份完全取自 socket 本身，伪造不了；
+ *   ③ 用 `lsof` 命令查：本机哪个进程占用着这个端口的客户端一侧？
+ *      → 得到发起请求的进程 pid（Chromium 的某个网络辅助进程）；
+ *   ④ 用 `ps` 命令沿父进程链往上爬（Chromium 是多进程架构：辅助进程都是
+ *      主进程的子孙）；
+ *   ⑤ 每个在线 Tabbit 实例的 endpoint.json 里记录着它主进程的 pid
+ *      （browserPid 字段）——父链上撞到哪个实例的 browserPid，就是它了。
+ *
+ * 设计取向：这是一个【启发式】（heuristic）：任何一步失败（不是 macOS、
+ * lsof/ps 不可用、对端不是 Tabbit 而是普通浏览器…）都返回 undefined，
+ * 调用方（core 的实例四级解析）落回下一优先级，绝不因此报错。
+ *
+ * 仅支持 macOS：Runtime Service 目前未在 Windows 启用，lsof/ps 的调用方式
+ * 也是 macOS 版的。
+ */
+import { execFile } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { promisify } from 'node:util';
+// execFile 的 Promise 版（原版是回调风格）；比 exec 安全——参数按数组传，
+// 不经过 shell，不存在命令注入问题。
+const execFileAsync = promisify(execFile);
+/*
+ * 建立 browserPid → 实例 id 的映射表（步骤⑤的查找表）。
+ * 只看在线实例；endpoint.json 解析失败（可能正赶上浏览器重启、文件被删）
+ * 就跳过该实例。
+ */
+function browserPidMap(instances) {
+    const map = new Map();
+    for (const instance of instances) {
+        if (!instance.online)
+            continue;
+        try {
+            const endpoint = JSON.parse(readFileSync(instance.endpointPath, 'utf8'));
+            if (typeof endpoint.browserPid === 'number' && endpoint.browserPid > 0) {
+                map.set(endpoint.browserPid, instance.id);
+            }
+        }
+        catch {
+            /* endpoint 文件与浏览器重启竞态：跳过这个实例 */
+        }
+    }
+    return map;
+}
+/*
+ * 解析 `lsof -Fpn` 的机器可读输出（步骤③的核心）。
+ *
+ * -F 输出格式：每行一个字段，首字符是字段类型——
+ *   p<pid>   接下来的行都属于这个进程
+ *   n<名字>  一条网络连接，形如 "127.0.0.1:54321->127.0.0.1:3199"
+ *
+ * 我们要找的是：哪个进程的连接里，【本地端】（-> 左边）端口等于 peerPort。
+ * 为什么看本地端？——对端端口 X 对我们（服务器）来说是"对方的端口"，但对
+ * 发起连接的客户端进程来说，X 正是它自己的本地端口。同时排除自己（dsh 进程
+ * 也持有这条连接的服务端一侧，别把自己认成客户端）。
+ *
+ * 导出仅为可单测（纯函数，喂字符串就能测）。
+ */
+export function clientPidFromLsof(output, peerPort, selfPid) {
+    let current;
+    for (const line of output.split('\n')) {
+        if (line.startsWith('p')) {
+            current = Number.parseInt(line.slice(1), 10);
+            continue;
+        }
+        if (!line.startsWith('n') || current === undefined || current === selfPid)
+            continue;
+        const local = line.slice(1).split('->')[0] ?? '';
+        if (local.endsWith(`:${peerPort}`))
+            return current;
+    }
+    return undefined;
+}
+/*
+ * 主入口：给定一条 loopback 连接的对端端口，返回拥有它的 Tabbit 实例 id。
+ * 非 macOS、端口非法、任何查询失败、或对端根本不是 Tabbit → undefined。
+ */
+export async function instanceIdForPeerPort(peerPort, instances, selfPid = process.pid) {
+    if (process.platform !== 'darwin')
+        return undefined;
+    if (!Number.isInteger(peerPort) || peerPort <= 0)
+        return undefined;
+    const byPid = browserPidMap(instances);
+    if (byPid.size === 0)
+        return undefined;
+    // 步骤③：lsof 按端口查连接。-n/-P 禁用域名/端口名反解（快很多），
+    // -iTCP:端口 过滤，-Fpn 机器可读输出。整体限时 3 秒。
+    let owner;
+    try {
+        const { stdout } = await execFileAsync('lsof', ['-n', '-P', `-iTCP:${peerPort}`, '-Fpn'], { timeout: 3000 });
+        owner = clientPidFromLsof(stdout, peerPort, selfPid);
+    }
+    catch {
+        return undefined;
+    }
+    if (owner === undefined)
+        return undefined;
+    // 步骤④：Chromium 辅助进程是主浏览器进程的子孙，沿父链最多爬 8 跳。
+    // `ps -o ppid= -p <pid>` 只输出该进程的父 pid。
+    let pid = owner;
+    for (let hop = 0; hop < 8 && pid > 1; hop += 1) {
+        const matched = byPid.get(pid);
+        if (matched !== undefined)
+            return matched; // 步骤⑤：撞上某实例的主进程 pid
+        try {
+            const { stdout } = await execFileAsync('ps', ['-o', 'ppid=', '-p', String(pid)], { timeout: 2000 });
+            const ppid = Number.parseInt(stdout.trim(), 10);
+            // 防御：ppid 非法或自指（不该发生）就放弃，绝不死循环。
+            if (!Number.isFinite(ppid) || ppid <= 0 || ppid === pid)
+                return undefined;
+            pid = ppid;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}