fedipod-server 0.28.1 → 0.30.0

package/lib/device/migrate.mjs

@@ -1,115 +0,0 @@
-// Keeping every identity on this machine at the current shape of an install.
-//
-// bbba587 fixed the DEFAULT: a new install keeps its private half — timeline,
-// contacts, blocklist, notifications, masto-tokens.json — on this machine.
-// It did nothing for the installs that already existed, and `privateRoot`
-// absent still means "on the pod" (run-agent.mjs privateUrls). So an identity
-// set up before that commit still writes every state change to a pod, and
-// still keeps its private data on a server.
-//
-// A new default only ever fixes the installs that do not exist yet. That is the
-// reason this file exists rather than a one-off script: a change to install
-// shape ships as a numbered step HERE, and `fedipod upgrade` runs the
-// pending ones over every identity under the root, not just the one you
-// happened to be in.
-
-// Bump when a step is added, and add the step to pendingSteps below.
-export const CURRENT_LAYOUT = 1;
-
-// 0 is "never stamped", which is every install made before this file existed.
-// It is not the same as "wrong": an old install may already be in the right
-// shape, and pendingSteps is what decides, per step.
-export const layoutOf = (cred) => Number(cred?.layout) || 0;
-
-// Layout 1 — the private half lives on this machine.
-//
-// Only when `privateRoot` is ABSENT. An operator who pointed it somewhere
-// deliberately, with `--private-root`, has said where they want it; a migration
-// that overrode that would be moving data on its own initiative.
-export function needsStateMove(cred) {
-  // `stateOnPod` is a move-in from a browser account (setup.mjs): the state
-  // is on the pod because that is where the account already lives.
-  return !cred?.privateRoot && !cred?.stateOnPod;
-}
-
-export function pendingSteps(cred) {
-  const steps = [];
-  if (needsStateMove(cred)) {
-    steps.push({
-      id: 'state-off-pod',
-      what: 'move the private half off the pod, onto this machine',
-      why: 'receiving a post costs pod writes, and the timeline lives on a server',
-    });
-  }
-  return steps;
-}
-
-// True when there is nothing left to do and the stamp can be written.
-export const isCurrent = (cred) => pendingSteps(cred).length === 0;
-
-// The documents on the pod that the state tree consists of — everything the
-// move copied. Deliberately NOT "everything in the container":
-//
-//   lease.json stays. It is the single-active-agent lock, and it is on the pod
-//   precisely BECAUSE the private half is not: a lease only one machine can
-//   reach coordinates nothing. run-agent builds it from urls.state, never from
-//   privateRoot, so it goes on being used after the move.
-//
-//   .keep and .acl belong to the container, which also stays — the container is
-//   what carries the owner-only ACL that lease.json sits behind.
-//
-// RemotePod.delete's deny-list is the backstop under all of this; this list is
-// what we affirmatively claim, and the two disagreeing is a bug worth hearing
-// about rather than a file quietly surviving.
-export const MOVED_STATE_DOCS = new Set([
-  'config.json', 'queue.json', 'blocklist.json', 'contacts.json', 'muted.json',
-  'pending.json', 'requests.json', 'deadletter.json', 'statuses.json',
-  'notifications.json', 'media.json', 'actors.json', 'ids.json', 'published.json',
-  'outbox.json', 'outbox-removed.json', 'parked.json', 'tagfeed.json',
-  'intake-attempts.json', 'inbox-channel.json', 'masto-tokens.json', 'masto-markers.json',
-  'lists.json', 'filters.json', 'scheduled.json', 'webpush.json',
-  'import-state.json',
-  // Present only in pod-keys mode; a state move must carry it or the moved
-  // store cannot sign.
-  'keys.json',
-]);
-
-export const KEPT_ON_POD = new Set(['lease.json', '.keep']);
-
-// What `state --drop-remote` would remove, given a container listing. Split out
-// so the decision can be tested without a pod, and so the caller can show it
-// before doing anything.
-export function classifyRemoteState(urls, base) {
-  const drop = [];
-  const keep = [];
-  for (const u of urls) {
-    const name = String(u).slice(String(base).length).replace(/^\/+/, '');
-    if (!name || name.includes('/')) { keep.push({ url: u, name, why: 'not a document of this container' }); continue; }
-    if (KEPT_ON_POD.has(name)) {
-      keep.push({ url: u, name, why: name === 'lease.json' ? 'the lease stays on the pod by design' : 'the container needs it' });
-    } else if (MOVED_STATE_DOCS.has(name)) {
-      drop.push({ url: u, name });
-    } else {
-      keep.push({ url: u, name, why: 'not one of ours' });
-    }
-  }
-  return { drop, keep };
-}
-
-// Copy the private half — every state document — from one storage to the
-// other. Copy and verify only: nothing is repointed and nothing is deleted, so
-// a failure part-way leaves the source authoritative.
-// Used by both `state --to` and the record page's Move private data.
-export async function copyPrivateHalf({ from, to, log = () => {} }) {
-  const { PodStore } = await import('../core/store.mjs');
-  const src = new PodStore({ log: () => {} });
-  src.attach(from.state);
-  await src.load();
-  const dst = new PodStore({ log });
-  dst.attach(to.state);
-  for (const [name, value] of src.cache) dst.write(name, value);
-  if (!await dst.commit()) {
-    throw new Error('some state documents did not land — nothing was repointed, nothing was deleted');
-  }
-  return { docs: src.cache.size };
-}

package/lib/device/ports.mjs

@@ -1,27 +0,0 @@
-// ports.mjs — finding a port nothing else is on.
-//
-// This lived twice, in bin/fedipod.mjs and lib/admin.mjs, and the two
-// copies had already drifted: one returned null when it ran out of ports and
-// the other threw. Both spawn agents, so which one you got decided whether a
-// full range produced an error message or a silent undefined.
-
-import net from 'node:net';
-
-// Bind to find out. Something holding a port without answering HTTP reads as
-// free to a probe that only asks for a response, and the new agent then dies on
-// EADDRINUSE with nobody watching.
-export function portFree(port) {
-  return new Promise((resolve) => {
-    const probe = net.createServer();
-    probe.once('error', () => resolve(false));
-    probe.once('listening', () => probe.close(() => resolve(true)));
-    probe.listen(port, '127.0.0.1');
-  });
-}
-
-// null when the whole span is taken. Callers that want an error say so in their
-// own words — the CLI has a person reading it, the admin API has a status code.
-export async function freePortFrom(first, span = 50) {
-  for (let p = first; p < first + span; p++) if (await portFree(p)) return p;
-  return null;
-}

package/lib/device/remote.mjs

@@ -1,54 +0,0 @@
-// remote.mjs — the Node agent's pod transport: CSS client-credentials + DPoP
-// (vendor/idp-grant.cjs, extracted from data-kitchen's "remember this IdP"
-// machinery — plain Node, no Electron).
-//
-// Everything about talking to a pod — the verbs, the ACL documents, the
-// deletion deny-list, the Retry-After cooldown, the container listing — lives
-// in lib/pod/transport.mjs, which knows nothing about Node and is shared with
-// the browser. What is left here is the one thing that genuinely differs: how
-// the session is obtained. That top-level `require` of the vendor grant is also
-// exactly why the split exists — it cannot be bundled for a service worker.
-
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { PodTransport } from '../pod/transport.mjs';
-
-const require = createRequire(import.meta.url);
-const vendorDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../vendor');
-const { mintCredential, discoverTokenEndpoint, createGrantSession, revokeCredentialViaAccount } =
-  require(path.join(vendorDir, 'idp-grant.cjs'));
-
-export { mintCredential, discoverTokenEndpoint, revokeCredentialViaAccount };
-
-// Re-exported so the callers that guard their own deletions — run-agent, the
-// server package's live test, the smoke suite — keep importing it from here.
-export { protectedFromDeletion } from '../pod/transport.mjs';
-
-export class RemotePod extends PodTransport {
-  constructor(credential, { log = () => {}, home = null, session = null, role = 'agent' } = {}) {
-    // An injected session replaces the credential-backed one, and everything
-    // above it — the cooldown, the deny-list, the url map — is unchanged. That
-    // is how the agent runs inside a pod server: same class, no token to mint.
-    super(session || createGrantSession(credential, home ? {
-      backoffFile: path.join(home, 'backoff.json'),
-      tokenFile: path.join(home, 'token.json'),
-    } : {}), {
-      webId: credential.webId,
-      log,
-      role,
-      runtime: 'node',
-      // Fail fast for the window rather than sleeping it out: a daemon has
-      // timers behind it, and a request that waits is a timer that does not
-      // fire. The callers' existing retry paths take it from there.
-      cooldownMode: 'refuse',
-    });
-  }
-
-  async warmup() { return this.session.warmup(); }
-
-  /** The grant's own counters, under the transport's. */
-  stats() {
-    return { ...(this.session.stats?.() || {}), ...super.stats() };
-  }
-}

package/lib/device/setup.mjs

@@ -1,459 +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';
-
-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',
-  } = answers;
-  let { pod, root } = answers;
-  if (!root) root = 'fedipod/';   // new installs default to the fedipod/ container; 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');
-      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 suffix-based host, `
-          + 'not a host root. WebFinger is only answered at a host root, so nobody '
-          + 'could find this group. The pod exists; no actor was published.');
-      }
-      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 held = await (deps.resourceExists || resourceExists)(deps.fetch || fetch, apUrls(pod, root || DEFAULT_ROOT).actor);
-      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; }
-      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 pod at its own host — a Gateway address for a group is not supported yet`
-          + (webfingerHost(pod) ? '' : `; ${pod} is a suffix-based host`) + '.');
-      }
-      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();
-    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 not a host root`);
-  } 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;
-}