source: Klonkt/src/routes/activitypub.js@ 383e897

/**
 * ActivityPub — public endpoints (Phase 1: discover + fetch).
 *
 *   GET /.well-known/webfinger?resource=acct:<slug>@<host>
 *   GET /ap/users/:slug            actor (content-negotiated: AP-JSON vs redirect to HTML profile)
 *   GET /ap/users/:slug/outbox     OrderedCollection of Create(Note)
 *   GET /ap/users/:slug/followers  count-only OrderedCollection
 *   GET /ap/users/:slug/featured   pinned posts (Mastodon "Featured" tab)
 *   GET /ap/notes/:id              a single Note
 *   POST /ap/users/:slug/inbox, /ap/inbox  → 202 (Follow/Accept + signature verify: next step)
 *
 * Mounted before resolveSite; resolves the site by slug itself.
 */
import express from 'express';
import { readFileSync } from 'fs';
import db from '../config/database.js';
import AP from '../services/ActivityPubService.js';
import { apReadLimiter, apInboxLimiter } from '../middleware/rate-limit.js';
import { apEnabled } from '../services/SettingsService.js';
import OAuth from '../services/OAuthService.js';
import * as Guardianship from '../services/guardianship/index.js';
import { getPrimarySite } from '../middleware/site.js';
import multer from 'multer';
import path from 'path';
import fs from 'fs';
import { randomUUID } from 'crypto';
import { mediaDir } from '../config/paths.js';

const router = express.Router();
// The whole fediverse layer can be turned off (solo "no federation" mode):
// then /ap/*, WebFinger and NodeInfo are simply gone — the site is undiscoverable
// and unfederatable. CRITICAL: this router is mounted at root (app.use(apRoutes)), so a
// blanket res.status(404) here ran for EVERY request and 404'd the whole site when AP was
// off. Use next('router') to SKIP this router entirely and let the normal routes handle it
// (the /ap/* paths then fall through to the app's normal 404, which is correct).
router.use((req, res, next) => { if (!apEnabled()) return next('router'); next(); });
// Generous per-IP baseline over the AP-READ paths. The inbox POST gets an
// additional, tighter cap inline (it triggers outbound fetches).
//
// PADGEBONDEN, niet router.use kaal (Barts 429-jacht, 9-8): deze router is op
// de ROOT gemonteerd, dus een kale use() draait voor ELKE request van de hele
// site -- pagina's, media, avatars, de PWA. De guardian-PWA met honderd
// ward-avatars leegde zo in seconden een emmer die "voor /ap-reads" heette,
// en hield hem leeg: vandaar een Too many requests die niet overging. De
// kijkbuis die dit vond: een lege /ap-teller naast remaining: 0.
router.use(['/ap', '/.well-known', '/nodeinfo'], apReadLimiter);
let _ver = '1.0.0';
try { _ver = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url))).version || _ver; } catch { /* keep default */ }

const baseUrl = (req) => (process.env.PUBLIC_BASE_URL || `${req.protocol}://${req.get('host')}`).replace(/\/+$/, '');
const hostOf = (req) => { try { return new URL(baseUrl(req)).host; } catch { return req.get('host'); } };
const publicSite = (slug) => db.prepare('SELECT * FROM sites WHERE slug = ? AND (is_public IS NULL OR is_public = 1)').get(slug);
// The primary site, via the one source of truth in middleware/site.js — which
// falls back to the oldest site when nothing carries the is_primary flag. This
// route used to keep its own is_primary-only copy, so a fresh instance whose
// site was never flagged served its HTML at / (that resolver falls back) while
// WebFinger and the actor route insisted it had no primary at all.
const primarySlug = () => { const s = getPrimarySite(); return s && s.slug; };
// A hostname as a human types it and as DNS stores it are the same host:
// `🩵.is.wildenvrij.nl` IS `xn--zz9h.is.wildenvrij.nl`. WHATWG URL does the IDNA,
// so compare the ASCII form and never the bytes the client happened to send.
const asciiHost = (h) => {
  try { return new URL(`https://${h}`).host.toLowerCase(); } catch { return String(h).trim().toLowerCase(); }
};

// ── host-meta ─────────────────────────────────────────────────────
// De klassieke eerste stap van WebFinger (RFC 6415): een client die het
// webfinger-pad niet wil raden, vraagt hier de sjabloon op. Mastodon serveert
// dit ook, en een client die ermee begint kreeg bij ons een 404 en gaf het dan
// op -- terwijl de webfinger eronder gewoon werkte.
//
// Twee vormen, want beide worden in het wild gevraagd: XRD (het origineel) en
// JRD (de JSON-variant, RFC 6415 §3).
const lrddSjabloon = (req) => `${baseUrl(req)}/.well-known/webfinger?resource={uri}`;

router.get('/.well-known/host-meta', (req, res) => {
  res.type('application/xrd+xml; charset=utf-8');
  res.set('Cache-Control', 'public, max-age=86400');
  res.send(`<?xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
  <Link rel="lrdd" template="${lrddSjabloon(req)}"/>
</XRD>`);
});

router.get('/.well-known/host-meta.json', (req, res) => {
  res.type('application/jrd+json; charset=utf-8');
  res.set('Cache-Control', 'public, max-age=86400');
  res.send(JSON.stringify({ links: [{ rel: 'lrdd', template: lrddSjabloon(req) }] }));
});

// ── WebFinger ─────────────────────────────────────────────────────
/**
 * De `resource` uitpakken tot de gebruiker die bedoeld wordt.
 *
 * RFC 7033 schrijft een URI voor, en `acct:` is de nette vorm -- maar in het
 * wild komen er vier spellingen langs, en drie daarvan wezen we af met een 400
 * terwijl we prima wisten wie er bedoeld werd:
 *
 *   acct:naam@host      de nette vorm (Mastodon stuurt altijd deze)
 *   naam@host           zonder schema
 *   @naam@host          met het apenstaartje dat mensen intypen
 *
 * Coulant zijn kost hier niets: het antwoord noemt altijd de canonieke
 * `acct:`-vorm terug, dus een slordige vraag levert geen slordig antwoord.
 *
 * De ACTOR-URI als resource (die Mastodon ook accepteert) hoort hier NIET bij,
 * bewust: test/webfinger-bare-host.test.js legt vast dat die een 400 geeft.
 * Dat is een uitgesproken keuze van eerder en geen vergetelheid, dus die draai
 * ik niet om als bijvangst van een coulance-fix.
 */
function webfingerGebruiker(resource) {
  const r = String(resource || '').trim();
  if (!r) return null;
  const acct = r.match(/^(?:acct:)?@?([^@/]+)@(.+)$/i);
  return acct ? acct[1] : null;
}

router.get('/.well-known/webfinger', (req, res) => {
  const user = webfingerGebruiker(req.query.resource);
  if (!user) return res.status(400).type('text/plain').send('bad resource');
  let site = publicSite(user);
  // `acct:<host>@<host>` asks for this server's primary actor — the convention
  // Shaer's Handle relies on so a Ward is reachable without knowing anyone's
  // slug. Typing `🩵.is.wildenvrij.nl`, pasting `https://🩵.is.wildenvrij.nl`
  // (which the client's URL parser silently punycodes) and sending the xn--
  // form by hand are three spellings of one address; all arrive here with the
  // host sitting in the user position, and all must find the same actor.
  if (!site && asciiHost(user) === asciiHost(hostOf(req))) {
    const slug = primarySlug();
    if (slug) site = publicSite(slug);
  }
  if (!site) return res.status(404).end();
  res.type('application/jrd+json; charset=utf-8');
  res.set('Cache-Control', 'public, max-age=300');
  const actorUri = AP.actorId(baseUrl(req), site.slug);
  const profileUrl = baseUrl(req) + (site.slug === primarySlug() ? '/' : `/user/${encodeURIComponent(site.slug)}`);
  res.send(JSON.stringify({
    subject: `acct:${site.slug}@${hostOf(req)}`,
    aliases: [actorUri, profileUrl],
    links: [
      { rel: 'self', type: 'application/activity+json', href: actorUri },
      { rel: 'http://webfinger.net/rel/profile-page', type: 'text/html', href: profileUrl },
    ],
  }));
});

// ── Actor ─────────────────────────────────────────────────────────
router.get('/ap/users/:slug', (req, res) => {
  const site = publicSite(req.params.slug);
  if (!site) return res.status(404).end();
  if (!AP.apWants(req)) {
    // A browser hit the AP actor URL → send them to the human profile.
    const human = site.slug === primarySlug() ? '/' : `/user/${encodeURIComponent(site.slug)}`;
    return res.redirect(302, baseUrl(req) + human);
  }
  site.primary_slug = primarySlug();
  AP.sendAP(res, AP.buildActor(baseUrl(req), site));
});

// ── Outbox ────────────────────────────────────────────────────────
router.get('/ap/users/:slug/outbox', async (req, res) => {
  const site = publicSite(req.params.slug);
  if (!site) return res.status(404).end();
  // Authorized fetch (30-7): who is asking decides what they see.
  //  - the owner's own app (bearer) and a verified accepted follower or
  //    guardian get the friends-only history too, so a NEW friend's backfill
  //    brings the past along (Robins besluit: vrienden krijgen de
  //    geschiedenis mee);
  //  - a verified caller this instance BLOCKS gets an EMPTY collection, not
  //    even the public set: a block is a closed door, and a signed fetch is
  //    the caller knocking with their name on it;
  //  - everyone else gets the public collection, exactly as before.
  const bearer = OAuth.verifyBearer(req.headers.authorization);
  let verifiedActor = null;
  if (!bearer && req.headers['signature']) {
    const verified = await AP.verifyRequest(req).catch(() => null);
    verifiedActor = verified && verified.id;
  }
  const audience = AP.outboxAudience(req.params.slug, {
    bearerSlug: bearer ? bearer.site.slug : null,
    verifiedActor,
  });
  if (audience === 'blocked') {
    return AP.sendAP(res, AP.buildOutbox(baseUrl(req), site, []), 'private, no-store');
  }
  const fanClause = audience === 'friend' ? '' : "AND (fan_only IS NULL OR fan_only = 0)";
  const posts = db.prepare(
    `SELECT id, slug, title, content, cover_image_url, cover_video_url, nsfw, content_warning, c2s_attachments, quote_json, embed_json, published_at, created_at
     FROM posts WHERE site_id = ? AND status = 'published' ${fanClause}
     ORDER BY COALESCE(published_at, created_at) DESC LIMIT 20`
  ).all(site.id);
  // De tracks gaan mee voor iedereen die de deur door mag; de blocked-tak
  // hierboven levert bewust een outbox ZONDER posts en zonder tracks.
  const ob = AP.buildOutbox(baseUrl(req), site, posts, AP.siteOpenTracks(site.id));
  if (audience === 'friend') {
    // The owner's app builds its feed from this leg, and every note here is
    // by the site itself, so give it a byline too (avatar + name): de
    // ingesloten actor in attributedTo, net als de tijdlijn.
    const me = AP.selfAuthor(baseUrl(req), site);
    // De kaart op je eigen post (shaer-k3f): dezelfde quote/preview die de
    // tijdlijn voor andermans posts draagt, uit de snapshots die
    // deliverCreate bij het publiceren opsloeg. Op note-id gekoppeld, want
    // buildOutbox sorteert en mengt tracks erdoorheen. De embed alleen voor de
    // BEARER en langs zijn eigen poort: een remote vriend krijgt hem niet
    // (diens server resolvet en gate zelf bij ontvangst), en een ward zonder
    // open embeds-poort krijgt hem hier net zo min als in de tijdlijn.
    const byNote = new Map(posts.map((p) => [AP.noteId(baseUrl(req), p.id), p]));
    const bearerEmbeds = bearer ? (() => {
      const isWard = (() => { try { return Guardianship.listGuardians(bearer.site.slug).length > 0; } catch { return false; } })();
      return Guardianship.externalEmbedsAllowed(bearer.site.external_embeds, isWard)
        ? { playback: Guardianship.externalPlaybackAllowed(bearer.site.external_playback, isWard) } : null;
    })() : null;
    for (const it of ob.orderedItems) {
      if (it && it.object && typeof it.object === 'object') {
        it.object.attributedTo = AP.actorObject(
          (typeof it.object.attributedTo === 'string' ? it.object.attributedTo : undefined) || AP.actorId(baseUrl(req), site.slug),
          me,
        );
        const row = byNote.get(it.object.id);
        if (row) {
          it.object.quote = AP.quoteObject(row.quote_json);
          if (bearerEmbeds) {
            it.object.preview = AP.previewObject(row.embed_json, { playback: bearerEmbeds.playback });
          }
        }
      }
    }
  }
  AP.sendAP(res, ob, audience === 'friend' ? 'private, no-store' : undefined);
});

// ── Follow-QR (Robins verzoek, 31-7) ──────────────────────────────
// The QR carries an HTTPS url, not the share: scheme: camera apps (Google
// Lens voorop) treat unknown schemes as plain text and only offer to OPEN
// https links (Robins melding, 31-7). The url lands on the interstitial
// below, whose one big button fires the share: scheme — from a browser the
// custom scheme DOES work (BROWSABLE intent-filter; Safari prompts).
// Public on purpose: it encodes only the public handle, and the app's plain
// image loaders carry no bearer.
router.get('/ap/users/:slug/follow-qr.png', async (req, res) => {
  const site = db.prepare('SELECT slug FROM sites WHERE slug = ?').get(req.params.slug);
  if (!site) return res.status(404).end();
  try {
    const { default: QRCode } = await import('qrcode');
    const png = await QRCode.toBuffer(`${baseUrl(req)}/ap/users/${encodeURIComponent(site.slug)}/follow`, { width: 600, margin: 1 });
    res.set('Content-Type', 'image/png');
    res.set('Cache-Control', 'public, max-age=86400');
    res.send(png);
  } catch (e) {
    console.warn('[AP] follow-qr failed:', e && e.message);
    res.status(500).end();
  }
});

// The interstitial the QR opens: one big button into Shaer, and the handle
// in plain sight for whoever has no Shaer (yet).
router.get('/ap/users/:slug/follow', (req, res) => {
  const site = db.prepare('SELECT slug, title FROM sites WHERE slug = ?').get(req.params.slug);
  if (!site) return res.status(404).end();
  const host = new URL(baseUrl(req)).host;
  const esc = (t) => String(t).replace(/[<>&"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;' }[c]));
  const handle = `@${site.slug}@${host}`;
  const name = esc(site.title || site.slug);
  res.set('Cache-Control', 'public, max-age=3600');
  res.send(`<!doctype html><html lang="en"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Follow ${name}</title>
<style>
  body { font-family: system-ui, sans-serif; margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
         background: linear-gradient(160deg, #5A32E6, #2a1a5e); color: #fff; text-align: center; }
  main { padding: 32px; max-width: 420px; }
  h1 { font-size: 1.5rem; margin: 0 0 .4rem; }
  .handle { opacity: .85; font-family: ui-monospace, monospace; word-break: break-all; }
  a.go { display: block; margin: 28px auto 14px; padding: 16px 28px; border-radius: 999px; background: #fff; color: #2a1a5e;
         font-weight: 700; font-size: 1.15rem; text-decoration: none; }
  p.small { font-size: .85rem; opacity: .75; line-height: 1.5; }
</style></head><body><main>
  <h1>Follow ${name}</h1>
  <div class="handle">${esc(handle)}</div>
  <a class="go" href="share:social/follow/AP/${esc(handle)}">Open in Shaer</a>
  <p class="small">No Shaer? Any fediverse app can follow ${esc(handle)}.</p>
</main></body></html>`);
});

/** De byline-gegevens uit een tijdlijnrij, langs de emoji-poort. */
function authorInfoFrom(r, prefix, gates) {
  const info = {
    name: r[`${prefix}name`] || undefined, handle: r[`${prefix}handle`] || undefined,
    icon: r[`${prefix}icon`] || undefined, url: r[`${prefix}url`] || undefined,
    emojis: (() => { try { return r[`${prefix}emoji_json`] ? JSON.parse(r[`${prefix}emoji_json`]) : undefined; } catch { return undefined; } })(),
  };
  return (info.name || info.handle || info.icon) ? gates.gateAuthor(info) : undefined;
}

// ── Een tijdlijnpost als AS2-item: EEN beschrijving van de kaartvorm ──
//
// Zelfde reden als messageItem hieronder: de volledige lezing en de
// verschil-lezing bouwen dezelfde kaart, en twee beschrijvingen lopen uit de
// pas zonder dat iemand het merkt.
function timelineItem(t, { p, reactions }) {
  const authorInfo = (r, prefix) => authorInfoFrom(r, prefix, p);
  const {
    embedsAllowed, playbackAllowed, imagesAllowed, musicAllowed, quotesAllowed, emojiAllowed,
  } = p;
  const reacties = reactions || new Map();
    const auteur = authorInfo(t, 'author_');
    const booster = authorInfo(t, 'reblog_');
    const boosterUri = t.reblog_url || t.reblog_handle || undefined;
    return {
    id: `${t.id}#create`,
    // EEN BOOST IS EEN ANNOUNCE (shaer-nmw): een Create met een
    // zijkanaal-property was onze uitvinding; de wrapper is de standaard, en
    // elke AP-client leest hem al.
    type: booster ? 'Announce' : 'Create',
    actor: booster ? (AP.actorObject(boosterUri || t.author_uri, booster)) : t.author_uri,
    published: t.published || t.created_at || undefined,
    object: {
      id: t.id,
      type: 'Note',
      // AS2 staat een INGESLOTEN actor toe; dan heeft elke client de byline,
      // niet alleen de onze (shaer-nmw).
      attributedTo: AP.actorObject(t.author_uri, auteur),
      content: t.content,
      url: t.url || undefined,
      published: t.published || t.created_at || undefined,
      sensitive: !!t.nsfw,
      summary: t.cw || undefined,
      // Friends' media travels along (media_json → AS2 attachment), so the
      // client renders their images/audio like own outbox posts.
      attachment: AP.gateAttachments(AP.timelineAttachments(t.media_json), { images: imagesAllowed, audio: musicAllowed }),
      // The note's preserved tags, so the client can render them: FEP-9098
      // Emoji tags (:shortcode: → image) and FEP-e232 Link tags (quotes /
      // inline object references). Combined into one `tag` array; omitted
      // when the note has neither.
      tag: (() => {
        const tags = [...(emojiAllowed ? (AP.timelineEmojis(t.emoji_json) || []) : []), ...(AP.timelineObjectLinks(t.link_json) || [])];
        return tags.length ? tags : undefined;
      })(),
      // Whether THIS account already liked/boosted the note, so the app's
      // detail-view buttons show the current state (and can toggle/undo).
      'shaer:liked': !!(reacties.get(t.id) || {}).liked,
      'shaer:boosted': !!(reacties.get(t.id) || {}).boosted,
      // FEP-044f: de geciteerde post als object, zodat de client een kaart
      // rendert in plaats van een kale link. AS2 preview is diezelfde kaart
      // voor een EXTERNE link: thumbnail, nooit de iframe van de aanbieder.
      // Allebei weg zodra hun poort dicht staat; de speler in preview hangt
      // aan de playback-poort.
      quote: quotesAllowed ? AP.quoteObject(t.quote_json) : undefined,
      preview: embedsAllowed ? AP.previewObject(t.embed_json, { playback: playbackAllowed }) : undefined,
    },
  };
}

/** Een inkomend antwoord op je eigen post als AS2-item. */
function replyItem(m, { base, me, myHandle, p }) {
  return {
    id: `${m.object_uri}#create`,
    type: 'Create',
    actor: m.actor_uri,
    published: AP.isoStamp(m.published || m.created_at),
    object: {
      id: m.object_uri,
      type: 'Note',
      attributedTo: AP.actorObject(m.actor_uri, (m.actor_name || m.actor_handle || m.actor_icon) ? p.gateAuthor({
        name: m.actor_name || undefined, handle: m.actor_handle || undefined,
        icon: m.actor_icon || undefined, url: m.actor_url || undefined,
        emojis: (() => { try { return m.actor_emoji_json ? JSON.parse(m.actor_emoji_json) : undefined; } catch { return undefined; } })(),
      }) : undefined),
      content: AP.stripLeadingMentions(m.content),
      inReplyTo: m.parent_uri || `${base}/ap/notes/${m.post_id}`,
      published: AP.isoStamp(m.published || m.created_at),
      to: [me],
      tag: [{ type: 'Mention', href: me, name: myHandle }, ...(AP.timelineEmojis(m.emoji_json) || [])],
      attachment: AP.timelineAttachments(m.media_json),
      quote: p.quotesAllowed ? AP.quoteObject(m.quote_json) : undefined,
      preview: p.embedsAllowed ? AP.previewObject(m.embed_json, { playback: p.playbackAllowed }) : undefined,
    },
  };
}

/** Wat deze lezer mag (FEP-633c 5.6), op EEN plek.
 *
 *  De verschil-lezing draagt ze net zo goed: een antwoord zonder rechten zou
 *  de client naar zijn standaard laten terugvallen, en die standaard is
 *  'alles mag'. Dan zet een gesloten poort zichzelf stil open. Dezelfde reden
 *  waarom een 304 de caps met rust laat.
 */
function capabilitiesOf(p, gate) {
  return {
      'shaer:externalEmbeds': p.embedsAllowed,
      'shaer:externalPlayback': p.playbackAllowed,
      // Leaving the app is the same decision as playing inside it: with the
      // gate shut a link is shown but not followed, so the door is closed too
      // and not just the picture over it.
      'shaer:externalLinks': p.playbackAllowed,
      // De rest van de familie (8-8): de app hoort VOORAF te weten wat hij mag
      // aanbieden in plaats van het bij de eerste weigering te ontdekken. De
      // (+) kaart leest shaer:compose al (Barts gate); de rest is er voor de
      // schermen die nog komen. Serveren wat waar is kost hier niets.
      'shaer:compose': p.composeAllowed,
      'shaer:replies': p.repliesAllowed,
      'shaer:messages': p.messagesAllowed,
      'shaer:images': p.imagesAllowed,
      'shaer:music': p.musicAllowed,
      'shaer:quoteCards': p.quotesAllowed,
      'shaer:customEmoji': p.emojiAllowed,
      'shaer:externalThreads': p.threadsAllowed,
      'shaer:following': p.followingAllowed,
      // Stond in de catalogus mét kolom, en ontbrak hier: de guardian zag de
      // poort in zijn paneel en de app van het kind heeft er nooit van gehoord.
      // Gevonden door de pariteitstest, niet door iemand die het toevallig zag.
      'shaer:accountMove': gate('gate_account_move'),
    };
}

// ── De poorten van een lezer, op EEN plek (FEP-633c) ─────────────
//
// De inbox-lezing rekende ze inline uit. Nu er meer lezingen zijn die
// dezelfde poorten moeten eerbiedigen (de gesprekken, de geschiedenis), zou
// dat evenveel kopieen worden -- en een poort die op een van die plekken
// vergeten wordt, levert stil iets uit dat dicht hoorde te staan.
function gatesFor(site) {
  const isWard = (() => { try { return Guardianship.listGuardians(site.slug).length > 0; } catch { return false; } })();
  const embeds = Guardianship.externalEmbedsAllowed(site.external_embeds, isWard);
  const gate = (col) => Guardianship.wardGateAllowed(site[col], isWard);
  const emoji = gate('gate_custom_emoji');
  return {
    isWard,
    embedsAllowed: embeds,
    playbackAllowed: embeds && Guardianship.externalPlaybackAllowed(site.external_playback, isWard),
    imagesAllowed: gate('gate_images'),
    musicAllowed: gate('gate_music'),
    quotesAllowed: gate('gate_quote_cards'),
    emojiAllowed: emoji,
    messagesAllowed: gate('gate_messages'),
    composeAllowed: gate('gate_compose'),
    repliesAllowed: gate('gate_replies'),
    threadsAllowed: gate('external_threads'),
    followingAllowed: gate('gate_following'),
    // Emoji dicht raakt ook de bylines: de plaatjes in een naam komen net zo
    // goed van een vreemde server. De naam zelf blijft, met :shortcode: als tekst.
    gateAuthor: (a) => (a && !emoji ? { ...a, emojis: undefined } : a),
  };
}

/** De naam waaronder deze lezer zichzelf herkent in een Mention. */
function ownHandle(base, slug) {
  try { return `@${slug}@${new URL(base).host}`; } catch { return `@${slug}`; }
}

// ── Een bericht als AS2-item: EEN beschrijving van de kaartvorm ──
//
// Gebruikt door de inbox-lezing en door de gesprekslezingen. Twee keer
// opschrijven is twee vormen die uit de pas kunnen lopen, en dat merk je pas
// als een kaart ergens anders rendert dan waar je keek.
function messageItem(m, { base, me, myHandle, p }) {
  return {
    id: `${m.object_uri}#create`,
    type: 'Create',
    actor: m.actor_uri,
    published: AP.isoStamp(m.published || m.created_at),
    object: {
      id: m.object_uri,
      type: 'Note',
      attributedTo: AP.actorObject(m.actor_uri, (m.actor_name || m.actor_handle || m.actor_icon) ? p.gateAuthor({
        name: m.actor_name || undefined, handle: m.actor_handle || undefined,
        icon: m.actor_icon || undefined, url: m.actor_url || undefined,
        emojis: (() => { try { return m.actor_emoji_json ? JSON.parse(m.actor_emoji_json) : undefined; } catch { return undefined; } })(),
      }) : undefined),
      content: AP.stripLeadingMentions(m.content),
      url: m.note_url || undefined,
      published: AP.isoStamp(m.published || m.created_at),
      // Addressed to us and to nobody we know of: the other recipients of a
      // note to several people are not ours to see, so we serve what we know.
      to: [me],
      // The Mention is how the client recognises itself as the addressee and
      // groups the note into a conversation. No FEP-e232 link tags here: a
      // mention row keeps the resolved quote, not the raw tags.
      tag: [{ type: 'Mention', href: me, name: myHandle }, ...(p.emojiAllowed ? (AP.timelineEmojis(m.emoji_json) || []) : [])],
      attachment: AP.gateAttachments(AP.timelineAttachments(m.media_json), { images: p.imagesAllowed, audio: p.musicAllowed }),
      // FEP-633c: what kind of message this is. The wave is a gentle nudge from
      // a guardian; the help request is the buoy. Both render differently.
      'shaer:wave': m.wave ? true : undefined,
      'shaer:helpRequest': m.help_request ? true : undefined,
      quote: p.quotesAllowed ? AP.quoteObject(m.quote_json) : undefined,
      preview: p.embedsAllowed ? AP.previewObject(m.embed_json, { playback: p.playbackAllowed }) : undefined,
    },
  };
}

/** Een eigen verzonden note als AS2-item, zelfde vorm als de inbox-leg. */
function sentItem(n, { me, mine }) {
  return {
    id: `${n.id}#create`,
    type: 'Create',
    actor: me,
    published: n.published,
    // The leading mention anchor is addressing, not prose (the DM leg strips
    // it the same way); the Mention tags built from the full content stay.
    object: {
      ...n, content: AP.stripLeadingMentions(n.content),
      attributedTo: AP.actorObject(typeof n.attributedTo === 'string' ? n.attributedTo : me, mine),
    },
  };
}

// ── Gesprekken: eerst wie, dan pas wat (shaer-frontend-yso) ──────
//
// Twee lezingen naast de bestaande inbox-lezing, niet in de plaats ervan: de
// apps in het veld lezen die nog. /conversations geeft EEN rij per tegenpartij
// -- compleet van vorm, dus de avatarhemel kan niemand kwijtraken doordat een
// ander druk was -- en /messages geeft een gesprek met een cursor, zodat een
// 'load more' eerlijk kan verschijnen in plaats van dat de geschiedenis stil
// ophoudt.
//
// Beide lopen langs dezelfde poorten als de inbox-lezing (gatesFor) en
// dezelfde kaartvorm (messageItem/sentItem). Messages dicht sluit ook
// hier vreemden en vrienden, maar nooit het guardian-kanaal en nooit de boei.
function conversationItems(req, auth, refs) {
  const base = baseUrl(req);
  const P = gatesFor(auth.site);
  const me = AP.actorId(base, auth.site.slug);
  const ctx = { base, me, myHandle: ownHandle(base, auth.site.slug), p: P };
  const mine = AP.selfAuthor(base, auth.site);
  const guardianUris = (() => { try { return new Set(Guardianship.listGuardians(auth.site.slug).map((g) => g.other_uri)); } catch { return new Set(); } })();

  const incoming = new Map(AP.messageRowsByUri(auth.site.slug, refs.filter((r) => r.direction === 'in').map((r) => r.ref))
    .map((m) => [m.object_uri, m]));
  // PAREN, geen losse lijst: een kop levert niet altijd een item op (dichte
  // poort, ontbrekende rij), en dan zou de aanroeper op index koppelen en de
  // telling aan het verkeerde gesprek hangen. Stil, en pas te zien als iemand
  // een badge op de verkeerde naam ziet staan.
  const pairs = [];
  for (const r of refs) {
    if (r.direction === 'in') {
      const m = incoming.get(r.ref);
      if (!m) continue;
      if (!(P.messagesAllowed || m.help_request || guardianUris.has(m.actor_uri))) continue;
      pairs.push({ head: r, item: messageItem(m, ctx) });
    } else {
      const n = AP.getOutboxNote(base, r.ref);
      // Je eigen woorden blijven van jou: een dichte messages-poort verbergt
      // niet wat je zelf gezegd hebt.
      if (n) pairs.push({ head: r, item: sentItem(n, { me, mine }) });
    }
  }
  return pairs;
}

router.get('/ap/users/:slug/conversations', (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  if (!auth || auth.site.slug !== req.params.slug) return res.status(403).end();
  const heads = AP.conversationHeads(auth.site.slug);
  const pairs = conversationItems(req, auth, heads);
  const items = pairs.map((x) => x.item);
  // Ongelezen per gesprek (shaer-frontend-3tx): een COUNT, geen bijgehouden
  // getal. Hij hangt aan het NIEUWSTE kopje van elke persoon -- er kunnen er
  // twee zijn (zie conversationHeads) en het aantal hoort bij het gesprek, niet
  // bij een bericht.
  //
  // AS2 heeft geen term voor ongelezen; dit is per-lezer-interactiestatus,
  // dezelfde categorie als shaer:liked. Niet in totalItems persen: dat betekent
  // 'hoeveel er zijn' en niet 'hoeveel jij nog niet zag'.
  const ongelezen = AP.unreadPerConversation(auth.site.slug, {
    messagesAllowed: P.messagesAllowed,
    guardians: (() => { try { return new Set(Guardianship.listGuardians(auth.site.slug).map((g) => g.other_uri)); } catch { return new Set(); } })(),
  });
  const gezien = new Set();
  for (const { head, item } of pairs) {
    if (gezien.has(head.other)) continue;
    gezien.add(head.other);
    const u = ongelezen.get(head.other);
    if (!u) continue;
    item.object['shaer:unread'] = u.n;
    // Een zwaai is geen aantal maar een zetje van een guardian: eigen teken.
    if (u.wave) item.object['shaer:unreadWave'] = true;
  }
  AP.sendAP(res, {
    '@context': AP.AP_CONTEXT,
    id: `${baseUrl(req)}/ap/users/${encodeURIComponent(auth.site.slug)}/conversations`,
    type: 'OrderedCollection',
    totalItems: items.length,
    orderedItems: items,
    'shaer:cursor': AP.feedCursor(auth.site.slug),
  }, 'private, no-store');
});

router.get('/ap/users/:slug/messages', (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  if (!auth || auth.site.slug !== req.params.slug) return res.status(403).end();
  const other = String(req.query.with || '');
  if (!/^https?:\/\//i.test(other)) return res.status(400).json({ error: 'with must be an actor URI' });
  const page = AP.conversationHistory(auth.site.slug, other, {
    before: req.query.before ? String(req.query.before) : null,
    limit: req.query.limit,
  });
  const items = conversationItems(req, auth, page.rows).map((x) => x.item);
  // De paginagrootte reist mee in next: vroeg je om 30, dan hoort de volgende
  // pagina er ook 30 te zijn. Zonder dit wordt hij stilletjes de standaard, en
  // dan klopt het ritme van een 'load more' niet meer met wat de gebruiker ziet.
  const size = req.query.limit ? `&limit=${encodeURIComponent(String(req.query.limit))}` : '';
  const self = `${baseUrl(req)}/ap/users/${encodeURIComponent(auth.site.slug)}/messages?with=${encodeURIComponent(other)}`;
  AP.sendAP(res, {
    '@context': AP.AP_CONTEXT,
    id: req.query.before ? `${self}${size}&before=${encodeURIComponent(String(req.query.before))}` : `${self}${size}`,
    type: 'OrderedCollectionPage',
    partOf: self,
    orderedItems: items,
    // De volgende pagina is de standaardvorm van 'er is meer' (AS2). Ontbreekt
    // hij, dan is het gesprek op -- en dat mag de client weten zonder gokken,
    // want anders kan een 'load more' niet eerlijk verschijnen.
    next: page.more && page.oldest ? `${self}${size}&before=${encodeURIComponent(page.oldest)}` : undefined,
  }, 'private, no-store');
});

// ── Long-poll (owner only, Robins verzoek 31-7) ───────────────────
// Hold the request until something push-worthy lands for this account, then
// answer 200 (news: re-read your feed) or 204 after ~25s (nothing: re-arm).
// The thread in the app stays live without interval polling.
router.get('/ap/users/:slug/inbox/wait', (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  if (!auth || auth.site.slug !== req.params.slug) return res.status(403).end();
  let settled = false;
  const done = (code) => {
    if (settled) return;
    settled = true;
    clearTimeout(timer);
    off();
    if (!res.headersSent) res.status(code).end();
  };
  const off = AP.onNews(auth.site.slug, () => done(200));
  const timer = setTimeout(() => done(204), 25_000);
  req.on('close', () => done(204));
});

// ── Blocked collection (owner only, AP §5.6) ──────────────────────
// The server blocklist is the source of truth for Shaer's "in Orbit":
// clients read it here instead of keeping their own state. Actor-kind
// blocks only (domain blocks are instance policy, not an Orbit member).
router.get('/ap/users/:slug/blocked', (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  if (!auth || auth.site.slug !== req.params.slug) return res.status(403).end();
  const base = baseUrl(req);
  const items = AP.listBlocks(auth.site.slug)
    .filter((b) => b.kind === 'actor')
    .map((b) => b.target);
  AP.sendAP(res, {
    '@context': AP.AP_CONTEXT,
    id: `${base}/ap/users/${auth.site.slug}/blocked`,
    type: 'OrderedCollection',
    totalItems: items.length,
    orderedItems: items,
  });
});

// ── Guardian queues (owner only, FEP-633c, shaer:queues) ──────────
// The dashboard collections the Shaer clients read: pending adoption offers,
// gated follows (empty in Klonkt for now) and the guardian's wards. Same
// contract as the Shaer test daemon.
function queueRoute(name, build) {
  router.get(`/ap/users/:slug/queues/${name}`, (req, res) => {
    const auth = OAuth.verifyBearer(req.headers.authorization);
    if (!auth || auth.site.slug !== req.params.slug) return res.status(403).end();
    const base = baseUrl(req);
    const me = `${base}/ap/users/${auth.site.slug}`;
    // 304 als er niets veranderde (Barts punt, 9-8). Zonder dit haalde een app
    // bij elke actie de hele lijst opnieuw op -- een hulpvraag afvinken vroeg de
    // honderd wards inclusief poorten terug.
    AP.sendMaybe304(req, res, { '@context': AP.AP_CONTEXT, ...build(`${me}/queues/${name}`, auth.site.slug, me) });
  });
}
queueRoute('offers', (id, slug, me) => Guardianship.offersCollection(id, slug, me));
queueRoute('follows', (id, slug, me) => Guardianship.followsCollection(id, slug, me));
// §5.3 turned around (shaer-p729): what this ward has asked to follow, still
// waiting on its guardians. Owner-only like the rest — who a child wants to
// follow is nobody else's business.
queueRoute('outgoing-follows', (id, slug, me) => Guardianship.outgoingFollowsCollection(id, slug, me));
queueRoute('wards', (id, slug) => Guardianship.wardsCollection(id, slug));
// Availability (FEP-633c 3.6.1) is never public: the ward reads its
// guardians' real states here and nowhere else.
queueRoute('guardians', (id, slug) => Guardianship.guardiansCollection(id, slug));

// ── Het logboek (FEP-633c §4.2, shaer:log) ────────────────────────────
// NAAST de wachtrijen en niet erin: alles onder shaer:queues wacht op een
// antwoord, dit is wat er al besloten is. Eigen pad, dezelfde eigenaar-only
// bearer. Het bestaat omdat een weigering anders alleen te merken viel doordat
// er iets uit een lijst verdween, en "het is weg" is geen reden.
router.get('/ap/users/:slug/log', (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  if (!auth || auth.site.slug !== req.params.slug) return res.status(403).end();
  const me = `${baseUrl(req)}/ap/users/${auth.site.slug}`;
  AP.sendAP(res, {
    '@context': AP.AP_CONTEXT,
    ...Guardianship.logCollection(`${me}/log`, auth.site.slug, (s) => AP.listGuardianEvents(s, 50)),
  }, 'private, no-store');
});
// De hulpvragen MET hun staat (5.2.1, shaer-lgo). De apps lazen ze uit de feed
// en wisten dus niet of er al iemand op af was -- daarom bleef een afgehandeld
// verzoek daar staan (Barts melding, 8-8).
queueRoute('help', (id, slug) => Guardianship.helpCollection(id, slug));

// ── Inbox read (owner only, AP C2S) ───────────────────────────────
// GET on the inbox is part of ActivityPub C2S: the account owner (a bearer
// scoped to this site) reads recent inbound posts (the timeline: accounts
// they follow) as Create(Note) items, so an app (Shaer) can build a unified
// feed. Anyone else gets 403; the inbox stays write-only for the public.
router.get('/ap/users/:slug/inbox', async (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  if (!auth || auth.site.slug !== req.params.slug) return res.status(403).end();
  const base = baseUrl(req);
  // Wachten is een UITBREIDING van deze lezing, geen tweede endpoint (shaer-n05).
  // Geef `since` (de shaer:cursor van je vorige antwoord) en `wait` mee, en het
  // antwoord blijft hangen tot er iets is of de tijd om is. Zonder die twee
  // gedraagt de route zich exact zoals altijd.
  //
  // Bewust hetzelfde antwoord in plaats van een "er is nieuws"-seintje: dan
  // hoeft er niets nieuws geparsed te worden, is er geen tweede beschrijving van
  // de kaartvorm die uit de pas kan lopen, en scheelt het de client een tweede
  // ronde.
  const wachtS = Math.min(Math.max(parseInt(req.query.wait, 10) || 0, 0), 50);
  if (req.query.since && wachtS > 0) {
    const afbreken = new AbortController();
    res.on('close', () => afbreken.abort());   // client hing op: niet doorgaan met wachten
    const uit = await AP.waitForFeedChange(auth.site.slug, {
      since: String(req.query.since), waitMs: wachtS * 1000, signal: afbreken.signal,
    });
    if (res.writableEnded || afbreken.signal.aborted) return undefined;
    // Niets veranderd? Dan een LEEG antwoord (Barts punt): de hele collectie
    // terugsturen terwijl er niets gebeurd is, is elke 25 seconden een tijdlijn
    // over de mobiele verbinding voor niets. Met 304 kost stilte niets en kost
    // nieuws nog steeds maar één rondje -- beter dan een apart seintje-endpoint,
    // dat voor nieuws twee rondjes nodig heeft.
    //
    // De '0'-uitzondering is geen franje. Ontbreekt ap_feed_state (een instance
    // die de migratie nog niet draaide), dan geeft feedCursor altijd '0' terug,
    // en zou een client hier eeuwig 304 krijgen en nooit meer inhoud zien. Bij
    // een lege merksteen sturen we dus gewoon de collectie.
    if (!uit.changed && uit.cursor !== '0') {
      res.set('Vary', 'Authorization');
      return res.status(304).end();
    }
  }
  // Gated feature (FEP-633c): may this account see EXTERNAL embeds? A ward's
  // world outside the fediverse is the guardians' call. The gate is applied
  // here, at serialisation: a blocked embed is never sent, because an embed the
  // client merely hides has still been delivered to the device.
  // De poorten van deze lezer (gatesFor): een plek waar ze berekend worden,
  // zodat de gesprekslezingen dezelfde stand eerbiedigen en niet hun eigen
  // kopie krijgen die kan gaan afwijken.
  const P = gatesFor(auth.site);
  const {
    embedsAllowed, playbackAllowed, imagesAllowed, musicAllowed, quotesAllowed,
    emojiAllowed, messagesAllowed, composeAllowed, repliesAllowed, threadsAllowed,
    followingAllowed, gateAuthor,
  } = P;
  // De rechten-lijst hieronder vraagt er nog een paar rechtstreeks op.
  const gate = (col) => Guardianship.wardGateAllowed(auth.site[col], P.isWard);
  // ── Standaardvormen naast het dialect (shaer-nmw) ────────────────
  //
  // Een lezer die AS2 kent heeft nu genoeg aan attributedTo (ingesloten
  // actor), quote (FEP-044f als object), preview (AS2 core) en de
  // Announce-wrapper. De shaer:-velden blijven er nog naast staan voor apps
  // in het veld; die gaan eruit als de clients om zijn.
  // Wie ik ben en wie mijn guardians zijn: allebei de lezingen hieronder
  // hebben ze nodig, dus een keer, hierboven.
  const me = AP.actorId(base, auth.site.slug);
  const myHandle = (() => { try { return `@${auth.site.slug}@${new URL(base).host}`; } catch { return `@${auth.site.slug}`; } })();
  const guardianUris = (() => { try { return new Set(Guardianship.listGuardians(auth.site.slug).map((g) => g.other_uri)); } catch { return new Set(); } })();
  // ── Alleen het VERSCHIL, als de client daarom vraagt (shaer-pq4) ──
  //
  // De wachtende lezing zei tot nu toe alleen DAT er iets veranderde, waarna de
  // client alles opnieuw las: vier legs van zestig met al hun media-, quote- en
  // embed-JSON, voor een enkel nieuw bericht. ap_feed_state houdt per object al
  // bij wat er wanneer veranderde, dus het verschil lag er klaar en werd alleen
  // nooit uitgedeeld (feedChangesSince had geen enkele aanroeper).
  //
  // OPT-IN met ?changes=1, en dat is geen franje: een app in het veld stuurt
  // `since` al mee en vervangt haar hele feed door wat er terugkomt. Zou
  // `since` opeens een verschil betekenen, dan wist die app zichzelf leeg.
  //
  // Het antwoord is een OrderedCollectionPage met partOf, want dat is wat het
  // IS -- een deel, geen collectie. Een generieke lezer ziet dat verschil ook.
  if (req.query.changes && req.query.since) {
    const veranderd = AP.feedChangesSince(auth.site.slug, String(req.query.since));
    const levend = veranderd.filter((c) => c.kind !== 'deleted').map((c) => c.object_uri);
    const tl = new Map(AP.timelineRowsByIds(auth.site.slug, levend).map((r) => [r.id, r]));
    const mn = new Map(AP.messageRowsByUri(auth.site.slug, levend.filter((u) => !tl.has(u))).map((r) => [r.object_uri, r]));
    const rp = new Map(AP.replyRowsByUri(auth.site.slug, levend.filter((u) => !tl.has(u) && !mn.has(u))).map((r) => [r.object_uri, r]));
    const reacties = AP.getReactionsFor(auth.site.slug, [...tl.keys()]);
    const ctx = { base, me, myHandle, p: P };
    const items = [];
    for (const c of veranderd) {
      if (c.kind === 'deleted') {
        // Een verwijdering reisde tot nu toe als AFWEZIGHEID mee: de volledige
        // lezing bevatte hem simpelweg niet meer. Die volledigheid is precies
        // wat hier wegvalt, dus zonder grafsteen zou een weggehaalde post voor
        // altijd in de app blijven staan -- en dat faalt stil. AS2 heeft er een
        // vorm voor, en de rij lag er al.
        items.push({ type: 'Delete', actor: me, object: { id: c.object_uri, type: 'Tombstone' } });
        continue;
      }
      const t = tl.get(c.object_uri);
      if (t) { items.push(timelineItem(t, { p: P, reactions: reacties })); continue; }
      const m = mn.get(c.object_uri);
      if (m) {
        if (messagesAllowed || m.help_request || guardianUris.has(m.actor_uri)) items.push(messageItem(m, ctx));
        continue;
      }
      const r = rp.get(c.object_uri);
      if (r) { items.push(replyItem(r, ctx)); continue; }
      const n = AP.getOutboxNote(base, c.object_uri);
      if (n) items.push(sentItem(n, { me, mine: AP.selfAuthor(base, auth.site) }));
    }
    return AP.sendAP(res, {
      '@context': AP.AP_CONTEXT,
      id: `${base}/ap/users/${encodeURIComponent(auth.site.slug)}/inbox?changes=1&since=${encodeURIComponent(String(req.query.since))}`,
      type: 'OrderedCollectionPage',
      partOf: `${base}/ap/users/${auth.site.slug}/inbox`,
      orderedItems: items,
      // De rechten gaan MEE. Zonder dit valt de client terug op zijn standaard,
      // en die standaard is 'alles mag' -- dan zet een gesloten poort zichzelf
      // stil open bij elke verschil-lezing. Dezelfde reden waarom een 304 de
      // caps met rust laat.
      'shaer:capabilities': capabilitiesOf(P, gate),
      'shaer:cursor': AP.feedCursor(auth.site.slug),
    }, 'private, no-store');
  }
  const rows = AP.getTimeline(auth.site.slug, 60);
  // Eén query voor de hele pagina (shaer-9e9 fase 2): shaer:liked komt uit de
  // tussentabel, de bron van waarheid, en niet meer uit de afgeleide kolom op
  // ap_timeline. Per rij vragen zou hier een N+1 opleveren.
  const reacties = AP.getReactionsFor(auth.site.slug, rows.map((t) => t.id));
  const posts = rows.map((t) => timelineItem(t, { p: P, reactions: reacties }));
  // The direct notes addressed to this account: a plain DM, a guardian's wave
  // (§5), a ward's 🛟 help request (§5.2.1). Those are messages, not posts, so
  // they are not in the timeline; without them the app's Berichten shows only
  // what you said yourself. Same shape as a post, so one parser handles both.
  // Messages dicht (shaer-3ow) sluit vreemden en vrienden, maar NOOIT het
  // guardian-kanaal: de zwaai en het gesprek na een hulpvraag zijn precies
  // het kanaal dat het kind veilig houdt, en een poort die dat afsnijdt
  // beschermt niemand. De hulpvraag zelf gaat aan de innamekant al altijd voor.
  const messageCtx = { base, me, myHandle, p: P };
  const messages = AP.getDirectMessages(auth.site.slug, 60)
    .filter((m) => messagesAllowed || m.help_request || guardianUris.has(m.actor_uri))
    .map((m) => messageItem(m, messageCtx));
  // Inbound REPLIES on your own posts: stored as interactions (the web's
  // comment machinery), never as mentions, so this read missed them and a
  // friend's reply arrived everywhere except in your app (Robins melding,
  // 30-7). Same shape as the other legs; media/quotes ride the stored JSON.
  const replies = AP.getReplyMessages(auth.site.slug, 60).map((m) => replyItem(m, messageCtx));
  // Your OWN sent notes (replies and direct messages, ap_outbox): without
  // them a reply existed everywhere except in your own app, Messages showed
  // half a conversation, and a retry ran into the duplicate guard (Robins
  // melding, 30-7). Served like the other legs: same shape, one parser.
  const mine = AP.selfAuthor(base, auth.site);
  const sent = AP.getSentNotes(base, auth.site, 60).map((n) => ({
    id: `${n.id}#create`,
    type: 'Create',
    actor: me,
    published: n.published,
    // The leading mention anchor is addressing, not prose (the DM leg strips
    // it the same way); the Mention tags built from the full content stay.
    object: {
      ...n, content: AP.stripLeadingMentions(n.content),
      attributedTo: AP.actorObject(typeof n.attributedTo === 'string' ? n.attributedTo : me, mine),
    },
  }));
  // Newest first over all legs, so the app can keep treating this as one feed.
  const items = [...posts, ...messages, ...replies, ...sent].sort((a, b) => String(b.published || '').localeCompare(String(a.published || '')));
  AP.sendAP(res, {
    '@context': AP.AP_CONTEXT,
    id: `${base}/ap/users/${auth.site.slug}/inbox`,
    type: 'OrderedCollection',
    // What this account may do with what is in here (FEP-633c 5.6). Owner-only
    // by construction, and never on the public actor document: it says
    // something about a child, and only the child and its guardians need it.
    'shaer:capabilities': capabilitiesOf(P, gate),
    // Het merk van wat hierin zit. Geef hem terug als `since` om op het
    // volgende te wachten. NA het samenstellen bepaald, zodat hij precies dekt
    // wat je in handen hebt en niet iets dat er ondertussen bij kwam.
    'shaer:cursor': AP.feedCursor(auth.site.slug),
    totalItems: items.length,
    orderedItems: items,
  });
  return undefined;
});

// ── uploadMedia (owner only, AP C2S) ──────────────────────────────
// The actor advertises endpoints.uploadMedia; this implements it. A bearer
// scoped to this site uploads one image/audio/video (multipart field "file",
// AP convention) into the same store the reply editor uses, and gets back
// { url, mediaType, name } to attach on a note (e.g. the help-buoy capture).
const AP_MEDIA_DIR = mediaDir('REPLY_MEDIA_PATH', 'reply-media');
fs.mkdirSync(AP_MEDIA_DIR, { recursive: true });
const AP_MEDIA_EXT = new Set(['.jpg', '.jpeg', '.png', '.webp', '.gif', '.mp3', '.m4a', '.ogg', '.opus', '.flac', '.wav', '.mp4', '.webm', '.mov']);
const apMediaUpload = multer({
  storage: multer.diskStorage({
    destination: (req, file, cb) => cb(null, AP_MEDIA_DIR),
    filename: (req, file, cb) => cb(null, `${randomUUID()}${path.extname(file.originalname || '').toLowerCase()}`),
  }),
  limits: { fileSize: 32 * 1024 * 1024 },
  fileFilter: (req, file, cb) => {
    const ext = path.extname(file.originalname || '').toLowerCase();
    if (!AP_MEDIA_EXT.has(ext)) return cb(new Error('Media must be an image, audio or video file'));
    cb(null, true);
  },
});
router.post('/ap/users/:slug/uploadMedia', (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  if (!auth || auth.site.slug !== req.params.slug) return res.status(403).end();
  apMediaUpload.single('file')(req, res, (err) => {
    if (err) return res.status(400).json({ error: err.message });
    if (!req.file) return res.status(400).json({ error: 'No file' });
    const mime = String(req.file.mimetype || '');
    if (!/^(image|audio|video)\//.test(mime)) {
      try { fs.unlinkSync(req.file.path); } catch { /* best effort */ }
      return res.status(400).json({ error: 'Media must be an image, audio or video file' });
    }
    // A video gets a poster frame next to it (shaer-zowq), best-effort and
    // out of band: ffmpeg pulls one frame at 1s into <name>.poster.jpg. On a
    // machine without ffmpeg nothing happens and nothing breaks; the clients
    // fall back to extracting a frame natively.
    if (mime.startsWith('video/')) {
      // The bundled static build (ffmpeg-static) does the work, exactly like
      // VideoCoverService and AudioTranscoder already do: Klonkt SHIPS its
      // ffmpeg (Robins opmerking, 30-7), so nothing needs installing on any
      // machine. Soft dependency + best-effort: absent stays silent, and
      // FFMPEG_PATH can still override for an operator who wants a newer one.
      Promise.all([import('child_process'), import('ffmpeg-static')]).then(([{ execFile }, ff]) => {
        const bin = process.env.FFMPEG_PATH || ff.default;
        if (!bin) return;
        const poster = req.file.path + '.poster.jpg';
        execFile(bin, ['-hide_banner', '-loglevel', 'error', '-y', '-ss', '1', '-i', req.file.path, '-frames:v', '1', '-vf', "scale='min(640,iw)':-2", poster],
          { timeout: 30000 }, (e) => { if (e && e.code !== 'ENOENT') console.warn('[media] poster failed:', e.message); });
      }).catch(() => { /* never blocks the upload */ });
    }
    // Audio gets the same courtesy (Robins vraag, 30-7: vrolijk de kale
    // audio-tegel op): ffmpeg draws the waveform into <name>.poster.png.
    // White on transparent, so the tile's own gradient stays the backdrop
    // and every audio post keeps its own hue. The shape is bars, not the
    // raw hairy wave (Robins tweede vraag): peak and average sampled into
    // 57 columns (soft tip over bright core), blown up nearest-neighbor to
    // 14px bars, and drawgrid ERASES 5px gaps (c=black@0 + replace=1 writes
    // transparent pixels; h=2*ih keeps horizontal grid lines out of frame).
    if (mime.startsWith('audio/')) {
      Promise.all([import('child_process'), import('ffmpeg-static')]).then(([{ execFile }, ff]) => {
        const bin = process.env.FFMPEG_PATH || ff.default;
        if (!bin) return;
        const poster = req.file.path + '.poster.png';
        const graph = '[0:a]aformat=channel_layouts=mono,asplit[a][b];'
          + '[a]showwavespic=s=57x256:colors=white@0.5:filter=peak:scale=sqrt:draw=full[pk];'
          + '[b]showwavespic=s=57x256:colors=white:filter=average:scale=sqrt:draw=full[av];'
          + '[pk][av]overlay=format=auto,scale=798:256:flags=neighbor,drawgrid=w=14:h=2*ih:t=5:c=black@0:replace=1';
        execFile(bin, ['-hide_banner', '-loglevel', 'error', '-y', '-i', req.file.path, '-filter_complex', graph, '-frames:v', '1', poster],
          { timeout: 30000 }, (e) => { if (e && e.code !== 'ENOENT') console.warn('[media] waveform failed:', e.message); });
      }).catch(() => { /* never blocks the upload */ });
    }
    res.status(201).json({
      url: '/media/reply-media/' + req.file.filename,
      mediaType: mime,
      name: String(req.file.originalname || '').slice(0, 120),
    });
  });
});

// ── Followers (count-only public, full for the owner) ─────────────
// A C2S bearer scoped to this site (the account owner) gets the real actor
// URIs so their own client can build a friends list; everyone else gets the
// count only (privacy).
// FEP-9876: enrichment is opt-in via `Prefer: return=representation` (RFC 7240).
// Returns true and sets the response headers when the owner asked for it.
function wantsEnriched(req, res) {
  res.set('Vary', 'Prefer');   // enriched and bare are two representations
  if (AP.prefersEnriched(req.get('Prefer'))) {
    res.set('Preference-Applied', 'return=representation');
    return true;
  }
  return false;
}

router.get('/ap/users/:slug/followers', (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  const owner = auth && auth.site.slug === req.params.slug;
  const site = owner ? auth.site : publicSite(req.params.slug);
  if (!site) return res.status(404).end();
  if (owner) {
    const uris = db.prepare('SELECT actor_uri FROM ap_followers WHERE slug = ? ORDER BY created_at').all(site.slug).map((r) => r.actor_uri);
    // Default = bare references; enrich only when the client asks (FEP-9876).
    const items = wantsEnriched(req, res) ? uris.map((u) => AP.buildActorRef(site.slug, u)) : uris;
    return AP.sendAP(res, AP.buildFollowers(baseUrl(req), site, items.length, items));
  }
  const n = db.prepare('SELECT COUNT(*) n FROM ap_followers WHERE slug = ?').get(site.slug).n;
  AP.sendAP(res, AP.buildFollowers(baseUrl(req), site, n));
});

// ── Following (count-only public, full for the owner) ─────────────
router.get('/ap/users/:slug/following', (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  const owner = auth && auth.site.slug === req.params.slug;
  const site = owner ? auth.site : publicSite(req.params.slug);
  if (!site) return res.status(404).end();
  if (owner) {
    const enrich = wantsEnriched(req, res);   // FEP-9876 opt-in
    let items = [];
    try {
      const uris = db.prepare("SELECT actor_uri FROM ap_following WHERE slug = ? AND status = 'accepted' ORDER BY created_at").all(site.slug).map((r) => r.actor_uri);
      items = enrich ? uris.map((u) => AP.buildActorRef(site.slug, u)) : uris;
    } catch { /* table may not exist */ }
    return AP.sendAP(res, AP.buildFollowing(baseUrl(req), site, items.length, items));
  }
  let n = 0;
  try { n = db.prepare("SELECT COUNT(*) n FROM ap_following WHERE slug = ? AND status = 'accepted'").get(site.slug).n; } catch { /* table may not exist */ }
  AP.sendAP(res, AP.buildFollowing(baseUrl(req), site, n));
});

// ── Featured (pinned posts → Mastodon "Featured" tab) ─────────────
router.get('/ap/users/:slug/featured', (req, res) => {
  const site = publicSite(req.params.slug);
  if (!site) return res.status(404).end();
  // NB: Mastodon DISPLAYS the featured collection in REVERSE (pins shown
  // last-processed-first). So we emit it reversed (lowest pin priority first,
  // rank 1 last) → Mastodon flips it back to pin-rank ascending on the profile.
  const posts = db.prepare(
    `SELECT id, slug, title, content, cover_image_url, cover_video_url, nsfw, content_warning, c2s_attachments, published_at, created_at
     FROM posts WHERE site_id = ? AND status = 'published' AND (fan_only IS NULL OR fan_only = 0)
       AND pinned IS NOT NULL AND pinned > 0
     ORDER BY pinned DESC, COALESCE(published_at, created_at) ASC LIMIT 20`
  ).all(site.id);
  AP.sendAP(res, AP.buildFeatured(baseUrl(req), site, posts));
});

// ── Playlist als dereferenceerbare AP-collectie (shaer-ayc) ───────
// De eerste stap van het Funkwhale-spoor: een playlist heeft een id, dus een
// stabiele URI. Alleen het fedi_open-deel staat erin (de poort is per bestand
// en eenrichtings; zie setAudioFediOpen in routes/posts.js) — een collectie
// zonder open tracks bestaat wel maar is leeg, want de playlist zelf is niet
// geheim, alleen de bestanden erachter.
// De lijst van alle playlist-collecties (shaer-ayc, stap 2). De actor wijst
// hierheen via AS2 `streams`. Kaal standaard; verrijkte stubs op verzoek
// (FEP-9876), dezelfde conventie als followers/following.
router.get('/ap/users/:slug/playlists', (req, res) => {
  const site = publicSite(req.params.slug);
  if (!site) return res.status(404).end();
  AP.sendAP(res, AP.listPlaylistsAP(baseUrl(req), site, wantsEnriched(req, res)));
});

// De tracks van deze site: de kanonieke plek voor onze muziek (shaer-0nh,
// stap 3). Een playlist is een keuze hieruit; deze collectie is alles wat de
// artiest heeft opengezet, ook wat in geen enkele playlist staat.
router.get('/ap/users/:slug/tracks', (req, res) => {
  const site = publicSite(req.params.slug);
  if (!site) return res.status(404).end();
  AP.sendAP(res, AP.buildTrackCollection(baseUrl(req), site, AP.siteOpenTracks(site.id)));
});

// Eén track, los op te halen. Een gesloten track is AFWEZIG, niet leeg: 404,
// dezelfde regel als in de collectie, zodat het bestaan van een gated nummer
// niet uit een ander antwoord af te leiden is.
router.get('/ap/users/:slug/tracks/:id', (req, res) => {
  const site = publicSite(req.params.slug);
  if (!site) return res.status(404).end();
  const row = AP.openTrack(site.id, req.params.id);
  if (!row) return res.status(404).end();
  AP.sendAP(res, AP.buildTrackAudio(baseUrl(req), site, row, { standalone: true }));
});

// De losse tracks van een post als EEN uitgave (shaer-38y). Ze gingen tot nu
// toe los de deur uit -- Audio-objecten die een lezer nergens kon plaatsen. Ze
// horen bij elkaar omdat ze in dezelfde post staan, en die post leent zijn
// titel, tekst, hoes en tags uit. 404 als de post geen muzikale eenheid IS:
// dan is er niets om naar te wijzen, en dat is geen lege collectie maar een
// collectie die niet bestaat.
router.get('/ap/users/:slug/posts/:id/tracks', (req, res) => {
  const site = publicSite(req.params.slug);
  if (!site) return res.status(404).end();
  const post = db.prepare(
    "SELECT id, slug, title, excerpt, content, cover_image_url, tags FROM posts WHERE id = ? AND site_id = ? AND status = 'published'"
  ).get(req.params.id, site.id);
  if (!post) return res.status(404).end();
  const col = AP.buildPostTrackCollection(baseUrl(req), site, post);
  if (!col) return res.status(404).end();
  AP.sendAP(res, col);
});

router.get('/ap/users/:slug/playlists/:id', (req, res) => {
  const site = publicSite(req.params.slug);
  if (!site) return res.status(404).end();
  const pl = db.prepare('SELECT id, title, artist, year, cover_url, kind FROM playlists WHERE id = ? AND site_id = ?')
    .get(req.params.id, site.id);
  if (!pl) return res.status(404).end();
  AP.sendAP(res, AP.buildPlaylistCollection(baseUrl(req), site, pl, AP.playlistOpenTracks(pl.id)));
});

// ── Note ──────────────────────────────────────────────────────────
router.get('/ap/notes/:id', async (req, res) => {
  // No fan_only filter in the SELECT anymore: a friends-only post is not
  // absent, it is GATED. The old route hid it from EVERYONE, also from the
  // follower whose friendship earns it — so the signed resolution the reply
  // path performs knocked on a door that could never open, and every reply
  // to a friends-only post (Shaer's default!) died in
  // cannot_resolve_inReplyTo. Strangers still get the exact same 404, so a
  // note's existence stays as private as before.
  const post = db.prepare(
    "SELECT * FROM posts WHERE id = ? AND status = 'published'"
  ).get(req.params.id);
  if (post && AP.noteAudience(post) !== 'public') {
    // The whole gate in a try: this is the only async route in this file,
    // and Express 4 does not catch an async rejection — the request would
    // hang forever instead of failing (which is exactly how the missing
    // default-export entry manifested while building this). Any error here
    // reads as "not authorized", never as silence.
    try {
      if (AP.noteAudience(post) === 'direct') return res.status(404).end();
      const gsite = db.prepare('SELECT * FROM sites WHERE id = ?').get(post.site_id);
      const actor = await AP.verifyRequest(req).catch(() => null);
      if (!actor || !AP.mayReadNote(gsite, post, actor.id)) return res.status(404).end();
    } catch { return res.status(404).end(); }
  }
  if (!post) {
    // Could be one of OUR outbound replies (ap_outbox), not a post.
    const note = AP.getOutboxNote(baseUrl(req), req.params.id);
    if (!note) return res.status(404).end();
    if (!AP.apWants(req)) {
      // A browser hit a reply's AP URL → send them to the source it replies to
      // (where the post + its reactions live), falling back to the site home.
      const src = (typeof note.inReplyTo === 'string' && /^https?:\/\//i.test(note.inReplyTo))
        ? note.inReplyTo : (baseUrl(req) + '/');
      return res.redirect(302, src);
    }
    return AP.sendAP(res, { '@context': AP.AP_CONTEXT, ...note });
  }
  const site = db.prepare('SELECT * FROM sites WHERE id = ?').get(post.site_id);
  if (!site) return res.status(404).end();
  const note = AP.buildNote(baseUrl(req), site, post);
  if (!AP.apWants(req)) {
    // A browser hit a post's AP note URL → send them to the human post page
    // (which shows the post + its "from the fediverse" reactions).
    return res.redirect(302, note.url || (baseUrl(req) + '/'));
  }
  AP.sendAP(res, { '@context': AP.AP_CONTEXT, ...note });
});

// ── Replies collection ── lets remote servers fetch a post's whole thread.
// ── De composer-preview (shaer-k3f): een URL wordt alvast een kaart ──
//
// Bearer-only, net als de thread: dit is de eigen app die tijdens het typen
// vraagt wat een link gaat worden. Dezelfde pijplijn als publiceren, dus de
// preview kan niet iets beloven dat de post niet waarmaakt. De embed gaat
// langs de eigen poort van de lezer -- een ward zonder open embeds-poort
// krijgt in de composer geen kaart die zijn feed hem ook niet zou tonen.
router.get('/ap/users/:slug/card', async (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  if (!auth || auth.site.slug !== req.params.slug) return res.status(403).end();
  const uit = await AP.previewCard(String(req.query.url || ''));
  const isWard = (() => { try { return Guardianship.listGuardians(auth.site.slug).length > 0; } catch { return false; } })();
  const embedsAllowed = Guardianship.externalEmbedsAllowed(auth.site.external_embeds, isWard);
  const playback = embedsAllowed && Guardianship.externalPlaybackAllowed(auth.site.external_playback, isWard);
  AP.sendAP(res, {
    '@context': AP.AP_CONTEXT,
    quote: AP.quoteObject(uit.quoteJson),
    preview: embedsAllowed ? AP.previewObject(uit.embedJson, { playback }) : undefined,
  }, 'private, no-store');
});

// ── De thread onder een post (shaer-tqz): ophalen, niet bewaren ────
//
// Bearer-only: dit is de eigen app van deze account die vraagt, nooit een
// vreemde. Klonkt doet de ondertekende GET die de app zelf niet kan (de
// sleutel staat hier), loopt één pagina van de replies-collectie af en geeft
// genormaliseerde notes terug. Er wordt NIETS opgeslagen; zie getThread.
//
// Voor een ward geldt de veiligste stand tot shaer-vw4 beslist is: alleen
// antwoorden uit de kring die de guardians al kennen, en shaer:hidden telt wat
// er buiten viel. De telling staat er zodat de UI eerlijk kan zijn -- OF hij
// getoond wordt is onderdeel van datzelfde besluit.
router.get('/ap/users/:slug/thread', async (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  if (!auth || auth.site.slug !== req.params.slug) return res.status(403).end();
  const objectUri = String(req.query.object || '');
  if (!/^https:\/\//i.test(objectUri)) return res.status(400).json({ error: 'object must be an https URI' });
  const isWard = (() => { try { return Guardianship.listGuardians(auth.site.slug).length > 0; } catch { return false; } })();
  const uit = await AP.getThread(auth.site.slug, objectUri);
  if (!uit.found) {
    // WIENS schuld is dit? De oude melding zei "jouw server kon het niet
    // laden" terwijl onze server het prima deed en de BRON weigerde -- dat
    // wees naar de verkeerde partij (Barts melding, 10-8: een post van een
    // account dat hij vanochtend nog volgde, en dat nu niet meer).
    // 401/403/404/410 is een besluit van die server; al het andere, inclusief
    // een status die we niet eens kregen, is een storing.
    const geweigerd = [401, 403, 404, 410].includes(uit.sourceStatus);
    return res.status(geweigerd ? 404 : 502)
      .json({ error: geweigerd ? 'not shared by source' : 'source unreachable', sourceStatus: uit.sourceStatus || undefined });
  }
  // De poortstand komt uit de kolom (shaer-9y2): expliciete 0/1 van de
  // guardians wint, de automatiek is dicht-voor-een-ward. Dicht is de KRING,
  // niet niets: antwoorden van al goedgekeurd volk blijven staan, en wat er
  // buiten valt wordt geteld. Beeld, muziek en emoji gaan door dezelfde
  // poorten als de tijdlijn -- per verzoek, buiten de threadcache om.
  const threadsOpen = Guardianship.wardGateAllowed(auth.site.external_threads, isWard);
  const gate2 = (col) => Guardianship.wardGateAllowed(auth.site[col], isWard);
  const kring = threadsOpen ? { notes: uit.notes, hidden: 0 } : AP.filterThreadToCircle(auth.site.slug, uit.notes);
  const imagesOk = gate2('gate_images'), musicOk = gate2('gate_music'), emojiOk = gate2('gate_custom_emoji');
  uit.notes = kring.notes.map((n) => ({
    ...n,
    attachment: AP.gateAttachments(n.attachment, { images: imagesOk, audio: musicOk }),
    tag: emojiOk ? n.tag : AP.stripEmojiTags(n.tag),
    // De emoji-poort knipt in de byline zelf: FEP-9098 zit in de tag van de
    // ingesloten actor, niet meer in een eigen emoji-kaart ernaast.
    attributedTo: (!emojiOk && n.attributedTo && typeof n.attributedTo === 'object')
      ? { ...n.attributedTo, tag: undefined } : n.attributedTo,
  }));
  uit.hidden = kring.hidden;
  // Liked/boosted per antwoord, BUITEN de cache om: de genormaliseerde notes
  // mogen twee minuten oud zijn, maar of JIJ iets geliked hebt hoort van nu te
  // zijn -- anders springt het hartje terug zodra de reader opnieuw opent.
  const reacties = AP.getReactionsFor(auth.site.slug, uit.notes.map((n) => n.id));
  AP.sendAP(res, {
    '@context': AP.AP_CONTEXT,
    id: `${baseUrl(req)}/ap/users/${encodeURIComponent(auth.site.slug)}/thread?object=${encodeURIComponent(objectUri)}`,
    type: 'OrderedCollection',
    totalItems: uit.notes.length,
    orderedItems: uit.notes.map((n) => ({
      ...n,
      'shaer:liked': !!(reacties.get(n.id) || {}).liked,
      'shaer:boosted': !!(reacties.get(n.id) || {}).boosted,
    })),
    'shaer:hidden': uit.hidden || undefined,
  }, 'private, no-store');
});

router.get('/ap/notes/:id/replies', (req, res) => {
  const base = baseUrl(req);
  const items = AP.getReplyUris(base, req.params.id);
  AP.sendAP(res, {
    '@context': AP.AP_CONTEXT,
    id: `${base}/ap/notes/${req.params.id}/replies`,
    type: 'OrderedCollection',
    totalItems: items.length,
    orderedItems: items,
  });
});

// ── NodeInfo ── standard instance metadata so fediverse tools recognise Klonkt.
router.get('/.well-known/nodeinfo', (req, res) => {
  res.type('application/json');
  res.set('Cache-Control', 'public, max-age=3600');
  res.send(JSON.stringify({ links: [{ rel: 'http://nodeinfo.diaspora.software/ns/schema/2.1', href: `${baseUrl(req)}/nodeinfo/2.1` }] }));
});
router.get('/nodeinfo/2.1', (req, res) => {
  let users = 0; let posts = 0;
  // "users" = public AP actors (sites), not the admin/member account rows.
  try { users = db.prepare('SELECT COUNT(*) c FROM sites WHERE (is_public IS NULL OR is_public = 1)').get().c; } catch { /* */ }
  try { posts = db.prepare("SELECT COUNT(*) c FROM posts WHERE status = 'published'").get().c; } catch { /* */ }
  res.type('application/json; charset=utf-8');
  res.set('Cache-Control', 'public, max-age=600');
  res.send(JSON.stringify({
    version: '2.1',
    software: { name: 'klonkt', version: _ver, repository: 'https://github.com/roboburr/klonkt' },
    protocols: ['activitypub'],
    services: { inbound: [], outbound: [] },
    openRegistrations: false,
    usage: { users: { total: users }, localPosts: posts },
    metadata: { nodeName: 'Klonkt' },
  }));
});

// ── Inbox — Follow→Accept, Undo Follow (best-effort signature verify) ──
const apJson = express.json({
  type: ['application/activity+json', 'application/ld+json', 'application/json'],
  limit: '1mb',
  verify: (req, _res, buf) => { req.rawBody = buf; }, // raw body for digest verification
});
router.post(['/ap/users/:slug/inbox', '/ap/inbox'], apInboxLimiter, apJson, async (req, res) => {
  try { return res.status(await AP.handleInbox(req, req.params.slug || null) || 202).end(); }
  catch (e) { console.warn('[AP inbox] error:', e.message); return res.status(202).end(); }
});

// ── Outbox POST: ActivityPub Client-to-Server ─────────────────────
// A bearer-authenticated client (Shaer) POSTs an activity; we translate it onto
// the normal delivery machinery. The token is scoped to one user+site (OAuth
// consent), so it must match the slug in the URL. (Declared after apJson, which
// this shares with the inbox handler.)
router.post('/ap/users/:slug/outbox', apInboxLimiter, apJson, async (req, res) => {
  const auth = OAuth.verifyBearer(req.headers.authorization);
  if (!auth) { res.set('WWW-Authenticate', 'Bearer'); return res.status(401).json({ error: 'invalid_token' }); }
  if (auth.site.slug !== req.params.slug) return res.status(403).json({ error: 'wrong_site', detail: 'token is scoped to a different site' });
  if (auth.user.readonly) return res.status(403).json({ error: 'read_only_account' });

  const out = await AP.ingestOutboxActivity(auth.site, auth.user, req.body);
  if (out.error) return res.status(out.status || 400).json({ error: out.error, detail: out.detail });
  // 201 Created → Location header (AP spec); 202 Accepted for side-effect verbs.
  if (out.status === 201 && out.url) res.set('Location', out.url);
  // `state` carries a third outcome the app must be able to tell apart from a
  // plain success: a ward's follow held for its guardians (§5.3, shaer-p729).
  return res.status(out.status || 202).json({ ok: true, id: out.id, url: out.url, ...(out.state ? { state: out.state } : {}) });
});

export default router;