@oj-module/cli 0.2.8 → 0.2.15

package/src/market/__tests__/report.test.ts

@@ -0,0 +1,51 @@
+// market/report spec（T12 收尾）：报告白黑名单——白名单内容落盘，黑名单字段写盘前被掩码。
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { FAILURE_PLAYBOOK } from "../failure-playbook";
+import { sanitizeReportText, writeWalkthroughReport } from "../report";
+
+describe("given 含黑名单字段的文本 When 过脱敏", () => {
+	it("then Bearer token / JWT / PEM / jwt_secret 全部被掩码，白名单内容（指纹/sha256/key_id）原样保留", () => {
+		const text = [
+			"authorization: Bearer abc.def-123~",
+			"jwt: eyJhbGciOiJ.eyJzdWI.SflKxw",
+			"-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMG\n-----END PRIVATE KEY-----",
+			"jwt_secret: hunter2",
+			"fingerprint 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 / key_id demo.publisher / sha256 abc123",
+		].join("\n");
+		const out = sanitizeReportText(text);
+		expect(out).not.toContain("abc.def-123");
+		expect(out).not.toContain("eyJhbGciOiJ");
+		expect(out).not.toContain("MIGHAgEAMBMG");
+		expect(out).not.toContain("hunter2");
+		expect(out).toContain("Bearer ***");
+		expect(out).toContain("9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"); // 白名单原样
+		expect(out).toContain("demo.publisher");
+		// 幂等：二次过检不再变化
+		expect(sanitizeReportText(out)).toBe(out);
+	});
+});
+
+describe("given 一次 walkthrough 的行 When 落盘报告", () => {
+	it("then 写出 AC 表 + 文案表，且 detail 里的 token 被掩码", () => {
+		const dir = mkdtempSync(join(tmpdir(), "ojm-report-"));
+		const file = writeWalkthroughReport({
+			rows: [
+				{ key: "install", title: "安装（11 段）", ok: true, detail: "" },
+				{ key: "neg-x", title: "负向示例", ok: false, detail: "泄漏 Authorization: Bearer leAk.ed-tok~en" },
+			],
+			port: 49999,
+			playbook: FAILURE_PLAYBOOK,
+			logDir: dir,
+		});
+		const text = readFileSync(file, "utf-8");
+		expect(file).toContain(join(dir, "walkthrough-"));
+		expect(text).toContain("| install | PASS | 安装（11 段） |");
+		expect(text).toContain("| neg-x | FAIL |");
+		expect(text).toContain("sig_missing"); // 文案表段在场
+		expect(text).not.toContain("leAk.ed-tok"); // 黑名单兜底生效
+	});
+});

package/src/market/__tests__/setup.test.ts

@@ -0,0 +1,114 @@
+// ojm market setup spec（T5）：首跑打开市场地址。
+//
+// 两条必守：① 写出的地址必须是 config 推导的**绝对 URL**（dev 形态下相对路径会拿到 index.html，
+// 见设计 §3.1.1）；② seed admin 处于 must_change 悬挂期时，登录拿的是限权 token，
+// 必须先改密拿全权 token 才写得了 system 设置——这条不闭环，首跑就直接卡死。
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { setupMarketUrl } from "../setup";
+
+const MOUNTS = "  - prefix: /api\n    api: src\n  - prefix: /cdn\n    web: ../cdn\n";
+const CONFIG = `mounts:\n${MOUNTS}server:\n  host: 127.0.0.1\n  port: 9778\n`;
+const MARKET_KEY = "framework.market_cdn_url";
+
+interface Call {
+	url: string
+	method: string
+	body?: Record<string, unknown>
+	auth?: string
+}
+
+/** 假站点：可编排 login 是否受限、settings 是否拒绝 */
+function fakeSite(opts: { restricted?: boolean, rejectSettings?: boolean, rejectLogin?: boolean } = {}) {
+	const calls: Call[] = [];
+	const fetchFn = (async (url: string, init?: { method?: string, body?: string, headers?: Record<string, string> }): Promise<Response> => {
+		const method = init?.method ?? "GET";
+		const body = init?.body === undefined ? undefined : JSON.parse(init.body) as Record<string, unknown>;
+		calls.push({ url, method, body, auth: init?.headers?.authorization });
+		if (url.endsWith("/api/auth/login")) {
+			if (opts.rejectLogin === true)
+				return json({ code: 401, msg: "用户名或密码错误", data: null });
+			return json({ code: 0, msg: "ok", data: { access_token: "token-limited", restricted: opts.restricted === true } });
+		}
+		if (url.endsWith("/api/auth/password"))
+			return json({ code: 0, msg: "ok", data: { access_token: "token-full", refresh_token: "r", expires_in: 3600 } });
+		if (url.endsWith("/api/system/settings")) {
+			if (opts.rejectSettings === true)
+				return json({ code: 403, msg: "must_change", data: null });
+			return json({ code: 0, msg: "ok", data: true });
+		}
+		throw new Error(`未预期的请求：${method} ${url}`);
+	}) as unknown as typeof fetch;
+	return { calls, fetchFn };
+}
+
+function json(payload: unknown): Response {
+	return { ok: true, status: 200, text: async () => JSON.stringify(payload) } as unknown as Response;
+}
+
+function newProject(): string {
+	const root = mkdtempSync(join(tmpdir(), "ojm-market-setup-"));
+	mkdirSync(join(root, "api"), { recursive: true });
+	writeFileSync(join(root, "api", "config.yaml"), CONFIG, "utf-8");
+	mkdirSync(join(root, "cdn"), { recursive: true });
+	return root;
+}
+
+describe("given 站点可直连且凭据未悬挂 When setup", () => {
+	it("then 直接写入 config 推导的绝对市场地址", async () => {
+		const root = newProject();
+		const site = fakeSite();
+
+		const result = await setupMarketUrl({ projectRoot: root, user: "admin", pass: "123456", url: "http://127.0.0.1:9778", fetchFn: site.fetchFn });
+
+		expect(result.cdnBaseUrl).toBe("http://127.0.0.1:9778/cdn");
+		const put = site.calls.find(c => c.url.endsWith("/api/system/settings"))!;
+		expect(put.method).toBe("PUT");
+		expect(put.body).toEqual({ key: MARKET_KEY, value: "http://127.0.0.1:9778/cdn" });
+		expect(result.changedPassword).toBe(false);
+	});
+});
+
+describe("given seed admin 处于 must_change 悬挂期 When setup", () => {
+	it("then 先改密换全权 token，再写设置（且后续请求用新 token）", async () => {
+		const root = newProject();
+		const site = fakeSite({ restricted: true });
+
+		const result = await setupMarketUrl({ projectRoot: root, user: "admin", pass: "123456", newPass: "newpass-123", url: "http://127.0.0.1:9778", fetchFn: site.fetchFn });
+
+		expect(result.changedPassword).toBe(true);
+		const pwd = site.calls.find(c => c.url.endsWith("/api/auth/password"))!;
+		expect(pwd.method).toBe("PUT");
+		expect(pwd.body).toEqual({ old_password: "123456", new_password: "newpass-123" });
+		const put = site.calls.find(c => c.url.endsWith("/api/system/settings"))!;
+		expect(put.auth).toBe("Bearer token-full");
+	});
+});
+
+describe("given 站点不可达 When setup", () => {
+	it("then 抛人话错误提示先起站点，不写任何东西", async () => {
+		const root = newProject();
+		const failing = async (): Promise<Response> => {
+			throw new Error("ECONNREFUSED");
+		};
+		const fetchFn = failing as unknown as typeof fetch;
+
+		await expect(setupMarketUrl({ projectRoot: root, user: "admin", pass: "123456", url: "http://127.0.0.1:9778", fetchFn }))
+			.rejects
+			.toThrow(/ojm dev/);
+	});
+});
+
+describe("given 改密后写设置仍被拒 When setup", () => {
+	it("then 抛人话错误而不是静默成功", async () => {
+		const root = newProject();
+		const site = fakeSite({ restricted: true, rejectSettings: true });
+
+		await expect(setupMarketUrl({ projectRoot: root, user: "admin", pass: "123456", newPass: "newpass-123", url: "http://127.0.0.1:9778", fetchFn: site.fetchFn }))
+			.rejects
+			.toThrow(/must_change|权限|设置/);
+	});
+});

package/src/market/__tests__/verify.test.ts

@@ -0,0 +1,111 @@
+// ojm market verify spec（T7）：离线验包——不起站点、不装、不要凭据。
+//
+// 钉死两条：① 四类校验分列（完整性 / 包级签 / 索引签 / 结构），篡改任一项都必须在对应项上打叉；
+// ② 结论恒带边界声明——验签过 ≠ 代码无恶意，这一点写错比校验写错更危险。
+import { Buffer } from "node:buffer";
+import { generateKeyPairSync } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { buildIndex } from "../build-index";
+import { publishPackage } from "../publish";
+import { verifyMarket } from "../verify";
+
+const MOUNTS = "  - prefix: /api\n    api: src\n  - prefix: /cdn\n    web: ../cdn\n";
+const CONFIG = `mounts:\n${MOUNTS}server:\n  host: 127.0.0.1\n  port: 9778\n`;
+const KEY_ID = "demo.publisher";
+
+function testPem(): string {
+	return generateKeyPairSync("ed25519").privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+}
+
+function newProject(): string {
+	const root = mkdtempSync(join(tmpdir(), "ojm-market-verify-"));
+	mkdirSync(join(root, "api"), { recursive: true });
+	writeFileSync(join(root, "api", "config.yaml"), CONFIG, "utf-8");
+	mkdirSync(join(root, "cdn"), { recursive: true });
+	return root;
+}
+
+/** 落一个包并重建索引，返回工程根 */
+async function seed(): Promise<string> {
+	const root = newProject();
+	await publishPackage({ projectRoot: root, fixture: "demo-solution@0.1.0", id: KEY_ID, privateKeyPem: testPem() });
+	await buildIndex({ projectRoot: root, id: KEY_ID, privateKeyPem: testPem() });
+	return root;
+}
+
+function itemOf(result: Awaited<ReturnType<typeof verifyMarket>>, name: string): { ok: boolean, detail: string } | undefined {
+	return result.checks.find(c => c.item === name);
+}
+
+describe("given 一个正常落地的包 When 离线验包", () => {
+	it("then 四类校验全绿且结论带边界声明", async () => {
+		const root = await seed();
+
+		const result = await verifyMarket({ projectRoot: root });
+
+		expect(result.passed).toBe(true);
+		expect(itemOf(result, "完整性")?.ok).toBe(true);
+		expect(itemOf(result, "包级签名")?.ok).toBe(true);
+		expect(itemOf(result, "索引签名")?.ok).toBe(true);
+		expect(itemOf(result, "manifest 结构")?.ok).toBe(true);
+		expect(result.conclusion).toContain("不构成内容安全性背书");
+	});
+});
+
+describe("given 包体被改了一个字节 When 离线验包", () => {
+	it("then 完整性与包级签名双双打叉（sha256 不符 + 验签不过）", async () => {
+		const root = await seed();
+		const tgz = join(root, "cdn", "demo-solution-0.1.0.tgz");
+		const bytes = Buffer.from(readFileSync(tgz));
+		bytes[bytes.length - 1] = bytes[bytes.length - 1]! ^ 0xFF;
+		writeFileSync(tgz, bytes);
+
+		const result = await verifyMarket({ projectRoot: root });
+
+		expect(result.passed).toBe(false);
+		expect(itemOf(result, "完整性")?.ok).toBe(false);
+		expect(itemOf(result, "包级签名")?.ok).toBe(false);
+	});
+});
+
+describe("given 包级签名被删掉 When 离线验包", () => {
+	it("then 包级签名打叉并给出 sig_missing 口径的指引", async () => {
+		const root = await seed();
+		rmSync(join(root, "cdn", "demo-solution-0.1.0.tgz.sig"));
+
+		const result = await verifyMarket({ projectRoot: root });
+
+		expect(itemOf(result, "包级签名")?.ok).toBe(false);
+		expect(itemOf(result, "包级签名")?.detail).toMatch(/sig|签名/);
+	});
+});
+
+describe("given 索引被手改过 When 离线验包", () => {
+	it("then 索引签名打叉（索引签名是完整性层，篡改必须可见）", async () => {
+		const root = await seed();
+		const bundles = join(root, "cdn", "bundles.yaml");
+		writeFileSync(bundles, `${readFileSync(bundles, "utf-8")}\n# tampered\n`);
+
+		const result = await verifyMarket({ projectRoot: root });
+
+		expect(itemOf(result, "索引签名")?.ok).toBe(false);
+	});
+});
+
+describe("given 落了 tgz 但没重建索引 When 带 --rebuild-check 验包", () => {
+	it("then 报漂移：索引缺该包条目", async () => {
+		const root = newProject();
+		await publishPackage({ projectRoot: root, fixture: "demo-solution@0.1.0", id: KEY_ID, privateKeyPem: testPem() });
+		await buildIndex({ projectRoot: root, id: KEY_ID, privateKeyPem: testPem() });
+		await publishPackage({ projectRoot: root, fixture: "other-solution@0.1.0", id: KEY_ID, privateKeyPem: testPem() });
+
+		const result = await verifyMarket({ projectRoot: root, rebuildCheck: true });
+
+		expect(result.drift?.length ?? 0).toBeGreaterThan(0);
+		expect(result.drift?.join(" ")).toMatch(/other-solution/);
+	});
+});

package/src/market/bootstrap.ts

@@ -0,0 +1,255 @@
+/**
+ * 隔离站点自举（T8）：`ojm market trial` / `walkthrough` 的地基。
+ *
+ * 目标：给你一个「别人家的站点」来试装——不碰你的工程、DB、信任库、端口。
+ * 隔离六项各有落点：
+ * - **端口**：临时根 config 写入空闲端口（startOj 从 config 读端口，故派生 config 是唯一真相）；
+ * - **DB**：oj 的 sqlite 按 config 所在目录解析，临时根内自然隔离（dbPath 暴露供断言）；
+ * - **密钥**：发布方 Ed25519 由公开 seed 经 SHA-256 派生（照 fixtures/sig 夹具手法），
+ *   私钥只在内存，临时根内无 PEM（站点自己的开发证书走 mintDevCert，属站点身份）；
+ * - **凭据**：隔离库是全新 seed，admin 口令即种子默认值，与真站点凭据零交集；
+ * - **信任库**：`.solutions/trusted-keys.yaml` 只在安装器写入时生成，全新根内不存在；
+ * - **CDN 目录**：临时根内 cdn/，由本模块自建（publish + build-index 直落）。
+ *
+ * 提库来源：`scripts/verify-solution-smoke/bootstrap-host.mjs`（同手法，脚本形态）；
+ * 本文件是它的 cli 内嵌版（计划 §9.1：phase1 从这里提库而非重写）。
+ */
+
+import type { OjProcess } from "../oj";
+import { Buffer } from "node:buffer";
+import { createHash, createPrivateKey, randomBytes } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { buildBackend } from "../build";
+import { exportRawPublicKeyHex, fingerprintOfPublicKey } from "../lifecycle/sign";
+import { startOj } from "../oj";
+import { mintDevCert } from "../oj-cert";
+import { resolveOjBin } from "../vendor";
+import { buildIndex } from "./build-index";
+import { parseFixtureSpec } from "./fixture";
+import { publishPackage } from "./publish";
+
+/** 种子管理员（隔离库全新 seed；与 templates seed.sql 一致） */
+const SEED_ADMIN_USER = "admin";
+const SEED_ADMIN_PASS = "123456";
+
+/** Ed25519 PKCS#8 DER 前缀（RFC 8410 固定头；与 gen-signed-fixtures.mjs 同一手法） */
+const ED25519_PKCS8_PREFIX = "302e020100300506032b657004220420";
+
+export interface IsolatedPublisher {
+	keyId: string
+	privateKeyPem: string
+	publicKeyHex: string
+	fingerprint: string
+}
+
+export interface IsolatedSite {
+	/** 临时根（含 api/ bin/ cdn/） */
+	root: string
+	port: number
+	baseUrl: string
+	apiBase: string
+	cdnDir: string
+	cdnBaseUrl: string
+	/** sqlite 库路径（config 目录相对解析；断言隔离用） */
+	dbPath: string
+	/** 一次性发布方身份（私钥只在内存） */
+	publisher: IsolatedPublisher
+	/** 隔离库的种子管理员 */
+	admin: { user: string, pass: string }
+	/** 销毁隔离根与 oj 进程；幂等 */
+	cleanup: () => Promise<void>
+	/** 销毁清单（--keep 时给人看这里到底有什么） */
+	teardownReport: () => string[]
+}
+
+export interface BootstrapOptions {
+	/** 源工程（提供 bin/oj 与 cli 内置模板）；缺省 process.cwd() */
+	projectRoot?: string
+	/** 落进隔离 CDN 的 fixture；缺省 demo-solution@0.1.0 */
+	fixture?: string
+	/** 保留现场（cleanup 不删根，只打清单） */
+	keep?: boolean
+	/** 测试注入；缺省真 startOj */
+	starter?: (configPath: string, base: string, apiSrc: string) => OjProcess
+	/** 日志旁路（测试收集用） */
+	onLog?: (line: string) => void
+}
+
+export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promise<IsolatedSite> {
+	const projectRoot = opts.projectRoot ?? process.cwd();
+	const log = (line: string) => (opts.onLog ?? ((l: string) => console.log(l)))(line);
+
+	const ojBin = resolveOjBin(projectRoot);
+	if (!existsSync(ojBin)) {
+		throw new Error(
+			`[ojm] 源工程未安装 oj 二进制：${ojBin}\n`
+			+ "下一步：在源工程目录跑一次 `ojm vendor`（经 npm 包 @oj-bin/oj 下载），再重试。",
+		);
+	}
+
+	const root = mkdtempSync(path.join(tmpdir(), "ojm-trial-"));
+	const apiDir = path.join(root, "api");
+	const configPath = path.join(apiDir, "config.yaml");
+	const cdnDir = path.join(root, "cdn");
+	const dbPath = path.join(apiDir, "db.sqlite");
+
+	// 1) api 树 + config（模板由 cli 包内置，init 同源；与 cli→templates 依赖红线不冲突——那是运行期文件而非 import）
+	const cliRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+	const templateApi = path.join(cliRoot, "templates", "api");
+	if (!existsSync(path.join(templateApi, "config.yaml"))) {
+		throw new Error(`[ojm] cli 内置模板缺失：${templateApi}（@oj-module/cli 安装不完整？）`);
+	}
+	cpSync(path.join(templateApi, "src"), path.join(apiDir, "src"), { recursive: true });
+	writeFileSync(configPath, readFileSync(path.join(templateApi, "config.yaml"), "utf-8"), "utf-8");
+
+	// 2) oj 二进制与插件（startOj 按 <root>/bin/oj 解析；plugins 让 auth 插件可用）
+	mkdirSync(path.join(root, "bin"), { recursive: true });
+	cpSync(ojBin, path.join(root, "bin", "oj"), { recursive: true });
+	const versionMarker = path.join(projectRoot, "bin", ".oj-version");
+	if (existsSync(versionMarker)) {
+		cpSync(versionMarker, path.join(root, "bin", ".oj-version"));
+	}
+	const pluginsDir = path.join(projectRoot, "bin", "plugins");
+	if (existsSync(pluginsDir)) {
+		cpSync(pluginsDir, path.join(root, "bin", "plugins"), { recursive: true });
+	}
+
+	// 3) 派生 config：空闲端口 / 随机 jwt / CDN 挂载指绝对路径 / fs 段
+	const port = await freePort();
+	let cfg = readFileSync(configPath, "utf-8");
+	cfg = cfg.replace("port: 9778", `port: ${port}`);
+	if (!cfg.includes(`port: ${port}`)) {
+		throw new Error(`[ojm] 模板 config 未含 端口: 9778 字面（模板结构变了？）：${configPath}`);
+	}
+	cfg = cfg.replace("__JWT_SECRET__", randomBytes(32).toString("hex"));
+	// 最小 SPA 挂载：真实部署里前端路由（深检会逐条探活）由站点壳承接；没有 web 挂载时
+	// 这些路径一律 404，深检会判成 anomaly。这里放一个 index.html 就够（不构建前端）。
+	// 挂在 /cdn 之后（前缀特异性匹配，顺序无关，仅为可读）。
+	const siteDir = path.join(root, "site");
+	mkdirSync(siteDir, { recursive: true });
+	writeFileSync(path.join(siteDir, "index.html"), "<!doctype html><html><body>ojm trial site</body></html>\n", "utf-8");
+	cfg = cfg.replace("web: ../cdn", `web: ${cdnDir}\n  - prefix: /\n    web: ${siteDir}\n    spa: true`);
+	// 安装目标恒为 release 部署：装好的模块落在 api/dist，dev 形态（--api-path src）发现不了。
+	// 故隔离站点以 dist 起站，platform.root 同步改写（oj 校验 root 必须是生效的 api 挂载目录）。
+	cfg = cfg.replace("  root: src", "  root: dist");
+	// auth 守卫在装配期读 anonymous_paths，安装器注册的新匿名端点要重启才生效（首次安装 smoke 会 401）。
+	// 隔离站点直接预置被测方案的探活路径——与 scripts/verify-solution-smoke/bootstrap-host.mjs 同手法，
+	// 让 trial 验的是安装机制本身，而不是重启时序。
+	const healthPath = `/${parseFixtureSpec(opts.fixture).name}/ping`;
+	if (!cfg.includes(`- ${healthPath}`))
+		cfg = cfg.replace(/^(\s*)- \/system\/login-methods$/m, `$1- /system/login-methods\n$1- ${healthPath}`);
+	// fs 段：模板自 0.2.13 起已自带（安装器落盘面）；旧模板没有时才补，避免重复键
+	if (!/^fs:/m.test(cfg))
+		cfg = `${cfg.trimEnd()}\nfs:\n  root: .\n  readonly: false\n`;
+	writeFileSync(configPath, cfg, "utf-8");
+
+	// 4) 站点开发证书（oj serve 无绕过开关；mintDevCert 落 api/config 三件套）
+	await mintDevCert(path.join(apiDir, "config"));
+
+	// 5) 一次性发布方身份：seed 派生，私钥只在内存
+	const keyId = "trial.publisher";
+	const publisher = derivePublisherKey(randomBytes(16).toString("hex"));
+
+	// 6) 隔离 CDN：落 fixture 包 + 重建索引（publish/buildIndex 直落临时根）
+	mkdirSync(cdnDir, { recursive: true });
+	await publishPackage({ projectRoot: root, fixture: opts.fixture, id: keyId, privateKeyPem: publisher.privateKeyPem });
+	await buildIndex({ projectRoot: root, id: keyId, privateKeyPem: publisher.privateKeyPem });
+
+	// 7) 后端构建（api/dist + versions.json；安装与 reloading 都依赖它）
+	await buildBackend(root);
+
+	// 7b) 起 oj（starter 注入供测试）；ready 失败即整体作废，不留孤儿
+	const starter = opts.starter ?? ((cfgPath: string, base: string, apiSrc: string) => startOj(cfgPath, base, apiSrc));
+	let oj: OjProcess;
+	try {
+		oj = starter(configPath, "/api", path.join(apiDir, "dist"));
+		await oj.ready;
+	}
+	catch (error) {
+		rmSync(root, { recursive: true, force: true });
+		throw error;
+	}
+	log(`[ojm] 隔离站点就绪：http://127.0.0.1:${port}（根 ${root}）`);
+
+	// 8) cleanup：停进程 → 按 keep 决定删不删根 → 摘信号；全程幂等
+	let done = false;
+	let cleanup: () => Promise<void>;
+	const onSignal = () => {
+		void cleanup();
+	};
+	cleanup = async () => {
+		if (done) {
+			return;
+		}
+		done = true;
+		process.off("SIGINT", onSignal);
+		process.off("SIGTERM", onSignal);
+		await oj.stop().catch(() => {});
+		if (opts.keep === true) {
+			log(`[ojm] --keep：隔离根保留在 ${root}（内容见销毁清单）`);
+			return;
+		}
+		rmSync(root, { recursive: true, force: true });
+		log("[ojm] 隔离站点已销毁");
+	};
+	process.on("SIGINT", onSignal);
+	process.on("SIGTERM", onSignal);
+
+	return {
+		root,
+		port,
+		baseUrl: `http://127.0.0.1:${port}`,
+		apiBase: "/api",
+		cdnDir,
+		cdnBaseUrl: `http://127.0.0.1:${port}/cdn`,
+		dbPath,
+		publisher: { keyId, privateKeyPem: publisher.privateKeyPem, publicKeyHex: publisher.publicKeyHex, fingerprint: fingerprintOfPublicKey(publisher.publicKeyHex) },
+		admin: { user: SEED_ADMIN_USER, pass: SEED_ADMIN_PASS },
+		cleanup,
+		teardownReport: () => teardownReport(root, port),
+	};
+}
+
+/**
+ * seed 派生一次性 Ed25519 身份（照 fixtures/sig 夹具手法：公开 seed → SHA-256 → PKCS#8 DER）。
+ * 私钥只在内存；label 每次随机，故每次 trial 都是不同身份（不会与任何既有信任库条目撞）。
+ * 导出供 walkthrough 的 neg-stranger op 派生「未登记 key」（DRY：不重写派生手法）。
+ */
+export function derivePublisherKey(label: string): { privateKeyPem: string, publicKeyHex: string } {
+	const seed = createHash("sha256").update(`ojm-trial-publisher:${label}`).digest();
+	const der = Buffer.concat([Buffer.from(ED25519_PKCS8_PREFIX, "hex"), seed]);
+	const key = createPrivateKey({ key: der, format: "der", type: "pkcs8" });
+	const privateKeyPem = key.export({ type: "pkcs8", format: "pem" }).toString();
+	return { privateKeyPem, publicKeyHex: exportRawPublicKeyHex(privateKeyPem) };
+}
+/** 空闲端口：listen(0) 取端口后立刻归还（本地一次性使用，竞态可接受） */
+function freePort(): Promise<number> {
+	return new Promise((resolve, reject) => {
+		const server = net.createServer();
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			const port = typeof address === "object" && address !== null ? address.port : 0;
+			server.close(() => resolve(port));
+		});
+	});
+}
+
+/** 销毁清单：--keep 时告诉人这里到底有什么、怎么手动清 */
+function teardownReport(root: string, port: number): string[] {
+	const lines = [
+		`隔离根：${root}`,
+		"  api/    站点树（src + config.yaml + config/ 证书 + db.sqlite）",
+		"  bin/    oj 二进制与插件（拷贝自源工程）",
+		"  cdn/    隔离 CDN（fixture 包 + 两份索引 + 签名）",
+		`监听端口：127.0.0.1:${port}（进程已停）`,
+		`手动清理：rm -rf ${root}`,
+	];
+	return lines;
+}