148 lines
4.3 KiB
TypeScript
148 lines
4.3 KiB
TypeScript
/**
|
|
* Path Validator - HIGH-2 Remediation
|
|
*
|
|
* Fixes path traversal vulnerabilities by:
|
|
* - Validating all file paths against allowed prefixes
|
|
* - Using path.resolve() for canonicalization
|
|
* - Blocking traversal patterns (../, etc.)
|
|
* - Enforcing path length limits
|
|
*
|
|
* Security Properties:
|
|
* - Path canonicalization
|
|
* - Prefix validation
|
|
* - Symlink resolution (optional)
|
|
* - Traversal pattern detection
|
|
*
|
|
* @module v3/security/path-validator
|
|
*/
|
|
export interface PathValidatorConfig {
|
|
/**
|
|
* Allowed directory prefixes.
|
|
* Paths must start with one of these after resolution.
|
|
*/
|
|
allowedPrefixes: string[];
|
|
/**
|
|
* Blocked file extensions.
|
|
* Files with these extensions are rejected.
|
|
*/
|
|
blockedExtensions?: string[];
|
|
/**
|
|
* Blocked file names.
|
|
* Files matching these names are rejected.
|
|
*/
|
|
blockedNames?: string[];
|
|
/**
|
|
* Maximum path length.
|
|
* Default: 4096 characters
|
|
*/
|
|
maxPathLength?: number;
|
|
/**
|
|
* Whether to resolve symlinks.
|
|
* Default: true
|
|
*/
|
|
resolveSymlinks?: boolean;
|
|
/**
|
|
* Whether to allow paths that don't exist.
|
|
* Default: true (for write operations)
|
|
*/
|
|
allowNonExistent?: boolean;
|
|
/**
|
|
* Whether to allow hidden files/directories.
|
|
* Default: false
|
|
*/
|
|
allowHidden?: boolean;
|
|
}
|
|
export interface PathValidationResult {
|
|
isValid: boolean;
|
|
resolvedPath: string;
|
|
relativePath: string;
|
|
matchedPrefix: string;
|
|
errors: string[];
|
|
}
|
|
export declare class PathValidatorError extends Error {
|
|
readonly code: string;
|
|
readonly path?: string | undefined;
|
|
constructor(message: string, code: string, path?: string | undefined);
|
|
}
|
|
/**
|
|
* Path validator that prevents traversal attacks.
|
|
*
|
|
* This class validates file paths to ensure they stay within
|
|
* allowed directories and don't access sensitive files.
|
|
*
|
|
* @example
|
|
* ```typescript
|
|
* const validator = new PathValidator({
|
|
* allowedPrefixes: ['/workspaces/project']
|
|
* });
|
|
*
|
|
* const result = await validator.validate('/workspaces/project/src/file.ts');
|
|
* if (result.isValid) {
|
|
* // Safe to use result.resolvedPath
|
|
* }
|
|
* ```
|
|
*/
|
|
export declare class PathValidator {
|
|
private readonly config;
|
|
private readonly resolvedPrefixes;
|
|
constructor(config: PathValidatorConfig);
|
|
/**
|
|
* Validates a path against security rules.
|
|
*
|
|
* @param inputPath - The path to validate
|
|
* @returns Validation result with resolved path
|
|
*/
|
|
validate(inputPath: string): Promise<PathValidationResult>;
|
|
/**
|
|
* Validates and returns resolved path, throwing on failure.
|
|
*
|
|
* @param inputPath - The path to validate
|
|
* @returns Resolved path if valid
|
|
* @throws PathValidatorError if validation fails
|
|
*/
|
|
validateOrThrow(inputPath: string): Promise<string>;
|
|
/**
|
|
* Synchronous validation (without symlink resolution).
|
|
*
|
|
* @param inputPath - The path to validate
|
|
* @returns Validation result
|
|
*/
|
|
validateSync(inputPath: string): PathValidationResult;
|
|
/**
|
|
* Securely joins path segments within allowed directories.
|
|
*
|
|
* @param prefix - Base directory (must be in allowedPrefixes)
|
|
* @param segments - Path segments to join
|
|
* @returns Validated resolved path
|
|
*/
|
|
securePath(prefix: string, ...segments: string[]): Promise<string>;
|
|
/**
|
|
* Adds a prefix to the allowed list at runtime.
|
|
*
|
|
* @param prefix - Prefix to add
|
|
*/
|
|
addPrefix(prefix: string): void;
|
|
/**
|
|
* Returns the current allowed prefixes.
|
|
*/
|
|
getAllowedPrefixes(): readonly string[];
|
|
/**
|
|
* Checks if a path is within allowed prefixes (quick check).
|
|
*/
|
|
isWithinAllowed(inputPath: string): boolean;
|
|
}
|
|
/**
|
|
* Factory function to create a path validator for a project directory.
|
|
*
|
|
* @param projectRoot - Root directory of the project
|
|
* @returns Configured PathValidator
|
|
*/
|
|
export declare function createProjectPathValidator(projectRoot: string): PathValidator;
|
|
/**
|
|
* Factory function to create a path validator for the entire project.
|
|
*
|
|
* @param projectRoot - Root directory of the project
|
|
* @returns Configured PathValidator
|
|
*/
|
|
export declare function createFullProjectPathValidator(projectRoot: string): PathValidator;
|
|
//# sourceMappingURL=path-validator.d.ts.map
|