@oj-module/cli 0.2.43 → 0.2.45

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

@@ -0,0 +1,127 @@
+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 走后者）。
+//
+// 为什么这几件事必须由回调驱动（而不是管理端手工录）：
+//   · suite_ticket 每 10 分钟推一次、30 分钟过期，拿不到就换不出 suite_access_token，
+//     整套「企业授权 → 应用 secret → 企业 token」链路全断；
+//   · permanent_code（= 代开发应用的 secret）只在 create_auth / reset_permanent_code 时
+//     由 AuthCode 一次性换取，企微后台**不显示**它；
+//   · 企业解绑/取消授权只在 cancel_auth 出现。
+// 因此这里不是「可选的后台功能」，是代开发模式的下限能力。
+//
+// 响应纪律：处理完返回（路由回纯文本 success）。企微 5 秒内拿不到 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";
+
+/** suite_ticket 官方有效期 30 分钟（10 分钟推一次）；本地按 30 分钟作废，宁可拒一次也不拿过期票打企微 */
+const SUITE_TICKET_TTL_SECS = 30 * 60;
+
+export interface SuiteEventDeps {
+	cfg: WecomConfig
+	client: WecomClient
+	store: WecomStoreDeps
+}
+
+/** 事件里带的 State（授权链接自定义参数）：只认 `env=xxx` 或裸环境名，其余一律按正式环境 */
+export function envOfState(state: string | null): string {
+	if (!state)
+		return "prod";
+	const trimmed = state.trim();
+	const kv = /^env=([\w-]+)$/i.exec(trimmed);
+	if (kv)
+		return kv[1]!.toLowerCase();
+	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;
+}
+
+/** 该 corp 的所有应用都标记为停用，并吊销其租户下的全部会话 */
+async function disableCorp(corpId: string, deps: SuiteEventDeps): Promise<void> {
+	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));
+	await setProfileStatus(corpId, "disabled", deps.store);
+	// 会话必须与授权同频：解绑后旧 refresh 串不得继续换新 access token。
+	// tenant 条件写死在 SQL 里（不用 truncate：它的清理范围取决于本请求是否已绑过租户），
+	// 取消授权回调是匿名端点，不该依赖那种隐式前提。
+	await revokeTenantSessions(tenantOfCorp(corpId));
+	invalidateAllUsers();
+}
+
+/** AuthCode → permanent_code → 按 agent 逐个 upsert profile（幂等；同一企业多应用各自一行） */
+async function applyAuthCode(authCode: string, state: string | null, deps: SuiteEventDeps): Promise<{ corpId: string, agentIds: string[] }> {
+	const { cfg, client, store } = deps;
+	const suiteTicket = await getSuiteTicket(cfg.suiteId, store);
+	const suiteToken = await client.suiteAccessToken(cfg.suiteId, cfg.suiteSecret, suiteTicket.ticket);
+	const granted = await client.permanentCodeByAuthCode(suiteToken, authCode);
+	const env = envOfState(state ?? granted.state);
+	for (const agentId of granted.agentIds) {
+		await saveProfile({
+			suiteId: cfg.suiteId,
+			corpId: granted.corpId,
+			authCorpId: granted.corpId,
+			agentId,
+			env,
+			corpName: granted.corpName,
+			permanentCode: granted.permanentCode,
+		}, 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 } });
+	return { corpId: granted.corpId, agentIds: granted.agentIds };
+}
+
+/** 处理一条已验签并解密的回调明文；返回值仅用于日志（未知 InfoType 也回 success，不触发重推） */
+export async function handleSuiteEvent(plaintext: string, deps: SuiteEventDeps): Promise<string> {
+	const infoType = xmlField(plaintext, "InfoType") ?? "";
+	const suiteId = xmlField(plaintext, "SuiteId") ?? "";
+	if (suiteId && suiteId !== deps.cfg.suiteId)
+		throw Object.assign(new Error("企微事件 SuiteId 与本部署配置不一致"), { status: 400 });
+
+	switch (infoType) {
+		case "suite_ticket": {
+			const ticket = requireField(plaintext, "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);
+			return infoType;
+		}
+		case "create_auth":
+		case "reset_permanent_code": {
+			const authCode = requireField(plaintext, "AuthCode", infoType);
+			const applied = await applyAuthCode(authCode, xmlField(plaintext, "State"), 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);
+			log.info("wecom auth changed", "corpId", authCorpId);
+			return infoType;
+		}
+		case "cancel_auth": {
+			const authCorpId = requireField(plaintext, "AuthCorpId", infoType);
+			await disableCorp(authCorpId, deps);
+			await recordOp({ action: "wecom.auth.cancel", module: "auth", target: authCorpId, level: 4 });
+			log.warn("wecom auth cancelled", "corpId", authCorpId);
+			return infoType;
+		}
+		default:
+			// 通讯录变更等事件本模块不消费：记账即可，回 success 让企微别再推
+			log.info("wecom event ignored", "infoType", infoType);
+			return infoType;
+	}
+}

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

@@ -0,0 +1,137 @@
+// 企微登录领域服务：授权链接构造、state 一次性票据、code→userid、JIT 建档。
+//
+// 两条入口（都落在同一个回调上）：
+//   · 企微客户端内打开（UA 含 wxwork）→ 网页授权 snsapi_base，静默拿 code；
+//   · 普通浏览器 → qrConnect 扫码（appid=corpid + agentid）。
+// 二者换 userid 走同一个 `auth/getuserinfo`（代开发=自建应用口径，不是第三方应用口径）。
+//
+// JIT（无独立注册）：外部身份沿用 `wecom:<userid>` 用户名前缀（D6），口令哈希占位 `!wecom`
+// （任何口令都验不过，低信任来源不接管本地号，同 ldap 的 `!ldap`）；外层租户由 corp_id 决定。
+import type { WecomCache } from "./client";
+
+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";
+
+/** 登录票据有效期：302 落地后 SPA 立即兑换，180s 足够；越短越安全 */
+export const LOGIN_TICKET_TTL_SECS = 180;
+
+/** state 一次性票据（kv）：既不进 URL 也不可伪造——随机 nonce 即凭证，服务端查得到才认 */
+export const LOGIN_STATE_TTL_SECS = 600;
+
+export interface PendingLogin {
+	corpId: string
+	agentId: string
+	env: string
+}
+
+export function isWecomUa(ua: string): boolean {
+	return /wxwork/i.test(ua);
+}
+
+/**
+ * 授权链接。`redirect_uri` 必须整串 encode（含自己的 query），否则企微会把我们的参数当自己的解析。
+ * 扫码用 qrConnect（`appid` + `agentid`）；企微内用 oauth2 授权（scope 固定 snsapi_base：
+ * 只换 userid，不弹授权页，够 JIT 与身份识别；要姓名头像再加 snsapi_privateinfo，属 Phase 3）。
+ */
+export function buildAuthorizeUrl(opts: {
+	corpId: string
+	agentId: string
+	redirectUri: string
+	state: string
+	inWecom: boolean
+}): string {
+	const redirect = encodeURIComponent(opts.redirectUri);
+	const appid = encodeURIComponent(opts.corpId);
+	const agentid = encodeURIComponent(opts.agentId);
+	if (opts.inWecom) {
+		return `${AUTHORIZE_IN_APP}?appid=${appid}&redirect_uri=${redirect}&response_type=code&scope=snsapi_base&state=${encodeURIComponent(opts.state)}&agentid=${agentid}#wechat_redirect`;
+	}
+	return `${AUTHORIZE_QRCODE}?appid=${appid}&agentid=${agentid}&redirect_uri=${redirect}&state=${encodeURIComponent(opts.state)}`;
+}
+
+export async function putLoginState(nonce: string, pending: PendingLogin, cache: WecomCache): Promise<void> {
+	await cache.set(`wecom:state:${nonce}`, JSON.stringify(pending), LOGIN_STATE_TTL_SECS);
+}
+
+/** 取并立即删除（一次性）：拿不到 = 过期/伪造/已用过 */
+export async function takeLoginState(nonce: string, cache: WecomCache): Promise<PendingLogin> {
+	const raw = await cache.get(`wecom:state:${nonce}`);
+	if (!raw)
+		throw Object.assign(new Error("登录状态已失效，请从企业微信重新进入"), { status: 400 });
+	await cache.del(`wecom:state:${nonce}`);
+	const parsed = JSON.parse(raw) as Partial<PendingLogin>;
+	if (!parsed.corpId || !parsed.agentId)
+		throw Object.assign(new Error("登录状态已失效，请从企业微信重新进入"), { status: 400 });
+	return { corpId: parsed.corpId, agentId: parsed.agentId, env: parsed.env ?? "prod" };
+}
+
+/** 外部号用户名命名空间（D6）：与 ldap:/sso: 同约定，禁止本地建号占用 */
+export function externalUsername(userid: string): string {
+	return `wecom:${userid}`;
+}
+
+/** 占位口令哈希：bcrypt.verify 对任何口令返回 false（与 `!ldap` 同义） */
+export const WECOM_PASSWORD_PLACEHOLDER = "!wecom";
+
+/**
+ * JIT find-or-create（租户由调用方先 ensureTenant 绑好，insert 的 tenant_id 由 sql_guard 自动填）。
+ * 返回 uid 与禁用位：禁号仍要拦（企微侧未移除，本地已停用时拒绝签发）。
+ *
+ * `resolveName` 只在**首次建档**时调用一次（老用户不为此多打一次上游）：拿到名字就写进
+ * `display_name`，拿不到（无通讯录权限/上游抖）用工号兜底——用户列表里宁可显示工号，也不要空白行。
+ */
+export async function ensureWecomUser(
+	corpId: string,
+	userid: string,
+	resolveName?: () => Promise<string | null>,
+): Promise<{ uid: number, forbidden: boolean }> {
+	const username = externalUsername(userid);
+	let rows = await db.table("users").select(["id", "is_forbidden"]).where({ field: "username", op: "eq", value: username }).all() as Array<{ id: number, is_forbidden: number }>;
+	if (!rows.length) {
+		const name = resolveName ? await resolveName().catch(() => null) : null;
+		try {
+			await db.table("users").insert({
+				username,
+				display_name: name?.trim() || userid,
+				password_hash: WECOM_PASSWORD_PLACEHOLDER,
+				avatar_base64: "",
+				source: "wecom",
+				corp_id: corpId,
+				must_change: 0,
+				is_forbidden: 0,
+			}).run();
+		}
+		catch (e) {
+			// 唯一约束兜底（预查与插入间的竞态，同 createUser / ldap 模式）：撞 (tenant_id, username) → 回查复用
+			if (!/unique|constraint/i.test(e instanceof Error ? e.message : String(e)))
+				throw e;
+		}
+		rows = await db.table("users").select(["id", "is_forbidden"]).where({ field: "username", op: "eq", value: username }).all() as Array<{ id: number, is_forbidden: number }>;
+	}
+	if (!rows.length)
+		throw Object.assign(new Error("账号建档失败"), { status: 500 });
+	return { uid: Number(rows[0]!.id), forbidden: Number(rows[0]!.is_forbidden) === 1 };
+}
+
+/**
+ * 换会话前的最后一道闸：建号可能已过几分钟（票据 TTL 180s），期间管理员可能停用了这个号。
+ * 「企微侧还在、本地已停用」必须以本地为准（停用是安全动作，不能被 IdP 覆盖）。
+ */
+export async function assertUserActive(uid: number): Promise<void> {
+	const rows = await db.table("users").select(["is_forbidden"]).where({ field: "id", op: "eq", value: uid }).all() as Array<{ is_forbidden: number }>;
+	if (!rows[0])
+		throw Object.assign(new Error("账号不存在"), { status: 401 });
+	if (Number(rows[0].is_forbidden) === 1)
+		throw Object.assign(new Error("账号已被停用，请联系管理员"), { status: 403 });
+}
+
+/**
+ * 302 落地地址：票据只能走 query（浏览器历史/Referer 可见，故只是**一次性票**，不是 token）。
+ * `tenant` 一并带上：前端 tenantStore 启动时读它 → 后续每个请求的 `X-TENANT-ID` 才对得上，
+ * 否则换票请求会落到默认租户、被 `ensureTenant` 判成 403。
+ * 路径用 SPA 默认的 browser 路由 `/login`；hash 路由部署由前端 Phase 2 的落地页自行改写。
+ */
+export function loginLandingUrl(opts: { origin: string, ticket: string, tenant: string }): string {
+	const q = new URLSearchParams({ wecom_ticket: opts.ticket, tenant: opts.tenant });
+	return `${opts.origin}/login?${q.toString()}`;
+}

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

@@ -0,0 +1,66 @@
+// 企微指令回调的**重放防护**（2026-10-30 补缺口）。
+//
+// 为什么必须有第二道：企微的验签只证明「这个报文是拿着 Token 的一方签的」，
+// 而 (timestamp, nonce, Encrypt, msg_signature) 这个组合在 Token 不变的前提下
+// **永久有效**——服务端不校验 timestamp 的新旧，抓到过一次合法回调的人可以在任意
+// 时刻原样重放。最坏的一条是 cancel_auth：重放即触发 disableCorp（整家企业停用 +
+// 吊销该企业全部会话），而企微只在「拿不到 success」时才重推，所以它连报警窗口都没有。
+// 官方 SDK 的解密样例里同样有这一步（此处原本漏掉）。
+//
+// 两道闸：
+//   1. timestamp 新鲜度：与本机时间偏差超过 ±5 分钟即拒（企微→本站是直连 HTTPS，
+//      正常网络与重试延迟在秒级；窗口取 5 分钟只为容忍双方时钟不同步）。
+//   2. nonce 幂等：kv.incr 原子计数，首次才写入 TTL。计数而不是读改写，是为了
+//      「两个并发同 nonce」也只有一个拿到 1（oj 的 kv 在配了 Redis 时是多实例共享的）。
+//
+// 两条都回调 400：它不是「本站要鉴权」的问题，401 会把排查带偏。
+const REPLAY_WINDOW_SECS = 5 * 60;
+/** 计数键存活时间：只要盖住重放窗口即可，避免 kv 无界增长 */
+const NONCE_TTL_SECS = 2 * REPLAY_WINDOW_SECS;
+
+export interface ReplayGate {
+	/** 原子自增并返回新值（kv.incr 同语义） */
+	incr: (key: string) => Promise<number>
+	expire: (key: string, ttlSecs: number) => Promise<unknown>
+	del: (key: string) => Promise<unknown>
+	now: () => number
+}
+
+function fail(status: number, message: string): never {
+	throw Object.assign(new Error(message), { status });
+}
+
+/** 运行时形态：计数走 kv（Redis 时跨实例），时钟取本机秒级时间戳 */
+export function runtimeReplayGate(): ReplayGate {
+	return {
+		incr: key => kv.incr(key),
+		expire: (key, ttlSecs) => kv.expire(key, ttlSecs),
+		del: key => kv.del(key),
+		now: () => Math.floor(Date.now() / 1000),
+	};
+}
+
+/**
+ * 校验一次回调的时效与唯一性。通过 => void；不通过 => 抛 400。
+ * 调用时机：**签名校验之后、解密之前**（先验签避免给未鉴权的请求写 kv，再拦重放省一次解密）。
+ */
+export async function guardReplay(timestampRaw: string, nonce: string, gate: ReplayGate): Promise<void> {
+	const ts = Number(timestampRaw);
+	if (!Number.isInteger(ts) || ts <= 0)
+		fail(400, "回调 timestamp 非法");
+	if (Math.abs(gate.now() - ts) > REPLAY_WINDOW_SECS)
+		fail(400, "回调 timestamp 超出允许窗口：请检查服务器时间，或该请求为历史回调的重放");
+	if (!nonce)
+		fail(400, "回调 nonce 缺失");
+
+	const key = `wecom:nonce:${nonce}`;
+	const seen = Number(await gate.incr(key));
+	if (seen !== 1)
+		fail(400, "回调 nonce 重复：同一条指令回调已被处理过（重放请求已拒绝）");
+	// 首次访问才有资格设 TTL：设不上就删键——留一个没有过期的计数键既让它永久增长，
+	// 也会把未来的同一 nonce（虽概率极低）误判成重放。
+	if (!(await gate.expire(key, NONCE_TTL_SECS))) {
+		log.warn("wecom replay nonce ttl not set", "key", key);
+		await gate.del(key);
+	}
+}

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

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

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

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

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

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

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

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