@oj-module/cli 0.2.43 → 0.2.46

package/templates/tests/wecom-crypt.spec.ts

@@ -0,0 +1,155 @@
+// 企微回调加解密原语（手写 SHA-1 / AES-256-CBC）——以 Node/WebCrypto 为唯一对照物：
+// 这里不验证「我的实现与我的实现一致」，而是逐字节比对标准实装，避免自洽的错。
+// 加密侧走 `crypto.webcrypto.subtle`（AES-CBC 自带 PKCS#7，与企微协议同语义）；
+// 不用 `createCipheriv`：本机 Node 22.21 的它对着整块明文 `final()` 仍吐一块（实测 48B→64B），
+// 会把「多一块」的差异误记到解密实现账上。
+import { Buffer } from "node:buffer";
+import { webcrypto } from "node:crypto";
+import { createRequire } from "node:module";
+
+import { describe, expect, it } from "vitest";
+import {
+	aes256CbcDecrypt,
+	b64ToBytes,
+	bytesToB64,
+	pkcs7Unpad,
+	sha1Hex,
+	unwrapWecomMessage,
+	utf8Bytes,
+	wecomSignature,
+} from "../src/auth/api/_shared/wecom/crypt";
+
+const req = createRequire(import.meta.url);
+const nodeCrypto = req("node:crypto") as typeof import("node:crypto");
+
+const AES_KEY = webcrypto.getRandomValues(new Uint8Array(32));
+const IV = webcrypto.getRandomValues(new Uint8Array(16));
+
+/** 标准 AES-256-CBC 加密（WebCrypto 自动加 PKCS#7，与企微一致） */
+async function encryptCbc(plain: Uint8Array, key: Uint8Array = AES_KEY, iv: Uint8Array = IV): Promise<Uint8Array> {
+	const k = await webcrypto.subtle.importKey("raw", key, { name: "AES-CBC" }, false, ["encrypt"]);
+	return new Uint8Array(await webcrypto.subtle.encrypt({ name: "AES-CBC", iv }, k, plain));
+}
+
+describe("sha1Hex 对 OpenSSL", () => {
+	it("空串与 ASCII", () => {
+		expect(sha1Hex("")).toBe(nodeCrypto.createHash("sha1").update("").digest("hex"));
+		expect(sha1Hex("abc")).toBe("a9993e364706816aba3e25717850c26c9cd0d89d");
+		expect(sha1Hex("The quick brown fox jumps over the lazy dog")).toBe("2fd4e1c67a2d28fced849ee1bb76e7391b93eb12");
+	});
+
+	it("uTF-8 多字节（走 TextEncoder 分流）", () => {
+		const s = "企业微信 wecom 中文 🙂";
+		expect(sha1Hex(s)).toBe(nodeCrypto.createHash("sha1").update(s, "utf8").digest("hex"));
+	});
+
+	it("块边界与跨块长度（1/55/56/63/64/65/119/120/200 字节）", () => {
+		for (const n of [1, 55, 56, 63, 64, 65, 119, 120, 200]) {
+			const buf = nodeCrypto.randomBytes(n);
+			expect(sha1Hex(new Uint8Array(buf))).toBe(nodeCrypto.createHash("sha1").update(buf).digest("hex"));
+		}
+	});
+});
+
+describe("aes256CbcDecrypt 对 WebCrypto", () => {
+	it("多种明文长度逐一比对（含整块时补整块填充的边界）", async () => {
+		for (const n of [0, 1, 15, 16, 17, 32, 38, 100, 255]) {
+			const plain = webcrypto.getRandomValues(new Uint8Array(n));
+			const cipher = await encryptCbc(plain);
+			const got = aes256CbcDecrypt(cipher, AES_KEY, IV);
+			expect(got.length).toBe(cipher.length);
+			expect(Buffer.from(pkcs7Unpad(got)).equals(Buffer.from(plain))).toBe(true);
+		}
+	});
+
+	it("密钥/IV 错则明文不同（防实现自洽：不同钥必须解出不同结果）", async () => {
+		const plain = webcrypto.getRandomValues(new Uint8Array(32));
+		const cipher = await encryptCbc(plain);
+		const wrongKey = webcrypto.getRandomValues(new Uint8Array(32));
+		const wrongIv = webcrypto.getRandomValues(new Uint8Array(16));
+		expect(Buffer.from(aes256CbcDecrypt(cipher, wrongKey, IV)).equals(Buffer.from(plain))).toBe(false);
+		expect(Buffer.from(aes256CbcDecrypt(cipher, AES_KEY, wrongIv)).equals(Buffer.from(plain))).toBe(false);
+	});
+
+	it("非法输入硬失败：长度非 16 倍数、空串、IV 长度错、密钥长度错", () => {
+		expect(() => aes256CbcDecrypt(new Uint8Array(15), AES_KEY, IV)).toThrow(/multiple of 16/);
+		expect(() => aes256CbcDecrypt(new Uint8Array(0), AES_KEY, IV)).toThrow(/multiple of 16/);
+		expect(() => aes256CbcDecrypt(new Uint8Array(16), AES_KEY, new Uint8Array(15))).toThrow(/iv must be 16/);
+		expect(() => aes256CbcDecrypt(new Uint8Array(16), new Uint8Array(16), IV)).toThrow(/key must be 32/);
+	});
+
+	it("pKCS#7 非法填充硬失败（不返回半截明文）", () => {
+		expect(() => pkcs7Unpad(new Uint8Array(16))).toThrow(/bad padding/); // 全 0 填充
+		const tooBig = new Uint8Array(16).fill(0);
+		tooBig[15] = 17;
+		expect(() => pkcs7Unpad(tooBig)).toThrow(/bad padding/);
+		const inconsistent = new Uint8Array(16).fill(0);
+		inconsistent[14] = 3;
+		inconsistent[15] = 3;
+		expect(() => pkcs7Unpad(inconsistent)).toThrow(/bad padding/);
+	});
+});
+
+describe("wecomSignature：字典序排序后 sha1", () => {
+	it("与手算 OpenSSL 一致（乱序入参同结果）", () => {
+		const token = "QDG6eK";
+		const ts = "1409659813";
+		const nonce = "1372623149";
+		const enc = "RypEvHKD8QQKFhvQ6QleEB4J58tiPdvo+rtK1I9qca6aM/wvqnLSV5zE";
+		const sig = wecomSignature(token, ts, nonce, enc);
+		const manual = nodeCrypto.createHash("sha1")
+			.update([token, ts, nonce, enc].sort().join(""), "utf8")
+			.digest("hex");
+		expect(sig).toBe(manual);
+		expect(wecomSignature(enc, nonce, ts, token)).toBe(sig);
+		expect(wecomSignature(token, ts, nonce)).not.toBe(sig); // 少一项必须不同
+	});
+});
+
+describe("unwrapWecomMessage：random(16) | len(4) | msg | receiveid 结构", () => {
+	const key = webcrypto.getRandomValues(new Uint8Array(32));
+	const encodingAesKey = Buffer.from(key).toString("base64").slice(0, 43);
+
+	/** 按企微明文结构造包并加密（与解密侧严格互逆） */
+	async function buildEnvelope(msg: string, receiver: string): Promise<string> {
+		const msgBytes = utf8Bytes(msg);
+		const recv = utf8Bytes(receiver);
+		const body = new Uint8Array(20 + msgBytes.length + recv.length);
+		body.set(webcrypto.getRandomValues(new Uint8Array(16)), 0);
+		new DataView(body.buffer).setUint32(16, msgBytes.length);
+		body.set(msgBytes, 20);
+		body.set(recv, 20 + msgBytes.length);
+		return bytesToB64(await encryptCbc(body, key, key.subarray(0, 16)));
+	}
+
+	it("解出 <xml> 明文，receiver 命中 suite_id", async () => {
+		const xml = "<xml><SuiteId>ww123</SuiteId><InfoType>suite_ticket</InfoType><SuiteTicket>abc</SuiteTicket></xml>";
+		expect(unwrapWecomMessage(await buildEnvelope(xml, "ww123"), encodingAesKey, "ww123")).toBe(xml);
+	});
+
+	it("空 msg 也能解出空串（不把长度 0 当错）", async () => {
+		expect(unwrapWecomMessage(await buildEnvelope("", "ww123"), encodingAesKey, "ww123")).toBe("");
+	});
+
+	it("uTF-8 明文（中文企业名）不被截坏——长度按字节而非字符", async () => {
+		const xml = "<xml><CorpName>示例科技（上海）有限公司</CorpName></xml>";
+		expect(unwrapWecomMessage(await buildEnvelope(xml, "ww123"), encodingAesKey, "ww123")).toBe(xml);
+	});
+
+	it("receiver 不匹配必须拒（错套件/错钥混用 fail-closed）", async () => {
+		const enc = await buildEnvelope("<xml/>", "ww-other");
+		expect(() => unwrapWecomMessage(enc, encodingAesKey, "ww123")).toThrow(/receiver mismatch/);
+	});
+
+	it("encodingAESKey 非法（长度/字符）必须硬失败", async () => {
+		const enc = await buildEnvelope("x", "ww123");
+		expect(() => unwrapWecomMessage(enc, `${encodingAesKey.slice(0, 40)}=`, "ww123")).toThrow();
+		expect(() => unwrapWecomMessage(enc, "@".repeat(43), "ww123")).toThrow();
+	});
+
+	it("密文损坏 → 填充校验硬失败（不返回半截明文）", async () => {
+		const bytes = b64ToBytes(await buildEnvelope("hello", "ww123"));
+		bytes[bytes.length - 1] ^= 0xFF;
+		expect(() => unwrapWecomMessage(bytesToB64(bytes), encodingAesKey, "ww123")).toThrow();
+	});
+});

package/templates/tests/wecom-endpoints.spec.ts

@@ -0,0 +1,468 @@
+// BDD：企微代开发四个端点的**接线**（不是领域逻辑——那在 wecom-connector.spec.ts）。
+//
+// 这里钉的是最容易写错、且错得很安静的三件事：
+//   1. 302 端点不能落进 respond（它末尾 json.ok 会把 302 覆盖成 200 信封）；
+//   2. 企微事件端点必须回**纯文本** success / echostr（JSON 信封 = 企微判失败 → 重推三次）；
+//   3. 回调链的租户来自服务端推导（state→profile → db.asTenant），且票据只能兑换一次。
+//
+// json / vars / kv / fetch / crypto 全部桩掉（oj 运行时全局同名同面）；密文用 WebCrypto 现造，
+// 与 wecom-crypt.spec.ts 同一对照物，不拿自实现给自己背书。
+/* eslint-disable test/prefer-lowercase-title -- AC 编号是验收锚点，保留大写 */
+import { webcrypto } from "node:crypto";
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { bytesToB64, utf8Bytes, wecomSignature } from "../src/auth/api/_shared/wecom/crypt";
+import { installDb } from "./fixture";
+
+const g = globalThis as any;
+let dbo: ReturnType<typeof installDb>;
+
+const SUITE = "suite_1";
+const TOKEN = "cb_token";
+const AES_KEY = webcrypto.getRandomValues(new Uint8Array(32));
+const AES_KEY_B64 = bytesToB64(AES_KEY);
+
+interface Captured { status: number | null, body: any, location: string | null, text: string | null, contentType: string | null }
+
+let out: Captured;
+
+function installJson(): void {
+	out = { status: null, body: null, location: null, text: null, contentType: null };
+	const redirect = (url: string, code = 302) => {
+		out.status = code;
+		out.location = url;
+	};
+	g.json = {
+		ok: (data?: unknown) => {
+			out.status = 200;
+			out.body = data;
+		},
+		fail: (code: number, msg: string, data?: unknown) => {
+			out.status = code;
+			out.body = data === undefined ? { code, msg } : { code, msg, data };
+		},
+		header: () => {},
+		raw: (data: unknown) => {
+			out.status = 200;
+			out.body = data;
+		},
+		redirect: Object.assign(redirect, {
+			found: (url: string) => redirect(url, 302),
+			seeOther: (url: string) => redirect(url, 303),
+		}),
+		stream: (opts?: { contentType?: string }) => {
+			out.status = 200;
+			out.contentType = opts?.contentType ?? null;
+			return {
+				write: (chunk: string) => {
+					out.text = (out.text ?? "") + chunk;
+				},
+				end: () => {},
+			};
+		},
+	};
+}
+
+function installVars(overrides: Record<string, string> = {}): void {
+	const base: Record<string, string> = {
+		wecom_suite_id: SUITE,
+		wecom_suite_secret: "suite_secret",
+		wecom_callback_token: TOKEN,
+		wecom_encoding_aes_key: AES_KEY_B64.replace(/=$/, ""),
+		// 32 字符 hex = 16 字节，是 oj aesGcmEncrypt 接受的两种尺寸之一
+		wecom_enc_key: "0123456789abcdef0123456789abcdef",
+		wecom_base_url: "https://site.example.com/api/auth/wecom",
+		...overrides,
+	};
+	g.vars = { get: (name: string) => base[name] ?? null };
+}
+
+function installKv(): Map<string, string> {
+	const store = new Map<string, string>();
+	// 计数也是真的（有理）：重放防护靠 incr 的原子返回值判断「谁是第一个」，
+	// 恒返回 1 的桩会把这条防线伪装成通过。
+	const counters = new Map<string, number>();
+	g.kv = {
+		get: async (k: string) => store.get(k) ?? null,
+		set: async (k: string, v: string) => {
+			store.set(k, v);
+		},
+		del: async (k: string) => {
+			store.delete(k);
+			counters.delete(k);
+		},
+		expire: async () => 1,
+		incr: async (k: string) => {
+			const n = (counters.get(k) ?? 0) + 1;
+			counters.set(k, n);
+			return n;
+		},
+	};
+	return store;
+}
+
+function installCrypto(): void {
+	const c = {
+		randomHex: (n = 32) => (n === 16 ? "state_nonce_0001" : `ticket_${"a".repeat(n * 2)}`),
+		sha256Hex: (s: string) => `sha(${s})`,
+		aesGcmEncrypt: (plain: string) => `gcm(${plain})`,
+		aesGcmDecrypt: (blob: string) => blob.replace(/^gcm\((.*)\)$/, "$1"),
+	};
+	Object.defineProperty(globalThis, "crypto", { value: c, configurable: true });
+}
+
+/** 企微侧 webhook 的密文包（random|len|msg|receiveid → AES-256-CBC/PKCS#7） */
+async function seal(plain: string, receiveId = SUITE): Promise<string> {
+	const msg = utf8Bytes(plain);
+	const head = webcrypto.getRandomValues(new Uint8Array(16));
+	const len = new Uint8Array(4);
+	new DataView(len.buffer).setUint32(0, msg.length);
+	const recv = utf8Bytes(receiveId);
+	const buf = new Uint8Array(20 + msg.length + recv.length);
+	buf.set(head, 0);
+	buf.set(len, 16);
+	buf.set(msg, 20);
+	buf.set(recv, 20 + msg.length);
+	const key = await webcrypto.subtle.importKey("raw", AES_KEY, { name: "AES-CBC" }, false, ["encrypt"]);
+	const cipher = new Uint8Array(await webcrypto.subtle.encrypt({ name: "AES-CBC", iv: AES_KEY.subarray(0, 16) }, key, buf));
+	return bytesToB64(cipher);
+}
+
+function request(opts: { query?: Record<string, string>, body?: unknown, headers?: Record<string, string>, tenantId?: string } = {}): void {
+	g.http = {
+		method: "GET",
+		query: opts.query ?? {},
+		body: opts.body ?? null,
+		headers: opts.headers ?? {},
+		...(opts.tenantId ? { tenantId: opts.tenantId } : {}),
+	};
+}
+
+/** 预置一家已授权的企业（相当于 create_auth 已跑过） */
+function seedCorp(corpId = "ww_corp_a", agentId = "100001"): void {
+	dbo.prepare("INSERT INTO wecom_app_profile (suite_id, corp_id, agent_id, auth_corp_id, env, corp_name, status, permanent_code_enc, installed_at, update_time) VALUES (?, ?, ?, ?, 'prod', '测试企业', 'active', ?, 0, 0)")
+		.run(SUITE, corpId, agentId, corpId, `gcm(perm_${corpId})`);
+}
+
+const api = async () => (await import("../src/auth/api/wecom/api")).default;
+
+beforeAll(() => {
+	dbo = installDb();
+	g.db.asTenant = (id: string) => {
+		if (g.http?.tenantId)
+			throw new Error("tenant already set");
+		g.http = { ...(g.http ?? {}), tenantId: id };
+	};
+	g.log = { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} };
+	g.jwt = { sign: (p: { sub: string }) => `jwt(${p.sub})`, accessDuration: 7200, refreshDuration: 2_592_000 };
+	g.bcrypt = { hash: async (s: string) => `hashed:${s}`, verify: async () => false };
+});
+
+beforeEach(() => {
+	installJson();
+	installVars();
+	installKv();
+	installCrypto();
+	g.fetch = async () => ({ ok: true, json: async () => ({}) });
+	for (const t of ["wecom_app_profile", "wecom_suite_ticket", "wecom_login_ticket", "sys_refresh_token", "sys_login_throttle", "sys_rate_window", "sys_oplog"])
+		dbo.exec(`DELETE FROM ${t}`);
+	// JIT 建号是跨用例污染源：每个用例都从「本企业还没建过号」起步
+	dbo.exec("DELETE FROM users WHERE source = 'wecom'");
+});
+
+afterEach(() => {
+	g.http = {};
+});
+
+describe("P1-I：GET /auth/wecom/login（发起授权）", () => {
+	it("部署常量缺失 → 400 信封并点出缺哪几个 vars（不是 500）", async () => {
+		installVars({ wecom_suite_id: "", wecom_enc_key: "" });
+		request({ query: { corp: "ww_corp_a" } });
+		await (await api()).login.get();
+		expect(out.status).toBe(400);
+		expect(out.body.msg).toMatch(/wecom_suite_id/);
+		expect(out.location).toBeNull();
+	});
+
+	it("缺企业代码 → 400，引导去登录页填（不猜默认企业）", async () => {
+		request({ query: {} });
+		await (await api()).login.get();
+		expect(out.status).toBe(400);
+		expect(out.body.msg).toMatch(/企业代码/);
+	});
+
+	it("未授权企业 → 400（文案不区分「没装」与「已停用」）", async () => {
+		request({ query: { corp: "ww_unknown" } });
+		await (await api()).login.get();
+		expect(out.status).toBe(400);
+		expect(out.body.msg).toMatch(/无效或应用未开通/);
+	});
+
+	it("企微客户端内 → 302 到 oauth2 静默授权，redirect_uri 指向 <base>/callback", async () => {
+		seedCorp();
+		request({ query: { corp: "ww_corp_a" }, headers: { "user-agent": "Mozilla/5.0 wxwork/4.1.0" } });
+		await (await api()).login.get();
+		expect(out.status).toBe(302);
+		expect(out.location).toContain("connect/oauth2/authorize");
+		expect(out.location).toContain("agentid=100001");
+		expect(out.location).toContain(encodeURIComponent("https://site.example.com/api/auth/wecom/callback"));
+	});
+
+	it("普通浏览器 → 302 到 qrConnect 扫码（appid = corpid）", async () => {
+		seedCorp();
+		request({ query: { corp: "ww_corp_a" }, headers: { "user-agent": "Mozilla/5.0 Chrome/120" } });
+		await (await api()).login.get();
+		expect(out.status).toBe(302);
+		expect(out.location).toContain("wwopen/sso/qrConnect");
+		expect(out.location).toContain("appid=ww_corp_a");
+	});
+
+	it("同一企业两个应用：未指定 agent → 400 提示带 agent 参数", async () => {
+		seedCorp("ww_corp_a", "100001");
+		seedCorp("ww_corp_a", "100002");
+		request({ query: { corp: "ww_corp_a" }, headers: { "user-agent": "wxwork" } });
+		await (await api()).login.get();
+		expect(out.status).toBe(400);
+		expect(out.body.msg).toMatch(/agent/);
+	});
+});
+
+describe("P1-J：GET /auth/wecom/callback（回跳换人 + 发票）", () => {
+	async function startLogin(corp = "ww_corp_a"): Promise<string> {
+		seedCorp(corp);
+		request({ query: { corp }, headers: { "user-agent": "wxwork" } });
+		await (await api()).login.get();
+		const state = new URL(out.location!).searchParams.get("state")!;
+		return state;
+	}
+
+	function stubUpstream(userid: string | null = "zhangsan", memberName: string | null = "张三"): void {
+		g.fetch = async (url: string) => ({
+			ok: true,
+			json: async () => {
+				if (url.includes("/cgi-bin/gettoken"))
+					return { access_token: "corp_tk", expires_in: 7200 };
+				if (url.includes("/cgi-bin/auth/getuserinfo"))
+					return userid ? { errcode: 0, userid } : { errcode: 0, openid: "o_ext" };
+				// 通讯录读权限：没有就是 60011，补名必须降级而不是失败
+				if (url.includes("/cgi-bin/user/get"))
+					return memberName ? { errcode: 0, name: memberName } : { errcode: 60011, errmsg: "no privilege" };
+				throw new Error(`stub fetch 未预期：${url}`);
+			},
+		});
+	}
+
+	it("缺 code（用户取消授权）→ 400，不建号不发票", async () => {
+		const state = await startLogin();
+		request({ query: { state } });
+		await (await api()).callback.get();
+		expect(out.status).toBe(400);
+		expect(out.body.msg).toMatch(/code/);
+		expect(dbo.prepare("SELECT COUNT(*) AS n FROM wecom_login_ticket").get()).toMatchObject({ n: 0 });
+	});
+
+	it("正常回跳 → 302 到 SPA 并只带**一次性票据**与租户；JIT 建号落 corp_id", async () => {
+		const state = await startLogin();
+		stubUpstream();
+		request({ query: { code: "CODE_1", state } });
+		await (await api()).callback.get();
+
+		expect(out.status).toBe(302);
+		const loc = new URL(out.location!);
+		expect(loc.origin).toBe("https://site.example.com");
+		expect(loc.pathname).toBe("/login");
+		expect(loc.searchParams.get("tenant")).toBe("ww_corp_a");
+		// URL 里只能是票据，不能出现 token
+		expect(loc.search).not.toMatch(/access_token|refresh_token/);
+		expect(loc.searchParams.get("wecom_ticket")).toBeTruthy();
+
+		const row = dbo.prepare("SELECT username, source, corp_id, display_name FROM users WHERE source = 'wecom'").get();
+		expect(row).toMatchObject({ username: "wecom:zhangsan", corp_id: "ww_corp_a", display_name: "张三" });
+		expect(dbo.prepare("SELECT COUNT(*) AS n FROM wecom_login_ticket").get()).toMatchObject({ n: 1 });
+	});
+
+	it("取不到真实姓名（套件无通讯录权限）→ 用工号兜底建档，登录照常成功", async () => {
+		const state = await startLogin();
+		stubUpstream("zhangsan", null);
+		request({ query: { code: "CODE_1", state } });
+		await (await api()).callback.get();
+
+		expect(out.status).toBe(302);
+		expect(dbo.prepare("SELECT display_name FROM users WHERE username = 'wecom:zhangsan'").get()).toMatchObject({ display_name: "zhangsan" });
+	});
+
+	it("state 一次性：同一 state 重放 → 400（不重复发票）", async () => {
+		const state = await startLogin();
+		stubUpstream();
+		request({ query: { code: "CODE_1", state } });
+		await (await api()).callback.get();
+		expect(out.status).toBe(302);
+
+		installJson();
+		request({ query: { code: "CODE_1", state } });
+		await (await api()).callback.get();
+		expect(out.status).toBe(400);
+	});
+
+	it("非本企业成员（企微只回 openid）→ 401，且不留半截账号", async () => {
+		const state = await startLogin();
+		stubUpstream(null);
+		request({ query: { code: "CODE_1", state } });
+		await (await api()).callback.get();
+		expect(out.status).toBe(401);
+		expect(dbo.prepare("SELECT COUNT(*) AS n FROM users WHERE source = 'wecom'").get()).toMatchObject({ n: 0 });
+	});
+});
+
+describe("P1-K：POST /auth/wecom/ticket（票据换会话）", () => {
+	async function issueTicket(): Promise<string> {
+		const state = "st_1";
+		installKv();
+		await g.kv.set(`wecom:state:${state}`, JSON.stringify({ corpId: "ww_corp_a", agentId: "100001", env: "prod" }));
+		seedCorp();
+		g.fetch = async (url: string) => ({
+			ok: true,
+			json: async () => (url.includes("gettoken") ? { access_token: "t", expires_in: 7200 } : { errcode: 0, userid: "zhangsan" }),
+		});
+		request({ query: { code: "CODE_1", state } });
+		await (await api()).callback.get();
+		return new URL(out.location!).searchParams.get("wecom_ticket")!;
+	}
+
+	it("换出 TokenBundle（access + refresh + user），票据随即作废", async () => {
+		const ticket = await issueTicket();
+		installJson();
+		request({ body: { ticket }, tenantId: "ww_corp_a" });
+		await (await api()).ticket.post();
+
+		expect(out.status).toBe(200);
+		expect(out.body.access_token).toMatch(/^jwt\(/);
+		expect(out.body.refresh_token).toMatch(/^ticket_/);
+		expect(out.body.user.username).toBe("wecom:zhangsan");
+		expect(dbo.prepare("SELECT COUNT(*) AS n FROM sys_refresh_token").get()).toMatchObject({ n: 1 });
+
+		installJson();
+		request({ body: { ticket }, tenantId: "ww_corp_a" });
+		await (await api()).ticket.post();
+		expect(out.status).toBe(401);
+	});
+
+	it("租户头与票据不一致 → 403（前端忘了带 ?tenant= 必须当场炸，不能悄悄落默认租户）", async () => {
+		const ticket = await issueTicket();
+		installJson();
+		request({ body: { ticket }, tenantId: "default" });
+		await (await api()).ticket.post();
+		expect(out.status).toBe(403);
+		expect(dbo.prepare("SELECT COUNT(*) AS n FROM sys_refresh_token").get()).toMatchObject({ n: 0 });
+	});
+
+	it("缺 ticket → 400", async () => {
+		request({ body: {} });
+		await (await api()).ticket.post();
+		expect(out.status).toBe(400);
+	});
+});
+
+describe("P1-L：GET/POST /auth/wecom/event（企微指令回调）", () => {
+	// 必须是「当下」：服务端按 ±5 分钟窗口挡重放，写死历史时间戳等于主动把自己判成重放
+	const nowSecs = () => Math.floor(Date.now() / 1000);
+	const TS = String(nowSecs());
+	const NONCE = "n0nce";
+	const TICKET_XML = "<xml><InfoType>suite_ticket</InfoType><SuiteId>suite_1</SuiteId><SuiteTicket>tk_9</SuiteTicket></xml>";
+
+	function signedQuery(encrypted: string, overrides: Partial<Record<string, string>> = {}): Record<string, string> {
+		const query = { timestamp: TS, nonce: NONCE, ...overrides } as Record<string, string>;
+		return { ...query, msg_signature: wecomSignature(TOKEN, query.timestamp, query.nonce, encrypted) };
+	}
+
+	it("URL 验证：验签通过 → 以 text/plain 原样回解出的 echostr（不套信封）", async () => {
+		const echo = await seal("echo_12345");
+		request({ query: { ...signedQuery(echo), echostr: echo } });
+		await (await api()).event.get();
+		expect(out.status).toBe(200);
+		expect(out.contentType).toContain("text/plain");
+		expect(out.text).toBe("echo_12345");
+		expect(out.body).toBeNull();
+	});
+
+	it("URL 验证（鸡生蛋解法）：suite_id 尚未下发时也能通过——receiveid 放宽，签名仍是唯一闸门", async () => {
+		// 引导期：模版还没建、suite_id 为空，但 Tier A 凭据（token/aeskey）已配齐，服务应能响应验证。
+		installVars({ wecom_suite_id: "" });
+		const echo = await seal("echo_bootstrap");
+		request({ query: { ...signedQuery(echo), echostr: echo } });
+		await (await api()).event.get();
+		expect(out.status).toBe(200);
+		expect(out.contentType).toContain("text/plain");
+		expect(out.text).toBe("echo_bootstrap");
+	});
+
+	it("签名不符 → 400（不给探测者任何比对材料）", async () => {
+		const echo = await seal("echo_12345");
+		request({ query: { timestamp: TS, nonce: NONCE, msg_signature: "bad", echostr: echo } });
+		await (await api()).event.get();
+		expect(out.status).toBe(400);
+		expect(out.body.msg).toMatch(/签名/);
+	});
+
+	it("指令回调：验签+解密 → 落 suite_ticket → 回纯文本 success", async () => {
+		const plain = "<xml><InfoType>suite_ticket</InfoType><SuiteId>suite_1</SuiteId><SuiteTicket>tk_9</SuiteTicket></xml>";
+		const encrypted = await seal(plain);
+		request({ query: signedQuery(encrypted), body: `<xml><Encrypt><![CDATA[${encrypted}]]></Encrypt></xml>` });
+		await (await api()).event.post();
+		expect(out.status).toBe(200);
+		expect(out.text).toBe("success");
+		expect(dbo.prepare("SELECT suite_ticket FROM wecom_suite_ticket WHERE suite_id = ?").get(SUITE)).toMatchObject({ suite_ticket: "tk_9" });
+	});
+
+	it("报文缺 Encrypt → 400", async () => {
+		request({ query: signedQuery("x"), body: "<xml></xml>" });
+		await (await api()).event.post();
+		expect(out.status).toBe(400);
+	});
+
+	it("密文属于别的套件（receiveid 不符）→ 400，不落任何状态", async () => {
+		const encrypted = await seal("<xml><InfoType>suite_ticket</InfoType><SuiteTicket>tk_x</SuiteTicket></xml>", "other_suite");
+		request({ query: signedQuery(encrypted), body: `<xml><Encrypt>${encrypted}</Encrypt></xml>` });
+		await (await api()).event.post();
+		expect(out.status).toBe(400);
+		expect(dbo.prepare("SELECT COUNT(*) AS n FROM wecom_suite_ticket").get()).toMatchObject({ n: 0 });
+	});
+
+	it("timestamp 超出 ±5 分钟窗口 → 400（历史回调不得被无限期重放）", async () => {
+		const encrypted = await seal(TICKET_XML);
+		const stale = String(nowSecs() - 8 * 60);
+		request({ query: signedQuery(encrypted, { timestamp: stale }), body: `<xml><Encrypt>${encrypted}</Encrypt></xml>` });
+		await (await api()).event.post();
+		expect(out.status).toBe(400);
+		expect(out.body.msg).toMatch(/超出允许窗口/);
+		expect(dbo.prepare("SELECT COUNT(*) AS n FROM wecom_suite_ticket").get()).toMatchObject({ n: 0 });
+	});
+
+	it("同一条回调连发两次（重放）→ 第二次 400 nonce 重复，票据只落一次", async () => {
+		const encrypted = await seal(TICKET_XML);
+		const body = `<xml><Encrypt>${encrypted}</Encrypt></xml>`;
+		request({ query: signedQuery(encrypted), body });
+		await (await api()).event.post();
+		expect(out.status).toBe(200);
+
+		installJson();
+		request({ query: signedQuery(encrypted), body });
+		await (await api()).event.post();
+		expect(out.status).toBe(400);
+		expect(out.body.msg).toMatch(/nonce 重复/);
+		expect(dbo.prepare("SELECT suite_ticket FROM wecom_suite_ticket WHERE suite_id = ?").get(SUITE)).toMatchObject({ suite_ticket: "tk_9" });
+	});
+
+	it("换一个新 nonce 的同内容回调仍能落（重放闸门没把正常重试误伤）", async () => {
+		const first = await seal(TICKET_XML);
+		request({ query: signedQuery(first), body: `<xml><Encrypt>${first}</Encrypt></xml>` });
+		await (await api()).event.post();
+		expect(out.status).toBe(200);
+
+		installJson();
+		const again = await seal(TICKET_XML.replace("tk_9", "tk_10"));
+		request({ query: signedQuery(again, { nonce: `${NONCE}_2` }), body: `<xml><Encrypt>${again}</Encrypt></xml>` });
+		await (await api()).event.post();
+		expect(out.status).toBe(200);
+		expect(dbo.prepare("SELECT suite_ticket FROM wecom_suite_ticket WHERE suite_id = ?").get(SUITE)).toMatchObject({ suite_ticket: "tk_10" });
+	});
+});

package/templates/tests/wecom-landing.spec.ts

@@ -0,0 +1,54 @@
+// BDD：企微登录落地的纯逻辑（Phase 2 前端）。
+//
+// 这三处错了都不报错、只表现为「点了没反应 / 登录过期」，故单独锁：
+//   · 落地参数解析必须区分「企微回跳」与「普通打开登录页」（后者不能触发换票）；
+//   · 参数要裁剪、要能容忍少了 tenant（此时沿用本地租户，不是登录失败）；
+//   · 授权入口即使没填企业代码也要跳（后端会回 400 说明缺什么，比前端静默不动好排查）。
+import { describe, expect, it } from "vitest";
+import { parseWecomLanding, wecomAuthorizePath } from "../src/login/web/wecom";
+
+describe("p2-A：回跳落地参数解析", () => {
+	it("带齐 ticket 与 tenant → 解析出两者", () => {
+		expect(parseWecomLanding("?wecom_ticket=tk_1&tenant=ww_corp_a")).toEqual({ ticket: "tk_1", tenant: "ww_corp_a" });
+	});
+
+	it("只有 ticket（后端没带租户）→ tenant 为空串，仍算企微落地", () => {
+		expect(parseWecomLanding("?wecom_ticket=tk_1")).toEqual({ ticket: "tk_1", tenant: "" });
+	});
+
+	it("普通打开登录页（无 ticket）→ null，绝不触发换票", () => {
+		expect(parseWecomLanding("")).toBeNull();
+		expect(parseWecomLanding("?tenant=ww_corp_a")).toBeNull();
+		expect(parseWecomLanding("?wecom_ticket=")).toBeNull();
+		expect(parseWecomLanding("?wecom_ticket=%20%20")).toBeNull();
+	});
+
+	it("参数前后空白被裁掉（复制粘贴链接常带空格）", () => {
+		expect(parseWecomLanding("?wecom_ticket=%20tk_1%20&tenant=%20ww_corp_a%20")).toEqual({ ticket: "tk_1", tenant: "ww_corp_a" });
+	});
+
+	it("不吞别的参数：redirect 原样留给 getRedirectPath（登录后回原页）", () => {
+		const search = "?wecom_ticket=tk_1&tenant=ww_corp_a&redirect=%2Fsystem%2Fusers";
+		expect(parseWecomLanding(search)).toEqual({ ticket: "tk_1", tenant: "ww_corp_a" });
+		expect(new URLSearchParams(search).get("redirect")).toBe("/system/users");
+	});
+});
+
+describe("p2-B：授权入口拼装", () => {
+	it("企业代码 → 站内路径（部署前缀由调用方 withSiteBase 拼）", () => {
+		expect(wecomAuthorizePath("ww_corp_a")).toBe("/auth/wecom/login?corp=ww_corp_a");
+	});
+
+	it("同企业两个应用（测试/正式）→ 带 agent 区分", () => {
+		expect(wecomAuthorizePath("ww_corp_a", "100002")).toBe("/auth/wecom/login?corp=ww_corp_a&agent=100002");
+	});
+
+	it("企业代码为空/空白 → 仍拼出入口（后端回 400 点明缺 corp，比按钮无反应好排查）", () => {
+		expect(wecomAuthorizePath("")).toBe("/auth/wecom/login");
+		expect(wecomAuthorizePath("  ")).toBe("/auth/wecom/login");
+	});
+
+	it("值做 URL 编码（企业代码/agent 可能含特殊字符）", () => {
+		expect(wecomAuthorizePath("ww a&b", "1 0")).toBe("/auth/wecom/login?corp=ww+a%26b&agent=1+0");
+	});
+});