Feature request: Add Cognito trigger schemas

[jkahn117]

Use case

To continue implementation of parser, add schemas for Cognito Lambda triggers. Lambda triggers customize the flow of user pool sign-up, authentication, etc. Details are in docs.

Solution/User Experience

Cognito schemas would be similar to existing schemas in the parser middleware. Many of the schemas would be similar / same.

For example, a basic event schema for the pre-signup trigger:

z.object({
  version: z.string(),
  region: z.string(),
  userPoolId: z.string(),
  userName: z.string(),
  callerContext: z.object({
    awsSdkVersion: z.string(),
    clientId: z.string()
  }),
  triggerSource: z.string(),
  request: z.object({
    userAttributes: z.record(z.string(), z.string()),
    validationData: z.record(z.string(), z.string()).nullable().optional(),
    userNotFound: z.boolean().optional()
  }),
  response: z.object({
    autoConfirmUser: z.boolean().optional(),
    autoVerifyEmail: z.boolean().optional(),
    autoVerifyPhone: z.boolean().optional()
  }).optional()
});

Alternative solutions

Acknowledgment

• This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out the #typescript channel on our Powertools for AWS Lambda Discord: Invite link

[dreamorosi]

Hi @jkahn117 - thank you for opening the issue.

I agree it makes sense to add these schemas to the Parser - we've added the help-wanted and good-first-issue labels to give an opportunity to contribute for community members.

Note

If anyone is interested in contributing, please leave a comment below so that we can assign the issue to you. If you have any doubts on the implementation or issue, don't hesitate to ask.

If not, someone from the team will pick up the issue and implement it during the next two iterations.

[VatsalGoel3]

@dreamorosi Would like to work on this

[dreamorosi]

Hi @VatsalGoel3, I see you've opened a PR but I realize that the issue was missing a bit of information and we could have been clearer in the requirements. Let me do that now.

As part of this issue we should add a number of schemas, below the full list:

1. Pre sign-up

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-sign-up.html

Sample event:

{
    "request": {
        "userAttributes": {
            "string": "string",
            . . .
        },
        "validationData": {
            "string": "string",
            . . .
         },
        "clientMetadata": {
            "string": "string",
            . . .
         }
    },
    "response": {
        "autoConfirmUser": "boolean",
        "autoVerifyPhone": "boolean",
        "autoVerifyEmail": "boolean"
    }
}

2. Post confirmation

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-post-confirmation.html

Sample event:

{
    "request": {
            "userAttributes": {
                "string": "string",
                . . .
            },
            "clientMetadata": {
            	"string": "string",
            	. . .
            }
        },
    "response": {}
}

3. Pre authentication

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-authentication.html

Sample event:

{
    "request": {
        "userAttributes": {
            "string": "string",
            . . .
        },
        "validationData": {
            "string": "string",
            . . .
        },
        "userNotFound": boolean
    },
    "response": {}
}

4. Post authentication

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-post-authentication.html

Sample event:

{
    "request": {
        "userAttributes": {
             "string": "string",
             . . .
         },
         "newDeviceUsed": boolean,
         "clientMetadata": {
             "string": "string",
             . . .
            }
        },
    "response": {}
}

5. Pre token generation

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html

Sample event:

{
    "request": {
        "userAttributes": {"string": "string"},
        "groupConfiguration": {
                "groupsToOverride": [
                    "string",
                    "string"
                ],
                "iamRolesToOverride": [
                    "string",
                    "string"
                ],
                "preferredRole": "string"
        },
        "clientMetadata": {"string": "string"}
    },
    "response": {
        "claimsOverrideDetails": {
            "claimsToAddOrOverride": {"string": "string"},
            "claimsToSuppress": [
                "string",
                "string"
            ],
            "groupOverrideDetails": {
                "groupsToOverride": [
                    "string",
                    "string"
                ],
                "iamRolesToOverride": [
                    "string",
                    "string"
                ],
                "preferredRole": "string"
            }
        }
    }
}

Note that this event has two versions, we'll need to add a schema for both.

6. Migrate user

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-migrate-user.html

Sample event:

{
    "userName": "string",
    "request": {
        "password": "string",
        "validationData": {
            "string": "string",
            . . .
        },
        "clientMetadata": {
            "string": "string",
      	. . .
        }
    },
    "response": {
        "userAttributes": {
            "string": "string",
            . . .
        },
        "finalUserStatus": "string",
        "messageAction": "string",
        "desiredDeliveryMediums": [ "string", . . .],
        "forceAliasCreation": boolean,
        "enableSMSMFA": boolean
    }
}

7. Custom message

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-custom-message.html

Sample event

{
    "request": {
        "userAttributes": {
            "string": "string",
            . . .
        }
        "codeParameter": "####",
        "usernameParameter": "string",
        "clientMetadata": {
            "string": "string",
            . . .
        }
    },
    "response": {
        "smsMessage": "string",
        "emailMessage": "string",
        "emailSubject": "string"
    }
}

8. Custom email sender

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-custom-email-sender.html

Sample event

{
    "request": {
        "type": "customEmailSenderRequestV1",
        "code": "string",
        "clientMetadata": {
            "string": "string",
             . . .
            },
        "userAttributes": {
            "string": "string",
            . . .
         }
}

9. Custom SMS sender

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-custom-sms-sender.html

Sample event

{
    "request": {
        "type": "customSMSSenderRequestV1",
        "code": "string",
        "clientMetadata": {
            "string": "string",
             . . .
            },
        "userAttributes": {
            "string": "string",
            . . .
         }
}

10. Define auth challenge

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-define-auth-challenge.html#cognito-user-pools-lambda-trigger-syntax-define-auth-challenge

Sample event

{
    "request": {
        "userAttributes": {
            "string": "string",
                . . .
        },
        "session": [
            ChallengeResult,
            . . .
        ],
        "clientMetadata": {
            "string": "string",
            . . .
        },
        "userNotFound": boolean
    },
    "response": {
        "challengeName": "string",
        "issueTokens": boolean,
        "failAuthentication": boolean
    }
}

11. Create auth challenge

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-create-auth-challenge.html#cognito-user-pools-lambda-trigger-syntax-create-auth-challenge

Sample event

{
    "request": {
        "userAttributes": {
            "string": "string",
            . . .
        },
        "challengeName": "string",
        "session": [
            ChallengeResult,
            . . .
        ],
        "clientMetadata": {
            "string": "string",
            . . .
        },
        "userNotFound": boolean
    },
    "response": {
        "publicChallengeParameters": {
            "string": "string",
            . . .
        },
        "privateChallengeParameters": {
            "string": "string",
            . . .
        },
        "challengeMetadata": "string"
    }
}

12. Verify auth challenge

Docs link: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-verify-auth-challenge-response.html#cognito-user-pools-lambda-trigger-syntax-verify-auth-challenge

Sample event

{
    "request": {
        "userAttributes": {
            "string": "string",
            . . .
        },
        "privateChallengeParameters": {
            "string": "string",
            . . .
        },
        "challengeAnswer": "string",
        "clientMetadata": {
            "string": "string",
            . . .
        },
        "userNotFound": boolean
    },
    "response": {
        "answerCorrect": boolean
    }
}

---

In addition to adding the schemas, each schema should have:

• corresponding unit tests following conventions set by existing ones (example)
• dedicated exports following the existing patterns (example)
• documentation like existing ones have (example)

[VatsalGoel3]

@dreamorosi, I had a question regarding the PR, do I need to define a new ChallengeResultSchema namely for Schemas 10,11 & 12 mentioned in your previous comment or please let me know if there is any pre existing code for it, I might have missed.

[dreamorosi]

Hi, none of the schemas listed above (1 to 12) exist today, so the PR (or PRs) should include all of them.

[github-actions]

⚠️ COMMENT VISIBILITY WARNING ⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.