fedipod-server 0.11.0 → 0.13.0

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

@@ -0,0 +1,199 @@
+// gateway.mjs — the inbox gateway lifecycle: configure, mode, check, attach
+// through a front, forget.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+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) {
+    // The inbox gateway lifecycle (opt-in). `configure` points at a
+    // deployed gateway (and reveals the HMAC secret once, to paste into
+    // its env); `mode` walks off→shadow→trust→locked and back, each step
+    // reversible; `forget` clears it and restores the pod inbox.
+    case '/gateway': {
+      const cfg = { ...agent.store.getConfig() };
+      const g = { ...(cfg.gateway || {}) };
+      const inboxUrl = agent.publisher?.urls?.inbox;
+      // Availability is a read: answered before the lease takeover below,
+      // which every real gateway change does want.
+      if (body.action === 'check') {
+        const front = String(body.front || '').replace(/\/+$/, '');
+        try { new URL(front); } catch { return json(res, 400, { error: 'front must be a gateway origin URL' }); }
+        const chk = await fetch(`${front}/api/handle?handle=${encodeURIComponent(String(body.handle || '').toLowerCase())}`,
+          { headers: { accept: 'application/json' } }).then((r) => r.json()).catch(() => null);
+        if (!chk) return json(res, 502, { error: `${front} did not answer its handle check` });
+        return json(res, 200, { available: !!chk.available, reason: chk.reason || null });
+      }
+      await agent.requestTakeover?.();
+      const persist = async () => {
+        cfg.gateway = g; agent.store.setConfig(cfg);
+        if (agent.publisher) agent.publisher.config.gateway = g;
+        await agent.store.flush();
+      };
+      // Fronting renames the actor's ids; the signing key is the same
+      // identity's and moves with it, wherever the key record lives.
+      const restampKeys = async (actorId) => {
+        try {
+          const kp = path.join(agent.home, 'keys.json');
+          const rec = JSON.parse(fs.readFileSync(kp, 'utf8'));
+          if (rec.mintedFor) { rec.mintedFor = actorId; fs.writeFileSync(kp, JSON.stringify(rec)); return; }
+        } catch { /* not local — try pod state */ }
+        const podRec = agent.store.read('keys.json', null);
+        if (podRec?.mintedFor) { podRec.mintedFor = actorId; agent.store.write('keys.json', podRec); await agent.store.flush(); }
+      };
+      const podActorId = () => {
+        const base = cfg.remotePod.endsWith('/') ? cfg.remotePod : `${cfg.remotePod}/`;
+        const root = cfg.root ? (cfg.root.endsWith('/') ? cfg.root : `${cfg.root}/`) : 'activitypods-js/';
+        return `${base}${root}ap/actor`;
+      };
+      // The reply first, the restart a beat later — same shape as /update.
+      const selfRestart = (why) => setTimeout(() => {
+        log(why);
+        if (process.env.INVOCATION_ID) { process.exit(1); return; }   // systemd: Restart=on-failure respawns
+        const child = spawn(process.execPath, process.argv.slice(1),
+          { detached: true, stdio: 'ignore', env: process.env });
+        child.unref();
+        setTimeout(() => process.exit(0), 300);
+      }, 200);
+      if (body.action === 'configure') {
+        if (!/^https:\/\/\S+$/.test(String(body.url || ''))) return json(res, 400, { error: 'gateway url must be https' });
+        if (!/^https?:\/\/\S+$/.test(String(body.webId || ''))) return json(res, 400, { error: 'gateway webId must be a URL' });
+        g.url = String(body.url); g.webId = String(body.webId);
+        g.hmacSecret = g.hmacSecret || crypto.randomBytes(32).toString('base64');
+        g.mode = g.mode || 'off';
+        // The fronted actor URL, for a multi-user front that gives this
+        // identity a @name@front handle: the agent then publishes and signs
+        // under it. Optional; setting it on a published identity renames
+        // every id (a Move), so it belongs at setup or a fresh identity.
+        if ('frontActor' in body) {
+          const fa = String(body.frontActor || '');
+          if (fa && !/^https:\/\/\S+\/ap\/actor$/.test(fa)) {
+            return json(res, 400, { error: 'frontActor must be an https …/ap/actor URL' });
+          }
+          g.frontActor = fa || undefined;
+        }
+        await persist();
+        // The one time the secret is returned: the operator pastes it into
+        // the gateway's deploy env. /gateway GET never reveals it again.
+        return json(res, 200, { ok: true, mode: g.mode, url: g.url, webId: g.webId, hmacSecret: g.hmacSecret });
+      }
+      if (body.action === 'mode') {
+        const target = body.mode;
+        if (!['off', 'shadow', 'trust', 'locked'].includes(target)) {
+          return json(res, 400, { error: 'mode must be off, shadow, trust or locked' });
+        }
+        if (target !== 'off' && !g.url) return json(res, 400, { error: 'point at a gateway first (action: configure)' });
+        // Locking needs the door's own WebID to name in the ACL. Without it
+        // the mode used to persist and the ACL be written for an undefined
+        // agent, leaving config and pod disagreeing about who may write.
+        if (target === 'locked' && !g.webId) {
+          return json(res, 400, {
+            error: 'locked needs the gateway\'s WebID — set it with action: configure, webId: <door-webid>',
+          });
+        }
+        const prev = g.mode || 'off';
+        // The ACL first: a lock that fails must not leave the mode recorded
+        // as locked while the pod still accepts anyone's writes.
+        if (target === 'locked') await agent.publisher?.lockInboxToGateway(g.webId);
+        else if (prev === 'locked' && inboxUrl) await agent.remote.setAcl(inboxUrl, ['Append']);
+        g.mode = target;
+        await persist();
+        // Advertisement flips only when crossing the off boundary (the actor
+        // doc's inbox changes → publishProfile republishes, digest-gated).
+        if ((prev === 'off') !== (target === 'off')) await agent.publisher?.publishProfile();
+        else if (target !== 'off') await agent.publisher?.publishGatewayPolicy().catch(() => {});
+        return json(res, 200, { ok: true, mode: g.mode });
+      }
+      // Attach through a multi-user front (fedipod.net and kin): the agent
+      // proves the pod with its own credential — no browser, no password —
+      // and the front answers with the door and the receipt secret.
+      if (body.action === 'attach') {
+        const front = String(body.front || '').replace(/\/+$/, '');
+        let fu;
+        try { fu = new URL(front); } catch { return json(res, 400, { error: 'front must be the gateway origin, like https://fedipod.net' }); }
+        if (fu.protocol !== 'https:' && !/^(localhost|127\.0\.0\.1)$|\.localhost$/.test(fu.hostname)) {
+          return json(res, 400, { error: 'front must be https' });
+        }
+        if (agent.embedded) {
+          return json(res, 400, { error: 'this identity runs inside its pod server and has no portable credential — attach from a standalone agent' });
+        }
+        const named = !!String(body.handle || '').trim();
+        let handle = String(body.handle || cfg.handle || '').toLowerCase().trim();
+        if (!handle) return json(res, 400, { error: 'a name at the gateway is required' });
+        const fronted = body.fronted === true;
+        // Availability first, for a clean answer before anything is created.
+        const avail = async (h) => fetch(`${front}/api/handle?handle=${encodeURIComponent(h)}`,
+          { headers: { accept: 'application/json' } }).then((r) => r.json()).catch(() => null);
+        let chk = await avail(handle);
+        if (!chk) return json(res, 502, { error: `${front} did not answer its handle check` });
+        // An unnamed door name is plumbing nobody reads: walk to a free
+        // variant instead of failing over a label the user never chose.
+        if (!chk.available && !named) {
+          for (let i = 2; i <= 9 && !chk.available; i++) {
+            const cand = `${handle}${i}`;
+            const c = await avail(cand);
+            if (c?.available) { handle = cand; chk = c; }
+          }
+        }
+        if (!chk.available) return json(res, 409, { error: chk.reason || `the name ${handle} is taken at ${front}` });
+        const frontActor = `${front}/u/${handle}/ap/actor`;
+        if (g.frontActor && (!fronted || g.frontActor !== frontActor)) {
+          return json(res, 400, { error: `this identity already fronts through ${g.frontActor} — changing a published front renames every id; detach first if you mean it` });
+        }
+        const attach = await agent.remote.session.fetch(`${front}/api/attach`, {
+          method: 'POST', headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ handle, podHome: agent.urls.home, kind: cfg.kind || 'person', fronted }),
+        }).catch(() => null);
+        if (!attach) return json(res, 502, { error: `${front} did not answer the attach` });
+        const d = await attach.json().catch(() => ({}));
+        if (attach.status !== 201) {
+          return json(res, attach.status >= 400 && attach.status < 500 ? attach.status : 502,
+            { error: d.error || `attach failed (HTTP ${attach.status})` });
+        }
+        g.url = String(d.doorInbox || `${front}/u/${handle}/ap/inbox/`);
+        if (d.hmacSecret) g.hmacSecret = String(d.hmacSecret);
+        if (fronted) g.frontActor = String(d.frontActor || frontActor);
+        if (!g.mode || g.mode === 'off') g.mode = 'shadow';
+        await persist();
+        // Inbox-only applies live: the actor republishes advertising the
+        // door. A front carries new ids, which are wired at startup — so a
+        // fronted attach restarts this agent itself, the reply going out
+        // first so it is not taken down with the process.
+        if (!fronted) {
+          await agent.publisher?.publishProfile();
+          await agent.publisher?.publishGatewayPolicy?.().catch(() => {});
+          return json(res, 200, { ok: true, mode: g.mode, url: g.url });
+        }
+        await restampKeys(g.frontActor);
+        json(res, 200, { ok: true, mode: g.mode, url: g.url,
+          frontActor: g.frontActor, address: d.address || null, restarting: true });
+        selfRestart('restarting to publish under the front');
+        return true;
+      }
+      if (body.action === 'forget') {
+        const wasLocked = g.mode === 'locked';
+        const wasFronted = !!g.frontActor;
+        delete cfg.gateway; agent.store.setConfig(cfg);
+        if (agent.publisher) agent.publisher.config.gateway = undefined;
+        await agent.store.flush();
+        if (wasLocked && inboxUrl) await agent.remote.setAcl(inboxUrl, ['Append']).catch(() => {});
+        if (wasFronted) {
+          // Going home renames every id back to the pod: key and process
+          // follow, the same way attach came.
+          await restampKeys(podActorId());
+          json(res, 200, { ok: true, mode: 'off', forgotten: true, restarting: true });
+          selfRestart('restarting under the pod\'s own ids');
+          return true;
+        }
+        await agent.publisher?.publishProfile();   // re-advertise the pod inbox
+        return json(res, 200, { ok: true, mode: 'off', forgotten: true });
+      }
+      return json(res, 400, { error: 'action must be configure, mode, check, attach or forget' });
+    }
+    default: return false;
+  }
+}

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

@@ -0,0 +1,191 @@
+// lifecycle.mjs — what happens to the identity over time: draining and
+// pruning the inbox, rebuilding posts, republishing, parking and reviving,
+// rotating the key, moving, aliases, importing, retiring.
+
+import { resolveHandle } from '../../../core/social.mjs';
+import { webfingerHost } from '../../../core/wire.mjs';
+import { normalizeImport, IMPORT_KINDS } from '../../../connections/import.mjs';
+
+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) {
+    // Both of these DELETE from the pod's inbox, which is the one thing the
+    // lease exists to keep to a single agent. A viewer must claim it first
+    // and give up if it cannot — the facade has refused viewer writes since
+    // multi-device landed, and these two were simply missed.
+    case '/drain': {
+      if (!await agent.requestTakeover?.()) {
+        return json(res, 503, { error: 'another agent is active for this pod — it is doing the draining' });
+      }
+      await agent.intake.drain();
+      return json(res, 200, agent.status());
+    }
+    // The owner's answer to "your inbox is very full". Never automatic:
+    // discarding someone's mail is their call, not the agent's.
+    case '/inbox/prune': {
+      if (!body.before) return json(res, 400, { error: 'before (a date) required' });
+      if (!await agent.requestTakeover?.()) {
+        return json(res, 503, { error: 'another agent is active for this pod — discard from that one' });
+      }
+      return json(res, 200, await agent.intake.prune({
+        before: body.before,
+        ...(body.keepConcerning ? { keepConcerning: true } : {}),
+      }));
+    }
+    // Put back the posts a lost or restored machine no longer knows about,
+    // from what the pod still serves. It writes the statuses store, which is
+    // the lease's business, so it refuses the same way the drain does.
+    case '/rebuild': {
+      if (!await agent.requestTakeover?.()) {
+        return json(res, 503, { error: 'another agent is active for this pod — rebuild from that one' });
+      }
+      return json(res, 200, await agent.publisher.rebuildStatuses({ fromNotes: !!body.fromNotes }));
+    }
+    case '/publish-profile': {
+      // The explicit "republish now" control. Asking for it IS the reason.
+      const r = await agent.publisher.publishProfile({ force: true });
+      return json(res, 200, { ok: true, ...(r?.unreachable?.length ? { unreachable: r.unreachable } : {}) });
+    }
+    // ---- lifecycle: what the CLI calls park | revive | rotate-key | retire ----
+    // Each claims the lease first, for the same reason /config does: someone
+    // acting on this page outranks an idle active agent on another device.
+    // Asking first is the page's job — see the warnings in its markup.
+    case '/park': {
+      await agent.requestTakeover?.();
+      return json(res, 200, { ok: true, ...await agent.park() });
+    }
+    case '/revive': {
+      await agent.requestTakeover?.();
+      return json(res, 200, { ok: true, ...await agent.revive() });
+    }
+    case '/rotate-key': {
+      await agent.requestTakeover?.();
+      const r = await agent.rotateKey();
+      return json(res, 200, { ok: true, changed: !!r?.changed });
+    }
+    // Hand the identity on. Federated and effectively one-way: the Move
+    // tells every follower's server to migrate them, and the actor is left
+    // advertising movedTo so the old handle redirects. Same typed-handle
+    // interlock as retire — a stray click cannot produce it.
+    case '/move': {
+      if (!body.target) return json(res, 400, { error: 'target required' });
+      if (!body.confirm || body.confirm !== agent.store.getConfig()?.handle) {
+        return json(res, 400, { error: 'type the handle to confirm' });
+      }
+      await agent.requestTakeover?.();
+      // A handle is not an actor URI, and the Move's target has to be one or
+      // the far side has nothing to migrate anyone to. The CLI resolves it
+      // the same way; doing it here rather than in the page keeps the one
+      // WebFinger lookup on the side that already knows how.
+      let target = String(body.target).trim();
+      if (!/^https?:\/\//.test(target)) {
+        const doc = await resolveHandle(agent, target);
+        if (!doc?.id) return json(res, 400, { error: `could not resolve ${target}` });
+        target = doc.id;
+      }
+      return json(res, 200, { ok: true, ...await agent.moveTo(target) });
+    }
+    // The inbound half of a migration: list an old account elsewhere in
+    // this actor's alsoKnownAs, which is what the old server checks for
+    // before it will send a Move here. Whatever is entered is resolved to
+    // the account's canonical id — the check on the far side is an exact
+    // string match, so a pasted profile URL stored as typed would fail it.
+    case '/alias': {
+      const urls = agent.publisher?.urls;
+      if (!urls) return json(res, 409, { error: 'agent not connected yet' });
+      if (!body.add && !body.remove) return json(res, 400, { error: 'add or remove required' });
+      await agent.requestTakeover?.();
+      const cfg = { ...agent.store.getConfig() };
+      const aliases = [...(cfg.aliases || [])];
+      if (body.add) {
+        // A Move target nobody can resolve is a landing pad nobody lands on.
+        if (!webfingerHost(urls.base) && !cfg.gateway?.frontActor) {
+          return json(res, 400, {
+            error: 'this pod is a path on a shared host, so WebFinger cannot answer for it '
+              + '— other servers could never resolve this account as a Move target',
+          });
+        }
+        const input = String(body.add).trim().replace(/^@/, '');
+        let doc = /^https?:\/\//.test(input)
+          ? await agent.intake.fetchAP(input).catch(() => null)
+          : await resolveHandle(agent, input).catch(() => null);
+        // A URL may answer with any id it likes; before that id is stored
+        // it must vouch for itself — the intake's verify-by-deref.
+        if (doc?.id && /^https?:\/\//.test(input) && doc.id !== input) {
+          const own = await agent.intake.fetchAP(doc.id).catch(() => null);
+          doc = own?.id === doc.id ? own : null;
+        }
+        if (!doc?.id) {
+          return json(res, 400, { error: `could not fetch the old account (${input}) — it must exist and answer` });
+        }
+        if (doc.id === urls.actor) return json(res, 400, { error: 'that is this account' });
+        if (!aliases.includes(doc.id)) aliases.push(doc.id);
+      } else {
+        const target = String(body.remove).trim();
+        if (!aliases.includes(target)) return json(res, 404, { error: 'no such alias' });
+        // Follower servers process a Move on their own retry schedules,
+        // over days — an alias removed early strands the late ones.
+        if (!body.confirm) {
+          return json(res, 409, {
+            error: 'servers still retrying the Move check this alias and would strand '
+              + 'their followers — send confirm: true to remove it anyway',
+          });
+        }
+        aliases.splice(aliases.indexOf(target), 1);
+      }
+      cfg.aliases = aliases;
+      agent.store.setConfig(cfg);
+      agent.publisher.config.aliases = aliases;
+      await agent.store.flush();
+      const pub = await agent.publisher.publishProfile();
+      return json(res, 200, {
+        ok: true, aliases,
+        ...(pub?.unreachable?.length ? { unreachable: pub.unreachable } : {}),
+      });
+    }
+    // Stage a CSV export from the old account. Rows are applied by the
+    // agent's paced worker, not in this request — big lists take a while,
+    // and GET /import is the window onto how far it has gotten.
+    case '/import': {
+      if (!agent.importer) return json(res, 409, { error: 'agent not connected yet' });
+      // Unlike the one-shot routes, staging arms a worker that keeps
+      // writing for minutes — a device that could not take the lease must
+      // not run one alongside the device that holds it.
+      const took = await agent.requestTakeover?.();
+      if (took === false) {
+        return json(res, 503, { error: 'another device is active for this pod — import from there' });
+      }
+      if (body.clear === true) {
+        agent.importer.clear();
+        return json(res, 200, { ok: true, cleared: true });
+      }
+      if (!IMPORT_KINDS.includes(body.kind)) {
+        return json(res, 400, { error: `kind must be one of: ${IMPORT_KINDS.join(', ')}` });
+      }
+      if (typeof body.text !== 'string' || !body.text.trim()) {
+        return json(res, 400, { error: 'text required — the CSV file contents' });
+      }
+      const { values, invalid } = normalizeImport(body.kind, body.text);
+      const r = agent.importer.stage(body.kind, values);
+      await agent.store.flush();
+      return json(res, 200, {
+        ok: true, kind: body.kind, ...r,
+        invalid: invalid.length,
+        ...(invalid.length ? { invalidSample: invalid.slice(0, 5) } : {}),
+      });
+    }
+    case '/retire': {
+      // Irreversible and federated: a Delete leaves for every follower and
+      // the actor becomes a Tombstone. The typed handle is the interlock —
+      // a stray click cannot produce it, and nor can anything that never
+      // read the record.
+      if (!body.confirm || body.confirm !== agent.store.getConfig()?.handle) {
+        return json(res, 400, { error: 'type the handle to confirm' });
+      }
+      await agent.requestTakeover?.();
+      return json(res, 200, { ok: true, ...await agent.publisher.retireActor() });
+    }
+    default: return false;
+  }
+}