@venizia/ignis 0.2.0 → 0.2.1-0

package/dist/components/static-asset/controller/factory.js

@@ -19,6 +19,9 @@ const node_fs_1 = require("node:fs");
 const common_2 = require("../common");
 const common_3 = require("../common");
 const base_definition_1 = require("./base.definition");
+const key_scope_1 = require("./key-scope");
+const meta_link_1 = require("./meta-link");
+const route_options_1 = require("./route-options");
 /** Hono ALREADY percent-decodes path params - a second decodeURIComponent throws on `report_100%.pdf` and turns `a%2Fb.png` into a DIFFERENT object; `isValidName`/`isValidPath` still run on this value, so traversal is still rejected. */
 /** The upload labels, read off the multipart form. Every value arrives as text, so `sequence` is the one that needs converting. */
 /** One list: the reader below and the stale-caller warning must agree. */
@@ -144,37 +147,6 @@ const applyMetadataHeaders = ({ ctx, metadata }) => {
         ctx.header(key.toLowerCase(), String(value).replace(/[\r\n]/g, ''));
     });
 };
-/** The MetaLink row for one uploaded object. Both upload paths go through here, so a direct upload lands exactly the row an ordinary one does. */
-const createMetaLinkRow = async (opts) => {
-    const { metaLink, helper, storage, uploadResult, fileStat, query } = opts;
-    if (metaLink.createMetaLink) {
-        const created = await metaLink.createMetaLink({ uploadResult, fileStat, query });
-        return created.data;
-    }
-    // Resolved per call so an application that swaps the repository is not pinned to the first one.
-    const repository = await (0, common_1.resolveValueAsync)({ value: metaLink.repository });
-    const created = await repository.create({
-        data: {
-            bucketName: uploadResult.bucket.name,
-            objectName: uploadResult.object.key,
-            link: uploadResult.link,
-            // The column is NOT NULL and a backend may report nothing.
-            mimetype: fileStat.metadata?.mimetype ?? helper.getMimeType({ filename: uploadResult.object.key }),
-            size: fileStat.size,
-            etag: fileStat.etag,
-            metadata: fileStat.metadata,
-            storageType: storage,
-            isSynced: true,
-            principalId: query.principalId ? String(query.principalId) : undefined,
-            principalType: query.principalType ? String(query.principalType) : undefined,
-            variant: query.variant ? String(query.variant) : undefined,
-            // Absent leaves the column default rather than writing 0, so a row the caller never
-            // ordered is indistinguishable from a legacy one.
-            sequence: query.sequence === undefined ? undefined : Number(query.sequence),
-        },
-    });
-    return created.data;
-};
 class AssetControllerFactory extends core_1.BaseHelper {
     constructor() {
         super({ scope: AssetControllerFactory.name });
@@ -187,6 +159,20 @@ class AssetControllerFactory extends core_1.BaseHelper {
         const maxFolderDepth = options?.maxFolderDepth ?? ignis_helpers_1.BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH;
         const maxBytes = options?.maxBytes;
         const hasConfiguredBucket = bucket !== undefined;
+        // With the bucket in the URL, the bucket routes stay unscoped and the scope spans every bucket.
+        if (controller.keyPrefix !== undefined && !hasConfiguredBucket) {
+            throw (0, core_1.getError)({
+                message: `[${name}] keyPrefix needs controller.bucket | a bucket in the URL is a bucket the caller chooses, and the bucket routes cannot be scoped`,
+            });
+        }
+        const scope = controller.keyPrefix === undefined
+            ? undefined
+            : (0, key_scope_1.normalizeKeyPrefix)({ keyPrefix: controller.keyPrefix, helper, scope: name });
+        const keyPrefix = scope?.keyPrefix;
+        // `maxFolderDepth` counts the caller's folders; the scope's own are configuration, not input.
+        const objectKeyMaxDepth = maxFolderDepth + (scope?.depth ?? 0);
+        // The component's own name under a scope: the original name must stay one segment, as without one.
+        const isScopedDefaultNaming = keyPrefix !== undefined && !resolveObjectName && !options?.normalizeNameFn;
         const definitions = (0, base_definition_1.buildAssetDefinitions)({ hasConfiguredBucket, rawObjectPath });
         // The mount path may be declared with or without a leading slash; a link must carry exactly one.
         const normalizedBasePath = basePath.startsWith('/') ? basePath : `/${basePath}`;
@@ -228,16 +214,81 @@ class AssetControllerFactory extends core_1.BaseHelper {
                 // A single-bucket application has no reason to expose bucket creation or deletion, so the
                 // four bucket-management routes are not registered once `bucket` is configured.
                 if (!hasConfiguredBucket) {
+                    const getBucketsRoute = (0, route_options_1.readRouteOverride)({ route: routes?.getBuckets });
+                    if (getBucketsRoute.isEnabled) {
+                        this.bindRoute({
+                            configs: { ...definitions.GET_BUCKETS, ...getBucketsRoute.override },
+                        }).to({
+                            handler: async (ctx) => {
+                                const buckets = await helper.getBuckets();
+                                return ctx.json(buckets, common_1.HTTP.ResultCodes.RS_2.Ok);
+                            },
+                        });
+                    }
+                    const getBucketByNameRoute = (0, route_options_1.readRouteOverride)({ route: routes?.getBucketByName });
+                    if (getBucketByNameRoute.isEnabled) {
+                        this.bindRoute({
+                            configs: { ...definitions.GET_BUCKET_BY_NAME, ...getBucketByNameRoute.override },
+                        }).to({
+                            handler: async (ctx) => {
+                                const params = ctx.req.valid('param');
+                                const bucketName = await resolveBucket({
+                                    configured: bucket,
+                                    param: params.bucketName,
+                                });
+                                if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
+                                    throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
+                                }
+                                const found = await helper.getBucket({ bucket: { name: bucketName } });
+                                return ctx.json(found, common_1.HTTP.ResultCodes.RS_2.Ok);
+                            },
+                        });
+                    }
+                    const createBucketRoute = (0, route_options_1.readRouteOverride)({ route: routes?.createBucket });
+                    if (createBucketRoute.isEnabled) {
+                        this.bindRoute({
+                            configs: { ...definitions.CREATE_BUCKET, ...createBucketRoute.override },
+                        }).to({
+                            handler: async (ctx) => {
+                                const params = ctx.req.valid('param');
+                                const bucketName = await resolveBucket({
+                                    configured: bucket,
+                                    param: params.bucketName,
+                                });
+                                if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
+                                    throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
+                                }
+                                const createdBucket = await helper.createBucket({ bucket: { name: bucketName } });
+                                return ctx.json(createdBucket, common_1.HTTP.ResultCodes.RS_2.Ok);
+                            },
+                        });
+                    }
+                    const deleteBucketRoute = (0, route_options_1.readRouteOverride)({ route: routes?.deleteBucket });
+                    if (deleteBucketRoute.isEnabled) {
+                        this.bindRoute({
+                            configs: { ...definitions.DELETE_BUCKET, ...deleteBucketRoute.override },
+                        }).to({
+                            handler: async (ctx) => {
+                                const params = ctx.req.valid('param');
+                                const bucketName = await resolveBucket({
+                                    configured: bucket,
+                                    param: params.bucketName,
+                                });
+                                if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
+                                    throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
+                                }
+                                const isRemovedBucket = await helper.removeBucket({
+                                    bucket: { name: bucketName },
+                                });
+                                return ctx.json({ isDeleted: isRemovedBucket }, common_1.HTTP.ResultCodes.RS_2.Ok);
+                            },
+                        });
+                    }
+                }
+                const getObjectByNameRoute = (0, route_options_1.readRouteOverride)({ route: routes?.getObjectByName });
+                if (getObjectByNameRoute.isEnabled) {
                     this.bindRoute({
-                        configs: { ...definitions.GET_BUCKETS, ...routes?.getBuckets },
-                    }).to({
-                        handler: async (ctx) => {
-                            const buckets = await helper.getBuckets();
-                            return ctx.json(buckets, common_1.HTTP.ResultCodes.RS_2.Ok);
-                        },
-                    });
-                    this.bindRoute({
-                        configs: { ...definitions.GET_BUCKET_BY_NAME, ...routes?.getBucketByName },
+                        configs: { ...definitions.GET_OBJECT_BY_NAME, ...getObjectByNameRoute.override },
                     }).to({
                         handler: async (ctx) => {
                             const params = ctx.req.valid('param');
@@ -245,31 +296,66 @@ class AssetControllerFactory extends core_1.BaseHelper {
                                 configured: bucket,
                                 param: params.bucketName,
                             });
+                            const objectName = readObjectName(params.objectName);
                             if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
                                 throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
                             }
-                            const found = await helper.getBucket({ bucket: { name: bucketName } });
-                            return ctx.json(found, common_1.HTTP.ResultCodes.RS_2.Ok);
-                        },
-                    });
-                    this.bindRoute({
-                        configs: { ...definitions.CREATE_BUCKET, ...routes?.createBucket },
-                    }).to({
-                        handler: async (ctx) => {
-                            const params = ctx.req.valid('param');
-                            const bucketName = await resolveBucket({
-                                configured: bucket,
-                                param: params.bucketName,
+                            if (!helper.isValidObjectKey({
+                                object: { key: objectName },
+                                maxDepth: objectKeyMaxDepth,
+                            })) {
+                                throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.OBJECT_NAME_INVALID });
+                            }
+                            // Before any storage call: a key outside the scope must not even be probed.
+                            (0, key_scope_1.assertKeyInScope)({ key: objectName, keyPrefix });
+                            const fileStat = await helper.getStat({
+                                bucket: { name: bucketName },
+                                object: { key: objectName },
                             });
-                            if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
-                                throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
+                            const { size, metadata } = fileStat;
+                            applyMetadataHeaders({ ctx, metadata });
+                            const served = (0, exports.resolveServedContentType)({ helper, object: { key: objectName } });
+                            ctx.header(common_1.HTTP.Headers.CONTENT_TYPE, served.contentType);
+                            ctx.header('x-content-type-options', 'nosniff');
+                            // Sandboxed even when renderable, so an unforeseen renderable type cannot reach this origin.
+                            ctx.header(common_1.HTTP.Headers.CONTENT_SECURITY_POLICY, 'sandbox');
+                            // Advertised unconditionally: a player only offers seeking once it sees this.
+                            ctx.header('accept-ranges', 'bytes');
+                            // A type outside the allow-list downloads instead of rendering; that is the XSS boundary.
+                            if (!served.isRenderable) {
+                                const inlineName = objectName.split('/').pop() ?? objectName;
+                                ctx.header(common_1.HTTP.Headers.CONTENT_DISPOSITION, (0, ignis_helpers_1.createContentDispositionHeader)({ filename: inlineName, type: 'attachment' }));
+                            }
+                            const range = readByteRange({ header: ctx.req.header('range'), size });
+                            if (range) {
+                                ctx.header(common_1.HTTP.Headers.CONTENT_LENGTH, String(range.end - range.start + 1));
+                                ctx.header(common_1.HTTP.Headers.CONTENT_RANGE, `bytes ${range.start}-${range.end}/${size}`);
                             }
-                            const createdBucket = await helper.createBucket({ bucket: { name: bucketName } });
-                            return ctx.json(createdBucket, common_1.HTTP.ResultCodes.RS_2.Ok);
+                            else {
+                                ctx.header(common_1.HTTP.Headers.CONTENT_LENGTH, size.toString());
+                            }
+                            // The web stream is what a Response body wants, so no Node Readable sits in between.
+                            const stream = await helper.getObjectStream({
+                                bucket: { name: bucketName },
+                                object: { key: objectName },
+                                ...(range ? { range } : {}),
+                            });
+                            return new Response(stream, {
+                                headers: ctx.res.headers,
+                                status: range ? common_1.HTTP.ResultCodes.RS_2.PartialContent : common_1.HTTP.ResultCodes.RS_2.Ok,
+                            });
                         },
                     });
+                }
+                const downloadObjectByNameRoute = (0, route_options_1.readRouteOverride)({
+                    route: routes?.downloadObjectByName,
+                });
+                if (downloadObjectByNameRoute.isEnabled) {
                     this.bindRoute({
-                        configs: { ...definitions.DELETE_BUCKET, ...routes?.deleteBucket },
+                        configs: {
+                            ...definitions.DOWNLOAD_OBJECT_BY_NAME,
+                            ...downloadObjectByNameRoute.override,
+                        },
                     }).to({
                         handler: async (ctx) => {
                             const params = ctx.req.valid('param');
@@ -277,500 +363,215 @@ class AssetControllerFactory extends core_1.BaseHelper {
                                 configured: bucket,
                                 param: params.bucketName,
                             });
+                            const objectName = readObjectName(params.objectName);
                             if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
                                 throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
                             }
-                            const isRemovedBucket = await helper.removeBucket({
+                            if (!helper.isValidObjectKey({
+                                object: { key: objectName },
+                                maxDepth: objectKeyMaxDepth,
+                            })) {
+                                throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.OBJECT_NAME_INVALID });
+                            }
+                            // Before any storage call: a key outside the scope must not even be probed.
+                            (0, key_scope_1.assertKeyInScope)({ key: objectName, keyPrefix });
+                            const fileStat = await helper.getStat({
                                 bucket: { name: bucketName },
+                                object: { key: objectName },
+                            });
+                            const { size, metadata } = fileStat;
+                            applyMetadataHeaders({ ctx, metadata });
+                            // Download always attaches, so the served type only has to be honest, never renderable.
+                            const served = (0, exports.resolveServedContentType)({ helper, object: { key: objectName } });
+                            ctx.header(common_1.HTTP.Headers.CONTENT_TYPE, served.contentType);
+                            ctx.header(common_1.HTTP.Headers.CONTENT_LENGTH, size.toString());
+                            const fileName = objectName.split('/').pop() ?? objectName;
+                            ctx.header(common_1.HTTP.Headers.CONTENT_DISPOSITION, (0, ignis_helpers_1.createContentDispositionHeader)({ filename: fileName, type: 'attachment' }));
+                            ctx.header('x-content-type-options', 'nosniff');
+                            ctx.header(common_1.HTTP.Headers.CONTENT_SECURITY_POLICY, 'sandbox');
+                            const stream = await helper.getObjectStream({
+                                bucket: { name: bucketName },
+                                object: { key: objectName },
+                            });
+                            return new Response(stream, {
+                                headers: ctx.res.headers,
+                                status: common_1.HTTP.ResultCodes.RS_2.Ok,
                             });
-                            return ctx.json({ isDeleted: isRemovedBucket }, common_1.HTTP.ResultCodes.RS_2.Ok);
                         },
                     });
                 }
-                this.bindRoute({
-                    configs: { ...definitions.GET_OBJECT_BY_NAME, ...routes?.getObjectByName },
-                }).to({
-                    handler: async (ctx) => {
-                        const params = ctx.req.valid('param');
-                        const bucketName = await resolveBucket({
-                            configured: bucket,
-                            param: params.bucketName,
-                        });
-                        const objectName = readObjectName(params.objectName);
-                        if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
-                            throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
-                        }
-                        if (!helper.isValidObjectKey({ object: { key: objectName }, maxDepth: maxFolderDepth })) {
-                            throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.OBJECT_NAME_INVALID });
-                        }
-                        const fileStat = await helper.getStat({
-                            bucket: { name: bucketName },
-                            object: { key: objectName },
-                        });
-                        const { size, metadata } = fileStat;
-                        applyMetadataHeaders({ ctx, metadata });
-                        const served = (0, exports.resolveServedContentType)({ helper, object: { key: objectName } });
-                        ctx.header(common_1.HTTP.Headers.CONTENT_TYPE, served.contentType);
-                        ctx.header('x-content-type-options', 'nosniff');
-                        // Sandboxed even when renderable, so an unforeseen renderable type cannot reach this origin.
-                        ctx.header(common_1.HTTP.Headers.CONTENT_SECURITY_POLICY, 'sandbox');
-                        // Advertised unconditionally: a player only offers seeking once it sees this.
-                        ctx.header('accept-ranges', 'bytes');
-                        // A type outside the allow-list downloads instead of rendering; that is the XSS boundary.
-                        if (!served.isRenderable) {
-                            const inlineName = objectName.split('/').pop() ?? objectName;
-                            ctx.header(common_1.HTTP.Headers.CONTENT_DISPOSITION, (0, ignis_helpers_1.createContentDispositionHeader)({ filename: inlineName, type: 'attachment' }));
-                        }
-                        const range = readByteRange({ header: ctx.req.header('range'), size });
-                        if (range) {
-                            ctx.header(common_1.HTTP.Headers.CONTENT_LENGTH, String(range.end - range.start + 1));
-                            ctx.header(common_1.HTTP.Headers.CONTENT_RANGE, `bytes ${range.start}-${range.end}/${size}`);
-                        }
-                        else {
-                            ctx.header(common_1.HTTP.Headers.CONTENT_LENGTH, size.toString());
-                        }
-                        // The web stream is what a Response body wants, so no Node Readable sits in between.
-                        const stream = await helper.getObjectStream({
-                            bucket: { name: bucketName },
-                            object: { key: objectName },
-                            ...(range ? { range } : {}),
-                        });
-                        return new Response(stream, {
-                            headers: ctx.res.headers,
-                            status: range ? common_1.HTTP.ResultCodes.RS_2.PartialContent : common_1.HTTP.ResultCodes.RS_2.Ok,
-                        });
-                    },
-                });
-                this.bindRoute({
-                    configs: {
-                        ...definitions.DOWNLOAD_OBJECT_BY_NAME,
-                        ...routes?.downloadObjectByName,
-                    },
-                }).to({
-                    handler: async (ctx) => {
-                        const params = ctx.req.valid('param');
-                        const bucketName = await resolveBucket({
-                            configured: bucket,
-                            param: params.bucketName,
-                        });
-                        const objectName = readObjectName(params.objectName);
-                        if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
-                            throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
-                        }
-                        if (!helper.isValidObjectKey({ object: { key: objectName }, maxDepth: maxFolderDepth })) {
-                            throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.OBJECT_NAME_INVALID });
-                        }
-                        const fileStat = await helper.getStat({
-                            bucket: { name: bucketName },
-                            object: { key: objectName },
-                        });
-                        const { size, metadata } = fileStat;
-                        applyMetadataHeaders({ ctx, metadata });
-                        // Download always attaches, so the served type only has to be honest, never renderable.
-                        const served = (0, exports.resolveServedContentType)({ helper, object: { key: objectName } });
-                        ctx.header(common_1.HTTP.Headers.CONTENT_TYPE, served.contentType);
-                        ctx.header(common_1.HTTP.Headers.CONTENT_LENGTH, size.toString());
-                        const fileName = objectName.split('/').pop() ?? objectName;
-                        ctx.header(common_1.HTTP.Headers.CONTENT_DISPOSITION, (0, ignis_helpers_1.createContentDispositionHeader)({ filename: fileName, type: 'attachment' }));
-                        ctx.header('x-content-type-options', 'nosniff');
-                        ctx.header(common_1.HTTP.Headers.CONTENT_SECURITY_POLICY, 'sandbox');
-                        const stream = await helper.getObjectStream({
-                            bucket: { name: bucketName },
-                            object: { key: objectName },
-                        });
-                        return new Response(stream, {
-                            headers: ctx.res.headers,
-                            status: common_1.HTTP.ResultCodes.RS_2.Ok,
+                const uploadRoute = (0, route_options_1.readRouteOverride)({ route: routes?.upload });
+                if (uploadRoute.isEnabled) {
+                    const uploadMiddleware = maxBytes === undefined
+                        ? uploadRoute.override.middleware
+                        : (0, route_options_1.appendDeclaredLengthGuard)({
+                            middleware: uploadRoute.override.middleware,
+                            maxBytes,
                         });
-                    },
-                });
-                this.bindRoute({
-                    configs: { ...definitions.UPLOAD, ...routes?.upload },
-                }).to({
-                    handler: async (ctx) => {
-                        // A configured bucket drops `params` from this route entirely, so it is read only when it exists.
-                        const bucketParam = hasConfiguredBucket
-                            ? undefined
-                            : ctx.req.valid('param').bucketName;
-                        const bucketName = await resolveBucket({ configured: bucket, param: bucketParam });
-                        if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
-                            throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
-                        }
-                        const validateFolderPath = (folderPath) => {
-                            const normalizedFolder = folderPath.replace(/^\/+|\/+$/g, '');
-                            if (!normalizedFolder) {
-                                throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.FOLDER_PATH_INVALID });
-                            }
-                            // maxFolderDepth excludes the filename, so it is compared directly against segment count.
-                            const folderSegments = normalizedFolder.split('/');
-                            if (folderSegments.length > maxFolderDepth) {
-                                throw (0, core_1.getError)({
-                                    error: common_2.StaticAssetErrors.FOLDER_DEPTH_EXCEEDED,
-                                    message: `Folder path exceeds max depth of ${maxFolderDepth}`,
-                                });
-                            }
-                            const invalidSegmentIndex = folderSegments.findIndex(segment => !helper.isValidSegment({ segment }));
-                            if (invalidSegmentIndex !== -1) {
-                                throw (0, core_1.getError)({
-                                    error: common_2.StaticAssetErrors.FOLDER_SEGMENT_INVALID,
-                                    message: `Invalid folder path segment: ${folderSegments[invalidSegmentIndex]}`,
-                                });
-                            }
-                        };
-                        refuseLabelsInQuery({ query: ctx.req.query() });
-                        // The early exit, before the body is spooled. Not authoritative: a multipart envelope is
-                        // larger than its files, so the per-file check below is the one that decides.
-                        if (maxBytes !== undefined) {
-                            const declaredLength = Number(ctx.req.header(common_1.HTTP.Headers.CONTENT_LENGTH));
-                            if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
-                                throw (0, core_1.getError)({
-                                    error: common_2.StaticAssetErrors.UPLOAD_TOO_LARGE,
-                                    message: `Request body of ${declaredLength} bytes exceeds the maximum of ${maxBytes}`,
-                                });
+                    this.bindRoute({
+                        configs: {
+                            ...definitions.UPLOAD,
+                            ...uploadRoute.override,
+                            middleware: uploadMiddleware,
+                        },
+                    }).to({
+                        handler: async (ctx) => {
+                            // A configured bucket drops `params` from this route entirely, so it is read only when it exists.
+                            const bucketParam = hasConfiguredBucket
+                                ? undefined
+                                : ctx.req.valid('param').bucketName;
+                            const bucketName = await resolveBucket({ configured: bucket, param: bucketParam });
+                            if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
+                                throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
                             }
-                        }
-                        const { files: filesArray, fields } = await (0, ignis_helpers_1.parseMultipartBody)({
-                            context: ctx,
-                            storage: options?.parseMultipartBody?.storage,
-                            uploadDir: options?.parseMultipartBody?.uploadDir,
-                        });
-                        // Labels travel with the payload, not the URL, so the folder check waits for the parse.
-                        const query = readUploadLabels({ fields });
-                        const folderPath = query.folderPath;
-                        if (folderPath) {
-                            validateFolderPath(folderPath);
-                        }
-                        const spoolPaths = filesArray
-                            .map(file => file.path)
-                            .filter((filePath) => Boolean(filePath));
-                        let uploaded;
-                        try {
-                            // `storage: 'disk'` spools the payload to `uploadDir` and returns `path` instead of `buffer`; the storage helpers only ever write `buffer`, so it must be read back.
-                            const modifiedFiles = filesArray.map(file => {
-                                const buffer = file.buffer ?? (file.path ? (0, node_fs_1.readFileSync)(file.path) : undefined);
-                                if (!buffer?.length) {
-                                    throw (0, core_1.getError)({
-                                        error: common_2.StaticAssetErrors.FILE_EMPTY,
-                                        message: `Empty file content | name: ${file.originalname}`,
-                                    });
+                            const validateFolderPath = (folderPath) => {
+                                const normalizedFolder = folderPath.replace(/^\/+|\/+$/g, '');
+                                if (!normalizedFolder) {
+                                    throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.FOLDER_PATH_INVALID });
                                 }
-                                // Authoritative: `buffer.length`, not the client-declared `size`.
-                                if (maxBytes !== undefined && buffer.length > maxBytes) {
+                                // maxFolderDepth excludes the filename, so it is compared directly against segment count.
+                                const folderSegments = normalizedFolder.split('/');
+                                if (folderSegments.length > maxFolderDepth) {
                                     throw (0, core_1.getError)({
-                                        error: common_2.StaticAssetErrors.UPLOAD_TOO_LARGE,
-                                        message: `File ${file.originalname} of ${buffer.length} bytes exceeds the maximum of ${maxBytes}`,
+                                        error: common_2.StaticAssetErrors.FOLDER_DEPTH_EXCEEDED,
+                                        message: `Folder path exceeds max depth of ${maxFolderDepth}`,
                                     });
                                 }
-                                return {
-                                    originalName: file.originalname,
-                                    mimetype: file.mimetype,
-                                    buffer,
-                                    size: file.size,
-                                    encoding: file.encoding,
-                                    folderPath: folderPath ?? undefined,
-                                };
-                            });
-                            // Built per request: the hook is offered the bucket, which only the route knows. No
-                            // hook leaves `normalizeNameFn` exactly as configured, so the stored name is unchanged.
-                            const normalizeNameFn = resolveObjectName
-                                ? (naming) => {
-                                    const defaultKey = options?.normalizeNameFn
-                                        ? options.normalizeNameFn(naming)
-                                        : defaultObjectName(naming);
-                                    return resolveObjectName({
-                                        bucket: { name: bucketName },
-                                        file: naming.file,
-                                        defaultKey,
+                                const invalidSegmentIndex = folderSegments.findIndex(segment => !helper.isValidSegment({ segment }));
+                                if (invalidSegmentIndex !== -1) {
+                                    throw (0, core_1.getError)({
+                                        error: common_2.StaticAssetErrors.FOLDER_SEGMENT_INVALID,
+                                        message: `Invalid folder path segment: ${folderSegments[invalidSegmentIndex]}`,
                                     });
                                 }
-                                : options?.normalizeNameFn;
-                            uploaded = await helper.upload({
-                                bucket: { name: bucketName },
-                                files: modifiedFiles,
-                                normalizeNameFn,
-                                normalizeLinkFn,
-                                // Without this the helper re-validates against its own hard default of 2, so an app configured for a deeper tree spools the body and only then fails inside the helper.
-                                maxFolderDepth,
+                            };
+                            refuseLabelsInQuery({ query: ctx.req.query() });
+                            const { files: filesArray, fields } = await (0, ignis_helpers_1.parseMultipartBody)({
+                                context: ctx,
+                                storage: options?.parseMultipartBody?.storage,
+                                uploadDir: options?.parseMultipartBody?.uploadDir,
                             });
-                        }
-                        finally {
-                            this.removeSpoolFiles({ paths: spoolPaths });
-                        }
-                        if (!useMetaLink || !metaLink) {
-                            return ctx.json(uploaded, common_1.HTTP.ResultCodes.RS_2.Ok);
-                        }
-                        const results = [];
-                        for (const uploadResult of uploaded) {
+                            // Labels travel with the payload, not the URL, so the folder check waits for the parse.
+                            const query = readUploadLabels({ fields });
+                            const folderPath = query.folderPath;
+                            if (folderPath) {
+                                validateFolderPath(folderPath);
+                            }
+                            const spoolPaths = filesArray
+                                .map(file => file.path)
+                                .filter((filePath) => Boolean(filePath));
+                            let uploaded;
                             try {
-                                const fileStat = await helper.getStat({
-                                    bucket: uploadResult.bucket,
-                                    object: uploadResult.object,
-                                });
-                                const createdMetaLink = await createMetaLinkRow({
-                                    metaLink,
-                                    helper,
-                                    storage,
-                                    uploadResult,
-                                    fileStat,
-                                    query,
+                                // `storage: 'disk'` spools the payload to `uploadDir` and returns `path` instead of `buffer`; the storage helpers only ever write `buffer`, so it must be read back.
+                                const modifiedFiles = filesArray.map(file => {
+                                    const buffer = file.buffer ?? (file.path ? (0, node_fs_1.readFileSync)(file.path) : undefined);
+                                    if (!buffer?.length) {
+                                        throw (0, core_1.getError)({
+                                            error: common_2.StaticAssetErrors.FILE_EMPTY,
+                                            message: `Empty file content | name: ${file.originalname}`,
+                                        });
+                                    }
+                                    // Authoritative: `buffer.length`, not the client-declared `size`.
+                                    if (maxBytes !== undefined && buffer.length > maxBytes) {
+                                        throw (0, core_1.getError)({
+                                            error: common_2.StaticAssetErrors.UPLOAD_TOO_LARGE,
+                                            message: `File ${file.originalname} of ${buffer.length} bytes exceeds the maximum of ${maxBytes}`,
+                                        });
+                                    }
+                                    return {
+                                        originalName: file.originalname,
+                                        mimetype: file.mimetype,
+                                        buffer,
+                                        size: file.size,
+                                        encoding: file.encoding,
+                                        folderPath: folderPath ?? undefined,
+                                    };
                                 });
-                                results.push({ ...uploadResult, metaLink: { data: createdMetaLink } });
-                            }
-                            catch (error) {
-                                this.logger
-                                    .for('UPLOAD')
-                                    .error('Failed to create MetaLink | objectName: %s | Error: %s', uploadResult.object.key, error);
-                                results.push({
-                                    ...uploadResult,
-                                    // A CODE, never the driver text. This handler returns 200, so it bypasses the
-                                    // error middleware and `database.handler` - the two places that strip
-                                    // `detail`/`table`/`constraint` - and shipped raw constraint names to the client.
-                                    // The real error is already logged in full immediately above.
-                                    metaLink: { error: common_2.META_LINK_CREATE_FAILED },
+                                // Built per request: the hook is offered the bucket, which only the route knows. With
+                                // neither hook nor scope, `normalizeNameFn` stays exactly as configured. Under a scope,
+                                // the component's own default is placed inside it; an application hook's key is
+                                // checked, never rewritten, because the application may record that key elsewhere.
+                                const normalizeNameFn = resolveObjectName || keyPrefix !== undefined
+                                    ? (naming) => {
+                                        if (isScopedDefaultNaming &&
+                                            !helper.isValidSegment({ segment: naming.file.originalName })) {
+                                            throw (0, core_1.getError)({ message: '[upload] Invalid original file name' });
+                                        }
+                                        const defaultKey = options?.normalizeNameFn
+                                            ? options.normalizeNameFn(naming)
+                                            : `${keyPrefix ?? ''}${defaultObjectName(naming)}`;
+                                        const key = resolveObjectName
+                                            ? resolveObjectName({
+                                                bucket: { name: bucketName },
+                                                file: naming.file,
+                                                defaultKey,
+                                            })
+                                            : defaultKey;
+                                        if (!(0, key_scope_1.isKeyInScope)({ key, keyPrefix })) {
+                                            throw (0, core_1.getError)({
+                                                error: common_2.StaticAssetErrors.OBJECT_KEY_OUT_OF_SCOPE,
+                                                message: `Object key is outside the key prefix of this controller | key: ${key} | keyPrefix: ${keyPrefix}`,
+                                            });
+                                        }
+                                        return key;
+                                    }
+                                    : options?.normalizeNameFn;
+                                uploaded = await helper.upload({
+                                    bucket: { name: bucketName },
+                                    files: modifiedFiles,
+                                    normalizeNameFn,
+                                    normalizeLinkFn,
+                                    // Without this the helper re-validates against its own hard default of 2, so an app configured for a deeper tree spools the body and only then fails inside the helper.
+                                    maxFolderDepth: objectKeyMaxDepth,
                                 });
                             }
-                        }
-                        return ctx.json(results, common_1.HTTP.ResultCodes.RS_2.Ok);
-                    },
-                });
-                this.bindRoute({
-                    configs: { ...definitions.DELETE_OBJECT, ...routes?.deleteObject },
-                }).to({
-                    handler: async (ctx) => {
-                        const params = ctx.req.valid('param');
-                        const bucketName = await resolveBucket({
-                            configured: bucket,
-                            param: params.bucketName,
-                        });
-                        const objectName = readObjectName(params.objectName);
-                        if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
-                            throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
-                        }
-                        if (!helper.isValidObjectKey({ object: { key: objectName }, maxDepth: maxFolderDepth })) {
-                            throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.OBJECT_NAME_INVALID });
-                        }
-                        // Deliberately idempotent: S3 answers 200 for a key that was never there, and consumers
-                        // already depend on it. `disk` throws instead, so the two are reconciled here, not below.
-                        try {
-                            await helper.removeObject({
-                                bucket: { name: bucketName },
-                                object: { key: objectName },
-                            });
-                        }
-                        catch (error) {
-                            if (!(0, ignis_helpers_1.isNotFoundError)({ error })) {
-                                throw error;
+                            finally {
+                                this.removeSpoolFiles({ paths: spoolPaths });
                             }
-                        }
-                        if (!useMetaLink || !metaLink) {
-                            return ctx.json({ success: true }, common_1.HTTP.ResultCodes.RS_2.Ok);
-                        }
-                        const deleteRepository = await (0, common_1.resolveValueAsync)({ value: metaLink.repository });
-                        deleteRepository
-                            .deleteAll({
-                            where: {
-                                bucketName,
-                                objectName,
-                            },
-                        })
-                            .then(() => {
-                            this.logger
-                                .for('DELETE_OBJECT')
-                                .info('Successfully to delete MetaLink for %s/%s', bucketName, objectName);
-                        })
-                            .catch(error => {
-                            this.logger
-                                .for('DELETE_OBJECT')
-                                .error('Failed to delete MetaLink | bucket: %s | objectName: %s | Error: %s', bucketName, objectName, error);
-                        });
-                        return ctx.json({ success: true }, common_1.HTTP.ResultCodes.RS_2.Ok);
-                    },
-                });
-                this.bindRoute({
-                    configs: { ...definitions.LIST_OBJECTS, ...routes?.listObjects },
-                }).to({
-                    handler: async (ctx) => {
-                        // A configured bucket drops `params` from this route entirely, so it is read only when it exists.
-                        const bucketParam = hasConfiguredBucket
-                            ? undefined
-                            : ctx.req.valid('param').bucketName;
-                        const bucketName = await resolveBucket({ configured: bucket, param: bucketParam });
-                        const { prefix, recursive, maxKeys } = ctx.req.valid('query');
-                        if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
-                            throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
-                        }
-                        // A NaN or 0 maxKeys is silently treated as "unlimited" by the storage backends, so an unparsable value must be rejected instead of forwarded.
-                        let resolvedMaxKeys;
-                        if (maxKeys !== undefined) {
-                            resolvedMaxKeys = Number(maxKeys);
-                            if (!Number.isInteger(resolvedMaxKeys) || resolvedMaxKeys < 1) {
-                                throw (0, core_1.getError)({
-                                    error: common_2.StaticAssetErrors.MAX_KEYS_INVALID,
-                                    message: `Invalid maxKeys | Expected a positive integer | value: ${maxKeys}`,
-                                });
+                            if (!useMetaLink || !metaLink) {
+                                return ctx.json(uploaded, common_1.HTTP.ResultCodes.RS_2.Ok);
                             }
-                        }
-                        const objects = await helper.listObjects({
-                            bucket: { name: bucketName },
-                            prefix,
-                            useRecursive: recursive === 'true',
-                            maxKeys: resolvedMaxKeys,
-                        });
-                        return ctx.json(objects, common_1.HTTP.ResultCodes.RS_2.Ok);
-                    },
-                });
-                if (directUpload) {
-                    if (!hasConfiguredBucket) {
-                        throw (0, core_1.getError)({
-                            message: `[${name}] directUpload needs controller.bucket | a policy names one bucket, and a bucket in the URL is a bucket the caller chooses`,
-                        });
-                    }
-                    const pendingPrefix = directUpload.pendingPrefix ?? common_2.DEFAULT_PENDING_PREFIX;
-                    this.bindRoute({
-                        configs: { ...definitions.UPLOAD_POLICY, ...routes?.uploadPolicy },
-                    }).to({
-                        handler: async (ctx) => {
-                            if (!(await directUpload.authorize({ context: ctx }))) {
-                                throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.UPLOAD_NOT_AUTHORIZED });
-                            }
-                            const { files } = ctx.req.valid('json');
-                            const bucketName = await resolveBucket({ configured: bucket });
-                            const policies = [];
-                            for (const file of files) {
-                                if (file.size !== undefined && file.size > directUpload.maxBytes) {
-                                    throw (0, core_1.getError)({
-                                        error: common_2.StaticAssetErrors.UPLOAD_TOO_LARGE,
-                                        message: `File '${file.fileName}' is ${file.size} bytes, over the ${directUpload.maxBytes} the policy allows`,
-                                    });
-                                }
-                                // Generated, never taken from the caller: a key the caller picks is a key the caller
-                                // can collide with, and the pending object is the one thing a policy authorizes.
-                                const objectName = `${pendingPrefix}${core_1.UuidHelper.getInstance().v4()}/${file.fileName}`;
-                                const policy = await helper.presignPost({
-                                    bucket: { name: bucketName },
-                                    keyPrefix: pendingPrefix,
-                                    maxBytes: directUpload.maxBytes,
-                                    contentType: file.contentType,
-                                    expiresIn: directUpload.expiresIn,
-                                });
-                                policies.push({
-                                    ...policy,
-                                    objectName,
-                                    commitToken: (0, common_3.buildCommitToken)({
-                                        payload: {
-                                            bucket: bucketName,
-                                            key: objectName,
-                                            expiresAt: new Date(policy.expiresAt).getTime(),
-                                        },
-                                        secretKey: directUpload.secretKey,
-                                    }),
-                                });
-                            }
-                            return ctx.json(policies, common_1.HTTP.ResultCodes.RS_2.Ok);
-                        },
-                    });
-                    this.bindRoute({
-                        configs: { ...definitions.UPLOAD_COMMIT, ...routes?.uploadCommit },
-                    }).to({
-                        handler: async (ctx) => {
-                            const commitQuery = ctx.req.query();
-                            refuseLabelsInQuery({ query: commitQuery, names: COMMIT_LABEL_NAMES });
-                            refuseLabelsInQuery({
-                                query: commitQuery,
-                                names: ['folderPath'],
-                                reason: 'folderPath was decided when the upload policy was issued; the commit route cannot move the object',
-                            });
-                            const { commitToken, ...labels } = ctx.req.valid('json');
-                            // Verified BEFORE any storage call. That is what keeps this route from being a name
-                            // prober: a forged token fails without a round trip, so timing says nothing.
-                            const payload = (0, common_3.readCommitToken)({
-                                token: commitToken,
-                                secretKey: directUpload.secretKey,
-                            });
-                            // Labels, not authorization - the token deliberately carries no business fields, so
-                            // they travel beside it rather than inside it.
-                            const query = readUploadLabels({ fields: labels });
-                            const bucketRef = { name: payload.bucket };
-                            const pendingObject = { key: payload.key };
-                            const object = { key: payload.key.slice(pendingPrefix.length) };
-                            // Before the copy, so a hook that throws leaves the object under the pending prefix
-                            // for a lifecycle rule, rather than stranding it at the final key.
-                            await directUpload.onCommit?.({ bucket: bucketRef, pendingObject, object });
-                            await helper.copyObject({
-                                bucket: bucketRef,
-                                source: pendingObject,
-                                destination: object,
-                            });
-                            // The copy IS the commit; removing the temporary object is cleanup. A failure here
-                            // leaves one object for the lifecycle rule, and failing the request would tell the
-                            // caller their upload did not work when it did.
-                            await helper
-                                .removeObject({ bucket: bucketRef, object: pendingObject })
-                                .catch(error => {
-                                this.logger
-                                    .for('UPLOAD_COMMIT')
-                                    .warn('Committed, but the pending object remains | key: %s | error: %s', pendingObject.key, error);
-                            });
-                            const link = (0, exports.buildObjectLink)({
-                                basePath: normalizedBasePath,
-                                bucket: bucketRef,
-                                object,
-                                hasConfiguredBucket,
-                                rawObjectPath,
-                            });
-                            // The two paths have to agree: without this a client reading `metaLink` off the
-                            // response renders an empty state with no error - the failure nobody reports.
-                            let metaLinkResult;
-                            if (useMetaLink && metaLink) {
+                            const results = [];
+                            for (const uploadResult of uploaded) {
                                 try {
-                                    const fileStat = await helper.getStat({ bucket: bucketRef, object });
-                                    const data = await createMetaLinkRow({
+                                    const fileStat = await helper.getStat({
+                                        bucket: uploadResult.bucket,
+                                        object: uploadResult.object,
+                                    });
+                                    const createdMetaLink = await (0, meta_link_1.createMetaLinkRow)({
                                         metaLink,
                                         helper,
                                         storage,
-                                        uploadResult: {
-                                            bucket: bucketRef,
-                                            object: {
-                                                key: object.key,
-                                                size: fileStat.size,
-                                                contentType: fileStat.metadata?.mimetype ??
-                                                    helper.getMimeType({ filename: object.key }),
-                                            },
-                                            link,
-                                        },
+                                        uploadResult,
                                         fileStat,
                                         query,
                                     });
-                                    metaLinkResult = { data };
+                                    results.push({ ...uploadResult, metaLink: { data: createdMetaLink } });
                                 }
                                 catch (error) {
-                                    // The object IS committed by now. A 500 would send the caller back with a token
-                                    // whose source no longer exists, so this rides the body as a code, like UPLOAD.
                                     this.logger
-                                        .for('UPLOAD_COMMIT')
-                                        .error('Failed to create MetaLink | objectName: %s | Error: %s', object.key, error);
-                                    metaLinkResult = { error: common_2.META_LINK_CREATE_FAILED };
+                                        .for('UPLOAD')
+                                        .error('Failed to create MetaLink | objectName: %s | Error: %s', uploadResult.object.key, error);
+                                    results.push({
+                                        ...uploadResult,
+                                        // A CODE, never the driver text. This handler returns 200, so it bypasses the
+                                        // error middleware and `database.handler` - the two places that strip
+                                        // `detail`/`table`/`constraint` - and shipped raw constraint names to the client.
+                                        // The real error is already logged in full immediately above.
+                                        metaLink: { error: common_2.META_LINK_CREATE_FAILED },
+                                    });
                                 }
                             }
-                            return ctx.json({
-                                bucket: bucketRef,
-                                object,
-                                link,
-                                ...(metaLinkResult === undefined ? {} : { metaLink: metaLinkResult }),
-                            }, common_1.HTTP.ResultCodes.RS_2.Ok);
+                            return ctx.json(results, common_1.HTTP.ResultCodes.RS_2.Ok);
                         },
                     });
                 }
-                if (useMetaLink && metaLink) {
+                const deleteObjectRoute = (0, route_options_1.readRouteOverride)({ route: routes?.deleteObject });
+                if (deleteObjectRoute.isEnabled) {
                     this.bindRoute({
-                        configs: { ...definitions.RECREATE_METALINK, ...routes?.recreateMetaLink },
+                        configs: { ...definitions.DELETE_OBJECT, ...deleteObjectRoute.override },
                     }).to({
                         handler: async (ctx) => {
-                            // This route takes no labels anywhere: one in the query would land an unlabelled row.
-                            refuseLabelsInQuery({
-                                query: ctx.req.query(),
-                                reason: 'This route recreates a MetaLink for an existing object and takes no labels',
-                            });
                             const params = ctx.req.valid('param');
                             const bucketName = await resolveBucket({
                                 configured: bucket,
@@ -780,72 +581,326 @@ class AssetControllerFactory extends core_1.BaseHelper {
                             if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
                                 throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
                             }
-                            if (!helper.isValidObjectKey({ object: { key: objectName }, maxDepth: maxFolderDepth })) {
+                            if (!helper.isValidObjectKey({
+                                object: { key: objectName },
+                                maxDepth: objectKeyMaxDepth,
+                            })) {
                                 throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.OBJECT_NAME_INVALID });
                             }
-                            const fileStat = await helper.getStat({
-                                bucket: { name: bucketName },
-                                object: { key: objectName },
-                            });
-                            const link = options?.normalizeLinkFn
-                                ? options.normalizeLinkFn({
-                                    bucket: { name: bucketName },
-                                    object: { key: objectName },
-                                })
-                                : (0, exports.buildObjectLink)({
-                                    basePath: normalizedBasePath,
+                            // Before any storage call: a key outside the scope must not even be probed.
+                            (0, key_scope_1.assertKeyInScope)({ key: objectName, keyPrefix });
+                            // Deliberately idempotent: S3 answers 200 for a key that was never there, and consumers
+                            // already depend on it. `disk` throws instead, so the two are reconciled here, not below.
+                            try {
+                                await helper.removeObject({
                                     bucket: { name: bucketName },
                                     object: { key: objectName },
-                                    hasConfiguredBucket,
-                                    rawObjectPath,
-                                });
-                            // Read per call, never once per handler: an application may rebind the repository
-                            // between two of these, and a copy held across them would answer from the old binding.
-                            const findRepository = await (0, common_1.resolveValueAsync)({ value: metaLink.repository });
-                            const existing = await findRepository.findOne({
-                                filter: {
-                                    where: {
-                                        bucketName,
-                                        objectName,
-                                    },
-                                },
-                            });
-                            if (existing) {
-                                const updateRepository = await (0, common_1.resolveValueAsync)({ value: metaLink.repository });
-                                await updateRepository.updateById({
-                                    id: existing.id,
-                                    data: {
-                                        link,
-                                        mimetype: fileStat.metadata?.['mimetype'],
-                                        size: fileStat.size,
-                                        etag: fileStat.etag,
-                                        metadata: fileStat.metadata,
-                                        storageType: storage,
-                                        isSynced: true,
-                                    },
                                 });
-                                const readRepository = await (0, common_1.resolveValueAsync)({ value: metaLink.repository });
-                                const updatedMetaLink = await readRepository.findById({ id: existing.id });
-                                return ctx.json({ success: true, metaLink: updatedMetaLink }, common_1.HTTP.ResultCodes.RS_2.Ok);
                             }
-                            const createRepository = await (0, common_1.resolveValueAsync)({ value: metaLink.repository });
-                            const createdMetaLink = await createRepository.create({
-                                data: {
+                            catch (error) {
+                                if (!(0, ignis_helpers_1.isNotFoundError)({ error })) {
+                                    throw error;
+                                }
+                            }
+                            if (!useMetaLink || !metaLink) {
+                                return ctx.json({ success: true }, common_1.HTTP.ResultCodes.RS_2.Ok);
+                            }
+                            const deleteRepository = await (0, common_1.resolveValueAsync)({ value: metaLink.repository });
+                            deleteRepository
+                                .deleteAll({
+                                where: {
                                     bucketName,
                                     objectName,
-                                    link,
-                                    mimetype: fileStat.metadata?.mimetype ?? helper.getMimeType({ filename: objectName }),
-                                    size: fileStat.size,
-                                    etag: fileStat.etag,
-                                    metadata: fileStat.metadata,
-                                    storageType: storage,
-                                    isSynced: true,
                                 },
+                            })
+                                .then(() => {
+                                this.logger
+                                    .for('DELETE_OBJECT')
+                                    .info('Successfully to delete MetaLink for %s/%s', bucketName, objectName);
+                            })
+                                .catch(error => {
+                                this.logger
+                                    .for('DELETE_OBJECT')
+                                    .error('Failed to delete MetaLink | bucket: %s | objectName: %s | Error: %s', bucketName, objectName, error);
+                            });
+                            return ctx.json({ success: true }, common_1.HTTP.ResultCodes.RS_2.Ok);
+                        },
+                    });
+                }
+                const listObjectsRoute = (0, route_options_1.readRouteOverride)({ route: routes?.listObjects });
+                if (listObjectsRoute.isEnabled) {
+                    this.bindRoute({
+                        configs: { ...definitions.LIST_OBJECTS, ...listObjectsRoute.override },
+                    }).to({
+                        handler: async (ctx) => {
+                            // A configured bucket drops `params` from this route entirely, so it is read only when it exists.
+                            const bucketParam = hasConfiguredBucket
+                                ? undefined
+                                : ctx.req.valid('param').bucketName;
+                            const bucketName = await resolveBucket({ configured: bucket, param: bucketParam });
+                            const { prefix, recursive, maxKeys } = ctx.req.valid('query');
+                            if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
+                                throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
+                            }
+                            // A NaN or 0 maxKeys is silently treated as "unlimited" by the storage backends, so an unparsable value must be rejected instead of forwarded.
+                            let resolvedMaxKeys;
+                            if (maxKeys !== undefined) {
+                                resolvedMaxKeys = Number(maxKeys);
+                                if (!Number.isInteger(resolvedMaxKeys) || resolvedMaxKeys < 1) {
+                                    throw (0, core_1.getError)({
+                                        error: common_2.StaticAssetErrors.MAX_KEYS_INVALID,
+                                        message: `Invalid maxKeys | Expected a positive integer | value: ${maxKeys}`,
+                                    });
+                                }
+                            }
+                            const scoped = (0, key_scope_1.resolveScopedListPrefix)({ prefix, keyPrefix });
+                            if (scoped.isOutOfScope) {
+                                return ctx.json([], common_1.HTTP.ResultCodes.RS_2.Ok);
+                            }
+                            const objects = await helper.listObjects({
+                                bucket: { name: bucketName },
+                                prefix: scoped.prefix,
+                                useRecursive: recursive === 'true',
+                                maxKeys: resolvedMaxKeys,
                             });
-                            return ctx.json({ success: true, metaLink: createdMetaLink.data }, common_1.HTTP.ResultCodes.RS_2.Ok);
+                            return ctx.json(objects, common_1.HTTP.ResultCodes.RS_2.Ok);
                         },
                     });
                 }
+                if (directUpload) {
+                    if (!hasConfiguredBucket) {
+                        throw (0, core_1.getError)({
+                            message: `[${name}] directUpload needs controller.bucket | a policy names one bucket, and a bucket in the URL is a bucket the caller chooses`,
+                        });
+                    }
+                    const pendingPrefix = directUpload.pendingPrefix ?? common_2.DEFAULT_PENDING_PREFIX;
+                    // The scope rides inside the pending key, so the commit, which strips `pendingPrefix`, lands inside it.
+                    const policyKeyPrefix = `${pendingPrefix}${keyPrefix ?? ''}`;
+                    const uploadPolicyRoute = (0, route_options_1.readRouteOverride)({ route: routes?.uploadPolicy });
+                    if (uploadPolicyRoute.isEnabled) {
+                        this.bindRoute({
+                            configs: { ...definitions.UPLOAD_POLICY, ...uploadPolicyRoute.override },
+                        }).to({
+                            handler: async (ctx) => {
+                                if (!(await directUpload.authorize({ context: ctx }))) {
+                                    throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.UPLOAD_NOT_AUTHORIZED });
+                                }
+                                const { files } = ctx.req.valid('json');
+                                const bucketName = await resolveBucket({ configured: bucket });
+                                const policies = [];
+                                for (const file of files) {
+                                    if (file.size !== undefined && file.size > directUpload.maxBytes) {
+                                        throw (0, core_1.getError)({
+                                            error: common_2.StaticAssetErrors.UPLOAD_TOO_LARGE,
+                                            message: `File '${file.fileName}' is ${file.size} bytes, over the ${directUpload.maxBytes} the policy allows`,
+                                        });
+                                    }
+                                    // Generated, never taken from the caller: a key the caller picks is a key the caller
+                                    // can collide with, and the pending object is the one thing a policy authorizes.
+                                    const objectName = `${policyKeyPrefix}${core_1.UuidHelper.getInstance().v4()}/${file.fileName}`;
+                                    const policy = await helper.presignPost({
+                                        bucket: { name: bucketName },
+                                        keyPrefix: policyKeyPrefix,
+                                        maxBytes: directUpload.maxBytes,
+                                        contentType: file.contentType,
+                                        expiresIn: directUpload.expiresIn,
+                                    });
+                                    policies.push({
+                                        ...policy,
+                                        objectName,
+                                        commitToken: (0, common_3.buildCommitToken)({
+                                            payload: {
+                                                bucket: bucketName,
+                                                key: objectName,
+                                                expiresAt: new Date(policy.expiresAt).getTime(),
+                                            },
+                                            secretKey: directUpload.secretKey,
+                                        }),
+                                    });
+                                }
+                                return ctx.json(policies, common_1.HTTP.ResultCodes.RS_2.Ok);
+                            },
+                        });
+                    }
+                    const uploadCommitRoute = (0, route_options_1.readRouteOverride)({ route: routes?.uploadCommit });
+                    if (uploadCommitRoute.isEnabled) {
+                        this.bindRoute({
+                            configs: { ...definitions.UPLOAD_COMMIT, ...uploadCommitRoute.override },
+                        }).to({
+                            handler: async (ctx) => {
+                                const commitQuery = ctx.req.query();
+                                refuseLabelsInQuery({ query: commitQuery, names: COMMIT_LABEL_NAMES });
+                                refuseLabelsInQuery({
+                                    query: commitQuery,
+                                    names: ['folderPath'],
+                                    reason: 'folderPath was decided when the upload policy was issued; the commit route cannot move the object',
+                                });
+                                const { commitToken, ...labels } = ctx.req.valid('json');
+                                // Verified BEFORE any storage call. That is what keeps this route from being a name
+                                // prober: a forged token fails without a round trip, so timing says nothing.
+                                const payload = (0, common_3.readCommitToken)({
+                                    token: commitToken,
+                                    secretKey: directUpload.secretKey,
+                                });
+                                // Labels, not authorization - the token deliberately carries no business fields, so
+                                // they travel beside it rather than inside it.
+                                const query = readUploadLabels({ fields: labels });
+                                const bucketRef = { name: payload.bucket };
+                                const pendingObject = { key: payload.key };
+                                const object = { key: payload.key.slice(pendingPrefix.length) };
+                                // A token another controller signed with the same secret must not land outside this scope.
+                                (0, key_scope_1.assertKeyInScope)({ key: object.key, keyPrefix });
+                                // Before the copy, so a hook that throws leaves the object under the pending prefix
+                                // for a lifecycle rule, rather than stranding it at the final key.
+                                await directUpload.onCommit?.({ bucket: bucketRef, pendingObject, object });
+                                await helper.copyObject({
+                                    bucket: bucketRef,
+                                    source: pendingObject,
+                                    destination: object,
+                                });
+                                // The copy IS the commit; removing the temporary object is cleanup. A failure here
+                                // leaves one object for the lifecycle rule, and failing the request would tell the
+                                // caller their upload did not work when it did.
+                                await helper
+                                    .removeObject({ bucket: bucketRef, object: pendingObject })
+                                    .catch(error => {
+                                    this.logger
+                                        .for('UPLOAD_COMMIT')
+                                        .warn('Committed, but the pending object remains | key: %s | error: %s', pendingObject.key, error);
+                                });
+                                const link = (0, exports.buildObjectLink)({
+                                    basePath: normalizedBasePath,
+                                    bucket: bucketRef,
+                                    object,
+                                    hasConfiguredBucket,
+                                    rawObjectPath,
+                                });
+                                // The two paths have to agree: without this a client reading `metaLink` off the
+                                // response renders an empty state with no error - the failure nobody reports.
+                                let metaLinkResult;
+                                if (useMetaLink && metaLink) {
+                                    try {
+                                        const fileStat = await helper.getStat({ bucket: bucketRef, object });
+                                        const data = await (0, meta_link_1.createMetaLinkRow)({
+                                            metaLink,
+                                            helper,
+                                            storage,
+                                            uploadResult: (0, meta_link_1.buildStoredUploadResult)({
+                                                helper,
+                                                bucket: bucketRef,
+                                                object,
+                                                link,
+                                                fileStat,
+                                            }),
+                                            fileStat,
+                                            query,
+                                        });
+                                        metaLinkResult = { data };
+                                    }
+                                    catch (error) {
+                                        // The object IS committed by now. A 500 would send the caller back with a token
+                                        // whose source no longer exists, so this rides the body as a code, like UPLOAD.
+                                        this.logger
+                                            .for('UPLOAD_COMMIT')
+                                            .error('Failed to create MetaLink | objectName: %s | Error: %s', object.key, error);
+                                        metaLinkResult = { error: common_2.META_LINK_CREATE_FAILED };
+                                    }
+                                }
+                                return ctx.json({
+                                    bucket: bucketRef,
+                                    object,
+                                    link,
+                                    ...(metaLinkResult === undefined ? {} : { metaLink: metaLinkResult }),
+                                }, common_1.HTTP.ResultCodes.RS_2.Ok);
+                            },
+                        });
+                    }
+                }
+                if (useMetaLink && metaLink) {
+                    const recreateMetaLinkRoute = (0, route_options_1.readRouteOverride)({ route: routes?.recreateMetaLink });
+                    if (recreateMetaLinkRoute.isEnabled) {
+                        this.bindRoute({
+                            configs: { ...definitions.RECREATE_METALINK, ...recreateMetaLinkRoute.override },
+                        }).to({
+                            handler: async (ctx) => {
+                                // This route takes no labels anywhere: one in the query would land an unlabelled row.
+                                refuseLabelsInQuery({
+                                    query: ctx.req.query(),
+                                    reason: 'This route recreates a MetaLink for an existing object and takes no labels',
+                                });
+                                const params = ctx.req.valid('param');
+                                const bucketName = await resolveBucket({
+                                    configured: bucket,
+                                    param: params.bucketName,
+                                });
+                                const objectName = readObjectName(params.objectName);
+                                if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
+                                    throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
+                                }
+                                if (!helper.isValidObjectKey({
+                                    object: { key: objectName },
+                                    maxDepth: objectKeyMaxDepth,
+                                })) {
+                                    throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.OBJECT_NAME_INVALID });
+                                }
+                                // Before any storage call: a key outside the scope must not even be probed.
+                                (0, key_scope_1.assertKeyInScope)({ key: objectName, keyPrefix });
+                                const bucketRef = { name: bucketName };
+                                const object = { key: objectName };
+                                const fileStat = await helper.getStat({ bucket: bucketRef, object });
+                                const link = options?.normalizeLinkFn
+                                    ? options.normalizeLinkFn({ bucket: bucketRef, object })
+                                    : (0, exports.buildObjectLink)({
+                                        basePath: normalizedBasePath,
+                                        bucket: bucketRef,
+                                        object,
+                                        hasConfiguredBucket,
+                                        rawObjectPath,
+                                    });
+                                const refreshed = await (0, meta_link_1.refreshMetaLinkRows)({
+                                    metaLink,
+                                    helper,
+                                    bucket: bucketRef,
+                                    object,
+                                    link,
+                                    fileStat,
+                                });
+                                if (refreshed.count > 0) {
+                                    return ctx.json({
+                                        success: true,
+                                        action: common_3.MetaLinkRecreateActions.REFRESHED,
+                                        count: refreshed.count,
+                                        metaLink: refreshed.data[0],
+                                        metaLinks: refreshed.data,
+                                    }, common_1.HTTP.ResultCodes.RS_2.Ok);
+                                }
+                                // Not atomic with the refresh above: two concurrent calls may both create, which the
+                                // table allows - rows per pair are deliberately not unique.
+                                const created = await (0, meta_link_1.createMetaLinkRow)({
+                                    metaLink,
+                                    helper,
+                                    storage,
+                                    uploadResult: (0, meta_link_1.buildStoredUploadResult)({
+                                        helper,
+                                        bucket: bucketRef,
+                                        object,
+                                        link,
+                                        fileStat,
+                                    }),
+                                    fileStat,
+                                    query: {},
+                                });
+                                return ctx.json({
+                                    success: true,
+                                    action: common_3.MetaLinkRecreateActions.CREATED,
+                                    count: 1,
+                                    metaLink: created,
+                                    metaLinks: [created],
+                                }, common_1.HTTP.ResultCodes.RS_2.Ok);
+                            },
+                        });
+                    }
+                }
                 // Last, so a built-in route always wins a path collision with an application's own.
                 defineExtraRoutes?.({ controller: this, helper, basePath: normalizedBasePath });
             }