fedipod-server 0.4.0 → 0.6.0

package/lib/intake.mjs

@@ -113,7 +113,19 @@ function pollOf(note) {
     })),
   };
 }
-export const isContentType = (t) => CONTENT_TYPES.has(t);
+// AS2 lets `type` be one string or a list, and implementations use both —
+// `["Person","Service"]` is an ordinary actor. Read either form.
+const typesOf = (t) => (Array.isArray(t) ? t : [t]).filter(x => typeof x === 'string');
+export const isContentType = (t) => typesOf(t).some(x => CONTENT_TYPES.has(x));
+const isActorType = (t) => typesOf(t).some(x => ACTOR_TYPES.has(x));
+
+// What we will carry to our followers on someone else's behalf (§7.1.2): the
+// activities a conversation is made of, and nothing else. A type this file
+// does not handle falls out of handle() with no rejection, and "no rejection"
+// is what qualifies an activity for forwarding — so without this gate a
+// stranger could have anything at all, of a type nothing here reads,
+// re-delivered to every follower over our signature.
+const FORWARDABLE = new Set(['Create', 'Update', 'Delete', 'Like', 'Announce', 'Undo']);
 const ACCEPT_AP = 'application/activity+json, application/ld+json; profile="https://www.w3.org/ns/activitystreams"';
 
 export function sameOrigin(a, b) {
@@ -741,7 +753,7 @@ export class Intake {
     // Same origin rather than exact equality: signedFetch follows redirects
     // without reporting where it landed, so a server that redirects its own
     // canonical actor URL would otherwise stop being cached at all.
-    if (ACTOR_TYPES.has(doc?.type) && doc.id && sameOrigin(doc.id, url)) {
+    if (isActorType(doc?.type) && doc.id && sameOrigin(doc.id, url)) {
       this.store.cacheActor(doc.id, doc);
     }
     return doc;
@@ -1123,6 +1135,7 @@ export class Intake {
   // never forwarded.
   async _maybeForward(activity) {
     if (!activity || typeof activity !== 'object') return;
+    if (!FORWARDABLE.has(activity.type)) return;              // see FORWARDABLE
     try {
       const audience = []
         .concat(activity.to || [], activity.cc || [], activity.audience || [])
@@ -1380,9 +1393,9 @@ export class Intake {
     const note = await this.fetchAP(objectId);
     if (!note) return `object fetch failed (${objectId})`;
     if (note.id !== objectId || !isContentType(note.type)) return `object not verifiable content (${objectId}, ${note.type})`;
-    const { attachmentsOf, sanitizeHtml } = await import('./wire.mjs');
+    const { attachmentsOf, titledContent } = await import('./wire.mjs');
     const attachments = attachmentsOf(note);
-    const content = sanitizeHtml(note.content);   // hostile markup never reaches pod or client
+    const content = titledContent(note);          // hostile markup never reaches pod or client
     // The delivering actor was checked on arrival; the author is only known once
     // the note is dereferenced. authorOf refuses an author the note's own origin
     // does not vouch for — see its comment; this is where a forged attribution
@@ -1594,8 +1607,8 @@ export class Intake {
     const note = await this.fetchAP(objectId);
     if (!note) throw new Error(`cannot refetch ${objectId} — will retry`);
     if (note.id !== objectId || !isContentType(note.type)) return `object not verifiable content (${objectId}, ${note.type})`;
-    const { attachmentsOf, sanitizeHtml } = await import('./wire.mjs');
-    const content = sanitizeHtml(note.content);
+    const { attachmentsOf, titledContent } = await import('./wire.mjs');
+    const content = titledContent(note);
     const attachments = attachmentsOf(note);
     const freshPoll = pollOf(note);
     const freshEmojis = emojisOf(note);

package/lib/keys.mjs

@@ -1,7 +1,7 @@
 // keys.mjs — actor signing keys. RSA (Mastodon's draft-cavage HTTP Signatures
-// require RSA-SHA256) + Ed25519 (stored for future FEP-8b32 use, not yet in
-// the actor doc). PEM at rest (0600), CryptoKey in memory for Fedify's
-// signRequest.
+// require RSA-SHA256) signs deliveries; Ed25519 signs the FEP-8b32 proof that
+// travels with an activity. PEM at rest (0600), CryptoKey in memory for
+// Fedify's signRequest and for the proof.
 //
 // The key lives on THIS MACHINE by default (AP_HOME/keys.json): the pod host
 // then never holds it. `setup --keys pod` puts it in pod state instead,
@@ -112,9 +112,23 @@ export async function resolveKeys(store, { localDir = null, rotate = false, acto
     log(rotate ? 'minted a REPLACEMENT signing key — republish the profile' : 'minted a signing key');
   }
 
+  // A record written before proofs existed has no Ed25519 half. Minting one is
+  // safe in a way minting an RSA key is not: nothing has ever published or
+  // cached it, so no remote signature is invalidated.
+  if (!rec.ed25519) {
+    rec = { ...rec, ed25519: generate().ed25519 };
+    if (localDir) writeLocal(localDir, rec); else store.write('keys.json', rec);
+    log('minted the Ed25519 half of the signing key');
+  }
+
   const der = crypto.createPrivateKey(rec.rsa.privatePem).export({ type: 'pkcs8', format: 'der' });
   const rsaPrivate = await crypto.subtle.importKey('pkcs8', der, RSA_ALG, true, ['sign']);
-  return { rsaPrivate, rsaPublicPem: rec.rsa.publicPem };
+  const { edPrivateKey, multibaseEd25519 } = await import('./proof.mjs');
+  return {
+    rsaPrivate, rsaPublicPem: rec.rsa.publicPem,
+    edPrivate: await edPrivateKey(rec.ed25519.privatePem),
+    edPublicMultibase: multibaseEd25519(rec.ed25519.publicPem),
+  };
 }
 
 // Move a local key into pod state — the arrangement that lets several

package/lib/lease.mjs

@@ -29,6 +29,7 @@ export class Lease {
     this.stopped = false;
     this.timer = null;
     this.heldUntil = 0;   // wall-clock end of the lease we last wrote
+    this.denied = null;   // why the last acquire() said no: 'unreadable' | 'held'
   }
 
   // null means the lease document is NOT THERE — nobody holds it. UNREADABLE
@@ -74,16 +75,21 @@ export class Lease {
     const cur = await this.readFresh();
     // Cannot read it: stay a viewer. A viewer that should have been active is
     // an inconvenience; two agents both draining is the destructive one.
-    if (cur === UNREADABLE) { this.log('lease unreadable — staying a viewer'); return false; }
-    if (cur && cur.holder !== this.id && Date.now() < cur.expiresAt) return false;
+    if (cur === UNREADABLE) {
+      this.denied = 'unreadable';
+      this.log('lease unreadable — staying a viewer'); return false;
+    }
+    if (cur && cur.holder !== this.id && Date.now() < cur.expiresAt) { this.denied = 'held'; return false; }
     const doc = { holder: this.id, expiresAt: Date.now() + TTL_MS };
-    if (!await this.write(doc)) return false;
+    if (!await this.write(doc)) { this.denied = 'held'; return false; }
     const confirm = await this.readFresh();
-    if (confirm === UNREADABLE || confirm?.holder !== this.id) return false;
+    if (confirm === UNREADABLE) { this.denied = 'unreadable'; return false; }
+    if (confirm?.holder !== this.id) { this.denied = 'held'; return false; }
     // From the document we WROTE, and only once the confirm agrees. Recomputing
     // it here would claim a lease that outlives what the pod's copy grants, by
     // however long the PUT and the confirming GET took.
     this.heldUntil = doc.expiresAt;
+    this.denied = null;
     return true;
   }
 

package/lib/mastoapi.mjs

@@ -12,7 +12,7 @@
 
 import crypto from 'node:crypto';
 import * as social from './social.mjs';
-import { sanitizeHtml } from './wire.mjs';
+import { sanitizeHtml, followsNeedApproval } from './wire.mjs';
 import { authorOf } from './intake.mjs';
 import { profileUrl, postUrl } from './bskyfeed.mjs';
 import { Push } from './webpush.mjs';
@@ -222,7 +222,7 @@ export class MastoApi {
       // people — so read it from config, or the editor opens empty and saving
       // wipes what was there.
       display_name: (self ? this.store.getConfig()?.name : cached.name) || cached.name || user,
-      locked: self ? !!this.store.getConfig()?.approveJoins : false,
+      locked: self ? followsNeedApproval(this.store.getConfig() || {}) : false,
       // Read from config for self, like the fields above it: our own actor is
       // not in the actor cache — the cache is for other people — so a group
       // asking about itself would be told it was a person.

package/lib/proof.mjs

@@ -0,0 +1,79 @@
+// proof.mjs — FEP-8b32 object integrity proofs (Data Integrity, eddsa-jcs-2022).
+//
+// An HTTP signature covers one delivery and says nothing about who wrote what
+// was inside it. A proof travels with the activity, so a server that receives
+// one of ours second-hand — carried by a group, or forwarded by a follower's
+// server — can tell it is ours without asking us.
+//
+// The RSA `#main-key` and its HTTP signatures are untouched; this is a second
+// key alongside, which is what the Data Integrity suites require.
+
+import crypto from 'node:crypto';
+import serialize from 'json-canon';
+
+// multicodec: an Ed25519 public key is its 32 raw bytes behind 0xed 0x01.
+const ED25519_PREFIX = Buffer.from([0xed, 0x01]);
+const B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+export function base58btc(bytes) {
+  const b = Buffer.from(bytes);
+  let n = 0n;
+  for (const byte of b) n = (n << 8n) + BigInt(byte);
+  let out = '';
+  while (n > 0n) { out = B58[Number(n % 58n)] + out; n /= 58n; }
+  for (const byte of b) { if (byte !== 0) break; out = B58[0] + out; }
+  return out;
+}
+
+/** The `publicKeyMultibase` form of an Ed25519 public key in PEM. */
+export function multibaseEd25519(publicPem) {
+  const raw = Buffer.from(crypto.createPublicKey(publicPem).export({ format: 'jwk' }).x, 'base64url');
+  return 'z' + base58btc(Buffer.concat([ED25519_PREFIX, raw]));
+}
+
+/** The signing key, as WebCrypto wants it. */
+export function edPrivateKey(privatePem) {
+  const jwk = crypto.createPrivateKey(privatePem).export({ format: 'jwk' });
+  return crypto.subtle.importKey('jwk', { ...jwk, key_ops: ['sign'] }, { name: 'Ed25519' }, true, ['sign']);
+}
+
+const sha256 = (s) => crypto.createHash('sha256').update(s).digest();
+
+// The proof's own terms have to be declared in the document that carries it,
+// or a receiver that processes JSON-LD expands the proof away before it ever
+// looks at it. Declared BEFORE signing, because the proof covers the document
+// exactly as sent, `@context` included.
+export const DI_CTX = 'https://w3id.org/security/data-integrity/v1';
+
+function withProofContext(doc) {
+  const ctx = doc['@context'];
+  const list = Array.isArray(ctx) ? ctx : ctx ? [ctx] : [];
+  if (list.includes(DI_CTX)) return doc;
+  return { ...doc, '@context': [...list, DI_CTX] };
+}
+
+/**
+ * Return the activity with a `proof` attached. The proof covers the activity
+ * exactly as it goes on the wire, minus the proof itself — so it must be the
+ * last thing added, and nothing may edit the activity afterwards.
+ *
+ * Whole seconds on `created`: a verifier re-serializes the timestamp it was
+ * given, and a fractional one has more than one spelling.
+ */
+export async function attachProof(activity, { privateKey, verificationMethod, created = new Date() } = {}) {
+  if (!privateKey || !verificationMethod || !activity || typeof activity !== 'object') return activity;
+  const { proof: _existing, ...bare } = activity;
+  const doc = withProofContext(bare);
+  const config = {
+    '@context': doc['@context'],
+    type: 'DataIntegrityProof',
+    cryptosuite: 'eddsa-jcs-2022',
+    verificationMethod,
+    proofPurpose: 'assertionMethod',
+    created: new Date(created).toISOString().replace(/\.\d+Z$/, 'Z'),
+  };
+  const digest = Buffer.concat([sha256(serialize(config)), sha256(serialize(doc))]);
+  const sig = await crypto.subtle.sign('Ed25519', privateKey, digest);
+  const { '@context': _ctx, ...emitted } = config;
+  return { ...doc, proof: { ...emitted, proofValue: 'z' + base58btc(Buffer.from(sig)) } };
+}

package/lib/publisher.mjs

@@ -22,7 +22,7 @@ const AGENT_VERSION = JSON.parse(fs.readFileSync(
   path.join(path.dirname(fileURLToPath(import.meta.url)), '../package.json'), 'utf8')).version;
 
 export class Publisher {
-  constructor({ config, remote, local, store, deliverer, publicKeyPem, log = console.log,
+  constructor({ config, remote, local, store, deliverer, publicKeyPem, assertionKey = null, log = console.log,
     probeFetch = null, resolveMention = null, privateOnPod = true,
   }) {
     this.config = config;
@@ -31,6 +31,7 @@ export class Publisher {
     this.store = store;
     this.deliverer = deliverer;
     this.publicKeyPem = publicKeyPem;
+    this.assertionKey = assertionKey;      // Ed25519 public half, multibase; null = no proofs
     // A fronted identity (config.gateway.frontActor) advertises its ids on a
     // shared domain; the map tells RemotePod where each writes on the pod.
     const publicBase = config.gateway?.frontActor
@@ -76,7 +77,8 @@ export class Publisher {
     const actorDoc = wire.actorDoc({
       urls, handle: this.config.handle, name: this.config.name, publicKeyPem: this.publicKeyPem,
       movedTo: this.config.movedTo || null, kind: this.config.kind,
-      approveJoins: !!this.config.approveJoins,
+      approveJoins: wire.followsNeedApproval(this.config),
+      assertionKey: this.assertionKey,
       summary: this.config.summary || null, icon: this.config.icon || null,
       image: this.config.image || null, fields: this.config.fields || [],
       webId: this.remote.webId || null,
@@ -350,7 +352,8 @@ export class Publisher {
     await this.remote.putJson(urls.actor, wire.actorDoc({
       urls, handle: this.config.handle, name: this.config.name,
       publicKeyPem: this.publicKeyPem, movedTo: target, kind: this.config.kind,
-      approveJoins: !!this.config.approveJoins,
+      approveJoins: wire.followsNeedApproval(this.config),
+      assertionKey: this.assertionKey,
       summary: this.config.summary || null, icon: this.config.icon || null,
       image: this.config.image || null, fields: this.config.fields || [],
       webId: this.remote.webId || null,

package/lib/tagfeed.mjs

@@ -135,10 +135,10 @@ export class TagFeed {
         if (!this.store.getActors()[author]) {
           await this.intake.fetchAP(author).catch(() => {});   // warm name+avatar
         }
-        const { attachmentsOf, sanitizeHtml } = await import('./wire.mjs');
+        const { attachmentsOf, titledContent } = await import('./wire.mjs');
         const attachments = attachmentsOf(note);
         this.store.addStatus({
-          noteId, actor: author, content: sanitizeHtml(note.content),
+          noteId, actor: author, content: titledContent(note),
           published: note.published, inReplyTo: note.inReplyTo, kind: 'tag', tag,
           ...(attachments.length ? { attachments } : {}),
         });

package/lib/update.mjs

@@ -42,16 +42,21 @@ export async function checkLatest({ current = localVersion(), fetchImpl = fetch
   } catch { return null; }
 }
 
+// The npm half, injectable — a test asking what runUpdate DOES must never be
+// able to install software on the machine running it.
+const npmInstallLatest = () =>
+  execFileSync('npm', ['install', '-g', 'fedipod@latest'], { stdio: 'pipe' });
+
 // Fast-forward only: a checkout with local changes is somebody's work, and an
 // update must refuse rather than eat it.
-export function runUpdate({ root = repoRoot(), log = () => {} } = {}) {
+export function runUpdate({ root = repoRoot(), log = () => {}, install = npmInstallLatest } = {}) {
   // The ordinary install comes from npm, where updating is npm's job and the
   // files under us are not ours to move. A checkout is somebody working on it,
   // and gets the fast-forward below.
   if (!fs.existsSync(path.join(root, '.git'))) {
     try {
       log('updating from npm…');
-      execFileSync('npm', ['install', '-g', 'fedipod@latest'], { stdio: 'pipe' });
+      install();
       return { ok: true, note: 'updated from npm — restart the agent to serve it' };
     } catch (e) {
       return { ok: false,

package/lib/wire.mjs

@@ -87,7 +87,19 @@ export function jrd({ handle, host, actor }) {
 
 // `kind: 'group'` publishes a Group rather than a Person, which is what makes
 // Mastodon and Lemmy treat the actor as a community you join.
-export function actorDoc({ urls, handle, name, publicKeyPem, movedTo = null, kind = 'person',
+// Whether a follow will be held for the operator instead of accepted on
+// arrival. A person's follows wait unless `autoAcceptFollows` says otherwise,
+// because a delivery on its own proves nothing about who sent it; a group is
+// open unless its operator asked to see joins. The actor document has to say
+// the same thing, or a remote server shows "Following" for a follow that is
+// in fact still waiting, and nothing ever tells it otherwise.
+export function followsNeedApproval(config = {}) {
+  return !!config.approveJoins || (config.kind !== 'group' && !config.autoAcceptFollows);
+}
+
+export const assertionKeyId = (urls) => urls.actor + '#ed25519-key';
+
+export function actorDoc({ urls, handle, name, publicKeyPem, assertionKey = null, movedTo = null, kind = 'person',
   approveJoins = false, summary = null, icon = null, image = null, fields = [],
   webId = null, aliases = [], moderators = null, pendingFollowers = null, pendingFollowing = null,
   blocked = null, inbox = null }) {
@@ -103,6 +115,12 @@ export function actorDoc({ urls, handle, name, publicKeyPem, movedTo = null, kin
   // inline exactly as Mastodon declares it.
   context.push({ toot: 'http://joinmastodon.org/ns#', featured: { '@id': 'toot:featured', '@type': '@id' } });
   if (approveJoins) context.push({ manuallyApprovesFollowers: 'as:manuallyApprovesFollowers' });
+  // FEP-8b32. The Multikey is a SECOND key beside publicKey/#main-key, not a
+  // replacement: HTTP signatures stay RSA, and only the proof is Ed25519.
+  // `assertionMethod` comes from the DID context and the key's own terms from
+  // the Multikey one; the proof's terms travel with the proof, not here.
+  if (assertionKey) context.push('https://www.w3.org/ns/did/v1',
+    'https://w3id.org/security/multikey/v1');
   // FEP-4ccd and FEP-c648 terms, declared exactly as those FEPs declare them,
   // and only when the collections are actually published.
   if (pendingFollowers || pendingFollowing) {
@@ -130,6 +148,10 @@ export function actorDoc({ urls, handle, name, publicKeyPem, movedTo = null, kin
     id: urls.actor,
     type: kind === 'group' ? 'Group' : 'Person',
     ...(approveJoins ? { manuallyApprovesFollowers: true } : {}),
+    ...(assertionKey ? { assertionMethod: [{
+      id: assertionKeyId(urls), type: 'Multikey', controller: urls.actor,
+      publicKeyMultibase: assertionKey,
+    }] } : {}),
     ...(movedTo ? { movedTo } : {}),
     ...(webId || aliases.length ? { alsoKnownAs: [...(webId ? [webId] : []), ...aliases] } : {}),
     preferredUsername: handle,
@@ -526,11 +548,28 @@ export function sanitizeHtml(html) {
   });
 }
 
+// A Lemmy post, a blog article, a PeerTube video and a Bookwyrm review each
+// carry their headline in `name` and their body in `content`. Reading content
+// alone loses the headline, and a link post is often nothing else — so keep it
+// as the first line, unless the body already opens with it.
+export function titledContent(note) {
+  const html = sanitizeHtml(note?.content);
+  const types = Array.isArray(note?.type) ? note.type : [note?.type];
+  const title = typeof note?.name === 'string' ? note.name.trim() : '';
+  if (!title || types.includes('Note')) return html;
+  const opening = html.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim().toLowerCase();
+  if (opening.startsWith(title.toLowerCase())) return html;
+  const esc = String(title).replace(/[&<>]/g, c => HTML_ESCAPES[c]);
+  return `<p><strong>${esc}</strong></p>${html}`;
+}
+
 // Normalize a wire Note's attachment list to { url, mediaType, description }.
 export function attachmentsOf(note) {
   const list = Array.isArray(note?.attachment) ? note.attachment : note?.attachment ? [note.attachment] : [];
+  // A bare Link carries `href` and no `url` — Lemmy's link posts arrive that
+  // way, and reading only `url` dropped the link the post was about.
   return list.map(a => ({
-    url: typeof a?.url === 'string' ? a.url : a?.url?.href,
+    url: typeof a?.url === 'string' ? a.url : a?.url?.href || (typeof a?.href === 'string' ? a.href : undefined),
     mediaType: a?.mediaType || '',
     ...(a?.name ? { description: a.name } : {}),
   })).filter(a => a.url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fedipod-server",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "The FediPod Server: a full ActivityPub server as a Community Solid Server component.",
   "license": "MIT",
   "main": "dist/index.js",
@@ -35,6 +35,11 @@
     "@types/node": "^20.0.0",
     "@solid/community-server": "^7.2.0"
   },
+  "overrides": {
+    "@opentelemetry/core": "^2.8.0",
+    "package.json": "npm:empty-npm-package@1.0.0",
+    "package-lock.json": "npm:empty-npm-package@1.0.0"
+  },
   "lsd:module": "https://linkedsoftwaredependencies.org/bundles/npm/fedipod-server",
   "lsd:components": "dist/components/components.jsonld",
   "lsd:contexts": {
@@ -50,6 +55,7 @@
     "build:components": "componentsjs-generator -s src -c dist/components -r fps",
     "test": "npm run build && node --test test/*.mjs",
     "test:e2e": "node test/e2e/live-agent.mjs",
+    "prepublishOnly": "npm test",
     "prepack": "node scripts/pack-tree.mjs copy",
     "postpack": "node scripts/pack-tree.mjs clean"
   }

package/run-agent.mjs

@@ -47,7 +47,7 @@ import { Lease } from './lib/lease.mjs';
 import { startAdmin } from './lib/admin.mjs';
 import { exposureProblem, hostLabel } from './lib/guard.mjs';
 import { pendingSteps } from './lib/migrate.mjs';
-import { apUrls } from './lib/wire.mjs';
+import { apUrls, assertionKeyId } from './lib/wire.mjs';
 import { followActor, unfollowActor, resolveHandle } from './lib/social.mjs';
 
 export class Agent {
@@ -324,11 +324,14 @@ export class Agent {
     clearInterval(this.schedTimer);
     this.deliverer = new Deliverer({
       store: this.store, rsaPrivate: keys.rsaPrivate, keyId: this.urls.actor + '#main-key',
+      actorId: this.urls.actor, edPrivate: keys.edPrivate,
+      proofKeyId: assertionKeyId(this.urls),
       log: this.log, passive: this.viewer,
     });
     this.publisher = new Publisher({
       config, remote: this.remote, local: this.local, store: this.store,
-      deliverer: this.deliverer, publicKeyPem: keys.rsaPublicPem, log: this.log,
+      deliverer: this.deliverer, publicKeyPem: keys.rsaPublicPem,
+      assertionKey: keys.edPublicMultibase, log: this.log,
       resolveMention: (h) => resolveHandle(this, h),
       // Whether the fediverse tree is on the pod at all, so the ACL check does
       // not probe for something the default layout keeps on local disk.
@@ -355,7 +358,9 @@ export class Agent {
     this.intake.bskyGroup = null;
     if (this.viewer) {
       this.startViewer();
-      this.log(`another agent is active for this pod — viewing as @${config.handle} (read-only)`);
+      this.log(this.lease.denied === 'unreadable'
+        ? `the pod cannot be read, so the lease is unknown — viewing as @${config.handle} (read-only)`
+        : `another agent is active for this pod — viewing as @${config.handle} (read-only)`);
       return true;
     }
     await this.startActive({ repair });
@@ -389,7 +394,9 @@ export class Agent {
       log: this.log,
     });
     this.publisher.publicKeyPem = keys.rsaPublicPem;
+    this.publisher.assertionKey = keys.edPublicMultibase;
     this.deliverer.rsaPrivate = keys.rsaPrivate;
+    this.deliverer.edPrivate = keys.edPrivate;
     await this.publisher.publishProfile();
     return { changed: before !== keys.rsaPublicPem, publicKeyPem: keys.rsaPublicPem };
   }

package/web/admin/admin.js

@@ -141,7 +141,7 @@ function render() {
     ['local host', (origins.named || origins.loopback || `http://localhost:${config.port}`)
       .replace(/\/$/, '')],
   ];
-  if (config.update || config.pendingUpgrade?.length) rows.push(['software', 'ctl']);
+  if (config.version || config.update || config.pendingUpgrade?.length) rows.push(['software', 'ctl']);
   if (config.quiescedAt) rows.push(['parked since', config.quiescedAt]);
   if (config.movedTo) rows.push(['moved to', config.movedTo]);
   // A person gates followers here; a group's gate is the joins control on its
@@ -190,8 +190,13 @@ function render() {
       dd.append(UPDATE_CTL);
       UPDATE_CTL.hidden = false;
       const u = config.update;
+      // The version this agent is running, never the one sitting in the
+      // checkout — saying otherwise would name a version nobody is serving.
+      const running = config.version || u?.current || null;
       const words = [];
-      if (u) words.push(u.available ? `FediPod ${u.current} — ${u.latest} available` : `FediPod ${u.current}`);
+      if (running) words.push(u?.available ? `FediPod ${running} — ${u.latest} available` : `FediPod ${running}`);
+      if (config.versionOnDisk && running && config.versionOnDisk !== running)
+        words.push(`${config.versionOnDisk} is on disk — restart to run it`);
       if (config.pendingUpgrade?.length) words.push('older data layout — run `fedipod upgrade` in a terminal');
       UPDATE_WORD.textContent = words.join('; ');
       UPDATE_GO.hidden = !u?.available;
@@ -232,6 +237,7 @@ function render() {
   renderAliases();
   renderOthers();
   renderInbox();
+  renderGateway();
   if (config.kind === 'group') {
     // Its lists have no bound, so this page scrolls — see body.group in the CSS.
     document.body.classList.add('group');
@@ -931,9 +937,62 @@ async function renderInbox() {
   panel.hidden = false;
 }
 
-// The inbox-gateway / multi-user-front operator panel is parked: not shown in
-// the UI yet. The backend routes (GET/POST /gateway) still exist and work, so
-// this can be re-added when the feature is ready to expose.
+// The gateway panel: attach through a multi-user front with this agent's own
+// credential, see what the door has verified, detach back to the pod inbox.
+let gwTimer = null;
+async function renderGateway() {
+  const { status, json: g } = await api('/gateway');
+  if (status !== 200 || !g) return;              // no answer, no surface
+  $('pane-gateway').hidden = false;
+  if (g.configured) {
+    const host = (() => { try { return new URL(g.url).host; } catch { return g.url; } })();
+    const st = g.stats || {};
+    $('gateway-summary').textContent = `Attached to ${host} (mode ${g.mode})`
+      + (g.frontActor ? `, publishing as ${g.frontActor}` : '')
+      + ` — ${st.verified || 0} deliveries verified, ${st.unverified || 0} unverified.`;
+    $('gateway-attach-form').hidden = true;
+    $('gateway-attached').hidden = false;
+  } else {
+    $('gateway-summary').textContent = 'Mail arrives directly at your pod\'s own inbox.';
+    $('gateway-attach-form').hidden = false;
+    $('gateway-attached').hidden = true;
+    if (!$('gw-name').value && config?.handle) $('gw-name').value = config.handle;
+  }
+}
+// Live availability, asked through the agent (the front answers it without CORS).
+function gwCheck() {
+  clearTimeout(gwTimer);
+  const front = $('gw-front').value.trim().replace(/\/+$/, '');
+  const name = $('gw-name').value.trim().toLowerCase();
+  $('gw-name-msg').textContent = ''; $('gw-name-msg').className = 'hint';
+  if (!front || !name) return;
+  gwTimer = setTimeout(async () => {
+    const { status, json } = await postJson('/gateway', { action: 'check', front, handle: name });
+    if (status !== 200 || !json) return;
+    $('gw-name-msg').textContent = json.available
+      ? `${name} is free at ${front.replace(/^https?:\/\//, '')}`
+      : (json.reason || 'that name is taken');
+    $('gw-name-msg').className = json.available ? 'hint' : 'warn';
+  }, 300);
+}
+$('gw-front').addEventListener('input', gwCheck);
+$('gw-name').addEventListener('input', gwCheck);
+$('gw-attach').onclick = async () => {
+  const front = $('gw-front').value.trim().replace(/\/+$/, '');
+  const fronted = $('gw-shape').value === 'front';
+  $('gw-attach').disabled = true;
+  const r = await write('/gateway',
+    { action: 'attach', front, handle: $('gw-name').value.trim().toLowerCase(), fronted },
+    fronted ? 'attached — restart the agent to publish under the gateway name'
+      : 'attached — your mail now arrives through the gateway, filtered');
+  $('gw-attach').disabled = false;
+  if (r) renderGateway();
+};
+$('gw-detach').onclick = async () => {
+  const r = await write('/gateway', { action: 'forget' },
+    'detached — the actor was republished advertising your pod\'s own inbox');
+  if (r) renderGateway();
+};
 
 $('inbox-keep').addEventListener('click', () => {
   dismissed = true;

package/web/admin/index.html

@@ -314,9 +314,36 @@ pre { overflow-x: auto; background: #0001; padding: .6rem; border-radius: .3rem;
   </span>
 </section>
 
-<!-- The inbox-gateway / multi-user-front controls are deliberately not shown
-     in the UI yet. The backend routes (GET/POST /gateway) exist and work; the
-     operator surface is parked until the feature is ready to expose. -->
+<!-- The inbox gateway: a mail filter for an account that stays yours. -->
+<section id="pane-gateway" hidden>
+  <h2><span class="hlabel">Gateway</span></h2>
+  <p id="gateway-summary"></p>
+  <div id="gateway-attach-form" hidden>
+    <p class="hint">A gateway filters your fediverse mail before it reaches your pod: your
+      actor advertises the gateway's door as its inbox, each delivery is verified there,
+      spam is dropped, and the rest lands in your pod as before. Attaching proves the pod
+      with this agent's own credential — no password leaves this machine.</p>
+    <p>
+      <label for="gw-front">Gateway</label>
+      <input type="url" id="gw-front" placeholder="https://fedipod.net" autocomplete="off">
+      <label for="gw-name">Your name there</label>
+      <input type="text" id="gw-name" autocomplete="off" autocapitalize="off" spellcheck="false">
+    </p>
+    <p id="gw-name-msg" class="hint"></p>
+    <p>
+      <select id="gw-shape" aria-label="Name shape" title="   Which address the fediverse sees — the pod-based name keeps everything on your pod; a gateway-based name survives changing pods">
+        <option value="pod">keep my pod-based name</option>
+        <option value="front">use a gateway-based name</option>
+      </select>
+      <button id="gw-attach" class="primary" title="   Create the gateway account and point your mail through its door">Attach</button>
+    </p>
+  </div>
+  <div id="gateway-attached" hidden>
+    <p>
+      <button id="gw-detach" class="inline danger" title="   Republish the actor with your pod's own inbox and forget the gateway">Detach</button>
+    </p>
+  </div>
+</section>
 
 <section id="pane-group" hidden>
   <!-- Both queues are consequences of a moderation setting: with the setting off