fedipod 0.8.0

package/lib/migrate.mjs

@@ -0,0 +1,127 @@
+// Keeping every identity on this machine at the current shape of an install.
+//
+// bbba587 fixed the DEFAULT: a new install keeps its private half — timeline,
+// contacts, blocklist, notifications, masto-tokens.json — on this machine.
+// It did nothing for the installs that already existed, and `privateRoot`
+// absent still means "on the pod" (run-agent.mjs privateUrls). So an identity
+// set up before that commit still writes every state change to a pod, and
+// still keeps its private data on a server.
+//
+// A new default only ever fixes the installs that do not exist yet. That is the
+// reason this file exists rather than a one-off script: a change to install
+// shape ships as a numbered step HERE, and `fedipod upgrade` runs the
+// pending ones over every identity under the root, not just the one you
+// happened to be in.
+
+// Bump when a step is added, and add the step to pendingSteps below.
+export const CURRENT_LAYOUT = 1;
+
+// 0 is "never stamped", which is every install made before this file existed.
+// It is not the same as "wrong": an old install may already be in the right
+// shape, and pendingSteps is what decides, per step.
+export const layoutOf = (cred) => Number(cred?.layout) || 0;
+
+// Layout 1 — the private half lives on this machine.
+//
+// Only when `privateRoot` is ABSENT. An operator who pointed it somewhere
+// deliberately, with `--private-root`, has said where they want it; a migration
+// that overrode that would be moving data on its own initiative.
+export function needsStateMove(cred) {
+  return !cred?.privateRoot;
+}
+
+export function pendingSteps(cred) {
+  const steps = [];
+  if (needsStateMove(cred)) {
+    steps.push({
+      id: 'state-off-pod',
+      what: 'move the private half off the pod, onto this machine',
+      why: 'receiving a post costs pod writes, and the timeline lives on a server',
+    });
+  }
+  return steps;
+}
+
+// True when there is nothing left to do and the stamp can be written.
+export const isCurrent = (cred) => pendingSteps(cred).length === 0;
+
+// The documents on the pod that the state tree consists of — everything the
+// move copied. Deliberately NOT "everything in the container":
+//
+//   lease.json stays. It is the single-active-agent lock, and it is on the pod
+//   precisely BECAUSE the private half is not: a lease only one machine can
+//   reach coordinates nothing. run-agent builds it from urls.state, never from
+//   privateRoot, so it goes on being used after the move.
+//
+//   .keep and .acl belong to the container, which also stays — the container is
+//   what carries the owner-only ACL that lease.json sits behind.
+//
+// RemotePod.delete's deny-list is the backstop under all of this; this list is
+// what we affirmatively claim, and the two disagreeing is a bug worth hearing
+// about rather than a file quietly surviving.
+export const MOVED_STATE_DOCS = new Set([
+  'config.json', 'queue.json', 'blocklist.json', 'contacts.json', 'muted.json',
+  'pending.json', 'requests.json', 'deadletter.json', 'statuses.json',
+  'notifications.json', 'media.json', 'actors.json', 'ids.json', 'published.json',
+  'outbox.json', 'outbox-removed.json', 'parked.json', 'tagfeed.json',
+  'intake-attempts.json', 'inbox-channel.json', 'masto-tokens.json', 'masto-markers.json',
+  'lists.json', 'filters.json', 'scheduled.json', 'webpush.json',
+  'import-state.json',
+  // Present only in pod-keys mode; a state move must carry it or the moved
+  // store cannot sign.
+  'keys.json',
+]);
+
+export const KEPT_ON_POD = new Set(['lease.json', '.keep']);
+
+// What `state --drop-remote` would remove, given a container listing. Split out
+// so the decision can be tested without a pod, and so the caller can show it
+// before doing anything.
+export function classifyRemoteState(urls, base) {
+  const drop = [];
+  const keep = [];
+  for (const u of urls) {
+    const name = String(u).slice(String(base).length).replace(/^\/+/, '');
+    if (!name || name.includes('/')) { keep.push({ url: u, name, why: 'not a document of this container' }); continue; }
+    if (KEPT_ON_POD.has(name)) {
+      keep.push({ url: u, name, why: name === 'lease.json' ? 'the lease stays on the pod by design' : 'the container needs it' });
+    } else if (MOVED_STATE_DOCS.has(name)) {
+      drop.push({ url: u, name });
+    } else {
+      keep.push({ url: u, name, why: 'not one of ours' });
+    }
+  }
+  return { drop, keep };
+}
+
+// Copy the private half — every state document, then the RDF tree — from one
+// pair of storages to the other. Copy and verify only: nothing is repointed and
+// nothing is deleted, so a failure part-way leaves the source authoritative.
+// Used by both `state --to` and the record page's Move private data.
+export async function copyPrivateHalf({ from, to, log = () => {} }) {
+  const { PodStore } = await import('./store.mjs');
+  const { PodRdf } = await import('./podrdf.mjs');
+  const src = new PodStore({ log: () => {} });
+  src.attach(from.state);
+  await src.load();
+  const dst = new PodStore({ log });
+  dst.attach(to.state);
+  for (const [name, value] of src.cache) dst.write(name, value);
+  if (!await dst.commit()) {
+    throw new Error('some state documents did not land — nothing was repointed, nothing was deleted');
+  }
+  const rdfFrom = new PodRdf({ storage: from.fediverse });
+  const rdfTo = new PodRdf({ storage: to.fediverse });
+  let notes = 0;
+  for (const doc of ['settings', 'contacts']) {
+    try { await rdfTo.put(rdfTo.fedi + doc, await rdfFrom.get(rdfFrom.fedi + doc)); }
+    catch (e) { if (!/ 404$/.test(e.message)) throw e; }
+  }
+  for (const kind of ['posts', 'timeline']) {
+    for (const url of await rdfFrom.listNotes(kind)) {
+      await rdfTo.put(`${rdfTo.fedi}${kind}/${url.split('/').pop()}`, await rdfFrom.get(url));
+      notes++;
+    }
+  }
+  return { docs: src.cache.size, notes };
+}

package/lib/oidc-auth.mjs

@@ -0,0 +1,53 @@
+// oidc-auth.mjs — who may drive the C2S surface. Two proofs are accepted:
+// the Mastodon facade's bearer (minted on this machine, so its holder is the
+// operator by construction), or a Solid-OIDC token — DPoP-bound when the
+// client sends the proof header — verified by the same library the wider
+// Solid world uses. The token alone is not enough: the WebID it names must
+// be THIS identity's owner, an authorization step the token does not carry.
+//
+// The verifier is injected so offline tests stub it, and wrapped so the
+// library (CJS, older jose) can be replaced without touching any caller.
+
+export function makeC2sAuth({ agent, masto = null, verifier = null, log = () => {}, scheme = null }) {
+  let verify = verifier;
+  const loadVerifier = async () => {
+    if (!verify) {
+      const { createSolidTokenVerifier } = await import('@solid/access-token-verifier');
+      verify = createSolidTokenVerifier();
+    }
+    return verify;
+  };
+
+  return async function authenticate(req, pathname) {
+    if (masto?.authed(req)) {
+      return { ok: true, webid: agent.remote?.webId || null, via: 'bearer' };
+    }
+    if (!req.headers.authorization) {
+      return { ok: false, status: 401, error: 'authentication required: a Solid-OIDC token (DPoP) or this agent\'s own bearer' };
+    }
+    let webid;
+    try {
+      const v = await loadVerifier();
+      // The URL the client signed its proof over. The Host header already
+      // passed the Authorities firewall, so whichever alias the client used
+      // (localhost, 127.0.0.1, the named origin) is one this agent answers on;
+      // the scheme is whichever listener the request arrived on.
+      const htu = `${scheme ? scheme.replace(/:$/u, '') : req.socket?.encrypted ? 'https' : 'http'
+      }://${req.headers.host}${pathname}`;
+      ({ webid } = await v(
+        req.headers.authorization,
+        req.headers.dpop ? { header: req.headers.dpop, method: req.method, url: htu } : undefined,
+      ));
+    } catch (e) {
+      log(`c2s auth: token rejected — ${e.message}`);
+      return { ok: false, status: 401, error: `token rejected: ${e.message}` };
+    }
+    const owner = agent.remote?.webId;
+    if (!owner || webid !== owner) {
+      // Verified is not authorized: a valid token from ANY WebID must not
+      // post as this actor. (The gap jg10's outbox leaves open.)
+      return { ok: false, status: 403, error: 'authenticated, but this outbox belongs to its owner alone' };
+    }
+    return { ok: true, webid, via: 'oidc' };
+  };
+}

package/lib/podrdf.mjs

@@ -0,0 +1,132 @@
+// podrdf.mjs — the RDF source of truth under /activitypods-js/fediverse/:
+// settings, contacts, and one document per note. Same documents and AS2
+// vocabulary as dk's local.mjs (plan: ap-pod-mapping.md).
+//
+// Parsed and serialised by rdflib, never by hand. Escaping, encoding and shape
+// are exactly what a regex gets wrong quietly — a tab inside a literal, a '%'
+// in a slug, a triple laid out in a form the pattern did not anticipate — and
+// a hand-built serialiser writes the documents the hand-built parser reads
+// back, so the two bugs cover for each other. See claude/plans/no-regex-rdf.md.
+//
+// The container it lives in is a Storage (lib/storage.mjs): a pod over HTTP or
+// a directory. Callers still speak in absolute URLs, which is what the rest of
+// the agent has.
+
+import * as $rdf from 'rdflib';
+
+const AS = $rdf.Namespace('https://www.w3.org/ns/activitystreams#');
+const RDF = $rdf.Namespace('http://www.w3.org/1999/02/22-rdf-syntax-ns#');
+const XSD = $rdf.Namespace('http://www.w3.org/2001/XMLSchema#');
+const TURTLE = 'text/turtle';
+
+export class PodRdf {
+  constructor({ storage }) {
+    this.storage = storage;
+    this.base = storage.base;
+    this.fedi = this.base;
+  }
+
+  // Callers hold absolute URLs; the storage works in paths under its base.
+  _rel(url) {
+    if (!url.startsWith(this.fedi)) throw new Error(`${url} is not under ${this.fedi}`);
+    return url.slice(this.fedi.length);
+  }
+
+  async get(url) {
+    const r = await this.storage.read(this._rel(url));
+    if (!r.ok) throw new Error(`pod GET ${url} → ${r.status}`);
+    return r.body;
+  }
+
+  async put(url, body, contentType = TURTLE) {
+    const r = await this.storage.write(this._rel(url), body, contentType);
+    if (!r.ok) throw new Error(`pod PUT ${url} → ${r.why}`);
+  }
+
+  async delete(url) {
+    if (!await this.storage.remove(this._rel(url))) throw new Error(`pod DELETE ${url} failed`);
+  }
+
+  // Child resource URLs of {fedi}{kind}/ (empty when the container is absent).
+  async listNotes(kind) {
+    const { names } = await this.storage.list(`${kind}/`);
+    return names
+      // `.<pid>.tmp` is what FileStorage.write leaves if it is interrupted
+      // between the write and the rename. It is not a note, and handing one to
+      // the parser produces a failure that reads like a corrupt document.
+      .filter(n => !n.endsWith('/') && !/\.(acl|meta)$/.test(n) && !/\.\d+\.tmp$/.test(n))
+      .map(n => `${this.fedi}${kind}/${n}`);
+  }
+
+  _graph(url, ttl) {
+    const g = $rdf.graph();
+    $rdf.parse(ttl, g, url, TURTLE);
+    return g;
+  }
+
+  // Inverse of writeNote for one resource.
+  async readNote(url) {
+    const g = this._graph(url, await this.get(url));
+    const doc = $rdf.sym(url);
+    const iri = (p) => g.any(doc, AS(p), null, doc)?.value;
+    const str = (p) => g.any(doc, AS(p), null, doc)?.value;
+    const attachments = g.each(doc, AS('attachment'), null, doc).map((a) => {
+      const mediaType = g.any(a, AS('mediaType'), null, doc)?.value;
+      const description = g.any(a, AS('name'), null, doc)?.value;
+      return { url: a.value, mediaType: mediaType || '', ...(description ? { description } : {}) };
+    });
+    return {
+      noteId: iri('url'), actor: iri('attributedTo'),
+      published: str('published'), inReplyTo: iri('inReplyTo'), content: str('content'),
+      ...(attachments.length ? { attachments } : {}),
+    };
+  }
+
+  // Incoming or own post → one RDF resource. kind: 'timeline' | 'posts'
+  async writeNote(kind, slug, { noteId, actor, published, content, inReplyTo, attachments }) {
+    const url = `${this.fedi}${kind}/${slug}`;
+    const doc = $rdf.sym(url);
+    const g = $rdf.graph();
+    g.add(doc, RDF('type'), AS('Note'), doc);
+    g.add(doc, AS('url'), $rdf.sym(noteId), doc);
+    g.add(doc, AS('attributedTo'), $rdf.sym(actor), doc);
+    // Two-arg with a NamedNode is how rdflib takes a datatype; passing it
+    // third silently yields an xsd:string, which would drop ^^xsd:dateTime
+    // from every note published from here on.
+    if (published) g.add(doc, AS('published'), $rdf.literal(published, XSD('dateTime')), doc);
+    if (inReplyTo) g.add(doc, AS('inReplyTo'), $rdf.sym(inReplyTo), doc);
+    g.add(doc, AS('content'), $rdf.literal(content || ''), doc);
+    for (const a of attachments || []) {
+      const at = $rdf.sym(a.url);
+      g.add(doc, AS('attachment'), at, doc);
+      g.add(at, RDF('type'), AS('Document'), doc);
+      if (a.mediaType) g.add(at, AS('mediaType'), $rdf.literal(a.mediaType), doc);
+      if (a.description) g.add(at, AS('name'), $rdf.literal(a.description), doc);
+    }
+    await this.put(url, $rdf.serialize(doc, g, url, TURTLE));
+  }
+
+  // Contacts doc — the followers/following truth, rebuilt whole each change.
+  async writeContacts({ followers, following }) {
+    const url = this.fedi + 'contacts';
+    const doc = $rdf.sym(url);
+    const me = $rdf.sym(url + '#me');
+    const g = $rdf.graph();
+    g.add(me, RDF('type'), AS('Person'), doc);
+    for (const f of followers) g.add(me, AS('followers'), $rdf.sym(f.actor), doc);
+    for (const f of following) g.add(me, AS('following'), $rdf.sym(f.actor), doc);
+    await this.put(url, $rdf.serialize(doc, g, url, TURTLE));
+  }
+
+  // Settings doc — handle + pointer to the public face.
+  async writeSettings({ handle, actorUrl }) {
+    const url = this.fedi + 'settings';
+    const doc = $rdf.sym(url);
+    const me = $rdf.sym(url + '#me');
+    const g = $rdf.graph();
+    g.add(me, RDF('type'), AS('Person'), doc);
+    g.add(me, AS('preferredUsername'), $rdf.literal(handle), doc);
+    g.add(me, AS('url'), $rdf.sym(actorUrl), doc);
+    await this.put(url, $rdf.serialize(doc, g, url, TURTLE));
+  }
+}

package/lib/ports.mjs

@@ -0,0 +1,27 @@
+// ports.mjs — finding a port nothing else is on.
+//
+// This lived twice, in bin/fedipod.mjs and lib/admin.mjs, and the two
+// copies had already drifted: one returned null when it ran out of ports and
+// the other threw. Both spawn agents, so which one you got decided whether a
+// full range produced an error message or a silent undefined.
+
+import net from 'node:net';
+
+// Bind to find out. Something holding a port without answering HTTP reads as
+// free to a probe that only asks for a response, and the new agent then dies on
+// EADDRINUSE with nobody watching.
+export function portFree(port) {
+  return new Promise((resolve) => {
+    const probe = net.createServer();
+    probe.once('error', () => resolve(false));
+    probe.once('listening', () => probe.close(() => resolve(true)));
+    probe.listen(port, '127.0.0.1');
+  });
+}
+
+// null when the whole span is taken. Callers that want an error say so in their
+// own words — the CLI has a person reading it, the admin API has a status code.
+export async function freePortFrom(first, span = 50) {
+  for (let p = first; p < first + span; p++) if (await portFree(p)) return p;
+  return null;
+}