npm - @warlock.js/core - Versions diffs - 4.3.0 → 4.5.0 - Mend

@warlock.js/core 4.3.0 → 4.5.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 (903) hide show

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

	@@ -1 +1 @@
1	- {"version":3,"file":"storage.mjs","names":[],"sources":["../../../../../../../@warlock.js/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 { storageConfig } 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 type {\n CloudStorageDriverContract,\n CloudStorageDriverOptions,\n DeleteManyResult,\n FileVisibility,\n ListOptions,\n LocalStorageDriverOptions,\n PresignedOptions,\n PresignedUploadOptions,\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 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 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 await events.triggerAll(`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 @param url - Source URL to download from\n * @param location - Destination path\n * @param options - Storage 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?: PutOptions,\n ): Promise<StorageFile> {\n const response = await fetch(url);\n\n if (!response.ok) {\n throw new Error(`Failed to fetch file from URL: ${response.statusText}`);\n }\n\n const arrayBuffer = await response.arrayBuffer();\n const buffer = Buffer.from(arrayBuffer);\n const mimeType = options?.mimeType \|\| response.headers.get(\"content-type\") \|\| undefined;\n\n return this.put(buffer, location, { ...options, 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, maxSize)\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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"}
1	+ {"version":3,"file":"storage.mjs","names":[],"sources":["../../../../../../../@warlock.js/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 { storageConfig } 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 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 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 await events.triggerAll(`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 } =\n 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":"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"}

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

@@ -310,21 +310,49 @@ type PresignedOptions = {
 };
 /**
  * Options for presigned upload URLs
+ *
+ * NOTE: there is intentionally no `maxSize` option. The driver issues a
+ * presigned PUT URL (via `getSignedUrl` + `PutObjectCommand`), which CANNOT
+ * enforce an upload size limit — only a presigned POST policy
+ * (`createPresignedPost` + `ContentLengthRange`) can. A `maxSize` field here
+ * would advertise a guarantee the implementation does not provide, so it was
+ * removed rather than left as a no-op. Enforce size limits server-side (e.g.
+ * verify `metadata().size` after upload) or migrate to presigned POST.
  */
 type PresignedUploadOptions = PresignedOptions & {
   /**
    * File content type
    */
   contentType?: string;
-  /**
-   * Maximum file size in bytes
-   */
-  maxSize?: number;
   /**
    * Custom metadata to store with the file (cloud drivers only)
    */
   metadata?: Record<string, string>;
 };
+/**
+ * Options for `putFromUrl` operations.
+ *
+ * Extends {@link PutOptions} with SSRF / resource-exhaustion guards for the
+ * outbound download. All guard fields are optional and default to the SAFE
+ * (guards-ON) behaviour: https+http only, private/loopback/metadata hosts
+ * denied, a byte cap, and a timeout.
+ */
+type PutFromUrlOptions = PutOptions & {
+  /**
+   * Allow private / loopback / link-local / cloud-metadata hosts. Default
+   * `false` — the SSRF guard is ON.
+   */
+  allowPrivateHosts?: boolean;
+  /**
+   * Maximum downloaded body size in bytes. Default `52_428_800` (50 MiB).
+   */
+  maxBytes?: number; /** Per-request timeout in milliseconds. Default `30_000`. */
+  timeoutMs?: number;
+  /**
+   * URL schemes permitted for the download. Default `["https", "http"]`.
+   */
+  allowedSchemes?: string[];
+};
 /**
  * Options for put operations
  */
@@ -963,5 +991,5 @@ interface EventSubscription {
   unsubscribe(): void;
 }
 //#endregion
-export { CloudStorageDriverContract, CloudStorageDriverOptions, CloudStorageFileData, DeleteManyResult, EventSubscription, FileVisibility, ListOptions, LocalStorageDriverOptions, PresignedOptions, PresignedUploadOptions, PutDirectoryOptions, PutDirectoryResult, PutOptions, R2StorageDriverOptions, ScopedStorageContract, StorageConfigurations, StorageCopyEventPayload, StorageDriverConfig, StorageDriverContract, StorageDriverName, StorageDriverRegistry, StorageDriverType, StorageEventHandler, StorageEventPayload, StorageEventType, StorageFileData, StorageFileInfo, StorageManagerContract, StoragePutEventPayload, TemporaryTokenError, TemporaryTokenPayload, TemporaryTokenValidation };
+export { CloudStorageDriverContract, CloudStorageDriverOptions, CloudStorageFileData, DeleteManyResult, EventSubscription, FileVisibility, ListOptions, LocalStorageDriverOptions, PresignedOptions, PresignedUploadOptions, PutDirectoryOptions, PutDirectoryResult, PutFromUrlOptions, PutOptions, R2StorageDriverOptions, ScopedStorageContract, StorageConfigurations, StorageCopyEventPayload, StorageDriverConfig, StorageDriverContract, StorageDriverName, StorageDriverRegistry, StorageDriverType, StorageEventHandler, StorageEventPayload, StorageEventType, StorageFileData, StorageFileInfo, StorageManagerContract, StoragePutEventPayload, TemporaryTokenError, TemporaryTokenPayload, TemporaryTokenValidation };
 //# sourceMappingURL=types.d.mts.map

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

	@@ -1 +1 @@
1	- {"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../@warlock.js/core/src/storage/types.ts"],"mappings":";;;;;;;;KASY,yBAAA;EAAyB;;;;EAKnC,IAAA;EAiBA;;;;AAWY;AAQd;;EA3BE,MAAA;EA2BmC;;;;;;EAnBnC,SAAA;EA8DA;;;;;EAxDA,kBAAA;EAiEmB;AAAA;AAOrB;;EAnEE,YAAA;AAAA;;;;KAQU,yBAAA;EA0EV;;AAAM;EAtEN,MAAA;EA8EyB;;;EA1EzB,MAAA;EAkFA;;;EA9EA,WAAA;EA8FA;;AAAM;EA1FN,eAAA;EAgG8B;;;;EA3F9B,QAAA;EA+HiB;;;;;;;EAtHjB,MAAA;EA0GA;;;;;;;AAYiB;AAMnB;;;EA/GE,SAAA;EAmHA;;;EA9GA,KAAA;IACE,UAAA;IACA,cAAA;IACA,UAAA;IACA,iBAAA;EAAA;AAAA;;AA0IK;AAMT;KAzIY,sBAAA,GAAyB,IAAI,CAAC,yBAAA;;;;EAIxC,SAAA;EAiJA;;;AAIM;EAhJN,YAAA;EAsJ6B;;;;;EAhJ7B,MAAA;AAAA;;;;KAQU,eAAA;EAqKR;;;EAjKF,IAAA;EAuKuB;AAMzB;;EAzKE,GAAA;EAyK4B;;;EArK5B,IAAA;EA8Ka;;;EA1Kb,IAAA;EA0KQ;;;EAtKR,QAAA;EA2KA;;AAAK;EAvKL,MAAA;AAAA;;;AAiLS;KA3KC,oBAAA,GAAuB,eAAA;~~EAiLD~~;;;~~EA7KhC~~,MAAA;~~EAiLA~~;;;~~EA7KA~~,MAAA;~~EAqLiB~~;~~AAAA;AAMnB;EAvLE~~,IAAA~~;;;;EAIA~~,SAAA;~~EA4LW~~;;;~~EAxLX~~,YAAA;~~EAoMa;;AAAc;EAhM3B~~,YAAA,GAAe,IAAA;~~EAwMgB~~;;;~~EApM/B~~,eAAA;~~EA4MA~~;;;~~EAxMA~~,YAAA;~~EAkNU;;;EA9MV~~,QAAA,GAAW,MAAA;AAAA~~;AAwNb;;;AAAA~~,~~KAlNY,~~eAAA;~~EAsOE;;;EAlOZ~~,IAAA;~~EAkP0B;;;EA9O1B~~,IAAA~~;EA8MA;;;EA1MA~~,IAAA;~~EAsNA~~;;;~~EAlNA~~,WAAA;~~EA8NA~~;;;~~EA1NA~~,YAAA,GAAe,IAAI;~~EA8NK~~;;;~~EA1NxB~~,QAAA;~~EA8NkC;AAAA;AAQpC;EAlOE~~,IAAA;;;~~AAkOwB;EA9NxB~~,YAAA;~~EAqO0B~~;;;~~EAjO1B~~,OAAA;AAAA;;;;KAMU,WAAA;~~EAgPV~~;;;~~EA5OA~~,SAAA;~~EAgPe~~;~~AAMjB~~;;~~EAlPE~~,KAAA;~~EAsPsB~~;;;~~EAlPtB~~,MAAA;~~EAsPA;;;EAlPA~~,MAAA;AAAA;;;;KAMU,mBAAA;~~EA0PV~~;;;;~~EArPA~~,WAAA;~~EA6PsB;AAMxB;;;;;;;;;EAvPE~~,MAAA,IAAU,YAAA,UAAsB,YAAA;~~EAuPQ;;;;;;AAEvB;EAhPjB~~,UAAA,IACE,QAAA,UACA,KAAA,UACA,IAAA,EA7B2B,WAAA;~~EAiRH~~;;;~~EA9O1B~~,UAAA,GAAa,UAAU;AAAA~~;;;AA0PlB;KApPK~~,kBAAA;~~EAyPiB~~;;;~~EArP3B~~,QAAA,EAJ4B,WAAA;~~EA+PlB~~;;;~~EAtPV~~,MAAA,EAAQ,KAAA;IAAQ,SAAA;IAAmB,KAAA,EAAO,KAAA;EAAA;~~EAsQ1C;;;EAjQA~~,KAAA;AAAA;;;;KAMU,gBAAA;~~EAiSE;AAAA;AAmBd;EAhTE~~,SAAS;AAAA~~;;AAgT2B~~;~~AAStC;KAnTY~~,sBAAA,GAAyB,gBAAA;;;~~AAqTN;EAjT7B~~,WAAA;~~EAsT+B;;;EAlT~~/B,~~OAAA;EA0TS;;;EAtTT,~~QAAA,GAAW,MAAM;AAAA;;;;~~KAMP~~,~~UAAA~~;~~EAoTV~~;;;~~AAAwB~~;~~EA/SxB~~,QAAA;~~EA2ToC~~;;;~~EAvTpC~~,QAAA,GAAW,MAAA;~~EAgUO~~;;;~~EA5TlB~~,YAAA;~~EA2UY~~;;;~~EAvUZ~~,kBAAA;~~EAoVwD~~;;;~~EAhVxD~~,UAAA,GAAa,cAAc;AAAA;;;;KAQjB,qBAAA;~~EA0WuB~~;;;~~EAtWjC~~,IAAA;~~EAmZoC~~;;;~~EA/YpC~~,GAAA;~~EAmagC~~;;;EA/~~ZhC~~,GAAA;AAAA;;;;KAMU,mBAAA;;;;KAUA,wBAAA;~~EA4RV~~;;;~~EAxRA~~,KAAA;~~EAyRE~~;;;~~EArRF~~,KAAA,GAAQ,mBAAA;~~EAwRL~~;;;~~EApRH~~,IAAA;~~EAgSU~~;;;~~EA5RV~~,YAAA;~~EA4RqE~~;;;~~EAxRrE~~,SAAA,GAAY,IAAA;~~EAiSW~~;;;~~EA7RvB~~,QAAA;~~EAsS6B~~;;;~~EAlS7B~~,MAAA,GAAS,qBAAA;~~EA0SiB~~;;;~~EAtS1B~~,OAAA,SAAgB,OAAA,CAAQ,MAAA;~~EA8SiB~~;;;~~EA1SzC~~,SAAA,SAAkB,OAAA,CAAQ,QAAA;AAAA;;;;KAQhB,cAAA;;;;KAOA,gBAAA;;;;KAaA,mBAAA;~~EAoUV~~;;;~~EAhUA~~,MAAA;~~EA2UK;;;EAvUL~~,QAAA~~;EAgVA;;;EA5UA~~,SAAA,EAAW,IAAI;AAAA;;;;KAML,sBAAA,GAAyB,mBAAA;~~EA+Ua~~;;;~~EA3UhD~~,IAAA,GAAO,eAAe;~~EAmWtB~~;;;~~EA/VA~~,IAAA;~~EAwWe~~;;;~~EApWf~~,QAAA;AAAA;;;;KAMU,uBAAA,GAA0B,mBAAA;~~EA2WzB~~;;;~~EAvWX~~,IAAA;~~EAiXwC~~;;;~~EA7WxC~~,EAAA;~~EAiYkD~~;;;~~EA7XlD~~,IAAA,GAAO,eAAe;AAAA;;;;KAMZ,mBAAA,WAA8B,mBAAA,GAAsB,mBAAA,KAC9D,OAAA,EAAS,CAAA,YACC,OAAA;;;;KAOA,gBAAA;~~EAuUN~~;;;~~EAnUJ~~,QAAA;~~EAmU2D~~;;;~~EA/T3D~~,OAAA;~~EAqUE~~;;;~~EAjUF~~,KAAA;AAAA;AAAA,KAKU,iBAAA;;;;;KAMA,mBAAA;~~EAmUV~~;;;~~EA/TA~~,MAAA,EAAQ,iBAAiB;~~EA+Te~~;;;~~EAxTxC~~,IAAA;~~EAmUkC~~;;;~~EA9TlC~~,YAAA;~~EAuUkD;;;EAhUlD~~,MAAA;~~EA4UA~~;;;~~EAxUA~~,MAAA;~~EAgVyD~~;;;~~EA5UzD~~,WAAA;~~EAsVgC~~;;;~~EAlVhC~~,eAAA;~~EA0ViC~~;;;~~EAtVjC~~,QAAA;~~EAiWe~~;;;~~EA7Vf~~,SAAA;~~EA4WiB~~;;;~~EArWjB~~,SAAA;~~EAwWG~~;;;~~EApWH~~,YAAA;AAAA;;;;;;;;;;;;;;;;;UAmBe,qBAAA;;;;;;;;KASL,iBAAA,SAA0B,qBAAA,gCAE5B,qBAAqB;;;;KAKnB,qBAAA;~~EA8TR~~;;;~~EA1TF~~,OAAA,EAAS,iBAAA;~~EA6TN~~;;;~~EAzTH~~,OAAA,EAAS,MAAA,SAAe,mBAAA;~~EA8Td~~;;;~~EA1TV~~,QAAA,SAAiB,OAAA;AAAA;;;;;;;;UAYF,qBAAA;~~EAwTsB~~;;;EAAA,~~SApT5B~~,IAAA,EAAM,iBAAA;~~EAyTyB~~;;;EAAA,~~SApT/B~~,OAAA,EAAS,IAAA,CAAK,mBAAA;~~EAyTkB~~;;;;;;;;~~EA7SzC~~,GAAA,CACE,IAAA,EAAM,MAAA,GAAS,YAAA,YAAwB,QAAA,EACvC,QAAA,UACA,OAAA,GAAU,UAAA,GACT,OAAA,CAAQ,eAAA;~~EAwTyC~~;;;;;;;;;;~~EA5SpD~~,SAAA,CAAU,MAAA,EAAQ,QAAA,EAAU,QAAA,UAAkB,OAAA,GAAU,UAAA,GAAa,OAAA,CAAQ,eAAA;~~EA2T5C;;;;;;;EAlTjC~~,GAAA,CAAI,QAAA,WAAmB,OAAA,CAAQ,MAAA;~~EAuTuB~~;;;;;;;~~EA9StD~~,SAAA,CAAU,QAAA,WAAmB,OAAA,CAAQ,QAAA;~~EAwThC;;;AAA8B;AAWrC;;EA3TE~~,MAAA,CAAO,QAAA,WAAmB,OAAA;EAuUhB;;;;;;EA/TV,UAAA,CAAW,SAAA,aAAsB,OAAA,CAAQ,gBAAA;~~EAkW9B~~;;;;;~~EA3VX~~,eAAA,CAAgB,aAAA,WAAwB,OAAA;~~EAiX7B~~;;;;;;~~EAzWX~~,MAAA,CAAO,QAAA,WAAmB,OAAA;~~EAgTtB~~;;;;;;~~EAtSJ~~,GAAA,CAAI,QAAA;~~EA0TW;;;;;;;EAjTf~~,YAAA,CAAa,QAAA,UAAkB,SAAA,YAAqB,OAAA;~~EAgUzC~~;;;;;;;~~EArTX~~,QAAA,CAAS,QAAA,WAAmB,OAAA,CAAQ,eAAA~~;EAkUlC;;;;;;AASyB;EAlU3B~~,IAAA,CAAK,QAAA,WAAmB,OAAA~~;EAwUQ;;;AAIrB;;;;EAjUX~~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"}
1	+ {"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../@warlock.js/core/src/storage/types.ts"],"mappings":"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"}

package/esm/storage/utils/contain-path.d.mts ADDED Viewed

@@ -0,0 +1,23 @@
+//#region ../@warlock.js/core/src/storage/utils/contain-path.d.ts
+/**
+ * Resolve `location` against `root` and assert the result stays *inside*
+ * `root` — the local-storage path-traversal guard.
+ *
+ * Without this, a `location` like `../../etc/passwd`, `..\..\windows\...`,
+ * an absolute path (`/etc/passwd`, `C:\secret`), or a prefix breakout could
+ * escape the configured storage root and read or clobber arbitrary files on
+ * the host.
+ *
+ * The check compares the relative path from `root` to the resolved target:
+ * if it climbs out (`..` prefix) or is itself absolute (different drive /
+ * root on Windows), the location is rejected.
+ *
+ * @param root - Absolute, normalized storage root.
+ * @param location - Caller-supplied (already prefix-applied) location.
+ * @returns The absolute, contained filesystem path.
+ * @throws {StorageError} When the location escapes `root`.
+ */
+declare function resolveWithinRoot(root: string, location: string): string;
+//#endregion
+export { resolveWithinRoot };
+//# sourceMappingURL=contain-path.d.mts.map

package/esm/storage/utils/contain-path.d.mts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"contain-path.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/core/src/storage/utils/contain-path.ts"],"mappings":";;AAqBA;;;;AAAgE;;;;;;;;;;;;;iBAAhD,iBAAA,CAAkB,IAAA,UAAc,QAAgB"}

package/esm/storage/utils/contain-path.mjs ADDED Viewed

@@ -0,0 +1,35 @@
+import { StorageError } from "./storage-error.mjs";
+import path from "path";
+//#region ../@warlock.js/core/src/storage/utils/contain-path.ts
+/**
+* Resolve `location` against `root` and assert the result stays *inside*
+* `root` — the local-storage path-traversal guard.
+*
+* Without this, a `location` like `../../etc/passwd`, `..\..\windows\...`,
+* an absolute path (`/etc/passwd`, `C:\secret`), or a prefix breakout could
+* escape the configured storage root and read or clobber arbitrary files on
+* the host.
+*
+* The check compares the relative path from `root` to the resolved target:
+* if it climbs out (`..` prefix) or is itself absolute (different drive /
+* root on Windows), the location is rejected.
+*
+* @param root - Absolute, normalized storage root.
+* @param location - Caller-supplied (already prefix-applied) location.
+* @returns The absolute, contained filesystem path.
+* @throws {StorageError} When the location escapes `root`.
+*/
+function resolveWithinRoot(root, location) {
+	const resolved = path.resolve(root, location);
+	const rel = path.relative(root, resolved);
+	if (rel !== "" && (rel.startsWith("..") || path.isAbsolute(rel))) throw new StorageError(`Storage location escapes the storage root: "${location}"`, { context: {
+		location,
+		root
+	} });
+	return resolved;
+}
+//#endregion
+export { resolveWithinRoot };
+//# sourceMappingURL=contain-path.mjs.map

package/esm/storage/utils/contain-path.mjs.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"contain-path.mjs","names":[],"sources":["../../../../../../../../@warlock.js/core/src/storage/utils/contain-path.ts"],"sourcesContent":["import path from \"path\";\nimport { StorageError } from \"./storage-error\";\n\n/**\n * Resolve `location` against `root` and assert the result stays *inside*\n * `root` — the local-storage path-traversal guard.\n *\n * Without this, a `location` like `../../etc/passwd`, `..\\..\\windows\\...`,\n * an absolute path (`/etc/passwd`, `C:\\secret`), or a prefix breakout could\n * escape the configured storage root and read or clobber arbitrary files on\n * the host.\n *\n * The check compares the relative path from `root` to the resolved target:\n * if it climbs out (`..` prefix) or is itself absolute (different drive /\n * root on Windows), the location is rejected.\n *\n * @param root - Absolute, normalized storage root.\n * @param location - Caller-supplied (already prefix-applied) location.\n * @returns The absolute, contained filesystem path.\n * @throws {StorageError} When the location escapes `root`.\n */\nexport function resolveWithinRoot(root: string, location: string): string {\n const resolved = path.resolve(root, location);\n const rel = path.relative(root, resolved);\n\n if (rel !== \"\" && (rel.startsWith(\"..\") || path.isAbsolute(rel))) {\n throw new StorageError(\n `Storage location escapes the storage root: \"${location}\"`,\n { context: { location, root } },\n );\n }\n\n return resolved;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,kBAAkB,MAAc,UAA0B;CACxE,MAAM,WAAW,KAAK,QAAQ,MAAM,QAAQ;CAC5C,MAAM,MAAM,KAAK,SAAS,MAAM,QAAQ;CAExC,IAAI,QAAQ,OAAO,IAAI,WAAW,IAAI,KAAK,KAAK,WAAW,GAAG,IAC5D,MAAM,IAAI,aACR,+CAA+C,SAAS,IACxD,EAAE,SAAS;EAAE;EAAU;CAAK,EAAE,CAChC;CAGF,OAAO;AACT"}

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

@@ -0,0 +1,68 @@
+//#region ../@warlock.js/core/src/storage/utils/safe-fetch.d.ts
+/**
+ * Options controlling a guarded outbound fetch. Every field is optional;
+ * {@link resolveFetchPolicy} fills safe defaults. The defaults are
+ * deliberately strict (https+http, private-IP deny ON, 30s timeout,
+ * 50 MiB cap) so a caller that does not tune them still gets a hardened
+ * request.
+ */
+type SafeFetchOptions = {
+  /**
+   * Whether to ALLOW private / loopback / link-local / metadata hosts.
+   * Default `false` — the SSRF guard is on (private hosts are denied).
+   */
+  allowPrivateHosts?: boolean;
+  /**
+   * Maximum response body size in bytes. A declared `content-length` over
+   * this fails fast; otherwise the body is read with a running cap and the
+   * stream is aborted on overflow. Default `52_428_800` (50 MiB).
+   */
+  maxBytes?: number; /** Per-request timeout in milliseconds. Default `30_000`. */
+  timeoutMs?: number;
+  /**
+   * URL schemes permitted for the request, compared case-insensitively.
+   * Default `["https", "http"]`.
+   */
+  allowedSchemes?: string[];
+  /**
+   * Injected `fetch` implementation (for tests or proxies). Defaults to the
+   * global `fetch`.
+   */
+  fetch?: typeof fetch;
+};
+/**
+ * True when `ip` is a private, loopback, link-local, unique-local,
+ * carrier-grade-NAT, unspecified, or otherwise non-public address — the set
+ * an SSRF guard must refuse. Accepts IPv4 and IPv6 literals (including
+ * IPv4-mapped IPv6 like `::ffff:169.254.169.254`). A non-IP string returns
+ * `false` (the caller resolves hostnames via DNS first).
+ *
+ * The cloud-metadata endpoint `169.254.169.254` is covered by the IPv4
+ * link-local range `169.254.0.0/16`.
+ */
+declare function isPrivateOrReservedIp(ip: string): boolean;
+/**
+ * Result of {@link safeFetchToBuffer}: the (capped) body plus the response's
+ * content-type, so callers can derive a MIME type and enforce a non-empty
+ * content-type check.
+ */
+type SafeFetchResult = {
+  buffer: Buffer;
+  contentType: string | null;
+  status: number;
+  statusText: string;
+  ok: boolean;
+};
+/**
+ * SSRF-guarded download: validates the URL (scheme allowlist + post-DNS
+ * private-IP deny), performs the request with a timeout via
+ * `AbortController`, then streams the body with a hard byte cap — aborting
+ * the moment the running total exceeds `maxBytes`. A declared
+ * `content-length` over the cap fails fast.
+ *
+ * @throws {StorageError} On a blocked URL, timeout, or oversized body.
+ */
+declare function safeFetchToBuffer(rawUrl: string, options?: SafeFetchOptions): Promise<SafeFetchResult>;
+//#endregion
+export { SafeFetchOptions, SafeFetchResult, isPrivateOrReservedIp, safeFetchToBuffer };
+//# sourceMappingURL=safe-fetch.d.mts.map

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

@@ -0,0 +1 @@

+ {"version":3,"file":"safe-fetch.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/core/src/storage/utils/safe-fetch.ts"],"mappings":";;AA0BA;;;;;;KAAY,gBAAA;EAkBV;;;;EAbA,iBAAA;EA2Hc;;;;AAAgC;EArH9C,QAAA,WAgNyB;EA9MzB,SAAA;EA+Mc;;;;EA1Md,cAAA;EA6MA;;;AACE;EAzMF,KAAA,UAAe,KAAK;AAAA;;;;;;;;;;;iBAyGN,qBAAA,CAAsB,EAAU;;AA+GtB;;;;KApBd,eAAA;EACV,MAAA,EAAQ,MAAM;EACd,WAAA;EACA,MAAA;EACA,UAAA;EACA,EAAA;AAAA;;;;;;;;;;iBAYoB,iBAAA,CACpB,MAAA,UACA,OAAA,GAAS,gBAAA,GACR,OAAA,CAAQ,eAAA"}