mbkbucket 4.0.1 → 4.2.0

package/lib/src/controllers/api.controller.js

@@ -1,9 +1,12 @@
 import { pipeline } from "stream/promises";
 import { listfiles, uploadFile, deleteFile, deleteFiles, deleteFolder, createFolder as createStorageFolder, downloadFile, getFileMetadata, fileExists, ensureKeyHasAppPrefix, ensurePrefix, createMultipartUpload, uploadPart, completeMultipartUpload, abortMultipartUpload, listIncompleteMultipartUploads, cleanupIncompleteMultipartUploads, getStorageProvider, copyFile, moveFile, checkHealth } from "../services/storage.service.js";
+import { metricsRegistry } from "../core/metrics.js";
 import { sendApiError, classifyApiError } from "../utils/errors.js";
-import { getBaseName, isSensitiveTextType, buildKey, normalizeKeyParam, getFolderPath, destroyStream } from "../utils/helpers.js";
+import { getBaseName } from "mbkutils";
+import { isSensitiveTextType, buildKey, normalizeKeyParam, getFolderPath, destroyStream } from "../utils/helpers.js";
 import { createLogger } from "#logger";
 
+
 const debugApi = createLogger('api');
 
 function resolvePrefix(req, res, prefix) {
@@ -107,6 +110,9 @@ export async function listFiles(req, res) {
         .map(p => p.Prefix);
       nextContinuationToken = result.NextContinuationToken;
 
+      const provider = getStorageProvider(bucketName);
+      const capabilities = provider?.capabilities?.toJSON ? provider.capabilities.toJSON() : (provider?.capabilities || {});
+
       return res.json({
         success: true,
         files,
@@ -120,7 +126,8 @@ export async function listFiles(req, res) {
         nextContinuationToken,
         mode: 'optimized',
         totalFiles: -1,
-        paginationType: 'continuation-token'
+        paginationType: 'continuation-token',
+        capabilities
       });
     }
 
@@ -152,6 +159,9 @@ export async function listFiles(req, res) {
     const currentPage = Math.max(1, parseInt(page, 10) || 1);
     const paginatedFiles = files.slice((currentPage - 1) * pageSize, currentPage * pageSize);
 
+    const provider = getStorageProvider(bucketName);
+    const capabilities = provider?.capabilities?.toJSON ? provider.capabilities.toJSON() : (provider?.capabilities || {});
+
     res.json({
       success: true,
       files: paginatedFiles,
@@ -164,7 +174,8 @@ export async function listFiles(req, res) {
       hasPrevPage: currentPage > 1,
       nextPage: currentPage + 1,
       prevPage: Math.max(1, currentPage - 1),
-      totalFiles
+      totalFiles,
+      capabilities
     });
   } catch (error) {
     console.error("Error listing files:", error);
@@ -366,8 +377,9 @@ export async function downloadFileHandler(req, res) {
     if (aborted) return;
 
     const result = await downloadFile(keyToUse, { bucketName: req.activeBucket });
+    const stream = result.Body || result.stream;
     if (aborted) {
-      destroyStream(result.Body);
+      destroyStream(stream);
       return;
     }
 
@@ -386,14 +398,15 @@ export async function downloadFileHandler(req, res) {
     res.setHeader('Cache-Control', isSensitive ? 'private, no-store' : isLargeFile ? 'private, max-age=600, must-revalidate' : 'private, max-age=1800, must-revalidate');
 
     try {
-      await pipeline(result.Body, res);
+      await pipeline(stream, res);
     } catch (pipeErr) {
       if (aborted) {
-        destroyStream(result.Body);
+        destroyStream(stream);
         return;
       }
       throw pipeErr;
     }
+
   } catch (error) {
     if (aborted) return;
     console.error("Error downloading file:", error);
@@ -457,3 +470,18 @@ export async function getFileInfo(req, res) {
     return sendApiError(res, error, 'Failed to get file info');
   }
 }
+
+export async function getMetricsHandler(req, res) {
+  try {
+    const format = req.query.format || (req.headers.accept?.includes('application/json') ? 'json' : 'prometheus');
+    if (format === 'json') {
+      res.setHeader('Content-Type', 'application/json');
+      return res.json({ success: true, ...metricsRegistry.getStats() });
+    }
+    res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+    return res.send(metricsRegistry.toPrometheusText());
+  } catch (error) {
+    return sendApiError(res, error, 'Failed to generate metrics');
+  }
+}
+

package/lib/src/controllers/dashboard.controller.js

@@ -2,8 +2,8 @@ import fs from "fs";
 import path from "path";
 import { resolveStorageName, getAvailableStorageNames, getStorageProvider, getStorageConfig } from "../services/storage.service.js";
 import { storageManager } from "../core/storage/storage-manager.js";
-import { renderPage, mbkautheVar } from "mbkauthe";
-import { commonHandlebarsHelpers } from "../utils/helpers.js";
+import { renderPage, commonHandlebarsHelpers } from "mbkutils";
+import { mbkautheVar } from "mbkauthe";
 import { mbkbucketVar } from "../config/index.js";
 
 /**

package/lib/src/controllers/info.controller.js

@@ -1,9 +1,10 @@
-import { renderPage, mbkautheVar } from "mbkauthe";
+import { renderPage } from "mbkutils";
+import { mbkautheVar } from "mbkauthe";
 import { packageJson, getLatestVersion, appVersion, mbkbucketVar } from "../config/index.js";
 import { getAvailableBucketNames, getStorageProvider } from "../services/storage.service.js";
 import { storageManager } from "../core/storage/storage-manager.js";
 
-async function getInfoData() {
+async function getInfoData(requestedBucket) {
   let latestVersion = 'unknown';
   try {
     latestVersion = (await getLatestVersion()) || 'unknown';
@@ -12,16 +13,21 @@ async function getInfoData() {
   }
 
   const buckets = getAvailableBucketNames();
-  const defaultBucket = storageManager.getDefaultConnectionName() || (buckets[0] ?? '');
+  let defaultBucket = requestedBucket;
+  if (!defaultBucket || !buckets.includes(defaultBucket)) {
+    defaultBucket = storageManager.getDefaultConnectionName() || (buckets[0] ?? '');
+  }
+
   let providerType = 'S3';
+  let capabilities = {};
   if (defaultBucket) {
     try {
       const provider = getStorageProvider(defaultBucket);
       providerType = (provider?.type || 's3').toUpperCase();
+      capabilities = provider?.capabilities?.toJSON ? provider.capabilities.toJSON() : (provider?.capabilities || {});
     } catch {}
   }
 
-  // Safe subset only - strictly prevent leaking passwords, DB connection strings, OAuth secrets, or storage credentials
   const safeMbkautheVar = {
     APP_NAME: mbkautheVar?.APP_NAME || mbkautheVar?.app_name || "mbkbucket",
   };
@@ -41,24 +47,19 @@ async function getInfoData() {
     mbkbucketVar: safeMbkbucketVar,
     defaultBucket,
     configuredBucketsCount: buckets.length,
-    providerType
+    providerType,
+    capabilities
   };
 }
 
-/**
- * Render the mbkbucket info page (Handlebars).
- */
 export async function infoPage(req, res) {
   renderPage(req, res, "mbkbucket_info.hbs", false, {
     pageTitle: "MBKBucket Information",
     ogUrl: "/mbkbucket/info",
-    ...(await getInfoData())
+    ...(await getInfoData(req.query?.bucket))
   });
 }
 
-/**
- * Return bucket info as JSON.
- */
-export async function infoJson(_req, res) {
-  res.json(await getInfoData());
+export async function infoJson(req, res) {
+  res.json(await getInfoData(req.query?.bucket));
 }

package/lib/src/controllers/view.controller.js

@@ -1,11 +1,13 @@
-import { downloadFile, getFileMetadata, ensureKeyHasAppPrefix, generateSignedUrl, resolveStorageName, getStorageProvider } from "../services/storage.service.js";
+import { downloadFile, getFileMetadata, ensureKeyHasAppPrefix, resolveStorageName, getStorageProvider } from "../services/storage.service.js";
 import { mbkbucketVar } from "../config/index.js";
-import { escapeHtml, getBaseName, getFileExt, getMimeType, normalizeKeyParam, destroyStream, VIEWABLE_TYPES, VIEWABLE_TYPES_SORTED, STATIC_ASSET_TYPES, VIDEO_TYPES, AUDIO_TYPES, buildCacheControl, parseRangeHeader, renderPlayerPage } from "../utils/helpers.js";
+import { escapeHtml, getBaseName, getFileExt } from "mbkutils";
+import { getMimeType, normalizeKeyParam, destroyStream, VIEWABLE_TYPES, VIEWABLE_TYPES_SORTED, STATIC_ASSET_TYPES, VIDEO_TYPES, AUDIO_TYPES, buildCacheControl, parseRangeHeader, renderPlayerPage } from "../utils/helpers.js";
 import { createLogger } from "#logger";
 
 const debugView = createLogger('view');
 
 function attachStreamCleanup(req, res, stream, timeoutMs = 120000) {
+  if (!stream || typeof stream.on !== 'function') return;
   const cleanup = () => destroyStream(stream);
 
   stream.on('error', (err) => {
@@ -25,6 +27,7 @@ function attachStreamCleanup(req, res, stream, timeoutMs = 120000) {
   res.on('close', cleanup);
 }
 
+
 async function serveFileInline(req, res, keyToUse, { noindex = true, bucketName, publicCache = false } = {}) {
   const fileName = getBaseName(keyToUse);
   const fileExtension = getFileExt(fileName);
@@ -48,6 +51,8 @@ async function serveFileInline(req, res, keyToUse, { noindex = true, bucketName,
   const isPdf = fileExtension === 'pdf';
   const supportsRanges = isVideo || isAudio || isPdf;
   const contentType = getMimeType(fileName);
+  const safeAsciiName = fileName.replace(/["\\]/g, '').replace(/[^\x20-\x7E]/g, '_');
+  const encodedName = encodeURIComponent(fileName);
 
   // Fast path for range requests (video / audio / PDF streaming)
   if (supportsRanges && rangeHeader) {
@@ -86,21 +91,27 @@ async function serveFileInline(req, res, keyToUse, { noindex = true, bucketName,
         res.setHeader('Content-Range', `bytes ${start}-${end}/${total}`);
         res.setHeader('Content-Length', chunksize);
         res.setHeader('Content-Type', contentType);
+        res.setHeader('Content-Disposition', `inline; filename="${safeAsciiName}"; filename*=UTF-8''${encodedName}`);
         res.setHeader('Cache-Control', buildCacheControl(contentType, { supportsRanges: true, publicCache }));
         res.setHeader('ETag', etag);
         res.setHeader('Accept-Ranges', 'bytes');
+        res.setHeader('X-Frame-Options', 'SAMEORIGIN');
         if (noindex) res.setHeader('X-Robots-Tag', 'noindex, nofollow');
         res.setHeader('X-Content-Type-Options', 'nosniff');
-        if (meta.LastModified) res.setHeader('Last-Modified', new Date(meta.LastModified).toUTCString());
-
-        attachStreamCleanup(req, res, rangeResult.Body);
-        return rangeResult.Body.pipe(res);
+        const stream = rangeResult.Body || rangeResult.stream;
+        attachStreamCleanup(req, res, stream);
+        return stream.pipe(res);
       } catch (rangeError) {
-        console.error('Range request failed:', rangeError);
+        console.error('[mbkbucket] Range request failed for %s:', keyToUse, rangeError);
+        if (!res.headersSent) {
+          return res.status(500).json({ message: 'Range stream failed', error: rangeError.message });
+        }
+        return;
       }
     }
   }
 
+
   // Standard path: full-file download
   const downloadOptions = {
     ...(ifNoneMatch && { ifNoneMatch }),
@@ -130,13 +141,14 @@ async function serveFileInline(req, res, keyToUse, { noindex = true, bucketName,
   if (ifNoneMatch === etag) return res.status(304).end();
 
   res.setHeader('Content-Type', contentType);
-  res.setHeader('Content-Disposition', `inline; filename="${fileName}"`);
+  res.setHeader('Content-Disposition', `inline; filename="${safeAsciiName}"; filename*=UTF-8''${encodedName}`);
   res.setHeader('ETag', etag);
   res.setHeader('X-Content-Type-Options', 'nosniff');
   res.setHeader('X-Frame-Options', 'SAMEORIGIN');
   if (noindex) res.setHeader('X-Robots-Tag', 'noindex, nofollow');
   if (result.ContentLength) res.setHeader('Content-Length', result.ContentLength);
   if (result.LastModified) res.setHeader('Last-Modified', new Date(result.LastModified).toUTCString());
+
   if (fileExtension === 'html' || fileExtension === 'htm') {
     res.setHeader('Content-Security-Policy', "default-src 'self'; script-src 'none'; object-src 'none';");
   }
@@ -144,11 +156,13 @@ async function serveFileInline(req, res, keyToUse, { noindex = true, bucketName,
   res.setHeader('Cache-Control', buildCacheControl(contentType, { isStaticAsset, supportsRanges, publicCache }));
   res.status(200);
 
+  const stream = result.Body || result.stream;
   const timeoutDuration = result.ContentLength > 50 * 1024 * 1024 ? 300000 : 120000;
-  attachStreamCleanup(req, res, result.Body, timeoutDuration);
-  result.Body.pipe(res);
+  attachStreamCleanup(req, res, stream, timeoutDuration);
+  stream.pipe(res);
 }
 
+
 export async function viewFile(req, res) {
   try {
     const key = normalizeKeyParam(req.params.key);
@@ -213,18 +227,6 @@ export async function publicView(req, res) {
       return res.status(400).json({ message: e.message });
     }
 
-    if (!mbkbucketVar?.p_view_inline) {
-      try {
-        const provider = getStorageProvider(bucketName);
-        if (provider.capabilities.presignedUrls) {
-          const signed = await generateSignedUrl(keyToUse, 'getObject', 3600, bucketName);
-          return res.redirect(302, signed.url);
-        }
-      } catch (err) {
-        debugView('Signed URL redirection failed, falling back to inline serve: %s', err.message);
-      }
-    }
-
     await serveFileInline(req, res, keyToUse, { noindex: true, bucketName, publicCache: true });
   } catch (error) {
     console.error('[mbkbucket] p_view error:', error);

package/lib/src/core/metrics.js

@@ -0,0 +1,134 @@
+/**
+ * MBKBucket - Metrics & Observability Registry
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ */
+
+export class MetricsRegistry {
+  constructor() {
+    this.reset();
+  }
+
+  reset() {
+    this.operations = new Map(); // key: "op:provider:status" -> count
+    this.durations = new Map();  // key: "op:provider" -> { totalMs, count, minMs, maxMs }
+    this.bytesTransferred = new Map(); // key: "direction:provider" -> bytes
+    this.errors = new Map(); // key: "op:provider:errorType" -> count
+    this.activeMultipart = 0;
+    this.startedAt = new Date().toISOString();
+  }
+
+  recordOperation(operation, { provider = 'unknown', status = 'success', durationMs = 0, bytes = 0 } = {}) {
+    const opKey = `${operation}:${provider}:${status}`;
+    this.operations.set(opKey, (this.operations.get(opKey) || 0) + 1);
+
+    if (durationMs >= 0) {
+      const durKey = `${operation}:${provider}`;
+      const existing = this.durations.get(durKey) || { totalMs: 0, count: 0, minMs: Infinity, maxMs: 0 };
+      existing.totalMs += durationMs;
+      existing.count += 1;
+      existing.minMs = Math.min(existing.minMs, durationMs);
+      existing.maxMs = Math.max(existing.maxMs, durationMs);
+      this.durations.set(durKey, existing);
+    }
+
+    if (bytes > 0) {
+      const direction = operation.startsWith('download') || operation.startsWith('view') ? 'outbound' : 'inbound';
+      const byteKey = `${direction}:${provider}`;
+      this.bytesTransferred.set(byteKey, (this.bytesTransferred.get(byteKey) || 0) + bytes);
+    }
+  }
+
+  recordError(operation, provider = 'unknown', errorType = 'Error') {
+    const errKey = `${operation}:${provider}:${errorType}`;
+    this.errors.set(errKey, (this.errors.get(errKey) || 0) + 1);
+  }
+
+  incrementActiveMultipart(delta = 1) {
+    this.activeMultipart = Math.max(0, this.activeMultipart + delta);
+  }
+
+  getStats() {
+    const ops = {};
+    for (const [key, count] of this.operations.entries()) {
+      ops[key] = count;
+    }
+
+    const durations = {};
+    for (const [key, d] of this.durations.entries()) {
+      durations[key] = {
+        count: d.count,
+        avgMs: d.count ? Math.round((d.totalMs / d.count) * 100) / 100 : 0,
+        minMs: d.minMs === Infinity ? 0 : d.minMs,
+        maxMs: d.maxMs
+      };
+    }
+
+    const bytes = {};
+    for (const [key, val] of this.bytesTransferred.entries()) {
+      bytes[key] = val;
+    }
+
+    const errs = {};
+    for (const [key, count] of this.errors.entries()) {
+      errs[key] = count;
+    }
+
+    return {
+      startedAt: this.startedAt,
+      activeMultipartUploads: this.activeMultipart,
+      operations: ops,
+      durations,
+      bytesTransferred: bytes,
+      errors: errs,
+      timestamp: new Date().toISOString()
+    };
+  }
+
+  toPrometheusText() {
+    const lines = [
+      '# HELP mbkbucket_operations_total Total number of storage operations executed',
+      '# TYPE mbkbucket_operations_total counter'
+    ];
+
+    for (const [key, count] of this.operations.entries()) {
+      const [operation, provider, status] = key.split(':');
+      lines.push(`mbkbucket_operations_total{operation="${operation}",provider="${provider}",status="${status}"} ${count}`);
+    }
+
+    lines.push('');
+    lines.push('# HELP mbkbucket_operation_duration_seconds Total duration of storage operations');
+    lines.push('# TYPE mbkbucket_operation_duration_seconds summary');
+    for (const [key, d] of this.durations.entries()) {
+      const [operation, provider] = key.split(':');
+      lines.push(`mbkbucket_operation_duration_seconds_count{operation="${operation}",provider="${provider}"} ${d.count}`);
+      lines.push(`mbkbucket_operation_duration_seconds_sum{operation="${operation}",provider="${provider}"} ${(d.totalMs / 1000).toFixed(4)}`);
+    }
+
+    lines.push('');
+    lines.push('# HELP mbkbucket_transferred_bytes_total Total bytes transferred into or out of storage');
+    lines.push('# TYPE mbkbucket_transferred_bytes_total counter');
+    for (const [key, bytes] of this.bytesTransferred.entries()) {
+      const [direction, provider] = key.split(':');
+      lines.push(`mbkbucket_transferred_bytes_total{direction="${direction}",provider="${provider}"} ${bytes}`);
+    }
+
+    lines.push('');
+    lines.push('# HELP mbkbucket_errors_total Total storage errors encountered');
+    lines.push('# TYPE mbkbucket_errors_total counter');
+    for (const [key, count] of this.errors.entries()) {
+      const [operation, provider, errorType] = key.split(':');
+      lines.push(`mbkbucket_errors_total{operation="${operation}",provider="${provider}",error_type="${errorType}"} ${count}`);
+    }
+
+    lines.push('');
+    lines.push('# HELP mbkbucket_active_multipart_uploads Current number of active multipart uploads');
+    lines.push('# TYPE mbkbucket_active_multipart_uploads gauge');
+    lines.push(`mbkbucket_active_multipart_uploads ${this.activeMultipart}`);
+    lines.push('');
+
+    return lines.join('\n');
+  }
+}
+
+export const metricsRegistry = new MetricsRegistry();

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

@@ -0,0 +1,58 @@
+/**
+ * MBKBucket - Storage Provider Capabilities
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ */
+
+import { StorageUnsupportedOperationError } from "./errors.js";
+
+export class StorageCapabilities {
+  constructor(flags = {}) {
+    this.multipart = Boolean(flags.multipart);
+    this.resumable = Boolean(flags.resumable ?? flags.multipart);
+    this.nativeFolders = Boolean(flags.nativeFolders);
+    this.ranges = Boolean(flags.ranges ?? true);
+    this.copy = Boolean(flags.copy);
+    this.move = Boolean(flags.move);
+    this.search = Boolean(flags.search);
+    this.directDownloadUrl = Boolean(flags.directDownloadUrl);
+    this.versioning = Boolean(flags.versioning);
+    this.publicUrls = Boolean(flags.publicUrls);
+    this.storageQuota = Boolean(flags.storageQuota);
+    this.deleteBatch = Boolean(flags.deleteBatch ?? true);
+    this.metadata = Boolean(flags.metadata ?? true);
+
+    Object.freeze(this);
+  }
+
+  has(capability) {
+    return Boolean(this[capability]);
+  }
+
+  assert(capability, operationName, providerType = 'storage provider') {
+    if (!this.has(capability)) {
+      const op = operationName || capability;
+      throw new StorageUnsupportedOperationError(
+        `Operation '${op}' is not supported by ${providerType} (missing capability: ${capability})`
+      );
+    }
+  }
+
+  toJSON() {
+    return {
+      multipart: this.multipart,
+      resumable: this.resumable,
+      nativeFolders: this.nativeFolders,
+      ranges: this.ranges,
+      copy: this.copy,
+      move: this.move,
+      search: this.search,
+      directDownloadUrl: this.directDownloadUrl,
+      versioning: this.versioning,
+      publicUrls: this.publicUrls,
+      storageQuota: this.storageQuota,
+      deleteBatch: this.deleteBatch,
+      metadata: this.metadata
+    };
+  }
+}

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

@@ -5,11 +5,6 @@
  */
 
 export class StorageError extends Error {
-  /**
-   * @param {string} message
-   * @param {number} [status=500]
-   * @param {string} [code='INTERNAL_STORAGE_ERROR']
-   */
   constructor(message, status = 500, code = 'INTERNAL_STORAGE_ERROR') {
     super(message);
     this.name = this.constructor.name;

package/lib/src/core/storage/gdrive-auth.js

@@ -15,17 +15,6 @@ export const GOOGLE_DRIVE_SCOPES = [
   'https://www.googleapis.com/auth/drive.metadata.readonly'
 ];
 
-/**
- * Generate Google OAuth 2.0 Authorization URL for user consent.
- * @param {object} options
- * @param {string} options.clientId
- * @param {string} options.redirectUri
- * @param {string} [options.state]
- * @param {string[]} [options.scopes]
- * @param {'consent'|'select_account'|'none'} [options.prompt='consent']
- * @param {'offline'|'online'} [options.accessType='offline']
- * @returns {string}
- */
 export function getGoogleAuthUrl({
   clientId,
   redirectUri,
@@ -51,15 +40,6 @@ export function getGoogleAuthUrl({
   return `https://accounts.google.com/o/oauth2/v2/auth?${params.toString()}`;
 }
 
-/**
- * Exchange an OAuth authorization code for tokens (access_token, refresh_token).
- * @param {object} options
- * @param {string} options.code
- * @param {string} options.clientId
- * @param {string} options.clientSecret
- * @param {string} options.redirectUri
- * @returns {Promise<{ access_token: string, refresh_token?: string, expires_in: number, token_type: string, scope: string, expiry_date: number }>}
- */
 export async function exchangeCodeForTokens({
   code,
   clientId,
@@ -94,14 +74,6 @@ export async function exchangeCodeForTokens({
   return { ...data, expiry_date };
 }
 
-/**
- * Refresh an expired access token using a refresh token.
- * @param {object} options
- * @param {string} options.clientId
- * @param {string} options.clientSecret
- * @param {string} options.refreshToken
- * @returns {Promise<{ access_token: string, expires_in: number, expiry_date: number, token_type: string }>}
- */
 export async function refreshGoogleAccessToken({
   clientId,
   clientSecret,
@@ -134,14 +106,6 @@ export async function refreshGoogleAccessToken({
   return { ...data, expiry_date };
 }
 
-/**
- * Generate an OAuth2 access token from a Google Service Account using JWT signing.
- * @param {object} options
- * @param {string} options.clientEmail
- * @param {string} options.privateKey
- * @param {string[]} [options.scopes]
- * @returns {Promise<{ access_token: string, expires_in: number, expiry_date: number }>}
- */
 export async function getServiceAccountAccessToken({
   clientEmail,
   privateKey,