@oj-module/cli 0.2.2 → 0.2.6

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

@@ -0,0 +1,228 @@
+import type { FetchInitFace } from "../_shared/site-facade";
+// 深检后端四项（P2-7，C2-42）+ SSRF 防护钉（R9 纪律：全程不触 exec，迁移账本走 db.query + journalHeadOf）。
+// 职责（ISP）：纯 diff 函数（diffPermRows/diffSettingRows/diffLedger/diffWebIntegrity）与 I/O 探针
+// （verifyRouteReachability）分离；端点只编排取参 + 调四项 + 组装 checks（报告结构/persist/trust 项归 P2-8）。
+// 设值永不进 checks（subject 只报 key/path/code；secret 同只报 key）——「看得见但不知怎么做」即不合格。
+import { fsFace } from "./atomic";
+import { createStateStore } from "./state";
+
+export { sha384B64 } from "./sha384";
+
+/** 深检项（契约 §2.13 item 结构） */
+export interface VerifyItem {
+	id: string
+	severity: "error" | "warn" | "info"
+	subject: string
+	advise_key: string
+}
+
+/** 线格式路由行（与 solutions/api.ts 的 SolutionRouteRow 同构，避免循环依赖在此定义） */
+export interface SolutionRouteRow {
+	path: string
+	module: string
+	category: "main" | "admin" | "hidden"
+	order: number
+	title_key: string | null
+	required_permission: string | null
+	enabled: boolean
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * SSRF 钉①：探测 URL 永不出站——拒绝 scheme:// 与协议相对 //，要求站点相对路径（以单 / 起）；
+ * 绝对化用请求源（siteOrigin）补全，确保探针永不指向本站之外的主机。
+ */
+export function probeUrlOf(routePath: string, origin: { proto: string, host: string }): string {
+	if (/:\/\//.test(routePath) || routePath.startsWith("//"))
+		throw Object.assign(new Error(`路由探测拒绝出站/协议相对 URL（SSRF 防护）：${routePath}`), { status: 400 });
+	if (!routePath.startsWith("/"))
+		throw Object.assign(new Error(`路由探测路径须为站点相对路径（以 / 开头，SSRF 防护）：${routePath}`), { status: 400 });
+	return `${origin.proto}://${origin.host}${routePath}`;
+}
+
+/** SSRF 钉③：探针不跟随重定向（手动处理，3xx 按异常对待） */
+function noRedirectFetch(fetchFn: FetchInitFace): FetchInitFace {
+	return (url, init) => fetchFn(url, { ...init, redirect: "manual" } as Record<string, unknown>);
+}
+
+/**
+ * 路由可达性探针（I/O）：逐路由探活；分类（契约 §2.13 + 计划 §3 P2-7）：
+ * 2xx / 401（需登录仍可达）→ 不打项；
+ * 404 / 5xx → error（anomaly）；
+ * 403 → 声明 `required_permission` = 未以目标身份验证、未校验（warn，非通过非失败）；否则 error（被拦截）。
+ * 抛错（连不通）→ error（unreachable）。origin 为 null（非 HTTP 请求上下文）→ 跳过探针，打 info 项。
+ */
+export async function verifyRouteReachability(
+	fetchFn: FetchInitFace,
+	routes: SolutionRouteRow[],
+	origin: { proto: string, host: string } | null,
+): Promise<VerifyItem[]> {
+	const items: VerifyItem[] = [];
+	if (origin === null) {
+		items.push({ id: "routes", severity: "info", subject: "*", advise_key: "lifecycle.verify.routes.skipped" });
+		return items;
+	}
+	const fetch = noRedirectFetch(fetchFn);
+	for (const r of routes) {
+		let status: number;
+		try {
+			const res = await fetch(probeUrlOf(r.path, origin), { headers: { "cache-control": "no-cache" } });
+			status = res.status;
+		}
+		catch (e) {
+			if (e instanceof Error && (e as { status?: number }).status != null)
+				throw e; // SSRF 拦截（400）原样上抛，端点收口为 400
+			items.push({ id: "routes", severity: "error", subject: r.path, advise_key: "lifecycle.verify.routes.unreachable" });
+			continue;
+		}
+		if (status === 404 || status >= 500) {
+			items.push({ id: "routes", severity: "error", subject: r.path, advise_key: "lifecycle.verify.routes.anomaly" });
+		}
+		else if (status >= 300 && status < 400) {
+			// 3xx 重定向：探针不跟随（SSRF 钉③，init.redirect="manual"），裸 3xx 即异常
+			items.push({ id: "routes", severity: "error", subject: r.path, advise_key: "lifecycle.verify.routes.redirect" });
+		}
+		else if (status === 403) {
+			if (r.required_permission != null)
+				items.push({ id: "routes", severity: "warn", subject: r.path, advise_key: "lifecycle.verify.routes.unauthenticated" });
+			else
+				items.push({ id: "routes", severity: "error", subject: r.path, advise_key: "lifecycle.verify.routes.blocked" });
+		}
+		// 2xx / 401 → 可达，不打项
+	}
+	return items;
+}
+
+/** RBAC 完整性（纯函数）：路由声明权限点 ↔ sys_permission 实有；缺失即 error */
+export function diffPermRows(declared: string[], actual: Set<string>): VerifyItem[] {
+	return declared
+		.filter(p => !actual.has(p))
+		.map(p => ({ id: "rbac", severity: "error" as const, subject: p, advise_key: "lifecycle.verify.rbac.missing_perm" }));
+}
+
+/** 设置完整性（纯函数）：方案声明设置 key ↔ sys_setting 实有；缺失即 error（永不含值） */
+export function diffSettingRows(declared: string[], actual: Set<string>): VerifyItem[] {
+	return declared
+		.filter(k => !actual.has(k))
+		.map(k => ({ id: "settings", severity: "error" as const, subject: k, advise_key: "lifecycle.verify.settings.missing_key" }));
+}
+
+/** 迁移账本（纯函数）：声明迁移模块版本 ↔ `_oj_migrations` 实有 max(version)；缺失/落后即 error */
+export function diffLedger(declared: Array<{ module: string, version: number }>, applied: Map<string, number | null | undefined>): VerifyItem[] {
+	const items: VerifyItem[] = [];
+	for (const d of declared) {
+		const got = applied.get(d.module);
+		if (got == null)
+			items.push({ id: "ledger", severity: "error", subject: d.module, advise_key: "lifecycle.verify.ledger.not_applied" });
+		else if (got < d.version)
+			items.push({ id: "ledger", severity: "error", subject: d.module, advise_key: "lifecycle.verify.ledger.stale" });
+	}
+	return items;
+}
+
+/** manifest 声明设置 key 提取（不报值）；groups[].items[].key 摊平 */
+export function declaredSettingsOf(manifest: unknown): string[] {
+	const groups = isObj(manifest) ? manifest.settings : undefined;
+	if (!isObj(groups) || !Array.isArray(groups.groups))
+		return [];
+	const keys: string[] = [];
+	for (const g of groups.groups) {
+		if (!isObj(g) || !Array.isArray(g.items))
+			continue;
+		for (const it of g.items) {
+			if (isObj(it) && typeof it.key === "string")
+				keys.push(it.key);
+		}
+	}
+	return keys;
+}
+
+/** 迁移文件名 → 声明最高版本（module 由调用方给定；缺迁移文件返回空） */
+export function declaredMigrationsOf(files: string[], module: string): Array<{ module: string, version: number }> {
+	const versions: number[] = [];
+	for (const f of files) {
+		const m = /^(\d+)__/.exec(f);
+		if (m)
+			versions.push(Number(m[1]));
+	}
+	if (versions.length === 0)
+		return [];
+	return [{ module, version: Math.max(...versions) }];
+}
+
+/** 读取已装方案 manifest（state 取版本 → 版本目录读盘）；不可得返回 null（端点据 404 降级） */
+export async function readSolutionManifest(env: SolutionsEnv, name: string): Promise<{ version: string, manifest: unknown } | null> {
+	const state = await createStateStore(env.statePath);
+	const entry = state.read().solutions[name];
+	if (!entry)
+		return null;
+	const version = entry.version;
+	if (typeof version !== "string")
+		return null;
+	try {
+		const yaml = (globalThis as { yaml?: { parse: (t: string) => Promise<unknown> } }).yaml;
+		if (!yaml?.parse)
+			return null;
+		const bytes = await fsFace().readFile(`${env.sharedRoot}/${name}-${version}/manifest.yaml`);
+		return { version, manifest: await yaml.parse(new TextDecoder().decode(bytes)) };
+	}
+	catch {
+		return null;
+	}
+}
+
+/** web 入口条目（modules.json）形态（与 deployWeb 落地形状对齐；此处仅取深检所需字段） */
+export interface ModuleEntryIntegrity {
+	name: string
+	entry?: string
+	integrity?: string
+}
+
+/**
+ * 深检 web 入口 integrity（P4-2，P3-10#2 收口）：声明 entry 的 sha384（本地 dist 资产）↔
+ * modules.json 条目 integrity 比对；不符 = error（被篡改/损坏），缺失 integrity 声明 = info
+ * （未声明，非阻断），资产不存在 = info（web 入口缺失，非阻断）。SSRF 钉：只比对本地 dist
+ * 资产，绝不经 fetch 出站（与路由可达性探针严格隔离——复用 native 资产校验，不引入外联面）。
+ */
+export async function diffWebIntegrity(
+	entries: ModuleEntryIntegrity[],
+	distRoot: string,
+	sha384: (data: Uint8Array) => string,
+): Promise<VerifyItem[]> {
+	const items: VerifyItem[] = [];
+	const me = entries.find(e => e.name != null && typeof e.entry === "string" && e.entry !== "");
+	if (me === undefined) {
+		items.push({ id: "web", severity: "info", subject: "*", advise_key: "lifecycle.verify.web.no_entry" });
+		return items;
+	}
+	if (typeof me.integrity !== "string" || !me.integrity.startsWith("sha384-")) {
+		items.push({ id: "web", severity: "info", subject: me.name ?? "*", advise_key: "lifecycle.verify.web.no_integrity" });
+		return items;
+	}
+	try {
+		const bytes = await fsFace().readFile(`${distRoot}/${me.entry}`);
+		const actual = `sha384-${sha384(new Uint8Array(bytes))}`;
+		if (actual !== me.integrity) {
+			items.push({ id: "web", severity: "error", subject: me.entry, advise_key: "lifecycle.verify.web.integrity_mismatch" });
+		}
+	}
+	catch {
+		// 资产缺失（web 入口未落位或路径变更）——info 非阻断（路由可达性已另测）
+		items.push({ id: "web", severity: "info", subject: me.entry, advise_key: "lifecycle.verify.web.asset_missing" });
+	}
+	return items;
+}
+
+/** 站点源（深检端点依赖；sharedRoot/statePath 为读面，fetch 可注入） */
+export interface SolutionsEnv {
+	sharedRoot: string
+	statePath: string
+	modulesJsonPath?: string
+	apiPrefix?: string
+	/** 深检报告留存目录（默认随 statePath 同目录 verify-reports；P2-8） */
+	verifyReportsDir?: string
+	fetch?: FetchInitFace
+}

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

@@ -0,0 +1,92 @@
+import type { VerifyItem } from "./verify-checks";
+// 深检报告结构 + 时间序留存（P2-8，C2-42）：VerifyReport 定义、verify-reports 落盘、N=10 留存、
+// 按 name 取最新。i18n 项本仓只下发待查 key 清单（advise），前端经 oj-market 解析；缺执行降级
+// 「未校验」不阻断（不在此处解析文案）——编排见 solutions/api.ts。
+// 设值永不进报告（checks 只报 id/path/code/key；secret 同只报 key）——与 verify-checks 同纪律。
+import { atomicWriteText, fsFace } from "./atomic";
+
+/** 深检报告（契约 §2.13：{ok, checks[], advise[]}） */
+export interface VerifyReport {
+	/** 是否存在 error 级检查项（无 error = 整体通过；warn/info 不阻断） */
+	ok: boolean
+	/** 检查项（routes/rbac/settings/ledger/trust/i18n）——每项 id/severity/subject/advise_key */
+	checks: VerifyItem[]
+	/** 待查 i18n key 清单（去重排序）：前端经 oj-market 解析文案；缺执行降级「未校验」不阻断 */
+	advise: string[]
+}
+
+/** 落盘文件形态（文件名=createdAt.json，便于时间序排序与按 name 检索） */
+export interface VerifyReportFile {
+	createdAt: number
+	name: string
+	report: VerifyReport
+}
+
+// 报告留存条数（超出删最旧；与 tasks.ts TASK_KEEP 同口径「时间序保留 + 触发点」）
+export const VERIFY_REPORTS_KEEP = 10;
+
+/** 报告目录（默认随 statePath 同目录 verify-reports；与 .solutions 同根） */
+export function verifyReportsDirOf(env: { statePath: string, verifyReportsDir?: string }): string {
+	if (env.verifyReportsDir !== undefined)
+		return env.verifyReportsDir;
+	const slash = env.statePath.lastIndexOf("/");
+	const base = slash === -1 ? "" : env.statePath.slice(0, slash);
+	return base === "" ? "verify-reports" : `${base}/verify-reports`;
+}
+
+/** 文件名（纯数字 .json）判定，避免误吞非报告文件 */
+function isReportName(n: string): boolean {
+	return /^\d+\.json$/.test(n);
+}
+
+/** 持久化一份报告 + 触发留存 GC（保留最近 N=10，删最旧）。单条清理失败不影响主流程。 */
+export async function persistReport(dir: string, name: string, report: VerifyReport, now: number = Date.now()): Promise<void> {
+	const file: VerifyReportFile = { createdAt: now, name, report };
+	await atomicWriteText(`${dir}/${now}.json`, `${JSON.stringify(file)}\n`);
+	// GC：按文件名数值序（=createdAt 序）保留最近 N=10，删最旧（第 11 份挤掉第 1 份）
+	let names: string[];
+	try {
+		names = await fsFace().readdir(dir);
+	}
+	catch {
+		return; // 目录尚不存在/不可读：本次写入已落盘，GC 下次收敛
+	}
+	const sorted = names.filter(isReportName).sort((a, b) => Number(a.slice(0, -5)) - Number(b.slice(0, -5)));
+	const stale = sorted.slice(0, Math.max(0, sorted.length - VERIFY_REPORTS_KEEP));
+	for (const n of stale) {
+		try {
+			await fsFace().remove(`${dir}/${n}`);
+		}
+		catch {
+			// 单条清理失败不影响主流程
+		}
+	}
+}
+
+/**
+ * 取某方案最新报告（按 createdAt 最大）；无/目录缺失/全部损坏 → null（不炸，端点据 404 降级）。
+ * 损坏文件跳过（可观测性优先，不为坏文件阻塞读取）。
+ */
+export async function getLastReport(dir: string, name: string): Promise<VerifyReport | null> {
+	let names: string[];
+	try {
+		names = await fsFace().readdir(dir);
+	}
+	catch {
+		return null;
+	}
+	let best: VerifyReportFile | null = null;
+	for (const n of names.filter(isReportName)) {
+		try {
+			const f = JSON.parse(new TextDecoder().decode(await fsFace().readFile(`${dir}/${n}`))) as VerifyReportFile;
+			if (f.name !== name)
+				continue;
+			if (best === null || f.createdAt > best.createdAt)
+				best = f;
+		}
+		catch {
+			// 损坏跳过
+		}
+	}
+	return best?.report ?? null;
+}

package/templates/api/src/_platform/_shared/service/access.ts

@@ -64,8 +64,8 @@ function deny(): never {
 	throw Object.assign(new Error("forbidden"), { status: 403 });
 }
 
-/** 当前请求的访问快照；未认证/禁用/改密悬挂即拒（403 不泄露账号存在性）。 */
-async function currentAccess(): Promise<AccessSnapshot> {
+/** 当前请求的访问快照；未认证/禁用/改密悬挂即拒（403 不泄露账号存在性）。导出供各 handler 作「登录态即放行」判据（如操作日志写端）。 */
+export async function currentAccess(): Promise<AccessSnapshot> {
 	const uid = http.user?.id;
 	if (uid == null)
 		deny();

package/templates/api/src/_platform/_shared/service/settings.ts

@@ -11,6 +11,8 @@ export interface SettingItem {
 	value: string | null
 	default_value: string | null
 	label_key: string | null
+	/** 组标题 key（C2-22 组级 label_key 落库值，P2-15③；同组各行一致，组面取首个非空） */
+	group_label_key: string | null
 	options: string | null
 	secret: boolean
 	update_time: number
@@ -18,6 +20,8 @@ export interface SettingItem {
 
 export interface SettingGroup {
 	group: string
+	/** 组标题 key（组面收敛：同组任一行非空即用——P2-15③ DB 组标题回填消费面） */
+	label_key: string | null
 	items: SettingItem[]
 }
 
@@ -36,13 +40,18 @@ export async function listSettings(): Promise<SettingGroup[]> {
 			value: Number(r.secret) === 1 ? "***" : (r.value == null ? null : String(r.value)),
 			default_value: r.default_value == null ? null : String(r.default_value),
 			label_key: r.label_key == null ? null : String(r.label_key),
+			group_label_key: r.group_label_key == null ? null : String(r.group_label_key),
 			options: r.options == null ? null : String(r.options),
 			secret: Number(r.secret) === 1,
 			update_time: Number(r.update_time),
 		};
 		(groups.get(item.group) ?? groups.set(item.group, []).get(item.group))!.push(item);
 	}
-	return [...groups.entries()].map(([group, items]) => ({ group, items }));
+	return [...groups.entries()].map(([group, items]) => ({
+		group,
+		label_key: items.find(x => x.group_label_key !== null)?.group_label_key ?? null,
+		items,
+	}));
 }
 
 export async function updateSetting(actorId: number, key: string, value: string): Promise<void> {

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

@@ -73,22 +73,29 @@ export async function upsertSolutionPerms(m: SolutionManifest): Promise<UpsertRe
 	return { deprecated };
 }
 
+/** 事务/非事务统一的 db 面（P3-3：可传入 db.tx 的事务句柄以纳入单一事务） */
+interface DbLike {
+	query: (sql: string, params?: unknown[]) => Promise<unknown>
+	exec: (sql: string, params?: unknown[]) => Promise<unknown>
+}
+
 /**
  * 卸载级联清理（AC2-6，唯一减法出口）——双维度：
  * ① 该 module 的角色行 + 这些角色的全部绑定 + 用户成员资格；
  * ② permission_code 属该 module 的绑定（含 custom 角色上的）+ 权限点行——
  *   漏维度②会让 custom 角色残留绑定在重装时静默复活旧授权。custom 角色本体保留（空绑定）。
  * AC2-7：业务表不属本出口，运维手工处理（Q4）。
+ * P3-3：可传入事务句柄 `d`（db.tx 的 t），使级联纳入卸载的单一 DB 事务；缺省回落全局 db（兼容既有调用面）。
  */
-export async function uninstallSolution(module: string): Promise<void> {
-	const roles = await db.query("select name from sys_role where module = ?", [module]) as Array<{ name: string }>;
+export async function uninstallSolution(module: string, d: DbLike = db): Promise<void> {
+	const roles = await d.query("select name from sys_role where module = ?", [module]) as Array<{ name: string }>;
 	for (const r of roles) {
-		await db.exec("delete from sys_role_permission where role_name = ?", [r.name]);
-		await db.exec("delete from sys_user_role where role_name = ?", [r.name]);
+		await d.exec("delete from sys_role_permission where role_name = ?", [r.name]);
+		await d.exec("delete from sys_user_role where role_name = ?", [r.name]);
 	}
-	await db.exec("delete from sys_role where module = ?", [module]);
+	await d.exec("delete from sys_role where module = ?", [module]);
 	// module 名是 slug（[a-z0-9_-]），LIKE 前缀匹配的转义纪律同 query.ts（ESCAPE '!' 三方言同义）
 	const prefix = `${module.replace(/[!%_]/g, c => `!${c}`)}.%`;
-	await db.exec("delete from sys_role_permission where permission_code like ? escape '!'", [prefix]);
-	await db.exec("delete from sys_permission where module = ?", [module]);
+	await d.exec("delete from sys_role_permission where permission_code like ? escape '!'", [prefix]);
+	await d.exec("delete from sys_permission where module = ?", [module]);
 }

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

@@ -0,0 +1,44 @@
+// 站点编排面共享真源（P2-16 真机构建钉出：oj build 禁「模块内 import api.ts」——
+// market/api.ts 是路由入口，verify-checks/solutions 复用的非路由原语必须落本模块）。
+// 单一真源：market/api.ts re-export 保持既有引用面；深检/方案域直接 import 本模块。
+
+import type { FetchFace } from "../_lifecycle/steps/download";
+
+/** 带缓存指令的拉取面（FetchFace 的超集：oj 全局 fetch/测试 stub 天然满足，少参函数可赋多参形） */
+export type FetchInitFace = (url: string, init?: { headers?: Record<string, string>, redirect?: string }) => Promise<{
+	ok: boolean
+	status: number
+	arrayBuffer: () => Promise<ArrayBuffer>
+}>;
+
+/** 站点源（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) {
+		return null;
+	}
+	const proto = String(h["x-forwarded-proto"] ?? "http").split(",")[0]!.trim() || "http";
+	return { proto, host };
+}
+
+/** 站点源补全（深检探针复用 siteOrigin；相对 URL → 绝对同源 URL） */
+export function withSiteOrigin(fetch: FetchInitFace): FetchFace {
+	const o = siteOrigin();
+	if (o === null) {
+		return fetch as FetchFace;
+	}
+	return url => fetch(/^https?:\/\//i.test(url) ? url : `${o.proto}://${o.host}${url}`) as ReturnType<FetchFace>;
+}
+
+/** 站点迁移账本 head（oj journal 真源 `_oj_migrations`；表缺失/查询失败 → null = 跳过禁降版判定，不猜） */
+export async function journalHeadOf(name: string): Promise<number | bigint | null> {
+	try {
+		const rows = await db.query("select max(version) as head from _oj_migrations where module = ?", [name]) as Array<{ head: unknown }>;
+		const head = rows[0]?.head;
+		return head == null ? null : Number(head);
+	}
+	catch {
+		return null;
+	}
+}

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

@@ -11,3 +11,4 @@ tables:
   - sys_role_permission
   - sys_user_role
   - sys_refresh_token
+  - market_history