fedipod-server 0.9.0 → 0.11.0

package/lib/mastoapi.mjs

@@ -11,12 +11,18 @@
 // that log is the running punch list.
 
 import crypto from 'node:crypto';
+import * as podMedia from './pod/media.mjs';
 import * as social from './social.mjs';
+import { isCrossSiteNavigation } from './guard.mjs';
 import { sanitizeHtml, followsNeedApproval, publicHandle } from './wire.mjs';
 import { authorOf } from './intake.mjs';
 import { profileUrl, postUrl } from './bskyfeed.mjs';
 import { Push } from './webpush.mjs';
 import { safeFetch, readCapped } from './safefetch.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 './polls.mjs';
 
 // What an attachment is allowed to BE. Anything else is stored as bytes, which
 // a browser downloads rather than runs.
@@ -27,6 +33,26 @@ const ATTACHMENT_KINDS = new Set(['image', 'video', 'audio']);
 const NEVER = new Set(['image/svg+xml', 'image/svg']);
 const OPAQUE = 'application/octet-stream';
 
+/**
+ * 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',
+  };
+}
+
 export function attachmentType(claimed) {
   const t = String(claimed || '').split(';')[0].trim().toLowerCase();
   if (!/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/.test(t) || NEVER.has(t)) return OPAQUE;
@@ -50,13 +76,11 @@ const STUBS = new Map(Object.entries({
   '/api/v1/filters': [],
   '/api/v1/custom_emojis': [],
   '/api/v1/announcements': [],
-  '/api/v1/follow_requests': [],
   '/api/v1/instance/peers': [],
   '/api/v1/trends/tags': [], '/api/v1/trends/links': [],
   '/api/v2/suggestions': [],
   '/api/v1/preferences': {},
-  '/api/v1/followed_tags': [],
-}));
+}));   // followed_tags is served live from the tag feed, not stubbed
 
 const TOKEN_TTL_MS = 90 * 24 * 60 * 60 * 1000;   // tokens age out after 90 days
 const AUTHZ_WINDOW_MS = 60_000;
@@ -64,10 +88,14 @@ const AUTHZ_MAX_ATTEMPTS = 5;
 const CODE_TTL_MS = 5 * 60_000;                  // an authorization code is short-lived
 const MAX_APPS = 200;                            // registered third-party clients, capped
 const CLIENT_DOC_TTL_MS = 10 * 60_000;           // how long a fetched client document is trusted
+const CLIENT_DOC_MAX_CACHED = 200;               // ids remembered at once; oldest out
+const CLIENT_DOC_WINDOW_MS = 60_000;
+const CLIENT_DOC_MAX_FETCHES = 20;               // outbound lookups per window
 const CLIENT_DOC_MAX = 64 * 1024;                // it names a client; it is not a payload
 
 export class MastoApi {
-  constructor({ agent, log = console.log, allowed = null, scheme = null, embedded = false }) {
+  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.
@@ -77,6 +105,29 @@ export class MastoApi {
     // 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
   }
 
@@ -97,6 +148,7 @@ export class MastoApi {
   // 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')
@@ -116,14 +168,54 @@ export class MastoApi {
     const now = Date.now();
     return this.tokenRecords().filter(r => now - (r.createdAt || 0) < TOKEN_TTL_MS).map(r => r.token);
   }
-  mintToken() {
+  // `scope` is what the owner actually granted at /oauth/authorize. It used to
+  // be discarded: every token was full authority, so a client that asked for
+  // `read` could post, delete, and edit the profile. Recorded now, and enforced
+  // at the one gate every client route passes (see scopeFor / authed).
+  mintToken(scope = null) {
     const t = crypto.randomBytes(24).toString('hex');
     const now = Date.now();
     const kept = this.tokenRecords().filter(r => now - (r.createdAt || 0) < TOKEN_TTL_MS);
-    this.store.write('masto-tokens.json', [...kept, { token: t, createdAt: now }].slice(-20));
+    this.store.write('masto-tokens.json',
+      [...kept, { token: t, createdAt: now, ...(scope ? { scope } : {}) }].slice(-20));
     return t;
   }
 
+  // What one request needs. Mastodon's four coarse scopes; a client that was
+  // granted a granular `write:statuses` satisfies `write` here, which is the
+  // direction that cannot let anything through that `write` would not.
+  //
+  // Reads are `read`, writes are `write`, and the two Mastodon carves out are
+  // kept: relationship changes accept the legacy `follow`, and push
+  // subscriptions want `push`. Nothing here grants across: `write` does NOT
+  // imply `read`, exactly as on Mastodon, so a write-only client cannot read
+  // the owner's direct messages.
+  static scopeFor(method, pathname) {
+    if (/^\/api\/v\d\/push\//u.test(pathname)) return 'push';
+    const relationship = /^\/api\/v1\/(accounts\/[a-f0-9]+\/(follow|unfollow|block|unblock|mute|unmute|remove_from_followers)|follow_requests\/)/u;
+    if (method !== 'GET' && method !== 'HEAD') {
+      return relationship.test(pathname) ? 'follow' : 'write';
+    }
+    return 'read';
+  }
+
+  // Whether a token's granted scopes satisfy `need`.
+  //
+  // A record with NO scope is a token minted before scopes were kept — it is
+  // full authority, because that is what it was granted, and quietly demoting
+  // live 90-day tokens would sign people out of working clients for a bug that
+  // was ours. New tokens all carry one.
+  static scopeAllows(granted, need) {
+    if (granted == null) return true;                       // pre-scope token
+    const have = String(granted).split(/[\s,+]+/u).filter(Boolean);
+    if (!have.length) return true;
+    if (need === 'follow') {
+      // Mastodon's `follow` is the legacy spelling; `write` covers it too.
+      return have.some((g) => g === 'follow' || g === 'write' || g.startsWith('write:'));
+    }
+    return have.some((g) => g === need || g.startsWith(`${need}:`));
+  }
+
   // Registered OAuth apps. A third-party (browser) client registers here, and
   // the authorization code it later receives is bound to the client_id and the
   // redirect_uri it registered — so the code reaches only where that client
@@ -170,31 +262,55 @@ export class MastoApi {
     if (!/^https:\/\//iu.test(String(clientId || ''))) return null;   // cleartext is refused
     this.clientDocs = this.clientDocs || new Map();
     const seen = this.clientDocs.get(clientId);
+    // A cached FAILURE counts. Only successes were remembered, so a client id
+    // that 404s (or is not a client document at all) was re-fetched on every
+    // single call — and this runs on an unauthenticated GET, so a page could
+    // fire these in a loop and have the owner's machine hammer an address of
+    // the attacker's choosing, from the owner's IP, indefinitely.
     if (seen && Date.now() - seen.at < CLIENT_DOC_TTL_MS) return seen.client;
+    // And a budget, because caching alone still lets a fresh id per request
+    // through. `safeFetch` keeps every one of these to a public address, so
+    // this is not internal SSRF — it is amplification, and a cap is what
+    // amplification needs.
+    if (!this._clientDocFetches || Date.now() - this._clientDocWindow > CLIENT_DOC_WINDOW_MS) {
+      this._clientDocWindow = Date.now();
+      this._clientDocFetches = 0;
+    }
+    if (this._clientDocFetches >= CLIENT_DOC_MAX_FETCHES) {
+      this.log(`client document ${clientId} not fetched: too many lookups this minute`);
+      return null;
+    }
+    this._clientDocFetches += 1;
+    // The Map has a TTL but had no ceiling, so it grew for as long as an
+    // attacker cared to serve distinct documents. Oldest out when it is full;
+    // Map iterates in insertion order, so the first key is the oldest.
+    if (this.clientDocs.size >= CLIENT_DOC_MAX_CACHED) {
+      this.clientDocs.delete(this.clientDocs.keys().next().value);
+    }
+    const remember = (client) => { this.clientDocs.set(clientId, { at: Date.now(), client }); return client; };
     let doc;
     try {
       const res = await safeFetch(clientId, { headers: { accept: 'application/json' } });
-      if (res.status >= 400) { this.log(`client document ${clientId} → ${res.status}`); return null; }
+      if (res.status >= 400) { this.log(`client document ${clientId} → ${res.status}`); return remember(null); }
       doc = JSON.parse(await readCapped(res, CLIENT_DOC_MAX));
     } catch (e) {
       this.log(`client document ${clientId} could not be read: ${e.message}`);
-      return null;
+      return remember(null);
     }
     // It must claim to be itself: a document naming some other id would let
     // one client borrow another's name.
     if (doc?.client_id !== clientId) {
       this.log(`client document ${clientId} names ${doc?.client_id ?? 'nothing'} — refused`);
-      return null;
+      return remember(null);
     }
     const redirectUris = [].concat(doc.redirect_uris || []).filter((u) => typeof u === 'string');
-    if (!redirectUris.length) { this.log(`client document ${clientId} names no redirect — refused`); return null; }
+    if (!redirectUris.length) { this.log(`client document ${clientId} names no redirect — refused`); return remember(null); }
     const client = {
       clientId, redirectUris,
       name: String(doc.client_name || clientId).slice(0, 200),
       scopes: 'read write follow',
     };
-    this.clientDocs.set(clientId, { at: Date.now(), client });
-    return client;
+    return remember(client);
   }
 
   /**
@@ -270,10 +386,15 @@ export class MastoApi {
     if (rec) this.store.write('oauth-codes.json', all.filter(c => c.code !== code));   // single-use
     return rec || null;
   }
-  authed(req) {
+  // The live record for the bearer on this request, or null.
+  tokenOf(req) {
     const m = /^Bearer (.+)$/.exec(req.headers.authorization || '');
-    return !!m && this.tokens().includes(m[1]);
+    if (!m) return null;
+    const now = Date.now();
+    return this.tokenRecords().find(
+      (r) => r.token === m[1] && now - (r.createdAt || 0) < TOKEN_TTL_MS) || null;
   }
+  authed(req) { return !!this.tokenOf(req); }
 
   // A redirect_uri must name an authority this agent answers on — otherwise
   // a visited page could navigate to /oauth/authorize and have the freshly
@@ -304,6 +425,14 @@ export class MastoApi {
     return cfg?.handle ? `@${cfg.handle}@${this.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.
+  tagObject(name, following, req) {
+    const host = req?.headers?.host || this.host;
+    return { name, url: `https://${host}/tags/${name}`, history: [], following: !!following };
+  }
+
   instanceBlurb() {
     const kind = this.store.getConfig()?.kind === 'group' ? 'group' : 'actor';
     return `Solid pod ActivityPub ${kind}`;
@@ -551,9 +680,52 @@ export class MastoApi {
         shortcode: e.shortcode, url: e.url, static_url: e.url, visible_in_picker: false,
       })),
       card: null, poll: s.poll ? this.pollJson(s) : null,
+      // What a filter matched, if any. Mastodon's clients read this and do the
+      // hiding or warning; they do NOT match keywords themselves — Phanpy does
+      // not — so filters that were stored and served but never applied were a
+      // setting that did nothing. The README named them as a feature.
+      filtered: this.filtersFor(s),
     };
   }
 
+  // v2 filters against one status. `context` is the timeline the client is
+  // showing, which we do not know here, so every non-expired filter is offered
+  // and the client drops the ones whose context does not match — the same
+  // information it uses to decide anyway.
+  filtersFor(s) {
+    const now = Date.now();
+    const hay = `${s.content || ''} ${s.spoiler || ''}`
+      .replace(/<[^>]*>/gu, ' ')            // the text, not the markup around it
+      .toLowerCase();
+    if (!hay.trim()) return [];
+    const out = [];
+    // `status()` renders on every timeline read, including from the Bluesky and
+    // connected-account paths whose stores are narrower than the pod's. A
+    // missing filter list means no filters, never a thrown render.
+    for (const f of this.store.getFilters?.() || []) {
+      if (f.expiresAt && Date.parse(f.expiresAt) <= now) continue;
+      const hit = (f.keywords || []).filter((k) => {
+        const word = String(k.keyword || '').toLowerCase().trim();
+        if (!word) return false;
+        if (!k.wholeWord) return hay.includes(word);
+        // A whole word, by the same rule Mastodon uses: a boundary that is not
+        // itself a word character, at both ends.
+        const esc = word.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+        return new RegExp(`(?:^|[^\\p{L}\\p{N}_])${esc}(?:[^\\p{L}\\p{N}_]|$)`, 'u').test(hay);
+      }).map((k) => k.keyword);
+      if (!hit.length) continue;
+      out.push({
+        filter: {
+          id: f.id, title: f.title, context: f.context || ['home'],
+          expires_at: f.expiresAt || null, filter_action: f.action || 'warn',
+        },
+        keyword_matches: hit,
+        status_matches: [],
+      });
+    }
+    return out;
+  }
+
   // A timeline row's id may name the CARRY rather than the post — statusOrBoost
   // mints `via:<noteId>` for the envelope. A client that asks about a row it
   // was served has to get an answer: a 404 there makes it drop the row, which
@@ -628,7 +800,7 @@ export class MastoApi {
       expires_at: s.poll.expiresAt || null,
       expired: !!s.poll.closed || (!!s.poll.expiresAt && Date.parse(s.poll.expiresAt) < Date.now()),
       multiple: !!s.poll.multiple,
-      votes_count: votes, voters_count: null,
+      votes_count: votes, voters_count: s.poll.votersCount ?? null,
       options: opts.map(o => ({ title: o.title, votes_count: o.votes || 0 })),
       voted: !!s.poll.voted, own_votes: s.poll.ownVotes || [],
       emojis: [],
@@ -638,7 +810,11 @@ export class MastoApi {
   mediaJson(a) {
     const kind = /^video\//.test(a.mediaType) ? 'video'
       : /^audio\//.test(a.mediaType) ? 'audio'
-        : /^image\/gif/.test(a.mediaType) ? 'gifv' : 'image';
+        // NOT 'gifv'. Mastodon uses gifv for a silent MP4 it transcoded a GIF
+        // into, and a client renders one with <video src>; handed the raw .gif
+        // URL, every GIF came out blank. Nothing here transcodes, so what we
+        // have is an image and saying so is what makes it show.
+        : 'image';
     return {
       id: a.id || this.store.idFor(a.url),
       type: kind, url: a.url, preview_url: a.url, remote_url: null,
@@ -661,8 +837,14 @@ export class MastoApi {
     };
   }
 
+  // Ours is stored with a hyphen; Mastodon's API spells it with an underscore,
+  // and a client that does not know the type shows "Unknown notification type"
+  // — which is what every Mastodon client did with a follow request here. The
+  // stored spelling is left alone so existing state keeps reading.
+  notificationType(t) { return t === 'follow-request' ? 'follow_request' : t; }
+
   notification(n) {
-    const out = { id: n.id, type: n.type, created_at: n.at, account: this.account(n.actor) };
+    const out = { id: n.id, type: this.notificationType(n.type), created_at: n.at, account: this.account(n.actor) };
     if (n.noteId) {
       const s = this.store.getStatuses().find(x => x.noteId === n.noteId);
       if (s) out.status = this.status(s);
@@ -723,7 +905,7 @@ export class MastoApi {
         id: app.clientId, name: app.name, website: app.website,
         client_id: app.clientId, client_secret: app.clientSecret,
         redirect_uri: redirectUris.join(' ') || 'urn:ietf:wg:oauth:2.0:oob',
-        vapid_key: this.push.publicKey(),
+        ...(this.webPush ? { vapid_key: this.push.publicKey() } : {}),
       });
     }
     if (pathname === '/oauth/authorize' && (req.method === 'GET' || req.method === 'POST')) {
@@ -744,6 +926,42 @@ export class MastoApi {
       // code-is-the-token flow is only for the built-in client, which never
       // registers.
       const external = !!app || !!doc;
+
+      // S36. Two doors were open at once, and together they handed a bearer for
+      // this account to any page the owner happened to be reading.
+      //
+      // /api/v1/apps takes any redirect_uri from anyone — as it must, that is
+      // how a fediverse client registers — and the instant-authorize path below
+      // mints without a password whenever the request "is this machine". A page
+      // in another tab is this machine. So: register a client whose redirect is
+      // your own server, navigate the owner's browser to /oauth/authorize, and
+      // the code arrives at your address. The agent's own CA is in the browser's
+      // trust store, so https://localhost:<port> loads without a murmur.
+      //
+      // Two locks, either of which alone would do, both cheap:
+      //
+      // 1. A cross-site NAVIGATION may not reach the mint. A client signing in
+      //    navigates from its own page and is same-site; a page on somebody
+      //    else's site is not. (Absent Sec-Fetch-Site — curl, an old browser —
+      //    is not cross-site and still passes, as everywhere else in this
+      //    project; the second lock is what covers that case.)
+      if (isCrossSiteNavigation(req)) {
+        this.log(`authorize refused: cross-site navigation to the mint from ${req.headers.referer || 'nowhere'}`);
+        return send(403, { error: 'a cross-site navigation may not authorize a client' });
+      }
+      // 2. With NO password set there is nothing to authorize a third party
+      //    WITH. The password-less path is honest only for a client on an
+      //    address this agent itself answers on — where "whoever reaches the
+      //    port is the owner" is a statement about the machine rather than
+      //    about a web page. Anything pointing elsewhere has to be approved by
+      //    somebody who knows the password.
+      if (external && !this.store.getConfig()?.uiPassword && !this.redirectAllowed(redirect)) {
+        this.log(`authorize refused: no UI password, and "${redirect}" is not an address of this agent`);
+        return send(403, {
+          error: 'this client asks to be sent somewhere other than this agent, and no password is '
+            + 'set to approve that with. Run `fedipod passwd` and try again.',
+        });
+      }
       const client = { name: app?.name || doc?.name || null, redirect, scope: params.get('scope') || 'read' };
       if (app) {
         if (!app.redirectUris.includes(redirect)) {
@@ -806,7 +1024,7 @@ export class MastoApi {
         ? this.mintCode({ clientId: (app || doc).clientId, redirectUri: redirect, scope: client.scope,
           challenge: params.get('code_challenge') || null,
           challengeMethod: params.get('code_challenge_method') || null })
-        : this.mintToken();
+        : this.mintToken(client.scope);
       if (!redirect || redirect === 'urn:ietf:wg:oauth:2.0:oob') return send(200, { code });
       const target = new URL(redirect);
       target.searchParams.set('code', code);
@@ -834,7 +1052,7 @@ export class MastoApi {
           this.log('token refused: the verifier does not answer the challenge this code was made with');
           return send(400, { error: 'invalid_grant' });
         }
-        return send(200, { access_token: this.mintToken(), token_type: 'Bearer',
+        return send(200, { access_token: this.mintToken(rec.scope || 'read'), token_type: 'Bearer',
           scope: rec.scope || 'read', created_at: Math.floor(Date.now() / 1000),
           ...(this.urls?.actor ? { activitypub_actor_id: this.urls.actor } : {}) });
       }
@@ -854,7 +1072,7 @@ export class MastoApi {
           this.log('token refused: the verifier does not answer the challenge this code was made with');
           return send(400, { error: 'invalid_grant' });
         }
-        return send(200, { access_token: this.mintToken(), token_type: 'Bearer',
+        return send(200, { access_token: this.mintToken(rec.scope || 'read'), token_type: 'Bearer',
           scope: rec.scope || 'read', created_at: Math.floor(Date.now() / 1000),
           ...(this.urls?.actor ? { activitypub_actor_id: this.urls.actor } : {}) });
       }
@@ -874,7 +1092,7 @@ export class MastoApi {
           this.log('token refused: this code was made with a challenge and the verifier does not answer it');
           return send(400, { error: 'invalid_grant' });
         }
-        return send(200, { access_token: this.mintToken(), token_type: 'Bearer',
+        return send(200, { access_token: this.mintToken(rec.scope || 'read'), token_type: 'Bearer',
           scope: rec.scope || 'read', created_at: Math.floor(Date.now() / 1000),
           // Which actor the token acts for. A Mastodon client ignores it; an
           // ActivityPub API client needs it, and asking for it separately
@@ -890,8 +1108,13 @@ export class MastoApi {
         this.log('token refused: code is not a live authorization');
         return send(400, { error: 'invalid_grant' });
       }
+      // The scope this token was actually minted with, not whatever the client
+      // asks to be told — reporting one and enforcing another is how a client
+      // ends up surprised by a 403 it was promised it would not get.
+      const granted = this.tokenRecords().find((r) => r.token === body.code)?.scope
+        || 'read write follow push';
       return send(200, { access_token: body.code, token_type: 'Bearer',
-        scope: body.scope || 'read write follow push', created_at: Math.floor(Date.now() / 1000),
+        scope: granted, created_at: Math.floor(Date.now() / 1000),
         ...(this.urls?.actor ? { activitypub_actor_id: this.urls.actor } : {}) });
     }
     if (pathname === '/oauth/revoke' && req.method === 'POST') {
@@ -912,10 +1135,11 @@ export class MastoApi {
 
     // --- instance (public) ---
     if (pathname === '/api/v1/instance') {
+      const su = this.streamingUrl(req);
       return send(200, {
         uri: this.host, title: this.instanceTitle(), short_description: this.instanceBlurb(),
         description: this.instanceBlurb(), email: '', version: '4.2.0 (compatible; fedipod)',
-        urls: { streaming_api: this.streamingUrl(req) },
+        urls: su ? { streaming_api: su } : {},
         stats: { user_count: 1, status_count: this.store.countStatuses(), domain_count: 1 },
         languages: ['en'], registrations: false, approval_required: false, invites_enabled: false,
         configuration: instanceConfig(),
@@ -923,6 +1147,7 @@ export class MastoApi {
       });
     }
     if (pathname === '/api/v2/instance') {
+      const su = this.streamingUrl(req);
       return send(200, {
         domain: this.host, title: this.instanceTitle(), version: '4.2.0 (compatible; fedipod)',
         source_url: 'https://github.com/jeff-zucker/FediPod', description: this.instanceBlurb(),
@@ -931,11 +1156,12 @@ export class MastoApi {
         languages: ['en'],
         // Both spellings: v2 clients read configuration.urls.streaming, older
         // ones the top-level urls.streaming_api, and some fall back blindly.
-        urls: { streaming_api: this.streamingUrl(req) },
+        // Omitted entirely when there is no streaming, so the client polls.
+        urls: su ? { streaming_api: su } : {},
         configuration: {
           ...instanceConfig(),
-          urls: { streaming: this.streamingUrl(req) },
-          vapid: { public_key: this.push.publicKey() },
+          ...(su ? { urls: { streaming: su } } : {}),
+          ...(this.webPush ? { vapid: { public_key: this.push.publicKey() } } : {}),
         },
         registrations: { enabled: false, approval_required: false, message: null },
         contact: { email: '', account: null }, rules: [],
@@ -946,7 +1172,16 @@ export class MastoApi {
     if (stub !== undefined && req.method === 'GET') return send(200, stub);
 
     // --- everything below needs a bearer token + a configured agent ---
-    if (!this.authed(req)) return send(401, { error: 'The access token is invalid' });
+    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
@@ -989,7 +1224,7 @@ export class MastoApi {
         const slug = new Date().toISOString().slice(0, 10) + '-' + crypto.randomBytes(4).toString('hex') + '.' + ext;
         const url = this.urls.media + slug;
         await this.agent.publisher.ensureMediaContainer();
-        await this.agent.remote.put(url, f.data, f.contentType);
+        await podMedia.write(this.agent.remote, url, f.data, f.contentType);
         return url;
       };
 
@@ -1054,6 +1289,41 @@ export class MastoApi {
       return send(200, page.map(s => this.statusOrBoost(s, { all })), headers);
     }
 
+    // --- hashtags: the client's Followed Hashtags surface drives the tag feed ---
+    // followed_tags is what the feed currently pulls; follow/unfollow add and
+    // remove a hashtag (unfollow the last and the topical feed goes quiet); the
+    // tag timeline is the mirrored notes carrying that tag.
+    if (pathname === '/api/v1/followed_tags') {
+      const tags = this.agent.tagfeed?.config().tags || [];
+      return send(200, tags.map(t => this.tagObject(t, true, req)));
+    }
+    const mTagFollow = pathname.match(/^\/api\/v1\/tags\/([^/]+)\/(follow|unfollow)$/);
+    if (mTagFollow && req.method === 'POST') {
+      const name = decodeURIComponent(mTagFollow[1]).replace(/^#/, '').toLowerCase();
+      const follow = mTagFollow[2] === 'follow';
+      const tf = this.agent.tagfeed;
+      if (tf) {
+        const cur = tf.config().tags;
+        tf.setConfig({ tags: follow ? [...new Set([...cur, name])] : cur.filter(t => t !== name) });
+      }
+      return send(200, this.tagObject(name, follow, req));
+    }
+    const mTagGet = pathname.match(/^\/api\/v1\/tags\/([^/]+)$/);
+    if (mTagGet && req.method === 'GET') {
+      const name = decodeURIComponent(mTagGet[1]).replace(/^#/, '').toLowerCase();
+      const following = (this.agent.tagfeed?.config().tags || []).includes(name);
+      return send(200, this.tagObject(name, following, req));
+    }
+    const mTagTl = pathname.match(/^\/api\/v1\/timelines\/tag\/([^/]+)$/);
+    if (mTagTl && req.method === 'GET') {
+      const name = decodeURIComponent(mTagTl[1]).replace(/^#/, '').toLowerCase();
+      const all = this.store.getStatuses();
+      const items = all.filter(s => s.kind === 'tag' && s.tag === name)
+        .sort((a, b) => String(b.published || '').localeCompare(String(a.published || '')));
+      const { items: page, headers } = this.page(items, url);
+      return send(200, page.map(s => this.statusOrBoost(s, { all })), headers);
+    }
+
     if (pathname === '/api/v1/statuses' && req.method === 'POST') {
       const body = await readBody(req);
       if (!body.status) return send(422, { error: 'status text required' });
@@ -1080,7 +1350,48 @@ export class MastoApi {
       const mediaIds = [].concat(body.media_ids || body['media_ids[]'] || []).filter(Boolean);
       const media = this.store.getMedia();
       const attachments = mediaIds.map(id => media[id] && { id, ...media[id] }).filter(Boolean);
+
+      const asking = pollParams(body);
+      if (asking) {
+        // Mastodon's own rules, stated here rather than discovered inside the
+        // publisher, so a client gets the reason back on the request it made.
+        if (attachments.length) return send(422, { error: 'a poll cannot carry media' });
+        if (body.scheduled_at) return send(422, { error: 'a poll cannot be scheduled' });
+        if (asking.options.length < 2) return send(422, { error: 'a poll needs at least two options' });
+        if (asking.options.length > POLL_MAX_OPTIONS) {
+          return send(422, { error: `a poll takes at most ${POLL_MAX_OPTIONS} options` });
+        }
+        if (asking.options.some(o => o.length > POLL_MAX_OPTION_CHARS)) {
+          return send(422, { error: `a poll option is at most ${POLL_MAX_OPTION_CHARS} characters` });
+        }
+        if (new Set(asking.options).size !== asking.options.length) {
+          return send(422, { error: 'a poll\u2019s options must differ from one another' });
+        }
+        const seconds = asking.expiresIn ?? POLL_MAX_SECONDS;
+        if (!Number.isFinite(seconds) || seconds < POLL_MIN_SECONDS || seconds > POLL_MAX_SECONDS) {
+          return send(422, {
+            error: `a poll runs between ${POLL_MIN_SECONDS} and ${POLL_MAX_SECONDS} seconds`,
+          });
+        }
+        try {
+          const q = await this.agent.publisher.publishQuestion(body.status, {
+            options: asking.options, multiple: asking.multiple,
+            expiresAt: new Date(Date.now() + seconds * 1000).toISOString(),
+            inReplyTo, visibility, spoilerText,
+          });
+          return send(200, this.status(this.store.getStatuses().find(x => x.noteId === q.id)));
+        } catch (e) {
+          return send(422, { error: e.message });
+        }
+      }
+
       if (body.scheduled_at) {
+        // Nothing here publishes it when the time comes (see `scheduling` in the
+        // constructor), so saying yes would be losing the post quietly.
+        if (!this.scheduling) {
+          return send(422, { error: 'this instance cannot schedule posts — it has no process '
+            + 'running between now and then to publish one. Post it when you want it sent.' });
+        }
         const at = Date.parse(body.scheduled_at);
         if (!Number.isFinite(at) || at < Date.now() + 60_000) {
           return send(422, { error: 'scheduled_at must be at least a minute from now' });
@@ -1310,7 +1621,9 @@ export class MastoApi {
       return send(200, page.map(s => this.statusOrBoost(s, { all })), headers);
     }
 
-    // v2 filters: stored and served; the client applies them to what it shows.
+    // v2 filters: stored, served, and APPLIED — every status carries what it
+    // matched in `filtered` (see filtersFor), because no client matches
+    // keywords for itself.
     const filterJson = (f) => ({
       id: f.id, title: f.title, context: f.context || ['home'],
       expires_at: f.expiresAt || null, filter_action: f.action || 'warn',
@@ -1460,15 +1773,94 @@ export class MastoApi {
       return send(200, this.status(updated || s));
     }
 
+    // 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, this.store.getRequests().slice(0, limit)
+        .map((r) => this.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 = this.store.urlFor(mReq[1]);
+      if (!actorUrl) return send(404, { error: 'Record not found' });
+      if (!this.store.getRequests().some((r) => r.actor === actorUrl)) {
+        return send(404, { error: 'Record not found' });
+      }
+      try {
+        if (mReq[2] === 'authorize') await social.admitRequest(this.agent, actorUrl);
+        else await social.refuseRequest(this.agent, actorUrl);
+      } catch (e) { return send(422, { error: e.message }); }
+      await this.store.flush();
+      return send(200, this.relationship(actorUrl));
+    }
+
     if (pathname === '/api/v1/notifications') {
       const limit = Math.min(Number(url.searchParams.get('limit')) || 30, 60);
+      const q = url.searchParams;
+      // Newest first, which is what every id rule below assumes.
       let items = this.store.getNotifications();
-      const maxId = url.searchParams.get('max_id');
-      if (maxId) {
-        const i = items.findIndex(n => n.id === maxId);
-        if (i >= 0) items = items.slice(i + 1);
+
+      // Which KINDS. A client that asks for mentions and is handed favourites
+      // and boosts renders them as mentions — Phanpy's Mentions column did
+      // exactly that, and re-pilled on every poll. Both spellings: clients send
+      // `types[]=mention` and some send bare `types=mention`.
+      const listParam = (name) => {
+        const all = [...q.getAll(`${name}[]`), ...q.getAll(name)]
+          .flatMap((v) => String(v).split(',')).map((v) => v.trim()).filter(Boolean);
+        return all.length ? new Set(all) : null;
+      };
+      const want = listParam('types');
+      const skip = listParam('exclude_types');
+      // Mastodon spells the type with an underscore; ours is stored with a
+      // hyphen, and notification() translates on the way out — so match on what
+      // the client would have been given, not on what is on disk.
+      const shown = (n) => this.notificationType(n.type);
+      if (want) items = items.filter((n) => want.has(shown(n)));
+      if (skip) items = items.filter((n) => !skip.has(shown(n)));
+
+      // Which SLICE. `max_id` walks backwards into history; `since_id` and
+      // `min_id` both mean "newer than this", which is how a client asks
+      // "anything since I last looked?". Ignoring them meant every poll
+      // returned the whole list, so the client always saw unread items and the
+      // bell never went out.
+      const cut = (id, keepNewer) => {
+        const i = items.findIndex((n) => n.id === id);
+        if (i < 0) return;
+        items = keepNewer ? items.slice(0, i) : items.slice(i + 1);
+      };
+      const maxId = q.get('max_id');
+      if (maxId) cut(maxId, false);
+      const sinceId = q.get('since_id') || q.get('min_id');
+      if (sinceId) cut(sinceId, true);
+      // min_id asks for the ones IMMEDIATELY newer, i.e. the oldest end of
+      // what is newer; since_id asks for the newest. Only the window differs.
+      const page = q.get('min_id') && !q.get('since_id')
+        ? items.slice(Math.max(0, items.length - limit))
+        : items.slice(0, limit);
+
+      // A client pages by following these rather than by guessing ids.
+      if (page.length) {
+        const base = `${this.scheme || (req.socket?.encrypted ? 'https' : 'http')}://${req.headers.host}${pathname}`;
+        const link = (params) => {
+          const u = new URL(base);
+          for (const [k, v] of q) if (k !== 'max_id' && k !== 'since_id' && k !== 'min_id') u.searchParams.append(k, v);
+          for (const [k, v] of Object.entries(params)) u.searchParams.set(k, v);
+          return u.href;
+        };
+        return send(200, page.map((n) => this.notification(n)), {
+          link: `<${link({ max_id: page[page.length - 1].id })}>; rel="next", `
+            + `<${link({ min_id: page[0].id })}>; rel="prev"`,
+        });
       }
-      return send(200, items.slice(0, limit).map(n => this.notification(n)));
+      return send(200, []);
     }
 
     if (pathname === '/api/v1/markers') {
@@ -1547,6 +1939,10 @@ export class MastoApi {
     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 (!this.webPush) return send(422, { error: 'this instance does not send web push' });
       if (req.method === 'GET') {
         const sub = this.push.get(token);
         return sub ? send(200, this.push.json(token, sub)) : send(404, { error: 'Record not found' });
@@ -1673,7 +2069,7 @@ export class MastoApi {
       const slug = new Date().toISOString().slice(0, 10) + '-' + crypto.randomBytes(4).toString('hex') + '.' + ext;
       const mediaUrl = this.urls.media + slug;
       await this.agent.publisher.ensureMediaContainer();
-      await this.agent.remote.put(mediaUrl, file.data, mediaType);
+      await podMedia.write(this.agent.remote, mediaUrl, file.data, mediaType);
       const entry = { url: mediaUrl, mediaType, description: fields.description || '' };
       const id = this.store.idFor(mediaUrl);
       this.store.setMedia(id, entry);
@@ -1707,7 +2103,12 @@ function instanceConfig() {
       image_size_limit: 10 * 1024 * 1024, video_size_limit: 40 * 1024 * 1024,
       image_matrix_limit: 16777216, video_matrix_limit: 2304000,
     },
-    polls: { max_options: 0 },
+    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 },
   };
 }
@@ -1865,7 +2266,17 @@ function readBody(req) {
       const ct = String(req.headers['content-type'] || '');
       try {
         if (ct.includes('application/json')) return resolve(data ? JSON.parse(data) : {});
-        resolve(Object.fromEntries(new URLSearchParams(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);