Initial commit

2025-11-29 18:13:12 +08:00
commit d765af1a6c
4 changed files with 695 additions and 0 deletions
--- a/commands/env-config-manager.md
+++ b/commands/env-config-manager.md
@@ -0,0 +1,635 @@
+---
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob
+description: ClaudeForge environment configuration and secrets management with Vault, AWS Secrets Manager, and validation.
+---
+
+# ClaudeForge Environment Config Manager
+
+ClaudeForge intelligent environment configuration and secrets management system that securely handles environment variables, manages secrets across multiple environments, and ensures configuration validation with enterprise-grade security practices.
+
+## Purpose
+
+Transform configuration management from scattered environment files to centralized, secure, and validated configuration systems that prevent security vulnerabilities, simplify deployment, and maintain consistency across all environments.
+
+## Features
+
+- **Environment Files**: Manage .env files with validation and type checking
+- **Secrets Management**: Integrate with Vault, AWS Secrets Manager, Azure Key Vault
+- **Configuration Validation**: Schema validation and required variable checking
+- **Multi-Environment**: Separate configurations for dev, staging, production
+- **Secret Rotation**: Automated secret rotation and expiration management
+- **Encryption**: Encrypt sensitive configuration values at rest
+- **Access Control**: Role-based access to configuration and secrets
+- **Audit Logging**: Track all configuration and secret access
+
+## Usage
+
+```bash
+/env-config-manager [action] [options]
+```
+
+Target: $ARGUMENTS (if specified, otherwise analyze current scope)
+
+### Environment File Management
+
+**Initialize Environment:**
+```bash
+/env-config-manager init --template=node --environments=dev,staging,prod
+```
+Creates environment configuration structure with:
+- .env template files for each environment
+- .env.example with all required variables (without values)
+- .env.local for local development overrides
+- .gitignore entries for sensitive files
+- README documentation for setup
+- Type definitions for TypeScript projects
+- Validation schemas for required variables
+- Default values for non-sensitive configuration
+
+**Validate Configuration:**
+```bash
+/env-config-manager validate --env=production --strict=true
+```
+Validates environment configuration including:
+- Required variables presence check
+- Type validation (string, number, boolean, url, email)
+- Format validation (URLs, ports, connection strings)
+- Value range checking (min/max for numbers)
+- Enum value validation for restricted options
+- Cross-variable dependency validation
+- Security checks (no hardcoded secrets in code)
+- Unused variable detection
+
+**Generate Types:**
+```bash
+/env-config-manager generate-types --output=./types/env.d.ts
+```
+Generates TypeScript type definitions with:
+- Interface definitions for process.env
+- Type-safe environment variable access
+- JSDoc comments with descriptions
+- Enum types for restricted values
+- Required vs optional property marking
+- Default value documentation
+- Environment-specific types
+- Auto-completion support in IDEs
+
+### Secrets Management
+
+**HashiCorp Vault Integration:**
+```bash
+/env-config-manager vault --action=sync --path=secret/myapp --env=production
+```
+Manages secrets with Vault including:
+- Secret reading from Vault paths
+- Writing secrets to Vault with versioning
+- Dynamic secret generation (database credentials)
+- Lease management and renewal
+- Token authentication and renewal
+- AppRole and Kubernetes auth methods
+- Secret rotation scheduling
+- Audit log integration
+
+**AWS Secrets Manager:**
+```bash
+/env-config-manager aws-secrets --region=us-east-1 --sync=true
+```
+Integrates with AWS Secrets Manager:
+- Secret creation with KMS encryption
+- Automatic secret rotation setup
+- Version management and staging labels
+- Resource-based access policies
+- CloudFormation integration
+- Cross-region replication
+- Secret recovery and deletion
+- Cost optimization recommendations
+
+**Azure Key Vault:**
+```bash
+/env-config-manager azure-keyvault --vault=myapp-vault --managed-identity=true
+```
+Manages Azure Key Vault secrets with:
+- Secret, key, and certificate management
+- Managed identity authentication
+- Soft-delete and purge protection
+- Access policies and RBAC
+- Secret versioning and backup
+- Virtual network restrictions
+- Private endpoint configuration
+- Compliance and monitoring
+
+### Configuration Patterns
+
+**Multi-Environment Strategy:**
+```bash
+/env-config-manager multi-env --strategy=hierarchical --base=.env.base
+```
+Implements environment hierarchy with:
+- Base configuration shared across environments
+- Environment-specific overrides (.env.dev, .env.prod)
+- Local development overrides (.env.local)
+- Priority and merge strategies
+- Environment detection logic
+- Validation per environment
+- Documentation generation
+- Migration scripts between environments
+
+**Configuration Schema:**
+```bash
+/env-config-manager schema --format=json-schema --output=./config.schema.json
+```
+Creates configuration schemas with:
+- JSON Schema or YAML schema definition
+- Required and optional fields
+- Type constraints and validation rules
+- Default values specification
+- Description and examples
+- Secret field marking
+- Environment-specific requirements
+- Version tracking
+
+**Secret Encryption:**
+```bash
+/env-config-manager encrypt --method=age --public-key=./key.pub
+```
+Encrypts configuration files with:
+- Age encryption for simplicity and security
+- GPG encryption for traditional workflows
+- KMS encryption for cloud-native apps
+- Symmetric encryption for team sharing
+- Key management and rotation
+- Encrypted file versioning in git
+- Decryption automation in CI/CD
+- Emergency access procedures
+
+### Security Features
+
+**Secret Detection:**
+```bash
+/env-config-manager detect-secrets --scan=./src --prevent-commit=true
+```
+Scans for accidentally committed secrets:
+- Pattern-based secret detection
+- Entropy analysis for random strings
+- API key and token recognition
+- Private key detection
+- Password pattern matching
+- Database connection string scanning
+- Pre-commit hook integration
+- Historical commit scanning
+
+**Access Control:**
+```bash
+/env-config-manager access-control --role=developer --env=production
+```
+Manages configuration access with:
+- Role-based access control (RBAC)
+- Environment-based restrictions
+- Secret-level permissions
+- Time-based access (temporary grants)
+- Approval workflows for production
+- Audit trail of all access
+- IP allowlisting for sensitive environments
+- Multi-factor authentication integration
+
+**Secret Rotation:**
+```bash
+/env-config-manager rotate --secrets=DB_PASSWORD,API_KEY --schedule=30d
+```
+Automates secret rotation including:
+- Scheduled rotation policies
+- Zero-downtime rotation strategies
+- Automatic application restart
+- Multi-step rotation (dual secrets)
+- Rollback capabilities
+- Notification on rotation
+- Rotation testing and validation
+- Compliance reporting
+
+## Code Generation Examples
+
+### Environment Configuration (Node.js)
+```javascript
+// config/env.js
+const dotenv = require('dotenv');
+const path = require('path');
+const Joi = require('joi');
+
+// Load environment-specific configuration
+const envFile = `.env.${process.env.NODE_ENV || 'development'}`;
+dotenv.config({ path: path.resolve(__dirname, '../', envFile) });
+dotenv.config({ path: path.resolve(__dirname, '../', '.env.local') });
+dotenv.config({ path: path.resolve(__dirname, '../', '.env') });
+
+// Configuration schema
+const envSchema = Joi.object({
+  NODE_ENV: Joi.string()
+    .valid('development', 'staging', 'production', 'test')
+    .default('development'),
+
+  PORT: Joi.number()
+    .integer()
+    .min(1024)
+    .max(65535)
+    .default(3000)
+    .description('Server port number'),
+
+  DATABASE_URL: Joi.string()
+    .uri({ scheme: ['postgres', 'postgresql'] })
+    .required()
+    .description('PostgreSQL connection string'),
+
+  REDIS_URL: Joi.string()
+    .uri({ scheme: ['redis', 'rediss'] })
+    .required()
+    .description('Redis connection string'),
+
+  JWT_SECRET: Joi.string()
+    .min(32)
+    .required()
+    .description('JWT signing secret (min 32 characters)'),
+
+  JWT_EXPIRES_IN: Joi.string()
+    .pattern(/^\d+[dhms]$/)
+    .default('7d')
+    .description('JWT expiration time'),
+
+  AWS_REGION: Joi.string()
+    .when('NODE_ENV', {
+      is: 'production',
+      then: Joi.required(),
+      otherwise: Joi.optional()
+    })
+    .description('AWS region for services'),
+
+  AWS_ACCESS_KEY_ID: Joi.string()
+    .when('NODE_ENV', {
+      is: 'production',
+      then: Joi.required(),
+      otherwise: Joi.optional()
+    }),
+
+  AWS_SECRET_ACCESS_KEY: Joi.string()
+    .when('NODE_ENV', {
+      is: 'production',
+      then: Joi.required(),
+      otherwise: Joi.optional()
+    }),
+
+  STRIPE_API_KEY: Joi.string()
+    .pattern(/^sk_(test|live)_[a-zA-Z0-9]+$/)
+    .required()
+    .description('Stripe API key'),
+
+  SENDGRID_API_KEY: Joi.string()
+    .pattern(/^SG\.[a-zA-Z0-9_-]+$/)
+    .required()
+    .description('SendGrid API key'),
+
+  API_RATE_LIMIT: Joi.number()
+    .integer()
+    .min(10)
+    .max(10000)
+    .default(100)
+    .description('API rate limit per minute'),
+
+  LOG_LEVEL: Joi.string()
+    .valid('error', 'warn', 'info', 'http', 'debug')
+    .default('info')
+    .description('Logging level'),
+
+  CORS_ORIGIN: Joi.alternatives()
+    .try(
+      Joi.string().uri(),
+      Joi.string().valid('*'),
+      Joi.array().items(Joi.string().uri())
+    )
+    .default('*')
+    .description('CORS allowed origins')
+}).unknown(false);
+
+// Validate environment variables
+const { error, value: config } = envSchema.validate(process.env, {
+  abortEarly: false,
+  stripUnknown: true
+});
+
+if (error) {
+  const errors = error.details.map(detail => detail.message).join('\n');
+  throw new Error(`Environment validation failed:\n${errors}`);
+}
+
+// Export validated configuration
+module.exports = {
+  env: config.NODE_ENV,
+  port: config.PORT,
+
+  database: {
+    url: config.DATABASE_URL
+  },
+
+  redis: {
+    url: config.REDIS_URL
+  },
+
+  jwt: {
+    secret: config.JWT_SECRET,
+    expiresIn: config.JWT_EXPIRES_IN
+  },
+
+  aws: {
+    region: config.AWS_REGION,
+    accessKeyId: config.AWS_ACCESS_KEY_ID,
+    secretAccessKey: config.AWS_SECRET_ACCESS_KEY
+  },
+
+  stripe: {
+    apiKey: config.STRIPE_API_KEY
+  },
+
+  sendgrid: {
+    apiKey: config.SENDGRID_API_KEY
+  },
+
+  api: {
+    rateLimit: config.API_RATE_LIMIT
+  },
+
+  logging: {
+    level: config.LOG_LEVEL
+  },
+
+  cors: {
+    origin: config.CORS_ORIGIN
+  }
+};
+```
+
+### TypeScript Type Definitions
+```typescript
+// types/env.d.ts
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      /** Application environment */
+      NODE_ENV: 'development' | 'staging' | 'production' | 'test';
+
+      /** Server port number (1024-65535) */
+      PORT: string;
+
+      /** PostgreSQL connection string */
+      DATABASE_URL: string;
+
+      /** Redis connection string */
+      REDIS_URL: string;
+
+      /** JWT signing secret (minimum 32 characters) */
+      JWT_SECRET: string;
+
+      /** JWT expiration time (e.g., "7d", "24h") */
+      JWT_EXPIRES_IN?: string;
+
+      /** AWS region for services (required in production) */
+      AWS_REGION?: string;
+
+      /** AWS access key ID (required in production) */
+      AWS_ACCESS_KEY_ID?: string;
+
+      /** AWS secret access key (required in production) */
+      AWS_SECRET_ACCESS_KEY?: string;
+
+      /** Stripe API key (sk_test_* or sk_live_*) */
+      STRIPE_API_KEY: string;
+
+      /** SendGrid API key (SG.*) */
+      SENDGRID_API_KEY: string;
+
+      /** API rate limit per minute (10-10000) */
+      API_RATE_LIMIT?: string;
+
+      /** Logging level */
+      LOG_LEVEL?: 'error' | 'warn' | 'info' | 'http' | 'debug';
+
+      /** CORS allowed origins */
+      CORS_ORIGIN?: string;
+    }
+  }
+}
+
+export {};
+```
+
+### Vault Integration (Go)
+```go
+package config
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "os"
+    "time"
+
+    vault "github.com/hashicorp/vault/api"
+)
+
+type VaultConfig struct {
+    client    *vault.Client
+    mountPath string
+    secretPath string
+}
+
+func NewVaultConfig() (*VaultConfig, error) {
+    config := vault.DefaultConfig()
+    config.Address = os.Getenv("VAULT_ADDR")
+
+    client, err := vault.NewClient(config)
+    if err != nil {
+        return nil, fmt.Errorf("failed to create vault client: %w", err)
+    }
+
+    // Authenticate using token
+    token := os.Getenv("VAULT_TOKEN")
+    if token != "" {
+        client.SetToken(token)
+    } else {
+        // Authenticate using AppRole
+        if err := authenticateAppRole(client); err != nil {
+            return nil, fmt.Errorf("vault authentication failed: %w", err)
+        }
+    }
+
+    return &VaultConfig{
+        client:     client,
+        mountPath:  "secret",
+        secretPath: "myapp",
+    }, nil
+}
+
+func authenticateAppRole(client *vault.Client) error {
+    roleID := os.Getenv("VAULT_ROLE_ID")
+    secretID := os.Getenv("VAULT_SECRET_ID")
+
+    data := map[string]interface{}{
+        "role_id":   roleID,
+        "secret_id": secretID,
+    }
+
+    resp, err := client.Logical().Write("auth/approle/login", data)
+    if err != nil {
+        return err
+    }
+
+    client.SetToken(resp.Auth.ClientToken)
+
+    // Start token renewal goroutine
+    go renewToken(client, resp.Auth.LeaseDuration)
+
+    return nil
+}
+
+func renewToken(client *vault.Client, leaseDuration int) {
+    ticker := time.NewTicker(time.Duration(leaseDuration/2) * time.Second)
+    defer ticker.Stop()
+
+    for range ticker.C {
+        secret, err := client.Auth().Token().RenewSelf(leaseDuration)
+        if err != nil {
+            log.Printf("Failed to renew token: %v", err)
+            continue
+        }
+        log.Printf("Token renewed, new TTL: %d seconds", secret.Auth.LeaseDuration)
+    }
+}
+
+func (vc *VaultConfig) GetSecret(key string) (string, error) {
+    path := fmt.Sprintf("%s/data/%s", vc.mountPath, vc.secretPath)
+
+    secret, err := vc.client.Logical().Read(path)
+    if err != nil {
+        return "", fmt.Errorf("failed to read secret: %w", err)
+    }
+
+    if secret == nil || secret.Data == nil {
+        return "", fmt.Errorf("secret not found")
+    }
+
+    // KV v2 stores data under "data" key
+    data, ok := secret.Data["data"].(map[string]interface{})
+    if !ok {
+        return "", fmt.Errorf("invalid secret format")
+    }
+
+    value, ok := data[key].(string)
+    if !ok {
+        return "", fmt.Errorf("secret key not found: %s", key)
+    }
+
+    return value, nil
+}
+
+func (vc *VaultConfig) SetSecret(key, value string) error {
+    path := fmt.Sprintf("%s/data/%s", vc.mountPath, vc.secretPath)
+
+    // First, read existing secrets to preserve them
+    existing, err := vc.client.Logical().Read(path)
+    if err != nil {
+        return fmt.Errorf("failed to read existing secrets: %w", err)
+    }
+
+    data := make(map[string]interface{})
+    if existing != nil && existing.Data != nil {
+        if existingData, ok := existing.Data["data"].(map[string]interface{}); ok {
+            data = existingData
+        }
+    }
+
+    // Update with new value
+    data[key] = value
+
+    // Write back to vault
+    payload := map[string]interface{}{
+        "data": data,
+    }
+
+    _, err = vc.client.Logical().Write(path, payload)
+    if err != nil {
+        return fmt.Errorf("failed to write secret: %w", err)
+    }
+
+    return nil
+}
+
+func (vc *VaultConfig) RotateSecret(ctx context.Context, key string, generator func() (string, error)) error {
+    // Generate new secret value
+    newValue, err := generator()
+    if err != nil {
+        return fmt.Errorf("failed to generate new secret: %w", err)
+    }
+
+    // Store new secret
+    if err := vc.SetSecret(key, newValue); err != nil {
+        return fmt.Errorf("failed to store new secret: %w", err)
+    }
+
+    log.Printf("Secret %s rotated successfully", key)
+    return nil
+}
+
+// Example usage
+func LoadConfig() (*AppConfig, error) {
+    vaultConfig, err := NewVaultConfig()
+    if err != nil {
+        return nil, err
+    }
+
+    dbPassword, err := vaultConfig.GetSecret("DB_PASSWORD")
+    if err != nil {
+        return nil, err
+    }
+
+    apiKey, err := vaultConfig.GetSecret("API_KEY")
+    if err != nil {
+        return nil, err
+    }
+
+    return &AppConfig{
+        DatabasePassword: dbPassword,
+        APIKey:          apiKey,
+    }, nil
+}
+```
+
+## Best Practices
+
+### Environment File Management
+- **Never Commit Secrets**: Always add .env files to .gitignore
+- **Use .env.example**: Provide template with variable names (no values)
+- **Environment Hierarchy**: Base configuration + environment-specific overrides
+- **Type Validation**: Validate types and formats, not just presence
+- **Documentation**: Document each variable's purpose and format
+
+### Secrets Management
+- **Centralized Storage**: Store secrets in dedicated secret managers
+- **Least Privilege**: Grant minimal necessary access to secrets
+- **Rotation Policy**: Implement regular secret rotation (30-90 days)
+- **Encryption at Rest**: Always encrypt secrets in storage
+- **Audit Logging**: Track all secret access and modifications
+
+### Security Best Practices
+- **Secret Detection**: Scan code for accidentally committed secrets
+- **Access Control**: Implement RBAC for configuration access
+- **Encryption in Transit**: Use TLS for all secret retrieval
+- **Emergency Procedures**: Document secret compromise response
+- **Compliance**: Ensure SOC2, HIPAA, PCI-DSS compliance as needed
+
+### Development Workflow
+- **Local Overrides**: Use .env.local for developer-specific settings
+- **CI/CD Integration**: Inject secrets from secret manager in pipelines
+- **Testing**: Use separate secrets for testing environments
+- **Onboarding**: Simplify new developer setup with clear documentation
+- **Version Control**: Track configuration schema changes in git
+
+---
+
+**ClaudeForge Environment Config Manager** - Enterprise-grade configuration and secrets management with comprehensive validation, multi-platform integration, and security-first architecture for modern applications.