FlaskPaste Roadmap

Current State

FlaskPaste v1.5.0 is deployed with comprehensive security hardening and abuse prevention.

Implemented:

Full REST API (CRUD operations)
Binary content support with magic-byte MIME detection
Client certificate authentication
Minimal PKI (CA generation, certificate issuance, revocation)
Content-hash deduplication (abuse prevention)
Proof-of-work spam prevention
Anti-flood system (dynamic PoW difficulty under load)
IP-based rate limiting with X-RateLimit-* headers
Entropy enforcement (require encrypted uploads)
E2E encryption in CLI (AES-256-GCM, key in URL fragment)
URL prefix support for reverse proxy deployments
/client endpoint for CLI distribution
Automatic paste expiry
Burn-after-read pastes
Custom expiry per paste
Scheduled cleanup (pastes, hashes, rate limits)
Security headers and request tracing
Container deployment support
systemd service unit with security hardening
Security tooling (ruff, bandit, mypy, pip-audit)
CI/CD pipeline with lint, security, and test jobs
CLI with list, search, update, export commands
Public certificate registration (PoW-protected)
CLI register command for certificate enrollment
Comprehensive test suite (284 tests)
PKI audit logging (certificate lifecycle events)
Request duration metrics (Prometheus histogram)
Memory leak detection in CI pipeline

Phase 1: Hardening (Complete)

Focus: Production readiness and operational excellence.

┌───┬─────────────────────────────────┬────────────────────────────────────┐
│ # │ Milestone                       │ Status
├───┼─────────────────────────────────┼────────────────────────────────────┤
│ 1 │ Abuse prevention (dedup)        │ Done
│ 2 │ Security headers complete       │ Done
│ 3 │ Request tracing (X-Request-ID)  │ Done
│ 4 │ Proxy trust validation          │ Done
│ 5 │ Proof-of-work spam prevention   │ Done
│ 6 │ Entropy enforcement             │ Done
│ 7 │ Test coverage > 90%             │ Done (283 tests)
│ 8 │ Documentation complete          │ Done
└───┴─────────────────────────────────┴────────────────────────────────────┘

Phase 2: Operations (Complete)

Focus: Deployment, monitoring, and maintenance tooling.

┌───┬─────────────────────────────────┬────────────────────────────────────┐
│ # │ Milestone                       │ Status
├───┼─────────────────────────────────┼────────────────────────────────────┤
│ 1 │ Prometheus metrics endpoint     │ Done (prometheus-flask-exporter)
│ 2 │ Structured JSON logging         │ Done (production mode)
│ 3 │ Security tooling (lint/scan)    │ Done (ruff, bandit, mypy)
│ 4 │ CI/CD pipeline                  │ Done (Gitea Actions)
│ 5 │ Multi-stage Containerfile       │ Done
└───┴─────────────────────────────────┴────────────────────────────────────┘

Phase 3: Features (Complete)

Focus: User-requested enhancements within scope.

┌───┬─────────────────────────────────┬────────────────────────────────────┐
│ # │ Feature                         │ Status
├───┼─────────────────────────────────┼────────────────────────────────────┤
│ 1 │ E2E encryption (client-side)    │ Done (CLI encrypts by default)
│ 2 │ URL prefix support              │ Done
│ 3 │ Custom expiry per paste         │ Done (X-Expiry header)
│ 4 │ Burn-after-read option          │ Done (X-Burn-After-Read header)
│ 5 │ Minimal PKI (CA + issuance)     │ Done
│ 6 │ Anti-flood (dynamic PoW)        │ Done (v1.4.0)
│ 7 │ IP-based rate limiting          │ Done (v1.4.0)
│ 8 │ Scheduled cleanup               │ Done (v1.4.0)
└───┴─────────────────────────────────┴────────────────────────────────────┘

Anti-Flood System (v1.4.0)

Dynamic proof-of-work difficulty that increases under abuse:

Base difficulty: 20 bits (configurable)
Threshold: 5 requests per 60s window triggers increase
Step: +2 bits per threshold breach
Maximum: 28 bits
Decay: Returns to base after 60s of normal traffic

PKI Features

Integrated certificate authority for mTLS:

POST /pki/ca - Generate CA (first-run bootstrap)
GET /pki/status - CA status and fingerprint
GET /pki/ca.crt - Download CA certificate
POST /pki/issue - Issue client certificate (admin)
POST /pki/revoke/<serial> - Revoke certificate
GET /register/challenge - Get PoW challenge for registration
POST /register - Public certificate registration (PoW-protected)
CLI: fpaste pki status, fpaste pki issue, fpaste pki revoke
CLI: fpaste register - Self-service certificate enrollment

Phase 4: Ecosystem (In Progress)

Focus: Integration with external systems.

┌───┬─────────────────────────────────┬────────────────────────────────────┐
│ # │ Integration                     │ Status
├───┼─────────────────────────────────┼────────────────────────────────────┤
│ 1 │ CLI client (fpaste)             │ Done (with E2E + PKI)
│ 2 │ /client endpoint                │ Done (downloadable CLI)
│ 3 │ systemd service unit            │ Done (with security hardening)
│ 4 │ Ansible deployment role         │ Planned
│ 5 │ Kubernetes manifests            │ Planned
│ 6 │ Shell aliases/functions         │ Planned
└───┴─────────────────────────────────┴────────────────────────────────────┘

CLI Client (Complete)

Standalone Python CLI with encryption, PKI, and paste management:

fpaste file.txt - Create encrypted paste (file path shortcut)
fpaste create -E file.txt - Create unencrypted paste
fpaste get <id> - Get paste (auto-decrypts with URL fragment key)
fpaste delete <id> - Delete paste
fpaste info - Show server info (includes PoW difficulty)
fpaste list - List your pastes
fpaste search --type image/* - Search pastes by type/date
fpaste update <id> - Update paste content/metadata
fpaste export -o dir/ - Export all pastes to directory
fpaste pki status - Show PKI status
fpaste pki issue -n "name" - Request client certificate (admin)
fpaste pki revoke <serial> - Revoke certificate
fpaste register - Self-service certificate registration
fpaste register --configure - Register and auto-configure client
Automatic retry on PoW failure (max 5 attempts)
Config file for server URL and cert fingerprint
Downloadable via curl https://server/client > fpaste

Non-Goals (Explicit)

These features will not be implemented:

Web UI - Out of scope; use API directly
User accounts - PKI handles identity
Syntax highlighting - Client responsibility
Search/discovery - Pastes are private by design
Clustering - Scale via container orchestration
S3/PostgreSQL backend - SQLite is sufficient

Decision Log

Date	Decision	Rationale
2024-11	SQLite only	Simplicity; no external dependencies
2024-11	No web UI	API-first; reduces attack surface
2024-11	Client cert auth	Integrates with existing PKI
2024-12	Content-hash dedup	Prevent spam without IP tracking
2024-12	Proof-of-work	Computational cost deters spam bots
2024-12	Client-side E2E encryption	Zero-knowledge; key in URL fragment
2024-12	Entropy enforcement	Heuristic to require encrypted uploads
2024-12	URL prefix support	Reverse proxy path-based routing
2024-12	Burn-after-read	Single-use pastes for sensitive data
2024-12	Custom expiry	Per-paste TTL override
2024-12	Multi-stage Containerfile	Smaller production images
2024-12	Minimal PKI	Self-contained mTLS without external CA
2024-12	Security tooling (ruff/bandit)	Code quality and security scanning
2024-12	CI/CD with job dependencies	Tests wait for lint to pass
2024-12	Anti-flood dynamic PoW	Adaptive difficulty under attack
2024-12	IP-based rate limiting	Per-IP request throttling
2024-12	Scheduled cleanup (in-process)	No external cron needed
2024-12	CLI encrypt-by-default	Security-first design
2024-12	CLI retry on PoW failure	Graceful handling of stale tokens
2024-12	Public cert registration	Self-service onboarding with PoW protection
2024-12	PKI audit logging	Full certificate lifecycle traceability
2024-12	Request duration metrics	Prometheus histogram for observability
2024-12	Memory leak CI job	tracemalloc-based leak detection in CI
2024-12	systemd service unit	Security-hardened deployment example
2024-12	Rate limit headers	X-RateLimit-* on 201/429 responses

Review Schedule

Monthly: Review TODO.md, refine TASKLIST.md
Quarterly: Evaluate roadmap phases, adjust priorities
Yearly: Major version planning, scope review

11 KiB Raw Blame History