@zucker-framework/storage 1.0.0 → 1.0.2

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { ReadStream } from 'fs';
 import { OnModuleDestroy, Type, DynamicModule, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import { ReadStream as ReadStream$1 } from 'node:fs';
 
 interface UploadOptions {
     contentType?: string;
@@ -424,10 +425,108 @@ declare class ZuckerStorageModule {
     private static createAsyncProviders;
 }
 
+interface StorageUrlHydrationOptions {
+    /** The application must establish ownership before allowing a key to be signed. */
+    allowedStorageKeys: ReadonlySet<string>;
+    getDownloadUrl: (key: string) => Promise<string>;
+    storageKeyField: string;
+    urlFields: readonly string[];
+}
+/**
+ * Clone a JSON-like response graph and resolve only authorized object keys.
+ * Dates/class instances pass through. Signatures are deduplicated within this
+ * call, never cached between requests. A signing failure rejects the whole call;
+ * generated URLs never mutate the source graph that might later be persisted.
+ */
+declare function hydrateStorageUrls<T>(value: T, options: StorageUrlHydrationOptions): Promise<T>;
+
+/** Disabled storage preserves startup availability while all data operations remain explicit. */
+declare class UnavailableFileManager implements FileManager {
+    readonly providerType: StorageProviderType;
+    private readonly message;
+    constructor(providerType: StorageProviderType, message?: string);
+    isConfigured(): boolean;
+    private unavailable;
+    upload(_buffer: Buffer, _key: string, _options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(_stream: ReadStream$1, _key: string, _options?: UploadOptions): Promise<UploadResult>;
+    download(_key: string): Promise<{
+        stream: ReadStream$1;
+        size: number;
+    }>;
+    delete(_key: string): Promise<void>;
+    exists(_key: string): Promise<boolean>;
+    getPublicUrl(_key: string): Promise<string>;
+    getDownloadUrl(_key: string): Promise<string>;
+    list(_prefix: string): Promise<FileInfo[]>;
+}
+
+interface DownloadedStorageObject {
+    body: Buffer;
+    reportedSize: number;
+}
+interface BufferedObjectStore<TMimeType extends string = string> {
+    read(key: string): Promise<DownloadedStorageObject>;
+    exists(key: string): Promise<boolean>;
+    write(key: string, body: Buffer, options: {
+        contentType: TMimeType;
+        metadata: Record<string, string>;
+        private: true;
+    }): Promise<{
+        size: number;
+    }>;
+}
+type StorageTransferErrorCode = 'STORAGE_NOT_CONFIGURED' | 'OBJECT_SIZE_OUT_OF_BOUNDS' | 'SOURCE_SIZE_MISMATCH' | 'TARGET_SIZE_CONFLICT' | 'TARGET_MIME_CONFLICT' | 'TARGET_HASH_CONFLICT' | 'UPLOAD_SIZE_MISMATCH';
+declare class StorageTransferError extends Error {
+    readonly code: StorageTransferErrorCode;
+    constructor(code: StorageTransferErrorCode);
+}
+type StorageTransferErrorFactory = (code: StorageTransferErrorCode) => Error;
+interface VerifiedStorageMetadata<TMimeType extends string = string> {
+    sha256: string;
+    size: number;
+    mimeType: TMimeType;
+}
+/** Compare every byte via SHA-256, with explicit size and MIME conflict reasons. */
+declare function verifyStoredObject<TMimeType extends string>(object: DownloadedStorageObject, expected: VerifiedStorageMetadata<TMimeType>, detectMimeType: (body: Buffer) => TMimeType, errorFactory?: StorageTransferErrorFactory): void;
+interface VerifiedObjectTransferOptions<TMimeType extends string> {
+    source: DownloadedStorageObject;
+    target: BufferedObjectStore<TMimeType>;
+    destinationKey: string;
+    mode: 'dry-run' | 'apply';
+    allowUpload: boolean;
+    detectMimeType: (body: Buffer) => TMimeType;
+    errorFactory?: StorageTransferErrorFactory;
+}
+/**
+ * Copy a bounded source buffer into a private destination, verify existing data
+ * before reuse and round-trip every upload before reporting success. Dry-run and
+ * disallowed uploads never write. This does not delete sources or commit metadata.
+ */
+declare function transferVerifiedObject<TMimeType extends string>(options: VerifiedObjectTransferOptions<TMimeType>): Promise<VerifiedStorageMetadata<TMimeType> & {
+    targetDisposition: 'planned' | 'uploaded' | 'reused';
+}>;
+
+/** Bounded in-memory transfer adapter over the existing FileManager contract. */
+declare class BufferedFileManagerStore implements BufferedObjectStore {
+    private readonly manager;
+    private readonly maxObjectBytes;
+    private readonly errorFactory;
+    constructor(manager: FileManager, maxObjectBytes: number, errorFactory?: StorageTransferErrorFactory);
+    read(key: string): Promise<DownloadedStorageObject>;
+    exists(key: string): Promise<boolean>;
+    write(key: string, body: Buffer, options: {
+        contentType: string;
+        metadata: Record<string, string>;
+        private: true;
+    }): Promise<{
+        size: number;
+    }>;
+}
+
 declare enum StorageProvider {
     LOCAL = "LOCAL",
     S3 = "S3",
     WEBDAV = "WEBDAV"
 }
 
-export { type ChunkUploadState, DANGEROUS_EXTENSIONS, FILE_MANAGER, type FileInfo, FileLifecycleManager, type FileLifecyclePolicy, type FileManager, type FileMetadata, type FileUploadValidation, type LifecycleResult, LocalFileStorage, type PosixFilePermissions, type S3ObjectAclMode, S3Storage, type S3StorageOptions, type S3UploadUrlMode, type StorageModuleAsyncOptions, type StorageModuleOptions, type StorageModuleOptionsFactory, StorageProvider, type StorageProviderType, type UploadOptions, type UploadResult, WebDavStorage, type WebDavStorageOptions, ZuckerStorageModule, generateDateBasedKey, isFileDenied, isSafeOriginalFileName, sanitizeFileName };
+export { BufferedFileManagerStore, type BufferedObjectStore, type ChunkUploadState, DANGEROUS_EXTENSIONS, type DownloadedStorageObject, FILE_MANAGER, type FileInfo, FileLifecycleManager, type FileLifecyclePolicy, type FileManager, type FileMetadata, type FileUploadValidation, type LifecycleResult, LocalFileStorage, type PosixFilePermissions, type S3ObjectAclMode, S3Storage, type S3StorageOptions, type S3UploadUrlMode, type StorageModuleAsyncOptions, type StorageModuleOptions, type StorageModuleOptionsFactory, StorageProvider, type StorageProviderType, StorageTransferError, type StorageTransferErrorCode, type StorageTransferErrorFactory, type StorageUrlHydrationOptions, UnavailableFileManager, type UploadOptions, type UploadResult, type VerifiedObjectTransferOptions, type VerifiedStorageMetadata, WebDavStorage, type WebDavStorageOptions, ZuckerStorageModule, generateDateBasedKey, hydrateStorageUrls, isFileDenied, isSafeOriginalFileName, sanitizeFileName, transferVerifiedObject, verifyStoredObject };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ReadStream } from 'fs';
 import { OnModuleDestroy, Type, DynamicModule, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import { ReadStream as ReadStream$1 } from 'node:fs';
 
 interface UploadOptions {
     contentType?: string;
@@ -424,10 +425,108 @@ declare class ZuckerStorageModule {
     private static createAsyncProviders;
 }
 
+interface StorageUrlHydrationOptions {
+    /** The application must establish ownership before allowing a key to be signed. */
+    allowedStorageKeys: ReadonlySet<string>;
+    getDownloadUrl: (key: string) => Promise<string>;
+    storageKeyField: string;
+    urlFields: readonly string[];
+}
+/**
+ * Clone a JSON-like response graph and resolve only authorized object keys.
+ * Dates/class instances pass through. Signatures are deduplicated within this
+ * call, never cached between requests. A signing failure rejects the whole call;
+ * generated URLs never mutate the source graph that might later be persisted.
+ */
+declare function hydrateStorageUrls<T>(value: T, options: StorageUrlHydrationOptions): Promise<T>;
+
+/** Disabled storage preserves startup availability while all data operations remain explicit. */
+declare class UnavailableFileManager implements FileManager {
+    readonly providerType: StorageProviderType;
+    private readonly message;
+    constructor(providerType: StorageProviderType, message?: string);
+    isConfigured(): boolean;
+    private unavailable;
+    upload(_buffer: Buffer, _key: string, _options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(_stream: ReadStream$1, _key: string, _options?: UploadOptions): Promise<UploadResult>;
+    download(_key: string): Promise<{
+        stream: ReadStream$1;
+        size: number;
+    }>;
+    delete(_key: string): Promise<void>;
+    exists(_key: string): Promise<boolean>;
+    getPublicUrl(_key: string): Promise<string>;
+    getDownloadUrl(_key: string): Promise<string>;
+    list(_prefix: string): Promise<FileInfo[]>;
+}
+
+interface DownloadedStorageObject {
+    body: Buffer;
+    reportedSize: number;
+}
+interface BufferedObjectStore<TMimeType extends string = string> {
+    read(key: string): Promise<DownloadedStorageObject>;
+    exists(key: string): Promise<boolean>;
+    write(key: string, body: Buffer, options: {
+        contentType: TMimeType;
+        metadata: Record<string, string>;
+        private: true;
+    }): Promise<{
+        size: number;
+    }>;
+}
+type StorageTransferErrorCode = 'STORAGE_NOT_CONFIGURED' | 'OBJECT_SIZE_OUT_OF_BOUNDS' | 'SOURCE_SIZE_MISMATCH' | 'TARGET_SIZE_CONFLICT' | 'TARGET_MIME_CONFLICT' | 'TARGET_HASH_CONFLICT' | 'UPLOAD_SIZE_MISMATCH';
+declare class StorageTransferError extends Error {
+    readonly code: StorageTransferErrorCode;
+    constructor(code: StorageTransferErrorCode);
+}
+type StorageTransferErrorFactory = (code: StorageTransferErrorCode) => Error;
+interface VerifiedStorageMetadata<TMimeType extends string = string> {
+    sha256: string;
+    size: number;
+    mimeType: TMimeType;
+}
+/** Compare every byte via SHA-256, with explicit size and MIME conflict reasons. */
+declare function verifyStoredObject<TMimeType extends string>(object: DownloadedStorageObject, expected: VerifiedStorageMetadata<TMimeType>, detectMimeType: (body: Buffer) => TMimeType, errorFactory?: StorageTransferErrorFactory): void;
+interface VerifiedObjectTransferOptions<TMimeType extends string> {
+    source: DownloadedStorageObject;
+    target: BufferedObjectStore<TMimeType>;
+    destinationKey: string;
+    mode: 'dry-run' | 'apply';
+    allowUpload: boolean;
+    detectMimeType: (body: Buffer) => TMimeType;
+    errorFactory?: StorageTransferErrorFactory;
+}
+/**
+ * Copy a bounded source buffer into a private destination, verify existing data
+ * before reuse and round-trip every upload before reporting success. Dry-run and
+ * disallowed uploads never write. This does not delete sources or commit metadata.
+ */
+declare function transferVerifiedObject<TMimeType extends string>(options: VerifiedObjectTransferOptions<TMimeType>): Promise<VerifiedStorageMetadata<TMimeType> & {
+    targetDisposition: 'planned' | 'uploaded' | 'reused';
+}>;
+
+/** Bounded in-memory transfer adapter over the existing FileManager contract. */
+declare class BufferedFileManagerStore implements BufferedObjectStore {
+    private readonly manager;
+    private readonly maxObjectBytes;
+    private readonly errorFactory;
+    constructor(manager: FileManager, maxObjectBytes: number, errorFactory?: StorageTransferErrorFactory);
+    read(key: string): Promise<DownloadedStorageObject>;
+    exists(key: string): Promise<boolean>;
+    write(key: string, body: Buffer, options: {
+        contentType: string;
+        metadata: Record<string, string>;
+        private: true;
+    }): Promise<{
+        size: number;
+    }>;
+}
+
 declare enum StorageProvider {
     LOCAL = "LOCAL",
     S3 = "S3",
     WEBDAV = "WEBDAV"
 }
 
-export { type ChunkUploadState, DANGEROUS_EXTENSIONS, FILE_MANAGER, type FileInfo, FileLifecycleManager, type FileLifecyclePolicy, type FileManager, type FileMetadata, type FileUploadValidation, type LifecycleResult, LocalFileStorage, type PosixFilePermissions, type S3ObjectAclMode, S3Storage, type S3StorageOptions, type S3UploadUrlMode, type StorageModuleAsyncOptions, type StorageModuleOptions, type StorageModuleOptionsFactory, StorageProvider, type StorageProviderType, type UploadOptions, type UploadResult, WebDavStorage, type WebDavStorageOptions, ZuckerStorageModule, generateDateBasedKey, isFileDenied, isSafeOriginalFileName, sanitizeFileName };
+export { BufferedFileManagerStore, type BufferedObjectStore, type ChunkUploadState, DANGEROUS_EXTENSIONS, type DownloadedStorageObject, FILE_MANAGER, type FileInfo, FileLifecycleManager, type FileLifecyclePolicy, type FileManager, type FileMetadata, type FileUploadValidation, type LifecycleResult, LocalFileStorage, type PosixFilePermissions, type S3ObjectAclMode, S3Storage, type S3StorageOptions, type S3UploadUrlMode, type StorageModuleAsyncOptions, type StorageModuleOptions, type StorageModuleOptionsFactory, StorageProvider, type StorageProviderType, StorageTransferError, type StorageTransferErrorCode, type StorageTransferErrorFactory, type StorageUrlHydrationOptions, UnavailableFileManager, type UploadOptions, type UploadResult, type VerifiedObjectTransferOptions, type VerifiedStorageMetadata, WebDavStorage, type WebDavStorageOptions, ZuckerStorageModule, generateDateBasedKey, hydrateStorageUrls, isFileDenied, isSafeOriginalFileName, sanitizeFileName, transferVerifiedObject, verifyStoredObject };

package/dist/index.js

@@ -31,18 +31,24 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BufferedFileManagerStore: () => BufferedFileManagerStore,
   DANGEROUS_EXTENSIONS: () => DANGEROUS_EXTENSIONS,
   FILE_MANAGER: () => FILE_MANAGER,
   FileLifecycleManager: () => FileLifecycleManager,
   LocalFileStorage: () => LocalFileStorage,
   S3Storage: () => S3Storage,
   StorageProvider: () => StorageProvider,
+  StorageTransferError: () => StorageTransferError,
+  UnavailableFileManager: () => UnavailableFileManager,
   WebDavStorage: () => WebDavStorage,
   ZuckerStorageModule: () => ZuckerStorageModule,
   generateDateBasedKey: () => generateDateBasedKey,
+  hydrateStorageUrls: () => hydrateStorageUrls,
   isFileDenied: () => isFileDenied,
   isSafeOriginalFileName: () => isSafeOriginalFileName,
-  sanitizeFileName: () => sanitizeFileName
+  sanitizeFileName: () => sanitizeFileName,
+  transferVerifiedObject: () => transferVerifiedObject,
+  verifyStoredObject: () => verifyStoredObject
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1057,6 +1063,198 @@ ZuckerStorageModule = _ts_decorate5([
   (0, import_common5.Module)({})
 ], ZuckerStorageModule);
 
+// src/storage-url-hydrator.ts
+function isPlainRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+__name(isPlainRecord, "isPlainRecord");
+async function hydrateStorageUrls(value, options) {
+  const signedUrls = /* @__PURE__ */ new Map();
+  const hydrate = /* @__PURE__ */ __name(async (current) => {
+    if (Array.isArray(current)) return Promise.all(current.map(hydrate));
+    if (!isPlainRecord(current)) return current;
+    const entries = await Promise.all(Object.entries(current).map(async ([key2, nested]) => [
+      key2,
+      await hydrate(nested)
+    ]));
+    const result = Object.fromEntries(entries);
+    const key = result[options.storageKeyField];
+    if (typeof key === "string" && key.length > 0 && options.allowedStorageKeys.has(key)) {
+      let signed = signedUrls.get(key);
+      if (!signed) {
+        signed = options.getDownloadUrl(key);
+        signedUrls.set(key, signed);
+      }
+      const url = await signed;
+      for (const field of options.urlFields) {
+        Object.defineProperty(result, field, {
+          value: url,
+          writable: true,
+          enumerable: true,
+          configurable: true
+        });
+      }
+    }
+    return result;
+  }, "hydrate");
+  return hydrate(value);
+}
+__name(hydrateStorageUrls, "hydrateStorageUrls");
+
+// src/unavailable-file-manager.ts
+var UnavailableFileManager = class {
+  static {
+    __name(this, "UnavailableFileManager");
+  }
+  providerType;
+  message;
+  constructor(providerType, message = `Storage provider ${providerType} is not configured`) {
+    this.providerType = providerType;
+    this.message = message;
+  }
+  isConfigured() {
+    return false;
+  }
+  unavailable() {
+    return new Error(this.message);
+  }
+  upload(_buffer, _key, _options) {
+    return Promise.reject(this.unavailable());
+  }
+  uploadStream(_stream, _key, _options) {
+    return Promise.reject(this.unavailable());
+  }
+  download(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  delete(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  exists(_key) {
+    return Promise.resolve(false);
+  }
+  getPublicUrl(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  getDownloadUrl(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  list(_prefix) {
+    return Promise.resolve([]);
+  }
+};
+
+// src/verified-object-transfer.ts
+var import_node_crypto2 = require("crypto");
+var StorageTransferError = class extends Error {
+  static {
+    __name(this, "StorageTransferError");
+  }
+  code;
+  constructor(code) {
+    super(code), this.code = code;
+    this.name = "StorageTransferError";
+  }
+};
+function verifyStoredObject(object, expected, detectMimeType, errorFactory = (code) => new StorageTransferError(code)) {
+  if (object.reportedSize !== object.body.length || object.body.length !== expected.size) throw errorFactory("TARGET_SIZE_CONFLICT");
+  if (detectMimeType(object.body) !== expected.mimeType) throw errorFactory("TARGET_MIME_CONFLICT");
+  if ((0, import_node_crypto2.createHash)("sha256").update(object.body).digest("hex") !== expected.sha256) throw errorFactory("TARGET_HASH_CONFLICT");
+}
+__name(verifyStoredObject, "verifyStoredObject");
+async function transferVerifiedObject(options) {
+  const fail = options.errorFactory ?? ((code) => new StorageTransferError(code));
+  const body = options.source.body;
+  if (options.source.reportedSize !== body.length || body.length === 0) throw fail("SOURCE_SIZE_MISMATCH");
+  const metadata = {
+    sha256: (0, import_node_crypto2.createHash)("sha256").update(body).digest("hex"),
+    size: body.length,
+    mimeType: options.detectMimeType(body)
+  };
+  if (await options.target.exists(options.destinationKey)) {
+    verifyStoredObject(await options.target.read(options.destinationKey), metadata, options.detectMimeType, fail);
+    return {
+      ...metadata,
+      targetDisposition: options.mode === "dry-run" ? "planned" : "reused"
+    };
+  }
+  if (options.mode === "dry-run" || !options.allowUpload) return {
+    ...metadata,
+    targetDisposition: "planned"
+  };
+  const uploaded = await options.target.write(options.destinationKey, body, {
+    contentType: metadata.mimeType,
+    metadata: {
+      sha256: metadata.sha256,
+      size: String(metadata.size),
+      mimeType: metadata.mimeType
+    },
+    private: true
+  });
+  if (uploaded.size !== metadata.size) throw fail("UPLOAD_SIZE_MISMATCH");
+  verifyStoredObject(await options.target.read(options.destinationKey), metadata, options.detectMimeType, fail);
+  return {
+    ...metadata,
+    targetDisposition: "uploaded"
+  };
+}
+__name(transferVerifiedObject, "transferVerifiedObject");
+
+// src/buffered-file-manager-store.ts
+var BufferedFileManagerStore = class {
+  static {
+    __name(this, "BufferedFileManagerStore");
+  }
+  manager;
+  maxObjectBytes;
+  errorFactory;
+  constructor(manager, maxObjectBytes, errorFactory = (code) => new StorageTransferError(code)) {
+    this.manager = manager;
+    this.maxObjectBytes = maxObjectBytes;
+    this.errorFactory = errorFactory;
+    if (!Number.isSafeInteger(maxObjectBytes) || maxObjectBytes < 1) throw new RangeError("maxObjectBytes must be a positive integer");
+    if (!manager.isConfigured()) throw errorFactory("STORAGE_NOT_CONFIGURED");
+  }
+  async read(key) {
+    const downloaded = await this.manager.download(key);
+    if (downloaded.size < 1 || downloaded.size > this.maxObjectBytes) {
+      downloaded.stream.destroy();
+      throw this.errorFactory("OBJECT_SIZE_OUT_OF_BOUNDS");
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of downloaded.stream) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      size += buffer.length;
+      if (size > this.maxObjectBytes) {
+        downloaded.stream.destroy();
+        throw this.errorFactory("OBJECT_SIZE_OUT_OF_BOUNDS");
+      }
+      chunks.push(buffer);
+    }
+    return {
+      body: Buffer.concat(chunks),
+      reportedSize: downloaded.size
+    };
+  }
+  exists(key) {
+    return this.manager.exists(key);
+  }
+  async write(key, body, options) {
+    if (body.length > this.maxObjectBytes) throw this.errorFactory("OBJECT_SIZE_OUT_OF_BOUNDS");
+    const result = await this.manager.upload(body, key, {
+      contentType: options.contentType,
+      metadata: options.metadata,
+      acl: "private"
+    });
+    return {
+      size: result.size
+    };
+  }
+};
+
 // src/index.ts
 var StorageProvider = /* @__PURE__ */ (function(StorageProvider2) {
   StorageProvider2["LOCAL"] = "LOCAL";
@@ -1066,16 +1264,22 @@ var StorageProvider = /* @__PURE__ */ (function(StorageProvider2) {
 })({});
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BufferedFileManagerStore,
   DANGEROUS_EXTENSIONS,
   FILE_MANAGER,
   FileLifecycleManager,
   LocalFileStorage,
   S3Storage,
   StorageProvider,
+  StorageTransferError,
+  UnavailableFileManager,
   WebDavStorage,
   ZuckerStorageModule,
   generateDateBasedKey,
+  hydrateStorageUrls,
   isFileDenied,
   isSafeOriginalFileName,
-  sanitizeFileName
+  sanitizeFileName,
+  transferVerifiedObject,
+  verifyStoredObject
 });

package/dist/index.mjs

@@ -1012,6 +1012,198 @@ ZuckerStorageModule = _ts_decorate5([
   Module({})
 ], ZuckerStorageModule);
 
+// src/storage-url-hydrator.ts
+function isPlainRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+__name(isPlainRecord, "isPlainRecord");
+async function hydrateStorageUrls(value, options) {
+  const signedUrls = /* @__PURE__ */ new Map();
+  const hydrate = /* @__PURE__ */ __name(async (current) => {
+    if (Array.isArray(current)) return Promise.all(current.map(hydrate));
+    if (!isPlainRecord(current)) return current;
+    const entries = await Promise.all(Object.entries(current).map(async ([key2, nested]) => [
+      key2,
+      await hydrate(nested)
+    ]));
+    const result = Object.fromEntries(entries);
+    const key = result[options.storageKeyField];
+    if (typeof key === "string" && key.length > 0 && options.allowedStorageKeys.has(key)) {
+      let signed = signedUrls.get(key);
+      if (!signed) {
+        signed = options.getDownloadUrl(key);
+        signedUrls.set(key, signed);
+      }
+      const url = await signed;
+      for (const field of options.urlFields) {
+        Object.defineProperty(result, field, {
+          value: url,
+          writable: true,
+          enumerable: true,
+          configurable: true
+        });
+      }
+    }
+    return result;
+  }, "hydrate");
+  return hydrate(value);
+}
+__name(hydrateStorageUrls, "hydrateStorageUrls");
+
+// src/unavailable-file-manager.ts
+var UnavailableFileManager = class {
+  static {
+    __name(this, "UnavailableFileManager");
+  }
+  providerType;
+  message;
+  constructor(providerType, message = `Storage provider ${providerType} is not configured`) {
+    this.providerType = providerType;
+    this.message = message;
+  }
+  isConfigured() {
+    return false;
+  }
+  unavailable() {
+    return new Error(this.message);
+  }
+  upload(_buffer, _key, _options) {
+    return Promise.reject(this.unavailable());
+  }
+  uploadStream(_stream, _key, _options) {
+    return Promise.reject(this.unavailable());
+  }
+  download(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  delete(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  exists(_key) {
+    return Promise.resolve(false);
+  }
+  getPublicUrl(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  getDownloadUrl(_key) {
+    return Promise.reject(this.unavailable());
+  }
+  list(_prefix) {
+    return Promise.resolve([]);
+  }
+};
+
+// src/verified-object-transfer.ts
+import { createHash } from "crypto";
+var StorageTransferError = class extends Error {
+  static {
+    __name(this, "StorageTransferError");
+  }
+  code;
+  constructor(code) {
+    super(code), this.code = code;
+    this.name = "StorageTransferError";
+  }
+};
+function verifyStoredObject(object, expected, detectMimeType, errorFactory = (code) => new StorageTransferError(code)) {
+  if (object.reportedSize !== object.body.length || object.body.length !== expected.size) throw errorFactory("TARGET_SIZE_CONFLICT");
+  if (detectMimeType(object.body) !== expected.mimeType) throw errorFactory("TARGET_MIME_CONFLICT");
+  if (createHash("sha256").update(object.body).digest("hex") !== expected.sha256) throw errorFactory("TARGET_HASH_CONFLICT");
+}
+__name(verifyStoredObject, "verifyStoredObject");
+async function transferVerifiedObject(options) {
+  const fail = options.errorFactory ?? ((code) => new StorageTransferError(code));
+  const body = options.source.body;
+  if (options.source.reportedSize !== body.length || body.length === 0) throw fail("SOURCE_SIZE_MISMATCH");
+  const metadata = {
+    sha256: createHash("sha256").update(body).digest("hex"),
+    size: body.length,
+    mimeType: options.detectMimeType(body)
+  };
+  if (await options.target.exists(options.destinationKey)) {
+    verifyStoredObject(await options.target.read(options.destinationKey), metadata, options.detectMimeType, fail);
+    return {
+      ...metadata,
+      targetDisposition: options.mode === "dry-run" ? "planned" : "reused"
+    };
+  }
+  if (options.mode === "dry-run" || !options.allowUpload) return {
+    ...metadata,
+    targetDisposition: "planned"
+  };
+  const uploaded = await options.target.write(options.destinationKey, body, {
+    contentType: metadata.mimeType,
+    metadata: {
+      sha256: metadata.sha256,
+      size: String(metadata.size),
+      mimeType: metadata.mimeType
+    },
+    private: true
+  });
+  if (uploaded.size !== metadata.size) throw fail("UPLOAD_SIZE_MISMATCH");
+  verifyStoredObject(await options.target.read(options.destinationKey), metadata, options.detectMimeType, fail);
+  return {
+    ...metadata,
+    targetDisposition: "uploaded"
+  };
+}
+__name(transferVerifiedObject, "transferVerifiedObject");
+
+// src/buffered-file-manager-store.ts
+var BufferedFileManagerStore = class {
+  static {
+    __name(this, "BufferedFileManagerStore");
+  }
+  manager;
+  maxObjectBytes;
+  errorFactory;
+  constructor(manager, maxObjectBytes, errorFactory = (code) => new StorageTransferError(code)) {
+    this.manager = manager;
+    this.maxObjectBytes = maxObjectBytes;
+    this.errorFactory = errorFactory;
+    if (!Number.isSafeInteger(maxObjectBytes) || maxObjectBytes < 1) throw new RangeError("maxObjectBytes must be a positive integer");
+    if (!manager.isConfigured()) throw errorFactory("STORAGE_NOT_CONFIGURED");
+  }
+  async read(key) {
+    const downloaded = await this.manager.download(key);
+    if (downloaded.size < 1 || downloaded.size > this.maxObjectBytes) {
+      downloaded.stream.destroy();
+      throw this.errorFactory("OBJECT_SIZE_OUT_OF_BOUNDS");
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of downloaded.stream) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      size += buffer.length;
+      if (size > this.maxObjectBytes) {
+        downloaded.stream.destroy();
+        throw this.errorFactory("OBJECT_SIZE_OUT_OF_BOUNDS");
+      }
+      chunks.push(buffer);
+    }
+    return {
+      body: Buffer.concat(chunks),
+      reportedSize: downloaded.size
+    };
+  }
+  exists(key) {
+    return this.manager.exists(key);
+  }
+  async write(key, body, options) {
+    if (body.length > this.maxObjectBytes) throw this.errorFactory("OBJECT_SIZE_OUT_OF_BOUNDS");
+    const result = await this.manager.upload(body, key, {
+      contentType: options.contentType,
+      metadata: options.metadata,
+      acl: "private"
+    });
+    return {
+      size: result.size
+    };
+  }
+};
+
 // src/index.ts
 var StorageProvider = /* @__PURE__ */ (function(StorageProvider2) {
   StorageProvider2["LOCAL"] = "LOCAL";
@@ -1020,16 +1212,22 @@ var StorageProvider = /* @__PURE__ */ (function(StorageProvider2) {
   return StorageProvider2;
 })({});
 export {
+  BufferedFileManagerStore,
   DANGEROUS_EXTENSIONS,
   FILE_MANAGER,
   FileLifecycleManager,
   LocalFileStorage,
   S3Storage,
   StorageProvider,
+  StorageTransferError,
+  UnavailableFileManager,
   WebDavStorage,
   ZuckerStorageModule,
   generateDateBasedKey,
+  hydrateStorageUrls,
   isFileDenied,
   isSafeOriginalFileName,
-  sanitizeFileName
+  sanitizeFileName,
+  transferVerifiedObject,
+  verifyStoredObject
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zucker-framework/storage",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",