@oj-module/cli 0.2.30 → 0.2.43

package/templates/config.yaml

@@ -1,107 +1,61 @@
-# oj 服务配置（字段语义见 oj 后端开发手册 oj-api-dev / 或 oj --help）。
-# 本文件由 ojm init 生成；config 内相对路径相对本文件所在目录。
-# 更多能力见手册 §10：vars / broker / tasks / oidc / ws / html_meta / secrets。
-#
-# ---- 证书与密钥的唯一落点：`./config/`（= 工程根/config/，本文件同级的子目录）----
-# 三件套由 `ojm init` 现场签发（dev 缺证时 `ojm dev` 也会补签），逐把的作用与后果：
-#
-#   ① private.pem —— 证书签发私钥（RSA 2048）。只用来给 ③ 签名，**oj 不读它**，
-#      也绝不出部署机、不入仓。丢了不需要恢复：重新签发一套即可（旧的 ③ 作废）。
-#   ② public.pem  —— 与 ① 成对的公钥，oj 启动时拿它验 ③ 的 RS256 签名。
-#      配错路径或与 ③ 不是同一对 → oj 验签失败、启动即拒（读作「证书无效」）。
-#      由 server.public_key_path 引用。
-#   ③ cert.jws    —— JWS 证书（RS256 紧凑三段，payload 仅 nbf/exp），**oj 的启动闸门**：
-#      缺失、过期、签名对不上 → fail-fast 拒启，devkit 手册明确**无任何 config/CLI 绕过开关**。
-#      默认有效期 3650 天（短有效期等于定时炸弹）；过期只能重新签发一套 ①②③。
-#      由 server.certificate_path 引用。
-#
-# 另有一对与上面无关的密钥（jwt_secret 密封用，init 密封成功后追加到本文件末尾）：
-#   secrets.private_key_path  ./config/secrets-private.pem  解 jwt_secret 密文的私钥，只放部署机
-#   secrets.public_key_path   ./config/secrets-public.pem   加密用的公钥，可随代码分发
-#   （密文形如 ENC 后跟方括号包裹的字串；未密封时 config 里是 32 字节十六进制明文）
-#
-# ojm 侧的解析入口是 `resolveCertDir()`，由本文件位置派生；改落点只需动那一处 + 本段注释。
+# oj 服务配置（字段手册见 devkit oj-api-dev / oj --help）。由 ojm init 生成，相对路径相对本文件所在目录。
 
-# 站点挂载（oj v0.1.58 起顶层扁平表：一行=一个 URL 前缀+一个目录，api/web 恰好其一）。
-# 被删除的 server.api_prefix / app_spa_fallback 已由 mounts 取代；
-# ojm dev 的 SPA 深链回落由 ojm 自建静态层负责；ojm preview 为单服务形态，
-# 现场生成派生 config（.ojm-preview.yaml，注入下面的 web 挂载 + spa: true），无需手改。
-#
-# **这里没有 api 挂载是有意的**：本工程是 `src/<name>/{api,web}` 布局，模块分散在
-# `src/<name>/api` 下，而 mounts 的 api 项按 `<目录>/<模块>/manifest.yaml` 单层解析、
-# 不会递归（实测报 `module 'x' missing manifest.yaml`）。源码形态由 `ojm dev` 用
-# `--module-root src` 供给，产物形态由 `ojm preview` 用 `--api-path dist/api` 供给；
-# 两者与 mounts 的 api 项同时出现还会报「module declared in multiple places」。
-# 手写部署（不经 ojm）时才需要自己加回一条 `- prefix: /api` + `api: dist`。
+# ---- 证书三件套在 ./config/（init 已现场签发）----
+#   private.pem  签发私钥：只用于给 cert.jws 签名，oj 不读它；泄露或丢失就重签一套，旧的作废
+#   public.pem   oj 启动时验 cert.jws 签名用（server.public_key_path）
+#   cert.jws     启动闸门：缺失/过期/签名不符直接拒启，无 config/CLI 绕过（默认 10 年有效期）
+# 另有一对 secrets-*.pem：init 密封 jwt_secret 后追加到本文件末尾，同样只放部署机。
+
+# 站点挂载：一行 = 一个 URL 前缀 + 一个目录（api/web 二选一）。
+# 这里不放 api 挂载是有意的：本工程是 src/<name>/{api,web} 布局，源码由 ojm dev
+# 以 --module-root src 供给、产物由 ojm preview 以 --api-path dist/api 供给，都不走 mounts。
+# 手写部署（不用 ojm）时才需要加回一条 `- prefix: /api` + `api: dist`。
 mounts:
-  # 本地模拟 CDN：直出工程根 cdn/（内容见 cdn/README.md）。
-  # seed 的 framework.market_cdn_url 缺省即 /cdn（本站点自供），新工程免 market setup。
-  # 红线：生产请删掉这一条挂载，并把 system 设置 framework.market_cdn_url 指向真 CDN（绝对地址）。
-  # 不得给此挂载设 spa——缺文件必须返回 404，回落 index.html 会让市场解析崩。
+  # 本地市场 CDN：直出工程根 cdn/。seed 里 framework.market_cdn_url 缺省就是 /cdn，本站点自供免 setup。
+  # 生产删掉这条，并把该设置指向真 CDN（绝对地址）。不能设 spa：缺文件必须 404，
+  # 回落 index.html 会让市场解析崩。
   - prefix: /cdn
     web: ./cdn
-  # 生产若由 oj 直出前端（前后端同进程，即 ojm preview 的生产形态），
-  # 取消下一行注释并先 build 出 dist/web（preview 会自动注入等价挂载，无需手改）：
+    # 读面缓存 60s：yank 最坏 120s 生效。304 由 oj 静态层自带，这里只管新鲜窗口。
+    headers:
+      Cache-Control: 'max-age=60, stale-while-revalidate=60'
+  # 生产要 oj 直出前端（前后端同端口的 SPA，即 ojm preview 形态）就解开下面三行，先 ojm build。
+  # preview 自己会注入等价挂载，平时不用动。
   # - prefix: "/"
-  #   web: "./dist/web"   # 相对 config.yaml → 工程根/dist/web
+  #   web: "./dist/web"   # 相对本文件 → 工程根/dist/web
   #   spa: true
-  # 嵌套 handler 组（oj v0.1.64）无需配置开关，组织方式见 api.ts 顶部注释。
 
 server:
-  host: 127.0.0.1 # 显式钉死：oj 默认绑 [::1]，localhost 解析序在反代下有坑
+  host: 127.0.0.1 # 钉死 127.0.0.1：oj 默认绑 [::1]，localhost 在反代下解析有坑
   port: 9778
   public_key_path: ./config/public.pem
   certificate_path: ./config/cert.jws
-  # ---- 迁移门禁 ----
-  # auto = dev 缺省（启动即应用）；release 缺省是 verify（账本落后拒启，先 oj migrate）。
-  # 显式写出来：dev 的隐式 DB 副作用不再靠「模式默认值」猜，release 也不会因缺省拒启。
-  migrate_on_start: auto
-  # ---- 入参契约（v0.1.44）----
-  # 契约生成的 .schema 在此生效：违反即 400 且 handler 不执行。
-  # 关掉等于退回「后端零校验」，仅在 .schema 与旧 handler 冲突时临时逃生。
-  schema_validation: true
-  # ---- 单 isolate 堆限额（v0.1.40，默认 256MiB，下限 32MiB）----
-  js_heap_limit_bytes: 268435456
-  # ---- 路由级超时（v0.1.30）：pattern 按声明序首个命中，且是含 base 的全路径 ----
-  route_timeouts: []
-  # ---- 统一响应头（v0.1.30）----
-  response_headers: {}
-  # ---- 热更端点（ojm install 的 reloading 段消费；显式关闭 = 安装器 reloading 段可读失败）----
-  # ojm:reload
-  reload_api: true
-  # ---- 直传路由 PUT {base}/blob/{key} 的体积上限（v0.1.30，默认 1GiB）----
-  # 与 max_upload_bytes（multipart，默认 10MB）是两套闸，别混。
-  blob_upload_max_bytes: 1073741824
-  # ---- CORS（v0.1.35）：缺这一段 = 不挂 CORS 层；credentials 必须配显式 origins ----
+  migrate_on_start: auto # auto=启动即迁移；release 建议 verify（账本落后拒启，先 oj migrate）
+  schema_validation: true # 契约 .schema 违反即 400；仅当 .schema 与旧 handler 冲突时临时关
+  js_heap_limit_bytes: 268435456 # 单 isolate 堆限额（默认 256MiB，下限 32MiB）
+  route_timeouts: [] # 路由级超时；pattern 按声明序首个命中，写含 base 的全路径
+  response_headers: {} # 统一响应头
+  reload_api: true # 热更端点 /ojm:reload：安装器的 reloading 段要用，关掉安装会失败
+  blob_upload_max_bytes: 1073741824 # PUT blob 单文件上限（默认 1GiB；与 multipart 的 10MB 是两道闸）
   cors:
-    origins: [] # 留空 = 放行任意源；要带凭据则必须列出具体源
+    origins: [] # 空 = 放行任意源；要带凭据必须列具体源
     credentials: false
 db:
   default: 'sqlite://db.sqlite' # 相对 config 目录；缺文件自动建空库
 
-# ---- 安装序号（ojm install 每次安装自增一次，作为 reload 热更触发变更——unchanged 判定基于
-# config 文档 sha，无落盘变更则热更恒失败。勿删行/勿手工回写旧值。）----
 vars:
+  # ojm install 每次安装自增一次，用来触发 reload 热更。别删行、别手工回写旧值。
   ojm_install_seq: 0
+  # 站点对外地址。装方案时服务端拿它把 /cdn 这类相对地址补全成绝对 URL（深检探针也用它）。
+  # 故意不读请求头 Host（防伪造 Host 牵引出站）：不配 = fail-closed，不会替你猜。
+  # canonical_origin: "https://your-site.example.com"
 
-# ---- 平台 exec 白名单（ojm install 的解压/迁移两处消费；模板逐字对齐 lifecycle steps 命令构造，
-# 不得增删——多一个 token 都会 NotCapable）----
 platform:
-  # 平台特权模块名单：方案安装器的 reloading 段调 server.reloadConfig 触发热更。
-  # 缺这条 → 装在最后一步报 NotCapable: module '_platform' is not platform-privileged。
-  modules: [_platform]
-  # 受控根 = 后端模块源码根（`src/<name>/api` 的父目录，即 src）。ojm preview 派生 config
-  # 时会改写为 dist，保持与 `--api-path` 同源；手写部署请按实际模块根填写。
-  root: src
-  # ---- U6 信任库加固（P3-1；P2-2 红线 spike 结论）----
-  # 威胁：devkit 0.1.75 语义下 fs: 段对全部模块生效（jail = fs.root），且 trusted_paths 只增不减——
-  # 信任库落在第三方方案模块可写的 fs.root 内即可被其伪造信任锚。加固须两端配合：
-  # ① 本模板已将信任库默认路径移出 modules/ 安装子树（见 _lifecycle 默认 `.solutions/trusted-keys.yaml`，
-  #    落在 fs.root 之外的部署根，第三方方案模块 jail 之外）；
-  # ② **部署侧**须按 oj 语义补 `platform.trusted_paths`（指向运行时信任库目录，该目录须先存在——
-  #    oj 对不存在的 trusted_paths 装配 fail-fast，故不可在模板里硬编码尚未创建的目录）显式授权给
-  #    _platform 特权模块写信任库，并收窄第三方方案模块的 fs.root 至其安装子树，方可彻底隔离。
-  # 本仓负责①（代码路径）；②属部署/上游配置，留作部署清单项（P3-1 备案，不硬编码以免 oj serve 装配失败）。
+  modules: [_platform] # 安装器热更 config 需要 _platform 特权；删了会在装到最后一步报 NotCapable
+  root: src # 后端模块源码根（src/<name>/api 的父目录）；preview 派生 config 时改写成 dist
+  # 信任库默认落在安装子树之外（.solutions/trusted-keys.yaml），第三方方案模块碰不到。
+  # 部署侧还应补 platform.trusted_paths 授权 _platform 写库、并把第三方模块 fs.root 收窄到各自安装子树。
+  # 下面三条命令与安装器逐字对齐（含每个空格），一个 token 都不能动：
   exec:
     _platform:
       allow:
@@ -109,18 +63,14 @@ platform:
         - 'tar -xzf ${path:archive} -C ${path:dest}'
         - 'oj migrate --format json -d ${path:dir} ${raw:module}'
 
-# ---- 方案安装器的落盘面（fs.* 全局）----
-# 安装器要解包到 modules/.staging、写 dist/modules、备份 db.sqlite——全在 config 目录内。
-# 缺本段 = fs.* 抛 NotCapable，且失败发生在任务文件落盘之前：表现为「POST 安装返回 200、
-# 但 task 查询恒 404」，排查成本极高。生产收紧口径见上面 platform 段的 U6 说明
-# （fs.root 收窄到安装子树 + third-party 模块 jail 隔离属部署清单项）。
+# 安装器落盘面：解包到 modules/.staging、写 dist/modules、备份 db.sqlite，全在 config 目录内。
+# 缺这段会 NotCapable，且症状很阴：安装提交返回 200，但 task 查询恒 404。
 fs:
   root: .
   readonly: false
 
-# ---- LDAP 连接段（D1/PRD §4.5 两段式之连接段；oj 插件严格解析本段，未知键启动 fail-fast——只写下列键）----
-# 取消注释并填值即接通目录服务；应用映射段在 DB/设置页（ldap.enabled、ldap_base_dn、
-# ldap_uid_attr、ldap_email_attr，group=ldap，即时生效）。本段改动属 restart_pending，需重启。
+# LDAP 连接段：解开注释填值即接通目录服务；字段映射在「系统设置 → LDAP」里配，改本段要重启。
+# oj 严格解析这段，只写下面这些键，多一个键启动 fail-fast。
 # ldap:
 #  url: "ldap://127.0.0.1:389"
 #  bind_dn: ""
@@ -128,14 +78,14 @@ fs:
 #  timeout_ms: 3000
 #  start_tls: false
 #  tls_skip_verify: false
+
 auth:
   jwt_secret: __JWT_SECRET__ # init 随机生成；生产必须更换
   access_token_duration: 2h
   refresh_token_duration: 720h
-  anonymous_paths: # auth 端点是业务路由，必须显式匿名（漏列则握手 401，见 ojm 开发手册 §8）
+  anonymous_paths: # 不带 token 也能访问的路径；漏列则未登录访问一律 401
     - /auth/login
-    - /auth/ldap-login # D1/AC1-12：LDAP 目录登录（匿名）
+    - /auth/ldap-login # LDAP 目录登录
     - /auth/refresh
     - /auth/logout
-    # 登录页登录方式 Tabs 数据源（C5/AC2-2）：未登录即可读
-    - /system/login-methods
+    - /system/login-methods # 登录页「登录方式」Tabs 的数据源，未登录就要能读

package/templates/init.include.yaml

@@ -27,7 +27,7 @@ include:
   # —— 工程级文件 ——
   - README.md
   # 本地模拟 CDN 目录：只带 README（它的存在让挂载目录不缺，站点才起得来）。
-  # 产物 *.tgz / *.sig / bundles.yaml / manifests.yaml 一律不拷、不进发布包。
+  # 产物 *.tgz / *.sig / catalog.yaml / shards/ 一律不拷、不进发布包。
   - cdn/README.md
   - tsconfig.json
   - global.d.ts

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

@@ -15,6 +15,8 @@ export interface FsFace {
 	copyFile: (src: string, dest: string) => Promise<void>
 	/** 列目录成员名（不含路径；不含 . / ..） */
 	readdir: (path: string) => Promise<string[]>
+	/** 取文件体积（REG-CS8 解压后实际磁盘占用复核用；oj 真机 stat 形状略有差异，缺失则复核降级跳过） */
+	stat?: (path: string) => Promise<{ size: number }>
 }
 
 /**
@@ -67,6 +69,7 @@ export function fsFace(): FsFace {
 				names.push(e.name);
 			return names;
 		}),
+		stat: f.stat ?? undefined,
 	};
 }
 

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

@@ -79,6 +79,8 @@ export interface InstallRequest extends InstallContext {
 	trustPath?: string
 	/** Ed25519 验签面（P2-3；缺省回落运行时全局 crypto.verifyEd25519，同 verify.ts） */
 	verifyEd25519?: (publicKey: string, msg: string, sigBase64: string) => boolean
+	/** 本站点（registry）身份（REG-CS3 v2 防跨仓库重放）；安装验签时与 .sig.registry_id 比对 */
+	registryId?: string
 	/** 迁移账本 head（rollbackGuard 真源；缺省跳过禁降版判定，同 migrate.ts） */
 	ledgerHead?: number | bigint | null
 	/** 注册快照查询（smoke；缺省回落 queryRegistered 的 db 全局） */
@@ -297,6 +299,11 @@ export function declOf(req: InstallRequest): SolutionDecl {
 			title: typeof r.title_key === "string" ? r.title_key : "",
 			permissions: Array.isArray(r.permissions) ? r.permissions.map(String) : [],
 		})),
+		// 顶层 permissions[] 的 code：无角色权限点（系统预置点）唯一能落库的来源，别在此丢弃
+		permissions: (Array.isArray(m.permissions) ? m.permissions : [])
+			.filter(isObj)
+			.map(p => (typeof p.code === "string" ? p.code : ""))
+			.filter(Boolean),
 		settings,
 		routes: (Array.isArray(m.routes) ? m.routes : []).filter(isObj).map(r => ({
 			path: typeof r.path === "string" ? r.path : "",
@@ -331,26 +338,56 @@ async function deployWebStage(req: InstallRequest): Promise<StageResult> {
 	return deployWeb({ ...req, stagingDir: req.staging, integrity });
 }
 
+/** `ojm preview` 派生的 config 文件名（与 CLI 侧 preview-config.ts 的 PREVIEW_CONFIG_NAME 逐字一致） */
+const PREVIEW_CONFIG_NAME = ".ojm-preview.yaml";
+
+/** 与 config 同目录的 preview 派生文件路径（无目录分隔符 = 同目录裸名） */
+function previewSiblingOf(configPath: string): string {
+	const cut = Math.max(configPath.lastIndexOf("/"), configPath.lastIndexOf("\\"));
+	return cut < 0 ? PREVIEW_CONFIG_NAME : `${configPath.slice(0, cut + 1)}${PREVIEW_CONFIG_NAME}`;
+}
+
+/** 把「安装序号自增 + 匿名端点接线」写到一份 config 文本上；`optional` 用于派生文件不存在即跳过 */
+async function patchConfigAt(configPath: string, anonymous: string[], optional = false): Promise<string[]> {
+	let content: string;
+	try {
+		content = new TextDecoder().decode(await fsFace().readFile(configPath));
+	}
+	catch (e) {
+		if (optional)
+			return [];
+		throw e;
+	}
+	const bumped = bumpInstallSeq(content);
+	const patched = anonymous.length > 0 ? appendAnonymousPaths(bumped.content, anonymous) : { content: bumped.content, added: [] };
+	await atomicWriteText(configPath, patched.content);
+	return patched.added;
+}
+
 /**
  * 热更段适配（B-11 reload 触发面）：先落盘触发变更再 reloadAndAssert——reloadConfig 的
  * unchanged 判定基于 config 文档 sha（oj-bin reload_bridge 真源），不落盘变更则热更恒
  * unchanged 必失败。触发变更 = vars.ojm_install_seq 自增（PRD E5 实测先例：vars 段语义值
  * 改动 applied 可热生效，无需改 mounts），经 text-edit 纯文本行操作（R18，注释/键序逐字保留）。
+ *
+ * **preview 形态（`ojm preview`）**：服务端读的是同目录派生出来的 `.ojm-preview.yaml`（spa 挂载 +
+ * platform.root 改写到 dist），安装器改的 `config.yaml` 它根本不看——于是 reload 按文档 sha 判
+ * unchanged，安装恒定卡在 reloading。所以派生文件存在时同步写一份：源 config 仍是真相（preview
+ * 重启后按它重建派生文件），派生文件是当前活视图，两份一起变，reload 才看得到差异。
+ * 派生文件不存在（dev / 生产部署形态）就只写源 config，不无中生有。
  */
 async function reloadStage(req: InstallRequest): Promise<StageResult> {
 	const path = req.configPath ?? "config.yaml";
 	try {
-		const content = new TextDecoder().decode(await fsFace().readFile(path));
-		const bumped = bumpInstallSeq(content);
-		// C2-26 anonymous 运行时接线（P2-15③，观察项 6 收口）：方案匿名端点补进
-		// auth.anonymous_paths（幂等；热改属 restart_pending——reload 消息已明示重启生效）
 		const m = isObj(req.manifest) ? req.manifest : {};
 		const api = isObj(m.api) ? m.api : {};
 		const anonymous = Array.isArray(api.anonymous) ? api.anonymous.filter((x): x is string => typeof x === "string") : [];
-		const patched = anonymous.length > 0 ? appendAnonymousPaths(bumped.content, anonymous) : { content: bumped.content, added: [] };
-		await atomicWriteText(path, patched.content);
+		// C2-26 anonymous 运行时接线（P2-15③，观察项 6 收口）：方案匿名端点补进
+		// auth.anonymous_paths（幂等；热改属 restart_pending——reload 消息已明示重启生效）
+		const added = await patchConfigAt(path, anonymous);
+		await patchConfigAt(previewSiblingOf(path), anonymous, true);
 		// 交接给 smoke：本次真正新增的匿名路径在重启前恒 401（restart_pending）
-		req.deferredAnonymous = patched.added;
+		req.deferredAnonymous = added;
 	}
 	catch (e) {
 		return { stage: "reloading", ok: false, retryable: true, message: `热更失败：config.yaml 安装序号自增/匿名端点接线失败（${String(e)}）——reload unchanged 判定基于 config 文档 sha，无变更则热更不可能生效（B-11，PRD E5 口径）` };

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

@@ -0,0 +1,21 @@
+// 体积上限常量（REG-CS8 红队 F1，Q13 已拍板数值）。
+//
+// 全仓单源：下载闸 / 解压闸 / 上传侧（S4-2）三处共用同一组数字——改一处即可调，
+// 杜绝「下载侧一个值、解压侧另一个值」的散落（红队 F1 原罪）。
+//
+// 语义分工：
+// - MAX_PACKAGE_BYTES：分发包（.tgz，已压缩）体积上限。下载闸在 fetch 之前比对索引声明的
+//   archive.size 直接拒，不发请求、不读入内存——先中毒后验毒的源头堵死。
+// - MAX_UNPACKED_BYTES：解压后未压缩总体积上限。解压炸弹（1MB → 2GB）的主闸：tar -tvzf 清单
+//   已含真实未压缩尺寸，校验阶段即拒，零解压零落盘；解压后再复核实际磁盘占用兜底。
+// - MAX_ENTRIES：tar 成员条目数上限。海量小文件 / zip-bomb 的条目数维度封顶。
+// - MAX_SINGLE_ENTRY_BYTES：单成员未压缩体积上限。单文件解压炸弹（一个 50MB+ 的成员）封顶。
+
+/** 分发包（.tgz）体积上限 = 50MB */
+export const MAX_PACKAGE_BYTES = 50 * 1024 * 1024;
+/** 解压后未压缩总体积上限 = 200MB */
+export const MAX_UNPACKED_BYTES = 200 * 1024 * 1024;
+/** tar 成员条目数上限 = 5000 */
+export const MAX_ENTRIES = 5000;
+/** 单成员未压缩体积上限 = 50MB */
+export const MAX_SINGLE_ENTRY_BYTES = 50 * 1024 * 1024;

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 };
+}