@oj-module/cli 0.2.47 → 0.2.48

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

@@ -2,7 +2,7 @@ import type { WecomClient } from "./client";
 import type { WecomConfig } from "./config";
 import type { WecomStoreDeps } from "./store";
 // 企微「指令回调」事件处理：suite_ticket / create_auth / change_auth / cancel_auth /
-// reset_permanent_code（代开发重置 secret 走后者）。
+// reset_permanent_code（代开发重置 secret 走后者），以及轨三的通讯录变更（contacts.ts）。
 //
 // 为什么这几件事必须由回调驱动（而不是管理端手工录）：
 //   · suite_ticket 每 10 分钟推一次、30 分钟过期，拿不到就换不出 suite_access_token，
@@ -12,13 +12,16 @@ import type { WecomStoreDeps } from "./store";
 //   · 企业解绑/取消授权只在 cancel_auth 出现。
 // 因此这里不是「可选的后台功能」，是代开发模式的下限能力。
 //
-// 响应纪律：处理完返回（路由回纯文本 success）。企微 5 秒内拿不到 success 会重推三次；
-// 重推对我们是幂等的（profile upsert / ticket 覆盖），但 AuthCode 一次有效，重推时已换取过 → 502，
+// 响应纪律：处理完返回（路由回纯文本 success）。企微对 `create_auth` 的窗口是 **约 1 秒**
+// （官方文档写 5 秒，实际按 1 秒卡；超时/非 success 一律在企业管理员浏览器上显示
+// 「应用安装失败，联系服务商」）。拿不到 success 会重推三次；重推对我们是幂等的
+// （profile upsert / ticket 覆盖），但 AuthCode 一次有效，重推时已换取过 → 502，
 // 属预期（日志留痕即可，不影响已落库的 profile）。
 import { invalidateAllUsers } from "#/_platform/_shared/service/infra/access";
 import { recordOp } from "#/_platform/_shared/service/infra/audit";
-import { corpScope, getSuiteTicket, putSuiteTicket, revokeTenantSessions, saveProfile, setProfileStatus, tenantOfCorp } from "./store";
-import { xmlField } from "./xml";
+import { handleContactChange } from "./contacts";
+import { callbackFields, field, requireField } from "./payload";
+import { corpScope, ensureTenant, findCorpAuth, getSuiteTicket, putSuiteTicket, revokeTenantSessions, saveProfile, setAuthMode, setProfileStatus, tenantOfCorp } from "./store";
 
 /** suite_ticket 官方有效期 30 分钟（10 分钟推一次）；本地按 30 分钟作废，宁可拒一次也不拿过期票打企微 */
 const SUITE_TICKET_TTL_SECS = 30 * 60;
@@ -40,15 +43,27 @@ export function envOfState(state: string | null): string {
 	return /^(?:prod|test|staging|dev)$/i.test(trimmed) ? trimmed.toLowerCase() : "prod";
 }
 
-function requireField(xml: string, name: string, infoType: string): string {
-	const value = xmlField(xml, name);
-	if (!value)
-		throw Object.assign(new Error(`企微事件 ${infoType} 缺少 ${name}`), { status: 400 });
-	return value;
+/**
+ * 事件路径的审计。两处纪律：
+ *   1. 调用前必须先 `ensureTenant(corp)`——`sys_oplog` 是租户表，本端点又是匿名路径（企微带不了
+ *      `X-TENANT-ID`），`sql_guard: deny` 下不带租户上下文的 insert 会被守卫直接拒；
+ *   2. 审计失败**只告警**：它发生在 profile 已落库之后，一次成功的授权不能因为写日志失败
+ *      变成企业管理员看到的「应用安装失败」。
+ */
+async function auditAuth(action: string, corpId: string, detail?: unknown, level?: number): Promise<void> {
+	try {
+		await recordOp({ action, module: "auth", target: corpId, detail, level });
+	}
+	catch (e) {
+		log.warn("wecom auth audit skipped", "action", action, "corpId", corpId, "reason", (e as Error).message);
+	}
 }
 
 /** 该 corp 的所有应用都标记为停用，并吊销其租户下的全部会话 */
 async function disableCorp(corpId: string, deps: SuiteEventDeps): Promise<void> {
+	// 取消授权同样是匿名回调：会话清理走裸 SQL，`sql_guard: deny` 下没有租户上下文会被拒——
+	// 而这里拒掉的后果是「旧 refresh 串仍能续命」，属安全红线，故必须绑成功再往下走。
+	ensureTenant(tenantOfCorp(corpId));
 	const rows = await db.table("wecom_app_profile").select(["agent_id"]).where(corpScope(corpId)).all() as Array<{ agent_id: string }>;
 	for (const r of rows)
 		await deps.client.invalidateCorpToken(corpId, String(r.agent_id));
@@ -67,6 +82,9 @@ async function applyAuthCode(authCode: string, state: string | null, deps: Suite
 	const suiteToken = await client.suiteAccessToken(cfg.suiteId, cfg.suiteSecret, suiteTicket.ticket);
 	const granted = await client.permanentCodeByAuthCode(suiteToken, authCode);
 	const env = envOfState(state ?? granted.state);
+	// 拿到企业身份就绑租户：profile 表虽共享，但其后的审计与后续写库都在这个租户下。
+	// 顺序不能挪到审计里——那样 saveProfile 之后才发现守卫拒，profile 已落库却回失败。
+	ensureTenant(tenantOfCorp(granted.corpId));
 	for (const agentId of granted.agentIds) {
 		await saveProfile({
 			suiteId: cfg.suiteId,
@@ -76,52 +94,119 @@ async function applyAuthCode(authCode: string, state: string | null, deps: Suite
 			env,
 			corpName: granted.corpName,
 			permanentCode: granted.permanentCode,
+			authMode: granted.authModes[agentId] ?? 0,
 		}, store);
 		// secret 可能已轮换：旧 token 必须立刻作废，否则下一个登录会带着失效 token 打 userinfo
 		await client.invalidateCorpToken(granted.corpId, agentId);
 	}
-	await recordOp({ action: "wecom.auth.apply", module: "auth", target: granted.corpId, detail: { agentIds: granted.agentIds, env } });
+	await auditAuth("wecom.auth.apply", granted.corpId, { agentIds: granted.agentIds, env });
 	return { corpId: granted.corpId, agentIds: granted.agentIds };
 }
 
+/**
+ * `change_auth` 后复核授权模式并落库。
+ *
+ * 失败**只告警**：回调窗口 1 秒，一次上游抖动不该把通知打成失败（重推也补不回被误判的
+ * 授权模式，反而让企业管理员看到「配置失败」）。代价是 auth_mode 短期仍是旧值，
+ * 同步闸门那侧还有 60011 兜底（见 sync 的 permission 分支）。
+ */
+async function refreshAuthModes(corpId: string, deps: SuiteEventDeps): Promise<void> {
+	try {
+		const auth = await findCorpAuth(corpId, deps.store);
+		if (!auth)
+			return;
+		const ticket = await getSuiteTicket(deps.cfg.suiteId, deps.store);
+		const suiteToken = await deps.client.suiteAccessToken(deps.cfg.suiteId, deps.cfg.suiteSecret, ticket.ticket);
+		const modes = await deps.client.authModesByPermanentCode(suiteToken, corpId, auth.permanentCode);
+		for (const agentId of auth.agentIds) {
+			const mode = modes[agentId];
+			if (mode == null)
+				continue;
+			await setAuthMode(corpId, agentId, mode, deps.store);
+			log.info("wecom auth_mode refreshed", "corpId", corpId, "agentId", agentId, "authMode", mode);
+		}
+	}
+	catch (e) {
+		log.warn("wecom auth_mode refresh skipped", "corpId", corpId, "reason", (e as Error).message);
+	}
+}
+
 /** 处理一条已验签并解密的回调明文；返回值仅用于日志（未知 InfoType 也回 success，不触发重推） */
-export async function handleSuiteEvent(plaintext: string, deps: SuiteEventDeps): Promise<string> {
-	const infoType = xmlField(plaintext, "InfoType") ?? "";
-	const suiteId = xmlField(plaintext, "SuiteId") ?? "";
+export async function handleSuiteEvent(payload: unknown, deps: SuiteEventDeps): Promise<string> {
+	// 入参是「原始报文」（对象 / JSON 串 / XML 串都行，见 payload.ts）；归一化只在这里做一次，
+	// 往下全是字段名，函数体里再也看不到格式。
+	const fields = callbackFields(payload);
+	const infoType = field(fields, "InfoType");
+	const suiteId = field(fields, "SuiteId");
 	if (suiteId && suiteId !== deps.cfg.suiteId)
 		throw Object.assign(new Error("企微事件 SuiteId 与本部署配置不一致"), { status: 400 });
 
+	// 通讯录变更（轨三）：**必须在 switch 之前分流**。两种形态都认——
+	// 应用侧数据回调是 `MsgType=event` + `Event=change_contact`（InfoType 为空），
+	// 代开发指令回调是 `InfoType=change_contact`；后者与 suite_ticket 同用 InfoType 这一列，
+	// 落进 default 只会被记成「不消费的事件」。
+	// 与下面几个分支的不同：通讯录事件失败**不抛**（事件是加速器，重推补不回来，见 contacts.ts）。
+	if (field(fields, "Event") === "change_contact" || infoType === "change_contact")
+		return await handleContactChange(fields, deps);
+
 	switch (infoType) {
 		case "suite_ticket": {
-			const ticket = requireField(plaintext, "SuiteTicket", infoType);
+			const ticket = requireField(fields, "SuiteTicket", infoType);
 			await putSuiteTicket(deps.cfg.suiteId, ticket, deps.store.now() + SUITE_TICKET_TTL_SECS, deps.store);
 			log.info("wecom suite_ticket updated", "suiteId", deps.cfg.suiteId);
+			// 顺势换一次 suite_access_token（命中缓存则 0 次往返）：create_auth 只有约 1 秒窗口，
+			// 这里先换掉，企业管理员扫码那条路径就只剩 get_permanent_code 一次出网。
+			// 副产品：suite_secret 配错会在票据推送时就进日志，而不是等某家企业扫码失败。
+			await deps.client.suiteAccessToken(deps.cfg.suiteId, deps.cfg.suiteSecret, ticket)
+				.catch((e: Error) => log.warn("wecom suite token warmup failed", "reason", e.message));
 			return infoType;
 		}
 		case "create_auth":
 		case "reset_permanent_code": {
-			const authCode = requireField(plaintext, "AuthCode", infoType);
-			const applied = await applyAuthCode(authCode, xmlField(plaintext, "State"), deps);
+			const authCode = requireField(fields, "AuthCode", infoType);
+			const applied = await applyAuthCode(authCode, field(fields, "State") || null, deps);
 			log.info("wecom auth applied", "event", infoType, "corpId", applied.corpId, "agents", applied.agentIds.join(","));
 			return infoType;
 		}
 		case "change_auth": {
-			// 可见范围/权限/启停变化：MVP 只做「数据可见性不加码」——不改状态、不动 secret，
-			// 靠下次登录重新走 userinfo（企微会拒掉已移出可见范围的成员）。停用/解绑走 cancel_auth。
-			const authCorpId = requireField(plaintext, "AuthCorpId", infoType);
+			// 可见范围/权限/启停变化。其中**「管理员授权 ⇄ 成员授权」切换**必须跟：切到成员授权后
+			// 部门接口一律 60011，同步闸门还按旧值放行就会一直 502。官方要求服务商自行调
+			// `get_auth_info` 复核——通知本身只带 AuthCorpId（没有 AuthCode），只能拿已存永久码反查。
+			// 其余变化（可见范围收窄等）仍是「下次登录重新走 userinfo」，不在回调里处理。
+			const authCorpId = requireField(fields, "AuthCorpId", infoType);
+			ensureTenant(tenantOfCorp(authCorpId));
+			await refreshAuthModes(authCorpId, deps);
 			log.info("wecom auth changed", "corpId", authCorpId);
 			return infoType;
 		}
 		case "cancel_auth": {
-			const authCorpId = requireField(plaintext, "AuthCorpId", infoType);
+			const authCorpId = requireField(fields, "AuthCorpId", infoType);
 			await disableCorp(authCorpId, deps);
-			await recordOp({ action: "wecom.auth.cancel", module: "auth", target: authCorpId, level: 4 });
+			await auditAuth("wecom.auth.cancel", authCorpId, undefined, 4);
 			log.warn("wecom auth cancelled", "corpId", authCorpId);
 			return infoType;
 		}
-		default:
-			// 通讯录变更等事件本模块不消费：记账即可，回 success 让企微别再推
-			log.info("wecom event ignored", "infoType", infoType);
-			return infoType;
+		default: {
+			// 余下的事件（标签变更、外部联系人等）本模块不消费：记账即可，回 success 让企微别再推。
+			//
+			// 记账要记够「这条报文能不能用」的量：指令回调（有 InfoType）与数据回调
+			// （`MsgType=event` + `Event=xxx`，没有 InfoType）走的是同一个 `/event`，
+			// 而两者的 Token/AESKey 未必是同一套。真机验形态时只凭 InfoType 为空无法区分
+			// 「收到了一条事件」与「收到了一条别的消息」，所以把 Event 与字段清单一起记下。
+			// **只记字段名不记值**：明文里有姓名与工号。
+			const eventName = field(fields, "Event");
+			log.info(
+				"wecom event ignored",
+				"infoType",
+				infoType,
+				"msgType",
+				field(fields, "MsgType"),
+				"event",
+				eventName,
+				"fields",
+				fields.names.join(","),
+			);
+			return eventName || infoType;
+		}
 	}
 }

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

@@ -1,3 +1,5 @@
+import type { WecomCache, WecomClient } from "./client";
+import type { WecomStoreDeps } from "./store";
 // 企微登录领域服务：授权链接构造、state 一次性票据、code→userid、JIT 建档。
 //
 // 两条入口（都落在同一个回调上）：
@@ -7,7 +9,14 @@
 //
 // JIT（无独立注册）：外部身份沿用 `wecom:<userid>` 用户名前缀（D6），口令哈希占位 `!wecom`
 // （任何口令都验不过，低信任来源不接管本地号，同 ldap 的 `!ldap`）；外层租户由 corp_id 决定。
-import type { WecomCache } from "./client";
+//
+// 轨一「登录自更新」（方案 §6.1）：登录成功后顺手 user/get 一次，补本人资料与所属部门。
+// 四条纪律：① 24h 节流（老用户不重复打上游）；② 整体 try/catch，失败不影响登录；
+// ③ **不建占位部门**——只对已知部门写关联（D10，否则任何登录成员都能凭空造出部门节点）；
+// ④ 只加不摘：人调到新部门只加新的，旧部门由全量同步/事件摘除。
+// 落库只有**一个**函数（applyMemberDetail）：轨二（全量同步）、轨三（事件增量）也调它——
+// 三套写库逻辑必然长歪，而症状只在「某条路径走过来的人组织关系不对」时才暴露。
+import { setMainDepartment, upsertMember } from "#/_platform/_shared/service/domain/org";
 
 export const AUTHORIZE_IN_APP = "https://open.weixin.qq.com/connect/oauth2/authorize";
 export const AUTHORIZE_QRCODE = "https://open.work.weixin.qq.com/wwopen/sso/qrConnect";
@@ -99,6 +108,8 @@ export async function ensureWecomUser(
 				corp_id: corpId,
 				must_change: 0,
 				is_forbidden: 0,
+				// 走到这里说明真人正在扫码登录 → 这位是「用过本站」的活人，进通讯录目录
+				activated: 1,
 			}).run();
 		}
 		catch (e) {
@@ -135,3 +146,143 @@ export function loginLandingUrl(opts: { origin: string, ticket: string, tenant:
 	const q = new URLSearchParams({ wecom_ticket: opts.ticket, tenant: opts.tenant });
 	return `${opts.origin}/login?${q.toString()}`;
 }
+
+// ---------------------------------------------------------------------------
+// 轨一：登录自更新（方案 §6.1）
+// ---------------------------------------------------------------------------
+
+/** 节流窗口：一个企业上万员工每天登录都会触发，不节流就是把 user/get 打成常驻流量 */
+export const SELF_UPDATE_TTL_SECS = 24 * 60 * 60;
+
+export interface SelfUpdateCtx {
+	uid: number
+	userid: string
+	corpId: string
+	agentId: string
+	permanentCode: string
+}
+
+export interface SelfUpdateDeps {
+	client: WecomClient
+	cache: WecomCache
+	store: WecomStoreDeps
+}
+
+/** 企微在职状态里「不该再放进来」的两档：2=已禁用、5=退出企业（4=未激活仍可登录） */
+function isBlockedStatus(status: number | null): boolean {
+	return status === 2 || status === 5;
+}
+
+async function dbExternalStatus(userid: string): Promise<number | null> {
+	const rows = await db.table("users").select(["external_status"]).where({ field: "username", op: "eq", value: externalUsername(userid) }).all() as Array<{ external_status: number | null }>;
+	const v = rows[0]?.external_status;
+	return v == null ? null : Number(v);
+}
+
+/** 一条成员的「外部源口径」快照：登录自更新、全量同步、事件增量三处都写这一个形状 */
+export interface MemberDetail {
+	/** undefined = 这条数据源没给名字，保留原值（空串/空白的名字不写） */
+	name?: string | null
+	/** undefined = 没给，**不写**（别把已知职务清成 null；null = 明确为空，写 null） */
+	position?: string | null
+	/** 同上：undefined = 不知道在职状态，不能覆盖 */
+	status?: number | null
+	departments: string[]
+	orders?: number[]
+	leaderInDept?: number[]
+	mainDepartment?: number | null
+}
+
+/**
+ * 把一条成员详情写回本地：资料（姓名/职务/在职状态）+ 所属部门关联。
+ *
+ * **三轨共用这一个写入口**（登录自更新 / 全量同步 / 事件增量）：两套写库逻辑必然长歪——
+ * 一处漏了主部门兜底、一处漏了 D13 归属权，症状都是「某类路径走过来的人组织关系不对」，
+ * 而且只在特定组合下才出现。所以这里只认「一条快照」，不认它从哪个轨来。
+ *
+ * **只加不摘**：人调到新部门只写新部门，旧部门不在这里删——摘除属全量同步/事件增量的职责，
+ * 登录路径上删关联会在「企微接口这次只返回部分部门」时把人的组织关系误删。
+ * **只写企微拥有的行**（D13）：`source != 'wecom'`（管理员已「转为本地维护」）一律不覆盖。
+ */
+export async function applyMemberDetail(
+	ctx: { uid: number, userid: string },
+	detail: MemberDetail,
+	opts: {
+		now: () => number
+		/** 真人刚登录过 → 纳入通讯录目录（§9.1）。同步与事件建档的人**不算**用过本站。 */
+		activated?: boolean
+		/** 全量同步按片预取的「企微部门 origin_id → 本地 id」；缺省时按本次涉及的部门现查 */
+		deptByOrigin?: Map<string, number>
+	},
+): Promise<void> {
+	const cols: Record<string, unknown> = {};
+	if (detail.position !== undefined)
+		cols.position = detail.position;
+	if (detail.status !== undefined)
+		cols.external_status = detail.status;
+	if (opts.activated)
+		cols.activated = 1;
+	const displayName = detail.name?.trim();
+	if (displayName)
+		cols.display_name = displayName;
+	if (Object.keys(cols).length) {
+		await db.table("users").update(cols).where({ and: [
+			{ field: "username", op: "eq", value: externalUsername(ctx.userid) },
+			{ field: "source", op: "eq", value: "wecom" },
+		] }).run();
+	}
+
+	if (!detail.departments.length)
+		return;
+	const byOrigin = opts.deptByOrigin ?? await wecomDeptIndex(detail.departments);
+	const orgDeps = { now: opts.now };
+	for (const [i, originId] of detail.departments.entries()) {
+		const deptId = byOrigin.get(String(originId));
+		// D10：未知部门一律跳过，等全量同步补——这里若能建部门，任何登录成员都能伪造组织架构
+		if (!deptId)
+			continue;
+		await upsertMember({
+			userId: ctx.uid,
+			deptId,
+			orderNo: detail.orders?.[i] ?? 0,
+			isLeader: (detail.leaderInDept?.[i] ?? 0) === 1,
+		}, orgDeps);
+	}
+	// 主部门可能缺失（仅当应用对主部门有查看权限时才返回）→ 兜底取 department[0]
+	const mainOrigin = detail.mainDepartment != null ? String(detail.mainDepartment) : String(detail.departments[0]!);
+	const mainDept = byOrigin.get(mainOrigin);
+	if (mainDept != null)
+		await setMainDepartment(ctx.uid, mainDept, orgDeps);
+}
+
+async function wecomDeptIndex(originIds: string[]): Promise<Map<string, number>> {
+	const rows = await db.table("sys_department").select(["id", "origin_id"]).where({ and: [
+		{ field: "origin", op: "eq", value: "wecom" },
+		{ field: "origin_id", op: "in", value: originIds },
+	] }).all() as Array<{ id: number, origin_id: string }>;
+	return new Map(rows.map(r => [String(r.origin_id), Number(r.id)]));
+}
+
+/**
+ * 登录自更新入口。**永不抛出**：任何失败只告警并放过登录（拿不到就用兜底值）。
+ * 返回值 `blocked` 供调用方在换会话前拦「企微侧已离职/禁用」的账号。
+ */
+export async function selfUpdate(ctx: SelfUpdateCtx, deps: SelfUpdateDeps): Promise<{ blocked: boolean }> {
+	const key = `wecom:self:${ctx.corpId}:${ctx.userid}`;
+	try {
+		if (await deps.cache.get(key))
+			return { blocked: isBlockedStatus(await dbExternalStatus(ctx.userid)) };
+		const detail = await deps.client.userDetail(ctx.corpId, ctx.agentId, ctx.permanentCode, ctx.userid);
+		// null = 无通讯录权限 / 不在可见范围 / 上游抖：本次不更新，也别写节流键（下次登录重试）
+		if (!detail)
+			return { blocked: isBlockedStatus(await dbExternalStatus(ctx.userid)) };
+		// 真人刚扫码登录过 → 纳入通讯录目录（§9.1）；同步/事件建档的人不算
+		await applyMemberDetail(ctx, detail, { now: deps.store.now, activated: true });
+		await deps.cache.set(key, "1", SELF_UPDATE_TTL_SECS);
+		return { blocked: isBlockedStatus(detail.status) };
+	}
+	catch (e) {
+		log.warn("wecom self-update skipped", "userid", ctx.userid, "reason", (e as Error).message);
+		return { blocked: false };
+	}
+}

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

@@ -0,0 +1,116 @@
+// 企微回调报文的入口归一化：把两种可能的包体（XML / JSON）折成同一份扁平字段表，
+// 业务代码（`events.ts` / `wecom/api.ts`）只认字段名，不认格式。
+//
+// **按官方文档，我们这类回调收到的是 XML**：代开发 / 第三方应用所属的「通用回调配置」
+// （96238 §3.2）只写 `<xml><ToUserName><Encrypt>`；`callback_format=json` 只在「对外收款」的
+// 指令回调（97478）有说明。所以回调地址不带那个参数（`config.ts::eventUrlOf` 记了这段依据）。
+//
+// 那为什么还收 JSON：解密后的**明文**在多份业务文档里都有 JSON 版（如 92655 的 change_contact），
+// 上游哪天默认切 JSON、或某类事件改发 JSON，这里不用动就能吃下。归一化只此一个入口，多一个分支
+// 的成本；反过来「只吃 XML」意味着那天要回头改事件分发与端点接线。
+//
+// 为什么不用通用 XML 解析器：明文已由 AES-CBC + msg_signature 双重认证（crypt.ts），
+// 这里只取扁平标签，且标签名由调用方常量给出——不解析结构、不处理命名空间，
+// 用正则换掉一个解析器依赖与它的实体展开攻击面。
+//
+// 大小写：同一份报文里信封用小写（`{"tousername","encrypt","agentid"}`），密文里的明文
+// 用大写（`{"SuiteId","InfoType"}`）。查字段一律走小写键，调用方不用关心这件事。
+
+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;
+	});
+}
+
+export interface CallbackFields {
+	/** 小写键 → 值（查字段只走这里） */
+	values: Map<string, string>
+	/** 报文里出现过的字段名（原样大小写、去重保序），只用于日志取证 */
+	names: string[]
+}
+
+/** 取字段；未命中空串（「没这个字段」与「字段为空」在回调处理里不需要区分） */
+export function field(fields: CallbackFields, name: string): string {
+	return fields.values.get(name.toLowerCase()) ?? "";
+}
+
+/**
+ * 必填字段：缺了直接 400。文案是给运维排查用的（企微侧只会显示「应用安装失败」），
+ * 不含值——明文字段里有姓名与工号。
+ */
+export function requireField(fields: CallbackFields, name: string, infoType: string): string {
+	const value = field(fields, name);
+	if (!value)
+		throw Object.assign(new Error(`企微事件 ${infoType} 缺少 ${name}`), { status: 400 });
+	return value;
+}
+
+function isCallbackFields(v: unknown): v is CallbackFields {
+	return typeof v === "object" && v !== null && (v as CallbackFields).values instanceof Map;
+}
+
+// 只取「叶子节点」：非 CDATA 分支明确排除 `<`，于是 `<xml><Encrypt>…</Encrypt></xml>` 里的
+// 根标签匹配不上（它内部以 `<` 开头），正则会继续向内找到 `<Encrypt>`。换成 `[\s\S]*?` 会让
+// 根标签把整段吞成一个字段（名叫 `xml`），内层字段全部丢失——这是最容易写错的一处。
+const XML_FIELD_RE = /<([A-Z_]\w*)>(?:<!\[CDATA\[([\s\S]*?)\]\]>|([^<]*))<\/\1>/gi;
+
+/**
+ * 归一回调包体。接受四种输入：已是归一结果的字段表（幂等，直接返回）、oj 已解析好的对象、
+ * JSON 字符串、XML 字符串。
+ *
+ * 都解不出字段时**不在这里抛错**：调用方按「缺 Encrypt」回 400，那条文案比
+ * 「JSON 解析失败」更好排查（能直接指向回调地址被中间件改写这种事）。
+ */
+export function callbackFields(raw: unknown): CallbackFields {
+	if (isCallbackFields(raw))
+		return raw;
+	const values = new Map<string, string>();
+	const names: string[] = [];
+	const put = (name: string, value: unknown) => {
+		if (!names.includes(name))
+			names.push(name);
+		values.set(name.toLowerCase(), value == null ? "" : String(value));
+	};
+
+	if (typeof raw === "string") {
+		const text = raw.trim();
+		if (text.startsWith("{")) {
+			try {
+				for (const [k, v] of Object.entries(JSON.parse(text) as Record<string, unknown>))
+					put(k, v);
+			}
+			catch {
+				return { values, names };
+			}
+		}
+		else {
+			for (const m of text.matchAll(XML_FIELD_RE))
+				put(m[1]!, decodeEntities((m[2] ?? m[3] ?? "").trim()));
+		}
+		return { values, names };
+	}
+
+	if (raw && typeof raw === "object") {
+		for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+			// 嵌套对象不是企微回调的形态（字段全平铺）；遇到就跳过，别把 [object Object] 塞进字段表
+			if (v !== null && typeof v === "object")
+				continue;
+			put(k, v);
+		}
+	}
+	return { values, names };
+}

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

@@ -27,6 +27,8 @@ export interface AppProfile {
 	corpName: string | null
 	status: "active" | "disabled"
 	permanentCode: string
+	/** 0=管理员授权 / 1=成员授权（成员授权下应用无任何部门权限，组织架构同步必然 60011，§2.3） */
+	authMode: number
 }
 
 /** 套件票据：企微每 10 分钟推一次，有效期 30 分钟；过期不得发起任何套件级 API 调用 */
@@ -120,6 +122,8 @@ export async function saveProfile(p: Omit<AppProfile, "status"> & { status?: App
 		corp_name: p.corpName,
 		status: p.status ?? "active",
 		permanent_code_enc: deps.encrypt(p.permanentCode),
+		// 授权模式是「该企业应用能不能做组织架构同步」的判据（§2.3）；重授权时必须跟着刷新
+		auth_mode: Number(p.authMode ?? 0),
 		update_time: now,
 	};
 	if (rows.length) {
@@ -161,6 +165,43 @@ export async function findProfile(corpId: string, agentId: string | null, deps:
 		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)),
+		authMode: Number(r.auth_mode ?? 0),
+	};
+}
+
+/** 「这家企业能不能同步」的三个事实：装没装 / 什么授权模式 / 是否还启用 */
+export interface ProfileProbe {
+	agentId: string
+	authMode: number
+	status: AppProfile["status"]
+}
+
+/**
+ * 授权探针（组织架构同步面的准入用）：与 `findProfile` 只差一件事——**查不到返回 null 而不是 400**。
+ *
+ * 为什么敢把「没有」当正常状态：调用方是本租户管理员在自己的组织架构页自省，`corp_id`
+ * 取自租户头而不是外部输入，不存在 `findProfile` 要防的枚举面（§5.3）。「本站没装企微」
+ * 是一个要能画成空态的事实，不是错误。
+ *
+ * 选中口径与 `findProfile` 对齐（优选启用中的应用；全停用时退回停用行，让页面能画
+ * 「已取消授权」冻结态），只多一条：没有启用应用时也返回，而不是 400。
+ */
+export async function probeProfile(corpId: string, agentId: string | null): Promise<ProfileProbe | null> {
+	const rows = await db.table("wecom_app_profile").select(["agent_id", "auth_mode", "status"]).where(corpScope(corpId)).all() as Array<Record<string, unknown>>;
+	if (rows.length === 0)
+		return null;
+	const active = rows.filter(r => String(r.status) === "active");
+	const pool = active.length > 0 ? active : rows;
+	const picked = agentId ? pool.filter(r => String(r.agent_id) === agentId) : pool;
+	if (picked.length === 0)
+		return null;
+	if (picked.length > 1)
+		fail(400, "该企业开通了多个应用，同步入口必须带 agent 参数");
+	const r = picked[0]!;
+	return {
+		agentId: String(r.agent_id),
+		authMode: Number(r.auth_mode ?? 0),
+		status: String(r.status) === "disabled" ? "disabled" : "active",
 	};
 }
 
@@ -169,6 +210,30 @@ export async function setProfileStatus(corpId: string, status: AppProfile["statu
 	return Number(await db.table("wecom_app_profile").update({ status, update_time: deps.now() }).where(corpScope(corpId)).run());
 }
 
+/**
+ * 该企业已授权的应用 + 共享的永久授权码。
+ * 用于 `change_auth` 复核授权模式：事件只带 AuthCorpId（**没有 AuthCode**），
+ * 只能拿已落库的 permanent_code 去 `get_auth_info` 反查。未授权企业返回 null。
+ *
+ * 一并返回 `corpId`（真实企业 ID）：事件里给的可能是 `AuthCorpId`（第三方体系下是 open_corpid），
+ * 而租户键只能用真实 corp_id（D10），故由这里统一把「事件身份 → 租户身份」的翻译交出来。
+ */
+export async function findCorpAuth(corpId: string, deps: WecomStoreDeps): Promise<{ corpId: string, permanentCode: string, agentIds: string[] } | null> {
+	const rows = await db.table("wecom_app_profile").select(["corp_id", "agent_id", "permanent_code_enc"]).where(corpScope(corpId)).all() as Array<Record<string, unknown>>;
+	if (rows.length === 0)
+		return null;
+	return {
+		corpId: String(rows[0]!.corp_id),
+		permanentCode: deps.decrypt(String(rows[0]!.permanent_code_enc)),
+		agentIds: rows.map(r => String(r.agent_id)),
+	};
+}
+
+/** 授权模式变更：只改 auth_mode，不动 secret / 状态（改状态是 cancel_auth 的事） */
+export async function setAuthMode(corpId: string, agentId: string, authMode: number, deps: WecomStoreDeps): Promise<void> {
+	await db.table("wecom_app_profile").update({ auth_mode: Number(authMode), update_time: deps.now() }).where(corpAgentScope(corpId, agentId)).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() };