@crvouga/mockingbird-service-cognito 3.13.0 → 3.15.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 CHANGED
@@ -1,5 +1,21 @@
1
1
  # Changelog — @crvouga/mockingbird-service-cognito
2
2
 
3
+ ## 3.15.0 (2026-11-13)
4
+
5
+ ### Features
6
+
7
+ - user-pool validation, SRP sign-in, groups and missing operations ([1f50324](https://github.com/crvouga/mockingbird/commit/1f50324b11eb38bfa9bcd4826d706e5f32c882e4))
8
+
9
+ ## 3.14.0 (2026-11-12)
10
+
11
+ ### Features
12
+
13
+ - record delivered messages and show them in notifications ([b280c32](https://github.com/crvouga/mockingbird/commit/b280c32ec3e7f22f2c354747ab5193067290c26b))
14
+
15
+ ### Fixes and improvements
16
+
17
+ - document COGNITO_DEFAULT_SENDER ([302364d](https://github.com/crvouga/mockingbird/commit/302364de1917310e693dde783f2b26efe94b192a))
18
+
3
19
  ## 3.13.0 (2026-11-12)
4
20
 
5
21
  ### Features
package/README.md CHANGED
@@ -59,15 +59,32 @@ await emulator.close() // after the test
59
59
 
60
60
  ### AWS JSON operations
61
61
 
62
- `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.
62
+ `POST /` dispatches by `X-Amz-Target` and supports SignUp, ConfirmSignUp, ResendConfirmationCode, InitiateAuth and AdminInitiateAuth (`USER_PASSWORD_AUTH` / `ADMIN_USER_PASSWORD_AUTH`, `USER_SRP_AUTH`, `REFRESH_TOKEN_AUTH`), RespondToAuthChallenge and AdminRespondToAuthChallenge (`PASSWORD_VERIFIER`, `NEW_PASSWORD_REQUIRED`), GetTokensFromRefreshToken, ForgotPassword, ConfirmForgotPassword, ChangePassword, GetUser, UpdateUserAttributes, VerifyUserAttribute, DeleteUser, GlobalSignOut, RevokeToken, AdminCreateUser, AdminSetUserPassword, AdminResetUserPassword, AdminConfirmSignUp, AdminGetUser, AdminUpdateUserAttributes, AdminDeleteUserAttributes, AdminDisableUser, AdminEnableUser, AdminDeleteUser, ListUsers, AdminLinkProviderForUser, CreateGroup, GetGroup, ListGroups, DeleteGroup, AdminAddUserToGroup, AdminRemoveUserFromGroup, AdminListGroupsForUser, ListUsersInGroup, DescribeUserPool, DescribeUserPoolClient, and AdminUserGlobalSignOut. Any other target answers `UnknownOperationException`.
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
+ ### Users, sign-in and validation (best guess, not oracle-verified)
67
+
68
+ No live user pool backs the parity harness, so these rules come from the [API reference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html) (each operation's request, response and Errors sections), the [user-pool attributes guide](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html), the [user existence errors guide](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-managing-errors.html) and `amazon-cognito-identity-js`'s SRP client. They are a **best guess, not oracle-verified**.
69
+
70
+ - **Pool and client.** A `UserPoolId` other than the configured `poolId` answers `ResourceNotFoundException` (`User pool <id> does not exist.`), and a `ClientId` that is neither the default `clientId` nor a registered `appClients` entry answers `ResourceNotFoundException` (`User pool client <id> does not exist.`). Register every client id your application sends. A request that omits either falls back to the configured pool and default client. ListUsers, ListUsersInGroup, the group operations, DescribeUserPool and DescribeUserPoolClient need IAM credentials, like the `Admin*` operations.
71
+ - **Usernames.** Any `Username` parameter accepts the username, the user's `sub`, or a sign-in alias (`email`, plus `phone_number` when it is a username attribute). Usernames and aliases match case-insensitively (`usernameCaseSensitive: false`, the console default); pass `usernameCaseSensitive: true` for a case-sensitive pool. With `usernameAttributes: ["email"]` (and/or `"phone_number"`), SignUp and AdminCreateUser take an email (or E.164 phone) as `Username`, store it as that attribute, and generate the username, which is the `sub`; `Username` in responses and `cognito:username` / `username` in tokens are then the sub. A `Username` that is not an email in such a pool answers `InvalidParameterException` `Username should be an email.`
72
+ - **Attributes.** A malformed `email` (or `phone_number`) attribute answers `InvalidParameterException` `Invalid email address format.`. Emails are unique in the pool: creating a user whose username or email another user holds answers `UsernameExistsException`, and AdminUpdateUserAttributes or UpdateUserAttributes setting one answers `AliasExistsException`. UpdateUserAttributes that changes the caller's own `email` or `phone_number` marks it unverified and sends a verification code (`123456`, trigger `UpdateUserAttributes`), which VerifyUserAttribute accepts. Every change moves `UserLastModifiedDate`.
73
+ - **ListUsers.** `Filter` takes `attribute = "value"` or `attribute ^= "value"` on `username`, `email`, `phone_number`, `name`, `given_name`, `family_name`, `preferred_username`, `cognito:user_status`, `status` (`Enabled`/`Disabled`) or `sub`; values match exactly (usernames under the pool's case rule). Another attribute or a malformed filter answers `InvalidParameterException`. `AttributesToGet` limits the returned attributes (`[]` returns none). `Limit` must be 0–60 (0 means 60), and a `PaginationToken` the emulator did not issue answers `InvalidParameterException`.
74
+ - **AdminGetUser** returns `UserAttributes`; ListUsers, ListUsersInGroup and AdminCreateUser return `Attributes`, as in Cognito.
75
+ - **Sign-in.** `USER_SRP_AUTH` (the default flow of `amazon-cognito-identity-js`'s `authenticateUser`) answers the `PASSWORD_VERIFIER` challenge and RespondToAuthChallenge checks the SRP-6a password claim. After the password checks out, a disabled user gets `NotAuthorizedException` `User is disabled.`, a `RESET_REQUIRED` user `PasswordResetRequiredException`, a `FORCE_CHANGE_PASSWORD` user the `NEW_PASSWORD_REQUIRED` challenge (with `userAttributes`), and an unconfirmed user `UserNotConfirmedException`. AdminInitiateAuth takes `ADMIN_USER_PASSWORD_AUTH` (or `ADMIN_NO_SRP_AUTH`), `USER_SRP_AUTH` and `REFRESH_TOKEN_AUTH`; the other operation's password flow answers `Initiate Auth method not supported.`. `CUSTOM_AUTH` and `USER_AUTH` are **not modelled** and answer `InvalidParameterException` `AuthFlow <flow> is not supported by the Mockingbird Cognito emulator.` (an emulator limitation, not a Cognito error). GetTokensFromRefreshToken returns new access and ID tokens without a new refresh token (refresh-token rotation is not modelled).
76
+ - **Confirmation.** ConfirmSignUp and AdminConfirmSignUp for a user that is not `UNCONFIRMED` answer `NotAuthorizedException` `User cannot be confirmed. Current status is <status>`; ResendConfirmationCode answers `InvalidParameterException` `User is already confirmed.`
77
+ - **PreventUserExistenceErrors.** Set `preventUserExistenceErrors: true` on an app client (`appClients` or `POST /__admin/app-clients`) for Cognito's `ENABLED` setting: ForgotPassword and ResendConfirmationCode for an unknown user answer a simulated `CodeDeliveryDetails` (masked email destination, nothing delivered), and ConfirmSignUp / ConfirmForgotPassword answer `CodeMismatchException`. Without it (Cognito's `LEGACY`) they answer `UserNotFoundException`.
78
+ - **Sign-out and revocation.** GlobalSignOut and AdminUserGlobalSignOut revoke all of the user's tokens. RevokeToken revokes a refresh token and every access token issued with it (or refreshed from it); an access token answers `UnsupportedTokenTypeException`, a refresh token of another client `UnauthorizedException`, and an unknown token succeeds. AdminDisableUser revokes the user's tokens.
79
+ - **Groups.** CreateGroup creates a group (`GroupExistsException` if it exists); AdminAddUserToGroup, AdminRemoveUserFromGroup, GetGroup, DeleteGroup and ListUsersInGroup answer `ResourceNotFoundException` `Group not found.` for one that does not. Groups named in seeded users' `groups` exist from the start.
80
+ - **AdminResetUserPassword** sets `RESET_REQUIRED` and sends a reset code (`654321`, trigger `ForgotPassword`); ConfirmForgotPassword with it sets the new password and `CONFIRMED`.
81
+ - **DescribeUserPool / DescribeUserPoolClient** describe the emulator's pool (username attributes, case sensitivity, the fixed password policy) and a registered client (callback URLs, providers, scopes, `PreventUserExistenceErrors`, and its secret if it has one).
82
+
66
83
  ### Hosted UI: `/oauth2/authorize` and `/oauth2/token` (best guess, not oracle-verified)
67
84
 
68
85
  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
86
 
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.
87
+ - **App clients.** `appClients: [{ clientId, callbackUrls, clientSecret?, identityProviders?, scopes?, preventUserExistenceErrors? }]` (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
88
  - **`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
89
  - **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
90
  - **`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.
@@ -78,7 +95,8 @@ The hosted-UI domain is the emulator's own origin (plus the `/__admin/ns/<name>`
78
95
  ### Admin and deterministic controls
79
96
 
80
97
  - `GET/POST /__admin/users` lists redacted users or seeds one. Passwords and tokens are never returned.
81
- - `GET /__admin/codes?username=…` returns local confirmation/reset codes without sending mail.
98
+ - `GET /__admin/codes?username=…` returns a user's current confirmation/reset codes; without `username` it is a 400.
99
+ - `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.
82
100
  - `POST /__admin/sessions/revoke {"username":"…"}` invalidates access and refresh sessions.
83
101
  - `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.
84
102
  - `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.
@@ -90,7 +108,7 @@ The shared runtime supplies reset, clock, snapshots, journals, metrics, faults,
90
108
 
91
109
  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.
92
110
 
93
- 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`.
111
+ 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`.
94
112
 
95
113
  | Surface | Public origin and path prefix | Namespace isolation |
96
114
  | --- | --- | --- |
@@ -106,13 +124,13 @@ Current and retained synthetic signing keys live in namespace storage, so namesp
106
124
 
107
125
  ### Deliberately not modelled
108
126
 
109
- 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. 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).
127
+ Operations outside the documented subset, custom and choice-based auth flows (`CUSTOM_AUTH`, `USER_AUTH`), refresh-token rotation, custom attributes in ListUsers filters, 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).
110
128
 
111
129
  ## API
112
130
 
113
131
  - `CognitoAPI`, `CognitoAPIOptions`: AWS JSON handler and options.
114
132
  - `createRuntime`, `CognitoRuntime`, `CognitoRuntimeOptions`: full Mockingbird service runtime.
115
- - `COGNITO_NAMESPACE`, `COGNITO_PRESETS`, `accessKeyCredential`: service constants and controls.
133
+ - `COGNITO_NAMESPACE`, `COGNITO_PRESETS`, `COGNITO_DEFAULT_SENDER`, `accessKeyCredential`: service constants and controls (`COGNITO_DEFAULT_SENDER` is the `from` address on delivered email codes).
116
134
  - `CognitoAttribute`, `CognitoSeedUser`, `CognitoUser`, `CognitoFixtures`: state and fixture types.
117
135
  - `document`, `operationIds`, `supportedOperationIds`: generated OpenAPI metadata.
118
136
  - `createServer`, `CognitoServerOptions`, `DEFAULT_PORT`, `serveTarget` from `./server`: Node HTTP adapter and CLI integration.