docs update

Author: jszobody

docs/.vitepress/config.mjs

@@ -28,6 +28,7 @@ export default defineConfig({
           items: [
             { text: 'Introduction', link: '/guide/' },
             { text: 'Installation', link: '/guide/installation' },
+            { text: 'AWS Authentication', link: '/guide/aws-authentication' },
             { text: 'Configuration', link: '/guide/configuration' },
             { text: 'Quick Start', link: '/guide/quick-start' }
           ]

docs/examples/index.md

@@ -1,63 +1,42 @@
 # Examples
 
-This section provides practical examples of using Keep in real-world scenarios. These examples will help you understand how to integrate Keep into your workflow and get the most out of its features.
-
 ## Available Examples
 
 ### [Laravel Integration](./laravel)
-Learn how to integrate Keep with your Laravel applications, including:
-- Service provider setup
-- Helper function usage  
-- Caching strategies
-- Development workflow
+Integrate Keep with Laravel applications using the service provider and helper functions.
 
 ### [CI/CD Workflows](./ci-cd)
-Examples of using Keep in continuous integration and deployment:
-- GitHub Actions integration
-- Automated secret deployment
-- Environment promotion strategies
-- Security best practices
+Use Keep in GitHub Actions, GitLab CI, and other automation pipelines.
 
 ### [Multi-Environment Setup](./multi-environment)
-Best practices for organizing secrets across multiple environments:
-- Stage organization strategies
-- Vault selection guidelines
-- Secret promotion workflows
-- Team access patterns
+Organize secrets across development, staging, and production environments.
 
 ### [AWS Setup](./aws-setup)
-Complete guide to setting up Keep with AWS services:
-- IAM roles and permissions
-- SSM Parameter Store configuration
-- Secrets Manager setup
-- Cross-account access patterns
+Configure IAM roles, SSM Parameter Store, and Secrets Manager for Keep.
 
-## Common Workflows
+## Quick Examples
 
-### Development to Production Flow
+### Development to Production
 ```bash
-# 1. Set up local development
+# Configure project
 keep configure
-keep vault:add local myapp
-keep set myapp:development API_KEY "dev-key-123"
+keep vault:add
+
+# Set development secret
+keep set API_KEY "dev-key" --stage=development
 
-# 2. Set up staging environment  
-keep vault:add aws-ssm staging-vault
-keep copy myapp:development staging-vault:staging API_KEY
+# Copy to staging
+keep copy API_KEY --from=development --to=staging
 
-# 3. Promote to production
-keep vault:add aws-secrets prod-vault  
-keep copy staging-vault:staging prod-vault:production API_KEY
+# Promote to production
+keep copy API_KEY --from=staging --to=production
 ```
 
-### Template-Based Configuration
+### Using Templates
 ```bash
-# Create template file
-echo "API_KEY={myapp:API_KEY}" > app.env.template
-
-# Generate configuration
-keep template:validate app.env.template myapp:production
-keep template:merge app.env.template myapp:production > app.env
-```
+# Create template
+echo "API_KEY={ssm:API_KEY}" > .env.template
 
-Each example includes complete code samples, configuration files, and step-by-step instructions to help you implement similar patterns in your own projects.
+# Generate config
+keep merge .env.template --stage=production --output=.env
+```

docs/guide/aws-authentication.md

@@ -0,0 +1,275 @@
+# AWS Authentication
+
+Keep uses AWS services (SSM Parameter Store and Secrets Manager) to store your secrets. This page explains how to properly configure AWS authentication so Keep can access these vaults.
+
+## The Secret Zero Problem
+
+Before diving into solutions, it's worth understanding the "Secret Zero" problem: if Keep fetches secrets from AWS to generate your `.env` file, but AWS credentials are typically stored in `.env` files... we have a circular dependency. You need credentials to get credentials.
+
+The solution is to keep AWS authentication separate from your application secrets.
+
+## What NOT to Do
+
+```env
+# .env file - DON'T DO THIS with Keep!
+AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+DB_PASSWORD=my-secret-password
+API_KEY=sk_live_abc123
+```
+
+Storing AWS credentials in `.env` defeats the purpose of Keep. You're storing the keys to the vault alongside the secrets themselves.
+
+## Authentication Methods
+
+### Development Environment
+
+**Option 1: AWS CLI Configuration (Good)**
+
+Use the AWS CLI's standard credential file:
+
+```bash
+# Configure AWS CLI
+aws configure
+
+# This creates ~/.aws/credentials
+[default]
+aws_access_key_id = AKIAIOSFODNN7EXAMPLE
+aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+region = us-east-1
+```
+
+Keep automatically uses these credentials. Your `.env` file stays clean:
+
+```env
+# .env - generated by Keep, no AWS credentials!
+DB_PASSWORD=my-secret-password
+API_KEY=sk_live_abc123
+```
+
+**Option 2: aws-vault (Better)**
+
+[aws-vault](https://github.com/99designs/aws-vault) stores credentials encrypted in your OS keychain:
+
+```bash
+# Install aws-vault
+brew install aws-vault  # macOS
+# or download from GitHub releases
+
+# Add your default AWS profile, or use a named profile
+aws-vault add default
+```
+
+Edit your ~/.aws/config to set a default region and use aws-vault for credential_process:
+
+```ini
+[default]
+region = us-east-1
+credential_process = aws-vault exec default --json  --no-session
+```
+
+Edit your ~/.aws/credentials and add the same credential_process:
+
+```ini
+[default]
+credential_process = aws-vault exec default --json  --no-session
+```
+
+Now when you run Keep (or any AWS CLI command), it will use aws-vault to fetch temporary credentials automatically.
+
+**Option 3: AWS SSO (Best for Teams)**
+
+If your organization uses AWS SSO:
+
+```bash
+# Configure SSO
+aws configure sso
+
+# Login
+aws sso login --profile myproject
+
+# Keep uses the SSO session automatically
+keep list --stage=development
+```
+
+### Production Environment
+
+**Option 1: EC2 Instance Roles (Best for AWS)**
+
+When running on EC2, ECS, or Lambda, use IAM roles:
+
+```bash
+# No credentials needed in your application!
+# The AWS SDK automatically uses the instance role
+
+# In your deployment script:
+keep export --stage=production --output=.env
+php artisan config:cache
+```
+
+Configure your EC2 instance role with appropriate IAM permissions for your vault type.
+
+**Option 2: Non-AWS Servers**
+
+For servers outside AWS, you have limited secure options:
+
+```bash
+# Option A: Credentials file on server (secured with proper permissions)
+# /home/myapp/.aws/credentials (chmod 600)
+[default]
+aws_access_key_id = AKIAIOSFODNN7EXAMPLE
+aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+
+# Option B: Environment variables set during provisioning
+# For systemd services: /etc/systemd/system/myapp.service.d/override.conf
+[Service]
+Environment="AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE"
+Environment="AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+
+# For Docker: passed securely during container start
+docker run -e AWS_ACCESS_KEY_ID=... -e AWS_SECRET_ACCESS_KEY=... myapp
+
+# For traditional setups: /etc/environment or user's ~/.bashrc
+```
+
+## CI/CD Pipelines
+
+**GitHub Actions**
+
+Use OIDC (recommended) or secrets:
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+on: push
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # for OIDC
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/github-actions
+          aws-region: us-east-1
+      
+      - run: |
+          vendor/bin/keep export --stage=production --output=.env
+          # Deploy your application
+```
+
+**GitLab CI**
+
+```yaml
+# .gitlab-ci.yml
+deploy:
+  script:
+    # Using GitLab's AWS integration
+    - vendor/bin/keep export --stage=production --output=.env
+  id_tokens:
+    AWS_TOKEN:
+      aud: https://gitlab.com
+```
+
+## Security Best Practices
+
+### Never Do This
+
+❌ Store AWS credentials in your repository  
+❌ Put AWS credentials in `.env` files tracked by git  
+❌ Use long-lived AWS access keys in production  
+❌ Share AWS credentials between environments  
+
+### Always Do This
+
+✅ Use temporary credentials when possible (aws-vault, SSO, instance roles)  
+✅ Apply least-privilege IAM policies  
+✅ Rotate credentials regularly  
+✅ Use different credentials for each environment  
+✅ Audit credential usage with CloudTrail  
+
+## Quick Decision Guide
+
+| Environment | Hosting | Recommended Solution |
+|------------|---------|---------------------|
+| Development | Local | aws-vault or AWS SSO |
+| Production | EC2/ECS | Instance/Task IAM Roles |
+| Production | Lambda | Lambda Execution Role |
+| Production | Kubernetes (EKS) | IRSA (Service Accounts) |
+| Production | Non-AWS | ~/.aws/credentials (secured) |
+| CI/CD | GitHub Actions | OIDC with IAM Role |
+| CI/CD | GitLab | OIDC with IAM Role |
+| CI/CD | Other | Secure secret storage |
+
+## IAM Permissions
+
+After setting up authentication, you need to configure IAM permissions for the AWS services Keep will access:
+
+- **For AWS SSM Parameter Store**: See [SSM IAM Permissions](/guide/vaults/aws-ssm#iam-permissions)
+- **For AWS Secrets Manager**: See [Secrets Manager IAM Permissions](/guide/vaults/aws-secrets-manager#iam-permissions)
+
+Each vault type requires specific IAM permissions based on your usage pattern (read-only, read-write, or admin access).
+
+## Laravel-Specific Considerations
+
+When using Keep with Laravel:
+
+1. **Don't cache config with AWS credentials**
+   ```php
+   // config/aws.php - DON'T DO THIS
+   'credentials' => [
+       'key'    => env('AWS_ACCESS_KEY_ID'),
+       'secret' => env('AWS_SECRET_ACCESS_KEY'),
+   ]
+   ```
+
+2. **Let the SDK find credentials automatically**
+   ```php
+   // config/aws.php - DO THIS
+   'credentials' => null, // SDK will use IAM role, ~/.aws/credentials, etc.
+   ```
+
+3. **Generate .env before config:cache**
+   ```bash
+   # deployment.sh
+   keep export --stage=production --output=.env
+   php artisan config:cache
+   php artisan route:cache
+   ```
+
+## Troubleshooting
+
+**"Keep can't find AWS credentials"**
+
+Check credential chain:
+```bash
+# 1. Environment variables
+env | grep AWS
+
+# 2. Credentials file
+cat ~/.aws/credentials
+
+# 3. Instance role (on EC2)
+curl http://169.254.169.254/latest/meta-data/iam/security-credentials/
+
+# 4. Test with AWS CLI
+aws sts get-caller-identity
+```
+
+**"Access denied when Keep tries to fetch secrets"**
+
+Verify IAM permissions:
+```bash
+# Test SSM access
+aws ssm get-parameter --name /myapp/production/test
+
+# Test Secrets Manager access  
+aws secretsmanager get-secret-value --secret-id myapp/production/test
+```
+
+## Summary
+
+The Secret Zero problem is real, but solvable. By keeping AWS credentials **out** of your application configuration and using platform-native credential management, you maintain security while enabling Keep to manage your application secrets effectively.
+
+Remember: Keep manages your application secrets, not your AWS credentials. Keep AWS credentials separate, secure, and platform-appropriate.