@oj-module/cli 0.2.49 → 0.2.53

package/templates/src/_platform/api/_shared/service/domain/users.ts

@@ -59,13 +59,30 @@ function assertNotSelf(actorId: number, targetUid: number): void {
 		fail(400, "cannot operate on yourself");
 }
 
-/** AC1-8：成员资格（superadmin/admin 分配）仅 superadmin 可动。 */
+/**
+ * AC1-8（已修订）：成员资格提权守卫——按**被授予的角色**分层，不再一刀切。
+ *
+ *   · `superadmin` —— 仍严格只许 superadmin 授。它是**平台级**角色：握着它就能进
+ *     /system/wecom 那类跨租户页面（listApps 列出**所有企业**的档案），一旦租户内可授
+ *     即为跨租户越权，故这条不因下面的修订而放宽。
+ *   · `admin` —— 允许本租户内握有 `admin` 或 `superadmin` 的人任命。
+ *     判定与写入两侧都被租户作用域约束：`rolesOf()` 读 sys_user_role 走请求租户注入，
+ *     下面的写入同样带 tenant_id，所以租户管理员只能影响**自己租户**，不会越到别家。
+ *     动机：企业租户是隐式具象化的，平台 superadmin 因租户隔离查不到企业租户的用户
+ *     （实测 404），若 admin 任命也只许 superadmin，企业租户就永远配不出管理员。
+ *   · 其余角色（editor/viewer 等）—— 不校验，保持原行为。
+ */
 async function assertMembershipAllowed(actorId: number, nextRoles: string[]): Promise<void> {
 	if (!nextRoles.includes("superadmin") && !nextRoles.includes("admin"))
 		return;
 	const actorRoles = await rolesOf(Number(actorId));
-	if (!actorRoles.includes("superadmin"))
-		fail(403, "membership management requires superadmin");
+	const isSuper = actorRoles.includes("superadmin");
+	// 提权到平台级：只许 superadmin
+	if (nextRoles.includes("superadmin") && !isSuper)
+		fail(403, "granting superadmin requires superadmin");
+	// 任命本租户管理员：本租户的 admin 或 superadmin 均可
+	if (nextRoles.includes("admin") && !isSuper && !actorRoles.includes("admin"))
+		fail(403, "membership management requires admin or superadmin");
 }
 
 export async function listUsers(): Promise<UserRow[]> {
@@ -206,11 +223,30 @@ export async function updateUserRoles(actorId: number, targetUid: number, roles:
 			await t.table("sys_user_role").insert({ user_id: targetUid, role_name: role }).run();
 	});
 	invalidateUser(Number(targetUid));
+	// 提权类变更（牵涉 admin / superadmin）单列严重级：任命管理员＝把该租户的最高权限交出去，
+	// 不该和「勾了个 editor」落在同一噪声水平上。收回也算——撤销提权同样是安全事件。
+	const touchesPrivilege = (r: string) => r === "admin" || r === "superadmin";
+	const elevated = next.some(touchesPrivilege) || [...beforeSet].some(touchesPrivilege);
 	await recordOp({
 		action: "user.roles.update",
 		module: "framework",
 		target: await usernameOf(Number(targetUid)),
-		detail: { added: next.filter(r => !beforeSet.has(r)), removed: [...beforeSet].filter(r => !next.includes(r)) },
+		detail: {
+			added: next.filter(r => !beforeSet.has(r)),
+			removed: [...beforeSet].filter(r => !next.includes(r)),
+			// —— 租户维度 ——
+			// 每个租户都有自己的管理员，且**用户名撞车**（都叫 admin）：只记 username 分不清
+			// 「哪个租户的 admin 任命了谁」。sys_oplog.tenant_id 虽由请求租户注入，但那是隐式列，
+			// 显式落一份 + 双方 uid，审计才能直接按租户筛、也能定位到具体两个账号。
+			tenant: http.tenantId ?? "",
+			actorUid: Number(actorId),
+			targetUid: Number(targetUid),
+			// 便于直接筛出「任命/撤销管理员」这类高价值条目，不必去解析 added/removed
+			elevated,
+		},
+		// 4=warning（与「重设租户管理员口令」同级）：提权变更按安全事件留痕；
+		// 普通角色变更（editor/viewer）保持默认 6=info，避免审计被噪声淹没。
+		level: elevated ? 4 : 6,
 	});
 }
 

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

@@ -1,19 +1,20 @@
-// 代开发后台（服务商运营面）的领域逻辑：企业应用清单、启停、开通入口。
+// 企微后台（服务商运营面 + 自建应用接入面）：企业应用清单、启停、开通入口、验证并接入。
 //
-// 三个反常识点，都是踩过的坑：
+// 四个反常识点，都是踩过的坑：
 //   1. **不读部署常量也能停用**：`wecom_base_url` 配错时正是最需要「先把这个企业停掉」的时刻，
-//      所以清单与启停都不依赖 `readWecomConfig`，只有开通入口要（它得调企微换预授权码）。
+//      所以清单与启停都不依赖 `readSuiteConfig`，只有开通入口要（它得调企微换预授权码）。
 //   2. **不能用 `asTenant` 清会话**：管理员请求自带自己的租户头（多半是 `default`），
 //      而 `asTenant` 只能在「请求还没有租户」时调用，否则抛错。故吊销目标企业会话走带
 //      `tenant_id = ?` 的裸 SQL（守卫是 check-on-miss，带了租户条件即放行）。
 //   3. **停用单个应用 ≠ 停用企业**：会话是按租户（= 企业）发的，一个企业可能有测试/正式两个应用。
 //      只有该企业**再没有启用中的应用**时才吊销会话——否则停用测试应用会把正式环境的人踢下线。
 import type { WecomClient } from "./client";
-import type { WecomConfig } from "./config";
+import type { WecomConfig, WecomCorpConfig, WecomKind } from "./config";
 import type { WecomStoreDeps } from "./store";
 import { invalidateAllUsers } from "#/_platform/_shared/service/infra/access";
 import { assertProviderConfig, eventUrlOf } from "./config";
-import { corpScope, revokeTenantSessions, tenantOfCorp } from "./store";
+import { provisionTenantAdmin } from "./tenant-admin";
+import { corpScope, revokeTenantSessions, saveProfile, tenantOfCorp } from "./store";
 
 export interface WecomAdminDeps {
 	client: WecomClient
@@ -29,7 +30,9 @@ export interface AppRow {
 	env: string
 	corp_name: string | null
 	status: string
-	/** 0=管理员授权 / 1=成员授权：成员授权下这家企业的应用做不了组织架构同步（§2.3） */
+	/** 应用来源：suite=代开发 / corp=企业内部应用（自建） */
+	credential_kind: WecomKind
+	/** 0=管理员授权 / 1=成员授权：成员授权下这家企业的应用做不了组织架构同步（§2.3）；自建行恒 0 */
 	auth_mode: number
 	installed_at: number
 	update_time: number
@@ -37,7 +40,7 @@ export interface AppRow {
 
 export async function listApps(): Promise<AppRow[]> {
 	const rows = await db.table("wecom_app_profile")
-		.select(["suite_id", "corp_id", "agent_id", "auth_corp_id", "env", "corp_name", "status", "auth_mode", "installed_at", "update_time"])
+		.select(["suite_id", "corp_id", "agent_id", "auth_corp_id", "env", "corp_name", "status", "credential_kind", "auth_mode", "installed_at", "update_time"])
 		.all() as unknown as AppRow[];
 	// 稳定序：先按企业、再按应用；同企业多环境并排，运维一眼能看出「哪两个是同一家」
 	return rows.sort((a, b) => a.corp_id.localeCompare(b.corp_id) || a.agent_id.localeCompare(b.agent_id));
@@ -117,3 +120,84 @@ export async function createInstall(
 		expiresIn: auth.expiresIn,
 	};
 }
+
+/** 接入校验最多探多少个部门找人（顶层部门常只有子部门，只看第一个会误判「读不到人」） */
+const CONNECT_SAMPLE_DEPTS = 10;
+
+export interface ConnectResult {
+	corpId: string
+	agentId: string
+	/** 应用可见范围内的部门数 */
+	departments: number
+	/** 示例部门里的直属成员数（>0 才说明通讯录权限真的通了） */
+	members: number
+}
+
+/**
+ * 自建应用「验证并接入」：**四步全过才落库**（plan §4.3）。
+ *
+ * 为什么不能启动时自动写一行：自检失败会变成启动失败，而自建模式最常见的失败是客户还没加可信 IP、
+ * 可见范围没配——那是运营动作，不该让服务起不来。所以这一步放在人点的按钮后面。
+ *
+ * 顺序有讲究：
+ *   1. 先**作废 token 缓存**再换 token。换过 Secret 的部署若命中旧缓存，校验会「通过」，
+ *      而真正的问题（旧 secret 已失效）会在下一个登录请求上以 40001 冒出来。
+ *   2. gettoken 验 secret、department/simplelist 验通讯录读权限、user/simplelist 验能读到人——
+ *      这三件事对应三个最容易配错的开关（Secret 抄错 / 可见范围空 / 通讯录权限没给）。
+ */
+export async function connectCorp(cfg: WecomCorpConfig, client: WecomClient, deps: WecomStoreDeps): Promise<ConnectResult> {
+	await client.invalidateCorpToken(cfg.corpId, cfg.agentId);
+	await client.corpAccessToken(cfg.corpId, cfg.agentId, cfg.corpSecret);
+
+	const depts = await client.departmentChildren(cfg.corpId, cfg.agentId, cfg.corpSecret);
+	if (!depts.length)
+		throw Object.assign(new Error("接入校验失败：应用可见范围里没有任何部门（把「应用可见范围」设为全公司，或至少包含一个部门）"), { status: 400 });
+
+	// 顶层部门常常只有子部门、没有直属成员，所以往后再看几个再下结论
+	let members = 0;
+	for (const d of depts.slice(0, CONNECT_SAMPLE_DEPTS)) {
+		members = (await client.deptMembers(cfg.corpId, cfg.agentId, cfg.corpSecret, d.id)).length;
+		if (members)
+			break;
+	}
+	if (!members)
+		throw Object.assign(new Error("接入校验失败：可见范围内读不到成员（请把应用可见范围扩大到至少一名成员）"), { status: 400 });
+
+	await saveProfile({
+		// corp 行没有套件：suite_id 用空串（主键第一段），来源由 credential_kind 表达
+		suiteId: "",
+		corpId: cfg.corpId,
+		authCorpId: cfg.corpId,
+		agentId: cfg.agentId,
+		env: "prod",
+		corpName: null,
+		credentialKind: "corp",
+		permanentCode: cfg.corpSecret,
+		// 自建应用没有「管理员授权 / 成员授权」之分：恒 0，同步闸门据此直接放行
+		authMode: 0,
+	}, deps);
+
+	// 换过 AgentId 的部署会留下旧应用的活跃行：旧行的 secret 已不可用，留着只会让
+	// 「同一企业多应用」的分辨逻辑误判，故随本次接入一并停用。
+	const stale = await db.table("wecom_app_profile").select(["agent_id"]).where({
+		and: [
+			corpScope(cfg.corpId),
+			{ field: "credential_kind", op: "eq", value: "corp" },
+			{ field: "status", op: "eq", value: "active" },
+		],
+	}).all() as Array<{ agent_id: string }>;
+	for (const r of stale) {
+		const old = String(r.agent_id);
+		if (old === cfg.agentId)
+			continue;
+		await db.table("wecom_app_profile").update({ status: "disabled", update_time: deps.now() }).where({
+			and: [corpScope(cfg.corpId), { field: "agent_id", op: "eq", value: old }],
+		}).run();
+		await client.invalidateCorpToken(cfg.corpId, old);
+	}
+	// 租户具象化：给这个企业配一个本租户的管理员（admin，非 superadmin），否则
+	// 该租户里只有 JIT 出来的员工号，没人能做组织架构同步、也没人能在租户内授权。
+	await provisionTenantAdmin(cfg.corpId);
+	invalidateAllUsers();
+	return { corpId: cfg.corpId, agentId: cfg.agentId, departments: depts.length, members };
+}

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

@@ -518,11 +518,18 @@ export function createWecomClient(deps: WecomClientDeps) {
 				await invalidateCorpToken(corpId, agentId);
 				continue;
 			}
-			if (errcode !== 0)
+			if (errcode !== 0) {
+				// 部署侧错误（IP 白名单 / 限流）不是用户凭据问题：按 502 抛，避免被统一成 401 把排查带偏
+				log.warn("wecom getuserinfo rejected", "errcode", String(errcode), "errmsg", String(res.errmsg ?? ""));
+				if (errcode === 60020 || errcode === 45009)
+					throw upstream(`企微 auth/getuserinfo 失败：errcode=${errcode} ${String(res.errmsg ?? "")}`.trim());
 				rejectCode();
+			}
 			const userid = res.userid == null ? "" : String(res.userid);
-			if (!userid)
+			if (!userid) {
+				log.warn("wecom getuserinfo no userid", "keys", Object.keys(res).join(","));
 				rejectCode(); // 非企业成员（外部联系人）时企微只给 openid，不认作本应用用户
+			}
 			return userid;
 		}
 		throw upstream("企微 token 反复失效（40001/42001）");

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

@@ -1,15 +1,27 @@
-// 企微代开发「服务商侧」部署常量（config `vars:` 段，不进 DB、不进 sys_setting）。
+// 企微连接器的部署常量（config `vars:` 段，不进 DB、不进 sys_setting）。
 //
-// 多租户动态性边界：**套件（suite）是部署级的**——一个部署 = 一个服务商账号下的一套代开发模板
-// （suite_id/suite_secret/callback token/EncodingAESKey 全在这套模板的后台里）。
-// 「哪个企业装了哪个应用」不写配置：企微 create_auth 回调推 AuthCode → 换 permanent_code →
-// 落 wecom_app_profile，新增企业只需企业管理员扫码授权，**不改配置、不重启**。
-// 同一企业两个应用（测试/正式）也无需改配置：profile 主键含 agent_id（D5）。
+// **两种应用来源，可同时启用**（docs/plans/20261101-2044-wecom-internal-app-plan.md §4.10）：
+//   · suite（代开发）：一个部署 = 一个服务商账号下的一套代开发模板。凭据是 suite_id/suite_secret，
+//     「哪个企业装了哪个应用」不写配置：create_auth 回调推 AuthCode → 换 permanent_code →
+//     落 wecom_app_profile，新增企业只需扫码授权，**不改配置、不重启**。
+//   · corp（企业内部应用 / 自建应用）：一套部署 = 一家企业，凭据是 corpid + 应用 Secret + AgentId。
+//     没有套件流程，也没有开通链接；档案行由后台「验证并接入」写入。
+//
+// 两套的来源不同但**企业侧数据链路完全相同**：代开发的 permanent_code 就是当 corpsecret 用的，
+// 所以下面凡是「拿企业 token / 读通讯录 / 换 userid」的代码都只有一份实现。
+//
+// 回声（业务上最容易混）：
+//   · `wecom_callback_token` / `wecom_encoding_aes_key` = 代开发**指令回调**那一组（服务商后台填）；
+//   · `wecom_corp_callback_token` / `wecom_corp_encoding_aes_key` = 自建应用**通讯录同步 → 接收事件服务器**
+//     那一组（企业管理员在自己后台填）。两组不同源，不能互相顶替。
 //
 // 与 ldap 同口径：启用开关走 sys_setting（`wecom.enabled`），凭据走部署常量。
 
 import { b64ToBytes } from "./crypt";
 
+/** 应用来源：代开发（套件） / 企业内部应用（自建） */
+export type WecomKind = "suite" | "corp";
+
 /**
  * 回调引导配置（Tier A）：echostr URL 验证 + 永久码落库加密所需的全部凭据。
  * 这四项**全部由部署方在本地生成**，与企业微信无关——所以可以在「创建代开发模版 / 拿到
@@ -21,12 +33,12 @@ export interface WecomCallbackConfig {
 	token: string
 	/** 回调加密密钥（43 字符 EncodingAESKey） */
 	encodingAesKey: string
-	/** AES-GCM 落库密钥（hex/base64，16 或 32 字节）：加密 permanent_code/secret */
+	/** AES-GCM 落库密钥（hex/base64，16 或 32 字节）：加密永久码 / 应用 Secret */
 	encKey: string
 	/**
 	 * 连接器基址（绝对地址，无尾斜杠），如 `https://site.example.com/api/auth/wecom`。
 	 * 两个派生地址都由它拼出，避免「同一件事配两处、改一处漏一处」：
-	 *   · 指令回调 URL = `<base>/event` → **原样填进企微后台**（须逐字一致，含协议与路径）
+	 *   · 回调 URL = `<base>/event` → **原样填进企微后台**（须逐字一致，含协议与路径）
 	 *   · 网页授权 redirect_uri = `<base>/callback`
 	 */
 	baseUrl: string
@@ -51,6 +63,61 @@ export interface WecomConfig extends WecomCallbackConfig {
 	providerSecret: string
 }
 
+/**
+ * 企业内部应用（自建应用）的部署常量。
+ *
+ * 一套部署只服务一家企业——这是产品定位而非技术妥协：凭据是「企业 × 应用」维度的，
+ * 进配置就意味着单企业；多企业共用一套部署的需求由代开发承担（扫码即装）。
+ */
+export interface WecomCorpConfig {
+	/** 企业 ID（企微后台「我的企业 → 企业信息 → 企业ID」），同时是租户键 */
+	corpId: string
+	/** 应用 Secret（应用详情页）——换过必须重新走「验证并接入」 */
+	corpSecret: string
+	/** 应用 AgentId（应用详情页） */
+	agentId: string
+	/** 通讯录同步「接收事件服务器」的 Token（不配 = 不做事件增量） */
+	callbackToken: string
+	/** 同上 → EncodingAESKey */
+	encodingAesKey: string
+	encKey: string
+	baseUrl: string
+}
+
+/** 与来源无关的两项：登录/同步/回跳都只需要它们 */
+export interface WecomBase {
+	encKey: string
+	baseUrl: string
+}
+
+/** 一次性读出全部部署常量（未 trim 的尾斜杠在此归一） */
+function readWecomVars() {
+	return {
+		token: vars.get("wecom_callback_token") ?? "",
+		encodingAesKey: vars.get("wecom_encoding_aes_key") ?? "",
+		encKey: vars.get("wecom_enc_key") ?? "",
+		baseUrl: (vars.get("wecom_base_url") ?? "").replace(/\/+$/, ""),
+		suiteId: vars.get("wecom_suite_id") ?? "",
+		suiteSecret: vars.get("wecom_suite_secret") ?? "",
+		providerId: vars.get("wecom_provider_id") ?? "",
+		providerSecret: vars.get("wecom_provider_secret") ?? "",
+		corpId: vars.get("wecom_corp_id") ?? "",
+		corpSecret: vars.get("wecom_corp_secret") ?? "",
+		agentId: vars.get("wecom_corp_agent_id") ?? "",
+		corpCallbackToken: vars.get("wecom_corp_callback_token") ?? "",
+		corpEncodingAesKey: vars.get("wecom_corp_encoding_aes_key") ?? "",
+		allowCoexist: vars.get("wecom_allow_coexist") ?? "",
+	};
+}
+
+type WecomVars = ReturnType<typeof readWecomVars>;
+
+/** 与来源无关的两项：登录 / 回跳 / 同步 / 回调验签之外的一切路径都只认它 */
+const REQUIRED_BASE: Array<[keyof WecomBase, string]> = [
+	["encKey", "wecom_enc_key"],
+	["baseUrl", "wecom_base_url"],
+];
+
 // Tier A：部署方本地生成，创建模版前即可配齐（token / EncodingAESKey / 落库密钥 / 基址）。
 const REQUIRED_CALLBACK: Array<[keyof WecomCallbackConfig, string]> = [
 	["token", "wecom_callback_token"],
@@ -66,26 +133,21 @@ const REQUIRED_SUITE: Array<[keyof WecomConfig, string]> = [
 ];
 
 // Tier C：服务商凭证（provider_access_token 源）。**仅「生成授权链接」需要**，不影响
-// login/callback/create_auth 等 suite 流程，故不进 readWecomConfig 的必填集合（readWecomConfig
+// login/callback/create_auth 等 suite 流程，故不进 readSuiteConfig 的必填集合（readSuiteConfig
 // 被登录链路复用，缺 provider 凭证不该让登录 400）。createInstall 单独校验。
 const REQUIRED_PROVIDER: Array<[keyof WecomConfig, string]> = [
 	["providerId", "wecom_provider_id"],
 	["providerSecret", "wecom_provider_secret"],
 ];
 
-/** 一次性读出六处部署常量（未 trim 的尾斜杠在此归一） */
-function readWecomVars(): WecomConfig {
-	return {
-		token: vars.get("wecom_callback_token") ?? "",
-		encodingAesKey: vars.get("wecom_encoding_aes_key") ?? "",
-		encKey: vars.get("wecom_enc_key") ?? "",
-		baseUrl: (vars.get("wecom_base_url") ?? "").replace(/\/+$/, ""),
-		suiteId: vars.get("wecom_suite_id") ?? "",
-		suiteSecret: vars.get("wecom_suite_secret") ?? "",
-		providerId: vars.get("wecom_provider_id") ?? "",
-		providerSecret: vars.get("wecom_provider_secret") ?? "",
-	};
-}
+// 自建应用：三项缺一不可（Secret 换 token，AgentId 既进授权 URL 也进 token 缓存键）。
+// 类型按「变量名」而不是按配置接口来标：`WecomCorpConfig.encodingAesKey` 是**自建应用回调**那把，
+// 而变量里同名字段 `wecom_encoding_aes_key` 是**代开发**那把——按接口标会在这两者之间打错。
+const REQUIRED_CORP: Array<[keyof WecomVars, string]> = [
+	["corpId", "wecom_corp_id"],
+	["corpSecret", "wecom_corp_secret"],
+	["agentId", "wecom_corp_agent_id"],
+];
 
 /**
  * 落库密钥格式校验（fail-fast 在**读配置**处，而不是等 create_auth 时在 crypto 里炸）：
@@ -108,53 +170,201 @@ export function assertEncKey(encKey: string): void {
 		throw Object.assign(new Error("企业微信配置错误：wecom_enc_key 必须是 16 或 32 字节的 hex（32/64 字符）或 base64"), { status: 400 });
 }
 
+/** 缺项文案：一次报全，省掉逐轮补配置的往返 */
+function missingError(names: string[], hint: string): Error {
+	return Object.assign(new Error(`企业微信未配置：config vars 缺少 ${names.join(" / ")}${hint}`), { status: 400 });
+}
+
+function assertBaseUrl(baseUrl: string): void {
+	if (!/^https?:\/\//.test(baseUrl))
+		throw Object.assign(new Error("企业微信配置错误：wecom_base_url 必须是绝对地址（企微回调与 redirect_uri 都要求）"), { status: 400 });
+}
+
 /**
- * 校验服务商凭证（生成授权链接必需）。缺任一即 400 并点名缺哪两项——
- * 区分于 suite 凭证：那是「模版创建后下发」，provider 凭证是「服务商后台通用开发参数」里拿的。
+ * 读与来源无关的两项（落库密钥 + 基址）。
+ *
+ * 登录 / 302 回跳 / 同步只用到这两项，**不该要求 suite 或 corp 的凭据**——这正是两种来源
+ * 能共存的前提：否则自建应用的部署会在「读 wecom_suite_id」处直接 400。
  */
-export function assertProviderConfig(cfg: WecomConfig): void {
-	const missing = REQUIRED_PROVIDER.filter(([field]) => !cfg[field]).map(([, name]) => name);
+export function readBase(): WecomBase {
+	const v = readWecomVars();
+	const missing = REQUIRED_BASE.filter(([field]) => !v[field]).map(([, name]) => name);
 	if (missing.length)
-		throw Object.assign(new Error(`企业微信未配置：生成授权链接需要 ${missing.join(" / ")}（服务商后台「通用开发参数」页获取，与 suite 凭证不同源）`), { status: 400 });
+		throw missingError(missing, "");
+	assertBaseUrl(v.baseUrl);
+	assertEncKey(v.encKey);
+	return { encKey: v.encKey, baseUrl: v.baseUrl };
 }
 
 /**
- * 读 Tier A 凭据（token / aeskey / encKey / baseUrl）。**不依赖 suite 凭据**：这是 echostr
- * URL 验证与永久码落库加密所需的全部东西，部署方本地即可生成。引导期（suite_id 尚未下发）
- * 服务也能靠它启动并响应企微的回调验证（plan §18）。
+ * 读 Tier A 凭据（**代开发**的回调 token / aeskey / 落库密钥 / 基址）。**不依赖 suite 凭据**：
+ * 这是 echostr URL 验证与永久码落库加密所需的全部东西，部署方本地即可生成。引导期（suite_id
+ * 尚未下发）服务也能靠它启动并响应企微的回调验证（plan §18）。
+ *
+ * 缺项校验**不复用 readBase**：那样只会报出最先撞上的那一项，运维得逐轮补配置
+ * （「缺项一次报全」是这套配置体系的既有纪律）。
  */
 export function readCallbackConfig(): WecomCallbackConfig {
 	const v = readWecomVars();
 	const missing = REQUIRED_CALLBACK.filter(([field]) => !v[field]).map(([, name]) => name);
 	if (missing.length)
-		throw Object.assign(new Error(`企业微信未配置：config vars 缺少 ${missing.join(" / ")}`), { status: 400 });
-	if (!/^https?:\/\//.test(v.baseUrl))
-		throw Object.assign(new Error("企业微信配置错误：wecom_base_url 必须是绝对地址（企微回调与 redirect_uri 都要求）"), { status: 400 });
+		throw missingError(missing, "");
+	assertBaseUrl(v.baseUrl);
 	assertEncKey(v.encKey);
 	return { token: v.token, encodingAesKey: v.encodingAesKey, encKey: v.encKey, baseUrl: v.baseUrl };
 }
 
 /**
- * 读完整部署常量。缺任一必需项即 400（「未配置」是运维事实，不是服务端缺陷）。
- * 一次报全 Tier A + Tier B 所有缺失项，省掉逐轮补配置的往返；suite 凭据（Tier B）缺失时
- * 文案点明「由代开发模版创建成功后下发」，避免运维误以为是本地漏配。
+ * 读完整 suite 配置（代开发）。缺任一必需项即 400（「未配置」是运维事实，不是服务端缺陷）。
+ * 一次报全 Tier A + Tier B 所有缺失项；suite 凭据（Tier B）缺失时文案点明「由代开发模版创建成功后
+ * 下发」，避免运维误以为是本地漏配。
  *
  * 注：Tier B 缺失只影响 login/callback/create_auth 等 suite 流程；echostr 验证走
- * `readCallbackConfig()`，不受此约束（见 api.ts::event.get）。
+ * `readCallbackConfig()`，不受此约束。
  */
-export function readWecomConfig(): WecomConfig {
+export function readSuiteConfig(): WecomConfig {
 	const v = readWecomVars();
 	const missing = [...REQUIRED_CALLBACK, ...REQUIRED_SUITE].filter(([field]) => !v[field]).map(([, name]) => name);
 	if (missing.length)
-		throw Object.assign(new Error(`企业微信未配置：config vars 缺少 ${missing.join(" / ")}（suite 凭据由代开发模版创建成功后下发）`), { status: 400 });
-	if (!/^https?:\/\//.test(v.baseUrl))
-		throw Object.assign(new Error("企业微信配置错误：wecom_base_url 必须是绝对地址（企微回调与 redirect_uri 都要求）"), { status: 400 });
+		throw missingError(missing, "（suite 凭据由代开发模版创建成功后下发）");
+	assertBaseUrl(v.baseUrl);
+	assertEncKey(v.encKey);
+	return {
+		token: v.token,
+		encodingAesKey: v.encodingAesKey,
+		encKey: v.encKey,
+		baseUrl: v.baseUrl,
+		suiteId: v.suiteId,
+		suiteSecret: v.suiteSecret,
+		providerId: v.providerId,
+		providerSecret: v.providerSecret,
+	};
+}
+
+/**
+ * 读自建应用配置。回调那两项**不在必填集合**：不配只是没有事件增量，
+ * 全量同步与登录照样能用（见 contacts 的「加速器不是权威」定位）。
+ */
+export function readCorpConfig(): WecomCorpConfig {
+	const v = readWecomVars();
+	const missing = REQUIRED_CORP.filter(([field]) => !v[field]).map(([, name]) => name);
+	if (missing.length)
+		throw missingError(missing, "（自建应用：企业ID / 应用Secret / AgentId，均在企微管理后台取）");
+	assertBaseUrl(v.baseUrl);
 	assertEncKey(v.encKey);
-	return v;
+	return {
+		corpId: v.corpId,
+		corpSecret: v.corpSecret,
+		agentId: v.agentId,
+		callbackToken: v.corpCallbackToken,
+		encodingAesKey: v.corpEncodingAesKey,
+		encKey: v.encKey,
+		baseUrl: v.baseUrl,
+	};
+}
+
+/** 是否显式允许两种来源同时生效 */
+function coexistAllowed(v: WecomVars): boolean {
+	return /^(?:1|true|yes)$/i.test(v.allowCoexist.trim());
+}
+
+/**
+ * 只看「哪套凭据填齐了」，**不做共存校验、不抛错**。
+ * 后台页要能展示「配了什么、还差什么」——配置事故恰恰是最需要它显示清楚的时刻。
+ */
+export function configuredKinds(): WecomKind[] {
+	const v = readWecomVars();
+	const kinds: WecomKind[] = [];
+	if (v.suiteId && v.suiteSecret)
+		kinds.push("suite");
+	if (v.corpId && v.corpSecret && v.agentId)
+		kinds.push("corp");
+	return kinds;
+}
+
+/** 本部署自建应用的三项（后台页展示用；未配齐时为 null） */
+export function corpIdentity(): { corpId: string, agentId: string, hasCallback: boolean } | null {
+	const v = readWecomVars();
+	if (!v.corpId || !v.corpSecret || !v.agentId)
+		return null;
+	return { corpId: v.corpId, agentId: v.agentId, hasCallback: Boolean(v.corpCallbackToken && v.corpEncodingAesKey) };
+}
+
+/**
+ * 本部署已配置的**来源**（凭据齐 = 启用）。这是唯一判定口径，不另设 `wecom_mode`：
+ * 「变量填了没有」是客观事实，不会与运行期实际能力漂移。
+ *
+ * 两种来源都配齐时必须显式 `wecom_allow_coexist: 'true'`——否则 fail-fast。这条不是洁癖：
+ * 两套凭据同时生效会让回调验签多一次尝试、档案里多一类行，配置事故（比如从代开发迁到自建
+ * 却忘了清旧变量）应当被看见，而不是被静默择一。
+ */
+export function wecomKinds(): WecomKind[] {
+	const v = readWecomVars();
+	const kinds = configuredKinds();
+	if (kinds.length === 0) {
+		throw missingError(
+			["wecom_suite_id / wecom_suite_secret", "wecom_corp_id / wecom_corp_secret / wecom_corp_agent_id"],
+			"（二选一：代开发填 suite 两项，企业内部应用填 corp 三项）",
+		);
+	}
+	if (kinds.length > 1 && !coexistAllowed(v))
+		throw missingError(["wecom_allow_coexist: 'true'"], "（检测到代开发与自建应用两套凭据同时配置；确认要共存请显式开启）");
+	return kinds;
+}
+
+/** 一套可用于回调验签的凭据。`receiver` 是明文里的 receiveid（suite=suite_id，corp=corpid） */
+export interface CallbackCreds {
+	kind: WecomKind
+	token: string
+	encodingAesKey: string
+	receiver: string
+}
+
+/**
+ * 列出可用于回调验签的凭据，**按代开发优先**（存量部署行为不变）。
+ *
+ * 两套的 Token/EncodingAESKey 不同源，而验签必须发生在解密之前——所以入口只能逐个试签
+ * （SHA1 一次，成本可忽略），用命中的那把钥匙解密。这比给两种来源各开一条路由更省：
+ * 少一个端点、少一份重复的「验签→重放→解密」接线，且回调地址只有 `/event` 一个。
+ *
+ * **刻意不经过 `wecomKinds()`**：这里列的是「回调钥匙」，不是「启用了哪几种来源」。两者在引导期
+ * 不重合——代开发模版还没建、`suite_id`/`suite_secret` 一项未填，但 Token/EncodingAESKey 已经能填，
+ * 企微正在该 URL 上做保存校验。要是按来源过滤，验证立刻 400，死锁（plan §18）就又回来了。
+ * 所以判据只有一条：**这一组的 token 与 aeskey 是否都填了**。
+ *
+ * 共存守卫单独做：只有**两套身份凭据都齐**（`configuredKinds().length > 1`）才算配置事故，
+ * 引导期的「只有回调钥匙」不算。
+ */
+export function callbackCreds(): CallbackCreds[] {
+	const v = readWecomVars();
+	if (configuredKinds().length > 1 && !coexistAllowed(v))
+		throw missingError(["wecom_allow_coexist: 'true'"], "（检测到代开发与自建应用两套凭据同时配置；确认要共存请显式开启）");
+	const list: CallbackCreds[] = [];
+	if (v.token && v.encodingAesKey)
+		list.push({ kind: "suite", token: v.token, encodingAesKey: v.encodingAesKey, receiver: v.suiteId });
+	if (v.corpCallbackToken && v.corpEncodingAesKey)
+		list.push({ kind: "corp", token: v.corpCallbackToken, encodingAesKey: v.corpEncodingAesKey, receiver: v.corpId });
+	if (list.length === 0) {
+		throw missingError(
+			["wecom_callback_token / wecom_encoding_aes_key", "wecom_corp_callback_token / wecom_corp_encoding_aes_key"],
+			"（回调验签凭据一组都没配；自建应用填「通讯录同步 → 接收事件服务器」那一组）",
+		);
+	}
+	return list;
+}
+
+/**
+ * 校验服务商凭证（生成授权链接必需）。缺任一即 400 并点名缺哪两项——
+ * 区分于 suite 凭证：那是「模版创建后下发」，provider 凭证是「服务商后台通用开发参数」里拿的。
+ */
+export function assertProviderConfig(cfg: WecomConfig): void {
+	const missing = REQUIRED_PROVIDER.filter(([field]) => !cfg[field]).map(([, name]) => name);
+	if (missing.length)
+		throw Object.assign(new Error(`企业微信未配置：生成授权链接需要 ${missing.join(" / ")}（服务商后台「通用开发参数」页获取，与 suite 凭证不同源）`), { status: 400 });
 }
 
 /**
- * 企微后台「指令回调 URL / 应用回调 URL」：原样填这个（base + `/event`）。
+ * 企微后台「指令回调 URL / 通讯录同步接收事件服务器」：原样填这个（base + `/event`）。
  *
  * **不带 `?callback_format=json`**——查过官方文档才这么定的：该参数只在「对外收款」的指令回调
  * 文档（97478）里有说明，而代开发 / 第三方应用所属的**通用回调配置**（96238 §3.2）至今只写
@@ -165,12 +375,12 @@ export function readWecomConfig(): WecomConfig {
  * 代价却是把「企业管理员扫码能否装成功」押在上游实现上。服务端两种包体都认（payload.ts），
  * 上游哪天默认改 JSON 也不用动这里。
  */
-export function eventUrlOf(cfg: WecomConfig): string {
+export function eventUrlOf(cfg: { baseUrl: string }): string {
 	return `${cfg.baseUrl}/event`;
 }
 
 /** 网页授权 redirect_uri（base + /callback） */
-export function loginRedirectOf(cfg: WecomConfig): string {
+export function loginRedirectOf(cfg: { baseUrl: string }): string {
 	return `${cfg.baseUrl}/callback`;
 }
 
@@ -184,7 +394,7 @@ const CONNECTOR_SUFFIX = "/api/auth/wecom";
  * 回跳到 `/login` 会打到宿主机根的别的应用（或 404）。前缀不另配一个变量——它就等于
  * `wecom_base_url` 去掉本连接器的固定后缀，配一处即可，且不匹配时**报错**而不是猜。
  */
-export function siteRootOf(cfg: WecomConfig): string {
+export function siteRootOf(cfg: { baseUrl: string }): string {
 	const url = new URL(cfg.baseUrl);
 	const path = url.pathname.replace(/\/+$/, "");
 	if (!path.endsWith(CONNECTOR_SUFFIX))

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

@@ -1,4 +1,5 @@
 import type { WecomClient, WecomDept } from "./client";
+import type { WecomKind } from "./config";
 import type { MemberDetail } from "./login";
 import type { CallbackFields } from "./payload";
 import type { WecomStoreDeps } from "./store";
@@ -32,6 +33,11 @@ const ORIGIN = "wecom";
 export interface ContactEventDeps {
 	client: WecomClient
 	store: WecomStoreDeps
+	/**
+	 * 本次回调**验签命中的**凭据来源（由入口从 `callbackCreds()` 传下来）。
+	 * 同一家企业可能有代开发行与自建行，取哪一行的 secret 决定这次事件读通讯录能不能成。
+	 */
+	credentialKind: WecomKind
 }
 
 /** 一条事件的执行上下文：企业已授权 → 应用 与 永久码（= 企业应用 secret） */
@@ -73,7 +79,7 @@ export async function handleContactChange(fields: CallbackFields, deps: ContactE
 async function applyChange(changeType: string, corpId: string, fields: CallbackFields, deps: ContactEventDeps): Promise<boolean> {
 	if (!corpId)
 		throw new Error("报文里没有企业身份（ToUserName / AuthCorpId 皆空）");
-	const auth = await findCorpAuth(corpId, deps.store);
+	const auth = await findCorpAuth(corpId, deps.store, deps.credentialKind);
 	if (!auth)
 		throw new Error("该企业未授权本站（wecom_app_profile 无记录）");
 	const ctx: CorpCtx = {