npm - @warlock.js/core - Versions diffs - 5.6.0 → 5.8.0 - Mend

@warlock.js/core 5.6.0 → 5.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (94) hide show

package/esm/storage/scoped-storage.mjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"scoped-storage.mjs","names":["fs"],"sources":["../../../../../../../core/src/storage/scoped-storage.ts"],"sourcesContent":["import { fileExistsAsync } from \"@warlock.js/fs\";\nimport { createReadStream } from \"fs\";\nimport fs from \"fs/promises\";\nimport path from \"path\";\nimport type { Readable } from \"stream\";\nimport type { UploadedFile } from \"../http\";\nimport { StorageFile } from \"./storage-file\";\nimport type {\n DeleteManyResult,\n ListOptions,\n PutDirectoryOptions,\n PutDirectoryResult,\n PutFromUrlOptions,\n PutOptions,\n ScopedStorageContract,\n StorageDriverContract,\n StorageDriverType,\n StorageFileInfo,\n} from \"./types\";\nimport { safeFetchToBuffer } from \"./utils/safe-fetch\";\n\n/*\n ScopedStorage - Base class for storage operations\n \n Wraps a storage driver and provides a consistent, developer-friendly API\n * that returns `StorageFile` instances instead of raw data objects.\n \n This class serves as the base for both direct driver usage and the\n * full `Storage` manager class.\n \n @example\n * ```typescript\n * // Using via storage.use()\n * const s3Storage = storage.use(\"s3\");\n * const file = await s3Storage.put(buffer, \"images/photo.jpg\");\n \n // file is a StorageFile instance with rich API\n * console.log(file.name); // \"photo.jpg\"\n * console.log(file.url); // \"https://...\"\n * await file.copy(\"backup/photo.jpg\");\n * ```\n /\nexport class ScopedStorage implements ScopedStorageContract {\n /\n The underlying storage driver instance\n * @internal\n /\n protected _driver: StorageDriverContract;\n\n /\n Create a new ScopedStorage instance\n \n @param driver - The storage driver to wrap\n /\n public constructor(driver: StorageDriverContract) {\n this._driver = driver;\n }\n\n // ============================================================\n // Properties\n // ============================================================\n\n /\n Get the driver name\n \n @returns The name identifier of the underlying driver (e.g., \"local\", \"s3\", \"r2\")\n /\n public get name(): StorageDriverType {\n return this.activeDriver.name;\n }\n\n /\n Get the default driver instance\n \n Use this for advanced operations that require direct driver access.\n \n @returns The raw storage driver\n /\n public get defaultDriver(): StorageDriverContract {\n return this._driver;\n }\n\n /\n Get the currently active driver\n \n Returns the driver being used for storage operations.\n * Can be overridden in subclasses for dynamic driver resolution (e.g., multi-tenant contexts).\n \n @returns The active storage driver\n /\n public get activeDriver(): StorageDriverContract {\n return this._driver;\n }\n\n // ============================================================\n // File Operations\n // ============================================================\n\n /\n Store a file in storage\n \n Accepts multiple input types and stores the file at the specified location.\n * Returns a `StorageFile` instance for further operations.\n \n @param file - File content as Buffer, string path, UploadedFile, or Readable stream\n * @param location - Destination path in storage (e.g., \"uploads/images/photo.jpg\")\n * @param options - Optional storage options\n * @returns StorageFile instance with cached metadata\n \n @example\n * ```typescript\n * // From buffer\n * const file = await storage.put(buffer, \"documents/report.pdf\");\n \n // From uploaded file\n * const file = await storage.put(uploadedFile, \"avatars/user-123.jpg\");\n \n // With options\n * const file = await storage.put(buffer, \"images/photo.jpg\", {\n * mimeType: \"image/jpeg\",\n * cacheControl: \"max-age=31536000\"\n * });\n * ```\n /\n public async put(\n file: UploadedFile \| Buffer \| string \| Readable,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n const buffer = await this.toBuffer(file);\n const data = await this.activeDriver.put(buffer, location, options);\n return StorageFile.fromData(data, this.activeDriver);\n }\n\n /\n Store a file from a readable stream\n \n Optimized for large files - streams data directly without full buffering.\n * Ideal for file uploads, remote file fetching, or processing pipelines.\n \n @param stream - Readable stream of file content\n * @param location - Destination path in storage\n * @param options - Optional storage options\n * @returns StorageFile instance with cached metadata\n \n @example\n * ```typescript\n * import { createReadStream } from \"fs\";\n \n const stream = createReadStream(\"./large-video.mp4\");\n * const file = await storage.putStream(stream, \"videos/upload.mp4\");\n * ```\n /\n public async putStream(\n stream: Readable,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n const data = await this.activeDriver.putStream(stream, location, options);\n return StorageFile.fromData(data, this.activeDriver);\n }\n\n /\n Store a file from a URL\n \n Downloads the file from the URL and stores it. The download is\n * SSRF-guarded by default: the URL scheme must be https/http, the host\n * must not resolve to a private / loopback / link-local / cloud-metadata\n * address, the body is capped, and the request times out. Tune or relax\n * via the {@link PutFromUrlOptions} guard fields.\n \n @param url - URL to download from\n * @param location - Destination path in storage\n * @param options - Storage + outbound-download guard options\n * @returns StorageFile instance\n \n @example\n * ```typescript\n * const file = await storage.putFromUrl(\n * \"https://example.com/image.jpg\",\n * \"images/downloaded.jpg\"\n * );\n * ```\n /\n public async putFromUrl(\n url: string,\n location: string,\n options?: PutFromUrlOptions,\n ): Promise<StorageFile> {\n const { allowPrivateHosts, maxBytes, timeoutMs, allowedSchemes, ...putOptions } = options ?? {};\n\n const result = await safeFetchToBuffer(url, {\n allowPrivateHosts,\n maxBytes,\n timeoutMs,\n allowedSchemes,\n });\n\n if (!result.ok) {\n throw new Error(`Failed to fetch file from ${url}: ${result.statusText}`);\n }\n\n if (!result.contentType) {\n throw new Error(`Failed to fetch file from ${url}: missing content-type header`);\n }\n\n const mimeType = putOptions.mimeType \|\| result.contentType;\n\n return this.put(result.buffer, location, { ...putOptions, mimeType });\n }\n\n /\n Store a file from base64 data URL\n \n @param dataUrl - Data URL (data:image/png;base64,iVBORw0KG...)\n * @param location - Destination path in storage\n * @param options - Optional storage options\n * @returns StorageFile instance\n \n @example\n * ```typescript\n * const file = await storage.putFromBase64(\n * \"data:image/png;base64,iVBORw0KGgoAAAANS...\",\n * \"images/upload.png\"\n * );\n * ```\n /\n public async putFromBase64(\n dataUrl: string,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n // Parse data URL: data:image/png;base64,iVBORw0KG...\n const matches = dataUrl.match(/^data:([^;]+);base64,(.+)$/);\n\n if (!matches) {\n throw new Error(\"Invalid base64 data URL format. Expected: data:mime/type;base64,<data>\");\n }\n\n const [, mimeType, base64Data] = matches;\n const buffer = Buffer.from(base64Data, \"base64\");\n\n return this.put(buffer, location, {\n ...options,\n mimeType: options?.mimeType \|\| mimeType,\n });\n }\n\n /\n Retrieve file contents as a Buffer\n \n Downloads the entire file into memory. For large files,\n * consider using `getStream()` instead.\n \n @param location - Path to the file in storage\n * @returns Buffer containing file contents\n * @throws Error if file not found\n \n @example\n * ```typescript\n * const buffer = await storage.get(\"documents/report.pdf\");\n * const content = buffer.toString(\"utf-8\");\n * ```\n /\n public async get(location: string): Promise<Buffer> {\n return this.activeDriver.get(location);\n }\n\n /\n Retrieve file contents as a readable stream\n \n Streams file data without loading entire file into memory.\n * Ideal for large files or when piping to a response.\n \n @param location - Path to the file in storage\n * @returns Readable stream of file contents\n * @throws Error if file not found\n \n @example\n * ```typescript\n * const stream = await storage.getStream(\"videos/large.mp4\");\n * stream.pipe(response.raw);\n * ```\n /\n public async getStream(location: string): Promise<Readable> {\n return this.activeDriver.getStream(location);\n }\n\n /\n Delete a file from storage\n \n @param location - Path to the file, or a StorageFile instance\n * @returns `true` if deleted, `false` if file not found\n \n @example\n * ```typescript\n * // By path\n * await storage.delete(\"temp/old-file.txt\");\n \n // From StorageFile instance\n * const file = await storage.put(buffer, \"temp/file.txt\");\n * await storage.delete(file);\n * ```\n /\n public async delete(location: string \| StorageFile): Promise<boolean> {\n const path = typeof location === \"string\" ? location : location.path;\n return this.activeDriver.delete(path);\n }\n\n /\n Delete multiple files at once\n \n Performs batch deletion for efficiency. Returns results for each file\n * including success/failure status.\n \n @param locations - Array of file paths to delete\n * @returns Array of delete results with status for each file\n \n @example\n * ```typescript\n * const results = await storage.deleteMany([\n * \"temp/file1.txt\",\n * \"temp/file2.txt\",\n * \"temp/file3.txt\"\n * ]);\n \n for (const result of results) {\n * console.log(`${result.location}: ${result.deleted ? \"deleted\" : result.error}`);\n * }\n * ```\n /\n public async deleteMany(locations: string[]): Promise<DeleteManyResult[]> {\n return this.activeDriver.deleteMany(locations);\n }\n\n /\n Delete a directory\n \n @param directoryPath - Path to the directory\n /\n public async deleteDirectory(directoryPath: string): Promise<boolean> {\n return await this.activeDriver.deleteDirectory(directoryPath);\n }\n\n /\n Check if a file exists in storage\n \n @param location - Path to check\n * @returns `true` if file exists, `false` otherwise\n \n @example\n * ```typescript\n * if (await storage.exists(\"config/settings.json\")) {\n * const config = await storage.get(\"config/settings.json\");\n * }\n * ```\n /\n public async exists(location: string): Promise<boolean> {\n return this.activeDriver.exists(location);\n }\n\n /\n Copy a file to a new location\n \n Creates a copy of the file at the destination path.\n * The original file remains unchanged.\n \n @param from - Source path or StorageFile instance\n * @param to - Destination path\n * @returns StorageFile instance at the new location\n \n @example\n * ```typescript\n * // Copy by path\n * const backup = await storage.copy(\"documents/report.pdf\", \"backups/report.pdf\");\n \n // Copy from StorageFile\n * const original = await storage.file(\"documents/report.pdf\");\n * const backup = await storage.copy(original, \"backups/report.pdf\");\n * ```\n /\n public async copy(from: string \| StorageFile, to: string): Promise<StorageFile> {\n const fromPath = typeof from === \"string\" ? from : from.path;\n const data = await this.activeDriver.copy(fromPath, to);\n return StorageFile.fromData(data, this.activeDriver);\n }\n\n /\n Move a file to a new location\n \n Moves the file to the destination path. The original file\n * is deleted after successful copy.\n \n @param from - Source path or StorageFile instance\n * @param to - Destination path\n * @returns StorageFile instance at the new location\n \n @example\n * ```typescript\n * // Move by path\n * const file = await storage.move(\"uploads/temp.jpg\", \"images/photo.jpg\");\n \n // Move from StorageFile\n * const temp = await storage.file(\"uploads/temp.jpg\");\n * const final = await storage.move(temp, \"images/photo.jpg\");\n * ```\n /\n public async move(from: string \| StorageFile, to: string): Promise<StorageFile> {\n const fromPath = typeof from === \"string\" ? from : from.path;\n const data = await this.activeDriver.move(fromPath, to);\n return StorageFile.fromData(data, this.activeDriver);\n }\n\n /\n Copy an entire directory recursively\n \n Copies all files from the source directory to the destination directory,\n * preserving the directory structure.\n \n @param from - Source directory path\n * @param to - Destination directory path\n * @param options - Optional concurrency control\n * @returns Number of files copied\n \n @example\n * ```typescript\n * // Copy entire directory\n * const count = await storage.copyDirectory(\"uploads/temp\", \"uploads/final\");\n * console.log(`Copied ${count} files`);\n \n // With concurrency limit\n * const count = await storage.copyDirectory(\"large-dir\", \"backup\", {\n * concurrency: 10\n * });\n * ```\n /\n public async copyDirectory(\n from: string,\n to: string,\n options?: { concurrency?: number },\n ): Promise<number> {\n const concurrency = options?.concurrency \|\| 5;\n\n // List all files recursively\n const files = await this.list(from, { recursive: true });\n const filesToCopy = files.filter((f) => !f.isDirectory);\n\n // Copy files in batches for efficiency\n let copied = 0;\n for (let i = 0; i < filesToCopy.length; i += concurrency) {\n const batch = filesToCopy.slice(i, i + concurrency);\n await Promise.all(\n batch.map(async (file) => {\n // Calculate relative path and new destination\n const relativePath = file.path.substring(from.length).replace(/^\\//, \"\");\n const newPath = `${to}/${relativePath}`;\n await this.copy(file.path, newPath);\n copied++;\n }),\n );\n }\n\n return copied;\n }\n\n /\n Move an entire directory recursively\n \n Moves all files from the source directory to the destination directory,\n * then deletes the source directory.\n \n @param from - Source directory path\n * @param to - Destination directory path\n * @param options - Optional concurrency control\n * @returns Number of files moved\n \n @example\n * ```typescript\n * const count = await storage.moveDirectory(\"uploads/temp\", \"uploads/final\");\n * console.log(`Moved ${count} files`);\n * ```\n /\n public async moveDirectory(\n from: string,\n to: string,\n options?: { concurrency?: number },\n ): Promise<number> {\n // Copy all files first\n const count = await this.copyDirectory(from, to, options);\n\n // Delete source directory\n await this.deleteDirectory(from);\n\n return count;\n }\n\n /\n Upload a local filesystem directory into storage\n \n Recursively walks the local directory, applies an optional filter, then\n * streams each file into storage. Uploads run in concurrent batches for\n * efficiency. Failures are collected â€” a single failed file never aborts\n * the entire operation (mirrors the contract of `deleteMany`).\n \n @param localDirPath - Absolute path of the local directory to upload\n * @param destination - Target prefix in storage (e.g. \"uploads/assets\")\n * @param options - Concurrency, filter, progress callback, put options\n * @returns - { uploaded, failed, total }\n \n @example\n * ```typescript\n * const result = await storage.putDirectory(\"./public/assets\", \"cdn/assets\", {\n * concurrency: 10,\n * filter: (_, rel) => !rel.startsWith(\".\"),\n * onProgress: (done, total) => console.log(`${done}/${total}`),\n * });\n \n console.log(`Uploaded: ${result.uploaded.length}, Failed: ${result.failed.length}`);\n * ```\n /\n public async putDirectory(\n localDirPath: string,\n destination: string,\n options?: PutDirectoryOptions,\n ): Promise<PutDirectoryResult> {\n const concurrency = options?.concurrency ?? 5;\n\n // Collect all local file paths recursively\n const localFiles = await this.walkLocalDirectory(localDirPath);\n\n // Apply the user-supplied filter if any\n const filteredFiles = options?.filter\n ? localFiles.filter(({ absolute, relative }) => options.filter!(absolute, relative))\n : localFiles;\n\n const total = filteredFiles.length;\n const uploaded: StorageFile[] = [];\n const failed: Array<{ localPath: string; error: Error }> = [];\n let doneCount = 0;\n\n // Upload in concurrent batches\n for (let i = 0; i < filteredFiles.length; i += concurrency) {\n const batch = filteredFiles.slice(i, i + concurrency);\n\n await Promise.all(\n batch.map(async ({ absolute, relative }) => {\n const storagePath = `${destination.replace(/\\/$/, \"\")}/${relative}`;\n\n try {\n const stream = createReadStream(absolute);\n const file = await this.putStream(stream, storagePath, options?.putOptions);\n uploaded.push(file);\n doneCount++;\n options?.onProgress?.(doneCount, total, file);\n } catch (err) {\n failed.push({\n localPath: absolute,\n error: err instanceof Error ? err : new Error(String(err)),\n });\n }\n }),\n );\n }\n\n return { uploaded, failed, total };\n }\n\n /\n Walk a local directory recursively and return all file paths\n \n @param dirPath - Absolute local directory path\n * @returns Array of { absolute, relative } file path pairs\n * @internal\n /\n private async walkLocalDirectory(\n dirPath: string,\n baseDir?: string,\n ): Promise<Array<{ absolute: string; relative: string }>> {\n const root = baseDir ?? dirPath;\n const entries = await fs.readdir(dirPath, { withFileTypes: true });\n const results: Array<{ absolute: string; relative: string }> = [];\n\n for (const entry of entries) {\n const absolute = path.join(dirPath, entry.name);\n const relative = path.relative(root, absolute).replace(/\\\\/g, \"/\");\n\n if (entry.isDirectory()) {\n const nested = await this.walkLocalDirectory(absolute, root);\n results.push(...nested);\n } else if (entry.isFile()) {\n results.push({ absolute, relative });\n }\n // Symlinks are intentionally skipped\n }\n\n return results;\n }\n\n /\n Empty a directory without deleting the directory itself\n \n Deletes all files within the directory but preserves the directory structure.\n \n @param path - Directory path to empty\n * @returns Number of files deleted\n \n @example\n * ```typescript\n * const count = await storage.emptyDirectory(\"uploads/temp\");\n * console.log(`Deleted ${count} files`);\n * ```\n /\n public async emptyDirectory(path: string): Promise<number> {\n // List all files in directory\n const files = await this.list(path, { recursive: true });\n const filePaths = files.filter((f) => !f.isDirectory).map((f) => f.path);\n\n if (filePaths.length === 0) {\n return 0;\n }\n\n // Delete all files\n await this.deleteMany(filePaths);\n\n return filePaths.length;\n }\n\n /\n List files in a directory\n \n Returns file information for all files in the specified directory.\n * Supports recursive listing and pagination.\n \n @param directory - Directory path (defaults to root)\n * @param options - List options (recursive, limit, cursor)\n * @returns Array of file information objects\n \n @example\n * ```typescript\n * // List all files in uploads\n * const files = await storage.list(\"uploads\");\n \n // Recursive listing with limit\n * const files = await storage.list(\"uploads\", {\n * recursive: true,\n * limit: 100\n * });\n * ```\n /\n public async list(directory?: string, options?: ListOptions): Promise<StorageFileInfo[]> {\n return this.activeDriver.list(directory \|\| \"\", options);\n }\n\n // ============================================================\n // URL Operations\n // ============================================================\n\n /\n Get the public URL for a file\n \n Returns the URL where the file can be accessed. For local storage,\n * this is typically a path prefix. For cloud storage, this is the\n * bucket URL or CDN URL.\n \n @param location - File path\n * @returns Public URL string\n \n @example\n * ```typescript\n * const url = storage.url(\"images/photo.jpg\");\n * // Local: \"/uploads/images/photo.jpg\"\n * // S3: \"https://bucket.s3.amazonaws.com/images/photo.jpg\"\n * ```\n /\n public url(location: string): string {\n return this.activeDriver.url(location);\n }\n\n /\n Get a temporary signed URL with expiration\n \n Creates a URL that provides temporary access to the file.\n * For cloud storage, this uses presigned URLs.\n * For local storage, this uses HMAC-signed tokens.\n \n @param location - File path\n * @param expiresIn - Seconds until URL expires (default: 3600)\n * @returns Signed URL string\n \n @example\n * ```typescript\n * // URL valid for 1 hour\n * const url = await storage.temporaryUrl(\"private/document.pdf\");\n \n // URL valid for 24 hours\n * const url = await storage.temporaryUrl(\"private/document.pdf\", 86400);\n * ```\n /\n public async temporaryUrl(location: string, expiresIn?: number): Promise<string> {\n return this.activeDriver.temporaryUrl(location, expiresIn);\n }\n\n // ============================================================\n // Metadata Operations\n // ============================================================\n\n /\n Get file metadata without downloading the file\n \n Retrieves information about a file including size, last modified date,\n * and MIME type without downloading the file contents.\n \n @param location - File path\n * @returns File information object\n * @throws Error if file not found\n \n @example\n * ```typescript\n * const info = await storage.metadata(\"documents/report.pdf\");\n * console.log(`Size: ${info.size} bytes`);\n * console.log(`Type: ${info.mimeType}`);\n * console.log(`Modified: ${info.lastModified}`);\n * ```\n /\n public async metadata(location: string): Promise<StorageFileInfo> {\n return this.activeDriver.metadata(location);\n }\n\n /\n Get file size in bytes\n \n Shortcut for `metadata(location).size`.\n \n @param location - File path\n * @returns File size in bytes\n * @throws Error if file not found\n /\n public async size(location: string): Promise<number> {\n return this.activeDriver.size(location);\n }\n\n /\n Get a StorageFile instance for OOP-style operations\n \n Creates a `StorageFile` wrapper for the specified path,\n * allowing fluent method chaining for file operations.\n \n @param location - File path\n * @returns StorageFile instance\n \n @example\n * ```typescript\n * const file = await storage.file(\"uploads/image.jpg\");\n \n // Properties\n * console.log(file.name); // \"image.jpg\"\n * console.log(file.extension); // \"jpg\"\n \n // Operations\n * await file.copy(\"backup/image.jpg\");\n * await file.delete();\n * ```\n /\n public file(location: string): StorageFile {\n return new StorageFile(location, this.activeDriver);\n }\n\n // ============================================================\n // Utilities\n // ============================================================\n\n /\n Convert various input types to Buffer\n \n @param file - Input file in various formats\n * @returns Buffer containing file contents\n * @internal\n /\n protected async toBuffer(file: UploadedFile \| Buffer \| string \| Readable): Promise<Buffer> {\n // Already a buffer\n if (Buffer.isBuffer(file)) {\n return file;\n }\n\n // Readable stream - collect into buffer\n if (this.isReadable(file)) {\n return this.streamToBuffer(file as Readable);\n }\n\n // String content\n if (typeof file === \"string\") {\n if (await fileExistsAsync(file)) {\n return fs.readFile(file);\n }\n\n return Buffer.from(file);\n }\n\n // UploadedFile\n return (file as UploadedFile).buffer();\n }\n\n /\n Check if value is a Readable stream\n \n @param value - Value to check\n * @returns True if value is a Readable stream\n * @internal\n /\n protected isReadable(value: unknown): value is Readable {\n return (\n typeof value === \"object\" &&\n value !== null &&\n \"pipe\" in value &&\n typeof (value as Readable).pipe === \"function\"\n );\n }\n\n /\n Convert a Readable stream to Buffer\n \n @param stream - Readable stream\n * @returns Buffer containing stream contents\n * @internal\n /\n protected async streamToBuffer(stream: Readable): Promise<Buffer> {\n const chunks: Buffer[] = [];\n for await (const chunk of stream) {\n chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));\n }\n return Buffer.concat(chunks as unknown as Uint8Array[]);\n }\n\n /\n Prepend a prefix to a location path\n \n Useful for organizing files into directories.\n \n @param prefix - Prefix to add (e.g., \"uploads\")\n * @param location - Original location path\n * @returns Combined path with prefix\n \n @example\n * ```typescript\n * storage.prepend(\"uploads\", \"image.jpg\"); // \"uploads/image.jpg\"\n * storage.prepend(\"uploads/\", \"/image.jpg\"); // \"uploads/image.jpg\"\n * ```\n /\n public prepend(prefix: string, location: string): string {\n return `${prefix.replace(/\\/$/, \"\")}/${location.replace(/^\\//, \"\")}`;\n }\n\n /\n Append a suffix to a location path (before extension)\n \n Useful for creating variants of files (thumbnails, etc.).\n \n @param location - Original location path\n * @param suffix - Suffix to add before extension\n * @returns Path with suffix added before extension\n \n @example\n * ```typescript\n * storage.append(\"image.jpg\", \"_thumb\"); // \"image_thumb.jpg\"\n * storage.append(\"document.pdf\", \"_v2\"); // \"document_v2.pdf\"\n * ```\n */\n public append(location: string, suffix: string): string {\n const lastDot = location.lastIndexOf(\".\");\n if (lastDot === -1) {\n return `${location}${suffix}`;\n }\n return `${location.substring(0, lastDot)}${suffix}${location.substring(lastDot)}`;\n }\n}\n"],"mappings":"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"}
1	+ {"version":3,"file":"scoped-storage.mjs","names":["fs"],"sources":["../../../../../../../core/src/storage/scoped-storage.ts"],"sourcesContent":["import { fileExistsAsync } from \"@warlock.js/fs\";\nimport { createReadStream } from \"fs\";\nimport fs from \"fs/promises\";\nimport path from \"path\";\nimport type { Readable } from \"stream\";\nimport type { UploadedFile } from \"../http\";\nimport { StorageFile } from \"./storage-file\";\nimport type {\n DeleteManyResult,\n ListOptions,\n PutDirectoryOptions,\n PutDirectoryResult,\n PutFromUrlOptions,\n PutOptions,\n ScopedStorageContract,\n StorageDriverContract,\n StorageDriverType,\n StorageFileInfo,\n} from \"./types\";\nimport { safeFetchToBuffer } from \"./utils/safe-fetch\";\n\n/*\n ScopedStorage - Base class for storage operations\n \n Wraps a storage driver and provides a consistent, developer-friendly API\n * that returns `StorageFile` instances instead of raw data objects.\n \n This class serves as the base for both direct driver usage and the\n * full `Storage` manager class.\n \n @example\n * ```typescript\n * // Using via storage.use()\n * const s3Storage = storage.use(\"s3\");\n * const file = await s3Storage.put(buffer, \"images/photo.jpg\");\n \n // file is a StorageFile instance with rich API\n * console.log(file.name); // \"photo.jpg\"\n * console.log(file.url); // \"https://...\"\n * await file.copy(\"backup/photo.jpg\");\n * ```\n /\nexport class ScopedStorage implements ScopedStorageContract {\n /\n The underlying storage driver instance\n * @internal\n /\n protected _driver: StorageDriverContract;\n\n /\n Create a new ScopedStorage instance\n \n @param driver - The storage driver to wrap\n /\n public constructor(driver: StorageDriverContract) {\n this._driver = driver;\n }\n\n // ============================================================\n // Properties\n // ============================================================\n\n /\n Get the driver name\n \n @returns The name identifier of the underlying driver (e.g., \"local\", \"s3\", \"r2\")\n /\n public get name(): StorageDriverType {\n return this.activeDriver.name;\n }\n\n /\n Get the default driver instance\n \n Use this for advanced operations that require direct driver access.\n \n @returns The raw storage driver\n /\n public get defaultDriver(): StorageDriverContract {\n return this._driver;\n }\n\n /\n Get the currently active driver\n \n Returns the driver being used for storage operations.\n * Can be overridden in subclasses for dynamic driver resolution (e.g., multi-tenant contexts).\n \n @returns The active storage driver\n /\n public get activeDriver(): StorageDriverContract {\n return this._driver;\n }\n\n // ============================================================\n // File Operations\n // ============================================================\n\n /\n Store a file in storage\n \n Accepts multiple input types and stores the file at the specified location.\n * Returns a `StorageFile` instance for further operations.\n \n @param file - File content as Buffer, string path, UploadedFile, or Readable stream\n * @param location - Destination path in storage (e.g., \"uploads/images/photo.jpg\")\n * @param options - Optional storage options\n * @returns StorageFile instance with cached metadata\n \n @example\n * ```typescript\n * // From buffer\n * const file = await storage.put(buffer, \"documents/report.pdf\");\n \n // From uploaded file\n * const file = await storage.put(uploadedFile, \"avatars/user-123.jpg\");\n \n // With options\n * const file = await storage.put(buffer, \"images/photo.jpg\", {\n * mimeType: \"image/jpeg\",\n * cacheControl: \"max-age=31536000\"\n * });\n * ```\n /\n public async put(\n file: UploadedFile \| Buffer \| string \| Readable,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n const buffer = await this.toBuffer(file);\n const data = await this.activeDriver.put(buffer, location, options);\n return StorageFile.fromData(data, this.activeDriver);\n }\n\n /\n Store a file from a readable stream\n \n Optimized for large files - streams data directly without full buffering.\n * Ideal for file uploads, remote file fetching, or processing pipelines.\n \n @param stream - Readable stream of file content\n * @param location - Destination path in storage\n * @param options - Optional storage options\n * @returns StorageFile instance with cached metadata\n \n @example\n * ```typescript\n * import { createReadStream } from \"fs\";\n \n const stream = createReadStream(\"./large-video.mp4\");\n * const file = await storage.putStream(stream, \"videos/upload.mp4\");\n * ```\n /\n public async putStream(\n stream: Readable,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n const data = await this.activeDriver.putStream(stream, location, options);\n return StorageFile.fromData(data, this.activeDriver);\n }\n\n /\n Store a file from a URL\n \n Downloads the file from the URL and stores it. The download is\n * SSRF-guarded by default: the URL scheme must be https/http, the host\n * must not resolve to a private / loopback / link-local / cloud-metadata\n * address, the body is capped, and the request times out. Tune or relax\n * via the {@link PutFromUrlOptions} guard fields.\n \n @param url - URL to download from\n * @param location - Destination path in storage\n * @param options - Storage + outbound-download guard options\n * @returns StorageFile instance\n \n @example\n * ```typescript\n * const file = await storage.putFromUrl(\n * \"https://example.com/image.jpg\",\n * \"images/downloaded.jpg\"\n * );\n * ```\n /\n public async putFromUrl(\n url: string,\n location: string,\n options?: PutFromUrlOptions,\n ): Promise<StorageFile> {\n const { allowPrivateHosts, maxBytes, timeoutMs, allowedSchemes, ...putOptions } = options ?? {};\n\n const result = await safeFetchToBuffer(url, {\n allowPrivateHosts,\n maxBytes,\n timeoutMs,\n allowedSchemes,\n });\n\n if (!result.ok) {\n throw new Error(`Failed to fetch file from ${url}: ${result.statusText}`);\n }\n\n if (!result.contentType) {\n throw new Error(`Failed to fetch file from ${url}: missing content-type header`);\n }\n\n const mimeType = putOptions.mimeType \|\| result.contentType;\n\n return this.put(result.buffer, location, { ...putOptions, mimeType });\n }\n\n /\n Store a file from base64 data URL\n \n @param dataUrl - Data URL (data:image/png;base64,iVBORw0KG...)\n * @param location - Destination path in storage\n * @param options - Optional storage options\n * @returns StorageFile instance\n \n @example\n * ```typescript\n * const file = await storage.putFromBase64(\n * \"data:image/png;base64,iVBORw0KGgoAAAANS...\",\n * \"images/upload.png\"\n * );\n * ```\n /\n public async putFromBase64(\n dataUrl: string,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n // Parse data URL: data:image/png;base64,iVBORw0KG...\n const matches = dataUrl.match(/^data:([^;]+);base64,(.+)$/);\n\n if (!matches) {\n throw new Error(\"Invalid base64 data URL format. Expected: data:mime/type;base64,<data>\");\n }\n\n const [, mimeType, base64Data] = matches;\n\n if (mimeType === undefined \|\| base64Data === undefined) {\n throw new Error(\"Invalid base64 data URL format. Expected: data:mime/type;base64,<data>\");\n }\n\n const buffer = Buffer.from(base64Data, \"base64\");\n\n return this.put(buffer, location, {\n ...options,\n mimeType: options?.mimeType \|\| mimeType,\n });\n }\n\n /\n Retrieve file contents as a Buffer\n \n Downloads the entire file into memory. For large files,\n * consider using `getStream()` instead.\n \n @param location - Path to the file in storage\n * @returns Buffer containing file contents\n * @throws Error if file not found\n \n @example\n * ```typescript\n * const buffer = await storage.get(\"documents/report.pdf\");\n * const content = buffer.toString(\"utf-8\");\n * ```\n /\n public async get(location: string): Promise<Buffer> {\n return this.activeDriver.get(location);\n }\n\n /\n Retrieve file contents as a readable stream\n \n Streams file data without loading entire file into memory.\n * Ideal for large files or when piping to a response.\n \n @param location - Path to the file in storage\n * @returns Readable stream of file contents\n * @throws Error if file not found\n \n @example\n * ```typescript\n * const stream = await storage.getStream(\"videos/large.mp4\");\n * stream.pipe(response.raw);\n * ```\n /\n public async getStream(location: string): Promise<Readable> {\n return this.activeDriver.getStream(location);\n }\n\n /\n Delete a file from storage\n \n @param location - Path to the file, or a StorageFile instance\n * @returns `true` if deleted, `false` if file not found\n \n @example\n * ```typescript\n * // By path\n * await storage.delete(\"temp/old-file.txt\");\n \n // From StorageFile instance\n * const file = await storage.put(buffer, \"temp/file.txt\");\n * await storage.delete(file);\n * ```\n /\n public async delete(location: string \| StorageFile): Promise<boolean> {\n const path = typeof location === \"string\" ? location : location.path;\n return this.activeDriver.delete(path);\n }\n\n /\n Delete multiple files at once\n \n Performs batch deletion for efficiency. Returns results for each file\n * including success/failure status.\n \n @param locations - Array of file paths to delete\n * @returns Array of delete results with status for each file\n \n @example\n * ```typescript\n * const results = await storage.deleteMany([\n * \"temp/file1.txt\",\n * \"temp/file2.txt\",\n * \"temp/file3.txt\"\n * ]);\n \n for (const result of results) {\n * console.log(`${result.location}: ${result.deleted ? \"deleted\" : result.error}`);\n * }\n * ```\n /\n public async deleteMany(locations: string[]): Promise<DeleteManyResult[]> {\n return this.activeDriver.deleteMany(locations);\n }\n\n /\n Delete a directory\n \n @param directoryPath - Path to the directory\n /\n public async deleteDirectory(directoryPath: string): Promise<boolean> {\n return await this.activeDriver.deleteDirectory(directoryPath);\n }\n\n /\n Check if a file exists in storage\n \n @param location - Path to check\n * @returns `true` if file exists, `false` otherwise\n \n @example\n * ```typescript\n * if (await storage.exists(\"config/settings.json\")) {\n * const config = await storage.get(\"config/settings.json\");\n * }\n * ```\n /\n public async exists(location: string): Promise<boolean> {\n return this.activeDriver.exists(location);\n }\n\n /\n Copy a file to a new location\n \n Creates a copy of the file at the destination path.\n * The original file remains unchanged.\n \n @param from - Source path or StorageFile instance\n * @param to - Destination path\n * @returns StorageFile instance at the new location\n \n @example\n * ```typescript\n * // Copy by path\n * const backup = await storage.copy(\"documents/report.pdf\", \"backups/report.pdf\");\n \n // Copy from StorageFile\n * const original = await storage.file(\"documents/report.pdf\");\n * const backup = await storage.copy(original, \"backups/report.pdf\");\n * ```\n /\n public async copy(from: string \| StorageFile, to: string): Promise<StorageFile> {\n const fromPath = typeof from === \"string\" ? from : from.path;\n const data = await this.activeDriver.copy(fromPath, to);\n return StorageFile.fromData(data, this.activeDriver);\n }\n\n /\n Move a file to a new location\n \n Moves the file to the destination path. The original file\n * is deleted after successful copy.\n \n @param from - Source path or StorageFile instance\n * @param to - Destination path\n * @returns StorageFile instance at the new location\n \n @example\n * ```typescript\n * // Move by path\n * const file = await storage.move(\"uploads/temp.jpg\", \"images/photo.jpg\");\n \n // Move from StorageFile\n * const temp = await storage.file(\"uploads/temp.jpg\");\n * const final = await storage.move(temp, \"images/photo.jpg\");\n * ```\n /\n public async move(from: string \| StorageFile, to: string): Promise<StorageFile> {\n const fromPath = typeof from === \"string\" ? from : from.path;\n const data = await this.activeDriver.move(fromPath, to);\n return StorageFile.fromData(data, this.activeDriver);\n }\n\n /\n Copy an entire directory recursively\n \n Copies all files from the source directory to the destination directory,\n * preserving the directory structure.\n \n @param from - Source directory path\n * @param to - Destination directory path\n * @param options - Optional concurrency control\n * @returns Number of files copied\n \n @example\n * ```typescript\n * // Copy entire directory\n * const count = await storage.copyDirectory(\"uploads/temp\", \"uploads/final\");\n * console.log(`Copied ${count} files`);\n \n // With concurrency limit\n * const count = await storage.copyDirectory(\"large-dir\", \"backup\", {\n * concurrency: 10\n * });\n * ```\n /\n public async copyDirectory(\n from: string,\n to: string,\n options?: { concurrency?: number },\n ): Promise<number> {\n const concurrency = options?.concurrency \|\| 5;\n\n // List all files recursively\n const files = await this.list(from, { recursive: true });\n const filesToCopy = files.filter((f) => !f.isDirectory);\n\n // Copy files in batches for efficiency\n let copied = 0;\n for (let i = 0; i < filesToCopy.length; i += concurrency) {\n const batch = filesToCopy.slice(i, i + concurrency);\n await Promise.all(\n batch.map(async (file) => {\n // Calculate relative path and new destination\n const relativePath = file.path.substring(from.length).replace(/^\\//, \"\");\n const newPath = `${to}/${relativePath}`;\n await this.copy(file.path, newPath);\n copied++;\n }),\n );\n }\n\n return copied;\n }\n\n /\n Move an entire directory recursively\n \n Moves all files from the source directory to the destination directory,\n * then deletes the source directory.\n \n @param from - Source directory path\n * @param to - Destination directory path\n * @param options - Optional concurrency control\n * @returns Number of files moved\n \n @example\n * ```typescript\n * const count = await storage.moveDirectory(\"uploads/temp\", \"uploads/final\");\n * console.log(`Moved ${count} files`);\n * ```\n /\n public async moveDirectory(\n from: string,\n to: string,\n options?: { concurrency?: number },\n ): Promise<number> {\n // Copy all files first\n const count = await this.copyDirectory(from, to, options);\n\n // Delete source directory\n await this.deleteDirectory(from);\n\n return count;\n }\n\n /\n Upload a local filesystem directory into storage\n \n Recursively walks the local directory, applies an optional filter, then\n * streams each file into storage. Uploads run in concurrent batches for\n * efficiency. Failures are collected â€” a single failed file never aborts\n * the entire operation (mirrors the contract of `deleteMany`).\n \n @param localDirPath - Absolute path of the local directory to upload\n * @param destination - Target prefix in storage (e.g. \"uploads/assets\")\n * @param options - Concurrency, filter, progress callback, put options\n * @returns - { uploaded, failed, total }\n \n @example\n * ```typescript\n * const result = await storage.putDirectory(\"./public/assets\", \"cdn/assets\", {\n * concurrency: 10,\n * filter: (_, rel) => !rel.startsWith(\".\"),\n * onProgress: (done, total) => console.log(`${done}/${total}`),\n * });\n \n console.log(`Uploaded: ${result.uploaded.length}, Failed: ${result.failed.length}`);\n * ```\n /\n public async putDirectory(\n localDirPath: string,\n destination: string,\n options?: PutDirectoryOptions,\n ): Promise<PutDirectoryResult> {\n const concurrency = options?.concurrency ?? 5;\n\n // Collect all local file paths recursively\n const localFiles = await this.walkLocalDirectory(localDirPath);\n\n // Apply the user-supplied filter if any\n const filteredFiles = options?.filter\n ? localFiles.filter(({ absolute, relative }) => options.filter!(absolute, relative))\n : localFiles;\n\n const total = filteredFiles.length;\n const uploaded: StorageFile[] = [];\n const failed: Array<{ localPath: string; error: Error }> = [];\n let doneCount = 0;\n\n // Upload in concurrent batches\n for (let i = 0; i < filteredFiles.length; i += concurrency) {\n const batch = filteredFiles.slice(i, i + concurrency);\n\n await Promise.all(\n batch.map(async ({ absolute, relative }) => {\n const storagePath = `${destination.replace(/\\/$/, \"\")}/${relative}`;\n\n try {\n const stream = createReadStream(absolute);\n const file = await this.putStream(stream, storagePath, options?.putOptions);\n uploaded.push(file);\n doneCount++;\n options?.onProgress?.(doneCount, total, file);\n } catch (err) {\n failed.push({\n localPath: absolute,\n error: err instanceof Error ? err : new Error(String(err)),\n });\n }\n }),\n );\n }\n\n return { uploaded, failed, total };\n }\n\n /\n Walk a local directory recursively and return all file paths\n \n @param dirPath - Absolute local directory path\n * @returns Array of { absolute, relative } file path pairs\n * @internal\n /\n private async walkLocalDirectory(\n dirPath: string,\n baseDir?: string,\n ): Promise<Array<{ absolute: string; relative: string }>> {\n const root = baseDir ?? dirPath;\n const entries = await fs.readdir(dirPath, { withFileTypes: true });\n const results: Array<{ absolute: string; relative: string }> = [];\n\n for (const entry of entries) {\n const absolute = path.join(dirPath, entry.name);\n const relative = path.relative(root, absolute).replace(/\\\\/g, \"/\");\n\n if (entry.isDirectory()) {\n const nested = await this.walkLocalDirectory(absolute, root);\n results.push(...nested);\n } else if (entry.isFile()) {\n results.push({ absolute, relative });\n }\n // Symlinks are intentionally skipped\n }\n\n return results;\n }\n\n /\n Empty a directory without deleting the directory itself\n \n Deletes all files within the directory but preserves the directory structure.\n \n @param path - Directory path to empty\n * @returns Number of files deleted\n \n @example\n * ```typescript\n * const count = await storage.emptyDirectory(\"uploads/temp\");\n * console.log(`Deleted ${count} files`);\n * ```\n /\n public async emptyDirectory(path: string): Promise<number> {\n // List all files in directory\n const files = await this.list(path, { recursive: true });\n const filePaths = files.filter((f) => !f.isDirectory).map((f) => f.path);\n\n if (filePaths.length === 0) {\n return 0;\n }\n\n // Delete all files\n await this.deleteMany(filePaths);\n\n return filePaths.length;\n }\n\n /\n List files in a directory\n \n Returns file information for all files in the specified directory.\n * Supports recursive listing and pagination.\n \n @param directory - Directory path (defaults to root)\n * @param options - List options (recursive, limit, cursor)\n * @returns Array of file information objects\n \n @example\n * ```typescript\n * // List all files in uploads\n * const files = await storage.list(\"uploads\");\n \n // Recursive listing with limit\n * const files = await storage.list(\"uploads\", {\n * recursive: true,\n * limit: 100\n * });\n * ```\n /\n public async list(directory?: string, options?: ListOptions): Promise<StorageFileInfo[]> {\n return this.activeDriver.list(directory \|\| \"\", options);\n }\n\n // ============================================================\n // URL Operations\n // ============================================================\n\n /\n Get the public URL for a file\n \n Returns the URL where the file can be accessed. For local storage,\n * this is typically a path prefix. For cloud storage, this is the\n * bucket URL or CDN URL.\n \n @param location - File path\n * @returns Public URL string\n \n @example\n * ```typescript\n * const url = storage.url(\"images/photo.jpg\");\n * // Local: \"/uploads/images/photo.jpg\"\n * // S3: \"https://bucket.s3.amazonaws.com/images/photo.jpg\"\n * ```\n /\n public url(location: string): string {\n return this.activeDriver.url(location);\n }\n\n /\n Get a temporary signed URL with expiration\n \n Creates a URL that provides temporary access to the file.\n * For cloud storage, this uses presigned URLs.\n * For local storage, this uses HMAC-signed tokens.\n \n @param location - File path\n * @param expiresIn - Seconds until URL expires (default: 3600)\n * @returns Signed URL string\n \n @example\n * ```typescript\n * // URL valid for 1 hour\n * const url = await storage.temporaryUrl(\"private/document.pdf\");\n \n // URL valid for 24 hours\n * const url = await storage.temporaryUrl(\"private/document.pdf\", 86400);\n * ```\n /\n public async temporaryUrl(location: string, expiresIn?: number): Promise<string> {\n return this.activeDriver.temporaryUrl(location, expiresIn);\n }\n\n // ============================================================\n // Metadata Operations\n // ============================================================\n\n /\n Get file metadata without downloading the file\n \n Retrieves information about a file including size, last modified date,\n * and MIME type without downloading the file contents.\n \n @param location - File path\n * @returns File information object\n * @throws Error if file not found\n \n @example\n * ```typescript\n * const info = await storage.metadata(\"documents/report.pdf\");\n * console.log(`Size: ${info.size} bytes`);\n * console.log(`Type: ${info.mimeType}`);\n * console.log(`Modified: ${info.lastModified}`);\n * ```\n /\n public async metadata(location: string): Promise<StorageFileInfo> {\n return this.activeDriver.metadata(location);\n }\n\n /\n Get file size in bytes\n \n Shortcut for `metadata(location).size`.\n \n @param location - File path\n * @returns File size in bytes\n * @throws Error if file not found\n /\n public async size(location: string): Promise<number> {\n return this.activeDriver.size(location);\n }\n\n /\n Get a StorageFile instance for OOP-style operations\n \n Creates a `StorageFile` wrapper for the specified path,\n * allowing fluent method chaining for file operations.\n \n @param location - File path\n * @returns StorageFile instance\n \n @example\n * ```typescript\n * const file = await storage.file(\"uploads/image.jpg\");\n \n // Properties\n * console.log(file.name); // \"image.jpg\"\n * console.log(file.extension); // \"jpg\"\n \n // Operations\n * await file.copy(\"backup/image.jpg\");\n * await file.delete();\n * ```\n /\n public file(location: string): StorageFile {\n return new StorageFile(location, this.activeDriver);\n }\n\n // ============================================================\n // Utilities\n // ============================================================\n\n /\n Convert various input types to Buffer\n \n @param file - Input file in various formats\n * @returns Buffer containing file contents\n * @internal\n /\n protected async toBuffer(file: UploadedFile \| Buffer \| string \| Readable): Promise<Buffer> {\n // Already a buffer\n if (Buffer.isBuffer(file)) {\n return file;\n }\n\n // Readable stream - collect into buffer\n if (this.isReadable(file)) {\n return this.streamToBuffer(file as Readable);\n }\n\n // String content\n if (typeof file === \"string\") {\n if (await fileExistsAsync(file)) {\n return fs.readFile(file);\n }\n\n return Buffer.from(file);\n }\n\n // UploadedFile\n return (file as UploadedFile).buffer();\n }\n\n /\n Check if value is a Readable stream\n \n @param value - Value to check\n * @returns True if value is a Readable stream\n * @internal\n /\n protected isReadable(value: unknown): value is Readable {\n return (\n typeof value === \"object\" &&\n value !== null &&\n \"pipe\" in value &&\n typeof (value as Readable).pipe === \"function\"\n );\n }\n\n /\n Convert a Readable stream to Buffer\n \n @param stream - Readable stream\n * @returns Buffer containing stream contents\n * @internal\n /\n protected async streamToBuffer(stream: Readable): Promise<Buffer> {\n const chunks: Buffer[] = [];\n for await (const chunk of stream) {\n chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));\n }\n return Buffer.concat(chunks as unknown as Uint8Array[]);\n }\n\n /\n Prepend a prefix to a location path\n \n Useful for organizing files into directories.\n \n @param prefix - Prefix to add (e.g., \"uploads\")\n * @param location - Original location path\n * @returns Combined path with prefix\n \n @example\n * ```typescript\n * storage.prepend(\"uploads\", \"image.jpg\"); // \"uploads/image.jpg\"\n * storage.prepend(\"uploads/\", \"/image.jpg\"); // \"uploads/image.jpg\"\n * ```\n /\n public prepend(prefix: string, location: string): string {\n return `${prefix.replace(/\\/$/, \"\")}/${location.replace(/^\\//, \"\")}`;\n }\n\n /\n Append a suffix to a location path (before extension)\n \n Useful for creating variants of files (thumbnails, etc.).\n \n @param location - Original location path\n * @param suffix - Suffix to add before extension\n * @returns Path with suffix added before extension\n \n @example\n * ```typescript\n * storage.append(\"image.jpg\", \"_thumb\"); // \"image_thumb.jpg\"\n * storage.append(\"document.pdf\", \"_v2\"); // \"document_v2.pdf\"\n * ```\n */\n public append(location: string, suffix: string): string {\n const lastDot = location.lastIndexOf(\".\");\n if (lastDot === -1) {\n return `${location}${suffix}`;\n }\n return `${location.substring(0, lastDot)}${suffix}${location.substring(lastDot)}`;\n }\n}\n"],"mappings":"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"}

package/esm/storage/storage.d.mts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"storage.d.mts","names":[],"sources":["../../../../../../../core/src/storage/storage.ts"],"mappings":";;;;;;;;;;;AAiFA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,OAAA,SAAgB,aAAA,YAAyB,sBAAA;EAgWjD;;;;EAAA,UA3VO,OAAA,EAAO,GAAA,SAAA,qBAAA;EAwbL;;;;EAAA,UAlbF,OAAA,EAAO,GAAA,SAAA,mBAAA;EAoed;;;;EAAA,UA9dO,iBAAA,EAAoB,iBAAA;~~EAmhBqB~~;;;;EAAA,~~QA7gB3C~~,WAAA;~~EA8jBwC~~;;;;;;EAgDoB;;;;;~~EA7lBvD~~,IAAA,IAAQ,OAAA;~~EAypByB~~;;;~~EAroBvC~~,KAAA;~~EAutBK~~;;;;;;;;EAAA,~~IAvsBQ~~,YAAA,IAAgB,qBAAA;~~EAwzBsC~~;;;;EAAA,~~UAvyBhE~~,qBAAA;~~EAg2BqB~~;;;;;;;;;;;;;;;EAAA,~~UAv0BrB~~,0BAAA;EA3GO;;;;;;;;;;;;;;;;;;;;;;EA2IV,GAAA,CAAI,IAAA,EAAM,iBAAA,GAAoB,qBAAA;EA+C9B;;;;;;;;;;;;;;;;;EA1BA,SAAA,CAAU,IAAA,EAAM,iBAAA,GAAoB,qBAAA;EAgGuB;;;EAzF3D,IAAA,CAAK,YAAA;EAuH8B;;;;;;;;;;;;;EApGnC,QAAA,CAAS,IAAA,EAAM,iBAAA,GAAoB,0BAAA;EAgIxC;;;;;;;;;;;;;;;;;;;;;;;EA/FK,QAAA,CAAS,IAAA,EAAM,iBAAA,EAAmB,MAAA,EAAQ,mBAAA;EAsN/C;;;;;;;;;;;;EApMK,UAAA,CAAW,IAAA,EAAM,iBAAA;~~EA+QE~~;;;;;~~EApQb~~,OAAA,IAAW,OAAA;~~EAiSF~~;;;;EAAA,~~UAzRZ~~,aAAA,CAAc,MAAA,EAAQ,qBAAA,GAAwB,MAAA,IAAU,0BAAA;~~EAqSlB~~;;;;;;;;;;;;;;;;;;;;;;~~EAvQzC~~,EAAA,WAAa,mBAAA,GAAsB,mBAAA,EACxC,KAAA,EAAO,gBAAA,EACP,OAAA,EAAS,mBAAA,CAAoB,CAAA,IAC5B,iBAAA;~~EA2XD~~;;;;;;;;;;;~~EA5WK~~,GAAA,CAAI,KAAA,EAAO,gBAAA;~~EAuZL~~;;;;EAAA,~~UA9YG~~,IAAA,WAAe,mBAAA,EAC7B,KAAA,EAAO,gBAAA,EACP,OAAA,EAAS,CAAA,GACR,OAAA;~~EA0asD~~;;;;;;;;;;~~EArZnC~~,GAAA,CACpB,IAAA,EAAM,YAAA,GAAe,MAAA,YAAkB,QAAA,EACvC,QAAA,UACA,OAAA,GAAU,UAAA,GACT,OAAA,CAAQ,WAAA;~~EAwde~~;;;;;;;;;;~~EAnbJ~~,SAAA,CACpB,MAAA,EAAQ,QAAA,WACR,QAAA,UACA,OAAA,GAAU,UAAA,GACT,OAAA,CAAQ,WAAA;~~EAwegB~~;;;;;;;;;;;;;;;;;;;;;;;;~~EAvbd~~,UAAA,CACX,GAAA,UACA,QAAA,UACA,OAAA,GAAU,iBAAA,GACT,OAAA,CAAQ,WAAA;~~EAwnB6B~~;;;AAAyB;AAwBnE;;;;AAAoC;;;;;;;;;;;;;;~~EAnmBrB~~,aAAA,CACX,MAAA,UACA,QAAA,UACA,OAAA,GAAU,UAAA,GACT,OAAA,CAAQ,WAAA;;;;;;;;;~~EAwBW~~,GAAA,CAAI,QAAA,WAAmB,OAAA,CAAQ,MAAA;;;;;;;;;;;;;;;EAkBxC,OAAA,CAAQ,QAAA,WAAmB,OAAA;;;;;;;EAWlB,SAAA,CAAU,QAAA,WAAmB,OAAA,CAAQ,QAAA;;;;;;;;;EAYrC,MAAA,CAAO,QAAA,WAAmB,WAAA,GAAc,OAAA;;;;;;;EA2BxC,UAAA,CAAW,SAAA,aAAsB,OAAA,CAAQ,gBAAA;;;;;;;EAUzC,MAAA,CAAO,QAAA,WAAmB,OAAA;;;;;;;;;;EAa1B,IAAA,CAAK,IAAA,WAAe,WAAA,EAAa,EAAA,WAAa,OAAA,CAAQ,WAAA;;;;;;;;;;EAmCtD,IAAA,CAAK,IAAA,WAAe,WAAA,EAAa,EAAA,WAAa,OAAA,CAAQ,WAAA;;;;;;;;EAiCtD,IAAA,CACpB,SAAA,WACA,OAAA,GAAU,WAAA,GACT,OAAA,CAAQ,eAAA;;;;;;;EAcW,QAAA,CAAS,QAAA,WAAmB,OAAA,CAAQ,eAAA;;;;;;;EAUpC,IAAA,CAAK,QAAA,WAAmB,OAAA;;;;;;;;;;EAiBjC,IAAA,CAAK,QAAA,WAAmB,OAAA;;;;;;;;;;;;;;;;;;EA+BxB,eAAA,CAAgB,QAAA,UAAkB,OAAA,GAAU,gBAAA,GAAmB,OAAA;;;;;;;;;;;;;;;;;;;;;;;EAgC/D,qBAAA,CACX,QAAA,UACA,OAAA,GAAU,sBAAA,GACT,OAAA;;;;;;;;;EAkBU,SAAA,IAAa,OAAA;;;;;;;;;EAkBb,SAAA,IAAa,OAAA;;;;;;;;;;EAmBb,eAAA,CAAgB,QAAA,UAAkB,YAAA,WAAuB,OAAA;;;;;;;;;;EAmBzD,aAAA,CAAc,QAAA,UAAkB,UAAA,EAAY,cAAA,GAAiB,OAAA;;;;;;;;;;EAmB7D,aAAA,CAAc,QAAA,WAAmB,OAAA,CAAQ,cAAA;;;;;;;;;;EAmBhC,YAAA,CAAa,QAAA,UAAkB,SAAA,YAAqB,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+B7D,sBAAA,CAAuB,KAAA,WAAgB,OAAA,CAAQ,wBAAA;;;;;YAwBlD,YAAA,CACR,MAAA,EAAQ,mBAAA,GACP,yBAAA,GAA4B,yBAAA,GAA4B,sBAAA;;;;;YA8DjD,mBAAA,CAAoB,MAAA,EAAQ,mBAAA,EAAqB,UAAA;;;;;YAkBjD,aAAA,CAAc,IAAA,WAAe,qBAAA;;;;;YAyCvB,oBAAA,IAAwB,OAAA,CAAQ,iBAAA;AAAA;;;;;;;;;;;;;cAwBrC,OAAA,EAAO,OAAgB"}
1	+ {"version":3,"file":"storage.d.mts","names":[],"sources":["../../../../../../../core/src/storage/storage.ts"],"mappings":"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"}

package/esm/storage/storage.mjs CHANGED Viewed

@@ -432,8 +432,12 @@ var Storage = class extends ScopedStorage {
 		if (base64.startsWith("data:")) {
 			const match = base64.match(/^data:([^;]+);base64,(.+)$/);
 			if (match) {
-				mimeType = mimeType || match[1];
-				data = match[2];
+				const matchedMimeType = match[1];
+				const matchedData = match[2];
+				if (matchedMimeType !== void 0 && matchedData !== void 0) {
+					mimeType = mimeType || matchedMimeType;
+					data = matchedData;
+				}
 			}
 		}
 		const buffer = Buffer.from(data, "base64");

package/esm/storage/storage.mjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"storage.mjs","names":[],"sources":["../../../../../../../core/src/storage/storage.ts"],"sourcesContent":["import events, { type EventSubscription } from \"@mongez/events\";\nimport fs from \"fs\";\nimport path from \"path\";\nimport type { Readable } from \"stream\";\nimport type { UploadedFile } from \"../http\";\nimport { uploadsPath } from \"../utils/paths\";\nimport { storageConfig, storageConfigurations } from \"./config\";\nimport { storageDriverContext } from \"./context/storage-driver-context\";\nimport { DOSpacesDriver } from \"./drivers/do-spaces-driver\";\nimport { LocalDriver } from \"./drivers/local-driver\";\nimport { R2Driver } from \"./drivers/r2-driver\";\nimport { S3Driver } from \"./drivers/s3-driver\";\nimport { ScopedStorage } from \"./scoped-storage\";\nimport { StorageFile } from \"./storage-file\";\nimport { safeFetchToBuffer } from \"./utils/safe-fetch\";\nimport type {\n CloudStorageDriverContract,\n CloudStorageDriverOptions,\n DeleteManyResult,\n FileVisibility,\n ListOptions,\n LocalStorageDriverOptions,\n PresignedOptions,\n PresignedUploadOptions,\n PutFromUrlOptions,\n PutOptions,\n R2StorageDriverOptions,\n ScopedStorageContract,\n StorageCopyEventPayload,\n StorageDriverConfig,\n StorageDriverContract,\n StorageDriverName,\n StorageEventHandler,\n StorageEventPayload,\n StorageEventType,\n StorageFileInfo,\n StorageManagerContract,\n StoragePutEventPayload,\n TemporaryTokenValidation,\n} from \"./types\";\n\n/*\n Storage Manager\n \n Provides a unified interface for file storage operations across multiple\n * drivers (local, S3, R2, DigitalOcean Spaces). Extends `ScopedStorage` to\n * inherit all base operations while adding driver management and events.\n \n All operations return `StorageFile` instances for a consistent, rich DX.\n \n @example\n * ```typescript\n * // Basic usage (uses default driver)\n * const file = await storage.put(buffer, \"uploads/image.jpg\");\n \n // With options\n * const file = await storage.put(buffer, \"uploads/image.jpg\", {\n * mimeType: \"image/jpeg\",\n * cacheControl: \"max-age=31536000\"\n * });\n \n // Using specific driver (also returns StorageFile)\n * const file = await storage.use(\"s3\").put(buffer, \"path/to/file\");\n \n // Get raw driver for advanced use\n * const driver = storage.driver(\"s3\");\n * const data = await driver.put(buffer, \"path/to/file\"); // Returns StorageFileData\n \n // Stream operations for large files\n * const stream = await storage.getStream(\"large-file.zip\");\n * await storage.putStream(readableStream, \"output/file.zip\");\n \n // Batch operations\n * const results = await storage.deleteMany([\"file1.txt\", \"file2.txt\"]);\n \n // Event hooks\n * storage.on(\"afterPut\", ({ location, file }) => {\n * console.log(`Uploaded ${location}`);\n * });\n * ```\n /\nexport class Storage extends ScopedStorage implements StorageManagerContract {\n /\n Registered drivers (cached instances)\n * @internal\n /\n protected drivers = new Map<string, StorageDriverContract>();\n\n /\n Driver configurations\n * @internal\n /\n protected configs = new Map<string, StorageDriverConfig>();\n\n /\n Default driver name\n * @internal\n /\n protected defaultDriverName!: StorageDriverName;\n\n /\n Whether the storage has been initialized\n * @internal\n /\n private initialized = false;\n\n /\n Create a new Storage manager instance\n \n Uses lazy initialization - driver is resolved on first access.\n /\n public constructor() {\n // Temp placeholder - will be replaced on first access\n super(null as unknown as StorageDriverContract);\n }\n\n /\n Ensure storage is initialized (lazy initialization)\n \n Called automatically on first driver access.\n /\n public async init(): Promise<void> {\n if (this.initialized) return;\n\n // Mark as initialized FIRST to prevent infinite recursion\n this.initialized = true;\n\n // Get default driver name from config\n\n const defaultName = storageConfig(\"default\", \"local\");\n\n this.defaultDriverName = defaultName as StorageDriverName;\n this.loadDriversFromConfig();\n\n // Now set the actual driver\n this._driver = this.resolveDriver(this.defaultDriverName);\n }\n\n /\n Reset storage defaults\n /\n public reset(): void {\n this.initialized = false;\n this.drivers.clear();\n this.configs.clear();\n this.defaultDriverName = null as unknown as StorageDriverName;\n this._driver = null as unknown as StorageDriverContract;\n }\n\n /\n Get the currently active driver (context-aware in future)\n \n Currently returns the default driver.\n * Will be enhanced to check AsyncLocalStorage context for multi-tenant support.\n \n @returns The active storage driver\n /\n public override get activeDriver(): StorageDriverContract {\n // Check context for tenant-specific driver\n const contextDriver = storageDriverContext.getDriver();\n\n if (contextDriver) return contextDriver;\n\n return this._driver;\n }\n\n // ============================================================\n // Driver Management\n // ============================================================\n\n /\n Load drivers from configuration\n * @internal\n /\n protected loadDriversFromConfig(): void {\n this.registerBuiltInLocalDriver();\n\n const drivers = storageConfig<Record<string, StorageDriverConfig>>(\"drivers\", {});\n\n for (const [name, config] of Object.entries(drivers)) {\n this.configs.set(name, config);\n }\n }\n\n /\n Register the built-in `local` driver, rooted at `uploadsPath()`.\n \n The storage connector starts unconditionally — unlike database, cache and\n * herald, it does not early-return when `config.get(\"storage\")` is absent —\n * on the stated grounds that `init()` falls back to a built-in local driver so\n * file storage works out of the box. That fallback did not exist: `init()`\n * resolved the default driver name and then found no config registered\n * under it, so any app without `src/config/storage.ts` failed to boot\n * with `Storage driver \"local\" is not configured`. Only scaffolded apps, which\n * always ship that file, hid it.\n \n Registered before the configured drivers so an app that defines its own\n * `local` entry overrides this one rather than fighting it.\n /\n protected registerBuiltInLocalDriver(): void {\n this.configs.set(\n \"local\",\n storageConfigurations.local({\n root: uploadsPath(),\n urlPrefix: \"/uploads\",\n }),\n );\n }\n\n /\n Get a scoped storage for a specific driver\n \n Returns a `ScopedStorage` instance that wraps the specified driver.\n * Operations on the returned instance also return `StorageFile` objects.\n \n @param name - Driver name as defined in configuration\n * @returns ScopedStorage instance for the specified driver\n \n @example\n * ```typescript\n * // Upload to S3\n * const s3File = await storage.use(\"s3\").put(buffer, \"images/photo.jpg\");\n \n // Upload to local\n * const localFile = await storage.use(\"local\").put(buffer, \"temp/file.txt\");\n \n // Both return StorageFile with identical API\n * console.log(s3File.url);\n * console.log(localFile.url);\n * ```\n /\n public use(name: StorageDriverName): ScopedStorageContract {\n return new ScopedStorage(this.getDriver(name));\n }\n\n /\n Get a raw driver instance\n \n Returns the underlying driver directly for advanced use cases.\n * Unlike `use()`, calling methods on the raw driver returns\n * `StorageFileData` instead of `StorageFile`.\n \n @param name - Driver name as defined in configuration\n * @returns Raw driver instance implementing StorageDriverContract\n \n @example\n * ```typescript\n * const driver = storage.getDriver(\"s3\");\n * const data = await driver.put(buffer, \"path/to/file\");\n * // data is StorageFileData, not StorageFile\n * ```\n /\n public getDriver(name: StorageDriverName): StorageDriverContract {\n return this.resolveDriver(name);\n }\n\n /\n Get root directory of current driver\n /\n public root(apepndedPath?: string): string {\n const rootPath = this.activeDriver.options?.root \|\| \"\";\n\n return path.join(rootPath, apepndedPath \|\| \"\");\n }\n\n /\n Use a cloud storage driver with extended cloud capabilities\n \n @param name - Cloud driver name (s3, r2, spaces)\n * @returns Driver instance implementing CloudStorageDriverContract\n * @throws Error if driver doesn't support cloud operations\n \n @example\n * ```typescript\n * const cloudDriver = storage.useCloud(\"s3\");\n * const presignedUrl = await cloudDriver.getPresignedUrl(\"private/doc.pdf\");\n * ```\n /\n public useCloud(name: StorageDriverName): CloudStorageDriverContract {\n const instance = this.getDriver(name);\n\n if (!this.isCloudDriver(instance)) {\n throw new Error(`Driver \"${name}\" does not support cloud operations`);\n }\n\n return instance as CloudStorageDriverContract;\n }\n\n /\n Register a new driver configuration at runtime\n \n Allows dynamic driver registration for multi-tenancy or\n * runtime configuration scenarios.\n \n @param name - Unique driver name\n * @param config - Driver configuration\n * @returns This instance for chaining\n \n @example\n * ```typescript\n * storage.register(\"tenant-s3\", {\n * driver: \"s3\",\n * bucket: \"tenant-bucket\",\n * region: \"us-east-1\",\n * accessKeyId: process.env.TENANT_AWS_KEY,\n * secretAccessKey: process.env.TENANT_AWS_SECRET\n * });\n \n await storage.use(\"tenant-s3\").put(buffer, \"file.txt\");\n * ```\n /\n public register(name: StorageDriverName, config: StorageDriverConfig): this {\n this.configs.set(name, config);\n this.drivers.delete(name); // Clear cached instance\n return this;\n }\n\n /\n Set the default driver name\n \n @param name - Driver name to use as default\n * @returns This instance for chaining\n \n @example\n * ```typescript\n * storage.setDefault(\"s3\");\n * await storage.put(buffer, \"file.txt\"); // Now uses S3\n * ```\n /\n public setDefault(name: StorageDriverName): this {\n this.defaultDriverName = name;\n this._driver = this.getDriver(name);\n return this;\n }\n\n /\n Check if current driver is a cloud driver\n \n @returns Promise resolving to true if the current driver supports cloud operations\n /\n public async isCloud(): Promise<boolean> {\n return this.isCloudDriver(this.activeDriver);\n }\n\n /\n Check if a driver instance supports cloud operations\n * @internal\n /\n protected isCloudDriver(driver: StorageDriverContract): driver is CloudStorageDriverContract {\n return \"getPresignedUrl\" in driver;\n }\n\n // ============================================================\n // Event System\n // ============================================================\n\n /\n Register an event handler\n \n Subscribe to storage events for logging, analytics, or side effects.\n \n @param event - Event type to listen for\n * @param handler - Handler function\n * @returns Event subscription for unsubscribing\n \n @example\n * ```typescript\n * // Log all uploads\n * storage.on(\"afterPut\", ({ location, file }) => {\n * console.log(`Uploaded ${file?.size} bytes to ${location}`);\n * });\n \n // Track deletions\n * storage.on(\"afterDelete\", ({ location }) => {\n * analytics.track(\"file_deleted\", { path: location });\n * });\n * ```\n /\n public on<T extends StorageEventPayload = StorageEventPayload>(\n event: StorageEventType,\n handler: StorageEventHandler<T>,\n ): EventSubscription {\n return events.subscribe(`storage.${event}`, handler);\n }\n\n /\n Remove all handlers for an event type\n \n @param event - Event type to remove handlers for\n * @returns This instance for chaining\n \n @example\n * ```typescript\n * storage.off(\"afterPut\"); // Remove all afterPut handlers\n * ```\n /\n public off(event: StorageEventType): this {\n events.off(`storage.${event}`);\n return this;\n }\n\n /\n Emit an event to all registered handlers\n * @internal\n /\n protected async emit<T extends StorageEventPayload>(\n event: StorageEventType,\n payload: T,\n ): Promise<void> {\n // `triggerAll` is synchronous — it never awaits its handlers, so awaiting it\n // would make async listeners fire-and-forget. `triggerAllAsync` takes the\n // same `(event, ...args)` shape and awaits each handler in turn.\n await events.triggerAllAsync(`storage.${event}`, payload);\n }\n\n // ============================================================\n // Overridden Operations with Events\n // ============================================================\n\n /\n Store a file in storage\n \n Extends base `put()` with event emission for beforePut/afterPut hooks.\n \n @param file - File content as Buffer, string, UploadedFile, or Readable stream\n * @param location - Destination path\n * @param options - Storage options (mimeType, cacheControl, etc.)\n * @returns StorageFile instance with cached metadata\n /\n public override async put(\n file: UploadedFile \| Buffer \| string \| Readable,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n const driver = this.activeDriver;\n const buffer = await this.toBuffer(file);\n\n await this.emit<StoragePutEventPayload>(\"beforePut\", {\n driver: driver.name,\n location,\n timestamp: new Date(),\n size: buffer.length,\n });\n\n const result = await driver.put(buffer, location, options);\n\n await this.emit<StoragePutEventPayload>(\"afterPut\", {\n driver: driver.name,\n location,\n timestamp: new Date(),\n file: result,\n });\n\n if (!result.size) {\n result.size = buffer.length;\n }\n\n return StorageFile.fromData(result, driver);\n }\n\n /\n Store a file from a readable stream (for large files)\n \n Extends base `putStream()` with event emission.\n \n @param stream - Readable stream\n * @param location - Destination path\n * @param options - Storage options\n * @returns StorageFile instance with cached metadata\n /\n public override async putStream(\n stream: Readable \| string,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n const driver = this.activeDriver;\n\n await this.emit<StoragePutEventPayload>(\"beforePut\", {\n driver: driver.name,\n location,\n timestamp: new Date(),\n });\n\n if (typeof stream === \"string\") {\n stream = fs.createReadStream(stream);\n }\n\n const result = await driver.putStream(stream, location, options);\n\n await this.emit<StoragePutEventPayload>(\"afterPut\", {\n driver: driver.name,\n location,\n timestamp: new Date(),\n file: result,\n });\n\n return StorageFile.fromData(result, driver);\n }\n\n /\n Store a file from a URL\n \n Downloads content from the URL and stores it at the specified location.\n \n The download is SSRF-guarded by default: the URL scheme must be\n * https/http, the host must not resolve to a private / loopback /\n * link-local / cloud-metadata address, the body is capped, and the\n * request times out. Tune or relax via the {@link PutFromUrlOptions}\n * guard fields.\n \n @param url - Source URL to download from\n * @param location - Destination path\n * @param options - Storage + outbound-download guard options\n * @returns StorageFile instance with cached metadata\n \n @example\n * ```typescript\n * const file = await storage.putFromUrl(\n * \"https://example.com/image.jpg\",\n * \"downloads/image.jpg\"\n * );\n * ```\n /\n public async putFromUrl(\n url: string,\n location: string,\n options?: PutFromUrlOptions,\n ): Promise<StorageFile> {\n const { allowPrivateHosts, maxBytes, timeoutMs, allowedSchemes, ...putOptions } = options ?? {};\n\n const result = await safeFetchToBuffer(url, {\n allowPrivateHosts,\n maxBytes,\n timeoutMs,\n allowedSchemes,\n });\n\n if (!result.ok) {\n throw new Error(`Failed to fetch file from URL: ${result.statusText}`);\n }\n\n if (!result.contentType) {\n throw new Error(`Failed to fetch file from URL: missing content-type header`);\n }\n\n const mimeType = putOptions.mimeType \|\| result.contentType;\n\n return this.put(result.buffer, location, { ...putOptions, mimeType });\n }\n\n /\n Store a file from base64 encoded string\n \n Decodes base64 content (with optional data URL prefix) and stores it.\n \n @param base64 - Base64 encoded file content (or data URL)\n * @param location - Destination path\n * @param options - Storage options\n * @returns StorageFile instance with cached metadata\n \n @example\n * ```typescript\n * // From plain base64\n * const file = await storage.putFromBase64(base64String, \"images/photo.jpg\");\n \n // From data URL (auto-extracts MIME type)\n * const file = await storage.putFromBase64(\n * \"data:image/png;base64,iVBORw0KGgo...\",\n * \"images/photo.png\"\n * );\n * ```\n /\n public async putFromBase64(\n base64: string,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n let data = base64;\n let mimeType = options?.mimeType;\n\n if (base64.startsWith(\"data:\")) {\n const match = base64.match(/^data:([^;]+);base64,(.+)$/);\n if (match) {\n mimeType = mimeType \|\| match[1];\n data = match[2];\n }\n }\n\n const buffer = Buffer.from(data, \"base64\");\n return this.put(buffer, location, { ...options, mimeType });\n }\n\n /\n Retrieve file contents as Buffer\n \n Uses the current driver (with async resolution).\n \n @param location - File path\n * @returns Buffer containing file contents\n /\n public override async get(location: string): Promise<Buffer> {\n return this.activeDriver.get(location);\n }\n\n /\n Get JSON content from a file\n \n Downloads and parses JSON file content.\n \n @param location - File path\n * @returns Parsed JSON content\n \n @example\n * ```typescript\n * const config = await storage.getJson(\"config/settings.json\");\n * console.log(config.apiKey);\n * ```\n /\n public async getJson(location: string): Promise<any> {\n const buffer = await this.get(location);\n return JSON.parse(buffer.toString());\n }\n\n /\n Retrieve a file as a readable stream (for large files)\n \n @param location - File path\n * @returns Readable stream of file contents\n /\n public override async getStream(location: string): Promise<Readable> {\n return this.activeDriver.getStream(location);\n }\n\n /\n Delete a file\n \n Extends base `delete()` with event emission.\n \n @param location - File path or StorageFile\n * @returns true if deleted, false if not found\n /\n public override async delete(location: string \| StorageFile): Promise<boolean> {\n const driver = this.activeDriver;\n const path = typeof location === \"string\" ? location : location.path;\n\n await this.emit<StorageEventPayload>(\"beforeDelete\", {\n driver: driver.name,\n location: path,\n timestamp: new Date(),\n });\n\n const result = await driver.delete(path);\n\n await this.emit<StorageEventPayload>(\"afterDelete\", {\n driver: driver.name,\n location: path,\n timestamp: new Date(),\n });\n\n return result;\n }\n\n /\n Delete multiple files at once\n \n @param locations - Array of file paths\n * @returns Array of delete results with status for each file\n /\n public override async deleteMany(locations: string[]): Promise<DeleteManyResult[]> {\n return this.activeDriver.deleteMany(locations);\n }\n\n /\n Check if a file exists\n \n @param location - File path\n * @returns true if file exists\n /\n public override async exists(location: string): Promise<boolean> {\n return this.activeDriver.exists(location);\n }\n\n /\n Copy a file to a new location\n \n Extends base `copy()` with event emission.\n \n @param from - Source path or StorageFile\n * @param to - Destination path\n * @returns StorageFile instance at destination\n /\n public override async copy(from: string \| StorageFile, to: string): Promise<StorageFile> {\n const driver = this.activeDriver;\n const fromPath = typeof from === \"string\" ? from : from.path;\n\n await this.emit<StorageCopyEventPayload>(\"beforeCopy\", {\n driver: driver.name,\n location: to,\n from: fromPath,\n to,\n timestamp: new Date(),\n });\n\n const result = await driver.copy(fromPath, to);\n\n await this.emit<StorageCopyEventPayload>(\"afterCopy\", {\n driver: driver.name,\n location: to,\n from: fromPath,\n to,\n timestamp: new Date(),\n file: result,\n });\n\n return StorageFile.fromData(result, driver);\n }\n\n /\n Move a file to a new location\n \n Extends base `move()` with event emission.\n \n @param from - Source path or StorageFile\n * @param to - Destination path\n * @returns StorageFile instance at destination\n /\n public override async move(from: string \| StorageFile, to: string): Promise<StorageFile> {\n const driver = this.activeDriver;\n const fromPath = typeof from === \"string\" ? from : from.path;\n\n await this.emit<StorageCopyEventPayload>(\"beforeMove\", {\n driver: driver.name,\n location: to,\n from: fromPath,\n to,\n timestamp: new Date(),\n });\n\n const result = await driver.move(fromPath, to);\n\n await this.emit<StorageCopyEventPayload>(\"afterMove\", {\n driver: driver.name,\n location: to,\n from: fromPath,\n to,\n timestamp: new Date(),\n file: result,\n });\n\n return StorageFile.fromData(result, driver);\n }\n\n /\n List files in a directory\n \n @param directory - Directory path (defaults to root)\n * @param options - List options (recursive, limit, etc.)\n * @returns Array of file information objects\n /\n public override async list(\n directory?: string,\n options?: ListOptions,\n ): Promise<StorageFileInfo[]> {\n return this.activeDriver.list(directory \|\| \"\", options);\n }\n\n // ============================================================\n // Metadata Operations\n // ============================================================\n\n /\n Get file metadata without downloading\n \n @param location - File path\n * @returns File information object\n /\n public override async metadata(location: string): Promise<StorageFileInfo> {\n return this.activeDriver.metadata(location);\n }\n\n /\n Get file size in bytes\n \n @param location - File path\n * @returns File size in bytes\n /\n public override async size(location: string): Promise<number> {\n return this.activeDriver.size(location);\n }\n\n // ============================================================\n // Path Operations (Local Driver Only)\n // ============================================================\n\n /\n Get the absolute filesystem path for a location\n \n Only available for local driver.\n \n @param location - File path\n * @throws Error if current driver is not a local driver\n * @returns Absolute filesystem path\n /\n public async path(location: string): Promise<string> {\n const driver = this.activeDriver;\n\n if (!(\"path\" in driver) \|\| typeof driver.path !== \"function\") {\n throw new Error(\"path() is only available for local storage drivers\");\n }\n\n return driver.path(location);\n }\n\n // ============================================================\n // Cloud-Specific Operations\n // ============================================================\n\n /\n Get a presigned URL for downloading a file\n \n Only available for cloud drivers.\n \n @param location - File path\n * @param options - Presigned URL options (expiresIn)\n * @throws Error if current driver is not a cloud driver\n * @returns Presigned download URL\n \n @example\n * ```typescript\n * const url = await storage.getPresignedUrl(\"private/document.pdf\", {\n * expiresIn: 3600 // 1 hour\n * });\n * ```\n /\n public async getPresignedUrl(location: string, options?: PresignedOptions): Promise<string> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Presigned URLs are only available for cloud storage drivers\");\n }\n\n return driver.getPresignedUrl(location, options);\n }\n\n /\n Get a presigned URL for uploading a file directly to cloud storage\n \n Only available for cloud drivers.\n \n @param location - Destination path\n * @param options - Upload options (expiresIn, contentType, metadata).\n * There is no size cap: a presigned PUT URL cannot enforce one — verify\n * the uploaded size server-side or use a presigned POST policy instead.\n * @throws Error if current driver is not a cloud driver\n * @returns Presigned upload URL\n \n @example\n * ```typescript\n * const uploadUrl = await storage.getPresignedUploadUrl(\"uploads/file.pdf\", {\n * expiresIn: 3600,\n * contentType: \"application/pdf\"\n * });\n \n // Client can PUT directly to this URL\n * ```\n /\n public async getPresignedUploadUrl(\n location: string,\n options?: PresignedUploadOptions,\n ): Promise<string> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Presigned upload URLs are only available for cloud storage drivers\");\n }\n\n return driver.getPresignedUploadUrl(location, options);\n }\n\n /\n Get the bucket name for cloud storage\n \n Only available for cloud drivers.\n \n @throws Error if current driver is not a cloud driver\n * @returns Bucket name\n /\n public async getBucket(): Promise<string> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Bucket information is only available for cloud storage drivers\");\n }\n\n return driver.getBucket();\n }\n\n /\n Get the region for cloud storage\n \n Only available for cloud drivers.\n \n @throws Error if current driver is not a cloud driver\n * @returns Region name\n /\n public async getRegion(): Promise<string> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Region information is only available for cloud storage drivers\");\n }\n\n return driver.getRegion();\n }\n\n /\n Set storage class for a file (e.g., STANDARD, GLACIER, etc.)\n \n Only available for cloud drivers.\n \n @param location - File path\n * @param storageClass - Target storage class\n * @throws Error if current driver is not a cloud driver\n /\n public async setStorageClass(location: string, storageClass: string): Promise<void> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Storage class is only available for cloud storage drivers\");\n }\n\n return driver.setStorageClass(location, storageClass);\n }\n\n /\n Set file visibility (public or private)\n \n Only available for cloud drivers.\n \n @param location - File path\n * @param visibility - \"public\" or \"private\"\n * @throws Error if current driver is not a cloud driver\n /\n public async setVisibility(location: string, visibility: FileVisibility): Promise<void> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Visibility is only available for cloud storage drivers\");\n }\n\n return driver.setVisibility(location, visibility);\n }\n\n /\n Get file visibility\n \n Only available for cloud drivers.\n \n @param location - File path\n * @throws Error if current driver is not a cloud driver\n * @returns Current visibility setting\n /\n public async getVisibility(location: string): Promise<FileVisibility> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Visibility is only available for cloud storage drivers\");\n }\n\n return driver.getVisibility(location);\n }\n\n /\n Get a temporary signed URL\n \n Creates a URL that provides temporary access to the file.\n \n @param location - File path\n * @param expiresIn - Seconds until expiration (default: 3600)\n * @returns Signed URL string\n /\n public override async temporaryUrl(location: string, expiresIn?: number): Promise<string> {\n return this.activeDriver.temporaryUrl(location, expiresIn);\n }\n\n /\n Validate a temporary URL token\n \n For local driver: validates HMAC-signed tokens\n * For cloud drivers: returns invalid (cloud validates via presigned URL)\n \n @param token - The token from the temporary URL\n * @returns Validation result with file info and convenience methods\n \n @example\n * ```typescript\n * const result = await storage.validateTemporaryToken(token);\n \n if (!result.valid) {\n * return response.status(403).send(result.error);\n * }\n \n // For local driver - use sendFile for efficiency\n * if (result.absolutePath) {\n * return response.sendFile(result.absolutePath);\n * }\n \n // For cloud driver - stream the file\n * const stream = await result.getStream!();\n * stream.pipe(response.raw);\n * ```\n /\n public async validateTemporaryToken(token: string): Promise<TemporaryTokenValidation> {\n // Check if driver supports token validation\n if (\n !(\"validateTemporaryToken\" in this.activeDriver) \|\|\n typeof this.activeDriver.validateTemporaryToken !== \"function\"\n ) {\n // For cloud drivers, temporary URLs are presigned and validated by the cloud provider\n return {\n valid: false,\n error: \"invalid_token\",\n };\n }\n\n return this.activeDriver.validateTemporaryToken(token);\n }\n\n // ============================================================\n // Configuration Parsing\n // ============================================================\n\n /\n Parse config into driver-specific options\n * @internal\n /\n protected parseOptions(\n config: StorageDriverConfig,\n ): LocalStorageDriverOptions \| CloudStorageDriverOptions \| R2StorageDriverOptions {\n const { driver, ...options } = config;\n\n switch (driver) {\n case \"local\":\n return {\n root: options.root,\n urlPrefix: options.urlPrefix,\n signatureKey: options.signatureKey,\n } satisfies LocalStorageDriverOptions;\n\n case \"s3\":\n this.validateCloudConfig(config, \"s3\");\n return {\n ...options,\n bucket: options.bucket!,\n region: options.region!,\n accessKeyId: options.accessKeyId!,\n secretAccessKey: options.secretAccessKey!,\n endpoint: options.endpoint,\n urlPrefix: options.urlPrefix,\n } satisfies CloudStorageDriverOptions;\n\n case \"r2\":\n this.validateCloudConfig(config, \"r2\");\n if (!options.accountId) {\n throw new Error('R2 driver requires \"accountId\" configuration');\n }\n\n return {\n ...options,\n region: options.region \|\| \"auto\",\n bucket: options.bucket!,\n accessKeyId: options.accessKeyId!,\n secretAccessKey: options.secretAccessKey!,\n endpoint: options.endpoint,\n urlPrefix: options.urlPrefix,\n accountId: options.accountId,\n publicDomain: options.publicDomain,\n } satisfies R2StorageDriverOptions;\n\n case \"spaces\":\n this.validateCloudConfig(config, \"spaces\");\n return {\n ...options,\n bucket: options.bucket!,\n region: options.region!,\n accessKeyId: options.accessKeyId!,\n secretAccessKey: options.secretAccessKey!,\n endpoint: options.endpoint,\n urlPrefix: options.urlPrefix,\n } satisfies CloudStorageDriverOptions;\n\n default:\n throw new Error(`Unknown driver type: ${driver}`);\n }\n }\n\n /\n Validate cloud driver configuration has required fields\n * @internal\n /\n protected validateCloudConfig(config: StorageDriverConfig, driverName: string): void {\n const required = [\"bucket\", \"accessKeyId\", \"secretAccessKey\"];\n\n if (driverName !== \"r2\") {\n required.push(\"region\");\n }\n\n for (const field of required) {\n if (!config[field as keyof StorageDriverConfig]) {\n throw new Error(`${driverName.toUpperCase()} driver requires \"${field}\" configuration`);\n }\n }\n }\n\n /\n Get or create driver instance from cache\n * @internal\n /\n protected resolveDriver(name: string): StorageDriverContract {\n // Ensure configs are loaded\n\n if (this.drivers.has(name)) {\n return this.drivers.get(name)!;\n }\n\n const config = this.configs.get(name);\n\n if (!config) {\n throw new Error(`Storage driver \"${name}\" is not configured`);\n }\n\n const options = this.parseOptions(config);\n let driver: StorageDriverContract;\n\n switch (config.driver) {\n case \"local\":\n driver = new LocalDriver(options as LocalStorageDriverOptions);\n break;\n case \"s3\":\n driver = new S3Driver(options as CloudStorageDriverOptions);\n break;\n case \"r2\":\n driver = new R2Driver(options as R2StorageDriverOptions);\n break;\n case \"spaces\":\n driver = new DOSpacesDriver(options as CloudStorageDriverOptions);\n break;\n default:\n throw new Error(`Unknown storage driver type: ${config.driver}`);\n }\n\n this.drivers.set(name, driver);\n return driver;\n }\n\n /\n Resolve the default driver name (supports async resolver for multi-tenancy)\n * @internal\n /\n protected async resolveDefaultDriver(): Promise<StorageDriverName> {\n const resolver = storageConfig(\"resolver\");\n\n if (resolver) {\n const resolved = await resolver();\n return resolved \|\| this.defaultDriverName;\n }\n\n return this.defaultDriverName;\n }\n}\n\n/\n Singleton storage instance\n \n Pre-configured storage manager ready for use throughout the application.\n \n @example\n * ```typescript\n * import { storage } from \"@warlock.js/core\";\n \n const file = await storage.put(buffer, \"uploads/file.txt\");\n * ```\n */\nexport const storage = new Storage();\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiFA,IAAa,UAAb,cAA6B,cAAgD;;;;;;CA8B3E,AAAO,cAAc;EAEnB,MAAM,IAAwC;iCA3B5B,IAAI,IAAmC;iCAMvC,IAAI,IAAiC;qBAYnC;CAUtB;;;;;;CAOA,MAAa,OAAsB;EACjC,IAAI,KAAK,aAAa;EAGtB,KAAK,cAAc;EAInB,MAAM,cAAc,cAAc,WAAW,OAAO;EAEpD,KAAK,oBAAoB;EACzB,KAAK,sBAAsB;EAG3B,KAAK,UAAU,KAAK,cAAc,KAAK,iBAAiB;CAC1D;;;;CAKA,AAAO,QAAc;EACnB,KAAK,cAAc;EACnB,KAAK,QAAQ,MAAM;EACnB,KAAK,QAAQ,MAAM;EACnB,KAAK,oBAAoB;EACzB,KAAK,UAAU;CACjB;;;;;;;;;CAUA,IAAoB,eAAsC;EAExD,MAAM,gBAAgB,qBAAqB,UAAU;EAErD,IAAI,eAAe,OAAO;EAE1B,OAAO,KAAK;CACd;;;;;CAUA,AAAU,wBAA8B;EACtC,KAAK,2BAA2B;EAEhC,MAAM,UAAU,cAAmD,WAAW,CAAC,CAAC;EAEhF,KAAK,MAAM,CAAC,MAAM,WAAW,OAAO,QAAQ,OAAO,GACjD,KAAK,QAAQ,IAAI,MAAM,MAAM;CAEjC;;;;;;;;;;;;;;;;CAiBA,AAAU,6BAAmC;EAC3C,KAAK,QAAQ,IACX,SACA,sBAAsB,MAAM;GAC1B,MAAM,YAAY;GAClB,WAAW;EACb,CAAC,CACH;CACF;;;;;;;;;;;;;;;;;;;;;;;CAwBA,AAAO,IAAI,MAAgD;EACzD,OAAO,IAAI,cAAc,KAAK,UAAU,IAAI,CAAC;CAC/C;;;;;;;;;;;;;;;;;;CAmBA,AAAO,UAAU,MAAgD;EAC/D,OAAO,KAAK,cAAc,IAAI;CAChC;;;;CAKA,AAAO,KAAK,cAA+B;EACzC,MAAM,WAAW,KAAK,aAAa,SAAS,QAAQ;EAEpD,OAAO,KAAK,KAAK,UAAU,gBAAgB,EAAE;CAC/C;;;;;;;;;;;;;;CAeA,AAAO,SAAS,MAAqD;EACnE,MAAM,WAAW,KAAK,UAAU,IAAI;EAEpC,IAAI,CAAC,KAAK,cAAc,QAAQ,GAC9B,MAAM,IAAI,MAAM,WAAW,KAAK,oCAAoC;EAGtE,OAAO;CACT;;;;;;;;;;;;;;;;;;;;;;;;CAyBA,AAAO,SAAS,MAAyB,QAAmC;EAC1E,KAAK,QAAQ,IAAI,MAAM,MAAM;EAC7B,KAAK,QAAQ,OAAO,IAAI;EACxB,OAAO;CACT;;;;;;;;;;;;;CAcA,AAAO,WAAW,MAA+B;EAC/C,KAAK,oBAAoB;EACzB,KAAK,UAAU,KAAK,UAAU,IAAI;EAClC,OAAO;CACT;;;;;;CAOA,MAAa,UAA4B;EACvC,OAAO,KAAK,cAAc,KAAK,YAAY;CAC7C;;;;;CAMA,AAAU,cAAc,QAAqE;EAC3F,OAAO,qBAAqB;CAC9B;;;;;;;;;;;;;;;;;;;;;;;CA4BA,AAAO,GACL,OACA,SACmB;EACnB,OAAO,OAAO,UAAU,WAAW,SAAS,OAAO;CACrD;;;;;;;;;;;;CAaA,AAAO,IAAI,OAA+B;EACxC,OAAO,IAAI,WAAW,OAAO;EAC7B,OAAO;CACT;;;;;CAMA,MAAgB,KACd,OACA,SACe;EAIf,MAAM,OAAO,gBAAgB,WAAW,SAAS,OAAO;CAC1D;;;;;;;;;;;CAgBA,MAAsB,IACpB,MACA,UACA,SACsB;EACtB,MAAM,SAAS,KAAK;EACpB,MAAM,SAAS,MAAM,KAAK,SAAS,IAAI;EAEvC,MAAM,KAAK,KAA6B,aAAa;GACnD,QAAQ,OAAO;GACf;GACA,2BAAW,IAAI,KAAK;GACpB,MAAM,OAAO;EACf,CAAC;EAED,MAAM,SAAS,MAAM,OAAO,IAAI,QAAQ,UAAU,OAAO;EAEzD,MAAM,KAAK,KAA6B,YAAY;GAClD,QAAQ,OAAO;GACf;GACA,2BAAW,IAAI,KAAK;GACpB,MAAM;EACR,CAAC;EAED,IAAI,CAAC,OAAO,MACV,OAAO,OAAO,OAAO;EAGvB,OAAO,YAAY,SAAS,QAAQ,MAAM;CAC5C;;;;;;;;;;;CAYA,MAAsB,UACpB,QACA,UACA,SACsB;EACtB,MAAM,SAAS,KAAK;EAEpB,MAAM,KAAK,KAA6B,aAAa;GACnD,QAAQ,OAAO;GACf;GACA,2BAAW,IAAI,KAAK;EACtB,CAAC;EAED,IAAI,OAAO,WAAW,UACpB,SAAS,GAAG,iBAAiB,MAAM;EAGrC,MAAM,SAAS,MAAM,OAAO,UAAU,QAAQ,UAAU,OAAO;EAE/D,MAAM,KAAK,KAA6B,YAAY;GAClD,QAAQ,OAAO;GACf;GACA,2BAAW,IAAI,KAAK;GACpB,MAAM;EACR,CAAC;EAED,OAAO,YAAY,SAAS,QAAQ,MAAM;CAC5C;;;;;;;;;;;;;;;;;;;;;;;;;CA0BA,MAAa,WACX,KACA,UACA,SACsB;EACtB,MAAM,EAAE,mBAAmB,UAAU,WAAW,gBAAgB,GAAG,eAAe,WAAW,CAAC;EAE9F,MAAM,SAAS,MAAM,kBAAkB,KAAK;GAC1C;GACA;GACA;GACA;EACF,CAAC;EAED,IAAI,CAAC,OAAO,IACV,MAAM,IAAI,MAAM,kCAAkC,OAAO,YAAY;EAGvE,IAAI,CAAC,OAAO,aACV,MAAM,IAAI,MAAM,4DAA4D;EAG9E,MAAM,WAAW,WAAW,YAAY,OAAO;EAE/C,OAAO,KAAK,IAAI,OAAO,QAAQ,UAAU;GAAE,GAAG;GAAY;EAAS,CAAC;CACtE;;;;;;;;;;;;;;;;;;;;;;;CAwBA,MAAa,cACX,QACA,UACA,SACsB;EACtB,IAAI,OAAO;EACX,IAAI,WAAW,SAAS;EAExB,IAAI,OAAO,WAAW,OAAO,GAAG;GAC9B,MAAM,QAAQ,OAAO,MAAM,4BAA4B;GACvD,IAAI,OAAO;IACT,WAAW,YAAY,MAAM;IAC7B,OAAO,MAAM;GACf;EACF;EAEA,MAAM,SAAS,OAAO,KAAK,MAAM,QAAQ;EACzC,OAAO,KAAK,IAAI,QAAQ,UAAU;GAAE,GAAG;GAAS;EAAS,CAAC;CAC5D;;;;;;;;;CAUA,MAAsB,IAAI,UAAmC;EAC3D,OAAO,KAAK,aAAa,IAAI,QAAQ;CACvC;;;;;;;;;;;;;;;CAgBA,MAAa,QAAQ,UAAgC;EACnD,MAAM,SAAS,MAAM,KAAK,IAAI,QAAQ;EACtC,OAAO,KAAK,MAAM,OAAO,SAAS,CAAC;CACrC;;;;;;;CAQA,MAAsB,UAAU,UAAqC;EACnE,OAAO,KAAK,aAAa,UAAU,QAAQ;CAC7C;;;;;;;;;CAUA,MAAsB,OAAO,UAAkD;EAC7E,MAAM,SAAS,KAAK;EACpB,MAAM,OAAO,OAAO,aAAa,WAAW,WAAW,SAAS;EAEhE,MAAM,KAAK,KAA0B,gBAAgB;GACnD,QAAQ,OAAO;GACf,UAAU;GACV,2BAAW,IAAI,KAAK;EACtB,CAAC;EAED,MAAM,SAAS,MAAM,OAAO,OAAO,IAAI;EAEvC,MAAM,KAAK,KAA0B,eAAe;GAClD,QAAQ,OAAO;GACf,UAAU;GACV,2BAAW,IAAI,KAAK;EACtB,CAAC;EAED,OAAO;CACT;;;;;;;CAQA,MAAsB,WAAW,WAAkD;EACjF,OAAO,KAAK,aAAa,WAAW,SAAS;CAC/C;;;;;;;CAQA,MAAsB,OAAO,UAAoC;EAC/D,OAAO,KAAK,aAAa,OAAO,QAAQ;CAC1C;;;;;;;;;;CAWA,MAAsB,KAAK,MAA4B,IAAkC;EACvF,MAAM,SAAS,KAAK;EACpB,MAAM,WAAW,OAAO,SAAS,WAAW,OAAO,KAAK;EAExD,MAAM,KAAK,KAA8B,cAAc;GACrD,QAAQ,OAAO;GACf,UAAU;GACV,MAAM;GACN;GACA,2BAAW,IAAI,KAAK;EACtB,CAAC;EAED,MAAM,SAAS,MAAM,OAAO,KAAK,UAAU,EAAE;EAE7C,MAAM,KAAK,KAA8B,aAAa;GACpD,QAAQ,OAAO;GACf,UAAU;GACV,MAAM;GACN;GACA,2BAAW,IAAI,KAAK;GACpB,MAAM;EACR,CAAC;EAED,OAAO,YAAY,SAAS,QAAQ,MAAM;CAC5C;;;;;;;;;;CAWA,MAAsB,KAAK,MAA4B,IAAkC;EACvF,MAAM,SAAS,KAAK;EACpB,MAAM,WAAW,OAAO,SAAS,WAAW,OAAO,KAAK;EAExD,MAAM,KAAK,KAA8B,cAAc;GACrD,QAAQ,OAAO;GACf,UAAU;GACV,MAAM;GACN;GACA,2BAAW,IAAI,KAAK;EACtB,CAAC;EAED,MAAM,SAAS,MAAM,OAAO,KAAK,UAAU,EAAE;EAE7C,MAAM,KAAK,KAA8B,aAAa;GACpD,QAAQ,OAAO;GACf,UAAU;GACV,MAAM;GACN;GACA,2BAAW,IAAI,KAAK;GACpB,MAAM;EACR,CAAC;EAED,OAAO,YAAY,SAAS,QAAQ,MAAM;CAC5C;;;;;;;;CASA,MAAsB,KACpB,WACA,SAC4B;EAC5B,OAAO,KAAK,aAAa,KAAK,aAAa,IAAI,OAAO;CACxD;;;;;;;CAYA,MAAsB,SAAS,UAA4C;EACzE,OAAO,KAAK,aAAa,SAAS,QAAQ;CAC5C;;;;;;;CAQA,MAAsB,KAAK,UAAmC;EAC5D,OAAO,KAAK,aAAa,KAAK,QAAQ;CACxC;;;;;;;;;;CAeA,MAAa,KAAK,UAAmC;EACnD,MAAM,SAAS,KAAK;EAEpB,IAAI,EAAE,UAAU,WAAW,OAAO,OAAO,SAAS,YAChD,MAAM,IAAI,MAAM,oDAAoD;EAGtE,OAAO,OAAO,KAAK,QAAQ;CAC7B;;;;;;;;;;;;;;;;;;CAuBA,MAAa,gBAAgB,UAAkB,SAA6C;EAC1F,MAAM,SAAS,KAAK;EAEpB,IAAI,CAAC,KAAK,cAAc,MAAM,GAC5B,MAAM,IAAI,MAAM,6DAA6D;EAG/E,OAAO,OAAO,gBAAgB,UAAU,OAAO;CACjD;;;;;;;;;;;;;;;;;;;;;;;CAwBA,MAAa,sBACX,UACA,SACiB;EACjB,MAAM,SAAS,KAAK;EAEpB,IAAI,CAAC,KAAK,cAAc,MAAM,GAC5B,MAAM,IAAI,MAAM,oEAAoE;EAGtF,OAAO,OAAO,sBAAsB,UAAU,OAAO;CACvD;;;;;;;;;CAUA,MAAa,YAA6B;EACxC,MAAM,SAAS,KAAK;EAEpB,IAAI,CAAC,KAAK,cAAc,MAAM,GAC5B,MAAM,IAAI,MAAM,gEAAgE;EAGlF,OAAO,OAAO,UAAU;CAC1B;;;;;;;;;CAUA,MAAa,YAA6B;EACxC,MAAM,SAAS,KAAK;EAEpB,IAAI,CAAC,KAAK,cAAc,MAAM,GAC5B,MAAM,IAAI,MAAM,gEAAgE;EAGlF,OAAO,OAAO,UAAU;CAC1B;;;;;;;;;;CAWA,MAAa,gBAAgB,UAAkB,cAAqC;EAClF,MAAM,SAAS,KAAK;EAEpB,IAAI,CAAC,KAAK,cAAc,MAAM,GAC5B,MAAM,IAAI,MAAM,2DAA2D;EAG7E,OAAO,OAAO,gBAAgB,UAAU,YAAY;CACtD;;;;;;;;;;CAWA,MAAa,cAAc,UAAkB,YAA2C;EACtF,MAAM,SAAS,KAAK;EAEpB,IAAI,CAAC,KAAK,cAAc,MAAM,GAC5B,MAAM,IAAI,MAAM,wDAAwD;EAG1E,OAAO,OAAO,cAAc,UAAU,UAAU;CAClD;;;;;;;;;;CAWA,MAAa,cAAc,UAA2C;EACpE,MAAM,SAAS,KAAK;EAEpB,IAAI,CAAC,KAAK,cAAc,MAAM,GAC5B,MAAM,IAAI,MAAM,wDAAwD;EAG1E,OAAO,OAAO,cAAc,QAAQ;CACtC;;;;;;;;;;CAWA,MAAsB,aAAa,UAAkB,WAAqC;EACxF,OAAO,KAAK,aAAa,aAAa,UAAU,SAAS;CAC3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BA,MAAa,uBAAuB,OAAkD;EAEpF,IACE,EAAE,4BAA4B,KAAK,iBACnC,OAAO,KAAK,aAAa,2BAA2B,YAGpD,OAAO;GACL,OAAO;GACP,OAAO;EACT;EAGF,OAAO,KAAK,aAAa,uBAAuB,KAAK;CACvD;;;;;CAUA,AAAU,aACR,QACgF;EAChF,MAAM,EAAE,QAAQ,GAAG,YAAY;EAE/B,QAAQ,QAAR;GACE,KAAK,SACH,OAAO;IACL,MAAM,QAAQ;IACd,WAAW,QAAQ;IACnB,cAAc,QAAQ;GACxB;GAEF,KAAK;IACH,KAAK,oBAAoB,QAAQ,IAAI;IACrC,OAAO;KACL,GAAG;KACH,QAAQ,QAAQ;KAChB,QAAQ,QAAQ;KAChB,aAAa,QAAQ;KACrB,iBAAiB,QAAQ;KACzB,UAAU,QAAQ;KAClB,WAAW,QAAQ;IACrB;GAEF,KAAK;IACH,KAAK,oBAAoB,QAAQ,IAAI;IACrC,IAAI,CAAC,QAAQ,WACX,MAAM,IAAI,MAAM,gDAA8C;IAGhE,OAAO;KACL,GAAG;KACH,QAAQ,QAAQ,UAAU;KAC1B,QAAQ,QAAQ;KAChB,aAAa,QAAQ;KACrB,iBAAiB,QAAQ;KACzB,UAAU,QAAQ;KAClB,WAAW,QAAQ;KACnB,WAAW,QAAQ;KACnB,cAAc,QAAQ;IACxB;GAEF,KAAK;IACH,KAAK,oBAAoB,QAAQ,QAAQ;IACzC,OAAO;KACL,GAAG;KACH,QAAQ,QAAQ;KAChB,QAAQ,QAAQ;KAChB,aAAa,QAAQ;KACrB,iBAAiB,QAAQ;KACzB,UAAU,QAAQ;KAClB,WAAW,QAAQ;IACrB;GAEF,SACE,MAAM,IAAI,MAAM,wBAAwB,QAAQ;EACpD;CACF;;;;;CAMA,AAAU,oBAAoB,QAA6B,YAA0B;EACnF,MAAM,WAAW;GAAC;GAAU;GAAe;EAAiB;EAE5D,IAAI,eAAe,MACjB,SAAS,KAAK,QAAQ;EAGxB,KAAK,MAAM,SAAS,UAClB,IAAI,CAAC,OAAO,QACV,MAAM,IAAI,MAAM,GAAG,WAAW,YAAY,EAAE,oBAAoB,MAAM,gBAAgB;CAG5F;;;;;CAMA,AAAU,cAAc,MAAqC;EAG3D,IAAI,KAAK,QAAQ,IAAI,IAAI,GACvB,OAAO,KAAK,QAAQ,IAAI,IAAI;EAG9B,MAAM,SAAS,KAAK,QAAQ,IAAI,IAAI;EAEpC,IAAI,CAAC,QACH,MAAM,IAAI,MAAM,mBAAmB,KAAK,oBAAoB;EAG9D,MAAM,UAAU,KAAK,aAAa,MAAM;EACxC,IAAI;EAEJ,QAAQ,OAAO,QAAf;GACE,KAAK;IACH,SAAS,IAAI,YAAY,OAAoC;IAC7D;GACF,KAAK;IACH,SAAS,IAAI,SAAS,OAAoC;IAC1D;GACF,KAAK;IACH,SAAS,IAAI,SAAS,OAAiC;IACvD;GACF,KAAK;IACH,SAAS,IAAI,eAAe,OAAoC;IAChE;GACF,SACE,MAAM,IAAI,MAAM,gCAAgC,OAAO,QAAQ;EACnE;EAEA,KAAK,QAAQ,IAAI,MAAM,MAAM;EAC7B,OAAO;CACT;;;;;CAMA,MAAgB,uBAAmD;EACjE,MAAM,WAAW,cAAc,UAAU;EAEzC,IAAI,UAEF,OAAO,MADgB,SAAS,KACb,KAAK;EAG1B,OAAO,KAAK;CACd;AACF;;;;;;;;;;;;;AAcA,MAAa,UAAU,IAAI,QAAQ"}
1	+ {"version":3,"file":"storage.mjs","names":[],"sources":["../../../../../../../core/src/storage/storage.ts"],"sourcesContent":["import events, { type EventSubscription } from \"@mongez/events\";\nimport fs from \"fs\";\nimport path from \"path\";\nimport type { Readable } from \"stream\";\nimport type { UploadedFile } from \"../http\";\nimport { uploadsPath } from \"../utils/paths\";\nimport { storageConfig, storageConfigurations } from \"./config\";\nimport { storageDriverContext } from \"./context/storage-driver-context\";\nimport { DOSpacesDriver } from \"./drivers/do-spaces-driver\";\nimport { LocalDriver } from \"./drivers/local-driver\";\nimport { R2Driver } from \"./drivers/r2-driver\";\nimport { S3Driver } from \"./drivers/s3-driver\";\nimport { ScopedStorage } from \"./scoped-storage\";\nimport { StorageFile } from \"./storage-file\";\nimport { safeFetchToBuffer } from \"./utils/safe-fetch\";\nimport type {\n CloudStorageDriverContract,\n CloudStorageDriverOptions,\n DeleteManyResult,\n FileVisibility,\n ListOptions,\n LocalStorageDriverOptions,\n PresignedOptions,\n PresignedUploadOptions,\n PutFromUrlOptions,\n PutOptions,\n R2StorageDriverOptions,\n ScopedStorageContract,\n StorageCopyEventPayload,\n StorageDriverConfig,\n StorageDriverContract,\n StorageDriverName,\n StorageEventHandler,\n StorageEventPayload,\n StorageEventType,\n StorageFileInfo,\n StorageManagerContract,\n StoragePutEventPayload,\n TemporaryTokenValidation,\n} from \"./types\";\n\n/*\n Storage Manager\n \n Provides a unified interface for file storage operations across multiple\n * drivers (local, S3, R2, DigitalOcean Spaces). Extends `ScopedStorage` to\n * inherit all base operations while adding driver management and events.\n \n All operations return `StorageFile` instances for a consistent, rich DX.\n \n @example\n * ```typescript\n * // Basic usage (uses default driver)\n * const file = await storage.put(buffer, \"uploads/image.jpg\");\n \n // With options\n * const file = await storage.put(buffer, \"uploads/image.jpg\", {\n * mimeType: \"image/jpeg\",\n * cacheControl: \"max-age=31536000\"\n * });\n \n // Using specific driver (also returns StorageFile)\n * const file = await storage.use(\"s3\").put(buffer, \"path/to/file\");\n \n // Get raw driver for advanced use\n * const driver = storage.driver(\"s3\");\n * const data = await driver.put(buffer, \"path/to/file\"); // Returns StorageFileData\n \n // Stream operations for large files\n * const stream = await storage.getStream(\"large-file.zip\");\n * await storage.putStream(readableStream, \"output/file.zip\");\n \n // Batch operations\n * const results = await storage.deleteMany([\"file1.txt\", \"file2.txt\"]);\n \n // Event hooks\n * storage.on(\"afterPut\", ({ location, file }) => {\n * console.log(`Uploaded ${location}`);\n * });\n * ```\n /\nexport class Storage extends ScopedStorage implements StorageManagerContract {\n /\n Registered drivers (cached instances)\n * @internal\n /\n protected drivers = new Map<string, StorageDriverContract>();\n\n /\n Driver configurations\n * @internal\n /\n protected configs = new Map<string, StorageDriverConfig>();\n\n /\n Default driver name\n * @internal\n /\n protected defaultDriverName!: StorageDriverName;\n\n /\n Whether the storage has been initialized\n * @internal\n /\n private initialized = false;\n\n /\n Create a new Storage manager instance\n \n Uses lazy initialization - driver is resolved on first access.\n /\n public constructor() {\n // Temp placeholder - will be replaced on first access\n super(null as unknown as StorageDriverContract);\n }\n\n /\n Ensure storage is initialized (lazy initialization)\n \n Called automatically on first driver access.\n /\n public async init(): Promise<void> {\n if (this.initialized) return;\n\n // Mark as initialized FIRST to prevent infinite recursion\n this.initialized = true;\n\n // Get default driver name from config\n\n const defaultName = storageConfig(\"default\", \"local\");\n\n this.defaultDriverName = defaultName as StorageDriverName;\n this.loadDriversFromConfig();\n\n // Now set the actual driver\n this._driver = this.resolveDriver(this.defaultDriverName);\n }\n\n /\n Reset storage defaults\n /\n public reset(): void {\n this.initialized = false;\n this.drivers.clear();\n this.configs.clear();\n this.defaultDriverName = null as unknown as StorageDriverName;\n this._driver = null as unknown as StorageDriverContract;\n }\n\n /\n Get the currently active driver (context-aware in future)\n \n Currently returns the default driver.\n * Will be enhanced to check AsyncLocalStorage context for multi-tenant support.\n \n @returns The active storage driver\n /\n public override get activeDriver(): StorageDriverContract {\n // Check context for tenant-specific driver\n const contextDriver = storageDriverContext.getDriver();\n\n if (contextDriver) return contextDriver;\n\n return this._driver;\n }\n\n // ============================================================\n // Driver Management\n // ============================================================\n\n /\n Load drivers from configuration\n * @internal\n /\n protected loadDriversFromConfig(): void {\n this.registerBuiltInLocalDriver();\n\n const drivers = storageConfig<Record<string, StorageDriverConfig>>(\"drivers\", {});\n\n for (const [name, config] of Object.entries(drivers)) {\n this.configs.set(name, config);\n }\n }\n\n /\n Register the built-in `local` driver, rooted at `uploadsPath()`.\n \n The storage connector starts unconditionally — unlike database, cache and\n * herald, it does not early-return when `config.get(\"storage\")` is absent —\n * on the stated grounds that `init()` falls back to a built-in local driver so\n * file storage works out of the box. That fallback did not exist: `init()`\n * resolved the default driver name and then found no config registered\n * under it, so any app without `src/config/storage.ts` failed to boot\n * with `Storage driver \"local\" is not configured`. Only scaffolded apps, which\n * always ship that file, hid it.\n \n Registered before the configured drivers so an app that defines its own\n * `local` entry overrides this one rather than fighting it.\n /\n protected registerBuiltInLocalDriver(): void {\n this.configs.set(\n \"local\",\n storageConfigurations.local({\n root: uploadsPath(),\n urlPrefix: \"/uploads\",\n }),\n );\n }\n\n /\n Get a scoped storage for a specific driver\n \n Returns a `ScopedStorage` instance that wraps the specified driver.\n * Operations on the returned instance also return `StorageFile` objects.\n \n @param name - Driver name as defined in configuration\n * @returns ScopedStorage instance for the specified driver\n \n @example\n * ```typescript\n * // Upload to S3\n * const s3File = await storage.use(\"s3\").put(buffer, \"images/photo.jpg\");\n \n // Upload to local\n * const localFile = await storage.use(\"local\").put(buffer, \"temp/file.txt\");\n \n // Both return StorageFile with identical API\n * console.log(s3File.url);\n * console.log(localFile.url);\n * ```\n /\n public use(name: StorageDriverName): ScopedStorageContract {\n return new ScopedStorage(this.getDriver(name));\n }\n\n /\n Get a raw driver instance\n \n Returns the underlying driver directly for advanced use cases.\n * Unlike `use()`, calling methods on the raw driver returns\n * `StorageFileData` instead of `StorageFile`.\n \n @param name - Driver name as defined in configuration\n * @returns Raw driver instance implementing StorageDriverContract\n \n @example\n * ```typescript\n * const driver = storage.getDriver(\"s3\");\n * const data = await driver.put(buffer, \"path/to/file\");\n * // data is StorageFileData, not StorageFile\n * ```\n /\n public getDriver(name: StorageDriverName): StorageDriverContract {\n return this.resolveDriver(name);\n }\n\n /\n Get root directory of current driver\n /\n public root(apepndedPath?: string): string {\n const rootPath = this.activeDriver.options?.root \|\| \"\";\n\n return path.join(rootPath, apepndedPath \|\| \"\");\n }\n\n /\n Use a cloud storage driver with extended cloud capabilities\n \n @param name - Cloud driver name (s3, r2, spaces)\n * @returns Driver instance implementing CloudStorageDriverContract\n * @throws Error if driver doesn't support cloud operations\n \n @example\n * ```typescript\n * const cloudDriver = storage.useCloud(\"s3\");\n * const presignedUrl = await cloudDriver.getPresignedUrl(\"private/doc.pdf\");\n * ```\n /\n public useCloud(name: StorageDriverName): CloudStorageDriverContract {\n const instance = this.getDriver(name);\n\n if (!this.isCloudDriver(instance)) {\n throw new Error(`Driver \"${name}\" does not support cloud operations`);\n }\n\n return instance as CloudStorageDriverContract;\n }\n\n /\n Register a new driver configuration at runtime\n \n Allows dynamic driver registration for multi-tenancy or\n * runtime configuration scenarios.\n \n @param name - Unique driver name\n * @param config - Driver configuration\n * @returns This instance for chaining\n \n @example\n * ```typescript\n * storage.register(\"tenant-s3\", {\n * driver: \"s3\",\n * bucket: \"tenant-bucket\",\n * region: \"us-east-1\",\n * accessKeyId: process.env.TENANT_AWS_KEY,\n * secretAccessKey: process.env.TENANT_AWS_SECRET\n * });\n \n await storage.use(\"tenant-s3\").put(buffer, \"file.txt\");\n * ```\n /\n public register(name: StorageDriverName, config: StorageDriverConfig): this {\n this.configs.set(name, config);\n this.drivers.delete(name); // Clear cached instance\n return this;\n }\n\n /\n Set the default driver name\n \n @param name - Driver name to use as default\n * @returns This instance for chaining\n \n @example\n * ```typescript\n * storage.setDefault(\"s3\");\n * await storage.put(buffer, \"file.txt\"); // Now uses S3\n * ```\n /\n public setDefault(name: StorageDriverName): this {\n this.defaultDriverName = name;\n this._driver = this.getDriver(name);\n return this;\n }\n\n /\n Check if current driver is a cloud driver\n \n @returns Promise resolving to true if the current driver supports cloud operations\n /\n public async isCloud(): Promise<boolean> {\n return this.isCloudDriver(this.activeDriver);\n }\n\n /\n Check if a driver instance supports cloud operations\n * @internal\n /\n protected isCloudDriver(driver: StorageDriverContract): driver is CloudStorageDriverContract {\n return \"getPresignedUrl\" in driver;\n }\n\n // ============================================================\n // Event System\n // ============================================================\n\n /\n Register an event handler\n \n Subscribe to storage events for logging, analytics, or side effects.\n \n @param event - Event type to listen for\n * @param handler - Handler function\n * @returns Event subscription for unsubscribing\n \n @example\n * ```typescript\n * // Log all uploads\n * storage.on(\"afterPut\", ({ location, file }) => {\n * console.log(`Uploaded ${file?.size} bytes to ${location}`);\n * });\n \n // Track deletions\n * storage.on(\"afterDelete\", ({ location }) => {\n * analytics.track(\"file_deleted\", { path: location });\n * });\n * ```\n /\n public on<T extends StorageEventPayload = StorageEventPayload>(\n event: StorageEventType,\n handler: StorageEventHandler<T>,\n ): EventSubscription {\n return events.subscribe(`storage.${event}`, handler);\n }\n\n /\n Remove all handlers for an event type\n \n @param event - Event type to remove handlers for\n * @returns This instance for chaining\n \n @example\n * ```typescript\n * storage.off(\"afterPut\"); // Remove all afterPut handlers\n * ```\n /\n public off(event: StorageEventType): this {\n events.off(`storage.${event}`);\n return this;\n }\n\n /\n Emit an event to all registered handlers\n * @internal\n /\n protected async emit<T extends StorageEventPayload>(\n event: StorageEventType,\n payload: T,\n ): Promise<void> {\n // `triggerAll` is synchronous — it never awaits its handlers, so awaiting it\n // would make async listeners fire-and-forget. `triggerAllAsync` takes the\n // same `(event, ...args)` shape and awaits each handler in turn.\n await events.triggerAllAsync(`storage.${event}`, payload);\n }\n\n // ============================================================\n // Overridden Operations with Events\n // ============================================================\n\n /\n Store a file in storage\n \n Extends base `put()` with event emission for beforePut/afterPut hooks.\n \n @param file - File content as Buffer, string, UploadedFile, or Readable stream\n * @param location - Destination path\n * @param options - Storage options (mimeType, cacheControl, etc.)\n * @returns StorageFile instance with cached metadata\n /\n public override async put(\n file: UploadedFile \| Buffer \| string \| Readable,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n const driver = this.activeDriver;\n const buffer = await this.toBuffer(file);\n\n await this.emit<StoragePutEventPayload>(\"beforePut\", {\n driver: driver.name,\n location,\n timestamp: new Date(),\n size: buffer.length,\n });\n\n const result = await driver.put(buffer, location, options);\n\n await this.emit<StoragePutEventPayload>(\"afterPut\", {\n driver: driver.name,\n location,\n timestamp: new Date(),\n file: result,\n });\n\n if (!result.size) {\n result.size = buffer.length;\n }\n\n return StorageFile.fromData(result, driver);\n }\n\n /\n Store a file from a readable stream (for large files)\n \n Extends base `putStream()` with event emission.\n \n @param stream - Readable stream\n * @param location - Destination path\n * @param options - Storage options\n * @returns StorageFile instance with cached metadata\n /\n public override async putStream(\n stream: Readable \| string,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n const driver = this.activeDriver;\n\n await this.emit<StoragePutEventPayload>(\"beforePut\", {\n driver: driver.name,\n location,\n timestamp: new Date(),\n });\n\n if (typeof stream === \"string\") {\n stream = fs.createReadStream(stream);\n }\n\n const result = await driver.putStream(stream, location, options);\n\n await this.emit<StoragePutEventPayload>(\"afterPut\", {\n driver: driver.name,\n location,\n timestamp: new Date(),\n file: result,\n });\n\n return StorageFile.fromData(result, driver);\n }\n\n /\n Store a file from a URL\n \n Downloads content from the URL and stores it at the specified location.\n \n The download is SSRF-guarded by default: the URL scheme must be\n * https/http, the host must not resolve to a private / loopback /\n * link-local / cloud-metadata address, the body is capped, and the\n * request times out. Tune or relax via the {@link PutFromUrlOptions}\n * guard fields.\n \n @param url - Source URL to download from\n * @param location - Destination path\n * @param options - Storage + outbound-download guard options\n * @returns StorageFile instance with cached metadata\n \n @example\n * ```typescript\n * const file = await storage.putFromUrl(\n * \"https://example.com/image.jpg\",\n * \"downloads/image.jpg\"\n * );\n * ```\n /\n public async putFromUrl(\n url: string,\n location: string,\n options?: PutFromUrlOptions,\n ): Promise<StorageFile> {\n const { allowPrivateHosts, maxBytes, timeoutMs, allowedSchemes, ...putOptions } = options ?? {};\n\n const result = await safeFetchToBuffer(url, {\n allowPrivateHosts,\n maxBytes,\n timeoutMs,\n allowedSchemes,\n });\n\n if (!result.ok) {\n throw new Error(`Failed to fetch file from URL: ${result.statusText}`);\n }\n\n if (!result.contentType) {\n throw new Error(`Failed to fetch file from URL: missing content-type header`);\n }\n\n const mimeType = putOptions.mimeType \|\| result.contentType;\n\n return this.put(result.buffer, location, { ...putOptions, mimeType });\n }\n\n /\n Store a file from base64 encoded string\n \n Decodes base64 content (with optional data URL prefix) and stores it.\n \n @param base64 - Base64 encoded file content (or data URL)\n * @param location - Destination path\n * @param options - Storage options\n * @returns StorageFile instance with cached metadata\n \n @example\n * ```typescript\n * // From plain base64\n * const file = await storage.putFromBase64(base64String, \"images/photo.jpg\");\n \n // From data URL (auto-extracts MIME type)\n * const file = await storage.putFromBase64(\n * \"data:image/png;base64,iVBORw0KGgo...\",\n * \"images/photo.png\"\n * );\n * ```\n /\n public async putFromBase64(\n base64: string,\n location: string,\n options?: PutOptions,\n ): Promise<StorageFile> {\n let data = base64;\n let mimeType = options?.mimeType;\n\n if (base64.startsWith(\"data:\")) {\n const match = base64.match(/^data:([^;]+);base64,(.+)$/);\n if (match) {\n const matchedMimeType = match[1];\n const matchedData = match[2];\n\n if (matchedMimeType !== undefined && matchedData !== undefined) {\n mimeType = mimeType \|\| matchedMimeType;\n data = matchedData;\n }\n }\n }\n\n const buffer = Buffer.from(data, \"base64\");\n return this.put(buffer, location, { ...options, mimeType });\n }\n\n /\n Retrieve file contents as Buffer\n \n Uses the current driver (with async resolution).\n \n @param location - File path\n * @returns Buffer containing file contents\n /\n public override async get(location: string): Promise<Buffer> {\n return this.activeDriver.get(location);\n }\n\n /\n Get JSON content from a file\n \n Downloads and parses JSON file content.\n \n @param location - File path\n * @returns Parsed JSON content\n \n @example\n * ```typescript\n * const config = await storage.getJson(\"config/settings.json\");\n * console.log(config.apiKey);\n * ```\n /\n public async getJson(location: string): Promise<any> {\n const buffer = await this.get(location);\n return JSON.parse(buffer.toString());\n }\n\n /\n Retrieve a file as a readable stream (for large files)\n \n @param location - File path\n * @returns Readable stream of file contents\n /\n public override async getStream(location: string): Promise<Readable> {\n return this.activeDriver.getStream(location);\n }\n\n /\n Delete a file\n \n Extends base `delete()` with event emission.\n \n @param location - File path or StorageFile\n * @returns true if deleted, false if not found\n /\n public override async delete(location: string \| StorageFile): Promise<boolean> {\n const driver = this.activeDriver;\n const path = typeof location === \"string\" ? location : location.path;\n\n await this.emit<StorageEventPayload>(\"beforeDelete\", {\n driver: driver.name,\n location: path,\n timestamp: new Date(),\n });\n\n const result = await driver.delete(path);\n\n await this.emit<StorageEventPayload>(\"afterDelete\", {\n driver: driver.name,\n location: path,\n timestamp: new Date(),\n });\n\n return result;\n }\n\n /\n Delete multiple files at once\n \n @param locations - Array of file paths\n * @returns Array of delete results with status for each file\n /\n public override async deleteMany(locations: string[]): Promise<DeleteManyResult[]> {\n return this.activeDriver.deleteMany(locations);\n }\n\n /\n Check if a file exists\n \n @param location - File path\n * @returns true if file exists\n /\n public override async exists(location: string): Promise<boolean> {\n return this.activeDriver.exists(location);\n }\n\n /\n Copy a file to a new location\n \n Extends base `copy()` with event emission.\n \n @param from - Source path or StorageFile\n * @param to - Destination path\n * @returns StorageFile instance at destination\n /\n public override async copy(from: string \| StorageFile, to: string): Promise<StorageFile> {\n const driver = this.activeDriver;\n const fromPath = typeof from === \"string\" ? from : from.path;\n\n await this.emit<StorageCopyEventPayload>(\"beforeCopy\", {\n driver: driver.name,\n location: to,\n from: fromPath,\n to,\n timestamp: new Date(),\n });\n\n const result = await driver.copy(fromPath, to);\n\n await this.emit<StorageCopyEventPayload>(\"afterCopy\", {\n driver: driver.name,\n location: to,\n from: fromPath,\n to,\n timestamp: new Date(),\n file: result,\n });\n\n return StorageFile.fromData(result, driver);\n }\n\n /\n Move a file to a new location\n \n Extends base `move()` with event emission.\n \n @param from - Source path or StorageFile\n * @param to - Destination path\n * @returns StorageFile instance at destination\n /\n public override async move(from: string \| StorageFile, to: string): Promise<StorageFile> {\n const driver = this.activeDriver;\n const fromPath = typeof from === \"string\" ? from : from.path;\n\n await this.emit<StorageCopyEventPayload>(\"beforeMove\", {\n driver: driver.name,\n location: to,\n from: fromPath,\n to,\n timestamp: new Date(),\n });\n\n const result = await driver.move(fromPath, to);\n\n await this.emit<StorageCopyEventPayload>(\"afterMove\", {\n driver: driver.name,\n location: to,\n from: fromPath,\n to,\n timestamp: new Date(),\n file: result,\n });\n\n return StorageFile.fromData(result, driver);\n }\n\n /\n List files in a directory\n \n @param directory - Directory path (defaults to root)\n * @param options - List options (recursive, limit, etc.)\n * @returns Array of file information objects\n /\n public override async list(\n directory?: string,\n options?: ListOptions,\n ): Promise<StorageFileInfo[]> {\n return this.activeDriver.list(directory \|\| \"\", options);\n }\n\n // ============================================================\n // Metadata Operations\n // ============================================================\n\n /\n Get file metadata without downloading\n \n @param location - File path\n * @returns File information object\n /\n public override async metadata(location: string): Promise<StorageFileInfo> {\n return this.activeDriver.metadata(location);\n }\n\n /\n Get file size in bytes\n \n @param location - File path\n * @returns File size in bytes\n /\n public override async size(location: string): Promise<number> {\n return this.activeDriver.size(location);\n }\n\n // ============================================================\n // Path Operations (Local Driver Only)\n // ============================================================\n\n /\n Get the absolute filesystem path for a location\n \n Only available for local driver.\n \n @param location - File path\n * @throws Error if current driver is not a local driver\n * @returns Absolute filesystem path\n /\n public async path(location: string): Promise<string> {\n const driver = this.activeDriver;\n\n if (!(\"path\" in driver) \|\| typeof driver.path !== \"function\") {\n throw new Error(\"path() is only available for local storage drivers\");\n }\n\n return driver.path(location);\n }\n\n // ============================================================\n // Cloud-Specific Operations\n // ============================================================\n\n /\n Get a presigned URL for downloading a file\n \n Only available for cloud drivers.\n \n @param location - File path\n * @param options - Presigned URL options (expiresIn)\n * @throws Error if current driver is not a cloud driver\n * @returns Presigned download URL\n \n @example\n * ```typescript\n * const url = await storage.getPresignedUrl(\"private/document.pdf\", {\n * expiresIn: 3600 // 1 hour\n * });\n * ```\n /\n public async getPresignedUrl(location: string, options?: PresignedOptions): Promise<string> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Presigned URLs are only available for cloud storage drivers\");\n }\n\n return driver.getPresignedUrl(location, options);\n }\n\n /\n Get a presigned URL for uploading a file directly to cloud storage\n \n Only available for cloud drivers.\n \n @param location - Destination path\n * @param options - Upload options (expiresIn, contentType, metadata).\n * There is no size cap: a presigned PUT URL cannot enforce one — verify\n * the uploaded size server-side or use a presigned POST policy instead.\n * @throws Error if current driver is not a cloud driver\n * @returns Presigned upload URL\n \n @example\n * ```typescript\n * const uploadUrl = await storage.getPresignedUploadUrl(\"uploads/file.pdf\", {\n * expiresIn: 3600,\n * contentType: \"application/pdf\"\n * });\n \n // Client can PUT directly to this URL\n * ```\n /\n public async getPresignedUploadUrl(\n location: string,\n options?: PresignedUploadOptions,\n ): Promise<string> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Presigned upload URLs are only available for cloud storage drivers\");\n }\n\n return driver.getPresignedUploadUrl(location, options);\n }\n\n /\n Get the bucket name for cloud storage\n \n Only available for cloud drivers.\n \n @throws Error if current driver is not a cloud driver\n * @returns Bucket name\n /\n public async getBucket(): Promise<string> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Bucket information is only available for cloud storage drivers\");\n }\n\n return driver.getBucket();\n }\n\n /\n Get the region for cloud storage\n \n Only available for cloud drivers.\n \n @throws Error if current driver is not a cloud driver\n * @returns Region name\n /\n public async getRegion(): Promise<string> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Region information is only available for cloud storage drivers\");\n }\n\n return driver.getRegion();\n }\n\n /\n Set storage class for a file (e.g., STANDARD, GLACIER, etc.)\n \n Only available for cloud drivers.\n \n @param location - File path\n * @param storageClass - Target storage class\n * @throws Error if current driver is not a cloud driver\n /\n public async setStorageClass(location: string, storageClass: string): Promise<void> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Storage class is only available for cloud storage drivers\");\n }\n\n return driver.setStorageClass(location, storageClass);\n }\n\n /\n Set file visibility (public or private)\n \n Only available for cloud drivers.\n \n @param location - File path\n * @param visibility - \"public\" or \"private\"\n * @throws Error if current driver is not a cloud driver\n /\n public async setVisibility(location: string, visibility: FileVisibility): Promise<void> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Visibility is only available for cloud storage drivers\");\n }\n\n return driver.setVisibility(location, visibility);\n }\n\n /\n Get file visibility\n \n Only available for cloud drivers.\n \n @param location - File path\n * @throws Error if current driver is not a cloud driver\n * @returns Current visibility setting\n /\n public async getVisibility(location: string): Promise<FileVisibility> {\n const driver = this.activeDriver;\n\n if (!this.isCloudDriver(driver)) {\n throw new Error(\"Visibility is only available for cloud storage drivers\");\n }\n\n return driver.getVisibility(location);\n }\n\n /\n Get a temporary signed URL\n \n Creates a URL that provides temporary access to the file.\n \n @param location - File path\n * @param expiresIn - Seconds until expiration (default: 3600)\n * @returns Signed URL string\n /\n public override async temporaryUrl(location: string, expiresIn?: number): Promise<string> {\n return this.activeDriver.temporaryUrl(location, expiresIn);\n }\n\n /\n Validate a temporary URL token\n \n For local driver: validates HMAC-signed tokens\n * For cloud drivers: returns invalid (cloud validates via presigned URL)\n \n @param token - The token from the temporary URL\n * @returns Validation result with file info and convenience methods\n \n @example\n * ```typescript\n * const result = await storage.validateTemporaryToken(token);\n \n if (!result.valid) {\n * return response.status(403).send(result.error);\n * }\n \n // For local driver - use sendFile for efficiency\n * if (result.absolutePath) {\n * return response.sendFile(result.absolutePath);\n * }\n \n // For cloud driver - stream the file\n * const stream = await result.getStream!();\n * stream.pipe(response.raw);\n * ```\n /\n public async validateTemporaryToken(token: string): Promise<TemporaryTokenValidation> {\n // Check if driver supports token validation\n if (\n !(\"validateTemporaryToken\" in this.activeDriver) \|\|\n typeof this.activeDriver.validateTemporaryToken !== \"function\"\n ) {\n // For cloud drivers, temporary URLs are presigned and validated by the cloud provider\n return {\n valid: false,\n error: \"invalid_token\",\n };\n }\n\n return this.activeDriver.validateTemporaryToken(token);\n }\n\n // ============================================================\n // Configuration Parsing\n // ============================================================\n\n /\n Parse config into driver-specific options\n * @internal\n /\n protected parseOptions(\n config: StorageDriverConfig,\n ): LocalStorageDriverOptions \| CloudStorageDriverOptions \| R2StorageDriverOptions {\n const { driver, ...options } = config;\n\n switch (driver) {\n case \"local\":\n return {\n root: options.root,\n urlPrefix: options.urlPrefix,\n signatureKey: options.signatureKey,\n } satisfies LocalStorageDriverOptions;\n\n case \"s3\":\n this.validateCloudConfig(config, \"s3\");\n return {\n ...options,\n bucket: options.bucket!,\n region: options.region!,\n accessKeyId: options.accessKeyId!,\n secretAccessKey: options.secretAccessKey!,\n endpoint: options.endpoint,\n urlPrefix: options.urlPrefix,\n } satisfies CloudStorageDriverOptions;\n\n case \"r2\":\n this.validateCloudConfig(config, \"r2\");\n if (!options.accountId) {\n throw new Error('R2 driver requires \"accountId\" configuration');\n }\n\n return {\n ...options,\n region: options.region \|\| \"auto\",\n bucket: options.bucket!,\n accessKeyId: options.accessKeyId!,\n secretAccessKey: options.secretAccessKey!,\n endpoint: options.endpoint,\n urlPrefix: options.urlPrefix,\n accountId: options.accountId,\n publicDomain: options.publicDomain,\n } satisfies R2StorageDriverOptions;\n\n case \"spaces\":\n this.validateCloudConfig(config, \"spaces\");\n return {\n ...options,\n bucket: options.bucket!,\n region: options.region!,\n accessKeyId: options.accessKeyId!,\n secretAccessKey: options.secretAccessKey!,\n endpoint: options.endpoint,\n urlPrefix: options.urlPrefix,\n } satisfies CloudStorageDriverOptions;\n\n default:\n throw new Error(`Unknown driver type: ${driver}`);\n }\n }\n\n /\n Validate cloud driver configuration has required fields\n * @internal\n /\n protected validateCloudConfig(config: StorageDriverConfig, driverName: string): void {\n const required = [\"bucket\", \"accessKeyId\", \"secretAccessKey\"];\n\n if (driverName !== \"r2\") {\n required.push(\"region\");\n }\n\n for (const field of required) {\n if (!config[field as keyof StorageDriverConfig]) {\n throw new Error(`${driverName.toUpperCase()} driver requires \"${field}\" configuration`);\n }\n }\n }\n\n /\n Get or create driver instance from cache\n * @internal\n /\n protected resolveDriver(name: string): StorageDriverContract {\n // Ensure configs are loaded\n\n if (this.drivers.has(name)) {\n return this.drivers.get(name)!;\n }\n\n const config = this.configs.get(name);\n\n if (!config) {\n throw new Error(`Storage driver \"${name}\" is not configured`);\n }\n\n const options = this.parseOptions(config);\n let driver: StorageDriverContract;\n\n switch (config.driver) {\n case \"local\":\n driver = new LocalDriver(options as LocalStorageDriverOptions);\n break;\n case \"s3\":\n driver = new S3Driver(options as CloudStorageDriverOptions);\n break;\n case \"r2\":\n driver = new R2Driver(options as R2StorageDriverOptions);\n break;\n case \"spaces\":\n driver = new DOSpacesDriver(options as CloudStorageDriverOptions);\n break;\n default:\n throw new Error(`Unknown storage driver type: ${config.driver}`);\n }\n\n this.drivers.set(name, driver);\n return driver;\n }\n\n /\n Resolve the default driver name (supports async resolver for multi-tenancy)\n * @internal\n /\n protected async resolveDefaultDriver(): Promise<StorageDriverName> {\n const resolver = storageConfig(\"resolver\");\n\n if (resolver) {\n const resolved = await resolver();\n return resolved \|\| this.defaultDriverName;\n }\n\n return this.defaultDriverName;\n }\n}\n\n/\n Singleton storage instance\n \n Pre-configured storage manager ready for use throughout the application.\n \n @example\n * ```typescript\n * import { storage } from \"@warlock.js/core\";\n \n const file = await storage.put(buffer, \"uploads/file.txt\");\n * ```\n */\nexport const storage = new Storage();\n"],"mappings":"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"}

package/esm/storage/utils/safe-fetch.d.mts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"safe-fetch.d.mts","names":[],"sources":["../../../../../../../../core/src/storage/utils/safe-fetch.ts"],"mappings":";;AAmCA;;;;;;KAAY,gBAAA;EAkBV;;;;EAbA,iBAAA;~~EA2Hc~~;;;;AAAgC;~~EArH9C~~,QAAA,~~WA+MyB~~;~~EA7MzB~~,SAAA;~~EA8Mc~~;;;;~~EAzMd~~,cAAA;~~EA4MA~~;;;AACE;~~EAxMF~~,KAAA,UAAe,KAAK;AAAA;;;;;;;;;;;~~iBAyGN~~,qBAAA,CAAsB,EAAU;;AAwHtB;;;;KA9Bd,eAAA;EACV,MAAA,EAAQ,MAAM;EACd,WAAA;EACA,MAAA;EACA,UAAA;EACA,EAAA;AAAA;;;;;;;;;;;;;;;;;;;;iBAsBoB,iBAAA,CACpB,MAAA,UACA,OAAA,GAAS,gBAAA,GACR,OAAA,CAAQ,eAAA"}
1	+ {"version":3,"file":"safe-fetch.d.mts","names":[],"sources":["../../../../../../../../core/src/storage/utils/safe-fetch.ts"],"mappings":";;AAmCA;;;;;;KAAY,gBAAA;EAkBV;;;;EAbA,iBAAA;EAiJc;;;;AAAgC;EA3I9C,QAAA,WAqOyB;EAnOzB,SAAA;EAoOc;;;;EA/Nd,cAAA;EAkOA;;;AACE;EA9NF,KAAA,UAAe,KAAK;AAAA;;;;;;;;;;;iBA+HN,qBAAA,CAAsB,EAAU;;AAwHtB;;;;KA9Bd,eAAA;EACV,MAAA,EAAQ,MAAM;EACd,WAAA;EACA,MAAA;EACA,UAAA;EACA,EAAA;AAAA;;;;;;;;;;;;;;;;;;;;iBAsBoB,iBAAA,CACpB,MAAA,UACA,OAAA,GAAS,gBAAA,GACR,OAAA,CAAQ,eAAA"}

package/esm/storage/utils/safe-fetch.mjs CHANGED Viewed

@@ -59,10 +59,15 @@ function isPrivateIpv4(ip) {
 }
 function isPrivateIpv6(ip) {
 	const normalized = ip.toLowerCase().split("%")[0];
+	if (normalized === void 0) return true;
 	const v4 = normalized.match(/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
-	if (v4) return isPrivateIpv4(v4[1]);
+	if (v4) {
+		const dottedQuad = v4[1];
+		return dottedQuad === void 0 ? true : isPrivateIpv4(dottedQuad);
+	}
 	if (normalized === "::1" || normalized === "::") return true;
 	const firstGroup = normalized.split(":")[0];
+	if (firstGroup === void 0) return true;
 	const head = firstGroup === "" ? 0 : Number.parseInt(firstGroup, 16);
 	if ((head & 65024) === 64512) return true;
 	if ((head & 65472) === 65152) return true;

package/esm/storage/utils/safe-fetch.mjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"safe-fetch.mjs","names":[],"sources":["../../../../../../../../core/src/storage/utils/safe-fetch.ts"],"sourcesContent":["import { lookup } from \"node:dns/promises\";\nimport { isIP } from \"@warlock.js/seal\";\nimport { StorageError } from \"./storage-error\";\n\n/*\n SSRF / resource-exhaustion guard for storage's outbound downloads\n * (`putFromUrl`).\n \n NOTE: this MIRRORS `@warlock.js/ai`'s `src/security/private-ip.ts` and\n * `src/security/outbound-policy.ts`. It is duplicated here intentionally\n * because `@warlock.js/core` cannot depend on `@warlock.js/ai`. Pending\n * extraction of a shared security package, keep the two copies in sync.\n /\n\n/* 50 MiB — default cap on a downloaded body (storage files run larger than AI payloads). /\nconst DEFAULT_MAX_BYTES = 50 1024 * 1024;\n/** 30s — default per-request timeout. /\nconst DEFAULT_TIMEOUT_MS = 30_000;\n/\n Cap on the number of re-validated redirect hops. Mirrors\n * `@warlock.js/ai`'s `DEFAULT_MAX_REDIRECTS`\n * (ai/src/security/outbound-policy.ts:15).\n /\nconst DEFAULT_MAX_REDIRECTS = 5;\n\n/* 3xx statuses whose `Location` a follow re-issues — mirrors ai/src/security/outbound-policy.ts:18. /\nconst REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);\n\n/\n Options controlling a guarded outbound fetch. Every field is optional;\n * {@link resolveFetchPolicy} fills safe defaults. The defaults are\n * deliberately strict (https+http, private-IP deny ON, 30s timeout,\n * 50 MiB cap) so a caller that does not tune them still gets a hardened\n * request.\n /\nexport type SafeFetchOptions = {\n /\n Whether to ALLOW private / loopback / link-local / metadata hosts.\n * Default `false` — the SSRF guard is on (private hosts are denied).\n /\n allowPrivateHosts?: boolean;\n /\n Maximum response body size in bytes. A declared `content-length` over\n * this fails fast; otherwise the body is read with a running cap and the\n * stream is aborted on overflow. Default `52_428_800` (50 MiB).\n /\n maxBytes?: number;\n /* Per-request timeout in milliseconds. Default `30_000`. /\n timeoutMs?: number;\n /\n URL schemes permitted for the request, compared case-insensitively.\n * Default `[\"https\", \"http\"]`.\n /\n allowedSchemes?: string[];\n /\n Injected `fetch` implementation (for tests or proxies). Defaults to the\n * global `fetch`.\n /\n fetch?: typeof fetch;\n};\n\n/* {@link SafeFetchOptions} with every default resolved — never partial. /\ntype ResolvedFetchPolicy = {\n allowPrivateHosts: boolean;\n maxBytes: number;\n timeoutMs: number;\n allowedSchemes: string[];\n fetch: typeof fetch;\n};\n\n/\n Fill a {@link SafeFetchOptions} with strict defaults: https+http,\n * private-IP deny on, 30s timeout, 50 MiB cap, global `fetch`.\n /\nfunction resolveFetchPolicy(options: SafeFetchOptions = {}): ResolvedFetchPolicy {\n return {\n allowPrivateHosts: options.allowPrivateHosts ?? false,\n maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,\n timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n allowedSchemes: options.allowedSchemes ?? [\"https\", \"http\"],\n fetch: options.fetch ?? globalThis.fetch,\n };\n}\n\n/* Parse a dotted-quad into four octets, or `null` if malformed. /\nfunction parseIpv4(ip: string): [number, number, number, number] \| null {\n const parts = ip.split(\".\");\n if (parts.length !== 4) {\n return null;\n }\n\n const octets = parts.map((part) => Number(part));\n if (octets.some((n) => !Number.isInteger(n) \|\| n < 0 \|\| n > 255)) {\n return null;\n }\n\n return octets as [number, number, number, number];\n}\n\nfunction isPrivateIpv4(ip: string): boolean {\n const octets = parseIpv4(ip);\n if (!octets) {\n return true; // unparseable → refuse, fail closed\n }\n\n const [a, b] = octets;\n\n return (\n a === 0 \|\| // 0.0.0.0/8 \"this network\"\n a === 10 \|\| // 10.0.0.0/8 private\n a === 127 \|\| // 127.0.0.0/8 loopback\n (a === 100 && b >= 64 && b <= 127) \|\| // 100.64.0.0/10 CGNAT\n (a === 169 && b === 254) \|\| // 169.254.0.0/16 link-local + metadata\n (a === 172 && b >= 16 && b <= 31) \|\| // 172.16.0.0/12 private\n (a === 192 && b === 168) \|\| // 192.168.0.0/16 private\n (a === 192 && b === 0) \|\| // 192.0.0.0/24 + 192.0.2.0/24 (IETF/test)\n (a === 198 && (b === 18 \|\| b === 19)) \|\| // 198.18.0.0/15 benchmarking\n (a === 198 && b === 51) \|\| // 198.51.100.0/24 test-net-2\n (a === 203 && b === 0) \|\| // 203.0.113.0/24 test-net-3\n a >= 224 // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved + 255.255.255.255\n );\n}\n\nfunction isPrivateIpv6(ip: string): boolean {\n const normalized = ip.toLowerCase().split(\"%\")[0]; // drop zone id\n\n // IPv4-mapped / -embedded (::ffff:a.b.c.d, ::a.b.c.d) — defer to the v4\n // check on the trailing dotted-quad so an inward-mapped address is caught.\n const v4 = normalized.match(/(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$/);\n if (v4) {\n return isPrivateIpv4(v4[1]);\n }\n\n if (normalized === \"::1\" \|\| normalized === \"::\") {\n return true; // loopback / unspecified\n }\n\n // Expand only the leading group enough to classify the reserved blocks.\n const firstGroup = normalized.split(\":\")[0];\n const head = firstGroup === \"\" ? 0 : Number.parseInt(firstGroup, 16);\n\n // fc00::/7 unique-local (fc.. / fd..)\n if ((head & 0xfe00) === 0xfc00) {\n return true;\n }\n // fe80::/10 link-local\n if ((head & 0xffc0) === 0xfe80) {\n return true;\n }\n\n return false;\n}\n\n/\n True when `ip` is a private, loopback, link-local, unique-local,\n * carrier-grade-NAT, unspecified, or otherwise non-public address — the set\n * an SSRF guard must refuse. Accepts IPv4 and IPv6 literals (including\n * IPv4-mapped IPv6 like `::ffff:169.254.169.254`). A non-IP string returns\n * `false` (the caller resolves hostnames via DNS first).\n \n The cloud-metadata endpoint `169.254.169.254` is covered by the IPv4\n * link-local range `169.254.0.0/16`.\n /\nexport function isPrivateOrReservedIp(ip: string): boolean {\n const family = isIP(ip);\n if (family === 4) {\n return isPrivateIpv4(ip);\n }\n if (family === 6) {\n return isPrivateIpv6(ip);\n }\n return false;\n}\n\n/* Strip the `[ ]` IPv6 brackets `URL.hostname` keeps. /\nfunction stripBrackets(host: string): string {\n return host.startsWith(\"[\") && host.endsWith(\"]\") ? host.slice(1, -1) : host;\n}\n\n/\n Reject when `host` is — or resolves to — a private / reserved address.\n * IP literals are checked directly; hostnames are resolved via DNS and every\n * returned address is checked (a public name pointing inward is caught). A\n * resolution failure fails closed.\n /\nasync function assertHostNotPrivate(host: string, rawUrl: string): Promise<void> {\n if (isIP(host) !== 0) {\n if (isPrivateOrReservedIp(host)) {\n throw new StorageError(`outbound request blocked — \"${host}\" is a private/reserved address`, {\n context: { url: rawUrl, address: host },\n });\n }\n return;\n }\n\n let addresses: Array<{ address: string }>;\n try {\n addresses = await lookup(host, { all: true });\n } catch (cause) {\n throw new StorageError(\n `outbound request blocked — could not resolve host \"${host}\" to verify it is public`,\n { cause, context: { url: rawUrl, host } },\n );\n }\n\n for (const { address } of addresses) {\n if (isPrivateOrReservedIp(address)) {\n throw new StorageError(\n `outbound request blocked — host \"${host}\" resolves to a private/reserved address (${address})`,\n { context: { url: rawUrl, host, address } },\n );\n }\n }\n}\n\n/\n Validate a URL against the policy BEFORE any network call: scheme\n * allowlist and (when private hosts are not allowed) a DNS resolution that\n * rejects private / loopback / link-local / metadata addresses — the SSRF\n * guard. Returns the parsed `URL` on success; throws {@link StorageError}\n * otherwise.\n /\nasync function assertUrlAllowed(rawUrl: string, policy: ResolvedFetchPolicy): Promise<URL> {\n let url: URL;\n try {\n url = new URL(rawUrl);\n } catch {\n throw new StorageError(`outbound request blocked — invalid URL: ${rawUrl}`, {\n context: { url: rawUrl },\n });\n }\n\n const scheme = url.protocol.replace(/:$/, \"\").toLowerCase();\n if (!policy.allowedSchemes.some((s) => s.toLowerCase() === scheme)) {\n throw new StorageError(\n `outbound request blocked — scheme \"${scheme}\" is not allowed (allowed: ${policy.allowedSchemes.join(\", \")})`,\n { context: { url: rawUrl, scheme } },\n );\n }\n\n if (!policy.allowPrivateHosts) {\n const host = stripBrackets(url.hostname);\n await assertHostNotPrivate(host, rawUrl);\n }\n\n return url;\n}\n\n/\n Result of {@link safeFetchToBuffer}: the (capped) body plus the response's\n * content-type, so callers can derive a MIME type and enforce a non-empty\n * content-type check.\n /\nexport type SafeFetchResult = {\n buffer: Buffer;\n contentType: string \| null;\n status: number;\n statusText: string;\n ok: boolean;\n};\n\n/\n SSRF-guarded download: validates the URL (scheme allowlist + post-DNS\n * private-IP deny), performs the request with a timeout via\n * `AbortController`, then streams the body with a hard byte cap — aborting\n * the moment the running total exceeds `maxBytes`. A declared\n * `content-length` over the cap fails fast.\n \n Redirects are NEVER delegated to the platform: every hop is issued with\n * `redirect: \"manual\"` and its `Location` is re-run through\n * {@link assertUrlAllowed} — including the DNS-resolution private-IP check\n * — before being followed (capped at {@link DEFAULT_MAX_REDIRECTS}), so a\n * 3xx from an allowed host cannot smuggle the request to a private /\n * metadata target. Mirrors `@warlock.js/ai`'s `guardedFetch`\n * (ai/src/security/outbound-policy.ts:188-284); duplicated per this\n * module's file-header note since core cannot depend on ai.\n \n @throws {StorageError} On a blocked URL (initial or redirect target),\n * a redirect-hop bound overflow, timeout, or oversized body.\n /\nexport async function safeFetchToBuffer(\n rawUrl: string,\n options: SafeFetchOptions = {},\n): Promise<SafeFetchResult> {\n const policy = resolveFetchPolicy(options);\n let url = await assertUrlAllowed(rawUrl, policy);\n\n const controller = new AbortController();\n const timer = setTimeout(() => {\n controller.abort(\n new StorageError(`outbound request timed out after ${policy.timeoutMs}ms`, {\n context: { url: rawUrl, timeoutMs: policy.timeoutMs },\n }),\n );\n }, policy.timeoutMs);\n\n try {\n let response: Response;\n\n for (let hop = 0; ; hop++) {\n response = await policy.fetch(url, { signal: controller.signal, redirect: \"manual\" });\n\n const location = response.headers.get(\"location\");\n if (!REDIRECT_STATUSES.has(response.status) \|\| location === null) {\n break;\n }\n\n if (hop >= DEFAULT_MAX_REDIRECTS) {\n throw new StorageError(\n `outbound request blocked — more than ${DEFAULT_MAX_REDIRECTS} redirects`,\n { context: { url: rawUrl, maxRedirects: DEFAULT_MAX_REDIRECTS } },\n );\n }\n\n let target: URL;\n try {\n target = new URL(location, url);\n } catch {\n throw new StorageError(\n `outbound request blocked — invalid redirect Location: ${location}`,\n {\n context: { url: url.toString(), location },\n },\n );\n }\n\n // Discard the interim body so the connection can be reused.\n if (response.body) {\n await response.body.cancel().catch(() => undefined);\n }\n\n // The redirect target gets the SAME scheme + private-IP validation\n // (incl. DNS resolution) as the initial URL — this is what closes\n // the redirect-based SSRF bypass: a 302 from an allowed host to\n // 169.254.169.254 is re-validated here, not blindly followed.\n url = await assertUrlAllowed(target.toString(), policy);\n }\n\n const declared = Number(response.headers.get(\"content-length\"));\n if (Number.isFinite(declared) && declared > policy.maxBytes) {\n throw new StorageError(\n `outbound response body too large — declared ${declared} bytes exceeds the ${policy.maxBytes}-byte cap`,\n { context: { url: rawUrl, declared, maxBytes: policy.maxBytes } },\n );\n }\n\n const buffer = await readBodyCapped(response, policy.maxBytes, rawUrl);\n\n return {\n buffer,\n contentType: response.headers.get(\"content-type\"),\n status: response.status,\n statusText: response.statusText,\n ok: response.ok,\n };\n } finally {\n clearTimeout(timer);\n }\n}\n\n/\n Read a response body into a Buffer with a hard byte cap. The stream is\n * read chunk-by-chunk and cancelled the moment the running total exceeds\n * `maxBytes`. Throws {@link StorageError} on overflow.\n */\nasync function readBodyCapped(\n response: Response,\n maxBytes: number,\n rawUrl: string,\n): Promise<Buffer> {\n if (!response.body) {\n const arrayBuffer = await response.arrayBuffer();\n if (arrayBuffer.byteLength > maxBytes) {\n throw new StorageError(`outbound response body exceeded the ${maxBytes}-byte cap`, {\n context: { url: rawUrl, maxBytes },\n });\n }\n return Buffer.from(arrayBuffer);\n }\n\n const reader = response.body.getReader();\n const chunks: Uint8Array[] = [];\n let total = 0;\n\n for (;;) {\n const { done, value } = await reader.read();\n if (done) {\n break;\n }\n if (!value) {\n continue;\n }\n\n total += value.byteLength;\n if (total > maxBytes) {\n await reader.cancel();\n throw new StorageError(`outbound response body exceeded the ${maxBytes}-byte cap`, {\n context: { url: rawUrl, maxBytes },\n });\n }\n chunks.push(value);\n }\n\n return Buffer.concat(chunks);\n}\n"],"mappings":"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"}
1	+ {"version":3,"file":"safe-fetch.mjs","names":[],"sources":["../../../../../../../../core/src/storage/utils/safe-fetch.ts"],"sourcesContent":["import { lookup } from \"node:dns/promises\";\nimport { isIP } from \"@warlock.js/seal\";\nimport { StorageError } from \"./storage-error\";\n\n/*\n SSRF / resource-exhaustion guard for storage's outbound downloads\n * (`putFromUrl`).\n \n NOTE: this MIRRORS `@warlock.js/ai`'s `src/security/private-ip.ts` and\n * `src/security/outbound-policy.ts`. It is duplicated here intentionally\n * because `@warlock.js/core` cannot depend on `@warlock.js/ai`. Pending\n * extraction of a shared security package, keep the two copies in sync.\n /\n\n/* 50 MiB — default cap on a downloaded body (storage files run larger than AI payloads). /\nconst DEFAULT_MAX_BYTES = 50 1024 * 1024;\n/** 30s — default per-request timeout. /\nconst DEFAULT_TIMEOUT_MS = 30_000;\n/\n Cap on the number of re-validated redirect hops. Mirrors\n * `@warlock.js/ai`'s `DEFAULT_MAX_REDIRECTS`\n * (ai/src/security/outbound-policy.ts:15).\n /\nconst DEFAULT_MAX_REDIRECTS = 5;\n\n/* 3xx statuses whose `Location` a follow re-issues — mirrors ai/src/security/outbound-policy.ts:18. /\nconst REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);\n\n/\n Options controlling a guarded outbound fetch. Every field is optional;\n * {@link resolveFetchPolicy} fills safe defaults. The defaults are\n * deliberately strict (https+http, private-IP deny ON, 30s timeout,\n * 50 MiB cap) so a caller that does not tune them still gets a hardened\n * request.\n /\nexport type SafeFetchOptions = {\n /\n Whether to ALLOW private / loopback / link-local / metadata hosts.\n * Default `false` — the SSRF guard is on (private hosts are denied).\n /\n allowPrivateHosts?: boolean;\n /\n Maximum response body size in bytes. A declared `content-length` over\n * this fails fast; otherwise the body is read with a running cap and the\n * stream is aborted on overflow. Default `52_428_800` (50 MiB).\n /\n maxBytes?: number;\n /* Per-request timeout in milliseconds. Default `30_000`. /\n timeoutMs?: number;\n /\n URL schemes permitted for the request, compared case-insensitively.\n * Default `[\"https\", \"http\"]`.\n /\n allowedSchemes?: string[];\n /\n Injected `fetch` implementation (for tests or proxies). Defaults to the\n * global `fetch`.\n /\n fetch?: typeof fetch;\n};\n\n/* {@link SafeFetchOptions} with every default resolved — never partial. /\ntype ResolvedFetchPolicy = {\n allowPrivateHosts: boolean;\n maxBytes: number;\n timeoutMs: number;\n allowedSchemes: string[];\n fetch: typeof fetch;\n};\n\n/\n Fill a {@link SafeFetchOptions} with strict defaults: https+http,\n * private-IP deny on, 30s timeout, 50 MiB cap, global `fetch`.\n /\nfunction resolveFetchPolicy(options: SafeFetchOptions = {}): ResolvedFetchPolicy {\n return {\n allowPrivateHosts: options.allowPrivateHosts ?? false,\n maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,\n timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n allowedSchemes: options.allowedSchemes ?? [\"https\", \"http\"],\n fetch: options.fetch ?? globalThis.fetch,\n };\n}\n\n/* Parse a dotted-quad into four octets, or `null` if malformed. /\nfunction parseIpv4(ip: string): [number, number, number, number] \| null {\n const parts = ip.split(\".\");\n if (parts.length !== 4) {\n return null;\n }\n\n const octets = parts.map((part) => Number(part));\n if (octets.some((n) => !Number.isInteger(n) \|\| n < 0 \|\| n > 255)) {\n return null;\n }\n\n return octets as [number, number, number, number];\n}\n\nfunction isPrivateIpv4(ip: string): boolean {\n const octets = parseIpv4(ip);\n if (!octets) {\n return true; // unparseable → refuse, fail closed\n }\n\n const [a, b] = octets;\n\n return (\n a === 0 \|\| // 0.0.0.0/8 \"this network\"\n a === 10 \|\| // 10.0.0.0/8 private\n a === 127 \|\| // 127.0.0.0/8 loopback\n (a === 100 && b >= 64 && b <= 127) \|\| // 100.64.0.0/10 CGNAT\n (a === 169 && b === 254) \|\| // 169.254.0.0/16 link-local + metadata\n (a === 172 && b >= 16 && b <= 31) \|\| // 172.16.0.0/12 private\n (a === 192 && b === 168) \|\| // 192.168.0.0/16 private\n (a === 192 && b === 0) \|\| // 192.0.0.0/24 + 192.0.2.0/24 (IETF/test)\n (a === 198 && (b === 18 \|\| b === 19)) \|\| // 198.18.0.0/15 benchmarking\n (a === 198 && b === 51) \|\| // 198.51.100.0/24 test-net-2\n (a === 203 && b === 0) \|\| // 203.0.113.0/24 test-net-3\n a >= 224 // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved + 255.255.255.255\n );\n}\n\nfunction isPrivateIpv6(ip: string): boolean {\n const normalized = ip.toLowerCase().split(\"%\")[0]; // drop zone id\n\n // EVERY fallback in this function returns `true`, and that direction is the\n // whole point: this is an SSRF guard, and `true` means \"private — refuse\".\n //\n // `split` on a non-empty string always yields a first element, so none of\n // these is reachable today. But the safe answer for an address we could not\n // classify is to REFUSE it, not to let it through. A `?? \"\"` here would fall\n // past every check below and return `false` — reporting an unparseable\n // address as public, which is a fail-OPEN in the one function whose job is\n // to keep requests off the internal network.\n if (normalized === undefined) {\n return true;\n }\n\n // IPv4-mapped / -embedded (::ffff:a.b.c.d, ::a.b.c.d) — defer to the v4\n // check on the trailing dotted-quad so an inward-mapped address is caught.\n const v4 = normalized.match(/(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$/);\n if (v4) {\n const dottedQuad = v4[1];\n\n // Capture group 1 exists whenever this pattern matched. Refusing rather\n // than defaulting, for the reason above.\n return dottedQuad === undefined ? true : isPrivateIpv4(dottedQuad);\n }\n\n if (normalized === \"::1\" \|\| normalized === \"::\") {\n return true; // loopback / unspecified\n }\n\n // Expand only the leading group enough to classify the reserved blocks.\n const firstGroup = normalized.split(\":\")[0];\n\n if (firstGroup === undefined) {\n return true;\n }\n\n const head = firstGroup === \"\" ? 0 : Number.parseInt(firstGroup, 16);\n\n // fc00::/7 unique-local (fc.. / fd..)\n if ((head & 0xfe00) === 0xfc00) {\n return true;\n }\n // fe80::/10 link-local\n if ((head & 0xffc0) === 0xfe80) {\n return true;\n }\n\n return false;\n}\n\n/\n True when `ip` is a private, loopback, link-local, unique-local,\n * carrier-grade-NAT, unspecified, or otherwise non-public address — the set\n * an SSRF guard must refuse. Accepts IPv4 and IPv6 literals (including\n * IPv4-mapped IPv6 like `::ffff:169.254.169.254`). A non-IP string returns\n * `false` (the caller resolves hostnames via DNS first).\n \n The cloud-metadata endpoint `169.254.169.254` is covered by the IPv4\n * link-local range `169.254.0.0/16`.\n /\nexport function isPrivateOrReservedIp(ip: string): boolean {\n const family = isIP(ip);\n if (family === 4) {\n return isPrivateIpv4(ip);\n }\n if (family === 6) {\n return isPrivateIpv6(ip);\n }\n return false;\n}\n\n/* Strip the `[ ]` IPv6 brackets `URL.hostname` keeps. /\nfunction stripBrackets(host: string): string {\n return host.startsWith(\"[\") && host.endsWith(\"]\") ? host.slice(1, -1) : host;\n}\n\n/\n Reject when `host` is — or resolves to — a private / reserved address.\n * IP literals are checked directly; hostnames are resolved via DNS and every\n * returned address is checked (a public name pointing inward is caught). A\n * resolution failure fails closed.\n /\nasync function assertHostNotPrivate(host: string, rawUrl: string): Promise<void> {\n if (isIP(host) !== 0) {\n if (isPrivateOrReservedIp(host)) {\n throw new StorageError(`outbound request blocked — \"${host}\" is a private/reserved address`, {\n context: { url: rawUrl, address: host },\n });\n }\n return;\n }\n\n let addresses: Array<{ address: string }>;\n try {\n addresses = await lookup(host, { all: true });\n } catch (cause) {\n throw new StorageError(\n `outbound request blocked — could not resolve host \"${host}\" to verify it is public`,\n { cause, context: { url: rawUrl, host } },\n );\n }\n\n for (const { address } of addresses) {\n if (isPrivateOrReservedIp(address)) {\n throw new StorageError(\n `outbound request blocked — host \"${host}\" resolves to a private/reserved address (${address})`,\n { context: { url: rawUrl, host, address } },\n );\n }\n }\n}\n\n/\n Validate a URL against the policy BEFORE any network call: scheme\n * allowlist and (when private hosts are not allowed) a DNS resolution that\n * rejects private / loopback / link-local / metadata addresses — the SSRF\n * guard. Returns the parsed `URL` on success; throws {@link StorageError}\n * otherwise.\n /\nasync function assertUrlAllowed(rawUrl: string, policy: ResolvedFetchPolicy): Promise<URL> {\n let url: URL;\n try {\n url = new URL(rawUrl);\n } catch {\n throw new StorageError(`outbound request blocked — invalid URL: ${rawUrl}`, {\n context: { url: rawUrl },\n });\n }\n\n const scheme = url.protocol.replace(/:$/, \"\").toLowerCase();\n if (!policy.allowedSchemes.some((s) => s.toLowerCase() === scheme)) {\n throw new StorageError(\n `outbound request blocked — scheme \"${scheme}\" is not allowed (allowed: ${policy.allowedSchemes.join(\", \")})`,\n { context: { url: rawUrl, scheme } },\n );\n }\n\n if (!policy.allowPrivateHosts) {\n const host = stripBrackets(url.hostname);\n await assertHostNotPrivate(host, rawUrl);\n }\n\n return url;\n}\n\n/\n Result of {@link safeFetchToBuffer}: the (capped) body plus the response's\n * content-type, so callers can derive a MIME type and enforce a non-empty\n * content-type check.\n /\nexport type SafeFetchResult = {\n buffer: Buffer;\n contentType: string \| null;\n status: number;\n statusText: string;\n ok: boolean;\n};\n\n/\n SSRF-guarded download: validates the URL (scheme allowlist + post-DNS\n * private-IP deny), performs the request with a timeout via\n * `AbortController`, then streams the body with a hard byte cap — aborting\n * the moment the running total exceeds `maxBytes`. A declared\n * `content-length` over the cap fails fast.\n \n Redirects are NEVER delegated to the platform: every hop is issued with\n * `redirect: \"manual\"` and its `Location` is re-run through\n * {@link assertUrlAllowed} — including the DNS-resolution private-IP check\n * — before being followed (capped at {@link DEFAULT_MAX_REDIRECTS}), so a\n * 3xx from an allowed host cannot smuggle the request to a private /\n * metadata target. Mirrors `@warlock.js/ai`'s `guardedFetch`\n * (ai/src/security/outbound-policy.ts:188-284); duplicated per this\n * module's file-header note since core cannot depend on ai.\n \n @throws {StorageError} On a blocked URL (initial or redirect target),\n * a redirect-hop bound overflow, timeout, or oversized body.\n /\nexport async function safeFetchToBuffer(\n rawUrl: string,\n options: SafeFetchOptions = {},\n): Promise<SafeFetchResult> {\n const policy = resolveFetchPolicy(options);\n let url = await assertUrlAllowed(rawUrl, policy);\n\n const controller = new AbortController();\n const timer = setTimeout(() => {\n controller.abort(\n new StorageError(`outbound request timed out after ${policy.timeoutMs}ms`, {\n context: { url: rawUrl, timeoutMs: policy.timeoutMs },\n }),\n );\n }, policy.timeoutMs);\n\n try {\n let response: Response;\n\n for (let hop = 0; ; hop++) {\n response = await policy.fetch(url, { signal: controller.signal, redirect: \"manual\" });\n\n const location = response.headers.get(\"location\");\n if (!REDIRECT_STATUSES.has(response.status) \|\| location === null) {\n break;\n }\n\n if (hop >= DEFAULT_MAX_REDIRECTS) {\n throw new StorageError(\n `outbound request blocked — more than ${DEFAULT_MAX_REDIRECTS} redirects`,\n { context: { url: rawUrl, maxRedirects: DEFAULT_MAX_REDIRECTS } },\n );\n }\n\n let target: URL;\n try {\n target = new URL(location, url);\n } catch {\n throw new StorageError(\n `outbound request blocked — invalid redirect Location: ${location}`,\n {\n context: { url: url.toString(), location },\n },\n );\n }\n\n // Discard the interim body so the connection can be reused.\n if (response.body) {\n await response.body.cancel().catch(() => undefined);\n }\n\n // The redirect target gets the SAME scheme + private-IP validation\n // (incl. DNS resolution) as the initial URL — this is what closes\n // the redirect-based SSRF bypass: a 302 from an allowed host to\n // 169.254.169.254 is re-validated here, not blindly followed.\n url = await assertUrlAllowed(target.toString(), policy);\n }\n\n const declared = Number(response.headers.get(\"content-length\"));\n if (Number.isFinite(declared) && declared > policy.maxBytes) {\n throw new StorageError(\n `outbound response body too large — declared ${declared} bytes exceeds the ${policy.maxBytes}-byte cap`,\n { context: { url: rawUrl, declared, maxBytes: policy.maxBytes } },\n );\n }\n\n const buffer = await readBodyCapped(response, policy.maxBytes, rawUrl);\n\n return {\n buffer,\n contentType: response.headers.get(\"content-type\"),\n status: response.status,\n statusText: response.statusText,\n ok: response.ok,\n };\n } finally {\n clearTimeout(timer);\n }\n}\n\n/\n Read a response body into a Buffer with a hard byte cap. The stream is\n * read chunk-by-chunk and cancelled the moment the running total exceeds\n * `maxBytes`. Throws {@link StorageError} on overflow.\n */\nasync function readBodyCapped(\n response: Response,\n maxBytes: number,\n rawUrl: string,\n): Promise<Buffer> {\n if (!response.body) {\n const arrayBuffer = await response.arrayBuffer();\n if (arrayBuffer.byteLength > maxBytes) {\n throw new StorageError(`outbound response body exceeded the ${maxBytes}-byte cap`, {\n context: { url: rawUrl, maxBytes },\n });\n }\n return Buffer.from(arrayBuffer);\n }\n\n const reader = response.body.getReader();\n const chunks: Uint8Array[] = [];\n let total = 0;\n\n for (;;) {\n const { done, value } = await reader.read();\n if (done) {\n break;\n }\n if (!value) {\n continue;\n }\n\n total += value.byteLength;\n if (total > maxBytes) {\n await reader.cancel();\n throw new StorageError(`outbound response body exceeded the ${maxBytes}-byte cap`, {\n context: { url: rawUrl, maxBytes },\n });\n }\n chunks.push(value);\n }\n\n return Buffer.concat(chunks);\n}\n"],"mappings":"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"}

package/esm/utils/load-environment.mjs CHANGED Viewed

@@ -1,3 +1,4 @@
+import { recordEnvironmentOverrides } from "./recorded-environment-overrides.mjs";
 import { detectEnvironmentOverrides } from "./detect-environment-overrides.mjs";
 import { reportEnvironmentOverrides } from "./report-environment-overrides.mjs";
 import { loadEnv } from "@mongez/dotenv";
@@ -102,7 +103,9 @@ async function loadEnvironmentFiles(directory = process.cwd()) {
 	if (!candidateEnvFiles(directory).some((file) => existsSync(file))) return;
 	environmentLoaded = true;
 	const processEnvironmentSnapshot = { ...process.env };
-	reportEnvironmentOverrides(detectEnvironmentOverrides(resolveLoadedEnvFiles(directory), processEnvironmentSnapshot));
+	const overrides = detectEnvironmentOverrides(resolveLoadedEnvFiles(directory), processEnvironmentSnapshot);
+	recordEnvironmentOverrides(overrides);
+	reportEnvironmentOverrides(overrides);
 	await loadEnv(void 0, {
 		...environmentLoaderOptions,
 		dir: directory