From d765af1a6c033345ca331deddb0b167b3b27a4cf Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:13:12 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + commands/env-config-manager.md | 635 +++++++++++++++++++++++++++++++++ plugin.lock.json | 45 +++ 4 files changed, 695 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/env-config-manager.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..3e5c38a --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "env-config-manager", + "description": "ClaudeForge Enterprise Environment Configuration Manager delivering comprehensive secrets management, configuration validation excellence, and multi-environment orchestration that transforms environment configuration from scattered files into centralized, secure, and intelligent configuration systems with enterprise-grade security", + "version": "1.0.0", + "author": { + "name": "ClaudeForge Community", + "url": "https://github.com/claudeforge/marketplace" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..3069a6c --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# env-config-manager + +ClaudeForge Enterprise Environment Configuration Manager delivering comprehensive secrets management, configuration validation excellence, and multi-environment orchestration that transforms environment configuration from scattered files into centralized, secure, and intelligent configuration systems with enterprise-grade security diff --git a/commands/env-config-manager.md b/commands/env-config-manager.md new file mode 100644 index 0000000..a796508 --- /dev/null +++ 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. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..1ea899e --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,45 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:claudeforge/marketplace:plugins/commands/env-config-manager", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "69736c9aca6304551268ade228548f52bd46d71c", + "treeHash": "73ab1715d8991b0cba1ad6e6bc372034aa94a18c8d5c3aeb0f0a1649d34d897f", + "generatedAt": "2025-11-28T10:15:29.579495Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "env-config-manager", + "description": "ClaudeForge Enterprise Environment Configuration Manager delivering comprehensive secrets management, configuration validation excellence, and multi-environment orchestration that transforms environment configuration from scattered files into centralized, secure, and intelligent configuration systems with enterprise-grade security", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "352b53b4f616cc8cc4dd9956d5737b4572ab11b85bb2e0c1a2ba9542056f4d36" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "2280d23631e52006f0f6dd18dd8a996ce56017bbdef86b66a799edeed97cae9f" + }, + { + "path": "commands/env-config-manager.md", + "sha256": "4373fdb5ece0cb89248ef8d1149af17530617d1ec8884c13a6759595fcc50239" + } + ], + "dirSha256": "73ab1715d8991b0cba1ad6e6bc372034aa94a18c8d5c3aeb0f0a1649d34d897f" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file