Authentication, Security & Safety Gate Architecture

1. Passkeyless WhatsApp Webhook Auth Engine

SML Web eliminates password vulnerabilities by using a WhatsApp-Native Inbound Webhook Authentication Engine:

sequenceDiagram
    autonumber
    actor Customer
    participant Frontend as React SPA Client
    participant Backend as SML Hono Backend
    participant DB as PostgreSQL Database
    participant Gateway as Wadeno / GoWA Gateway
    participant WA as WhatsApp Client

    Customer->>Frontend: Input WhatsApp Phone Number (e.g. 08123456789)
    Frontend->>Backend: POST /api/auth/login { whatsappNumber }
    Backend->>DB: Check LoginBan table (Rate limit & ban level check)
    alt Is Banned
        Backend-->>Frontend: HTTP 429 / Ban active error
    else Allowed
        Backend->>DB: Create LoginToken record (PENDING, 90s expiry)
        Backend-->>Frontend: { token, magicLink, expiresIn: 90 }
    end

    Frontend->>Customer: Display "Verify via WhatsApp" magic link button
    Customer->>WA: Click magic link (wa.me/628...?text=VERIFY_tok_123)
    Customer->>WA: Send pre-filled message to SML Official WhatsApp Number

    WA->>Gateway: Inbound verification message received
    Gateway->>Backend: POST /api/auth/gowa-webhook { from, message }
    Backend->>DB: Validate token, match whatsappNumber & mark VERIFIED
    Backend->>DB: Upsert User profile (default role: CUSTOMER)

    loop Polling status (every 2 seconds)
        Frontend->>Backend: GET /api/auth/poll-status?token=tok_123
        Backend-->>Frontend: { status: "VERIFIED", token: "<JWT>", user: {...} }
    end

    Frontend->>Customer: Authenticated! Save JWT in localStorage

---

2. Outbound WhatsApp Safety Gate Architecture

To protect operational WhatsApp numbers from automated spam detection and carrier bans, the Wadeno Gateway enforces an Outbound Safety Gate:

1. Consent Rule Enforcement: Prevents outbound message dispatch to numbers without recorded inbound chat interaction unless explicitly registered via /consent endpoint.
2. Warm-up Quota Scaling: Restricts daily message quotas for newly paired WhatsApp channels, scaling throughput limits dynamically based on channel age.
3. Deliberate Jitter Spacing: Injects automated millisecond delays ($2000 ext{ms} \pm 500 ext{ms}$ random jitter) between message transmissions to eliminate robotic dispatch signatures.
4. Duplicate Content Filter: Automatically flags and blocks mass broadcasts containing identical text strings.

---

3. Anti-Brute-Force & Rate Limiting System

The authentication service maintains a sliding-window rate limiter and ban enforcement engine in login_bans:

model LoginBan {
  id             String    @id @default(uuid())
  whatsappNumber String    @unique
  attempts       Int       @default(0)
  banLevel       Int       @default(0) // 0: None, 1: 1h, 2: 24h, 3: Permanent
  banUntil       DateTime?
  lastAttemptAt  DateTime  @default(now())
}

Escalation Level	Threshold Condition	System Enforcement	Lock Duration
Level 0 (Normal)	$< 3$ unverified login attempts	Standard login token issuance	None
Level 1 Ban	$3$ consecutive unverified attempts	Restricts token generation for phone number & IP	1 Hour (3600s)
Level 2 Ban	Failed attempt during Level 1 window	Escalated access restriction	24 Hours (86400s)
Level 3 Ban	Persistent automated abuse	Account flagged for manual review	Permanent

---

4. Role-Based Access Control (RBAC) Matrix

Users are assigned one of four strict system roles (Role enum). Fine-grained backoffice navigation access for staff is controlled via the allowedMenus JSON column in users.

System Feature / Route	CUSTOMER	STAFF	ADMIN	OWNER
Browse Menu & Place Orders	✅	✅	✅	✅
View Personal Order History	✅	✅	✅	✅
Access Kitchen KDS & POS	❌	✅	✅	✅
Verify Manual Payment Receipts	❌	Allowed if in allowedMenus	✅	✅
Manage Menu Catalog & Pricing	❌	❌	✅	✅
Manage Operational Settings	❌	❌	✅	✅
View Financial Ledger & Profits	❌	❌	❌	✅
Manage System Users & Roles	❌	❌	❌	✅