Auth Start (Passwordless Sign-In)

A user initiates sign-in by submitting their email address; the server generates a magic link and delivers it via email so no password is ever required.

Flow

1. User submits email — The mobile app or web client sends a POST request to the auth-start Lambda with { "email": "user@example.com" }.

2. Email validation — The Lambda normalizes the email (trim + lowercase) and validates format with a regex. Invalid or missing emails return HTTP 400.

3. Cognito user provisioning — If the user does not exist in the Cognito User Pool, admin_create_user is called with MessageAction=SUPPRESS and a random strong password is set immediately so the account is CONFIRMED. If the user already exists but is unconfirmed, the same password-set and attribute-update steps run.

4. CUSTOM_AUTH challenge initiation — admin_initiate_auth is called with AuthFlow=CUSTOM_AUTH. A cryptographically random token is embedded in ClientMetadata. Cognito returns a Session string and, via a Cognito Lambda trigger, echoes back the magic_link_token in ChallengeParameters.

5. Magic link construction — The token, email, and session are URL-encoded into MAGIC_LINK_BASE_URL to produce a deep-link URL.

6. Email delivery — SES sends an HTML email containing the magic-link button. The email subject is "Sign in to Encache".

7. Response — The API returns { "session": "<cognito-session-string>" } to the client, which stores it locally pending the user clicking the link.

Entry Point

• Lambda: main/server/api/auth/start/app.py → lambda_handler
• HTTP method: POST /auth/start (API Gateway)

Dependencies

• AWS Cognito User Pools (COGNITO_USER_POOL_ID, COGNITO_APP_CLIENT_ID)
• AWS SES (MAGIC_LINK_SENDER)
• Environment: MAGIC_LINK_BASE_URL

Error Cases