No description
  • Ada 69.3%
  • Go 18.2%
  • C 3.2%
  • JavaScript 2.7%
  • Handlebars 2.3%
  • Other 4.3%
Find a file
2026-11-18 23:10:39 +01:00
alire Replace AWS with libmicrohttpd and libcurl 2026-09-17 12:22:21 +02:00
smoke Who follows the blog is sent on to its alias, the way an account that moved takes its followers along, where the Follow got a Reject and the followers of the blog's fediverse years found themselves refused: with an alias in the Federation panel the Follow is accepted and the follower kept in the keystore, and ten minutes after a server's first follower, the others of the same server usually coming together, that server gets one Move from the blog to the alias, which Mastodon carries out for all its users who follow the blog, once a week at most, so another goes a week later if somebody new came; an Undo takes the follower away; without an alias the Follow is still refused; the smoke has two people of one server follow, be accepted, get a single Move and leave 2026-11-18 23:10:39 +01:00
src Who follows the blog is sent on to its alias, the way an account that moved takes its followers along, where the Follow got a Reject and the followers of the blog's fediverse years found themselves refused: with an alias in the Federation panel the Follow is accepted and the follower kept in the keystore, and ten minutes after a server's first follower, the others of the same server usually coming together, that server gets one Move from the blog to the alias, which Mastodon carries out for all its users who follow the blog, once a week at most, so another goes a week later if somebody new came; an Undo takes the follower away; without an alias the Follow is still refused; the smoke has two people of one server follow, be accepted, get a single Move and leave 2026-11-18 23:10:39 +01:00
static The blog posts in fediverse groups, Lemmy communities, NodeBB categories and any actor of type Group: the author's WebFinger account is now the blog's own actor, a Person with the profile's name, avatar and bio, an inbox and the key already in the keystore, where it sent the asker on to another server as an account moved there; an alias on another server stays optional and is named in the aliases and in alsoKnownAs, the self link staying here so that a server checking a handle against its actor accepts it. The new Groups panel follows a group by its handle through its host's WebFinger, lists each with read once it accepted, answer, and write unless only its moderators may post, reading every group again when the panel opens, and unfollows with an Undo of the Follow itself; in the list of posts a menu sends a post to the groups that take it, once each, as a Page with the title, a link to the post and the whole post in HTML and Markdown with a cc line for the group, an object per group readable at /ap/objects/ and sent to the post for a browser, and editing a post sends an Update to the groups that have it, back to draft nothing, deleting it a Delete, or takes it out of the queue if it never left. Requests are signed as Lemmy and NodeBB expect, draft-cavage over the target, host, date and digest; the inbox takes only signed Accepts, Rejects and Blocks from the groups followed that are about the blog, reading a group's key again at most every five minutes when a signature does not hold, and a Follow of the blog gets one Reject, only to an inbox on the follower's own host; deliveries go through a queue in the keystore worked in order by a task in the server, 2xx done, 400, 401, 403, 404, 405, 410, 421 and 422 final, anything else tried again after 2, 2, 4, 6, 10 minutes and on, sixteen times. Remote JSON is read through jansson, now in the image; the decisions are a proved SPARK unit; the smoke runs a fake Lemmy that checks every signature the blog sends and answers with its own 2026-11-18 22:36:41 +01:00
tools Serve a file without putting it on the stack, and read the markdown under a <br> 2026-09-18 23:37:31 +02:00
.dockerignore Remove ActivityPub and add Docker runtime assets 2026-08-18 22:31:38 +02:00
.drone.yml Take the smoke tests out of the image build 2026-09-17 14:07:20 +02:00
.gitignore Write the archive's permissions into the archive 2026-09-18 22:31:44 +02:00
alire.toml Replace AWS with libmicrohttpd and libcurl 2026-09-17 12:22:21 +02:00
DOCKER_INSTALL.md Document the country table and WORTWERK_RIR_SOURCE 2026-09-29 16:12:30 +02:00
Dockerfile The blog posts in fediverse groups, Lemmy communities, NodeBB categories and any actor of type Group: the author's WebFinger account is now the blog's own actor, a Person with the profile's name, avatar and bio, an inbox and the key already in the keystore, where it sent the asker on to another server as an account moved there; an alias on another server stays optional and is named in the aliases and in alsoKnownAs, the self link staying here so that a server checking a handle against its actor accepts it. The new Groups panel follows a group by its handle through its host's WebFinger, lists each with read once it accepted, answer, and write unless only its moderators may post, reading every group again when the panel opens, and unfollows with an Undo of the Follow itself; in the list of posts a menu sends a post to the groups that take it, once each, as a Page with the title, a link to the post and the whole post in HTML and Markdown with a cc line for the group, an object per group readable at /ap/objects/ and sent to the post for a browser, and editing a post sends an Update to the groups that have it, back to draft nothing, deleting it a Delete, or takes it out of the queue if it never left. Requests are signed as Lemmy and NodeBB expect, draft-cavage over the target, host, date and digest; the inbox takes only signed Accepts, Rejects and Blocks from the groups followed that are about the blog, reading a group's key again at most every five minutes when a signature does not hold, and a Follow of the blog gets one Reject, only to an inbox on the follower's own host; deliveries go through a queue in the keystore worked in order by a task in the server, 2xx done, 400, 401, 403, 404, 405, 410, 421 and 422 final, anything else tried again after 2, 2, 4, 6, 10 minutes and on, sixteen times. Remote JSON is read through jansson, now in the image; the decisions are a proved SPARK unit; the smoke runs a fake Lemmy that checks every signature the blog sends and answers with its own 2026-11-18 22:36:41 +01:00
INSTALL.md The blog posts in fediverse groups, Lemmy communities, NodeBB categories and any actor of type Group: the author's WebFinger account is now the blog's own actor, a Person with the profile's name, avatar and bio, an inbox and the key already in the keystore, where it sent the asker on to another server as an account moved there; an alias on another server stays optional and is named in the aliases and in alsoKnownAs, the self link staying here so that a server checking a handle against its actor accepts it. The new Groups panel follows a group by its handle through its host's WebFinger, lists each with read once it accepted, answer, and write unless only its moderators may post, reading every group again when the panel opens, and unfollows with an Undo of the Follow itself; in the list of posts a menu sends a post to the groups that take it, once each, as a Page with the title, a link to the post and the whole post in HTML and Markdown with a cc line for the group, an object per group readable at /ap/objects/ and sent to the post for a browser, and editing a post sends an Update to the groups that have it, back to draft nothing, deleting it a Delete, or takes it out of the queue if it never left. Requests are signed as Lemmy and NodeBB expect, draft-cavage over the target, host, date and digest; the inbox takes only signed Accepts, Rejects and Blocks from the groups followed that are about the blog, reading a group's key again at most every five minutes when a signature does not hold, and a Follow of the blog gets one Reject, only to an inbox on the follower's own host; deliveries go through a queue in the keystore worked in order by a task in the server, 2xx done, 400, 401, 403, 404, 405, 410, 421 and 422 final, anything else tried again after 2, 2, 4, 6, 10 minutes and on, sixteen times. Remote JSON is read through jansson, now in the image; the decisions are a proved SPARK unit; the smoke runs a fake Lemmy that checks every signature the blog sends and answers with its own 2026-11-18 22:36:41 +01:00
README.md Who follows the blog is sent on to its alias, the way an account that moved takes its followers along, where the Follow got a Reject and the followers of the blog's fediverse years found themselves refused: with an alias in the Federation panel the Follow is accepted and the follower kept in the keystore, and ten minutes after a server's first follower, the others of the same server usually coming together, that server gets one Move from the blog to the alias, which Mastodon carries out for all its users who follow the blog, once a week at most, so another goes a week later if somebody new came; an Undo takes the follower away; without an alias the Follow is still refused; the smoke has two people of one server follow, be accepted, get a single Move and leave 2026-11-18 23:10:39 +01:00
wortwerk.gpr The blog posts in fediverse groups, Lemmy communities, NodeBB categories and any actor of type Group: the author's WebFinger account is now the blog's own actor, a Person with the profile's name, avatar and bio, an inbox and the key already in the keystore, where it sent the asker on to another server as an account moved there; an alias on another server stays optional and is named in the aliases and in alsoKnownAs, the self link staying here so that a server checking a handle against its actor accepts it. The new Groups panel follows a group by its handle through its host's WebFinger, lists each with read once it accepted, answer, and write unless only its moderators may post, reading every group again when the panel opens, and unfollows with an Undo of the Follow itself; in the list of posts a menu sends a post to the groups that take it, once each, as a Page with the title, a link to the post and the whole post in HTML and Markdown with a cc line for the group, an object per group readable at /ap/objects/ and sent to the post for a browser, and editing a post sends an Update to the groups that have it, back to draft nothing, deleting it a Delete, or takes it out of the queue if it never left. Requests are signed as Lemmy and NodeBB expect, draft-cavage over the target, host, date and digest; the inbox takes only signed Accepts, Rejects and Blocks from the groups followed that are about the blog, reading a group's key again at most every five minutes when a signature does not hold, and a Follow of the blog gets one Reject, only to an inbox on the follower's own host; deliveries go through a queue in the keystore worked in order by a task in the server, 2xx done, 400, 401, 403, 404, 405, 410, 421 and 422 final, anything else tried again after 2, 2, 4, 6, 10 minutes and on, sixteen times. Remote JSON is read through jansson, now in the image; the decisions are a proved SPARK unit; the smoke runs a fake Lemmy that checks every signature the blog sends and answers with its own 2026-11-18 22:36:41 +01:00
wortwerk_spark.gpr The blog posts in fediverse groups, Lemmy communities, NodeBB categories and any actor of type Group: the author's WebFinger account is now the blog's own actor, a Person with the profile's name, avatar and bio, an inbox and the key already in the keystore, where it sent the asker on to another server as an account moved there; an alias on another server stays optional and is named in the aliases and in alsoKnownAs, the self link staying here so that a server checking a handle against its actor accepts it. The new Groups panel follows a group by its handle through its host's WebFinger, lists each with read once it accepted, answer, and write unless only its moderators may post, reading every group again when the panel opens, and unfollows with an Undo of the Follow itself; in the list of posts a menu sends a post to the groups that take it, once each, as a Page with the title, a link to the post and the whole post in HTML and Markdown with a cc line for the group, an object per group readable at /ap/objects/ and sent to the post for a browser, and editing a post sends an Update to the groups that have it, back to draft nothing, deleting it a Delete, or takes it out of the queue if it never left. Requests are signed as Lemmy and NodeBB expect, draft-cavage over the target, host, date and digest; the inbox takes only signed Accepts, Rejects and Blocks from the groups followed that are about the blog, reading a group's key again at most every five minutes when a signature does not hold, and a Follow of the blog gets one Reject, only to an inbox on the follower's own host; deliveries go through a queue in the keystore worked in order by a task in the server, 2xx done, 400, 401, 403, 404, 405, 410, 421 and 422 final, anything else tried again after 2, 2, 4, 6, 10 minutes and on, sixteen times. Remote JSON is read through jansson, now in the image; the decisions are a proved SPARK unit; the smoke runs a fake Lemmy that checks every signature the blog sends and answers with its own 2026-11-18 22:36:41 +01:00

Wortwerk

Wortwerk is a single-user blog engine with a newsletter, written in Ada. Every pure decision layer (routing, slugs, paths, login policy, mail headers, quotas, sanitising, parsing helpers) is written in SPARK and proved with GNATprove.

It is a small, explicit take on what WriteFreely does. There is one author, one process and one volume, and no database: posts are plain Markdown files in a Hugo-compatible layout, so the blog can always be taken elsewhere as it is.

Wortwerk is in production use. For deployment, see DOCKER_INSTALL.md. For building from source, see INSTALL.md.

What it does

The blog. The public blog uses the Ghost Journal theme, with paginated front pages (/page/N), one page per post, pinned posts first, and an Atom feed at /feed.atom (also /rss): this month and the newest posts up to 20, every older post in the archive of its month (?month=YYYY-MM). Markdown is rendered by cmark-gfm, so tables and the rest of GFM work. The tagfilter is always on, which means a post cannot carry a <script>.

The editor. The owner writes at /newpost in a Toast UI Markdown editor, in a plain field that nothing rewrites. Images are uploaded into the post's bundle. Posts can be drafts or published, and can be pinned or deleted.

Images. Every stored image goes through one place (Save_Post_Asset), whatever door it came through: it is stored under md5(content).ext and shrunk with ImageMagick to fit the column it lands in.

Feed import. The owner pastes the URL of another blog's RSS or Atom feed, and a background task turns its entries into posts:

  • it fetches over http/https only, capped in size and time, and refuses loopback, private, link-local and CGNAT targets at the resolved address;
  • it parses with libxml2 (SAX, no external entities);
  • it cleans the markup at the door;
  • it copies images locally instead of hotlinking them;
  • it is idempotent on the entry's guid, so re-importing the same feed does nothing new;
  • an entry that carries only a summary is reported and not saved as if it were the article.

Newsletter. A reader asks to subscribe from the blog, and the request waits in a queue: nothing is mailed to an address a stranger typed. The newsletter panel lists each request with the time it arrived, the IP and the browser it came from, and how many waiting requests share them. "Go ahead" sends the one confirmation (double opt-in), "Kill" drops the request without a word. The same panel takes the countries requests may come from, ISO codes separated by commas ("IT, DE, LU, CH"): a request from anywhere else, or from an address no registry knows, is dropped before the queue and answered like any other; an empty list accepts the whole world. Every mail carries an unsubscribe link, and a List-Unsubscribe header with RFC 8058's one-click: the link in the body asks before it unsubscribes, so a link scanner removes nobody, while a mail client's one-click POST does it at once. Sending a post to subscribers is one button in the admin. A task inside the server drains the queue, within the daily and monthly limits set for the relay. A post held back by those limits goes out by itself when the window reopens, and when the relay refuses a mail, the admin shows what the relay answered. Headers are RFC-correct: a valid Date, and the sender name and subject encoded when they are not ASCII. The subscriber list can be exported and imported.

Statistics. The admin has a dashboard built on the GoAccess 1.9.3 report shell. It shows readers, pages, referrers, browser languages, crawlers by name, and how many newsletter messages went out and on which days. No address is ever written down: a reader is a fingerprint under a salt that is drawn each day and thrown away with that day's file, so the figure means "distinct readers per day" and never "who". See static/stats/README.md.

Federation. Wortwerk answers WebFinger for exactly one account, the author's (say alice@example.org), and that account is the blog's own ActivityPub actor at /ap/actor: a Person with the profile's name, avatar and bio, an inbox, and an RSA-2048 key made in the keystore on the first start and kept after that. Every answer is signed (RFC 9421, rsa-v1_5-sha256, with a Content-Digest). The actor is there for the Groups panel (below). Nobody follows the blog itself: without an alias a Follow gets a Reject; with one, the Follow is accepted and the follower's server then gets a Move from the blog to the alias, as when an account moves, which it carries out for all its users who follow the blog. Mastodon carries out a Move of an account once a week, so each server gets one ten minutes after its first follower (the others usually come together) and another a week later if somebody new came meanwhile. The alias has to name the blog's actor in its own alsoKnownAs, or the Move is ignored.

An alias is optional: the same person's account on another server (say alice@social.example.net). It is named in the WebFinger aliases and in the actor's alsoKnownAs, but the self link stays the blog's, because a server that checks a handle against its actor (Mastodon does) refuses one whose WebFinger points elsewhere. A search for the local handle therefore finds the blog. Everything is set in the admin's Federation panel: the local account and, if wanted, the alias. The feature is off until it is enabled there, and while it is off every address above returns 404.

Groups. The blog can post in fediverse groups: Lemmy communities, NodeBB categories, any actor of type Group. The Groups panel follows one by its handle (!name@host, @name@host or name@host, found through the host's WebFinger), lists each group followed with what it grants (read once it accepted, answer, write unless only its moderators may start posts), reading every group's actor again when the panel opens, and unfollows (an Undo, and the group is forgotten). In the list of posts, a menu sends a post to the groups that take it, once each. What goes is a Page: the post's title, a link to it on the blog and then the whole post, in HTML and in Markdown (Lemmy shows the source), a "cc:" line with the group's mention last, addressed to the group and the public with the group as audience. Each group gets an object of its own (/ap/objects/..., readable as JSON, a redirect to the post for a browser), since a Lemmy post lives in one community. Editing a post sends an Update to the groups that have it, deleting it a Delete.

Requests are signed as Lemmy and NodeBB expect (draft-cavage, (request-target) host date digest, rsa-sha256), and the inbox takes only signed activities from the groups followed, reading a group's actor again once when a signature does not hold, in case its key changed. Deliveries go through a queue that a task in the server works through: 2xx is done, 400, 401, 403, 404, 405, 410, 421 and 422 are final, and anything else is tried again after 2, 2, 4, 6, 10... minutes, sixteen tries in all. The state is files under federation/ in the keystore root: one per group followed, one per post per group, one per delivery waiting.

While it answers, Wortwerk also serves NodeInfo (/.well-known/nodeinfo, pointing to /nodeinfo/2.1) so the fediverse's crawlers can list the blog: ActivityPub as its protocol (the actor above; the schema has no "none"), one user, no registrations, and the Atom feed and the newsletter (smtp) as what it sends out. The node's name and description are set in the same panel, under a line; left empty, they are the blog's name and slogan.

Three things are the deployer's job:

  • Routing. The fediverse asks the domain of the handle. If that is not the blog's own host (alice@example.org writing at blog.example.org), https://example.org/.well-known/webfinger has to reach Wortwerk. The Federation panel says so when the two differ.
  • The remote actor URL. It is the account's id on its own server, and its shape depends on the software (/users/name on Mastodon, /name or /@name elsewhere). The reliable way to get it is to ask the remote server's WebFinger and copy the self link.
  • The alias on the other side. Add the local account as an alias of the remote one (Mastodon: Account settings → Moving from a different account; other servers have their own equivalent), so the pairing is accepted both ways.

Administration. /admin has panels for posts, the editor, feed import, federation, groups, newsletter, SMTP, blog settings, profile and avatar, login (changing the password), and statistics.

Security model

  • Two roots, never mixed. WORTWERK_CONTENT_ROOT holds posts and assets, and is publishable. WORTWERK_KEYSTORE_ROOT holds private state: the credential wallet, SMTP settings, subscribers, sessions and statistics.
  • The wallet is encrypted with a key derived from WORTWERK_KEYSTORE_SECRET and the owner username, and passwords are hashed with scrypt. The keystore secret is key material only. It is never accepted or compared on an HTTP request.
  • Sessions. Login issues a session cookie, and everything under /admin, /newpost, /api/..., /static/admin/ and /static/toast/ requires it.
  • No inline code. The Content-Security-Policy allows no inline script and no inline style, and every page, the dashboard included, loads its code from files.
  • No archives. Importing a zip was the most dangerous thing the application did, so it was removed. Posts come in only through the editor and the RSS/Atom feed import. They go out through the Atom feed, which carries whole posts: the current feed links the newest monthly archive (rel="prev-archive", RFC 5005), each archive the one before it, so following the links to the end is the export.

Storage layout

blog/                       (WORTWERK_CONTENT_ROOT)
  content/posts/YYYY/MM/DD/<slug>/index.md   the folder of the post's date
  content/posts/_undated/<slug>/index.md     a post with no date
  content/pinned/<slug>/index.md
  static/images/<md5>.<ext>
keystore/                   (WORTWERK_KEYSTORE_ROOT)
  wallet, sessions, SMTP config, federation key, subscribers, queue, stats
  geo/<registry>.txt          the registries' delegation files, refreshed weekly
  federation/groups/<md5>.json        a group followed, with its state
  federation/sent/<md5>-<md5>.json    a post sent to a group
  federation/queue/<id>.json          an activity waiting to be delivered
  federation/followers/<md5>.json     somebody following, until moved
  federation/moves/<md5>.json         a server's Move: when due, when last sent

The content tree is plain Hugo: a Hugo site pointed at it builds. The order of the blog is the order of the folder names, so a page of the home, of the admin or of the feed opens only the posts it shows. The address of a post is its slug alone, wherever its folder is. A post found at the old place, content/posts/<slug>/, is moved into the folder of its date when the server starts; one whose move fails is logged as an error and served from where it is. Wortwerk must be the only one writing posts while it runs: a post copied in by hand is seen at the next start.

Configuration

All configuration is done through environment variables. The full table with defaults is in DOCKER_INSTALL.md. The required ones are:

Variable Meaning
WORTWERK_KEYSTORE_SECRET Opens the wallet. 16–4096 chars. Never change it after the first boot.
WORTWERK_INITIAL_USER Owner username. Part of the wallet key: keep it set and unchanged.
WORTWERK_INITIAL_PASSWORD Seeds the wallet on the first boot only.

These are optional tunables:

Variable Default Meaning
WORTWERK_NEWSLETTER_INTERVAL 300 Seconds between newsletter queue passes (1–3600).

SMTP (host, port, credentials, STARTTLS, sender, daily and monthly limits, and the send latency: seconds between one newsletter mail and the next, 0 to 3600, so a freemail relay does not see the list leave in a burst) is set from the admin's SMTP panel and stored in the keystore, never in the content.

Routes

These routes are public:

Route
/, /page/N Front page, paginated
/<slug>/ (e.g. /2026-09-17/my_post/) A post
/feed.atom, /rss Atom feed; ?month=YYYY-MM for a past month's archive
/subscribe Newsletter subscription
/email/confirm/..., /email/unsubscribe/... Links sent by mail
/login, /logout Owner session
/health Liveness probe for healthchecks
/.well-known/webfinger?resource=acct:... Signed WebFinger answer for the author (when enabled)
/.well-known/nodeinfo, /nodeinfo/2.1 NodeInfo for the fediverse's crawlers (when enabled)
/ap/actor The blog's actor, signed, with its public key (when enabled)
POST /ap/inbox Signed activities from the groups followed (when enabled)
/ap/outbox, /ap/followers, /ap/following Empty collections the actor names (when enabled)
/ap/objects/... A post as one group has it; a browser is sent to the post (when enabled)

The owner routes need the session cookie:

Route
/admin, /newpost Administration and editor
GET /api/posts/list?offset=, GET /api/posts/get?slug= Read posts: the list twenty at a time, newest first, pinned ones on the first page, "more" when older ones remain
POST /api/posts/create?date=&title= New draft (raw text/markdown, ≤ 50,000 bytes)
POST /api/posts/save, /draft, /publish ?slug= Save the body in that state
POST /api/posts/pin?slug=&pinned= Pin or unpin
DELETE /api/posts/delete?slug= Delete the bundle
POST /api/images?slug= Upload an image (png, jpeg, gif, webp)
POST /api/posts/distribute?slug=&go=true Queue a post for the newsletter
POST /api/posts/import?url=, GET /api/posts/import/status Feed import
/api/admin/config/{smtp,blog,profile,login,newsletter,federation} Settings
/api/admin/subscribers, /api/admin/subscribers/import Subscriber list
GET /api/admin/subscribers/requests, POST .../requests/{approve,kill} (id=) Subscription requests
GET /api/admin/groups (?cached=1 without asking the groups), GET /api/admin/groups/sent Groups followed; what was sent where
POST /api/admin/groups/{follow,unfollow,send} (handle=, id=, slug=&group=...) Follow, unfollow, send a post

Building

Wortwerk is built with Alire, using GNAT 16.1 and GPRbuild 26. The native libraries it needs are libmicrohttpd, libcurl, OpenSSL, zlib, cmark-gfm (with extensions), libxml2, jansson and MagickWand.

alr build

By default the link uses ImageMagick 7 (Debian 13). On a system with ImageMagick 6:

MAGICK_WAND_LINK=-lMagickWand-6.Q16 MAGICK_CORE_LINK=-lMagickCore-6.Q16 alr build

To run the SPARK proof gate:

alr exec -- gnatprove -P wortwerk_spark.gpr --mode=all --level=2 --timeout=10 --prover=all --report=fail -j0

The smoke suite is written in Go and starts the real binary:

cd smoke && go test ./...

The Docker build runs the build and the proof gate, and an image is only produced if both pass. The smoke suite runs locally before a commit.

License

Wortwerk is licensed under the European Union Public Licence, version 1.2 (EUPL-1.2).

Credits

  • TOAST UI Editor (MIT) is vendored under static/toast. See static/toast/Toast-UI-MIT.txt.
  • Ghost Journal (MIT, © Ghost Foundation) is the default theme, under static/themes/journal. See its LICENSE.
  • The GoAccess 1.9.3 report shell (MIT) is used for the statistics dashboard, under static/stats and static/admin/goaccess-*.