digitaltwin-core 0.14.3 → 1.0.1

package/dist/loader/component_loader.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Component auto-discovery and loading utilities
+ *
+ * Provides functions to automatically discover and load Digital Twin components
+ * from a directory based on file naming conventions.
+ */
+import type { LoadedComponents } from '../engine/component_types.js';
+/**
+ * Options for component auto-discovery
+ */
+export interface LoadComponentsOptions {
+    /**
+     * File patterns to match by suffix.
+     * Keys are component types, values are file suffixes (without extension).
+     * @default Standard naming conventions
+     */
+    patterns?: {
+        collectors?: string;
+        harvesters?: string;
+        handlers?: string;
+        assetsManagers?: string;
+        customTableManagers?: string;
+    };
+    /**
+     * File extensions to scan for.
+     * @default ['.js', '.mjs']
+     */
+    extensions?: string[];
+    /**
+     * Whether to scan subdirectories recursively.
+     * @default true
+     */
+    recursive?: boolean;
+    /**
+     * Patterns to exclude (glob-like patterns applied to file names).
+     * @default ['*.spec.*', '*.test.*', 'index.*']
+     */
+    exclude?: string[];
+    /**
+     * Enable verbose logging during discovery.
+     * @default false
+     */
+    verbose?: boolean;
+}
+/**
+ * Result of component loading operation
+ */
+export interface LoadComponentsResult extends LoadedComponents {
+    /** Files that were scanned */
+    scannedFiles: string[];
+    /** Errors encountered during loading */
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+    /** Summary statistics */
+    summary: {
+        total: number;
+        collectors: number;
+        harvesters: number;
+        handlers: number;
+        assetsManagers: number;
+        customTableManagers: number;
+        errors: number;
+    };
+}
+/**
+ * Auto-discovers and loads Digital Twin components from a directory.
+ *
+ * This function scans the specified directory for component files following
+ * the naming conventions (*_collector.js, *_harvester.js, etc.), dynamically
+ * imports them, and instantiates any component classes found.
+ *
+ * ## Naming Conventions
+ *
+ * Component files should follow these naming patterns:
+ * - Collectors: `*_collector.js` (e.g., `weather_collector.js`)
+ * - Harvesters: `*_harvester.js` (e.g., `traffic_harvester.js`)
+ * - Handlers: `*_handler.js` (e.g., `api_handler.js`)
+ * - Assets Managers: `*_assets_manager.js` (e.g., `gltf_assets_manager.js`)
+ * - Custom Table Managers: `*_custom_table.js` (e.g., `wms_custom_table.js`)
+ *
+ * ## Component Export Requirements
+ *
+ * Components should be exported as default export or named export matching the class name:
+ * ```typescript
+ * // Default export (preferred)
+ * export default class WeatherCollector extends Collector { ... }
+ *
+ * // Named export matching file name
+ * export class WeatherCollector extends Collector { ... }
+ * ```
+ *
+ * @param directory - Directory path to scan for components (absolute or relative to cwd)
+ * @param options - Configuration options for discovery
+ * @returns Promise resolving to loaded components and metadata
+ *
+ * @example
+ * ```typescript
+ * import { loadComponents, DigitalTwinEngine } from 'digitaltwin-core'
+ *
+ * // Basic usage - scan compiled components
+ * const result = await loadComponents('./dist/components')
+ *
+ * console.log(`Loaded ${result.summary.total} components`)
+ *
+ * const engine = new DigitalTwinEngine({ storage, database })
+ * engine.registerComponents(result)
+ * await engine.start()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Advanced usage with options
+ * const result = await loadComponents('./dist/components', {
+ *   recursive: true,
+ *   verbose: true,
+ *   extensions: ['.js'],
+ *   exclude: ['*.test.*', 'deprecated_*']
+ * })
+ *
+ * if (result.errors.length > 0) {
+ *   console.warn('Some components failed to load:', result.errors)
+ * }
+ * ```
+ */
+export declare function loadComponents(directory: string, options?: LoadComponentsOptions): Promise<LoadComponentsResult>;
+//# sourceMappingURL=component_loader.d.ts.map

package/dist/loader/component_loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component_loader.d.ts","sourceRoot":"","sources":["../../src/loader/component_loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,8BAA8B,CAAA;AASlF;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,EAAE;QACP,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAC/B,CAAA;IAED;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC1D,8BAA8B;IAC9B,YAAY,EAAE,MAAM,EAAE,CAAA;IAEtB,wCAAwC;IACxC,MAAM,EAAE,KAAK,CAAC;QACV,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,EAAE,MAAM,CAAA;KAChB,CAAC,CAAA;IAEF,yBAAyB;IACzB,OAAO,EAAE;QACL,KAAK,EAAE,MAAM,CAAA;QACb,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,EAAE,MAAM,CAAA;QAClB,QAAQ,EAAE,MAAM,CAAA;QAChB,cAAc,EAAE,MAAM,CAAA;QACtB,mBAAmB,EAAE,MAAM,CAAA;QAC3B,MAAM,EAAE,MAAM,CAAA;KACjB,CAAA;CACJ;AA6JD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAsB,cAAc,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,qBAA0B,GACpC,OAAO,CAAC,oBAAoB,CAAC,CAoJ/B"}

package/dist/loader/component_loader.js

@@ -0,0 +1,330 @@
+/**
+ * @fileoverview Component auto-discovery and loading utilities
+ *
+ * Provides functions to automatically discover and load Digital Twin components
+ * from a directory based on file naming conventions.
+ */
+import { pathToFileURL } from 'node:url';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isCollector, isHarvester, isHandler, isAssetsManager, isCustomTableManager } from '../engine/component_types.js';
+/**
+ * Default file patterns for component detection based on naming conventions
+ */
+const DEFAULT_PATTERNS = {
+    collectors: '_collector',
+    harvesters: '_harvester',
+    handlers: '_handler',
+    assetsManagers: '_assets_manager',
+    customTableManagers: '_custom_table'
+};
+const DEFAULT_EXTENSIONS = ['.js', '.mjs'];
+const DEFAULT_EXCLUDE = ['*.spec.*', '*.test.*', 'index.*', '*.d.ts'];
+/**
+ * Check if a filename matches an exclusion pattern.
+ */
+function matchesExcludePattern(filename, patterns) {
+    for (const pattern of patterns) {
+        // Convert glob pattern to regex
+        const regexPattern = pattern.replace(/\./g, '\\.').replace(/\*/g, '.*');
+        const regex = new RegExp(`^${regexPattern}$`, 'i');
+        if (regex.test(filename)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Determine component type from filename based on patterns.
+ */
+function getComponentTypeFromFilename(filename, patterns) {
+    const baseName = path.basename(filename);
+    // Remove extension for matching
+    const nameWithoutExt = baseName.replace(/\.[^.]+$/, '');
+    if (nameWithoutExt.endsWith(patterns.collectors))
+        return 'collectors';
+    if (nameWithoutExt.endsWith(patterns.harvesters))
+        return 'harvesters';
+    if (nameWithoutExt.endsWith(patterns.handlers))
+        return 'handlers';
+    if (nameWithoutExt.endsWith(patterns.assetsManagers))
+        return 'assetsManagers';
+    if (nameWithoutExt.endsWith(patterns.customTableManagers))
+        return 'customTableManagers';
+    // Also check for *_manager pattern for tileset/map managers
+    if (nameWithoutExt.endsWith('_manager') ||
+        nameWithoutExt.endsWith('_tileset_manager') ||
+        nameWithoutExt.endsWith('_map_manager')) {
+        return 'assetsManagers';
+    }
+    return null;
+}
+/**
+ * Check if a value is a class constructor.
+ */
+function isClassConstructor(value) {
+    return typeof value === 'function' && value.prototype && value.prototype.constructor === value;
+}
+/**
+ * Check if an instance is a valid Digital Twin component.
+ */
+function isValidComponent(instance) {
+    if (!instance || typeof instance !== 'object')
+        return false;
+    if (typeof instance.getConfiguration !== 'function')
+        return false;
+    return (isCollector(instance) ||
+        isHarvester(instance) ||
+        isHandler(instance) ||
+        isAssetsManager(instance) ||
+        isCustomTableManager(instance));
+}
+/**
+ * Recursively scan a directory for component files.
+ */
+async function scanDirectory(dir, options) {
+    const results = [];
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            // Skip hidden files/directories
+            if (entry.name.startsWith('.') || entry.name.startsWith('_')) {
+                continue;
+            }
+            if (entry.isDirectory() && options.recursive) {
+                const subResults = await scanDirectory(fullPath, options);
+                results.push(...subResults);
+            }
+            else if (entry.isFile()) {
+                // Check extension
+                const ext = path.extname(entry.name);
+                if (!options.extensions.includes(ext)) {
+                    continue;
+                }
+                // Check exclusions
+                if (matchesExcludePattern(entry.name, options.exclude)) {
+                    continue;
+                }
+                // Determine component type
+                const componentType = getComponentTypeFromFilename(entry.name, options.patterns);
+                if (componentType) {
+                    results.push({ path: fullPath, type: componentType });
+                }
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or can't be read - return empty array
+    }
+    return results;
+}
+/**
+ * Convert a snake_case or kebab-case string to PascalCase.
+ */
+function toPascalCase(str) {
+    return str
+        .split(/[-_]/)
+        .map(part => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join('');
+}
+/**
+ * Auto-discovers and loads Digital Twin components from a directory.
+ *
+ * This function scans the specified directory for component files following
+ * the naming conventions (*_collector.js, *_harvester.js, etc.), dynamically
+ * imports them, and instantiates any component classes found.
+ *
+ * ## Naming Conventions
+ *
+ * Component files should follow these naming patterns:
+ * - Collectors: `*_collector.js` (e.g., `weather_collector.js`)
+ * - Harvesters: `*_harvester.js` (e.g., `traffic_harvester.js`)
+ * - Handlers: `*_handler.js` (e.g., `api_handler.js`)
+ * - Assets Managers: `*_assets_manager.js` (e.g., `gltf_assets_manager.js`)
+ * - Custom Table Managers: `*_custom_table.js` (e.g., `wms_custom_table.js`)
+ *
+ * ## Component Export Requirements
+ *
+ * Components should be exported as default export or named export matching the class name:
+ * ```typescript
+ * // Default export (preferred)
+ * export default class WeatherCollector extends Collector { ... }
+ *
+ * // Named export matching file name
+ * export class WeatherCollector extends Collector { ... }
+ * ```
+ *
+ * @param directory - Directory path to scan for components (absolute or relative to cwd)
+ * @param options - Configuration options for discovery
+ * @returns Promise resolving to loaded components and metadata
+ *
+ * @example
+ * ```typescript
+ * import { loadComponents, DigitalTwinEngine } from 'digitaltwin-core'
+ *
+ * // Basic usage - scan compiled components
+ * const result = await loadComponents('./dist/components')
+ *
+ * console.log(`Loaded ${result.summary.total} components`)
+ *
+ * const engine = new DigitalTwinEngine({ storage, database })
+ * engine.registerComponents(result)
+ * await engine.start()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Advanced usage with options
+ * const result = await loadComponents('./dist/components', {
+ *   recursive: true,
+ *   verbose: true,
+ *   extensions: ['.js'],
+ *   exclude: ['*.test.*', 'deprecated_*']
+ * })
+ *
+ * if (result.errors.length > 0) {
+ *   console.warn('Some components failed to load:', result.errors)
+ * }
+ * ```
+ */
+export async function loadComponents(directory, options = {}) {
+    const patterns = { ...DEFAULT_PATTERNS, ...options.patterns };
+    const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
+    const exclude = options.exclude ?? DEFAULT_EXCLUDE;
+    const recursive = options.recursive ?? true;
+    const verbose = options.verbose ?? false;
+    const result = {
+        collectors: [],
+        harvesters: [],
+        handlers: [],
+        assetsManagers: [],
+        customTableManagers: [],
+        scannedFiles: [],
+        errors: [],
+        summary: {
+            total: 0,
+            collectors: 0,
+            harvesters: 0,
+            handlers: 0,
+            assetsManagers: 0,
+            customTableManagers: 0,
+            errors: 0
+        }
+    };
+    // Resolve directory path
+    const absoluteDir = path.isAbsolute(directory) ? directory : path.resolve(process.cwd(), directory);
+    // Check if directory exists
+    try {
+        await fs.access(absoluteDir);
+    }
+    catch {
+        if (verbose) {
+            console.warn(`[loadComponents] Directory not found: ${absoluteDir}`);
+        }
+        return result;
+    }
+    // Scan for component files
+    const files = await scanDirectory(absoluteDir, { extensions, exclude, recursive, patterns });
+    result.scannedFiles = files.map(f => f.path);
+    if (verbose) {
+        console.log(`[loadComponents] Found ${files.length} potential component files`);
+    }
+    // Load each component file
+    for (const { path: filePath, type: expectedType } of files) {
+        try {
+            // Convert to file URL for ESM import
+            const fileUrl = pathToFileURL(filePath).href;
+            const module = await import(fileUrl);
+            // Find component class in module exports
+            let ComponentClass = null;
+            // Try default export first
+            if (module.default && isClassConstructor(module.default)) {
+                ComponentClass = module.default;
+            }
+            else {
+                // Try named exports
+                const fileName = path.basename(filePath, path.extname(filePath));
+                const expectedClassName = toPascalCase(fileName);
+                if (module[expectedClassName] && isClassConstructor(module[expectedClassName])) {
+                    ComponentClass = module[expectedClassName];
+                }
+                else {
+                    // Try to find any class export that's a valid component
+                    for (const [, value] of Object.entries(module)) {
+                        if (isClassConstructor(value)) {
+                            try {
+                                const testInstance = new value();
+                                if (isValidComponent(testInstance)) {
+                                    ComponentClass = value;
+                                    break;
+                                }
+                            }
+                            catch {
+                                // Skip if instantiation fails
+                            }
+                        }
+                    }
+                }
+            }
+            if (!ComponentClass) {
+                result.errors.push({
+                    file: filePath,
+                    error: 'No valid component class found in module exports'
+                });
+                continue;
+            }
+            // Instantiate the component
+            const instance = new ComponentClass();
+            if (!isValidComponent(instance)) {
+                result.errors.push({
+                    file: filePath,
+                    error: 'Instantiated class is not a valid Digital Twin component'
+                });
+                continue;
+            }
+            // Add to appropriate array based on actual type (not expected type)
+            if (isCollector(instance)) {
+                result.collectors.push(instance);
+                result.summary.collectors++;
+            }
+            else if (isHarvester(instance)) {
+                result.harvesters.push(instance);
+                result.summary.harvesters++;
+            }
+            else if (isHandler(instance)) {
+                result.handlers.push(instance);
+                result.summary.handlers++;
+            }
+            else if (isCustomTableManager(instance)) {
+                result.customTableManagers.push(instance);
+                result.summary.customTableManagers++;
+            }
+            else if (isAssetsManager(instance)) {
+                result.assetsManagers.push(instance);
+                result.summary.assetsManagers++;
+            }
+            result.summary.total++;
+            if (verbose) {
+                const config = instance.getConfiguration();
+                console.log(`[loadComponents] Loaded: ${config.name} (${expectedType})`);
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            result.errors.push({
+                file: filePath,
+                error: `Failed to import: ${errorMessage}`
+            });
+            result.summary.errors++;
+            if (verbose) {
+                console.error(`[loadComponents] Error loading ${filePath}:`, errorMessage);
+            }
+        }
+    }
+    if (verbose) {
+        console.log(`[loadComponents] Summary:`, result.summary);
+    }
+    return result;
+}
+//# sourceMappingURL=component_loader.js.map

package/dist/loader/component_loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component_loader.js","sourceRoot":"","sources":["../../src/loader/component_loader.ts"],"names":[],"mappings":"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"}

package/dist/loader/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Component auto-discovery and loading utilities
+ *
+ * This module provides utilities for automatically discovering and loading
+ * Digital Twin components from a directory based on file naming conventions.
+ *
+ * @example
+ * ```typescript
+ * import { loadComponents } from 'digitaltwin-core'
+ *
+ * const result = await loadComponents('./dist/components')
+ *
+ * const engine = new DigitalTwinEngine({ storage, database })
+ * engine.registerComponents(result)
+ * await engine.start()
+ * ```
+ */
+export { loadComponents, type LoadComponentsOptions, type LoadComponentsResult } from './component_loader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/loader/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/loader/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/loader/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Component auto-discovery and loading utilities
+ *
+ * This module provides utilities for automatically discovering and loading
+ * Digital Twin components from a directory based on file naming conventions.
+ *
+ * @example
+ * ```typescript
+ * import { loadComponents } from 'digitaltwin-core'
+ *
+ * const result = await loadComponents('./dist/components')
+ *
+ * const engine = new DigitalTwinEngine({ storage, database })
+ * engine.registerComponents(result)
+ * await engine.start()
+ * ```
+ */
+export { loadComponents } from './component_loader.js';
+//# sourceMappingURL=index.js.map

package/dist/loader/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/loader/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,cAAc,EAAyD,MAAM,uBAAuB,CAAA"}

package/dist/storage/adapters/local_storage_service.d.ts

@@ -4,6 +4,7 @@ import { StorageService } from '../storage_service.js';
  * Saves files in a configured folder using a timestamp as filename.
  */
 export declare class LocalStorageService extends StorageService {
+    #private;
     private baseDir;
     constructor(baseDir?: string);
     /**
@@ -18,11 +19,13 @@ export declare class LocalStorageService extends StorageService {
      * Retrieves a file as buffer using its relative path.
      * @param relativePath - Filename previously returned by `save`
      * @returns File content as Buffer
+     * @throws Error if path traversal is detected
      */
     retrieve(relativePath: string): Promise<Buffer>;
     /**
      * Deletes a stored file.
      * @param relativePath - Filename previously returned by `save`
+     * @throws Error if path traversal is detected
      */
     delete(relativePath: string): Promise<void>;
     /**
@@ -31,6 +34,7 @@ export declare class LocalStorageService extends StorageService {
      * @param buffer - Content to save
      * @param relativePath - Full relative path including filename (e.g., 'tilesets/123/tileset.json')
      * @returns The same relative path that was provided
+     * @throws Error if path traversal is detected
      */
     saveWithPath(buffer: Buffer, relativePath: string): Promise<string>;
     /**
@@ -39,12 +43,14 @@ export declare class LocalStorageService extends StorageService {
      * In production, use a cloud storage service (OVH, S3) for public URLs.
      * @param relativePath - The storage path of the file
      * @returns The file path (relative to baseDir)
+     * @throws Error if path traversal is detected
      */
     getPublicUrl(relativePath: string): string;
     /**
      * Deletes all files under a given prefix (folder).
      * @param prefix - The folder/prefix to delete (e.g., 'tilesets/123')
      * @returns Number of files deleted
+     * @throws Error if path traversal is detected
      */
     deleteByPrefix(prefix: string): Promise<number>;
 }

package/dist/storage/adapters/local_storage_service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local_storage_service.d.ts","sourceRoot":"","sources":["../../../src/storage/adapters/local_storage_service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAItD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;IACvC,OAAO,CAAC,OAAO;gBAAP,OAAO,GAAE,MAAe;IAI5C;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAetF;;;;OAIG;IACG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKrD;;;OAGG;IACG,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD;;;;;;OAMG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUzE;;;;;;OAMG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAM1C;;;;OAIG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAgCxD"}
+{"version":3,"file":"local_storage_service.d.ts","sourceRoot":"","sources":["../../../src/storage/adapters/local_storage_service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAItD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;;IAGvC,OAAO,CAAC,OAAO;gBAAP,OAAO,GAAE,MAAe;IAqB5C;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAetF;;;;;OAKG;IACG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKrD;;;;OAIG;IACG,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD;;;;;;;OAOG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUzE;;;;;;;OAOG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAQ1C;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAgCxD"}

package/dist/storage/adapters/local_storage_service.js

@@ -6,9 +6,24 @@ import path from 'path';
  * Saves files in a configured folder using a timestamp as filename.
  */
 export class LocalStorageService extends StorageService {
+    #normalizedBase;
     constructor(baseDir = 'data') {
         super();
         this.baseDir = baseDir;
+        this.#normalizedBase = path.resolve(this.baseDir);
+    }
+    /**
+     * Validates that a path does not escape the base directory (path traversal protection).
+     * @param relativePath - The relative path to validate
+     * @returns The resolved absolute path if valid
+     * @throws Error if path traversal is detected
+     */
+    #validatePath(relativePath) {
+        const resolved = path.resolve(this.#normalizedBase, relativePath);
+        if (!resolved.startsWith(this.#normalizedBase + path.sep) && resolved !== this.#normalizedBase) {
+            throw new Error(`Invalid path: path traversal detected for "${relativePath}"`);
+        }
+        return resolved;
     }
     /**
      * Saves the given buffer to disk under a unique filename.
@@ -33,17 +48,19 @@ export class LocalStorageService extends StorageService {
      * Retrieves a file as buffer using its relative path.
      * @param relativePath - Filename previously returned by `save`
      * @returns File content as Buffer
+     * @throws Error if path traversal is detected
      */
     async retrieve(relativePath) {
-        const filePath = path.join(this.baseDir, relativePath);
+        const filePath = this.#validatePath(relativePath);
         return fs.readFile(filePath);
     }
     /**
      * Deletes a stored file.
      * @param relativePath - Filename previously returned by `save`
+     * @throws Error if path traversal is detected
      */
     async delete(relativePath) {
-        const filePath = path.join(this.baseDir, relativePath);
+        const filePath = this.#validatePath(relativePath);
         await fs.rm(filePath, { force: true });
     }
     /**
@@ -52,9 +69,10 @@ export class LocalStorageService extends StorageService {
      * @param buffer - Content to save
      * @param relativePath - Full relative path including filename (e.g., 'tilesets/123/tileset.json')
      * @returns The same relative path that was provided
+     * @throws Error if path traversal is detected
      */
     async saveWithPath(buffer, relativePath) {
-        const filePath = path.join(this.baseDir, relativePath);
+        const filePath = this.#validatePath(relativePath);
         const dirPath = path.dirname(filePath);
         await fs.mkdir(dirPath, { recursive: true });
         await fs.writeFile(filePath, buffer);
@@ -66,8 +84,11 @@ export class LocalStorageService extends StorageService {
      * In production, use a cloud storage service (OVH, S3) for public URLs.
      * @param relativePath - The storage path of the file
      * @returns The file path (relative to baseDir)
+     * @throws Error if path traversal is detected
      */
     getPublicUrl(relativePath) {
+        // Validate path to prevent traversal (even though this just returns a string)
+        this.#validatePath(relativePath);
         // For local storage, return the file path
         // In a real deployment, you'd need Express static serving or similar
         return path.join(this.baseDir, relativePath);
@@ -76,9 +97,10 @@ export class LocalStorageService extends StorageService {
      * Deletes all files under a given prefix (folder).
      * @param prefix - The folder/prefix to delete (e.g., 'tilesets/123')
      * @returns Number of files deleted
+     * @throws Error if path traversal is detected
      */
     async deleteByPrefix(prefix) {
-        const folderPath = path.join(this.baseDir, prefix);
+        const folderPath = this.#validatePath(prefix);
         try {
             // Check if folder exists
             await fs.access(folderPath);