fedipod-server 0.11.0 → 0.13.0

package/lib/server/embed.mjs

@@ -0,0 +1,405 @@
+// embed.mjs — the agent, running inside the pod server that holds its pod.
+//
+// Nothing here reimplements the agent: it is the same Agent class, the same
+// intake, deliverer, publisher and lease. What changes is the transport. The
+// caller hands in a session that reaches the pod through the server's own
+// store, and RemotePod takes it instead of minting a credential — so an
+// identity acts on its pod with no token, no socket, and no second process.
+//
+// The one thing a pod server can do that a laptop cannot is notice a write the
+// moment it happens, so the notification socket is replaced by the store's own
+// change events.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { createRequire } from 'node:module';
+
+import { Agent } from '../../run-agent.mjs';
+import { RemotePod } from '../device/remote.mjs';
+import { apUrls, DEFAULT_ROOT } from '../core/wire.mjs';
+import { handleDelivery } from '../gateway/gateway-core.mjs';
+import { writeJsonAtomic } from '../device/home.mjs';
+import { buildAdminSurface } from '../device/admin/index.mjs';
+import { FixedAuthorities } from '../shared/guard.mjs';
+import { CONNECTION_PREFIX, fileVault, moveVault, podVault } from '../connections/vault.mjs';
+
+const require = createRequire(import.meta.url);
+const { makeGate } = require('../../vendor/gate.cjs');
+
+// How long to gather store events before draining, so a delivery of several
+// items costs one sweep rather than one each.
+const DRAIN_COALESCE_MS = 250;
+
+// How every secret in this project is minted (the attach flow's recipe).
+const mintSecret = () => crypto.randomBytes(32).toString('base64');
+
+/**
+ * The secret guarding one identity's owner door, kept in its pod's state
+ * beside its signing key. Minted when absent; `rotate` re-mints over an
+ * existing one — which is how a lost secret is recovered, by proving pod
+ * control again. Never logged.
+ *
+ * `dataDir`, when given, is where an identity set up before this kept it: the
+ * secret is moved into the pod and the host's copy removed, so the owner's
+ * existing door link goes on working.
+ */
+export async function ensureDoorSecret(session, podBase, { rotate = false, dataDir = null, handle = null, log = () => {} } = {}) {
+  const base = podBase.endsWith('/') ? podBase : podBase + '/';
+  const url = apUrls(base, DEFAULT_ROOT).state + 'door-secret.json';
+  const onHost = dataDir && handle ? path.join(dataDir, handle, 'door-secret.json') : null;
+
+  if (!rotate) {
+    const res = await session.fetch(url, { headers: { accept: 'application/json' } })
+      .catch(() => ({ ok: false }));
+    if (res.ok) {
+      try {
+        const rec = JSON.parse(await res.text());
+        if (rec?.secret) {
+          if (onHost) fs.rmSync(onHost, { force: true });
+          return { secret: rec.secret, url, rotated: false };
+        }
+      } catch { /* unreadable: mint below */ }
+    }
+    // Set up before the secret lived on the pod: keep the one the owner has.
+    if (onHost && fs.existsSync(onHost)) {
+      try {
+        const rec = JSON.parse(fs.readFileSync(onHost, 'utf8'));
+        if (rec?.secret && await putSecret(session, url, rec)) {
+          fs.rmSync(onHost, { force: true });
+          log('door secret moved into the pod');
+          return { secret: rec.secret, url, rotated: false };
+        }
+      } catch { /* unreadable: mint below */ }
+    }
+  }
+
+  const rec = { secret: mintSecret(), mintedAt: new Date().toISOString() };
+  if (await putSecret(session, url, rec)) {
+    if (onHost) fs.rmSync(onHost, { force: true });
+    return { secret: rec.secret, url, rotated: rotate };
+  }
+  // The pod would not take it. Opting in must not fail for that: a pod that
+  // cannot be written to right now is a pod whose owner still asked for an
+  // identity, and the secret has somewhere else to live — where it lived
+  // before. The next start moves it onto the pod.
+  if (onHost) {
+    writeJsonAtomic(onHost, rec, { mode: 0o600 });
+    log(`the pod would not take the door secret; it is on this host at ${onHost} for now`);
+    return { secret: rec.secret, url: onHost, rotated: rotate };
+  }
+  throw new Error(`could not write the door secret to ${url}, and there is no directory to keep it in`);
+}
+
+async function putSecret(session, url, rec) {
+  try {
+    const res = await session.fetch(url, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(rec, null, 2) + '\n',
+    });
+    return res.ok;
+  } catch {
+    // A store that throws rather than answering is a store that did not take
+    // it, which is the same answer.
+    return false;
+  }
+}
+
+/** The identity's name: a subdomain pod is its label, a path pod its last segment. */
+export function handleFor(podBase) {
+  const u = new URL(podBase);
+  const segments = u.pathname.split('/').filter(Boolean);
+  return segments.length ? segments[segments.length - 1] : u.hostname.split('.')[0];
+}
+
+/**
+ * The credential file an embedded identity runs on. It names the pod and
+ * nothing else: there is no client id and no secret, because there is nobody
+ * to authenticate to. Absent `privateRoot`, so the state tree stays on the pod.
+ *
+ * `keysMode: 'pod'` because here the pod's server and the agent are the same
+ * process: keeping the signing key on the host's disk puts it somewhere the
+ * pod does not travel to, so handing the pod over hands over an identity that
+ * cannot sign. An identity set up before this gets the mode added.
+ */
+function ensureCredential(home, { podBase, webId }) {
+  const file = path.join(home, 'credential.json');
+  try {
+    const rec = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (rec.keysMode === 'pod') return rec;
+    const updated = { ...rec, keysMode: 'pod' };
+    writeJsonAtomic(file, updated, { mode: 0o600 });
+    return updated;
+  } catch { /* first run for this identity */ }
+  const rec = {
+    webId,
+    remotePod: podBase.endsWith('/') ? podBase : podBase + '/',
+    root: 'activitypods-js/',
+    keysMode: 'pod',
+  };
+  writeJsonAtomic(file, rec, { mode: 0o600 });
+  return rec;
+}
+
+/**
+ * Move an identity's signing key off the host's disk and into its pod.
+ *
+ * Only after the pod has it: the private key is the one thing here that
+ * nothing can rebuild, and remote servers have its public half cached, so a
+ * copy lost between the two places is an identity that can never sign again
+ * under the name it already published.
+ */
+async function keyIntoPod(agent, home, log) {
+  const local = path.join(home, 'keys.json');
+  if (!fs.existsSync(local)) return;
+  if (agent.store.read('keys.json', null)) {
+    fs.rmSync(local, { force: true });
+    log('this identity signs with the key in its pod; removed the copy on this host');
+    return;
+  }
+  let rec;
+  try {
+    rec = JSON.parse(fs.readFileSync(local, 'utf8'));
+  } catch (e) {
+    log(`the local signing key could not be read (${e.message}) — leaving it where it is`);
+    return;
+  }
+  agent.store.write('keys.json', rec);
+  if (!await agent.store.commit()) {
+    log('could not write the signing key to the pod — it stays on this host for now');
+    return;
+  }
+  fs.rmSync(local, { force: true });
+  log('signing key moved into the pod');
+}
+
+/**
+ * Move an identity's credentials for accounts it holds on OTHER servers off
+ * the host's disk and into its pod. A token here is full access to somebody's
+ * account on a server this project does not run, so the host's copy goes only
+ * after the pod has taken it.
+ */
+async function connectionsIntoPod(agent, home, log) {
+  const moves = [
+    [fileVault(path.join(home, 'fediaccts')), podVault(agent.store, `${CONNECTION_PREFIX}fedi-`)],
+    [fileVault(path.join(home, 'fediaccts', '_apps')), podVault(agent.store, `${CONNECTION_PREFIX}fediapp-`)],
+    [fileVault(home), podVault(agent.store, CONNECTION_PREFIX)],
+  ];
+  // The last pair is the whole home directory, where only the Bluesky
+  // credential is ours to move.
+  for (const [from, to] of moves.slice(0, 2)) await moveVault(from, to, log);
+  const bluesky = moves[2][0].read('atproto');
+  if (bluesky && !moves[2][1].read('bluesky')) {
+    moves[2][1].write('bluesky', bluesky);
+    if (await moves[2][1].commit()) {
+      await moves[2][0].remove('atproto');
+      log('the Bluesky connection moved into the pod');
+    } else {
+      log('could not write the Bluesky connection to the pod — it stays on this host for now');
+    }
+  }
+}
+
+/**
+ * The pod's own inbox is a verifying door here.
+ *
+ * The server that stores the inbox is the server the delivery arrives at, so
+ * the signature is checked while the headers still exist and the receipt is
+ * written beside the activity — the same door code a standalone gateway runs,
+ * with nothing renamed and nothing advertised differently. The identity's
+ * config names its own inbox as the door and carries the receipt secret, which
+ * is what makes the drain read receipts at all; `trust` because a verified
+ * sender is one the identity may act for.
+ *
+ * An identity attached to an outside door keeps that door: only the secret
+ * is ensured, so receipts from either door verify against the one value.
+ */
+export async function ensureInboxDoor(agent, urls, log = () => {}) {
+  const cfg = agent.store.getConfig();
+  if (!cfg) return;
+  const g = { ...(cfg.gateway || {}) };
+  const fresh = !g.url || !g.mode || g.mode === 'off';
+  if (fresh) Object.assign(g, { url: urls.inbox, mode: 'trust' });
+  if (!g.hmacSecret) g.hmacSecret = crypto.randomBytes(32).toString('base64');
+  if (fresh || !cfg.gateway?.hmacSecret) {
+    agent.store.setConfig({ ...cfg, gateway: g });
+    await agent.store.flush();
+    log(fresh ? 'the pod inbox verifies deliveries at the door' : 'receipt secret added for the inbox door');
+  }
+}
+
+/**
+ * One delivery to a running identity's inbox, verified at the door.
+ *
+ * `request` is the WHATWG form of the POST. `podPut` writes through the
+ * server's store. Returns { status, reason } for the caller to answer with.
+ * The policy is read from the identity's live state rather than its
+ * published policy document, because both are in this process.
+ */
+export async function deliverToInbox(agent, request, { podPut, gatewayWebId = null, fetchImpl = fetch } = {}) {
+  const cfg = agent.store.getConfig() || {};
+  const contacts = agent.store.getContacts();
+  const bl = agent.store.getBlocklist();
+  const u = agent.urls;
+  const toPod = (x) => (u.toPod ? u.toPod(x) : x);
+  const ident = {
+    inboxUrl: toPod(u.inbox),
+    actorUrl: u.actor,
+    followersUrl: u.followers,
+    notesPrefix: u.notes,
+    following: contacts.following.filter((f) => f.accepted && !f.bsky).map((f) => f.actor),
+    blocklist: { domains: bl.domains || [], actors: bl.actors || [] },
+    kind: cfg.kind || 'person',
+    gatewayWebId,
+    hmacSecret: cfg.gateway?.hmacSecret || null,
+  };
+  return handleDelivery(request, ident, { podPut, fetchImpl });
+}
+
+/**
+ * Bring one identity up inside the server.
+ *
+ * `session` is the store-backed transport ({ fetch, warmup, stats }).
+ * `resourceStore` is optional and used only to watch for inbox writes.
+ * Returns the running agent and a stop() that leaves the pod tidy.
+ */
+export async function startEmbeddedAgent({
+  podBase,
+  dataDir,
+  session,
+  resourceStore = null,
+  webIdSuffix = 'profile/card#me',
+  log = () => {},
+  pollSeconds = null,
+  autoAcceptFollows = true,
+  gateToken = null,
+  uiPath = '/fedipod/',
+}) {
+  const base = podBase.endsWith('/') ? podBase : podBase + '/';
+  const handle = handleFor(base);
+  const home = path.join(dataDir, handle);
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+
+  const webId = base + webIdSuffix.replace(/^\//u, '');
+  const cred = ensureCredential(home, { podBase: base, webId });
+
+  const agent = new Agent({ home, log });
+  agent.log = log;
+  agent.store.log = log;
+  // Read by connect() when it builds Intake: in-process, the pod's own change
+  // events are the push channel.
+  agent.embedded = true;
+  if (pollSeconds) agent.pollSeconds = pollSeconds;
+  agent.remote = new RemotePod(cred, { log, session });
+  await agent.remote.warmup();
+
+  // Whether this pod already carries an identity is the question connect()
+  // assumes an answer to, so settle it first.
+  const urls = apUrls(cred.remotePod, cred.root);
+  agent.store.attach(agent.privateStorage(cred, 'state', urls));
+
+  // A state container that is NOT THERE means a pod nobody has set up yet. A
+  // state container we could not READ means a pod we could not ask, which is a
+  // different answer: treating it as empty would provision a second identity
+  // over the top of a working one.
+  const state = await agent.remote.fetch(urls.state, { headers: { accept: 'text/turtle' } });
+  const unprovisioned = state.status === 404 || state.status === 410;
+  if (!unprovisioned && state.status >= 400) {
+    throw new Error(`state at ${urls.state} → ${state.status} — cannot tell whether this pod is set up`);
+  }
+  if (!unprovisioned) {
+    await agent.store.load();
+    agent.stateLoaded = true;
+  }
+
+  if (!agent.store.getConfig()) {
+    // The pod itself must exist first. A server creates its seeded pods after
+    // it runs its initializers, so an agent that provisioned eagerly would
+    // leave a container tree exactly where a pod is about to be created.
+    const profile = await agent.remote.fetch(webId.split('#')[0], { headers: { accept: 'text/turtle' } });
+    if (profile.status === 404 || profile.status === 410) {
+      throw new Error(`no pod at ${base} yet — its owner profile is not there`);
+    }
+    log(`no identity on ${base} yet — provisioning @${handle}`);
+    await agent.bootstrap({ handle, name: handle, kind: 'person' });
+    if (autoAcceptFollows) {
+      agent.store.setConfig({ ...agent.store.getConfig(), autoAcceptFollows: true });
+      await agent.store.flush();
+    }
+    agent.stateLoaded = true;
+  }
+
+  // Before connect(), which is what looks the key and the connections up.
+  await keyIntoPod(agent, home, log);
+  await connectionsIntoPod(agent, home, log);
+  await ensureInboxDoor(agent, urls, log);
+
+  await agent.connect();
+
+  // The client surfaces, on the pod's own origin: the Mastodon API a phone app
+  // speaks, the write API, nodeinfo, and behind the door the admin routes and
+  // the web client. Same code the standalone agent serves, minus the routes
+  // that only mean something to a process of one's own.
+  const authorities = new FixedAuthorities(base);
+  agent.authorities = authorities;
+  const surface = buildAdminSurface({
+    agent,
+    log,
+    gate: makeGate(gateToken, { secureCookie: authorities.secure }),
+    allowed: authorities,
+    embedded: true,
+    basePath: uiPath,
+    publicOrigin: base,
+    scheme: new URL(base).protocol,
+  });
+
+  // A delivery landing in the inbox — through the door, or from any other
+  // writer — wakes the drain at once. Only additions, and only in the inbox:
+  // the drain's own DELETEs must not call it back.
+  let coalesce = null;
+  let onChanged = null;
+  if (typeof resourceStore?.on === 'function') {
+    const inbox = urls.inbox;
+    onChanged = (identifier, activity) => {
+      const kind = String(activity?.value ?? activity ?? '');
+      if (!identifier?.path?.startsWith(inbox)) return;
+      if (!kind.endsWith('Create') && !kind.endsWith('Add')) return;
+      if (coalesce) return;
+      coalesce = setTimeout(() => {
+        coalesce = null;
+        if (!agent.viewer) agent.intake?.drain().catch((e) => log(`drain: ${e.message}`));
+      }, DRAIN_COALESCE_MS);
+      coalesce.unref?.();
+    };
+    resourceStore.on('changed', onChanged);
+  }
+
+  const stop = async () => {
+    if (onChanged) resourceStore.off('changed', onChanged);
+    surface.streaming?.stop?.();
+    clearTimeout(coalesce);
+    agent.intake?.stop();
+    agent.tagfeed?.stop();
+    agent.bskyfeed?.stop();
+    agent.deliverer?.stop();
+    agent.importer?.stop();
+    clearInterval(agent.schedTimer);
+    clearInterval(agent.refreshTimer);
+    agent.publisher?.stopPolls();
+    // Same order the standalone agent's shutdown uses: write what is pending,
+    // then let go of the lease so the next agent need not wait out the TTL.
+    await Promise.allSettled([
+      agent.store.flush(),
+      agent.viewer ? Promise.resolve() : agent.lease?.release(),
+    ]);
+  };
+
+  // podHome and actorUrl are the identity's own locations on the pod. They are
+  // returned rather than rebuilt by the caller so the root name lives here.
+  return {
+    agent, handle, home, surface, host: authorities.host,
+    podHome: urls.home, actorUrl: urls.actor, inboxUrl: urls.inbox, stop,
+  };
+}

package/lib/{links.mjs → shared/links.mjs}

@@ -6,4 +6,4 @@
 // importers around the project do not move, and so there is still one obvious
 // place to look for "how does this read a Link header".
 
-export { linkTargets, REL } from './pod/links.mjs';
+export { linkTargets, REL } from '../pod/links.mjs';

package/lib/{ua.mjs → shared/ua.mjs}

@@ -16,7 +16,7 @@ import { fileURLToPath } from 'node:url';
 let version = '0';
 try {
   ({ version } = JSON.parse(fs.readFileSync(
-    path.join(path.dirname(fileURLToPath(import.meta.url)), '../package.json'), 'utf8')));
+    path.join(path.dirname(fileURLToPath(import.meta.url)), '../../package.json'), 'utf8')));
 } catch {
   try {
     ({ version } = JSON.parse(fs.readFileSync(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fedipod-server",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "The FediPod Server: a full ActivityPub server as a Community Solid Server component.",
   "license": "MIT",
   "main": "dist/index.js",

package/run-agent.mjs

@@ -28,28 +28,29 @@ import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
-import { PodStore } from './lib/store.mjs';
-import { apRoot, rootOf, writeJsonAtomic } from './lib/home.mjs';
-import { ensureTrustedTls } from './lib/certs.mjs';
-import { storageFor } from './lib/storage.mjs';
-import { resolveKeys } from './lib/keys.mjs';
-import { RemotePod } from './lib/remote.mjs';
-import { Deliverer } from './lib/deliver.mjs';
-import { Publisher } from './lib/publisher.mjs';
-import { Intake } from './lib/intake.mjs';
-import { TagFeed } from './lib/tagfeed.mjs';
-import { ImportWorker } from './lib/import.mjs';
-import { Atproto } from './lib/atproto.mjs';
-import { FediAccounts } from './lib/fediacct.mjs';
-import { AcctFeed } from './lib/acctfeed.mjs';
-import { BskyFeed } from './lib/bskyfeed.mjs';
-import { BskyGroup } from './lib/bskygroup.mjs';
-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, assertionKeyId , publicHandle } from './lib/wire.mjs';
-import { followActor, unfollowActor, resolveHandle } from './lib/social.mjs';
+import { PodStore } from './lib/core/store.mjs';
+import { apRoot, rootOf, writeJsonAtomic } from './lib/device/home.mjs';
+import { ensureTrustedTls } from './lib/device/certs.mjs';
+import { storageFor } from './lib/core/storage.mjs';
+import { resolveKeys } from './lib/core/keys.mjs';
+import { RemotePod } from './lib/device/remote.mjs';
+import { Deliverer } from './lib/core/deliver.mjs';
+import { Publisher } from './lib/core/publisher/index.mjs';
+import { Intake } from './lib/core/intake/index.mjs';
+import { TagFeed } from './lib/connections/tagfeed.mjs';
+import { ImportWorker } from './lib/connections/import.mjs';
+import { Atproto } from './lib/connections/atproto.mjs';
+import { FediAccounts } from './lib/connections/fediacct.mjs';
+import { vaultsFor } from './lib/connections/vault.mjs';
+import { AcctFeed } from './lib/connections/acctfeed.mjs';
+import { BskyFeed } from './lib/connections/bskyfeed.mjs';
+import { BskyGroup } from './lib/connections/bskygroup.mjs';
+import { Lease } from './lib/core/lease.mjs';
+import { startAdmin } from './lib/device/admin/index.mjs';
+import { exposureProblem, hostLabel } from './lib/shared/guard.mjs';
+import { pendingSteps } from './lib/device/migrate.mjs';
+import { apUrls, assertionKeyId , publicHandle } from './lib/core/wire.mjs';
+import { followActor, unfollowActor, resolveHandle } from './lib/core/social.mjs';
 
 export class Agent {
   constructor({ home, log }) {
@@ -344,13 +345,20 @@ export class Agent {
     // The CSV-import worker: paced, resumable, armed only while active.
     this.importer?.stop();
     this.importer = new ImportWorker({ agent: this, log: this.log });
+    // Where the credentials for accounts held on OTHER servers are kept.
+    const vaults = vaultsFor({ embedded: this.embedded, home: this.home, store: this.store });
     // The Bluesky connection, when one exists. Stamped to this actor; a
     // credential connected for another identity is treated as absent.
-    this.atproto = new Atproto({ localDir: this.home, actorId: this.urls.actor, log: this.log });
+    this.atproto = new Atproto({
+      localDir: this.home, actorId: this.urls.actor, log: this.log, vault: vaults.bluesky,
+    });
     this.publisher.atproto = this.atproto;
     // Fediverse accounts the owner holds elsewhere. Same custody rules as the
     // Bluesky credential, and the same absence when stamped for someone else.
-    this.fediaccts = new FediAccounts({ localDir: this.home, actorId: this.urls.actor, log: this.log });
+    this.fediaccts = new FediAccounts({
+      localDir: this.home, actorId: this.urls.actor, log: this.log,
+      vault: vaults.fedi, apps: vaults.apps,
+    });
     this.acctfeed?.stop();
     this.acctfeed = null;
     this.bskyfeed?.stop();
@@ -773,7 +781,7 @@ export async function startAgent({
   // Is a newer FediPod published? Once at boot and daily after; the answer
   // rides /status and the record page offers the update.
   const updateTick = async () => {
-    const { checkLatest } = await import('./lib/update.mjs');
+    const { checkLatest } = await import('./lib/device/update.mjs');
     const u = await checkLatest();
     if (u) {
       agent.updateInfo = u;

package/web/admin/actors.js

@@ -0,0 +1,145 @@
+// actors.js — the other actors on this machine: the picker, going to one,
+// starting a stopped one, and the form for a new one.
+
+// Somewhere to go, and nothing else. A stopped actor is left out — the link
+// would land on nothing. The one you are on keeps its place in the row but
+// offers only `app`, because its admin page is the page you are reading.
+
+let actors = [];
+
+async function renderOthers() {
+  const { json } = await api('/profiles');
+  actors = json?.identities || [];
+  const sel = $('actor-pick');
+  sel.textContent = '';
+  // The fediverse address, which is what the actor IS to everyone else, and the
+  // only form that stays distinct: two identities can share a local handle, but
+  // never a handle AND a pod. A stopped one has no address to report — nothing
+  // answered — so it falls back to the name it is filed under.
+  const label = (r) => (r.address || r.handle || r.name)
+    + (r.mode && r.mode !== 'active' ? ` (${r.mode})` : '') + (r.mode ? '' : ' (stopped)');
+  const seen = {};
+  for (const r of actors) seen[label(r)] = (seen[label(r)] || 0) + 1;
+
+  for (const [i, r] of actors.entries()) {
+    const o = document.createElement('option');
+    o.value = String(i);
+    o.selected = !!r.current;      // it opens showing where you already are
+    o.textContent = label(r) + (seen[label(r)] > 1 && r.port ? ` :${r.port}` : '');
+    sel.appendChild(o);
+  }
+  // The way to a NEW actor rides the same dropdown as the existing ones.
+  const add = document.createElement('option');
+  add.value = '__add';
+  add.textContent = '+ add a new account…';
+  sel.appendChild(add);
+}
+
+// Going to an actor commits a navigation and, for a stopped one, a POST that
+// boots its pod — so it must run once per choice. Pressing Enter on the select
+// fires BOTH a keydown (handled below) and a native `change`, so without a
+// guard a keyboard commit would start the actor twice.
+let goingToActor = false;
+const goToActor = async () => {
+  if (goingToActor) return;
+  if ($('actor-pick').value === '__add') { renderOthers(); openNewActor(); return; }
+  const r = actors[Number($('actor-pick').value)];
+  if (!r || r.current) return;
+  goingToActor = true;
+  try {
+    if (r.mode) { location.href = r.admin; return; }
+    $('actor-pick').disabled = true;
+    say(`starting ${r.name}`);
+    const started = await write('/start-actor', { name: r.name }, `${r.name} is up`);
+    $('actor-pick').disabled = false;
+    if (started?.url) location.href = `${started.url}admin/`;
+    else renderOthers();            // put the picker back on the current actor
+  } finally {
+    goingToActor = false;
+  }
+};
+// Choosing one goes to its record, as it always has.
+//
+// Arrowing is the one case that must not: on a closed select every Arrow
+// keypress fires `change`, so a keyboard user browsing the list would be
+// carried off to the first actor they passed — and for a stopped one that
+// boots its pod. An arrow key arms a flag and the change it causes is ignored;
+// Enter commits. A mouse never sets the flag, so clicking behaves as before.
+let arrowing = false;
+$('actor-pick').addEventListener('keydown', (ev) => {
+  if (['ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown'].includes(ev.key)) arrowing = true;
+  if (ev.key === 'Enter') { arrowing = false; goToActor(); }
+});
+$('actor-pick').addEventListener('pointerdown', () => { arrowing = false; });
+$('actor-pick').addEventListener('change', () => {
+  if (!arrowing) goToActor();
+  arrowing = false;
+});
+
+// Setting up a new actor asks for exactly what this page cannot already tell
+// it: the pod and the account behind it, and its permanent name. Display name,
+// bio and pictures are the client's job now — Phanpy's profile editor writes
+// them through /api/v1/accounts/update_credentials. Where the private data goes
+// is not a question either: it lands beside the credential, and `state --to`
+// moves it afterwards.
+
+const picked = (name) => document.querySelector(`input[name=${name}]:checked`)?.value;
+
+function newActorRows() {
+  const mode = picked('newMode');
+  $('new-row-podname').hidden = mode !== 'new';
+  $('new-row-pod').hidden = mode !== 'existing';
+}
+for (const el of document.querySelectorAll('input[name=newMode]')) {
+  el.addEventListener('change', newActorRows);
+}
+
+// While the form is up the page IS the new actor's setup — so the record of
+// the actor you came from goes away, list included. Which panes were showing
+// is remembered rather than recomputed: whether Group and Inbox belong is a
+// decision render() already made.
+const RECORD_PANES = ['pane-identity', 'pane-group', 'pane-inbox', 'rail'];
+let putBack = [];
+
+function showNewActor(on) {
+  if (on) closePanels();              // nothing of the old actor left open behind it
+  document.body.classList.toggle('adding', on);   // see body.adding in the CSS
+  $('new-actor-form').hidden = !on;
+  if (on) {
+    putBack = RECORD_PANES.filter(id => !$(id).hidden);
+    for (const id of putBack) $(id).hidden = true;
+  } else {
+    for (const id of putBack) $(id).hidden = false;
+    putBack = [];
+  }
+}
+
+// `add a new account` is the last item of the Local Actors dropdown; choosing
+// it opens the form in place. Arriving with ?new does the same.
+function openNewActor() {
+  showNewActor(true);
+  newActorRows();
+  $('new-handle').focus();
+}
+$('new-actor-cancel').addEventListener('click', () => { showNewActor(false); say('nothing changed'); });
+
+$('new-actor-form').addEventListener('submit', async (ev) => {
+  ev.preventDefault();
+  const handle = $('new-handle').value.trim();
+  const answers = {
+    handle,
+    kind: picked('newKind'),
+    mode: picked('newMode'),
+    issuer: $('new-issuer').value.trim(),
+    email: $('new-email').value.trim(),
+    password: $('new-password').value,
+  };
+  if (answers.mode === 'new') answers.podName = $('new-podname').value.trim() || handle;
+  else answers.pod = $('new-pod').value.trim();
+  $('new-actor-go').disabled = true;
+  say(`setting up ${handle || 'the new actor'} — this takes a while`);
+  const r = await write('/new-actor', answers, `setting up ${handle}`);
+  $('new-actor-go').disabled = false;
+  if (r?.url) location.href = r.url;      // its own page, where the progress is
+});
+