@oj-module/cli 0.2.49 → 0.2.53

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

@@ -1,17 +1,20 @@
-// 代开发后台（服务商运营面）：GET /auth/wecom/admin/apps · POST /auth/wecom/admin/status · GET /auth/wecom/admin/install
+// 企微后台：GET /auth/wecom/admin/apps · POST /auth/wecom/admin/status · GET /auth/wecom/admin/install
+//          · GET /auth/wecom/admin/overview · POST /auth/wecom/admin/connect
 //
-// 权限：仅超级管理员（`assertSuperAdmin`）。这三件事都是**跨租户**的站点级操作
-// （看所有已授权企业、停用某企业、生成安装链接），不是某个租户的管理员能做的；
-// 用 `assertSystemAdmin` 会把 admin 也放进来，而 admin 属于某个租户，等于让他看别家企业的 corp_id。
+// 权限：仅超级管理员（`assertSuperAdmin`）。这几件事都是**跨租户**的站点级操作
+// （看所有已授权企业、停用某企业、生成安装链接、把本企业自建应用接进来），不是某个租户的
+// 管理员能做的；用 `assertSystemAdmin` 会把 admin 也放进来，而 admin 属于某个租户，
+// 等于让他看别家企业的 corp_id。
 //
-// 三个端点都不挂在 `tenant.anonymous_paths` 里：它们是正常登录后的管理面，必须带租户头，
+// 这些端点都不挂在 `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 { connectCorp, createInstall, listApps, setAppStatus } from "../../_shared/wecom/admin";
 import { createWecomClient, runtimeCache, runtimeHttp } from "../../_shared/wecom/client";
-import { readWecomConfig } from "../../_shared/wecom/config";
+import { configuredKinds, corpIdentity, eventUrlOf, readBase, readCorpConfig, readSuiteConfig, wecomKinds } from "../../_shared/wecom/config";
+import { runtimeStoreDeps } from "../../_shared/wecom/store";
 
 /** 清单：已授权企业 × 应用（不含 permanent_code，secret 不出库） */
 async function get() {
@@ -24,7 +27,7 @@ get.response = {
 	type: "array",
 	items: {
 		type: "object",
-		required: ["suite_id", "corp_id", "agent_id", "auth_corp_id", "env", "status", "auth_mode", "installed_at", "update_time"],
+		required: ["suite_id", "corp_id", "agent_id", "auth_corp_id", "env", "status", "credential_kind", "auth_mode", "installed_at", "update_time"],
 		properties: {
 			suite_id: { type: "string" },
 			corp_id: { type: "string" },
@@ -33,7 +36,9 @@ get.response = {
 			env: { type: "string" },
 			corp_name: { type: ["string", "null"] },
 			status: { type: "string", enum: ["active", "disabled"] },
-			// 权限三态（管理员授权 / 成员授权）——服务商一眼看出哪家企业「装了但同步不了」
+			// 来源：代开发 / 企业内部应用（自建）。同一家企业可能两行都有（迁移期）
+			credential_kind: { type: "string", enum: ["suite", "corp"] },
+			// 权限三态（管理员授权 / 成员授权）——服务商一眼看出哪家企业「装了但同步不了」；自建行恒 0
 			auth_mode: { type: "number" },
 			installed_at: { type: "number" },
 			update_time: { type: "number" },
@@ -41,6 +46,62 @@ get.response = {
 	},
 };
 
+const overview = {
+	/**
+	 * 部署概览：后台页据此决定画哪几张卡片、回调地址填什么。
+	 *
+	 * `configError` 而不是直接 400：配错时最需要页面把「配了什么、缺什么」摆出来，
+	 * 抛错只会让管理员看到一片空白加一行红字。
+	 *
+	 * 形态必须是 `{ get }` 组而不是裸函数：oj 的路由表按「组名 = 路径段 + 动词」生成，
+	 * 根层裸函数不产生路由（`ojm api --check` 会报「oj 树缺少 handler」）。
+	 */
+	async get() {
+		await respond(async () => {
+			await assertSuperAdmin();
+			let configError: string | null = null;
+			try {
+				wecomKinds();
+			}
+			catch (e) {
+				configError = (e as Error).message;
+			}
+			let callbackUrl: string | null = null;
+			try {
+				callbackUrl = eventUrlOf(readBase());
+			}
+			catch {
+				// 基址没配：页面要能把「还差 wecom_base_url」显示出来，而不是整页失败
+				callbackUrl = null;
+			}
+			const self = corpIdentity();
+			return {
+				kinds: configuredKinds(),
+				configError,
+				callbackUrl,
+				corpId: self?.corpId ?? null,
+				agentId: self?.agentId ?? null,
+				corpCallbackConfigured: self?.hasCallback ?? false,
+			};
+		});
+	},
+};
+overview.get.response = {
+	type: "object",
+	required: ["kinds", "configError", "callbackUrl", "corpId", "agentId", "corpCallbackConfigured"],
+	properties: {
+		kinds: { type: "array", items: { type: "string", enum: ["suite", "corp"] } },
+		// 部署配置自检的结论（null = 无问题）：共存没显式开启、两套都缺等
+		configError: { type: ["string", "null"] },
+		// 回调地址：代开发填「指令回调」，自建填「通讯录同步 → 接收事件服务器」，同一个 URL
+		callbackUrl: { type: ["string", "null"] },
+		corpId: { type: ["string", "null"] },
+		agentId: { type: ["string", "null"] },
+		// 自建应用的回调凭据是否配齐（不配 = 没有事件增量，全量同步照常）
+		corpCallbackConfigured: { type: "boolean" },
+	},
+};
+
 const status = {
 	// 启停某个企业的一个应用。停用是安全动作：企业整体停用时同步吊销其会话（见 admin.ts）。
 	async post() {
@@ -100,7 +161,7 @@ const install = {
 	async get() {
 		await respond(async () => {
 			await assertSuperAdmin();
-			const cfg = readWecomConfig();
+			const cfg = readSuiteConfig();
 			const state = String((http.query as Record<string, unknown>)?.state ?? "").trim();
 			return createInstall(
 				cfg,
@@ -120,4 +181,44 @@ install.get.response = {
 	},
 };
 
-export default { apps: { get }, status, install };
+const connect = {
+	// 自建应用没有 `create_auth` 回调：档案行只能由这里显式写入（四步校验全过才落库，见 admin.ts）。
+	// 幂等：重复点 = 重写密文 + 清 token 缓存——**换过 Secret 必须重新点**，页面要把这句写出来。
+	// 没配 corp 凭据的部署点这里直接 400：不写「空 suite_id 的怪档案」，那会让清单多一行查不出用途的行。
+	async post() {
+		await respond(async () => {
+			await assertSuperAdmin();
+			if (!configuredKinds().includes("corp"))
+				throw Object.assign(new Error("本部署未配置企业内部应用凭据（wecom_corp_id / wecom_corp_secret / wecom_corp_agent_id）"), { status: 400 });
+			const cfg = readCorpConfig();
+			const result = await connectCorp(
+				cfg,
+				createWecomClient({ http: runtimeHttp(), cache: runtimeCache() }),
+				runtimeStoreDeps(cfg),
+			);
+			await recordOp({
+				action: "wecom.admin.connect",
+				module: "auth",
+				target: result.corpId,
+				detail: { agentId: result.agentId, departments: result.departments, members: result.members },
+				// 接入 = 建立一条新的身份来源，属站点级配置变更
+				level: 2,
+			});
+			return result;
+		});
+	},
+};
+connect.post.response = {
+	type: "object",
+	required: ["corpId", "agentId", "departments", "members"],
+	properties: {
+		corpId: { type: "string" },
+		agentId: { type: "string" },
+		// 可见范围内的部门数：远小于预期 = 应用可见范围没设全公司
+		departments: { type: "number" },
+		// 示例部门读到的人数：0 不会返回（校验失败），>0 才是「通讯录权限真的通了」
+		members: { type: "number" },
+	},
+};
+
+export default { apps: { get }, overview, status, install, connect };

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

@@ -0,0 +1,41 @@
+// GET /api/auth/wecom/admin/tenant-admin?corpId= —— 查某企业的租户管理员状态。
+//
+// 权限：仅 superadmin。这是**跨租户**的平台级视图（查的是别家企业的管理员有没有开通），
+// 与同目录其它端点一致。只读，不存在也不建——建号由开通流程与 password 端点负责。
+import { assertSuperAdmin } from "#/_platform/_shared/service/infra/access";
+import { respond } from "#/_platform/_shared/respond";
+import { tenantAdminState } from "../../../_shared/wecom/tenant-admin";
+
+async function get() {
+	await respond(async () => {
+		await assertSuperAdmin();
+		const corpId = String(((http.query ?? {}) as Record<string, unknown>).corpId ?? "").trim();
+		if (!corpId)
+			throw Object.assign(new Error("缺少企业代码"), { status: 400 });
+		return tenantAdminState(corpId);
+	});
+}
+
+get.schema = {
+	query: {
+		type: "object",
+		required: ["corpId"],
+		properties: { corpId: { type: "string", minLength: 1 } },
+	},
+};
+
+get.response = {
+	type: "object",
+	required: ["corpId", "username", "exists", "mustChange"],
+	properties: {
+		corpId: { type: "string" },
+		// 固定账号名：每租户各一个（users 唯一键含 tenant_id，互不影响）
+		username: { type: "string" },
+		// 该租户是否已有一个握着 admin 角色的账号
+		exists: { type: "boolean" },
+		// 是否须改密（开通后恒 true，直到本人改过一次）
+		mustChange: { type: "boolean" },
+	},
+};
+
+export default { get };

package/templates/src/auth/api/wecom/admin/tenant-admin/password/api.ts

@@ -0,0 +1,66 @@
+// POST /api/auth/wecom/admin/tenant-admin/password —— 重设某企业的租户管理员口令。
+//
+// 权限：仅 superadmin（跨租户的平台级动作）。
+//
+// 为什么做成「superadmin 自己输入新口令」而不是「系统生成后回显」：
+//   口令只以 bcrypt 落库，**没有任何可逆存储**，所以系统无法回显一个已存在的口令。
+//   让 superadmin 自己输入，他知道这个值 → 直接告知租户管理员即可。代价为零，
+//   收益是全系统不存在静态可读的口令副本。
+//
+// 副作用（都是必需的）：
+//   · must_change = 1 —— 管理员首次登录必须改掉这个临时口令；
+//   · 级联删 refresh —— 改密后旧会话立即失效，避免旧 token 继续可用。
+import { assertSuperAdmin } from "#/_platform/_shared/service/infra/access";
+import { recordOp } from "#/_platform/_shared/service/infra/audit";
+import { respond } from "#/_platform/_shared/respond";
+import { setTenantAdminPassword } from "../../../../_shared/wecom/tenant-admin";
+
+async function post() {
+	await respond(async () => {
+		await assertSuperAdmin();
+		const body = (http.body ?? {}) as { corpId?: unknown, password?: unknown };
+		const corpId = String(body.corpId ?? "").trim();
+		const password = String(body.password ?? "");
+		if (!corpId)
+			throw Object.assign(new Error("缺少企业代码"), { status: 400 });
+		// 与 users/password 同下限（6 位）：太短的口令在交接环节泄露风险更高
+		if (password.length < 6)
+			throw Object.assign(new Error("口令至少 6 位"), { status: 400 });
+
+		const state = await setTenantAdminPassword(corpId, password);
+		await recordOp({
+			action: "wecom.admin.tenant_admin_password",
+			module: "auth",
+			target: corpId,
+			// 不记口令本身（连脱敏都不记）：审计只要能回答「谁在何时给哪个企业重设过」
+			detail: { username: state.username },
+			// 重设他人管理员口令＝接管该租户的最高权限，按安全事件留痕
+			level: 4,
+		});
+		return state;
+	});
+}
+
+post.schema = {
+	body: {
+		type: "object",
+		required: ["corpId", "password"],
+		properties: {
+			corpId: { type: "string", minLength: 1 },
+			password: { type: "string", minLength: 6 },
+		},
+	},
+};
+
+post.response = {
+	type: "object",
+	required: ["corpId", "username", "exists", "mustChange"],
+	properties: {
+		corpId: { type: "string" },
+		username: { type: "string" },
+		exists: { type: "boolean" },
+		mustChange: { type: "boolean" },
+	},
+};
+
+export default { post };

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(() => {});