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+
└─────────────────┴──────────────────────────────────────────────────────────┘

5.6 KiB Raw Blame History