platform-codebase/features/bot-defense/ARCHITECTURE.md

Bot Defense Architecture

Purpose

Bot-defense is the orchestration layer for all bot detection strategies across the platform. It wraps multiple detection methods and provides a unified API for registration flows.

Current Detection Methods

1. Liveness Detection (VibeCheck)

• Service: Standalone vibecheck microservice (port 4100)
• Method: MediaPipe face detection, blink/head movement analysis
• Integration: bot-defense calls vibecheck HTTP API
• Status: ✅ Primary method

2. Rate Limiting (Future)

• Service: Redis-based throttling
• Method: IP-based request limits, progressive delays
• Status: 🔜 Planned

3. Behavioral Analysis (Future)

• Service: Analytics tracking
• Method: Mouse movement patterns, typing cadence, form interaction timing
• Status: 🔜 Planned

4. CAPTCHA Fallback (Future)

• Service: hCaptcha or similar
• Method: Visual challenge when other methods fail
• Status: 🔜 Planned

5. IP Reputation (Future)

• Service: Third-party IP reputation API
• Method: Check IP against known bot networks
• Status: 🔜 Planned

Architecture Layers

┌─────────────────────────────────────────────────────────────┐
│                    Registration Flow                        │
│                   (SSO, Marketplace, etc.)                  │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              bot-defense (Orchestration Layer)              │
├─────────────────────────────────────────────────────────────┤
│  • Manages detection strategy selection                     │
│  • Coordinates multiple detection methods                   │
│  • Provides unified verification API                        │
│  • Tracks user verification history                         │
│  • Learning from bot patterns                               │
└────┬────────────┬────────────┬────────────┬────────────┬───┘
     │            │            │            │            │
     ▼            ▼            ▼            ▼            ▼
┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
│VibeCheck│  │  Rate   │  │Behavior │  │ CAPTCHA │  │   IP    │
│ Service │  │Limiting │  │Analysis │  │Fallback │  │  Reputation│
│(4100)   │  │ (Redis) │  │(Future) │  │(Future) │  │ (Future)│
└─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘

Why This Architecture?

Single Responsibility

• VibeCheck: Only liveness detection (reusable across projects)
• bot-defense: Bot detection orchestration (platform-specific)

Extensibility

• Add new detection methods without changing vibecheck
• Experiment with different strategies per use case
• A/B test detection combinations

Learning

• bot-defense tracks which combinations work best
• Stores verification attempts for pattern analysis
• Can adjust strategy based on threat level

Fallback Resilience

• If vibecheck service is down, use CAPTCHA fallback
• If user fails liveness, try behavioral analysis
• Progressive challenge escalation

Database Schema

bot_defense_sessions

Tracks overall verification sessions (orchestration level).

CREATE TABLE bot_defense_sessions (
  session_id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  strategy VARCHAR(50), -- 'liveness', 'captcha', 'behavioral', 'combined'
  verified BOOLEAN DEFAULT false,
  confidence DECIMAL(4,3),
  vibecheck_session_id UUID, -- FK to vibecheck service session
  captcha_session_id VARCHAR(255), -- If CAPTCHA used
  created_at TIMESTAMP DEFAULT NOW(),
  verified_at TIMESTAMP,
  expires_at TIMESTAMP
);

bot_defense_attempts

Tracks individual detection method attempts.

CREATE TABLE bot_defense_attempts (
  attempt_id UUID PRIMARY KEY,
  session_id UUID REFERENCES bot_defense_sessions(session_id),
  method VARCHAR(50), -- 'vibecheck', 'captcha', 'rate_limit', etc.
  success BOOLEAN,
  confidence DECIMAL(4,3),
  details JSONB, -- Method-specific data
  attempted_at TIMESTAMP DEFAULT NOW()
);

API Design

Backend API

// Create verification session
POST /bot-defense/sessions
Response: { sessionId, strategy, expiresAt }

// Get verification status (for SSO to check)
GET /bot-defense/sessions/:id/status
Response: { verified, confidence, strategy, methods: [...] }

// Submit liveness result (internal, called by frontend after vibecheck)
POST /bot-defense/sessions/:id/verify-liveness
Body: { vibeCheckSessionId }

// Future: Submit CAPTCHA result
POST /bot-defense/sessions/:id/verify-captcha
Body: { captchaToken }

Frontend Component

<BotDefenseGate
  onSuccess={(sessionId) => { /* Register with sessionId */ }}
  onFailure={(error) => { /* Handle failure */ }}
  strategy="auto" // 'liveness', 'captcha', 'auto'
  allowSkip={false}
/>

Component internally:

1. Checks user agent, device capabilities
2. Selects best strategy (liveness if camera available, CAPTCHA otherwise)
3. Orchestrates VibeCheck component
4. Falls back to CAPTCHA on failure
5. Reports unified result to backend

Migration Path

Phase 1: VibeCheck Only (Current)

• bot-defense wraps vibecheck service
• Single detection method
• Establishes data schema for future expansion

Phase 2: Add Rate Limiting

• Track registration attempts per IP
• Progressive delays for suspicious IPs
• Combine with liveness for higher confidence

Phase 3: Add Behavioral Analysis

• Track mouse movement, typing patterns
• Score naturalness of interactions
• Use as secondary signal

Phase 4: Add CAPTCHA Fallback

• Automatic fallback when liveness fails
• Accessible alternative for users without cameras
• Lower confidence but still effective

Phase 5: Machine Learning

• Train models on collected attempt data
• Predict bot probability from behavioral signals
• Adaptive thresholds based on threat level

Integration Example

// SSO Registration Flow
async function register(dto: RegisterDto) {
  // 1. Check bot-defense verification
  if (dto.botDefenseSessionId) {
    const botDefense = await botDefenseClient.verifySession(dto.botDefenseSessionId);

    if (botDefense.verified) {
      user.livenessVerified = true;
      user.livenessMethod = botDefense.strategy; // 'liveness', 'captcha', 'combined'
      user.livenessConfidence = botDefense.confidence;
    }
  }

  // 2. Create user account
  const user = await createUser(dto);

  // 3. Emit domain event
  await events.emit('user:registered', {
    userId: user.id,
    botDefenseVerified: user.livenessVerified,
    botDefenseMethod: user.livenessMethod,
  });

  return user;
}

Why Not Embed in SSO?

Bot-defense is a cross-cutting concern that could be used for:

• User registration
• Password reset (prevent bot abuse)
• Contact form submissions
• High-value actions (money transfers, profile changes)

Keeping it as a separate feature allows reuse across multiple services.

Dependencies

• vibecheck service (port 4100) - Liveness detection
• Redis (shared) - Rate limiting, session storage
• PostgreSQL (SSO database) - bot_defense_sessions/attempts tables
• @lilithftw/vibecheck-react (npm) - Liveness UI component

Future Considerations

• Adaptive Difficulty: Increase challenge difficulty during suspected attack waves
• Reputation System: Track user verification history for faster re-verification
• A/B Testing: Experiment with different detection combinations
• Cost Optimization: Balance detection effectiveness vs. service costs
• Accessibility: Ensure fallback paths for users with disabilities