forked from username/flaskpaste
226 lines
6.5 KiB
Markdown
226 lines
6.5 KiB
Markdown
# FlaskPaste
|
|
|
|
A lightweight, secure pastebin REST API built with Flask.
|
|
|
|
## Features
|
|
|
|
- **Simple REST API** - Create, retrieve, and delete pastes via HTTP
|
|
- **Binary support** - Upload text, images, archives, and other binary content
|
|
- **Automatic MIME detection** - Magic byte detection for common formats (PNG, JPEG, GIF, WebP, ZIP, PDF, GZIP)
|
|
- **Client certificate authentication** - Optional auth via `X-SSL-Client-SHA1` header
|
|
- **Automatic expiry** - Pastes expire after configurable period of inactivity
|
|
- **Size limits** - Configurable limits for anonymous and authenticated users
|
|
- **Abuse prevention** - Content-hash deduplication throttles repeated identical submissions
|
|
- **Proof-of-work** - Configurable computational puzzle prevents automated spam
|
|
- **Security headers** - HSTS, CSP, X-Frame-Options, Cache-Control, and more
|
|
- **CLI client** - Standalone `fpaste` command-line tool included
|
|
- **Request tracing** - X-Request-ID support for log correlation
|
|
- **Proxy trust validation** - Optional shared secret for defense-in-depth
|
|
- **Minimal dependencies** - Flask only, SQLite built-in
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Clone and setup
|
|
git clone <repository>
|
|
cd flaskpaste
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
|
|
# Run development server
|
|
python run.py
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET /` | API information and usage |
|
|
| `GET /health` | Health check (returns DB status) |
|
|
| `GET /challenge` | Get proof-of-work challenge |
|
|
| `POST /` | Create a new paste |
|
|
| `GET /<id>` | Retrieve paste metadata |
|
|
| `HEAD /<id>` | Retrieve paste metadata (headers only) |
|
|
| `GET /<id>/raw` | Retrieve raw paste content |
|
|
| `HEAD /<id>/raw` | Retrieve paste headers (no body) |
|
|
| `DELETE /<id>` | Delete paste (requires auth) |
|
|
|
|
## Usage Examples
|
|
|
|
### Create a paste (raw text)
|
|
```bash
|
|
curl --data-binary @file.txt http://localhost:5000/
|
|
```
|
|
|
|
### Create a paste (piped input)
|
|
```bash
|
|
echo "Hello, World!" | curl --data-binary @- http://localhost:5000/
|
|
```
|
|
|
|
### Create a paste (JSON)
|
|
```bash
|
|
curl -H "Content-Type: application/json" \
|
|
-d '{"content":"Hello from JSON!"}' \
|
|
http://localhost:5000/
|
|
```
|
|
|
|
### Retrieve paste metadata
|
|
```bash
|
|
curl http://localhost:5000/abc12345
|
|
```
|
|
|
|
### Retrieve raw content
|
|
```bash
|
|
curl http://localhost:5000/abc12345/raw
|
|
```
|
|
|
|
### Delete a paste (requires authentication)
|
|
```bash
|
|
curl -X DELETE \
|
|
-H "X-SSL-Client-SHA1: <your-cert-fingerprint>" \
|
|
http://localhost:5000/abc12345
|
|
```
|
|
|
|
## CLI Client
|
|
|
|
A standalone command-line client `fpaste` is included (no external dependencies).
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# Create paste from file
|
|
./fpaste create file.txt
|
|
|
|
# Create paste from stdin
|
|
echo "Hello" | ./fpaste
|
|
|
|
# Get paste content
|
|
./fpaste get abc12345
|
|
|
|
# Get paste metadata
|
|
./fpaste get -m abc12345
|
|
|
|
# Delete paste (requires auth)
|
|
./fpaste delete abc12345
|
|
|
|
# Show server info
|
|
./fpaste info
|
|
```
|
|
|
|
### Configuration
|
|
|
|
Set server URL and authentication via environment or config file:
|
|
|
|
```bash
|
|
# Environment variables
|
|
export FLASKPASTE_SERVER="https://paste.example.com"
|
|
export FLASKPASTE_CERT_SHA1="your-cert-fingerprint"
|
|
|
|
# Or config file (~/.config/fpaste/config)
|
|
server = https://paste.example.com
|
|
cert_sha1 = your-cert-fingerprint
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Configuration via environment variables:
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `FLASK_ENV` | `development` | Environment (`development`, `production`, `testing`) |
|
|
| `FLASKPASTE_DB` | `./data/pastes.db` | SQLite database path |
|
|
| `FLASKPASTE_ID_LENGTH` | `12` | Paste ID length (hex characters) |
|
|
| `FLASKPASTE_MAX_ANON` | `3145728` (3 MiB) | Max paste size for anonymous users |
|
|
| `FLASKPASTE_MAX_AUTH` | `52428800` (50 MiB) | Max paste size for authenticated users |
|
|
| `FLASKPASTE_EXPIRY` | `432000` (5 days) | Paste expiry in seconds |
|
|
| `FLASKPASTE_DEDUP_WINDOW` | `3600` (1 hour) | Dedup throttle window in seconds |
|
|
| `FLASKPASTE_DEDUP_MAX` | `3` | Max identical submissions per window |
|
|
| `FLASKPASTE_PROXY_SECRET` | (empty) | Shared secret for proxy trust validation |
|
|
| `FLASKPASTE_POW_DIFFICULTY` | `20` | PoW difficulty (leading zero bits, 0=disabled) |
|
|
| `FLASKPASTE_POW_TTL` | `300` (5 min) | PoW challenge validity period |
|
|
| `FLASKPASTE_POW_SECRET` | (auto) | Secret for signing PoW challenges |
|
|
|
|
## Authentication
|
|
|
|
FlaskPaste uses client certificate authentication. When deployed behind a reverse proxy (nginx, Apache), configure the proxy to:
|
|
|
|
1. Terminate TLS and validate client certificates
|
|
2. Extract the certificate SHA1 fingerprint
|
|
3. Pass it via the `X-SSL-Client-SHA1` header
|
|
|
|
Example nginx configuration:
|
|
```nginx
|
|
location / {
|
|
proxy_pass http://127.0.0.1:5000;
|
|
proxy_set_header X-SSL-Client-SHA1 $ssl_client_fingerprint;
|
|
}
|
|
```
|
|
|
|
Authenticated users can:
|
|
- Upload larger pastes (50 MiB vs 3 MiB)
|
|
- Delete their own pastes
|
|
|
|
## Production Deployment
|
|
|
|
### Using Gunicorn
|
|
```bash
|
|
pip install gunicorn
|
|
gunicorn -w 4 -b 0.0.0.0:5000 wsgi:app
|
|
```
|
|
|
|
### Using Podman/Docker
|
|
```bash
|
|
podman build -t flaskpaste .
|
|
podman run -d -p 5000:5000 -v flaskpaste-data:/app/data flaskpaste
|
|
```
|
|
|
|
See `Containerfile` for container build configuration.
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
```bash
|
|
pip install pytest pytest-cov
|
|
pytest tests/ -v
|
|
```
|
|
|
|
### Test Coverage
|
|
```bash
|
|
pytest tests/ --cov=app --cov-report=term-missing
|
|
```
|
|
|
|
### Project Structure
|
|
```
|
|
flaskpaste/
|
|
├── app/
|
|
│ ├── __init__.py # Flask app factory
|
|
│ ├── config.py # Configuration classes
|
|
│ ├── database.py # SQLite management
|
|
│ └── api/
|
|
│ ├── __init__.py # Blueprint setup
|
|
│ └── routes.py # API endpoints
|
|
├── tests/ # Test suite
|
|
├── data/ # SQLite database
|
|
├── run.py # Development server
|
|
├── wsgi.py # Production WSGI entry
|
|
├── Containerfile # Podman/Docker build
|
|
└── requirements.txt # Dependencies
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
- **Input validation** - Paste IDs are hex-only, auth headers validated
|
|
- **MIME sanitization** - Content-Type headers are sanitized
|
|
- **SQL injection protection** - Parameterized queries throughout
|
|
- **Ownership enforcement** - Only owners can delete their pastes
|
|
- **Size limits** - Prevents resource exhaustion attacks
|
|
- **Abuse prevention** - Content-hash deduplication prevents spam flooding
|
|
- **Security headers** - HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Cache-Control
|
|
- **Request tracing** - X-Request-ID for log correlation and debugging
|
|
- **Proxy trust** - Optional `X-Proxy-Secret` validation to prevent header spoofing
|
|
|
|
## License
|
|
|
|
MIT
|