@nestm/storage 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/files-sdk/files-sdk.driver.js

@@ -1,46 +1,324 @@
 import { Readable } from 'node:stream';
-import { Files, FilesError, } from 'files-sdk';
+import { Files, FilesError, handlers, } from 'files-sdk';
 import { StorageError, StorageErrorCode, isStorageError, } from '../storage.error.js';
+import { isCanonicalStorageEtag, normalizeProviderStorageEtag, } from '../storage-etag.js';
 import { getFilesSdkUploadControl } from '../storage-upload-control.js';
+/**
+ * Interim compatibility gate until Files SDK exposes native conditional/CAS
+ * verbs through the same operation pipeline as its generic data plane.
+ */
+function hasCallerFilesOperationPolicy(options) {
+    const hooks = options.hooks;
+    return ((options.plugins?.length ?? 0) > 0 ||
+        typeof hooks?.onAction === 'function' ||
+        typeof hooks?.onError === 'function' ||
+        typeof hooks?.onRetry === 'function' ||
+        (options.receipts !== undefined && options.receipts !== false));
+}
+const FILES_SDK_S3_RESERVED_EXTENSION_KEYS = [
+    'conditionalCopyDestination',
+    'conditionalCopySource',
+    'conditionalCreate',
+    'conditionalDelete',
+    'conditionalMultipartCompletion',
+    'conditionalRead',
+    'conditionalReplace',
+    'deleteConditional',
+    'downloadConditional',
+    'physicalKey',
+    'promote',
+    'signedDownloadPolicy',
+    'signedUploadPolicy',
+    'uploadConditional',
+];
+const FILES_SDK_S3_AUTHORITY_KEYS = [
+    ...FILES_SDK_S3_RESERVED_EXTENSION_KEYS,
+    'bucket',
+    'copy',
+    'delete',
+    'deleteMany',
+    'download',
+    'exists',
+    'head',
+    'list',
+    'move',
+    'reportsUploadProgress',
+    'resumableUpload',
+    'signedUploadUrl',
+    'signedUrl',
+    'supportsCacheControl',
+    'supportsDelimiter',
+    'supportsMetadata',
+    'supportsRange',
+    'supportsServerSideCopy',
+    'upload',
+    'url',
+];
+const s3AdapterProvenance = new WeakMap();
+const undecoratedS3Adapters = new WeakSet();
+const s3AdapterAuthority = new WeakMap();
+const s3MethodAuthority = new WeakMap();
+const s3AuthorityState = new WeakMap();
+const conflictingS3Authority = Symbol('conflictingS3Authority');
+function adapterRawObject(adapter) {
+    try {
+        const raw = adapter.raw;
+        return (typeof raw === 'object' && raw !== null) ||
+            typeof raw === 'function'
+            ? raw
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function s3AdapterAuthorityTokenOf(adapter) {
+    let resolved = s3AdapterAuthority.get(adapter);
+    const consider = (token) => {
+        if (token === undefined)
+            return true;
+        if (resolved !== undefined && resolved !== token)
+            return false;
+        resolved = token;
+        return true;
+    };
+    try {
+        const candidate = adapter;
+        for (const key of FILES_SDK_S3_AUTHORITY_KEYS) {
+            if (!(key in candidate))
+                continue;
+            const value = candidate[key];
+            if (typeof value === 'function' &&
+                !consider(s3MethodAuthority.get(value))) {
+                return conflictingS3Authority;
+            }
+        }
+        return resolved;
+    }
+    catch {
+        return conflictingS3Authority;
+    }
+}
+function bindS3AdapterAuthorityMethods(adapter, token) {
+    const candidate = adapter;
+    for (const key of FILES_SDK_S3_AUTHORITY_KEYS) {
+        if (!(key in candidate))
+            continue;
+        const value = candidate[key];
+        if (typeof value !== 'function')
+            continue;
+        const existing = s3MethodAuthority.get(value);
+        if (existing !== undefined && existing !== token) {
+            throw new TypeError('S3 adapter methods have conflicting authority.');
+        }
+        s3MethodAuthority.set(value, token);
+    }
+}
+function attachS3AdapterAuthority(adapter, raw) {
+    const existing = s3AdapterAuthorityTokenOf(adapter);
+    if (existing === conflictingS3Authority) {
+        throw new TypeError('S3 adapter authority is inconsistent.');
+    }
+    const token = existing ?? Object.freeze({});
+    const state = s3AuthorityState.get(token);
+    if (state !== undefined && state.raw !== raw) {
+        throw new TypeError('S3 adapter authority raw client cannot be changed.');
+    }
+    if (state === undefined)
+        s3AuthorityState.set(token, { raw });
+    s3AdapterAuthority.set(adapter, token);
+    bindS3AdapterAuthorityMethods(adapter, token);
+    return token;
+}
+function setS3AdapterProvenance(target, adapter, provenance) {
+    const existing = s3AdapterProvenanceOfRaw(target);
+    if (existing !== undefined) {
+        if (existing.provenance !== provenance ||
+            mismatchedS3Authority(adapter, existing.surface) !== undefined) {
+            throw new TypeError('S3 adapter provenance cannot be changed.');
+        }
+        s3AdapterProvenance.set(target, existing);
+        return existing;
+    }
+    const record = Object.freeze({
+        provenance,
+        surface: s3AuthoritySnapshot(adapter),
+    });
+    s3AdapterProvenance.set(target, record);
+    return record;
+}
+function s3AdapterProvenanceOfRaw(raw) {
+    return s3AdapterProvenance.get(raw);
+}
+function s3AuthoritySnapshot(adapter) {
+    const candidate = adapter;
+    return Object.freeze(Object.fromEntries(FILES_SDK_S3_AUTHORITY_KEYS.map((key) => {
+        const present = key in candidate;
+        return [
+            key,
+            Object.freeze({
+                present,
+                value: present ? candidate[key] : undefined,
+            }),
+        ];
+    })));
+}
+function mismatchedS3Authority(adapter, snapshot) {
+    const candidate = adapter;
+    try {
+        return FILES_SDK_S3_AUTHORITY_KEYS.find((key) => {
+            const present = key in candidate;
+            const expected = snapshot[key];
+            return (present !== expected.present ||
+                !Object.is(present ? candidate[key] : undefined, expected.value));
+        });
+    }
+    catch {
+        return FILES_SDK_S3_AUTHORITY_KEYS[0];
+    }
+}
+/** Rejects adapters already carrying reserved storage S3 extensions. */
+export function assertFilesSdkS3AdapterHasNoReservedExtensions(adapter) {
+    const reserved = filesSdkS3ReservedExtensionOf(adapter);
+    if (reserved !== undefined) {
+        throw new TypeError(`S3 adapter already defines reserved extension "${reserved}".`);
+    }
+}
+function filesSdkS3ReservedExtensionOf(adapter) {
+    const candidate = adapter;
+    try {
+        return FILES_SDK_S3_RESERVED_EXTENSION_KEYS.find((key) => key in candidate);
+    }
+    catch {
+        return FILES_SDK_S3_RESERVED_EXTENSION_KEYS[0];
+    }
+}
+/** Records that an S3 adapter was constructed but not provider-decorated. */
+export function markFilesSdkS3AdapterUndecorated(adapter) {
+    const raw = adapterRawObject(adapter);
+    if (raw === undefined) {
+        throw new TypeError('S3 adapter must expose an object raw client.');
+    }
+    attachS3AdapterAuthority(adapter, raw);
+    undecoratedS3Adapters.add(raw);
+}
+/** Records the provider verification state of one decorated S3 adapter. */
+export function markFilesSdkS3AdapterProvenance(adapter, provenance) {
+    const raw = adapterRawObject(adapter);
+    if (raw === undefined) {
+        throw new TypeError('S3 adapter must expose an object raw client.');
+    }
+    markFilesSdkS3RawClientProvenance(raw, adapter, provenance);
+}
+/** Records final provider verification state on one stable raw S3 client. */
+export function markFilesSdkS3RawClientProvenance(raw, adapter, provenance) {
+    const authority = attachS3AdapterAuthority(adapter, raw);
+    const record = setS3AdapterProvenance(raw, adapter, provenance);
+    s3AuthorityState.set(authority, { raw, record });
+    bindS3AdapterAuthorityMethods(adapter, authority);
+}
+function isUndecoratedS3Raw(raw) {
+    return undecoratedS3Adapters.has(raw);
+}
+function isStructuralS3Raw(raw) {
+    try {
+        const candidate = raw;
+        return (typeof candidate.send === 'function' &&
+            typeof candidate.config === 'object' &&
+            candidate.config !== null &&
+            candidate.config.serviceId === 'S3');
+    }
+    catch {
+        return false;
+    }
+}
 function conditionalCopyAdapterOf(adapter) {
     if (typeof adapter !== 'object' ||
         adapter === null ||
-        !('conditionalCopy' in adapter) ||
         !('promote' in adapter)) {
         return undefined;
     }
     const candidate = adapter;
-    const capability = candidate.conditionalCopy;
-    if (capability === undefined ||
-        typeof capability.supported !== 'boolean' ||
-        typeof capability.etag !== 'boolean' ||
-        typeof capability.version !== 'boolean' ||
+    const source = candidate.conditionalCopySource;
+    const destination = candidate.conditionalCopyDestination;
+    if ((source === undefined && destination === undefined) ||
+        (source !== undefined &&
+            (typeof source.etag !== 'boolean' ||
+                typeof source.version !== 'boolean')) ||
+        (destination !== undefined &&
+            (typeof destination.create !== 'boolean' ||
+                typeof destination.replace !== 'boolean' ||
+                typeof destination.atomicWithSource !== 'boolean')) ||
         typeof candidate.promote !== 'function') {
         return undefined;
     }
     return candidate;
 }
-function conditionalMutationAdapterOf(adapter) {
+function conditionalUploadAdapterOf(adapter) {
     if (typeof adapter !== 'object' ||
         adapter === null ||
-        !('conditionalMutation' in adapter) ||
-        !('uploadConditional' in adapter) ||
+        !('uploadConditional' in adapter)) {
+        return undefined;
+    }
+    const candidate = adapter;
+    const create = candidate.conditionalCreate;
+    const replace = candidate.conditionalReplace;
+    const multipart = candidate.conditionalMultipartCompletion;
+    if ((create === undefined && replace === undefined) ||
+        (create !== undefined && typeof create.resultEtag !== 'boolean') ||
+        (replace !== undefined && typeof replace.resultEtag !== 'boolean') ||
+        (multipart !== undefined &&
+            (typeof multipart.create !== 'boolean' ||
+                typeof multipart.replace !== 'boolean')) ||
+        typeof candidate.uploadConditional !== 'function') {
+        return undefined;
+    }
+    return candidate;
+}
+function conditionalDeleteAdapterOf(adapter) {
+    if (typeof adapter !== 'object' ||
+        adapter === null ||
+        !('conditionalDelete' in adapter) ||
         !('deleteConditional' in adapter)) {
         return undefined;
     }
     const candidate = adapter;
-    const capability = candidate.conditionalMutation;
-    if (capability === undefined ||
-        typeof capability.create !== 'boolean' ||
-        typeof capability.replace !== 'boolean' ||
-        typeof capability.delete !== 'boolean' ||
-        typeof capability.etag !== 'boolean' ||
-        typeof candidate.uploadConditional !== 'function' ||
+    if (candidate.conditionalDelete === undefined ||
+        typeof candidate.conditionalDelete.etag !== 'boolean' ||
         typeof candidate.deleteConditional !== 'function') {
         return undefined;
     }
     return candidate;
 }
+function conditionalReadAdapterOf(adapter) {
+    if (typeof adapter !== 'object' ||
+        adapter === null ||
+        !('conditionalRead' in adapter) ||
+        !('downloadConditional' in adapter)) {
+        return undefined;
+    }
+    const candidate = adapter;
+    if (candidate.conditionalRead === undefined ||
+        typeof candidate.conditionalRead.etag !== 'boolean' ||
+        typeof candidate.conditionalRead.version !== 'boolean' ||
+        typeof candidate.downloadConditional !== 'function') {
+        return undefined;
+    }
+    return candidate;
+}
+function physicalKeyAdapterOf(adapter) {
+    if (typeof adapter !== 'object' ||
+        adapter === null ||
+        !('physicalKey' in adapter)) {
+        return undefined;
+    }
+    const candidate = adapter;
+    const maxBytes = candidate.physicalKey?.maxBytes;
+    if (!Number.isSafeInteger(maxBytes) || (maxBytes ?? 0) <= 0) {
+        return undefined;
+    }
+    return candidate;
+}
 function signedUploadPolicyAdapterOf(adapter) {
     if (typeof adapter !== 'object' ||
         adapter === null ||
@@ -114,19 +392,42 @@ function unwrapFilesError(error) {
     }
     return current;
 }
+const PUBLIC_PROVIDER_ERROR_MESSAGES = Object.freeze({
+    [StorageErrorCode.NOT_FOUND]: 'Storage provider object was not found.',
+    [StorageErrorCode.UNAUTHORIZED]: 'Storage provider operation was unauthorized.',
+    [StorageErrorCode.CONFLICT]: 'Storage provider operation conflicted with current state.',
+    [StorageErrorCode.READ_ONLY]: 'Storage provider is read-only.',
+    [StorageErrorCode.INVALID_ARGUMENT]: 'Storage provider rejected an invalid argument.',
+    [StorageErrorCode.NOT_SUPPORTED]: 'Storage provider operation is not supported.',
+    [StorageErrorCode.ABORTED]: 'Storage provider operation was aborted.',
+    [StorageErrorCode.TIMEOUT]: 'Storage provider operation timed out.',
+    [StorageErrorCode.LIMIT_EXCEEDED]: 'Storage provider operation exceeded a limit.',
+    [StorageErrorCode.PROVIDER]: 'Storage provider operation failed.',
+});
+function sanitizedStorageError(error) {
+    return new StorageError(PUBLIC_PROVIDER_ERROR_MESSAGES[error.code], {
+        aborted: error.aborted,
+        code: error.code,
+        permanent: error.permanent,
+        timedOut: error.timedOut,
+    });
+}
 export function mapFilesSdkError(error) {
-    if (isStorageError(error)) {
-        return error;
-    }
+    if (isStorageError(error))
+        return sanitizedStorageError(error);
     if (!isFilesErrorLike(error)) {
-        return new StorageError(error instanceof Error ? error.message : String(error), {
-            cause: error,
+        return new StorageError('Storage provider operation failed.', {
             code: StorageErrorCode.PROVIDER,
         });
     }
     const filesError = unwrapFilesError(error);
-    if (isStorageError(filesError.cause)) {
-        return filesError.cause;
+    if (filesError.code === 'Provider' &&
+        !filesError.aborted &&
+        !filesError.timedOut &&
+        !filesError.permanent &&
+        isStorageError(filesError.cause) &&
+        filesError.message === filesError.cause.message) {
+        return sanitizedStorageError(filesError.cause);
     }
     let code;
     if (filesError.timedOut) {
@@ -156,9 +457,8 @@ export function mapFilesSdkError(error) {
                 break;
         }
     }
-    return new StorageError(filesError.message, {
+    return new StorageError(PUBLIC_PROVIDER_ERROR_MESSAGES[code], {
         aborted: filesError.aborted,
-        cause: filesError.cause ?? error,
         code,
         permanent: filesError.permanent,
         timedOut: filesError.timedOut,
@@ -366,10 +666,34 @@ function signedUploadOptions(options) {
         ...(options.minSize !== undefined && { minSize: options.minSize }),
     };
 }
-function metadataOf(file) {
+function providerEtag(value, key, operation) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const etag = normalizeProviderStorageEtag(value);
+    if (etag === undefined) {
+        throw new StorageError('Storage adapter returned an invalid ETag.', {
+            code: StorageErrorCode.PROVIDER,
+            key,
+            operation,
+            permanent: true,
+        });
+    }
+    return etag;
+}
+function invalidConditionalEtag(label, key, operation) {
+    return new StorageError(`${label} must be a canonical storage ETag.`, {
+        code: StorageErrorCode.INVALID_ARGUMENT,
+        key,
+        operation,
+        permanent: true,
+    });
+}
+function metadataOf(file, operation) {
+    const etag = providerEtag(file.etag, file.key, operation);
     return {
         contentType: file.type,
-        ...(file.etag !== undefined && { etag: file.etag }),
+        ...(etag !== undefined && { etag }),
         key: file.key,
         ...(file.lastModified !== undefined && {
             lastModified: new Date(file.lastModified),
@@ -382,9 +706,10 @@ function metadataOf(file) {
     };
 }
 function uploadResultOf(result) {
+    const etag = providerEtag(result.etag, result.key, 'upload');
     return {
         contentType: result.contentType,
-        ...(result.etag !== undefined && { etag: result.etag }),
+        ...(etag !== undefined && { etag }),
         key: result.key,
         ...(result.lastModified !== undefined && {
             lastModified: new Date(result.lastModified),
@@ -392,11 +717,171 @@ function uploadResultOf(result) {
         size: result.size,
     };
 }
+function normalizeFilesSdkPrefix(prefix) {
+    if (prefix === undefined)
+        return '';
+    if (typeof prefix !== 'string') {
+        throw new StorageError('prefix must be a string.', {
+            code: StorageErrorCode.INVALID_ARGUMENT,
+            permanent: true,
+        });
+    }
+    const normalized = prefix.replaceAll(/^\/+|(?<!\/)\/+$/gu, '');
+    if (normalized.length === 0 || normalized.includes('\0')) {
+        throw new StorageError('prefix must be a non-empty string without null bytes.', {
+            code: StorageErrorCode.INVALID_ARGUMENT,
+            permanent: true,
+        });
+    }
+    if (normalized.split('/').some((segment) => segment === '.' || segment === '..')) {
+        throw new StorageError('prefix must not contain . or .. path segments.', {
+            code: StorageErrorCode.INVALID_ARGUMENT,
+            permanent: true,
+        });
+    }
+    return normalized;
+}
+function physicalPluginKey(prefix, key) {
+    if (typeof key !== 'string' || key.length === 0) {
+        throw new StorageError('The final plugin key must be a non-empty string.', {
+            code: StorageErrorCode.INVALID_ARGUMENT,
+            permanent: true,
+        });
+    }
+    if (key.includes('\0')) {
+        throw new StorageError('The final plugin key must not contain null bytes.', {
+            code: StorageErrorCode.INVALID_ARGUMENT,
+            key,
+            permanent: true,
+        });
+    }
+    const normalized = key.replace(/^\/+/u, '');
+    if (normalized.split('/').some((segment) => segment === '.' || segment === '..')) {
+        throw new StorageError('The final plugin key must not contain . or .. path segments.', {
+            code: StorageErrorCode.INVALID_ARGUMENT,
+            key,
+            permanent: true,
+        });
+    }
+    return {
+        logicalKey: key,
+        physicalKey: prefix.length === 0 ? key : `${prefix}/${normalized}`,
+    };
+}
+function assertPhysicalPluginBudget(physicalKey, maxBytes, logicalKey) {
+    if (maxBytes === undefined ||
+        new TextEncoder().encode(physicalKey).byteLength <= maxBytes) {
+        return;
+    }
+    throw new StorageError(`The combined storage prefix and key exceed the provider's ${maxBytes}-byte physical-key limit.`, {
+        code: StorageErrorCode.LIMIT_EXCEEDED,
+        ...(logicalKey !== undefined && { key: logicalKey }),
+        permanent: true,
+    });
+}
+function physicalKeyGuardPlugin(prefix, maxBytes) {
+    const assertKey = (key) => {
+        const resolved = physicalPluginKey(prefix, key);
+        assertPhysicalPluginBudget(resolved.physicalKey, maxBytes, resolved.logicalKey);
+        return resolved.logicalKey;
+    };
+    const assertListOptions = (options) => {
+        if (options !== undefined &&
+            (typeof options !== 'object' || options === null)) {
+            throw new StorageError('The final plugin list options must be an object.', {
+                code: StorageErrorCode.INVALID_ARGUMENT,
+                permanent: true,
+            });
+        }
+        const listPrefix = options
+            ?.prefix;
+        if (listPrefix === undefined || listPrefix === '') {
+            if (prefix.length > 0) {
+                assertPhysicalPluginBudget(`${prefix}/`, maxBytes);
+            }
+            return options === undefined
+                ? undefined
+                : (() => {
+                    const { prefix: _prefix, ...rest } = options;
+                    return Object.freeze({
+                        ...rest,
+                        ...(listPrefix === '' && { prefix: listPrefix }),
+                    });
+                })();
+        }
+        if (typeof listPrefix !== 'string') {
+            throw new StorageError('The final plugin list prefix must be a string.', {
+                code: StorageErrorCode.INVALID_ARGUMENT,
+                permanent: true,
+            });
+        }
+        const resolved = physicalPluginKey(prefix, listPrefix);
+        assertPhysicalPluginBudget(resolved.physicalKey, maxBytes, resolved.logicalKey);
+        return Object.freeze({
+            ...options,
+            prefix: resolved.logicalKey,
+        });
+    };
+    return {
+        name: '@nestm/storage/physical-key-guard',
+        wrap: handlers({
+            copy: (operation, next) => {
+                const from = assertKey(operation.from);
+                const to = assertKey(operation.to);
+                return next(Object.freeze({ ...operation, from, to }));
+            },
+            delete: (operation, next) => {
+                const key = assertKey(operation.key);
+                return next(Object.freeze({ ...operation, key }));
+            },
+            download: (operation, next) => {
+                const key = assertKey(operation.key);
+                return next(Object.freeze({ ...operation, key }));
+            },
+            exists: (operation, next) => {
+                const key = assertKey(operation.key);
+                return next(Object.freeze({ ...operation, key }));
+            },
+            head: (operation, next) => {
+                const key = assertKey(operation.key);
+                return next(Object.freeze({ ...operation, key }));
+            },
+            list: (operation, next) => {
+                const options = assertListOptions(operation.options);
+                return next(Object.freeze({
+                    ...operation,
+                    ...(options !== undefined && { options }),
+                }));
+            },
+            move: (operation, next) => {
+                const from = assertKey(operation.from);
+                const to = assertKey(operation.to);
+                return next(Object.freeze({ ...operation, from, to }));
+            },
+            signedUploadUrl: (operation, next) => {
+                const key = assertKey(operation.key);
+                return next(Object.freeze({ ...operation, key }));
+            },
+            upload: (operation, next) => {
+                const key = assertKey(operation.key);
+                return next(Object.freeze({ ...operation, key }));
+            },
+            url: (operation, next) => {
+                const key = assertKey(operation.key);
+                return next(Object.freeze({ ...operation, key }));
+            },
+        }),
+    };
+}
 export class FilesSdkStorageDriver {
     #files;
     #name;
     #conditionalCopy;
-    #conditionalMutation;
+    #conditionalDelete;
+    #conditionalRead;
+    #conditionalUpload;
+    #conditionalOperationsBlockedByFilesPolicy;
+    #physicalKey;
     #prefix;
     #readOnly;
     #retries;
@@ -405,17 +890,91 @@ export class FilesSdkStorageDriver {
     #signedUploadPolicy;
     #signedDownloadPolicy;
     constructor(options) {
-        this.#files = new Files(options);
-        this.#name = options.adapter.name;
-        this.#conditionalCopy = conditionalCopyAdapterOf(options.adapter);
-        this.#conditionalMutation = conditionalMutationAdapterOf(options.adapter);
+        const raw = adapterRawObject(options.adapter);
+        const rawProvenance = raw === undefined ? undefined : s3AdapterProvenanceOfRaw(raw);
+        const authorityToken = s3AdapterAuthorityTokenOf(options.adapter);
+        const authorityState = typeof authorityToken === 'object'
+            ? s3AuthorityState.get(authorityToken)
+            : undefined;
+        const authorityInvalid = authorityToken === conflictingS3Authority ||
+            (authorityState !== undefined &&
+                (authorityState.record === undefined ||
+                    raw === undefined ||
+                    (raw !== authorityState.raw &&
+                        rawProvenance !== authorityState.record)));
+        const s3Provenance = authorityState?.record ?? rawProvenance;
+        if (authorityInvalid ||
+            (s3Provenance === undefined &&
+                raw !== undefined &&
+                (isUndecoratedS3Raw(raw) || isStructuralS3Raw(raw)))) {
+            throw new StorageError('Raw S3 adapters must be configured with withS3Capabilities() or createS3StorageDriver().', {
+                code: StorageErrorCode.INVALID_ARGUMENT,
+                permanent: true,
+            });
+        }
+        const mismatchedAuthority = s3Provenance === undefined
+            ? undefined
+            : mismatchedS3Authority(options.adapter, s3Provenance.surface);
+        if (mismatchedAuthority !== undefined) {
+            throw new StorageError(`S3 adapter authority "${mismatchedAuthority}" does not match its verified provider profile.`, {
+                code: StorageErrorCode.INVALID_ARGUMENT,
+                permanent: true,
+            });
+        }
+        const adapterForFiles = s3Provenance === undefined
+            ? options.adapter
+            : Object.freeze({ ...options.adapter });
+        const copiedAuthorityMismatch = s3Provenance === undefined
+            ? undefined
+            : mismatchedS3Authority(adapterForFiles, s3Provenance.surface);
+        if (copiedAuthorityMismatch !== undefined) {
+            throw new StorageError(`S3 adapter authority "${copiedAuthorityMismatch}" changed while it was being bound.`, {
+                code: StorageErrorCode.INVALID_ARGUMENT,
+                permanent: true,
+            });
+        }
+        const readOnly = options.readonly === true || s3Provenance?.provenance === 'unverified';
+        // Evaluate caller policy before appending NestM's internal key guard below.
+        this.#conditionalOperationsBlockedByFilesPolicy =
+            hasCallerFilesOperationPolicy(options);
+        // Files retains the hooks object by reference. Snapshot it so an initially
+        // inactive object cannot be mutated after this compatibility decision and
+        // start observing only ordinary operations.
+        const hooks = options.hooks === undefined
+            ? undefined
+            : Object.freeze({ ...options.hooks });
+        this.#physicalKey = physicalKeyAdapterOf(adapterForFiles);
+        const guardedPrefix = normalizeFilesSdkPrefix(options.prefix);
+        const plugins = [
+            ...(options.plugins ?? []),
+            physicalKeyGuardPlugin(guardedPrefix, this.#physicalKey?.physicalKey.maxBytes),
+        ];
+        this.#files = new Files({
+            ...options,
+            adapter: adapterForFiles,
+            ...(hooks !== undefined && { hooks }),
+            plugins,
+            readonly: readOnly,
+        });
+        this.#name = adapterForFiles.name;
+        this.#conditionalCopy = conditionalCopyAdapterOf(adapterForFiles);
+        this.#conditionalDelete = conditionalDeleteAdapterOf(adapterForFiles);
+        this.#conditionalRead = conditionalReadAdapterOf(adapterForFiles);
+        this.#conditionalUpload = conditionalUploadAdapterOf(adapterForFiles);
         this.#prefix = this.#files.prefix;
-        this.#readOnly = options.readonly === true;
+        if (guardedPrefix !== this.#prefix) {
+            throw new StorageError('Storage prefix normalization was inconsistent.', {
+                code: StorageErrorCode.INVALID_ARGUMENT,
+                permanent: true,
+            });
+        }
+        this.#assertPhysicalKeyBudget(this.#prefix);
+        this.#readOnly = readOnly;
         this.#retries = storageRetryOptions(options.retries);
         this.#signal = options.signal;
         this.#timeout = options.timeout;
-        this.#signedUploadPolicy = signedUploadPolicyAdapterOf(options.adapter);
-        this.#signedDownloadPolicy = signedDownloadPolicyAdapterOf(options.adapter);
+        this.#signedUploadPolicy = signedUploadPolicyAdapterOf(adapterForFiles);
+        this.#signedDownloadPolicy = signedDownloadPolicyAdapterOf(adapterForFiles);
     }
     get name() {
         return this.#name;
@@ -427,34 +986,85 @@ export class FilesSdkStorageDriver {
             delimiter: capabilities.delimiter,
             metadata: capabilities.metadata,
             rangeRead: capabilities.rangeRead,
-            resumableUpload: capabilities.multipart,
-            serverSideCopy: capabilities.serverSideCopy,
-            ...(this.#conditionalCopy !== undefined && {
-                conditionalCopy: { ...this.#conditionalCopy.conditionalCopy },
+            resumableUpload: !this.#readOnly && capabilities.multipart,
+            serverSideCopy: !this.#readOnly && capabilities.serverSideCopy,
+            ...(!this.#conditionalOperationsBlockedByFilesPolicy &&
+                this.#conditionalCopy !== undefined &&
+                !this.#readOnly && {
+                ...(this.#conditionalCopy.conditionalCopySource !== undefined && {
+                    conditionalCopySource: {
+                        ...this.#conditionalCopy.conditionalCopySource,
+                    },
+                }),
+                ...(this.#conditionalCopy.conditionalCopyDestination !==
+                    undefined && {
+                    conditionalCopyDestination: {
+                        ...this.#conditionalCopy.conditionalCopyDestination,
+                    },
+                }),
             }),
-            ...(this.#conditionalMutation !== undefined &&
+            ...(!this.#conditionalOperationsBlockedByFilesPolicy &&
+                this.#conditionalDelete !== undefined &&
                 !this.#readOnly && {
-                conditionalMutation: {
-                    ...this.#conditionalMutation.conditionalMutation,
+                conditionalDelete: {
+                    ...this.#conditionalDelete.conditionalDelete,
                 },
             }),
+            ...(!this.#conditionalOperationsBlockedByFilesPolicy &&
+                this.#conditionalRead !== undefined && {
+                conditionalRead: { ...this.#conditionalRead.conditionalRead },
+            }),
+            ...(!this.#conditionalOperationsBlockedByFilesPolicy &&
+                this.#conditionalUpload !== undefined &&
+                !this.#readOnly && {
+                ...(this.#conditionalUpload.conditionalCreate !== undefined && {
+                    conditionalCreate: {
+                        ...this.#conditionalUpload.conditionalCreate,
+                    },
+                }),
+                ...(this.#conditionalUpload.conditionalReplace !== undefined && {
+                    conditionalReplace: {
+                        ...this.#conditionalUpload.conditionalReplace,
+                    },
+                }),
+                ...(this.#conditionalUpload.conditionalMultipartCompletion !==
+                    undefined && {
+                    conditionalMultipartCompletion: {
+                        ...this.#conditionalUpload.conditionalMultipartCompletion,
+                    },
+                }),
+            }),
+            ...(this.#physicalKey !== undefined && {
+                physicalKey: { ...this.#physicalKey.physicalKey },
+            }),
             signedDownload: { ...capabilities.signedUrl },
             ...(this.#signedDownloadPolicy !== undefined && {
                 signedDownloadPolicy: {
                     ...this.#signedDownloadPolicy.signedDownloadPolicy,
                 },
             }),
-            signedUpload: 'runtime',
-            ...(this.#signedUploadPolicy !== undefined && {
-                signedUploadPolicy: { ...this.#signedUploadPolicy.signedUploadPolicy },
+            signedUpload: this.#readOnly ? false : 'runtime',
+            ...(this.#signedUploadPolicy !== undefined &&
+                !this.#readOnly && {
+                signedUploadPolicy: {
+                    ...this.#signedUploadPolicy.signedUploadPolicy,
+                },
             }),
-            nativeUploadProgress: capabilities.uploadProgress,
+            nativeUploadProgress: !this.#readOnly && capabilities.uploadProgress,
         };
     }
     async upload(key, body, options) {
+        this.#assertLogicalKey(key);
         return this.#call(async () => uploadResultOf(await this.#files.upload(key, mapBody(body), uploadOptions(options))));
     }
     uploadConditional(key, body, options) {
+        if (options.condition.type === 'replace' &&
+            !isCanonicalStorageEtag(options.condition.etag)) {
+            return Promise.reject(invalidConditionalEtag('condition.etag', key, 'upload'));
+        }
+        if (this.#conditionalOperationsBlockedByFilesPolicy) {
+            return Promise.reject(this.#conditionalFilesPolicyError(key, 'upload'));
+        }
         if (this.#readOnly) {
             return Promise.reject(new StorageError(`Cannot call uploadConditional() on a read-only storage adapter.`, {
                 code: StorageErrorCode.READ_ONLY,
@@ -463,8 +1073,18 @@ export class FilesSdkStorageDriver {
                 permanent: true,
             }));
         }
-        const adapter = this.#conditionalMutation;
-        if (adapter === undefined) {
+        const adapter = this.#conditionalUpload;
+        const capability = options.condition.type === 'create'
+            ? adapter?.conditionalCreate
+            : adapter?.conditionalReplace;
+        const multipartRequested = options.multipart !== undefined && options.multipart !== false;
+        const multipartSupported = !multipartRequested ||
+            (options.condition.type === 'create'
+                ? adapter?.conditionalMultipartCompletion?.create === true
+                : adapter?.conditionalMultipartCompletion?.replace === true);
+        if (adapter === undefined ||
+            capability === undefined ||
+            !multipartSupported) {
             return Promise.reject(new StorageError(`Storage adapter "${this.#name}" does not support conditional upload.`, {
                 code: StorageErrorCode.NOT_SUPPORTED,
                 key,
@@ -484,30 +1104,94 @@ export class FilesSdkStorageDriver {
                     permanent: true,
                 });
             }
-            return { ...result, key };
+            const etag = providerEtag(result.etag, key, 'upload');
+            return {
+                ...result,
+                ...(etag === undefined ? {} : { etag }),
+                key,
+            };
         });
     }
     async download(key, options) {
+        this.#assertLogicalKey(key);
         return this.#call(async () => {
             const file = await this.#files.download(key, downloadOptions(options));
             return {
-                ...metadataOf(file),
+                ...metadataOf(file, 'download'),
                 body: normalizeDownloadStream(file.stream()),
             };
         });
     }
+    downloadConditional(key, options) {
+        if (options.condition.etag !== undefined &&
+            !isCanonicalStorageEtag(options.condition.etag)) {
+            return Promise.reject(invalidConditionalEtag('condition.etag', key, 'download'));
+        }
+        if (this.#conditionalOperationsBlockedByFilesPolicy) {
+            return Promise.reject(this.#conditionalFilesPolicyError(key, 'download'));
+        }
+        const adapter = this.#conditionalRead;
+        if (adapter === undefined ||
+            (options.condition.etag !== undefined && !adapter.conditionalRead.etag) ||
+            (options.condition.version !== undefined &&
+                !adapter.conditionalRead.version)) {
+            return Promise.reject(new StorageError(`Storage adapter "${this.#name}" does not support conditional read.`, {
+                code: StorageErrorCode.NOT_SUPPORTED,
+                key,
+                operation: 'download',
+                permanent: true,
+            }));
+        }
+        return this.#call(async () => {
+            const physicalKey = this.#path(key);
+            const object = await adapter.downloadConditional(physicalKey, this.#conditionalOptions(options));
+            if (object.key !== physicalKey) {
+                await object.body.cancel().catch(() => undefined);
+                throw new StorageError('Storage adapter returned an unexpected conditional download key.', {
+                    code: StorageErrorCode.PROVIDER,
+                    key,
+                    operation: 'download',
+                    permanent: true,
+                });
+            }
+            let etag;
+            try {
+                etag = providerEtag(object.etag, key, 'download');
+            }
+            catch (error) {
+                await object.body.cancel(error).catch(() => undefined);
+                throw error;
+            }
+            return {
+                ...object,
+                body: normalizeDownloadStream(object.body),
+                ...(etag === undefined ? {} : { etag }),
+                key,
+                name: key.split('/').at(-1) ?? key,
+            };
+        });
+    }
     async head(key, options) {
-        return this.#call(async () => metadataOf(await this.#files.head(key, operationOptions(options))));
+        this.#assertLogicalKey(key);
+        return this.#call(async () => metadataOf(await this.#files.head(key, operationOptions(options)), 'head'));
     }
     exists(key, options) {
+        this.#assertLogicalKey(key);
         return this.#call(() => this.#files.exists(key, operationOptions(options)));
     }
     delete(key, options) {
+        this.#assertLogicalKey(key);
         return this.#call(async () => {
             await this.#files.delete(key, operationOptions(options));
         });
     }
     deleteConditional(key, options) {
+        if (!isCanonicalStorageEtag(options.condition.etag)) {
+            return Promise.reject(invalidConditionalEtag('condition.etag', key, 'delete'));
+        }
+        if (this.#conditionalOperationsBlockedByFilesPolicy) {
+            return Promise.reject(this.#conditionalFilesPolicyError(key, 'delete'));
+        }
         if (this.#readOnly) {
             return Promise.reject(new StorageError(`Cannot call deleteConditional() on a read-only storage adapter.`, {
                 code: StorageErrorCode.READ_ONLY,
@@ -516,8 +1200,8 @@ export class FilesSdkStorageDriver {
                 permanent: true,
             }));
         }
-        const adapter = this.#conditionalMutation;
-        if (adapter === undefined) {
+        const adapter = this.#conditionalDelete;
+        if (adapter === undefined || !adapter.conditionalDelete.etag) {
             return Promise.reject(new StorageError(`Storage adapter "${this.#name}" does not support conditional delete.`, {
                 code: StorageErrorCode.NOT_SUPPORTED,
                 key,
@@ -529,14 +1213,61 @@ export class FilesSdkStorageDriver {
         return this.#call(() => adapter.deleteConditional(this.#path(key), mergedOptions));
     }
     copy(sourceKey, destinationKey, options) {
+        this.#assertLogicalKey(sourceKey);
+        this.#assertLogicalKey(destinationKey);
         return this.#call(() => this.#files.copy(sourceKey, destinationKey, operationOptions(options)));
     }
     move(sourceKey, destinationKey, options) {
+        this.#assertLogicalKey(sourceKey);
+        this.#assertLogicalKey(destinationKey);
         return this.#call(() => this.#files.move(sourceKey, destinationKey, operationOptions(options)));
     }
     promote(sourceKey, destinationKey, options) {
+        const destination = options.destination;
+        if (destination !== undefined &&
+            (typeof destination !== 'object' ||
+                destination === null ||
+                (destination.type !== 'create' && destination.type !== 'replace'))) {
+            return Promise.reject(new StorageError('destination.type must be "create" or "replace".', {
+                code: StorageErrorCode.INVALID_ARGUMENT,
+                key: destinationKey,
+                operation: 'promote',
+                permanent: true,
+            }));
+        }
+        if (options.sourceEtag !== undefined &&
+            !isCanonicalStorageEtag(options.sourceEtag)) {
+            return Promise.reject(invalidConditionalEtag('sourceEtag', sourceKey, 'promote'));
+        }
+        if (destination?.type === 'replace' &&
+            !isCanonicalStorageEtag(destination.etag)) {
+            return Promise.reject(invalidConditionalEtag('destination.etag', destinationKey, 'promote'));
+        }
+        if (this.#conditionalOperationsBlockedByFilesPolicy) {
+            return Promise.reject(this.#conditionalFilesPolicyError(sourceKey, 'promote'));
+        }
+        if (this.#readOnly) {
+            return Promise.reject(new StorageError(`Cannot call promote() on a read-only storage adapter.`, {
+                code: StorageErrorCode.READ_ONLY,
+                key: sourceKey,
+                operation: 'promote',
+                permanent: true,
+            }));
+        }
         const adapter = this.#conditionalCopy;
-        if (adapter === undefined || !adapter.conditionalCopy.supported) {
+        if (adapter === undefined ||
+            (options.sourceEtag !== undefined &&
+                adapter.conditionalCopySource?.etag !== true) ||
+            (options.sourceVersion !== undefined &&
+                adapter.conditionalCopySource?.version !== true) ||
+            (options.destination?.type === 'create' &&
+                adapter.conditionalCopyDestination?.create !== true) ||
+            (options.destination?.type === 'replace' &&
+                adapter.conditionalCopyDestination?.replace !== true) ||
+            (options.destination !== undefined &&
+                (options.sourceEtag !== undefined ||
+                    options.sourceVersion !== undefined) &&
+                adapter.conditionalCopyDestination?.atomicWithSource !== true)) {
             return Promise.reject(new StorageError(`Storage adapter "${this.#name}" does not support conditional promotion.`, {
                 code: StorageErrorCode.NOT_SUPPORTED,
                 key: sourceKey,
@@ -544,13 +1275,14 @@ export class FilesSdkStorageDriver {
                 permanent: true,
             }));
         }
-        return this.#call(() => adapter.promote(sourceKey, destinationKey, options));
+        return this.#call(() => adapter.promote(this.#path(sourceKey), this.#path(destinationKey), this.#conditionalOptions(options)));
     }
     async list(options) {
+        this.#assertListPhysicalPrefix(options?.prefix);
         return this.#call(async () => {
             const result = await this.#files.list(listOptions(options));
             return {
-                items: result.items.map(metadataOf),
+                items: result.items.map((file) => metadataOf(file, 'list')),
                 ...(result.cursor !== undefined && { cursor: result.cursor }),
                 ...(result.prefixes !== undefined && {
                     prefixes: [...result.prefixes],
@@ -564,7 +1296,7 @@ export class FilesSdkStorageDriver {
     async *#search(pattern, options) {
         try {
             for await (const file of this.#files.search(pattern, searchOptions(options))) {
-                yield metadataOf(file);
+                yield metadataOf(file, 'search');
             }
         }
         catch (error) {
@@ -572,9 +1304,11 @@ export class FilesSdkStorageDriver {
         }
     }
     signDownload(key, options) {
+        this.#assertLogicalKey(key);
         return this.#call(() => this.#files.url(key, signedDownloadOptions(options)));
     }
     signUpload(key, options) {
+        this.#assertLogicalKey(key);
         return this.#call(() => this.#files.signedUploadUrl(key, signedUploadOptions(options)));
     }
     async #call(operation) {
@@ -599,9 +1333,6 @@ export class FilesSdkStorageDriver {
                 permanent: true,
             });
         }
-        if (this.#prefix.length === 0) {
-            return key;
-        }
         const normalized = key.replace(/^\/+/u, '');
         if (normalized
             .split('/')
@@ -612,7 +1343,44 @@ export class FilesSdkStorageDriver {
                 permanent: true,
             });
         }
-        return `${this.#prefix}/${normalized}`;
+        const physicalKey = this.#prefix.length === 0 ? key : `${this.#prefix}/${normalized}`;
+        this.#assertPhysicalKeyBudget(physicalKey, key);
+        return physicalKey;
+    }
+    #assertLogicalKey(key) {
+        this.#path(key);
+    }
+    #assertListPhysicalPrefix(prefix) {
+        if (prefix !== undefined && prefix.length > 0) {
+            this.#assertLogicalKey(prefix);
+            return;
+        }
+        if (this.#prefix.length > 0) {
+            this.#assertPhysicalKeyBudget(`${this.#prefix}/`);
+        }
+    }
+    #physicalKeyExceedsBudget(physicalKey) {
+        const maxBytes = this.#physicalKey?.physicalKey.maxBytes;
+        return (maxBytes !== undefined &&
+            new TextEncoder().encode(physicalKey).byteLength > maxBytes);
+    }
+    #assertPhysicalKeyBudget(physicalKey, logicalKey) {
+        const maxBytes = this.#physicalKey?.physicalKey.maxBytes;
+        if (maxBytes === undefined || !this.#physicalKeyExceedsBudget(physicalKey))
+            return;
+        throw new StorageError(`The combined storage prefix and key exceed the provider's ${maxBytes}-byte physical-key limit.`, {
+            code: StorageErrorCode.LIMIT_EXCEEDED,
+            ...(logicalKey !== undefined && { key: logicalKey }),
+            permanent: true,
+        });
+    }
+    #conditionalFilesPolicyError(key, operation) {
+        return new StorageError('Conditional storage operations are unavailable while Files SDK plugins, hooks, or receipts are configured.', {
+            code: StorageErrorCode.NOT_SUPPORTED,
+            key,
+            operation,
+            permanent: true,
+        });
     }
     #conditionalOptions(options) {
         return {