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

554 lines
20 KiB
TypeScript
Raw Permalink 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 } from "vitest";
import { createHash } from "node:crypto";
import {
planFlash,
dryRun,
verifyFlash,
runFlash,
parseOffset,
parseLsblk,
isRootDiskTarget,
targetExistsInRows,
deviceBasename,
ROOT_MOUNTPOINTS,
splitCommand,
finalizeFlashContent,
type FlashPlanEx,
} from "../src/extensions/flash.js";
import type { ExecFn } from "../src/shared/types.js";
// ---- mock helpers ----
/** 构造 ExecFn:按 command 路由到不同 mock 分支。 */
function mockExec(handlers: Record<string, (args: string[]) => { stdout: string; stderr: string; exitCode: number }>): ExecFn {
return async (command, args) => {
const h = handlers[command];
if (!h) return { stdout: "", stderr: `command not found: ${command}`, exitCode: 127 };
return h(args);
};
}
const LSBLK_ROOT_ON_SDA = `NAME SIZE TYPE MOUNTPOINT
sda 500000000000 disk
├─sda1 536870912 part /boot
└─sda2 499000000000 part /
mmcblk0 32000000000 disk
└─mmcblk0p1 32000000000 part`;
const LSBLK_MMCBLK0_NO_ROOT = `NAME SIZE TYPE MOUNTPOINT
mmcblk0 32000000000 disk
└─mmcblk0p1 32000000000 part
sda 500000000000 disk`;
// ============================================================================
// planFlash
// ============================================================================
describe("flash planFlash — 各 method 命令构建", () => {
it("dd: 生成 dd if=.. of=.. bs=4M conv=fsync", () => {
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
expect(plan.method).toBe("dd");
expect(plan.target).toBe("/dev/mmcblk0");
expect(plan.image).toBe("sdcard.img");
expect(plan.commands).toHaveLength(1);
expect(plan.commands[0]).toBe("dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync");
// 无 offset → 不带 seek=,offsetBytes 为 undefined
expect(plan.commands[0]).not.toContain("seek=");
});
it("dd + offset: 带 seek= 块数(字节 8388608 → 2 块)", () => {
const plan = planFlash("dd", "rootfs.img", "/dev/mmcblk0", { offset: "8388608" });
expect(plan.commands[0]).toContain("seek=2");
expect(plan.offsetBytes).toBe(8388608);
});
it("dd + hex offset 0x800000 → seek=2", () => {
const plan = planFlash("dd", "rootfs.img", "/dev/mmcblk0", { offset: "0x800000" });
expect(plan.offsetBytes).toBe(0x800000);
expect(plan.commands[0]).toContain("seek=2");
});
it("fastboot: 带分区名", () => {
const plan = planFlash("fastboot", "boot.img", "serial", { partition: "boot" });
expect(plan.commands[0]).toBe("fastboot flash boot boot.img");
});
it("dfu: target=vid:pid + alt", () => {
const plan = planFlash("dfu", "firmware.bin", "0483:df11", { partition: "0" });
expect(plan.commands[0]).toBe("dfu-util -d 0483:df11 -a 0 -D firmware.bin");
});
it("openocd: program + verify reset exit", () => {
const plan = planFlash("openocd", "firmware.elf", "openocd.cfg");
expect(plan.commands[0]).toBe('openocd -f openocd.cfg -c "program firmware.elf verify reset exit"');
});
it("非法 method 抛错", () => {
expect(() => planFlash("bogus" as never, "x", "/dev/sda")).toThrow(/unsupported method/);
});
it("空 image 抛错", () => {
expect(() => planFlash("dd", "", "/dev/mmcblk0")).toThrow(/image path required/);
});
it("空 target 抛错", () => {
expect(() => planFlash("dd", "img", "")).toThrow(/target required/);
});
it("非法 offset 抛错", () => {
expect(() => planFlash("dd", "img", "/dev/mmcblk0", { offset: "not-a-number" })).toThrow(/invalid offset/);
});
});
// ============================================================================
// parseOffset / parseLsblk / isRootDiskTarget
// ============================================================================
describe("flash parseOffset", () => {
it("十进制字符串", () => {
expect(parseOffset("8388608")).toBe(8388608);
});
it("0x hex", () => {
expect(parseOffset("0x800000")).toBe(0x800000);
});
it("空/undefined → 0", () => {
expect(parseOffset(undefined)).toBe(0);
expect(parseOffset("")).toBe(0);
});
it("非法 → null", () => {
expect(parseOffset("abc")).toBeNull();
});
});
describe("flash parseLsblk", () => {
it("解析多行含树形字符", () => {
const rows = parseLsblk(LSBLK_ROOT_ON_SDA);
expect(rows.length).toBeGreaterThanOrEqual(4);
const sda1 = rows.find((r) => r.name === "sda1");
expect(sda1).toBeDefined();
expect(sda1?.mountpoint).toBe("/boot");
const sda2 = rows.find((r) => r.name === "sda2");
expect(sda2?.mountpoint).toBe("/");
});
it("跳过表头", () => {
const rows = parseLsblk("NAME SIZE TYPE MOUNTPOINT\nsda 1000 disk");
expect(rows).toHaveLength(1);
expect(rows[0]?.name).toBe("sda");
});
});
describe("flash isRootDiskTarget", () => {
it("/dev/sda 是宿主系统盘(sda2 挂载 /)", () => {
expect(isRootDiskTarget("/dev/sda", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(true);
});
it("/dev/sda1 根分区(/boot)", () => {
expect(isRootDiskTarget("/dev/sda1", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(true);
});
it("/dev/mmcblk0 未挂载根 → false", () => {
expect(isRootDiskTarget("/dev/mmcblk0", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(false);
});
it("/dev/mmcblk0 在无根盘场景 → false", () => {
expect(isRootDiskTarget("/dev/mmcblk0", parseLsblk(LSBLK_MMCBLK0_NO_ROOT))).toBe(false);
});
it("不存在的设备 → false(但 targetExistsInRows 为 false)", () => {
expect(isRootDiskTarget("/dev/zzz", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(false);
});
});
describe("flash targetExistsInRows / deviceBasename / splitCommand", () => {
it("/dev/mmcblk0 存在", () => {
expect(targetExistsInRows("/dev/mmcblk0", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(true);
});
it("/dev/zzz 不存在", () => {
expect(targetExistsInRows("/dev/zzz", parseLsblk(LSBLK_ROOT_ON_SDA))).toBe(false);
});
it("deviceBasename 提取", () => {
expect(deviceBasename("/dev/sda1")).toBe("sda1");
expect(deviceBasename("/dev/mmcblk0p2")).toBe("mmcblk0p2");
});
it("ROOT_MOUNTPOINTS 含 /", () => {
expect(ROOT_MOUNTPOINTS.has("/")).toBe(true);
expect(ROOT_MOUNTPOINTS.has("/boot")).toBe(true);
});
it("splitCommand 保留引号内整体", () => {
const tokens = splitCommand('openocd -f openocd.cfg -c "program fw.elf verify reset exit"');
expect(tokens[0]).toBe("openocd");
expect(tokens[1]).toBe("-f");
expect(tokens[2]).toBe("openocd.cfg");
expect(tokens[3]).toBe("-c");
expect(tokens[4]).toBe("program fw.elf verify reset exit");
});
it("splitCommand 普通命令", () => {
const tokens = splitCommand("dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync");
expect(tokens[0]).toBe("dd");
expect(tokens).toHaveLength(5);
});
});
// ============================================================================
// dryRun
// ============================================================================
describe("flash dryRun — fail-closed 拒根盘", () => {
it("/dev/sda(宿主系统盘)被拒", async () => {
const plan = planFlash("dd", "sdcard.img", "/dev/sda");
const fn = mockExec({
lsblk: () => ({ stdout: LSBLK_ROOT_ON_SDA, stderr: "", exitCode: 0 }),
});
const r = await dryRun(plan, fn);
expect(r.ok).toBe(false);
expect(r.isRootDisk).toBe(true);
expect(r.targetExists).toBe(true);
expect(r.reason).toContain("/dev/sda");
expect(r.reason).toContain("mounted");
expect(r.reason).toContain("/");
});
it("/dev/sda1(根分区 /boot)被拒", async () => {
const plan = planFlash("dd", "sdcard.img", "/dev/sda1");
const fn = mockExec({
lsblk: () => ({ stdout: LSBLK_ROOT_ON_SDA, stderr: "", exitCode: 0 }),
});
const r = await dryRun(plan, fn);
expect(r.ok).toBe(false);
expect(r.isRootDisk).toBe(true);
expect(r.reason).toContain("/boot");
});
it("target 不存在被拒", async () => {
const plan = planFlash("dd", "sdcard.img", "/dev/zzz");
const fn = mockExec({
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
});
const r = await dryRun(plan, fn);
expect(r.ok).toBe(false);
expect(r.targetExists).toBe(false);
expect(r.reason).toContain("not found");
});
it("/dev/mmcblk0(合法 SD 卡)dry-run 通过 + 预计算 sha256", async () => {
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
const fn = mockExec({
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
sha256sum: () => ({ stdout: "deadbeefcafebabe0000000000000000000000000000000000000000000000ff sdcard.img\n", stderr: "", exitCode: 0 }),
dd: () => ({ stdout: "", stderr: "", exitCode: 0 }),
});
const r = await dryRun(plan, fn);
expect(r.ok).toBe(true);
expect(r.isRootDisk).toBe(false);
expect(plan.expectedSha256).toBe("deadbeefcafebabe0000000000000000000000000000000000000000000000ff");
expect(plan.imageSizeBytes).toBe(4294967296);
expect(plan.blockCount).toBe(1024); // 4GiB / 4MiB
});
it("offset 越过镜像大小被拒", async () => {
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0", { offset: "999999999999" });
const fn = mockExec({
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
sha256sum: () => ({ stdout: "abcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabca img\n", stderr: "", exitCode: 0 }),
dd: () => ({ stdout: "", stderr: "", exitCode: 0 }),
});
const r = await dryRun(plan, fn);
expect(r.ok).toBe(false);
expect(r.reason).toContain("offset");
});
it("lsblk 失败被拒", async () => {
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
const fn = mockExec({
lsblk: () => ({ stdout: "", stderr: "command not found", exitCode: 127 }),
});
const r = await dryRun(plan, fn);
expect(r.ok).toBe(false);
expect(r.reason).toContain("lsblk failed");
});
it("dry-run 不执行任何写操作(probeCommands 不含 of=/dev/mmcblk0 的写真写)", async () => {
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
const fn = mockExec({
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
sha256sum: () => ({ stdout: "a".repeat(64) + " img\n", stderr: "", exitCode: 0 }),
dd: () => ({ stdout: "", stderr: "", exitCode: 0 }),
});
const r = await dryRun(plan, fn);
expect(r.ok).toBe(true);
// 所有探测命令不应含 of=/dev/mmcblk0(写真写目标)
for (const c of r.probeCommands) {
expect(c).not.toContain("of=/dev/mmcblk0");
}
// 应含 of=/dev/null(只读探针)
expect(r.probeCommands.some((c) => c.includes("of=/dev/null"))).toBe(true);
});
it("fastboot dry-run 跑 getvar all", async () => {
const plan = planFlash("fastboot", "boot.img", "serial", { partition: "boot" });
const fn = mockExec({
fastboot: () => ({ stdout: "OKAY [ 0.001s]", stderr: "", exitCode: 0 }),
});
const r = await dryRun(plan, fn);
expect(r.ok).toBe(true);
expect(r.probeCommands[0]).toContain("getvar all");
});
it("openocd dry-run 跑 init+exit", async () => {
const plan = planFlash("openocd", "fw.elf", "openocd.cfg");
const fn = mockExec({
openocd: () => ({ stdout: "", stderr: "", exitCode: 0 }),
});
const r = await dryRun(plan, fn);
expect(r.ok).toBe(true);
expect(r.probeCommands[0]).toContain("init");
});
it("dfu dry-run 跑 dfu-util -l", async () => {
const plan = planFlash("dfu", "fw.bin", "0483:df11");
const fn = mockExec({
"dfu-util": () => ({ stdout: "Found DFU: 0483:df11", stderr: "", exitCode: 0 }),
});
const r = await dryRun(plan, fn);
expect(r.ok).toBe(true);
expect(r.probeCommands[0]).toContain("-l");
});
});
// ============================================================================
// verifyFlash
// ============================================================================
describe("flash verifyFlash — dd sha256 校验", () => {
it("sha 匹配 → ok", async () => {
// 读回 stdout "hello" → sha256
const readback = "hello";
const expected = createHash("sha256").update(readback).digest("hex");
const plan: FlashPlanEx = {
method: "dd",
commands: ["dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync"],
target: "/dev/mmcblk0",
image: "sdcard.img",
expectedSha256: expected,
blockCount: 1,
};
const fn = mockExec({
dd: () => ({ stdout: readback, stderr: "", exitCode: 0 }),
});
const r = await verifyFlash(plan, fn);
expect(r.ok).toBe(true);
expect(r.expected).toBe(expected);
expect(r.actual).toBe(expected);
});
it("sha 不匹配 → VERIFY FAILED", async () => {
const plan: FlashPlanEx = {
method: "dd",
commands: ["dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync"],
target: "/dev/mmcblk0",
image: "sdcard.img",
expectedSha256: "a".repeat(64),
blockCount: 2,
};
const fn = mockExec({
dd: () => ({ stdout: "different-bytes", stderr: "", exitCode: 0 }),
});
const r = await verifyFlash(plan, fn);
expect(r.ok).toBe(false);
expect(r.expected).toBe("a".repeat(64));
expect(r.actual).not.toBe("a".repeat(64));
expect(r.reason).toContain("VERIFY FAILED");
});
it("无 expectedSha256(未 dry-run)→ 拒绝", async () => {
const plan: FlashPlanEx = {
method: "dd",
commands: ["dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync"],
target: "/dev/mmcblk0",
image: "sdcard.img",
};
const fn = mockExec({ dd: () => ({ stdout: "", stderr: "", exitCode: 0 }) });
const r = await verifyFlash(plan, fn);
expect(r.ok).toBe(false);
expect(r.reason).toContain("expectedSha256");
});
it("读回 dd 失败 → fail", async () => {
const plan: FlashPlanEx = {
method: "dd",
commands: ["dd if=sdcard.img of=/dev/mmcblk0 bs=4M conv=fsync"],
target: "/dev/mmcblk0",
image: "sdcard.img",
expectedSha256: "a".repeat(64),
blockCount: 1,
};
const fn = mockExec({
dd: () => ({ stdout: "", stderr: "read error", exitCode: 1 }),
});
const r = await verifyFlash(plan, fn);
expect(r.ok).toBe(false);
expect(r.reason).toContain("readback dd failed");
});
it("openocd verify 走 verify_image exitCode", async () => {
const plan: FlashPlanEx = {
method: "openocd",
commands: ['openocd -f openocd.cfg -c "program fw.elf verify reset exit"'],
target: "openocd.cfg",
image: "fw.elf",
};
const fn = mockExec({
openocd: () => ({ stdout: "", stderr: "", exitCode: 0 }),
});
const r = await verifyFlash(plan, fn);
expect(r.ok).toBe(true);
expect(r.verifyCommand).toContain("verify_image");
});
});
// ============================================================================
// runFlash 三段式编排
// ============================================================================
describe("flash runFlash — 三段式编排", () => {
it("dry_run=true(skipWrite)只 dry-run 不写真写", async () => {
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
let ddCalled = false;
const fn = mockExec({
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
sha256sum: () => ({ stdout: "a".repeat(64) + " img\n", stderr: "", exitCode: 0 }),
dd: (args) => {
// dry-run 阶段 dd 是 of=/dev/null 探针;写真写不会触发
if (args.includes("of=/dev/null")) return { stdout: "", stderr: "", exitCode: 0 };
ddCalled = true; // 真写 dd(of=/dev/mmcblk0)
return { stdout: "", stderr: "", exitCode: 0 };
},
});
const r = await runFlash(plan, fn, { skipWrite: true });
expect(r.ok).toBe(true);
expect(r.written).toBe(false);
expect(ddCalled).toBe(false);
});
it("dry-run 失败时不写真写", async () => {
const plan = planFlash("dd", "sdcard.img", "/dev/sda");
const fn = mockExec({
lsblk: () => ({ stdout: LSBLK_ROOT_ON_SDA, stderr: "", exitCode: 0 }),
});
const r = await runFlash(plan, fn);
expect(r.ok).toBe(false);
expect(r.written).toBe(false);
expect(r.reason).toContain("mounted");
});
it("全流程:dry-run → 写 → verify 全过", async () => {
const readback = "image-bytes";
const expected = createHash("sha256").update(readback).digest("hex");
// 用一个自定义 plan 跳过 stat/sha256(已填 expectedSha256)—— 但 runFlash 会先 dryRun
// 重新算 sha256 覆盖 expectedSha256。故让 sha256sum mock 返回 expected。
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
const fn = mockExec({
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
sha256sum: () => ({ stdout: expected + " sdcard.img\n", stderr: "", exitCode: 0 }),
dd: (args) => {
// of=/dev/null → 读探针;of=/dev/mmcblk0 无 count → 真写;
// of=/dev/mmcblk0 + count → verify 读回
if (args.includes("of=/dev/null")) return { stdout: "", stderr: "", exitCode: 0 };
if (args.some((a) => a.startsWith("count="))) return { stdout: readback, stderr: "", exitCode: 0 };
return { stdout: "", stderr: "", exitCode: 0 }; // 真写
},
});
const r = await runFlash(plan, fn);
expect(r.ok).toBe(true);
expect(r.written).toBe(true);
expect(r.writeExitCodes).toEqual([0]);
expect(r.verify?.ok).toBe(true);
});
it("写真写命令失败 → ok:false", async () => {
const expected = createHash("sha256").update("x").digest("hex");
const plan = planFlash("dd", "sdcard.img", "/dev/mmcblk0");
const fn = mockExec({
lsblk: () => ({ stdout: LSBLK_MMCBLK0_NO_ROOT, stderr: "", exitCode: 0 }),
stat: () => ({ stdout: "4294967296\n", stderr: "", exitCode: 0 }),
sha256sum: () => ({ stdout: expected + " sdcard.img\n", stderr: "", exitCode: 0 }),
dd: (args) => {
if (args.includes("of=/dev/null")) return { stdout: "", stderr: "", exitCode: 0 };
if (args.some((a) => a.startsWith("count="))) return { stdout: "x", stderr: "", exitCode: 0 };
return { stdout: "", stderr: "write protected", exitCode: 1 }; // 真写失败
},
});
const r = await runFlash(plan, fn);
expect(r.ok).toBe(false);
expect(r.written).toBe(true);
expect(r.writeExitCodes).toEqual([1]);
expect(r.reason).toContain("write command failed");
});
});
// ============================================================================
// T04 finalizeFlashContent —— flash content-only 不变量
// ============================================================================
describe("T04 finalizeFlashContent —— content-only 归一", () => {
it("已是 text-block 数组 → 原样(details 保留)", () => {
const r = finalizeFlashContent({
content: [{ type: "text", text: "flash OK" }],
details: { stage: "full" },
});
expect(r.content).toEqual([{ type: "text", text: "flash OK" }]);
expect(r.details).toEqual({ stage: "full" });
expect(r.isError).toBeUndefined();
});
it("裸字符串 content → 包成 text-block", () => {
const r = finalizeFlashContent({ content: "raw string" });
expect(r.content).toEqual([{ type: "text", text: "raw string" }]);
});
it("字符串数组 content → 每项包成 text-block", () => {
const r = finalizeFlashContent({ content: ["a", "b"] });
expect(r.content).toEqual([
{ type: "text", text: "a" },
{ type: "text", text: "b" },
]);
});
it("单个 text-shaped 对象 → 包成单块", () => {
const r = finalizeFlashContent({ content: { type: "text", text: "x" } });
expect(r.content).toEqual([{ type: "text", text: "x" }]);
});
it("非 text-shaped content → 强制 stringify(content-only,绝不抛)", () => {
const r = finalizeFlashContent({ content: { weird: true } });
expect(r.content).toEqual([{ type: "text", text: JSON.stringify({ weird: true }) }]);
});
it("isError 透传", () => {
const r = finalizeFlashContent({ content: "fail", isError: true });
expect(r.isError).toBe(true);
});
// 不变式:所有输出 content 必是 Array<{type:"text",text:string}>
it("不变式:6 种输入归一后 content 恒为 text-block 数组", () => {
const inputs = [
{ content: "s" },
{ content: ["a"] },
{ content: [{ type: "text", text: "t" }] },
{ content: { type: "text", text: "o" } },
{ content: { x: 1 } },
{ content: 42 },
];
for (const inp of inputs) {
const r = finalizeFlashContent(inp);
expect(Array.isArray(r.content)).toBe(true);
for (const b of r.content) {
expect(b.type).toBe("text");
expect(typeof b.text).toBe("string");
}
}
});
});