Authentication & Security Overview

Architecture Philosophy

Wafra implements a hybrid authentication system that combines traditional password-based login with cutting-edge WebAuthn passkey technology. This approach provides bank-grade security while maintaining an intuitive user experience.

Current Implementation

Authentication Flow

Primary Authentication:

  • Phone + Password: Traditional login for familiar UX
  • Passkey Creation: WebAuthn hardware-backed authentication
  • Multi-Device Support: Users can register multiple passkeys with approval workflow

Session Management:

  • JWT Tokens: 5-day expiration with automatic refresh
  • Session Context: Rich user data and passkey information
  • Server Validation: Comprehensive session validation on each request

Current Architecture

tRPC Authentication Integration

API Protection:

  • protectedProcedure: Requires valid JWT and session
  • publicProcedure: Open endpoints (signup, signin)
  • Session Context: Available in all protected procedures via ctx.session

Current Session Structure:

interface SessionContext {
  user: {
    id: string;
    phone: string;
    name?: string;
    walletAddress?: string;
    phoneVerified: Date | null;
    onboardingCompleted: boolean;
    country: string;
    currency?: string;
  };
  passkeyId?: string;
}

Multi-Device Passkey Management

Device Registration Flow

First Device (During Onboarding):

  • Automatically approved
  • Becomes primary authentication method
  • Enables wallet operations

Additional Devices:

  • Requires approval from existing approved device
  • Approval/rejection workflow via tRPC endpoints
  • Real-time notifications via Socket.IO

Device Management Features

Current Implementation:

  • List all registered devices with metadata
  • View pending approval requests
  • Approve/reject new device requests
  • Remove compromised devices (with security checks)
  • Session age validation for sensitive operations

Security Controls:

  • Cannot remove current session’s passkey
  • Cannot remove last approved device
  • Recent session requirement for device removal (≤5 minutes)

Development Authentication

Development JWT System

Current Implementation:

  • Environment Gated: Only available when NODE_ENV=development
  • First User Authentication: Automatically authenticates as first user in database
  • Script Generation: node apps/server/scripts/generate-dev-jwt.js
⚠️

Development JWT completely bypasses all security measures and should NEVER be used in production.

Current API Endpoints (tRPC)

Authentication Router

Available Procedures:

  • auth.signIn: Phone + password authentication
  • auth.signUp: User registration
  • auth.verifyCredentials: Credential validation
  • auth.refresh: Token refresh

Passkey Router

Device Management:

  • passkey.generateRegistrationChallenge: Start passkey registration
  • passkey.verifyRegistration: Complete passkey registration
  • passkey.generateAuthenticationChallenge: Start passkey authentication
  • passkey.verifyAuthentication: Complete passkey authentication
  • passkey.listPasskeys: Get user’s devices
  • passkey.getPendingApprovals: Get pending approval requests
  • passkey.approveRequest: Approve/reject device requests
  • passkey.removePasskey: Remove device from account

Security Implementation

1. WebAuthn Security

Current Features:

  • Hardware-Backed Keys: Stored in TPM/Secure Enclave
  • Biometric Protection: Face ID, Touch ID, fingerprint required
  • Domain-Bound: Phishing-resistant authentication
  • Public Key Cryptography: No shared secrets

2. Session Security

Current Protections:

  • JWT Verification: Server-side signature validation
  • Expiration Handling: 5-day token lifetime
  • Session Context: User and passkey information
  • Request Validation: Session validation on every protected endpoint

3. Transaction Authorization

Hybrid Signing Model:

  • Client Authorization: User signs with passkey
  • Server Verification: Server validates and co-signs
  • Blockchain Execution: Multi-signature Safe execution

Real-Time Features

Socket.IO Integration

Current Events:

  • Device approval requests
  • Device approval/rejection notifications
  • Balance updates
  • Transaction status updates

Implementation:

  • User-specific rooms for targeted notifications
  • Event-driven UI updates
  • Automatic query invalidation via React Query

Migration Status

Completed

  • ✅ Full tRPC migration (REST endpoints removed)
  • ✅ Multi-device passkey management
  • ✅ Session context and validation
  • ✅ Real-time notifications
  • ✅ Development authentication tools

Current Focus

  • Ongoing payment provider integration
  • Enhanced security monitoring
  • Performance optimizations
  • Error handling improvements

This authentication system provides enterprise-grade security while maintaining the simplicity users expect from modern financial applications.