@goplusvn/core 0.1.57 → 0.1.59

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 });
+    }
+  };
+}

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;
+    },
+  };
+}