env-secrets 0.3.3 → 0.5.0

package/src/vaults/secretsmanager-admin.ts

@@ -0,0 +1,397 @@
+import {
+  CreateSecretCommand,
+  DeleteSecretCommand,
+  DescribeSecretCommand,
+  GetSecretValueCommand,
+  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 secretExists = async (
+  options: AwsSecretCommandOptions & { name: string }
+): Promise<boolean> => {
+  validateSecretName(options.name);
+  debug('secretExists called', { name: options.name });
+  const client = await createClient(options);
+
+  try {
+    await client.send(new DescribeSecretCommand({ SecretId: options.name }));
+    return true;
+  } catch (error: unknown) {
+    const awsError = error as AWSLikeError;
+    if (awsError?.name === 'ResourceNotFoundException') {
+      return false;
+    }
+
+    return mapAwsError(error, options.name);
+  }
+};
+
+export const getSecretString = async (
+  options: AwsSecretCommandOptions & { name: string }
+): Promise<string> => {
+  validateSecretName(options.name);
+  debug('getSecretString called', { name: options.name });
+  const client = await createClient(options);
+
+  try {
+    const result = await client.send(
+      new GetSecretValueCommand({ SecretId: options.name })
+    );
+
+    if (typeof result.SecretString !== 'string') {
+      throw new Error(
+        `Secret "${options.name}" is not stored as a string value and cannot be edited with append/remove.`
+      );
+    }
+
+    return result.SecretString;
+  } 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');
 
@@ -31,10 +31,9 @@ const isCredentialsError = (error: unknown): error is AWSLikeError => {
 };
 
 const checkConnection = async (
-  region?: string,
-  credentials?: ReturnType<typeof fromIni>
+  config: ReturnType<typeof buildAwsClientConfig>
 ) => {
-  const stsClient = new STSClient({ region, credentials });
+  const stsClient = new STSClient(config);
   const command = new GetCallerIdentityCommand({});
 
   try {
@@ -56,33 +55,21 @@ const checkConnection = async (
 
 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, credentials);
+  const connected = await checkConnection(config);
 
   if (connected) {
     const client = new SecretsManagerClient(config);

package/website/docs/cli-reference.mdx

@@ -28,6 +28,67 @@ 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.
+
+Use `env-secrets aws -s <secret-name>` together with either `-- <program-to-run>` to inject secret values into a spawned child process, or with `-o <file>` to write exports to a file.  
+`env-secrets aws secret <command>` is the lifecycle-management path and does not inject values by itself.
+
+### Commands
+
+- `create` - Create a new secret
+- `update` - Update secret value or metadata
+- `append` - Add or overwrite one key in an existing JSON secret
+- `remove` - Remove one or more keys from an existing JSON secret
+- `upsert` (`import`) - Create or update one JSON secret from an env file
+- `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` or `-f, --file <path>`
+  - `-d, --description <description>`
+  - `-k, --kms-key-id <kmsKeyId>`
+  - `-t, --tag <key=value...>`
+- `update`
+  - `-n, --name <name>` (required)
+  - `-v, --value <value>` or `--value-stdin` or `-f, --file <path>`
+  - `-d, --description <description>`
+  - `-k, --kms-key-id <kmsKeyId>`
+- `upsert` / `import`
+  - `-f, --file <path>` (required)
+  - `-n, --name <name>` (required)
+  - `-d, --description <description>`
+  - `-k, --kms-key-id <kmsKeyId>`
+  - `-t, --tag <key=value...>` (applies on create)
+- `append`
+  - `-n, --name <name>` (required)
+  - `--key <key>` (required)
+  - `-v, --value <value>` or `--value-stdin` or `-f, --file <path>`
+- `remove`
+  - `-n, --name <name>` (required)
+  - `--key <key...>` (required, repeatable)
+- `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 +192,46 @@ env-secrets aws -s docker-secrets -r us-east-1 -o .env
 docker run --env-file .env my-app:latest
 ```
 
+This is also the supported way to load values into your current shell session.
+`env-secrets aws -s ... -- <command>` only affects the spawned child process.
+
+### 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
+
+# Upsert/import from env file
+env-secrets aws secret upsert --file .env --name app/dev --output json
+# alias
+env-secrets aws secret import --file .env --name app/dev --output json
+
+# Result: one secret named app/dev with SecretString like:
+# {"API_KEY":"abc123","DATABASE_URL":"postgres://..."}
+
+# Append/remove keys (JSON secret only)
+env-secrets aws secret append -n app/dev --key JIRA_EMAIL_TOKEN -v blah --output json
+env-secrets aws secret remove -n app/dev --key OLD_TOKEN --output json
+
+# 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/providers/aws-secrets-manager.mdx

@@ -4,6 +4,13 @@ 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>`.
+
+Use:
+
+- `env-secrets aws -s <secret-name> -- <command>` to fetch/inject secret values while running a command (or use `-o <file>` to write env vars to a file).
+- `env-secrets aws secret <command>` for lifecycle operations (`create`, `update`, `append`, `remove`, `upsert/import`, `list`, `get`, `delete`).
+
 ### Create a secret (JSON)
 
 ```bash
@@ -22,6 +29,58 @@ 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
 
+### Inject into current shell
+
+By default, variables are injected into the spawned child process only.
+To load variables into your current shell session:
+
+```bash
+env-secrets aws -s local/sample -r us-east-1 -o secrets.env
+source secrets.env
+```
+
+### 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"}'
+
+# Append/remove keys on JSON secret
+env-secrets aws secret append -n app/dev/api --key JIRA_EMAIL_TOKEN -v blah
+env-secrets aws secret remove -n app/dev/api --key OLD_TOKEN
+
+# Upsert/import from env file
+env-secrets aws secret upsert --file .env --name app/dev --output json
+
+# Result: one secret named app/dev with SecretString JSON:
+# {"API_KEY":"abc123","DATABASE_URL":"postgres://..."}
+
+# 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`, `--value-stdin`, or `--file`
+- `update` with value and/or metadata changes
+- `append` / `remove` for key-level edits on JSON object secrets
+- `upsert/import` from env files containing `export KEY=value` or `KEY=value`, stored as one JSON secret via `--name`
+- `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.