timonel 3.1.1 → 3.1.2

package/dist/lib/security.d.ts

@@ -1,21 +1,144 @@
+/**
+ * @fileoverview Security utilities for input validation and sanitization
+ * Focused on CLI tool security concerns: path traversal, injection prevention
+ * @since 2.8.0+
+ */
+/** Options controlling path validation behaviour. */
 export interface PathValidationOptions {
+    /**
+     * When true, accepts absolute destinations even if they fall outside the allowed base.
+     * @since 2.12.2 Enables secure chart writes to system-level directories.
+     */
     allowAbsolute?: boolean;
 }
+/**
+ * Security utilities for input validation and sanitization
+ * Focused on CLI tool security concerns: path traversal, injection prevention
+ *
+ * @since 2.8.0+
+ */
 export declare class SecurityUtils {
+    /**
+     * Validates and sanitizes file paths to prevent path traversal attacks
+     * @param inputPath - The path to validate
+     * @param allowedBasePath - The base path that the input should be within
+     * @returns Sanitized path if valid
+     * @throws Error if path is invalid or contains traversal sequences
+     *
+     * @since 2.8.0+
+     */
     static validatePath(inputPath: string, allowedBasePath: string, options?: PathValidationOptions): string;
+    /**
+     * Sanitizes log messages to prevent log injection attacks
+     * @param message - The message to sanitize
+     * @returns Sanitized message with control characters removed
+     *
+     * @since 2.8.0+
+     */
     static sanitizeLogMessage(message: string): string;
+    /**
+     * Sanitizes environment names to prevent path traversal (CWE-22)
+     * @param env - Environment name to sanitize
+     * @returns Sanitized environment name
+     * @throws Error if environment name is invalid
+     *
+     * @since 2.8.0+
+     */
     static sanitizeEnvironmentName(env: string): string;
+    /**
+     * Validates TypeScript file extensions for dynamic imports
+     * @param filePath - The file path to validate
+     * @returns True if the file has a valid TypeScript extension
+     *
+     * @since 2.8.0+
+     */
     static isValidTypeScriptFile(filePath: string): boolean;
+    /**
+     * Validates if a path is safe for use in Helm templates
+     * Enhanced validation with better security checks and Helm best practices
+     * @param templatePath - The template path to validate
+     * @returns True if the path is valid for Helm templates
+     *
+     * @since 2.8.0+
+     */
     static isValidHelmTemplatePath(templatePath: string): boolean;
+    /**
+     * Validates chart names according to Helm conventions
+     * @param chartName - Chart name to validate
+     * @returns True if chart name follows Helm naming rules
+     *
+     * @since 2.8.0+
+     */
     static isValidChartName(chartName: string): boolean;
+    /**
+     * Validates subchart names according to Helm conventions
+     * @param subchartName - Subchart name to validate
+     * @returns True if subchart name is valid
+     *
+     * @since 2.8.0+
+     */
     static isValidSubchartName(subchartName: string): boolean;
+    /**
+     * Sanitizes environment variable names and values for Kubernetes security
+     * Prevents injection attacks and ensures compliance with Kubernetes naming rules
+     * @param name - Environment variable name to sanitize
+     * @param value - Environment variable value to sanitize
+     * @returns Object with sanitized name and value
+     * @throws Error if name or value contains dangerous patterns
+     *
+     * @since 2.8.0+
+     */
     static sanitizeEnvVar(name: string, value: string): {
         name: string;
         value: string;
     };
+    /**
+     * Validates container image tags for security best practices
+     * Prevents use of dangerous tags and ensures proper versioning
+     * @param tag - Image tag to validate
+     * @returns True if tag is valid and secure
+     * @throws Error if tag violates security policies
+     *
+     * @since 2.8.0+
+     */
     static validateImageTag(tag: string): boolean;
+    /**
+     * Generates secure names for Kubernetes secrets
+     * Ensures names follow RFC 1123 and are safe for Kubernetes
+     * @param baseName - Base name for the secret
+     * @param suffix - Optional suffix to append
+     * @returns Secure secret name
+     * @throws Error if generated name is invalid
+     *
+     * @since 2.8.0+
+     */
     static generateSecretName(baseName: string, suffix?: string): string;
+    /**
+     * Sanitizes the base name for secret generation using safe string methods
+     * @param baseName - Base name to sanitize
+     * @returns Sanitized base name
+     * @throws Error if no valid characters remain
+     *
+     * @since 2.8.0+
+     */
     private static sanitizeBaseName;
+    /**
+     * Appends suffix to sanitized base name using safe string methods
+     * @param baseName - Sanitized base name
+     * @param suffix - Suffix to append
+     * @returns Base name with suffix
+     * @throws Error if suffix is invalid
+     *
+     * @since 2.8.0+
+     */
     private static appendSuffix;
+    /**
+     * Truncates name if it exceeds length limits
+     * @param name - Name to potentially truncate
+     * @param suffix - Original suffix for preservation
+     * @returns Truncated name if needed
+     *
+     * @since 2.8.0+
+     */
     private static truncateIfNeeded;
 }

package/dist/lib/security.js

@@ -1,5 +1,25 @@
+/**
+ * @fileoverview Security utilities for input validation and sanitization
+ * Focused on CLI tool security concerns: path traversal, injection prevention
+ * @since 2.8.0+
+ */
 import * as path from 'path';
+/**
+ * Security utilities for input validation and sanitization
+ * Focused on CLI tool security concerns: path traversal, injection prevention
+ *
+ * @since 2.8.0+
+ */
 export class SecurityUtils {
+    /**
+     * Validates and sanitizes file paths to prevent path traversal attacks
+     * @param inputPath - The path to validate
+     * @param allowedBasePath - The base path that the input should be within
+     * @returns Sanitized path if valid
+     * @throws Error if path is invalid or contains traversal sequences
+     *
+     * @since 2.8.0+
+     */
     static validatePath(inputPath, allowedBasePath, options) {
         if (!inputPath || typeof inputPath !== 'string') {
             throw new Error('Invalid path: path must be a non-empty string');
@@ -24,6 +44,7 @@ export class SecurityUtils {
                 registerCandidate(normalized);
             }
             catch {
+                // Ignore normalization errors and continue with existing candidates.
             }
         };
         addCandidate(inputPath);
@@ -58,6 +79,7 @@ export class SecurityUtils {
                 throw new Error('Invalid path: path traversal sequences detected');
             }
         }
+        // Resolve and normalize paths
         const resolvedInput = path.resolve(inputPath);
         const resolvedBase = path.resolve(allowedBasePath);
         const relativePath = path.relative(resolvedBase, resolvedInput);
@@ -67,21 +89,39 @@ export class SecurityUtils {
         }
         return resolvedInput;
     }
+    /**
+     * Sanitizes log messages to prevent log injection attacks
+     * @param message - The message to sanitize
+     * @returns Sanitized message with control characters removed
+     *
+     * @since 2.8.0+
+     */
     static sanitizeLogMessage(message) {
         if (typeof message !== 'string') {
             return String(message);
         }
+        // Remove control characters (ASCII 0-31 and 127) and normalize line endings
         return (message
-            .replace(/\r\n/g, '\n')
-            .replace(/[\x00-\x09\x0B-\x0C\x0E-\x1F\x7F]/g, '')
-            .replace(/[\r\n]/g, ' ')
-            .replace(/\s+/g, ' ')
+            .replace(/\r\n/g, '\n') // Normalize CRLF to LF
+            // eslint-disable-next-line no-control-regex -- Intentionally removing control characters for security
+            .replace(/[\x00-\x09\x0B-\x0C\x0E-\x1F\x7F]/g, '') // Strip control chars except LF/CR
+            .replace(/[\r\n]/g, ' ') // Normalize remaining line breaks
+            .replace(/\s+/g, ' ') // Collapse repeated whitespace
             .trim());
     }
+    /**
+     * Sanitizes environment names to prevent path traversal (CWE-22)
+     * @param env - Environment name to sanitize
+     * @returns Sanitized environment name
+     * @throws Error if environment name is invalid
+     *
+     * @since 2.8.0+
+     */
     static sanitizeEnvironmentName(env) {
         if (!env || typeof env !== 'string') {
             throw new Error('Environment name must be a non-empty string');
         }
+        // Allow only alphanumeric, hyphens, and underscores
         const sanitized = env.replace(/[^a-zA-Z0-9-_]/g, '');
         if (sanitized !== env) {
             throw new Error(`Invalid environment name: ${SecurityUtils.sanitizeLogMessage(env)}`);
@@ -91,52 +131,105 @@ export class SecurityUtils {
         }
         return sanitized;
     }
+    /**
+     * Validates TypeScript file extensions for dynamic imports
+     * @param filePath - The file path to validate
+     * @returns True if the file has a valid TypeScript extension
+     *
+     * @since 2.8.0+
+     */
     static isValidTypeScriptFile(filePath) {
         const allowedExtensions = ['.ts', '.tsx', '.cts', '.mts'];
         const ext = path.extname(filePath);
         return allowedExtensions.includes(ext);
     }
+    /**
+     * Validates if a path is safe for use in Helm templates
+     * Enhanced validation with better security checks and Helm best practices
+     * @param templatePath - The template path to validate
+     * @returns True if the path is valid for Helm templates
+     *
+     * @since 2.8.0+
+     */
     static isValidHelmTemplatePath(templatePath) {
         if (!templatePath || typeof templatePath !== 'string') {
             return false;
         }
+        // Check length limits (reasonable for Helm paths)
         if (templatePath.length > 253) {
             return false;
         }
+        // Enhanced validation following Kubernetes naming conventions
+        // Check if starts and ends with alphanumeric
         if (!/^[a-zA-Z0-9]/.test(templatePath) || !/[a-zA-Z0-9]$/.test(templatePath)) {
             return false;
         }
+        // Check for valid characters only (safe regex)
         if (!/^[a-zA-Z0-9._\-/]+$/.test(templatePath)) {
             return false;
         }
+        // Additional security checks
+        // Prevent path traversal attempts
         if (templatePath.includes('..') || templatePath.includes('//')) {
             return false;
         }
+        // Prevent reserved words that could cause issues
         const reservedWords = ['nil', 'null', 'undefined', 'true', 'false'];
+        // Split by directory separators first
         const pathParts = templatePath.split('/');
         for (const part of pathParts) {
+            // Then split by dots for file extensions/parts
             const segments = part.split('.');
             for (const segment of segments) {
                 if (reservedWords.includes(segment.toLowerCase())) {
                     return false;
                 }
+                // Each segment should not be empty (except possibly for leading dot files, but split handles that)
                 if (segment.length === 0 && segments.length > 1) {
+                    // Allow .gitignore (empty first segment)
                     continue;
                 }
             }
         }
         return true;
     }
+    /**
+     * Validates chart names according to Helm conventions
+     * @param chartName - Chart name to validate
+     * @returns True if chart name follows Helm naming rules
+     *
+     * @since 2.8.0+
+     */
     static isValidChartName(chartName) {
         if (!chartName || typeof chartName !== 'string') {
             return false;
         }
+        // Helm chart name validation (RFC 1123 subdomain) - safe regex
+        // Must start with a letter, can contain letters, numbers, and hyphens
+        // eslint-disable-next-line security/detect-unsafe-regex -- Simple character class regex is safe
         const chartNameRegex = /^[a-z]([-a-z0-9]*[a-z0-9])?$/;
         return chartNameRegex.test(chartName) && chartName.length <= 63;
     }
+    /**
+     * Validates subchart names according to Helm conventions
+     * @param subchartName - Subchart name to validate
+     * @returns True if subchart name is valid
+     *
+     * @since 2.8.0+
+     */
     static isValidSubchartName(subchartName) {
         return this.isValidChartName(subchartName);
     }
+    /**
+     * Sanitizes environment variable names and values for Kubernetes security
+     * Prevents injection attacks and ensures compliance with Kubernetes naming rules
+     * @param name - Environment variable name to sanitize
+     * @param value - Environment variable value to sanitize
+     * @returns Object with sanitized name and value
+     * @throws Error if name or value contains dangerous patterns
+     *
+     * @since 2.8.0+
+     */
     static sanitizeEnvVar(name, value) {
         if (!name || typeof name !== 'string') {
             throw new Error('Environment variable name must be a non-empty string');
@@ -144,7 +237,9 @@ export class SecurityUtils {
         if (typeof value !== 'string') {
             throw new Error('Environment variable value must be a string');
         }
+        // Kubernetes env var name validation (RFC 1123 compatible)
         let sanitizedName = name.toUpperCase().replace(/[^A-Z0-9_]/g, '_');
+        // Ensure name starts with letter or underscore
         if (/^[0-9]/.test(sanitizedName)) {
             sanitizedName = `_${sanitizedName}`;
         }
@@ -152,6 +247,7 @@ export class SecurityUtils {
         if (!nameRegex.test(sanitizedName)) {
             throw new Error(`Invalid environment variable name: ${SecurityUtils.sanitizeLogMessage(name)}`);
         }
+        // Check for dangerous patterns in value using safer string methods
         const hasDangerousPattern = (val) => {
             if (val.includes('$(') && val.includes(')'))
                 return 'command substitution';
@@ -159,6 +255,7 @@ export class SecurityUtils {
                 return 'backtick execution';
             if (val.includes('${') && val.includes('}'))
                 return 'variable expansion';
+            // Check for control characters
             for (let i = 0; i < val.length; i++) {
                 const code = val.charCodeAt(i);
                 if ((code >= 0x00 && code <= 0x08) ||
@@ -175,6 +272,7 @@ export class SecurityUtils {
         if (dangerousPattern) {
             throw new Error(`Environment variable value contains dangerous pattern (${dangerousPattern}): ${SecurityUtils.sanitizeLogMessage(value)}`);
         }
+        // Limit value length to prevent DoS
         if (value.length > 32768) {
             throw new Error('Environment variable value exceeds maximum length (32KB)');
         }
@@ -183,31 +281,58 @@ export class SecurityUtils {
             value: value.trim(),
         };
     }
+    /**
+     * Validates container image tags for security best practices
+     * Prevents use of dangerous tags and ensures proper versioning
+     * @param tag - Image tag to validate
+     * @returns True if tag is valid and secure
+     * @throws Error if tag violates security policies
+     *
+     * @since 2.8.0+
+     */
     static validateImageTag(tag) {
         if (!tag || typeof tag !== 'string') {
             throw new Error('Image tag must be a non-empty string');
         }
         const trimmedTag = tag.trim();
+        // Reject dangerous or non-specific tags
         const dangerousTags = ['latest', 'master', 'main', 'dev', 'development', 'test', 'staging'];
         if (dangerousTags.includes(trimmedTag.toLowerCase())) {
             throw new Error(`Insecure image tag detected: '${trimmedTag}'. Use specific version tags for security.`);
         }
+        // Validate tag format (Docker tag rules)
         const tagRegex = /^[a-zA-Z0-9._-]+$/;
         if (!tagRegex.test(trimmedTag)) {
             throw new Error(`Invalid image tag format: ${SecurityUtils.sanitizeLogMessage(trimmedTag)}`);
         }
+        // Check length limits
         if (trimmedTag.length > 128) {
             throw new Error('Image tag exceeds maximum length (128 characters)');
         }
+        // Prefer semantic versioning patterns
+        // eslint-disable-next-line security/detect-unsafe-regex -- Simple regex patterns are safe for validation
         const semverPattern = /^v?\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?$/;
         const hashPattern = /^[a-f0-9]{7,64}$/;
+        // eslint-disable-next-line security/detect-unsafe-regex -- Simple date pattern is safe for validation
         const datePattern = /^\d{4}-\d{2}-\d{2}(-[a-zA-Z0-9.-]+)?$/;
         if (!semverPattern.test(trimmedTag) &&
             !hashPattern.test(trimmedTag) &&
             !datePattern.test(trimmedTag)) {
+            // Warning for non-standard tags but don't fail
+            // Note: Non-standard tag pattern detected but allowing it
         }
         return true;
     }
+    /**
+     * Generates secure names for Kubernetes secrets
+     * Ensures names follow RFC 1123 and are safe for Kubernetes
+     * @param baseName - Base name for the secret
+     * @param suffix - Optional suffix to append
+     * @returns Secure secret name
+     * @throws Error if generated name is invalid
+     *
+     * @since 2.8.0+
+     */
     static generateSecretName(baseName, suffix) {
         if (!baseName || typeof baseName !== 'string') {
             throw new Error('Base name must be a non-empty string');
@@ -216,16 +341,27 @@ export class SecurityUtils {
         if (suffix) {
             sanitizedBase = this.appendSuffix(sanitizedBase, suffix);
         }
+        // Ensure name starts with letter (not number)
         if (/^[0-9]/.test(sanitizedBase)) {
             sanitizedBase = `s${sanitizedBase}`;
         }
         sanitizedBase = this.truncateIfNeeded(sanitizedBase, suffix);
+        // Final validation
         if (!this.isValidChartName(sanitizedBase)) {
             throw new Error(`Generated secret name is invalid: ${sanitizedBase}`);
         }
         return sanitizedBase;
     }
+    /**
+     * Sanitizes the base name for secret generation using safe string methods
+     * @param baseName - Base name to sanitize
+     * @returns Sanitized base name
+     * @throws Error if no valid characters remain
+     *
+     * @since 2.8.0+
+     */
     static sanitizeBaseName(baseName) {
+        // Use character-by-character processing instead of regex
         let sanitized = '';
         for (const char of baseName.toLowerCase()) {
             if ((char >= 'a' && char <= 'z') || (char >= '0' && char <= '9') || char === '-') {
@@ -235,6 +371,7 @@ export class SecurityUtils {
                 sanitized += '-';
             }
         }
+        // Collapse multiple hyphens using split/filter/join
         const parts = sanitized.split('-').filter((part) => part.length > 0);
         sanitized = parts.join('-');
         if (!sanitized) {
@@ -242,10 +379,20 @@ export class SecurityUtils {
         }
         return sanitized;
     }
+    /**
+     * Appends suffix to sanitized base name using safe string methods
+     * @param baseName - Sanitized base name
+     * @param suffix - Suffix to append
+     * @returns Base name with suffix
+     * @throws Error if suffix is invalid
+     *
+     * @since 2.8.0+
+     */
     static appendSuffix(baseName, suffix) {
         if (typeof suffix !== 'string') {
             throw new Error('Suffix must be a string');
         }
+        // Use character-by-character processing instead of regex
         let sanitizedSuffix = '';
         for (const char of suffix.toLowerCase()) {
             if ((char >= 'a' && char <= 'z') || (char >= '0' && char <= '9') || char === '-') {
@@ -255,6 +402,7 @@ export class SecurityUtils {
                 sanitizedSuffix += '-';
             }
         }
+        // Collapse multiple hyphens using split/filter/join
         const parts = sanitizedSuffix.split('-').filter((part) => part.length > 0);
         sanitizedSuffix = parts.join('-');
         if (sanitizedSuffix) {
@@ -262,12 +410,22 @@ export class SecurityUtils {
         }
         return baseName;
     }
+    /**
+     * Truncates name if it exceeds length limits
+     * @param name - Name to potentially truncate
+     * @param suffix - Original suffix for preservation
+     * @returns Truncated name if needed
+     *
+     * @since 2.8.0+
+     */
     static truncateIfNeeded(name, suffix) {
         const maxLength = 63;
         if (name.length <= maxLength) {
             return name;
         }
+        // Truncate but preserve suffix if possible
         if (suffix) {
+            // Use safe character processing instead of regex
             let safeSuffix = '';
             for (const char of suffix.toLowerCase()) {
                 if ((char >= 'a' && char <= 'z') || (char >= '0' && char <= '9') || char === '-') {

package/dist/lib/templates/flexible-subchart.d.ts

@@ -1,4 +1,12 @@
+/**
+ * @fileoverview Flexible subchart template that supports any cdk8s/cdk8s-plus-33 construct
+ * @since 2.8.4
+ */
 import { Chart } from 'cdk8s';
+/**
+ * Flexible subchart that can accept any cdk8s construct or function
+ * @since 2.8.4
+ */
 export declare class FlexibleSubchart extends Chart {
     private readonly config;
     private _constructs;
@@ -11,18 +19,62 @@ export declare class FlexibleSubchart extends Chart {
         manifest?: unknown;
         [key: string]: unknown;
     });
+    /**
+     * Add any cdk8s construct
+     * @param construct - Any cdk8s construct
+     * @param id - Unique identifier
+     */
     addConstruct(construct: unknown, id?: string): void;
+    /**
+     * Add any manifest (for addManifest compatibility)
+     * @param manifest - Any manifest object
+     * @param id - Unique identifier
+     */
     addManifest(manifest: unknown, id?: string): void;
+    /**
+     * Configure the subchart with any provided construct or manifest
+     * @private
+     */
     private configure;
+    /**
+     * Write Helm chart files for this subchart
+     * @param outputDir - Directory to write the Helm chart files
+     */
     writeHelmChart(outputDir: string): void;
+    /**
+     * Generate Helm template for a manifest
+     * @param manifest - The manifest object
+     * @param id - Template identifier
+     * @returns Generated template content
+     * @private
+     */
     private _generateManifestTemplate;
+    /**
+     * Get all constructs added to this subchart
+     */
     getConstructs(): unknown[];
+    /**
+     * Get all manifests added to this subchart
+     */
     getManifests(): unknown[];
 }
+/**
+ * Create a flexible subchart that can accept any construct
+ * @param scope - Parent chart scope
+ * @param id - Unique identifier
+ * @param config - Subchart configuration
+ * @returns FlexibleSubchart instance
+ */
 export declare function createFlexibleSubchart(scope: Chart, id: string, config: {
     name: string;
     version?: string;
     description?: string;
     [key: string]: unknown;
 }): FlexibleSubchart;
+/**
+ * Generate a simple subchart template using Rutter addManifest()
+ * @param name Subchart name
+ * @returns Template string for chart.ts with simple Rutter implementation
+ * @since 2.11.0
+ */
 export declare function generateFlexibleSubchartTemplate(name: string): string;