timonel 3.0.0 → 3.1.0-beta.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# [3.1.0-beta.1](https://github.com/KenkoGeek/timonel/compare/v3.0.0...v3.1.0-beta.1) (2026-01-03)
+
+### Features
+
+- **core:** policy engine plugin and documentation improvement ([#250](https://github.com/KenkoGeek/timonel/issues/250)) ([400478e](https://github.com/KenkoGeek/timonel/commit/400478e32a30f6f00864832347deb176cb81c94b))
+
 # [3.0.0](https://github.com/KenkoGeek/timonel/compare/v2.13.0...v3.0.0) (2025-12-07)
 
 - feat!: rename ChartFactory to Rutter (maritime pilot concept) ([b0a7a33](https://github.com/KenkoGeek/timonel/commit/b0a7a3361e761a5b20ff2c203d55bdfab35323af))

package/README.md

@@ -102,6 +102,11 @@ Useful string-based utilities (no ValuesRef equivalent):
   - Command injection prevention (CWE-78/77/88)
   - Log injection protection (CWE-117)
   - Code injection prevention (CWE-94)
+- **🔍 Policy Engine** (NEW):
+  - Extensible validation framework for Kubernetes manifests
+  - Plugin-based architecture for custom policy rules
+  - Zero-impact integration (completely optional)
+  - Support for security, compliance, and best practice policies
 - **NetworkPolicy support** for pod-level network isolation
 - **Helm chart validation** with `validateHelmYaml`
 - **SecurityUtils** for path validation and sanitization
@@ -212,6 +217,64 @@ chart.addManifest(
 chart.write('./dist');
 ```
 
+### Policy Engine Integration
+
+```typescript
+import { Rutter, PolicyEngine } from 'timonel';
+import { securityPolicies } from '@mycompany/k8s-security-policies';
+
+// Create policy engine with custom plugins
+const policyEngine = new PolicyEngine().use(securityPolicies).configure({
+  timeout: 5000,
+  parallel: true,
+});
+
+const chart = new Rutter({
+  meta: {
+    name: 'secure-app',
+    version: '1.0.0',
+  },
+  // Optional policy validation
+  policyEngine,
+});
+
+// Policies validate manifests before chart generation
+chart.write('./dist'); // Fails if policy violations found
+```
+
+### Creating Custom Policy Plugins
+
+```typescript
+import { PolicyPlugin, PolicyViolation } from 'timonel';
+
+export const mySecurityPolicy: PolicyPlugin = {
+  name: 'my-security-policy',
+  version: '1.0.0',
+  description: 'Custom security validation rules',
+
+  async validate(manifests, context) {
+    const violations: PolicyViolation[] = [];
+
+    for (const manifest of manifests) {
+      if (manifest.kind === 'Deployment') {
+        // Check for security context
+        if (!manifest.spec?.template?.spec?.securityContext) {
+          violations.push({
+            plugin: this.name,
+            severity: 'error',
+            message: 'Deployment must specify securityContext',
+            resourcePath: `${manifest.kind}/${manifest.metadata?.name}`,
+            suggestion: 'Add spec.template.spec.securityContext to your Deployment',
+          });
+        }
+      }
+    }
+
+    return violations;
+  },
+};
+```
+
 ### Umbrella Chart with Multiple Services
 
 ```typescript
@@ -350,12 +413,380 @@ with `v.if()`, `v.range()`, `v.with()`.
 [Type-Safe Helm Helpers Guide](https://github.com/KenkoGeek/timonel/wiki/Helm-Helpers-System) for
 complete documentation, examples, and best practices.
 
+## 🔍 Policy Engine
+
+The Policy Engine provides extensible validation for Kubernetes manifests through a
+plugin-based architecture. It's completely optional and has zero impact on existing users.
+
+### Key Features
+
+- **🔌 Plugin Architecture**: Extensible through external npm packages
+- **⚡ Zero Impact**: Completely optional with no performance overhead when unused
+- **🛡️ Security Focus**: Built-in support for security and compliance policies
+- **🔄 Async Support**: Handles both synchronous and asynchronous validation plugins
+- **📊 Rich Reporting**: Detailed violation reports with suggestions and context
+- **⏱️ Timeout Protection**: Configurable timeouts prevent hanging validations
+- **🔧 Configurable**: Environment-specific policy configuration support
+- **🚀 Performance Optimized**: Parallel execution, caching, and resource monitoring
+- **🔄 Error Resilience**: Graceful degradation and retry mechanisms
+- **📈 Observability**: Structured logging and performance metrics
+
+### Quick Start
+
+```typescript
+import { Rutter, PolicyEngine } from 'timonel';
+
+// Optional: Add policy validation
+const policyEngine = new PolicyEngine({
+  timeout: 10000,
+  parallel: true,
+  gracefulDegradation: true,
+});
+
+// Register plugins
+await policyEngine.use(await import('@mycompany/security-policies'));
+await policyEngine.use(await import('@kubernetes/best-practices'));
+
+const chart = new Rutter({
+  meta: { name: 'my-app', version: '1.0.0' },
+  policyEngine, // ← Completely optional
+});
+
+chart.write('./dist'); // Validates before writing
+```
+
+### Available Policy Plugins
+
+**Built-in Examples:**
+
+- **Security Plugin** - Comprehensive security validation (security contexts, RBAC, network policies)
+- **Best Practices Plugin** - Kubernetes best practices (resource limits, naming, probes)
+- **AWS Plugin** - AWS-specific validations (EKS, ALB, IRSA, cost optimization)
+
+**Community Plugins:**
+
+- `@kubernetes/pod-security-standards` - Official Kubernetes PSS validation
+- `@open-policy-agent/timonel-plugin` - OPA Rego policy integration
+- `@falco/security-policies` - Falco runtime security rules
+
+**Enterprise Plugins:**
+
+- `@company/compliance-policies` - Organization-specific compliance rules
+- `@aws/well-architected-policies` - AWS Well-Architected Framework validation
+- `@security/cis-benchmarks` - CIS Kubernetes Benchmark validation
+
+### Creating Custom Policies
+
+```typescript
+import { PolicyPlugin, PolicyViolation, ValidationContext } from 'timonel';
+
+export const customSecurityPolicy: PolicyPlugin = {
+  name: 'custom-security-policy',
+  version: '1.0.0',
+  description: 'Custom security validation rules',
+
+  // Optional: Configuration schema for validation
+  configSchema: {
+    type: 'object',
+    properties: {
+      strictMode: { type: 'boolean', default: false },
+      allowedNamespaces: { type: 'array', items: { type: 'string' } },
+    },
+  },
+
+  async validate(manifests: unknown[], context: ValidationContext): Promise<PolicyViolation[]> {
+    const violations: PolicyViolation[] = [];
+    const config = context.config as { strictMode?: boolean; allowedNamespaces?: string[] };
+
+    for (const manifest of manifests) {
+      if (manifest.kind === 'Deployment') {
+        // Validate security context
+        if (!manifest.spec?.template?.spec?.securityContext) {
+          violations.push({
+            plugin: this.name,
+            severity: config?.strictMode ? 'error' : 'warning',
+            message: 'Deployment should specify securityContext',
+            resourcePath: `${manifest.kind}/${manifest.metadata?.name}`,
+            field: 'spec.template.spec.securityContext',
+            suggestion: 'Add securityContext with runAsNonRoot: true',
+            context: {
+              kubernetesVersion: context.kubernetesVersion,
+              environment: context.environment,
+            },
+          });
+        }
+
+        // Validate namespace restrictions
+        const namespace = manifest.metadata?.namespace || 'default';
+        if (config?.allowedNamespaces && !config.allowedNamespaces.includes(namespace)) {
+          violations.push({
+            plugin: this.name,
+            severity: 'error',
+            message: `Deployment in unauthorized namespace: ${namespace}`,
+            resourcePath: `${manifest.kind}/${manifest.metadata?.name}`,
+            field: 'metadata.namespace',
+            suggestion: `Deploy to allowed namespaces: ${config.allowedNamespaces.join(', ')}`,
+          });
+        }
+      }
+    }
+
+    return violations;
+  },
+};
+```
+
+### Advanced Configuration
+
+```typescript
+const policyEngine = new PolicyEngine({
+  // Execution settings
+  timeout: 15000, // 15 second timeout per plugin
+  parallel: true, // Run plugins in parallel for better performance
+  failFast: false, // Collect all violations before failing
+  gracefulDegradation: true, // Continue on plugin failures
+
+  // Performance optimization
+  cacheOptions: {
+    maxSize: 1000, // Cache up to 1000 validation results
+    ttl: 300000, // 5 minute cache TTL
+    enableStats: true, // Enable cache performance monitoring
+  },
+
+  // Parallel execution tuning
+  parallelOptions: {
+    maxConcurrency: 4, // Run up to 4 plugins concurrently
+    enableResourceMonitoring: true,
+  },
+
+  // Retry configuration
+  retryConfig: {
+    maxAttempts: 3,
+    baseDelay: 1000,
+    retryOnTimeout: true,
+    retryOnPluginError: false,
+  },
+
+  // Plugin-specific configuration
+  pluginConfig: {
+    'security-plugin': {
+      strictMode: true,
+      allowedNamespaces: ['default', 'kube-system'],
+      securityContext: {
+        required: true,
+        runAsNonRoot: true,
+      },
+    },
+    'best-practices-plugin': {
+      enforceResourceLimits: true,
+      requireLabels: ['app', 'version', 'environment'],
+      maxReplicas: 50,
+    },
+    'aws-plugin': {
+      region: 'us-west-2',
+      enforceTagging: true,
+      costOptimization: {
+        enabled: true,
+        maxInstanceSize: 'xlarge',
+      },
+    },
+  },
+});
+
+// Register plugins
+await policyEngine.use(securityPolicies);
+await policyEngine.use(bestPracticesPolicies);
+await policyEngine.use(awsPolicies);
+```
+
+### Environment-Specific Policies
+
+```typescript
+// Load different policies based on environment
+const createPolicyEngine = (environment: string) => {
+  const engine = new PolicyEngine({
+    environment,
+    configurationLoader: {
+      configurationFiles: ['config/policy-engine.json', `config/environments/${environment}.json`],
+    },
+  });
+
+  // Base security policies for all environments
+  await engine.use(baseSecurity);
+
+  // Environment-specific policies
+  switch (environment) {
+    case 'production':
+      await engine.use(strictSecurity);
+      await engine.use(compliancePolicies);
+      await engine.use(awsPolicies);
+      break;
+    case 'staging':
+      await engine.use(moderateSecurity);
+      await engine.use(awsPolicies);
+      break;
+    case 'development':
+      // Minimal policies for development
+      await engine.use(basicSecurity);
+      break;
+  }
+
+  return engine;
+};
+```
+
+### Integration with CI/CD
+
+```typescript
+// In your CI/CD pipeline
+import { Rutter, PolicyEngine, PolicyEngineError } from 'timonel';
+
+const validateChart = async (chartPath: string, environment: string) => {
+  const policyEngine = await createPolicyEngine(environment);
+
+  try {
+    const chart = new Rutter({
+      meta: { name: 'my-app', version: process.env.VERSION },
+      policyEngine,
+    });
+
+    await chart.write(chartPath);
+
+    // Log validation success with metrics
+    const stats = policyEngine.getCacheStats();
+    console.log('✅ Chart validation passed', {
+      environment,
+      cacheHitRate: stats.hitRate,
+      pluginCount: policyEngine.getPluginCount(),
+    });
+  } catch (error) {
+    if (error instanceof PolicyEngineError) {
+      console.error('❌ Policy violations found:');
+
+      // Group violations by severity
+      const errors = error.violations.filter((v) => v.severity === 'error');
+      const warnings = error.violations.filter((v) => v.severity === 'warning');
+
+      if (errors.length > 0) {
+        console.error(`\n🚨 Errors (${errors.length}):`);
+        errors.forEach((v) => {
+          console.error(`  • ${v.resourcePath}: ${v.message}`);
+          if (v.suggestion) {
+            console.error(`    💡 ${v.suggestion}`);
+          }
+        });
+      }
+
+      if (warnings.length > 0) {
+        console.warn(`\n⚠️  Warnings (${warnings.length}):`);
+        warnings.forEach((v) => {
+          console.warn(`  • ${v.resourcePath}: ${v.message}`);
+        });
+      }
+
+      // Fail CI/CD on errors, but allow warnings
+      if (errors.length > 0) {
+        process.exit(1);
+      }
+    } else {
+      throw error;
+    }
+  }
+};
+
+// Usage in GitHub Actions, GitLab CI, etc.
+await validateChart('./dist', process.env.ENVIRONMENT || 'development');
+```
+
+### Plugin Ecosystem
+
+The Policy Engine supports a rich ecosystem of plugins for various use cases:
+
+#### Security & Compliance
+
+- **Pod Security Standards** - Kubernetes PSS validation
+- **CIS Benchmarks** - Center for Internet Security benchmarks
+- **NIST Framework** - NIST Cybersecurity Framework compliance
+- **PCI DSS** - Payment Card Industry compliance
+- **SOC 2** - Service Organization Control 2 compliance
+
+#### Cloud Provider Integrations
+
+- **AWS Well-Architected** - AWS best practices and cost optimization
+- **Azure Security Center** - Azure-specific security policies
+- **GCP Security Command Center** - Google Cloud security validation
+
+#### Development & Operations
+
+- **GitOps Policies** - GitOps workflow validation
+- **Resource Optimization** - Cost and performance optimization
+- **Observability** - Monitoring and logging best practices
+- **Backup & Recovery** - Data protection policies
+
+#### Creating Plugin Packages
+
+```typescript
+// package.json for a policy plugin
+{
+  "name": "@mycompany/k8s-security-policies",
+  "version": "1.0.0",
+  "description": "Security policies for Kubernetes manifests",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": ["timonel", "policy", "security", "kubernetes"],
+  "peerDependencies": {
+    "timonel": "^3.0.0"
+  }
+}
+
+// src/index.ts
+export { SecurityPlugin } from './security-plugin.js';
+export { CompliancePlugin } from './compliance-plugin.js';
+export type { SecurityConfig, ComplianceConfig } from './types.js';
+```
+
+### Performance & Monitoring
+
+The Policy Engine includes comprehensive performance monitoring:
+
+```typescript
+// Monitor policy engine performance
+const result = await policyEngine.validate(manifests, { name: 'example-chart', version: '1.0.0' });
+
+console.log('Validation Performance:', {
+  executionTime: result.metadata.executionTime,
+  pluginCount: result.metadata.pluginCount,
+  manifestCount: result.metadata.manifestCount,
+  violationsFound: result.violations.length,
+});
+
+// Cache performance monitoring
+const cacheStats = policyEngine.getCacheStats();
+console.log('Cache Performance:', {
+  hitRate: cacheStats.hitRate,
+  totalHits: cacheStats.hits,
+  totalMisses: cacheStats.misses,
+  cacheSize: cacheStats.size,
+});
+
+// Clear cache when needed
+policyEngine.invalidateCache({ all: true });
+```
+
 ## 📚 Documentation
 
 - **[API Reference](https://github.com/KenkoGeek/timonel/wiki/API-Reference)** - Complete API
   documentation
 - **[CLI Reference](https://github.com/KenkoGeek/timonel/wiki/CLI-Reference)** - Command-line
   interface guide
+- **[Policy Engine Guide](https://github.com/KenkoGeek/timonel/wiki/Policy-Engine)** -
+  Policy validation and plugin development
+- **[Plugin Development Guide](https://github.com/KenkoGeek/timonel/wiki/Plugin-Development)** -
+  Creating custom policy plugins
+- **[Configuration Reference](https://github.com/KenkoGeek/timonel/wiki/Policy-Configuration)** -
+  Policy engine configuration options
+- **[Policy Examples](https://github.com/KenkoGeek/timonel/wiki/Policy-Examples)** - Example plugins
+  and usage patterns
 - **[Examples](https://github.com/KenkoGeek/timonel/wiki/Examples)** - Real-world usage examples
 - **[Best Practices](https://github.com/KenkoGeek/timonel/wiki/Best-Practices)** - Recommended
   patterns and practices

package/dist/index.d.ts

@@ -3,9 +3,12 @@ export * from './lib/helmChartWriter.js';
 export * from './lib/rutter.js';
 export * from './lib/security.js';
 export * from './lib/umbrella.js';
+export * from './lib/policy/index.js';
+export * from './lib/validation/inputValidator.js';
 export { FlexibleSubchart, createFlexibleSubchart } from './lib/templates/flexible-subchart.js';
 export { UmbrellaChartTemplate as UmbrellaChart } from './lib/templates/umbrella-chart.js';
 export type { ChartProps, SubchartProps } from './lib/types.js';
+export type { PolicyConfig, PolicyRule, PolicyContext, PluginConfig } from './types/index.js';
 export type { AWSALBIngressSpec, AWSEBSStorageClassSpec, AWSEFSStorageClassSpec, AWSIRSAServiceAccountSpec, } from './lib/resources/cloud/aws/awsResources.js';
 export type { KarpenterDisruption, KarpenterDisruptionBudget, KarpenterEC2NodeClassSpec, KarpenterNodeClaimSpec, KarpenterNodePoolSpec, } from './lib/resources/cloud/aws/karpenterResources.js';
 export { DEFAULT_TERMINATION_GRACE_PERIOD, isValidDisruptionBudget, isValidKubernetesDuration, KarpenterVersionUtils, } from './lib/resources/cloud/aws/karpenterResources.js';

package/dist/index.js

@@ -3,6 +3,8 @@ export * from './lib/helmChartWriter.js';
 export * from './lib/rutter.js';
 export * from './lib/security.js';
 export * from './lib/umbrella.js';
+export * from './lib/policy/index.js';
+export * from './lib/validation/inputValidator.js';
 export { FlexibleSubchart, createFlexibleSubchart } from './lib/templates/flexible-subchart.js';
 export { UmbrellaChartTemplate as UmbrellaChart } from './lib/templates/umbrella-chart.js';
 export { DEFAULT_TERMINATION_GRACE_PERIOD, isValidDisruptionBudget, isValidKubernetesDuration, KarpenterVersionUtils, } from './lib/resources/cloud/aws/karpenterResources.js';

package/dist/lib/policy/configurationLoader.d.ts

@@ -0,0 +1,46 @@
+import type { JSONSchema, PolicyPlugin, ConfigurationLoaderOptions } from './types.js';
+export type ConfigurationSource = 'environment' | 'file' | 'inline' | 'default';
+export interface ConfigurationEntry {
+    readonly value: unknown;
+    readonly source: ConfigurationSource;
+    readonly environment?: string;
+    readonly priority: number;
+    readonly schema?: JSONSchema;
+}
+export interface PluginConfiguration {
+    readonly pluginName: string;
+    readonly config: Record<string, unknown>;
+    readonly entries: ConfigurationEntry[];
+    readonly validated: boolean;
+    readonly validationErrors?: string[];
+}
+export interface EnvironmentConfiguration {
+    readonly environment: string;
+    readonly plugins: Record<string, unknown>;
+    readonly global?: Record<string, unknown>;
+}
+export declare class ConfigurationLoader {
+    private readonly options;
+    private readonly logger;
+    private readonly configurations;
+    private readonly environmentConfigs;
+    constructor(options?: ConfigurationLoaderOptions);
+    loadPluginConfiguration(plugin: PolicyPlugin, environment?: string, inlineConfig?: Record<string, unknown>): Promise<PluginConfiguration>;
+    private collectConfigurationEntries;
+    private validatePluginConfiguration;
+    loadEnvironmentConfiguration(environment: string): Promise<EnvironmentConfiguration | undefined>;
+    validateConfiguration(config: Record<string, unknown>, schema: JSONSchema, pluginName: string): void;
+    addConfigurationEntry(pluginName: string, entry: ConfigurationEntry): void;
+    getConfigurationEntries(pluginName: string): ConfigurationEntry[];
+    clearCache(): void;
+    private loadFileConfiguration;
+    private loadEnvironmentVariableConfiguration;
+    private loadEnvironmentFromFiles;
+    private mergeConfigurations;
+    private parseEnvironmentValue;
+    private validateAgainstSchema;
+    private validateBasicType;
+    private validateObjectProperties;
+    private validateRequiredProperties;
+    private validateEachProperty;
+}