wiki-plugin-hitchhiker 0.2.0 → 0.3.1

package/README.md

@@ -12,8 +12,8 @@ fallback), unless a site has authored its own page of that slug. Currently:
 `tools`, `changes-to-this-site` (copied from hitchhikers.earth, journals stripped),
 and `about-hitchhiker-plugin`.
 
-This plugin defines **no authorable item type** (no `factory.json`) — its value is the
-pages and the served client script below.
+This plugin defines **no authorable item type** — its `factory.json` exists only to
+declare the bundled pages — its value is the pages and the served client script below.
 
 ## 2. Client UX override (`client/wiki-ux.js`)
 Served at `/plugins/hitchhiker/wiki-ux.js` and loaded globally on every page by the
@@ -40,7 +40,10 @@ surface. It installs:
   a loud pulsing highlight; on drop it opens a ghost **preview card** (see the server below).
 
 ## 3. Server component (`server/server.js`, ESM)
-`GET /system/unfurl.json?url=…` → a normalized **static** link-preview card
+`GET /system/unfurl.json?url=…` → a normalized **static** link-preview card.
+Since 0.3.0 the two extractor libraries are **imported on first request, not at
+start-up** — they cost about 14 MB of heap together, and a host that never
+unfurls should never pay it. Start-up cost of this server is now under 1 MB.
 `{ url, title, description, provider, author, type, image, favicon, source }`.
 - oEmbed metadata first (`@extractus/oembed-extractor`), OpenGraph/Twitter/JSON-LD fallback
   (`open-graph-scraper`). Metadata only — never the oEmbed HTML embed (no live third-party

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-plugin-hitchhiker",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "House UX + default-pages plugin for the hitchhiker farms: ships default pages (Tools, Changes to this Site) and hosts the wiki-ux.js client override (friendlier factory chooser + page-flag tool page), loaded globally by the wiki-security-hitchhiker bootstrap.",
   "type": "module",
   "files": [
@@ -29,5 +29,8 @@
       "version": 1,
       "spec": "api/openapi.json"
     }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
   }
-}
+}

package/server/server.js

@@ -17,16 +17,28 @@
 //     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.
+// redirect-following: since 0.3.1 the OpenGraph and image fetches walk redirects
+// by hand and re-check every hop (safeFetch); the oEmbed endpoint hop remains
+// the library's own — see fromOembed.
 
 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'
+
+// The two extractor libraries are imported on first use, not at start-up.
+// Together they load about 14 MB of heap — eighty per cent of the memory of
+// every plugin server on the farm combined — and this server is resident in
+// the shared process on every site of the host, whether or not anything ever
+// asks for a link preview. Lazy import means a host that never unfurls never
+// pays. Each import is awaited once and cached, so the second request costs
+// nothing; a failed import is not cached, so a transient error does not stick.
+let ogsP = null
+const ogs = (...a) => (ogsP ||= import('open-graph-scraper').then(m => m.default, e => { ogsP = null; throw e })).then(f => f(...a))
+let oembedP = null
+const oembedExtract = (...a) =>
+  (oembedP ||= import('@extractus/oembed-extractor').then(m => m.extract, e => { oembedP = null; throw e })).then(f => f(...a))
 
 const CACHE = new Map()
 const TTL = 1000 * 60 * 30 // 30 minutes
@@ -105,12 +117,34 @@ const assertPublicUrl = async raw => {
   return u
 }
 
+// ── a fetch that re-checks every hop ─────────────────────────────────────────
+// redirect:'follow' would let a public host 302 us onto 127.0.0.1 after the
+// guard has already passed the starting URL. So follow by hand: manual
+// redirects, assertPublicUrl on each Location, and a small hop cap.
+const MAX_HOPS = 4
+const safeFetch = async (raw, init = {}) => {
+  let url = raw
+  for (let hop = 0; hop <= MAX_HOPS; hop++) {
+    await assertPublicUrl(url)
+    const r = await fetch(url, { ...init, redirect: 'manual' })
+    if (r.status >= 300 && r.status < 400) {
+      const loc = r.headers.get('location')
+      if (!loc) return r
+      url = new URL(loc, url).href
+      continue
+    }
+    return r
+  }
+  throw new Error('too many redirects')
+}
+
+export const __safeFetchForTest = (...a) => safeFetch(...a)
+
 // ── 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' })
+    const r = await safeFetch(imgUrl, { signal: AbortSignal.timeout(FETCH_MS) })
     if (!r.ok) return ''
     const type = r.headers.get('content-type') || ''
     if (!/^image\//i.test(type)) return ''
@@ -127,6 +161,12 @@ const inlineImage = async imgUrl => {
 // ── extractors ────────────────────────────────────────────────────────────────
 const fromOembed = async url => {
   try {
+    // Residual: the extractor discovers an oEmbed endpoint from the page and
+    // fetches it with its own client. The starting URL is checked by the route,
+    // the thumbnail it returns is re-checked by inlineImage, but the endpoint
+    // hop itself is the library's. Acceptable on a host that only unfurls
+    // public URLs; not acceptable as the only guard. Hence the redirect-checked
+    // path for OpenGraph and the image, which are the two fetches we control.
     const d = await oembedExtract(url, {}, { signal: AbortSignal.timeout(FETCH_MS) })
     if (!d) return null
     return {
@@ -145,7 +185,11 @@ const fromOembed = async url => {
 
 const fromOpenGraph = async url => {
   try {
-    const r = await ogs({ url, fetchOptions: { signal: AbortSignal.timeout(FETCH_MS) } })
+    // Walk redirects ourselves so every hop is checked, then hand the library
+    // the final URL with redirects off. It cannot be led anywhere we did not look.
+    const probe = await safeFetch(url, { method: 'GET', signal: AbortSignal.timeout(FETCH_MS) })
+    const finalUrl = probe.url || url
+    const r = await ogs({ url: finalUrl, fetchOptions: { signal: AbortSignal.timeout(FETCH_MS), redirect: 'manual' } })
     if (!r || r.error || !r.result) return null
     const x = r.result
     const img =