@nestm/storage 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/files-sdk/s3/index.js

@@ -1,6 +1,315 @@
-import { CopyObjectCommand } from '@aws-sdk/client-s3';
-import { mapS3Error, s3, } from 'files-sdk/s3';
-import { createFilesSdkDriver, mapFilesSdkError, } from '../files-sdk.driver.js';
+import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CopyObjectCommand, CreateMultipartUploadCommand, DeleteObjectCommand, GetObjectCommand, PutObjectCommand, UploadPartCommand, } from '@aws-sdk/client-s3';
+import { createPresignedPost, } from '@aws-sdk/s3-presigned-post';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { Readable } from 'node:stream';
+import { mapS3Error, s3 as createFilesSdkS3Adapter, } from 'files-sdk/s3';
+import { StorageError, StorageErrorCode, isStorageError, } from '../../storage.error.js';
+import { normalizeProviderStorageEtag, storageEtagHeader, } from '../../storage-etag.js';
+import { assertFilesSdkS3AdapterHasNoReservedExtensions, createFilesSdkDriver, markFilesSdkS3AdapterUndecorated, markFilesSdkS3RawClientProvenance, mapFilesSdkError, } from '../files-sdk.driver.js';
+import { getS3ConstructionMetadata, recordS3ConstructionMetadata, } from './construction-metadata.js';
+const verifiedS3ProviderProfile = Symbol('verifiedS3ProviderProfile');
+const verifiedS3ProviderProfiles = new WeakSet();
+function assertCapabilityBoolean(value, label) {
+    if (typeof value !== 'boolean') {
+        throw new TypeError(`${label} must be a boolean.`);
+    }
+}
+/** Validates and deeply freezes an explicitly verified S3-compatible profile. */
+export function defineS3ProviderProfile(profile) {
+    if (typeof profile.name !== 'string' || profile.name.trim().length === 0) {
+        throw new TypeError('S3 provider profile name must be a non-empty string.');
+    }
+    if (!Number.isSafeInteger(profile.physicalKey.maxBytes) ||
+        profile.physicalKey.maxBytes <= 0) {
+        throw new TypeError('S3 provider profile physicalKey.maxBytes must be a positive safe integer.');
+    }
+    const booleanFields = [
+        [
+            profile.signedUploadPolicy !== undefined,
+            'signedUploadPolicy.contentType',
+            profile.signedUploadPolicy?.contentType,
+        ],
+        [
+            profile.signedUploadPolicy !== undefined,
+            'signedUploadPolicy.sizeRange',
+            profile.signedUploadPolicy?.sizeRange,
+        ],
+        [
+            profile.conditionalCreate !== undefined,
+            'conditionalCreate.resultEtag',
+            profile.conditionalCreate?.resultEtag,
+        ],
+        [
+            profile.conditionalReplace !== undefined,
+            'conditionalReplace.resultEtag',
+            profile.conditionalReplace?.resultEtag,
+        ],
+        [
+            profile.conditionalDelete !== undefined,
+            'conditionalDelete.etag',
+            profile.conditionalDelete?.etag,
+        ],
+        [
+            profile.conditionalRead !== undefined,
+            'conditionalRead.etag',
+            profile.conditionalRead?.etag,
+        ],
+        [
+            profile.conditionalRead !== undefined,
+            'conditionalRead.version',
+            profile.conditionalRead?.version,
+        ],
+        [
+            profile.conditionalCopySource !== undefined,
+            'conditionalCopySource.etag',
+            profile.conditionalCopySource?.etag,
+        ],
+        [
+            profile.conditionalCopySource !== undefined,
+            'conditionalCopySource.version',
+            profile.conditionalCopySource?.version,
+        ],
+        [
+            profile.conditionalCopyDestination !== undefined,
+            'conditionalCopyDestination.create',
+            profile.conditionalCopyDestination?.create,
+        ],
+        [
+            profile.conditionalCopyDestination !== undefined,
+            'conditionalCopyDestination.replace',
+            profile.conditionalCopyDestination?.replace,
+        ],
+        [
+            profile.conditionalCopyDestination !== undefined,
+            'conditionalCopyDestination.atomicWithSource',
+            profile.conditionalCopyDestination?.atomicWithSource,
+        ],
+        [
+            profile.conditionalMultipartCompletion !== undefined,
+            'conditionalMultipartCompletion.create',
+            profile.conditionalMultipartCompletion?.create,
+        ],
+        [
+            profile.conditionalMultipartCompletion !== undefined,
+            'conditionalMultipartCompletion.replace',
+            profile.conditionalMultipartCompletion?.replace,
+        ],
+    ];
+    for (const [declared, label, value] of booleanFields) {
+        if (declared)
+            assertCapabilityBoolean(value, label);
+    }
+    if (profile.conditionalCopyDestination?.atomicWithSource === true &&
+        profile.conditionalCopySource?.etag !== true &&
+        profile.conditionalCopySource?.version !== true) {
+        throw new TypeError('An atomic destination-copy profile must enable at least one source-copy condition.');
+    }
+    if (profile.conditionalCopyDestination?.atomicWithSource === true &&
+        profile.conditionalCopyDestination.create !== true &&
+        profile.conditionalCopyDestination.replace !== true) {
+        throw new TypeError('An atomic destination-copy profile must declare create or replace support.');
+    }
+    if (profile.conditionalMultipartCompletion?.create === true &&
+        profile.conditionalCreate === undefined) {
+        throw new TypeError('Conditional multipart create requires conditional create support.');
+    }
+    if (profile.conditionalMultipartCompletion?.replace === true &&
+        profile.conditionalReplace === undefined) {
+        throw new TypeError('Conditional multipart replace requires conditional replace support.');
+    }
+    const clone = {
+        name: profile.name.trim(),
+        physicalKey: Object.freeze({ ...profile.physicalKey }),
+        signedUploadPolicy: Object.freeze(profile.signedUploadPolicy === undefined
+            ? { contentType: false, sizeRange: false }
+            : { ...profile.signedUploadPolicy }),
+        ...(profile.conditionalCreate !== undefined && {
+            conditionalCreate: Object.freeze({ ...profile.conditionalCreate }),
+        }),
+        ...(profile.conditionalReplace !== undefined && {
+            conditionalReplace: Object.freeze({ ...profile.conditionalReplace }),
+        }),
+        ...(profile.conditionalDelete !== undefined && {
+            conditionalDelete: Object.freeze({ ...profile.conditionalDelete }),
+        }),
+        ...(profile.conditionalRead !== undefined && {
+            conditionalRead: Object.freeze({ ...profile.conditionalRead }),
+        }),
+        ...(profile.conditionalCopySource !== undefined && {
+            conditionalCopySource: Object.freeze({
+                ...profile.conditionalCopySource,
+            }),
+        }),
+        ...(profile.conditionalCopyDestination !== undefined && {
+            conditionalCopyDestination: Object.freeze({
+                ...profile.conditionalCopyDestination,
+            }),
+        }),
+        ...(profile.conditionalMultipartCompletion !== undefined && {
+            conditionalMultipartCompletion: Object.freeze({
+                ...profile.conditionalMultipartCompletion,
+            }),
+        }),
+    };
+    Object.defineProperty(clone, verifiedS3ProviderProfile, {
+        configurable: false,
+        enumerable: false,
+        value: true,
+        writable: false,
+    });
+    const verified = Object.freeze(clone);
+    verifiedS3ProviderProfiles.add(verified);
+    return verified;
+}
+function assertVerifiedS3ProviderProfile(profile) {
+    if (typeof profile !== 'object' ||
+        profile === null ||
+        !verifiedS3ProviderProfiles.has(profile)) {
+        throw new TypeError('providerProfile must be created with defineS3ProviderProfile().');
+    }
+}
+function assertS3ProviderProfileContainedBy(profile, ceiling) {
+    if (profile.physicalKey.maxBytes > ceiling.physicalKey.maxBytes) {
+        throw new TypeError(`S3 provider profile "${profile.name}" cannot widen ${ceiling.name} physicalKey.maxBytes beyond ${ceiling.physicalKey.maxBytes}.`);
+    }
+    const operationCapabilities = [
+        ['conditionalCreate', profile.conditionalCreate, ceiling.conditionalCreate],
+        [
+            'conditionalReplace',
+            profile.conditionalReplace,
+            ceiling.conditionalReplace,
+        ],
+        ['conditionalDelete', profile.conditionalDelete, ceiling.conditionalDelete],
+        ['conditionalRead', profile.conditionalRead, ceiling.conditionalRead],
+        [
+            'conditionalCopySource',
+            profile.conditionalCopySource,
+            ceiling.conditionalCopySource,
+        ],
+        [
+            'conditionalCopyDestination',
+            profile.conditionalCopyDestination,
+            ceiling.conditionalCopyDestination,
+        ],
+        [
+            'conditionalMultipartCompletion',
+            profile.conditionalMultipartCompletion,
+            ceiling.conditionalMultipartCompletion,
+        ],
+    ];
+    for (const [name, declared, supported] of operationCapabilities) {
+        if (declared !== undefined && supported === undefined) {
+            throw new TypeError(`S3 provider profile "${profile.name}" cannot widen ${ceiling.name} with ${name}.`);
+        }
+    }
+    const booleanClaims = [
+        [
+            'signedUploadPolicy.contentType',
+            profile.signedUploadPolicy.contentType,
+            ceiling.signedUploadPolicy.contentType,
+        ],
+        [
+            'signedUploadPolicy.sizeRange',
+            profile.signedUploadPolicy.sizeRange,
+            ceiling.signedUploadPolicy.sizeRange,
+        ],
+        [
+            'conditionalCreate.resultEtag',
+            profile.conditionalCreate?.resultEtag,
+            ceiling.conditionalCreate?.resultEtag,
+        ],
+        [
+            'conditionalReplace.resultEtag',
+            profile.conditionalReplace?.resultEtag,
+            ceiling.conditionalReplace?.resultEtag,
+        ],
+        [
+            'conditionalDelete.etag',
+            profile.conditionalDelete?.etag,
+            ceiling.conditionalDelete?.etag,
+        ],
+        [
+            'conditionalRead.etag',
+            profile.conditionalRead?.etag,
+            ceiling.conditionalRead?.etag,
+        ],
+        [
+            'conditionalRead.version',
+            profile.conditionalRead?.version,
+            ceiling.conditionalRead?.version,
+        ],
+        [
+            'conditionalCopySource.etag',
+            profile.conditionalCopySource?.etag,
+            ceiling.conditionalCopySource?.etag,
+        ],
+        [
+            'conditionalCopySource.version',
+            profile.conditionalCopySource?.version,
+            ceiling.conditionalCopySource?.version,
+        ],
+        [
+            'conditionalCopyDestination.create',
+            profile.conditionalCopyDestination?.create,
+            ceiling.conditionalCopyDestination?.create,
+        ],
+        [
+            'conditionalCopyDestination.replace',
+            profile.conditionalCopyDestination?.replace,
+            ceiling.conditionalCopyDestination?.replace,
+        ],
+        [
+            'conditionalCopyDestination.atomicWithSource',
+            profile.conditionalCopyDestination?.atomicWithSource,
+            ceiling.conditionalCopyDestination?.atomicWithSource,
+        ],
+        [
+            'conditionalMultipartCompletion.create',
+            profile.conditionalMultipartCompletion?.create,
+            ceiling.conditionalMultipartCompletion?.create,
+        ],
+        [
+            'conditionalMultipartCompletion.replace',
+            profile.conditionalMultipartCompletion?.replace,
+            ceiling.conditionalMultipartCompletion?.replace,
+        ],
+    ];
+    for (const [name, declared, supported] of booleanClaims) {
+        if (declared === true && supported !== true) {
+            throw new TypeError(`S3 provider profile "${profile.name}" cannot widen ${ceiling.name} with ${name}.`);
+        }
+    }
+}
+export const AWS_S3_PROVIDER_PROFILE = defineS3ProviderProfile({
+    name: 'aws-s3-general-purpose',
+    physicalKey: { maxBytes: 1024 },
+    signedUploadPolicy: { contentType: true, sizeRange: true },
+    conditionalCreate: { resultEtag: true },
+    conditionalReplace: { resultEtag: true },
+    conditionalDelete: { etag: true },
+    conditionalRead: { etag: true, version: true },
+    conditionalCopySource: { etag: true, version: true },
+    conditionalCopyDestination: {
+        atomicWithSource: true,
+        create: true,
+        replace: true,
+    },
+    conditionalMultipartCompletion: { create: true, replace: true },
+});
+export const CLOUDFLARE_R2_PROVIDER_PROFILE = defineS3ProviderProfile({
+    name: 'cloudflare-r2-stable',
+    physicalKey: { maxBytes: 1024 },
+    signedUploadPolicy: { contentType: true, sizeRange: false },
+    conditionalCreate: { resultEtag: true },
+    conditionalReplace: { resultEtag: true },
+    conditionalRead: { etag: true, version: false },
+    conditionalCopySource: { etag: true, version: false },
+});
+const UNVERIFIED_S3_PROVIDER_PROFILE = defineS3ProviderProfile({
+    name: 'unverified-s3-compatible',
+    physicalKey: { maxBytes: 1024 },
+    signedUploadPolicy: { contentType: false, sizeRange: false },
+});
 function copySource(bucket, key, version) {
     const source = `${encodeURIComponent(bucket)}/${encodeURIComponent(key)}`;
     return version === undefined
@@ -24,6 +333,166 @@ function maxRetries(options) {
         : options.retries?.max;
     return Math.max(0, Math.floor(configured ?? 0));
 }
+function etagHeader(etag, key, operation, label) {
+    const header = storageEtagHeader(etag);
+    if (header === undefined) {
+        throw new StorageError(`${label} must be a canonical storage ETag.`, {
+            code: StorageErrorCode.INVALID_ARGUMENT,
+            key,
+            operation,
+            permanent: true,
+        });
+    }
+    return header;
+}
+function providerEtag(etag, key, operation) {
+    if (etag === undefined) {
+        return undefined;
+    }
+    const normalized = normalizeProviderStorageEtag(etag);
+    if (normalized === undefined) {
+        throw new StorageError('S3 returned an invalid ETag.', {
+            code: StorageErrorCode.PROVIDER,
+            key,
+            operation,
+            permanent: true,
+        });
+    }
+    return normalized;
+}
+function contentTypeOf(body, override) {
+    if (override !== undefined) {
+        return override;
+    }
+    if (typeof body === 'string') {
+        return 'text/plain; charset=utf-8';
+    }
+    if (body instanceof Blob && body.type.length > 0) {
+        return body.type;
+    }
+    return 'application/octet-stream';
+}
+async function normalizeConditionalBody(body, onProgress) {
+    let bytes;
+    if (typeof body === 'string') {
+        bytes = new TextEncoder().encode(body);
+    }
+    else if (body instanceof Uint8Array) {
+        bytes = body;
+    }
+    else if (body instanceof ArrayBuffer) {
+        bytes = new Uint8Array(body);
+    }
+    else if (ArrayBuffer.isView(body)) {
+        bytes = new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    }
+    else if (body instanceof Blob) {
+        bytes = new Uint8Array(await body.arrayBuffer());
+    }
+    if (bytes !== undefined) {
+        const total = bytes.byteLength;
+        onProgress?.({ loaded: 0, total });
+        return { body: bytes, contentLength: total, size: () => total };
+    }
+    const stream = body instanceof Readable
+        ? Readable.toWeb(body)
+        : body;
+    if (!(stream instanceof ReadableStream)) {
+        throw new StorageError('Unsupported conditional upload body.', {
+            code: StorageErrorCode.INVALID_ARGUMENT,
+            operation: 'upload',
+            permanent: true,
+        });
+    }
+    const reader = stream.getReader();
+    let loaded = 0;
+    return {
+        body: new ReadableStream({
+            cancel(reason) {
+                return reader.cancel(reason);
+            },
+            async pull(controller) {
+                const result = await reader.read();
+                if (result.done) {
+                    controller.close();
+                    return;
+                }
+                loaded += result.value.byteLength;
+                controller.enqueue(result.value);
+                onProgress?.({ loaded });
+            },
+        }),
+        size: () => loaded,
+    };
+}
+function s3ErrorIdentity(error) {
+    if (typeof error !== 'object' || error === null) {
+        return { code: undefined, status: undefined };
+    }
+    const candidate = error;
+    const serviceCode = candidate.name ?? candidate.Code ?? candidate.code;
+    const status = candidate.$metadata?.httpStatusCode;
+    return {
+        code: typeof serviceCode === 'string' ? serviceCode : undefined,
+        status: typeof status === 'number' ? status : undefined,
+    };
+}
+function mapS3ConditionalError(error, operation) {
+    if (isStorageError(error)) {
+        return error;
+    }
+    const identity = s3ErrorIdentity(error);
+    const provider = mapFilesSdkError(mapS3Error(error));
+    const precondition = identity.status === 412 || identity.code === 'PreconditionFailed';
+    const conditionalConflict = identity.status === 409 || identity.code === 'ConditionalRequestConflict';
+    const notFound = identity.status === 404 ||
+        identity.code === 'NoSuchKey' ||
+        identity.code === 'NoSuchUpload' ||
+        provider.code === StorageErrorCode.NOT_FOUND;
+    const code = precondition || conditionalConflict
+        ? StorageErrorCode.CONFLICT
+        : notFound
+            ? StorageErrorCode.NOT_FOUND
+            : provider.code;
+    return new StorageError(`Conditional S3 ${operation} failed.`, {
+        aborted: provider.aborted,
+        code,
+        operation,
+        permanent: precondition || notFound
+            ? true
+            : conditionalConflict
+                ? false
+                : provider.permanent,
+        timedOut: provider.timedOut,
+    });
+}
+async function withS3Retry(options, operationName, operation) {
+    const retries = maxRetries(options);
+    for (let attempt = 0;; attempt += 1) {
+        const signal = operationSignal(options);
+        try {
+            return await operation(signal);
+        }
+        catch (error) {
+            const mapped = mapS3ConditionalError(error, operationName);
+            if (attempt >= retries ||
+                mapped.code !== StorageErrorCode.PROVIDER ||
+                mapped.aborted ||
+                mapped.permanent ||
+                signal?.aborted === true) {
+                throw mapped;
+            }
+            const delay = typeof options.retries === 'object' &&
+                options.retries.backoff !== undefined
+                ? options.retries.backoff({
+                    attempt: attempt + 1,
+                    error: mapped,
+                })
+                : Math.min(1000, 100 * 2 ** attempt);
+            await waitForRetry(delay, options.signal);
+        }
+    }
+}
 async function waitForRetry(milliseconds, signal) {
     if (signal?.aborted === true) {
         throw signal.reason;
@@ -42,78 +511,598 @@ async function waitForRetry(milliseconds, signal) {
         signal?.addEventListener('abort', abort, { once: true });
     });
 }
+const S3_MIN_MULTIPART_PART_BYTES = 5 * 1024 * 1024;
+const S3_MAX_MULTIPART_PARTS = 10_000;
+function conditionalHeaders(condition, key) {
+    return condition.type === 'create'
+        ? { IfNoneMatch: '*' }
+        : {
+            IfMatch: etagHeader(condition.etag, key, 'upload', 'condition.etag'),
+        };
+}
+function rangeHeader(range) {
+    if (range === undefined)
+        return undefined;
+    return `bytes=${range.start}-${range.end ?? ''}`;
+}
+function s3ResponseStream(body) {
+    let stream;
+    if (body instanceof ReadableStream) {
+        stream = body;
+    }
+    else if (body instanceof Readable) {
+        stream = Readable.toWeb(body);
+    }
+    else if (typeof body === 'object' &&
+        body !== null &&
+        'transformToWebStream' in body &&
+        typeof body.transformToWebStream === 'function') {
+        stream = body.transformToWebStream();
+    }
+    else {
+        throw new StorageError('Conditional S3 download returned no body stream.', {
+            code: StorageErrorCode.PROVIDER,
+            operation: 'download',
+            permanent: true,
+        });
+    }
+    const reader = stream.getReader();
+    return new ReadableStream({
+        async cancel(reason) {
+            try {
+                await reader.cancel(reason);
+            }
+            catch (error) {
+                throw mapS3ConditionalError(error, 'download');
+            }
+            finally {
+                reader.releaseLock();
+            }
+        },
+        async pull(controller) {
+            try {
+                const result = await reader.read();
+                if (result.done) {
+                    reader.releaseLock();
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(result.value);
+            }
+            catch (error) {
+                reader.releaseLock();
+                controller.error(mapS3ConditionalError(error, 'download'));
+            }
+        },
+    });
+}
+async function* multipartParts(source, partSize) {
+    if (source instanceof Uint8Array) {
+        for (let offset = 0; offset < source.byteLength; offset += partSize) {
+            yield source.subarray(offset, Math.min(offset + partSize, source.byteLength));
+        }
+        return;
+    }
+    const reader = source.getReader();
+    let buffered = new Uint8Array(0);
+    try {
+        for (;;) {
+            const result = await reader.read();
+            if (result.done)
+                break;
+            const combined = new Uint8Array(buffered.byteLength + result.value.byteLength);
+            combined.set(buffered);
+            combined.set(result.value, buffered.byteLength);
+            buffered = combined;
+            while (buffered.byteLength >= partSize) {
+                yield buffered.slice(0, partSize);
+                buffered = buffered.slice(partSize);
+            }
+        }
+        if (buffered.byteLength > 0)
+            yield buffered;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function missingResultEtag(key) {
+    return new StorageError('S3 committed a conditional upload without returning the ETag required to identify its result; reconcile the destination before retrying.', {
+        code: StorageErrorCode.PROVIDER,
+        key,
+        operation: 'upload',
+        permanent: true,
+    });
+}
+async function uploadConditionalSingle(base, key, body, conditional) {
+    const normalized = await normalizeConditionalBody(body, conditional.onProgress);
+    const contentType = contentTypeOf(body, conditional.contentType);
+    const retryOptions = normalized.contentLength === undefined
+        ? { ...conditional, retries: 0 }
+        : conditional;
+    const result = await withS3Retry(retryOptions, 'upload', (signal) => base.raw.send(new PutObjectCommand({
+        Body: normalized.body,
+        Bucket: base.bucket,
+        ...(conditional.cacheControl !== undefined && {
+            CacheControl: conditional.cacheControl,
+        }),
+        ...(normalized.contentLength !== undefined && {
+            ContentLength: normalized.contentLength,
+        }),
+        ContentType: contentType,
+        ...conditionalHeaders(conditional.condition, key),
+        Key: key,
+        ...(conditional.metadata !== undefined && {
+            Metadata: conditional.metadata,
+        }),
+    }), signal === undefined ? undefined : { abortSignal: signal }));
+    const size = normalized.size();
+    conditional.onProgress?.({
+        loaded: size,
+        ...(normalized.contentLength !== undefined && {
+            total: normalized.contentLength,
+        }),
+    });
+    const etag = providerEtag(result.ETag, key, 'upload');
+    if (etag === undefined)
+        throw missingResultEtag(key);
+    return { contentType, etag, key, size };
+}
+async function uploadConditionalMultipart(base, key, body, conditional) {
+    const configuredPartSize = typeof conditional.multipart === 'object'
+        ? conditional.multipart.partSize
+        : undefined;
+    if (configuredPartSize !== undefined &&
+        (!Number.isSafeInteger(configuredPartSize) || configuredPartSize <= 0)) {
+        throw new StorageError('multipart.partSize must be a positive safe integer.', {
+            code: StorageErrorCode.INVALID_ARGUMENT,
+            key,
+            operation: 'upload',
+            permanent: true,
+        });
+    }
+    const partSize = Math.max(S3_MIN_MULTIPART_PART_BYTES, configuredPartSize ?? S3_MIN_MULTIPART_PART_BYTES);
+    const normalized = await normalizeConditionalBody(body, undefined);
+    if (normalized.contentLength === 0) {
+        return uploadConditionalSingle(base, key, new Uint8Array(), {
+            ...conditional,
+            multipart: false,
+        });
+    }
+    const contentType = contentTypeOf(body, conditional.contentType);
+    let uploadId;
+    let size = 0;
+    try {
+        const created = await withS3Retry(conditional, 'upload', (signal) => base.raw.send(new CreateMultipartUploadCommand({
+            Bucket: base.bucket,
+            ...(conditional.cacheControl !== undefined && {
+                CacheControl: conditional.cacheControl,
+            }),
+            ContentType: contentType,
+            Key: key,
+            ...(conditional.metadata !== undefined && {
+                Metadata: conditional.metadata,
+            }),
+        }), signal === undefined ? undefined : { abortSignal: signal }));
+        uploadId = created.UploadId;
+        if (uploadId === undefined || uploadId.length === 0) {
+            throw new StorageError('S3 did not return a multipart upload ID.', {
+                code: StorageErrorCode.PROVIDER,
+                key,
+                operation: 'upload',
+                permanent: true,
+            });
+        }
+        const completedParts = [];
+        let partNumber = 0;
+        for await (const part of multipartParts(normalized.body, partSize)) {
+            partNumber += 1;
+            if (partNumber > S3_MAX_MULTIPART_PARTS) {
+                throw new StorageError(`Conditional multipart upload exceeds the ${S3_MAX_MULTIPART_PARTS}-part S3 limit.`, {
+                    code: StorageErrorCode.LIMIT_EXCEEDED,
+                    key,
+                    operation: 'upload',
+                    permanent: true,
+                });
+            }
+            const uploaded = await withS3Retry(conditional, 'upload', (signal) => base.raw.send(new UploadPartCommand({
+                Body: part,
+                Bucket: base.bucket,
+                ContentLength: part.byteLength,
+                Key: key,
+                PartNumber: partNumber,
+                UploadId: uploadId,
+            }), signal === undefined ? undefined : { abortSignal: signal }));
+            const partEtag = providerEtag(uploaded.ETag, key, 'upload');
+            if (partEtag === undefined) {
+                throw new StorageError('S3 upload part returned no ETag.', {
+                    code: StorageErrorCode.PROVIDER,
+                    key,
+                    operation: 'upload',
+                    permanent: true,
+                });
+            }
+            completedParts.push({
+                ETag: storageEtagHeader(partEtag),
+                PartNumber: partNumber,
+            });
+            size += part.byteLength;
+            conditional.onProgress?.({
+                loaded: size,
+                ...(normalized.contentLength !== undefined && {
+                    total: normalized.contentLength,
+                }),
+            });
+        }
+        if (completedParts.length === 0) {
+            await base.raw.send(new AbortMultipartUploadCommand({
+                Bucket: base.bucket,
+                Key: key,
+                UploadId: uploadId,
+            }));
+            uploadId = undefined;
+            return uploadConditionalSingle(base, key, new Uint8Array(), {
+                ...conditional,
+                multipart: false,
+            });
+        }
+        const completed = await withS3Retry(conditional, 'upload', (signal) => base.raw.send(new CompleteMultipartUploadCommand({
+            Bucket: base.bucket,
+            ...conditionalHeaders(conditional.condition, key),
+            Key: key,
+            MultipartUpload: { Parts: completedParts },
+            UploadId: uploadId,
+        }), signal === undefined ? undefined : { abortSignal: signal }));
+        const etag = providerEtag(completed.ETag, key, 'upload');
+        if (etag === undefined)
+            throw missingResultEtag(key);
+        uploadId = undefined;
+        return { contentType, etag, key, size };
+    }
+    catch (error) {
+        if (uploadId !== undefined) {
+            await base.raw
+                .send(new AbortMultipartUploadCommand({
+                Bucket: base.bucket,
+                Key: key,
+                UploadId: uploadId,
+            }))
+                .catch(() => undefined);
+        }
+        throw error;
+    }
+}
+const configuredS3Clients = new WeakSet();
+/** Constructs the upstream S3 adapter while retaining security-relevant metadata. */
+export function s3(options) {
+    const adapter = createFilesSdkS3Adapter(options);
+    markFilesSdkS3AdapterUndecorated(adapter);
+    recordS3ConstructionMetadata(adapter.raw, {
+        publicBaseUrlConfigured: options.publicBaseUrl !== undefined,
+    });
+    return adapter;
+}
 /**
- * Adds the S3-only capabilities to an adapter already built by `s3(...)`: an
- * ETag/version-conditional server-side promotion, and the signed upload and
- * download policies the bridge advertises through `capabilities`.
- *
- * Exported so the provider factory can apply them to the adapter `loadFiles`
- * resolved for the `s3` slug instead of re-deriving {@link S3AdapterOptions}
- * from flat provider config. It expects an adapter whose `raw` is an `S3Client`
- * — pass one built by `s3(...)`, not an S3-compatible wrapper.
+ * Adds only the exact operations declared by one verified provider profile.
+ * Each raw adapter may be decorated once so capability state cannot depend on
+ * profile application order. A native AWS SDK endpoint also bounds every
+ * explicit profile by the built-in AWS capability ceiling.
  */
 export function withS3Capabilities(base, options = {}) {
-    return Object.assign(base, {
-        conditionalCopy: Object.freeze({
-            etag: true,
-            supported: true,
-            version: true,
-        }),
-        signedUploadPolicy: Object.freeze({
-            contentType: true,
-            sizeRange: true,
-        }),
+    const raw = base.raw;
+    if (configuredS3Clients.has(raw)) {
+        throw new TypeError('withS3Capabilities may only be applied once to an S3 adapter.');
+    }
+    assertFilesSdkS3AdapterHasNoReservedExtensions(base);
+    const sdkHasCustomEndpoint = raw.config.isCustomEndpoint === true;
+    if (options.endpoint !== undefined && !sdkHasCustomEndpoint) {
+        throw new TypeError('The declared S3 endpoint does not match the SDK client endpoint provenance.');
+    }
+    if (!sdkHasCustomEndpoint) {
+        // files-sdk does not expose this S3Client constructor option. Endpoint
+        // resolution is lazy, so fixing the resolved SDK config before the adapter
+        // is exposed prevents environment and shared-config endpoint redirection.
+        raw.config.ignoreConfiguredEndpointUrls = true;
+    }
+    const inferredNativeAws = base.name === 's3' && !sdkHasCustomEndpoint;
+    const profile = options.providerProfile ??
+        (inferredNativeAws
+            ? AWS_S3_PROVIDER_PROFILE
+            : UNVERIFIED_S3_PROVIDER_PROFILE);
+    assertVerifiedS3ProviderProfile(profile);
+    if (!sdkHasCustomEndpoint) {
+        assertS3ProviderProfileContainedBy(profile, AWS_S3_PROVIDER_PROFILE);
+    }
+    const provenance = options.providerProfile === undefined
+        ? inferredNativeAws
+            ? 'native'
+            : 'unverified'
+        : inferredNativeAws
+            ? 'native'
+            : 'verified';
+    const constructionMetadata = getS3ConstructionMetadata(raw);
+    const publicBaseUrlConfigured = options.publicBaseUrl !== undefined ||
+        constructionMetadata?.publicBaseUrlConfigured === true;
+    const bucket = base.bucket;
+    const requestAdapter = { bucket, raw };
+    const signedUploadUrl = async (key, signOptions) => {
+        if (signOptions.minSize !== undefined &&
+            signOptions.maxSize === undefined) {
+            throw new StorageError('S3 signed uploads cannot enforce minSize without maxSize.', {
+                code: StorageErrorCode.NOT_SUPPORTED,
+                key,
+                operation: 'signUpload',
+                permanent: true,
+            });
+        }
+        if (signOptions.maxSize !== undefined && key.endsWith('${filename}')) {
+            throw new StorageError('Signed POST keys must not end with the AWS ${filename} template.', {
+                code: StorageErrorCode.INVALID_ARGUMENT,
+                key,
+                operation: 'signUpload',
+                permanent: true,
+            });
+        }
+        if (signOptions.contentType !== undefined &&
+            profile.signedUploadPolicy.contentType !== true) {
+            throw new StorageError(`S3 provider profile "${profile.name}" cannot enforce signed-upload contentType.`, {
+                code: StorageErrorCode.NOT_SUPPORTED,
+                key,
+                operation: 'signUpload',
+                permanent: true,
+            });
+        }
+        if (signOptions.maxSize !== undefined &&
+            profile.signedUploadPolicy.sizeRange !== true) {
+            throw new StorageError(`S3 provider profile "${profile.name}" cannot enforce signed-upload sizeRange.`, {
+                code: StorageErrorCode.NOT_SUPPORTED,
+                key,
+                operation: 'signUpload',
+                permanent: true,
+            });
+        }
+        try {
+            if (signOptions.maxSize !== undefined) {
+                const conditions = [
+                    [
+                        'content-length-range',
+                        signOptions.minSize ?? 1,
+                        signOptions.maxSize,
+                    ],
+                ];
+                if (signOptions.contentType !== undefined) {
+                    conditions.push(['eq', '$Content-Type', signOptions.contentType]);
+                }
+                const post = await createPresignedPost(raw, {
+                    Bucket: bucket,
+                    Conditions: conditions,
+                    Expires: signOptions.expiresIn,
+                    Key: key,
+                    ...(signOptions.contentType !== undefined && {
+                        Fields: { 'Content-Type': signOptions.contentType },
+                    }),
+                });
+                return { fields: post.fields, method: 'POST', url: post.url };
+            }
+            const url = await getSignedUrl(raw, new PutObjectCommand({
+                Bucket: bucket,
+                Key: key,
+                ...(signOptions.contentType !== undefined && {
+                    ContentType: signOptions.contentType,
+                }),
+            }), {
+                expiresIn: signOptions.expiresIn,
+                ...(signOptions.contentType !== undefined && {
+                    signableHeaders: new Set(['content-type']),
+                }),
+            });
+            return {
+                ...(signOptions.contentType !== undefined && {
+                    headers: { 'Content-Type': signOptions.contentType },
+                }),
+                method: 'PUT',
+                url,
+            };
+        }
+        catch (error) {
+            throw mapS3Error(error);
+        }
+    };
+    const adapter = Object.assign(base, {
+        physicalKey: profile.physicalKey,
+        signedUploadPolicy: profile.signedUploadPolicy,
+        signedUploadUrl,
         signedDownloadPolicy: Object.freeze({
-            expiresIn: options.publicBaseUrl === undefined,
+            expiresIn: constructionMetadata !== undefined && !publicBaseUrlConfigured,
         }),
-        async promote(sourceKey, destinationKey, promotion) {
-            const retries = maxRetries(promotion);
-            for (let attempt = 0;; attempt += 1) {
-                const signal = operationSignal(promotion);
-                try {
-                    await base.raw.send(new CopyObjectCommand({
-                        Bucket: base.bucket,
-                        CopySource: copySource(base.bucket, sourceKey, promotion.sourceVersion),
+    });
+    if (profile.conditionalCopySource !== undefined ||
+        profile.conditionalCopyDestination !== undefined) {
+        Object.assign(adapter, {
+            ...(profile.conditionalCopySource !== undefined && {
+                conditionalCopySource: profile.conditionalCopySource,
+            }),
+            ...(profile.conditionalCopyDestination !== undefined && {
+                conditionalCopyDestination: profile.conditionalCopyDestination,
+            }),
+            async promote(sourceKey, destinationKey, promotion) {
+                const destination = promotion.destination;
+                if (destination !== undefined &&
+                    (typeof destination !== 'object' ||
+                        destination === null ||
+                        (destination.type !== 'create' && destination.type !== 'replace'))) {
+                    throw new StorageError('destination.type must be "create" or "replace".', {
+                        code: StorageErrorCode.INVALID_ARGUMENT,
+                        key: destinationKey,
+                        operation: 'promote',
+                        permanent: true,
+                    });
+                }
+                if ((promotion.sourceEtag !== undefined &&
+                    profile.conditionalCopySource?.etag !== true) ||
+                    (promotion.sourceVersion !== undefined &&
+                        profile.conditionalCopySource?.version !== true) ||
+                    (promotion.destination?.type === 'create' &&
+                        profile.conditionalCopyDestination?.create !== true) ||
+                    (promotion.destination?.type === 'replace' &&
+                        profile.conditionalCopyDestination?.replace !== true) ||
+                    (promotion.destination !== undefined &&
+                        (promotion.sourceEtag !== undefined ||
+                            promotion.sourceVersion !== undefined) &&
+                        profile.conditionalCopyDestination?.atomicWithSource !== true)) {
+                    throw new StorageError(`S3 provider profile "${profile.name}" does not support the requested conditional promotion.`, {
+                        code: StorageErrorCode.NOT_SUPPORTED,
+                        key: sourceKey,
+                        operation: 'promote',
+                        permanent: true,
+                    });
+                }
+                await withS3Retry(promotion, 'copy', async (signal) => {
+                    await raw.send(new CopyObjectCommand({
+                        Bucket: bucket,
+                        CopySource: copySource(bucket, sourceKey, promotion.sourceVersion),
                         ...(promotion.sourceEtag !== undefined && {
-                            CopySourceIfMatch: promotion.sourceEtag,
+                            CopySourceIfMatch: etagHeader(promotion.sourceEtag, sourceKey, 'copy', 'sourceEtag'),
                         }),
+                        ...(promotion.destination?.type === 'create'
+                            ? { IfNoneMatch: '*' }
+                            : promotion.destination?.type === 'replace'
+                                ? {
+                                    IfMatch: etagHeader(promotion.destination.etag, destinationKey, 'copy', 'destination.etag'),
+                                }
+                                : {}),
                         Key: destinationKey,
                     }), signal === undefined ? undefined : { abortSignal: signal });
-                    return;
+                });
+            },
+        });
+    }
+    if (profile.conditionalRead !== undefined) {
+        Object.assign(adapter, {
+            conditionalRead: profile.conditionalRead,
+            async downloadConditional(key, options) {
+                if ((options.condition.etag !== undefined &&
+                    profile.conditionalRead?.etag !== true) ||
+                    (options.condition.version !== undefined &&
+                        profile.conditionalRead?.version !== true)) {
+                    throw new StorageError(`S3 provider profile "${profile.name}" does not support the requested conditional read.`, {
+                        code: StorageErrorCode.NOT_SUPPORTED,
+                        key,
+                        operation: 'download',
+                        permanent: true,
+                    });
+                }
+                const result = await withS3Retry(options, 'download', (signal) => raw.send(new GetObjectCommand({
+                    Bucket: bucket,
+                    ...(options.condition.etag !== undefined && {
+                        IfMatch: etagHeader(options.condition.etag, key, 'download', 'condition.etag'),
+                    }),
+                    Key: key,
+                    ...(rangeHeader(options.range) !== undefined && {
+                        Range: rangeHeader(options.range),
+                    }),
+                    ...(options.condition.version !== undefined && {
+                        VersionId: options.condition.version,
+                    }),
+                }), signal === undefined ? undefined : { abortSignal: signal }));
+                const etag = providerEtag(result.ETag, key, 'download');
+                return {
+                    body: s3ResponseStream(result.Body),
+                    contentType: result.ContentType ?? 'application/octet-stream',
+                    ...(etag !== undefined && { etag }),
+                    key,
+                    ...(result.LastModified !== undefined && {
+                        lastModified: result.LastModified,
+                    }),
+                    ...(result.Metadata !== undefined && { metadata: result.Metadata }),
+                    name: key.split('/').at(-1) ?? key,
+                    size: Number(result.ContentLength ?? 0),
+                };
+            },
+        });
+    }
+    if (profile.conditionalDelete !== undefined) {
+        Object.assign(adapter, {
+            conditionalDelete: profile.conditionalDelete,
+            async deleteConditional(key, options) {
+                await withS3Retry(options, 'delete', async (signal) => {
+                    await raw.send(new DeleteObjectCommand({
+                        Bucket: bucket,
+                        IfMatch: etagHeader(options.condition.etag, key, 'delete', 'condition.etag'),
+                        Key: key,
+                    }), signal === undefined ? undefined : { abortSignal: signal });
+                });
+            },
+        });
+    }
+    if (profile.conditionalCreate !== undefined ||
+        profile.conditionalReplace !== undefined) {
+        Object.assign(adapter, {
+            ...(profile.conditionalCreate !== undefined && {
+                conditionalCreate: profile.conditionalCreate,
+            }),
+            ...(profile.conditionalReplace !== undefined && {
+                conditionalReplace: profile.conditionalReplace,
+            }),
+            ...(profile.conditionalMultipartCompletion !== undefined && {
+                conditionalMultipartCompletion: profile.conditionalMultipartCompletion,
+            }),
+            async uploadConditional(key, body, conditional) {
+                if (conditional.condition.type === 'replace') {
+                    etagHeader(conditional.condition.etag, key, 'upload', 'condition.etag');
                 }
-                catch (error) {
-                    const mapped = mapS3Error(error);
-                    if (attempt >= retries ||
-                        mapped.code !== 'Provider' ||
-                        mapped.aborted ||
-                        mapped.permanent ||
-                        signal?.aborted === true) {
-                        throw mapped;
-                    }
-                    const storageError = mapFilesSdkError(mapped);
-                    const delay = typeof promotion.retries === 'object' &&
-                        promotion.retries.backoff !== undefined
-                        ? promotion.retries.backoff({
-                            attempt: attempt + 1,
-                            error: storageError,
-                        })
-                        : Math.min(1000, 100 * 2 ** attempt);
-                    await waitForRetry(delay, promotion.signal);
+                const supported = conditional.condition.type === 'create'
+                    ? profile.conditionalCreate !== undefined
+                    : profile.conditionalReplace !== undefined;
+                const multipartRequested = conditional.multipart !== undefined &&
+                    conditional.multipart !== false;
+                const multipartSupported = !multipartRequested ||
+                    (conditional.condition.type === 'create'
+                        ? profile.conditionalMultipartCompletion?.create === true
+                        : profile.conditionalMultipartCompletion?.replace === true);
+                if (!supported || !multipartSupported) {
+                    throw new StorageError(`S3 provider profile "${profile.name}" does not support the requested conditional upload.`, {
+                        code: StorageErrorCode.NOT_SUPPORTED,
+                        key,
+                        operation: 'upload',
+                        permanent: true,
+                    });
                 }
-            }
-        },
-    });
+                if (conditional.control !== undefined) {
+                    throw new StorageError('Conditional S3 uploads do not support resumable control.', {
+                        code: StorageErrorCode.NOT_SUPPORTED,
+                        key,
+                        operation: 'upload',
+                        permanent: true,
+                    });
+                }
+                return multipartRequested
+                    ? uploadConditionalMultipart(requestAdapter, key, body, conditional)
+                    : uploadConditionalSingle(requestAdapter, key, body, conditional);
+            },
+        });
+    }
+    Object.freeze(adapter);
+    markFilesSdkS3RawClientProvenance(raw, adapter, provenance);
+    configuredS3Clients.add(raw);
+    return adapter;
 }
 /**
  * Creates the files-sdk S3 driver from the storage package's own dependency
- * context and adds an ETag/version-conditional server-side promotion.
+ * context and exposes only the operations in its verified provider profile.
  */
 export function createS3StorageDriver(options) {
     const { adapter: adapterOptions, ...filesOptions } = options;
+    const { providerProfile, ...plainFilesOptions } = filesOptions;
+    const unverifiedCustomEndpoint = adapterOptions.endpoint !== undefined && providerProfile === undefined;
     return createFilesSdkDriver({
-        ...filesOptions,
-        adapter: withS3Capabilities(s3(adapterOptions), adapterOptions),
+        ...plainFilesOptions,
+        ...(unverifiedCustomEndpoint && { readonly: true }),
+        adapter: withS3Capabilities(s3(adapterOptions), {
+            ...adapterOptions,
+            ...(providerProfile !== undefined && { providerProfile }),
+        }),
     });
 }
-export { mapS3Error, s3 } from 'files-sdk/s3';
+export { mapS3Error };
 //# sourceMappingURL=index.js.map