import * as cip from "@distilled.cloud/aws/cognito-identity-provider";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireDays } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
/**
* Password complexity requirements enforced by the user pool at sign-up and
* password change.
*/
export interface UserPoolPasswordPolicy {
/**
* Minimum password length (6-99).
* @default 8
*/
minimumLength?: number;
/**
* Require at least one uppercase letter.
* @default true
*/
requireUppercase?: boolean;
/**
* Require at least one lowercase letter.
* @default true
*/
requireLowercase?: boolean;
/**
* Require at least one number.
* @default true
*/
requireNumbers?: boolean;
/**
* Require at least one symbol.
* @default true
*/
requireSymbols?: boolean;
/**
* Number of previous passwords a user cannot reuse. Requires the
* `ESSENTIALS` or `PLUS` feature tier.
*/
passwordHistorySize?: number;
/**
* How long an admin-set temporary password stays valid, e.g.
* `"7 days"` (0-365 days). Rounded to whole days on the wire
* (`TemporaryPasswordValidityDays`).
* @default 7 days
*/
temporaryPasswordValidity?: Duration.Input;
}
/**
* A custom schema attribute added to the user pool. Custom attributes are
* automatically prefixed with `custom:` by Cognito. Attributes can be added
* to an existing pool but never removed or changed — removing or modifying a
* declared attribute triggers a replacement.
*/
export interface UserPoolSchemaAttribute {
/**
* Attribute name (without the `custom:` prefix; Cognito adds it).
* 1-20 characters.
*/
name: string;
/**
* The data type of the attribute.
* @default "String"
*/
attributeDataType?: "String" | "Number" | "DateTime" | "Boolean";
/**
* Whether users can change the value after it is set.
* @default true
*/
mutable?: boolean;
/**
* Whether the attribute is required at sign-up. Custom attributes cannot
* be required.
* @default false
*/
required?: boolean;
/**
* Min/max length constraints for `String` attributes (stringified numbers,
* matching the Cognito wire format).
*/
stringConstraints?: { minLength?: string; maxLength?: string };
/**
* Min/max value constraints for `Number` attributes (stringified numbers,
* matching the Cognito wire format).
*/
numberConstraints?: { minValue?: string; maxValue?: string };
/**
* Developer-only attributes can only be modified with IAM credentials
* (prefixed `dev:` in addition to `custom:`).
* @default false
*/
developerOnlyAttribute?: boolean;
}
/**
* The user pool Lambda trigger slots that take a plain function ARN — the
* string-valued keys of the pool's `LambdaConfig`. The versioned custom
* sender slots are configured separately: `CustomEmailSender` through
* {@link UserPoolProps.customEmailSender} (+ `kmsKeyId`); `CustomSMSSender`
* is not modelled yet (an observed one is preserved, never cleared).
*/
export type UserPoolTriggerName =
| "PreSignUp"
| "PostConfirmation"
| "PreAuthentication"
| "PostAuthentication"
| "CustomMessage"
| "DefineAuthChallenge"
| "CreateAuthChallenge"
| "VerifyAuthChallengeResponse"
| "PreTokenGeneration"
| "UserMigration";
const USER_POOL_TRIGGER_NAMES: readonly UserPoolTriggerName[] = [
"PreSignUp",
"PostConfirmation",
"PreAuthentication",
"PostAuthentication",
"CustomMessage",
"DefineAuthChallenge",
"CreateAuthChallenge",
"VerifyAuthChallengeResponse",
"PreTokenGeneration",
"UserMigration",
];
/**
* Lambda trigger configuration for the pool: each key is a trigger slot,
* each value the ARN of the Lambda function Cognito invokes for it.
* Usually populated through the trigger event source
* (`Cognito.onPreSignUp(pool, ...)` etc.) rather than declared directly.
*/
export interface UserPoolLambdaConfig extends Partial<Record<UserPoolTriggerName, string>> {}
/**
* The binding contract of a user pool: event sources contribute
* `LambdaConfig` trigger entries (trigger slot → function ARN) that the
* provider merges with `props.lambdaConfig` and syncs onto the pool.
*/
export interface UserPoolBinding {
/** Trigger entries injected by `Cognito.onUserPoolTrigger` and friends. */
lambdaConfig?: UserPoolLambdaConfig;
}
/**
* Two different Lambda functions were registered for the same user pool
* trigger slot — Cognito supports exactly one function per trigger.
*/
export class ConflictingUserPoolTrigger extends Data.TaggedError("ConflictingUserPoolTrigger")<{
readonly trigger: string;
readonly functionArns: readonly string[];
}> {}
/**
* The user pool's configuration is internally inconsistent (e.g. a custom
* email sender without the KMS key Cognito needs to encrypt the codes it
* hands to the function). Raised before any API call is made.
*/
export class InvalidUserPoolConfiguration extends Data.TaggedError("InvalidUserPoolConfiguration")<{
readonly reason: string;
}> {}
/**
* A first-factor sign-in method for choice-based authentication.
*/
export type UserPoolAuthFactor = "PASSWORD" | "EMAIL_OTP" | "SMS_OTP" | "WEB_AUTHN";
/**
* The sign-in policy of the pool — which first-factor authentication
* methods users may start with (choice-based authentication). Requires the
* `ESSENTIALS` or `PLUS` feature tier.
*/
export interface UserPoolSignInPolicy {
/**
* First-factor sign-in methods the pool allows. `PASSWORD` is the
* classic username + password flow; `EMAIL_OTP` / `SMS_OTP` send a
* one-time code (email OTP is delivered through `customEmailSender` when
* one is configured); `WEB_AUTHN` is passkey sign-in.
* Passwordless factors require the `ESSENTIALS` or `PLUS` tier.
*/
allowedFirstAuthFactors?: UserPoolAuthFactor[];
}
/**
* The `CustomEmailSender` Lambda trigger: Cognito invokes this function
* instead of sending email itself, passing the verification / OTP code
* encrypted with `kmsKeyId` (decrypt it with the AWS Encryption SDK).
* Requires {@link UserPoolProps.kmsKeyId}. The function must also grant
* `cognito-idp.amazonaws.com` invoke access (`AWS.Lambda.Permission`).
*/
export interface UserPoolCustomEmailSender {
/** ARN of the Lambda function that delivers the pool's email messages. */
lambdaArn: string;
/**
* The custom sender event version the function understands.
* @default "V1_0"
*/
lambdaVersion?: "V1_0";
}
/**
* How the user pool delivers its email messages (verification codes, OTPs,
* invitations): either Cognito's built-in, rate-limited delivery
* (`COGNITO_DEFAULT`) or your own verified Amazon SES identity
* (`DEVELOPER`). With `DEVELOPER`, the SES identity's policy must grant
* `cognito-idp.amazonaws.com` permission to send
* (`SES.EmailIdentityPolicy`).
*/
export interface UserPoolEmailConfiguration {
/**
* Which sending account delivers the pool's email. `COGNITO_DEFAULT`
* uses Cognito's built-in delivery (limited daily volume);
* `DEVELOPER` sends through your own SES identity (`sourceArn`
* required) at your SES quota.
* @default "COGNITO_DEFAULT"
*/
emailSendingAccount?: "COGNITO_DEFAULT" | "DEVELOPER";
/**
* ARN of a verified SES email identity (address or domain) in a
* supported region. Required when `emailSendingAccount` is `DEVELOPER`;
* with `COGNITO_DEFAULT` it customizes the FROM address while Cognito
* still handles delivery.
*/
sourceArn?: string;
/**
* The FROM address, either bare (`no-reply@example.com`) or with a
* friendly display name (`"My App <no-reply@example.com>"`). Must be
* covered by the `sourceArn` identity.
*/
from?: string;
/**
* The destination for replies to the pool's messages.
*/
replyToEmailAddress?: string;
/**
* Name of an SES configuration set applied to email sent by the pool
* (event publishing, IP pool selection). `DEVELOPER` only.
*/
configurationSet?: string;
}
/**
* An account recovery mechanism with its priority (1 is highest).
*/
export interface UserPoolRecoveryMechanism {
/** Recovery channel. */
name: "verified_email" | "verified_phone_number" | "admin_only";
/** Priority of this mechanism; 1 is tried first. */
priority: number;
}
export interface UserPoolProps {
/**
* Name of the user pool. If omitted, a deterministic physical name is
* generated from the app, stage, and logical ID.
*/
poolName?: string;
/**
* Password complexity policy for the pool.
*/
passwordPolicy?: UserPoolPasswordPolicy;
/**
* Attributes users may sign in with *instead of* a username
* (`email` and/or `phone_number`). When set, Cognito generates an
* immutable UUID username and the listed attributes become sign-in
* identifiers. Mutually exclusive with `aliasAttributes`.
* Changing this triggers a replacement.
*/
usernameAttributes?: ("email" | "phone_number")[];
/**
* Attributes that may be used as sign-in aliases *in addition to* the
* username (`email`, `phone_number`, `preferred_username`). Mutually
* exclusive with `usernameAttributes`. Changing this triggers a
* replacement.
*/
aliasAttributes?: ("email" | "phone_number" | "preferred_username")[];
/**
* Attributes Cognito verifies automatically by sending a code
* (`email` and/or `phone_number`). `phone_number` requires SMS (SNS)
* configuration.
*/
autoVerifiedAttributes?: ("email" | "phone_number")[];
/**
* Custom schema attributes. Attributes may be added to an existing pool;
* removing or changing a declared attribute triggers a replacement.
*/
schema?: UserPoolSchemaAttribute[];
/**
* Choice-based authentication: the first-factor sign-in methods users may
* start with (`PASSWORD`, `EMAIL_OTP`, `SMS_OTP`, `WEB_AUTHN`). Requires
* the `ESSENTIALS` or `PLUS` tier when any passwordless factor is listed.
* When omitted the observed policy is left untouched.
*/
signInPolicy?: UserPoolSignInPolicy;
/**
* Multi-factor authentication mode. `ON` requires SMS or TOTP setup for
* every user; avoid SMS-based MFA unless the account has SNS spend
* entitlements.
* @default "OFF"
*/
mfaConfiguration?: "OFF" | "OPTIONAL" | "ON";
/**
* Account recovery mechanisms in priority order.
* @default verified_email then verified_phone_number
*/
accountRecovery?: UserPoolRecoveryMechanism[];
/**
* When true the pool cannot be deleted until protection is disabled.
* @default false
*/
deletionProtection?: boolean;
/**
* When true, only administrators (via `AdminCreateUser`) can create
* users — public `SignUp` is disabled.
* @default false
*/
adminCreateUserOnly?: boolean;
/**
* Whether usernames are case sensitive. Changing this triggers a
* replacement.
* @default true (the API default)
*/
usernameCaseSensitive?: boolean;
/**
* The feature tier of the user pool.
* @default "ESSENTIALS"
*/
tier?: "LITE" | "ESSENTIALS" | "PLUS";
/**
* Lambda trigger configuration (trigger slot → function ARN). Merged with
* trigger entries injected through the binding contract by
* `Cognito.onUserPoolTrigger` / `onPreSignUp` / etc. — prefer those over
* declaring ARNs here, since the event source also creates the invoke
* Permission and registers the runtime handler.
*/
lambdaConfig?: UserPoolLambdaConfig;
/**
* Route the pool's email messages (sign-up / OTP / recovery codes,
* temporary passwords) through your own Lambda function instead of
* Cognito's built-in delivery. Requires `kmsKeyId`. Omitting this on an
* existing pool clears the custom sender (Cognito falls back to its own
* email delivery); ordinary triggers and the other pool settings are
* never affected by adding or removing it.
*/
customEmailSender?: UserPoolCustomEmailSender;
/**
* How the pool delivers its email messages: Cognito's built-in delivery
* (`COGNITO_DEFAULT`, the service default) or a verified SES identity
* (`DEVELOPER`) — no custom sender Lambda required. When omitted, an
* observed email configuration is preserved rather than reset to the
* service default.
*/
emailConfiguration?: UserPoolEmailConfiguration;
/**
* ARN of the symmetric KMS key Cognito uses to encrypt the codes it
* passes to the custom sender function(s) (`LambdaConfig.KMSKeyID`).
* The principal running the deploy must hold `kms:CreateGrant` on the
* key — Cognito creates a grant against it when the pool is configured —
* and the sender function's role needs `kms:Decrypt`.
*/
kmsKeyId?: string;
/**
* Tags to apply to the user pool. Merged with internal Alchemy tags.
*/
tags?: Record<string, string>;
}
export interface UserPool extends Resource<
"AWS.Cognito.UserPool",
UserPoolProps,
{
/** The generated ID of the user pool, e.g. `us-west-2_AbCdEfGhI`. */
userPoolId: string;
/** The ARN of the user pool. */
userPoolArn: string;
/** The name of the user pool. */
userPoolName: string;
},
UserPoolBinding,
Providers
> {}
/**
* An Amazon Cognito user pool — a managed user directory that handles
* sign-up, sign-in, and token issuance (OIDC-compliant JWTs) for your
* application.
* ### Creating a User Pool
* **Example:** Basic User Pool
* ```typescript
* import * as Cognito from "@alchemy.run/aws/Cognito";
*
* const pool = yield* Cognito.UserPool("Users", {});
* ```
*
* **Example:** Email Sign-In with Password Policy
* ```typescript
* const pool = yield* Cognito.UserPool("Users", {
* usernameAttributes: ["email"],
* autoVerifiedAttributes: ["email"],
* passwordPolicy: {
* minimumLength: 12,
* requireSymbols: false,
* },
* });
* ```
*
* **Example:** Admin-Only User Creation
* ```typescript
* const pool = yield* Cognito.UserPool("Users", {
* adminCreateUserOnly: true,
* accountRecovery: [{ name: "admin_only", priority: 1 }],
* });
* ```
*
* ### Custom Attributes
* **Example:** Pool with Custom Schema Attributes
* ```typescript
* const pool = yield* Cognito.UserPool("Users", {
* schema: [
* { name: "tenantId", mutable: false },
* { name: "plan", attributeDataType: "String" },
* ],
* });
* ```
*
* ### Sending Email Through SES
* **Example:** OTP and Verification Email from a Verified SES Identity
* ```typescript
* const identity = yield* SES.EmailIdentity("Sender", {
* emailIdentity: "mail.example.com",
* });
* // allow Cognito to send through the identity
* yield* SES.EmailIdentityPolicy("CognitoSend", {
* emailIdentity: identity.emailIdentity,
* policyName: "cognito",
* policy: {
* Version: "2012-10-17",
* Statement: [{
* Effect: "Allow",
* Principal: { Service: "cognito-idp.amazonaws.com" },
* Action: ["ses:SendEmail", "ses:SendRawEmail"],
* Resource: identity.identityArn,
* }],
* },
* });
* const pool = yield* Cognito.UserPool("Users", {
* usernameAttributes: ["email"],
* autoVerifiedAttributes: ["email"],
* emailConfiguration: {
* emailSendingAccount: "DEVELOPER",
* sourceArn: identity.identityArn,
* from: "My App <no-reply@mail.example.com>",
* replyToEmailAddress: "support@example.com",
* },
* });
* ```
*
* ### Email OTP with a Custom Email Sender
* **Example:** Passwordless Email OTP Delivered by Your Own Lambda
* ```typescript
* const key = yield* KMS.Key("CodeKey", {});
* const sender = yield* Lambda.Function("EmailSender", {
* main: import.meta.url,
* });
* yield* Lambda.Permission("CognitoInvoke", {
* functionName: sender.functionName,
* action: "lambda:InvokeFunction",
* principal: "cognito-idp.amazonaws.com",
* });
* const pool = yield* Cognito.UserPool("Auth", {
* tier: "ESSENTIALS",
* usernameAttributes: ["email"],
* signInPolicy: { allowedFirstAuthFactors: ["PASSWORD", "EMAIL_OTP"] },
* customEmailSender: { lambdaArn: sender.functionArn },
* kmsKeyId: key.keyArn,
* });
* ```
*
* ### App Clients and Auth
* **Example:** Pool with an App Client
* ```typescript
* const pool = yield* Cognito.UserPool("Users", {});
* const client = yield* Cognito.UserPoolClient("Web", {
* userPoolId: pool.userPoolId,
* explicitAuthFlows: ["ALLOW_USER_PASSWORD_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"],
* });
* ```
*
* @resource
*/
export const UserPool = Resource<UserPool>("AWS.Cognito.UserPool");
/** Map camelCase password policy props to the Cognito wire shape (the wire
* unit for `TemporaryPasswordValidityDays` is whole days). */
const toWirePasswordPolicy = (policy: UserPoolPasswordPolicy | undefined) =>
policy === undefined
? undefined
: {
MinimumLength: policy.minimumLength,
RequireUppercase: policy.requireUppercase,
RequireLowercase: policy.requireLowercase,
RequireNumbers: policy.requireNumbers,
RequireSymbols: policy.requireSymbols,
PasswordHistorySize: policy.passwordHistorySize,
TemporaryPasswordValidityDays: toWireDays(policy.temporaryPasswordValidity),
};
const toWireSchemaAttribute = (attribute: UserPoolSchemaAttribute) => ({
Name: attribute.name,
AttributeDataType: attribute.attributeDataType ?? "String",
Mutable: attribute.mutable ?? true,
Required: attribute.required ?? false,
DeveloperOnlyAttribute: attribute.developerOnlyAttribute,
StringAttributeConstraints:
attribute.stringConstraints === undefined
? undefined
: {
MinLength: attribute.stringConstraints.minLength,
MaxLength: attribute.stringConstraints.maxLength,
},
NumberAttributeConstraints:
attribute.numberConstraints === undefined
? undefined
: {
MinValue: attribute.numberConstraints.minValue,
MaxValue: attribute.numberConstraints.maxValue,
},
});
const toWireAccountRecovery = (mechanisms: UserPoolRecoveryMechanism[] | undefined) =>
mechanisms === undefined
? undefined
: {
RecoveryMechanisms: mechanisms.map((m) => ({
Name: m.name,
Priority: m.priority,
})),
};
const toWireSignInPolicy = (policy: UserPoolSignInPolicy | undefined) =>
policy === undefined ? undefined : { AllowedFirstAuthFactors: policy.allowedFirstAuthFactors };
const toWireEmailConfiguration = (
config: UserPoolEmailConfiguration | undefined,
): cip.EmailConfigurationType | undefined =>
config === undefined
? undefined
: {
EmailSendingAccount: config.emailSendingAccount ?? "COGNITO_DEFAULT",
SourceArn: config.sourceArn,
From: config.from,
ReplyToEmailAddress: config.replyToEmailAddress,
ConfigurationSet: config.configurationSet,
};
/** Observed/desired email configuration with the service default filled in,
* for order- and absence-insensitive comparison (`JSON.stringify` drops the
* `undefined` members on both sides). */
const normalizedEmailConfiguration = (config: cip.EmailConfigurationType | undefined) => ({
emailSendingAccount: config?.EmailSendingAccount ?? "COGNITO_DEFAULT",
sourceArn: config?.SourceArn,
from: config?.From,
replyToEmailAddress: config?.ReplyToEmailAddress,
configurationSet: config?.ConfigurationSet,
});
const toWireCustomEmailSender = (
sender: UserPoolCustomEmailSender | undefined,
): cip.CustomEmailLambdaVersionConfigType | undefined =>
sender === undefined
? undefined
: {
LambdaArn: sender.lambdaArn,
LambdaVersion: sender.lambdaVersion ?? "V1_0",
};
const PASSWORDLESS_AUTH_FACTORS: readonly UserPoolAuthFactor[] = [
"EMAIL_OTP",
"SMS_OTP",
"WEB_AUTHN",
];
/**
* Reject configurations Cognito would refuse (or silently mangle) before
* any API call is made.
*/
const validateProps = (props: UserPoolProps) =>
props.customEmailSender !== undefined && props.kmsKeyId === undefined
? Effect.fail(
new InvalidUserPoolConfiguration({
reason:
"customEmailSender requires kmsKeyId — Cognito encrypts the codes it passes to the custom sender with that KMS key",
}),
)
: props.emailConfiguration?.emailSendingAccount === "DEVELOPER" &&
props.emailConfiguration.sourceArn === undefined
? Effect.fail(
new InvalidUserPoolConfiguration({
reason:
"emailConfiguration with emailSendingAccount DEVELOPER requires sourceArn — the ARN of the verified SES identity Cognito sends from",
}),
)
: props.tier === "LITE" &&
(props.signInPolicy?.allowedFirstAuthFactors ?? []).some((factor) =>
PASSWORDLESS_AUTH_FACTORS.includes(factor),
)
? Effect.fail(
new InvalidUserPoolConfiguration({
reason:
"passwordless first-auth factors (EMAIL_OTP / SMS_OTP / WEB_AUTHN) require the ESSENTIALS or PLUS tier, not LITE",
}),
)
: Effect.void;
const tagRecordOf = (
tags: { [key: string]: string | undefined } | undefined,
): Record<string, string> =>
Object.fromEntries(
Object.entries(tags ?? {}).filter((entry): entry is [string, string] => entry[1] !== undefined),
);
/**
* The wire name an observed pool attribute would have for a declared custom
* schema attribute (Cognito prefixes `custom:`, or `dev:custom:` for
* developer-only attributes).
*/
const customAttributeWireName = (attribute: UserPoolSchemaAttribute) =>
attribute.developerOnlyAttribute ? `dev:custom:${attribute.name}` : `custom:${attribute.name}`;
const schemaAttributeChanged = (before: UserPoolSchemaAttribute, after: UserPoolSchemaAttribute) =>
JSON.stringify(toWireSchemaAttribute(before)) !== JSON.stringify(toWireSchemaAttribute(after));
export const UserPoolProvider = () =>
Provider.effect(
UserPool,
Effect.gen(function* () {
const createName = Effect.fn(function* (id: string, props: Pick<UserPoolProps, "poolName">) {
return props.poolName ?? (yield* createPhysicalName({ id, maxLength: 128 }));
});
const describePool = Effect.fn(function* (userPoolId: string) {
return yield* cip.describeUserPool({ UserPoolId: userPoolId }).pipe(
Effect.map((r) => r.UserPool),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
});
/**
* Find a pool by exact name. Pool names are not unique, so return every
* candidate — callers disambiguate by ownership tags.
*/
const findPoolsByName = Effect.fn(function* (name: string) {
const pages = yield* cip.listUserPools.pages({ MaxResults: 60 }).pipe(Stream.runCollect);
const candidates = Array.from(pages)
.flatMap((page) => page.UserPools ?? [])
.filter((pool) => pool.Name === name && pool.Id !== undefined);
return yield* Effect.forEach(candidates, (candidate) => describePool(candidate.Id!), {
concurrency: 3,
}).pipe(Effect.map((pools) => pools.filter((pool) => pool !== undefined)));
});
const attributesOf = (pool: cip.UserPoolType) => ({
userPoolId: pool.Id!,
userPoolArn: pool.Arn!,
userPoolName: pool.Name!,
});
/**
* The pool's desired trigger slots: `props.lambdaConfig` merged with
* the trigger entries contributed through the binding contract
* (`Cognito.onUserPoolTrigger` and friends). Fails when two different
* function ARNs target the same trigger slot.
*/
const resolveTriggers = Effect.fn(function* (
news: UserPoolProps,
bindings: ReadonlyArray<UserPoolBinding | { data?: UserPoolBinding }>,
) {
const merged: Partial<Record<UserPoolTriggerName, string>> = {};
const contributions = [
news.lambdaConfig,
...bindings.map(
(binding) =>
(binding as { data?: UserPoolBinding }).data?.lambdaConfig ??
(binding as UserPoolBinding).lambdaConfig,
),
];
for (const config of contributions) {
if (config === undefined) continue;
for (const trigger of USER_POOL_TRIGGER_NAMES) {
const arn = config[trigger];
if (arn === undefined) continue;
const existing = merged[trigger];
if (existing !== undefined && existing !== arn) {
return yield* new ConflictingUserPoolTrigger({
trigger,
functionArns: [existing, arn],
});
}
merged[trigger] = arn;
}
}
return merged as UserPoolLambdaConfig;
});
/**
* The full desired `LambdaConfig` wire shape: the string trigger slots
* plus the versioned `CustomEmailSender` + `KMSKeyID` from props. The
* provider owns `LambdaConfig` outright, so a trigger or custom sender
* removed from the program is cleared on the pool. The one exception
* is `CustomSMSSender`, which the props cannot express yet: an
* observed one (and the KMS key it needs) is carried over rather than
* wiped by an unrelated update. Returns `undefined` when nothing is
* desired (omitting `LambdaConfig` clears it on both create and
* update).
*/
const desiredLambdaConfig = (
news: UserPoolProps,
triggers: UserPoolLambdaConfig,
observed: cip.LambdaConfigType | undefined,
): cip.LambdaConfigType | undefined => {
const customSMSSender = observed?.CustomSMSSender;
const config: cip.LambdaConfigType = {
...triggers,
CustomEmailSender: toWireCustomEmailSender(news.customEmailSender),
CustomSMSSender: customSMSSender,
KMSKeyID:
news.kmsKeyId ?? (customSMSSender !== undefined ? observed?.KMSKeyID : undefined),
};
const present = Object.fromEntries(
Object.entries(config).filter(([, value]) => value !== undefined),
) as cip.LambdaConfigType;
return Object.keys(present).length > 0 ? present : undefined;
};
/** True when the managed parts of the observed `LambdaConfig` differ
* from the desired one. */
const lambdaConfigDrifted = (
desired: cip.LambdaConfigType | undefined,
observed: cip.LambdaConfigType | undefined,
) => {
for (const trigger of USER_POOL_TRIGGER_NAMES) {
if (desired?.[trigger] !== observed?.[trigger]) return true;
}
if (
desired?.CustomEmailSender?.LambdaArn !== observed?.CustomEmailSender?.LambdaArn ||
desired?.CustomEmailSender?.LambdaVersion !== observed?.CustomEmailSender?.LambdaVersion
) {
return true;
}
return desired?.KMSKeyID !== observed?.KMSKeyID;
};
/** The update body sent to `updateUserPool` — always the full desired
* state, because Cognito resets any omitted field to its default.
* Props the user left undefined are "don't care" (see `hasDrift`), so
* their OBSERVED value is echoed back rather than dropped — an update
* to one setting must not reset another to its default. */
const desiredUpdate = (
news: UserPoolProps,
observed: cip.UserPoolType,
lambdaConfig: cip.LambdaConfigType | undefined,
): Omit<cip.UpdateUserPoolRequest, "UserPoolId"> => {
const PasswordPolicy =
news.passwordPolicy === undefined
? observed.Policies?.PasswordPolicy
: toWirePasswordPolicy(news.passwordPolicy);
const SignInPolicy =
news.signInPolicy === undefined
? observed.Policies?.SignInPolicy
: toWireSignInPolicy(news.signInPolicy);
return {
LambdaConfig: lambdaConfig,
// updateUserPool resets an omitted EmailConfiguration to the
// service default — echo the OBSERVED configuration back when the
// prop is undefined so unrelated updates never clear it.
EmailConfiguration:
news.emailConfiguration === undefined
? observed.EmailConfiguration
: toWireEmailConfiguration(news.emailConfiguration),
Policies:
PasswordPolicy === undefined && SignInPolicy === undefined
? undefined
: { PasswordPolicy, SignInPolicy },
DeletionProtection: news.deletionProtection ? "ACTIVE" : "INACTIVE",
AutoVerifiedAttributes: news.autoVerifiedAttributes ?? observed.AutoVerifiedAttributes,
MfaConfiguration: news.mfaConfiguration ?? "OFF",
AdminCreateUserConfig:
news.adminCreateUserOnly === undefined
? observed.AdminCreateUserConfig === undefined
? undefined
: {
// never echo the deprecated UnusedAccountValidityDays —
// Cognito rejects it next to TemporaryPasswordValidityDays
AllowAdminCreateUserOnly:
observed.AdminCreateUserConfig.AllowAdminCreateUserOnly,
InviteMessageTemplate: observed.AdminCreateUserConfig.InviteMessageTemplate,
}
: { AllowAdminCreateUserOnly: news.adminCreateUserOnly },
AccountRecoverySetting:
news.accountRecovery === undefined
? observed.AccountRecoverySetting
: toWireAccountRecovery(news.accountRecovery),
UserPoolTier: news.tier ?? observed.UserPoolTier,
};
};
/** Canonicalize a recovery-mechanism list for order-insensitive
* comparison. */
const canonicalRecovery = (
mechanisms: {
priority: number | undefined;
name: string | undefined;
}[],
) =>
mechanisms
.map((m) => `${m.priority}:${m.name}`)
.sort()
.join(",");
/** Full password policy with the Cognito API defaults filled in, so a
* partial desired policy compares fairly against the observed one.
* Operates on the wire shape — `temporaryPasswordValidityDays` is a
* whole number of days (desired durations are converted first). */
const normalizedPasswordPolicy = (
policy: Omit<UserPoolPasswordPolicy, "temporaryPasswordValidity"> & {
temporaryPasswordValidityDays?: number;
},
): Required<
Omit<UserPoolPasswordPolicy, "passwordHistorySize" | "temporaryPasswordValidity">
> & {
passwordHistorySize: number | undefined;
temporaryPasswordValidityDays: number;
} => ({
minimumLength: policy.minimumLength ?? 8,
requireUppercase: policy.requireUppercase ?? true,
requireLowercase: policy.requireLowercase ?? true,
requireNumbers: policy.requireNumbers ?? true,
requireSymbols: policy.requireSymbols ?? true,
passwordHistorySize: policy.passwordHistorySize,
temporaryPasswordValidityDays: policy.temporaryPasswordValidityDays ?? 7,
});
/** True when the observed pool differs from the desired mutable state.
* Props the user left undefined are "don't care" and never drift —
* except `LambdaConfig`, which the provider owns outright (bindings
* contribute to it), so a trigger or custom sender removed from the
* program is drift that clears the observed entry. */
const hasDrift = (
news: UserPoolProps,
observed: cip.UserPoolType,
lambdaConfig: cip.LambdaConfigType | undefined,
) => {
if (lambdaConfigDrifted(lambdaConfig, observed.LambdaConfig)) {
return true;
}
if (
news.signInPolicy?.allowedFirstAuthFactors !== undefined &&
[...news.signInPolicy.allowedFirstAuthFactors].sort().join(",") !==
[...(observed.Policies?.SignInPolicy?.AllowedFirstAuthFactors ?? [])].sort().join(",")
) {
return true;
}
if (news.passwordPolicy !== undefined) {
const desired = normalizedPasswordPolicy({
...news.passwordPolicy,
temporaryPasswordValidityDays: toWireDays(
news.passwordPolicy.temporaryPasswordValidity,
),
});
const actual = normalizedPasswordPolicy({
minimumLength: observed.Policies?.PasswordPolicy?.MinimumLength,
requireUppercase: observed.Policies?.PasswordPolicy?.RequireUppercase,
requireLowercase: observed.Policies?.PasswordPolicy?.RequireLowercase,
requireNumbers: observed.Policies?.PasswordPolicy?.RequireNumbers,
requireSymbols: observed.Policies?.PasswordPolicy?.RequireSymbols,
passwordHistorySize: observed.Policies?.PasswordPolicy?.PasswordHistorySize,
temporaryPasswordValidityDays:
observed.Policies?.PasswordPolicy?.TemporaryPasswordValidityDays,
});
if (JSON.stringify(desired) !== JSON.stringify(actual)) return true;
}
if (
(news.deletionProtection ? "ACTIVE" : "INACTIVE") !==
(observed.DeletionProtection ?? "INACTIVE")
) {
return true;
}
if (
news.autoVerifiedAttributes !== undefined &&
[...news.autoVerifiedAttributes].sort().join(",") !==
[...(observed.AutoVerifiedAttributes ?? [])].sort().join(",")
) {
return true;
}
if ((news.mfaConfiguration ?? "OFF") !== (observed.MfaConfiguration ?? "OFF")) {
return true;
}
if (
news.emailConfiguration !== undefined &&
JSON.stringify(
normalizedEmailConfiguration(toWireEmailConfiguration(news.emailConfiguration)),
) !== JSON.stringify(normalizedEmailConfiguration(observed.EmailConfiguration))
) {
return true;
}
if (
news.adminCreateUserOnly !== undefined &&
news.adminCreateUserOnly !==
(observed.AdminCreateUserConfig?.AllowAdminCreateUserOnly ?? false)
) {
return true;
}
if (
news.accountRecovery !== undefined &&
canonicalRecovery(news.accountRecovery) !==
canonicalRecovery(
(observed.AccountRecoverySetting?.RecoveryMechanisms ?? []).map((m) => ({
priority: m.Priority,
name: m.Name,
})),
)
) {
return true;
}
if (news.tier !== undefined && news.tier !== observed.UserPoolTier) {
return true;
}
return false;
};
return UserPool.Provider.of({
stables: ["userPoolId", "userPoolArn"],
list: () =>
Effect.gen(function* () {
const pages = yield* cip.listUserPools
.pages({ MaxResults: 60 })
.pipe(Stream.runCollect);
const descriptions = Array.from(pages).flatMap((page) => page.UserPools ?? []);
const pools = yield* Effect.forEach(
descriptions.filter((d) => d.Id !== undefined),
(d) => describePool(d.Id!),
{ concurrency: 5 },
);
return pools.filter((pool) => pool !== undefined).map((pool) => attributesOf(pool));
}),
read: Effect.fn(function* ({ id, olds, output }) {
if (output?.userPoolId !== undefined) {
const pool = yield* describePool(output.userPoolId);
if (pool === undefined) return undefined;
const attrs = attributesOf(pool);
const tags = tagRecordOf(pool.UserPoolTags);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}
const name = yield* createName(id, olds ?? {});
const pools = yield* findPoolsByName(name);
if (pools.length === 0) return undefined;
for (const pool of pools) {
if (yield* hasAlchemyTags(id, tagRecordOf(pool.UserPoolTags))) {
return attributesOf(pool);
}
}
return Unowned(attributesOf(pools[0]!));
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
const oldName = yield* createName(id, olds ?? {});
const newName = yield* createName(id, news ?? {});
if (oldName !== newName) return { action: "replace" } as const;
// sign-in configuration is immutable
if (
JSON.stringify(olds?.usernameAttributes ?? []) !==
JSON.stringify(news?.usernameAttributes ?? []) ||
JSON.stringify(olds?.aliasAttributes ?? []) !==
JSON.stringify(news?.aliasAttributes ?? []) ||
(olds?.usernameCaseSensitive ?? true) !== (news?.usernameCaseSensitive ?? true)
) {
return { action: "replace" } as const;
}
// schema attributes are add-only: removal or mutation ⇒ replace
const oldSchema = olds?.schema ?? [];
const newSchema = news?.schema ?? [];
for (const before of oldSchema) {
const after = newSchema.find((a) => a.name === before.name);
if (after === undefined || schemaAttributeChanged(before, after)) {
return { action: "replace" } as const;
}
}
}),
reconcile: Effect.fn(function* ({ id, news = {}, output, session, bindings }) {
yield* validateProps(news);
const name = output?.userPoolName ?? (yield* createName(id, news));
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
const triggers = yield* resolveTriggers(news, bindings);
// 1. OBSERVE — output.userPoolId is only a cache; fall back to a
// name search so out-of-band deletes and adoption converge.
let observed =
output?.userPoolId !== undefined ? yield* describePool(output.userPoolId) : undefined;
if (observed === undefined) {
// Recover from state loss by name — only take over a pool that
// carries our ownership tags (adoption flows arrive with output
// set, not through this path).
const candidates = yield* findPoolsByName(name);
for (const candidate of candidates) {
if (yield* hasAlchemyTags(id, tagRecordOf(candidate.UserPoolTags))) {
observed = candidate;
break;
}
}
}
// 2. ENSURE — create when missing.
if (observed === undefined) {
observed = yield* cip
.createUserPool({
PoolName: name,
LambdaConfig: desiredLambdaConfig(news, triggers, undefined),
Policies:
news.passwordPolicy === undefined && news.signInPolicy === undefined
? undefined
: {
PasswordPolicy: toWirePasswordPolicy(news.passwordPolicy),
SignInPolicy: toWireSignInPolicy(news.signInPolicy),
},
DeletionProtection: news.deletionProtection ? "ACTIVE" : "INACTIVE",
EmailConfiguration: toWireEmailConfiguration(news.emailConfiguration),
UsernameAttributes: news.usernameAttributes,
AliasAttributes: news.aliasAttributes,
AutoVerifiedAttributes: news.autoVerifiedAttributes,
Schema: news.schema?.map(toWireSchemaAttribute),
MfaConfiguration: news.mfaConfiguration ?? "OFF",
AdminCreateUserConfig:
news.adminCreateUserOnly === undefined
? undefined
: { AllowAdminCreateUserOnly: news.adminCreateUserOnly },
AccountRecoverySetting: toWireAccountRecovery(news.accountRecovery),
UsernameConfiguration:
news.usernameCaseSensitive === undefined
? undefined
: { CaseSensitive: news.usernameCaseSensitive },
UserPoolTier: news.tier,
UserPoolTags: desiredTags,
})
.pipe(Effect.map((r) => r.UserPool!));
} else {
// 3. SYNC — updateUserPool resets omitted fields to defaults, so
// the body is always the full desired mutable state; skip the
// call entirely when nothing drifted.
const lambdaConfig = desiredLambdaConfig(news, triggers, observed.LambdaConfig);
if (hasDrift(news, observed, lambdaConfig)) {
yield* cip.updateUserPool({
UserPoolId: observed.Id!,
...desiredUpdate(news, observed, lambdaConfig),
});
}
// 3b. SYNC SCHEMA — custom attributes are add-only.
const observedNames = new Set(
(observed.SchemaAttributes ?? [])
.map((attribute) => attribute.Name)
.filter((n): n is string => n !== undefined),
);
const missing = (news.schema ?? []).filter(
(attribute) =>
!observedNames.has(customAttributeWireName(attribute)) &&
!observedNames.has(attribute.name),
);
if (missing.length > 0) {
yield* cip.addCustomAttributes({
UserPoolId: observed.Id!,
CustomAttributes: missing.map(toWireSchemaAttribute),
});
}
}
const userPoolId = observed.Id!;
const userPoolArn = observed.Arn!;
// 3c. SYNC TAGS — diff against OBSERVED cloud tags so adoption
// converges (never olds/output).
const observedTags = yield* cip.listTagsForResource({ ResourceArn: userPoolArn }).pipe(
Effect.map((r) => tagRecordOf(r.Tags)),
Effect.catchTag("ResourceNotFoundException", () =>
Effect.succeed({} as Record<string, string>),
),
);
const { upsert, removed } = diffTags(observedTags, desiredTags);
if (upsert.length > 0) {
yield* cip.tagResource({
ResourceArn: userPoolArn,
Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
});
}
if (removed.length > 0) {
yield* cip.untagResource({
ResourceArn: userPoolArn,
TagKeys: removed,
});
}
yield* session.note(userPoolId);
return { userPoolId, userPoolArn, userPoolName: name };
}),
delete: Effect.fn(function* ({ output }) {
yield* cip
.deleteUserPool({ UserPoolId: output.userPoolId })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}),
});
}),
);