@oj-module/cli 0.2.43 → 0.2.45

package/src/market/walkthrough.ts

@@ -7,7 +7,7 @@
  * 输出是一张 AC 表 + 汇总行；有 FAIL 即退出码 1。`--strict` 首败即停（调试用）。
  *
  * T12 追加：upgrade / rollback（主链路）与 neg-tamper / nosig / badindex / stranger（负向）。
- * neg-* 统一用 9.9.9 版本与主链路隔离；篡改的文件在 finally 里回抄原始字节（不重签），
+ * neg-* 统一用 0.0.9 版本（低于主链路 latest 0.2.0，永远成不了 latest）与主链路隔离；篡改的文件在 finally 里回抄原始字节（不重签），
  * 收尾摘包重铺索引——否则后续 op 全挂。
  */
 
@@ -22,7 +22,7 @@ import process from "node:process";
 import { resolveLayout } from "../layout";
 import { writeIndexFile } from "../publish";
 import { signCommand } from "../sign";
-import { callApi, login, pollTask, unwrapEnvelope } from "../site";
+import { callApi, login, pollTask, tenantHeaders, unwrapEnvelope } from "../site";
 import { bootstrapIsolatedSite, derivePublisherKey } from "./bootstrap";
 import { buildIndex } from "./build-index";
 import { FAILURE_PLAYBOOK } from "./failure-playbook";
@@ -70,8 +70,14 @@ export interface WalkthroughResult {
 	port: number
 }
 
-/** neg-* 专用版本：与主链路（0.1.0/0.2.0）完全隔离，收尾整包摘除 */
-const NEG_VERSION = "9.9.9";
+/**
+ * neg-* 专用版本：与主链路（0.1.0/0.2.0）完全隔离，收尾整包摘除。
+ * 必须低于主链路 latest（0.2.0），否则发布后它会成为 latest，摘除时 REG-CS2 单调性守卫
+ * 会把它判成「latest 回退」而拒建索引，导致负向用例的安装拒绝断言没机会跑（9.9.9 曾踩此坑）。
+ */
+const NEG_VERSION = "0.0.9";
+/** neg-* 独立方案名：与主链路 demo-solution 隔离，避免共享迁移账本（OJ-9 降级守卫会误拦 neg 包的低 seq 迁移）与 latest 守卫串扰 */
+const NEG_NAME = "neg-solution";
 
 const OPS: Op[] = [
 	{
@@ -224,14 +230,14 @@ const OPS: Op[] = [
 		key: "neg-tamper",
 		title: "负向：包体篡改（sha256 不符）",
 		run: async (ctx) => {
-			await publishVersion(ctx, NEG_VERSION);
-			const tgz = path.join(ctx.site.cdnDir, `${ctx.name}-${NEG_VERSION}.tgz`);
+			await publishVersion(ctx, NEG_VERSION, NEG_NAME);
+			const tgz = path.join(ctx.site.cdnDir, `${NEG_NAME}-${NEG_VERSION}.tgz`);
 			const orig = fs.readFileSync(tgz);
 			try {
 				const tampered = Buffer.from(orig);
 				tampered[Math.floor(tampered.length / 2)] ^= 0x01; // 翻转中间一个字节
 				fs.writeFileSync(tgz, tampered);
-				const task = await installOnce(ctx, NEG_VERSION);
+				const task = await installOnce(ctx, NEG_VERSION, NEG_NAME);
 				const rejected = task.status === "failed" && task.stage === "verifying";
 				const noDrop = !fs.existsSync(path.join(ctx.site.root, "api", "dist", `${ctx.name}-${NEG_VERSION}`));
 				const ok = rejected && noDrop;
@@ -244,7 +250,7 @@ const OPS: Op[] = [
 			}
 			finally {
 				fs.writeFileSync(tgz, orig); // 回抄原始字节，不重签
-				await removeVersion(ctx, NEG_VERSION);
+				await removeVersion(ctx, NEG_VERSION, NEG_NAME);
 			}
 		},
 	},
@@ -252,21 +258,21 @@ const OPS: Op[] = [
 		key: "neg-nosig",
 		title: "负向：缺包级签名（sig_missing）",
 		run: async (ctx) => {
-			await publishVersion(ctx, NEG_VERSION);
-			const tgz = path.join(ctx.site.cdnDir, `${ctx.name}-${NEG_VERSION}.tgz`);
+			await publishVersion(ctx, NEG_VERSION, NEG_NAME);
+			const tgz = path.join(ctx.site.cdnDir, `${NEG_NAME}-${NEG_VERSION}.tgz`);
 			const sig = `${tgz}.sig`;
 			const origSig = fs.readFileSync(sig);
 			try {
 				fs.rmSync(sig);
 				await buildIndex({ projectRoot: ctx.site.root, id: ctx.site.publisher.keyId, privateKeyPem: ctx.site.publisher.privateKeyPem }); // Form B 缺 archive.signature
-				const task = await installOnce(ctx, NEG_VERSION);
+				const task = await installOnce(ctx, NEG_VERSION, NEG_NAME);
 				const reason = task.error?.reason ?? task.message;
 				const ok = task.status === "failed" && reason.includes("sig_missing");
 				return { ok, detail: ok ? "failed，失败码 sig_missing（G4 硬 fail-closed）" : `status=${task.status}：${reason}` };
 			}
 			finally {
 				fs.writeFileSync(sig, origSig); // 回抄原始字节
-				await removeVersion(ctx, NEG_VERSION);
+				await removeVersion(ctx, NEG_VERSION, NEG_NAME);
 			}
 		},
 	},
@@ -274,14 +280,14 @@ const OPS: Op[] = [
 		key: "neg-badindex",
 		title: "负向：索引篡改（验签拒载）",
 		run: async (ctx) => {
-			await publishVersion(ctx, NEG_VERSION);
+			await publishVersion(ctx, NEG_VERSION, NEG_NAME);
 			const catalog = path.join(ctx.site.cdnDir, "catalog.yaml");
 			const orig = fs.readFileSync(catalog);
 			try {
 				fs.appendFileSync(catalog, "# tampered\n"); // 索引字节变、签名失配
 				let msg = "";
 				try {
-					await installOnce(ctx, NEG_VERSION);
+					await installOnce(ctx, NEG_VERSION, NEG_NAME);
 				}
 				catch (error) {
 					msg = (error as Error).message; // 预期：安装 POST 即 502，任务都未创建
@@ -291,7 +297,7 @@ const OPS: Op[] = [
 			}
 			finally {
 				writeIndexFile(catalog, orig.toString("utf-8")); // 回抄原始字节（也走唯一写入口，不留下直写索引的路径）
-				await removeVersion(ctx, NEG_VERSION);
+				await removeVersion(ctx, NEG_VERSION, NEG_NAME);
 			}
 		},
 	},
@@ -299,21 +305,21 @@ const OPS: Op[] = [
 		key: "neg-stranger",
 		title: "负向：未登记 key（TOFU 闭环）",
 		run: async (ctx) => {
-			await publishVersion(ctx, NEG_VERSION);
-			const tgz = path.join(ctx.site.cdnDir, `${ctx.name}-${NEG_VERSION}.tgz`);
+			await publishVersion(ctx, NEG_VERSION, NEG_NAME);
+			const tgz = path.join(ctx.site.cdnDir, `${NEG_NAME}-${NEG_VERSION}.tgz`);
 			const sig = `${tgz}.sig`;
 			const orig = fs.readFileSync(tgz);
 			const origSig = fs.readFileSync(sig);
 			const stranger = derivePublisherKey(randomBytes(16).toString("hex")); // 未登记身份，私钥只在内存
 			const before = await trustKeys(ctx); // 信任库快照（F3 diff 基线）
 			try {
-				signCommand(tgz, { id: "stranger.publisher", privateKeyPem: stranger.privateKeyPem }); // 覆盖侧车签名
+				signCommand(tgz, { id: "stranger.publisher", privateKeyPem: stranger.privateKeyPem, registryId: "trial.registry" }); // 覆盖侧车签名（REG-CS3 v2 规范串首段需 registry 身份）
 				await buildIndex({ projectRoot: ctx.site.root, id: "stranger.publisher", privateKeyPem: stranger.privateKeyPem });
-				const first = await installOnce(ctx, NEG_VERSION);
+				const first = await installOnce(ctx, NEG_VERSION, NEG_NAME);
 				if (first.status !== "needs_trust")
 					return { ok: false, detail: `未停 needs_trust：status=${first.status}：${first.message}` };
 				await callApi(fetch, ctx.base, ctx.token, "POST", "/api/_platform/market/trust", { task_id: first.id });
-				const second = await installOnce(ctx, NEG_VERSION);
+				const second = await installOnce(ctx, NEG_VERSION, NEG_NAME);
 				if (second.status !== "done")
 					return { ok: false, detail: `确认后重装未 done：status=${second.status}：${second.message}` };
 				// 收尾（F3）：显式 revoke 陌生 key，快照 diff 断言无残留——不靠 uninstall 兜底（它本就不摘信任）
@@ -332,7 +338,7 @@ const OPS: Op[] = [
 			finally {
 				fs.writeFileSync(tgz, orig); // 回抄原始字节，不重签
 				fs.writeFileSync(sig, origSig);
-				await removeVersion(ctx, NEG_VERSION);
+				await removeVersion(ctx, NEG_VERSION, NEG_NAME);
 			}
 		},
 	},
@@ -343,7 +349,7 @@ const OPS: Op[] = [
 			const evil = path.join(ctx.site.cdnDir, `${ctx.name}-evil.tgz`);
 			buildEvilZipSlipTgz(evil); // 成员含 ../evil.sql，无需发布进索引（file 源直传）
 			const distDir = resolveLayout(ctx.site.root).apiDist;
-			const before = fs.readdirSync(distDir).sort(); // 零副作用基线：9.9.9 目录可能是前序 neg-stranger 的合法产物
+			const before = fs.readdirSync(distDir).sort(); // 零副作用基线：0.0.9 目录可能是前序 neg-stranger 的合法产物
 			try {
 				let msg = "";
 				try {
@@ -421,8 +427,8 @@ async function install(ctx: Ctx, version: string): Promise<TaskRecord> {
 	return task;
 }
 
-async function installOnce(ctx: Ctx, version: string): Promise<TaskRecord> {
-	const started = await callApi<{ task_id?: string, id?: string }>(fetch, ctx.base, ctx.token, "POST", "/api/_platform/market/install", { name: ctx.name, version, source: "cdn" });
+async function installOnce(ctx: Ctx, version: string, name: string = ctx.name): Promise<TaskRecord> {
+	const started = await callApi<{ task_id?: string, id?: string }>(fetch, ctx.base, ctx.token, "POST", "/api/_platform/market/install", { name, version, source: "cdn" });
 	const taskId = String(started.task_id ?? started.id ?? "");
 	if (taskId === "")
 		throw new Error("[ojm] 安装接口未返回 task id");
@@ -438,7 +444,7 @@ async function installFile(ctx: Ctx, tgzPath: string, version: string): Promise<
 	form.append("file", new Blob([fs.readFileSync(tgzPath)], { type: "application/gzip" }), path.basename(tgzPath));
 	const res = await fetch(`${ctx.base}/api/_platform/market/install`, {
 		method: "POST",
-		headers: { authorization: `Bearer ${ctx.token}` },
+		headers: { authorization: `Bearer ${ctx.token}`, ...tenantHeaders() },
 		body: form,
 	});
 	await unwrapEnvelope(res); // 非 0 code 抛人话（400 zip-slip / 502 索引等）
@@ -467,14 +473,14 @@ async function indexCard(ctx: Ctx): Promise<Record<string, unknown> | undefined>
 }
 
 /** 发布某版本 fixture 进隔离 CDN 并重铺索引（upgrade/rollback/neg-* 的共用前置） */
-async function publishVersion(ctx: Ctx, version: string): Promise<void> {
-	await publishPackage({ projectRoot: ctx.site.root, fixture: `${ctx.name}@${version}`, id: ctx.site.publisher.keyId, privateKeyPem: ctx.site.publisher.privateKeyPem, registryId: "trial.registry" });
+async function publishVersion(ctx: Ctx, version: string, name: string = ctx.name): Promise<void> {
+	await publishPackage({ projectRoot: ctx.site.root, fixture: `${name}@${version}`, id: ctx.site.publisher.keyId, privateKeyPem: ctx.site.publisher.privateKeyPem, registryId: "trial.registry" });
 	await buildIndex({ projectRoot: ctx.site.root, id: ctx.site.publisher.keyId, privateKeyPem: ctx.site.publisher.privateKeyPem });
 }
 
 /** neg op 收尾：整包摘除（tgz + 侧车签名）并重铺索引，恢复主链路原状 */
-async function removeVersion(ctx: Ctx, version: string): Promise<void> {
-	for (const file of [`${ctx.name}-${version}.tgz`, `${ctx.name}-${version}.tgz.sig`])
+async function removeVersion(ctx: Ctx, version: string, name: string = ctx.name): Promise<void> {
+	for (const file of [`${name}-${version}.tgz`, `${name}-${version}.tgz.sig`])
 		fs.rmSync(path.join(ctx.site.cdnDir, file), { force: true });
 	await buildIndex({ projectRoot: ctx.site.root, id: ctx.site.publisher.keyId, privateKeyPem: ctx.site.publisher.privateKeyPem });
 }

package/src/site.ts

@@ -6,6 +6,21 @@
 
 import process from "node:process";
 
+/**
+ * 租户头（企微代开发多租户，v3 Phase 0）：宿主 `tenant.enable: true` 时 oj 对每个请求
+ * **强制**要求该头——登录这类匿名端点同样不放过，缺即 `400 missing tenant header`。
+ * 浏览器侧由 runtime 请求层统一注入；CLI 是独立进程，必须自己带上，否则
+ * install / enable / list / market setup / walkthrough / trial 全线打不通站点。
+ * CLI 只以默认租户身份做运维操作（与 templates 的 DEFAULT_TENANT 对齐）。
+ */
+export const TENANT_HEADER = "X-TENANT-ID";
+export const DEFAULT_TENANT = "default";
+
+/** 每个发往站点的请求都要带的租户头 */
+export function tenantHeaders(): Record<string, string> {
+	return { [TENANT_HEADER]: DEFAULT_TENANT };
+}
+
 /** 任务记录（线形状镜像；真源 templates/src/_platform/api/_lifecycle/types.ts:65，客户端不 import 模板内部） */
 export interface TaskRecord {
 	/**
@@ -84,7 +99,7 @@ export async function unwrapEnvelope(res: { ok: boolean, status: number, text: (
 export async function login(fetchFn: typeof fetch, base: string, user: string, pass: string): Promise<string> {
 	const data = await unwrapEnvelope(await fetchFn(`${base}/api/auth/login`, {
 		method: "POST",
-		headers: { "content-type": "application/json" },
+		headers: { "content-type": "application/json", ...tenantHeaders() },
 		body: JSON.stringify({ username: user, password: pass }),
 	})) as { access_token?: string };
 	const token = String(data?.access_token ?? "");
@@ -99,6 +114,7 @@ export async function callApi<T>(fetchFn: typeof fetch, base: string, token: str
 		method,
 		headers: {
 			authorization: `Bearer ${token}`,
+			...tenantHeaders(),
 			...(body === undefined ? {} : { "content-type": "application/json" }),
 		},
 		...(body === undefined ? {} : { body: JSON.stringify(body) }),

package/templates/config.yaml

@@ -35,7 +35,11 @@ server:
   js_heap_limit_bytes: 268435456 # 单 isolate 堆限额（默认 256MiB，下限 32MiB）
   route_timeouts: [] # 路由级超时；pattern 按声明序首个命中，写含 base 的全路径
   response_headers: {} # 统一响应头
-  reload_api: true # 热更端点 /ojm:reload：安装器的 reloading 段要用，关掉安装会失败
+  # 热更端点 /ojm:reload：安装器的 reloading 段要用，关掉安装会失败。
+  # 下面这行是**安装器的文本锚点**（ensureReloadApi 在锚点行下插回 reload_api: true）：
+  # 整行必须逐字等于 `# ojm:reload`，不要删、不要加尾注。
+  # ojm:reload
+  reload_api: true
   blob_upload_max_bytes: 1073741824 # PUT blob 单文件上限（默认 1GiB；与 multipart 的 10MB 是两道闸）
   cors:
     origins: [] # 空 = 放行任意源；要带凭据必须列具体源
@@ -50,11 +54,33 @@ vars:
   # 故意不读请求头 Host（防伪造 Host 牵引出站）：不配 = fail-closed，不会替你猜。
   # canonical_origin: "https://your-site.example.com"
 
+  # ---- 企业微信代开发（服务商侧，部署级常量）----
+  # 一个部署 = 一个服务商账号下的一套代开发模板，所以这 6 个值是「部署」维度，不进 DB。
+  # 「哪个企业装了哪个应用」不写在这里：企微 create_auth 回调推 AuthCode → 换永久授权码 →
+  # 落 wecom_app_profile（主键含 agent_id，同一企业测试/正式两个应用天然并存），
+  # 新增企业只需企业管理员扫码授权，**不改配置、不重启**。
+  # 六项任一为空 → 企微登录整体 400 拒绝服务（宁可不登录，也不明文存 permanent_code）。
+  #   wecom_suite_id          代开发应用模版 id（企微后台「应用管理 → 代开发」里的 SuiteID）
+  #   wecom_suite_secret      套件密钥（SuiteSecret）
+  #   wecom_callback_token    「Token」（回调验签用）
+  #   wecom_encoding_aes_key  「EncodingAESKey」（43 字符，回调解密用）
+  #   wecom_enc_key           permanent_code 落库加密密钥（hex/base64，16 或 32 字节；建议 oj secret keygen）
+  #   wecom_base_url          连接器基址（绝对地址，无尾斜杠），如 https://site.example.com/api/auth/wecom
+  #                           → 企微后台「指令回调URL」填 <base>/event；网页授权 redirect_uri 用 <base>/callback
+  wecom_suite_id: ''
+  wecom_suite_secret: ''
+  wecom_callback_token: ''
+  wecom_encoding_aes_key: ''
+  wecom_enc_key: ''
+  wecom_base_url: ''
+
 platform:
   modules: [_platform] # 安装器热更 config 需要 _platform 特权；删了会在装到最后一步报 NotCapable
   root: src # 后端模块源码根（src/<name>/api 的父目录）；preview 派生 config 时改写成 dist
   # 信任库默认落在安装子树之外（.solutions/trusted-keys.yaml），第三方方案模块碰不到。
-  # 部署侧还应补 platform.trusted_paths 授权 _platform 写库、并把第三方模块 fs.root 收窄到各自安装子树。
+  # U6 加固：第三方模块的 fs 读写范围 = fs.root（= modules/ 安装子树），信任库必须在其外，
+  # 否则方案包可写自己的信任锚（伪造签名来源）。部署侧还应补 platform.trusted_paths 授权
+  # _platform 写库、并把第三方模块 fs.root 收窄到各自安装子树。
   # 下面三条命令与安装器逐字对齐（含每个空格），一个 token 都不能动：
   exec:
     _platform:
@@ -89,3 +115,47 @@ auth:
     - /auth/refresh
     - /auth/logout
     - /system/login-methods # 登录页「登录方式」Tabs 的数据源，未登录就要能读
+    - /auth/wecom/login # 企微授权入口：跳转前必然未登录
+    - /auth/wecom/callback # 企微 302 回跳：code 即凭证，此时还没有本地会话
+    - /auth/wecom/ticket # 一次性票据换 TokenBundle：票据本身就是「刚验过的登录证明」
+    - /auth/wecom/event # 企微指令回调：靠 msg_signature 验签，不走 Bearer
+
+# 多租户（企微代开发 v3 Phase 0）：开启后所有 {base} 请求必须带 X-TENANT-ID，否则 400。
+# 前端由 tenantStore + headerProvider 统一注入（单租户部署恒为 default，UX 不变）。
+tenant:
+  enable: true
+  header_key: X-TENANT-ID
+  sql_guard: deny # 构造器查询自动注入 tenant_id；裸 SQL 漏写/绑错租户直接拒
+  allow_as_tenant: true # 企微 302 回调（浏览器带不了自定义头）用 db.asTenant(服务端推导值) 补身份
+  # 共享表白名单：schema.yaml 里 tenant: false 的表必须在此再列一次，双声明才豁免守卫。
+  # 只放全局映射/凭证/框架目录，不放租户业务数据。
+  shared_allow:
+    - _oj_migrations # oj 迁移 journal（自建自管）
+    - sys_setting # 登录方式发现是未登录端点，此刻无租户上下文（D8）
+    - sys_solution_route # 站点级路由/启用注册表（安装是站点操作）
+    - sys_role # 框架角色目录
+    - sys_permission # 权限码目录
+    - sys_role_permission # 角色→权限映射（同上，分配关系在 sys_user_role）
+    - sys_rate_window # 限速窗口（登录前就要用）
+    - sys_login_throttle # 登录节流（登录前就要用）
+    - market_history # 解决方案安装/升级/回滚是站点级留痕
+    - reg_source_seq # 索引新鲜度水位属于站点（防回放）
+    - wecom_app_profile # 企微 corp→租户映射权威：查它时必然还没有租户上下文（D9）
+    - wecom_suite_ticket # 套件级凭证，按 suite_id 全局唯一
+    - wecom_login_ticket # 一次性登录票据：跨「匿名 302 回跳」与「已认证换取」两段
+  # 豁免缺租户头的路径（去 base 前缀后的形态）。与 auth.anonymous_paths 同语义，
+  # 但这是「没有租户头也不 400」的逃生口，只给**真的拿不到头**的端点。
+  # 登录类端点不在此列：前端 headerProvider 每请求都注头（单租户恒 default），
+  # 少了头应当直接 400 `missing tenant header`，而不是落进匿名态后被 sql_guard 兜成 500。
+  # `/auth/wecom/**` 是例外：企微回调与 302 回跳由浏览器发起，带不了自定义头，
+  # 租户只能由服务端从 profile/票据推导（db.asTenant，见 store.ts::ensureTenant）。
+  anonymous_paths:
+    - /system/login-methods # 登录方式发现：读共享表 sys_setting，天然无租户语义
+    - /auth/wecom/login # 发起授权：此时还没有任何身份
+    - /auth/wecom/callback # 企微 302 回跳：浏览器带不了头，租户由 state→profile 推导
+    - /auth/wecom/ticket # 一次性票据换会话：租户由票据行携带
+    - /auth/wecom/event # 企微指令回调：验签+解密即认证，无租户语义
+  # tenant.require_signed_claim：租户头的服务端绑定（平台级 fail-closed）。
+  # 暂保持 false——上游 oj 的 jwt.sign 目前会静默丢弃自定义 claim（需求 R6），
+  # 开启前无法把 tenant 放进 token。R6 落地后改 true，裸头即失去自证能力。
+  require_signed_claim: false

package/templates/openapi.json

@@ -882,6 +882,325 @@
 				}
 			}
 		},
+		"/api/auth/wecom/admin/apps": {
+			"get": {
+				"operationId": "auth_wecom_admin_apps_get",
+				"summary": "GET api/auth/wecom/admin/apps",
+				"x-oj-file": "auth/wecom/admin/api.ts",
+				"tags": [
+					"auth"
+				],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"required": [
+										"code",
+										"msg",
+										"data"
+									],
+									"properties": {
+										"code": {
+											"type": "integer"
+										},
+										"msg": {
+											"type": "string"
+										},
+										"data": {
+											"type": "array",
+											"items": {
+												"type": "object",
+												"required": [
+													"suite_id",
+													"corp_id",
+													"agent_id",
+													"auth_corp_id",
+													"env",
+													"status",
+													"installed_at",
+													"update_time"
+												],
+												"properties": {
+													"suite_id": {
+														"type": "string"
+													},
+													"corp_id": {
+														"type": "string"
+													},
+													"agent_id": {
+														"type": "string"
+													},
+													"auth_corp_id": {
+														"type": "string"
+													},
+													"env": {
+														"type": "string"
+													},
+													"corp_name": {
+														"type": [
+															"string",
+															"null"
+														]
+													},
+													"status": {
+														"type": "string",
+														"enum": [
+															"active",
+															"disabled"
+														]
+													},
+													"installed_at": {
+														"type": "number"
+													},
+													"update_time": {
+														"type": "number"
+													}
+												}
+											}
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/wecom/admin/status": {
+			"post": {
+				"operationId": "auth_wecom_admin_status_post",
+				"summary": "POST api/auth/wecom/admin/status",
+				"x-oj-file": "auth/wecom/admin/api.ts",
+				"tags": [
+					"auth"
+				],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "object",
+								"required": [
+									"corpId",
+									"agentId",
+									"status"
+								],
+								"properties": {
+									"corpId": {
+										"type": "string",
+										"minLength": 1
+									},
+									"agentId": {
+										"type": "string",
+										"minLength": 1
+									},
+									"status": {
+										"type": "string",
+										"enum": [
+											"active",
+											"disabled"
+										]
+									}
+								}
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"required": [
+										"code",
+										"msg",
+										"data"
+									],
+									"properties": {
+										"code": {
+											"type": "integer"
+										},
+										"msg": {
+											"type": "string"
+										},
+										"data": {
+											"type": "object",
+											"required": [
+												"updated",
+												"revokedSessions"
+											],
+											"properties": {
+												"updated": {
+													"type": "number"
+												},
+												"revokedSessions": {
+													"type": "number"
+												}
+											}
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/wecom/admin/install": {
+			"get": {
+				"operationId": "auth_wecom_admin_install_get",
+				"summary": "GET api/auth/wecom/admin/install",
+				"x-oj-file": "auth/wecom/admin/api.ts",
+				"tags": [
+					"auth"
+				],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"required": [
+										"code",
+										"msg",
+										"data"
+									],
+									"properties": {
+										"code": {
+											"type": "integer"
+										},
+										"msg": {
+											"type": "string"
+										},
+										"data": {
+											"type": "object",
+											"required": [
+												"installUrl",
+												"callbackUrl",
+												"expiresIn"
+											],
+											"properties": {
+												"installUrl": {
+													"type": "string"
+												},
+												"callbackUrl": {
+													"type": "string"
+												},
+												"expiresIn": {
+													"type": "number"
+												}
+											}
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/wecom/login": {
+			"get": {
+				"operationId": "auth_wecom_login_get",
+				"summary": "GET api/auth/wecom/login",
+				"x-oj-file": "auth/wecom/api.ts",
+				"tags": [
+					"auth"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/auth/wecom/callback": {
+			"get": {
+				"operationId": "auth_wecom_callback_get",
+				"summary": "GET api/auth/wecom/callback",
+				"x-oj-file": "auth/wecom/api.ts",
+				"tags": [
+					"auth"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/auth/wecom/ticket": {
+			"post": {
+				"operationId": "auth_wecom_ticket_post",
+				"summary": "POST api/auth/wecom/ticket",
+				"x-oj-file": "auth/wecom/api.ts",
+				"tags": [
+					"auth"
+				],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "object",
+								"required": [
+									"ticket"
+								],
+								"properties": {
+									"ticket": {
+										"type": "string",
+										"minLength": 32,
+										"maxLength": 128
+									}
+								}
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/auth/wecom/event": {
+			"get": {
+				"operationId": "auth_wecom_event_get",
+				"summary": "GET api/auth/wecom/event",
+				"x-oj-file": "auth/wecom/api.ts",
+				"tags": [
+					"auth"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			},
+			"post": {
+				"operationId": "auth_wecom_event_post",
+				"summary": "POST api/auth/wecom/event",
+				"x-oj-file": "auth/wecom/api.ts",
+				"tags": [
+					"auth"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
 		"/api/demo/todos": {
 			"get": {
 				"operationId": "demo_todos_get",

package/templates/src/_platform/api/_lifecycle/steps/download.ts

@@ -8,8 +8,12 @@ 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<{
+/**
+ * 最小 fetch 面（结构化：Node fetch/Response 天然满足；测试注入 stub 不真跑网络）。
+ * init 形参**可选**（cache/头/重定向按需）：少参实现仍可赋给本形，故既有 stub 不受影响；
+ * 探活 Probe 靠它带上租户头（见 steps/smoke.ts）。
+ */
+export type FetchFace = (url: string, init?: { headers?: Record<string, string>, redirect?: string }) => Promise<{
 	ok: boolean
 	status: number
 	arrayBuffer: () => Promise<ArrayBuffer>