@oj-module/cli 0.2.43 → 0.2.46

package/templates/src/auth/api/_shared/wecom/store.ts

@@ -0,0 +1,230 @@
+// 企微三张表 + 租户上下文的持久化面（全部走构造器，交给 sql_guard 管租户）。
+//
+// 表定性（与 schema.yaml / config.shared_allow 三处一致）：
+//   wecom_app_profile / wecom_suite_ticket / wecom_login_ticket 均 `tenant: false`（D9）——
+//   它们本身就是「corp → 租户」的映射权威与套件级凭证，查它们的时候必然还没有租户上下文。
+//   共享 = 不受守卫约束，故只放映射/凭证/一次性票据，不放任何租户业务数据。
+//
+// permanent_code（= 代开发应用的 secret，全 corp 数据权限）只以 AES-GCM 密文落库（§7.5），
+// 加解密经 deps 注入：Node 侧测试用假实现，运行时走 crypto.aesGcmEncrypt/Decrypt。
+import type { WecomConfig } from "./config";
+
+export interface WecomStoreDeps {
+	encrypt: (plain: string) => string
+	decrypt: (blob: string) => string
+	now: () => number
+}
+
+export interface AppProfile {
+	suiteId: string
+	/** 真实企业 ID（get_permanent_code 的 auth_corp_info.corpid）：登录 URL 里的「企业代码」即它 */
+	corpId: string
+	/** 企微事件里的 AuthCorpId（第三方应用体系下可能是 open_corpid，故与 corp_id 分列存） */
+	authCorpId: string
+	agentId: string
+	/** 测试/正式等部署标签（D5：只作标签，不参与主键） */
+	env: string
+	corpName: string | null
+	status: "active" | "disabled"
+	permanentCode: string
+}
+
+/** 套件票据：企微每 10 分钟推一次，有效期 30 分钟；过期不得发起任何套件级 API 调用 */
+export interface SuiteTicket {
+	ticket: string
+	expiresAt: number
+}
+
+export interface LoginTicketRow {
+	uid: number
+	/** 票据所属租户（列名 `owner_tenant`：共享表不声明 tenant_id，见 migration 头注释） */
+	ownerTenant: string
+}
+
+function fail(status: number, message: string): never {
+	throw Object.assign(new Error(message), { status });
+}
+
+/**
+ * 把请求绑到指定租户（L2 的第四层）：浏览器 302 回调带不了自定义头 → 请求是匿名态，
+ * 用 db.asTenant(服务端推导值) 补身份。已带头则只做一致性复核（不符即伪造，403）。
+ * 注意 asTenant 是**请求级且只能设一次**（oj 手册），故这里不重复调用。
+ */
+export function ensureTenant(tenantId: string): void {
+	const current = http.tenantId;
+	if (current == null || current === "") {
+		db.asTenant(tenantId);
+		return;
+	}
+	if (current !== tenantId)
+		fail(403, "tenant header does not match the authenticated tenant");
+}
+
+/** 企微回调推导出来的租户键：直接就是企业 ID（D10：企业代码=corp_id，故 URL/头/隔离列三者同值） */
+export function tenantOfCorp(corpId: string): string {
+	return corpId;
+}
+
+/**
+ * 企业匹配谓词（corp_id 与 auth_corp_id 双列等价命中：代开发拿到的是 corp_id，
+ * 第三方/open_corpid 落到 auth_corp_id）。
+ * 抽取理由：清单 / 启停 / 停企业三处原本各写一份 `or: [...]`，任一处漏一列的表现都是
+ * 「某类企业查不到」，而它只在真实第三方身份下才出现。
+ */
+export function corpScope(corpId: string) {
+	return {
+		or: [
+			{ field: "corp_id", op: "eq", value: corpId },
+			{ field: "auth_corp_id", op: "eq", value: corpId },
+		],
+	};
+}
+
+/** 企业 + 应用（profile 主键的两段：一次授权多家应用时按 agent 逐个命中） */
+export function corpAgentScope(corpId: string, agentId: string) {
+	return {
+		and: [
+			corpScope(corpId),
+			{ field: "agent_id", op: "eq", value: agentId },
+		],
+	};
+}
+
+/**
+ * 吊销某租户的全部会话（refresh token）。
+ *
+ * 用带 `tenant_id` 的裸 SQL 而不是 `truncate()`：后者靠「守卫自动注入当前租户」生效，
+ * 而 `db.asTenant` 一次请求只能设一次、且要求当时还没租户——本次请求是否处于匿名态
+ * 决定了 truncate 的清理范围，边界交给了上游实现。条件写死在 SQL 里，范围自带。
+ */
+export async function revokeTenantSessions(tenantId: string): Promise<number> {
+	return Number(await db.exec("DELETE FROM sys_refresh_token WHERE tenant_id = ?", [tenantId]));
+}
+
+function isUniqueViolation(e: unknown): boolean {
+	return /unique|constraint/i.test(e instanceof Error ? e.message : String(e));
+}
+
+export async function saveProfile(p: Omit<AppProfile, "status"> & { status?: AppProfile["status"] }, deps: WecomStoreDeps): Promise<void> {
+	const now = deps.now();
+	const scope = {
+		and: [
+			{ field: "suite_id", op: "eq", value: p.suiteId },
+			corpAgentScope(p.corpId, p.agentId),
+		],
+	};
+	const rows = await db.table("wecom_app_profile").select(["suite_id"]).where(scope).all();
+	const cols = {
+		auth_corp_id: p.authCorpId,
+		env: p.env,
+		corp_name: p.corpName,
+		status: p.status ?? "active",
+		permanent_code_enc: deps.encrypt(p.permanentCode),
+		update_time: now,
+	};
+	if (rows.length) {
+		await db.table("wecom_app_profile").update(cols).where(scope).run();
+		return;
+	}
+	try {
+		await db.table("wecom_app_profile").insert({ suite_id: p.suiteId, corp_id: p.corpId, agent_id: p.agentId, installed_at: now, ...cols }).run();
+	}
+	catch (e) {
+		// 并发插入者先落（企微 5 秒未拿到 success 就重推，两条 create_auth 撞车是常态）：
+		// 撞 (suite_id, corp_id, agent_id) 即转为更新，不让它以 500 收场——
+		// 否则企微再推第三次，这次授权就有可能在还剩一次重推时被判死。
+		if (!isUniqueViolation(e))
+			throw e;
+		await db.table("wecom_app_profile").update(cols).where(scope).run();
+	}
+}
+
+/**
+ * 按企业代码找应用。`agentId` 为空时要求该企业只有一个启用中的应用。
+ * 「企业不存在」与「已停用」返回**同一条文案**（§5.3 枚举风险：不让外部探测哪些企业装过）。
+ */
+export async function findProfile(corpId: string, agentId: string | null, deps: WecomStoreDeps): Promise<AppProfile> {
+	const rows = await db.table("wecom_app_profile").select(["*"]).where(corpScope(corpId)).all() as Array<Record<string, unknown>>;
+	const active = rows.filter(r => String(r.status) === "active");
+	const picked = agentId ? active.filter(r => String(r.agent_id) === agentId) : active;
+	if (picked.length === 0)
+		fail(400, "企业代码无效或应用未开通");
+	if (picked.length > 1)
+		fail(400, "该企业开通了多个应用，登录链接必须带 agent 参数");
+	const r = picked[0]!;
+	return {
+		suiteId: String(r.suite_id),
+		corpId: String(r.corp_id),
+		authCorpId: r.auth_corp_id == null ? String(r.corp_id) : String(r.auth_corp_id),
+		agentId: String(r.agent_id),
+		env: r.env == null ? "prod" : String(r.env),
+		corpName: r.corp_name == null ? null : String(r.corp_name),
+		status: String(r.status) === "disabled" ? "disabled" : "active",
+		permanentCode: deps.decrypt(String(r.permanent_code_enc)),
+	};
+}
+
+/** 停用/解绑：只改状态，不删行（取消授权也要留痕，§7.5 审计） */
+export async function setProfileStatus(corpId: string, status: AppProfile["status"], deps: WecomStoreDeps): Promise<number> {
+	return Number(await db.table("wecom_app_profile").update({ status, update_time: deps.now() }).where(corpScope(corpId)).run());
+}
+
+export async function putSuiteTicket(suiteId: string, ticket: string, expiresAt: number, deps: WecomStoreDeps): Promise<void> {
+	const rows = await db.table("wecom_suite_ticket").select(["suite_id"]).where({ field: "suite_id", op: "eq", value: suiteId }).all();
+	const cols = { suite_ticket: ticket, expires_at: expiresAt, update_time: deps.now() };
+	if (rows.length)
+		await db.table("wecom_suite_ticket").update(cols).where({ field: "suite_id", op: "eq", value: suiteId }).run();
+	else
+		await db.table("wecom_suite_ticket").insert({ suite_id: suiteId, ...cols }).run();
+}
+
+/** 套件票据（过期作废：过期后调 get_suite_token 会被企微拒，故本地先拒，省一次往返与一次失败计数） */
+export async function getSuiteTicket(suiteId: string, deps: WecomStoreDeps): Promise<SuiteTicket> {
+	const rows = await db.table("wecom_suite_ticket").select(["suite_ticket", "expires_at"]).where({ field: "suite_id", op: "eq", value: suiteId }).all() as Array<Record<string, unknown>>;
+	const row = rows[0];
+	if (!row)
+		fail(503, "企微套件票据（suite_ticket）尚未收到：回调 URL 未打通或企微尚未推送");
+	const expiresAt = Number(row.expires_at);
+	if (!Number.isFinite(expiresAt) || expiresAt <= deps.now())
+		fail(503, "企微套件票据（suite_ticket）已过期：企微每 10 分钟推送一次，请检查回调 URL");
+	return { ticket: String(row.suite_ticket), expiresAt };
+}
+
+/** 一次性登录票据：只存 SHA-256，明文只出现在 302 的 URL 与 SPA 内存里 */
+export async function issueLoginTicket(ticketHash: string, uid: number, ownerTenant: string, ttlSecs: number, deps: WecomStoreDeps): Promise<void> {
+	const now = deps.now();
+	// 顺手清过期票（共享表、无租户语义；避免长期累积；失败不影响签发）
+	await db.table("wecom_login_ticket").where({ field: "expires_at", op: "lt", value: now }).delete().run();
+	await db.table("wecom_login_ticket").insert({ ticket_hash: ticketHash, uid, owner_tenant: ownerTenant, expires_at: now + ttlSecs, used: 0, created_at: now }).run();
+}
+
+/**
+ * 兑换登录票据（原子单次消费）：先 `update used=1 where used=0` 抢所有权——
+ * 抢不到说明已被用/伪造；抢到再校验过期。并发双花只可能有一个 changes=1。
+ */
+export async function claimLoginTicket(ticketHash: string, deps: WecomStoreDeps): Promise<LoginTicketRow> {
+	const changed = Number(await db.table("wecom_login_ticket").update({ used: 1 }).where({
+		and: [
+			{ field: "ticket_hash", op: "eq", value: ticketHash },
+			{ field: "used", op: "eq", value: 0 },
+		],
+	}).run());
+	if (changed !== 1)
+		fail(401, "登录票据无效或已使用");
+	const rows = await db.table("wecom_login_ticket").select(["uid", "owner_tenant", "expires_at"]).where({ field: "ticket_hash", op: "eq", value: ticketHash }).all() as Array<Record<string, unknown>>;
+	const row = rows[0];
+	if (!row)
+		fail(401, "登录票据无效或已使用");
+	if (Number(row.expires_at) <= deps.now())
+		fail(401, "登录票据已过期，请重新登录");
+	return { uid: Number(row.uid), ownerTenant: String(row.owner_tenant) };
+}
+
+/** 运行时依赖：密钥取自部署常量，加密原语取自 oj 运行时全局 */
+export function runtimeStoreDeps(cfg: WecomConfig): WecomStoreDeps {
+	return {
+		encrypt: (plain: string) => crypto.aesGcmEncrypt(plain, cfg.encKey),
+		decrypt: (blob: string) => crypto.aesGcmDecrypt(blob, cfg.encKey),
+		now: () => Math.floor(Date.now() / 1000),
+	};
+}

package/templates/src/auth/api/_shared/wecom/xml.ts

@@ -0,0 +1,36 @@
+// 企微消息 XML 取字段（只读、白名单式）。
+// 为什么不用通用 XML 解析：明文已由 AES-CBC + msg_signature 双重认证（见 crypt.ts），
+// 这里只从**可信明文**里取几个扁平标签，且标签名由调用方常量给出——不解析结构、不处理命名空间，
+// 用正则换掉一个解析器依赖与它的实体展开攻击面。标签名非纯字母直接抛错（防拼接正则）。
+// 未命中返回 null（「没这个字段」与「字段为空」由调用方区分）。
+
+const XML_ENTITIES: Record<string, string> = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+};
+
+function decodeEntities(s: string): string {
+	return s.replace(/&(amp|lt|gt|quot|apos|#\d+|#x[\da-f]+);/gi, (whole, body: string) => {
+		if (body[0] === "#") {
+			const code = body[1] === "x" || body[1] === "X"
+				? Number.parseInt(body.slice(2), 16)
+				: Number.parseInt(body.slice(1), 10);
+			return Number.isFinite(code) && code > 0 && code <= 0x10FFFF ? String.fromCodePoint(code) : whole;
+		}
+		return XML_ENTITIES[body.toLowerCase()] ?? whole;
+	});
+}
+
+/** 取 `<Name>值</Name>`（支持 CDATA 与实体）；未命中 null */
+export function xmlField(xml: string, name: string): string | null {
+	if (!/^[A-Z_]\w*$/i.test(name))
+		throw new Error(`xml: illegal field name ${name}`);
+	const re = new RegExp(`<${name}>(?:<!\\[CDATA\\[([\\s\\S]*?)\\]\\]>|([\\s\\S]*?))</${name}>`);
+	const m = re.exec(xml);
+	if (!m)
+		return null;
+	return decodeEntities((m[1] ?? m[2] ?? "").trim());
+}

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

@@ -1,6 +1,12 @@
 name: auth
 desc: JWT 鉴权端点（业务路由）：login/refresh/logout；Bearer 守卫由 oj-auth 提供
 version: 0.1.0
+# 企微代开发 connector 的三张表（schema.yaml 定性 + migrations/0001__wecom* 建表）：
+# 共享表，只放 corp→租户映射 / 套件凭证 / 一次性登录票据，不放租户业务数据。
+tables:
+  - wecom_app_profile
+  - wecom_suite_ticket
+  - wecom_login_ticket
 deps: # 两处都用：login/refresh 读 _platform.users（ownership_guard: deny，§3/S003）；
   # 跨模块别名 `#/_platform/…` 的依赖门禁（oj build S008）
   _platform: ^0.1.0

package/templates/src/auth/api/migrations/0001__wecom.mysql.sql

@@ -0,0 +1,35 @@
+-- 企微代开发三表 mysql 方言覆盖（方言覆盖必胜，通用兜底；oj-bin docs/migration.md §3.1）。
+-- 差异：TEXT 主键须给长度（按业务长度收窄为 VARCHAR）；INTEGER → BIGINT（秒级 epoch）；
+-- 复合主键里 VARCHAR 合计长度须可进 InnoDB 索引；索引写在 CREATE TABLE 内（MySQL 无 CREATE INDEX IF NOT EXISTS）。
+CREATE TABLE IF NOT EXISTS wecom_app_profile (
+  suite_id VARCHAR(64) NOT NULL,
+  corp_id VARCHAR(64) NOT NULL,
+  agent_id VARCHAR(32) NOT NULL,
+  auth_corp_id VARCHAR(64) NOT NULL,
+  env VARCHAR(32) NOT NULL DEFAULT 'prod',
+  corp_name VARCHAR(255),
+  status VARCHAR(16) NOT NULL DEFAULT 'active',
+  permanent_code_enc TEXT NOT NULL,
+  installed_at BIGINT NOT NULL,
+  update_time BIGINT NOT NULL,
+  PRIMARY KEY (suite_id, corp_id, agent_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE IF NOT EXISTS wecom_suite_ticket (
+  suite_id VARCHAR(64) NOT NULL,
+  suite_ticket TEXT NOT NULL,
+  expires_at BIGINT NOT NULL,
+  update_time BIGINT NOT NULL,
+  PRIMARY KEY (suite_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE IF NOT EXISTS wecom_login_ticket (
+  ticket_hash CHAR(64) NOT NULL,
+  uid BIGINT NOT NULL,
+  owner_tenant VARCHAR(128) NOT NULL,
+  expires_at BIGINT NOT NULL,
+  used INTEGER NOT NULL DEFAULT 0,
+  created_at BIGINT NOT NULL,
+  PRIMARY KEY (ticket_hash),
+  KEY idx_wecom_login_ticket_expires (expires_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

package/templates/src/auth/api/migrations/0001__wecom.pg.sql

@@ -0,0 +1,33 @@
+-- 企微代开发三表 pg 方言覆盖（方言覆盖必胜，通用兜底；oj-bin docs/migration.md §3.1）。
+-- 差异：INTEGER → BIGINT（秒级 epoch）；TEXT 在 pg 合法，主键/密文列保留 TEXT。
+CREATE TABLE IF NOT EXISTS wecom_app_profile (
+  suite_id TEXT NOT NULL,
+  corp_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  auth_corp_id TEXT NOT NULL,
+  env TEXT NOT NULL DEFAULT 'prod',
+  corp_name TEXT,
+  status TEXT NOT NULL DEFAULT 'active',
+  permanent_code_enc TEXT NOT NULL,
+  installed_at BIGINT NOT NULL,
+  update_time BIGINT NOT NULL,
+  PRIMARY KEY (suite_id, corp_id, agent_id)
+);
+
+CREATE TABLE IF NOT EXISTS wecom_suite_ticket (
+  suite_id TEXT NOT NULL PRIMARY KEY,
+  suite_ticket TEXT NOT NULL,
+  expires_at BIGINT NOT NULL,
+  update_time BIGINT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS wecom_login_ticket (
+  ticket_hash TEXT NOT NULL PRIMARY KEY,
+  uid BIGINT NOT NULL,
+  owner_tenant TEXT NOT NULL,
+  expires_at BIGINT NOT NULL,
+  used INTEGER NOT NULL DEFAULT 0,
+  created_at BIGINT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_wecom_login_ticket_expires ON wecom_login_ticket (expires_at);

package/templates/src/auth/api/migrations/0001__wecom.sql

@@ -0,0 +1,47 @@
+-- 企微代开发 connector 的三张表（阶段 P1）。结构只进 migrations（S006），列集与 schema.yaml 一致。
+--
+-- 定性（三处必须一致：本文件头 / schema.yaml `tenant: false` / config.yaml `tenant.shared_allow`）：
+--   三张表全部**共享表**——它们在「还没有租户上下文」的时刻被读写：
+--     · wecom_app_profile 本身就是 corp → 租户的映射权威（查它的时候必然不知道租户）；
+--     · wecom_suite_ticket 是套件级凭证，按 suite_id 全局唯一；
+--     · wecom_login_ticket 跨「匿名 302 回跳」与「已认证换取」两段，票据本身携带租户。
+--   共享 = 不受 sql_guard 约束，故只放映射/凭证/一次性票据，不放任何租户业务数据。
+--
+-- 凭证保密（§7.5）：permanent_code 即代开发应用的 secret（具备全 corp 数据权限），
+-- 只以 AES-GCM 密文落库（crypto.aesGcmEncrypt，密钥取部署常量 wecom_enc_key），列名带 _enc 后缀。
+CREATE TABLE IF NOT EXISTS wecom_app_profile (
+  suite_id TEXT NOT NULL,
+  corp_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  auth_corp_id TEXT NOT NULL,
+  env TEXT NOT NULL DEFAULT 'prod',
+  corp_name TEXT,
+  status TEXT NOT NULL DEFAULT 'active',
+  permanent_code_enc TEXT NOT NULL,
+  installed_at INTEGER NOT NULL,
+  update_time INTEGER NOT NULL,
+  PRIMARY KEY (suite_id, corp_id, agent_id)
+);
+
+CREATE TABLE IF NOT EXISTS wecom_suite_ticket (
+  suite_id TEXT NOT NULL PRIMARY KEY,
+  suite_ticket TEXT NOT NULL,
+  expires_at INTEGER NOT NULL,
+  update_time INTEGER NOT NULL
+);
+
+-- 一次性登录票据：302 的 URL 里只能放票，不能放 access/refresh token（会被浏览器历史、
+-- Referer、反代日志留存）。只存 SHA-256，明文仅存在于 302 Location 与 SPA 内存。
+-- 列名用 owner_tenant 而不是 tenant_id：本表是共享表，出现 tenant_id 列会被
+-- 「tenant:false 却声明隔离列」的定性红线判为自相矛盾，而它的语义是「票据绑定的租户」。
+CREATE TABLE IF NOT EXISTS wecom_login_ticket (
+  ticket_hash TEXT NOT NULL PRIMARY KEY,
+  uid INTEGER NOT NULL,
+  owner_tenant TEXT NOT NULL,
+  expires_at INTEGER NOT NULL,
+  used INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL
+);
+
+-- 过期票清理按 expires_at 扫（签发时顺手删）；无索引会全表扫
+CREATE INDEX IF NOT EXISTS idx_wecom_login_ticket_expires ON wecom_login_ticket (expires_at);

package/templates/src/auth/api/schema.yaml

@@ -0,0 +1,48 @@
+# 声明式表结构（§4.2 / D1-C）：auth 模块自有表——企微代开发 connector 的三张表。
+# 结构真源是 migrations/0001__wecom*.sql（S006）；本文件负责「列集/主键/租户定性」的运行时元数据，
+# 与迁移逐列对齐（列集不一致时 oj 的 schema 校验会 fail-fast）。
+#
+# 定性（三处一致：这里 / config.yaml `tenant.shared_allow` / 迁移文件头注释）：
+# 三张表都是**共享表**（`tenant: false`）——它们在「还没有租户上下文」的时刻被读写，
+# 而且本身就是 corp → 租户的映射权威。只放映射/凭证/一次性票据，不放租户业务数据。
+tables:
+  wecom_app_profile:
+    # 共享表：corp → 租户的映射权威，查它时必然还不知道租户（D9）
+    tenant: false
+    pk: [suite_id, corp_id, agent_id]
+    columns:
+      suite_id: {type: text, null: false}
+      corp_id: {type: text, null: false}
+      agent_id: {type: text, null: false}
+      # 企微事件里的 AuthCorpId：第三方应用体系下可能是 open_corpid，故与 corp_id 分列存
+      auth_corp_id: {type: text, null: false}
+      # 测试/正式等部署标签（D5：只作标签，不参与主键）
+      env: {type: text, null: false}
+      corp_name: {type: text}
+      # active / disabled：取消授权只改状态不删行（留痕）
+      status: {type: text, null: false}
+      # permanent_code（= 代开发应用的 secret）的 AES-GCM 密文，禁止明文落库
+      permanent_code_enc: {type: text, null: false}
+      installed_at: {type: integer, null: false}
+      update_time: {type: integer, null: false}
+  wecom_suite_ticket:
+    # 共享表：套件级凭证，按 suite_id 全局唯一（每 10 分钟被企微覆盖一次）
+    tenant: false
+    pk: suite_id
+    columns:
+      suite_id: {type: text, null: false}
+      suite_ticket: {type: text, null: false}
+      expires_at: {type: integer, null: false}
+      update_time: {type: integer, null: false}
+  wecom_login_ticket:
+    # 共享表：一次性登录票据，跨「匿名 302 回跳」与「已认证换取」两段
+    tenant: false
+    pk: ticket_hash
+    columns:
+      ticket_hash: {type: text, null: false}
+      uid: {type: integer, null: false}
+      # 票据绑定的租户。不叫 tenant_id：共享表出现隔离列会被定性红线判为自相矛盾
+      owner_tenant: {type: text, null: false}
+      expires_at: {type: integer, null: false}
+      used: {type: integer, null: false}
+      created_at: {type: integer, null: false}

package/templates/src/auth/api/wecom/admin/api.ts

@@ -0,0 +1,121 @@
+// 代开发后台（服务商运营面）：GET /auth/wecom/admin/apps · POST /auth/wecom/admin/status · GET /auth/wecom/admin/install
+//
+// 权限：仅超级管理员（`assertSuperAdmin`）。这三件事都是**跨租户**的站点级操作
+// （看所有已授权企业、停用某企业、生成安装链接），不是某个租户的管理员能做的；
+// 用 `assertSystemAdmin` 会把 admin 也放进来，而 admin 属于某个租户，等于让他看别家企业的 corp_id。
+//
+// 三个端点都不挂在 `tenant.anonymous_paths` 里：它们是正常登录后的管理面，必须带租户头，
+// 也就不会走 `db.asTenant`（见 _shared/wecom/admin.ts 头注释第 2 点）。
+import { respond } from "#/_platform/_shared/respond";
+import { assertSuperAdmin } from "#/_platform/_shared/service/infra/access";
+import { recordOp } from "#/_platform/_shared/service/infra/audit";
+import { createInstall, listApps, setAppStatus } from "../../_shared/wecom/admin";
+import { createWecomClient, runtimeCache, runtimeHttp } from "../../_shared/wecom/client";
+import { readWecomConfig } from "../../_shared/wecom/config";
+import { runtimeStoreDeps } from "../../_shared/wecom/store";
+
+/** 清单：已授权企业 × 应用（不含 permanent_code，secret 不出库） */
+async function get() {
+	await respond(async () => {
+		await assertSuperAdmin();
+		return listApps();
+	});
+}
+get.response = {
+	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" },
+		},
+	},
+};
+
+const status = {
+	// 启停某个企业的一个应用。停用是安全动作：企业整体停用时同步吊销其会话（见 admin.ts）。
+	async post() {
+		await respond(async () => {
+			await assertSuperAdmin();
+			const body = (http.body ?? {}) as { corpId?: unknown, agentId?: unknown, status?: unknown };
+			const corpId = String(body.corpId ?? "").trim();
+			const agentId = String(body.agentId ?? "").trim();
+			const next = String(body.status ?? "").trim();
+			if (!corpId || !agentId)
+				throw Object.assign(new Error("缺少企业代码或应用 id"), { status: 400 });
+			if (next !== "active" && next !== "disabled")
+				throw Object.assign(new Error("status 只能是 active 或 disabled"), { status: 400 });
+
+			const result = await setAppStatus(corpId, agentId, next, {
+				client: createWecomClient({ http: runtimeHttp(), cache: runtimeCache() }),
+				// 只有 update_time 用到 now，加解密用不上：这里给空实现，避免为一个时间戳去读部署常量
+				store: { encrypt: () => "", decrypt: () => "", now: () => Math.floor(Date.now() / 1000) },
+			});
+			await recordOp({
+				action: next === "active" ? "wecom.admin.enable" : "wecom.admin.disable",
+				module: "auth",
+				target: corpId,
+				detail: { agentId, revokedSessions: result.revokedSessions },
+				// 停用是断人访问的动作，按安全事件留痕（与 cancel_auth 同级）
+				level: next === "active" ? 2 : 4,
+			});
+			return result;
+		});
+	},
+};
+status.post.schema = {
+	body: {
+		type: "object",
+		required: ["corpId", "agentId", "status"],
+		properties: {
+			corpId: { type: "string", minLength: 1 },
+			agentId: { type: "string", minLength: 1 },
+			status: { type: "string", enum: ["active", "disabled"] },
+		},
+	},
+};
+status.post.response = {
+	type: "object",
+	required: ["updated", "revokedSessions"],
+	properties: {
+		updated: { type: "number" },
+		revokedSessions: { type: "number" },
+	},
+};
+
+const install = {
+	// 开通入口：生成 install URL（预授权码 10 分钟有效，故不缓存，每次点都重新换）。
+	// 顺带回「指令回调 URL」——服务商后台要把它逐字填进企微「代开发」配置页。
+	async get() {
+		await respond(async () => {
+			await assertSuperAdmin();
+			const cfg = readWecomConfig();
+			const state = String((http.query as Record<string, unknown>)?.state ?? "").trim();
+			return createInstall(
+				cfg,
+				createWecomClient({ http: runtimeHttp(), cache: runtimeCache() }),
+				runtimeStoreDeps(cfg),
+				state,
+			);
+		});
+	},
+};
+install.get.response = {
+	type: "object",
+	required: ["installUrl", "callbackUrl", "expiresIn"],
+	properties: {
+		installUrl: { type: "string" },
+		callbackUrl: { type: "string" },
+		expiresIn: { type: "number" },
+	},
+};
+
+export default { apps: { get }, status, install };