@oj-module/cli 0.2.42 → 0.2.45

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

@@ -0,0 +1,312 @@
+// 企微代开发「指令回调」的验签与解密原语（Phase 1）。
+//
+// 为什么手写：oj isolate 的 crypto 面（0.1.110 实测，devkit global.d.ts）只有
+// sha256Hex / md5Hex / aesGcm* / verifyEd25519 / verifyEd25519；企微指令回调钉死
+// `msg_signature = sha1(sort(token,timestamp,nonce,Encrypt))` + `AES-256-CBC(PKCS#7)`，
+// 两样都没有。处置与 _platform/api/_lifecycle/sha384.ts 一致：自实现 + 上游需求 R8
+// （`crypto.sha1Hex` / `crypto.aesCbcDecrypt` 原语）。落地 R8 后本文件可直接删。
+//
+// 边界：只做**解密**（回包走明文 `echostr` / `success`），不做加密；输入按字节处理，
+// 长度/填充非法一律抛错（不猜、不截断）——宁可事件处理失败留痕，不可解出半截明文。
+// S 盒不手抄 512 字节常量表：按 FIPS 197 定义式（GF 乘法逆元 + 仿射变换）在加载期生成，
+// 逆 S 盒由置换求逆（加载期一次性，<5ms）。
+
+const BLOCK = 16;
+
+/** GF(2^8) 乘法，域多项式 x^8+x^4+x^3+x+1（0x11B），AES 唯一乘法 */
+function gmul(a: number, b: number): number {
+	let p = 0;
+	let x = a & 0xFF;
+	let y = b & 0xFF;
+	for (let i = 0; i < 8; i++) {
+		if (y & 1)
+			p ^= x;
+		const hi = x & 0x80;
+		x = (x << 1) & 0xFF;
+		if (hi)
+			x ^= 0x1B;
+		y >>= 1;
+	}
+	return p;
+}
+
+/** 乘法逆元（0 的逆元定义为 0）：255 次试乘，加载期一次性 */
+function ginv(a: number): number {
+	if (a === 0)
+		return 0;
+	for (let x = 1; x < 256; x++) {
+		if (gmul(a, x) === 1)
+			return x;
+	}
+	throw new Error("aes: no inverse"); // 不可达（GF(2^8) 除 0 外皆可逆）
+}
+
+const rotl8 = (v: number, n: number): number => ((v << n) | (v >>> (8 - n))) & 0xFF;
+
+// S 盒 = 逆元 ⊕ 循环移位 1/2/3/4 ⊕ 0x63（FIPS 197 §5.1.1）；逆 S 盒 = 该置换的逆
+const SBOX = new Uint8Array(256);
+const INV_SBOX = new Uint8Array(256);
+for (let a = 0; a < 256; a++) {
+	const inv = ginv(a);
+	const s = inv ^ rotl8(inv, 1) ^ rotl8(inv, 2) ^ rotl8(inv, 3) ^ rotl8(inv, 4) ^ 0x63;
+	SBOX[a] = s;
+	INV_SBOX[s] = a;
+}
+
+const NK = 8; // AES-256：密钥 8 个 32bit 字
+const NR = 14; // 轮数
+const RCON = [0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40]; // 只需前 NR/NK = 7 项
+
+/** 密钥扩展（FIPS 197 §5.2）：返回 4*(NR+1) 个 32bit 字，字内 big-endian（b0 在高位） */
+function expandKey(key: Uint8Array): Uint32Array {
+	if (key.length !== 32)
+		throw new Error(`aes: key must be 32 bytes, got ${key.length}`);
+	const w = new Uint32Array(4 * (NR + 1));
+	for (let i = 0; i < NK; i++)
+		w[i] = ((key[4 * i]! << 24) | (key[4 * i + 1]! << 16) | (key[4 * i + 2]! << 8) | key[4 * i + 3]!) >>> 0;
+	for (let i = NK; i < w.length; i++) {
+		let t = w[i - 1]!;
+		if (i % NK === 0) {
+			// RotWord → SubWord → Rcon
+			t = ((t << 8) | (t >>> 24)) >>> 0;
+			t = ((SBOX[(t >>> 24) & 0xFF]! << 24) | (SBOX[(t >>> 16) & 0xFF]! << 16) | (SBOX[(t >>> 8) & 0xFF]! << 8) | SBOX[t & 0xFF]!) >>> 0;
+			t = (t ^ (RCON[i / NK - 1]! << 24)) >>> 0;
+		}
+		else if (i % NK === 4) {
+			// AES-256 特有：半轮 SubWord
+			t = ((SBOX[(t >>> 24) & 0xFF]! << 24) | (SBOX[(t >>> 16) & 0xFF]! << 16) | (SBOX[(t >>> 8) & 0xFF]! << 8) | SBOX[t & 0xFF]!) >>> 0;
+		}
+		w[i] = (w[i - NK]! ^ t) >>> 0;
+	}
+	return w;
+}
+
+/** 状态按列优先：state[r + 4c] */
+function addRoundKey(state: Uint8Array, w: Uint32Array, round: number): void {
+	for (let c = 0; c < 4; c++) {
+		const word = w[round * 4 + c]!;
+		state[4 * c]! ^= (word >>> 24) & 0xFF;
+		state[4 * c + 1]! ^= (word >>> 16) & 0xFF;
+		state[4 * c + 2]! ^= (word >>> 8) & 0xFF;
+		state[4 * c + 3]! ^= word & 0xFF;
+	}
+}
+
+/** InvShiftRows：第 r 行循环右移 r 位 */
+function invShiftRows(s: Uint8Array): void {
+	const t = s.slice();
+	for (let r = 1; r < 4; r++) {
+		for (let c = 0; c < 4; c++)
+			s[r + 4 * c] = t[r + 4 * ((c - r + 4) % 4)]!;
+	}
+}
+
+function invSubBytes(s: Uint8Array): void {
+	for (let i = 0; i < BLOCK; i++)
+		s[i] = INV_SBOX[s[i]!]!;
+}
+
+/** InvMixColumns：列乘 [0e 0b 0d 09] 循环矩阵 */
+function invMixColumns(s: Uint8Array): void {
+	for (let c = 0; c < 4; c++) {
+		const [a0, a1, a2, a3] = [s[4 * c]!, s[4 * c + 1]!, s[4 * c + 2]!, s[4 * c + 3]!];
+		s[4 * c] = gmul(a0, 0x0E) ^ gmul(a1, 0x0B) ^ gmul(a2, 0x0D) ^ gmul(a3, 0x09);
+		s[4 * c + 1] = gmul(a0, 0x09) ^ gmul(a1, 0x0E) ^ gmul(a2, 0x0B) ^ gmul(a3, 0x0D);
+		s[4 * c + 2] = gmul(a0, 0x0D) ^ gmul(a1, 0x09) ^ gmul(a2, 0x0E) ^ gmul(a3, 0x0B);
+		s[4 * c + 3] = gmul(a0, 0x0B) ^ gmul(a1, 0x0D) ^ gmul(a2, 0x09) ^ gmul(a3, 0x0E);
+	}
+}
+
+/** 单块解密（等价逆密码） */
+function decryptBlock(input: Uint8Array, w: Uint32Array, out: Uint8Array): void {
+	const s = input.slice();
+	addRoundKey(s, w, NR);
+	for (let round = NR - 1; round >= 1; round--) {
+		invShiftRows(s);
+		invSubBytes(s);
+		addRoundKey(s, w, round);
+		invMixColumns(s);
+	}
+	invShiftRows(s);
+	invSubBytes(s);
+	addRoundKey(s, w, 0);
+	out.set(s);
+}
+
+/** AES-256-CBC 解密（不做填充剥离） */
+export function aes256CbcDecrypt(cipher: Uint8Array, key: Uint8Array, iv: Uint8Array): Uint8Array {
+	if (iv.length !== BLOCK)
+		throw new Error(`aes: iv must be 16 bytes, got ${iv.length}`);
+	if (cipher.length === 0 || cipher.length % BLOCK !== 0)
+		throw new Error(`aes: ciphertext length must be a positive multiple of 16, got ${cipher.length}`);
+	const w = expandKey(key);
+	const out = new Uint8Array(cipher.length);
+	const block = new Uint8Array(BLOCK);
+	let prev = iv.slice();
+	for (let off = 0; off < cipher.length; off += BLOCK) {
+		decryptBlock(cipher.subarray(off, off + BLOCK), w, block);
+		for (let i = 0; i < BLOCK; i++) {
+			out[off + i] = block[i]! ^ prev[i]!;
+		}
+		prev = cipher.subarray(off, off + BLOCK).slice();
+	}
+	return out;
+}
+
+/** PKCS#7 去填充（1..16 字节，逐字节校验；非法抛错） */
+export function pkcs7Unpad(data: Uint8Array): Uint8Array {
+	if (data.length === 0 || data.length % BLOCK !== 0)
+		throw new Error("pkcs7: bad length");
+	const pad = data[data.length - 1]!;
+	if (pad < 1 || pad > BLOCK || pad > data.length)
+		throw new Error("pkcs7: bad padding");
+	for (let i = data.length - pad; i < data.length; i++) {
+		if (data[i] !== pad)
+			throw new Error("pkcs7: bad padding");
+	}
+	return data.subarray(0, data.length - pad);
+}
+
+/** SHA-1（FIPS 180-4），返回 20 字节 */
+export function sha1(data: Uint8Array): Uint8Array {
+	const len = data.length;
+	const withPad = new Uint8Array((((len + 8) >> 6) + 1) * 64);
+	withPad.set(data);
+	withPad[len] = 0x80;
+	const bits = len * 8;
+	// 长度域 64bit big-endian：低 32 位足够（>512MB 的输入本就不该进 isolate）
+	const dv = new DataView(withPad.buffer);
+	dv.setUint32(withPad.length - 8, Math.floor(bits / 0x100000000));
+	dv.setUint32(withPad.length - 4, bits >>> 0);
+
+	let h0 = 0x67452301;
+	let h1 = 0xEFCDAB89;
+	let h2 = 0x98BADCFE;
+	let h3 = 0x10325476;
+	let h4 = 0xC3D2E1F0;
+	const w = new Uint32Array(80);
+
+	for (let off = 0; off < withPad.length; off += 64) {
+		for (let i = 0; i < 16; i++)
+			w[i] = dv.getUint32(off + i * 4);
+		for (let i = 16; i < 80; i++) {
+			const v = w[i - 3]! ^ w[i - 8]! ^ w[i - 14]! ^ w[i - 16]!;
+			w[i] = ((v << 1) | (v >>> 31)) >>> 0;
+		}
+		let a = h0;
+		let b = h1;
+		let c = h2;
+		let d = h3;
+		let e = h4;
+		for (let i = 0; i < 80; i++) {
+			let f: number;
+			let k: number;
+			if (i < 20) {
+				f = (b & c) | (~b & d);
+				k = 0x5A827999;
+			}
+			else if (i < 40) {
+				f = b ^ c ^ d;
+				k = 0x6ED9EBA1;
+			}
+			else if (i < 60) {
+				f = (b & c) | (b & d) | (c & d);
+				k = 0x8F1BBCDC;
+			}
+			else {
+				f = b ^ c ^ d;
+				k = 0xCA62C1D6;
+			}
+			const temp = (((a << 5) | (a >>> 27)) + f + e + k + w[i]!) >>> 0;
+			e = d;
+			d = c;
+			c = ((b << 30) | (b >>> 2)) >>> 0;
+			b = a;
+			a = temp;
+		}
+		h0 = (h0 + a) >>> 0;
+		h1 = (h1 + b) >>> 0;
+		h2 = (h2 + c) >>> 0;
+		h3 = (h3 + d) >>> 0;
+		h4 = (h4 + e) >>> 0;
+	}
+
+	const out = new Uint8Array(20);
+	const odv = new DataView(out.buffer);
+	odv.setUint32(0, h0);
+	odv.setUint32(4, h1);
+	odv.setUint32(8, h2);
+	odv.setUint32(12, h3);
+	odv.setUint32(16, h4);
+	return out;
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export function utf8Bytes(s: string): Uint8Array {
+	return encoder.encode(s);
+}
+
+export function bytesToUtf8(b: Uint8Array): string {
+	return decoder.decode(b);
+}
+
+export function bytesToHex(b: Uint8Array): string {
+	let out = "";
+	for (const x of b)
+		out += x.toString(16).padStart(2, "0");
+	return out;
+}
+
+/** 标准 base64 解码（oj v0.1.30 起有全局 atob；非法输入由 atob 抛错） */
+export function b64ToBytes(s: string): Uint8Array {
+	const bin = atob(s.replace(/\s+/g, ""));
+	const out = new Uint8Array(bin.length);
+	for (let i = 0; i < bin.length; i++)
+		out[i] = bin.charCodeAt(i);
+	return out;
+}
+
+export function bytesToB64(b: Uint8Array): string {
+	let bin = "";
+	for (const x of b)
+		bin += String.fromCharCode(x);
+	return btoa(bin);
+}
+
+export function sha1Hex(data: string | Uint8Array): string {
+	return bytesToHex(sha1(typeof data === "string" ? utf8Bytes(data) : data));
+}
+
+/**
+ * 企微签名（明文 `signature` 与密文 `msg_signature` 同算法）：
+ * 参数按字典序排序后拼接、sha1 取十六进制。
+ */
+export function wecomSignature(...parts: string[]): string {
+	return sha1Hex(parts.slice().sort().join(""));
+}
+
+/**
+ * 解出企微消息明文（`<xml>…</xml>` 或裸 `echostr`）。
+ *
+ * 明文结构（企微 §消息加解密）：`random(16B) | msg_len(4B, big-endian) | msg | receiveid`。
+ * `receiveid` 对第三方平台/代开发模版是 **suite_id**；不一致即拒（错钥/错套件混用必须 fail-closed，
+ * 否则不同套件的回调会互相污染）。43 字符 EncodingAESKey 末尾补 "=" 才是 44 字符 base64（32 字节）。
+ */
+export function unwrapWecomMessage(encryptedB64: string, encodingAesKey: string, expectedReceiver: string): string {
+	const key = b64ToBytes(`${encodingAesKey}=`);
+	if (key.length !== 32)
+		throw new Error(`wecom: EncodingAESKey must decode to 32 bytes, got ${key.length}`);
+	const plain = pkcs7Unpad(aes256CbcDecrypt(b64ToBytes(encryptedB64), key, key.subarray(0, BLOCK)));
+	if (plain.length < 20)
+		throw new Error("wecom: plaintext too short");
+	const msgLen = new DataView(plain.buffer, plain.byteOffset, plain.byteLength).getUint32(16);
+	if (20 + msgLen > plain.length)
+		throw new Error("wecom: msg length out of range");
+	const msg = bytesToUtf8(plain.subarray(20, 20 + msgLen));
+	const receiver = bytesToUtf8(plain.subarray(20 + msgLen));
+	if (receiver !== expectedReceiver)
+		throw new Error(`wecom: receiver mismatch (got ${receiver === "" ? "<empty>" : "other"}, expected suite)`);
+	return msg;
+}

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);
+	}
+}