From b84558e92827735cdb3204d30488a4fb777c90d1 Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Tue, 28 Jul 2026 13:59:25 -0400
Subject: [PATCH] [og] Render per-video OpenGraph tags for crawlers

index.html carries one set of site-wide OG tags, so every /?v=<nevent> link
previewed as the same generic bitvid card -- never the video's title or
thumbnail. bitvid is a static SPA and crawlers do not run JS, so the client
cannot fix this.

api/og.js renders the tags on demand. Nothing is pre-generated and nothing is
stored: the video is a query param, not a path, so one stateless function
serves every video and dist/ is byte-identical with or without it. The only
caching is the CDN edge (s-maxage=300) plus a per-container memo of the admin
lists.

This is never load-bearing. Only crawler user-agents are rewritten to it
(vercel.json), humans get a 302 to the untouched SPA, and a static/nsite deploy
with no functions keeps working -- it just serves the site-wide card. Rollback
is deleting the `rewrites` block.

- Emits twitter:player / og:video:url pointing at embed.html?pointer=<nevent>,
  so a shared link plays inline on Twitter/Discord/Telegram rather than showing
  a still. frame-ancestors * already permits the embed.
- Fails closed. A crawler never authenticates, so anything emitted is public
  forever in third-party caches: deleted, isPrivate, isNsfw/content-warning,
  blacklisted authors, and -- while whitelist mode is on -- an unavailable or
  empty whitelist all fall back to the generic card.
- Escapes every attribute. Titles come from arbitrary nostr events and this HTML
  is served from bitvid's own origin; only http(s) URLs reach a meta tag.
- Parses BOTH event shapes: bitvid's kind-30078 v3 JSON and the NIP-71 tag shape
  (kinds 21/22/34235/34236) that nostube/slidestr publish, where the title is a
  `title` tag and the thumbnail an `imeta image` entry. Reading only the JSON
  shape made every NIP-71 video fall back to the generic card.
- Relay budget is 4s: a cold pool's first read measured ~3s, and 1.5s silently
  degraded every preview. Warm containers answer in <600ms.

Admin-list identity and the relay set are imported from js/config.js,
js/nostr/toolkit.js and js/nostrEventSchemas.js rather than duplicated -- a
hardcoded copy of the namespace gated every preview during development, and a
test now fails if any npub or wss:// literal reappears in the handler.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 api/_lib/ogRenderer.mjs    | 363 +++++++++++++++++++++++++++++++
 api/og.js                  | 257 ++++++++++++++++++++++
 tests/og-renderer.test.mjs | 426 +++++++++++++++++++++++++++++++++++++
 vercel.json                |  14 ++
 4 files changed, 1060 insertions(+)
 create mode 100644 api/_lib/ogRenderer.mjs
 create mode 100644 api/og.js
 create mode 100644 tests/og-renderer.test.mjs

diff --git a/api/_lib/ogRenderer.mjs b/api/_lib/ogRenderer.mjs
new file mode 100644
index 00000000..d23903b4
--- /dev/null
+++ b/api/_lib/ogRenderer.mjs
@@ -0,0 +1,363 @@
+// Per-video OpenGraph / Twitter-player rendering for crawlers.
+//
+// bitvid is a static SPA: index.html carries one set of site-wide OG tags, so
+// every `/?v=<nevent>` link previewed as the same generic bitvid card. Crawlers
+// don't run JS, so the client can't fix that — this module renders the tags a
+// crawler needs, and a thin host adapter (api/og.js on Vercel) feeds it.
+//
+// PURE by design: no network, no host globals. All I/O lives in the adapter so
+// the escaping and gating rules below stay unit-testable.
+//
+// Rollback: remove the crawler rewrite from vercel.json. The static site keeps
+// serving its existing tags and nothing else changes — this is never on the
+// path of a real user's page load, and `npm run archive` (nsite) is unaffected.
+
+// Player card dimensions. Twitter refuses a player card without explicit
+// dimensions, and 16:9 matches bitvid's embed shell.
+export const DEFAULT_PLAYER_WIDTH = 1280;
+export const DEFAULT_PLAYER_HEIGHT = 720;
+
+const MAX_TITLE_LENGTH = 120;
+const MAX_DESCRIPTION_LENGTH = 200;
+
+/**
+ * Escape a value for use inside a double-quoted HTML attribute.
+ *
+ * Titles and descriptions come from arbitrary nostr events — treat every one as
+ * hostile. A title of `"><script>…` would otherwise break out of the meta tag
+ * and inject markup into a page we serve from our own origin.
+ */
+export function escapeHtmlAttribute(value) {
+  if (typeof value !== "string") {
+    return "";
+  }
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * Only http(s) URLs may reach a meta tag. Anything else (javascript:, data:,
+ * relative paths) is dropped — a crawler resolving them is at best useless and
+ * at worst a vector.
+ */
+export function sanitizeAbsoluteUrl(value) {
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  if (!trimmed) {
+    return "";
+  }
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch (err) {
+    return "";
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return "";
+  }
+  return parsed.toString();
+}
+
+/** Collapse whitespace and hard-truncate for preview surfaces. */
+export function normalizeText(value, maxLength) {
+  const collapsed =
+    typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+  if (!collapsed || !Number.isFinite(maxLength) || maxLength <= 0) {
+    return collapsed;
+  }
+  if (collapsed.length <= maxLength) {
+    return collapsed;
+  }
+  return `${collapsed.slice(0, maxLength - 1).trimEnd()}…`;
+}
+
+/**
+ * Decide whether a video may be described in a link preview.
+ *
+ * A crawler never authenticates, so anything emitted here is fully public and
+ * outlives us in third-party caches. The rule is fail-closed: only a video that
+ * is affirmatively public gets a rich card; everything else — including the
+ * "we couldn't determine it" case — falls back to the generic bitvid card.
+ *
+ * @returns {{allowed: boolean, reason: string}}
+ */
+export function isPubliclyShareable(video, options = {}) {
+  if (!video || typeof video !== "object") {
+    return { allowed: false, reason: "missing-video" };
+  }
+  if (video.invalid) {
+    return { allowed: false, reason: "invalid-video" };
+  }
+  if (video.deleted === true) {
+    return { allowed: false, reason: "deleted" };
+  }
+  if (video.isPrivate === true) {
+    return { allowed: false, reason: "private" };
+  }
+  // NSFW thumbnails must never be injected into an unsuspecting timeline.
+  if (video.isNsfw === true) {
+    return { allowed: false, reason: "nsfw" };
+  }
+
+  const pubkey =
+    typeof video.pubkey === "string" ? video.pubkey.trim().toLowerCase() : "";
+  if (!pubkey) {
+    return { allowed: false, reason: "missing-author" };
+  }
+
+  const blacklist = options.blacklist instanceof Set ? options.blacklist : null;
+  if (blacklist && blacklist.has(pubkey)) {
+    return { allowed: false, reason: "blacklisted" };
+  }
+
+  if (options.whitelistEnabled) {
+    const whitelist =
+      options.whitelist instanceof Set ? options.whitelist : null;
+    // No usable whitelist while whitelist mode is on means we cannot prove the
+    // author is allowed. Fail closed rather than leak a gated video's metadata.
+    if (!whitelist || whitelist.size === 0) {
+      return { allowed: false, reason: "whitelist-unavailable" };
+    }
+    if (!whitelist.has(pubkey)) {
+      return { allowed: false, reason: "not-whitelisted" };
+    }
+  }
+
+  return { allowed: true, reason: "ok" };
+}
+
+// bitvid's own notes are kind 30078 with a v3 JSON body. Other clients
+// (nostube/slidestr and anything NIP-71 native) publish kind 21/22/34235/34236
+// with the metadata in TAGS and the description in `content`. bitvid normalizes
+// both in the browser, so the preview must understand both too — parsing only
+// the JSON shape made every NIP-71 video fall back to the generic card.
+export const NIP71_VIDEO_KINDS = Object.freeze([21, 22, 34235, 34236]);
+
+function firstTagValue(tags, name) {
+  if (!Array.isArray(tags)) {
+    return "";
+  }
+  for (const tag of tags) {
+    if (Array.isArray(tag) && tag[0] === name && typeof tag[1] === "string") {
+      const value = tag[1].trim();
+      if (value) {
+        return value;
+      }
+    }
+  }
+  return "";
+}
+
+function hasTag(tags, name) {
+  return (
+    Array.isArray(tags) &&
+    tags.some((tag) => Array.isArray(tag) && tag[0] === name)
+  );
+}
+
+/** First `image <url>` entry inside any imeta tag. */
+function imetaImageUrl(tags) {
+  if (!Array.isArray(tags)) {
+    return "";
+  }
+  for (const tag of tags) {
+    if (!Array.isArray(tag) || tag[0] !== "imeta") {
+      continue;
+    }
+    for (let i = 1; i < tag.length; i += 1) {
+      const entry = typeof tag[i] === "string" ? tag[i].trim() : "";
+      if (/^image\s+/i.test(entry)) {
+        const url = sanitizeAbsoluteUrl(entry.replace(/^image\s+/i, ""));
+        if (url) {
+          return url;
+        }
+      }
+    }
+  }
+  return "";
+}
+
+/**
+ * Normalize a raw nostr event into the fields the preview needs, for both the
+ * bitvid v3 JSON shape and the NIP-71 tag shape. Returns null when the event is
+ * not a recognizable video note (caller renders the generic card).
+ */
+export function parseVideoEvent(event) {
+  if (!event || typeof event !== "object") {
+    return null;
+  }
+
+  const base = { pubkey: event.pubkey, deleted: false, isPrivate: false };
+
+  // --- bitvid native (kind 30078, JSON content) ---
+  if (typeof event.content === "string" && event.content.trim().startsWith("{")) {
+    try {
+      const content = JSON.parse(event.content);
+      if (content && typeof content === "object") {
+        return {
+          ...base,
+          title: content.title,
+          description: content.description,
+          thumbnail: content.thumbnail,
+          deleted: content.deleted === true,
+          isPrivate: content.isPrivate === true,
+          isNsfw: content.isNsfw === true || hasTag(event.tags, "content-warning"),
+          invalid: !content.title || (!content.url && !content.magnet),
+        };
+      }
+    } catch (err) {
+      // Not JSON after all — fall through to the NIP-71 reading.
+    }
+  }
+
+  // --- NIP-71 (metadata in tags, description in content) ---
+  if (NIP71_VIDEO_KINDS.includes(event.kind)) {
+    const title = firstTagValue(event.tags, "title");
+    const thumbnail =
+      imetaImageUrl(event.tags) ||
+      sanitizeAbsoluteUrl(firstTagValue(event.tags, "image")) ||
+      sanitizeAbsoluteUrl(firstTagValue(event.tags, "thumb"));
+    const description =
+      (typeof event.content === "string" && event.content.trim()) ||
+      firstTagValue(event.tags, "summary") ||
+      firstTagValue(event.tags, "alt");
+    return {
+      ...base,
+      title,
+      description,
+      thumbnail,
+      // NIP-71 has no privacy flag; `content-warning` is the NSFW signal.
+      isNsfw: hasTag(event.tags, "content-warning"),
+      invalid: !title,
+    };
+  }
+
+  return null;
+}
+
+function metaTag(attribute, name, content) {
+  return `    <meta ${attribute}="${escapeHtmlAttribute(name)}" content="${escapeHtmlAttribute(content)}" />`;
+}
+
+/**
+ * Render the crawler-facing HTML document.
+ *
+ * @param {object} params
+ * @param {object|null} params.video      Normalized video object, or null.
+ * @param {string} params.shareUrl        Canonical `/?v=<nevent>` URL.
+ * @param {string} [params.embedUrl]      `/embed.html?pointer=<nevent>` player URL.
+ * @param {object} params.fallback        Site-wide defaults (title/description/image/url).
+ * @param {object} [params.gate]          Result of isPubliclyShareable().
+ * @returns {string} A complete HTML document.
+ */
+export function renderOgHtml({
+  video = null,
+  shareUrl = "",
+  embedUrl = "",
+  fallback = {},
+  gate = null,
+} = {}) {
+  const siteName = normalizeText(fallback.siteName || "bitvid", 60);
+  const fallbackTitle = normalizeText(
+    fallback.title || "bitvid - Decentralized Video Sharing",
+    MAX_TITLE_LENGTH
+  );
+  const fallbackDescription = normalizeText(
+    fallback.description || "Decentralized video sharing on Nostr.",
+    MAX_DESCRIPTION_LENGTH
+  );
+  const fallbackImage = sanitizeAbsoluteUrl(fallback.image);
+  const canonical = sanitizeAbsoluteUrl(shareUrl) || sanitizeAbsoluteUrl(fallback.url);
+
+  const decision = gate || isPubliclyShareable(video);
+  const useVideo = decision.allowed === true;
+
+  const title = useVideo
+    ? normalizeText(video.title, MAX_TITLE_LENGTH) || fallbackTitle
+    : fallbackTitle;
+  const description = useVideo
+    ? normalizeText(video.description, MAX_DESCRIPTION_LENGTH) ||
+      fallbackDescription
+    : fallbackDescription;
+  const image = useVideo
+    ? sanitizeAbsoluteUrl(video.thumbnail) || fallbackImage
+    : fallbackImage;
+  const player = useVideo ? sanitizeAbsoluteUrl(embedUrl) : "";
+
+  const lines = [
+    "<!doctype html>",
+    '<html lang="en">',
+    "  <head>",
+    '    <meta charset="utf-8" />',
+    '    <meta name="viewport" content="width=device-width, initial-scale=1" />',
+    `    <title>${escapeHtmlAttribute(title)}</title>`,
+  ];
+
+  if (canonical) {
+    lines.push(`    <link rel="canonical" href="${escapeHtmlAttribute(canonical)}" />`);
+  }
+
+  lines.push(metaTag("name", "description", description));
+  lines.push(metaTag("property", "og:site_name", siteName));
+  lines.push(metaTag("property", "og:type", useVideo ? "video.other" : "website"));
+  lines.push(metaTag("property", "og:title", title));
+  lines.push(metaTag("property", "og:description", description));
+  if (canonical) {
+    lines.push(metaTag("property", "og:url", canonical));
+  }
+  if (image) {
+    lines.push(metaTag("property", "og:image", image));
+    lines.push(metaTag("property", "og:image:alt", title));
+  }
+
+  if (player) {
+    // A player card is what makes a shared bitvid link behave like a YouTube
+    // link: the video plays inline in the timeline instead of showing a still.
+    lines.push(metaTag("property", "og:video:url", player));
+    lines.push(metaTag("property", "og:video:secure_url", player));
+    lines.push(metaTag("property", "og:video:type", "text/html"));
+    lines.push(metaTag("property", "og:video:width", String(DEFAULT_PLAYER_WIDTH)));
+    lines.push(metaTag("property", "og:video:height", String(DEFAULT_PLAYER_HEIGHT)));
+    lines.push(metaTag("name", "twitter:card", "player"));
+    lines.push(metaTag("name", "twitter:player", player));
+    lines.push(metaTag("name", "twitter:player:width", String(DEFAULT_PLAYER_WIDTH)));
+    lines.push(metaTag("name", "twitter:player:height", String(DEFAULT_PLAYER_HEIGHT)));
+  } else {
+    lines.push(metaTag("name", "twitter:card", image ? "summary_large_image" : "summary"));
+  }
+
+  lines.push(metaTag("name", "twitter:title", title));
+  lines.push(metaTag("name", "twitter:description", description));
+  if (image) {
+    lines.push(metaTag("name", "twitter:image", image));
+  }
+
+  lines.push("  </head>");
+  lines.push("  <body>");
+  // A human should never land here (only crawler user-agents are rewritten),
+  // but if one does, give them a real link rather than a blank page.
+  lines.push(
+    canonical
+      ? `    <p><a href="${escapeHtmlAttribute(canonical)}">${escapeHtmlAttribute(title)}</a></p>`
+      : `    <p>${escapeHtmlAttribute(title)}</p>`
+  );
+  lines.push("  </body>");
+  lines.push("</html>");
+
+  return `${lines.join("\n")}\n`;
+}
+
+// Conservative crawler match. Being wrong in the "not a bot" direction is free
+// (the visitor gets the normal SPA); being wrong the other way would serve a
+// human this stub page, so the pattern stays narrow and explicit.
+export const CRAWLER_USER_AGENT_PATTERN =
+  /(facebookexternalhit|twitterbot|slackbot|discordbot|telegrambot|whatsapp|linkedinbot|pinterest|redditbot|embedly|quora link preview|nostrbot|primal|iframely|opengraph|mastodon|bluesky|skypeuripreview|vkshare|googlebot|bingbot|applebot|yandexbot|duckduckbot|baiduspider|petalbot|semrushbot|ahrefsbot|developers\.google\.com\/\+\/web\/snippet)/i;
+
+export function isCrawlerUserAgent(userAgent) {
+  return typeof userAgent === "string"
+    ? CRAWLER_USER_AGENT_PATTERN.test(userAgent)
+    : false;
+}
diff --git a/api/og.js b/api/og.js
new file mode 100644
index 00000000..2420df71
--- /dev/null
+++ b/api/og.js
@@ -0,0 +1,257 @@
+// Vercel serverless handler: renders per-video OpenGraph / Twitter-player tags
+// for crawlers hitting `/?v=<nevent>`.
+//
+// Nothing is pre-generated and nothing is persisted. This is a stateless
+// function invoked per crawler request; `dist/` is byte-identical with or
+// without it. The only caching is the CDN edge cache via Cache-Control below.
+//
+// This must never become load-bearing for the app: real users are not routed
+// here (see the user-agent rewrite in vercel.json), and a static/nsite deploy
+// without any functions keeps working exactly as it does today, just with the
+// site-wide card.
+
+import { nip19 } from "nostr-tools";
+import { SimplePool, useWebSocketImplementation } from "nostr-tools/pool";
+import WebSocket from "ws";
+
+import {
+  isCrawlerUserAgent,
+  isPubliclyShareable,
+  parseVideoEvent,
+  renderOgHtml,
+} from "./_lib/ogRenderer.mjs";
+
+// Imported, not duplicated: these modules are plain ESM with no DOM access, so
+// the function reads the SAME admin-list identity and relay set the browser
+// does. A hardcoded copy would silently drift the moment an operator retunes
+// the instance, and the failure mode (previews gated forever, or worse, a stale
+// whitelist) would be invisible.
+import {
+  ADMIN_LIST_NAMESPACE,
+  ADMIN_SUPER_NPUB,
+} from "../js/config.js";
+import { DEFAULT_RELAY_URLS } from "../js/nostr/toolkit.js";
+import { ADMIN_LIST_IDENTIFIERS } from "../js/nostrEventSchemas.js";
+
+useWebSocketImplementation(WebSocket);
+
+const RELAYS = Array.from(DEFAULT_RELAY_URLS);
+
+// Admin moderation lists are addressable kind-30000 sets published by the
+// instance's super admin (js/adminListStore.js).
+const ADMIN_LIST_KIND = 30000;
+
+// Measured: a COLD pool's first read across these relays can take ~3s (WSS
+// handshake + REQ round trip on four connections). 1.5s and 2.5s both cut it
+// off and served the generic card every time. Twitter allows ~5s and Facebook
+// ~10s, so 4s buys a correct card on a cold container while still leaving
+// headroom under Vercel's function limit. Warm containers answer in <600ms.
+const RELAY_TIMEOUT_MS = 4000;
+
+// Admin lists are identical for every request, so re-reading them on each crawl
+// is pure waste (and it was starving the video read of its budget). Memoized in
+// module scope: warm invocations skip the relay round trip entirely. This is a
+// per-container, in-memory cache of PUBLIC data that dies with the container —
+// nothing is persisted anywhere.
+const ADMIN_LIST_TTL_MS = 5 * 60 * 1000;
+let adminListCache = { expiresAt: 0, whitelist: null, blacklist: null };
+
+const SITE_ORIGIN = process.env.BITVID_SITE_ORIGIN || "https://bitvid.network";
+const FALLBACK = Object.freeze({
+  siteName: "bitvid",
+  title: "bitvid - Decentralized Video Sharing",
+  description:
+    "bitvid is a decentralized video sharing platform built on Nostr and WebTorrent.",
+  image: `${SITE_ORIGIN}/assets/jpg/bitvid.jpg`,
+  url: SITE_ORIGIN,
+});
+
+function withTimeout(promise, ms, fallbackValue) {
+  return Promise.race([
+    promise.catch(() => fallbackValue),
+    new Promise((resolve) => setTimeout(() => resolve(fallbackValue), ms)),
+  ]);
+}
+
+/** Decode `?v=` (nevent/naddr/note/raw hex) into a relay filter. */
+function pointerToFilter(pointer) {
+  const trimmed = typeof pointer === "string" ? pointer.trim() : "";
+  if (!trimmed) {
+    return null;
+  }
+  if (/^[0-9a-f]{64}$/i.test(trimmed)) {
+    return { ids: [trimmed.toLowerCase()] };
+  }
+  try {
+    const decoded = nip19.decode(trimmed);
+    if (decoded.type === "nevent" && decoded.data?.id) {
+      return { ids: [decoded.data.id] };
+    }
+    if (decoded.type === "note" && typeof decoded.data === "string") {
+      return { ids: [decoded.data] };
+    }
+    if (decoded.type === "naddr" && decoded.data?.identifier) {
+      return {
+        kinds: [decoded.data.kind],
+        authors: [decoded.data.pubkey],
+        "#d": [decoded.data.identifier],
+      };
+    }
+  } catch (err) {
+    // Unparseable pointer -> generic card.
+  }
+  return null;
+}
+
+function extractPubkeySet(event) {
+  const out = new Set();
+  if (!event || !Array.isArray(event.tags)) {
+    return out;
+  }
+  for (const tag of event.tags) {
+    if (!Array.isArray(tag) || tag[0] !== "p" || typeof tag[1] !== "string") {
+      continue;
+    }
+    const value = tag[1].trim().toLowerCase();
+    if (/^[0-9a-f]{64}$/.test(value)) {
+      out.add(value);
+      continue;
+    }
+    try {
+      const decoded = nip19.decode(value);
+      if (decoded.type === "npub" && typeof decoded.data === "string") {
+        out.add(decoded.data.toLowerCase());
+      }
+    } catch (err) {
+      // ignore malformed entries
+    }
+  }
+  return out;
+}
+
+export default async function handler(req, res) {
+  const host = req.headers?.host || new URL(SITE_ORIGIN).host;
+  const proto = req.headers?.["x-forwarded-proto"] || "https";
+  const requestUrl = new URL(req.url || "/", `${proto}://${host}`);
+  const pointer = requestUrl.searchParams.get("v") || "";
+
+  const shareUrl = pointer
+    ? `${SITE_ORIGIN}/?v=${encodeURIComponent(pointer)}`
+    : SITE_ORIGIN;
+  const embedUrl = pointer
+    ? `${SITE_ORIGIN}/embed.html?pointer=${encodeURIComponent(pointer)}`
+    : "";
+
+  const renderFallback = (reason) => {
+    // Short TTL: a video may be published, edited or moderated at any time, and
+    // we would rather re-ask the relays than pin a wrong card in someone's CDN.
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.setHeader("Cache-Control", "public, s-maxage=300, stale-while-revalidate=600");
+    res.setHeader("X-Bitvid-OG", reason);
+    res.status(200).send(
+      renderOgHtml({ video: null, shareUrl, fallback: FALLBACK })
+    );
+  };
+
+  // Defensive: the rewrite should only send crawlers here, but never serve a
+  // human this stub if the rule ever widens.
+  if (!isCrawlerUserAgent(req.headers?.["user-agent"])) {
+    res.setHeader("Cache-Control", "no-store");
+    res.redirect(302, shareUrl);
+    return;
+  }
+
+  const filter = pointerToFilter(pointer);
+  if (!filter) {
+    renderFallback("no-pointer");
+    return;
+  }
+
+  const pool = new SimplePool();
+  let superAdminHex = "";
+  try {
+    const decoded = nip19.decode(ADMIN_SUPER_NPUB);
+    superAdminHex = decoded.type === "npub" ? decoded.data : "";
+  } catch (err) {
+    superAdminHex = "";
+  }
+
+  try {
+    const listFilter = (identifier) => ({
+      kinds: [ADMIN_LIST_KIND],
+      "#d": [`${ADMIN_LIST_NAMESPACE}:${identifier}`],
+      ...(superAdminHex ? { authors: [superAdminHex] } : {}),
+    });
+
+    // One shared deadline across all three reads.
+    const now = Date.now();
+    const adminListsFresh =
+      adminListCache.expiresAt > now && adminListCache.whitelist instanceof Set;
+
+    const [videoEvent, whitelistEvent, blacklistEvent] = await Promise.all([
+      withTimeout(pool.get(RELAYS, filter), RELAY_TIMEOUT_MS, null),
+      adminListsFresh
+        ? Promise.resolve(null)
+        : withTimeout(
+            pool.get(RELAYS, listFilter(ADMIN_LIST_IDENTIFIERS.whitelist)),
+            RELAY_TIMEOUT_MS,
+            null
+          ),
+      adminListsFresh
+        ? Promise.resolve(null)
+        : withTimeout(
+            pool.get(RELAYS, listFilter(ADMIN_LIST_IDENTIFIERS.blacklist)),
+            RELAY_TIMEOUT_MS,
+            null
+          ),
+    ]);
+
+    let whitelist = adminListsFresh ? adminListCache.whitelist : null;
+    let blacklist = adminListsFresh ? adminListCache.blacklist : null;
+    if (!adminListsFresh) {
+      whitelist = extractPubkeySet(whitelistEvent);
+      blacklist = extractPubkeySet(blacklistEvent);
+      // Only cache a whitelist we actually got. Caching an empty one would pin
+      // "whitelist-unavailable" for the whole TTL after a single slow read.
+      if (whitelist.size > 0) {
+        adminListCache = {
+          expiresAt: now + ADMIN_LIST_TTL_MS,
+          whitelist,
+          blacklist,
+        };
+      }
+    }
+
+    const video = parseVideoEvent(videoEvent);
+    if (!video) {
+      renderFallback("event-not-found");
+      return;
+    }
+
+    const gate = isPubliclyShareable(video, {
+      whitelistEnabled: true,
+      whitelist,
+      blacklist,
+    });
+
+    if (!gate.allowed) {
+      renderFallback(`gated:${gate.reason}`);
+      return;
+    }
+
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.setHeader("Cache-Control", "public, s-maxage=300, stale-while-revalidate=600");
+    res.setHeader("X-Bitvid-OG", "video");
+    res
+      .status(200)
+      .send(renderOgHtml({ video, shareUrl, embedUrl, fallback: FALLBACK, gate }));
+  } catch (err) {
+    renderFallback("error");
+  } finally {
+    try {
+      pool.close(RELAYS);
+    } catch (err) {
+      // ignore
+    }
+  }
+}
diff --git a/tests/og-renderer.test.mjs b/tests/og-renderer.test.mjs
new file mode 100644
index 00000000..fc8531ab
--- /dev/null
+++ b/tests/og-renderer.test.mjs
@@ -0,0 +1,426 @@
+// Per-video OpenGraph rendering for crawlers — see api/_lib/ogRenderer.mjs.
+//
+// Two things here are security-relevant and get the most attention:
+//   1. Escaping. Titles/descriptions come from arbitrary nostr events, and this
+//      HTML is served from bitvid's own origin.
+//   2. Gating. A crawler never authenticates, so anything emitted is public
+//      forever in third-party caches. Deleted/private/NSFW/non-whitelisted
+//      videos must fall back to the generic site card.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import {
+  CRAWLER_USER_AGENT_PATTERN,
+  escapeHtmlAttribute,
+  isCrawlerUserAgent,
+  isPubliclyShareable,
+  normalizeText,
+  parseVideoEvent,
+  renderOgHtml,
+  sanitizeAbsoluteUrl,
+} from "../api/_lib/ogRenderer.mjs";
+
+const PUBKEY = "b7c6f6915cfa9a62fff6a1f02604de88c23c6c6c6d1b8f62c7cc10749f307e81";
+
+const publicVideo = () => ({
+  pubkey: PUBKEY,
+  title: "Why I'm (sort of) not worried about AI",
+  description: "A talk about creativity and machines.",
+  thumbnail: "https://cdn.example/thumb.jpg",
+  deleted: false,
+  isPrivate: false,
+  isNsfw: false,
+  invalid: false,
+});
+
+const FALLBACK = {
+  siteName: "bitvid",
+  title: "bitvid - Decentralized Video Sharing",
+  description: "Decentralized video sharing on Nostr.",
+  image: "https://bitvid.network/assets/jpg/bitvid.jpg",
+  url: "https://bitvid.network",
+};
+
+const render = (video, extra = {}) =>
+  renderOgHtml({
+    video,
+    shareUrl: "https://bitvid.network/?v=nevent1abc",
+    embedUrl: "https://bitvid.network/embed.html?pointer=nevent1abc",
+    fallback: FALLBACK,
+    gate: isPubliclyShareable(video, extra.gateOptions || {}),
+    ...extra.render,
+  });
+
+// --- escaping -------------------------------------------------------------
+
+test("escapeHtmlAttribute neutralizes attribute-breaking characters", () => {
+  assert.equal(
+    escapeHtmlAttribute(`"><script>alert(1)</script>`),
+    "&quot;&gt;&lt;script&gt;alert(1)&lt;/script&gt;"
+  );
+  assert.equal(escapeHtmlAttribute("a & b"), "a &amp; b");
+  assert.equal(escapeHtmlAttribute("it's"), "it&#39;s");
+  assert.equal(escapeHtmlAttribute(null), "");
+  assert.equal(escapeHtmlAttribute(42), "");
+});
+
+test("a hostile title cannot break out of the meta tag", () => {
+  const video = publicVideo();
+  video.title = `"><script>alert(document.domain)</script><meta x="`;
+  const html = render(video);
+
+  assert.equal(html.includes("<script>"), false, "no raw script tag");
+  assert.equal(html.includes(`"><script`), false, "no attribute breakout");
+  assert.match(html, /&lt;script&gt;/);
+});
+
+test("a hostile description is escaped too", () => {
+  const video = publicVideo();
+  video.description = `" onload="alert(1)`;
+  const html = render(video);
+  assert.equal(html.includes(`onload="alert(1)`), false);
+  assert.match(html, /&quot; onload=&quot;alert\(1\)/);
+});
+
+// --- URL sanitization -----------------------------------------------------
+
+test("sanitizeAbsoluteUrl accepts only http(s)", () => {
+  assert.equal(
+    sanitizeAbsoluteUrl("https://cdn.example/a.jpg"),
+    "https://cdn.example/a.jpg"
+  );
+  assert.equal(sanitizeAbsoluteUrl("http://cdn.example/a.jpg"), "http://cdn.example/a.jpg");
+  assert.equal(sanitizeAbsoluteUrl("javascript:alert(1)"), "");
+  assert.equal(sanitizeAbsoluteUrl("data:image/png;base64,AAAA"), "");
+  assert.equal(sanitizeAbsoluteUrl("assets/jpg/local.jpg"), "");
+  assert.equal(sanitizeAbsoluteUrl(""), "");
+  assert.equal(sanitizeAbsoluteUrl(null), "");
+});
+
+test("a javascript: thumbnail never reaches og:image", () => {
+  const video = publicVideo();
+  video.thumbnail = "javascript:alert(1)";
+  const html = render(video);
+  assert.equal(html.includes("javascript:"), false);
+  // Falls back to the site image rather than emitting nothing.
+  assert.match(html, /og:image" content="https:\/\/bitvid\.network\/assets/);
+});
+
+// --- text normalization ---------------------------------------------------
+
+test("normalizeText collapses whitespace and truncates with an ellipsis", () => {
+  assert.equal(normalizeText("  a \n b \t c  ", 50), "a b c");
+  const long = "x".repeat(300);
+  const out = normalizeText(long, 120);
+  assert.equal(out.length, 120);
+  assert.equal(out.endsWith("…"), true);
+  assert.equal(normalizeText(null, 10), "");
+});
+
+// --- gating ---------------------------------------------------------------
+
+test("a clean public video is shareable", () => {
+  assert.deepEqual(isPubliclyShareable(publicVideo()), {
+    allowed: true,
+    reason: "ok",
+  });
+});
+
+test("deleted, private, NSFW and invalid videos are never described", () => {
+  for (const [field, reason] of [
+    ["deleted", "deleted"],
+    ["isPrivate", "private"],
+    ["isNsfw", "nsfw"],
+    ["invalid", "invalid-video"],
+  ]) {
+    const video = publicVideo();
+    video[field] = true;
+    const result = isPubliclyShareable(video);
+    assert.equal(result.allowed, false, `${field} must gate the preview`);
+    assert.equal(result.reason, reason);
+  }
+});
+
+test("a missing video or author is gated", () => {
+  assert.equal(isPubliclyShareable(null).allowed, false);
+  assert.equal(isPubliclyShareable(undefined).reason, "missing-video");
+  const noAuthor = publicVideo();
+  noAuthor.pubkey = "";
+  assert.equal(isPubliclyShareable(noAuthor).reason, "missing-author");
+});
+
+test("a blacklisted author is gated regardless of whitelist mode", () => {
+  const result = isPubliclyShareable(publicVideo(), {
+    blacklist: new Set([PUBKEY]),
+  });
+  assert.equal(result.allowed, false);
+  assert.equal(result.reason, "blacklisted");
+});
+
+test("whitelist mode fails CLOSED when the list is missing or empty", () => {
+  // The dangerous case: relays timed out, so we cannot prove the author is
+  // allowed. Emitting a rich card here would leak gated metadata.
+  assert.equal(
+    isPubliclyShareable(publicVideo(), { whitelistEnabled: true }).reason,
+    "whitelist-unavailable"
+  );
+  assert.equal(
+    isPubliclyShareable(publicVideo(), {
+      whitelistEnabled: true,
+      whitelist: new Set(),
+    }).reason,
+    "whitelist-unavailable"
+  );
+});
+
+test("whitelist mode admits a listed author and rejects an unlisted one", () => {
+  assert.equal(
+    isPubliclyShareable(publicVideo(), {
+      whitelistEnabled: true,
+      whitelist: new Set([PUBKEY]),
+    }).allowed,
+    true
+  );
+  assert.equal(
+    isPubliclyShareable(publicVideo(), {
+      whitelistEnabled: true,
+      whitelist: new Set(["a".repeat(64)]),
+    }).reason,
+    "not-whitelisted"
+  );
+});
+
+test("gated videos render the generic site card, leaking no metadata", () => {
+  const video = publicVideo();
+  video.isPrivate = true;
+  video.title = "Secret internal recording";
+  video.thumbnail = "https://cdn.example/secret.jpg";
+  const html = render(video);
+
+  assert.equal(html.includes("Secret internal recording"), false);
+  assert.equal(html.includes("secret.jpg"), false);
+  assert.match(html, /og:title" content="bitvid - Decentralized Video Sharing"/);
+  assert.match(html, /og:type" content="website"/);
+  // No player card for a gated video.
+  assert.equal(html.includes("twitter:player"), false);
+});
+
+// --- rendering ------------------------------------------------------------
+
+test("a public video renders a player card pointing at the embed", () => {
+  const html = render(publicVideo());
+
+  assert.match(html, /og:type" content="video\.other"/);
+  assert.match(html, /og:title" content="Why I&#39;m \(sort of\) not worried about AI"/);
+  assert.match(html, /og:image" content="https:\/\/cdn\.example\/thumb\.jpg"/);
+  assert.match(
+    html,
+    /og:video:url" content="https:\/\/bitvid\.network\/embed\.html\?pointer=nevent1abc"/
+  );
+  assert.match(html, /twitter:card" content="player"/);
+  assert.match(
+    html,
+    /twitter:player" content="https:\/\/bitvid\.network\/embed\.html\?pointer=nevent1abc"/
+  );
+  assert.match(html, /twitter:player:width" content="1280"/);
+  assert.match(html, /twitter:player:height" content="720"/);
+  assert.match(html, /<link rel="canonical" href="https:\/\/bitvid\.network\/\?v=nevent1abc"/);
+});
+
+test("without an embed URL it degrades to a summary_large_image card", () => {
+  const html = renderOgHtml({
+    video: publicVideo(),
+    shareUrl: "https://bitvid.network/?v=nevent1abc",
+    fallback: FALLBACK,
+    gate: { allowed: true, reason: "ok" },
+  });
+  assert.match(html, /twitter:card" content="summary_large_image"/);
+  assert.equal(html.includes("twitter:player"), false);
+});
+
+test("the rendered document is well-formed and self-contained", () => {
+  const html = render(publicVideo());
+  assert.match(html, /^<!doctype html>/);
+  assert.match(html, /<\/html>\n$/);
+  // Crawler stub only — it must not pull in the app or any script.
+  assert.equal(/<script/i.test(html), false);
+});
+
+// --- event parsing --------------------------------------------------------
+// bitvid publishes kind 30078 with a v3 JSON body; nostube/slidestr and other
+// NIP-71-native clients publish kind 21/22/34235/34236 with the metadata in
+// TAGS. Parsing only the JSON shape made every NIP-71 video — including the
+// real note this work started from — fall back to the generic card.
+
+test("parseVideoEvent reads the bitvid v3 JSON shape", () => {
+  const parsed = parseVideoEvent({
+    kind: 30078,
+    pubkey: PUBKEY,
+    content: JSON.stringify({
+      version: 3,
+      title: "A bitvid upload",
+      description: "Body text",
+      thumbnail: "https://cdn.example/t.jpg",
+      url: "https://cdn.example/v.mp4",
+      isNsfw: false,
+    }),
+    tags: [],
+  });
+
+  assert.equal(parsed.title, "A bitvid upload");
+  assert.equal(parsed.description, "Body text");
+  assert.equal(parsed.thumbnail, "https://cdn.example/t.jpg");
+  assert.equal(parsed.invalid, false);
+  assert.equal(isPubliclyShareable(parsed).allowed, true);
+});
+
+test("parseVideoEvent reads the NIP-71 tag shape (the real nostube note)", () => {
+  const parsed = parseVideoEvent({
+    kind: 34235,
+    pubkey: PUBKEY,
+    content: "As a creator, and as a leader of a tech company…",
+    tags: [
+      ["d", "b52ab495-ac9c-4a29-a454-aff142a43691"],
+      ["title", "Why I'm (sort of) not worried about AI"],
+      [
+        "imeta",
+        "dim 1280x720",
+        "url https://almond.example/video.m3u8",
+        "m application/vnd.apple.mpegurl",
+        "image https://almond.example/thumb.jpg",
+        "image https://blossom.example/thumb.jpg",
+      ],
+      ["client", "nostube"],
+    ],
+  });
+
+  assert.equal(parsed.title, "Why I'm (sort of) not worried about AI");
+  assert.equal(parsed.thumbnail, "https://almond.example/thumb.jpg");
+  assert.match(parsed.description, /^As a creator/);
+  assert.equal(parsed.invalid, false);
+});
+
+test("parseVideoEvent treats a content-warning tag as NSFW", () => {
+  const parsed = parseVideoEvent({
+    kind: 34235,
+    pubkey: PUBKEY,
+    content: "desc",
+    tags: [["title", "Sensitive"], ["content-warning", "nudity"]],
+  });
+  assert.equal(parsed.isNsfw, true);
+  assert.equal(isPubliclyShareable(parsed).reason, "nsfw");
+});
+
+test("parseVideoEvent rejects untitled and non-video events", () => {
+  assert.equal(
+    parseVideoEvent({ kind: 34235, pubkey: PUBKEY, content: "", tags: [] }).invalid,
+    true
+  );
+  // A plain kind-1 note is not a video.
+  assert.equal(parseVideoEvent({ kind: 1, pubkey: PUBKEY, content: "hi", tags: [] }), null);
+  assert.equal(parseVideoEvent(null), null);
+  assert.equal(parseVideoEvent({}), null);
+});
+
+test("parseVideoEvent survives malformed JSON content", () => {
+  // A kind-30078 whose content is truncated/corrupt must not throw.
+  assert.equal(
+    parseVideoEvent({ kind: 30078, pubkey: PUBKEY, content: "{not json", tags: [] }),
+    null
+  );
+});
+
+test("parseVideoEvent ignores non-http imeta image entries", () => {
+  const parsed = parseVideoEvent({
+    kind: 34235,
+    pubkey: PUBKEY,
+    content: "desc",
+    tags: [
+      ["title", "T"],
+      ["imeta", "image javascript:alert(1)", "image https://ok.example/t.png"],
+    ],
+  });
+  assert.equal(parsed.thumbnail, "https://ok.example/t.png");
+});
+
+// --- crawler detection ----------------------------------------------------
+
+test("known preview crawlers are recognized", () => {
+  for (const ua of [
+    "facebookexternalhit/1.1",
+    "Twitterbot/1.0",
+    "Slackbot-LinkExpanding 1.0",
+    "Mozilla/5.0 (compatible; Discordbot/2.0)",
+    "TelegramBot (like TwitterBot)",
+    "WhatsApp/2.19",
+    "Mozilla/5.0 (compatible; Googlebot/2.1)",
+  ]) {
+    assert.equal(isCrawlerUserAgent(ua), true, `${ua} should match`);
+  }
+});
+
+test("real browsers are NOT treated as crawlers", () => {
+  for (const ua of [
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (X11; Linux x86_64; rv:146.0) Gecko/20100101 Firefox/146.0",
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Version/17.0 Safari/605.1.15",
+    "",
+  ]) {
+    assert.equal(isCrawlerUserAgent(ua), false, `${ua} must not match`);
+  }
+  assert.equal(isCrawlerUserAgent(null), false);
+  assert.equal(isCrawlerUserAgent(undefined), false);
+});
+
+test("the crawler pattern is not sticky/global (no lastIndex state)", () => {
+  // A /g regex would alternate true/false across calls via lastIndex — a
+  // classic bug that would randomly serve crawlers the wrong page.
+  assert.equal(CRAWLER_USER_AGENT_PATTERN.global, false);
+  const ua = "Twitterbot/1.0";
+  assert.equal(isCrawlerUserAgent(ua), true);
+  assert.equal(isCrawlerUserAgent(ua), true);
+  assert.equal(isCrawlerUserAgent(ua), true);
+});
+
+// --- config drift ---------------------------------------------------------
+// api/og.js imports the admin-list identity and relay set from the SAME modules
+// the browser uses, rather than keeping its own copies. These assertions fail
+// loudly if that ever regresses to duplicated constants, because the failure
+// mode otherwise is silent: previews gated forever, or a stale whitelist.
+
+test("api/og.js derives its config from the app, not from copies", async () => {
+  const source = await readFile(new URL("../api/og.js", import.meta.url), "utf8");
+
+  assert.match(source, /from "\.\.\/js\/config\.js"/);
+  assert.match(source, /from "\.\.\/js\/nostr\/toolkit\.js"/);
+  assert.match(source, /from "\.\.\/js\/nostrEventSchemas\.js"/);
+
+  // No hardcoded npub or wss:// literal may reappear in the handler.
+  assert.equal(
+    /npub1[0-9a-z]{20,}/.test(source),
+    false,
+    "admin npub must come from js/config.js, not a literal"
+  );
+  assert.equal(
+    /"wss:\/\//.test(source),
+    false,
+    "relay URLs must come from js/nostr/toolkit.js, not literals"
+  );
+});
+
+test("the admin list d-tag matches what the browser store queries", async () => {
+  const { ADMIN_LIST_NAMESPACE } = await import("../js/config.js");
+  const { ADMIN_LIST_IDENTIFIERS } = await import("../js/nostrEventSchemas.js");
+
+  // Pinned against the live list this instance actually publishes; a namespace
+  // change without a matching relay migration would silently gate everything.
+  assert.equal(
+    `${ADMIN_LIST_NAMESPACE}:${ADMIN_LIST_IDENTIFIERS.whitelist}`,
+    "bitvid:admin:whitelist"
+  );
+  assert.equal(
+    `${ADMIN_LIST_NAMESPACE}:${ADMIN_LIST_IDENTIFIERS.blacklist}`,
+    "bitvid:admin:blacklist"
+  );
+});
diff --git a/vercel.json b/vercel.json
index 8e1b2e0f..e2e36021 100644
--- a/vercel.json
+++ b/vercel.json
@@ -7,6 +7,20 @@
       "unstable": true
     }
   },
+  "rewrites": [
+    {
+      "source": "/",
+      "has": [
+        { "type": "query", "key": "v" },
+        {
+          "type": "header",
+          "key": "user-agent",
+          "value": ".*(facebookexternalhit|Twitterbot|Slackbot|Discordbot|TelegramBot|WhatsApp|LinkedInBot|Pinterest|redditbot|Embedly|Iframely|Mastodon|Bluesky|SkypeUriPreview|vkShare|Googlebot|bingbot|Applebot|YandexBot|DuckDuckBot|Baiduspider|PetalBot|primal).*"
+        }
+      ],
+      "destination": "/api/og"
+    }
+  ],
   "headers": [
     {
       "source": "/sw.min.js",