@goplusvn/core 0.1.57 → 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.57",
+  "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",
@@ -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/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);
+  });
+});

package/src/storage/file-proxy.ts

@@ -0,0 +1,147 @@
+import type { NextRequest } from "next/server";
+
+import {
+  CONTENT_TYPES,
+  INLINE_EXTENSIONS,
+  InvalidStorageKeyError,
+  assertSafeKey,
+  fileExtension,
+} from "./keys";
+import { getFile } from "./storage-service";
+import { StorageNotFoundError, isNotFoundError } from "./types";
+
+/**
+ * Route factory phục vụ tập tin qua chính app server.
+ *
+ * Vì sao phải proxy: MinIO/S3 nội bộ không mở ra Internet, và ngay cả khi mở
+ * thì object nào cũng cần luật quyền riêng. Route này gom phần CHUNG (chặn
+ * traversal, đoán content-type, inline hay attachment, 404 khi thiếu key,
+ * cache header) và chừa phần RIÊNG cho app qua seam `authorize` — luật kiểu
+ * "prefix `misa-invoices/` cần quyền xem hoá đơn" hay "tra ngược key trong
+ * cột attachments" là nghiệp vụ của app, không phải của core.
+ *
+ *   // src/app/api/files/[...key]/route.ts
+ *   export const GET = apiHandler(
+ *     createFileProxyHandler({
+ *       authorize: ({ key, session }) => authorizeFileKey(key, session),
+ *       onError: (error, req) => serverError(error, req, { message: "Không thể tải tập tin" }),
+ *     }),
+ *   )
+ */
+
+export interface FileProxyAuthContext<TSession = unknown> {
+  /** Key đã ghép + đã kiểm tra an toàn. */
+  key: string;
+  req: NextRequest;
+  /** Session do lớp bọc (apiHandler) truyền xuống — `undefined` nếu route công khai. */
+  session: TSession;
+}
+
+/**
+ * `true` → cho qua. `false` → 403. Trả object để tự chọn mã lỗi (ví dụ 404 cho
+ * route công khai: lộ 403 là lộ luôn "key này có tồn tại").
+ */
+export type FileProxyDecision =
+  | boolean
+  | { status: number; message?: string };
+
+export interface FileProxyOptions<TSession = unknown> {
+  authorize?: (
+    ctx: FileProxyAuthContext<TSession>,
+  ) => Promise<FileProxyDecision> | FileProxyDecision;
+  /** Bảng đuôi → content-type. Mặc định `CONTENT_TYPES`. */
+  contentTypes?: Record<string, string>;
+  /**
+   * Đuôi lạ thì làm gì: `false` (mặc định) → `application/octet-stream`;
+   * `true` → 404. Route CÔNG KHAI nên bật để chỉ phục vụ đúng loại cho phép.
+   */
+  rejectUnknownType?: boolean;
+  /** Đuôi mở thẳng trong tab. Mặc định `INLINE_EXTENSIONS`. */
+  inlineExtensions?: string[];
+  /** Mặc định `private, max-age=3600` — chớ để `public` cho tập tin có phiên. */
+  cacheControl?: string;
+  /** Bọc lỗi 5xx (mặc định trả 500 trơn). Truyền `serverError` của app vào đây. */
+  onError?: (error: unknown, req: NextRequest) => Response | Promise<Response>;
+}
+
+interface RouteContext {
+  params?: unknown;
+  session?: unknown;
+}
+
+async function resolveKey(ctx: RouteContext | undefined): Promise<string> {
+  const params = (await ctx?.params) as { key?: unknown } | undefined;
+  const raw = params?.key;
+  if (Array.isArray(raw)) return raw.join("/");
+  return typeof raw === "string" ? raw : "";
+}
+
+export function createFileProxyHandler<TSession = unknown>(
+  options: FileProxyOptions<TSession> = {},
+) {
+  const contentTypes = options.contentTypes ?? CONTENT_TYPES;
+  const inlineExtensions = options.inlineExtensions ?? INLINE_EXTENSIONS;
+  const cacheControl = options.cacheControl ?? "private, max-age=3600";
+
+  return async function handler(
+    req: NextRequest,
+    ctx?: RouteContext,
+  ): Promise<Response> {
+    try {
+      const key = await resolveKey(ctx);
+      if (!key) return new Response("Missing file key", { status: 400 });
+      // Chặn traversal NGAY, trước cả `authorize`: seam của app thường lấy key
+      // đi tra DB, đừng để chuỗi bẩn đi xa hơn cổng. Ném
+      // InvalidStorageKeyError → catch bên dưới trả 400.
+      assertSafeKey(key);
+
+      const ext = fileExtension(key);
+      const contentType = contentTypes[ext];
+      if (!contentType && options.rejectUnknownType) {
+        return new Response("Not found", { status: 404 });
+      }
+
+      if (options.authorize) {
+        const decision = await options.authorize({
+          key,
+          req,
+          session: ctx?.session as TSession,
+        });
+        if (decision !== true) {
+          const denial =
+            typeof decision === "object"
+              ? decision
+              : { status: 403, message: "Forbidden" };
+          return new Response(denial.message ?? "Forbidden", {
+            status: denial.status,
+          });
+        }
+      }
+
+      const body = await getFile(key);
+      const filename = key.split("/").pop() || "file";
+      const disposition = inlineExtensions.includes(ext)
+        ? "inline"
+        : "attachment";
+
+      return new Response(new Uint8Array(body), {
+        headers: {
+          "Content-Type": contentType ?? "application/octet-stream",
+          "Content-Length": String(body.length),
+          "Content-Disposition": `${disposition}; filename="${encodeURIComponent(filename)}"`,
+          "Cache-Control": cacheControl,
+        },
+      });
+    } catch (error) {
+      if (error instanceof InvalidStorageKeyError) {
+        return new Response("Invalid file key", { status: 400 });
+      }
+      if (error instanceof StorageNotFoundError || isNotFoundError(error)) {
+        return new Response("File not found", { status: 404 });
+      }
+      if (options.onError) return options.onError(error, req);
+      console.error("[storage] file proxy lỗi:", error);
+      return new Response("Internal error", { status: 500 });
+    }
+  };
+}