@venizia/ignis 0.2.0-21 → 0.2.0-23

package/dist/components/static-asset/controller/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/components/static-asset/controller/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,EAAE,UAAU,EAAY,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAQ,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAGL,cAAc,EAIf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAE3B,OAAO,EAIL,eAAe,EAEf,wBAAwB,EACxB,6BAA6B,EAC7B,uBAAuB,EAGxB,MAAM,WAAW,CAAC;AAGnB,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,6BAA6B,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAChE,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,cAAc,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,OAAO,CAAC,EAAE,wBAAwB,CAAC;CACpC;AAuBD,qBAAa,sBAAuB,SAAQ,UAAU;;IAKpD,MAAM,CAAC,qBAAqB,CAAC,IAAI,EAAE,uBAAuB;;YAkBtD,6FAA6F;2CAC9D;gBAAE,KAAK,EAAE,MAAM,EAAE,CAAA;aAAE,GAAG,IAAI;uBAYrC,cAAc,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAxDiC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAif/E"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/components/static-asset/controller/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,EAGL,eAAe,EAEf,UAAU,EAEV,cAAc,EAKf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAQ,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,UAAU,EAAY,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAE3B,OAAO,EAIL,kBAAkB,EAElB,eAAe,EAEf,kBAAkB,EAClB,wBAAwB,EACxB,6BAA6B,EAC7B,uBAAuB,EAGxB,MAAM,WAAW,CAAC;AAGnB,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,6BAA6B,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAChE,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,cAAc,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,OAAO,CAAC,EAAE,wBAAwB,CAAC;IAEnC,qHAAqH;IACrH,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;IAEvC,oGAAoG;IACpG,4IAA4I;IAC5I,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;CACxC;AAqBD,qJAAqJ;AACrJ,eAAO,MAAM,eAAe,GAC1B,MAAM,eAAe,GAAG;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,KACA,MAQF,CAAC;AAcF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM;IAC7C,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,UAAU,CAAC;CACpB,KAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAS/C,CAAC;AAyDF,qBAAa,sBAAuB,SAAQ,UAAU;;IAKpD,MAAM,CAAC,qBAAqB,CAAC,IAAI,EAAE,uBAAuB;;YAoCtD,6FAA6F;2CAC9D;gBAAE,KAAK,EAAE,MAAM,EAAE,CAAA;aAAE,GAAG,IAAI;uBAYrC,cAAc,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAxLN,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4tBxC"}

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

@@ -9,12 +9,12 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AssetControllerFactory = void 0;
+exports.AssetControllerFactory = exports.resolveServedContentType = exports.buildObjectLink = void 0;
 const controllers_1 = require("../../../base/controllers");
 const metadata_1 = require("../../../base/metadata");
-const core_1 = require("@venizia/ignis-helpers/core");
-const common_1 = require("@venizia/ignis-helpers/common");
 const ignis_helpers_1 = require("@venizia/ignis-helpers");
+const common_1 = require("@venizia/ignis-helpers/common");
+const core_1 = require("@venizia/ignis-helpers/core");
 const node_fs_1 = require("node:fs");
 const common_2 = require("../common");
 const base_definition_1 = require("./base.definition");
@@ -24,7 +24,77 @@ const readObjectName = rawObjectName => rawObjectName;
 const encodeObjectPath = objectPath => {
     return encodeURIComponent(objectPath);
 };
-/** Sets whitelisted metadata headers on the response context. */
+/** The bucket one request works on: a configured value wins - called on every request, so an application may read an environment variable lazily - else the path param, which is only registered when there is no configured bucket. */
+const resolveBucket = (opts) => {
+    const { configured, param } = opts;
+    if (typeof configured === 'function') {
+        return configured();
+    }
+    return configured ?? param ?? '';
+};
+/** The URL of one object, in the shape its controller serves: no `/buckets/<name>` with a configured bucket, and a raw path with `rawObjectPath`. */
+const buildObjectLink = (opts) => {
+    const { basePath, bucket, object } = opts;
+    const { hasConfiguredBucket = false, rawObjectPath = false } = opts;
+    const bucketSegment = hasConfiguredBucket ? '' : `/buckets/${bucket.name}`;
+    const objectSegment = rawObjectPath ? object.key : encodeObjectPath(object.key);
+    return `${basePath}${bucketSegment}/objects/${objectSegment}`;
+};
+exports.buildObjectLink = buildObjectLink;
+/** Mirrors `BaseStorageHelper.normalizeObjectName`, which is protected: `resolveObjectName` is offered the very name the helper would otherwise have written. */
+const defaultObjectName = ({ file }) => {
+    const { originalName, folderPath } = file;
+    const normalizedFileName = originalName.toLowerCase().replace(/ /g, '_');
+    if (!folderPath) {
+        return normalizedFileName;
+    }
+    return `${folderPath.toLowerCase().replace(/ /g, '_')}/${normalizedFileName}`;
+};
+/**
+ * The served type comes from the object NAME, never the backend or the uploader: a renderable type on
+ * the API origin is stored XSS. Exported so a hand-written route makes the same decision - the
+ * backend's own content-type is dropped by `WHITELIST_HEADERS`.
+ */
+const resolveServedContentType = (opts) => {
+    const { helper, object } = opts;
+    const candidate = helper.getMimeType({ filename: object.key }).toLowerCase().split(';')[0].trim();
+    if (!common_2.RENDERABLE_CONTENT_TYPES.has(candidate)) {
+        return { contentType: common_1.HTTP.HeaderValues.APPLICATION_OCTET_STREAM, isRenderable: false };
+    }
+    return { contentType: candidate, isRenderable: true };
+};
+exports.resolveServedContentType = resolveServedContentType;
+/**
+ * Reads one `Range` header. Only a single byte range is honoured - multipart ranges need a multipart
+ * body no browser asks for here. An unsatisfiable or malformed range returns `null`, and the caller
+ * serves the whole object, which is what RFC 9110 allows.
+ */
+const readByteRange = (opts) => {
+    const { header, size } = opts;
+    if (!header || size <= 0) {
+        return null;
+    }
+    const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!match) {
+        return null;
+    }
+    const [, rawStart, rawEnd] = match;
+    // `bytes=-500` means the LAST 500 bytes, not "from 0 to 500".
+    if (!rawStart) {
+        const suffixLength = Number(rawEnd);
+        if (!Number.isInteger(suffixLength) || suffixLength <= 0) {
+            return null;
+        }
+        return { start: Math.max(size - suffixLength, 0), end: size - 1 };
+    }
+    const start = Number(rawStart);
+    const end = rawEnd ? Number(rawEnd) : size - 1;
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start > end || start >= size) {
+        return null;
+    }
+    return { start, end: Math.min(end, size - 1) };
+};
+/** Sets whitelisted metadata headers on the response context. `content-type` is not among them. */
 const applyMetadataHeaders = ({ ctx, metadata }) => {
     Object.entries(metadata).forEach(([key, value]) => {
         if (!common_2.WHITELIST_HEADERS.includes(key.toLowerCase())) {
@@ -39,10 +109,24 @@ class AssetControllerFactory extends core_1.BaseHelper {
     }
     static defineAssetController(opts) {
         const { controller, helper, options, useMetaLink, metaLink, storage } = opts;
-        const { name, basePath, routes, isStrict = true } = controller;
+        const { resolveObjectName, defineRoutesBefore, defineExtraRoutes } = opts;
+        const { name, basePath, routes, isStrict = true, bucket, rawObjectPath = false } = controller;
         const maxFolderDepth = options?.maxFolderDepth ?? ignis_helpers_1.BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH;
+        const hasConfiguredBucket = bucket !== undefined;
+        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}`;
+        /** Only when the URL shape deviates: with neither option the storage helper's own link is left untouched. */
+        const shapedLinkFn = hasConfiguredBucket || rawObjectPath
+            ? (linkOptions) => (0, exports.buildObjectLink)({
+                basePath: normalizedBasePath,
+                bucket: linkOptions.bucket,
+                object: linkOptions.object,
+                hasConfiguredBucket,
+                rawObjectPath,
+            })
+            : undefined;
+        const normalizeLinkFn = options?.normalizeLinkFn ?? shapedLinkFn;
         let GeneratedStaticAssetController = class GeneratedStaticAssetController extends controllers_1.BaseRestController {
             constructor() {
                 super({
@@ -65,79 +149,146 @@ class AssetControllerFactory extends core_1.BaseHelper {
                 }
             }
             binding() {
+                // First, so a literal path can win over the built-in catch-all `rawObjectPath` registers.
+                defineRoutesBefore?.({ controller: this, helper, basePath: normalizedBasePath });
+                // 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) {
+                    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 },
+                    }).to({
+                        handler: async (ctx) => {
+                            const params = ctx.req.valid('param');
+                            const bucketName = 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);
+                        },
+                    });
+                    this.bindRoute({
+                        configs: { ...definitions.CREATE_BUCKET, ...routes?.createBucket },
+                    }).to({
+                        handler: async (ctx) => {
+                            const params = ctx.req.valid('param');
+                            const bucketName = 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);
+                        },
+                    });
+                    this.bindRoute({
+                        configs: { ...definitions.DELETE_BUCKET, ...routes?.deleteBucket },
+                    }).to({
+                        handler: async (ctx) => {
+                            const params = ctx.req.valid('param');
+                            const bucketName = 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);
+                        },
+                    });
+                }
                 this.bindRoute({
-                    configs: { ...base_definition_1.StaticAssetDefinitions.GET_BUCKETS, ...routes?.getBuckets },
-                }).to({
-                    handler: async (ctx) => {
-                        const bucket = await helper.getBuckets();
-                        return ctx.json(bucket, common_1.HTTP.ResultCodes.RS_2.Ok);
-                    },
-                });
-                this.bindRoute({
-                    configs: { ...base_definition_1.StaticAssetDefinitions.GET_BUCKET_BY_NAME, ...routes?.getBucketByName },
-                }).to({
-                    handler: async (ctx) => {
-                        const { bucketName } = ctx.req.valid('param');
-                        if (!helper.isValidName(bucketName)) {
-                            throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
-                        }
-                        const bucket = await helper.getBucket({ name: bucketName });
-                        return ctx.json(bucket, common_1.HTTP.ResultCodes.RS_2.Ok);
-                    },
-                });
-                this.bindRoute({
-                    configs: { ...base_definition_1.StaticAssetDefinitions.GET_OBJECT_BY_NAME, ...routes?.getObjectByName },
+                    configs: { ...definitions.GET_OBJECT_BY_NAME, ...routes?.getObjectByName },
                 }).to({
                     handler: async (ctx) => {
-                        const { bucketName, objectName: rawObjectName } = ctx.req.valid('param');
-                        const objectName = readObjectName(rawObjectName);
-                        if (!helper.isValidName(bucketName)) {
+                        const params = ctx.req.valid('param');
+                        const bucketName = 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.isValidPath(objectName, { maxDepth: maxFolderDepth })) {
+                        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: bucketName, name: objectName });
+                        const fileStat = await helper.getStat({
+                            bucket: { name: bucketName },
+                            object: { key: objectName },
+                        });
                         const { size, metadata } = fileStat;
                         applyMetadataHeaders({ ctx, metadata });
-                        if (!ctx.res.headers.has(common_1.HTTP.Headers.CONTENT_TYPE)) {
-                            ctx.header(common_1.HTTP.Headers.CONTENT_TYPE, common_1.HTTP.HeaderValues.APPLICATION_OCTET_STREAM);
-                        }
-                        ctx.header(common_1.HTTP.Headers.CONTENT_LENGTH, size.toString());
+                        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');
-                        const stream = await helper.getFile({ bucket: bucketName, name: objectName });
+                        // 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: common_1.HTTP.ResultCodes.RS_2.Ok,
+                            status: range ? common_1.HTTP.ResultCodes.RS_2.PartialContent : common_1.HTTP.ResultCodes.RS_2.Ok,
                         });
                     },
                 });
                 this.bindRoute({
                     configs: {
-                        ...base_definition_1.StaticAssetDefinitions.DOWNLOAD_OBJECT_BY_NAME,
+                        ...definitions.DOWNLOAD_OBJECT_BY_NAME,
                         ...routes?.downloadObjectByName,
                     },
                 }).to({
                     handler: async (ctx) => {
-                        const { bucketName, objectName: rawObjectName } = ctx.req.valid('param');
-                        const objectName = readObjectName(rawObjectName);
-                        if (!helper.isValidName(bucketName)) {
+                        const params = ctx.req.valid('param');
+                        const bucketName = 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.isValidPath(objectName, { maxDepth: maxFolderDepth })) {
+                        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: bucketName, name: objectName });
+                        const fileStat = await helper.getStat({
+                            bucket: { name: bucketName },
+                            object: { key: objectName },
+                        });
                         const { size, metadata } = fileStat;
                         applyMetadataHeaders({ ctx, metadata });
-                        if (!ctx.res.headers.has(common_1.HTTP.Headers.CONTENT_TYPE)) {
-                            ctx.header(common_1.HTTP.Headers.CONTENT_TYPE, common_1.HTTP.HeaderValues.APPLICATION_OCTET_STREAM);
-                        }
+                        // 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');
-                        const stream = await helper.getFile({ bucket: bucketName, name: objectName });
+                        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,
@@ -145,24 +296,16 @@ class AssetControllerFactory extends core_1.BaseHelper {
                     },
                 });
                 this.bindRoute({
-                    configs: { ...base_definition_1.StaticAssetDefinitions.CREATE_BUCKET, ...routes?.createBucket },
+                    configs: { ...definitions.UPLOAD, ...routes?.upload },
                 }).to({
                     handler: async (ctx) => {
-                        const { bucketName } = ctx.req.valid('param');
-                        if (!helper.isValidName(bucketName)) {
-                            throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
-                        }
-                        const createdBucket = await helper.createBucket({ name: bucketName });
-                        return ctx.json(createdBucket, common_1.HTTP.ResultCodes.RS_2.Ok);
-                    },
-                });
-                this.bindRoute({
-                    configs: { ...base_definition_1.StaticAssetDefinitions.UPLOAD, ...routes?.upload },
-                }).to({
-                    handler: async (ctx) => {
-                        const { bucketName } = ctx.req.valid('param');
+                        // 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 = resolveBucket({ configured: bucket, param: bucketParam });
                         const query = ctx.req.valid('query');
-                        if (!helper.isValidName(bucketName)) {
+                        if (!helper.isValidBucketName({ bucket: { name: bucketName } })) {
                             throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
                         }
                         const folderPath = query.folderPath;
@@ -179,7 +322,7 @@ class AssetControllerFactory extends core_1.BaseHelper {
                                     message: `Folder path exceeds max depth of ${maxFolderDepth}`,
                                 });
                             }
-                            const invalidSegmentIndex = folderSegments.findIndex(segment => !helper.isValidName(segment));
+                            const invalidSegmentIndex = folderSegments.findIndex(segment => !helper.isValidSegment({ segment }));
                             if (invalidSegmentIndex !== -1) {
                                 throw (0, core_1.getError)({
                                     error: common_2.StaticAssetErrors.FOLDER_SEGMENT_INVALID,
@@ -215,11 +358,25 @@ class AssetControllerFactory extends core_1.BaseHelper {
                                     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,
+                                    });
+                                }
+                                : options?.normalizeNameFn;
                             uploaded = await helper.upload({
-                                bucket: bucketName,
+                                bucket: { name: bucketName },
                                 files: modifiedFiles,
-                                normalizeNameFn: options?.normalizeNameFn,
-                                normalizeLinkFn: options?.normalizeLinkFn,
+                                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,
                             });
@@ -234,8 +391,8 @@ class AssetControllerFactory extends core_1.BaseHelper {
                         for (const uploadResult of uploaded) {
                             try {
                                 const fileStat = await helper.getStat({
-                                    bucket: uploadResult.bucketName,
-                                    name: uploadResult.objectName,
+                                    bucket: uploadResult.bucket,
+                                    object: uploadResult.object,
                                 });
                                 const { data: createdMetaLink } = metaLink.createMetaLink
                                     ? await metaLink.createMetaLink({
@@ -245,10 +402,12 @@ class AssetControllerFactory extends core_1.BaseHelper {
                                     })
                                     : await metaLink.repository.create({
                                         data: {
-                                            bucketName: uploadResult.bucketName,
-                                            objectName: uploadResult.objectName,
+                                            bucketName: uploadResult.bucket.name,
+                                            objectName: uploadResult.object.key,
                                             link: uploadResult.link,
-                                            mimetype: fileStat.metadata?.['mimetype'],
+                                            // 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,
@@ -261,20 +420,19 @@ class AssetControllerFactory extends core_1.BaseHelper {
                                             variant: query.variant ? String(query.variant) : undefined,
                                         },
                                     });
-                                results.push({ ...uploadResult, metaLink: createdMetaLink });
+                                results.push({ ...uploadResult, metaLink: { data: createdMetaLink } });
                             }
                             catch (error) {
                                 this.logger
                                     .for('UPLOAD')
-                                    .error('Failed to create MetaLink | objectName: %s | Error: %s', uploadResult.objectName, error);
+                                    .error('Failed to create MetaLink | objectName: %s | Error: %s', uploadResult.object.key, error);
                                 results.push({
                                     ...uploadResult,
-                                    metaLink: null,
                                     // 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.
-                                    metaLinkError: 'META_LINK_CREATE_FAILED',
+                                    metaLink: { error: 'META_LINK_CREATE_FAILED' },
                                 });
                             }
                         }
@@ -282,32 +440,31 @@ class AssetControllerFactory extends core_1.BaseHelper {
                     },
                 });
                 this.bindRoute({
-                    configs: { ...base_definition_1.StaticAssetDefinitions.DELETE_BUCKET, ...routes?.deleteBucket },
-                }).to({
-                    handler: async (ctx) => {
-                        const { bucketName } = ctx.req.valid('param');
-                        if (!helper.isValidName(bucketName)) {
-                            throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.BUCKET_NAME_INVALID });
-                        }
-                        const isRemovedBucket = await helper.removeBucket({
-                            name: bucketName,
-                        });
-                        return ctx.json({ isDeleted: isRemovedBucket }, common_1.HTTP.ResultCodes.RS_2.Ok);
-                    },
-                });
-                this.bindRoute({
-                    configs: { ...base_definition_1.StaticAssetDefinitions.DELETE_OBJECT, ...routes?.deleteObject },
+                    configs: { ...definitions.DELETE_OBJECT, ...routes?.deleteObject },
                 }).to({
                     handler: async (ctx) => {
-                        const { bucketName, objectName: rawObjectName } = ctx.req.valid('param');
-                        const objectName = readObjectName(rawObjectName);
-                        if (!helper.isValidName(bucketName)) {
+                        const params = ctx.req.valid('param');
+                        const bucketName = 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.isValidPath(objectName, { maxDepth: maxFolderDepth })) {
+                        if (!helper.isValidObjectKey({ object: { key: objectName }, maxDepth: maxFolderDepth })) {
                             throw (0, core_1.getError)({ error: common_2.StaticAssetErrors.OBJECT_NAME_INVALID });
                         }
-                        await helper.removeObject({ bucket: bucketName, name: objectName });
+                        // 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;
+                            }
+                        }
                         if (!useMetaLink || !metaLink) {
                             return ctx.json({ success: true }, common_1.HTTP.ResultCodes.RS_2.Ok);
                         }
@@ -332,12 +489,16 @@ class AssetControllerFactory extends core_1.BaseHelper {
                     },
                 });
                 this.bindRoute({
-                    configs: { ...base_definition_1.StaticAssetDefinitions.LIST_OBJECTS, ...routes?.listObjects },
+                    configs: { ...definitions.LIST_OBJECTS, ...routes?.listObjects },
                 }).to({
                     handler: async (ctx) => {
-                        const { bucketName } = ctx.req.valid('param');
+                        // 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 = resolveBucket({ configured: bucket, param: bucketParam });
                         const { prefix, recursive, maxKeys } = ctx.req.valid('query');
-                        if (!helper.isValidName(bucketName)) {
+                        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.
@@ -352,7 +513,7 @@ class AssetControllerFactory extends core_1.BaseHelper {
                             }
                         }
                         const objects = await helper.listObjects({
-                            bucket: bucketName,
+                            bucket: { name: bucketName },
                             prefix,
                             useRecursive: recursive === 'true',
                             maxKeys: resolvedMaxKeys,
@@ -362,24 +523,34 @@ class AssetControllerFactory extends core_1.BaseHelper {
                 });
                 if (useMetaLink && metaLink) {
                     this.bindRoute({
-                        configs: { ...base_definition_1.StaticAssetDefinitions.RECREATE_METALINK, ...routes?.recreateMetaLink },
+                        configs: { ...definitions.RECREATE_METALINK, ...routes?.recreateMetaLink },
                     }).to({
                         handler: async (ctx) => {
-                            const { bucketName, objectName: rawObjectName } = ctx.req.valid('param');
-                            const objectName = readObjectName(rawObjectName);
-                            if (!helper.isValidName(bucketName)) {
+                            const params = ctx.req.valid('param');
+                            const bucketName = 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.isValidPath(objectName, { maxDepth: maxFolderDepth })) {
+                            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: bucketName,
-                                name: objectName,
+                                bucket: { name: bucketName },
+                                object: { key: objectName },
                             });
                             const link = options?.normalizeLinkFn
-                                ? options.normalizeLinkFn({ bucketName, normalizeName: objectName })
-                                : `${normalizedBasePath}/buckets/${bucketName}/objects/${encodeObjectPath(objectName)}`;
+                                ? options.normalizeLinkFn({
+                                    bucket: { name: bucketName },
+                                    object: { key: objectName },
+                                })
+                                : (0, exports.buildObjectLink)({
+                                    basePath: normalizedBasePath,
+                                    bucket: { name: bucketName },
+                                    object: { key: objectName },
+                                    hasConfiguredBucket,
+                                    rawObjectPath,
+                                });
                             const existing = await metaLink.repository.findOne({
                                 filter: {
                                     where: {
@@ -409,7 +580,7 @@ class AssetControllerFactory extends core_1.BaseHelper {
                                     bucketName,
                                     objectName,
                                     link,
-                                    mimetype: fileStat.metadata?.['mimetype'],
+                                    mimetype: fileStat.metadata?.mimetype ?? helper.getMimeType({ filename: objectName }),
                                     size: fileStat.size,
                                     etag: fileStat.etag,
                                     metadata: fileStat.metadata,
@@ -421,6 +592,8 @@ class AssetControllerFactory extends core_1.BaseHelper {
                         },
                     });
                 }
+                // Last, so a built-in route always wins a path collision with an application's own.
+                defineExtraRoutes?.({ controller: this, helper, basePath: normalizedBasePath });
             }
         };
         GeneratedStaticAssetController = __decorate([