@oj-module/cli 0.2.30 → 0.2.42

package/templates/src/_platform/api/_lifecycle/source-seq.ts

@@ -0,0 +1,88 @@
+// REG-CS2 索引新鲜度（防回放/降级）：站点按源记住「见过的最大 seq」，回退即拒。
+//
+// 记在站点 DB（`reg_source_seq`，0014 迁移）而不记在 CLI：受害者是**站点**——镜像把旧索引
+// 回放给谁，谁就是被降级的一方（D1 已定，CLI/API 一致）。CLI 侧 `ojm market verify` 是
+// 离线单点校验，没有「上次见过的 seq」，故不做这项判定。
+//
+// fail-closed 口径（与 REG-CS1 同源）：
+// - 读不到 / 读到非正整数 / 写入失败 —— 一律按 `index_state_corrupt` 拒，不静默重置。
+//   静默重置等于把「防回放」降级成「每次都当第一次见」，攻击者先破坏状态再回放即穿。
+// - 表不存在同样算读不到：迁移由 _platform 自带，起不来就该响，不该悄悄放行。
+
+// db 为 oj isolate 注入全局（同模板 service 层惯例，history.ts 同款；测试由夹具装 globalThis.db）
+declare const db: { table: (name: string) => any };
+
+export const SOURCE_SEQ_TABLE = "reg_source_seq";
+
+/** 判定：ok = 放行并已记录；!ok = 拒，`code` 区分「回放/降级」与「状态损坏」 */
+export type SourceSeqVerdict = {
+	ok: true
+	prev: number | null
+} | {
+	ok: false
+	code: "index_stale" | "index_state_corrupt"
+	prev: number | null
+};
+
+/**
+ * 比对并推进某个源的最大 seq。
+ *
+ * - 首次见（无行）→ 记录并放行；
+ * - 同 seq 重复拉取 → 放行（幂等，不误伤正常重复请求），不重复写；
+ * - seq 回退（< 记录值）→ `index_stale` 拒，且不覆盖记录（不能让回放把水位拉低）。
+ */
+export async function guardAndRecordSourceSeq(source: string, seq: number): Promise<SourceSeqVerdict> {
+	const prev = await readSourceSeq(source);
+	if (prev === "corrupt")
+		return { ok: false, code: "index_state_corrupt", prev: null };
+	if (prev !== null && seq < prev)
+		return { ok: false, code: "index_stale", prev };
+	if (prev === seq)
+		return { ok: true, prev };
+	try {
+		await writeSourceSeq(source, seq);
+	}
+	catch {
+		// 写失败按 fail-closed 转「状态损坏」——不静默重置（否则防回放被降级成「每次都当第一次见」）
+		return { ok: false, code: "index_state_corrupt", prev: null };
+	}
+	return { ok: true, prev };
+}
+
+/** 读取记录：无行 → null；读不到或非正整数 → "corrupt"（bigint 是 pg/mysql 的整型口径，一并认） */
+export async function readSourceSeq(source: string): Promise<number | null | "corrupt"> {
+	let rows: Array<{ max_seq?: unknown }>;
+	try {
+		rows = await db.table(SOURCE_SEQ_TABLE)
+			.select(["max_seq"])
+			.where({ field: "source_url", op: "eq", value: source })
+			.limit(1)
+			.all() as Array<{ max_seq?: unknown }>;
+	}
+	catch {
+		return "corrupt";
+	}
+	if (!Array.isArray(rows) || rows.length === 0)
+		return null;
+	const raw = rows[0]?.max_seq;
+	if (typeof raw === "bigint")
+		return raw >= 1n ? Number(raw) : "corrupt";
+	if (typeof raw === "number" && Number.isInteger(raw) && raw >= 1)
+		return raw;
+	return "corrupt";
+}
+
+/**
+ * 记录某源的最大 seq：先 insert（首见），撞唯一键（并发首见同源）则降级为 update。
+ * 这样消除「SELECT 再 INSERT」的 TOCTOU——并发首装同源不再因唯一键冲突被误判成
+ * index_state_corrupt；任何写失败仍向上抛，由 guard 按 fail-closed 转成 index_state_corrupt。
+ */
+export async function writeSourceSeq(source: string, seq: number): Promise<void> {
+	const now = Math.floor(Date.now() / 1000);
+	try {
+		await db.table(SOURCE_SEQ_TABLE).insert({ source_url: source, max_seq: seq, updated_at: now }).run();
+	}
+	catch {
+		await db.table(SOURCE_SEQ_TABLE).update({ max_seq: seq, updated_at: now }).where({ field: "source_url", op: "eq", value: source }).run();
+	}
+}

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

@@ -6,6 +6,7 @@
 
 import type { InstallContext } from "./preflight";
 import { fsFace } from "../atomic";
+import { MAX_PACKAGE_BYTES } from "../limits";
 
 /** 最小 fetch 面（结构化：Node fetch/Response 天然满足；测试注入 stub 不真跑网络） */
 export type FetchFace = (url: string) => Promise<{
@@ -28,6 +29,8 @@ export interface StageResult {
 	ok: boolean
 	message: string
 	retryable?: boolean
+	/** 终止态错误码（installer 据此置 task.error.reason）；体积闸门命中恒 package_too_large */
+	code?: string
 }
 
 /**
@@ -62,6 +65,18 @@ export async function download(ctx: DownloadContext): Promise<StageResult> {
 		return { stage: "downloading", ok: false, retryable: false, message: `下载失败：archive.file「${arch.file}」须逐字为 <name>-<version>.tgz（「${expected}」，P2-11 索引投毒加固）` };
 	}
 	const dest = `${ctx.staging}/${arch.file}`;
+	// REG-CS8 下载闸（红队 F1）：先比对索引声明的 archive.size，超限直接拒——不发请求、不读入内存，
+	// 把「先中毒后验毒」的源头堵死（限量值全仓单源，与解压闸/上传侧共用 MAX_PACKAGE_BYTES）。
+	const declaredSize = arch.archive.size;
+	if (typeof declaredSize === "number" && Number.isFinite(declaredSize) && declaredSize > MAX_PACKAGE_BYTES) {
+		return {
+			stage: "downloading",
+			ok: false,
+			retryable: false,
+			code: "package_too_large",
+			message: `下载失败：分发包声明体积 ${declaredSize} 字节超过上限 ${MAX_PACKAGE_BYTES}（REG-CS8 package_too_large）——拒绝下载以省带宽与内存，请发布方拆分或压缩后重试`,
+		};
+	}
 	try {
 		const res = await ctx.fetch(ctx.archiveUrl);
 		if (!res.ok) {

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

@@ -9,7 +9,8 @@
 
 import type { InstallContext } from "./preflight";
 import { fsFace } from "../atomic";
-import { validateTarListing } from "../tgz-guard";
+import { MAX_UNPACKED_BYTES } from "../limits";
+import { checkTarVolumeLimits, validateTarListing } from "../tgz-guard";
 import { archiveFileOf } from "./download";
 
 export interface ExecResult {
@@ -49,6 +50,8 @@ export interface StageResult {
 	ok: boolean
 	message: string
 	retryable?: boolean
+	/** 终止态错误码（installer 据此置 task.error.reason）；体积闸门命中恒为体积类 code */
+	code?: string
 }
 
 function isObj(v: unknown): v is Record<string, unknown> {
@@ -94,6 +97,17 @@ export async function extract(ctx: ExtractContext): Promise<StageResult> {
 				message: `解压失败：包内容未通过安全校验（R1：offender「${v.offender}」为越界/链接成员）——零解压零落盘，附录 A extracting：若反复出现请勿使用该分发包`,
 			};
 		}
+		// 第二步（续）REG-CS8 体积闸门：复用同一份清单累加，零额外 IO、零解压前即拒
+		const vol = checkTarVolumeLimits(lines);
+		if (!vol.ok) {
+			return {
+				stage: "extracting",
+				ok: false,
+				retryable: false,
+				code: vol.code,
+				message: `解压失败：包内容超出体积上限（REG-CS8：${vol.code}，offender「${vol.offender}」）——零解压零落盘，附录 A extracting：请发布方拆分或压缩后重试`,
+			};
+		}
 		// 第三步 extract：校验通过才落盘；-C staging 就位即止，rename 由 P1-10 落锁段接管
 		const extracted = await ctx.exec.run(buildExtractCmd(file, ctx.staging));
 		if (extracted.code !== 0) {
@@ -109,7 +123,19 @@ export async function extract(ctx: ExtractContext): Promise<StageResult> {
 		if (!c31.ok) {
 			return { stage: "extracting", ok: false, retryable: false, message: c31.message };
 		}
-		return { stage: "extracting", ok: true, message: `解压完成：${lines.length} 个成员 → ${ctx.staging}/（单根已归平，§2.9 布局消费点；C2-31 复核通过；目录 rename 由 P1-10 落锁段接管）` };
+		// REG-CS8 解压后复核：清单尺寸可能由畸形 tar 瞒报（解压炸弹绕过清单口径），以实际磁盘占用兜底。
+		// 仅当 stat 面可用时执行（oj 真机提供；测试/缺失则降级跳过，LIST 闸已先拦）。
+		const recheck = await recheckStagingOccupancy(ctx);
+		if (!recheck.ok) {
+			return {
+				stage: "extracting",
+				ok: false,
+				retryable: false,
+				code: "unpacked_too_large",
+				message: `解压失败：实际磁盘占用 ${recheck.bytes} 字节超过上限 ${MAX_UNPACKED_BYTES}（REG-CS8 解压后复核：清单尺寸瞒报，已清场）——附录 A extracting：请发布方拆分或压缩后重试`,
+			};
+		}
+		return { stage: "extracting", ok: true, message: `解压完成：${lines.length} 个成员 → ${ctx.staging}/（单根已归平，§2.9 布局消费点；C2-31 复核通过；REG-CS8 解压后复核通过；目录 rename 由 P1-10 落锁段接管）` };
 	}
 	catch (e) {
 		return { stage: "extracting", ok: false, retryable: true, message: `解压失败：${String(e)}——附录 A extracting（S1-2 exec.run tar 三步范式）` };
@@ -239,3 +265,36 @@ export async function flattenBundleRoot(staging: string): Promise<void> {
 		await f.remove(root, { recursive: true });
 	}
 }
+
+/**
+ * REG-CS8 解压后实际磁盘占用复核（解压炸弹绕过清单口径的兜底）：递归累加 staging 全部文件体积。
+ * 仅当 stat 面可用时执行；读盘失败/缺面 → 降级跳过（LIST 闸已先拦，不误杀正常包）。
+ * 注：staging 顶层的 .tgz 一并计入（已压缩，≤ MAX_PACKAGE_BYTES，对 200MB 阈值保守不影响正常包）。
+ */
+async function recheckStagingOccupancy(ctx: ExtractContext): Promise<{ ok: true } | { ok: false, bytes: number }> {
+	const f = fsFace();
+	if (f.stat === undefined)
+		return { ok: true };
+	let total = 0;
+	const walk = async (dir: string): Promise<void> => {
+		const names = await f.readdir(dir);
+		for (const name of names) {
+			const p = `${dir}/${name}`;
+			try {
+				await f.readdir(p); // 失败 = 普通文件（与 flattenBundleRoot 同手法）
+			}
+			catch {
+				total += (await f.stat!(p)).size;
+				continue;
+			}
+			await walk(p);
+		}
+	};
+	try {
+		await walk(ctx.staging);
+	}
+	catch {
+		return { ok: true };
+	}
+	return total > MAX_UNPACKED_BYTES ? { ok: false, bytes: total } : { ok: true };
+}

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

@@ -19,11 +19,15 @@ export interface StageResult {
 	ok: boolean
 	message: string
 	retryable?: boolean
+	/** 终止态错误码（安装器据此置 task.error.reason）；保留名命中恒 reserved_name */
+	code?: string
 }
 
 interface Violation {
 	clause: string
 	detail: string
+	/** 终止态错误码（安装器据此置 task.error.reason）；保留名命中恒 reserved_name */
+	code?: string
 }
 
 // ── 契约 §2/§4 正则与清单（与契约现行文本逐字对应，改动须先改契约再同步夹具与双端实现）──
@@ -31,8 +35,13 @@ interface Violation {
 /** C2-01：name 白名单 */
 const NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
 
-/** §4.2 保留名清单（C2-01/13/14 共用；market 经 R9 恢复保留） */
-const RESERVED_NAMES = new Set(["_platform", "system", "auth", "market", "framework", "health", "plugins", "_system"]);
+/** §4.2 保留名清单（C2-01/13/14 共用；market 经 R9 恢复保留）。REG-CS7 扩项：oj/ojm/registry 一并保留 */
+const RESERVED_NAMES = new Set(["_platform", "system", "auth", "market", "framework", "health", "plugins", "_system", "oj", "ojm", "registry"]);
+
+/** 保留名替代建议（REG-CS7：给可落地的 kebab-case 候选，而非只说「非法」；两候选恒非保留名） */
+function reservedNameSuggestions(name: string): [string, string] {
+	return [`${name}-app`, `meta-${name}`];
+}
 
 /** C2-02 字符集：[0-9A-Za-z.-]（禁 +——oj validate_version 拒装，附录 B-1；禁 _——契约收紧） */
 const VERSION_CHARS_RE = /^[0-9A-Z.-]+$/i;
@@ -152,6 +161,34 @@ function caretSatisfies(host: string, base: string): boolean {
 	return hm === 0 && hi === 0 && hp === bp;
 }
 
+/**
+ * 升版反噬（红队 F4）的专属迁移提示：`host 0.2.x` + 声明 `^0.1.x`。
+ *
+ * 0.x 的 caret 语义是「minor 必须相等」（见 caretSatisfies），所以平台小版本一升，
+ * 所有声明 `^0.1.0` 的存量包**同时**装不上。这不是包写错了，是升级带来的兼容断点——
+ * 笼统回「不满足 peerPlatform」会把发布方引向「升方案版本」「改代码」两个错方向，
+ * 真正要改的只有这一行 range。
+ *
+ * 只对 0.x 给建议：`^1.0.0` 在 2.0.0 宿主上不满足是标准的语义化版本预期，没有迁移可言。
+ */
+function caretUpgradeAdvice(host: string, op: string | undefined, base: string): string | null {
+	if (op !== "^")
+		return null;
+	const h = coreParts(host);
+	const b = coreParts(base);
+	if (h === null || b === null)
+		return null;
+	if (h[0] !== 0 || b[0] !== 0 || h[1] <= b[1])
+		return null;
+	return `这是平台小版本升级带来的兼容断点（0.x 下 ^ 只匹配同 minor：^${coreOf(base)} 等价于 ${coreOf(base).split(".")[0]}.${b[1]}.*），不是本方案的问题。请把 peerPlatform 改成「>=${coreOf(base)}」后重新打包——这一条要改的是声明，不是代码`;
+}
+
+/** 版本核心段文本（`0.1.0-rc.1` → `0.1.0`；cit：提示文案里只出现核心段，别把 prerelease 带进去） */
+function coreOf(v: string): string {
+	const [major, minor, patch] = coreParts(v) ?? [0, 0, 0];
+	return `${major}.${minor}.${patch}`;
+}
+
 export async function preflight(ctx: InstallContext): Promise<StageResult> {
 	const v: Violation[] = [];
 	const m = ctx.manifest;
@@ -173,7 +210,8 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 		v.push({ clause: "C2-01", detail: `name「${String(m.name)}」不匹配 ^[a-z][a-z0-9-]{0,63}$（小写字母开头，仅小写字母/数字/连字符）` });
 	}
 	if (RESERVED_NAMES.has(name)) {
-		v.push({ clause: "C2-01", detail: `name「${name}」是保留名（§4.2：_platform/system/auth/market/framework/health/plugins/_system），禁用于方案（R9）` });
+		const [a1, a2] = reservedNameSuggestions(name);
+		v.push({ clause: "C2-01", code: "reserved_name", detail: `name「${name}」为保留名（§4.2：${[...RESERVED_NAMES].join("/")}），禁用于方案（R9）；替代名建议：${a1} / ${a2}` });
 	}
 
 	// ── C2-02 version：字符集 + oj 相容排除 ──
@@ -236,7 +274,13 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 				v.push({ clause: "C2-11", detail: `无法读取宿主平台 API 版本（GET /api/_platform/market/meta 不可用或本仓 API_VERSION 未注入），peerPlatform「${range}」强制比对失败（fail-closed）` });
 			}
 			else if (!rangeSatisfies(host, parsed[1], parsed[2])) {
-				v.push({ clause: "C2-11", detail: `宿主平台 API 版本 ${host} 不满足 peerPlatform 声明「${range}」（需升级宿主平台模块）` });
+				const advice = caretUpgradeAdvice(host, parsed[1], parsed[2]);
+				v.push({
+					clause: "C2-11",
+					detail: advice === null
+						? `宿主平台 API 版本 ${host} 不满足 peerPlatform 声明「${range}」（需升级宿主平台模块）`
+						: `宿主平台 API 版本 ${host} 不满足 peerPlatform 声明「${range}」。${advice}`,
+				});
 			}
 		}
 	}
@@ -263,7 +307,8 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 				else {
 					apiSeg = p.slice("/api/".length);
 					if (RESERVED_NAMES.has(apiSeg)) {
-						v.push({ clause: "C2-13", detail: `api.prefix 模块段「${apiSeg}」是保留名（§4.2），禁用` });
+						const [a1, a2] = reservedNameSuggestions(apiSeg);
+						v.push({ clause: "C2-13", code: "reserved_name", detail: `api.prefix 模块段「${apiSeg}」为保留名（§4.2：${[...RESERVED_NAMES].join("/")}），禁用；替代名建议：${a1} / ${a2}` });
 					}
 					if (apiSeg !== name) {
 						const occ = occupier(apiSeg);
@@ -341,7 +386,8 @@ export async function preflight(ctx: InstallContext): Promise<StageResult> {
 				else {
 					const seg = rp.slice(1);
 					if (RESERVED_NAMES.has(seg)) {
-						v.push({ clause: "C2-14", detail: `web.route_prefix 首段「${seg}」是保留名（§4.2），禁用` });
+						const [a1, a2] = reservedNameSuggestions(seg);
+						v.push({ clause: "C2-14", code: "reserved_name", detail: `web.route_prefix 首段「${seg}」为保留名（§4.2：${[...RESERVED_NAMES].join("/")}），禁用；替代名建议：${a1} / ${a2}` });
 					}
 					if (seg !== name) {
 						const occ = occupier(seg);
@@ -581,10 +627,13 @@ function report(v: Violation[]): StageResult {
 	if (v.length === 0) {
 		return { stage: "preflight", ok: true, message: "预检通过：manifest 满足 C2 契约（身份/兼容/占用/匿名/RBAC/路由/设置/health 安全预检全部通过）" };
 	}
+	// 保留名命中（reserved_name）优先作为终止态错误码（红队 F5：撞保留名是确定性拒绝，非可重试）
+	const coded = v.find(x => x.code !== undefined);
 	return {
 		stage: "preflight",
 		ok: false,
 		retryable: false,
+		code: coded?.code,
 		message: `预检未通过（${v.length} 项违规，全量列出）：\n${v.map(x => `- 【${x.clause}】${x.detail}`).join("\n")}`,
 	};
 }

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

@@ -117,7 +117,8 @@ export async function registerSolution(decl: SolutionDecl): Promise<RegisterResu
 		}
 
 		// RBAC（唯一出口）：upsert + 声明消失标 deprecated，deprecated 清单原样汇入
-		const perms = await upsertSolutionPerms({ module: decl.module, roles: decl.roles });
+		// permissions 透传顶层声明——无角色的权限点只能靠它落库（少了这行 = 管理面绑不了）
+		const perms = await upsertSolutionPerms({ module: decl.module, roles: decl.roles, permissions: decl.permissions });
 
 		// 设置项 upsert：存在只覆定义列（value/update 语义 = 管理员改过的值不复活，AC1-15），
 		// 不存在插 default_value（首装 value）

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

@@ -26,6 +26,12 @@ export interface VerifyContext extends InstallContext {
 	trustPath?: string
 	/** Ed25519 验签面；缺省回落 globalThis.crypto.verifyEd25519 */
 	verifyEd25519?: VerifyEd25519Face
+	/**
+	 * 本站点（registry）身份（REG-CS3 v2 防跨仓库重放）：签名 .sig.registry_id 必须与之一致，
+	 * 否则视为「A 签的包被 B 的 CDN 安装」→ canon_mismatch 拒装。缺省 undefined = 不启用跨仓比对
+	 * （仅验签完整性），由站点装配时填入自身 registry id 才生效。
+	 */
+	registryId?: string
 }
 
 export interface StageResult {
@@ -41,8 +47,8 @@ export interface StageResult {
 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";
+/** 规范串版本标记（REG-CS3 v2；不认识即 canon_stale 拒装） */
+const CANON = "v2";
 
 interface Signature {
 	alg: unknown
@@ -50,6 +56,8 @@ interface Signature {
 	public_key: unknown
 	value: unknown
 	canon?: unknown
+	/** 签发方 registry 身份（REG-CS3 v2 规范串首段，跨仓重放判定真源） */
+	registry_id?: unknown
 }
 
 /** 签名失败结果统一出口（六码：retryable 恒 false、零解压零落盘；unknown_key 附 needsTrust） */
@@ -160,9 +168,9 @@ async function verifySignature(ctx: VerifyContext, bytes: Uint8Array, sha256: st
 	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)}」`);
+	// ⑤ canon 版本标记（REG-CS3：v1 旧格式一律拒，逼重签；缺失即拒，不兼容旧 ojm）
+	if (sig.canon !== CANON) {
+		return sigFail("canon_stale", `校验失败：规范串版本过旧（canon_stale；本机要求 ${CANON}，实为「${String(sig.canon)}」）——请用当前 ojm 重签，旧版 .sig 不再受理`);
 	}
 	// ⑥ 验签原语可得性（与 sha256Hex 同口径：不可得 = 拒装，不静默跳过）
 	const face = verifyEd25519FaceOf(ctx);
@@ -186,8 +194,14 @@ async function verifySignature(ctx: VerifyContext, bytes: Uint8Array, sha256: st
 	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}`;
+	// ⑧ 规范串 + 验签（双层语义：抛错 = sig_format，false = signature_mismatch，同拒装但分码）
+	// REG-CS3 v2：规范串首段 = 签发方 registry 身份，防「A 签的包被 B 的 CDN 安装」跨仓重放。
+	const sigRegistryId = typeof sig.registry_id === "string" ? sig.registry_id : "";
+	const canonical = `${sigRegistryId}:${ctx.name}@${ctx.version}:${sha256}`;
+	// REG-CS3 跨仓重放：声明的 registry_id 必须与本站点身份一致（env.registryId 未配置则跳过此比对）
+	if (ctx.registryId !== undefined && sigRegistryId !== ctx.registryId) {
+		return sigFail("canon_mismatch", `校验失败：包归属 registry「${sigRegistryId}」与本站「${ctx.registryId}」不符（canon_mismatch；REG-CS3 防跨仓库重放）——疑似被挪到非签发方 registry 的 CDN 安装，已拒装`);
+	}
 	let verified: boolean;
 	try {
 		verified = face(sig.public_key, canonical, sig.value);
@@ -197,7 +211,7 @@ async function verifySignature(ctx: VerifyContext, bytes: Uint8Array, sha256: st
 		return sigFail("sig_format", `校验失败：验签输入格式错（sig_format）：${String(e)}`);
 	}
 	if (!verified) {
-		return sigFail("tampered", "校验失败：签名与包体不符（tampered；签名不符不落盘——请重新从可信源获取分发包与签名）");
+		return sigFail("signature_mismatch", "校验失败：签名与包体不符（signature_mismatch；REG-CS3 v2 规范串含 registry_id，签名不符不落盘——请重新从可信源获取分发包与签名）");
 	}
 	return {
 		stage: "verifying",

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

@@ -5,6 +5,8 @@
 // 拒绝：绝对路径、任何 `..` 段、l/h 条目、空成员名、反斜杠路径（防御性）；
 // `./` 前缀视为相对合法（归一化后必须在包根内）。
 
+import { MAX_ENTRIES, MAX_SINGLE_ENTRY_BYTES, MAX_UNPACKED_BYTES } from "./limits";
+
 function extractMemberName(line: string): string {
 	const arrow = line.indexOf(" -> ");
 	const entry = arrow === -1 ? line : line.slice(0, arrow);
@@ -39,3 +41,97 @@ export function validateTarListing(lines: string[]): { ok: true } | { ok: false,
 	}
 	return { ok: true };
 }
+
+// ── REG-CS8 体积闸门（红队 F1）：复用同一份 tar 清单累加体积/条目数/单条目最大体积，不额外跑一次 tar ──
+
+/** 体积闸门错误码（installer 据此置 task.error.reason；retryable 恒 false——体积超限非可重试） */
+export type VolumeCode = "too_many_entries" | "unpacked_too_large" | "entry_too_large";
+
+export interface TarVolume {
+	/** 成员条目数（含目录条目） */
+	entries: number
+	/** 未压缩总体积（字节） */
+	totalUncompressed: number
+	/** 单条目最大未压缩体积（字节） */
+	maxEntry: number
+}
+
+/**
+ * 从 `tar -tvzf` verbose 行提取未压缩体积（字节）。
+ * 体积恒位于「日期组」紧邻左侧、成员名之前；日期组跨实现形态：
+ *   GNU:  <size> [MM DD | YYYY-MM-DD] [HH:MM]   —— 旧 mtime（>6 月）省略时刻，只剩日期
+ *   BSD:  <size> Mon DD [HH:MM | YYYY]          —— 旧 mtime 省略时刻，只剩年份
+ * 旧实现只锚定 HH:MM，旧 mtime 行（无时刻）回退 0，使大包绕过 REG-CS8 体积闸门（zip bomb）。
+ * 这里分两路：含时刻的行仍按时间回退定位（兼容 GNU-ISO / GNU 月日 / BSD 三态）；
+ * 无时刻的旧 mtime 行改锚定「日期组」（ISO 日期或月份名），取前一 token 为 size。
+ * 无日期组的畸形行回退 0。
+ */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const MONTH = /^[A-Z]{3}$/i;
+const TIME = /^\d{1,2}:\d{2}(?::\d{2})?$/;
+const DAY_OR_YEAR = /^\d{1,2}$|^\d{4}$/;
+
+/** 定位日期组首 token 索引：含时刻则回退时间锚点；否则锚定 ISO 日期或「月份名 + 其后跟日/年份」 */
+function findDateGroupStart(tokens: string[]): number {
+	const timeIdx = tokens.findIndex(t => TIME.test(t));
+	if (timeIdx >= 1)
+		return ISO_DATE.test(tokens[timeIdx - 1]!) ? timeIdx - 1 : timeIdx - 2;
+	for (let i = tokens.length - 1; i >= 0; i--) {
+		const t = tokens[i]!;
+		if (ISO_DATE.test(t))
+			return i;
+		if (MONTH.test(t)) {
+			const next = tokens[i + 1] ?? "";
+			if (DAY_OR_YEAR.test(next))
+				return i;
+		}
+	}
+	return -1;
+}
+
+export function extractTarEntrySize(line: string): number {
+	const tokens = line.trim().split(/\s+/);
+	if (tokens.length < 2)
+		return 0;
+	const dateGroupStart = findDateGroupStart(tokens);
+	if (dateGroupStart < 1)
+		return 0;
+	const n = Number(tokens[dateGroupStart - 1]!.replace(/,/g, ""));
+	return Number.isFinite(n) ? n : 0;
+}
+
+/** 累加清单体积统计（条目数 / 未压缩总体积 / 单条目最大体积） */
+export function accumulateTarVolume(lines: string[]): TarVolume {
+	let entries = 0;
+	let totalUncompressed = 0;
+	let maxEntry = 0;
+	for (const line of lines) {
+		if (line.trim() === "")
+			continue;
+		entries++;
+		const size = extractTarEntrySize(line);
+		totalUncompressed += size;
+		if (size > maxEntry)
+			maxEntry = size;
+	}
+	return { entries, totalUncompressed, maxEntry };
+}
+
+/**
+ * 体积闸门（REG-CS8）：复用 validateTarListing 已消费的同一份 tar 清单逐项累加——
+ * 条目数 / 未压缩总体积 / 单条目最大体积任一超限即拒，零解压零落盘。
+ * 检查序：条目数 → 总体积 → 单条目（先罚「整体维度」，再罚「单点维度」）。
+ */
+export function checkTarVolumeLimits(lines: string[]): { ok: true, volume: TarVolume } | { ok: false, code: VolumeCode, offender: string, volume: TarVolume } {
+	const volume = accumulateTarVolume(lines);
+	if (volume.entries > MAX_ENTRIES) {
+		return { ok: false, code: "too_many_entries", offender: `${volume.entries} 个成员（上限 ${MAX_ENTRIES}）`, volume };
+	}
+	if (volume.totalUncompressed > MAX_UNPACKED_BYTES) {
+		return { ok: false, code: "unpacked_too_large", offender: `${volume.totalUncompressed} 字节（上限 ${MAX_UNPACKED_BYTES}）`, volume };
+	}
+	if (volume.maxEntry > MAX_SINGLE_ENTRY_BYTES) {
+		return { ok: false, code: "entry_too_large", offender: `${volume.maxEntry} 字节（上限 ${MAX_SINGLE_ENTRY_BYTES}）`, volume };
+	}
+	return { ok: true, volume };
+}

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

@@ -41,8 +41,11 @@ export interface StageResult {
 	retryable?: boolean
 	/** 取消安装（U5，P3-8）：本 stage 被用户中止，运行器据其走「清场 + 锁/目录回退装前 + 审计末位」语义 */
 	cancelled?: boolean
-	/** 签名失败六码（P2-3，契约附录 A.2；缺省 = 非签名类失败） */
-	code?: SigCode
+	/**
+	 * 终止态错误码（installer 据此置 task.error.reason；各 step 自带字面量集合——签名六码见 SigCode、
+	 * 保留名 reserved_name、体积闸 package_too_large 等；统一收敛为 string 供编排层记录与 i18n 兜底）
+	 */
+	code?: string
 	/** 未知 key_id 待 TOFU 确认：任务停 needs_trust 终态，staging 不清场供确认后重试 */
 	needsTrust?: boolean
 	/** 待确认的发布方 key（TaskRecord.trust 同源；UI/CLI 展示指纹） */
@@ -53,7 +56,7 @@ export interface StageResult {
  * 签名失败六码（契约 v1.3 附录 A.2，P2-3）：retryable 恒 false、零解压零落盘。
  * 文案 key = `lifecycle.stage.verifying.<code>`（双语值 P2-5 落 locales）。
  */
-export type SigCode = "sig_missing" | "sig_alg" | "sig_key" | "tampered" | "unknown_key" | "sig_format";
+export type SigCode = "sig_missing" | "sig_alg" | "sig_key" | "tampered" | "signature_mismatch" | "canon_stale" | "canon_mismatch" | "unknown_key" | "sig_format";
 
 /**
  * 安装阶段名（契约附录 A 十阶段逐字 + D11①扩展组 lock_commit + audit/done 终态）。

package/templates/src/_platform/api/_lifecycle/verify-checks.ts

@@ -222,6 +222,14 @@ export interface SolutionsEnv {
 	statePath: string
 	modulesJsonPath?: string
 	apiPrefix?: string
+	/**
+	 * canonical origin（REG-CS6 Host 头 SSRF 修复）：深检探针补全用的站点权威 origin，
+	 * 取自 config.yaml `vars.canonical_origin`，**绝不读请求头 Host/x-forwarded-proto**。
+	 * 缺失 → null，探针跳过（info 项），不猜、不回落请求头。
+	 */
+	canonicalOrigin?: string
+	/** 站点 config.yaml 路径（canonical origin 读取处；缺省 config.yaml） */
+	configPath?: string
 	/** 深检报告留存目录（默认随 statePath 同目录 verify-reports；P2-8） */
 	verifyReportsDir?: string
 	fetch?: FetchInitFace

package/templates/src/_platform/api/_shared/service/domain/solution-perms.ts

@@ -15,6 +15,13 @@ export interface SolutionRoleDecl {
 export interface SolutionManifest {
 	module: string
 	roles: SolutionRoleDecl[]
+	/**
+	 * 顶层 `permissions[]` 的 code 清单（契约 C2-15 的声明面）。
+	 * 与 `roles[].permissions` **不是**上下级关系：C2-16 只要求角色引用的 code 先在此声明，
+	 * 反过来「声明了但没有任何角色引用」是合法形态（系统预置权限点，由管理员在管理面自行分配）。
+	 * 漏收集的后果是这类权限点根本不落库 → 管理面绑不上 → 声明形同虚设。
+	 */
+	permissions?: string[]
 }
 
 export interface UpsertResult {
@@ -25,7 +32,8 @@ export interface UpsertResult {
 export async function upsertSolutionPerms(m: SolutionManifest): Promise<UpsertResult> {
 	const deprecated: string[] = [];
 	const declaredRoles = new Set(m.roles.map(r => r.name));
-	const declaredPerms = new Set(m.roles.flatMap(r => r.permissions ?? []));
+	// 权限点全集 = 角色引用的 ∪ 顶层独立声明的（后者是无角色权限点唯一能落库的来源）
+	const declaredPerms = new Set([...m.roles.flatMap(r => r.permissions ?? []), ...(m.permissions ?? [])]);
 
 	for (const role of m.roles) {
 		const existing = await db.table("sys_role").select(["name"]).where({ field: "name", op: "eq", value: role.name }).all() as unknown[];