express-storage 2.0.2 → 3.0.0

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

@@ -0,0 +1,343 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GCSStorageDriver = void 0;
+const base_driver_js_1 = require("./base.driver.js");
+const file_utils_js_1 = require("../utils/file.utils.js");
+function parseGcsFileSize(size) {
+    if (size === undefined || size === null)
+        return undefined;
+    const parsed = typeof size === 'string' ? parseInt(size, 10) : Number(size);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+// Lazy SDK loader — module is imported on first use, not at import time.
+let _gcsMod;
+function loadGCSSDK() {
+    if (!_gcsMod) {
+        _gcsMod = Promise.resolve().then(() => __importStar(require('@google-cloud/storage'))).catch(() => {
+            _gcsMod = undefined;
+            throw new Error('@google-cloud/storage is required for GCS storage.\n' +
+                'Install: npm install @google-cloud/storage');
+        });
+    }
+    return _gcsMod;
+}
+/**
+ * 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.
+ *
+ * When driver is 'gcs-presigned', upload() returns presigned URLs
+ * instead of uploading directly.
+ *
+ * Required package: @google-cloud/storage
+ */
+class GCSStorageDriver extends base_driver_js_1.BaseStorageDriver {
+    _storage;
+    _bucket;
+    bucketName;
+    projectId;
+    constructor(config) {
+        super(config);
+        if (!config.bucketName) {
+            throw new Error('bucketName is required for GCS. Set BUCKET_NAME environment variable or pass bucketName in credentials.');
+        }
+        if (!config.gcsProjectId) {
+            throw new Error('gcsProjectId is required for GCS. Set GCS_PROJECT_ID environment variable or pass gcsProjectId in credentials.');
+        }
+        this.bucketName = config.bucketName;
+        this.projectId = config.gcsProjectId;
+    }
+    async ensureBucket() {
+        if (this._bucket)
+            return this._bucket;
+        const { Storage } = await loadGCSSDK();
+        const storageOptions = {
+            projectId: this.projectId,
+        };
+        if (this.config.gcsCredentials) {
+            storageOptions.keyFilename = this.config.gcsCredentials;
+        }
+        this._storage = new Storage(storageOptions);
+        this._bucket = this._storage.bucket(this.bucketName);
+        return this._bucket;
+    }
+    destroy() {
+        this._storage = undefined;
+        this._bucket = undefined;
+    }
+    /**
+     * Uploads a file to GCS, or returns a presigned URL when in presigned mode.
+     *
+     * For large files (>100MB), uses streaming upload to reduce
+     * memory usage and improve reliability.
+     */
+    async upload(file, options) {
+        if (this.presignedMode) {
+            return this.presignedUpload(file);
+        }
+        try {
+            const { errors: validationErrors, resolvedSize } = await this.validateFile(file);
+            if (validationErrors.length > 0) {
+                return this.createErrorResult(validationErrors.join(', '), 'VALIDATION_FAILED');
+            }
+            const fileName = this.generateFileName(file.originalname);
+            const filePath = this.buildFilePath(fileName);
+            const bucket = await this.ensureBucket();
+            const gcsFile = 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;
+            }
+            options?.signal?.throwIfAborted();
+            if (this.shouldUseStreaming(resolvedSize)) {
+                await this.uploadWithStream(gcsFile, file, metadata);
+            }
+            else {
+                const fileContent = await this.getFileContent(file);
+                await gcsFile.save(fileContent, { metadata });
+            }
+            const fileUrl = `https://storage.googleapis.com/${this.bucketName}/${(0, file_utils_js_1.encodePathSegments)(filePath)}`;
+            return this.createSuccessResult(filePath, fileUrl);
+        }
+        catch (error) {
+            await this.cleanupTempFile(file);
+            return this.createErrorResult(error instanceof Error ? error.message : 'Failed to upload file to GCS');
+        }
+    }
+    /**
+     * Uploads a large file using streaming.
+     * Pipes the file stream directly to GCS for memory efficiency.
+     */
+    async uploadWithStream(gcsFile, file, metadata) {
+        return new Promise((resolve, reject) => {
+            const fileStream = this.getFileStream(file);
+            const writeStream = gcsFile.createWriteStream({
+                metadata,
+                resumable: true,
+            });
+            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)
+     */
+    async generateUploadUrl(fileName, contentType, fileSize) {
+        try {
+            const decodedFileName = this.decodeFileName(fileName);
+            const bucket = await this.ensureBucket();
+            const gcsFile = 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,
+            };
+            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) {
+        try {
+            const decodedFileName = this.decodeFileName(fileName);
+            const bucket = await this.ensureBucket();
+            const gcsFile = 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.
+     */
+    async delete(fileName) {
+        try {
+            const decodedFileName = this.decodeFileName(fileName);
+            const bucket = await this.ensureBucket();
+            const gcsFile = bucket.file(decodedFileName);
+            const [exists] = await gcsFile.exists();
+            if (!exists) {
+                return { success: false, reference: fileName, error: 'File not found', code: 'FILE_NOT_FOUND' };
+            }
+            await gcsFile.delete();
+            return { success: true, reference: fileName };
+        }
+        catch (error) {
+            return { success: false, reference: fileName, error: error instanceof Error ? error.message : 'Failed to delete file', code: 'PROVIDER_ERROR' };
+        }
+    }
+    /**
+     * Confirms an upload and optionally validates the file.
+     * Uses shared validation logic from BaseStorageDriver.
+     */
+    async validateAndConfirmUpload(reference, options) {
+        try {
+            const bucket = await this.ensureBucket();
+            const gcsFile = bucket.file(reference);
+            const [metadata] = await gcsFile.getMetadata();
+            const actual = {
+                contentType: metadata.contentType,
+                fileSize: parseGcsFileSize(metadata.size),
+            };
+            const validationError = await this.checkUploadedFileMetadata(reference, actual, options);
+            if (validationError)
+                return validationError;
+            const viewResult = await this.generateViewUrl(reference);
+            return this.buildValidationSuccess(reference, viewResult.success ? viewResult.viewUrl : undefined, actual.contentType, actual.fileSize);
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'File not found or access denied',
+                code: 'FILE_NOT_FOUND',
+            };
+        }
+    }
+    /**
+     * Returns metadata about a file from GCS without downloading it.
+     */
+    async getMetadata(reference) {
+        try {
+            const decoded = this.decodeFileName(reference);
+            const bucket = await this.ensureBucket();
+            const gcsFile = bucket.file(decoded);
+            const [exists] = await gcsFile.exists();
+            if (!exists)
+                return null;
+            const [metadata] = await gcsFile.getMetadata();
+            const info = { name: reference };
+            const size = parseGcsFileSize(metadata.size);
+            if (size !== undefined)
+                info.size = size;
+            if (metadata.contentType)
+                info.contentType = metadata.contentType;
+            if (metadata.updated)
+                info.lastModified = new Date(metadata.updated);
+            return info;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Lists files in the bucket with optional prefix filtering and pagination.
+     */
+    async listFiles(prefix, maxResults = 1000, continuationToken) {
+        try {
+            const validatedMaxResults = this.validateMaxResults(maxResults);
+            const bucket = await this.ensureBucket();
+            const options = {
+                maxResults: validatedMaxResults,
+            };
+            if (prefix)
+                options.prefix = prefix;
+            if (continuationToken)
+                options.pageToken = continuationToken;
+            const [files, , apiResponse] = await bucket.getFiles(options);
+            const fileList = files.map((file) => {
+                const fileInfo = { name: file.name };
+                const size = parseGcsFileSize(file.metadata.size);
+                if (size !== undefined)
+                    fileInfo.size = size;
+                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',
+                code: 'PROVIDER_ERROR',
+            };
+        }
+    }
+}
+exports.GCSStorageDriver = GCSStorageDriver;
+//# sourceMappingURL=gcs.driver.js.map

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

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

package/dist/cjs/drivers/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * express-storage/drivers
+ *
+ * Driver classes, factory, and base class for custom driver implementations.
+ *
+ * @example
+ * import { BaseStorageDriver, createDriver } from 'express-storage/drivers';
+ */
+export { BaseStorageDriver } from './base.driver.js';
+export { LocalStorageDriver } from './local.driver.js';
+export { S3StorageDriver } from './s3.driver.js';
+export { GCSStorageDriver } from './gcs.driver.js';
+export { AzureStorageDriver } from './azure.driver.js';
+export { StorageDriverFactory, createDriver, getAvailableDrivers } from '../factory/driver.factory.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/drivers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/drivers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/cjs/drivers/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * express-storage/drivers
+ *
+ * Driver classes, factory, and base class for custom driver implementations.
+ *
+ * @example
+ * import { BaseStorageDriver, createDriver } from 'express-storage/drivers';
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAvailableDrivers = exports.createDriver = exports.StorageDriverFactory = exports.AzureStorageDriver = exports.GCSStorageDriver = exports.S3StorageDriver = exports.LocalStorageDriver = exports.BaseStorageDriver = void 0;
+var base_driver_js_1 = require("./base.driver.js");
+Object.defineProperty(exports, "BaseStorageDriver", { enumerable: true, get: function () { return base_driver_js_1.BaseStorageDriver; } });
+var local_driver_js_1 = require("./local.driver.js");
+Object.defineProperty(exports, "LocalStorageDriver", { enumerable: true, get: function () { return local_driver_js_1.LocalStorageDriver; } });
+var s3_driver_js_1 = require("./s3.driver.js");
+Object.defineProperty(exports, "S3StorageDriver", { enumerable: true, get: function () { return s3_driver_js_1.S3StorageDriver; } });
+var gcs_driver_js_1 = require("./gcs.driver.js");
+Object.defineProperty(exports, "GCSStorageDriver", { enumerable: true, get: function () { return gcs_driver_js_1.GCSStorageDriver; } });
+var azure_driver_js_1 = require("./azure.driver.js");
+Object.defineProperty(exports, "AzureStorageDriver", { enumerable: true, get: function () { return azure_driver_js_1.AzureStorageDriver; } });
+var driver_factory_js_1 = require("../factory/driver.factory.js");
+Object.defineProperty(exports, "StorageDriverFactory", { enumerable: true, get: function () { return driver_factory_js_1.StorageDriverFactory; } });
+Object.defineProperty(exports, "createDriver", { enumerable: true, get: function () { return driver_factory_js_1.createDriver; } });
+Object.defineProperty(exports, "getAvailableDrivers", { enumerable: true, get: function () { return driver_factory_js_1.getAvailableDrivers; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/drivers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/drivers/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,mDAAqD;AAA5C,mHAAA,iBAAiB,OAAA;AAC1B,qDAAuD;AAA9C,qHAAA,kBAAkB,OAAA;AAC3B,+CAAiD;AAAxC,+GAAA,eAAe,OAAA;AACxB,iDAAmD;AAA1C,iHAAA,gBAAgB,OAAA;AACzB,qDAAuD;AAA9C,qHAAA,kBAAkB,OAAA;AAC3B,kEAAuG;AAA9F,yHAAA,oBAAoB,OAAA;AAAE,iHAAA,YAAY,OAAA;AAAE,wHAAA,mBAAmB,OAAA"}

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

@@ -0,0 +1,86 @@
+import { BaseStorageDriver } from './base.driver.js';
+import { FileUploadResult, PresignedUrlResult, StorageConfig, ListFilesResult, UploadOptions, FileInfo, BlobValidationOptions, BlobValidationResult, DeleteResult } 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
+ *
+ * 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 readonly basePath;
+    private readonly originalLocalPath;
+    constructor(config: StorageConfig);
+    /**
+     * Saves a file to the local filesystem.
+     *
+     * Files are automatically organized into YYYY/MM folders.
+     * For large files (>100MB), uses streaming to reduce memory usage.
+     */
+    upload(file: Express.Multer.File, options?: UploadOptions): Promise<FileUploadResult>;
+    /**
+     * Uploads a large file using streaming.
+     * Pipes the file stream directly to disk for memory efficiency.
+     */
+    private uploadWithStream;
+    /**
+     * Builds a URL for accessing the file.
+     *
+     * If basePath starts with 'public/', strips that prefix since
+     * Express.static('public') serves files from /
+     */
+    private generateFileUrl;
+    private normalizePathSeparators;
+    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)
+     */
+    validateAndConfirmUpload(reference: string, options?: BlobValidationOptions): Promise<BlobValidationResult>;
+    /**
+     * Deletes a file from local storage.
+     *
+     * Security: decodeFileName() rejects traversal/encoding attacks.
+     * Containment check ensures resolved path stays within basePath.
+     * Symlinks and non-files are rejected.
+     */
+    delete(reference: string): Promise<DeleteResult>;
+    /**
+     * Resolves a decoded reference to a verified file path within basePath.
+     * Checks containment (path stays inside basePath), rejects symlinks,
+     * and verifies the target is a regular file.
+     *
+     * Callers are responsible for decoding/validating the reference first
+     * (via decodeFileName or StorageManager's hasPathTraversal check).
+     */
+    private resolveFilePath;
+    /**
+     * Returns metadata about a file without downloading it.
+     * Uses magic byte detection for accurate content type identification.
+     */
+    getMetadata(reference: string): Promise<FileInfo | null>;
+    /**
+     * Lists files in local storage with optional prefix filtering and pagination.
+     */
+    listFiles(prefix?: string, maxResults?: number, continuationToken?: string): Promise<ListFilesResult>;
+}
+//# sourceMappingURL=local.driver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local.driver.d.ts","sourceRoot":"","sources":["../../../src/drivers/local.driver.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,aAAa,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,qBAAqB,EAAE,oBAAoB,EAAyB,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAoR5N;;;;;;;;;;;;;;GAcG;AACH,qBAAa,kBAAmB,SAAQ,iBAAiB;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAE/B,MAAM,EAAE,aAAa;IAMjC;;;;;OAKG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAgD3F;;;OAGG;YACW,gBAAgB;IAqB9B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,YAAY;IAIpB;;OAEG;IAEG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAOjH;;OAEG;IAEG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAOrE;;;;;;OAMG;IACY,wBAAwB,CACrC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAkChC;;;;;;OAMG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgCtD;;;;;;;OAOG;YACW,eAAe;IA0B7B;;;OAGG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAsB9D;;OAEG;IACG,SAAS,CACb,MAAM,CAAC,EAAE,MAAM,EACf,UAAU,GAAE,MAAa,EACzB,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,eAAe,CAAC;CAuC5B"}