forked from claw/flaskpaste
105 lines
5.6 KiB
Markdown
105 lines
5.6 KiB
Markdown
# FlaskPaste
|
|
|
|
## Purpose
|
|
|
|
FlaskPaste is a lightweight, security-hardened pastebin REST API for self-hosted deployments. It provides a minimal, dependency-light alternative to public pastebin services, designed for environments where data privacy, authentication control, and operational simplicity are priorities.
|
|
|
|
## Problem Statement
|
|
|
|
Public pastebin services present risks:
|
|
- Data sovereignty concerns (content stored on third-party infrastructure)
|
|
- Limited authentication options
|
|
- No control over retention policies
|
|
- Abuse/spam from other users affecting service reliability
|
|
- Feature bloat and complex UIs when only an API is needed
|
|
|
|
## Solution
|
|
|
|
A self-hosted pastebin API that:
|
|
- Stores pastes locally in SQLite
|
|
- Supports client certificate authentication via reverse proxy
|
|
- Automatically expires content based on access patterns
|
|
- Prevents abuse through content-hash deduplication
|
|
- Serves text and binary content with proper MIME detection
|
|
- Runs behind any reverse proxy (nginx, HAProxy, Caddy)
|
|
|
|
## Success Criteria
|
|
|
|
```
|
|
┌────────────────────────────────┬────────────────────────────────────────────┐
|
|
│ Criterion │ Metric
|
|
├────────────────────────────────┼────────────────────────────────────────────┤
|
|
│ Security │ Zero injection vulnerabilities
|
|
│ │ All OWASP headers implemented
|
|
│ │ Input validation on all endpoints
|
|
├────────────────────────────────┼────────────────────────────────────────────┤
|
|
│ Reliability │ SQLite ACID guarantees
|
|
│ │ Graceful degradation on errors
|
|
│ │ Health check endpoint for monitoring
|
|
├────────────────────────────────┼────────────────────────────────────────────┤
|
|
│ Simplicity │ Single dependency (Flask)
|
|
│ │ SQLite for storage (no external DB)
|
|
│ │ Environment-based configuration
|
|
├────────────────────────────────┼────────────────────────────────────────────┤
|
|
│ Operability │ Container-ready (Podman/Docker)
|
|
│ │ Gunicorn-compatible WSGI
|
|
│ │ Request tracing via X-Request-ID
|
|
└────────────────────────────────┴────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Scope
|
|
|
|
### In Scope
|
|
|
|
- REST API for paste CRUD operations
|
|
- Text and binary content support
|
|
- Magic-byte MIME type detection
|
|
- Client certificate authentication (via proxy header)
|
|
- Configurable size limits (anon vs authenticated)
|
|
- Time-based expiry with access-touch semantics
|
|
- Content-hash deduplication for abuse prevention
|
|
- Security headers (HSTS, CSP, X-Frame-Options, etc.)
|
|
- Request tracing and structured logging
|
|
- Container deployment support
|
|
- SQLite storage
|
|
|
|
### Out of Scope
|
|
|
|
- Web UI / HTML frontend
|
|
- User registration / account management
|
|
- Syntax highlighting
|
|
- Paste forking / versioning
|
|
- Public paste listing / discovery
|
|
- Rate limiting per IP (delegated to reverse proxy)
|
|
- Multi-node clustering / distributed storage
|
|
- Alternative storage backends (S3, PostgreSQL)
|
|
|
|
## Constraints
|
|
|
|
- **Single process** - SQLite limits concurrency; scale via multiple containers
|
|
- **Reverse proxy required** - Client cert auth requires TLS termination
|
|
- **No web UI** - API-only; CLI tools (curl, httpie) are the interface
|
|
- **Ephemeral by design** - Pastes expire; not for permanent storage
|
|
|
|
## Assumptions
|
|
|
|
- Deployment behind a TLS-terminating reverse proxy
|
|
- Client certificates managed externally (PKI, mTLS)
|
|
- Operators have container runtime (Podman/Docker) or Python venv
|
|
- SQLite performance sufficient for expected load
|
|
|
|
## Technical Stack
|
|
|
|
```
|
|
┌─────────────────┬──────────────────────────────────────────────────────────┐
|
|
│ Component │ Technology
|
|
├─────────────────┼──────────────────────────────────────────────────────────┤
|
|
│ Framework │ Flask 3.x
|
|
│ Database │ SQLite 3 (built-in)
|
|
│ WSGI Server │ Gunicorn (production)
|
|
│ Container │ Podman / Docker
|
|
│ Testing │ pytest, pytest-cov
|
|
│ Python │ 3.11+
|
|
└─────────────────┴──────────────────────────────────────────────────────────┘
|
|
```
|