We take security seriously. If you discover a security vulnerability, please report it responsibly.
Please do NOT report security vulnerabilities through public GitHub issues.
Instead, please report them via email to:
Or use GitHub's private vulnerability reporting feature if available.
Please include the following information:
- Description of the vulnerability
- Steps to reproduce the issue
- Potential impact of the vulnerability
- Suggested fix (if you have one)
- Your contact information for follow-up
- Acknowledgment: Within 48 hours of your report
- Initial Assessment: Within 7 days
- Status Updates: Every 7 days until resolution
- Resolution Timeline: Typically within 90 days
- We will work with you to understand and resolve the issue
- We will credit you in the security advisory (unless you prefer to remain anonymous)
- We ask that you do not publicly disclose the issue until we've had a chance to address it
When deploying Spooled Backend, please follow these security guidelines:
- JWT_SECRET: Use a strong, random secret (minimum 32 characters)
openssl rand -base64 32
- Database Passwords: Use strong, unique passwords
- RUST_ENV: Set to
productionin production environments
Never deploy with a key pair taken from this repository or its history. Releases before
2026-10-12 shipped a development key pair under certs/; it is public and must not protect any
deployment. The production Compose file generates a fresh key pair in a private Docker volume on
first start; other platforms should generate one outside Git and provide it through their secret
manager.
- Run behind a reverse proxy with TLS for REST API (:8080)
- Use TLS termination for gRPC (:50051) via envoy, nginx, or cloud load balancers
- Use network policies to restrict database access
- Don't expose metrics endpoint publicly
- Configure appropriate CORS settings
- Use SSL for database connections in production
- Apply principle of least privilege for database users
- Enable PostgreSQL audit logging
- Use Redis AUTH in production
- Don't expose Redis to the internet
- Consider using TLS for Redis connections
- Rotate API keys regularly
- Use short-lived JWT tokens
- Implement proper rate limiting
- Validate and sanitize all inputs
- Send REST credentials in the
Authorization: Bearerheader. Query-string credentials (?api_key=,?token=) are rejected with401on every REST endpoint except the four realtime routes β/api/v1/ws,/api/v1/events,/api/v1/events/jobs/{id},/api/v1/events/queues/{name}β where browserEventSourceandWebSocketcannot set headers. Query strings are captured by reverse-proxy and CDN access logs, tracing spans, browser history and theRefererheader, and API keys do not expire by default (CWE-598) - Prefer a short-lived JWT over an API key on the realtime routes, and treat any key that has appeared in a URL as compromised
- Behind a reverse proxy, set
TRUSTED_CLIENT_IP_HEADERorTRUSTED_PROXY_HOPSso per-IP rate limiting sees the real client. The leftmostX-Forwarded-Forentry is caller-supplied and is never trusted. WithoutTRUSTED_CLIENT_IP_HEADER,CF-Connecting-IPandX-Real-IPare believed only when the TCP peer is a loopback, private, link-local or unique-local address, so a client that reaches the backend directly cannot choose its own rate-limit bucket; an IPv6 client is limited as its whole /64 - Email login codes are throttled per client IP (
POST /auth/email/start: 3 per minute and 10 per hour) and per address (5 guesses per 10 minutes per client, 20 from all clients); setTURNSTILE_SECRET_KEYto also require a Cloudflare Turnstile token onPOST /auth/email/start - Stripe Checkout sessions are created by
POST /api/v1/billing/checkoutand trusted through server-set metadata only; theclient_reference_idof a public Payment Link is a URL parameter and cannot be trusted to name an organization - For gRPC API-key authentication, send the API key credential as the value of the
x-api-keymetadata field;x-api-keyis the metadata name, not a separate credential - Alternatively, send a JWT credential as
authorization: Bearer <jwt-token>metadata - gRPC health and reflection services are public by default (disable in production if needed)
- Run as non-root user (already configured in Dockerfile)
- Use read-only filesystem where possible
- Scan images for vulnerabilities
- Keep base images updated
Spooled Backend includes several security features:
- Multi-tenant isolation enforced in the application layer: every query filters on the authenticated
organization_id(RLS policies exist in the migrations but are inert at runtime β see docs/guides/architecture.md) - Header-only REST credentials, so keys and tokens stay out of access logs and
Refererheaders - Bcrypt password hashing for API keys (used by both REST and gRPC)
- JWT authentication with configurable expiration
- Rate limiting per API key
- HMAC webhook verification for incoming webhooks
- Input validation on all endpoints (REST and gRPC)
- Constant-time comparison for sensitive data
- Security headers via middleware
- Queue-scoped authorization across REST, realtime, and gRPC operations
- Stream revalidation so key revocation, expiry, organization deletion, and scope narrowing take effect on active realtime/gRPC streams
- gRPC interceptors for authentication and authorization
- gRPC health service for load balancer health checks
- SSRF protection for outgoing webhook URLs
Outgoing webhook URLs are validated in production to prevent Server-Side Request Forgery attacks:
- β Private IP ranges (RFC 1918: 10.x.x.x, 172.16-31.x.x, 192.168.x.x)
- β Loopback addresses (127.x.x.x, localhost, ::1)
- β Link-local addresses (169.254.x.x, fe80::)
- β Cloud metadata endpoints (169.254.169.254, metadata.google.internal)
- β Internal hostnames (.local, .internal, .corp, .lan)
- β HTTP URLs (HTTPS required in production)
- β CGNAT ranges (100.64.0.0/10)
DNS resolution is also validated to prevent DNS rebinding attacks.
Security fixes are documented in CHANGELOG.md. Deploy the latest
release and review GitHub security advisories before operating an internet-facing
instance.
Thank you for helping keep Spooled Backend and its users safe!