@venizia/ignis 0.4.6 → 0.4.7-1

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

@@ -24,31 +24,31 @@ export interface IAssetControllerOptions {
 /** 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. */
 declare const UPLOAD_LABEL_NAMES: readonly ["principalType", "principalId", "variant", "sequence", "folderPath"];
-/** Names any label a caller put in the query - where the upload routes refuse it. */
-export declare const findLabelsInQuery: (opts: {
-    query: Record<string, string>;
-    names?: ReadonlyArray<(typeof UPLOAD_LABEL_NAMES)[number]>;
-}) => string[];
-/** The URL of one object, in the shape its controller serves: no `/buckets/<name>` with a configured bucket, and a raw path with `rawObjectPath`. */
-export declare const buildObjectLink: (opts: IObjectLocation & {
-    basePath: string;
-    hasConfiguredBucket?: boolean;
-    rawObjectPath?: boolean;
-}) => string;
-/**
- * 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`.
- */
-export declare const resolveServedContentType: (opts: {
-    helper: IStorageHelper;
-    object: IObjectRef;
-}) => {
-    contentType: string;
-    isRenderable: boolean;
-};
 export declare class AssetControllerFactory extends BaseHelper {
     constructor();
+    /** Names any label a caller put in the query - where the upload routes refuse it. */
+    static findLabelsInQuery(opts: {
+        query: Record<string, string>;
+        names?: ReadonlyArray<(typeof UPLOAD_LABEL_NAMES)[number]>;
+    }): string[];
+    /** The URL of one object, in the shape its controller serves: no `/buckets/<name>` with a configured bucket, and a raw path with `rawObjectPath`. */
+    static buildObjectLink(opts: IObjectLocation & {
+        basePath: string;
+        hasConfiguredBucket?: boolean;
+        rawObjectPath?: boolean;
+    }): string;
+    /**
+     * The served type comes from the object NAME, never the backend or the uploader: a renderable type on
+     * the API origin is stored XSS. Public so a hand-written route makes the same decision - the
+     * backend's own content-type is dropped by `WHITELIST_HEADERS`.
+     */
+    static resolveServedContentType(opts: {
+        helper: IStorageHelper;
+        object: IObjectRef;
+    }): {
+        contentType: string;
+        isRenderable: boolean;
+    };
     static defineAssetController(opts: IAssetControllerOptions): {
         new (): {
             /** Clears the multipart spool files written by `parseMultipartBody({ storage: 'disk' })`. */

package/dist/esm/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,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE5E,OAAO,EAGL,KAAK,eAAe,EAEpB,KAAK,UAAU,EAEf,KAAK,cAAc,EAMpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAA2B,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC7F,OAAO,KAAK,EAAE,OAAO,EAAyB,MAAM,+BAA+B,CAAC;AACpF,OAAO,EAAE,UAAU,EAAwB,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAEhC,OAAO,EAIL,KAAK,kBAAkB,EAEvB,KAAK,eAAe,EAKpB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EAClC,KAAK,uBAAuB,EAG7B,MAAM,WAAW,CAAC;AAYnB,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,iRAAiR;IACjR,QAAQ,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,wBAAwB,CAAC;IAEnC,qHAAqH;IACrH,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IAExC,oGAAoG;IACpG,4IAA4I;IAC5I,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;CACxC;AAED,6OAA6O;AAC7O,mIAAmI;AACnI,0EAA0E;AAC1E,QAAA,MAAM,kBAAkB,gFAMd,CAAC;AAEX,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,GAAI,MAAM;IACtC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,aAAa,CAAC,CAAC,OAAO,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5D,KAAG,MAAM,EAAyF,CAAC;AA8DpG,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;;YAwDtD,6FAA6F;2CAC9D;gBAAE,KAAK,EAAE,MAAM,EAAE,CAAA;aAAE,GAAG,IAAI;uBAYrC,cAAc,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBArRrB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsmCzB"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../../src/components/static-asset/controller/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE5E,OAAO,EAIL,KAAK,eAAe,EAEpB,KAAK,UAAU,EACf,KAAK,cAAc,EAKpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC3F,OAAO,KAAK,EAAE,OAAO,EAAyB,MAAM,+BAA+B,CAAC;AACpF,OAAO,EAAE,UAAU,EAAwB,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAEhC,OAAO,EAIL,KAAK,kBAAkB,EAEvB,KAAK,eAAe,EAKpB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EAClC,KAAK,uBAAuB,EAG7B,MAAM,WAAW,CAAC;AAOnB,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,iRAAiR;IACjR,QAAQ,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,wBAAwB,CAAC;IAEnC,qHAAqH;IACrH,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IAExC,oGAAoG;IACpG,4IAA4I;IAC5I,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;CACxC;AAED,6OAA6O;AAC7O,mIAAmI;AACnI,0EAA0E;AAC1E,QAAA,MAAM,kBAAkB,gFAMd,CAAC;AAuIX,qBAAa,sBAAuB,SAAQ,UAAU;;IAKpD,qFAAqF;IACrF,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE;QAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC9B,KAAK,CAAC,EAAE,aAAa,CAAC,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;KAC5D,GAAG,MAAM,EAAE;IAIZ,qJAAqJ;IACrJ,MAAM,CAAC,eAAe,CACpB,IAAI,EAAE,eAAe,GAAG;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,GACA,MAAM;IAUT;;;;OAIG;IACH,MAAM,CAAC,wBAAwB,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,GAAG;QACrF,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,OAAO,CAAC;KACvB;IAeD,MAAM,CAAC,qBAAqB,CAAC,IAAI,EAAE,uBAAuB;;YAwDtD,6FAA6F;2CAC9D;gBAAE,KAAK,EAAE,MAAM,EAAE,CAAA;aAAE,GAAG,IAAI;uBAYrC,cAAc,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA5RzC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmoCL"}

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

@@ -9,16 +9,16 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { BaseRestController } from '../../../base/controllers/index.js';
 import { controller as controllerDecorator } from '../../../base/metadata/index.js';
-import { BaseStorageHelper, createContentDispositionHeader, isNotFoundError, parseMultipartBody, } from '@venizia/ignis-helpers';
-import { HTTP, resolveValueAsync } from '@venizia/ignis-helpers/common';
+import { BaseStorageHelper, RequestUtility, StorageUtility, } from '@venizia/ignis-helpers';
+import { HTTP, ResolverUtility } from '@venizia/ignis-helpers/common';
 import { BaseHelper, getError, UuidHelper } from '@venizia/ignis-helpers/core';
 import { readFileSync, rmSync } from 'node:fs';
 import { RENDERABLE_CONTENT_TYPES, StaticAssetErrors, DEFAULT_PENDING_PREFIX, META_LINK_CREATE_FAILED, WHITELIST_HEADERS, } from '../common/index.js';
-import { buildCommitToken, MetaLinkRecreateActions, readCommitToken } from '../common/index.js';
-import { buildAssetDefinitions } from './base.definition.js';
-import { assertKeyInScope, isKeyInScope, normalizeKeyPrefix, resolveScopedListPrefix, } from './key-scope.js';
-import { buildStoredUploadResult, createMetaLinkRow, refreshMetaLinkRows } from './meta-link.js';
-import { appendDeclaredLengthGuard, readRouteOverride } from './route-options.js';
+import { AssetCommitToken, MetaLinkRecreateActions } from '../common/index.js';
+import { AssetDefinitionBuilder } from './base.definition.js';
+import { AssetKeyScope } from './key-scope.js';
+import { AssetMetaLink } from './meta-link.js';
+import { AssetRouteOptions } from './route-options.js';
 /** 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. */
@@ -29,11 +29,11 @@ const UPLOAD_LABEL_NAMES = [
     'sequence',
     'folderPath',
 ];
-/** Names any label a caller put in the query - where the upload routes refuse it. */
-export const findLabelsInQuery = (opts) => (opts.names ?? UPLOAD_LABEL_NAMES).filter((name) => opts.query[name] !== undefined);
+/** The body of `AssetControllerFactory.findLabelsInQuery`, callable from the helpers above the class. */
+const listLabelsInQuery = (opts) => (opts.names ?? UPLOAD_LABEL_NAMES).filter((name) => opts.query[name] !== undefined);
 /** Refused before the body is read: a route that ignored them would store an unlabelled row. */
 const refuseLabelsInQuery = (opts) => {
-    const names = findLabelsInQuery(opts);
+    const names = listLabelsInQuery(opts);
     if (names.length > 0) {
         throw getError({
             error: StaticAssetErrors.LABELS_IN_QUERY,
@@ -70,15 +70,7 @@ const resolveBucket = async (opts) => {
     if (configured === undefined) {
         return param ?? '';
     }
-    return resolveValueAsync({ value: configured });
-};
-/** The URL of one object, in the shape its controller serves: no `/buckets/<name>` with a configured bucket, and a raw path with `rawObjectPath`. */
-export 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}`;
+    return ResolverUtility.resolveValueAsync({ value: configured });
 };
 /** Mirrors `BaseStorageHelper.normalizeObjectName`, which is protected: `resolveObjectName` is offered the very name the helper would otherwise have written. */
 const defaultObjectName = ({ file }) => {
@@ -89,19 +81,6 @@ const defaultObjectName = ({ file }) => {
     }
     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`.
- */
-export const resolveServedContentType = (opts) => {
-    const { helper, object } = opts;
-    const candidate = helper.getMimeType({ filename: object.key }).toLowerCase().split(';')[0].trim();
-    if (!RENDERABLE_CONTENT_TYPES.has(candidate)) {
-        return { contentType: HTTP.HeaderValues.APPLICATION_OCTET_STREAM, isRenderable: false };
-    }
-    return { contentType: candidate, isRenderable: true };
-};
 /**
  * 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
@@ -145,6 +124,35 @@ export class AssetControllerFactory extends BaseHelper {
     constructor() {
         super({ scope: AssetControllerFactory.name });
     }
+    /** Names any label a caller put in the query - where the upload routes refuse it. */
+    static findLabelsInQuery(opts) {
+        return listLabelsInQuery(opts);
+    }
+    /** The URL of one object, in the shape its controller serves: no `/buckets/<name>` with a configured bucket, and a raw path with `rawObjectPath`. */
+    static 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}`;
+    }
+    /**
+     * The served type comes from the object NAME, never the backend or the uploader: a renderable type on
+     * the API origin is stored XSS. Public so a hand-written route makes the same decision - the
+     * backend's own content-type is dropped by `WHITELIST_HEADERS`.
+     */
+    static resolveServedContentType(opts) {
+        const { helper, object } = opts;
+        const candidate = helper
+            .getMimeType({ filename: object.key })
+            .toLowerCase()
+            .split(';')[0]
+            .trim();
+        if (!RENDERABLE_CONTENT_TYPES.has(candidate)) {
+            return { contentType: HTTP.HeaderValues.APPLICATION_OCTET_STREAM, isRenderable: false };
+        }
+        return { contentType: candidate, isRenderable: true };
+    }
     static defineAssetController(opts) {
         const { controller, helper, options, useMetaLink, metaLink, storage } = opts;
         const { resolveObjectName, defineRoutesBefore, defineExtraRoutes } = opts;
@@ -161,18 +169,18 @@ export class AssetControllerFactory extends BaseHelper {
         }
         const scope = controller.keyPrefix === undefined
             ? undefined
-            : normalizeKeyPrefix({ keyPrefix: controller.keyPrefix, helper, scope: name });
+            : AssetKeyScope.normalizePrefix({ 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 = buildAssetDefinitions({ hasConfiguredBucket, rawObjectPath });
+        const definitions = AssetDefinitionBuilder.build({ 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) => buildObjectLink({
+            ? (linkOptions) => AssetControllerFactory.buildObjectLink({
                 basePath: normalizedBasePath,
                 bucket: linkOptions.bucket,
                 object: linkOptions.object,
@@ -208,7 +216,7 @@ export class AssetControllerFactory extends 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 = readRouteOverride({ route: routes?.getBuckets });
+                    const getBucketsRoute = AssetRouteOptions.readOverride({ route: routes?.getBuckets });
                     if (getBucketsRoute.isEnabled) {
                         this.bindRoute({
                             configs: { ...definitions.GET_BUCKETS, ...getBucketsRoute.override },
@@ -219,7 +227,9 @@ export class AssetControllerFactory extends BaseHelper {
                             },
                         });
                     }
-                    const getBucketByNameRoute = readRouteOverride({ route: routes?.getBucketByName });
+                    const getBucketByNameRoute = AssetRouteOptions.readOverride({
+                        route: routes?.getBucketByName,
+                    });
                     if (getBucketByNameRoute.isEnabled) {
                         this.bindRoute({
                             configs: { ...definitions.GET_BUCKET_BY_NAME, ...getBucketByNameRoute.override },
@@ -238,7 +248,7 @@ export class AssetControllerFactory extends BaseHelper {
                             },
                         });
                     }
-                    const createBucketRoute = readRouteOverride({ route: routes?.createBucket });
+                    const createBucketRoute = AssetRouteOptions.readOverride({ route: routes?.createBucket });
                     if (createBucketRoute.isEnabled) {
                         this.bindRoute({
                             configs: { ...definitions.CREATE_BUCKET, ...createBucketRoute.override },
@@ -257,7 +267,7 @@ export class AssetControllerFactory extends BaseHelper {
                             },
                         });
                     }
-                    const deleteBucketRoute = readRouteOverride({ route: routes?.deleteBucket });
+                    const deleteBucketRoute = AssetRouteOptions.readOverride({ route: routes?.deleteBucket });
                     if (deleteBucketRoute.isEnabled) {
                         this.bindRoute({
                             configs: { ...definitions.DELETE_BUCKET, ...deleteBucketRoute.override },
@@ -279,7 +289,9 @@ export class AssetControllerFactory extends BaseHelper {
                         });
                     }
                 }
-                const getObjectByNameRoute = readRouteOverride({ route: routes?.getObjectByName });
+                const getObjectByNameRoute = AssetRouteOptions.readOverride({
+                    route: routes?.getObjectByName,
+                });
                 if (getObjectByNameRoute.isEnabled) {
                     this.bindRoute({
                         configs: { ...definitions.GET_OBJECT_BY_NAME, ...getObjectByNameRoute.override },
@@ -301,14 +313,17 @@ export class AssetControllerFactory extends BaseHelper {
                                 throw getError({ error: StaticAssetErrors.OBJECT_NAME_INVALID });
                             }
                             // Before any storage call: a key outside the scope must not even be probed.
-                            assertKeyInScope({ key: objectName, keyPrefix });
+                            AssetKeyScope.assertInScope({ key: objectName, keyPrefix });
                             const fileStat = await helper.getStat({
                                 bucket: { name: bucketName },
                                 object: { key: objectName },
                             });
                             const { size, metadata } = fileStat;
                             applyMetadataHeaders({ ctx, metadata });
-                            const served = resolveServedContentType({ helper, object: { key: objectName } });
+                            const served = AssetControllerFactory.resolveServedContentType({
+                                helper,
+                                object: { key: objectName },
+                            });
                             ctx.header(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.
@@ -318,7 +333,10 @@ export class AssetControllerFactory extends BaseHelper {
                             // 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(HTTP.Headers.CONTENT_DISPOSITION, createContentDispositionHeader({ filename: inlineName, type: 'attachment' }));
+                                ctx.header(HTTP.Headers.CONTENT_DISPOSITION, RequestUtility.buildContentDispositionHeader({
+                                    filename: inlineName,
+                                    type: 'attachment',
+                                }));
                             }
                             const range = readByteRange({ header: ctx.req.header('range'), size });
                             if (range) {
@@ -341,7 +359,7 @@ export class AssetControllerFactory extends BaseHelper {
                         },
                     });
                 }
-                const downloadObjectByNameRoute = readRouteOverride({
+                const downloadObjectByNameRoute = AssetRouteOptions.readOverride({
                     route: routes?.downloadObjectByName,
                 });
                 if (downloadObjectByNameRoute.isEnabled) {
@@ -368,7 +386,7 @@ export class AssetControllerFactory extends BaseHelper {
                                 throw getError({ error: StaticAssetErrors.OBJECT_NAME_INVALID });
                             }
                             // Before any storage call: a key outside the scope must not even be probed.
-                            assertKeyInScope({ key: objectName, keyPrefix });
+                            AssetKeyScope.assertInScope({ key: objectName, keyPrefix });
                             const fileStat = await helper.getStat({
                                 bucket: { name: bucketName },
                                 object: { key: objectName },
@@ -376,11 +394,17 @@ export class AssetControllerFactory extends BaseHelper {
                             const { size, metadata } = fileStat;
                             applyMetadataHeaders({ ctx, metadata });
                             // Download always attaches, so the served type only has to be honest, never renderable.
-                            const served = resolveServedContentType({ helper, object: { key: objectName } });
+                            const served = AssetControllerFactory.resolveServedContentType({
+                                helper,
+                                object: { key: objectName },
+                            });
                             ctx.header(HTTP.Headers.CONTENT_TYPE, served.contentType);
                             ctx.header(HTTP.Headers.CONTENT_LENGTH, size.toString());
                             const fileName = objectName.split('/').pop() ?? objectName;
-                            ctx.header(HTTP.Headers.CONTENT_DISPOSITION, createContentDispositionHeader({ filename: fileName, type: 'attachment' }));
+                            ctx.header(HTTP.Headers.CONTENT_DISPOSITION, RequestUtility.buildContentDispositionHeader({
+                                filename: fileName,
+                                type: 'attachment',
+                            }));
                             ctx.header('x-content-type-options', 'nosniff');
                             ctx.header(HTTP.Headers.CONTENT_SECURITY_POLICY, 'sandbox');
                             const stream = await helper.getObjectStream({
@@ -394,11 +418,11 @@ export class AssetControllerFactory extends BaseHelper {
                         },
                     });
                 }
-                const uploadRoute = readRouteOverride({ route: routes?.upload });
+                const uploadRoute = AssetRouteOptions.readOverride({ route: routes?.upload });
                 if (uploadRoute.isEnabled) {
                     const uploadMiddleware = maxBytes === undefined
                         ? uploadRoute.override.middleware
-                        : appendDeclaredLengthGuard({
+                        : AssetRouteOptions.appendLengthGuard({
                             middleware: uploadRoute.override.middleware,
                             maxBytes,
                         });
@@ -440,7 +464,7 @@ export class AssetControllerFactory extends BaseHelper {
                                 }
                             };
                             refuseLabelsInQuery({ query: ctx.req.query() });
-                            const { files: filesArray, fields } = await parseMultipartBody({
+                            const { files: filesArray, fields } = await RequestUtility.parseMultipartBody({
                                 context: ctx,
                                 storage: options?.parseMultipartBody?.storage,
                                 uploadDir: options?.parseMultipartBody?.uploadDir,
@@ -501,7 +525,7 @@ export class AssetControllerFactory extends BaseHelper {
                                                 defaultKey,
                                             })
                                             : defaultKey;
-                                        if (!isKeyInScope({ key, keyPrefix })) {
+                                        if (!AssetKeyScope.isInScope({ key, keyPrefix })) {
                                             throw getError({
                                                 error: StaticAssetErrors.OBJECT_KEY_OUT_OF_SCOPE,
                                                 message: `Object key is outside the key prefix of this controller | key: ${key} | keyPrefix: ${keyPrefix}`,
@@ -510,7 +534,7 @@ export class AssetControllerFactory extends BaseHelper {
                                         return key;
                                     }
                                     : options?.normalizeNameFn;
-                                uploaded = await helper.upload({
+                                const result = await helper.upload({
                                     bucket: { name: bucketName },
                                     files: modifiedFiles,
                                     normalizeNameFn,
@@ -518,6 +542,7 @@ export class AssetControllerFactory extends BaseHelper {
                                     // 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,
                                 });
+                                uploaded = result;
                             }
                             finally {
                                 this.removeSpoolFiles({ paths: spoolPaths });
@@ -532,7 +557,7 @@ export class AssetControllerFactory extends BaseHelper {
                                         bucket: uploadResult.bucket,
                                         object: uploadResult.object,
                                     });
-                                    const createdMetaLink = await createMetaLinkRow({
+                                    const createdMetaLink = await AssetMetaLink.createRow({
                                         metaLink,
                                         helper,
                                         storage,
@@ -560,7 +585,7 @@ export class AssetControllerFactory extends BaseHelper {
                         },
                     });
                 }
-                const deleteObjectRoute = readRouteOverride({ route: routes?.deleteObject });
+                const deleteObjectRoute = AssetRouteOptions.readOverride({ route: routes?.deleteObject });
                 if (deleteObjectRoute.isEnabled) {
                     this.bindRoute({
                         configs: { ...definitions.DELETE_OBJECT, ...deleteObjectRoute.override },
@@ -582,7 +607,7 @@ export class AssetControllerFactory extends BaseHelper {
                                 throw getError({ error: StaticAssetErrors.OBJECT_NAME_INVALID });
                             }
                             // Before any storage call: a key outside the scope must not even be probed.
-                            assertKeyInScope({ key: objectName, keyPrefix });
+                            AssetKeyScope.assertInScope({ 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 {
@@ -592,14 +617,16 @@ export class AssetControllerFactory extends BaseHelper {
                                 });
                             }
                             catch (error) {
-                                if (!isNotFoundError({ error })) {
+                                if (!StorageUtility.isNotFoundError({ error })) {
                                     throw error;
                                 }
                             }
                             if (!useMetaLink || !metaLink) {
                                 return ctx.json({ success: true }, HTTP.ResultCodes.RS_2.Ok);
                             }
-                            const deleteRepository = await resolveValueAsync({ value: metaLink.repository });
+                            const deleteRepository = await ResolverUtility.resolveValueAsync({
+                                value: metaLink.repository,
+                            });
                             deleteRepository
                                 .deleteAll({
                                 where: {
@@ -621,7 +648,7 @@ export class AssetControllerFactory extends BaseHelper {
                         },
                     });
                 }
-                const listObjectsRoute = readRouteOverride({ route: routes?.listObjects });
+                const listObjectsRoute = AssetRouteOptions.readOverride({ route: routes?.listObjects });
                 if (listObjectsRoute.isEnabled) {
                     this.bindRoute({
                         configs: { ...definitions.LIST_OBJECTS, ...listObjectsRoute.override },
@@ -647,7 +674,7 @@ export class AssetControllerFactory extends BaseHelper {
                                     });
                                 }
                             }
-                            const scoped = resolveScopedListPrefix({ prefix, keyPrefix });
+                            const scoped = AssetKeyScope.resolveListPrefix({ prefix, keyPrefix });
                             if (scoped.isOutOfScope) {
                                 return ctx.json([], HTTP.ResultCodes.RS_2.Ok);
                             }
@@ -670,13 +697,14 @@ export class AssetControllerFactory extends BaseHelper {
                     const pendingPrefix = directUpload.pendingPrefix ?? 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 = readRouteOverride({ route: routes?.uploadPolicy });
+                    const uploadPolicyRoute = AssetRouteOptions.readOverride({ route: routes?.uploadPolicy });
                     if (uploadPolicyRoute.isEnabled) {
                         this.bindRoute({
                             configs: { ...definitions.UPLOAD_POLICY, ...uploadPolicyRoute.override },
                         }).to({
                             handler: async (ctx) => {
-                                if (!(await directUpload.authorize({ context: ctx }))) {
+                                const result = await directUpload.authorize({ context: ctx });
+                                if (!result) {
                                     throw getError({ error: StaticAssetErrors.UPLOAD_NOT_AUTHORIZED });
                                 }
                                 const { files } = ctx.req.valid('json');
@@ -702,7 +730,7 @@ export class AssetControllerFactory extends BaseHelper {
                                     policies.push({
                                         ...policy,
                                         objectName,
-                                        commitToken: buildCommitToken({
+                                        commitToken: AssetCommitToken.build({
                                             payload: {
                                                 bucket: bucketName,
                                                 key: objectName,
@@ -716,7 +744,7 @@ export class AssetControllerFactory extends BaseHelper {
                             },
                         });
                     }
-                    const uploadCommitRoute = readRouteOverride({ route: routes?.uploadCommit });
+                    const uploadCommitRoute = AssetRouteOptions.readOverride({ route: routes?.uploadCommit });
                     if (uploadCommitRoute.isEnabled) {
                         this.bindRoute({
                             configs: { ...definitions.UPLOAD_COMMIT, ...uploadCommitRoute.override },
@@ -732,7 +760,7 @@ export class AssetControllerFactory extends BaseHelper {
                                 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 = readCommitToken({
+                                const payload = AssetCommitToken.read({
                                     token: commitToken,
                                     secretKey: directUpload.secretKey,
                                 });
@@ -743,7 +771,7 @@ export class AssetControllerFactory extends BaseHelper {
                                 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.
-                                assertKeyInScope({ key: object.key, keyPrefix });
+                                AssetKeyScope.assertInScope({ 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 });
@@ -762,7 +790,7 @@ export class AssetControllerFactory extends BaseHelper {
                                         .for('UPLOAD_COMMIT')
                                         .warn('Committed, but the pending object remains | key: %s | error: %s', pendingObject.key, error);
                                 });
-                                const link = buildObjectLink({
+                                const link = AssetControllerFactory.buildObjectLink({
                                     basePath: normalizedBasePath,
                                     bucket: bucketRef,
                                     object,
@@ -775,11 +803,11 @@ export class AssetControllerFactory extends BaseHelper {
                                 if (useMetaLink && metaLink) {
                                     try {
                                         const fileStat = await helper.getStat({ bucket: bucketRef, object });
-                                        const data = await createMetaLinkRow({
+                                        const data = await AssetMetaLink.createRow({
                                             metaLink,
                                             helper,
                                             storage,
-                                            uploadResult: buildStoredUploadResult({
+                                            uploadResult: AssetMetaLink.buildStoredUploadResult({
                                                 helper,
                                                 bucket: bucketRef,
                                                 object,
@@ -811,7 +839,9 @@ export class AssetControllerFactory extends BaseHelper {
                     }
                 }
                 if (useMetaLink && metaLink) {
-                    const recreateMetaLinkRoute = readRouteOverride({ route: routes?.recreateMetaLink });
+                    const recreateMetaLinkRoute = AssetRouteOptions.readOverride({
+                        route: routes?.recreateMetaLink,
+                    });
                     if (recreateMetaLinkRoute.isEnabled) {
                         this.bindRoute({
                             configs: { ...definitions.RECREATE_METALINK, ...recreateMetaLinkRoute.override },
@@ -838,20 +868,20 @@ export class AssetControllerFactory extends BaseHelper {
                                     throw getError({ error: StaticAssetErrors.OBJECT_NAME_INVALID });
                                 }
                                 // Before any storage call: a key outside the scope must not even be probed.
-                                assertKeyInScope({ key: objectName, keyPrefix });
+                                AssetKeyScope.assertInScope({ 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 })
-                                    : buildObjectLink({
+                                    : AssetControllerFactory.buildObjectLink({
                                         basePath: normalizedBasePath,
                                         bucket: bucketRef,
                                         object,
                                         hasConfiguredBucket,
                                         rawObjectPath,
                                     });
-                                const refreshed = await refreshMetaLinkRows({
+                                const refreshed = await AssetMetaLink.refreshRows({
                                     metaLink,
                                     helper,
                                     bucket: bucketRef,
@@ -870,11 +900,11 @@ export class AssetControllerFactory extends BaseHelper {
                                 }
                                 // 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 createMetaLinkRow({
+                                const created = await AssetMetaLink.createRow({
                                     metaLink,
                                     helper,
                                     storage,
-                                    uploadResult: buildStoredUploadResult({
+                                    uploadResult: AssetMetaLink.buildStoredUploadResult({
                                         helper,
                                         bucket: bucketRef,
                                         object,