@syengup/friday-channel-next 0.1.27 → 0.1.29

package/dist/src/link-preview/ssrf-guard.js

@@ -0,0 +1,223 @@
+/**
+ * SSRF guard + restricted fetch for the link-preview endpoint.
+ *
+ * Unlike `downloadRemoteMedia` (agent-supplied URLs for outbound media), link-preview fetches
+ * URLs that originate from arbitrary message text, so every hop must be validated: protocol,
+ * port, hostname literals, and the full set of DNS-resolved addresses. Redirects are followed
+ * manually so each target is re-checked before the next request.
+ *
+ * Known residual risk: DNS rebinding TOCTOU — we validate resolved addresses, then `fetch`
+ * resolves again. Closing that gap requires dialing by IP with SNI/Host rewriting, which is
+ * disproportionate for preview metadata; accepted at this threat level.
+ */
+import dns from "node:dns/promises";
+import net from "node:net";
+const MAX_REDIRECTS = 5;
+export class BlockedUrlError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Blocked URL: ${reason}`);
+        this.name = "BlockedUrlError";
+        this.reason = reason;
+    }
+}
+/** Parse an absolute http/https URL. Returns null for anything else (caller maps to invalid_url). */
+export function parseHttpUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return null;
+    return url;
+}
+const BLOCKED_HOST_SUFFIXES = [".local", ".internal", ".home.arpa", ".localhost"];
+/** Synchronous literal checks: port, hostname blocklist, IP-literal hosts. Throws BlockedUrlError. */
+export function assertPublicHttpUrl(url) {
+    if (url.port && url.port !== "80" && url.port !== "443") {
+        throw new BlockedUrlError(`port ${url.port} not allowed`);
+    }
+    const host = url.hostname.toLowerCase().replace(/\.$/, "");
+    if (!host)
+        throw new BlockedUrlError("empty host");
+    if (host === "localhost" || BLOCKED_HOST_SUFFIXES.some((s) => host.endsWith(s))) {
+        throw new BlockedUrlError(`host "${host}" is not public`);
+    }
+    // IPv6 literal in a URL comes bracketed: strip for net.isIP.
+    const bareHost = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+    if (net.isIP(bareHost) && isPrivateAddress(bareHost)) {
+        throw new BlockedUrlError(`address ${bareHost} is private/reserved`);
+    }
+}
+/** True when the IP (v4 or v6, including ::ffff: mapped v4) is private, loopback, or reserved. */
+export function isPrivateAddress(ip) {
+    const version = net.isIP(ip);
+    if (version === 4)
+        return isPrivateIPv4(ip);
+    if (version === 6)
+        return isPrivateIPv6(ip);
+    return true; // not an IP at all — treat as unsafe
+}
+function isPrivateIPv4(ip) {
+    const parts = ip.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return true;
+    const [a, b] = parts;
+    if (a === 0)
+        return true; // 0.0.0.0/8
+    if (a === 10)
+        return true; // 10/8
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64/10 CGNAT
+    if (a === 127)
+        return true; // loopback
+    if (a === 169 && b === 254)
+        return true; // link-local
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16/12
+    if (a === 192 && b === 0 && parts[2] === 0)
+        return true; // 192.0.0/24
+    if (a === 192 && b === 168)
+        return true; // 192.168/16
+    // 198.18/15 (benchmarking) intentionally NOT blocked: fake-IP DNS setups (clash/surge tun
+    // mode, common on gateway hosts) resolve EVERY domain into this range, so blocking it kills
+    // all lookups. The range is not used for real LAN services, so the SSRF exposure is nil.
+    if (a >= 224)
+        return true; // multicast 224/4 + reserved 240/4 + broadcast
+    return false;
+}
+function isPrivateIPv6(ip) {
+    const lower = ip.toLowerCase();
+    // ::ffff:a.b.c.d mapped IPv4 → validate the embedded v4.
+    const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped)
+        return isPrivateIPv4(mapped[1]);
+    if (lower === "::" || lower === "::1")
+        return true; // unspecified / loopback
+    const head = lower.split(":")[0];
+    if (head.startsWith("fc") || head.startsWith("fd"))
+        return true; // fc00::/7 ULA
+    if (/^fe[89ab]/.test(head))
+        return true; // fe80::/10 link-local
+    return false;
+}
+/** Resolve the hostname and require every returned address to be public. Throws BlockedUrlError. */
+export async function assertResolvesPublic(url) {
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (net.isIP(host)) {
+        if (isPrivateAddress(host))
+            throw new BlockedUrlError(`address ${host} is private/reserved`);
+        return;
+    }
+    let addresses;
+    try {
+        addresses = await dns.lookup(host, { all: true, verbatim: true });
+    }
+    catch {
+        throw new Error(`DNS lookup failed for ${host}`);
+    }
+    if (!addresses.length)
+        throw new Error(`DNS lookup returned no addresses for ${host}`);
+    for (const { address } of addresses) {
+        if (isPrivateAddress(address)) {
+            throw new BlockedUrlError(`${host} resolves to private/reserved address ${address}`);
+        }
+    }
+}
+const PREVIEW_USER_AGENT = "Mozilla/5.0 (compatible; OpenClawLinkPreview/1.0)";
+/**
+ * Fetch a public http/https URL with manual redirects (≤5 hops, each hop re-validated) and a
+ * streamed size cap (Content-Length is not trusted). Returns null on ordinary failures (non-2xx,
+ * oversize, timeout, bad content type, DNS error); throws BlockedUrlError on SSRF rejection.
+ */
+export async function fetchPublicUrl(rawUrl, opts) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+    try {
+        let current = rawUrl;
+        for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+            const url = parseHttpUrl(current);
+            if (!url)
+                return null;
+            assertPublicHttpUrl(url);
+            await assertResolvesPublic(url);
+            const res = await fetch(url, {
+                redirect: "manual",
+                signal: controller.signal,
+                headers: {
+                    "User-Agent": PREVIEW_USER_AGENT,
+                    ...(opts.accept ? { Accept: opts.accept } : {}),
+                },
+            });
+            if (res.status >= 300 && res.status < 400) {
+                const location = res.headers.get("location");
+                await res.body?.cancel().catch(() => { });
+                if (!location)
+                    return null;
+                try {
+                    current = new URL(location, url).toString();
+                }
+                catch {
+                    return null;
+                }
+                continue;
+            }
+            if (!res.ok) {
+                await res.body?.cancel().catch(() => { });
+                return null;
+            }
+            const contentType = res.headers.get("content-type")?.trim().toLowerCase() ?? "";
+            if (opts.requireContentTypePrefixes &&
+                !opts.requireContentTypePrefixes.some((p) => contentType.startsWith(p))) {
+                await res.body?.cancel().catch(() => { });
+                return null;
+            }
+            const body = await readBodyCapped(res, opts.maxBytes);
+            if (body === null)
+                return null;
+            return { finalUrl: url.toString(), contentType, body };
+        }
+        return null; // too many redirects
+    }
+    catch (err) {
+        if (err instanceof BlockedUrlError)
+            throw err;
+        return null; // timeout / network / DNS failure
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Stream the response body, aborting once it exceeds maxBytes. */
+async function readBodyCapped(res, maxBytes) {
+    if (!res.body) {
+        const buffer = Buffer.from(await res.arrayBuffer());
+        return buffer.length <= maxBytes ? buffer : null;
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                total += value.byteLength;
+                if (total > maxBytes) {
+                    await reader.cancel().catch(() => { });
+                    return null;
+                }
+                chunks.push(Buffer.from(value));
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    const buffer = Buffer.concat(chunks);
+    return buffer.length ? buffer : null;
+}

package/dist/src/plugin-install-info.d.ts

@@ -1,10 +1,29 @@
 /** Install source from the OpenClaw config `plugins.installs[<id>].source`. */
 export type InstallSource = "npm" | "path" | "archive" | "clawhub" | "git" | "marketplace" | "unknown";
 /**
- * Read the install source for this plugin from the live config snapshot.
- * Returns "unknown" when the record can't be resolved (e.g. runtime not captured).
- * Only "npm" is auto-upgradable; "path" means a dev (load.paths) install which must
- * never be npm-upgraded (would duplicate-install and break agent media sends).
+ * Infer the install source from the loaded plugin's filesystem path (`api.source`).
+ *
+ * OpenClaw copies non-dev installs (npm/archive/clawhub/git) into
+ * `~/.openclaw/npm/projects/<hash>/node_modules/...`, whereas a dev install
+ * (`load.paths` / `plugins install --link`) is loaded directly from the source
+ * checkout. For this plugin's purposes the only distinction that matters is
+ * npm-managed (auto-upgradable) vs dev (must never npm-upgrade — see
+ * dev-no-duplicate-plugin-install), so anything under the managed projects dir
+ * is treated as "npm".
+ */
+export declare function classifyInstallSourceFromLoadedPath(loadedPath: string | null | undefined): InstallSource;
+/**
+ * Resolve the install source for this plugin (npm vs dev path).
+ * Returns "unknown" when it can't be resolved (e.g. runtime not captured).
+ * Only "npm" is auto-upgradable; "path" means a dev (load.paths / --link) install
+ * which must never be npm-upgraded (would duplicate-install and break agent media sends).
+ *
+ * Resolution order:
+ *  1. The explicit `plugins.installs[<id>].source` config record — present on older
+ *     OpenClaw builds that surface install records in the runtime config snapshot.
+ *  2. Fallback: OpenClaw 2026.6.x moved install records out of the config snapshot
+ *     into a separate registry (~/.openclaw/state.db), leaving `plugins.installs`
+ *     unset — so infer from the loaded plugin path (`api.source`) instead.
  */
 export declare function getInstallSource(): InstallSource;
 /** Compare dotted numeric versions. Returns true if `a` is strictly greater than `b`. */

package/dist/src/plugin-install-info.js

@@ -6,10 +6,33 @@
 import { getUpgradeRuntime } from "./upgrade-runtime.js";
 import { PLUGIN_ID, PLUGIN_PACKAGE_NAME } from "./version.js";
 /**
- * Read the install source for this plugin from the live config snapshot.
- * Returns "unknown" when the record can't be resolved (e.g. runtime not captured).
- * Only "npm" is auto-upgradable; "path" means a dev (load.paths) install which must
- * never be npm-upgraded (would duplicate-install and break agent media sends).
+ * Infer the install source from the loaded plugin's filesystem path (`api.source`).
+ *
+ * OpenClaw copies non-dev installs (npm/archive/clawhub/git) into
+ * `~/.openclaw/npm/projects/<hash>/node_modules/...`, whereas a dev install
+ * (`load.paths` / `plugins install --link`) is loaded directly from the source
+ * checkout. For this plugin's purposes the only distinction that matters is
+ * npm-managed (auto-upgradable) vs dev (must never npm-upgrade — see
+ * dev-no-duplicate-plugin-install), so anything under the managed projects dir
+ * is treated as "npm".
+ */
+export function classifyInstallSourceFromLoadedPath(loadedPath) {
+    if (!loadedPath)
+        return "unknown";
+    return loadedPath.includes("/.openclaw/npm/projects/") ? "npm" : "path";
+}
+/**
+ * Resolve the install source for this plugin (npm vs dev path).
+ * Returns "unknown" when it can't be resolved (e.g. runtime not captured).
+ * Only "npm" is auto-upgradable; "path" means a dev (load.paths / --link) install
+ * which must never be npm-upgraded (would duplicate-install and break agent media sends).
+ *
+ * Resolution order:
+ *  1. The explicit `plugins.installs[<id>].source` config record — present on older
+ *     OpenClaw builds that surface install records in the runtime config snapshot.
+ *  2. Fallback: OpenClaw 2026.6.x moved install records out of the config snapshot
+ *     into a separate registry (~/.openclaw/state.db), leaving `plugins.installs`
+ *     unset — so infer from the loaded plugin path (`api.source`) instead.
  */
 export function getInstallSource() {
     const rt = getUpgradeRuntime();
@@ -26,11 +49,11 @@ export function getInstallSource() {
             source === "marketplace") {
             return source;
         }
-        return "unknown";
     }
     catch {
-        return "unknown";
+        // fall through to the path-based heuristic
     }
+    return classifyInstallSourceFromLoadedPath(rt.pluginSource);
 }
 /** Compare dotted numeric versions. Returns true if `a` is strictly greater than `b`. */
 export function semverGreater(a, b) {

package/dist/src/upgrade-runtime.d.ts

@@ -32,6 +32,12 @@ export type UpgradeRuntime = {
         afterWrite: ConfigAfterWrite;
         mutate: (draft: unknown) => unknown | void;
     }) => Promise<unknown>;
+    /**
+     * Filesystem path of THIS loaded plugin (`api.source`). Used to infer the install
+     * source (npm vs dev) on OpenClaw builds (2026.6.x+) that no longer surface
+     * `plugins.installs` in the config snapshot. See `getInstallSource`.
+     */
+    pluginSource: string | undefined;
 };
 export declare function setUpgradeRuntime(api: OpenClawPluginApi): void;
 export declare function getUpgradeRuntime(): UpgradeRuntime | null;

package/dist/src/upgrade-runtime.js

@@ -16,6 +16,7 @@ export function setUpgradeRuntime(api) {
                 throw new Error("runtime.config.mutateConfigFile unavailable");
             return mutate(params);
         },
+        pluginSource: typeof api.source === "string" ? api.source : undefined,
     };
 }
 export function getUpgradeRuntime() {

package/dist/src/version.js

@@ -10,7 +10,7 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 /** Keep in sync with package.json "version" as a last-resort fallback. */
-const FALLBACK_VERSION = "0.1.27";
+const FALLBACK_VERSION = "0.1.29";
 function resolvePluginVersion() {
     // dist layout: <root>/dist/src/version.js → ../../package.json = <root>/package.json
     // source layout (vitest/jiti): <root>/src/version.ts → ../package.json = <root>/package.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syengup/friday-channel-next",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "OpenClaw Friday Next Apple channel plugin",
   "license": "MIT",
   "type": "module",

package/src/http/handlers/files.ts

@@ -328,6 +328,7 @@ export function guessMimeType(filename: string): string {
     ".jpeg": "image/jpeg",
     ".gif": "image/gif",
     ".webp": "image/webp",
+    ".ico": "image/x-icon",
     ".heic": "image/heic",
     ".pdf": "application/pdf",
     ".mp4": "video/mp4",

package/src/http/handlers/link-preview.test.ts

@@ -0,0 +1,242 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+vi.mock("node:dns/promises", () => ({
+  default: { lookup: vi.fn() },
+}));
+
+import dns from "node:dns/promises";
+import { handleLinkPreview } from "./link-preview.js";
+import { resetLinkPreviewCacheForTest, type LinkPreviewPayload } from "../../link-preview/preview-service.js";
+import { setAttachmentsDirForTest } from "./files.js";
+import { clearFridayNextRuntime, setFridayNextRuntime } from "../../runtime.js";
+
+const lookupMock = vi.mocked(dns.lookup);
+
+class MockRes extends EventEmitter {
+  statusCode = 0;
+  headers: Record<string, string> = {};
+  body = "";
+  setHeader(name: string, value: string): void {
+    this.headers[name.toLowerCase()] = value;
+  }
+  end(body?: string): void {
+    if (body) this.body += body;
+    this.emit("finish");
+  }
+}
+
+function makeReq(query: string | null, token: string | null = "tok"): IncomingMessage {
+  return {
+    method: "GET",
+    url: query == null ? "/friday-next/link-preview" : `/friday-next/link-preview?url=${encodeURIComponent(query)}`,
+    headers: token ? { authorization: `Bearer ${token}` } : {},
+  } as unknown as IncomingMessage;
+}
+
+async function invoke(req: IncomingMessage): Promise<MockRes> {
+  const res = new MockRes();
+  await handleLinkPreview(req, res as unknown as ServerResponse);
+  return res;
+}
+
+const PAGE_HTML = `<html><head>
+  <meta property="og:title" content="Hello Page">
+  <meta property="og:description" content="A description">
+  <meta property="og:site_name" content="Example Site">
+  <meta property="og:image" content="https://example.com/cover.png">
+</head></html>`;
+
+const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0, 0]);
+
+let tmpDir: string;
+
+beforeEach(() => {
+  resetLinkPreviewCacheForTest();
+  lookupMock.mockReset();
+  lookupMock.mockResolvedValue([{ address: "93.184.216.34", family: 4 }] as never);
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "link-preview-test-"));
+  setAttachmentsDirForTest(tmpDir);
+  setFridayNextRuntime({
+    config: { loadConfig: () => ({ gateway: { auth: { token: "tok" } }, channels: {} }) },
+  } as never);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  setAttachmentsDirForTest(null);
+  clearFridayNextRuntime();
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("handleLinkPreview", () => {
+  it("405 on non-GET", async () => {
+    const res = new MockRes();
+    await handleLinkPreview({ method: "POST", url: "/friday-next/link-preview", headers: {} } as never, res as never);
+    expect(res.statusCode).toBe(405);
+  });
+
+  it("401 without bearer token", async () => {
+    const res = await invoke(makeReq("https://example.com/", null));
+    expect(res.statusCode).toBe(401);
+  });
+
+  it("400 when url param is missing or not http(s)", async () => {
+    expect((await invoke(makeReq(null))).statusCode).toBe(400);
+    expect((await invoke(makeReq("ftp://example.com/x"))).statusCode).toBe(400);
+    expect((await invoke(makeReq("not a url"))).statusCode).toBe(400);
+  });
+
+  it("403 blocked_url for private targets", async () => {
+    const res = await invoke(makeReq("http://192.168.1.1/admin"));
+    expect(res.statusCode).toBe(403);
+    expect(JSON.parse(res.body).error).toBe("blocked_url");
+  });
+
+  it("200 with full preview payload and re-hosted cover image", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: URL | string) => {
+        const url = String(input);
+        if (url.includes("cover.png")) {
+          return new Response(PNG_BYTES, { status: 200, headers: { "content-type": "image/png" } });
+        }
+        return new Response(PAGE_HTML, { status: 200, headers: { "content-type": "text/html; charset=utf-8" } });
+      }),
+    );
+    const res = await invoke(makeReq("https://example.com/article"));
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body) as { ok: boolean; preview: LinkPreviewPayload };
+    expect(body.ok).toBe(true);
+    expect(body.preview.title).toBe("Hello Page");
+    expect(body.preview.description).toBe("A description");
+    expect(body.preview.siteName).toBe("Example Site");
+    expect(body.preview.url).toBe("https://example.com/article");
+    expect(body.preview.finalUrl).toBe("https://example.com/article");
+    expect(body.preview.imageUrl).toMatch(/^\/friday-next\/files\/.+\.png$/);
+    expect(typeof body.preview.fetchedAt).toBe("number");
+    // 封面图确实落盘
+    const token = decodeURIComponent(body.preview.imageUrl!.split("/").pop()!);
+    expect(fs.existsSync(path.join(tmpDir, token))).toBe(true);
+  });
+
+  it("200 with imageUrl null when the cover download fails", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: URL | string) => {
+        const url = String(input);
+        if (url.includes("cover.png")) return new Response("nope", { status: 404 });
+        return new Response(PAGE_HTML, { status: 200, headers: { "content-type": "text/html" } });
+      }),
+    );
+    const res = await invoke(makeReq("https://example.com/article"));
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).preview.imageUrl).toBeNull();
+  });
+
+  it("falls back siteName to hostname when og:site_name is absent", async () => {
+    const html = `<meta property="og:title" content="T">`;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response(html, { status: 200, headers: { "content-type": "text/html" } })),
+    );
+    const res = await invoke(makeReq("https://example.com/x"));
+    expect(JSON.parse(res.body).preview.siteName).toBe("example.com");
+  });
+
+  it("200 minimal hostname card when a reachable page has no OG metadata", async () => {
+    // 可达但无 OG/title → 退到 hostname 卡片(不再折叠)。
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("<html><body>plain</body></html>", { status: 200, headers: { "content-type": "text/html" } })),
+    );
+    const res = await invoke(makeReq("https://example.com/bare"));
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).preview.title).toBe("example.com");
+  });
+
+  it("ICO favicon re-hosted into iconUrl", async () => {
+    const ICO_BYTES = new Uint8Array([0x00, 0x00, 0x01, 0x00, 0x01, 0, 0, 0, 0, 0, 0, 0]);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: URL | string) => {
+        const url = String(input);
+        if (url.includes("favicon")) {
+          return new Response(ICO_BYTES, { status: 200, headers: { "content-type": "image/x-icon" } });
+        }
+        return new Response(`<meta property="og:title" content="Titled">`, { status: 200, headers: { "content-type": "text/html" } });
+      }),
+    );
+    const res = await invoke(makeReq("https://example.com/p"));
+    const preview = JSON.parse(res.body).preview as LinkPreviewPayload;
+    expect(preview.iconUrl).toMatch(/^\/friday-next\/files\/.+\.ico$/);
+    const token = decodeURIComponent(preview.iconUrl!.split("/").pop()!);
+    expect(fs.existsSync(path.join(tmpDir, token))).toBe(true);
+  });
+
+  it("200 minimal card for a bot-blocked page whose favicon.ico is reachable (zhihu-style)", async () => {
+    const ICO_BYTES = new Uint8Array([0x00, 0x00, 0x01, 0x00, 0x01, 0, 0, 0, 0, 0, 0, 0]);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: URL | string) => {
+        const url = String(input);
+        if (url.endsWith("/favicon.ico")) {
+          return new Response(ICO_BYTES, { status: 200, headers: { "content-type": "image/vnd.microsoft.icon" } });
+        }
+        return new Response("blocked", { status: 403, headers: { "content-type": "text/html" } }); // page blocks bots
+      }),
+    );
+    const res = await invoke(makeReq("https://www.zhihu.com/question/123"));
+    expect(res.statusCode).toBe(200);
+    const preview = JSON.parse(res.body).preview as LinkPreviewPayload;
+    expect(preview.title).toBe("www.zhihu.com");
+    expect(preview.iconUrl).toMatch(/^\/friday-next\/files\/.+\.ico$/);
+    expect(preview.imageUrl).toBeNull();
+  });
+
+  it("502 fetch_failed for a dead domain (page and favicon both fail)", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response("nope", { status: 404 })));
+    const res = await invoke(makeReq("https://dead.example.com/x"));
+    expect(res.statusCode).toBe(502);
+    expect(JSON.parse(res.body).error).toBe("fetch_failed");
+  });
+
+  it("502 fetch_failed on non-2xx and non-HTML responses", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response("nope", { status: 500 })));
+    expect((await invoke(makeReq("https://example.com/down"))).statusCode).toBe(502);
+
+    resetLinkPreviewCacheForTest();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("{}", { status: 200, headers: { "content-type": "application/json" } })),
+    );
+    expect((await invoke(makeReq("https://example.com/api"))).statusCode).toBe(502);
+  });
+
+  it("serves the second request from cache without refetching", async () => {
+    const fetchMock = vi.fn(async () => new Response(`<meta property="og:title" content="Cached">`, {
+      status: 200,
+      headers: { "content-type": "text/html" },
+    }));
+    vi.stubGlobal("fetch", fetchMock);
+    await invoke(makeReq("https://example.com/cached"));
+    const afterFirst = fetchMock.mock.calls.length;
+    const second = await invoke(makeReq("https://example.com/cached"));
+    expect(second.statusCode).toBe(200);
+    expect(JSON.parse(second.body).preview.title).toBe("Cached");
+    expect(fetchMock).toHaveBeenCalledTimes(afterFirst); // cached → no extra network
+  });
+
+  it("negative-caches failures", async () => {
+    const fetchMock = vi.fn(async () => new Response("nope", { status: 500 }));
+    vi.stubGlobal("fetch", fetchMock);
+    await invoke(makeReq("https://example.com/flaky"));
+    const afterFirst = fetchMock.mock.calls.length;
+    await invoke(makeReq("https://example.com/flaky"));
+    expect(fetchMock).toHaveBeenCalledTimes(afterFirst); // negative-cached → no refetch
+  });
+});

package/src/http/handlers/link-preview.ts

@@ -0,0 +1,47 @@
+/**
+ * GET /friday-next/link-preview?url=<percent-encoded http(s) URL>
+ *
+ * Returns Open Graph metadata for a page link so the app can render a preview card without
+ * ever contacting the third-party site itself. Cover images are re-hosted under
+ * /friday-next/files/ by the preview service.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { getLinkPreview, type LinkPreviewError } from "../../link-preview/preview-service.js";
+import { extractBearerToken } from "../middleware/auth.js";
+
+const ERROR_STATUS: Record<LinkPreviewError, number> = {
+  invalid_url: 400,
+  blocked_url: 403,
+  no_metadata: 422,
+  fetch_failed: 502,
+};
+
+export async function handleLinkPreview(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if (req.method !== "GET") {
+    res.statusCode = 405;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Method Not Allowed" }));
+    return true;
+  }
+  if (!extractBearerToken(req)) {
+    res.statusCode = 401;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ ok: false, error: "unauthorized" }));
+    return true;
+  }
+
+  const url = new URL(req.url ?? "/", "http://localhost").searchParams.get("url")?.trim();
+  if (!url) {
+    res.statusCode = 400;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ ok: false, error: "invalid_url" }));
+    return true;
+  }
+
+  const result = await getLinkPreview(url);
+  res.statusCode = result.ok ? 200 : ERROR_STATUS[result.error];
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(result));
+  return true;
+}

package/src/http/server.ts

@@ -20,6 +20,7 @@ import { handleHistorySessions } from "./handlers/history-sessions.js";
 import { handleHistoryMessages } from "./handlers/history-messages.js";
 import { handleHistorySetTitle } from "./handlers/history-set-title.js";
 import { handleStatus } from "./handlers/status.js";
+import { handleLinkPreview } from "./handlers/link-preview.js";
 import { handleHealth } from "./handlers/health.js";
 import { handlePluginInfo } from "./handlers/plugin-info.js";
 import { handlePluginUpgrade } from "./handlers/plugin-upgrade.js";
@@ -106,6 +107,11 @@ async function handleFridayNextRoute(
     return await handleHistorySetTitle(req, res);
   }
 
+  // Route: GET /friday-next/link-preview?url=... (Open Graph metadata for preview cards)
+  if (req.method === "GET" && pathname === "/friday-next/link-preview") {
+    return await handleLinkPreview(req, res);
+  }
+
   // Route: GET /friday-next/health?deviceId=...&nodeDeviceId=...&selfHeal=true
   if (req.method === "GET" && pathname === "/friday-next/health") {
     return await handleHealth(req, res);