@oj-module/cli 0.2.69 → 0.2.71

package/src/market/publish.ts

@@ -1,12 +1,13 @@
 /**
- * `ojm market publish`（T3）：把方案包落进 CDN 目录。
+ * 市场发布包构建（A6 重构）：buildSignedPackage = 合成/构建 + 确定性 tgz + 包级 detached 签名，
+ * 产出**内存字节**（不落 CDN）——本地落盘（publishPackage）与远端推送（remote-push.ts）
+ * 共用同一构建面（DRY：签名/打包一行不重复）。
  *
- * 职责收窄到「落包 + 包级签名」（D-1）——**不碰索引**，索引由 `build-index` 扫描重建。
- * 由此多人可并发发布：每人只写 `<name>-<version>.tgz`（名字含名+版本，天然不撞），
- * 没有共享可变索引文件，也就没有 TOCTOU。
+ * 本地落盘模式（publishPackage）仍保留：walkthrough/trial 的隔离站点需要 cdn/ 字节 +
+ * DB 目录行双写（内部通道）；CLI 命令层 `ojm market publish` 缺省走远端推送。
  *
- * 签名原语一行都不重写：11 复用 `ojm sign` 的 `signCommand`（规范串 `<name>@<version>:<sha256>`，
- * detached `.tgz.sig` 五字段，与 Form B archive.signature 同源同构）。
+ * 签名原语一行都不重写：11 复用 `ojm sign` 的 `signCommand`（规范串 `<registry_id>:<name>@<version>:<sha256>`，
+ * detached `.tgz.sig` 六字段，与 Form B archive.signature 同源同构）。
  */
 
 import { createHash } from "node:crypto";
@@ -17,6 +18,8 @@ import process from "node:process";
 
 import { buildBundle } from "../bundle";
 import { createDeterministicTgz } from "../deterministic-tar";
+import { isValidKeyId } from "../keygen";
+import { readPrivateKeyPem } from "../lifecycle/keygen";
 import { assertDefaultModulesUntouched } from "../scaffold-guard";
 import { signCommand } from "../sign";
 import { resolveCdnLayout } from "./cdn-layout";
@@ -25,7 +28,7 @@ import { buildFixturePackage, parseFixtureSpec } from "./fixture";
 export interface MarketPublishOptions {
 	/** 站点工程根（含 api/config.yaml 与 cdn/）；缺省 process.cwd() */
 	projectRoot?: string
-	/** `--fixture <name>@<version>`；缺省 demo-solution@0.1.0 */
+	/** `--fixture <name@version>`；缺省 demo-solution@0.1.0 */
 	fixture?: string
 	/** `--real <方案工程根>`：走 ojm build --bundle 真构建（替代 fixture） */
 	real?: string
@@ -35,77 +38,97 @@ export interface MarketPublishOptions {
 	key?: string
 	/** 内存私钥 PEM（一次性/隔离场景，不落盘） */
 	privateKeyPem?: string
-	/** 落包后离线自检（verifyCanonical 复核包级签名） */
-	check?: boolean
 	/** 签发方 registry 身份（REG-CS3 v2 防跨仓库重放；透传 signCommand --registry-id） */
 	registryId?: string
-	/** 命令层是否紧接着重建索引（仅用于措辞：true 时不打印「索引未重建」） */
-	rebuildIndex?: boolean
+	/** 落包后离线自检（verifyCanonical 复核包级签名） */
+	check?: boolean
 }
 
-export interface MarketPublishResult {
+/** 已签名发布包（内存字节态；落盘/推送由调用方决定） */
+export interface SignedPackage {
 	name: string
 	version: string
-	tgzPath: string
-	sigPath: string
+	tgzBytes: Uint8Array
+	/** tgz 字节 sha256（内容寻址；上传 canonical 与 Form B archive.sha256 同源） */
 	sha256: string
 	size: number
-	canonical: string
+	/** 包级 detached 签名（六字段，与 .tgz.sig 旁车文件内容一致） */
+	sig: Record<string, unknown>
+	sigBytes: Uint8Array
 	keyId: string
 	publicKeyHex: string
 	fingerprint: string
+	/** 包级 canonical（`<registry_id>:<name>@<version>:<sha256>`） */
+	canonical: string
+	/** 本次签名用私钥（远端推送构造上传 canonical 要用；内存态不落盘纪律不变） */
+	privateKeyPem: string
 }
 
-export async function publishPackage(opts: MarketPublishOptions = {}): Promise<MarketPublishResult> {
-	const projectRoot = opts.projectRoot ?? process.cwd();
-	const layout = resolveCdnLayout(projectRoot);
-	if (!fs.existsSync(layout.dir)) {
-		fs.mkdirSync(layout.dir, { recursive: true });
-		console.log(`[ojm] 已建立 CDN 目录 ${path.relative(projectRoot, layout.dir)}`);
+/**
+ * 解析签名身份（内存 PEM > --key 显式文件 > ~/.ojm/keys/<id>/private.pem）。
+ * 与 sign.ts signCommand 同源规则；独立抽出是因为推送路径不经 signCommand 也要签
+ * 上传 canonical（`cdn-upload:<站点 registry>:<file>:<sha256>`）——同一身份两把签名。
+ */
+export function resolveSigningIdentity(opts: { id?: string, key?: string, privateKeyPem?: string, cwd?: string }): { keyId: string, privateKeyPem: string } {
+	const cwd = opts.cwd ?? process.cwd();
+	if (opts.privateKeyPem !== undefined && opts.privateKeyPem !== "") {
+		const keyId = opts.id ?? "";
+		if (keyId === "")
+			throw new Error("[ojm] 使用内存私钥时须同时给 --id <publisher.id>（.sig 的发布方标识；C2-37 命名空间）");
+		if (!isValidKeyId(keyId))
+			throw new Error(`[ojm] key_id 命名空间非法（C2-37）：「${keyId}」`);
+		return { keyId, privateKeyPem: opts.privateKeyPem };
+	}
+	let keyFile: string;
+	let keyId: string;
+	if (opts.key !== undefined) {
+		keyFile = path.resolve(cwd, opts.key);
+		const m = /[/\\]\.ojm[/\\]keys[/\\]([^/\\]+)[/\\]private\.pem$/.exec(keyFile);
+		keyId = opts.id ?? m?.[1] ?? "";
+		if (keyId === "")
+			throw new Error("[ojm] --key 指向自定义位置时须同时给 --id <publisher.id>（.sig 的发布方标识；C2-37 命名空间）");
 	}
+	else {
+		keyId = opts.id ?? "";
+		if (keyId === "")
+			throw new Error("[ojm] 缺少签名身份：--id <publisher.id>（从 ~/.ojm/keys/<id>/ 取私钥）或 --key <pem> --id <publisher.id>。先生成：ojm keygen --id <publisher.id>");
+		keyFile = path.join(os.homedir(), ".ojm", "keys", keyId, "private.pem");
+	}
+	if (!isValidKeyId(keyId))
+		throw new Error(`[ojm] key_id 命名空间非法（C2-37）：「${keyId}」`);
+	if (!fs.existsSync(keyFile))
+		throw new Error(`[ojm] 私钥文件不存在：${keyFile}（用 ojm keygen --id ${keyId} 生成，或 --key 指定）`);
+	return { keyId, privateKeyPem: readPrivateKeyPem(keyFile) };
+}
 
-	const staging = mkdtempSync(path.join(os.tmpdir(), "ojm-market-publish-"));
+/** 构建 + 包级签名（staging 内完成，staging 自清理；产出内存字节） */
+export async function buildSignedPackage(opts: MarketPublishOptions = {}): Promise<SignedPackage> {
+	const staging = mkdtempSync(path.join(os.tmpdir(), "ojm-market-build-"));
 	try {
-		const { name, version, tgzPath, sha256, preExisted } = opts.real !== undefined
-			? await buildRealPackage(opts.real, staging, layout.dir)
-			: await buildFixture({ fixture: opts.fixture, staging, cdnDir: layout.dir });
-
-		// 原子性：tgz 已落盘而后续环节失败时，新包必须捡回来，不留半成品
-		const rollbackPackage = () => {
-			if (!preExisted)
-				rmSync(tgzPath, { force: true });
-		};
-
-		let signed: ReturnType<typeof signCommand>;
-		try {
-			signed = signCommand(tgzPath, { id: opts.id, key: opts.key, privateKeyPem: opts.privateKeyPem, check: opts.check, registryId: opts.registryId });
-		}
-		catch (error) {
-			rollbackPackage();
-			throw error;
-		}
-		if (signed.checkPassed === false) {
-			rollbackPackage();
-			throw new Error(`[ojm] 包级签名自检失败，已移除未签通的包：${tgzPath}`);
-		}
-		const size = fs.statSync(tgzPath).size;
-		console.log(`[ojm] 包已落 CDN → ${path.relative(projectRoot, tgzPath)}（${size} 字节）`);
-		console.log(`[ojm] 发布方 ${signed.keyId}；指纹 ${signed.fingerprint}`);
-		// 带了 --rebuild-index 时由命令层紧接着重建索引，这里不能再报「未重建」（否则前后两句自相矛盾）
-		if (opts.rebuildIndex !== true)
-			console.log("[ojm] 索引未重建：多人场景请由维护者跑 ojm market build-index");
+		const identity = resolveSigningIdentity({ id: opts.id, key: opts.key, privateKeyPem: opts.privateKeyPem, cwd: opts.projectRoot });
+		const { name, version, tgzPath, sha256 } = opts.real !== undefined
+			? await buildRealPackage(opts.real, staging)
+			: await buildFixture({ fixture: opts.fixture, staging });
 
+		const signed = signCommand(tgzPath, { id: identity.keyId, privateKeyPem: identity.privateKeyPem, check: opts.check, registryId: opts.registryId });
+		if (signed.checkPassed === false)
+			throw new Error("[ojm] 包级签名自检失败，已丢弃未签通的包");
+		const tgzBytes = new Uint8Array(fs.readFileSync(tgzPath));
+		const sigBytes = new Uint8Array(fs.readFileSync(signed.sigPath));
+		const sig = JSON.parse(new TextDecoder().decode(sigBytes)) as Record<string, unknown>;
 		return {
 			name,
 			version,
-			tgzPath,
-			sigPath: signed.sigPath,
+			tgzBytes,
 			sha256,
-			size,
-			canonical: signed.canonical,
+			size: tgzBytes.byteLength,
+			sig,
+			sigBytes,
 			keyId: signed.keyId,
 			publicKeyHex: signed.publicKeyHex,
 			fingerprint: signed.fingerprint,
+			canonical: signed.canonical,
+			privateKeyPem: identity.privateKeyPem,
 		};
 	}
 	finally {
@@ -113,61 +136,94 @@ export async function publishPackage(opts: MarketPublishOptions = {}): Promise<M
 	}
 }
 
-/** fixture 路径：合成 → 确定性打包 → 与既有同名版本比对 */
-async function buildFixture(args: { fixture?: string, staging: string, cdnDir: string }): Promise<{ name: string, version: string, tgzPath: string, sha256: string, preExisted: boolean }> {
-	const spec = parseFixtureSpec(args.fixture);
-	const pkg = buildFixturePackage({ stagingDir: args.staging, name: spec.name, version: spec.version });
-	const tgzPath = path.join(args.cdnDir, `${spec.name}-${spec.version}.tgz`);
+export interface MarketPublishResult {
+	name: string
+	version: string
+	tgzPath: string
+	sigPath: string
+	sha256: string
+	size: number
+	canonical: string
+	keyId: string
+	publicKeyHex: string
+	fingerprint: string
+}
+
+/**
+ * 本地落盘模式：把已签名包写进 cdn/（内部通道——walkthrough/trial 隔离站点用；
+ * CLI 命令层 publish 缺省走远端推送，本地-only 发布模式已退役）。
+ * 多人可并发：每人只写 `<name>-<version>.tgz`（名字含名+版本，天然不撞）。
+ */
+export async function publishPackage(opts: MarketPublishOptions = {}): Promise<MarketPublishResult> {
+	const projectRoot = opts.projectRoot ?? process.cwd();
+	const layout = resolveCdnLayout(projectRoot);
+	if (!fs.existsSync(layout.dir)) {
+		fs.mkdirSync(layout.dir, { recursive: true });
+		console.log(`[ojm] 已建立 CDN 目录 ${path.relative(projectRoot, layout.dir)}`);
+	}
+	const built = await buildSignedPackage(opts);
+
+	const tgzPath = path.join(layout.dir, `${built.name}-${built.version}.tgz`);
+	const sigPath = `${tgzPath}.sig`;
 	const before = captureExisting(tgzPath);
+	// 同 name@version 重发：字节一致即幂等；字节不一致是真正的冲突——同一版本号出现两份
+	// 不同的包会毁掉内容寻址前提，必须升 version 重发
+	if (before.exists && before.sha256 !== built.sha256) {
+		throw new Error(
+			`[ojm] 包冲突：${built.name}@${built.version} 已存在且字节不一致（${before.sha256.slice(0, 12)} vs ${built.sha256.slice(0, 12)}）。\n`
+			+ "下一步：内容有变更请升 version 后重发（同一版本号只允许一份字节）；"
+			+ "确需覆盖请先删除 CDN 目录里的旧 tgz。",
+		);
+	}
+	fs.writeFileSync(tgzPath, built.tgzBytes);
+	fs.writeFileSync(sigPath, built.sigBytes);
+	console.log(`[ojm] 包已落 CDN → ${path.relative(projectRoot, tgzPath)}（${built.size} 字节）`);
+	console.log(`[ojm] 发布方 ${built.keyId}；指纹 ${built.fingerprint}`);
+
+	return {
+		name: built.name,
+		version: built.version,
+		tgzPath,
+		sigPath,
+		sha256: built.sha256,
+		size: built.size,
+		canonical: built.canonical,
+		keyId: built.keyId,
+		publicKeyHex: built.publicKeyHex,
+		fingerprint: built.fingerprint,
+	};
+}
 
+/** fixture 路径：合成 → 确定性打包（staging 内） */
+async function buildFixture(args: { fixture?: string, staging: string }): Promise<{ name: string, version: string, tgzPath: string, sha256: string }> {
+	const spec = parseFixtureSpec(args.fixture);
+	const pkg = buildFixturePackage({ stagingDir: args.staging, name: spec.name, version: spec.version });
+	const tgzPath = path.join(args.staging, `${spec.name}-${spec.version}.tgz`);
 	const sha256 = await createDeterministicTgz(pkg.dir, tgzPath);
-	assertNoByteConflict(tgzPath, before, spec);
-	return { name: spec.name, version: spec.version, tgzPath, sha256, preExisted: before.exists };
+	return { name: spec.name, version: spec.version, tgzPath, sha256 };
 }
 
-/** `--real`：走既有 ojm build --bundle，产物搬到 CDN 目录（一次只发一份：多方案工程请显式指定） */
-async function buildRealPackage(solutionRoot: string, staging: string, cdnDir: string): Promise<{ name: string, version: string, tgzPath: string, sha256: string, preExisted: boolean }> {
+/** `--real`：走既有 ojm build --bundle，产物归拢 staging（一次只发一份：多方案工程请显式指定） */
+async function buildRealPackage(solutionRoot: string, staging: string): Promise<{ name: string, version: string, tgzPath: string, sha256: string }> {
 	// 与 ojm build 同一道完整性门禁：发布链路同样不许携带被改过的默认模块
 	assertDefaultModulesUntouched(solutionRoot);
 	const builtList = await buildBundle(solutionRoot, { out: staging });
 	if (builtList.length !== 1) {
 		throw new Error(
 			`[ojm] market publish --real 一次只发布一份方案，但该工程打出了 ${builtList.length} 份用户方案。`
-			+ "请改用显式链路：在方案工程里 `ojm build --bundle <name>`，再 `ojm sign dist/<name>-<version>.tgz --id <publisher>.<key>`，"
-			+ "把 tgz + .sig 放进 cdn/ 后 `ojm market build-index`。",
+			+ "请改用显式链路：在方案工程里 `ojm build --bundle <name>`，再 `ojm sign dist/<name>-<version>.tgz --id <publisher>.<key>`。",
 		);
 	}
 	const built = builtList[0]!;
-	const tgzPath = path.join(cdnDir, `${built.name}-${built.version}.tgz`);
-	const before = captureExisting(tgzPath);
-
+	const tgzPath = path.join(staging, `${built.name}-${built.version}.tgz`);
 	fs.copyFileSync(built.tgz, tgzPath);
-	assertNoByteConflict(tgzPath, before, { name: built.name, version: built.version });
-	return { name: built.name, version: built.version, tgzPath, sha256: built.sha256, preExisted: before.exists };
+	return { name: built.name, version: built.version, tgzPath, sha256: built.sha256 };
 }
 
-/** 落包前先记下同名文件的指纹（可能不存在） */
+/** 落包前记下同名文件的指纹（可能不存在） */
 function captureExisting(tgzPath: string): { exists: boolean, sha256: string } {
 	if (!fs.existsSync(tgzPath))
 		return { exists: false, sha256: "" };
 	const bytes = new Uint8Array(fs.readFileSync(tgzPath));
 	return { exists: true, sha256: createHash("sha256").update(bytes).digest("hex") };
 }
-
-/**
- * 同 name@version 重发：字节一致即幂等；字节不一致是真正的冲突——
- * 同一个版本号出现两份不同的包会毁掉内容寻址前提，必须升 version 重发。
- */
-function assertNoByteConflict(tgzPath: string, before: { exists: boolean, sha256: string }, spec: { name: string, version: string }): void {
-	if (!before.exists)
-		return;
-	const bytes = new Uint8Array(fs.readFileSync(tgzPath));
-	const after = createHash("sha256").update(bytes).digest("hex");
-	if (after === before.sha256)
-		return;
-	throw new Error(
-		`[ojm] 包冲突：${spec.name}@${spec.version} 已存在且字节不一致（${before.sha256.slice(0, 12)} vs ${after.slice(0, 12)}）。\n`
-		+ "下一步：内容有变更请升 version 后重发（同一版本号只允许一份字节）；"
-		+ "确需覆盖请先删除 CDN 目录里的旧 tgz。",
-	);
-}

package/src/market/remote-push.ts

@@ -0,0 +1,236 @@
+/**
+ * 市场远端推送（A6，计划 v4 §五）：`ojm market publish` 缺省链路。
+ *
+ * 远端 = oj 模板站点（纯站点无 ojm CLI）：签名制推送（不经账号口令；企微用户无障碍）——
+ * X-OJM-Key-Id / X-OJM-Signature 头 + 站点信任库 + Ed25519，canonical 由**站点**从实收字节
+ * 重算 sha256 重构（`cdn-upload:<站点 registry_id>:<file>:<sha256>`）——换字节即 401。
+ *
+ * 顺序（pair 约束，钉死）：先推 `.sig` 旁车再推 `.tgz`——服务端 tgz 未配对不入库（409）。
+ * 半成功（sig 已推、tgz 被拒）：报错文案带「重跑本命令幂等补齐」——同字节重传幂等（服务端
+ * 查库仲裁），无人工清场负担。退出码 1 由命令层置（本库以抛错表达失败）。
+ *
+ * 站点身份发现：推送前先 GET catalog（匿名）——响应顶层 registry_id（A6 新增发现面）；
+ * 同请求兼作 2×2 兼容矩阵探测：旧站点无 catalog API → 404 → 「站点版本过旧」人话。
+ */
+
+import type { MarketPublishOptions } from "./publish";
+import { createHash } from "node:crypto";
+
+import process from "node:process";
+import { signCanonical } from "../lifecycle/sign";
+import { unwrapEnvelope } from "../site";
+import { buildSignedPackage, resolveSigningIdentity } from "./publish";
+
+/** 站点目录探测结果（catalog 响应顶层字段） */
+export interface MarketDiscovery {
+	apiVersion: string | null
+	/** 站点身份（= 上传/yank canonical 首段）；缺失在发现期即人话拒，故此后恒非空 */
+	registryId: string
+}
+
+/** 去掉尾斜杠的站点基址（env 回落与 resolveSite 同序：flag > OJM_SITE_URL） */
+export function resolvePushTarget(siteUrl?: string): string {
+	const base = (siteUrl ?? process.env.OJM_SITE_URL ?? "").replace(/\/+$/, "");
+	if (base === "")
+		throw new Error("[ojm] 远端发布须指定目标站点：--site-url <https://your-site>（或环境变量 OJM_SITE_URL）");
+	return base;
+}
+
+/**
+ * GET /api/oj-market/catalog 探测（page=1&size=1 最小请求）：发现 registry_id +
+ * 旧站点人话分流（404 → 「站点版本过旧」+ 迁移指向；网络层失败 → 人话不抛原生错）。
+ */
+export async function discoverMarket(fetchFn: typeof fetch, base: string): Promise<MarketDiscovery> {
+	let res: Response;
+	try {
+		res = await fetchFn(`${base}/api/oj-market/catalog?page=1&size=1`, { method: "GET" });
+	}
+	catch (error) {
+		throw new Error(`[ojm] 连不上站点 ${base}（${(error as Error).message}）——核对 --site-url / 网络后重试`);
+	}
+	if (res.status === 404)
+		throw new Error(`[ojm] 站点 ${base} 版本过旧（无 /api/oj-market/catalog 目录 API）——目标站点须先升级到 DB 目录版本；迁移指南见 docs/migration/ 市场远程发布篇`);
+	if (!res.ok)
+		throw new Error(`[ojm] 站点目录探测被拒（HTTP ${res.status}）——匿名可读端点不应要求凭据，核对站点配置`);
+	const raw = await res.json() as { code?: number, data?: unknown };
+	// 站点统一信封 {code,msg,data}（AC-D16）；匿名读端点 code!==0 时按无目录处理
+	if (typeof raw.code === "number" && raw.code !== 0)
+		throw new Error(`[ojm] 站点目录探测失败（code=${raw.code}）——目标站点须为 DB 目录版本；迁移指南见 docs/migration/ 市场远程发布篇`);
+	const body = (typeof raw.code === "number" ? raw.data : raw) as { api_version?: unknown, registry_id?: unknown };
+	const registryId = typeof body.registry_id === "string" && body.registry_id !== "" ? body.registry_id : null;
+	if (registryId === null)
+		throw new Error(`[ojm] 站点 ${base} 未配置 registry_id（签名推送 canonical 首段 = 站点身份）——请站点管理员在 config.yaml vars 增加 registry_id 后重试`);
+	return { apiVersion: typeof body.api_version === "string" ? body.api_version : null, registryId };
+}
+
+/** 推送失败：带阶段（sig/tgz）与 HTTP 语义的人话错（命令层据此置 exitCode 1） */
+export class RemotePushError extends Error {
+	constructor(
+		public readonly stage: "sig" | "tgz",
+		public readonly status: number,
+		message: string,
+	) {
+		super(message);
+		this.name = "RemotePushError";
+	}
+}
+
+/**
+ * 单文件签名推送：canonical `cdn-upload:<站点 registry_id>:<文件名>:<实收字节 sha256>`
+ * 由发布方私钥签名（与服务端重算口径逐字一致——本函数按同一公式构造）。
+ */
+async function pushSignedFile(
+	fetchFn: typeof fetch,
+	base: string,
+	registryId: string,
+	fileName: string,
+	bytes: Uint8Array,
+	keyId: string,
+	privateKeyPem: string,
+): Promise<unknown> {
+	const sha256 = createHash("sha256").update(bytes).digest("hex");
+	const signature = signCanonical(privateKeyPem, `cdn-upload:${registryId}:${fileName}:${sha256}`);
+	const form = new FormData();
+	form.append("file", new Blob([bytes.slice()]), fileName);
+	const res = await fetchFn(`${base}/api/oj-market/cdn/upload?name=${encodeURIComponent(fileName)}`, {
+		method: "POST",
+		headers: { "x-ojm-key-id": keyId, "x-ojm-signature": signature },
+		body: form,
+	});
+	// unwrapEnvelope 的人话已含服务端指引（403 附 trust add、409 附升 version 指引）；
+	// 这里包阶段上下文 + 下一步（错误文案数据表面）
+	const text = await res.text();
+	let env: { code?: number, msg?: string } | null = null;
+	try {
+		env = JSON.parse(text) as { code?: number, msg?: string };
+	}
+	catch {}
+	const status = res.status;
+	if (!res.ok || (typeof env?.code === "number" && env.code !== 0)) {
+		const msg = env?.msg ?? text.slice(0, 200);
+		throw new RemotePushError(fileName.endsWith(".sig") ? "sig" : "tgz", status, `[ojm] 推送 ${fileName} 被拒（HTTP ${res.status}）：${msg}`);
+	}
+	return env?.code === 0 ? (env as { data?: unknown }).data : env;
+}
+
+export interface RemotePublishOptions extends MarketPublishOptions {
+	/** 目标站点基址（缺省 OJM_SITE_URL；无则人话报错——不猜默认站点） */
+	siteUrl?: string
+	/** 测试注入 fetch；缺省全局 fetch */
+	fetchFn?: typeof fetch
+	/** 日志旁路（测试收集用） */
+	onLog?: (line: string) => void
+}
+
+export interface RemotePublishResult {
+	name: string
+	version: string
+	sha256: string
+	size: number
+	keyId: string
+	fingerprint: string
+	/** 站点身份（= 上传 canonical 首段） */
+	registryId: string
+	siteUrl: string
+}
+
+/**
+ * 远端发布主链：构建 + 包级签名（buildSignedPackage）→ catalog 探测（registry_id）→
+ * sig→tgz 顺序推送。半成功（sig 成 tgz 败）时错误文案追加「重跑本命令幂等补齐」。
+ */
+export async function remotePublish(opts: RemotePublishOptions = {}): Promise<RemotePublishResult> {
+	const log = opts.onLog ?? ((line: string) => console.log(line));
+	const base = resolvePushTarget(opts.siteUrl);
+	const fetchFn = opts.fetchFn ?? fetch;
+
+	log(`[ojm] 远端发布目标 ${base}：构建发布包…`);
+	const built = await buildSignedPackage(opts);
+	log(`[ojm] 包已构建并签名：${built.name}@${built.version}（${built.size} 字节，发布方 ${built.keyId}）`);
+
+	const discovery = await discoverMarket(fetchFn, base);
+	log(`[ojm] 站点目录就绪（api_version ${discovery.apiVersion ?? "?"}，registry_id ${discovery.registryId}）——先推 .sig 旁车`);
+
+	let sigPushed = false;
+	try {
+		await pushSignedFile(fetchFn, base, discovery.registryId, `${built.name}-${built.version}.tgz.sig`, built.sigBytes, built.keyId, built.privateKeyPem);
+		sigPushed = true;
+		log(`[ojm] .sig 旁车已推送（key_id ${built.keyId}）`);
+		await pushSignedFile(fetchFn, base, discovery.registryId, `${built.name}-${built.version}.tgz`, built.tgzBytes, built.keyId, built.privateKeyPem);
+	}
+	catch (error) {
+		// 半成功：sig 已落、tgz 未至——服务端 pair 约束下重跑本命令同字节幂等补齐，无清场负担
+		if (sigPushed && error instanceof RemotePushError && error.stage === "tgz")
+			throw new RemotePushError(error.stage, error.status, `${error.message}\n[ojm] .sig 旁车已推送成功——重跑本命令幂等补齐（同字节重传幂等，pair 自动完成）`);
+		throw error;
+	}
+	log(`[ojm] 发布完成：${built.name}@${built.version} 已进 ${base} 市场目录（DB 目录行 + cdn/ 字节）`);
+
+	return {
+		name: built.name,
+		version: built.version,
+		sha256: built.sha256,
+		size: built.size,
+		keyId: built.keyId,
+		fingerprint: built.fingerprint,
+		registryId: discovery.registryId,
+		siteUrl: base,
+	};
+}
+
+export interface RemoteYankOptions {
+	/** 目标站点基址（缺省 OJM_SITE_URL） */
+	siteUrl?: string
+	/** 方案名（product） */
+	name: string
+	/** 版本 */
+	version: string
+	/** 恢复（unyank）；缺省 = 下线 */
+	restore?: boolean
+	/** 下线原因（审计留痕；可选） */
+	reason?: string
+	/** 操作人（审计留痕；缺省由站点记 key_id） */
+	by?: string
+	id?: string
+	key?: string
+	privateKeyPem?: string
+	/** 测试注入 fetch；缺省全局 fetch */
+	fetchFn?: typeof fetch
+}
+
+export interface RemoteYankResult {
+	product: string
+	version: string
+	yanked: boolean
+	idempotent: boolean
+}
+
+/**
+ * 远端 yank（计划 v4 §五）：POST /api/oj-market/yank，canonical
+ * `market-yank:<站点 registry_id>:<product>:<version>`（无内容哈希——重放退化为幂等，
+ * 与服务端口径一致）。仅发布者本人可下线/恢复（服务端按行 key_id 授权，不符 403）。
+ */
+export async function remoteYank(opts: RemoteYankOptions): Promise<RemoteYankResult> {
+	const base = resolvePushTarget(opts.siteUrl);
+	const fetchFn = opts.fetchFn ?? fetch;
+	const discovery = await discoverMarket(fetchFn, base);
+	const { keyId, privateKeyPem } = resolveSigningIdentity({ id: opts.id, key: opts.key, privateKeyPem: opts.privateKeyPem });
+	const signature = signCanonical(privateKeyPem, `market-yank:${discovery.registryId}:${opts.name}:${opts.version}`);
+	const res = await fetchFn(`${base}/api/oj-market/yank`, {
+		method: "POST",
+		headers: { "content-type": "application/json", "x-ojm-key-id": keyId, "x-ojm-signature": signature },
+		body: JSON.stringify({
+			product: opts.name,
+			version: opts.version,
+			...(opts.restore === true ? { restore: true } : {}),
+			...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+			...(opts.by !== undefined ? { by: opts.by } : {}),
+		}),
+	});
+	const data = await unwrapEnvelope(res) as { product?: string, version?: string, yanked?: boolean, idempotent?: boolean };
+	return {
+		product: String(data.product ?? opts.name),
+		version: String(data.version ?? opts.version),
+		yanked: data.yanked === true,
+		idempotent: data.idempotent === true,
+	};
+}

package/src/market/trial.ts

@@ -68,7 +68,7 @@ export async function trialInstall(opts: TrialOptions = {}): Promise<TrialResult
 		if (task.status === "needs_trust") {
 			const fingerprint = task.trust?.fingerprint ?? "";
 			log(`[ojm] 待信任发布方 ${task.trust?.key_id ?? "?"}，指纹 ${fingerprint.slice(0, 16)}…（隔离站点，自动确认）`);
-			await callApi(fetch, site.baseUrl, token, "POST", "/api/_platform/market/trust", { task_id: task.id });
+			await callApi(fetch, site.baseUrl, token, "POST", "/api/oj-market/trust", { task_id: task.id });
 			task = await installOnce(site.baseUrl, token, spec.name, spec.version);
 		}
 
@@ -86,7 +86,7 @@ export async function trialInstall(opts: TrialOptions = {}): Promise<TrialResult
 /** 一次安装 + 轮询到终态 */
 async function installOnce(base: string, token: string, name: string, version: string): Promise<TaskRecord> {
 	// 站点返回 {task_id}（安装同步跑完后回填）；mock 兼容 id 形态
-	const started = await callApi<{ task_id?: string, id?: string }>(fetch, base, token, "POST", "/api/_platform/market/install", {
+	const started = await callApi<{ task_id?: string, id?: string }>(fetch, base, token, "POST", "/api/oj-market/install", {
 		name,
 		version,
 		source: "cdn",