fedipod-server 0.10.0 → 0.12.1

package/lib/{remote.mjs → pod/transport.mjs}

@@ -1,11 +1,20 @@
-// remote.mjs — authenticated I/O against the remote pod, via CSS
-// client-credentials + DPoP (vendor/idp-grant.cjs, extracted from
-// data-kitchen's "remember this IdP" machinery — plain Node, no Electron).
+// transport.mjs — every authenticated request this library makes to a pod, and
+// the manners that must hold for all of them.
+//
+// The session is injected and never built here: a Node agent hands in a DPoP
+// client-credentials grant, a browser hands in a Solid-OIDC session, a pod
+// server hands in a shim straight onto its own store. That is what lets one
+// implementation serve all three, and it is why this file has no `import` of
+// anything with a runtime.
+//
+// Two copies of this used to exist — lib/remote.mjs and web/app/pod-remote.mjs
+// — hand-kept in sync, with the browser copy quietly behind on five separate
+// hardenings. The subclasses below now add only what genuinely differs: how the
+// session is obtained, and whether a throttled pod is waited out or refused.
 
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import * as $rdf from 'rdflib';
+import { readCapped, retryAfterMs } from './http.mjs';
+import { linkTargets, REL } from './links.mjs';
 
 const LDP = $rdf.Namespace('http://www.w3.org/ns/ldp#');
 const DC = $rdf.Namespace('http://purl.org/dc/terms/');
@@ -15,24 +24,8 @@ const ACL = $rdf.Namespace('http://www.w3.org/ns/auth/acl#');
 const FOAF = $rdf.Namespace('http://xmlns.com/foaf/0.1/');
 const AS = $rdf.Namespace('https://www.w3.org/ns/activitystreams#');
 
-const require = createRequire(import.meta.url);
-const vendorDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../vendor');
-const { mintCredential, discoverTokenEndpoint, createGrantSession, revokeCredentialViaAccount } =
-  require(path.join(vendorDir, 'idp-grant.cjs'));
-
-export { mintCredential, discoverTokenEndpoint, revokeCredentialViaAccount };
-
-// A pod that answers 429 or 503 is asking to be left alone; Retry-After says
-// for how long. Every request to this pod goes through one cooldown, so a
-// server under strain gets silence rather than each timer discovering the
-// refusal separately. Requests during the window fail fast — no socket is
-// opened — and the callers' existing retry paths take it from there.
-// The parser is shared with the outbound path; see lib/safefetch.mjs.
-import { retryAfterMs, readCapped } from './safefetch.mjs';
-import { linkTargets, REL } from './links.mjs';
-
 // A pod whose access rules are ACP policies, not WAC authorizations. This
-// agent writes WAC; over an ACP resource that would be noise where the pod's
+// library writes WAC; over an ACP resource that would be noise where the pod's
 // real rules used to be, so it stops instead.
 const ACP_NS = 'http://www.w3.org/ns/solid/acp#';
 
@@ -40,13 +33,19 @@ const ACP_NS = 'http://www.w3.org/ns/solid/acp#';
 // hands; reading it whole must still have a ceiling.
 const LISTING_MAX_BYTES = 10 * 1024 * 1024;
 
+// No Retry-After header still means "not now". Sixty seconds is the answer
+// when the server declined to give one.
+const COOLDOWN_DEFAULT_MS = 60_000;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
 // A pod's ability to BE a pod. Not data, and never ours to remove: delete one
 // of these and the pod does not degrade, it stops — and it cannot be repaired
 // by the tool that broke it, because that tool can no longer authenticate. A
 // pod was crippled exactly this way.
 //
-// Here rather than in any one script, because every DELETE this project sends
-// goes through RemotePod.delete — so this is the one place that cannot be
+// Here rather than in any one caller, because every DELETE this library sends
+// goes through PodTransport.fetch — so this is the one place that cannot be
 // routed around. A DENY-list, not an allow-prefix: the next script will have a
 // different prefix and the same list of things it must never touch.
 const PROTECTED = [
@@ -70,100 +69,160 @@ export function protectedFromDeletion(url) {
   if (p === '/' || p === '') throw new Error(`refusing to DELETE the pod root: ${url}`);
   for (const [re, why] of PROTECTED) {
     if (re.test(p)) {
-      throw new Error(`refusing to DELETE ${url} — ${why}. Deny-list: lib/remote.mjs.`);
+      throw new Error(`refusing to DELETE ${url} — ${why}. Deny-list: lib/pod/transport.mjs.`);
     }
   }
 }
 
-export class RemotePod {
-  constructor(credential, { log = () => {}, home = null, session = null } = {}) {
-    // An injected session replaces the credential-backed one, and everything
-    // below it — the cooldown, the deny-list, the url map — is unchanged. That
-    // is how the agent runs inside a pod server: same class, no token to mint.
-    this.session = session || createGrantSession(credential, home ? {
-      backoffFile: path.join(home, 'backoff.json'),
-      tokenFile: path.join(home, 'token.json'),
-    } : {});
-    this.webId = credential.webId;
+export class PodTransport {
+  /**
+   * @param {object} session          `{ fetch(url, init) }` — injected, never built here
+   * @param {object} opts
+   * @param {string} opts.webId       who this transport acts as; the ACL owner
+   * @param {string} [opts.role]      'agent' | 'gateway' | 'signup' — what is talking
+   * @param {string} [opts.runtime]   'node' | 'browser' — where it is talking from
+   * @param {string} [opts.cooldownMode] 'refuse' fails fast for the window;
+   *                                  'wait' sleeps it out and continues
+   * @param {number} [opts.maxCooldownMs] ceiling on a Retry-After we will honour
+   */
+  constructor(session, {
+    webId, log = () => {}, role = 'agent', runtime = 'node',
+    cooldownMode = 'refuse', maxCooldownMs = 30 * 60_000,
+  } = {}) {
+    this.session = session;
+    this.webId = webId;
+    this.log = log;
+    this.role = role;
+    this.runtime = runtime;
+    this.cooldownMode = cooldownMode;
+    this.maxCooldownMs = maxCooldownMs;
     this.pausedUntil = 0;
     this.probeCount = 0;
-    this.log = log;
     // Where each resource's access control lives, as the pod itself said. WAC
     // forbids working it out from the resource's own URL, so it is asked for
     // and remembered rather than assembled.
     this.aclUrls = new Map();
     this.aclFlavour = null;      // null until the first write asks what this pod speaks
+    this._listCache = new Map();
     // A fronted identity advertises ids on a shared domain but writes to the
-    // pod. run-agent installs the fronted→pod mapping here, so every request
-    // built from an advertised id lands on the pod — one choke point, and
-    // publisher/social/intake stay unaware. Unset → identity, byte-for-byte
-    // the unfronted behaviour.
+    // pod. The caller installs the advertised→pod mapping here, so every
+    // request built from an advertised id lands on the pod — one choke point.
+    // Unset → identity, byte-for-byte the unfronted behaviour.
     this.toPod = null;
   }
 
-  // Install the advertised→pod url map for a fronted identity (urls.toPod).
+  /** Who is talking, and from where — the prefix on every log line and error. */
+  get label() { return `${this.role}/${this.runtime}`; }
+
+  /** One line for a boot log: what this transport is and what it points at. */
+  describe() {
+    return `${this.role} over a ${this.runtime} session → ${this.webId?.split('#')[0] || 'unknown'}`;
+  }
+
+  /** Install the advertised→pod url map for a fronted identity (urls.toPod). */
   setUrlMap(fn) { this.toPod = typeof fn === 'function' ? fn : null; }
 
-  async warmup() { return this.session.warmup(); }
+  async warmup() { return this.session.warmup?.(); }
 
-  // What we have asked of this pod, for /status and for answering an operator.
+  /** What we have asked of this pod, for a status page or an operator. */
   stats() {
     return {
-      ...this.session.stats(),
+      role: this.role,
+      runtime: this.runtime,
       probes: this.probeCount,
       pausedFor: Math.max(0, Math.round((this.pausedUntil - Date.now()) / 1000)),
     };
   }
 
-  // A deliberately CREDENTIAL-FREE request: it asks what a stranger would see,
-  // so it cannot go through session.fetch without answering a different
-  // question. It still belongs to this pod, though — it opens a socket to it
-  // and takes one of its workers — so it observes the same Retry-After window
-  // and is counted. Ten of these ride on every profile save, and none of them
-  // used to appear in /status, which made podRequests under-report by design.
-  async probe(url, init = {}) {
+  /**
+   * Observe a throttling answer and arm the pod-wide cooldown.
+   *
+   * One pause for the whole pod, not one per request: without it every
+   * in-flight call rides its own ladder into a server that has already said it
+   * is overloaded, which is how a throttle becomes a stampede. A 429 or 503
+   * with NO Retry-After still arms the window — the browser copy used to arm
+   * nothing at all in that case, which is most cases.
+   */
+  _observe(res) {
+    if (res.status !== 429 && res.status !== 503) return res;
+    // What the server ASKED for is always honoured. What to do when it asked
+    // for nothing depends on what the cooldown costs here: a caller that
+    // REFUSES for the window loses nothing by assuming a minute, while one that
+    // WAITS it out would freeze a person's tab for a minute over a throttle
+    // that clears in seconds — so there, absence arms nothing and the caller's
+    // own retry ladder paces it instead.
+    const asked = retryAfterMs(res, this.maxCooldownMs);
+    const ms = asked ?? (this.cooldownMode === 'refuse' ? COOLDOWN_DEFAULT_MS : 0);
+    if (!ms) return res;
+    this.pausedUntil = Date.now() + ms;
+    this.log(`[${this.label}] pod returned ${res.status}${asked ? ', Retry-After' : ''} — `
+      + `holding all requests for ${Math.round(ms / 1000)}s`);
+    return res;
+  }
+
+  /** Honour an armed cooldown: fail fast, or wait it out, as configured. */
+  async _cooldownGate() {
     const left = this.pausedUntil - Date.now();
-    if (left > 0) {
-      throw new Error(`pod asked us to back off — ${Math.ceil(left / 1000)}s left of its Retry-After`);
+    if (left <= 0) return;
+    if (this.cooldownMode === 'wait') {
+      await sleep(Math.min(left, this.maxCooldownMs));
+      return;
     }
+    throw new Error(`[${this.label}] pod asked us to back off — ${Math.ceil(left / 1000)}s left of its Retry-After`);
+  }
+
+  /**
+   * The seam a subclass overrides to add transport behaviour — the browser's
+   * retry ladder lives here. Overriding THIS rather than `fetch` is deliberate:
+   * an override cannot skip the url map, the cooldown accounting or the
+   * deletion deny-list, because those are in `fetch` above it.
+   */
+  async _send(url, init) { return this.session.fetch(url, init); }
+
+  /**
+   * A deliberately CREDENTIAL-FREE request: it asks what a stranger would see,
+   * so it cannot go through the session without answering a different question.
+   * It still belongs to this pod, though — it opens a socket to it and takes
+   * one of its workers — so it observes the same cooldown and is counted.
+   *
+   * No url map: a probe asks about the ADVERTISED face, which is the whole
+   * point of asking.
+   */
+  async probe(url, init = {}) {
+    await this._cooldownGate();
     this.probeCount++;
-    const res = await fetch(url, init);
-    if (res.status === 429 || res.status === 503) {
-      const ms = retryAfterMs(res) ?? 60_000;
-      this.pausedUntil = Date.now() + ms;
-      this.log(`pod returned ${res.status} to an unauthenticated probe — pausing for ${Math.round(ms / 1000)}s`);
-    }
-    return res;
+    return this._observe(await fetch(url, init));
   }
 
+  /**
+   * Every authenticated request. Nothing below this reaches the session
+   * directly: this is the only place the cooldown is both OBSERVED and ARMED,
+   * the url map applied, and the deny-list enforced.
+   */
   async fetch(url, init) {
-    const left = this.pausedUntil - Date.now();
-    if (left > 0) {
-      throw new Error(`pod asked us to back off — ${Math.ceil(left / 1000)}s left of its Retry-After`);
-    }
-    // Fronted identity: an advertised id maps to its pod location here, so the
-    // request lands on the pod. A no-op for a pod-native id or an unfronted
-    // identity (toPod unset).
+    await this._cooldownGate();
     if (this.toPod) url = this.toPod(url);
-    const res = await this.session.fetch(url, init);
-    if (res.status === 429 || res.status === 503) {
-      const ms = retryAfterMs(res) ?? 60_000;   // no header: our own cooldown
-      this.pausedUntil = Date.now() + ms;
-      this.log(`pod returned ${res.status} — pausing all requests for ${Math.round(ms / 1000)}s`);
+    if (String(init?.method || '').toUpperCase() === 'DELETE') this._guardDelete(url);
+    return this._observe(await this._send(url, init));
+  }
+
+  /** Both refusals a DELETE must pass, wherever it was issued from. */
+  _guardDelete(url) {
+    protectedFromDeletion(url);
+    // The pattern list knows the usual name for an access-control document.
+    // One the pod named itself is just as fatal to remove. Tolerating an
+    // absent map matters: this now runs for EVERY delete, including one issued
+    // through `fetch` by a caller holding a minimally-built transport.
+    for (const acl of this.aclUrls?.values() ?? []) {
+      if (acl === url) throw new Error(`refusing to DELETE an access-control document: ${url}`);
     }
-    return res;
   }
 
-  // Everything below goes through this.fetch, never session.fetch directly:
-  // that is the only place the Retry-After cooldown is both OBSERVED and ARMED.
-  // Writing straight to the session meant a pod could answer 429 to every PUT
-  // and DELETE we sent without any of them ever being recorded as a refusal,
-  // and meant a cooldown armed by a read did not stop a publish burst.
   async put(url, body, contentType) {
     const res = await this.fetch(url, {
       method: 'PUT', headers: { 'content-type': contentType }, body,
     });
-    if (res.status >= 400) throw new Error(`PUT ${url} → ${res.status}`);
+    if (res.status >= 400) throw new Error(`[${this.label}] PUT ${url} → ${res.status}`);
     // Writing a document is usually the step before setting its access, and
     // the answer to the write already says where that lives. Taking it here
     // spares the extra request the ACL write would otherwise make.
@@ -171,6 +230,26 @@ export class RemotePod {
     return res;
   }
 
+  async putJson(url, obj, contentType = 'application/activity+json') {
+    return this.put(url, JSON.stringify(obj), contentType);
+  }
+
+  // A read that FAILED is not a document that is ABSENT. Returning null for
+  // both let a 429 read as "no replies yet", and the caller then rewrote the
+  // collection from empty — erasing every reply already recorded. Only a real
+  // 404/410 is absence; anything else throws and the caller retries later.
+  async getJson(url) {
+    const res = await this.fetch(url, { headers: { accept: '*/*' } });
+    if (res.status === 404 || res.status === 410) return null;
+    if (res.status >= 400) throw new Error(`[${this.label}] GET ${url} → ${res.status}`);
+    return res.json().catch(() => null);
+  }
+
+  async delete(url) {
+    const res = await this.fetch(url, { method: 'DELETE' });
+    return res.status < 400 || res.status === 404;
+  }
+
   /** Remember an access-control location the pod volunteered on a response. */
   noteAclLink(url, res) {
     if (this.aclUrls.has(url)) return;
@@ -213,7 +292,7 @@ export class RemotePod {
           || st.object.value.startsWith(ACP_NS));
         if (acp) {
           this.aclFlavour = false;
-          this.log('this pod states access as ACP policies, which this agent does not write — '
+          this.log(`[${this.label}] this pod states access as ACP policies, which this library does not write — `
             + 'its access rules are left exactly as they are, and nothing here is published private');
         }
       }
@@ -221,36 +300,51 @@ export class RemotePod {
     return this.aclFlavour;
   }
 
-  async putJson(url, obj, contentType = 'application/activity+json') {
-    return this.put(url, JSON.stringify(obj), contentType);
-  }
-
-  // A read that FAILED is not a document that is ABSENT. Returning null for
-  // both let a 429 read as "no replies yet", and the caller then rewrote the
-  // collection from empty — erasing every reply already recorded. Only a real
-  // 404/410 is absence; anything else throws and the caller retries later.
-  async getJson(url) {
-    const res = await this.fetch(url, { headers: { accept: '*/*' } });
-    if (res.status === 404 || res.status === 410) return null;
-    if (res.status >= 400) throw new Error(`GET ${url} → ${res.status}`);
-    return res.json().catch(() => null);
+  // WAC doc granting the public `publicModes` on target, owner full control.
+  // An empty publicModes list yields an owner-only document.
+  //
+  // Built and serialised by rdflib, like every other document written here.
+  // This is the highest-consequence RDF in the project: an ACL that comes out
+  // malformed, or naming the wrong subject, either locks the owner out or
+  // leaves the private trees world-readable. $rdf.sym() also throws on an
+  // illegal IRI, so a pod URL with something odd in it fails here rather than
+  // silently producing a document that means something else.
+  aclDoc(targetUrl, publicModes, { appendAgents = [], aclUrl = null } = {}) {
+    const url = aclUrl || targetUrl + '.acl';
+    const doc = $rdf.sym(url);
+    const target = $rdf.sym(targetUrl);
+    const g = $rdf.graph();
+    const authorize = (subject, agentPred, agent, modes) => {
+      g.add(subject, RDF('type'), ACL('Authorization'), doc);
+      g.add(subject, agentPred, agent, doc);
+      g.add(subject, ACL('accessTo'), target, doc);
+      g.add(subject, ACL('default'), target, doc);
+      for (const m of modes) g.add(subject, ACL('mode'), ACL(m), doc);
+    };
+    if (publicModes.length) {
+      authorize($rdf.sym(url + '#public'), ACL('agentClass'), FOAF('Agent'), publicModes);
+    }
+    // Named agents granted Append but not public: this is how the inbox is
+    // locked to a gateway — public loses Append, the gateway's WebID keeps it.
+    appendAgents.forEach((webId, i) =>
+      authorize($rdf.sym(url + `#gw${i}`), ACL('agent'), $rdf.sym(webId), ['Append']));
+    authorize($rdf.sym(url + '#owner'), ACL('agent'), $rdf.sym(this.webId),
+      ['Read', 'Write', 'Control']);
+    return $rdf.serialize(doc, g, url, 'text/turtle');
   }
 
-  async delete(url) {
-    protectedFromDeletion(url);
-    // The pattern list above knows the usual name for an access-control
-    // document. One the pod named itself is just as fatal to remove.
-    for (const acl of this.aclUrls.values()) {
-      if (acl === url) throw new Error(`refusing to DELETE an access-control document: ${url}`);
-    }
-    const res = await this.fetch(url, { method: 'DELETE' });
-    return res.status < 400 || res.status === 404;
+  async setAcl(targetUrl, publicModes, opts = {}) {
+    const url = await this.aclUrlFor(targetUrl);
+    if (!await this.aclWritable(url)) return null;
+    return this.put(url, this.aclDoc(targetUrl, publicModes, { ...opts, aclUrl: url }), 'text/turtle');
   }
 
   // Child documents of an LDP container (URLs under it, excluding aux docs).
-  // Revalidated: the inbox is polled every two minutes and is usually
+  // Revalidated: the inbox is polled every couple of minutes and is usually
   // unchanged, so ask conditionally and let the server answer 304.
   async listContainer(url) {
+    // Lazily, not only in the constructor: a caller may hold a transport built
+    // with Object.create for a test, setting just the few fields it drives.
     this._listCache ||= new Map();
     const known = this._listCache.get(url);
     const res = await this.fetch(url, {
@@ -260,18 +354,21 @@ export class RemotePod {
     if (res.status >= 400) return [];
     // rdflib, not a regex: a container listing is RDF, and the gap between
     // "any angle-bracketed thing in the document" and "what this container
-    // actually contains" is where quiet bugs live. claude/plans/no-regex-rdf.md
+    // actually contains" is where quiet bugs live.
     //
     // CSS puts dc:modified and posix:size on every child of the same listing,
-    // so age and weight cost nothing extra — which is what lets the drain work
+    // so age and weight cost nothing extra — which is what lets a drain work
     // oldest-first and lets a backlog be measured without reading any of it.
     let body;
     try {
       body = await readCapped(res, LISTING_MAX_BYTES);
     } catch (e) {
-      this.log(`listing at ${url}: ${e.message} — using the last known listing`);
+      this.log(`[${this.label}] listing at ${url}: ${e.message} — using the last known listing`);
       return known?.children ?? [];
     }
+    // A parse failure is a real fault, not a cache hit: it propagates. The
+    // browser copy used to swallow it and hand back a stale listing, which
+    // turns a corrupt container into silently missing work.
     const g = $rdf.graph();
     $rdf.parse(body, g, url, 'text/turtle');
     const here = $rdf.sym(url);
@@ -289,65 +386,26 @@ export class RemotePod {
         modified: g.any(child, DC('modified'), null, here)?.value || null,
       });
     }
-    // Oldest first. An LDP listing is a set, so without this the drain works
-    // in whatever order the graph happened to parse — a mention from last week
+    // Oldest first. An LDP listing is a set, so without this a drain works in
+    // whatever order the graph happened to parse — a mention from last week
     // after one from today, and no way to make progress predictable.
     list.sort((a, b) => String(a.modified || '').localeCompare(String(b.modified || '')));
     this._listCache.set(url, { etag: res.headers.get('etag'), children: list });
     return list;
   }
 
-  // WAC doc granting the public `publicModes` on target, owner full control.
-  // An empty publicModes list yields an owner-only document.
-  //
-  // Built and serialised by rdflib, like every other document this project
-  // writes — see claude/plans/no-regex-rdf.md. This was the last site still
-  // assembling Turtle from template literals, and it is the highest-consequence
-  // RDF here: an ACL that comes out malformed, or naming the wrong subject,
-  // either locks the owner out or leaves the private trees world-readable.
-  // $rdf.sym() also throws on an illegal IRI, so a pod URL with something odd
-  // in it fails here rather than silently producing a document that means
-  // something else.
-  aclDoc(targetUrl, publicModes, { appendAgents = [], aclUrl = null } = {}) {
-    const url = aclUrl || targetUrl + '.acl';
-    const doc = $rdf.sym(url);
-    const target = $rdf.sym(targetUrl);
-    const g = $rdf.graph();
-    const authorize = (subject, agentPred, agent, modes) => {
-      g.add(subject, RDF('type'), ACL('Authorization'), doc);
-      g.add(subject, agentPred, agent, doc);
-      g.add(subject, ACL('accessTo'), target, doc);
-      g.add(subject, ACL('default'), target, doc);
-      for (const m of modes) g.add(subject, ACL('mode'), ACL(m), doc);
-    };
-    if (publicModes.length) {
-      authorize($rdf.sym(url + '#public'), ACL('agentClass'), FOAF('Agent'), publicModes);
-    }
-    // Named agents granted Append but not public: this is how the inbox is
-    // locked to a gateway — public loses Append, the gateway's WebID keeps it.
-    appendAgents.forEach((webId, i) =>
-      authorize($rdf.sym(url + `#gw${i}`), ACL('agent'), $rdf.sym(webId), ['Append']));
-    authorize($rdf.sym(url + '#owner'), ACL('agent'), $rdf.sym(this.webId),
-      ['Read', 'Write', 'Control']);
-    return $rdf.serialize(doc, g, url, 'text/turtle');
-  }
-
-  async setAcl(targetUrl, publicModes, opts = {}) {
-    const url = await this.aclUrlFor(targetUrl);
-    if (!await this.aclWritable(url)) return null;
-    return this.put(url, this.aclDoc(targetUrl, publicModes, { ...opts, aclUrl: url }), 'text/turtle');
-  }
-
-  // The WebID profile advertises the actor as an account:
-  //   <webId> foaf:account <actor> .
-  //   <actor> a foaf:OnlineAccount, as:Person|as:Group ; foaf:accountName "@handle@host" .
-  // Read–check–write through rdflib. Returns false when the profile already
-  // says all of it. The parsed graph must mention the WebID before anything is
-  // written back — an empty or foreign body must never become the new profile.
+  /**
+   * The WebID profile advertises the actor as an account:
+   *   <webId> foaf:account <actor> .
+   *   <actor> a foaf:OnlineAccount, as:Person|as:Group ; foaf:accountName "@handle@host" .
+   * Read–check–write through rdflib. Returns false when the profile already
+   * says all of it. The parsed graph must mention the WebID before anything is
+   * written back — an empty or foreign body must never become the new profile.
+   */
   async linkAccountInProfile({ actorUrl, accountName, kind = 'person' }) {
     const docUrl = this.webId.split('#')[0];
     const res = await this.fetch(docUrl, { headers: { accept: 'text/turtle' } });
-    if (res.status >= 400) throw new Error(`GET ${docUrl} → ${res.status}`);
+    if (res.status >= 400) throw new Error(`[${this.label}] GET ${docUrl} → ${res.status}`);
     const g = $rdf.graph();
     $rdf.parse(await res.text(), g, docUrl, 'text/turtle');
     const doc = $rdf.sym(docUrl);
@@ -370,7 +428,7 @@ export class RemotePod {
     // A patch touches these statements and nothing else. Rewriting the whole
     // profile re-serialises statements that are not ours — the OIDC issuer
     // among them — and a server is entitled to refuse a write that would.
-    const deletes = stale.map(st => [ st.subject, st.predicate, st.object ]);
+    const deletes = stale.map(st => [st.subject, st.predicate, st.object]);
     if (await this.patchDocument(docUrl, missing, deletes)) return true;
     for (const st of stale) g.remove(st);
     for (const [s, p, o] of missing) g.add(s, p, o, doc);
@@ -414,6 +472,6 @@ export class RemotePod {
     // remove is not there any more — is a real answer, and rewriting the whole
     // document over the top of it would destroy whatever changed it.
     if (res.status === 405 || res.status === 415 || res.status === 501) return false;
-    throw new Error(`PATCH ${docUrl} → ${res.status}`);
+    throw new Error(`[${this.label}] PATCH ${docUrl} → ${res.status}`);
   }
 }

package/lib/pod/urls.mjs

@@ -0,0 +1,71 @@
+// urls.mjs — where an ActivityPub actor's documents live on a Solid pod.
+//
+// Everything the actor owns nests under ONE top-level container (`root`), so
+// the pod stays tidy and one pod could host several actors under different
+// roots. WebFinger and host-meta are the exception: fediverse discovery only
+// ever looks at the host root, so they sit at the pod base.
+//
+// `root` is REQUIRED. It used to default, and the default disagreed with what
+// one of the two callers actually passed — which is the kind of bug that puts
+// an actor's state in one container and its published documents in another.
+// A library has no business having an opinion about which container an
+// application uses; the application states it.
+//
+// When `publicBase` is given — an identity whose ADVERTISED ids live somewhere
+// else, e.g. "https://front.example/u/me/" — the ids a remote server sees build
+// on that instead, while the pod-side trees and every write target stay on the
+// pod. `toPod`/`toPublic` map between the two spaces, and a transport applies
+// `toPod` at its one request choke point, so callers keep passing advertised
+// ids and the writes still land on the pod. With no `publicBase` the returned
+// object is byte-identical to the unfronted form — an invariant worth keeping,
+// because it is what lets the fronted case be tested against the plain one.
+
+export function apUrls(remotePod, root, { publicBase = null } = {}) {
+  if (!root) throw new Error('apUrls: a container root is required — the caller states it, this library does not guess');
+  const base = remotePod.endsWith('/') ? remotePod : remotePod + '/';
+  const home = base + (root.endsWith('/') ? root : root + '/');
+  // The face a remote sees: the fronted home, or the pod home when unfronted.
+  const face = publicBase ? (publicBase.endsWith('/') ? publicBase : publicBase + '/') : home;
+  const urls = {
+    base, home,
+    webfinger: base + '.well-known/webfinger',
+    actor: face + 'ap/actor',
+    inbox: face + 'ap/inbox/',
+    outbox: face + 'ap/outbox',
+    followers: face + 'ap/followers',
+    following: face + 'ap/following',
+    notes: face + 'ap/notes/',
+    privateNotes: face + 'ap/private/',
+    featured: face + 'ap/featured',
+    // FEP-1b12: the moderator roster a recipient validates announced
+    // moderation against. Published only when moderators are configured.
+    moderators: face + 'ap/moderators',
+    // FEP-4ccd and FEP-c648: follows in limbo and the block list, as
+    // collections. They live in the private container so the owner-only ACL
+    // is inherited, not re-stated per document.
+    pendingFollowers: face + 'ap/private/pending-followers',
+    pendingFollowing: face + 'ap/private/pending-following',
+    blocked: face + 'ap/private/blocked',
+    profileHtml: face + 'ap/profile.html',
+    // Media stays on the pod even when fronted: attachment urls are not
+    // identity-checked by remotes, and proxying blobs would be pure cost.
+    media: home + 'ap/media/',
+    state: home + 'ap-state/',
+  };
+  if (publicBase) {
+    urls.podHome = home;
+    urls.publicHome = face;
+    urls.toPod = (u) => (typeof u === 'string' && u.startsWith(face) ? home + u.slice(face.length) : u);
+    urls.toPublic = (u) => (typeof u === 'string' && u.startsWith(home) ? face + u.slice(home.length) : u);
+  }
+  return urls;
+}
+
+// The host a handle would resolve through, or null when no handle can point
+// here. @name@host is looked up at https://host/.well-known/webfinger, so only
+// a pod that owns the root of its host can answer for one; a pod living at
+// https://server/name/ may publish the document but nothing will ever ask.
+export function webfingerHost(podUrl) {
+  const u = new URL(podUrl);
+  return u.pathname === '/' ? u.host : null;
+}