stirfry-spam-filter/README.md

# Strfry Nostr Spam Filter

A sophisticated spam filter for Strfry Nostr relays with reputation tracking, burst handling, and adaptive rate limiting.

## Features

- Reputation-based filtering system with detailed logging
- Intelligent burst handling for follow lists
- Per-user and kind-specific rate limiting
- Content similarity detection
- New account protection
- Bot behavior detection
- Progressive penalty system
- Automatic recovery mechanism
- Configurable thresholds
- Memory-efficient cleanup system

## Installation

1. Clone this repository:
```bash
git clone https://github.com/yourusername/strfry-spam-filter.git
```

2. Make the filter executable:
```bash
chmod +x relay-spam-filter.js
```

3. Configure your strfry relay to use the filter:
```yaml
# Add to your strfry configuration
plugins = [
  {
    exec = "/path/to/relay-spam-filter.js"
  }
]
```

## Configuration

### Rate Limits and Burst Handling

```javascript
// General rate limits
maxRepliesPerMinute: 50,
maxRepliesPerHour: 400,

// Kind-specific limits with burst handling
kindSpecificLimits: {
    0: { // Profile updates
        maxPerHour: 10,
        minTimeBetween: 300
    },
    1: { // Regular posts
        maxPerMinute: 30,
        maxPerHour: 200
    },
    3: { // Follow lists
        maxPerMinute: 120,
        maxPerHour: 360,
        minTimeBetween: 2,
        ignoreSimilarity: true,
        burstAllowance: {
            maxBurst: 500,       // Maximum events in burst
            burstWindow: 300,    // Window for burst (5 minutes)
            cooldownPeriod: 3600 // Cooldown after burst (1 hour)
        }
    },
    7: { // Reactions
        maxPerMinute: 60,
        maxPerHour: 300,
        ignoreSimilarity: true
    }
}
```

### Reputation System

```javascript
reputationConfig: {
    initialScore: 100,          // Starting reputation
    goodEventBonus: 1,          // Points for good events
    spamPenalty: -15,          // Base spam penalty
    recoveryRate: 3,           // Points/hour recovery
    minScore: -100,           // Minimum reputation
    maxScore: 1000,           // Maximum reputation
    blockThreshold: -50,      // Blocking threshold
    blockRecoveryThreshold: -25, // Recovery threshold
    
    // Progressive penalties
    penaltyScaling: {
        0: -15,    // Above 0 reputation
        "-25": -20, // Below -25
        "-50": -25  // Below -50
    },
    
    // Variable recovery rates
    recoveryScaling: {
        0: 3,      // Above 0
        "-25": 2,  // Below -25
        "-50": 1   // Below -50
    }
}
```

### New User Protection

```javascript
newPubkeyReplyThreshold: 60,    // Seconds before first reply
newPubkeyMaxPostsIn5Min: 10     // Initial rate limit
```

## How It Works

### Enhanced Reputation System

The filter maintains a detailed reputation score for each user:

- New users start at 100 points
- Good behavior increases reputation gradually
- Spam behavior triggers scaled penalties based on current reputation
- Recovery rates vary by reputation level
- Detailed logging of all reputation changes
- Special handling for follow list operations

### Burst Handling

Special consideration for bulk operations:

- Follow list updates (kind 3) can operate in burst mode
- Up to 500 follows in a 5-minute window
- Cooldown period after burst completion
- Normal rate limits apply during cooldown
- Reputation affects burst allowances

### Spam Detection

Multiple detection mechanisms:

- Adaptive Rate Limiting
  - Per-user and per-kind limits
  - Reputation-based scaling
  - Burst mode for specific operations

- Content Analysis
  - Cross-user content similarity
  - Fast reply detection
  - Bot pattern recognition

- New Account Protection
  - Progressive rate limits
  - Reply waiting periods
  - Initial posting restrictions

### Logging and Monitoring

Comprehensive logging system:

```
[2024-12-19T10:15:30.123Z] Event abc123 from pubkey xyz789 (reputation: 85.50)
[2024-12-19T10:15:30.124Z] Reputation update: 85.50 -> 86.50 (change: +1.00)
[2024-12-19T10:15:30.125Z] Burst tracking - count: 42/500 (window: 300s remaining)
```

### Memory Management

Efficient resource usage:

- Periodic cleanup of old data
- Configurable retention periods
- Automatic purging of inactive users
- Memory-efficient data structures
- Burst tracking cleanup

## Contributing

Contributions are welcome!

## License

MIT License - See LICENSE file for details