🔒 Supernal TTS Security Documentation

Overview

This document outlines the security measures implemented in the Supernal TTS API to ensure safe, reliable, and compliant operation in production environments.

Table of Contents

1. Authentication & Authorization
2. Rate Limiting
3. Input Validation
4. Security Headers
5. Data Protection
6. Deployment Security
7. Security Checklist

Authentication & Authorization

API Key Authentication

The API uses Bearer token authentication with API keys prefixed with sk-tts-:

curl -X POST https://api.supernal-tts.com/v1/generate \
  -H "Authorization: Bearer sk-tts-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world"}'

API Key Features:

• Bcrypt hashing: Keys are hashed with bcrypt (10 rounds) before storage
• Scopes: Each key has configurable scopes (read, write, admin)
• Rate limits: Per-key rate limiting
• Expiration: Optional expiration dates
• Usage tracking: Last used timestamp

Creating API Keys (Development):

// Set CREATE_TEST_KEYS=true in development
// Keys will be printed to console on startup

JWT Authentication

Alternative authentication using JWT tokens:

curl -X POST https://api.supernal-tts.com/v1/generate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world"}'

JWT Features:

• Standard JWT with HS256 signing
• Contains user ID, email, and roles
• Configurable expiration
• Role-based access control

Development Mode

For development, authentication can be disabled:

REQUIRE_AUTH=false npm start

Rate Limiting

Tiered Rate Limiting

Different rate limits for different scenarios:

Tier	Limit	Window	Use Case
Global	100 req/min	60s	Per IP address
Authenticated	1000 req/min	60s	Per API key
Generation	10 req/min	60s	TTS generation
Strict	10 req/min	60s	Unauthenticated

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 2024-01-01T00:01:00Z
Retry-After: 60

Redis Support

For distributed rate limiting across multiple instances:

REDIS_URL=redis://localhost:6379 npm start

Bypassing Rate Limits

Admin users automatically bypass rate limits. Custom rate limits can be set per API key.

Input Validation

Text Validation

All text inputs are validated with Zod schemas:

• Min length: 1 character
• Max length: 100,000 characters
• Sanitization: Removes control characters
• Whitespace: Normalized to single spaces

Request Validation

{
  text: string,              // Required, 1-100k chars
  options: {
    provider: string,        // openai|cartesia|azure|mock
    voice: string,          // Provider-specific
    speed: number,          // 0.25-4.0
    format: string,         // mp3|opus|aac|flac|wav
    quality: string,        // standard|high
    language: string,       // ISO 639-1 code
    cache: boolean          // Default: true
  }
}

Error Responses

Validation errors return detailed information:

{
  "error": "Validation failed",
  "details": [
    {
      "path": "options.voice",
      "message": "Invalid voice for selected provider"
    }
  ]
}

Security Headers

Helmet Configuration

The API uses Helmet.js with the following configuration:

{
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      mediaSrc: ["'self'"],     // Allow audio playback
      // ... other directives
    }
  },
  hsts: {
    maxAge: 31536000,         // 1 year
    includeSubDomains: true,
    preload: true
  }
}

Custom Headers

Additional security headers:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: microphone=(), camera=(), geolocation=()

CORS Configuration

CORS is configured per environment:

# Development
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# Production
ALLOWED_ORIGINS=https://app.example.com,https://www.example.com

Data Protection

Request Sanitization

1. Text sanitization: Removes zero-width characters and control codes
2. Size limits: 1MB default request size
3. Content-Type validation: Only accepts application/json

Sensitive Data Handling

1. No PII storage: Audio is cached by content hash, not user data
2. API keys: Never logged or returned in responses
3. Error messages: Sanitized to prevent information leakage

Caching Security

• Files cached with SHA-256 hashes
• No user-identifiable information in cache
• Cache directory permissions: 0755

Deployment Security

Environment Variables

Required security environment variables:

# Production Required
NODE_ENV=production
JWT_SECRET=<strong-random-secret>
REQUIRE_AUTH=true

# Optional Security
TRUST_PROXY=true              # Behind reverse proxy
WHITELISTED_IPS=1.2.3.4,5.6.7.8
MAX_REQUEST_SIZE=1mb

HTTPS/TLS

Always deploy behind HTTPS:

1. Use reverse proxy (nginx, caddy)
2. Enable HSTS headers
3. Use TLS 1.2 minimum
4. Strong cipher suites only

Container Security

When using Docker:

# Run as non-root user
USER node

# Read-only root filesystem
# Mount cache directory as volume

# No sensitive data in image
# Use secrets management

Infrastructure Security

1. Network isolation: API in private subnet
2. Firewall rules: Only allow required ports
3. Monitoring: Log all authentication failures
4. Secrets management: Use AWS Secrets Manager, Vault, etc.

Security Checklist

Pre-Deployment

• All environment variables set correctly
• Authentication enabled (REQUIRE_AUTH=true)
• Strong JWT secret (min 32 chars)
• HTTPS/TLS configured
• Rate limiting tested
• Input validation working
• Security headers verified

Monitoring

• Authentication failures logged
• Rate limit violations tracked
• Error rates monitored
• Response times tracked
• Suspicious patterns alerted

Regular Audits

• Dependency updates (npm audit)
• Security scanning (Snyk, etc.)
• Penetration testing
• Access log review
• API key rotation

Testing Security

Run the security test suite:

# Basic security tests
./scripts/test-security.sh

# With verbose output
VERBOSE=true ./scripts/test-security.sh

# Against production
API_URL=https://api.example.com/v1 ./scripts/test-security.sh

Reporting Security Issues

If you discover a security vulnerability:

1. DO NOT open a public issue
2. Email security@supernal.com
3. Include:
   • Description of the issue
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

We aim to respond within 48 hours and provide fixes within 7 days for critical issues.

Compliance

The API is designed to support:

• GDPR: No PII storage, data minimization
• SOC 2: Audit logging, access controls
• HIPAA: Encryption, access controls (with proper BAA)
• PCI DSS: No payment data handling

Note: Compliance requires proper deployment and configuration.

Security Roadmap

Completed (Phase 1) ✅

• API key authentication
• JWT support
• Rate limiting
• Input validation
• Security headers
• CORS protection

Planned (Phase 2)

• OAuth 2.0 support
• Webhook signatures
• Audit logging
• IP allowlisting UI

Future (Phase 3)

• mTLS support
• Hardware security module (HSM)
• Zero-trust architecture
• Advanced threat detection