@oj-module/cli 0.2.30 → 0.2.43

package/src/__tests__/registry-sign.test.ts

@@ -0,0 +1,352 @@
+// BDD：`ojm registry sign`（REG-R7 外置签名，CI 侧）。
+//
+// 这条命令是「私钥不进服务端」的另一半：registry 只渲染并导出未签索引，签名发生在离线侧。
+// 用例盯三件事：
+//   ① 产出的 signatures 能被**真验签**（不是「字段齐了就算过」）——规范串与 sha256 都由命令自己拼；
+//   ② 三条 fail-closed 各自有码：公钥不符 / 正文被改 / 参数缺去处；
+//   ③ CLI 接线：`--json` 下 stdout 只有一行信封，业务失败 exit 1 且信封 code 是稳定机器码。
+import type { KeyPair } from "../lifecycle/keygen";
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { buildCli, localizeCacError, reportCliError } from "../cli";
+import { generateKeyPair } from "../lifecycle/keygen";
+import { fingerprintOfPublicKey, verifyCanonical } from "../lifecycle/sign";
+import { indexCanonical, revocationCanonical } from "../publish";
+import { registryRevocationSignCommand, registrySignCommand, RegistrySignError } from "../registry-sign";
+
+const CATALOG = `seq: 3
+issued_at: 1700000000
+expires_at: 1700604800
+shards:
+  "1": 1
+solutions:
+  - name: demo-solution
+    shards:
+      - 1
+`;
+const SHARD1 = `solutions:
+  - name: demo-solution
+    latest: 0.1.0
+    versions:
+      - name: demo-solution
+        version: 0.1.0
+`;
+const SHARD2 = SHARD1.replace("0.1.0", "0.1.1");
+
+let tmpRoot: string;
+let cwd: string;
+
+beforeEach(() => {
+	tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ojm-registry-sign-"));
+	cwd = fs.mkdtempSync(path.join(tmpRoot, "proj-"));
+});
+
+afterEach(() => {
+	vi.restoreAllMocks();
+	fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+function sha256(text: string): string {
+	return createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");
+}
+
+interface ExportFile { kind: "catalog" | "shard", no: number, text: string, seq?: number }
+
+/** 造一份 `POST /index/unsigned` 的响应体（形状与 registry 的 UNSIGNED_INDEX_SCHEMA 一致） */
+function exportBody(opts: { gen: number, keys: Array<{ keyId: string, key: KeyPair }>, files?: ExportFile[] }): string {
+	const files = opts.files ?? [
+		{ kind: "catalog" as const, no: 0, text: CATALOG, seq: opts.gen },
+		{ kind: "shard" as const, no: 1, text: SHARD1 },
+		{ kind: "shard" as const, no: 2, text: SHARD2 },
+	];
+	const pending = files.map(f => ({ kind: f.kind, no: f.no, seq: f.seq ?? opts.gen, sha256: sha256(f.text), text: f.text, needsSignature: true, signature: null }));
+	return JSON.stringify({
+		gen: opts.gen,
+		state: "pending",
+		issuedAt: 1700000000,
+		expiresAt: 1700604800,
+		pending,
+		files: pending,
+		keys: opts.keys.map(k => ({ keyId: k.keyId, fingerprint: fingerprintOfPublicKey(k.key.publicKeyHex) })),
+	});
+}
+
+function writeExport(body: string): string {
+	const file = path.join(cwd, "unsigned.json");
+	fs.writeFileSync(file, body);
+	return file;
+}
+
+function keyFile(key: KeyPair, name = "key.pem"): string {
+	const file = path.join(cwd, name);
+	fs.writeFileSync(file, key.privateKeyPem, { mode: 0o600 });
+	return file;
+}
+
+describe("registry sign：产出可直接回传的六字段签名", () => {
+	it("scenario: 正常路径 → 每个待签文件一条签名，真验签通过，回传体落盘", () => {
+		const key = generateKeyPair();
+		const file = writeExport(exportBody({ gen: 3, keys: [{ keyId: "registry.index", key }] }));
+
+		const result = registrySignCommand({
+			file,
+			id: "registry.index",
+			key: keyFile(key),
+			out: "signatures.json",
+			cwd,
+		});
+
+		expect(result.gen).toBe(3);
+		expect(result.signed).toBe(3);
+		expect(result.keyId).toBe("registry.index");
+		expect(result.fingerprint).toBe(fingerprintOfPublicKey(key.publicKeyHex));
+		expect(result.signatures.map(s => `${s.kind}:${s.no}`)).toEqual(["catalog:0", "shard:1", "shard:2"]);
+		for (const sig of result.signatures) {
+			expect(sig).toMatchObject({ alg: "Ed25519", key_id: "registry.index", public_key: key.publicKeyHex, canon: "v2", seq: 3 });
+			const text = sig.no === 0 ? CATALOG : sig.no === 1 ? SHARD1 : SHARD2;
+			expect(verifyCanonical(key.publicKeyHex, indexCanonical(sig.kind, sig.seq, text), sig.value), `${sig.kind}:${sig.no} 必须真验得过`).toBe(true);
+		}
+
+		// 落盘的就是回传请求体：`{ gen, signatures }`，可直接 `-d @`
+		const body = JSON.parse(fs.readFileSync(result.outPath!, "utf8")) as { gen: number, signatures: Array<Record<string, unknown>> };
+		expect(body.gen).toBe(3);
+		expect(body.signatures).toEqual(result.signatures);
+	});
+
+	it("scenario: 沿用片按导出给的旧代次签（seq < gen），不会自作主张签成新代次", () => {
+		const key = generateKeyPair();
+		const file = writeExport(exportBody({
+			gen: 4,
+			keys: [{ keyId: "registry.index", key }],
+			files: [
+				{ kind: "catalog", no: 0, text: CATALOG, seq: 4 },
+				{ kind: "shard", no: 1, text: SHARD1, seq: 2 },
+			],
+		}));
+		const result = registrySignCommand({ file, id: "registry.index", key: keyFile(key), out: "s.json", cwd });
+		expect(result.signatures.map(s => `${s.kind}:${s.no}@${s.seq}`)).toEqual(["catalog:0@4", "shard:1@2"]);
+		const shard = result.signatures.find(s => s.kind === "shard")!;
+		expect(verifyCanonical(key.publicKeyHex, indexCanonical("shard", 2, SHARD1), shard.value)).toBe(true);
+	});
+
+	it("scenario: 这一代没有待签文件 → 幂等成功，不碰私钥（CI 重跑不该因为没 key 变红）", () => {
+		const key = generateKeyPair();
+		const file = writeExport(exportBody({ gen: 2, keys: [{ keyId: "registry.index", key }], files: [] }));
+		const result = registrySignCommand({ file, id: "registry.index", key: path.join(cwd, "does-not-exist.pem"), out: "s.json", cwd });
+		expect(result.signed).toBe(0);
+		expect(result.signatures).toEqual([]);
+		expect(JSON.parse(fs.readFileSync(result.outPath!, "utf8"))).toEqual({ gen: 2, signatures: [] });
+	});
+});
+
+describe("registry sign：三条 fail-closed", () => {
+	it("scenario: 私钥与登记的公钥不是一对 → index_key_mismatch（上传前就挡，省一次流水线）", () => {
+		const registered = generateKeyPair();
+		const attacker = generateKeyPair();
+		const file = writeExport(exportBody({ gen: 1, keys: [{ keyId: "registry.index", key: registered }] }));
+		expect(() => registrySignCommand({ file, id: "registry.index", key: keyFile(attacker), out: "s.json", cwd }))
+			.toThrow(RegistrySignError);
+		try {
+			registrySignCommand({ file, id: "registry.index", key: keyFile(attacker), out: "s.json", cwd });
+		}
+		catch (error) {
+			expect((error as RegistrySignError).code).toBe("index_key_mismatch");
+		}
+	});
+
+	it("scenario: key_id 没在导出里登记 → index_key_mismatch", () => {
+		const key = generateKeyPair();
+		const file = writeExport(exportBody({ gen: 1, keys: [{ keyId: "registry.index", key }] }));
+		expect(() => registrySignCommand({ file, id: "other.index", key: keyFile(key), out: "s.json", cwd }))
+			.toThrowError(/没有登记 key_id「other\.index」/);
+	});
+
+	it("scenario: 正文被改过（与声明的 sha256 不符）→ index_export_tampered", () => {
+		const key = generateKeyPair();
+		const body = JSON.parse(exportBody({ gen: 1, keys: [{ keyId: "registry.index", key }] })) as { pending: Array<Record<string, unknown>> };
+		body.pending[1]!.text = `${String(body.pending[1]!.text)}#tampered`;
+		const file = writeExport(JSON.stringify(body));
+		try {
+			registrySignCommand({ file, id: "registry.index", key: keyFile(key), out: "s.json", cwd });
+			throw new Error("应当失败");
+		}
+		catch (error) {
+			expect(error).toBeInstanceOf(RegistrySignError);
+			expect((error as RegistrySignError).code).toBe("index_export_tampered");
+		}
+	});
+
+	it("scenario: 既没 --out 也没 --json → 用法错误（签名结果不能凭空消失）", () => {
+		const key = generateKeyPair();
+		const file = writeExport(exportBody({ gen: 1, keys: [{ keyId: "registry.index", key }] }));
+		expect(() => registrySignCommand({ file, id: "registry.index", key: keyFile(key), cwd }))
+			.toThrowError(/签名结果必须有去处/);
+	});
+});
+
+describe("registry sign：吊销清单（--revocations）", () => {
+	const REVOCATIONS = `seq: 7\nentries:\n  - seq: 7\n    keyId: publisher.key\n    fingerprint: ${"0".repeat(64)}\n    scope: acme\n    package: demo\n    version: 1.0.0\n    severity: block\n    reason: key compromised\n    at: 1700000000\n`;
+
+	function writeRevocations(text = REVOCATIONS): string {
+		const file = path.join(cwd, "revocations.yaml");
+		fs.writeFileSync(file, text);
+		return file;
+	}
+
+	it("scenario: 正常路径 → 签的是 revocations:<seq>:<sha256(正文)>，真验签通过，回传体落盘", () => {
+		const key = generateKeyPair();
+		const file = writeRevocations();
+		const result = registryRevocationSignCommand({ file, revocations: true, id: "registry.index", key: keyFile(key), out: "rev-sig.json", cwd });
+
+		expect(result.seq).toBe(7);
+		expect(result.keyId).toBe("registry.index");
+		expect(result.signature).toMatchObject({
+			seq: 7,
+			alg: "Ed25519",
+			key_id: "registry.index",
+			public_key: key.publicKeyHex,
+			canon: revocationCanonical(7, REVOCATIONS),
+		});
+		// 规范串里带的是**正文**摘要：服务端会重算同一个串逐字比对
+		expect(result.signature.canon).toBe(`revocations:7:${sha256(REVOCATIONS)}`);
+		expect(verifyCanonical(key.publicKeyHex, result.signature.canon, result.signature.value)).toBe(true);
+
+		// 落盘的就是回传请求体六字段，可直接 `-d @`
+		const body = JSON.parse(fs.readFileSync(result.outPath!, "utf8")) as Record<string, unknown>;
+		expect(body).toEqual(result.signature);
+	});
+
+	it("scenario: 正文任何字节变化都换 canon（这正是「必须喂原文」的原因）", () => {
+		const key = generateKeyPair();
+		const bare = registryRevocationSignCommand({ file: writeRevocations(), revocations: true, id: "registry.index", key: keyFile(key), json: true, cwd });
+		const padded = registryRevocationSignCommand({ file: writeRevocations(`${REVOCATIONS}\n`), revocations: true, id: "registry.index", key: keyFile(key), json: true, cwd });
+		expect(padded.signature.canon).not.toBe(bare.signature.canon);
+	});
+
+	it("scenario: 喂了 /revocations 的 JSON 导出 → revocation_sig_format（服务端按正文重算，签了也白签）", () => {
+		const key = generateKeyPair();
+		const file = writeRevocations("{\"seq\":7,\"entries\":[]}\n");
+		try {
+			registryRevocationSignCommand({ file, revocations: true, id: "registry.index", key: keyFile(key), json: true, cwd });
+			throw new Error("应当失败");
+		}
+		catch (error) {
+			expect(error).toBeInstanceOf(RegistrySignError);
+			expect((error as RegistrySignError).code).toBe("revocation_sig_format");
+			expect((error as RegistrySignError).message).toContain("/cdn/revocations");
+		}
+	});
+
+	it("scenario: YAML 正文里没有 seq → revocation_sig_format", () => {
+		const key = generateKeyPair();
+		const file = writeRevocations("entries: []\n");
+		try {
+			registryRevocationSignCommand({ file, revocations: true, id: "registry.index", key: keyFile(key), json: true, cwd });
+			throw new Error("应当失败");
+		}
+		catch (error) {
+			expect(error).toBeInstanceOf(RegistrySignError);
+			expect((error as RegistrySignError).code).toBe("revocation_sig_format");
+		}
+	});
+
+	it("scenario: 空文件 → 用法错误（空清单要 seq=0 的正文，不是空文件）", () => {
+		const key = generateKeyPair();
+		expect(() => registryRevocationSignCommand({ file: writeRevocations(""), revocations: true, id: "registry.index", key: keyFile(key), json: true, cwd }))
+			.toThrowError(/空清单也必须签/);
+	});
+
+	it("scenario: 缺 --id → 用法错误（这一处没有导出体可推断 key）", () => {
+		const key = generateKeyPair();
+		expect(() => registryRevocationSignCommand({ file: writeRevocations(), revocations: true, key: keyFile(key), json: true, cwd }))
+			.toThrowError(/--id/);
+	});
+
+	it("scenario: 既没 --out 也没 --json → 用法错误（签名结果不能凭空消失）", () => {
+		const key = generateKeyPair();
+		expect(() => registryRevocationSignCommand({ file: writeRevocations(), revocations: true, id: "registry.index", key: keyFile(key), cwd }))
+			.toThrowError(/签名结果必须有去处/);
+	});
+
+	it("scenario: CLI --json → stdout 一行信封，data.kind = revocations 且带 signature", async () => {
+		const key = generateKeyPair();
+		const file = writeRevocations();
+		const r = await run(["registry", "sign", file, "--revocations", "--id", "registry.index", "--key", keyFile(key), "--json"]);
+		expect(r.exitCode).toBeUndefined();
+		expect(r.out).toHaveLength(1);
+		const envelope = JSON.parse(r.out[0]!) as { ok: boolean, command: string, data: { kind: string, seq: number, signature: { canon: string } } };
+		expect(envelope).toMatchObject({ ok: true, command: "registry sign" });
+		expect(envelope.data.kind).toBe("revocations");
+		expect(envelope.data.seq).toBe(7);
+		expect(envelope.data.signature.canon).toBe(`revocations:7:${sha256(REVOCATIONS)}`);
+	});
+});
+
+/* ────────────────────────────── CLI 接线（真分发） ────────────────────────────── */
+
+interface RunResult { out: string[], err: string[], exitCode: number | undefined }
+
+async function run(argv: string[]): Promise<RunResult> {
+	const out: string[] = [];
+	const err: string[] = [];
+	const outSpy = vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+		out.push(args.map(String).join(" "));
+	});
+	const errSpy = vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+		err.push(args.map(String).join(" "));
+	});
+	const exitSpy = vi.fn();
+	const exit = exitSpy as unknown as (code: number) => never;
+	const cli = buildCli(cwd, "zh-CN", { exit, argv });
+	try {
+		cli.parse(["node", "ojm", ...argv], { run: true });
+	}
+	catch (error) {
+		reportCliError(localizeCacError(error, "zh-CN"), exit, argv);
+	}
+	await vi.waitUntil(() => out.length > 0 || err.length > 0 || exitSpy.mock.calls.length > 0, { timeout: 3000, interval: 10 });
+	outSpy.mockRestore();
+	errSpy.mockRestore();
+	return { out, err, exitCode: exitSpy.mock.calls[0]?.[0] as number | undefined };
+}
+
+describe("registry sign：CLI 接线与信封", () => {
+	it("scenario: --json 成功 → stdout 只有一行信封，signatures 在 data 里", async () => {
+		const key = generateKeyPair();
+		const file = writeExport(exportBody({ gen: 1, keys: [{ keyId: "registry.index", key }] }));
+		const r = await run(["registry", "sign", file, "--id", "registry.index", "--key", keyFile(key), "--out", "s.json", "--json"]);
+		expect(r.exitCode).toBeUndefined();
+		expect(r.out).toHaveLength(1);
+		const envelope = JSON.parse(r.out[0]!) as { ok: boolean, command: string, code: string, data: { gen: number, signed: number, signatures: Array<Record<string, unknown>>, out: string } };
+		expect(envelope.ok).toBe(true);
+		expect(envelope.command).toBe("registry sign");
+		expect(envelope.code).toBe("ok");
+		expect(envelope.data.gen).toBe(1);
+		expect(envelope.data.signed).toBe(3);
+		expect(envelope.data.signatures).toHaveLength(3);
+		expect(envelope.data.out).toBe("s.json");
+	});
+
+	it("scenario: 公钥不符 → exit 1，信封 code = index_key_mismatch（CI 靠码分支，不解析人话）", async () => {
+		const registered = generateKeyPair();
+		const attacker = generateKeyPair();
+		const file = writeExport(exportBody({ gen: 1, keys: [{ keyId: "registry.index", key: registered }] }));
+		const r = await run(["registry", "sign", file, "--id", "registry.index", "--key", keyFile(attacker), "--out", "s.json", "--json"]);
+		expect(r.exitCode).toBe(1);
+		expect(r.out).toHaveLength(1);
+		const envelope = JSON.parse(r.out[0]!) as { ok: boolean, code: string, data: unknown };
+		expect(envelope).toMatchObject({ ok: false, code: "index_key_mismatch", data: null });
+	});
+
+	it("scenario: 未知子命令 / 裸 registry → 帮助或用法错误（拼错是 2，不是业务失败 1）", async () => {
+		const bare = await run(["registry"]);
+		expect(bare.exitCode).toBeUndefined();
+		expect(bare.out.join("\n")).toContain("registry sign");
+		const typo = await run(["registry", "sing"]);
+		expect(typo.exitCode).toBe(2);
+	});
+});

package/src/cli-output.ts

@@ -0,0 +1,81 @@
+// `--json` 输出契约（REG-R12）：stdout 只放**一份**可解析的 JSON，人话改走 stderr。
+//
+// 信封字段固定（CI 靠字段分支，不解析文案）：
+//   ok       boolean   成功与否（与退出码 0/1 一一对应；用法错误=2 时 stdout 可能为空）
+//   command  string    命令名（`publish` / `config ls`）——一条流水线里多个 ojm 调用靠它归因
+//   code     string    稳定错误码（成功恒为 `"ok"`；失败是 `index_generation_mismatch` 这类机器码）
+//   message  string    人话（可以改，不该被程序依赖）
+//   data     object    命令专属载荷（成功时的结果；失败时为 null）
+//
+// 为什么不把「人话行」也塞进 JSON 数组：它们会随文案改动而变，混进机器通道等于让 CI 依赖文案。
+// 所以 `--json` 下人类提示统一走 stderr——终端里照样看得见，管道里却不会污染 stdout。
+//
+// 稳定性纪律（验收「`--json` 输出稳定字段」）：本文件导出的字段名即契约，
+// 加字段可以、改名/删字段必须当成破坏性变更（下游有 schema 断言）。
+
+export interface CliEnvelope<T> {
+	ok: boolean
+	command: string
+	code: string
+	message: string
+	data: T | null
+}
+
+export const OK_CODE = "ok";
+
+export function okEnvelope<T>(command: string, data: T, message = OK_CODE): CliEnvelope<T> {
+	return { ok: true, command, code: OK_CODE, message, data };
+}
+
+export function failEnvelope(command: string, code: string, message: string): CliEnvelope<never> {
+	return { ok: false, command, code, message, data: null };
+}
+
+export interface EmitIo {
+	/** `--json`：stdout 只放信封，人话改走 stderr */
+	json?: boolean
+}
+
+/** 命令的一次输出计划：机器通道（信封）+ 人类通道（逐行） */
+export interface EmitPlan<T> {
+	command: string
+	/** 机器码（成功 = `"ok"`） */
+	code?: string
+	message?: string
+	data: T | null
+	/** 人类可读行（不带 `[ojm]` 前缀的由调用方自己带；空数组 = 没有可读输出） */
+	human?: string[]
+}
+
+export interface EmitStreams {
+	out: (line: string) => void
+	err: (line: string) => void
+}
+
+const DEFAULT_STREAMS: EmitStreams = {
+	out: line => console.log(line),
+	err: line => console.error(line),
+};
+
+/**
+ * 按模式输出：人类通道恒发（json 下改 stderr），机器通道仅在 `--json` 下发。
+ * 信封**单行** JSON——多行也能解析，但单行让 `jq -r` 与逐行 grep 都省事。
+ */
+export function emit<T>(plan: EmitPlan<T>, io: EmitIo = {}, streams: EmitStreams = DEFAULT_STREAMS): CliEnvelope<T | null> {
+	const code = plan.code ?? OK_CODE;
+	const message = plan.message ?? (code === OK_CODE ? "ok" : "");
+	// 失败分支的 data 恒为 null：命令没跑完，半份载荷比没有更危险
+	const envelope: CliEnvelope<T | null> = code === OK_CODE
+		? okEnvelope<T | null>(plan.command, plan.data, message)
+		: failEnvelope(plan.command, code, message);
+	const human = plan.human ?? [];
+	if (io.json) {
+		for (const line of human)
+			streams.err(line);
+		streams.out(JSON.stringify(envelope));
+		return envelope;
+	}
+	for (const line of human)
+		streams.out(line);
+	return envelope;
+}