fedipod-server 0.29.0 → 0.31.0

package/lib/device/setup.mjs

@@ -1,496 +0,0 @@
-// setup.mjs — the setup flow itself, lifted out of the CLI so a browser page
-// can drive it. Same order, same decisions as `fedipod setup` always had:
-// create the account and pod (or use one you already have), mint a revocable
-// credential, provision the pod, publish the actor, check it is really public.
-//
-// The caller owns the run record and polls it; runSetup only fills it in. That
-// is deliberate. The credential a CSS server mints is shown once and cannot be
-// recovered, so the durable record of a run has to be the credential file on
-// disk, never an HTTP response a closed tab can take with it.
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-import * as $rdf from 'rdflib';
-
-import { createAccountWithPod as realCreateAccount } from './account.mjs';
-import { mintCredential as realMint, RemotePod } from './remote.mjs';
-import { hashPassword } from '../client/masto/index.mjs';
-import { webfingerHost, apUrls, DEFAULT_ROOT } from '../core/wire.mjs';
-import { rootOf, recordLastUsed, writeJsonAtomic } from './home.mjs';
-import { insecureUrlReason } from '../shared/safefetch.mjs';
-import { resourceExists } from '../pod/root.mjs';
-import { CURRENT_LAYOUT, isCurrent } from './migrate.mjs';
-import { completeGatewayMove } from './gateway-move.mjs';
-import { chosenRoot, chosenRootInNewPod, publicIndexKnown, recordPlace, needsIndex } from '../core/place.mjs';
-
-const SOLID = $rdf.Namespace('http://www.w3.org/ns/solid/terms#');
-
-export const STEPS = ['account', 'credential', 'bootstrap', 'connect', 'publish', 'verify'];
-
-// Read-only pre-check on the pod behind an existing-pod setup, before a
-// credential is minted or the first write is attempted. Two failures it turns
-// from a bare "PUT … → 401" into a plain sentence:
-//   1. the pod host is unreachable — no account should be built on a pod that
-//      is not there;
-//   2. the pod's WebID document declares no OIDC issuer. A pod verifies a token
-//      by dereferencing its WebID and looking for solid:oidcIssuer; an empty or
-//      issuer-less profile makes it reject every write with 401, so setup would
-//      stall on the first one. Only judged when the document is publicly
-//      readable — a protected one cannot be read here and is left to bootstrap.
-export async function checkPodUsable(pod, { webId, fetch: doFetch = globalThis.fetch } = {}) {
-  const base = pod.endsWith('/') ? pod : pod + '/';
-  const wid = webId || new URL('profile/card#me', base).href;
-  const cardUrl = wid.split('#')[0];
-
-  let root;
-  try { root = await doFetch(base, { headers: { accept: 'text/turtle' } }); }
-  catch (e) { return { ok: false, error: `${base} could not be reached (${e.message}). Check the address and that the server is running.` }; }
-  if (root.status === 404) return { ok: false, error: `there is no pod at ${base} — the server answered 404.` };
-  if (root.status >= 500) return { ok: false, error: `the pod host at ${base} is not responding (HTTP ${root.status}).` };
-
-  let card;
-  try { card = await doFetch(cardUrl, { headers: { accept: 'text/turtle' } }); }
-  catch (e) { return { ok: false, error: `the pod's WebID document ${cardUrl} could not be read (${e.message}).` }; }
-  if (card.status === 404) return { ok: false, error: `the pod has no WebID document at ${cardUrl} — the identity it needs is missing.` };
-  if (card.status >= 500) return { ok: false, error: `the pod host is not serving ${cardUrl} (HTTP ${card.status}).` };
-  if (card.status === 401 || card.status === 403) return { ok: true };   // cannot read unauthenticated; leave it to bootstrap
-
-  const body = await card.text().catch(() => '');
-  const g = $rdf.graph();
-  try { $rdf.parse(body, g, cardUrl, (card.headers.get('content-type') || 'text/turtle').split(';')[0].trim()); }
-  catch { return { ok: false, error: `the pod's WebID document ${cardUrl} could not be parsed as RDF.` }; }
-  if (!g.each($rdf.sym(wid), SOLID('oidcIssuer'), null).length) {
-    return { ok: false, error: `the pod's WebID document ${cardUrl} declares no OIDC issuer, so the pod will reject every write. It looks empty or incomplete — restore it, or set up with a fresh pod.` };
-  }
-  return { ok: true };
-}
-
-export const credentialPath = (home) => path.join(home, 'credential.json');
-export const hasCredential = (home) => fs.existsSync(credentialPath(home));
-
-export function newRun() {
-  return {
-    phase: 'running',
-    startedAt: new Date().toISOString(),
-    steps: STEPS.map(key => ({ key, state: 'waiting', note: null })),
-    error: null,
-    result: null,
-  };
-}
-
-// What must be answered before a run can start. `resuming` is a run that
-// already has its credential: the account and the pod are settled, and only
-// the actor's own details are still open.
-export function setupInputError(a, resuming = false) {
-  if (!a.handle) return 'a handle is required';
-  if (a.kind && a.kind !== 'person' && a.kind !== 'group') return 'kind must be person or group';
-  if (a.privateRoot) {
-    try { new URL(a.privateRoot); } catch { return `"${a.privateRoot}" is not a container address`; }
-    // A pod one, at least. A file: private root is a directory and has no
-    // transport to secure.
-    if (/^https?:/i.test(a.privateRoot)) {
-      const bad = insecureUrlReason(a.privateRoot, 'private-data address');
-      if (bad) return bad;
-    }
-  }
-  if (a.gateway) {
-    if (typeof a.gateway.url !== 'string') return 'a gateway needs its door URL';
-    const badGw = insecureUrlReason(a.gateway.url, 'gateway address');
-    if (badGw) return badGw;
-  }
-  if (a.shape && a.shape !== 'pod' && a.shape !== 'front') return 'shape must be "pod" or "front"';
-  if (a.gatewayOrigin) {
-    const badO = insecureUrlReason(a.gatewayOrigin, 'gateway address');
-    if (badO) return badO;
-  }
-  if (resuming) return null;
-  if (a.mode !== 'new' && a.mode !== 'existing') return 'mode must be "new" or "existing"';
-  if (!a.issuer) return 'an identity provider is required';
-  // Checked BEFORE the password is asked for, let alone sent: the issuer is
-  // where it goes, and the pod is where the credential it buys is used.
-  const badIssuer = insecureUrlReason(a.issuer, 'identity provider address');
-  if (badIssuer) return badIssuer;
-  if (!a.email) return 'an account email is required';
-  if (!a.password) return 'the account password is required';
-  if (a.mode === 'existing' && !a.pod) return 'a pod address is required';
-  const badPod = insecureUrlReason(a.pod, 'pod address');
-  if (badPod) return badPod;
-  return null;
-}
-
-// Where an identity's address lives. A pod on a suffix-based host cannot
-// answer WebFinger for a handle, so its address must live at the Gateway
-// whatever was asked; a pod at its own host root takes the shape chosen.
-export function frontedAddress({ pod, shape }) {
-  const pathPod = pod ? !webfingerHost(pod) : false;
-  return pathPod || shape === 'front';
-}
-
-// The account a pod already holds, read as its owner: the config and the key
-// record in its state container. Both null when there is none, or when the
-// credential is not the owner's. Injected for tests.
-export async function readPodAccount({ home, credential, pod, root, log = () => {} }) {
-  const remote = new RemotePod(credential, { home, log });
-  await remote.warmup?.();
-  const urls = apUrls(pod, root || DEFAULT_ROOT);
-  const config = await remote.getJson(urls.state + 'config.json').catch(() => null);
-  const keys = await remote.getJson(urls.state + 'keys.json').catch(() => null);
-  return { config, keys };
-}
-
-// Take an address at a Gateway: attach the pod to it, fronted, and return the
-// gateway config bootstrap writes and connect reads. The pod session proves
-// the pod — no password reaches the Gateway. Injected for tests.
-export async function takeGatewayAddress({ home, credential, gatewayOrigin, handle, podHome, actorUrl, kind, log = () => {} }) {
-  const remote = new RemotePod(credential, { home, log });
-  await remote.warmup?.();
-  const origin = String(gatewayOrigin).replace(/\/$/, '');
-  const res = await remote.session.fetch(`${origin}/api/attach`, {
-    method: 'POST', headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ handle, podHome, actorUrl, kind: kind === 'group' ? 'group' : 'person', fronted: true }),
-  });
-  const d = await res.json().catch(() => ({}));
-  if (res.status !== 201 || !d.hmacSecret) {
-    throw new Error(`could not take a gateway address at ${new URL(origin).host} (HTTP ${res.status})${d.error ? ': ' + d.error : ''}`);
-  }
-  return {
-    url: `${origin}/u/${handle}/ap/inbox/`,
-    frontActor: String(d.frontActor || `${origin}/u/${handle}/ap/actor`),
-    hmacSecret: String(d.hmacSecret), mode: 'trust',
-  };
-}
-
-// What the CLI printed before asking "create pod and fediverse account?"
-// (bin/fedipod.mjs, the address preview) — as data, so the page can show
-// the same warnings. Pure: no network, so it can answer while you type.
-export function preflight({ mode, pod, issuer, podName, handle, kind, shape = 'pod', gatewayOrigin = 'https://fedipod.net' }) {
-  const warnings = [];
-  if (!handle) return { ok: false, error: 'a handle is required' };
-  let issuerHost;
-  try { issuerHost = new URL(issuer || 'https://solidcommunity.net').host; }
-  catch { return { ok: false, error: `"${issuer}" is not a URL` }; }
-
-  let gwHost; try { gwHost = new URL(gatewayOrigin).host; } catch { gwHost = 'fedipod.net'; }
-
-  if (mode === 'new') {
-    // Whether the provider puts the pod on its own subdomain or on a path is
-    // the provider's call, learned only once the pod is made. If the address
-    // was asked to live at the Gateway, it does. Otherwise the pod's own host
-    // is the address, and the run moves it to the Gateway if the provider
-    // turned out to use paths.
-    if (shape === 'front') {
-      if (kind === 'group') return { ok: false, mode, handle, kind, error: 'group-needs-host-root', refusal: 'group-needs-host-root', warnings };
-      return { ok: true, mode, handle, kind, fronted: true, forced: false, gatewayHost: gwHost, shape: 'front',
-        address: `@${handle}@${gwHost}`, webfingerHost: null, resolvable: true, warnings, refusal: null };
-    }
-    return {
-      ok: true, mode, handle, kind, fronted: false, shape: 'pod',
-      address: `@${handle}@${podName || handle}.${issuerHost}`,
-      webfingerHost: null, resolvable: null, warnings, refusal: null,
-    };
-  }
-
-  let podUrl;
-  try { podUrl = new URL(pod); }
-  catch { return { ok: false, error: `"${pod}" is not a pod address` }; }
-  // A handle resolves through <host>/.well-known/webfinger, so it only works
-  // when the pod owns the root of its host. A pod that does not can still be
-  // an account, with its address at the Gateway.
-  const wfHost = webfingerHost(podUrl.href);
-  const fronted = !wfHost || shape === 'front';
-  if (fronted) {
-    // A person's address moves to the Gateway; a group cannot, yet — a group
-    // needs a pod at its own host until fronted groups are proven.
-    if (kind === 'group') {
-      return { ok: false, mode: 'existing', handle, kind, refusal: 'group-needs-host-root', warnings,
-        address: `@${handle}@${podUrl.host}`, webfingerHost: null, resolvable: false };
-    }
-    return {
-      ok: true, mode: 'existing', handle, kind, fronted: true, forced: !wfHost, gatewayHost: gwHost, shape: 'front',
-      address: `@${handle}@${gwHost}`, webfingerHost: null, resolvable: true, warnings, refusal: null,
-    };
-  }
-  return {
-    ok: true, mode: 'existing', handle, kind, fronted: false, shape: 'pod',
-    address: `@${handle}@${wfHost}`,
-    webfingerHost: wfHost, resolvable: true, warnings, refusal: null,
-  };
-}
-
-// Fills `run` in as it goes. Never throws: a failure lands in run.error, so a
-// page that polls sees it. `deps` is for tests — the real functions otherwise.
-export async function runSetup({ home, agent, answers, run, deps = {}, log = () => {} }) {
-  const createAccount = deps.createAccountWithPod || realCreateAccount;
-  const mint = deps.mintCredential || realMint;
-  const checkPod = deps.checkPodUsable || checkPodUsable;
-  const attachGateway = deps.attachGateway || takeGatewayAddress;
-
-  const at = (key) => run.steps.find(s => s.key === key);
-  const begin = (key) => { at(key).state = 'running'; };
-  const done = (key, note = null) => { at(key).state = 'ok'; at(key).note = note; };
-  const skip = (key, note = null) => { at(key).state = 'skipped'; at(key).note = note; };
-
-  const {
-    mode, issuer, email, password, handle, name, podName,
-    kind = 'person', approveJoins = false, summary, icon, keys, uiPassword,
-    gateway = null, shape = 'pod', gatewayOrigin = 'https://fedipod.net',
-    // The container that holds `fedipod/` (blank: the pod's root), and the
-    // person's yes to a new public type index when their profile names none.
-    container = '', createIndex = false,
-  } = answers;
-  let { pod, root } = answers;
-  const rootGiven = !!root;
-  if (!root) root = 'fedipod/';   // until the pod is known; a resuming run
-  // overwrites this with the credential's own root below.
-  let accountWebId = null;   // what createAccountWithPod reported, when it ran
-  // The private half always starts here, beside the credential and the keys —
-  // not on the pod. Every activity you receive would otherwise cost the pod
-  // several writes, and that pod is a server somebody runs. `state --to` moves
-  // it afterwards; starting on the pod and moving later is strictly worse,
-  // because the copy left behind was on the pod the whole time.
-  let privateRoot = answers.privateRoot
-    || pathToFileURL(path.join(home, 'private')).href + '/';
-  // A pod that already holds an account at ANOTHER gateway, set up with an
-  // address at this one: not a second account but the same one moving in.
-  // Its state and key are on the pod, and stay there.
-  let movingIn = false;
-  let movedFrom = null;
-  // Everything that leaves this function — notes, errors, the log — goes
-  // through here. Nothing today echoes a password back, but /setup/progress is
-  // polled repeatedly and would re-serve one forever if anything ever did.
-  const scrub = (s) => (password ? String(s).split(password).join('••••••') : String(s));
-
-  const credPath = credentialPath(home);
-  const resuming = fs.existsSync(credPath);
-
-  try {
-    // --- account: create it, or use the pod you already have ---
-    if (resuming) {
-      skip('account', 'the credential is already on disk');
-    } else if (mode === 'new') {
-      begin('account');
-      // A new pod has no public type index: without a yes to making one,
-      // nothing is created at all.
-      if (!createIndex) throw needsIndex('A new pod has no public type index.');
-      const made = await createAccount({ issuer, email, password, podName: podName || handle });
-      pod = made.pod;
-      accountWebId = made.webId || null;
-      log(`account + pod created: ${pod}`);
-      // The server put the pod on a path rather than its own subdomain, so
-      // nobody could ever find this group. A person was warned before we got
-      // here and chose to continue; a group cannot.
-      if (kind === 'group' && !webfingerHost(pod)) {
-        throw new Error(`${issuer} created the pod at ${pod} — a suffixed pod. `
-          + 'WebFinger is only answered for a subdomained pod, so nobody '
-          + 'could find this group. The pod exists; no actor was published.');
-      }
-      if (!rootGiven) {
-        const place = chosenRootInNewPod(pod.endsWith('/') ? pod : pod + '/', container);
-        if (place.problem) throw new Error(`Where to store it: ${place.problem}.`);
-        root = place.root;
-      }
-      done('account', pod);
-    } else {
-      // A pod you bring must be there and carry a usable WebID before a
-      // credential is minted against it — no account on a pod that is not
-      // reachable, and no silent 401 later on a pod whose profile is empty.
-      const usable = await checkPod(pod);
-      if (!usable.ok) throw new Error(usable.error);
-      const podBase = pod.endsWith('/') ? pod : pod + '/';
-      if (!rootGiven) {
-        const place = chosenRoot(podBase, container);
-        if (place.problem) throw new Error(`Where to store it: ${place.problem}.`);
-        root = place.root;
-      }
-      // An account at the chosen place, or an older one where accounts used to go.
-      const exists = (r) => (deps.resourceExists || resourceExists)(deps.fetch || fetch, apUrls(pod, r).actor);
-      const held = await exists(root) || (root !== DEFAULT_ROOT && await exists(DEFAULT_ROOT));
-      if (held && !frontedAddress({ pod, shape })) {
-        throw new Error('The pod already hosts a FediPod account. If you want a second account, put it on a different pod. '
-          + 'To move an account whose address is at another gateway to this one, ask for an address at this gateway.');
-      }
-      if (held && kind === 'group') throw new Error('The pod already hosts a FediPod account, and a group cannot move between gateways.');
-      movingIn = held;
-      if (movingIn) { privateRoot = null; }
-      // Asked before anything is minted: a profile with no public type index
-      // gets one only on its person's yes.
-      if (!movingIn && !createIndex
-        && await (deps.publicIndexKnown || publicIndexKnown)(deps.fetch || fetch, podBase) !== true) {
-        throw needsIndex('Your profile names no public type index.');
-      }
-      skip('account', movingIn ? 'the pod already holds the account — its address moves here' : 'using the pod you already have');
-    }
-
-    // --- credential: the point of no return, and the durability boundary ---
-    let resumeWebId = null;
-    if (resuming) {
-      const rec = JSON.parse(fs.readFileSync(credPath, 'utf8'));
-      pod = rec.remotePod;
-      root = rec.root;
-      resumeWebId = rec.webId || null;
-      skip('credential', `already minted — ${credPath}`);
-    } else {
-      begin('credential');
-      // The WebID matters as much as the pod: an account with more than one
-      // pod has more than one, and a credential bound to the wrong one 403s
-      // every write. Account creation knows which; otherwise the pod's origin
-      // picks it out.
-      const credential = await mint({
-        origin: issuer, email, password, name: 'fedipod',
-        webId: accountWebId || undefined, podUrl: pod,
-      });
-      const rec = {
-        ...credential,
-        remotePod: pod.endsWith('/') ? pod : pod + '/',
-        createdAt: new Date().toISOString(),
-        ...(root ? { root } : {}),
-        ...(keys === 'pod' || movingIn ? { keysMode: 'pod' } : {}),
-        // Where the private half lives. Per-machine, like keysMode. A move-in
-        // keeps it on the pod, where the account already is, and says so.
-        ...(privateRoot ? { privateRoot } : {}),
-        ...(movingIn ? { stateOnPod: true } : {}),
-        // What shape this install is, so `upgrade` can tell an old one from a
-        // new one without guessing from the fields.
-        ...(isCurrent({ privateRoot, stateOnPod: movingIn }) ? { layout: CURRENT_LAYOUT } : {}),
-      };
-      fs.mkdirSync(home, { recursive: true, mode: 0o700 });
-      writeJsonAtomic(credPath, rec);
-      // The identity you just made is the one you are using, so it becomes what
-      // a plain command means. Here rather than earlier: the credential landing
-      // is what makes this an identity at all.
-      // NOT `root` — that name is already taken by the answers' AP container
-      // root, destructured above, and shadowing it is a temporal dead zone.
-      const apHomeRoot = rootOf(home);
-      if (apHomeRoot !== home) recordLastUsed(apHomeRoot, path.basename(home));
-      pod = rec.remotePod;
-      log(`credential minted and saved to ${credPath}`);
-      done('credential', credPath);
-    }
-
-    // --- a move-in: the account on the pod, read with the credential just
-    // minted, has to be one whose address lives at another gateway ---
-    if (movingIn) {
-      const cred = JSON.parse(fs.readFileSync(credPath, 'utf8'));
-      const account = await (deps.readPodAccount || readPodAccount)({ home, credential: cred, pod, root: root || DEFAULT_ROOT, log });
-      if (!account?.config) throw new Error('the pod holds an account, but its record could not be read with this credential — is this account the pod\'s owner?');
-      const frontActor = account.config.gateway?.frontActor || null;
-      const gwHost = new URL(gatewayOrigin).host;
-      if (!frontActor) throw new Error('The pod already hosts a FediPod account whose address lives on the pod: nothing to move. Sign in to it instead.');
-      if (new URL(frontActor).host === gwHost) throw new Error(`The pod already hosts a FediPod account at ${gwHost}: sign in to it instead of setting up again.`);
-      if ((account.config.kind || 'person') === 'group') throw new Error('a group cannot move between gateways');
-      if (!account.keys?.rsa || account.keys.ct) {
-        throw new Error(`this account's key is still under a password from an earlier version — sign in once at ${new URL(frontActor).host} first, then set up here`);
-      }
-      movedFrom = { actor: frontActor, gateway: new URL(frontActor).origin, handle: account.config.handle, at: new Date().toISOString() };
-      log(`moving @${account.config.handle}@${new URL(frontActor).host} here, as @${handle}@${gwHost}`);
-    }
-
-    // --- take an address at the Gateway, if this pod needs one or asked for
-    // one --- before bootstrap, so the config it writes carries the Gateway
-    // ids and the key connect mints below is stamped to the Gateway actor from
-    // the start. A signup-arranged gateway (the installer carry-over) wins.
-    let gatewayCfg = gateway;
-    if (!gatewayCfg && frontedAddress({ pod, shape })) {
-      if (kind === 'group') {
-        throw new Error(`a group needs a subdomained pod — a Gateway address for a group is not supported yet`
-          + (webfingerHost(pod) ? '' : `; ${pod} is suffixed`) + '.');
-      }
-      const urls = apUrls(pod, root || DEFAULT_ROOT);
-      const cred = JSON.parse(fs.readFileSync(credPath, 'utf8'));
-      log(`taking a gateway address at ${new URL(gatewayOrigin).host}`);
-      gatewayCfg = await attachGateway({
-        home, credential: cred, gatewayOrigin, handle,
-        podHome: urls.home, actorUrl: urls.actor, kind, log,
-      });
-      log(`gateway address @${handle}@${new URL(gatewayOrigin).host}`);
-    }
-
-    // --- provision the pod and bring federation up ---
-    begin('bootstrap');
-    // Resuming skipped the checks the fresh paths ran, and the credential it
-    // carries may be the one bound to a pod whose profile is empty — the write
-    // below would 401. Catch it here, as this step, with a sentence.
-    if (resuming) {
-      const ready = await checkPod(pod, { webId: resumeWebId || undefined });
-      if (!ready.ok) throw new Error(ready.error);
-    }
-    await agent.bootstrap({ handle, name: name || handle, root, kind, approveJoins, summary, icon, gateway: gatewayCfg });
-    if (movingIn && movedFrom) {
-      // The old actor becomes an alias, which is what a server checks on the
-      // new actor before it honours a Move; the Move itself is pending until
-      // the new actor is published (completeGatewayMove, below and at every
-      // start). The key stays; its stamp follows the actor.
-      const cfg = agent.store.getConfig() || {};
-      agent.store.setConfig({ ...cfg, aliases: [...new Set([...(cfg.aliases || []), movedFrom.actor])], movedFrom });
-      const keyRec = agent.store.read?.('keys.json', null);
-      if (keyRec?.mintedFor && gatewayCfg?.frontActor) agent.store.write?.('keys.json', { ...keyRec, mintedFor: gatewayCfg.frontActor });
-      await agent.store.flush();
-    }
-    done('bootstrap');
-
-    begin('connect');
-    // Direct, not connectWithRetry: setup wants to hear about a failure now,
-    // not back off for an hour with a browser tab waiting on it.
-    await agent.connect({ repair: false });          // publish below is the publish
-    done('connect');
-
-    begin('publish');
-    if (uiPassword) {
-      agent.store.setConfig({ ...agent.store.getConfig(), uiPassword: hashPassword(uiPassword) });
-    }
-    const published = await agent.publisher.publishProfile();
-    await agent.store.flush();
-    // Where the account lives, in the owner's public type index — made first
-    // if they said yes to one.
-    if (!movingIn) {
-      const urlsAt = apUrls(pod, root);
-      try {
-        await (deps.recordPlace || recordPlace)(agent.publisher?.remote || agent.remote, urlsAt.base, urlsAt.home + 'ap/actor', { create: !!createIndex });
-      } catch (e) {
-        throw new Error(`could not record where the account lives in your type index (${e.message})`);
-      }
-    }
-    if (movingIn) {
-      // Tell the old gateway and the followers. Not fatal: left pending, it
-      // is tried again when the agent next starts acting.
-      const moved = await (deps.completeGatewayMove || completeGatewayMove)(agent).catch((e) => { log(`gateway move: ${e.message}`); return null; });
-      if (moved?.completedAt) log(`Move sent from ${movedFrom.actor} to ${moved.moveSent} inbox(es)`);
-    }
-    done('publish');
-
-    // --- and say plainly whether the world can actually see it ---
-    begin('verify');
-    const unreachable = published?.unreachable || [];
-    const wfHost = webfingerHost(pod);
-    done('verify', unreachable.length
-      ? `not readable without credentials: ${unreachable.join(', ')}`
-      : 'the public surface is reachable');
-
-    // A fronted identity resolves at the Gateway, not the pod host.
-    const frontActor = gatewayCfg?.frontActor || agent.store.getConfig()?.gateway?.frontActor || null;
-    const gwHost = frontActor ? new URL(frontActor).host : null;
-    run.result = {
-      kind,
-      pod,
-      handle,
-      actor: agent.urls?.actor || null,
-      fronted: !!frontActor,
-      webfingerHost: gwHost || wfHost,
-      resolvable: !!(gwHost || wfHost),
-      address: gwHost ? `@${handle}@${gwHost}` : (wfHost ? `@${handle}@${wfHost}` : null),
-      unreachable,
-    };
-    run.phase = 'done';
-    log(wfHost
-      ? `${kind === 'group' ? 'group' : 'actor'} published: @${handle}@${wfHost}`
-      : `${kind === 'group' ? 'group' : 'actor'} published, but not reachable as a handle — `
-        + `${pod} is a suffixed pod`);
-  } catch (e) {
-    for (const s of run.steps) if (s.state === 'running') s.state = 'error';
-    run.error = scrub(e.message);
-    run.phase = 'error';
-    log(`setup failed: ${run.error}`);
-  }
-  return run;
-}

package/lib/device/update.mjs

@@ -1,96 +0,0 @@
-// update.mjs — is a newer FediPod published, and the update itself.
-//
-// "Latest" is the version field of package.json on the repo's main branch —
-// the same file a clone reads to know what it is running. The check is one
-// GET of that file; nothing else leaves the machine, and AP_UPDATE_CHECK=0
-// turns it off. The update is what re-running the installer does: fast-forward
-// the checkout, reinstall dependencies, restart the agents.
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { execFileSync, spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
-export const LATEST_URL = 'https://raw.githubusercontent.com/jeff-zucker/FediPod/main/package.json';
-
-export const repoRoot = () => path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
-
-export const localVersion = (root = repoRoot()) => {
-  try { return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version || null; }
-  catch { return null; }
-};
-
-// a newer than b, for dotted numeric versions.
-export const newerThan = (a, b) => {
-  const pa = String(a).split('.').map(Number);
-  const pb = String(b).split('.').map(Number);
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const d = (pa[i] || 0) - (pb[i] || 0);
-    if (d) return d > 0;
-  }
-  return false;
-};
-
-export async function checkLatest({ current = localVersion(), fetchImpl = fetch } = {}) {
-  if (process.env.AP_UPDATE_CHECK === '0') return null;
-  try {
-    const res = await fetchImpl(LATEST_URL, { signal: AbortSignal.timeout(10_000) });
-    if (!res.ok) return null;
-    const latest = (await res.json()).version || null;
-    if (!latest || !current) return null;
-    return { current, latest, available: newerThan(latest, current), checkedAt: new Date().toISOString() };
-  } 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 = () => {}, 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…');
-      install();
-      return { ok: true, note: 'updated from npm — restart the agent to serve it' };
-    } catch (e) {
-      return { ok: false,
-        note: `npm install -g fedipod@latest failed: ${String(e.stderr || e.message).slice(0, 300).trim()}` };
-    }
-  }
-  try {
-    execFileSync('git', ['-C', root, 'pull', '--ff-only'], { stdio: 'pipe' });
-  } catch (e) {
-    return { ok: false, note: `git pull refused: ${String(e.stderr || e.message).slice(0, 300).trim()}` };
-  }
-  try {
-    execFileSync('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], { cwd: root, stdio: 'pipe' });
-  } catch (e) {
-    return { ok: false, note: `npm install failed: ${String(e.stderr || e.message).slice(0, 300).trim()}` };
-  }
-  const version = localVersion(root);
-  log(`updated the checkout to ${version}`);
-  return { ok: true, note: `updated to ${version}`, version };
-}
-
-// New code runs only after a restart. Where systemd units exist they are all
-// restarted by name; otherwise the caller re-execs its own process.
-export function restartAgents({ log = () => {} } = {}) {
-  try {
-    const list = execFileSync('systemctl',
-      ['--user', 'list-units', '--plain', '--no-legend', 'fedipod-*'], { stdio: 'pipe' })
-      .toString().trim();
-    if (list) {
-      const child = spawn('systemctl', ['--user', 'restart', 'fedipod-*'], { detached: true, stdio: 'ignore' });
-      child.unref();
-      log('restarting the fedipod units');
-      return 'units';
-    }
-  } catch { /* no systemd here */ }
-  return 'self';
-}

package/lib/gateway/caches.mjs

@@ -1,36 +0,0 @@
-// caches.mjs — what one warm gateway process keeps between requests: the
-// pod-token verifier, and the public keys of the servers that deliver here.
-// Built per request, each costs round trips to somebody else's server for
-// every call; built once, a process pays them once.
-
-// The Solid-OIDC verifier remembers the issuers' key sets it has seen. A
-// fresh one per call re-read the caller's WebID document, the issuer's
-// discovery document and its keys on every signed-in call.
-let verifier = null;
-export async function podTokenVerifier() {
-  if (!verifier) verifier = (await import('@solid/access-token-verifier')).createSolidTokenVerifier();
-  return verifier;
-}
-
-// The keys deliveries are signed with, by key id, in the shape Fedify's
-// verifier asks for. A key is held an hour; a key that could not be fetched
-// is held five minutes, so a server that was down is asked again soon.
-// Fedify re-fetches on its own when a held key no longer verifies, so a
-// rotated key costs one failed check, not an hour of refused mail.
-const KEY_TTL_MS = 60 * 60_000;
-const MISS_TTL_MS = 5 * 60_000;
-const KEY_CACHE_MAX = 500;
-const keys = new Map();   // key id → { key, until }
-export const senderKeys = {
-  async get(keyId) {
-    const hit = keys.get(keyId.href);
-    if (!hit) return undefined;
-    if (hit.until < Date.now()) { keys.delete(keyId.href); return undefined; }
-    return hit.key;
-  },
-  async set(keyId, key) {
-    if (keys.size >= KEY_CACHE_MAX) keys.delete(keys.keys().next().value);
-    keys.set(keyId.href, { key, until: Date.now() + (key ? KEY_TTL_MS : MISS_TTL_MS) });
-  },
-  size: () => keys.size,
-};