@utilarium/cardigantime 0.0.24-dev.0

package/dist/security/profiles.d.ts

@@ -0,0 +1,127 @@
+import { SecurityValidationConfig, SecurityProfile } from './types';
+/**
+ * Profile presets for common scenarios.
+ */
+export declare const SECURITY_PROFILES: Record<SecurityProfile, SecurityValidationConfig>;
+/**
+ * Environment-based profile detection.
+ */
+export declare function detectProfile(): SecurityProfile;
+/**
+ * Get security configuration for a profile.
+ */
+export declare function getProfileConfig(profile: SecurityProfile): SecurityValidationConfig;
+/**
+ * Profile builder for custom configurations.
+ */
+export declare class SecurityProfileBuilder {
+    private config;
+    constructor(baseProfile?: 'development' | 'production');
+    /**
+   * Enable fail-fast mode (throw on first error).
+   */
+    failFast(enabled?: boolean): this;
+    /**
+   * Enable audit logging.
+   */
+    withAuditLogging(enabled?: boolean): this;
+    /**
+   * Set path security options.
+   */
+    withPathSecurity(options: Partial<SecurityValidationConfig['paths']>): this;
+    /**
+   * Set numeric security options.
+   */
+    withNumericSecurity(options: Partial<SecurityValidationConfig['numbers']>): this;
+    /**
+   * Set string security options.
+   */
+    withStringSecurity(options: Partial<SecurityValidationConfig['strings']>): this;
+    /**
+   * Restrict paths to specific base directories.
+   */
+    restrictPathsTo(directories: string[]): this;
+    /**
+   * Allow only specific file extensions.
+   */
+    allowExtensions(extensions: string[]): this;
+    /**
+   * Require explicit numeric bounds.
+   */
+    requireNumericBounds(required?: boolean): this;
+    /**
+   * Set maximum string length.
+   */
+    maxStringLength(length: number): this;
+    /**
+   * Create production-like profile with specific overrides.
+   */
+    productionLike(overrides?: Partial<SecurityValidationConfig>): this;
+    /**
+   * Build the final configuration.
+   */
+    build(): SecurityValidationConfig;
+}
+/**
+ * Create a custom security profile.
+ */
+export declare function createProfile(base?: 'development' | 'production'): SecurityProfileBuilder;
+/**
+ * Preset profiles for common scenarios.
+ */
+export declare const presets: {
+    /**
+   * Local development with warnings only.
+   */
+    localDevelopment: () => SecurityValidationConfig;
+    /**
+   * CI/CD testing with strict validation but detailed errors.
+   */
+    testing: () => SecurityValidationConfig;
+    /**
+   * Production deployment with maximum security.
+   */
+    productionDeployment: () => SecurityValidationConfig;
+    /**
+   * Library usage (embedded in other applications).
+   */
+    libraryMode: () => SecurityValidationConfig;
+    /**
+   * Config file only (no CLI, just validating config files).
+   */
+    configFileOnly: () => SecurityValidationConfig;
+};
+/**
+ * Runtime profile switching support.
+ */
+export declare class ProfileManager {
+    private currentProfile;
+    private currentConfig;
+    private listeners;
+    constructor(initialProfile?: SecurityProfile);
+    /**
+   * Get current profile.
+   */
+    getProfile(): SecurityProfile;
+    /**
+   * Get current configuration.
+   */
+    getConfig(): SecurityValidationConfig;
+    /**
+   * Switch to a different profile.
+   */
+    switchProfile(profile: SecurityProfile): void;
+    /**
+   * Apply a custom configuration.
+   */
+    applyCustomConfig(config: SecurityValidationConfig): void;
+    /**
+   * Subscribe to profile changes.
+   */
+    onProfileChange(listener: (profile: SecurityProfile, config: SecurityValidationConfig) => void): () => void;
+    private notifyListeners;
+}
+/**
+ * Get the global profile manager.
+ */
+export declare function getProfileManager(): ProfileManager;

package/dist/security/security-validator.d.ts

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { ConfigValueSource } from './config-validator';
+import { SecurityValidationConfig, SecurityValidationResult, SecurityValidationError, SecurityProfile } from './types';
+import { Logger } from '../types';
+/**
+ * Aggregated validation result from all sources.
+ */
+export interface AggregatedValidationResult {
+    /** Overall validation status */
+    valid: boolean;
+    /** All errors from all sources */
+    errors: SecurityValidationError[];
+    /** All warnings from all sources */
+    warnings: SecurityValidationResult['warnings'];
+    /** Results by source */
+    bySource: {
+        cli?: SecurityValidationResult;
+        config?: SecurityValidationResult;
+        defaults?: SecurityValidationResult;
+    };
+}
+/**
+ * SecurityValidator provides unified security validation across all input sources.
+ */
+export declare class SecurityValidator {
+    private config;
+    private cliValidator;
+    private configValidator;
+    private pathGuard;
+    private numericGuard;
+    private stringGuard;
+    private logger?;
+    private schemaRegistered;
+    constructor(config?: Partial<SecurityValidationConfig>, logger?: Logger);
+    /**
+   * Register a Zod schema for validation.
+   * Extracts security metadata and configures both CLI and config validators.
+   */
+    registerSchema<T extends z.ZodRawShape>(schema: z.ZodObject<T>): this;
+    /**
+   * Check if a schema has been registered.
+   */
+    hasSchema(): boolean;
+    /**
+   * Validate CLI arguments.
+   */
+    validateCLI(args: Record<string, unknown>): SecurityValidationResult;
+    /**
+   * Validate configuration file content.
+   */
+    validateConfig(config: Record<string, unknown>, sources?: Map<string, ConfigValueSource>): SecurityValidationResult;
+    /**
+   * Validate a single config file before merging.
+   */
+    validateConfigFile(content: Record<string, unknown>, filePath: string, level?: number): SecurityValidationResult;
+    /**
+   * Validate the merged configuration (CLI + config file + defaults).
+   * This is the main entry point for validation after all merging is complete.
+   */
+    validateMerged(merged: Record<string, unknown>, cliArgs: Record<string, unknown>, configValues: Record<string, unknown>, configSources?: Map<string, ConfigValueSource>): AggregatedValidationResult;
+    /**
+   * Validate a single value (for ad-hoc validation).
+   */
+    validateValue(value: unknown, type: 'path' | 'number' | 'string', options?: {
+        fieldName?: string;
+        bounds?: {
+            min: number;
+            max: number;
+            integer?: boolean;
+        };
+        pattern?: RegExp;
+    }): void;
+    /**
+   * Get the current security profile.
+   */
+    getProfile(): SecurityProfile;
+    /**
+   * Check if security validation should fail on errors.
+   */
+    shouldFailOnError(): boolean;
+    /**
+   * Perform cross-source validation (detect conflicts, suspicious patterns).
+   */
+    private validateCrossSources;
+    /**
+   * Check for suspicious patterns in configuration.
+   */
+    private checkSuspiciousPatterns;
+    /**
+   * Walk an object recursively.
+   */
+    private walkObject;
+    /**
+   * Log validation result.
+   */
+    private logResult;
+    /**
+   * Log aggregated validation result.
+   */
+    private logAggregatedResult;
+}
+/**
+ * Create a security validator.
+ */
+export declare function createSecurityValidator(config?: Partial<SecurityValidationConfig>, logger?: Logger): SecurityValidator;
+/**
+ * Create a security validator for a specific profile.
+ */
+export declare function createSecurityValidatorForProfile(profile: 'development' | 'production', logger?: Logger): SecurityValidator;

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

@@ -0,0 +1,92 @@
+import { StringSecurityOptions } from './types';
+/**
+ * Common patterns for security-sensitive strings.
+ */
+export declare const SAFE_PATTERNS: {
+    /** Model names: alphanumeric with hyphens, dots, colons, slashes */
+    readonly modelName: RegExp;
+    /** Identifiers: alphanumeric with underscores */
+    readonly identifier: RegExp;
+    /** Environment variable names */
+    readonly envVar: RegExp;
+    /** Slugs: lowercase alphanumeric with hyphens */
+    readonly slug: RegExp;
+    /** Semantic version */
+    readonly semver: RegExp;
+    /** Safe filename (no path separators) */
+    readonly filename: RegExp;
+    /** Email (basic validation) */
+    readonly email: RegExp;
+    /** URL (http/https only) */
+    readonly httpUrl: RegExp;
+};
+/**
+ * StringGuard provides secure string validation.
+ */
+export declare class StringGuard {
+    private options;
+    constructor(options?: Partial<StringSecurityOptions>);
+    /**
+   * Validate a string value against security constraints.
+   *
+   * @param value - The string to validate
+   * @param constraints - Validation constraints
+   * @param fieldName - Field name for error messages
+   * @returns The validated string
+   * @throws Error if validation fails
+   */
+    validate(value: unknown, constraints?: {
+        minLength?: number;
+        maxLength?: number;
+        pattern?: RegExp;
+        patternName?: string;
+        allowedValues?: string[];
+        blockShellMeta?: boolean;
+        trim?: boolean;
+    }, fieldName?: string): string;
+    /**
+   * Validate using a predefined safe pattern.
+   */
+    validatePattern(value: unknown, patternName: keyof typeof SAFE_PATTERNS, fieldName?: string, additionalConstraints?: {
+        minLength?: number;
+        maxLength?: number;
+    }): string;
+    /**
+   * Validate a model name (e.g., "gpt-4o", "claude-3-opus-20240229").
+   */
+    validateModelName(value: unknown, fieldName?: string): string;
+    /**
+   * Validate an identifier (variable name, etc.).
+   */
+    validateIdentifier(value: unknown, fieldName?: string): string;
+    /**
+   * Validate a filename (no path separators).
+   */
+    validateFilename(value: unknown, fieldName?: string): string;
+    /**
+   * Validate an enum-like string value.
+   */
+    validateEnum<T extends string>(value: unknown, allowedValues: readonly T[], fieldName: string, options?: {
+        caseSensitive?: boolean;
+    }): T;
+    /**
+   * Sanitize a string by removing dangerous characters (for logging, etc.).
+   */
+    sanitize(value: string, maxLength?: number): string;
+    /**
+   * Check if a string appears to contain injection attempts.
+   */
+    detectInjection(value: string): {
+        suspicious: boolean;
+        reason?: string;
+    };
+    private createError;
+}
+/**
+ * Get the default StringGuard instance.
+ */
+export declare function getStringGuard(): StringGuard;
+/**
+ * Create a new StringGuard with custom options.
+ */
+export declare function createStringGuard(options: Partial<StringSecurityOptions>): StringGuard;

package/dist/security/types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Security profile levels that determine validation strictness.
+ */
+export type SecurityProfile = 'development' | 'production' | 'custom';
+/**
+ * Path security configuration options.
+ */
+export interface PathSecurityOptions {
+    /** Allowed base directories for path resolution */
+    allowedBaseDirs?: string[];
+    /** Maximum path length in characters */
+    maxPathLength?: number;
+    /** Allowed file extensions (e.g., ['.yaml', '.json']) */
+    allowedExtensions?: string[];
+    /** Whether to allow hidden files (dotfiles) */
+    allowHiddenFiles?: boolean;
+    /** Whether to resolve and validate symlinks */
+    validateSymlinks?: boolean;
+    /** Whether to allow absolute paths */
+    allowAbsolutePaths?: boolean;
+}
+/**
+ * Numeric security configuration options.
+ */
+export interface NumericSecurityOptions {
+    /** Whether to require explicit min/max bounds */
+    requireBounds?: boolean;
+    /** Default minimum value if not specified */
+    defaultMin?: number;
+    /** Default maximum value if not specified */
+    defaultMax?: number;
+    /** Whether to allow NaN values */
+    allowNaN?: boolean;
+    /** Whether to allow Infinity values */
+    allowInfinity?: boolean;
+}
+/**
+ * String security configuration options.
+ */
+export interface StringSecurityOptions {
+    /** Maximum string length */
+    maxLength?: number;
+    /** Whether to allow null bytes */
+    allowNullBytes?: boolean;
+    /** Whether to allow control characters */
+    allowControlChars?: boolean;
+    /** Default pattern for validation */
+    defaultPattern?: RegExp;
+}
+/**
+ * Complete security validation configuration.
+ */
+export interface SecurityValidationConfig {
+    /** Security profile to use */
+    profile: SecurityProfile;
+    /** Path security settings */
+    paths: PathSecurityOptions;
+    /** Numeric security settings */
+    numbers: NumericSecurityOptions;
+    /** Strings security settings */
+    strings: StringSecurityOptions;
+    /** Whether validation failures should throw or warn */
+    failOnError: boolean;
+    /** Whether to log security events */
+    auditLogging: boolean;
+}
+/**
+ * Field-level security metadata that can be attached to schema fields.
+ */
+export interface SecureFieldOptions {
+    /** Whether this field contains a path */
+    isPath?: boolean;
+    /** Path security options for this specific field */
+    pathOptions?: PathSecurityOptions;
+    /** Whether this field should be treated as sensitive */
+    sensitive?: boolean;
+    /** Custom validation function */
+    customValidator?: (value: unknown) => boolean | string;
+}
+/**
+ * Result of a security validation operation.
+ */
+export interface SecurityValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Validation errors if any */
+    errors: SecurityValidationError[];
+    /** Warnings (used in development profile) */
+    warnings: SecurityValidationWarning[];
+    /** Source of the validated value */
+    source: 'cli' | 'config' | 'default' | 'unknown';
+}
+/**
+ * Security validation error details.
+ */
+export interface SecurityValidationError {
+    /** Field path in dot notation */
+    field: string;
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: SecurityErrorCode;
+    /** The invalid value (sanitized) */
+    value?: string;
+    /** Source of the invalid value */
+    source: 'cli' | 'config' | 'default' | 'unknown';
+}
+/**
+ * Security validation warning (non-fatal in development mode).
+ */
+export interface SecurityValidationWarning {
+    /** Field path in dot notation */
+    field: string;
+    /** Warning message */
+    message: string;
+    /** Warning code */
+    code: SecurityWarningCode;
+}
+/**
+ * Error codes for security validation failures.
+ */
+export type SecurityErrorCode = 'PATH_TRAVERSAL' | 'PATH_TOO_LONG' | 'PATH_INVALID_EXTENSION' | 'PATH_HIDDEN_FILE' | 'PATH_SYMLINK_ESCAPE' | 'PATH_OUTSIDE_ALLOWED' | 'PATH_ABSOLUTE_NOT_ALLOWED' | 'NUMBER_OUT_OF_RANGE' | 'NUMBER_NAN' | 'NUMBER_INFINITY' | 'NUMBER_MISSING_BOUNDS' | 'STRING_TOO_LONG' | 'STRING_NULL_BYTE' | 'STRING_CONTROL_CHAR' | 'STRING_PATTERN_MISMATCH' | 'VALIDATION_FAILED';
+/**
+ * Warning codes for security validation.
+ */
+export type SecurityWarningCode = 'MISSING_PATH_BOUNDS' | 'MISSING_NUMERIC_BOUNDS' | 'PERMISSIVE_PATTERN' | 'DEVELOPMENT_MODE';

package/dist/security/zod-secure-enum.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+/**
+ * Create a Zod schema for secure enum validation.
+ * Unlike z.enum(), this provides better error messages and case handling.
+ *
+ * @param values - Allowed enum values
+ * @param options - Enum options
+ * @returns Zod enum schema with security refinements
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   logLevel: secureEnum(['debug', 'info', 'warn', 'error']),
+ *   format: secureEnum(['json', 'yaml', 'xml'], { caseSensitive: false }),
+ * });
+ * ```
+ */
+export declare function secureEnum<T extends string>(values: readonly [T, ...T[]], options?: {
+    caseSensitive?: boolean;
+}): z.ZodPipe<z.ZodString, z.ZodTransform<Awaited<T>, string>> | z.ZodEnum<{ [k_1 in T]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>;

package/dist/security/zod-secure-number.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { NumericSecurityOptions } from './types';
+/**
+ * Create a Zod schema for secure numeric validation with required bounds.
+ *
+ * @param min - Minimum allowed value (required in production)
+ * @param max - Maximum allowed value (required in production)
+ * @param options - Additional numeric security options
+ * @returns Zod number schema with security refinements
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   timeout: secureNumber(100, 60000, { integer: true }),
+ *   temperature: secureNumber(0, 1),
+ * });
+ * ```
+ */
+export declare function secureNumber(min: number, max: number, options?: Partial<NumericSecurityOptions> & {
+    integer?: boolean;
+}): z.ZodNumber;
+/**
+ * Create a Zod schema for a port number (1-65535).
+ */
+export declare function securePort(): z.ZodNumber;
+/**
+ * Create a Zod schema for a timeout in milliseconds.
+ * @param maxMs - Maximum timeout in milliseconds (default: 5 minutes)
+ */
+export declare function secureTimeout(maxMs?: number): z.ZodNumber;
+/**
+ * Create a Zod schema for a percentage (0-100).
+ */
+export declare function securePercentage(): z.ZodNumber;
+/**
+ * Create a Zod schema for a retry count.
+ * @param maxRetries - Maximum retries allowed (default: 10)
+ */
+export declare function secureRetryCount(maxRetries?: number): z.ZodNumber;

package/dist/security/zod-secure-path.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { PathSecurityOptions } from './types';
+/**
+ * Create a Zod schema for secure path validation.
+ *
+ * @param options - Path security options
+ * @returns Zod string schema with path security refinements
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   configFile: securePath({
+ *     allowedExtensions: ['.yaml', '.json'],
+ *     maxPathLength: 200
+ *   }),
+ * });
+ * ```
+ */
+export declare function securePath(options?: Partial<PathSecurityOptions>): z.ZodString;
+/**
+ * Create a Zod schema for secure directory path validation.
+ * Same as securePath but with directory-specific defaults.
+ */
+export declare function secureDirectory(options?: Partial<PathSecurityOptions>): z.ZodString;

package/dist/security/zod-secure-string.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { StringSecurityOptions } from './types';
+/**
+ * Create a Zod schema for secure string validation.
+ *
+ * @param options - String security options
+ * @returns Zod string schema with security refinements
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   apiKey: secureString({ minLength: 20, maxLength: 100 }),
+ *   model: secureString({ pattern: /^[a-z0-9-]+$/i }),
+ * });
+ * ```
+ */
+export declare function secureString(options?: Partial<StringSecurityOptions> & {
+    minLength?: number;
+    pattern?: RegExp;
+}): z.ZodString;
+/**
+ * Create a Zod schema for model names (e.g., "gpt-4o", "claude-3-opus").
+ */
+export declare function secureModelName(): z.ZodString;
+/**
+ * Create a Zod schema for environment variable names.
+ */
+export declare function secureEnvVarName(): z.ZodString;
+/**
+ * Create a Zod schema for safe identifiers (no special chars).
+ */
+export declare function secureIdentifier(maxLength?: number): z.ZodString;
+/**
+ * Create a Zod schema for URLs.
+ */
+export declare function secureUrl(options?: {
+    allowedProtocols?: string[];
+}): z.ZodString;