@goplusvn/core 0.1.57 → 0.1.59

package/PLATFORM.md

@@ -193,6 +193,133 @@ await casUpdateById(
 )
 ```
 
+## File storage
+
+One engine, two backends: a private local directory (default) or S3/MinIO. The
+app configures it once in a dedicated `src/lib/storage.ts` and imports storage
+*only through that file* — the engine is a singleton, so importing core directly
+gives you the functions without the `configureStorage` call that arms them.
+
+```ts
+// src/lib/storage.ts — the one door
+import { configureStorage, type StorageDb } from "@goerp/core/storage"
+import { db } from "@/lib/prisma"
+
+configureStorage({ db: db as unknown as StorageDb })   // local disk: storage/files
+export * from "@goerp/core/storage"
+```
+
+Both routes are factories — the app supplies only its authorization rule:
+
+```ts
+// app/api/files/[...key]/route.ts
+export const GET = apiHandler<{ key: string[] }>(
+  createFileProxyHandler<Session>({
+    authorize: ({ key, session }) =>
+      key.startsWith("hop-dong/") ? checkPermission(session, "contract", "view") : true,
+  })
+)
+
+// app/api/upload/route.ts
+export const POST = apiHandler(createUploadHandler())   // 25MB, extension whitelist
+```
+
+`authorize` returning `false` is 403; returning `{ status: 404 }` hides the
+object's very existence. It runs *after* the key is validated, so a traversal
+attempt never reaches app code. Uploads always return `/api/files/<key>` no
+matter which backend is live, so switching to S3 later doesn't invalidate URLs
+already stored in the DB — and the local directory is private, not
+`public/uploads`: attachments are financial documents and ID scans, and a web
+root serves them to anyone with the path.
+
+S3/MinIO is opt-in because bundlers statically resolve dynamic imports — a
+lazily-imported driver would still make `aws-sdk` a hard build dependency for
+every app. It lives at its own subpath with the SDK as an *optional* peer:
+
+```ts
+import { createS3Driver } from "@goerp/core/storage/s3"
+
+configureStorage({
+  db: db as unknown as StorageDb,
+  driver: createS3Driver(),
+  requireRemote: process.env.NODE_ENV === "production",
+})
+```
+
+`requireRemote` makes a missing/broken S3 config *throw* instead of quietly
+falling back to container-local disk — that fallback "succeeds" and then loses
+every file on the next deploy. Credentials come from `system_configs`
+(`STORAGE_TYPE=s3`, `S3_ENDPOINT`, `S3_PUBLIC_ENDPOINT`, `S3_REGION`,
+`S3_BUCKET`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_REJECT_UNAUTHORIZED`), cached
+until `clearCache()`. The public endpoint is used for presigning only —
+a presigned signature is bound to the host that signed it, so signing with the
+internal endpoint yields URLs the browser cannot use.
+
+## Branch scope
+
+Multi-branch data visibility (`@goerp/core/branch-scope`). Two layers, on
+purpose — the second exists because the first is something a new route can
+simply forget.
+
+**Layer 1 — explicit filtering.** Every page/route/service that lists records
+does `const scope = await getBranchScope(session)` then spreads
+`scopedBranchWhere(scope)` into its `where`. `scopedBranchWhere` returns `{}`
+for view-all users, so there is no branching at the call site. Related helpers:
+`canAccessBranch(scope, row.branchId)` for detail pages, `clampBranchFilter`
+for a branch filter the client sent (out-of-scope selections collapse to the
+sentinel — 0 rows, never "no filter"), `clampIdFilter` for branch-owned things
+like warehouses. Records with `branchId: null` are treated as shared and stay
+visible to everyone.
+
+**Layer 2 — the safety net.** `createBranchGuardExtension({ models })` is a
+Prisma extension that ANDs the branch condition onto read operations
+(`findMany`, `findFirst`, `findFirstOrThrow`, `count`, `aggregate`, `groupBy`)
+for the declared models. It only acts inside a request context opened by the
+app's api-handler, so RSC pages, cron, webhooks and scripts see unfiltered data
+and must use layer 1. `findUnique*` is deliberately not guarded (its `where`
+only takes unique fields) — guard detail pages with `canAccessBranch`.
+
+Wiring, all in the app's composition root:
+
+```ts
+// src/lib/branch-scope.ts — the ONE door; nothing else imports the core module
+configureBranchScope<Session>({
+  getUserId: (session) => session.user?.id,
+  canViewAll: (session) => session.user.roles.includes("admin"),
+  getAllowedBranchIds: (session) => session.user.branches, // or pass `db` instead
+})
+
+// src/lib/prisma.ts
+db = rawClient.$extends(createBranchGuardExtension({ models: ["Invoice"] }))
+
+// src/lib/api-handler.ts (middleware) — resolve is lazy, so a request that
+// never touches a guarded model costs nothing
+runWithBranchScope({ resolve: () => getBranchScope(session) }, () => next())
+```
+
+Either give `configureBranchScope` a `db` (it reads `user_branches`) or
+`getAllowedBranchIds` when the session already carries the list.
+
+Three traps, each of which has cost a real incident:
+
+- **A guarded model MUST have a `branchId` column**, or you must route it
+  through a relation: `buildWhere: (model, scope) => model === "GoodsReceipt" ?
+  scopedBranchWhere(scope, "warehouse") : null`. Declare a model without the
+  column and Prisma throws a validation error on *every* read a scoped user
+  makes — a blank app, not a few missing rows.
+- **Document numbering must escape the guard.** `MAX(number)` filtered by
+  branch produces duplicate numbers and a unique violation. Wrap those queries
+  in `runWithoutBranchScope(...)`.
+- **"No branches assigned" means zero rows, not everything.** That is what
+  `NO_BRANCH_ACCESS` encodes; an empty `in: []` is ambiguous in Prisma and one
+  mistake there exposes the whole table.
+
+`runWithBranchScope` / `runWithoutBranchScope` pin a returned thenable to the
+context before handing it back, so `runWithoutBranchScope(() => db.doc.aggregate(…))`
+works even though a PrismaPromise does not run until it is awaited — otherwise
+the query would execute wherever the caller happened to await it, i.e. in the
+wrong scope.
+
 ## Utils
 
 `@goerp/core/utils` (formatCurrency, formatDate, cn, …) plus the granular:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goplusvn/core",
   "description": "GoPlusVN Platform Kit - ERP kernel: layout, RBAC, CRUD, multi-tenant, system pages",
-  "version": "0.1.57",
+  "version": "0.1.59",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -93,17 +93,25 @@
     "./crud/pages/entity-crud-page": "./src/crud/pages/entity-crud-page.tsx",
     "./auth/auth-service": "./src/auth/auth-service.ts",
     "./package.json": "./package.json",
-    "./providers/brand-theme": "./src/providers/brand-theme.ts"
+    "./providers/brand-theme": "./src/providers/brand-theme.ts",
+    "./storage": "./src/storage/index.ts",
+    "./storage/s3": "./src/storage/s3/index.ts"
   },
   "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/s3-request-presigner": "^3.0.0",
+    "@smithy/node-http-handler": "^4.0.0",
     "next": ">=14.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1101.0",
+    "@aws-sdk/s3-request-presigner": "^3.1101.0",
     "@eslint/compat": "1.2.7",
     "@eslint/js": "9.18.0",
     "@next/eslint-plugin-next": "16.0.3",
+    "@smithy/node-http-handler": "^4.9.13",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
     "@types/bcryptjs": "^2.4.6",
@@ -198,6 +206,17 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "zod": "3.23.8"
   },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "@smithy/node-http-handler": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "NODE_OPTIONS='--max-old-space-size=10240' tsup",
     "dev": "tsup --watch",

package/src/branch-scope/__tests__/branch-scope.test.ts

@@ -0,0 +1,288 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  getBranchScopeContext,
+  resolveAmbientBranchScope,
+  runWithBranchScope,
+  runWithoutBranchScope,
+  type BranchScopeContext,
+} from "../context";
+import { createBranchGuardExtension } from "../guard";
+import {
+  canAccessBranch,
+  clampBranchFilter,
+  clampIdFilter,
+  configureBranchScope,
+  getBranchScope,
+  scopedBranchWhere,
+} from "../scope";
+import { NO_BRANCH_ACCESS, type BranchScope } from "../types";
+
+const scoped: BranchScope = { canViewAll: false, allowedBranchIds: ["b1", "b2"] };
+const viewAll: BranchScope = { canViewAll: true };
+
+interface FakeSession {
+  id?: string;
+  admin?: boolean;
+}
+
+function configure(rows: { branchId: string | null }[]) {
+  const findMany = vi.fn(async () => rows);
+  configureBranchScope<FakeSession>({
+    db: { userBranch: { findMany } },
+    getUserId: (s) => s.id,
+    canViewAll: (s) => Boolean(s.admin),
+  });
+  return findMany;
+}
+
+describe("getBranchScope", () => {
+  it("người xem-tất không tốn truy vấn user_branches", async () => {
+    const findMany = configure([]);
+    expect(await getBranchScope({ id: "u1", admin: true })).toEqual({
+      canViewAll: true,
+    });
+    expect(findMany).not.toHaveBeenCalled();
+  });
+
+  it("lấy đúng chi nhánh được gán", async () => {
+    configure([{ branchId: "b1" }, { branchId: "b2" }]);
+    expect(await getBranchScope({ id: "u1" })).toEqual({
+      canViewAll: false,
+      allowedBranchIds: ["b1", "b2"],
+    });
+  });
+
+  it("chưa gán chi nhánh nào → sentinel = thấy 0 dòng, KHÔNG phải thấy tất", async () => {
+    configure([]);
+    expect(await getBranchScope({ id: "u1" })).toEqual({
+      canViewAll: false,
+      allowedBranchIds: [NO_BRANCH_ACCESS],
+    });
+  });
+
+  it("session không có userId → sentinel (không tra DB bằng undefined)", async () => {
+    const findMany = configure([{ branchId: "b1" }]);
+    expect(await getBranchScope({})).toEqual({
+      canViewAll: false,
+      allowedBranchIds: [NO_BRANCH_ACCESS],
+    });
+    expect(findMany).not.toHaveBeenCalled();
+  });
+});
+
+describe("scopedBranchWhere", () => {
+  it("xem tất → không thêm điều kiện", () => {
+    expect(scopedBranchWhere(viewAll)).toEqual({});
+  });
+
+  it("có phạm vi → CN được gán + bản ghi chưa gắn CN (dùng chung)", () => {
+    expect(scopedBranchWhere(scoped)).toEqual({
+      OR: [{ branchId: { in: ["b1", "b2"] } }, { branchId: null }],
+    });
+  });
+
+  it("scope qua quan hệ cho model không có cột branchId", () => {
+    expect(scopedBranchWhere(scoped, "warehouse")).toEqual({
+      OR: [
+        { warehouse: { branchId: { in: ["b1", "b2"] } } },
+        { warehouse: { branchId: null } },
+      ],
+    });
+  });
+});
+
+describe("canAccessBranch", () => {
+  it("xem tất → qua hết", () => {
+    expect(canAccessBranch(viewAll, "x")).toBe(true);
+  });
+  it("bản ghi không gắn CN = dùng chung", () => {
+    expect(canAccessBranch(scoped, null)).toBe(true);
+  });
+  it("đúng/sai theo danh sách được gán", () => {
+    expect(canAccessBranch(scoped, "b1")).toBe(true);
+    expect(canAccessBranch(scoped, "x")).toBe(false);
+  });
+});
+
+describe("kẹp bộ lọc client gửi lên", () => {
+  it("clampBranchFilter: giữ nguyên khi xem tất, lọc bỏ CN ngoài phạm vi", () => {
+    expect(clampBranchFilter(["x"], viewAll)).toEqual(["x"]);
+    expect(clampBranchFilter(["b1", "x"], scoped)).toEqual(["b1"]);
+  });
+
+  it("clampBranchFilter: toàn bộ ngoài phạm vi → sentinel, không rơi về không-lọc", () => {
+    expect(clampBranchFilter(["x", "y"], scoped)).toEqual([NO_BRANCH_ACCESS]);
+  });
+
+  it("clampBranchFilter: không lọc gì → undefined (phạm vi đã lo)", () => {
+    expect(clampBranchFilter(undefined, scoped)).toBeUndefined();
+    expect(clampBranchFilter("", scoped)).toBeUndefined();
+  });
+
+  it("clampIdFilter: ngoài danh sách cho phép → sentinel", () => {
+    expect(clampIdFilter(["w1", "x"], ["w1", "w2"])).toEqual(["w1"]);
+    expect(clampIdFilter(["x"], ["w1"])).toEqual([NO_BRANCH_ACCESS]);
+  });
+});
+
+describe("context", () => {
+  it("ngoài context → undefined (extension bất động cho cron/script)", () => {
+    expect(getBranchScopeContext()).toBeUndefined();
+    expect(resolveAmbientBranchScope()).toBeUndefined();
+  });
+
+  it("resolve lười và cache trong 1 request", async () => {
+    const resolve = vi.fn(async () => scoped);
+    await runWithBranchScope({ resolve }, async () => {
+      expect(resolve).not.toHaveBeenCalled();
+      expect(await resolveAmbientBranchScope()).toBe(scoped);
+      expect(await resolveAmbientBranchScope()).toBe(scoped);
+      expect(resolve).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("context sống qua await bên trong (PrismaPromise phải await TRONG context)", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, async () => {
+      await Promise.resolve();
+      expect(getBranchScopeContext()).toBeDefined();
+    });
+  });
+
+  it("runWithoutBranchScope thoát guard rồi trả lại context", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, async () => {
+      await runWithoutBranchScope(async () => {
+        await Promise.resolve();
+        expect(getBranchScopeContext()).toBeUndefined();
+        expect(resolveAmbientBranchScope()).toBeUndefined();
+      });
+      expect(getBranchScopeContext()).toBeDefined();
+    });
+  });
+
+  /**
+   * PrismaPromise lười: truy vấn chạy ở lần `.then()` đầu tiên, không phải lúc
+   * gọi `db.receipt.count()`. Giả lập đúng như vậy để chốt rằng callback KHÔNG
+   * async cũng chạy trong đúng phạm vi.
+   */
+  function lazyQuery(): Promise<BranchScopeContext | undefined> {
+    let started: Promise<BranchScopeContext | undefined> | undefined;
+    const thenable: PromiseLike<BranchScopeContext | undefined> = {
+      then(onFulfilled, onRejected) {
+        // Ngữ cảnh được chốt tại đây — chỗ đầu tiên ai đó await.
+        started ??= Promise.resolve(getBranchScopeContext());
+        return started.then(onFulfilled, onRejected);
+      },
+    };
+    // PrismaPromise cũng khai kiểu Promise nhưng chỉ chạy ở `.then` đầu tiên.
+    return thenable as Promise<BranchScopeContext | undefined>;
+  }
+
+  it("callback KHÔNG async trả PrismaPromise vẫn chạy TRONG context", async () => {
+    const ctx = await runWithBranchScope({ resolve: async () => scoped }, () =>
+      lazyQuery(),
+    );
+    expect(ctx).toBeDefined();
+  });
+
+  it("runWithoutBranchScope: callback KHÔNG async vẫn thoát guard", async () => {
+    const ctx = await runWithBranchScope(
+      { resolve: async () => scoped },
+      async () => runWithoutBranchScope(() => lazyQuery()),
+    );
+    expect(ctx).toBeUndefined();
+  });
+
+  it("giá trị đồng bộ đi qua nguyên vẹn (không bị bọc thành promise)", () => {
+    expect(runWithoutBranchScope(() => 42)).toBe(42);
+  });
+});
+
+describe("createBranchGuardExtension", () => {
+  const ext = createBranchGuardExtension({
+    models: ["Receipt", "GoodsReceipt"],
+    buildWhere: (model, scope) =>
+      model === "GoodsReceipt" ? scopedBranchWhere(scope, "warehouse") : null,
+  });
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const run = ext.query.$allModels.$allOperations as (a: any) => Promise<any>;
+
+  let seen: unknown;
+  const query = vi.fn(async (args: unknown) => {
+    seen = args;
+    return "ok";
+  });
+
+  beforeEach(() => {
+    seen = undefined;
+    query.mockClear();
+  });
+
+  const call = (model: string, operation: string, args: unknown) =>
+    run({ model, operation, args, query });
+
+  it("model ngoài danh sách → đi thẳng", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, () =>
+      call("Customer", "findMany", { where: { name: "a" } }),
+    );
+    expect(seen).toEqual({ where: { name: "a" } });
+  });
+
+  it("thao tác ghi và findUnique → không đụng vào", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, async () => {
+      await call("Receipt", "findUnique", { where: { id: "r1" } });
+      expect(seen).toEqual({ where: { id: "r1" } });
+      await call("Receipt", "update", { where: { id: "r1" }, data: {} });
+      expect(seen).toEqual({ where: { id: "r1" }, data: {} });
+    });
+  });
+
+  it("ngoài context (cron/script) → không cắt dữ liệu", async () => {
+    await call("Receipt", "findMany", { where: { a: 1 } });
+    expect(seen).toEqual({ where: { a: 1 } });
+  });
+
+  it("xem tất → không thêm điều kiện", async () => {
+    await runWithBranchScope({ resolve: async () => viewAll }, () =>
+      call("Receipt", "findMany", { where: { a: 1 } }),
+    );
+    expect(seen).toEqual({ where: { a: 1 } });
+  });
+
+  it("AND thêm điều kiện chi nhánh, GIỮ nguyên where cũ", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, () =>
+      call("Receipt", "findMany", { where: { status: "paid" } }),
+    );
+    expect(seen).toEqual({
+      where: {
+        AND: [
+          { status: "paid" },
+          { OR: [{ branchId: { in: ["b1", "b2"] } }, { branchId: null }] },
+        ],
+      },
+    });
+  });
+
+  it("không có where sẵn → guard trở thành where", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, () =>
+      call("Receipt", "count", {}),
+    );
+    expect(seen).toEqual({
+      where: { OR: [{ branchId: { in: ["b1", "b2"] } }, { branchId: null }] },
+    });
+  });
+
+  it("buildWhere riêng cho model không có cột branchId (chèn cột không tồn tại = Prisma ném lỗi cho MỌI truy vấn)", async () => {
+    await runWithBranchScope({ resolve: async () => scoped }, () =>
+      call("GoodsReceipt", "findMany", {}),
+    );
+    expect(seen).toEqual({
+      where: {
+        OR: [
+          { warehouse: { branchId: { in: ["b1", "b2"] } } },
+          { warehouse: { branchId: null } },
+        ],
+      },
+    });
+  });
+});

package/src/branch-scope/context.ts

@@ -0,0 +1,66 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import type { BranchScope } from "./types";
+
+/**
+ * Context của lưới an toàn lớp 2. `apiHandler` mở context cho MỌI request đã
+ * xác thực; extension branch-guard đọc ở đây.
+ *
+ * Phạm vi được resolve LƯỜI — lần đầu một model bị guard thực sự được đọc.
+ * Request không đụng model nào bị guard thì không tốn thêm truy vấn nào.
+ *
+ * File này cố ý không import phần scope: composition root của app tiêm hàm
+ * `resolve` vào lúc mở context, nhờ vậy context không kéo theo prisma và không
+ * tạo vòng import.
+ */
+
+export interface BranchScopeContext {
+  resolve: () => Promise<BranchScope>;
+  /** Cache trong phạm vi 1 request — extension gán ở lần resolve đầu. */
+  cached?: Promise<BranchScope>;
+}
+
+const store = new AsyncLocalStorage<BranchScopeContext>();
+
+/**
+ * PrismaPromise là LƯỜI: truy vấn chỉ thật sự chạy ở lần `.then()` đầu tiên.
+ * `run(ctx, () => db.receipt.count())` trả promise chưa chạy ra ngoài, người gọi
+ * `await` bên ngoài → truy vấn chạy NGOÀI context → guard im lặng không lọc
+ * (và với `exit` thì ngược lại: truy vấn cần toàn cục lại bị lọc → trùng số
+ * phiếu). Gọi `.then` ngay tại đây, khi còn ở trong/ngoài context đúng như ý,
+ * để việc chạy được ghim vào đúng phạm vi — bất kể người gọi await ở đâu.
+ */
+function pinToCurrentContext<T>(result: T): T {
+  const thenable = result as { then?: unknown };
+  if (typeof thenable?.then !== "function") return result;
+  return (result as unknown as Promise<unknown>).then((value) => value) as T;
+}
+
+export function runWithBranchScope<T>(
+  context: BranchScopeContext,
+  fn: () => T | Promise<T>,
+): T | Promise<T> {
+  return store.run(context, () => pinToCurrentContext(fn()));
+}
+
+export function getBranchScopeContext(): BranchScopeContext | undefined {
+  return store.getStore();
+}
+
+/** Phạm vi của request hiện tại (resolve + cache); undefined khi ở ngoài context. */
+export function resolveAmbientBranchScope(): Promise<BranchScope> | undefined {
+  const ctx = store.getStore();
+  if (!ctx) return undefined;
+  ctx.cached ??= ctx.resolve();
+  return ctx.cached;
+}
+
+/**
+ * Chạy `fn` NGOÀI lưới guard — cho truy vấn hạ tầng mà kết quả phải toàn cục
+ * bất kể phạm vi user. Ca kinh điển: đánh số phiếu (`MAX(number)` bị lọc theo
+ * chi nhánh là sinh trùng số → lỗi unique). Mọi `await` bên trong đều thoát
+ * guard, nên chỉ bọc đúng truy vấn cần toàn cục, đừng bọc cả handler.
+ */
+export function runWithoutBranchScope<T>(fn: () => T): T {
+  return store.exit(() => pinToCurrentContext(fn()));
+}

package/src/branch-scope/guard.ts

@@ -0,0 +1,100 @@
+import { resolveAmbientBranchScope } from "./context";
+import { scopedBranchWhere } from "./scope";
+
+import type { BranchScope } from "./types";
+
+/**
+ * LỚP 2 — lưới an toàn ở tầng ORM (mô hình Odoo/NocoBase): route mới quên lọc
+ * chi nhánh thì vẫn không lộ dữ liệu.
+ *
+ * Chỉ chạm thao tác ĐỌC, chỉ trên model được khai, và chỉ khi có
+ * BranchScopeContext — ngoài context (RSC page, cron, webhook, script) extension
+ * bất động, nên tác vụ nền không bị cắt dữ liệu bất ngờ.
+ *
+ *   db.$extends(createBranchGuardExtension({
+ *     models: ["Receipt", "Expense", "CashCount"],
+ *     // model không có cột branchId thì khai đường đi riêng:
+ *     buildWhere: (model, scope) =>
+ *       model === "GoodsReceipt" ? scopedBranchWhere(scope, "warehouse") : null,
+ *   }))
+ *
+ * CẢNH BÁO: model đưa vào `models` PHẢI có cột branchId, hoặc phải có nhánh
+ * riêng trong `buildWhere`. Chèn điều kiện lên cột không tồn tại là Prisma ném
+ * validation error cho MỌI thao tác đọc của user bị scope — nghĩa là hỏng cả
+ * nghiệp vụ, không chỉ hỏng bộ lọc.
+ */
+
+export interface BranchGuardOptions {
+  /** Tên model Prisma (đúng chữ hoa/thường như trong schema). */
+  models: string[];
+  /**
+   * Điều kiện guard riêng theo model; trả `null` để dùng mặc định (cột
+   * branchId trực tiếp + cho phép null = dùng chung).
+   */
+  buildWhere?: (
+    model: string,
+    scope: BranchScope,
+  ) => Record<string, unknown> | null;
+  /** Mặc định: các thao tác đọc nhiều dòng. */
+  operations?: string[];
+}
+
+/**
+ * findUnique* cố ý không guard: `where` của nó chỉ nhận unique field, chèn thêm
+ * điều kiện là Prisma từ chối. Trang chi tiết guard bằng `canAccessBranch`.
+ * Mutation cũng không guard — create ghi vào chi nhánh của user, update/delete
+ * đi qua kiểm tra quyền riêng.
+ */
+const DEFAULT_OPERATIONS = [
+  "findMany",
+  "findFirst",
+  "findFirstOrThrow",
+  "count",
+  "aggregate",
+  "groupBy",
+];
+
+export function createBranchGuardExtension(options: BranchGuardOptions) {
+  const models = new Set(options.models);
+  const operations = new Set(options.operations ?? DEFAULT_OPERATIONS);
+  const buildWhere = options.buildWhere;
+
+  return {
+    name: "branch-guard",
+    query: {
+      $allModels: {
+        // Chữ ký thật do Prisma sinh theo schema của từng app; khai chặt ở core
+        // sẽ không assignable ở phía app (kiểu hẹp hơn, contravariance).
+        /* eslint-disable @typescript-eslint/no-explicit-any */
+        async $allOperations({
+          model,
+          operation,
+          args,
+          query,
+        }: {
+          model?: string;
+          operation: string;
+          args: any;
+          query: (args: any) => Promise<any>;
+        }): Promise<any> {
+          if (!model || !models.has(model)) return query(args);
+          if (!operations.has(operation)) return query(args);
+
+          const scopePromise = resolveAmbientBranchScope();
+          if (!scopePromise) return query(args);
+
+          const scope = await scopePromise;
+          if (scope.canViewAll) return query(args);
+
+          const guard = buildWhere?.(model, scope) ?? scopedBranchWhere(scope);
+          const prevWhere = args?.where;
+          return query({
+            ...args,
+            where: prevWhere ? { AND: [prevWhere, guard] } : guard,
+          });
+        },
+        /* eslint-enable @typescript-eslint/no-explicit-any */
+      },
+    },
+  };
+}

package/src/branch-scope/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Phạm vi dữ liệu theo chi nhánh — hai lớp:
+ *
+ *   Lớp 1 (tường minh): `getBranchScope(session)` + `scopedBranchWhere(scope)`
+ *   trong page/route/service. Đây mới là lớp làm việc chính.
+ *
+ *   Lớp 2 (lưới an toàn): `createBranchGuardExtension` cắm vào Prisma, tự AND
+ *   điều kiện chi nhánh cho thao tác đọc trên model được khai — cứu chỗ quên.
+ *
+ * App cấu hình một lần ở composition root và import phạm vi qua đúng file đó
+ * (`src/lib/branch-scope.ts`), giống kho tập tin: engine là singleton, import
+ * thẳng từ core sẽ lấy được hàm nhưng bỏ lỡ lời gọi cấu hình.
+ */
+export {
+  configureBranchScope,
+  canViewAllBranches,
+  getBranchScope,
+  canAccessBranch,
+  scopedBranchWhere,
+  clampBranchFilter,
+  clampIdFilter,
+} from "./scope";
+
+export {
+  runWithBranchScope,
+  getBranchScopeContext,
+  resolveAmbientBranchScope,
+  runWithoutBranchScope,
+  type BranchScopeContext,
+} from "./context";
+
+export {
+  createBranchGuardExtension,
+  type BranchGuardOptions,
+} from "./guard";
+
+export {
+  NO_BRANCH_ACCESS,
+  type BranchScope,
+  type BranchScopeConfig,
+  type BranchScopeDb,
+} from "./types";