flaskpaste/PROJECT.md

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