leak-cli 2026.2.15-beta.1 → 2026.2.16

package/README.md

@@ -255,6 +255,7 @@ npm run leak -- --file ./song.mp3 --pay-to 0x... --price 1 --window 1h --public
 ```
 
 When a local image path is used for `--og-image-url`, leak serves it from `/og-image` and points OG/Twitter metadata at that endpoint.
+Without `--og-image-url`, leak serves a generated raster OG card from `/og.png` (and keeps `/og.svg` for debug/backward compatibility).
 
 This mirrors the behavior of the original Python scaffold implementation:
 
@@ -422,14 +423,15 @@ curl -L -o out.bin "http://localhost:4021/download?token=..."
 
 - `GET /` promo HTML page with OG/Twitter tags
   - `200` while sale is active
-  - `410` once sale has ended
+  - `200` once sale has ended (ended state is shown in page content/metadata)
 - `GET|HEAD /.well-known/skills/index.json` RFC skill discovery index
 - `GET|HEAD /.well-known/skills/leak/SKILL.md` RFC skill metadata markdown
 - `GET|HEAD /.well-known/skills/leak/resource.json` RFC sale/resource metadata (`200` live, `410` ended)
 - `GET /.well-known/leak` legacy discovery endpoint (backward-compatible)
 - `GET /info` machine-readable JSON status (compat endpoint)
-- `GET /og-image` configured OG image file (when using local `--og-image-url` path)
-- `GET /og.svg` fallback OG image (used when `--og-image-url` is not set)
+- `GET|HEAD /og-image` configured OG image file (when using local `--og-image-url` path)
+- `GET|HEAD /og.png` generated default OG image (used when `--og-image-url` is not set)
+- `GET|HEAD /og.svg` debug/backward-compatible OG SVG
 - `GET /health` free health check
 - `GET /download` x402-protected download endpoint
   - active sale: normal x402/token flow
@@ -440,6 +442,7 @@ curl -L -o out.bin "http://localhost:4021/download?token=..."
 ## Troubleshooting
 
 - **`Invalid seller payout address`** → set `--pay-to` / `SELLER_PAY_TO` to a valid Ethereum address (`0x` + 40 hex chars).
+- **Farcaster/Warpcast preview missing OG image** → prefer PNG/JPG (`--og-image-url` or default `/og.png`), ensure OG URLs are absolute `https://` (set `PUBLIC_BASE_URL` if needed), and re-share with a fresh URL variant (example: `/?v=2`) to bypass crawler cache.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leak-cli",
-  "version": "2026.2.15-beta.1",
+  "version": "2026.2.16",
   "description": "Self-hosted pop-up stores for creators -- with agent-friendly automation built in",
   "type": "module",
   "main": "src/index.js",
@@ -28,7 +28,7 @@
     "check:version-sync": "node scripts/check_version_sync.js",
     "check:changelog-version": "node scripts/check_changelog_version.js",
     "check:no-local-paths": "node scripts/check_no_local_paths.js",
-    "check:syntax": "node --check src/index.js && node --check scripts/cli.js && node --check scripts/leak.js && node --check scripts/buy.js && node --check scripts/config.js",
+    "check:syntax": "node --check src/index.js && node --check src/chain_meta.js && node --check scripts/cli.js && node --check scripts/leak.js && node --check scripts/buy.js && node --check scripts/config.js",
     "check:smoke": "node scripts/cli.js --help && node scripts/leak.js --help && node scripts/buy.js --help && node scripts/config.js --help",
     "check:release": "npm run check:version-sync && npm run check:syntax && npm run check:smoke && npm run check:no-local-paths && npm pack --dry-run --cache ./.npm-cache",
     "release:beta": "npm publish --tag beta --provenance",
@@ -51,6 +51,7 @@
   "license": "ISC",
   "dependencies": {
     "@coinbase/cdp-sdk": "^1.12.0",
+    "@resvg/resvg-js": "^2.6.2",
     "@x402/core": "^2.3.0",
     "@x402/evm": "^2.3.0",
     "@x402/express": "^2.3.0",

package/scripts/config.js

@@ -14,6 +14,7 @@ import {
   readConfig,
   writeConfig,
 } from "./config_store.js";
+import { resolveSupportedChain } from "../src/chain_meta.js";
 
 const ALLOWED_FACILITATOR_MODES = new Set(["testnet", "cdp_mainnet"]);
 const ALLOWED_CONFIRMATION_POLICIES = new Set(["confirmed", "optimistic"]);
@@ -217,11 +218,21 @@ async function runWizard({ writeEnv }) {
       sellerPayTo = await askWithDefault(rl, "SELLER_PAY_TO (seller payout address)", sellerPayTo);
     }
 
-    const chainId = await askWithDefault(
+    let chainIdInput = await askWithDefault(
       rl,
       "CHAIN_ID",
       existing.chainId || "eip155:84532",
     );
+    let chainId;
+    while (true) {
+      try {
+        chainId = resolveSupportedChain(chainIdInput).caip2;
+        break;
+      } catch (err) {
+        console.error(err.message || String(err));
+        chainIdInput = await askWithDefault(rl, "CHAIN_ID", chainIdInput || "eip155:84532");
+      }
+    }
 
     let facilitatorMode = await askWithDefault(
       rl,

package/scripts/leak.js

@@ -8,6 +8,7 @@ import { stdin as input, stdout as output } from "node:process";
 import { spawn, spawnSync } from "node:child_process";
 import { isAddress } from "viem";
 import { defaultFacilitatorUrlForMode, readConfig } from "./config_store.js";
+import { resolveSupportedChain } from "../src/chain_meta.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -330,7 +331,17 @@ async function main() {
     process.exit(1);
   }
 
-  const network = args.network || process.env.CHAIN_ID || configDefaults.chainId || "eip155:84532";
+  const networkInput = args.network || process.env.CHAIN_ID || configDefaults.chainId || "eip155:84532";
+  let network;
+  let networkName;
+  try {
+    const networkMeta = resolveSupportedChain(networkInput);
+    network = networkMeta.caip2;
+    networkName = networkMeta.name;
+  } catch (err) {
+    console.error(err.message || String(err));
+    process.exit(1);
+  }
   const port = Number(args.port || process.env.PORT || configDefaults.port || 4021);
   const facilitatorMode = (
     process.env.FACILITATOR_MODE || configDefaults.facilitatorMode || "testnet"
@@ -419,7 +430,7 @@ async function main() {
   console.log(`- price:  ${prompted.price} USDC`);
   console.log(`- window: ${prompted.windowSeconds}s`);
   console.log(`- to:     ${payTo}`);
-  console.log(`- net:    ${network}`);
+  console.log(`- net:    ${network} (${networkName})`);
   console.log(`- mode:   ${confirmationPolicy}`);
   console.log(`- facilitator_mode: ${facilitatorMode}`);
   console.log(`- facilitator_url:  ${facilitatorUrl}`);

package/src/chain_meta.js

@@ -0,0 +1,55 @@
+import { base, baseSepolia } from "viem/chains";
+import { extractChain } from "viem/chains/utils";
+
+const SUPPORTED_CHAINS = [base, baseSepolia];
+
+const SUPPORTED_CHAIN_SUMMARY = [
+  `${base.id} (${base.name})`,
+  `${baseSepolia.id} (${baseSepolia.name})`,
+].join(", ");
+
+function invalidFormatMessage(raw) {
+  const value = String(raw ?? "").trim() || "<empty>";
+  return `Invalid chain identifier '${value}'. Expected eip155:<number>. Supported values: ${SUPPORTED_CHAIN_SUMMARY}.`;
+}
+
+function unsupportedChainMessage(caip2) {
+  return `Unsupported chain '${caip2}'. Supported values: ${SUPPORTED_CHAIN_SUMMARY}.`;
+}
+
+export function parseCaip2Eip155(chainIdString) {
+  const value = String(chainIdString ?? "").trim();
+  const match = value.match(/^eip155:(\d+)$/);
+  if (!match) {
+    throw new Error(invalidFormatMessage(chainIdString));
+  }
+
+  const id = Number(match[1]);
+  if (!Number.isSafeInteger(id) || id <= 0) {
+    throw new Error(invalidFormatMessage(chainIdString));
+  }
+
+  return {
+    id,
+    caip2: `eip155:${id}`,
+  };
+}
+
+export function resolveSupportedChain(chainIdString) {
+  const parsed = parseCaip2Eip155(chainIdString);
+  const chain = extractChain({ chains: SUPPORTED_CHAINS, id: parsed.id });
+  if (!chain) {
+    throw new Error(unsupportedChainMessage(parsed.caip2));
+  }
+
+  return {
+    caip2: parsed.caip2,
+    id: parsed.id,
+    name: chain.name,
+    testnet: Boolean(chain.testnet),
+  };
+}
+
+export function formatChainDisplayName(chainIdString) {
+  return resolveSupportedChain(chainIdString).name;
+}

package/src/index.js

@@ -4,11 +4,13 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
+import { Resvg } from "@resvg/resvg-js";
 
 import { x402ResourceServer } from "@x402/core/server";
 import { x402HTTPResourceServer, HTTPFacilitatorClient } from "@x402/core/http";
 import { ExactEvmScheme } from "@x402/evm/exact/server";
 import { isAddress } from "viem";
+import { resolveSupportedChain } from "./chain_meta.js";
 
 dotenv.config();
 
@@ -73,18 +75,27 @@ const FACILITATOR_MODE = (process.env.FACILITATOR_MODE || "testnet").trim();
 const CDP_API_KEY_ID = (process.env.CDP_API_KEY_ID || "").trim();
 const CDP_API_KEY_SECRET = (process.env.CDP_API_KEY_SECRET || "").trim();
 const DEFAULT_TESTNET_FACILITATOR_URL = "https://x402.org/facilitator";
-const DEFAULT_CDP_MAINNET_FACILITATOR_URL = "https://api.cdp.coinbase.com/platform/v2/x402";
+const DEFAULT_CDP_MAINNET_FACILITATOR_URL =
+  "https://api.cdp.coinbase.com/platform/v2/x402";
 const FACILITATOR_URL = (
   process.env.FACILITATOR_URL ||
-  (FACILITATOR_MODE === "cdp_mainnet" ? DEFAULT_CDP_MAINNET_FACILITATOR_URL : DEFAULT_TESTNET_FACILITATOR_URL)
+  (FACILITATOR_MODE === "cdp_mainnet"
+    ? DEFAULT_CDP_MAINNET_FACILITATOR_URL
+    : DEFAULT_TESTNET_FACILITATOR_URL)
+).trim();
+const SELLER_PAY_TO = String(
+  process.env.SELLER_PAY_TO || process.env.PAY_TO || "",
 ).trim();
-const SELLER_PAY_TO = String(process.env.SELLER_PAY_TO || process.env.PAY_TO || "").trim();
 const PRICE_USD = process.env.PRICE_USD || "1.00";
-const CHAIN_ID = process.env.CHAIN_ID || process.env.NETWORK || "eip155:84532";
+const RAW_CHAIN_ID =
+  process.env.CHAIN_ID || process.env.NETWORK || "eip155:84532";
 const ARTIFACT_PATH = process.env.ARTIFACT_PATH || process.env.PROTECTED_FILE;
 const WINDOW_SECONDS = Number(process.env.WINDOW_SECONDS || 3600);
 const MAX_GRANTS = parsePositiveInt(process.env.MAX_GRANTS, 10000);
-const GRANT_SWEEP_SECONDS = parsePositiveInt(process.env.GRANT_SWEEP_SECONDS, 60);
+const GRANT_SWEEP_SECONDS = parsePositiveInt(
+  process.env.GRANT_SWEEP_SECONDS,
+  60,
+);
 
 const CONFIRMATION_POLICY = process.env.CONFIRMATION_POLICY || "confirmed"; // optimistic|confirmed
 const CONFIRMATIONS_REQUIRED = Number(process.env.CONFIRMATIONS_REQUIRED || 1);
@@ -97,10 +108,16 @@ const OG_IMAGE_URL = (process.env.OG_IMAGE_URL || "").trim();
 const OG_IMAGE_PATH_RAW = (process.env.OG_IMAGE_PATH || "").trim();
 const PUBLIC_BASE_URL = (process.env.PUBLIC_BASE_URL || "").trim();
 const OG_IMAGE_PATH = OG_IMAGE_PATH_RAW
-  ? (path.isAbsolute(OG_IMAGE_PATH_RAW) ? OG_IMAGE_PATH_RAW : path.join(__dirname, "..", OG_IMAGE_PATH_RAW))
+  ? path.isAbsolute(OG_IMAGE_PATH_RAW)
+    ? OG_IMAGE_PATH_RAW
+    : path.join(__dirname, "..", OG_IMAGE_PATH_RAW)
   : "";
+const OG_IMAGE_CACHE_CONTROL = "public, max-age=60";
+const OG_IMAGE_WIDTH = 1200;
+const OG_IMAGE_HEIGHT = 630;
 const SKILL_NAME = "leak";
-const SKILL_DESCRIPTION = "Sell or buy x402-gated digital content using the leak CLI tool";
+const SKILL_DESCRIPTION =
+  "Sell or buy x402-gated digital content using the leak CLI tool";
 const SKILL_SOURCE = "clawhub";
 const SKILL_INSTALL_COMMAND = "clawhub install leak";
 const WELL_KNOWN_CACHE_CONTROL = "public, max-age=60";
@@ -108,24 +125,53 @@ const LEGACY_DISCOVERY_DEPRECATION =
   "Deprecated endpoint; use /.well-known/skills/index.json for RFC-compatible discovery.";
 
 const SALE_START_TS = parsePositiveInt(process.env.SALE_START_TS, now());
-const SALE_END_TS = parsePositiveInt(process.env.SALE_END_TS, SALE_START_TS + WINDOW_SECONDS);
-const ENDED_WINDOW_SECONDS = parseNonNegativeInt(process.env.ENDED_WINDOW_SECONDS, 0);
-const IS_BASE_MAINNET = CHAIN_ID === "eip155:8453";
+const SALE_END_TS = parsePositiveInt(
+  process.env.SALE_END_TS,
+  SALE_START_TS + WINDOW_SECONDS,
+);
+const ENDED_WINDOW_SECONDS = parseNonNegativeInt(
+  process.env.ENDED_WINDOW_SECONDS,
+  0,
+);
+
+let CHAIN_META;
+try {
+  CHAIN_META = resolveSupportedChain(RAW_CHAIN_ID);
+} catch (err) {
+  console.error(err?.message || String(err));
+  process.exit(1);
+}
+
+const CHAIN_ID = CHAIN_META.caip2;
+const CHAIN_NAME = CHAIN_META.name;
+const CHAIN_NUMERIC_ID = CHAIN_META.id;
+const IS_BASE_MAINNET = CHAIN_NUMERIC_ID === 8453;
 
 if (!new Set(["testnet", "cdp_mainnet"]).has(FACILITATOR_MODE)) {
-  console.error("Invalid FACILITATOR_MODE. Supported values: testnet, cdp_mainnet");
+  console.error(
+    "Invalid FACILITATOR_MODE. Supported values: testnet, cdp_mainnet",
+  );
   process.exit(1);
 }
 
 if (IS_BASE_MAINNET && FACILITATOR_MODE !== "cdp_mainnet") {
-  console.error("Invalid config: CHAIN_ID=eip155:8453 requires FACILITATOR_MODE=cdp_mainnet.");
-  console.error("Set FACILITATOR_MODE=cdp_mainnet and configure CDP_API_KEY_ID/CDP_API_KEY_SECRET.");
+  console.error(
+    "Invalid config: CHAIN_ID=eip155:8453 requires FACILITATOR_MODE=cdp_mainnet.",
+  );
+  console.error(
+    "Set FACILITATOR_MODE=cdp_mainnet and configure CDP_API_KEY_ID/CDP_API_KEY_SECRET.",
+  );
   process.exit(1);
 }
 
-if (FACILITATOR_MODE === "cdp_mainnet" && (!CDP_API_KEY_ID || !CDP_API_KEY_SECRET)) {
+if (
+  FACILITATOR_MODE === "cdp_mainnet" &&
+  (!CDP_API_KEY_ID || !CDP_API_KEY_SECRET)
+) {
   console.error("Missing CDP credentials for FACILITATOR_MODE=cdp_mainnet.");
-  console.error("Set CDP_API_KEY_ID and CDP_API_KEY_SECRET in your environment.");
+  console.error(
+    "Set CDP_API_KEY_ID and CDP_API_KEY_SECRET in your environment.",
+  );
   process.exit(1);
 }
 
@@ -144,7 +190,9 @@ if (!ARTIFACT_PATH) {
 }
 
 function absArtifactPath() {
-  return path.isAbsolute(ARTIFACT_PATH) ? ARTIFACT_PATH : path.join(__dirname, "..", ARTIFACT_PATH);
+  return path.isAbsolute(ARTIFACT_PATH)
+    ? ARTIFACT_PATH
+    : path.join(__dirname, "..", ARTIFACT_PATH);
 }
 
 const ARTIFACT_NAME = path.basename(absArtifactPath());
@@ -185,25 +233,35 @@ function imageMimeTypeFromPath(filePath) {
   return null;
 }
 
+function imageMimeTypeFromUrl(urlString) {
+  try {
+    const parsed = new URL(String(urlString));
+    return imageMimeTypeFromPath(parsed.pathname);
+  } catch {
+    return null;
+  }
+}
+
 function classifyFacilitatorError(err) {
   const msg = (err?.message || String(err)).toLowerCase();
   if (
-    msg.includes("401")
-    || msg.includes("403")
-    || msg.includes("unauthorized")
-    || msg.includes("forbidden")
-    || msg.includes("authorization")
-    || msg.includes("bearer")
-    || msg.includes("jwt")
-    || msg.includes("api key")
-    || msg.includes("invalid key format")
+    msg.includes("401") ||
+    msg.includes("403") ||
+    msg.includes("unauthorized") ||
+    msg.includes("forbidden") ||
+    msg.includes("authorization") ||
+    msg.includes("bearer") ||
+    msg.includes("jwt") ||
+    msg.includes("api key") ||
+    msg.includes("invalid key format")
   ) {
     return "auth";
   }
   if (
-    msg.includes("does not support scheme")
-    || msg.includes("unsupported")
-    || (msg.includes("network") && (msg.includes("mismatch") || msg.includes("invalid")))
+    msg.includes("does not support scheme") ||
+    msg.includes("unsupported") ||
+    (msg.includes("network") &&
+      (msg.includes("mismatch") || msg.includes("invalid")))
   ) {
     return "network";
   }
@@ -214,16 +272,22 @@ function printFacilitatorHint(err) {
   const kind = classifyFacilitatorError(err);
   if (kind === "auth") {
     console.error("[hint] Facilitator authentication failed.");
-    console.error("[hint] For mainnet, set FACILITATOR_MODE=cdp_mainnet and valid CDP_API_KEY_ID/CDP_API_KEY_SECRET.");
+    console.error(
+      "[hint] For mainnet, set FACILITATOR_MODE=cdp_mainnet and valid CDP_API_KEY_ID/CDP_API_KEY_SECRET.",
+    );
     return;
   }
   if (kind === "network") {
     console.error("[hint] Facilitator/network mismatch.");
-    console.error("[hint] Verify CHAIN_ID and FACILITATOR_URL/FACILITATOR_MODE are aligned.");
+    console.error(
+      "[hint] Verify CHAIN_ID and FACILITATOR_URL/FACILITATOR_MODE are aligned.",
+    );
     return;
   }
   if (IS_BASE_MAINNET) {
-    console.error("[hint] Base mainnet requires a mainnet-capable facilitator and valid auth.");
+    console.error(
+      "[hint] Base mainnet requires a mainnet-capable facilitator and valid auth.",
+    );
   }
 }
 
@@ -244,7 +308,9 @@ function createCdpAuthHeadersFactory() {
     try {
       ({ generateJwt } = await import("@coinbase/cdp-sdk/auth"));
     } catch {
-      throw new Error("CDP auth helper unavailable. Install @coinbase/cdp-sdk and retry.");
+      throw new Error(
+        "CDP auth helper unavailable. Install @coinbase/cdp-sdk and retry.",
+      );
     }
 
     const createAuthorization = async (requestMethod, requestPath) => {
@@ -274,7 +340,9 @@ async function preflightCdpAuth() {
   try {
     ({ generateJwt } = await import("@coinbase/cdp-sdk/auth"));
   } catch {
-    console.error("[startup] Missing CDP auth dependency. Install @coinbase/cdp-sdk.");
+    console.error(
+      "[startup] Missing CDP auth dependency. Install @coinbase/cdp-sdk.",
+    );
     process.exit(1);
   }
 
@@ -301,19 +369,36 @@ function promoModel(req) {
   const baseUrl = baseUrlFromReq(req);
   const promoUrl = `${baseUrl}/`;
   const downloadUrl = `${baseUrl}/download`;
-  const imageUrl = isAbsoluteHttpUrl(OG_IMAGE_URL)
-    ? OG_IMAGE_URL
-    : (OG_IMAGE_PATH ? `${baseUrl}/og-image` : `${baseUrl}/og.svg`);
   const ogTitle = OG_TITLE || ARTIFACT_NAME;
   const ogDescription =
-    OG_DESCRIPTION ||
-    `Pay ${PRICE_USD} on ${CHAIN_ID} to unlock ${ARTIFACT_NAME}. Access is time-limited and agent-assisted via /download.`;
+    OG_DESCRIPTION || `$${PRICE_USD} to unlock ${ARTIFACT_NAME}`;
+  const imageAlt = `${ogTitle} preview image`;
+
+  let imageUrl = `${baseUrl}/og.png`;
+  let imageType = "image/png";
+  let imageWidth = OG_IMAGE_WIDTH;
+  let imageHeight = OG_IMAGE_HEIGHT;
+  if (isAbsoluteHttpUrl(OG_IMAGE_URL)) {
+    imageUrl = OG_IMAGE_URL;
+    imageType = imageMimeTypeFromUrl(OG_IMAGE_URL) || "";
+    imageWidth = null;
+    imageHeight = null;
+  } else if (OG_IMAGE_PATH) {
+    imageUrl = `${baseUrl}/og-image`;
+    imageType = imageMimeTypeFromPath(OG_IMAGE_PATH) || "";
+    imageWidth = null;
+    imageHeight = null;
+  }
 
   return {
     baseUrl,
     promoUrl,
     downloadUrl,
     imageUrl,
+    imageType,
+    imageWidth,
+    imageHeight,
+    imageAlt,
     ogTitle,
     ogDescription,
     saleStartTs: SALE_START_TS,
@@ -379,7 +464,8 @@ Do not explain x402 internals unless the user explicitly asks.
 function buildAgentQuickPath(promoUrl, downloadUrl) {
   const safePromoUrl = String(promoUrl || "").trim();
   const safeDownloadUrl = String(downloadUrl || "").trim();
-  const buyTarget = safePromoUrl || safeDownloadUrl || "<promo_or_download_url>";
+  const buyTarget =
+    safePromoUrl || safeDownloadUrl || "<promo_or_download_url>";
   const buyScriptCommand = `bash skills/leak/scripts/buy.sh "${buyTarget}" --buyer-private-key-file <buyer_key_file_path>`;
 
   return {
@@ -422,9 +508,95 @@ function renderAgentQuickPathHtmlBlock(fastPath) {
     </section>`;
 }
 
+function renderPromoSharedContent({ promoUrl, downloadUrl, saleEndTs }) {
+  const fastPath = buildAgentQuickPath(promoUrl, downloadUrl);
+  const expiresIso = new Date(saleEndTs * 1000).toISOString();
+  const humanActionText = "Just send the link to this page to your agent";
+
+  return `
+    <div class="kv"><strong>Price:</strong> ${escapeHtml(PRICE_USD)} USD equivalent</div>
+    <div class="kv"><strong>Network:</strong> ${escapeHtml(CHAIN_NAME)} (${escapeHtml(CHAIN_ID)})</div>
+    <div class="kv"><strong>Sale end:</strong> <span id="sale-end-local" data-sale-end-iso="${escapeHtml(expiresIso)}">${escapeHtml(expiresIso)}</span></div>
+    ${renderAgentQuickPathHtmlBlock(fastPath)}
+
+    <div class="prompt-head">
+      <p><strong>Human action</strong></p>
+      <button class="copy-btn" id="copy-link-btn" type="button" aria-label="Copy page link">Copy link</button>
+      <span class="copy-status" id="copy-link-status" aria-live="polite"></span>
+    </div>
+    <pre id="human-action-text">${escapeHtml(humanActionText)}</pre>
+    <p class="install-note">
+      Want to know more about <code>leak</code>? Visit
+      <a href="https://github.com/eucalyptus-viminalis/leak">github.com/eucalyptus-viminalis/leak</a>
+      or search for leak on clawhub.
+    </p>
+  `;
+}
+
+function renderPromoSharedClientScript(promoUrl) {
+  return `<script>
+    (() => {
+      const button = document.getElementById("copy-link-btn");
+      const status = document.getElementById("copy-link-status");
+      const safePromoUrl = ${toSafeJsonForScript(promoUrl)};
+      const saleEndLocal = document.getElementById("sale-end-local");
+
+      if (saleEndLocal) {
+        const saleEndIso = saleEndLocal.getAttribute("data-sale-end-iso") || "";
+        const saleEndDate = new Date(saleEndIso);
+        if (!Number.isNaN(saleEndDate.getTime())) {
+          try {
+            const formatter = new Intl.DateTimeFormat(undefined, { dateStyle: "medium", timeStyle: "medium" });
+            saleEndLocal.textContent = formatter.format(saleEndDate) + " (local time)";
+          } catch {
+            saleEndLocal.textContent = saleEndDate.toLocaleString() + " (local time)";
+          }
+        }
+      }
+
+      if (!button || !safePromoUrl) return;
+
+      const setStatus = (text) => {
+        if (status) status.textContent = text;
+      };
+
+      button.addEventListener("click", async () => {
+        const original = "Copy link";
+        try {
+          if (navigator.clipboard?.writeText) {
+            await navigator.clipboard.writeText(safePromoUrl);
+          } else {
+            const ta = document.createElement("textarea");
+            ta.value = safePromoUrl;
+            ta.setAttribute("readonly", "");
+            ta.style.position = "absolute";
+            ta.style.left = "-9999px";
+            document.body.appendChild(ta);
+            ta.select();
+            document.execCommand("copy");
+            document.body.removeChild(ta);
+          }
+          button.textContent = "Copied";
+          setStatus("Copied to clipboard.");
+          setTimeout(() => {
+            button.textContent = original;
+            setStatus("");
+          }, 1500);
+        } catch {
+          setStatus("Copy failed. Select and copy manually.");
+        }
+      });
+    })();
+  </script>`;
+}
+
 function renderUnpaidDownloadGuidancePage(requestUrl) {
   const urls = urlsForQuickPathFromRequestUrl(requestUrl);
-  const fastPath = buildAgentQuickPath(urls.promoUrl, urls.downloadUrl);
+  const sharedContent = renderPromoSharedContent({
+    promoUrl: urls.promoUrl,
+    downloadUrl: urls.downloadUrl,
+    saleEndTs: SALE_END_TS,
+  });
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -437,8 +609,20 @@ function renderUnpaidDownloadGuidancePage(requestUrl) {
     h1 { margin: 0 0 12px; font-size: 24px; }
     h2 { margin: 0 0 10px; font-size: 18px; }
     p { line-height: 1.5; }
+    .kv { margin: 14px 0; font-size: 14px; color: #333; }
     code, pre { background: #f0f0eb; border-radius: 6px; padding: 2px 6px; }
     pre { padding: 10px; overflow-x: auto; }
+    .prompt-head { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+    .prompt-head p { margin: 0; }
+    button.copy-btn { border: 1px solid #bdbdae; background: #f5f5ef; color: #1f1f1f; border-radius: 6px; padding: 6px 10px; cursor: pointer; font: inherit; font-size: 13px; }
+    button.copy-btn:hover { background: #ecece4; }
+    .copy-status { font-size: 12px; color: #3f3f3f; min-height: 1em; }
+    .install-note { margin-top: 16px; font-size: 13px; color: #2f2f2f; }
+    .install-note a { color: #1f1f1f; }
+    .agent-quick-path { margin: 16px 0; padding: 14px; border: 1px solid #d8d8d0; border-radius: 8px; background: #fafaf6; }
+    .agent-quick-path h2 { margin: 0 0 8px; font-size: 18px; }
+    .agent-quick-path ol { margin: 8px 0 8px 20px; }
+    .agent-quick-path p { margin: 8px 0 0; }
     ol { margin: 10px 0 12px 20px; }
   </style>
 </head>
@@ -446,10 +630,10 @@ function renderUnpaidDownloadGuidancePage(requestUrl) {
   <main class="card">
     <h1>402 Payment Required</h1>
     <p>This URL is paywalled. Use the leak skill fast path below.</p>
-    <p><strong>Promo URL:</strong> <code>${escapeHtml(fastPath.promoUrl)}</code></p>
-    <p><strong>x402 URL:</strong> <code>${escapeHtml(fastPath.downloadUrl)}</code></p>
-    ${renderAgentQuickPathHtmlBlock(fastPath)}
+    <div class="kv"><strong>Resource:</strong> ${escapeHtml(ARTIFACT_NAME)}</div>
+    ${sharedContent}
   </main>
+  ${renderPromoSharedClientScript(urls.promoUrl)}
 </body>
 </html>`;
 }
@@ -493,7 +677,6 @@ function renderPromoPage(model, { ended }) {
     ? `This leak has ended. ${model.ogDescription}`
     : model.ogDescription;
   const expiresIso = new Date(model.saleEndTs * 1000).toISOString();
-  const fastPath = buildAgentQuickPath(model.promoUrl, model.downloadUrl);
   const jsonLd = {
     "@context": "https://schema.org",
     "@type": "Product",
@@ -507,19 +690,47 @@ function renderPromoPage(model, { ended }) {
       url: model.downloadUrl,
       price: PRICE_USD,
       priceCurrency: "USD",
-      availability: ended ? "https://schema.org/OutOfStock" : "https://schema.org/InStock",
+      availability: ended
+        ? "https://schema.org/OutOfStock"
+        : "https://schema.org/InStock",
       validThrough: expiresIso,
     },
     additionalProperty: [
       { "@type": "PropertyValue", name: "paymentProtocol", value: "x402" },
-      { "@type": "PropertyValue", name: "paymentSettlementCurrency", value: "USDC" },
+      {
+        "@type": "PropertyValue",
+        name: "paymentSettlementCurrency",
+        value: "USDC",
+      },
       { "@type": "PropertyValue", name: "network", value: CHAIN_ID },
-      { "@type": "PropertyValue", name: "downloadUrl", value: model.downloadUrl },
+      {
+        "@type": "PropertyValue",
+        name: "downloadUrl",
+        value: model.downloadUrl,
+      },
     ],
   };
   const safeJsonLd = toSafeJsonForScript(jsonLd);
-
-  const humanActionText = "Just send the link to this page to your agent";
+  const secureImageUrl = model.imageUrl.startsWith("https://")
+    ? model.imageUrl
+    : "";
+  const ogImageSecureUrlMeta = secureImageUrl
+    ? `<meta property="og:image:secure_url" content="${escapeHtml(secureImageUrl)}" />`
+    : "";
+  const ogImageTypeMeta = model.imageType
+    ? `<meta property="og:image:type" content="${escapeHtml(model.imageType)}" />`
+    : "";
+  const ogImageWidthMeta = Number.isFinite(model.imageWidth)
+    ? `<meta property="og:image:width" content="${model.imageWidth}" />`
+    : "";
+  const ogImageHeightMeta = Number.isFinite(model.imageHeight)
+    ? `<meta property="og:image:height" content="${model.imageHeight}" />`
+    : "";
+  const sharedContent = renderPromoSharedContent({
+    promoUrl: model.promoUrl,
+    downloadUrl: model.downloadUrl,
+    saleEndTs: model.saleEndTs,
+  });
 
   return `<!doctype html>
 <html lang="en">
@@ -534,11 +745,17 @@ function renderPromoPage(model, { ended }) {
   <meta property="og:title" content="${escapeHtml(pageTitle)}" />
   <meta property="og:description" content="${escapeHtml(description)}" />
   <meta property="og:image" content="${escapeHtml(model.imageUrl)}" />
+  ${ogImageSecureUrlMeta}
+  ${ogImageTypeMeta}
+  ${ogImageWidthMeta}
+  ${ogImageHeightMeta}
+  <meta property="og:image:alt" content="${escapeHtml(model.imageAlt)}" />
 
   <meta name="twitter:card" content="summary_large_image" />
   <meta name="twitter:title" content="${escapeHtml(pageTitle)}" />
   <meta name="twitter:description" content="${escapeHtml(description)}" />
   <meta name="twitter:image" content="${escapeHtml(model.imageUrl)}" />
+  <meta name="twitter:image:alt" content="${escapeHtml(model.imageAlt)}" />
 
   <script type="application/ld+json">${safeJsonLd}</script>
   <style>
@@ -569,62 +786,9 @@ function renderPromoPage(model, { ended }) {
     <div class="state">${escapeHtml(stateLabel)}</div>
     <h1>${escapeHtml(pageTitle)}</h1>
 
-    <div class="kv"><strong>Price:</strong> ${escapeHtml(PRICE_USD)} USD equivalent</div>
-    <div class="kv"><strong>Network:</strong> ${escapeHtml(CHAIN_ID)}</div>
-    <div class="kv"><strong>Sale end:</strong> ${escapeHtml(expiresIso)}</div>
-    ${renderAgentQuickPathHtmlBlock(fastPath)}
-
-    <div class="prompt-head">
-      <p><strong>Human action</strong></p>
-      <button class="copy-btn" id="copy-link-btn" type="button" aria-label="Copy page link">Copy link</button>
-      <span class="copy-status" id="copy-link-status" aria-live="polite"></span>
-    </div>
-    <pre id="human-action-text">${escapeHtml(humanActionText)}</pre>
-    <p class="install-note">
-      Need help setting this up? Install leak at
-      <a href="https://github.com/eucalyptus-viminalis/leak">github.com/eucalyptus-viminalis/leak</a>
-      or search for leak on clawhub.
-    </p>
+    ${sharedContent}
   </main>
-  <script>
-    (() => {
-      const button = document.getElementById("copy-link-btn");
-      const status = document.getElementById("copy-link-status");
-      const promoUrl = ${toSafeJsonForScript(model.promoUrl)};
-      if (!button || !promoUrl) return;
-
-      const setStatus = (text) => {
-        if (status) status.textContent = text;
-      };
-
-      button.addEventListener("click", async () => {
-        const original = "Copy link";
-        try {
-          if (navigator.clipboard?.writeText) {
-            await navigator.clipboard.writeText(promoUrl);
-          } else {
-            const ta = document.createElement("textarea");
-            ta.value = promoUrl;
-            ta.setAttribute("readonly", "");
-            ta.style.position = "absolute";
-            ta.style.left = "-9999px";
-            document.body.appendChild(ta);
-            ta.select();
-            document.execCommand("copy");
-            document.body.removeChild(ta);
-          }
-          button.textContent = "Copied";
-          setStatus("Copied to clipboard.");
-          setTimeout(() => {
-            button.textContent = original;
-            setStatus("");
-          }, 1500);
-        } catch {
-          setStatus("Copy failed. Select and copy manually.");
-        }
-      });
-    })();
-  </script>
+  ${renderPromoSharedClientScript(model.promoUrl)}
 </body>
 </html>`;
 }
@@ -632,7 +796,7 @@ function renderPromoPage(model, { ended }) {
 function renderOgSvg(req) {
   const model = promoModel(req);
   const title = model.ogTitle;
-  const subtitle = `Pay ${PRICE_USD} on ${CHAIN_ID}`;
+  const subtitle = `$${PRICE_USD} on ${CHAIN_NAME}`;
   const status = saleEnded() ? "ENDED" : "LIVE";
 
   return `<?xml version="1.0" encoding="UTF-8"?>
@@ -645,13 +809,25 @@ function renderOgSvg(req) {
   </defs>
   <rect width="1200" height="630" fill="url(#bg)"/>
   <rect x="64" y="64" width="1072" height="502" rx="18" fill="#ffffff" stroke="#bdbdae"/>
-  <text x="96" y="170" font-size="32" font-family="monospace" fill="#222">${escapeXml(status)} LEAK</text>
+  <text x="96" y="170" font-size="32" font-family="monospace" fill="#222">${escapeXml(status)}</text>
   <text x="96" y="250" font-size="52" font-family="monospace" fill="#111">${escapeXml(title)}</text>
   <text x="96" y="330" font-size="30" font-family="monospace" fill="#333">${escapeXml(subtitle)}</text>
-  <text x="96" y="404" font-size="22" font-family="monospace" fill="#444">x402 via /download</text>
+  <text x="96" y="404" font-size="22" font-family="monospace" fill="#444">Share this link with your OpenClaw agent to download</text>
 </svg>`;
 }
 
+function renderOgPng(req) {
+  const svg = renderOgSvg(req);
+  const resvg = new Resvg(svg, {
+    fitTo: {
+      mode: "width",
+      value: OG_IMAGE_WIDTH,
+    },
+  });
+  const pngData = resvg.render();
+  return pngData.asPng();
+}
+
 // In-memory grants (v1). Later: SQLite.
 /** @type {Map<string, { token: string, expiresAt: number, downloadsLeft: number|null }>} */
 const GRANTS = new Map();
@@ -692,13 +868,15 @@ function validateAndConsumeToken(token) {
     return { ok: false, reason: "token expired" };
   }
   if (g.downloadsLeft !== null) {
-    if (g.downloadsLeft <= 0) return { ok: false, reason: "download limit reached" };
+    if (g.downloadsLeft <= 0)
+      return { ok: false, reason: "download limit reached" };
     g.downloadsLeft -= 1;
   }
   return { ok: true };
 }
 
 const app = express();
+app.set("trust proxy", true);
 
 // x402 core server + HTTP wrapper
 await preflightCdpAuth();
@@ -707,7 +885,10 @@ if (FACILITATOR_MODE === "cdp_mainnet") {
   facilitatorConfig.createAuthHeaders = createCdpAuthHeadersFactory();
 }
 const facilitatorClient = new HTTPFacilitatorClient(facilitatorConfig);
-const coreServer = new x402ResourceServer(facilitatorClient).register(CHAIN_ID, new ExactEvmScheme());
+const coreServer = new x402ResourceServer(facilitatorClient).register(
+  CHAIN_ID,
+  new ExactEvmScheme(),
+);
 
 // Route config for x402HTTPResourceServer
 const routes = {
@@ -735,7 +916,9 @@ try {
   await httpServer.initialize();
 } catch (err) {
   console.error("[startup] Failed to initialize x402 route configuration.");
-  console.error(`[startup] facilitator=${FACILITATOR_URL} mode=${FACILITATOR_MODE} network=${CHAIN_ID}`);
+  console.error(
+    `[startup] facilitator=${FACILITATOR_URL} mode=${FACILITATOR_MODE} network=${CHAIN_ID}`,
+  );
   if (Array.isArray(err?.errors) && err.errors.length > 0) {
     for (const e of err.errors) {
       console.error(`[startup] ${e.message || JSON.stringify(e)}`);
@@ -754,9 +937,8 @@ setInterval(() => {
 app.get("/", (req, res) => {
   const model = promoModel(req);
   const ended = saleEnded();
-  const status = ended ? 410 : 200;
   res.setHeader("Content-Type", "text/html; charset=utf-8");
-  return res.status(status).send(renderPromoPage(model, { ended }));
+  return res.status(200).send(renderPromoPage(model, { ended }));
 });
 
 app.get("/info", (req, res) => {
@@ -779,9 +961,34 @@ app.get("/info", (req, res) => {
 
 app.get("/og.svg", (req, res) => {
   res.setHeader("Content-Type", "image/svg+xml; charset=utf-8");
-  res.setHeader("Cache-Control", "public, max-age=60");
+  res.setHeader("Cache-Control", OG_IMAGE_CACHE_CONTROL);
+  if (req.method === "HEAD") return res.status(200).end();
   return res.status(200).send(renderOgSvg(req));
 });
+app.head("/og.svg", (req, res) => {
+  res.setHeader("Content-Type", "image/svg+xml; charset=utf-8");
+  res.setHeader("Cache-Control", OG_IMAGE_CACHE_CONTROL);
+  return res.status(200).end();
+});
+
+app.get("/og.png", (req, res) => {
+  let png;
+  try {
+    png = renderOgPng(req);
+  } catch (err) {
+    console.error(`[og] failed to render png: ${err?.message || String(err)}`);
+    return res.status(500).json({ error: "og image unavailable" });
+  }
+  res.setHeader("Content-Type", "image/png");
+  res.setHeader("Cache-Control", OG_IMAGE_CACHE_CONTROL);
+  if (req.method === "HEAD") return res.status(200).end();
+  return res.status(200).send(png);
+});
+app.head("/og.png", (req, res) => {
+  res.setHeader("Content-Type", "image/png");
+  res.setHeader("Cache-Control", OG_IMAGE_CACHE_CONTROL);
+  return res.status(200).end();
+});
 
 app.get("/og-image", (req, res) => {
   if (!OG_IMAGE_PATH) {
@@ -807,7 +1014,8 @@ app.get("/og-image", (req, res) => {
   }
 
   res.setHeader("Content-Type", contentType);
-  res.setHeader("Cache-Control", "public, max-age=60");
+  res.setHeader("Cache-Control", OG_IMAGE_CACHE_CONTROL);
+  if (req.method === "HEAD") return res.status(200).end();
   const stream = fs.createReadStream(OG_IMAGE_PATH);
   stream.on("error", () => {
     if (!res.headersSent) {
@@ -818,6 +1026,30 @@ app.get("/og-image", (req, res) => {
   });
   return stream.pipe(res);
 });
+app.head("/og-image", (req, res) => {
+  if (!OG_IMAGE_PATH) {
+    return res.status(404).end();
+  }
+  if (!fs.existsSync(OG_IMAGE_PATH)) {
+    return res.status(404).end();
+  }
+  let stat;
+  try {
+    stat = fs.statSync(OG_IMAGE_PATH);
+  } catch {
+    return res.status(404).end();
+  }
+  if (!stat.isFile()) {
+    return res.status(404).end();
+  }
+  const contentType = imageMimeTypeFromPath(OG_IMAGE_PATH);
+  if (!contentType) {
+    return res.status(404).end();
+  }
+  res.setHeader("Content-Type", contentType);
+  res.setHeader("Cache-Control", OG_IMAGE_CACHE_CONTROL);
+  return res.status(200).end();
+});
 
 app.get("/health", (req, res) => {
   res.json({ ok: true, ts: now() });
@@ -848,7 +1080,8 @@ app.get("/.well-known/leak", (req, res) => {
         source: SKILL_SOURCE,
         install_command: SKILL_INSTALL_COMMAND,
       },
-      message: "This leak has expired, but you can install the leak skill for future purchases",
+      message:
+        "This leak has expired, but you can install the leak skill for future purchases",
       deprecation: LEGACY_DISCOVERY_DEPRECATION,
       discovery_index_url: discoveryPath,
       rfc_resource_url: rfcResourcePath,
@@ -893,6 +1126,7 @@ app.use("/download", async (req, res, next) => {
   // NOTE: because this middleware is mounted at "/download", Express strips the mount
   // path and `req.path` becomes "/". x402 route matching needs the *full* path.
   const fullPath = `${req.baseUrl || ""}${req.path || ""}`;
+  const requestUrl = `${req.protocol}://${req.get("host")}${req.originalUrl}`;
 
   const adapter = {
     getHeader(name) {
@@ -900,8 +1134,10 @@ app.use("/download", async (req, res, next) => {
       if (v) return v;
       // legacy support: treat X-PAYMENT as PAYMENT-SIGNATURE (same base64 JSON format)
       const lower = String(name).toLowerCase();
-      if (lower === "payment-signature") return req.get("x-payment") || undefined;
-      if (lower === "payment-required") return req.get("payment-required") || undefined;
+      if (lower === "payment-signature")
+        return req.get("x-payment") || undefined;
+      if (lower === "payment-required")
+        return req.get("payment-required") || undefined;
       return undefined;
     },
     getMethod() {
@@ -911,7 +1147,7 @@ app.use("/download", async (req, res, next) => {
       return fullPath;
     },
     getUrl() {
-      return `${req.protocol}://${req.get("host")}${req.originalUrl}`;
+      return requestUrl;
     },
     getAcceptHeader() {
       return req.get("accept") || "";
@@ -932,7 +1168,9 @@ app.use("/download", async (req, res, next) => {
       method: req.method,
     });
   } catch (err) {
-    console.error(`[x402] payment handshake failed: ${err?.message || String(err)}`);
+    console.error(
+      `[x402] payment handshake failed: ${err?.message || String(err)}`,
+    );
     printFacilitatorHint(err);
     return res.status(502).json({ error: "payment gateway unavailable" });
   }
@@ -940,7 +1178,21 @@ app.use("/download", async (req, res, next) => {
   if (result.type === "no-payment-required") return next();
 
   if (result.type === "payment-error") {
-    for (const [k, v] of Object.entries(result.response.headers || {})) res.setHeader(k, v);
+    for (const [k, v] of Object.entries(result.response.headers || {}))
+      res.setHeader(k, v);
+
+    const isUnpaidBrowser402 =
+      result.response.status === 402 &&
+      (req.get("accept") || "").includes("text/html") &&
+      (req.get("user-agent") || "").includes("Mozilla") &&
+      !req.get("payment-signature") &&
+      !req.get("x-payment");
+
+    if (isUnpaidBrowser402) {
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      return res.status(402).send(renderUnpaidDownloadGuidancePage(requestUrl));
+    }
+
     return res.status(result.response.status).send(result.response.body ?? "");
   }
 
@@ -960,16 +1212,21 @@ app.get("/download", async (req, res) => {
   }
 
   // 1) If caller already has a valid access token, serve the artifact.
-  const token = typeof req.query.token === "string" ? req.query.token : undefined;
+  const token =
+    typeof req.query.token === "string" ? req.query.token : undefined;
   if (token) {
     const check = validateAndConsumeToken(token);
     if (!check.ok) return res.status(403).json({ error: check.reason });
 
     const p = absArtifactPath();
-    if (!fs.existsSync(p)) return res.status(404).json({ error: "artifact not found" });
+    if (!fs.existsSync(p))
+      return res.status(404).json({ error: "artifact not found" });
 
     res.setHeader("Content-Type", MIME_TYPE);
-    res.setHeader("Content-Disposition", `attachment; filename=\"${path.basename(p)}\"`);
+    res.setHeader(
+      "Content-Disposition",
+      `attachment; filename=\"${path.basename(p)}\"`,
+    );
     return fs.createReadStream(p).pipe(res);
   }
 
@@ -984,7 +1241,9 @@ app.get("/download", async (req, res) => {
         req.x402.declaredExtensions,
       );
     } catch (err) {
-      console.error(`[x402] settlement request failed: ${err?.message || String(err)}`);
+      console.error(
+        `[x402] settlement request failed: ${err?.message || String(err)}`,
+      );
       printFacilitatorHint(err);
       return res.status(502).json({ error: "payment settlement unavailable" });
     }
@@ -997,8 +1256,12 @@ app.get("/download", async (req, res) => {
       });
     }
 
-    for (const [k, v] of Object.entries(settle.headers || {})) res.setHeader(k, v);
-    res.setHeader("Access-Control-Expose-Headers", "PAYMENT-REQUIRED, PAYMENT-RESPONSE");
+    for (const [k, v] of Object.entries(settle.headers || {}))
+      res.setHeader(k, v);
+    res.setHeader(
+      "Access-Control-Expose-Headers",
+      "PAYMENT-REQUIRED, PAYMENT-RESPONSE",
+    );
   }
 
   const t = mintGrant();
@@ -1025,7 +1288,7 @@ app.listen(PORT, () => {
   console.log(`download http://localhost:${PORT}/download (x402 protected)`);
   if (endedWindowActive()) {
     console.log(
-      `ended-window active until ${new Date(endedWindowCutoffTs() * 1000).toISOString()} (HTTP 410 mode)`,
+      `ended-window active until ${new Date(endedWindowCutoffTs() * 1000).toISOString()} (download endpoints HTTP 410 mode)`,
     );
   }
 });