mbkbucket 4.1.0 → 4.2.0

package/lib/src/core/storage/models.js

@@ -1,120 +1,121 @@
-/**
- * MBKBucket - Normalized Storage Data Models
- * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
- * Licensed under the MIT License.
- */
-
-import { nowIso, getBaseName, getFolderPath, trimLeadingSlashes, trimSlashes } from "#helpers";
-
-export class StorageItem {
-  constructor(props = {}) {
-    const rawPath = String(props.path || props.key || props.Key || props.prefix || props.Prefix || '');
-    this.path = props.type === 'folder'
-      ? (rawPath ? (rawPath.endsWith('/') ? rawPath : `${rawPath}/`) : '')
-      : trimLeadingSlashes(rawPath);
-
-    this.type = props.type || (this.path.endsWith('/') ? 'folder' : 'file');
-    this.name = props.name || (this.type === 'folder' ? trimSlashes(getBaseName(this.path.replace(/\/+$/, ''))) : getBaseName(this.path));
-    this.parentPath = props.parentPath ?? (this.type === 'folder'
-      ? trimSlashes(getFolderPath(this.path.replace(/\/+$/, '')))
-      : trimSlashes(getFolderPath(this.path)));
-
-    this.id = props.id || props.nativeId || this.path;
-    this.nativeId = props.nativeId || props.id || null;
-    this.provider = props.provider || props.storageClass || props.StorageClass || 'generic';
-
-    this.size = this.type === 'folder' ? 0 : Number(props.size ?? props.Size ?? 0);
-    this.mimeType = props.mimeType || props.contentType || props.ContentType || (this.type === 'folder' ? 'application/x-directory' : 'application/octet-stream');
-    this.etag = props.etag || props.ETag || '';
-
-    const modDate = props.lastModified || props.LastModified || props.updatedAt;
-    this.lastModified = modDate instanceof Date ? modDate : new Date(modDate || Date.now());
-
-    if (props.createdAt || props.createdTime) {
-      const createDate = props.createdAt || props.createdTime;
-      this.createdAt = createDate instanceof Date ? createDate : new Date(createDate);
-    }
-
-    this.metadata = Object.freeze({ ...(props.metadata || {}) });
-  }
-
-  get isFolder() {
-    return this.type === 'folder';
-  }
-
-  get isFile() {
-    return this.type === 'file';
-  }
-}
-
-export class StorageFile extends StorageItem {
-  constructor(props = {}) {
-    const key = props.key || props.Key || props.path || '';
-    super({
-      ...props,
-      type: 'file',
-      path: key,
-      size: props.size ?? props.Size ?? 0,
-      mimeType: props.mimeType || props.contentType || props.ContentType,
-      lastModified: props.lastModified || props.LastModified,
-      etag: props.etag || props.ETag,
-      provider: props.storageClass || props.StorageClass || props.provider || 'STANDARD',
-      id: props.id,
-      nativeId: props.id || props.nativeId
-    });
-
-    // Backward-compatible properties for S3 consumers
-    this.Key = this.path;
-    this.Size = this.size;
-    this.LastModified = this.lastModified;
-    this.ETag = this.etag;
-    this.ContentType = this.mimeType;
-    this.StorageClass = this.provider;
-
-    if (props.id) this.id = props.id;
-    if (props.mimeType) this.mimeType = props.mimeType;
-    if (props.webViewLink) this.webViewLink = props.webViewLink;
-    if (props.webContentLink) this.webContentLink = props.webContentLink;
-  }
-}
-
-export class StorageFolder extends StorageItem {
-  constructor(prefixOrProps, id) {
-    const props = typeof prefixOrProps === 'object' && prefixOrProps !== null
-      ? prefixOrProps
-      : { prefix: prefixOrProps, id };
-
-    const rawPrefix = String(props.prefix || props.Prefix || props.path || '');
-    const cleanPrefix = rawPrefix ? (rawPrefix.endsWith('/') ? rawPrefix : `${rawPrefix}/`) : '';
-
-    super({
-      ...props,
-      type: 'folder',
-      path: cleanPrefix,
-      id: props.id || id,
-      nativeId: props.id || id
-    });
-
-    // Backward-compatible property for S3 consumers
-    this.Prefix = this.path;
-    if (this.id) this.id = this.id;
-  }
-}
-
-export class StorageListResult {
-  constructor(props = {}) {
-    this.Contents = props.contents || props.Contents || [];
-    this.CommonPrefixes = props.commonPrefixes || props.CommonPrefixes || [];
-    this.NextContinuationToken = props.nextToken ?? props.NextContinuationToken ?? null;
-    this.nextToken = this.NextContinuationToken;
-    this.IsTruncated = Boolean(props.isTruncated ?? props.IsTruncated ?? Boolean(this.NextContinuationToken));
-    this.hasMore = this.IsTruncated;
-    this.KeyCount = this.Contents.length;
-    this.totalFiles = props.totalFiles ?? this.Contents.length;
-    this.requestedAt = nowIso();
-
-    this.files = this.Contents;
-    this.folders = this.CommonPrefixes;
-    this.items = [...this.CommonPrefixes, ...this.Contents];
-  }
-}
+/**
+ * MBKBucket - Normalized Storage Data Models
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ */
+
+import { nowIso, getFolderPath } from "#helpers";
+import { getBaseName, trimLeadingSlashes, trimSlashes } from "mbkutils";
+
+export class StorageItem {
+  constructor(props = {}) {
+    const rawPath = String(props.path || props.key || props.Key || props.prefix || props.Prefix || '');
+    this.path = props.type === 'folder'
+      ? (rawPath ? (rawPath.endsWith('/') ? rawPath : `${rawPath}/`) : '')
+      : trimLeadingSlashes(rawPath);
+
+    this.type = props.type || (this.path.endsWith('/') ? 'folder' : 'file');
+    this.name = props.name || (this.type === 'folder' ? trimSlashes(getBaseName(this.path.replace(/\/+$/, ''))) : getBaseName(this.path));
+    this.parentPath = props.parentPath ?? (this.type === 'folder'
+      ? trimSlashes(getFolderPath(this.path.replace(/\/+$/, '')))
+      : trimSlashes(getFolderPath(this.path)));
+
+    this.id = props.id || props.nativeId || this.path;
+    this.nativeId = props.nativeId || props.id || null;
+    this.provider = props.provider || props.storageClass || props.StorageClass || 'generic';
+
+    this.size = this.type === 'folder' ? 0 : Number(props.size ?? props.Size ?? 0);
+    this.mimeType = props.mimeType || props.contentType || props.ContentType || (this.type === 'folder' ? 'application/x-directory' : 'application/octet-stream');
+    this.etag = props.etag || props.ETag || '';
+
+    const modDate = props.lastModified || props.LastModified || props.updatedAt;
+    this.lastModified = modDate instanceof Date ? modDate : new Date(modDate || Date.now());
+
+    if (props.createdAt || props.createdTime) {
+      const createDate = props.createdAt || props.createdTime;
+      this.createdAt = createDate instanceof Date ? createDate : new Date(createDate);
+    }
+
+    this.metadata = Object.freeze({ ...(props.metadata || {}) });
+  }
+
+  get isFolder() {
+    return this.type === 'folder';
+  }
+
+  get isFile() {
+    return this.type === 'file';
+  }
+}
+
+export class StorageFile extends StorageItem {
+  constructor(props = {}) {
+    const key = props.key || props.Key || props.path || '';
+    super({
+      ...props,
+      type: 'file',
+      path: key,
+      size: props.size ?? props.Size ?? 0,
+      mimeType: props.mimeType || props.contentType || props.ContentType,
+      lastModified: props.lastModified || props.LastModified,
+      etag: props.etag || props.ETag,
+      provider: props.storageClass || props.StorageClass || props.provider || 'STANDARD',
+      id: props.id,
+      nativeId: props.id || props.nativeId
+    });
+
+    // Backward-compatible properties for S3 consumers
+    this.Key = this.path;
+    this.Size = this.size;
+    this.LastModified = this.lastModified;
+    this.ETag = this.etag;
+    this.ContentType = this.mimeType;
+    this.StorageClass = this.provider;
+
+    if (props.id) this.id = props.id;
+    if (props.mimeType) this.mimeType = props.mimeType;
+    if (props.webViewLink) this.webViewLink = props.webViewLink;
+    if (props.webContentLink) this.webContentLink = props.webContentLink;
+  }
+}
+
+export class StorageFolder extends StorageItem {
+  constructor(prefixOrProps, id) {
+    const props = typeof prefixOrProps === 'object' && prefixOrProps !== null
+      ? prefixOrProps
+      : { prefix: prefixOrProps, id };
+
+    const rawPrefix = String(props.prefix || props.Prefix || props.path || '');
+    const cleanPrefix = rawPrefix ? (rawPrefix.endsWith('/') ? rawPrefix : `${rawPrefix}/`) : '';
+
+    super({
+      ...props,
+      type: 'folder',
+      path: cleanPrefix,
+      id: props.id || id,
+      nativeId: props.id || id
+    });
+
+    // Backward-compatible property for S3 consumers
+    this.Prefix = this.path;
+    if (this.id) this.id = this.id;
+  }
+}
+
+export class StorageListResult {
+  constructor(props = {}) {
+    this.Contents = props.contents || props.Contents || [];
+    this.CommonPrefixes = props.commonPrefixes || props.CommonPrefixes || [];
+    this.NextContinuationToken = props.nextToken ?? props.NextContinuationToken ?? null;
+    this.nextToken = this.NextContinuationToken;
+    this.IsTruncated = Boolean(props.isTruncated ?? props.IsTruncated ?? Boolean(this.NextContinuationToken));
+    this.hasMore = this.IsTruncated;
+    this.KeyCount = this.Contents.length;
+    this.totalFiles = props.totalFiles ?? this.Contents.length;
+    this.requestedAt = nowIso();
+
+    this.files = this.Contents;
+    this.folders = this.CommonPrefixes;
+    this.items = [...this.CommonPrefixes, ...this.Contents];
+  }
+}

package/lib/src/core/storage/path-strategy.js

@@ -1,78 +1,85 @@
-/**
- * MBKBucket - Path & Key Strategy
- * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
- * Licensed under the MIT License.
- */
-
-import { mbkautheVar } from "mbkauthe";
-import { StorageValidationError } from "./errors.js";
-import { trimLeadingSlashes, trimSlashes } from "#helpers";
-
-const escapeRegExp = value => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-let _configuredAppName = null;
-
-export class PathStrategy {
-  static setAppName(name) {
-    _configuredAppName = name ? String(name).trim() : null;
-  }
-
-  static resetAppName() {
-    _configuredAppName = null;
-  }
-
-  static getAppName() {
-    if (_configuredAppName !== null) {
-      return _configuredAppName;
-    }
-    const app = mbkautheVar?.APP_NAME || process.env.MBKAUTHE_APP_NAME || process.env.APP_NAME;
-    return typeof app === 'string' && app.trim() ? app.trim() : '';
-  }
-
-  static isRootModeApp(appName) {
-    return ['portal', 'mbkbucket'].includes(String(appName || '').toLowerCase());
-  }
-
-  static validateSafety(str, isKey = false) {
-    if (isKey && !str) throw new StorageValidationError('Key is required');
-    if (str && (str.includes('../') || str.includes('..\\') || /\.\.[\\/]/.test(str))) {
-      throw new StorageValidationError(`Path traversal detected: invalid ${isKey ? 'key' : 'prefix'}`);
-    }
-    if (str && /[\x00-\x1f\x7f]/.test(str)) {
-      throw new StorageValidationError(`Invalid characters in ${isKey ? 'key' : 'prefix'}`);
-    }
-  }
-
-  static applyKeyPrefix(key = '') {
-    if (Array.isArray(key)) key = key.join('/');
-    this.validateSafety(key, true);
-
-    const app = this.getAppName();
-    const cleaned = trimLeadingSlashes(key);
-    if (this.isRootModeApp(app)) return cleaned;
-    if (!app) throw new StorageValidationError('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
-
-    const appPrefixRegex = new RegExp(`^(?:${escapeRegExp(app)}\/)+`);
-    return cleaned.startsWith(`${app}/`) ? cleaned.replace(appPrefixRegex, `${app}/`) : `${app}/${cleaned}`;
-  }
-
-  static applyPrefix(prefix = '') {
-    if (Array.isArray(prefix)) prefix = prefix.join('/');
-    this.validateSafety(prefix, false);
-
-    const app = this.getAppName();
-    const p = trimLeadingSlashes(prefix);
-    if (this.isRootModeApp(app)) return p;
-    if (!app) throw new StorageValidationError('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
-    if (!p || p === app || p === `${app}/`) return p || app;
-
-    return p.startsWith(`${app}/`)
-      ? p.replace(new RegExp(`^(?:${escapeRegExp(app)}\/)+`), `${app}/`)
-      : `${app}/${p}`;
-  }
-
-  static normalizeFolderPrefix(prefix = '') {
-    const p = this.applyPrefix(trimSlashes(prefix));
-    return p ? `${p}/` : '';
-  }
-}
+/**
+ * MBKBucket - Path & Key Strategy
+ * Copyright (c) 2026 Muhammad Bin Khalid, MBKTech.org and contributors
+ * Licensed under the MIT License.
+ */
+
+import { mbkautheVar } from "mbkauthe";
+import { StorageValidationError } from "./errors.js";
+import { trimLeadingSlashes, trimSlashes } from "mbkutils";
+
+const escapeRegExp = value => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+let _configuredAppName = null;
+
+export class PathStrategy {
+  static setAppName(name) {
+    _configuredAppName = name ? String(name).trim() : null;
+  }
+
+  static resetAppName() {
+    _configuredAppName = null;
+  }
+
+  static getAppName() {
+    if (_configuredAppName !== null) {
+      return _configuredAppName;
+    }
+    let envAppName = null;
+    if (process.env.mbkautheVar) {
+      try {
+        const parsed = typeof process.env.mbkautheVar === 'string' ? JSON.parse(process.env.mbkautheVar) : process.env.mbkautheVar;
+        if (parsed?.APP_NAME) envAppName = parsed.APP_NAME;
+      } catch {}
+    }
+    const app = envAppName || process.env.MBKAUTHE_APP_NAME || process.env.APP_NAME || mbkautheVar?.APP_NAME;
+    return typeof app === 'string' && app.trim() ? app.trim() : '';
+  }
+
+  static isRootModeApp(appName) {
+    return ['portal', 'mbkbucket'].includes(String(appName || '').toLowerCase());
+  }
+
+  static validateSafety(str, isKey = false) {
+    if (isKey && !str) throw new StorageValidationError('Key is required');
+    if (str && (str.includes('../') || str.includes('..\\') || /\.\.[\\/]/.test(str))) {
+      throw new StorageValidationError(`Path traversal detected: invalid ${isKey ? 'key' : 'prefix'}`);
+    }
+    if (str && /[\x00-\x1f\x7f]/.test(str)) {
+      throw new StorageValidationError(`Invalid characters in ${isKey ? 'key' : 'prefix'}`);
+    }
+  }
+
+  static applyKeyPrefix(key = '') {
+    if (Array.isArray(key)) key = key.join('/');
+    this.validateSafety(key, true);
+
+    const app = this.getAppName();
+    const cleaned = trimLeadingSlashes(key);
+    if (this.isRootModeApp(app)) return cleaned;
+    if (!app) throw new StorageValidationError('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
+
+    const appPrefixRegex = new RegExp(`^(?:${escapeRegExp(app)}\/)+`);
+    return cleaned.startsWith(`${app}/`) ? cleaned.replace(appPrefixRegex, `${app}/`) : `${app}/${cleaned}`;
+  }
+
+  static applyPrefix(prefix = '') {
+    if (Array.isArray(prefix)) prefix = prefix.join('/');
+    this.validateSafety(prefix, false);
+
+    const app = this.getAppName();
+    const p = trimLeadingSlashes(prefix);
+    if (this.isRootModeApp(app)) return p;
+    if (!app) throw new StorageValidationError('APP_NAME is not configured; set mbkautheVar.APP_NAME or MBKAUTHE_APP_NAME');
+    if (!p || p === app || p === `${app}/`) return p || app;
+
+    return p.startsWith(`${app}/`)
+      ? p.replace(new RegExp(`^(?:${escapeRegExp(app)}\/)+`), `${app}/`)
+      : `${app}/${p}`;
+  }
+
+  static normalizeFolderPrefix(prefix = '') {
+    const p = this.applyPrefix(trimSlashes(prefix));
+    return p ? `${p}/` : '';
+  }
+}