@oj-module/cli 0.2.43 → 0.2.45

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

@@ -0,0 +1,243 @@
+// 企微 API 客户端（代开发三级凭证链 + 网页授权换 userid）。
+//
+// 凭证链（devkit 未覆盖，见 docs/plans/20261030-1845-wecom-daikaifa-login-plan.md §5.4）：
+//   suite_ticket(企微推) + suite_secret → suite_access_token（套件级，2h）
+//   suite_access_token + auth_code → permanent_code（= 代开发应用的 secret，属于 (suite, corp)）
+//   permanent_code + corpid  → corp access_token（**与自建应用同一个 gettoken 接口**，2h）
+//   corp access_token + code → userid（网页授权 snsapi_base，与自建应用同一个 auth/getuserinfo）
+// 代开发与第三方应用的分叉点只有两处：取永久授权码走 `/service/v2/get_permanent_code`；
+// 企业 token 走 `gettoken` 而不是 `service/get_corp_token`。
+//
+// 缓存：两段 token 都进 kv（oj 有 Redis 就跨进程，没有就进程内），TTL = expires_in-300。
+// 失效：40001/42001 视为 token 失效 → 删缓存重取一次（企微侧提前失效是常态，不重试会把登录打成 502）。
+// 错误两态红线（与 ldap-login 同）：上游网络/协议/企微错误码 → 502（可重试语义）；
+// 用户凭据层面（code 无效/不在可见范围）→ 401（不区分原因，防探测）。
+
+const API_BASE = "https://qyapi.weixin.qq.com";
+const TIMEOUT_MS = 5000;
+const TOKEN_SKEW_SECS = 300;
+
+export interface WecomHttp {
+	getJson: (url: string) => Promise<Record<string, unknown>>
+	postJson: (url: string, body: unknown) => Promise<Record<string, unknown>>
+}
+
+export interface WecomCache {
+	get: (key: string) => Promise<string | null>
+	set: (key: string, value: string, ttlSecs: number) => Promise<unknown>
+	del: (key: string) => Promise<unknown>
+}
+
+export interface WecomClientDeps {
+	http: WecomHttp
+	cache: WecomCache
+}
+
+export function runtimeHttp(): WecomHttp {
+	async function call(url: string, init: RequestInit): Promise<Record<string, unknown>> {
+		let res: Response;
+		try {
+			res = await fetch(url, { ...init, signal: AbortSignal.timeout(TIMEOUT_MS) });
+		}
+		catch (e) {
+			throw upstream(`企微接口不可达：${(e as Error).message}`);
+		}
+		if (!res.ok)
+			throw upstream(`企微接口 HTTP ${res.status}`);
+		try {
+			return await res.json() as Record<string, unknown>;
+		}
+		catch {
+			throw upstream("企微接口返回非 JSON");
+		}
+	}
+	return {
+		getJson: url => call(url, { method: "GET" }),
+		postJson: (url, body) => call(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body ?? {}) }),
+	};
+}
+
+export function runtimeCache(): WecomCache {
+	return {
+		get: key => kv.get(key),
+		// kv 没有「带 TTL 的写」，只能写值再设过期——两步之间进程退出、或 expire 失败，
+		// 这个键就变成「永不过期」：corp secret 轮换后旧 token 仍被当作新鲜的，
+		// 表现是长时间 502 而日志一片安静。故显式兜底：设不上过期就删键（宁可每请求回源）。
+		set: async (key, value, ttlSecs) => {
+			await kv.set(key, value);
+			if (!(await kv.expire(key, ttlSecs))) {
+				log.warn("wecom token cached without ttl", "key", key);
+				await kv.del(key);
+			}
+		},
+		del: key => kv.del(key),
+	};
+}
+
+function upstream(message: string): Error {
+	return Object.assign(new Error(message), { status: 502 });
+}
+
+/** code 无效 / 不在应用可见范围 / 非企业成员：统一 401（不泄露具体原因，§5.3 枚举风险） */
+function rejectCode(): never {
+	throw Object.assign(new Error("登录凭据无效或不在应用可见范围内"), { status: 401 });
+}
+
+/** 企微错误码 → 异常。`errcode` 缺失视为成功（get_permanent_code 的历史行为）。 */
+function assertOk(res: Record<string, unknown>, what: string): void {
+	const code = res.errcode;
+	if (code == null || Number(code) === 0)
+		return;
+	throw upstream(`企微 ${what} 失败：errcode=${String(code)} ${String(res.errmsg ?? "")}`.trimEnd());
+}
+
+const TOKEN_EXPIRED = new Set([40001, 40014, 42001]);
+
+export function createWecomClient(deps: WecomClientDeps) {
+	const { http, cache } = deps;
+
+	async function cachedToken(key: string, load: () => Promise<{ token: string, expiresIn: number }>): Promise<string> {
+		const hit = await cache.get(key);
+		if (hit)
+			return hit;
+		const { token, expiresIn } = await load();
+		const ttl = Math.max(60, Math.floor(expiresIn) - TOKEN_SKEW_SECS);
+		await cache.set(key, token, ttl);
+		return token;
+	}
+
+	/** 套件 access_token：需要 suite_ticket（过期/缺失由调用方先拦） */
+	async function suiteAccessToken(suiteId: string, suiteSecret: string, suiteTicket: string): Promise<string> {
+		return cachedToken(`wecom:suite_token:${suiteId}`, async () => {
+			const res = await http.postJson(`${API_BASE}/cgi-bin/service/get_suite_token`, {
+				suite_id: suiteId,
+				suite_secret: suiteSecret,
+				suite_ticket: suiteTicket,
+			});
+			assertOk(res, "get_suite_token");
+			if (!res.suite_access_token)
+				throw upstream("企微 get_suite_token 未返回 suite_access_token");
+			return { token: String(res.suite_access_token), expiresIn: Number(res.expires_in ?? 7200) };
+		});
+	}
+
+	/**
+	 * auth_code → permanent_code（+ 企业信息 + 应用列表）。
+	 * 代开发用 `/service/v2/get_permanent_code`：返回 is_customized_app=true，且**不返回 access_token**。
+	 * auth_code 一次有效（10 分钟内），重放只会拿到企微错误码 → 502，由调用方丢弃本条事件。
+	 */
+	async function permanentCodeByAuthCode(suiteAccessToken: string, authCode: string): Promise<{
+		permanentCode: string
+		corpId: string
+		corpName: string | null
+		agentIds: string[]
+		state: string | null
+	}> {
+		const res = await http.postJson(`${API_BASE}/cgi-bin/service/v2/get_permanent_code?suite_access_token=${encodeURIComponent(suiteAccessToken)}`, { auth_code: authCode });
+		assertOk(res, "get_permanent_code");
+		const authCorp = (res.auth_corp_info ?? {}) as Record<string, unknown>;
+		const agentList = ((res.auth_info ?? {}) as Record<string, unknown>).agent;
+		const agentIds = Array.isArray(agentList)
+			? agentList.map(a => String((a as Record<string, unknown>).agentid)).filter(Boolean)
+			: [];
+		if (!res.permanent_code || !authCorp.corpid)
+			throw upstream("企微 get_permanent_code 返回缺少 permanent_code / corpid");
+		if (agentIds.length === 0)
+			throw upstream("企微 get_permanent_code 未返回授权应用（auth_info.agent 为空）");
+		return {
+			permanentCode: String(res.permanent_code),
+			corpId: String(authCorp.corpid),
+			corpName: authCorp.corp_name == null ? null : String(authCorp.corp_name),
+			agentIds,
+			state: res.state == null ? null : String(res.state),
+		};
+	}
+
+	/**
+	 * 预授权码（开通入口用）：套件级、10 分钟、一次有效，拼进 install URL 交给企业管理员点开。
+	 * 与 permanent_code 无关——它只换「安装向导里那一屏同意」，真正的永久码仍由 create_auth 回调给。
+	 */
+	async function preAuthCode(suiteAccessToken: string): Promise<{ code: string, expiresIn: number }> {
+		const res = await http.postJson(`${API_BASE}/cgi-bin/service/get_pre_auth_code?suite_access_token=${encodeURIComponent(suiteAccessToken)}`, {});
+		assertOk(res, "get_pre_auth_code");
+		if (!res.pre_auth_code)
+			throw upstream("企微 get_pre_auth_code 未返回 pre_auth_code");
+		return { code: String(res.pre_auth_code), expiresIn: Number(res.expires_in ?? 600) };
+	}
+
+	/** 企业 access_token（代开发 = 自建应用的 gettoken，corpsecret 就是 permanent_code） */
+	async function corpAccessToken(corpId: string, agentId: string, secret: string): Promise<string> {
+		return cachedToken(`wecom:corp_token:${corpId}:${agentId}`, async () => {
+			const res = await http.getJson(`${API_BASE}/cgi-bin/gettoken?corpid=${encodeURIComponent(corpId)}&corpsecret=${encodeURIComponent(secret)}`);
+			assertOk(res, "gettoken");
+			if (!res.access_token)
+				throw upstream("企微 gettoken 未返回 access_token");
+			return { token: String(res.access_token), expiresIn: Number(res.expires_in ?? 7200) };
+		});
+	}
+
+	async function invalidateCorpToken(corpId: string, agentId: string): Promise<void> {
+		await cache.del(`wecom:corp_token:${corpId}:${agentId}`);
+	}
+
+	/**
+	 * 成员姓名（best-effort）：只用于把 JIT 号的 `display_name` 从工号变成真名。
+	 *
+	 * 三类失败一律返回 null，绝不抛出：套件没有通讯录读权限（60011/48002）、成员不在可见范围、
+	 * 上游抖动。补名是体验优化，不能因为拿不到名字把登录打成 5xx——
+	 * 调用方拿到 null 就用工号兜底。
+	 * token 复用 `userIdByCode` 刚取的那份缓存（同请求内通常 0 次额外换票）。
+	 */
+	async function userNameById(corpId: string, agentId: string, secret: string, userid: string): Promise<string | null> {
+		for (let attempt = 0; attempt < 2; attempt++) {
+			let token: string;
+			try {
+				token = await corpAccessToken(corpId, agentId, secret);
+			}
+			catch {
+				return null;
+			}
+			let res: Record<string, unknown>;
+			try {
+				res = await http.getJson(`${API_BASE}/cgi-bin/user/get?access_token=${encodeURIComponent(token)}&userid=${encodeURIComponent(userid)}`);
+			}
+			catch {
+				return null;
+			}
+			const errcode = Number(res.errcode ?? 0);
+			if (TOKEN_EXPIRED.has(errcode) && attempt === 0) {
+				await invalidateCorpToken(corpId, agentId);
+				continue;
+			}
+			if (errcode !== 0)
+				return null;
+			const name = res.name == null ? "" : String(res.name).trim();
+			return name || null;
+		}
+		return null;
+	}
+
+	/** 网页授权 code → userid（snsapi_base；非企业成员/超出可见范围 → 401） */
+	async function userIdByCode(corpId: string, agentId: string, secret: string, code: string): Promise<string> {
+		for (let attempt = 0; attempt < 2; attempt++) {
+			const token = await corpAccessToken(corpId, agentId, secret);
+			const res = await http.getJson(`${API_BASE}/cgi-bin/auth/getuserinfo?access_token=${encodeURIComponent(token)}&code=${encodeURIComponent(code)}`);
+			const errcode = Number(res.errcode ?? 0);
+			if (TOKEN_EXPIRED.has(errcode) && attempt === 0) {
+				await invalidateCorpToken(corpId, agentId);
+				continue;
+			}
+			if (errcode !== 0)
+				rejectCode();
+			const userid = res.userid == null ? "" : String(res.userid);
+			if (!userid)
+				rejectCode(); // 非企业成员（外部联系人）时企微只给 openid，不认作本应用用户
+			return userid;
+		}
+		throw upstream("企微 token 反复失效（40001/42001）");
+	}
+
+	return { suiteAccessToken, permanentCodeByAuthCode, preAuthCode, corpAccessToken, invalidateCorpToken, userIdByCode, userNameById };
+}
+
+export type WecomClient = ReturnType<typeof createWecomClient>;

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

@@ -0,0 +1,133 @@
+// 企微代开发「服务商侧」部署常量（config `vars:` 段，不进 DB、不进 sys_setting）。
+//
+// 多租户动态性边界：**套件（suite）是部署级的**——一个部署 = 一个服务商账号下的一套代开发模板
+// （suite_id/suite_secret/callback token/EncodingAESKey 全在这套模板的后台里）。
+// 「哪个企业装了哪个应用」不写配置：企微 create_auth 回调推 AuthCode → 换 permanent_code →
+// 落 wecom_app_profile，新增企业只需企业管理员扫码授权，**不改配置、不重启**。
+// 同一企业两个应用（测试/正式）也无需改配置：profile 主键含 agent_id（D5）。
+//
+// 与 ldap 同口径：启用开关走 sys_setting（`wecom.enabled`），凭据走部署常量。
+
+import { b64ToBytes } from "./crypt";
+
+export interface WecomConfig {
+	/** 代开发应用模版 id（企微侧即 suite_id），也是回调明文里的 receiveid */
+	suiteId: string
+	suiteSecret: string
+	/** 回调签名 token（企微后台「Token」） */
+	token: string
+	/** 回调加密密钥（43 字符 EncodingAESKey） */
+	encodingAesKey: string
+	/** AES-GCM 落库密钥（hex/base64，16 或 32 字节）：加密 permanent_code/secret */
+	encKey: string
+	/**
+	 * 连接器基址（绝对地址，无尾斜杠），如 `https://site.example.com/api/auth/wecom`。
+	 * 两个派生地址都由它拼出，避免「同一件事配两处、改一处漏一处」：
+	 *   · 指令回调 URL = `<base>/event` → **原样填进企微后台**（须逐字一致，含协议与路径）
+	 *   · 网页授权 redirect_uri = `<base>/callback`
+	 */
+	baseUrl: string
+}
+
+const REQUIRED: Array<[keyof WecomConfig, string]> = [
+	["suiteId", "wecom_suite_id"],
+	["suiteSecret", "wecom_suite_secret"],
+	["token", "wecom_callback_token"],
+	["encodingAesKey", "wecom_encoding_aes_key"],
+	["encKey", "wecom_enc_key"],
+	["baseUrl", "wecom_base_url"],
+];
+
+/**
+ * 落库密钥格式校验（fail-fast 在**读配置**处，而不是等 create_auth 时在 crypto 里炸）：
+ * oj 的 aesGcmEncrypt 只收「16 或 32 字节的 hex/base64」，AES-192（24 字节）明确不支持。
+ * 最常见的配置事故是把 32 个「随意字符」当密钥——它按 base64 解出 24 字节，加密时才报错，
+ * 而那时已经是企业授权回调，排查成本最高。
+ */
+export function assertEncKey(encKey: string): void {
+	const hex = /^[0-9a-f]+$/i.test(encKey) && [32, 64].includes(encKey.length);
+	let ok = hex;
+	if (!ok) {
+		try {
+			ok = [16, 32].includes(b64ToBytes(encKey).length);
+		}
+		catch {
+			ok = false;
+		}
+	}
+	if (!ok)
+		throw Object.assign(new Error("企业微信配置错误：wecom_enc_key 必须是 16 或 32 字节的 hex（32/64 字符）或 base64"), { status: 400 });
+}
+
+/**
+ * 读部署常量。缺任一必需项即 400（「未配置」是运维事实，不是服务端缺陷）：
+ * 前半段（suite 凭据）缺失 → 企微登录整体不可用；encKey 缺失则 permanent_code 无法安全落库，
+ * 宁可拒服务，也不退化成明文存储（§7.5 数据合规红线）。
+ */
+export function readWecomConfig(): WecomConfig {
+	const cfg: WecomConfig = {
+		suiteId: vars.get("wecom_suite_id") ?? "",
+		suiteSecret: vars.get("wecom_suite_secret") ?? "",
+		token: vars.get("wecom_callback_token") ?? "",
+		encodingAesKey: vars.get("wecom_encoding_aes_key") ?? "",
+		encKey: vars.get("wecom_enc_key") ?? "",
+		baseUrl: (vars.get("wecom_base_url") ?? "").replace(/\/+$/, ""),
+	};
+	const missing = REQUIRED.filter(([field]) => !cfg[field]).map(([, name]) => name);
+	if (missing.length)
+		throw Object.assign(new Error(`企业微信未配置：config vars 缺少 ${missing.join(" / ")}`), { status: 400 });
+	if (!/^https?:\/\//.test(cfg.baseUrl))
+		throw Object.assign(new Error("企业微信配置错误：wecom_base_url 必须是绝对地址（企微回调与 redirect_uri 都要求）"), { status: 400 });
+	assertEncKey(cfg.encKey);
+	return cfg;
+}
+
+/** 企微后台「指令回调 URL」：原样填这个（base + /event） */
+export function eventUrlOf(cfg: WecomConfig): string {
+	return `${cfg.baseUrl}/event`;
+}
+
+/** 网页授权 redirect_uri（base + /callback） */
+export function loginRedirectOf(cfg: WecomConfig): string {
+	return `${cfg.baseUrl}/callback`;
+}
+
+/** 连接器在站点里的固定挂载后缀（模块 apiPrefix `/auth` + 平台 API 前缀 `/api`）：`siteRootOf` 靠它剥离 */
+const CONNECTOR_SUFFIX = "/api/auth/wecom";
+
+/**
+ * 站点根（origin + 子路径前缀，无尾斜杠）：302 回跳落到 SPA 时用。
+ *
+ * 不能只取 origin：子路径部署（oj `mounts: [{ prefix: /oj }]`）时 SPA 的登录页在 `/oj/login`，
+ * 回跳到 `/login` 会打到宿主机根的别的应用（或 404）。前缀不另配一个变量——它就等于
+ * `wecom_base_url` 去掉本连接器的固定后缀，配一处即可，且不匹配时**报错**而不是猜。
+ */
+export function siteRootOf(cfg: WecomConfig): string {
+	const url = new URL(cfg.baseUrl);
+	const path = url.pathname.replace(/\/+$/, "");
+	if (!path.endsWith(CONNECTOR_SUFFIX))
+		throw Object.assign(new Error(`企业微信配置错误：wecom_base_url 必须以 ${CONNECTOR_SUFFIX} 结尾（如 https://site.example.com/oj${CONNECTOR_SUFFIX}）`), { status: 400 });
+	return `${url.origin}${path.slice(0, -CONNECTOR_SUFFIX.length)}`;
+}
+
+/**
+ * 代开发「开通入口」：企业管理员点开 → 企微授权安装页。
+ * `redirect_uri` 落在站点根下的登录页（安装完回站点，指令回调已把 profile 落好）。
+ */
+export function installUrlOf(cfg: WecomConfig, preAuthCode: string, state: string): string {
+	const redirect = `${siteRootOf(cfg)}/login?wecom_installed=1`;
+	const q = new URLSearchParams({
+		suite_id: cfg.suiteId,
+		pre_auth_code: preAuthCode,
+		redirect_uri: redirect,
+	});
+	if (state)
+		q.set("state", state);
+	return `https://open.work.weixin.qq.com/3rdapp/install?${q.toString()}`;
+}
+
+/** 登录方式发现用：只看开关，不读凭据（登录页要先知道「有没有这个方式」） */
+export async function wecomEnabled(): Promise<boolean> {
+	const rows = await db.table("sys_setting").select(["value"]).where({ field: "key", op: "eq", value: "wecom.enabled" }).all() as Array<{ value: string | null }>;
+	return rows[0]?.value === "1";
+}

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