@oj-module/cli 0.2.49 → 0.2.50

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

@@ -1,4 +1,5 @@
-import type { WecomConfig } from "../_shared/wecom/config";
+import type { CallbackCreds, WecomKind } from "../_shared/wecom/config";
+import type { SelfApp } from "../_shared/wecom/login";
 import type { CallbackFields } from "../_shared/wecom/payload";
 import type { ReplayClaim } from "../_shared/wecom/replay";
 import type { WecomStoreDeps } from "../_shared/wecom/store";
@@ -6,7 +7,7 @@ import type { WecomStoreDeps } from "../_shared/wecom/store";
 // GET  /api/auth/wecom/callback?code=&state=     —— 企微回跳：code→userid→JIT→一次性票据→302 SPA
 // POST /api/auth/wecom/ticket  {ticket}          —— 一次性票据换 TokenBundle（token 不进 URL）
 // GET  /api/auth/wecom/event                     —— 企微回调 URL 验证（echostr 解出后原样回）
-// POST /api/auth/wecom/event                     —— 企微指令回调（suite_ticket / 授权 / 解绑）
+// POST /api/auth/wecom/event                     —— 企微回调（代开发指令事件 / 自建应用通讯录变更）
 //
 // 三处纪律：
 //   1. 两个 302 端点**不能**用 respond（它末尾无脑 json.ok，会把 302 覆盖成 200 信封）——
@@ -19,25 +20,36 @@ import { failWith, respond } from "#/_platform/_shared/respond";
 import { clientIp, guardLoginThrottle, noteLoginFailed, noteLoginSucceeded } from "../_shared/login-throttle";
 import { createSession } from "../_shared/session";
 import { createWecomClient, runtimeCache, runtimeHttp } from "../_shared/wecom/client";
-import { loginRedirectOf, readCallbackConfig, readWecomConfig, siteRootOf } from "../_shared/wecom/config";
+import {
+
+	callbackCreds,
+	loginRedirectOf,
+	readBase,
+	readCorpConfig,
+	readSuiteConfig,
+	siteRootOf,
+	wecomKinds,
+} from "../_shared/wecom/config";
+import { handleContactChange } from "../_shared/wecom/contacts";
 import { sha1Hex, unwrapWecomMessage, wecomSignature } from "../_shared/wecom/crypt";
 import { handleSuiteEvent } from "../_shared/wecom/events";
 import {
 	assertUserActive,
 	buildAuthorizeUrl,
-	resolveWecomProfile,
 	ensureWecomUser,
 	LOGIN_TICKET_TTL_SECS,
 	loginLandingUrl,
 	putLoginState,
+	resolveWecomProfile,
+
 	selfUpdate,
 	takeLoginState,
 } from "../_shared/wecom/login";
 import { callbackFields, field } from "../_shared/wecom/payload";
-import { guardReplay, runtimeReplayGate, ReplayAlreadyApplied, markApplied } from "../_shared/wecom/replay";
+import { guardReplay, markApplied, ReplayAlreadyApplied, runtimeReplayGate } from "../_shared/wecom/replay";
 import { claimLoginTicket, ensureTenant, findProfile, issueLoginTicket, runtimeStoreDeps, tenantOfCorp } from "../_shared/wecom/store";
 
-// 模块级禁止 readWecomConfig()/createSession()/runtimeHttp()：oj build 的 introspect 在空沙箱里
+// 模块级禁止 readBase()/createSession()/runtimeHttp()：oj build 的 introspect 在空沙箱里
 // 评估模块（无 vars/jwt/fetch），一律在 handler 内按需构造（§9.4）。
 
 /** 请求头的读取按大小写不敏感处理（http.headers 的键大小写随客户端） */
@@ -62,6 +74,19 @@ function badRequest(message: string): Error {
 	return Object.assign(new Error(message), { status: 400 });
 }
 
+/**
+ * 本部署自己那家企业内部应用（配了 `wecom_corp_*` 才有）。
+ *
+ * 作用是给登录入口一个**确定的默认目标**，而不是去猜档案里哪一行是「本站自己」：共存部署里
+ * 档案表还有别家企业通过代开发装进来的行，猜的代价是本站 `/login` 反过来回 400。
+ */
+function corpSelf(): SelfApp | undefined {
+	if (!wecomKinds().includes("corp"))
+		return undefined;
+	const c = readCorpConfig();
+	return { corpId: c.corpId, agentId: c.agentId };
+}
+
 /**
  * 解不开时把「哪一侧配错」记进日志——只回一句 `pkcs7: bad padding` 等于没给线索。
  *
@@ -70,23 +95,26 @@ function badRequest(message: string): Error {
  *     一个字符），或这条推送其实来自另一个套件/模板（那把钥匙解不开这份密文）。
  *     `aesKeyFp` 是本进程**实际加载**那把钥匙的指纹：改完 config 对不上就说明没生效（没重启/改错文件）。
  *   · `receiver mismatch` → **钥匙对、身份不对**。`receiveid` 已按候选试过（见 unwrapAccepting：
- *     suite_id + 信封 `ToUserName`），两边都对不上只剩两种：信封里没有 `ToUserName`，或这条推送
- *     既不属本部署套件、receiveid 也不是它自己声称的身份（伪造/转发）。
+ *     凭据自己的 receiver + 信封 `ToUserName`），两边都对不上只剩两种：信封里没有 `ToUserName`，
+ *     或这条推送既不属本部署、receiveid 也不是它自己声称的身份（伪造/转发）。
  *
- * 注意 `envelopeToUser` **不等于** `configuredSuite` 是正常的：数据回调的 `ToUserName` 是 corpid。
+ * `kind` 必须记：共存部署里有两套钥匙，日志不写「这次用的是哪套」，排障就退化成猜。
+ * 注意 `envelopeToUser` **不等于** `configuredReceiver` 是正常的：数据回调的 `ToUserName` 是 corpid。
  */
-function noteDecryptFailure(e: unknown, envelope: CallbackFields | null, cfg: { encodingAesKey: string, suiteId: string }): void {
+function noteDecryptFailure(e: unknown, envelope: CallbackFields | null, creds: CallbackCreds): void {
 	log.warn(
 		"wecom callback decrypt failed",
 		"reason",
 		(e as Error).message,
+		"kind",
+		creds.kind,
 		"envelopeToUser",
 		// URL 验证（GET）只有 query 里的 echostr，没有报文信封——那一侧记空串
 		envelope ? field(envelope, "ToUserName") : "",
-		"configuredSuite",
-		cfg.suiteId,
+		"configuredReceiver",
+		creds.receiver,
 		"aesKeyFp",
-		sha1Hex(cfg.encodingAesKey).slice(0, 8),
+		sha1Hex(creds.encodingAesKey).slice(0, 8),
 	);
 }
 
@@ -94,12 +122,12 @@ function noteDecryptFailure(e: unknown, envelope: CallbackFields | null, cfg: {
  * 按「可能合法的 receiveid」依次尝试解密。
  *
  * receiveid 的含义随场景变（90968 附注）：**第三方事件的回调是 suiteid**（suite_ticket / create_auth
- * / cancel_auth），**企业应用（含代开发应用的数据回调）是 corpid**（通讯录变更就走这条）。
+ * / cancel_auth），**企业应用（含代开发应用的数据回调、自建应用的通讯录事件）是 corpid**。
  * 我们一个端点吃两种，只认 suiteid 会把所有数据回调判成「解密失败」——而真正的错是「比错了值」。
  *
  * 只对 `receiver mismatch` 换下一个候选：`bad padding` 说明密钥就不对，换谁都解不开，直接抛。
  */
-function unwrapAccepting(encrypted: string, cfg: WecomConfig, candidates: string[]): string {
+function unwrapAccepting(encrypted: string, creds: CallbackCreds, candidates: string[]): string {
 	let lastErr: unknown;
 	const tried = new Set<string>();
 	for (const receiver of candidates) {
@@ -107,7 +135,7 @@ function unwrapAccepting(encrypted: string, cfg: WecomConfig, candidates: string
 			continue;
 		tried.add(receiver);
 		try {
-			return unwrapWecomMessage(encrypted, cfg.encodingAesKey, receiver);
+			return unwrapWecomMessage(encrypted, creds.encodingAesKey, receiver);
 		}
 		catch (e) {
 			if (!/receiver mismatch/.test((e as Error).message))
@@ -118,6 +146,14 @@ function unwrapAccepting(encrypted: string, cfg: WecomConfig, candidates: string
 	throw lastErr ?? new Error("wecom: 没有可比对的 receiveid（suite_id 未配置？）");
 }
 
+/** 用哪一把钥匙能验过签名：**逐个试**（SHA1 一次，成本可忽略），命中即用它的钥匙解密 */
+function matchCreds(encrypted: string): CallbackCreds | null {
+	const sig = query("msg_signature");
+	const ts = query("timestamp");
+	const nonce = query("nonce");
+	return callbackCreds().find(c => wecomSignature(c.token, ts, nonce, encrypted) === sig) ?? null;
+}
+
 /**
  * 校验企微回调签名并解出明文。签名不合法 → 400（不是 401：调用方是企微服务器，
  * 401 会被当成「本站需要鉴权」误导排查）；信封里的原文不回显，避免给探测者提供比对材料。
@@ -125,22 +161,21 @@ function unwrapAccepting(encrypted: string, cfg: WecomConfig, candidates: string
  * 三道顺序不可换：先验签（不给未鉴权请求写 kv）→ 再拦重放（省一次解密，也让
  * cancel_auth 这种危险性最高的报文止步在落库之前）→ 最后解密。
  */
-async function decryptVerified(encrypted: string, envelope: CallbackFields): Promise<{ cfg: WecomConfig, plain: string, claim: ReplayClaim }> {
-	const cfg = readWecomConfig();
-	const expected = wecomSignature(cfg.token, query("timestamp"), query("nonce"), encrypted);
-	if (expected !== query("msg_signature"))
+async function decryptVerified(encrypted: string, envelope: CallbackFields): Promise<{ kind: WecomKind, plain: string, claim: ReplayClaim }> {
+	const creds = matchCreds(encrypted);
+	if (!creds)
 		throw badRequest("回调签名校验失败");
 	const claim = await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
 	try {
 		// 信封的 ToUserName 就是这条报文的身份：套件事件里是 suiteid，应用数据回调里是 corpid，
-		// 与 receiveid 必然一致（两者在同一份密文/明文里，签名已经覆盖）。
-		return { cfg, plain: unwrapAccepting(encrypted, cfg, [cfg.suiteId, field(envelope, "ToUserName")]), claim };
+		// 与 receiver 必然一致（两者在同一份密文/明文里，签名已经覆盖）。
+		return { kind: creds.kind, plain: unwrapAccepting(encrypted, creds, [creds.receiver, field(envelope, "ToUserName")]), claim };
 	}
 	catch (e) {
 		// 解不开的这一条不能占住 nonce：企微重推是它唯一的恢复路径，占住就把重推挡成 400
 		await claim.release();
 		// 解密失败只对外透出「失败」：错钥/错套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
-		noteDecryptFailure(e, envelope, cfg);
+		noteDecryptFailure(e, envelope, creds);
 		throw badRequest("回调消息解密失败");
 	}
 }
@@ -162,8 +197,10 @@ const login = {
 	// corp 必填（D10：企业代码 = corp_id，服务商后台可生成带码的专属登录链接）。
 	async get() {
 		try {
-			const cfg = readWecomConfig();
-			const deps = runtimeStoreDeps(cfg);
+			// 登录只用「与来源无关」的两项（落库密钥 + 基址）：自建模式没有 suite 凭据，
+			// 在这里读整套 suite 配置会把一条正常的登录打成 400。
+			const base = readBase();
+			const deps = runtimeStoreDeps(base);
 
 			const corp = query("corp");
 			const agent = query("agent");
@@ -172,7 +209,7 @@ const login = {
 			// 企业代码解析是**未登录可调的枚举面**（§5.3）：复用登录节流，维度 (IP, 企业代码）。
 			// corp 缺省时（代开发模板常只服务一家企业）自动从已安装档案解析，省去手动填企业代码，
 			// 也让「应用主页」可直接填 https://<域名>/login（无需 ${corpid} 占位符，企微后台会因非法 URL 字符拒收）。
-			let profile: { corpId: string; agentId: string; env: string };
+			let profile: { corpId: string, agentId: string, env: string };
 			if (corp) {
 				await guardLoginThrottle(ip, corp);
 				profile = await findProfile(corp, agent || null, deps).catch(async (e: Error & { status?: number }) => {
@@ -181,8 +218,9 @@ const login = {
 						await noteLoginFailed(ip, corp);
 					throw e;
 				});
-			} else {
-				profile = await resolveWecomProfile(agent || null);
+			}
+			else {
+				profile = await resolveWecomProfile(agent || null, corpSelf());
 				await guardLoginThrottle(ip, profile.corpId);
 			}
 
@@ -191,7 +229,7 @@ const login = {
 			const url = buildAuthorizeUrl({
 				corpId: profile.corpId,
 				agentId: profile.agentId,
-				redirectUri: loginRedirectOf(cfg),
+				redirectUri: loginRedirectOf(base),
 				state,
 				inWecom: /wxwork/i.test(header("user-agent")),
 			});
@@ -207,7 +245,7 @@ const callback = {
 	// 企微回跳：state 一次性（kv 取即删）→ profile → 绑租户 → code 换 userid → JIT 建档 → 发票 → 302。
 	async get() {
 		try {
-			const cfg = readWecomConfig();
+			const base = readBase();
 			const code = query("code");
 			const state = query("state");
 			// 用户在企业微信里点了「拒绝」时企微不回 code，只回 state
@@ -216,7 +254,7 @@ const callback = {
 			if (!state)
 				throw badRequest("登录状态缺失：请从企业微信重新进入");
 
-			const deps = runtimeStoreDeps(cfg);
+			const deps = runtimeStoreDeps(base);
 			const cache = runtimeCache();
 			const pending = await takeLoginState(state, cache);
 			const profile = await findProfile(pending.corpId, pending.agentId, deps);
@@ -246,7 +284,7 @@ const callback = {
 			await issueLoginTicket(crypto.sha256Hex(ticket), uid, tenant, LOGIN_TICKET_TTL_SECS, deps);
 			await noteLoginSucceeded(await clientIp(), profile.corpId);
 			log.info("wecom login ok", "tenant", tenant, "agentId", profile.agentId);
-			json.redirect.found(loginLandingUrl({ origin: siteRootOf(cfg), ticket, tenant }));
+			json.redirect.found(loginLandingUrl({ origin: siteRootOf(base), ticket, tenant }));
 		}
 		catch (e) {
 			failWith(e);
@@ -286,34 +324,35 @@ ticket.post.schema = {
 const event = {
 	// 企微后台「保存回调 URL」时会 GET 一次：解出 echostr 后**原样明文回**（不套信封、不加引号）。
 	//
-	// 只依赖 Tier A 凭据（readCallbackConfig）：token/aeskey/baseUrl/encKey 全部部署方本地生成，
-	// 不需要 suite_id——因此「配齐四项正确即可响应验证」，**不必等代开发模版创建、拿到 suite_id 之后**。
-	// 这正是打破鸡生蛋死锁（plan §18）的落点：先有可验证的回调，才能创建模版、拿到 suite 凭据。
+	// 只依赖回调凭据（`callbackCreds()`）：token/aeskey 由部署方与企微后台成对填写，不需要 suite_id——
+	// 因此「配齐即可响应验证」，**不必等代开发模版创建、拿到 suite_id 之后**。这正是打破鸡生蛋死锁
+	// （plan §18）的落点：先有可验证的回调，才能创建模版、拿到 suite 凭据。
+	//
+	// 共存部署有**两套**回调凭据（代开发的指令回调 / 自建应用的通讯录同步回调），企微用哪一套签名
+	// 取决于管理员在哪个后台点「保存」→ 逐个试签，命中哪套就用哪套钥匙解密。两套都没配才报错。
 	//
-	// suite_id 在「模版创建成功」后才下发；URL 验证可能发生在拿到 suite_id 之前（创建表单内联校验）。
-	// 加上「应用回调 URL 验证时 receiveid 是 corpid」这一层，GET 根本无从挑一个值来比 → 一律 tolerant，
-	// 见下面 try 里的说明（签名是唯一闸门，本端点不落状态）。
+	// URL 验证可能发生在拿到 suite_id 之前（创建表单内联校验），加上「应用回调 URL 验证时 receiveid
+	// 是 corpid」这一层，GET 根本无从挑一个值来比 → 一律 tolerant，见下面 try 里的说明
+	// （签名是唯一闸门，本端点不落状态）。
 	async get() {
 		try {
-			const cfg = readCallbackConfig();
 			const encrypted = query("echostr");
-			const expected = wecomSignature(cfg.token, query("timestamp"), query("nonce"), encrypted);
-			if (expected !== query("msg_signature"))
+			const creds = matchCreds(encrypted);
+			if (!creds)
 				throw badRequest("回调签名校验失败");
 			const claim = await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
-			const suiteId = (vars.get("wecom_suite_id") ?? "").trim();
 			try {
 				// receiveid 一律不比对：GET 只有 echostr、没有报文信封，无从知道该比哪一个——
-				// 「模板/指令回调 URL」验证时 receiveid 是 suiteid，「应用回调 URL」验证时是 corpid。
+				// 「模板/指令回调 URL」验证时 receiveid 是 suiteid，「应用回调 URL / 通讯录同步」验证时是 corpid。
 				// 放宽是安全的：签名已过（token 只有本部署与企微知道），回包只是把解出的 echostr 原样返回，
 				// 不写任何状态；真正的 receiveid 比对在 POST 那条路径上（见 unwrapAccepting）。
-				plainText(unwrapWecomMessage(encrypted, cfg.encodingAesKey, suiteId, true));
+				plainText(unwrapWecomMessage(encrypted, creds.encodingAesKey, creds.receiver, true));
 			}
 			catch (e) {
 				// 验证没通过就放回 nonce：企微后台点「保存」会连着验几次，占住会把后几次都挡成 400
 				await claim.release();
 				// 解密失败只透出「失败」：错钥/未下发套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
-				noteDecryptFailure(e, null, { encodingAesKey: cfg.encodingAesKey, suiteId });
+				noteDecryptFailure(e, null, creds);
 				throw badRequest("回调消息解密失败");
 			}
 		}
@@ -322,8 +361,12 @@ const event = {
 		}
 	},
 
-	// 回调（指令 + 应用数据）：验签 → 解密 → 分发（suite_ticket / create_auth / change_auth /
-	// cancel_auth / reset_permanent_code）。回 `success` 才算收下，否则企微 5 秒后重推三次。
+	// 回调（指令 + 应用数据 + 通讯录同步）：验签 → 解密 → 按**命中凭据的来源**分发。
+	// 回 `success` 才算收下，否则企微 5 秒后重推三次。
+	//
+	// 来源分派是共存的关键：suite 凭据只可能收到套件事件（suite_ticket / create_auth / change_auth /
+	// cancel_auth）；corp 凭据只可能收到通讯录变更（企业管理员在「通讯录同步 → 接收事件服务器」填的本 URL），
+	// **没有**套件事件这回事，所以直接进 change_contact 分支，不进 handleSuiteEvent 的 switch。
 	//
 	// 包体形态按官方文档是 XML（见 payload.ts 的开头），但归一化那一层两种都认，
 	// 所以本函数只认字段名，不认格式。
@@ -338,7 +381,18 @@ const event = {
 			claim = verified.claim;
 
 			const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
-			await handleSuiteEvent(verified.plain, { cfg: verified.cfg, client, store: runtimeStoreDeps(verified.cfg) });
+			if (verified.kind === "corp") {
+				// 自建应用没有套件流程：报文只可能是 change_contact（其余形态由 contacts.ts 记账后放过）
+				await handleContactChange(callbackFields(verified.plain), {
+					client,
+					store: runtimeStoreDeps(readBase()),
+					credentialKind: "corp",
+				});
+			}
+			else {
+				const cfg = readSuiteConfig();
+				await handleSuiteEvent(verified.plain, { cfg, client, store: runtimeStoreDeps(cfg) });
+			}
 			// 处理成功即标记 nonce 已落库：企微重推时命中即幂等回 success，解开「首推偏慢被企微判超时、
 			// 重推又被重放守卫挡 400」的死局——管理员端不再卡在「应用安装失败」。
 			await markApplied(query("nonce"), runtimeReplayGate()).catch(() => {});

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

@@ -18,7 +18,7 @@ import { assertPermission, assertTenantSelf } from "#/_platform/_shared/service/
 import { recordOp } from "#/_platform/_shared/service/infra/audit";
 import { rateLimit } from "#/_platform/_shared/service/infra/rate";
 import { createWecomClient, runtimeCache, runtimeHttp } from "../../_shared/wecom/client";
-import { readWecomConfig } from "../../_shared/wecom/config";
+import { corpIdentity, readBase } from "../../_shared/wecom/config";
 import { findProfile, probeProfile, runtimeStoreDeps } from "../../_shared/wecom/store";
 import { attachProfile, cancelSync, emptyView, startSync, syncStatus } from "../../_shared/wecom/sync";
 
@@ -44,12 +44,15 @@ const STATS = {
 
 const VIEW = {
 	type: "object",
-	required: ["connected", "authMode", "profileStatus", "status", "phase", "stats", "progress", "errCode", "errDetail", "startedAt", "finishedAt", "updateTime"],
+	required: ["connected", "authMode", "profileStatus", "agentId", "credentialKind", "status", "phase", "stats", "progress", "errCode", "errDetail", "startedAt", "finishedAt", "updateTime"],
 	properties: {
 		// 授权事实（页面据此决定「整条隐藏 / 成员授权卡片 / 冻结黄条 / 正常同步栏」）
 		connected: { type: "boolean" },
 		authMode: { type: "number" },
 		profileStatus: { type: ["string", "null"] },
+		// 分辨锚点：多应用/共存企业下前端必须原样回传（C6）
+		agentId: { type: ["string", "null"] },
+		credentialKind: { type: ["string", "null"], enum: ["suite", "corp", null] },
 		status: { type: "string", enum: ["idle", "running", "done", "failed", "cancelled"] },
 		phase: { type: "string", enum: ["departments", "members", "reconcile"] },
 		stats: STATS,
@@ -80,6 +83,18 @@ function agentOf(raw: unknown): string | null {
 	return s.length > 0 ? s : null;
 }
 
+/**
+ * 未带 agent 时的兜底：**只有当本租户就是本部署自建的那家企业**才用配置里的 agent。
+ *
+ * 共存下的双应用租户（同一 corp 同时有代开发行与自建行）不带 agent 时探针只能 400，
+ * 而「点进自己组织架构页」不该要求管理员手填应用 id。别家企业没有这个兜底——
+ * 它们的 agent 只能来自登录链接/状态条回传，不由本站配置决定（那正是代开发的意义）。
+ */
+function selfAgentOf(tenantId: string): string | null {
+	const self = corpIdentity();
+	return self && self.corpId === tenantId ? self.agentId : null;
+}
+
 /**
  * 解析当前租户的授权档案（企业代码 = 租户；多应用时必须带 agent）。
  *
@@ -88,14 +103,15 @@ function agentOf(raw: unknown): string | null {
  * 是自己填错了），findProfile 负责解密出 permanent_code。
  */
 async function profileOf(tenantId: string, agent: unknown) {
-	const probe = await probeProfile(tenantId, agentOf(agent));
+	const probe = await probeProfile(tenantId, agentOf(agent) ?? selfAgentOf(tenantId));
 	if (!probe) {
 		throw Object.assign(new Error("本站尚未开通企业微信：没有可同步的授权记录"), { status: 400 });
 	}
 	if (probe.status !== "active") {
 		throw Object.assign(new Error("该企业已取消授权或应用已停用：组织架构同步已冻结，请联系服务商重新开通"), { status: 400 });
 	}
-	const cfg = readWecomConfig();
+	// 同步只用与来源无关的两项（落库密钥 + 基址）：读整套 suite 配置会把自建部署打成 400
+	const cfg = readBase();
 	const profile = await findProfile(tenantId, probe.agentId, runtimeStoreDeps(cfg));
 	return { profile, probe, cfg };
 }
@@ -149,7 +165,7 @@ const status = {
 			const tenantId = currentTenant();
 			if (!tenantId)
 				throw Object.assign(new Error("缺少租户上下文"), { status: 400 });
-			const probe = await probeProfile(tenantId, agentOf((http.query as Record<string, unknown>).agent));
+			const probe = await probeProfile(tenantId, agentOf((http.query as Record<string, unknown>).agent) ?? selfAgentOf(tenantId));
 			if (!probe)
 				return attachProfile(emptyView("idle"), null);
 			return attachProfile(await syncStatus(tenantId, probe.agentId), probe);

package/templates/src/auth/web/__client/api.schemas.ts

@@ -19,6 +19,7 @@ export const schemas = {
 	"env": z.string(),
 	"corp_name": z.string().nullable().optional(),
 	"status": z.enum(["active", "disabled"]),
+	"credential_kind": z.enum(["suite", "corp"]),
 	"auth_mode": z.number(),
 	"installed_at": z.number(),
 	"update_time": z.number()
@@ -40,6 +41,24 @@ export const schemas = {
 	"installUrl": z.string(),
 	"callbackUrl": z.string(),
 	"expiresIn": z.number()
+}),
+	},
+	"authWecomAdminOverviewGet": {
+		data: z.object({
+	"kinds": z.array(z.enum(["suite", "corp"])),
+	"configError": z.string().nullable(),
+	"callbackUrl": z.string().nullable(),
+	"corpId": z.string().nullable(),
+	"agentId": z.string().nullable(),
+	"corpCallbackConfigured": z.boolean()
+}),
+	},
+	"authWecomAdminConnectPost": {
+		data: z.object({
+	"corpId": z.string(),
+	"agentId": z.string(),
+	"departments": z.number(),
+	"members": z.number()
 }),
 	},
 	"authWecomTicketPost": {
@@ -108,7 +127,9 @@ export const schemas = {
 }).nullable(),
 	"startedAt": z.number(),
 	"finishedAt": z.number(),
-	"updateTime": z.number()
+	"updateTime": z.number(),
+	"agentId": z.string().nullable(),
+	"credentialKind": z.union([z.literal("suite"), z.literal("corp"), z.literal(null)]).nullable()
 }),
 	},
 	"authWecomSyncCancelPost": {

package/templates/src/auth/web/__client/api.ts

@@ -33,7 +33,7 @@ export function createAuthClient(ctx: ModuleContext) {
 	}
 	ctx.register.apiPrefix(API_PREFIX);
 	bindRequest(ctx.utils.request);
-	return { authLoginPost, authLogoutPost, authRefreshPost, authPasswordPut, authLdapLoginPost, authWecomAdminAppsGet, authWecomAdminStatusPost, authWecomAdminInstallGet, authWecomLoginGet, authWecomCallbackGet, authWecomTicketPost, authWecomEventGet, authWecomEventPost, authWecomSyncStartPost, authWecomSyncStatusGet, authWecomSyncCancelPost };
+	return { authLoginPost, authLogoutPost, authRefreshPost, authPasswordPut, authLdapLoginPost, authWecomAdminAppsGet, authWecomAdminStatusPost, authWecomAdminInstallGet, authWecomAdminOverviewGet, authWecomAdminConnectPost, authWecomLoginGet, authWecomCallbackGet, authWecomTicketPost, authWecomEventGet, authWecomEventPost, authWecomSyncStartPost, authWecomSyncStatusGet, authWecomSyncCancelPost };
 }
 
 /**
@@ -211,6 +211,52 @@ export async function authWecomAdminInstallGet(): Promise<AuthWecomAdminInstallG
 	}
 }
 
+export type AuthWecomAdminOverviewGetData = z.infer<(typeof schemas)["authWecomAdminOverviewGet"]["data"]>;
+
+export async function authWecomAdminOverviewGet(): Promise<AuthWecomAdminOverviewGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`auth/wecom/admin/overview`).json<OjEnvelope<AuthWecomAdminOverviewGetData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as AuthWecomAdminOverviewGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomAdminOverviewGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomAdminOverviewGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type AuthWecomAdminConnectPostData = z.infer<(typeof schemas)["authWecomAdminConnectPost"]["data"]>;
+
+export async function authWecomAdminConnectPost(): Promise<AuthWecomAdminConnectPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`auth/wecom/admin/connect`).json<OjEnvelope<AuthWecomAdminConnectPostData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as AuthWecomAdminConnectPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomAdminConnectPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomAdminConnectPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
 export async function authWecomLoginGet(): Promise<unknown> {
 	const client = ensureReq();
 	try {

package/templates/src/system/web/locales/en-US.json

@@ -141,7 +141,8 @@
 			"status": "Status",
 			"installedAt": "Onboarded at",
 			"action": "Actions",
-			"authMode": "Auth mode"
+			"authMode": "Auth mode",
+			"source": "Source"
 		},
 		"statusActive": "Active",
 		"statusDisabled": "Disabled",
@@ -205,6 +206,28 @@
 					"hint": "Contact the service provider to investigate, then retry."
 				}
 			}
+		},
+		"source": {
+			"suite": "Delegated",
+			"corp": "Internal app"
+		},
+		"authModeNone": "—",
+		"configErrorTitle": "Deployment config check failed",
+		"coexistHint": "This deployment runs both delegated (suite) and internal (corp) apps (wecom_allow_coexist: 'true').",
+		"corp": {
+			"title": "Internal app (self-built)",
+			"hint": "This deployment connects as an internal app: credentials come from config.yaml (wecom_corp_id / wecom_corp_secret / wecom_corp_agent_id). Fill them in, then click \"Verify and connect\"; the corporation is registered only after all three checks pass.",
+			"corpId": "Corporation ID",
+			"agentId": "AgentId",
+			"callbackUrl": "Contacts event callback URL",
+			"callbackHint": "Fill this URL into WeCom → Tools → Contacts sync → Set event receiver URL. Leave the app's own message callback empty: the two use different tokens, and pointing both at one URL makes half the payloads fail signature verification.",
+			"callbackConfigured": "Contacts event callback credentials",
+			"callbackYes": "Configured (member changes sync in real time)",
+			"callbackNo": "Not configured (full sync only; to get increments, fill Token / EncodingAESKey for this URL in the WeCom console)",
+			"connect": "Verify and connect",
+			"connectConfirm": "Connect checks: whether the app Secret can fetch a token, whether contacts are readable, and whether any member is visible. Re-run it whenever the Corporation ID / AgentId changed or the Secret was rotated.",
+			"connectOk": "Connected: {{depts}} departments visible, {{members}} members in the sample department",
+			"connectHint": "After rotating the app Secret you must click \"Verify and connect\" again, otherwise every call fails with 40001. How many people get synced depends on the app's visible scope — set it to the whole company for a full sync."
 		}
 	},
 	"err": {

package/templates/src/system/web/locales/zh-CN.json

@@ -141,7 +141,8 @@
 			"status": "状态",
 			"installedAt": "开通时间",
 			"action": "操作",
-			"authMode": "授权模式"
+			"authMode": "授权模式",
+			"source": "来源"
 		},
 		"statusActive": "启用",
 		"statusDisabled": "停用",
@@ -205,6 +206,28 @@
 					"hint": "请联系服务商排查后重试。"
 				}
 			}
+		},
+		"source": {
+			"suite": "代开发",
+			"corp": "企业内部应用"
+		},
+		"authModeNone": "—",
+		"configErrorTitle": "部署配置自检未通过",
+		"coexistHint": "本部署同时启用了代开发与企业内部应用（wecom_allow_coexist: 'true'）。",
+		"corp": {
+			"title": "企业内部应用（自建）",
+			"hint": "本部署作为企业内部应用接入：凭据来自 config.yaml 的 wecom_corp_id / wecom_corp_secret / wecom_corp_agent_id。填好后点「验证并接入」，三步校验全过才会登记企业。",
+			"corpId": "企业ID",
+			"agentId": "AgentId",
+			"callbackUrl": "通讯录事件回调地址",
+			"callbackHint": "把上面这个地址填到企微「管理工具 → 通讯录同步 → 设置接收事件服务器」；应用自身的「接收消息」回调请留空——两处 Token 不同，填同一个 URL 会让一半报文验签失败。",
+			"callbackConfigured": "通讯录事件回调凭据",
+			"callbackYes": "已配置（成员变更会实时同步）",
+			"callbackNo": "未配置（只做全量同步；要增量请在企微后台填 Token / EncodingAESKey 到同一地址）",
+			"connect": "验证并接入",
+			"connectConfirm": "接入会依次校验：应用 Secret 能否换 token、能否读通讯录、可见范围内能否读到人。改过企业ID / AgentId 或换过 Secret 都必须重新点一次。",
+			"connectOk": "接入成功：可见范围内 {{depts}} 个部门，示例部门 {{members}} 人",
+			"connectHint": "换过应用 Secret 后必须重新「验证并接入」，否则所有调用都会 40001；同步到多少人取决于「应用可见范围」，要全量请设为全公司。"
 		}
 	},
 	"err": {