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
Provides optional built-in PKI for certificate management
Automatically expires content based on access patterns
Prevents abuse through content-hash deduplication and proof-of-work
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
│                                │ Security scanning in CI (bandit)
├────────────────────────────────┼────────────────────────────────────────────┤
│ 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
│                                │ Prometheus metrics endpoint
└────────────────────────────────┴────────────────────────────────────────────┘

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)
Built-in PKI (CA generation, certificate issuance, revocation)
Configurable size limits (anon vs authenticated)
Time-based expiry with access-touch semantics
Content-hash deduplication for abuse prevention
Proof-of-work spam prevention
Entropy enforcement for encrypted content
Client-side E2E encryption (CLI)
Burn-after-read pastes
Custom expiry per paste
URL shortener with open redirect prevention
URL prefix for reverse proxy deployments
Security headers (HSTS, CSP, X-Frame-Options, etc.)
Request tracing and structured logging
Container deployment support
SQLite storage
CI/CD with security scanning

Out of Scope

Web UI / HTML frontend
User registration / account management
Syntax highlighting
Paste forking / versioning
Public paste listing / discovery
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 or via built-in PKI
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
│ Linting         │ ruff, mypy
│ Security        │ bandit, pip-audit
│ CI/CD           │ Gitea Actions
│ Python          │ 3.11+
└─────────────────┴──────────────────────────────────────────────────────────┘

Current Status

Version: 1.6.0

┌─────────────────────────────────┬────────────────────────────────────────────┐
│ Feature                         │ Status
├─────────────────────────────────┼────────────────────────────────────────────┤
│ Core API (CRUD)                 │ Complete
│ Binary content support          │ Complete
│ MIME detection                  │ Complete
│ Client cert authentication      │ Complete
│ Built-in PKI                    │ Complete
│ Size limits                     │ Complete
│ Paste expiry                    │ Complete
│ Content-hash deduplication      │ Complete
│ Proof-of-work                   │ Complete
│ Anti-flood (dynamic PoW)        │ Complete
│ IP-based rate limiting          │ Complete (with X-RateLimit-* headers)
│ URL prefix support              │ Complete
│ /client endpoint                │ Complete
│ E2E encryption (CLI)            │ Complete
│ Entropy enforcement             │ Complete
│ Burn-after-read                 │ Complete
│ Custom expiry                   │ Complete
│ Security headers                │ Complete
│ Request tracing                 │ Complete
│ Container deployment            │ Complete
│ Security tooling                │ Complete
│ CI/CD pipeline                  │ Complete
│ Scheduled cleanup               │ Complete
│ CLI paste listing/search        │ Complete
│ Public certificate registration │ Complete
│ CLI register command            │ Complete
│ systemd deployment              │ Complete (security-hardened)
│ Test suite                      │ 346 tests passing
│ Kubernetes deployment           │ Complete (k3s, NodePort :30500)
│ Harbor registry integration     │ Complete (CI/CD + Trivy scanning)
│ URL shortener                   │ Complete (8-char base62, redirect, info)
└─────────────────────────────────┴────────────────────────────────────────────┘

8.6 KiB Raw Permalink Blame History