env-secrets 0.2.0 → 0.3.0

package/docs/AWS.md

@@ -0,0 +1,257 @@
+# AWS Integration Guide
+
+This guide explains how to configure and use AWS Secrets Manager with the `env-secrets` tool.
+
+## Overview
+
+The `env-secrets` tool supports AWS Secrets Manager as a secret vault. It can retrieve secrets stored in AWS Secrets Manager and inject them as environment variables into your running applications.
+
+## Prerequisites
+
+- [AWS CLI](https://docs.aws.amazon.com/cli/index.html) installed and configured
+- AWS credentials with appropriate permissions to access Secrets Manager
+- Node.js 18.0.0 or higher
+
+## Authentication Methods
+
+There are several ways to authenticate with AWS when using `env-secrets`:
+
+### 1. IAM Identity Center (Recommended)
+
+IAM Identity Center (formerly AWS SSO) is the recommended authentication method for most use cases.
+
+**Setup:**
+
+1. Configure AWS CLI with IAM Identity Center:
+   ```bash
+   aws configure sso
+   ```
+2. Follow the prompts to set up your SSO configuration
+3. Login to your SSO session:
+   ```bash
+   aws sso login
+   ```
+
+**Usage:**
+
+```bash
+env-secrets aws -s my-secret-name -r us-east-1 -- echo "Hello, ${USER_NAME}!"
+```
+
+**Benefits:**
+
+- Works from any machine
+- No long-term credentials to manage
+- Automatic credential rotation
+- Centralized access management
+
+**Documentation:** [AWS CLI SSO Configuration](https://docs.aws.amazon.com/cli/latest/userguide/sso-configure-profile-token.html)
+
+### 2. IAM Roles
+
+IAM roles are primarily used for accessing AWS from EC2 instances, ECS tasks, or other AWS services.
+
+**Setup:**
+
+1. Create an IAM role with appropriate Secrets Manager permissions
+2. Attach the role to your EC2 instance or ECS task
+3. The AWS SDK will automatically use the instance metadata service
+
+**Usage:**
+
+```bash
+env-secrets aws -s my-secret-name -r us-east-1 -- node app.js
+```
+
+**Benefits:**
+
+- No credentials to manage
+- Automatic credential rotation
+- Secure for production workloads
+
+**Documentation:** [AWS CLI Role Configuration](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html)
+
+### 3. IAM Users (Not Recommended)
+
+IAM users with access keys should only be used for development or testing purposes.
+
+**Setup:**
+
+1. Create an IAM user with appropriate permissions
+2. Generate access keys for the user
+3. Configure credentials using one of the methods below
+
+#### Option A: AWS Profile
+
+```bash
+aws configure --profile my-profile
+```
+
+Enter the following when prompted:
+
+- Access Key ID
+- Secret Access Key
+- Default region (e.g., `us-east-1`)
+- Output format: `json`
+
+**Usage:**
+
+```bash
+env-secrets aws -s my-secret-name -r us-east-1 -p my-profile -- node app.js
+```
+
+#### Option B: Environment Variables
+
+Set the following environment variables:
+
+```bash
+export AWS_ACCESS_KEY_ID=A...E
+export AWS_SECRET_ACCESS_KEY=w...Y
+export AWS_DEFAULT_REGION=us-east-1
+```
+
+**Usage:**
+
+```bash
+env-secrets aws -s my-secret-name -r us-east-1 -- node app.js
+```
+
+**Security Note:** Avoid hardcoding credentials in scripts or committing them to version control.
+
+## Required Permissions
+
+Your AWS credentials must have the following permissions to use Secrets Manager:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["secretsmanager:GetSecretValue"],
+      "Resource": "arn:aws:secretsmanager:*:*:secret:*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": ["sts:GetCallerIdentity"],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+## Examples
+
+### Basic Usage
+
+1. **Create a secret using AWS CLI:**
+
+   ```bash
+   aws secretsmanager create-secret \
+       --region us-east-1 \
+       --profile my-profile \
+       --name my-app-secrets \
+       --description "Application secrets" \
+       --secret-string '{"DATABASE_URL":"postgresql://user:pass@dbhost:5432/db","API_KEY":"abc123"}'
+   ```
+
+2. **Use the secret with env-secrets:**
+   ```bash
+   env-secrets aws -s my-app-secrets -r us-east-1 -p my-profile -- node app.js
+   ```
+
+### Advanced Examples
+
+1. **Run a Node.js application with secrets:**
+
+   ```bash
+   env-secrets aws -s production-secrets -r us-west-2 -- node server.js
+   ```
+
+2. **Check environment variables:**
+
+   ```bash
+   env-secrets aws -s my-secret -r us-east-1 -p my-profile -- env | grep -E "(DATABASE_URL|API_KEY)"
+   ```
+
+3. **Use with Docker containers:**
+
+   ```bash
+   env-secrets aws -s docker-secrets -r us-east-1 -- docker run -e DATABASE_URL -e API_KEY my-app
+   ```
+
+4. **Debug mode for troubleshooting:**
+   ```bash
+   DEBUG=env-secrets,env-secrets:secretsmanager env-secrets aws -s my-secret -r us-east-1 -- env
+   ```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Unable to connect to AWS"**
+
+   - Verify AWS credentials are configured correctly
+   - Check if the specified region is valid
+   - Ensure network connectivity to AWS services
+   - Verify IAM permissions include `sts:GetCallerIdentity`
+
+2. **"Secret not found"**
+
+   - Verify the secret name exists in the specified region
+   - Check if you have permissions to access the secret
+   - Ensure the secret name is correct (case-sensitive)
+   - Verify the secret is in the correct AWS account
+
+3. **"ConfigError"**
+
+   - Verify AWS profile configuration in `~/.aws/credentials`
+   - Check if environment variables are set correctly
+   - Ensure IAM role permissions if using EC2/ECS
+   - Verify AWS CLI is properly configured
+
+4. **Environment variables not injected**
+   - Verify the secret contains valid JSON
+   - Check if the secret is accessible
+   - Use debug mode to troubleshoot: `DEBUG=env-secrets env-secrets aws ...`
+
+### Debug Mode
+
+Enable debug logging to troubleshoot issues:
+
+```bash
+# Debug main application
+DEBUG=env-secrets env-secrets aws -s my-secret -r us-east-1 -- env
+
+# Debug vault-specific operations
+DEBUG=env-secrets,env-secrets:secretsmanager env-secrets aws -s my-secret -r us-east-1 -- env
+```
+
+### Testing Connectivity
+
+Test your AWS connectivity before using secrets:
+
+```bash
+# Test with AWS CLI
+aws sts get-caller-identity --region us-east-1
+
+# Test with env-secrets (will show connection status)
+DEBUG=env-secrets env-secrets aws -s test-secret -r us-east-1 -- echo "Connection test"
+```
+
+## Security Best Practices
+
+1. **Use IAM Identity Center** for most use cases
+2. **Use IAM roles** for production workloads on AWS
+3. **Rotate credentials regularly** if using IAM users
+4. **Use least privilege** - only grant necessary permissions
+5. **Enable CloudTrail** for audit logging
+6. **Use VPC endpoints** for enhanced security in production
+7. **Never commit credentials** to version control
+
+## Related Documentation
+
+- [AWS Secrets Manager User Guide](https://docs.aws.amazon.com/secretsmanager/latest/userguide/)
+- [AWS CLI Configuration](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)
+- [IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)
+- [AWS SDK for JavaScript v3](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/)

package/jest.config.js

@@ -3,5 +3,7 @@
 module.exports = {
   preset: 'ts-jest',
   testEnvironment: 'node',
-  collectCoverageFrom: ['src/**/*.ts']
+  collectCoverageFrom: ['src/**/*.ts'],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html']
 };

package/jest.e2e.config.js

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+// eslint-disable-next-line no-undef
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  setupFilesAfterEnv: ['<rootDir>/__e2e__/setup.ts'],
+  testTimeout: 30000 // 30 seconds timeout for e2e tests
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "env-secrets",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "get secrets from a secrets vault and inject them into the running environment",
   "main": "index.js",
   "author": "Mark C Allen (@markcallen)",
@@ -11,6 +11,7 @@
   "scripts": {
     "prepare": "husky install",
     "build": "rimraf ./dist && tsc -b src",
+    "start": "node dist/index.js",
     "postbuild": "chmod 755 ./dist/index.js",
     "lint": "eslint . --ext .ts,.js",
     "release": "release-it",
@@ -19,14 +20,16 @@
     "test": "npm run test:unit && npm run test:e2e",
     "test:unit": "jest __tests__",
     "test:unit:coverage": "jest __tests__ --coverage",
-    "test:e2e": "npm run build && jest __e2e__"
+    "test:e2e": "npm run build && jest --config jest.e2e.config.js",
+    "test:e2e:debug": "npm run build && DEBUG=true jest --config jest.e2e.config.js"
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",
     "@types/jest": "^29.5.14",
-    "@types/node": "^18.19.121",
+    "@types/node": "^18.19.124",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^5.62.0",
+    "aws-sdk-client-mock": "^3.0.0",
     "eslint": "^8.57.1",
     "eslint-config-prettier": "^8.10.2",
     "eslint-plugin-prettier": "^4.2.5",
@@ -41,9 +44,9 @@
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "@aws-sdk/client-secrets-manager": "^3.525.0",
-    "@aws-sdk/client-sts": "^3.525.0",
-    "@aws-sdk/credential-providers": "^3.525.0",
+    "@aws-sdk/client-secrets-manager": "^3.883.0",
+    "@aws-sdk/client-sts": "^3.883.0",
+    "@aws-sdk/credential-providers": "^3.883.0",
     "commander": "^9.5.0",
     "debug": "^4.4.1"
   },
@@ -52,7 +55,7 @@
       "prettier --write .",
       "eslint --fix ."
     ],
-    "*.{json,md,yaml}": [
+    "*.{json,md,mdx,yaml,yml}": [
       "prettier --write ."
     ]
   },

package/src/index.ts

@@ -2,10 +2,12 @@
 
 import { Command, Argument } from 'commander';
 import { spawn } from 'node:child_process';
+import { writeFileSync, existsSync } from 'node:fs';
 import Debug from 'debug';
 
 import { LIB_VERSION } from './version';
 import { secretsmanager } from './vaults/secretsmanager';
+import { objectToExport } from './vaults/utils';
 
 const debug = Debug('env-secrets');
 
@@ -27,17 +29,49 @@ program
   .requiredOption('-s, --secret <secret>', 'secret to get')
   .option('-p, --profile <profile>', 'profile to use')
   .option('-r, --region <region>', 'region to use')
+  .option(
+    '-o, --output <file>',
+    'output secrets to file instead of environment variables'
+  )
   .action(async (program, options) => {
-    let env = await secretsmanager(options);
-    env = Object.assign({}, process.env, env);
-    debug(env);
-    if (program && program.length > 0) {
-      debug(`${program[0]} ${program.slice(1)}`);
-      spawn(program[0], program.slice(1), {
-        stdio: 'inherit',
-        shell: true,
-        env
-      });
+    const secrets = await secretsmanager(options);
+    debug(secrets);
+
+    if (options.output) {
+      // Check if file already exists
+      if (existsSync(options.output)) {
+        // eslint-disable-next-line no-console
+        console.error(
+          `Error: File ${options.output} already exists and will not be overwritten`
+        );
+        process.exit(1);
+      }
+
+      // Write secrets to file with 0400 permissions
+      const envContent = objectToExport(secrets);
+      writeFileSync(options.output, envContent, { mode: 0o400 });
+      // eslint-disable-next-line no-console
+      console.log(`Secrets written to ${options.output}`);
+    } else {
+      // Original behavior: merge secrets into environment and run program
+      const env = Object.assign({}, process.env, secrets);
+      debug(env);
+      if (program && program.length > 0) {
+        debug(`${program[0]} ${program.slice(1)}`);
+
+        // In test mode, just output the environment variables for testing
+        if (process.env.NODE_ENV === 'test') {
+          // eslint-disable-next-line no-console
+          console.log(JSON.stringify(env));
+          return;
+        }
+
+        spawn(program[0], program.slice(1), {
+          stdio: 'inherit',
+          shell: true,
+          env
+        });
+      }
     }
   });
 

package/src/vaults/secretsmanager.ts

@@ -23,6 +23,7 @@ const checkConnection = async (region?: string) => {
     debug(data);
     return true;
   } catch (err) {
+    // eslint-disable-next-line no-console
     console.error(err);
     return false;
   }
@@ -73,20 +74,30 @@ export const secretsmanager = async (options: secretsmanagerType) => {
           return JSON.parse(secretvalue);
         }
       } catch (err) {
+        // eslint-disable-next-line no-console
         console.error(err);
       }
-    } catch (err: any) {
-      if (err && err.name === 'ResourceNotFoundException') {
-        console.error(`${secret} not found`);
-      } else if (err && err.name === 'ConfigError') {
-        console.error(err.message);
+    } catch (err: unknown) {
+      if (err && typeof err === 'object' && 'name' in err) {
+        if (err.name === 'ResourceNotFoundException') {
+          // eslint-disable-next-line no-console
+          console.error(`${secret} not found`);
+        } else if (err.name === 'ConfigError' && 'message' in err) {
+          // eslint-disable-next-line no-console
+          console.error(err.message);
+        } else {
+          // eslint-disable-next-line no-console
+          console.error(err);
+        }
       } else {
+        // eslint-disable-next-line no-console
         console.error(err);
       }
     }
 
     return {};
   } else {
+    // eslint-disable-next-line no-console
     console.error('Unable to connect to AWS');
     return {};
   }

package/src/vaults/utils.ts

@@ -14,16 +14,18 @@ export const replaceWithAstrisk = (str: string | undefined) => {
   }
 };
 
-export const objectToExport = (obj: Record<string, any>) => {
+export const objectToExport = (
+  obj: Record<string, string | number | boolean>
+) => {
   return Object.entries(obj).reduce(
     (env, [OutputKey, OutputValue]) =>
-      `${env}export ${OutputKey}=${OutputValue}${os.EOL}`,
+      `${env}${OutputKey}=${OutputValue}${os.EOL}`,
     ''
   );
 };
 
-export const objectToEnv = (obj: Record<string, any>) => {
+export const objectToEnv = (obj: Record<string, string | number | boolean>) => {
   return Object.entries(obj).map(
-    ([OutputKey, OutputValue]) => (process.env[OutputKey] = OutputValue)
+    ([OutputKey, OutputValue]) => (process.env[OutputKey] = String(OutputValue))
   );
 };