@goplusvn/core 0.1.56 → 0.1.58

package/PLATFORM.md

@@ -193,6 +193,68 @@ 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.
+
 ## 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.56",
+  "version": "0.1.58",
   "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",
@@ -119,7 +127,6 @@
     "eslint-plugin-react-hooks": "^7.0.1",
     "globals": "16.5.0",
     "jsdom": "^27.2.0",
-    "next-auth": "4.24.11",
     "tsup": "^8.5.1",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.50.1",
@@ -199,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/auth/__tests__/proxy-gate.test.ts

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+// Đọc theo cwd chứ không theo import.meta.url: môi trường test là jsdom nên
+// import.meta.url là URL http, fileURLToPath ném "URL must be of scheme file".
+const source = readFileSync(resolve(process.cwd(), "src/auth/proxy-gate.ts"), "utf8")
+  // Bỏ chú thích: phần header có ví dụ dùng, trong đó cũng có chữ `import`.
+  .replace(/\/\*[\s\S]*?\*\//g, "")
+  .replace(/^\s*\/\/.*$/gm, "");
+
+describe("proxy-gate không kéo theo thư viện auth nào", () => {
+  // Bẫy đã trả giá: proxy-gate từng `await import("next-auth/jwt")` trong nhánh
+  // mặc định. Bundler phân giải TĨNH cả dynamic import, nên mọi app Better Auth
+  // (không cài next-auth) đều gãy middleware bằng "Module not found" — mà trong
+  // workspace này thì không lộ, vì next-auth nằm ở devDependencies của core.
+  // Middleware chạy ở Edge: đừng thêm import nào không phải next/server.
+  it("chỉ import next/server", () => {
+    const specifiers = [
+      ...source.matchAll(/(?:^|\s)import\s+(?:type\s+)?[^"']*from\s*["']([^"']+)["']/gm),
+      ...source.matchAll(/\bimport\(\s*["']([^"']+)["']\s*\)/g),
+    ].map((m) => m[1]);
+
+    expect([...new Set(specifiers)].sort()).toEqual(["next/server"]);
+  });
+});

package/src/auth/proxy-gate.ts

@@ -1,7 +1,7 @@
 // @goerp/core/auth/proxy-gate — server-only request-gate for the Next.js
 // proxy/middleware. Default-DENY authentication (authN); route-level authZ still
 // happens via getCrudPermissions/checkPermission. Isolated in its own subpath so
-// `next/server` + `next-auth/jwt` never leak into client bundles via the auth barrel.
+// `next/server` never leaks into client bundles via the auth barrel.
 //
 // Usage (app side):
 //   // src/proxy.ts
@@ -14,7 +14,7 @@ import { NextResponse } from "next/server";
 import type { NextRequest } from "next/server";
 
 export interface AuthProxyOptions {
-  /** API prefixes served without a session (NextAuth + public). Default: /api/auth, /api/public. */
+  /** API prefixes served without a session (auth handler + public). Default: /api/auth, /api/public. */
   publicApiPrefixes?: string[];
   /** Pages reachable while logged out. Default: /sign-in. */
   publicPages?: string[];
@@ -22,33 +22,49 @@ export interface AuthProxyOptions {
   signInPath?: string;
   /** Where to send a logged-in user who hits a guest page. Default: "/". */
   homePath?: string;
-  /** Override token reader (tests / custom JWT). Default: next-auth getToken. */
+  /**
+   * Session reader. STRONGLY recommended — pass the one your auth library ships
+   * (Better Auth: `getSessionCookie` from "better-auth/cookies"; NextAuth:
+   * `getToken` from "next-auth/jwt"). Default: presence of a known session
+   * cookie, see SESSION_COOKIE_NAMES.
+   */
   getToken?: (req: NextRequest) => Promise<unknown | null>;
 }
 
 const startsWithAny = (pathname: string, list: string[]) =>
   list.some((p) => pathname === p || pathname.startsWith(`${p}/`));
 
+/**
+ * Cookie tên gì thì coi như "có phiên" — dùng cho trường hợp app không truyền
+ * getToken. Middleware chạy ở Edge nên đây CHỈ là rào authN thô; chữ ký/hạn
+ * dùng vẫn do từng route kiểm qua getSession(). Không import next-auth ở đây:
+ * bundler phân giải tĩnh cả `await import()`, nên một dòng import next-auth
+ * trong nhánh chết cũng đủ làm mọi app Better Auth gãy middleware bằng
+ * "Module not found: Can't resolve 'next-auth/jwt'".
+ */
+const SESSION_COOKIE_NAMES = [
+  "better-auth.session_token",
+  "__Secure-better-auth.session_token",
+  "next-auth.session-token",
+  "__Secure-next-auth.session-token",
+  "authjs.session-token",
+  "__Secure-authjs.session-token",
+];
+
 export function createAuthProxy(options: AuthProxyOptions = {}) {
   const publicApiPrefixes = options.publicApiPrefixes ?? ["/api/auth", "/api/public"];
   const publicPages = options.publicPages ?? ["/sign-in"];
   const signInPath = options.signInPath ?? "/sign-in";
   const homePath = options.homePath ?? "/";
-  // next-auth chỉ được LAZY-load khi app không truyền getToken riêng — app đã
-  // sang Better Auth (không cài next-auth) sẽ không dính module-not-found lúc
-  // import proxy-gate (trước đây import top-level, next-auth lại chỉ nằm ở
-  // devDependencies của core).
   const readToken =
     options.getToken ??
-    (async (req: NextRequest) => {
-      const { getToken } = await import("next-auth/jwt");
-      return getToken({ req });
-    });
+    (async (req: NextRequest) =>
+      SESSION_COOKIE_NAMES.some((name) => req.cookies.has(name)) ? { cookie: true } : null);
 
   return async function proxy(request: NextRequest) {
     const { pathname, search } = request.nextUrl;
 
-    // API routes that authenticate themselves (NextAuth) or are public → pass.
+    // API routes that authenticate themselves (the auth handler) or are public → pass.
     if (startsWithAny(pathname, publicApiPrefixes)) return NextResponse.next();
 
     const token = await readToken(request);

package/src/storage/__tests__/keys.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  InvalidStorageKeyError,
+  assertSafeKey,
+  contentTypeFor,
+  fileExtension,
+  isSafeKey,
+  safeFileName,
+} from "../keys";
+
+describe("assertSafeKey", () => {
+  // Key đến từ URL `/api/files/<key>` — người dùng điều khiển hoàn toàn.
+  it.each([
+    "../../etc/passwd",
+    "uploads/../../secret.pdf",
+    "/etc/passwd",
+    "uploads\\win.pdf",
+    "uploads/a\0b.pdf",
+    "",
+  ])("từ chối %j", (key) => {
+    expect(() => assertSafeKey(key)).toThrow(InvalidStorageKeyError);
+    expect(isSafeKey(key)).toBe(false);
+  });
+
+  it("cho qua key thường", () => {
+    expect(assertSafeKey("uploads/20260801/hoa_don_123.pdf")).toBe(
+      "uploads/20260801/hoa_don_123.pdf",
+    );
+  });
+});
+
+describe("safeFileName", () => {
+  it("giữ dấu tiếng Việt", () => {
+    expect(safeFileName("Hợp đồng số 12.pdf")).toBe("Hợp_đồng_số_12.pdf");
+  });
+
+  it("bỏ đường dẫn đính kèm trong tên", () => {
+    expect(safeFileName("../../evil.png")).toBe("evil.png");
+    expect(safeFileName("C:\\Users\\a\\b.png")).toBe("b.png");
+  });
+
+  it("hạ chữ thường phần mở rộng", () => {
+    expect(safeFileName("BAO_CAO.XLSX")).toBe("BAO_CAO.xlsx");
+  });
+
+  it("tên rỗng vẫn ra tên dùng được", () => {
+    expect(safeFileName("")).toBe("file");
+  });
+});
+
+describe("fileExtension / contentTypeFor", () => {
+  it("lấy đuôi ở phần tên cuối, không phải ở thư mục", () => {
+    expect(fileExtension("a.pdf/b")).toBe("");
+    expect(fileExtension("uploads/2026/bao-cao.XLSX")).toBe("xlsx");
+  });
+
+  it("đuôi lạ trả undefined để nơi gọi tự quyết", () => {
+    expect(contentTypeFor("a.exe")).toBeUndefined();
+    expect(contentTypeFor("a.pdf")).toBe("application/pdf");
+  });
+});

package/src/storage/__tests__/no-aws-in-barrel.test.ts

@@ -0,0 +1,45 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+/**
+ * Ratchet: `@goerp/core/storage` phải chạy được khi app KHÔNG cài aws-sdk.
+ *
+ * Bẫy đã trả giá một lần ở proxy-gate: bundler phân giải TĨNH cả
+ * `await import()`, nên chỉ cần một dòng import gói không cài trong nhánh chết
+ * là app gãy build bằng "Module not found". Driver S3 phải ở `storage/s3/`
+ * (subpath riêng), tuyệt đối không rò vào barrel.
+ */
+
+// Đọc theo cwd: môi trường test là jsdom nên import.meta.url là URL http,
+// fileURLToPath sẽ ném "URL must be of scheme file".
+const STORAGE_DIR = resolve(process.cwd(), "src/storage");
+
+function filesInBarrel(dir: string, acc: string[] = []): string[] {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    // `s3/` là nơi ĐƯỢC PHÉP dùng aws-sdk; __tests__ không vào bundle app.
+    if (entry.isDirectory()) {
+      if (entry.name === "s3" || entry.name === "__tests__") continue;
+      filesInBarrel(join(dir, entry.name), acc);
+      continue;
+    }
+    if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
+      acc.push(join(dir, entry.name));
+    }
+  }
+  return acc;
+}
+
+describe("barrel storage không kéo theo aws-sdk", () => {
+  it("không file nào ngoài storage/s3 nhắc tới @aws-sdk/@smithy", () => {
+    const offenders = filesInBarrel(STORAGE_DIR).filter((file) => {
+      const source = readFileSync(file, "utf8")
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/^\s*\/\/.*$/gm, "");
+      return /["'](@aws-sdk|@smithy)\//.test(source);
+    });
+
+    expect(offenders).toEqual([]);
+  });
+});

package/src/storage/__tests__/storage-service.test.ts

@@ -0,0 +1,312 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createFileProxyHandler } from "../file-proxy";
+import {
+  clearStorageCache,
+  configureStorage,
+  deleteFile,
+  getFile,
+  getPresignedUrl,
+  getPublicUrl,
+  isRemoteStorageEnabled,
+  listObjects,
+  putFile,
+} from "../storage-service";
+import { createUploadHandler } from "../upload-handler";
+import { StorageNotFoundError, type StorageDriver } from "../types";
+
+/** DB giả: trả đúng các dòng system_configs mà engine hỏi. */
+function fakeDb(rows: Record<string, string> = {}) {
+  return {
+    systemConfig: {
+      findMany: vi.fn(async () =>
+        Object.entries(rows).map(([key, value]) => ({ key, value })),
+      ),
+    },
+  };
+}
+
+let dir: string;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "goerp-storage-"));
+});
+
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe("chế độ local (mặc định)", () => {
+  beforeEach(() => {
+    configureStorage({ db: fakeDb(), localDir: dir });
+  });
+
+  it("không có driver thì không hỏi DB làm gì", async () => {
+    const db = fakeDb({ STORAGE_TYPE: "s3" });
+    configureStorage({ db, localDir: dir });
+
+    expect(await isRemoteStorageEnabled()).toBe(false);
+    expect(db.systemConfig.findMany).not.toHaveBeenCalled();
+  });
+
+  it("ghi rồi đọc lại", async () => {
+    await putFile("uploads/2026/a.txt", Buffer.from("xin chào"), "text/plain");
+    expect((await getFile("uploads/2026/a.txt")).toString()).toBe("xin chào");
+  });
+
+  it("thiếu key → StorageNotFoundError (nơi gọi dịch thành 404)", async () => {
+    await expect(getFile("uploads/khong-co.pdf")).rejects.toBeInstanceOf(
+      StorageNotFoundError,
+    );
+  });
+
+  it("xoá là idempotent", async () => {
+    await putFile("a.txt", Buffer.from("x"), "text/plain");
+    await deleteFile("a.txt");
+    await expect(deleteFile("a.txt")).resolves.toBeUndefined();
+  });
+
+  it("liệt kê theo tiền tố", async () => {
+    await putFile("uploads/a.txt", Buffer.from("1"), "text/plain");
+    await putFile("uploads/sub/b.txt", Buffer.from("22"), "text/plain");
+    await putFile("khac/c.txt", Buffer.from("333"), "text/plain");
+
+    const keys = (await listObjects("uploads/")).map((o) => o.key).sort();
+    expect(keys).toEqual(["uploads/a.txt", "uploads/sub/b.txt"]);
+  });
+
+  it("không ký được URL → null để nơi gọi rơi về proxy", async () => {
+    expect(await getPresignedUrl("a.txt")).toBeNull();
+    expect(await getPublicUrl("uploads/a.txt")).toBe("/api/files/uploads/a.txt");
+  });
+
+  it("chặn traversal trước khi chạm đĩa", async () => {
+    await expect(getFile("../../../etc/passwd")).rejects.toThrow(
+      /Key không hợp lệ/,
+    );
+  });
+});
+
+describe("chế độ từ xa", () => {
+  const driver = (): StorageDriver => ({
+    put: vi.fn(async () => undefined),
+    get: vi.fn(async () => Buffer.from("từ s3")),
+    remove: vi.fn(async () => undefined),
+    presign: vi.fn(async () => "https://cdn.example/signed"),
+    list: vi.fn(async () => []),
+  });
+
+  it("STORAGE_TYPE=s3 + có driver → dùng driver", async () => {
+    const d = driver();
+    configureStorage({
+      db: fakeDb({
+        STORAGE_TYPE: '"s3"', // giá trị trong DB là JSON string
+        S3_ENDPOINT: '"http://minio:9000"',
+        S3_BUCKET: '"erp"',
+        S3_ACCESS_KEY: '"ak"',
+        S3_SECRET_KEY: '"sk"',
+      }),
+      driver: d,
+      localDir: dir,
+    });
+
+    expect(await isRemoteStorageEnabled()).toBe(true);
+    expect((await getFile("a.txt")).toString()).toBe("từ s3");
+    expect(await getPresignedUrl("a.txt")).toBe("https://cdn.example/signed");
+    expect(await getPublicUrl("a.txt")).toBe("http://minio:9000/erp/a.txt");
+  });
+
+  it("thiếu trường bắt buộc → cảnh báo rồi rơi về local, không sập request", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    configureStorage({
+      db: fakeDb({ STORAGE_TYPE: "s3", S3_ENDPOINT: "http://minio:9000" }),
+      driver: driver(),
+      localDir: dir,
+    });
+
+    expect(await isRemoteStorageEnabled()).toBe(false);
+    await putFile("a.txt", Buffer.from("local"), "text/plain");
+    expect((await getFile("a.txt")).toString()).toBe("local");
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("requireRemote: mất cấu hình thì THROW chứ không âm thầm ghi đĩa container", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    configureStorage({
+      db: fakeDb({ STORAGE_TYPE: "local" }),
+      driver: driver(),
+      localDir: dir,
+      requireRemote: true,
+    });
+
+    await expect(putFile("a.txt", Buffer.from("x"), "text/plain")).rejects.toThrow(
+      /requireRemote/,
+    );
+    await expect(getFile("a.txt")).rejects.toThrow(/requireRemote/);
+    await expect(listObjects("")).rejects.toThrow(/requireRemote/);
+    warn.mockRestore();
+  });
+
+  it("clearCache() buộc đọc lại cấu hình", async () => {
+    const db = fakeDb({
+      STORAGE_TYPE: "s3",
+      S3_ENDPOINT: "http://minio:9000",
+      S3_BUCKET: "erp",
+      S3_ACCESS_KEY: "ak",
+      S3_SECRET_KEY: "sk",
+    });
+    configureStorage({ db, driver: driver(), localDir: dir });
+
+    await isRemoteStorageEnabled();
+    await isRemoteStorageEnabled();
+    expect(db.systemConfig.findMany).toHaveBeenCalledTimes(1);
+
+    clearStorageCache();
+    await isRemoteStorageEnabled();
+    expect(db.systemConfig.findMany).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("createFileProxyHandler", () => {
+  const req = () => new Request("http://x/api/files/a.pdf") as never;
+  const ctx = (key: string, session?: unknown) => ({
+    params: Promise.resolve({ key: key.split("/") }),
+    session,
+  });
+
+  beforeEach(async () => {
+    configureStorage({ db: fakeDb(), localDir: dir });
+    await putFile("uploads/bao cao.pdf", Buffer.from("%PDF"), "application/pdf");
+    await putFile("uploads/data.csv", Buffer.from("a,b"), "text/csv");
+  });
+
+  it("trả tập tin, pdf mở inline", async () => {
+    const res = await createFileProxyHandler()(req(), ctx("uploads/bao cao.pdf"));
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("application/pdf");
+    expect(res.headers.get("Content-Disposition")).toBe(
+      'inline; filename="bao%20cao.pdf"',
+    );
+    expect(res.headers.get("Cache-Control")).toBe("private, max-age=3600");
+  });
+
+  it("loại không xem được thì tải về", async () => {
+    const res = await createFileProxyHandler()(req(), ctx("uploads/data.csv"));
+    expect(res.headers.get("Content-Disposition")).toMatch(/^attachment;/);
+  });
+
+  it("authorize=false → 403 và KHÔNG đọc kho", async () => {
+    const res = await createFileProxyHandler({ authorize: () => false })(
+      req(),
+      ctx("uploads/bao cao.pdf"),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  it("authorize trả mã riêng → dùng mã đó (404 để giấu sự tồn tại)", async () => {
+    const res = await createFileProxyHandler({
+      authorize: () => ({ status: 404, message: "Not found" }),
+    })(req(), ctx("uploads/bao cao.pdf"));
+    expect(res.status).toBe(404);
+  });
+
+  it("seam authorize nhận đúng key và session", async () => {
+    const authorize = vi.fn(() => true);
+    await createFileProxyHandler({ authorize })(
+      req(),
+      ctx("uploads/bao cao.pdf", { userId: "u1" }),
+    );
+    expect(authorize).toHaveBeenCalledWith(
+      expect.objectContaining({
+        key: "uploads/bao cao.pdf",
+        session: { userId: "u1" },
+      }),
+    );
+  });
+
+  it("key bẩn bị chặn TRƯỚC authorize (seam app hay lấy key đi tra DB)", async () => {
+    const authorize = vi.fn(() => true);
+    const res = await createFileProxyHandler({ authorize })(
+      req(),
+      ctx("../../etc/passwd"),
+    );
+    expect(res.status).toBe(400);
+    expect(authorize).not.toHaveBeenCalled();
+  });
+
+  it("traversal → 400, thiếu key → 400, không có tập tin → 404", async () => {
+    const handler = createFileProxyHandler();
+    expect((await handler(req(), ctx("../../etc/passwd"))).status).toBe(400);
+    expect((await handler(req(), { params: Promise.resolve({}) })).status).toBe(
+      400,
+    );
+    expect((await handler(req(), ctx("uploads/thieu.pdf"))).status).toBe(404);
+  });
+
+  it("rejectUnknownType chặn loại ngoài bảng (route công khai)", async () => {
+    const res = await createFileProxyHandler({
+      contentTypes: { png: "image/png" },
+      rejectUnknownType: true,
+    })(req(), ctx("uploads/bao cao.pdf"));
+    expect(res.status).toBe(404);
+  });
+});
+
+describe("createUploadHandler", () => {
+  beforeEach(() => {
+    configureStorage({ db: fakeDb(), localDir: dir });
+  });
+
+  // Dựng request giả thay vì `new Request(body: FormData)`: môi trường test là
+  // jsdom nên File là của jsdom, còn Request.formData() lại do undici phân tích
+  // — undici không nhận File lạ và ném AssertionError trước khi vào handler.
+  const fakeFile = (name: string, content: string, type: string) => ({
+    name,
+    type,
+    size: Buffer.byteLength(content),
+    arrayBuffer: async () => Buffer.from(content),
+  });
+
+  const post = (file: unknown) =>
+    ({
+      formData: async () => ({ get: (key: string) => (key === "file" ? file : null) }),
+    }) as never;
+
+  it("lưu được và trả URL proxy — KHÔNG phải đường dẫn public", async () => {
+    const res = await createUploadHandler()(
+      post(fakeFile("Hợp đồng.pdf", "nội dung", "application/pdf")),
+    );
+    const body = (await res.json()) as { url: string; key: string };
+
+    expect(res.status).toBe(200);
+    expect(body.url).toMatch(
+      /^\/api\/files\/uploads\/\d{8}\/Hợp_đồng_\d+\.pdf$/,
+    );
+    expect((await getFile(body.key)).toString()).toBe("nội dung");
+  });
+
+  it("chặn đuôi không cho phép", async () => {
+    const res = await createUploadHandler()(
+      post(fakeFile("virus.exe", "MZ", "application/octet-stream")),
+    );
+    expect(res.status).toBe(415);
+  });
+
+  it("chặn tập tin quá lớn", async () => {
+    const res = await createUploadHandler({ maxBytes: 4 })(
+      post(fakeFile("a.txt", "quá dài", "text/plain")),
+    );
+    expect(res.status).toBe(413);
+  });
+
+  it("không có tập tin → 400", async () => {
+    const res = await createUploadHandler()(post(null));
+    expect(res.status).toBe(400);
+  });
+});