@emulates/cognito 0.0.0-stage → 2.3.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog — @emulates/cognito
+
+## 2.3.1 (2026-10-06)
+
+Initial release.
+
+### Dependencies
+
+- `@emulates/sqlite`

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @emulates/cognito discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@emulates/cognito/`; 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: **User pools and browser auth**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- cognito`.
+- 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/emulators/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: `cognito`.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @emulates/cognito
 
-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/emulators): high-fidelity, in-process emulators for APIs and databases.
+
+Stateful local emulator of Amazon Cognito User Pools for the AWS SDK and `amazon-cognito-identity-js`. It implements the authentication, user administration, group, federation, recovery, JWT, discovery, and JWKS surface the consumer app uses without contacting AWS.
+
+## Install
+
+```bash
+npm install -D @emulates/cognito
+```
+
+ESM only. Node 22+ or Bun 1.2+.
+
+## Usage
+
+Point `COGNITO_ENDPOINT` or the AWS SDK `endpoint` option at the served emulator. Fixture SigV4 credentials are accepted for admin operations. Public user-pool operations work without IAM credentials, matching Cognito's client-facing API.
+
+```ts
+import { createRuntime } from "@emulates/cognito"
+
+const cognito = createRuntime({
+  poolId: "us-east-1_emulators",
+  clientId: "emulates-client",
+  users: [
+    {
+      username: "ada@example.test",
+      password: "Password1",
+      confirmed: true,
+      attributes: [{ Name: "email", Value: "ada@example.test" }],
+    },
+  ],
+})
+```
+
+The Node adapter is `createServer()` from `./server`; the CLI is `npx emulates-cognito serve --port 8811 --pool-id us-east-1_emulators --client-id emulates-client`.
+
+### AWS JSON operations
+
+`POST /` dispatches by `X-Amz-Target` and supports SignUp, ConfirmSignUp, ResendConfirmationCode, InitiateAuth (`USER_PASSWORD_AUTH`, `REFRESH_TOKEN_AUTH`), ForgotPassword, ConfirmForgotPassword, ChangePassword, GetUser, DeleteUser, AdminCreateUser, AdminSetUserPassword, AdminConfirmSignUp, AdminGetUser, AdminUpdateUserAttributes, AdminDeleteUser, ListUsers, AdminLinkProviderForUser, AdminAddUserToGroup, AdminRemoveUserFromGroup, and AdminUserGlobalSignOut.
+
+Responses contain SDK-consumed Cognito fields and AWS-shaped exceptions (`__type`, `message`, HTTP status, `x-amzn-requestid`). Tokens are RS256 JWTs with Cognito issuer, subject, client, `token_use`, timestamps, username, email, groups, and linked identities. Discovery and JWKS are at `/<poolId>/.well-known/openid-configuration` and `/<poolId>/.well-known/jwks.json`.
+
+### Admin and deterministic controls
+
+- `GET/POST /__admin/users` lists redacted users or seeds one. Passwords and tokens are never returned.
+- `GET /__admin/codes?username=…` returns local confirmation/reset codes without sending mail.
+- `POST /__admin/sessions/revoke {"username":"…"}` invalidates access and refresh sessions.
+- `POST /__admin/keys/rotate {"retainPrevious":true}` rotates signing keys with optional overlap.
+- Fault presets: `throttled`, `unavailable`.
+
+The shared runtime supplies reset, clock, snapshots, journals, metrics, faults, branches, and namespace isolation. Select namespaces through `x-emulates-namespace`, `/__admin/ns/<name>`, or SigV4 access-key mappings.
+
+### Deliberately not modelled
+
+Operations outside the documented subset, production quotas, email/SMS delivery, MFA, Lambda triggers, device tracking, Cognito Identity Pools, AWS billing, dashboards, and outbound vendor calls are not implemented. Hosted UI federation is represented in linked identity claims; this WIP tier does not render Cognito's hosted login pages.
+
+## API
+
+- `CognitoAPI`, `CognitoAPIOptions`: AWS JSON handler and options.
+- `createRuntime`, `CognitoRuntime`, `CognitoRuntimeOptions`: full Emulates service runtime.
+- `COGNITO_NAMESPACE`, `COGNITO_PRESETS`, `accessKeyCredential`: service constants and controls.
+- `CognitoAttribute`, `CognitoSeedUser`, `CognitoUser`: state and fixture types.
+- `document`, `operationIds`, `supportedOperationIds`: generated OpenAPI metadata.
+- `createServer`, `CognitoServerOptions`, `DEFAULT_PORT`, `serveTarget` from `./server`: Node HTTP adapter and CLI integration.
+
+Official oracle: [Amazon Cognito User Pools API Reference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html) and [Cognito ID token claims](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html).

package/SUPPORT.md

@@ -0,0 +1,13 @@
+# Amazon Cognito Identity Provider (Emulates subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **3**
+- supported by the emulator: **3**
+- parity enabled: **1**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `CognitoRpc` | `POST /` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `Discovery` | `GET /{poolId}/.well-known/openid-configuration` | ✅ supported | ❌ disabled | Local issuer metadata. |
+| `Jwks` | `GET /{poolId}/.well-known/jwks.json` | ✅ supported | ❌ disabled | Local signing keys. |