flaskpaste/ROADMAP.md

FlaskPaste Roadmap

Current State

FlaskPaste v1.4.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 (configurable per-IP limits)
• 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
• Security tooling (ruff, bandit, mypy, pip-audit)
• CI/CD pipeline with lint, security, and test jobs
• CLI with list, search, update, export commands
• Comprehensive test suite (205 tests)

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 (205 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
• POST /pki/revoke/<serial> - Revoke certificate
• CLI: fpaste pki status, fpaste pki issue, fpaste pki revoke

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 │ Ansible deployment role         │ Planned
│ 4 │ Kubernetes manifests            │ Planned
│ 5 │ 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
• fpaste pki revoke <serial> - Revoke certificate
• 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

Review Schedule

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