mbkbucket 1.5.1 → 2.1.0

package/lib/s3.js

@@ -1,8 +1,10 @@
 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";
+import { createLogger } from "./debug.js";
 
 dotenv.config();
+const debugS3 = createLogger('s3');
 
 function parseJsonEnv(envVar, fallback = {}) {
     if (!envVar) return fallback;
@@ -18,6 +20,16 @@ function parseJsonEnv(envVar, fallback = {}) {
 
 // Parse BucketConnection JSON that contains all bucket configurations
 const allBucketConfigs = parseJsonEnv(process.env.BucketConnection, {});
+const availableBucketNames = Object.freeze(Object.keys(allBucketConfigs || {}));
+const hasBucketConfigs = availableBucketNames.length > 0;
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function getAvailableBucketNames() {
+  return availableBucketNames;
+}
 
 // Helper to get default bucket name
 function getDefaultBucketName() {
@@ -27,15 +39,34 @@ function getDefaultBucketName() {
   }
   
   // Second priority: use first bucket in BucketConnection
-  const buckets = Object.keys(allBucketConfigs);
-  if (buckets.length > 0) {
-    return buckets[0];
+  if (availableBucketNames.length > 0) {
+    return availableBucketNames[0];
   }
   
   // Fallback: return null (will cause error in getBucketConfig)
   return null;
 }
 
+export function resolveBucketName(bucketName) {
+  const candidate = (bucketName === undefined || bucketName === null)
+    ? getDefaultBucketName()
+    : String(bucketName).trim();
+
+  if (!candidate) {
+    throw new Error('No bucket selected. Provide ?bucket=<name> or configure a default bucket in mbkautheVar.bucket.');
+  }
+
+  if (!hasBucketConfigs) {
+    throw new Error('BucketConnection environment variable is not set or empty. Please configure it with your bucket connections.');
+  }
+
+  if (!allBucketConfigs[candidate]) {
+    throw new Error(`Bucket '${candidate}' not found in BucketConnection. Available buckets: ${availableBucketNames.join(', ')}`);
+  }
+
+  return candidate;
+}
+
 // (bucketClient singleton exported below, after cache setup)
 
 // Helper: get configured APP_NAME; prefer mbkautheVar, then env var
@@ -44,9 +75,12 @@ export function getAppName() {
   return (typeof app === 'string' && app.trim()) ? app.trim() : '';
 }
 
+function isRootModeApp(appName) {
+  return String(appName || '').trim().toLowerCase() === 'portal';
+}
+
 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
@@ -60,8 +94,16 @@ export function ensureKeyHasAppPrefix(key = '') {
   }
   
   let cleaned = String(key).replace(/^\/+/, '');
+
+  // Special case: APP_NAME=portal means operate from bucket root.
+  if (isRootModeApp(app)) {
+    return cleaned;
+  }
+
+  if (!app) throw new Error('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
+
   // Collapse repeated app prefixes (app/app/... -> app/...)
-  const appPrefixRegex = new RegExp(`^(?:${app}\/)+`);
+  const appPrefixRegex = new RegExp(`^(?:${escapeRegExp(app)}\/)+`);
   if (!cleaned.startsWith(`${app}/`)) {
     cleaned = `${app}/${cleaned}`;
   } else {
@@ -73,7 +115,6 @@ 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');
   
   // Security: Detect path traversal attempts
   if (prefix && (prefix.includes('../') || prefix.includes('..\\') || /\.\.[\\/]/.test(prefix))) {
@@ -87,6 +128,13 @@ export function ensurePrefix(prefix = '') {
   
   // Only strip LEADING slashes. Preserve trailing slashes for directory listing.
   let p = String(prefix || '').replace(/^\/+/, '');
+
+  // Special case: APP_NAME=portal means operate from bucket root.
+  if (isRootModeApp(app)) {
+    return p;
+  }
+
+  if (!app) throw new Error('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
   
   if (!p) return `${app}`;
   
@@ -96,7 +144,7 @@ export function ensurePrefix(prefix = '') {
 
   if (p.startsWith(`${app}/`)) {
     // collapse repeated app/ sequences
-    const appPrefixRegex = new RegExp(`^(?:${app}\/)+`);
+    const appPrefixRegex = new RegExp(`^(?:${escapeRegExp(app)}\/)+`);
     return p.replace(appPrefixRegex, `${app}/`);
   }
   return `${app}/${p}`;
@@ -110,19 +158,13 @@ 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.');
-    }
-  }
+  bucketName = resolveBucketName(bucketName);
   
   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) {
+  if (!hasBucketConfigs) {
     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://..."}}`);
@@ -135,7 +177,7 @@ export function getBucketConfig(bucketName) {
   const cfg = allBucketConfigs[bucketName];
   
   if (!cfg) {
-    throw new Error(`Bucket '${bucketName}' not found in BucketConnection. Available buckets: ${Object.keys(allBucketConfigs).join(', ')}`);
+    throw new Error(`Bucket '${bucketName}' not found in BucketConnection. Available buckets: ${availableBucketNames.join(', ')}`);
   }
 
   _configCache.set(cacheKey, cfg);
@@ -144,10 +186,7 @@ export function getBucketConfig(bucketName) {
 
 // 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();
-  }
+  bucketName = resolveBucketName(bucketName);
   
   if (_clientCache.has(bucketName)) return _clientCache.get(bucketName);
 
@@ -218,10 +257,10 @@ async function checkHealth() {
 // Quick diagnostics at startup
 (async () => {
   try {
-    console.log('[mbkbucket] mbkautheVar snapshot:', { APP_NAME: mbkautheVar?.APP_NAME, bucket: mbkautheVar?.bucket });
+    debugS3('mbkautheVar snapshot: %O', { APP_NAME: mbkautheVar?.APP_NAME, bucket: mbkautheVar?.bucket });
     const health = await checkHealth();
     if (health.status === 'healthy') {
-      console.log(`[mbkbucket] Connected to bucket: ${health.bucket} (${health.responseTime}ms)`);
+      debugS3('Connected to bucket: %s (%sms)', health.bucket, health.responseTime);
     } else {
       console.error(`[mbkbucket] S3 connection failed:`, health.error);
     }
@@ -254,11 +293,12 @@ export async function uploadFile(key, fileBuffer, contentType, options = {}) {
     const config = getBucketConfig(bucketName);
     const bucket = config.BUCKET_NAME;
 
-    console.log(`[mbkbucket] Uploading file to bucket=${bucket} key=${keyToUpload}`);
+    debugS3('Uploading file to bucket=%s key=%s', bucket, keyToUpload);
 
     // Add default metadata (supports metadata)
+    const uploadedAt = new Date().toISOString();
     const defaultMetadata = {
-      'uploaded-at': new Date().toISOString(),
+      'uploaded-at': uploadedAt,
       'file-size': fileBuffer.length.toString(),
       'upload-source': 'web-portal',
       ...metadata
@@ -289,7 +329,7 @@ export async function uploadFile(key, fileBuffer, contentType, options = {}) {
       fileSize: fileBuffer.length,
       key: keyToUpload,
       contentType,
-      uploadedAt: new Date().toISOString()
+      uploadedAt
     }; 
   } catch (error) {
     console.error(`Upload failed for key ${key}:`, error);
@@ -329,7 +369,7 @@ export async function downloadFile(key, options = {}) {
 
     // Log range requests for debugging
     if (range) {
-      console.log(`[mbkbucket] Range request for ${keyToDownload}: ${range}`);
+      debugS3('Range request for %s: %s', keyToDownload, range);
     }
 
     const command = new GetObjectCommand({
@@ -342,9 +382,7 @@ export async function downloadFile(key, options = {}) {
       ...(responseContentType && { ResponseContentType: responseContentType }),
     });
     
-    const startTime = Date.now();
     const result = await client.send(command);
-    const downloadTime = Date.now() - startTime;
     
     return {
       ...result,
@@ -414,6 +452,8 @@ export async function deleteFiles(keys, bucketName) {
     // S3 allows max 1000 objects per delete request
     const maxBatchSize = 1000;
     const results = [];
+    let deletedCount = 0;
+    const errors = [];
 
     for (let i = 0; i < keys.length; i += maxBatchSize) {
       const batch = keys.slice(i, i + maxBatchSize).map(k => ({ Key: ensureKeyHasAppPrefix(k) }));
@@ -428,12 +468,14 @@ export async function deleteFiles(keys, bucketName) {
 
       const result = await client.send(command);
       results.push(result);
+      deletedCount += result.Deleted?.length || 0;
+      if (result.Errors?.length) errors.push(...result.Errors);
     }
 
     return {
       results,
-      deletedCount: results.reduce((acc, result) => acc + (result.Deleted?.length || 0), 0),
-      errors: results.reduce((acc, result) => acc.concat(result.Errors || []), []),
+      deletedCount,
+      errors,
       deletedAt: new Date().toISOString()
     };
   } catch (error) {
@@ -568,19 +610,21 @@ export async function getFileMetadata(key, bucketName) {
     });
     
     const result = await client.send(command);
+    const queriedAt = new Date().toISOString();
     
     return {
       ...result,
       key: keyToCheck,
       exists: true,
-      queriedAt: new Date().toISOString()
+      queriedAt
     };
   } catch (error) {
+    const queriedAt = new Date().toISOString();
     if (error.name === 'NotFound' || error.name === 'NoSuchKey') {
       return {
         key,
         exists: false,
-        queriedAt: new Date().toISOString()
+        queriedAt
       };
     }
     
@@ -619,17 +663,18 @@ export { checkHealth };
 /**
  * Initiate a multipart upload. Returns the S3 UploadId.
  */
-export async function createMultipartUpload(key, contentType = 'application/octet-stream', metadata = {}) {
+export async function createMultipartUpload(key, contentType = 'application/octet-stream', metadata = {}, bucketName) {
   const keyToUse = ensureKeyHasAppPrefix(key);
-  const cfg = getBucketConfig();
-  const client = getBucketClient();
+  const cfg = getBucketConfig(bucketName);
+  const client = getBucketClient(bucketName);
+  const uploadedAt = new Date().toISOString();
   const command = new CreateMultipartUploadCommand({
     Bucket: cfg.BUCKET_NAME,
     Key: keyToUse,
     ContentType: contentType,
     Metadata: {
       'upload-source': 'web-portal',
-      'uploaded-at': new Date().toISOString(),
+      'uploaded-at': uploadedAt,
       ...metadata
     }
   });
@@ -641,10 +686,10 @@ export async function createMultipartUpload(key, contentType = 'application/octe
  * Upload a single part. partNumber is 1-based.
  * Returns the ETag needed for CompleteMultipartUpload.
  */
-export async function uploadPart(key, uploadId, partNumber, buffer) {
+export async function uploadPart(key, uploadId, partNumber, buffer, bucketName) {
   const keyToUse = ensureKeyHasAppPrefix(key);
-  const cfg = getBucketConfig();
-  const client = getBucketClient();
+  const cfg = getBucketConfig(bucketName);
+  const client = getBucketClient(bucketName);
   const command = new UploadPartCommand({
     Bucket: cfg.BUCKET_NAME,
     Key: keyToUse,
@@ -661,10 +706,10 @@ export async function uploadPart(key, uploadId, partNumber, buffer) {
  * Complete a multipart upload.
  * parts must be an array of { partNumber, ETag } sorted ascending by partNumber.
  */
-export async function completeMultipartUpload(key, uploadId, parts) {
+export async function completeMultipartUpload(key, uploadId, parts, bucketName) {
   const keyToUse = ensureKeyHasAppPrefix(key);
-  const cfg = getBucketConfig();
-  const client = getBucketClient();
+  const cfg = getBucketConfig(bucketName);
+  const client = getBucketClient(bucketName);
   const sorted = [...parts].sort((a, b) => a.partNumber - b.partNumber);
   const command = new CompleteMultipartUploadCommand({
     Bucket: cfg.BUCKET_NAME,
@@ -681,10 +726,10 @@ export async function completeMultipartUpload(key, uploadId, parts) {
 /**
  * Abort an in-progress multipart upload, freeing all stored parts.
  */
-export async function abortMultipartUpload(key, uploadId) {
+export async function abortMultipartUpload(key, uploadId, bucketName) {
   const keyToUse = ensureKeyHasAppPrefix(key);
-  const cfg = getBucketConfig();
-  const client = getBucketClient();
+  const cfg = getBucketConfig(bucketName);
+  const client = getBucketClient(bucketName);
   const command = new AbortMultipartUploadCommand({
     Bucket: cfg.BUCKET_NAME,
     Key: keyToUse,
@@ -695,26 +740,26 @@ export async function abortMultipartUpload(key, uploadId) {
 }
 
 // Generate signed URL for temporary access
-export async function generateSignedUrl(key, operation = 'getObject', expiresIn = 3600) {
+export async function generateSignedUrl(key, operation = 'getObject', expiresIn = 3600, bucketName) {
   try {
     const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner');
     const keyToUse = ensureKeyHasAppPrefix(key);
     
     let command;
-    const cfg = getBucketConfig();
-    const bucketName = cfg.BUCKET_NAME;
+    const cfg = getBucketConfig(bucketName);
+    const resolvedBucketName = cfg.BUCKET_NAME;
     switch (operation) {
       case 'getObject':
-        command = new GetObjectCommand({ Bucket: bucketName, Key: keyToUse });
+        command = new GetObjectCommand({ Bucket: resolvedBucketName, Key: keyToUse });
         break;
       case 'putObject':
-        command = new PutObjectCommand({ Bucket: bucketName, Key: keyToUse });
+        command = new PutObjectCommand({ Bucket: resolvedBucketName, Key: keyToUse });
         break;
       default:
         throw new Error(`Unsupported operation: ${operation}`);
     }
     
-    const signedUrl = await getSignedUrl(bucketClient, command, { expiresIn });
+    const signedUrl = await getSignedUrl(getBucketClient(bucketName), command, { expiresIn });
     
     return {
       url: signedUrl,
@@ -742,7 +787,7 @@ export async function generateSignedUrl(key, operation = 'getObject', expiresIn
  */
 export async function listIncompleteMultipartUploads(prefix = '', bucketName) {
   try {
-    const effectivePrefix = prefix ? ensurePrefix(prefix) : getAppName();
+    const effectivePrefix = ensurePrefix(prefix || '');
     const cfg = getBucketConfig(bucketName);
     const client = getBucketClient(bucketName);
     
@@ -771,7 +816,7 @@ export async function cleanupIncompleteMultipartUploads(olderThanDays = 7, prefi
     const uploads = await listIncompleteMultipartUploads(prefix, bucketName);
     
     if (!uploads.length) {
-      console.log('[mbkbucket] No incomplete multipart uploads found');
+      debugS3('No incomplete multipart uploads found');
       return { abortedCount: 0, uploads: [] };
     }
     
@@ -783,22 +828,22 @@ export async function cleanupIncompleteMultipartUploads(olderThanDays = 7, prefi
     });
     
     if (!uploadsToAbort.length) {
-      console.log(`[mbkbucket] No incomplete uploads older than ${olderThanDays} days`);
+      debugS3('No incomplete uploads older than %s days', olderThanDays);
       return { abortedCount: 0, uploads: [] };
     }
     
-    console.log(`[mbkbucket] Found ${uploadsToAbort.length} incomplete uploads to clean up`);
+    debugS3('Found %s incomplete uploads to clean up', uploadsToAbort.length);
     
     const aborted = [];
     for (const upload of uploadsToAbort) {
       try {
-        await abortMultipartUpload(upload.Key, upload.UploadId);
+        await abortMultipartUpload(upload.Key, upload.UploadId, bucketName);
         aborted.push({
           key: upload.Key,
           uploadId: upload.UploadId,
           initiated: upload.Initiated
         });
-        console.log(`[mbkbucket] Aborted incomplete upload: ${upload.Key} (initiated: ${upload.Initiated})`);
+        debugS3('Aborted incomplete upload: %s (initiated: %s)', upload.Key, upload.Initiated);
       } catch (err) {
         console.error(`[mbkbucket] Failed to abort upload ${upload.Key}:`, err);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbkbucket",
-  "version": "1.5.1",
+  "version": "2.1.0",
   "description": "Flexible S3/R2 bucket management library and Express router for mbktech.org applications, providing upload, download, listing, and multipart utilities with built-in configuration validation and health checks",
   "author": "Muhammad Bin Khalid",
   "homepage": "https://github.com/MIbnEKhalid/mbkbucket#readme",
@@ -9,18 +9,19 @@
   "type": "module",
   "types": "index.d.ts",
   "scripts": {
-    "dev": "cross-env mbkbucket_test=dev nodemon index.js",
-    "test": "echo \\\"Error: no test specified\\\" && exit 1"
+    "dev": "cross-env NODE_ENV=dev nodemon index.js",
+    "test": "node --test"
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.968.0",
     "@aws-sdk/s3-request-presigner": "^3.1000.0",
     "compression": "^1.8.0",
+    "debug": "^2.6.9",
     "dotenv": "^16.6.1",
     "express": "^4.22.1",
     "express-handlebars": "^8.0.3",
     "express-rate-limit": "^7.0.1",
-    "mbkauthe": "latest",
+    "mbkauthe": "5.0.4",
     "multer": "^2.0.2",
     "pg": "^8.16.3"
   },
@@ -49,4 +50,4 @@
     "mbkauthe",
     "mbktech.org"
   ]
-}
+}