@emulates/aws-secrets 0.0.0-stage → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog — @emulates/aws-secrets
+
+## 3.0.0 (2026-10-07)
+
+### ⚠️ Breaking changes
+
+- point the repo at crvouga/emulates ([cdb5e53](https://github.com/crvouga/emulates/commit/cdb5e536ed8c1f52345e3984f089001c25fdb08a))
+
+### Fixes and improvements
+
+- format the emulates records query ([8698872](https://github.com/crvouga/emulates/commit/8698872509d06002be5a8fcdc85d79f8462320c3))
+
+### Dependencies
+
+- `@emulates/sqlite`
+
+## 2.3.1 (2026-10-06)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @emulates/aws-secrets discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@emulates/aws-secrets/`; no repository checkout is needed to discover the emulator's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `emulates.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **Secrets Manager and Parameter Store**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- aws-secrets`.
+- Evidence model: Run from an Emulates checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Emulates
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-emulates-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/emulates/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual emulator result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `aws-secrets`.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @emulates/aws-secrets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Part of [Emulates](https://github.com/crvouga/emulates): high-fidelity, in-process emulators for APIs and databases.
+
+Stateful emulator of AWS Secrets Manager and SSM Parameter Store for the official AWS SDK v3 clients. It models secret versions and stages, binary values, deterministic rotation, SecureString metadata, parameter versions, denials, decryption failures, and redacted controls without contacting AWS.
+
+## Install
+
+```bash
+npm install -D @emulates/aws-secrets
+```
+
+ESM only. Node 22+ or Bun 1.2+.
+
+## Usage
+
+Point both clients' `endpoint` option at the same emulator URL. Fixture SigV4 credentials are accepted.
+
+```ts
+import { createServer } from "@emulates/aws-secrets/server"
+
+const mock = await createServer({
+  secrets: [{ name: "database/password", value: "fixture-password" }],
+  parameters: [{ name: "/app/region", value: "us-east-1" }],
+})
+const health = await fetch(`${mock.url}/__admin/health`)
+```
+
+Secrets Manager supports CreateSecret, PutSecretValue, GetSecretValue, and DescribeSecret by name or ARN, including VersionId, VersionStage, SecretString, and SecretBinary. SSM supports PutParameter, GetParameter, and GetParameters with String, StringList, SecureString, WithDecryption, versions, ARNs, and data types.
+
+### Admin and deterministic controls
+
+- `GET /__admin/secrets` and `/__admin/parameters` expose metadata with every value redacted.
+- `POST /__admin/secrets/:name/rotate` atomically moves AWSCURRENT to AWSPREVIOUS.
+- `PUT /__admin/controls/:name` configures denial, stale-version reads, or decryption failure.
+- Fault presets are `throttled` and `unavailable`.
+
+Values are encoded in durable state so timelines and snapshots do not contain plaintext markers. Request journals never record request or response bodies. The shared runtime also provides reset, clock, timeline, metrics, faults, and namespace isolation through `x-emulates-namespace`, `/__admin/ns/<name>`, or SigV4 access-key mappings.
+
+### Deliberately not modelled
+
+KMS cryptography, automatic rotation Lambdas, resource policies, replication, SSM hierarchies and labels beyond the supported reads, production quotas, AWS dashboards, billing, and outbound vendor calls are not modelled. SecureString ciphertext returned without decryption is deterministic emulator ciphertext, not KMS output.
+
+## API
+
+- `AwsSecretsAPI`, `AwsSecretsAPIOptions`, `SecretSeed`, `ParameterSeed`: handler and fixtures.
+- `Secret`, `SecretVersion`, `SecretControl`, `Parameter`: durable state types.
+- `createRuntime`, `AwsSecretsRuntime`, `AwsSecretsRuntimeOptions`: full Emulates runtime.
+- `AWS_SECRETS_NAMESPACE`, `AWS_SECRETS_PRESETS`, `accessKeyCredential`: constants and controls.
+- `document`, `operationIds`, `supportedOperationIds`: generated OpenAPI metadata.
+- `createServer`, `AwsSecretsServerOptions`, `DEFAULT_PORT`, `serveTarget` from `./server`: Node HTTP adapter and CLI integration.
+
+Official oracles: [AWS Secrets Manager API Reference](https://docs.aws.amazon.com/secretsmanager/latest/apireference/Welcome.html) and [AWS Systems Manager API Reference](https://docs.aws.amazon.com/systems-manager/latest/APIReference/Welcome.html).

package/SUPPORT.md

@@ -0,0 +1,11 @@
+# AWS Secrets Manager and SSM Parameter Store (Emulates subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **1**
+- supported by the emulator: **1**
+- parity enabled: **1**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `AwsSecretsRpc` | `POST /` | ✅ supported | ⚠️ unsafe (opt-in) |  |