Aws Sm

Read, write, and delete secrets stored in AWS Secrets Manager, with support for vault annotations (swamp vault annotate / swamp vault inspect). Emits OpenTelemetry spans for vault operations so failures and latency are attributable in traces when a TracerProvider is configured.

Deletion uses the default 30-day recovery window — the secret is scheduled for deletion and can be restored within that period. The secret name cannot be reused until the recovery window expires.

Authentication

Uses the default AWS credential chain — no credentials in config. Provide credentials via one of:

• Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
• AWS profile: ~/.aws/credentials
• IAM role attached to the instance or task

Required IAM Permissions

• secretsmanager:GetSecretValue
• secretsmanager:PutSecretValue
• secretsmanager:CreateSecret
• secretsmanager:ListSecrets
• secretsmanager:DescribeSecret
• secretsmanager:UpdateSecret
• secretsmanager:TagResource
• secretsmanager:DeleteSecret
• secretsmanager:UntagResource

Annotations

Annotations map to native AWS Secrets Manager primitives:

• notes → secret Description field
• labels → resource tags (key-value pairs)
• url → secret Description field (trailing swamp:url= line; stored there rather than a tag because AWS tag values reject URL characters like ? and &. A legacy swamp:url tag is still read for back-compat.)

swamp vault annotate my-aws-sm API_KEY \
  --url https://console.aws.amazon.com/iam \
  --note "Production API key" \
  --label env=prod --label team=infra
swamp vault inspect my-aws-sm API_KEY --json

Usage

swamp vault create @swamp/aws-sm my-aws-sm \
  --config '{"region": "us-east-1"}' --json

swamp vault get my-aws-sm my/secret/name --json
swamp vault put my-aws-sm my/secret/name "s3cr3t" --json
swamp vault delete my-aws-sm my/secret/name --json
swamp vault list-keys my-aws-sm --json

Secret Key Format

Secret keys map directly to AWS Secrets Manager secret names, including path-style names such as myapp/production/db-password.