@oj-module/cli 0.2.2 → 0.2.6

package/src/lifecycle/__tests__/fixtures/fixture-valid/api/src/demo-solution/schema.yaml

@@ -0,0 +1,9 @@
+# 声明式表结构（形态对齐 apps/playground-oj/api/src/demo/schema.yaml）。
+# 契约 C2-12：bundle manifest 的 api.tables 必须与本表 keys 一致（oj 冗余校验 fail-fast）。
+tables:
+  note:
+    pk: id
+    columns:
+      id: {type: integer, autoincrement: true}
+      title: {type: text, null: false}
+      create_time: {type: integer, null: false}

package/src/lifecycle/__tests__/fixtures/fixture-valid/manifest.yaml

@@ -0,0 +1,96 @@
+# ── C2 契约合法夹具（fixture-valid）────────────────────────────────────
+# 覆盖《202610171254-lifecycle-manifest-contract》全部字段的合法样例。
+# 双端测试期望：Node 侧 validateContract 与 isolate 侧 preflight 均零违规。
+# 规则编号（C2-xx）见契约 §2/§4。
+name: demo-solution # C2-01 白名单 + 非保留名
+version: 0.1.0 # C2-02 oj 相容版本语法
+title: 生命周期样例 # C2-03
+summary: manifest.yaml 契约全字段合法夹具 # C2-04（→ oj 模块 desc）
+description: | # C2-05
+  用于 P1 双端契约测试的合成方案：覆盖身份/兼容/prefix/匿名/RBAC/
+  路由分类/设置分组/i18n/web 全部契约字段。
+icon: /icons/demo-solution.svg # C2-06
+author: oj-module # C2-07
+license: MIT
+homepage: https://example.com/demo-solution
+keywords: [fixture, lifecycle]
+
+changelog: # C2-08（R27 市场卡片版本对比）
+  - 0.1.0 首个契约夹具版本：全字段覆盖
+
+peerRuntime: '>=0.0.0' # C2-09（P1 预检对宿主 versions.json 强制）
+peerOj: '>=0.1.76' # C2-10（P1 仅声明不强制）
+peerFramework: '>=0.2.4'
+peerPlatform: '>=0.1.0' # C2-11（P2 起对宿主 API_VERSION 强制；本仓 API_VERSION=0.1.0，夹具声明须可被其满足）
+
+api:
+  module: demo-solution # C2-12（存在时必须 === name）
+  prefix: /api/demo-solution # C2-13（默认形态显式写出）
+  tables: [note] # 与 schema.yaml 表集一致（oj 冗余校验同源）
+  deps: # 键 = 模块名（C2-01 语法或 _platform）；值 = 范围算子语法
+    _platform: '>=0.1.0'
+  anonymous: # C2-26：首段 === 模块段；无登录语义端点
+    - demo-solution/ping
+
+web:
+  route_prefix: /demo-solution # C2-14
+  entry: modules/demo-solution/0.1.0/entry.js # C2-27（版本段 === version，POSIX）
+  # 构建器对 entry 产物计算写入；安装器 deployWeb→smoke 段重算比对（C2-28/R10）。
+  # 源树夹具中为格式样例值，产物级比对不在本夹具断言范围（见 README）。
+  integrity: sha384-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
+  css:
+    - modules/demo-solution/0.1.0/demo-solution.css
+
+archive: # C2-29 Form A（tgz 内占位：仅 file；sha256/size/signature 由 P3 publish 填充于 Form B）
+  file: demo-solution-0.1.0.tgz
+
+permissions: # C2-15：code 强制 <name>. 前缀
+  - {code: demo-solution.view, title_key: demo-solution:perm.view}
+  - {code: demo-solution.manage, title_key: demo-solution:perm.manage}
+
+roles: # C2-16：name=<name>.<role>；permissions ⊆ permissions[].code
+  - name: demo-solution.admin
+    title_key: demo-solution:role.admin
+    permissions: [demo-solution.view, demo-solution.manage]
+  - name: demo-solution.viewer
+    title_key: demo-solution:role.viewer
+    permissions: [demo-solution.view]
+
+routes: # C2-17~21：D4 三值全覆盖；order 建议 ≥200
+  - {path: /demo-solution, category: main, order: 200, title_key: demo-solution:menu.main}
+  - path: /admin/demo-solution
+    category: admin
+    order: 200
+    title_key: demo-solution:menu.admin
+    required_permission: demo-solution.manage # C2-21：∈ permissions[].code；R22 前端不下发
+
+  - {path: /demo-solution/report, category: hidden, order: 210, title_key: demo-solution:menu.report}
+
+health: /demo-solution/ping # C2-33：冒烟探针（main 路由 /demo-solution 的子路径；匿名可达经 api.anonymous 声明，D14/Q-A）
+
+settings:
+  groups: # C2-22~24（R24：moduleOf(key) === name）
+    - group: display
+      label_key: demo-solution:settings.group.display
+      items:
+        - key: demo-solution.display.theme
+          type: enum
+          default: auto
+          options: [auto, light, dark]
+          label_key: demo-solution:settings.display.theme
+        - key: demo-solution.display.page_size
+          type: int
+          default: '20'
+          label_key: demo-solution:settings.display.page_size
+    - group: notify
+      label_key: demo-solution:settings.group.notify
+      items:
+        - key: demo-solution.notify.enabled
+          type: bool
+          default: '0'
+          label_key: demo-solution:settings.notify.enabled
+        - key: demo-solution.notify.webhook
+          type: string
+          default: ''
+          secret: true
+          label_key: demo-solution:settings.notify.webhook

package/src/lifecycle/__tests__/fixtures/fixture-valid/web/src/demo-solution/entry.ts

@@ -0,0 +1,23 @@
+// 夹具 entry 占位：真实工程经 defineModule（@oj-module/runtime）声明，形态对齐
+// apps/playground-oj/web/src/<module>/entry.ts。夹具仅承载结构与 i18n key 断言，
+// 不参与构建与类型检查（不 import 外部模块）。
+const entry = {
+	name: "demo-solution",
+	description: "manifest.yaml 契约全字段合法夹具",
+	version: "0.1.0",
+	peerRuntime: ">=0.0.0",
+	routes: [
+		{
+			path: "/demo-solution",
+			handle: { layout: "container", order: 200, title: "demo-solution:menu.main" },
+			children: [
+				{
+					path: "report",
+					handle: { title: "demo-solution:menu.report", hideInMenu: true },
+				},
+			],
+		},
+	],
+};
+
+export default entry;

package/src/lifecycle/__tests__/fixtures/fixture-valid/web/src/demo-solution/locales/en-US.json

@@ -0,0 +1,29 @@
+{
+	"menu": {
+		"main": "Lifecycle Sample",
+		"admin": "Sample Admin",
+		"report": "Sample Report"
+	},
+	"perm": {
+		"view": "View sample",
+		"manage": "Manage sample"
+	},
+	"role": {
+		"admin": "Sample Admin Role",
+		"viewer": "Sample Viewer Role"
+	},
+	"settings": {
+		"group": {
+			"display": "Display Preferences",
+			"notify": "Notification Preferences"
+		},
+		"display": {
+			"theme": "Theme",
+			"page_size": "Page Size"
+		},
+		"notify": {
+			"enabled": "Enable Notifications",
+			"webhook": "Webhook URL"
+		}
+	}
+}

package/src/lifecycle/__tests__/fixtures/fixture-valid/web/src/demo-solution/locales/zh-CN.json

@@ -0,0 +1,29 @@
+{
+	"menu": {
+		"main": "生命周期样例",
+		"admin": "样例管理",
+		"report": "样例报告"
+	},
+	"perm": {
+		"view": "查看样例",
+		"manage": "管理样例"
+	},
+	"role": {
+		"admin": "样例管理员",
+		"viewer": "样例查看者"
+	},
+	"settings": {
+		"group": {
+			"display": "显示偏好",
+			"notify": "通知偏好"
+		},
+		"display": {
+			"theme": "主题",
+			"page_size": "每页条数"
+		},
+		"notify": {
+			"enabled": "启用通知",
+			"webhook": "Webhook 地址"
+		}
+	}
+}

package/src/lifecycle/__tests__/fixtures/sig/demo-solution-0.2.0.tgz.bad.sig

@@ -0,0 +1,7 @@
+{
+  "alg": "Ed25519",
+  "key_id": "ojm.test",
+  "public_key": "6320cd295df4a2cf48b90282daae32e133fefd0459d71af92d6c376889d038ef",
+  "value": "AizOO9Xhj4iCJJj8GRORgl7G1IzvGHfEZ1tYq6NEuwxiVDdrX7Nu3sqhazxXyrfzybPa11M23RZtji4iLHq1Dw==",
+  "canon": "v1"
+}

package/src/lifecycle/__tests__/fixtures/sig/demo-solution-0.2.0.tgz.sig

@@ -0,0 +1,7 @@
+{
+  "alg": "Ed25519",
+  "key_id": "ojm.test",
+  "public_key": "6320cd295df4a2cf48b90282daae32e133fefd0459d71af92d6c376889d038ef",
+  "value": "ZizOO9Xhj4iCJJj8GRORgl7G1IzvGHfEZ1tYq6NEuwxiVDdrX7Nu3sqhazxXyrfzybPa11M23RZtji4iLHq1Dw==",
+  "canon": "v1"
+}

package/src/lifecycle/__tests__/fixtures/sig/demo-solution-0.2.0.tgz.unknown.sig

@@ -0,0 +1,7 @@
+{
+  "alg": "Ed25519",
+  "key_id": "stranger.unknown",
+  "public_key": "a329626d90b337a969f66b101ad8bda4dc95f8c6f000731083147c262e8bbabb",
+  "value": "A8X5XsXQJOvIY55I1Dnz7bB6Y/TY0yLJiGze9AFN+ZsHor5ZPlm09ZLgBRdaymw/cLaEgeSkLr6dnYXaKSDxDw==",
+  "canon": "v1"
+}

package/src/lifecycle/__tests__/fixtures/sig/gen-signed-fixtures.d.mts

@@ -0,0 +1,21 @@
+/** gen-signed-fixtures.mjs 的类型声明（.mjs 无内联类型，供两端 TS 测试 import） */
+export declare const FIXTURE_NAME: string;
+export declare const FIXTURE_VERSION: string;
+export declare const CANON: string;
+export declare const TRUSTED_KEY: { key_id: string, public_key_hex: string };
+export declare const UNKNOWN_KEY: { key_id: string, public_key_hex: string };
+export declare function canonicalString(name: string, version: string, sha256: string): string;
+export declare function fingerprintOf(publicKeyHex: string): string;
+export declare function signCanonicalB64(privateKey: unknown, canonical: string): string;
+export declare function verifyCanonicalB64(publicKeyHex: string, canonical: string, valueB64: string): boolean;
+export declare function generate(outDir?: string): {
+	sha256: string
+	canonical: string
+	tgzPath: string
+	paths: { tgz: string, good: string, bad: string, unknown: string }
+	sig: {
+		good: { alg: string, key_id: string, public_key: string, value: string, canon: string }
+		bad: { alg: string, key_id: string, public_key: string, value: string, canon: string }
+		unknown: { alg: string, key_id: string, public_key: string, value: string, canon: string }
+	}
+};

package/src/lifecycle/__tests__/fixtures/sig/gen-signed-fixtures.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import { Buffer } from "node:buffer";
+/**
+ * 签名链测试夹具生成器（P2-0，契约 v1.3 §2.11/§2.12 + 附录 A.2）。
+ *
+ * 为什么自包含（仅 node: 内建、不 import 仓库 TS）：夹具要被两个 vitest 项目消费
+ * （packages/cli 与 packages/cli/templates/api 各自 root 锚定），.mjs 是两端都能直接
+ * import/spawn 的唯一形态；签名逻辑（规范串/sign）与 P2-1 的 sign.ts 同语义，
+ * 由 P2-1 spec「Node 对拍 + 夹具验签」钉住逐字一致（DRY 锚点在测试而非本文件重复实现）。
+ *
+ * 确定性（提交为产物后可重复再生）：
+ * - 测试 key 由公开 seed 常量经 SHA-256 派生 32B → PKCS#8 DER 包裹 → Ed25519
+ *   （seed 公开 = 测试 key 无保密性，私钥永不入仓——P2-12「模板/夹具不得含私钥」的前提）；
+ * - ustar 手写（mtime=0、成员字典序、0644/0755、uid/gid=0、无 owner 名）+
+ *   Node zlib gzip（头内 MTIME/FNAME 恒 0，同 deterministic-tar.ts 口径）。
+ *
+ * 产物（outDir，缺省 = 本文件所在目录）：
+ * - demo-solution-0.2.0.tgz                  共用包体（Form A，禁带 sha256/signature）
+ * - demo-solution-0.2.0.tz.sig               已签（TRUSTED_KEY）
+ * - demo-solution-0.2.0.tgz.bad.sig          篡改（value 首字符翻转，仍是合法标准 base64 → tampered 而非 sig_format）
+ * - demo-solution-0.2.0.tgz.unknown.sig      未知 key 签名（UNKNOWN_KEY，key_id 不在任何信任库）
+ */
+import { createHash, createPrivateKey, createPublicKey, sign, verify } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { gzipSync } from "node:zlib";
+
+const FIXTURE_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+export const FIXTURE_NAME = "demo-solution";
+export const FIXTURE_VERSION = "0.2.0";
+/** 规范串版本标记（契约 §2.11：canon 字段恒 "v1"） */
+export const CANON = "v1";
+const SEED_PREFIX = "ojm-lifecycle-fixture-v1:";
+
+/** 契约 v1.3 §2.11 规范串格式（逐字，P2-1 照抄实现，禁止自造分隔符） */
+export function canonicalString(name, version, sha256) {
+	return `${name}@${version}:${sha256}`;
+}
+
+/** 指纹 = sha256Hex(publicKey) 全 64 hex（契约 §2.11，UI 分组展示用） */
+export function fingerprintOf(publicKeyHex) {
+	return createHash("sha256").update(Buffer.from(publicKeyHex, "hex")).digest("hex");
+}
+
+/** 标准 base64 编码的 Ed25519 签名（契约 §2.11：value 仅标准 base64，禁 base64url） */
+export function signCanonicalB64(privateKey, canonical) {
+	return sign(null, Buffer.from(canonical, "utf8"), privateKey).toString("base64");
+}
+
+/** Node 侧验签（与 P2-1 verifyCanonical / P2-3 crypto.verifyEd25519 三方同语义） */
+export function verifyCanonicalB64(publicKeyHex, canonical, valueB64) {
+	const publicKey = createPublicKey({
+		key: Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), Buffer.from(publicKeyHex, "hex")]),
+		format: "der",
+		type: "spki",
+	});
+	return verify(null, Buffer.from(canonical, "utf8"), publicKey, Buffer.from(valueB64, "base64"));
+}
+
+function deriveKeyPair(label) {
+	const seed = createHash("sha256").update(SEED_PREFIX + label).digest(); // 32B raw seed
+	const der = Buffer.concat([Buffer.from("302e020100300506032b657004220420", "hex"), seed]);
+	const privateKey = createPrivateKey({ key: der, format: "der", type: "pkcs8" });
+	const jwk = createPublicKey(privateKey).export({ format: "jwk" });
+	return { privateKey, publicKeyHex: Buffer.from(jwk.x, "base64url").toString("hex") };
+}
+
+const trusted = deriveKeyPair("trusted");
+const unknown = deriveKeyPair("unknown");
+
+/** 已信任测试 key（key_id 满足 §2.11 命名空间 <publisher>.<id>） */
+export const TRUSTED_KEY = { key_id: "ojm.test", public_key_hex: trusted.publicKeyHex };
+/** 未知发布方测试 key（签名合法但 key_id 不在信任库 → unknown_key/needs_trust 场景） */
+export const UNKNOWN_KEY = { key_id: "stranger.unknown", public_key_hex: unknown.publicKeyHex };
+
+// ── 确定性 ustar tgz（最小形态：目录成员在子成员之前、字典序）──────────────────
+
+const BLOCK = 512;
+const RECORD = 20 * BLOCK;
+
+function octal(n, width) {
+	return `${n.toString(8).padStart(width - 1, "0")}\0`;
+}
+
+function header(relPath, size, typeflag) {
+	const h = Buffer.alloc(BLOCK);
+	h.write(relPath, 0, 100, "utf8");
+	h.write(typeflag === "5" ? "0000755\0" : "0000644\0", 100, 8, "utf8");
+	h.write("0000000\0", 108, 8, "utf8"); // uid
+	h.write("0000000\0", 116, 8, "utf8"); // gid
+	h.write(octal(size, 12), 124, 12, "utf8");
+	h.write("00000000000\0", 136, 12, "utf8"); // mtime=0
+	h.write("        ", 148, 8, "utf8"); // chksum 占位（空格）
+	h.write(typeflag, 156, 1, "utf8");
+	h.write("ustar\0", 257, 6, "utf8");
+	h.write("00", 263, 2, "utf8");
+	let sum = 0;
+	for (const b of h) sum += b;
+	h.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, 8, "utf8");
+	return h;
+}
+
+function buildTgz(members) {
+	const body = [];
+	for (const m of members) {
+		body.push(header(m.path, m.content ? m.content.length : 0, m.content ? "0" : "5"));
+		if (m.content) {
+			body.push(m.content);
+			const pad = (BLOCK - (m.content.length % BLOCK)) % BLOCK;
+			if (pad > 0)
+				body.push(Buffer.alloc(pad));
+		}
+	}
+	body.push(Buffer.alloc(RECORD)); // 双零块 EOF + 补齐整记录
+	return gzipSync(Buffer.concat(body));
+}
+
+const BUNDLE_MANIFEST = `# 签名链测试夹具（P2-0，契约 v1.3）——Form A：禁带 sha256/size/signature（B-2 自引用悖论）
+name: ${FIXTURE_NAME}
+version: ${FIXTURE_VERSION}
+title: 签名链夹具
+summary: detached .sig 验签/TOFU/吊销场景共用包体
+changelog:
+  - ${FIXTURE_VERSION} 签名链夹具版本
+`;
+
+const MODULE_MANIFEST = `name: ${FIXTURE_NAME}
+desc: detached .sig 验签/TOFU/吊销场景共用包体
+version: ${FIXTURE_VERSION}
+`;
+
+function fixtureMembers() {
+	const root = `${FIXTURE_NAME}-${FIXTURE_VERSION}`;
+	const members = [
+		{ path: `${root}/` },
+		{ path: `${root}/manifest.yaml`, content: Buffer.from(BUNDLE_MANIFEST, "utf8") },
+		{ path: `${root}/api/` },
+		{ path: `${root}/api/${root}/` },
+		{ path: `${root}/api/${root}/manifest.yaml`, content: Buffer.from(MODULE_MANIFEST, "utf8") },
+	];
+	members.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+	return members;
+}
+
+function tamperFirstChar(valueB64) {
+	return (valueB64[0] === "A" ? "B" : "A") + valueB64.slice(1);
+}
+
+/**
+ * 生成全部夹具到 outDir，返回摘要（sha256/canonical/各 .sig 路径）。
+ * 幂等且确定：同版本生成器对同 outDir 重复运行字节一致。
+ */
+export function generate(outDir = FIXTURE_DIR) {
+	const tgz = buildTgz(fixtureMembers());
+	const sha256 = createHash("sha256").update(tgz).digest("hex");
+	const canonical = canonicalString(FIXTURE_NAME, FIXTURE_VERSION, sha256);
+
+	const sigOf = (keyId, publicKeyHex, privateKey) => ({
+		alg: "Ed25519",
+		key_id: keyId,
+		public_key: publicKeyHex,
+		value: signCanonicalB64(privateKey, canonical),
+		canon: CANON,
+	});
+
+	const good = sigOf(TRUSTED_KEY.key_id, TRUSTED_KEY.public_key_hex, trusted.privateKey);
+	const bad = { ...good, value: tamperFirstChar(good.value) };
+	const unknownSig = sigOf(UNKNOWN_KEY.key_id, UNKNOWN_KEY.public_key_hex, unknown.privateKey);
+
+	fs.mkdirSync(outDir, { recursive: true });
+	const tgzPath = path.join(outDir, `${FIXTURE_NAME}-${FIXTURE_VERSION}.tgz`);
+	const writeSig = (suffix, obj) => {
+		const p = `${tgzPath}${suffix}`;
+		fs.writeFileSync(p, `${JSON.stringify(obj, null, 2)}\n`);
+		return p;
+	};
+	fs.writeFileSync(tgzPath, tgz);
+	const paths = {
+		tgz: tgzPath,
+		good: writeSig(".sig", good),
+		bad: writeSig(".bad.sig", bad),
+		unknown: writeSig(".unknown.sig", unknownSig),
+	};
+	return { sha256, canonical, tgzPath, paths, sig: { good, bad, unknown: unknownSig } };
+}
+
+// 直接运行 = 再生成本目录产物（CI/人工复核用）
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	const r = generate();
+	console.log(`[gen-signed-fixtures] ${FIXTURE_NAME}-${FIXTURE_VERSION}.tgz sha256=${r.sha256}`);
+	console.log(`[gen-signed-fixtures] canonical=${r.canonical}`);
+	console.log(`[gen-signed-fixtures] trusted=${TRUSTED_KEY.key_id} fp=${fingerprintOf(TRUSTED_KEY.public_key_hex)}`);
+	console.log(`[gen-signed-fixtures] unknown=${UNKNOWN_KEY.key_id} fp=${fingerprintOf(UNKNOWN_KEY.public_key_hex)}`);
+}

package/src/lifecycle/__tests__/helpers.ts

@@ -0,0 +1,78 @@
+import type { KeyPair } from "../keygen";
+// 签名链测试 helper（P2-1）：测试运行时算摘要与签名，替代硬编码常量。
+// 消费方：P2-3 起全部安装路径用例（G4 下未签名夹具必被打红，P2-16 全量改造的替换件）。
+import { Buffer } from "node:buffer";
+import { createHash, createPublicKey, verify as nodeVerify } from "node:crypto";
+import { generateKeyPair } from "../keygen";
+import { CANON, canonicalString, fingerprintOfPublicKey, SIG_ALG, signCanonical } from "../sign";
+
+/** Ed25519 SPKI DER 前缀（12B）+ 32B raw 公钥 */
+const SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+/**
+ * Node 侧验签面（上游 crypto.verifyEd25519 的测试替身；同签名同语义：
+ * hex 32B 公钥 + UTF-8 msg + 标准 base64 签名；形状非法返回 false 而非抛错——
+ * 抛错/返 false 的分码由 verify 段自己负责，替身只当「原语在场」用）。
+ */
+export function nodeVerifyEd25519(publicKeyHex: string, msg: string, sigB64: string): boolean {
+	if (!/^[0-9a-f]{64}$/.test(publicKeyHex) || !/^[A-Z0-9+/]+={0,2}$/i.test(sigB64))
+		return false;
+	try {
+		const key = createPublicKey({ key: Buffer.concat([SPKI_PREFIX, Buffer.from(publicKeyHex, "hex")]), format: "der", type: "spki" });
+		return nodeVerify(null, Buffer.from(msg, "utf8"), key, Buffer.from(sigB64, "base64"));
+	}
+	catch {
+		return false;
+	}
+}
+
+/** detached 侧车 / Form B archive.signature 的字段形状（契约 §2.11 / C2-35） */
+export interface SigFile {
+	alg: string
+	key_id: string
+	public_key: string
+	value: string
+	canon: string
+}
+
+export interface SignedArchive {
+	/** 与包体匹配的 .sig 对象（上传/写盘即此 JSON） */
+	sig: SigFile
+	keyId: string
+	publicKeyHex: string
+	fingerprint: string
+	/** 生成用的密钥对（测试自行加入信任库或用于未知 key 场景） */
+	keyPair: KeyPair
+}
+
+let defaultKey: KeyPair | null = null;
+
+/** 进程内稳定的默认测试 key（每测试文件首次用时生成；跨文件不共享——无共享秘密） */
+export function defaultTestKey(): KeyPair {
+	defaultKey ??= generateKeyPair();
+	return defaultKey;
+}
+
+/**
+ * 对 tgz 字节签名：sha256(bytes) → 规范串 → Ed25519 → .sig 五字段。
+ * `keyPair` 缺省 = defaultTestKey()；传第二个 keyPair 即「未知发布方」场景。
+ */
+export function signedArchiveFor(tgz: Uint8Array, name: string, version: string, opts?: { keyPair?: KeyPair, keyId?: string }): SignedArchive {
+	const keyPair = opts?.keyPair ?? defaultTestKey();
+	const sha256 = createHash("sha256").update(tgz).digest("hex");
+	const value = signCanonical(keyPair.privateKeyPem, canonicalString(name, version, sha256));
+	return {
+		sig: { alg: SIG_ALG, key_id: opts?.keyId ?? "test.publisher", public_key: keyPair.publicKeyHex, value, canon: CANON },
+		keyId: opts?.keyId ?? "test.publisher",
+		publicKeyHex: keyPair.publicKeyHex,
+		fingerprint: fingerprintOfPublicKey(keyPair.publicKeyHex),
+		keyPair,
+	};
+}
+
+/** 便捷重载：直接给 Buffer（node fs 读出的常见形态） */
+export function signedArchiveForBuffer(tgz: Buffer, name: string, version: string, opts?: { keyPair?: KeyPair, keyId?: string }): SignedArchive {
+	return signedArchiveFor(new Uint8Array(tgz), name, version, opts);
+}
+
+export { Buffer };