wiki-plugin-hitchhiker 0.2.0

package/server/server.js

@@ -0,0 +1,240 @@
+// wiki-plugin-hitchhiker — server component (ESM)
+//
+// The farm runs Node v24 / wiki 0.40+, which loads plugin servers via import()
+// — so this matches wiki-plugin-similarity's ESM server (no server/package.json).
+// NOTE: for eventual publish to an older/public farm, revisit portability — an ESM
+// server silently 404s on wiki-server that uses require() + Node < 22.12.
+//
+// GET /system/unfurl.json?url=<url>
+//   Link-preview "unfurl" for a dropped URL. Returns a normalized STATIC card:
+//     { url, title, description, provider, author, type, image, favicon, source }
+//   - oEmbed metadata first (@extractus/oembed-extractor), OpenGraph/Twitter/JSON-LD
+//     fallback (open-graph-scraper). We use metadata only — never the oEmbed html
+//     embed — so nothing live/third-party is injected (static-cards-only).
+//   - The thumbnail is fetched server-side and inlined as a data: URI, so the card
+//     makes ZERO client→provider requests when the report renders.
+//   - SSRF-guarded (public http/https only). In-memory TTL cache. Never throws to
+//     the client: on any failure it returns a minimal card so a drop always works.
+//
+// v1 scope: private farm (owner-only). Before public use, harden SSRF against
+// redirect-following (the extractor libs do their own fetch and may follow
+// redirects to internal hosts) and tighten image caps.
+
+import dns from 'node:dns/promises'
+import net from 'node:net'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import ogs from 'open-graph-scraper'
+import { extract as oembedExtract } from '@extractus/oembed-extractor'
+
+const CACHE = new Map()
+const TTL = 1000 * 60 * 30 // 30 minutes
+const FETCH_MS = 8000
+const MAX_IMAGE_BYTES = 300 * 1024
+
+// ── farm-domain listing ("is this host ours?") ────────────────────────────────
+// primary farm root = 'local' (the *.localhost private farm); extra roots = 'public'
+// (the Nextcloud mirror). A directory is a wiki domain if it contains a pages/ dir.
+const EXTRA_FARMS = (process.env.WIKI_EXTRA_FARMS || '').split(':').filter(Boolean)
+let _farmCache = null
+const listFarmDomains = primaryRoot => {
+  if (_farmCache && Date.now() - _farmCache.t < 60000) return _farmCache.v
+  const extra = EXTRA_FARMS.length
+    ? EXTRA_FARMS
+    : [path.join(os.homedir(), 'Nextcloud', 'fedwiki')].filter(p => {
+        try {
+          return fs.existsSync(p)
+        } catch {
+          return false
+        }
+      })
+  const farms = [[primaryRoot, 'local'], ...extra.map(f => [f, 'public'])]
+  const out = { local: [], public: [] }
+  const seen = new Set()
+  for (const [farm, kind] of farms) {
+    if (!farm) continue
+    let entries
+    try {
+      entries = fs.readdirSync(farm, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const ent of entries) {
+      if (!ent.isDirectory() || seen.has(ent.name)) continue
+      try {
+        if (!fs.existsSync(path.join(farm, ent.name, 'pages'))) continue
+      } catch {
+        continue
+      }
+      seen.add(ent.name)
+      out[kind].push(ent.name)
+    }
+  }
+  _farmCache = { t: Date.now(), v: out }
+  return out
+}
+
+// ── SSRF guard ────────────────────────────────────────────────────────────────
+const isPrivateIp = ip => {
+  if (net.isIP(ip) === 4) {
+    const [a, b] = ip.split('.').map(Number)
+    return (
+      a === 0 ||
+      a === 127 ||
+      a === 10 ||
+      (a === 172 && b >= 16 && b <= 31) ||
+      (a === 192 && b === 168) ||
+      (a === 169 && b === 254) ||
+      a >= 224
+    )
+  }
+  const s = ip.toLowerCase()
+  return s === '::1' || s === '::' || s.startsWith('fc') || s.startsWith('fd') || s.startsWith('fe80')
+}
+
+const assertPublicUrl = async raw => {
+  const u = new URL(raw) // throws on bad url
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') throw new Error('protocol not allowed')
+  const host = u.hostname.toLowerCase()
+  if (host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local') || host.endsWith('.internal'))
+    throw new Error('internal host blocked')
+  // Literal-IP hosts are range-checked directly; names are resolved first.
+  const addrs = net.isIP(host) ? [{ address: host }] : await dns.lookup(host, { all: true })
+  for (const { address } of addrs) if (isPrivateIp(address)) throw new Error('private address blocked')
+  return u
+}
+
+// ── thumbnail → data URI (no client→provider request when the card renders) ───
+const inlineImage = async imgUrl => {
+  if (!imgUrl) return ''
+  try {
+    await assertPublicUrl(imgUrl)
+    const r = await fetch(imgUrl, { signal: AbortSignal.timeout(FETCH_MS), redirect: 'follow' })
+    if (!r.ok) return ''
+    const type = r.headers.get('content-type') || ''
+    if (!/^image\//i.test(type)) return ''
+    const len = Number(r.headers.get('content-length') || 0)
+    if (len && len > MAX_IMAGE_BYTES) return ''
+    const buf = Buffer.from(await r.arrayBuffer())
+    if (buf.length > MAX_IMAGE_BYTES) return ''
+    return `data:${type.split(';')[0]};base64,${buf.toString('base64')}`
+  } catch {
+    return ''
+  }
+}
+
+// ── extractors ────────────────────────────────────────────────────────────────
+const fromOembed = async url => {
+  try {
+    const d = await oembedExtract(url, {}, { signal: AbortSignal.timeout(FETCH_MS) })
+    if (!d) return null
+    return {
+      title: d.title || d.author_name || '',
+      description: '',
+      provider: d.provider_name || '',
+      author: d.author_name || '',
+      type: d.type || 'rich',
+      thumb: d.thumbnail_url || '',
+      source: 'oembed',
+    }
+  } catch {
+    return null // not an oEmbed provider (or fetch failed) → fall back
+  }
+}
+
+const fromOpenGraph = async url => {
+  try {
+    const r = await ogs({ url, fetchOptions: { signal: AbortSignal.timeout(FETCH_MS) } })
+    if (!r || r.error || !r.result) return null
+    const x = r.result
+    const img =
+      (Array.isArray(x.ogImage) && x.ogImage[0] && x.ogImage[0].url) ||
+      (Array.isArray(x.twitterImage) && x.twitterImage[0] && x.twitterImage[0].url) ||
+      ''
+    return {
+      title: x.ogTitle || x.twitterTitle || x.dcTitle || '',
+      description: x.ogDescription || x.twitterDescription || '',
+      provider: x.ogSiteName || '',
+      author: x.author || '',
+      type: x.ogType || 'website',
+      thumb: img,
+      favicon: x.favicon || '',
+      source: 'opengraph',
+    }
+  } catch {
+    return null
+  }
+}
+
+// ── route ─────────────────────────────────────────────────────────────────────
+export const startServer = ({ app, argv }) => {
+  // argv.status = {farm}/{thisDomain}/status → primary farm root is two levels up.
+  const primaryRoot = argv && argv.status ? path.dirname(path.dirname(argv.status)) : ''
+  console.log('[wiki-plugin-hitchhiker] registering GET /system/unfurl.json + /system/farm-domains.json')
+
+  const cors = res => {
+    res.setHeader('Access-Control-Allow-Origin', '*')
+    res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS')
+  }
+
+  app.options('/system/farm-domains.json', (req, res) => {
+    cors(res)
+    res.sendStatus(204)
+  })
+  app.get('/system/farm-domains.json', (req, res) => {
+    cors(res)
+    res.json(listFarmDomains(primaryRoot))
+  })
+
+  app.options('/system/unfurl.json', (req, res) => {
+    cors(res)
+    res.sendStatus(204)
+  })
+
+  app.get('/system/unfurl.json', async (req, res) => {
+    cors(res)
+    const url = String(req.query.url || '')
+    let host = ''
+    try {
+      host = new URL(url).hostname
+    } catch {}
+
+    const hit = CACHE.get(url)
+    if (hit && Date.now() - hit.t < TTL) return res.json(hit.v)
+
+    let card
+    try {
+      await assertPublicUrl(url)
+      const meta = (await fromOembed(url)) || (await fromOpenGraph(url)) || {}
+      const image = await inlineImage(meta.thumb)
+      card = {
+        url,
+        title: meta.title || host || url,
+        description: meta.description || '',
+        provider: meta.provider || host || '',
+        author: meta.author || '',
+        type: meta.type || 'link',
+        image,
+        favicon: meta.favicon || '',
+        source: meta.source || 'fallback',
+      }
+    } catch (e) {
+      // Graceful degradation (bad/blocked/offline URL) — always return a card.
+      card = {
+        url,
+        title: host || url,
+        description: '',
+        provider: host,
+        author: '',
+        type: 'link',
+        image: '',
+        favicon: '',
+        source: 'error',
+        error: String((e && e.message) || e),
+      }
+    }
+    CACHE.set(url, { t: Date.now(), v: card })
+    res.json(card)
+  })
+}