@nestm/storage 0.1.0-alpha.2 → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @nestm/storage
 
+## 0.1.0-alpha.3
+
+### Minor Changes
+
+- b947634: Harden storage integration boundaries with cross-copy-safe `StorageError`
+  detection, a package-owned S3 driver factory, conditional staged-object
+  promotion, and a mandatory parsed key policy plus signed-transfer limits for
+  the optional HTTP gateway.
+
+### Patch Changes
+
+- b947634: Map structurally branded `files-sdk` errors, including errors wrapped across
+  duplicate package copies, so missing objects retain the `NOT_FOUND` storage
+  error code.
+
 ## 0.1.0-alpha.2
 
 ### Minor Changes

package/README.md

@@ -25,7 +25,15 @@ consumers do not download NestJS.
 ## Install
 
 ```sh
-pnpm add @nestm/storage@alpha files-sdk@2.2.2
+pnpm add @nestm/storage@alpha
+```
+
+The package-owned S3 factory needs no direct `files-sdk` import. Install the
+pinned engine explicitly only when the application imports another adapter
+such as `files-sdk/gcs`:
+
+```sh
+pnpm add files-sdk@2.2.2
 ```
 
 Install only the native SDKs required by the chosen provider. For example:
@@ -82,14 +90,15 @@ runtime or declaration imports. Provider adapters remain available through
 
 ## Configure named stores
 
-Create provider adapters with `files-sdk`, wrap them through the explicit
-bridge, and register the resulting drivers:
+Use the package-owned S3 factory when applicable. For other providers, create a
+`files-sdk` adapter, wrap it through the explicit bridge, and register the
+resulting driver:
 
 ```ts
 import { Module } from '@nestjs/common';
-import { s3 } from 'files-sdk/s3';
 import { gcs } from 'files-sdk/gcs';
 import { createFilesSdkDriver } from '@nestm/storage/files-sdk';
+import { createS3StorageDriver } from '@nestm/storage/files-sdk/s3';
 import { StorageModule } from '@nestm/storage';
 
 export const StorageKey = {
@@ -104,11 +113,11 @@ export const StorageKey = {
       stores: [
         {
           name: StorageKey.MEDIA,
-          driver: createFilesSdkDriver({
-            adapter: s3({
+          driver: createS3StorageDriver({
+            adapter: {
               bucket: 'media',
               region: 'us-east-1',
-            }),
+            },
           }),
         },
         {
@@ -194,11 +203,11 @@ StorageModule.forRootAsync({
       name: 'media',
       inject: [ConfigService],
       useFactory: (config: ConfigService) =>
-        createFilesSdkDriver({
-          adapter: s3({
+        createS3StorageDriver({
+          adapter: {
             bucket: config.getOrThrow('MEDIA_BUCKET'),
             region: config.getOrThrow('AWS_REGION'),
-          }),
+          },
         }),
     },
   ],
@@ -221,6 +230,7 @@ whitespace.
 `StorageClient` exposes:
 
 - `upload`, `downloadStream`, `head`, `exists`, `delete`, `copy`, and `move`;
+- conditional staged-object `promote` when the driver advertises it;
 - `list`, cursor-aware `listAll`, and lazy `search`;
 - `signDownload` and discriminated PUT/POST `signUpload`;
 - `uploadMany`, `downloadMany`, `headMany`, `existsMany`, and `deleteMany`;
@@ -250,6 +260,37 @@ Node `Readable` uploads are accepted and converted to Web streams without
 buffering. Provider capability gaps fail closed with `StorageError` rather than
 silently discarding a range, metadata, or cache-control request.
 
+### Race-free staged-object promotion
+
+The S3 bridge advertises ETag- and version-conditional server-side copy. This
+lets an application validate a staged object and copy that exact source to its
+final key instead of re-reading whichever bytes occupy the staging key later:
+
+```ts
+import { StorageError, StorageErrorCode } from '@nestm/storage';
+
+const staged = await media.head(stagingKey);
+if (staged.etag === undefined) {
+  throw new StorageError('Provider did not return a source ETag.', {
+    code: StorageErrorCode.NOT_SUPPORTED,
+  });
+}
+
+// Validate size, declared MIME, and magic bytes before this call.
+await media.file(stagingKey).promoteTo(finalKey, {
+  sourceEtag: staged.etag,
+});
+
+// Commit ready metadata first. Promotion deliberately retains the staged
+// object so a failed database commit remains recoverable.
+await media.delete(stagingKey);
+```
+
+`sourceVersion` can select an immutable S3 version and may be combined with
+`sourceEtag`. A promotion without either identity is rejected. Drivers that do
+not publish `capabilities.conditionalCopy` fail with `NOT_SUPPORTED` rather
+than falling back to an unsafe ordinary copy.
+
 ### Resumable uploads
 
 ```ts
@@ -301,20 +342,42 @@ The gateway lives at `@nestm/storage/gateway` and is never mounted by
 `StorageModule`.
 
 ```ts
-import { Module } from '@nestjs/common';
+import { Injectable, Module } from '@nestjs/common';
 import {
   StorageGatewayModule,
   StorageGatewayOperation,
+  type StorageGatewayKeyPolicy,
 } from '@nestm/storage/gateway';
 
+@Injectable()
+class TenantStorageKeyPolicy implements StorageGatewayKeyPolicy {
+  resolve({ input, request, target }) {
+    const tenantId = tenantIdFromAuthenticatedRequest(request);
+    const root = `tenants/${base64url(tenantId)}`;
+    if (target === 'pattern') {
+      // Search is already constrained by the separately resolved prefix.
+      return input?.value ?? '*';
+    }
+    return `${root}/${input?.value ?? ''}`;
+  }
+}
+
+@Module({
+  providers: [TenantStorageKeyPolicy],
+  exports: [TenantStorageKeyPolicy],
+})
+class StoragePolicyModule {}
+
 @Module({
   imports: [
     AppStorageModule,
     AuthModule,
+    StoragePolicyModule,
     StorageGatewayModule.register({
-      imports: [AppStorageModule, AuthModule],
+      imports: [AppStorageModule, AuthModule, StoragePolicyModule],
       store: 'media',
       guards: [JwtAuthGuard],
+      keyPolicy: TenantStorageKeyPolicy,
       mode: 'hybrid',
       operations: [
         StorageGatewayOperation.DOWNLOAD,
@@ -325,6 +388,9 @@ import {
         StorageGatewayOperation.SIGN_UPLOAD,
       ],
       maxUploadBytes: 100 * 1024 * 1024,
+      maxSignedUploadBytes: 10 * 1024 * 1024,
+      signedUploadContentTypes: ['image/jpeg', 'image/png'],
+      maxSignedUrlExpiresIn: 900,
       maxListResults: 1000,
       maxSearchResults: 1000,
       proxyInlineContentTypes: ['image/jpeg', 'image/png'],
@@ -338,12 +404,39 @@ Registration fails without at least one existing Nest guard. The only bypass is
 the explicit `allowUnauthenticated: true` development escape hatch. Operations
 are deny-by-default and must be allowlisted individually.
 
+Registration also fails without a `keyPolicy`. Guards answer whether a request
+may reach the gateway; the key policy independently resolves every parsed
+`key`, `prefix`, search `pattern`, `from`, and `to` value to the exact provider
+path. It runs even when a list/search prefix was omitted, so the policy can
+always impose a tenant root. Key-policy providers may be request scoped.
+Returned paths are parsed again and reject absolute paths, backslashes, control
+characters, empty segments, and dot/parent segments.
+
+Existing single-tenant applications can temporarily set
+`unsafeAllowUnscopedKeys: true` instead of `keyPolicy`. The name is intentional:
+it preserves caller-controlled provider keys and must not be used on an exposed
+or multi-tenant gateway. It cannot be combined with `keyPolicy`.
+
 Proxy downloads default to `Content-Disposition: attachment` and always send
 `X-Content-Type-Options: nosniff`. Add only trusted, non-active MIME types to
 `proxyInlineContentTypes` when browser rendering is required. Search responses
 are capped by `maxSearchResults`, and list pages by `maxListResults` (both
 1,000 by default).
 
+Every signed URL is capped by `maxSignedUrlExpiresIn` (3,600 seconds by
+default). Signed uploads always carry a provider-enforced maximum size, capped
+by `maxSignedUploadBytes`, and require an exact lowercase MIME type from
+`signedUploadContentTypes`. The default direct-upload allowlist contains only
+`application/octet-stream`. Gateway callers may request only the literal
+`attachment` or `inline` response disposition; arbitrary response-header text
+and filenames are rejected. A driver must also advertise
+`signedUploadPolicy.contentType` and `signedUploadPolicy.sizeRange`; otherwise
+the gateway refuses to mint the URL. `createS3StorageDriver()` advertises both
+and uses S3 POST policy conditions. Signed downloads similarly require
+`signedDownloadPolicy.expiresIn`. The S3 factory advertises it only when no
+permanent `publicBaseUrl` was configured, preventing a configured TTL from
+silently returning a non-expiring public link.
+
 The fixed gateway prefix is `/storage`:
 
 | Method   | Path                        | Operation                            |
@@ -394,9 +487,14 @@ try {
 }
 ```
 
+`files-sdk` `NotFound` failures retain `StorageErrorCode.NOT_FOUND`, including
+when a provider adapter and this driver resolve separate copies of `files-sdk`.
+`isStorageError()` likewise recognizes branded and exact legacy structural
+errors produced by a duplicated `@nestm/storage` package copy.
+
 Capability flags cover range reads, native byte-level upload progress,
 delimiter listing, metadata, cache control, resumable uploads, server-side
-copy, and signed transfers.
+copy, conditional promotion, and signed transfers.
 Provider-specific native clients are intentionally not exposed from the root
 package.
 

package/SECURITY.md

@@ -23,3 +23,26 @@ cross-store pruning, or dependency compromise are especially useful.
 For a vulnerability originating in NestJS, `files-sdk`, or a provider SDK,
 follow that project's security policy as well. You may still report it here
 privately when this integration needs a mitigation.
+
+## Gateway security boundary
+
+Mounting the optional HTTP gateway requires both authentication guards and a
+`StorageGatewayKeyPolicy`. The policy receives parsed paths and must derive the
+provider key space from trusted request context. Do not treat a client prefix
+or object key as a tenant identifier. `unsafeAllowUnscopedKeys` exists only to
+migrate trusted single-tenant deployments and is unsafe on an exposed gateway.
+
+Signed URL expiry, signed-upload byte size, and signed-upload MIME are bounded
+by module configuration and cannot be increased by a request. Only `inline`
+and `attachment` content dispositions are accepted. File type still must be
+verified from magic bytes after upload; a signed MIME condition proves only
+what header the uploader supplied. The gateway rejects signed-upload drivers
+that do not advertise provider-enforced content-type and size-range policies.
+It also rejects download adapters that cannot guarantee the requested expiry;
+in particular, the S3 bridge does not treat `publicBaseUrl` links as expiring.
+
+For staged uploads on S3, use `promote`/`promoteTo` with the ETag returned by
+the validated `head` or with an immutable provider version. Ordinary `copy`
+does not protect against a staging-key replay between validation and copy.
+Conditional promotion keeps the staging source; delete it only after the
+application's metadata transaction commits.

package/dist/files-sdk/files-sdk.driver.d.ts

@@ -1,24 +1,52 @@
 import { type Adapter, type FilesOptions } from 'files-sdk';
+import { StorageError } from '../storage.error.js';
 import type { StorageDriver } from '../storage.driver.js';
-import type { StorageBody, StorageDownloadOptions, StorageListOptions, StorageListResult, StorageObject, StorageObjectMetadata, StorageOperationOptions, StorageSearchOptions, StorageSignedDownloadOptions, StorageSignedUpload, StorageSignedUploadOptions, StorageUploadOptions, StorageUploadResult } from '../storage.types.js';
+import type { StorageBody, StorageDownloadOptions, StorageListOptions, StorageListResult, StorageObject, StorageObjectMetadata, StorageOperationOptions, StorageConditionalCopyCapability, StoragePromotionOptions, StorageSearchOptions, StorageSignedUploadPolicyCapability, StorageSignedDownloadPolicyCapability, StorageSignedDownloadOptions, StorageSignedUpload, StorageSignedUploadOptions, StorageUploadOptions, StorageUploadResult } from '../storage.types.js';
 export type FilesSdkDriverOptions<AdapterType extends Adapter> = FilesOptions<AdapterType>;
+/**
+ * Optional adapter extension for providers that can conditionally copy an
+ * immutable source identity. Plain files-sdk adapters remain fully supported.
+ */
+export interface FilesSdkConditionalCopyAdapter {
+    readonly conditionalCopy: StorageConditionalCopyCapability;
+    promote(sourceKey: string, destinationKey: string, options: StoragePromotionOptions): Promise<void>;
+}
+export interface FilesSdkSignedUploadPolicyAdapter {
+    readonly signedUploadPolicy: StorageSignedUploadPolicyCapability;
+}
+export interface FilesSdkSignedDownloadPolicyAdapter {
+    readonly signedDownloadPolicy: StorageSignedDownloadPolicyCapability;
+}
+export declare function mapFilesSdkError(error: unknown): StorageError;
 export declare class FilesSdkStorageDriver<AdapterType extends Adapter = Adapter> implements StorageDriver {
     #private;
     constructor(options: FilesSdkDriverOptions<AdapterType>);
     get name(): string;
     get capabilities(): {
+        nativeUploadProgress: boolean;
+        signedUploadPolicy?: {
+            contentType: boolean;
+            sizeRange: boolean;
+        };
+        signedUpload: "runtime";
+        signedDownloadPolicy?: {
+            expiresIn: boolean;
+        };
+        signedDownload: {
+            supported: boolean;
+            maxExpiresIn?: number;
+        };
+        conditionalCopy?: {
+            supported: boolean;
+            etag: boolean;
+            version: boolean;
+        };
         cacheControl: boolean;
         delimiter: boolean;
         metadata: boolean;
         rangeRead: boolean;
         resumableUpload: boolean;
         serverSideCopy: boolean;
-        signedDownload: {
-            supported: boolean;
-            maxExpiresIn?: number;
-        };
-        signedUpload: "runtime";
-        nativeUploadProgress: boolean;
     };
     upload(key: string, body: StorageBody, options?: StorageUploadOptions): Promise<StorageUploadResult>;
     download(key: string, options?: StorageDownloadOptions): Promise<StorageObject>;
@@ -27,6 +55,7 @@ export declare class FilesSdkStorageDriver<AdapterType extends Adapter = Adapter
     delete(key: string, options?: StorageOperationOptions): Promise<void>;
     copy(sourceKey: string, destinationKey: string, options?: StorageOperationOptions): Promise<void>;
     move(sourceKey: string, destinationKey: string, options?: StorageOperationOptions): Promise<void>;
+    promote(sourceKey: string, destinationKey: string, options: StoragePromotionOptions): Promise<void>;
     list(options?: StorageListOptions): Promise<StorageListResult>;
     search(pattern: string | RegExp, options?: StorageSearchOptions): AsyncIterable<StorageObjectMetadata>;
     signDownload(key: string, options?: StorageSignedDownloadOptions): Promise<string>;

package/dist/files-sdk/files-sdk.driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files-sdk.driver.d.ts","sourceRoot":"","sources":["../../src/files-sdk/files-sdk.driver.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,OAAO,EAGZ,KAAK,YAAY,EAUlB,MAAM,WAAW,CAAC;AAGnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EACV,WAAW,EACX,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,qBAAqB,EACrB,uBAAuB,EAEvB,oBAAoB,EACpB,4BAA4B,EAC5B,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAG7B,MAAM,MAAM,qBAAqB,CAAC,WAAW,SAAS,OAAO,IAC3D,YAAY,CAAC,WAAW,CAAC,CAAC;AAyS5B,qBAAa,qBAAqB,CAChC,WAAW,SAAS,OAAO,GAAG,OAAO,CACrC,YAAW,aAAa;;gBAIZ,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC;IAKvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,YAAY;;;;;;;;;;;;;MAaf;IAEK,MAAM,CACV,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAQzB,QAAQ,CACZ,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,aAAa,CAAC;IAUnB,IAAI,CACR,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,qBAAqB,CAAC;IAMjC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrE,IAAI,CACF,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,IAAI,CAAC;IAMhB,IAAI,CACF,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,IAAI,CAAC;IAMV,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAapE,MAAM,CACJ,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,aAAa,CAAC,qBAAqB,CAAC;IAoBvC,YAAY,CACV,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,MAAM,CAAC;IAMlB,UAAU,CACR,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,mBAAmB,CAAC;CAahC;AAED,wBAAgB,oBAAoB,CAAC,WAAW,SAAS,OAAO,EAC9D,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAC1C,qBAAqB,CAAC,WAAW,CAAC,CAEpC"}
+{"version":3,"file":"files-sdk.driver.d.ts","sourceRoot":"","sources":["../../src/files-sdk/files-sdk.driver.ts"],"names":[],"mappings":"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"}

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

@@ -1,29 +1,121 @@
 import { Readable } from 'node:stream';
 import { Files, FilesError, } from 'files-sdk';
-import { StorageError, StorageErrorCode } from '../storage.error.js';
+import { StorageError, StorageErrorCode, isStorageError, } from '../storage.error.js';
 import { getFilesSdkUploadControl } from '../storage-upload-control.js';
-function mapFilesError(error) {
-    if (error instanceof StorageError) {
+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' ||
+        typeof candidate.promote !== 'function') {
+        return undefined;
+    }
+    return candidate;
+}
+function signedUploadPolicyAdapterOf(adapter) {
+    if (typeof adapter !== 'object' ||
+        adapter === null ||
+        !('signedUploadPolicy' in adapter)) {
+        return undefined;
+    }
+    const candidate = adapter;
+    const capability = candidate.signedUploadPolicy;
+    if (capability === undefined ||
+        typeof capability.contentType !== 'boolean' ||
+        typeof capability.sizeRange !== 'boolean') {
+        return undefined;
+    }
+    return candidate;
+}
+function signedDownloadPolicyAdapterOf(adapter) {
+    if (typeof adapter !== 'object' ||
+        adapter === null ||
+        !('signedDownloadPolicy' in adapter)) {
+        return undefined;
+    }
+    const candidate = adapter;
+    const capability = candidate.signedDownloadPolicy;
+    if (capability === undefined || typeof capability.expiresIn !== 'boolean') {
+        return undefined;
+    }
+    return candidate;
+}
+function isFilesErrorCode(value) {
+    return (value === 'NotFound' ||
+        value === 'Unauthorized' ||
+        value === 'Conflict' ||
+        value === 'ReadOnly' ||
+        value === 'Provider');
+}
+function isFilesErrorLike(error) {
+    if (error instanceof FilesError) {
+        return true;
+    }
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    try {
+        return (error.name === 'FilesError' &&
+            typeof error.message === 'string' &&
+            'code' in error &&
+            isFilesErrorCode(error.code) &&
+            'aborted' in error &&
+            typeof error.aborted === 'boolean' &&
+            'timedOut' in error &&
+            typeof error.timedOut === 'boolean' &&
+            'permanent' in error &&
+            typeof error.permanent === 'boolean');
+    }
+    catch {
+        return false;
+    }
+}
+function unwrapFilesError(error) {
+    const seen = new Set();
+    let current = error;
+    while (current.code === 'Provider' &&
+        !current.aborted &&
+        !current.timedOut &&
+        !current.permanent &&
+        isFilesErrorLike(current.cause) &&
+        current.message === current.cause.message &&
+        !seen.has(current.cause)) {
+        seen.add(current);
+        current = current.cause;
+    }
+    return current;
+}
+export function mapFilesSdkError(error) {
+    if (isStorageError(error)) {
         return error;
     }
-    if (!(error instanceof FilesError)) {
+    if (!isFilesErrorLike(error)) {
         return new StorageError(error instanceof Error ? error.message : String(error), {
             cause: error,
             code: StorageErrorCode.PROVIDER,
         });
     }
-    if (error.cause instanceof StorageError) {
-        return error.cause;
+    const filesError = unwrapFilesError(error);
+    if (isStorageError(filesError.cause)) {
+        return filesError.cause;
     }
     let code;
-    if (error.timedOut) {
+    if (filesError.timedOut) {
         code = StorageErrorCode.TIMEOUT;
     }
-    else if (error.aborted) {
+    else if (filesError.aborted) {
         code = StorageErrorCode.ABORTED;
     }
     else {
-        switch (error.code) {
+        switch (filesError.code) {
             case 'NotFound':
                 code = StorageErrorCode.NOT_FOUND;
                 break;
@@ -37,18 +129,18 @@ function mapFilesError(error) {
                 code = StorageErrorCode.READ_ONLY;
                 break;
             case 'Provider':
-                code = /(?:not supported|does not support|unsupported)/iu.test(error.message)
+                code = /(?:not supported|does not support|unsupported)/iu.test(filesError.message)
                     ? StorageErrorCode.NOT_SUPPORTED
                     : StorageErrorCode.PROVIDER;
                 break;
         }
     }
-    return new StorageError(error.message, {
-        aborted: error.aborted,
-        cause: error.cause ?? error,
+    return new StorageError(filesError.message, {
+        aborted: filesError.aborted,
+        cause: filesError.cause ?? error,
         code,
-        permanent: error.permanent,
-        timedOut: error.timedOut,
+        permanent: filesError.permanent,
+        timedOut: filesError.timedOut,
     });
 }
 function mapRetryOptions(retries) {
@@ -60,7 +152,7 @@ function mapRetryOptions(retries) {
         ...(retries.backoff !== undefined && {
             backoff: ({ attempt, error }) => retries.backoff?.({
                 attempt,
-                error: mapFilesError(error),
+                error: mapFilesSdkError(error),
             }) ?? 0,
         }),
     };
@@ -114,7 +206,7 @@ function normalizeDownloadStream(source) {
                 await activeReader.cancel(reason);
             }
             catch (error) {
-                throw mapFilesError(error);
+                throw mapFilesSdkError(error);
             }
             finally {
                 release();
@@ -137,7 +229,7 @@ function normalizeDownloadStream(source) {
             }
             catch (error) {
                 release();
-                controller.error(mapFilesError(error));
+                controller.error(mapFilesSdkError(error));
             }
         },
     });
@@ -256,9 +348,15 @@ function uploadResultOf(result) {
 export class FilesSdkStorageDriver {
     #files;
     #name;
+    #conditionalCopy;
+    #signedUploadPolicy;
+    #signedDownloadPolicy;
     constructor(options) {
         this.#files = new Files(options);
         this.#name = options.adapter.name;
+        this.#conditionalCopy = conditionalCopyAdapterOf(options.adapter);
+        this.#signedUploadPolicy = signedUploadPolicyAdapterOf(options.adapter);
+        this.#signedDownloadPolicy = signedDownloadPolicyAdapterOf(options.adapter);
     }
     get name() {
         return this.#name;
@@ -272,8 +370,19 @@ export class FilesSdkStorageDriver {
             rangeRead: capabilities.rangeRead,
             resumableUpload: capabilities.multipart,
             serverSideCopy: capabilities.serverSideCopy,
+            ...(this.#conditionalCopy !== undefined && {
+                conditionalCopy: { ...this.#conditionalCopy.conditionalCopy },
+            }),
             signedDownload: { ...capabilities.signedUrl },
+            ...(this.#signedDownloadPolicy !== undefined && {
+                signedDownloadPolicy: {
+                    ...this.#signedDownloadPolicy.signedDownloadPolicy,
+                },
+            }),
             signedUpload: 'runtime',
+            ...(this.#signedUploadPolicy !== undefined && {
+                signedUploadPolicy: { ...this.#signedUploadPolicy.signedUploadPolicy },
+            }),
             nativeUploadProgress: capabilities.uploadProgress,
         };
     }
@@ -306,6 +415,18 @@ export class FilesSdkStorageDriver {
     move(sourceKey, destinationKey, options) {
         return this.#call(() => this.#files.move(sourceKey, destinationKey, operationOptions(options)));
     }
+    promote(sourceKey, destinationKey, options) {
+        const adapter = this.#conditionalCopy;
+        if (adapter === undefined || !adapter.conditionalCopy.supported) {
+            return Promise.reject(new StorageError(`Storage adapter "${this.#name}" does not support conditional promotion.`, {
+                code: StorageErrorCode.NOT_SUPPORTED,
+                key: sourceKey,
+                operation: 'promote',
+                permanent: true,
+            }));
+        }
+        return this.#call(() => adapter.promote(sourceKey, destinationKey, options));
+    }
     async list(options) {
         return this.#call(async () => {
             const result = await this.#files.list(listOptions(options));
@@ -328,7 +449,7 @@ export class FilesSdkStorageDriver {
             }
         }
         catch (error) {
-            throw mapFilesError(error);
+            throw mapFilesSdkError(error);
         }
     }
     signDownload(key, options) {
@@ -342,7 +463,7 @@ export class FilesSdkStorageDriver {
             return await operation();
         }
         catch (error) {
-            throw mapFilesError(error);
+            throw mapFilesSdkError(error);
         }
     }
 }