@oj-module/cli 0.2.43 → 0.2.45

package/templates/tests/tenant-isolation.spec.ts

@@ -0,0 +1,133 @@
+// BDD：多租户地基的运行时语义（计划 §5.7 第 2/3/4/6 项）。
+//
+// 这一层此前只能在真 oj 上验证：夹具的构造器垫片不模拟租户注入。夹具补上之后（见
+// tests/fixture.ts 头注释），四件事才能在 L2 钉住：
+//   3 构造器 insert 自动落当前租户（业务代码不该自己写 tenant_id）
+//   6 读写自动按当前租户过滤（跨租户 update/delete 落 0 行，refresh 查不到别家行）
+//   4 同一 username 在不同租户各一行（UNIQUE(tenant_id, username)）
+//   2 裸 SQL 触碰租户表却不写 tenant_id → 拒（`sql_guard: deny` 的近似；样例在 guard.spec.ts）
+//
+// 为什么不测业务 handler：那在 tenant-forgery.spec.ts（伪造头的端点级拦截）。本文件只钉地基——
+// 地基错了，上层所有「读不到别家数据」的断言都可能是假绿。
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+
+import { DEFAULT_TENANT, installDb } from "./fixture";
+
+const g = globalThis as any;
+let dbo: ReturnType<typeof installDb>;
+
+/** 模拟一次请求带 `X-TENANT-ID`（oj 侧由构造器读同一个值） */
+function asTenant(tenant?: string): void {
+	g.http = tenant ? { tenantId: tenant } : {};
+}
+
+function rows(sql: string, params: unknown[] = []): Array<Record<string, any>> {
+	return dbo.prepare(sql).all(...params) as Array<Record<string, any>>;
+}
+
+beforeAll(() => {
+	dbo = installDb();
+});
+
+afterEach(() => {
+	asTenant();
+});
+
+describe("§5.7-3 insert 自动落当前租户", () => {
+	it("构造器不写 tenant_id 也落到当前租户", async () => {
+		asTenant("acme");
+		await db.table("users").insert({ username: "iso-alice", password_hash: "x" }).run();
+		expect(rows("SELECT tenant_id FROM users WHERE username = 'iso-alice'")[0]!.tenant_id).toBe("acme");
+	});
+
+	it("无请求上下文时落部署默认租户（运维脚本/迁移的形态）", async () => {
+		asTenant();
+		await db.table("users").insert({ username: "iso-bob", password_hash: "x" }).run();
+		expect(rows("SELECT tenant_id FROM users WHERE username = 'iso-bob'")[0]!.tenant_id).toBe(DEFAULT_TENANT);
+	});
+
+	it("显式给了 tenant_id 就按给的落，不被当前租户覆盖", async () => {
+		asTenant("acme");
+		await db.table("users").insert({ username: "iso-carol", password_hash: "x", tenant_id: "globex" }).run();
+		expect(rows("SELECT tenant_id FROM users WHERE username = 'iso-carol'")[0]!.tenant_id).toBe("globex");
+	});
+});
+
+describe("§5.7-6 读写自动按当前租户过滤", () => {
+	it("select 只看得到本租户的行", async () => {
+		asTenant("globex");
+		const names = (await db.table("users").all() as Array<Record<string, unknown>>).map(u => String(u.username));
+		expect(names).not.toContain("iso-alice");
+		expect(names).toContain("iso-carol"); // 前一个用例显式落在 globex 的那行
+	});
+
+	it("update 跨租户落 0 行，目标行不被改", async () => {
+		const changed = await db.table("users")
+			.where({ field: "username", op: "eq", value: "iso-alice" })
+			.update({ email: "hijacked@evil" })
+			.run();
+		expect(changed).toBe(0);
+		expect(rows("SELECT email FROM users WHERE username = 'iso-alice'")[0]!.email).toBeNull();
+	});
+
+	it("delete 跨租户落 0 行，目标行仍在", async () => {
+		const deleted = await db.table("users")
+			.where({ field: "username", op: "eq", value: "iso-alice" })
+			.delete()
+			.run();
+		expect(deleted).toBe(0);
+		expect(rows("SELECT id FROM users WHERE username = 'iso-alice'")).toHaveLength(1);
+	});
+
+	it("truncate 只清本租户（A 组表）", async () => {
+		asTenant("acme");
+		await db.table("todos").insert({ title: "acme-todo" }).run();
+		asTenant("globex");
+		await db.table("todos").insert({ title: "globex-todo" }).run();
+
+		asTenant("acme");
+		await db.table("todos").truncate().run();
+		expect(rows("SELECT title FROM todos")).toEqual([{ title: "globex-todo" }]);
+	});
+
+	it("refresh token 换票：别家的 token_hash 在本租户查不到", async () => {
+		asTenant("acme");
+		await db.table("sys_refresh_token").insert({
+			token_hash: "iso-h1",
+			user_id: 1,
+			expires_at: 9_999_999_999,
+			created_at: 0,
+		}).run();
+
+		asTenant("globex");
+		const other = await db.table("sys_refresh_token")
+			.where({ field: "token_hash", op: "eq", value: "iso-h1" })
+			.all();
+		expect(other).toHaveLength(0);
+
+		asTenant("acme");
+		const own = await db.table("sys_refresh_token")
+			.where({ field: "token_hash", op: "eq", value: "iso-h1" })
+			.all();
+		expect(own).toHaveLength(1);
+	});
+});
+
+describe("§5.7-4 同一 username 在不同租户各一行", () => {
+	it("唯一约束收敛为 (tenant_id, username)：同工号两家企业互不冲突", async () => {
+		asTenant("acme");
+		await db.table("users").insert({ username: "wecom:zhangsan", password_hash: "x" }).run();
+		asTenant("globex");
+		await db.table("users").insert({ username: "wecom:zhangsan", password_hash: "x" }).run();
+
+		expect(rows("SELECT tenant_id FROM users WHERE username = 'wecom:zhangsan' ORDER BY tenant_id"))
+			.toEqual([{ tenant_id: "acme" }, { tenant_id: "globex" }]);
+	});
+
+	it("同租户内重复用户名仍被唯一约束挡住", async () => {
+		asTenant("acme");
+		await expect(
+			db.table("users").insert({ username: "wecom:zhangsan", password_hash: "x" }).run(),
+		).rejects.toThrow(/UNIQUE/i);
+	});
+});

package/templates/tests/username-namespace.spec.ts

@@ -0,0 +1,118 @@
+// BDD：外来号命名空间抢占（B6 红线）在**改名路径**上的延伸。
+//
+// 背景：外部身份（ldap/sso/wecom）的本地用户名是 `ldap:<uid>` / `sso:<sub>` / `wecom:<userid>`
+// 这种带前缀的形式，JIT 建档时按用户名反查——查到就复用，查不到才新建。于是「用户名」本身
+// 就是外部身份的认领凭据。
+//
+// 攻击：我从本地建号起家（比如 `mario`），自助改名为 `wecom:boss`。此时企微侧那位
+// `boss` 还没登录过，库里没有真行，于是我的行成了唯一的匹配者——他第一次扫码登录时
+// `ensureWecomUser` 查到的就是**我的 uid**，服务端给真正的 boss 签发了我的会话，
+// 我的角色、我的数据、我的操作日志，全部对他敞开。
+//
+// 建号侧早挡了这条红线（rbac-users.spec.ts「B6：建号加固」），但改名侧漏了——同一条红线
+// 必须钉在所有写 `users.username` 的入口上，本文件就是把「漏了会怎样」钉死：
+//   · 自助改名拒 `wecom:` 前缀（401/403 之后的第三道：不给你改）；
+//   · 对照组：普通改名照旧放行（红线不能误伤正常用户）；
+//   · 端到端：改名被拒之后，真正的外部成员 JIT 登录拿到的是**新建**的那一行。
+
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { invalidateAllUsers } from "../src/_platform/api/_shared/service/infra/access";
+import { ensureWecomUser, externalUsername } from "../src/auth/api/_shared/wecom/login";
+import profile from "../src/personal-center/api/profile/api";
+import { installDb } from "./fixture";
+
+const g = globalThis as any;
+let dbo: ReturnType<typeof installDb>;
+
+interface Captured { status: number | null, body: any }
+
+let out: Captured;
+
+function installJson(): void {
+	out = { status: null, body: null };
+	g.json = {
+		ok: (data?: unknown) => {
+			out.status = 200;
+			out.body = data;
+		},
+		fail: (code: number, msg: string) => {
+			out.status = code;
+			out.body = { code, msg };
+		},
+	};
+}
+
+function mkUser(username: string): number {
+	dbo.prepare("INSERT INTO users (username, password_hash) VALUES (?, 'x')").run(username);
+	return (dbo.prepare("SELECT id FROM users WHERE username = ?").get(username) as { id: number }).id;
+}
+
+function usernameOf(uid: number): string {
+	const row = dbo.prepare("SELECT username FROM users WHERE id = ?").get(uid) as { username: string } | undefined;
+	return row ? String(row.username) : "";
+}
+
+beforeAll(() => {
+	dbo = installDb();
+});
+
+beforeEach(() => {
+	installJson();
+	invalidateAllUsers();
+});
+
+afterEach(() => {
+	g.http = {};
+	dbo.exec("DELETE FROM sys_user_role");
+	dbo.exec("DELETE FROM users WHERE username LIKE 'u_%' OR username LIKE 'wecom:%' OR username LIKE 'mario%'");
+});
+
+describe("自助改名不得抢占外部身份命名空间", () => {
+	it("改名为 wecom:boss → 400，且自己的用户名原样不动", async () => {
+		const uid = mkUser("u_mario");
+		g.http = { user: { id: uid }, body: { username: "wecom:boss" } };
+
+		await profile.post();
+
+		expect(out.status).toBe(400);
+		expect(String(out.body.msg)).toMatch(/reserved/i);
+		expect(usernameOf(uid)).toBe("u_mario");
+	});
+
+	it("三个前缀全覆盖（ldap:/sso:/wecom:），大小写不敏感", async () => {
+		const uid = mkUser("u_every");
+		for (const name of ["ldap:alice", "sso:bob", "wecom:carol", "WeCom:Dave"]) {
+			g.http = { user: { id: uid }, body: { username: name } };
+			await profile.post();
+			expect(out.status, name).toBe(400);
+		}
+		expect(usernameOf(uid)).toBe("u_every");
+	});
+
+	it("对照组：普通改名照旧放行", async () => {
+		const uid = mkUser("u_plain");
+		g.http = { user: { id: uid }, body: { username: "u_renamed" } };
+
+		await profile.post();
+
+		expect(out.status).toBe(200);
+		expect(usernameOf(uid)).toBe("u_renamed");
+	});
+});
+
+describe("端到端：抢占不成，真正的外部成员拿到的是自己那一行", () => {
+	it("wecom:boss 首次 JIT 登录 → 新建独立 uid，不是抢名者的 uid", async () => {
+		const attackerUid = mkUser("u_squatter");
+		g.http = { user: { id: attackerUid }, body: { username: externalUsername("boss") } };
+		await profile.post();
+		expect(out.status).toBe(400); // 抢占被拒是前提
+
+		g.http = {};
+		const { uid } = await ensureWecomUser("ww_corp", "boss");
+
+		expect(uid).not.toBe(attackerUid);
+		expect(usernameOf(uid)).toBe("wecom:boss");
+		// 幂等：boss 再登一次仍是同一行
+		expect((await ensureWecomUser("ww_corp", "boss")).uid).toBe(uid);
+	});
+});

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

@@ -0,0 +1,386 @@
+// BDD：代开发后台（服务商运营面）——清单 / 启停 / 开通入口 + 三个端点的接线。
+//
+// 这里钉的是「运营动作的正确边界」，不是企微协议（协议在 wecom-connector.spec.ts）：
+//   1. 清单**不带** permanent_code（secret 不出库：连 superadmin 也不给看）；
+//   2. 停用**一个应用 ≠ 停用一家企业**（同企业测试/正式两应用，停测试不得把正式用户踢下线）；
+//   3. 停用到该企业最后一个启用应用时才吊销会话，且只吊销**该租户**的；
+//   4. 判权缓存随吊销立即失效（撤销即强退，D10）——用「删角色后 stale 仍放行 → 停用后立刻 403」反证；
+//   5. 端点仅 superadmin（admin 属于某个租户，不该看别家 corp_id）。
+//
+// 夹具即真实库（真迁移 + 真 sqlite），全局 json/http/vars/kv/crypto/fetch 按 oj 同名同面桩掉。
+/* eslint-disable test/prefer-lowercase-title -- AC 编号是验收锚点，保留大写 */
+import { Buffer } from "node:buffer";
+import { webcrypto } from "node:crypto";
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { assertSuperAdmin, invalidateAllUsers } from "../src/_platform/api/_shared/service/infra/access";
+import { listApps, setAppStatus } from "../src/auth/api/_shared/wecom/admin";
+import { createWecomClient, runtimeCache, runtimeHttp } from "../src/auth/api/_shared/wecom/client";
+import { installUrlOf, readWecomConfig, siteRootOf } from "../src/auth/api/_shared/wecom/config";
+import { installDb } from "./fixture";
+
+const g = globalThis as any;
+let dbo: ReturnType<typeof installDb>;
+
+const SUITE = "suite_1";
+const AES_KEY_B64 = Buffer.from(webcrypto.getRandomValues(new Uint8Array(32))).toString("base64");
+const NOW = 1_700_000_000;
+
+interface Captured { status: number | null, body: any }
+
+let out: Captured;
+
+function installJson(): void {
+	out = { status: null, body: null };
+	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: () => {},
+		redirect: Object.assign(() => {}, { found: () => {}, seeOther: () => {} }),
+		stream: () => ({ write: () => {}, 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: "cb_token",
+		wecom_encoding_aes_key: AES_KEY_B64.replace(/=$/, ""),
+		wecom_enc_key: "0123456789abcdef0123456789abcdef",
+		wecom_base_url: "https://site.example.com/api/auth/wecom",
+		...overrides,
+	};
+	g.vars = { get: (name: string) => base[name] ?? null };
+}
+
+/** 每次换新 Map：suite_token 有 kv 缓存，跨用例复用会把「该打的上游」吞掉 */
+function installKv(): void {
+	const store = new Map<string, string>();
+	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);
+		},
+		expire: async () => 1,
+		incr: async () => 1,
+	};
+}
+
+function installCrypto(): void {
+	Object.defineProperty(globalThis, "crypto", {
+		value: {
+			randomHex: (n = 32) => `r${"a".repeat(n * 2)}`,
+			sha256Hex: (s: string) => `sha(${s})`,
+			aesGcmEncrypt: (plain: string) => `gcm(${plain})`,
+			aesGcmDecrypt: (blob: string) => blob.replace(/^gcm\((.*)\)$/, "$1"),
+		},
+		configurable: true,
+	});
+}
+
+function request(opts: { query?: Record<string, string>, body?: unknown, user?: { id: number } } = {}): void {
+	g.http = { method: "GET", query: opts.query ?? {}, body: opts.body ?? null, headers: {}, ...(opts.user ? { user: opts.user } : {}) };
+}
+
+function seedCorp(corpId = "ww_corp_a", agentId = "100001", env = "prod", status = "active", authCorpId = corpId): 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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+		.run(SUITE, corpId, agentId, authCorpId, env, `企业 ${corpId}`, status, `gcm(perm_${corpId}_${agentId})`, NOW, NOW);
+}
+
+function seedTicket(ticket = "tk_9", expiresAt = NOW + 1800): void {
+	dbo.prepare("INSERT INTO wecom_suite_ticket (suite_id, suite_ticket, expires_at, update_time) VALUES (?, ?, ?, ?)").run(SUITE, ticket, expiresAt, NOW);
+}
+
+function mkUser(username: string, roles: string[] = []): number {
+	dbo.prepare("INSERT INTO users (username, password_hash) VALUES (?, 'x')").run(username);
+	const id = (dbo.prepare("SELECT id FROM users WHERE username = ?").get(username) as { id: number }).id;
+	for (const r of roles)
+		dbo.prepare("INSERT OR IGNORE INTO sys_user_role (user_id, role_name) VALUES (?, ?)").run(id, r);
+	return id;
+}
+
+/** 只关心 invalidateCorpToken 是否被调（其余成员由类型收窄成 unknown） */
+function fakeClient(): { client: any, invalidated: string[] } {
+	const invalidated: string[] = [];
+	return {
+		client: {
+			invalidateCorpToken: async (corpId: string, agentId: string) => {
+				invalidated.push(`${corpId}:${agentId}`);
+			},
+		},
+		invalidated,
+	};
+}
+
+const deps = { store: { encrypt: (p: string) => `gcm(${p})`, decrypt: (b: string) => b, now: () => NOW } };
+
+/** createInstall 的薄包装：store.now 固定，避免用例依赖真实时钟 */
+async function createInstallForTest(cfg: ReturnType<typeof readWecomConfig>, client: ReturnType<typeof createWecomClient>, state: string) {
+	const { createInstall } = await import("../src/auth/api/_shared/wecom/admin");
+	return createInstall(cfg, client, deps.store, state);
+}
+
+const api = async () => (await import("../src/auth/api/wecom/admin/api")).default;
+
+beforeAll(() => {
+	dbo = installDb();
+	g.log = { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} };
+	g.db.asTenant = () => {
+		throw new Error("管理面不应调用 asTenant（请求已带租户头）");
+	};
+});
+
+beforeEach(() => {
+	installJson();
+	installVars();
+	installKv();
+	installCrypto();
+	g.fetch = async () => ({ ok: true, json: async () => ({}) });
+	for (const t of ["wecom_app_profile", "wecom_suite_ticket", "sys_refresh_token", "sys_oplog", "sys_user_role"])
+		dbo.exec(`DELETE FROM ${t}`);
+	invalidateAllUsers();
+});
+
+afterEach(() => {
+	g.http = {};
+	invalidateAllUsers();
+});
+
+describe("P3-A：清单（listApps）", () => {
+	it("不返回 permanent_code（secret 不出库，superadmin 也不给看）", async () => {
+		seedCorp();
+		const rows = await listApps();
+		expect(rows).toHaveLength(1);
+		expect(Object.keys(rows[0]!)).not.toContain("permanent_code_enc");
+		expect(JSON.stringify(rows)).not.toContain("perm_ww_corp_a");
+	});
+
+	it("稳定序：先企业再应用，同企业测试/正式两行相邻", async () => {
+		seedCorp("ww_b", "100002");
+		seedCorp("ww_a", "100009", "prod");
+		seedCorp("ww_a", "100001", "test");
+		const rows = await listApps();
+		expect(rows.map(r => `${r.corp_id}:${r.agent_id}`)).toEqual(["ww_a:100001", "ww_a:100009", "ww_b:100002"]);
+	});
+
+	it("空表 → []（不是报错）", async () => {
+		await expect(listApps()).resolves.toEqual([]);
+	});
+});
+
+describe("P3-B：启停（setAppStatus）", () => {
+	it("企业代码/应用不匹配 → 404，且不改任何行", async () => {
+		seedCorp("ww_a", "100001");
+		const { client } = fakeClient();
+		await expect(setAppStatus("ww_a", "999999", "disabled", { client, ...deps }))
+			.rejects
+			.toMatchObject({ status: 404 });
+		expect(dbo.prepare("SELECT status FROM wecom_app_profile").get()).toMatchObject({ status: "active" });
+	});
+
+	it("停用同企业两个应用中的一个 → 不吊销会话（否则停测试应用会把正式用户踢下线）", async () => {
+		seedCorp("ww_a", "100001", "test");
+		seedCorp("ww_a", "100002", "prod");
+		dbo.prepare("INSERT INTO sys_refresh_token (token_hash, tenant_id, user_id, expires_at, revoked, created_at) VALUES ('h1', 'ww_a', 1, ?, 0, ?)").run(NOW + 100, NOW);
+		const { client, invalidated } = fakeClient();
+
+		const r = await setAppStatus("ww_a", "100001", "disabled", { client, ...deps });
+		expect(r).toEqual({ updated: 1, revokedSessions: 0 });
+		expect(dbo.prepare("SELECT COUNT(*) AS n FROM sys_refresh_token WHERE tenant_id = 'ww_a'").get()).toMatchObject({ n: 1 });
+		// secret 仍可能在另一状态被缓存：无论启停都先让企业 token 失效
+		expect(invalidated).toEqual(["ww_a:100001"]);
+	});
+
+	it("停用该企业最后一个启用应用 → 只吊销该租户的会话", async () => {
+		seedCorp("ww_a", "100001");
+		seedCorp("ww_b", "100002");
+		dbo.prepare("INSERT INTO sys_refresh_token (token_hash, tenant_id, user_id, expires_at, revoked, created_at) VALUES ('h1', 'ww_a', 1, ?, 0, ?)").run(NOW + 100, NOW);
+		dbo.prepare("INSERT INTO sys_refresh_token (token_hash, tenant_id, user_id, expires_at, revoked, created_at) VALUES ('h2', 'ww_a', 2, ?, 0, ?)").run(NOW + 100, NOW);
+		dbo.prepare("INSERT INTO sys_refresh_token (token_hash, tenant_id, user_id, expires_at, revoked, created_at) VALUES ('h3', 'ww_b', 3, ?, 0, ?)").run(NOW + 100, NOW);
+		const { client } = fakeClient();
+
+		const r = await setAppStatus("ww_a", "100001", "disabled", { client, ...deps });
+		expect(r).toEqual({ updated: 1, revokedSessions: 2 });
+		expect(dbo.prepare("SELECT COUNT(*) AS n FROM sys_refresh_token").get()).toMatchObject({ n: 1 });
+		expect(dbo.prepare("SELECT tenant_id FROM sys_refresh_token").get()).toMatchObject({ tenant_id: "ww_b" });
+	});
+
+	it("吊销会同时清判权缓存（撤销即强退）：stale 快照在停用后立刻失效", async () => {
+		const uid = mkUser("u_super", ["superadmin"]);
+		request({ user: { id: uid } });
+		await expect(assertSuperAdmin()).resolves.toBeUndefined();
+
+		// 直接删角色绕过写路径 → 判权缓存此时仍是 stale（10s TTL 内的正常残留）
+		dbo.exec("DELETE FROM sys_user_role");
+		await expect(assertSuperAdmin()).resolves.toBeUndefined();
+
+		seedCorp("ww_a", "100001");
+		const { client } = fakeClient();
+		await setAppStatus("ww_a", "100001", "disabled", { client, ...deps });
+
+		await expect(assertSuperAdmin()).rejects.toMatchObject({ status: 403 });
+	});
+
+	it("启用不动会话，但仍让企业 token 缓存失效", async () => {
+		seedCorp("ww_a", "100001", "prod", "disabled");
+		dbo.prepare("INSERT INTO sys_refresh_token (token_hash, tenant_id, user_id, expires_at, revoked, created_at) VALUES ('h1', 'ww_a', 1, ?, 0, ?)").run(NOW + 100, NOW);
+		const { client, invalidated } = fakeClient();
+
+		const r = await setAppStatus("ww_a", "100001", "active", { client, ...deps });
+		expect(r).toEqual({ updated: 1, revokedSessions: 0 });
+		expect(invalidated).toEqual(["ww_a:100001"]);
+		expect(dbo.prepare("SELECT status FROM wecom_app_profile").get()).toMatchObject({ status: "active" });
+	});
+
+	it("按 auth_corp_id（open_corpid）也能定位同一个应用", async () => {
+		seedCorp("ww_real", "100001", "prod", "active", "open_corp_x");
+		const { client } = fakeClient();
+		await expect(setAppStatus("open_corp_x", "100001", "disabled", { client, ...deps }))
+			.resolves
+			.toMatchObject({ updated: 1 });
+	});
+});
+
+describe("P3-C：开通入口（createInstall）", () => {
+	function stubUpstream(preAuth = "PRE_1", expiresIn = 600): string[] {
+		const calls: string[] = [];
+		g.fetch = async (url: string) => {
+			calls.push(url);
+			return {
+				ok: true,
+				json: async () => {
+					if (url.includes("get_suite_token"))
+						return { suite_access_token: "suite_tk", expires_in: 7200 };
+					if (url.includes("get_pre_auth_code"))
+						return { pre_auth_code: preAuth, expires_in: expiresIn };
+					throw new Error(`stub fetch 未预期：${url}`);
+				},
+			};
+		};
+		return calls;
+	}
+
+	it("suite_ticket → suite_token → 预授权码 → install URL（redirect_uri 落站点根登录页）", async () => {
+		seedTicket();
+		const calls = stubUpstream();
+		const cfg = readWecomConfig();
+		const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
+
+		const r = await createInstallForTest(cfg, client, "st_1");
+		expect(calls.some(u => u.includes("get_suite_token"))).toBe(true);
+		expect(calls.some(u => u.includes("get_pre_auth_code"))).toBe(true);
+		expect(r.callbackUrl).toBe("https://site.example.com/api/auth/wecom/event");
+		expect(r.expiresIn).toBe(600);
+
+		const url = new URL(r.installUrl);
+		expect(`${url.origin}${url.pathname}`).toBe("https://open.work.weixin.qq.com/3rdapp/install");
+		expect(url.searchParams.get("suite_id")).toBe(SUITE);
+		expect(url.searchParams.get("pre_auth_code")).toBe("PRE_1");
+		expect(url.searchParams.get("redirect_uri")).toBe("https://site.example.com/login?wecom_installed=1");
+		expect(url.searchParams.get("state")).toBe("st_1");
+	});
+
+	it("子路径部署：redirect_uri 保留 /oj（回跳不落到宿主机根）", () => {
+		installVars({ wecom_base_url: "https://site.example.com/oj/api/auth/wecom" });
+		const cfg = readWecomConfig();
+		expect(siteRootOf(cfg)).toBe("https://site.example.com/oj");
+		const url = new URL(installUrlOf(cfg, "PRE_1", ""));
+		expect(url.searchParams.get("redirect_uri")).toBe("https://site.example.com/oj/login?wecom_installed=1");
+		// state 为空时不出现在 URL 里（不塞空串进去骗企微后台）
+		expect(url.searchParams.has("state")).toBe(false);
+	});
+
+	it("缺 suite_ticket（回调未打通/已过期）→ 503，不白跑一趟上游", async () => {
+		const calls = stubUpstream();
+		const cfg = readWecomConfig();
+		const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
+		await expect(createInstallForTest(cfg, client, "")).rejects.toMatchObject({ status: 503 });
+		expect(calls).toEqual([]);
+	});
+
+	it("上游 errcode → 502（可重试语义，不是 500）", async () => {
+		seedTicket();
+		g.fetch = async () => ({ ok: true, json: async () => ({ errcode: 40001, errmsg: "invalid credential" }) });
+		const cfg = readWecomConfig();
+		const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
+		await expect(createInstallForTest(cfg, client, "")).rejects.toMatchObject({ status: 502 });
+	});
+});
+
+describe("P3-D：端点接线（/auth/wecom/admin/*）", () => {
+	it("superadmin 才能进：admin 与未登录都 403", async () => {
+		const adminId = mkUser("u_admin", ["admin"]);
+		request({ user: { id: adminId } });
+		await (await api()).apps.get();
+		expect(out.status).toBe(403);
+
+		installJson();
+		request({});
+		await (await api()).apps.get();
+		expect(out.status).toBe(403);
+	});
+
+	it("apps.get → 200 + 数组（不含 permanent_code）", async () => {
+		seedCorp();
+		const uid = mkUser("u_super2", ["superadmin"]);
+		request({ user: { id: uid } });
+		await (await api()).apps.get();
+		expect(out.status).toBe(200);
+		expect(out.body).toHaveLength(1);
+		expect(JSON.stringify(out.body)).not.toContain("perm_");
+	});
+
+	it("status.post 缺字段 / status 非法 → 400（不猜默认值）", async () => {
+		const uid = mkUser("u_super3", ["superadmin"]);
+		request({ user: { id: uid }, body: { corpId: "ww_a" } });
+		await (await api()).status.post();
+		expect(out.status).toBe(400);
+
+		installJson();
+		request({ user: { id: uid }, body: { corpId: "ww_a", agentId: "1", status: "paused" } });
+		await (await api()).status.post();
+		expect(out.status).toBe(400);
+	});
+
+	it("status.post 停用 → 200 并记安全级审计（level 4）", async () => {
+		seedCorp("ww_a", "100001");
+		const uid = mkUser("u_super4", ["superadmin"]);
+		request({ user: { id: uid }, body: { corpId: "ww_a", agentId: "100001", status: "disabled" } });
+		await (await api()).status.post();
+
+		expect(out.status).toBe(200);
+		expect(out.body).toEqual({ updated: 1, revokedSessions: 0 });
+		const op = dbo.prepare("SELECT action, module, target, level, detail FROM sys_oplog ORDER BY id DESC LIMIT 1").get() as Record<string, unknown>;
+		expect(op).toMatchObject({ action: "wecom.admin.disable", module: "auth", target: "ww_a", level: 4 });
+		expect(String(op.detail)).toContain("100001");
+	});
+
+	it("status.post 未开通的企业 → 404（不是 500）", async () => {
+		const uid = mkUser("u_super5", ["superadmin"]);
+		request({ user: { id: uid }, body: { corpId: "ww_none", agentId: "1", status: "disabled" } });
+		await (await api()).status.post();
+		expect(out.status).toBe(404);
+		// 404 不该留审计（动作没发生）
+		expect(dbo.prepare("SELECT COUNT(*) AS n FROM sys_oplog").get()).toMatchObject({ n: 0 });
+	});
+
+	it("install.get 未配置部署常量 → 400 并点名缺哪几个 vars", async () => {
+		installVars({ wecom_suite_id: "", wecom_base_url: "" });
+		const uid = mkUser("u_super6", ["superadmin"]);
+		request({ user: { id: uid } });
+		await (await api()).install.get();
+		expect(out.status).toBe(400);
+		expect(out.body.msg).toMatch(/wecom_suite_id/);
+		expect(out.body.msg).toMatch(/wecom_base_url/);
+	});
+});