docs: modernize and clean deprecated content

- replace deprecated FLASK_ENV with FLASK_DEBUG
- remove duplicate FLASKPASTE_MAX_EXPIRY entry
- update API version to 1.5.0
- add missing /pastes and /pki endpoints to table
- remove deprecated X-XSS-Protection header
- add PKI config variables
- update features list with current capabilities
- update auth benefits and security sections

README.md

@@ -4,26 +4,25 @@ A lightweight, secure pastebin REST API built with Flask.
 
 ## Features
 
-- **Simple REST API** - Create, retrieve, and delete pastes via HTTP
+- **Simple REST API** - Create, retrieve, list, and delete pastes via HTTP
 - **Binary support** - Upload text, images, archives, and other binary content
-- **Automatic MIME detection** - Magic byte detection for common formats (PNG, JPEG, GIF, WebP, ZIP, PDF, GZIP)
+- **Automatic MIME detection** - Magic byte detection (PNG, JPEG, GIF, WebP, ZIP, PDF, GZIP)
-- **Client certificate authentication** - Optional auth via `X-SSL-Client-SHA1` header
+- **Client certificate authentication** - mTLS or header-based via reverse proxy
-- **Automatic expiry** - Pastes expire after configurable period of inactivity
+- **Tiered expiry** - 1 day (anon), 7 days (untrusted), 30 days (trusted PKI)
-- **Size limits** - Configurable limits for anonymous and authenticated users
+- **Size limits** - 3 MiB anonymous, 50 MiB authenticated
-- **Abuse prevention** - Content-hash deduplication throttles repeated identical submissions
+- **Abuse prevention** - Content-hash deduplication throttles spam
-- **Entropy enforcement** - Optional minimum entropy requirement to enforce client-side encryption
+- **Proof-of-work** - Computational puzzles prevent automated abuse
-- **Proof-of-work** - Configurable computational puzzle prevents automated spam
+- **Anti-flood** - Dynamic PoW difficulty increases under attack
-- **Anti-flood** - Dynamic PoW difficulty increases under attack, decays when abuse stops
+- **Rate limiting** - Per-IP throttling with auth multiplier
-- **Rate limiting** - Per-IP request throttling with auth user multiplier
+- **E2E encryption** - Client-side AES-256-GCM with key in URL fragment
-- **E2E encryption** - Client-side AES-256-GCM encryption with key in URL fragment (zero-knowledge)
+- **Burn-after-read** - Single-access pastes that auto-delete
-- **Burn-after-read** - Single-access pastes that auto-delete after first retrieval
+- **Password protection** - PBKDF2-HMAC-SHA256 with 600k iterations
-- **Custom expiry** - Per-paste expiry override via X-Expiry header
+- **Built-in PKI** - Certificate authority for client certificate issuance
-- **Password protection** - Optional paste passwords with PBKDF2 hashing
+- **Admin support** - First registered user can manage all pastes
-- **Security headers** - HSTS, CSP, X-Frame-Options, Cache-Control, and more
+- **Security headers** - HSTS, CSP, X-Frame-Options, X-Content-Type-Options
-- **CLI client** - Standalone `fpaste` command-line tool included
+- **CLI client** - Standalone `fpaste` tool with encryption support
-- **Request tracing** - X-Request-ID support for log correlation
+- **Request tracing** - X-Request-ID for log correlation
-- **Proxy trust validation** - Optional shared secret for defense-in-depth
+- **Minimal dependencies** - Flask + SQLite, optional cryptography for CLI
-- **Minimal dependencies** - Flask only, SQLite built-in
 
 ## Quick Start
 
@@ -53,8 +52,11 @@ python run.py
 | `GET /<id>/raw` | Retrieve raw paste content |
 | `HEAD /<id>/raw` | Retrieve paste headers (no body) |
 | `DELETE /<id>` | Delete paste (requires auth) |
+| `GET /pastes` | List user's pastes (requires auth) |
 | `GET /register/challenge` | Get PoW challenge for registration |
-| `POST /register` | Register and get client certificate (PKCS#12) |
+| `POST /register` | Register and get client certificate |
+| `GET /pki` | PKI status and CA info |
+| `GET /pki/ca.crt` | Download CA certificate |
 
 ## Usage Examples
 
@@ -250,7 +252,7 @@ Configuration via environment variables:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `FLASK_ENV` | `development` | Environment (`development`, `production`, `testing`) |
+| `FLASK_DEBUG` | `0` | Enable debug mode (`1` = enabled) |
 | `FLASKPASTE_DB` | `./data/pastes.db` | SQLite database path |
 | `FLASKPASTE_ID_LENGTH` | `12` | Paste ID length (hex characters) |
 | `FLASKPASTE_MAX_ANON` | `3145728` (3 MiB) | Max paste size for anonymous users |
@@ -279,7 +281,9 @@ Configuration via environment variables:
 | `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 |
+| `FLASKPASTE_PKI_ENABLED` | `0` | Enable PKI certificate authority |
+| `FLASKPASTE_PKI_CA_PASSWORD` | (empty) | CA password (required when PKI enabled) |
+| `FLASKPASTE_PKI_CERT_DAYS` | `365` | Client certificate validity (days) |
 
 ## Authentication
 
@@ -368,15 +372,18 @@ flaskpaste/
 - **Input validation** - Paste IDs are hex-only, auth headers validated
 - **MIME sanitization** - Content-Type headers are sanitized
 - **SQL injection protection** - Parameterized queries throughout
-- **Ownership enforcement** - Only owners can delete their pastes
+- **Ownership enforcement** - Only owners (or admins) can delete 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
+- **Entropy enforcement** - Optional minimum entropy rejects plaintext uploads
-- **E2E encryption** - Client-side encryption keeps server zero-knowledge
+- **E2E encryption** - Client-side AES-256-GCM, server is zero-knowledge
 - **Burn-after-read** - Single-use pastes for sensitive data
-- **Security headers** - HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Cache-Control
+- **Password protection** - PBKDF2-HMAC-SHA256 with 600k iterations
-- **Request tracing** - X-Request-ID for log correlation and debugging
+- **Security headers** - HSTS, CSP, X-Frame-Options, X-Content-Type-Options
-- **Proxy trust** - Optional `X-Proxy-Secret` validation to prevent header spoofing
+- **Proof-of-work** - Computational puzzles prevent automated spam
+- **Rate limiting** - Per-IP throttling with auth multiplier
+- **Request tracing** - X-Request-ID for log correlation
+- **PKI support** - Built-in CA for client certificate issuance
 
 ## License
 

documentation/api.md

@@ -22,7 +22,9 @@ The fingerprint must be exactly 40 lowercase hexadecimal characters (SHA1).
 
 **Benefits of authentication:**
 - Larger upload limit (50 MiB vs 3 MiB)
-- Ability to delete owned pastes
+- Longer default expiry (7-30 days vs 1 day)
+- Ability to list and delete owned pastes
+- Register via PKI for trusted status and admin eligibility
 
 ---
 
@@ -120,7 +122,7 @@ Host: localhost:5000
 ```json
 {
   "name": "FlaskPaste",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "endpoints": {
     "GET /": "API information",
     "GET /health": "Health check",
@@ -795,7 +797,6 @@ All responses include the following security headers:
 | `Cache-Control` | `no-store, no-cache, must-revalidate, private` |
 | `Pragma` | `no-cache` |
 
-
 ---
 
 ## Request Tracing