@goplusvn/core 0.1.57 → 0.1.58

package/src/storage/index.ts

@@ -0,0 +1,51 @@
+/**
+ * `@goerp/core/storage` — kho tập tin dùng chung.
+ *
+ * Barrel này KHÔNG kéo aws-sdk (ratchet `__tests__/no-aws-in-barrel.test.ts`
+ * canh). Muốn chạy S3/MinIO thì cắm driver từ `@goerp/core/storage/s3`.
+ */
+
+export {
+  clearStorageCache,
+  configureStorage,
+  deleteFile,
+  getFile,
+  getPresignedUrl,
+  getPublicUrl,
+  getRemoteConfig,
+  isRemoteStorageEnabled,
+  listObjects,
+  putFile,
+  storage,
+} from "./storage-service";
+
+export {
+  CONTENT_TYPES,
+  IMAGE_CONTENT_TYPES,
+  INLINE_EXTENSIONS,
+  InvalidStorageKeyError,
+  assertSafeKey,
+  contentTypeFor,
+  fileExtension,
+  isSafeKey,
+  safeFileName,
+} from "./keys";
+
+export { createFileProxyHandler } from "./file-proxy";
+export type {
+  FileProxyAuthContext,
+  FileProxyDecision,
+  FileProxyOptions,
+} from "./file-proxy";
+
+export { createUploadHandler } from "./upload-handler";
+export type { UploadHandlerOptions } from "./upload-handler";
+
+export { StorageNotFoundError, isNotFoundError } from "./types";
+export type {
+  StorageConfigInput,
+  StorageDb,
+  StorageDriver,
+  StorageObjectInfo,
+  StorageRemoteConfig,
+} from "./types";

package/src/storage/keys.ts

@@ -0,0 +1,105 @@
+/**
+ * Chuẩn hoá "key" (đường dẫn logic của tập tin trong kho) + bảng content-type.
+ *
+ * Key là đầu vào do NGƯỜI DÙNG điều khiển (URL `/api/files/<key>`), nên mọi
+ * đường vào kho phải đi qua `assertSafeKey` trước khi chạm đĩa hay S3.
+ */
+
+/** Ký tự an toàn cho tên tập tin — GIỮ dấu tiếng Việt, thay phần còn lại. */
+const UNSAFE_NAME_CHARS = /[^a-zA-Z0-9._\-À-ɏḀ-ỿ]/g;
+
+export class InvalidStorageKeyError extends Error {
+  constructor(key: string) {
+    super(`Key không hợp lệ: ${key}`);
+    this.name = "InvalidStorageKeyError";
+  }
+}
+
+/**
+ * Chặn traversal (`..`), key tuyệt đối, backslash (Windows path) và null byte.
+ * Ném `InvalidStorageKeyError` — route factory dịch thành 400.
+ */
+export function assertSafeKey(key: string): string {
+  if (
+    !key ||
+    key.includes("..") ||
+    key.startsWith("/") ||
+    key.includes("\\") ||
+    key.includes("\0")
+  ) {
+    throw new InvalidStorageKeyError(key);
+  }
+  return key;
+}
+
+export function isSafeKey(key: string): boolean {
+  try {
+    assertSafeKey(key);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Làm sạch tên tập tin người dùng tải lên (giữ tiếng Việt có dấu). */
+export function safeFileName(name: string): string {
+  const trimmed = name.split(/[\\/]/).pop() ?? "file";
+  const dot = trimmed.lastIndexOf(".");
+  const base = dot > 0 ? trimmed.slice(0, dot) : trimmed;
+  const ext = dot > 0 ? trimmed.slice(dot + 1).toLowerCase() : "";
+  const safeBase = base.replace(UNSAFE_NAME_CHARS, "_") || "file";
+  return ext ? `${safeBase}.${ext.replace(UNSAFE_NAME_CHARS, "")}` : safeBase;
+}
+
+export function fileExtension(key: string): string {
+  const name = key.split("/").pop() ?? "";
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+}
+
+export const CONTENT_TYPES: Record<string, string> = {
+  pdf: "application/pdf",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  svg: "image/svg+xml",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  csv: "text/csv",
+  txt: "text/plain",
+};
+
+/** Ảnh — dùng cho route công khai (chỉ phục vụ ảnh, không phục vụ chứng từ). */
+export const IMAGE_CONTENT_TYPES: Record<string, string> = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  svg: "image/svg+xml",
+};
+
+/** Đuôi mở thẳng trong tab (inline); còn lại tải về (attachment). */
+export const INLINE_EXTENSIONS = [
+  "pdf",
+  "jpg",
+  "jpeg",
+  "png",
+  "gif",
+  "webp",
+  "avif",
+  "svg",
+];
+
+export function contentTypeFor(
+  key: string,
+  map: Record<string, string> = CONTENT_TYPES,
+): string | undefined {
+  return map[fileExtension(key)];
+}

package/src/storage/s3/index.ts

@@ -0,0 +1,160 @@
+import https from "node:https";
+
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { NodeHttpHandler } from "@smithy/node-http-handler";
+
+import type {
+  StorageDriver,
+  StorageObjectInfo,
+  StorageRemoteConfig,
+} from "../types";
+
+/**
+ * Driver S3/MinIO cho `@goerp/core/storage`.
+ *
+ * Ở SUBPATH RIÊNG (`@goerp/core/storage/s3`) chứ không nằm trong barrel: gói
+ * aws-sdk là peer dependency TUỲ CHỌN, app nào chỉ dùng đĩa local thì không
+ * phải cài. Bundler phân giải TĨNH cả `await import()`, nên nếu để driver này
+ * trong nhánh mặc định của engine thì mọi app không cài aws-sdk sẽ gãy build
+ * bằng "Module not found" (đúng cái bẫy next-auth trong proxy-gate).
+ *
+ *   // composition root
+ *   import { configureStorage } from "@goerp/core/storage"
+ *   import { createS3Driver } from "@goerp/core/storage/s3"
+ *   configureStorage({ db, driver: createS3Driver() })
+ */
+
+function fingerprint(config: StorageRemoteConfig, endpoint: string): string {
+  return [
+    endpoint,
+    config.region,
+    config.accessKey,
+    config.rejectUnauthorized,
+  ].join("|");
+}
+
+function buildClient(
+  config: StorageRemoteConfig,
+  endpoint: string,
+): S3Client {
+  return new S3Client({
+    endpoint,
+    region: config.region,
+    credentials: {
+      accessKeyId: config.accessKey,
+      secretAccessKey: config.secretKey,
+    },
+    // MinIO không hỗ trợ virtual-host style.
+    forcePathStyle: true,
+    // MinIO self-hosted thường dùng cert tự ký — agent riêng để không phải tắt
+    // verify TLS toàn tiến trình.
+    ...(endpoint.startsWith("https://") && {
+      requestHandler: new NodeHttpHandler({
+        httpsAgent: new https.Agent({
+          rejectUnauthorized: config.rejectUnauthorized,
+        }),
+      }),
+    }),
+  });
+}
+
+async function toBuffer(body: unknown): Promise<Buffer> {
+  const stream = body as AsyncIterable<Uint8Array> | null;
+  if (!stream) throw new Error("Phản hồi S3 không có nội dung");
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of stream) chunks.push(chunk);
+  return Buffer.concat(chunks);
+}
+
+export function createS3Driver(): StorageDriver {
+  // Memo theo dấu vân tay config: admin đổi endpoint + clearCache() là lần gọi
+  // sau dựng client mới, không phải restart container.
+  const clients = new Map<string, S3Client>();
+
+  const clientFor = (config: StorageRemoteConfig, endpoint: string) => {
+    const id = fingerprint(config, endpoint);
+    let client = clients.get(id);
+    if (!client) {
+      client = buildClient(config, endpoint);
+      clients.set(id, client);
+    }
+    return client;
+  };
+
+  /** Thao tác phía server đi endpoint NỘI BỘ. */
+  const internal = (config: StorageRemoteConfig) =>
+    clientFor(config, config.endpoint);
+
+  /**
+   * Ký presigned URL phải ký bằng endpoint CÔNG KHAI: chữ ký gắn với host, ký
+   * bằng host nội bộ thì trình duyệt nhận URL không gọi tới được.
+   */
+  const publicFacing = (config: StorageRemoteConfig) =>
+    clientFor(config, config.publicEndpoint || config.endpoint);
+
+  return {
+    async put(config, key, body, contentType) {
+      await internal(config).send(
+        new PutObjectCommand({
+          Bucket: config.bucket,
+          Key: key,
+          Body: body,
+          ContentType: contentType,
+        }),
+      );
+    },
+
+    async get(config, key) {
+      const response = await internal(config).send(
+        new GetObjectCommand({ Bucket: config.bucket, Key: key }),
+      );
+      return toBuffer(response.Body);
+    },
+
+    async remove(config, key) {
+      await internal(config).send(
+        new DeleteObjectCommand({ Bucket: config.bucket, Key: key }),
+      );
+    },
+
+    async presign(config, key, expiresIn) {
+      return getSignedUrl(
+        publicFacing(config),
+        new GetObjectCommand({ Bucket: config.bucket, Key: key }),
+        { expiresIn },
+      );
+    },
+
+    async list(config, prefix) {
+      const results: StorageObjectInfo[] = [];
+      let token: string | undefined;
+      do {
+        const page = await internal(config).send(
+          new ListObjectsV2Command({
+            Bucket: config.bucket,
+            Prefix: prefix,
+            ContinuationToken: token,
+          }),
+        );
+        for (const item of page.Contents ?? []) {
+          // Key kết thúc bằng "/" là thư mục giả do console MinIO tạo — không phải tập tin.
+          if (!item.Key || item.Key.endsWith("/")) continue;
+          results.push({
+            key: item.Key,
+            size: item.Size ?? 0,
+            lastModified: item.LastModified,
+          });
+        }
+        token = page.IsTruncated ? page.NextContinuationToken : undefined;
+      } while (token);
+      return results;
+    },
+  };
+}

package/src/storage/storage-service.ts

@@ -0,0 +1,280 @@
+import { mkdir, readFile, rm, stat, writeFile, readdir } from "fs/promises";
+import { dirname, join, sep } from "path";
+
+import { assertSafeKey } from "./keys";
+import {
+  StorageNotFoundError,
+  isNotFoundError,
+  type StorageConfigInput,
+  type StorageDriver,
+  type StorageObjectInfo,
+  type StorageRemoteConfig,
+} from "./types";
+
+/**
+ * Kho tập tin dùng chung của goerp.
+ *
+ * HAI CHẾ ĐỘ, chọn theo runtime chứ không theo build:
+ *   • `remote` — S3/MinIO, khi `STORAGE_TYPE=s3` trong `system_configs` VÀ app
+ *     có cắm driver (`@goerp/core/storage/s3`).
+ *   • `local`  — thư mục đĩa PRIVATE (mặc định `<cwd>/storage/files`). Đây là
+ *     mặc định để app mới chạy được ngay, chưa cần dựng MinIO.
+ *
+ * Cấu hình nằm trong DB (bảng `system_configs`) chứ không phải env: admin đổi
+ * endpoint trong màn hình cấu hình rồi `clearCache()` là ăn ngay, không cần
+ * deploy lại. App cắm phụ thuộc một lần ở composition root:
+ *
+ *   configureStorage({ db, driver: createS3Driver() })
+ */
+
+const CONFIG_KEYS = [
+  "STORAGE_TYPE",
+  "S3_ENDPOINT",
+  "S3_PUBLIC_ENDPOINT",
+  "S3_REGION",
+  "S3_BUCKET",
+  "S3_ACCESS_KEY",
+  "S3_SECRET_KEY",
+  "S3_REJECT_UNAUTHORIZED",
+] as const;
+
+let configured: StorageConfigInput | null = null;
+let cachedRemote: StorageRemoteConfig | null = null;
+let cacheLoaded = false;
+
+export function configureStorage(input: StorageConfigInput): void {
+  configured = input;
+  clearStorageCache();
+}
+
+/** Quên cấu hình đã đọc từ DB — gọi sau khi admin sửa S3_*. */
+export function clearStorageCache(): void {
+  cachedRemote = null;
+  cacheLoaded = false;
+}
+
+function requireConfigured(): StorageConfigInput {
+  if (!configured) {
+    throw new Error(
+      "[storage] chưa configureStorage({ db, driver? }) — gọi 1 lần lúc khởi tạo app (cạnh configureSettingsService).",
+    );
+  }
+  return configured;
+}
+
+function localRoot(): string {
+  return configured?.localDir ?? join(process.cwd(), "storage", "files");
+}
+
+/** Giá trị trong `system_configs` có thể là JSON string hoặc chuỗi thô. */
+function parseValue(raw: string | null): string {
+  if (raw == null) return "";
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "string" ? parsed : String(parsed);
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * Đọc cấu hình S3 từ DB (memo hoá). Trả `null` khi chưa bật hoặc thiếu trường
+ * bắt buộc — engine tự rơi về chế độ local thay vì ném lỗi giữa request.
+ */
+export async function getRemoteConfig(): Promise<StorageRemoteConfig | null> {
+  if (cacheLoaded) return cachedRemote;
+
+  const { db, driver } = requireConfigured();
+  cacheLoaded = true;
+  cachedRemote = null;
+
+  // Không có driver thì đọc config cũng vô nghĩa — khỏi phải hỏi DB.
+  if (!driver) return null;
+
+  const rows = await db.systemConfig.findMany({
+    where: { key: { in: [...CONFIG_KEYS] } },
+    select: { key: true, value: true },
+  });
+
+  const map: Record<string, string> = {};
+  for (const row of rows) map[row.key] = parseValue(row.value);
+
+  if ((map.STORAGE_TYPE || "").toLowerCase() !== "s3") return null;
+
+  const endpoint = map.S3_ENDPOINT || "";
+  const bucket = map.S3_BUCKET || "";
+  const accessKey = map.S3_ACCESS_KEY || "";
+  const secretKey = map.S3_SECRET_KEY || "";
+  if (!endpoint || !bucket || !accessKey || !secretKey) {
+    console.warn(
+      "[storage] STORAGE_TYPE=s3 nhưng thiếu S3_ENDPOINT/S3_BUCKET/S3_ACCESS_KEY/S3_SECRET_KEY — tạm dùng đĩa local.",
+    );
+    return null;
+  }
+
+  cachedRemote = {
+    endpoint,
+    publicEndpoint: map.S3_PUBLIC_ENDPOINT || endpoint,
+    region: map.S3_REGION || "us-east-1",
+    bucket,
+    accessKey,
+    secretKey,
+    rejectUnauthorized: map.S3_REJECT_UNAUTHORIZED === "true",
+  };
+  return cachedRemote;
+}
+
+/** Có đang chạy trên kho từ xa không (false = đĩa local). */
+export async function isRemoteStorageEnabled(): Promise<boolean> {
+  return (await getRemoteConfig()) !== null;
+}
+
+async function withRemote<T>(
+  fn: (driver: StorageDriver, config: StorageRemoteConfig) => Promise<T>,
+): Promise<T | null> {
+  const config = await getRemoteConfig();
+  if (!config) return null;
+  return fn(requireConfigured().driver as StorageDriver, config);
+}
+
+/**
+ * Chặn cửa hậu "im lặng rơi về local" ở app đã chạy S3: ghi thành công vào đĩa
+ * container = mất tập tin ở lần deploy sau, tệ hơn hẳn một lỗi ồn ào.
+ */
+function assertLocalAllowed(): void {
+  if (configured?.requireRemote) {
+    throw new Error(
+      "[storage] requireRemote=true nhưng kho S3 chưa sẵn sàng — kiểm tra STORAGE_TYPE/S3_* trong system_configs. Từ chối dùng đĩa local.",
+    );
+  }
+}
+
+function localPath(key: string): string {
+  assertLocalAllowed();
+  return join(localRoot(), ...assertSafeKey(key).split("/"));
+}
+
+/** Lưu tập tin. Trả về chính `key` để nơi gọi ghép URL. */
+export async function putFile(
+  key: string,
+  body: Buffer,
+  contentType = "application/octet-stream",
+): Promise<string> {
+  assertSafeKey(key);
+  const done = await withRemote((driver, config) =>
+    driver.put(config, key, body, contentType),
+  );
+  if (done === null) {
+    const path = localPath(key);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, body);
+  }
+  return key;
+}
+
+/** Đọc tập tin. Không có → ném `StorageNotFoundError`. */
+export async function getFile(key: string): Promise<Buffer> {
+  assertSafeKey(key);
+  const config = await getRemoteConfig();
+  if (config) {
+    try {
+      return await (requireConfigured().driver as StorageDriver).get(
+        config,
+        key,
+      );
+    } catch (error) {
+      if (isNotFoundError(error)) throw new StorageNotFoundError(key);
+      throw error;
+    }
+  }
+  try {
+    return await readFile(localPath(key));
+  } catch (error) {
+    if (isNotFoundError(error)) throw new StorageNotFoundError(key);
+    throw error;
+  }
+}
+
+/** Xoá tập tin. Không có sẵn cũng coi như thành công (idempotent). */
+export async function deleteFile(key: string): Promise<void> {
+  assertSafeKey(key);
+  const done = await withRemote((driver, config) => driver.remove(config, key));
+  if (done === null) {
+    await rm(localPath(key), { force: true });
+  }
+}
+
+/**
+ * URL có chữ ký để trình duyệt tải thẳng từ kho. Chế độ local không ký được →
+ * trả `null`, nơi gọi rơi về proxy `/api/files/<key>`.
+ */
+export async function getPresignedUrl(
+  key: string,
+  expiresIn = 3600,
+): Promise<string | null> {
+  assertSafeKey(key);
+  return withRemote((driver, config) => driver.presign(config, key, expiresIn));
+}
+
+/**
+ * URL công khai của object. Chế độ local (hoặc MinIO nội bộ) không có URL trực
+ * tiếp cho trình duyệt → dùng proxy của app.
+ */
+export async function getPublicUrl(
+  key: string,
+  proxyPrefix = "/api/files",
+): Promise<string> {
+  assertSafeKey(key);
+  const config = await getRemoteConfig();
+  if (!config) return `${proxyPrefix}/${key}`;
+  return `${config.publicEndpoint}/${config.bucket}/${key}`;
+}
+
+/** Liệt kê object theo tiền tố — dùng cho backup/dọn rác. */
+export async function listObjects(
+  prefix: string,
+): Promise<StorageObjectInfo[]> {
+  const config = await getRemoteConfig();
+  if (config) {
+    return (requireConfigured().driver as StorageDriver).list(config, prefix);
+  }
+
+  assertLocalAllowed();
+  const root = localRoot();
+  const results: StorageObjectInfo[] = [];
+  const walk = async (dir: string): Promise<void> => {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (error) {
+      if (isNotFoundError(error)) return;
+      throw error;
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+        continue;
+      }
+      const key = full.slice(root.length + 1).split(sep).join("/");
+      if (!key.startsWith(prefix)) continue;
+      const info = await stat(full);
+      results.push({ key, size: info.size, lastModified: info.mtime });
+    }
+  };
+  await walk(root);
+  return results;
+}
+
+/** Gom lại thành facade cho nơi gọi thích gọi kiểu `storage.getFile(...)`. */
+export const storage = {
+  clearCache: clearStorageCache,
+  getRemoteConfig,
+  isRemoteEnabled: isRemoteStorageEnabled,
+  put: putFile,
+  get: getFile,
+  delete: deleteFile,
+  getPresignedUrl,
+  getPublicUrl,
+  list: listObjects,
+};

package/src/storage/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Kho tập tin — kiểu dùng chung cho engine, driver và các route factory.
+ *
+ * Core KHÔNG phụ thuộc aws-sdk: driver S3/MinIO nằm ở subpath riêng
+ * `@goerp/core/storage/s3` và được app cắm vào qua `configureStorage`. App nào
+ * chỉ cần đĩa local thì không phải cài thêm gói nào.
+ */
+
+/** Cấu hình S3/MinIO đọc từ bảng `system_configs`. */
+export interface StorageRemoteConfig {
+  /** Endpoint NỘI BỘ — dùng cho upload/get/delete từ phía server. */
+  endpoint: string;
+  /**
+   * Endpoint CÔNG KHAI — chỉ dùng khi ký presigned URL để trình duyệt gọi
+   * thẳng. Khác endpoint nội bộ thì chữ ký phải ký bằng cái này, nếu không
+   * URL trả về trỏ vào host mà trình duyệt không thấy.
+   */
+  publicEndpoint: string;
+  region: string;
+  bucket: string;
+  accessKey: string;
+  secretKey: string;
+  /**
+   * Verify chứng chỉ TLS của endpoint. MẶC ĐỊNH `false` vì MinIO self-hosted
+   * thường dùng cert tự ký — bật `true` (key `S3_REJECT_UNAUTHORIZED`) khi
+   * endpoint có cert hợp lệ.
+   */
+  rejectUnauthorized: boolean;
+}
+
+export interface StorageObjectInfo {
+  key: string;
+  size: number;
+  lastModified?: Date;
+}
+
+/**
+ * Driver kho từ xa. Nhận config theo từng lời gọi (thay vì giữ state) để
+ * `clearCache()` của engine đổi config là ăn ngay — driver tự memo client theo
+ * dấu vân tay config.
+ */
+export interface StorageDriver {
+  put(
+    config: StorageRemoteConfig,
+    key: string,
+    body: Buffer,
+    contentType: string,
+  ): Promise<void>;
+  get(config: StorageRemoteConfig, key: string): Promise<Buffer>;
+  remove(config: StorageRemoteConfig, key: string): Promise<void>;
+  presign(
+    config: StorageRemoteConfig,
+    key: string,
+    expiresIn: number,
+  ): Promise<string>;
+  list(
+    config: StorageRemoteConfig,
+    prefix: string,
+  ): Promise<StorageObjectInfo[]>;
+}
+
+/**
+ * Delegate Prisma tối thiểu — args để `any` CÓ CHỦ ĐÍCH (cùng bài học
+ * SettingsDb/TaskDb: generated types của mỗi app hẹp hơn nên khai chặt sẽ
+ * không assignable).
+ */
+export interface StorageDb {
+  systemConfig: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    findMany(args: any): Promise<{ key: string; value: string | null }[]>;
+  };
+}
+
+export interface StorageConfigInput {
+  db: StorageDb;
+  /**
+   * Driver kho từ xa. Bỏ trống → luôn dùng đĩa local (`localDir`), kể cả khi
+   * `STORAGE_TYPE=s3` trong DB.
+   */
+  driver?: StorageDriver;
+  /** Thư mục fallback khi không có driver / STORAGE_TYPE != s3. */
+  localDir?: string;
+  /**
+   * `true` = CẤM rơi về đĩa local: thiếu/hỏng cấu hình S3 thì ném lỗi thay vì
+   * âm thầm ghi vào đĩa container. Bật cho app production đã chạy S3 — mất
+   * cấu hình mà vẫn "thành công" nghĩa là tập tin bay theo lần deploy sau.
+   */
+  requireRemote?: boolean;
+}
+
+/** Lỗi "không có key này" — engine và driver đều ném ra dạng này. */
+export class StorageNotFoundError extends Error {
+  readonly key: string;
+  constructor(key: string) {
+    super(`Không tìm thấy tập tin: ${key}`);
+    this.name = "StorageNotFoundError";
+    this.key = key;
+  }
+}
+
+/** Nhận diện lỗi 404 từ mọi phía (driver S3 ném NoSuchKey, local ném ENOENT). */
+export function isNotFoundError(error: unknown): boolean {
+  if (error instanceof StorageNotFoundError) return true;
+  const err = error as { name?: string; code?: string; message?: string } | null;
+  if (!err) return false;
+  if (err.name === "NoSuchKey" || err.name === "NotFound") return true;
+  if (err.code === "ENOENT" || err.code === "NoSuchKey") return true;
+  return Boolean(
+    err.message?.includes("NoSuchKey") || err.message?.includes("ENOENT"),
+  );
+}