mbkbucket 3.8.3 → 4.0.0

package/lib/src/services/storage.service.js

@@ -0,0 +1,213 @@
+/**
+ * MBKBucket - Provider-Independent Storage Service
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ */
+
+import dotenv from "dotenv";
+import { storageManager } from "../core/storage/storage-manager.js";
+import { PathStrategy } from "../core/storage/path-strategy.js";
+import { StorageValidationError } from "../core/storage/errors.js";
+import { createLogger } from "#logger";
+import { trimSlashes } from "#helpers";
+
+dotenv.config();
+const debugStorage = createLogger('storage-service');
+
+export const getAvailableStorageNames = () => storageManager.getAvailableConnectionNames();
+export const getAvailableBucketNames = getAvailableStorageNames;
+
+export function resolveStorageName(name) {
+  return storageManager.resolveConnectionName(name);
+}
+export const resolveBucketName = resolveStorageName;
+
+export const getAppName = () => PathStrategy.getAppName();
+export const validateKeySafety = (str, isKey = false) => PathStrategy.validateSafety(str, isKey);
+export const ensureKeyHasAppPrefix = (key = '') => PathStrategy.applyKeyPrefix(key);
+export const ensurePrefix = (prefix = '') => PathStrategy.applyPrefix(prefix);
+
+export function getStorageProvider(connectionName) {
+  return storageManager.getProvider(connectionName);
+}
+
+export function getStorageConfig(connectionName) {
+  return storageManager.getConnectionConfig(connectionName);
+}
+
+// ---------------------------------------------------------------------------
+// Health Checks
+// ---------------------------------------------------------------------------
+
+export async function checkHealth(connectionName) {
+  return storageManager.checkHealth(connectionName);
+}
+
+export async function runHealthCheck(connectionName) {
+  try {
+    const health = await checkHealth(connectionName);
+    if (health.status === 'healthy') {
+      debugStorage('Connected to storage: %s (%sms)', health.bucket || health.name || 'default', health.responseTime);
+    } else {
+      console.error('[mbkbucket] Storage connection failed:', health.error);
+    }
+    return health;
+  } catch (err) {
+    console.error("[mbkbucket] Storage connection test error:", err.message);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Unified Storage Operations
+// ---------------------------------------------------------------------------
+
+export async function uploadFile(key, fileBuffer, contentType, options = {}) {
+  if (!key || !fileBuffer) throw new StorageValidationError('Key and file buffer are required');
+  const keyToUpload = ensureKeyHasAppPrefix(key);
+  const provider = getStorageProvider(options.bucketName || options.connectionName);
+  return provider.uploadFile(keyToUpload, fileBuffer, contentType, options);
+}
+
+export async function downloadFile(key, options = {}) {
+  if (!key) throw new StorageValidationError('Key is required');
+  const keyToDownload = ensureKeyHasAppPrefix(key);
+  const provider = getStorageProvider(options.bucketName || options.connectionName);
+  return provider.downloadFile(keyToDownload, options);
+}
+
+export async function deleteFile(key, connectionName) {
+  if (!key) throw new StorageValidationError('Key is required');
+  const keyToDelete = ensureKeyHasAppPrefix(key);
+  const provider = getStorageProvider(connectionName);
+  return provider.deleteFile(keyToDelete);
+}
+
+export async function deleteFiles(keys, connectionName) {
+  if (!keys || !Array.isArray(keys) || !keys.length) {
+    throw new StorageValidationError('Keys array is required and must not be empty');
+  }
+  const keysToDelete = keys.map(k => ensureKeyHasAppPrefix(k));
+  const provider = getStorageProvider(connectionName);
+  return provider.deleteFiles(keysToDelete);
+}
+
+export async function deleteFolder(prefix, connectionName) {
+  if (!prefix) throw new StorageValidationError('Prefix is required');
+  const effectivePrefix = `${ensurePrefix(trimSlashes(prefix))}/`;
+  const provider = getStorageProvider(connectionName);
+  return provider.deleteFolder(effectivePrefix);
+}
+
+export async function createFolder(prefix, connectionName, options = {}) {
+  const effectivePrefix = ensurePrefix(prefix);
+  const provider = getStorageProvider(connectionName);
+  return provider.createFolder(effectivePrefix, options);
+}
+
+export async function listfiles(prefix = '', options = {}) {
+  const effectivePrefix = ensurePrefix(prefix);
+  const provider = getStorageProvider(options.bucketName || options.connectionName);
+  return provider.listFiles(effectivePrefix, options);
+}
+
+export async function getFileMetadata(key, connectionName) {
+  if (!key) throw new StorageValidationError('Key is required');
+  const keyToCheck = ensureKeyHasAppPrefix(key);
+  const provider = getStorageProvider(connectionName);
+  return provider.getFileMetadata(keyToCheck);
+}
+
+export async function fileExists(key, connectionName) {
+  try {
+    const meta = await getFileMetadata(key, connectionName);
+    return Boolean(meta?.exists);
+  } catch {
+    return false;
+  }
+}
+
+export async function getFileSize(key, connectionName) {
+  try {
+    const meta = await getFileMetadata(key, connectionName);
+    return meta?.exists ? (meta.ContentLength ?? null) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function generateSignedUrl(key, operation = 'getObject', expiresIn = 3600, connectionName) {
+  const keyToUse = ensureKeyHasAppPrefix(key);
+  const provider = getStorageProvider(connectionName);
+  return provider.generateSignedUrl(keyToUse, operation, expiresIn);
+}
+
+export async function copyFile(sourceKey, destKey, options = {}, connectionName) {
+  const src = ensureKeyHasAppPrefix(sourceKey);
+  const dst = ensureKeyHasAppPrefix(destKey);
+  const provider = getStorageProvider(connectionName);
+  return provider.copyFile(src, dst, options);
+}
+
+export async function moveFile(sourceKey, destKey, options = {}, connectionName) {
+  const src = ensureKeyHasAppPrefix(sourceKey);
+  const dst = ensureKeyHasAppPrefix(destKey);
+  const provider = getStorageProvider(connectionName);
+  return provider.moveFile(src, dst, options);
+}
+
+// ---------------------------------------------------------------------------
+// Multipart Upload Helpers (For S3 / compatible providers)
+// ---------------------------------------------------------------------------
+
+export async function createMultipartUpload(key, contentType = 'application/octet-stream', metadata = {}, connectionName) {
+  const keyToUse = ensureKeyHasAppPrefix(key);
+  const provider = getStorageProvider(connectionName);
+  if (typeof provider.createMultipartUpload !== 'function') {
+    throw new Error(`Multipart upload is not supported by provider ${provider.type}`);
+  }
+  return provider.createMultipartUpload(keyToUse, contentType, metadata);
+}
+
+export async function uploadPart(key, uploadId, partNumber, buffer, connectionName) {
+  const keyToUse = ensureKeyHasAppPrefix(key);
+  const provider = getStorageProvider(connectionName);
+  if (typeof provider.uploadPart !== 'function') {
+    throw new Error(`Multipart upload is not supported by provider ${provider.type}`);
+  }
+  return provider.uploadPart(keyToUse, uploadId, partNumber, buffer);
+}
+
+export async function completeMultipartUpload(key, uploadId, parts, connectionName) {
+  const keyToUse = ensureKeyHasAppPrefix(key);
+  const provider = getStorageProvider(connectionName);
+  if (typeof provider.completeMultipartUpload !== 'function') {
+    throw new Error(`Multipart upload is not supported by provider ${provider.type}`);
+  }
+  return provider.completeMultipartUpload(keyToUse, uploadId, parts);
+}
+
+export async function abortMultipartUpload(key, uploadId, connectionName) {
+  const keyToUse = ensureKeyHasAppPrefix(key);
+  const provider = getStorageProvider(connectionName);
+  if (typeof provider.abortMultipartUpload !== 'function') {
+    throw new Error(`Multipart upload is not supported by provider ${provider.type}`);
+  }
+  return provider.abortMultipartUpload(keyToUse, uploadId);
+}
+
+export async function listIncompleteMultipartUploads(prefix = '', connectionName) {
+  const effectivePrefix = ensurePrefix(prefix || '');
+  const provider = getStorageProvider(connectionName);
+  if (typeof provider.listIncompleteMultipartUploads !== 'function') {
+    return [];
+  }
+  return provider.listIncompleteMultipartUploads(effectivePrefix);
+}
+
+export async function cleanupIncompleteMultipartUploads(olderThanDays = 7, prefix = '', connectionName) {
+  const provider = getStorageProvider(connectionName);
+  if (typeof provider.cleanupIncompleteMultipartUploads !== 'function') {
+    return { abortedCount: 0, uploads: [] };
+  }
+  return provider.cleanupIncompleteMultipartUploads(olderThanDays, prefix);
+}

package/lib/src/utils/errors.js

@@ -1,46 +1,56 @@
-/**
- * Centralized error classification for API and View routes.
- * Maps error messages to HTTP status codes and machine-readable error codes.
- */
-
-const API_ERROR_RULES = [
-  { match: 'bucketconnection environment variable is not set', status: 503, code: 'BUCKET_CONFIG_ERROR' },
-  { match: ['no bucket selected', 'not found in bucketconnection'], status: 400, code: 'INVALID_BUCKET' },
-  { match: 'already exists', status: 409, code: 'CONFLICT' },
-  { match: 'not found', status: 404, code: 'NOT_FOUND' },
-  { match: 'access denied', status: 403, code: 'ACCESS_DENIED' },
-  { match: ['required', 'invalid', 'must be'], status: 400, code: 'VALIDATION_ERROR' },
-];
-
-const VIEW_ERROR_RULES = [
-  { match: ['no bucket selected', 'not found in bucketconnection'], status: 400, code: 'INVALID_BUCKET' },
-  { match: 'access denied', status: 403, code: 'ACCESS_DENIED' },
-  { match: 'not found', status: 404, code: 'NOT_FOUND' },
-  { match: ['invalid', 'required'], status: 400, code: 'VALIDATION_ERROR' },
-];
-
-function matchError(rules, error, fallbackMessage) {
-  const message = String(error?.message || fallbackMessage);
-  const lower = message.toLowerCase();
-  const found = rules.find(r => Array.isArray(r.match) ? r.match.some(m => lower.includes(m)) : lower.includes(r.match));
-  return { status: found?.status ?? 500, code: found?.code ?? 'INTERNAL_ERROR', message };
-}
-
-export const classifyApiError = (error, fallbackMessage = 'Request failed') => matchError(API_ERROR_RULES, error, fallbackMessage);
-export const classifyViewError = (error, fallbackMessage = 'Request failed') => matchError(VIEW_ERROR_RULES, error, fallbackMessage);
-
-export function sendApiError(res, error, fallbackMessage = 'Request failed') {
-  const { status, code, message } = classifyApiError(error, fallbackMessage);
-  return res.status(status).json({
-    success: false,
-    code,
-    error: { code, message },
-    message,
-    timestamp: new Date().toISOString(),
-  });
-}
-
-export function sendViewError(res, error, fallbackMessage = 'Request failed') {
-  const { status, code, message } = classifyViewError(error, fallbackMessage);
-  return res.status(status).json({ code, message });
-}
+/**
+ * Centralized error classification for API and View routes.
+ * Maps typed StorageErrors and error messages to HTTP status codes and machine-readable error codes.
+ */
+
+import { StorageError } from "../core/storage/errors.js";
+
+const API_ERROR_RULES = [
+  { match: 'bucketconnection environment variable is not set', status: 503, code: 'BUCKET_CONFIG_ERROR' },
+  { match: ['no bucket selected', 'not found in bucketconnection', 'no storage connection'], status: 400, code: 'INVALID_BUCKET' },
+  { match: 'already exists', status: 409, code: 'CONFLICT' },
+  { match: 'not found', status: 404, code: 'NOT_FOUND' },
+  { match: 'access denied', status: 403, code: 'ACCESS_DENIED' },
+  { match: ['required', 'invalid', 'must be', 'path traversal'], status: 400, code: 'VALIDATION_ERROR' },
+];
+
+const VIEW_ERROR_RULES = [
+  { match: ['no bucket selected', 'not found in bucketconnection', 'no storage connection'], status: 400, code: 'INVALID_BUCKET' },
+  { match: 'access denied', status: 403, code: 'ACCESS_DENIED' },
+  { match: 'not found', status: 404, code: 'NOT_FOUND' },
+  { match: ['invalid', 'required', 'path traversal'], status: 400, code: 'VALIDATION_ERROR' },
+];
+
+function matchError(rules, error, fallbackMessage) {
+  if (error instanceof StorageError) {
+    return {
+      status: error.status,
+      code: error.code,
+      message: error.message || fallbackMessage
+    };
+  }
+
+  const message = String(error?.message || fallbackMessage);
+  const lower = message.toLowerCase();
+  const found = rules.find(r => Array.isArray(r.match) ? r.match.some(m => lower.includes(m)) : lower.includes(r.match));
+  return { status: found?.status ?? 500, code: found?.code ?? 'INTERNAL_ERROR', message };
+}
+
+export const classifyApiError = (error, fallbackMessage = 'Request failed') => matchError(API_ERROR_RULES, error, fallbackMessage);
+export const classifyViewError = (error, fallbackMessage = 'Request failed') => matchError(VIEW_ERROR_RULES, error, fallbackMessage);
+
+export function sendApiError(res, error, fallbackMessage = 'Request failed') {
+  const { status, code, message } = classifyApiError(error, fallbackMessage);
+  return res.status(status).json({
+    success: false,
+    code,
+    error: { code, message },
+    message,
+    timestamp: new Date().toISOString(),
+  });
+}
+
+export function sendViewError(res, error, fallbackMessage = 'Request failed') {
+  const { status, code, message } = classifyViewError(error, fallbackMessage);
+  return res.status(status).json({ code, message });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbkbucket",
-  "version": "3.8.3",
+  "version": "4.0.0",
   "description": "Flexible S3/R2 bucket management — library, Express router, and standalone server CLI for mbktech.org applications. Provides upload, download, listing, multipart utilities, signed URLs, and a standalone server runner with built-in configuration validation and health checks",
   "author": "Muhammad Bin Khalid",
   "homepage": "https://github.com/MIbnEKhalid/mbkbucket#readme",

package/views/bucket.hbs

@@ -22,86 +22,63 @@
     <style>
         :root {
             --primary-color-ml: #0f766e;
-            --primary-light-color-ml: #d7f4ee;
-            --primary-dark-color-ml: #0b4f4a;
-            --secondary-color-ml: #1f8f84;
-            --dark-color-ml: #1f2a2a;
-            --light-color-ml: #f4f7f3;
-            --gray-color-ml: #667c79;
-            --gray-light-color-ml: #dce8e3;
-            --danger-color-ml: #dc2626;
-            --warning-color-ml: #d97706;
-            --success-color-ml: #16a34a;
-            --info-color-ml: #3b82f6;
+            --primary-light-color-ml: #f0fdfa;
+            --primary-dark-color-ml: #115e59;
+            --secondary-color-ml: #14b8a6;
+            --dark-color-ml: #0f172a;
+            --light-color-ml: #f8fafc;
+            --gray-color-ml: #64748b;
+            --gray-light-color-ml: #e2e8f0;
+            --danger-color-ml: #ef4444;
+            --warning-color-ml: #f59e0b;
+            --success-color-ml: #10b981;
+            --info-color-ml: #0284c7;
 
             --primary: var(--primary-color-ml);
             --primary-lt: var(--primary-light-color-ml);
             --primary-dk: var(--primary-dark-color-ml);
-            --primary-hover: #0d635c;
+            --primary-hover: #134e4a;
 
             --body-bg: var(--light-color-ml);
-            --bg-surface: rgba(255, 255, 255, 0.88);
-            --bg-surface-secondary: rgba(244, 247, 243, 0.7);
-            --bg-surface-tertiary: #e9f2ee;
+            --bg-surface: #ffffff;
+            --bg-surface-secondary: #f8fafc;
+            --bg-surface-tertiary: #f1f5f9;
 
-            --border-color: rgba(15, 118, 110, 0.15);
-            --border-color-light: rgba(15, 118, 110, 0.08);
+            --border-color: #e2e8f0;
+            --border-color-light: #f1f5f9;
 
             --text: var(--dark-color-ml);
-            --text-secondary: #4a5c5a;
+            --text-secondary: #475569;
             --text-muted: var(--gray-color-ml);
-            --text-disabled: #a0b2af;
+            --text-disabled: #94a3b8;
 
-            --font-family: "IBM Plex Sans", "Segoe UI", sans-serif;
-            --font-family-headings: "Sora", "Segoe UI", sans-serif;
-            --font-mono: 'JetBrains Mono', monospace;
+            --font-family: "Segoe UI", -apple-system, BlinkMacSystemFont, system-ui, Roboto, sans-serif;
+            --font-family-headings: "Segoe UI", -apple-system, BlinkMacSystemFont, system-ui, Roboto, sans-serif;
+            --font-mono: "Segoe UI Mono", "Cascadia Code", Consolas, "Courier New", monospace;
         }
 
         * {
             margin: 0;
             padding: 0;
             box-sizing: border-box;
+            font-family: inherit;
+        }
+
+        body, button, input, select, textarea {
+            font-family: var(--font-family);
         }
 
         body {
             font-family: var(--font-family);
-            background:
-                radial-gradient(circle at 12% 14%, rgba(16, 185, 129, 0.12), transparent 44%),
-                radial-gradient(circle at 86% 8%, rgba(244, 114, 38, 0.12), transparent 40%),
-                linear-gradient(160deg, #eef7f2 0, #f8fbf7 52%, #eaf2ef 100%);
-            color: var(--dark-color-ml);
+            background: var(--body-bg);
+            color: var(--text);
             display: flex;
             min-height: 100vh;
             overflow-x: hidden;
-            line-height: 1.6;
+            line-height: 1.5;
             font-size: 14px;
-            position: relative;
-            isolation: isolate;
-        }
-
-        body::before,
-        body::after {
-            content: "";
-            position: fixed;
-            border-radius: 999px;
-            pointer-events: none;
-            z-index: -1;
-        }
-
-        body::before {
-            width: 260px;
-            height: 260px;
-            left: -80px;
-            top: 18vh;
-            background: radial-gradient(circle, rgba(15, 118, 110, 0.16) 0, rgba(15, 118, 110, 0) 70%);
-        }
-
-        body::after {
-            width: 300px;
-            height: 300px;
-            right: -120px;
-            bottom: 10vh;
-            background: radial-gradient(circle, rgba(251, 146, 60, 0.18) 0, rgba(251, 146, 60, 0) 72%);
+            -webkit-font-smoothing: antialiased;
+            -moz-osx-font-smoothing: grayscale;
         }
 
         .main-content {
@@ -113,33 +90,32 @@
         }
 
         .top-nav {
-            background: rgba(255, 255, 255, .85);
-            backdrop-filter: blur(10px);
-            padding: .75rem 1.5rem;
+            background: #ffffff;
+            padding: 0.75rem 1.5rem;
             display: flex;
             align-items: center;
             justify-content: space-between;
-            box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.06), 0 2px 4px -1px rgba(0, 0, 0, 0.04);
+            border-bottom: 1px solid var(--border-color);
             z-index: 90;
-            border-bottom: 1px solid rgba(255, 255, 255, .75);
             gap: 1rem;
         }
 
         .logo {
             font-family: var(--font-family-headings);
-            font-size: 1.5rem;
+            font-size: 1.25rem;
             font-weight: 700;
-            color: #0b4f4a;
+            color: var(--primary-dk);
             display: flex;
             align-items: center;
-            gap: .5rem;
+            gap: 0.6rem;
             cursor: pointer;
             text-decoration: none;
+            letter-spacing: -0.01em;
         }
 
         .logo img {
-            width: 32px;
-            height: 32px;
+            width: 28px;
+            height: 28px;
         }
 
         .content-area {
@@ -149,7 +125,7 @@
         }
 
         .content-area::-webkit-scrollbar {
-            width: 8px;
+            width: 6px;
         }
 
         .content-area::-webkit-scrollbar-track {
@@ -157,20 +133,20 @@
         }
 
         .content-area::-webkit-scrollbar-thumb {
-            background: var(--gray-color-ml);
-            border-radius: 4px;
+            background: #cbd5e1;
+            border-radius: 3px;
         }
 
         .content-area::-webkit-scrollbar-thumb:hover {
-            background: var(--primary-color-ml);
+            background: #94a3b8;
         }
 
         @media (max-width: 768px) {
             .top-nav {
-                padding: .5rem 1rem;
+                padding: 0.6rem 1rem;
             }
             .content-area {
-                padding: 0.85rem;
+                padding: 0.75rem;
             }
         }
     </style>

package/views/bucketadmin_move_modal.hbs

@@ -0,0 +1,35 @@
+<!-- Move / Rename Modal -->
+<div class="modal" id="moveModal" tabindex="-1" aria-labelledby="moveModalLabel" aria-hidden="true">
+  <div class="modal-dialog modal-dialog-centered">
+    <div class="modal-content">
+      <div class="modal-header">
+        <h5 class="modal-title" id="moveModalLabel">
+          <svg width="18" height="18" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" class="modal-title-icon"><path d="M11 2L14 5L11 8M14 5H5C3.34315 5 2 6.34315 2 8V14"/></svg>
+          <span id="moveModalTitle">Move or Rename</span>
+        </h5>
+        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close" onclick="closeMoveModal()">&times;</button>
+      </div>
+      <div class="modal-body">
+        <form id="moveForm" onsubmit="event.preventDefault(); submitMoveItem();">
+          <div class="modal-form-row mb-3">
+            <label class="form-label text-muted small">Current Path</label>
+            <div class="p-2 rounded text-truncate font-mono small" id="moveSourcePathPreview" style="background: var(--bg-surface-secondary); border: 1px solid var(--border-color); color: var(--dark-color-ml);"></div>
+            <input type="hidden" id="moveSourceKeyInput">
+            <input type="hidden" id="moveIsCopyInput" value="false">
+          </div>
+          <div class="modal-form-row mb-3">
+            <label for="moveDestNameInput" class="form-label" id="moveDestNameLabel">New Name or Path</label>
+            <input type="text" id="moveDestNameInput" class="form-control" autocomplete="off" required>
+            <div class="form-text" id="moveHelpText">Enter the new file name or folder destination path.</div>
+          </div>
+        </form>
+      </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-outline" onclick="closeMoveModal()">Cancel</button>
+        <button type="button" class="btn btn-primary" id="submitMoveBtn" onclick="submitMoveItem()">
+          <span id="moveSubmitBtnText">Save Changes</span>
+        </button>
+      </div>
+    </div>
+  </div>
+</div>