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