npm - @syengup/friday-channel-next - Versions diffs - 0.1.27 → 0.1.29 - Mend

@syengup/friday-channel-next 0.1.27 → 0.1.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/dist/src/http/handlers/files.js +1 -0
package/dist/src/http/handlers/link-preview.d.ts +9 -0
package/dist/src/http/handlers/link-preview.js +41 -0
package/dist/src/http/server.js +5 -0
package/dist/src/link-preview/og-parse.d.ts +21 -0
package/dist/src/link-preview/og-parse.js +232 -0
package/dist/src/link-preview/preview-service.d.ts +31 -0
package/dist/src/link-preview/preview-service.js +216 -0
package/dist/src/link-preview/ssrf-guard.d.ts +43 -0
package/dist/src/link-preview/ssrf-guard.js +223 -0
package/dist/src/plugin-install-info.d.ts +23 -4
package/dist/src/plugin-install-info.js +29 -6
package/dist/src/upgrade-runtime.d.ts +6 -0
package/dist/src/upgrade-runtime.js +1 -0
package/dist/src/version.js +1 -1
package/package.json +1 -1
package/src/http/handlers/files.ts +1 -0
package/src/http/handlers/link-preview.test.ts +242 -0
package/src/http/handlers/link-preview.ts +47 -0
package/src/http/server.ts +6 -0
package/src/link-preview/og-parse.test.ts +168 -0
package/src/link-preview/og-parse.ts +249 -0
package/src/link-preview/preview-service.ts +247 -0
package/src/link-preview/ssrf-guard.test.ts +234 -0
package/src/link-preview/ssrf-guard.ts +229 -0
package/src/plugin-install-info.test.ts +31 -1
package/src/plugin-install-info.ts +29 -6
package/src/upgrade-runtime.ts +7 -0
package/src/version.ts +1 -1

package/src/link-preview/og-parse.test.ts ADDED Viewed

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import { decodeHtmlEntities, parseOpenGraph } from "./og-parse.js";
+const BASE = "https://example.com/article/42";
+describe("decodeHtmlEntities", () => {
+  it("decodes named, decimal, and hex entities", () => {
+    expect(decodeHtmlEntities("Tom &amp; Jerry &mdash; &quot;fun&quot;")).toBe('Tom & Jerry — "fun"');
+    expect(decodeHtmlEntities("&#20013;&#25991;")).toBe("中文");
+    expect(decodeHtmlEntities("&#x27;quoted&#x27;")).toBe("'quoted'");
+  });
+  it("leaves unknown entities untouched", () => {
+    expect(decodeHtmlEntities("&unknownentity; stays")).toBe("&unknownentity; stays");
+  });
+});
+describe("parseOpenGraph", () => {
+  it("extracts the standard og tags", () => {
+    const html = `<html><head>
+      <meta property="og:title" content="Hello World" />
+      <meta property="og:description" content="A page about things" />
+      <meta property="og:image" content="https://cdn.example.com/cover.jpg" />
+      <meta property="og:site_name" content="Example" />
+    </head><body></body></html>`;
+    expect(parseOpenGraph(html, BASE)).toEqual({
+      title: "Hello World",
+      description: "A page about things",
+      imageUrl: "https://cdn.example.com/cover.jpg",
+      siteName: "Example",
+      iconUrl: null,
+    });
+  });
+  it("handles name= variant, swapped attribute order, and single quotes", () => {
+    const html = `
+      <meta content="Swapped" property="og:title">
+      <meta name='og:description' content='Single quoted'>
+    `;
+    const result = parseOpenGraph(html, BASE);
+    expect(result.title).toBe("Swapped");
+    expect(result.description).toBe("Single quoted");
+  });
+  it("first occurrence wins for duplicate og tags", () => {
+    const html = `
+      <meta property="og:title" content="First">
+      <meta property="og:title" content="Second">
+    `;
+    expect(parseOpenGraph(html, BASE).title).toBe("First");
+  });
+  it("falls back to <title> and meta description", () => {
+    const html = `<html><head>
+      <title>  Fallback   Title </title>
+      <meta name="description" content="Fallback description">
+    </head></html>`;
+    const result = parseOpenGraph(html, BASE);
+    expect(result.title).toBe("Fallback Title");
+    expect(result.description).toBe("Fallback description");
+  });
+  it("decodes entities and collapses whitespace in text fields", () => {
+    const html = `<meta property="og:title" content="Q&amp;A:&#x20;What&#39;s
+      new">`;
+    expect(parseOpenGraph(html, BASE).title).toBe("Q&A: What's new");
+  });
+  it("resolves a relative og:image against the page URL", () => {
+    const html = `<meta property="og:image" content="/img/cover.png">`;
+    expect(parseOpenGraph(html, BASE).imageUrl).toBe("https://example.com/img/cover.png");
+  });
+  it("drops non-http og:image values", () => {
+    const html = `<meta property="og:image" content="data:image/png;base64,AAAA">`;
+    expect(parseOpenGraph(html, BASE).imageUrl).toBeNull();
+  });
+  it("returns nulls for a page with no usable metadata", () => {
+    expect(parseOpenGraph("<html><body>plain</body></html>", BASE)).toEqual({
+      title: null,
+      description: null,
+      imageUrl: null,
+      siteName: null,
+      iconUrl: null,
+    });
+  });
+  it("extracts and resolves a favicon, preferring apple-touch-icon, skipping mask-icon", () => {
+    const html = `<head>
+      <link rel="mask-icon" href="/safari.svg" color="#000">
+      <link rel="icon" type="image/png" href="/favicon-32.png">
+      <link rel="apple-touch-icon" href="https://cdn.example.com/touch.png">
+    </head>`;
+    expect(parseOpenGraph(html, BASE).iconUrl).toBe("https://cdn.example.com/touch.png");
+  });
+  it("falls back to a regular icon link and resolves relative hrefs", () => {
+    const html = `<link rel="shortcut icon" href="/static/fav.ico">`;
+    expect(parseOpenGraph(html, BASE).iconUrl).toBe("https://example.com/static/fav.ico");
+  });
+  it("returns null icon when only a mask-icon is present", () => {
+    expect(parseOpenGraph(`<link rel="mask-icon" href="/m.svg">`, BASE).iconUrl).toBeNull();
+  });
+  it("falls back to twitter card tags when og is absent", () => {
+    const html = `
+      <meta name="twitter:title" content="TW Title">
+      <meta name="twitter:description" content="TW Desc">
+      <meta name="twitter:image" content="https://cdn.example.com/tw.jpg">
+    `;
+    const r = parseOpenGraph(html, BASE);
+    expect(r.title).toBe("TW Title");
+    expect(r.description).toBe("TW Desc");
+    expect(r.imageUrl).toBe("https://cdn.example.com/tw.jpg");
+  });
+  it("falls back to JSON-LD (headline/description/image, incl. @graph and ImageObject)", () => {
+    const html = `<script type="application/ld+json">
+      {"@context":"https://schema.org","@graph":[
+        {"@type":"NewsArticle","headline":"LD Headline","description":"LD Desc",
+         "image":{"@type":"ImageObject","url":"https://cdn.example.com/ld.jpg"}}
+      ]}
+    </script>`;
+    const r = parseOpenGraph(html, BASE);
+    expect(r.title).toBe("LD Headline");
+    expect(r.description).toBe("LD Desc");
+    expect(r.imageUrl).toBe("https://cdn.example.com/ld.jpg");
+  });
+  it("prefers a body article-title over a generic <title> (QQ-style SPA shell)", () => {
+    const html = `<head><title>搜索资讯页</title></head>
+      <body><div class="article-wrapper"><div class="article-title">钉钉"两篇大作文"事件——离职副总裁万字长文</div></div></body>`;
+    expect(parseOpenGraph(html, BASE).title).toBe('钉钉"两篇大作文"事件——离职副总裁万字长文');
+  });
+  it("prefers an <h1> over a generic <title>", () => {
+    const html = `<title>Home</title><h1>The Real Headline</h1>`;
+    expect(parseOpenGraph(html, BASE).title).toBe("The Real Headline");
+  });
+  it("extracts a cover image from inline JSON (extensionless, escaped slashes)", () => {
+    const html = `<title>搜索资讯页</title>
+      <script>window.__INFO__={"imgUrl":"http:\\/\\/qqpublic.qpic.cn\\/qq_public_cover\\/0\\/0-2342_op"}</script>`;
+    expect(parseOpenGraph(html, BASE).imageUrl).toBe("http://qqpublic.qpic.cn/qq_public_cover/0/0-2342_op");
+  });
+  it("standard og tags still win over body/json fallbacks", () => {
+    const html = `<meta property="og:title" content="OG Wins">
+      <h1>Body H1</h1>
+      <div class="article-title">Body Title</div>`;
+    expect(parseOpenGraph(html, BASE).title).toBe("OG Wins");
+  });
+  it("does not throw on malformed or truncated HTML", () => {
+    expect(() => parseOpenGraph(`<meta property="og:title" content="Trunc`, BASE)).not.toThrow();
+    expect(() => parseOpenGraph("<<<>>><meta<meta>", BASE)).not.toThrow();
+  });
+  it("ignores empty content values", () => {
+    const html = `<meta property="og:title" content="">
+      <title>Real Title</title>`;
+    // og:title 占位为空串 → cleanText 归 null,但 og map 已记录空串;回退逻辑应仍给出可用 title
+    const result = parseOpenGraph(html, BASE);
+    expect(result.title).toBe("Real Title");
+  });
+});

package/src/link-preview/og-parse.ts ADDED Viewed

@@ -0,0 +1,249 @@
+/**
+ * Open Graph metadata extraction via regex — no HTML parser dependency.
+ *
+ * Good enough for the link-preview card use case: og:* meta tags are flat, attribute-ordered
+ * variants are handled generically, and pages where this fails simply degrade to "no card".
+ */
+const MAX_PARSE_BYTES = 512 * 1024;
+export interface OpenGraphResult {
+  title: string | null;
+  description: string | null;
+  imageUrl: string | null;
+  siteName: string | null;
+  /** Favicon URL parsed from `<link rel="...icon...">`, resolved absolute. */
+  iconUrl: string | null;
+}
+const META_TAG_RE = /<meta\b[^>]*>/gi;
+const TITLE_TAG_RE = /<title[^>]*>([\s\S]*?)<\/title>/i;
+const LINK_TAG_RE = /<link\b[^>]*>/gi;
+/** Extract one attribute value from a tag, tolerating single/double/no quotes and any order. */
+function attributeValue(tag: string, name: string): string | null {
+  const re = new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'>]+))`, "i");
+  const m = tag.match(re);
+  if (!m) return null;
+  return m[1] ?? m[2] ?? m[3] ?? "";
+}
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  ndash: "–",
+  mdash: "—",
+  hellip: "…",
+  middot: "·",
+  copy: "©",
+  reg: "®",
+  trade: "™",
+  lsquo: "‘",
+  rsquo: "’",
+  ldquo: "“",
+  rdquo: "”",
+  laquo: "«",
+  raquo: "»",
+};
+export function decodeHtmlEntities(s: string): string {
+  return s.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (whole, body: string) => {
+    if (body.startsWith("#x") || body.startsWith("#X")) {
+      const code = Number.parseInt(body.slice(2), 16);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+    }
+    if (body.startsWith("#")) {
+      const code = Number.parseInt(body.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+    }
+    return NAMED_ENTITIES[body.toLowerCase()] ?? whole;
+  });
+}
+function cleanText(raw: string | null | undefined): string | null {
+  if (raw == null) return null;
+  const text = decodeHtmlEntities(raw).replace(/\s+/g, " ").trim();
+  return text || null;
+}
+/** Resolve og:image (possibly relative) against the final page URL; only http(s) survives. */
+function resolveImageUrl(raw: string | null | undefined, baseUrl: string): string | null {
+  if (!raw) return null;
+  try {
+    const url = new URL(raw.trim(), baseUrl);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+export function parseOpenGraph(html: string, baseUrl: string): OpenGraphResult {
+  const slice = html.length > MAX_PARSE_BYTES ? html.slice(0, MAX_PARSE_BYTES) : html;
+  // First occurrence wins per key (matches browser/crawler behavior).
+  const og: Record<string, string> = {};
+  const tw: Record<string, string> = {};
+  let metaDescription: string | null = null;
+  for (const match of slice.matchAll(META_TAG_RE)) {
+    const tag = match[0];
+    const key = (attributeValue(tag, "property") ?? attributeValue(tag, "name"))?.trim().toLowerCase();
+    if (!key) continue;
+    const content = attributeValue(tag, "content");
+    if (content == null || !content.trim()) continue;
+    if (key.startsWith("og:")) {
+      const ogKey = key.slice(3);
+      if (!(ogKey in og)) og[ogKey] = content;
+    } else if (key.startsWith("twitter:")) {
+      const twKey = key.slice(8);
+      if (!(twKey in tw)) tw[twKey] = content;
+    } else if (key === "description" && metaDescription == null) {
+      metaDescription = content;
+    }
+  }
+  const ld = parseJsonLd(slice);
+  const pageTitle = slice.match(TITLE_TAG_RE)?.[1] ?? null;
+  // Title chain: standard tags first, then server-rendered body title (h1 / article-title class)
+  // BEFORE the generic <title> — many SPA/news shells put a useless <title> ("搜索资讯页") in the
+  // head while the real headline lives in the body.
+  const title =
+    cleanText(og["title"]) ??
+    cleanText(tw["title"]) ??
+    cleanText(ld.title) ??
+    cleanText(parseBodyTitle(slice)) ??
+    cleanText(pageTitle);
+  const description =
+    cleanText(og["description"]) ??
+    cleanText(tw["description"]) ??
+    cleanText(ld.description) ??
+    cleanText(metaDescription);
+  const imageUrl =
+    resolveImageUrl(og["image"] ?? null, baseUrl) ??
+    resolveImageUrl(tw["image"] ?? null, baseUrl) ??
+    resolveImageUrl(ld.image, baseUrl) ??
+    resolveImageUrl(parseBodyCoverImage(slice), baseUrl);
+  return {
+    title,
+    description,
+    imageUrl,
+    siteName: cleanText(og["site_name"] ?? tw["site"] ?? null),
+    iconUrl: parseFaviconUrl(slice, baseUrl),
+  };
+}
+const JSON_LD_RE = /<script[^>]*type\s*=\s*["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+/** Extract title/description/image from JSON-LD blocks (schema.org Article/NewsArticle/etc.). */
+function parseJsonLd(html: string): { title: string | null; description: string | null; image: string | null } {
+  for (const match of html.matchAll(JSON_LD_RE)) {
+    let data: unknown;
+    try {
+      data = JSON.parse(match[1].trim());
+    } catch {
+      continue;
+    }
+    // JSON-LD may be a single object, an array, or a @graph container.
+    const nodes: unknown[] = Array.isArray(data)
+      ? data
+      : isRecord(data) && Array.isArray(data["@graph"])
+        ? (data["@graph"] as unknown[])
+        : [data];
+    for (const node of nodes) {
+      if (!isRecord(node)) continue;
+      const title = asString(node.headline) ?? asString(node.name);
+      const description = asString(node.description);
+      const image = firstImage(node.image) ?? asString(node.thumbnailUrl);
+      if (title || description || image) {
+        return { title: title ?? null, description: description ?? null, image: image ?? null };
+      }
+    }
+  }
+  return { title: null, description: null, image: null };
+}
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+function asString(v: unknown): string | null {
+  return typeof v === "string" && v.trim() ? v : null;
+}
+/** JSON-LD `image` is a string, an array, or an ImageObject `{ url }`. */
+function firstImage(v: unknown): string | null {
+  if (typeof v === "string") return v;
+  if (Array.isArray(v)) {
+    for (const item of v) {
+      const found = firstImage(item);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (isRecord(v)) return asString(v.url);
+  return null;
+}
+// Common server-rendered article-title class names (whitelist keeps false positives down vs. any
+// class containing "title", e.g. a sidebar "related-titles" block).
+const BODY_TITLE_CLASS_RE =
+  /class\s*=\s*["'][^"']*\b(?:article-title|post-title|entry-title|news-title|content-title|headline|title-text)\b[^"']*["'][^>]*>\s*([^<]{4,200}?)\s*</i;
+const H1_RE = /<h1\b[^>]*>\s*([\s\S]{4,200}?)\s*<\/h1>/i;
+/** Server-rendered headline fallback: first <h1>, else an element with a known article-title class. */
+function parseBodyTitle(html: string): string | null {
+  const h1 = html.match(H1_RE)?.[1];
+  if (h1) {
+    const text = stripTags(h1).trim();
+    if (text.length >= 4) return text;
+  }
+  return html.match(BODY_TITLE_CLASS_RE)?.[1] ?? null;
+}
+// Cover image embedded in inline JSON (e.g. QQ's `"imgUrl":"http:\/\/...cover..."`). The URL may be
+// extensionless; the re-host step's magic-byte sniff is the safety net against non-image matches.
+const JSON_COVER_RE =
+  /"(?:imgUrl|imageUrl|coverUrl|coverImage|cover|ogImage|thumbnail|picUrl)"\s*:\s*"(https?:(?:\\?\/){2}[^"]+?)"/i;
+/** Cover image from inline JSON when no og/twitter/json-ld image is present. */
+function parseBodyCoverImage(html: string): string | null {
+  const raw = html.match(JSON_COVER_RE)?.[1];
+  if (!raw) return null;
+  return raw.replace(/\\\//g, "/"); // unescape JSON `\/`
+}
+function stripTags(s: string): string {
+  return s.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ");
+}
+/**
+ * Pick the best `<link rel="...icon...">` href. Prefers a high-res `apple-touch-icon`, then a
+ * regular `icon` / `shortcut icon`. Skips `mask-icon` (monochrome SVG). Returns absolute http(s).
+ */
+export function parseFaviconUrl(html: string, baseUrl: string): string | null {
+  let appleTouch: string | null = null;
+  let regular: string | null = null;
+  for (const match of html.matchAll(LINK_TAG_RE)) {
+    const tag = match[0];
+    const rel = attributeValue(tag, "rel")?.trim().toLowerCase();
+    if (!rel || !rel.includes("icon") || rel.includes("mask-icon")) continue;
+    const href = attributeValue(tag, "href");
+    if (!href) continue;
+    const resolved = resolveImageUrl(href, baseUrl);
+    if (!resolved) continue;
+    if (rel.includes("apple-touch-icon")) {
+      appleTouch ??= resolved;
+    } else {
+      regular ??= resolved;
+    }
+  }
+  return appleTouch ?? regular;
+}

package/src/link-preview/preview-service.ts ADDED Viewed

@@ -0,0 +1,247 @@
+/**
+ * Link-preview orchestration: fetch page → parse Open Graph → re-host the cover image through
+ * the gateway's stored files → cache.
+ *
+ * The cover image is downloaded server-side and served from /friday-next/files/ so the app only
+ * ever talks to the trusted gateway host (same rationale as `downloadRemoteMedia` for outbound
+ * media). Failures degrade to "no card" on the app side, so every error path returns a typed
+ * error instead of throwing.
+ */
+import { createFridayNextLogger } from "../logging.js";
+import { storeFile } from "../http/handlers/files.js";
+import { parseOpenGraph } from "./og-parse.js";
+import { BlockedUrlError, fetchPublicUrl, parseHttpUrl } from "./ssrf-guard.js";
+const HTML_MAX_BYTES = 2 * 1024 * 1024;
+const HTML_TIMEOUT_MS = 10_000;
+const IMAGE_MAX_BYTES = 8 * 1024 * 1024;
+const IMAGE_TIMEOUT_MS = 10_000;
+const SUCCESS_TTL_MS = 24 * 60 * 60 * 1000;
+const FAILURE_TTL_MS = 10 * 60 * 1000;
+const MAX_CACHE_ENTRIES = 1000;
+const logger = createFridayNextLogger("link-preview");
+export interface LinkPreviewPayload {
+  url: string;
+  finalUrl: string;
+  siteName: string | null;
+  title: string;
+  description: string | null;
+  /** Gateway-relative cover URL ("/friday-next/files/{token}") or null. */
+  imageUrl: string | null;
+  /** Gateway-relative favicon URL ("/friday-next/files/{token}") or null. */
+  iconUrl: string | null;
+  fetchedAt: number;
+}
+export type LinkPreviewError = "invalid_url" | "blocked_url" | "fetch_failed" | "no_metadata";
+export type LinkPreviewResult =
+  | { ok: true; preview: LinkPreviewPayload }
+  | { ok: false; error: LinkPreviewError };
+interface CacheEntry {
+  result: LinkPreviewResult;
+  cachedAt: number;
+}
+const cache = new Map<string, CacheEntry>();
+const inFlight = new Map<string, Promise<LinkPreviewResult>>();
+export function resetLinkPreviewCacheForTest(): void {
+  cache.clear();
+  inFlight.clear();
+}
+export async function getLinkPreview(rawUrl: string): Promise<LinkPreviewResult> {
+  const parsed = parseHttpUrl(rawUrl);
+  if (!parsed) return { ok: false, error: "invalid_url" };
+  const key = parsed.toString();
+  const cached = cache.get(key);
+  if (cached) {
+    const ttl = cached.result.ok ? SUCCESS_TTL_MS : FAILURE_TTL_MS;
+    if (Date.now() - cached.cachedAt < ttl) return cached.result;
+    cache.delete(key);
+  }
+  const pending = inFlight.get(key);
+  if (pending) return pending;
+  const task = buildPreview(key)
+    .then((result) => {
+      writeCache(key, result);
+      return result;
+    })
+    .finally(() => {
+      inFlight.delete(key);
+    });
+  inFlight.set(key, task);
+  return task;
+}
+function writeCache(key: string, result: LinkPreviewResult): void {
+  if (cache.size >= MAX_CACHE_ENTRIES) {
+    let oldestKey: string | null = null;
+    let oldestAt = Infinity;
+    for (const [k, entry] of cache) {
+      if (entry.cachedAt < oldestAt) {
+        oldestAt = entry.cachedAt;
+        oldestKey = k;
+      }
+    }
+    if (oldestKey) cache.delete(oldestKey);
+  }
+  cache.set(key, { result, cachedAt: Date.now() });
+}
+async function buildPreview(pageUrl: string): Promise<LinkPreviewResult> {
+  let page;
+  try {
+    page = await fetchPublicUrl(pageUrl, {
+      maxBytes: HTML_MAX_BYTES,
+      timeoutMs: HTML_TIMEOUT_MS,
+      accept: "text/html,application/xhtml+xml",
+      requireContentTypePrefixes: ["text/html", "application/xhtml+xml"],
+    });
+  } catch (err) {
+    if (err instanceof BlockedUrlError) {
+      logger.warn(`link-preview blocked: ${pageUrl} (${err.reason})`);
+      return { ok: false, error: "blocked_url" };
+    }
+    page = null; // network/timeout — fall through to a favicon-only minimal card
+  }
+  const finalUrl = page?.finalUrl ?? pageUrl;
+  const og = page ? parseOpenGraph(page.body.toString("utf8"), finalUrl) : null;
+  const hostname = (() => {
+    try {
+      return new URL(finalUrl).hostname;
+    } catch {
+      return null;
+    }
+  })();
+  // Favicon: parsed <link rel icon> first, then the conventional /favicon.ico (which is reachable
+  // even for pages that block bots, e.g. zhihu → redirects to its CDN icon).
+  const iconUrl = await resolveFavicon(og?.iconUrl ?? null, finalUrl);
+  // A failed page fetch only yields a (minimal) card when the favicon resolved — that proves the
+  // domain is real/reachable (e.g. bot-blocked zhihu). A dead domain (favicon also fails) collapses.
+  const reachable = page !== null || iconUrl !== null;
+  const title = og?.title ?? hostname;
+  if (!reachable || !title) {
+    return { ok: false, error: page ? "no_metadata" : "fetch_failed" };
+  }
+  const imageUrl = og?.imageUrl ? await rehostCoverImage(og.imageUrl) : null;
+  return {
+    ok: true,
+    preview: {
+      url: pageUrl,
+      finalUrl,
+      siteName: og?.siteName ?? hostname,
+      title: title ?? hostname ?? pageUrl,
+      description: og?.description ?? null,
+      imageUrl,
+      iconUrl,
+      fetchedAt: Date.now(),
+    },
+  };
+}
+/** Re-host a favicon: try the parsed `<link rel icon>`, then `<origin>/favicon.ico`. */
+async function resolveFavicon(parsedIconUrl: string | null, finalUrl: string): Promise<string | null> {
+  const candidates: string[] = [];
+  if (parsedIconUrl) candidates.push(parsedIconUrl);
+  try {
+    candidates.push(new URL("/favicon.ico", finalUrl).toString());
+  } catch {
+    // finalUrl unparseable — skip the conventional fallback
+  }
+  for (const candidate of candidates) {
+    const rehosted = await rehostIconImage(candidate);
+    if (rehosted) return rehosted;
+  }
+  return null;
+}
+/** Download a favicon (full SSRF checks) and re-publish via stored files. Null on any failure. */
+async function rehostIconImage(iconUrl: string): Promise<string | null> {
+  let image;
+  try {
+    image = await fetchPublicUrl(iconUrl, {
+      maxBytes: 1024 * 1024,
+      timeoutMs: IMAGE_TIMEOUT_MS,
+      accept: "image/*",
+      requireContentTypePrefixes: ["image/"],
+    });
+  } catch {
+    return null;
+  }
+  if (!image) return null;
+  const sniffed = sniffImageType(image.body);
+  if (!sniffed) return null;
+  try {
+    const stored = storeFile(image.body, `link-preview-icon.${sniffed.ext}`, sniffed.mime);
+    return `/friday-next/files/${encodeURIComponent(stored.urlToken)}`;
+  } catch {
+    return null;
+  }
+}
+/** Download og:image (full SSRF checks) and re-publish via stored files. Null on any failure. */
+async function rehostCoverImage(imageUrl: string): Promise<string | null> {
+  let image;
+  try {
+    image = await fetchPublicUrl(imageUrl, {
+      maxBytes: IMAGE_MAX_BYTES,
+      timeoutMs: IMAGE_TIMEOUT_MS,
+      accept: "image/*",
+      requireContentTypePrefixes: ["image/"],
+    });
+  } catch {
+    return null; // blocked og:image just means no cover
+  }
+  if (!image) return null;
+  const sniffed = sniffImageType(image.body);
+  if (!sniffed) return null;
+  try {
+    const stored = storeFile(image.body, `link-preview-cover.${sniffed.ext}`, sniffed.mime);
+    return `/friday-next/files/${encodeURIComponent(stored.urlToken)}`;
+  } catch (err) {
+    logger.warn(`link-preview cover store failed for ${imageUrl}: ${String(err)}`);
+    return null;
+  }
+}
+/** Magic-byte sniff — second line of defense after the Content-Type check. */
+function sniffImageType(buffer: Buffer): { ext: string; mime: string } | null {
+  if (buffer.length < 12) return null;
+  // ICO: 00 00 01 00 (favicons are commonly .ico; iOS ImageIO decodes them).
+  if (buffer[0] === 0x00 && buffer[1] === 0x00 && buffer[2] === 0x01 && buffer[3] === 0x00) {
+    return { ext: "ico", mime: "image/x-icon" };
+  }
+  if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
+    return { ext: "png", mime: "image/png" };
+  }
+  if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+    return { ext: "jpg", mime: "image/jpeg" };
+  }
+  if (buffer.subarray(0, 4).toString("latin1") === "GIF8") {
+    return { ext: "gif", mime: "image/gif" };
+  }
+  if (
+    buffer.subarray(0, 4).toString("latin1") === "RIFF" &&
+    buffer.subarray(8, 12).toString("latin1") === "WEBP"
+  ) {
+    return { ext: "webp", mime: "image/webp" };
+  }
+  return null;
+}