@syengup/friday-channel-next 0.1.27 → 0.1.28

package/dist/src/http/handlers/files.js

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

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

@@ -0,0 +1,9 @@
+/**
+ * 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";
+export declare function handleLinkPreview(req: IncomingMessage, res: ServerResponse): Promise<boolean>;

package/dist/src/http/handlers/link-preview.js

@@ -0,0 +1,41 @@
+/**
+ * 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 { getLinkPreview } from "../../link-preview/preview-service.js";
+import { extractBearerToken } from "../middleware/auth.js";
+const ERROR_STATUS = {
+    invalid_url: 400,
+    blocked_url: 403,
+    no_metadata: 422,
+    fetch_failed: 502,
+};
+export async function handleLinkPreview(req, res) {
+    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/dist/src/http/server.js

@@ -18,6 +18,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";
@@ -85,6 +86,10 @@ async function handleFridayNextRoute(req, res) {
     if ((req.method === "PUT" || req.method === "POST") && pathname === "/friday-next/sessions/title") {
         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);

package/dist/src/link-preview/og-parse.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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".
+ */
+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;
+}
+export declare function decodeHtmlEntities(s: string): string;
+export declare function parseOpenGraph(html: string, baseUrl: string): OpenGraphResult;
+/**
+ * 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 declare function parseFaviconUrl(html: string, baseUrl: string): string | null;

package/dist/src/link-preview/og-parse.js

@@ -0,0 +1,232 @@
+/**
+ * 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;
+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, name) {
+    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 = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: " ",
+    ndash: "–",
+    mdash: "—",
+    hellip: "…",
+    middot: "·",
+    copy: "©",
+    reg: "®",
+    trade: "™",
+    lsquo: "‘",
+    rsquo: "’",
+    ldquo: "“",
+    rdquo: "”",
+    laquo: "«",
+    raquo: "»",
+};
+export function decodeHtmlEntities(s) {
+    return s.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (whole, body) => {
+        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) {
+    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, baseUrl) {
+    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, baseUrl) {
+    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 = {};
+    const tw = {};
+    let metaDescription = 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) {
+    for (const match of html.matchAll(JSON_LD_RE)) {
+        let data;
+        try {
+            data = JSON.parse(match[1].trim());
+        }
+        catch {
+            continue;
+        }
+        // JSON-LD may be a single object, an array, or a @graph container.
+        const nodes = Array.isArray(data)
+            ? data
+            : isRecord(data) && Array.isArray(data["@graph"])
+                ? data["@graph"]
+                : [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) {
+    return typeof v === "object" && v !== null;
+}
+function asString(v) {
+    return typeof v === "string" && v.trim() ? v : null;
+}
+/** JSON-LD `image` is a string, an array, or an ImageObject `{ url }`. */
+function firstImage(v) {
+    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) {
+    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) {
+    const raw = html.match(JSON_COVER_RE)?.[1];
+    if (!raw)
+        return null;
+    return raw.replace(/\\\//g, "/"); // unescape JSON `\/`
+}
+function stripTags(s) {
+    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, baseUrl) {
+    let appleTouch = null;
+    let regular = 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/dist/src/link-preview/preview-service.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+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;
+};
+export declare function resetLinkPreviewCacheForTest(): void;
+export declare function getLinkPreview(rawUrl: string): Promise<LinkPreviewResult>;

package/dist/src/link-preview/preview-service.js

@@ -0,0 +1,216 @@
+/**
+ * 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");
+const cache = new Map();
+const inFlight = new Map();
+export function resetLinkPreviewCacheForTest() {
+    cache.clear();
+    inFlight.clear();
+}
+export async function getLinkPreview(rawUrl) {
+    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, result) {
+    if (cache.size >= MAX_CACHE_ENTRIES) {
+        let oldestKey = 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) {
+    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, finalUrl) {
+    const candidates = [];
+    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) {
+    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) {
+    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) {
+    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;
+}

package/dist/src/link-preview/ssrf-guard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+export declare class BlockedUrlError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** Parse an absolute http/https URL. Returns null for anything else (caller maps to invalid_url). */
+export declare function parseHttpUrl(raw: string): URL | null;
+/** Synchronous literal checks: port, hostname blocklist, IP-literal hosts. Throws BlockedUrlError. */
+export declare function assertPublicHttpUrl(url: URL): void;
+/** True when the IP (v4 or v6, including ::ffff: mapped v4) is private, loopback, or reserved. */
+export declare function isPrivateAddress(ip: string): boolean;
+/** Resolve the hostname and require every returned address to be public. Throws BlockedUrlError. */
+export declare function assertResolvesPublic(url: URL): Promise<void>;
+export interface FetchPublicUrlOptions {
+    maxBytes: number;
+    timeoutMs: number;
+    /** Sent as the Accept header. */
+    accept?: string;
+    /** When set, the response Content-Type must start with one of these prefixes. */
+    requireContentTypePrefixes?: string[];
+}
+export interface FetchPublicUrlResult {
+    finalUrl: string;
+    contentType: string;
+    body: Buffer;
+}
+/**
+ * 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 declare function fetchPublicUrl(rawUrl: string, opts: FetchPublicUrlOptions): Promise<FetchPublicUrlResult | null>;