axiodb 7.33.233 → 7.33.234

package/.agents/skills/axiodb-development/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: axiodb-development
+description: Core development rules and patterns for AxioDB embedded NoSQL database
+version: 1.0.0
+tags: [typescript, database, testing, build]
+author: AxioDB Team
+---
+
+# AxioDB Development Skill
+
+## Project Identity
+
+**AxioDB** - Embedded NoSQL database for Node.js
+- TypeScript strict mode → CommonJS
+- Node.js ≥20.0.0
+- Zero native dependencies
+- Singleton pattern, file-per-document storage
+
+## Mandatory Workflows
+
+### After EVERY Code Change
+```bash
+npm run build  # MANDATORY - catch TypeScript errors immediately
+```
+
+### For ANY Feature Change
+1. Update tests in `Test/modules/`
+2. Run `npm test` - all tests must pass
+3. Update docs (README.md, Document/, Dockerfile)
+4. Run `npm run lint` - must pass
+
+## Definition of "Done"
+
+A task is NOT complete until ALL of these are true:
+- ✅ Code written following standards
+- ✅ `npm run build` passes with zero errors
+- ✅ Tests added/updated in `Test/modules/`
+- ✅ `npm test` passes - all tests green
+- ✅ `npm run lint` passes
+- ✅ Documentation updated (README, Document/, Dockerfile)
+- ✅ No breaking changes (or explicitly noted and approved)
+- ✅ Self-reviewed for performance, security, maintainability
+
+## Architecture Constraints
+
+### Singleton Pattern (NON-NEGOTIABLE)
+```typescript
+export class AxioDB {
+  private static _instance: AxioDB;
+
+  constructor() {
+    if (AxioDB._instance) {
+      throw new Error("Only one instance of AxioDB is allowed.");
+    }
+    AxioDB._instance = this;
+  }
+}
+```
+
+**Critical Implication**: Tests MUST run in separate child processes. Cannot run tests in parallel.
+
+### File-Per-Document Storage
+```
+{RootPath}/{DatabaseName}/{CollectionName}/{documentId}.axiodb
+```
+
+### Dual-Write Pattern (Indexes)
+```typescript
+// ALWAYS write to BOTH memory AND disk
+await this.indexCache.set(key, data, TTL);  // Memory (speed)
+await this.fileManager.writeFile(path, JSON.stringify(data));  // Disk (durability)
+```
+
+### Random Cache TTL (5-15 minutes)
+```typescript
+const TTL = Math.floor(Math.random() * (15 - 5 + 1) + 5) * 60 * 1000;
+```
+**Why**: Prevents cache stampede/thundering herd
+
+## TypeScript Standards (STRICT)
+
+### NO `any` Types - EVER
+```typescript
+// ❌ ABSOLUTELY FORBIDDEN
+const result: any = await operation();
+
+// ✅ REQUIRED
+interface OperationResult {
+  success: boolean;
+  data: DocumentData;
+}
+const result: OperationResult = await operation();
+```
+
+### Strict Null Checks
+```typescript
+// ✅ GOOD
+function get(id: string): Document | null {
+  return this.cache.get(id) ?? null;
+}
+
+const doc = get('123');
+if (doc !== null) {
+  console.log(doc.name);
+}
+```
+
+## SOLID Principles
+
+### Single Responsibility
+Each class/module has ONE reason to change.
+
+### Don't Repeat Yourself (DRY)
+If same logic appears in 2+ files, extract to `Helper/` directory.
+
+### No Hacky Solutions
+```typescript
+// ❌ FORBIDDEN
+setTimeout(() => { /* hope this works */ }, 1000);
+eval(userInput);
+try { risky(); } catch (e) { /* ignore */ }
+
+// ✅ REQUIRED
+await properAsyncOperation();
+const sanitized = validateAndSanitize(userInput);
+try { await risky(); } catch (error) {
+  logger.error('Operation failed', error);
+  return ResponseHelper.error('Failed', StatusCodes.ERROR);
+}
+```
+
+## Testing Requirements
+
+### Location
+```
+Test/modules/
+├── crud.test.js          # CRUD operations
+├── transaction.test.js   # Transactions, WAL, savepoints
+└── read.test.js          # Read optimizations, caching
+```
+
+### Coverage Required
+- Happy path (success scenarios)
+- Edge cases (empty, null, undefined, large data)
+- Error cases (validation failures, file errors, conflicts)
+- Concurrent operations
+- Backward compatibility
+
+## Module Organization
+
+```
+source/
+├── Services/
+│   ├── Database/              # Database ops
+│   ├── Collection/            # Collection ops
+│   ├── CRUD Operation/        # Create, Reader, Update, Delete
+│   ├── Index/                 # Index management (cache + disk)
+│   ├── Aggregation/           # MongoDB-style pipelines
+│   └── Transaction/           # ACID, WAL, sessions
+├── engine/Filesystem/         # FileManager, FolderManager
+├── server/                    # HTTP GUI (Fastify, port 27018)
+├── tcp/                       # TCP server (AxioDBCloud, port 27019)
+├── client/                    # AxioDBCloud TCP client
+├── Helper/                    # Converter, Crypto, Response
+└── Memory/                    # InMemoryCache
+```
+
+## Naming Conventions
+
+- **Files**: `{Feature}.operation.ts`, `{Feature}.service.ts`, `{Feature}.helper.ts`
+- **Classes**: PascalCase: `FileManager`, `QueryMatcher`
+- **Methods**: camelCase: `createDatabase()`, `isValidDocument()`
+- **Variables**: camelCase: `documentId`, `collectionPath`
+
+## Performance Standards
+
+### 1. Use InMemoryCache
+```typescript
+const cached = this.cache.get(key);
+if (cached) return cached;
+
+const data = await this.readFromDisk(id);
+this.cache.set(key, data, TTL);
+return data;
+```
+
+### 2. Batch Operations
+```typescript
+// ✅ PARALLEL
+await Promise.all(docs.map(d => this.insert(d)));
+
+// ❌ SEQUENTIAL (slow)
+for (const d of docs) { await this.insert(d); }
+```
+
+### 3. Use Map for O(1) Lookups
+```typescript
+// ✅ O(1)
+const map = new Map<string, Document>();
+const found = map.get(id);
+
+// ❌ O(n)
+const found = array.find(d => d.id === id);
+```
+
+## Security Standards
+
+### 1. Validate All Input
+```typescript
+if (!document || typeof document !== 'object') {
+  return this.ResponseHelper.error('Invalid', StatusCodes.BAD_REQUEST);
+}
+if (Array.isArray(document)) {
+  return this.ResponseHelper.error('Cannot be array', StatusCodes.BAD_REQUEST);
+}
+```
+
+### 2. Sanitize File Paths
+```typescript
+// Prevent path traversal
+const sanitized = documentId.replace(/[^a-zA-Z0-9-_]/g, '_');
+return path.join(collectionPath, `${sanitized}.axiodb`);
+```
+
+### 3. Handle Sensitive Data
+```typescript
+// Encrypt collections with sensitive data
+const users = await db.createCollection('Users', true, process.env.KEY);
+
+// Never log passwords
+logger.info('Auth', { userId }); // ✅
+logger.info('Auth', { password }); // ❌
+```
+
+## Documentation Requirements
+
+Update when features change:
+
+1. **README.md** - Public API, features, quick start examples
+2. **Document/** - React docs site (`cd Document && npm run dev`)
+3. **Dockerfile** - If ports, env vars, or commands change
+4. **JSDoc** - All public methods with examples
+
+## Anti-Patterns (FORBIDDEN)
+
+❌ Using `any` types
+❌ Duplicated code (violates DRY)
+❌ Sequential operations that could be parallel
+❌ Ignoring build errors
+❌ Skipping tests
+❌ Missing documentation
+❌ Hardcoded values
+❌ Magic strings/numbers
+❌ Deep nesting (>3 levels)
+❌ Unclear variable names
+❌ Suppressing errors without handling
+
+## Commands
+
+```bash
+# Build & Test
+npm run build              # TypeScript → lib/ (MANDATORY)
+npm test                   # All tests
+npm test crud              # CRUD tests only
+npm test transaction       # Transaction tests only
+npm test read              # Read optimization tests
+npm run lint               # ESLint
+
+# Development
+node Test/modules/crud.test.js  # Run specific test
+cd Document && npm run dev      # Docs site (localhost:5173)
+```
+
+## Success Criteria
+
+Every task must meet ALL:
+- ✅ Builds successfully (`npm run build`)
+- ✅ Tests pass (`npm test`)
+- ✅ Lint passes (`npm run lint`)
+- ✅ Docs updated
+- ✅ No regressions
+- ✅ Follows patterns
+- ✅ Security validated
+- ✅ Performance acceptable

package/.gemini/settings.json

@@ -0,0 +1,53 @@
+{
+  "version": "1.0",
+  "description": "NoSQL database management system for efficient data storage and retrieval.",
+  "project": {
+    "name": "AxioDB",
+    "type": "NoSQL Database",
+    "language": "TypeScript",
+    "runtime": "Node.js ≥18.0.0"
+  },
+  "context": {
+    "fileName": [
+      "GEMINI.md"
+    ],
+    "hierarchical": true,
+    "scanSubdirectories": true
+  },
+  "tools": {
+    "enabled": [
+      "codeSearch",
+      "fileOperations",
+      "shellCommands"
+    ],
+    "codeSearch": {
+      "indexFiles": true,
+      "excludePatterns": [
+        "node_modules",
+        "lib",
+        "dist",
+        ".git"
+      ]
+    }
+  },
+  "safety": {
+    "blockNone": false,
+    "blockFewUnsafe": true,
+    "blockSomeUnsafe": true,
+    "blockMostUnsafe": true
+  },
+  "performance": {
+    "streamResponse": true,
+    "cacheContext": true,
+    "maxCachedContexts": 10
+  },
+  "features": {
+    "codeCompletion": true,
+    "codeGeneration": true,
+    "codeExplanation": true,
+    "debugging": true,
+    "refactoring": true,
+    "testing": true,
+    "documentation": true
+  }
+}

package/lib/Helper/DocumentLoader.helper.d.ts

@@ -0,0 +1,45 @@
+import { SuccessInterface, ErrorInterface } from '../config/Interfaces/Helper/response.helper.interface';
+/**
+ * DocumentLoader - Shared utility for loading documents from collection directories
+ *
+ * Provides a centralized method for loading document files using worker threads,
+ * replacing duplicated code in Reader, Update, Delete, and Aggregation operations.
+ *
+ * @class DocumentLoader
+ */
+export default class DocumentLoader {
+    private static readonly ResponseHelper;
+    /**
+     * Loads all documents from a collection directory using worker threads
+     *
+     * This method consolidates the LoadAllBufferRawData logic that was previously
+     * duplicated across multiple CRUD operations. It handles both direct file
+     * specification and directory scanning with .axiodb file filtering.
+     *
+     * @param collectionPath - Full path to collection directory
+     * @param encryptionKey - Optional encryption key for encrypted documents
+     * @param isEncrypted - Whether documents are encrypted (default: false)
+     * @param documentFiles - Optional specific file names to load
+     * @param includeFileName - Whether to include fileName in result (default: false)
+     * @returns Success with document array or Error
+     *
+     * @example
+     * // Load all documents from a collection
+     * const result = await DocumentLoader.loadDocuments(
+     *   '/path/to/collection',
+     *   undefined,
+     *   false
+     * );
+     *
+     * @example
+     * // Load specific documents with filenames included
+     * const result = await DocumentLoader.loadDocuments(
+     *   '/path/to/collection',
+     *   'encryption-key',
+     *   true,
+     *   ['doc1.axiodb', 'doc2.axiodb'],
+     *   true
+     * );
+     */
+    static loadDocuments(collectionPath: string, encryptionKey?: string, isEncrypted?: boolean, documentFiles?: string[], includeFileName?: boolean): Promise<SuccessInterface | ErrorInterface>;
+}

package/lib/Helper/DocumentLoader.helper.js

@@ -0,0 +1,91 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const FolderManager_1 = __importDefault(require("../engine/Filesystem/FolderManager"));
+const BufferLoaderWithWorker_utils_1 = __importDefault(require("../utility/BufferLoaderWithWorker.utils"));
+const response_helper_1 = __importDefault(require("./response.helper"));
+/**
+ * DocumentLoader - Shared utility for loading documents from collection directories
+ *
+ * Provides a centralized method for loading document files using worker threads,
+ * replacing duplicated code in Reader, Update, Delete, and Aggregation operations.
+ *
+ * @class DocumentLoader
+ */
+class DocumentLoader {
+    /**
+     * Loads all documents from a collection directory using worker threads
+     *
+     * This method consolidates the LoadAllBufferRawData logic that was previously
+     * duplicated across multiple CRUD operations. It handles both direct file
+     * specification and directory scanning with .axiodb file filtering.
+     *
+     * @param collectionPath - Full path to collection directory
+     * @param encryptionKey - Optional encryption key for encrypted documents
+     * @param isEncrypted - Whether documents are encrypted (default: false)
+     * @param documentFiles - Optional specific file names to load
+     * @param includeFileName - Whether to include fileName in result (default: false)
+     * @returns Success with document array or Error
+     *
+     * @example
+     * // Load all documents from a collection
+     * const result = await DocumentLoader.loadDocuments(
+     *   '/path/to/collection',
+     *   undefined,
+     *   false
+     * );
+     *
+     * @example
+     * // Load specific documents with filenames included
+     * const result = await DocumentLoader.loadDocuments(
+     *   '/path/to/collection',
+     *   'encryption-key',
+     *   true,
+     *   ['doc1.axiodb', 'doc2.axiodb'],
+     *   true
+     * );
+     */
+    static loadDocuments(collectionPath_1, encryptionKey_1) {
+        return __awaiter(this, arguments, void 0, function* (collectionPath, encryptionKey, isEncrypted = false, documentFiles, includeFileName = false) {
+            try {
+                const dataFilesList = [];
+                if (documentFiles !== undefined) {
+                    // Use provided file list
+                    dataFilesList.push(...documentFiles);
+                }
+                else {
+                    // Scan directory for .axiodb files
+                    const readResponse = yield new FolderManager_1.default().ListDirectory(collectionPath);
+                    if ("data" in readResponse) {
+                        // Filter for .axiodb files only
+                        const axiodbFiles = readResponse.data.filter((file) => file.endsWith(".axiodb"));
+                        dataFilesList.push(...axiodbFiles);
+                    }
+                    else {
+                        return this.ResponseHelper.Error("Failed to read directory");
+                    }
+                }
+                // Load all files using worker threads (parallel processing)
+                const resultData = yield (0, BufferLoaderWithWorker_utils_1.default)(dataFilesList, encryptionKey, collectionPath, isEncrypted, includeFileName);
+                return this.ResponseHelper.Success(resultData);
+            }
+            catch (error) {
+                return this.ResponseHelper.Error(error);
+            }
+        });
+    }
+}
+DocumentLoader.ResponseHelper = new response_helper_1.default();
+exports.default = DocumentLoader;
+//# sourceMappingURL=DocumentLoader.helper.js.map

package/lib/Helper/DocumentLoader.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentLoader.helper.js","sourceRoot":"","sources":["../../source/Helper/DocumentLoader.helper.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AACA,uFAA+D;AAC/D,2GAAuE;AACvE,wEAA+C;AAE/C;;;;;;;GAOG;AACH,MAAqB,cAAc;IAGjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,MAAM,CAAO,aAAa;6DACxB,cAAsB,EACtB,aAAsB,EACtB,cAAuB,KAAK,EAC5B,aAAwB,EACxB,kBAA2B,KAAK;YAEhC,IAAI,CAAC;gBACH,MAAM,aAAa,GAAa,EAAE,CAAC;gBAEnC,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;oBAChC,yBAAyB;oBACzB,aAAa,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC;gBACvC,CAAC;qBAAM,CAAC;oBACN,mCAAmC;oBACnC,MAAM,YAAY,GAAG,MAAM,IAAI,uBAAa,EAAE,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC;oBAE7E,IAAI,MAAM,IAAI,YAAY,EAAE,CAAC;wBAC3B,gCAAgC;wBAChC,MAAM,WAAW,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAY,EAAE,EAAE,CAC5D,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CACzB,CAAC;wBACF,aAAa,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC;oBACrC,CAAC;yBAAM,CAAC;wBACN,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;oBAC/D,CAAC;gBACH,CAAC;gBAED,4DAA4D;gBAC5D,MAAM,UAAU,GAAG,MAAM,IAAA,sCAAgB,EACvC,aAAa,EACb,aAAa,EACb,cAAc,EACd,WAAW,EACX,eAAe,CAChB,CAAC;gBAEF,OAAO,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;YACjD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;KAAA;;AA3EuB,6BAAc,GAAG,IAAI,yBAAc,EAAE,CAAC;kBAD3C,cAAc"}

package/lib/Helper/PathSanitizer.helper.d.ts

@@ -0,0 +1,69 @@
+/**
+ * PathSanitizer - Security helper to prevent directory traversal attacks
+ *
+ * Provides methods to sanitize user-controlled path components and validate
+ * that constructed paths remain within expected boundaries.
+ *
+ * @class PathSanitizer
+ * @example
+ * const safe = PathSanitizer.sanitizePathComponent('../../etc/passwd');
+ * // Returns: '______etc_passwd'
+ */
+export default class PathSanitizer {
+    /**
+     * Sanitizes user input to prevent directory traversal attacks
+     *
+     * Removes dangerous characters that could be used for path traversal,
+     * including: '../', '/', '\', null bytes, and other special characters.
+     *
+     * @param userInput - Potentially malicious path component
+     * @returns Sanitized string safe for file paths
+     * @throws Error if input is invalid or results in empty string
+     *
+     * @example
+     * PathSanitizer.sanitizePathComponent('../../../etc/passwd');
+     * // Returns: '______etc_passwd'
+     *
+     * PathSanitizer.sanitizePathComponent('safe-name_123');
+     * // Returns: 'safe-name_123'
+     */
+    static sanitizePathComponent(userInput: string): string;
+    /**
+     * Validates that resolved path is within basePath (defense in depth)
+     *
+     * This provides an additional security layer by ensuring the final
+     * constructed path hasn't escaped the expected base directory through
+     * symlinks or other means.
+     *
+     * @param basePath - Expected parent directory
+     * @param fullPath - Constructed path to validate
+     * @throws Error if path traversal detected
+     *
+     * @example
+     * PathSanitizer.validatePath('/app/data', '/app/data/users/123.axiodb');
+     * // No error - path is within base
+     *
+     * PathSanitizer.validatePath('/app/data', '/etc/passwd');
+     * // Throws: Security violation: Path traversal attempt detected
+     */
+    static validatePath(basePath: string, fullPath: string): void;
+    /**
+     * Safe path join with automatic sanitization and validation
+     *
+     * Combines base path with one or more path components after sanitizing
+     * each component and validating the final path remains within the base.
+     *
+     * @param basePath - Base directory (trusted path)
+     * @param components - Path components to join (will be sanitized)
+     * @returns Safe joined path guaranteed to be within basePath
+     * @throws Error if sanitization fails or path traversal detected
+     *
+     * @example
+     * PathSanitizer.safePath('/app/data', 'users', 'doc123.axiodb');
+     * // Returns: '/app/data/users/doc123.axiodb'
+     *
+     * PathSanitizer.safePath('/app/data', '../../../etc/passwd');
+     * // Throws: Security violation (after sanitization and validation)
+     */
+    static safePath(basePath: string, ...components: string[]): string;
+}

package/lib/Helper/PathSanitizer.helper.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+/**
+ * PathSanitizer - Security helper to prevent directory traversal attacks
+ *
+ * Provides methods to sanitize user-controlled path components and validate
+ * that constructed paths remain within expected boundaries.
+ *
+ * @class PathSanitizer
+ * @example
+ * const safe = PathSanitizer.sanitizePathComponent('../../etc/passwd');
+ * // Returns: '______etc_passwd'
+ */
+class PathSanitizer {
+    /**
+     * Sanitizes user input to prevent directory traversal attacks
+     *
+     * Removes dangerous characters that could be used for path traversal,
+     * including: '../', '/', '\', null bytes, and other special characters.
+     *
+     * @param userInput - Potentially malicious path component
+     * @returns Sanitized string safe for file paths
+     * @throws Error if input is invalid or results in empty string
+     *
+     * @example
+     * PathSanitizer.sanitizePathComponent('../../../etc/passwd');
+     * // Returns: '______etc_passwd'
+     *
+     * PathSanitizer.sanitizePathComponent('safe-name_123');
+     * // Returns: 'safe-name_123'
+     */
+    static sanitizePathComponent(userInput) {
+        if (!userInput || typeof userInput !== 'string') {
+            throw new Error('Invalid path component: must be a non-empty string');
+        }
+        // Remove all directory traversal attempts
+        let sanitized = userInput
+            .replace(/\.\./g, '_') // Remove .. (parent directory)
+            .replace(/\//g, '_') // Remove / (Unix path separator)
+            .replace(/\\/g, '_') // Remove \ (Windows path separator)
+            .replace(/\0/g, '_'); // Remove null bytes
+        // Allow only alphanumeric, dash, underscore, and dot (for file extensions)
+        // Note: We preserve dots for file extensions but removed '..' above
+        sanitized = sanitized.replace(/[^a-zA-Z0-9-_.]/g, '_');
+        // Prevent empty result
+        if (sanitized.length === 0) {
+            throw new Error('Invalid path component: results in empty string after sanitization');
+        }
+        // Prevent starting with dot (hidden files) to avoid potential issues
+        if (sanitized.startsWith('.')) {
+            sanitized = '_' + sanitized.substring(1);
+        }
+        return sanitized;
+    }
+    /**
+     * Validates that resolved path is within basePath (defense in depth)
+     *
+     * This provides an additional security layer by ensuring the final
+     * constructed path hasn't escaped the expected base directory through
+     * symlinks or other means.
+     *
+     * @param basePath - Expected parent directory
+     * @param fullPath - Constructed path to validate
+     * @throws Error if path traversal detected
+     *
+     * @example
+     * PathSanitizer.validatePath('/app/data', '/app/data/users/123.axiodb');
+     * // No error - path is within base
+     *
+     * PathSanitizer.validatePath('/app/data', '/etc/passwd');
+     * // Throws: Security violation: Path traversal attempt detected
+     */
+    static validatePath(basePath, fullPath) {
+        const resolvedBase = path_1.default.resolve(basePath);
+        const resolvedFull = path_1.default.resolve(fullPath);
+        if (!resolvedFull.startsWith(resolvedBase)) {
+            throw new Error('Security violation: Path traversal attempt detected');
+        }
+    }
+    /**
+     * Safe path join with automatic sanitization and validation
+     *
+     * Combines base path with one or more path components after sanitizing
+     * each component and validating the final path remains within the base.
+     *
+     * @param basePath - Base directory (trusted path)
+     * @param components - Path components to join (will be sanitized)
+     * @returns Safe joined path guaranteed to be within basePath
+     * @throws Error if sanitization fails or path traversal detected
+     *
+     * @example
+     * PathSanitizer.safePath('/app/data', 'users', 'doc123.axiodb');
+     * // Returns: '/app/data/users/doc123.axiodb'
+     *
+     * PathSanitizer.safePath('/app/data', '../../../etc/passwd');
+     * // Throws: Security violation (after sanitization and validation)
+     */
+    static safePath(basePath, ...components) {
+        // Sanitize each component
+        const sanitizedComponents = components.map(c => this.sanitizePathComponent(c));
+        // Join paths using Node.js path.join (handles platform differences)
+        const fullPath = path_1.default.join(basePath, ...sanitizedComponents);
+        // Validate final path is within base (defense in depth)
+        this.validatePath(basePath, fullPath);
+        return fullPath;
+    }
+}
+exports.default = PathSanitizer;
+//# sourceMappingURL=PathSanitizer.helper.js.map

package/lib/Helper/PathSanitizer.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PathSanitizer.helper.js","sourceRoot":"","sources":["../../source/Helper/PathSanitizer.helper.ts"],"names":[],"mappings":";;;;;AAAA,gDAAwB;AAExB;;;;;;;;;;GAUG;AACH,MAAqB,aAAa;IAChC;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,qBAAqB,CAAC,SAAiB;QAC5C,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QAED,0CAA0C;QAC1C,IAAI,SAAS,GAAG,SAAS;aACtB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAI,+BAA+B;aACxD,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAM,iCAAiC;aAC1D,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAM,oCAAoC;aAC7D,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAK,oBAAoB;QAEhD,2EAA2E;QAC3E,oEAAoE;QACpE,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;QAEvD,uBAAuB;QACvB,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACxF,CAAC;QAED,qEAAqE;QACrE,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,SAAS,GAAG,GAAG,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC3C,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,YAAY,CAAC,QAAgB,EAAE,QAAgB;QACpD,MAAM,YAAY,GAAG,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC5C,MAAM,YAAY,GAAG,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAE5C,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAgB,EAAE,GAAG,UAAoB;QACvD,0BAA0B;QAC1B,MAAM,mBAAmB,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;QAE/E,oEAAoE;QACpE,MAAM,QAAQ,GAAG,cAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,mBAAmB,CAAC,CAAC;QAE7D,wDAAwD;QACxD,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAEtC,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AAxGD,gCAwGC"}