@oj-module/cli 0.2.30 → 0.2.43

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[];

package/templates/src/_platform/api/_shared/site-facade.ts

@@ -3,32 +3,83 @@
 // 单一真源：market/api.ts re-export 保持既有引用面；深检/方案域直接 import 本模块。
 
 import type { FetchFace } from "../_lifecycle/steps/download";
+import { fsFace } from "../_lifecycle/atomic";
 
 /** 带缓存指令的拉取面（FetchFace 的超集：oj 全局 fetch/测试 stub 天然满足，少参函数可赋多参形） */
 export type FetchInitFace = (url: string, init?: { headers?: Record<string, string>, redirect?: string }) => Promise<{
 	ok: boolean
 	status: number
 	arrayBuffer: () => Promise<ArrayBuffer>
+	/**
+	 * 响应头读取面（REG-CS5 读面缓存）：读 ETag 发 If-None-Match → 304 不重传正文。
+	 * 可选字段：真实 fetch 的 Response.headers 天然满足；不暴露响应头的测试 stub 省略即按
+	 * 「无 ETag 语义」退化为每次全量拉取——语义正确，只是少了条件请求的省字节。
+	 */
+	headers?: { get: (name: string) => string | null }
 }>;
 
-/** 站点源（SSRF 钉②：x-forwarded-proto 取首个、去空白）。非请求上下文（CLI/测试无 Host）→ null */
-export function siteOrigin(): { proto: string, host: string } | null {
-	const h = (http as { headers?: Record<string, string | undefined> }).headers ?? {};
-	const host = h.host;
-	if (!host) {
+/**
+ * 站点 canonical origin（REG-CS6 Host 头 SSRF 修复）：**绝不**读请求头 host / x-forwarded-proto——
+ * 伪造 Host（如 169.254.169.254 云元数据）若被用来补全相对 URL，出站请求会被牵引到攻击者指定的
+ * 源。一律走站点配置 `vars.canonical_origin`（模板 config.yaml 随发，部署侧填真实对外地址）。
+ *
+ * - 给定合法 origin（http(s)://host，无路径）→ 返回 {proto, host}；
+ * - 缺失 / 非法 / 空 → 返回 null（不补全、不回落请求头；相对 URL 原样透传，由下层 fetch 判不可用）。
+ *   这是 fail-closed：没有可信源就不替请求「猜」一个，避免把 Host 头当可信输入。
+ */
+export function siteOrigin(canonicalOrigin?: string | null): { proto: string, host: string } | null {
+	if (!canonicalOrigin || !canonicalOrigin.trim()) {
 		return null;
 	}
-	const proto = String(h["x-forwarded-proto"] ?? "http").split(",")[0]!.trim() || "http";
-	return { proto, host };
+	const m = /^(https?):\/\/([^/?#]+)$/i.exec(canonicalOrigin.trim());
+	if (m === null) {
+		return null;
+	}
+	return { proto: m[1]!.toLowerCase(), host: m[2]! };
+}
+
+/**
+ * 读站点 canonical origin（config.yaml `vars.canonical_origin`；缺文件/缺字段/解析失败 → null）。
+ * 隔离运行时无 node:fs/yaml：统一走 fsFace() + globalThis.yaml（与 _platform 其余读盘一致）。
+ * 异步：config 读取在隔离环境只有异步面，故 caller（marketEnv/solutionsEnv 是同步的）改为惰性、请求内解析。
+ * 进程级缓存：canonical_origin 是部署期安全设置，不会随请求热更，按 configPath 缓存避免每次请求重复读盘。
+ */
+const canonicalOriginCache = new Map<string, Promise<string | null>>();
+
+export function readCanonicalOrigin(configPath?: string): Promise<string | null> {
+	if (!configPath) {
+		return Promise.resolve(null);
+	}
+	const cached = canonicalOriginCache.get(configPath);
+	if (cached !== undefined) {
+		return cached;
+	}
+	const p = (async () => {
+		try {
+			const bytes = await fsFace().readFile(configPath);
+			// yaml.parse 是异步面（oj 隔离全局，全仓消费方同一口径）——必须 await：
+			// 漏 await 时 doc 是 Promise，vars 恒 undefined，config 里的 canonical_origin 永远读不到。
+			const doc = await (globalThis as { yaml?: { parse: (t: string) => Promise<unknown> } }).yaml?.parse(new TextDecoder().decode(bytes)) as { vars?: { canonical_origin?: unknown } } | undefined;
+			const v = doc?.vars?.canonical_origin;
+			return typeof v === "string" && v.trim() !== "" ? v.trim() : null;
+		}
+		catch {
+			return null;
+		}
+	})();
+	canonicalOriginCache.set(configPath, p);
+	return p;
 }
 
-/** 站点源补全（深检探针复用 siteOrigin；相对 URL → 绝对同源 URL） */
-export function withSiteOrigin(fetch: FetchInitFace): FetchFace {
-	const o = siteOrigin();
+/** 站点源补全（深检探针复用 siteOrigin；相对 URL → 绝对同源 URL；无可信源则不补全） */
+export function withSiteOrigin(fetch: FetchInitFace, canonicalOrigin?: string | null): FetchFace {
+	const o = siteOrigin(canonicalOrigin);
 	if (o === null) {
 		return fetch as FetchFace;
 	}
-	return url => fetch(/^https?:\/\//i.test(url) ? url : `${o.proto}://${o.host}${url}`) as ReturnType<FetchFace>;
+	// init（如 REG-CS5 条件请求的 if-none-match）必须透传——否则按源补全会静默丢掉调用方的请求头。
+	// init 形参可选，故仍可赋给单参的 FetchFace。
+	return (url: string, init?: { headers?: Record<string, string>, redirect?: string }) => fetch(/^https?:\/\//i.test(url) ? url : `${o.proto}://${o.host}${url}`, init) as ReturnType<FetchFace>;
 }
 
 /** 站点迁移账本 head（oj journal 真源 `_oj_migrations`；表缺失/查询失败 → null = 跳过禁降版判定，不猜） */

package/templates/src/_platform/api/manifest.yaml

@@ -15,3 +15,4 @@ tables:
   - market_history
   - sys_rate_window
   - sys_login_throttle
+  - reg_source_seq