@oj-module/cli 0.2.69 → 0.2.71

package/templates/src/oj-market/api/backfill.ts

@@ -0,0 +1,221 @@
+// 站点侧目录回填（计划 v4 §六——三用：回填=恢复=对账）。POST /api/oj-market/backfill
+// （superadmin，R9）触发；远端纯站点可用（无 ojm CLI 依赖，一次 HTTP 调用）。
+//
+// 语义：扫 cdn/ 存量 `<name>-<version>.tgz` → 内嵌 manifest 抽取（与上传端点同一
+// manifestOfUpload 管线，勿各写一遍）+ 旁车 .sig → upsert market_release。
+//   · 新行：published_at_source='file'（与上传通道 'upload' 区分）；yanked=0。
+//   · 已存在行（对账/灾备重放）：只重写内容列（key_id/sha256/size/sig 四列/manifest），
+//     published_at/published_at_source/first_seen_at/yanked 原样保留——审计连续、yank 不回魂。
+//   · 幂等可重入：重复跑行数不变，报告 unchanged 供对账。
+// 降级（数据表）：.sig 缺失/不可解析/与实收字节验签不绑定 → 行照落库但 sig 四列 NULL（安装验签 sig_missing
+// fail-closed），文件名进 sigMissing；坏包（解不开/manifest 名实不符）进 skipped 带
+// reason，不阻断其它文件；孤立 .sig（tgz 缺失）容忍不加 GC（须受信 key 才能制造）。
+
+import type { FsFace } from "#/_platform/_lifecycle/atomic";
+import type { ExecFace } from "#/_platform/_lifecycle/steps/extract";
+import { fsFace } from "#/_platform/_lifecycle/atomic";
+import { manifestOfUpload } from "#/_platform/_lifecycle/manifest-of-upload";
+
+import { clampManifest, packageCanonicalOf, parseSidecarSig, parseUploadFile } from "./cdn/shared";
+
+export interface BackfillEnv {
+	/** cdn/ 字节仓库目录（扫描源） */
+	cdnDir: string
+	/** 暂存目录（manifestOfUpload 解包用；常量名 staging，与上传端点分离防并发互踩） */
+	staging: string
+	/** 注入面（DIP）：缺省回落 isolate 全局 exec / crypto.sha256Hex */
+	exec?: ExecFace
+	sha256Hex?: (data: Uint8Array) => string
+	/** Ed25519 验签面（旁车与实收字节绑定校验；缺省回落 isolate 全局 crypto.verifyEd25519） */
+	verifyEd25519?: (publicKey: string, msg: string, sigBase64: string) => boolean
+	/** 当前时刻（epoch 秒；新行 published_at/first_seen_at；缺省 Date.now） */
+	now?: () => number
+}
+
+export interface BackfillReport {
+	/** cdn/ 下识别为 `<name>-<version>.tgz` 的包数（孤立 .sig 不计） */
+	scanned: number
+	/** 新建行 + 内容列被重写的行 */
+	upserted: number
+	/** 已存在且内容列无变化（幂等对账锚） */
+	unchanged: number
+	/** 坏包：解不开 / manifest 名实不符 / 缺 name·version */
+	skipped: Array<{ file: string, reason: string }>
+	/** .sig 缺失或不可解析（行已落库，sig 四列 NULL） */
+	sigMissing: string[]
+}
+
+/** 单包扫描结果（行内容列集，upsert 判定与写入共用） */
+interface RowContent {
+	key_id: string | null
+	sha256: string
+	size: number
+	sig_alg: string | null
+	sig_value: string | null
+	sig_public_key: string | null
+	sig_registry_id: string | null
+	manifest: string
+}
+
+function sha256Of(env: BackfillEnv): (data: Uint8Array) => string {
+	const g = globalThis as { crypto?: { sha256Hex?: (data: Uint8Array) => string } };
+	return env.sha256Hex ?? ((data: Uint8Array) => g.crypto!.sha256Hex!(data));
+}
+
+function verifyOf(env: BackfillEnv): (publicKey: string, msg: string, sigBase64: string) => boolean {
+	const g = globalThis as { crypto?: { verifyEd25519?: (pk: string, msg: string, sig: string) => boolean } };
+	return env.verifyEd25519 ?? ((pk, msg, sig) => g.crypto!.verifyEd25519!(pk, msg, sig));
+}
+
+function execOf(env: BackfillEnv): ExecFace {
+	const g = globalThis as { exec?: { run: ExecFace["run"] } };
+	return env.exec ?? { run: (argv, opts) => g.exec!.run(argv, opts) };
+}
+
+async function readFileOrNull(f: FsFace, path: string): Promise<Uint8Array | null> {
+	try {
+		return await f.readFile(path);
+	}
+	catch {
+		return null;
+	}
+}
+
+/** 扫描单文件：解包抽 manifest + 旁车 .sig → 行内容列；不可回填的错误以 reason 抛出（调用方计入 skipped） */
+async function scanPackage(f: FsFace, env: BackfillEnv, file: string, parsed: { name: string, version: string }): Promise<{ content: RowContent, sigMissing: boolean }> {
+	const bytes = await f.readFile(`${env.cdnDir}/${file}`);
+	const manifest = await manifestOfUpload({ stagingDir: `${env.staging}/backfill`, bytes, exec: execOf(env) });
+	const m = typeof manifest === "object" && manifest !== null && !Array.isArray(manifest) ? manifest as Record<string, unknown> : {};
+	if (typeof m.name !== "string" || m.name === "" || typeof m.version !== "string" || m.version === "")
+		throw new Error("包内 manifest 缺 name/version");
+	if (m.name !== parsed.name || m.version !== parsed.version)
+		throw new Error(`名实不符：文件名 ${parsed.name}-${parsed.version}，包内 manifest ${String(m.name)}-${String(m.version)}`);
+
+	// 旁车 .sig：缺失/损坏/与实收字节不绑定一律降级（sig 四列 NULL，fail-closed 同口径）。
+	// 验签（终审 I2）：结构合法不等于绑定——投毒旁车五字段全对但签的是别家字节，照验才挡得住。
+	let sig: ReturnType<typeof parseSidecarSig> | null = null;
+	const sigBytes = await readFileOrNull(f, `${env.cdnDir}/${file}.sig`);
+	if (sigBytes !== null) {
+		try {
+			sig = parseSidecarSig(new TextDecoder().decode(sigBytes));
+			const canonical = packageCanonicalOf(sig.registry_id, parsed.name, parsed.version, sha256Of(env)(bytes));
+			if (!verifyOf(env)(sig.public_key, canonical, sig.value))
+				sig = null; // 验签不绑定 → 视同缺签
+		}
+		catch {
+			sig = null;
+		}
+	}
+	const sigMissing = sig === null;
+	return {
+		content: {
+			key_id: sig?.key_id ?? null,
+			sha256: sha256Of(env)(bytes),
+			size: bytes.byteLength,
+			sig_alg: sig?.alg ?? null,
+			sig_value: sig?.value ?? null,
+			sig_public_key: sig?.public_key ?? null,
+			sig_registry_id: sig?.registry_id ?? null,
+			manifest: JSON.stringify(clampManifest(m)),
+		},
+		sigMissing,
+	};
+}
+
+/** 内容列集合相等判定（幂等对账：一字不差才算 unchanged） */
+function contentEqual(row: Record<string, unknown>, c: RowContent): boolean {
+	const pairs: Array<[unknown, unknown]> = [
+		[row.sha256, c.sha256],
+		[Number(row.size), c.size],
+		[row.key_id ?? null, c.key_id],
+		[row.sig_alg ?? null, c.sig_alg],
+		[row.sig_value ?? null, c.sig_value],
+		[row.sig_public_key ?? null, c.sig_public_key],
+		[row.sig_registry_id ?? null, c.sig_registry_id],
+		[String(row.manifest ?? ""), c.manifest],
+	];
+	return pairs.every(([a, b]) => a === b);
+}
+
+/**
+ * 回填主链：列目录 → 逐包扫描 → select 后 insert/update（审计列保留）。
+ * db 面走 oj 构造器全局（与上传端点同纪律）；FS 失败（单文件读坏）按坏包计入 skipped。
+ */
+export async function backfillReleases(env: BackfillEnv): Promise<BackfillReport> {
+	const f = fsFace();
+	const report: BackfillReport = { scanned: 0, upserted: 0, unchanged: 0, skipped: [], sigMissing: [] };
+	const names = await f.readdir(env.cdnDir);
+	for (const file of names.sort()) {
+		if (!file.endsWith(".tgz"))
+			continue; // 孤立 .sig 与杂文件容忍忽略
+		const parsed = parseUploadFile(file);
+		if (parsed === null || parsed.sig) {
+			report.skipped.push({ file, reason: "文件名不属于 <name>-<version>.tgz 形态" });
+			continue;
+		}
+		let scanned: Awaited<ReturnType<typeof scanPackage>>;
+		try {
+			scanned = await scanPackage(f, env, file, parsed);
+		}
+		catch (e) {
+			report.skipped.push({ file, reason: (e as Error).message });
+			continue;
+		}
+		report.scanned++;
+		if (scanned.sigMissing)
+			report.sigMissing.push(file);
+		const { content } = scanned;
+
+		const existing = (await db.table("market_release")
+			.select(["id", "sha256", "size", "key_id", "sig_alg", "sig_value", "sig_public_key", "sig_registry_id", "manifest"])
+			.where({ field: "product", op: "eq", value: parsed.name })
+			.where({ field: "version", op: "eq", value: parsed.version })
+			.limit(1)
+			.all()) as Array<Record<string, unknown>>;
+		const prior = existing[0];
+		if (prior !== undefined && contentEqual(prior, content)) {
+			report.unchanged++;
+			continue;
+		}
+		if (prior === undefined) {
+			const now = env.now?.() ?? Math.floor(Date.now() / 1000);
+			try {
+				await db.table("market_release").insert({
+					product: parsed.name,
+					version: parsed.version,
+					...content,
+					published_at: now,
+					published_at_source: "file",
+					yanked: 0,
+					first_seen_at: now,
+				}).run();
+			}
+			catch (e) {
+				// 唯一键并发仲裁（minor M2）：select 与 insert 之间他方上传先落行。重读定幂等/冲突——
+				// 同字节 → unchanged（他方行即真源）；异字节 → skipped 记冲突（他方行不可被回填改写），
+				// 全量扫描不中断；重跑回填即可再对账。非撞键的底层错误（DB 故障）原样上抛不吞。
+				const raced = (await db.table("market_release")
+					.select(["id", "sha256", "size", "key_id", "sig_alg", "sig_value", "sig_public_key", "sig_registry_id", "manifest"])
+					.where({ field: "product", op: "eq", value: parsed.name })
+					.where({ field: "version", op: "eq", value: parsed.version })
+					.limit(1)
+					.all()) as Array<Record<string, unknown>>;
+				const racedRow = raced[0];
+				if (racedRow === undefined)
+					throw e; // 非撞键错误：真故障不遮
+				if (contentEqual(racedRow, content)) {
+					report.unchanged++;
+					continue;
+				}
+				report.skipped.push({ file, reason: `并发冲突：扫描期间「${parsed.name}@${parsed.version}」已被他方上传占用且字节不同——重跑回填对账（他方行未被改写）` });
+				continue;
+			}
+		}
+		else {
+			// 对账/灾备重放：只重写内容列；published_at/published_at_source/first_seen_at/yanked 保留
+			await db.table("market_release").update({ ...content }).where({ field: "id", op: "eq", value: prior.id }).run();
+		}
+		report.upserted++;
+	}
+	return report;
+}

package/templates/src/{app/api/_platform/market → oj-market/api}/bootstrap.ts

@@ -5,8 +5,8 @@
 // 私钥入仓即信任根基烧毁（tests/lifecycle/bootstrap.spec 钉全仓 grep 私钥 pattern 零命中）。
 // 播种纪律：只在信任库文件尚不存在时播种一次——不与运维吊销对抗（remove 后不复活，G5 语义）。
 
-import { fsFace } from "../_lifecycle/atomic";
-import { createTrustStore } from "../_lifecycle/trust";
+import { fsFace } from "#/_platform/_lifecycle/atomic";
+import { createTrustStore } from "#/_platform/_lifecycle/trust";
 
 export interface BootstrapKey {
 	key_id: string

package/templates/src/oj-market/api/cdn/api.ts

@@ -0,0 +1,312 @@
+// CDN 上传端点（Phase A v4 §二）：签名推送 + pair 约束 + DB 目录真源写行。
+// POST /api/oj-market/cdn/upload?name=<file> —— 发布方（ojm market publish 远端模式）推
+// .tgz + .sig 旁车；不经账号口令（企微用户无障碍），签名鉴权 = X-OJM-Key-Id / X-OJM-Signature
+// 头 + 信任库 + Ed25519；无角色检查（信任库成员即发布身份）。
+//
+// 鉴权序（钉死）：① 验头（403 fail-fast：key 须在信任库，不消费 body）→ 限速（按 key_id）→
+// registry_id 解析（缺失 503）→ ② 消费 body（MAX_PACKAGE_BYTES 显式 413；反代 body cap 兜底）
+// → ③ 服务端从实收字节**重算 sha256** 重构 canonical `cdn-upload:<registry_id>:<name>:<sha256>`
+// 验签（换字节/跨站重放 → 401；不取 .sig 声明值——防签名-字节重绑）。站内重放（无 timestamp/
+// nonce）因内容哈希绑定退化为同字节幂等，无实害——不引入时间戳。
+//
+// 处理序（钉死）：查库比对（同 name+version：同字节 → 幂等 200 + 补缺文件〔自愈〕；异字节 →
+// 409 **不碰盘**，防「文件先被换、DB 后拒」的字节持久损坏）→ staging 解包抽 manifest（R1 三步
+// 范式 + REG-CS8 体积闸；manifest.name/version 与文件名逐字一致；summary/description 入库钳制）
+// → 原子落盘（tmp+rename）→ db.tx 写行（唯一键并发仲裁：撞键重读比对 sha256 定幂等/冲突）。
+// FS+DB 无同事务——db.tx 只包 DB 段；中断靠同字节重传自愈。任一步失败 CDN 零痕迹。
+//
+// name 所有权（v4 §一）：product → 首发 key_id 绑定不可改（C2-38 同源纪律）——既有行 key_id
+// 非 NULL 且不符 → 409；NULL（syncReleases 遗留）不建立所有权，首个上传采用并绑定；
+// 换主 = 站点 superadmin 操作（端点不提供）。
+//
+// 匿名面：config.yaml auth.anonymous_paths 增 /api/oj-market/cdn/upload（restart_pending
+// 冻结段，重启生效，发版说明提醒）。审计：发布成败落 market_history（action=publish，
+// operator = key_id）；验签前的请求（401/403/413/429/400 文件名）不是已知身份的发布行为，不留痕。
+
+import type { ExecFace } from "#/_platform/_lifecycle/steps/extract";
+import type { ParsedUploadFile } from "./shared";
+import type { SignedAuthEnv } from "./signed-auth";
+import { atomicWriteBytes, fsFace } from "#/_platform/_lifecycle/atomic";
+import { recordHistory } from "#/_platform/_lifecycle/history";
+import { MAX_PACKAGE_BYTES } from "#/_platform/_lifecycle/limits";
+
+import { manifestOfUpload } from "#/_platform/_lifecycle/manifest-of-upload";
+import { respond } from "#/_platform/_shared/respond";
+import { clampManifest, fail, packageCanonicalOf, parseSidecarSig, parseUploadFile } from "./shared";
+import { authenticateSignedKey, UPLOAD_RATE_LIMIT, verifyCanonicalSig } from "./signed-auth";
+
+// 既有引用面兼容（tests/lifecycle/cdn-upload.spec.ts 等从本文件取）
+export { UPLOAD_RATE_LIMIT };
+export type { SignedAuthEnv };
+
+/** 上传体积闸 = 分发包体积闸（单源 limits.ts，杜绝散落） */
+export const MAX_UPLOAD_BYTES = MAX_PACKAGE_BYTES;
+
+export interface CdnUploadEnv {
+	/** cdn/ 字节仓库目录（站点挂载的静态目录；暂存与任务不留其内——失败零可见痕迹） */
+	cdnDir: string
+	/** 上传暂存目录（解包抽 manifest；与安装器 staging 分离，防并发互踩） */
+	staging: string
+	/** 宿主信任库（.solutions/trusted-keys.yaml） */
+	trustPath: string
+	/** 本站点 registry 身份（canonical 首段 = 站点身份，防跨站重放）；缺省读 config vars.registry_id */
+	registryId?: string
+	/** 站点 config.yaml 路径（vars.registry_id 读取处；缺省 config.yaml） */
+	configPath?: string
+	/** 注入面（DIP）：缺省回落 isolate 全局 exec / crypto.sha256Hex / crypto.verifyEd25519 */
+	exec?: ExecFace
+	sha256Hex?: (data: Uint8Array) => string
+	verifyEd25519?: (publicKey: string, msg: string, sigBase64: string) => boolean
+	/** 当前时刻（epoch 秒；published_at/first_seen_at；测试注入，缺省 Date.now） */
+	now?: () => number
+}
+
+/** 生产缺省（全字段可注入覆盖，测试 stub 同款）；路径相对 fs jail 根（= config.yaml 所在目录） */
+export function cdnEnv(): CdnUploadEnv {
+	return {
+		cdnDir: "cdn",
+		staging: "modules/.staging-upload",
+		trustPath: ".solutions/trusted-keys.yaml",
+		configPath: "config.yaml",
+	};
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// ── 注入面缺省回落 ─────────────────────────────────────────────────────────────────────────
+function execOf(env: CdnUploadEnv): ExecFace {
+	const g = globalThis as { exec?: { run: ExecFace["run"] } };
+	return env.exec ?? { run: (argv, opts) => g.exec!.run(argv, opts) };
+}
+
+function sha256Of(env: CdnUploadEnv): (data: Uint8Array) => string {
+	const g = globalThis as { crypto?: { sha256Hex?: (data: Uint8Array) => string } };
+	return env.sha256Hex ?? ((data: Uint8Array) => g.crypto!.sha256Hex!(data));
+}
+
+function nowOf(env: CdnUploadEnv): number {
+	return env.now?.() ?? Math.floor(Date.now() / 1000);
+}
+
+/** 上传载荷字节（upload/api.ts 先例双路径：小文件字节在手，大文件已流式落 blob 须走 blob.get） */
+async function uploadBytes(): Promise<Uint8Array | null> {
+	const h = http as { files?: Array<{ key?: string }>, file?: (i: number) => Promise<Uint8Array> };
+	if (!Array.isArray(h.files) || h.files.length === 0)
+		return null;
+	const meta = h.files[0]!;
+	return meta.key ? await blob.get(meta.key) : await h.file!(0);
+}
+
+async function readFileOrNull(path: string): Promise<Uint8Array | null> {
+	try {
+		return await fsFace().readFile(path);
+	}
+	catch {
+		return null;
+	}
+}
+
+/** 幂等自愈：盘上缺失才补写（存在即不动——绝不改写既有字节） */
+async function healIfMissing(path: string, bytes: Uint8Array): Promise<void> {
+	if (await readFileOrNull(path) === null)
+		await atomicWriteBytes(path, bytes);
+}
+
+/** 发布审计（成败俱记 market_history；守卫式 insert，留痕失败不阻断主流程——history.ts 同语义） */
+async function auditPublish(row: { name: string, version: string, keyId: string, status: "success" | "failed", message: string }): Promise<void> {
+	await recordHistory({
+		solution: row.name,
+		version: row.version,
+		action: "publish",
+		status: row.status,
+		operator: row.keyId,
+		message: row.message,
+	});
+}
+
+// ── 主体 ────────────────────────────────────────────────────────────────────────────────────
+async function sigUploadBody(env: CdnUploadEnv, file: ParsedUploadFile, rawName: string, bytes: Uint8Array, sha256: string, keyId: string): Promise<Record<string, unknown>> {
+	const sigPath = `${env.cdnDir}/${rawName}`;
+	const existing = await readFileOrNull(sigPath);
+	if (existing !== null && sha256Of(env)(existing) === sha256) {
+		// 幂等重推留痕（minor M3）：重推不是发布动作，但发布留痕口径成败俱记——补一条 success 审计
+		await auditPublish({ name: file.name, version: file.version, keyId, status: "success", message: `幂等重推 .sig 旁车（${rawName} 内容未变，行未动）` });
+		return { ok: true, name: rawName, kind: "sig", sha256, idempotent: true };
+	}
+	parseSidecarSig(new TextDecoder().decode(bytes)); // 结构校验（400 人话分流）；内容列在 tgz pair 时从盘上旁车读取
+	// 已配对（market_release 行在）后禁止换签：pair 完整是已发布事实，签名与 tgz 绑定不可拆换
+	const paired = await db.table("market_release").select(["id"]).where({ field: "product", op: "eq", value: file.name }).where({ field: "version", op: "eq", value: file.version }).limit(1).all() as unknown[];
+	if (paired.length > 0 && existing !== null && sha256Of(env)(existing) !== sha256)
+		fail(409, `「${file.name}@${file.version}」的 .sig 已与 tgz 配对入库，不接受换签——请升 version 重发`);
+	await atomicWriteBytes(sigPath, bytes);
+	return { ok: true, name: rawName, kind: "sig", sha256 };
+}
+
+async function tgzUploadBody(env: CdnUploadEnv, file: ParsedUploadFile, rawName: string, bytes: Uint8Array, sha256: string, keyId: string): Promise<Record<string, unknown>> {
+	const tgzPath = `${env.cdnDir}/${rawName}`;
+	const sigPath = `${tgzPath}.sig`;
+
+	// pair 约束：sig 先 tgz 后——旁车缺失/损坏都不进解包
+	const sigBytes = await readFileOrNull(sigPath);
+	if (sigBytes === null)
+		fail(409, `pair 约束（sig 先 tgz 后）：请先上传 ${rawName}.sig 旁车，再推 ${rawName}——tgz 未配对不入库`);
+	const sig = parseSidecarSig(new TextDecoder().decode(sigBytes));
+	// pair 验签（终审 I2）：旁车必须与实收字节密码学绑定——受信 key 也可能作恶，预推
+	// 「形全实毒」旁车会让受害方 tgz 配对错签、该版本全部安装 fail-closed。验签在 pair
+	// 时做（sig 先行时 tgz 字节尚不存在，无法绑定）；包级 canonical 首段 = 旁车自带签发方
+	// 身份（跨站签发合法），与上传鉴权用的站点 canonical 是两串。
+	if (!verifyCanonicalSig(env, sig.public_key, packageCanonicalOf(sig.registry_id, file.name, file.version, sha256), sig.value)) {
+		await auditPublish({ name: file.name, version: file.version, keyId, status: "failed", message: "409 旁车验签失败：签名与实收字节不绑定" });
+		fail(409, `「${file.name}@${file.version}」的 .sig 旁车验签失败——签名与实收字节不绑定（cdn/ 若残留他人旁车，须站点 superadmin 清理后重推）`);
+	}
+	if (sig.key_id !== keyId) {
+		await auditPublish({ name: file.name, version: file.version, keyId, status: "failed", message: `409 旁车 key 不符：${sig.key_id} ≠ 推送身份 ${keyId}` });
+		fail(409, `「${file.name}@${file.version}」的 .sig 旁车 key_id「${sig.key_id}」与推送身份「${keyId}」不符——旁车与包体须同一把发布 key（一行一锚）`);
+	}
+
+	// ① 查库比对（不碰盘仲裁：异字节在此被拒，CDN 字节绝无被持久损坏的窗口）
+	const prior = (await db.table("market_release")
+		.select(["id", "sha256"])
+		.where({ field: "product", op: "eq", value: file.name })
+		.where({ field: "version", op: "eq", value: file.version })
+		.limit(1)
+		.all()) as Array<{ id: unknown, sha256: unknown }>;
+	if (prior.length > 0) {
+		if (String(prior[0]!.sha256) === sha256) {
+			// 同字节幂等 + 补缺文件自愈（sig 先行缺失也一并补）
+			await healIfMissing(tgzPath, bytes);
+			await healIfMissing(sigPath, sigBytes);
+			return { ok: true, name: file.name, version: file.version, sha256, size: bytes.byteLength, key_id: keyId, idempotent: true };
+		}
+		await auditPublish({ name: file.name, version: file.version, keyId, status: "failed", message: "409 异字节同版本：同一版本号只允许一份字节" });
+		fail(409, `「${file.name}@${file.version}」已存在且字节不一致——同一版本号只允许一份字节，请升 version 重发（确需覆盖须站点侧删行，superadmin 操作）`);
+	}
+
+	// ② name 所有权：既有行（key_id 非 NULL）锁定首发 key；NULL（遗留行）不建立所有权
+	const ownerRows = await db.table("market_release").select(["key_id"]).where({ field: "product", op: "eq", value: file.name }).limit(1).all() as Array<{ key_id: unknown }>;
+	const owner = ownerRows[0]?.key_id;
+	if (typeof owner === "string" && owner !== "" && owner !== keyId) {
+		await auditPublish({ name: file.name, version: file.version, keyId, status: "failed", message: `409 name 所有权：${file.name} 已由 ${owner} 首发绑定` });
+		fail(409, `name 所有权：「${file.name}」已由 key「${owner}」首发绑定，key「${keyId}」不得发布——换主 = 站点 superadmin 操作`);
+	}
+
+	// ③ staging 解包抽 manifest（查库后的第一碰盘动作；体积闸/zip-slip/坏包全在此拒）
+	const manifest = await manifestOfUpload({ stagingDir: env.staging, bytes, exec: execOf(env) });
+	const m = isObj(manifest) ? manifest : {};
+	if (m.name !== file.name || m.version !== file.version)
+		fail(400, `包内 manifest「${String(m.name)}@${String(m.version)}」与上传文件名「${file.name}@${file.version}」不一致——请核对分发包`);
+	const stored = clampManifest(m);
+
+	// ④ 原子落盘（tmp+rename；此后任一步失败尽力回收本方字节，绝不改写他人文件）
+	await atomicWriteBytes(tgzPath, bytes);
+	const now = nowOf(env);
+	try {
+		// ⑤ db.tx 写行（只包 DB 段；FS+DB 无同事务，中断靠同字节重传自愈）。
+		// 所有权复核在事务内重读（minor M1）：预检在事务外，两发布方并发首发同 product 的
+		// 竞态窗口（预检通过 → 他方先落行）只能由写事务内重读仲裁——SQLite 单写者序列化，
+		// 后入事务必见先提交行。
+		await db.tx(async (t) => {
+			const ownersNow = await t.table("market_release").select(["key_id"]).where({ field: "product", op: "eq", value: file.name }).limit(1).all() as Array<{ key_id: unknown }>;
+			const ownerNow = ownersNow[0]?.key_id;
+			if (typeof ownerNow === "string" && ownerNow !== "" && ownerNow !== keyId)
+				fail(409, `name 所有权：「${file.name}」已由 key「${ownerNow}」首发绑定（并发复核），key「${keyId}」不得发布——换主 = 站点 superadmin 操作`);
+			await t.table("market_release").insert({
+				product: file.name,
+				version: file.version,
+				key_id: keyId,
+				sha256,
+				size: bytes.byteLength,
+				published_at: now,
+				published_at_source: "upload",
+				yanked: 0,
+				first_seen_at: now,
+				sig_alg: sig.alg,
+				sig_value: sig.value,
+				sig_public_key: sig.public_key,
+				sig_registry_id: sig.registry_id,
+				manifest: JSON.stringify(stored),
+			}).run();
+		});
+	}
+	catch (e) {
+		// 唯一键并发仲裁：撞键 = 并发同版本上传先落一方——重读比对 sha256 定幂等/冲突。
+		// tx 内业务 fail（409 并发复核）也走此 catch：err.status 在，原样重抛（信封取 status）。
+		const status = (e as { status?: number }).status;
+		const again = (await db.table("market_release")
+			.select(["sha256"])
+			.where({ field: "product", op: "eq", value: file.name })
+			.where({ field: "version", op: "eq", value: file.version })
+			.limit(1)
+			.all()) as Array<{ sha256: unknown }>;
+		if (status === undefined && again.length > 0 && String(again[0]!.sha256) === sha256) {
+			await healIfMissing(tgzPath, bytes);
+			return { ok: true, name: file.name, version: file.version, sha256, size: bytes.byteLength, key_id: keyId, idempotent: true };
+		}
+		// 仲裁失败/业务拒绝：回收本方字节（盘上若已是他方字节则不动——按 sha256 判别）。
+		// minor M4：底层错误不原样上抛（SQL 文本泄进 500 信封）——人话出口，细节只进审计。
+		const onDisk = await readFileOrNull(tgzPath);
+		if (onDisk !== null && sha256Of(env)(onDisk) === sha256)
+			await fsFace().remove(tgzPath, { force: true }).catch(() => {});
+		if (typeof status === "number") {
+			await auditPublish({ name: file.name, version: file.version, keyId, status: "failed", message: `409 并发复核拒绝：${(e as Error).message}` });
+			throw e;
+		}
+		await auditPublish({ name: file.name, version: file.version, keyId, status: "failed", message: `写库失败/冲突：${String(e)}` });
+		fail(500, `「${file.name}@${file.version}」写库失败（已回收本次字节，cdn/ 无残留）——请重试；持续失败请站点 superadmin 查 market_history 审计明细`);
+	}
+	await auditPublish({ name: file.name, version: file.version, keyId, status: "success", message: `签名推送发布成功（${rawName}，${bytes.byteLength} 字节）` });
+	return { ok: true, name: file.name, version: file.version, sha256, size: bytes.byteLength, key_id: keyId };
+}
+
+async function uploadBody(env: CdnUploadEnv): Promise<Record<string, unknown>> {
+	const q = (http as { query?: Record<string, unknown> }).query ?? {};
+	const rawName = String(q.name ?? "").trim();
+	const file = parseUploadFile(rawName);
+	if (file === null)
+		fail(400, `文件名非法：「${rawName}」——须为 <name>-<version>.tgz 或其 .sig 旁车（name ^[a-z][a-z0-9-]{0,63}$ 全小写、版本数字开头）；路径逃逸/绝对路径/反斜杠/错扩展名一律拒`);
+
+	// ① 验面（403 fail-fast：信任库成员判定不消费 body）——共享序见 authenticateSignedKey
+	const { keyId, publicKey, registryId, signature } = await authenticateSignedKey(env, "cdn-upload");
+
+	// ② 消费 body（显式 413；反代 body cap 兜底是部署面责任）
+	const bytes = await uploadBytes();
+	if (bytes === null)
+		fail(400, "须随 multipart 上传文件字节（http.files）");
+	if (bytes.byteLength > MAX_UPLOAD_BYTES)
+		fail(413, `上传体积 ${bytes.byteLength} 字节超过上限 ${MAX_UPLOAD_BYTES}（与分发包体积闸同源）——请缩减包体；部署面请配反代 body cap 兜底`);
+
+	// ③ 服务端重算 sha256 重构 canonical 验签（硬约束：不取 .sig 声明值——防签名-字节重绑）
+	const sha256 = sha256Of(env)(bytes);
+	const canonical = `cdn-upload:${registryId}:${rawName}:${sha256}`;
+	if (!verifyCanonicalSig(env, publicKey, canonical, signature))
+		fail(401, "签名验签失败：服务端按实收字节重算 sha256 重构 canonical 验签——字节被换、registry 身份不符或签名无效，已拒（401）");
+
+	if (file.sig)
+		return await sigUploadBody(env, file, rawName, bytes, sha256, keyId);
+	return await tgzUploadBody(env, file, rawName, bytes, sha256, keyId);
+}
+
+/** 单端点组（oj 嵌套组：组名 = 路径段）→ POST /api/oj-market/cdn/upload */
+export function createCdnUploadApi(env: CdnUploadEnv) {
+	return {
+		upload: {
+			async post() {
+				await respond(async () => {
+					return await uploadBody(env);
+				});
+			},
+		},
+	};
+}
+
+const cdnUploadApi = createCdnUploadApi(cdnEnv());
+
+// 契约 I/O（schema-first，oj v0.1.72+）：入参对齐 query 收口（name 必填），出参宽松。
+cdnUploadApi.upload.post.schema = {
+	query: { type: "object", required: ["name"], properties: { name: { type: "string" } } },
+};
+cdnUploadApi.upload.post.response = { type: "object", additionalProperties: true };
+
+export default cdnUploadApi;

package/templates/src/oj-market/api/cdn/shared.ts

@@ -0,0 +1,104 @@
+// cdn 域共享非入口件（文件名白名单解析 / .sig 旁车五字段 / 入库钳制）：
+// api.ts 与 cdn/api.ts 都是路由入口（oj S 规则不可被模块内 import），回填（backfill.ts）
+// 与两端共用本文件，勿各写一遍（与 manifestOfUpload 同一管线纪律）。
+//
+// 为什么在这里而非 _platform：文件名/旁车/钳制的消费方全在 oj-market 模块内
+// （_platform 内核不经手发布文件名），归模块私有。
+
+import { isValidKeyId } from "#/_platform/_lifecycle/trust";
+
+// ── 文件名白名单（fail-closed：正则不匹配即 400/跳过，路径逃逸/绝对路径/反斜杠无处通过）──
+// name：C2-01（^[a-z][a-z0-9-]{0,63}$，全小写锚）；version：数字开头（semver 生态实况，
+// 左起首个「name 合法且版本段数字开头」的分割点为确定性解析）。
+const NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
+const VERSION_RE = /^\d[0-9A-Z.+-]{0,63}$/i;
+
+export interface ParsedUploadFile {
+	name: string
+	version: string
+	/** .sig 旁车 or .tgz 包体 */
+	sig: boolean
+}
+
+/** 文件名 → {name,version,sig}；不属于「<name>-<version>.tgz[.sig]」形态 → null */
+export function parseUploadFile(raw: string): ParsedUploadFile | null {
+	if (raw === "" || raw.length > 128 || raw.includes("/") || raw.includes("\\"))
+		return null;
+	const sig = raw.endsWith(".sig");
+	const base = sig ? raw.slice(0, -".sig".length) : raw;
+	if (!base.endsWith(".tgz"))
+		return null;
+	const stem = base.slice(0, -".tgz".length);
+	for (let i = stem.indexOf("-"); i !== -1; i = stem.indexOf("-", i + 1)) {
+		const name = stem.slice(0, i);
+		const version = stem.slice(i + 1);
+		if (NAME_RE.test(name) && VERSION_RE.test(version))
+			return { name, version, sig };
+	}
+	return null;
+}
+
+// ── .sig 旁车五字段（契约 §2.11 / C2-35，canon 恒 "v2"）───────────────────────────────────
+const PUBLIC_KEY_HEX = /^[0-9a-f]{64}$/;
+const SIG_B64 = /^[A-Z0-9+/]+={0,2}$/i;
+
+export interface SidecarSig {
+	alg: string
+	key_id: string
+	public_key: string
+	value: string
+	canon: string
+	/** 包级 canonical 首段（REG-CS3 签发方 registry 身份；install verify 重构规范串用，A5 增补落列） */
+	registry_id: string
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** 五字段结构校验（400 人话分流；加密学校验在 install verify 段——此处不重复） */
+export function parseSidecarSig(text: string): SidecarSig {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	}
+	catch (e) {
+		return fail(400, `.sig 旁车不是合法 JSON（${String(e)}）——应为 {alg,key_id,public_key,value,canon} 对象`);
+	}
+	if (!isObj(parsed))
+		fail(400, ".sig 旁车必须是 JSON 对象（{alg,key_id,public_key,value,canon}）");
+	const { alg, key_id: keyId, public_key: publicKey, value, canon, registry_id: registryId } = parsed;
+	if (alg !== "Ed25519")
+		fail(400, `.sig alg 须为 "Ed25519"，实为「${String(alg)}」`);
+	if (typeof keyId !== "string" || !isValidKeyId(keyId))
+		fail(400, `.sig key_id 非法（C2-37 <publisher>.<id>）：「${String(keyId)}」`);
+	if (typeof publicKey !== "string" || !PUBLIC_KEY_HEX.test(publicKey))
+		fail(400, `.sig public_key 须为 64 hex（Ed25519 32B raw）：「${typeof publicKey === "string" ? `${publicKey.slice(0, 16)}…` : String(publicKey)}」`);
+	if (typeof value !== "string" || value === "" || !SIG_B64.test(value))
+		fail(400, ".sig value 须为非空标准 base64 签名");
+	if (canon !== "v2")
+		fail(400, `.sig canon 须为 "v2"（canon_stale 一律拒），实为「${String(canon)}」`);
+	if (typeof registryId !== "string" || registryId === "")
+		fail(400, `.sig registry_id 须为非空字符串（REG-CS3 签发方身份）：「${String(registryId)}」`);
+	return { alg, key_id: keyId, public_key: publicKey, value, canon, registry_id: registryId };
+}
+
+/** 包级 canonical（REG-CS3 v2；与 packages/cli/src/lifecycle/sign.ts canonicalString 逐字一致——双端不可漂移） */
+export function packageCanonicalOf(registryId: string, name: string, version: string, sha256: string): string {
+	return `${registryId}:${name}@${version}:${sha256}`;
+}
+
+/** 入库钳制（catalog 展示字段）：summary ≤200 / description ≤2000 截断——全量 manifest 仍在包内 */
+export function clampManifest(m: Record<string, unknown>): Record<string, unknown> {
+	const out = { ...m };
+	if (typeof out.summary === "string" && out.summary.length > 200)
+		out.summary = out.summary.slice(0, 200);
+	if (typeof out.description === "string" && out.description.length > 2000)
+		out.description = out.description.slice(0, 2000);
+	return out;
+}
+
+/** 带 status 的可读失败（respond 收口成 json.fail，D14/B5 同通道） */
+export function fail(status: number, msg: string): never {
+	throw Object.assign(new Error(msg), { status });
+}