telegram-management-system/marketing-agent/services/safety-guard/README.md

# Safety Guard Service

Content moderation, compliance checking, and rate limiting service for the Marketing Intelligence Agent system.

## Overview

The Safety Guard service provides comprehensive safety and compliance features:

- **Content Moderation**: AI-powered content analysis with profanity detection, sentiment analysis, and toxicity checking
- **Compliance Management**: Region-specific compliance validation (GDPR, CCPA, etc.)
- **Rate Limiting**: Flexible rate limiting with tier-based controls
- **Content Policy**: Customizable content policies with pattern matching and validation rules

## Features

### Content Moderation
- Multi-layer moderation using OpenAI, Google Cloud NLP, and local filters
- Profanity detection with custom word lists
- Sentiment analysis and toxicity scoring
- Risk score calculation and content categorization
- Result caching for performance optimization

### Compliance Checking
- Region-specific compliance rules (EU/GDPR, CA/CCPA, BR/LGPD, ZA/POPIA)
- Consent validation and tracking
- Age restriction enforcement
- Data retention policy validation
- Marketing-specific compliance (opt-out requirements, double opt-in)

### Rate Limiting
- Hierarchical rate limits (per second, minute, hour, day)
- Tier-based limits (free, basic, pro, enterprise)
- Custom rate limit creation
- Violation tracking and reporting
- Redis-based distributed rate limiting

### Content Policy
- Configurable content policies (default, strict, marketing)
- Pattern-based content validation
- Media size and type restrictions
- Link validation and spam detection
- Policy violation logging and reporting

## API Endpoints

### Content Moderation
- `POST /api/v1/moderate` - Moderate single content
- `POST /api/v1/moderate/bulk` - Moderate multiple contents

### Compliance
- `POST /api/v1/compliance/check` - Check compliance for action
- `POST /api/v1/compliance/consent/validate` - Validate user consent
- `GET /api/v1/compliance/report` - Get compliance report

### Rate Limiting
- `POST /api/v1/ratelimit/check` - Check rate limit
- `POST /api/v1/ratelimit/check-multiple` - Check multiple limits
- `GET /api/v1/ratelimit/status` - Get rate limit status
- `POST /api/v1/ratelimit/reset` - Reset rate limit
- `GET /api/v1/ratelimit/violations` - Get violation report

### Content Policy
- `POST /api/v1/policy/validate` - Validate content against policy
- `PUT /api/v1/policy/{policyId}` - Update policy
- `GET /api/v1/policy/violations` - Get policy violation report

### Combined Safety Check
- `POST /api/v1/safety/check` - Comprehensive safety validation

## Installation

```bash
# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Start the service
npm start

# Development mode with auto-reload
npm run dev
```

## Configuration

### Environment Variables

- `PORT`: Service port (default: 3004)
- `MONGODB_URI`: MongoDB connection string
- `REDIS_HOST/PORT`: Redis connection details
- `OPENAI_API_KEY`: OpenAI API key for AI moderation
- `GOOGLE_CLOUD_PROJECT`: Google Cloud project for NLP API
- `CUSTOM_BAD_WORDS`: Comma-separated custom bad words

### Rate Limit Configuration

Default rate limits can be adjusted in the service initialization:

```javascript
// Message rate limits
'message:minute': 30 points
'message:hour': 500 points
'message:day': 5000 points

// API rate limits
'api:request:second': 10 points
'api:request:minute': 100 points
```

### Compliance Regions

Supported regions with specific compliance rules:
- `EU`: GDPR compliance
- `CA`: CCPA compliance  
- `BR`: LGPD compliance
- `ZA`: POPIA compliance
- `DEFAULT`: General compliance

## Usage Examples

### Content Moderation

```javascript
// Moderate content
const response = await fetch('http://localhost:3004/api/v1/moderate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        content: 'Hello world!',
        contentType: 'text'
    })
});

const result = await response.json();
// result.data.approved: true/false
// result.data.riskScore: 0-1
// result.data.violations: [...]
```

### Compliance Check

```javascript
// Check compliance
const response = await fetch('http://localhost:3004/api/v1/compliance/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        action: 'bulk_message',
        content: 'Marketing message',
        targetRegion: 'EU',
        targetAudience: { minAge: 16 },
        metadata: { hasConsent: true }
    })
});
```

### Rate Limit Check

```javascript
// Check rate limit
const response = await fetch('http://localhost:3004/api/v1/ratelimit/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        limitType: 'message:hour',
        identifier: 'user123',
        tier: 'pro',
        cost: 1
    })
});
```

### Combined Safety Check

```javascript
// Comprehensive safety check
const response = await fetch('http://localhost:3004/api/v1/safety/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        content: 'Check out this offer!',
        action: 'message',
        context: {
            accountId: 'account123',
            targetRegion: 'EU',
            targetAudience: { minAge: 18 },
            tier: 'pro',
            policyId: 'marketing'
        }
    })
});
```

## Development

### Running Tests

```bash
npm test
```

### Adding Custom Moderation Rules

1. Add custom bad words in `.env`:
   ```
   CUSTOM_BAD_WORDS=word1,word2,word3
   ```

2. Create custom content policy:
   ```javascript
   await contentPolicyService.updatePolicy('custom', {
       rules: {
           prohibitedPatterns: ['pattern1', 'pattern2'],
           maxRiskScore: 0.5
       }
   });
   ```

3. Add custom rate limits:
   ```javascript
   await rateLimiterService.setCustomRateLimit('special-campaign', {
       points: 1000,
       duration: 3600,
       blockDuration: 300
   });
   ```

## Monitoring

### Health Check

```bash
curl http://localhost:3004/health
```

### Metrics

- Moderation processing time
- Compliance check results
- Rate limit violations
- Policy violation trends

## Security Considerations

1. **API Keys**: Store securely in environment variables
2. **Rate Limiting**: Protect against abuse
3. **Content Storage**: Limited content preview storage for privacy
4. **TTL Indexes**: Automatic cleanup of old violation records
5. **Fail-Open**: Service fails permissively on errors to avoid blocking

## License

Proprietary