fedipod-server 0.7.0 → 0.9.0

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/fediacct.mjs

@@ -0,0 +1,257 @@
+// fediacct.mjs — the agent's connections to fediverse accounts the owner holds
+// on OTHER servers. The agent is an API client of an existing Mastodon-API
+// account, the same relationship a Mastodon app has to this agent, and the same
+// one atproto.mjs has to a Bluesky account. Nothing here is a second identity:
+// no key, no pod, nothing published.
+//
+// One credential per account at AP_HOME/fediaccts/<id>.json (0600, atomic,
+// stamped with the actor it was connected for — the keys.json rules). A file
+// stamped for someone else is skipped rather than fatal, so one stray record
+// cannot cost the owner the whole roster.
+//
+// An access token here is full access to that account on that server, so it
+// never reaches pod state: config.json gets the handle and the host, nothing
+// more.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { writeJsonAtomic } from './home.mjs';
+import { safeFetch, retryAfterMs } from './safefetch.mjs';
+
+const DIR = 'fediaccts';
+const APPS = '_apps';
+const SCOPES = 'read write';
+const STATE_TTL_MS = 10 * 60_000;
+const CLIENT_NAME = 'FediPod';
+
+// The id becomes a file name, and both halves come from a remote server's own
+// answer. `--handle ../escape` is the shape of bug this project has already
+// paid for once, so the result is checked rather than trusted.
+export function safeId(user, host) {
+  const id = `${String(user || '').trim()}@${String(host || '').trim()}`
+    .toLowerCase().replace(/[^a-z0-9.@_-]/g, '-');
+  if (!/^[a-z0-9][a-z0-9.@_-]{0,80}$/.test(id) || id.includes('..')) return null;
+  return id;
+}
+
+// A host as we will address it: bare authority, no scheme, no path, no case.
+export function cleanHost(host) {
+  const raw = String(host || '').trim().replace(/^https?:\/\//i, '').replace(/\/.*$/, '');
+  return /^[a-z0-9.-]+(:\d+)?$/i.test(raw) ? raw.toLowerCase() : null;
+}
+
+export class FediAccounts {
+  constructor({ localDir, actorId = null, log = console.log, fetcher = null }) {
+    this.dir = path.join(localDir, DIR);
+    this.actorId = actorId;
+    this.log = log;
+    // Injectable for tests; the default is the politeness stack, which also
+    // refuses private addresses — a connected account is on the public web.
+    this.fetcher = fetcher || ((url, init) => safeFetch(url, init));
+    this.pausedUntil = new Map();          // host → epoch ms
+    this.pending = new Map();              // state nonce → { host, redirectUri, at }
+  }
+
+  // ---- records ----
+
+  _path(id) { return path.join(this.dir, `${id}.json`); }
+
+  ids() {
+    let names = [];
+    try { names = fs.readdirSync(this.dir); } catch { return []; }
+    return names.filter(n => n.endsWith('.json') && !n.startsWith('_')).map(n => n.slice(0, -5));
+  }
+
+  read(id) {
+    let rec;
+    try { rec = JSON.parse(fs.readFileSync(this._path(id), 'utf8')); } catch { return null; }
+    if (rec?.mintedFor && this.actorId && rec.mintedFor !== this.actorId) {
+      this.log(`fediaccts/${id}.json belongs to ${rec.mintedFor} — not reusing it for ${this.actorId}`);
+      return null;
+    }
+    return rec;
+  }
+
+  write(rec) {
+    fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    writeJsonAtomic(this._path(rec.id), rec);
+  }
+
+  list() { return this.ids().map(id => this.read(id)).filter(Boolean); }
+
+  connected() { return this.list().some(r => r.token && r.enabled !== false); }
+
+  // What may be written to pod state: who, where, and whether it is polled.
+  roster() {
+    return this.list().map(r => ({
+      id: r.id, handle: r.handle, host: r.host,
+      addedAt: r.addedAt || null, enabled: r.enabled !== false,
+    }));
+  }
+
+  status() {
+    return this.list().map(r => ({
+      id: r.id, handle: r.handle, host: r.host,
+      enabled: r.enabled !== false,
+      needsReconnect: !!r.needsReconnect,
+      cooldownFor: Math.max(0, Math.round(((this.pausedUntil.get(r.host) || 0) - Date.now()) / 1000)),
+    }));
+  }
+
+  setEnabled(id, on) {
+    const rec = this.read(id);
+    if (!rec) return null;
+    this.write({ ...rec, enabled: !!on });
+    return this.roster().find(r => r.id === id) || null;
+  }
+
+  remove(id) {
+    if (!this.read(id)) return false;
+    try { fs.rmSync(this._path(id)); } catch { return false; }
+    this.log(`Fediverse account disconnected: ${id}`);
+    return true;
+  }
+
+  // ---- HTTP ----
+
+  async _fetch(host, url, init) {
+    const left = (this.pausedUntil.get(host) || 0) - Date.now();
+    if (left > 0) throw new Error(`${host} asked us to back off — ${Math.ceil(left / 1000)}s left`);
+    const res = await this.fetcher(url, init);
+    if (res.status === 429 || res.status === 503) {
+      const ms = retryAfterMs(res) ?? 60_000;
+      this.pausedUntil.set(host, Date.now() + ms);
+      this.log(`${host} answered ${res.status} — pausing for ${Math.round(ms / 1000)}s`);
+    }
+    return res;
+  }
+
+  async _json(res, host) {
+    const body = await res.json().catch(() => ({}));
+    if (res.status >= 400) {
+      const err = new Error(body.error_description || body.error || `${host} answered ${res.status}`);
+      err.status = res.status;
+      throw err;
+    }
+    return body;
+  }
+
+  // ---- the OAuth dance, as the client ----
+
+  // One app registration per host, remembered. The redirect_uri is part of what
+  // was registered, so an agent that moved to another port re-registers rather
+  // than sending the server a redirect it will refuse.
+  async appFor(host, redirectUri) {
+    const file = path.join(this.dir, APPS, `${host}.json`);
+    try {
+      const app = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (app.redirectUri === redirectUri && app.clientId && app.clientSecret) return app;
+    } catch { /* not registered here yet */ }
+    const res = await this._fetch(host, `https://${host}/api/v1/apps`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        client_name: CLIENT_NAME, redirect_uris: redirectUri,
+        scopes: SCOPES, website: 'https://github.com/jeff-zucker/FediPod',
+      }),
+    });
+    const body = await this._json(res, host);
+    if (!body.client_id || !body.client_secret) throw new Error(`${host} registered no client`);
+    const app = { host, redirectUri, clientId: body.client_id, clientSecret: body.client_secret };
+    fs.mkdirSync(path.join(this.dir, APPS), { recursive: true, mode: 0o700 });
+    writeJsonAtomic(file, app);
+    return app;
+  }
+
+  // Step one: where to send the browser. The state nonce is single-use and
+  // short-lived — without one, any page the owner visits could hand our
+  // callback somebody else's authorization code and bind THEIR account here.
+  async begin({ host, redirectUri }) {
+    const h = cleanHost(host);
+    if (!h) throw new Error('that is not a server address');
+    const app = await this.appFor(h, redirectUri);
+    const state = crypto.randomBytes(24).toString('hex');
+    const now = Date.now();
+    for (const [k, v] of this.pending) if (now - v.at > STATE_TTL_MS) this.pending.delete(k);
+    this.pending.set(state, { host: h, redirectUri, at: now });
+    const u = new URL(`https://${h}/oauth/authorize`);
+    u.searchParams.set('client_id', app.clientId);
+    u.searchParams.set('redirect_uri', redirectUri);
+    u.searchParams.set('response_type', 'code');
+    u.searchParams.set('scope', SCOPES);
+    u.searchParams.set('state', state);
+    return { url: u.href, state, host: h };
+  }
+
+  // Step two: the code comes back. Exchange it, ask the server who we now are,
+  // and only then write anything.
+  async complete({ state, code }) {
+    const pend = this.pending.get(state);
+    if (!pend || Date.now() - pend.at > STATE_TTL_MS) throw new Error('that sign-in has expired — start again');
+    this.pending.delete(state);
+    const { host, redirectUri } = pend;
+    const app = await this.appFor(host, redirectUri);
+    const res = await this._fetch(host, `https://${host}/oauth/token`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        grant_type: 'authorization_code', code, redirect_uri: redirectUri,
+        client_id: app.clientId, client_secret: app.clientSecret, scope: SCOPES,
+      }),
+    });
+    const tok = await this._json(res, host);
+    if (!tok.access_token) throw new Error(`${host} returned no token`);
+    const me = await this.whoami(host, tok.access_token);
+    const id = safeId(me.username, host);
+    if (!id) throw new Error(`${host} answered with a name we cannot file safely`);
+    this.write({
+      id, host, token: tok.access_token, scope: tok.scope || SCOPES,
+      handle: `@${me.username}@${host}`, acct: me.acct || me.username,
+      accountId: String(me.id), actorUrl: me.url || null,
+      name: me.display_name || me.username, icon: me.avatar || null,
+      addedAt: new Date().toISOString(), enabled: true,
+      ...(this.actorId ? { mintedFor: this.actorId } : {}),
+    });
+    this.log(`Fediverse account connected: @${me.username}@${host}`);
+    return this.roster().find(r => r.id === id);
+  }
+
+  async whoami(host, token) {
+    const res = await this._fetch(host, `https://${host}/api/v1/accounts/verify_credentials`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    const me = await this._json(res, host);
+    if (!me.username) throw new Error(`${host} did not say who we are`);
+    return me;
+  }
+
+  // ---- authenticated calls on behalf of one connected account ----
+
+  // Returns the Response, so a caller can read rate-limit headers. A 401 means
+  // the token was revoked on the far side: the account is marked rather than
+  // deleted, because the owner should be told rather than quietly dropped.
+  async api(id, pathname, init = {}) {
+    const rec = this.read(id);
+    if (!rec?.token) throw new Error(`no connected account ${id}`);
+    const url = pathname.startsWith('https://') ? pathname : `https://${rec.host}${pathname}`;
+    const res = await this._fetch(rec.host, url, {
+      ...init,
+      headers: { ...(init.headers || {}), authorization: `Bearer ${rec.token}` },
+    });
+    if (res.status === 401) {
+      if (!rec.needsReconnect) this.write({ ...rec, needsReconnect: true });
+      const err = new Error(`${rec.handle} no longer accepts our token — reconnect it`);
+      err.status = 401;
+      throw err;
+    }
+    if (rec.needsReconnect && res.status < 400) this.write({ ...rec, needsReconnect: false });
+    return res;
+  }
+
+  async apiJson(id, pathname, init = {}) {
+    const rec = this.read(id);
+    const res = await this.api(id, pathname, init);
+    return this._json(res, rec?.host || id);
+  }
+}

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; }
 }
@@ -130,6 +149,8 @@ function identFor(rec, policy = null) {
 //   host        the front's own host, e.g. "fedipod.net" (for WebFinger subjects)
 //   frontOrigin "https://fedipod.net"
 //   lookup(handle) -> record | null       the directory
+//   listDirectory() -> { handle: record }  every row, for the admin roster
+//   removeDirectory(handle) -> boolean     drop a row; false when a seeded row remains
 //   podPut(url, body, ct) -> boolean      append to a user's pod (per-user cred inside)
 //   podGet(url) -> Response                read a user's pod (public reads; plain fetch is fine)
 export async function routeFront(request, ctx) {
@@ -155,6 +176,51 @@ export async function routeFront(request, ctx) {
     return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: ctx.runPage };
   }
 
+  // The admin page: the host reading who has accounts here. The page signs in
+  // and calls the roster API below; a deploy with no admin supplies no page.
+  if (pathname === '/admin') {
+    if (request.method !== 'GET' && request.method !== 'HEAD') return { status: 405, headers: {}, body: '' };
+    if (!ctx.adminPage) return notFound();
+    return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: ctx.adminPage };
+  }
+
+  // The roster: every directory row, secrets stripped, for the host's own
+  // eyes. The reader proves themself the way attach proves a pod — a
+  // Solid-OIDC token — and must be the WebID the deploy names as admin.
+  if (pathname === '/api/roster') {
+    if (!ctx.listDirectory || !ctx.adminWebId) return j(501, { error: 'this front has no roster to offer' });
+    const webid = await verifyPodToken(request, pathname, ctx.verifier);
+    if (!webid) return j(401, { error: 'a Solid-OIDC token is required' });
+    if (webid !== ctx.adminWebId) return j(403, { error: 'that WebID is not the admin of this front' });
+    const rows = await ctx.listDirectory();
+    const accounts = Object.values(rows)
+      .map((r) => ({
+        handle: r.handle, kind: r.kind || 'person', fronted: !r.inboxOnly,
+        podHome: r.podHome, webId: r.webId || null, actorUrl: r.actorUrl,
+        address: `@${r.handle}@${ctx.host}`,
+      }))
+      .sort((a, b) => a.handle.localeCompare(b.handle));
+    return j(200, { host: ctx.host, accounts });
+  }
+
+  // Revoke: the admin removes an account's row, so the server stops answering
+  // for the name. Nothing on the user's pod is touched. Attach-created rows go
+  // for good; a row seeded in the deploy's environment can only be removed there.
+  if (pathname === '/api/revoke' && request.method === 'POST') {
+    if (!ctx.removeDirectory || !ctx.adminWebId) return j(501, { error: 'this front cannot revoke accounts' });
+    const webid = await verifyPodToken(request, pathname, ctx.verifier);
+    if (!webid) return j(401, { error: 'a Solid-OIDC token is required' });
+    if (webid !== ctx.adminWebId) return j(403, { error: 'that WebID is not the admin of this front' });
+    let body;
+    try { body = JSON.parse(await request.clone().text()); } catch { return j(400, { error: 'bad JSON' }); }
+    const handle = String(body.handle || '').toLowerCase();
+    if (!(await ctx.lookup(handle))) return j(404, { error: 'no such account' });
+    const removed = (await ctx.removeDirectory(handle)) === true;
+    return j(200, removed ? { handle, removed }
+      : { handle, removed: false,
+          reason: 'this row is seeded in the deploy environment (FEDIPOD_DIRECTORY_JSON) — remove it there and redeploy' });
+  }
+
   // Live handle check for the page: valid shape AND not already in the
   // directory. Also tells the page whether this host offers pods.
   if (pathname === '/api/handle') {
@@ -238,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') {
@@ -257,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',
+};