Buyer Auth

Flow

1. Buyer enters phone number (or email) on their portal’s login page
2. POST /api/auth/otp/send normalizes the identifier, validates with Turnstile, applies rate limits, and triggers OTP delivery
3. Buyer enters the 6-digit code → POST /api/auth/otp/verify
4. If the buyer doesn’t exist yet: a new buyers record is created (self-service registration)
5. Lucia session cookie (convertella_session) is set
6. Buyer is redirected to their dashboard or saved redirect target

Delivery Channels

Channel	Implementation	Notes
Email	src/lib/otp/cf-email.ts via Cloudflare Email Service	Primary delivery method
WhatsApp	src/lib/otp/cf-email.ts → WhatsApp fallback	Optional, per-agent configuration

Key Differences from CRM OTP

Aspect	Buyer OTP	CRM OTP
Service	src/lib/otp/service.ts (uses stored procs + TenantContext)	src/lib/auth/admin-otp/service.ts (direct Drizzle, no tenant)
Registration	Self-service (OTP verify creates buyer)	Invite-only
Delivery channels	Email + WhatsApp	Email only
Rate limiting	Stored-proc (IP + identifier, persisted)	IP rate limit (in-memory)

Code Organization

File	Purpose
src/lib/otp/service.ts	sendOtp() and verifyOtp() — wraps stored procedures
src/lib/otp/deliver.ts	deliverOtp() — channel dispatch
src/lib/otp/cf-email.ts	sendOtpEmail() — Cloudflare Email integration
src/lib/otp/hash.ts	generateOtpDigits(), hashOtp() (HMAC-SHA256)
src/lib/otp/normalize.ts	normalizeIdentifier() — phone/email normalization
src/lib/otp/ip-rate-limit.ts	IP-based rate limiter (in-memory rolling window)
src/lib/otp/constants.ts	OTP_EXPIRY_MS, OTP_MAX_ATTEMPTS
src/lib/otp/errors.ts	OtpError class and error codes
src/lib/otp/client-ip.ts	IP extraction from request headers