update project documentation

README.md

@@ -11,7 +11,12 @@ A lightweight, secure pastebin REST API built with Flask.
 - **Automatic expiry** - Pastes expire after configurable period of inactivity
 - **Size limits** - Configurable limits for anonymous and authenticated users
 - **Abuse prevention** - Content-hash deduplication throttles repeated identical submissions
+- **Entropy enforcement** - Optional minimum entropy requirement to enforce client-side encryption
 - **Proof-of-work** - Configurable computational puzzle prevents automated spam
+- **E2E encryption** - Client-side AES-256-GCM encryption with key in URL fragment (zero-knowledge)
+- **Burn-after-read** - Single-access pastes that auto-delete after first retrieval
+- **Custom expiry** - Per-paste expiry override via X-Expiry header
+- **Password protection** - Optional paste passwords with PBKDF2 hashing
 - **Security headers** - HSTS, CSP, X-Frame-Options, Cache-Control, and more
 - **CLI client** - Standalone `fpaste` command-line tool included
 - **Request tracing** - X-Request-ID support for log correlation
@@ -39,6 +44,7 @@ python run.py
 | `GET /` | API information and usage |
 | `GET /health` | Health check (returns DB status) |
 | `GET /challenge` | Get proof-of-work challenge |
+| `GET /client` | Download fpaste CLI client |
 | `POST /` | Create a new paste |
 | `GET /<id>` | Retrieve paste metadata |
 | `HEAD /<id>` | Retrieve paste metadata (headers only) |
@@ -84,7 +90,17 @@ curl -X DELETE \
 
 ## CLI Client
 
-A standalone command-line client `fpaste` is included (no external dependencies).
+A standalone command-line client `fpaste` is included. For E2E encryption, install the optional `cryptography` package.
+
+### Installation
+
+```bash
+# Download from running server
+curl -sS https://paste.example.com/client > fpaste && chmod +x fpaste
+
+# Optional: enable encryption support
+pip install cryptography
+```
 
 ### Basic Usage
 
@@ -95,9 +111,25 @@ A standalone command-line client `fpaste` is included (no external dependencies)
 # Create paste from stdin
 echo "Hello" | ./fpaste
 
+# Create encrypted paste (E2E, zero-knowledge)
+./fpaste create -e secret.txt
+# Returns: https://paste.example.com/abc123#<key>
+
+# Create burn-after-read paste (single access, auto-deletes)
+./fpaste create -b secret.txt
+
+# Create paste with custom expiry (1 hour)
+./fpaste create -x 3600 temp.txt
+
+# Combine options: encrypted + burn-after-read
+./fpaste create -e -b secret.txt
+
 # Get paste content
 ./fpaste get abc12345
 
+# Get encrypted paste (auto-decrypts if URL has #key fragment)
+./fpaste get "https://paste.example.com/abc123#<key>"
+
 # Get paste metadata
 ./fpaste get -m abc12345
 
@@ -108,6 +140,17 @@ echo "Hello" | ./fpaste
 ./fpaste info
 ```
 
+### End-to-End Encryption
+
+The `-e` flag encrypts content client-side using AES-256-GCM before upload:
+
+- Key is generated locally and never sent to server
+- Key is appended to URL as fragment (`#...`) which browsers never transmit
+- Server stores only opaque ciphertext
+- Retrieval auto-detects `#key` fragment and decrypts locally
+
+This provides true zero-knowledge storage: the server cannot read your content.
+
 ### Configuration
 
 Set server URL and authentication via environment or config file:
@@ -122,6 +165,50 @@ server = https://paste.example.com
 cert_sha1 = your-cert-fingerprint
 ```
 
+### mTLS Client Certificate Authentication
+
+The CLI supports mutual TLS (mTLS) for direct client certificate authentication:
+
+```bash
+# Environment variables
+export FLASKPASTE_CLIENT_CERT="/path/to/client.crt"
+export FLASKPASTE_CLIENT_KEY="/path/to/client.key"
+export FLASKPASTE_CA_CERT="/path/to/ca.crt"  # Optional CA verification
+
+# Or config file (~/.config/fpaste/config)
+client_cert = /path/to/client.crt
+client_key = /path/to/client.key
+ca_cert = /path/to/ca.crt
+```
+
+When client certificates are configured, fpaste performs mTLS authentication directly with the server (or TLS-terminating proxy). This is more secure than header-based authentication as the certificate is validated at the TLS layer.
+
+### Generating Client Certificates
+
+The CLI includes a built-in certificate generator for mTLS authentication:
+
+```bash
+# Generate EC certificate (recommended, fast key generation)
+./fpaste cert
+# Outputs fingerprint to stdout, details to stderr
+
+# Generate and auto-configure fpaste
+./fpaste cert --configure
+# Creates ~/.config/fpaste/client.{crt,key} and updates config
+
+# Custom options
+./fpaste cert -a rsa -b 4096 -d 730 -n "my-client" --configure
+# RSA 4096-bit key, 2-year validity, custom common name
+
+# Supported curves for EC: secp256r1, secp384r1 (default), secp521r1
+./fpaste cert -c secp256r1 --configure
+```
+
+The generated certificate includes:
+- `CLIENT_AUTH` extended key usage for mTLS
+- SHA1 fingerprint compatible with `X-SSL-Client-SHA1` header
+- Self-signed with configurable validity period
+
 ## Configuration
 
 Configuration via environment variables:
@@ -140,6 +227,10 @@ Configuration via environment variables:
 | `FLASKPASTE_POW_DIFFICULTY` | `20` | PoW difficulty (leading zero bits, 0=disabled) |
 | `FLASKPASTE_POW_TTL` | `300` (5 min) | PoW challenge validity period |
 | `FLASKPASTE_POW_SECRET` | (auto) | Secret for signing PoW challenges |
+| `FLASKPASTE_URL_PREFIX` | (empty) | URL prefix for reverse proxy deployments |
+| `FLASKPASTE_MIN_ENTROPY` | `0` | Min entropy bits/byte (0=disabled, 6.0=require encryption) |
+| `FLASKPASTE_MIN_ENTROPY_SIZE` | `256` | Only check entropy for content >= this size |
+| `FLASKPASTE_MAX_EXPIRY` | `2592000` (30 days) | Maximum custom expiry allowed |
 
 ## Authentication
 
@@ -216,6 +307,9 @@ flaskpaste/
 - **Ownership enforcement** - Only owners can delete their pastes
 - **Size limits** - Prevents resource exhaustion attacks
 - **Abuse prevention** - Content-hash deduplication prevents spam flooding
+- **Entropy enforcement** - Optional minimum entropy rejects low-entropy (plaintext) uploads
+- **E2E encryption** - Client-side encryption keeps server zero-knowledge
+- **Burn-after-read** - Single-use pastes for sensitive data
 - **Security headers** - HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Cache-Control
 - **Request tracing** - X-Request-ID for log correlation and debugging
 - **Proxy trust** - Optional `X-Proxy-Secret` validation to prevent header spoofing