@crvouga/mockingbird-service-cognito 3.12.0 → 3.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +21 -0
- package/README.md +20 -6
- package/SUPPORT.md +7 -2
- package/dist/{chunk-2FO5HE4X.js → admin-ui.js} +14 -5952
- package/dist/admin-ui.js.map +7 -0
- package/dist/chunk-7JVYABWD.js +6556 -0
- package/dist/chunk-7JVYABWD.js.map +7 -0
- package/dist/chunk-B52AI6ZH.js +7 -0
- package/dist/chunk-B52AI6ZH.js.map +7 -0
- package/dist/{chunk-OK7AEWW5.js → chunk-ZL5JEUFF.js} +38 -18
- package/dist/chunk-ZL5JEUFF.js.map +7 -0
- package/dist/cli.js +3 -2
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +134 -4
- package/dist/index.js +4 -1
- package/dist/server.d.ts +62 -1196
- package/dist/server.js +3 -2
- package/openapi.yaml +118 -0
- package/package.json +1 -1
- package/dist/chunk-2FO5HE4X.js.map +0 -7
- package/dist/chunk-OK7AEWW5.js.map +0 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,26 @@
|
|
|
1
1
|
# Changelog — @crvouga/mockingbird-service-cognito
|
|
2
2
|
|
|
3
|
+
## 3.14.0 (2026-11-12)
|
|
4
|
+
|
|
5
|
+
### Features
|
|
6
|
+
|
|
7
|
+
- record delivered messages and show them in notifications ([b280c32](https://github.com/crvouga/mockingbird/commit/b280c32ec3e7f22f2c354747ab5193067290c26b))
|
|
8
|
+
|
|
9
|
+
### Fixes and improvements
|
|
10
|
+
|
|
11
|
+
- document COGNITO_DEFAULT_SENDER ([302364d](https://github.com/crvouga/mockingbird/commit/302364de1917310e693dde783f2b26efe94b192a))
|
|
12
|
+
|
|
13
|
+
## 3.13.0 (2026-11-12)
|
|
14
|
+
|
|
15
|
+
### Features
|
|
16
|
+
|
|
17
|
+
- hosted UI /oauth2/authorize and /oauth2/token with refreshable tokens ([47b649c](https://github.com/crvouga/mockingbird/commit/47b649c86d73e220ccfdf451a955d24ef5ebe4ce))
|
|
18
|
+
|
|
19
|
+
### Fixes and improvements
|
|
20
|
+
|
|
21
|
+
- serve vendor brand data from each emulator instead of the docs site ([0c72a69](https://github.com/crvouga/mockingbird/commit/0c72a693fc76e612936150598faef9787ad1c824))
|
|
22
|
+
- take SIGINT/SIGTERM before readiness is published ([d5a98a0](https://github.com/crvouga/mockingbird/commit/d5a98a09a344e12818c5c94cbea03621b528f841))
|
|
23
|
+
|
|
3
24
|
## 3.12.0 (2026-11-11)
|
|
4
25
|
|
|
5
26
|
### Features
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> Local emulators. Real API contracts. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
|
|
4
4
|
|
|
5
|
-
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.
|
|
5
|
+
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 (including the hosted UI's `/oauth2/authorize` and `/oauth2/token`), recovery, JWT, discovery, and JWKS surface the consumer app uses without contacting AWS.
|
|
6
6
|
|
|
7
7
|
## Install
|
|
8
8
|
|
|
@@ -63,11 +63,25 @@ await emulator.close() // after the test
|
|
|
63
63
|
|
|
64
64
|
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, `token_use`, timestamps and groups. The ID token adds `aud`, `cognito:username`, email and linked identities; the access token adds `client_id`, `username` and `scope`, and no user attributes, as Cognito does. Discovery and JWKS are at `/<poolId>/.well-known/openid-configuration` and `/<poolId>/.well-known/jwks.json`.
|
|
65
65
|
|
|
66
|
+
### Hosted UI: `/oauth2/authorize` and `/oauth2/token` (best guess, not oracle-verified)
|
|
67
|
+
|
|
68
|
+
The hosted-UI domain is the emulator's own origin (plus the `/__admin/ns/<name>` prefix for a non-default namespace), and discovery advertises it as `authorization_endpoint` / `token_endpoint`. Behaviour follows the Cognito developer guide ([authorization endpoint](https://docs.aws.amazon.com/cognito/latest/developerguide/authorization-endpoint.html), [token endpoint](https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html), [ID token claims](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html)). No live user pool backs the parity harness, so everything here is a **best guess, not oracle-verified**.
|
|
69
|
+
|
|
70
|
+
- **App clients.** `appClients: [{ clientId, callbackUrls, clientSecret?, identityProviders?, scopes? }]` (runtime option, or `fixtures.appClients` in a fleet entry), or `POST /__admin/app-clients` at runtime (`GET` lists them; secrets are never returned). The default `clientId` exists with no callback URLs, so register the app's `redirect_uri` before using the hosted UI. `identityProviders` omitted allows every provider name; `scopes` omitted allows the five system scopes. Requested scopes the client does not allow are ignored, and no `scope` grants all allowed ones.
|
|
71
|
+
- **`GET /oauth2/authorize`** with `response_type=code`, `client_id`, `redirect_uri`, `state`, `scope`, `nonce`, `identity_provider` (`Google`, `SignInWithApple`, `Facebook`, `LoginWithAmazon`, an OIDC/SAML name, or `COGNITO`/absent), and optional PKCE (`code_challenge_method=S256` only). It renders an account picker of the pool's own users in place of the provider's sign-in page; choosing one posts to `/oauth2/idpresponse` and redirects to `redirect_uri?code=…&state=…`. Codes are single use and expire after five minutes.
|
|
72
|
+
- **Federation.** The picked user stands in for the provider account; its provider subject is the subject it is already linked under for that provider, otherwise its `sub`. A native user linked to that subject with `AdminLinkProviderForUser` signs in as itself. Otherwise the first sign-in creates the user `<Provider>_<subject>` (status `EXTERNAL_PROVIDER`, the picked user's attributes copied, an `identities` claim `{userId, providerName, providerType, issuer: null, primary: "true", dateCreated}`); later sign-ins reuse it. Federated users cannot use `USER_PASSWORD_AUTH`. With `identity_provider=COGNITO` (or absent) the picked native user signs in directly, standing in for the username/password page.
|
|
73
|
+
- **`POST /oauth2/token`** (form body; `client_secret_basic` or `client_secret_post` when the client has a secret): `authorization_code` returns `access_token`, `id_token` (when `openid` was granted), `refresh_token`, `token_type: "Bearer"`, `expires_in: 3600`; `refresh_token` returns new ID and access tokens without a refresh token. Tokens are signed by the pool's keys with the pool's `iss`; the access token's `scope` is the granted scope and the ID token carries the `nonce`. The refresh token is an ordinary pool refresh token: `InitiateAuth` `REFRESH_TOKEN_AUTH` accepts it (keeping its scopes), and the token endpoint accepts refresh tokens from API sign-ins. Every answer carries `Access-Control-Allow-Origin: *` and `OPTIONS` answers the CORS preflight, as the docs describe.
|
|
74
|
+
- **Errors.** An unknown `client_id` or unregistered `redirect_uri` redirects to the hosted UI's `/error?error=invalid_client|redirect_mismatch&client_id=…` page (HTTP 400 HTML), since there is no trusted place to send them. With a valid client and callback, a missing `response_type`, a `code_challenge` without `code_challenge_method`, or a method other than `S256` returns `redirect_uri?error=invalid_request&state=…`; an `identity_provider` the client does not support returns `error=invalid_request` with `Login option is not available. Please try another one`; Cancel on the picker returns `error=access_denied`. The token endpoint answers HTTP 400 `{"error": …}`: `invalid_client` (unknown client or wrong secret), `invalid_grant` (unknown, expired, reused or other-client code; wrong `code_verifier`; revoked, expired or other-client refresh token), `unauthorized_client` with `error_description: "invalid_redirect"` (`redirect_uri` differs from the authorization request, as the token-endpoint docs say), `invalid_request` (missing `code`, `redirect_uri` or `refresh_token`), and `unsupported_grant_type`.
|
|
75
|
+
- **Not modelled (explicit errors).** The implicit grant (`response_type=token`) returns `error=unauthorized_client`, `idp_identifier` returns `error=invalid_request`, and `grant_type=client_credentials` returns `unsupported_grant_type` with a description saying the emulator does not model it. Managed-login branding, `prompt`, `login_hint`, `/login`, `/logout`, `/oauth2/userInfo`, real redirects to Google/Apple, and attribute mapping beyond copying the picked user's attributes are not modelled.
|
|
76
|
+
- **Headless control.** `POST /__admin/hosted-ui/next-account {"username":"…"}` makes the next `/oauth2/authorize` in that namespace pick that user and redirect at once, so a test completes the flow with plain `fetch`. The pick is consumed by one authorization.
|
|
77
|
+
|
|
66
78
|
### Admin and deterministic controls
|
|
67
79
|
|
|
68
80
|
- `GET/POST /__admin/users` lists redacted users or seeds one. Passwords and tokens are never returned.
|
|
69
|
-
- `GET /__admin/codes?username=…` returns
|
|
81
|
+
- `GET /__admin/codes?username=…` returns a user's current confirmation/reset codes; without `username` it is a 400.
|
|
82
|
+
- `GET /__admin/outbox` lists every message Cognito delivered, oldest first (filters `to`, `since`, `limit`, `channel` = `email`/`sms`, `trigger`, `username`; `GET /__admin/outbox/:id` reads one). SignUp, ResendConfirmationCode and ForgotPassword send Cognito's default verification message (`no-reply@verificationemail.com`, subject `Your verification code`, body `Your verification code is <code>.`) to the user's `email`, or by SMS to `phone_number` when the user has no email, and `CodeDeliveryDetails` names that medium. AdminCreateUser sends the default invitation (`Your username is <username> and temporary password is <password>.`) over `DesiredDeliveryMediums` (SMS by default, email for a user without `phone_number`) unless `MessageAction` is `SUPPRESS`. Each entry has `to`, `channel`, `deliveryMedium`, `attributeName`, `username`, `trigger`, `code`, `from`, `subject`, `body` and `createdAt`. Custom message templates are not modelled. Run the [notifications harness](../../notifications/README.md) against the pool to see these on a phone and webmail screen and finish sign-up from there.
|
|
70
83
|
- `POST /__admin/sessions/revoke {"username":"…"}` invalidates access and refresh sessions.
|
|
84
|
+
- `POST /__admin/hosted-ui/next-account {"username":"…"}` picks the hosted UI's next account; `GET/POST /__admin/app-clients` lists or registers hosted-UI app clients.
|
|
71
85
|
- `POST /__admin/keys/rotate {"retainPrevious":true}` rotates signing keys and retains at most two prior keys. As in Cognito, ID and access tokens are signed with different keys, so the JWKS lists one key of each kind per generation and rotation replaces both (the response names them `kid` and `accessKid`). Every new key receives a fresh random UUID `kid`, independently of the virtual clock. Reset starts a fresh key ring.
|
|
72
86
|
- Fault presets: `throttled`, `unavailable`.
|
|
73
87
|
|
|
@@ -77,7 +91,7 @@ The shared runtime supplies reset, clock, snapshots, journals, metrics, faults,
|
|
|
77
91
|
|
|
78
92
|
Use `fixtures: { users: [...] }` in a fleet service entry, or `options: { fixtures: "./synthetic-users.json" }` for an explicit JSON file containing the same object. The standalone CLI accepts `--fixtures ./synthetic-users.json`. Each user requires `username` and `password`; optional `sub`, `confirmed`, `enabled`, `status`, `createdAt`, attributes, groups, linked identities and inspection codes match the in-process seed fields. Invalid fields, duplicate usernames/subjects/email aliases and conflicting identities fail with field paths before readiness. Diagnostics omit values. Fixture identity objects accept Cognito identity claim fields and the supported provider-link fields, rather than arbitrary nested objects.
|
|
79
93
|
|
|
80
|
-
Fixtures form the reset baseline for every independent namespace. Importing a snapshot replaces saved state, including deleted fixture users, without reseeding. Synthetic passwords stay in private state/archives; user admin responses redact passwords, session data and inspection codes. Codes remain available only from `/__admin/codes`.
|
|
94
|
+
Fixtures form the reset baseline for every independent namespace. Importing a snapshot replaces saved state, including deleted fixture users, without reseeding. Synthetic passwords stay in private state/archives; user admin responses redact passwords, session data and inspection codes. Codes remain available only from `/__admin/codes` and the delivered messages in `/__admin/outbox`.
|
|
81
95
|
|
|
82
96
|
| Surface | Public origin and path prefix | Namespace isolation |
|
|
83
97
|
| --- | --- | --- |
|
|
@@ -85,7 +99,7 @@ Fixtures form the reset baseline for every independent namespace. Importing a sn
|
|
|
85
99
|
| RS256 issuer, discovery and JWKS | Supported; `publicOrigin` + `publicPath` configure the authoritative base | Advertised URLs carry the selected namespace, including header-selected requests |
|
|
86
100
|
| SigV4-signed AWS admin operations | Direct private listener only; signature validation through proxies is not certified | Fixture signatures remain the local test contract |
|
|
87
101
|
| Mockingbird admin controls / private signing material | Private listener only | Never routed by the reference public ingress |
|
|
88
|
-
| Hosted
|
|
102
|
+
| Hosted UI (`/oauth2/authorize`, `/oauth2/idpresponse`, `/oauth2/token`, `/error`) | Supported; redirects and the picker's form use the configured public base | Header and path carriers; picker links carry the namespace prefix |
|
|
89
103
|
|
|
90
104
|
In-process callers can set `baseUrl`, and the CLI accepts `--base-url`. Fixed configuration determines advertised identity URLs; Host and forwarding headers never override it. Without explicit configuration, the direct request/mount URL supplies the origin. Replacing a fleet behind a stable public endpoint retains the issuer even when private listener ports change.
|
|
91
105
|
|
|
@@ -93,13 +107,13 @@ Current and retained synthetic signing keys live in namespace storage, so namesp
|
|
|
93
107
|
|
|
94
108
|
### Deliberately not modelled
|
|
95
109
|
|
|
96
|
-
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.
|
|
110
|
+
Operations outside the documented subset, production quotas, real email/SMS delivery (messages are recorded in `/__admin/outbox` instead), custom message templates, MFA, Lambda triggers, device tracking, Cognito Identity Pools, AWS billing, dashboards, and outbound vendor calls are not implemented. The hosted UI renders an emulator account picker instead of Cognito's managed login pages or the real Google/Apple pages (see Hosted UI above for the unmodelled parameters and grants).
|
|
97
111
|
|
|
98
112
|
## API
|
|
99
113
|
|
|
100
114
|
- `CognitoAPI`, `CognitoAPIOptions`: AWS JSON handler and options.
|
|
101
115
|
- `createRuntime`, `CognitoRuntime`, `CognitoRuntimeOptions`: full Mockingbird service runtime.
|
|
102
|
-
- `COGNITO_NAMESPACE`, `COGNITO_PRESETS`, `accessKeyCredential`: service constants and controls.
|
|
116
|
+
- `COGNITO_NAMESPACE`, `COGNITO_PRESETS`, `COGNITO_DEFAULT_SENDER`, `accessKeyCredential`: service constants and controls (`COGNITO_DEFAULT_SENDER` is the `from` address on delivered email codes).
|
|
103
117
|
- `CognitoAttribute`, `CognitoSeedUser`, `CognitoUser`, `CognitoFixtures`: state and fixture types.
|
|
104
118
|
- `document`, `operationIds`, `supportedOperationIds`: generated OpenAPI metadata.
|
|
105
119
|
- `createServer`, `CognitoServerOptions`, `DEFAULT_PORT`, `serveTarget` from `./server`: Node HTTP adapter and CLI integration.
|
package/SUPPORT.md
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Generated from `openapi.yaml`; do not edit by hand.
|
|
4
4
|
|
|
5
|
-
- operations in spec: **
|
|
6
|
-
- supported by the emulator: **
|
|
5
|
+
- operations in spec: **8**
|
|
6
|
+
- supported by the emulator: **8**
|
|
7
7
|
- parity enabled: **1**
|
|
8
8
|
|
|
9
9
|
| operationId | route | emulator | parity | notes |
|
|
@@ -11,3 +11,8 @@ Generated from `openapi.yaml`; do not edit by hand.
|
|
|
11
11
|
| `CognitoRpc` | `POST /` | ✅ supported | ⚠️ unsafe (opt-in) | |
|
|
12
12
|
| `Discovery` | `GET /{poolId}/.well-known/openid-configuration` | ✅ supported | ❌ disabled | Namespace-scoped local issuer metadata with configured public origin/prefix. |
|
|
13
13
|
| `Jwks` | `GET /{poolId}/.well-known/jwks.json` | ✅ supported | ❌ disabled | Namespace-scoped RS256 keys; one key signs ID tokens and another signs access tokens as in Cognito; portable snapshots retain the current pair and two prior pairs. |
|
|
14
|
+
| `HostedAuthorize` | `GET /oauth2/authorize` | ✅ supported | ❌ disabled | Best guess from the Cognito docs, not oracle-verified; browser redirect flow with an emulator-rendered account picker. |
|
|
15
|
+
| `HostedIdpResponse` | `POST /oauth2/idpresponse` | ✅ supported | ❌ disabled | Emulator-only stand-in for the provider callback; best guess, not oracle-verified. |
|
|
16
|
+
| `HostedToken` | `POST /oauth2/token` | ✅ supported | ❌ disabled | Best guess from the Cognito docs, not oracle-verified; client_credentials is not modelled (unsupported_grant_type). |
|
|
17
|
+
| `HostedTokenPreflight` | `OPTIONS /oauth2/token` | ✅ supported | ❌ disabled | CORS preflight. |
|
|
18
|
+
| `HostedError` | `GET /error` | ✅ supported | ❌ disabled | Static error page. |
|