mbkbucket 3.3.2 → 3.4.0

package/README.md

@@ -37,14 +37,7 @@ npm install mbkbucket
 ### As a Library
 
 ```js
-import {
-  uploadFile,
-  downloadFile,
-  listfiles,
-  deleteFile,
-  deleteFolder,
-  getFileMetadata,
-  generateSignedUrl,
+import { uploadFile, downloadFile, listfiles, deleteFile, deleteFolder, getFileMetadata, generateSignedUrl,
   bucket,          // Express router
   packageJson       // Package metadata
 } from 'mbkbucket';
@@ -82,7 +75,7 @@ mbkbucket.listen(3004, () => {
 ```
 
 The Express app includes:
-- **`/mbkbucket`** — Admin dashboard (SuperAdmin only)
+- **`/mbkbucket`** — Admin dashboard (superadmin only)
 - **`/mbkbucket/api/*`** — REST API for file operations
 - **`/mbkbucket/p_view/:key(*)`** — Public file view
 - **`/mbkbucket/info`** — Health & config info
@@ -225,23 +218,23 @@ All functions are exported from the package root. Full TypeScript declarations i
 
 | Route | Auth | Description |
 |---|---|---|
-| `GET /mbkbucket` | SuperAdmin | Admin dashboard |
+| `GET /mbkbucket` | superadmin | Admin dashboard |
 | `GET /mbkbucket/info` | Any | Health check & config info |
 | `GET /mbkbucket/p_view/:key(*)` | Public | Public file viewer |
-| `POST /mbkbucket/api/list` | SuperAdmin | List files (JSON) |
-| `POST /mbkbucket/api/upload` | SuperAdmin | Upload file(s) |
-| `POST /mbkbucket/api/delete` | SuperAdmin | Delete file(s) |
-| `POST /mbkbucket/api/delete-folder` | SuperAdmin | Delete folder |
-| `POST /mbkbucket/api/create-folder` | SuperAdmin | Create folder marker |
-| `POST /mbkbucket/api/rename` | SuperAdmin | Rename/move a file |
-| `GET /mbkbucket/api/download/:key(*)` | SuperAdmin | Download a file |
-| `GET /mbkbucket/api/metadata/:key(*)` | SuperAdmin | Get file metadata |
-| `POST /mbkbucket/api/multipart/init` | SuperAdmin | Init multipart upload |
-| `POST /mbkbucket/api/multipart/part` | SuperAdmin | Upload multipart chunk |
-| `POST /mbkbucket/api/multipart/complete` | SuperAdmin | Complete multipart |
-| `POST /mbkbucket/api/multipart/abort` | SuperAdmin | Abort multipart |
-| `GET /mbkbucket/api/multipart/list` | SuperAdmin | List incomplete uploads |
-| `POST /mbkbucket/api/multipart/cleanup` | SuperAdmin | Clean up stale uploads |
+| `POST /mbkbucket/api/list` | superadmin | List files (JSON) |
+| `POST /mbkbucket/api/upload` | superadmin | Upload file(s) |
+| `POST /mbkbucket/api/delete` | superadmin | Delete file(s) |
+| `POST /mbkbucket/api/delete-folder` | superadmin | Delete folder |
+| `POST /mbkbucket/api/create-folder` | superadmin | Create folder marker |
+| `POST /mbkbucket/api/rename` | superadmin | Rename/move a file |
+| `GET /mbkbucket/api/download/:key(*)` | superadmin | Download a file |
+| `GET /mbkbucket/api/metadata/:key(*)` | superadmin | Get file metadata |
+| `POST /mbkbucket/api/multipart/init` | superadmin | Init multipart upload |
+| `POST /mbkbucket/api/multipart/part` | superadmin | Upload multipart chunk |
+| `POST /mbkbucket/api/multipart/complete` | superadmin | Complete multipart |
+| `POST /mbkbucket/api/multipart/abort` | superadmin | Abort multipart |
+| `GET /mbkbucket/api/multipart/list` | superadmin | List incomplete uploads |
+| `POST /mbkbucket/api/multipart/cleanup` | superadmin | Clean up stale uploads |
 
 ### Views
 

package/lib/cli.js

@@ -133,39 +133,39 @@ function promptLine() {
 
 async function cmdLogin() {
   const storedCfg = readConfig();
-  let serverUrl = findFlag('server') || storedCfg.serverUrl;
+  let server_url = findFlag('server') || storedCfg.server_url;
 
-  if (!serverUrl || typeof serverUrl !== 'string') {
-    console.error('❌ --server <url> is required for login.\n   Example: mbkbucket login --server https://myapp.example.com\n\n💡 Tip: Set it once with:\n   mbkbucket config set serverUrl https://your-server.com\n   Then just run: mbkbucket login');
+  if (!server_url || typeof server_url !== 'string') {
+    console.error('❌ --server <url> is required for login.\n   Example: mbkbucket login --server https://myapp.example.com\n\n💡 Tip: Set it once with:\n   mbkbucket config set server_url https://your-server.com\n   Then just run: mbkbucket login');
     process.exit(1);
   }
 
-  const profileKey = findFlag('profile-key') || storedCfg.profileKey;
-  updateConfig({ serverUrl });
+  const profile_key = findFlag('profile-key') || storedCfg.profile_key;
+  updateConfig({ server_url });
 
   try {
     const result = await deviceFlowLogin({
-      serverUrl,
-      profileKey: typeof profileKey === 'string' ? profileKey : undefined,
+      server_url,
+      profile_key: typeof profile_key === 'string' ? profile_key : undefined,
     });
 
     updateConfig({
       token: result.token,
-      tokenPrefix: result.tokenPrefix,
+      token_prefix: result.token_prefix,
       username: result.username,
-      serverUrl,
+      server_url,
       profile: result.profile || null,
-      loggedInAt: nowIso(),
+      logged_in_at: nowIso(),
     });
 
     console.log('\n✅ Credentials saved. You are now logged in.\n   Run "mbkbucket whoami" to verify.');
   } catch (err) {
     const msg = err.message || '';
     console.error(`❌ Login failed: ${msg}`);
-    if (msg.includes('profileKey') || msg.includes('profileId')) {
+    if (msg.includes('profile_key') || msg.includes('profile_id')) {
       console.error('\n💡 An API token profile is required. Create one in mbkauthe admin panel and pass --profile-key.');
     } else if (msg.includes('fetch') || msg.includes('ECONNREFUSED') || msg.includes('ENOTFOUND')) {
-      console.error(`\n💡 Could not reach server "${serverUrl}". Verify it is running and CLI_AUTH_ENABLED=true.`);
+      console.error(`\n💡 Could not reach server "${server_url}". Verify it is running and CLI_AUTH_ENABLED=true.`);
     }
     process.exit(1);
   }
@@ -182,10 +182,10 @@ function cmdWhoami() {
   if (!isLoggedIn()) return console.log('ℹ️  Not logged in. Run "mbkbucket login --server <url>" to authenticate.');
   const cfg = readConfig();
   console.log(`✅ Logged in as: ${cfg.username}`);
-  console.log(`   Server:      ${cfg.serverUrl}`);
-  console.log(`   Token:       ${cfg.tokenPrefix}...`);
+  console.log(`   Server:      ${cfg.server_url}`);
+  console.log(`   Token:       ${cfg.token_prefix}...`);
   if (cfg.profile) console.log(`   Profile:     ${cfg.profile.name} (scope: ${cfg.profile.scope || 'full'})`);
-  console.log(`   Since:       ${formatDate(cfg.loggedInAt)}`);
+  console.log(`   Since:       ${formatDate(cfg.logged_in_at)}`);
 }
 
 async function cmdList() {
@@ -462,14 +462,14 @@ async function cmdSignedUrl() {
 // ---------------------------------------------------------------------------
 const DEMO_CONFIG = {
   token: 'mbk_demo_token_replace_with_real_one_from_login',
-  tokenPrefix: 'mbk_demo',
+  token_prefix: 'mbk_demo',
   username: 'demo-user',
-  serverUrl: 'https://your-app.example.com',
-  profile: { name: 'Default CLI Profile', scope: 'read-write', allowedApps: ['mbkbucket'] },
-  loggedInAt: nowIso(),
+  server_url: 'https://your-app.example.com',
+  profile: { name: 'Default CLI Profile', scope: 'read-write', allowed_apps: ['mbkbucket'] },
+  logged_in_at: nowIso(),
 };
 
-const VALID_CONFIG_KEYS = ['token', 'tokenPrefix', 'username', 'serverUrl', 'profile', 'profileKey', 'loggedInAt'];
+const VALID_CONFIG_KEYS = ['token', 'token_prefix', 'username', 'server_url', 'profile', 'profile_key', 'logged_in_at'];
 
 async function cmdConfig() {
   const [sub, key, value] = cmdArgs;

package/lib/src/cli/auth-helper.js

@@ -52,8 +52,8 @@ export function updateConfig(partial) {
 }
 
 export function isLoggedIn() {
-  const { token, serverUrl } = readConfig();
-  return Boolean(token && serverUrl);
+  const { token, server_url } = readConfig();
+  return Boolean(token && server_url);
 }
 
 export function getStoredToken() {
@@ -61,11 +61,11 @@ export function getStoredToken() {
 }
 
 export function getStoredServerUrl() {
-  return readConfig().serverUrl || null;
+  return readConfig().server_url || null;
 }
 
-export async function deviceFlowLogin({ serverUrl, profileKey }) {
-  const baseUrl = String(serverUrl).replace(/\/+$/, '');
+export async function deviceFlowLogin({ server_url, profile_key }) {
+  const baseUrl = String(server_url).replace(/\/+$/, '');
   console.log(`🔑 Requesting device login from ${baseUrl} ...`);
 
   let deviceResp;
@@ -74,8 +74,8 @@ export async function deviceFlowLogin({ serverUrl, profileKey }) {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
-        clientName: `mbkbucket-cli-${os.hostname()}`,
-        ...(profileKey && { profileKey }),
+        client_name: `mbkbucket-cli-${os.hostname()}`,
+        ...(profile_key && { profile_key }),
       }),
     });
     deviceResp = await res.json();
@@ -87,19 +87,24 @@ export async function deviceFlowLogin({ serverUrl, profileKey }) {
     throw err;
   }
 
-  const { verificationUrl, userCode, deviceCode, expiresIn, interval, profile } = deviceResp;
+  const verification_url = deviceResp.verification_url;
+  const user_code = deviceResp.user_code;
+  const device_code = deviceResp.device_code;
+  const expires_in = deviceResp.expires_in;
+  const interval = deviceResp.interval;
+  const profile = deviceResp.profile;
 
   console.log('\n┌─────────────────────────────────────────────────────────┐');
   console.log('│                                                         │');
   console.log('│   🌐 Open this URL in your browser to approve:           │');
-  console.log(`│   ${verificationUrl.padEnd(53)}│`);
+  console.log(`│   ${(verification_url || '').padEnd(53)}│`);
   console.log('│                                                         │');
-  console.log(`│   🔢 Or enter this code:  ${userCode.padEnd(30)}│`);
+  console.log(`│   🔢 Or enter this code:  ${(user_code || '').padEnd(30)}│`);
   console.log('│                                                         │');
   console.log('└─────────────────────────────────────────────────────────┘\n');
 
   if (profile) console.log(`   Profile: ${profile.name} (scope: ${profile.scope || 'full'})`);
-  console.log(`   Waiting for approval (expires in ${Math.floor(expiresIn / 60)} minutes)...\n`);
+  console.log(`   Waiting for approval (expires in ${Math.floor((expires_in || 900) / 60)} minutes)...\n`);
 
   const pollInterval = (interval || 5) * 1000;
   const deadline = Date.now() + MAX_POLL_TIME_MS;
@@ -113,17 +118,18 @@ export async function deviceFlowLogin({ serverUrl, profileKey }) {
       const pollRes = await fetch(`${baseUrl}/api/cli/device/token`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ deviceCode }),
+        body: JSON.stringify({ device_code }),
       });
 
       const pollBody = await pollRes.json();
 
       if (pollBody.status === 'approved' && pollBody.success) {
+        const token_prefix = pollBody.token_prefix || '';
         console.log(`✅ Login approved! Welcome, ${pollBody.username}.`);
-        console.log(`   Token prefix: ${pollBody.tokenPrefix}...`);
+        console.log(`   Token prefix: ${token_prefix}...`);
         return {
           token: pollBody.token,
-          tokenPrefix: pollBody.tokenPrefix,
+          token_prefix: token_prefix,
           username: pollBody.username,
           profile: profile || null,
         };

package/lib/src/config/index.js

@@ -102,7 +102,4 @@ export function validateAllConfiguration() {
 
 export const mbkbucketVar = validateConfiguration();
 
-export {
-  packageJson,
-  appVersion
-};
+export { packageJson, appVersion };

package/lib/src/middleware/error-handler.js

@@ -1,11 +1,26 @@
 import { createLogger } from "#logger";
+import { isJsonRequest, sendError, sanitizeErrorDetails } from "mbkauthe";
 
 const debugServer = createLogger('server');
 
 const BASE_ERROR_DATA = { layout: false, pagename: "Home", page: "/" };
 
-export function notFoundHandler(req, res) {
+export function notFoundHandler(req, res, next) {
+  const url = req.originalUrl || req.url || '';
+  if (!url.startsWith('/mbkbucket') && typeof next === 'function') {
+    return next();
+  }
+
   debugServer("Path not found: %s %s", req.method, req.url);
+
+  if (isJsonRequest(req)) {
+    return sendError(res, "The requested API route was not found.", {
+      statusCode: 404,
+      code: "ROUTE_NOT_FOUND",
+      req,
+    });
+  }
+
   return res.status(404).render("Error/dError.handlebars", {
     ...BASE_ERROR_DATA,
     code: 404,
@@ -14,13 +29,26 @@ export function notFoundHandler(req, res) {
   });
 }
 
-export function globalErrorHandler(err, _req, res, _next) {
-  console.error(`[mbkbucket] ${err.stack}`);
-  return res.status(500).render("Error/dError.handlebars", {
+export function globalErrorHandler(err, req, res, _next) {
+  console.error(`[mbkbucket] ${err.stack || err}`);
+
+  const statusCode = Number(err.status || err.statusCode || 500);
+
+  if (isJsonRequest(req)) {
+    return sendError(res, err, {
+      statusCode,
+      req,
+      details: process.env.NODE_ENV !== 'production' ? err.stack : undefined,
+    });
+  }
+
+  const sanitizedDetails = err.message ? sanitizeErrorDetails(err.message) : undefined;
+
+  return res.status(statusCode).render("Error/dError.handlebars", {
     ...BASE_ERROR_DATA,
-    code: 500,
-    error: "Internal app Error",
-    message: "An unexpected error occurred on the app.",
-    details: err.message,
+    code: statusCode,
+    error: statusCode >= 500 ? "Internal app Error" : (err.name || "Client Error"),
+    message: err.message || "An unexpected error occurred on the app.",
+    ...(sanitizedDetails ? { details: sanitizedDetails } : {}),
   });
 }

package/lib/src/routes/api.routes.js

@@ -21,7 +21,7 @@ const uploadChunkMiddleware = (req, res, next) => {
   });
 };
 
-const adminAuth = sessRole('SuperAdmin');
+const adminAuth = sessRole('superadmin');
 
 router.use(requireBucketApi);
 

package/lib/src/routes/index.js

@@ -8,7 +8,7 @@ import apiRoutes from "./api.routes.js";
 
 const router = express.Router();
 
-router.get('/mbkbucket', sessRole('SuperAdmin'), renderBucketDashboard);
+router.get('/mbkbucket', sessRole('superadmin'), renderBucketDashboard);
 router.use('/mbkbucket', bucketResolver, infoRoutes, viewRoutes, apiRoutes);
 
 export default router;

package/lib/src/routes/view.routes.js

@@ -7,7 +7,7 @@ import { pviewSecurity } from "../middleware/security.js";
 import { viewFile, playerPage, publicView } from "../controllers/view.controller.js";
 
 const router = express.Router();
-const adminAuth = sessRole('SuperAdmin');
+const adminAuth = sessRole('superadmin');
 
 router.use(requireBucketView);
 router.get('/player/*key', adminAuth, playerPage);

package/lib/src/utils/errors.js

@@ -36,7 +36,16 @@ export function classifyViewError(error, fallbackMessage = 'Request failed') {
 
 export function sendApiError(res, error, fallbackMessage = 'Request failed') {
   const { status, code, message } = classifyApiError(error, fallbackMessage);
-  return res.status(status).json({ success: false, code, error: message });
+  return res.status(status).json({
+    success: false,
+    code,
+    error: {
+      code,
+      message,
+    },
+    message,
+    timestamp: new Date().toISOString(),
+  });
 }
 
 export function sendViewError(res, error, fallbackMessage = 'Request failed') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbkbucket",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "description": "Flexible S3/R2 bucket management — library, Express router, and CLI for mbktech.org applications. Provides upload, download, listing, multipart utilities, signed URLs, and a command-line interface with built-in configuration validation and health checks",
   "author": "Muhammad Bin Khalid",
   "homepage": "https://github.com/MIbnEKhalid/mbkbucket#readme",
@@ -13,7 +13,7 @@
   },
   "scripts": {
     "dev": "cross-env NODE_ENV=dev nodemon index.js",
-    "test": "node --test"
+    "test": "vitest run"
   },
   "imports": {
     "#helpers": "./lib/src/utils/helpers.js",
@@ -28,13 +28,16 @@
     "express": "^5.1.0",
     "express-handlebars": "^8.0.3",
     "express-rate-limit": "^7.5.0",
-    "mbkauthe": "^5.3.6",
+    "mbkauthe": "^5.7.0",
     "multer": "^2.0.2",
     "pg": "^8.16.3"
   },
   "devDependencies": {
+    "@types/supertest": "^7.2.1",
     "cross-env": "^7.0.3",
-    "nodemon": "^3.1.14"
+    "nodemon": "^3.1.14",
+    "supertest": "^7.2.2",
+    "vitest": "^4.1.11"
   },
   "overrides": {
     "csurf": {
@@ -77,4 +80,4 @@
     "file-upload",
     "file-download"
   ]
-}
+}