mbkbucket 1.2.1 → 1.4.0

package/lib/config/index.js

@@ -1,4 +1,7 @@
 import { createRequire } from "module";
+import dotenv from "dotenv";
+
+dotenv.config();
 
 // Load package.json from mbkbucket package (not parent project)
 const require = createRequire(import.meta.url);
@@ -54,4 +57,134 @@ async function checkVersion() {
         console.warn(`[mbkbucket] Failed to check for updates: ${error.message}`);
     }
 }
-export { packageJson, appVersion, getLatestVersion, checkVersion };
+
+// Comprehensive validation function
+function validateConfiguration() {
+    const errors = [];
+
+    // Parse and validate mbkbucketVar
+    let mbkbucketVar;
+    try {
+        if (!process.env.mbkbucketVar) {
+            // If mbkbucketVar is not defined, use empty object (defaults will be applied later)
+            mbkbucketVar = {};
+            console.log(`[mbkbucket] mbkbucketVar not defined, using defaults`);
+        } else {
+            mbkbucketVar = JSON.parse(process.env.mbkbucketVar);
+        }
+    } catch (error) {
+        errors.push("Invalid JSON in process.env.mbkbucketVar");
+        throw new Error(`[mbkbucket] Configuration Error:\n  - ${errors.join('\n  - ')}`);
+    }
+
+    if (!mbkbucketVar || typeof mbkbucketVar !== 'object') {
+        errors.push("mbkbucketVar must be a valid object");
+        throw new Error(`[mbkbucket] Configuration Error:\n  - ${errors.join('\n  - ')}`);
+    }
+
+    // Apply defaults for optional keys (booleans now)
+    const defaults = {
+        p_view_inline: true,
+        publiView_enabled: false
+    };
+
+    const usedDefaults = [];
+    Object.entries(defaults).forEach(([key, defaultVal]) => {
+        const current = mbkbucketVar[key];
+        if (current === undefined || (typeof current === 'string' && current.trim() === '')) {
+            mbkbucketVar[key] = defaultVal;
+            usedDefaults.push(key);
+        }
+    });
+
+    // Helper to normalize various truthy/falsy representations
+    function normalizeBool(val) {
+        if (typeof val === 'boolean') return val;
+        if (typeof val === 'string') {
+            const norm = val.trim().toLowerCase();
+            if (['true', 't', '1', 'yes', 'y', 'on'].includes(norm)) return true;
+            if (['false', 'f', '0', 'no', 'n', 'off'].includes(norm)) return false;
+            return val; // return original so later validation will flag it
+        }
+        return val;
+    }
+
+    // Normalize boolean-like values early so validation works on cleaned values;
+    // results are actual booleans.
+    ['p_view_inline', 'publiView_enabled'].forEach(k => {
+        if (k in mbkbucketVar) {
+            mbkbucketVar[k] = normalizeBool(mbkbucketVar[k]);
+        }
+    });
+
+    // Validate that applied values are proper booleans (after defaults and normalization)
+    // Note: p_view_inline and publiView_enabled are optional - defaults are applied above
+    ['p_view_inline', 'publiView_enabled'].forEach(key => {
+        if (mbkbucketVar[key] !== undefined && typeof mbkbucketVar[key] !== 'boolean') {
+            errors.push(`mbkbucketVar.${key} must be a boolean if provided`);
+        }
+    });
+
+    if (errors.length > 0) {
+        throw new Error(`[mbkbucket] Configuration Validation Failed:\n  - ${errors.join('\n  - ')}`);
+    }
+
+    const summary = usedDefaults.length > 0 ? ` (defaults applied: ${usedDefaults.join(', ')})` : '';
+    console.log(`[mbkbucket] Configuration loaded${summary}`);
+    return mbkbucketVar;
+}
+
+// Validate BucketConnection configuration
+function validateBucketConnection() {
+    if (!process.env.BucketConnection) {
+        console.warn(`[mbkbucket] ⚠️  BucketConnection not configured. You need to set this environment variable.`);
+        console.warn(`[mbkbucket] Example format:`);
+        console.warn(`[mbkbucket] BucketConnection={"r2":{"BUCKET_NAME":"my-bucket","ACCESS_KEY_ID":"key","SECRET_ACCESS_KEY":"secret","ENDPOINT":"https://..."}}`);
+        return;
+    }
+
+    try {
+        const bucketConfig = JSON.parse(process.env.BucketConnection);
+        
+        if (!bucketConfig || typeof bucketConfig !== 'object' || Object.keys(bucketConfig).length === 0) {
+            throw new Error('BucketConnection must be a non-empty object');
+        }
+
+        // Validate each bucket configuration
+        const bucketNames = Object.keys(bucketConfig);
+        for (const bucketName of bucketNames) {
+            const config = bucketConfig[bucketName];
+            
+            if (!config || typeof config !== 'object') {
+                throw new Error(`Bucket '${bucketName}' configuration must be an object, not a string. Remove quotes around the inner JSON object.`);
+            }
+            
+            const requiredFields = ['BUCKET_NAME', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY', 'ENDPOINT'];
+            const missingFields = requiredFields.filter(field => !config[field]);
+            
+            if (missingFields.length > 0) {
+                throw new Error(`Bucket '${bucketName}' is missing required fields: ${missingFields.join(', ')}`);
+            }
+        }
+
+        console.log(`[mbkbucket] ✓ BucketConnection validated (${bucketNames.length} bucket(s): ${bucketNames.join(', ')})`);
+        return bucketConfig;
+    } catch (error) {
+        console.error(`[mbkbucket] ❌ BucketConnection validation failed: ${error.message}`);
+        console.error(`[mbkbucket] Current value (excerpt): ${process.env.BucketConnection.slice(0, 200)}...`);
+        console.error(`[mbkbucket] Correct format example:`);
+        console.error(`[mbkbucket] BucketConnection={"r2":{"BUCKET_NAME":"my-bucket","ACCESS_KEY_ID":"key","SECRET_ACCESS_KEY":"secret","ENDPOINT":"https://endpoint.com"}}`);
+        console.error(`[mbkbucket] ⚠️  Note: Inner objects should NOT be quoted as strings!`);
+        throw new Error(`[mbkbucket] Invalid BucketConnection configuration`);
+    }
+}
+
+// Parse and validate mbkbucketVar once
+const mbkbucketVar = validateConfiguration();
+console.log(`[mbkbucket] mbkbucketVar configuration:`, mbkbucketVar);
+
+// Validate BucketConnection
+validateBucketConnection();
+
+export { packageJson, appVersion, getLatestVersion, checkVersion };
+export { mbkbucketVar };

package/lib/s3.js

@@ -1,4 +1,4 @@
-import { S3Client, ListObjectsV2Command, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, DeleteObjectsCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import { S3Client, ListObjectsV2Command, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, DeleteObjectsCommand, HeadObjectCommand, CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand, AbortMultipartUploadCommand, ListMultipartUploadsCommand } from '@aws-sdk/client-s3';
 import dotenv from "dotenv";
 import { mbkautheVar } from "mbkauthe";
 
@@ -11,35 +11,32 @@ function parseJsonEnv(envVar, fallback = {}) {
     } catch (e) {
         // Log a concise message including the error and a short excerpt of the env value when available
         console.error(`❌ Error parsing JSON for envVar: ${envVar ? String(envVar).slice(0, 200) : 'undefined'} - ${e.message}`);
+        console.error(`💡 Tip: Check that inner objects are NOT quoted as strings. Use {"key":{"field":"value"}} not {"key":"{"field":"value"}"}`);
         return fallback;
     }
 }
 
-const r2BucketConfig = parseJsonEnv(process.env.R2_Bucket, {});
-const e2BucketConfig = parseJsonEnv(process.env.E2_Bucket, {});
-const e2_1BucketConfig = parseJsonEnv(process.env.E2_1_Bucket, {});
-
-// Function to get bucket config by name or from single configured env var key via mbkautheVar.bucket
-export function getBucketConfig(bucketName = 'r2') {
-  // If a single configured bucket is set (the value is the ENV VAR name that contains the JSON config)
-  const configuredEnvKey = (mbkautheVar && mbkautheVar.bucket);
-  if (configuredEnvKey) {
-    const envVal = process.env[configuredEnvKey];
-    if (!envVal) throw new Error(`Configured bucket env var '${configuredEnvKey}' is not set`);
-    const parsed = parseJsonEnv(envVal, null);
-    if (!parsed || typeof parsed !== 'object') {
-      throw new Error(`Configured bucket env var '${configuredEnvKey}' contains invalid JSON`);
-    }
-    return parsed;
-  }
+// Parse BucketConnection JSON that contains all bucket configurations
+const allBucketConfigs = parseJsonEnv(process.env.BucketConnection, {});
 
-  if (bucketName === 'e2') return e2BucketConfig;
-  if (bucketName === 'e2_1') return e2_1BucketConfig;
-  return r2BucketConfig;
+// Helper to get default bucket name
+function getDefaultBucketName() {
+  // First priority: use mbkautheVar.bucket if configured
+  if (mbkautheVar && mbkautheVar.bucket) {
+    return mbkautheVar.bucket;
+  }
+  
+  // Second priority: use first bucket in BucketConnection
+  const buckets = Object.keys(allBucketConfigs);
+  if (buckets.length > 0) {
+    return buckets[0];
+  }
+  
+  // Fallback: return null (will cause error in getBucketConfig)
+  return null;
 }
 
-// Default client uses getBucketClient() which respects the configured bucket
-export const bucketClient = getBucketClient();
+// (bucketClient singleton exported below, after cache setup)
 
 // Helper: get configured APP_NAME; prefer mbkautheVar, then env var
 export function getAppName() {
@@ -51,6 +48,17 @@ export function ensureKeyHasAppPrefix(key = '') {
   const app = getAppName();
   if (!app) throw new Error('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
   if (!key) throw new Error('Key is required');
+  
+  // Security: Detect path traversal attempts
+  if (key.includes('../') || key.includes('..\\') || /\.\.[\\/]/.test(key)) {
+    throw new Error('Path traversal detected: invalid key');
+  }
+  
+  // Security: Block null bytes and control characters
+  if (/[\x00-\x1f\x7f]/.test(key)) {
+    throw new Error('Invalid characters in key');
+  }
+  
   let cleaned = String(key).replace(/^\/+/, '');
   // Collapse repeated app prefixes (app/app/... -> app/...)
   const appPrefixRegex = new RegExp(`^(?:${app}\/)+`);
@@ -66,10 +74,26 @@ export function ensureKeyHasAppPrefix(key = '') {
 export function ensurePrefix(prefix = '') {
   const app = getAppName();
   if (!app) throw new Error('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
-  let p = String(prefix || '').replace(/^\/+/, '').replace(/\/+$/g, '');
+  
+  // Security: Detect path traversal attempts
+  if (prefix && (prefix.includes('../') || prefix.includes('..\\') || /\.\.[\\/]/.test(prefix))) {
+    throw new Error('Path traversal detected: invalid prefix');
+  }
+  
+  // Security: Block null bytes and control characters
+  if (prefix && /[\x00-\x1f\x7f]/.test(prefix)) {
+    throw new Error('Invalid characters in prefix');
+  }
+  
+  // Only strip LEADING slashes. Preserve trailing slashes for directory listing.
+  let p = String(prefix || '').replace(/^\/+/, '');
+  
   if (!p) return `${app}`;
+  
   // If prefix already equals app or already starts with app/, normalize and return single app prefix
-  if (p === app) return app;
+  if (p === app) return app; // If p is exactly "app", we return "app". (Caller should append / if listing root)
+  if (p === `${app}/`) return `${app}/`;
+
   if (p.startsWith(`${app}/`)) {
     // collapse repeated app/ sequences
     const appPrefixRegex = new RegExp(`^(?:${app}\/)+`);
@@ -78,11 +102,57 @@ export function ensurePrefix(prefix = '') {
   return `${app}/${p}`;
 }  
 
-// Function to get S3 client for specific bucket
-export function getBucketClient(bucketName = 'r2') {
-  const config = getBucketConfig(bucketName);
+// ---------------------------------------------------------------------------
+// Singleton S3 client cache — one reused client per bucket key.
+// Avoids creating a new S3Client (and losing connection pooling) on every call.
+// ---------------------------------------------------------------------------
+const _clientCache = new Map();
+const _configCache = new Map();
+
+export function getBucketConfig(bucketName) {
+  // Resolve default bucket name if not provided
+  if (!bucketName) {
+    bucketName = getDefaultBucketName();
+    if (!bucketName) {
+      throw new Error('No bucket name provided and no default bucket configured. Please set mbkautheVar.bucket or configure BucketConnection.');
+    }
+  }
+  
+  const cacheKey = bucketName;
+  if (_configCache.has(cacheKey)) return _configCache.get(cacheKey);
+
+  // Look up bucket config from BucketConnection JSON
+  if (!allBucketConfigs || Object.keys(allBucketConfigs).length === 0) {
+    console.error(`[mbkbucket] ❌ BucketConnection is not configured or failed to parse`);
+    console.error(`[mbkbucket] Please set BucketConnection in your .env file with this format:`);
+    console.error(`[mbkbucket] BucketConnection={"r2":{"BUCKET_NAME":"...","ACCESS_KEY_ID":"...","SECRET_ACCESS_KEY":"...","ENDPOINT":"https://..."}}`);
+    console.error(`[mbkbucket] ⚠️  Important: Inner objects must NOT be quoted as strings!`);
+    console.error(`[mbkbucket] Wrong: {"r2":"{\\"BUCKET_NAME\\":\\"...\\"}"}  ❌`);
+    console.error(`[mbkbucket] Right: {"r2":{"BUCKET_NAME":"..."}}  ✓`);
+    throw new Error(`BucketConnection environment variable is not set or empty. Please configure it with your bucket connections.`);
+  }
+  
+  const cfg = allBucketConfigs[bucketName];
+  
+  if (!cfg) {
+    throw new Error(`Bucket '${bucketName}' not found in BucketConnection. Available buckets: ${Object.keys(allBucketConfigs).join(', ')}`);
+  }
+
+  _configCache.set(cacheKey, cfg);
+  return cfg;
+}
+
+// Function to get S3 client for specific bucket — returns cached singleton
+export function getBucketClient(bucketName) {
+  // Resolve default bucket name if not provided
+  if (!bucketName) {
+    bucketName = getDefaultBucketName();
+  }
   
-  return new S3Client({
+  if (_clientCache.has(bucketName)) return _clientCache.get(bucketName);
+
+  const config = getBucketConfig(bucketName);
+  const client = new S3Client({
     region: config.region || 'auto',
     endpoint: config.ENDPOINT,
     credentials: {
@@ -102,10 +172,16 @@ export function getBucketClient(bucketName = 'r2') {
     useAccelerateEndpoint: false,
     forcePathStyle: true,
   });
+
+  _clientCache.set(bucketName, client);
+  return client;
 }
 
-// Health check for R2 connection (moved up for startup test)
-async function checkR2Health() {
+// Default client singleton — reused by any external consumers that import it
+export const bucketClient = getBucketClient();
+
+// Health check for connection (moved up for startup test)
+async function checkHealth() {
   try {
     const startTime = Date.now();
     
@@ -143,14 +219,14 @@ async function checkR2Health() {
 (async () => {
   try {
     console.log('[mbkbucket] mbkautheVar snapshot:', { APP_NAME: mbkautheVar?.APP_NAME, bucket: mbkautheVar?.bucket });
-    const health = await checkR2Health();
+    const health = await checkHealth();
     if (health.status === 'healthy') {
       console.log(`[mbkbucket] Connected to bucket: ${health.bucket} (${health.responseTime}ms)`);
     } else {
-      console.error(`[mbkbucket] R2 connection failed:`, health.error);
+      console.error(`[mbkbucket] S3 connection failed:`, health.error);
     }
   } catch (err) {
-    console.error("[mbkbucket] R2 connection test error:", err.message);
+    console.error("[mbkbucket] S3 connection test error:", err.message);
   }
 })();
 
@@ -170,7 +246,8 @@ export async function uploadFile(key, fileBuffer, contentType, options = {}) {
       cacheControl = 'public, max-age=31536000', // 1 year default
       storageClass = 'STANDARD',
       serverSideEncryption = 'AES256',
-      bucketName = 'r2'
+      bucketName,
+      preventOverwrite = false // New option to prevent race conditions
     } = options;
     
     const client = getBucketClient(bucketName);
@@ -179,7 +256,7 @@ export async function uploadFile(key, fileBuffer, contentType, options = {}) {
 
     console.log(`[mbkbucket] Uploading file to bucket=${bucket} key=${keyToUpload}`);
 
-    // Add default metadata (R2 supports metadata)
+    // Add default metadata (supports metadata)
     const defaultMetadata = {
       'uploaded-at': new Date().toISOString(),
       'file-size': fileBuffer.length.toString(),
@@ -187,7 +264,7 @@ export async function uploadFile(key, fileBuffer, contentType, options = {}) {
       ...metadata
     };
 
-    const command = new PutObjectCommand({
+    const commandParams = {
       Bucket: bucket,
       Key: keyToUpload,
       Body: fileBuffer,
@@ -196,8 +273,14 @@ export async function uploadFile(key, fileBuffer, contentType, options = {}) {
       Metadata: defaultMetadata,
       ServerSideEncryption: serverSideEncryption,
       StorageClass: storageClass,
-      // Note: R2 doesn't support object tagging, so we remove the Tagging parameter
-    });
+    };
+    
+    // Add conditional upload to prevent overwriting (atomic operation)
+    if (preventOverwrite) {
+      commandParams.IfNoneMatch = '*'; // Only upload if object doesn't exist
+    }
+
+    const command = new PutObjectCommand(commandParams);
     
     const result = await client.send(command);
     
@@ -210,6 +293,12 @@ export async function uploadFile(key, fileBuffer, contentType, options = {}) {
     }; 
   } catch (error) {
     console.error(`Upload failed for key ${key}:`, error);
+    
+    // Handle precondition failed (file already exists)
+    if (error.name === 'PreconditionFailed' || error.$metadata?.httpStatusCode === 412) {
+      throw new Error('File already exists');
+    }
+    
     throw new Error(`Upload failed: ${error.message}`);
   }
 }
@@ -231,7 +320,7 @@ export async function downloadFile(key, options = {}) {
       ifModifiedSince = null,
       responseCacheControl = null,
       responseContentType = null,
-      bucketName = 'r2'
+      bucketName
     } = options;
     
     const client = getBucketClient(bucketName);
@@ -257,16 +346,9 @@ export async function downloadFile(key, options = {}) {
     const result = await client.send(command);
     const downloadTime = Date.now() - startTime;
     
-    // Log performance for large files
-    if (result.ContentLength > 10 * 1024 * 1024) {
-      console.log(`[mbkbucket] Large file download: ${keyToDownload}, Size: ${result.ContentLength} bytes, Time: ${downloadTime}ms`);
-    }
-    
     return {
       ...result,
       key: keyToDownload,
-      downloadedAt: new Date().toISOString(),
-      downloadTime
     }; 
   } catch (error) {
     console.error(`Download failed for key ${key}:`, error);
@@ -289,7 +371,7 @@ export async function downloadFile(key, options = {}) {
 }
 
 // Delete file with enhanced error handling
-export async function deleteFile(key, bucketName = 'r2') {
+export async function deleteFile(key, bucketName) {
   try {
     if (!key) {
       throw new Error('Key is required');
@@ -319,7 +401,7 @@ export async function deleteFile(key, bucketName = 'r2') {
 } 
 
 // Batch delete multiple files
-export async function deleteFiles(keys, bucketName = 'r2') {
+export async function deleteFiles(keys, bucketName) {
   try {
     if (!keys || !Array.isArray(keys) || keys.length === 0) {
       throw new Error('Keys array is required and must not be empty');
@@ -366,7 +448,7 @@ export async function deleteFiles(keys, bucketName = 'r2') {
  * Accepts either a folder key (may include trailing slash) or a relative prefix.
  * Normalizes the prefix to include the configured APP_NAME and ensures trailing slash.
  */
-export async function deleteFolder(prefix, bucketName = 'r2') {
+export async function deleteFolder(prefix, bucketName) {
   try {
     if (!prefix) {
       throw new Error('Prefix is required');
@@ -432,7 +514,7 @@ export async function listfiles(prefix = '', options = {}) {
       delimiter = null,
       fetchOwner = false,
       startAfter = null,
-      bucketName = 'r2'
+      bucketName
     } = options;
     
     // Enforce non-root prefix: default to APP_NAME and normalize
@@ -442,7 +524,6 @@ export async function listfiles(prefix = '', options = {}) {
     const config = getBucketConfig(bucketName);
     const bucket = config.BUCKET_NAME;
 
-    console.log(`[mbkbucket] Listing objects in bucket=${bucket} prefix=${effectivePrefix}`);
 
     const command = new ListObjectsV2Command({
       Bucket: bucket,
@@ -470,7 +551,7 @@ export async function listfiles(prefix = '', options = {}) {
 }
 
 // Get file metadata without downloading
-export async function getFileMetadata(key, bucketName = 'r2') {
+export async function getFileMetadata(key, bucketName) {
   try {
     if (!key) {
       throw new Error('Key is required');
@@ -509,7 +590,7 @@ export async function getFileMetadata(key, bucketName = 'r2') {
 } 
 
 // Check if file exists
-export async function fileExists(key, bucketName = 'r2') {
+export async function fileExists(key, bucketName) {
   try {
     const metadata = await getFileMetadata(key, bucketName);
     return metadata.exists;
@@ -519,7 +600,7 @@ export async function fileExists(key, bucketName = 'r2') {
 }
 
 // Get file size without downloading
-export async function getFileSize(key, bucketName = 'r2') {
+export async function getFileSize(key, bucketName) {
   try {
     const metadata = await getFileMetadata(key, bucketName);
     return metadata.exists ? metadata.ContentLength : null;
@@ -529,7 +610,89 @@ export async function getFileSize(key, bucketName = 'r2') {
 }
 
 // Export health check for external use
-export { checkR2Health };
+export { checkHealth };
+
+// ---------------------------------------------------------------------------
+// S3 Multipart Upload helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Initiate a multipart upload. Returns the S3 UploadId.
+ */
+export async function createMultipartUpload(key, contentType = 'application/octet-stream', metadata = {}) {
+  const keyToUse = ensureKeyHasAppPrefix(key);
+  const cfg = getBucketConfig();
+  const client = getBucketClient();
+  const command = new CreateMultipartUploadCommand({
+    Bucket: cfg.BUCKET_NAME,
+    Key: keyToUse,
+    ContentType: contentType,
+    Metadata: {
+      'upload-source': 'web-portal',
+      'uploaded-at': new Date().toISOString(),
+      ...metadata
+    }
+  });
+  const result = await client.send(command);
+  return { uploadId: result.UploadId, key: keyToUse };
+}
+
+/**
+ * Upload a single part. partNumber is 1-based.
+ * Returns the ETag needed for CompleteMultipartUpload.
+ */
+export async function uploadPart(key, uploadId, partNumber, buffer) {
+  const keyToUse = ensureKeyHasAppPrefix(key);
+  const cfg = getBucketConfig();
+  const client = getBucketClient();
+  const command = new UploadPartCommand({
+    Bucket: cfg.BUCKET_NAME,
+    Key: keyToUse,
+    UploadId: uploadId,
+    PartNumber: partNumber,
+    Body: buffer,
+    ContentLength: buffer.length
+  });
+  const result = await client.send(command);
+  return { ETag: result.ETag, partNumber };
+}
+
+/**
+ * Complete a multipart upload.
+ * parts must be an array of { partNumber, ETag } sorted ascending by partNumber.
+ */
+export async function completeMultipartUpload(key, uploadId, parts) {
+  const keyToUse = ensureKeyHasAppPrefix(key);
+  const cfg = getBucketConfig();
+  const client = getBucketClient();
+  const sorted = [...parts].sort((a, b) => a.partNumber - b.partNumber);
+  const command = new CompleteMultipartUploadCommand({
+    Bucket: cfg.BUCKET_NAME,
+    Key: keyToUse,
+    UploadId: uploadId,
+    MultipartUpload: {
+      Parts: sorted.map(p => ({ PartNumber: p.partNumber, ETag: p.ETag }))
+    }
+  });
+  await client.send(command);
+  return { key: keyToUse };
+}
+
+/**
+ * Abort an in-progress multipart upload, freeing all stored parts.
+ */
+export async function abortMultipartUpload(key, uploadId) {
+  const keyToUse = ensureKeyHasAppPrefix(key);
+  const cfg = getBucketConfig();
+  const client = getBucketClient();
+  const command = new AbortMultipartUploadCommand({
+    Bucket: cfg.BUCKET_NAME,
+    Key: keyToUse,
+    UploadId: uploadId
+  });
+  await client.send(command);
+  return { key: keyToUse, abortedAt: new Date().toISOString() };
+}
 
 // Generate signed URL for temporary access
 export async function generateSignedUrl(key, operation = 'getObject', expiresIn = 3600) {
@@ -566,3 +729,88 @@ export async function generateSignedUrl(key, operation = 'getObject', expiresIn
     throw new Error(`Generate signed URL failed: ${error.message}`);
   }
 }
+
+// ---------------------------------------------------------------------------
+// Multipart Upload Cleanup
+// ---------------------------------------------------------------------------
+
+/**
+ * List incomplete multipart uploads
+ * @param {string} prefix - Optional prefix to filter uploads
+ * @param {string} bucketName - Bucket name
+ * @returns {Promise<Array>} Array of incomplete multipart uploads
+ */
+export async function listIncompleteMultipartUploads(prefix = '', bucketName) {
+  try {
+    const effectivePrefix = prefix ? ensurePrefix(prefix) : getAppName();
+    const cfg = getBucketConfig(bucketName);
+    const client = getBucketClient(bucketName);
+    
+    const command = new ListMultipartUploadsCommand({
+      Bucket: cfg.BUCKET_NAME,
+      Prefix: effectivePrefix
+    });
+    
+    const result = await client.send(command);
+    return result.Uploads || [];
+  } catch (error) {
+    console.error('Failed to list incomplete multipart uploads:', error);
+    throw new Error(`Failed to list incomplete uploads: ${error.message}`);
+  }
+}
+
+/**
+ * Clean up old incomplete multipart uploads
+ * @param {number} olderThanDays - Delete uploads older than this many days (default: 7)
+ * @param {string} prefix - Optional prefix to filter uploads
+ * @param {string} bucketName - Bucket name
+ * @returns {Promise<Object>} Cleanup results with count of aborted uploads
+ */
+export async function cleanupIncompleteMultipartUploads(olderThanDays = 7, prefix = '', bucketName) {
+  try {
+    const uploads = await listIncompleteMultipartUploads(prefix, bucketName);
+    
+    if (!uploads.length) {
+      console.log('[mbkbucket] No incomplete multipart uploads found');
+      return { abortedCount: 0, uploads: [] };
+    }
+    
+    const cutoffDate = new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - olderThanDays);
+    
+    const uploadsToAbort = uploads.filter(upload => {
+      return upload.Initiated && new Date(upload.Initiated) < cutoffDate;
+    });
+    
+    if (!uploadsToAbort.length) {
+      console.log(`[mbkbucket] No incomplete uploads older than ${olderThanDays} days`);
+      return { abortedCount: 0, uploads: [] };
+    }
+    
+    console.log(`[mbkbucket] Found ${uploadsToAbort.length} incomplete uploads to clean up`);
+    
+    const aborted = [];
+    for (const upload of uploadsToAbort) {
+      try {
+        await abortMultipartUpload(upload.Key, upload.UploadId);
+        aborted.push({
+          key: upload.Key,
+          uploadId: upload.UploadId,
+          initiated: upload.Initiated
+        });
+        console.log(`[mbkbucket] Aborted incomplete upload: ${upload.Key} (initiated: ${upload.Initiated})`);
+      } catch (err) {
+        console.error(`[mbkbucket] Failed to abort upload ${upload.Key}:`, err);
+      }
+    }
+    
+    return {
+      abortedCount: aborted.length,
+      uploads: aborted,
+      cleanedAt: new Date().toISOString()
+    };
+  } catch (error) {
+    console.error('Cleanup of incomplete multipart uploads failed:', error);
+    throw new Error(`Cleanup failed: ${error.message}`);
+  }
+}