express-storage 2.0.2 → 3.0.0

package/dist/drivers/gcs.driver.js

@@ -1,354 +0,0 @@
-import { Storage } from '@google-cloud/storage';
-import { BaseStorageDriver } from './base.driver.js';
-/**
- * GCSStorageDriver - Handles file operations with Google Cloud Storage.
- *
- * Supports two authentication methods:
- * 1. Service account JSON file (GCS_CREDENTIALS path)
- * 2. Application Default Credentials (when running on GCP)
- *
- * If you're running on GCP (Cloud Run, GKE, etc.), you usually don't need
- * to provide credentials — the SDK picks them up automatically.
- */
-export class GCSStorageDriver extends BaseStorageDriver {
-    constructor(config) {
-        super(config);
-        this.bucketName = config.bucketName;
-        this.projectId = config.gcsProjectId;
-        const storageOptions = {
-            projectId: this.projectId,
-        };
-        if (config.gcsCredentials) {
-            storageOptions.keyFilename = config.gcsCredentials;
-        }
-        this.storage = new Storage(storageOptions);
-        this.bucket = this.storage.bucket(this.bucketName);
-    }
-    /**
-     * Uploads a file directly to GCS.
-     * Handles both memory and disk storage from Multer.
-     *
-     * For large files (>100MB), uses streaming upload to reduce
-     * memory usage and improve reliability.
-     */
-    async upload(file, options) {
-        try {
-            const validationErrors = this.validateFile(file);
-            if (validationErrors.length > 0) {
-                return this.createErrorResult(validationErrors.join(', '));
-            }
-            const fileName = this.generateFileName(file.originalname);
-            const filePath = this.buildFilePath(fileName);
-            const gcsFile = this.bucket.file(filePath);
-            const metadata = {
-                contentType: options?.contentType || file.mimetype,
-            };
-            if (options?.cacheControl) {
-                metadata.cacheControl = options.cacheControl;
-            }
-            if (options?.contentDisposition) {
-                metadata.contentDisposition = options.contentDisposition;
-            }
-            if (options?.metadata) {
-                metadata.metadata = options.metadata;
-            }
-            // Use streaming upload for large files to reduce memory usage
-            if (this.shouldUseStreaming(file)) {
-                await this.uploadWithStream(gcsFile, file, metadata);
-            }
-            else {
-                const fileContent = this.getFileContent(file);
-                await gcsFile.save(fileContent, { metadata });
-            }
-            // Build the public URL with proper encoding
-            const encodedPath = filePath.split('/').map(segment => encodeURIComponent(segment)).join('/');
-            const fileUrl = `https://storage.googleapis.com/${this.bucketName}/${encodedPath}`;
-            return this.createSuccessResult(filePath, fileUrl);
-        }
-        catch (error) {
-            return this.createErrorResult(error instanceof Error ? error.message : 'Failed to upload file to GCS');
-        }
-    }
-    /**
-     * Uploads a large file using streaming.
-     *
-     * This method pipes the file stream directly to GCS, which is more
-     * memory-efficient for large files.
-     */
-    async uploadWithStream(gcsFile, file, metadata) {
-        return new Promise((resolve, reject) => {
-            const fileStream = this.getFileStream(file);
-            const writeStream = gcsFile.createWriteStream({
-                metadata,
-                resumable: true, // Enable resumable uploads for reliability
-            });
-            // Handle errors from the source stream (fileStream) explicitly
-            // to ensure they propagate and don't get silently dropped
-            fileStream.on('error', reject);
-            fileStream
-                .pipe(writeStream)
-                .on('error', reject)
-                .on('finish', resolve);
-        });
-    }
-    /**
-     * Creates a presigned URL for uploading directly to GCS.
-     *
-     * The URL enforces:
-     * - Exact content type
-     * - Exact file size (via x-goog-content-length-range header)
-     *
-     * Clients that try to upload different content will get a 403.
-     */
-    async generateUploadUrl(fileName, contentType, fileSize) {
-        // Security: Defense-in-depth validation (StorageManager also validates)
-        // Decode URL-encoded characters first to catch encoded traversal attempts like %2e%2e%2f
-        let decodedFileName;
-        try {
-            decodedFileName = decodeURIComponent(fileName);
-        }
-        catch {
-            return this.createPresignedErrorResult('Invalid fileName: malformed URL encoding');
-        }
-        if (decodedFileName.includes('..') || decodedFileName.includes('\0')) {
-            return this.createPresignedErrorResult('Invalid fileName: path traversal sequences are not allowed');
-        }
-        try {
-            const gcsFile = this.bucket.file(decodedFileName);
-            const resolvedContentType = contentType || 'application/octet-stream';
-            const expiresOn = new Date(Date.now() + (this.getPresignedUrlExpiry() * 1000));
-            const options = {
-                version: 'v4',
-                action: 'write',
-                expires: expiresOn,
-                contentType: resolvedContentType,
-            };
-            // GCS enforces exact file size via this header
-            if (fileSize !== undefined) {
-                options.extensionHeaders = {
-                    'x-goog-content-length-range': `${fileSize},${fileSize}`,
-                };
-            }
-            const [uploadUrl] = await gcsFile.getSignedUrl(options);
-            return this.createPresignedSuccessResult(uploadUrl);
-        }
-        catch (error) {
-            return this.createPresignedErrorResult(error instanceof Error ? error.message : 'Failed to generate upload URL');
-        }
-    }
-    /**
-     * Creates a presigned URL for downloading/viewing a file.
-     */
-    async generateViewUrl(fileName) {
-        // Security: Defense-in-depth validation
-        // Decode URL-encoded characters first to catch encoded traversal attempts like %2e%2e%2f
-        let decodedFileName;
-        try {
-            decodedFileName = decodeURIComponent(fileName);
-        }
-        catch {
-            return this.createPresignedErrorResult('Invalid fileName: malformed URL encoding');
-        }
-        if (decodedFileName.includes('..') || decodedFileName.includes('\0')) {
-            return this.createPresignedErrorResult('Invalid fileName: path traversal sequences are not allowed');
-        }
-        try {
-            const gcsFile = this.bucket.file(decodedFileName);
-            const expiresOn = new Date(Date.now() + (this.getPresignedUrlExpiry() * 1000));
-            const [viewUrl] = await gcsFile.getSignedUrl({
-                version: 'v4',
-                action: 'read',
-                expires: expiresOn,
-            });
-            return this.createPresignedSuccessResult(undefined, viewUrl);
-        }
-        catch (error) {
-            return this.createPresignedErrorResult(error instanceof Error ? error.message : 'Failed to generate view URL');
-        }
-    }
-    /**
-     * Deletes a file from GCS.
-     * Returns false if the file doesn't exist, throws on real errors.
-     */
-    async delete(fileName) {
-        // Security: Defense-in-depth validation
-        // Decode URL-encoded characters first to catch encoded traversal attempts like %2e%2e%2f
-        let decodedFileName;
-        try {
-            decodedFileName = decodeURIComponent(fileName);
-        }
-        catch {
-            return false;
-        }
-        if (decodedFileName.includes('..') || decodedFileName.includes('\0')) {
-            return false;
-        }
-        const gcsFile = this.bucket.file(decodedFileName);
-        const [exists] = await gcsFile.exists();
-        if (!exists) {
-            return false;
-        }
-        await gcsFile.delete();
-        return true;
-    }
-    /**
-     * Confirms an upload and optionally validates the file.
-     *
-     * For GCS, validation is optional since constraints are enforced at URL level.
-     * But you can still use this to verify the file matches expectations.
-     */
-    async validateAndConfirmUpload(reference, options) {
-        const deleteOnFailure = options?.deleteOnFailure !== false;
-        try {
-            const gcsFile = this.bucket.file(reference);
-            const [metadata] = await gcsFile.getMetadata();
-            const actualContentType = metadata.contentType;
-            let actualFileSize;
-            if (metadata.size !== undefined) {
-                const parsed = typeof metadata.size === 'string' ? parseInt(metadata.size, 10) : metadata.size;
-                actualFileSize = Number.isNaN(parsed) ? undefined : parsed;
-            }
-            // Validate content type if expected
-            if (options?.expectedContentType && actualContentType !== options.expectedContentType) {
-                if (deleteOnFailure) {
-                    await this.delete(reference);
-                }
-                const errorResult = {
-                    success: false,
-                    error: `Content type mismatch: expected '${options.expectedContentType}', got '${actualContentType}'${deleteOnFailure ? ' (file deleted)' : ' (file kept for inspection)'}`,
-                };
-                if (actualContentType)
-                    errorResult.actualContentType = actualContentType;
-                if (actualFileSize !== undefined)
-                    errorResult.actualFileSize = actualFileSize;
-                return errorResult;
-            }
-            // Validate file size if expected
-            if (options?.expectedFileSize !== undefined && actualFileSize !== options.expectedFileSize) {
-                if (deleteOnFailure) {
-                    await this.delete(reference);
-                }
-                const errorResult = {
-                    success: false,
-                    error: `File size mismatch: expected ${options.expectedFileSize} bytes, got ${actualFileSize} bytes${deleteOnFailure ? ' (file deleted)' : ' (file kept for inspection)'}`,
-                };
-                if (actualContentType)
-                    errorResult.actualContentType = actualContentType;
-                if (actualFileSize !== undefined)
-                    errorResult.actualFileSize = actualFileSize;
-                return errorResult;
-            }
-            const viewResult = await this.generateViewUrl(reference);
-            const result = {
-                success: true,
-                reference,
-                expiresIn: this.getPresignedUrlExpiry(),
-            };
-            if (viewResult.viewUrl) {
-                result.viewUrl = viewResult.viewUrl;
-            }
-            if (actualContentType) {
-                result.actualContentType = actualContentType;
-            }
-            if (actualFileSize !== undefined) {
-                result.actualFileSize = actualFileSize;
-            }
-            return result;
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'File not found or access denied';
-            return {
-                success: false,
-                error: errorMessage,
-            };
-        }
-    }
-    /**
-     * Lists files in the bucket with optional prefix filtering and pagination.
-     */
-    async listFiles(prefix, maxResults = 1000, continuationToken) {
-        try {
-            const validatedMaxResults = Math.floor(Math.max(1, Math.min(Number.isNaN(maxResults) ? 1000 : maxResults, 1000)));
-            const options = {
-                maxResults: validatedMaxResults,
-            };
-            if (prefix)
-                options.prefix = prefix;
-            if (continuationToken)
-                options.pageToken = continuationToken;
-            const [files, , apiResponse] = await this.bucket.getFiles(options);
-            const fileList = files.map((file) => {
-                const fileInfo = { name: file.name };
-                if (file.metadata.size) {
-                    const parsed = parseInt(String(file.metadata.size), 10);
-                    if (!Number.isNaN(parsed)) {
-                        fileInfo.size = parsed;
-                    }
-                }
-                if (file.metadata.contentType) {
-                    fileInfo.contentType = file.metadata.contentType;
-                }
-                if (file.metadata.updated) {
-                    fileInfo.lastModified = new Date(file.metadata.updated);
-                }
-                return fileInfo;
-            });
-            const result = {
-                success: true,
-                files: fileList,
-            };
-            const responseWithToken = apiResponse;
-            if (responseWithToken?.nextPageToken) {
-                result.nextToken = responseWithToken.nextPageToken;
-            }
-            return result;
-        }
-        catch (error) {
-            return {
-                success: false,
-                error: error instanceof Error ? error.message : 'Failed to list files',
-            };
-        }
-    }
-}
-/**
- * GCSPresignedStorageDriver - GCS driver that returns presigned URLs from upload().
- *
- * Use this when you want clients to upload directly to GCS without
- * the file passing through your server.
- */
-export class GCSPresignedStorageDriver extends GCSStorageDriver {
-    constructor(config) {
-        super(config);
-    }
-    /**
-     * Instead of uploading the file, returns a presigned URL for the client to use.
-     *
-     * The returned fileUrl is the presigned upload URL.
-     * After the client uploads, use validateAndConfirmUpload() to get a view URL.
-     *
-     * Note: The `options` parameter (metadata, cacheControl, etc.) is NOT applied
-     * when using presigned uploads. These options must be set by the client when
-     * making the actual upload request to GCS, or configured via bucket settings.
-     * For server-side uploads with full options support, use the regular 'gcs' driver.
-     */
-    async upload(file, _options) {
-        try {
-            const validationErrors = this.validateFile(file);
-            if (validationErrors.length > 0) {
-                return this.createErrorResult(validationErrors.join(', '));
-            }
-            const fileName = this.generateFileName(file.originalname);
-            const filePath = this.buildFilePath(fileName);
-            const presignedResult = await this.generateUploadUrl(filePath, file.mimetype, file.size);
-            if (!presignedResult.success) {
-                return this.createErrorResult(presignedResult.error || 'Failed to generate presigned URL');
-            }
-            return this.createSuccessResult(filePath, presignedResult.uploadUrl);
-        }
-        catch (error) {
-            return this.createErrorResult(error instanceof Error ? error.message : 'Failed to generate presigned URL');
-        }
-    }
-}
-//# sourceMappingURL=gcs.driver.js.map

package/dist/drivers/gcs.driver.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"gcs.driver.js","sourceRoot":"","sources":["../../src/drivers/gcs.driver.ts"],"names":[],"mappings":"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"}

package/dist/drivers/local.driver.d.ts

@@ -1,107 +0,0 @@
-import { BaseStorageDriver } from './base.driver.js';
-import { FileUploadResult, PresignedUrlResult, StorageConfig, ListFilesResult, UploadOptions } from '../types/storage.types.js';
-/**
- * LocalStorageDriver - Saves files to your local filesystem.
- *
- * Great for development and small-scale applications.
- * Files are organized by year/month folders automatically.
- *
- * **Security features:**
- * - Path traversal prevention (blocks ../ and null bytes)
- * - Symlinks are NOT followed or deleted (prevents directory escape attacks)
- * - Magic byte detection for content-type validation (prevents extension spoofing)
- * - Files stay within the configured base directory
- *
- * **Symlink behavior:** This driver explicitly rejects symlinks for security.
- * If a file is a symlink, it will not be read, deleted, or listed. This prevents
- * attackers from using symlinks to access files outside the storage directory.
- *
- * Note: Local storage doesn't support presigned URLs since
- * there's no external service to sign requests against.
- */
-export declare class LocalStorageDriver extends BaseStorageDriver {
-    private basePath;
-    constructor(config: StorageConfig);
-    /**
-     * Saves a file to the local filesystem.
-     *
-     * Files are automatically organized into YYYY/MM folders.
-     * For example, a file uploaded in January 2026 goes into:
-     * {basePath}/2026/01/{unique_filename}.jpg
-     *
-     * For large files (>100MB), uses streaming to reduce memory usage
-     * and prevent application crashes.
-     */
-    upload(file: Express.Multer.File, _options?: UploadOptions): Promise<FileUploadResult>;
-    /**
-     * Uploads a large file using streaming.
-     *
-     * This method pipes the file stream directly to disk, which is more
-     * memory-efficient for large files (>100MB).
-     */
-    private uploadWithStream;
-    /**
-     * Builds a URL for accessing the file.
-     *
-     * If your basePath starts with 'public/', we strip that prefix
-     * since Express.static('public') serves files from /
-     *
-     * Example: public/uploads/2026/01/photo.jpg -> /uploads/2026/01/photo.jpg
-     */
-    private generateFileUrl;
-    /**
-     * Converts Windows backslashes to forward slashes.
-     */
-    private normalizePathSeparators;
-    /**
-     * Removes duplicate slashes from URLs.
-     */
-    private normalizeUrl;
-    /**
-     * Local storage doesn't support presigned upload URLs.
-     */
-    generateUploadUrl(_fileName: string, _contentType?: string, _maxSize?: number): Promise<PresignedUrlResult>;
-    /**
-     * Local storage doesn't support presigned view URLs.
-     */
-    generateViewUrl(_fileName: string): Promise<PresignedUrlResult>;
-    /**
-     * Validates a local file exists and matches expected values.
-     *
-     * Content type detection uses a two-tier approach:
-     * 1. Magic byte detection (examines actual file content for security)
-     * 2. Extension-based fallback (when magic bytes don't match)
-     *
-     * This helps detect extension spoofing attacks where a malicious file
-     * is renamed with an innocent extension (e.g., malware.exe -> photo.jpg).
-     */
-    validateAndConfirmUpload(reference: string, options?: import('../types/storage.types.js').BlobValidationOptions): Promise<import('../types/storage.types.js').BlobValidationResult>;
-    /**
-     * Deletes a file from local storage.
-     *
-     * Security checks:
-     * - Rejects path traversal attempts (../ sequences)
-     * - Rejects null bytes in paths
-     * - Verifies target stays within base directory
-     * - Won't follow or delete symlinks (security: prevents directory escape attacks)
-     * - Only deletes regular files (not directories)
-     *
-     * @param reference - The file path relative to the storage base directory
-     * @returns true if file was deleted, false if not found or security check failed
-     */
-    delete(reference: string): Promise<boolean>;
-    /**
-     * Safely resolves a reference to a file path within our base directory.
-     * Returns null for any suspicious input.
-     */
-    private resolveFilePath;
-    /**
-     * Lists files in local storage with optional prefix filtering and pagination.
-     *
-     * Uses early termination to avoid loading all files into memory when possible.
-     * Files are collected in sorted order and iteration stops once we have enough
-     * results for the requested page.
-     */
-    listFiles(prefix?: string, maxResults?: number, continuationToken?: string): Promise<ListFilesResult>;
-}
-//# sourceMappingURL=local.driver.d.ts.map

package/dist/drivers/local.driver.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"local.driver.d.ts","sourceRoot":"","sources":["../../src/drivers/local.driver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,aAAa,EAAE,eAAe,EAAE,aAAa,EAAY,MAAM,2BAA2B,CAAC;AA0I1I;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,kBAAmB,SAAQ,iBAAiB;IACvD,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,EAAE,aAAa;IAKjC;;;;;;;;;OASG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwC5F;;;;;OAKG;YACW,gBAAgB;IAmC9B;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAiBvB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAI/B;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;OAEG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMjH;;OAEG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMrE;;;;;;;;;OASG;IACY,wBAAwB,CACrC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,OAAO,2BAA2B,EAAE,qBAAqB,GAClE,OAAO,CAAC,OAAO,2BAA2B,EAAE,oBAAoB,CAAC;IAgFpE;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiDjD;;;OAGG;IACH,OAAO,CAAC,eAAe;IAuCvB;;;;;;OAMG;IACG,SAAS,CACb,MAAM,CAAC,EAAE,MAAM,EACf,UAAU,GAAE,MAAa,EACzB,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,eAAe,CAAC;CA2L5B"}