update project documentation

This commit is contained in:
Username
2025-12-20 17:20:40 +01:00
parent 713052de3d
commit 260d6e894d
5 changed files with 197 additions and 50 deletions

View File

@@ -2,19 +2,24 @@
## Current State
FlaskPaste v1.0 is feature-complete for its core mission: a secure, minimal pastebin API.
FlaskPaste v1.1.0 is deployed and feature-complete for its core mission: a secure, minimal pastebin API with zero-knowledge encryption support.
**Implemented:**
- Full REST API (CRUD operations)
- Binary content support with magic-byte MIME detection
- Client certificate authentication
- Content-hash deduplication (abuse prevention)
- Proof-of-work spam prevention
- 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
- Security headers and request tracing
- Container deployment support
- Comprehensive test suite
- Comprehensive test suite (98 tests)
## Phase 1: Hardening (Current)
## Phase 1: Hardening (Complete)
Focus: Production readiness and operational excellence.
@@ -22,12 +27,14 @@ Focus: Production readiness and operational excellence.
┌───┬─────────────────────────────────────┬────────────────────────────────────┐
│ # │ Milestone │ Status
├───┼─────────────────────────────────────┼────────────────────────────────────┤
│ 1 │ Abuse prevention (dedup) │ Implemented (pending commit)
│ 1 │ Abuse prevention (dedup) │ Done
│ 2 │ Security headers complete │ Done
│ 3 │ Request tracing (X-Request-ID) │ Done
│ 4 │ Proxy trust validation │ Done
│ 5 │ Test coverage > 90% │ In progress
│ 6 │ Documentation completeIn progress
│ 5 │ Proof-of-work spam prevention │ Done
│ 6 │ Entropy enforcement Done
│ 7 │ Test coverage > 90% │ Done (98 tests)
│ 8 │ Documentation complete │ Done
└───┴─────────────────────────────────────┴────────────────────────────────────┘
```
@@ -64,19 +71,19 @@ Replace text logs with JSON format:
- Consistent field names across all log entries
- Compatible with log aggregation (Loki, ELK)
## Phase 3: Features
## Phase 3: Features (Complete)
Focus: User-requested enhancements within scope.
```
┌───┬─────────────────────────────────────┬────────────────────────────────────┐
│ # │ Feature │ Complexity
│ # │ Feature │ Status
├───┼─────────────────────────────────────┼────────────────────────────────────┤
│ 1 │ Paste encryption (server-side) │ Medium
│ 2 │ Custom expiry per pasteLow
│ 3 │ Paste size in response headers │ Low
│ 4 │ Burn-after-read option │ Low
│ 5 │ Paste password protection │ Medium
│ 1 │ E2E encryption (client-side) │ Done (CLI -e flag, zero-knowledge)
│ 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 │ Paste password protection │ Planned
└───┴─────────────────────────────────────┴────────────────────────────────────┘
```
@@ -100,23 +107,26 @@ Focus: Integration with external systems.
```
┌───┬─────────────────────────────────────┬────────────────────────────────────┐
│ # │ Integration │ Purpose
│ # │ Integration │ Status
├───┼─────────────────────────────────────┼────────────────────────────────────┤
│ 1 │ CLI client (fpaste) │ User convenience
│ 2 │ Neovim/Vim pluginEditor integration
│ 3 │ Shell aliases/functions │ Workflow integration
│ 4 │ Webhook notifications │ Automation triggers
│ 1 │ CLI client (fpaste) │ Done (with E2E encryption)
│ 2 │ /client endpoint Done (downloadable CLI)
│ 3 │ Neovim/Vim plugin │ Planned
│ 4 │ Shell aliases/functions │ Planned
│ 5 │ Webhook notifications │ Planned
└───┴─────────────────────────────────────┴────────────────────────────────────┘
```
### CLI Client
### CLI Client (Complete)
Standalone Python CLI:
- `fpaste < file.txt` - Create paste from stdin
- `fpaste file.txt` - Create paste from file
- `fpaste -g <id>` - Get paste
- `fpaste -d <id>` - Delete paste
- Config file for server URL and cert path
Standalone Python CLI with encryption support:
- `fpaste create file.txt` - Create paste from file
- `fpaste create -e file.txt` - Create encrypted paste (E2E)
- `fpaste get <id>` - Get paste (auto-decrypts with URL fragment key)
- `fpaste delete <id>` - Delete paste
- `fpaste info` - Show server info
- Config file for server URL and cert fingerprint
- Downloadable via `curl https://server/client > fpaste`
## Non-Goals (Explicit)
@@ -137,6 +147,13 @@ These features will not be implemented:
| 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
## Review Schedule