fedipod-server 0.11.0 → 0.13.0

package/lib/device/admin/server.mjs

@@ -0,0 +1,95 @@
+// server.mjs — the DeviceAgent's listener: the https servers on both
+// loopbacks, the pidfile, the directory door, and the retry when the port is
+// held by that door.
+
+import https from 'node:https';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { Authorities } from '../../shared/guard.mjs';
+import { rootOf } from '../home.mjs';
+import { portFree } from '../ports.mjs';
+import { claimDirectory, yieldDirectory } from '../../gateway/directory.mjs';
+import { ensureTrustedTls } from '../certs.mjs';
+import { localVersion } from '../update.mjs';
+import { projectRoot } from './static.mjs';
+import { secureOrigin } from './origins.mjs';
+import { buildAdminSurface } from './surface.mjs';
+
+const require = createRequire(import.meta.url);
+const { makeGate } = require(path.join(projectRoot, 'vendor/gate.cjs'));
+
+export function startAdmin({ port, gateToken, agent, log = console.log, handle = null, tls = null,
+  // Injectable, so a test can put a checkout ahead of the running process
+  // without editing the package.json of the machine running the test.
+  versionOnDisk = () => localVersion(projectRoot) }) {
+  const gate = makeGate(gateToken);
+  // Live, so the named origin appears the moment connect() reads the handle
+  // out of pod state — including for the OAuth redirect check in MastoApi.
+  // The https listener's port joins the authority set: same names, second port.
+  const allowed = new Authorities(port, handle);
+  agent.authorities = allowed;
+  const { handler, streaming } = buildAdminSurface({ agent, gate, allowed, log, port, handle, versionOnDisk });
+
+  // Loopback both ways: the canonical URL is https://localhost:<port>/, and
+  // "localhost" resolves to ::1 on many systems before falling back to IPv4 —
+  // answer on both so the same origin always works (one origin = one
+  // browser storage = one login). There is one listener and it is https: the
+  // port you name is the port you browse.
+  // Every listener here is https, so a caller that did not bring a certificate
+  // gets this install's own rather than an exception: throwing here killed the
+  // signal handlers registered after the call, and the agent became unstoppable.
+  if (!tls) {
+    tls = ensureTrustedTls(path.join(rootOf(agent.home || os.tmpdir()), 'certs'),
+      { log, names: allowed.label ? [`${allowed.label}.localhost`] : [] });
+  }
+  const tlsOpts = { key: tls.key, cert: tls.cert };
+  const server = https.createServer(tlsOpts, handler);
+  streaming.attach(server);
+  const server6 = https.createServer(tlsOpts, handler);
+  streaming.attach(server6);
+  server6.on('error', () => { /* no IPv6 loopback on this system — IPv4 covers it */ });
+  const onListen = () => {
+    // Pidfile for `fedipod stop` — written only AFTER the listen
+    // succeeds, so a port-race loser can never clobber the live agent's pid.
+    try {
+      if (agent.home) fs.writeFileSync(path.join(agent.home, 'agent.pid'), String(process.pid) + '\n');
+    } catch { /* stop will report no pidfile */ }
+    // The named origin when there is one: on a detached start this line is the
+    // only record of where to browse, and sending you to the shared origin is
+    // how two identities end up in one browser storage bucket.
+    log(`FediPod on ${secureOrigin(allowed.label, port)}/ (UI + API)`
+      + (tls.trust ? '' : ' (self-signed — your client may ask once to trust it)'));
+    // Hold the well-known door: whoever answers on the directory port sends the
+    // browser to its own record page, which lists every identity on this
+    // machine. Only a configured agent qualifies — an unconfigured one's record
+    // page is a setup form with no identity list.
+    const door = claimDirectory({ port,
+      origin: () => secureOrigin(allowed.label, port),
+      log, eligible: () => agent.configured(), tls });
+    // Closing the IPv4 listener has to take the IPv6 one and the door with it,
+    // or a shutdown leaves a listening handle and the process never exits.
+    server.on('close', () => { door.stop(); try { server6.close(); } catch { /* already down */ } });
+  };
+  let retriedDoor = false;
+  server.on('error', async (e) => {
+    if (e.code === 'EADDRINUSE') {
+      // The directory door yields to a real owner of its port; anything else
+      // holding it is a genuine conflict.
+      if (!retriedDoor && await yieldDirectory(port, { portFree, home: agent.home })) {
+        retriedDoor = true;
+        server.listen(port, '127.0.0.1', onListen);
+        if (!server6.listening) server6.listen(port, '::1');
+        return;
+      }
+      log(`port ${port} is already in use by another server — set AP_PORT to a free port and retry`);
+      process.exit(1);
+    }
+    throw e;
+  });
+  server.listen(port, '127.0.0.1', onListen);
+  server6.listen(port, '::1');
+
+  return server;
+}

package/lib/device/admin/static.mjs

@@ -0,0 +1,244 @@
+// static.mjs — what the agent serves off disk: the vendored client with its
+// own service worker taken out, any client dist dropped into ui/, and the
+// agent's own pages; the headers every response carries; and the two
+// constants every module here shares, where the checkout is and what
+// version it is.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { wsOrigins } from './origins.mjs';
+
+export const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+
+const PHANPY_DIR = path.join(projectRoot, 'phanpy/dist');
+// The vendored client is upstream's build, byte for byte, so the integrity
+// check can say so. The two things it needs changed happen on the way out
+// instead of in the files.
+//
+// vite-plugin-pwa injects this registration into every page it builds. The
+// worker it installs answers navigations from a precache and replays the
+// headers stored at install time, so a CSP change can never reach a browser
+// that already has one.
+const SW_REGISTER = /<script id="vite-plugin-pwa:inline-sw">[\s\S]*?<\/script>/i;
+// Removing it stops new installs. This replaces the worker itself, so the ones
+// already out there clean up: browsers re-fetch sw.js on navigation and
+// install what they find. No fetch handler on purpose — a worker without one
+// never intercepts a request, so pages go straight to the network while it
+// runs.
+const SW_KILL = `self.addEventListener('install', () => self.skipWaiting());
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil((async () => {
+    for (const key of await caches.keys()) await caches.delete(key);
+    await self.registration.unregister();
+    for (const client of await self.clients.matchAll({ type: 'window' })) {
+      try { await client.navigate(client.url); } catch { /* tab will refresh on its own */ }
+    }
+  })());
+});
+`;
+// Null rather than the original when the tag is gone: an upstream change that
+// silently no-opped here would put the worker back, which is the whole thing
+// this exists to prevent.
+function stripSwRegistration(html) {
+  return SW_REGISTER.test(html) ? html.replace(SW_REGISTER, '') : null;
+}
+const UI_DIR = path.join(projectRoot, 'ui');       // extra client dists: ui/<name>/ → /<name>/
+// Our own pages, kept out of ui/ for two reasons: a client dist dropped in
+// there under the same name would shadow them, and a group serves these and
+// nothing else — so the prefix has to be one nobody is invited to write into.
+// One surface, /admin/, with setup as its first section: /admin/setup/ is the
+// first run, /admin/ is the record, and there is room for the rest.
+const WEB_DIR = path.join(projectRoot, 'web');
+const WEB_MOUNTS = ['admin'];
+export const webMount = (pathname) => {
+  const seg = decodeURIComponent(pathname).replace(/^\/+/, '').split('/')[0];
+  return WEB_MOUNTS.includes(seg) ? seg : null;
+};
+export const SETUP_PAGE = '/admin/setup/';
+
+export const AGENT_VERSION = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8')).version;
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.css': 'text/css',
+  '.json': 'application/json', '.map': 'application/json', '.webmanifest': 'application/manifest+json',
+  '.png': 'image/png', '.svg': 'image/svg+xml', '.ico': 'image/x-icon', '.gif': 'image/gif',
+  '.jpg': 'image/jpeg', '.webp': 'image/webp', '.txt': 'text/plain', '.woff2': 'font/woff2',
+};
+
+// Sent on every response: nosniff and no-referrer everywhere, and for HTML a
+// CSP that keeps SCRIPTS to our own origin while still allowing the remote
+// avatars, media and instance calls a fediverse client must make. It is not an
+// exfiltration boundary — connect-src has to allow https: for the client to
+// work at all — it is a code-execution one.
+// Phanpy's index.html carries an inline bootstrap script. Rather than
+// opening the policy with 'unsafe-inline', hash the inline scripts we
+// actually ship and allow exactly those.
+let inlineHashes = null;
+function inlineScriptHashes() {
+  if (inlineHashes) return inlineHashes;
+  inlineHashes = [];
+  try {
+    // The page as it is SERVED, not as it sits on disk: hashing the
+    // registration script we strip would allow a script nobody gets.
+    const raw = fs.readFileSync(path.join(PHANPY_DIR, 'index.html'), 'utf8');
+    const html = stripSwRegistration(raw) ?? raw;
+    for (const m of html.matchAll(/<script(?![^>]*\ssrc=)[^>]*>([\s\S]*?)<\/script>/gi)) {
+      const digest = crypto.createHash('sha256').update(m[1], 'utf8').digest('base64');
+      inlineHashes.push(`'sha256-${digest}'`);
+    }
+  } catch { /* no inline scripts to allow */ }
+  return inlineHashes;
+}
+
+export function securityHeaders(auth, isHtml) {
+  const h = {
+    'x-content-type-options': 'nosniff',
+    'referrer-policy': 'no-referrer',
+    // SAMEORIGIN, not DENY: /admin/client/ frames the bundled client so a bar
+    // of ours can sit above it. Only pages on this agent's own origins may —
+    // the same set the Host/Origin firewall already trusts.
+    'x-frame-options': 'SAMEORIGIN',
+  };
+  if (isHtml) {
+    h['content-security-policy'] = [
+      "default-src 'self'",
+      `script-src 'self' 'wasm-unsafe-eval' ${inlineScriptHashes().join(' ')}`,
+      "style-src 'self' 'unsafe-inline'",
+      "img-src 'self' https: data: blob:",
+      "media-src 'self' https: data: blob:",
+      "font-src 'self' data:",
+      // Every authority the Host/Origin firewall accepts, so browsing an agent
+      // at its own name (solo.localhost:8041, a tailnet host) keeps streaming.
+      // Pinning this to localhost blocked the socket with no visible error.
+      //
+      // `https:` is still here and the comment above no longer claims otherwise:
+      // a fediverse client fetches remote instances by design — link previews,
+      // an actor's own server, media — so there is no narrower set that leaves
+      // it working. The XSS story is `script-src 'self'` plus hashes; treat
+      // connect-src as availability, not containment.
+      `connect-src 'self' https: ${(typeof auth.wsAuthorities === 'function'
+        ? auth.wsAuthorities()
+        : wsOrigins(auth.port, auth.labels())).join(' ')}`,
+      "frame-ancestors 'self'",
+      "base-uri 'self'",
+      "form-action 'self'",
+    ].join('; ');
+  }
+  return h;
+}
+
+export function sendJson(res, status, obj, auth) {
+  res.writeHead(status, { 'content-type': 'application/json', ...securityHeaders(auth, false) });
+  res.end(JSON.stringify(obj) + '\n');
+}
+
+// Static UI serving, path-jailed. Phanpy owns the root; any other client
+// dist dropped into ui/<name>/ is served at /<name>/. Hash-routed apps:
+// '/' (and directories) get their index.html; anything unknown 404s.
+export function serveStatic(res, pathname, auth) {
+  let rel = decodeURIComponent(pathname).replace(/^\/+/, '');
+  let baseDir = PHANPY_DIR;
+  const uiName = rel.split('/')[0];
+  // The mount name is joined to UI_DIR, so it must be CONTAINED by it — the
+  // same resolve-then-check sendFile does below, for the same reason.
+  //
+  // Decoding happens before the split, so a `%2f` in the first segment becomes
+  // a real separator afterwards and `..` arrives here as a mount name. It
+  // exists, and it is a directory, so baseDir was silently re-based to the
+  // project root — and sendFile's jail then enforced containment against THAT,
+  // dutifully approving `/..%2fpackage.json`, `/..%2f.git/config` and every
+  // source file under it for anyone who could reach the port.
+  // Resolved through symlinks, not just lexically: sendFile's own jail has
+  // always used realpath, and a lexical check here would still admit a mount
+  // that is a link pointing out of ui/.
+  let mount = '';
+  try {
+    if (uiName) {
+      const cand = path.resolve(UI_DIR, uiName);
+      if (cand.startsWith(UI_DIR + path.sep) && fs.statSync(cand).isDirectory()) {
+        const real = fs.realpathSync(cand);
+        if (real.startsWith(fs.realpathSync(UI_DIR) + path.sep)) mount = cand;
+      }
+    }
+  } catch { /* no such mount; fall through to the default base */ }
+  if (mount) {
+    baseDir = mount;
+    rel = rel.slice(uiName.length).replace(/^\/+/, '');
+  }
+  return sendFile(res, baseDir, rel, auth);
+}
+
+// '/admin/setup' names a directory, so it needs the slash the browser will
+// resolve relative URLs against. Returns the corrected path, or null.
+export function webDirRedirect(pathname) {
+  if (pathname.endsWith('/')) return null;
+  const rel = decodeURIComponent(pathname).replace(/^\/+/, '');
+  const full = path.normalize(path.join(WEB_DIR, rel));
+  if (!full.startsWith(WEB_DIR + path.sep)) return null;      // not ours to stat
+  try {
+    if (fs.statSync(full).isDirectory()) return pathname + '/';
+  } catch { /* not a directory here */ }
+  return null;
+}
+
+// web/<mount>/ → /<mount>/. Same jail, different mount rule.
+export function serveWeb(res, pathname, mount, auth) {
+  const rel = decodeURIComponent(pathname).replace(/^\/+/, '').slice(mount.length).replace(/^\/+/, '');
+  return sendFile(res, path.join(WEB_DIR, mount), rel, auth);
+}
+
+export function sendFile(res, baseDir, rel, auth) {
+  if (rel === '' || rel.endsWith('/')) rel += 'index.html';
+  const file = path.normalize(path.join(baseDir, rel));
+  if (!file.startsWith(baseDir + path.sep) && file !== path.join(baseDir, 'index.html')) {
+    res.writeHead(403); res.end(); return true;
+  }
+  let target = file;
+  try {
+    if (fs.statSync(target).isDirectory()) target = path.join(target, 'index.html');
+    // Resolve symlinks before reading: a link inside a UI dir must not be a
+    // way out of the jail.
+    const real = fs.realpathSync(target);
+    const realBase = fs.realpathSync(baseDir);
+    if (!real.startsWith(realBase + path.sep) && real !== path.join(realBase, 'index.html')) {
+      res.writeHead(403); res.end(); return true;
+    }
+    const ext = path.extname(real);
+    let body = fs.readFileSync(real);
+    // The vendored client, adjusted on the way out rather than in the files.
+    if (real.startsWith(fs.realpathSync(PHANPY_DIR))) {
+      if (path.basename(real) === 'sw.js') {
+        body = Buffer.from(SW_KILL);
+      } else if (ext === '.html') {
+        const stripped = stripSwRegistration(body.toString('utf8'));
+        if (stripped === null) {
+          console.error(`refusing to serve ${path.basename(real)}: no service-worker `
+            + 'registration to remove — the vendored client changed shape');
+          res.writeHead(500, { 'content-type': 'text/plain', ...securityHeaders(auth, false) });
+          res.end('the bundled client changed shape; refusing to serve it\n');
+          return true;
+        }
+        body = Buffer.from(stripped);
+      }
+    }
+    // Our own pages are read straight off disk and change whenever the project
+    // does. With no cache headers a browser is free to reuse them without
+    // asking, so an edited page keeps rendering the old one and looks like the
+    // edit never landed. The vendored client dists have hashed filenames and
+    // are left alone.
+    const ours = real.startsWith(fs.realpathSync(WEB_DIR) + path.sep);
+    res.writeHead(200, {
+      'content-type': MIME[ext] || 'application/octet-stream',
+      ...(ours ? { 'cache-control': 'no-store' } : {}),
+      ...securityHeaders(auth, ext === '.html'),
+    });
+    res.end(body);
+  } catch {
+    res.writeHead(404, { 'content-type': 'text/plain', ...securityHeaders(auth, false) });
+    res.end('not found\n');
+  }
+  return true;
+}

package/lib/device/admin/surface.mjs

@@ -0,0 +1,274 @@
+// surface.mjs — the whole admin surface as one request handler, with
+// nothing that belongs to a process of its own: the preamble every request
+// passes (CORS for the client API, the Host/Origin firewall, the operator's
+// door when embedded), the protocol routes that answer strangers (C2S, the
+// OAuth metadata, nodeinfo, the Mastodon facade), the pages and client
+// served off disk, and the dispatch to the routes modules beside it. Each of
+// those exports get() and post() over the same ctx.
+
+import { MastoApi } from '../../client/masto/index.mjs';
+import { C2S } from '../../client/c2s.mjs';
+import { makeC2sAuth } from '../../client/oidc-auth.mjs';
+import { Streaming } from '../../client/streaming.mjs';
+import { nodeinfoPointer, nodeinfoDoc } from '../../core/wire.mjs';
+import { checkRequest } from '../../shared/guard.mjs';
+import { hasCredential } from '../setup.mjs';
+import { localVersion } from '../update.mjs';
+import { projectRoot, AGENT_VERSION, SETUP_PAGE, securityHeaders, sendJson, serveStatic, serveWeb, webDirRedirect, webMount } from './static.mjs';
+import * as owner from './routes/owner.mjs';
+import * as setup from './routes/setup.mjs';
+import * as lifecycle from './routes/lifecycle.mjs';
+import * as gateway from './routes/gateway.mjs';
+import * as social from './routes/social.mjs';
+import * as connections from './routes/connections.mjs';
+
+// POSTs an unconfigured agent still answers: /block is worth having before
+// federation starts, and /setup is how it stops being unconfigured.
+// /shutdown is here because stopping an agent that was never set up is exactly
+// the case it exists for; it is in LOCAL_ONLY_POSTS below, so it still answers
+// only to this machine.
+const OPEN_POSTS = new Set(['/block', '/unblock', '/setup', '/setup/check', '/setup/reset', '/shutdown']);
+// Routes that manage a local agent process — spawning siblings, killing this
+// one, moving files on the machine, running setup in a browser. Inside a pod
+// server there is no such process and no such machine: identities come from
+// the server's own configuration, so these are not there to be found.
+const EMBEDDED_CUT = new Set(['/profiles', '/shutdown', '/new-actor', '/start-actor',
+  '/state-move', '/setup', '/setup/check', '/setup/reset']);
+// AP_ALLOWED_HOSTS may name a tailnet host or a reverse-proxy domain. The
+// fediverse is welcome there; creating accounts and editing the record is for
+// whoever is sitting at the machine.
+const LOCAL_ONLY_POSTS = new Set(['/setup', '/setup/check', '/setup/reset', '/config', '/new-actor', '/start-actor', '/shutdown', '/state-move', '/atproto/connect', '/fediacct/connect', '/fediacct/disconnect', '/fediacct', '/gateway', '/alias', '/import', '/update']);
+
+// A cross-origin form POST needs no CORS preflight, and JSON.parse does not
+// care what Content-Type claimed — so parsing whatever arrived let a visited
+// page reach every write route with a body of its choosing. Our own callers
+// (web/admin/*.js, the CLI) all send application/json; `stop` sends no body at
+// all, which is why an absent type is allowed only for an empty one.
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const ct = String(req.headers['content-type'] || '').split(';')[0].trim().toLowerCase();
+    const isJson = ct === 'application/json';
+    const wrongType = () => reject(new Error('expected content-type: application/json'));
+    if (ct && !isJson) { req.resume(); wrongType(); return; }
+    let data = '';
+    req.on('data', c => {
+      data += c;
+      if (data.length > 1e6) { reject(new Error('request body too large')); req.destroy(); }
+    });
+    req.on('end', () => {
+      if (data && !isJson) return wrongType();
+      try { resolve(data ? JSON.parse(data) : {}); } catch (e) { reject(e); }
+    });
+    req.on('error', reject);
+  });
+}
+
+// The routes, in the order the one if-chain and the one switch used to be
+// read: the first module that answers a path wins.
+const ROUTES = [owner, setup, lifecycle, gateway, social, connections];
+
+// The whole admin/facade surface as one request handler, with nothing that
+// belongs to a process of its own. startAdmin wraps it in listeners; the CSS
+// component hands it CSS's, so the same routes answer on the pod's origin.
+//
+// `embedded` cuts the routes that manage local agent processes — they have no
+// meaning inside a server that is not one — and moves the gate: a pod that is
+// a fediverse instance must let strangers reach /api and /oauth, so the gate
+// guards the operator's door (basePath) instead of the whole surface.
+export function buildAdminSurface({ agent, gate, allowed, log = console.log,
+  port = null, handle = null, embedded = false, basePath = '/',
+  publicOrigin = null, scheme = null,
+  versionOnDisk = () => localVersion(projectRoot) }) {
+  const json = (res, status, obj) => sendJson(res, status, obj, allowed);
+  const masto = new MastoApi({ agent, log, allowed, scheme, embedded });
+  // The spec's own write API (§6), beside the facade. Its bearer fallback is
+  // the facade's token, so the two surfaces share one notion of the operator.
+  const c2s = new C2S({ agent, log, auth: makeC2sAuth({ agent, masto, log, scheme }) });
+  const streaming = new Streaming({ masto, log, allowed, gate, gateOptional: embedded });
+  // Asked per request, not once here: startAdmin runs before connect, so the
+  // kind is not known yet at mount time.
+  const isGroup = () => agent.store.getConfig()?.kind === 'group';
+  // One setup at a time, and the record outlives the run: a reloaded page
+  // must still find out how the run it started ended. `setup.run` is written
+  // by the setup routes and read by the setup page's state route.
+  const setup_ = { run: null };
+  // New statuses/notifications flow to connected streaming clients live.
+  agent.store.onEvent = (type, obj) => {
+    try {
+      if (type === 'status') streaming.broadcast('update', masto.status(obj));
+      else if (type === 'notification') {
+        streaming.broadcast('notification', masto.notification(obj));
+        // and out to any closed client, via its push subscription
+        masto.pushNotify(obj).catch(e => log(`webpush: ${e.message}`));
+      }
+    } catch (e) { log(`streaming broadcast: ${e.message}`); }
+  };
+
+  // A path as the browser must ask for it: behind the door, prefixed with it.
+  const atPath = (p_) => (basePath === '/' ? p_ : basePath.slice(0, -1) + p_);
+
+  // What every route may reach: the agent and the deployment's facts.
+  const ctx = { agent, log, allowed, embedded, port, handle, publicOrigin, versionOnDisk, isGroup, json, setup: setup_ };
+
+  const handler = async (req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+    // Mastodon-style: the bearer-gated client API and the OAuth + nodeinfo
+    // routes answer any origin — a browser client is served the way any
+    // instance serves it. CORS headers and the preflight make that work; the
+    // bearer stays the only credential, and the Host check below (which is
+    // what stops DNS rebinding) still runs.
+    const apiPath = url.pathname.startsWith('/api/') || url.pathname.startsWith('/oauth/')
+      || url.pathname === '/.well-known/nodeinfo' || url.pathname === '/nodeinfo/2.0';
+    if (apiPath) {
+      res.setHeader('access-control-allow-origin', '*');
+      res.setHeader('access-control-expose-headers', 'Link');
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204, {
+          'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
+          'access-control-allow-headers': 'Authorization, Content-Type, Idempotency-Key',
+          'access-control-max-age': '86400',
+        });
+        res.end();
+        return;
+      }
+    }
+    // Host/Origin firewall: loopback binding alone does not keep a visited web
+    // page (or a rebound DNS name) out. The API paths keep the Host check but
+    // answer a foreign Origin, per above.
+    const bad = checkRequest(req, allowed, { ignoreOrigin: apiPath });
+    if (bad) {
+      log(`refused: ${bad} (${req.method} ${req.url})`);
+      res.writeHead(403, { 'content-type': 'text/plain', ...securityHeaders(allowed, false) });
+      res.end('forbidden\n');
+      return;
+    }
+    let p = url.pathname;
+    // Embedded, the operator's door is one path on the pod's origin. Behind it
+    // is everything that was the admin server; in front of it are the protocol
+    // routes, which have to answer strangers because that is what makes the pod
+    // an instance other software can talk to.
+    let atDoor = !embedded;
+    if (embedded && basePath !== '/'
+      && (p === basePath.slice(0, -1) || p.startsWith(basePath))) {
+      atDoor = true;
+      p = p.slice(basePath.length - 1) || '/';
+    }
+    if (embedded && atDoor && EMBEDDED_CUT.has(p)) {
+      return json(res, 404, { error: 'not available on a server-hosted identity' });
+    }
+    try {
+      // C2S (ActivityPub §6) carries its own authentication — a Solid-OIDC
+      // DPoP proof or the facade's bearer — so the dk-token gate does not
+      // stand in front of it. The Host/Origin firewall above still does.
+      if (p === '/ap/outbox' || p === '/ap/actor' || p === '/ap/inbox') {
+        if (await c2s.handle(req, res, p, url)) return;
+      }
+      // Where a client looks first to find out how to sign in (RFC 8414), and
+      // in front of the door for the same reason C2S is: a client that has to
+      // be handed a secret before it can ask how to sign in cannot set itself
+      // up at all. It names endpoints and nothing else, the endpoints it names
+      // refuse without a password anyway, and the host and origin firewall
+      // above still decides who gets this far.
+      if (p === '/.well-known/oauth-authorization-server') {
+        const scheme = req.socket.encrypted || req.headers['x-forwarded-proto'] === 'https' ? 'https' : 'http';
+        return json(res, 200, masto.authorizationServerMetadata(`${scheme}://${req.headers.host}`));
+      }
+      if (atDoor && gate(req, res)) return;
+      if (p === '/api/v1/streaming/health') {
+        res.writeHead(200, { 'content-type': 'text/plain' }); res.end('OK'); return;
+      }
+      // NodeInfo on the agent origin — clients probe it at login.
+      if (p === '/.well-known/nodeinfo') {
+        return json(res, 200, nodeinfoPointer(
+          `${req.socket.encrypted || req.headers['x-forwarded-proto'] === 'https' ? 'https' : 'http'}://${req.headers.host}/nodeinfo/2.0`));
+      }
+      if (p === '/nodeinfo/2.0') {
+        return json(res, 200, nodeinfoDoc({
+          version: AGENT_VERSION,
+          localPosts: agent.store.countStatuses('post'),
+        }));
+      }
+      // A group serves the client too, as of 2026-08-01. It was withheld on the
+      // reasoning that a group has no timeline a human reads — which was wrong
+      // twice over: a group has statuses (what it carried) and notifications
+      // (who joined), and its operator has a bio to edit and a profile they
+      // want to see the way everyone else does. The surface this opens is a
+      // login and client tokens, and `passwd` has never had a group carve-out,
+      // so a group can be gated exactly like a person before it is exposed.
+      if (p.startsWith('/api/') || p.startsWith('/oauth/')) {
+        if (await masto.handle(req, res, p, url)) return;
+      }
+      if (embedded && !atDoor) return json(res, 404, { error: 'unknown endpoint' });
+      if (req.method === 'GET') {
+        for (const r of ROUTES) if (await r.get?.(p, ctx, req, res, url)) return;
+      }
+      if (req.method === 'GET' || req.method === 'HEAD') {
+        // Our own pages come before the group check: a group is set up in the
+        // browser like anything else, and it has a record to edit. It still
+        // serves no fediverse client — see the 404 two lines down.
+        const mount = webMount(p);
+        if (mount) {
+          // Without the slash a page's own relative <script src> resolves one
+          // level up and 404s — and that is true at any depth, so ask the
+          // filesystem rather than only special-casing the mount itself.
+          const asDir = webDirRedirect(p);
+          if (asDir) {
+            res.writeHead(302, { location: atPath(asDir), ...securityHeaders(allowed, false) });
+            res.end();
+            return;
+          }
+          return serveWeb(res, p, mount, allowed);
+        }
+        // The bare URL means "show me what this agent wants from me now".
+        // Keyed on the credential FILE, never on configured(): a healthy
+        // install whose pod is briefly unreachable reports itself
+        // unconfigured for up to an hour, and must not be sent to setup.
+        if (p === '/' || p === '/index.html') {
+          if (!(agent.home && hasCredential(agent.home))) {
+            res.writeHead(302, { location: atPath(SETUP_PAGE), ...securityHeaders(allowed, false) });
+            res.end();
+            return;
+          }
+          // Opening the bare origin gets this actor's own client — the framed
+          // view with the bar — not the unbound app. The client page frames
+          // `/` itself and that load says so (Sec-Fetch-Dest: iframe), so only
+          // a top-level navigation is sent onward. The one top-level landing
+          // that must NOT be sent onward is the OAuth return, `/?code=…`: the
+          // client registered `/` as its redirect URI and only the app at `/`
+          // can exchange the code — the framed page would drop it and leave
+          // the client logged out.
+          const q = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
+          const oauthLanding = /[?&](code|error)=/.test(q);
+          if (!oauthLanding && req.headers['sec-fetch-dest'] === 'document') {
+            res.writeHead(302, { location: atPath('/admin/client/') + q, ...securityHeaders(allowed, false) });
+            res.end();
+            return;
+          }
+        }
+        return serveStatic(res, p, allowed);
+      }
+      if (req.method !== 'POST') return json(res, 405, { error: 'POST only' });
+      // A body we refuse to read is the caller's mistake, not ours — 400 says
+      // so, where the catch-all below would have called it a server fault.
+      let body;
+      try { body = await readBody(req); }
+      catch (e) { return json(res, 400, { error: e.message }); }
+      if (!OPEN_POSTS.has(p) && !agent.configured()) {
+        return json(res, 409, { error: 'agent not configured — set it up at /admin/setup/' });
+      }
+      if (!embedded && LOCAL_ONLY_POSTS.has(p) && !allowed.isLocalRequest(req)) {
+        return json(res, 403, { error: 'setup and configuration are available on this machine only' });
+      }
+      for (const r of ROUTES) if (await r.post?.(p, body, ctx, req, res)) return;
+      return json(res, 404, { error: 'unknown endpoint' });
+    } catch (e) {
+      // The caller gets the real message: this server binds loopback only, sets
+      // no CORS headers, and its one reader is the operator. Hiding the reason
+      // from them buys nothing and costs a trip to the log. Stack stays here.
+      log(`admin ${p}: ${e.stack || e.message}`);
+      return json(res, 500, { error: e.message || String(e) });
+    }
+  };
+
+  return { handler, masto, c2s, streaming };
+}