Security Overview
Security features and best practices for Tuzzle.
Tuzzle provides multiple layers of security to protect your assets from unauthorized access and abuse.
Authentication Methods
| Method | Use Case | Format |
|---|---|---|
| Space API Key | Server-to-server, production backends | sk_ prefix |
| Signed URLs | Temporary file access, client-side uploads | HMAC signature in URL |
Access Control Hierarchy
Access control cascades from spaces to folders to files:
Space (default) -> Folder (override) -> File (override)
Each level can set requires_auth to control whether files need signed URLs for delivery.
File Access Types
| Type | Description |
|---|---|
upload | Public. Anyone with the URL can access the file. |
private | Requires a signed URL for URL generation. Delivery is public after signing. |
authenticated | Requires a signed URL for all access. No CDN caching. |
Upload Security
File Validation
- 80+ dangerous file extensions are blocked (executables, scripts, server-side languages)
- Double extensions are rejected (e.g.,
photo.jpg.php) - Maximum file size enforced (50 MB default, configurable per upload config)
- Image dimension constraints (configurable min/max width and height)
- Format whitelisting via upload configs
Unsigned Upload Restrictions
- Referrer domain validation with wildcard support
- HTTPS enforcement
- Per-config rate limiting
Delivery Security
Signed URLs
- HMAC-SHA256 signatures with server-side secret
- Unix timestamp expiration
- Full URL path and parameter coverage
- Validated on every CDN request for protected files
Path Traversal Prevention
..sequences blocked- Null bytes (
\0) blocked - Double slashes (
//) blocked
Watermarking
- Configurable per space
- Applied on delivery by the CDN
- Supports positioning (compass directions) and opacity
Rate Limiting
- Separate rate limits for API operations, uploads, and unsigned uploads
- CDN concurrency limiting for image processing
- Memory-based request rejection under pressure
Best Practices
- Use API keys for all programmatic access. API keys are space-scoped and can be revoked independently.
- Set access types at the upload config level so files are automatically protected on upload.
- Use
authenticatedtype for sensitive documents that should never be cached on the CDN. - Restrict unsigned uploads with referrer validation, HTTPS enforcement, and rate limits.
- Rotate API keys periodically and revoke unused ones.
- Use folder-level access control to manage permissions for groups of files instead of individual files.