fedipod 0.8.0

package/lib/guard.mjs

@@ -0,0 +1,213 @@
+// guard.mjs — the browser-facing firewall. A loopback HTTP server is
+// reachable by any web page the user visits, and DNS rebinding lets such a
+// page keep its own origin while its requests land here — so binding to
+// loopback is NOT an access control. Two header checks close that door:
+//
+//   Host   must name a loopback authority we expect (or an operator-declared
+//          host) — a rebound `evil.example` fails here.
+//   Origin when present, must be one of those same authorities — a
+//          cross-origin fetch/WebSocket fails here even without rebinding.
+//
+// AP_ALLOWED_HOSTS (comma-separated host[:port]) extends the set for
+// deliberate exposure (tailnet name, reverse-proxy domain).
+//
+// An agent also answers at <handle>.localhost, so each identity on a machine
+// gets an origin of its own — one browser storage jar per actor, instead of
+// every agent sharing localhost:<port> and asking which instance you meant.
+// `.localhost` is reserved by RFC 6761 and cannot be delegated in public DNS,
+// so it is not the rebinding hole this file exists to close; the label comes
+// from config, never from a request header, and matching stays exact-string.
+
+const LOOPBACK_NAMES = ['localhost', '127.0.0.1', '[::1]', '::1'];
+
+// A handle earns a named origin only when it is already a clean DNS label.
+// Nothing is rewritten: a mangled name would be a different origin from the
+// one we printed, and the user would land on a 403 with no way to see why.
+export function hostLabel(handle) {
+  const s = String(handle || '').toLowerCase();
+  return /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(s) ? s : null;
+}
+
+// The authorities that are this machine, and only this machine.
+//
+// The port-less form is a DIFFERENT origin: `http://localhost` means port 80
+// and `https://localhost` means 443. Emitting it whatever port we are on put
+// every other local server's pages inside our own origin set — a page served
+// from 127.0.0.1:80 sends `Origin: http://localhost`, which passed the Origin
+// check, and a form POST needs no preflight to reach a write route. So the
+// bare form is emitted only when it really is this server's own authority.
+export function loopbackAuthorities(port, labels = []) {
+  const out = [];
+  const bare = Number(port) === 80 || Number(port) === 443;
+  for (const name of LOOPBACK_NAMES) {
+    out.push(`${name}:${port}`);
+    if (bare) out.push(name);
+  }
+  for (const l of labels) {
+    const label = hostLabel(l);
+    if (!label) continue;
+    out.push(`${label}.localhost:${port}`);
+    if (bare) out.push(`${label}.localhost`);
+  }
+  return out;
+}
+
+const LOOPBACK_ADDRESSES = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+
+// Where the connection came FROM, as opposed to which authority it asked for.
+// Both listeners bind loopback, so today this is true of everything that
+// arrives — including a request relayed by a same-host reverse proxy, which is
+// exactly why it is not what keeps an exposed agent safe (see exposureProblem).
+// It is here so that binding to another address later cannot silently turn the
+// local-only routes into public ones.
+export function isLoopbackSocket(req) {
+  const a = req?.socket?.remoteAddress;
+  if (!a) return false;
+  return LOOPBACK_ADDRESSES.has(a) || a.startsWith('127.');
+}
+
+// AP_ALLOWED_HOSTS is the documented way to put the agent on a tailnet name or
+// behind a reverse proxy. Doing so removes every transport signal that told the
+// operator apart from everyone else: the listeners bind loopback, so exposure
+// means something on this machine is relaying, and a stock
+// `proxy_pass http://127.0.0.1:<port>;` rewrites Host to a loopback authority
+// and connects from loopback. Every caller then looks local, which is what the
+// local-only routes and the password-less authorize path were trusting.
+//
+// A secret is all that is left, and AP_GATE_TOKEN is the one every route
+// checks — a uiPassword guards the OAuth login and nothing else. Returns a
+// reason string when the agent must not start, or null.
+export function exposureProblem({ allowedHosts, gateToken } = {}) {
+  const exposed = String(allowedHosts || '').split(',').map(s => s.trim()).filter(Boolean);
+  if (!exposed.length || gateToken) return null;
+  return `AP_ALLOWED_HOSTS names ${exposed.join(', ')}, but AP_GATE_TOKEN is not set.\n`
+    + 'An exposed agent cannot tell your requests from anyone else\'s — a reverse proxy\n'
+    + 'rewrites Host to a loopback authority and connects from loopback, so every caller\n'
+    + 'looks like this machine. Without a shared secret that means the admin API, the\n'
+    + 'setup routes and the OAuth mint answer whoever reaches the address.\n\n'
+    + 'Either set AP_GATE_TOKEN to a secret (send it as the x-dk-token header, or visit\n'
+    + '?dk-token=<secret> once to be given the cookie), or unset AP_ALLOWED_HOSTS.';
+}
+
+export function allowedAuthorities(port, labels = []) {
+  const extra = String(process.env.AP_ALLOWED_HOSTS || '')
+    .split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+  return new Set([...loopbackAuthorities(port, labels), ...extra]);
+}
+
+// The set has to stay live. startAdmin runs before connect, so an unconfigured
+// agent has no handle yet — and MastoApi consults this same object to decide
+// whether an OAuth redirect_uri is one of ours, so a snapshot taken at listen
+// time would reject the named origin for the life of the process.
+export class Authorities {
+  constructor(port, handle = null, extraPorts = []) {
+    this.port = port;
+    // The https listener's port: same machine, same names, second authority.
+    this.extraPorts = extraPorts.filter(Boolean);
+    this.label = null;
+    this.set = null;
+    this.local = null;
+    this.rebuild();
+    this.setHandle(handle);
+  }
+
+  rebuild() {
+    const labels = this.labels();
+    this.set = allowedAuthorities(this.port, labels);
+    this.local = new Set(loopbackAuthorities(this.port, labels));
+    for (const p of this.extraPorts) {
+      for (const a of loopbackAuthorities(p, labels)) { this.set.add(a); this.local.add(a); }
+    }
+  }
+
+  // Returns true when the named origin actually changed.
+  setHandle(handle) {
+    const label = hostLabel(handle);
+    if (label === this.label) return false;
+    this.label = label;
+    this.rebuild();
+    return true;
+  }
+
+  labels() { return this.label ? [this.label] : []; }
+
+  has(authority) { return this.set.has(authority); }
+
+  // Machine-local, ignoring AP_ALLOWED_HOSTS: an agent deliberately exposed
+  // under a tailnet name answers the fediverse there, but must not offer
+  // account creation or config editing over it.
+  isLocal(host) { return this.local.has(String(host || '').toLowerCase()); }
+
+  // The Host header says which authority the client asked for; the socket says
+  // where it came from. A local-only route wants both to agree. Neither
+  // survives a same-host proxy on its own — exposureProblem is what covers
+  // that case — but requiring both costs nothing and closes the plain forgery.
+  isLocalRequest(req) {
+    return isLoopbackSocket(req) && this.isLocal(req?.headers?.host);
+  }
+}
+
+// The authority set for an identity served by somebody else's server: one
+// origin, the pod's own, and no notion of "this machine" at all. Nothing is
+// local here — a request from the next room and one from the far side of the
+// world arrive the same way — so the routes that were local-only are guarded
+// by the door's secret instead.
+export class FixedAuthorities {
+  constructor(origin) {
+    const u = new URL(origin);
+    this.host = u.host.toLowerCase();
+    this.port = Number(u.port) || (u.protocol === 'https:' ? 443 : 80);
+    this.secure = u.protocol === 'https:';
+    this.label = null;
+    this.set = new Set([this.host]);
+    this.extraPorts = [];
+  }
+
+  rebuild() { /* one origin, fixed at construction */ }
+
+  setHandle() { return false; }        // the origin does not follow the handle
+
+  labels() { return []; }
+
+  has(authority) { return this.set.has(String(authority || '').toLowerCase()); }
+
+  isLocal() { return false; }
+
+  isLocalRequest() { return false; }
+
+  // What a page here may open a streaming socket to. Built from the pod's own
+  // origin: the loopback list would leave the socket refused by the page's own
+  // content-security-policy, with nothing in the console to say why.
+  wsAuthorities() { return [`${this.secure ? 'wss' : 'ws'}://${this.host}`]; }
+}
+
+const authorityOf = (originHeader) => {
+  try { return new URL(originHeader).host.toLowerCase(); } catch { return null; }
+};
+
+// Returns null when the request is acceptable, else a reason string.
+// `ignoreOrigin` keeps the Host check (what stops DNS rebinding) while letting
+// a foreign Origin through — the bearer-gated API answers any origin the way
+// a Mastodon server does, and a websocket with a live token likewise.
+export function checkRequest(req, allowed, { ignoreOrigin = false } = {}) {
+  const host = String(req.headers.host || '').toLowerCase();
+  if (!host || !allowed.has(host)) return `unexpected Host "${host || '(none)'}"`;
+  if (ignoreOrigin) return null;
+  const origin = req.headers.origin;
+  // 'null' is what a sandboxed/file: page sends — never trusted here.
+  if (origin && origin !== 'null') {
+    const oh = authorityOf(origin);
+    if (!oh || !allowed.has(oh)) return `cross-origin request from "${origin}"`;
+  } else if (origin === 'null') {
+    return 'opaque origin';
+  }
+  return null;
+}
+
+// Same-site navigations and typed URLs only — blocks a visited page from
+// driving a top-level navigation into an endpoint that mints credentials.
+// Absent header (older browsers, curl) is allowed: Host/Origin still apply.
+export function isCrossSiteNavigation(req) {
+  const site = req.headers['sec-fetch-site'];
+  return site === 'cross-site';
+}

package/lib/home.mjs

@@ -0,0 +1,161 @@
+// Where an install keeps its credential, signing keys, pidfile and log.
+//
+// The root was `~/.activitypod`, then `~/.solid-activitypub`, before the
+// rename to fedipod. An install that already has one keeps using it: that
+// directory holds the credential and the private key, and moving those is the
+// owner's decision rather than an upgrade's side effect. `fedipod home
+// --to <dir>` is how you take the new name when you want it.
+//
+// Resolve ONCE and derive `profiles/` from the same answer. Deciding the two
+// separately is how `--profile solo` ends up looking in a different tree from
+// the default agent.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const CURRENT_ROOT = '.fedipod';
+export const LEGACY_ROOTS = ['.solid-activitypub', '.activitypod'];  // most recent first
+
+// Existing install wins over the new name; a fresh one gets the new name.
+export function apRoot(homedir = os.homedir()) {
+  const current = path.join(homedir, CURRENT_ROOT);
+  if (fs.existsSync(current)) return current;
+  for (const name of LEGACY_ROOTS) {
+    const legacy = path.join(homedir, name);
+    if (fs.existsSync(legacy)) return legacy;
+  }
+  return current;
+}
+
+export const isLegacyRoot = (root) => LEGACY_ROOTS.includes(path.basename(root));
+
+// Write one of this home's files without a window in which it is half there.
+//
+// lib/storage.mjs goes to the trouble of tmp+rename for state documents that
+// its own header calls rebuildable from the pod. The files here are the ones
+// that are NOT: keys.json is the private key remote servers have cached, and
+// credential.json holds a secret a Solid server mints once and will not mint
+// again. A plain writeFileSync truncates first, so a crash, a power loss or a
+// full disk between truncate and write leaves an empty or half-written file
+// where the identity used to be.
+//
+// rename(2) is atomic on POSIX, so a reader — or a backup running at the wrong
+// moment — sees either the old file or the new one. fsync before it, so the
+// content is on the platter and not merely in the page cache when the rename
+// lands. Windows has no atomic rename over an existing file; there the copy
+// path is still better than a truncate, and this is a best effort by design.
+export function writeFileAtomic(file, body, { mode = 0o600 } = {}) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const fd = fs.openSync(tmp, 'w', mode);
+  try {
+    fs.writeFileSync(fd, body);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, file);
+}
+
+// The same, for the JSON these files all happen to be.
+export function writeJsonAtomic(file, obj, opts) {
+  writeFileAtomic(file, JSON.stringify(obj, null, 2) + '\n', opts);
+}
+
+export const profilesDir = (root) => path.join(root, 'profiles');
+
+// The root an arbitrary home belongs to. `<root>/profiles/<name>` is a profile;
+// anything else is its own root — so a custom AP_HOME reports no neighbours,
+// which is the truth rather than a special case.
+export function rootOf(home) {
+  const resolved = path.resolve(home);
+  const parent = path.dirname(resolved);
+  return path.basename(parent) === 'profiles' ? path.dirname(parent) : resolved;
+}
+
+// Every identity under a root — all of them under `profiles/`, none of them the
+// root itself. Callers read `agent.json` from these — a port and a handle.
+// Nothing here, and nothing that uses it, opens a sibling's credential or keys.
+//
+// The root used to BE one of these, and had no name, so this function invented
+// `(default)` for it at display time. That was the tell: a thing you have to
+// name when you show it does not have an identity, it has a position. It also
+// meant one identity's home contained all the others — back it up and you
+// backed up everyone; delete it and you deleted everyone.
+export function identityHomes(root) {
+  const homes = [];
+  try {
+    for (const name of fs.readdirSync(profilesDir(root)).sort()) {
+      const dir = path.join(profilesDir(root), name);
+      if (fs.statSync(dir).isDirectory()) homes.push({ name, dir });
+    }
+  } catch { /* no identities yet */ }
+  return homes;
+}
+
+// The root's own record. Today it holds one thing: which identity was last
+// started, which is what a plain command means afterwards. Nobody sets it —
+// using an identity IS setting it, so there is no default to configure and no
+// way for the configured answer to drift from the one you actually work in.
+export const ROOT_FILE = 'root.json';
+
+export function readRoot(root) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, ROOT_FILE), 'utf8')) || {}; }
+  catch { return {}; }
+}
+
+export function writeRoot(root, fields) {
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  const rec = { ...readRoot(root), ...fields };
+  writeJsonAtomic(path.join(root, ROOT_FILE), rec);
+  return rec;
+}
+
+// Which identity you get with no `--profile`: the last one started. Failing
+// that, one identity is unambiguous and needs no ceremony. Two, neither ever
+// started, is a genuine question — and the answer is to ask rather than pick,
+// because picking silently would be picking someone's fediverse account.
+export function defaultProfile(root) {
+  const named = readRoot(root).default;
+  // Only a home holding a credential counts. A setup that was abandoned leaves a
+  // directory behind, and letting that become the default would answer "which
+  // identity" with one that does not exist yet.
+  const real = identityHomes(root).filter(h => fs.existsSync(path.join(h.dir, 'credential.json')));
+  if (named && real.some(h => h.name === named)) return named;
+  if (named) return { missing: named };
+  return real.length === 1 ? real[0].name : null;
+}
+
+export const profileHome = (root, name) => path.join(profilesDir(root), name);
+
+// A root from before every identity moved under profiles/. Its presence is what
+// every command checks to tell you to migrate, rather than quietly doing it —
+// this directory holds a private key.
+export const rootHoldsIdentity = (root) => fs.existsSync(path.join(root, 'credential.json'));
+
+
+// For DISPLAY only: `~/.fedipod` reads at a glance where
+// `/home/jeff/.fedipod` has to be parsed, and the home directory is
+// the least interesting part of every path this prints. A `file:` URL is a path
+// wearing a scheme, so it is shown as the path — which is also what you would
+// type, since `state --to` takes either.
+//
+// Never used to build a path. `~` is the shell's, not the filesystem's, and
+// anything that resolves one must expand it first.
+export function tildify(p, homedir = os.homedir()) {
+  if (!p) return p;
+  let s = String(p);
+  if (s.startsWith('file://')) { try { s = fileURLToPath(s); } catch { return s; } }
+  if (s === homedir) return '~';
+  return s.startsWith(homedir + path.sep) ? '~' + s.slice(homedir.length) : s;
+}
+
+// Using an identity is what makes it the default. Called when an agent starts
+// for one — not on every read, or `--profile other status` would quietly move
+// the machine's idea of "you" while only asking a question.
+export function recordLastUsed(root, name) {
+  if (!root || !name || readRoot(root).default === name) return;
+  try { writeRoot(root, { default: name, at: new Date().toISOString() }); } catch { /* not fatal */ }
+}

package/lib/httpsig.mjs

@@ -0,0 +1,109 @@
+// httpsig.mjs — inbound HTTP-Signature verification, and the verification
+// receipt that carries the outcome from wherever the verify happened (an
+// always-on gateway, or the agent's own endpoint when it is publicly reachable)
+// into the drain, which cannot see the delivery's headers.
+//
+// We SIGN outbound with Fedify draft-cavage (lib/deliver.mjs); we VERIFY with
+// the same library, so the signing-string reconstruction can never drift out
+// of step with what we produce. The one thing Fedify must be prevented from
+// doing on its own is fetching an attacker-named key over an unguarded socket
+// — so the key deref is injected as a loader that goes through safefetch.
+
+import crypto from 'node:crypto';
+import { verifyRequest } from '@fedify/fedify/sig';
+import { assertPublicUrl, safeFetch, readCapped } from './safefetch.mjs';
+
+// An SSRF-safe JSON-LD document loader for Fedify's key fetch. The keyId in a
+// delivery is chosen by the sender, so every deref it triggers is untrusted
+// input and must pass the same address policy as the rest of our outbound
+// path. `skipActor` forces a network read past any cache, for the one refetch
+// a rotated key needs.
+export function makeSafeLoader({ getActors = null, fetchImpl = fetch } = {}) {
+  return async (url) => {
+    // A cached actor document short-circuits the network entirely — and it was
+    // only cached after its own origin vouched for its id (intake.fetchAP).
+    if (getActors) {
+      const hit = getActors()[url];
+      if (hit) return { document: hit, documentUrl: url, contextUrl: null };
+    }
+    await assertPublicUrl(url);
+    const res = await safeFetch(url, {
+      headers: { accept: 'application/activity+json, application/ld+json' },
+    }, fetchImpl);
+    if (res.status >= 400) throw new Error(`key fetch ${url} → ${res.status}`);
+    const document = JSON.parse(await readCapped(res));
+    return { document, documentUrl: url, contextUrl: null };
+  };
+}
+
+// Verify a delivery's signature. `request` is a WHATWG Request (the gateway
+// has one natively; an agent-side endpoint builds one from its req). Returns a
+// normalized result both the gateway and the drain understand — never throws
+// on a bad signature, because "unverified" is a routine outcome, not an error.
+export async function verifyHttpSignature(request, { documentLoader, keyCache, timeWindow } = {}) {
+  const hadSig = request.headers.get('signature') != null;
+  let key = null;
+  try {
+    key = await verifyRequest(request, {
+      documentLoader,
+      ...(keyCache ? { keyCache } : {}),
+      timeWindow: timeWindow ?? { hours: 1 },
+    });
+  } catch {
+    key = null;   // a loader that refused (SSRF, 401 from a secure-mode pod) → unverified
+  }
+  if (key) {
+    return {
+      verified: true, method: 'draft-cavage',
+      keyId: key.id?.href ?? null, actor: key.ownerId?.href ?? null, reason: null,
+      checks: { signature: true, digest: true, dateSkew: true, keyFetched: true },
+    };
+  }
+  return {
+    verified: false, method: hadSig ? 'draft-cavage' : 'none',
+    keyId: null, actor: null,
+    // The distinction the receipt needs: a forgery (present but invalid) is
+    // dropped at the edge; an absent or unfetchable-key signature degrades to
+    // buffered-unverified, exactly as an install with no gateway behaves.
+    reason: hadSig ? 'bad-signature-or-key-unfetchable' : 'no-signature',
+    checks: { signature: false },
+  };
+}
+
+// The receipt: what the door concluded, HMAC-stamped so the drain can trust it
+// even while the inbox is still public-Append (a forger without the secret
+// cannot mint `verified: true`). The HMAC is over the receipt minus the hmac
+// field itself, with sorted keys so gateway and drain canonicalize alike.
+function canonical(obj) {
+  return JSON.stringify(obj, Object.keys(obj).filter(k => k !== 'hmac').sort());
+}
+
+export function makeReceipt(result, { gateway = null } = {}) {
+  return {
+    v: 1,
+    verified: !!result.verified,
+    method: result.method,
+    keyId: result.keyId,
+    actor: result.actor,
+    checks: result.checks,
+    reason: result.reason,
+    gateway,
+  };
+}
+
+export function signReceipt(receipt, secret) {
+  const hmac = crypto.createHmac('sha256', secret).update(canonical(receipt)).digest('base64');
+  return { ...receipt, hmac };
+}
+
+// True only when the receipt carries a valid HMAC for `secret`. A missing
+// secret, a missing hmac, or a mismatch all read as "not ours" → the drain
+// treats the receipt as absent (today's unverified behavior). timingSafeEqual
+// over equal-length buffers; unequal lengths are a straight mismatch.
+export function verifyReceipt(receipt, secret) {
+  if (!receipt || typeof receipt !== 'object' || !receipt.hmac || !secret) return false;
+  const expected = crypto.createHmac('sha256', secret).update(canonical(receipt)).digest();
+  let given;
+  try { given = Buffer.from(receipt.hmac, 'base64'); } catch { return false; }
+  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
+}