Security Best Practices

OptStuff is built with a defense-in-depth approach. Even if one layer is compromised, multiple additional barriers protect your assets.

Security Layers

Encrypted Storage

Secret keys are encrypted with AES-256-GCM before storage. The encryption key is derived via HKDF (RFC 5869) from a master secret stored in environment variables — separate from the database. Even if the database is compromised, attackers cannot obtain usable keys.

Request Signing

Every request must include an HMAC-SHA256 signature. The signature is a one-way function — intercepting it cannot reveal the secret key. Signatures are compared using constant-time comparison (timingSafeEqual) to prevent timing attacks.

See URL Signing for implementation details.

Signature Expiration

The optional exp parameter limits how long a signed URL is valid. Recommended expiration times depend on the use case — see URL Signing.

Domain Whitelisting

Two-layer domain control restricts both who can use the service (referer domains) and which images can be processed (source domains). Both settings are configured at the project level in Settings → Domain Security. Referer validation targets browser-based hotlinking specifically — requests without a Referer header are allowed since they indicate server-to-server calls or privacy-stripping policies, not hotlinking. See Domain Whitelisting for configuration and Referer Security Model for the trust model.

Rate Limiting

Per-key rate limits prevent abuse and contain the impact of compromised keys. In the current implementation, Redis outages cause rate limiting to fail open to preserve availability; monitor Redis health and alerting accordingly. See Rate Limiting for details.

Dual-Key System

Public keys (pk_...) are safe to expose in URLs. Secret keys (sk_...) never leave your server. Even if someone sees a signed URL, they cannot forge new requests.

Attack Protection Summary

Secure Defaults

Technical Standards

Production Checklist

Use this checklist before going live:

API Key Security

• Secret keys (sk_...) stored in server-side environment variables only
• No secret keys in frontend code, Git, or client-side bundles
• .env / .env.local files added to .gitignore
• API key expiration set for non-permanent integrations
• Unused or test keys revoked

Domain Security

• allowedSourceDomains explicitly configured (empty list rejects all in production)
• allowedRefererDomains configured if browser hotlinking is a concern
• Development, staging, and production use separate projects or domain configs

URL Signing

• All signing happens server-side (Server Components, API Routes, or backend services)
• Appropriate exp expiration set on signed URLs
• No signing logic in client-side JavaScript

Infrastructure

• Redis health monitoring configured
• Rate limit alerts set (see Rate Limiting)
• HTTPS enforced on all endpoints

Environment Isolation

Use separate projects and API keys for each environment to prevent cross-environment leakage:

This ensures a compromised development key cannot access production resources, and development traffic does not consume production rate limits.

Incident Response: Key Compromise

If an API key may have been exposed:

1. Rotate immediately — Use the Rotate action in Dashboard → API Keys. This atomically revokes the old key and creates a new one.
2. Update environment variables — Deploy the new secret key to all services that use it.
3. Review request logs — Check Dashboard → Usage for suspicious traffic patterns during the exposure window.
4. Audit access — Verify no unauthorized domains were added to the project's domain security settings.
5. Consider expiration — For the new key, set a shorter expiration until you've confirmed the incident is contained.

Related Documentation

• URL Signing — Signature generation and code examples
• Domain Whitelisting — Domain configuration
• Rate Limiting — Rate limit configuration
• Key Management — API key lifecycle best practices
• SSRF Prevention — How the image proxy prevents Server-Side Request Forgery