mbkbucket 4.0.1 → 4.2.0

package/lib/src/core/storage/local-provider.js

@@ -0,0 +1,508 @@
+/**
+ * MBKBucket - Local Filesystem Storage Provider
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ */
+
+import fs from "fs";
+import path from "path";
+import { Readable } from "stream";
+import { StorageProvider } from "./storage-provider.js";
+import { StorageCapabilities } from "./capabilities.js";
+import { StorageValidationError, StorageNotFoundError, StorageError } from "./errors.js";
+import { StorageListResult } from "./models.js";
+import { nowIso, formatBytes } from "#helpers";
+import { getFileExt, trimLeadingSlashes } from "mbkutils";
+import { createLogger } from "#logger";
+
+
+const debugLocal = createLogger('local-provider');
+
+function sanitizeKey(key = '') {
+  return trimLeadingSlashes(String(key || '')).replace(/\\/g, '/');
+}
+
+function getMimeType(key = '') {
+  const ext = getFileExt(key);
+  const mimeMap = {
+    txt: 'text/plain',
+    html: 'text/html',
+    css: 'text/css',
+    js: 'application/javascript',
+    json: 'application/json',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    svg: 'image/svg+xml',
+    webp: 'image/webp',
+    pdf: 'application/pdf',
+    mp4: 'video/mp4',
+    mp3: 'audio/mpeg',
+    zip: 'application/zip'
+  };
+  return mimeMap[ext] || 'application/octet-stream';
+}
+
+export class LocalStorageProvider extends StorageProvider {
+
+  constructor(name, config = {}) {
+    super(name, config);
+    const rawPath = config.basePath || config.rootPath || config.directory || './mbkbucket_storage';
+    this.baseDirectory = path.resolve(process.cwd(), rawPath);
+
+    // Ensure base directory exists on construction
+    try {
+      if (!fs.existsSync(this.baseDirectory)) {
+        fs.mkdirSync(this.baseDirectory, { recursive: true });
+      }
+    } catch (err) {
+      debugLocal('Could not initialize base directory %s: %s', this.baseDirectory, err.message);
+    }
+  }
+
+  get type() {
+    return 'local';
+  }
+
+  get capabilities() {
+    return new StorageCapabilities({
+      multipart: false,
+      resumable: false,
+      nativeFolders: true,
+      ranges: true,
+      copy: true,
+      move: true,
+      search: true,
+      directDownloadUrl: false,
+      versioning: false,
+      publicUrls: false,
+      storageQuota: true,
+      deleteBatch: true,
+      metadata: true
+    });
+  }
+
+  resolvePath(key) {
+    const raw = String(key || '').trim();
+    const cleanKey = sanitizeKey(raw);
+
+    // Guard against Windows drive letters (C:) and root escapes
+    if (/^[a-zA-Z]:/.test(cleanKey) || /^[a-zA-Z]:/.test(raw) || raw.startsWith('/') || raw.startsWith('\\')) {
+      if (raw !== cleanKey && !cleanKey) {
+        throw new StorageValidationError(`Invalid storage key: path traversal or root escape detected for "${key}"`);
+      }
+    }
+
+    const resolvedPath = path.resolve(this.baseDirectory, cleanKey);
+
+    // Verify resolved path stays strictly inside base directory across OSes
+    const relative = path.relative(this.baseDirectory, resolvedPath);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new StorageValidationError(`Invalid storage key: path traversal detected for "${key}"`);
+    }
+
+    return { resolvedPath, relativeKey: cleanKey.replace(/\\/g, '/') };
+  }
+
+
+  async listFiles(prefix = '', options = {}) {
+    const cleanPrefix = sanitizeKey(prefix || '');
+    const { resolvedPath: dirPath } = this.resolvePath(cleanPrefix);
+    const isRecursive = options.recursive === true || options.recursive === 'true';
+    const delimiter = options.delimiter || (isRecursive ? '' : '/');
+    const search = (options.search || '').trim().toLowerCase();
+    const maxKeys = Math.max(1, Math.min(Number(options.maxKeys) || 1000, 5000));
+    const token = options.continuationToken || options.token || null;
+
+    if (!fs.existsSync(dirPath)) {
+      return new StorageListResult({
+        contents: [],
+        commonPrefixes: [],
+        nextToken: null,
+        isTruncated: false,
+        totalFiles: 0
+      });
+    }
+
+    const files = [];
+    const folders = [];
+    const seenFolders = new Set();
+
+    const scanDirectory = (currentDir, currentPrefix) => {
+      let entries = [];
+      try {
+        entries = fs.readdirSync(currentDir, { withFileTypes: true });
+      } catch (err) {
+        debugLocal('Failed reading directory %s: %s', currentDir, err.message);
+        return;
+      }
+
+      for (const entry of entries) {
+        const fullPath = path.join(currentDir, entry.name);
+        const relativeKey = path.relative(this.baseDirectory, fullPath).replace(/\\/g, '/');
+
+        if (entry.isDirectory()) {
+          const folderPrefix = relativeKey.endsWith('/') ? relativeKey : `${relativeKey}/`;
+          
+          if (delimiter === '/') {
+            if (!seenFolders.has(folderPrefix)) {
+              seenFolders.add(folderPrefix);
+              folders.push({
+                name: entry.name,
+                prefix: folderPrefix,
+                path: folderPrefix
+              });
+            }
+          } else {
+            if (!seenFolders.has(folderPrefix)) {
+              seenFolders.add(folderPrefix);
+              folders.push({
+                name: entry.name,
+                prefix: folderPrefix,
+                path: folderPrefix
+              });
+            }
+            if (isRecursive) {
+              scanDirectory(fullPath, folderPrefix);
+            }
+          }
+        } else if (entry.isFile()) {
+          try {
+            const stat = fs.statSync(fullPath);
+            const fileName = entry.name;
+            const matchesSearch = !search || fileName.toLowerCase().includes(search) || relativeKey.toLowerCase().includes(search);
+
+            if (matchesSearch) {
+              files.push({
+                Key: relativeKey,
+                Size: stat.size,
+                LastModified: stat.mtime.toISOString(),
+                ETag: `"${stat.mtimeMs.toString(16)}-${stat.size.toString(16)}"`,
+                ContentType: getMimeType(fileName),
+                name: fileName,
+                sizeFormatted: formatBytes(stat.size)
+              });
+            }
+          } catch (err) {
+            debugLocal('Error reading file stat %s: %s', fullPath, err.message);
+          }
+        }
+      }
+    };
+
+    scanDirectory(dirPath, cleanPrefix);
+
+    // Sort alphabetically
+    files.sort((a, b) => a.Key.localeCompare(b.Key));
+    folders.sort((a, b) => a.prefix.localeCompare(b.prefix));
+
+    // Simple token-based pagination
+    let startIndex = 0;
+    if (token) {
+      const idx = files.findIndex(f => f.Key === token);
+      if (idx !== -1) startIndex = idx + 1;
+    }
+
+    const paginatedFiles = files.slice(startIndex, startIndex + maxKeys);
+    const isTruncated = (startIndex + maxKeys) < files.length;
+    const nextContinuationToken = isTruncated && paginatedFiles.length > 0
+      ? paginatedFiles[paginatedFiles.length - 1].Key
+      : null;
+
+    return new StorageListResult({
+      contents: paginatedFiles,
+      commonPrefixes: folders.map(f => ({ Prefix: f.prefix || f })),
+      nextToken: nextContinuationToken,
+      isTruncated,
+      totalFiles: files.length
+    });
+  }
+
+
+  async uploadFile(key, fileBuffer, contentType, options = {}) {
+    if (!key) throw new StorageValidationError("Storage key is required for upload");
+    const { resolvedPath, relativeKey } = this.resolvePath(key);
+    const dir = path.dirname(resolvedPath);
+
+    try {
+      if (!fs.existsSync(dir)) {
+        await fs.promises.mkdir(dir, { recursive: true });
+      }
+
+      if (fileBuffer instanceof Readable) {
+        const outStream = fs.createWriteStream(resolvedPath);
+        await new Promise((resolve, reject) => {
+          fileBuffer.pipe(outStream);
+          outStream.on('finish', resolve);
+          outStream.on('error', reject);
+          fileBuffer.on('error', reject);
+        });
+      } else {
+        const buffer = Buffer.isBuffer(fileBuffer) ? fileBuffer : Buffer.from(fileBuffer);
+        await fs.promises.writeFile(resolvedPath, buffer);
+      }
+
+      const stat = await fs.promises.stat(resolvedPath);
+      const mime = contentType || getMimeType(key);
+      const etag = `"${stat.mtimeMs.toString(16)}-${stat.size.toString(16)}"`;
+
+      return {
+        key: relativeKey,
+        Key: relativeKey,
+        size: stat.size,
+        Size: stat.size,
+        etag,
+        ETag: etag,
+        contentType: mime,
+        ContentType: mime,
+        uploadedAt: nowIso(),
+        storageType: 'local'
+      };
+    } catch (err) {
+      debugLocal('Upload error for key %s: %s', key, err.message);
+      throw new StorageError(`Local upload failed: ${err.message}`);
+    }
+  }
+
+  async downloadFile(key, options = {}) {
+    if (!key) throw new StorageValidationError("Storage key is required for download");
+    const { resolvedPath, relativeKey } = this.resolvePath(key);
+
+    try {
+      const stat = await fs.promises.stat(resolvedPath);
+      if (stat.isDirectory()) {
+        throw new StorageValidationError(`Key "${key}" refers to a directory, not a file`);
+      }
+
+      let start = 0;
+      let end = stat.size - 1;
+      let isRange = false;
+
+      if (options.range) {
+        const match = /^bytes=(\d*)-(\d*)$/.exec(String(options.range).trim());
+        if (match) {
+          const rawStart = match[1];
+          const rawEnd = match[2];
+          if (rawStart !== '') start = parseInt(rawStart, 10);
+          if (rawEnd !== '') end = parseInt(rawEnd, 10);
+          isRange = true;
+        }
+      } else if (typeof options.start === 'number' || typeof options.end === 'number') {
+        if (typeof options.start === 'number') start = options.start;
+        if (typeof options.end === 'number') end = options.end;
+        isRange = true;
+      }
+
+      if (isRange) {
+        if (isNaN(start) || start < 0) start = 0;
+        if (isNaN(end) || end >= stat.size) end = stat.size - 1;
+        if (start > end) start = end;
+      }
+
+      const stream = fs.createReadStream(resolvedPath, isRange ? { start, end } : undefined);
+      const contentType = getMimeType(key);
+      const contentLength = isRange ? (end - start + 1) : stat.size;
+      const etag = `"${stat.mtimeMs.toString(16)}-${stat.size.toString(16)}"`;
+
+      return {
+        Body: stream,
+        stream,
+        ContentType: contentType,
+        ContentLength: contentLength,
+        LastModified: stat.mtime,
+        ETag: etag,
+        isRange,
+        contentRange: isRange ? `bytes ${start}-${end}/${stat.size}` : null
+      };
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        throw new StorageNotFoundError(`File not found: ${key}`);
+      }
+      throw new StorageError(`Local download failed: ${err.message}`);
+    }
+
+  }
+
+  async deleteFile(key) {
+    if (!key) throw new StorageValidationError("Storage key is required for delete");
+    const { resolvedPath, relativeKey } = this.resolvePath(key);
+
+    try {
+      await fs.promises.unlink(resolvedPath);
+      return { key: relativeKey, deleted: true, deletedAt: nowIso() };
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        return { key: relativeKey, deleted: false, reason: 'notFound' };
+      }
+      throw new StorageError(`Local delete failed: ${err.message}`);
+    }
+  }
+
+  async deleteFolder(prefix) {
+    if (!prefix) throw new StorageValidationError("Prefix is required for deleteFolder");
+    const { resolvedPath, relativeKey } = this.resolvePath(prefix);
+
+    try {
+      if (fs.existsSync(resolvedPath)) {
+        await fs.promises.rm(resolvedPath, { recursive: true, force: true });
+      }
+      return { prefix: relativeKey, deleted: true, deletedAt: nowIso() };
+    } catch (err) {
+      throw new StorageError(`Local deleteFolder failed: ${err.message}`);
+    }
+  }
+
+  async createFolder(prefix) {
+    if (!prefix) throw new StorageValidationError("Prefix is required for createFolder");
+    const { resolvedPath, relativeKey } = this.resolvePath(prefix);
+
+    try {
+      await fs.promises.mkdir(resolvedPath, { recursive: true });
+      return { prefix: relativeKey, created: true, createdAt: nowIso() };
+    } catch (err) {
+      throw new StorageError(`Local createFolder failed: ${err.message}`);
+    }
+  }
+
+  async getFileMetadata(key) {
+    if (!key) throw new StorageValidationError("Storage key is required for metadata");
+    const { resolvedPath, relativeKey } = this.resolvePath(key);
+
+    try {
+      const stat = await fs.promises.stat(resolvedPath);
+      const isDir = stat.isDirectory();
+      const contentType = isDir ? 'application/x-directory' : getMimeType(key);
+      const etag = `"${stat.mtimeMs.toString(16)}-${stat.size.toString(16)}"`;
+
+      return {
+        exists: true,
+        Key: relativeKey,
+        ContentLength: isDir ? 0 : stat.size,
+        LastModified: stat.mtime,
+        ContentType: contentType,
+        ETag: etag,
+        isDirectory: isDir,
+        Metadata: {}
+      };
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        return { exists: false, Key: relativeKey };
+      }
+      throw new StorageError(`Local getFileMetadata failed: ${err.message}`);
+    }
+  }
+
+  async copyFile(sourceKey, destKey) {
+    if (!sourceKey || !destKey) throw new StorageValidationError("sourceKey and destKey are required for copy");
+    const { resolvedPath: srcPath, relativeKey: srcRel } = this.resolvePath(sourceKey);
+    const { resolvedPath: dstPath, relativeKey: dstRel } = this.resolvePath(destKey);
+
+    try {
+      const dstDir = path.dirname(dstPath);
+      if (!fs.existsSync(dstDir)) {
+        await fs.promises.mkdir(dstDir, { recursive: true });
+      }
+
+      await fs.promises.copyFile(srcPath, dstPath);
+      return { sourceKey: srcRel, destKey: dstRel, copiedAt: nowIso() };
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        throw new StorageNotFoundError(`Source file not found: ${sourceKey}`);
+      }
+      throw new StorageError(`Local copy failed: ${err.message}`);
+    }
+  }
+
+  async moveFile(sourceKey, destKey) {
+    if (!sourceKey || !destKey) throw new StorageValidationError("sourceKey and destKey are required for move");
+    const { resolvedPath: srcPath, relativeKey: srcRel } = this.resolvePath(sourceKey);
+    const { resolvedPath: dstPath, relativeKey: dstRel } = this.resolvePath(destKey);
+
+    try {
+      const dstDir = path.dirname(dstPath);
+      if (!fs.existsSync(dstDir)) {
+        await fs.promises.mkdir(dstDir, { recursive: true });
+      }
+
+      try {
+        await fs.promises.rename(srcPath, dstPath);
+      } catch (renameErr) {
+        // Fallback for cross-device moves
+        await fs.promises.copyFile(srcPath, dstPath);
+        await fs.promises.unlink(srcPath);
+      }
+
+      return { sourceKey: srcRel, destKey: dstRel, movedAt: nowIso() };
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        throw new StorageNotFoundError(`Source file not found: ${sourceKey}`);
+      }
+      throw new StorageError(`Local move failed: ${err.message}`);
+    }
+  }
+
+  async getStorageQuota() {
+    let totalBytes = 0;
+    let fileCount = 0;
+
+    const calculateSize = (dir) => {
+      try {
+        if (!fs.existsSync(dir)) return;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            calculateSize(fullPath);
+          } else if (entry.isFile()) {
+            const stat = fs.statSync(fullPath);
+            totalBytes += stat.size;
+            fileCount++;
+          }
+        }
+      } catch {}
+    };
+
+    calculateSize(this.baseDirectory);
+
+    return {
+      usedBytes: totalBytes,
+      fileCount,
+      usedFormatted: formatBytes(totalBytes),
+      path: this.baseDirectory
+    };
+  }
+
+  async checkHealth() {
+    const startTime = Date.now();
+    const rand = Math.random().toString(36).slice(2, 8);
+    const testFile = path.join(this.baseDirectory, `.health_${process.pid}_${Date.now()}_${rand}.tmp`);
+    try {
+      if (!fs.existsSync(this.baseDirectory)) {
+        await fs.promises.mkdir(this.baseDirectory, { recursive: true });
+      }
+      // Test read/write permission with a temporary marker file
+      await fs.promises.writeFile(testFile, 'ok');
+      try { await fs.promises.unlink(testFile); } catch {}
+
+      return {
+        status: 'healthy',
+        type: 'local',
+        baseDirectory: this.baseDirectory,
+        responseTime: Date.now() - startTime,
+        checkedAt: nowIso()
+      };
+    } catch (err) {
+      try { if (fs.existsSync(testFile)) await fs.promises.unlink(testFile); } catch {}
+      return {
+        status: 'unhealthy',
+        type: 'local',
+        baseDirectory: this.baseDirectory,
+        error: err.message,
+        responseTime: Date.now() - startTime,
+        checkedAt: nowIso()
+      };
+    }
+  }
+
+}

package/lib/src/core/storage/models.js

@@ -4,68 +4,105 @@
  * Licensed under the MIT License.
  */
 
-import { nowIso } from "#helpers";
+import { nowIso, getFolderPath } from "#helpers";
+import { getBaseName, trimLeadingSlashes, trimSlashes } from "mbkutils";
+
+export class StorageItem {
+  constructor(props = {}) {
+    const rawPath = String(props.path || props.key || props.Key || props.prefix || props.Prefix || '');
+    this.path = props.type === 'folder'
+      ? (rawPath ? (rawPath.endsWith('/') ? rawPath : `${rawPath}/`) : '')
+      : trimLeadingSlashes(rawPath);
+
+    this.type = props.type || (this.path.endsWith('/') ? 'folder' : 'file');
+    this.name = props.name || (this.type === 'folder' ? trimSlashes(getBaseName(this.path.replace(/\/+$/, ''))) : getBaseName(this.path));
+    this.parentPath = props.parentPath ?? (this.type === 'folder'
+      ? trimSlashes(getFolderPath(this.path.replace(/\/+$/, '')))
+      : trimSlashes(getFolderPath(this.path)));
+
+    this.id = props.id || props.nativeId || this.path;
+    this.nativeId = props.nativeId || props.id || null;
+    this.provider = props.provider || props.storageClass || props.StorageClass || 'generic';
+
+    this.size = this.type === 'folder' ? 0 : Number(props.size ?? props.Size ?? 0);
+    this.mimeType = props.mimeType || props.contentType || props.ContentType || (this.type === 'folder' ? 'application/x-directory' : 'application/octet-stream');
+    this.etag = props.etag || props.ETag || '';
+
+    const modDate = props.lastModified || props.LastModified || props.updatedAt;
+    this.lastModified = modDate instanceof Date ? modDate : new Date(modDate || Date.now());
+
+    if (props.createdAt || props.createdTime) {
+      const createDate = props.createdAt || props.createdTime;
+      this.createdAt = createDate instanceof Date ? createDate : new Date(createDate);
+    }
+
+    this.metadata = Object.freeze({ ...(props.metadata || {}) });
+  }
+
+  get isFolder() {
+    return this.type === 'folder';
+  }
+
+  get isFile() {
+    return this.type === 'file';
+  }
+}
+
+export class StorageFile extends StorageItem {
+  constructor(props = {}) {
+    const key = props.key || props.Key || props.path || '';
+    super({
+      ...props,
+      type: 'file',
+      path: key,
+      size: props.size ?? props.Size ?? 0,
+      mimeType: props.mimeType || props.contentType || props.ContentType,
+      lastModified: props.lastModified || props.LastModified,
+      etag: props.etag || props.ETag,
+      provider: props.storageClass || props.StorageClass || props.provider || 'STANDARD',
+      id: props.id,
+      nativeId: props.id || props.nativeId
+    });
+
+    // Backward-compatible properties for S3 consumers
+    this.Key = this.path;
+    this.Size = this.size;
+    this.LastModified = this.lastModified;
+    this.ETag = this.etag;
+    this.ContentType = this.mimeType;
+    this.StorageClass = this.provider;
 
-/**
- * Standardized file item representation across all providers.
- */
-export class StorageFile {
-  /**
-   * @param {object} props
-   * @param {string} props.key - Normalized virtual key / path
-   * @param {number} [props.size=0] - File size in bytes
-   * @param {Date|string} [props.lastModified] - Last modified timestamp
-   * @param {string} [props.etag] - Entity tag / checksum
-   * @param {string} [props.contentType] - MIME content type
-   * @param {string} [props.storageClass] - Storage tier / provider type
-   * @param {string} [props.id] - Native provider ID (e.g. Google Drive file ID)
-   * @param {string} [props.webViewLink] - Web preview link
-   * @param {string} [props.webContentLink] - Direct download link
-   * @param {object} [props.metadata={}] - Custom user metadata
-   */
-  constructor(props) {
-    this.Key = props.key || props.Key || '';
-    this.Size = Number(props.size ?? props.Size ?? 0);
-    this.LastModified = props.lastModified instanceof Date
-      ? props.lastModified
-      : new Date(props.lastModified || props.LastModified || Date.now());
-    this.ETag = props.etag || props.ETag || '';
-    this.ContentType = props.contentType || props.ContentType || 'application/octet-stream';
-    this.StorageClass = props.storageClass || props.StorageClass || 'STANDARD';
     if (props.id) this.id = props.id;
     if (props.mimeType) this.mimeType = props.mimeType;
     if (props.webViewLink) this.webViewLink = props.webViewLink;
     if (props.webContentLink) this.webContentLink = props.webContentLink;
-    if (props.metadata) this.metadata = props.metadata;
   }
 }
 
-/**
- * Standardized folder representation.
- */
-export class StorageFolder {
-  /**
-   * @param {string} prefix - Folder prefix with trailing slash
-   * @param {string} [id] - Native provider folder ID
-   */
-  constructor(prefix, id) {
-    this.Prefix = String(prefix || '').endsWith('/') ? String(prefix) : `${prefix}/`;
-    if (id) this.id = id;
+export class StorageFolder extends StorageItem {
+  constructor(prefixOrProps, id) {
+    const props = typeof prefixOrProps === 'object' && prefixOrProps !== null
+      ? prefixOrProps
+      : { prefix: prefixOrProps, id };
+
+    const rawPrefix = String(props.prefix || props.Prefix || props.path || '');
+    const cleanPrefix = rawPrefix ? (rawPrefix.endsWith('/') ? rawPrefix : `${rawPrefix}/`) : '';
+
+    super({
+      ...props,
+      type: 'folder',
+      path: cleanPrefix,
+      id: props.id || id,
+      nativeId: props.id || id
+    });
+
+    // Backward-compatible property for S3 consumers
+    this.Prefix = this.path;
+    if (this.id) this.id = this.id;
   }
 }
 
-/**
- * Standardized paginated listing result.
- */
 export class StorageListResult {
-  /**
-   * @param {object} props
-   * @param {StorageFile[]} [props.contents=[]]
-   * @param {StorageFolder[]} [props.commonPrefixes=[]]
-   * @param {string|null} [props.nextToken=null]
-   * @param {boolean} [props.isTruncated=false]
-   * @param {number} [props.totalFiles]
-   */
   constructor(props = {}) {
     this.Contents = props.contents || props.Contents || [];
     this.CommonPrefixes = props.commonPrefixes || props.CommonPrefixes || [];
@@ -76,5 +113,9 @@ export class StorageListResult {
     this.KeyCount = this.Contents.length;
     this.totalFiles = props.totalFiles ?? this.Contents.length;
     this.requestedAt = nowIso();
+
+    this.files = this.Contents;
+    this.folders = this.CommonPrefixes;
+    this.items = [...this.CommonPrefixes, ...this.Contents];
   }
 }