mbkbucket 1.5.0 → 2.0.0

package/.env.example

@@ -1,9 +1,9 @@
-mbkautheVar={"APP_NAME":"mbkbucket","loginRedirectURL":"/dashboard","bucket":""}
+mbkautheVar={"APP_NAME":"portal","loginRedirectURL":"/dashboard","bucket":"R2_Bucket"}
 mbkauthShared={"Main_SECRET_TOKEN": 123,"DOMAIN":"mbktech.org","IS_DEPLOYED":"false","EncPass":"false","DEVICE_TRUST_DURATION_DAYS":7,"SESSION_SECRET_KEY":"123","LOGIN_DB":"postgres://","MBKAUTH_TWO_FA_ENABLE":"true","COOKIE_EXPIRE_TIME":2,"GITHUB_LOGIN_ENABLED":"f","GITHUB_CLIENT_ID":"123","GITHUB_CLIENT_SECRET":"123","GOOGLE_LOGIN_ENABLED":"f","GOOGLE_CLIENT_ID":"123","GOOGLE_CLIENT_SECRET":"123"}
 # See @node_modules/mbkauthe/docs/env.md for more details
 NODE_ENV=development
 
-BucketConnection={"r2":{"BUCKET_NAME":"","ACCESS_KEY_ID":"","SECRET_ACCESS_KEY":"","ENDPOINT":""},"e2":{"BUCKET_NAME":"","ACCESS_KEY_ID":"","SECRET_ACCESS_KEY":"","ENDPOINT":"","Region":"ap-southeast-1"},"custom":{"BUCKET_NAME":"","ACCESS_KEY_ID":"","SECRET_ACCESS_KEY":"","ENDPOINT":"","Region":""}}
+BucketConnection={"R2_Bucket":{"BUCKET_NAME":"my-r2-bucket","ACCESS_KEY_ID":"your-r2-access-key","SECRET_ACCESS_KEY":"your-r2-secret","ENDPOINT":"https://accountid.r2.cloudflarestorage.com"},"S3_Bucket":{"BUCKET_NAME":"my-s3-bucket","ACCESS_KEY_ID":"your-s3-access-key","SECRET_ACCESS_KEY":"your-s3-secret","ENDPOINT":"https://s3.ap-southeast-1.amazonaws.com"}}
 # Region is optional
 
 mbkbucketVar={"publiView_enabled":"true","p_view_inline":"true"}

package/README.md

@@ -75,6 +75,78 @@ For complete API documentation, refer to the TypeScript declarations in [index.d
 
 ---
 
+## Environment Configuration
+
+The package validates both `mbkbucketVar` and `BucketConnection` at startup.
+
+### 1 `mbkautheVar`
+
+`mbkautheVar.bucket` is used as the default bucket.
+
+Example:
+
+```env
+mbkautheVar={"APP_NAME":"portal","loginRedirectURL":"/dashboard","bucket":"R2_Bucket"}
+```
+
+Notes:
+
+- If `APP_NAME` is `portal`, mbkbucket works from bucket root (no `portal/` folder prefix).
+- If `bucket` is missing, mbkbucket falls back to the first bucket key in `BucketConnection`.
+
+### 2 `BucketConnection`
+
+Use a JSON object where each key is a selectable connection name.
+
+Example:
+
+```env
+BucketConnection={"R2_Bucket":{"BUCKET_NAME":"my-r2-bucket","ACCESS_KEY_ID":"...","SECRET_ACCESS_KEY":"...","ENDPOINT":"https://<account-id>.r2.cloudflarestorage.com"},"S3_Bucket":{"BUCKET_NAME":"my-s3-bucket","ACCESS_KEY_ID":"...","SECRET_ACCESS_KEY":"...","ENDPOINT":"https://s3.ap-southeast-1.amazonaws.com"}}
+```
+
+Required fields per bucket:
+
+- `BUCKET_NAME`
+- `ACCESS_KEY_ID`
+- `SECRET_ACCESS_KEY`
+- `ENDPOINT`
+
+### Common Configuration Mistakes
+
+1. Quoted inner object (invalid)
+
+```env
+BucketConnection={"R2_Bucket":"{\"BUCKET_NAME\":\"...\"}"}
+```
+
+2. Correct inner object (valid)
+
+```env
+BucketConnection={"R2_Bucket":{"BUCKET_NAME":"...","ACCESS_KEY_ID":"...","SECRET_ACCESS_KEY":"...","ENDPOINT":"https://..."}}
+```
+
+### Runtime Selection
+
+- Admin page bucket selection: `/mbkbucket?bucket=R2_Bucket`
+- Public view route `/mbkbucket/p_view/:key(*)` always uses the default bucket from `mbkautheVar.bucket`.
+
+---
+
+## Automated Tests
+
+Run tests:
+
+```bash
+npm test
+```
+
+Current tests cover:
+
+- `mbkbucketVar` parsing/defaults/boolean normalization
+- `BucketConnection` shape validation and required fields
+
+---
+
 ## Contact & Support
 
 For questions, issues, or contributions, please reach out:

package/index.d.ts

@@ -1,6 +1,5 @@
-// Type definitions for mbkbucket 1.5.0
+// Type definitions for mbkbucket
 // Project: https://github.com/MIbnEKhalid/mbkbucket
-// Definitions by: Muhammad Bin Khalid <https://github.com/MIbnEKhalid">
 
 import { Readable } from "stream";
 import { Router, Application } from "express";
@@ -17,6 +16,8 @@ export interface BucketConfig {
   [key: string]: any;
 }
 
+export type BucketConnectionMap = Record<string, BucketConfig>;
+
 export interface S3ObjectResult {
   Body: Readable;
   ContentLength?: number;
@@ -26,18 +27,16 @@ export interface S3ObjectResult {
   [key: string]: any;
 }
 
-// Options passed to uploadFile
 export interface UploadOptions {
   metadata?: Record<string, string>;
   cacheControl?: string;
   storageClass?: string;
   serverSideEncryption?: string;
   bucketName?: string;
-  preventOverwrite?: boolean; // added in 1.4.1
+  preventOverwrite?: boolean;
   [key: string]: any;
 }
 
-// Options for listing files
 export interface ListFilesOptions {
   maxKeys?: number;
   continuationToken?: string | null;
@@ -48,7 +47,6 @@ export interface ListFilesOptions {
   [key: string]: any;
 }
 
-// Result returned from listfiles calls
 export interface ListFilesResult extends Record<string, any> {
   requestedAt: string;
   totalFiles: number;
@@ -56,7 +54,6 @@ export interface ListFilesResult extends Record<string, any> {
   nextToken: string | null;
 }
 
-// Incomplete multipart upload descriptor returned by AWS
 export interface IncompleteMultipartUpload {
   Key?: string;
   UploadId?: string;
@@ -65,7 +62,6 @@ export interface IncompleteMultipartUpload {
   [key: string]: any;
 }
 
-// Result returned by cleanupIncompleteMultipartUploads
 export interface CleanupResult {
   abortedCount: number;
   uploads: Array<{ key: string; uploadId: string; initiated?: string }>;
@@ -73,23 +69,31 @@ export interface CleanupResult {
   [key: string]: any;
 }
 
+export interface ConfigVars {
+  publiView_enabled: boolean;
+  p_view_inline: boolean;
+  [key: string]: any;
+}
+
 /**
- * S3-related functions (available from `mbkbucket/lib/s3` and re-exported at package root)
+ * S3 exports (re-exported from lib/s3.js at package root)
  */
+export function getAvailableBucketNames(): string[];
+export function resolveBucketName(bucketName?: string | null): string;
 export function getBucketConfig(bucketName?: string): BucketConfig;
 export const bucketClient: any;
 export function getAppName(): string;
 export function ensureKeyHasAppPrefix(key?: string): string;
 export function ensurePrefix(prefix?: string): string;
 export function getBucketClient(bucketName?: string): any;
-export function checkHealth(): Promise<{ status: string; responseTime?: number; bucket?: string; error?: string; checkedAt: string; region?: string }>;
+export function checkHealth(): Promise<{ status: string; responseTime?: number; bucket?: string; error?: string; checkedAt: string; region?: string; }>;
 
 export function uploadFile(
   key: string,
   fileBuffer: Buffer | Uint8Array,
   contentType: string,
   options?: UploadOptions
-): Promise<{ fileSize?: number; key: string; contentType?: string; uploadedAt?: string } & Record<string, any>>;
+): Promise<{ fileSize?: number; key: string; contentType?: string; uploadedAt?: string; } & Record<string, any>>;
 
 export function downloadFile(
   key: string,
@@ -121,10 +125,7 @@ export function deleteFolder(prefix: string, bucketName?: string): Promise<{
   prefix?: string;
 }>;
 
-export function listfiles(
-  prefix?: string,
-  options?: ListFilesOptions
-): Promise<ListFilesResult>;
+export function listfiles(prefix?: string, options?: ListFilesOptions): Promise<ListFilesResult>;
 
 export function getFileMetadata(key: string, bucketName?: string): Promise<{
   key: string;
@@ -141,8 +142,9 @@ export function getFileSize(key: string, bucketName?: string): Promise<number |
 
 export function generateSignedUrl(
   key: string,
-  operation?: 'getObject' | 'putObject' | string,
-  expiresIn?: number
+  operation?: "getObject" | "putObject" | string,
+  expiresIn?: number,
+  bucketName?: string
 ): Promise<{
   url: string;
   key: string;
@@ -152,31 +154,32 @@ export function generateSignedUrl(
   generatedAt: string;
 }>;
 
-/**
- * S3 Multipart Upload Functions
- */
 export function createMultipartUpload(
   key: string,
   contentType?: string,
-  metadata?: Record<string, string>
+  metadata?: Record<string, string>,
+  bucketName?: string
 ): Promise<{ uploadId: string; key: string }>;
 
 export function uploadPart(
   key: string,
   uploadId: string,
   partNumber: number,
-  buffer: Buffer | Uint8Array
+  buffer: Buffer | Uint8Array,
+  bucketName?: string
 ): Promise<{ ETag: string; partNumber: number }>;
 
 export function completeMultipartUpload(
   key: string,
   uploadId: string,
-  parts: Array<{ partNumber: number; ETag: string }>
+  parts: Array<{ partNumber: number; ETag: string }>,
+  bucketName?: string
 ): Promise<{ key: string }>;
 
 export function abortMultipartUpload(
   key: string,
-  uploadId: string
+  uploadId: string,
+  bucketName?: string
 ): Promise<{ key: string; abortedAt: string }>;
 
 export function listIncompleteMultipartUploads(
@@ -191,35 +194,33 @@ export function cleanupIncompleteMultipartUploads(
 ): Promise<CleanupResult>;
 
 /**
- * Configuration variables from mbkbucket
+ * Config exports (re-exported from lib/config/index.js at package root)
  */
-export interface ConfigVars {
-  publiView_enabled: boolean;
-  p_view_inline: boolean;
-  [key: string]: any;
-}
-
+export const packageJson: Record<string, any>;
+export const appVersion: string;
 export const mbkbucketVar: ConfigVars;
+export function getLatestVersion(): Promise<string | null>;
+export function checkVersion(): Promise<void>;
+export function parseAndValidateMbkbucketVar(rawValue?: string): ConfigVars;
+export function parseAndValidateBucketConnection(rawValue?: string): BucketConnectionMap | null;
 
 /**
- * Exported router from `lib/bucket` (re-exported at package root as `bucket`)
+ * Router export (re-exported from lib/routes/index.js at package root as `bucket`)
  */
 export const bucket: Router;
 
 /**
- * Root default export: the configured Express application
+ * Root default export from index.js: configured Express application
  */
 declare const server: Application;
 export default server;
 
 /**
- * Module declarations for subpath imports so TypeScript consumers can import:
- * import { uploadFile } from 'mbkbucket/lib/s3';
- * import { packageJson } from 'mbkbucket/lib/config/index';
- * import bucketRouter from 'mbkbucket/lib/bucket';
+ * Subpath module declarations
  */
 declare module "mbkbucket/lib/s3" {
   import { Readable } from "stream";
+
   export interface BucketConfig {
     BUCKET_NAME: string;
     ENDPOINT?: string;
@@ -228,6 +229,9 @@ declare module "mbkbucket/lib/s3" {
     region?: string;
     [key: string]: any;
   }
+
+  export type BucketConnectionMap = Record<string, BucketConfig>;
+
   export interface S3ObjectResult {
     Body: Readable;
     ContentLength?: number;
@@ -237,7 +241,6 @@ declare module "mbkbucket/lib/s3" {
     [key: string]: any;
   }
 
-  // re-use shared interfaces defined at top of index.d.ts
   export interface UploadOptions {
     metadata?: Record<string, string>;
     cacheControl?: string;
@@ -247,6 +250,7 @@ declare module "mbkbucket/lib/s3" {
     preventOverwrite?: boolean;
     [key: string]: any;
   }
+
   export interface ListFilesOptions {
     maxKeys?: number;
     continuationToken?: string | null;
@@ -256,12 +260,14 @@ declare module "mbkbucket/lib/s3" {
     bucketName?: string;
     [key: string]: any;
   }
+
   export interface ListFilesResult extends Record<string, any> {
     requestedAt: string;
     totalFiles: number;
     hasMore: boolean;
     nextToken: string | null;
   }
+
   export interface IncompleteMultipartUpload {
     Key?: string;
     UploadId?: string;
@@ -269,6 +275,7 @@ declare module "mbkbucket/lib/s3" {
     Initiator?: { DisplayName?: string; [key: string]: any };
     [key: string]: any;
   }
+
   export interface CleanupResult {
     abortedCount: number;
     uploads: Array<{ key: string; uploadId: string; initiated?: string }>;
@@ -276,13 +283,15 @@ declare module "mbkbucket/lib/s3" {
     [key: string]: any;
   }
 
+  export function getAvailableBucketNames(): string[];
+  export function resolveBucketName(bucketName?: string | null): string;
   export function getBucketConfig(bucketName?: string): BucketConfig;
   export const bucketClient: any;
   export function getAppName(): string;
   export function ensureKeyHasAppPrefix(key?: string): string;
   export function ensurePrefix(prefix?: string): string;
   export function getBucketClient(bucketName?: string): any;
-  export function checkHealth(): Promise<{ status: string; responseTime?: number; bucket?: string; error?: string; checkedAt: string; region?: string }>;
+  export function checkHealth(): Promise<{ status: string; responseTime?: number; bucket?: string; error?: string; checkedAt: string; region?: string; }>;
 
   export function uploadFile(
     key: string,
@@ -320,10 +329,7 @@ declare module "mbkbucket/lib/s3" {
     prefix?: string;
   }>;
 
-  export function listfiles(
-    prefix?: string,
-    options?: ListFilesOptions
-  ): Promise<ListFilesResult>;
+  export function listfiles(prefix?: string, options?: ListFilesOptions): Promise<ListFilesResult>;
 
   export function getFileMetadata(key: string, bucketName?: string): Promise<{
     key: string;
@@ -337,10 +343,12 @@ declare module "mbkbucket/lib/s3" {
 
   export function fileExists(key: string, bucketName?: string): Promise<boolean>;
   export function getFileSize(key: string, bucketName?: string): Promise<number | null>;
+
   export function generateSignedUrl(
     key: string,
-    operation?: 'getObject' | 'putObject' | string,
-    expiresIn?: number
+    operation?: "getObject" | "putObject" | string,
+    expiresIn?: number,
+    bucketName?: string
   ): Promise<{
     url: string;
     key: string;
@@ -353,25 +361,29 @@ declare module "mbkbucket/lib/s3" {
   export function createMultipartUpload(
     key: string,
     contentType?: string,
-    metadata?: Record<string, string>
+    metadata?: Record<string, string>,
+    bucketName?: string
   ): Promise<{ uploadId: string; key: string }>;
 
   export function uploadPart(
     key: string,
     uploadId: string,
     partNumber: number,
-    buffer: Buffer | Uint8Array
+    buffer: Buffer | Uint8Array,
+    bucketName?: string
   ): Promise<{ ETag: string; partNumber: number }>;
 
   export function completeMultipartUpload(
     key: string,
     uploadId: string,
-    parts: Array<{ partNumber: number; ETag: string }>
+    parts: Array<{ partNumber: number; ETag: string }>,
+    bucketName?: string
   ): Promise<{ key: string }>;
 
   export function abortMultipartUpload(
     key: string,
-    uploadId: string
+    uploadId: string,
+    bucketName?: string
   ): Promise<{ key: string; abortedAt: string }>;
 
   export function listIncompleteMultipartUploads(
@@ -392,11 +404,37 @@ declare module "mbkbucket/lib/config/index" {
     p_view_inline: boolean;
     [key: string]: any;
   }
+
+  export interface BucketConfig {
+    BUCKET_NAME: string;
+    ENDPOINT?: string;
+    ACCESS_KEY_ID?: string;
+    SECRET_ACCESS_KEY?: string;
+    region?: string;
+    [key: string]: any;
+  }
+
+  export type BucketConnectionMap = Record<string, BucketConfig>;
+
   export const packageJson: Record<string, any>;
   export const appVersion: string;
   export const mbkbucketVar: ConfigVars;
   export function getLatestVersion(): Promise<string | null>;
   export function checkVersion(): Promise<void>;
+  export function parseAndValidateMbkbucketVar(rawValue?: string): ConfigVars;
+  export function parseAndValidateBucketConnection(rawValue?: string): BucketConnectionMap | null;
+}
+
+declare module "mbkbucket/lib/config/validation" {
+  export function normalizeBooleanLike(value: any): any;
+  export function parseAndValidateMbkbucketVar(rawValue?: string): { [key: string]: any };
+  export function parseAndValidateBucketConnection(rawValue?: string): Record<string, any> | null;
+}
+
+declare module "mbkbucket/lib/routes/index" {
+  import { Router } from "express";
+  const router: Router;
+  export default router;
 }
 
 declare module "mbkbucket/lib/bucket" {

package/index.js

@@ -8,22 +8,17 @@ import compression from "compression";
 import rateLimit from 'express-rate-limit';
 import bucketRoutes from "./lib/routes/index.js";
 import { checkVersion } from "./lib/config/index.js";
-import { appVersion } from "./lib/config/index.js";
+import { packageJson } from "./lib/config/index.js";
 
 dotenv.config();
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const assetVersion = appVersion;
 
 const server = express();
 server.set('trust proxy', 1);
 
 server.use(compression());
-server.use((req, res, next) => {
-  res.locals.assetVersion = assetVersion;
-  next();
-});
 
 // Rate limiting: general limiter for typical browsing/API usage and a stricter
 // limiter for dashboard (admin) routes.
@@ -37,21 +32,24 @@ const generalLimiter = rateLimit({
   }
 });
 
-server.use(express.json());
-server.use(express.urlencoded({ extended: true }));
+// Increase body size limits to support larger form submissions (e.g., multipart upload init/complete payloads).
+// Multipart/form-data uploads themselves are handled separately via multer in the upload endpoints.
+server.use(express.json({ limit: '10mb' }));
+server.use(express.urlencoded({ extended: true, limit: '10mb' }));
 
-// Serve only specific static assets (limit exposure): CSS and JS used by the dashboard
-// This replaces serving the entire /public directory.
-const staticMaxAgeSeconds = 90 * 24 * 60 * 60; // 90 days
+// Serve only specific static assets (limit exposure): CSS and JS used by the dashboard.
+// Avoid immutable long cache here because dashboard routes change frequently and stale JS
+// can keep writing old URLs in browser history.
+const dashboardAssetCacheControl = 'public, max-age=300, must-revalidate';
 server.get('/mbkbucket/bucketadmin.css', (req, res) => {
-  res.set('Cache-Control', `public, max-age=${staticMaxAgeSeconds}, immutable`);
+  res.set('Cache-Control', dashboardAssetCacheControl);
   res.sendFile(path.join(__dirname, 'public', 'bucketadmin.css'), (err) => {
     if (err) res.status(err.status || 404).end();
   });
 });
 
 server.get('/mbkbucket/bucketadmin.js', (req, res) => {
-  res.set('Cache-Control', `public, max-age=${staticMaxAgeSeconds}, immutable`);
+  res.set('Cache-Control', dashboardAssetCacheControl);
   res.sendFile(path.join(__dirname, 'public', 'bucketadmin.js'), (err) => {
     if (err) res.status(err.status || 404).end();
   });
@@ -61,6 +59,7 @@ server.get('/mbkbucket/bucketadmin.js', (req, res) => {
 server.engine("handlebars", engine({
   extname: ".handlebars",
   defaultLayout: "main",
+  layoutsDir: path.join(__dirname, "../../views/layouts"),
   partialsDir: [
     path.join(__dirname, "views/templates"),
     path.join(__dirname, "views/templates/notice"),
@@ -73,6 +72,9 @@ server.engine("handlebars", engine({
   helpers: {
     eq: function (a, b) {
       return a === b;
+    },
+    mbkbucket_cachebuster: function () {
+      return "?v=" + packageJson.version;
     }
   }
 }));

package/lib/config/index.js

@@ -1,5 +1,6 @@
 import { createRequire } from "module";
 import dotenv from "dotenv";
+import { parseAndValidateMbkbucketVar, parseAndValidateBucketConnection } from "./validation.js";
 
 dotenv.config();
 
@@ -60,78 +61,16 @@ async function checkVersion() {
 
 // Comprehensive validation function
 function validateConfiguration() {
-    const errors = [];
-
-    // Parse and validate mbkbucketVar
-    let mbkbucketVar;
     try {
+        const parsed = parseAndValidateMbkbucketVar(process.env.mbkbucketVar);
         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);
         }
+        console.log(`[mbkbucket] Configuration loaded`);
+        return parsed;
     } 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;
+        throw new Error(`[mbkbucket] Configuration Validation Failed:\n  - ${error.message}`);
     }
-
-    // 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
@@ -144,28 +83,8 @@ function validateBucketConnection() {
     }
 
     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(', ')}`);
-            }
-        }
+        const bucketConfig = parseAndValidateBucketConnection(process.env.BucketConnection);
+        const bucketNames = Object.keys(bucketConfig || {});
 
         console.log(`[mbkbucket] ✓ BucketConnection validated (${bucketNames.length} bucket(s): ${bucketNames.join(', ')})`);
         return bucketConfig;
@@ -187,4 +106,5 @@ console.log(`[mbkbucket] mbkbucketVar configuration:`, mbkbucketVar);
 validateBucketConnection();
 
 export { packageJson, appVersion, getLatestVersion, checkVersion };
-export { mbkbucketVar };
+export { mbkbucketVar };
+export { parseAndValidateMbkbucketVar, parseAndValidateBucketConnection };