volumen/CHANGELOG.md

Changelog

All notable changes to volumen are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Versions ≤ 0.3.0 were implemented in Ruby. The current codebase is Python (FastAPI). Earlier release notes are kept verbatim as historical record.

[development]

[0.4.2] — 2026-07-27

Fixed

• web/templates/*.jinja missing from distribution wheel — added web/templates/*.jinja to [tool.setuptools.package-data] in pyproject.toml. After a fresh install from PyPI the admin panel returned 500 because Jinja2Templates could not find any templates.
• Duplicate script-src / style-src in admin CSP — the nonce-augmented directives used to be appended after the base ones, so the browser (which honours the first occurrence) ignored the nonce and blocked every inline JS/CSS. They are now replaced: script-src and style-src are filtered out of the base CSP and the nonce versions are appended as the only occurrence.
• CSP nonce generated after template rendering — request.state.csp_nonce is now set in GlobalSecurityHeadersMiddleware.dispatch() before call_next(request) so templates see it during rendering. Previously it was generated afterwards, so csp_nonce was an empty string in the template context and every inline script was blocked.
• Missing nonce attribute on <script> in list.html.jinja and settings.html.jinja — inline scripts in these templates now carry nonce="{{ csp_nonce | default('') }}" so they match the nonce in the CSP header.
• Bootstrap admin.password_hash ignored when users.toml is empty — Users.all now falls back to the bootstrap admin even when users.toml exists but is empty (e.g. right after volumen init, which creates the file via Path.touch()). Previously the first login after a clean install failed.
• admin_context did not pass users_exist — the login page showed the “No users configured” warning even when authentication worked. Added "users_exist": users_obj.any to the admin template context.
• Inline style="..." blocked by strict admin CSP — the admin templates used inline style="..." attributes (and one card.style.display = ... JS assignment) which the new strict style-src 'self' 'nonce-…' directive blocks. Replaced every offending attribute with a utility class in the <style> block (page-head-actions, form-options, form-inline, form-hidden, form-spaced, flex-spacer, btn-static, btn-danger-text, text-fg-strong, badge-inline, h3-section, mt-3, is-hidden); the dynamic background-image: url(...) on .post-cover now flows through a --cover-url custom property (style="--cover-url: …") which CSP3 does not treat as an inline style application.
• /favicon.ico returned 404 — browsers auto-request /favicon.ico even when the page declares an explicit <link rel="icon">. Added a tiny route in create_app() that serves the packaged web/static/volumen-icon.svg with Content-Type: image/svg+xml and a 1-day Cache-Control; added the matching <link rel="icon" type="image/svg+xml" href="/favicon.ico"> to the admin layout so the tab gets the volumen icon instead of a generic placeholder.
• Sidebar version label rendered as bare v — admin_context did not include the package VERSION, so the footer <div class="sidebar-version">v{{ version }}</div> rendered as just v with no number behind it. Added "version": VERSION to the context.

[0.4.1] — 2026-07-27

Fixed

• Missing CSP nonce for style-src on admin routes — added style-src 'self' 'nonce-{nonce}' to the CSP header on /admin routes. Without a nonce the browser blocked every inline <style> tag in the admin templates.
• web/static/ SVG assets missing from distribution wheel — added a [tool.setuptools.package-data] section to pyproject.toml so volumen-icon.svg and volumen-logo.svg ship inside the installed wheel. The admin panel previously returned 500 on /admin/icon.svg and /admin/logo.svg.

[0.4.0] — 2026-07-26

Added

• volumen init — a new init subcommand is the operational bootstrap (config, data dirs, admin password, optional systemd unit). Run as root for a system install (default --systemd); pass --local for a per-user install (~/.config/volumen/, ~/.local/share/volumen/). The command renders the production-hardened config from the same commented TOML template (host = "::1", env = "production", trust_proxy = true, cookie_secure = true), prompts for an admin password (getpass), hashes it via the existing scrypt helper, generates a 64-byte hex session key, creates the system user (useradd --system) and the /etc/volumen/ / /var/lib/volumen/ layout, and (with --systemd) installs a hardened /etc/systemd/system/volumen.service and runs systemctl daemon-reload && systemctl enable --now.
• PyPI publish metadata — pyproject.toml gains readme, keywords, a complete classifiers array (Development Status, Framework :: FastAPI, supported Python versions, OS, Topic, Typing), and a [project.urls] block (Homepage, Repository, Issues, Changelog, Documentation). PyPI now renders the README on the project page and links back to sourcedock.dev.
• volumen status — read-only inspection of an installation. Prints human output by default or --json for tooling; reports config_exists, data_dir_exists, users_file_exists, password_hash_set, session_key_ok, systemd_unit_installed, service_active, admin_user_present, and any issues found. Exit code is 1 when any issue is reported.
• volumen check-update — compares the installed version (read via importlib.metadata) with the latest release on PyPI. Uses only urllib.request (stdlib, 5 s timeout); exit code is 0 up-to-date, 1 update available (suggests uv tool upgrade volumen), 2 PyPI unreachable / offline / malformed response. --json returns the same fields plus checked_at for cron-friendly alerting.
• src/volumen/installer.py — a new module exposing system_install, user_install, inspect, plus the private _mutate_config_text helper used to apply line-anchored substitutions to the rendered TOML template (preserves comment blocks byte-for-byte).
• Tests — tests/test_installer.py adds 15 tests covering both install flows, the config-template mutator, the systemd-unit rendering, idempotency / backup behaviour, the inspect round-trip, and the --systemd + --local CLI guard.

Changed

• First-run setup is now volumen init — replaces the legacy install.sh. The CLI subcommand renders config, creates data dirs, prompts for an admin password, generates a session key, and (with --systemd) installs and enables a hardened systemd unit. No bash required.
• Publishing now targets PyPI — release.yml runs uv publish --token "$PYPI_TOKEN" after python -m build for v* tags. Wheel + sdist continue to be uploaded to sourcedock.dev Releases as a secondary mirror. End users get uv tool install volumen and pipx install volumen as the one-line install path; no checkout required.
• Distribution path is uv tool install (or pipx install) — the CLI binary is installed globally; the operational bootstrap is delegated to volumen init. The legacy uv sync + project-local venv at /opt/volumen/.venv is gone.
• Config.load round-trips config-file content_dir / users_file — the rendered template places these two keys after the [server] header, so TOML table folding puts them inside [server]. Config.load now hoists them to the root so files produced by volumen init (and any hand-edited config) round-trip through the canonical accessors without relying on CLI overrides.
• Migrated from Ruby to Python: the runtime has been rewritten on top of FastAPI + Uvicorn, replacing Sinatra with FastAPI, kramdown with python-markdown + pymdown-extensions, Puma with Uvicorn, Bundler with uv, minitest with pytest, RuboCop with Ruff, and the TOML parser (toml-rb) with the standard library tomllib (plus tomli-w for round-tripping edits). The public API (/api/volumen/*) and the server-rendered admin (/admin/*) keep the same shape and HTTP semantics.
• Installer — install.sh now bootstraps uv instead of Bundler, runs uv sync --frozen to provision /opt/volumen/.venv, and points the systemd ExecStart at the venv-resident volumen console script. The Python runtime is auto-installed on Fedora/openEuler; other distros get a heredoc with the equivalent apt / pacman / zypper / apk lines.
• CI — Forgejo Actions moved to setup-uv + Ruff + pytest on a single Python 3.12 job (was: Ruby 3.3/3.4 matrix with Bundler, RuboCop, and bundle exec rake test). The release workflow builds wheel + sdist via python -m build and uploads them with the Forgejo Releases API.
• Migration guard — new .forgejo/workflows/migration-guard.yml greps the tracked tree for Ruby-only terms (bundle exec, RuboCop, Sinatra, Puma, kramdown, gem build, Volumen::, Rack::Session::Cookie, OpenSSL::KDF, lib/volumen/) and fails the build if any of them leak back into production paths.
• Configuration — config.toml gains six new keys surfaced in config.toml.example: [server].env ("production" enables strict startup), [server].trust_proxy (honour X-Forwarded-Proto from nginx), [admin].min_password_length (default 10), [admin].max_password_length (default 1024, caps scrypt work), [admin].max_upload_bytes (default 10485760, 10 MB), and [admin].cookie_secure (default false in dev, set true behind HTTPS). See docs/configuration.md for the full schema.
• Default bind address — the installer and config.toml.example default to host = "::" (IPv6 with automatic IPv4 fallback) so the service is reachable on both stacks out of the box. Bind to "::1" when running behind a reverse proxy.
• Test client now uses httpx2 — dev dependencies replace httpx>=0.28 with httpx2>=2.7 (the actively maintained fork by Pydantic). Starlette 1.3.x prefers httpx2 in TestClient and emits StarletteDeprecationWarning when only legacy httpx is installed; shipping httpx2 keeps the test suite warning-free. The legacy httpx package is still pulled in via fastapi[standard] for the fastapi CLI and remains API-compatible. The unused ignore::DeprecationWarning:starlette.testclient filter is removed from [tool.pytest.ini_options] (it targeted the wrong warning class and never matched).

Removed

• install.sh — the bash installer is deleted. Use uv tool install volumen (or pipx install volumen) followed by volumen init.
• pkg/ build output and volumen.gem (Ruby gem packaging is gone; the project now ships as a wheel + sdist built with python -m build).
• Gemfile, volumen.gemspec, Rakefile, .rubocop.yml and the Sinatra-era lib/ tree.
• .editorconfig — Ruff (pyproject.toml's [tool.ruff]) is the single source of truth for Python formatting; modern editors default to UTF-8, LF, and a trailing newline. Markdown files in this repo use blank lines between paragraphs (no \n line-break idiom), so trimming trailing whitespace is safe.

Security

• scrypt password hashing now uses hashlib.scrypt and constant-time verification via secrets.compare_digest (was: Ruby's OpenSSL::KDF).
• Session cookies are signed by Starlette's SessionMiddleware (itsdangerous) with HttpOnly and SameSite=Strict; Secure is added by SecureCookieMiddleware when the request was forwarded over HTTPS (only when [server].trust_proxy = true).
• CSRF tokens are generated with secrets.token_hex(32) and verified with secrets.compare_digest on every state-changing admin POST.
• Markdown sanitisation policy — the renderer still passes inline HTML through (authors are the trusted admin); document the trust model explicitly in docs/security.md so deployments that ingest untrusted content know to add a sanitiser.

Note: refine the Security bullets above once the Python agent confirms the final cryptographic controls (e.g. whether image/* upload signatures get re-validated server-side and whether the CSRF token is rotated on login).

[0.3.0] — 2026-07-12

Added

Content & authoring

• Fediverse attribution: a fediverse_creator frontmatter field (e.g. @user@mastodon.social) plus a site-wide [site].fediverse_creator default in config.toml. The value is exposed as fediverse_creator on the site and post payloads, rendered as <dc:creator> in the RSS feed, as authors[].name in the JSON feed, and can be consumed by a front-end to emit <meta name="fediverse:creator"> on rendered pages. Per-post values override the site default.
• Cover caption: a cover_caption post field rendered next to the cover image so authors can credit photos or add a short blurb.
• Titled images as <figure>: Markdown images with a title (![alt](url "caption")) are wrapped in a <figure> with a <figcaption> and a small i info icon. Images without a title render exactly as before.

Public API

• has_next and has_prev boolean flags in the paginated /api/volumen/posts response so clients can navigate pages without computing boundaries themselves.
• Distinct "draft" error code in /api/volumen/posts/:slug when the post exists but is a draft, replacing the generic "not_found".

Admin

• Modern admin UI: redesigned layout with a sticky top bar, breadcrumbs on every page, and a unified design language across login, post list, post form, and settings.
• Volumen icon: a dedicated SVG icon shown in the sidebar and on the login page (served at /admin/icon.svg).
• Version in sidebar footer so admins always see which release is running.
• Per-user display name on the user record and admin header.
• Per-user fediverse handle editable from the settings page (independent of the post-level fediverse_creator).
• Profile photo upload: each admin user can upload a WebP/AVIF avatar that is stored alongside posts in the content directory and shown in the settings page.
• Tabbed settings page separating account, profile, and admin sections.
• Restricted uploads: only WebP (image/webp) and AVIF (image/avif) are accepted, with a 415 error message that points users to cwebp / avifenc for conversion. Reflects the engine's WebP/AVIF-only posture end-to-end.
• Polished native inputs for <input type="date|time|file"> so they match the rest of the admin's design language.

Tooling

• just lint recipe for standalone RuboCop checks and just fmt for auto-fixing lint issues.
• config.toml.example template for local development; config.toml is now gitignored.

Changed

• Memoize published_posts within a single request so repeated calls (posts list, tags, feeds, sitemap) reuse the cached result.
• Store#all cache now invalidates on individual file mtime changes, not just on the content directory mtime. Manual edits and git pull are detected without a restart.
• Cache-Control: public, max-age=60 header on all public API responses for browser and CDN caching.
• Extract feed and sitemap generation into a dedicated FeedHelpers module, reducing Server from ~500 to ~420 lines.

Fixed

• Admin post save/delete now correctly clears the in-memory posts cache, so the post list reflects edits without a manual reload.
• The post form's date field defaults to today when the underlying post has no date, preventing the picker from showing an invalid empty value.

Security

• Content-Security-Policy header on all /admin/* responses: default-src 'self', script-src 'self' 'unsafe-inline', style-src 'self' 'unsafe-inline', img-src 'self' data:, font-src 'self', connect-src 'self', form-action 'self', frame-ancestors 'none'.
• File uploads are rejected (HTTP 413) when exceeding 10 MB (MAX_UPLOAD_BYTES).
• File uploads are restricted to image/webp and image/avif (ALLOWED_UPLOAD_TYPES). Anything else is rejected with a 415 and a conversion hint.

[0.2.0] — 2026-06-25

Added

• <pubDate> in RSS feed items, derived from the post date.
• <lastmod> in sitemap entries for SEO.
• In-memory rate limiting on the login endpoint: 10 attempts per 60 seconds per IP.
• <language> element in the RSS feed channel.
• Periodic cleanup of stale login_attempts entries to prevent unbounded memory growth.
• Slug format validation ([a-z0-9._-]) preventing path traversal and XSS in templates.
• Username validation in change_username matching the create-user regex.
• Escape-on-output for slug and username in admin template attributes.
• Memoization of Store#all with mtime-based invalidation, eliminating N×read+parse per request.
• Atomic file writes (tmp + rename) for posts and users.toml.
• Post language directory routing: non-default-language posts now land in content_dir/<lang>/ instead of overwriting root-level files.
• CLI test coverage (version, help, unknown command, option parsing, config bootstrap).
• Test coverage for RSS feed and sitemap endpoints.
• CORS preflight (OPTIONS /api/volumen/*) so browsers can reach the JSON API.
• Users#all memoization with mtime-based invalidation, matching Store#all.
• Session invalidation: deleted users can no longer use existing session cookies.
• CSRF protection on POST /admin/preview.
• Symlink-safe containment in Store#media_file via File.realpath.

Added

• Scheduled publishing: a publish_at frontmatter field hides posts from the public API and feeds until their publication date arrives. The admin form includes a Publish at date picker.
• JSON Feed: GET /api/volumen/feed.json serves a jsonfeed.org v1.1 feed with content_html and date_published per item.
• Fulltext search: GET /api/volumen/posts?q=… filters posts by case-insensitive match in title and body.

Changed

• Split lib/volumen/server.rb into api_routes.rb and admin_routes.rb modules, keeping the server class focused on configuration and shared helpers.

Fixed

• admin.session_ttl was defined but never read; it now controls Rack::Session::Cookie expiration via expire_after.
• Derived post excerpts now strip HTML tags before stripping markdown markup, avoiding raw HTML leaks in auto-generated excerpts.
• Draft posts no longer leak through the public detail endpoint (/api/volumen/posts/:slug).
• Config::DEFAULTS inner hashes are now frozen and deep_merge builds fresh copies, preventing mutation from silently poisoning later Config.load calls.
• A warning is emitted when admin.session_key is configured but shorter than 64 bytes, instead of silently falling back to a random secret.

[0.1.0] — 2026-06-20

First public release: a small, file-based Markdown blog engine in CRuby. Posts are plain files, the engine exposes them as a JSON API and ships a self-hosted admin — no database, no external services.

Added

Content & storage

• File-based store: each post is a .md file with a TOML frontmatter block delimited by +++. No database.
• Post fields: title, slug, date, lang, author, tags, draft, excerpt, cover, all_langs, and translations (a lang → slug map).
• Drafts (draft = true) are hidden from the public API.
• Excerpt falls back to the first paragraph (~200 chars) when none is set.
• Estimated reading time (~200 words/min) computed per post.
• Multilingual posts: per-language slugs via translations, plus all_langs to surface a single post under every language.

Markdown rendering

• GFM rendering via kramdown: tables, fenced code blocks, task lists, and strikethrough.
• Automatic heading IDs for in-page anchors.
• Raw HTML in post bodies is passed through (authors are the trusted admin).

Public JSON API (/api/volumen)

• Read-only endpoints: site, posts, posts/{slug}, tags, feed.xml (RSS), and sitemap.xml.
• posts supports pagination (page, limit, returning total and page_size) and filtering by lang and tag.
• Permissive CORS so a separate front end can consume the API.

Admin (/admin)

• Server-rendered admin with a sidebar layout and full post CRUD.
• Dual-mode editor: Markdown source (primary) and a visual WYSIWYG, switchable per post, with a toggleable live preview persisted across sessions.
• Image upload from the editor toolbar into content_dir/media; any image format is accepted (WebP and AVIF included) and served with the correct Content-Type.
• Cover image field with upload, URL, clear, and preview.

Multi-user & roles

• Multiple admin users stored in users.toml, managed from a settings page.
• Two roles: admin (full access incl. user management) and author (posts only).
• Change password and username; last-admin and self-deletion safeguards.

Configuration & CLI

• TOML configuration, auto-generated with a commented template on first run.
• Configurable host/port (defaults to 9090), content_dir, users_file, and site metadata.
• CLI: serve, hash-password, version, help, with --config, --content, --host, and --port overrides.

Deployment

• install.sh installs the Ruby toolchain from distro packages on Fedora and openEuler (and prints guidance on other distros), creates the service user and directories, and installs a systemd unit.
• Deployment docs for systemd and FreeBSD (rc.d), plus an nginx reverse-proxy setup that runs the admin same-origin, with brute-force rate-limiting and an optional IP allowlist on the login endpoint.

Project & tooling

• Documentation set: architecture, configuration, API reference, deployment, and security.
• just task set (install, run, dev, build, test, uninstall) and Forgejo Actions CI (RuboCop + tests on Ruby 3.3/3.4, gem build on release).
• CONTRIBUTING.md and a minitest suite; clean RuboCop.

Security

• Passwords hashed with scrypt and verified in constant time.
• Per-form CSRF tokens on every state-changing admin request.
• Session cookies are HttpOnly and SameSite=Strict, and gain the Secure attribute automatically on HTTPS requests (detected via request.ssl? / X-Forwarded-Proto), so the cookie never travels over plain HTTP in production.
• Configurable, stable session_key so sessions survive restarts.
• Generic login error message to avoid username enumeration.