Scaffold & Document: AWS Cognito Account Creation Flow Using Temporary Password (Mocked — No Implementation)

[SamNie2027]

Please branch off of the authentication branch.

Context

When a user submits an application, we need to automatically create a Cognito account for them and email them a temporary password. On first login, Cognito will force them to set a new permanent password before gaining access.

We are not implementing the real logic yet. The goal of this ticket is to scaffold the functions, mock their behavior, and document exactly what each function is supposed to do so that implementation can begin cleanly in a follow-up ticket.

Chosen Approach: Temporary Password (Cognito Native Flow)

1. User submits an application with Pandadoc, calling the Create flow
2. Our Create flow calls Cognito's AdminCreateUser API to create an account with a temporary password
3. Cognito emails the temporary password to the user automatically
4. User logs in with the temp password — Cognito responds with a NEW_PASSWORD_REQUIRED challenge
5. Frontend prompts the user to set a new password and calls RespondToAuthChallenge
6. User is now fully authenticated with their own password

Acceptance Criteria

• createCognitoUser(email, temporaryPassword) is scaffolded with a mock implementation and JSDoc comment that describes:

  • What it does (calls AdminCreateUser on the Cognito User Pool after creation endpoint is called)
  • Its parameters and expected types
  • What it returns on success and on failure
  • Any side effects (e.g., triggers a Cognito-sent email to the user)

• handleNewPasswordChallenge(username, tempPassword, newPassword) is scaffolded with a mock implementation and JSDoc comment that describes:

  • What it does (calls RespondToAuthChallenge with the NEW_PASSWORD_REQUIRED challenge type)
  • Its parameters and expected types
  • What it returns (e.g., Cognito auth tokens on success)
  • When it would be called (triggered by frontend after user submits their new password)

• resendTemporaryPassword(email) is scaffolded with a mock implementation and JSDoc comment that describes:

  • What it does (calls AdminCreateUser with MessageAction: RESEND to re-trigger the temp password email)
  • When it would be used (e.g., user never received the email or the temp password expired)
  • Its parameters, return value, and failure cases

• All mocks return realistic-looking fake data that mirrors what the real Cognito API would return (e.g., a mock auth token object, a mock user object). No real AWS calls should be made.

• A README or inline doc block exists at the top of the file/module OR Diagram using something like Miro

  • The overall flow in plain English (can reference the numbered steps in the Context section above)
  • Which AWS SDK package will be used in real implementation (@aws-sdk/client-cognito-identity-provider)
  • What environment variables will be needed (e.g., COGNITO_USER_POOL_ID, COGNITO_CLIENT_ID, AWS_REGION) — values can be left as TODO for now

• No real AWS credentials or API calls are used anywhere in this ticket. All functions must be purely mocked.