- Ada 69.3%
- Go 18.2%
- C 3.2%
- JavaScript 2.7%
- Handlebars 2.3%
- Other 4.3%
|
|
||
|---|---|---|
| alire | ||
| smoke | ||
| src | ||
| static | ||
| tools | ||
| .dockerignore | ||
| .drone.yml | ||
| .gitignore | ||
| alire.toml | ||
| DOCKER_INSTALL.md | ||
| Dockerfile | ||
| INSTALL.md | ||
| README.md | ||
| wortwerk.gpr | ||
| wortwerk_spark.gpr | ||
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.orgwriting atblog.example.org),https://example.org/.well-known/webfingerhas 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/nameon Mastodon,/nameor/@nameelsewhere). The reliable way to get it is to ask the remote server's WebFinger and copy theselflink. - 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_ROOTholds posts and assets, and is publishable.WORTWERK_KEYSTORE_ROOTholds private state: the credential wallet, SMTP settings, subscribers, sessions and statistics. - The wallet is encrypted with a key derived from
WORTWERK_KEYSTORE_SECRETand 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. Seestatic/toast/Toast-UI-MIT.txt. - Ghost Journal (MIT, © Ghost Foundation) is the default theme, under
static/themes/journal. See itsLICENSE. - The GoAccess 1.9.3 report shell (MIT) is used for the statistics
dashboard, under
static/statsandstatic/admin/goaccess-*.