fedipod-server 0.10.0 → 0.12.1

package/lib/{front-core.mjs → gateway/front-core.mjs}

@@ -17,8 +17,9 @@
 
 import crypto from 'node:crypto';
 import { handleDelivery } from './gateway-core.mjs';
-import { readCapped } from './safefetch.mjs';
-import { linkTargets, REL } from './links.mjs';
+import { readCapped, safeFetch, isLoopbackHost } from '../shared/safefetch.mjs';
+import * as podRoot from '../pod/root.mjs';
+import * as podPolicy from '../pod/policy.mjs';
 
 // The one WebFinger document, spelled out here rather than imported from
 // wire.mjs: wire drags the agent's whole HTML pipeline (sanitize-html and
@@ -58,25 +59,122 @@ const OWNER_LOOKUP_MS = 5_000;
  * authority on that, so when it answers, its answer decides. A server that
  * says nothing leaves where the WebID lives as the only evidence there is.
  */
-async function podOwners(podBase, fetchImpl = fetch) {
-  try {
-    const res = await fetchImpl(podBase, {
-      method: 'HEAD', signal: AbortSignal.timeout(OWNER_LOOKUP_MS),
-    });
-    return linkTargets(res?.headers?.get?.('link'), REL.owner, podBase);
-  } catch { return []; }
-}
+const podOwners = (podBase, fetchImpl = fetch) =>
+  podRoot.readOwnerLinks(fetchImpl, podBase, { timeoutMs: OWNER_LOOKUP_MS });
 
+// Whether a token's WebID vouches for this pod, on the evidence of where it
+// lives. Weak on purpose, and never used alone any more — see provesPod.
 function webidUnderPod(webid, podHome) {
   try { return new URL(webid).origin === new URL(podHome).origin; } catch { return false; }
 }
 
+/**
+ * Whether this WebID may speak for this pod.
+ *
+ * Sharing an origin was the whole test, which is right where an origin is one
+ * person (a subdomain pod) and wrong where it is not. On a path-based server
+ * every account is on the same origin, so any account holder could attach
+ * somebody else's pod under a name of their choosing — and, worse, re-attach a
+ * name that already existed and be handed its receipt secret (S7).
+ *
+ * The pod server is the authority on who owns the pod, and it will say so in a
+ * `solid:owner` link if asked. When it answers, its answer decides. Only when
+ * it says nothing does this fall back to where the WebID lives, which is the
+ * best a silent server leaves available. This is the rule /api/agent's opt-in
+ * has used all along; attach simply never asked.
+ */
+async function provesPod(webid, podHome, fetchImpl) {
+  const owners = await podOwners(podHome, fetchImpl || fetch);
+  if (owners.length) return owners.includes(webid);
+  return webidUnderPod(webid, podHome);
+}
+
+// A pod this front will read from at all.
+//
+// The front reads `rec.podHome + <the rest of the request path>` and, on the
+// CSS server component, that read goes straight into the resource store with
+// no access control of its own — so a row whose podHome names the FRONT is a
+// row that can read the server's own internals, `/.internal/fedipod/directory/`
+// included, where every user's receipt secret is kept (S2). The front is not a
+// pod and never was one; saying so outright is the fix, and it closes the
+// self-recursion of S8 with the same line.
+function podHomeProblem(podHome, frontOrigin) {
+  let u;
+  try { u = new URL(podHome); } catch { return 'podHome is not a URL'; }
+  if (frontOrigin) {
+    try {
+      if (u.origin === new URL(frontOrigin).origin) {
+        return 'a pod cannot live on this gateway — name the pod that holds your data';
+      }
+    } catch { /* no usable frontOrigin: the other checks still apply */ }
+  }
+  // Nothing may reach a server's private trees, whatever origin they are on.
+  if (/(^|\/)\.internal(\/|$)/u.test(u.pathname) || /(^|\/)\.\.(\/|$)/u.test(u.pathname)) {
+    return 'that is not a pod address';
+  }
+  return null;
+}
+
+const RELAY_MAX_REQUESTS = 20;
+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;
+
+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, 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, status: 0, error: e.message }; }
+}
+
 const j = (status, obj, ct = 'application/json') =>
   ({ status, headers: { 'content-type': ct, 'cache-control': 'no-store' }, body: JSON.stringify(obj) });
 const notFound = () => ({ status: 404, headers: { 'content-type': 'text/plain' }, body: 'not found\n' });
 
 // A user's public base on the front, a 1:1 mirror of their pod home.
-export const userBase = (frontOrigin, handle) => `${frontOrigin}/u/${handle}/`;
+// The directory key is the FULL fediverse address — handle@host — never the
+// bare handle, which is not unique: two different pods can each have a "me".
+// A fronted identity answers at this front's host; a mail-door identity at its
+// own pod's host. The `/u/` path segment carries that same key.
+export const addressKey = (handle, host) => `${handle}@${host}`;
+export const userBase = (frontOrigin, key) => `${frontOrigin}/u/${encodeURIComponent(key)}/`;
 
 // Rewrite every occurrence of the pod home to the front base (or back). The
 // bodies are JSON, so a whole-string swap rewrites ids wherever they appear —
@@ -90,7 +188,7 @@ function parseUserPath(pathname) {
 }
 
 // Top-level paths a handle may not take, so a name never shadows a route.
-const RESERVED = new Set(['u', 'api', 'signup', 'new-account', 'run', 'admin', 'gateway',
+const RESERVED = new Set(['u', 'api', 'signup', 'new-account', 'run', 'admin', 'roster', 'gateway',
   'gw', 'well-known', 'inbox', 'outbox', 'actor', 'install']);
 
 // Why a handle is unusable, or null when it is fine. Lowercase letters, digits
@@ -114,19 +212,12 @@ function handleProblem(h) {
 const POLICY_TTL_MS = 5 * 60_000;
 const policyCache = new Map();              // podHome -> { at, policy }
 
-async function policyFor(rec, fetchImpl = fetch) {
-  const key = rec.podHome;
-  const hit = policyCache.get(key);
-  if (hit && Date.now() - hit.at < POLICY_TTL_MS) return hit.policy;
-  let policy = null;
-  try {
-    const res = await fetchImpl(rec.podHome + 'ap/gateway-policy.json',
-      { headers: { accept: 'application/json' } });
-    if (res && res.status < 400) policy = JSON.parse(await readCapped(res, 256 * 1024));
-  } catch { /* unpublished or unreachable: the row's own fields stand */ }
-  policyCache.set(key, { at: Date.now(), policy });
-  return policy;
-}
+// The cache is OURS, not the library's: on a warm serverless container one Map
+// is shared across every user this front serves, so what it is keyed by is a
+// correctness property. Keyed by podHome, it is one person's policy under one
+// person's key.
+const policyFor = (rec, fetchImpl = fetch) =>
+  podPolicy.read(fetchImpl, rec.podHome, { cache: policyCache, ttlMs: POLICY_TTL_MS });
 
 // The verified-delivery identity for a directory record: what gateway-core
 // needs to check what concerns the user and to append to their pod inbox.
@@ -152,8 +243,61 @@ function identFor(rec, policy = null) {
 //   listDirectory() -> { handle: record }  every row, for the admin roster
 //   removeDirectory(handle) -> boolean     drop a row; false when a seeded row remains
 //   podPut(url, body, ct) -> boolean      append to a user's pod (per-user cred inside)
-//   podGet(url) -> Response                read a user's pod (public reads; plain fetch is fine)
+//   podGet(url, { podHome }) -> Response   read a user's pod (public reads; plain fetch
+//                                          is fine). `podHome` is the row's own pod, for
+//                                          an adapter that reads a store directly and so
+//                                          must confine the read itself.
 export async function routeFront(request, ctx) {
+  const out = await route(request, ctx);
+  return { ...out, headers: withSecurityHeaders(out.headers, out.body) };
+}
+
+// Every response this file makes, hardened in one place rather than in each of
+// the dozen shapes below.
+//
+// `nosniff` matters most: the front serves user-supplied JSON straight from
+// somebody's pod (the proxied actor and object documents), and without it a
+// browser is free to decide for itself that a document is HTML and run what is
+// inside it. The rest is the same posture the app already has — nothing may be
+// framed, no base tag may be rewritten, no plugin content.
+//
+// A content-security-policy goes on the HTML only: it would mean nothing on a
+// JSON document, and `frame-ancestors` has to be a header rather than a meta
+// tag anyway.
+//
+// `script-src 'self'` is the one that matters, and it is only possible because
+// none of these pages carries inline script any more — each has its own file and
+// its own route above. A policy cannot tell an inline block the author wrote
+// from one an attacker injected, so as long as any inline script has to run,
+// every inline script may.
+//
+// `connect-src` allows https: because the pages sign in against the user's own
+// pod, which is a different origin by definition and not one we can name here.
+function withSecurityHeaders(headers = {}, body = null) {
+  const ct = String(headers['content-type'] || '');
+  const isHtml = ct.startsWith('text/html');
+  return {
+    ...headers,
+    'x-content-type-options': 'nosniff',
+    'referrer-policy': 'same-origin',
+    'x-frame-options': 'SAMEORIGIN',
+    ...(isHtml && body ? {
+      'content-security-policy': [
+        "default-src 'self'",
+        "script-src 'self'",             // no inline script: see above
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' https: data:",
+        "connect-src 'self' https:",     // sign-in goes to the user's own pod
+        "object-src 'none'",             // no plugin content, ever
+        "base-uri 'none'",               // no rewriting where relative URLs resolve
+        "frame-ancestors 'self'",        // nobody else may frame these pages
+        "form-action 'self'",            // a form here submits here
+      ].join('; '),
+    } : {}),
+  };
+}
+
+async function route(request, ctx) {
   const url = new URL(request.url);
   const { pathname } = url;
 
@@ -176,9 +320,10 @@ export async function routeFront(request, ctx) {
     return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: ctx.runPage };
   }
 
-  // The admin page: the host reading who has accounts here. The page signs in
+  // The roster page: the host reading who has accounts here. The page signs in
   // and calls the roster API below; a deploy with no admin supplies no page.
-  if (pathname === '/admin') {
+  // Off /admin, which is the owner's own record page on every agent.
+  if (pathname === '/roster') {
     if (request.method !== 'GET' && request.method !== 'HEAD') return { status: 405, headers: {}, body: '' };
     if (!ctx.adminPage) return notFound();
     return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: ctx.adminPage };
@@ -197,9 +342,9 @@ export async function routeFront(request, ctx) {
       .map((r) => ({
         handle: r.handle, kind: r.kind || 'person', fronted: !r.inboxOnly,
         podHome: r.podHome, webId: r.webId || null, actorUrl: r.actorUrl,
-        address: `@${r.handle}@${ctx.host}`,
+        address: r.address || `@${r.handle}@${ctx.host}`,
       }))
-      .sort((a, b) => a.handle.localeCompare(b.handle));
+      .sort((a, b) => (a.address || a.handle).localeCompare(b.address || b.handle));
     return j(200, { host: ctx.host, accounts });
   }
 
@@ -213,11 +358,13 @@ export async function routeFront(request, ctx) {
     if (webid !== ctx.adminWebId) return j(403, { error: 'that WebID is not the admin of this front' });
     let body;
     try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
-    const handle = String(body.handle || '').toLowerCase();
-    if (!(await ctx.lookup(handle))) return j(404, { error: 'no such account' });
-    const removed = (await ctx.removeDirectory(handle)) === true;
-    return j(200, removed ? { handle, removed }
-      : { handle, removed: false,
+    // Revoke by full address (what the roster lists); a bare handle still works
+    // for any legacy row keyed that way.
+    const key = String(body.address || body.handle || '').replace(/^@/, '').toLowerCase();
+    if (!key || !(await ctx.lookup(key))) return j(404, { error: 'no such account' });
+    const removed = (await ctx.removeDirectory(key)) === true;
+    return j(200, removed ? { account: key, removed }
+      : { account: key, removed: false,
           reason: 'this row is seeded in the deploy environment (FEDIPOD_DIRECTORY_JSON) — remove it there and redeploy' });
   }
 
@@ -247,38 +394,94 @@ export async function routeFront(request, ctx) {
     const podHome = String(body.podHome || '');
     const problem = handleProblem(handle);
     if (problem) return j(400, { error: problem });
-    if (!/^https:\/\/\S+\/$/.test(podHome)) return j(400, { error: 'podHome must be an https URL ending in /' });
-    if (await ctx.lookup(handle)) return j(409, { error: 'that name is taken' });
+    const podLoopback = (() => { try { return isLoopbackHost(new URL(podHome).hostname); } catch { return false; } })();
+    if (!(/^https:\/\/\S+\/$/.test(podHome) || (/^http:\/\/\S+\/$/.test(podHome) && podLoopback))) {
+      return j(400, { error: 'podHome must be an https URL ending in /' });
+    }
+    const badPod = podHomeProblem(podHome, ctx.frontOrigin);
+    if (badPod) return j(400, { error: badPod });
     const webid = await verifyPodToken(request, pathname, ctx.verifier);
     if (!webid) return j(401, { error: 'a Solid-OIDC token proving the pod is required' });
-    if (!webidUnderPod(webid, podHome)) {
+    if (!await provesPod(webid, podHome, ctx.fetchImpl)) {
       return j(403, { error: 'the token proves a different pod than the one you listed' });
     }
     // The usual attachment keeps the user's identity on their pod and moves
     // only the mail door here (@me@mypod). Fronted identity — actor ids on
     // this domain — remains available to an explicit `fronted: true`.
     const fronted = body.fronted === true;
-    const actorUrl = fronted ? `${ctx.frontOrigin}/u/${handle}/ap/actor` : podHome + 'ap/actor';
-    const hmacSecret = crypto.randomBytes(32).toString('base64');
+    // The full address is the key: a fronted name answers at this front's host,
+    // a mail-door name at its pod's host. The same handle on two pods is two
+    // distinct addresses, so it never collides.
+    let addressHost; try { addressHost = fronted ? ctx.host : new URL(podHome).host; } catch { return j(400, { error: 'bad podHome' }); }
+    // A fronted name answers at this front's host, where the handle alone is the
+    // whole address and is unique — so it keeps keying by bare handle (and its
+    // actor id stays /u/<handle>/, unchanged for existing accounts). A mail-door
+    // name answers at its own pod, where "me" is not unique, so it keys by the
+    // full address handle@podhost, which the /u/ segment then carries.
+    const key = fronted ? handle : addressKey(handle, addressHost);
+    const address = `@${handle}@${addressHost}`;
+    // "Taken" only when this exact address already belongs to a DIFFERENT pod.
+    // Re-attaching your own pod — a retry, a re-provision, a second browser — is
+    // idempotent: it updates the row in place and keeps the same door secret.
+    const prior = await ctx.lookup(key);
+    if (prior && prior.podHome !== podHome) return j(409, { error: 'that name is taken' });
+    // Re-attaching is idempotent — a retry, a re-provision, a second browser —
+    // and it hands back the EXISTING receipt secret. So it has to be the same
+    // person: matching podHome was enough on a subdomain server and, on a
+    // path-based one, meant any co-tenant could re-attach your row, flip its
+    // kind, and be given your secret (S7). A row that predates `webId` has
+    // nothing to compare and falls back to the pod check above.
+    if (prior?.webId && prior.webId !== webid) {
+      return j(409, { error: 'that name belongs to a different account on this pod' });
+    }
+    // The pod's actor lives under its AP root container, which the pod owner
+    // knows and the front does not — so take the caller's actorUrl when it is on
+    // this pod, and fall back only when none is given.
+    const claimedActor = typeof body.actorUrl === 'string' && body.actorUrl.startsWith(podHome) ? body.actorUrl : null;
+    const actorUrl = fronted ? `${userBase(ctx.frontOrigin, key)}ap/actor` : (claimedActor || podHome + 'ap/actor');
+    const hmacSecret = prior?.hmacSecret || crypto.randomBytes(32).toString('base64');
     const record = {
-      handle, podHome, webId: webid, actorUrl,
+      handle, address, podHome, webId: webid, actorUrl,
       kind: body.kind === 'group' ? 'group' : 'person',
       gatewayWebId: ctx.gatewayWebId || null, hmacSecret,
       ...(fronted ? {} : { inboxOnly: true }),
     };
-    await ctx.putDirectory(handle, record);
+    await ctx.putDirectory(key, record);
     // The secret is returned ONCE, with the one command the user runs to
     // point their agent at this gateway.
-    const doorInbox = `${ctx.frontOrigin}/u/${handle}/ap/inbox/`;
+    const doorInbox = `${userBase(ctx.frontOrigin, key)}ap/inbox/`;
     if (fronted) {
-      return j(201, { ok: true, handle, actorUrl, frontActor: actorUrl, hmacSecret,
-        address: `@${handle}@${ctx.host}`,
+      return j(201, { ok: true, handle, address, actorUrl, frontActor: actorUrl, hmacSecret,
         command: `fedipod gateway ${actorUrl} --secret ${hmacSecret}` });
     }
-    return j(201, { ok: true, handle, doorInbox, hmacSecret,
+    return j(201, { ok: true, handle, address, doorInbox, hmacSecret,
       command: `fedipod gateway ${doorInbox} --secret ${hmacSecret} --inbox-only` });
   }
 
+  // The relay: the front sends requests a browser has already signed. A page
+  // may not set the Date or Host header, and both are inside an HTTP
+  // signature, so a browser-run agent signs and hands the request here; the
+  // front sends it with exactly the headers that were signed. It can forward
+  // a signature and cannot make one. Only the account's own key may sign,
+  // only the account's own pod may call, and nothing unsigned-for reaches
+  // the remote server.
+  if (pathname === '/api/relay' && request.method === 'POST') {
+    let body;
+    try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
+    const handle = String(body.handle || '').toLowerCase();
+    const rec = await ctx.lookup(handle);
+    if (!rec) return j(404, { error: 'no such account' });
+    const webid = await verifyPodToken(request, pathname, ctx.verifier);
+    if (!webid) return 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 j(403, { error: "the token proves a different pod than this account's" });
+    const items = Array.isArray(body.requests) ? body.requests : [];
+    if (!items.length) return j(400, { error: 'requests must be a non-empty list' });
+    if (items.length > RELAY_MAX_REQUESTS) return j(400, { error: `at most ${RELAY_MAX_REQUESTS} requests per call` });
+    const results = await Promise.all(items.map((it) => relayOne(it, rec, ctx.fetchImpl || fetch)));
+    return j(200, { results });
+  }
+
   // Runtime opt-in: a pod owner asks the server this front sits on to RUN
   // their identity. Same proof as attach — a Solid-OIDC token — but the
   // ownership check is stricter: the WebID must live UNDER the pod base, not
@@ -327,6 +530,20 @@ export async function routeFront(request, ctx) {
     return j(400, { error: 'action must be opt-in or opt-out' });
   }
 
+  // Each page's own script. They were inline until 2026-09-09; out here the
+  // pages can be served under `script-src 'self'`, which is the directive that
+  // tells running code from injected markup — and inline script defeats it by
+  // construction. Same mechanism the vendored library below has always used.
+  //
+  // The name is matched against a literal list, so nothing about the request
+  // chooses a file.
+  const mPageScript = /^\/(new-account|run|admin)\.js$/u.exec(pathname);
+  if (mPageScript) {
+    const body = ctx.pageScripts?.[`${mPageScript[1]}.js`];
+    if (!body) return notFound();
+    return { status: 200, headers: { 'content-type': 'text/javascript; charset=utf-8' }, body };
+  }
+
   // The vendored Solid-OIDC browser library the /run and /admin pages load —
   // served here because this function owns every path on the domain.
   if (pathname === '/solid-oidc-client.js') {
@@ -373,9 +590,15 @@ export async function routeFront(request, ctx) {
   // fixed to the front so a consumer cross-checks it consistently.
   if (request.method !== 'GET' && request.method !== 'HEAD') return { status: 405, headers: {}, body: '' };
   const podTarget = rec.podHome + up.rest;
-  const res = await (ctx.podGet ? ctx.podGet(podTarget) : fetch(podTarget, { headers: { accept: AP_CT } }));
-  if (!res || res.status >= 400) return { status: res?.status || 502, headers: {}, body: '' };
-  let text = await readCapped(res, 1024 * 1024);
+  // The pod this read belongs to travels with it: an adapter reading a store
+  // directly (the CSS server component) has no access control of its own and
+  // needs to be told what it may reach. See podHomeProblem above for the other
+  // half — a row that names something which is not a pod.
+  const got = await podRoot.readPublicDocument(
+    ctx.podGet || ((u) => fetch(u, { headers: { accept: AP_CT } })),
+    podTarget, { podHome: rec.podHome });
+  if (got.text === null) return { status: got.status, headers: {}, body: '' };
+  let text = got.text;
   text = swap(text, rec.podHome, base);
   if (up.rest === 'ap/actor') {
     try {

package/lib/{gateway-core.mjs → gateway/gateway-core.mjs}

@@ -14,6 +14,7 @@
 
 import crypto from 'node:crypto';
 import { verifyHttpSignature, makeSafeLoader, makeReceipt, signReceipt } from './httpsig.mjs';
+import * as inbox from '../pod/inbox.mjs';
 
 const DEFAULT_MAX_BYTES = 512 * 1024;   // mirror intake.mjs MAX_ITEM_BYTES
 
@@ -100,17 +101,12 @@ export async function handleDelivery(request, ident, { podPut, fetchImpl = fetch
     ? signReceipt(makeReceipt(v, { gateway: ident.gatewayWebId }), ident.hmacSecret)
     : null;
   const hash = sha256hex(raw);
-  const okA = await podPut(ident.inboxUrl + hash, raw, 'application/activity+json');
+  const okA = await inbox.appendVerifiedDelivery(podPut, ident.inboxUrl, hash, raw);
   // A pod-write failure returns 5xx so the ORIGIN retries over its own ladder —
   // that is what preserves the pod's buffer property without the gateway
   // holding any state.
   if (!okA) return { status: 502, reason: 'pod inbox write failed' };
-  // The receipt is best-effort, like _archive: a delivery that landed but whose
-  // receipt did not is simply unverified, never lost.
-  if (receipt) {
-    await podPut(ident.inboxUrl + hash + '.receipt.json', JSON.stringify(receipt), 'application/json')
-      .catch(() => {});
-  }
+  if (receipt) await inbox.writeReceiptBeside(podPut, ident.inboxUrl, hash, receipt);
   return { status: 202, reason: v.verified ? 'verified' : 'buffered-unverified' };
 }
 

package/lib/{httpsig.mjs → gateway/httpsig.mjs}

@@ -11,7 +11,7 @@
 
 import crypto from 'node:crypto';
 import { verifyRequestDetailed } from '@fedify/fedify/sig';
-import { assertPublicUrl, safeFetch, readCapped } from './safefetch.mjs';
+import { assertPublicUrl, safeFetch, readCapped } from '../shared/safefetch.mjs';
 
 // An SSRF-safe JSON-LD document loader for Fedify's key fetch. The keyId in a
 // delivery is chosen by the sender, so every deref it triggers is untrusted
@@ -89,7 +89,33 @@ export async function verifyHttpSignature(request, { documentLoader, keyCache, t
 // even while the inbox is still public-Append (a forger without the secret
 // cannot mint `verified: true`). The HMAC is over the receipt minus the hmac
 // field itself, with sorted keys so gateway and drain canonicalize alike.
+//
+// JSON.stringify's replacer ARRAY applies at EVERY level, not just the top: the
+// old canonical() passed the top-level key names, so `checks` — whose own keys
+// are `signature`, `digest`, `dateSkew`, `keyFetched` — serialized as `{}` and
+// was covered by no signature at all. Anything nested was equally unstamped.
+// Sort recursively instead, and exclude `hmac` only where it actually lives.
+function sortedKeys(v) {
+  if (Array.isArray(v)) return v.map(sortedKeys);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = sortedKeys(v[k]);
+    return out;
+  }
+  return v;
+}
 function canonical(obj) {
+  const { hmac, ...rest } = obj;       // eslint-disable-line no-unused-vars
+  return JSON.stringify(sortedKeys(rest));
+}
+
+// What canonical() used to produce. Kept ONLY for verification, and only until
+// every door has been redeployed: a gateway (fedipod.net) and an agent update
+// independently, so for a while a receipt signed by an old door has to keep
+// verifying against a new drain. Receipts are short-lived — one per inbox item,
+// deleted with the item — so this can go once the doors have turned over.
+// Nothing signs with it.
+function canonicalLegacy(obj) {
   return JSON.stringify(obj, Object.keys(obj).filter(k => k !== 'hmac').sort());
 }
 
@@ -117,8 +143,13 @@ export function signReceipt(receipt, secret) {
 // over equal-length buffers; unequal lengths are a straight mismatch.
 export function verifyReceipt(receipt, secret) {
   if (!receipt || typeof receipt !== 'object' || !receipt.hmac || !secret) return false;
-  const expected = crypto.createHmac('sha256', secret).update(canonical(receipt)).digest();
   let given;
   try { given = Buffer.from(receipt.hmac, 'base64'); } catch { return false; }
-  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
+  const matches = (text) => {
+    const expected = crypto.createHmac('sha256', secret).update(text).digest();
+    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
+  };
+  // The current stamp first; the pre-2026-09-09 one second, for receipts a door
+  // that has not been redeployed yet is still writing. See canonicalLegacy.
+  return matches(canonical(receipt)) || matches(canonicalLegacy(receipt));
 }

package/lib/pod/README.md

@@ -0,0 +1,61 @@
+# 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.