{"_id":"@aws-blocks/bb-auth-cognito","_rev":"11-bba04f81aab135785c9d1617086df4c5","name":"@aws-blocks/bb-auth-cognito","dist-tags":{"latest":"0.1.10"},"versions":{"0.1.0":{"name":"@aws-blocks/bb-auth-cognito","version":"0.1.0","author":{"name":"Amazon Web Services"},"license":"Apache-2.0","_id":"@aws-blocks/bb-auth-cognito@0.1.0","maintainers":[{"name":"aws-blocks-npm-ops","email":"aws-blocks@amazon.com"}],"dist":{"shasum":"bce83a04693b0f3bdf1e3bd1eaef0ef985c7cd2e","tarball":"https://registry.npmjs.org/@aws-blocks/bb-auth-cognito/-/bb-auth-cognito-0.1.0.tgz","fileCount":86,"integrity":"sha512-5Mb8VvUAnGXVSNLezUjws5WaB9UpfNW98LAtpn9elGM8CR17FHHcoUzUrabAO2BcaJgHDRWyT8r1FlQV3v4S3A==","signatures":[{"sig":"MEYCIQDq4KDVsOmpWQaArtxkD+bd/WNqmZytoy1Kc+NCQlFsVQIhAOSsHikWuvXUdX5oX+Ut8Uy49qxHia3VriWUc/2HdbYG","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":661336},"type":"module","exports":{".":{"cdk":{"types":"./dist/index.cdk.d.ts","default":"./dist/index.cdk.js"},"types":"./dist/index.d.ts","browser":"./dist/index.browser.js","default":"./dist/index.js","aws-runtime":"./dist/index.aws.js"},"./ui":{"types":"./dist/ui.d.ts","default":"./dist/ui.js"}},"gitHead":"639f6fad510d473abd72286351b3294a646d9895","scripts":{"test":"node --test dist/**/*.test.js","build":"tsc --build","prebuild":"node ../../scripts/generate-version.mjs AuthCognito","deploy:manual-pools":"node scripts/deploy-manual-test-pools.mjs","teardown:manual-pools":"node scripts/teardown-manual-test-pools.mjs"},"_npmUser":{"name":"aws-blocks-npm-ops","email":"aws-blocks@amazon.com"},"_npmVersion":"10.9.8","directories":{},"_nodeVersion":"22.22.3","dependencies":{"aws-jwt-verify":"^5.0.0","@aws-blocks/core":"^0.1.0","@aws-blocks/bb-logger":"^0.1.0","@aws-blocks/auth-common":"^0.1.0","@aws-blocks/bb-kv-store":"^0.1.0","@aws-blocks/bb-app-setting":"^0.1.0","@aws-sdk/client-cognito-identity-provider":"^3.0.0"},"_hasShrinkwrap":false,"devDependencies":{"bn.js":"^5.2.3","asn1.js":"^5.4.1","esbuild":"^0.25.0","typescript":"^5.3.0","@types/node":"^20.0.0","@aws-sdk/client-iam":"^3.0.0","@aws-sdk/client-kms":"^3.0.0","@aws-sdk/client-ses":"^3.0.0","@aws-sdk/client-sts":"^3.0.0","@aws-sdk/client-lambda":"^3.0.0","@aws-crypto/client-node":"^4.0.0","@aws-sdk/client-dynamodb":"^3.0.0","@aws-sdk/client-cloudwatch-logs":"^3.0.0"},"peerDependencies":{"constructs":"^10.6.0","aws-cdk-lib":"^2.257.0"},"_npmOperationalInternal":{"tmp":"tmp/bb-auth-cognito_0.1.0_1781566769843_0.9977254047192123","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aws-blocks/bb-auth-cognito","version":"0.1.1","author":{"name":"Amazon Web Services"},"license":"Apache-2.0","_id":"@aws-blocks/bb-auth-cognito@0.1.1","maintainers":[{"name":"aws-blocks-npm-ops","email":"aws-blocks@amazon.com"}],"dist":{"shasum":"bc8580eadbcad7cf59949f506820da0fb8158c76","tarball":"https://registry.npmjs.org/@aws-blocks/bb-auth-cognito/-/bb-auth-cognito-0.1.1.tgz","fileCount":87,"integrity":"sha512-A+oLl0rJa0a1tGCM/mwKhbswhuuAVG0diUhq6zbkDEyBs8hSpnJIuduNro0emnbZBHEBI3K5VtAgs/zXfDEK+g==","signatures":[{"sig":"MEYCIQDXJo5STx3fxkijj5juKtkmkZjAQ2CyyOhSfngdtmSqEQIhAKXtgmU5CrMhiP3JRPjlXHziPRGaeT4FsbFQVDYJCbOa","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":688197},"type":"module","exports":{".":{"cdk":{"types":"./dist/index.cdk.d.ts","default":"./dist/index.cdk.js"},"types":"./dist/index.d.ts","browser":"./dist/index.browser.js","default":"./dist/index.js","aws-runtime":"./dist/index.aws.js"},"./ui":{"types":"./dist/ui.d.ts","default":"./dist/ui.js"}},"gitHead":"ed3e0ad5724d28c2a2fb0ea9207dfc9e941257f9","scripts":{"test":"node --test dist/**/*.test.js","build":"tsc --build","prebuild":"node ../../scripts/generate-version.mjs AuthCognito","deploy:manual-pools":"node scripts/deploy-manual-test-pools.mjs","teardown:manual-pools":"node scripts/teardown-manual-test-pools.mjs"},"_npmUser":{"name":"aws-blocks-npm-ops","email":"aws-blocks@amazon.com"},"_npmVersion":"10.9.8","description":"Authentication backed by Amazon Cognito User Pools. Ships with username/password + MFA (SMS, TOTP, Email OTP), user pool groups for RBAC, custom attributes, device tracking, password reset, and a provider-agnostic state machine that drives the same `` UI as every other AWS Blocks auth BB.\n\n**When to use:** Production apps that need MFA, RBAC via groups, custom attributes, or device tracking on top of AWS Cognito. This BB lets you use Cognito without writing ~130 lines of boilerplate (raw CDK + JWT verify).\n\n**When NOT to use:** Prototypes or internal tools that just need username/password without Cognito — use `AuthBasic`. Direct OIDC federation without Cognito in the middle — use `AuthOIDC`.\n\n> Design & mock parity details: [DESIGN.md](./DESIGN.md)\n\n## Quick Start\n\n```typescript\nimport { Scope, ApiNamespace } from '@aws-blocks/core';\nimport { AuthCognito } from '@aws-blocks/bb-auth-cognito';\n\nconst scope = new Scope('my-app');\nconst auth = new AuthCognito(scope, 'auth', {\n passwordPolicy: { minLength: 8, requireDigits: true },\n userAttributes: [{ name: 'department' }],\n groups: ['admins', 'readers'],\n mfa: 'optional',\n mfaTypes: ['TOTP', 'EMAIL'],\n});\n\nexport const api = new ApiNamespace(scope, 'api', (context) => ({\n async getProfile() {\n const user = await auth.requireAuth(context);\n return { username: user.username, groups: user.groups };\n },\n\n async adminOnly() {\n const user = await auth.requireRole(context, 'admins');\n return { message: `Welcome, ${user.username}` };\n },\n}));\n\n// State machine for the UI\nexport const authApi = auth.createApi();\n```\n\n> The client namespace is taken from the **export name** you choose here (so `import { authApi } from 'aws-blocks'` matches); the `'auth'` label inside `createApi()` is internal and does not affect the wire namespace.\n\n## Supported auth flows\n\nCognito advertises several top-level auth flows + a matrix of challenge types. This BB implements the non-SRP / non-custom subset — enough to cover every flow a greenfield app is likely to pick. SRP, device-remembered, and custom-auth flows are tracked follow-ups.\n\n| Top-level auth flow | Status | Notes |\n|---|---|---|\n| `USER_PASSWORD_AUTH` | ✅ Supported | Default. Classic username + password. |\n| `USER_AUTH` | ✅ Supported | Choice-based (password / email-OTP / SMS-OTP). Pass `preferredChallenge` to skip `SELECT_CHALLENGE`. |\n| `USER_SRP_AUTH` | ❌ Not yet | SRP key-exchange helpers aren't wired. CDK synth throws. |\n| `CUSTOM_AUTH` | ❌ Not yet | Custom-challenge Lambda trigger path. CDK synth throws. |\n\n| Challenge type | Status | When it fires |\n|---|---|---|\n| `SMS_MFA` | ✅ Supported | SMS MFA on classic sign-in. Requires a verified phone + SNS-wired pool. |\n| `SOFTWARE_TOKEN_MFA` | ✅ Supported | TOTP MFA on classic sign-in. |\n| `EMAIL_OTP` (MFA) | ✅ Supported | Email MFA on classic sign-in. Pool must have SES-wired email. |\n| `SELECT_MFA_TYPE` | ✅ Supported | Multi-factor users pick one. |\n| `MFA_SETUP` (TOTP) | ✅ Supported | Pools with `mfa: 'required'`. Auto-runs `AssociateSoftwareToken` → `VerifySoftwareToken` on the first sign-in. |\n| `MFA_SETUP` (EMAIL) | ✅ Supported | User submits the address to enroll, then confirms via `EMAIL_OTP`. |\n| `MFA_SETUP` (selection) | ✅ Supported | Pool allows both TOTP and EMAIL enrollment. |\n| `NEW_PASSWORD_REQUIRED` | ✅ Supported | Admin-created users with `Permanent: false`. |\n| `SELECT_CHALLENGE` | ✅ Supported | USER_AUTH first-factor picker. |\n| `PASSWORD` (USER_AUTH) | ✅ Supported | Non-SRP password leg of USER_AUTH. |\n| `SMS_OTP` | ✅ Supported | USER_AUTH passwordless SMS. |\n| `EMAIL_OTP` (USER_AUTH) | ✅ Supported | USER_AUTH passwordless email. |\n| `WEB_AUTHN` / passkeys | ✅ Supported | Passkey enrolment + USER_AUTH passkey sign-in. Requires `enablePasskeys: true` and a WebAuthn-configured pool (`webAuthnRelyingParty`); throws `WebAuthnNotEnabled` otherwise. |\n| `PASSWORD_SRP` | ❌ Not yet | SRP key-exchange required. |\n| `PASSWORD_VERIFIER` / `DEVICE_SRP_AUTH` / `DEVICE_PASSWORD_VERIFIER` | ❌ Not yet | SRP + device-remembered flows. |\n| `CUSTOM_CHALLENGE` | ❌ Not yet | Requires `CUSTOM_AUTH`. |\n\nEvery unsupported challenge that Cognito might emit returns a typed `ApiError(501)` pointing at the relevant follow-up work, rather than falling through to a vague `InvalidParameterException`.\n\n## Client-facing API\n\nEvery method takes `context: BlocksContext` (for cookie I/O) or operates on the session established by `signIn`.\n\n### Sign-up\n\n| Method | Signature | Notes |\n|---|---|---|\n| `signUp(username, password, options?)` | `Promise` | Options: `{attributes?, clientMetadata?}`. Returns `{isSignUpComplete, userId, nextStep?}` with `nextStep.name === 'CONFIRM_SIGN_UP'` — the code-confirmation flow is required. |\n| `confirmSignUp(username, code)` | `Promise` | Confirm with the code from email/SMS. Returns `{isSignUpComplete, nextStep}` with `nextStep.signUpStep` being `'DONE' \\| 'COMPLETE_AUTO_SIGN_IN'`. |\n| `resendSignUpCode(username)` | `Promise` | Re-deliver the confirmation code. |\n\n### Sign-in + challenge continuation\n\n| Method | Signature | Notes |\n|---|---|---|\n| `signIn(username, password, context, options?)` | `Promise` | Returns `{status: 'signedIn', user}` or `{status: 'continueSignIn', nextStep}` (narrow with `if (result.status === 'signedIn')`). On success, sets the session cookie. |\n| `confirmSignIn(session, response, context, options?)` | `Promise` | Advance any challenge. `response` is discriminated: `{ code }` (SMS/TOTP/Email/TOTP-setup), `{ newPassword }` (NEW_PASSWORD_REQUIRED), `{ mfaType }` (MFA selection / setup selection), `{ email }` (EMAIL_SETUP address submit), `{ password }` (USER_AUTH password leg), `{ firstFactor }` (USER_AUTH first-factor pick), `{ credential }` (USER_AUTH passkey assertion — the JSON-encoded `PublicKeyCredential` from `navigator.credentials.get(...)`). Legacy `string` is still accepted and routed to the code branch. |\n| `signOut(context, options?)` | `Promise` | `{global: true}` calls `GlobalSignOutCommand` (revokes the refresh token at Cognito). |\n\nSee the `SignInResult` and `SignInNextStep` types for the discriminated-union shape.\n\n### Session / identity (`BlocksAuth` interface)\n\n| Method | Returns | Description |\n|---|---|---|\n| `requireAuth(context)` | `Promise` | Throws 401 `NotAuthenticatedException` if no valid session. |\n| `checkAuth(context)` | `Promise` | Boolean check — no throw. |\n| `getCurrentUser(context)` | `Promise` | Returns user or `null`. Auto-refreshes expired tokens on AWS; the mock has no refresh-token concept, so an expired access token is treated as dead (session dropped, cookie cleared) and `null` is returned. |\n| `requireRole(context, role)` | `Promise` | Throws 403 `NotAuthorizedException` if user isn't in the group. |\n| `fetchUserAttributes(context)` | `Promise>` | Return the signed-in user's attributes (live fetch from Cognito via `GetUserCommand`). |\n| `fetchAuthSession(context, options?)` | `Promise` | Return `{ tokens: { idToken, accessToken }, userSub }` for the signed-in user, or `{ tokens: undefined }` when not signed in. Auto-refreshes if the access token has expired; pass `{ forceRefresh: true }` to rotate unconditionally. Shape mirrors Amplify-JS v6 `AuthSession`. Use when calling a non-AWS Blocks AWS service that needs a Cognito JWT — not for identity checks (use `requireAuth` / `getCurrentUser` for those). |\n\n### User profile mutations\n\n| Method | Description |\n|---|---|\n| `updatePassword(context, old, new)` | Change password. |\n| `updateUserAttributes(context, attrs)` | Update multiple attributes; returns per-attribute outcome (may require confirmation code for email/phone). |\n| `updateUserAttribute(context, name, value)` | Update a single attribute. |\n| `deleteUser(context)` | Delete the signed-in user. |\n| `confirmUserAttribute(context, name, code)` | Confirm an attribute change with the verification code. |\n| `sendUserAttributeVerificationCode(context, name)` | Resend verification code for an unverified attribute. |\n\n### Password reset\n\n| Method | Description |\n|---|---|\n| `resetPassword(username)` | Initiate reset; returns `{isPasswordReset: false, nextStep}`. Silently succeeds for unknown users. |\n| `confirmResetPassword(username, code, newPassword)` | Complete reset with the emailed code. |\n\n### MFA setup\n\n| Method | Description |\n|---|---|\n| `setUpTOTP(context)` | Returns `{sharedSecret}` for the authenticator app / QR code. |\n| `verifyTOTPSetup(context, code)` | Confirm TOTP setup with a code from the app. |\n| `updateMFAPreference(context, preference)` | Configure per-factor MFA settings. `preference` is a delta `{ sms?, totp?, email? }` where each value is `'ENABLED' \\| 'DISABLED' \\| 'PREFERRED' \\| 'NOT_PREFERRED'`. |\n| `fetchMFAPreference(context)` | Read current preference. |\n\n### Device tracking\n\n| Method | Description |\n|---|---|\n| `fetchDevices(context)` | `AsyncIterable` — paginates automatically. |\n| `forgetDevice(context, deviceKey)` | Forget the device identified by `deviceKey` (pull it from `fetchDevices`). |\n\n### Passkeys (WebAuthn)\n\nRequires `enablePasskeys: true` and a WebAuthn-configured pool (`webAuthnRelyingParty`). Enrolment/listing operate on the signed-in session; USER_AUTH passkey *sign-in* is driven through `confirmSignIn` (the `{ credential }` branch above).\n\n| Method | Returns | Description |\n|---|---|---|\n| `startPasskeyRegistration(context)` | `Promise` | Begin enrolment for the signed-in user. Returns `credentialCreationOptions` (JSON) for the browser's `navigator.credentials.create(...)`. Throws `WebAuthnNotEnabled` if the pool has no WebAuthn config. |\n| `completePasskeyRegistration(context, credential)` | `Promise` | Persist the browser-encoded `PublicKeyCredential` (JSON string). Returns `{ credentialId }`. |\n| `listPasskeys(context)` | `Promise` | List the signed-in user's registered passkeys (paginates internally). |\n| `deletePasskey(context, credentialId)` | `Promise` | Remove a registered passkey by `credentialId`. |\n\n## Admin surface (`auth.admin`)\n\nServer-side admin operations — group membership and user lifecycle — that act on **any** user by `username` (unlike the client methods above, which act on the signed-in user via `context`). These are **opt-in**: pass an `admin` options object to enable the `auth.admin` handle and grant the matching `Admin*` / `List*` IAM. A pool that never opts in has no admin grant — its synthesized role is identical to today.\n\n```typescript\nconst auth = new AuthCognito(scope, 'auth', {\n groups: ['admins'],\n admin: { actions: ['groups'] }, // enable auth.admin; grant only group Admin* actions\n});\n\n// Always gate admin routes behind requireRole — these methods do NOT self-gate.\nawait auth.requireRole(ctx, 'admins');\nawait auth.admin.addUserToGroup('alice', 'admins'); // group narrowed via GroupOf\n```\n\n- **Compile-time gate.** Without an `admin` options object, `auth.admin` is typed `AdminDisabled` and any access is a compile error whose message names the fix (`construct AuthCognito with { admin: {} }`). The getter also throws at runtime for untyped JS callers.\n- **`actions` scopes both the IAM grant and the typed method set.** `actions: ['groups']` grants only the group `Admin*` actions and makes only the group methods typecheck; `['lifecycle']` only the user-lifecycle actions/methods; omitted grants both. The method gate lives in a trailing parameter position (`AdminActionGate`), so calling a method whose action wasn't granted is a **compile error** while `AuthCognito` stays covariant in `O`. Untyped JS callers that reach past the gate additionally fast-fail at runtime with a clear error rather than a cryptic AWS `AccessDenied`.\n- **Not an access boundary.** Like every block on the shared backend Lambda, client and admin run under one role. Separation is by API surface + lint, not IAM — gate every admin route with `requireRole`.\n\n**Group membership** (`actions: 'groups'`):\n\n| Method | Returns | Description |\n|---|---|---|\n| `admin.addUserToGroup(username, group)` | `Promise` | Add a user to a seeded group. `group` narrows to `GroupOf`. Throws `GroupNotFound` for an unseeded group, `UserNotFound` for a missing user. |\n| `admin.removeUserFromGroup(username, group)` | `Promise` | Remove a user from a group. |\n| `admin.listGroupsForUser(username)` | `Promise[]>` | Groups the user belongs to. |\n| `admin.listUsersInGroup(group)` | `Promise` | Members of a group (paginates internally). |\n\n**User lifecycle** (`actions: 'lifecycle'`):\n\n| Method | Returns | Description |\n|---|---|---|\n| `admin.createUser(username, init?)` | `Promise` | Create a user. `init`: `{ temporaryPassword?, attributes?, suppressInvite? }`. Conflicts with `UserAlreadyExists`. |\n| `admin.deleteUser(username)` | `Promise` | Delete a user (also strips them from every group). |\n| `admin.disableUser(username)` / `admin.enableUser(username)` | `Promise` | Toggle sign-in. A disabled user's `signIn` is rejected with `NotAuthorizedException`. |\n| `admin.resetUserPassword(username)` | `Promise` | Force the user to set a new password on next sign-in. |\n| `admin.setUserPassword(username, password, { permanent })` | `Promise` | Set a password. `permanent: true` clears the force-change flag. |\n| `admin.getUser(username)` | `Promise` | Look up a user, or `null` if absent. |\n| `admin.scan()` | `AsyncIterable` | Enumerate all users (paginates internally). |\n| `admin.revokeUserSessions(username)` | `Promise` | Revoke the user's refresh tokens (AWS: `AdminUserGlobalSignOut`; mock: delete session records). New tokens can no longer be minted; see the session-freshness note for when this takes effect. |\n\n> **Session freshness.** A group change does not affect a user's **existing** session until their token refreshes — `requireRole` reads the `cognito:groups` claim, not live state. This is inherent Cognito behavior. The change applies on the next sign-in or `fetchAuthSession({ forceRefresh: true })`.\n>\n> `admin.revokeUserSessions(username)` revokes the user's **refresh tokens** so no new access tokens can be minted, but it does **not** invalidate an already-issued access token — a Blocks session whose access token is still valid keeps passing `checkAuth` / `requireAuth` until that token expires (verified against live Cognito). It is not an instant kill-switch on AWS. (The mock deletes the session record outright, so it *does* flip immediately there — a known mock-vs-AWS parity difference.) For a hard cap, lower `sessionTtlSeconds` / the access-token validity.\n\n## Options\n\n```typescript\ninterface AuthCognitoOptions {\n mfa?: 'off' | 'optional' | 'required';\n mfaTypes?: ('SMS' | 'TOTP' | 'EMAIL')[];\n passwordPolicy?: PasswordPolicy;\n userAttributes?: UserAttribute[];\n groups?: (string | { name: string; description?: string; precedence?: number })[];\n selfSignUp?: boolean;\n signInWith?: 'username' | 'email' | 'phone' // identifier shape, see § Sign-in identifiers\n | ('username' | 'email' | 'phone')[]; // default: ['username', 'email']\n deviceTracking?: { challengeRequiredOnNewDevice?: boolean; deviceOnlyRememberedOnUserPrompt?: boolean };\n userPool?: ExternalUserPoolRef; // wrap a pre-existing pool\n authFlowType?: 'USER_PASSWORD_AUTH' | 'USER_SRP_AUTH' // full union typed for forward compat;\n | 'USER_AUTH' | 'CUSTOM_AUTH'; // USER_PASSWORD_AUTH + USER_AUTH supported; SRP/CUSTOM throw at synth\n preferredChallenge?: 'PASSWORD' | 'EMAIL_OTP' // USER_AUTH: skip the SELECT_CHALLENGE step\n | 'SMS_OTP' | 'WEB_AUTHN';\n enablePasskeys?: boolean; // provision WebAuthn config on the pool\n webAuthnRelyingParty?: { // required when enablePasskeys is set\n id: string; origins: string[];\n userVerification?: 'required' | 'preferred' | 'discouraged';\n };\n crossDomain?: boolean; // SameSite=None; Secure; Partitioned cookie for cross-site frontends\n logger?: ChildLogger; // optional logger for internal operations\n removalPolicy?: 'destroy' | 'retain'; // default: destroy (sandbox-friendly)\n featurePlan?: 'lite' | 'essentials' | 'plus'; // default: 'essentials'; pinned to stop UpdateUserPool drift\n sessionTtlSeconds?: number; // cookie Max-Age; default 400 days (browser cap)\n}\n\n// Mock-only extension — use with the local dev runtime\ninterface AuthCognitoMockOptions extends AuthCognitoOptions {\n codeDelivery?: CodeDeliveryFn; // local-only verification-code capture\n}\n```\n\n## Sign-in identifiers\n\nThe `signInWith` option controls what end users sign in with. It maps to Cognito's `signInAliases` flag map and dictates which sign-up payloads the pool accepts:\n\n| `signInWith` | Cognito shape | What `signUp(username, ...)` accepts |\n|---|---|---|\n| `['username', 'email']` *(default)* | `AliasAttributes: ['email']` | A non-email username string. Email also signs in via the alias, but **passing an email here throws** *\"Username cannot be of email format, since user pool is configured for email alias.\"* |\n| `'username'` | `signInAliases: { username: true }` | A non-email username string. Email/phone are not aliases. |\n| `'email'` | `UsernameAttributes: ['email']` | An email address. Email **is** the username. Pick this for email-only sign-up flows. |\n| `'phone'` | `UsernameAttributes: ['phone_number']` | A phone number in E.164 format. Pool needs an SMS sender. |\n| `['email', 'phone']` | `UsernameAttributes: ['email', 'phone_number']` | Either contact value as the primary identifier. |\n| `['username', 'email', 'phone']` | `AliasAttributes: ['email', 'phone_number']` | Username string; both contacts are sign-in aliases. |\n\n`autoVerify` is derived from `signInWith` automatically (email/phone get auto-verified; username can't be \"verified\").\n\n> **Backward compatibility.** Changing `signInWith` on a deployed pool is destructive — Cognito rejects the alias-shape transition with `InvalidParameterException`. Pick the right value for your initial deploy.\n\n## Using AuthCognito generically (literal-narrowing with `as const`)\n\n`AuthCognito` is generic on its options literal. Because the generic is a **`const` type parameter**, TypeScript narrows method signatures to the exact values you configured for **options passed inline** — typos on group names, custom attributes, and MFA factors become compile errors instead of runtime surprises, with no `as const` needed:\n\n```typescript\nconst auth = new AuthCognito(scope, 'auth', { groups: ['admins', 'readers'] });\nawait auth.requireRole(ctx, 'admins'); // ✅ narrowed inline — no `as const`\nawait auth.requireRole(ctx, 'admin'); // ❌ compile error (typo)\n```\n\nFor an options object **declared separately** in a variable, add `as const` so its literals don't widen before reaching the constructor. The example below uses `as const` for that reason; the narrowing it produces is identical.\n\n```typescript\nconst options = {\n groups: ['admins', 'readers'] as const,\n userAttributes: [\n { name: 'department', type: 'String' },\n { name: 'employeeId', type: 'Number' },\n ] as const,\n mfaTypes: ['TOTP', 'EMAIL'] as const,\n} satisfies AuthCognitoOptions;\n\nconst auth = new AuthCognito(scope, 'auth', options);\n\n// ✅ Typechecks — 'admins' is in the narrowed group union.\nawait auth.requireRole(ctx, 'admins');\n\n// ❌ Compile error — 'admin' (typo) is not a configured group.\nawait auth.requireRole(ctx, 'admin');\n\n// ✅ 'custom:department' is in the narrowed AttrOf. Prefixed and\n// unprefixed forms both accept the declared names for writes.\nawait auth.updateUserAttribute(ctx, 'custom:department', 'platform');\nawait auth.updateUserAttribute(ctx, 'department', 'platform');\n\n// ❌ Compile error — 'custom:manager' was never declared.\nawait auth.updateUserAttribute(ctx, 'custom:manager', 'alice');\n\n// ✅ 'totp' is in the narrowed MfaTypeOf.\nawait auth.updateMFAPreference(ctx, { totp: 'PREFERRED' });\n\n// ❌ Compile error — pool is not configured for SMS MFA.\nawait auth.updateMFAPreference(ctx, { sms: 'PREFERRED' });\n```\n\n**Without `as const` you get today's wide types** — every method accepts the full `string` / Cognito-standard / `'SMS' | 'TOTP' | 'EMAIL'` union. Backward-compatible; opt into narrowing when you want the extra safety.\n\n`CognitoUser` — returned by `requireAuth` / `getCurrentUser` / `requireRole` / `signIn` — narrows the same way:\n\n```typescript\nconst user = await auth.requireAuth(ctx);\nuser.groups.includes('admins'); // ✅ ok\nuser.groups.includes('admin'); // ❌ typo caught at compile time\nuser.attributes['custom:department']; // ✅ typed as `string | undefined`\n```\n\nJWT claim payloads on `fetchAuthSession(ctx)` are typed `Record` — narrow before use:\n\n```typescript\nconst session = await auth.fetchAuthSession(ctx);\nconst sub = session.tokens?.idToken.payload.sub;\nif (typeof sub === 'string') { /* … */ }\n```\n\n## Porting from Amplify JS v6\n\n`AuthCognito` is source-compatible with Amplify JS v6 `Auth` for every method name and most payload shapes. When we deliberately differ from Amplify, we do it to fit the server-side BFF model AWS Blocks uses.\n\n| Amplify JS v6 | `AuthCognito` | Notes |\n|---|---|---|\n| `signUp({ username, password, options: { userAttributes } })` | `signUp(username, password, { attributes })` | AWS Blocks flattens Amplify's nested `options.userAttributes` into `attributes`. |\n| `confirmSignUp({ username, confirmationCode })` | `confirmSignUp(username, code)` | Positional. |\n| `resendSignUpCode({ username })` | `resendSignUpCode(username)` | |\n| `signIn({ username, password })` | `signIn(username, password, context)` | AWS Blocks takes the request `context` so it can set the HttpOnly session cookie. |\n| `confirmSignIn({ challengeResponse })` | `confirmSignIn(session, response, context, options?)` | Discriminated: `{ code }`, `{ newPassword }`, `{ mfaType }`. |\n| `signOut()` | `signOut(context, options?)` | `{ global: true }` calls `GlobalSignOutCommand`. |\n| `resetPassword({ username })` | `resetPassword(username)` | |\n| `confirmResetPassword({ username, newPassword, confirmationCode })` | `confirmResetPassword(username, code, newPassword)` | |\n| `updatePassword({ oldPassword, newPassword })` | `updatePassword(context, oldPassword, newPassword)` | |\n| `fetchUserAttributes()` | `fetchUserAttributes(context)` | Live read. Returns `Record`; narrows via `as const` on `userAttributes`. |\n| `updateUserAttribute({ userAttribute: { attributeKey, value } })` | `updateUserAttribute(context, name, value)` | Flattened. |\n| `updateUserAttributes({ userAttributes: { … } })` | `updateUserAttributes(context, attributes)` | |\n| `sendUserAttributeVerificationCode({ userAttributeKey })` | `sendUserAttributeVerificationCode(context, name)` | |\n| `confirmUserAttribute({ userAttributeKey, confirmationCode })` | `confirmUserAttribute(context, name, code)` | |\n| `setUpTOTP()` | `setUpTOTP(context)` | Returns `{ sharedSecret }` (Amplify returns `{ getSetupUri, sharedSecret }` — we keep just the secret). |\n| `verifyTOTPSetup({ code })` | `verifyTOTPSetup(context, code)` | |\n| `updateMFAPreference({ sms, totp, email })` | `updateMFAPreference(context, { sms, totp, email })` | Same per-factor shape: `'ENABLED' \\| 'DISABLED' \\| 'PREFERRED' \\| 'NOT_PREFERRED'`. At most one `'PREFERRED'` per call. |\n| `fetchMFAPreference()` | `fetchMFAPreference(context)` | Returns `{ enabled, preferred }`. |\n| `fetchAuthSession()` | `fetchAuthSession(context, options?)` | See § \"Session surface\" below for the intentional differences. |\n| `rememberDevice()` | `rememberDevice(context)` | Works on mock; AWS throws `501` until NewDeviceMetadata plumbing lands. |\n| `forgetDevice(device?)` | `forgetDevice(context, deviceKey)` | `deviceKey` is required — no \"current device\" inference. |\n| `fetchDevices()` | `fetchDevices(context)` | Returns `AsyncIterable` (Amplify returns an array). |\n\n### Session surface — why not every Amplify field?\n\nAmplify v6's `AuthSession`:\n\n```ts\ninterface AuthSession {\n tokens?: { idToken?: JWT; accessToken: JWT; signInDetails?: CognitoAuthSignInDetails };\n credentials?: AWSCredentials;\n identityId?: string;\n userSub?: string;\n}\n```\n\nAWS Blocks's `AuthSession`:\n\n```ts\ninterface AuthSession {\n tokens?: { idToken: JWT; accessToken: JWT };\n userSub?: string;\n}\n```\n\nDeliberate differences:\n\n- **`credentials` / `identityId` omitted** — AWS Blocks uses User Pools only, no Identity Pool. Lambdas call AWS using their own IAM role. Adding these fields would require wiring an Identity Pool, which is a separate Building Block.\n- **Refresh token not surfaced** — Amplify v6 agrees on this point. Refresh tokens are long-lived bearer credentials; returning them from `fetchAuthSession` would break AWS Blocks's HttpOnly-cookie security model. The BB uses the refresh token internally for auto-refresh; callers never see it.\n- **`idToken` is required**, not optional — AWS Blocks always issues both tokens. Amplify's optional marker covers edge cases like client-credentials flows that AWS Blocks doesn't support.\n- **`signInDetails` not exposed** — low-value (`loginId` + `authFlowType`); revisit if callers need it.\n- **`JWT.payload` is `Record`** — forces claim-by-claim narrowing. The HMAC-signed cookie prevents forgery, but individual claim shapes depend on Cognito version + pool config. Narrow with `typeof` before trusting a claim.\n\n## Error Handling\n\n```typescript\nimport { isBlocksError } from '@aws-blocks/core';\nimport { AuthCognitoErrors } from '@aws-blocks/bb-auth-cognito';\n\ntry {\n await auth.signIn('alice', 'wrong', context);\n} catch (e) {\n if (isBlocksError(e, AuthCognitoErrors.NotAuthorized)) {\n // wrong password / unauthorized\n }\n}\n```\n\nError names match Cognito's wire-format exceptions, so customers familiar with AWS encounter the same strings. `AuthCognitoErrors` maps an ergonomic constant to each wire-format `error.name` — match on the constant with `isBlocksError`, never on the raw string.\n\n| Constant | Wire-format `error.name` | Thrown when |\n|---|---|---|\n| `AuthCognitoErrors.NotAuthenticated` | `NotAuthenticatedException` | No valid session — surfaced by `requireAuth` (401). |\n| `AuthCognitoErrors.NotAuthorized` | `NotAuthorizedException` | Bad credentials, or the user is not in the group required by `requireRole` (403). |\n| `AuthCognitoErrors.UserNotFound` | `UserNotFoundException` | No user with that username/alias. |\n| `AuthCognitoErrors.UserAlreadyExists` | `UsernameExistsException` | Username already taken on sign-up. |\n| `AuthCognitoErrors.InvalidPassword` | `InvalidPasswordException` | Password doesn't satisfy the pool policy. |\n| `AuthCognitoErrors.InvalidParameter` | `InvalidParameterException` | Malformed input or an unsupported request shape. |\n| `AuthCognitoErrors.CodeMismatch` | `CodeMismatchException` | Wrong confirmation/MFA code on `RespondToAuthChallenge`. Session stays valid; retriable. |\n| `AuthCognitoErrors.ExpiredCode` | `ExpiredCodeException` | Confirmation/MFA code expired. |\n| `AuthCognitoErrors.LimitExceeded` | `LimitExceededException` | Per-user attempt limit exceeded (e.g. too many code requests). |\n| `AuthCognitoErrors.TooManyRequests` | `TooManyRequestsException` | Request rate-limited by Cognito. |\n| `AuthCognitoErrors.TooManyFailedAttempts` | `TooManyFailedAttemptsException` | Too many failed verification attempts. |\n| `AuthCognitoErrors.PasswordResetRequired` | `PasswordResetRequiredException` | Sign-in blocked — an admin requires a password reset. |\n| `AuthCognitoErrors.UserNotConfirmed` | `UserNotConfirmedException` | User hasn't confirmed sign-up yet. |\n| `AuthCognitoErrors.MFAMethodNotFound` | `MFAMethodNotFoundException` | Requested MFA method isn't configured for the user. |\n| `AuthCognitoErrors.SoftwareTokenMFANotFound` | `SoftwareTokenMFANotFoundException` | TOTP MFA isn't enabled for the user. |\n| `AuthCognitoErrors.GroupNotFound` | `ResourceNotFoundException` | Referenced user-pool group doesn't exist. **Note the non-1:1 mapping — see below.** |\n| `AuthCognitoErrors.UnsupportedUserState` | `UnsupportedUserStateException` | Operation invalid for the user's current state (e.g. force-change-password). |\n| `AuthCognitoErrors.AliasExists` | `AliasExistsException` | Email or phone alias already in use on another user in this pool. |\n| `AuthCognitoErrors.InvalidLambdaResponse` | `InvalidLambdaResponseException` | Cognito Lambda trigger returned a malformed response. |\n| `AuthCognitoErrors.UserLambdaValidation` | `UserLambdaValidationException` | Cognito Lambda trigger threw; error wrapped by Cognito. |\n| `AuthCognitoErrors.InternalError` | `InternalErrorException` | Rare Cognito-side failure. Safe to retry with backoff. |\n| `AuthCognitoErrors.EnableSoftwareTokenMFA` | `EnableSoftwareTokenMFAException` | TOTP code mismatch during `VerifySoftwareToken` (MFA setup). Distinct from `CodeMismatchException`; retriable on the same session. |\n| `AuthCognitoErrors.WebAuthnNotEnabled` | `WebAuthnNotEnabledException` | Pool has no `WebAuthnConfiguration` — passkeys disabled. |\n| `AuthCognitoErrors.WebAuthnOriginNotAllowed` | `WebAuthnOriginNotAllowedException` | Browser submitted a passkey assertion from a non-allow-listed origin. |\n| `AuthCognitoErrors.WebAuthnRelyingPartyMismatch` | `WebAuthnRelyingPartyMismatchException` | Submitted credential's rpId does not match the pool's relying-party config. |\n| `AuthCognitoErrors.WebAuthnChallengeNotFound` | `WebAuthnChallengeNotFoundException` | WebAuthn challenge expired or session lost — caller must restart. |\n| `AuthCognitoErrors.WebAuthnCredentialNotSupported` | `WebAuthnCredentialNotSupportedException` | Submitted credential type / algorithm not supported by the pool config. |\n| `AuthCognitoErrors.WebAuthnClientMismatch` | `WebAuthnClientMismatchException` | Cognito refused the assertion because the client ID does not match. |\n| `AuthCognitoErrors.WebAuthnConfigurationMissing` | `WebAuthnConfigurationMissingException` | Pool is missing required `WebAuthnConfiguration` (rpId / origins). |\n\n> **Non-obvious mapping:** `AuthCognitoErrors.GroupNotFound` resolves to `'ResourceNotFoundException'`, **not** a `GroupNotFound*` string. Cognito has no dedicated \"group not found\" exception, so a missing user-pool group surfaces as the generic `ResourceNotFoundException`. Always match with `isBlocksError(e, AuthCognitoErrors.GroupNotFound)` rather than the literal string so the intent stays clear.\n\n### Branching on the `setAuthState` client path\n\n`isBlocksError` works on a **thrown** error. The recommended client path (`createApi()` → `setAuthState()`) does not throw — it returns an `AuthState` whose `errorName` carries the same structured name. Use `hasAuthError` to branch on the returned state:\n\n```typescript\nimport { hasAuthError } from '@aws-blocks/core';\nimport { AuthCognitoErrors } from '@aws-blocks/bb-auth-cognito';\n\nconst next = await authApi.setAuthState({ action: 'signIn', username, password });\nif (hasAuthError(next, AuthCognitoErrors.NotAuthorized)) {\n // wrong username or password\n}\n```\n\nRule of thumb: **throw path → `isBlocksError`; returned `AuthState` → `hasAuthError`.** Never match on the human-facing `error` string.\n\nFor the `setAuthState()` path, auth failures resolve to an error state instead\nof rejecting the promise. A non-retriable failure returns the normal signed-out\nstate with the available sign-in actions plus `error` and, when available,\n`errorName`:\n\n```typescript\n{\n state: 'signedOut',\n actions: [/* sign-in actions */],\n error: 'Incorrect username or password',\n errorName: AuthCognitoErrors.NotAuthorized,\n}\n```\n\nRetriable challenge failures return a thin error state:\n\n```typescript\n{\n state: 'signedOut',\n actions: [],\n error: 'Invalid code',\n errorName: AuthCognitoErrors.CodeMismatch,\n retriable: true,\n}\n```\n\n`CodeMismatchException` from `confirmSignIn` (for example, a wrong MFA or OTP\ncode) is retriable: Cognito keeps the challenge session valid, so custom UI\nshould keep the current challenge form and its hidden `session` fields in place\nand show the returned `error` inline. The built-in `Authenticator` already does\nthat when it sees `retriable: true`.\n\n## UI Components\n\nUse the provider-agnostic Authenticator from `@aws-blocks/auth-common/ui` — same shape as for `AuthBasic`:\n\n```typescript\nimport { Authenticator } from '@aws-blocks/auth-common/ui';\nimport { authApi } from 'aws-blocks';\n\ndocument.body.appendChild(Authenticator(authApi));\n```\n\nThe state machine (`createApi()`) handles every challenge type, so the same component drives sign-up, confirm, MFA code entry, MFA-type selection, TOTP/Email setup, and password reset — all without frontend code changes.\n\n## Local Development\n\nZero AWS required. The mock uses in-memory data stores persisted to `.bb-data//state.json`. Verification codes are captured by the optional mock-only `codeDelivery` hook (no email service needed for sign-up/reset flows in tests). See the `createConfirmedUser` helper in `test-apps/comprehensive/test/auth-cognito.test.ts` for a worked example that provisions users end-to-end via `signUp` + `confirmSignUp`.\n\n### Full demo app\n\nThe `auth-cognito` template (`packages/create-blocks-app/templates/auth-cognito/`) is a standalone app that exercises every public method with the narrowed types (`as const` options, narrowed `requireRole`, discriminated `confirmSignIn`, typed `setAuthState`). Scaffold via `npm create @aws-blocks/blocks-app my-auth-app -- --template auth-cognito` and run `npm run dev`. See that template's README for the full feature tour.\n\nBackend sketch (matches the template's `aws-blocks/index.ts`):\n\n```ts\nimport { ApiNamespace, Scope } from '@aws-blocks/core';\nimport { AuthCognito } from '@aws-blocks/bb-auth-cognito';\n\n// `as const` on the options unlocks literal narrowing across the API.\nconst options = {\n passwordPolicy: { minLength: 8, requireDigits: true },\n userAttributes: [\n { name: 'department', type: 'String' as const },\n { name: 'employeeId', type: 'Number' as const },\n ] as const,\n groups: ['admins', 'readers'] as const,\n mfaTypes: ['TOTP', 'EMAIL'] as const,\n} as const;\n\nconst scope = new Scope('cognito-demo');\nconst auth = new AuthCognito(scope, 'auth', options);\n\nexport const api = new ApiNamespace(scope, 'api', (context) => ({\n async whoAmI() {\n const user = await auth.requireAuth(context);\n // `user.groups` is narrowed to `('admins' | 'readers')[]`.\n // `user.attributes['custom:department']` is typed.\n return { username: user.username, groups: user.groups };\n },\n async adminOnly() {\n // ❌ `'admin'` (typo) would be a compile error.\n const user = await auth.requireRole(context, 'admins');\n return { message: `Welcome, admin ${user.username}` };\n },\n async enableTOTP() {\n // ❌ `{ sms: 'PREFERRED' }` would be a compile error — pool only\n // configured `['TOTP', 'EMAIL']`.\n await auth.updateMFAPreference(context, { totp: 'PREFERRED' });\n },\n async sessionInfo() {\n const session = await auth.fetchAuthSession(context);\n // Discriminate on a string `status` (not a boolean): native-client codegen\n // (Swift/Kotlin/Dart) only builds a proper discriminated union from a\n // single-value string const/enum per arm.\n if (!session.tokens) return { status: 'signedOut' as const };\n // Claims are `unknown` — narrow before using.\n const payload = session.tokens.idToken.payload;\n const sub = typeof payload.sub === 'string' ? payload.sub : null;\n return { status: 'signedIn' as const, sub };\n },\n}));\n\nexport const authApi = auth.createApi();\n```\n\n## Scaling & Cost\n\nCognito scales automatically. Default quotas: 40 sign-ups/sec, 120 sign-ins/sec (adjustable via Service Quotas). Session records live in a nested DynamoDB table (provisioned by this BB); pay-per-request billing, single-digit ms reads. No per-user storage cost from Cognito.\n\n## Security Model\n\nAWS Blocks auth follows the BFF pattern: the browser sends `{username, password}` to the customer's Lambda over TLS; Lambda forwards to Cognito. The customer's Lambda is inside the user's trust boundary by design — same as `AuthBasic`, `AuthOIDC`, NextAuth, Devise, and every server-mediated auth library. Cognito tokens never reach the browser — instead, the BB issues an opaque HMAC-signed session cookie that maps to a server-side `SessionRecord` in a nested `KVStore`.\n\nThe user pool client sets `PreventUserExistenceErrors: ENABLED`, so sign-in and forgot-password responses return a uniform error whether or not the username exists — closing the account-enumeration oracle Cognito exposes by default.\n\nSee the auth-cognito technical design (see source repo) for the full architecture and mock-vs-AWS parity notes.\n\n## Cookies and sessions\n\nThe session cookie is an opaque, HMAC-signed pointer to a server-side `SessionRecord` (Cognito tokens never reach the browser). By default it is `HttpOnly; SameSite=Lax` (plus `Secure` off localhost), which is correct for same-origin apps and the local dev proxy.\n\nSet `crossDomain: true` only when the frontend and API are served from **different registrable domains** in production (e.g. frontend on Vercel, API on AWS). That switches the cookie to `SameSite=None; Secure; Partitioned` so it survives the cross-site request:\n\n```typescript\nconst auth = new AuthCognito(app, 'auth', { crossDomain: true });\n```\n\nOn plain-HTTP localhost the BB drops `Secure` for the `Lax` default and drops `Partitioned` for the cross-domain recipe (CHIPS requires HTTPS). The auto-sign-in bridge cookie follows the same policy.\n\n\n\n## See Also\n\n- [`@aws-blocks/bb-auth-basic`](../bb-auth-basic/README.md) — Simple username/password for prototypes.\n- [`@aws-blocks/auth-common`](../auth-common/README.md) — Shared `BlocksAuth` interface and `` UI.\n","readmeFilename":"README.md","keywords":["aws-blocks","authentication","cognito","mfa","user-pool"]}