fedipod-server 0.28.1 → 0.30.0

package/lib/pod/README.md

@@ -1,61 +0,0 @@
-# solid-ap-pod
-
-Reading and writing an ActivityPub actor's documents on a Solid pod.
-
-It knows **where each document lives and how it lands safely** — the container
-layout, the transport, the WAC access-control documents, the deletion deny-list,
-the byte budgets. It does not know **what is in them**: every AS2 document is
-built by the caller and passed in. That line is why this can be lifted out of
-the application it grew up in.
-
-It currently lives inside FediPod at `lib/pod/`. Extracting it is a directory
-move plus this `package.json`; `scripts/check-pod-calls.mjs` in the parent repo
-exists to keep that true.
-
-## Rules it holds itself to
-
-1. **No upward imports.** Nothing here reaches outside this directory.
-2. **No Node built-ins.** It runs unmodified in a service worker, which is why
-   it carries its own `readCapped`/`retryAfterMs` in `http.mjs` rather than
-   using a host application's SSRF-guarding fetch.
-3. **One runtime dependency, rdflib**, reached only by `transport.mjs` (listings,
-   ACL documents, ACP detection, the WebID patch). Resource modules must stay
-   free of it so a size-sensitive host — a serverless function answering every
-   request — can import one without paying for a parser.
-4. **Everything injected.** It never builds a session, mints a credential, or
-   reads config or environment.
-5. **No opinions with defaults.** `apUrls` requires the container root rather
-   than guessing one, because a guessed root put an identity's state in one
-   container and its published documents in another.
-
-## Layout
-
-| file | what |
-|---|---|
-| `urls.mjs` | the container layout; `apUrls(remotePod, root, { publicBase })` |
-| `transport.mjs` | `PodTransport` — verbs, ACLs, listings, cooldown, deny-list |
-| `http.mjs` | `readCapped`, `retryAfterMs` |
-| `links.mjs` | RFC 8288 `Link` header parsing |
-
-## The transport
-
-`PodTransport` takes a session — `{ fetch(url, init) }` — and never makes one.
-A Node agent hands it a DPoP client-credentials grant, a browser hands it a
-Solid-OIDC session, a pod server hands it a shim straight onto its own store.
-
-Three manners hold for every request, and they are in `fetch()` so nothing can
-route around them:
-
-- **The cooldown.** A 429 or 503 arms a pod-wide pause. `cooldownMode: 'refuse'`
-  fails fast for the window (right for a daemon with timers behind it);
-  `'wait'` sleeps it out (right for a tab with a person in front of it).
-- **The url map.** A fronted identity's advertised ids are mapped to their pod
-  locations at this one choke point, so callers pass advertised ids throughout.
-- **The deletion deny-list.** A pod's profile, settings, discovery documents,
-  access-control documents and lease are never deletable. A pod was crippled
-  exactly this way; the list is a DENY-list rather than an allow-prefix because
-  the next caller will have a different prefix and the same things it must
-  never touch.
-
-Subclasses override **`_send`**, not `fetch` — an override of `_send` cannot
-skip any of the three.

package/lib/pod/actor.mjs

@@ -1,96 +0,0 @@
-// actor.mjs — ap/actor and the documents that speak for it.
-//
-// "Actor" here always means the ActivityPub actor DOCUMENT — the thing remote
-// servers fetch to learn this identity's inbox, keys and collections. It is
-// not the party performing an operation; a transport carries that as its
-// `role`.
-//
-// The actor is public, and its Read rule travels with every write for the same
-// reason it does in discovery.mjs: an actor nobody can fetch is an identity
-// nobody can follow, and the failure is silent from this side.
-
-const PUBLIC_READ = ['Read'];
-
-// What ActivityPub §3.2 requires a client to send: the profiled JSON-LD type is
-// the MUST, activity+json only the SHOULD a server ought to treat as equivalent.
-// Asking for both is the only form every implementation answers.
-const ACCEPT_AP = 'application/activity+json, application/ld+json; profile="https://www.w3.org/ns/activitystreams"';
-
-// ---- the owner's agent ----
-
-/** Publish the actor document. */
-export async function write(pod, urls, doc) {
-  await pod.putJson(urls.actor, doc);
-  await pod.setAcl(urls.actor, PUBLIC_READ);
-}
-
-/** What this pod currently publishes as its actor, or null if nothing does. */
-export function read(pod, urls) {
-  return pod.getJson(urls.actor);
-}
-
-/**
- * Replace the actor with a Tombstone.
- *
- * Still public-Read, deliberately: a retired actor that 404s reads to a remote
- * server as a temporary failure worth retrying, where a Tombstone reads as an
- * answer.
- */
-export async function writeTombstone(pod, urls, doc) {
-  await pod.putJson(urls.actor, doc);
-  await pod.setAcl(urls.actor, PUBLIC_READ);
-}
-
-/**
- * Publish the actor carrying `movedTo`.
- *
- * The same document in the same place — but named apart from `write` because
- * what it means is not "the profile changed", it is "this identity is now
- * somewhere else", and a caller should have to say which it intends.
- */
-export async function writeMoved(pod, urls, doc) {
-  await pod.putJson(urls.actor, doc);
-  await pod.setAcl(urls.actor, PUBLIC_READ);
-}
-
-/** The human half: a page a person can open and follow from. */
-export async function writeProfilePage(pod, urls, html) {
-  await pod.put(urls.profileHtml, html, 'text/html');
-  await pod.setAcl(urls.profileHtml, PUBLIC_READ);
-}
-
-/**
- * Record the actor in the pod owner's WebID profile, as `foaf:account`.
- *
- * The inverse of the actor's own `alsoKnownAs`: together they let a reader of
- * either document verify the other, rather than taking one side's word.
- *
- * Delegated to the transport, which reads the profile, refuses to write if the
- * parsed graph does not mention the WebID, and patches exactly the statements
- * involved rather than rewriting a document full of things that are not ours.
- */
-export function linkInWebIdProfile(pod, { actorUrl, accountName, kind = 'person', outbox = null }) {
-  return pod.linkAccountInProfile({ actorUrl, accountName, kind, outbox });
-}
-
-// ---- anyone at all ----
-
-/**
- * The OIDC issuer a published actor names, read without credentials.
- *
- * Asked of a stranger's pod during sign-in, before there is any session to ask
- * with — so a plain fetch, and a null rather than a throw when the actor is
- * not there or says nothing.
- */
-export async function readIssuer(actorUrl, fetchImpl = fetch) {
-  try {
-    // Both media types, and the profile with it. `application/activity+json`
-    // alone is what ActivityPub calls the SHOULD, not the MUST — and a pod that
-    // stores its actor as JSON-LD answers 501 to it, which would read here as
-    // "this pod names no issuer" and send the caller off to guess one.
-    const res = await fetchImpl(actorUrl, { headers: { accept: ACCEPT_AP } });
-    if (res.status >= 400) return null;
-    const doc = await res.json();
-    return doc?.endpoints?.oauthAuthorizationEndpoint || null;
-  } catch { return null; }
-}

package/lib/pod/collection.mjs

@@ -1,77 +0,0 @@
-// collection.mjs — the mechanics every AS2 collection on a pod shares.
-//
-// Not a resource itself: the outbox, the followers list and the block list are
-// each their own document with their own meaning, and each has a module that
-// says so. What they have in common is how a collection is written and walked,
-// and that is here so it is written once.
-//
-// A paged collection is a HEAD carrying counts and bounds, plus page documents
-// carrying the items. A remote server reads the small head and walks only as
-// far as it needs, instead of pulling one enormous document.
-
-const PUBLIC_READ = ['Read'];
-
-/**
- * One page.
- *
- * `publicRead` is false for a page that already exists: the ACL is set when a
- * page is first created and not rewritten on every republish, because a page
- * is written on every change and its rule is not what changed.
- */
-export async function writePage(pod, pageUrl, doc, { publicRead = false } = {}) {
-  await pod.putJson(pageUrl, doc);
-  if (publicRead) await pod.setAcl(pageUrl, PUBLIC_READ);
-}
-
-/** The head — counts, bounds, and the pointer at the first page. */
-export async function writeHead(pod, url, doc, { publicRead = false } = {}) {
-  await pod.putJson(url, doc);
-  if (publicRead) await pod.setAcl(url, PUBLIC_READ);
-}
-
-/**
- * Remove a page that is no longer within bounds.
- *
- * Best-effort: a surplus page left behind is stale but harmless — the head no
- * longer points at it — where a failed publish over a delete is not.
- */
-export async function dropPage(pod, pageUrl) {
-  await pod.delete(pageUrl).catch(() => {});
-}
-
-/** A whole flat collection, written as one document. */
-export async function writeFlat(pod, url, doc, { publicRead = false } = {}) {
-  await pod.putJson(url, doc);
-  if (publicRead) await pod.setAcl(url, PUBLIC_READ);
-}
-
-/**
- * Every item in a published collection, walking pages.
- *
- * Also reads a FLAT collection, so a collection published before this project
- * paged them is still readable — which matters because a rebuild reads these
- * to recover what a lost machine no longer has.
- *
- * `seen` guards a cycle and `max` a collection that lies about its own size;
- * both are the pod's data but not necessarily ours, since a restored backup or
- * a half-finished write can leave either.
- *
- * @returns items, or null when there is no collection there at all
- */
-export async function readPaged(pod, headUrl, { max = 10_000, alsoItems = false } = {}) {
-  const head = await pod.getJson(headUrl).catch(() => null);
-  if (!head) return null;
-  if (Array.isArray(head.orderedItems) && head.orderedItems.length) return head.orderedItems;
-  if (alsoItems && Array.isArray(head.items) && head.items.length) return head.items;
-  const items = [];
-  const seen = new Set();
-  let next = head.first;
-  while (next && !seen.has(next) && items.length < max) {
-    seen.add(next);
-    const page = await pod.getJson(next).catch(() => null);
-    if (!page) break;
-    items.push(...(page.orderedItems || []));
-    next = page.next;
-  }
-  return items;
-}

package/lib/pod/containers.mjs

@@ -1,140 +0,0 @@
-// containers.mjs — making a container exist, and making its access right.
-//
-// A container on a Solid pod is not created; it is implied by something being
-// in it. So every provisioning here writes one small canary document and then
-// states the access rule the container is supposed to have. The two are one
-// operation on purpose: a container that exists without its ACL is either
-// world-readable when it should not be, or unreachable when it should not be,
-// and both have happened by writing one and not the other.
-//
-// The probes at the bottom take a `probe` function rather than a transport,
-// and that is the whole point of them: they ask what a STRANGER sees. Handing
-// them a credential would answer a different question, and answer it wrongly.
-
-const KEEP = { keep: true };
-const KEEP_CT = 'application/json';
-
-/** The canary this module writes, and reads back to ask whether it was here. */
-const keepUrl = (base) => `${base}.keep`;
-
-// ---- the owner's agent, holding the pod's own credential ----
-
-/**
- * Whether this container has already been provisioned.
- *
- * Only a definite "yes" counts: anything else falls through to the write,
- * which is idempotent anyway, so a failed probe costs a request and never
- * correctness. Worth asking because the alternative is re-provisioning — and
- * rewriting an ACL — every time a service worker restarts, which is whenever
- * the browser feels like it.
- */
-export async function exists(pod, base) {
-  try {
-    const r = await pod.fetch(keepUrl(base), { method: 'HEAD' });
-    return r?.status >= 200 && r.status < 300;
-  } catch { return false; }
-}
-
-/** Bring a container into being with an owner-only rule. */
-export async function provisionOwnerOnly(pod, base) {
-  await pod.putJson(keepUrl(base), KEEP, KEEP_CT);
-  await pod.setAcl(base, []);
-}
-
-/** Bring a container into being, world-readable — a published tree. */
-export async function provisionPublic(pod, base) {
-  await pod.putJson(keepUrl(base), KEEP, KEEP_CT);
-  await pod.setAcl(base, ['Read']);
-}
-
-/**
- * The private half: the home itself and the state container.
- *
- * Idempotent, so two devices doing it at once is harmless — which is what
- * makes it safe to run on every boot rather than only at setup. Asked before
- * written: a browser's worker boots whenever the browser likes, and each boot
- * used to write the canary and both rules again. Returns whether it wrote.
- */
-export async function provisionPrivate(pod, urls) {
-  if (await exists(pod, urls.state)) return false;
-  await pod.putJson(keepUrl(urls.state), KEEP, KEEP_CT);
-  await pod.setAcl(urls.state, []);
-  await pod.setAcl(urls.home, []);
-  return true;
-}
-
-/**
- * Check the private trees are actually private, and put back any that are not.
- *
- * An ACL write that silently failed — or that something else changed
- * afterwards — leaves the private trees, signing keys among them, readable by
- * anyone. Setup writes them once and never returns, so this is what makes it a
- * standing property rather than a one-time hope.
- *
- * Returns what it found rather than logging: what a finding MEANS, and how
- * loudly to say it, belongs to the application.
- *
- * `isPublic` is supplied rather than assumed: how you decide a tree is
- * world-readable — which headers, which timeout — is the caller's business.
- *
- * @returns {Promise<Array<{url, rewritten, stillPublic, error}>>} one entry per
- *          tree that was readable without credentials; empty when all is well.
- */
-export async function repairPrivateAcls(pod, trees, { isPublic } = {}) {
-  const findings = [];
-  for (const url of trees) {
-    if (!await isPublic(url)) continue;
-    const finding = { url, rewritten: false, stillPublic: false, error: null };
-    findings.push(finding);
-    try {
-      await pod.setAcl(url, []);
-      finding.rewritten = true;
-    } catch (e) {
-      finding.error = e.message;
-      continue;
-    }
-    finding.stillPublic = await isPublic(url);
-  }
-  return findings;
-}
-
-// ---- anyone at all: what a stranger can see ----
-
-/**
- * Is this readable with no credentials?
- *
- * `accept: *\/*` matters. Asking for turtle makes a server answer 501 on the
- * JSON documents — webfinger, the actor — which reads as "unreachable" when
- * the world can in fact see them perfectly well.
- *
- * Unreachable is not a finding: a pod that failed to answer has not been shown
- * to be public, and treating that as one would rewrite ACLs on a network blip.
- */
-export async function probePublicReadability(probe, url, { headers = {}, timeoutMs = 20_000 } = {}) {
-  try {
-    const res = await probe(url, {
-      headers: { accept: '*/*', ...headers },
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-    return res.status < 400;
-  } catch { return false; }
-}
-
-/**
- * Does this pod actually ENFORCE an owner-only rule?
- *
- * A bare, unauthenticated read of the private container's canary must be
- * refused. Anything else — including a redirect to a login page, which is why
- * redirects are not followed — means documents meant to be private would not
- * be, and the caller should decline to put private things here.
- *
- * Takes a POD-SPACE url: an identity whose ids are advertised elsewhere must
- * map back to the pod first, because the rule being tested is the pod's.
- *
- * @returns {Promise<true|string>} true, or why not
- */
-export async function probePrivateEnforcement(probe, podKeepUrl) {
-  const r = await probe(podKeepUrl, { redirect: 'manual' });
-  if (r.status === 401 || r.status === 403) return true;
-  return `this pod serves private documents to strangers (HTTP ${r.status})`;
-}

package/lib/pod/discovery.mjs

@@ -1,46 +0,0 @@
-// discovery.mjs — the documents that make a handle resolve.
-//
-// These live at the HOST root, not in the actor's container, because that is
-// the only place the fediverse looks: @name@host is resolved at
-// https://host/.well-known/webfinger and nowhere else. A pod that does not own
-// the root of its host can still publish them, but nothing will ever ask.
-//
-// Every one is public by definition — a discovery document nobody may read
-// discovers nothing — so the Read rule is not a parameter here. It travels
-// with the write because publishing one of these unreadable is a failure mode
-// with an entire verification pass devoted to catching it.
-
-const PUBLIC_READ = ['Read'];
-
-// ---- the owner's agent ----
-
-/** The JRD that answers `acct:name@host`. */
-export async function writeWebfinger(pod, urls, jrd) {
-  await pod.putJson(urls.webfinger, jrd, 'application/jrd+json');
-  await pod.setAcl(urls.webfinger, PUBLIC_READ);
-}
-
-/** RFC 6415 host-meta: the LRDD template some implementations prefer. */
-export async function writeHostMeta(pod, urls, xml) {
-  const url = urls.base + '.well-known/host-meta';
-  await pod.put(url, xml, 'application/xrd+xml');
-  await pod.setAcl(url, PUBLIC_READ);
-}
-
-/**
- * NodeInfo, which is two documents: a pointer at the protocol-required root,
- * and the document itself in the actor's own tree.
- *
- * Four requests, one fact — "this pod answers nodeinfo". Split into separate
- * operations, a caller could write the pointer and not what it points at,
- * which is worse than neither.
- */
-export async function writeNodeinfo(pod, urls, { pointer, doc }) {
-  const pointerUrl = urls.base + '.well-known/nodeinfo';
-  const docUrl = urls.home + 'ap/nodeinfo-2.0';
-  await pod.putJson(pointerUrl, pointer, 'application/json');
-  await pod.setAcl(pointerUrl, PUBLIC_READ);
-  await pod.putJson(docUrl, doc, 'application/json');
-  await pod.setAcl(docUrl, PUBLIC_READ);
-  return docUrl;
-}

package/lib/pod/featured.mjs

@@ -1,18 +0,0 @@
-// featured.mjs — ap/featured and ap/moderators: the two small public rosters.
-//
-// Together because both are short, flat, public lists that say "these are the
-// ones that matter", and neither is big enough to page. `featured` is the
-// pinned posts; `moderators` is FEP-1b12's roster, which a recipient validates
-// a group's announced moderation against — published only when a group
-// actually has moderators, since an empty roster and no roster mean different
-// things.
-
-import * as collection from './collection.mjs';
-
-// ---- the owner's agent ----
-
-export const write = (pod, urls, doc) =>
-  collection.writeFlat(pod, urls.featured, doc, { publicRead: true });
-
-export const writeModerators = (pod, urls, doc) =>
-  collection.writeFlat(pod, urls.moderators, doc, { publicRead: true });

package/lib/pod/followers.mjs

@@ -1,24 +0,0 @@
-// followers.mjs — ap/followers: who follows this actor, paged.
-//
-// Paged like the outbox, and for the same reason: a popular account's follower
-// list is large, and a remote server should read a small head rather than pull
-// all of it. Read back to reconcile — anyone the pod says follows us that we
-// have no record of is a sign the local half is BEHIND the pod, and publishing
-// blindly over them would drop them from the wire.
-
-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.followers, doc, opts);
-export const dropPage = (pod, pageUrl) => collection.dropPage(pod, pageUrl);
-
-/**
- * Every follower the pod currently publishes, or null if it publishes none.
- *
- * `alsoItems`, unlike the outbox: the flat followers collection this project
- * used to write put them under `items` rather than `orderedItems`.
- */
-export const readPublished = (pod, urls) =>
-  collection.readPaged(pod, urls.followers, { max: 100_000, alsoItems: true });

package/lib/pod/following.mjs

@@ -1,10 +0,0 @@
-// following.mjs — ap/following: who this actor follows.
-//
-// Flat, not paged: it is bounded by what one person chose to do, where the
-// followers list is bounded by what everyone else chose.
-
-import * as collection from './collection.mjs';
-
-// ---- the owner's agent ----
-
-export const write = (pod, urls, doc, opts) => collection.writeFlat(pod, urls.following, doc, opts);

package/lib/pod/http.mjs

@@ -1,74 +0,0 @@
-// http.mjs — the two HTTP manners this library needs, and nothing else.
-//
-// FediPod has lib/safefetch.mjs, which does far more: DNS pinning, private
-// address refusal, redirect re-checking. None of that can come here, because
-// it imports node:dns and node:net and this library must run unmodified inside
-// a service worker. What IS needed on both sides is a byte budget and a reading
-// of Retry-After, so they live here in a form with no runtime of their own.
-//
-// Deliberately NOT a fetch wrapper. The library never opens a connection by
-// itself; every request goes through a transport or a fetcher the caller
-// supplies, which is what lets the same code serve an authenticated agent, a
-// keyless gateway, and a test with no network at all.
-
-// Five megabytes is what the wider project uses as a body budget, and a
-// document this library reads is a pod resource, not a stranger's timeline.
-const MAX_BYTES = 5 * 1024 * 1024;
-
-// Thirty minutes is a ceiling, not a policy: a hostile or confused header must
-// not be able to park a caller for a day. Callers that want a tighter ceiling
-// pass their own — the browser transport does.
-const COOLDOWN_MAX_MS = 30 * 60_000;
-
-/**
- * How long a server asked to be left alone, or **null** when it did not say.
- *
- * The null matters and must not become a default. The caller decides what
- * absence means: a pod falls back to a flat cooldown, while a delivery queue
- * keeps its exponential ladder — and returning a default here once collapsed
- * that ladder to a flat 60s for every 503 without the header, which is most
- * of them.
- */
-export function retryAfterMs(res, max = COOLDOWN_MAX_MS) {
-  const raw = res?.headers?.get?.('retry-after');
-  if (!raw) return null;
-  const secs = Number(raw);
-  // A floor of one second: a server answering `Retry-After: 0` is still asking
-  // for a pause, and honouring it as "none" is how a throttle becomes a spin.
-  if (Number.isFinite(secs)) return Math.min(Math.max(secs, 1) * 1000, max);
-  const when = Date.parse(raw);                       // the HTTP-date spelling
-  if (Number.isFinite(when)) return Math.min(Math.max(when - Date.now(), 1000), max);
-  return null;
-}
-
-/**
- * Read a response body with a hard byte budget.
- *
- * Checking `content-length` and then handing back `res.text()` is not a cap: a
- * chunked response carries no `content-length` at all, and an inbox listing is
- * public-Append, so its size is in other people's hands. Stream it and stop at
- * the budget.
- *
- * TextDecoder rather than Buffer — it exists in both runtimes — and
- * `stream: true` so a UTF-8 sequence split across two chunks still decodes.
- */
-export async function readCapped(res, max = MAX_BYTES) {
-  const len = Number(res.headers?.get?.('content-length') || 0);
-  if (len > max) throw new Error(`response too large (${len} bytes)`);
-  if (!res.body) return res.text();
-  const reader = res.body.getReader();
-  const decoder = new TextDecoder('utf-8');
-  let out = '';
-  let total = 0;
-  for (;;) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    total += value.length;
-    if (total > max) {
-      await reader.cancel();
-      throw new Error(`response exceeded ${max} bytes`);
-    }
-    out += decoder.decode(value, { stream: true });
-  }
-  return out + decoder.decode();
-}