@oj-module/cli 0.2.43 → 0.2.46

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,176 @@
+// 企微代开发「服务商侧」部署常量（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";
+
+/**
+ * 回调引导配置（Tier A）：echostr URL 验证 + 永久码落库加密所需的全部凭据。
+ * 这四项**全部由部署方在本地生成**，与企业微信无关——所以可以在「创建代开发模版 / 拿到
+ * suite_id」之前就配齐并启动服务、响应企微的 URL 验证。这是打破「先有 suite 还是先有回调」
+ * 死锁的关键（见 plan §18）：鸡生蛋问题里，这四项属于「蛋还没孵出来前就能自己备齐的料」。
+ */
+export interface WecomCallbackConfig {
+	/** 回调签名 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
+}
+
+/**
+ * 完整配置（Tier A + Tier B）：login/callback/create_auth 等 suite 流程额外需要
+ * `suiteId` 与 `suiteSecret`——它们由企业微信在「代开发模版创建成功」后下发（模版详情页可见），
+ * 缺失只影响 suite 流程，不影响回调 URL 验证（后者只需 Tier A）。
+ */
+export interface WecomConfig extends WecomCallbackConfig {
+	/** 代开发应用模版 id（企微侧即 suite_id），也是回调明文里的 receiveid */
+	suiteId: string
+	suiteSecret: string
+}
+
+// Tier A：部署方本地生成，创建模版前即可配齐（token / EncodingAESKey / 落库密钥 / 基址）。
+const REQUIRED_CALLBACK: Array<[keyof WecomCallbackConfig, string]> = [
+	["token", "wecom_callback_token"],
+	["encodingAesKey", "wecom_encoding_aes_key"],
+	["encKey", "wecom_enc_key"],
+	["baseUrl", "wecom_base_url"],
+];
+
+// Tier B：suite 凭据，企业微信在「代开发模版创建成功」后下发（模版详情页可查）。
+const REQUIRED_SUITE: Array<[keyof WecomConfig, string]> = [
+	["suiteId", "wecom_suite_id"],
+	["suiteSecret", "wecom_suite_secret"],
+];
+
+/** 一次性读出六处部署常量（未 trim 的尾斜杠在此归一） */
+function readWecomVars(): WecomConfig {
+	return {
+		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(/\/+$/, ""),
+		suiteId: vars.get("wecom_suite_id") ?? "",
+		suiteSecret: vars.get("wecom_suite_secret") ?? "",
+	};
+}
+
+/**
+ * 落库密钥格式校验（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 });
+}
+
+/**
+ * 读 Tier A 凭据（token / aeskey / encKey / baseUrl）。**不依赖 suite 凭据**：这是 echostr
+ * URL 验证与永久码落库加密所需的全部东西，部署方本地即可生成。引导期（suite_id 尚未下发）
+ * 服务也能靠它启动并响应企微的回调验证（plan §18）。
+ */
+export function readCallbackConfig(): WecomCallbackConfig {
+	const v = readWecomVars();
+	const missing = REQUIRED_CALLBACK.filter(([field]) => !v[field]).map(([, name]) => name);
+	if (missing.length)
+		throw Object.assign(new Error(`企业微信未配置：config vars 缺少 ${missing.join(" / ")}`), { status: 400 });
+	if (!/^https?:\/\//.test(v.baseUrl))
+		throw Object.assign(new Error("企业微信配置错误：wecom_base_url 必须是绝对地址（企微回调与 redirect_uri 都要求）"), { status: 400 });
+	assertEncKey(v.encKey);
+	return { token: v.token, encodingAesKey: v.encodingAesKey, encKey: v.encKey, baseUrl: v.baseUrl };
+}
+
+/**
+ * 读完整部署常量。缺任一必需项即 400（「未配置」是运维事实，不是服务端缺陷）。
+ * 一次报全 Tier A + Tier B 所有缺失项，省掉逐轮补配置的往返；suite 凭据（Tier B）缺失时
+ * 文案点明「由代开发模版创建成功后下发」，避免运维误以为是本地漏配。
+ *
+ * 注：Tier B 缺失只影响 login/callback/create_auth 等 suite 流程；echostr 验证走
+ * `readCallbackConfig()`，不受此约束（见 api.ts::event.get）。
+ */
+export function readWecomConfig(): WecomConfig {
+	const v = readWecomVars();
+	const missing = [...REQUIRED_CALLBACK, ...REQUIRED_SUITE].filter(([field]) => !v[field]).map(([, name]) => name);
+	if (missing.length)
+		throw Object.assign(new Error(`企业微信未配置：config vars 缺少 ${missing.join(" / ")}（suite 凭据由代开发模版创建成功后下发）`), { status: 400 });
+	if (!/^https?:\/\//.test(v.baseUrl))
+		throw Object.assign(new Error("企业微信配置错误：wecom_base_url 必须是绝对地址（企微回调与 redirect_uri 都要求）"), { status: 400 });
+	assertEncKey(v.encKey);
+	return v;
+}
+
+/** 企微后台「指令回调 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";
+}