env-secrets 0.2.0 → 0.3.0

package/website/docs/security.mdx

@@ -0,0 +1,122 @@
+---
+title: Security Considerations
+---
+
+# Security Considerations
+
+When using `env-secrets` in your applications, it's important to understand the security implications and follow best practices.
+
+## Credential Management
+
+`env-secrets` respects AWS credential precedence in the following order:
+
+1. **Environment Variables** (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
+2. **IAM Roles** (when running on EC2, ECS, or Lambda)
+3. **AWS Profiles** (specified with `-p` flag)
+
+### Best Practices
+
+- **Use IAM Roles**: Prefer IAM roles over hardcoded credentials when possible
+- **Least Privilege**: Grant only `secretsmanager:GetSecretValue` permission
+- **Rotate Credentials**: Regularly rotate AWS access keys
+- **Environment Isolation**: Use different AWS accounts/profiles for different environments
+
+## Secret Exposure Prevention
+
+### What env-secrets does NOT do:
+
+- ❌ Store secrets locally on disk
+- ❌ Log secrets to console or files
+- ❌ Cache secrets in memory beyond the process lifetime
+- ❌ Expose secrets in process lists
+
+### What env-secrets does:
+
+- ✅ Injects secrets only into the child process environment
+- ✅ Cleans up environment variables when the process exits
+- ✅ Uses AWS SDK's built-in security features
+- ✅ Supports debug logging without exposing secret values
+
+## Network Security
+
+- **HTTPS Only**: All AWS API calls use HTTPS/TLS encryption
+- **AWS SDK Security**: Leverages AWS SDK's built-in security features
+- **No Local Storage**: No secrets are stored locally
+
+## Audit Trail
+
+All AWS Secrets Manager API calls are logged in AWS CloudTrail, providing:
+
+- Access timestamps
+- User/role information
+- Secret names accessed
+- API actions performed
+
+## Environment Variable Security
+
+### Child Process Isolation
+
+Secrets are only injected into the specified child process:
+
+```bash
+# Only the 'node app.js' process gets the secrets
+env-secrets aws -s my-secret -r us-east-1 -- node app.js
+
+# The parent shell environment remains unchanged
+echo $DATABASE_URL  # This will be empty
+```
+
+### Process Environment
+
+The child process receives environment variables in the same way as if they were set normally:
+
+```bash
+# These are equivalent:
+DATABASE_URL=postgres://... node app.js
+
+env-secrets aws -s my-secret -r us-east-1 -- node app.js
+```
+
+## Production Security Checklist
+
+Before deploying to production:
+
+- [ ] Use IAM roles instead of access keys
+- [ ] Implement least-privilege IAM policies
+- [ ] Enable AWS CloudTrail logging
+- [ ] Use separate AWS accounts for different environments
+- [ ] Regularly rotate secrets in AWS Secrets Manager
+- [ ] Monitor for unauthorized access attempts
+- [ ] Use VPC endpoints for AWS Secrets Manager (if applicable)
+
+## IAM Policy Example
+
+Here's a minimal IAM policy for using env-secrets:
+
+> **Note:** In the ARN below, replace `region` with your AWS region (e.g., `us-east-1`), and `account` with your AWS account ID. Also, replace `your-secret-name*` with the actual name or pattern of your secret(s).
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": "secretsmanager:GetSecretValue",
+      "Resource": "arn:aws:secretsmanager:region:account:secret:your-secret-name*"
+    }
+  ]
+}
+```
+
+## Debug Mode Security
+
+When using debug mode, be aware that:
+
+- Secret values are NOT logged
+- Only metadata and API calls are logged
+- Debug logs may contain secret names (but not values)
+
+```bash
+# Safe to use - no secret values are exposed
+DEBUG=env-secrets env-secrets aws -s my-secret -r us-east-1 -- env
+```

package/website/docs/troubleshooting.mdx

@@ -0,0 +1,236 @@
+---
+title: Troubleshooting
+---
+
+# Troubleshooting
+
+This guide helps you resolve common issues when using `env-secrets`.
+
+## Common Issues
+
+### "Unable to connect to AWS"
+
+**Symptoms:**
+
+- `ConfigError` or connection timeout errors
+- "Unable to load credentials" messages
+
+**Solutions:**
+
+1. **Check AWS credentials:**
+
+   ```bash
+   # Verify AWS CLI works
+   aws sts get-caller-identity
+
+   # Check environment variables
+   echo $AWS_ACCESS_KEY_ID
+   echo $AWS_SECRET_ACCESS_KEY
+   echo $AWS_DEFAULT_REGION
+   ```
+
+2. **Verify profile configuration:**
+
+   ```bash
+   # List available profiles
+   aws configure list-profiles
+
+   # Test with specific profile
+   aws sts get-caller-identity --profile your-profile
+   ```
+
+3. **Check network connectivity:**
+   ```bash
+   # Test AWS API connectivity
+   aws secretsmanager list-secrets --region us-east-1
+   ```
+
+### "Secret not found"
+
+**Symptoms:**
+
+- `ResourceNotFoundException` errors
+- "Secret does not exist" messages
+
+**Solutions:**
+
+1. **Verify secret exists:**
+
+   ```bash
+   # List all secrets
+   aws secretsmanager list-secrets --region us-east-1
+
+   # Check specific secret
+   aws secretsmanager describe-secret --secret-id your-secret-name --region us-east-1
+   ```
+
+2. **Check secret name and region:**
+
+   ```bash
+   # Ensure correct region
+   env-secrets aws -s your-secret-name -r us-east-1 -- env
+
+   # Check for typos in secret name
+   aws secretsmanager list-secrets --region us-east-1 | grep your-secret-name
+   ```
+
+3. **Verify permissions:**
+   ```bash
+   # Test secret access
+   aws secretsmanager get-secret-value --secret-id your-secret-name --region us-east-1
+   ```
+
+### "ConfigError"
+
+**Symptoms:**
+
+- AWS SDK configuration errors
+- Profile or credential issues
+
+**Solutions:**
+
+1. **Check AWS configuration:**
+
+   ```bash
+   # View current configuration
+   aws configure list
+
+   # Check credentials file
+   cat ~/.aws/credentials
+
+   # Check config file
+   cat ~/.aws/config
+   ```
+
+2. **Set up credentials properly:**
+
+   ```bash
+   # Configure with environment variables
+   export AWS_ACCESS_KEY_ID=your-access-key
+   export AWS_SECRET_ACCESS_KEY=your-secret-key
+   export AWS_DEFAULT_REGION=us-east-1
+
+   # Or configure with profile
+   aws configure --profile my-profile
+   ```
+
+### Environment variables not injected
+
+**Symptoms:**
+
+- Application doesn't receive expected environment variables
+- `process.env.VARIABLE_NAME` returns `undefined`
+
+**Solutions:**
+
+1. **Verify secret format:**
+
+   ```bash
+   # Check secret content
+   aws secretsmanager get-secret-value --secret-id your-secret-name --region us-east-1 --query SecretString
+
+   # Ensure it's valid JSON
+   aws secretsmanager get-secret-value --secret-id your-secret-name --region us-east-1 --query SecretString | jq .
+   ```
+
+2. **Test environment injection:**
+
+   ```bash
+   # Check what variables are injected
+   env-secrets aws -s your-secret-name -r us-east-1 -- env | grep -E "(DATABASE|API|SECRET)"
+
+   # Test with a simple command
+   env-secrets aws -s your-secret-name -r us-east-1 -- echo "DB_URL: $DATABASE_URL"
+   ```
+
+3. **Check for JSON parsing issues:**
+   ```bash
+   # Enable debug mode to see parsing details
+   DEBUG=env-secrets env-secrets aws -s your-secret-name -r us-east-1 -- env
+   ```
+
+## Debug Mode
+
+Enable debug logging to troubleshoot issues:
+
+### Basic Debug
+
+```bash
+# Debug main application
+DEBUG=env-secrets env-secrets aws -s my-secret -r us-east-1 -- env
+```
+
+### Detailed Debug
+
+```bash
+# Debug vault-specific operations
+DEBUG=env-secrets,env-secrets:secretsmanager env-secrets aws -s my-secret -r us-east-1 -- env
+```
+
+### AWS SDK Debug
+
+```bash
+# Debug AWS SDK operations
+DEBUG=env-secrets,aws-sdk:* env-secrets aws -s my-secret -r us-east-1 -- env
+```
+
+## Error Messages Reference
+
+| Error                        | Cause                          | 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      |
+| `DecryptionFailureException` | Secret encryption issues       | Contact AWS support               |
+
+## Performance Issues
+
+### Slow Secret Retrieval
+
+**Causes:**
+
+- Network latency to AWS
+- Large secret values
+- Cold AWS SDK initialization
+
+**Solutions:**
+
+1. **Use closer AWS regions:**
+
+   ```bash
+   # Choose region closest to your location
+   env-secrets aws -s my-secret -r us-west-2 -- node app.js
+   ```
+
+2. **Optimize secret size:**
+
+   - Keep secrets as small as possible
+   - Avoid storing large binary data in secrets
+
+3. **Reuse AWS SDK instances:**
+   - The tool automatically reuses AWS SDK instances
+   - No additional configuration needed
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. **Check the logs:** Enable debug mode and review the output
+2. **Verify AWS setup:** Ensure AWS CLI works correctly
+3. **Test with AWS CLI:** Try the same operations with AWS CLI directly
+4. **Check permissions:** Verify IAM policies and roles
+5. **Review documentation:** Check this troubleshooting guide and other docs
+6. **Open an issue:** Create a GitHub issue with debug output and error details
+
+### Creating a Good Bug Report
+
+When reporting issues, include:
+
+- Error message and stack trace
+- Debug output (`DEBUG=env-secrets`)
+- AWS CLI version and configuration
+- Node.js version
+- Operating system
+- Steps to reproduce the issue
+- Expected vs actual behavior

package/website/docs/tutorials/local-dev/devcontainer-localstack.mdx

@@ -0,0 +1,31 @@
+---
+title: Devcontainer + LocalStack
+---
+
+Use LocalStack to develop without touching real AWS resources.
+
+1. **Start LocalStack** (Docker or Helm)
+
+```bash
+docker compose up -d  # or 'helm upgrade --install localstack ...'
+```
+
+2. **Configure CLI**
+
+```bash
+aws configure --profile localstack
+export AWS_PROFILE=localstack
+export AWS_ENDPOINT_URL=http://localhost:4566
+```
+
+3. **Create a secret in LocalStack**
+
+```bash
+awslocal secretsmanager create-secret   --name local/sample   --secret-string '{"user":"dev","password":"dev"}'
+```
+
+4. **Run with env-secrets**
+
+```bash
+AWS_ENDPOINT_URL=http://localhost:4566 env-secrets aws -s local/sample -r us-east-1 -- env | grep -E '(user|password)'
+```

package/website/docs/tutorials/local-dev/docker-compose.mdx

@@ -0,0 +1,22 @@
+---
+title: Docker Compose
+---
+
+You can combine `env-secrets` with Docker Compose for local workflows.
+
+**Option A: Wrapper script**
+
+```bash
+env-secrets aws -s my/docker/secrets -r us-east-1 -- docker compose up
+```
+
+Your Compose file can reference environment variables with `${VAR}` as usual.
+
+**Option B: Inject into a "dotenv" file**
+
+If your stack requires a `.env` file, generate it on the fly:
+
+```bash
+# generate .env without writing secrets to VCS
+env-secrets aws -s my/docker/secrets -r us-east-1 -- sh -lc 'env | grep -E "^(DATABASE_URL|API_KEY)=" > .env && docker compose up'
+```

package/website/docs/tutorials/local-dev/nextjs.mdx

@@ -0,0 +1,18 @@
+---
+title: Next.js example
+---
+
+Run Next.js with secrets injected at dev time.
+
+```bash
+env-secrets aws -s nextjs/dev -r us-east-1 -- npm run dev
+```
+
+Then read config in code via:
+
+```ts
+export const API_KEY = process.env.API_KEY!;
+export const DATABASE_URL = process.env.DATABASE_URL!;
+```
+
+> For server components only—do **not** expose secrets to the browser.

package/website/docs/tutorials/local-dev/node-python-go.mdx

@@ -0,0 +1,39 @@
+---
+title: Node, Python & Go examples
+---
+
+## Node
+
+```bash
+env-secrets aws -s node/dev -r us-east-1 -- node server.js
+```
+
+```js
+// server.js
+const apiKey = process.env.API_KEY;
+```
+
+## Python
+
+```bash
+env-secrets aws -s py/dev -r us-east-1 -- uvicorn app:app --reload
+```
+
+```py
+# app.py
+import os
+API_KEY = os.getenv("API_KEY")
+```
+
+## Go
+
+```bash
+env-secrets aws -s go/dev -r us-east-1 -- go run main.go
+```
+
+```go
+// main.go
+package main
+import ("fmt"; "os")
+func main(){ fmt.Println(os.Getenv("API_KEY")) }
+```

package/website/docs/tutorials/local-dev/quickstart.mdx

@@ -0,0 +1,23 @@
+---
+title: Local dev quickstart
+---
+
+This tutorial shows how to fetch a JSON secret and run your app locally with environment variables injected.
+
+1. **Create a JSON secret**
+
+```bash
+aws secretsmanager create-secret   --name my/local/app   --region us-east-1   --secret-string '{"DATABASE_URL":"postgres://user:pass@localhost:5432/db","API_KEY":"abc123"}'
+```
+
+2. **Start your app with `env-secrets`**
+
+```bash
+env-secrets aws -s my/local/app -r us-east-1 -- npm run dev
+```
+
+3. **Confirm variables are present**
+
+```bash
+env | grep -E 'DATABASE_URL|API_KEY'
+```

package/website/docusaurus.config.ts

@@ -0,0 +1,89 @@
+import { Config } from '@docusaurus/types';
+import { themes as prismThemes } from 'prism-react-renderer';
+
+const config: Config = {
+  title: 'env-secrets',
+  tagline:
+    'Fetch secrets from your vault — run any app with env vars injected.',
+  url: 'https://markcallen.github.io',
+  baseUrl: '/env-secrets/',
+  favicon: 'img/favicon.ico',
+  organizationName: 'markcallen',
+  projectName: 'env-secrets',
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+  i18n: { defaultLocale: 'en', locales: ['en'] },
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: require.resolve('./sidebars.ts'),
+          routeBasePath: '/',
+          editUrl:
+            'https://github.com/markcallen/env-secrets/edit/main/website/docs/',
+          showLastUpdateAuthor: true,
+          showLastUpdateTime: true
+        },
+        blog: false,
+        theme: { customCss: require.resolve('./src/css/custom.css') }
+      }
+    ]
+  ],
+  themeConfig: {
+    image: 'img/social-card.png',
+    navbar: {
+      title: 'env-secrets',
+      logo: { alt: 'env-secrets logo', src: 'img/env-secrets.png' },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'docs',
+          position: 'left',
+          label: 'Docs'
+        },
+        {
+          href: 'https://github.com/markcallen/env-secrets',
+          label: 'GitHub',
+          position: 'right'
+        }
+      ]
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'Docs',
+          items: [
+            { label: 'Overview', to: '/overview' },
+            { label: 'CLI', to: '/cli-reference' }
+          ]
+        },
+        {
+          title: 'Community',
+          items: [
+            {
+              label: 'Issues',
+              href: 'https://github.com/markcallen/env-secrets/issues'
+            }
+          ]
+        },
+        {
+          title: 'More',
+          items: [
+            {
+              label: 'GitHub',
+              href: 'https://github.com/markcallen/env-secrets'
+            }
+          ]
+        }
+      ],
+      copyright: `© ${new Date().getFullYear()} Mark C Allen.`
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula
+    }
+  }
+};
+export default config;

package/website/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "env-secrets-website",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "serve": "docusaurus serve",
+    "clear": "docusaurus clear"
+  },
+  "dependencies": {
+    "@docusaurus/core": "^3.8.1",
+    "@docusaurus/preset-classic": "^3.8.1",
+    "@docusaurus/theme-classic": "^3.8.1",
+    "@mdx-js/react": "^3.0.1",
+    "clsx": "^2.1.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  }
+}

package/website/sidebars.ts

@@ -0,0 +1,33 @@
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+const sidebars: SidebarsConfig = {
+  docs: [
+    { type: 'doc', id: 'index' },
+    { type: 'doc', id: 'overview' },
+    { type: 'doc', id: 'installation' },
+    {
+      type: 'category',
+      label: 'Providers',
+      items: ['providers/aws-secrets-manager']
+    },
+    {
+      type: 'category',
+      label: 'Local Development Tutorials',
+      items: [
+        'tutorials/local-dev/quickstart',
+        'tutorials/local-dev/docker-compose',
+        'tutorials/local-dev/nextjs',
+        'tutorials/local-dev/node-python-go',
+        'tutorials/local-dev/devcontainer-localstack'
+      ]
+    },
+    { type: 'doc', id: 'cli-reference' },
+    { type: 'doc', id: 'examples' },
+    { type: 'doc', id: 'advanced-usage' },
+    { type: 'doc', id: 'best-practices' },
+    { type: 'doc', id: 'production-deployment' },
+    { type: 'doc', id: 'security' },
+    { type: 'doc', id: 'troubleshooting' },
+    { type: 'doc', id: 'faq' }
+  ]
+};
+export default sidebars;

package/website/src/css/custom.css

@@ -0,0 +1 @@
+/* custom styles here */

package/website/static/img/logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128">
+  <rect width="100%" height="100%" fill="#0ea5e9"/>
+  <text x="50%" y="55%" text-anchor="middle" font-size="60" fill="#fff" font-family="Arial" dy=".3em">es</text>
+</svg>