fedipod-server 0.10.0 → 0.12.1

package/lib/pod/notes.mjs

@@ -0,0 +1,80 @@
+// notes.mjs — ap/notes/: the posts themselves, and the two documents each one
+// drags with it.
+//
+// A published post is not one document. It is the Note, the Create activity
+// that announced it, and a replies collection remote servers will dereference
+// — and they have different lifetimes, which is the whole reason this file
+// exists. Deleting a post REPLACES the Note with a Tombstone (a peer learns
+// the post was deleted, rather than getting a bare 404 it reads as a temporary
+// failure) while DELETING the Create outright, because the Create was an
+// action that has been withdrawn rather than an object that still exists.
+//
+// The container is public-Read and the notes inherit it. The Tombstone is the
+// exception that has to state its own rule: a private post lives in a
+// different, owner-only container, so there is nothing public to inherit.
+
+const PUBLIC_READ = ['Read'];
+
+// ---- the owner's agent ----
+
+/** The notes container itself, public-Read so everything under it inherits. */
+export async function provisionContainer(pod, urls) {
+  await pod.putJson(urls.notes + '.keep', { keep: true }, 'application/json');
+  await pod.setAcl(urls.notes, PUBLIC_READ);
+}
+
+/** The Note. Inherits the container's rule; states none of its own. */
+export const write = (pod, noteId, doc) => pod.putJson(noteId, doc);
+
+/** The Create that announced it — its own document, at a derived id. */
+export const writeCreate = (pod, createId, doc) => pod.putJson(createId, doc);
+
+/**
+ * An empty replies collection, written with the note.
+ *
+ * Remote servers dereference `replies`, and a dangling pointer that 404s is
+ * worse than no pointer at all.
+ */
+export const writeEmptyReplies = (pod, repliesId, doc) => pod.putJson(repliesId, doc);
+
+/** The replies collection as it stands. */
+export const readReplies = (pod, repliesId) => pod.getJson(repliesId);
+export const writeReplies = (pod, repliesId, doc) => pod.putJson(repliesId, doc);
+
+/** One published note, as the pod currently serves it. */
+export const read = (pod, noteId) => pod.getJson(noteId);
+
+/**
+ * Replace a note with a Tombstone, and keep it readable.
+ *
+ * The Read rule is stated explicitly here even though the public container
+ * grants it: a private or direct post lives in the owner-only container, and
+ * its Tombstone still has to be fetchable by the servers being told about the
+ * deletion.
+ */
+export async function writeTombstone(pod, noteId, doc) {
+  await pod.putJson(noteId, doc);
+  await pod.setAcl(noteId, PUBLIC_READ);
+}
+
+/** Withdraw the Create. Returns whether the pod actually removed it. */
+export const dropCreate = (pod, createId) => pod.delete(createId).catch(() => false);
+
+/** The replies collection, once the note it belonged to is gone. */
+export const dropReplies = (pod, repliesId) => pod.delete(repliesId).catch(() => {});
+
+/**
+ * What the container holds, with the derived documents filtered out.
+ *
+ * A listing returns the Note, its `-create` and its `-replies` alike; only the
+ * first is a post, and handing the other two to a reader that expects posts
+ * produces failures that read like corruption.
+ */
+export async function list(pod, urls) {
+  const children = await pod.listContainer(urls.notes);
+  return children
+    .filter((c) => !/(-create|-replies)$/.test(c.url) && !c.url.endsWith('.keep'))
+    // A defensive copy: the transport hands back the same array on a 304, so a
+    // caller that sorts in place would corrupt it for every later reader.
+    .map((c) => ({ ...c }));
+}

package/lib/pod/notifications.mjs

@@ -0,0 +1,89 @@
+// notifications.mjs — being told when the inbox changes, instead of asking.
+//
+// A pod that offers Solid Notifications lets a client open a socket and hear
+// about a container the moment it changes, which is the difference between
+// mail arriving and mail being noticed two minutes later. Discovering that
+// service takes two unauthenticated reads of the pod's own description, and
+// then one authenticated POST to subscribe.
+//
+// This is the ONLY module here that parses RDF itself, which is why it is its
+// own file: a service that only ever appends to an inbox can import inbox.mjs
+// without pulling a parser in behind it.
+
+import * as $rdf from 'rdflib';
+import { readCapped } from './http.mjs';
+import { linkTargets, REL } from './links.mjs';
+
+const RDF = $rdf.Namespace('http://www.w3.org/1999/02/22-rdf-syntax-ns#');
+const NOTIFY = $rdf.Namespace('http://www.w3.org/ns/solid/notifications#');
+const WS_CHANNEL = 'WebSocketChannel2023';
+
+// ---- anyone at all: a pod describes its own services publicly ----
+
+/**
+ * Where this pod describes the services it offers.
+ *
+ * The pod says so on any response about one of its resources; the well-known
+ * path is only what a pod that says nothing has always used. Unauthenticated
+ * on purpose — this is a public fact about the server, asked before there is
+ * anything to authenticate about.
+ */
+export async function storageDescriptionUrl(podBase, { fetchImpl = fetch, headers = {}, timeoutMs = 20_000 } = {}) {
+  try {
+    const head = await fetchImpl(podBase, {
+      method: 'HEAD', headers, signal: AbortSignal.timeout(timeoutMs),
+    });
+    const [found] = linkTargets(head.headers.get('link'), REL.storageDescription, podBase);
+    if (found) return found;
+  } catch { /* the well-known path below */ }
+  return podBase + '.well-known/solid';
+}
+
+/**
+ * The websocket channel service this pod offers, or null when it offers none.
+ *
+ * Asked of rdflib rather than pattern-matched: the description is RDF, and the
+ * gap between "a string that appears in the document" and "the service this
+ * pod actually advertises" is where quiet bugs live. A pod may name the type
+ * on the service, or name the service's channelType — both are asked for.
+ */
+export async function readWebSocketChannel(descUrl, { fetchImpl = fetch, headers = {}, timeoutMs = 20_000 } = {}) {
+  const res = await fetchImpl(descUrl, {
+    headers: { accept: 'text/turtle', ...headers },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const g = $rdf.graph();
+  try {
+    $rdf.parse(await readCapped(res), g, descUrl, 'text/turtle');
+  } catch (e) {
+    return { channel: null, error: `service description unparsable (${e.message})` };
+  }
+  const channel = g.each(null, RDF('type'), NOTIFY(WS_CHANNEL), null).map((n) => n.value).find(Boolean)
+    || g.each(null, NOTIFY('channelType'), NOTIFY(WS_CHANNEL), null).map((n) => n.value).find(Boolean);
+  return { channel: channel || null, error: channel ? null : `no ${WS_CHANNEL} service` };
+}
+
+// ---- the owner's agent ----
+
+/**
+ * Subscribe to changes on the inbox.
+ *
+ * `podTopicUrl` is POD-SPACE, and the parameter is named that way because
+ * getting it wrong fails in a way nothing else here does: the topic travels in
+ * the BODY, so the advertised-to-pod url map a transport applies to the
+ * request LINE never reaches it. An identity whose ids are advertised
+ * elsewhere would name a container the pod cannot grant read on, and the
+ * subscription comes back 403.
+ */
+export async function subscribeToInbox(pod, { channelUrl, podTopicUrl, ...rest }) {
+  return pod.fetch(channelUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/ld+json' },
+    body: JSON.stringify({
+      '@context': ['https://www.w3.org/ns/solid/notification/v1'],
+      type: `http://www.w3.org/ns/solid/notifications#${WS_CHANNEL}`,
+      topic: podTopicUrl,
+      ...rest,
+    }),
+  });
+}

package/lib/pod/outbox.mjs

@@ -0,0 +1,18 @@
+// outbox.mjs — ap/outbox: everything this actor has published, paged.
+//
+// Public by definition, and read by strangers rather than by us: a remote
+// server walks it to backfill an account it has just met. It is also what a
+// rebuild reads to recover posts a lost machine no longer has, which is why
+// readPublished tolerates the flat shape this project used to write.
+
+import * as collection from './collection.mjs';
+
+// ---- the owner's agent ----
+
+export const writePage = (pod, pageUrl, doc, opts) => collection.writePage(pod, pageUrl, doc, opts);
+export const writeHead = (pod, urls, doc, opts) => collection.writeHead(pod, urls.outbox, doc, opts);
+export const dropPage = (pod, pageUrl) => collection.dropPage(pod, pageUrl);
+
+/** Every activity the pod currently publishes, or null if it publishes none. */
+export const readPublished = (pod, urls) =>
+  collection.readPaged(pod, urls.outbox, { max: 10_000 });

package/lib/pod/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "solid-ap-pod",
+  "version": "0.1.0",
+  "description": "Read and write an ActivityPub actor's documents on a Solid pod: the container layout, an injected-session transport, WAC access control, and one module per pod resource.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    "./urls.mjs": "./urls.mjs",
+    "./transport.mjs": "./transport.mjs",
+    "./http.mjs": "./http.mjs",
+    "./links.mjs": "./links.mjs"
+  },
+  "dependencies": {
+    "rdflib": "^2.4.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/lib/pod/policy.mjs

@@ -0,0 +1,58 @@
+// policy.mjs — ap/gateway-policy.json: what the pod's owner has published
+// about which mail they want.
+//
+// The point of the document is that a service filtering on someone's behalf
+// reads their stated wishes from their own pod rather than holding a private
+// copy of them. So the reader here is deliberately unauthenticated: the
+// document is public, and a service that needed a credential to read it would
+// be holding something about the person it should not have to.
+
+import { readCapped } from './http.mjs';
+
+const POLICY_TTL_MS = 5 * 60_000;
+const POLICY_MAX_BYTES = 256 * 1024;
+
+/**
+ * The published policy, or null when there is none to read.
+ *
+ * The cache is passed IN rather than kept here. A library that holds
+ * process-global state decides its own lifetime, and the lifetime that matters
+ * belongs to the service: on a warm serverless container one Map is shared
+ * across every user it serves, so what it is keyed by is a correctness
+ * property, not an optimisation. Keyed by `podHome`, it is one person's policy
+ * under one person's key.
+ *
+ * Cached at all because a delivery flood must not become one read per delivery
+ * against the person's pod — which is the load the whole arrangement exists to
+ * spare them.
+ *
+ * ---- asked by: a delivery gateway, deciding what concerns this person ----
+ */
+export async function read(fetchImpl, podHome, { cache = null, ttlMs = POLICY_TTL_MS } = {}) {
+  const hit = cache?.get(podHome);
+  if (hit && Date.now() - hit.at < ttlMs) return hit.policy;
+  let policy = null;
+  try {
+    const res = await fetchImpl(podHome + 'ap/gateway-policy.json',
+      { headers: { accept: 'application/json' } });
+    if (res && res.status < 400) policy = JSON.parse(await readCapped(res, POLICY_MAX_BYTES));
+  } catch { /* unpublished or unreachable: the caller's own fields stand */ }
+  cache?.set(podHome, { at: Date.now(), policy });
+  return policy;
+}
+
+// ---- the owner's agent ----
+
+/**
+ * Publish the policy.
+ *
+ * Public-Read on purpose, and the only document in this library written
+ * public specifically so that a service holding no credential can act on the
+ * owner's behalf. What goes IN it — which follows count, which blocks — is the
+ * caller's to decide; that it is readable is the point of it existing.
+ */
+export async function write(pod, urls, doc) {
+  const url = urls.home + 'ap/gateway-policy.json';
+  await pod.putJson(url, doc, 'application/json');
+  await pod.setAcl(url, ['Read']);
+}

package/lib/pod/private.mjs

@@ -0,0 +1,19 @@
+// private.mjs — ap/private/: the collections that are nobody else's business.
+//
+// pending-followers and pending-following are FEP-4ccd's follows in limbo;
+// blocked is FEP-c648's block list. All three live in the private container so
+// the owner-only rule is INHERITED rather than re-stated per document — which
+// is why none of these writes sets an ACL of its own, and why writing one into
+// the wrong container would silently publish it.
+
+import * as collection from './collection.mjs';
+
+// ---- the owner's agent ----
+
+export async function writePending(pod, urls, { followers, following }) {
+  await collection.writeFlat(pod, urls.pendingFollowers, followers);
+  await collection.writeFlat(pod, urls.pendingFollowing, following);
+}
+
+export const writeBlocked = (pod, urls, doc) =>
+  collection.writeFlat(pod, urls.blocked, doc);

package/lib/pod/root.mjs

@@ -0,0 +1,63 @@
+// root.mjs — the pod itself, before any of its containers.
+//
+// Three questions get asked of a pod root rather than of a document in it: who
+// owns it, whether it is there at all, and — for a service publishing someone
+// else's pod on their behalf — what one of its public documents says.
+//
+// Every operation here takes a plain fetcher, not a transport. That is the
+// honest shape: these are asked by parties that hold no credential for the pod
+// — a keyless delivery gateway, a sign-up page looking at a pod the person
+// brought with them — and giving them an authenticated transport would let
+// them ask questions they have no business asking.
+
+import { readCapped } from './http.mjs';
+import { linkTargets, REL } from './links.mjs';
+
+const OWNER_LOOKUP_MS = 5_000;
+const PUBLIC_DOC_MAX_BYTES = 1024 * 1024;
+
+/**
+ * Who the pod server says owns this pod.
+ *
+ * The server hosting it is the authority on that, so when it answers, its
+ * answer decides. A server that says nothing leaves where the WebID lives as
+ * the only evidence there is — which is weaker, and the caller's problem.
+ *
+ * ---- asked by: a service deciding whether someone may speak for a pod ----
+ */
+export async function readOwnerLinks(fetchImpl, podBase, { timeoutMs = OWNER_LOOKUP_MS } = {}) {
+  try {
+    const res = await fetchImpl(podBase, {
+      method: 'HEAD', signal: AbortSignal.timeout(timeoutMs),
+    });
+    return linkTargets(res?.headers?.get?.('link'), REL.owner, podBase);
+  } catch { return []; }
+}
+
+/**
+ * Does anything answer at this pod?
+ *
+ * ---- asked by: a provisioning client, about a pod the person brought ----
+ */
+export async function probeAnswers(podUrl, fetchImpl = fetch) {
+  try {
+    const res = await fetchImpl(podUrl, { method: 'HEAD' });
+    return { ok: res.status < 400, status: res.status };
+  } catch (e) { return { ok: false, status: 0, error: e.message }; }
+}
+
+/**
+ * One public document, read on behalf of someone who is not its owner.
+ *
+ * `getter` is how the read happens, which is not always a network fetch: a
+ * component running inside the pod server reads its own store directly and has
+ * no access control of its own, so the pod this read belongs to travels with
+ * the request and the getter is told what it may reach.
+ *
+ * ---- asked by: a front publishing a pod's public face under its own name ----
+ */
+export async function readPublicDocument(getter, podTarget, { podHome, maxBytes = PUBLIC_DOC_MAX_BYTES } = {}) {
+  const res = await getter(podTarget, { podHome });
+  if (!res || res.status >= 400) return { status: res?.status || 502, text: null };
+  return { status: 200, text: await readCapped(res, maxBytes) };
+}

package/lib/pod/state.mjs

@@ -0,0 +1,39 @@
+// state.mjs — ap-state/: what the agent knows, kept where the agent is not.
+//
+// A browser has no disk you can carry to the next machine, so the durable copy
+// of an identity's state lives on its pod. Most of that tree is handled by a
+// caching store; what is here is the two documents read and written OUTSIDE
+// it, before there is a store to read them with.
+//
+// The container is owner-only, and every operation here assumes that has
+// already been established — see provisionKey, which is the one place that
+// establishes it, and does so in an order that is not negotiable.
+
+// ---- the owner's agent ----
+
+export const readWrappedKeys = (pod, urls) => pod.getJson(urls.state + 'keys.json');
+export const readConfig = (pod, urls) => pod.getJson(urls.state + 'config.json');
+
+export const writeWrappedKeys = (pod, urls, envelope) =>
+  pod.putJson(urls.state + 'keys.json', envelope, 'application/json');
+export const writeConfig = (pod, urls, config) =>
+  pod.putJson(urls.state + 'config.json', config, 'application/json');
+
+// ---- a provisioning client, setting an identity up for the first time ----
+
+/**
+ * Lock the state container, THEN write the signing key into it.
+ *
+ * The order is the operation. Writing the key first leaves a window in which a
+ * pod whose root is world-readable serves it to anyone who asks — and a pod
+ * the person brought with them is exactly the case where that root may be
+ * public. As two statements this was two chances to get it wrong; as one
+ * operation there is nowhere to put them in the other order.
+ *
+ * The envelope is built by the caller. This library does not choose how a key
+ * is wrapped, and should not be able to write an unwrapped one by accident.
+ */
+export async function provisionKey(pod, { stateUrl, keysUrl, envelope }) {
+  await pod.setAcl(stateUrl, []);
+  await pod.putJson(keysUrl, envelope, 'application/json');
+}