fedipod 0.8.0

package/lib/social.mjs

@@ -0,0 +1,505 @@
+// social.mjs — outbound social actions (follow, like, announce, delete)
+// shared by the admin API and the Mastodon-API facade. Each action delivers
+// the activity and mirrors state into the store; the store keeps the
+// activity a later Undo must name.
+
+import crypto from 'node:crypto';
+import * as wire from './wire.mjs';
+import { dropFollower } from './store.mjs';
+
+// WebFinger, ours rather than fedify's — v2 dropped lookupWebFinger.
+//
+// Better here anyway: the host comes out of a handle, and a handle can arrive
+// in a MENTION inside a post somebody else wrote, so it is remote input and
+// belongs behind the same SSRF guard as every other outbound request. fedify's
+// lookup did not go through ours. https only, because a handle resolved over
+// plaintext is a handle anyone on the path can answer for.
+export async function lookupWebFinger(acct) {
+  const clean = String(acct || '').replace(/^acct:/, '');
+  const at = clean.lastIndexOf('@');
+  if (at < 1) return null;
+  const [user, host] = [clean.slice(0, at), clean.slice(at + 1)];
+  if (!host || /[/\\?#]/.test(host)) return null;
+  const { safeFetch, readCapped } = await import('./safefetch.mjs');
+  const url = `https://${host}/.well-known/webfinger?resource=${encodeURIComponent(`acct:${clean}`)}`;
+  const res = await safeFetch(url, {
+    headers: { accept: 'application/jrd+json, application/json' },
+  }).catch(() => null);
+  if (!res || res.status >= 400) return null;
+  try { return JSON.parse(await readCapped(res, 256 * 1024)); } catch { return null; }
+}
+
+export const selfLink = (jrd) => jrd?.links?.find(l => l.rel === 'self' &&
+  /application\/(activity\+json|ld\+json)/.test(l.type || ''));
+
+// A WebFinger server can name an actor on ANY host, and until this ran we
+// believed it. The handle is remote input — it arrives in the Mention tags of a
+// note somebody else wrote — so evil.example could answer for `@x@evil.example`
+// with a real, busy actor elsewhere, and a reply that carried that mention was
+// addressed, tagged and DELIVERED to a third party who had nothing to do with
+// the thread, over our signature.
+//
+// The host cannot simply be required to match: `@user@example.com` served by
+// mastodon.example is the ordinary delegated setup and the whole point of
+// WebFinger. So ask the ACTOR's own host who it says that actor is, and require
+// it to come back to the same document. A server may name anyone; it cannot
+// make that person's server agree. This is the round trip Mastodon does.
+//
+// Only when the two hosts differ — same-host is self-consistent by
+// construction, so the common case costs no extra request.
+export async function confirmDelegation(asked, doc, lookup = lookupWebFinger) {
+  let home;
+  try { home = new URL(doc.id).host.toLowerCase(); }
+  catch { throw new Error(`actor id is not a URL (${doc.id})`); }
+  if (home === asked.toLowerCase()) return;
+  const user = doc.preferredUsername;
+  if (!user) {
+    throw new Error(`${asked} points at ${doc.id} on another host, which names no `
+      + 'username to confirm it by');
+  }
+  const back = await lookup(`acct:${user}@${home}`);
+  if (selfLink(back)?.href !== doc.id) {
+    throw new Error(`${asked} claims ${doc.id}, but ${home} does not agree that is `
+      + `@${user}@${home} — refusing to take one host's word for another's actor`);
+  }
+}
+
+// acct:user@host → verified actor doc (cached by fetchAP), or throws.
+export async function resolveHandle(agent, handle) {
+  const clean = String(handle || '').replace(/^@/, '');
+  if (!/^[^@]+@[^@]+$/.test(clean)) throw new Error('handle must look like user@host');
+  if (agent.store.isBlocked('https://' + clean.split('@')[1] + '/')) throw new Error('domain is blocked');
+  const jrd = await lookupWebFinger('acct:' + clean);
+  const self = selfLink(jrd);
+  if (!self?.href) throw new Error(`webfinger found no actor for ${clean}`);
+  const doc = await agent.intake.fetchAP(self.href);
+  if (!doc?.id) throw new Error(`actor document unusable for ${clean}`);
+  if (agent.store.isBlocked(doc.id)) throw new Error('actor is blocked');
+  await confirmDelegation(clean.slice(clean.lastIndexOf('@') + 1), doc);
+  // Counts live in the collections, not the actor document, so a client asking
+  // "who is this" would otherwise be told everyone has none. Two GETs, and only
+  // when someone asked by name — never on the drain path.
+  await cacheCounts(agent, doc);
+  return doc;
+}
+
+// totalItems off the followers/following collections, stored beside the cached
+// actor. Best effort: a collection that will not answer leaves the count unset
+// rather than reported as zero, which is a different claim.
+async function cacheCounts(agent, doc) {
+  const total = async (url) => {
+    if (!url) return null;
+    try {
+      const res = await agent.intake.fetchAP(url);
+      return Number.isInteger(res?.totalItems) ? res.totalItems : null;
+    } catch { return null; }
+  };
+  const [followers, following] = await Promise.all([total(doc.followers), total(doc.following)]);
+  if (followers === null && following === null) return;
+  const actors = agent.store.getActors();
+  if (!actors[doc.id]) return;
+  actors[doc.id] = { ...actors[doc.id], counts: { followers, following } };
+  agent.store.write('actors.json', actors);
+}
+
+// `doc` skips the fetch when the caller already resolved the actor; a bulk
+// import passes publish:false and republishes the collections once at the end.
+export async function followActor(agent, actorUrl, { publish = true, doc: fetched = null } = {}) {
+  const doc = fetched || await agent.intake.fetchAP(actorUrl);
+  if (!doc?.inbox) throw new Error(`actor document unusable (${actorUrl})`);
+  if (agent.store.isBlocked(doc.id)) throw new Error('actor is blocked');
+  const contacts = agent.store.getContacts();
+  let rec = contacts.following.find(f => f.actor === doc.id);
+  if (!rec) {
+    rec = { actor: doc.id, inbox: doc.inbox, accepted: false };
+    contacts.following.push(rec);
+  }
+  const follow = wire.followActivity({ urls: agent.publisher.urls, targetActor: doc.id, serial: Date.now() });
+  rec.followActivity = follow;               // kept for a later Undo
+  agent.store.setContacts(contacts);
+  await agent.deliverer.deliver(doc.inbox, follow);
+  if (publish) await agent.publisher.publishCollections({ following: true, pending: true });
+  return doc;
+}
+
+export async function followHandle(agent, handle) {
+  const doc = await resolveHandle(agent, handle);
+  await followActor(agent, doc.id);
+  const clean = String(handle || '').replace(/^@/, '');
+  const contacts = agent.store.getContacts();
+  const rec = contacts.following.find(f => f.actor === doc.id);
+  if (rec && !rec.handle) { rec.handle = clean; agent.store.setContacts(contacts); }
+  return { ok: true, actor: doc.id };
+}
+
+export async function unfollowActor(agent, actor) {
+  const contacts = agent.store.getContacts();
+  const rec = contacts.following.find(f => f.actor === actor);
+  if (!rec) throw new Error('not following that actor');
+  if (rec.followActivity) {
+    await agent.deliverer.deliver(rec.inbox,
+      wire.undoActivity({ urls: agent.publisher.urls, activity: rec.followActivity, serial: Date.now() }));
+  }
+  contacts.following = contacts.following.filter(f => f.actor !== actor);
+  agent.store.setContacts(contacts);
+  await agent.publisher.publishCollections({ following: true, pending: true });
+  return { ok: true };
+}
+
+export async function favourite(agent, s) {
+  if (s.favourited) return s;
+  const doc = await agent.intake.fetchAP(s.actor);
+  if (!doc?.inbox) throw new Error('author inbox unavailable');
+  const act = wire.likeActivity({ urls: agent.publisher.urls, noteId: s.noteId, serial: Date.now() });
+  await agent.deliverer.deliver(doc.endpoints?.sharedInbox || doc.inbox, act);
+  return agent.store.updateStatus(s.noteId, { favourited: true, likeActivity: act });
+}
+
+export async function unfavourite(agent, s) {
+  if (s.likeActivity) {
+    const doc = await agent.intake.fetchAP(s.actor).catch(() => null);
+    if (doc?.inbox) {
+      await agent.deliverer.deliver(doc.endpoints?.sharedInbox || doc.inbox,
+        wire.undoActivity({ urls: agent.publisher.urls, activity: s.likeActivity, serial: Date.now() }));
+    }
+  }
+  return agent.store.updateStatus(s.noteId, { favourited: false, likeActivity: undefined });
+}
+
+// Announce goes to our followers (that's what boosting is) and to the author.
+export async function reblog(agent, s) {
+  if (s.reblogged) return s;
+  const { urls } = agent.publisher;
+  const act = wire.announceActivity({ urls, object: s.noteId, serial: Date.now() });
+  const inboxes = new Set(agent.store.getContacts().followers
+    .map(f => f.sharedInbox || f.inbox).filter(Boolean));
+  if (s.actor !== urls.actor) {
+    const doc = await agent.intake.fetchAP(s.actor).catch(() => null);
+    if (doc?.inbox) inboxes.add(doc.endpoints?.sharedInbox || doc.inbox);
+  }
+  await agent.deliverer.deliverToAll([...inboxes], act);
+  // Mark it boosted before recording it: a failed outbox write costs one
+  // missing entry, a failed status write would let a retry announce twice.
+  const updated = agent.store.updateStatus(s.noteId, { reblogged: true, announceActivity: act });
+  await agent.publisher.recordOutbox(act);
+  return updated;
+}
+
+export async function unreblog(agent, s) {
+  if (s.announceActivity) {
+    const undo = wire.undoActivity({ urls: agent.publisher.urls, activity: s.announceActivity, serial: Date.now() });
+    const inboxes = new Set(agent.store.getContacts().followers
+      .map(f => f.sharedInbox || f.inbox).filter(Boolean));
+    const doc = await agent.intake.fetchAP(s.actor).catch(() => null);
+    if (doc?.inbox && s.actor !== agent.publisher.urls.actor) inboxes.add(doc.endpoints?.sharedInbox || doc.inbox);
+    await agent.deliverer.deliverToAll([...inboxes], undo);
+    await agent.publisher.unrecordOutbox(i => i?.id === s.announceActivity.id);
+  }
+  return agent.store.updateStatus(s.noteId, { reblogged: false, announceActivity: undefined });
+}
+
+// Group: end a following we will no longer carry. Forgetting them locally is
+// not enough — without the Reject their server keeps the relationship and they
+// keep receiving everything the group announces. Muting them too, because an
+// ejection anyone can undo by re-following is not an ejection; a re-follow is
+// still auto-accepted, but nothing of theirs gets carried.
+export async function ejectFollower(agent, actor) {
+  const { urls } = agent.publisher;
+  const contacts = agent.store.getContacts();
+  const rec = contacts.followers.find(f => f.actor === actor);
+  if (!rec) throw new Error('not a member');
+  dropFollower(contacts, actor, 'ejected');
+  agent.store.setContacts(contacts);
+  const muted = agent.store.getMuted();
+  muted.actors = [...new Set([...muted.actors, actor])];
+  agent.store.setMuted(muted);
+  await agent.publisher.publishCollections({ followers: true });
+  // The ban is broadcast to the membership (FEP-1b12), so their servers can
+  // mirror it. Never sent to the ejected member — they get the Reject below.
+  await announceModeration(agent,
+    wire.blockActivity({ urls, targetActor: actor, serial: Date.now() }))
+    .catch(e => agent.log?.(`moderation announce failed: ${e.message}`));
+  // A Bluesky-side member's departure sticks by blocking the DID.
+  if (rec.bsky) {
+    await agent.bskygroup?.blockDid(rec.bsky.did)
+      .catch(e => agent.log?.(`bluesky block failed for ${rec.bsky.handle}: ${e.message}`));
+    return { ok: true, actor, told: true };
+  }
+  if (rec.inbox) {
+    await agent.deliverer.deliver(rec.inbox, wire.rejectActivity({
+      urls,
+      followActivity: { id: rec.followId, type: 'Follow', actor, object: urls.actor },
+      serial: Date.now(),
+    }));
+  }
+  return { ok: true, actor, told: !!rec.inbox };
+}
+
+// Group: answer a held join request. Admitting is the Accept onFollow would
+// have sent immediately had the group not been gated.
+export async function admitRequest(agent, actor, { publish = true } = {}) {
+  const reqs = agent.store.getRequests();
+  const req = reqs.find(r => r.actor === actor);
+  if (!req) throw new Error('no such request');
+  const contacts = agent.store.getContacts();
+  if (!contacts.followers.some(f => f.actor === actor)) {
+    // Admitting a bridged Bluesky member retires their Bluesky-only record,
+    // the same way an ungated group's follow does: one person, one membership.
+    const bridgedDid = /^https:\/\/bsky\.brid\.gy\/ap\/(did:[^/]+)$/.exec(actor)?.[1];
+    if (bridgedDid) contacts.followers = contacts.followers.filter(f => f.bsky?.did !== bridgedDid);
+    contacts.followers.push(req.bsky
+      ? { actor, bsky: req.bsky }
+      : { actor, inbox: req.inbox, sharedInbox: req.sharedInbox, followId: req.activity?.id });
+    agent.store.setContacts(contacts);
+    agent.store.addNotification({ type: 'follow', actor, ...(req.bsky ? { bsky: true } : {}) });
+  }
+  agent.store.setRequests(reqs.filter(r => r.actor !== actor));
+  // A Bluesky-only member has no inbox and no Accept to receive; the follow
+  // already stands on their side. The one-time bridge nudge goes out instead.
+  if (req.bsky) {
+    await agent.bskygroup?.nudgeOnce(contacts.followers.find(f => f.actor === actor));
+    return { ok: true, actor };
+  }
+  // A bulk admit passes publish:false and republishes once for the lot.
+  if (publish) await agent.publisher.publishCollections({ followers: true, pending: true });
+  await agent.deliverer.deliver(req.inbox, wire.acceptActivity({
+    urls: agent.publisher.urls, followActivity: req.activity, serial: Date.now(),
+  }));
+  return { ok: true, actor };
+}
+
+// Refusing is not a ban: they may ask again, and the queue is where you would
+// see that. Eject is the sticky one, because it mutes.
+export async function refuseRequest(agent, actor) {
+  const reqs = agent.store.getRequests();
+  const req = reqs.find(r => r.actor === actor);
+  if (!req) throw new Error('no such request');
+  agent.store.setRequests(reqs.filter(r => r.actor !== actor));
+  await agent.publisher?.publishCollections({ pending: true }).catch(() => {});
+  // No Reject can reach a Bluesky-only requester, so the refusal is enforced
+  // where it can be: their DID is blocked.
+  if (req.bsky) {
+    await agent.bskygroup?.blockDid(req.bsky.did)
+      .catch(e => agent.log?.(`bluesky block failed for ${req.bsky.handle}: ${e.message}`));
+    return { ok: true, actor };
+  }
+  await agent.deliverer.deliver(req.inbox, wire.rejectActivity({
+    urls: agent.publisher.urls, followActivity: req.activity, serial: Date.now(),
+  }));
+  return { ok: true, actor };
+}
+
+// Group: unsay an Announce. The work is in Intake because an upstream Delete
+// has to do the same thing, and both must use the recipient set amplify used.
+export async function retractAnnouncement(agent, noteId) {
+  return agent.intake.retract(noteId);
+}
+
+// Remove an own note everywhere: Delete→followers, remote note + outbox,
+// local pod RDF, statuses mirror.
+//
+// Two of the three pod deletes have to land, and both are checked. While the
+// note document answers, anyone holding its id can still read a post its author
+// deleted — and the `-create` beside it EMBEDS the whole note, so leaving that
+// one behind publishes the same content under another name. A failure keeps the
+// post here and says so, rather than reporting a deletion that did not happen:
+// removing it locally would leave nothing to try again with, and nothing to see
+// that it is still up.
+// A vote is the fediverse convention: one bare Note per chosen option, whose
+// name IS the option, inReplyTo the question, addressed to the question's
+// author alone. The documents are stored for dereference but never listed —
+// not in the outbox, not in the local index.
+export async function votePoll(agent, s, choices) {
+  const { urls } = agent.publisher;
+  const poll = s.poll || {};
+  const opts = poll.options || [];
+  if (poll.closed || (poll.expiresAt && Date.parse(poll.expiresAt) < Date.now())) {
+    return { ok: false, error: 'this poll has closed' };
+  }
+  if (poll.voted) return { ok: false, error: 'already voted' };
+  const picks = [...new Set(choices)].filter(i => i >= 0 && i < opts.length);
+  if (!picks.length) return { ok: false, error: 'invalid choice' };
+  if (!poll.multiple && picks.length > 1) return { ok: false, error: 'this poll takes one choice' };
+  const author = await agent.intake.fetchAP(s.actor).catch(() => null);
+  const inbox = author?.endpoints?.sharedInbox || author?.inbox;
+  if (!inbox) return { ok: false, error: 'could not reach the poll author' };
+  const published = new Date().toISOString();
+  for (const i of picks) {
+    const id = urls.notes + published.slice(0, 10) + '-vote-' + crypto.randomBytes(4).toString('hex');
+    const note = {
+      '@context': wire.AS_CTX, id, type: 'Note',
+      attributedTo: urls.actor, name: opts[i].title,
+      inReplyTo: s.noteId, published, to: [s.actor],
+    };
+    const create = {
+      '@context': wire.AS_CTX, id: wire.createActivityId(id), type: 'Create',
+      actor: urls.actor, published, to: [s.actor], object: note,
+    };
+    await agent.remote.putJson(id, note);
+    await agent.remote.putJson(create.id, create);
+    await agent.deliverer.deliverToAll([inbox], create);
+  }
+  agent.store.updateStatus(s.noteId, {
+    poll: {
+      ...poll, voted: true, ownVotes: picks,
+      options: opts.map((o, j) => (picks.includes(j) ? { ...o, votes: (o.votes || 0) + 1 } : o)),
+    },
+  });
+  return { ok: true };
+}
+
+export async function deleteNote(agent, s) {
+  const { urls } = agent.publisher;
+  const inboxes = agent.store.getContacts().followers
+    .map(f => f.sharedInbox || f.inbox).filter(Boolean);
+  await agent.deliverer.deliverToAll(inboxes, wire.deleteActivity({ urls, noteId: s.noteId }));
+
+  // The note is REPLACED with a Tombstone rather than removed, so a peer that
+  // dereferences it learns the post was deleted instead of a bare 404 (§7.4).
+  // The Tombstone must stay readable; the container above it is owner-only, so
+  // the ACL cannot be inherited. The Create activity is the withdrawn action,
+  // not the object, so it is deleted outright.
+  const stuck = [];
+  const deletedAt = new Date().toISOString();
+  try {
+    await agent.remote.putJson(s.noteId, wire.noteTombstone(s.noteId, deletedAt));
+    await agent.remote.setAcl(s.noteId, ['Read']);
+  } catch { stuck.push(s.noteId); }
+  if (!await agent.remote.delete(wire.createActivityId(s.noteId)).catch(() => false)) {
+    stuck.push(wire.createActivityId(s.noteId));
+  }
+  if (stuck.length) {
+    agent.log?.(`delete ${s.noteId}: the pod kept ${stuck.length} document(s) — the post is STILL PUBLISHED`);
+    return {
+      ok: false, stillPublished: stuck,
+      error: 'the pod would not remove the post — it is still published, and has been kept here so you can try again',
+    };
+  }
+  // Empty, and referenced by nothing once the note is gone.
+  await agent.remote.delete(wire.repliesId(s.noteId)).catch(() => {});
+
+  // The Bluesky mirror goes with the post. Best-effort: a mirror the far side
+  // already lost is not a reason to keep the post here.
+  if (s.atproto?.uri && agent.atproto?.connected()) {
+    await agent.atproto.deleteCrossPost(s.atproto.uri)
+      .then(() => agent.log?.(`bluesky mirror deleted: ${s.atproto.uri}`))
+      .catch(e => agent.log?.(`bluesky mirror not deleted (${e.message}): ${s.atproto.uri}`));
+  }
+
+  // The note, and our own boost of it if there was one.
+  await agent.publisher.unrecordOutbox(i => i === s.noteId || (i?.id && i.id === s.announceActivity?.id));
+  if (s.slug) await agent.local.delete(agent.local.fedi + 'posts/' + s.slug).catch(() => {});
+  agent.store.removeStatus(s.noteId);
+  return { ok: true };
+}
+
+// FEP-1b12: a GROUP's moderation is announced to its followers, so their
+// servers can mirror the action. Group moderation only — a person's blocks
+// never go on the wire (that is also the spec's own SHOULD NOT), which is why
+// the guard lives here rather than in every caller. Never delivered to the
+// moderated party; the announce goes to the membership.
+export async function announceModeration(agent, activity) {
+  if (agent.store.getConfig()?.kind !== 'group') return null;
+  const { urls } = agent.publisher;
+  const act = wire.announceActivity({ urls, object: activity, serial: Date.now(), audience: urls.actor });
+  const inboxes = [...new Set(agent.store.getContacts().followers
+    .map(f => f.sharedInbox || f.inbox).filter(Boolean))];
+  await agent.deliverer.deliverToAll(inboxes, act);
+  await agent.publisher.recordOutbox(act);
+  return act;
+}
+
+// A block is state, not speech: the list changes and the follow ends, and
+// nothing is delivered TO THE BLOCKED PARTY (§6.10). Intake already refuses a
+// blocked author on arrival. A group additionally announces the ban to its
+// members (FEP-1b12) — announceModeration keeps a person's blocks silent.
+export async function blockActor(agent, actorUrl) {
+  if (!/^https?:\/\/\S+$/.test(String(actorUrl || ''))) throw new Error('actor must be a URL');
+  const b = agent.store.getBlocklist();
+  if (!b.actors.includes(actorUrl)) b.actors.push(actorUrl);
+  agent.store.setBlocklist(b);
+  await unfollowActor(agent, actorUrl).catch(() => {});   // not following is fine
+  await agent.publisher?.publishCollections({ blocked: true }).catch(() => {});
+  await announceModeration(agent,
+    wire.blockActivity({ urls: agent.publisher.urls, targetActor: actorUrl, serial: Date.now() }))
+    .catch(e => agent.log?.(`moderation announce failed: ${e.message}`));
+  return { ok: true, actor: actorUrl };
+}
+
+export async function unblockActor(agent, actorUrl) {
+  const b = agent.store.getBlocklist();
+  b.actors = b.actors.filter(a => a !== actorUrl);
+  agent.store.setBlocklist(b);
+  await agent.publisher?.publishCollections({ blocked: true }).catch(() => {});
+  // The unban is announced as the Undo of the ban, the ban re-stated inside it
+  // — its id was a fragment nobody stored, so receivers match on the shape.
+  await announceModeration(agent, wire.undoActivity({
+    urls: agent.publisher.urls,
+    activity: { type: 'Block', actor: agent.publisher.urls.actor, object: actorUrl },
+    serial: Date.now(),
+  })).catch(e => agent.log?.(`moderation announce failed: ${e.message}`));
+  return { ok: true, actor: actorUrl };
+}
+
+// Apply (or refuse) one queued moderation request — an action a LISTED
+// moderator asked for over federation. Deliveries carry nothing that proves
+// the sender, which is exactly why these wait in a queue for the operator
+// instead of running on arrival; applying one is the operator vouching for it.
+export async function applyModeration(agent, entry) {
+  const { urls } = agent.publisher;
+  const target = typeof entry.activity?.object === 'string'
+    ? entry.activity.object : entry.activity?.object?.id;
+  switch (entry.type) {
+    case 'Block': {
+      if (!target) throw new Error('the queued Block names nobody');
+      // A member is ejected (which mutes and announces the ban); a stranger is
+      // simply blocked. Either way the ban is broadcast once.
+      const member = agent.store.getContacts().followers.some(f => f.actor === target);
+      return member ? ejectFollower(agent, target) : blockActor(agent, target);
+    }
+    case 'Undo': {
+      const inner = entry.activity?.object;
+      const unbanned = typeof inner === 'object' && inner?.type === 'Block'
+        ? (typeof inner.object === 'string' ? inner.object : inner.object?.id) : null;
+      if (!unbanned) throw new Error('the queued Undo does not name a Block');
+      const muted = agent.store.getMuted();
+      muted.actors = muted.actors.filter(a => a !== unbanned);
+      agent.store.setMuted(muted);
+      return unblockActor(agent, unbanned);
+    }
+    case 'Delete': {
+      if (!target) throw new Error('the queued Delete names nothing');
+      // Removing a post from the group is unsaying its carry.
+      return agent.intake.retract(target);
+    }
+    case 'Add':
+    case 'Remove': {
+      if (!target) throw new Error('the queued roster change names nobody');
+      const cfg = { ...agent.store.getConfig() };
+      const prev = cfg.moderators || [];
+      cfg.moderators = entry.type === 'Add'
+        ? [...new Set([...prev, target])]
+        : prev.filter(m => m !== target);
+      agent.store.setConfig(cfg);
+      if (agent.publisher) agent.publisher.config.moderators = cfg.moderators;
+      await agent.publisher.publishProfile();
+      await announceModeration(agent, wire.addRemoveActivity({
+        urls, type: entry.type, object: target, target: urls.moderators, serial: Date.now(),
+      })).catch(e => agent.log?.(`moderation announce failed: ${e.message}`));
+      return { ok: true, moderators: cfg.moderators };
+    }
+    default: throw new Error(`no way to apply a queued ${entry.type}`);
+  }
+}
+
+// Pin or unpin an own post. Republishing the featured collection is what makes
+// the pin real to anyone else — the actor document names that collection, and
+// a visitor's server reads it, so the profile is republished too (it skips
+// itself when nothing changed).
+export async function pinStatus(agent, s, pinned) {
+  if (s.actor !== agent.publisher.urls.actor) throw new Error('not your status');
+  const updated = agent.store.updateStatus(s.noteId, { pinned: !!pinned });
+  await agent.publisher.publishFeatured().catch(e => agent.log?.(`featured: ${e.message}`));
+  agent.publisher.publishProfile?.().catch(() => {});
+  return updated || s;
+}

package/lib/storage.mjs

@@ -0,0 +1,170 @@
+// storage.mjs — a container of documents, and the two places one can live.
+//
+// The store and the RDF tree only ever do four things to a container: list its
+// children, read one, write one, remove one. Everything else an LDP server
+// offers — membership triples, content negotiation, status codes, auxiliary
+// resources — exists to satisfy HTTP. So the filesystem implementation does
+// not pretend to have any of it, and nothing serialises a container listing
+// into RDF only to parse it straight back out.
+//
+// Paths are relative to the container's base ('config.json', 'posts/n1'), and
+// a name ending in '/' is a child container, in both implementations.
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as $rdf from 'rdflib';
+
+const LDP = $rdf.Namespace('http://www.w3.org/ns/ldp#');
+const slash = (u) => (u.endsWith('/') ? u : u + '/');
+
+// A pod, local or remote. `fetchImpl` carries whatever authentication it needs.
+export class HttpStorage {
+  constructor(base, fetchImpl) {
+    this.base = slash(base);
+    this.fetchImpl = fetchImpl;
+  }
+
+  get kind() { return 'pod'; }
+
+  // The same jail FileStorage has, and for the same reason: a path here can
+  // carry `..`, encodeURI leaves both `.` and `/` alone, and fetch normalises
+  // the segments away — so a name derived from remote input could name a
+  // resource outside the container entirely. PodRdf._rel only checks the
+  // PREFIX, which a concatenated URL always satisfies, so it catches nothing.
+  _url(p) {
+    const u = new URL(encodeURI(p), this.base);
+    if (!u.href.startsWith(this.base)) throw new Error(`path escapes the container: ${p}`);
+    return u.href;
+  }
+
+  async list(sub = '', { etag } = {}) {
+    const url = this._url(sub);
+    const res = await this.fetchImpl(url, {
+      headers: { accept: 'text/turtle', ...(etag ? { 'if-none-match': etag } : {}) },
+    });
+    if (res.status === 304) return { notModified: true, names: null, etag };
+    // `missing` because a 404 is ambiguous over HTTP: a pod saying "no such
+    // container" and a proxy answering for a dead backend look identical.
+    // The caller decides whether absence is an answer here.
+    if (res.status === 404) return { notModified: false, names: [], etag: null, missing: true };
+    if (res.status >= 400) throw new Error(`container unreadable (HTTP ${res.status})`);
+    const g = $rdf.graph();
+    // Throws on malformed Turtle rather than quietly matching the wrong thing,
+    // which is the entire reason this is not a regex.
+    $rdf.parse(await res.text(), g, url, 'text/turtle');
+    const here = $rdf.sym(url);
+    const names = g.each(here, LDP('contains'), null, here)
+      .map(n => n.value)
+      .filter(u => u.startsWith(url) && u !== url)
+      .map(u => decodeURIComponent(u.slice(url.length)));
+    return { notModified: false, names, etag: res.headers.get('etag') };
+  }
+
+  async read(p, { etag } = {}) {
+    const res = await this.fetchImpl(this._url(p), {
+      headers: { accept: 'text/turtle, application/json;q=0.9, */*;q=0.8', ...(etag ? { 'if-none-match': etag } : {}) },
+    });
+    if (res.status === 304) return { ok: true, notModified: true, status: 304, body: null, etag };
+    if (res.status >= 400) return { ok: false, notModified: false, status: res.status, body: null, etag: null };
+    return { ok: true, notModified: false, status: res.status, body: await res.text(), etag: res.headers.get('etag') };
+  }
+
+  async write(p, body, contentType) {
+    const url = this._url(p);                          // outside the try, as in FileStorage
+    try {
+      const res = await this.fetchImpl(url, {
+        method: 'PUT', headers: { 'content-type': contentType }, body,
+      });
+      if (res.status < 400) return { ok: true, retry: false, why: '' };
+      // A 4xx is an answer, not a hiccup: retrying a 403 or a 409 four more
+      // times just spends the pod's write lock to be told the same thing.
+      const retry = res.status >= 500 || res.status === 429;
+      const ra = Number(res.headers?.get?.('retry-after'));
+      return {
+        ok: false, retry, why: `HTTP ${res.status}`,
+        retryAfterMs: Number.isFinite(ra) && ra > 0 ? ra * 1000 : 0,
+      };
+    } catch (e) {
+      return { ok: false, retry: true, why: e.message, retryAfterMs: 0 };
+    }
+  }
+
+  async remove(p) {
+    const url = this._url(p);                          // outside the try, as in FileStorage
+    try {
+      const res = await this.fetchImpl(url, { method: 'DELETE' });
+      return res.status < 400 || res.status === 404;
+    } catch { return false; }
+  }
+}
+
+// A directory. No server, so no round-trip and nothing to be unreachable —
+// which is why a write here is never worth retrying: an EACCES will still be
+// an EACCES in two seconds.
+export class FileStorage {
+  constructor(base) {
+    this.base = slash(base.startsWith('file:') ? base : pathToFileURL(base).href);
+    // resolve() drops the trailing separator, which the jail check below needs:
+    // '/a/b/' + sep is '/a/b//', and nothing under it starts with that.
+    this.dir = path.resolve(fileURLToPath(this.base));
+  }
+
+  get kind() { return 'files'; }
+
+  _path(p) {
+    const full = path.resolve(this.dir, decodeURIComponent(p));
+    if (full !== this.dir && !full.startsWith(this.dir + path.sep)) {
+      throw new Error(`path escapes the container: ${p}`);
+    }
+    return full;
+  }
+
+  async list(sub = '') {
+    let entries;
+    try { entries = await fsp.readdir(this._path(sub), { withFileTypes: true }); }
+    catch (e) { if (e.code === 'ENOENT') return { notModified: false, names: [], etag: null }; throw e; }
+    return {
+      notModified: false, etag: null,
+      names: entries.map(e => (e.isDirectory() ? e.name + '/' : e.name)),
+    };
+  }
+
+  // The jail check is deliberately outside the try: a path that climbs out of
+  // its container is a bug in the caller, and reporting it as "could not read"
+  // would hide it. Only actual I/O is reported.
+  async read(p) {
+    const full = this._path(p);
+    try {
+      return { ok: true, notModified: false, status: 200, body: await fsp.readFile(full, 'utf8'), etag: null };
+    } catch (e) {
+      return { ok: false, notModified: false, status: e.code === 'ENOENT' ? 404 : 500, body: null, etag: null };
+    }
+  }
+
+  // Written to a neighbour and renamed: rename is atomic on POSIX, so a reader
+  // — or a backup — never sees half a document.
+  async write(p, body) {
+    const full = this._path(p);                      // throws on an escape
+    try {
+      await fsp.mkdir(path.dirname(full), { recursive: true, mode: 0o700 });
+      const tmp = `${full}.${process.pid}.tmp`;
+      await fsp.writeFile(tmp, body, { mode: 0o600 });
+      await fsp.rename(tmp, full);
+      return { ok: true, retry: false, why: '' };
+    } catch (e) {
+      return { ok: false, retry: false, why: e.message };
+    }
+  }
+
+  async remove(p) {
+    const full = this._path(p);                      // throws on an escape
+    try { await fsp.rm(full, { force: true }); return true; }
+    catch { return false; }
+  }
+}
+
+// `file:` (or a bare path) is a directory; anything else is a pod.
+export function storageFor(base, fetchImpl) {
+  return /^https?:/i.test(base) ? new HttpStorage(base, fetchImpl) : new FileStorage(base);
+}