Overcast is alpha — behaviour and APIs may change between releases. Pin your version and read the changelog before upgrading.

overcast

Secrets Manager — AWS Secrets Manager

Quick start, versions and staging labels, the four rotation steps run against your Lambda, the deletion recovery window, and the encryption and resource policies that are not real.

Versioned secrets with real staging labels, and rotation that actually invokes your rotation Lambda. Values are stored in plaintext.

Status: ⚠️ Partial

Quick start

export AWS_ENDPOINT_URL=http://localhost:4566

aws secretsmanager create-secret --name app/db \
  --secret-string '{"username":"app","password":"hunter2"}'

aws secretsmanager get-secret-value --secret-id app/db \
  --query SecretString --output text

Any credentials work; with none configured, run eval "$(overcast env)" first — see Using AWS SDKs and CLI.

What works

AreaBehaviour
SecretsString and binary values, description, tags, and a recorded KmsKeyId
LookupBy name, full ARN, or the partial ARN without the six-character suffix — all three, as on AWS
VersionsClientRequestToken becomes the version ID; VersionStages defaults to AWSCURRENT, and taking it off a version moves AWSPREVIOUS onto it
RotationRotateSecret runs AWS’s four steps against your Lambda; RotationRules schedules drive a background loop
Password generationGetRandomPassword honours PasswordLength, the Exclude* settings, IncludeSpace and RequireEachIncludedType
Resource policiesPut, get, delete and syntactic validation, with BlockPublicPolicy honoured
Batch readsBatchGetSecretValue, with partial results when a secret is missing
DeletionDeleteSecret schedules a delete 7-30 days out (30 by default); the secret is hidden, refuses value operations, and RestoreSecret cancels it until the window closes

Rotation

RotateSecret invokes the configured function once per step — createSecret, setSecret, testSecret, finishSecret — with the payload AWS sends ({"Step", "SecretId", "ClientRequestToken"}) and the same token throughout. Before the first invocation the token is made a version staged AWSPENDING with no value in it, exactly as AWS does, so a rotation function copied from an AWS blueprint works unmodified.

Rotation itself diverges in two places:

AreaOn AWSOvercast
TimingReturns immediately, rotates in the backgroundReturns once the sequence has finished
A failed stepAnswers 200; the failure surfaces in CloudTrailInvalidRequestException naming the step, staging labels left as the function left them

RotateSecret with no rotation function configured — neither on the call nor already on the secret — is InvalidRequestException, as on AWS.

Differences from AWS

AreaOn AWSOvercast
Encryption at restEnvelope-encrypted under the named KMS keyKmsKeyId is recorded as metadata; the value is stored in plaintext
Permanent deletionA background task clears the secret some time after the window closesThe record stays until something reads it, so a name frees up the instant the window closes
Resource policiesEvaluated on every callStored and syntax-checked; never evaluated (#496)
ReplicationReplicateSecretToRegions and its counterpartNot implemented — 501 Not Implemented

Gotchas

Note

A version that exists but holds no value — the state a rotation leaves between staging AWSPENDING and the function writing to it — is listed by DescribeSecret but reported as ResourceNotFoundException by GetSecretValue. PutSecretValue under that token fills it rather than answering ResourceExistsException.

Operations

20 of 22 listed operations are implemented. Per-operation status, notes and AWS API links: Secrets Manager operations.