musonda 1.0.0

package/dist/security/fileSandbox.d.ts

@@ -0,0 +1,153 @@
+import { FileSandboxConfig } from '../config/types.js';
+export declare class SandboxSecurityError extends Error {
+    readonly code: string;
+    readonly path?: string;
+    readonly details?: Record<string, any>;
+    constructor(message: string, code?: string, extra?: {
+        path?: string;
+        details?: Record<string, any>;
+    });
+}
+export interface NormalizedSandboxRoot {
+    rawPath: string;
+    resolvedPath: string;
+    readOnly: boolean;
+    description?: string;
+}
+export interface FileEntryInfo {
+    name: string;
+    relativePath: string;
+    isDirectory: boolean;
+    isFile: boolean;
+    sizeBytes: number;
+    modifiedAt: string;
+}
+export interface GrepMatch {
+    file: string;
+    line: number;
+    text: string;
+}
+/**
+ * Match a string against a glob pattern.
+ * Supports `**` (recursive directories), `*` (any chars within path segment), and `?`.
+ */
+export declare function matchGlob(str: string, pattern: string): boolean;
+/**
+ * Check if child is equal to parent or inside parent directory.
+ */
+export declare function isSubPath(child: string, parent: string): boolean;
+/**
+ * Canonical realpath with Windows long-path prefix stripping.
+ */
+export declare function getRealPath(p: string): string;
+export declare class FileSandbox {
+    private config;
+    private normalizedRoots;
+    private defaultRootPath;
+    constructor(config: FileSandboxConfig);
+    private initRoots;
+    getAllowedRoots(): NormalizedSandboxRoot[];
+    getDefaultRootPath(): string;
+    /**
+     * Validate path syntax to block malicious tricks:
+     * - Null bytes
+     * - ASCII control characters
+     * - UNC paths
+     * - Windows Alternate Data Streams (colon in segments)
+     * - Windows reserved device names (CON, PRN, AUX, NUL, COM1-9, LPT1-9)
+     */
+    validatePathSyntax(rawPath: string): void;
+    /**
+     * Validates that a path is fully contained within the allowed sandbox roots,
+     * does not escape via traversal or symlinks, does not match blocked patterns,
+     * and respects permission controls (e.g. readOnly).
+     */
+    validatePath(rawPath: string, operation: 'read' | 'write' | 'delete'): {
+        resolvedPath: string;
+        rootRule: NormalizedSandboxRoot;
+    };
+    readFile(rawPath: string, options?: {
+        encoding?: 'utf-8' | 'base64';
+        startLine?: number;
+        endLine?: number;
+        maxBytes?: number;
+    }): {
+        path: string;
+        content: string;
+        startLine?: number;
+        endLine?: number;
+        totalLines?: number;
+        totalBytes: number;
+        truncated?: boolean;
+    };
+    writeFile(rawPath: string, content: string, options?: {
+        encoding?: 'utf-8' | 'base64';
+        overwrite?: boolean;
+    }): {
+        success: boolean;
+        path: string;
+        bytesWritten: number;
+    };
+    editFile(rawPath: string, target: string, replacement: string, allowMultiple?: boolean): {
+        success: boolean;
+        path: string;
+        occurrencesReplaced: number;
+        bytesWritten: number;
+    };
+    appendFile(rawPath: string, content: string): {
+        success: boolean;
+        path: string;
+        bytesAppended: number;
+    };
+    listFiles(rawPath?: string, options?: {
+        recursive?: boolean;
+        maxDepth?: number;
+    }): {
+        directory: string;
+        totalEntries: number;
+        truncated: boolean;
+        entries: FileEntryInfo[];
+    };
+    deletePath(rawPath: string, recursive?: boolean): {
+        success: boolean;
+        path: string;
+        deleted: boolean;
+    };
+    private verifyNoBlockedFilesInTree;
+    getFileInfo(rawPath: string): {
+        exists: boolean;
+        path: string;
+        isFile?: boolean;
+        isDirectory?: boolean;
+        isSymbolicLink?: boolean;
+        sizeBytes?: number;
+        createdAt?: string;
+        modifiedAt?: string;
+        readOnly?: boolean;
+    };
+    createDirectory(rawPath: string): {
+        success: boolean;
+        path: string;
+        created: boolean;
+    };
+    searchFiles(pattern: string, rawPath?: string, maxResults?: number): {
+        pattern: string;
+        totalMatches: number;
+        truncated: boolean;
+        matches: {
+            name: string;
+            relativePath: string;
+            isDirectory: boolean;
+            sizeBytes: number;
+        }[];
+    };
+    grepFiles(query: string, rawPath?: string, options?: {
+        caseInsensitive?: boolean;
+        maxResults?: number;
+    }): {
+        query: string;
+        totalMatches: number;
+        truncated: boolean;
+        matches: GrepMatch[];
+    };
+}