@utilarium/overcontext 0.0.4-dev.0 → 0.0.4

package/dist/index.cjs

@@ -43,7 +43,9 @@ const yaml__namespace = /*#__PURE__*/_interopNamespaceDefault(yaml);
  * The minimal contract every entity must satisfy.
  * Consuming libraries extend this with their own fields.
  */ const BaseEntitySchema = zod.z.object({
-    /** Unique identifier within the entity type (used as filename) */ id: zod.z.string().min(1),
+    /** Unique identifier within the entity type (used as filename) */ id: zod.z.string().min(1).max(255).regex(/^[a-zA-Z0-9][-a-zA-Z0-9_.]*$/, {
+        message: 'ID must be filesystem-safe: start with alphanumeric and contain only alphanumeric, hyphens, underscores, and dots'
+    }),
     /** Human-readable name (used for display and search) */ name: zod.z.string().min(1),
     /** Entity type discriminator (must be a string literal in extensions) */ type: zod.z.string().min(1),
     /** Optional notes - common enough to include in base */ notes: zod.z.string().optional()
@@ -344,6 +346,7 @@ class NamespaceNotFoundError extends StorageError {
                 type: 'storage:disposed',
                 timestamp: new Date()
             });
+            handlers.clear(); // Clear all handlers to prevent memory leaks
             await provider.dispose();
         },
         async save (entity, namespace) {
@@ -411,18 +414,78 @@ class NamespaceNotFoundError extends StorageError {
 const createFileSystemProvider = async (options)=>{
     const { basePath, registry, createIfMissing = true, extension = '.yaml', readonly = false, defaultNamespace } = options;
     // --- Helper Functions ---
+    /**
+     * Sanitize a path component to prevent directory traversal attacks.
+     * Rejects path separators, parent directory references, and other unsafe characters.
+     */ const sanitizePathComponent = (input, componentName)=>{
+        // Reject path separators and parent directory references
+        if (input.includes('/') || input.includes('\\') || input.includes('..')) {
+            throw new ValidationError(`Invalid characters in ${componentName}: cannot contain path separators or ".."`, [
+                {
+                    path: componentName,
+                    message: 'Path component cannot contain path separators or ".."'
+                }
+            ]);
+        }
+        // Reject null bytes and control characters
+        if (input.includes('\0')) {
+            throw new ValidationError(`Invalid characters in ${componentName}: cannot contain null bytes`, [
+                {
+                    path: componentName,
+                    message: 'Path component cannot contain null bytes'
+                }
+            ]);
+        }
+        // Check for control characters (0x00-0x1F and 0x7F)
+        for(let i = 0; i < input.length; i++){
+            const code = input.charCodeAt(i);
+            if (code >= 0 && code <= 0x1F || code === 0x7F) {
+                throw new ValidationError(`Invalid characters in ${componentName}: cannot contain control characters`, [
+                    {
+                        path: componentName,
+                        message: 'Path component cannot contain control characters'
+                    }
+                ]);
+            }
+        }
+        return input;
+    };
+    /**
+     * Verify that a resolved path stays within the basePath to prevent path traversal.
+     */ const verifyPathWithinBase = (resolvedPath)=>{
+        const resolvedBase = path__namespace.resolve(basePath);
+        const resolvedTarget = path__namespace.resolve(resolvedPath);
+        if (!resolvedTarget.startsWith(resolvedBase + path__namespace.sep) && resolvedTarget !== resolvedBase) {
+            throw new StorageAccessError('Path traversal attempt detected');
+        }
+    };
     const getEntityDir = (type, namespace)=>{
         const dirName = registry.getDirectoryName(type);
         if (!dirName) {
             throw new SchemaNotRegisteredError(type);
         }
-        if (namespace) {
-            return path__namespace.join(basePath, namespace, dirName);
+        // Sanitize namespace if provided
+        const safeNamespace = namespace ? sanitizePathComponent(namespace, 'namespace') : undefined;
+        // Sanitize directory name (should already be safe from registry, but double-check)
+        const safeDirName = sanitizePathComponent(dirName, 'directoryName');
+        let dir;
+        if (safeNamespace) {
+            dir = path__namespace.join(basePath, safeNamespace, safeDirName);
+        } else {
+            dir = path__namespace.join(basePath, safeDirName);
         }
-        return path__namespace.join(basePath, dirName);
+        // Verify the path stays within basePath
+        verifyPathWithinBase(dir);
+        return dir;
     };
     const getEntityPath = (type, id, namespace)=>{
-        return path__namespace.join(getEntityDir(type, namespace), `${id}${extension}`);
+        // Sanitize ID to prevent path traversal
+        const safeId = sanitizePathComponent(id, 'id');
+        const dir = getEntityDir(type, namespace);
+        const fullPath = path__namespace.join(dir, `${safeId}${extension}`);
+        // Verify the final path stays within basePath
+        verifyPathWithinBase(fullPath);
+        return fullPath;
     };
     const ensureDir = async (dir)=>{
         if (!node_fs.existsSync(dir) && createIfMissing && !readonly) {
@@ -445,9 +508,17 @@ const createFileSystemProvider = async (options)=>{
             if (!parsed || typeof parsed !== 'object') {
                 return undefined;
             }
+            // Protect against prototype pollution from malicious YAML
+            // Only __proto__ is dangerous - constructor/prototype as string keys are safe
+            const parsedObj = parsed;
+            if (Object.prototype.hasOwnProperty.call(parsedObj, '__proto__')) {
+                // eslint-disable-next-line no-console
+                console.warn(`Potential prototype pollution attempt in ${filePath}: __proto__ key detected`);
+                return undefined;
+            }
             // Validate against registered schema
             const result = registry.validateAs(type, {
-                ...parsed,
+                ...parsedObj,
                 source: filePath
             });
             if (!result.success) {
@@ -672,18 +743,37 @@ const createFileSystemProvider = async (options)=>{
             return namespaces;
         },
         async namespaceExists (namespace) {
-            const namespacePath = path__namespace.join(basePath, namespace);
+            // Sanitize namespace to prevent path traversal
+            const safeNamespace = sanitizePathComponent(namespace, 'namespace');
+            const namespacePath = path__namespace.join(basePath, safeNamespace);
+            // Verify path stays within basePath
+            verifyPathWithinBase(namespacePath);
             return node_fs.existsSync(namespacePath);
         },
         async listTypes (namespace) {
             const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
-            const searchPath = ns ? path__namespace.join(basePath, ns) : basePath;
+            let searchPath;
+            if (ns) {
+                // Sanitize namespace to prevent path traversal
+                const safeNamespace = sanitizePathComponent(ns, 'namespace');
+                searchPath = path__namespace.join(basePath, safeNamespace);
+                verifyPathWithinBase(searchPath);
+            } else {
+                searchPath = basePath;
+            }
             return listDirectoryTypes(searchPath);
         }
     };
     return provider;
 };
 
+/**
+ * Create a deep clone of an entity to prevent external mutation of stored data.
+ * Uses structured clone for proper handling of dates and nested objects.
+ */ const cloneEntity = (entity)=>{
+    // structuredClone handles Date objects properly
+    return structuredClone(entity);
+};
 const createMemoryProvider = (options)=>{
     const { registry, readonly = false, defaultNamespace, initialData = [] } = options;
     // Storage: namespace -> type -> id -> entity
@@ -723,11 +813,14 @@ const createMemoryProvider = (options)=>{
         },
         async get (type, id, namespace) {
             const ns = resolveNamespace(namespace);
-            return getTypeStore(ns, type).get(id);
+            const entity = getTypeStore(ns, type).get(id);
+            // Return a defensive copy to prevent external mutation of stored data
+            return entity ? cloneEntity(entity) : undefined;
         },
         async getAll (type, namespace) {
             const ns = resolveNamespace(namespace);
-            return Array.from(getTypeStore(ns, type).values());
+            // Return defensive copies to prevent external mutation
+            return Array.from(getTypeStore(ns, type).values()).map((e)=>cloneEntity(e));
         },
         async find (filter) {
             var _filter_ids;
@@ -774,8 +867,10 @@ const createMemoryProvider = (options)=>{
                 createdAt: (existing === null || existing === void 0 ? void 0 : existing.createdAt) || now,
                 updatedAt: now
             };
-            getTypeStore(ns, entity.type).set(entity.id, saved);
-            return saved;
+            // Store a cloned copy to prevent external mutation from affecting stored data
+            getTypeStore(ns, entity.type).set(entity.id, cloneEntity(saved));
+            // Return a clone so caller can't mutate stored data through returned reference
+            return cloneEntity(saved);
         },
         async delete (type, id, namespace) {
             if (readonly) {
@@ -861,6 +956,10 @@ const createMemoryProvider = (options)=>{
     return `${baseId}-${Date.now()}`;
 };
 
+/**
+ * Maximum number of entities that can be loaded into memory during search.
+ * Prevents memory exhaustion with large datasets.
+ */ const MAX_SEARCH_ENTITIES = 10000;
 const createSearchEngine = (options)=>{
     const { provider, registry, defaultNamespace } = options;
     const textMatch = (text, query, caseSensitive)=>{
@@ -891,6 +990,23 @@ const createSearchEngine = (options)=>{
         }
         return false;
     };
+    /**
+     * Check if a value looks like an ISO date string.
+     */ const isISODateString = (value)=>{
+        if (typeof value !== 'string') return false;
+        // Match ISO 8601 date format (YAML deserializes dates as ISO strings)
+        return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(value);
+    };
+    /**
+     * Try to parse a value as a Date for comparison.
+     */ const toDateValue = (value)=>{
+        if (value instanceof Date) return value.getTime();
+        if (isISODateString(value)) {
+            const parsed = new Date(value);
+            return isNaN(parsed.getTime()) ? null : parsed.getTime();
+        }
+        return null;
+    };
     const sortEntities = (entities, sort)=>{
         return [
             ...entities
@@ -902,10 +1018,13 @@ const createSearchEngine = (options)=>{
                 if (aVal === undefined || aVal === null) return direction === 'asc' ? 1 : -1;
                 if (bVal === undefined || bVal === null) return direction === 'asc' ? -1 : 1;
                 let cmp;
-                if (typeof aVal === 'string' && typeof bVal === 'string') {
+                // Try date comparison first (handles both Date objects and ISO strings)
+                const aDate = toDateValue(aVal);
+                const bDate = toDateValue(bVal);
+                if (aDate !== null && bDate !== null) {
+                    cmp = aDate - bDate;
+                } else if (typeof aVal === 'string' && typeof bVal === 'string') {
                     cmp = aVal.localeCompare(bVal);
-                } else if (aVal instanceof Date && bVal instanceof Date) {
-                    cmp = aVal.getTime() - bVal.getTime();
                 } else {
                     cmp = aVal < bVal ? -1 : 1;
                 }
@@ -940,6 +1059,10 @@ const createSearchEngine = (options)=>{
                     allEntities = allEntities.concat(entities);
                 }
             }
+            // Check for memory exhaustion risk
+            if (allEntities.length > MAX_SEARCH_ENTITIES) {
+                throw new StorageAccessError(`Search returned too many results (${allEntities.length}). ` + `Please narrow your query by specifying types, namespaces, or search terms. ` + `Maximum allowed: ${MAX_SEARCH_ENTITIES} entities.`);
+            }
             // Apply ID filter
             if (ids === null || ids === void 0 ? void 0 : ids.length) {
                 allEntities = allEntities.filter((e)=>ids.includes(e.id));
@@ -1139,21 +1262,28 @@ function _define_property(obj, key, value) {
     }
     /**
      * Set result limit.
+     * Must be a positive integer (minimum 1).
      */ limit(n) {
-        this.options.limit = n;
+        this.options.limit = Math.max(1, Math.floor(n));
         return this;
     }
     /**
      * Set result offset.
+     * Must be a non-negative integer (minimum 0).
      */ offset(n) {
-        this.options.offset = n;
+        this.options.offset = Math.max(0, Math.floor(n));
         return this;
     }
     /**
      * Set page (calculates offset from limit).
+     * Page numbers are 1-indexed (first page is 1).
      */ page(pageNum, pageSize) {
-        this.options.limit = pageSize;
-        this.options.offset = (pageNum - 1) * pageSize;
+        // Ensure valid page number (minimum 1)
+        const safePage = Math.max(1, Math.floor(pageNum));
+        // Ensure valid page size (minimum 1)
+        const safeSize = Math.max(1, Math.floor(pageSize));
+        this.options.limit = safeSize;
+        this.options.offset = (safePage - 1) * safeSize;
         return this;
     }
     /**
@@ -1382,7 +1512,21 @@ const createDirectoryWalker = (options)=>{
             const discovered = [];
             let currentDir = path__namespace.resolve(startDir);
             let level = 0;
+            const visited = new Set();
             while(level < maxLevels){
+                // Resolve real path to handle symlinks and prevent cycles
+                let realPath;
+                try {
+                    realPath = await fs__namespace.realpath(currentDir);
+                } catch  {
+                    // If realpath fails, use resolved path (may happen with permissions)
+                    realPath = currentDir;
+                }
+                // Check for symlink cycles
+                if (visited.has(realPath)) {
+                    break; // Already visited this real path, prevent infinite loop
+                }
+                visited.add(realPath);
                 const contextDir = path__namespace.join(currentDir, contextDirName);
                 if (node_fs.existsSync(contextDir)) {
                     const { namespaces, types } = await getNamespacesAndTypes(contextDir);
@@ -1477,15 +1621,24 @@ const discoverContextRoot = async (options = {})=>{
     await primaryProvider.initialize();
     const findEntities = async (filter)=>{
         const byId = new Map();
+        // Create a filter without pagination - we'll apply pagination after merging
+        // This prevents double-pagination (sub-providers paginating, then us paginating again)
+        const filterWithoutPagination = {
+            type: filter.type,
+            namespace: filter.namespace,
+            ids: filter.ids,
+            search: filter.search
+        };
         for (const p of [
             ...readProviders
         ].reverse()){
-            const results = await p.find(filter);
+            const results = await p.find(filterWithoutPagination);
             for (const entity of results){
                 byId.set(entity.id, entity);
             }
         }
         let results = Array.from(byId.values());
+        // Apply pagination once, after merging all results
         if (filter.offset) results = results.slice(filter.offset);
         if (filter.limit) results = results.slice(0, filter.limit);
         return results;