stirfry-spam-filter/README.md

# Strfry Nostr Spam Filter


## Features

- Reputation-based filtering system
- Per-user rate limiting
- Content similarity detection
- New account protection
- Bot behavior detection
- Progressive penalty system
- Automatic recovery mechanism
- Kind-specific rate limits
- Configurable thresholds

## 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:
```bash
# Add to your strfry configuration
plugins = [
  {
    exec = "/path/to/relay-spam-filter.js"
  }
]
```

## Configuration

The filter includes many configurable options. Here are the key settings:

### Rate Limits
```javascript
maxRepliesPerMinute: 50,        // Maximum replies per minute per user
maxRepliesPerHour: 400,         // Maximum replies per hour per user
```

### Event-Type Specific Limits
```javascript
kindSpecificLimits: {
    0: { maxPerHour: 10 },      // Profile updates
    3: { maxPerHour: 5 },       // Contact list updates
    1: {                        // Regular posts
        maxPerMinute: 30,
        maxPerHour: 200
    }
}
```

### Reputation System
```javascript
reputationConfig: {
    initialScore: 100,          // Starting reputation for new users
    goodEventBonus: 1,          // Points gained for good events
    spamPenalty: -15,           // Base penalty for spam
    recoveryRate: 3,            // Points recovered per hour
    minScore: -100,             // Minimum possible reputation
    maxScore: 1000,             // Maximum possible reputation
    blockThreshold: -50,        // Users blocked at this score
    blockRecoveryThreshold: -25 // Must recover to this to post again
}
```

### New User Protection
```javascript
newPubkeyReplyThreshold: 60,    // Seconds new users must wait to reply
newPubkeyMaxPostsIn5Min: 10     // Maximum posts in first 5 minutes
```

### Content Analysis
```javascript
contentSimilarityThreshold: 0.8, // 80% similarity triggers spam detection
fastReplyThreshold: 30,          // Minimum seconds between reply and original post
```

## How It Works

### Reputation System

The filter maintains a reputation score for each user:

1. New users start at 100 points
2. Good behavior slowly increases reputation
3. Spam behavior results in penalties:
   - -15 points above 0 reputation
   - -20 points below -25 reputation
   - -25 points below -50 reputation
4. Recovery rates:
   - 3 points/hour above 0
   - 2 points/hour between -25 and 0
   - 1 point/hour below -50
5. Users are blocked at -50 until they recover to -25

### Spam Detection

The filter checks for several types of spam behavior:

1. Rate Limiting
   - Monitors post frequency per user
   - Different limits for different event types
   - Limits scale with reputation

2. Content Analysis
   - Checks for duplicate content across users
   - Detects suspiciously fast replies
   - Identifies bot-like behavior patterns

3. New Account Protection
   - Stricter limits for new accounts
   - Longer waiting periods for replies
   - Limited initial posting rate

4. Bot Detection
   - Identifies automated posting patterns
   - Checks for relay URL spam
   - Monitors reply timing patterns

### Progressive Enforcement

The system becomes progressively stricter with problematic behavior:

1. Initial warnings and small penalties
2. Increased penalties for continued violations
3. Stricter rate limits for low-reputation users
4. Eventual blocking for persistent offenders

## Bypass Rules

Certain event kinds can bypass specific checks:

```javascript
allowedKinds: [3, 5, 10001, 10002, 30311],  // Bypass content checks
bypassAllChecksKinds: [38383]                // Bypass all checks
```

## Monitoring

The filter provides detailed logging:

```javascript
[2024-12-19T10:15:30.123Z] Event abc123 from pubkey xyz789 (reputation: 85.50)
[2024-12-19T10:15:30.124Z] Rate limit exceeded for pubkey xyz789
```

## Performance Considerations

- Memory usage is managed through periodic cleanup
- Old events and stats are automatically purged
- Reputation data persists for 24 hours of inactivity

## Contributing

Contributions are welcome!

## License

MIT License - See LICENSE file for details