Secrets Manager

Lightweight, dependency-free fake of AWS Secrets Manager that speaks the real AWS JSON 1.1 wire protocol, so application code using @aws-sdk/client-secrets-manager can run against it with zero cost and zero side effects.

Quick Start

Start the server:

import { SecretsmanagerServer } from "./services/secretsmanager/src/server.js";

const server = new SecretsmanagerServer(4572);
await server.start();
// ... use it ...
await server.stop();

Connect with the real AWS SDK client:

import {
  SecretsManagerClient,
  CreateSecretCommand,
  GetSecretValueCommand,
  PutSecretValueCommand,
  DescribeSecretCommand,
} from "@aws-sdk/client-secrets-manager";

const sm = new SecretsManagerClient({
  region: "us-east-1",
  endpoint: "http://127.0.0.1:4572",
  credentials: { accessKeyId: "parlel", secretAccessKey: "parlel" },
});

// Create a secret
const { ARN } = await sm.send(
  new CreateSecretCommand({ Name: "db/password", SecretString: "s3cr3t" }),
);

// Read it back
const { SecretString } = await sm.send(
  new GetSecretValueCommand({ SecretId: "db/password" }),
);
console.log(SecretString); // "s3cr3t"

// Rotate the stored value (creates a new AWSCURRENT version; the old one
// becomes AWSPREVIOUS)
await sm.send(
  new PutSecretValueCommand({ SecretId: "db/password", SecretString: "n3w-s3cr3t" }),
);

// Inspect metadata + version staging map
const meta = await sm.send(new DescribeSecretCommand({ SecretId: "db/password" }));
console.log(meta.VersionIdsToStages);

The SecretId parameter accepts either a bare secret name or a full ARN (arn:aws:secretsmanager:us-east-1:000000000000:secret:db/password-aB3xZ9).

Wire protocol

• Requests: POST / with header X-Amz-Target: secretsmanager.<Operation> and Content-Type: application/x-amz-json-1.1. The body is the operation's JSON input.
• SecretBinary is base64-encoded on the wire (the SDK handles encode/decode).
• Timestamp fields (CreatedDate, DeletionDate, LastChangedDate, ...) are epoch-seconds numbers; the SDK surfaces them as Date objects.
• Success: 200 with the operation's JSON output.
• Error: non-2xx with { "__type": "<Code>", "message": "<msg>" } plus an x-amzn-errortype: <Code> header.

Implemented operations

All 23 operations exposed by @aws-sdk/client-secrets-manager are implemented.

Secret lifecycle

Secret values

Listing

Version staging

Rotation

Resource policies

Replication

Tagging & utility

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes

Errors are returned as { "__type": "<Code>", "message": "<msg>" }. The SDK surfaces <Code> as the thrown error's name.

Health & reset

• GET /_parlel/health → { "status": "ok", "service": "secretsmanager", "secrets": <n> }
• POST /_parlel/reset → clears all in-memory state. You can also call server.reset() directly in tests.

Environment variables

The manifest publishes these defaults for AWS-SDK-based clients:

AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
AWS_REGION=us-east-1
AWS_ENDPOINT_URL_SECRETS_MANAGER=http://127.0.0.1:4572
AWS_ENDPOINT_URL=http://127.0.0.1:4572

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
AWS_REGION=us-east-1
AWS_ENDPOINT_URL_SECRETS_MANAGER=http://parlel-bridge:4572
AWS_ENDPOINT_URL=http://parlel-bridge:4572