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
• Entropy enforcement - Optional minimum entropy requirement to enforce client-side encryption
• Proof-of-work - Configurable computational puzzle prevents automated spam
• E2E encryption - Client-side AES-256-GCM encryption with key in URL fragment (zero-knowledge)
• Burn-after-read - Single-access pastes that auto-delete after first retrieval
• Custom expiry - Per-paste expiry override via X-Expiry header
• Password protection - Optional paste passwords with PBKDF2 hashing
• 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

# 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
GET /client	Download fpaste CLI client
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)

curl --data-binary @file.txt http://localhost:5000/

Create a paste (piped input)

echo "Hello, World!" | curl --data-binary @- http://localhost:5000/

Create a paste (JSON)

curl -H "Content-Type: application/json" \
     -d '{"content":"Hello from JSON!"}' \
     http://localhost:5000/

Retrieve paste metadata

curl http://localhost:5000/abc12345

Retrieve raw content

curl http://localhost:5000/abc12345/raw

Delete a paste (requires authentication)

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. For E2E encryption, install the optional cryptography package.

Installation

# Download from running server
curl -sS https://paste.example.com/client > fpaste && chmod +x fpaste

# Optional: enable encryption support
pip install cryptography

Basic Usage

# Create paste from file (encrypts by default)
./fpaste file.txt
# Returns: https://paste.example.com/abc123#<key>

# Shortcut: file path auto-selects "create" command
./fpaste secret.txt                    # Same as: ./fpaste create secret.txt

# Create paste from stdin
echo "Hello" | ./fpaste

# Disable encryption (upload plaintext)
./fpaste -E file.txt
./fpaste create --no-encrypt file.txt

# Create burn-after-read paste (single access, auto-deletes)
./fpaste -b secret.txt

# Create paste with custom expiry (1 hour)
./fpaste -x 3600 temp.txt

# Combine options: encrypted + burn-after-read
./fpaste -b secret.txt

# Get paste content (auto-decrypts if URL has #key fragment)
./fpaste get "https://paste.example.com/abc123#<key>"

# Get paste metadata
./fpaste get -m abc12345

# Delete paste (requires auth)
./fpaste delete abc12345

# Show server info
./fpaste info

End-to-End Encryption

Content is encrypted by default using AES-256-GCM before upload:

• Key is generated locally and never sent to server
• Key is appended to URL as fragment (#...) which browsers never transmit
• Server stores only opaque ciphertext
• Retrieval auto-detects #key fragment and decrypts locally
• Use -E or --no-encrypt to disable encryption

This provides true zero-knowledge storage: the server cannot read your content.

Configuration

Set server URL and authentication via environment or config file:

# 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

mTLS Client Certificate Authentication

The CLI supports mutual TLS (mTLS) for direct client certificate authentication:

# Environment variables
export FLASKPASTE_CLIENT_CERT="/path/to/client.crt"
export FLASKPASTE_CLIENT_KEY="/path/to/client.key"
export FLASKPASTE_CA_CERT="/path/to/ca.crt"  # Optional CA verification

# Or config file (~/.config/fpaste/config)
client_cert = /path/to/client.crt
client_key = /path/to/client.key
ca_cert = /path/to/ca.crt

When client certificates are configured, fpaste performs mTLS authentication directly with the server (or TLS-terminating proxy). This is more secure than header-based authentication as the certificate is validated at the TLS layer.

Generating Client Certificates

The CLI includes a built-in certificate generator for mTLS authentication:

# Generate EC certificate (recommended, fast key generation)
./fpaste cert
# Outputs fingerprint to stdout, details to stderr

# Generate and auto-configure fpaste
./fpaste cert --configure
# Creates ~/.config/fpaste/client.{crt,key} and updates config

# Custom options
./fpaste cert -a rsa -b 4096 -d 730 -n "my-client" --configure
# RSA 4096-bit key, 2-year validity, custom common name

# Supported curves for EC: secp256r1, secp384r1 (default), secp521r1
./fpaste cert -c secp256r1 --configure

The generated certificate includes:

• CLIENT_AUTH extended key usage for mTLS
• SHA1 fingerprint compatible with X-SSL-Client-SHA1 header
• Self-signed with configurable validity period

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
FLASKPASTE_URL_PREFIX	(empty)	URL prefix for reverse proxy deployments
FLASKPASTE_MIN_ENTROPY	0	Min entropy bits/byte (0=disabled, 6.0=require encryption)
FLASKPASTE_MIN_ENTROPY_SIZE	256	Only check entropy for content >= this size
FLASKPASTE_MAX_EXPIRY	2592000 (30 days)	Maximum custom expiry allowed

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:

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

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 wsgi:app

Using Podman/Docker

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

pip install pytest pytest-cov
pytest tests/ -v

Test Coverage

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
• Entropy enforcement - Optional minimum entropy rejects low-entropy (plaintext) uploads
• E2E encryption - Client-side encryption keeps server zero-knowledge
• Burn-after-read - Single-use pastes for sensitive data
• 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