Rate Limiting & Spam Prevention

Distributed Rate Limiting Architecture:

┌─────────────────────────────────────────────────────────────────┐
│                        User Device                               │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ Local Rate Limiter                                       │    │
│  │ - First line of defense                                  │    │
│  │ - Prevents unnecessary network requests                  │    │
│  │ - Maintains local usage counters                         │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Relay Network                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Relay Node  │  │  Relay Node  │  │  Relay Node  │          │
│  │  - Per-user  │  │  - Per-user  │  │  - Per-user  │          │
│  │    tracking  │  │    tracking  │  │    tracking  │          │
│  │  - Gossip    │  │  - Gossip    │  │  - Gossip    │          │
│  │    protocol  │  │    protocol  │  │    protocol  │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│              ↕              ↕              ↕                     │
│         Rate limit state synchronization via gossip              │
└─────────────────────────────────────────────────────────────────┘

Token Bucket Algorithm:

Parameters:
  bucket_capacity = base_limit + burst_allowance
  refill_rate = base_limit / window_seconds
  tokens = bucket_capacity (initial)

On message send:
  if tokens ≥ 1:
    tokens = tokens - 1
    allow_message()
  else:
    reject_message(RATE_LIMITED)

Every second:
  tokens = min(tokens + refill_rate, bucket_capacity)

Example (1:1 messaging):
  bucket_capacity = 60 + 20 = 80 tokens
  refill_rate = 60 / 60 = 1 token/second

  User can send 80 messages instantly (burst)
  Then must wait for token refill
  Sustained rate: 1 message/second maximum

Reconnection Backoff Strategy:

On disconnect:
  attempt = 0

Reconnection loop:
  while not connected:
    delay = calculate_delay(attempt)
    wait(delay)

    result = attempt_connection()

    if result == SUCCESS:
      break
    else if result == RATE_LIMITED:
      wait(retry_after_header)
    else:
      attempt = attempt + 1

calculate_delay(attempt):
  base = 1 second
  max_delay = 300 seconds  // 5 minutes

  // Exponential backoff with jitter
  delay = min(base * (2 ^ attempt), max_delay)
  jitter = random(0, delay * 0.2)

  return delay + jitter

Attempt Schedule:
  1: 1-1.2 seconds
  2: 2-2.4 seconds
  3: 4-4.8 seconds
  4: 8-9.6 seconds
  5: 16-19.2 seconds
  6: 32-38.4 seconds
  7: 64-76.8 seconds
  8: 128-153.6 seconds
  9+: 300-360 seconds

Prekey Management:

Server-side storage:
  min_prekeys = 20
  max_prekeys = 1000
  warning_threshold = 50

On prekey request (by peer):
  prekey = pop_one_time_prekey(user_id)
  remaining = count_prekeys(user_id)

  if remaining ≤ warning_threshold:
    notify_client(PREKEY_LOW, remaining)

  return prekey

Client replenishment:
  on PREKEY_LOW notification:
    current = get_prekey_count()
    to_generate = max_prekeys - current

    // Generate in batches to avoid blocking
    for batch in chunks(to_generate, 100):
      keys = generate_prekeys(batch)
      upload_prekeys(keys)
      wait(1 second)  // Rate limit compliance

Raid Detection Algorithm:

Parameters:
  join_rate_threshold = 10 members/minute
  message_rate_threshold = 5x normal
  new_member_message_threshold = 3 messages/minute

Monitoring:
  track join_rate over 5-minute window
  track message_rate over 1-minute window
  track new_member_activity over 10-minute window

On threshold exceeded:
  activate_raid_mode():
    - Slow mode: 1 message per 30 seconds
    - New member mute: 10-minute wait before posting
    - Join rate limit: 2 members/minute
    - Notify admins

  duration = 30 minutes
  auto_deactivate after duration if metrics normalize

Raid Mode Restrictions:
  ┌────────────────────────────────────────────────┐
  │ Normal Mode          │ Raid Mode               │
  ├────────────────────────────────────────────────┤
  │ 60 msg/min           │ 2 msg/min per user      │
  │ Instant join         │ 2 joins/min max         │
  │ Immediate posting    │ 10-min new member mute  │
  │ Unlimited reactions  │ 5 reactions/min         │
  └────────────────────────────────────────────────┘

Spam Behavior Patterns:

Pattern: Mass Messaging
  Indicators:
    - Messages to more than 20 unique users in 5 minutes
    - Less than 1 second between messages
    - No replies received
  Action: Temporary rate reduction (0.25x)

Pattern: Group Hopping
  Indicators:
    - Joins more than 5 groups in 1 hour
    - Sends messages immediately after joining
    - Leaves within 10 minutes
  Action: Group join cooldown (24 hours)

Pattern: Contact Harvesting
  Indicators:
    - More than 100 key bundle fetches in 1 hour
    - Low message-to-fetch ratio (less than 0.1)
    - Sequential address queries
  Action: Key bundle rate limit (10/hour)

Pattern: Bot Behavior
  Indicators:
    - Consistent message timing (low variance)
    - No typing indicators
    - 24/7 activity pattern
    - No read receipts sent
  Action: Flag for review, CAPTCHA challenge

Spam Score Algorithm:

score = 0

// Rate-based factors
if messages_per_minute > 30:
  score += (messages_per_minute - 30) * 2

if unique_recipients_per_hour > 50:
  score += (unique_recipients_per_hour - 50) * 1.5

// Behavioral factors
if avg_time_between_messages < 1 second:
  score += 20

if reply_rate < 0.05:  // less than 5% get replies
  score += 15

if session_creation_rate > 20:
  score += 10

// Account factors
if account_age < 7 days:
  score *= 1.5

if has_violations_history:
  score *= 2.0

// Threshold evaluation
if score ≥ 100:
  action = TEMPORARY_BAN
else if score ≥ 50:
  action = RATE_LIMIT_REDUCTION
else if score ≥ 25:
  action = WARNING
else:
  action = NONE

PoW Protocol Flow:

1. Client exceeds rate limit
2. Server responds:
   {
     challenge: random_256_bit_nonce,
     difficulty: target_leading_zeros,
     algorithm: "sha256",
     expires: timestamp + 60 seconds
   }

3. Client computes:
   nonce = 0
   while true:
     hash = SHA256(challenge || message_hash || nonce)
     if leading_zeros(hash) ≥ difficulty:
       break
     nonce = nonce + 1

4. Client sends message with proof:
   {
     message: encrypted_payload,
     pow_proof: {
       challenge: original_challenge,
       nonce: computed_nonce,
       hash: resulting_hash
     }
   }

5. Server verifies:
   - Challenge is valid and not expired
   - Hash meets difficulty requirement
   - Challenge not previously used (prevent replay)

PoW Decision Matrix:

                        │ Good Reputation │ Neutral │ Poor Reputation
────────────────────────┼─────────────────┼─────────┼─────────────────
Under rate limit        │ Never           │ Never   │ Optional
At rate limit           │ Never           │ Optional│ Required (easy)
Exceeded rate limit     │ Optional        │ Required│ Required (medium)
Spam score elevated     │ Required (easy) │ Required│ Required (hard)
Previous ban            │ Required        │ Required│ Required (very hard)

PoW Bypass Conditions:
  - Emergency messages (predefined contacts)
  - Account verification completed
  - Premium subscription active
  - Message to existing conversation (recent activity)

Reputation Calculation:

base_score = 50  // Starting reputation

// Positive factors
age_bonus = min(account_age_days / 365 * 20, 20)
contact_bonus = min(verified_contacts * 0.25, 25)
activity_bonus = calculate_activity_score()  // 0-10
verification_bonus = (phone_verified ? 5 : 0) + (email_verified ? 5 : 0)

// Negative factors
violation_penalty = violations_count * 10
spam_penalty = spam_reports_received * 5
rate_limit_penalty = rate_limit_hits_30d * 0.5

// Final calculation
reputation = base_score
           + age_bonus
           + contact_bonus
           + activity_bonus
           + verification_bonus
           - violation_penalty
           - spam_penalty
           - rate_limit_penalty

reputation = clamp(reputation, 0, 100)

Reputation Tiers:
  0-20:   Restricted (0.5x limits)
  21-40:  Limited (0.75x limits)
  41-60:  Standard (1.0x limits)
  61-80:  Trusted (1.25x limits)
  81-100: Highly Trusted (1.5x limits)

Multi-Device Reputation Sync:

Primary device holds authoritative reputation
  │
  ├── Device 1 (primary)
  │     reputation = 75
  │     last_sync = now
  │
  ├── Device 2 (secondary)
  │     reputation = derived from primary
  │     deviation_allowance = ±5 points
  │
  └── Device 3 (secondary)
        reputation = derived from primary
        deviation_allowance = ±5 points

On violation on any device:
  - Penalty applied to primary reputation
  - Synced to all devices within 1 hour
  - Device-specific rate limits may vary

On positive action:
  - Bonus applied to primary reputation
  - Synced on next heartbeat

Suspension Level Actions:

Level 1 (1 hour):
  - Can receive messages
  - Can send to existing contacts only
  - Cannot create new sessions
  - Cannot join groups

Level 2 (24 hours):
  - Can receive messages
  - Can send 1:1 only (10/hour max)
  - Cannot send to groups
  - Cannot create groups

Level 3 (7 days):
  - Can receive messages
  - Cannot send any messages
  - Can read group messages
  - Cannot interact

Level 4 (30 days):
  - Cannot send or receive
  - Account appears offline
  - Messages queued for 7 days then dropped
  - Must re-verify to restore

Permanent:
  - Identity key blacklisted
  - Cannot register new identity
  - All data purged after 30 days

Appeal Submission:

POST /api/v1/appeal

{
  "user_id": "0x1234...5678",
  "suspension_id": "susp_abc123",
  "appeal_type": "wrongful_suspension",
  "description": "User-provided explanation",
  "evidence": [
    // Optional supporting information
  ],
  "contact_email": "user@example.com"
}

Response:
{
  "appeal_id": "appeal_xyz789",
  "status": "received",
  "estimated_review": "2024-01-20T00:00:00Z",
  "tracking_url": "https://zentalk.io/appeal/xyz789"
}

Multi-Layer DDoS Defense:

Layer 1: Network Edge
  ├── BGP Flowspec rules
  ├── IP reputation filtering
  ├── Geographic restrictions (optional)
  └── Anycast distribution

Layer 2: Load Balancer
  ├── Connection rate limiting
  ├── SSL/TLS termination
  ├── Request inspection
  └── Backend health monitoring

Layer 3: Application
  ├── Per-user rate limiting
  ├── Authentication verification
  ├── Request validation
  └── Circuit breaker patterns

Layer 4: Protocol
  ├── Message format validation
  ├── Sequence number checking
  ├── Replay attack prevention
  └── Resource exhaustion limits

Circuit Creation Rate Limiting:

Client-side:
  circuit_tokens = 5  // Replenish 1 per 12 seconds

  create_circuit():
    if circuit_tokens ≤ 0:
      wait_for_token()

    circuit_tokens -= 1
    result = attempt_circuit_creation()

    if result == FAILED:
      circuit_tokens -= 0.5  // Extra penalty

    return result

Relay-side:
  per_client_circuits = {}  // Track per client

  on_create_request(client_id):
    count = per_client_circuits[client_id]

    if count ≥ MAX_CIRCUITS_PER_CLIENT:
      return REJECT_LIMIT_EXCEEDED

    if creation_rate(client_id) > MAX_RATE:
      return REJECT_RATE_LIMITED

    // Process creation
    per_client_circuits[client_id] += 1
    return create_circuit()

Emergency Mode Activation:

Triggers:
  - CPU usage > 90% sustained for 5 minutes
  - Memory usage > 95%
  - Network saturation > 90%
  - Request queue depth > 10,000

Actions:
  1. Enable strict rate limiting (0.1x normal)
  2. Require PoW for all requests
  3. Whitelist known-good clients
  4. Drop all unauthenticated connections
  5. Alert operations team
  6. Begin traffic analysis for attack signature

Recovery:
  - Metrics must be normal for 15 minutes
  - Gradual limit restoration (25% increments)
  - Full restoration after 1 hour stable

Rate Limit Testing Strategy:

Unit Tests:
  - Token bucket refill accuracy
  - Burst allowance consumption
  - PoW difficulty calculation
  - Reputation score computation

Integration Tests:
  - End-to-end rate limit enforcement
  - Multi-device rate aggregation
  - Distributed counter consistency
  - Recovery after rate limit

Load Tests:
  - Sustained rate at limit boundary
  - Burst behavior validation
  - PoW solver performance
  - System behavior under attack simulation

Test Scenarios:
  1. Normal user behavior (should never hit limits)
  2. Power user behavior (occasional soft limits)
  3. Spam simulation (should be blocked quickly)
  4. DDoS simulation (should trigger emergency mode)