fedipod-server 0.29.0 → 0.30.0

package/lib/gateway/quiet.mjs

@@ -1,189 +0,0 @@
-// quiet.mjs — accounts that go quiet: what the front knows about an account
-// nobody opens, and what its owner may say about it. The router in
-// front-core.mjs asks closedState/accountState at the door and on every
-// public read, stamps noteOpened from the relay, counts noteReceived after
-// a forwarded delivery, and hands /api/open, /api/pause and /api/close here.
-
-// ---- accounts that go quiet -------------------------------------------------
-//
-// The gateway holds no mail: every delivery it takes is two writes into the
-// owner's pod inbox, read only when their browser is open. An account nobody
-// opens grows on its pod without limit, and its owner comes back to a drain
-// of everything at once. So the front keeps two facts about each browser
-// account — when its owner was last here, and how much content has arrived
-// since — and acts on them.
-//
-// `openedAt` is written when the owner signs in (POST /api/open, always) and
-// while they act through the relay (at most hourly). The count of content
-// deliveries since then lives in its own record, keyed by handle AND
-// openedAt: a fresh stamp starts a fresh count with nothing to reset, and a
-// delivery's write can never overwrite a sign-in's. Two deliveries landing
-// together may each read the same total and one increment is lost — the cap
-// comes out slightly soft, never too strict.
-//
-// PAUSED: the count has reached the cap, or the owner said so. Content is
-// accepted and discarded, control (follows, unfollows, moves, deletions,
-// blocks) still lands. The owner's next sign-in ends a cap pause by itself; a
-// pause they set lasts until they lift it.
-//
-// CLOSED: the owner said so, or nothing has opened the account for the close
-// window. Found closed by time, it is written down so it stays closed. From
-// then on the door, the actor and the handle answer 410 — never a failure
-// code, which senders retry and count against this whole host, and never a
-// success, which would keep them sending. Nothing on the pod is touched. An
-// address that moved (see /api/move) keeps answering as moved; closing does
-// not take that away.
-//
-// Only an account whose owner has signed in from a browser carries
-// `openedAt`. A DeviceAgent behind this door never does: it drains its own
-// inbox as it runs, so it is never counted, never paused and never closed by
-// time. Accounts from before this was built are counted from their next
-// sign-in.
-export const DEFAULT_PAUSE_ITEMS = 5000;
-export const DEFAULT_CLOSE_DAYS = 183;                // six months
-const OPEN_STAMP_EVERY_MS = 60 * 60_000;              // the relay's stamp, at most hourly
-const pauseItemsOf = (ctx) => (Number(ctx.pauseItems) > 0 ? Number(ctx.pauseItems) : DEFAULT_PAUSE_ITEMS);
-const closeDaysOf = (ctx) => (Number(ctx.closeDays) > 0 ? Number(ctx.closeDays) : DEFAULT_CLOSE_DAYS);
-const receivedKey = (key, rec) => `${key}/${rec.openedAt}`;
-
-export async function receivedSince(ctx, key, rec) {
-  if (!ctx.readReceived || !rec.openedAt) return { items: 0, bytes: 0 };
-  const got = await ctx.readReceived(receivedKey(key, rec)).catch(() => null);
-  return { items: Number(got?.items) || 0, bytes: Number(got?.bytes) || 0 };
-}
-
-// One more content delivery reached the pod. Nothing to count against until
-// the owner has been here once.
-export async function noteReceived(ctx, key, rec, bytes) {
-  if (!ctx.readReceived || !ctx.writeReceived || !rec.openedAt) return;
-  const so = await receivedSince(ctx, key, rec);
-  await ctx.writeReceived(receivedKey(key, rec), { items: so.items + 1, bytes: so.bytes + (Number(bytes) || 0) })
-    .catch((e) => console.log(`front @${key}: count not written: ${e?.message || e}`));
-}
-
-// The owner is here. `always` is a sign-in; the relay stamps at most hourly,
-// so a busy hour of posting is one write. The count that went with the old
-// stamp is dropped: it is over, and a store should not keep one per hour.
-export async function noteOpened(ctx, key, rec, { always = false } = {}) {
-  if (!ctx.putDirectory) return rec;
-  if (!always && rec.openedAt && Date.now() - Date.parse(rec.openedAt) < OPEN_STAMP_EVERY_MS) return rec;
-  const next = { ...rec, openedAt: new Date().toISOString() };
-  await ctx.putDirectory(key, next);
-  if (rec.openedAt && ctx.dropReceived) await ctx.dropReceived(receivedKey(key, rec)).catch(() => {});
-  return next;
-}
-
-// Closed, and why. Reads no count: this is asked on every public read.
-export async function closedState(ctx, key, rec) {
-  if (rec.movedTo) return { closed: false };
-  if (rec.closedAt) return { closed: true, closedAt: rec.closedAt, closedBy: rec.closedBy || 'owner' };
-  if (rec.openedAt && Date.now() - Date.parse(rec.openedAt) > closeDaysOf(ctx) * 86400_000) {
-    const closedAt = new Date().toISOString();
-    if (ctx.putDirectory) await ctx.putDirectory(key, { ...rec, closedAt, closedBy: 'quiet' });
-    console.log(`front @${key}: closed — nothing opened it since ${rec.openedAt}`);
-    return { closed: true, closedAt, closedBy: 'quiet' };
-  }
-  return { closed: false };
-}
-
-// The whole standing of an account, for the door and for its owner's page.
-export async function accountState(ctx, key, rec) {
-  const c = await closedState(ctx, key, rec);
-  const received = c.closed ? { items: 0, bytes: 0 } : await receivedSince(ctx, key, rec);
-  const cap = pauseItemsOf(ctx);
-  const pausedBy = c.closed ? null : rec.pausedAt ? 'owner' : received.items >= cap ? 'quiet' : null;
-  return {
-    closed: c.closed, closedAt: c.closedAt || null, closedBy: c.closedBy || null,
-    paused: !!pausedBy, pausedBy, pausedAt: rec.pausedAt || null,
-    openedAt: rec.openedAt || null, received, pauseItems: cap, closeDays: closeDaysOf(ctx),
-  };
-}
-
-// A 410 with a reason, the shape every closed or moved id answers with.
-export const closedAnswer = (headers = {}, why = 'this address is closed') => ({
-  status: 410, headers: { 'cache-control': 'no-store', ...headers, 'content-type': 'application/json' },
-  body: JSON.stringify({ error: why }) });
-
-// The owner of a row, proved the way the relay proves them: a pod token whose
-// WebID is the row's, or lives on the row's pod for a row from before WebIDs
-// were recorded.
-async function provedOwner(request, pathname, ctx, rec, { j, verifyPodToken, webidUnderPod }) {
-  const webid = await verifyPodToken(request, pathname, ctx.verifier);
-  if (!webid) return { error: j(401, { error: 'a Solid-OIDC token proving the pod is required' }) };
-  const owner = rec.webId ? webid === rec.webId : webidUnderPod(webid, rec.podHome);
-  if (!owner) return { error: j(403, { error: "the token proves a different pod than this account's" }) };
-  return { webid };
-}
-
-// The owner's three routes. `deps` are front-core's own JSON reply and
-// token check, handed in so this module stays free of the router's privates.
-// Returns a response, or null when the path is not one of these.
-export async function routeQuietApi(request, pathname, ctx, deps) {
-  const { j } = deps;
-  if (!['/api/open', '/api/pause', '/api/close'].includes(pathname)) return null;
-  // A page at another origin asks first whether it may call, and is answered
-  // as the relay answers it. Unanswered, the browser never sends the call and
-  // some pages asked again every minute.
-  if (request.method === 'OPTIONS') return deps.apiPreflight();
-  if (request.method !== 'POST') return null;
-  // The owner is here: their browser says so as it opens the account. The
-  // answer is the account's standing at this gateway, which the manage page
-  // shows. A closed address is told so and nothing is written.
-  if (pathname === '/api/open' && request.method === 'POST') {
-    if (!ctx.putDirectory) return j(501, { error: 'this front keeps no directory' });
-    let body;
-    try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
-    const handle = String(body.handle || '').toLowerCase();
-    let rec = await ctx.lookup(handle);
-    if (!rec) return j(404, { error: 'no such account' });
-    const who = await provedOwner(request, pathname, ctx, rec, deps);
-    if (who.error) return who.error;
-    const before = await closedState(ctx, handle, rec);
-    if (before.closed) return j(410, { error: 'this address is closed', closedAt: before.closedAt, closedBy: before.closedBy });
-    rec = await noteOpened(ctx, handle, rec, { always: true });
-    return j(200, { ok: true, handle, ...await accountState(ctx, handle, rec) });
-  }
-
-  // The owner pausing their own account, or lifting the pause they set.
-  if (pathname === '/api/pause' && request.method === 'POST') {
-    if (!ctx.putDirectory) return j(501, { error: 'this front keeps no directory' });
-    let body;
-    try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
-    const handle = String(body.handle || '').toLowerCase();
-    let rec = await ctx.lookup(handle);
-    if (!rec) return j(404, { error: 'no such account' });
-    const who = await provedOwner(request, pathname, ctx, rec, deps);
-    if (who.error) return who.error;
-    const before = await closedState(ctx, handle, rec);
-    if (before.closed) return j(410, { error: 'this address is closed', closedAt: before.closedAt });
-    if (typeof body.paused !== 'boolean') return j(400, { error: 'paused must be true or false' });
-    if (body.paused && !rec.pausedAt) rec = { ...rec, pausedAt: new Date().toISOString() };
-    if (!body.paused && rec.pausedAt) { rec = { ...rec }; delete rec.pausedAt; }
-    // Lifting a pause is a sign-in's worth of "I am here": the count starts over.
-    if (!body.paused) rec = { ...rec, openedAt: new Date().toISOString() };
-    await ctx.putDirectory(handle, rec);
-    console.log(`front @${handle}: ${body.paused ? 'paused' : 'resumed'} by its owner`);
-    return j(200, { ok: true, handle, ...await accountState(ctx, handle, rec) });
-  }
-
-  // The owner closing their address for good. Repeating it changes nothing.
-  if (pathname === '/api/close' && request.method === 'POST') {
-    if (!ctx.putDirectory) return j(501, { error: 'this front keeps no directory' });
-    let body;
-    try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
-    const handle = String(body.handle || '').toLowerCase();
-    let rec = await ctx.lookup(handle);
-    if (!rec) return j(404, { error: 'no such account' });
-    const who = await provedOwner(request, pathname, ctx, rec, deps);
-    if (who.error) return who.error;
-    if (body.confirm !== true) return j(400, { error: 'closing is for good — send confirm: true' });
-    if (!rec.closedAt) {
-      rec = { ...rec, closedAt: new Date().toISOString(), closedBy: 'owner' };
-      await ctx.putDirectory(handle, rec);
-      console.log(`front @${handle}: closed by its owner`);
-    }
-    return j(200, { ok: true, handle, ...await accountState(ctx, handle, rec) });
-  }
-
-  return null;
-}

package/lib/gateway/relay-extras.mjs

@@ -1,89 +0,0 @@
-// relay-extras.mjs — the relay's single request, and what the relay notices
-// about the requests it carries.
-//
-// relayOne(): sends one request a browser-run agent has already signed, with
-// exactly the headers that were signed. It forwards a signature and cannot
-// make one: a POST must carry one, by this account's own key, over the body
-// its Digest names.
-//
-// withdrawn(): a relayed delivery that withdraws something of the account's —
-// a Delete, or an Undo — means the copies the edge holds of that account's
-// documents are out of date; the front purges them rather than serving a
-// deleted post for the rest of its hold.
-//
-// overLimit(): how many requests one account may have the relay carry. Counted
-// per running instance, which bounds a runaway agent or a stolen token without
-// any shared state; a real account sends nowhere near it.
-
-import crypto from 'node:crypto';
-import { readCapped, safeFetch } from '../shared/safefetch.mjs';
-
-const RELAY_MAX_BODY = 1024 * 1024;
-const RELAY_TIMEOUT_MS = 8_000;
-// The only headers a relayed request may carry to the remote server. Host
-// comes from the URL; the user agent from safeFetch.
-const RELAY_HEADERS = new Set(['date', 'digest', 'signature', 'content-type', 'accept']);
-const keyIdOf = (signature) => (/keyId="([^"]+)"/.exec(signature || '') || [])[1] || null;
-
-export async function relayOne(item, rec, fetchImpl) {
-  const url = String(item?.url || '');
-  const method = String(item?.method || 'POST').toUpperCase();
-  if (method !== 'GET' && method !== 'POST') return { url, status: 0, error: 'method must be GET or POST' };
-  let u;
-  try { u = new URL(url); } catch { return { url, status: 0, error: 'not a URL' }; }
-  if (u.protocol !== 'https:' && !(u.protocol === 'http:' && process.env.AP_ALLOW_PRIVATE_TARGETS === '1')) {
-    return { url, status: 0, error: 'https only' };
-  }
-  const headers = {};
-  for (const [k, v] of Object.entries(item?.headers || {})) {
-    const name = k.toLowerCase();
-    if (RELAY_HEADERS.has(name) && typeof v === 'string') headers[name] = v;
-  }
-  const body = method === 'POST' ? String(item?.body ?? '') : undefined;
-  if (body !== undefined && Buffer.byteLength(body) > RELAY_MAX_BODY) return { url, status: 0, error: 'body too large' };
-  const keyId = keyIdOf(headers.signature);
-  if (method === 'POST' && !keyId) return { url, status: 0, error: 'a delivery must be signed' };
-  if (keyId && !keyId.startsWith(rec.actorUrl + '#')) return { url, status: 0, error: "signed with a key that is not this account's" };
-  if (headers.digest) {
-    const want = 'SHA-256=' + crypto.createHash('sha256').update(body || '').digest('base64');
-    if (headers.digest !== want) return { url, status: 0, error: 'digest does not match the body' };
-  }
-  try {
-    const res = await safeFetch(url, { method, headers, body, signal: AbortSignal.timeout(RELAY_TIMEOUT_MS) }, fetchImpl);
-    const out = { url, method, status: res.status };
-    // The far server asking to be left alone has to reach the agent that will
-    // do the asking again. Without this the browser build could not honour a
-    // Retry-After at all — every delivery it makes goes through here — and fell
-    // back to its own ladder against a server that had already said how long.
-    const retryAfter = res.headers.get('retry-after');
-    if (retryAfter) out.retryAfter = retryAfter;
-    if (method === 'GET') {
-      out.contentType = res.headers.get('content-type') || null;
-      out.body = await readCapped(res, RELAY_MAX_BODY);
-    }
-    return out;
-  } catch (e) { return { url, method, status: 0, error: e.message }; }
-}
-
-const WINDOW_MS = 10 * 60 * 1000;
-const PER_WINDOW = 600;
-const counts = new Map();   // handle → { since, n }
-
-export function withdrawn(items, actorUrl) {
-  return items.some((it) => {
-    if (String(it?.method || 'POST').toUpperCase() !== 'POST') return false;
-    try {
-      const a = JSON.parse(String(it?.body ?? ''));
-      return a?.actor === actorUrl && (a.type === 'Delete' || a.type === 'Undo');
-    } catch { return false; }
-  });
-}
-
-export function overLimit(handle, n, now = Date.now()) {
-  const c = counts.get(handle);
-  const fresh = !c || now - c.since > WINDOW_MS ? { since: now, n: 0 } : c;
-  fresh.n += n;
-  counts.set(handle, fresh);
-  if (counts.size > 10_000) counts.clear();
-  return fresh.n > PER_WINDOW;
-}

package/lib/gateway/token-claims.mjs

@@ -1,16 +0,0 @@
-// token-claims.mjs — who a Solid access token says it is for, unchecked.
-//
-// Only for choosing where to send a read that the pod checks anyway: the
-// owner's full outbox lives on the pod under the owner's own rule, so reading
-// the claim decides nothing but the address. Verifying it here would let
-// anyone make the front fetch signing keys from a server they name, on every
-// read.
-
-export function claimedWebId(request) {
-  const token = /^(?:DPoP|Bearer)\s+([\w-]+)\.([\w-]+)\./u.exec(request.headers.get('authorization') || '');
-  if (!token) return null;
-  try {
-    const claims = JSON.parse(Buffer.from(token[2], 'base64url').toString('utf8'));
-    return typeof claims?.webid === 'string' ? claims.webid : null;
-  } catch { return null; }
-}

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})`;
-}