mbkbucket 3.3.2 → 3.5.0

package/LICENSE

@@ -1,165 +1,21 @@
-                   GNU LESSER GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-
-  This version of the GNU Lesser General Public License incorporates
-the terms and conditions of version 3 of the GNU General Public
-License, supplemented by the additional permissions listed below.
-
-  0. Additional Definitions.
-
-  As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the GNU
-General Public License.
-
-  "The Library" refers to a covered work governed by this License,
-other than an Application or a Combined Work as defined below.
-
-  An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-  A "Combined Work" is a work produced by combining or linking an
-Application with the Library.  The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-  The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-  The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-  1. Exception to Section 3 of the GNU GPL.
-
-  You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-  2. Conveying Modified Versions.
-
-  If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
-   a) under this License, provided that you make a good faith effort to
-   ensure that, in the event an Application does not supply the
-   function or data, the facility still operates, and performs
-   whatever part of its purpose remains meaningful, or
-
-   b) under the GNU GPL, with none of the additional permissions of
-   this License applicable to that copy.
-
-  3. Object Code Incorporating Material from Library Header Files.
-
-  The object code form of an Application may incorporate material from
-a header file that is part of the Library.  You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
-   a) Give prominent notice with each copy of the object code that the
-   Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the object code with a copy of the GNU GPL and this license
-   document.
-
-  4. Combined Works.
-
-  You may convey a Combined Work under terms of your choice that,
-taken together, effectively do not restrict modification of the
-portions of the Library contained in the Combined Work and reverse
-engineering for debugging such modifications, if you also do each of
-the following:
-
-   a) Give prominent notice with each copy of the Combined Work that
-   the Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the Combined Work with a copy of the GNU GPL and this license
-   document.
-
-   c) For a Combined Work that displays copyright notices during
-   execution, include the copyright notice for the Library among
-   these notices, as well as a reference directing the user to the
-   copies of the GNU GPL and this license document.
-
-   d) Do one of the following:
-
-       0) Convey the Minimal Corresponding Source under the terms of this
-       License, and the Corresponding Application Code in a form
-       suitable for, and under terms that permit, the user to
-       recombine or relink the Application with a modified version of
-       the Linked Version to produce a modified Combined Work, in the
-       manner specified by section 6 of the GNU GPL for conveying
-       Corresponding Source.
-
-       1) Use a suitable shared library mechanism for linking with the
-       Library.  A suitable mechanism is one that (a) uses at run time
-       a copy of the Library already present on the user's computer
-       system, and (b) will operate properly with a modified version
-       of the Library that is interface-compatible with the Linked
-       Version.
-
-   e) Provide Installation Information, but only if you would otherwise
-   be required to provide such information under section 6 of the
-   GNU GPL, and only to the extent that such information is
-   necessary to install and execute a modified version of the
-   Combined Work produced by recombining or relinking the
-   Application with a modified version of the Linked Version. (If
-   you use option 4d0, the Installation Information must accompany
-   the Minimal Corresponding Source and Corresponding Application
-   Code. If you use option 4d1, you must provide the Installation
-   Information in the manner specified by section 6 of the GNU GPL
-   for conveying Corresponding Source.)
-
-  5. Combined Libraries.
-
-  You may place library facilities that are a work based on the
-Library side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
-   a) Accompany the combined library with a copy of the same work based
-   on the Library, uncombined with any other library facilities,
-   conveyed under the terms of this License.
-
-   b) Give prominent notice with the combined library that part of it
-   is a work based on the Library, and explaining where to find the
-   accompanying uncombined form of the same work.
-
-  6. Revised Versions of the GNU Lesser General Public License.
-
-  The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-  Each version is given a distinguishing version number. If the
-Library as you received it specifies that a certain numbered version
-of the GNU Lesser General Public License "or any later version"
-applies to it, you have the option of following the terms and
-conditions either of that published version or of any later version
-published by the Free Software Foundation. If the Library as you
-received it does not specify a version number of the GNU Lesser
-General Public License, you may choose any version of the GNU Lesser
-General Public License ever published by the Free Software Foundation.
-
-  If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.
+MIT License
+
+Copyright (c) 2026 Muhammad Bin Khalid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,7 +4,7 @@
 
 [![Version](https://img.shields.io/npm/v/mbkbucket.svg)](https://www.npmjs.com/package/mbkbucket)
 [![Downloads](https://img.shields.io/npm/dm/mbkbucket.svg)](https://www.npmjs.com/package/mbkbucket)
-[![License](https://img.shields.io/badge/License-LGPL--3.0-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen.svg)](https://nodejs.org/)
 [![Publish Status](https://github.com/MIbnEKhalid/mbkbucket/actions/workflows/publish.yml/badge.svg)](https://github.com/MIbnEKhalid/mbkbucket/actions/workflows/publish.yml)
 
@@ -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
 
@@ -347,4 +340,12 @@ Part of [MBK Tech](https://mbktech.org/)
 
 ## License
 
-Licensed under the LGPL-3.0-only License. See [LICENSE](LICENSE) for details.
+Licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+
+<!--
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+-->

package/index.js

@@ -1,3 +1,10 @@
+/**
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+ */
+
 import dotenv from "dotenv";
 import { createApp } from "./lib/src/app.js";
 import { checkVersion } from "./lib/src/config/index.js";

package/lib/cli.js

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 
+/**
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+ */
+
 /**
  * mbkbucket CLI — Manage S3/R2 buckets from the command line.
  */
@@ -133,39 +140,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 +189,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 +469,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/public/bucketadmin.js

@@ -1,3 +1,10 @@
+/**
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+ */
+
 /**
  * MBKBucket File Manager - UI & Client Logic
  */

package/lib/public/mbkbucket-helper-demo.html

@@ -1,3 +1,10 @@
+<!--
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+-->
+ 
 <!DOCTYPE html>
 <html lang="en">
 <head>

package/lib/public/mbkbucket-helper.js

@@ -1,3 +1,10 @@
+/**
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+ */
+
 /**
  * mbkbucket-helper.js  v1.2.0
  * ─────────────────────────────────────────────────────────────────────────────

package/lib/src/app.js

@@ -1,3 +1,10 @@
+/**
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+ */
+
 import express from "express";
 import path from "path";
 import fs from "fs";

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

@@ -1,3 +1,10 @@
+/**
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+ */
+
 import { createRequire } from "module";
 import dotenv from "dotenv";
 import { parseAndValidateMbkbucketVar, parseAndValidateBucketConnection } from "./validation.js";
@@ -102,7 +109,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

@@ -1,3 +1,10 @@
+/**
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+ */
+
 import express from "express";
 import { sessRole } from "mbkauthe";
 import { bucketResolver } from "../middleware/bucket-resolver.js";
@@ -8,7 +15,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,10 +1,10 @@
 {
   "name": "mbkbucket",
-  "version": "3.3.2",
+  "version": "3.5.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",
-  "license": "LGPL-3.0-only",
+  "license": "MIT",
   "main": "index.js",
   "type": "module",
   "types": "index.d.ts",
@@ -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"
   ]
-}
+}

package/views/bucket.handlebars

@@ -1,3 +1,10 @@
+<!--
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+-->
+
 <!DOCTYPE html>
 <html lang="en">
 

package/views/mbkbucket_info.handlebars

@@ -1,3 +1,10 @@
+<!--
+ * MBKBucket
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ * Source: https://github.com/MIbnEKhalid/mbkbucket
+-->
+
 <!DOCTYPE html>
 <html lang="en">