fedipod-server 0.28.1 → 0.30.0

package/lib/client/masto/accounts.mjs

@@ -1,309 +0,0 @@
-// 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, readMultipart } from './body.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());
-    }
-    // By host with its port, as the account is shown; and by hostname alone,
-    // for a client that drops the port from an address it was given.
-    const hit = Object.entries(api.store.getActors()).find(([u, a]) => {
-      try {
-        const at = new URL(u);
-        return `${a.preferredUsername}@${at.host}` === acct || `${a.preferredUsername}@${at.hostname}` === 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 instance's own directory is its one account; there is nothing to
-  // suggest and nothing trending, so those screens are empty rather than 404.
-  if (pathname === '/api/v1/directory') return send(200, api.urls?.actor ? [api.account(api.urls.actor)] : []);
-  if (pathname === '/api/v1/suggestions') return send(200, []);
-
-  // The lists this account is on — what "add to list" from a profile reads.
-  const mAccLists = /^\/api\/v1\/accounts\/([a-f0-9]+)\/lists$/.exec(pathname);
-  if (mAccLists && req.method === 'GET') {
-    const actorUrl = api.store.urlFor(mAccLists[1]);
-    if (!actorUrl) return send(404, { error: 'Record not found' });
-    return send(200, api.store.getLists().filter(l => (l.members || []).includes(actorUrl))
-      .map(l => ({ id: l.id, title: l.title, replies_policy: l.repliesPolicy || 'list', exclusive: false })));
-  }
-
-  // The people muted and blocked, as accounts; the domains blocked, as names.
-  if (pathname === '/api/v1/mutes' && req.method === 'GET') {
-    return send(200, (api.store.getMuted().actors || []).map(a => api.account(a)));
-  }
-  if (pathname === '/api/v1/blocks' && req.method === 'GET') {
-    return send(200, (api.store.getBlocklist().actors || []).map(a => api.account(a)));
-  }
-  if (pathname === '/api/v1/domain_blocks') {
-    const b = api.store.getBlocklist();
-    if (req.method === 'GET') return send(200, [...b.domains]);
-    const body = await readBody(req);
-    const domain = String(body.domain || url.searchParams.get('domain') || '').trim().toLowerCase();
-    if (!/^[a-z0-9.-]+\.[a-z]{2,}$/u.test(domain)) return send(422, { error: 'a domain is required' });
-    if (req.method === 'POST' && !b.domains.includes(domain)) b.domains.push(domain);
-    if (req.method === 'DELETE') b.domains = b.domains.filter(d => d !== domain);
-    api.store.setBlocklist(b);
-    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 q = url.searchParams;
-    const is = (name) => q.get(name) === 'true' || q.get(name) === '1';
-    const pinnedOnly = is('pinned');
-    const tagged = String(q.get('tagged') || '').replace(/^#/, '').toLowerCase();
-    const isBoost = (s) => !!s.via && s.via !== s.actor;
-    const { items, headers } = api.page(
-      all.filter(s => s.actor === actorUrl && (!pinnedOnly || s.pinned))
-        .filter(s => !is('exclude_replies') || !s.inReplyTo)
-        .filter(s => !is('exclude_reblogs') || !isBoost(s))
-        .filter(s => !is('only_media') || (s.attachments || []).length > 0)
-        .filter(s => !tagged || (s.tags || []).some(t => String(t.name).toLowerCase() === tagged)), url);
-    return send(200, items.map(s => api.statusOrBoost(s, { all })), headers);
-  }
-
-  return false;
-}

package/lib/client/masto/body.mjs

@@ -1,156 +0,0 @@
-// body.mjs — reading what a client sent: JSON, form-encoded or multipart
-// 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 multipart body is not a query string: read as one it becomes a
-        // single nonsense key, so every field a client sent that way arrived
-        // undefined. Sengi registers its OAuth client with a FormData, which
-        // is multipart, so /api/v1/apps saw no redirect_uris and handed back
-        // the out-of-band URN, leaving the client nowhere to come back to.
-        if (ct.includes('multipart/form-data')) return resolve(textFields(data, ct));
-        // 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);
-  });
-}
-
-/**
- * The text fields of a multipart body that arrived as text. readBody
- * accumulates the body as a string, so this reads the fields out of that
- * string rather than out of bytes — which is all a client sending a plain
- * form this way has in it. A body with a FILE in it is not this reader's:
- * a text round trip corrupts binary, and the upload endpoints take their
- * bytes from readMultipart below.
- */
-function textFields(data, contentType) {
-  const m = /boundary=(?:"([^"]+)"|([^;]+))/.exec(contentType);
-  if (!m) return {};
-  const out = {};
-  for (const part of data.split('--' + (m[1] || m[2]).trim())) {
-    const sep = part.indexOf('\r\n\r\n');
-    if (sep < 0) continue;
-    const head = part.slice(0, sep);
-    const name = /name="([^"]*)"/.exec(head)?.[1];
-    // A file part is skipped rather than kept as mangled text.
-    if (!name || /filename="/.test(head)) continue;
-    const value = part.slice(sep + 4).replace(/\r\n$/, '');
-    if (name.endsWith('[]')) (out[name] ||= []).push(value);
-    else out[name] = value;
-  }
-  return out;
-}
-
-// Minimal multipart/form-data reader for media uploads: string fields plus
-// at most one file part (Mastodon's media endpoints send exactly one).
-export function readMultipart(req, limit = 12e6) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    let n = 0;
-    req.on('data', c => {
-      n += c.length;
-      if (n > limit) { reject(new Error('upload too large')); req.destroy(); return; }
-      chunks.push(c);
-    });
-    req.on('error', reject);
-    req.on('end', () => {
-      try {
-        const m = /boundary=(?:"([^"]+)"|([^;]+))/.exec(String(req.headers['content-type'] || ''));
-        if (!m) return resolve({ fields: {}, file: null });
-        const buf = Buffer.concat(chunks);
-        const boundary = Buffer.from('--' + (m[1] || m[2]).trim());
-        const fields = {};
-        // `file` is the last one seen, which is what the single-file media
-        // upload wants. `files` keys them by field name, because the profile
-        // editor submits an avatar and a header in one request.
-        const files = {};
-        let file = null;
-        let i = buf.indexOf(boundary);
-        while (i >= 0) {
-          const start = i + boundary.length;
-          if (buf.slice(start, start + 2).toString() === '--') break;
-          const next = buf.indexOf(boundary, start);
-          if (next < 0) break;
-          const part = buf.slice(start + 2, next - 2);        // strip the CRLFs framing the part
-          const sep = part.indexOf('\r\n\r\n');
-          if (sep >= 0) {
-            const head = part.slice(0, sep).toString();
-            const body = part.slice(sep + 4);
-            const name = /name="([^"]*)"/.exec(head)?.[1];
-            const filename = /filename="([^"]*)"/.exec(head)?.[1];
-            if (filename !== undefined) {
-              file = {
-                filename,
-                contentType: /content-type:\s*([^\r\n]+)/i.exec(head)?.[1]?.trim() || 'application/octet-stream',
-                data: body,
-              };
-              if (name) files[name] = file;
-            } else if (name) fields[name] = body.toString();
-          }
-          i = next;
-        }
-        resolve({ fields, file, files });
-      } catch (e) { reject(e); }
-    });
-  });
-}
-

package/lib/client/masto/index.mjs

@@ -1,206 +0,0 @@
-// 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, throughDoor = null,
-    mount = '', streaming = true, webPush = true, scheduling = true }) {
-    this.agent = agent;
-    // The path this identity's surface answers under, when it shares its origin
-    // with others (a suffix pod, e.g. `/aisha`). Empty for a host-root or
-    // subdomain pod. Folded into the self-URLs the client is handed —
-    // pagination links, the OAuth issuer — so they name the address the client
-    // actually reached.
-    this.mount = mount;
-    // 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
-    // Whether a request already passed the owner's door (its key or cookie):
-    // an owner who opened the management page is the owner at the sign-in too.
-    this.throughDoor = throughDoor;
-    // 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;
-  }
-  // The host in the owner's own address: the gateway's when the identity is
-  // fronted (its documents still live on the pod, but its name does not).
-  get host() {
-    if (!this.urls) return 'unconfigured.invalid';
-    return new URL(this.urls.publicHome || this.urls.base).host;
-  }
-
-  // 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;
-    };
-    // The address the client reached, so every self-URL handed back — the
-    // pagination links above all — names it rather than the pod's host.
-    const scheme = String(this.scheme
-      || (req.headers?.['x-forwarded-proto'] === 'https' || req.socket?.encrypted ? 'https' : 'http')).replace(/:.*$/, '');
-    let self = url;
-    try {
-      self = new URL(`${scheme}://${req.headers?.host || 'localhost'}${this.mount || ''}${pathname}${url.search || ''}`);
-    } catch { /* a Host nothing can parse: the links keep the placeholder origin */ }
-    const ctx = { req, res, pathname, url: self, 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); }
-  quoteApproval(...a) { return render.quoteApproval(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); }
-}