env-secrets 0.3.2 → 0.4.0

package/src/vaults/secretsmanager-admin.ts

@@ -0,0 +1,352 @@
+import {
+  CreateSecretCommand,
+  DeleteSecretCommand,
+  DescribeSecretCommand,
+  ListSecretsCommand,
+  SecretsManagerClient,
+  Tag,
+  UpdateSecretCommand
+} from '@aws-sdk/client-secrets-manager';
+import { GetCallerIdentityCommand, STSClient } from '@aws-sdk/client-sts';
+import Debug from 'debug';
+import { buildAwsClientConfig } from './aws-config';
+
+const debug = Debug('env-secrets:secretsmanager-admin');
+
+export interface AwsSecretCommandOptions {
+  profile?: string;
+  region?: string;
+}
+
+export interface SecretCreateOptions extends AwsSecretCommandOptions {
+  name: string;
+  value: string;
+  description?: string;
+  kmsKeyId?: string;
+  tags?: string[];
+}
+
+export interface SecretUpdateOptions extends AwsSecretCommandOptions {
+  name: string;
+  value?: string;
+  description?: string;
+  kmsKeyId?: string;
+}
+
+export interface SecretListOptions extends AwsSecretCommandOptions {
+  prefix?: string;
+  tags?: string[];
+}
+
+export interface SecretDeleteOptions extends AwsSecretCommandOptions {
+  name: string;
+  recoveryDays?: number;
+  forceDeleteWithoutRecovery?: boolean;
+}
+
+export interface SecretSummary {
+  name: string;
+  arn?: string;
+  description?: string;
+  lastChangedDate?: string;
+}
+
+export interface SecretMetadata {
+  name?: string;
+  arn?: string;
+  description?: string;
+  kmsKeyId?: string;
+  deletedDate?: string;
+  lastChangedDate?: string;
+  lastAccessedDate?: string;
+  createdDate?: string;
+  versionIdsToStages?: Record<string, string[]>;
+  tags?: Record<string, string>;
+}
+
+interface AWSLikeError {
+  name?: string;
+  message?: string;
+}
+
+// Allowed characters are documented by AWS Secrets Manager naming rules.
+// See: https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_limits.html
+const SECRET_NAME_PATTERN = /^[A-Za-z0-9/_+=.@-]+$/;
+
+const formatDate = (value?: Date): string | undefined => {
+  if (!value) {
+    return undefined;
+  }
+
+  return value.toISOString();
+};
+
+const parseTags = (tags?: string[]): Tag[] | undefined => {
+  if (!tags || tags.length === 0) {
+    return undefined;
+  }
+
+  return tags.map((tag) => {
+    const parts = tag.split('=');
+    if (parts.length < 2) {
+      throw new Error(`Invalid tag format: ${tag}. Use key=value.`);
+    }
+
+    const key = parts[0].trim();
+    const value = parts.slice(1).join('=').trim();
+
+    if (!key || !value) {
+      throw new Error(`Invalid tag format: ${tag}. Use key=value.`);
+    }
+
+    return { Key: key, Value: value };
+  });
+};
+
+const tagsToRecord = (tags?: Tag[]): Record<string, string> | undefined => {
+  if (!tags || tags.length === 0) {
+    return undefined;
+  }
+
+  const result: Record<string, string> = {};
+  for (const tag of tags) {
+    if (tag.Key && tag.Value) {
+      result[tag.Key] = tag.Value;
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+};
+
+const mapAwsError = (error: unknown, secretName?: string): never => {
+  const awsError = error as AWSLikeError;
+  const secretLabel = secretName ? ` for "${secretName}"` : '';
+
+  if (awsError?.name === 'AlreadyExistsException') {
+    throw new Error(`Secret${secretLabel} already exists.`);
+  }
+
+  if (awsError?.name === 'ResourceNotFoundException') {
+    throw new Error(`Secret${secretLabel} was not found.`);
+  }
+
+  if (awsError?.name === 'InvalidRequestException') {
+    throw new Error(
+      awsError.message || 'Invalid request to AWS Secrets Manager.'
+    );
+  }
+
+  if (awsError?.name === 'AccessDeniedException') {
+    throw new Error(
+      awsError.message ||
+        'Access denied while calling AWS Secrets Manager. Verify IAM permissions.'
+    );
+  }
+
+  if (awsError?.message) {
+    throw new Error(awsError.message);
+  }
+
+  throw new Error(String(error));
+};
+
+const ensureConnected = async (
+  clientConfig: ReturnType<typeof buildAwsClientConfig>
+) => {
+  const stsClient = new STSClient(clientConfig);
+  await stsClient.send(new GetCallerIdentityCommand({}));
+};
+
+const createClient = async (options: AwsSecretCommandOptions) => {
+  const config = buildAwsClientConfig(options);
+  debug('Creating AWS clients', {
+    hasProfile: Boolean(options.profile),
+    region: options.region,
+    hasEndpoint: Boolean(config.endpoint)
+  });
+  await ensureConnected(config);
+  return new SecretsManagerClient(config);
+};
+
+export const validateSecretName = (name: string) => {
+  if (!SECRET_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `Invalid secret name "${name}". Use only letters, numbers, and /_+=.@- characters.`
+    );
+  }
+};
+
+export const createSecret = async (
+  options: SecretCreateOptions
+): Promise<{ arn?: string; name?: string; versionId?: string }> => {
+  validateSecretName(options.name);
+  debug('createSecret called', {
+    name: options.name,
+    hasTags: !!options.tags?.length
+  });
+
+  const client = await createClient(options);
+  const tags = parseTags(options.tags);
+
+  try {
+    const result = await client.send(
+      new CreateSecretCommand({
+        Name: options.name,
+        Description: options.description,
+        SecretString: options.value,
+        KmsKeyId: options.kmsKeyId,
+        Tags: tags
+      })
+    );
+
+    return {
+      arn: result.ARN,
+      name: result.Name,
+      versionId: result.VersionId
+    };
+  } catch (error: unknown) {
+    return mapAwsError(error, options.name);
+  }
+};
+
+export const updateSecret = async (
+  options: SecretUpdateOptions
+): Promise<{ arn?: string; name?: string; versionId?: string }> => {
+  validateSecretName(options.name);
+  debug('updateSecret called', { name: options.name });
+
+  const client = await createClient(options);
+
+  try {
+    const result = await client.send(
+      new UpdateSecretCommand({
+        SecretId: options.name,
+        Description: options.description,
+        SecretString: options.value,
+        KmsKeyId: options.kmsKeyId
+      })
+    );
+
+    return {
+      arn: result.ARN,
+      name: result.Name,
+      versionId: result.VersionId
+    };
+  } catch (error: unknown) {
+    return mapAwsError(error, options.name);
+  }
+};
+
+export const listSecrets = async (
+  options: SecretListOptions
+): Promise<SecretSummary[]> => {
+  debug('listSecrets called', {
+    prefix: options.prefix,
+    hasTags: !!options.tags?.length
+  });
+  const client = await createClient(options);
+  const requiredTags = parseTags(options.tags);
+  const secrets: SecretSummary[] = [];
+
+  try {
+    let nextToken: string | undefined;
+
+    do {
+      const result = await client.send(
+        new ListSecretsCommand({ NextToken: nextToken })
+      );
+
+      for (const secret of result.SecretList || []) {
+        if (
+          options.prefix &&
+          secret.Name &&
+          !secret.Name.startsWith(options.prefix)
+        ) {
+          continue;
+        }
+
+        if (requiredTags && requiredTags.length > 0) {
+          const available = tagsToRecord(secret.Tags);
+          const matchesAll = requiredTags.every(
+            (tag) => tag.Key && tag.Value && available?.[tag.Key] === tag.Value
+          );
+          if (!matchesAll) {
+            continue;
+          }
+        }
+
+        secrets.push({
+          name: secret.Name || '',
+          arn: secret.ARN,
+          description: secret.Description,
+          lastChangedDate: formatDate(secret.LastChangedDate)
+        });
+      }
+
+      nextToken = result.NextToken;
+    } while (nextToken);
+  } catch (error: unknown) {
+    return mapAwsError(error);
+  }
+
+  return secrets;
+};
+
+export const getSecretMetadata = async (
+  options: AwsSecretCommandOptions & { name: string }
+): Promise<SecretMetadata> => {
+  validateSecretName(options.name);
+  debug('getSecretMetadata called', { name: options.name });
+  const client = await createClient(options);
+
+  try {
+    const result = await client.send(
+      new DescribeSecretCommand({ SecretId: options.name })
+    );
+
+    return {
+      name: result.Name,
+      arn: result.ARN,
+      description: result.Description,
+      kmsKeyId: result.KmsKeyId,
+      deletedDate: formatDate(result.DeletedDate),
+      lastChangedDate: formatDate(result.LastChangedDate),
+      lastAccessedDate: formatDate(result.LastAccessedDate),
+      createdDate: formatDate(result.CreatedDate),
+      versionIdsToStages: result.VersionIdsToStages,
+      tags: tagsToRecord(result.Tags)
+    };
+  } catch (error: unknown) {
+    return mapAwsError(error, options.name);
+  }
+};
+
+export const deleteSecret = async (
+  options: SecretDeleteOptions
+): Promise<{ arn?: string; name?: string; deletedDate?: string }> => {
+  validateSecretName(options.name);
+  debug('deleteSecret called', {
+    name: options.name,
+    recoveryDays: options.recoveryDays,
+    forceDeleteWithoutRecovery: options.forceDeleteWithoutRecovery
+  });
+  const client = await createClient(options);
+
+  try {
+    const result = await client.send(
+      new DeleteSecretCommand({
+        SecretId: options.name,
+        RecoveryWindowInDays: options.recoveryDays,
+        ForceDeleteWithoutRecovery: options.forceDeleteWithoutRecovery
+      })
+    );
+
+    return {
+      arn: result.ARN,
+      name: result.Name,
+      deletedDate: formatDate(result.DeletionDate)
+    };
+  } catch (error: unknown) {
+    return mapAwsError(error, options.name);
+  }
+};

package/src/vaults/secretsmanager.ts

@@ -3,8 +3,8 @@ import {
   GetSecretValueCommand
 } from '@aws-sdk/client-secrets-manager';
 import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
-import { fromIni } from '@aws-sdk/credential-providers';
 import Debug from 'debug';
+import { buildAwsClientConfig } from './aws-config';
 
 const debug = Debug('env-secrets:secretsmanager');
 
@@ -14,8 +14,26 @@ interface secretsmanagerType {
   region?: string;
 }
 
-const checkConnection = async (region?: string) => {
-  const stsClient = new STSClient({ region });
+interface AWSLikeError {
+  name?: string;
+  message?: string;
+}
+
+const isCredentialsError = (error: unknown): error is AWSLikeError => {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+
+  const errorName = 'name' in error ? error.name : undefined;
+  return (
+    errorName === 'CredentialsError' || errorName === 'CredentialsProviderError'
+  );
+};
+
+const checkConnection = async (
+  config: ReturnType<typeof buildAwsClientConfig>
+) => {
+  const stsClient = new STSClient(config);
   const command = new GetCallerIdentityCommand({});
 
   try {
@@ -23,6 +41,12 @@ const checkConnection = async (region?: string) => {
     debug(data);
     return true;
   } catch (err) {
+    if (isCredentialsError(err) && err.message) {
+      // eslint-disable-next-line no-console
+      console.error(err.message);
+      return false;
+    }
+
     // eslint-disable-next-line no-console
     console.error(err);
     return false;
@@ -31,33 +55,21 @@ const checkConnection = async (region?: string) => {
 
 export const secretsmanager = async (options: secretsmanagerType) => {
   const { secret, profile, region } = options;
-  const {
-    AWS_ACCESS_KEY_ID: awsAccessKeyId,
-    AWS_SECRET_ACCESS_KEY: awsSecretAccessKey
-  } = process.env;
+  const config = buildAwsClientConfig({ profile, region });
 
-  let credentials;
   if (profile) {
     debug(`Using profile: ${profile}`);
-    credentials = fromIni({ profile });
-  } else if (awsAccessKeyId && awsSecretAccessKey) {
-    debug('Using environment variables');
-    credentials = undefined; // Will use environment variables automatically
-  } else {
+  } else if (config.credentials) {
     debug('Using profile: default');
-    credentials = fromIni({ profile: 'default' });
+  } else {
+    debug('Using environment variables');
   }
 
-  const config = {
-    region,
-    credentials
-  };
-
   if (!config.region) {
     debug('no region set');
   }
 
-  const connected = await checkConnection(region);
+  const connected = await checkConnection(config);
 
   if (connected) {
     const client = new SecretsManagerClient(config);

package/website/docs/cli-reference.mdx

@@ -28,6 +28,48 @@ Currently supported provider: `aws`
 - `-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
 
+## AWS Secret Management Commands
+
+Use `env-secrets aws secret <command>` to manage AWS Secrets Manager secrets directly.
+
+### Commands
+
+- `create` - Create a new secret
+- `update` - Update secret value or metadata
+- `list` - List secrets
+- `get` - Get secret metadata/version info
+- `delete` - Delete a secret
+
+### Shared Options
+
+- `-r, --region <region>` - AWS region
+- `-p, --profile <profile>` - AWS profile
+- `--output <format>` - Output format: `json` or `table` (default: `table`)
+
+### Command-Specific Options
+
+- `create`
+  - `-n, --name <name>` (required)
+  - `-v, --value <value>` or `--value-stdin`
+  - `-d, --description <description>`
+  - `-k, --kms-key-id <kmsKeyId>`
+  - `-t, --tag <key=value...>`
+- `update`
+  - `-n, --name <name>` (required)
+  - `-v, --value <value>` or `--value-stdin`
+  - `-d, --description <description>`
+  - `-k, --kms-key-id <kmsKeyId>`
+- `list`
+  - `--prefix <prefix>`
+  - `-t, --tag <key=value...>`
+- `get`
+  - `-n, --name <name>` (required)
+- `delete`
+  - `-n, --name <name>` (required)
+  - `-y, --yes` (required for delete)
+  - `--recovery-days <7-30>`
+  - `--force-delete-without-recovery`
+
 ### Global Options
 
 - `--help` - Show help information
@@ -131,6 +173,31 @@ env-secrets aws -s docker-secrets -r us-east-1 -o .env
 docker run --env-file .env my-app:latest
 ```
 
+### Secret Management
+
+```bash
+# Create
+env-secrets aws secret create -n app/dev/api -v '{"API_KEY":"abc123"}' --output json
+
+# Create from stdin (recommended for sensitive values)
+echo -n 'super-secret-value' | env-secrets aws secret create -n app/dev/raw --value-stdin
+
+# Update value
+env-secrets aws secret update -n app/dev/api -v '{"API_KEY":"xyz789"}'
+
+# Update from stdin
+echo -n 'rotated-value' | env-secrets aws secret update -n app/dev/raw --value-stdin
+
+# List
+env-secrets aws secret list --prefix app/dev --output table
+
+# Get metadata (does not print secret value)
+env-secrets aws secret get -n app/dev/api --output json
+
+# Delete with confirmation
+env-secrets aws secret delete -n app/dev/raw --recovery-days 7 --yes
+```
+
 ## Environment Variable Behavior
 
 ### JSON Secret Parsing

package/website/docs/examples.mdx

@@ -738,7 +738,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      
+
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@v2
         with:

package/website/docs/installation.mdx

@@ -4,7 +4,7 @@ title: Installation
 
 ## Requirements
 
-- Node.js 18+
+- Node.js 20.0.0 or higher
 - (For AWS) AWS credentials via env vars, profile, or IAM role
 
 ## Install

package/website/docs/providers/aws-secrets-manager.mdx

@@ -4,6 +4,8 @@ title: AWS Secrets Manager
 
 `env-secrets` supports pulling a single JSON secret from AWS Secrets Manager, mapping each top-level key to an environment variable.
 
+It also supports secret lifecycle operations with `env-secrets aws secret <command>`.
+
 ### Create a secret (JSON)
 
 ```bash
@@ -22,6 +24,36 @@ env-secrets aws -s local/sample -r us-east-1 -- echo $user/$password
 - `-r, --region` — AWS region (or `AWS_DEFAULT_REGION`)
 - `-p, --profile` — AWS profile to use
 
+### Secret Management Commands
+
+```bash
+# Create
+env-secrets aws secret create -n app/dev/api -v '{"API_KEY":"abc123"}' --output json
+
+# Create from stdin
+echo -n 'super-secret-value' | env-secrets aws secret create -n app/dev/raw --value-stdin
+
+# Update
+env-secrets aws secret update -n app/dev/api -v '{"API_KEY":"rotated"}'
+
+# List
+env-secrets aws secret list --prefix app/dev --output table
+
+# Get metadata (does not print secret value)
+env-secrets aws secret get -n app/dev/api --output json
+
+# Delete (requires --yes)
+env-secrets aws secret delete -n app/dev/raw --recovery-days 7 --yes
+```
+
+Supported commands:
+
+- `create` with `--value` or `--value-stdin`
+- `update` with value and/or metadata changes
+- `list` with optional prefix/tag filters
+- `get` for metadata/version details
+- `delete` with recovery window or force-delete flags
+
 ### Tips
 
 - Use `DEBUG=env-secrets,env-secrets:secretsmanager` for verbose logs.

package/.eslintignore

@@ -1,4 +0,0 @@
-node_modules/
-dist/
-website/build/
-website/node_modules/

package/.eslintrc

@@ -1,18 +0,0 @@
-{
-  "root": true,
-  "parser": "@typescript-eslint/parser",
-  "plugins": ["@typescript-eslint", "prettier"],
-  "extends": [
-    "eslint:recommended",
-    "plugin:@typescript-eslint/eslint-recommended",
-    "plugin:@typescript-eslint/recommended",
-    "prettier"
-  ],
-  "env": {
-    "jest": true
-  },
-  "rules": {
-    "no-console": "warn",
-    "prettier/prettier": "error"
-  }
-}

package/.lintstagedrc

@@ -1,4 +0,0 @@
-{
-  "*.{js,ts}": ["prettier --write", "eslint --fix"],
-  "*.{json,md,yaml}": ["prettier --write"]
-}