chore: prepare release v0.4.0

docs/security.md

@@ -2,7 +2,7 @@
 
 > Status: threat model and security posture for the engine as implemented.
 
-volumen is a small, file-based blog engine: a single Ruby process exposing a
+volumen is a small, file-based blog engine: a single Python process exposing a
 read-only public JSON API and a session-authenticated admin, behind nginx. This
 document describes the trust model, the controls in place, and the known
 limitations.
@@ -13,33 +13,37 @@ than opening a public issue.
 ## Trust model
 
 - **Content authors are trusted.** Posts are written by authenticated admin
-  users. kramdown renders Markdown and **passes raw HTML through** on purpose,
-  so an author can embed HTML. The stored/served `html` is therefore only as
-  safe as the people who can log in. If you need to accept posts from untrusted
-  authors, add an HTML sanitiser before serving.
+  users. python-markdown renders Markdown with a few pymdown-extensions
+  extensions. The engine does **not** strip raw HTML from post bodies by
+  default (authors are the trusted admin); if you need to accept posts from
+  untrusted authors, add a sanitiser (e.g. `bleach`) before serving.
 - **The public API is read-only.** It exposes published (non-draft) posts, tags,
   a feed and a sitemap. No public endpoint mutates state.
 
 ## Authentication
 
-- Passwords are hashed with **scrypt** via `OpenSSL::KDF` (`N=16384`, `r=8`,
+- Passwords are hashed with **scrypt** via `hashlib.scrypt` (`n=16384`, `r=8`,
   `p=1`, 32-byte key, 16-byte random salt). Verification uses
-  `OpenSSL.fixed_length_secure_compare` (constant-time).
+  `secrets.compare_digest` (constant-time) on the derived bytes.
 - Login takes a **username + password**. The error message is intentionally
   generic ("Invalid username or password.") to avoid user enumeration.
-- Sessions use signed cookies (`Rack::Session::Cookie`) marked **`HttpOnly`**
-  and **`SameSite=Strict`**. The **`Secure`** attribute is added automatically on
-  HTTPS requests (detected via `request.ssl?` / `X-Forwarded-Proto`), so the
-  cookie never travels over plain HTTP in production. The signing secret comes
-  from `admin.session_key`; if it is shorter than 64 bytes a random secret is
-  generated per start (sessions then reset on restart, so set a stable key in
-  production).
+- Sessions use **signed cookies** via Starlette's `SessionMiddleware`
+  (`itsdangerous` TimestampSigner under the hood), marked **`HttpOnly`** and
+  **`SameSite=Strict`**. The **`Secure`** attribute is added by
+  `SecureCookieMiddleware` when `X-Forwarded-Proto: https` is observed (only
+  honoured when `[server].trust_proxy = true`) so the cookie never travels
+  over plain HTTP in production while local HTTP testing still works. The
+  signing secret comes from `admin.session_key`; if it is shorter than 64
+  bytes a random secret is generated per start (sessions then reset on
+  restart, so set a stable key in production).
+- A minimum password length of `[admin].min_password_length` (default `10`,
+  must be `>= 8`) is enforced on the Settings page password-change form.
 
 ## Authorization (roles)
 
 - Two roles: **admin** (full access, manages users) and **author** (posts and
   own account only).
-- User management (`add`/`delete`/role change) is gated by `require_admin!`
+- User management (`add`/`delete`/role change) is gated by `require_admin`
   **on the server**, not merely hidden in the UI.
 - Safeguards prevent lockout: the **last admin** cannot be deleted or demoted,
   and a user cannot delete their own account or change their own role.
@@ -47,13 +51,14 @@ than opening a public issue.
 ## CSRF
 
 - Every state-changing form (`POST`) carries a per-session token
-  (`SecureRandom.hex(32)`), validated with `Rack::Utils.secure_compare`.
+  (`secrets.token_hex(32)`), validated with `secrets.compare_digest`.
   Requests without a valid token get `403`.
 - `SameSite=Strict` cookies provide a second, independent layer.
 
 ## Content Security Policy (admin)
 
-All `/admin/*` responses send a strict **Content-Security-Policy** header:
+All `/admin/*` responses send a strict **Content-Security-Policy** header
+(via `CSPMiddleware`):
 
 ```
 default-src 'self';
@@ -66,8 +71,8 @@ form-action 'self';
 frame-ancestors 'none'
 ```
 
-The inline allowances are required by the server-rendered admin (ERB templates
-emit small inline `<script>` blocks and inline `style=""` attributes);
+The inline allowances are required by the server-rendered admin (Jinja2
+templates emit small inline `<script>` blocks and inline `style=""` attributes);
 `frame-ancestors 'none'` prevents clickjacking via iframe embedding. The public
 JSON API does not set a CSP — it returns no HTML, so none is needed.
 
@@ -76,20 +81,19 @@ JSON API does not set a CSP — it returns no HTML, so none is needed.
 - The public read API sends `Access-Control-Allow-Origin: *` (read-only, no
   credentials) so any front-end may consume it. The admin sends **no** CORS
   headers and is same-origin only.
-- `Rack::Protection::HostAuthorization` is disabled (`permitted_hosts: []`)
-  because volumen is intended to run behind nginx, which controls the `Host`
-  header. Do not expose the Puma port directly to the internet.
+- volumen is intended to run behind nginx, which controls the `Host` header.
+  Do not expose the Uvicorn port directly to the internet.
 
 ## File uploads and path traversal
 
 - Uploaded media is stored under `content_dir/media` with a **sanitised,
   randomised** filename (`<hex>-<slug>.<ext>`), so uploads cannot overwrite
   each other or escape the directory.
-- `GET /media/*` resolves names with `File.basename` and an explicit
+- `GET /media/*` resolves names with `Path(...).name` and an explicit
   containment check, so `../` traversal cannot read files outside the media
   directory.
-- Uploads are **rejected (HTTP 413)** when the file exceeds **10 MB**
-  (`MAX_UPLOAD_BYTES`).
+- Uploads are **rejected (HTTP 413)** when the file exceeds the
+  `[admin].max_upload_bytes` ceiling (default **10 MB**, `10485760` bytes).
 - Upload MIME type is **whitelisted** to `image/webp` and `image/avif`
   (`ALLOWED_UPLOAD_TYPES`); anything else returns **HTTP 415** with a
   conversion hint pointing at `cwebp` / `avifenc`. This matches the
@@ -107,21 +111,27 @@ JSON API does not set a CSP — it returns no HTML, so none is needed.
 
 ## Transport
 
-- Bind to `127.0.0.1` and terminate TLS at nginx. The browser ↔ nginx hop is
-  HTTPS; the nginx ↔ Puma hop is local.
+- Bind to `::1` (loopback) and terminate TLS at nginx. The browser ↔ nginx hop
+  is HTTPS; the nginx ↔ Uvicorn hop is local.
 
 ## Dependencies
 
-A small, audited set: `sinatra`, `kramdown` (+ `kramdown-parser-gfm`),
-`toml-rb`, `puma`, `rackup`. Cryptography uses the Ruby standard library
-(`openssl`, `securerandom`).
+A small, audited set declared in `pyproject.toml`:
+
+- Runtime: `fastapi[standard]` (FastAPI, Uvicorn, itsdangerous, Jinja2 transitively),
+  `python-markdown`, `pymdown-extensions`, `tomli-w`, `python-multipart`.
+  (`itsdangerous`, `Jinja2`, and `python-multipart` are pulled in directly
+  too — see `pyproject.toml`.)
+- Crypto: Python standard library (`hashlib`, `secrets`, `hmac`).
+- Dev: `pytest`, `httpx`, `ruff`.
 
 ## Known limitations / non-goals
 
 - **No rate limiting or lockout** on `/admin/login` at the application layer
-  (the engine does have an in-memory rate limiter, but nginx is the durable
-  line of defence — see `docs/deployment.md`). Put nginx `limit_req` in
-  front of it, or use fail2ban, to slow brute-force attempts.
+  beyond an in-memory per-IP sliding window (`MAX_LOGIN_ATTEMPTS = 10` per 60s
+  in `__init__.py`). nginx is the durable line of defence — see
+  `docs/deployment.md`. Put nginx `limit_req` in front of `/admin/login`, or use
+  fail2ban, to slow brute-force attempts.
 - **No 2FA** and **no audit log**.
 - **Raw HTML in posts is trusted** (see the trust model). There is no built-in
-  HTML sanitiser.
+  HTML sanitiser.