fedipod-server 0.29.0 → 0.30.0

package/lib/device/admin/routes/setup.mjs

@@ -1,428 +0,0 @@
-// setup.mjs — the first run and the process: setup driven from the page,
-// a new actor in a new home, starting a stopped one, updating and
-// restarting, moving the private half, and stopping this process.
-
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { spawn } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
-import { isCrossSiteNavigation } from '../../../shared/guard.mjs';
-import { identityHomes, rootOf, tildify, writeJsonAtomic } from '../../home.mjs';
-import { copyPrivateHalf, isCurrent, CURRENT_LAYOUT } from '../../migrate.mjs';
-import { insecureUrlReason } from '../../../shared/safefetch.mjs';
-import { newRun, preflight, runSetup, setupInputError, hasCredential, credentialPath } from '../../setup.mjs';
-import { podLayout } from '../../../pod/root.mjs';
-import { chosenRoot, publicIndexKnown } from '../../../core/place.mjs';
-import { portFree, freePortFrom } from '../../ports.mjs';
-import { yieldDirectory } from '../../../gateway/directory.mjs';
-import { localFetch } from '../../../client/localapi.mjs';
-import { projectRoot, SETUP_PAGE } from '../static.mjs';
-import { secureOrigin } from '../origins.mjs';
-
-// The signup carry-over: gateway and identity parameters a signup page
-// recorded for this install (written by the installer, consumed by the first
-// setup run). Read fresh each time — the file is deleted once consumed.
-function readFirstRun() {
-  const file = process.env.AP_FIRST_RUN;
-  if (!file) return null;
-  try {
-    const fr = JSON.parse(fs.readFileSync(file, 'utf8'));
-    return fr && typeof fr === 'object' ? fr : null;
-  } catch { return null; }
-}
-
-// The same config shape the `gateway` CLI command writes.
-function gatewayConfigFrom(fr) {
-  if (!fr?.gateway || !fr?.secret) return null;
-  const target = String(fr.gateway);
-  return fr.fronted
-    ? { url: target.replace(/ap\/actor$/, 'ap/inbox/'), frontActor: target,
-      mode: 'shadow', hmacSecret: String(fr.secret) }
-    : { url: target.replace(/\/?$/, '/'), mode: 'shadow', hmacSecret: String(fr.secret) };
-}
-
-export async function get(p, ctx, req, res, url) {   // eslint-disable-line no-unused-vars
-  const { agent, log, allowed, embedded, port, publicOrigin, versionOnDisk, isGroup } = ctx;   // eslint-disable-line no-unused-vars
-  const json = (res, status, obj) => { ctx.json(res, status, obj); return true; };
-
-  // ---- setup and configuration, for the pages under /admin/ ----
-  // These answer for a group too: a group is set up in the browser like
-  // anything else, and it has a display name to change.
-  if (req.method === 'GET' && p === '/setup/state') {
-    const home = agent.home || null;
-    const held = home && hasCredential(home) ? agent.readCredential?.() : null;
-    return json(res, 200, {
-      hasCredential: !!(home && hasCredential(home)),
-      configured: agent.configured(),
-      // Not the same question: a crashed setup leaves a credential with no
-      // actor behind it, and that is finishable without minting a second.
-      resumable: !!(home && hasCredential(home)) && !agent.configured(),
-      running: ctx.setup.run?.phase === 'running',
-      phase: ctx.setup.run?.phase || 'idle',
-      home,
-      port,
-      handle: agent.store.getConfig()?.handle || allowed.label || null,
-      kind: agent.store.getConfig()?.kind || null,
-      origins: {
-        loopback: publicOrigin
-          || `https://localhost:${port}/`,
-        named: publicOrigin
-          ? null
-          : allowed.label
-            ? (true
-              ? `https://${allowed.label}.localhost:${port}/`
-              : `http://${allowed.label}.localhost:${port}/`)
-            : null,
-      },
-      // Set in the environment, the password never needs to reach the page.
-      passwordSupplied: !!process.env.AP_PASSWORD,
-      identity: held ? { pod: held.remotePod, issuer: held.issuerOrigin, root: held.root || null } : null,
-      defaults: { issuer: 'https://solidcommunity.net', port: 8030 },
-      // What a signup page arranged for this install, so the form opens
-      // pre-filled. The receipt secret stays out of it — the /setup run
-      // reads that from the file itself.
-      firstRun: (() => {
-        if (agent.configured()) return null;
-        const fr = readFirstRun();
-        if (!fr?.handle) return null;
-        let gatewayHost = null;
-        try { gatewayHost = new URL(fr.gateway).host; } catch { /* no gateway named */ }
-        return { pod: fr.pod || null, issuer: fr.issuer || null, handle: String(fr.handle),
-          kind: fr.kind === 'group' ? 'group' : 'person', fronted: !!fr.fronted, gatewayHost };
-      })(),
-    });
-  }
-  if (req.method === 'GET' && p === '/setup/progress') {
-    return json(res, 200, ctx.setup.run || { phase: 'idle', steps: [], error: null, result: null });
-  }
-
-  return false;
-}
-
-export async function post(p, body, ctx, req, res) {   // eslint-disable-line no-unused-vars
-  const { agent, log, allowed, embedded, port, publicOrigin, versionOnDisk, isGroup } = ctx;   // eslint-disable-line no-unused-vars
-  const json = (res, status, obj) => { ctx.json(res, status, obj); return true; };
-  switch (p) {
-    // Stop an agent whose pidfile is gone and which no terminal owns
-    // (backgrounded, orphaned by a closed shell). It used to sit ABOVE both
-    // the configured() gate and the isLocal one, so it was the only
-    // state-changing route that needed neither — reachable from any host
-    // AP_ALLOWED_HOSTS named, on an agent that had never been set up.
-    case '/shutdown': {
-      json(res, 200, { ok: true, stopping: process.pid });
-      setTimeout(() => process.kill(process.pid, 'SIGTERM'), 50);
-      return true;
-    }
-    // ---- setup, driven by the page at /admin/setup/ ----
-    case '/setup/check': {
-      const pre = { ...preflight(body), ...await placeCheck(body) };
-      // For a new pod, ask the provider where it puts pods, so the page can
-      // show the Gateway address before the pod exists. A provider on paths
-      // means the address must live at the Gateway; the run decides for real.
-      if (pre.ok && body.mode === 'new' && body.shape !== 'front') {
-        const layout = await podLayout(fetch, body.issuer || '').catch(() => null);
-        if (layout === 'path') {
-          if ((body.kind || 'person') === 'group') {
-            return json(res, 200, { ...pre, ok: false, layout, refusal: 'group-needs-host-root' });
-          }
-          let gwHost; try { gwHost = new URL(body.gatewayOrigin || 'https://fedipod.net').host; } catch { gwHost = 'fedipod.net'; }
-          return json(res, 200, { ...pre, layout, fronted: true, forced: true, shape: 'front', gatewayHost: gwHost,
-            address: `@${body.handle}@${gwHost}`, resolvable: true });
-        }
-        return json(res, 200, { ...pre, layout });
-      }
-      return json(res, 200, pre);
-    }
-    // Discard a credential that never finished setup, so the account and
-    // pod can be entered again. The credential a CSS server mints is shown
-    // once, so a setup that stops after the mint (a wrong pod answers 401
-    // to the first write) leaves the form in "finish" mode with no way to
-    // re-enter what was wrong. This removes it locally and reopens the full
-    // form. It does NOT revoke server-side — that needs the account
-    // password (`fedipod revoke-credential`); the old credential is left on
-    // the account, revocable from its dashboard.
-    case '/setup/reset': {
-      if (isCrossSiteNavigation(req)) return json(res, 403, { error: 'cross-site request' });
-      // A working identity is never swapped out this way — that is a
-      // teardown (`fedipod retire`), not a half-finished setup.
-      if (agent.configured()) {
-        return json(res, 409, { error: 'this home holds a working identity — retire it, do not reset' });
-      }
-      if (ctx.setup.run?.phase === 'running') {
-        return json(res, 409, { error: 'setup is running — let it finish or stop it first', phase: 'running' });
-      }
-      const home = agent.home;
-      if (!home) return json(res, 500, { error: 'this agent has no AP_HOME to reset' });
-      const removed = hasCredential(home);
-      if (removed) fs.rmSync(credentialPath(home), { force: true });
-      // Drop the pod handle too, so configured() cannot flicker true off a
-      // stale in-memory session while the fresh form is filled in.
-      agent.remote = null;
-      ctx.setup.run = null;
-      return json(res, 200, { ok: true, removed });
-    }
-    case '/setup': {
-      // A visited page must not be able to navigate this into existence.
-      if (isCrossSiteNavigation(req)) return json(res, 403, { error: 'cross-site request' });
-      if (agent.configured()) {
-        return json(res, 409, {
-          error: 'this home already holds an identity',
-          pod: agent.store.getConfig()?.remotePod || null,
-        });
-      }
-      if (ctx.setup.run?.phase === 'running') {
-        return json(res, 409, { error: 'setup is already running', phase: 'running' });
-      }
-      const home = agent.home;
-      if (!home) return json(res, 500, { error: 'this agent has no AP_HOME to set up' });
-      // A crashed setup left a credential with no actor behind it. That is
-      // finishable, and must NOT mint a second credential — the first is
-      // unrecoverable and would be orphaned.
-      const resuming = hasCredential(home);
-      const answers = { ...body, password: body.password || process.env.AP_PASSWORD || '' };
-      // The signup carry-over: attach to the gateway the signup arranged,
-      // set before the first publish so the actor never advertises the pod
-      // inbox first. The secret comes from the installer's file, never the
-      // page.
-      const gatewayCfg = gatewayConfigFrom(readFirstRun());
-      if (gatewayCfg) answers.gateway = gatewayCfg;
-      const bad = setupInputError(answers, resuming);
-      if (bad) return json(res, 400, { error: bad });
-      if (!resuming) {
-        const pre = preflight(answers);
-        if (!pre.ok) return json(res, 400, { ...pre, error: pre.error || pre.refusal });
-      }
-      // Widen the allowlist now, not at the end: the page offers to move to
-      // the named origin, which has to answer before it is offered.
-      allowed.setHandle(answers.handle);
-      ctx.setup.run = newRun();
-      // Deliberately not awaited. The credential a CSS server mints is
-      // shown once, so what a run depends on is the file it writes, never
-      // a connection a closed tab can take with it.
-      runSetup({ home, agent, answers, run: ctx.setup.run, log })
-        .then((r) => {
-          // The carried secret is consumed; a finished setup deletes it.
-          if (r?.phase === 'done' && process.env.AP_FIRST_RUN) {
-            try { fs.unlinkSync(process.env.AP_FIRST_RUN); } catch { /* already gone */ }
-          }
-        })
-        .catch(e => { ctx.setup.run.phase = 'error'; ctx.setup.run.error = e.message; });
-      return json(res, 202, { ok: true, running: true, resuming });
-    }
-    // One identity per home, so a new actor means a new home, a free port
-    // and a process there — then its own setup, run with the answers this
-    // page collected. The reply is the address of the new actor's page,
-    // which is where the progress of that setup is reported.
-    case '/new-actor': {
-      if (isCrossSiteNavigation(req)) return json(res, 403, { error: 'cross-site request' });
-      const handle = String(body.handle || '').trim().toLowerCase();
-      // The name first, and before anything is created: it is what becomes
-      // a directory, and "mode must be new or existing" is a poor answer to
-      // a handle that could climb out of profiles/.
-      // Named after the handle rather than generated, so `profiles` and
-      // `--profile <name>` stay legible a year from now.
-      if (!/^[a-z0-9][a-z0-9_-]{0,30}$/.test(handle)) {
-        return json(res, 400, { error: 'a handle is letters, digits, hyphens and underscores' });
-      }
-      const dir = path.join(rootOf(path.resolve(agent.home || '')), 'profiles', handle);
-      if (fs.existsSync(path.join(dir, 'credential.json'))) {
-        return json(res, 409, { error: `${handle} already exists — it is in the list above` });
-      }
-      // Then everything else setup needs, so a missing password is refused
-      // here rather than after a process has been started for it.
-      const bad = setupInputError({ ...body, handle });
-      if (bad) return json(res, 400, { error: bad });
-      const newPort = await freePortFrom(port + 1);
-      if (!newPort) return json(res, 503, { error: 'no free port in the next 50' });
-      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-      const child = spawn(process.execPath, [path.join(projectRoot, 'run-agent.mjs')], {
-        detached: true, stdio: 'ignore',
-        env: { ...process.env, AP_HOME: dir, AP_PORT: String(newPort), AP_PROFILE: '' },
-      });
-      child.unref();
-      // Answer only once it is listening: handing back a URL that is not
-      // up yet shows a connection error instead of the setup form.
-      let listening = false;
-      for (let i = 0; i < 60 && !listening; i++) {
-        await new Promise(r => setTimeout(r, 250));
-        listening = await localFetch(agent.home, newPort, '/status', { timeout: 1000 })
-          .then(r => r.ok).catch(() => false);
-      }
-      if (!listening) return json(res, 504, { error: `started it on ${newPort} but it never answered` });
-
-      // Its own /setup owns the work — minting the credential, provisioning
-      // the pod, publishing. It answers 202 and runs in the background, so
-      // the page that opens next is the one reporting progress.
-      const started = await localFetch(agent.home, newPort, '/setup', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ ...body, handle }),
-      }).then(async r => ({ status: r.status, json: await r.json().catch(() => null) }))
-        .catch(e => ({ status: 0, json: { error: e.message } }));
-      if (started.status !== 202) {
-        return json(res, started.status || 502, {
-          error: started.json?.error || `the new agent refused setup (HTTP ${started.status})`,
-          port: newPort, url: `${secureOrigin(handle, newPort)}${SETUP_PAGE}`,
-        });
-      }
-      return json(res, 200,
-        { ok: true, handle, port: newPort,
-          url: `${secureOrigin(handle, newPort)}${SETUP_PAGE}` });
-    }
-    // Start an actor that is not running, so its page can be visited. The
-    // same spawn as /new-actor, minus the making: this one has a home
-    // already. Its recorded port is preferred so its address stays what it
-    // was, but a port something else has taken is walked past, not fought.
-    case '/start-actor': {
-      if (isCrossSiteNavigation(req)) return json(res, 403, { error: 'cross-site request' });
-      const name = String(body.name || '');
-      const found = identityHomes(rootOf(path.resolve(agent.home || ''))).find(h => h.name === name);
-      if (!found) return json(res, 404, { error: `no identity called ${name}` });
-
-      let want = null;
-      try { want = JSON.parse(fs.readFileSync(path.join(found.dir, 'agent.json'), 'utf8')).port || null; } catch {}
-      if (want) {
-        // Its own handle, not the profile directory's name: usually the
-        // same, but a renamed profile makes them differ and the origin has
-        // to be one that agent's own guard will accept.
-        const live = await localFetch(agent.home, want, '/status', { timeout: 1000 })
-          .then(r => (r.ok ? r.json() : null)).catch(() => null);
-        if (live) {
-          return json(res, 200, {
-            ok: true, name, port: want, already: true,
-            url: `${secureOrigin(live.handle || name, want)}/`,
-          });
-        }
-      }
-      // The port is not the only evidence it is running. An agent from
-      // before agent.json was written at startup has a live pidfile and no
-      // recorded port, and spawning past that gives one home two agents —
-      // which is exactly how this machine ended up with two on profiles/jeff.
-      let held = null;
-      try { held = Number(fs.readFileSync(path.join(found.dir, 'agent.pid'), 'utf8').trim()) || null; } catch {}
-      if (held) {
-        let alive = false;
-        try { process.kill(held, 0); alive = true; } catch { /* gone */ }
-        if (alive) {
-          return json(res, 409, {
-            error: `${name} is already running as pid ${held}, on a port it never recorded. `
-              + `Stop it first:  kill ${held}`,
-          });
-        }
-      }
-      // A recorded port held by the directory door is still this
-      // identity's port — the door steps aside for its owner.
-      if (want && !await portFree(want)) await yieldDirectory(want, { portFree });
-      const on = (want && await portFree(want)) ? want : await freePortFrom(port + 1);
-      if (!on) return json(res, 503, { error: 'no free port in the next 50' });
-
-      const started = spawn(process.execPath, [path.join(projectRoot, 'run-agent.mjs')], {
-        detached: true, stdio: 'ignore',
-        env: { ...process.env, AP_HOME: found.dir, AP_PORT: String(on), AP_PROFILE: '' },
-      });
-      started.unref();
-      for (let i = 0; i < 60; i++) {
-        await new Promise(r => setTimeout(r, 250));
-        const up = await localFetch(agent.home, on, '/status', { timeout: 1000 })
-          .then(r => (r.ok ? r.json() : null)).catch(() => null);
-        if (up) {
-          return json(res, 200, { ok: true, name, port: on,
-            url: `${secureOrigin(up.handle || name, on)}/` });
-        }
-      }
-      return json(res, 504, { error: `started ${name} on ${on} but it never answered` });
-    }
-    // Pull the latest published FediPod and restart the agents. What the
-    // installer does on a re-run, offered where the version line is.
-    case '/update': {
-      if (isCrossSiteNavigation(req)) return json(res, 403, { error: 'cross-site request' });
-      const { runUpdate, restartAgents, repoRoot } = await import('../../update.mjs');
-      const r = runUpdate({ log });
-      if (!r.ok) return json(res, 409, { error: r.note });
-      json(res, 200, { ok: true, note: r.note, restarting: true });
-      // The response first, the restart a beat later — a self-restart must
-      // not take the answer down with it.
-      setTimeout(() => {
-        if (restartAgents({ log }) === 'self') {
-          const child = spawn(process.execPath, [path.join(repoRoot(), 'run-agent.mjs')],
-            { detached: true, stdio: 'ignore', env: process.env });
-          child.unref();
-          setTimeout(() => process.exit(0), 300);
-        }
-      }, 200);
-      return true;
-    }
-    // Move the private half — every state document and the RDF tree — while
-    // the agent runs: quiesce this process's writers, flush, copy, verify,
-    // repoint the credential, then reconnect on the new location. The old
-    // copy is left where it was, exactly as the CLI move leaves it.
-    case '/state-move': {
-      const cred = agent.readCredential?.();
-      if (!cred) return json(res, 409, { error: 'no credential — run setup first' });
-      const to = String(body.to || '').trim();
-      if (!to) return json(res, 400, { error: 'say where it should go' });
-      let target = null;
-      if (to !== 'pod') {
-        // A path or a URL — two chars before the colon, so a Windows drive
-        // letter reads as a path rather than a scheme.
-        const asPath = !/^[a-z][a-z0-9+.-]+:/i.test(to);
-        const raw = asPath
-          ? pathToFileURL(path.resolve(to.replace(/^~(?=[/\\]|$)/, os.homedir()))).href
-          : to;
-        target = raw.endsWith('/') ? raw : raw + '/';
-        try { new URL(target); } catch { return json(res, 400, { error: `"${to}" is not a container URL or a path` }); }
-        if (/^https?:/i.test(target)) {
-          const bad = insecureUrlReason(target, 'private-data address');
-          if (bad) return json(res, 400, { error: bad });
-        }
-      }
-      const whereState = (c) => (c.privateRoot ? tildify(c.privateRoot) : 'on the pod');
-      if ((cred.privateRoot || null) === target) {
-        return json(res, 200, { ok: true, docs: 0, notes: 0, unchanged: true, now: whereState(cred) });
-      }
-      await agent.requestTakeover?.();
-      agent.intake?.stop(); agent.deliverer?.stop(); agent.tagfeed?.stop(); agent.importer?.stop();
-      try {
-        await agent.store.flush();
-        const destCred = { ...cred, privateRoot: target };
-        const copied = await copyPrivateHalf({
-          from: { state: agent.privateStorage(cred, 'state') },
-          to: { state: agent.privateStorage(destCred, 'state') },
-          log,
-        });
-        if (target) cred.privateRoot = target; else delete cred.privateRoot;
-        if (isCurrent(cred)) cred.layout = CURRENT_LAYOUT; else delete cred.layout;
-        writeJsonAtomic(path.join(agent.home, 'credential.json'), cred);
-        // connect() rebuilds everything that pointed at the old location —
-        // store, publisher, intake — and restarts them.
-        agent.store.attach(agent.privateStorage(cred, 'state'));
-        agent.stateLoaded = false;
-        await agent.connect();
-        return json(res, 200, { ok: true, ...copied, now: whereState(cred) });
-      } catch (e) {
-        // The credential is only repointed after a verified copy, so on any
-        // failure reconnect puts the agent back to work where it was.
-        agent.stateLoaded = false;
-        await agent.connect().catch(() => {});
-        return json(res, 502, { error: e.message });
-      }
-    }
-    default: return false;
-  }
-}
-
-// Where the data will go and whether the type index question has to be asked:
-// a pod you bring is read as a stranger would (its profile is public); a new
-// pod has no index, so the question is always asked for one.
-async function placeCheck(body) {
-  if (body.mode === 'new') return { typeIndex: false };
-  let base;
-  try { base = new URL(String(body.pod || '')).href; } catch { return {}; }
-  if (!base.endsWith('/')) base += '/';
-  const place = chosenRoot(base, body.container);
-  return {
-    typeIndex: await publicIndexKnown(fetch, base),
-    ...(place.problem ? { placeProblem: place.problem } : { place: base + place.root }),
-  };
-}

package/lib/device/admin/routes/social.mjs

@@ -1,188 +0,0 @@
-// social.mjs — the owner acting on the social graph, and a group operator
-// moderating: posting, the tag feed, follows, mutes, blocks, ejecting,
-// retracting, review, joins, the moderation queue.
-
-import { followHandle, followActor, unfollowActor, ejectFollower, retractAnnouncement, admitRequest, refuseRequest, applyModeration } from '../../../core/social.mjs';
-
-export async function get(p, ctx, req, res, url) {   // eslint-disable-line no-unused-vars
-  const { agent, log, allowed, embedded, port, publicOrigin, versionOnDisk, isGroup } = ctx;   // eslint-disable-line no-unused-vars
-  const json = (res, status, obj) => { ctx.json(res, status, obj); return true; };
-
-  if (req.method === 'GET' && p === '/tagfeed') {
-    return json(res, 200, agent.tagfeed
-      ? { ...agent.tagfeed.config(), lastSweep: agent.tagfeed.lastSweep, lastAdded: agent.tagfeed.lastAdded }
-      : { error: 'agent not configured' });
-  }
-
-  return false;
-}
-
-export async function post(p, body, ctx, req, res) {   // eslint-disable-line no-unused-vars
-  const { agent, log, allowed, embedded, port, publicOrigin, versionOnDisk, isGroup } = ctx;   // eslint-disable-line no-unused-vars
-  const json = (res, status, obj) => { ctx.json(res, status, obj); return true; };
-  switch (p) {
-    case '/post': {
-      if (!body.content) return json(res, 400, { error: 'content required' });
-      const note = await agent.publisher.publishNote(body.content, { inReplyTo: body.inReplyTo });
-      return json(res, 200, { ok: true, id: note.id });
-    }
-    case '/tagfeed': return json(res, 200, agent.tagfeed.setConfig(body));
-    case '/archive': {
-      // Whether drained mail's original bytes are kept in the private
-      // half's inbox-archive/. Absent means on.
-      const cfg = agent.store.getConfig();
-      agent.store.setConfig({ ...cfg, archiveInbox: !!body.on });
-      await agent.store.flush();
-      return json(res, 200, { ok: true, archiveInbox: !!body.on });
-    }
-    case '/follow': {
-      // By handle normally; by actor URL when there is no handle to resolve —
-      // a pod on a path, or anything WebFinger cannot answer for. Pasting an
-      // actor URL is a normal way to follow in Mastodon too.
-      if (body.actor) { await followActor(agent, body.actor); return json(res, 200, { ok: true, actor: body.actor }); }
-      if (!body.handle) return json(res, 400, { error: 'handle or actor required' });
-      return json(res, 200, await followHandle(agent, body.handle));
-    }
-    case '/unfollow': return json(res, 200, await unfollowActor(agent, body.actor));
-    case '/mute':
-    case '/unmute': {
-      if (!isGroup()) return json(res, 404, { error: 'not a group' });
-      if (!body.actor) return json(res, 400, { error: 'actor required' });
-      const m = agent.store.getMuted();
-      m.actors = p === '/mute'
-        ? [...new Set([...m.actors, body.actor])]
-        : m.actors.filter(a => a !== body.actor);
-      agent.store.setMuted(m);
-      await agent.store.flush();
-      return json(res, 200, { ok: true, actors: m.actors });
-    }
-    case '/eject': {
-      if (!isGroup()) return json(res, 404, { error: 'not a group' });
-      if (!body.actor) return json(res, 400, { error: 'actor required' });
-      const r = await ejectFollower(agent, body.actor);
-      await agent.store.flush();
-      return json(res, 200, r);
-    }
-    case '/retract': {
-      if (!isGroup()) return json(res, 404, { error: 'not a group' });
-      if (!body.noteId) return json(res, 400, { error: 'noteId required' });
-      const r = await retractAnnouncement(agent, body.noteId);
-      await agent.store.flush();
-      return json(res, 200, r);
-    }
-    case '/review': {
-      if (!isGroup()) return json(res, 404, { error: 'not a group' });
-      agent.store.setConfig({ ...agent.store.getConfig(), review: !!body.on });
-      await agent.store.flush();
-      return json(res, 200, { ok: true, review: !!body.on });
-    }
-    case '/describe': {
-      const cfg = { ...agent.store.getConfig() };
-      if ('summary' in body) cfg.summary = body.summary || undefined;
-      if ('icon' in body) cfg.icon = body.icon || undefined;
-      agent.store.setConfig(cfg);
-      Object.assign(agent.publisher.config, { summary: cfg.summary, icon: cfg.icon });
-      await agent.store.flush();
-      await agent.publisher.publishProfile();      // the bio and avatar are on the wire
-      return json(res, 200, { ok: true, summary: cfg.summary || null, icon: cfg.icon || null });
-    }
-    case '/joins': {
-      if (!isGroup()) return json(res, 404, { error: 'not a group' });
-      const cfg = { ...agent.store.getConfig(), approveJoins: !!body.approve };
-      agent.store.setConfig(cfg);
-      agent.publisher.config.approveJoins = !!body.approve;
-      await agent.store.flush();
-      // Unlike review, this one is visible to the fediverse: the actor
-      // document carries manuallyApprovesFollowers, so nothing changes for
-      // anyone until it is republished.
-      await agent.publisher.publishProfile();
-      return json(res, 200, { ok: true, approveJoins: !!body.approve });
-    }
-    case '/admit':
-    case '/refuse': {
-      // Kind-agnostic, like the queue they act on: admitting adds a
-      // follower and Accepts, refusing Rejects. A person needs both.
-      // `all` answers the whole queue — the shape a migration wave arrives
-      // in — with one collections republish for the lot.
-      if (p === '/admit' && body.all === true) {
-        const waiting = agent.store.getRequests().map(r => r.actor);
-        let admitted = 0;
-        for (const actor of waiting) {
-          try { await admitRequest(agent, actor, { publish: false }); admitted++; }
-          catch (e) { log(`admit ${actor} failed: ${e.message}`); }
-        }
-        if (admitted) await agent.publisher.publishCollections({ followers: true, pending: true });
-        await agent.store.flush();
-        return json(res, 200, { ok: true, admitted, requests: agent.store.getRequests().length });
-      }
-      if (!body.actor) return json(res, 400, { error: 'actor required' });
-      const r = p === '/admit' ? await admitRequest(agent, body.actor)
-        : await refuseRequest(agent, body.actor);
-      await agent.store.flush();
-      return json(res, 200, { ...r, requests: agent.store.getRequests().length });
-    }
-    case '/approve':
-    case '/decline': {
-      if (!isGroup()) return json(res, 404, { error: 'not a group' });
-      if (!body.noteId) return json(res, 400, { error: 'noteId required' });
-      const held = agent.store.getPending().some(x => x.noteId === body.noteId);
-      if (!held) return json(res, 404, { error: 'not held for review' });
-      if (p === '/approve') await agent.intake.amplify(body.noteId, { approved: true });
-      else agent.store.setPending(agent.store.getPending().filter(x => x.noteId !== body.noteId));
-      await agent.store.flush();
-      return json(res, 200, { ok: true, noteId: body.noteId, pending: agent.store.getPending().length });
-    }
-    // Answer one queued moderation ask: apply it (the operator vouching
-    // for a delivery nothing else can vouch for) or dismiss it.
-    case '/modqueue': {
-      if (!isGroup()) return json(res, 404, { error: 'not a group' });
-      const q = agent.store.read('modqueue.json', []);
-      const entry = q.find(e => e.id === body.id);
-      if (!entry) return json(res, 404, { error: 'no such queued action' });
-      if (body.action !== 'apply' && body.action !== 'dismiss') {
-        return json(res, 400, { error: 'action must be apply or dismiss' });
-      }
-      let applied = null;
-      if (body.action === 'apply') applied = await applyModeration(agent, entry);
-      agent.store.write('modqueue.json', q.filter(e => e.id !== entry.id));
-      await agent.store.flush();
-      return json(res, 200, {
-        ok: true, action: body.action, type: entry.type, moderator: entry.moderator,
-        ...(applied && typeof applied === 'object' ? { result: applied } : {}),
-        remaining: agent.store.read('modqueue.json', []).length,
-      });
-    }
-    // Symmetrical with /block, and open for the same reason: a block made
-    // by mistake is worth undoing before federation is even configured.
-    case '/unblock': {
-      const b = agent.store.getBlocklist();
-      const before = b.domains.length + b.actors.length;
-      if (body.actor) b.actors = b.actors.filter(a => a !== body.actor);
-      else if (body.domain) b.domains = b.domains.filter(d => d !== body.domain);
-      else return json(res, 400, { error: 'domain or actor required' });
-      agent.store.setBlocklist(b);
-      // The published blocked collection (FEP-c648) follows, best-effort.
-      Promise.resolve(agent.publisher?.publishCollections?.({ blocked: true })).catch(() => {});
-      return json(res, 200, {
-        ok: true, removed: before - (b.domains.length + b.actors.length),
-        domains: b.domains, actors: b.actors,
-      });
-    }
-    case '/block': {
-      const b = agent.store.getBlocklist();
-      if (body.actor) {
-        if (!/^https?:\/\/\S+$/.test(body.actor)) return json(res, 400, { error: 'actor must be a URL' });
-        if (!b.actors.includes(body.actor)) b.actors.push(body.actor);
-      } else if (body.domain) {
-        if (!b.domains.includes(body.domain)) b.domains.push(body.domain);
-      } else {
-        return json(res, 400, { error: 'domain or actor required' });
-      }
-      agent.store.setBlocklist(b);
-      // The published blocked collection (FEP-c648) follows, best-effort.
-      Promise.resolve(agent.publisher?.publishCollections?.({ blocked: true })).catch(() => {});
-      return json(res, 200, { ok: true, domains: b.domains, actors: b.actors });
-    }
-    default: return false;
-  }
-}