Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

feat(cognito): support CUSTOM_AUTH flow (Define/Create/Verify triggers) [#725] (#780)

Akhil Adiga123b7b1fa4a1
diff --git a/ministack/services/cognito.py b/ministack/services/cognito.py
index aa00d9ea..522f8c4c 100644
--- a/ministack/services/cognito.py
+++ b/ministack/services/cognito.py
@@ -269,6 +269,34 @@ _identity_tags = AccountScopedDict() # identity_pool_id -> {key: value}
_auth_codes = {} # code -> {pool_id, client_id, username, redirect_uri, scopes, state, created_at}
_AUTH_CODE_TTL = 300 # 5 minutes
+# ---------------------------------------------------------------------------
+# In-memory state — CUSTOM_AUTH Challenge Sessions
+# ---------------------------------------------------------------------------
+
+_challenge_sessions = AccountScopedDict()
+# token (base64-encoded session token, opaque to client) -> {
+# 'pool_id': str,
+# 'client_id': str,
+# 'username': str,
+# 'created_at': float (epoch seconds),
+# 'expires_at': float (epoch seconds),
+# 'challenges': [
+# {
+# 'challengeName': 'CUSTOM_CHALLENGE',
+# 'challengeResult': bool | None, # None = pending (not yet verified)
+# 'challengeMetadata': str | None, # 'MAGIC_LINK', 'SMS_OTP', etc.
+# 'publicChallengeParameters': dict,
+# 'privateChallengeParameters': dict,
+# 'timestamp': float,
+# },
+# ...
+# ],
+# 'last_challenge_metadata': str | None,
+# }
+
+_CHALLENGE_SESSION_TTL = 3600 # fallback only — see _create_challenge_session for TTL from client config
+_MAX_CHALLENGE_ATTEMPTS = 3 # AWS parity — terminate CUSTOM_AUTH after 3 answered rounds
+
# ── Persistence ────────────────────────────────────────────
@@ -281,6 +309,7 @@ def get_state():
"authorization_codes": copy.deepcopy(_authorization_codes),
"refresh_tokens": copy.deepcopy(_refresh_tokens),
"auth_codes": copy.deepcopy(_auth_codes),
+ "challenge_sessions": copy.deepcopy(_challenge_sessions),
}
@@ -293,6 +322,7 @@ def restore_state(data):
_authorization_codes.update(data.get("authorization_codes", {}))
_refresh_tokens.update(data.get("refresh_tokens", {}))
_auth_codes.update(data.get("auth_codes", {}))
+ _challenge_sessions.update(data.get("challenge_sessions", {}))
try:
@@ -705,6 +735,380 @@ def _merge_attributes(existing: list, updates: list) -> list:
return _dict_to_attr_list(d)
+# ---------------------------------------------------------------------------
+# CUSTOM_AUTH Challenge Session Helpers (Phase 2)
+# ---------------------------------------------------------------------------
+
+def _create_challenge_session(pool_id: str, client_id: str, username: str) -> tuple:
+ """Create a new challenge session and return (token, session).
+
+ Args:
+ pool_id: User pool ID
+ client_id: Client/App ID
+ username: Authenticated username
+
+ Returns:
+ (token: str, session: dict)
+ """
+ token = base64.b64encode(secrets.token_bytes(32)).decode()
+ now = time.time()
+
+ # Compute TTL from client's AuthSessionValidity (in minutes), falling back to _CHALLENGE_SESSION_TTL
+ pool = _user_pools.get(pool_id)
+ client = (pool or {}).get("_clients", {}).get(client_id, {})
+ ttl = client.get("AuthSessionValidity", 3) * 60 # AuthSessionValidity is in minutes
+
+ session = {
+ "pool_id": pool_id,
+ "client_id": client_id,
+ "username": username,
+ "created_at": now,
+ "expires_at": now + ttl,
+ "challenges": [],
+ "last_challenge_metadata": None,
+ }
+ _challenge_sessions[token] = session
+ return (token, session)
+
+
+def _get_challenge_session(token: str) -> tuple:
+ """Retrieve a challenge session from storage.
+
+ Args:
+ token: Session token (base64-encoded)
+
+ Returns:
+ (session: dict | None, error_str: str | None)
+ """
+ session = _challenge_sessions.get(token)
+ if session is None:
+ return (None, "InvalidParameterException: Session does not exist")
+
+ if time.time() > session["expires_at"]:
+ del _challenge_sessions[token]
+ return (None, "NotAuthorizedException: Session has expired")
+
+ return (session, None)
+
+
+def _append_challenge_to_session(session: dict, challenge_name: str,
+ challenge_result: bool | None,
+ challenge_metadata: str | None,
+ public_params: dict | None,
+ private_params: dict | None) -> None:
+ """Append a challenge record to a session's challenge history.
+
+ Args:
+ session: The session dict
+ challenge_name: Challenge name (e.g., 'CUSTOM_CHALLENGE')
+ challenge_result: None (pending), True (correct), or False (incorrect)
+ challenge_metadata: Metadata string (e.g., 'MAGIC_LINK')
+ public_params: Public challenge parameters dict
+ private_params: Private challenge parameters dict
+ """
+ session["challenges"].append({
+ "challengeName": challenge_name,
+ "challengeResult": challenge_result,
+ "challengeMetadata": challenge_metadata,
+ "publicChallengeParameters": public_params or {},
+ "privateChallengeParameters": private_params or {},
+ "timestamp": time.time(),
+ })
+ session["last_challenge_metadata"] = challenge_metadata
+
+
+def _build_session_list(session: dict) -> list:
+ """Build the session list for Lambda events (challenge history).
+
+ Args:
+ session: The session dict
+
+ Returns:
+ List of challenge records (challengeName, challengeMetadata, challengeResult)
+ """
+ return [
+ {
+ "challengeName": c["challengeName"],
+ "challengeMetadata": c["challengeMetadata"],
+ "challengeResult": c["challengeResult"],
+ }
+ for c in session["challenges"]
+ ]
+
+
+# ---------------------------------------------------------------------------
+# CUSTOM_AUTH Lambda Trigger Event Builders (Phase 3)
+# ---------------------------------------------------------------------------
+
+def _build_define_auth_challenge_event(pool_id: str, client_id: str, username: str,
+ user_attrs: dict, session: dict) -> dict:
+ """Build DefineAuthChallenge Lambda event.
+
+ Called at both InitiateAuth and RespondToAuthChallenge to determine
+ the next step in the authentication flow.
+ """
+ return {
+ "version": "1",
+ "triggerSource": "DefineAuthChallenge_Authentication",
+ "region": _pool_region(pool_id),
+ "userPoolId": pool_id,
+ "userName": username,
+ "callerContext": {
+ "awsSdkVersion": "ministack",
+ "clientId": client_id,
+ },
+ "request": {
+ "userAttributes": user_attrs or {},
+ "session": _build_session_list(session),
+ "userNotFound": False,
+ "clientMetadata": {},
+ },
+ "response": {
+ "challengeName": None,
+ "issueTokens": False,
+ "failAuthentication": False,
+ },
+ }
+
+
+def _build_create_auth_challenge_event(pool_id: str, client_id: str, username: str,
+ user_attrs: dict, session: dict,
+ client_metadata: dict) -> dict:
+ """Build CreateAuthChallenge Lambda event.
+
+ Called to generate the challenge (e.g., magic link, SMS OTP) that is sent
+ to the user.
+ """
+ return {
+ "version": "1",
+ "triggerSource": "CreateAuthChallenge_Authentication",
+ "region": _pool_region(pool_id),
+ "userPoolId": pool_id,
+ "userName": username,
+ "callerContext": {
+ "awsSdkVersion": "ministack",
+ "clientId": client_id,
+ },
+ "request": {
+ "userAttributes": user_attrs or {},
+ "challengeName": "CUSTOM_CHALLENGE",
+ "session": _build_session_list(session),
+ "userNotFound": False,
+ "clientMetadata": client_metadata or {},
+ },
+ "response": {
+ "publicChallengeParameters": None,
+ "privateChallengeParameters": None,
+ "challengeMetadata": None,
+ },
+ }
+
+
+def _build_verify_auth_challenge_event(pool_id: str, client_id: str, username: str,
+ user_attrs: dict, session: dict,
+ challenge_answer: str,
+ client_metadata: dict) -> dict:
+ """Build VerifyAuthChallengeResponse Lambda event.
+
+ Called to verify the challenge response (e.g., validate the magic link token
+ or SMS OTP).
+ """
+ last = session["challenges"][-1] if session["challenges"] else {}
+ return {
+ "version": "1",
+ "triggerSource": "VerifyAuthChallengeResponse_Authentication",
+ "region": _pool_region(pool_id),
+ "userPoolId": pool_id,
+ "userName": username,
+ "callerContext": {
+ "awsSdkVersion": "ministack",
+ "clientId": client_id,
+ },
+ "request": {
+ "userAttributes": user_attrs or {},
+ "challengeName": "CUSTOM_CHALLENGE",
+ "session": _build_session_list(session),
+ "userNotFound": False,
+ "challengeAnswer": challenge_answer,
+ "publicChallengeParameters": last.get("publicChallengeParameters", {}),
+ "privateChallengeParameters": last.get("privateChallengeParameters", {}),
+ "clientMetadata": client_metadata or {},
+ },
+ "response": {
+ "answerCorrect": None,
+ },
+ }
+
+
+# ---------------------------------------------------------------------------
+# CUSTOM_AUTH Lambda Invocation Wrappers (Phase 4)
+# ---------------------------------------------------------------------------
+
+
+
+
+def _invoke_define_auth_challenge_trigger(pool_id: str, client_id: str, username: str,
+ user_attrs: dict, session: dict) -> tuple:
+ """Invoke DefineAuthChallenge Lambda trigger.
+
+ Returns:
+ (payload_dict | None, error_response | None)
+ """
+ pool = _user_pools.get(pool_id)
+ if pool is None:
+ return (None, None)
+
+ arn = (pool.get("LambdaConfig") or {}).get("DefineAuthChallenge")
+ if not arn:
+ return (None, None)
+
+ event = _build_define_auth_challenge_event(pool_id, client_id, username, user_attrs, session)
+
+ try:
+ from ministack.services import lambda_svc
+ name, qualifier = lambda_svc._resolve_name_and_qualifier(arn)
+ record, _ = lambda_svc._get_func_record_for_qualifier(name, qualifier)
+ if record is None:
+ return (None, error_response_json("InvalidLambdaResponseException",
+ f"DefineAuthChallenge Lambda not found: {arn}", 400))
+ result = lambda_svc._execute_function(record, event)
+ except Exception as e:
+ return (None, error_response_json("InvalidLambdaResponseException",
+ f"DefineAuthChallenge invocation failed: {str(e)}", 400))
+
+ if result.get("error"):
+ return (None, error_response_json("InvalidLambdaResponseException",
+ f"DefineAuthChallenge returned error: {str(result.get('body', ''))}", 400))
+
+ body = result.get("body")
+ if body is None:
+ return (None, error_response_json("InvalidLambdaResponseException",
+ "DefineAuthChallenge returned null body", 400))
+
+ if isinstance(body, (str, bytes)):
+ try:
+ body = json.loads(body)
+ except (ValueError, TypeError):
+ return (None, error_response_json("InvalidLambdaResponseException",
+ "DefineAuthChallenge returned invalid JSON", 400))
+
+ if not isinstance(body, dict):
+ return (None, error_response_json("InvalidLambdaResponseException",
+ "DefineAuthChallenge returned unexpected body type", 400))
+
+ return (body, None)
+
+
+def _invoke_create_auth_challenge_trigger(pool_id: str, client_id: str, username: str,
+ user_attrs: dict, session: dict,
+ client_metadata: dict) -> tuple:
+ """Invoke CreateAuthChallenge Lambda trigger.
+
+ Returns:
+ (payload_dict | None, error_response | None)
+ """
+ pool = _user_pools.get(pool_id)
+ if pool is None:
+ return (None, None)
+
+ arn = (pool.get("LambdaConfig") or {}).get("CreateAuthChallenge")
+ if not arn:
+ return (None, None)
+
+ event = _build_create_auth_challenge_event(pool_id, client_id, username,
+ user_attrs, session, client_metadata)
+
+ try:
+ from ministack.services import lambda_svc
+ name, qualifier = lambda_svc._resolve_name_and_qualifier(arn)
+ record, _ = lambda_svc._get_func_record_for_qualifier(name, qualifier)
+ if record is None:
+ return (None, error_response_json("InvalidLambdaResponseException",
+ f"CreateAuthChallenge Lambda not found: {arn}", 400))
+ result = lambda_svc._execute_function(record, event)
+ except Exception as e:
+ return (None, error_response_json("InvalidLambdaResponseException",
+ f"CreateAuthChallenge invocation failed: {str(e)}", 400))
+
+ if result.get("error"):
+ return (None, error_response_json("InvalidLambdaResponseException",
+ f"CreateAuthChallenge returned error: {str(result.get('body', ''))}", 400))
+
+ body = result.get("body")
+ if body is None:
+ return (None, error_response_json("InvalidLambdaResponseException",
+ "CreateAuthChallenge returned null body", 400))
+
+ if isinstance(body, (str, bytes)):
+ try:
+ body = json.loads(body)
+ except (ValueError, TypeError):
+ return (None, error_response_json("InvalidLambdaResponseException",
+ "CreateAuthChallenge returned invalid JSON", 400))
+
+ if not isinstance(body, dict):
+ return (None, error_response_json("InvalidLambdaResponseException",
+ "CreateAuthChallenge returned unexpected body type", 400))
+
+ return (body, None)
+
+
+def _invoke_verify_auth_challenge_trigger(pool_id: str, client_id: str, username: str,
+ user_attrs: dict, session: dict,
+ challenge_answer: str,
+ client_metadata: dict) -> tuple:
+ """Invoke VerifyAuthChallengeResponse Lambda trigger.
+
+ Returns:
+ (payload_dict | None, error_response | None)
+ """
+ pool = _user_pools.get(pool_id)
+ if pool is None:
+ return (None, None)
+
+ arn = (pool.get("LambdaConfig") or {}).get("VerifyAuthChallengeResponse")
+ if not arn:
+ return (None, None)
+
+ event = _build_verify_auth_challenge_event(pool_id, client_id, username,
+ user_attrs, session,
+ challenge_answer, client_metadata)
+
+ try:
+ from ministack.services import lambda_svc
+ name, qualifier = lambda_svc._resolve_name_and_qualifier(arn)
+ record, _ = lambda_svc._get_func_record_for_qualifier(name, qualifier)
+ if record is None:
+ return (None, error_response_json("InvalidLambdaResponseException",
+ f"VerifyAuthChallengeResponse Lambda not found: {arn}", 400))
+ result = lambda_svc._execute_function(record, event)
+ except Exception as e:
+ return (None, error_response_json("InvalidLambdaResponseException",
+ f"VerifyAuthChallengeResponse invocation failed: {str(e)}", 400))
+
+ if result.get("error"):
+ return (None, error_response_json("InvalidLambdaResponseException",
+ f"VerifyAuthChallengeResponse returned error: {str(result.get('body', ''))}", 400))
+
+ body = result.get("body")
+ if body is None:
+ return (None, error_response_json("InvalidLambdaResponseException",
+ "VerifyAuthChallengeResponse returned null body", 400))
+
+ if isinstance(body, (str, bytes)):
+ try:
+ body = json.loads(body)
+ except (ValueError, TypeError):
+ return (None, error_response_json("InvalidLambdaResponseException",
+ "VerifyAuthChallengeResponse returned invalid JSON", 400))
+
+ if not isinstance(body, dict):
+ return (None, error_response_json("InvalidLambdaResponseException",
+ "VerifyAuthChallengeResponse returned unexpected body type", 400))
+
+ return (body, None)
+
+
# ---------------------------------------------------------------------------
# SAML / OAuth2 helpers
# ---------------------------------------------------------------------------
@@ -1851,6 +2255,98 @@ def _admin_initiate_auth(data):
result.pop("RefreshToken", None) # AWS doesn't return a new refresh token here
return json_response({"AuthenticationResult": result})
+ if auth_flow == "CUSTOM_AUTH":
+ # Validate ExplicitAuthFlows
+ client = pool["_clients"].get(cid, {})
+ if "ALLOW_CUSTOM_AUTH" not in client.get("ExplicitAuthFlows", []):
+ return error_response_json("InvalidParameterException",
+ "CUSTOM_AUTH flow not allowed for this client.", 400)
+
+ # Get username
+ username = auth_params.get("USERNAME")
+ if not username:
+ return error_response_json("InvalidParameterException",
+ "USERNAME is required.", 400)
+
+ # Validate user
+ user, err = _resolve_user(pool, username)
+ if err:
+ return err
+ if not user.get("Enabled", True):
+ return error_response_json("NotAuthorizedException",
+ "User is disabled.", 400)
+
+ # Extract ClientMetadata (top-level field, NOT inside AuthParameters)
+ client_metadata = data.get("ClientMetadata", {})
+
+ # Build user_attrs dict
+ user_attrs = _attr_list_to_dict(user.get("Attributes", []))
+
+ # Create session
+ token, session = _create_challenge_session(pid, cid, username)
+
+ # Invoke DefineAuthChallenge first
+ define_result, err = _invoke_define_auth_challenge_trigger(
+ pid, cid, username, user_attrs, session
+ )
+ if err:
+ del _challenge_sessions[token]
+ return err
+
+ # Evaluate Define result before proceeding to Create
+ if define_result is not None:
+ resp = define_result.get("response", {}) or {}
+ if resp.get("failAuthentication"):
+ del _challenge_sessions[token]
+ return error_response_json("NotAuthorizedException", "Authentication failed", 400)
+ if resp.get("issueTokens"):
+ del _challenge_sessions[token]
+ return json_response({"AuthenticationResult": _build_auth_result(pid, cid, user)})
+ if not resp.get("challengeName"):
+ del _challenge_sessions[token]
+ return error_response_json("InvalidLambdaResponseException",
+ "DefineAuthChallenge returned unexpected response — not issuing tokens, "
+ "not failing auth, and no challengeName set", 400)
+
+ # Add a pending challenge to session before checking if define/create need to happen
+ _append_challenge_to_session(session, "CUSTOM_CHALLENGE", None, None, {}, {})
+
+ # Invoke CreateAuthChallenge
+ create_result, err = _invoke_create_auth_challenge_trigger(
+ pid, cid, username, user_attrs, session, client_metadata
+ )
+ if err:
+ del _challenge_sessions[token]
+ return err
+
+ # Extract challenge parameters
+ if create_result is not None:
+ public_params = (create_result.get("response", {}) or {}).get("publicChallengeParameters") or {}
+ private_params = (create_result.get("response", {}) or {}).get("privateChallengeParameters") or {}
+ challenge_metadata = (create_result.get("response", {}) or {}).get("challengeMetadata")
+ else:
+ # Default: PROVIDE_AUTH_PARAMETERS — private MUST mirror public so a Verify
+ # Lambda can detect this round via privateChallengeParameters['challenge'].
+ public_params = {"challenge": "PROVIDE_AUTH_PARAMETERS"}
+ private_params = {"challenge": "PROVIDE_AUTH_PARAMETERS"}
+ challenge_metadata = None
+
+ # Update session with challenge parameters
+ if session["challenges"]:
+ session["challenges"][-1].update({
+ "publicChallengeParameters": public_params,
+ "privateChallengeParameters": private_params,
+ "challengeMetadata": challenge_metadata or session["challenges"][-1].get("challengeMetadata"),
+ })
+ session["last_challenge_metadata"] = challenge_metadata
+
+ # Return challenge to client
+ return json_response({
+ "ChallengeName": "CUSTOM_CHALLENGE",
+ "Session": token,
+ "ChallengeParameters": public_params,
+ })
+
return error_response_json("InvalidParameterException", f"Unsupported AuthFlow: {auth_flow}", 400)
@@ -1864,6 +2360,132 @@ def _admin_respond_to_auth_challenge(data):
challenge_name = data.get("ChallengeName", "")
responses = data.get("ChallengeResponses", {})
+ if challenge_name == "CUSTOM_CHALLENGE":
+ # Extract parameters
+ token = data.get("Session")
+ challenge_answer = responses.get("ANSWER", "")
+ client_metadata = data.get("ClientMetadata", {})
+
+ # Validate session
+ session, err = _get_challenge_session(token)
+ if err:
+ # Parse the error from the helper
+ if "Session does not exist" in err:
+ return error_response_json("InvalidParameterException",
+ "Session does not exist", 400)
+ elif "expired" in err.lower():
+ return error_response_json("NotAuthorizedException",
+ "Session has expired", 400)
+ return error_response_json("InvalidParameterException", err, 400)
+
+ # Re-resolve pool and user
+ pool = _user_pools.get(session["pool_id"])
+ if not pool:
+ return error_response_json("ResourceNotFoundException",
+ f"Pool {session['pool_id']} not found.", 400)
+
+ user, err = _resolve_user(pool, session["username"])
+ if err:
+ del _challenge_sessions[token]
+ return err
+
+ user_attrs = _attr_list_to_dict(user.get("Attributes", []))
+
+ # Invoke VerifyAuthChallenge
+ verify_result, err = _invoke_verify_auth_challenge_trigger(
+ session["pool_id"], session["client_id"], session["username"],
+ user_attrs, session, challenge_answer, client_metadata
+ )
+ if err:
+ return err
+
+ # Determine answer_correct
+ if verify_result is not None:
+ answer_correct = bool((verify_result.get("response", {}) or {}).get("answerCorrect", False))
+ else:
+ # No Lambda configured — auto-fail (caller must provide answer)
+ answer_correct = False
+
+ # Append verify result to session
+ _append_challenge_to_session(session, "CUSTOM_CHALLENGE", answer_correct, None, {}, {})
+
+ # Invoke DefineAuthChallenge (evaluates full session history)
+ define_result, err = _invoke_define_auth_challenge_trigger(
+ session["pool_id"], session["client_id"], session["username"],
+ user_attrs, session
+ )
+ if err:
+ return err
+
+ # Determine next action from DefineAuth response
+ if define_result is None:
+ # No Lambda configured — auto-fail
+ del _challenge_sessions[token]
+ return error_response_json("NotAuthorizedException",
+ "Incorrect username or password", 400)
+
+ define_resp = (define_result.get("response") or {})
+
+ # Check failAuthentication flag
+ if define_resp.get("failAuthentication"):
+ del _challenge_sessions[token]
+ return error_response_json("NotAuthorizedException",
+ "Incorrect username or password", 400)
+
+ # Enforce the max challenge-attempts ceiling (AWS parity — issue #725 step 4)
+ answered_count = sum(1 for c in session["challenges"]
+ if c.get("challengeResult") is not None)
+ if answered_count >= _MAX_CHALLENGE_ATTEMPTS:
+ del _challenge_sessions[token]
+ return error_response_json("NotAuthorizedException",
+ "Max authentication attempts exceeded", 400)
+
+ # Check if issueTokens
+ if define_resp.get("issueTokens"):
+ del _challenge_sessions[token]
+ return json_response({"AuthenticationResult": _build_auth_result(
+ session["pool_id"], session["client_id"], user
+ )})
+
+ # Determine next challenge
+ next_challenge = define_resp.get("challengeName")
+ if next_challenge == "CUSTOM_CHALLENGE":
+ # Invoke CreateAuthChallenge for the next round
+ create_result, err = _invoke_create_auth_challenge_trigger(
+ session["pool_id"], session["client_id"], session["username"],
+ user_attrs, session, client_metadata
+ )
+ if err:
+ return err
+
+ # Extract challenge parameters
+ if create_result is not None:
+ public_params = (create_result.get("response", {}) or {}).get("publicChallengeParameters") or {}
+ private_params = (create_result.get("response", {}) or {}).get("privateChallengeParameters") or {}
+ challenge_metadata = (create_result.get("response", {}) or {}).get("challengeMetadata")
+ else:
+ # Default: PROVIDE_AUTH_PARAMETERS — private MUST mirror public so a Verify
+ # Lambda can detect this round via privateChallengeParameters['challenge'].
+ public_params = {"challenge": "PROVIDE_AUTH_PARAMETERS"}
+ private_params = {"challenge": "PROVIDE_AUTH_PARAMETERS"}
+ challenge_metadata = None
+
+ # Append new pending challenge to session
+ _append_challenge_to_session(session, "CUSTOM_CHALLENGE", None, challenge_metadata,
+ public_params, private_params)
+
+ # Return challenge to client
+ return json_response({
+ "ChallengeName": "CUSTOM_CHALLENGE",
+ "Session": token,
+ "ChallengeParameters": public_params,
+ })
+ else:
+ # DefineAuth returned something unexpected — all flags false, no challengeName
+ del _challenge_sessions[token] # clear to prevent infinite loop
+ return error_response_json("InvalidLambdaResponseException",
+ "DefineAuthChallenge response invalid", 400)
+
if challenge_name == "NEW_PASSWORD_REQUIRED":
username = responses.get("USERNAME")
new_password = responses.get("NEW_PASSWORD")
@@ -1974,6 +2596,98 @@ def _initiate_auth(data):
},
})
+ if auth_flow == "CUSTOM_AUTH":
+ # Validate ExplicitAuthFlows
+ client = pool["_clients"].get(cid, {})
+ if "ALLOW_CUSTOM_AUTH" not in client.get("ExplicitAuthFlows", []):
+ return error_response_json("InvalidParameterException",
+ "CUSTOM_AUTH flow not allowed for this client.", 400)
+
+ # Get username
+ username = auth_params.get("USERNAME")
+ if not username:
+ return error_response_json("InvalidParameterException",
+ "USERNAME is required.", 400)
+
+ # Validate user
+ user, err = _resolve_user(pool, username)
+ if err:
+ return err
+ if not user.get("Enabled", True):
+ return error_response_json("NotAuthorizedException",
+ "User is disabled.", 400)
+
+ # Extract ClientMetadata (top-level field, NOT inside AuthParameters)
+ client_metadata = data.get("ClientMetadata", {})
+
+ # Build user_attrs dict
+ user_attrs = _attr_list_to_dict(user.get("Attributes", []))
+
+ # Create session
+ token, session = _create_challenge_session(pid, cid, username)
+
+ # Invoke DefineAuthChallenge first
+ define_result, err = _invoke_define_auth_challenge_trigger(
+ pid, cid, username, user_attrs, session
+ )
+ if err:
+ del _challenge_sessions[token]
+ return err
+
+ # Evaluate Define result before proceeding to Create
+ if define_result is not None:
+ resp = define_result.get("response", {}) or {}
+ if resp.get("failAuthentication"):
+ del _challenge_sessions[token]
+ return error_response_json("NotAuthorizedException", "Authentication failed", 400)
+ if resp.get("issueTokens"):
+ del _challenge_sessions[token]
+ return json_response({"AuthenticationResult": _build_auth_result(pid, cid, user)})
+ if not resp.get("challengeName"):
+ del _challenge_sessions[token]
+ return error_response_json("InvalidLambdaResponseException",
+ "DefineAuthChallenge returned unexpected response — not issuing tokens, "
+ "not failing auth, and no challengeName set", 400)
+
+ # Add a pending challenge to session before checking if define/create need to happen
+ _append_challenge_to_session(session, "CUSTOM_CHALLENGE", None, None, {}, {})
+
+ # Invoke CreateAuthChallenge
+ create_result, err = _invoke_create_auth_challenge_trigger(
+ pid, cid, username, user_attrs, session, client_metadata
+ )
+ if err:
+ del _challenge_sessions[token]
+ return err
+
+ # Extract challenge parameters
+ if create_result is not None:
+ public_params = (create_result.get("response", {}) or {}).get("publicChallengeParameters") or {}
+ private_params = (create_result.get("response", {}) or {}).get("privateChallengeParameters") or {}
+ challenge_metadata = (create_result.get("response", {}) or {}).get("challengeMetadata")
+ else:
+ # Default: PROVIDE_AUTH_PARAMETERS — private MUST mirror public so a Verify
+ # Lambda can detect this round via privateChallengeParameters['challenge'].
+ public_params = {"challenge": "PROVIDE_AUTH_PARAMETERS"}
+ private_params = {"challenge": "PROVIDE_AUTH_PARAMETERS"}
+ challenge_metadata = None
+
+ # Update session with challenge parameters
+ if session["challenges"]:
+ session["challenges"][-1].update({
+ "publicChallengeParameters": public_params,
+ "privateChallengeParameters": private_params,
+ "challengeMetadata": challenge_metadata or session["challenges"][-1].get("challengeMetadata"),
+ })
+ session["last_challenge_metadata"] = challenge_metadata
+
+ # Return challenge to client
+ return json_response({
+ "ChallengeName": "CUSTOM_CHALLENGE",
+ "Session": token,
+ "ChallengeParameters": public_params,
+ })
+
return error_response_json("InvalidParameterException", f"Unsupported AuthFlow: {auth_flow}", 400)
@@ -1992,6 +2706,132 @@ def _respond_to_auth_challenge(data):
if not pool:
return error_response_json("ResourceNotFoundException", f"Client {cid} not found.", 400)
+ if challenge_name == "CUSTOM_CHALLENGE":
+ # Extract parameters
+ token = data.get("Session")
+ challenge_answer = responses.get("ANSWER", "")
+ client_metadata = data.get("ClientMetadata", {})
+
+ # Validate session
+ session, err = _get_challenge_session(token)
+ if err:
+ # Parse the error from the helper
+ if "Session does not exist" in err:
+ return error_response_json("InvalidParameterException",
+ "Session does not exist", 400)
+ elif "expired" in err.lower():
+ return error_response_json("NotAuthorizedException",
+ "Session has expired", 400)
+ return error_response_json("InvalidParameterException", err, 400)
+
+ # Re-resolve pool and user
+ pool = _user_pools.get(session["pool_id"])
+ if not pool:
+ return error_response_json("ResourceNotFoundException",
+ f"Pool {session['pool_id']} not found.", 400)
+
+ user, err = _resolve_user(pool, session["username"])
+ if err:
+ del _challenge_sessions[token]
+ return err
+
+ user_attrs = _attr_list_to_dict(user.get("Attributes", []))
+
+ # Invoke VerifyAuthChallenge
+ verify_result, err = _invoke_verify_auth_challenge_trigger(
+ session["pool_id"], session["client_id"], session["username"],
+ user_attrs, session, challenge_answer, client_metadata
+ )
+ if err:
+ return err
+
+ # Determine answer_correct
+ if verify_result is not None:
+ answer_correct = bool((verify_result.get("response", {}) or {}).get("answerCorrect", False))
+ else:
+ # No Lambda configured — auto-fail (caller must provide answer)
+ answer_correct = False
+
+ # Append verify result to session
+ _append_challenge_to_session(session, "CUSTOM_CHALLENGE", answer_correct, None, {}, {})
+
+ # Invoke DefineAuthChallenge (evaluates full session history)
+ define_result, err = _invoke_define_auth_challenge_trigger(
+ session["pool_id"], session["client_id"], session["username"],
+ user_attrs, session
+ )
+ if err:
+ return err
+
+ # Determine next action from DefineAuth response
+ if define_result is None:
+ # No Lambda configured — auto-fail
+ del _challenge_sessions[token]
+ return error_response_json("NotAuthorizedException",
+ "Incorrect username or password", 400)
+
+ define_resp = (define_result.get("response") or {})
+
+ # Check failAuthentication flag
+ if define_resp.get("failAuthentication"):
+ del _challenge_sessions[token]
+ return error_response_json("NotAuthorizedException",
+ "Incorrect username or password", 400)
+
+ # Enforce the max challenge-attempts ceiling (AWS parity — issue #725 step 4)
+ answered_count = sum(1 for c in session["challenges"]
+ if c.get("challengeResult") is not None)
+ if answered_count >= _MAX_CHALLENGE_ATTEMPTS:
+ del _challenge_sessions[token]
+ return error_response_json("NotAuthorizedException",
+ "Max authentication attempts exceeded", 400)
+
+ # Check if issueTokens
+ if define_resp.get("issueTokens"):
+ del _challenge_sessions[token]
+ return json_response({"AuthenticationResult": _build_auth_result(
+ session["pool_id"], session["client_id"], user
+ )})
+
+ # Determine next challenge
+ next_challenge = define_resp.get("challengeName")
+ if next_challenge == "CUSTOM_CHALLENGE":
+ # Invoke CreateAuthChallenge for the next round
+ create_result, err = _invoke_create_auth_challenge_trigger(
+ session["pool_id"], session["client_id"], session["username"],
+ user_attrs, session, client_metadata
+ )
+ if err:
+ return err
+
+ # Extract challenge parameters
+ if create_result is not None:
+ public_params = (create_result.get("response", {}) or {}).get("publicChallengeParameters") or {}
+ private_params = (create_result.get("response", {}) or {}).get("privateChallengeParameters") or {}
+ challenge_metadata = (create_result.get("response", {}) or {}).get("challengeMetadata")
+ else:
+ # Default: PROVIDE_AUTH_PARAMETERS — private MUST mirror public so a Verify
+ # Lambda can detect this round via privateChallengeParameters['challenge'].
+ public_params = {"challenge": "PROVIDE_AUTH_PARAMETERS"}
+ private_params = {"challenge": "PROVIDE_AUTH_PARAMETERS"}
+ challenge_metadata = None
+
+ # Append new pending challenge to session
+ _append_challenge_to_session(session, "CUSTOM_CHALLENGE", None, challenge_metadata,
+ public_params, private_params)
+
+ # Return challenge to client
+ return json_response({
+ "ChallengeName": "CUSTOM_CHALLENGE",
+ "Session": token,
+ "ChallengeParameters": public_params,
+ })
+ else:
+ # DefineAuth returned something unexpected — all flags false, no challengeName
+ del _challenge_sessions[token] # clear to prevent infinite loop
+ return error_response_json("InvalidLambdaResponseException",
+ "DefineAuthChallenge response invalid", 400)
+
if challenge_name in ("NEW_PASSWORD_REQUIRED", "PASSWORD_VERIFIER"):
username = responses.get("USERNAME")
new_password = responses.get("NEW_PASSWORD") or responses.get("PASSWORD")
diff --git a/tests/test_cognito_custom_auth.py b/tests/test_cognito_custom_auth.py
new file mode 100644
index 00000000..6a2648ee
--- /dev/null
+++ b/tests/test_cognito_custom_auth.py
@@ -0,0 +1,1140 @@
+"""Tests for Cognito CUSTOM_AUTH flow — DefineAuthChallenge, CreateAuthChallenge, VerifyAuthChallenge."""
+
+import io
+import json
+import time
+import zipfile
+
+import pytest
+from botocore.exceptions import ClientError
+
+
+# ── Module-level state reset between tests ────────────────────────────────────
+
[email protected](autouse=True)
+def clear_challenge_sessions():
+ """Reset the TEST-PROCESS _challenge_sessions after each in-process unit test.
+
+ This only clears the test process's module instance (used by the in-process
+ unit tests below). It does NOT touch the server's session store; server-side
+ sessions are keyed by random tokens, so they never collide across API tests.
+ """
+ import ministack.services.cognito as cognito_mod
+ yield
+ cognito_mod._challenge_sessions.clear()
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _make_zip(handler_code: str) -> bytes:
+ buf = io.BytesIO()
+ with zipfile.ZipFile(buf, "w") as zf:
+ zf.writestr("index.py", handler_code)
+ return buf.getvalue()
+
+
+def _setup_pool(cognito_idp, pool_name, lambda_config=None):
+ """Create pool + client with ALLOW_CUSTOM_AUTH + enabled user. Returns (pool_id, client_id)."""
+ kwargs = {"PoolName": pool_name}
+ if lambda_config:
+ kwargs["LambdaConfig"] = lambda_config
+ pid = cognito_idp.create_user_pool(**kwargs)["UserPool"]["Id"]
+ cid = cognito_idp.create_user_pool_client(
+ UserPoolId=pid,
+ ClientName="app",
+ ExplicitAuthFlows=["ALLOW_CUSTOM_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"],
+ )["UserPoolClient"]["ClientId"]
+ cognito_idp.admin_create_user(
+ UserPoolId=pid,
+ Username="[email protected]",
+ MessageAction="SUPPRESS",
+ )
+ cognito_idp.admin_set_user_password(
+ UserPoolId=pid, Username="[email protected]", Password="Pass1234!", Permanent=True
+ )
+ return pid, cid
+
+
+def _create_lambda(lam, fn_name, handler_code):
+ """Deploy a Python Lambda function and return its ARN."""
+ try:
+ lam.delete_function(FunctionName=fn_name)
+ except Exception:
+ pass
+ lam.create_function(
+ FunctionName=fn_name,
+ Runtime="python3.12",
+ Role="arn:aws:iam::000000000000:role/service-role/lambda-role",
+ Handler="index.handler",
+ Code={"ZipFile": _make_zip(handler_code)},
+ )
+ return lam.get_function(FunctionName=fn_name)["Configuration"]["FunctionArn"]
+
+
+# ── Test 1: InitiateAuth CUSTOM_AUTH, no Lambda triggers configured ────────────
+
+def test_custom_auth_initiate_no_trigger(cognito_idp):
+ """When no CreateAuthChallenge Lambda is configured, return the default PROVIDE_AUTH_PARAMETERS challenge."""
+ pid, cid = _setup_pool(cognito_idp, "NoTriggerPool")
+
+ resp = cognito_idp.initiate_auth(
+ ClientId=cid,
+ AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+
+ assert resp["ChallengeName"] == "CUSTOM_CHALLENGE"
+ assert "Session" in resp
+ assert len(resp["Session"]) > 10 # non-empty, real-looking token
+ assert resp["ChallengeParameters"].get("challenge") == "PROVIDE_AUTH_PARAMETERS"
+
+
+# ── Test 2: InitiateAuth with CreateAuthChallenge Lambda ─────────────────────
+
+def test_custom_auth_initiate_with_create_trigger(cognito_idp, lam):
+ """CreateAuthChallenge Lambda is invoked; its publicChallengeParameters are returned."""
+ create_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['publicChallengeParameters'] = {'challenge': 'MAGIC_LINK', 'emailIdentifier': 'A1'}\n"
+ " return event\n"
+ )
+ fn_arn = _create_lambda(lam, "create-auth-basic", create_handler)
+ pid, cid = _setup_pool(cognito_idp, "CreateTriggerPool", {"CreateAuthChallenge": fn_arn})
+
+ resp = cognito_idp.initiate_auth(
+ ClientId=cid,
+ AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+
+ assert resp["ChallengeName"] == "CUSTOM_CHALLENGE"
+ assert resp["ChallengeParameters"]["challenge"] == "MAGIC_LINK"
+ assert resp["ChallengeParameters"]["emailIdentifier"] == "A1"
+
+
+# ── Test 3: InitiateAuth — user not found ────────────────────────────────────
+
+def test_custom_auth_user_not_found(cognito_idp):
+ pid = cognito_idp.create_user_pool(PoolName="NfPool")["UserPool"]["Id"]
+ cid = cognito_idp.create_user_pool_client(
+ UserPoolId=pid, ClientName="app",
+ ExplicitAuthFlows=["ALLOW_CUSTOM_AUTH"],
+ )["UserPoolClient"]["ClientId"]
+
+ with pytest.raises(ClientError) as exc:
+ cognito_idp.initiate_auth(
+ ClientId=cid,
+ AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ assert exc.value.response["Error"]["Code"] == "UserNotFoundException"
+
+
+# ── Test 4: InitiateAuth — user disabled ─────────────────────────────────────
+
+def test_custom_auth_user_disabled(cognito_idp):
+ pid, cid = _setup_pool(cognito_idp, "DisabledPool")
+ cognito_idp.admin_disable_user(UserPoolId=pid, Username="[email protected]")
+
+ with pytest.raises(ClientError) as exc:
+ cognito_idp.initiate_auth(
+ ClientId=cid,
+ AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ assert exc.value.response["Error"]["Code"] == "NotAuthorizedException"
+
+
+# ── Test 5: InitiateAuth — client missing ALLOW_CUSTOM_AUTH ──────────────────
+
+def test_custom_auth_client_missing_explicit_flow(cognito_idp):
+ """Client without ALLOW_CUSTOM_AUTH in ExplicitAuthFlows is rejected."""
+ pid = cognito_idp.create_user_pool(PoolName="WrongFlowPool")["UserPool"]["Id"]
+ cid = cognito_idp.create_user_pool_client(
+ UserPoolId=pid, ClientName="app",
+ ExplicitAuthFlows=["ALLOW_USER_PASSWORD_AUTH"], # no ALLOW_CUSTOM_AUTH
+ )["UserPoolClient"]["ClientId"]
+
+ with pytest.raises(ClientError) as exc:
+ cognito_idp.initiate_auth(
+ ClientId=cid,
+ AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ assert exc.value.response["Error"]["Code"] == "InvalidParameterException"
+
+
+# ── Test 6: RespondToAuthChallenge — missing Session ─────────────────────────
+
+def test_custom_auth_respond_missing_session(cognito_idp):
+ pid, cid = _setup_pool(cognito_idp, "MissingSessionPool")
+
+ with pytest.raises(ClientError) as exc:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ ChallengeResponses={"ANSWER": "test", "USERNAME": "[email protected]"},
+ )
+ assert exc.value.response["Error"]["Code"] == "InvalidParameterException"
+
+
+# ── Test 7: RespondToAuthChallenge — invalid session token ───────────────────
+
+def test_custom_auth_respond_invalid_session(cognito_idp):
+ pid, cid = _setup_pool(cognito_idp, "InvalidSessionPool")
+
+ with pytest.raises(ClientError) as exc:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session="invalid-session-token-1234567890",
+ ChallengeResponses={"ANSWER": "test", "USERNAME": "[email protected]"},
+ )
+ assert exc.value.response["Error"]["Code"] == "InvalidParameterException"
+
+
+# ── Test 8: Session expiry — in-process unit test ────────────────────────────
+# Cannot be driven over HTTP: the test process can't fast-forward the server's
+# session clock, and there's no API to do so. Test the helper directly.
+
+def test_custom_auth_session_expiry_in_process():
+ import ministack.services.cognito as cognito_mod
+
+ token, session = cognito_mod._create_challenge_session(
+ "us-east-1_pool", "client123", "[email protected]"
+ )
+ # Live session resolves cleanly.
+ got, err = cognito_mod._get_challenge_session(token)
+ assert got is session and err is None
+
+ # Expire it, then confirm _get_challenge_session rejects and evicts it.
+ session["expires_at"] = time.time() - 1 # in the past
+ got, err = cognito_mod._get_challenge_session(token)
+ assert got is None
+ assert "expired" in err.lower()
+ assert cognito_mod._challenge_sessions.get(token) is None
+
+
+# ── Test 9: Full flow — correct answer, tokens issued ────────────────────────
+
+def test_custom_auth_full_flow_issue_tokens(cognito_idp, lam):
+ """InitiateAuth → RespondToAuthChallenge with correct answer → AuthenticationResult."""
+ create_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['publicChallengeParameters'] = {'challenge': 'MAGIC_LINK'}\n"
+ " return event\n"
+ )
+ verify_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['answerCorrect'] = True\n"
+ " return event\n"
+ )
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " session = event['request']['session']\n"
+ " if not session:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " elif session[-1].get('challengeResult'):\n"
+ " event['response']['issueTokens'] = True\n"
+ " else:\n"
+ " event['response']['failAuthentication'] = True\n"
+ " return event\n"
+ )
+ create_arn = _create_lambda(lam, "create-full-flow", create_handler)
+ verify_arn = _create_lambda(lam, "verify-full-flow", verify_handler)
+ define_arn = _create_lambda(lam, "define-full-flow", define_handler)
+
+ pid, cid = _setup_pool(cognito_idp, "FullFlowPool", {
+ "CreateAuthChallenge": create_arn,
+ "VerifyAuthChallengeResponse": verify_arn,
+ "DefineAuthChallenge": define_arn,
+ })
+
+ step1 = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ assert step1["ChallengeName"] == "CUSTOM_CHALLENGE"
+ session = step1["Session"]
+
+ step2 = cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "SECRETCODE", "USERNAME": "[email protected]"},
+ )
+ assert "AuthenticationResult" in step2
+ result = step2["AuthenticationResult"]
+ assert "AccessToken" in result
+ assert "IdToken" in result
+ assert "RefreshToken" in result
+
+
+# ── Test 10: Wrong answer → failAuthentication, session cleared ───────────────
+
+def test_custom_auth_wrong_answer_fail_auth(cognito_idp, lam):
+ create_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['publicChallengeParameters'] = {'challenge': 'MAGIC_LINK'}\n"
+ " return event\n"
+ )
+ verify_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['answerCorrect'] = False\n"
+ " return event\n"
+ )
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " session = event['request']['session']\n"
+ " if not session:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " elif session[-1].get('challengeResult'):\n"
+ " event['response']['issueTokens'] = True\n"
+ " else:\n"
+ " event['response']['failAuthentication'] = True\n"
+ " return event\n"
+ )
+ create_arn = _create_lambda(lam, "create-fail-auth", create_handler)
+ verify_arn = _create_lambda(lam, "verify-fail-auth", verify_handler)
+ define_arn = _create_lambda(lam, "define-fail-auth", define_handler)
+
+ pid, cid = _setup_pool(cognito_idp, "FailAuthPool", {
+ "CreateAuthChallenge": create_arn,
+ "VerifyAuthChallengeResponse": verify_arn,
+ "DefineAuthChallenge": define_arn,
+ })
+
+ step1 = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ session = step1["Session"]
+
+ with pytest.raises(ClientError) as exc:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "WRONGCODE", "USERNAME": "[email protected]"},
+ )
+ assert exc.value.response["Error"]["Code"] == "NotAuthorizedException"
+
+ # Prove the session was cleared server-side: retrying with the same token
+ # is now rejected as a non-existent session (verified via the API).
+ with pytest.raises(ClientError) as exc2:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "STILLWRONG", "USERNAME": "[email protected]"},
+ )
+ assert exc2.value.response["Error"]["Code"] == "InvalidParameterException"
+
+
+# ── Test 11: Multi-round — magic link then SMS OTP ────────────────────────────
+
+def test_custom_auth_multi_round(cognito_idp, lam):
+ """Three steps: InitiateAuth → Respond(magic link) → Respond(SMS OTP) → tokens."""
+ create_handler = (
+ "def handler(event, ctx):\n"
+ " answered_count = len([c for c in event['request']['session'] if c.get('challengeResult')])\n"
+ " if answered_count == 0:\n"
+ " event['response']['publicChallengeParameters'] = {'round': '1', 'challenge': 'MAGIC_LINK'}\n"
+ " else:\n"
+ " event['response']['publicChallengeParameters'] = {'round': str(answered_count + 1), 'challenge': 'SMS_OTP'}\n"
+ " return event\n"
+ )
+ verify_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['answerCorrect'] = True\n"
+ " return event\n"
+ )
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " session = event['request']['session']\n"
+ " answered = [s for s in session if s.get('challengeResult') is not None]\n"
+ " if not session:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " elif len(answered) >= 2:\n"
+ " event['response']['issueTokens'] = True\n"
+ " else:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " return event\n"
+ )
+ create_arn = _create_lambda(lam, "create-multi", create_handler)
+ verify_arn = _create_lambda(lam, "verify-multi", verify_handler)
+ define_arn = _create_lambda(lam, "define-multi", define_handler)
+
+ pid, cid = _setup_pool(cognito_idp, "MultiRoundPool", {
+ "CreateAuthChallenge": create_arn,
+ "VerifyAuthChallengeResponse": verify_arn,
+ "DefineAuthChallenge": define_arn,
+ })
+
+ step1 = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ assert step1["ChallengeParameters"]["challenge"] == "MAGIC_LINK"
+ session = step1["Session"]
+
+ step2 = cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "magic-link-code", "USERNAME": "[email protected]"},
+ )
+ assert step2.get("ChallengeName") == "CUSTOM_CHALLENGE"
+ assert step2["ChallengeParameters"]["challenge"] == "SMS_OTP"
+ assert step2["Session"] == session # SAME token — never re-generated
+
+ step3 = cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "123456", "USERNAME": "[email protected]"},
+ )
+ assert "AuthenticationResult" in step3
+
+
+# ── Test 12: Lambda not found — session preserved for retry ──────────────────
+
+def test_custom_auth_lambda_not_found_session_preserved(cognito_idp):
+ # Only VerifyAuthChallengeResponse points at a non-existent Lambda.
+ pid, cid = _setup_pool(cognito_idp, "LambdaNotFoundPool", {
+ "VerifyAuthChallengeResponse": "arn:aws:lambda:us-east-1:000000000000:function:does-not-exist",
+ })
+
+ resp = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ session = resp["Session"]
+
+ with pytest.raises(ClientError) as exc:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "test", "USERNAME": "[email protected]"},
+ )
+ assert exc.value.response["Error"]["Code"] == "InvalidLambdaResponseException"
+
+ # Session preserved — a retry with the same token reaches the trigger again
+ with pytest.raises(ClientError) as exc2:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "test", "USERNAME": "[email protected]"},
+ )
+ assert exc2.value.response["Error"]["Code"] == "InvalidLambdaResponseException"
+
+
+# ── Test 13: Lambda crashes — session preserved ───────────────────────────────
+
+def test_custom_auth_lambda_crash_session_preserved(cognito_idp, lam):
+ broken = "def handler(event, ctx):\n raise RuntimeError('boom')\n"
+ verify_arn = _create_lambda(lam, "verify-crash", broken)
+
+ pid, cid = _setup_pool(cognito_idp, "CrashPool", {
+ "VerifyAuthChallengeResponse": verify_arn,
+ })
+
+ resp = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ session = resp["Session"]
+
+ with pytest.raises(ClientError) as exc:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "test", "USERNAME": "[email protected]"},
+ )
+ assert exc.value.response["Error"]["Code"] == "InvalidLambdaResponseException"
+
+ # Session preserved — retry reaches the crashing trigger again
+ with pytest.raises(ClientError) as exc2:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "test", "USERNAME": "[email protected]"},
+ )
+ assert exc2.value.response["Error"]["Code"] == "InvalidLambdaResponseException"
+
+
+# ── Test 14: AdminInitiateAuth CUSTOM_AUTH ────────────────────────────────────
+
+def test_custom_auth_admin_initiate(cognito_idp):
+ pid, cid = _setup_pool(cognito_idp, "AdminInitPool")
+
+ resp = cognito_idp.admin_initiate_auth(
+ UserPoolId=pid, ClientId=cid,
+ AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ assert resp["ChallengeName"] == "CUSTOM_CHALLENGE"
+ assert "Session" in resp
+
+
+# ── Test 15: AdminRespondToAuthChallenge CUSTOM_CHALLENGE ─────────────────────
+
+def test_custom_auth_admin_respond(cognito_idp, lam):
+ verify_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['answerCorrect'] = True\n"
+ " return event\n"
+ )
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " session = event['request']['session']\n"
+ " if not session:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " elif session[-1].get('challengeResult'):\n"
+ " event['response']['issueTokens'] = True\n"
+ " else:\n"
+ " event['response']['failAuthentication'] = True\n"
+ " return event\n"
+ )
+ verify_arn = _create_lambda(lam, "verify-admin", verify_handler)
+ define_arn = _create_lambda(lam, "define-admin", define_handler)
+
+ pid, cid = _setup_pool(cognito_idp, "AdminRespondPool", {
+ "VerifyAuthChallengeResponse": verify_arn,
+ "DefineAuthChallenge": define_arn,
+ })
+
+ step1 = cognito_idp.admin_initiate_auth(
+ UserPoolId=pid, ClientId=cid,
+ AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ session = step1["Session"]
+
+ step2 = cognito_idp.admin_respond_to_auth_challenge(
+ UserPoolId=pid, ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "code", "USERNAME": "[email protected]"},
+ )
+ assert "AuthenticationResult" in step2
+
+
+# ── Test 16: ClientMetadata is top-level, propagated to Lambda ────────────────
+
+def test_custom_auth_client_metadata_propagated(cognito_idp, lam):
+ """ClientMetadata is a top-level InitiateAuth field, not inside AuthParameters."""
+ create_handler = (
+ "def handler(event, ctx):\n"
+ " meta = event['request'].get('clientMetadata', {})\n"
+ " event['response']['publicChallengeParameters'] = {'signInMethod': meta.get('signInMethod', 'unknown')}\n"
+ " return event\n"
+ )
+ create_arn = _create_lambda(lam, "create-meta", create_handler)
+ pid, cid = _setup_pool(cognito_idp, "MetaPool", {"CreateAuthChallenge": create_arn})
+
+ resp = cognito_idp.initiate_auth(
+ ClientId=cid,
+ AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ ClientMetadata={"signInMethod": "MAGIC_LINK"},
+ )
+ assert resp["ChallengeParameters"]["signInMethod"] == "MAGIC_LINK"
+
+
+# ── Test 17: Session persists across get_state/restore_state — in-process ────
+
+def test_custom_auth_session_persistence():
+ import ministack.services.cognito as cognito_mod
+
+ token, _session = cognito_mod._create_challenge_session(
+ "us-east-1_pool", "client123", "[email protected]"
+ )
+ assert cognito_mod._challenge_sessions.get(token) is not None
+
+ # Save, clear, restore.
+ state = cognito_mod.get_state()
+ cognito_mod._challenge_sessions.clear()
+ assert cognito_mod._challenge_sessions.get(token) is None
+ cognito_mod.restore_state(state)
+ assert cognito_mod._challenge_sessions.get(token) is not None
+
+
+# ── Test 18: Concurrent sessions for same user ───────────────────────────────
+
+def test_custom_auth_concurrent_sessions(cognito_idp, lam):
+ """Two parallel auth flows for the same user get independent, usable tokens."""
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " session = event['request']['session']\n"
+ " if not session:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " elif session[-1].get('challengeResult'):\n"
+ " event['response']['issueTokens'] = True\n"
+ " else:\n"
+ " event['response']['failAuthentication'] = True\n"
+ " return event\n"
+ )
+ verify_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['answerCorrect'] = True\n"
+ " return event\n"
+ )
+ define_arn = _create_lambda(lam, "define-concurrent", define_handler)
+ verify_arn = _create_lambda(lam, "verify-concurrent", verify_handler)
+
+ pid, cid = _setup_pool(cognito_idp, "ConcurrentPool", {
+ "DefineAuthChallenge": define_arn,
+ "VerifyAuthChallengeResponse": verify_arn,
+ })
+
+ s1 = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )["Session"]
+ s2 = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )["Session"]
+
+ assert s1 != s2
+
+ # Both tokens are live and independent — complete each to tokens
+ r1 = cognito_idp.respond_to_auth_challenge(
+ ClientId=cid, ChallengeName="CUSTOM_CHALLENGE", Session=s1,
+ ChallengeResponses={"ANSWER": "", "USERNAME": "[email protected]"},
+ )
+ r2 = cognito_idp.respond_to_auth_challenge(
+ ClientId=cid, ChallengeName="CUSTOM_CHALLENGE", Session=s2,
+ ChallengeResponses={"ANSWER": "", "USERNAME": "[email protected]"},
+ )
+ # Each session should issue tokens independently (DefineAuthChallenge sees a completed challenge)
+ assert "AuthenticationResult" in r1
+ assert "AuthenticationResult" in r2
+
+
+# ── Test 19: LambdaConfig keys stored correctly ───────────────────────────────
+
+def test_custom_auth_lambda_config_stored(cognito_idp):
+ """Pool LambdaConfig stores DefineAuthChallenge, CreateAuthChallenge, VerifyAuthChallengeResponse."""
+ define_arn = "arn:aws:lambda:us-east-1:000000000000:function:define"
+ create_arn = "arn:aws:lambda:us-east-1:000000000000:function:create"
+ verify_arn = "arn:aws:lambda:us-east-1:000000000000:function:verify"
+
+ pid = cognito_idp.create_user_pool(
+ PoolName="LambdaConfigPool",
+ LambdaConfig={
+ "DefineAuthChallenge": define_arn,
+ "CreateAuthChallenge": create_arn,
+ "VerifyAuthChallengeResponse": verify_arn,
+ },
+ )["UserPool"]["Id"]
+
+ desc = cognito_idp.describe_user_pool(UserPoolId=pid)["UserPool"]
+ cfg = desc["LambdaConfig"]
+ assert cfg["DefineAuthChallenge"] == define_arn
+ assert cfg["CreateAuthChallenge"] == create_arn
+ assert cfg["VerifyAuthChallengeResponse"] == verify_arn
+
+
+# ── Test 20: DefineAuth unexpected response — session cleared ─────────────────
+
+def test_custom_auth_define_unexpected_response_clears_session(cognito_idp, lam):
+ """DefineAuthChallenge with all-false response and no challengeName clears session."""
+ verify_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['answerCorrect'] = True\n"
+ " return event\n"
+ )
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " session = event['request']['session']\n"
+ " if not session:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " else:\n"
+ " pass\n"
+ " return event\n"
+ )
+ verify_arn = _create_lambda(lam, "verify-unexpected", verify_handler)
+ define_arn = _create_lambda(lam, "define-unexpected", define_handler)
+
+ pid, cid = _setup_pool(cognito_idp, "UnexpectedPool", {
+ "VerifyAuthChallengeResponse": verify_arn,
+ "DefineAuthChallenge": define_arn,
+ })
+
+ resp = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ session = resp["Session"]
+
+ with pytest.raises(ClientError) as exc:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "test", "USERNAME": "[email protected]"},
+ )
+ assert exc.value.response["Error"]["Code"] == "InvalidLambdaResponseException"
+
+ # Session cleared
+ with pytest.raises(ClientError) as exc2:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "test", "USERNAME": "[email protected]"},
+ )
+ assert exc2.value.response["Error"]["Code"] == "InvalidParameterException"
+
+
+# ── Test 21: Empty ANSWER is forwarded to Lambda ────────────────────────────
+
+def test_custom_auth_empty_answer_passed_to_lambda(cognito_idp, lam):
+ """Empty ANSWER must not be rejected by the emulator — Lambda handles it."""
+ verify_handler = (
+ "def handler(event, ctx):\n"
+ " answer = event['request'].get('challengeAnswer', '')\n"
+ " event['response']['answerCorrect'] = len(answer) == 0\n"
+ " return event\n"
+ )
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " session = event['request']['session']\n"
+ " if not session:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " elif session[-1].get('challengeResult'):\n"
+ " event['response']['issueTokens'] = True\n"
+ " else:\n"
+ " event['response']['failAuthentication'] = True\n"
+ " return event\n"
+ )
+ verify_arn = _create_lambda(lam, "verify-empty-answer", verify_handler)
+ define_arn = _create_lambda(lam, "define-empty-answer", define_handler)
+
+ pid, cid = _setup_pool(cognito_idp, "EmptyAnswerPool", {
+ "VerifyAuthChallengeResponse": verify_arn,
+ "DefineAuthChallenge": define_arn,
+ })
+
+ step1 = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ session = step1["Session"]
+
+ step2 = cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "", "USERNAME": "[email protected]"},
+ )
+ assert "AuthenticationResult" in step2
+
+
+# ── Test 22: DefineAuth issues tokens at InitiateAuth (zero-round bypass) ────
+
+def test_custom_auth_define_issues_tokens_at_initiate(cognito_idp, lam):
+ """DefineAuthChallenge returning issueTokens=True at InitiateAuth bypasses the challenge."""
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['issueTokens'] = True\n"
+ " return event\n"
+ )
+ define_arn = _create_lambda(lam, "define-bypass", define_handler)
+ pid, cid = _setup_pool(cognito_idp, "BypassPool", {"DefineAuthChallenge": define_arn})
+
+ resp = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ # Tokens issued directly from InitiateAuth
+ assert "AuthenticationResult" in resp
+ assert "AccessToken" in resp["AuthenticationResult"]
+
+
+# ── Test 23: Session cleared after issueTokens=True ──────────────────────────
+
+def test_custom_auth_session_cleared_after_tokens_issued(cognito_idp, lam):
+ """Session is deleted after AuthenticationResult — verified via the API."""
+ verify_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['answerCorrect'] = True\n"
+ " return event\n"
+ )
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " session = event['request']['session']\n"
+ " if not session:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " elif session[-1].get('challengeResult'):\n"
+ " event['response']['issueTokens'] = True\n"
+ " else:\n"
+ " event['response']['failAuthentication'] = True\n"
+ " return event\n"
+ )
+ verify_arn = _create_lambda(lam, "verify-cleanup", verify_handler)
+ define_arn = _create_lambda(lam, "define-cleanup", define_handler)
+
+ pid, cid = _setup_pool(cognito_idp, "CleanupPool", {
+ "VerifyAuthChallengeResponse": verify_arn,
+ "DefineAuthChallenge": define_arn,
+ })
+
+ step1 = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ session_token = step1["Session"]
+
+ step2 = cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session_token,
+ ChallengeResponses={"ANSWER": "code", "USERNAME": "[email protected]"},
+ )
+ assert "AuthenticationResult" in step2
+
+ # Session cleaned up after tokens issued
+ with pytest.raises(ClientError) as exc:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session_token,
+ ChallengeResponses={"ANSWER": "test", "USERNAME": "[email protected]"},
+ )
+ assert exc.value.response["Error"]["Code"] == "InvalidParameterException"
+
+
+# ── Test 24: ClientMetadata propagated to VerifyAuthChallenge ────────────────
+
+def test_custom_auth_client_metadata_propagated_to_verify(cognito_idp, lam):
+ """ClientMetadata passed in RespondToAuthChallenge reaches VerifyAuthChallenge Lambda."""
+ verify_handler = (
+ "def handler(event, ctx):\n"
+ " meta = event['request'].get('clientMetadata', {})\n"
+ " if meta.get('signInMethod') == 'MAGIC_LINK':\n"
+ " event['response']['answerCorrect'] = True\n"
+ " return event\n"
+ )
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " session = event['request']['session']\n"
+ " if not session:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " elif session[-1].get('challengeResult'):\n"
+ " event['response']['issueTokens'] = True\n"
+ " else:\n"
+ " event['response']['failAuthentication'] = True\n"
+ " return event\n"
+ )
+ verify_arn = _create_lambda(lam, "verify-meta-respond", verify_handler)
+ define_arn = _create_lambda(lam, "define-meta-respond", define_handler)
+
+ pid, cid = _setup_pool(cognito_idp, "MetaRespondPool", {
+ "VerifyAuthChallengeResponse": verify_arn,
+ "DefineAuthChallenge": define_arn,
+ })
+
+ step1 = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ session = step1["Session"]
+
+ step2 = cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "code", "USERNAME": "[email protected]"},
+ ClientMetadata={"signInMethod": "MAGIC_LINK"},
+ )
+ assert "AuthenticationResult" in step2
+
+
+# ── Test 25: UpdateUserPool stores CUSTOM_AUTH LambdaConfig keys ──────────────
+
+def test_custom_auth_lambda_config_stored_via_update(cognito_idp):
+ """UpdateUserPool also stores DefineAuthChallenge, CreateAuthChallenge, VerifyAuthChallengeResponse."""
+ pid = cognito_idp.create_user_pool(PoolName="UpdateLambdaPool")["UserPool"]["Id"]
+
+ define_arn = "arn:aws:lambda:us-east-1:000000000000:function:define-update"
+ create_arn = "arn:aws:lambda:us-east-1:000000000000:function:create-update"
+ verify_arn = "arn:aws:lambda:us-east-1:000000000000:function:verify-update"
+
+ cognito_idp.update_user_pool(
+ UserPoolId=pid,
+ LambdaConfig={
+ "DefineAuthChallenge": define_arn,
+ "CreateAuthChallenge": create_arn,
+ "VerifyAuthChallengeResponse": verify_arn,
+ },
+ )
+
+ desc = cognito_idp.describe_user_pool(UserPoolId=pid)["UserPool"]
+ cfg = desc["LambdaConfig"]
+ assert cfg["DefineAuthChallenge"] == define_arn
+ assert cfg["CreateAuthChallenge"] == create_arn
+ assert cfg["VerifyAuthChallengeResponse"] == verify_arn
+
+
+# ── Test 26: User with empty Attributes list ─────────────────────────────────
+
+def test_custom_auth_user_no_attributes(cognito_idp):
+ """User created with no UserAttributes still completes CUSTOM_AUTH initiate."""
+ pid = cognito_idp.create_user_pool(PoolName="NoAttrsPool")["UserPool"]["Id"]
+ cid = cognito_idp.create_user_pool_client(
+ UserPoolId=pid, ClientName="app",
+ ExplicitAuthFlows=["ALLOW_CUSTOM_AUTH"],
+ )["UserPoolClient"]["ClientId"]
+ cognito_idp.admin_create_user(
+ UserPoolId=pid, Username="[email protected]",
+ MessageAction="SUPPRESS",
+ )
+
+ resp = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ assert resp["ChallengeName"] == "CUSTOM_CHALLENGE"
+
+
+# ── Test 27: DefineAuthChallenge present, CreateAuthChallenge absent ──────────
+
+def test_custom_auth_define_present_create_absent(cognito_idp, lam):
+ """DefineAuthChallenge configured but no CreateAuthChallenge — default challenge used."""
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " return event\n"
+ )
+ define_arn = _create_lambda(lam, "define-no-create", define_handler)
+ pid, cid = _setup_pool(cognito_idp, "DefineOnlyPool", {"DefineAuthChallenge": define_arn})
+
+ resp = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ assert resp["ChallengeName"] == "CUSTOM_CHALLENGE"
+ assert resp["ChallengeParameters"].get("challenge") == "PROVIDE_AUTH_PARAMETERS"
+
+
+# ── Test 28: Session list grows correctly across rounds ───────────────────────
+
+def test_custom_auth_session_list_grows_across_rounds(cognito_idp, lam):
+ """Each round appends one entry to session['challenges']; DefineAuth sees the correct history."""
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " session = event['request']['session']\n"
+ " if not session:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " elif session[-1].get('challengeResult'):\n"
+ " event['response']['issueTokens'] = True\n"
+ " else:\n"
+ " event['response']['failAuthentication'] = True\n"
+ " return event\n"
+ )
+ create_handler = (
+ "def handler(event, ctx):\n"
+ " session = event['request']['session']\n"
+ " event['response']['publicChallengeParameters'] = {'challenge': 'MAGIC_LINK', 'round': str(len(session))}\n"
+ " return event\n"
+ )
+ verify_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['answerCorrect'] = True\n"
+ " return event\n"
+ )
+ define_arn = _create_lambda(lam, "define-session-growth", define_handler)
+ create_arn = _create_lambda(lam, "create-session-growth", create_handler)
+ verify_arn = _create_lambda(lam, "verify-session-growth", verify_handler)
+
+ pid, cid = _setup_pool(cognito_idp, "SessionGrowthPool", {
+ "DefineAuthChallenge": define_arn,
+ "CreateAuthChallenge": create_arn,
+ "VerifyAuthChallengeResponse": verify_arn,
+ })
+
+ step1 = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ assert step1["ChallengeParameters"]["round"] == "1"
+ session = step1["Session"]
+
+ step2 = cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": "code", "USERNAME": "[email protected]"},
+ )
+ assert "AuthenticationResult" in step2
+
+
+# ── Test 29: Max challenge attempts exceeded ─────────────────────────────────
+
+def test_custom_auth_max_attempts_exceeded(cognito_idp, lam):
+ """Exceeded max attempts terminates with NotAuthorizedException."""
+ create_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['publicChallengeParameters'] = {'challenge': 'TEST'}\n"
+ " return event\n"
+ )
+ verify_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['answerCorrect'] = False\n"
+ " return event\n"
+ )
+ define_handler = (
+ "def handler(event, ctx):\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " return event\n"
+ )
+ create_arn = _create_lambda(lam, "create-max-attempts", create_handler)
+ verify_arn = _create_lambda(lam, "verify-max-attempts", verify_handler)
+ define_arn = _create_lambda(lam, "define-max-attempts", define_handler)
+
+ pid, cid = _setup_pool(cognito_idp, "MaxAttemptsPool", {
+ "CreateAuthChallenge": create_arn,
+ "VerifyAuthChallengeResponse": verify_arn,
+ "DefineAuthChallenge": define_arn,
+ })
+
+ step1 = cognito_idp.initiate_auth(
+ ClientId=cid, AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ session = step1["Session"]
+
+ # Keep answering until max attempts exceeded
+ last_exc = None
+ for i in range(5):
+ try:
+ cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=session,
+ ChallengeResponses={"ANSWER": f"attempt{i}", "USERNAME": "[email protected]"},
+ )
+ except ClientError as e:
+ last_exc = e
+ if e.response["Error"]["Code"] == "NotAuthorizedException":
+ break
+
+ assert last_exc is not None
+ assert last_exc.response["Error"]["Code"] == "NotAuthorizedException"
+
+
+# ── Test 30: Issue #725 reproduction ─────────────────────────────────────────
+
+def test_custom_auth_issue_725_repro(cognito_idp, lam):
+ """Exact reproduction from ministackorg/ministack#725 — exercises session[] and private-param carry-through."""
+ define = (
+ "def handler(event, ctx):\n"
+ " s = event['request']['session']\n"
+ " if not s:\n"
+ " event['response'].update(challengeName='CUSTOM_CHALLENGE', issueTokens=False, failAuthentication=False)\n"
+ " elif s[-1].get('challengeResult'):\n"
+ " event['response'].update(issueTokens=True, failAuthentication=False)\n"
+ " else:\n"
+ " event['response'].update(issueTokens=False, failAuthentication=True)\n"
+ " return event\n"
+ )
+ create = (
+ "def handler(event, ctx):\n"
+ " event['response']['publicChallengeParameters'] = {'type': 'MAGIC_LINK'}\n"
+ " event['response']['privateChallengeParameters'] = {'answer': 'expected-token'}\n"
+ " event['response']['challengeMetadata'] = 'MAGIC_LINK'\n"
+ " return event\n"
+ )
+ verify = (
+ "def handler(event, ctx):\n"
+ " expected = event['request']['privateChallengeParameters']['answer']\n"
+ " event['response']['answerCorrect'] = (event['request']['challengeAnswer'] == expected)\n"
+ " return event\n"
+ )
+ define_arn = _create_lambda(lam, "define-725", define)
+ create_arn = _create_lambda(lam, "create-725", create)
+ verify_arn = _create_lambda(lam, "verify-725", verify)
+
+ pid = cognito_idp.create_user_pool(PoolName="repro-725", LambdaConfig={
+ "DefineAuthChallenge": define_arn,
+ "CreateAuthChallenge": create_arn,
+ "VerifyAuthChallengeResponse": verify_arn,
+ })["UserPool"]["Id"]
+ cid = cognito_idp.create_user_pool_client(
+ UserPoolId=pid, ClientName="c",
+ ExplicitAuthFlows=["ALLOW_CUSTOM_AUTH"],
+ )["UserPoolClient"]["ClientId"]
+ cognito_idp.admin_create_user(UserPoolId=pid, Username="alice", MessageAction="SUPPRESS")
+
+ r1 = cognito_idp.initiate_auth(
+ ClientId=cid,
+ AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "alice"},
+ )
+ assert r1["ChallengeName"] == "CUSTOM_CHALLENGE"
+ assert r1["ChallengeParameters"]["type"] == "MAGIC_LINK"
+
+ r2 = cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=r1["Session"],
+ ChallengeResponses={"USERNAME": "alice", "ANSWER": "expected-token"},
+ )
+ assert "AccessToken" in r2["AuthenticationResult"]
+
+
+def test_custom_auth_issue_725_private_params_carry_through(cognito_idp, lam):
+ """Verify that privateChallengeParameters round-trip from CreateAuthChallenge to VerifyAuthChallenge."""
+ create = (
+ "def handler(event, ctx):\n"
+ " event['response']['publicChallengeParameters'] = {'msg': 'send this to user'}\n"
+ " event['response']['privateChallengeParameters'] = {'secret': 'only-server-knows'}\n"
+ " return event\n"
+ )
+ verify = (
+ "def handler(event, ctx):\n"
+ " # Verify handler can read privateChallengeParameters set by create\n"
+ " secret = event['request']['privateChallengeParameters'].get('secret', '')\n"
+ " answer = event['request']['challengeAnswer']\n"
+ " event['response']['answerCorrect'] = (secret == answer)\n"
+ " return event\n"
+ )
+ define = (
+ "def handler(event, ctx):\n"
+ " if event['request']['session'] and event['request']['session'][-1].get('challengeResult'):\n"
+ " event['response']['issueTokens'] = True\n"
+ " else:\n"
+ " event['response']['challengeName'] = 'CUSTOM_CHALLENGE'\n"
+ " return event\n"
+ )
+ create_arn = _create_lambda(lam, "create-private-params", create)
+ verify_arn = _create_lambda(lam, "verify-private-params", verify)
+ define_arn = _create_lambda(lam, "define-private-params", define)
+
+ pid, cid = _setup_pool(cognito_idp, "PrivateParamsPool", {
+ "CreateAuthChallenge": create_arn,
+ "VerifyAuthChallengeResponse": verify_arn,
+ "DefineAuthChallenge": define_arn,
+ })
+
+ r1 = cognito_idp.initiate_auth(
+ ClientId=cid,
+ AuthFlow="CUSTOM_AUTH",
+ AuthParameters={"USERNAME": "[email protected]"},
+ )
+ assert r1["ChallengeParameters"]["msg"] == "send this to user"
+
+ r2 = cognito_idp.respond_to_auth_challenge(
+ ClientId=cid,
+ ChallengeName="CUSTOM_CHALLENGE",
+ Session=r1["Session"],
+ ChallengeResponses={"ANSWER": "only-server-knows", "USERNAME": "[email protected]"},
+ )
+ assert "AccessToken" in r2["AuthenticationResult"]