env-secrets 0.2.0 → 0.3.0

package/website/docs/best-practices.mdx

@@ -0,0 +1,416 @@
+---
+title: Best Practices
+---
+
+# Best Practices
+
+This guide outlines best practices for using `env-secrets` effectively and securely.
+
+## Secret Management
+
+### Secret Structure
+
+**✅ Good: Flat, focused secrets**
+
+```json
+{
+  "DATABASE_URL": "postgres://user:pass@localhost:5432/db",
+  "API_KEY": "abc123",
+  "REDIS_URL": "redis://localhost:6379"
+}
+```
+
+**❌ Avoid: Overly nested structures**
+
+```json
+{
+  "app": {
+    "database": {
+      "connection": {
+        "url": "postgres://user:pass@localhost:5432/db"
+      }
+    }
+  }
+}
+```
+
+### Secret Naming
+
+**✅ Good: Environment-specific naming**
+
+```bash
+# Development
+dev/myapp/database
+dev/myapp/api-keys
+
+# Staging
+staging/myapp/database
+staging/myapp/api-keys
+
+# Production
+prod/myapp/database
+prod/myapp/api-keys
+```
+
+**❌ Avoid: Generic names**
+
+```bash
+# Too generic
+database
+api-keys
+secrets
+```
+
+### Secret Size
+
+**✅ Good: Keep secrets small and focused**
+
+```bash
+# Separate secrets by concern
+aws secretsmanager create-secret \
+  --name prod/myapp/database \
+  --secret-string '{"DATABASE_URL":"postgres://..."}'
+
+aws secretsmanager create-secret \
+  --name prod/myapp/api \
+  --secret-string '{"API_KEY":"abc123","API_SECRET":"xyz789"}'
+```
+
+**❌ Avoid: Large, monolithic secrets**
+
+```bash
+# Too large and mixed concerns
+aws secretsmanager create-secret \
+  --name prod/myapp/all-config \
+  --secret-string '{"database":"...","api":"...","redis":"...","email":"...","logging":"..."}'
+```
+
+## Security Practices
+
+### IAM Policies
+
+**✅ Good: Least privilege access**
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": "secretsmanager:GetSecretValue",
+      "Resource": [
+        "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/myapp/*",
+        "arn:aws:secretsmanager:us-east-1:123456789012:secret:staging/myapp/*"
+      ]
+    }
+  ]
+}
+```
+
+> **Note:** Replace `123456789012` with your actual AWS account ID in the resource ARNs above.
+
+**❌ Avoid: Overly permissive policies**
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": "secretsmanager:*",
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+### Credential Management
+
+**✅ Good: Use IAM roles**
+
+```bash
+# On EC2/ECS/Lambda
+env-secrets aws -s prod/myapp -r us-east-1 -- node app.js
+```
+
+**✅ Good: Use environment variables for CI/CD**
+
+```bash
+# In CI/CD pipeline
+export AWS_ACCESS_KEY_ID=$CI_AWS_ACCESS_KEY_ID
+export AWS_SECRET_ACCESS_KEY=$CI_AWS_SECRET_ACCESS_KEY
+export AWS_DEFAULT_REGION=us-east-1
+
+env-secrets aws -s prod/myapp -r us-east-1 -- npm run deploy
+```
+
+**❌ Avoid: Hardcoded credentials**
+
+```bash
+# Don't do this
+env-secrets aws -s prod/myapp -r us-east-1 -p my-profile -- node app.js
+# Where my-profile contains hardcoded credentials
+```
+
+## Application Integration
+
+### Environment Variable Validation
+
+**✅ Good: Validate required variables**
+
+```javascript
+// app.js
+const requiredEnvVars = ['DATABASE_URL', 'API_KEY', 'REDIS_URL'];
+
+for (const envVar of requiredEnvVars) {
+  if (!process.env[envVar]) {
+    console.error(`Missing required environment variable: ${envVar}`);
+    process.exit(1);
+  }
+}
+
+console.log('All required environment variables are present');
+```
+
+### Graceful Degradation
+
+**✅ Good: Handle missing secrets gracefully**
+
+```bash
+#!/bin/bash
+# start.sh
+
+# Try to load secrets, but don't fail if they're not available
+if env-secrets aws -s dev/myapp -r us-east-1 -- echo "Secrets loaded" 2>/dev/null; then
+  echo "Running with secrets from AWS"
+  env-secrets aws -s dev/myapp -r us-east-1 -- node app.js
+else
+  echo "Running with local environment variables"
+  node app.js
+fi
+```
+
+## Development Workflow
+
+### Local Development
+
+**✅ Good: Use separate development secrets**
+
+```bash
+# Create development secrets
+aws secretsmanager create-secret \
+  --name dev/myapp \
+  --secret-string '{
+    "DATABASE_URL": "postgres://dev:dev@localhost:5432/dev",
+    "API_KEY": "dev-key-123"
+  }'
+
+# Use in development
+env-secrets aws -s dev/myapp -r us-east-1 -- npm run dev
+```
+
+### Testing
+
+**✅ Good: Use test-specific secrets**
+
+```bash
+# Create test secrets
+aws secretsmanager create-secret \
+  --name test/myapp \
+  --secret-string '{
+    "DATABASE_URL": "postgres://test:test@localhost:5432/test",
+    "API_KEY": "test-key-456"
+  }'
+
+# Run tests with test secrets
+env-secrets aws -s test/myapp -r us-east-1 -- npm test
+```
+
+## Deployment Patterns
+
+### Blue-Green Deployment
+
+**✅ Good: Use environment-specific secrets**
+
+```bash
+# Blue environment
+env-secrets aws -s prod-blue/myapp -r us-east-1 -- node app.js
+
+# Green environment
+env-secrets aws -s prod-green/myapp -r us-east-1 -- node app.js
+```
+
+### Canary Deployment
+
+**✅ Good: Gradual secret rollout**
+
+```bash
+# Deploy to 10% of traffic with new secrets
+env-secrets aws -s prod-canary/myapp -r us-east-1 -- node app.js
+
+# Monitor and gradually increase
+env-secrets aws -s prod-stable/myapp -r us-east-1 -- node app.js
+```
+
+## Monitoring and Observability
+
+### Health Checks
+
+**✅ Good: Include secret validation in health checks**
+
+```bash
+#!/bin/bash
+# health-check.sh
+
+# Check if secrets are accessible
+if env-secrets aws -s health/check -r us-east-1 -- echo "OK" 2>/dev/null; then
+  echo "Secrets accessible"
+  exit 0
+else
+  echo "Secrets not accessible"
+  exit 1
+fi
+```
+
+### Logging
+
+**✅ Good: Log secret access (not values)**
+
+```bash
+# Log secret access for audit purposes
+env-secrets aws -s prod/myapp -r us-east-1 -- bash -c '
+  echo "Loading secrets from prod/myapp"
+  node app.js
+'
+```
+
+**❌ Avoid: Logging secret values**
+
+```bash
+# Never do this
+env-secrets aws -s prod/myapp -r us-east-1 -- bash -c '
+  echo "Database URL: $DATABASE_URL"  # DON'T DO THIS
+  node app.js
+'
+```
+
+## Performance Optimization
+
+### Region Selection
+
+**✅ Good: Use secrets in the same region as your application**
+
+```bash
+# If your app runs in us-west-2, store secrets there too
+env-secrets aws -s prod/myapp -r us-west-2 -- node app.js
+```
+
+### Secret Organization
+
+**✅ Good: Organize secrets by application and environment**
+
+```bash
+# Clear hierarchy
+prod/frontend/api-keys
+prod/frontend/database
+prod/backend/api-keys
+prod/backend/database
+staging/frontend/api-keys
+staging/frontend/database
+```
+
+## Error Handling
+
+### Robust Scripts
+
+**✅ Good: Handle errors gracefully**
+
+```bash
+#!/bin/bash
+# deploy.sh
+
+set -e  # Exit on any error
+
+echo "Starting deployment..."
+
+# Load secrets and deploy
+if env-secrets aws -s prod/myapp -r us-east-1 -- npm run deploy; then
+  echo "Deployment successful"
+else
+  echo "Deployment failed"
+  exit 1
+fi
+```
+
+### Fallback Strategies
+
+**✅ Good: Provide fallback options**
+
+```bash
+#!/bin/bash
+# start.sh
+
+# Try primary secrets first
+if env-secrets aws -s prod/myapp -r us-east-1 -- node app.js; then
+  echo "Started with primary secrets"
+else
+  echo "Primary secrets failed, trying backup..."
+  # Try backup secrets
+  env-secrets aws -s prod/myapp-backup -r us-east-1 -- node app.js
+fi
+```
+
+## Compliance and Audit
+
+### Access Logging
+
+**✅ Good: Enable CloudTrail logging**
+
+```bash
+# CloudTrail automatically logs all Secrets Manager access
+# No additional configuration needed with env-secrets
+```
+
+### Secret Rotation
+
+**✅ Good: Implement secret rotation**
+
+```bash
+# Rotate secrets regularly
+aws secretsmanager rotate-secret --secret-id prod/myapp/api-keys
+
+# Update applications to use new secret versions
+env-secrets aws -s prod/myapp/api-keys -r us-east-1 -- node app.js
+```
+
+## Common Anti-Patterns
+
+### ❌ Don't: Store secrets in version control
+
+```bash
+# Never commit secrets to git
+echo "DATABASE_URL=postgres://..." >> .env  # DON'T DO THIS
+```
+
+### ❌ Don't: Use the same secrets across environments
+
+```bash
+# Don't use production secrets in development
+env-secrets aws -s prod/myapp -r us-east-1 -- npm run dev  # DON'T DO THIS
+```
+
+### ❌ Don't: Share secrets between applications
+
+```bash
+# Don't use the same secret for multiple apps
+env-secrets aws -s shared/secrets -r us-east-1 -- node app1.js  # DON'T DO THIS
+env-secrets aws -s shared/secrets -r us-east-1 -- node app2.js  # DON'T DO THIS
+```
+
+### ❌ Don't: Use long-lived access keys
+
+```bash
+# Prefer IAM roles over long-lived access keys
+export AWS_ACCESS_KEY_ID=AKIA...  # DON'T DO THIS
+export AWS_SECRET_ACCESS_KEY=...   # DON'T DO THIS
+```

package/website/docs/cli-reference.mdx

@@ -0,0 +1,204 @@
+---
+title: CLI Reference
+---
+
+# CLI Reference
+
+The `env-secrets` command-line interface provides a simple way to inject secrets as environment variables into your applications.
+
+## Basic Syntax
+
+```bash
+env-secrets <provider> [options] -- <program-to-run>
+```
+
+## Providers
+
+Currently supported provider: `aws`
+
+## AWS Secrets Manager Options
+
+### Required Parameters
+
+- `-s, --secret <secret-name>` - The name or ARN of the secret in AWS Secrets Manager
+
+### Optional Parameters
+
+- `-r, --region <region>` - AWS region where the secret is stored (defaults to `AWS_DEFAULT_REGION`)
+- `-p, --profile <profile>` - AWS profile to use (defaults to environment variables or IAM role)
+- `-o, --output <file>` - Output secrets to a file instead of injecting into environment variables. File will be created with 0400 permissions and will not overwrite existing files
+
+### Global Options
+
+- `--help` - Show help information
+- `--version` - Show version information
+
+## Examples
+
+### Basic Usage
+
+```bash
+# Run a Node.js application with secrets
+env-secrets aws -s my-app-secrets -r us-east-1 -- node app.js
+
+# Run a Python application
+env-secrets aws -s my-app-secrets -r us-east-1 -- python app.py
+
+# Run a shell command
+env-secrets aws -s my-app-secrets -r us-east-1 -- echo "Hello, $USER_NAME!"
+
+# Output secrets to a file
+env-secrets aws -s my-app-secrets -r us-east-1 -o secrets.env
+```
+
+### Environment Variable Inspection
+
+```bash
+# Check what environment variables are injected
+env-secrets aws -s my-app-secrets -r us-east-1 -- env | grep -E "(DATABASE|API|SECRET)"
+
+# List all environment variables
+env-secrets aws -s my-app-secrets -r us-east-1 -- env
+
+# Check specific variables
+env-secrets aws -s my-app-secrets -r us-east-1 -- bash -c 'echo "DB: $DATABASE_URL, API: $API_KEY"'
+```
+
+### Docker Integration
+
+```bash
+# Run Docker container with secrets
+env-secrets aws -s docker-secrets -r us-east-1 -- docker run \
+  -e DATABASE_URL \
+  -e API_KEY \
+  -e REDIS_URL \
+  my-app:latest
+
+# Use with docker-compose
+env-secrets aws -s docker-secrets -r us-east-1 -- docker-compose up
+```
+
+### Kubernetes Integration
+
+```bash
+# Run in Kubernetes pod
+env-secrets aws -s k8s-secrets -r us-east-1 -- node app.js
+
+# Use with kubectl exec
+kubectl exec -it my-pod -- env-secrets aws -s k8s-secrets -r us-east-1 -- node app.js
+```
+
+### CI/CD Pipelines
+
+```bash
+# GitHub Actions
+env-secrets aws -s prod/app -r us-east-1 -- npm run deploy
+
+# GitLab CI
+env-secrets aws -s prod/app -r us-east-1 -- npm run deploy
+```
+
+### Debug Mode
+
+```bash
+# Enable debug logging
+DEBUG=env-secrets env-secrets aws -s my-secret -r us-east-1 -- node app.js
+
+# Detailed debug logging
+DEBUG=env-secrets,env-secrets:secretsmanager env-secrets aws -s my-secret -r us-east-1 -- node app.js
+```
+
+### File Output Mode
+
+```bash
+# Output secrets to a file with secure permissions
+env-secrets aws -s my-app-secrets -r us-east-1 -o secrets.env
+
+# Output with specific profile
+env-secrets aws -s my-secret -r us-east-1 -p my-profile -o /tmp/secrets.env
+
+# File content example (secrets.env):
+# export DATABASE_URL=postgres://user:pass@localhost:5432/db
+# export API_KEY=abc123
+# export REDIS_URL=redis://localhost:6379
+
+# Source the file in your application
+source secrets.env
+node app.js
+
+# Or use with Docker
+env-secrets aws -s docker-secrets -r us-east-1 -o .env
+docker run --env-file .env my-app:latest
+```
+
+## Environment Variable Behavior
+
+### JSON Secret Parsing
+
+Secrets stored as JSON are automatically parsed and converted to environment variables:
+
+```bash
+# Secret content: {"DATABASE_URL":"postgres://...","API_KEY":"abc123"}
+# Results in: DATABASE_URL=postgres://..., API_KEY=abc123
+```
+
+### Nested Object Handling
+
+Nested JSON objects are flattened:
+
+```bash
+# Secret: {"database":{"url":"postgres://...","port":5432}}
+# Results in: DATABASE_URL=postgres://..., DATABASE_PORT=5432
+```
+
+### Array Handling
+
+Arrays are converted to comma-separated values:
+
+```bash
+# Secret: {"allowed_ips":["192.168.1.1","10.0.0.1"]}
+# Results in: ALLOWED_IPS=192.168.1.1,10.0.0.1
+```
+
+### Special Character Handling
+
+Special characters in keys are converted to underscores:
+
+```bash
+# Secret: {"api-key":"abc123","db_url":"postgres://..."}
+# Results in: API_KEY=abc123, DB_URL=postgres://...
+```
+
+## Error Handling
+
+### Common Error Messages
+
+| Error                       | Description                    | Solution                          |
+| --------------------------- | ------------------------------ | --------------------------------- |
+| `ConfigError`               | AWS credentials not configured | Set up AWS credentials or profile |
+| `ResourceNotFoundException` | Secret doesn't exist           | Verify secret name and region     |
+| `AccessDeniedException`     | Insufficient permissions       | Check IAM policies                |
+| `ValidationException`       | Invalid secret name            | Use valid secret name format      |
+
+### Exit Codes
+
+- `0` - Success
+- `1` - General error
+- `2` - Configuration error
+- `3` - Secret not found
+- `4` - Permission denied
+
+## Security Notes
+
+- **No Local Storage**: Secrets are never stored locally (unless using `-o` flag)
+- **Process Isolation**: Secrets are only injected into the child process
+- **No Logging**: Secret values are never logged
+- **Clean Exit**: Environment variables are cleaned up when the process exits
+- **File Security**: When using `-o` flag, files are created with 0400 permissions (read-only for owner) and existing files are never overwritten
+
+## Performance Considerations
+
+- **Network Latency**: First secret retrieval may take longer due to AWS API calls
+- **Region Proximity**: Use secrets in the same region as your application
+- **Secret Size**: Keep secrets small for better performance
+- **Connection Reuse**: AWS SDK connections are reused automatically