fedipod-server 0.10.0 → 0.12.1

package/lib/pod/actor.mjs

@@ -0,0 +1,96 @@
+// 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' }) {
+  return pod.linkAccountInProfile({ actorUrl, accountName, kind });
+}
+
+// ---- 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

@@ -0,0 +1,77 @@
+// 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

@@ -0,0 +1,136 @@
+// 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.
+ */
+export async function provisionPrivate(pod, urls) {
+  await pod.putJson(keepUrl(urls.state), KEEP, KEEP_CT);
+  await pod.setAcl(urls.state, []);
+  await pod.setAcl(urls.home, []);
+}
+
+/**
+ * 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

@@ -0,0 +1,46 @@
+// 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

@@ -0,0 +1,18 @@
+// 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

@@ -0,0 +1,24 @@
+// 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

@@ -0,0 +1,10 @@
+// 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

@@ -0,0 +1,74 @@
+// 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();
+}

package/lib/pod/inbox.mjs

@@ -0,0 +1,144 @@
+// inbox.mjs — ap/inbox/: what arrives, and who may touch it.
+//
+// One file for the whole inbox, because the inbox is where two different
+// parties meet and neither half is comprehensible alone: a delivery gateway
+// may only ADD to it, holding at most an Append token; the owner's agent
+// lists, reads and removes, holding the pod's own credential. Splitting them
+// by who does them would put the two ends of one contract in two files.
+
+const DELIVERY_CT = 'application/activity+json';
+const RECEIPT_CT = 'application/json';
+
+// ---- a delivery gateway: appends verified mail, and can do nothing else ----
+
+/**
+ * PUT one document into a pod inbox, with an Append token when the caller
+ * holds one and anonymously when it does not.
+ *
+ * Sending no `authorization` header is not the same as sending an empty one:
+ * `Bearer undefined` is a credential the pod will reject, where absence is a
+ * public Append the pod may well allow. This is the one place that gets to
+ * decide that, because it lived in two adapters and had to be right in both.
+ *
+ * @returns {Promise<boolean>} whether it landed
+ */
+export async function appendWithToken(url, body, contentType, { appendToken = null, fetchImpl = fetch } = {}) {
+  const headers = { 'content-type': contentType,
+    ...(appendToken ? { authorization: `Bearer ${appendToken}` } : {}) };
+  const r = await fetchImpl(url, { method: 'PUT', headers, body }).catch(() => null);
+  return !!r && r.status < 400;
+}
+
+/**
+ * The delivery itself, named by the hash of its own bytes.
+ *
+ * Content-addressed on purpose: the same activity delivered twice writes the
+ * same document twice, so a retrying origin cannot produce duplicates in
+ * someone's inbox.
+ *
+ * A failure here must reach the ORIGIN as a 5xx so it retries over its own
+ * ladder — that is what preserves the pod's buffer property without the
+ * gateway holding any state of its own.
+ */
+export async function appendVerifiedDelivery(podPut, inboxUrl, hash, raw) {
+  return podPut(inboxUrl + hash, raw, DELIVERY_CT);
+}
+
+/**
+ * The verification receipt, written beside the delivery it vouches for.
+ *
+ * Best-effort by design: a delivery that landed but whose receipt did not is
+ * read as unverified at the drain, which is a lesser thing than losing it.
+ */
+export async function writeReceiptBeside(podPut, inboxUrl, hash, receipt) {
+  await podPut(inboxUrl + hash + '.receipt.json', JSON.stringify(receipt), RECEIPT_CT)
+    .catch(() => {});
+}
+
+// ---- the owner's agent: brings it into being and decides who may post ----
+
+/**
+ * The canary that makes the container exist.
+ *
+ * Written without an access rule of its own, because the rule that matters is
+ * the container's and is stated separately — see setPosture, which a caller
+ * must reach for deliberately rather than inherit by accident.
+ */
+export async function writeKeep(pod, urls) {
+  await pod.putJson(urls.inbox + '.keep', { keep: true }, 'application/json');
+}
+
+/**
+ * Who may deliver here.
+ *
+ *   'open'                 anyone may Append — an inbox the fediverse can post to
+ *   'closed'               nobody may — a quiesced actor, still resolving, taking no mail
+ *   { gatewayWebId }       only that WebID may — mail arrives through a door that
+ *                          verifies it first, and nobody may go round the door
+ *
+ * One operation because the three are one decision, and they were made in five
+ * places: the profile publish, three separate methods, and the manage surface
+ * reaching past all of them to set the ACL directly. A posture set in one of
+ * those and not the others is an inbox that is open when it should be shut.
+ */
+export async function setPosture(pod, urls, posture) {
+  if (posture === 'open') return pod.setAcl(urls.inbox, ['Append']);
+  if (posture === 'closed') return pod.setAcl(urls.inbox, []);
+  const webId = posture?.gatewayWebId;
+  if (!webId) throw new Error(`inbox.setPosture: unknown posture ${JSON.stringify(posture)}`);
+  // Public loses Append; the door keeps it. Both halves in one write, because
+  // between two writes the inbox is either open to everyone or shut to the door.
+  return pod.setAcl(urls.inbox, [], { appendAgents: [webId] });
+}
+
+/**
+ * What is waiting, oldest first.
+ *
+ * A defensive copy, because the transport hands back the SAME array on a 304
+ * and the inbox is polled constantly — a caller that sorted or spliced in
+ * place would corrupt the cache for every later reader.
+ */
+export async function list(pod, urls) {
+  const children = await pod.listContainer(urls.inbox);
+  return children.map((c) => ({ ...c }));
+}
+
+/**
+ * One item's bytes.
+ *
+ * A pod that would not GIVE us the item has told us nothing about it. Reading
+ * a 500 as an empty body once made it "unparsable JSON" — which is a
+ * REJECTION, so the delivery was dead-lettered with nothing recorded and then
+ * DELETED: destroyed by a transient fault, with no trace of what it had been.
+ * Anything but 404 throws, and the caller's retry path takes it. 404 is the
+ * exception: the item is already gone, so removing it is right.
+ *
+ * Capped rather than read whole: the listing's size is advisory, the inbox is
+ * public-Append, and the body is whatever a stranger chose to send.
+ *
+ * @returns {Promise<{status:number, raw:string|null}>}
+ */
+export async function readItem(pod, url, { maxBytes, readCapped }) {
+  const res = await pod.fetch(url, { headers: { accept: '*/*' } });
+  if (res.status >= 400 && res.status !== 404) throw new Error(`inbox item GET → ${res.status}`);
+  return { status: res.status, raw: res.status < 400 ? await readCapped(res, maxBytes) : null };
+}
+
+/** The gateway's receipt for an item, unparsed and unverified, or null. */
+export async function readDeliveryReceipt(pod, itemUrl, { maxBytes, readCapped }) {
+  const res = await pod.fetch(itemUrl + '.receipt.json', { headers: { accept: 'application/json' } });
+  if (res.status >= 400) return null;
+  return JSON.parse(await readCapped(res, maxBytes));
+}
+
+/**
+ * Remove an item that has been dealt with.
+ *
+ * This must NOT know about the caller's state: the drain deletes only after
+ * its own state write has landed, and folding that gate in here would put the
+ * decision somewhere with no view of whether it did. Getting that wrong
+ * deletes deliveries whose record never persisted — silent, and unrecoverable.
+ *
+ * @returns {Promise<boolean>} whether the pod removed it
+ */
+export const dropHandledItem = (pod, url) => pod.delete(url);

package/lib/{links.mjs → pod/links.mjs}

@@ -27,7 +27,7 @@ export function linkTargets(headerValue, rel, baseUrl) {
   return out;
 }
 
-/** The relations this project follows. */
+/** The relations this library follows. */
 export const REL = {
   acl: 'acl',
   storageDescription: 'http://www.w3.org/ns/solid/terms#storageDescription',

package/lib/pod/media.mjs

@@ -0,0 +1,27 @@
+// media.mjs — ap/media/: the bytes an attachment points at.
+//
+// The only tree here holding things that are not documents. Public-Read,
+// because an attachment url travels inside a post to servers that will fetch
+// it without credentials — and unlike an actor or a note, nothing checks that
+// the url belongs to the identity that posted it, which is why media stays on
+// the pod even for an identity whose ids are advertised elsewhere: proxying
+// blobs would be pure cost for no verification gained.
+
+const PUBLIC_READ = ['Read'];
+
+// ---- the owner's agent ----
+
+export async function provisionContainer(pod, urls) {
+  await pod.putJson(urls.media + '.keep', { keep: true }, 'application/json');
+  await pod.setAcl(urls.media, PUBLIC_READ);
+}
+
+/**
+ * One uploaded file.
+ *
+ * Takes the container as given: an upload into a container that was never
+ * provisioned is a 404, or worse a file nobody outside can read, so the caller
+ * ensures the container first — see provisionContainer, and the `exists` probe
+ * in containers.mjs that keeps a worker restart from re-provisioning.
+ */
+export const write = (pod, url, bytes, contentType) => pod.put(url, bytes, contentType);