From 028367d803ce6cfd0907ceecdedcbdd3266cff54 Mon Sep 17 00:00:00 2001 From: Username Date: Sun, 21 Dec 2025 22:36:48 +0100 Subject: [PATCH] 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 | 63 ++++++++++++++++++++++++-------------------- documentation/api.md | 7 ++--- 2 files changed, 39 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index caea0c8..003dd1f 100644 --- a/README.md +++ b/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) -- **Client certificate authentication** - Optional auth via `X-SSL-Client-SHA1` header -- **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 -- **Anti-flood** - Dynamic PoW difficulty increases under attack, decays when abuse stops -- **Rate limiting** - Per-IP request throttling with auth user multiplier -- **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 -- **Proxy trust validation** - Optional shared secret for defense-in-depth -- **Minimal dependencies** - Flask only, SQLite built-in +- **Automatic MIME detection** - Magic byte detection (PNG, JPEG, GIF, WebP, ZIP, PDF, GZIP) +- **Client certificate authentication** - mTLS or header-based via reverse proxy +- **Tiered expiry** - 1 day (anon), 7 days (untrusted), 30 days (trusted PKI) +- **Size limits** - 3 MiB anonymous, 50 MiB authenticated +- **Abuse prevention** - Content-hash deduplication throttles spam +- **Proof-of-work** - Computational puzzles prevent automated abuse +- **Anti-flood** - Dynamic PoW difficulty increases under attack +- **Rate limiting** - Per-IP throttling with auth multiplier +- **E2E encryption** - Client-side AES-256-GCM with key in URL fragment +- **Burn-after-read** - Single-access pastes that auto-delete +- **Password protection** - PBKDF2-HMAC-SHA256 with 600k iterations +- **Built-in PKI** - Certificate authority for client certificate issuance +- **Admin support** - First registered user can manage all pastes +- **Security headers** - HSTS, CSP, X-Frame-Options, X-Content-Type-Options +- **CLI client** - Standalone `fpaste` tool with encryption support +- **Request tracing** - X-Request-ID for log correlation +- **Minimal dependencies** - Flask + SQLite, optional cryptography for CLI ## Quick Start @@ -53,8 +52,11 @@ python run.py | `GET //raw` | Retrieve raw paste content | | `HEAD //raw` | Retrieve paste headers (no body) | | `DELETE /` | 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 -- **E2E encryption** - Client-side encryption keeps server zero-knowledge +- **Entropy enforcement** - Optional minimum entropy rejects plaintext uploads +- **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 -- **Request tracing** - X-Request-ID for log correlation and debugging -- **Proxy trust** - Optional `X-Proxy-Secret` validation to prevent header spoofing +- **Password protection** - PBKDF2-HMAC-SHA256 with 600k iterations +- **Security headers** - HSTS, CSP, X-Frame-Options, X-Content-Type-Options +- **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 diff --git a/documentation/api.md b/documentation/api.md index 62a24d6..78b59a3 100644 --- a/documentation/api.md +++ b/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: |--------|-------| | `X-Content-Type-Options` | `nosniff` | | `X-Frame-Options` | `DENY` | -| `X-XSS-Protection` | `1; mode=block` | | `Referrer-Policy` | `strict-origin-when-cross-origin` | | `Content-Security-Policy` | `default-src 'none'; frame-ancestors 'none'` | | `Permissions-Policy` | `geolocation=(), microphone=(), camera=()` |