mbkbucket 1.5.1 → 2.1.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,20 @@ 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";
+import { createLogger } from "./lib/debug.js";
 
 dotenv.config();
+const debugServer = createLogger('server');
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const assetVersion = appVersion;
+const isDevMode = process.env.NODE_ENV === "dev";
 
 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.
@@ -42,18 +40,19 @@ const generalLimiter = rateLimit({
 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();
   });
@@ -63,6 +62,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"),
@@ -75,6 +75,9 @@ server.engine("handlebars", engine({
   helpers: {
     eq: function (a, b) {
       return a === b;
+    },
+    mbkbucket_cachebuster: function () {
+      return "?v=" + packageJson.version;
     }
   }
 }));
@@ -89,11 +92,8 @@ server.set("views", [
 server.use(mbkautheRoutes);
 server.use(generalLimiter);
 server.use(bucketRoutes);
-
-if (process.env.mbkbucket_test === "dev") {
-
-  console.log("[mbkbucket] Dev mode is enabled. Starting server in dev mode.");
-
+if (isDevMode) {
+  debugServer("Dev mode is enabled. Starting server in dev mode.");
 
   // Request timing middleware: logs method, url, status and elapsed ms
   server.use((req, res, next) => {
@@ -101,7 +101,7 @@ if (process.env.mbkbucket_test === "dev") {
     res.on('finish', () => {
       const diff = process.hrtime(start);
       const ms = diff[0] * 1000 + diff[1] / 1e6;
-      console.log(`[mbkbucket] [${new Date().toISOString()}] ${req.method} ${req.originalUrl} ${res.statusCode} - ${ms.toFixed(3)} ms`);
+      debugServer("[%s] %s %s %s - %s ms", new Date().toISOString(), req.method, req.originalUrl, res.statusCode, ms.toFixed(3));
     });
     next();
   });
@@ -112,7 +112,7 @@ if (process.env.mbkbucket_test === "dev") {
 
   // 404 handler
   server.use((req, res) => {
-    console.log(`[mbkbucket] Path not found: ${req.method} ${req.url}`);
+    debugServer("Path not found: %s %s", req.method, req.url);
     return res.status(404).render("Error/dError.handlebars", {
       layout: false,
       code: 404,
@@ -138,8 +138,8 @@ if (process.env.mbkbucket_test === "dev") {
   });
 
   const port = process.env.PORT || 3004;
-  server.listen(port, async () => {
-    console.log(`[mbkbucket] Server running on http://localhost:${port}`);
+  server.listen(port, async() => {
+    debugServer("Server running on http://localhost:%s", port);
   });
 
 }