forked from username/flaskpaste
217 lines
12 KiB
Markdown
217 lines
12 KiB
Markdown
# FlaskPaste Roadmap
|
|
|
|
## Current State
|
|
|
|
FlaskPaste v1.5.1 is deployed with comprehensive security hardening and abuse prevention.
|
|
|
|
**Implemented:**
|
|
- Full REST API (CRUD operations)
|
|
- Binary content support with text/binary 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
|
|
- URL shortener (create, redirect, info, delete, list)
|
|
- Comprehensive test suite (346 tests)
|
|
- Complete security pentest remediation (15 items)
|
|
- 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 (346 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)
|
|
│ 9 │ URL shortener │ Done (v1.6.0)
|
|
└───┴─────────────────────────────────┴────────────────────────────────────┘
|
|
```
|
|
|
|
### URL Shortener (v1.6.0)
|
|
|
|
Short URL creation, redirect, metadata, and management:
|
|
- `POST /s` - Create short URL (PoW + rate limit)
|
|
- `GET /s` - List own short URLs (auth required)
|
|
- `GET /s/<id>` - 302 redirect to target
|
|
- `GET /s/<id>/info` - JSON metadata (target, clicks, expiry)
|
|
- `DELETE /s/<id>` - Delete (owner only)
|
|
- Open redirect prevention (http/https only, netloc required)
|
|
- 8-char base62 IDs (visually distinct from paste hex IDs)
|
|
|
|
### 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 download`
|
|
- 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 │ Done
|
|
│ 6 │ CI/CD image build/push │ Done
|
|
│ 7 │ 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"` - Issue client certificate (admin)
|
|
- `fpaste pki download` - Download CA 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
|
|
| 2024-12 | Pentest remediation complete | 15 security hardening items from formal review
|
|
| 2024-12 | Enhanced CI security | SBOM generation, dedicated security-tests job
|
|
| 2025-01 | CI/CD image build/push | Auto-build on main, push to Harbor registry
|
|
| 2026-02 | URL shortener | /s/ prefix avoids paste ID collision; base62 IDs
|
|
| 2026-02 | Open redirect prevention | http/https only, netloc required, 2048 byte limit
|
|
|
|
## Review Schedule
|
|
|
|
- **Monthly**: Review TODO.md, refine TASKLIST.md
|
|
- **Quarterly**: Evaluate roadmap phases, adjust priorities
|
|
- **Yearly**: Major version planning, scope review
|