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