@oj-module/cli 0.2.1 → 0.2.5

package/templates/api/src/_platform/_lifecycle/steps/verify.ts

@@ -0,0 +1,207 @@
+// 校验步骤（P1-6 sha256 fail-closed C2-29 + P2-3 Ed25519 验签，十阶段 stage 3 verifying）。
+// 签名载体两形态同源（契约 v1.3 §2.9/§2.11）：CDN 源 = Form B manifest.archive.signature；
+// file 源 = detached 侧车 .sig（market install 端点上传时点注入同一结构）。
+// 验签硬边界（G4）：缺签名/验签不过/格式错一律拒装零落盘，无 solution_allow_unsigned 类开关。
+// 结构校验序（全部前置，逐条短路）：alg → key_id 命名空间 → public_key 64hex → value 标准 base64
+// → 规范串 → 信任库比对 → verifyEd25519。未知 key_id → needsTrust（第五终态，staging 不清场）。
+// 注入面（DIP）：sha256Hex / verifyEd25519 / trustPath——原语不可得即拒装，同 sha256Hex 既有口径
+// （oj 运行时私有 crypto 面；Node 测试侧 WebCrypto 无此面，两面皆缺 fail-closed 不静默跳过）。
+
+import type { SigCode } from "../types";
+import type { InstallContext } from "./preflight";
+import { fsFace } from "../atomic";
+import { createTrustStore, isValidKeyId } from "../trust";
+import { archiveFileOf } from "./download";
+
+export type Sha256Face = (data: Uint8Array) => string;
+/** Ed25519 验签面（上游 crypto.verifyEd25519 同签名：hex/base64 32B 公钥 + UTF-8 msg + 标准 base64 签名） */
+export type VerifyEd25519Face = (publicKey: string, msg: string, sigBase64: string) => boolean;
+
+export interface VerifyContext extends InstallContext {
+	/** 暂存目录（与 download 同目录接力） */
+	staging: string
+	/** 注入式摘要面；缺省回落 globalThis.crypto.sha256Hex */
+	sha256Hex?: Sha256Face
+	/** 宿主信任库路径（.solutions/trusted-keys.yaml；缺省 = 验签能力未配置，fail-closed 拒装） */
+	trustPath?: string
+	/** Ed25519 验签面；缺省回落 globalThis.crypto.verifyEd25519 */
+	verifyEd25519?: VerifyEd25519Face
+}
+
+export interface StageResult {
+	stage: "verifying"
+	ok: boolean
+	message: string
+	retryable?: boolean
+	code?: SigCode
+	needsTrust?: boolean
+	trust?: { key_id: string, public_key: string, fingerprint: string }
+}
+
+const HEX64 = /^[0-9a-f]{64}$/;
+/** 标准 base64（含 -/_ 即 base64url，一律 sig_format，禁归一） */
+const STD_B64 = /^[A-Z0-9+/]+={0,2}$/i;
+/** 规范串版本标记（契约 §2.11；不认识即 sig_format） */
+const CANON = "v1";
+
+interface Signature {
+	alg: unknown
+	key_id: unknown
+	public_key: unknown
+	value: unknown
+	canon?: unknown
+}
+
+/** 签名失败结果统一出口（六码：retryable 恒 false、零解压零落盘；unknown_key 附 needsTrust） */
+function sigFail(code: SigCode, message: string, trust?: StageResult["trust"]): StageResult {
+	return { stage: "verifying", ok: false, retryable: false, code, message, ...(trust !== undefined ? { needsTrust: true, trust } : {}) };
+}
+
+function sha256HexFaceOf(ctx: VerifyContext): Sha256Face | undefined {
+	return ctx.sha256Hex ?? (globalThis as { crypto?: { sha256Hex?: Sha256Face } }).crypto?.sha256Hex;
+}
+
+function verifyEd25519FaceOf(ctx: VerifyContext): VerifyEd25519Face | undefined {
+	return ctx.verifyEd25519 ?? (globalThis as { crypto?: { verifyEd25519?: VerifyEd25519Face } }).crypto?.verifyEd25519;
+}
+
+/** 指纹 = sha256Hex(publicKey)（契约 §2.11；复用注入摘要面，面不可得 → null 仅展示降级） */
+function fingerprintOf(shaFace: Sha256Face, publicKeyHex: string): string | null {
+	try {
+		const raw = new Uint8Array(32);
+		for (let i = 0; i < 32; i++)
+			raw[i] = Number.parseInt(publicKeyHex.slice(i * 2, i * 2 + 2), 16);
+		return shaFace(raw);
+	}
+	catch {
+		return null;
+	}
+}
+
+export async function verify(ctx: VerifyContext): Promise<StageResult> {
+	const arch = archiveFileOf(ctx.manifest);
+	if (!arch.ok) {
+		return { stage: "verifying", ok: false, retryable: false, message: `校验失败：${arch.message}` };
+	}
+	const expected = arch.archive.sha256;
+	if (typeof expected !== "string" || expected === "") {
+		return {
+			stage: "verifying",
+			ok: false,
+			retryable: false,
+			message: "校验失败：archive.sha256 缺失（C2-29 fail-closed：Form A 占位无摘要，安装清单须为 Form B CDN 聚合真源）",
+		};
+	}
+	const dest = `${ctx.staging}/${arch.file}`;
+	const shaFace = sha256HexFaceOf(ctx);
+	if (typeof shaFace !== "function") {
+		return {
+			stage: "verifying",
+			ok: false,
+			retryable: false,
+			message: "校验失败：摘要能力不可用（sha256Hex 面未注入且运行时全局缺失）——C2-29 fail-closed 拒装，不静默跳过",
+		};
+	}
+	let bytes: Uint8Array;
+	try {
+		bytes = await fsFace().readFile(dest);
+	}
+	catch (e) {
+		return { stage: "verifying", ok: false, retryable: true, message: `校验失败：无法读取 ${dest}（${String(e)}）——附录 A verifying：请重试下载` };
+	}
+	const actual = shaFace(bytes);
+	if (actual !== expected) {
+		return {
+			stage: "verifying",
+			ok: false,
+			retryable: true,
+			message: `校验失败：${arch.file} 摘要与索引不符（C2-29 fail-closed；附录 A verifying：分发包可能损坏，请重试下载）期望 ${expected}，实得 ${actual}`,
+		};
+	}
+	// P2-6 同版本重装摘要比对（D11③ 族）：sidecar 记录过本版本的安装摘要——重取包不同 =
+	// 版本内容被替换（CDN 同名版本换包即拒；发布方应升版本号）。升级（新版本）无此记录不比对。
+	const prev = ctx.state.read().solutions[ctx.name];
+	if (prev !== undefined && prev.version === ctx.version && prev.archive !== undefined && prev.archive.sha256 !== expected) {
+		return {
+			stage: "verifying",
+			ok: false,
+			retryable: false,
+			code: "tampered",
+			message: `校验失败：重取包摘要与已装记录不符（tampered）——同版本 ${ctx.name}@${ctx.version} 的包内容被替换，拒装。已装记录 ${prev.archive.sha256}，本次重取 ${expected}；请发布方升版本号后重试`,
+		};
+	}
+	// ── P2-3 验签（sha256 通过后；规范串基于已验字节，R10 语义）────────────────────────
+	return verifySignature(ctx, bytes, actual, shaFace);
+}
+
+/** 验签主体（sha256 已过）：结构校验序 → 信任库 → verifyEd25519；全拒装路径零解压零落盘 */
+async function verifySignature(ctx: VerifyContext, bytes: Uint8Array, sha256: string, shaFace: Sha256Face): Promise<StageResult> {
+	const raw = (ctx.manifest as { archive?: { signature?: unknown } } | null)?.archive?.signature;
+	if (raw === undefined || raw === null) {
+		return sigFail("sig_missing", "校验失败：分发包未签名（sig_missing；G4 硬 fail-closed——Form B 缺 signature 或 file 源缺同目录 .sig 侧车，无逃生门）。指引：请向发布方索取签名包，或见 devkit「签名与信任」");
+	}
+	if (typeof raw !== "object" || Array.isArray(raw)) {
+		return sigFail("sig_format", `校验失败：signature 结构非法（sig_format；应为 {alg,key_id,public_key,value,canon} 对象），实为 ${Array.isArray(raw) ? "array" : typeof raw}`);
+	}
+	const sig = raw as Signature;
+	// ① alg 恒 "Ed25519"（大小写敏感）
+	if (sig.alg !== "Ed25519") {
+		return sigFail("sig_alg", `校验失败：签名算法只支持 Ed25519（sig_alg），实为「${String(sig.alg)}」`);
+	}
+	// ② key_id 命名空间 <publisher>.<id>（C2-37：禁裸通用名，防抢注/碰撞）
+	if (typeof sig.key_id !== "string" || !isValidKeyId(sig.key_id)) {
+		return sigFail("sig_key", `校验失败：key_id 命名空间非法（sig_key；C2-37：<publisher>.<id> 全小写、禁裸通用名单段），实为「${String(sig.key_id)}」`);
+	}
+	// ③ public_key 严格 64hex（32B raw；禁 PEM/SPKI——上游 decode_key 不认）
+	if (typeof sig.public_key !== "string" || !HEX64.test(sig.public_key)) {
+		return sigFail("sig_format", `校验失败：public_key 必须是 64 hex（Ed25519 32B raw，sig_format；禁 PEM/SPKI），实为「${String(sig.public_key).slice(0, 24)}」`);
+	}
+	// ④ value 严格标准 base64（含 -/_ 即 base64url → sig_format，禁归一）
+	if (typeof sig.value !== "string" || !STD_B64.test(sig.value)) {
+		return sigFail("sig_format", "校验失败：签名 value 必须是标准 base64（sig_format；base64url 含 -/_ 不受理，不做归一）");
+	}
+	// ⑤ canon 版本标记
+	if (sig.canon !== undefined && sig.canon !== CANON) {
+		return sigFail("sig_format", `校验失败：规范串版本标记不认识（sig_format；本机支持 ${CANON}），实为「${String(sig.canon)}」`);
+	}
+	// ⑥ 验签原语可得性（与 sha256Hex 同口径：不可得 = 拒装，不静默跳过）
+	const face = verifyEd25519FaceOf(ctx);
+	if (typeof face !== "function") {
+		return sigFail("sig_format", "校验失败：验签能力不可用（verifyEd25519 面未注入且运行时全局缺失）——G4 fail-closed 拒装，不静默跳过");
+	}
+	// ⑦ 信任库比对（TOFU 三态）
+	if (ctx.trustPath === undefined || ctx.trustPath === "") {
+		return sigFail("sig_missing", "校验失败：宿主未配置信任库路径（trustPath 缺失）——验签能力未就绪，fail-closed 拒装");
+	}
+	const trustedKey = await createTrustStore(ctx.trustPath).get(sig.key_id);
+	const fingerprint = fingerprintOf(shaFace, sig.public_key);
+	if (trustedKey === null) {
+		// 未知 key_id：停 needs_trust（staging 不清场，确认后重试）
+		return sigFail(
+			"unknown_key",
+			`待信任确认：发布方「${sig.key_id}」不在宿主信任库（unknown_key）。请核对指纹后执行 ojm trust confirm --task <task_id>（或市场页确认），确认入库即可重试安装`,
+			{ key_id: sig.key_id, public_key: sig.public_key, fingerprint: fingerprint ?? "" },
+		);
+	}
+	if (trustedKey !== sig.public_key) {
+		return sigFail("sig_key", `校验失败：key_id「${sig.key_id}」的包内公钥与信任库绑定不一致（sig_key；首次绑定不可改——疑抢注/换钥，请发布方轮换为新 key_id）`);
+	}
+	// ⑧ 规范串 + 验签（双层语义：抛错 = sig_format，false = tampered，同拒装但分码）
+	const canonical = `${ctx.name}@${ctx.version}:${sha256}`;
+	let verified: boolean;
+	try {
+		verified = face(sig.public_key, canonical, sig.value);
+	}
+	catch (e) {
+		// 上游格式错（verifyEd25519: 起头）在 isolate 内转 sig_format——抛错不得逃逸成阶段异常
+		return sigFail("sig_format", `校验失败：验签输入格式错（sig_format）：${String(e)}`);
+	}
+	if (!verified) {
+		return sigFail("tampered", "校验失败：签名与包体不符（tampered；签名不符不落盘——请重新从可信源获取分发包与签名）");
+	}
+	return {
+		stage: "verifying",
+		ok: true,
+		message: `校验通过：sha256 与索引一致（C2-29）+ Ed25519 验签通过（发布方 ${sig.key_id}，指纹 ${fingerprint ?? "n/a"}，G4 已启用）`,
+	};
+}

package/templates/api/src/_platform/_lifecycle/tasks.ts

@@ -0,0 +1,119 @@
+// 任务注册表（P1-10，R13/B9/R31）：.install-tasks/<id>.json 任务状态文件——oj 进程内单写者
+// （安装器），800ms 轮询消费面（市场页/CLI）。治理三件套：保留最近 10 条（超出删最旧，按
+// startedAt 序）；running 超 30min 无进展判 failed（启动/对账时点 sweep——持有者崩溃自愈）；
+// message 落盘前脱敏（URL query / Bearer / JWT / token= 形态；sha256 诊断摘要不脱——verify
+// 失败的期望/实得摘要非秘密，脱掉即失去可诊断性）。写入一律经 atomicWriteText（D13 同款）。
+
+import type { TaskRecord } from "./types";
+import { atomicWriteText, fsFace } from "./atomic";
+
+/** 任务文件保留条数（超出删最旧） */
+export const TASK_KEEP = 10;
+
+/** 当前任务记录 schema 版本（P2-10）：写方盖章、读方回填；升版纪律见 TaskRecord.schemaVersion 注释 */
+export const TASK_SCHEMA_VERSION = 1;
+
+/** 旧记录兼容：无 schemaVersion 的记录回填 1（读方不炸；更高版本原样透传，由消费面降级提示） */
+function normalizeTask(record: TaskRecord): TaskRecord {
+	return record.schemaVersion === undefined ? { ...record, schemaVersion: TASK_SCHEMA_VERSION } : record;
+}
+
+/** running 超时阈值：>30min 无进展判 failed（与 .lock stale 阈值同款口径） */
+export const TASK_TIMEOUT_MS = 30 * 60_000;
+
+/**
+ * message 脱敏（落盘前）：URL query 整段、Bearer 授权头、JWT 三段形态、token/secret/password
+ * 等敏感参数赋值——四类 token 形态字符串。sha256/sha384 摘要不脱（公开产物的诊断摘要非秘密）。
+ */
+export function redact(message: string): string {
+	return message
+		.replace(/\?[^"'\s)\]}]*/g, "?…")
+		.replace(/Bearer\s+\S+/gi, "Bearer …")
+		// PEM 私钥块（-----BEGIN ... PRIVATE KEY-----…-----END … PRIVATE KEY-----）整块脱敏
+		.replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?-----END [^-]*PRIVATE KEY-----/g, "-----BEGIN PRIVATE KEY-----…-----END PRIVATE KEY-----")
+		// JSON 中的 private_key / privateKey 字段值
+		.replace(/"private_?key"\s*:\s*"[^"]*"/gi, "\"private_key\":\"…\"")
+		// JWT（eyJ... 三段）
+		.replace(/eyJ[\w-]+(?:\.[\w-]+)+/g, "…")
+		.replace(/\b(token|secret|password|passwd|pwd|api_?key|signature)\s*[=:]\s*[^\s"',;)]+/gi, "$1=…");
+}
+
+/** 写任务文件：脱敏 → 盖章 schema 版本（写方语义，单写者恒为当前版本）→ 原子写 → 治理（保留最近 TASK_KEEP 条，删最旧；本次写入豁免） */
+export async function writeTask(taskDir: string, record: TaskRecord): Promise<void> {
+	const clean: TaskRecord = {
+		...record,
+		schemaVersion: TASK_SCHEMA_VERSION,
+		message: redact(record.message),
+		stages: record.stages.map(s => ({ ...s, message: redact(s.message) })),
+		...(record.error === undefined ? {} : { error: { ...record.error, reason: redact(record.error.reason) } }),
+	};
+	await atomicWriteText(`${taskDir}/${record.id}.json`, `${JSON.stringify(clean, null, 2)}\n`);
+	const all = (await readTasks(taskDir))
+		.filter(t => t.id !== record.id)
+		.sort((a, b) => a.startedAt - b.startedAt);
+	const stale = all.slice(0, Math.max(0, all.length + 1 - TASK_KEEP));
+	for (const t of stale) {
+		try {
+			await fsFace().remove(`${taskDir}/${t.id}.json`);
+		}
+		catch {
+			// 单条清理失败不影响主流程（下次写入再收敛）
+		}
+	}
+}
+
+/** 读全部任务文件（损坏条目跳过不炸；目录不存在视同空表） */
+export async function readTasks(taskDir: string): Promise<TaskRecord[]> {
+	let names: string[];
+	try {
+		names = await fsFace().readdir(taskDir);
+	}
+	catch {
+		return [];
+	}
+	const out: TaskRecord[] = [];
+	for (const name of names.filter(n => n.endsWith(".json"))) {
+		try {
+			out.push(normalizeTask(JSON.parse(new TextDecoder().decode(await fsFace().readFile(`${taskDir}/${name}`))) as TaskRecord));
+		}
+		catch {
+			// 单文件损坏跳过：任务面可观测性优先，不为坏文件阻塞对账/轮询
+		}
+	}
+	return out;
+}
+
+/** 单条查询（轮询消费面 getTask）；id 不在白名单（lock/state 键同款字符集，Finding B 防穿越）、缺失或损坏返回 null */
+export async function getTask(taskDir: string, id: string): Promise<TaskRecord | null> {
+	if (!/^[\w.-]+$/.test(id)) {
+		return null;
+	}
+	try {
+		return normalizeTask(JSON.parse(new TextDecoder().decode(await fsFace().readFile(`${taskDir}/${id}.json`))) as TaskRecord);
+	}
+	catch {
+		return null;
+	}
+}
+
+/**
+ * 超时清扫（启动/对账时点调用）：running 且 startedAt 超 TASK_TIMEOUT_MS 判 failed
+ * （retryable——重跑即可续装），finishedAt 补齐。返回被改判的记录。
+ */
+export async function sweepTimedOut(taskDir: string, now: number = Date.now()): Promise<TaskRecord[]> {
+	const flipped: TaskRecord[] = [];
+	for (const t of await readTasks(taskDir)) {
+		if (t.status !== "running" || now - t.startedAt <= TASK_TIMEOUT_MS) {
+			continue;
+		}
+		const fixed: TaskRecord = {
+			...t,
+			status: "failed",
+			finishedAt: now,
+			error: { reason: `安装任务超时（超过 ${Math.round(TASK_TIMEOUT_MS / 60000)} 分钟无进展，持有者疑似崩溃）——R13/B9/R31 启动/对账判 failed；锁前失败可重跑，锁后失败请先对账（reconcile）`, retryable: true },
+		};
+		await writeTask(taskDir, fixed);
+		flipped.push(fixed);
+	}
+	return flipped;
+}

package/templates/api/src/_platform/_lifecycle/text-edit.ts

@@ -0,0 +1,110 @@
+// config.yaml 文本锚点编辑（R18）：安装器改写用户 config.yaml 的唯一手段。
+// 禁止 yaml 解析/stringify 回写——用户注释、缩进、空行、键序必须逐字保留，
+// 因此只做文本级行操作：锚点是整行注释（如 `# ojm:mount`），块插入其下一行。
+// 匹配口径：整行 trim 后相等才算已存在（子串出现不算，防误判幂等）。
+
+export function hasAnchor(content: string, anchor: string): boolean {
+	const target = anchor.trim();
+	return content.split("\n").some(line => line.trim() === target);
+}
+
+export function insertAnchor(content: string, anchorComment: string, block: string): string {
+	const target = anchorComment.trim();
+	const lines = content.split("\n");
+	const index = lines.findIndex(line => line.trim() === target);
+	if (index === -1) {
+		throw new Error(`text-edit: config.yaml 中未找到锚点注释行「${anchorComment}」，无法插入内容块`);
+	}
+	// 幂等：锚点的下一行已与本块首行相同（上次插入的痕迹）则原样返回，
+	// 二次调用 no-op。判定只看紧邻一行（trim 后比较，兼容缩进继承）；
+	// 用户在锚点与块之间手工加行后重跑会再插一次——不猜意图，宁重不漏。
+	const firstBlock = block.split("\n")[0].trim();
+	if (lines[index + 1] !== undefined && lines[index + 1].trim() === firstBlock) {
+		return content;
+	}
+	// 缩进继承锚点行：块的每个非空行前缀锚点行缩进，空行保持为空（不留尾随空白）
+	const indent = /^\s*/.exec(lines[index])?.[0] ?? "";
+	const blockLines = block.split("\n").map(line => (line === "" ? "" : indent + line));
+	lines.splice(index + 1, 0, ...blockLines);
+	return lines.join("\n");
+}
+
+/**
+ * D3 一次性注入集收口（P1-10，裁决 7 escape hatch；S1-1 实测定稿「安装无需改 mounts」——
+ * 注入集只剩 server.reload_api: true，R18）。纯文本判定，不引 yaml 解析：
+ * - 存在 reload_api 键：值 false → 拒绝（用户主动关闭热更端点，安装器不偷偷翻转语义值）；
+ *   其余（true 等）→ no-op 幂等；
+ * - 键不存在 → 锚点 `# ojm:reload` 下插入 `reload_api: true`（insertAnchor 语义：缩进继承、
+ *   注释逐字保留；锚点缺失 = 可读报错不猜位置——锚点随模板 config.yaml 发布，P1-16 接线点）。
+ */
+export function ensureReloadApi(content: string): { content: string, changed: boolean } {
+	const lines = content.split("\n");
+	const idx = lines.findIndex(l => /^\s*reload_api\s*:/.test(l));
+	if (idx !== -1) {
+		if (/^\s*reload_api\s*:\s*false\s*(?:#.*)?$/.test(lines[idx]!)) {
+			throw new Error("text-edit: config.yaml 显式 reload_api: false（用户关闭热更端点）——安装器拒绝偷偷翻转语义值，请人工确认后改回 true 再重试安装");
+		}
+		return { content, changed: false };
+	}
+	return { content: insertAnchor(content, "# ojm:reload", "reload_api: true"), changed: true };
+}
+
+/**
+ * 安装序号自增（B-11 reload 触发面；PRD E5 实测先例：vars 段语义值改动可热生效，而
+ * reloadConfig 的 unchanged 判定基于 config 文档 sha——不落盘变更则热更恒 unchanged）。
+ * R18 同纪律：纯文本行操作，注释/缩进/键序逐字保留，`ojm_install_seq: N` 整行自增为 N+1
+ * （行内尾注释原样保留）。键缺失/形状不符 = 可读报错不猜位置（键随模板 config.yaml 发布；
+ * 用户删行 = 显式退出热更触发，安装器拒绝静默安装）。
+ */
+export function bumpInstallSeq(content: string): { content: string, seq: number } {
+	const lines = content.split("\n");
+	const idx = lines.findIndex(l => /^\s*ojm_install_seq\s*:\s*\d+\s*(?:#.*)?$/.test(l));
+	if (idx === -1) {
+		throw new Error("text-edit: config.yaml 缺 ojm_install_seq: N 行（vars 安装序号，模板 config.yaml 随发，勿删）——reload 热更无变更可落（unchanged 恒真），安装终止于 reloading 段");
+	}
+	const m = /^(\s*ojm_install_seq\s*:\s*)(\d+)/.exec(lines[idx]!)!;
+	const seq = Number(m[2]) + 1;
+	lines[idx] = `${m[1]}${seq}${lines[idx]!.slice(m[0].length)}`;
+	return { content: lines.join("\n"), seq };
+}
+
+/**
+ * C2-26 anonymous 运行时接线（P2-15③ 承载，观察项 6 收口）：把方案的匿名端点追加进
+ * config.yaml `auth.anonymous_paths` 列表（oj 匿名模型 config 独占；热改属
+ * restart_pending——reload 段消息已明示，重启后生效）。
+ * 幂等：已存在（trim 相等）的路径不重复插入；`anonymous_paths:` 键缺失 = 可读报错
+ * （键随模板 config.yaml 发布，用户删键 = 显式退出匿名模型，安装器不猜位置重建）。
+ * paths 传方案相对形态（C2-26 anonymous 值，首段=apiSeg）；本函数统一补前导 `/`。
+ */
+export function appendAnonymousPaths(content: string, paths: string[]): { content: string, added: string[] } {
+	const lines = content.split("\n");
+	const idx = lines.findIndex(l => /^\s*anonymous_paths\s*:/.test(l));
+	if (idx === -1) {
+		throw new Error("text-edit: config.yaml 缺 auth.anonymous_paths 键（oj 匿名模型 config 独占，键随模板 config.yaml 发布）——方案匿名端点无法接线，请恢复该键后重试安装");
+	}
+	// 列表项收集：键行之后连续的 `- item` 行（缩进任意）；空行/注释行跳过不中断
+	// （模板 config.yaml 列表中部有行内注释），遇首个其他内容行即止
+	const wanted = paths.map(p => (p.startsWith("/") ? p : `/${p}`));
+	const existing = new Set<string>();
+	let last = idx;
+	for (let i = idx + 1; i < lines.length; i++) {
+		const line = lines[i]!;
+		if (line.trim() === "" || /^\s*#/.test(line)) {
+			continue;
+		}
+		// 先剥行内注释再取项值（防 ReDoS：不写可交换量词的组合）
+		const stripped = line.replace(/#.*$/, "").trim();
+		if (!stripped.startsWith("- ")) {
+			break;
+		}
+		existing.add(stripped.slice(2).trim());
+		last = i;
+	}
+	const added = wanted.filter(p => !existing.has(p));
+	if (added.length === 0) {
+		return { content, added: [] };
+	}
+	const itemIndent = /^\s*-/.exec(lines[idx + 1] ?? "")?.[0]?.replace(/-.*/, "") ?? (`${/^\s*/.exec(lines[idx]!)?.[0] ?? ""}  `);
+	lines.splice(last + 1, 0, ...added.map(p => `${itemIndent}- ${p}`));
+	return { content: lines.join("\n"), added };
+}

package/templates/api/src/_platform/_lifecycle/tgz-guard.ts

@@ -0,0 +1,41 @@
+// tgz 成员守卫（R1）：zip-slip 防护的校验核，纯函数、无依赖。
+// 输入契约：`tar -tvzf` 的逐行输出（P1-6 extract 步骤必须喂 verbose 形态；
+// 非 verbose `tar -tzf` 是裸成员名，首字符会撞 l/h 误拒——勿换）。
+// 条目类型取权限串首字符（l=symlink、h=hardlink）；symlink 行成员名取 ` -> ` 左侧。
+// 拒绝：绝对路径、任何 `..` 段、l/h 条目、空成员名、反斜杠路径（防御性）；
+// `./` 前缀视为相对合法（归一化后必须在包根内）。
+
+function extractMemberName(line: string): string {
+	const arrow = line.indexOf(" -> ");
+	const entry = arrow === -1 ? line : line.slice(0, arrow);
+	const trimmed = entry.trim();
+	if (trimmed === "")
+		return "";
+	const fields = trimmed.split(/\s+/);
+	return fields[fields.length - 1];
+}
+
+export function validateTarListing(lines: string[]): { ok: true } | { ok: false, offender: string } {
+	for (const line of lines) {
+		const name = extractMemberName(line);
+		// 空成员名：退化行（空行/无名字段）一律拒绝，安全边界不做容错
+		if (name === "")
+			return { ok: false, offender: "" };
+		const type = line.trimStart()[0];
+		if (type === "l" || type === "h")
+			return { ok: false, offender: name };
+		// 成员名并非可靠来源：bsdtar 成员名可含空格，`../evil` 可藏在中段 token 里。
+		// 路径检查覆盖行的全部空白分隔 token（日期/时刻 token 不含 `..`，不误杀）；
+		// 任一 token 以 `/` 开头即拒（封「空格名 `/etc x`」形态）。
+		// `C:/x` 这类盘符前缀不拒：POSIX 下是合法相对目录名、无逃逸力，反斜杠形态才拒。
+		for (const token of line.split(/\s+/)) {
+			if (token === "")
+				continue;
+			if (token.startsWith("/") || token.includes("\\"))
+				return { ok: false, offender: token };
+			if (token.split("/").includes(".."))
+				return { ok: false, offender: token };
+		}
+	}
+	return { ok: true };
+}