arkos 2.0.0-next.3 → 2.0.0-next.30

package/dist/esm/modules/file-upload/utils/helpers/serve-upload-dir.js

@@ -0,0 +1,206 @@
+import express from "express";
+import fs from "fs";
+import path from "path";
+import AppError from "../../../error-handler/utils/app-error.js";
+import ArkosRouter from "../../../../utils/arkos-router/index.js";
+import { extractPathParams } from "../../../../utils/arkos-router/utils/helpers/index.js";
+import { getArkosConfig } from "../../../../server.js";
+import deepmerge from "../../../../utils/helpers/deepmerge.helper.js";
+import { assertSafeUploadPath, isRealPathInside, isSafeUploadParam, normalizeUploadDir, normalizeUploadUrlPath, resolveUploadPath, } from "./upload-path.helper.js";
+import { uploadServingRegistry, } from "./upload-serving.registry.js";
+const DEFAULT_STATIC_OPTIONS = {
+    maxAge: "1y",
+    etag: true,
+    lastModified: true,
+    dotfiles: "ignore",
+    fallthrough: false,
+    index: false,
+    cacheControl: true,
+};
+function buildStaticOptions(overrides) {
+    const config = getArkosConfig();
+    return deepmerge(deepmerge(DEFAULT_STATIC_OPTIONS, config.fileUpload?.expressStatic || {}), overrides || {});
+}
+function substituteParams(template, values) {
+    return template
+        .split("/")
+        .map((segment) => segment.startsWith(":") ? values[segment.slice(1)] : segment)
+        .join("/");
+}
+function stripMountSegments(url, segmentCount) {
+    const queryIndex = url.indexOf("?");
+    const rawPath = queryIndex === -1 ? url : url.slice(0, queryIndex);
+    const query = queryIndex === -1 ? "" : url.slice(queryIndex);
+    const parts = rawPath.split("/");
+    const start = rawPath.startsWith("/") ? segmentCount + 1 : segmentCount;
+    const remainder = parts.slice(start).join("/");
+    return `/${remainder}${query}`;
+}
+function isSafeServedPath(value) {
+    if (!value || value.includes("\\") || value.includes("\0"))
+        return false;
+    return value
+        .split("/")
+        .every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+function notFound() {
+    return new AppError("File not found", 404, "FileNotFound");
+}
+function getLocals(req) {
+    return req.res?.locals || {};
+}
+function openApiConfig(dir) {
+    return {
+        tags: ["File Upload"],
+        summary: "Retrieve uploaded file",
+        description: `Serves files from the "${dir}" upload directory.`,
+        responses: {
+            "200": {
+                description: "File retrieved successfully",
+                content: {
+                    "application/octet-stream": {
+                        schema: { type: "string", format: "binary" },
+                    },
+                },
+            },
+            "404": {
+                description: "File not found",
+            },
+        },
+    };
+}
+export function serveUploadDir(dir, options = {}) {
+    const normalizedDir = normalizeUploadDir(dir);
+    assertSafeUploadPath(normalizedDir, {
+        allowParams: true,
+        label: "upload directory",
+    });
+    const mountPath = normalizeUploadUrlPath(options.urlPath ?? `/${normalizedDir}`);
+    if (mountPath === "/")
+        throw new Error(`Invalid upload URL path "/" for upload directory "${normalizedDir}": it must contain at least one segment.`);
+    assertSafeUploadPath(mountPath.replace(/^\//, ""), {
+        allowParams: true,
+        label: "upload URL path",
+    });
+    if (options.prepare !== undefined && typeof options.prepare !== "function")
+        throw new Error(`Invalid prepare function for upload directory "${normalizedDir}": expected a function.`);
+    const dirParams = extractPathParams(`/${normalizedDir}`);
+    const pathParams = extractPathParams(mountPath);
+    if (dirParams.length > 0 && !options.prepare)
+        throw new Error(`Dynamic upload directory "${normalizedDir}" requires a prepare function.`);
+    const recursive = options.recursive === true;
+    const dynamic = dirParams.length > 0;
+    const mountSegments = mountPath.split("/").filter(Boolean).length;
+    const registration = {
+        dir: normalizedDir,
+        urlPath: mountPath,
+        dirParams,
+        pathParams,
+        recursive,
+        dynamic,
+        hasPrepare: !!options.prepare,
+    };
+    uploadServingRegistry.registerServe(registration);
+    const router = ArkosRouter();
+    let cachedStatic;
+    const resolveDirectory = async (req, _res, next) => {
+        try {
+            const config = getArkosConfig();
+            const baseUploadDir = config.fileUpload?.baseUploadDir || "uploads";
+            const basePath = path.resolve(process.cwd(), baseUploadDir);
+            const prepared = options.prepare
+                ? await options.prepare(req, getLocals(req))
+                : undefined;
+            const values = prepared?.dirParams ?? {};
+            for (const param of dirParams) {
+                const value = values[param];
+                if (value === undefined)
+                    throw new Error(`Missing required upload directory param ":${param}" for "${normalizedDir}" on "${req.method} ${req.originalUrl}".`);
+                if (!isSafeUploadParam(value))
+                    return next(notFound());
+            }
+            const resolvedDir = substituteParams(normalizedDir, values);
+            const rootPath = resolveUploadPath(basePath, resolvedDir, {
+                strictSegments: true,
+            });
+            if (!rootPath)
+                return next(notFound());
+            if (!(await isRealPathInside(basePath, rootPath)))
+                return next(notFound());
+            let stats;
+            try {
+                stats = await fs.promises.stat(rootPath);
+            }
+            catch {
+                return next(notFound());
+            }
+            req.__arkos = {
+                ...req.__arkos,
+                uploadDir: resolvedDir,
+                uploadPath: rootPath,
+                uploadKind: stats.isFile()
+                    ? "file"
+                    : stats.isDirectory()
+                        ? "directory"
+                        : undefined,
+            };
+            if (!req.__arkos.uploadKind)
+                return next(notFound());
+            next();
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+    const serveExactFile = (req, res, next) => {
+        const rootPath = req.__arkos?.uploadPath;
+        if (req.__arkos?.uploadKind !== "file" || !rootPath)
+            return next(notFound());
+        req.url = `/${encodeURIComponent(path.basename(rootPath))}${req.url.includes("?") ? req.url.slice(req.url.indexOf("?")) : ""}`;
+        const staticHandler = express.static(path.dirname(rootPath), buildStaticOptions(options.expressStatic));
+        staticHandler(req, res, next);
+    };
+    const serveFolder = (req, res, next) => {
+        const rootPath = req.__arkos?.uploadPath;
+        if (req.__arkos?.uploadKind !== "directory" || !rootPath)
+            return next(notFound());
+        if (!recursive) {
+            const fileName = req.params.fileName;
+            if (typeof fileName !== "string" ||
+                fileName.includes("/") ||
+                !isSafeServedPath(fileName))
+                return next(notFound());
+        }
+        else {
+            const filePath = req.params[0];
+            if (!filePath || !isSafeServedPath(filePath))
+                return next(notFound());
+        }
+        req.url = stripMountSegments(req.url, mountSegments);
+        if (req.url.split("?")[0] === "/")
+            return next(notFound());
+        if (!dynamic)
+            cachedStatic ??= express.static(rootPath, buildStaticOptions(options.expressStatic));
+        const staticHandler = cachedStatic ??
+            express.static(rootPath, buildStaticOptions(options.expressStatic));
+        staticHandler(req, res, next);
+    };
+    const handleStaticError = (err, req, _res, next) => {
+        if (err?.code === "ENOENT" ||
+            err?.status === 403 ||
+            err?.statusCode === 403)
+            return next(new AppError(`File ${req.path} was not found`, 404, "FileNotFound", { filepath: req.path }));
+        next(err);
+    };
+    const openapi = openApiConfig(normalizedDir);
+    router.get({
+        path: mountPath,
+        experimental: { openapi },
+    }, resolveDirectory, serveExactFile, handleStaticError);
+    router.get({
+        path: `${mountPath}${recursive ? "/*" : "/:fileName"}`,
+        experimental: { openapi },
+    }, resolveDirectory, serveFolder, handleStaticError);
+    return router;
+}
+//# sourceMappingURL=serve-upload-dir.js.map

package/dist/esm/modules/file-upload/utils/helpers/serve-upload-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-upload-dir.js","sourceRoot":"","sources":["../../../../../../src/modules/file-upload/utils/helpers/serve-upload-dir.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,QAAQ,MAAM,wCAAwC,CAAC;AAG9D,OAAO,WAAW,MAAM,gCAAgC,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,SAAS,MAAM,4CAA4C,CAAC;AACnE,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,qBAAqB,GAEtB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,sBAAsB,GAAG;IAC7B,MAAM,EAAE,IAAI;IACZ,IAAI,EAAE,IAAI;IACV,YAAY,EAAE,IAAI;IAClB,QAAQ,EAAE,QAAQ;IAClB,WAAW,EAAE,KAAK;IAClB,KAAK,EAAE,KAAK;IACZ,YAAY,EAAE,IAAI;CACnB,CAAC;AA2BF,SAAS,kBAAkB,CACzB,SAAgD;IAEhD,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;IAEhC,OAAO,SAAS,CACd,SAAS,CAAC,sBAAsB,EAAE,MAAM,CAAC,UAAU,EAAE,aAAa,IAAI,EAAE,CAAC,EACzE,SAAS,IAAI,EAAE,CACwB,CAAC;AAC5C,CAAC;AAED,SAAS,gBAAgB,CACvB,QAAgB,EAChB,MAA8B;IAE9B,OAAO,QAAQ;SACZ,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACf,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAC7D;SACA,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAW,EAAE,YAAoB;IAC3D,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;IACxE,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAE/C,OAAO,IAAI,SAAS,GAAG,KAAK,EAAE,CAAC;AACjC,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa;IACrC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAEzE,OAAO,KAAK;SACT,KAAK,CAAC,GAAG,CAAC;SACV,KAAK,CACJ,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,CACnE,CAAC;AACN,CAAC;AAED,SAAS,QAAQ;IACf,OAAO,IAAI,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,SAAS,CAAC,GAAiB;IAClC,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED,SAAS,aAAa,CAAC,GAAW;IAChC,OAAO;QACL,IAAI,EAAE,CAAC,aAAa,CAAC;QACrB,OAAO,EAAE,wBAAwB;QACjC,WAAW,EAAE,0BAA0B,GAAG,qBAAqB;QAC/D,SAAS,EAAE;YACT,KAAK,EAAE;gBACL,WAAW,EAAE,6BAA6B;gBAC1C,OAAO,EAAE;oBACP,0BAA0B,EAAE;wBAC1B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE;qBAC7C;iBACF;aACF;YACD,KAAK,EAAE;gBACL,WAAW,EAAE,gBAAgB;aAC9B;SACF;KACF,CAAC;AACJ,CAAC;AAiBD,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,UAAiC,EAAE;IAEnC,MAAM,aAAa,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAE9C,oBAAoB,CAAC,aAAa,EAAE;QAClC,WAAW,EAAE,IAAI;QACjB,KAAK,EAAE,kBAAkB;KAC1B,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,sBAAsB,CACtC,OAAO,CAAC,OAAO,IAAI,IAAI,aAAa,EAAE,CACvC,CAAC;IAEF,IAAI,SAAS,KAAK,GAAG;QACnB,MAAM,IAAI,KAAK,CACb,qDAAqD,aAAa,0CAA0C,CAC7G,CAAC;IAEJ,oBAAoB,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE;QACjD,WAAW,EAAE,IAAI;QACjB,KAAK,EAAE,iBAAiB;KACzB,CAAC,CAAC;IAEH,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,UAAU;QACxE,MAAM,IAAI,KAAK,CACb,kDAAkD,aAAa,yBAAyB,CACzF,CAAC;IAEJ,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,aAAa,EAAE,CAAC,CAAC;IACzD,MAAM,UAAU,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAEhD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO;QAC1C,MAAM,IAAI,KAAK,CACb,6BAA6B,aAAa,gCAAgC,CAC3E,CAAC;IAEJ,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC;IAC7C,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IACrC,MAAM,aAAa,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IAElE,MAAM,YAAY,GAA4B;QAC5C,GAAG,EAAE,aAAa;QAClB,OAAO,EAAE,SAAS;QAClB,SAAS;QACT,UAAU;QACV,SAAS;QACT,OAAO;QACP,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO;KAC9B,CAAC;IAEF,qBAAqB,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;IAElD,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC;IAC7B,IAAI,YAAgD,CAAC;IAErD,MAAM,gBAAgB,GAAwB,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACtE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;YAChC,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,EAAE,aAAa,IAAI,SAAS,CAAC;YACpE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,CAAC,CAAC;YAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO;gBAC9B,CAAC,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;gBAC5C,CAAC,CAAC,SAAS,CAAC;YACd,MAAM,MAAM,GAAG,QAAQ,EAAE,SAAS,IAAI,EAAE,CAAC;YAEzC,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;gBAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;gBAE5B,IAAI,KAAK,KAAK,SAAS;oBACrB,MAAM,IAAI,KAAK,CACb,6CAA6C,KAAK,UAAU,aAAa,SAAS,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,WAAW,IAAI,CACpH,CAAC;gBAEJ,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC;oBAC3B,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC5B,CAAC;YAED,MAAM,WAAW,GAAG,gBAAgB,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;YAC5D,MAAM,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,EAAE,WAAW,EAAE;gBACxD,cAAc,EAAE,IAAI;aACrB,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ;gBAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;YAEvC,IAAI,CAAC,CAAC,MAAM,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBAC/C,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;YAE1B,IAAI,KAAe,CAAC;YAEpB,IAAI,CAAC;gBACH,KAAK,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC3C,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC1B,CAAC;YAED,GAAG,CAAC,OAAO,GAAG;gBACZ,GAAG,GAAG,CAAC,OAAO;gBACd,SAAS,EAAE,WAAW;gBACtB,UAAU,EAAE,QAAQ;gBACpB,UAAU,EAAE,KAAK,CAAC,MAAM,EAAE;oBACxB,CAAC,CAAC,MAAM;oBACR,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE;wBACnB,CAAC,CAAC,WAAW;wBACb,CAAC,CAAC,SAAS;aAChB,CAAC;YAEF,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU;gBAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;YAErD,IAAI,EAAE,CAAC;QACT,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,cAAc,GAAwB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC7D,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC;QAEzC,IAAI,GAAG,CAAC,OAAO,EAAE,UAAU,KAAK,MAAM,IAAI,CAAC,QAAQ;YACjD,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAE1B,GAAG,CAAC,GAAG,GAAG,IAAI,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,GACvD,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAChE,EAAE,CAAC;QAEH,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAClC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EACtB,kBAAkB,CAAC,OAAO,CAAC,aAAa,CAAC,CAC1C,CAAC;QAEF,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC,CAAC;IAEF,MAAM,WAAW,GAAwB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC1D,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC;QAEzC,IAAI,GAAG,CAAC,OAAO,EAAE,UAAU,KAAK,WAAW,IAAI,CAAC,QAAQ;YACtD,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAE1B,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,QAAQ,GAAI,GAAG,CAAC,MAAc,CAAC,QAAQ,CAAC;YAE9C,IACE,OAAO,QAAQ,KAAK,QAAQ;gBAC5B,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC;gBACtB,CAAC,gBAAgB,CAAC,QAAQ,CAAC;gBAE3B,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,MAAM,QAAQ,GAAI,GAAG,CAAC,MAAc,CAAC,CAAC,CAAuB,CAAC;YAE9D,IAAI,CAAC,QAAQ,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC;gBAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxE,CAAC;QAED,GAAG,CAAC,GAAG,GAAG,kBAAkB,CAAC,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;QAErD,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAE3D,IAAI,CAAC,OAAO;YACV,YAAY,KAAK,OAAO,CAAC,MAAM,CAC7B,QAAQ,EACR,kBAAkB,CAAC,OAAO,CAAC,aAAa,CAAC,CAC1C,CAAC;QAEJ,MAAM,aAAa,GACjB,YAAY;YACZ,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,kBAAkB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;QAEtE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC,CAAC;IAEF,MAAM,iBAAiB,GAAG,CACxB,GAAQ,EACR,GAAQ,EACR,IAAS,EACT,IAA2B,EAC3B,EAAE;QACF,IACE,GAAG,EAAE,IAAI,KAAK,QAAQ;YACtB,GAAG,EAAE,MAAM,KAAK,GAAG;YACnB,GAAG,EAAE,UAAU,KAAK,GAAG;YAEvB,OAAO,IAAI,CACT,IAAI,QAAQ,CACV,QAAQ,GAAG,CAAC,IAAI,gBAAgB,EAChC,GAAG,EACH,cAAc,EACd,EAAE,QAAQ,EAAE,GAAG,CAAC,IAAI,EAAE,CACvB,CACF,CAAC;QAEJ,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;IAE7C,MAAM,CAAC,GAAG,CACR;QACE,IAAI,EAAE,SAAS;QACf,YAAY,EAAE,EAAE,OAAO,EAAE;KAC1B,EACD,gBAAgB,EAChB,cAAc,EACd,iBAAwB,CACzB,CAAC;IAEF,MAAM,CAAC,GAAG,CACR;QACE,IAAI,EAAE,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,EAAE;QACtD,YAAY,EAAE,EAAE,OAAO,EAAE;KAC1B,EACD,gBAAgB,EAChB,WAAW,EACX,iBAAwB,CACzB,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import express from \"express\";\nimport fs from \"fs\";\nimport path from \"path\";\nimport AppError from \"../../../error-handler/utils/app-error\";\nimport { ArkosRequest, ArkosRequestHandler } from \"../../../../types\";\nimport type { UploadPrepare } from \"../../../../types/upload\";\nimport ArkosRouter from \"../../../../utils/arkos-router\";\nimport { IArkosRouter } from \"../../../../utils/arkos-router/types\";\nimport { extractPathParams } from \"../../../../utils/arkos-router/utils/helpers\";\nimport { getArkosConfig } from \"../../../../server\";\nimport deepmerge from \"../../../../utils/helpers/deepmerge.helper\";\nimport {\n  assertSafeUploadPath,\n  isRealPathInside,\n  isSafeUploadParam,\n  normalizeUploadDir,\n  normalizeUploadUrlPath,\n  resolveUploadPath,\n} from \"./upload-path.helper\";\nimport {\n  uploadServingRegistry,\n  UploadServeRegistration,\n} from \"./upload-serving.registry\";\n\nconst DEFAULT_STATIC_OPTIONS = {\n  maxAge: \"1y\",\n  etag: true,\n  lastModified: true,\n  dotfiles: \"ignore\",\n  fallthrough: false,\n  index: false,\n  cacheControl: true,\n};\n\nexport type ServeUploadDirOptions = {\n  /**\n   * Public URL folder, relative to the file upload `baseRoute`.\n   *\n   * @default `\"/\" + dir`\n   */\n  urlPath?: string;\n  /**\n   * Resolves the disk parameters for this folder. Required for every dynamic\n   * folder (`:param` in `dir`). It may be async and may throw to deny the\n   * request.\n   */\n  prepare?: UploadPrepare;\n  /**\n   * Options passed to `express.static`.\n   */\n  expressStatic?: Parameters<typeof express.static>[1];\n  /**\n   * Allow files in nested folders.\n   *\n   * @default false\n   */\n  recursive?: boolean;\n};\n\nfunction buildStaticOptions(\n  overrides?: Parameters<typeof express.static>[1]\n) {\n  const config = getArkosConfig();\n\n  return deepmerge(\n    deepmerge(DEFAULT_STATIC_OPTIONS, config.fileUpload?.expressStatic || {}),\n    overrides || {}\n  ) as Parameters<typeof express.static>[1];\n}\n\nfunction substituteParams(\n  template: string,\n  values: Record<string, string>\n): string {\n  return template\n    .split(\"/\")\n    .map((segment) =>\n      segment.startsWith(\":\") ? values[segment.slice(1)] : segment\n    )\n    .join(\"/\");\n}\n\nfunction stripMountSegments(url: string, segmentCount: number): string {\n  const queryIndex = url.indexOf(\"?\");\n  const rawPath = queryIndex === -1 ? url : url.slice(0, queryIndex);\n  const query = queryIndex === -1 ? \"\" : url.slice(queryIndex);\n  const parts = rawPath.split(\"/\");\n  const start = rawPath.startsWith(\"/\") ? segmentCount + 1 : segmentCount;\n  const remainder = parts.slice(start).join(\"/\");\n\n  return `/${remainder}${query}`;\n}\n\nfunction isSafeServedPath(value: string): boolean {\n  if (!value || value.includes(\"\\\\\") || value.includes(\"\\0\")) return false;\n\n  return value\n    .split(\"/\")\n    .every(\n      (segment) => segment !== \"\" && segment !== \".\" && segment !== \"..\"\n    );\n}\n\nfunction notFound() {\n  return new AppError(\"File not found\", 404, \"FileNotFound\");\n}\n\nfunction getLocals(req: ArkosRequest): Record<string, any> {\n  return req.res?.locals || {};\n}\n\nfunction openApiConfig(dir: string) {\n  return {\n    tags: [\"File Upload\"],\n    summary: \"Retrieve uploaded file\",\n    description: `Serves files from the \"${dir}\" upload directory.`,\n    responses: {\n      \"200\": {\n        description: \"File retrieved successfully\",\n        content: {\n          \"application/octet-stream\": {\n            schema: { type: \"string\", format: \"binary\" },\n          },\n        },\n      },\n      \"404\": {\n        description: \"File not found\",\n      },\n    },\n  };\n}\n\n/**\n * Serves a folder from the upload directory.\n *\n * Authentication belongs on the router mount:\n *\n * ```ts\n * fileUploadRouter.use(\n *   { authentication: fileUploadPolicy.View },\n *   arkos.serveUploadDir(\"/storage/acme\", { urlPath: \"/private/files\" })\n * );\n * ```\n *\n * When the resolved `dir` is a file, the route serves that file directly.\n * When it is a directory, the remainder of the request URL is served from it.\n */\nexport function serveUploadDir(\n  dir: string,\n  options: ServeUploadDirOptions = {}\n): IArkosRouter {\n  const normalizedDir = normalizeUploadDir(dir);\n\n  assertSafeUploadPath(normalizedDir, {\n    allowParams: true,\n    label: \"upload directory\",\n  });\n\n  const mountPath = normalizeUploadUrlPath(\n    options.urlPath ?? `/${normalizedDir}`\n  );\n\n  if (mountPath === \"/\")\n    throw new Error(\n      `Invalid upload URL path \"/\" for upload directory \"${normalizedDir}\": it must contain at least one segment.`\n    );\n\n  assertSafeUploadPath(mountPath.replace(/^\\//, \"\"), {\n    allowParams: true,\n    label: \"upload URL path\",\n  });\n\n  if (options.prepare !== undefined && typeof options.prepare !== \"function\")\n    throw new Error(\n      `Invalid prepare function for upload directory \"${normalizedDir}\": expected a function.`\n    );\n\n  const dirParams = extractPathParams(`/${normalizedDir}`);\n  const pathParams = extractPathParams(mountPath);\n\n  if (dirParams.length > 0 && !options.prepare)\n    throw new Error(\n      `Dynamic upload directory \"${normalizedDir}\" requires a prepare function.`\n    );\n\n  const recursive = options.recursive === true;\n  const dynamic = dirParams.length > 0;\n  const mountSegments = mountPath.split(\"/\").filter(Boolean).length;\n\n  const registration: UploadServeRegistration = {\n    dir: normalizedDir,\n    urlPath: mountPath,\n    dirParams,\n    pathParams,\n    recursive,\n    dynamic,\n    hasPrepare: !!options.prepare,\n  };\n\n  uploadServingRegistry.registerServe(registration);\n\n  const router = ArkosRouter();\n  let cachedStatic: express.RequestHandler | undefined;\n\n  const resolveDirectory: ArkosRequestHandler = async (req, _res, next) => {\n    try {\n      const config = getArkosConfig();\n      const baseUploadDir = config.fileUpload?.baseUploadDir || \"uploads\";\n      const basePath = path.resolve(process.cwd(), baseUploadDir);\n      const prepared = options.prepare\n        ? await options.prepare(req, getLocals(req))\n        : undefined;\n      const values = prepared?.dirParams ?? {};\n\n      for (const param of dirParams) {\n        const value = values[param];\n\n        if (value === undefined)\n          throw new Error(\n            `Missing required upload directory param \":${param}\" for \"${normalizedDir}\" on \"${req.method} ${req.originalUrl}\".`\n          );\n\n        if (!isSafeUploadParam(value))\n          return next(notFound());\n      }\n\n      const resolvedDir = substituteParams(normalizedDir, values);\n      const rootPath = resolveUploadPath(basePath, resolvedDir, {\n        strictSegments: true,\n      });\n\n      if (!rootPath) return next(notFound());\n\n      if (!(await isRealPathInside(basePath, rootPath)))\n        return next(notFound());\n\n      let stats: fs.Stats;\n\n      try {\n        stats = await fs.promises.stat(rootPath);\n      } catch {\n        return next(notFound());\n      }\n\n      req.__arkos = {\n        ...req.__arkos,\n        uploadDir: resolvedDir,\n        uploadPath: rootPath,\n        uploadKind: stats.isFile()\n          ? \"file\"\n          : stats.isDirectory()\n            ? \"directory\"\n            : undefined,\n      };\n\n      if (!req.__arkos.uploadKind) return next(notFound());\n\n      next();\n    } catch (error) {\n      next(error);\n    }\n  };\n\n  const serveExactFile: ArkosRequestHandler = (req, res, next) => {\n    const rootPath = req.__arkos?.uploadPath;\n\n    if (req.__arkos?.uploadKind !== \"file\" || !rootPath)\n      return next(notFound());\n\n    req.url = `/${encodeURIComponent(path.basename(rootPath))}${\n      req.url.includes(\"?\") ? req.url.slice(req.url.indexOf(\"?\")) : \"\"\n    }`;\n\n    const staticHandler = express.static(\n      path.dirname(rootPath),\n      buildStaticOptions(options.expressStatic)\n    );\n\n    staticHandler(req, res, next);\n  };\n\n  const serveFolder: ArkosRequestHandler = (req, res, next) => {\n    const rootPath = req.__arkos?.uploadPath;\n\n    if (req.__arkos?.uploadKind !== \"directory\" || !rootPath)\n      return next(notFound());\n\n    if (!recursive) {\n      const fileName = (req.params as any).fileName;\n\n      if (\n        typeof fileName !== \"string\" ||\n        fileName.includes(\"/\") ||\n        !isSafeServedPath(fileName)\n      )\n        return next(notFound());\n    } else {\n      const filePath = (req.params as any)[0] as string | undefined;\n\n      if (!filePath || !isSafeServedPath(filePath)) return next(notFound());\n    }\n\n    req.url = stripMountSegments(req.url, mountSegments);\n\n    if (req.url.split(\"?\")[0] === \"/\") return next(notFound());\n\n    if (!dynamic)\n      cachedStatic ??= express.static(\n        rootPath,\n        buildStaticOptions(options.expressStatic)\n      );\n\n    const staticHandler =\n      cachedStatic ??\n      express.static(rootPath, buildStaticOptions(options.expressStatic));\n\n    staticHandler(req, res, next);\n  };\n\n  const handleStaticError = (\n    err: any,\n    req: any,\n    _res: any,\n    next: (error?: any) => void\n  ) => {\n    if (\n      err?.code === \"ENOENT\" ||\n      err?.status === 403 ||\n      err?.statusCode === 403\n    )\n      return next(\n        new AppError(\n          `File ${req.path} was not found`,\n          404,\n          \"FileNotFound\",\n          { filepath: req.path }\n        )\n      );\n\n    next(err);\n  };\n\n  const openapi = openApiConfig(normalizedDir);\n\n  router.get(\n    {\n      path: mountPath,\n      experimental: { openapi },\n    },\n    resolveDirectory,\n    serveExactFile,\n    handleStaticError as any\n  );\n\n  router.get(\n    {\n      path: `${mountPath}${recursive ? \"/*\" : \"/:fileName\"}`,\n      experimental: { openapi },\n    },\n    resolveDirectory,\n    serveFolder,\n    handleStaticError as any\n  );\n\n  return router;\n}\n"]}

package/dist/esm/modules/file-upload/utils/helpers/upload-path.helper.js

@@ -0,0 +1,103 @@
+import fs from "fs";
+import path from "path";
+export const DEFAULT_UPLOAD_DIRS = [
+    "images",
+    "videos",
+    "documents",
+    "files",
+];
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const PARAM_SEGMENT = /^:[A-Za-z_][A-Za-z0-9_]*$/;
+const RESERVED_WINDOWS_NAMES = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/i;
+export function isSafeUploadSegment(segment, allowParam = false) {
+    if (!segment)
+        return false;
+    if (allowParam && PARAM_SEGMENT.test(segment))
+        return true;
+    if (!SAFE_SEGMENT.test(segment))
+        return false;
+    if (segment === "." || segment === "..")
+        return false;
+    if (/[. ]$/.test(segment))
+        return false;
+    if (RESERVED_WINDOWS_NAMES.test(segment))
+        return false;
+    return true;
+}
+export function assertSafeUploadPath(value, options = {}) {
+    const label = options.label || "upload path";
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`Invalid ${label}: it must be a non-empty string.`);
+    if (path.isAbsolute(value))
+        throw new Error(`Invalid ${label} "${value}": absolute paths are not allowed.`);
+    if (value.includes("\\") || value.includes("\0"))
+        throw new Error(`Invalid ${label} "${value}": backslashes and null bytes are not allowed.`);
+    for (const segment of value.split("/")) {
+        if (!segment || segment === "." || segment === "..")
+            throw new Error(`Invalid ${label} "${value}": empty, "." and ".." segments are not allowed.`);
+        if (!isSafeUploadSegment(segment, options.allowParams))
+            throw new Error(`Invalid ${label} "${value}": segment "${segment}" is not allowed. Use letters, numbers, ".", "_" and "-".`);
+    }
+    return value;
+}
+export function normalizeUploadDir(dir) {
+    return dir.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+export function normalizeUploadUrlPath(urlPath) {
+    let result = urlPath.startsWith("/") ? urlPath : `/${urlPath}`;
+    if (result.length > 1)
+        result = result.replace(/\/+$/, "");
+    return result;
+}
+export function isSafeUploadParam(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= 128 &&
+        SAFE_SEGMENT.test(value) &&
+        value !== "." &&
+        value !== ".." &&
+        !/[. ]$/.test(value) &&
+        !RESERVED_WINDOWS_NAMES.test(value));
+}
+export function isPathInside(base, target) {
+    const relative = path.relative(base, target);
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+}
+export function resolveUploadPath(root, relative, options = {}) {
+    if (typeof relative !== "string")
+        return null;
+    const cleaned = relative.replace(/^\/+/, "");
+    if (cleaned.includes("\0") || cleaned.includes("\\"))
+        return null;
+    if (cleaned === "")
+        return path.resolve(root);
+    for (const segment of cleaned.split("/")) {
+        if (!segment || segment === "." || segment === "..")
+            return null;
+        if (options.strictSegments && !isSafeUploadSegment(segment))
+            return null;
+    }
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(resolvedRoot, ...cleaned.split("/"));
+    if (!isPathInside(resolvedRoot, resolved))
+        return null;
+    return resolved;
+}
+export async function isRealPathInside(base, target) {
+    try {
+        const [realBase, realTarget] = await Promise.all([
+            fs.promises.realpath(base),
+            fs.promises.realpath(target),
+        ]);
+        return isPathInside(realBase, realTarget);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return true;
+        return false;
+    }
+}
+//# sourceMappingURL=upload-path.helper.js.map

package/dist/esm/modules/file-upload/utils/helpers/upload-path.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-path.helper.js","sourceRoot":"","sources":["../../../../../../src/modules/file-upload/utils/helpers/upload-path.helper.ts"],"names":[],"mappings":"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","sourcesContent":["import fs from \"fs\";\nimport path from \"path\";\n\nexport const DEFAULT_UPLOAD_DIRS = [\n  \"images\",\n  \"videos\",\n  \"documents\",\n  \"files\",\n] as const;\n\nconst SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;\nconst PARAM_SEGMENT = /^:[A-Za-z_][A-Za-z0-9_]*$/;\nconst RESERVED_WINDOWS_NAMES = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/i;\n\nexport function isSafeUploadSegment(\n  segment: string,\n  allowParam = false\n): boolean {\n  if (!segment) return false;\n  if (allowParam && PARAM_SEGMENT.test(segment)) return true;\n  if (!SAFE_SEGMENT.test(segment)) return false;\n  if (segment === \".\" || segment === \"..\") return false;\n  if (/[. ]$/.test(segment)) return false;\n  if (RESERVED_WINDOWS_NAMES.test(segment)) return false;\n  return true;\n}\n\nexport function assertSafeUploadPath(\n  value: string,\n  options: { allowParams?: boolean; label?: string } = {}\n) {\n  const label = options.label || \"upload path\";\n\n  if (typeof value !== \"string\" || value.length === 0)\n    throw new Error(`Invalid ${label}: it must be a non-empty string.`);\n\n  if (path.isAbsolute(value))\n    throw new Error(\n      `Invalid ${label} \"${value}\": absolute paths are not allowed.`\n    );\n\n  if (value.includes(\"\\\\\") || value.includes(\"\\0\"))\n    throw new Error(\n      `Invalid ${label} \"${value}\": backslashes and null bytes are not allowed.`\n    );\n\n  for (const segment of value.split(\"/\")) {\n    if (!segment || segment === \".\" || segment === \"..\")\n      throw new Error(\n        `Invalid ${label} \"${value}\": empty, \".\" and \"..\" segments are not allowed.`\n      );\n\n    if (!isSafeUploadSegment(segment, options.allowParams))\n      throw new Error(\n        `Invalid ${label} \"${value}\": segment \"${segment}\" is not allowed. Use letters, numbers, \".\", \"_\" and \"-\".`\n      );\n  }\n\n  return value;\n}\n\nexport function normalizeUploadDir(dir: string): string {\n  return dir.replace(/^\\/+/, \"\").replace(/\\/+$/, \"\");\n}\n\nexport function normalizeUploadUrlPath(urlPath: string): string {\n  let result = urlPath.startsWith(\"/\") ? urlPath : `/${urlPath}`;\n  if (result.length > 1) result = result.replace(/\\/+$/, \"\");\n  return result;\n}\n\nexport function isSafeUploadParam(value: unknown): value is string {\n  return (\n    typeof value === \"string\" &&\n    value.length > 0 &&\n    value.length <= 128 &&\n    SAFE_SEGMENT.test(value) &&\n    value !== \".\" &&\n    value !== \"..\" &&\n    !/[. ]$/.test(value) &&\n    !RESERVED_WINDOWS_NAMES.test(value)\n  );\n}\n\nexport function isPathInside(base: string, target: string): boolean {\n  const relative = path.relative(base, target);\n  return (\n    relative === \"\" ||\n    (!relative.startsWith(`..${path.sep}`) &&\n      relative !== \"..\" &&\n      !path.isAbsolute(relative))\n  );\n}\n\nexport function resolveUploadPath(\n  root: string,\n  relative: string,\n  options: { strictSegments?: boolean } = {}\n): string | null {\n  if (typeof relative !== \"string\") return null;\n\n  const cleaned = relative.replace(/^\\/+/, \"\");\n  if (cleaned.includes(\"\\0\") || cleaned.includes(\"\\\\\")) return null;\n  if (cleaned === \"\") return path.resolve(root);\n\n  for (const segment of cleaned.split(\"/\")) {\n    if (!segment || segment === \".\" || segment === \"..\") return null;\n    if (options.strictSegments && !isSafeUploadSegment(segment)) return null;\n  }\n\n  const resolvedRoot = path.resolve(root);\n  const resolved = path.resolve(resolvedRoot, ...cleaned.split(\"/\"));\n\n  if (!isPathInside(resolvedRoot, resolved)) return null;\n\n  return resolved;\n}\n\nexport async function isRealPathInside(\n  base: string,\n  target: string\n): Promise<boolean> {\n  try {\n    const [realBase, realTarget] = await Promise.all([\n      fs.promises.realpath(base),\n      fs.promises.realpath(target),\n    ]);\n\n    return isPathInside(realBase, realTarget);\n  } catch (error: any) {\n    if (error?.code === \"ENOENT\") return true;\n    return false;\n  }\n}\n"]}

package/dist/esm/modules/file-upload/utils/helpers/upload-serving-validation.js

@@ -0,0 +1,212 @@
+import sheu from "../../../../utils/sheu.js";
+import { getArkosConfig } from "../../../../server.js";
+import { extractPathParams } from "../../../../utils/arkos-router/utils/helpers/index.js";
+import { DEFAULT_UPLOAD_DIRS, assertSafeUploadPath, normalizeUploadDir, normalizeUploadUrlPath, } from "./upload-path.helper.js";
+import { uploadServingRegistry, } from "./upload-serving.registry.js";
+function isExactUrlPath(urlPath) {
+    return !!urlPath && typeof urlPath === "object";
+}
+function normalizeBaseRoute(baseRoute) {
+    const withLeadingSlash = baseRoute.startsWith("/")
+        ? baseRoute
+        : `/${baseRoute}`;
+    return withLeadingSlash.length > 1
+        ? withLeadingSlash.replace(/\/+$/, "")
+        : withLeadingSlash;
+}
+function assertUrlPathIsRelativeToBaseRoute(urlPath, baseRoute, route) {
+    const normalizedBaseRoute = normalizeBaseRoute(baseRoute);
+    if (urlPath === normalizedBaseRoute ||
+        urlPath.startsWith(`${normalizedBaseRoute}/`))
+        throw new Error(`Invalid urlPath "${urlPath}" on route "${route}": it is relative to baseRoute and must not include "${normalizedBaseRoute}".`);
+}
+function substitutePath(pathTemplate, params) {
+    return pathTemplate
+        .split("/")
+        .map((segment) => segment.startsWith(":") ? params[segment.slice(1)] : segment)
+        .join("/");
+}
+function matchDirTemplates(serveDir, writeDir, recursive) {
+    const serveSegments = normalizeUploadDir(serveDir).split("/");
+    const writeSegments = normalizeUploadDir(writeDir).split("/");
+    if (serveSegments.length > writeSegments.length)
+        return null;
+    if (serveSegments.length < writeSegments.length && !recursive)
+        return null;
+    const params = {};
+    for (let index = 0; index < serveSegments.length; index++) {
+        const serveSegment = serveSegments[index];
+        const writeSegment = writeSegments[index];
+        if (serveSegment.startsWith(":")) {
+            if (writeSegment.startsWith(":")) {
+                if (serveSegment.slice(1) !== writeSegment.slice(1))
+                    return null;
+                params[serveSegment.slice(1)] = serveSegment;
+            }
+            else
+                params[serveSegment.slice(1)] = writeSegment;
+        }
+        else if (serveSegment !== writeSegment)
+            return null;
+    }
+    return {
+        params,
+        matched: serveSegments.length,
+        remaining: writeSegments.slice(serveSegments.length),
+    };
+}
+function validateWriteUrlPath(registration, baseRoute) {
+    const { urlPath, route, dir } = registration;
+    if (urlPath === undefined)
+        return;
+    if (!dir)
+        throw new Error(`Route "${route}" declares urlPath but does not declare uploadDir.`);
+    if (isExactUrlPath(urlPath)) {
+        const exact = urlPath.exact;
+        if (typeof exact !== "string" || !exact.startsWith("/"))
+            throw new Error(`Invalid exact urlPath on route "${route}": it must be a string starting with "/".`);
+        if (exact.length > 1 && exact.endsWith("/"))
+            throw new Error(`Invalid exact urlPath "${exact}" on route "${route}": it must not end with "/".`);
+        if (exact === "/")
+            throw new Error(`Invalid exact urlPath "/" on route "${route}": it must contain at least one segment.`);
+        assertSafeUploadPath(exact.replace(/^\//, ""), {
+            label: "exact upload urlPath",
+        });
+        assertUrlPathIsRelativeToBaseRoute(exact, baseRoute, route);
+        if (registration.type === "array")
+            throw new Error(`Exact urlPath "${exact}" on route "${route}" cannot be used with array uploads because every file would share the same URL.`);
+        return;
+    }
+    if (!urlPath.startsWith("/"))
+        throw new Error(`Invalid urlPath "${urlPath}" on route "${route}": it must start with "/".`);
+    if (urlPath.endsWith("/"))
+        throw new Error(`Invalid urlPath "${urlPath}" on route "${route}": it must not end with "/".`);
+    assertSafeUploadPath(urlPath.replace(/^\//, ""), {
+        allowParams: true,
+        label: "upload urlPath",
+    });
+    assertUrlPathIsRelativeToBaseRoute(urlPath, baseRoute, route);
+}
+function warnAboutUnusedUrlParams(dir, urlPath, route, suppress) {
+    if (suppress)
+        return;
+    const dirParams = extractPathParams(`/${dir}`);
+    const unused = extractPathParams(urlPath).filter((param) => !dirParams.includes(param));
+    if (unused.length > 0)
+        sheu.warn(`Upload urlPath "${urlPath}" on route "${route}" declares ${unused
+            .map((param) => `":${param}"`)
+            .join(", ")} but uploadDir "${dir}" does not use them.`, { timestamp: true });
+}
+export function validateUploadServingConfig() {
+    const config = getArkosConfig();
+    const serving = config.fileUpload?.serving || "all";
+    const findFileEnabled = uploadServingRegistry.isFindFileServingEnabled();
+    const baseRoute = config.fileUpload?.baseRoute || "/api/uploads";
+    const suppressUnusedUrlParams = config.warnings?.fileUpload?.suppressUnusedUrlParams === true;
+    const serveRegistrations = uploadServingRegistry.getServeRegistrations();
+    const writeRegistrations = uploadServingRegistry.getWriteRegistrations();
+    const seenServePaths = new Map();
+    const seenServeDirs = new Map();
+    const seenExactWritePaths = new Map();
+    const warnedRoutes = new Set();
+    for (const registration of serveRegistrations) {
+        const dir = normalizeUploadDir(registration.dir);
+        const publicPath = normalizeUploadUrlPath(registration.urlPath);
+        const firstDirSegment = dir.split("/")[0];
+        const firstPathSegment = publicPath.replace(/^\//, "").split("/")[0];
+        if (registration.dynamic && !registration.hasPrepare)
+            throw new Error(`Dynamic upload directory "${dir}" requires a prepare function.`);
+        if (registration.pathParams.length > 0 && !suppressUnusedUrlParams) {
+            const unused = registration.pathParams.filter((param) => !registration.dirParams.includes(param));
+            if (unused.length > 0)
+                sheu.warn(`Upload URL path "${publicPath}" declares ${unused
+                    .map((param) => `":${param}"`)
+                    .join(", ")} but the upload directory "${dir}" does not use them.`, { timestamp: true });
+        }
+        if (findFileEnabled &&
+            DEFAULT_UPLOAD_DIRS.includes(firstDirSegment))
+            throw new Error(`Cannot serve upload directory "${dir}" with arkos.serveUploadDir(): "${firstDirSegment}" is a built-in upload root and is always served while findFile is enabled.`);
+        if (findFileEnabled &&
+            DEFAULT_UPLOAD_DIRS.includes(firstPathSegment))
+            throw new Error(`Cannot register upload URL path "${publicPath}": "/${firstPathSegment}" is a built-in upload root and is always served while findFile is enabled.`);
+        if (seenServePaths.has(publicPath))
+            throw new Error(`Duplicate upload serving path "${publicPath}" registered with arkos.serveUploadDir().`);
+        seenServePaths.set(publicPath, dir);
+        if (seenServeDirs.has(dir))
+            throw new Error(seenServeDirs.get(dir) === publicPath
+                ? `Duplicate arkos.serveUploadDir() registration for "${dir}".`
+                : `Upload directory "${dir}" is served at multiple paths: "${seenServeDirs.get(dir)}" and "${publicPath}".`);
+        seenServeDirs.set(dir, publicPath);
+    }
+    let warnedAboutAllMode = false;
+    for (const registration of writeRegistrations) {
+        const dir = registration.dir
+            ? normalizeUploadDir(registration.dir)
+            : undefined;
+        validateWriteUrlPath(registration, baseRoute);
+        if (!dir)
+            continue;
+        assertSafeUploadPath(dir, { allowParams: true, label: "uploadDir" });
+        const dirParams = extractPathParams(`/${dir}`);
+        if (dirParams.length > 0 && !registration.hasPrepare)
+            throw new Error(`Dynamic upload directory "${dir}" on route "${registration.route}" requires a prepare function.`);
+        if (registration.urlPath !== undefined &&
+            !isExactUrlPath(registration.urlPath)) {
+            const warningKey = `${registration.route}:${dir}:${registration.urlPath}`;
+            if (!warnedRoutes.has(warningKey)) {
+                warnAboutUnusedUrlParams(dir, registration.urlPath, registration.route, suppressUnusedUrlParams);
+                warnedRoutes.add(warningKey);
+            }
+        }
+        if (isExactUrlPath(registration.urlPath)) {
+            const exact = registration.urlPath.exact;
+            if (seenExactWritePaths.has(exact))
+                throw new Error(`Duplicate exact urlPath "${exact}" on route "${registration.route}"; it is already used on route "${seenExactWritePaths.get(exact)}".`);
+            seenExactWritePaths.set(exact, registration.route);
+            continue;
+        }
+        const firstDirSegment = dir.split("/")[0];
+        if (findFileEnabled &&
+            DEFAULT_UPLOAD_DIRS.includes(firstDirSegment))
+            continue;
+        if (serving === "all") {
+            if (!warnedAboutAllMode && serveRegistrations.length > 0) {
+                warningAboutAllMode();
+                warnedAboutAllMode = true;
+            }
+            continue;
+        }
+        if (registration.serve === false)
+            continue;
+        const writePublicPath = normalizeUploadUrlPath(registration.urlPath ?? `/${dir}`);
+        let bestMatch;
+        for (const serveRegistration of serveRegistrations) {
+            const match = matchDirTemplates(serveRegistration.dir, dir, serveRegistration.recursive);
+            if (!match)
+                continue;
+            if (!bestMatch || match.matched > bestMatch.match.matched) {
+                bestMatch = { registration: serveRegistration, match };
+                continue;
+            }
+            if (match.matched === bestMatch.match.matched &&
+                normalizeUploadUrlPath(serveRegistration.urlPath) !==
+                    normalizeUploadUrlPath(bestMatch.registration.urlPath))
+                throw new Error(`Upload directory "${dir}" on route "${registration.route}" is ambiguously served by "${bestMatch.registration.urlPath}" and "${serveRegistration.urlPath}".`);
+        }
+        if (!bestMatch)
+            throw new Error(`Upload directory "${dir}" used by route "${registration.route}" is not served. Register it with arkos.serveUploadDir("${dir}"), register one of its parent folders with arkos.serveUploadDir(parent, { recursive: true }), or set "serve: false" in the route's uploads config.`);
+        const servedPublicPath = normalizeUploadUrlPath(`${substitutePath(bestMatch.registration.urlPath, bestMatch.match.params)}${bestMatch.match.remaining.length
+            ? `/${bestMatch.match.remaining.join("/")}`
+            : ""}`);
+        if (servedPublicPath !== writePublicPath)
+            throw new Error(`Generated URL "${writePublicPath}" does not match served URL "${servedPublicPath}" for upload directory "${dir}".`);
+    }
+    if (serving === "all" &&
+        serveRegistrations.length > 0 &&
+        !warnedAboutAllMode)
+        warningAboutAllMode();
+}
+function warningAboutAllMode() {
+    sheu.warn(`fileUpload.serving is "all"; per-folder permissions registered via arkos.serveUploadDir() are not enforced.`, { timestamp: true });
+}
+//# sourceMappingURL=upload-serving-validation.js.map

package/dist/esm/modules/file-upload/utils/helpers/upload-serving-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-serving-validation.js","sourceRoot":"","sources":["../../../../../../src/modules/file-upload/utils/helpers/upload-serving-validation.ts"],"names":[],"mappings":"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","sourcesContent":["import sheu from \"../../../../utils/sheu\";\nimport { getArkosConfig } from \"../../../../server\";\nimport { extractPathParams } from \"../../../../utils/arkos-router/utils/helpers\";\nimport type { UploadUrlPath } from \"../../../../types/upload\";\nimport {\n  DEFAULT_UPLOAD_DIRS,\n  assertSafeUploadPath,\n  normalizeUploadDir,\n  normalizeUploadUrlPath,\n} from \"./upload-path.helper\";\nimport {\n  uploadServingRegistry,\n  UploadServeRegistration,\n  UploadWriteRegistration,\n} from \"./upload-serving.registry\";\n\ntype TemplateMatch = {\n  params: Record<string, string>;\n  matched: number;\n  remaining: string[];\n};\n\nfunction isExactUrlPath(\n  urlPath: UploadUrlPath | undefined\n): urlPath is { exact: string } {\n  return !!urlPath && typeof urlPath === \"object\";\n}\n\nfunction normalizeBaseRoute(baseRoute: string): string {\n  const withLeadingSlash = baseRoute.startsWith(\"/\")\n    ? baseRoute\n    : `/${baseRoute}`;\n\n  return withLeadingSlash.length > 1\n    ? withLeadingSlash.replace(/\\/+$/, \"\")\n    : withLeadingSlash;\n}\n\nfunction assertUrlPathIsRelativeToBaseRoute(\n  urlPath: string,\n  baseRoute: string,\n  route: string\n) {\n  const normalizedBaseRoute = normalizeBaseRoute(baseRoute);\n\n  if (\n    urlPath === normalizedBaseRoute ||\n    urlPath.startsWith(`${normalizedBaseRoute}/`)\n  )\n    throw new Error(\n      `Invalid urlPath \"${urlPath}\" on route \"${route}\": it is relative to baseRoute and must not include \"${normalizedBaseRoute}\".`\n    );\n}\n\nfunction substitutePath(\n  pathTemplate: string,\n  params: Record<string, string>\n): string {\n  return pathTemplate\n    .split(\"/\")\n    .map((segment) =>\n      segment.startsWith(\":\") ? params[segment.slice(1)] : segment\n    )\n    .join(\"/\");\n}\n\nfunction matchDirTemplates(\n  serveDir: string,\n  writeDir: string,\n  recursive: boolean\n): TemplateMatch | null {\n  const serveSegments = normalizeUploadDir(serveDir).split(\"/\");\n  const writeSegments = normalizeUploadDir(writeDir).split(\"/\");\n\n  if (serveSegments.length > writeSegments.length) return null;\n  if (serveSegments.length < writeSegments.length && !recursive) return null;\n\n  const params: Record<string, string> = {};\n\n  for (let index = 0; index < serveSegments.length; index++) {\n    const serveSegment = serveSegments[index];\n    const writeSegment = writeSegments[index];\n\n    if (serveSegment.startsWith(\":\")) {\n      if (writeSegment.startsWith(\":\")) {\n        if (serveSegment.slice(1) !== writeSegment.slice(1)) return null;\n        params[serveSegment.slice(1)] = serveSegment;\n      } else params[serveSegment.slice(1)] = writeSegment;\n    } else if (serveSegment !== writeSegment) return null;\n  }\n\n  return {\n    params,\n    matched: serveSegments.length,\n    remaining: writeSegments.slice(serveSegments.length),\n  };\n}\n\nfunction validateWriteUrlPath(\n  registration: UploadWriteRegistration,\n  baseRoute: string\n) {\n  const { urlPath, route, dir } = registration;\n\n  if (urlPath === undefined) return;\n\n  if (!dir)\n    throw new Error(\n      `Route \"${route}\" declares urlPath but does not declare uploadDir.`\n    );\n\n  if (isExactUrlPath(urlPath)) {\n    const exact = urlPath.exact;\n\n    if (typeof exact !== \"string\" || !exact.startsWith(\"/\"))\n      throw new Error(\n        `Invalid exact urlPath on route \"${route}\": it must be a string starting with \"/\".`\n      );\n\n    if (exact.length > 1 && exact.endsWith(\"/\"))\n      throw new Error(\n        `Invalid exact urlPath \"${exact}\" on route \"${route}\": it must not end with \"/\".`\n      );\n\n    if (exact === \"/\")\n      throw new Error(\n        `Invalid exact urlPath \"/\" on route \"${route}\": it must contain at least one segment.`\n      );\n\n    assertSafeUploadPath(exact.replace(/^\\//, \"\"), {\n      label: \"exact upload urlPath\",\n    });\n\n    assertUrlPathIsRelativeToBaseRoute(exact, baseRoute, route);\n\n    if (registration.type === \"array\")\n      throw new Error(\n        `Exact urlPath \"${exact}\" on route \"${route}\" cannot be used with array uploads because every file would share the same URL.`\n      );\n\n    return;\n  }\n\n  if (!urlPath.startsWith(\"/\"))\n    throw new Error(\n      `Invalid urlPath \"${urlPath}\" on route \"${route}\": it must start with \"/\".`\n    );\n\n  if (urlPath.endsWith(\"/\"))\n    throw new Error(\n      `Invalid urlPath \"${urlPath}\" on route \"${route}\": it must not end with \"/\".`\n    );\n\n  assertSafeUploadPath(urlPath.replace(/^\\//, \"\"), {\n    allowParams: true,\n    label: \"upload urlPath\",\n  });\n\n  assertUrlPathIsRelativeToBaseRoute(urlPath, baseRoute, route);\n}\n\nfunction warnAboutUnusedUrlParams(\n  dir: string,\n  urlPath: string,\n  route: string,\n  suppress: boolean\n) {\n  if (suppress) return;\n\n  const dirParams = extractPathParams(`/${dir}`);\n  const unused = extractPathParams(urlPath).filter(\n    (param) => !dirParams.includes(param)\n  );\n\n  if (unused.length > 0)\n    sheu.warn(\n      `Upload urlPath \"${urlPath}\" on route \"${route}\" declares ${unused\n        .map((param) => `\":${param}\"`)\n        .join(\", \")} but uploadDir \"${dir}\" does not use them.`,\n      { timestamp: true }\n    );\n}\n\n/**\n * Validates the upload serving registrations collected while building the\n * routers. Must run once, after every router has been constructed.\n */\nexport function validateUploadServingConfig() {\n  const config = getArkosConfig();\n  const serving = config.fileUpload?.serving || \"all\";\n  const findFileEnabled = uploadServingRegistry.isFindFileServingEnabled();\n  const baseRoute = config.fileUpload?.baseRoute || \"/api/uploads\";\n  const suppressUnusedUrlParams =\n    config.warnings?.fileUpload?.suppressUnusedUrlParams === true;\n  const serveRegistrations = uploadServingRegistry.getServeRegistrations();\n  const writeRegistrations = uploadServingRegistry.getWriteRegistrations();\n\n  const seenServePaths = new Map<string, string>();\n  const seenServeDirs = new Map<string, string>();\n  const seenExactWritePaths = new Map<string, string>();\n  const warnedRoutes = new Set<string>();\n\n  for (const registration of serveRegistrations) {\n    const dir = normalizeUploadDir(registration.dir);\n    const publicPath = normalizeUploadUrlPath(registration.urlPath);\n    const firstDirSegment = dir.split(\"/\")[0];\n    const firstPathSegment = publicPath.replace(/^\\//, \"\").split(\"/\")[0];\n\n    if (registration.dynamic && !registration.hasPrepare)\n      throw new Error(\n        `Dynamic upload directory \"${dir}\" requires a prepare function.`\n      );\n\n    if (registration.pathParams.length > 0 && !suppressUnusedUrlParams) {\n      const unused = registration.pathParams.filter(\n        (param) => !registration.dirParams.includes(param)\n      );\n\n      if (unused.length > 0)\n        sheu.warn(\n          `Upload URL path \"${publicPath}\" declares ${unused\n            .map((param) => `\":${param}\"`)\n            .join(\", \")} but the upload directory \"${dir}\" does not use them.`,\n          { timestamp: true }\n        );\n    }\n\n    if (\n      findFileEnabled &&\n      (DEFAULT_UPLOAD_DIRS as readonly string[]).includes(firstDirSegment)\n    )\n      throw new Error(\n        `Cannot serve upload directory \"${dir}\" with arkos.serveUploadDir(): \"${firstDirSegment}\" is a built-in upload root and is always served while findFile is enabled.`\n      );\n\n    if (\n      findFileEnabled &&\n      (DEFAULT_UPLOAD_DIRS as readonly string[]).includes(firstPathSegment)\n    )\n      throw new Error(\n        `Cannot register upload URL path \"${publicPath}\": \"/${firstPathSegment}\" is a built-in upload root and is always served while findFile is enabled.`\n      );\n\n    if (seenServePaths.has(publicPath))\n      throw new Error(\n        `Duplicate upload serving path \"${publicPath}\" registered with arkos.serveUploadDir().`\n      );\n\n    seenServePaths.set(publicPath, dir);\n\n    if (seenServeDirs.has(dir))\n      throw new Error(\n        seenServeDirs.get(dir) === publicPath\n          ? `Duplicate arkos.serveUploadDir() registration for \"${dir}\".`\n          : `Upload directory \"${dir}\" is served at multiple paths: \"${seenServeDirs.get(\n              dir\n            )}\" and \"${publicPath}\".`\n      );\n\n    seenServeDirs.set(dir, publicPath);\n  }\n\n  let warnedAboutAllMode = false;\n\n  for (const registration of writeRegistrations) {\n    const dir = registration.dir\n      ? normalizeUploadDir(registration.dir)\n      : undefined;\n\n    validateWriteUrlPath(registration, baseRoute);\n\n    if (!dir) continue;\n\n    assertSafeUploadPath(dir, { allowParams: true, label: \"uploadDir\" });\n\n    const dirParams = extractPathParams(`/${dir}`);\n\n    if (dirParams.length > 0 && !registration.hasPrepare)\n      throw new Error(\n        `Dynamic upload directory \"${dir}\" on route \"${registration.route}\" requires a prepare function.`\n      );\n\n    if (\n      registration.urlPath !== undefined &&\n      !isExactUrlPath(registration.urlPath)\n    ) {\n      const warningKey = `${registration.route}:${dir}:${registration.urlPath}`;\n\n      if (!warnedRoutes.has(warningKey)) {\n        warnAboutUnusedUrlParams(\n          dir,\n          registration.urlPath,\n          registration.route,\n          suppressUnusedUrlParams\n        );\n        warnedRoutes.add(warningKey);\n      }\n    }\n\n    if (isExactUrlPath(registration.urlPath)) {\n      const exact = registration.urlPath.exact;\n\n      if (seenExactWritePaths.has(exact))\n        throw new Error(\n          `Duplicate exact urlPath \"${exact}\" on route \"${registration.route}\"; it is already used on route \"${seenExactWritePaths.get(\n            exact\n          )}\".`\n        );\n\n      seenExactWritePaths.set(exact, registration.route);\n      continue;\n    }\n\n    const firstDirSegment = dir.split(\"/\")[0];\n\n    if (\n      findFileEnabled &&\n      (DEFAULT_UPLOAD_DIRS as readonly string[]).includes(firstDirSegment)\n    )\n      continue;\n\n    if (serving === \"all\") {\n      if (!warnedAboutAllMode && serveRegistrations.length > 0) {\n        warningAboutAllMode();\n        warnedAboutAllMode = true;\n      }\n      continue;\n    }\n\n    if (registration.serve === false) continue;\n\n    const writePublicPath = normalizeUploadUrlPath(\n      registration.urlPath ?? `/${dir}`\n    );\n\n    let bestMatch:\n      | { registration: UploadServeRegistration; match: TemplateMatch }\n      | undefined;\n\n    for (const serveRegistration of serveRegistrations) {\n      const match = matchDirTemplates(\n        serveRegistration.dir,\n        dir,\n        serveRegistration.recursive\n      );\n\n      if (!match) continue;\n\n      if (!bestMatch || match.matched > bestMatch.match.matched) {\n        bestMatch = { registration: serveRegistration, match };\n        continue;\n      }\n\n      if (\n        match.matched === bestMatch.match.matched &&\n        normalizeUploadUrlPath(serveRegistration.urlPath) !==\n          normalizeUploadUrlPath(bestMatch.registration.urlPath)\n      )\n        throw new Error(\n          `Upload directory \"${dir}\" on route \"${registration.route}\" is ambiguously served by \"${bestMatch.registration.urlPath}\" and \"${serveRegistration.urlPath}\".`\n        );\n    }\n\n    if (!bestMatch)\n      throw new Error(\n        `Upload directory \"${dir}\" used by route \"${registration.route}\" is not served. Register it with arkos.serveUploadDir(\"${dir}\"), register one of its parent folders with arkos.serveUploadDir(parent, { recursive: true }), or set \"serve: false\" in the route's uploads config.`\n      );\n\n    const servedPublicPath = normalizeUploadUrlPath(\n      `${substitutePath(bestMatch.registration.urlPath, bestMatch.match.params)}${\n        bestMatch.match.remaining.length\n          ? `/${bestMatch.match.remaining.join(\"/\")}`\n          : \"\"\n      }`\n    );\n\n    if (servedPublicPath !== writePublicPath)\n      throw new Error(\n        `Generated URL \"${writePublicPath}\" does not match served URL \"${servedPublicPath}\" for upload directory \"${dir}\".`\n      );\n  }\n\n  if (\n    serving === \"all\" &&\n    serveRegistrations.length > 0 &&\n    !warnedAboutAllMode\n  )\n    warningAboutAllMode();\n}\n\nfunction warningAboutAllMode() {\n  sheu.warn(\n    `fileUpload.serving is \"all\"; per-folder permissions registered via arkos.serveUploadDir() are not enforced.`,\n    { timestamp: true }\n  );\n}\n"]}