@riotprompt/riotprompt 0.0.20 → 1.0.0

package/dist/security/path-guard.d.ts

@@ -0,0 +1,161 @@
+import { PathSecurityConfig } from './types';
+import { SecurityAuditLogger } from './audit-logger';
+export type { PathSecurityConfig };
+/**
+ * Result of path validation
+ */
+export interface PathValidationResult {
+    valid: boolean;
+    normalizedPath?: string;
+    error?: string;
+    violation?: string;
+}
+/**
+ * PathGuard provides security validation for file paths.
+ *
+ * Features:
+ * - Directory traversal prevention
+ * - Base path restriction
+ * - Pattern-based blocking
+ * - Null byte detection
+ * - Audit logging
+ *
+ * @example
+ * ```typescript
+ * const guard = new PathGuard({ basePaths: ['/app/data'] });
+ *
+ * const result = guard.validate('../../../etc/passwd');
+ * // { valid: false, error: 'Path contains forbidden pattern' }
+ *
+ * const safePath = guard.validateOrThrow('subdir/file.txt');
+ * // '/app/data/subdir/file.txt'
+ * ```
+ */
+export declare class PathGuard {
+    private config;
+    private auditLogger;
+    private basePaths;
+    constructor(config?: Partial<PathSecurityConfig>, auditLogger?: SecurityAuditLogger);
+    /**
+     * Validate and normalize a file path
+     *
+     * @param inputPath - The path to validate
+     * @param operation - The operation being performed (for audit logging)
+     * @returns Validation result with normalized path if valid
+     */
+    validate(inputPath: string, _operation?: string): PathValidationResult;
+    /**
+     * Validate and return the path, throwing on failure
+     *
+     * @param inputPath - The path to validate
+     * @param operation - The operation being performed
+     * @returns The normalized path
+     * @throws Error if validation fails
+     */
+    validateOrThrow(inputPath: string, operation?: string): string;
+    /**
+     * Add a base path at runtime
+     *
+     * @param basePath - The base path to add
+     */
+    addBasePath(basePath: string): void;
+    /**
+     * Remove a base path
+     *
+     * @param basePath - The base path to remove
+     */
+    removeBasePath(basePath: string): void;
+    /**
+     * Check if a path is within allowed directories
+     *
+     * @param testPath - The path to check
+     * @returns True if the path is within allowed directories
+     */
+    isWithinAllowed(testPath: string): boolean;
+    /**
+     * Get the first base path (for relative resolution)
+     *
+     * @returns The first base path or undefined
+     */
+    getBasePath(): string | undefined;
+    /**
+     * Get all configured base paths
+     *
+     * @returns Array of base paths
+     */
+    getBasePaths(): string[];
+    /**
+     * Check if path validation is enabled
+     *
+     * @returns True if enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Enable or disable path validation
+     *
+     * @param enabled - Whether to enable validation
+     */
+    setEnabled(enabled: boolean): void;
+}
+/**
+ * Get the global PathGuard instance
+ *
+ * @returns The global PathGuard
+ */
+export declare function getPathGuard(): PathGuard;
+/**
+ * Configure the global PathGuard
+ *
+ * @param config - Configuration options
+ */
+export declare function configurePathGuard(config: Partial<PathSecurityConfig>): void;
+/**
+ * Reset the global PathGuard to default
+ */
+export declare function resetPathGuard(): void;
+/**
+ * Sanitize a glob pattern by removing potentially dangerous sequences
+ *
+ * @param pattern - The glob pattern to sanitize
+ * @returns Sanitized glob pattern
+ *
+ * @example
+ * ```typescript
+ * sanitizeGlobPattern('../../../etc/*')  // Returns 'etc/*'
+ * sanitizeGlobPattern('/absolute/path/*') // Returns 'absolute/path/*'
+ * sanitizeGlobPattern('~/secrets/*')      // Returns 'secrets/*'
+ * ```
+ */
+export declare function sanitizeGlobPattern(pattern: string): string;
+/**
+ * Check if a glob pattern is safe to use
+ *
+ * @param pattern - The glob pattern to check
+ * @returns true if safe, false if potentially dangerous
+ *
+ * @example
+ * ```typescript
+ * isGlobSafe('src/**\/*.ts')        // true
+ * isGlobSafe('../../../etc/passwd') // false
+ * isGlobSafe('/etc/*')              // false
+ * ```
+ */
+export declare function isGlobSafe(pattern: string): boolean;
+/**
+ * Result of glob pattern validation
+ */
+export interface GlobValidationResult {
+    safe: boolean;
+    sanitized?: string;
+    warnings: string[];
+}
+/**
+ * Validate and optionally sanitize a glob pattern
+ *
+ * @param pattern - The glob pattern to validate
+ * @param options - Validation options
+ * @returns Validation result with sanitized pattern if requested
+ */
+export declare function validateGlobPattern(pattern: string, options?: {
+    sanitize?: boolean;
+}): GlobValidationResult;

package/dist/security/path-guard.js

@@ -0,0 +1,327 @@
+import path__default from 'path';
+import { getAuditLogger } from './audit-logger.js';
+
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+/**
+ * PathGuard provides security validation for file paths.
+ *
+ * Features:
+ * - Directory traversal prevention
+ * - Base path restriction
+ * - Pattern-based blocking
+ * - Null byte detection
+ * - Audit logging
+ *
+ * @example
+ * ```typescript
+ * const guard = new PathGuard({ basePaths: ['/app/data'] });
+ *
+ * const result = guard.validate('../../../etc/passwd');
+ * // { valid: false, error: 'Path contains forbidden pattern' }
+ *
+ * const safePath = guard.validateOrThrow('subdir/file.txt');
+ * // '/app/data/subdir/file.txt'
+ * ```
+ */ class PathGuard {
+    /**
+     * Validate and normalize a file path
+     *
+     * @param inputPath - The path to validate
+     * @param operation - The operation being performed (for audit logging)
+     * @returns Validation result with normalized path if valid
+     */ validate(inputPath, _operation = 'access') {
+        if (!this.config.enabled) {
+            return {
+                valid: true,
+                normalizedPath: inputPath
+            };
+        }
+        // Check for null bytes (path truncation attack)
+        if (inputPath.includes('\0')) {
+            this.auditLogger.pathTraversalBlocked(inputPath, 'Null byte detected');
+            return {
+                valid: false,
+                error: 'Path contains invalid characters',
+                violation: 'null_byte'
+            };
+        }
+        // Check for denied patterns
+        for (const pattern of this.config.denyPatterns){
+            try {
+                const regex = new RegExp(pattern, 'i');
+                if (regex.test(inputPath)) {
+                    this.auditLogger.pathTraversalBlocked(inputPath, `Matched deny pattern: ${pattern}`);
+                    return {
+                        valid: false,
+                        error: 'Path contains forbidden pattern',
+                        violation: pattern
+                    };
+                }
+            } catch  {
+            // Invalid regex pattern, skip
+            }
+        }
+        // Check absolute path handling
+        const isAbsolute = path__default.isAbsolute(inputPath);
+        if (isAbsolute && !this.config.allowAbsolute) {
+            this.auditLogger.pathTraversalBlocked(inputPath, 'Absolute paths not allowed');
+            return {
+                valid: false,
+                error: 'Absolute paths are not allowed',
+                violation: 'absolute_path'
+            };
+        }
+        // Normalize the path
+        let normalizedPath;
+        try {
+            if (isAbsolute) {
+                normalizedPath = path__default.normalize(inputPath);
+            } else if (this.basePaths.length > 0) {
+                // Resolve relative to first base path
+                normalizedPath = path__default.resolve(this.basePaths[0], inputPath);
+            } else {
+                normalizedPath = path__default.resolve(inputPath);
+            }
+        } catch  {
+            return {
+                valid: false,
+                error: 'Invalid path format'
+            };
+        }
+        // Verify path is within allowed base paths
+        if (this.basePaths.length > 0) {
+            const isWithinBase = this.basePaths.some((basePath)=>normalizedPath.startsWith(basePath + path__default.sep) || normalizedPath === basePath);
+            if (!isWithinBase) {
+                this.auditLogger.pathTraversalBlocked(inputPath, 'Path escapes allowed directories');
+                return {
+                    valid: false,
+                    error: 'Path is outside allowed directories',
+                    violation: 'directory_escape'
+                };
+            }
+        }
+        // Check for path traversal after normalization
+        // Only check if the path is NOT within any allowed base path
+        // (the isWithinBase check above already handles this for absolute paths)
+        return {
+            valid: true,
+            normalizedPath
+        };
+    }
+    /**
+     * Validate and return the path, throwing on failure
+     *
+     * @param inputPath - The path to validate
+     * @param operation - The operation being performed
+     * @returns The normalized path
+     * @throws Error if validation fails
+     */ validateOrThrow(inputPath, operation = 'access') {
+        const result = this.validate(inputPath, operation);
+        if (!result.valid) {
+            throw new Error(`Path validation failed: ${result.error}`);
+        }
+        return result.normalizedPath;
+    }
+    /**
+     * Add a base path at runtime
+     *
+     * @param basePath - The base path to add
+     */ addBasePath(basePath) {
+        const normalized = path__default.resolve(basePath);
+        if (!this.basePaths.includes(normalized)) {
+            this.basePaths.push(normalized);
+        }
+    }
+    /**
+     * Remove a base path
+     *
+     * @param basePath - The base path to remove
+     */ removeBasePath(basePath) {
+        const normalized = path__default.resolve(basePath);
+        const index = this.basePaths.indexOf(normalized);
+        if (index !== -1) {
+            this.basePaths.splice(index, 1);
+        }
+    }
+    /**
+     * Check if a path is within allowed directories
+     *
+     * @param testPath - The path to check
+     * @returns True if the path is within allowed directories
+     */ isWithinAllowed(testPath) {
+        if (this.basePaths.length === 0) return true;
+        const normalizedTest = path__default.resolve(testPath);
+        return this.basePaths.some((basePath)=>normalizedTest.startsWith(basePath + path__default.sep) || normalizedTest === basePath);
+    }
+    /**
+     * Get the first base path (for relative resolution)
+     *
+     * @returns The first base path or undefined
+     */ getBasePath() {
+        return this.basePaths[0];
+    }
+    /**
+     * Get all configured base paths
+     *
+     * @returns Array of base paths
+     */ getBasePaths() {
+        return [
+            ...this.basePaths
+        ];
+    }
+    /**
+     * Check if path validation is enabled
+     *
+     * @returns True if enabled
+     */ isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Enable or disable path validation
+     *
+     * @param enabled - Whether to enable validation
+     */ setEnabled(enabled) {
+        this.config.enabled = enabled;
+    }
+    constructor(config = {}, auditLogger){
+        _define_property(this, "config", void 0);
+        _define_property(this, "auditLogger", void 0);
+        _define_property(this, "basePaths", void 0);
+        this.config = {
+            enabled: true,
+            basePaths: [],
+            allowAbsolute: false,
+            allowSymlinks: false,
+            denyPatterns: [
+                '\\.\\.',
+                '~',
+                '\\$\\{',
+                '\\$\\('
+            ],
+            ...config
+        };
+        // Normalize base paths
+        this.basePaths = this.config.basePaths.map((p)=>path__default.resolve(p));
+        this.auditLogger = auditLogger || getAuditLogger();
+    }
+}
+// Global instance
+let globalPathGuard = null;
+/**
+ * Get the global PathGuard instance
+ *
+ * @returns The global PathGuard
+ */ function getPathGuard() {
+    if (!globalPathGuard) {
+        globalPathGuard = new PathGuard();
+    }
+    return globalPathGuard;
+}
+/**
+ * Configure the global PathGuard
+ *
+ * @param config - Configuration options
+ */ function configurePathGuard(config) {
+    globalPathGuard = new PathGuard(config);
+}
+/**
+ * Reset the global PathGuard to default
+ */ function resetPathGuard() {
+    globalPathGuard = null;
+}
+// ===== GLOB PATTERN SANITIZATION =====
+/**
+ * Dangerous patterns that should not appear in glob patterns
+ */ const DANGEROUS_GLOB_PATTERNS = [
+    /\.\.\//,
+    /\.\.\\/,
+    /^\//,
+    /^[a-zA-Z]:/,
+    /^~/,
+    /\$\{/,
+    /\$\(/,
+    /`/
+];
+/**
+ * Sanitize a glob pattern by removing potentially dangerous sequences
+ * 
+ * @param pattern - The glob pattern to sanitize
+ * @returns Sanitized glob pattern
+ * 
+ * @example
+ * ```typescript
+ * sanitizeGlobPattern('../../../etc/*')  // Returns 'etc/*'
+ * sanitizeGlobPattern('/absolute/path/*') // Returns 'absolute/path/*'
+ * sanitizeGlobPattern('~/secrets/*')      // Returns 'secrets/*'
+ * ```
+ */ function sanitizeGlobPattern(pattern) {
+    let safe = pattern// Remove parent directory references
+    .replace(/\.\.\//g, '').replace(/\.\.\\/g, '')// Remove absolute path starters
+    .replace(/^\/+/, '').replace(/^[a-zA-Z]:[\\/]?/, '')// Remove home directory references
+    .replace(/^~[\\/]?/, '')// Remove variable expansion
+    .replace(/\$\{[^}]*\}/g, '')// Remove command substitution
+    .replace(/\$\([^)]*\)/g, '').replace(/`[^`]*`/g, '');
+    // Remove any remaining dangerous characters at the start
+    while(safe.startsWith('/') || safe.startsWith('\\')){
+        safe = safe.substring(1);
+    }
+    return safe;
+}
+/**
+ * Check if a glob pattern is safe to use
+ * 
+ * @param pattern - The glob pattern to check
+ * @returns true if safe, false if potentially dangerous
+ * 
+ * @example
+ * ```typescript
+ * isGlobSafe('src/**\/*.ts')        // true
+ * isGlobSafe('../../../etc/passwd') // false
+ * isGlobSafe('/etc/*')              // false
+ * ```
+ */ function isGlobSafe(pattern) {
+    return !DANGEROUS_GLOB_PATTERNS.some((re)=>re.test(pattern));
+}
+/**
+ * Validate and optionally sanitize a glob pattern
+ * 
+ * @param pattern - The glob pattern to validate
+ * @param options - Validation options
+ * @returns Validation result with sanitized pattern if requested
+ */ function validateGlobPattern(pattern, options = {}) {
+    const warnings = [];
+    // Check for dangerous patterns
+    for (const dangerousPattern of DANGEROUS_GLOB_PATTERNS){
+        if (dangerousPattern.test(pattern)) {
+            warnings.push(`Pattern contains potentially dangerous sequence: ${dangerousPattern.source}`);
+        }
+    }
+    const safe = warnings.length === 0;
+    if (options.sanitize && !safe) {
+        return {
+            safe: false,
+            sanitized: sanitizeGlobPattern(pattern),
+            warnings
+        };
+    }
+    return {
+        safe,
+        sanitized: safe ? pattern : undefined,
+        warnings
+    };
+}
+
+export { PathGuard, configurePathGuard, getPathGuard, isGlobSafe, resetPathGuard, sanitizeGlobPattern, validateGlobPattern };
+//# sourceMappingURL=path-guard.js.map

package/dist/security/path-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-guard.js","sources":["../../src/security/path-guard.ts"],"sourcesContent":["/**\n * RiotPrompt - Path Security Guard\n *\n * Implements path validation to prevent directory traversal attacks\n * in file operations.\n */\n\nimport path from 'path';\nimport { PathSecurityConfig } from './types';\nimport { getAuditLogger, SecurityAuditLogger } from './audit-logger';\n\n// Re-export PathSecurityConfig for external use\nexport type { PathSecurityConfig };\n\n/**\n * Result of path validation\n */\nexport interface PathValidationResult {\n    valid: boolean;\n    normalizedPath?: string;\n    error?: string;\n    violation?: string;\n}\n\n/**\n * PathGuard provides security validation for file paths.\n *\n * Features:\n * - Directory traversal prevention\n * - Base path restriction\n * - Pattern-based blocking\n * - Null byte detection\n * - Audit logging\n *\n * @example\n * ```typescript\n * const guard = new PathGuard({ basePaths: ['/app/data'] });\n *\n * const result = guard.validate('../../../etc/passwd');\n * // { valid: false, error: 'Path contains forbidden pattern' }\n *\n * const safePath = guard.validateOrThrow('subdir/file.txt');\n * // '/app/data/subdir/file.txt'\n * ```\n */\nexport class PathGuard {\n    private config: PathSecurityConfig;\n    private auditLogger: SecurityAuditLogger;\n    private basePaths: string[];\n\n    constructor(config: Partial<PathSecurityConfig> = {}, auditLogger?: SecurityAuditLogger) {\n        this.config = {\n            enabled: true,\n            basePaths: [],\n            allowAbsolute: false,\n            allowSymlinks: false,\n            denyPatterns: [\n                '\\\\.\\\\.',        // Parent directory\n                '~',             // Home directory expansion\n                '\\\\$\\\\{',        // Variable expansion\n                '\\\\$\\\\(',        // Command substitution\n            ],\n            ...config,\n        };\n\n        // Normalize base paths\n        this.basePaths = this.config.basePaths.map(p => path.resolve(p));\n        this.auditLogger = auditLogger || getAuditLogger();\n    }\n\n    /**\n     * Validate and normalize a file path\n     *\n     * @param inputPath - The path to validate\n     * @param operation - The operation being performed (for audit logging)\n     * @returns Validation result with normalized path if valid\n     */\n    validate(inputPath: string, _operation: string = 'access'): PathValidationResult {\n        if (!this.config.enabled) {\n            return { valid: true, normalizedPath: inputPath };\n        }\n\n        // Check for null bytes (path truncation attack)\n        if (inputPath.includes('\\0')) {\n            this.auditLogger.pathTraversalBlocked(inputPath, 'Null byte detected');\n            return {\n                valid: false,\n                error: 'Path contains invalid characters',\n                violation: 'null_byte',\n            };\n        }\n\n        // Check for denied patterns\n        for (const pattern of this.config.denyPatterns) {\n            try {\n                const regex = new RegExp(pattern, 'i');\n                if (regex.test(inputPath)) {\n                    this.auditLogger.pathTraversalBlocked(inputPath, `Matched deny pattern: ${pattern}`);\n                    return {\n                        valid: false,\n                        error: 'Path contains forbidden pattern',\n                        violation: pattern,\n                    };\n                }\n            } catch {\n                // Invalid regex pattern, skip\n            }\n        }\n\n        // Check absolute path handling\n        const isAbsolute = path.isAbsolute(inputPath);\n        if (isAbsolute && !this.config.allowAbsolute) {\n            this.auditLogger.pathTraversalBlocked(inputPath, 'Absolute paths not allowed');\n            return {\n                valid: false,\n                error: 'Absolute paths are not allowed',\n                violation: 'absolute_path',\n            };\n        }\n\n        // Normalize the path\n        let normalizedPath: string;\n        try {\n            if (isAbsolute) {\n                normalizedPath = path.normalize(inputPath);\n            } else if (this.basePaths.length > 0) {\n                // Resolve relative to first base path\n                normalizedPath = path.resolve(this.basePaths[0], inputPath);\n            } else {\n                normalizedPath = path.resolve(inputPath);\n            }\n        } catch {\n            return {\n                valid: false,\n                error: 'Invalid path format',\n            };\n        }\n\n        // Verify path is within allowed base paths\n        if (this.basePaths.length > 0) {\n            const isWithinBase = this.basePaths.some(basePath =>\n                normalizedPath.startsWith(basePath + path.sep) || normalizedPath === basePath\n            );\n\n            if (!isWithinBase) {\n                this.auditLogger.pathTraversalBlocked(inputPath, 'Path escapes allowed directories');\n                return {\n                    valid: false,\n                    error: 'Path is outside allowed directories',\n                    violation: 'directory_escape',\n                };\n            }\n        }\n\n        // Check for path traversal after normalization\n        // Only check if the path is NOT within any allowed base path\n        // (the isWithinBase check above already handles this for absolute paths)\n\n        return {\n            valid: true,\n            normalizedPath,\n        };\n    }\n\n    /**\n     * Validate and return the path, throwing on failure\n     *\n     * @param inputPath - The path to validate\n     * @param operation - The operation being performed\n     * @returns The normalized path\n     * @throws Error if validation fails\n     */\n    validateOrThrow(inputPath: string, operation: string = 'access'): string {\n        const result = this.validate(inputPath, operation);\n        if (!result.valid) {\n            throw new Error(`Path validation failed: ${result.error}`);\n        }\n        return result.normalizedPath!;\n    }\n\n    /**\n     * Add a base path at runtime\n     *\n     * @param basePath - The base path to add\n     */\n    addBasePath(basePath: string): void {\n        const normalized = path.resolve(basePath);\n        if (!this.basePaths.includes(normalized)) {\n            this.basePaths.push(normalized);\n        }\n    }\n\n    /**\n     * Remove a base path\n     *\n     * @param basePath - The base path to remove\n     */\n    removeBasePath(basePath: string): void {\n        const normalized = path.resolve(basePath);\n        const index = this.basePaths.indexOf(normalized);\n        if (index !== -1) {\n            this.basePaths.splice(index, 1);\n        }\n    }\n\n    /**\n     * Check if a path is within allowed directories\n     *\n     * @param testPath - The path to check\n     * @returns True if the path is within allowed directories\n     */\n    isWithinAllowed(testPath: string): boolean {\n        if (this.basePaths.length === 0) return true;\n\n        const normalizedTest = path.resolve(testPath);\n        return this.basePaths.some(basePath =>\n            normalizedTest.startsWith(basePath + path.sep) || normalizedTest === basePath\n        );\n    }\n\n    /**\n     * Get the first base path (for relative resolution)\n     *\n     * @returns The first base path or undefined\n     */\n    getBasePath(): string | undefined {\n        return this.basePaths[0];\n    }\n\n    /**\n     * Get all configured base paths\n     *\n     * @returns Array of base paths\n     */\n    getBasePaths(): string[] {\n        return [...this.basePaths];\n    }\n\n    /**\n     * Check if path validation is enabled\n     *\n     * @returns True if enabled\n     */\n    isEnabled(): boolean {\n        return this.config.enabled;\n    }\n\n    /**\n     * Enable or disable path validation\n     *\n     * @param enabled - Whether to enable validation\n     */\n    setEnabled(enabled: boolean): void {\n        this.config.enabled = enabled;\n    }\n}\n\n// Global instance\nlet globalPathGuard: PathGuard | null = null;\n\n/**\n * Get the global PathGuard instance\n *\n * @returns The global PathGuard\n */\nexport function getPathGuard(): PathGuard {\n    if (!globalPathGuard) {\n        globalPathGuard = new PathGuard();\n    }\n    return globalPathGuard;\n}\n\n/**\n * Configure the global PathGuard\n *\n * @param config - Configuration options\n */\nexport function configurePathGuard(config: Partial<PathSecurityConfig>): void {\n    globalPathGuard = new PathGuard(config);\n}\n\n/**\n * Reset the global PathGuard to default\n */\nexport function resetPathGuard(): void {\n    globalPathGuard = null;\n}\n\n// ===== GLOB PATTERN SANITIZATION =====\n\n/**\n * Dangerous patterns that should not appear in glob patterns\n */\nconst DANGEROUS_GLOB_PATTERNS = [\n    /\\.\\.\\//,           // Parent directory traversal\n    /\\.\\.\\\\/,           // Windows parent directory\n    /^\\//,              // Absolute path (Unix)\n    /^[a-zA-Z]:/,       // Absolute path (Windows)\n    /^~/,               // Home directory\n    /\\$\\{/,             // Variable expansion\n    /\\$\\(/,             // Command substitution\n    /`/,                // Backtick command substitution\n];\n\n/**\n * Sanitize a glob pattern by removing potentially dangerous sequences\n * \n * @param pattern - The glob pattern to sanitize\n * @returns Sanitized glob pattern\n * \n * @example\n * ```typescript\n * sanitizeGlobPattern('../../../etc/*')  // Returns 'etc/*'\n * sanitizeGlobPattern('/absolute/path/*') // Returns 'absolute/path/*'\n * sanitizeGlobPattern('~/secrets/*')      // Returns 'secrets/*'\n * ```\n */\nexport function sanitizeGlobPattern(pattern: string): string {\n    let safe = pattern\n        // Remove parent directory references\n        .replace(/\\.\\.\\//g, '')\n        .replace(/\\.\\.\\\\/g, '')\n        // Remove absolute path starters\n        .replace(/^\\/+/, '')\n        .replace(/^[a-zA-Z]:[\\\\/]?/, '')\n        // Remove home directory references\n        .replace(/^~[\\\\/]?/, '')\n        // Remove variable expansion\n        .replace(/\\$\\{[^}]*\\}/g, '')\n        // Remove command substitution\n        .replace(/\\$\\([^)]*\\)/g, '')\n        .replace(/`[^`]*`/g, '');\n\n    // Remove any remaining dangerous characters at the start\n    while (safe.startsWith('/') || safe.startsWith('\\\\')) {\n        safe = safe.substring(1);\n    }\n\n    return safe;\n}\n\n/**\n * Check if a glob pattern is safe to use\n * \n * @param pattern - The glob pattern to check\n * @returns true if safe, false if potentially dangerous\n * \n * @example\n * ```typescript\n * isGlobSafe('src/**\\/*.ts')        // true\n * isGlobSafe('../../../etc/passwd') // false\n * isGlobSafe('/etc/*')              // false\n * ```\n */\nexport function isGlobSafe(pattern: string): boolean {\n    return !DANGEROUS_GLOB_PATTERNS.some(re => re.test(pattern));\n}\n\n/**\n * Result of glob pattern validation\n */\nexport interface GlobValidationResult {\n    safe: boolean;\n    sanitized?: string;\n    warnings: string[];\n}\n\n/**\n * Validate and optionally sanitize a glob pattern\n * \n * @param pattern - The glob pattern to validate\n * @param options - Validation options\n * @returns Validation result with sanitized pattern if requested\n */\nexport function validateGlobPattern(\n    pattern: string,\n    options: { sanitize?: boolean } = {}\n): GlobValidationResult {\n    const warnings: string[] = [];\n\n    // Check for dangerous patterns\n    for (const dangerousPattern of DANGEROUS_GLOB_PATTERNS) {\n        if (dangerousPattern.test(pattern)) {\n            warnings.push(`Pattern contains potentially dangerous sequence: ${dangerousPattern.source}`);\n        }\n    }\n\n    const safe = warnings.length === 0;\n\n    if (options.sanitize && !safe) {\n        return {\n            safe: false,\n            sanitized: sanitizeGlobPattern(pattern),\n            warnings,\n        };\n    }\n\n    return {\n        safe,\n        sanitized: safe ? pattern : undefined,\n        warnings,\n    };\n}\n\n"],"names":["PathGuard","validate","inputPath","_operation","config","enabled","valid","normalizedPath","includes","auditLogger","pathTraversalBlocked","error","violation","pattern","denyPatterns","regex","RegExp","test","isAbsolute","path","allowAbsolute","normalize","basePaths","length","resolve","isWithinBase","some","basePath","startsWith","sep","validateOrThrow","operation","result","Error","addBasePath","normalized","push","removeBasePath","index","indexOf","splice","isWithinAllowed","testPath","normalizedTest","getBasePath","getBasePaths","isEnabled","setEnabled","allowSymlinks","map","p","getAuditLogger","globalPathGuard","getPathGuard","configurePathGuard","resetPathGuard","DANGEROUS_GLOB_PATTERNS","sanitizeGlobPattern","safe","replace","substring","isGlobSafe","re","validateGlobPattern","options","warnings","dangerousPattern","source","sanitize","sanitized","undefined"],"mappings":"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"}

package/dist/security/rate-limiter.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Rate Limiter Interfaces
+ *
+ * Provides interfaces and basic implementations for rate limiting.
+ * Production applications should use dedicated rate limiting libraries
+ * (e.g., rate-limiter-flexible, express-rate-limit) for distributed systems.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Rate limiter interface
+ * Implementation is left to users (use your preferred library)
+ */
+export interface RateLimiter {
+    /**
+     * Check if request is allowed
+     * @param key - Unique identifier for the rate limit bucket (e.g., user ID, IP)
+     * @returns true if allowed, false if rate limited
+     */
+    check(key: string): Promise<boolean>;
+    /**
+     * Get remaining requests in the current window
+     * @param key - Unique identifier for the rate limit bucket
+     * @returns Number of remaining requests
+     */
+    remaining(key: string): Promise<number>;
+    /**
+     * Reset rate limit for a key
+     * @param key - Unique identifier for the rate limit bucket
+     */
+    reset(key: string): Promise<void>;
+}
+/**
+ * Rate limiter configuration
+ */
+export interface RateLimiterConfig {
+    /** Time window in milliseconds */
+    windowMs: number;
+    /** Maximum requests allowed in the window */
+    maxRequests: number;
+    /** Optional function to generate keys from context */
+    keyGenerator?: (context: unknown) => string;
+}
+/**
+ * No-op rate limiter that always allows requests
+ * Use this as a default when rate limiting is not needed
+ */
+export declare class NoOpRateLimiter implements RateLimiter {
+    check(_key: string): Promise<boolean>;
+    remaining(_key: string): Promise<number>;
+    reset(_key: string): Promise<void>;
+}
+/**
+ * Simple in-memory rate limiter
+ *
+ * **Warning**: This implementation is NOT suitable for production use in
+ * distributed systems. Use a Redis-backed solution for production.
+ *
+ * @example
+ * ```typescript
+ * const limiter = new MemoryRateLimiter({
+ *   windowMs: 60000,  // 1 minute
+ *   maxRequests: 100, // 100 requests per minute
+ * });
+ *
+ * if (await limiter.check('user-123')) {
+ *   // Process request
+ * } else {
+ *   // Rate limited
+ * }
+ * ```
+ */
+export declare class MemoryRateLimiter implements RateLimiter {
+    private requests;
+    private config;
+    private cleanupInterval;
+    constructor(config: RateLimiterConfig);
+    check(key: string): Promise<boolean>;
+    remaining(key: string): Promise<number>;
+    reset(key: string): Promise<void>;
+    /**
+     * Clean up expired entries to prevent memory leaks
+     */
+    private cleanup;
+    /**
+     * Stop the cleanup interval (call when done with the limiter)
+     */
+    destroy(): void;
+}
+/**
+ * Create a rate limiter with the given configuration
+ *
+ * @param config - Rate limiter configuration
+ * @returns Rate limiter instance
+ */
+export declare function createRateLimiter(config: RateLimiterConfig): RateLimiter;
+/**
+ * Create a no-op rate limiter that always allows requests
+ *
+ * @returns No-op rate limiter instance
+ */
+export declare function createNoOpRateLimiter(): RateLimiter;
+/**
+ * Get the global rate limiter instance
+ * Returns a no-op limiter if not configured
+ */
+export declare function getRateLimiter(): RateLimiter;
+/**
+ * Configure the global rate limiter
+ *
+ * @param config - Rate limiter configuration
+ */
+export declare function configureRateLimiter(config: RateLimiterConfig): void;
+/**
+ * Reset the global rate limiter to the default no-op implementation
+ */
+export declare function resetRateLimiter(): void;