fedipod-bb 0.2.0

package/README.md

@@ -0,0 +1,195 @@
+# FediPod-BB
+
+A forum whose record lives on a Solid pod, as ActivityPub documents in the
+shapes the Fediverse's boards use: each category is a Group actor (FEP-1b12),
+each topic is a context collection (FEP-7888), each post is a Page (with a title, as Lemmy's are) or a
+Note that names its topic and its category.
+
+This package holds the pod layout, the writers for it, the host, and the
+website: where every document lives, how a topic's pages are written and
+sealed, how a member's post is cached for readers, the process that runs
+the forum from a moderator's machine, and the page that shows the forum.
+A moderator's console is part of that page: the queue of reports, held posts
+and asks, and the settings.
+The queue shows what needs a moderator: a report, a held post, a join
+request, and a request of a moderator's that did not take. The design and the phases are in
+`claude/plans/fedipod-bb.md` at the repository root.
+
+```
+node --test packages/fedipod-bb/test/*.test.mjs
+```
+
+## Hosting a forum
+
+```
+npm install -g fedipod-bb
+fedipod-bb credential --home DIR --email you@example.org --pod https://forum.example/
+fedipod-bb init --home DIR --handle forum --name "The Forum" \
+    --category gardening:Gardening --category compost:Compost --moderator <actor id>
+fedipod-bb start --home DIR
+```
+
+`credential` mints the forum's pod credential at the pod's server, with the
+account's password asked at the terminal, and saves it as
+`DIR/credential.json`; nothing is written to the pod.
+
+`init` writes the forum's config and containers. `start` publishes every
+actor the first time, then drains the forum's one inbox, hands each activity
+to the category it names, places carried posts in topics, and carries them
+to the category's followers. Several moderators run `start` on their own
+machines against the same pod: one hosts, the others watch, and when the
+host stops another takes over within fifteen minutes. A public
+`ap/heartbeat` says when the forum was last hosted. `status` prints
+what the pod's state says without hosting.
+
+Every category is a FediPod group: joining is a Follow, a member's public
+post addressed to the category is carried (FEP-1b12) and then placed in its
+topic — the one its `context` names, the one its reply chain leads to, or a
+new one with the post as its opening (FEP-7888). A post from a non-member is
+not carried and opens nothing.
+
+## Layout
+
+Under one root, `fedipod-bb/`, on the forum's pod:
+
+| path | what |
+|---|---|
+| `ap/actor` | the forum's own actor, an `Application` |
+| `ap/inbox/` | the one inbox every category names as its own |
+| `ap/categories` | the categories, an `OrderedCollection` of their actor ids |
+| `ap/administrators` | the moderators' actor ids |
+| `ap-state/` | owner-only: the forum's config, keys and lease |
+| `c/<slug>/` | one FediPod group root per category, unchanged from a group's |
+| `c/<slug>/ap/topics` | the category's topics, newest first, paged |
+| `c/<slug>/ap/topic/<tid>` | a topic: the context collection, with pages `-1`, `-2`, … oldest first |
+| `c/<slug>/ap/cache/<key>` | a readable copy of a member's post, for the website |
+| `c/<slug>/ap-state/topics.json`, `topics/<tid>.json` | owner-only: the topic record |
+
+A category's `ap/actor`, `ap/outbox`, `ap/followers`, `ap/moderators` and
+`ap/featured` are what a FediPod group publishes today; the forum adds the
+topic documents beside them. Posts are named in a topic by their authors'
+own ids; the cached copy is for readers in a browser and is never listed in
+a collection.
+
+## The website
+
+`site/` is a static page. Staged by `scripts/stage-site.mjs` under `/bb/`
+on the fedipod.net site, it opens a forum attached there at
+`/bb/?forum=<handle>`, reading everything through that site's own
+`/u/<handle>/` addresses; `/bb/?pod=https://…/fedipod-bb/` reads a forum
+from its pod directly. Where the site has `bb.<domain>` as a domain alias,
+the same page answers there for every path, with the forum named by the
+first path segment: `https://bb.fedipod.net/<handle>/`. It still reads
+through `<domain>`, where the handles live (the hosts are `BB_HOSTS` in the
+staging script). Anyone reads.
+A topic whose newest post arrived since the reader last opened it is marked
+`New` on the index. The mark is the reader's own: one entry per topic in their
+browser's storage, written nowhere else and sent nowhere - a public forum has
+no place to keep who read what, and no business keeping it. Arriving at a
+forum for the first time reads everything before that moment, so a new reader
+does not meet a page of `New`.
+
+The page is built to WCAG 2.2 AA: a skip link, named landmarks, a label on
+every control, an `aria-label` on each post's buttons naming whose post they
+act on, `aria-current` on the category in view, `scope` on the index's
+headers, a polite live region for what the page has just done, and a reply
+box that takes the keyboard when it opens and returns it when it closes.
+The front page is an index of the forum's newest posts, across every
+category: topic, category, author, date and the topic's reply count, one
+line each. The forum publishes that index itself (`ap/latest`, the copies it
+already holds, newest first, capped at fifty), so the page makes one request
+for the list rather than walking every category. The category chips filter
+it; a topic's name opens the thread at that post. Pinned topics sort first -
+a category's `featured` collection for a pin within it, the forum actor's own
+for one that holds everywhere.
+
+A thread is a tree: a reply sits under the post it answers, six deep. Posts
+are written in Markdown (`site/markdown.mjs`, no dependency, escaped before
+it is marked up) and carry their source alongside, so an edit reopens what
+was typed. A topic is named by the activity that opens it; a post has no
+title.
+
+Each post offers Reply, Share and Report, and its author Edit and Delete; a
+report is queued for the moderators. Under a topic's title a moderator gets
+rename, pin, pin site-wide and delete. Every moderator request is published
+at the moderator's own pod and fetched back from there before the forum acts
+on it (FEP-fe34), which is what makes a button on a public page safe.
+A post can be voted for: a `Like` to the category, its `Undo` to take it
+back, counted per person and published with the post as AS2 `likes`. The
+index sorts by newest or by votes, and searches what it is holding - topic
+names, authors and the words of the posts. A byline opens that person's
+posts in this forum.
+
+A moderator's queue lives at `<pod>/fedipod-bb/mod/queue.json`, with a
+record of what was done beside it in `log.json`. Neither is public: the
+container's access rule names the moderators' WebIDs, and the page reads it
+with the moderator's own login rather than through the Gateway. From it a
+moderator lets a held post through (`Accept`), turns it away (`Reject`) or
+bans its author (`Block`) - each published at their own pod and checked
+there, like every other ask.
+
+A moderator gets a Settings page: rename the forum, rename a category,
+manage moderators and members, and make a new category. Each row carries
+Open and Private. Every change is an ordinary activity - a `Create` of a
+`Group`, an `Update`, an `Add` or a `Remove` - published at the moderator's
+own pod and fetched back before it is applied.
+
+**Open or private belongs to the category, and only the forum changes it.**
+Joining does not, being admitted does not, and being removed does not. On
+the wire it is `manuallyApprovesFollowers` on the Group.
+
+A private category means all of this, and no more:
+
+- Its trees are readable by named WebIDs only. The actor stays public, since
+  a server that cannot read the actor cannot deliver to the category.
+- It publishes `c/<slug>/ap/members`, the WebIDs that may read it, readable
+  only by those same WebIDs. The forum's own WebID is one of them, because
+  the forum fetches every post back from its author's pod.
+- Every join waits for a moderator, and admitting somebody requires a WebID.
+  A follower without one is let go with a `Reject`: carrying posts to
+  somebody refused the pages would not be private at all.
+- A member's post is addressed to the category's followers collection rather
+  than to the public, and is written into a container of its own on the
+  member's pod whose access rule names the same reader list. One container
+  per category, rewritten on each post, so one rule covers that member's
+  whole history there.
+
+What it does NOT mean, and the page says so in the box before anyone writes:
+an ejected reader keeps a given author's older posts until that author next
+writes; somebody admitted today reads the whole history; posts written while
+the category was open stay public; pod operators hold the plaintext; and any
+admitted member can copy anything.
+
+The command-line equivalents are `--members-only <slug>` and
+`--member <slug>:<webid>`. A draft FEP for the layout and this model is in
+[fep-draft.md](fep-draft.md).
+To reply, a reader signs in once with a
+Mastodon account: the page registers itself on their server, sends them to
+approve it, and keeps the token in their browser; a reply is posted from
+their account with the category mentioned, and answers the thread's last
+post as their server resolves it. The reply shows in the thread once the
+forum's host has placed it; until then the reader sees their own copy marked
+as waiting. A reader with a pod account is pointed at FediPod and the
+category's address; a reader with nothing is pointed at sign-up.
+
+## Attaching to a Gateway
+
+```
+node packages/fedipod-bb/bin/fedipod-bb.mjs attach --home DIR --front https://fedipod.net
+```
+
+Takes `@<handle>@fedipod.net` for the forum and one address per category,
+each a row of its own at the Gateway pointing at that category's tree on the
+pod and at the forum's one inbox. Deliveries arrive verified at the front;
+the next `start` republishes every actor under its front address.
+
+A post is voted up or down, the way Lemmy federates a vote: a `Like` for up,
+a `Dislike` for down, and the `Undo` of whichever was cast to take it back.
+One person has one vote, so voting the other way is a changed mind rather
+than a second vote. The up count is AS2's `likes` on the post's copy.
+ActivityStreams has no property for a down count and none is invented: it is
+an ordinary `Collection` published beside the copy, at that copy's address
+with `-dislikes` after it, and taken down again when it reaches nought.
+The copy also carries the count itself, as `dislikes` shaped like `likes`,
+which is the forum's own word; the page reads it there rather than asking
+for a document beside every post it shows.

package/bin/fedipod-bb.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// fedipod-bb.mjs — run a forum from this machine.
+//
+//   fedipod-bb credential --home DIR --email you@example.org --pod https://forum.example/ [--issuer URL]
+//     Mint the forum's pod credential at the pod's server (the password is
+//     asked at the terminal) and save it as DIR/credential.json.
+//   fedipod-bb init --home DIR --handle forum --name "The Forum" \
+//       [--moderator-webid https://you.example/profile/card#me] \
+//       --category gardening:Gardening --category compost:Compost [--moderator <actor>]
+//     Writes the forum's config and containers to the pod; publishes nothing yet.
+//   fedipod-bb start --home DIR
+//     Host the forum from here. Publishes every actor on first start, then
+//     drains the forum's inbox, places posts in topics and carries them.
+//     Several moderators may run this on their own machines; one acts, the
+//     others watch and take over when it stops.
+//   fedipod-bb status --home DIR
+//     What the forum's state says, without hosting.
+//   fedipod-bb attach --home DIR --front https://fedipod.net
+//     Take addresses at a Gateway: @<handle>@<front> for the forum and one
+//     per category. Deliveries arrive verified at the front and are written
+//     into the forum's inbox; every actor is republished with its front ids
+//     on the next start.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { ForumAgent } from '../src/forum-agent.mjs';
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const flag = (name) => { const i = args.indexOf('--' + name); return i >= 0 ? args[i + 1] : null; };
+const flags = (name) => args.flatMap((a, i) => (a === '--' + name && args[i + 1] ? [args[i + 1]] : []));
+const home = flag('home') || process.env.FEDIPOD_BB_HOME;
+if (!home) { console.error('--home DIR is required'); process.exit(2); }
+
+const logFile = path.join(home, 'forum.log');
+const log = (...a) => {
+  const line = `${new Date().toISOString()} ${a.join(' ')}`;
+  console.log('[bb]', ...a);
+  try { fs.appendFileSync(logFile, line + '\n'); } catch { /* logging never throws */ }
+};
+
+// --reply-policy open|review, checked here so a typo does not quietly become
+// the strictest reading of it.
+const replyPolicy = () => {
+  const said = String(flag('reply-policy') || '').toLowerCase();
+  if (said !== 'open' && said !== 'review') {
+    console.error('--reply-policy takes open or review');
+    process.exit(2);
+  }
+  return said;
+};
+
+if (cmd === 'credential') {
+  const email = flag('email');
+  const pod = flag('pod');
+  if (!email || !pod) { console.error('--email and --pod are required'); process.exit(2); }
+  const { mintForumCredential } = await import('../src/credential.mjs');
+  try {
+    const file = await mintForumCredential({ email, pod, home, issuer: flag('issuer'), root: flag('root') || 'fedipod-bb/' });
+    console.log(`credential minted and saved to ${file}`);
+  } catch (e) { console.error(e.message); process.exit(1); }
+} else if (cmd === 'init') {
+  const handle = flag('handle');
+  if (!handle) { console.error('--handle is required'); process.exit(2); }
+  const categories = flags('category').map(c => {
+    const [slug, name] = c.split(':');
+    return { slug, name: name || slug };
+  });
+  const agent = new ForumAgent({ home, log });
+  const cfg = await agent.init({
+    handle, name: flag('name') || handle, categories, moderators: flags('moderator'),
+    // A moderator's WebID, so the pod itself can let them read the queue;
+    // their actor id is what the wire uses and cannot be granted access.
+    moderatorWebIds: flags('moderator-webid'),
+    // A members-only category, and who may read it: --members-only <slug>
+    // and --member <slug>:<webid>. Only a WebID can be named; a follower
+    // from Mastodon has none, and serving them is the Server build's job.
+    membersOnly: flags('members-only'),
+    memberWebIds: flags('member').reduce((m, v) => {
+      const at = v.indexOf(':');
+      if (at < 1) return m;
+      const slug = v.slice(0, at);
+      (m[slug] ||= []).push(v.slice(at + 1));
+      return m;
+    }, {}),
+    approveJoins: args.includes('--approve-joins'), review: args.includes('--review'),
+    // What becomes of a post from somebody who has not joined: `open` takes
+    // the post as the joining, `review` holds it for a moderator. A private
+    // category holds it whatever this says.
+    ...(flag('reply-policy') ? { replyPolicy: replyPolicy() } : {}),
+  });
+  console.log(JSON.stringify(cfg, null, 2));
+} else if (cmd === 'start') {
+  const { runForum } = await import('../src/run.mjs');
+  const agent = await runForum({ home, log });
+  if (!agent) process.exit(1);
+} else if (cmd === 'attach') {
+  const front = flag('front');
+  if (!front) { console.error('--front <https://gateway-origin> is required'); process.exit(2); }
+  const agent = new ForumAgent({ home, log });
+  if (!await agent.connect({ act: false })) { console.error('nothing to attach — run init first'); process.exit(1); }
+  const r = await agent.attach({ front });
+  console.log(`attached at ${r.front}: ${r.handles.map(h => '@' + h).join(', ')} — start the forum to publish its new addresses`);
+  process.exit(0);
+} else if (cmd === 'status') {
+  const agent = new ForumAgent({ home, log: () => {} });
+  const up = await agent.connect({ act: false });
+  console.log(JSON.stringify(up ? agent.status() : { mode: 'unconfigured' }, null, 2));
+  process.exit(0);
+} else {
+  console.log('usage: fedipod-bb <credential|init|start|status|attach> --home DIR [--email E --pod URL | --handle H --name N --category slug:Name … --reply-policy open|review | --front URL]');
+  process.exit(2);
+}

package/fep-draft.md

@@ -0,0 +1,110 @@
+---
+slug: "xxxx"
+authors: Jeff Zucker <https://jeffz.solidcommunity.net/profile/card#me>
+status: DRAFT
+dateReceived: 2026-09-16
+---
+# A discussion forum whose record is a Solid pod
+
+## Summary
+
+A forum — categories, topics, posts, moderation — kept as ActivityPub
+documents on a Solid pod and served from static pages. No forum database and no
+forum server. Readers read the pod. Members write to their own pods. A host
+run by the moderators drains one inbox and writes the record back.
+
+Existing FEPs cover the wire. This says where the documents live and how a
+category is made private with the pod's own access control.
+
+## Requirements
+
+The key words MUST, SHOULD and MAY are to be interpreted as in RFC 2119.
+
+## The layout
+
+One container, by convention `fedipod-bb/`, on the forum's pod.
+
+    ap/actor              the site, an Application
+    ap/inbox/             ONE inbox; every category names it as its sharedInbox
+    ap/categories         OrderedCollection of category actor ids
+    ap/administrators     FEP-baf5
+    ap-state/             owner-only: config, lease, keys
+    c/<slug>/             one per category, an ordinary group's tree
+      ap/actor            a Group (FEP-1b12)
+      ap/followers        its membership
+      ap/moderators       its roster; the actor's attributedTo
+      ap/members          who may READ it; present only when it is private
+      ap/topics(-N)       OrderedCollection of topic ids
+      ap/topic/<tid>(-N)  one topic: a context collection (FEP-7888)
+      ap/cache/<sha16>    the forum's readable copy of a member's post
+
+A topic is an `OrderedCollection` whose `attributedTo` is the category, whose
+`orderedItems` are the authors' own post ids, and whose `name` is the topic's
+title — given by the person opening it, in the `name` of their `Create`, and
+never taken from the post. Every post in it carries `context` naming it.
+
+Posts are named, not copied, in the record: the author's server stays the
+authority on edits and deletions (FEP-fe34). Because a browser cannot fetch
+from a stranger's server, the forum ALSO writes a verified copy under
+`ap/cache/`, replaced by a `Tombstone` (FEP-4f05) when the original goes.
+
+## Open and private
+
+Open or private is a property of the category, set by its administrators. It
+MUST NOT change as a side effect of anybody joining, being admitted, or being
+removed. On the wire it is `manuallyApprovesFollowers` on the Group.
+
+A private category:
+
+1. Its trees are readable by named WebIDs only; the actor stays public, since
+   a server that cannot read the actor cannot deliver to it.
+2. It publishes `ap/members`, an OrderedCollection of the WebIDs that may read
+   it, itself readable only by those WebIDs. The forum's own WebID is among
+   them, because the forum dereferences each post at its author's pod.
+3. Every join waits for a moderator, and admitting somebody requires a WebID.
+   A follower without one MUST be let go with a `Reject`: carrying posts to
+   someone who is refused the pages is not privacy.
+4. Members address their posts to the category's followers collection, not to
+   `as:Public`. A group MUST NOT otherwise carry a non-public post; a private
+   group carries them because its membership is exactly the set already
+   permitted to read them.
+5. The member's own copy is written into a container on the member's pod whose
+   access rule names the same reader list. One container per category, so one
+   rule covers that member's whole history there and is rewritten with each
+   post.
+
+## Votes
+
+A vote is a `Like` or a `Dislike` addressed to the category, and the `Undo` of
+whichever was cast to take it back; one actor MAY hold one of them per object,
+so the second replaces the first. The up count is published as the object's
+`likes`. ActivityStreams has no property for a down count: implementations
+MUST NOT invent one. This publishes it as a `Collection` beside the object's
+cached copy, at that copy's address with `-dislikes` after it, absent at nought.
+
+## Security considerations
+
+- **Revocation is not uniform.** The forum revokes its own copies at once.
+  Members' own copies are behind rules only those members can write, so an
+  ejected reader keeps a given author's older posts until that author next
+  writes. Implementations SHOULD rewrite the rule on every post.
+- **Admission is retroactive.** A new member reads the whole history, because
+  the forum's copies are re-granted as a set.
+- **Not confidentiality.** This is access control. Pod operators, and any
+  gateway a delivery passes through, hold the plaintext. Any admitted member
+  can copy anything. A category MUST NOT claim more than that.
+- **Nothing is retroactive at the switch.** Posts written while a category was
+  open were published to the world and stay so.
+- An unsigned append to a public inbox proves nothing, so a moderator's
+  request is published at the moderator's own pod and fetched back from there
+  before it is applied (FEP-fe34).
+
+## References
+
+FEP-1b12 group federation · FEP-7888 contexts · FEP-f15d relocation ·
+FEP-4f05 tombstones · FEP-fe34 origin · FEP-7458 replies · FEP-b2b8 long-form ·
+FEP-baf5 administrators · FEP-044f quotes · W3C Web Access Control · Solid-OIDC
+
+## Copyright
+
+CC0 1.0 Universal.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "fedipod-bb",
+  "version": "0.2.0",
+  "description": "FediPod-BB: a forum website whose record lives on a Solid pod.",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.mjs",
+  "bin": {
+    "fedipod-bb": "bin/fedipod-bb.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "site",
+    "README.md",
+    "fep-draft.md"
+  ],
+  "scripts": {
+    "pretest": "node scripts/link-fedipod.mjs",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "fedipod": "^1.42.0",
+    "fediverse-session": "^0.2.1"
+  }
+}