env-secrets 0.3.3 → 0.4.0

package/AGENTS.md

@@ -51,7 +51,7 @@ Always run quaity checks after creating or modifing files
 ### Testing Strategy
 
 Always run unit tests after creating or modifying files.  
-Always run end to end tests before pushing code to a remote git repository.
+Always start Docker Compose LocalStack and run end to end tests before pushing code to a remote git repository.
 
 - **Unit Tests**: Jest framework, located in `__tests__/`
 - **E2E Tests**: Located in `__e2e__/`
@@ -60,6 +60,7 @@ Always run end to end tests before pushing code to a remote git repository.
   - `yarn test` - runs all tests
   - `yarn test:unit` - runs unit tests only
   - `yarn test:e2e` - builds and runs e2e tests
+  - `docker compose up -d localstack` - start LocalStack for e2e tests
 
 ## Project Structure
 
@@ -120,8 +121,9 @@ yarn test:unit:coverage # Run tests with coverage
 
 1. Run `yarn prettier:fix && yarn lint` to ensure code quality
 2. Run `yarn test` to ensure all tests pass
-3. Update tests for new features or bug fixes
-4. Update documentation if needed
+3. Run `docker compose up -d localstack` and then `yarn test:e2e` before pushing
+4. Update tests for new features or bug fixes
+5. Update documentation if needed
 
 ### Pull Request Process
 
@@ -130,6 +132,7 @@ yarn test:unit:coverage # Run tests with coverage
 3. Add tests for new functionality
 4. Ensure all CI checks pass
 5. Submit a pull request with a clear description
+6. Always request a GitHub Copilot review on every new pull request
 
 ## Development Environment
 
@@ -138,6 +141,8 @@ yarn test:unit:coverage # Run tests with coverage
 - Node.js 20.0.0 or higher (see .nvmrc)
 - Yarn package manager
 - AWS CLI (for testing AWS integration)
+- Homebrew (macOS/Linux) with `awscli-local` installed:
+  - `brew install awscli-local`
 
 ### Setup
 
@@ -145,5 +150,6 @@ yarn test:unit:coverage # Run tests with coverage
 git clone https://github.com/markcallen/env-secrets.git
 cd env-secrets
 yarn install
+brew install awscli-local
 yarn build
 ```

package/README.md

@@ -103,6 +103,14 @@ env-secrets aws -s my-app-secrets -r us-east-1 -- node app.js
 - `-o, --output <file>` (optional): Output secrets to a file instead of injecting into environment variables. File will be created with 0400 permissions and will not overwrite existing files
 - `-- <program-to-run>`: The program to run with the injected environment variables (only used when `-o` is not specified)
 
+For `aws secret` management subcommands (`create`, `update`, `list`, `get`, `delete`), use:
+
+- `-r, --region <region>` to target a specific region
+- `-p, --profile <profile>` to select credentials profile
+- `--output <format>` for `json` or `table`
+
+These options are honored consistently on `aws secret` subcommands.
+
 #### Examples
 
 1. **Create a secret using AWS CLI:**
@@ -459,11 +467,8 @@ The end-to-end tests use LocalStack to emulate AWS Secrets Manager and test the
 1. **Install awslocal** (required for e2e tests):
 
    ```bash
-   # Using pip (recommended)
-   pip install awscli-local
-
-   # Or using npm
-   npm install -g awscli-local
+   # macOS/Linux (recommended)
+   brew install awscli-local
    ```
 
 2. **Start LocalStack**:
@@ -508,15 +513,15 @@ The end-to-end test suite includes:
 - **Program Execution**: Tests for executing programs with injected environment variables
 - **Error Handling**: Tests for various error scenarios and edge cases
 - **AWS Profile Support**: Tests for both default and custom AWS profiles
-- **Region Support**: Tests for different AWS regions
+- **Region Support**: Tests for different AWS regions, including multi-region `aws secret list` isolation checks
 
 #### Troubleshooting E2E Tests
 
 **awslocal not found**:
 
 ```bash
-# Install awslocal
-pip install awscli-local
+# Install awslocal (macOS/Linux)
+brew install awscli-local
 
 # Verify installation
 awslocal --version

package/__e2e__/README.md

@@ -33,11 +33,8 @@ localstack start
 The tests require `awslocal` to be installed, which is a wrapper around AWS CLI that automatically points to LocalStack:
 
 ```bash
-# Install awslocal using pip (recommended)
-pip install awscli-local
-
-# Or using npm
-npm install -g awscli-local
+# Install awslocal (macOS/Linux recommended)
+brew install awscli-local
 
 # Verify installation
 awslocal --version

package/__e2e__/index.test.ts

@@ -2,6 +2,7 @@ import {
   LocalStackHelper,
   cli,
   cliWithEnv,
+  cliWithEnvAndStdin,
   createTempFile,
   cleanupTempFile,
   createTestProfile,
@@ -332,7 +333,157 @@ describe('End-to-End Tests', () => {
         const result = await cliWithEnv(['aws'], getLocalStackEnv());
 
         expect(result.code).toBe(1);
-        expect(result.stderr).toContain('required option');
+        expect(result.stderr).toContain('Missing required option --secret');
+      });
+    });
+
+    describe('AWS Secret Management Commands', () => {
+      test('should create, list, get, and delete a secret', async () => {
+        const secretName = `e2e-managed-secret-${Date.now()}`;
+
+        const createResult = await cliWithEnv(
+          ['aws', 'secret', 'create', '-n', secretName, '-v', 'initial-value'],
+          getLocalStackEnv()
+        );
+
+        expect(createResult.code).toBe(0);
+        expect(createResult.stdout).toContain(secretName);
+
+        const listResult = await cliWithEnv(
+          ['aws', 'secret', 'list', '--prefix', 'e2e-managed-secret-'],
+          getLocalStackEnv()
+        );
+        expect(listResult.code).toBe(0);
+        expect(listResult.stdout).toContain(secretName);
+
+        const getResult = await cliWithEnv(
+          ['aws', 'secret', 'get', '-n', secretName],
+          getLocalStackEnv()
+        );
+        expect(getResult.code).toBe(0);
+        expect(getResult.stdout).toContain(secretName);
+        expect(getResult.stdout).not.toContain('initial-value');
+
+        const deleteResult = await cliWithEnv(
+          [
+            'aws',
+            'secret',
+            'delete',
+            '-n',
+            secretName,
+            '--force-delete-without-recovery',
+            '--yes'
+          ],
+          getLocalStackEnv()
+        );
+        expect(deleteResult.code).toBe(0);
+      });
+
+      test('should update secret value from stdin', async () => {
+        const secret = await createTestSecret({
+          name: `managed-secret-stdin-${Date.now()}`,
+          value: 'initial-value',
+          description: 'Secret for stdin update test'
+        });
+
+        const updateResult = await cliWithEnvAndStdin(
+          [
+            'aws',
+            'secret',
+            'update',
+            '-n',
+            secret.prefixedName,
+            '--value-stdin'
+          ],
+          getLocalStackEnv(),
+          'stdin-updated-value'
+        );
+
+        expect(updateResult.code).toBe(0);
+        expect(updateResult.stderr).toBe('');
+
+        const deleteResult = await cliWithEnv(
+          [
+            'aws',
+            'secret',
+            'delete',
+            '-n',
+            secret.prefixedName,
+            '--force-delete-without-recovery',
+            '--yes'
+          ],
+          getLocalStackEnv()
+        );
+        expect(deleteResult.code).toBe(0);
+      });
+
+      test('should require confirmation for delete', async () => {
+        const secret = await createTestSecret({
+          name: `managed-secret-confirm-${Date.now()}`,
+          value: 'value',
+          description: 'Secret for delete confirmation test'
+        });
+
+        const result = await cliWithEnv(
+          ['aws', 'secret', 'delete', '-n', secret.prefixedName],
+          getLocalStackEnv()
+        );
+
+        expect(result.code).toBe(1);
+        expect(result.stderr).toContain('requires --yes confirmation');
+      });
+
+      test('should honor region flag for secret list across multiple regions', async () => {
+        const secret = await createTestSecret(
+          {
+            name: `managed-secret-multi-region-${Date.now()}`,
+            value: '{"region":"us-west-2"}',
+            description: 'Secret used for region isolation test'
+          },
+          'us-west-2'
+        );
+
+        const westResult = await cliWithEnv(
+          [
+            'aws',
+            'secret',
+            'list',
+            '--prefix',
+            secret.prefixedName,
+            '-r',
+            'us-west-2',
+            '--output',
+            'json'
+          ],
+          getLocalStackEnv()
+        );
+        expect(westResult.code).toBe(0);
+        const westRows = JSON.parse(westResult.stdout) as Array<{
+          name: string;
+        }>;
+        expect(westRows.some((row) => row.name === secret.prefixedName)).toBe(
+          true
+        );
+
+        const eastResult = await cliWithEnv(
+          [
+            'aws',
+            'secret',
+            'list',
+            '--prefix',
+            secret.prefixedName,
+            '-r',
+            'us-east-1',
+            '--output',
+            'json'
+          ],
+          getLocalStackEnv()
+        );
+        expect(eastResult.code).toBe(0);
+        const eastRows = JSON.parse(eastResult.stdout) as Array<{
+          name: string;
+        }>;
+        expect(eastRows).toEqual([]);
       });
     });
   });

package/__e2e__/utils/test-utils.ts

@@ -1,4 +1,4 @@
-import { exec } from 'child_process';
+import { exec, spawn } from 'child_process';
 import { promisify } from 'util';
 import * as path from 'path';
 import * as fs from 'fs';
@@ -506,6 +506,66 @@ export async function cliWithEnv(
   });
 }
 
+export async function cliWithEnvAndStdin(
+  args: string[],
+  env: Record<string, string>,
+  stdin: string,
+  cwd = '.'
+): Promise<CliResult> {
+  return await new Promise((resolve) => {
+    const cleanEnv = { ...process.env };
+    delete cleanEnv.AWS_PROFILE;
+    delete cleanEnv.AWS_DEFAULT_PROFILE;
+    delete cleanEnv.AWS_SESSION_TOKEN;
+    delete cleanEnv.AWS_SECURITY_TOKEN;
+    delete cleanEnv.AWS_ROLE_ARN;
+    delete cleanEnv.AWS_ROLE_SESSION_NAME;
+    delete cleanEnv.AWS_WEB_IDENTITY_TOKEN_FILE;
+    delete cleanEnv.AWS_WEB_IDENTITY_TOKEN;
+
+    const defaultEnv = {
+      AWS_ENDPOINT_URL: process.env.LOCALSTACK_URL || 'http://localhost:4566',
+      AWS_ACCESS_KEY_ID: 'test',
+      AWS_SECRET_ACCESS_KEY: 'test',
+      AWS_DEFAULT_REGION: 'us-east-1',
+      AWS_REGION: 'us-east-1',
+      NODE_ENV: 'test'
+    };
+
+    const envVars = { ...cleanEnv, ...defaultEnv, ...env };
+    const child = spawn('node', [path.resolve('./dist/index'), ...args], {
+      cwd,
+      env: envVars,
+      stdio: 'pipe'
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let error: Error | null = null;
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('error', (err) => {
+      error = err;
+    });
+    child.on('close', (code) => {
+      resolve({
+        code: code ?? (error ? 1 : 0),
+        error,
+        stdout,
+        stderr
+      });
+    });
+
+    child.stdin.write(stdin);
+    child.stdin.end();
+  });
+}
+
 export function createTempFile(content: string) {
   const tempDir = os.tmpdir();
   const tempFile = path.join(tempDir, `env-secrets-test-${Date.now()}.env`);

package/__tests__/cli/helpers.test.ts

@@ -0,0 +1,129 @@
+import { PassThrough } from 'node:stream';
+
+import {
+  asOutputFormat,
+  parseRecoveryDays,
+  printData,
+  readStdin,
+  renderTable,
+  resolveAwsScope,
+  resolveSecretValue
+} from '../../src/cli/helpers';
+
+describe('cli/helpers', () => {
+  it('validates output format', () => {
+    expect(asOutputFormat('json')).toBe('json');
+    expect(asOutputFormat('table')).toBe('table');
+    expect(() => asOutputFormat('xml')).toThrow('Invalid output format');
+  });
+
+  it('renders empty table message', () => {
+    const output = renderTable([{ key: 'name', label: 'Name' }], []);
+    expect(output).toBe('No results.');
+  });
+
+  it('renders aligned table output', () => {
+    const output = renderTable(
+      [
+        { key: 'name', label: 'Name' },
+        { key: 'value', label: 'Value' }
+      ],
+      [{ name: 'one', value: '1' }]
+    );
+
+    expect(output).toContain('Name');
+    expect(output).toContain('Value');
+    expect(output).toContain('one');
+  });
+
+  it('prints JSON output', () => {
+    const consoleSpy = jest
+      .spyOn(console, 'log')
+      .mockImplementation(() => undefined);
+
+    printData('json', [{ key: 'name', label: 'Name' }], [{ name: 'value' }]);
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      JSON.stringify([{ name: 'value' }], null, 2)
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it('parses valid recovery days and rejects invalid values', () => {
+    expect(parseRecoveryDays('7')).toBe(7);
+    expect(parseRecoveryDays('30')).toBe(30);
+    expect(() => parseRecoveryDays('6')).toThrow();
+    expect(() => parseRecoveryDays('31')).toThrow();
+    expect(() => parseRecoveryDays('abc')).toThrow();
+  });
+
+  it('reads stdin content and strips one trailing newline', async () => {
+    const stream = new PassThrough();
+    const promise = readStdin(stream as unknown as NodeJS.ReadStream);
+
+    stream.write('secret-value\n');
+    stream.end();
+
+    await expect(promise).resolves.toBe('secret-value');
+  });
+
+  it('resolves secret value from explicit --value', async () => {
+    await expect(resolveSecretValue('inline', false)).resolves.toBe('inline');
+  });
+
+  it('rejects when both --value and --value-stdin are used', async () => {
+    await expect(resolveSecretValue('inline', true)).rejects.toThrow(
+      'Use either --value or --value-stdin, not both.'
+    );
+  });
+
+  it('rejects stdin mode when no stdin is provided', async () => {
+    const originalStdin = process.stdin;
+    Object.defineProperty(process, 'stdin', {
+      value: { ...originalStdin, isTTY: true },
+      configurable: true
+    });
+
+    await expect(resolveSecretValue(undefined, true)).rejects.toThrow(
+      'No stdin detected. Pipe a value when using --value-stdin.'
+    );
+
+    Object.defineProperty(process, 'stdin', {
+      value: originalStdin,
+      configurable: true
+    });
+  });
+
+  it('prefers explicit aws scope options over global options', () => {
+    const command = {
+      optsWithGlobals: () => ({
+        profile: 'global-profile',
+        region: 'us-west-2'
+      })
+    };
+
+    expect(
+      resolveAwsScope(
+        { profile: 'local-profile', region: 'us-east-1' },
+        command
+      )
+    ).toEqual({
+      profile: 'local-profile',
+      region: 'us-east-1'
+    });
+  });
+
+  it('falls back to global aws scope options when local options are absent', () => {
+    const command = {
+      optsWithGlobals: () => ({
+        profile: 'global-profile',
+        region: 'us-west-2'
+      })
+    };
+
+    expect(resolveAwsScope({}, command)).toEqual({
+      profile: 'global-profile',
+      region: 'us-west-2'
+    });
+  });
+});

package/__tests__/vaults/aws-config.test.ts

@@ -0,0 +1,85 @@
+import { fromIni } from '@aws-sdk/credential-providers';
+
+jest.mock('@aws-sdk/credential-providers');
+
+import { buildAwsClientConfig } from '../../src/vaults/aws-config';
+
+const mockFromIni = fromIni as jest.MockedFunction<typeof fromIni>;
+
+describe('aws-config', () => {
+  let originalEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    originalEnv = { ...process.env };
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('uses explicit profile when provided', () => {
+    const mockCredentials = jest.fn();
+    mockFromIni.mockReturnValue(mockCredentials as ReturnType<typeof fromIni>);
+
+    const config = buildAwsClientConfig({
+      profile: 'my-profile',
+      region: 'us-east-1'
+    });
+
+    expect(mockFromIni).toHaveBeenCalledWith({ profile: 'my-profile' });
+    expect(config).toEqual({
+      region: 'us-east-1',
+      credentials: mockCredentials
+    });
+  });
+
+  it('uses environment credentials when access key and secret are present', () => {
+    process.env.AWS_ACCESS_KEY_ID = 'test';
+    process.env.AWS_SECRET_ACCESS_KEY = 'test';
+
+    const config = buildAwsClientConfig({ region: 'us-east-1' });
+
+    expect(mockFromIni).not.toHaveBeenCalled();
+    expect(config).toEqual({
+      region: 'us-east-1',
+      credentials: undefined
+    });
+  });
+
+  it('falls back to default profile when no explicit credentials are provided', () => {
+    const mockCredentials = jest.fn();
+    mockFromIni.mockReturnValue(mockCredentials as ReturnType<typeof fromIni>);
+
+    const config = buildAwsClientConfig({ region: 'us-east-1' });
+
+    expect(mockFromIni).toHaveBeenCalledWith({ profile: 'default' });
+    expect(config).toEqual({
+      region: 'us-east-1',
+      credentials: mockCredentials
+    });
+  });
+
+  it('prefers AWS_ENDPOINT_URL for custom endpoint', () => {
+    const mockCredentials = jest.fn();
+    mockFromIni.mockReturnValue(mockCredentials as ReturnType<typeof fromIni>);
+    process.env.AWS_ENDPOINT_URL = 'http://localhost:4566';
+    process.env.AWS_SECRETS_MANAGER_ENDPOINT = 'http://localhost:4577';
+
+    const config = buildAwsClientConfig({ region: 'us-east-1' });
+
+    expect(config.endpoint).toBe('http://localhost:4566');
+  });
+
+  it('uses AWS_SECRETS_MANAGER_ENDPOINT when AWS_ENDPOINT_URL is unset', () => {
+    const mockCredentials = jest.fn();
+    mockFromIni.mockReturnValue(mockCredentials as ReturnType<typeof fromIni>);
+    delete process.env.AWS_ENDPOINT_URL;
+    process.env.AWS_SECRETS_MANAGER_ENDPOINT = 'http://localhost:4577';
+
+    const config = buildAwsClientConfig({ region: 'us-east-1' });
+
+    expect(config.endpoint).toBe('http://localhost:4577');
+  });
+});