fedipod 0.19.0 → 1.2.0

package/lib/client/masto/accounts.mjs

@@ -0,0 +1,264 @@
+// accounts.mjs — the account endpoints: the owner's credentials and profile
+// editor, follow requests, markers, relationships, search and lookup, block
+// and mute, follow and unfollow, an account and its lists and statuses, and
+// the web-push subscription a client login holds.
+
+import crypto from 'node:crypto';
+import * as podMedia from '../../pod/media.mjs';
+import * as social from '../../core/social.mjs';
+import { readBody } from './body.mjs';
+import { readMultipart } from './media.mjs';
+
+export async function handle(api, ctx) {
+  const { req, res, pathname, url, send } = ctx;   // eslint-disable-line no-unused-vars
+
+  if (pathname === '/api/v1/accounts/verify_credentials') {
+    const cfg0 = api.store.getConfig() || {};
+    return send(200, {
+      ...api.selfAccount(),
+      // `source` is what the editor fills its inputs from: the raw text it
+      // will send back, not the HTML the profile renders.
+      source: {
+        privacy: 'public', sensitive: false, language: 'en',
+        note: cfg0.summary || '',
+        fields: (cfg0.fields || []).map(f => ({ name: f.name, value: f.value })),
+      },
+    });
+  }
+
+  // The profile editor. Everything it can send is carried: the name and bio,
+  // both pictures, and the extra fields. An avatar or header arrives as file
+  // bytes, so it goes to the pod's media container first and the actor gets
+  // the URL — the same path a posted attachment takes.
+  if (pathname === '/api/v1/accounts/update_credentials') {
+    if (req.method !== 'PATCH' && req.method !== 'POST') return send(405, { error: 'PATCH expected' });
+    const ct = String(req.headers['content-type'] || '');
+    // readBody already covers JSON and urlencoded; only the file case differs.
+    let form = {}, files = {};
+    if (ct.includes('multipart/form-data')) ({ fields: form, files } = await readMultipart(req));
+    else form = await readBody(req);
+
+    const cfg = { ...api.store.getConfig() };
+    const putImage = async (f) => {
+      const ext = (f.filename || '').includes('.')
+        ? f.filename.split('.').pop().replace(/[^\w]/g, '') : 'bin';
+      const slug = new Date().toISOString().slice(0, 10) + '-' + crypto.randomBytes(4).toString('hex') + '.' + ext;
+      const url = api.urls.media + slug;
+      await api.agent.publisher.ensureMediaContainer();
+      await podMedia.write(api.agent.remote, url, f.data, f.contentType);
+      return url;
+    };
+
+    if ('display_name' in form) cfg.name = String(form.display_name).trim() || cfg.handle;
+    if ('note' in form) cfg.summary = String(form.note) || undefined;
+    if ('locked' in form) cfg.approveJoins = form.locked === 'true' || form.locked === true;
+    if (files.avatar?.data?.length) cfg.icon = await putImage(files.avatar);
+    if (files.header?.data?.length) cfg.image = await putImage(files.header);
+
+    // fields_attributes arrives as fields_attributes[0][name] etc. A row with
+    // no name is how the editor says "delete this one", so it is dropped.
+    const rows = [];
+    for (const [k, v] of Object.entries(form)) {
+      const m = /^fields_attributes\[(\d+)\]\[(name|value)\]$/.exec(k);
+      if (!m) continue;
+      (rows[Number(m[1])] ||= {})[m[2]] = String(v);
+    }
+    if (rows.length) cfg.fields = rows.filter(r => r && r.name?.trim())
+      .map(r => ({ name: r.name.trim(), value: (r.value || '').trim() }));
+
+    api.store.setConfig(cfg);
+    Object.assign(api.agent.publisher.config, {
+      name: cfg.name, summary: cfg.summary, icon: cfg.icon, image: cfg.image,
+      fields: cfg.fields, approveJoins: !!cfg.approveJoins,
+    });
+    await api.store.flush();
+    // publishProfile says whether the world can actually read the actor it
+    // just wrote. Discarding that reported success for a save that left the
+    // account undiscoverable — the one outcome the caller needed to hear.
+    const published = await api.agent.publisher.publishProfile();
+    const unreachable = published?.unreachable;
+    if (unreachable?.length) {
+      api.log(`profile saved but NOT publicly readable: ${unreachable.join(', ')}`);
+    }
+    api.log(`profile updated from a client: ${Object.keys(form).join(', ') || '(files only)'}`);
+    return send(200, api.selfAccount());
+  }
+
+  // Follow requests. The queue, and the two answers to it, have existed since
+  // groups did — `agent.store.getRequests()`, `admitRequest`, `refuseRequest`,
+  // all driven from the record page — but the facade stubbed the list to `[]`
+  // and offered no authorize/reject. So a locked account could see and answer
+  // its requests in FediPod's own page and in NO Mastodon client: Phanpy,
+  // Tuba and Whalebird all showed nothing waiting.
+  if (pathname === '/api/v1/follow_requests' && req.method === 'GET') {
+    const limit = Math.min(Number(url.searchParams.get('limit')) || 40, 80);
+    return send(200, api.store.getRequests().slice(0, limit)
+      .map((r) => api.account(r.actor)));
+  }
+  const mReq = /^\/api\/v1\/follow_requests\/([a-f0-9]+)\/(authorize|reject)$/.exec(pathname);
+  if (mReq && req.method === 'POST') {
+    // The client addresses an account by the id it was given for it, which is
+    // this store's own hash of the actor URL — the same one every other
+    // account route here uses.
+    const actorUrl = api.store.urlFor(mReq[1]);
+    if (!actorUrl) return send(404, { error: 'Record not found' });
+    if (!api.store.getRequests().some((r) => r.actor === actorUrl)) {
+      return send(404, { error: 'Record not found' });
+    }
+    try {
+      if (mReq[2] === 'authorize') await social.admitRequest(api.agent, actorUrl);
+      else await social.refuseRequest(api.agent, actorUrl);
+    } catch (e) { return send(422, { error: e.message }); }
+    await api.store.flush();
+    return send(200, api.relationship(actorUrl));
+  }
+
+  if (pathname === '/api/v1/markers') {
+    if (req.method === 'POST') {
+      const body = await readBody(req);
+      const markers = api.store.read('masto-markers.json', {});
+      for (const [k, v] of Object.entries(body)) {
+        const lastId = v?.last_read_id || v;
+        if (typeof lastId === 'string') {
+          markers[k] = { last_read_id: lastId, version: (markers[k]?.version || 0) + 1, updated_at: new Date().toISOString() };
+        }
+      }
+      api.store.write('masto-markers.json', markers);
+      return send(200, markers);
+    }
+    return send(200, api.store.read('masto-markers.json', {}));
+  }
+
+  if (pathname === '/api/v1/accounts/relationships') {
+    const ids = [...url.searchParams.getAll('id[]'), ...url.searchParams.getAll('id')];
+    const rels = ids.map(id => api.store.urlFor(id)).filter(Boolean).map(u => api.relationship(u));
+    return send(200, rels);
+  }
+
+  if (pathname === '/api/v1/accounts/search') {
+    return send(200, await api.accountSearch(url.searchParams.get('q')));
+  }
+
+  if (pathname === '/api/v1/accounts/lookup') {
+    const acct = String(url.searchParams.get('acct') || '').replace(/^@/, '');
+    const cfg = api.store.getConfig();
+    if (acct === cfg?.handle || acct === `${cfg?.handle}@${api.host}`) {
+      return send(200, api.selfAccount());
+    }
+    const hit = Object.entries(api.store.getActors()).find(([u, a]) => {
+      try { return `${a.preferredUsername}@${new URL(u).host}` === acct; } catch { return false; }
+    });
+    return hit ? send(200, api.account(hit[0])) : send(404, { error: 'Record not found' });
+  }
+
+  // Block and mute, from where the trouble is seen. A block also unfollows —
+  // intake refuses a blocked author already — and a mute is view-only: their
+  // posts stay out of the timelines, nothing federates.
+  const mRel = /^\/api\/v1\/accounts\/([a-f0-9]+)\/(block|unblock|mute|unmute)$/.exec(pathname);
+  if (mRel && req.method === 'POST') {
+    const actorUrl = api.store.urlFor(mRel[1]);
+    if (!actorUrl) return send(404, { error: 'Record not found' });
+    if (mRel[2] === 'block' || mRel[2] === 'unblock') {
+      if (mRel[2] === 'block') await social.blockActor(api.agent, actorUrl);
+      else await social.unblockActor(api.agent, actorUrl);
+    } else {
+      const m = api.store.getMuted();
+      if (mRel[2] === 'mute' && !m.actors.includes(actorUrl)) m.actors.push(actorUrl);
+      if (mRel[2] === 'unmute') m.actors = m.actors.filter(a => a !== actorUrl);
+      api.store.setMuted(m);
+    }
+    return send(200, api.relationship(actorUrl));
+  }
+
+  const mFollow = /^\/api\/v1\/accounts\/([a-f0-9]+)\/(follow|unfollow)$/.exec(pathname);
+  if (mFollow && req.method === 'POST') {
+    const actorUrl = api.store.urlFor(mFollow[1]);
+    if (!actorUrl) return send(404, { error: 'Record not found' });
+    if (mFollow[2] === 'follow') await social.followActor(api.agent, actorUrl);
+    else await social.unfollowActor(api.agent, actorUrl).catch(() => {});   // already-gone is fine
+    return send(200, api.relationship(actorUrl));
+  }
+
+  const mAccount = /^\/api\/v1\/accounts\/([a-f0-9]+)$/.exec(pathname);
+  if (mAccount && req.method === 'GET') {
+    const actorUrl = api.store.urlFor(mAccount[1]);
+    return actorUrl ? send(200, api.account(actorUrl)) : send(404, { error: 'Record not found' });
+  }
+
+  // Web push: one subscription per client login. The agent pushes payloads
+  // to the browser's push service itself, so a closed client still hears.
+  if (pathname === '/api/v1/push/subscription') {
+    const token = (/^Bearer (.+)$/.exec(req.headers.authorization || '') || [])[1];
+    if (!token) return send(401, { error: 'The access token is invalid' });
+    // A client that ignores the missing `vapid` and subscribes anyway must
+    // not be told it worked — a stored subscription nothing ever pushes to is
+    // the same silent nothing the toggle was.
+    if (!api.webPush) return send(422, { error: 'this instance does not send web push' });
+    if (req.method === 'GET') {
+      const sub = api.push.get(token);
+      return sub ? send(200, api.push.json(token, sub)) : send(404, { error: 'Record not found' });
+    }
+    if (req.method === 'POST') {
+      const body = await readBody(req);
+      const sub = api.push.set(token, {
+        endpoint: body.subscription?.endpoint,
+        keys: body.subscription?.keys,
+        alerts: body.data?.alerts,
+      });
+      if (!sub) return send(422, { error: 'a https endpoint and p256dh/auth keys are required' });
+      return send(200, api.push.json(token, sub));
+    }
+    if (req.method === 'PUT') {
+      const body = await readBody(req);
+      const sub = api.push.setAlerts(token, body.data?.alerts);
+      return sub ? send(200, api.push.json(token, sub)) : send(404, { error: 'Record not found' });
+    }
+    if (req.method === 'DELETE') {
+      api.push.drop(token);
+      return send(200, {});
+    }
+  }
+
+  if (/^\/api\/v1\/accounts\/[a-f0-9]+\/featured_tags$/.test(pathname)) return send(200, []);
+
+  // The counts these back are rendered from the same two arrays (see
+  // `account`), so a client that shows a number here can always open it.
+  const mAccList = /^\/api\/v1\/accounts\/([a-f0-9]+)\/(following|followers)$/.exec(pathname);
+  if (mAccList && req.method === 'GET') {
+    const actorUrl = api.store.urlFor(mAccList[1]);
+    if (!actorUrl) return send(404, { error: 'Record not found' });
+    // Only our own lists are known. A remote actor's collections live on its
+    // own server, and opening a profile is not worth a fetch of a stranger's
+    // pod — an empty list, not an error, is what the API can honestly say.
+    const mine = actorUrl === api.urls?.actor;
+    const c = api.store.getContacts();
+    // Reversed: the contact arrays append, and page()'s cursors read
+    // newest-first — fed as stored, since_id answered with its complement.
+    const recs = (!mine ? []
+      : mAccList[2] === 'followers' ? c.followers
+        : c.following.filter(f => f.accepted))   // pending is not following
+      .slice().reverse();
+    const { items, headers } = api.page(recs, url,
+      { limit: 40, max: 80, idOf: (r) => api.store.idFor(r.actor) });
+    return send(200, items.map(r => api.account(r.actor)), headers);
+  }
+
+  // Who among the people I follow also follows THEM — a graph we do not hold,
+  // and the shape is an entry per requested account, not a bare list.
+  if (pathname === '/api/v1/accounts/familiar_followers') {
+    const ids = [...url.searchParams.getAll('id[]'), ...url.searchParams.getAll('id')];
+    return send(200, ids.map(id => ({ id, accounts: [] })));
+  }
+
+  const mAccStatuses = /^\/api\/v1\/accounts\/([a-f0-9]+)\/statuses$/.exec(pathname);
+  if (mAccStatuses) {
+    const actorUrl = api.store.urlFor(mAccStatuses[1]);
+    const all = api.store.getStatuses();
+    const pinnedOnly = url.searchParams.get('pinned') === 'true';
+    const { items, headers } = api.page(
+      all.filter(s => s.actor === actorUrl && (!pinnedOnly || s.pinned)), url);
+    return send(200, items.map(s => api.statusOrBoost(s, { all })), headers);
+  }
+
+  return false;
+}

package/lib/client/masto/body.mjs

@@ -0,0 +1,69 @@
+// body.mjs — reading what a client sent: JSON or form-encoded bodies, the
+// poll a compose request carries, and the text of a post back out of its
+// HTML.
+
+
+
+/**
+ * A poll out of a compose request, or null when there is none. A JSON client
+ * sends a `poll` object; a form-encoded one spells the same thing out in
+ * Rails's bracket notation, which is the shape the option list arrives in.
+ */
+export function pollParams(body) {
+  const nested = body?.poll && typeof body.poll === 'object' ? body.poll : null;
+  const options = [].concat(nested?.options ?? body?.['poll[options][]'] ?? [])
+    .map(o => String(o ?? '').trim()).filter(Boolean);
+  const rawExpiry = nested?.expires_in ?? body?.['poll[expires_in]'];
+  const rawMultiple = nested?.multiple ?? body?.['poll[multiple]'];
+  if (!options.length && rawExpiry === undefined) return null;
+  return {
+    options,
+    expiresIn: rawExpiry === undefined || rawExpiry === null || rawExpiry === ''
+      ? null : Number(rawExpiry),
+    multiple: rawMultiple === true || rawMultiple === 'true' || rawMultiple === '1',
+  };
+}
+
+// Accepts JSON or form-encoded bodies (OAuth posts are often form-encoded).
+// The source of a post that predates raw-text storage: its HTML back to
+// typed text, near enough to edit.
+export function htmlToText(html) {
+  return String(html)
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/p>\s*<p[^>]*>/gi, '\n\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'")
+    .trim();
+}
+
+export function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    req.on('data', c => {
+      data += c;
+      // Destroying the socket without settling left the awaiting handler
+      // pending for the life of the process and the client waiting on a
+      // response that would never come.
+      if (data.length > 1e6) { req.destroy(); reject(new Error('request body too large')); }
+    });
+    req.on('end', () => {
+      const ct = String(req.headers['content-type'] || '');
+      try {
+        if (ct.includes('application/json')) return resolve(data ? JSON.parse(data) : {});
+        // A form-encoded list is the same key repeated, spelled with a
+        // trailing `[]`. Reading it as a plain object kept only the last one,
+        // so a client sending its poll or its media that way lost all but the
+        // final value. Only the `[]` keys become lists: everything else keeps
+        // the single value the rest of this file reads.
+        const form = new URLSearchParams(data);
+        const out = {};
+        for (const key of new Set(form.keys())) {
+          out[key] = key.endsWith('[]') ? form.getAll(key) : form.get(key);
+        }
+        resolve(out);
+      } catch (e) { reject(e); }
+    });
+    req.on('error', reject);
+  });
+}

package/lib/client/masto/index.mjs

@@ -0,0 +1,183 @@
+// mastoapi.mjs — Mastodon client-API facade over ap-agent (M1: read + post).
+// Modeled on snac2's approach: real implementations for the endpoints
+// clients actually exercise, empty-collection stubs for the rest. Reached
+// through the router (/api/*, /oauth/* → this port), so requests carry the
+// gate; OAuth here is theater for a single already-trusted local user.
+//
+// Surface: oauth trio · instance v1/v2 · verify_credentials · timelines/home
+// (M1) · notifications, relationships, lookup, follow/unfollow, thread
+// context, /v2/search (M2) · favourite/reblog, media upload, markers,
+// DELETE status (M3) · stub farm. Unknown /api/* GETs 404 and are LOGGED —
+// that log is the running punch list.
+//
+// This file is the class and the dispatcher. The endpoints are in the modules
+// beside it, one per area — oauth.mjs, instance.mjs, accounts.mjs,
+// timelines.mjs, statuses.mjs, media.mjs — each exporting handle(api, ctx),
+// which answers and returns true or returns false; handle() below walks them
+// in order with the bearer gate between the public ones and the rest. The
+// JSON shapes are render.mjs and the request readers body.mjs; every helper
+// the areas reach through `api.` is a one-line delegation here.
+
+import { Push } from '../webpush.mjs';
+import * as oauth from './oauth.mjs';
+import * as render from './render.mjs';
+import * as instance from './instance.mjs';
+import * as accounts from './accounts.mjs';
+import * as timelines from './timelines.mjs';
+import * as statuses from './statuses.mjs';
+import * as media from './media.mjs';
+export { hashPassword } from './oauth.mjs';
+export { pollParams } from './body.mjs';
+export { attachmentType, extensionFor } from './media.mjs';
+
+export class MastoApi {
+  constructor({ agent, log = console.log, allowed = null, scheme = null, embedded = false,
+    streaming = true, webPush = true, scheduling = true }) {
+    this.agent = agent;
+    // A server-hosted identity has no CLI of its own, so the advice this gives
+    // when it refuses has to name the route that identity really has.
+    this.embedded = embedded;
+    this.log = log;
+    this.allowed = allowed;             // authorities a redirect_uri may name
+    // The scheme this identity is reached on, when the socket cannot say —
+    // a server behind a TLS proxy terminates cleartext and still is https.
+    this.scheme = scheme;
+    // Whether this deployment can serve the Mastodon streaming WebSocket. A
+    // Node agent can; the in-browser service-worker facade cannot (it is
+    // fetch-only), so it advertises NO streaming URL. Otherwise the client
+    // opens wss://localhost/... (the worker has no request host to name), which
+    // not only fails but, from a public origin, trips Chrome's private-network
+    // permission prompt ("access other apps and services on this device").
+    // With no streaming URL the client falls back to polling, which is served.
+    this.streaming = streaming;
+    // The same idea for two more capabilities the browser build does not have.
+    // A client decides what to offer from what the instance document says, so
+    // the honest thing is to say nothing rather than advertise and no-op.
+    //
+    // `webPush`: the browser build's web-push is a shim that mints a random
+    // placeholder VAPID key and whose sendNotification does nothing. Advertised,
+    // the client shows a notifications toggle that looks on and never fires.
+    // Omit `vapid` and it hides the toggle instead.
+    this.webPush = webPush;
+    // `scheduling`: a scheduled post is only a stored row until something
+    // publishes it when its time comes, and the only such tick is the Node
+    // agent's (run-agent.mjs). Where nothing ticks, accepting one is silent
+    // loss — the client says "scheduled" and the post never appears. Refusing
+    // it is worse UX and better behaviour.
+    this.scheduling = scheduling;
+    this.authzAttempts = [];            // password-attempt timestamps
+  }
+
+  get store() { return this.agent.store; }
+  get urls() { return this.agent.publisher?.urls; }
+  get push() {
+    this._push ||= new Push({
+      store: this.store,
+      subject: () => this.urls?.actor || 'https://localhost/',
+      log: this.log,
+    });
+    return this._push;
+  }
+  get host() { return this.urls ? new URL(this.urls.base).host : 'unconfigured.invalid'; }
+
+  // Where the live feed is, as the CLIENT must address it: this agent's own
+  // origin, taken from the request, not the pod's host. An instance document
+  // that leaves it empty is not merely unhelpful — clients read it without a
+  // guard and fall over, and every one of them loses live updates.
+  streamingUrl(req) {
+    if (!this.streaming) return null;   // fetch-only facade: no WebSocket, no wss://localhost prompt
+    const host = req?.headers?.host || `localhost:${this.port || ''}`;
+    const secure = this.scheme
+      ? this.scheme.startsWith('https')
+      : req?.headers?.['x-forwarded-proto'] === 'https' || !!req?.socket?.encrypted;
+    return `${secure ? 'wss' : 'ws'}://${host}/api/v1/streaming`;
+  }
+
+  static scopeFor(...a) { return oauth.scopeFor(...a); }
+  static scopeAllows(...a) { return oauth.scopeAllows(...a); }
+  static redirectMatches(...a) { return oauth.redirectMatches(...a); }
+  static provesCode(...a) { return oauth.provesCode(...a); }
+
+  // ---- request handling; returns true when handled ----
+  async handle(req, res, pathname, url) {
+    const send = (status, obj, headers = {}) => {
+      const body = JSON.stringify(obj);
+      res.writeHead(status, { 'content-type': 'application/json', ...headers });
+      res.end(body);
+      return true;
+    };
+    const ctx = { req, res, pathname, url, send };
+
+    if (await oauth.handle(this, ctx)) return true;
+    if (!pathname.startsWith('/api/')) return false;
+    if (await instance.handle(this, ctx)) return true;
+
+    // --- everything below needs a bearer token + a configured agent ---
+    const bearer = this.tokenOf(req);
+    if (!bearer) return send(401, { error: 'The access token is invalid' });
+    // One gate for every client route below, rather than a check in each of
+    // the fifty-odd branches — which is how the scope came to be recorded and
+    // never consulted in the first place.
+    const need = MastoApi.scopeFor(req.method, pathname);
+    if (!MastoApi.scopeAllows(bearer.scope, need)) {
+      this.log(`refused ${req.method} ${pathname}: token has "${bearer.scope}", needs "${need}"`);
+      return send(403, { error: `This action is outside the authorized scopes (needs ${need})` });
+    }
+    if (!this.agent.configured()) return send(503, { error: 'agent not configured' });
+    // A viewer-mode agent (another agent holds the drain lease) may not act —
+    // but a user acting HERE outranks the idle active agent elsewhere, so a
+    // write attempt claims the lease and proceeds. Only a failed claim 503s.
+    if (this.agent.viewer && req.method !== 'GET' && req.method !== 'HEAD') {
+      const took = await this.agent.requestTakeover?.();
+      if (!took) return send(503, { error: 'another agent is active for this pod — takeover failed, try again' });
+    }
+
+    for (const area of [accounts, timelines, statuses, media]) {
+      if (await area.handle(this, ctx)) return true;
+    }
+
+    this.log(`mastoapi: unhandled ${req.method} ${pathname} — punch list`);
+    return send(404, { error: `Unimplemented: ${req.method} ${pathname}` });
+  }
+
+  // oauth.mjs
+  tokenRecords(...a) { return oauth.tokenRecords(this, ...a); }
+  tokens(...a) { return oauth.tokens(this, ...a); }
+  mintToken(...a) { return oauth.mintToken(this, ...a); }
+  apps(...a) { return oauth.apps(this, ...a); }
+  authorizationServerMetadata(...a) { return oauth.authorizationServerMetadata(this, ...a); }
+  findApp(...a) { return oauth.findApp(this, ...a); }
+  resolveClientDocument(...a) { return oauth.resolveClientDocument(this, ...a); }
+  registerApp(...a) { return oauth.registerApp(this, ...a); }
+  mintCode(...a) { return oauth.mintCode(this, ...a); }
+  consumeCode(...a) { return oauth.consumeCode(this, ...a); }
+  tokenOf(...a) { return oauth.tokenOf(this, ...a); }
+  authed(...a) { return oauth.authed(this, ...a); }
+  redirectAllowed(...a) { return oauth.redirectAllowed(this, ...a); }
+  rateLimited(...a) { return oauth.rateLimited(this, ...a); }
+
+  // render.mjs
+  selfAccount(...a) { return render.selfAccount(this, ...a); }
+  account(...a) { return render.account(this, ...a); }
+  page(...a) { return render.page(this, ...a); }
+  bskyReply(...a) { return render.bskyReply(this, ...a); }
+  acctAction(...a) { return render.acctAction(this, ...a); }
+  acctReply(...a) { return render.acctReply(this, ...a); }
+  status(...a) { return render.status(this, ...a); }
+  filtersFor(...a) { return render.filtersFor(this, ...a); }
+  lookup(...a) { return render.lookup(this, ...a); }
+  statusOrBoost(...a) { return render.statusOrBoost(this, ...a); }
+  pushNotify(...a) { return render.pushNotify(this, ...a); }
+  scheduledJson(...a) { return render.scheduledJson(this, ...a); }
+  pollJson(...a) { return render.pollJson(this, ...a); }
+  mediaJson(...a) { return render.mediaJson(this, ...a); }
+  relationship(...a) { return render.relationship(this, ...a); }
+  notificationType(...a) { return render.notificationType(this, ...a); }
+  notification(...a) { return render.notification(this, ...a); }
+  accountSearch(...a) { return render.accountSearch(this, ...a); }
+
+  // instance.mjs
+  instanceTitle(...a) { return instance.instanceTitle(this, ...a); }
+  tagObject(...a) { return instance.tagObject(this, ...a); }
+  instanceBlurb(...a) { return instance.instanceBlurb(this, ...a); }
+}

package/lib/client/masto/instance.mjs

@@ -0,0 +1,104 @@
+// instance.mjs — what the instance says about itself: the v1 and v2 instance
+// documents, the limits a client reads from them, the title and blurb, the
+// tag object, and the empty-collection stubs for endpoints a single-actor
+// instance has nothing to say to.
+
+import { TRANSPARENT_PNG } from './render.mjs';
+import {
+  MAX_OPTIONS as POLL_MAX_OPTIONS, MAX_OPTION_CHARS as POLL_MAX_OPTION_CHARS,
+  MIN_SECONDS as POLL_MIN_SECONDS, MAX_SECONDS as POLL_MAX_SECONDS,
+} from '../../core/polls.mjs';
+
+const STUBS = new Map(Object.entries({
+  '/api/v1/filters': [],
+  '/api/v1/custom_emojis': [],
+  '/api/v1/announcements': [],
+  '/api/v1/instance/peers': [],
+  '/api/v1/trends/tags': [], '/api/v1/trends/links': [],
+  '/api/v2/suggestions': [],
+  '/api/v1/preferences': {},
+}));   // followed_tags is served live from the tag feed, not stubbed
+
+export function instanceConfig() {
+  return {
+    statuses: { max_characters: 5000, max_media_attachments: 4, characters_reserved_per_url: 23 },
+    media_attachments: {
+      supported_mime_types: ['image/jpeg', 'image/png', 'image/gif', 'image/webp',
+        'video/mp4', 'video/webm', 'audio/mpeg', 'audio/ogg'],
+      image_size_limit: 10 * 1024 * 1024, video_size_limit: 40 * 1024 * 1024,
+      image_matrix_limit: 16777216, video_matrix_limit: 2304000,
+    },
+    polls: {
+      max_options: POLL_MAX_OPTIONS,
+      max_characters_per_option: POLL_MAX_OPTION_CHARS,
+      min_expiration: POLL_MIN_SECONDS,
+      max_expiration: POLL_MAX_SECONDS,
+    },
+    accounts: { max_featured_tags: 0 },
+  };
+}
+
+// Every agent used to report title 'solid-activitypub', so a client holding two
+// of them showed two identical instances and you had to read the acct to tell
+// them apart. The title is free text no client parses — make it say who.
+export function instanceTitle(api) {
+  const cfg = api.store.getConfig();
+  return cfg?.handle ? `@${cfg.handle}@${api.host}` : 'FediPod';
+}
+
+// A Mastodon Tag object. The client reads `following` in its Followed
+// Hashtags view and toggles it with the follow/unfollow endpoints. No usage
+// history — a single-actor instance has no firehose stats to report.
+export function tagObject(api, name, following, req) {
+  const host = req?.headers?.host || api.host;
+  return { name, url: `https://${host}/tags/${name}`, history: [], following: !!following };
+}
+
+export function instanceBlurb(api) {
+  const kind = api.store.getConfig()?.kind === 'group' ? 'group' : 'actor';
+  return `Solid pod ActivityPub ${kind}`;
+}
+
+export async function handle(api, ctx) {
+  const { req, res, pathname, url, send } = ctx;   // eslint-disable-line no-unused-vars
+
+  // --- instance (public) ---
+  if (pathname === '/api/v1/instance') {
+    const su = api.streamingUrl(req);
+    return send(200, {
+      uri: api.host, title: api.instanceTitle(), short_description: api.instanceBlurb(),
+      description: api.instanceBlurb(), email: '', version: '4.2.0 (compatible; fedipod)',
+      urls: su ? { streaming_api: su } : {},
+      stats: { user_count: 1, status_count: api.store.countStatuses(), domain_count: 1 },
+      languages: ['en'], registrations: false, approval_required: false, invites_enabled: false,
+      configuration: instanceConfig(),
+      contact_account: null, rules: [],
+    });
+  }
+  if (pathname === '/api/v2/instance') {
+    const su = api.streamingUrl(req);
+    return send(200, {
+      domain: api.host, title: api.instanceTitle(), version: '4.2.0 (compatible; fedipod)',
+      source_url: 'https://github.com/jeff-zucker/FediPod', description: api.instanceBlurb(),
+      usage: { users: { active_month: 1 } },
+      thumbnail: { url: TRANSPARENT_PNG },
+      languages: ['en'],
+      // Both spellings: v2 clients read configuration.urls.streaming, older
+      // ones the top-level urls.streaming_api, and some fall back blindly.
+      // Omitted entirely when there is no streaming, so the client polls.
+      urls: su ? { streaming_api: su } : {},
+      configuration: {
+        ...instanceConfig(),
+        ...(su ? { urls: { streaming: su } } : {}),
+        ...(api.webPush ? { vapid: { public_key: api.push.publicKey() } } : {}),
+      },
+      registrations: { enabled: false, approval_required: false, message: null },
+      contact: { email: '', account: null }, rules: [],
+    });
+  }
+
+  const stub = STUBS.get(pathname);
+  if (stub !== undefined && req.method === 'GET') return send(200, stub);
+
+  return false;
+}