@chidchanun/bcp 0.1.23 → 0.1.25

package/packages/server/src/upload.ts

@@ -0,0 +1,556 @@
+import {
+    createHash,
+    randomUUID,
+} from "node:crypto";
+import {
+    mkdir,
+    writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+
+export type UploadErrorCode =
+    | "INVALID_MULTIPART"
+    | "UPLOAD_TOO_LARGE"
+    | "FILE_REQUIRED"
+    | "FILE_TOO_LARGE"
+    | "FILE_TYPE_NOT_ALLOWED"
+    | "FILE_EXTENSION_NOT_ALLOWED"
+    | "INVALID_FILE_NAME"
+    | "FILE_EXISTS";
+
+export interface MultipartUploadOptions {
+    maxBytes?: number;
+}
+
+export interface UploadConstraints {
+    maxBytes?: number;
+    allowedTypes?: readonly string[];
+    allowedExtensions?: readonly string[];
+}
+
+export interface SaveUploadedFileOptions {
+    directory: string;
+    fileName?: string;
+    overwrite?: boolean;
+    constraints?: UploadConstraints;
+}
+
+export interface SavedUploadedFile {
+    originalName: string;
+    fileName: string;
+    path: string;
+    type: string;
+    size: number;
+    checksumSha256: string;
+}
+
+export class UploadError extends Error {
+    readonly code:
+        UploadErrorCode;
+    readonly status:
+        number;
+
+    constructor(
+        code: UploadErrorCode,
+        message: string,
+        status: number
+    ) {
+        super(
+            message
+        );
+        this.name =
+            "UploadError";
+        this.code =
+            code;
+        this.status =
+            status;
+    }
+}
+
+export async function parseMultipartFormData(
+    request: Request,
+    options: MultipartUploadOptions = {}
+): Promise<FormData> {
+    const contentType =
+        request.headers.get(
+            "content-type"
+        ) ?? "";
+
+    if (
+        !contentType
+            .toLowerCase()
+            .startsWith(
+                "multipart/form-data"
+            )
+    ) {
+        throw new UploadError(
+            "INVALID_MULTIPART",
+            "BCP Framework: upload request must use multipart/form-data.",
+            400
+        );
+    }
+
+    const maxBytes =
+        normalizePositiveLimit(
+            options.maxBytes,
+            "maxBytes"
+        );
+    const contentLength =
+        readContentLength(
+            request.headers.get(
+                "content-length"
+            )
+        );
+
+    if (
+        maxBytes !== null &&
+        contentLength !== null &&
+        contentLength > maxBytes
+    ) {
+        throw new UploadError(
+            "UPLOAD_TOO_LARGE",
+            `BCP Framework: multipart request exceeds the ${maxBytes} byte upload limit.`,
+            413
+        );
+    }
+
+    const formData =
+        await request.formData();
+
+    if (
+        maxBytes !== null &&
+        estimateFormDataBytes(
+            formData
+        ) > maxBytes
+    ) {
+        throw new UploadError(
+            "UPLOAD_TOO_LARGE",
+            `BCP Framework: multipart payload exceeds the ${maxBytes} byte upload limit.`,
+            413
+        );
+    }
+
+    return formData;
+}
+
+export function getUploadedFile(
+    formData: FormData,
+    fieldName: string,
+    constraints: UploadConstraints = {}
+): File | null {
+    const value =
+        formData.get(
+            fieldName
+        );
+
+    if (
+        !isUploadedFile(
+            value
+        )
+    ) {
+        return null;
+    }
+
+    validateUploadedFile(
+        value,
+        constraints
+    );
+
+    return value;
+}
+
+export function requireUploadedFile(
+    formData: FormData,
+    fieldName: string,
+    constraints: UploadConstraints = {}
+): File {
+    const file =
+        getUploadedFile(
+            formData,
+            fieldName,
+            constraints
+        );
+
+    if (!file) {
+        throw new UploadError(
+            "FILE_REQUIRED",
+            `BCP Framework: upload field "${fieldName}" must contain a file.`,
+            400
+        );
+    }
+
+    return file;
+}
+
+export function validateUploadedFile(
+    file: File,
+    constraints: UploadConstraints = {}
+): void {
+    const maxBytes =
+        normalizePositiveLimit(
+            constraints.maxBytes,
+            "maxBytes"
+        );
+
+    if (
+        maxBytes !== null &&
+        file.size > maxBytes
+    ) {
+        throw new UploadError(
+            "FILE_TOO_LARGE",
+            `BCP Framework: file "${file.name}" exceeds the ${maxBytes} byte file limit.`,
+            413
+        );
+    }
+
+    if (
+        constraints.allowedTypes &&
+        constraints.allowedTypes.length > 0
+    ) {
+        const allowedTypes =
+            constraints.allowedTypes.map(
+                (value) =>
+                    value
+                        .trim()
+                        .toLowerCase()
+            );
+        const fileType =
+            file.type
+                .trim()
+                .toLowerCase();
+
+        if (
+            !allowedTypes.includes(
+                fileType
+            )
+        ) {
+            throw new UploadError(
+                "FILE_TYPE_NOT_ALLOWED",
+                `BCP Framework: file type "${file.type || "unknown"}" is not allowed for "${file.name}".`,
+                415
+            );
+        }
+    }
+
+    if (
+        constraints.allowedExtensions &&
+        constraints.allowedExtensions.length > 0
+    ) {
+        const extension =
+            path.extname(
+                file.name
+            ).toLowerCase();
+        const allowedExtensions =
+            constraints.allowedExtensions.map(
+                normalizeExtension
+            );
+
+        if (
+            !allowedExtensions.includes(
+                extension
+            )
+        ) {
+            throw new UploadError(
+                "FILE_EXTENSION_NOT_ALLOWED",
+                `BCP Framework: file extension "${extension || "(none)"}" is not allowed for "${file.name}".`,
+                415
+            );
+        }
+    }
+}
+
+export async function saveUploadedFile(
+    file: File,
+    options: SaveUploadedFileOptions
+): Promise<SavedUploadedFile> {
+    validateUploadedFile(
+        file,
+        options.constraints
+    );
+
+    const directory =
+        path.resolve(
+            options.directory
+        );
+    const requestedName =
+        options.fileName ??
+        createStoredFileName(
+            file.name
+        );
+    const fileName =
+        sanitizeUploadFileName(
+            requestedName
+        );
+    const destination =
+        path.resolve(
+            directory,
+            fileName
+        );
+    const relative =
+        path.relative(
+            directory,
+            destination
+        );
+
+    if (
+        relative === "" ||
+        relative.startsWith(
+            ".."
+        ) ||
+        path.isAbsolute(
+            relative
+        )
+    ) {
+        throw new UploadError(
+            "INVALID_FILE_NAME",
+            "BCP Framework: upload destination must remain inside the configured directory.",
+            400
+        );
+    }
+
+    await mkdir(
+        directory,
+        {
+            recursive: true,
+        }
+    );
+
+    const bytes =
+        Buffer.from(
+            await file.arrayBuffer()
+        );
+
+    try {
+        await writeFile(
+            destination,
+            bytes,
+            {
+                flag:
+                    options.overwrite
+                        ? "w"
+                        : "wx",
+            }
+        );
+    } catch (error) {
+        if (
+            isNodeErrorCode(
+                error,
+                "EEXIST"
+            )
+        ) {
+            throw new UploadError(
+                "FILE_EXISTS",
+                `BCP Framework: upload destination "${fileName}" already exists.`,
+                409
+            );
+        }
+
+        throw error;
+    }
+
+    return {
+        originalName:
+            file.name,
+        fileName,
+        path:
+            destination,
+        type:
+            file.type,
+        size:
+            file.size,
+        checksumSha256:
+            createHash(
+                "sha256"
+            )
+                .update(
+                    bytes
+                )
+                .digest(
+                    "hex"
+                ),
+    };
+}
+
+export function sanitizeUploadFileName(
+    value: string
+): string {
+    const baseName =
+        path.basename(
+            value
+                .replace(
+                    /\\/g,
+                    "/"
+                )
+        );
+    const sanitized =
+        baseName
+            .replace(
+                /[\u0000-\u001F\u007F]/g,
+                ""
+            )
+            .replace(
+                /[<>:"/\\|?*]/g,
+                "-"
+            )
+            .replace(
+                /\s+/g,
+                "-"
+            )
+            .replace(
+                /-+/g,
+                "-"
+            )
+            .replace(
+                /^[.\s-]+|[.\s-]+$/g,
+                ""
+            );
+
+    if (
+        !sanitized ||
+        sanitized === "." ||
+        sanitized === ".."
+    ) {
+        throw new UploadError(
+            "INVALID_FILE_NAME",
+            "BCP Framework: upload file name is invalid.",
+            400
+        );
+    }
+
+    return sanitized;
+}
+
+function createStoredFileName(
+    originalName: string
+): string {
+    const extension =
+        path.extname(
+            originalName
+        )
+            .toLowerCase()
+            .replace(
+                /[^.a-z0-9]/g,
+                ""
+            )
+            .slice(
+                0,
+                16
+            );
+
+    return `${randomUUID()}${extension}`;
+}
+
+function estimateFormDataBytes(
+    formData: FormData
+): number {
+    let total =
+        0;
+
+    for (
+        const value
+        of formData.values()
+    ) {
+        total +=
+            isUploadedFile(
+                value
+            )
+                ? value.size
+                : Buffer.byteLength(
+                    value
+                );
+    }
+
+    return total;
+}
+
+function isUploadedFile(
+    value: FormDataEntryValue | null
+): value is File {
+    return (
+        value !== null &&
+        typeof value !== "string" &&
+        typeof value.name === "string" &&
+        typeof value.type === "string" &&
+        typeof value.size === "number" &&
+        typeof value.arrayBuffer ===
+            "function"
+    );
+}
+
+function normalizeExtension(
+    value: string
+): string {
+    const normalized =
+        value
+            .trim()
+            .toLowerCase();
+
+    if (!normalized) {
+        return "";
+    }
+
+    return normalized.startsWith(
+        "."
+    )
+        ? normalized
+        : `.${normalized}`;
+}
+
+function normalizePositiveLimit(
+    value: number | undefined,
+    label: string
+): number | null {
+    if (
+        value === undefined
+    ) {
+        return null;
+    }
+
+    if (
+        !Number.isSafeInteger(
+            value
+        ) ||
+        value <= 0
+    ) {
+        throw new TypeError(
+            `BCP Framework: upload ${label} must be a positive safe integer.`
+        );
+    }
+
+    return value;
+}
+
+function readContentLength(
+    value: string | null
+): number | null {
+    if (!value) {
+        return null;
+    }
+
+    const parsed =
+        Number(
+            value
+        );
+
+    return Number.isSafeInteger(
+        parsed
+    ) &&
+    parsed >= 0
+        ? parsed
+        : null;
+}
+
+function isNodeErrorCode(
+    error: unknown,
+    code: string
+): boolean {
+    return (
+        error instanceof Error &&
+        "code" in error &&
+        (
+            error as Error & {
+                code?: string;
+            }
+        ).code === code
+    );
+}