Built-in WAF

Shield implements three main security mechanisms:

1. Hashcash-based CAPTCHA - Proof-of-work challenges to prevent automated attacks
2. Rate Limiting - Token bucket algorithm to control API request rates
3. Anti-XSS Utilities - Input sanitization functions to prevent cross-site scripting

Components

Hashcash CAPTCHA

A proof-of-work based CAPTCHA system that requires clients to solve computational puzzles before performing sensitive operations. The frontend requests a challenge with specified difficulty and TTL, solves it locally, and submits the solution for verification.

Use cases:

• Protecting registration/login endpoints
• Preventing automated form submissions
• Rate limiting expensive operations

The challenge-response cycle is stateful and stored in Redis with configurable expiration.

Rate Limiting Middleware

Per-user rate limiting using the token bucket algorithm. The middleware can be applied to any gRPC endpoint to automatically enforce rate limits based on user identity.

Configuration parameters:

• api_name: Identifier for the rate limit bucket
• capacity: Maximum tokens available
• refill: Token refill rate (tokens per second)
• cost: Tokens consumed per request
• ttl: Bucket expiration time

Rate limit state is maintained in Redis using atomic Lua scripts. The middleware extracts user identity from request extensions (requires authentication middleware to run first).

Anti-XSS Utilities

Three sanitization functions for different content types:

• anti_xss_text(): Basic HTML entity encoding for plain text
• anti_xss_markdown(): Sanitizes markdown while preserving safe formatting, with allowlist-based filtering for images and links
• anti_xss_enhanced(): Advanced protection that detects and removes script injections, event handlers, and dangerous schemes

When to use:

• Sanitize user-generated content before storage or display
• Clean markdown in announcements, tickets, or comments
• Validate URLs and embedded content

Architecture Notes

Redis Dependency

Both hashcash and rate limiting rely on Redis for state management. The hashcash service stores active challenges, while rate limiting maintains token bucket state with atomic updates.

Middleware Integration

RateLimitLayer is a Tower middleware that integrates with the gRPC server stack. It must be placed after authentication middleware to access user identity from request extensions.

Performance Considerations

• Hashcash difficulty should be tuned based on client capabilities (mobile vs desktop)
• Rate limit refill rates should balance user experience with system protection
• Anti-XSS functions are synchronous and relatively lightweight, safe to use in request paths