fedipod 0.14.1 → 0.17.0

package/lib/admin.mjs

@@ -27,7 +27,7 @@ import { identityHomes, rootOf, tildify, defaultProfile, writeJsonAtomic } from
 import { copyPrivateHalf, isCurrent, CURRENT_LAYOUT } from './migrate.mjs';
 import { normalizeImport, IMPORT_KINDS } from './import.mjs';
 import { insecureUrlReason } from './safefetch.mjs';
-import { newRun, preflight, runSetup, setupInputError, hasCredential } from './setup.mjs';
+import { newRun, preflight, runSetup, setupInputError, hasCredential, credentialPath } from './setup.mjs';
 import { portFree, freePortFrom } from './ports.mjs';
 import { claimDirectory, yieldDirectory } from './directory.mjs';
 import { localFetch } from './localapi.mjs';
@@ -112,7 +112,7 @@ const AGENT_VERSION = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package
 // /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', '/shutdown']);
+const OPEN_POSTS = new Set(['/block', '/unblock', '/setup', '/setup/check', '/setup/reset', '/shutdown']);
 
 // The page the other server's redirect lands on. Self-contained on purpose:
 // the browser arrives here from somewhere else, and nothing may load from
@@ -147,11 +147,11 @@ function callbackPage(ok, msg) {
 // 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']);
+  '/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', '/config', '/new-actor', '/start-actor', '/shutdown', '/state-move', '/atproto/connect', '/fediacct/connect', '/fediacct/disconnect', '/fediacct', '/gateway', '/alias', '/import', '/update']);
+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']);
 // The identity itself. Changing any of these means a different actor at a
 // different address, which is a new setup, not an edit.
 const PERMANENT_CONFIG = ['handle', 'remotePod', 'issuer', 'root', 'kind'];
@@ -485,9 +485,19 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
       // 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') {
+      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;
@@ -848,6 +858,34 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
         }
         // ---- setup, driven by the page at /admin/setup/ ----
         case '/setup/check': return json(res, 200, preflight(body));
+        // 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 (setupRun?.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;
+          setupRun = 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' });

package/lib/c2s.mjs

@@ -5,14 +5,26 @@
 // SAME helper the facade and admin surfaces use — this module re-implements
 // no persistence and no delivery, so one write path stays one.
 //
-// GETs are redirects: the pod's documents are the canonical actor and outbox,
-// and a second renderer here would only drift from them.
+// GETs on the actor and outbox are redirects: the pod's documents are the
+// canonical ones, and a second renderer here would only drift from them.
+//
+// The inbox is the exception, and has to be. Deliveries land in a container on
+// the pod which the drain empties as it handles each item, so reading that
+// container tells the owner only what has not been dealt with yet. What was
+// actually received is whole only in the archive, so §5.2's "the owner can
+// read their own inbox" is served from there, by this agent, to the owner
+// alone.
 
 import * as social from './social.mjs';
 import * as wire from './wire.mjs';
 
 const MAX_BODY = 512 * 1024;          // same ceiling the inbox drain enforces
 
+// How many archived items one page of the inbox will read. A page is one
+// month, and a month with more than this is served short rather than costing
+// the pod an unbounded read; the log says when that happened.
+const MAX_INBOX_PAGE = 500;
+
 // §6 names activities; anything else with a type is an object to wrap.
 const ACTIVITY_TYPES = new Set([
   'Create', 'Update', 'Delete', 'Follow', 'Like', 'Announce', 'Undo',
@@ -60,14 +72,102 @@ export class C2S {
     return iri ? this.store.getStatuses().find((s) => s.noteId === iri) : null;
   }
 
+  /** The months the archive holds, newest first. One container listing. */
+  async archiveMonths() {
+    const archive = this.agent.intake?.archive;
+    if (!archive) return [];
+    const { names } = await archive.list('');
+    return (names || [])
+      .map((n) => n.replace(/\/$/u, ''))
+      .filter((n) => /^\d{4}-\d{2}$/u.test(n))
+      .sort()
+      .reverse();
+  }
+
+  /**
+   * The owner's own inbox, §5.2. Paged by month because that is how the
+   * archive is stored, so a page costs one listing and a read per item and no
+   * page is dearer for another month being large.
+   */
+  async sendInbox(res, url) {
+    const id = `${this.urls.base}ap/inbox`;
+    const page = url?.searchParams?.get('page') || null;
+    let months;
+    try {
+      months = await this.archiveMonths();
+    } catch (e) {
+      return this.send(res, 502, { error: `the archive could not be read: ${e.message}` });
+    }
+
+    if (!page) {
+      if (!months.length && this.store.getConfig()?.archiveInbox === false) {
+        this.log('inbox read: nothing to show — this identity does not keep what it receives');
+      }
+      return this.send(res, 200, {
+        '@context': wire.AS_CTX, id, type: 'OrderedCollection',
+        ...(months.length ? { first: `${id}?page=${months[0]}` } : { orderedItems: [] }),
+      });
+    }
+    if (!/^\d{4}-\d{2}$/u.test(page)) {
+      return this.send(res, 400, { error: 'page names a month, written 2026-09' });
+    }
+
+    const archive = this.agent.intake?.archive;
+    let names = [];
+    try {
+      // The trailing slash matters: without it this names a document, not the
+      // container, and a pod answers about the wrong thing.
+      ({ names } = await archive.list(`${page}/`));
+    } catch (e) {
+      return this.send(res, 502, { error: `the archive could not be read: ${e.message}` });
+    }
+    const files = (names || []).filter((n) => n.endsWith('.json')).sort();
+    if (files.length > MAX_INBOX_PAGE) {
+      this.log(`inbox read: ${page} holds ${files.length} items; serving the first ${MAX_INBOX_PAGE}`);
+    }
+    const kept = [];
+    for (const file of files.slice(0, MAX_INBOX_PAGE)) {
+      // Read as written: these records are JSON-LD, and the default read asks
+      // turtle-first, which a server is free to answer with turtle.
+      const read = await archive.read(`${page}/${file}`, { accept: '*/*' });
+      if (!read?.ok || !read.body) continue;
+      try {
+        const record = JSON.parse(read.body);
+        // The record wraps the bytes as they arrived; the activity is those
+        // bytes, not a retelling of them.
+        kept.push({ at: record.receivedAt || '', activity: JSON.parse(record.raw) });
+      } catch { /* a record that will not parse is not one that can be served */ }
+    }
+    kept.sort((a, b) => String(b.at).localeCompare(String(a.at)));
+    const older = months.filter((m) => m < page)[0] || null;
+    return this.send(res, 200, {
+      '@context': wire.AS_CTX,
+      id: `${id}?page=${page}`,
+      type: 'OrderedCollectionPage',
+      partOf: id,
+      ...(older ? { next: `${id}?page=${older}` } : {}),
+      orderedItems: kept.map((k) => k.activity),
+    });
+  }
+
   async handle(req, res, pathname, url) {   // eslint-disable-line no-unused-vars
-    if (pathname !== '/ap/outbox' && pathname !== '/ap/actor') return false;
+    if (pathname !== '/ap/outbox' && pathname !== '/ap/actor' && pathname !== '/ap/inbox') return false;
     if (req.method === 'OPTIONS') {
-      res.writeHead(204, { allow: 'GET, POST, OPTIONS' }); res.end(); return true;
+      res.writeHead(204, { allow: pathname === '/ap/inbox' ? 'GET, OPTIONS' : 'GET, POST, OPTIONS' });
+      res.end(); return true;
     }
     if (!this.agent.configured() || !this.urls) {
       return this.send(res, 409, { error: 'agent not configured' });
     }
+    if (pathname === '/ap/inbox') {
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        return this.send(res, 405, { error: "deliveries go to this actor's inbox on the pod, which the "
+          + 'actor document names; this address is the owner reading their own' });
+      }
+      const reader = await this.auth(req, pathname);
+      if (!reader.ok) return this.send(res, reader.status, { error: reader.error });
+      return this.sendInbox(res, url);
+    }
     if (req.method === 'GET' || req.method === 'HEAD') {
       // The pod's copy is the document; send the reader there.
       const target = pathname === '/ap/actor' ? this.urls.actor : this.urls.outbox;

package/lib/embed.mjs

@@ -210,5 +210,10 @@ export async function startEmbeddedAgent({
     ]);
   };
 
-  return { agent, handle, home, surface, host: authorities.host, stop };
+  // podHome and actorUrl are the identity's own locations on the pod. They are
+  // returned rather than rebuilt by the caller so the root name lives here.
+  return {
+    agent, handle, home, surface, host: authorities.host,
+    podHome: urls.home, actorUrl: urls.actor, stop,
+  };
 }

package/lib/front-core.mjs

@@ -18,6 +18,7 @@
 import crypto from 'node:crypto';
 import { handleDelivery } from './gateway-core.mjs';
 import { readCapped } from './safefetch.mjs';
+import { linkTargets, REL } from './links.mjs';
 
 // The one WebFinger document, spelled out here rather than imported from
 // wire.mjs: wire drags the agent's whole HTML pipeline (sanitize-html and
@@ -48,6 +49,24 @@ async function verifyPodToken(request, pathname, verifier) {
 // Is this WebID served by the claimed pod? A pod owner's WebID lives on the pod
 // origin — that is the whole proof: a token for a WebID under podHome could
 // only be minted by someone who controls that pod's identity provider.
+// A pod that will not answer must not hold up the person opting in; without
+// an answer the older check stands on its own.
+const OWNER_LOOKUP_MS = 5_000;
+
+/**
+ * Who the pod server says owns the pod. The server that hosts it is the
+ * authority on that, so when it answers, its answer decides. A server that
+ * says nothing leaves where the WebID lives as the only evidence there is.
+ */
+async function podOwners(podBase, fetchImpl = fetch) {
+  try {
+    const res = await fetchImpl(podBase, {
+      method: 'HEAD', signal: AbortSignal.timeout(OWNER_LOOKUP_MS),
+    });
+    return linkTargets(res?.headers?.get?.('link'), REL.owner, podBase);
+  } catch { return []; }
+}
+
 function webidUnderPod(webid, podHome) {
   try { return new URL(webid).origin === new URL(podHome).origin; } catch { return false; }
 }
@@ -285,7 +304,11 @@ export async function routeFront(request, ctx) {
     } catch { return j(400, { error: 'podBase is not a URL' }); }
     const webid = await verifyPodToken(request, pathname, ctx.verifier);
     if (!webid) return j(401, { error: 'a Solid-OIDC token proving the pod is required' });
-    if (!webid.startsWith(podBase)) {
+    // The pod's own server names its owner when it can. Where it does, that is
+    // the proof; where it does not, the WebID must at least live under the pod.
+    const owners = await podOwners(podBase, ctx.fetchImpl || fetch);
+    const proven = owners.length ? owners.includes(webid) : webid.startsWith(podBase);
+    if (!proven) {
       return j(403, { error: 'the token proves a different pod than the one you listed' });
     }
     if (action === 'opt-in') {
@@ -304,9 +327,9 @@ export async function routeFront(request, ctx) {
     return j(400, { error: 'action must be opt-in or opt-out' });
   }
 
-  // The vendored Solid-OIDC browser library the signup page loads — served
-  // here because this function owns every path on the domain.
-  if (pathname === '/solid-client-authn.bundle.js') {
+  // The vendored Solid-OIDC browser library the /run and /admin pages load —
+  // served here because this function owns every path on the domain.
+  if (pathname === '/solid-oidc-client.js') {
     if (!ctx.authBundle) return notFound();
     return { status: 200, headers: { 'content-type': 'text/javascript' }, body: ctx.authBundle };
   }

package/lib/intake.mjs

@@ -18,6 +18,7 @@ import * as $rdf from 'rdflib';
 import { USER_AGENT } from './ua.mjs';
 import { PUBLIC } from './wire.mjs';
 import { HTTP_TIMEOUT_MS, readCapped } from './safefetch.mjs';
+import { linkTargets, REL } from './links.mjs';
 import { dropFollower } from './store.mjs';
 
 const RDF = $rdf.Namespace('http://www.w3.org/1999/02/22-rdf-syntax-ns#');
@@ -307,6 +308,24 @@ export class Intake {
     }
   }
 
+  /**
+   * Where this pod describes the services it offers. The pod says so on any
+   * response about one of its resources; the well-known path is only what a
+   * pod that says nothing has always used.
+   */
+  async _storageDescriptionUrl() {
+    try {
+      const head = await fetch(this.urls.base, {
+        method: 'HEAD',
+        headers: { 'user-agent': USER_AGENT },
+        signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+      });
+      const [found] = linkTargets(head.headers.get('link'), REL.storageDescription, this.urls.base);
+      if (found) return found;
+    } catch { /* the well-known path below */ }
+    return this.urls.base + '.well-known/solid';
+  }
+
   async _subscribeOnce() {
     // Reuse a channel we already have rather than asking for another one.
     const saved = this.store.read(CHANNEL_DOC, null);
@@ -314,13 +333,13 @@ export class Intake {
       this._openSocket(saved.receiveFrom, true);
       return;
     }
-    const descRes = await fetch(this.urls.base + '.well-known/solid', {
+    const descUrl = await this._storageDescriptionUrl();
+    const descRes = await fetch(descUrl, {
       headers: { accept: 'text/turtle', 'user-agent': USER_AGENT },
       signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
     });
     // The service description is RDF; ask rdflib which subject is the
     // WebSocketChannel2023 service rather than pattern-matching the document.
-    const descUrl = this.urls.base + '.well-known/solid';
     const g = $rdf.graph();
     try { $rdf.parse(await readCapped(descRes), g, descUrl, 'text/turtle'); }
     catch (e) { this.wsState = 'unavailable'; this.log(`service description unparsable (${e.message}) — polling only`); return; }

package/lib/links.mjs

@@ -0,0 +1,35 @@
+// links.mjs — reading RFC 8288 Link headers.
+//
+// Solid says where a resource's access control lives, where a storage
+// describes itself, and who owns a storage, by putting a link on the response.
+// Working any of those out from the resource's own URL instead is exactly what
+// the specs tell clients not to do, so this is the one place that reads them.
+
+/**
+ * Every target a Link header gives for one relation, resolved against the URL
+ * the header came from. A header may carry several links, and one link may
+ * carry several relation names.
+ */
+export function linkTargets(headerValue, rel, baseUrl) {
+  if (!headerValue) return [];
+  const wanted = String(rel).toLowerCase();
+  const out = [];
+  // Split on the commas BETWEEN links: one inside a URI has its closing angle
+  // bracket still ahead of it, and is left alone.
+  for (const part of String(headerValue).split(/,(?![^<]*>)/u)) {
+    const link = /^\s*<([^>]*)>\s*(.*)$/u.exec(part);
+    if (!link) continue;
+    const relParam = /(?:^|;)\s*rel\s*=\s*(?:"([^"]*)"|([^;"\s]+))/iu.exec(link[2]);
+    const names = (relParam?.[1] ?? relParam?.[2] ?? '').toLowerCase().split(/\s+/u);
+    if (!names.includes(wanted)) continue;
+    try { out.push(new URL(link[1], baseUrl).href); } catch { /* not a URL we can follow */ }
+  }
+  return out;
+}
+
+/** The relations this project follows. */
+export const REL = {
+  acl: 'acl',
+  storageDescription: 'http://www.w3.org/ns/solid/terms#storageDescription',
+  owner: 'http://www.w3.org/ns/solid/terms#owner',
+};