physical_byte_agent/tests/board-link.test.ts
d-robotics d671f174fe feat(v3): P0 全落地 — T01-T05b 安全骨架 + 命门根治
P0 六项任务全部完成,1044 单测全绿,tsc 0 错。

- T01 真 createAgentSession boot 离线验证(e2e-runtime + e2e-smoke 71 测试)
- T02 safety-gate 正则与 hex 归一联动,堵 devmem 十进制砖板漏洞;devmem-via-bash 硬门
- T03 reg-tool.ts:datasheet 地址校验寄存器工具,prepareArguments 接 hex 归一;barrel 22 工厂
- T04 src/core/tool-pipeline.ts:五段流水线 + 单调 guard 不变量;safety-gate 委托 decide();flash finalizeFlashContent
- T05a sandbox-policy.ts:fail-closed unusable→exitCode126 不 spawn;board-link 包 argv
- T05b native/landlock-run/landlock-run.c:C11 raw-landlock self-restrict-then-exec + Makefile + README;probeViaBinary 接线

测试方法:等价类/边界值/决策表/状态转换/变异/对抗/元蜕变(TDD test-first)。
文档:架构设计文档_v3.md 进度表 + Docs/postmortem/0001-e2e-smoke.md。

Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-14 12:12:24 +08:00

610 lines
21 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

import { describe, it, expect, vi, beforeEach } from "vitest";
import {
BoardRegistry,
parseSshAddress,
buildSshArgs,
parseSerialAddress,
makeExec,
healthCheck,
computeFingerprint,
SERIAL_STUB_RESULT,
resetBoardSandboxProbe,
type RegistryEntry,
} from "../src/extensions/board-link.js";
import { DEFAULT_BOARD_SANDBOX_POLICY } from "../src/core/sandbox-policy.js";
import type { BoardSpec, ExecFn, ExecResult } from "../src/shared/types.js";
// ============================================================================
// mock 工厂
// ============================================================================
function makeMockExec(overrides?: Partial<ExecResult>): ExecFn & { mock: { calls: unknown[][] } } {
const fn = vi.fn(async (): Promise<ExecResult> => ({
stdout: overrides?.stdout ?? "",
stderr: overrides?.stderr ?? "",
exitCode: overrides?.exitCode ?? 0,
}));
return fn as unknown as ExecFn & { mock: { calls: unknown[][] } };
}
function sshBoard(id = "x5", address = "root@192.168.1.100:22"): BoardSpec {
return {
id,
name: `Board ${id}`,
link: "ssh",
address,
fingerprint: computeFingerprint("ssh", address),
};
}
// ============================================================================
// BoardRegistry — register / list / unregister
// ============================================================================
describe("board-link BoardRegistry — register/list/unregister", () => {
it("register 后 list 能查到", () => {
const reg = new BoardRegistry();
const board = sshBoard("x5", "root@192.168.1.100:22");
const r = reg.register(board);
expect(r.ok).toBe(true);
expect(reg.list()).toHaveLength(1);
expect(reg.get("x5")).toBe(board);
});
it("register 多块板 list 按插入序返回", () => {
const reg = new BoardRegistry();
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
reg.register(sshBoard("s100", "root@192.168.1.101:2222"));
reg.register({
id: "local",
name: "Local board",
link: "local",
address: "",
fingerprint: computeFingerprint("local", ""),
});
expect(reg.list()).toHaveLength(3);
expect(reg.size).toBe(3);
});
it("unregister 存在的板返回 true 并移除", () => {
const reg = new BoardRegistry();
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
expect(reg.unregister("x5")).toBe(true);
expect(reg.list()).toHaveLength(0);
expect(reg.get("x5")).toBeUndefined();
});
it("unregister 不存在的板返回 false", () => {
const reg = new BoardRegistry();
expect(reg.unregister("nonexistent")).toBe(false);
});
it("getByFingerprint 能按指纹反查", () => {
const reg = new BoardRegistry();
const board = sshBoard("x5", "root@192.168.1.100:22");
reg.register(board);
expect(reg.getByFingerprint(board.fingerprint)).toBe(board);
expect(reg.getByFingerprint("nonexistent")).toBeUndefined();
});
});
// ============================================================================
// BoardRegistry — fingerprint 去重
// ============================================================================
describe("board-link BoardRegistry — fingerprint 去重", () => {
it("重复 fingerprint 被拒绝(同一物理板不可重复注册)", () => {
const reg = new BoardRegistry();
const a = sshBoard("board-a", "root@192.168.1.100:22");
// 不同 id 但相同 address → 相同 fingerprint
const b = sshBoard("board-b", "root@192.168.1.100:22");
expect(reg.register(a).ok).toBe(true);
const r = reg.register(b);
expect(r.ok).toBe(false);
expect(r.error).toContain("fingerprint");
expect(r.conflictId).toBe("board-a");
expect(reg.size).toBe(1); // b 没进去
});
it("重复 id 被拒绝(即使 fingerprint 不同)", () => {
const reg = new BoardRegistry();
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
const r = reg.register(sshBoard("x5", "root@192.168.1.101:22"));
expect(r.ok).toBe(false);
expect(r.error).toContain("already registered");
expect(r.conflictId).toBe("x5");
});
it("不同 fingerprint + 不同 id 都能注册", () => {
const reg = new BoardRegistry();
expect(reg.register(sshBoard("x5", "root@192.168.1.100:22")).ok).toBe(true);
expect(reg.register(sshBoard("s100", "root@192.168.1.101:22")).ok).toBe(true);
expect(reg.size).toBe(2);
});
it("unregister 后 fingerprint 释放,可重新注册同 address", () => {
const reg = new BoardRegistry();
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
reg.unregister("x5");
// 同 address 现在可以注册了(fingerprint 已释放)
expect(reg.register(sshBoard("x5-reborn", "root@192.168.1.100:22")).ok).toBe(true);
});
});
// ============================================================================
// BoardRegistry — session 重建
// ============================================================================
describe("board-link BoardRegistry — fromEntries/toEntries session 重建", () => {
it("fromEntries 从 session entries 重建注册表", () => {
const entries: Array<{ customType?: string; data?: unknown }> = [
{ customType: "boardlink:registry", data: sshBoard("x5", "root@192.168.1.100:22") },
{ customType: "other:stuff", data: { foo: "bar" } },
{ customType: "boardlink:registry", data: sshBoard("s100", "root@192.168.1.101:2222") },
{ customType: "boardlink:registry", data: { broken: true } }, // 无效 spec,跳过
];
const reg = BoardRegistry.fromEntries(entries);
expect(reg.size).toBe(2);
expect(reg.get("x5")).toBeDefined();
expect(reg.get("s100")).toBeDefined();
});
it("toEntries 导出可持久化条目", () => {
const reg = new BoardRegistry();
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
const entries = reg.toEntries();
expect(entries).toHaveLength(1);
expect(entries[0]?.customType).toBe("boardlink:registry");
expect((entries[0] as RegistryEntry).data.id).toBe("x5");
});
it("toEntries → fromEntries 往返一致", () => {
const reg = new BoardRegistry();
reg.register(sshBoard("x5", "root@192.168.1.100:22"));
reg.register(sshBoard("s100", "root@192.168.1.101:2222"));
const rebuilt = BoardRegistry.fromEntries(reg.toEntries());
expect(rebuilt.size).toBe(2);
expect(rebuilt.get("x5")?.address).toBe("root@192.168.1.100:22");
expect(rebuilt.get("s100")?.address).toBe("root@192.168.1.101:2222");
});
});
// ============================================================================
// parseSshAddress
// ============================================================================
describe("board-link parseSshAddress", () => {
it("完整 user@host:port", () => {
const t = parseSshAddress("root@192.168.1.100:2222");
expect(t.user).toBe("root");
expect(t.host).toBe("192.168.1.100");
expect(t.port).toBe(2222);
});
it("无端口默认 22", () => {
const t = parseSshAddress("root@board");
expect(t.user).toBe("root");
expect(t.host).toBe("board");
expect(t.port).toBe(22);
});
it("无 user 默认 root", () => {
const t = parseSshAddress("192.168.1.100");
expect(t.user).toBe("root");
expect(t.host).toBe("192.168.1.100");
expect(t.port).toBe(22);
});
it("空字符串安全返回默认值", () => {
const t = parseSshAddress("");
expect(t.user).toBe("root");
expect(t.port).toBe(22);
});
});
// ============================================================================
// buildSshArgs — SSH 命令拼接
// ============================================================================
describe("board-link buildSshArgs — SSH 命令拼接", () => {
it("非默认端口加 -p", () => {
const board = sshBoard("x5", "root@192.168.1.100:2222");
const args = buildSshArgs(board, "ls", ["-la", "/tmp"]);
expect(args).toEqual(["-p", "2222", "root@192.168.1.100", "ls", "-la", "/tmp"]);
});
it("默认端口 22 不加 -p(减少参数噪声)", () => {
const board = sshBoard("x5", "root@192.168.1.100:22");
const args = buildSshArgs(board, "dmesg", ["|", "tail"]);
expect(args).toEqual(["root@192.168.1.100", "dmesg", "|", "tail"]);
expect(args).not.toContain("-p");
});
it("无参数命令也能拼接", () => {
const board = sshBoard("x5", "root@192.168.1.100:2222");
const args = buildSshArgs(board, "true", []);
expect(args).toEqual(["-p", "2222", "root@192.168.1.100", "true"]);
});
it("无 user 的地址默认 root@", () => {
const board = sshBoard("x5", "192.168.1.100:2222");
const args = buildSshArgs(board, "pwd", []);
expect(args[0]).toBe("-p");
expect(args[1]).toBe("2222");
expect(args[2]).toBe("root@192.168.1.100");
expect(args[3]).toBe("pwd");
});
});
// ============================================================================
// parseSerialAddress
// ============================================================================
describe("board-link parseSerialAddress", () => {
it("完整 /dev/ttyUSB0@115200", () => {
const t = parseSerialAddress("/dev/ttyUSB0@115200");
expect(t.dev).toBe("/dev/ttyUSB0");
expect(t.baudrate).toBe(115200);
});
it("无 baudrate 默认 115200", () => {
const t = parseSerialAddress("/dev/ttyUSB0");
expect(t.dev).toBe("/dev/ttyUSB0");
expect(t.baudrate).toBe(115200);
});
it("自定义 baudrate", () => {
const t = parseSerialAddress("/dev/ttyACM0@9600");
expect(t.dev).toBe("/dev/ttyACM0");
expect(t.baudrate).toBe(9600);
});
});
// ============================================================================
// makeExec — 按板类型产出 ExecFn
// ============================================================================
describe("board-link makeExec", () => {
beforeEach(() => {
// 沙箱 runner 可用 + 内核 5.13 → "full" capability(使 makeExec 正常包装并 spawn)
process.env.PBA_BOARD_SANDBOX_RUNNER = "1";
process.env.PBA_BOARD_KERNEL = "5.13.0";
resetBoardSandboxProbe();
});
it('ssh: calls underlying("ssh", sshArgs, opts)', async () => {
const mock = makeMockExec({ stdout: "/tmp\n", exitCode: 0 });
const board = sshBoard("x5", "root@192.168.1.100:2222");
const { exec, transport, isStub } = makeExec(board, mock);
const result = await exec("pwd", [], { timeout: 5000 });
expect(result.exitCode).toBe(0);
expect(result.stdout).toBe("/tmp\n");
expect(isStub).toBe(false);
expect(transport).toBe("ssh:root@192.168.1.100:2222");
// 验证 mock 被调时 command="ssh" 且 args 含沙箱包装 + ssh 拼接
const call = mock.mock.calls[0];
expect(call?.[0]).toBe("ssh");
const callArgs = call?.[1] as string[];
// 沙箱包装前缀 + 原始 ssh 拼接后缀
expect(callArgs).toEqual([
"pba-board-sandbox", "--ro", "/", "--rw", "/workspace", "--",
"-p", "2222", "root@192.168.1.100", "pwd",
]);
});
it("ssh: opts 透传到 underlying", async () => {
const mock = makeMockExec();
const board = sshBoard("x5", "root@board");
const { exec } = makeExec(board, mock);
const opts = { timeout: 30000, env: { FOO: "bar" } };
await exec("ls", ["-la"], opts);
const call = mock.mock.calls[0];
expect(call?.[2]).toBe(opts);
});
it("ssh: 默认端口 22 不加 -p", async () => {
const mock = makeMockExec();
const board = sshBoard("x5", "root@192.168.1.100:22");
const { exec } = makeExec(board, mock);
await exec("dmesg", []);
const callArgs = mock.mock.calls[0]?.[1] as string[];
expect(callArgs).not.toContain("-p");
// 沙箱包装 + 默认端口 ssh 拼接(无 -p)
expect(callArgs).toEqual([
"pba-board-sandbox", "--ro", "/", "--rw", "/workspace", "--",
"root@192.168.1.100", "dmesg",
]);
});
it("serial: 返回 stub,isStub=true,不调 underlying", async () => {
const mock = makeMockExec();
const board: BoardSpec = {
id: "serial-board",
name: "Serial Board",
link: "serial",
address: "/dev/ttyUSB0@115200",
fingerprint: computeFingerprint("serial", "/dev/ttyUSB0@115200"),
};
const { exec, transport, isStub } = makeExec(board, mock);
const result = await exec("ls", []);
expect(isStub).toBe(true);
expect(transport).toBe("serial:/dev/ttyUSB0@115200");
expect(result).toEqual(SERIAL_STUB_RESULT);
expect(mock.mock.calls).toHaveLength(0); // underlying 没被调
});
it("local: 沙箱包装后调 underlying(runner token 作为 command)", async () => {
const mock = makeMockExec({ stdout: "hello\n", exitCode: 0 });
const board: BoardSpec = {
id: "local",
name: "Local",
link: "local",
address: "",
fingerprint: computeFingerprint("local", ""),
};
const { exec, transport, isStub } = makeExec(board, mock);
const result = await exec("echo", ["hello"]);
expect(result.stdout).toBe("hello\n");
expect(isStub).toBe(false);
expect(transport).toBe("local");
// local 沙箱包装:runner token 作为 command,策略根 + "--" + 原始命令作为 args
const call = mock.mock.calls[0];
expect(call?.[0]).toBe("pba-board-sandbox");
expect(call?.[1]).toEqual(["--ro", "/", "--rw", "/workspace", "--", "echo", "hello"]);
});
});
// ============================================================================
// healthCheck
// ============================================================================
describe("board-link healthCheck", () => {
beforeEach(() => {
// 沙箱 runner 可用 + 内核 5.13 → "full"(使 healthCheck 能 spawn 探活命令)
process.env.PBA_BOARD_SANDBOX_RUNNER = "1";
process.env.PBA_BOARD_KERNEL = "5.13.0";
resetBoardSandboxProbe();
});
it("exit 0 → alive (true)", async () => {
const mock = makeMockExec({ exitCode: 0 });
// local board: exec 沙箱包装后调 underlying,mock 能看到 runner token + 探活命令
const board: BoardSpec = {
id: "local",
name: "Local",
link: "local",
address: "",
fingerprint: computeFingerprint("local", ""),
};
const { exec } = makeExec(board, mock);
const alive = await healthCheck(board, exec);
expect(alive).toBe(true);
// 探活命令 "true" 经沙箱包装后出现在 args 中
const callArgs = mock.mock.calls[0]?.[1] as string[];
expect(callArgs).toContain("true");
});
it("非 0 exit → dead (false)", async () => {
const mock = makeMockExec({ exitCode: 1 });
const board: BoardSpec = {
id: "local",
name: "Local",
link: "local",
address: "",
fingerprint: computeFingerprint("local", ""),
};
const { exec } = makeExec(board, mock);
const alive = await healthCheck(board, exec);
expect(alive).toBe(false);
});
it("exec 抛异常 → dead (false)(fail-closed)", async () => {
const throwingExec: ExecFn = vi.fn(async () => {
throw new Error("connection refused");
}) as unknown as ExecFn;
const board = sshBoard("x5", "root@192.168.1.100:22");
const alive = await healthCheck(board, throwingExec);
expect(alive).toBe(false);
});
it("自定义探活命令", async () => {
const mock = makeMockExec({ exitCode: 0 });
const board: BoardSpec = {
id: "local",
name: "Local",
link: "local",
address: "",
fingerprint: computeFingerprint("local", ""),
};
const { exec } = makeExec(board, mock);
const alive = await healthCheck(board, exec, { probeCommand: "echo ok" });
expect(alive).toBe(true);
// 自定义探活命令经沙箱包装后出现在 args 中
const callArgs = mock.mock.calls[0]?.[1] as string[];
expect(callArgs).toContain("echo ok");
});
it("timeout 透传到 exec opts", async () => {
const mock = makeMockExec({ exitCode: 0 });
const board: BoardSpec = {
id: "local",
name: "Local",
link: "local",
address: "",
fingerprint: computeFingerprint("local", ""),
};
const { exec } = makeExec(board, mock);
await healthCheck(board, exec, { timeout: 5000 });
const callOpts = mock.mock.calls[0]?.[2] as { timeout?: number };
expect(callOpts?.timeout).toBe(5000);
});
it("ssh board: 探活命令经 ssh 包装(mock 收到 ssh + args 含 true)", async () => {
const mock = makeMockExec({ exitCode: 0 });
const board = sshBoard("x5", "root@192.168.1.100:2222");
const { exec } = makeExec(board, mock);
const alive = await healthCheck(board, exec);
expect(alive).toBe(true);
// ssh 包装:underlying 收到 "ssh" + 拼接的 args(含沙箱前缀 + true)
expect(mock.mock.calls[0]?.[0]).toBe("ssh");
const sshArgs = mock.mock.calls[0]?.[1] as string[];
expect(sshArgs).toContain("true");
expect(sshArgs).toContain("root@192.168.1.100");
});
});
// ============================================================================
// computeFingerprint
// ============================================================================
describe("board-link computeFingerprint", () => {
it("同 link+address → 同 fingerprint", () => {
const a = computeFingerprint("ssh", "root@192.168.1.100:22");
const b = computeFingerprint("ssh", "root@192.168.1.100:22");
expect(a).toBe(b);
});
it("不同 address → 不同 fingerprint", () => {
const a = computeFingerprint("ssh", "root@192.168.1.100:22");
const b = computeFingerprint("ssh", "root@192.168.1.101:22");
expect(a).not.toBe(b);
});
it("不同 link → 不同 fingerprint(即使 address 相同)", () => {
const a = computeFingerprint("ssh", "board");
const b = computeFingerprint("serial", "board");
expect(a).not.toBe(b);
});
it("address 首尾空白被 trim", () => {
const a = computeFingerprint("ssh", " root@board ");
const b = computeFingerprint("ssh", "root@board");
expect(a).toBe(b);
});
});
// ============================================================================
// board-side 沙箱 fail-closed (T05)
// ============================================================================
describe("board-side 沙箱 fail-closed (T05)", () => {
beforeEach(() => {
// 默认:沙箱 runner 未设 → unusable(fail-closed)
delete process.env.PBA_BOARD_SANDBOX_RUNNER;
delete process.env.PBA_BOARD_KERNEL;
resetBoardSandboxProbe();
});
it("ssh: runner 不可用 → exec 返回 exitCode 126 + 拒绝 stderr,不 spawn underlying", async () => {
const mock = makeMockExec({ stdout: "should-not-see", exitCode: 0 });
const board = sshBoard("x5", "root@192.168.1.100:22");
const { exec } = makeExec(board, mock);
const result = await exec("ls", ["/tmp"]);
expect(result.exitCode).toBe(126);
expect(result.stdout).toBe("");
expect(result.stderr).toContain("[board-sandbox]");
expect(result.stderr).toContain("fail-closed");
// 关键证明:underlying 从未被调用
expect(mock.mock.calls).toHaveLength(0);
});
it("ssh: runner 可用 + 内核 5.13 → exec 跑通,argv 含沙箱包装", async () => {
process.env.PBA_BOARD_SANDBOX_RUNNER = "1";
process.env.PBA_BOARD_KERNEL = "5.13.0";
resetBoardSandboxProbe();
const mock = makeMockExec({ stdout: "ok\n", exitCode: 0 });
const board = sshBoard("x5", "root@192.168.1.100:22");
const { exec } = makeExec(board, mock);
const result = await exec("ls", ["/tmp"]);
expect(result.exitCode).toBe(0);
expect(result.stdout).toBe("ok\n");
// underlying 被调用,且 argv 含沙箱 runner token
expect(mock.mock.calls).toHaveLength(1);
const callArgs = mock.mock.calls[0]?.[1] as string[];
expect(callArgs).toContain("pba-board-sandbox");
expect(callArgs).toContain("--ro");
expect(callArgs).toContain("--rw");
expect(callArgs).toContain("--");
});
it("local: runner 不可用 → exec 返回 exitCode 126 + 拒绝 stderr,不 spawn underlying", async () => {
const mock = makeMockExec({ stdout: "should-not-see", exitCode: 0 });
const board: BoardSpec = {
id: "local",
name: "Local",
link: "local",
address: "",
fingerprint: computeFingerprint("local", ""),
};
const { exec } = makeExec(board, mock);
const result = await exec("ls", ["/tmp"]);
expect(result.exitCode).toBe(126);
expect(result.stderr).toContain("[board-sandbox]");
expect(mock.mock.calls).toHaveLength(0);
});
it("local: runner 可用 + 内核 5.13 → exec 跑通,argv 含沙箱包装", async () => {
process.env.PBA_BOARD_SANDBOX_RUNNER = "1";
process.env.PBA_BOARD_KERNEL = "5.13.0";
resetBoardSandboxProbe();
const mock = makeMockExec({ stdout: "ok\n", exitCode: 0 });
const board: BoardSpec = {
id: "local",
name: "Local",
link: "local",
address: "",
fingerprint: computeFingerprint("local", ""),
};
const { exec } = makeExec(board, mock);
const result = await exec("echo", ["hi"]);
expect(result.exitCode).toBe(0);
expect(mock.mock.calls).toHaveLength(1);
expect(mock.mock.calls[0]?.[0]).toBe("pba-board-sandbox");
const callArgs = mock.mock.calls[0]?.[1] as string[];
expect(callArgs).toContain("echo");
expect(callArgs).toContain("hi");
});
it("serial: runner 不可用 → stub 也被拒绝(exitCode 126)", async () => {
const mock = makeMockExec();
const board: BoardSpec = {
id: "serial-board",
name: "Serial Board",
link: "serial",
address: "/dev/ttyUSB0@115200",
fingerprint: computeFingerprint("serial", "/dev/ttyUSB0@115200"),
};
const { exec } = makeExec(board, mock);
const result = await exec("ls", []);
expect(result.exitCode).toBe(126);
expect(result.stderr).toContain("[board-sandbox]");
// serial stub 也不调 underlying
expect(mock.mock.calls).toHaveLength(0);
});
it("DEFAULT_BOARD_SANDBOX_POLICY 是 board-link 消费的单一共享 home", () => {
// board-link 通过值导入引用 sandbox-policy 的 DEFAULT_BOARD_SANDBOX_POLICY
// flash 接线由另一 agent 拥有(TODO,见架构文档 §5.4)—— 此处只验证 board-link 侧
expect(DEFAULT_BOARD_SANDBOX_POLICY.readOnlyRoots).toEqual(["/"]);
expect(DEFAULT_BOARD_SANDBOX_POLICY.readWriteRoots).toEqual(["/workspace"]);
});
});