fedipod-server 0.4.0 → 0.6.0

package/README.md

@@ -12,7 +12,7 @@ made, and opting out is the only way one ends.
 With nothing configured beyond the defaults, installing the component changes
 nothing about how the server serves pods.
 
-![FediPod as a component of a Solid server](fedipod-server.svg)
+![A pod and its agent, both inside one Solid server](fedipod-server.svg)
 
 ## Install
 
@@ -189,6 +189,8 @@ npm run test:e2e    # boots a real server and uses it as a client would
 container listings — through the transport an identity uses, and checks the
 lease protocol and the deletion deny-list still hold across it.
 
+`npm test` is also what a publish runs, so a red suite blocks one.
+
 `npm run test:e2e` starts a real Community Solid Server with three pods (two
 become identities up front; the third opts in and out at runtime), then signs in as a phone app does, posts,
 receives a follow from another server, and watches the live feed. It takes

package/fedipod-server.svg

@@ -1,134 +1,82 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1620 1140" width="1620" height="1140" font-family="system-ui, sans-serif" role="img" aria-labelledby="ttl dsc">
-<title id="ttl">FediPod Server, a Community Solid Server component</title>
-<desc id="dsc">One Community Solid Server hosting many pods, with the FediPod component installed, and down the right-hand side everyone who talks to it. The open social web delivers mail and looks things up: some of that reaches the component, and the rest reaches pod storage directly, because a pod's public record and its inbox are ordinary pod resources the server already serves. Mei's phone and Tamara's laptop sign in, read and post; any authorized Solid app reads and writes the pods directly, except the paths the component claims. Inside, the component is the same FediPod Agent running in the server's own process, in two parts. The endpoints it serves are, on each pod's own address, the client API an app signs in to, the owner's pages behind that owner's own secret, and the live feed; and on the shared address, the front, and the door that verifies deliveries for the handles it fronts. The work it does for each pod is accepting a follow, delivering a post, emptying the inbox, and holding the lease so only one agent at a time acts. Below, server storage holds, outside every pod, each identity's signing key and door secret, plus a handle directory and the opt-in list when the server serves other people; an identity's log goes to the server's own log. Pod storage is one pod per identity, each holding that identity's public face, its inbox and its private state, written directly with no credential and no second connection, and a pod owner opts in from there.</desc>
-<style>
-  .t    { font-size: 18px; font-weight: 600; fill: #1a1a19; }
-  .d    { font-size: 16px; fill: #333; }
-  .sub  { font-size: 15px; fill: #666; }
-  .lbl  { font-size: 15px; fill: #555; }
-  .cc   { font-size: 11px; font-weight: 400; font-style: italic; fill: #555; }
-  .arrow  { stroke: #555; stroke-width: 2; fill: none; marker-end: url(#arr); }
-  .arrow2 { stroke: #555; stroke-width: 2; fill: none; marker-end: url(#arr); marker-start: url(#arr); }
-</style>
-<defs>
-  <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
-    <path d="M0,0 L10,5 L0,10 z" fill="#555"/>
-  </marker>
-</defs>
-
-<rect width="1620" height="1140" fill="#ffffff"/>
-
-<!-- ===== the server ===== -->
-<rect x="40" y="40" width="1060" height="1050" rx="12" fill="#f7f6f2" stroke="#9a988f"/>
-<text class="t" x="570" y="80" text-anchor="middle">One Community Solid Server, hosting many pods, with the FediPod component installed</text>
-<text class="sub" x="570" y="104" text-anchor="middle">the pods it already served, and a fediverse identity for each user who opts in</text>
-
-<!-- ===== processing ===== -->
-<rect x="64" y="128" width="1012" height="518" rx="12" fill="#fdeeee" stroke="#b87a7a"/>
-<text class="t" x="570" y="164" text-anchor="middle">Processing — the same FediPod Agent, running inside the server</text>
-
-<text class="sub" x="88" y="196">the endpoints it serves, on each pod's own address</text>
-<rect x="88" y="206" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="106" y="234">The client API</text>
-<text class="sub" x="106" y="256">what a Mastodon app signs in to</text>
-<rect x="88" y="286" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="106" y="314">The owner's pages</text>
-<text class="sub" x="106" y="336">the record and a web client, behind their own secret</text>
-<rect x="88" y="366" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="106" y="394">The live feed</text>
-<text class="sub" x="106" y="416">a socket a client holds open</text>
-
-<text class="sub" x="88" y="464">and on the shared address</text>
-<rect x="88" y="474" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="106" y="502">The front</text>
-<text class="sub" x="106" y="524">signup, name lookups and attach</text>
-<rect x="88" y="554" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="106" y="582">The door</text>
-<text class="sub" x="106" y="604">verifies deliveries for the handles it fronts</text>
-
-<text class="sub" x="584" y="196">the work it does, for each pod it runs</text>
-<rect x="584" y="206" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="602" y="234">Accepts a follow</text>
-<text class="sub" x="602" y="256">answers as that pod's owner</text>
-<rect x="584" y="286" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="602" y="314">Delivers a post</text>
-<text class="sub" x="602" y="336">signs it and sends it on</text>
-<rect x="584" y="366" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="602" y="394">Empties the inbox</text>
-<text class="sub" x="602" y="416">reads what arrived, then clears it</text>
-<rect x="584" y="446" width="468" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="602" y="474">Holds the lease</text>
-<text class="sub" x="602" y="496">so only one agent at a time acts on a pod</text>
-
-<!-- ===== processing <-> storage ===== -->
-<path class="arrow" d="M 298 648 L 298 742"/>
-<text class="lbl" x="286" y="678" text-anchor="end">keeps each identity's</text>
-<text class="lbl" x="286" y="700" text-anchor="end">signing key and door secret</text>
-
-<path class="arrow" d="M 798 648 L 798 742"/>
-<text class="lbl" x="786" y="678" text-anchor="end">writes directly to each user's pod</text>
-<text class="lbl" x="786" y="700" text-anchor="end">no credential, no second connection</text>
-
-<path class="arrow" d="M 838 742 L 838 648"/>
-<text class="lbl" x="850" y="678">user opts in to have a</text>
-<text class="lbl" x="850" y="700">fediverse account on their pod</text>
-
-<!-- ===== server storage ===== -->
-<rect x="64" y="746" width="468" height="320" rx="12" fill="#f2ece0" stroke="#b09a5e"/>
-<text class="t" x="298" y="782" text-anchor="middle">Server storage</text>
-<text class="sub" x="298" y="806" text-anchor="middle">on the server, outside every pod</text>
-<text class="sub" x="298" y="826" text-anchor="middle">an identity's log goes to the server's own log</text>
-<rect x="88" y="852" width="420" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="106" y="880">A signing key per identity</text>
-<text class="sub" x="106" y="902">what it means to be able to post as them</text>
-<rect x="88" y="932" width="420" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="106" y="960">A door secret per identity</text>
-<text class="sub" x="106" y="982">opens that identity's pages, nobody else's</text>
-<rect x="88" y="1012" width="420" height="46" rx="10" fill="#ffffff" stroke="#c9c7bf" stroke-dasharray="4 4"/>
-<text class="sub" x="106" y="1040">a handle directory and the opt-in list, if it serves others</text>
-
-<!-- ===== pod storage ===== -->
-<rect x="584" y="746" width="468" height="320" rx="12" fill="#e7f2e7" stroke="#6a9a6a"/>
-<text class="t" x="818" y="782" text-anchor="middle">Pod storage — one pod per identity</text>
-<text class="sub" x="818" y="806" text-anchor="middle">addressable by Solid and by ActivityPub</text>
-<rect x="608" y="832" width="420" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="626" y="860">mei.example.org</text>
-<text class="sub" x="626" y="882">public face, inbox, and her agent's private state</text>
-<rect x="608" y="912" width="420" height="68" rx="10" fill="#ffffff" stroke="#c9c7bf"/>
-<text class="d" x="626" y="940">tamara.example.org</text>
-<text class="sub" x="626" y="962">the same again, hers alone</text>
-<rect x="608" y="992" width="420" height="46" rx="10" fill="#ffffff" stroke="#c9c7bf" stroke-dasharray="4 4"/>
-<text class="sub" x="626" y="1020">and every other pod this server hosts, untouched</text>
-
-<!-- ===== everyone who talks to it ===== -->
-<rect x="1160" y="170" width="340" height="104" rx="12" fill="#f0e9f5" stroke="#9a7ab0"/>
-<text class="t" x="1330" y="206" text-anchor="middle">Mei's phone</text>
-<text class="d" x="1330" y="234" text-anchor="middle">any mobile Mastodon client</text>
-<text class="d" x="1330" y="256" text-anchor="middle">signs in, reads, posts</text>
-<path class="arrow2" d="M 1158 222 L 1080 222"/>
-
-<rect x="1160" y="310" width="340" height="104" rx="12" fill="#f0e9f5" stroke="#9a7ab0"/>
-<text class="t" x="1330" y="346" text-anchor="middle">Tamara's laptop</text>
-<text class="d" x="1330" y="374" text-anchor="middle">browser or native app</text>
-<text class="d" x="1330" y="396" text-anchor="middle">signs in, reads, posts</text>
-<path class="arrow2" d="M 1158 362 L 1080 362"/>
-
-<rect x="1160" y="450" width="340" height="126" rx="12" fill="#eef1f8" stroke="#7a88b8"/>
-<text class="t" x="1330" y="486" text-anchor="middle">The open social web</text>
-<text class="d" x="1330" y="514" text-anchor="middle">Mastodon, Lemmy, PeerTube,</text>
-<text class="d" x="1330" y="536" text-anchor="middle">anyone else</text>
-<text class="d" x="1330" y="558" text-anchor="middle">delivers mail, and looks things up</text>
-<path class="arrow2" d="M 1158 513 L 1080 513"/>
-<path class="arrow2" d="M 1330 578 L 1330 906 L 1058 906"/>
-<text class="lbl" x="1348" y="734">to the pod — mail into its inbox</text>
-<text class="lbl" x="1348" y="756">from the pod — its public record</text>
-
-<rect x="1160" y="940" width="340" height="126" rx="12" fill="#f1efe8" stroke="#9a988f"/>
-<text class="t" x="1330" y="976" text-anchor="middle">Any authorized Solid app</text>
-<text class="d" x="1330" y="1004" text-anchor="middle">reads and writes the pod,</text>
-<text class="d" x="1330" y="1026" text-anchor="middle">except the paths the</text>
-<text class="d" x="1330" y="1048" text-anchor="middle">component claims</text>
-<path class="arrow2" d="M 1158 1003 L 1056 1003"/>
-
-<text class="cc" x="1580" y="1120" text-anchor="end">(cc) 4.0 By, Jeff Zucker, 2026</text>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1290 800" width="1290" height="800" font-family="system-ui, sans-serif">
+  <defs>
+    <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0,0 L10,5 L0,10 z" fill="#555"/>
+    </marker>
+  </defs>
+  <style>
+    .t   { font-size: 18px; font-weight: 600; fill: #1a1a19; }
+    .d   { font-size: 16px; fill: #333; }
+    .sub { font-size: 15px; fill: #666; }
+    .lbl { font-size: 15px; fill: #555; }
+    .cc  { font-size: 11px; font-weight: 400; font-style: italic; fill: #555; }
+    .arrow  { stroke: #555; stroke-width: 2; fill: none; marker-end: url(#arr); }
+    .arrow2 { stroke: #555; stroke-width: 2; fill: none; marker-end: url(#arr); marker-start: url(#arr); }
+  </style>
+
+  <rect width="1290" height="800" fill="#ffffff"/>
+
+  <!-- The open social web -->
+  <rect x="210" y="30" width="870" height="92" rx="12" fill="#eef1f8" stroke="#7a88b8"/>
+  <text class="t" x="645" y="64" text-anchor="middle">The open social web</text>
+  <text class="d" x="645" y="94" text-anchor="middle">other servers: deliver mail to us, read what we publish</text>
+
+  <!-- The server holding both -->
+  <rect x="180" y="200" width="930" height="301" rx="12" fill="#f7f6f2" stroke="#9a988f"/>
+  <text class="t" x="645" y="234" text-anchor="middle">FediPod Server (CSS + FediPod component)</text>
+  <text class="sub" x="645" y="258" text-anchor="middle">the pods it already served, and a fediverse identity for each user who opts in</text>
+
+  <!-- Pod -->
+  <rect x="210" y="280" width="360" height="197" rx="12" fill="#e7f2e7" stroke="#6a9a6a"/>
+  <text class="t" x="390" y="312" text-anchor="middle">Tamara's pod</text>
+  <text class="sub" x="390" y="336" text-anchor="middle">a subdomain pod on this server</text>
+  <text class="d" x="390" y="364" text-anchor="middle">stores &amp; serves her public</text>
+  <text class="d" x="390" y="386" text-anchor="middle">record in S2S AS2 format —</text>
+  <text class="d" x="390" y="408" text-anchor="middle">actor, posts, collections;</text>
+  <text class="d" x="390" y="430" text-anchor="middle">her inbox buffers mail</text>
+  <text class="d" x="390" y="452" text-anchor="middle">until her agent sweeps it</text>
+
+  <!-- Agent -->
+  <rect x="720" y="280" width="360" height="197" rx="12" fill="#fdeeee" stroke="#b87a7a"/>
+  <text class="t" x="900" y="312" text-anchor="middle">Tamara's FediPod Agent</text>
+  <text class="sub" x="900" y="336" text-anchor="middle">inside the server, no machine of her own</text>
+  <text class="d" x="900" y="364" text-anchor="middle">does the thinking:</text>
+  <text class="d" x="900" y="386" text-anchor="middle">reads the buffered mail,</text>
+  <text class="d" x="900" y="408" text-anchor="middle">accepts follows, builds her</text>
+  <text class="d" x="900" y="430" text-anchor="middle">timeline, signs &amp; delivers</text>
+  <text class="d" x="900" y="452" text-anchor="middle">everything she says</text>
+
+  <!-- Client -->
+  <rect x="720" y="560" width="360" height="136" rx="12" fill="#f0e9f5" stroke="#9a7ab0"/>
+  <text class="t" x="900" y="594" text-anchor="middle">Browser or Native App</text>
+  <text class="sub" x="900" y="618" text-anchor="middle">(Phanpy, Whalebird, …)</text>
+  <text class="d" x="900" y="646" text-anchor="middle">where she reads and posts;</text>
+  <text class="d" x="900" y="668" text-anchor="middle">signs in at her pod's address</text>
+
+  <!-- open social web -> pod: straight in, there is no door in the way -->
+  <path class="arrow" d="M 390 124 L 390 276"/>
+  <text class="lbl" x="402" y="160">deliveries in</text>
+
+  <!-- pod <-> agent -->
+  <path class="arrow2" d="M 572 378 L 718 378"/>
+  <text class="lbl" x="645" y="360" text-anchor="middle">drains mail,</text>
+  <text class="lbl" x="645" y="402" text-anchor="middle">writes the record</text>
+
+  <!-- agent <-> client -->
+  <path class="arrow2" d="M 900 479 L 900 558"/>
+  <text class="lbl" x="912" y="524">read / post</text>
+
+  <!-- pod -> open social web -->
+  <path class="arrow" d="M 208 345 L 70 345 C 45 345, 38 310, 38 260 C 38 190, 88 100, 206 100"/>
+  <text class="lbl" x="188" y="317" text-anchor="end">reads her record</text>
+
+  <!-- agent -> open social web -->
+  <path class="arrow" d="M 1082 345 L 1220 345 C 1245 345, 1252 310, 1252 250 C 1252 180, 1202 78, 1084 78"/>
+  <text class="lbl" x="1102" y="317">signed deliveries out</text>
+
+  <text class="d" x="45" y="646">A pod becomes an identity when its owner opts in, and stops when they opt out.</text>
+  <text class="d" x="45" y="670">The agent runs inside the server, so there is no second machine and nothing</text>
+  <text class="d" x="45" y="694">to authenticate between them — and the server holds her signing key.</text>
+
+  <text class="cc" x="1245" y="764" text-anchor="end">(cc) 4.0 By, Jeff Zucker, 2026</text>
 </svg>

package/lib/admin.mjs

@@ -32,6 +32,7 @@ import { portFree, freePortFrom } from './ports.mjs';
 import { claimDirectory, yieldDirectory } from './directory.mjs';
 import { localFetch } from './localapi.mjs';
 import { ensureTrustedTls } from './certs.mjs';
+import { localVersion } from './update.mjs';
 
 const require = createRequire(import.meta.url);
 const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -325,7 +326,8 @@ function sendFile(res, baseDir, rel, auth) {
 // guards the operator's door (basePath) instead of the whole surface.
 export function buildAdminSurface({ agent, gate, allowed, log = console.log,
   port = null, handle = null, embedded = false, basePath = '/',
-  publicOrigin = null, scheme = null }) {
+  publicOrigin = null, scheme = null,
+  versionOnDisk = () => localVersion(projectRoot) }) {
   const json = (res, status, obj) => sendJson(res, status, obj, allowed);
   const masto = new MastoApi({ agent, log, allowed, scheme, embedded });
   // The spec's own write API (§6), beside the facade. Its bearer fallback is
@@ -592,6 +594,10 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
           privateRoot: agent.readCredential?.()?.privateRoot || null,
           mode: agent.status?.().mode || null, port, home: tildify(agent.home) || null,
           update: agent.updateInfo || null,
+          // What this process is running, against what a restart would run:
+          // the checkout can move while an agent stays up.
+          version: AGENT_VERSION,
+          versionOnDisk: versionOnDisk(),
           pendingUpgrade: agent.pendingUpgrade || [],
           // The connected Bluesky account, non-secret half. `connected` is the
           // credential's word, so a config entry orphaned by a deleted
@@ -1423,6 +1429,16 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
           const cfg = { ...agent.store.getConfig() };
           const g = { ...(cfg.gateway || {}) };
           const inboxUrl = agent.publisher?.urls?.inbox;
+          // Availability is a read: answered before the lease takeover below,
+          // which every real gateway change does want.
+          if (body.action === 'check') {
+            const front = String(body.front || '').replace(/\/+$/, '');
+            try { new URL(front); } catch { return json(res, 400, { error: 'front must be a gateway origin URL' }); }
+            const chk = await fetch(`${front}/api/handle?handle=${encodeURIComponent(String(body.handle || '').toLowerCase())}`,
+              { headers: { accept: 'application/json' } }).then((r) => r.json()).catch(() => null);
+            if (!chk) return json(res, 502, { error: `${front} did not answer its handle check` });
+            return json(res, 200, { available: !!chk.available, reason: chk.reason || null });
+          }
           await agent.requestTakeover?.();
           const persist = async () => {
             cfg.gateway = g; agent.store.setConfig(cfg);
@@ -1478,6 +1494,56 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
             else if (target !== 'off') await agent.publisher?.publishGatewayPolicy().catch(() => {});
             return json(res, 200, { ok: true, mode: g.mode });
           }
+          // Attach through a multi-user front (fedipod.net and kin): the agent
+          // proves the pod with its own credential — no browser, no password —
+          // and the front answers with the door and the receipt secret.
+          if (body.action === 'attach') {
+            const front = String(body.front || '').replace(/\/+$/, '');
+            let fu;
+            try { fu = new URL(front); } catch { return json(res, 400, { error: 'front must be the gateway origin, like https://fedipod.net' }); }
+            if (fu.protocol !== 'https:' && !/^(localhost|127\.0\.0\.1)$|\.localhost$/.test(fu.hostname)) {
+              return json(res, 400, { error: 'front must be https' });
+            }
+            if (agent.embedded) {
+              return json(res, 400, { error: 'this identity runs inside its pod server and has no portable credential — attach from a standalone agent' });
+            }
+            const handle = String(body.handle || cfg.handle || '').toLowerCase().trim();
+            if (!handle) return json(res, 400, { error: 'a name at the gateway is required' });
+            const fronted = body.fronted === true;
+            const frontActor = `${front}/u/${handle}/ap/actor`;
+            if (g.frontActor && (!fronted || g.frontActor !== frontActor)) {
+              return json(res, 400, { error: `this identity already fronts through ${g.frontActor} — changing a published front renames every id; detach first if you mean it` });
+            }
+            // Availability first, for a clean answer before anything is created.
+            const chk = await fetch(`${front}/api/handle?handle=${encodeURIComponent(handle)}`,
+              { headers: { accept: 'application/json' } }).then((r) => r.json()).catch(() => null);
+            if (!chk) return json(res, 502, { error: `${front} did not answer its handle check` });
+            if (!chk.available) return json(res, 409, { error: chk.reason || `the name ${handle} is taken at ${front}` });
+            const attach = await agent.remote.session.fetch(`${front}/api/attach`, {
+              method: 'POST', headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ handle, podHome: agent.urls.home, kind: cfg.kind || 'person', fronted }),
+            }).catch(() => null);
+            if (!attach) return json(res, 502, { error: `${front} did not answer the attach` });
+            const d = await attach.json().catch(() => ({}));
+            if (attach.status !== 201) {
+              return json(res, attach.status >= 400 && attach.status < 500 ? attach.status : 502,
+                { error: d.error || `attach failed (HTTP ${attach.status})` });
+            }
+            g.url = String(d.doorInbox || `${front}/u/${handle}/ap/inbox/`);
+            if (d.hmacSecret) g.hmacSecret = String(d.hmacSecret);
+            if (fronted) g.frontActor = String(d.frontActor || frontActor);
+            if (!g.mode || g.mode === 'off') g.mode = 'shadow';
+            await persist();
+            // Inbox-only applies live: the actor republishes advertising the
+            // door. A front carries new ids, which are wired at startup — that
+            // attach persists and owes a restart.
+            if (!fronted) {
+              await agent.publisher?.publishProfile();
+              await agent.publisher?.publishGatewayPolicy?.().catch(() => {});
+            }
+            return json(res, 200, { ok: true, mode: g.mode, url: g.url,
+              ...(fronted ? { frontActor: g.frontActor, address: d.address || null, restart: true } : {}) });
+          }
           if (body.action === 'forget') {
             const wasLocked = g.mode === 'locked';
             delete cfg.gateway; agent.store.setConfig(cfg);
@@ -1487,7 +1553,7 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
             await agent.publisher?.publishProfile();   // re-advertise the pod inbox
             return json(res, 200, { ok: true, mode: 'off', forgotten: true });
           }
-          return json(res, 400, { error: 'action must be configure, mode or forget' });
+          return json(res, 400, { error: 'action must be configure, mode, check, attach or forget' });
         }
         // Symmetrical with /block, and open for the same reason: a block made
         // by mistake is worth undoing before federation is even configured.
@@ -1534,14 +1600,17 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
   return { handler, masto, c2s, streaming };
 }
 
-export function startAdmin({ port, gateToken, agent, log = console.log, handle = null, tls = null }) {
+export function startAdmin({ port, gateToken, agent, log = console.log, handle = null, tls = null,
+  // Injectable, so a test can put a checkout ahead of the running process
+  // without editing the package.json of the machine running the test.
+  versionOnDisk = () => localVersion(projectRoot) }) {
   const gate = makeGate(gateToken);
   // Live, so the named origin appears the moment connect() reads the handle
   // out of pod state — including for the OAuth redirect check in MastoApi.
   // The https listener's port joins the authority set: same names, second port.
   const allowed = new Authorities(port, handle);
   agent.authorities = allowed;
-  const { handler, streaming } = buildAdminSurface({ agent, gate, allowed, log, port, handle });
+  const { handler, streaming } = buildAdminSurface({ agent, gate, allowed, log, port, handle, versionOnDisk });
 
   // Loopback both ways: the canonical URL is https://localhost:<port>/, and
   // "localhost" resolves to ::1 on many systems before falling back to IPv4 —

package/lib/deliver.mjs

@@ -4,11 +4,43 @@
 // dropped after MAX_ATTEMPTS (~3 days).
 
 import { signRequest } from '@fedify/fedify/sig';
+import { webcrypto } from 'node:crypto';
+import { attachProof } from './proof.mjs';
 import { pinnedFor, retryAfterMs, HTTP_TIMEOUT_MS } from './safefetch.mjs';
 import { USER_AGENT } from './ua.mjs';
 
 const MAX_REDIRECTS = 3;
 
+// draft-cavage signs `(request-target): <method> <path><query>`. Fedify 2.3.4
+// builds that line from the pathname alone, so a signature over any URL
+// carrying a query is one a correct verifier cannot reconstruct — a paged
+// collection at `?page=2`, a WordPress inbox at `?rest_route=…`. Re-sign just
+// that line, over the header list Fedify already chose; a URL with no query
+// comes back untouched, and anything unexpected is left exactly as signed.
+export async function withQueryInTarget(signed, privateKey) {
+  const url = new URL(signed.url);
+  if (!url.search) return signed;
+  const header = signed.headers.get('signature');
+  if (!header) return signed;
+  const fields = Object.fromEntries(
+    [...header.matchAll(/([A-Za-z]+)="([^"]*)"/g)].map(m => [m[1], m[2]]));
+  const names = fields.headers?.split(/\s+/g) || [];
+  if (!fields.signature || !names.includes('(request-target)')) return signed;
+  if (names.some(n => n.startsWith('(') && n !== '(request-target)')) return signed;
+  const message = names.map(n => n === '(request-target)'
+    ? `(request-target): ${signed.method.toLowerCase()} ${url.pathname}${url.search}`
+    : `${n}: ${(n === 'host' ? signed.headers.get('host') || url.host : signed.headers.get(n)) ?? ''}`)
+    .join('\n');
+  const sig = await webcrypto.subtle.sign('RSASSA-PKCS1-v1_5', privateKey,
+    new TextEncoder().encode(message));
+  const headers = new Headers(signed.headers);
+  headers.set('signature',
+    header.replace(/signature="[^"]*"/, `signature="${Buffer.from(sig).toString('base64')}"`));
+  const init = { method: signed.method, headers, signal: signed.signal };
+  if (signed.method !== 'GET' && signed.method !== 'HEAD') init.body = await signed.arrayBuffer();
+  return new Request(signed.url, init);
+}
+
 const MAX_ATTEMPTS = 12;                       // 2^12 min ≈ 68h of backoff
 const TICK_MS = 60_000;
 const MAX_QUEUE = 2000;                        // beyond it, overflow dead-letters
@@ -25,10 +57,14 @@ export class Deliverer {
   // passive: signing-only (viewer-mode agents) — no queue drain timer, so a
   // read-only agent never mutates shared delivery state. startQueue() flips
   // it live when a viewer is promoted to active.
-  constructor({ store, keyId, rsaPrivate, log = console.log, passive = false }) {
+  constructor({ store, keyId, rsaPrivate, actorId = null, edPrivate = null, proofKeyId = null,
+    log = console.log, passive = false }) {
     this.store = store;
     this.keyId = keyId;
     this.rsaPrivate = rsaPrivate;
+    this.actorId = actorId;
+    this.edPrivate = edPrivate;
+    this.proofKeyId = proofKeyId;
     this.log = log;
     if (!passive) this.startQueue();
   }
@@ -64,7 +100,8 @@ export class Deliverer {
     for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
       const dispatcher = await pinnedFor(current);
       const req = new Request(current, withUa);
-      const signed = await signRequest(req, this.rsaPrivate, new URL(this.keyId));
+      const signed = await withQueryInTarget(
+        await signRequest(req, this.rsaPrivate, new URL(this.keyId)), this.rsaPrivate);
       const res = await fetch(signed, { ...(dispatcher ? { dispatcher } : {}), redirect: 'manual' });
       if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
         current = new URL(res.headers.get('location'), current).href;
@@ -101,20 +138,43 @@ export class Deliverer {
   }
 
   // Deliver, queueing on failure.
+  // FEP-8b32: a proof on everything WE author, so a server that meets one of
+  // our activities second-hand can verify it without asking us.
+  //
+  // Only ours. An activity we forward on someone else's behalf keeps whatever
+  // proof its author gave it — signing that one as an assertion of ours would
+  // be claiming to have written it.
+  async proofed(activity) {
+    if (!this.edPrivate || !this.proofKeyId || !activity || typeof activity !== 'object') return activity;
+    if (activity.proof) return activity;
+    const actor = typeof activity.actor === 'string' ? activity.actor : activity.actor?.id;
+    if (!this.actorId || actor !== this.actorId) return activity;
+    try {
+      return await attachProof(activity,
+        { privateKey: this.edPrivate, verificationMethod: this.proofKeyId });
+    } catch (e) {
+      this.log(`proof: ${e.message}`);      // an unproved activity still federates
+      return activity;
+    }
+  }
+
   async deliver(inbox, activity) {
+    // Proved before anything else, so the copy that goes on the queue is the
+    // copy that was signed — a retry days later must not post a bare activity.
+    const signed = await this.proofed(activity);
     // A host we already know is refusing: queue without asking again. This is
     // the path a FRESH activity takes, so without it a fan-out to a struggling
     // server opened one socket per follower before any of this applied.
     const host = hostOf(inbox);
     const until = this._cooling?.get(host);
     if (until && until > Date.now()) {
-      this.log(`${host} is cooling — queueing ${activity.type} rather than asking again`);
-      this._enqueue({ inbox, activity, attempts: 1, nextAt: until });
+      this.log(`${host} is cooling — queueing ${signed.type} rather than asking again`);
+      this._enqueue({ inbox, activity: signed, attempts: 1, nextAt: until });
       return;
     }
     try {
-      await this.deliverNow(inbox, activity);
-      this.log(`delivered ${activity.type} → ${inbox}`);
+      await this.deliverNow(inbox, signed);
+      this.log(`delivered ${signed.type} → ${inbox}`);
     } catch (e) {
       this.log(`delivery failed (${e.message}) — queued`);
       const wait = e.retryAfterMs || 60_000;
@@ -122,7 +182,7 @@ export class Deliverer {
         this._cooling ||= new Map();
         this._cooling.set(host, Date.now() + wait);
       }
-      this._enqueue({ inbox, activity, attempts: 1, nextAt: Date.now() + wait });
+      this._enqueue({ inbox, activity: signed, attempts: 1, nextAt: Date.now() + wait });
     }
   }
 
@@ -140,8 +200,11 @@ export class Deliverer {
   }
 
   async deliverToAll(inboxes, activity) {
+    // Proved once for the whole fan-out: every recipient gets the same bytes,
+    // and one signature is computed rather than one per follower.
+    const signed = await this.proofed(activity);
     // Shared inboxes deduplicate fan-out to the same server.
-    for (const inbox of [...new Set(inboxes)]) await this.deliver(inbox, activity);
+    for (const inbox of [...new Set(inboxes)]) await this.deliver(inbox, signed);
   }
 
   // Serialized, for the same reason Intake.drain is: the tick is 60s and a

package/lib/gateway-core.mjs

@@ -33,7 +33,9 @@ function httpUrl(u) {
 function isBlocked(actor, blocklist = {}) {
   if (!actor) return true;
   if ((blocklist.actors || []).includes(actor)) return true;
-  let host; try { host = new URL(actor).host; } catch { return false; }
+  // hostname, not host: the agent's own isBlocked strips the port, and a door
+  // that keeps it lets a blocked domain back in on a non-default port.
+  let host; try { host = new URL(actor).hostname; } catch { return false; }
   return (blocklist.domains || []).some(d => host === d || host.endsWith('.' + d));
 }
 
@@ -88,7 +90,7 @@ export async function handleDelivery(request, ident, { podPut, fetchImpl = fetch
   // reaches the pod (today it would, drain, and die unapplied). An absent or
   // unfetchable-key signature is NOT dropped: it forwards unverified and the
   // drain's verify-by-dereference still stands behind it.
-  if (v.verified === false && v.reason === 'bad-signature-or-key-unfetchable') {
+  if (v.verified === false && v.reason === 'bad-signature') {
     return { status: 202, reason: 'forged signature' };
   }
 

package/lib/httpsig.mjs

@@ -10,7 +10,7 @@
 // — so the key deref is injected as a loader that goes through safefetch.
 
 import crypto from 'node:crypto';
-import { verifyRequest } from '@fedify/fedify/sig';
+import { verifyRequestDetailed } from '@fedify/fedify/sig';
 import { assertPublicUrl, safeFetch, readCapped } from './safefetch.mjs';
 
 // An SSRF-safe JSON-LD document loader for Fedify's key fetch. The keyId in a
@@ -40,33 +40,48 @@ export function makeSafeLoader({ getActors = null, fetchImpl = fetch } = {}) {
 // has one natively; an agent-side endpoint builds one from its req). Returns a
 // normalized result both the gateway and the drain understand — never throws
 // on a bad signature, because "unverified" is a routine outcome, not an error.
+//
+// Three outcomes, kept apart because the door acts on them differently. Only a
+// signature we could CHECK and found wrong is a forgery. A key we could not
+// fetch proves nothing: a sender in secure mode — Threads, Mastodon with
+// AUTHORIZED_FETCH — answers this keyless loader 404 or 401, so its deliveries
+// have to degrade to unverified rather than be read as forged.
 export async function verifyHttpSignature(request, { documentLoader, keyCache, timeWindow } = {}) {
   const hadSig = request.headers.get('signature') != null;
-  let key = null;
+  let result = null;
   try {
-    key = await verifyRequest(request, {
+    result = await verifyRequestDetailed(request, {
       documentLoader,
       ...(keyCache ? { keyCache } : {}),
       timeWindow: timeWindow ?? { hours: 1 },
     });
   } catch {
-    key = null;   // a loader that refused (SSRF, 401 from a secure-mode pod) → unverified
+    result = null;   // the library itself failed — no more informative than a bad signature
   }
-  if (key) {
+  if (result?.verified) {
+    const key = result.key;
     return {
       verified: true, method: 'draft-cavage',
       keyId: key.id?.href ?? null, actor: key.ownerId?.href ?? null, reason: null,
       checks: { signature: true, digest: true, dateSkew: true, keyFetched: true },
     };
   }
+  const kind = result?.reason?.type;
+  if (!hadSig || kind === 'noSignature') {
+    return {
+      verified: false, method: 'none', keyId: null, actor: null,
+      reason: 'no-signature', checks: { signature: false },
+    };
+  }
+  if (kind === 'keyFetchError') {
+    return {
+      verified: false, method: 'draft-cavage', keyId: null, actor: null,
+      reason: 'key-unfetchable', checks: { signature: false, keyFetched: false },
+    };
+  }
   return {
-    verified: false, method: hadSig ? 'draft-cavage' : 'none',
-    keyId: null, actor: null,
-    // The distinction the receipt needs: a forgery (present but invalid) is
-    // dropped at the edge; an absent or unfetchable-key signature degrades to
-    // buffered-unverified, exactly as an install with no gateway behaves.
-    reason: hadSig ? 'bad-signature-or-key-unfetchable' : 'no-signature',
-    checks: { signature: false },
+    verified: false, method: 'draft-cavage', keyId: null, actor: null,
+    reason: 'bad-signature', checks: { signature: false },
   };
 }