Cognito Auth: Borrower UI & Borrower-Auth-UI

Auth Overview

Two auth flows, one server-side session.

New Borrower — Inline Signup

Client-side Cognito SDK

Cognito User Pool

Establish session

Config→borrower-interactions-ui/src/lib/amplify-config.ts

Pool config→lc/cortex/cognito/configuration.py

Session mgmt→lc/app/borrower/auth/utils.py:175

Returning Borrower — Auth Portal

Email & password

Server-side Cognito call

MFA challenge (if required)

Signin view→lc/app/borrower/auth/views.py:98

ℹ️

Shared Flask Session — both paths converge on one session carrying borrower identity, company context, and loan file.

ℹ️

Each company has its own Cognito pool — multi-tenant isolation at the auth layer

Inline Signup Bridges Cognito to Session

Inline signup: collect, register, verify, sign in.

Client-side (React)

Idle

Register

per-company poolno MFA

Verify email

Sign in

ℹ️

Pre-auth screens collect name & email + property address — PII stays in React state only

State machine→src/pre-auth/signup-screen.tsx:19-68

Pool lookup→src/lib/company-theme.api.ts:19-25

Auth API→src/lib/auth.api.ts

Personal info→src/pre-auth/personal-info-screen.tsx

SESSION BOUNDARY

Server-side (Flask)

Establish session

Create loan file

Session API→src/lib/auth.api.ts

Create file→src/lib/auth.api.ts:57

Session Establishment Handles Three Cases

How the server resolves a Cognito token into a borrower session.

Validate Cognito Token

Server receives token and resolves borrower identity

Existing user

Found by identity — link and set session

Invitation flow

Pre-created record found by email — link identity

Self-signup

No record exists — create borrower, set session

Source Files

Lookup→app/borrower/auth/views.py:1070-1072

Invite handler→app/borrower/auth/views.py:334-431

Creation→app/borrower/auth/views.py:1084-1097

⛔

Error recovery: session errors retry automatically, general errors restart the flow

ℹ️

Borrower UI has no MFA — signup flow only. MFA lives entirely in the legacy auth portal.

Legacy Auth Handles Sign-in, MFA, and Recovery

Server-side auth with MFA, recovery, and invitation flows.

Sign in

Email & password → server validates with Cognito

MFA challenge

Verify SMS code or authenticator token

MFA setup required

Choose SMS or TOTP, enroll device

Email not confirmed

Re-verify email before proceeding

Direct success

No challenge needed — session set immediately

Source Files

Sign in page→borrower-auth-ui/src/routes/signin.tsx

API call→borrower-auth-ui/src/api/signin.ts

Backend→app/borrower/auth/views.py:98

Challenge UI→borrower-auth-ui/src/routes/code-challenge.tsx

MFA backend→app/borrower/auth/views.py:593-831

Setup UI→borrower-auth-ui/src/routes/mfa-options.tsx

ℹ️

Also handles invitation signup, forgot password, and password reset flows

Auth Consolidation Is Underway

Migration status: signup done, the rest is pending.

Migrated

inline signup session bridge file creation

Signup→borrower-interactions-ui/src/pre-auth/signup-screen.tsx

Session bridge→borrower-interactions-ui/src/lib/auth.api.ts

Bridge backend→marketplace/lc/app/borrower/auth/views.py:1037

Still in legacy portal

sign-in MFA setup password recovery invitation signup

Legacy routes→borrower-auth-ui/src/routes/

Auth views→marketplace/lc/app/borrower/auth/views.py

Auth utils→marketplace/lc/app/borrower/auth/utils.py

⛔

The legacy portal has zero test coverage — every ported route needs new tests written during migration

Navigation

Next: App Architecture

← Back to Series Hub

Auth Overview

Inline Signup Bridges Cognito to Session

Session Establishment Handles Three Cases

Legacy Auth Handles Sign-in, MFA, and Recovery

Auth Consolidation Is Underway

Keyboard Shortcuts