Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.
Python awsaws-emulatoraws-localaws-sdkdevtoolsdockerdynamodbec2emulatorlambdalocalstacklocalstack-alternativeministackmock-awsopen-sourcepythons3sqsterraform
feat(cognito): route invitation and verification emails through SES (#646)
kjdev082fd9e44b4b
diff --git a/ministack/services/cognito.py b/ministack/services/cognito.pyindex 3735f5e3..85181db9 100644--- a/ministack/services/cognito.py+++ b/ministack/services/cognito.py@@ -13,7 +13,7 @@ User Pools operations:AdminSetUserPassword, AdminUpdateUserAttributes,AdminInitiateAuth, AdminRespondToAuthChallenge,InitiateAuth, RespondToAuthChallenge, SignUp, ConfirmSignUp,- ForgotPassword, ConfirmForgotPassword, ChangePassword,+ ResendConfirmationCode, ForgotPassword, ConfirmForgotPassword, ChangePassword,GetUser, UpdateUserAttributes, DeleteUser,AdminAddUserToGroup, AdminRemoveUserFromGroup,AdminListGroupsForUser, AdminListUserAuthEvents,@@ -866,6 +866,7 @@ def _dispatch_idp(action: str, data: dict):# Self-service"SignUp": _sign_up,"ConfirmSignUp": _confirm_sign_up,+ "ResendConfirmationCode": _resend_confirmation_code,"ForgotPassword": _forgot_password,"ConfirmForgotPassword": _confirm_forgot_password,"ChangePassword": _change_password,@@ -1203,6 +1204,176 @@ def _validate_password(pool, password):return None+# ===========================================================================+# EMAIL DELIVERY (invitation + verification)+# ===========================================================================++# AWS Cognito's COGNITO_DEFAULT sender; can be overridden per pool via+# EmailConfiguration.From or globally via the COGNITO_DEFAULT_FROM env var.+_COGNITO_DEFAULT_FROM = "[email protected]"++# Default templates Cognito uses when InviteMessageTemplate /+# VerificationMessageTemplate are not configured on the pool.+_DEFAULT_INVITE_SUBJECT = "Your temporary password"+_DEFAULT_INVITE_MESSAGE = (+ "Your username is {username} and temporary password is {####}."+)+_DEFAULT_VERIFICATION_SUBJECT = "Your verification code"+_DEFAULT_VERIFICATION_MESSAGE = "Your verification code is {####}."+_DEFAULT_VERIFICATION_LINK_MESSAGE = (+ "Please click the link below to verify your email address. {##Verify Email##}"+)+++def _cognito_email_enabled() -> bool:+ val = os.environ.get("COGNITO_EMAIL_ENABLED", "true").strip().lower()+ return val not in ("0", "false", "no", "off", "disabled")+++def _resolve_email_sender(pool: dict) -> tuple:+ """Resolve (from, reply_to, configuration_set) from the pool's EmailConfiguration.++ Falls back to the COGNITO_DEFAULT sender, mirroring real AWS behaviour+ where EmailSendingAccount=COGNITO_DEFAULT uses [email protected].+ A user-supplied From always wins, regardless of EmailSendingAccount.+ """+ cfg = pool.get("EmailConfiguration") or {}+ from_addr = cfg.get("From") or cfg.get("FromEmailAddress") or ""+ if not from_addr:+ from_addr = os.environ.get("COGNITO_DEFAULT_FROM", _COGNITO_DEFAULT_FROM)+ reply_to = cfg.get("ReplyToEmailAddress") or ""+ config_set = cfg.get("ConfigurationSet") or ""+ return from_addr, reply_to, config_set+++def _expand_template(template: str, username: str, code: str) -> str:+ """Apply Cognito's `{username}` and `{####}` placeholder substitutions."""+ if not template:+ return ""+ return template.replace("{username}", username or "").replace("{####}", code or "")+++def _resolve_invite_template(pool: dict) -> tuple:+ """Return (subject, message_text, message_html) for invitation mail."""+ tpl = (pool.get("AdminCreateUserConfig") or {}).get("InviteMessageTemplate") or {}+ subject = tpl.get("EmailSubject") or _DEFAULT_INVITE_SUBJECT+ body = tpl.get("EmailMessage") or _DEFAULT_INVITE_MESSAGE+ # AWS lets EmailMessage be HTML; we store the same text in both slots when+ # the template doesn't disambiguate. SMS template is intentionally ignored.+ return subject, body, ""+++def _resolve_verification_template(pool: dict, by_link: bool = False) -> tuple:+ """Return (subject, message_text) for verification/forgot-password mail."""+ tpl = pool.get("VerificationMessageTemplate") or {}+ if by_link:+ subject = (+ tpl.get("EmailSubjectByLink")+ or pool.get("EmailVerificationSubject")+ or _DEFAULT_VERIFICATION_SUBJECT+ )+ body = (+ tpl.get("EmailMessageByLink")+ or _DEFAULT_VERIFICATION_LINK_MESSAGE+ )+ return subject, body+ subject = (+ tpl.get("EmailSubject")+ or pool.get("EmailVerificationSubject")+ or _DEFAULT_VERIFICATION_SUBJECT+ )+ body = (+ tpl.get("EmailMessage")+ or pool.get("EmailVerificationMessage")+ or _DEFAULT_VERIFICATION_MESSAGE+ )+ return subject, body+++def _looks_like_html(text: str) -> bool:+ if not text:+ return False+ return bool(re.search(r"<[a-zA-Z/!][^>]*>", text))+++def _deliver_cognito_email(pool, to_email, subject, body, type_name, extra=None):+ """Hand a fully-rendered message off to the SES recorder.++ Skipped when COGNITO_EMAIL_ENABLED=false or recipient is missing.+ Errors are swallowed so user-facing Cognito calls never fail because of+ email-only problems (matches AWS, which reports delivery failures async).+ """+ if not _cognito_email_enabled() or not to_email:+ return None+ from_addr, reply_to, config_set = _resolve_email_sender(pool)+ extras = dict(extra or {})+ extras["UserPoolId"] = pool.get("Id", "")+ if reply_to:+ extras["ReplyToAddresses"] = [reply_to]+ body_text = "" if _looks_like_html(body) else body+ body_html = body if _looks_like_html(body) else ""+ try:+ from ministack.services import ses as ses_mod # local import: avoid cycle+ return ses_mod.send_internal_email(+ source=from_addr,+ to_addrs=[to_email],+ subject=subject,+ body_text=body_text,+ body_html=body_html,+ type_name=type_name,+ config_set=config_set,+ extra=extras,+ )+ except Exception:+ logger.exception("Cognito: failed to record %s for pool %s", type_name, pool.get("Id"))+ return None+++def _wants_email_delivery(data: dict) -> bool:+ """Per AWS, DesiredDeliveryMediums defaults to ['SMS']. We treat the+ parameter being absent as 'EMAIL' too so out-of-the-box flows that don't+ pass it still surface invitation mail — AWS itself falls back when no+ SmsConfiguration is set on the pool, which mirrors our SMS-less emulator.+ """+ mediums = data.get("DesiredDeliveryMediums")+ if not mediums:+ return True+ return "EMAIL" in [str(m).upper() for m in mediums]+++def _send_invitation_email(pool, username, temp_password, attr_dict):+ email = (attr_dict or {}).get("email")+ if not email:+ return None+ subject_tpl, body_tpl, _ = _resolve_invite_template(pool)+ subject = _expand_template(subject_tpl, username, temp_password)+ body = _expand_template(body_tpl, username, temp_password)+ return _deliver_cognito_email(+ pool, email, subject, body,+ type_name="CognitoInvitationMessage",+ extra={"Username": username},+ )+++def _send_verification_email(pool, username, attr_dict, code, attribute_name="email"):+ email = (attr_dict or {}).get("email")+ if not email:+ return None+ # CONFIRM_WITH_LINK means body uses {##...##} link placeholder; we still+ # interpolate {####} as the verification code for compatibility.+ by_link = (pool.get("VerificationMessageTemplate") or {}).get(+ "DefaultEmailOption"+ ) == "CONFIRM_WITH_LINK"+ subject_tpl, body_tpl = _resolve_verification_template(pool, by_link=by_link)+ subject = _expand_template(subject_tpl, username, code)+ body = _expand_template(body_tpl, username, code)+ return _deliver_cognito_email(+ pool, email, subject, body,+ type_name="CognitoVerificationMessage",+ extra={"Username": username, "AttributeName": attribute_name},+ )++# ===========================================================================# USER MANAGEMENT# ===========================================================================@@ -1216,7 +1387,21 @@ def _admin_create_user(data):username = data.get("Username")if not username:return error_response_json("InvalidParameterException", "Username is required.", 400)- if username in pool["_users"]:++ message_action = (data.get("MessageAction") or "").upper()+ existing = pool["_users"].get(username)+ if message_action == "RESEND":+ if not existing:+ return error_response_json(+ "UserNotFoundException", "User does not exist.", 400,+ )+ existing["UserLastModifiedDate"] = _now_epoch()+ attr_dict = _attr_list_to_dict(existing.get("Attributes", []))+ if _wants_email_delivery(data):+ _send_invitation_email(pool, username, existing.get("_password", ""), attr_dict)+ return json_response({"User": _user_out(existing)})++ if existing:return error_response_json("UsernameExistsException","User account already exists.", 400,@@ -1249,6 +1434,10 @@ def _admin_create_user(data):pool["_users"][username] = userpool["EstimatedNumberOfUsers"] = len(pool["_users"])logger.info("Cognito: AdminCreateUser %s in pool %s", username, pid)++ if message_action != "SUPPRESS" and _wants_email_delivery(data):+ _send_invitation_email(pool, username, temp_password, attr_dict)+return json_response({"User": _user_out(user)})@@ -1404,9 +1593,42 @@ def _admin_reset_user_password(data):return erruser["UserStatus"] = "RESET_REQUIRED"user["UserLastModifiedDate"] = _now_epoch()+ code = "654321"+ user["_reset_code"] = code+ attrs = _attr_list_to_dict(user.get("Attributes", []))+ _send_verification_email(pool, username, attrs, code, attribute_name="password")return json_response({})+def _resend_confirmation_code(data):+ cid = data.get("ClientId")+ username = data.get("Username")++ pool = None+ for p in _user_pools.values():+ if cid in p["_clients"]:+ pool = p+ break+ if not pool:+ return error_response_json("ResourceNotFoundException", f"Client {cid} not found.", 400)++ user = pool["_users"].get(username)+ if not user:+ return error_response_json("UserNotFoundException", "User does not exist.", 400)++ code = user.get("_confirmation_code") or "123456"+ user["_confirmation_code"] = code+ attrs = _attr_list_to_dict(user.get("Attributes", []))+ _send_verification_email(pool, username, attrs, code)+ return json_response({+ "CodeDeliveryDetails": {+ "Destination": attrs.get("email", ""),+ "DeliveryMedium": "EMAIL",+ "AttributeName": "email",+ }+ })++def _admin_user_global_sign_out(data):pid = data.get("UserPoolId")pool, err = _resolve_pool(pid)@@ -1819,6 +2041,7 @@ def _sign_up(data):"DeliveryMedium": "EMAIL","AttributeName": "email",}+ _send_verification_email(pool, username, attr_dict, user["_confirmation_code"])return json_response(resp)@@ -1861,8 +2084,10 @@ def _forgot_password(data):if not user:return error_response_json("UserNotFoundException", "User does not exist.", 400)- user["_reset_code"] = "654321"+ code = "654321"+ user["_reset_code"] = codeattrs = _attr_list_to_dict(user.get("Attributes", []))+ _send_verification_email(pool, username, attrs, code, attribute_name="password")return json_response({"CodeDeliveryDetails": {"Destination": attrs.get("email", ""),diff --git a/ministack/services/ses.py b/ministack/services/ses.pyindex e6a29d98..63ed3702 100644--- a/ministack/services/ses.py+++ b/ministack/services/ses.py@@ -159,6 +159,32 @@ def _send_email(params):cc_addrs = _collect_list(params, "Destination.CcAddresses.member")bcc_addrs = _collect_list(params, "Destination.BccAddresses.member")+ msg_id = _record_send(+ source=source,+ to_addrs=to_addrs,+ cc_addrs=cc_addrs,+ bcc_addrs=bcc_addrs,+ subject=subject,+ body_text=body_text,+ body_html=body_html,+ type_name="SendEmail",+ config_set=config_set,+ )+ return _xml(200, "SendEmailResponse",+ f"<SendEmailResult><MessageId>{msg_id}</MessageId></SendEmailResult>")+++def _record_send(source, to_addrs, cc_addrs=None, bcc_addrs=None,+ subject="", body_text="", body_html="",+ type_name="SendEmail", config_set="", extra=None):+ """Record a sent email and best-effort SMTP relay. Returns MessageId.++ Used by both HTTP handlers and other in-process services (e.g. Cognito's+ invitation/verification flows) so all simulated mail flows through SES.+ """+ to_addrs = list(to_addrs or [])+ cc_addrs = list(cc_addrs or [])+ bcc_addrs = list(bcc_addrs or [])msg_id = f"{new_uuid()}@email.amazonses.com"record = {"MessageId": msg_id,@@ -167,22 +193,41 @@ def _send_email(params):"CC": cc_addrs,"BCC": bcc_addrs,"Subject": subject,- "BodyText": body_text,- "BodyHtml": body_html,+ "BodyText": body_text or "",+ "BodyHtml": body_html or "","Timestamp": time.time(),- "Type": "SendEmail",+ "Type": type_name,}if config_set:record["ConfigurationSetName"] = config_set+ if extra:+ record.update(extra)_sent_emails_list().append(record)- logger.info("SES SendEmail: %s -> %s | %s", source, to_addrs, subject)+ logger.info("SES %s: %s -> %s | %s", type_name, source, to_addrs, subject)all_addrs = to_addrs + cc_addrs + bcc_addrsif all_addrs:mime_str = _build_mime_message(source, to_addrs, cc_addrs, bcc_addrs,subject, body_text, body_html, msg_id)_smtp_relay(source, all_addrs, mime_str)- return _xml(200, "SendEmailResponse",- f"<SendEmailResult><MessageId>{msg_id}</MessageId></SendEmailResult>")+ return msg_id+++def send_internal_email(source, to_addrs, subject, body_text="", body_html="",+ type_name="InternalSend", config_set="", extra=None):+ """Public hook for other emulated services to deliver mail through SES.++ Returns the MessageId of the stored record.+ """+ return _record_send(+ source=source,+ to_addrs=to_addrs,+ subject=subject,+ body_text=body_text,+ body_html=body_html,+ type_name=type_name,+ config_set=config_set,+ extra=extra,+ )def _send_raw_email(params):diff --git a/tests/test_cognito.py b/tests/test_cognito.pyindex f73be343..370c1ac9 100644--- a/tests/test_cognito.py+++ b/tests/test_cognito.py@@ -2729,3 +2729,219 @@ def test_auth_codes_dict_types_are_plain_builtin_dict():mod = _cognito_module()assert type(mod._auth_codes) is dictassert type(mod._authorization_codes) is dict+++# ---------------------------------------------------------------------------+# Invitation / verification email delivery via SES+# ---------------------------------------------------------------------------++def _fetch_ses_messages():+ """Pull SES outbox via the public inspection endpoint (account 000000000000)."""+ endpoint = os.environ.get("MINISTACK_ENDPOINT", "http://localhost:4566")+ url = f"{endpoint}/_ministack/ses/messages"+ with urllib.request.urlopen(urllib.request.Request(url, method="GET"), timeout=5) as r:+ data = json.loads(r.read().decode())+ return data.get("messages", {}).get("000000000000", [])+++def _messages_to(addr: str, type_name: str | None = None):+ msgs = _fetch_ses_messages()+ return [+ m for m in msgs+ if addr in (m.get("To") or [])+ and (type_name is None or m.get("Type") == type_name)+ ]+++def test_cognito_admin_create_user_sends_invitation_email(cognito_idp):+ pid = cognito_idp.create_user_pool(+ PoolName="InvitePool",+ AdminCreateUserConfig={+ "AllowAdminCreateUserOnly": True,+ "InviteMessageTemplate": {+ "EmailSubject": "Welcome {username}!",+ "EmailMessage": "Hi {username}, your temp password is {####}.",+ },+ },+ )["UserPool"]["Id"]++ email = f"invite-{_uuid_mod.uuid4().hex[:8]}@example.com"+ cognito_idp.admin_create_user(+ UserPoolId=pid,+ Username="invitee",+ UserAttributes=[{"Name": "email", "Value": email}],+ TemporaryPassword="TempPw1!aa",+ DesiredDeliveryMediums=["EMAIL"],+ )++ msgs = _messages_to(email, "CognitoInvitationMessage")+ assert len(msgs) == 1, f"expected 1 invitation message, got {len(msgs)}"+ msg = msgs[0]+ assert msg["Subject"] == "Welcome invitee!"+ body = msg["BodyText"] or msg["BodyHtml"]+ assert "TempPw1!aa" in body+ assert "invitee" in body+ # Default sender when EmailConfiguration is unset matches AWS's COGNITO_DEFAULT.+ assert msg["Source"] == "[email protected]"+++def test_cognito_admin_create_user_suppress_skips_email(cognito_idp):+ pid = cognito_idp.create_user_pool(PoolName="SuppressPool")["UserPool"]["Id"]++ email = f"suppress-{_uuid_mod.uuid4().hex[:8]}@example.com"+ cognito_idp.admin_create_user(+ UserPoolId=pid,+ Username="quiet",+ UserAttributes=[{"Name": "email", "Value": email}],+ TemporaryPassword="TempPw1!bb",+ MessageAction="SUPPRESS",+ DesiredDeliveryMediums=["EMAIL"],+ )++ assert _messages_to(email) == []+++def test_cognito_admin_create_user_resend_sends_again(cognito_idp):+ pid = cognito_idp.create_user_pool(PoolName="ResendPool")["UserPool"]["Id"]++ email = f"resend-{_uuid_mod.uuid4().hex[:8]}@example.com"+ cognito_idp.admin_create_user(+ UserPoolId=pid,+ Username="reinv",+ UserAttributes=[{"Name": "email", "Value": email}],+ TemporaryPassword="TempPw1!cc",+ DesiredDeliveryMediums=["EMAIL"],+ )+ cognito_idp.admin_create_user(+ UserPoolId=pid,+ Username="reinv",+ MessageAction="RESEND",+ DesiredDeliveryMediums=["EMAIL"],+ )++ msgs = _messages_to(email, "CognitoInvitationMessage")+ assert len(msgs) == 2+++def test_cognito_admin_create_user_sms_only_no_email(cognito_idp):+ """If only SMS is requested, MiniStack must not push an EMAIL invitation."""+ pid = cognito_idp.create_user_pool(PoolName="SmsOnlyPool")["UserPool"]["Id"]++ email = f"smsonly-{_uuid_mod.uuid4().hex[:8]}@example.com"+ cognito_idp.admin_create_user(+ UserPoolId=pid,+ Username="smsuser",+ UserAttributes=[+ {"Name": "email", "Value": email},+ {"Name": "phone_number", "Value": "+15555550100"},+ ],+ TemporaryPassword="TempPw1!dd",+ DesiredDeliveryMediums=["SMS"],+ )++ assert _messages_to(email) == []+++def test_cognito_admin_create_user_uses_pool_email_configuration(cognito_idp):+ custom_from = f"custom-{_uuid_mod.uuid4().hex[:8]}@example.com"+ pid = cognito_idp.create_user_pool(+ PoolName="CustomFromPool",+ EmailConfiguration={+ "From": custom_from,+ "ReplyToEmailAddress": "[email protected]",+ "EmailSendingAccount": "DEVELOPER",+ },+ )["UserPool"]["Id"]++ email = f"custom-{_uuid_mod.uuid4().hex[:8]}@example.com"+ cognito_idp.admin_create_user(+ UserPoolId=pid,+ Username="branded",+ UserAttributes=[{"Name": "email", "Value": email}],+ TemporaryPassword="TempPw1!ee",+ DesiredDeliveryMediums=["EMAIL"],+ )++ msgs = _messages_to(email, "CognitoInvitationMessage")+ assert len(msgs) == 1+ assert msgs[0]["Source"] == custom_from+++def test_cognito_signup_sends_verification_email(cognito_idp):+ pid = cognito_idp.create_user_pool(PoolName="SignupVerifyPool")["UserPool"]["Id"]+ cid = cognito_idp.create_user_pool_client(+ UserPoolId=pid, ClientName="VerifyApp",+ )["UserPoolClient"]["ClientId"]++ email = f"signup-{_uuid_mod.uuid4().hex[:8]}@example.com"+ cognito_idp.sign_up(+ ClientId=cid,+ Username="signer",+ Password="Sup3rSecret!",+ UserAttributes=[{"Name": "email", "Value": email}],+ )++ msgs = _messages_to(email, "CognitoVerificationMessage")+ assert len(msgs) == 1+ assert "123456" in (msgs[0]["BodyText"] or msgs[0]["BodyHtml"])+++def test_cognito_forgot_password_sends_verification_email(cognito_idp):+ pid = cognito_idp.create_user_pool(PoolName="ForgotVerifyPool")["UserPool"]["Id"]+ cid = cognito_idp.create_user_pool_client(+ UserPoolId=pid, ClientName="ForgotMailApp",+ )["UserPoolClient"]["ClientId"]+ email = f"forgot-{_uuid_mod.uuid4().hex[:8]}@example.com"+ cognito_idp.admin_create_user(+ UserPoolId=pid,+ Username="forgetter",+ UserAttributes=[{"Name": "email", "Value": email}],+ TemporaryPassword="TempPw1!ff",+ MessageAction="SUPPRESS",+ )++ cognito_idp.forgot_password(ClientId=cid, Username="forgetter")++ msgs = _messages_to(email, "CognitoVerificationMessage")+ assert len(msgs) == 1+ assert "654321" in (msgs[0]["BodyText"] or msgs[0]["BodyHtml"])+++def test_cognito_resend_confirmation_code_sends_email(cognito_idp):+ pid = cognito_idp.create_user_pool(PoolName="ResendCodePool")["UserPool"]["Id"]+ cid = cognito_idp.create_user_pool_client(+ UserPoolId=pid, ClientName="ResendCodeApp",+ )["UserPoolClient"]["ClientId"]++ email = f"resendcode-{_uuid_mod.uuid4().hex[:8]}@example.com"+ cognito_idp.sign_up(+ ClientId=cid,+ Username="resender",+ Password="Sup3rSecret!",+ UserAttributes=[{"Name": "email", "Value": email}],+ )+ cognito_idp.resend_confirmation_code(ClientId=cid, Username="resender")++ msgs = _messages_to(email, "CognitoVerificationMessage")+ assert len(msgs) == 2+++def test_cognito_email_disabled_env_skips_send(cognito_idp, monkeypatch):+ """COGNITO_EMAIL_ENABLED=false must short-circuit delivery in-process."""+ mod = _cognito_module()+ ses_mod = importlib.import_module("ministack.services.ses")+ monkeypatch.setenv("COGNITO_EMAIL_ENABLED", "false")+ before = len(ses_mod._sent_emails_list())++ pool_resp = mod._create_user_pool({"PoolName": "DisabledMailPool"})+ pid = json.loads(pool_resp[2])["UserPool"]["Id"]+ email = f"disabled-{_uuid_mod.uuid4().hex[:8]}@example.com"+ mod._admin_create_user({+ "UserPoolId": pid,+ "Username": "muted",+ "UserAttributes": [{"Name": "email", "Value": email}],+ "TemporaryPassword": "TempPw1!gg",+ "DesiredDeliveryMediums": ["EMAIL"],+ })++ assert len(ses_mod._sent_emails_list()) == before