@oj-module/cli 0.2.43 → 0.2.45

package/templates/tests/fixture.ts

@@ -9,8 +9,15 @@
 // delete / truncate / all / run / listTables。子集外的调用**直接报「未实现」**，不静默返回空结果
 // （静默空值会把「垫片缺能力」伪装成「业务没数据」，是最难查的一类假绿）。
 //
-// 已知边界（模板当前用不到，不模拟）：租户/归属守卫（`tenant_id` 注入、`owner_of`）——模板是单租户，
-// 开启多租户后本夹具必先补这两条，否则守卫失效也会绿。
+// 已知边界（模板当前用不到，不模拟）：归属守卫（`owner_of`）——**租户已模拟**，见下。
+// 租户模拟（2026-10-30 补，多租户上线后必须有，否则守卫失效也会绿）：
+//   · 哪些表按租户隔离不硬编码，建库后按 PRAGMA 找带 `tenant_id` 列的表（与 0015__tenant.sql 同源，
+//     迁移改了这里自动跟随，不会漂移）；
+//   · 当前租户取 `globalThis.http.tenantId`（与 oj 同源：请求头进来就是它），缺省 `default`；
+//     用例里改 `g.http.tenantId` 即可模拟「伪造 X-TENANT-ID」；
+//   · 三条语义与 oj 对齐：insert 自动补 `tenant_id`、select/update/delete/truncate 自动加
+//     `tenant_id = ?` 谓词、裸 SQL（db.query/db.exec）触碰租户表却无 `tenant_id` 直接拒
+//     （近似 `sql_guard: deny`，是文本级判断，不是解析器）。
 //
 // 分工不变：
 //   · L2（本目录 *.spec.ts）：构造器渲染出**语义等价**的 SQL 后在真 sqlite 上跑——服务层行为、
@@ -29,6 +36,45 @@ const SRC = join(dirname(fileURLToPath(import.meta.url)), "..", "src");
 
 export const ADMIN = 1;
 
+/** 部署默认租户（与运行时 store/tenant.ts 的 DEFAULT_TENANT 同值） */
+export const DEFAULT_TENANT = "default";
+
+/**
+ * 带 `tenant_id` 列的表 = 租户化表（A 组）。建库时按 PRAGMA 自省后填充，
+ * 不在代码里抄一份清单——迁移口径变了这里跟着变。
+ */
+const TENANT_TABLES = new Set<string>();
+
+/** 当前请求的租户：与 oj 同源（`http.tenantId`），无请求上下文时落部署默认 */
+function currentTenant(): string {
+	const t = (globalThis as any).http?.tenantId;
+	return typeof t === "string" && t.trim() ? t.trim() : DEFAULT_TENANT;
+}
+
+function isTenantScoped(table: string): boolean {
+	return TENANT_TABLES.has(table.toLowerCase());
+}
+
+/**
+ * 裸 SQL 的租户红线段落（近似 `sql_guard: deny`）：SQL 里出现租户表却整条没有 `tenant_id`
+ * 就拒。文本级判断，只挡「整条忘了带租户」这一类，挡不住精心构造的绕过——真判据在 oj 侧。
+ */
+const TENANT_SQL_TABLE_RE = /\b(?:from|into|update|join)\s+"?([a-z_]\w*)"?/gi;
+
+function guardTenantSql(sql: string): void {
+	if (TENANT_TABLES.size === 0)
+		return;
+	const touched = [...sql.matchAll(TENANT_SQL_TABLE_RE)]
+		.map(m => m[1]!.toLowerCase())
+		.filter(t => isTenantScoped(t));
+	if (touched.length === 0 || /\btenant_id\b/i.test(sql))
+		return;
+	throw new Error(
+		`[fixture] 裸 SQL 触碰租户表 ${[...new Set(touched)].join(", ")} 但未写 tenant_id：`
+		+ "tenant.enable + sql_guard: deny 下真 oj 会拒（租户值须走参数，不拼字符串）",
+	);
+}
+
 /** 标识符加引号（保留字列名如 `order` / `group` / `count` 全按字面量处理；`表.列` 逐段加） */
 function quoteIdent(name: string): string {
 	return name.split(".").map(p => `"${p.replace(/"/g, "\"\"")}"`).join(".");
@@ -268,15 +314,25 @@ class FakeQuery {
 			return this.compileUpdate();
 		if (s.verb === "delete")
 			return this.compileDelete();
-		if (s.verb === "truncate")
-			return { sql: `DELETE FROM ${quoteIdent(s.table)}`, params: [] };
+		if (s.verb === "truncate") {
+			const tenant = this.tenantPredicate();
+			return {
+				sql: `DELETE FROM ${quoteIdent(s.table)}${tenant ? ` WHERE ${tenant.sql}` : ""}`,
+				params: tenant ? tenant.params : [],
+			};
+		}
 		return this.compileSelect(inner);
 	}
 
 	private compileInsert(): Compiled {
-		const rows = (Array.isArray(this.s.values) ? this.s.values : [this.s.values]) as Array<Record<string, unknown>>;
-		if (rows.length === 0)
+		const raw = (Array.isArray(this.s.values) ? this.s.values : [this.s.values]) as Array<Record<string, unknown>>;
+		if (raw.length === 0)
 			throw new Error("[fixture] insert 至少需要一行");
+		// 租户化表：调用方不写 tenant_id 时自动补当前租户（oj 构造器同语义——
+		// 业务代码不该自己写 tenant_id，注入失效才是最危险的失败模式）
+		const rows = isTenantScoped(this.s.table)
+			? raw.map(r => ("tenant_id" in r ? r : { ...r, tenant_id: currentTenant() }))
+			: raw;
 		const cols = Object.keys(rows[0]!);
 		for (const r of rows) {
 			if (Object.keys(r).length !== cols.length)
@@ -309,11 +365,21 @@ class FakeQuery {
 		return { sql: `DELETE FROM ${quoteIdent(this.s.table)}${where.sql}`, params: where.params };
 	}
 
-	/** where 子句（追加进既有 params，返回拼接后的片段） */
+	/** 基表租户谓词（表名/别名限定，与 oj 渲染的 `"users"."tenant_id"` 同形）；共享表返回 null */
+	private tenantPredicate(): Compiled | null {
+		if (!isTenantScoped(this.s.table))
+			return null;
+		return { sql: `${quoteIdent(this.s.alias ?? this.s.table)}.tenant_id = ?`, params: [currentTenant()] };
+	}
+
+	/** where 子句（追加进既有 params，返回拼接后的片段）；租户谓词始终参与 AND */
 	private compileWhereClause(params: unknown[]): Compiled {
-		if (this.s.wheres.length === 0)
-			return { sql: "", params };
 		const parts = this.s.wheres.map(compileWhere);
+		const tenant = this.tenantPredicate();
+		if (tenant)
+			parts.push(tenant);
+		if (parts.length === 0)
+			return { sql: "", params };
 		return {
 			sql: ` WHERE ${parts.map(p => `(${p.sql})`).join(" AND ")}`,
 			params: [...params, ...parts.flatMap(p => p.params)],
@@ -408,10 +474,24 @@ export function installDb(): any {
 			dbo.exec(readFileSync(join(dir, f), "utf8"));
 	}
 
+	// 租户化表自省：有 `tenant_id` 列即按租户隔离（迁移是唯一真相，不在夹具里抄清单）
+	TENANT_TABLES.clear();
+	for (const { name } of dbo.prepare(SQL_LIST_TABLES).all() as Array<{ name: string }>) {
+		const cols = dbo.prepare(`PRAGMA table_info(${quoteIdent(name)})`).all() as Array<{ name: string }>;
+		if (cols.some(c => c.name.toLowerCase() === "tenant_id"))
+			TENANT_TABLES.add(name.toLowerCase());
+	}
+
 	dbo.prepare("INSERT INTO users (id, username, password_hash) VALUES (?, ?, 'x')").run(ADMIN, "admin");
 
-	const query = async (sql: string, params: unknown[] = []) => dbo.prepare(sql).all(...(params as never[]));
-	const exec = async (sql: string, params: unknown[] = []) => Number(dbo.prepare(sql).run(...(params as never[])).changes);
+	const query = async (sql: string, params: unknown[] = []) => {
+		guardTenantSql(sql);
+		return dbo.prepare(sql).all(...(params as never[]));
+	};
+	const exec = async (sql: string, params: unknown[] = []) => {
+		guardTenantSql(sql);
+		return Number(dbo.prepare(sql).run(...(params as never[])).changes);
+	};
 	const table = (name: string) => new FakeQuery(dbo, name);
 	const txInstance = { query, exec, table, listTables: (prefix?: string) => listTables(dbo, prefix), isTx: true };
 	// db.tx 镜像运行时面：BEGIN/COMMIT/ROLLBACK 包裹回调（versions.ts 注释同语义）

package/templates/tests/guard.spec.ts

@@ -43,17 +43,23 @@ describe("spike 夹具冒烟：真实迁移 + 运行时全局面 + 事务", () =
 		expect(row.username).toBe("admin");
 	});
 	it("全局 db.query/exec 与运行时同面可用", async () => {
-		const rows = await db.query("SELECT id, username FROM users");
+		const rows = await db.query("SELECT id, username FROM users WHERE tenant_id = ?", ["default"]);
 		expect(rows.length).toBeGreaterThan(0);
 	});
+	it("裸 SQL 漏写 tenant_id 一律拒（sql_guard: deny 的夹具替身）", async () => {
+		await expect(db.query("SELECT id FROM users")).rejects.toThrow(/未写 tenant_id/);
+		await expect(db.exec("DELETE FROM users")).rejects.toThrow(/未写 tenant_id/);
+		// B 组共享表无 tenant_id，照旧放行
+		await expect(db.query("SELECT key FROM sys_setting")).resolves.toBeDefined();
+	});
 	it("db.tx 事务往返：提交持久化 / 回滚不留痕", async () => {
 		await db.tx(async (t) => {
-			await t.exec("INSERT INTO users (username, password_hash) VALUES ('tx-ok', 'x')");
+			await t.exec("INSERT INTO users (tenant_id, username, password_hash) VALUES ('default', 'tx-ok', 'x')");
 		});
 		const ok = dbo.prepare("SELECT COUNT(*) AS n FROM users WHERE username = 'tx-ok'").get() as { n: number };
 		expect(Number(ok.n)).toBe(1);
 		await expect(db.tx(async (t) => {
-			await t.exec("INSERT INTO users (username, password_hash) VALUES ('tx-bad', 'x')");
+			await t.exec("INSERT INTO users (tenant_id, username, password_hash) VALUES ('default', 'tx-bad', 'x')");
 			throw new Error("rollback");
 		})).rejects.toThrow("rollback");
 		const bad = dbo.prepare("SELECT COUNT(*) AS n FROM users WHERE username = 'tx-bad'").get() as { n: number };

package/templates/tests/lifecycle/deploy-smoke.spec.ts

@@ -326,27 +326,29 @@ describe("smoke 探活（D14/Q-A：health 不强制）", () => {
 		expect(r.ok).toBe(true);
 	});
 
-	it("health 401 且路径属本次新增 anonymous（restart_pending）→ 判通过 + 落待重启提示", async () => {
+	it("health 401（无凭证探针，restart_pending 常态）→ 一律判通过 + 落待重启提示", async () => {
 		await seedDeployed();
 		const r = await smoke(smCtx({
 			manifest: solManifest({ health: "/demo-solution/ping" }),
 			fetch: async () => ({ ok: false, status: 401 }),
-			deferredAnonymous: ["/demo-solution/ping"],
 		}));
 		expect(r.ok).toBe(true);
 		expect(r.message).toContain("restart_pending");
-		expect(r.message).toContain("重启宿主后生效");
+		expect(r.message).toContain("不计入失败");
 	});
 
-	it("health 401 但路径不是本次新增（已在配置里）→ 仍判失败（不放宽真失败）", async () => {
+	it("health 401 与否声明 anonymous 无关（统一 deferred，不放宽真失败靠非 401）", async () => {
+		// 旧语义按 deferredAnonymous 白名单区分是否 deferred；该字段从未被调用方赋值（死代码），
+		// 且设计明确「health 不强制、无凭证预期 401」，故改为 health 401 一律 deferred。
+		// 真失败仍由非 401（如 500，见下条）兜底，不靠 anonymous 白名单。
 		await seedDeployed();
 		const r = await smoke(smCtx({
 			manifest: solManifest({ health: "/demo-solution/ping" }),
 			fetch: async () => ({ ok: false, status: 401 }),
 			deferredAnonymous: ["/demo-solution/other"],
 		}));
-		expect(r.ok).toBe(false);
-		expect(r.message).toContain("401");
+		expect(r.ok).toBe(true);
+		expect(r.message).toContain("restart_pending");
 	});
 
 	it("health 非 2xx → 探活失败", async () => {

package/templates/tests/lifecycle/installer.spec.ts

@@ -1237,3 +1237,79 @@ describe("P1-16 接线：reconcile 不一致自动修复（重跑 setEnabled）+
 		expect(mig?.opts).toEqual({ timeoutMs: 600000 });
 	});
 });
+
+describe("冒烟探活必须自报租户头（企微代开发多租户 v3 Phase 0）", () => {
+	it("probe fetch 带 X-TENANT-ID: default —— 宿主 tenant.enable 时匿名健康端点也强制要租户头，缺即 400", async () => {
+		const seen: Array<{ url: string, headers?: Record<string, string> }> = [];
+		const t = await runInstall(makeReq({
+			fetch: async (url: string, init?: { headers?: Record<string, string> }) => {
+				seen.push({ url, headers: init?.headers });
+				return { ok: true, status: 200, arrayBuffer: async () => ARCHIVE.slice().buffer };
+			},
+		}));
+		expect(t.status).toBe("done");
+		// 探活命中的是首个非匿名路由 /demo-solution（anonymous 仅 demo-solution/ping）
+		const probe = seen.find(c => c.url === "/api/demo-solution/demo-solution");
+		expect(probe, "smoke 应对首个非匿名路由发起探活").toBeDefined();
+		expect(probe!.headers?.["X-TENANT-ID"]).toBe("default");
+	});
+
+	it("遇「缺租户头即 400」的宿主时因已自报 default 而通过（属性测试，非假绿）", async () => {
+		// 模拟宿主 tenant.enable 的硬 fail-closed：探针缺 X-TENANT-ID 即 400、带 default 即 200。
+		// 本例用 health 端点（smoke 对 health 断言 2xx）——若 smoke 没带租户头，探针必 400 → smoke 失败。
+		// 安装成功(done) 即反向证明租户头确已注入，而非靠「非 health 探活忽略 2xx」蒙混。
+		const seen: Array<{ url: string, headers?: Record<string, string> }> = [];
+		const t = await runInstall(makeReq({
+			manifest: { ...manifestFixture("0.1.0"), health: "/demo-solution/ping" },
+			fetch: async (url: string, init?: { headers?: Record<string, string> }) => {
+				seen.push({ url, headers: init?.headers });
+				// 仅对探活 URL 模拟「缺租户头即 400」；下载 CDN 等一律 200，避免误伤其他阶段。
+				if (url === "/api/demo-solution/demo-solution/ping" && init?.headers?.["X-TENANT-ID"] !== "default") {
+					return { ok: false, status: 400, arrayBuffer: async () => new ArrayBuffer(0) };
+				}
+				return { ok: true, status: 200, arrayBuffer: async () => ARCHIVE.slice().buffer };
+			},
+		}));
+		expect(t.status).toBe("done");
+		const probe = seen.find(c => c.url === "/api/demo-solution/demo-solution/ping");
+		expect(probe, "health 优先被探活").toBeDefined();
+		expect(probe!.headers?.["X-TENANT-ID"]).toBe("default");
+	});
+
+	it("health 端点声明为匿名：探针 401（restart_pending）应判 deferred 而非失败", async () => {
+		// 租户化站点上「本次新增的匿名端点要重启才生效」，探活收 401 是预期，不计入失败（设计 §4.1）。
+		// 复现 reinstall/upgrade 在隔离站点的 401 误判失败：修复前 deferredAnonymous 从未被赋值 → 误失败。
+		const t = await runInstall(makeReq({
+			manifest: {
+				...manifestFixture("0.1.0"),
+				health: "/demo-solution/ping",
+				api: { prefix: "/api/demo-solution", anonymous: ["demo-solution/ping"] },
+			},
+			fetch: async (url: string) => {
+				if (url === "/api/demo-solution/demo-solution/ping") {
+					return { ok: false, status: 401, arrayBuffer: async () => new ArrayBuffer(0) };
+				}
+				return { ok: true, status: 200, arrayBuffer: async () => ARCHIVE.slice().buffer };
+			},
+		}));
+		expect(t.status).toBe("done");
+	});
+
+	it("health 端点收非 401（如 500）：仍判失败（仅 401 转 deferred）", async () => {
+		const t = await runInstall(makeReq({
+			manifest: {
+				...manifestFixture("0.1.0"),
+				health: "/demo-solution/ping",
+				api: { prefix: "/api/demo-solution", anonymous: ["demo-solution/ping"] },
+			},
+			fetch: async (url: string) => {
+				if (url === "/api/demo-solution/demo-solution/ping") {
+					return { ok: false, status: 500, arrayBuffer: async () => new ArrayBuffer(0) };
+				}
+				return { ok: true, status: 200, arrayBuffer: async () => ARCHIVE.slice().buffer };
+			},
+		}));
+		expect(t.status).toBe("partial");
+		expect(t.stage).toBe("smoke");
+	});
+});

package/templates/tests/lifecycle/trust.spec.ts

@@ -280,7 +280,7 @@ describe("信任库运维端点（superadmin，R9）", () => {
 		await api.trust.key.del();
 		expect(last).toMatchObject({ status: 400 });
 
-		const rows = await (g.db.query as (sql: string, p?: unknown[]) => Promise<Array<Record<string, unknown>>>)("select action, target, detail from sys_oplog where action like 'solution.trust.%' order by id");
+		const rows = await (g.db.query as (sql: string, p?: unknown[]) => Promise<Array<Record<string, unknown>>>)("select action, target, detail from sys_oplog where tenant_id = ? and action like 'solution.trust.%' order by id", ["default"]);
 		expect(rows.map(r => r.action)).toEqual(["solution.trust.add", "solution.trust.revoke"]);
 		expect(rows[0]).toMatchObject({ target: "ojm.test" });
 		expect(JSON.parse(String(rows[0].detail))).toMatchObject({ key_id: "ojm.test", operator: "admin" });

package/templates/tests/query-utils.spec.ts

@@ -14,12 +14,15 @@ beforeAll(() => {
 		dbo.prepare("INSERT INTO users (username, password_hash) VALUES (?, 'x')").run(`u${String(i).padStart(3, "0")}`);
 });
 
-const LIST = "select id, username from users where 1=1";
-const COUNT = "select count(*) as c from users where 1=1";
+// 裸 SQL（paged 直通）：租户化表必须显式写 tenant_id 且走参数——tenant.enable + sql_guard: deny
+// 下缺它会被真 oj 拒（夹具的 guardTenantSql 同样拒，见 tests/fixture.ts 头注释）
+const TENANT = "default";
+const LIST = "select id, username from users where tenant_id = ?";
+const COUNT = "select count(*) as c from users where tenant_id = ?";
 
 describe("AC1-24：limit 钳制与截断标记", () => {
 	it("size 静默钳 200，truncated=true（库 301 人=夹具 admin+300）", async () => {
-		const r = await paged<any>(LIST, COUNT, [], { page: 1, size: 500 });
+		const r = await paged<any>(LIST, COUNT, [TENANT], { page: 1, size: 500 });
 		expect(r.size).toBe(200);
 		expect(r.list.length).toBe(200);
 		expect(r.total).toBe(301);
@@ -27,16 +30,16 @@ describe("AC1-24：limit 钳制与截断标记", () => {
 	});
 
 	it("末页 truncated=false", async () => {
-		const r = await paged<any>(LIST, COUNT, [], { page: 2, size: 200 });
+		const r = await paged<any>(LIST, COUNT, [TENANT], { page: 2, size: 200 });
 		expect(r.list.length).toBe(101);
 		expect(r.truncated).toBe(false);
 	});
 
 	it("缺省 page=1 / size=20；页码/尺寸非法值回落（0/负数/非数）", async () => {
-		const d = await paged<any>(LIST, COUNT, [], {});
+		const d = await paged<any>(LIST, COUNT, [TENANT], {});
 		expect(d.page).toBe(1);
 		expect(d.size).toBe(20);
-		const bad = await paged<any>(LIST, COUNT, [], { page: 0, size: -3 });
+		const bad = await paged<any>(LIST, COUNT, [TENANT], { page: 0, size: -3 });
 		expect(bad.page).toBe(1);
 		expect(bad.size).toBe(20);
 	});
@@ -54,9 +57,9 @@ describe("AC1-22：LIKE 模式与 keyword 长度红线", () => {
 	it("LIKE 元字符转义：% _ ! 原样匹配不泛化", async () => {
 		dbo.prepare("INSERT INTO users (username, password_hash) VALUES ('a%b_c!d', 'x')").run();
 		const r = await paged<any>(
-			"select id, username from users where username like ? escape '!'",
-			"select count(*) as c from users where username like ? escape '!'",
-			[likePattern("a%b_c!d")],
+			"select id, username from users where tenant_id = ? and username like ? escape '!'",
+			"select count(*) as c from users where tenant_id = ? and username like ? escape '!'",
+			[TENANT, likePattern("a%b_c!d")],
 			{ size: 10 },
 		);
 		expect(r.list.map((x: any) => x.username)).toEqual(["a%b_c!d"]);

package/templates/tests/rbac-guard.spec.ts

@@ -4,7 +4,7 @@
 /* eslint-disable test/prefer-lowercase-title -- AC 编号是验收锚点，保留大写 */
 import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 
-import { assertPermission, assertSuperAdmin, assertSystemAdmin, invalidateUser } from "../src/_platform/api/_shared/service/infra/access";
+import { assertPermission, assertSuperAdmin, assertSystemAdmin, currentAccess, invalidateUser } from "../src/_platform/api/_shared/service/infra/access";
 import { installDb } from "./fixture";
 
 let dbo: ReturnType<typeof installDb>;
@@ -151,6 +151,23 @@ describe("禁用与未认证", () => {
 		asUser(undefined);
 		await expect(assertPermission("wiki.page.edit")).rejects.toMatchObject({ status: 403 });
 	});
+
+	it("伪造租户头：token 的 sub 在本租户查无此人 → 403（不能只靠「角色为空」兜底）", async () => {
+		// 租户化后 `users` 的查询自动带 `tenant_id = 当前头值`，于是「A 企业的人带 B 企业的头」
+		// 等价于「这一行查不到」。夹具不模拟租户注入（fixture.ts 头注释已声明），
+		// 故用「行不存在」直接钉住这条分支——它就是伪造头在 SQL 层的表现。
+		asUser(987_654_321);
+		await expect(currentAccess()).rejects.toMatchObject({ status: 403 });
+		// 只要求登录态的端点（不走 assertPermission）也必须被挡住
+		await expect(assertSystemAdmin()).rejects.toMatchObject({ status: 403 });
+	});
+
+	it("用户行存在才放行登录态（对照组：同一断言换个真实 uid 即通过）", async () => {
+		const uid = mkUser("u9x");
+		bindRole(uid, "superadmin");
+		asUser(uid);
+		await expect(currentAccess()).resolves.toMatchObject({ exists: true });
+	});
 });
 
 describe("AC1-9：系统管理员断言（D11）", () => {

package/templates/tests/tenant-access-cache.spec.ts

@@ -0,0 +1,99 @@
+// BDD：判权快照缓存的租户边界（多租户 2026-10，`_platform/.../infra/access.ts`）。
+//
+// 攻击/故障形态：`access.ts` 的判权快照按 **uid 单键**缓存时，「A 企业的张三」判过权之后
+// 同一个进程再处理「B 企业的张三」的请求——后者的 `users` 行按 B 租户查不到（构造器自动
+// 注入 `tenant_id` 谓词），本应 403，但缓存里还留着 A 租户那张 `exists: true` 的快照，
+// 于是**放行**。
+//
+// oj 目前每请求重建模块实例，缓存恒不命中，所以线上看不到；但只要有一次复用
+// （常驻进程、或本工程自己的测试宿主）就是静默的跨租户放行——而这一层是伪造
+// `X-TENANT-ID` 的**唯一**服务端拦截点，它一旦放行就没有第二道了。
+// 这里把「同一 uid 换租户必须重查」钉死，顺手钉住写时失效不得漏掉别的租户。
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+
+import { currentAccess, invalidateAllUsers, invalidateUser, isSelfTenant } from "../src/_platform/api/_shared/service/infra/access";
+import { installDb } from "./fixture";
+
+const g = globalThis as any;
+let dbo: ReturnType<typeof installDb>;
+
+/** 模拟一次请求的租户头（`X-TENANT-ID` → http.tenantId）与登录态 */
+function as(tenant: string, uid?: number): void {
+	g.http = tenant ? { tenantId: tenant, user: uid == null ? {} : { id: uid } } : { user: uid == null ? {} : { id: uid } };
+}
+
+/** 在指定租户里建一个用户（业务侧永不自己写 tenant_id，这里是造数据） */
+function mkUser(tenant: string, username: string): number {
+	dbo.prepare("INSERT INTO users (tenant_id, username, password_hash) VALUES (?, ?, 'x')").run(tenant, username);
+	return (dbo.prepare("SELECT id FROM users WHERE username = ? AND tenant_id = ?").get(username, tenant) as { id: number }).id;
+}
+
+function bind(tenant: string, uid: number, role: string): void {
+	dbo.prepare("INSERT OR IGNORE INTO sys_user_role (tenant_id, user_id, role_name) VALUES (?, ?, ?)").run(tenant, uid, role);
+}
+
+beforeAll(() => {
+	dbo = installDb();
+});
+
+beforeEach(() => {
+	invalidateAllUsers();
+});
+
+afterEach(() => {
+	g.http = {};
+	dbo.exec("DELETE FROM sys_role_permission");
+	dbo.exec("DELETE FROM sys_user_role");
+	dbo.exec("DELETE FROM users WHERE username LIKE 'tk_%'");
+});
+
+describe("判权快照按 (租户, uid) 缓存", () => {
+	it("同一 uid 换到别家租户 → 查无此人（不吃上一家留下的快照）", async () => {
+		const uid = mkUser("acme", "tk_zhangsan");
+		as("acme", uid);
+		expect(await isSelfTenant()).toBe(true);
+
+		as("globex", uid);
+		expect(await isSelfTenant()).toBe(false);
+	});
+
+	it("逆时针顺序同样成立（先访问别人家，回自己家不能被判没）", async () => {
+		const uid = mkUser("acme", "tk_lisi");
+		as("globex", uid);
+		expect(await isSelfTenant()).toBe(false);
+
+		as("acme", uid);
+		expect(await isSelfTenant()).toBe(true);
+	});
+
+	it("两个租户各自的同 uid 快照互不覆盖：角色也不串台", async () => {
+		const uid = mkUser("acme", "tk_wangwu");
+		bind("acme", uid, "wiki.editor");
+		bind("globex", uid, "crm.viewer");
+
+		as("acme", uid);
+		expect((await currentAccess()).roles).toEqual(["wiki.editor"]);
+		as("globex", uid);
+		expect(await isSelfTenant()).toBe(false);
+	});
+});
+
+describe("写时失效覆盖该 uid 的全部租户快照", () => {
+	it("在别家上下文里 invalidateUser，回原租户也必须重查", async () => {
+		const uid = mkUser("acme", "tk_zhaoliu");
+		as("acme", uid);
+		expect((await currentAccess()).roles).toEqual([]);
+
+		// 直接改库（模拟别处写路径），此 uid 在 acme 的旧快照此刻已过期
+		bind("acme", uid, "wiki.editor");
+		as("acme", uid);
+		expect((await currentAccess()).roles, "未失效前读到旧快照（TTL 内缓存命中，符合预期）").toEqual([]);
+
+		// 失效发生在**别家**的上下文里 —— 不得只清当前租户那一张
+		as("globex", uid);
+		invalidateUser(uid);
+
+		as("acme", uid);
+		expect((await currentAccess()).roles).toEqual(["wiki.editor"]);
+	});
+});

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

@@ -0,0 +1,152 @@
+// BDD：伪造 `X-TENANT-ID` 的拦截面（计划 §5.7 第 1 项）。
+//
+// 攻击形态：攻击者持 A 企业的合法 token（JWT 只带 sub，不带租户），请求时把
+// `X-TENANT-ID` 改成 B 企业。oj 构造器按当前头值注入 `tenant_id`，于是「A 企业的人
+// 查 B 企业的 users」等价于**查无此行**——这是服务端唯一能看见的异常。
+//
+// 为什么必须单独钉这一层：`assertPermission` / `currentAccess()` 覆盖的是挂了权限点的
+// 端点；而通知、我的资料、人员目录这些「登录即可」的端点根本不走它们。少了这一步，
+// 伪造头的人能读到别家企业的广播通知、改别家企业的个人资料。
+//
+// 夹具自此已模拟租户注入（fixture.ts 头注释），跨租户「查不到、改不动」的地基语义由
+// tenant-isolation.spec.ts 单独钉；本文件仍用「sub 在库中不存在」来钉端点级拦截——
+// 它就是伪造头在 SQL 层的表现，且不依赖构造器能力。对照组用真实 uid 证明同一路径照常放行。
+/* eslint-disable test/prefer-lowercase-title -- 用例标题带端点路径，保留原样更易检索 */
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+
+import { invalidateUser } from "../src/_platform/api/_shared/service/infra/access";
+import notification from "../src/notification/api/api";
+import notificationDel from "../src/notification/api/del/api";
+import profile from "../src/personal-center/api/profile/api";
+import upload from "../src/personal-center/api/upload/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;
+}
+
+/** 本租户查无此人的 sub —— 伪造租户头在 SQL 层就是这个样子 */
+const FORGED = 987_654_321;
+
+beforeAll(() => {
+	dbo = installDb();
+});
+
+afterEach(() => {
+	invalidateUser(FORGED);
+	g.http = {};
+});
+
+describe("伪造租户头：通知族全部 403（6 个入口无一漏网）", () => {
+	it("GET /api/notification/notifications → 403", async () => {
+		installJson();
+		g.http = { user: { id: FORGED } };
+		await notification.notifications.get();
+		expect(out.status).toBe(403);
+	});
+
+	it("POST /api/notification/notifications/read → 403（先于 body 校验）", async () => {
+		installJson();
+		g.http = { user: { id: FORGED }, body: { id: "u:1" } };
+		await notification.notifications.read.post();
+		expect(out.status).toBe(403);
+	});
+
+	it("POST /api/notification/notifications/read-all → 403", async () => {
+		installJson();
+		g.http = { user: { id: FORGED } };
+		await notification.notifications["read-all"].post();
+		expect(out.status).toBe(403);
+	});
+
+	it("POST /api/notification/notifications/clear → 403", async () => {
+		installJson();
+		g.http = { user: { id: FORGED } };
+		await notification.notifications.clear.post();
+		expect(out.status).toBe(403);
+	});
+
+	it("POST /api/notification/push → 403（不能先按 body 回 400）", async () => {
+		installJson();
+		g.http = { user: { id: FORGED }, body: { title: "t", message: "m" } };
+		await notification.push.post();
+		expect(out.status).toBe(403);
+	});
+
+	it("POST /api/notification/push-broadcast → 403（否则可向别家企业广播）", async () => {
+		installJson();
+		g.http = { user: { id: FORGED }, body: { title: "t", message: "m" } };
+		await notification["push-broadcast"].post();
+		expect(out.status).toBe(403);
+	});
+
+	it("POST /api/notification/del → 403（否则可按 id 删别家企业的通知）", async () => {
+		installJson();
+		g.http = { user: { id: FORGED }, body: { id: "u:1" } };
+		await notificationDel.post();
+		expect(out.status).toBe(403);
+	});
+});
+
+describe("伪造租户头：个人中心写端点 403", () => {
+	it("POST /api/personal-center/profile → 403（否则「更新 0 行回 200」）", async () => {
+		installJson();
+		g.http = { user: { id: FORGED }, body: { email: "x@example.com" } };
+		await profile.post();
+		expect(out.status).toBe(403);
+	});
+
+	it("POST /api/personal-center/upload → 403（且不落 blob 垃圾文件）", async () => {
+		installJson();
+		g.http = { user: { id: FORGED }, files: [{ key: "", content_type: "image/png" }] };
+		await upload.post();
+		expect(out.status).toBe(403);
+	});
+});
+
+describe("对照组：同一路径换真实 uid 照常放行（证明 403 来自租户自洽而非误伤）", () => {
+	// 对照组不取通知列表：'noticesFor' 走 UNION，夹具渲染成 `(SELECT …) UNION ALL (SELECT …)`，
+	// sqlite 的 compound select 不接受括号（真 oj 构造器无此问题）——那是夹具的能力边界，
+	// 与本层要钉的租户拦截无关，故换同一护栏下的 read-all 作对照。
+	it("read-all 与我的资料：真实 uid → 200", async () => {
+		const uid = mkUser("tf_ok");
+		installJson();
+		g.http = { user: { id: uid }, tenantId: "default" };
+		await notification.notifications["read-all"].post();
+		expect(out.status).toBe(200);
+
+		installJson();
+		g.http = { user: { id: uid }, body: { description: "hi" } };
+		await profile.post();
+		expect(out.status).toBe(200);
+	});
+
+	it("未认证（无 http.user）仍是 401，不是 403", async () => {
+		installJson();
+		g.http = {};
+		await notification.notifications.get();
+		expect(out.status).toBe(401);
+	});
+});