leak-cli 2026.2.15-beta.0 → 2026.2.15

package/README.md

@@ -105,6 +105,14 @@ Security note: use a dedicated buyer key with limited funds.
 
 Under the hood, the skill scripts try `leak` on PATH first and fall back to `npx -y leak-cli@2026.2.14` for one-off usage if needed.
 
+Recommended first-time agent UX for unknown URLs:
+- ask only for skill-install approval (`clawhub install leak`)
+- ask for an existing buyer key file path (default mode)
+- if user opts in and no key exists, create `./.leak/buyer.key` (hot wallet; fund minimally; user must back it up)
+- if workspace is a git repo, add `./.leak/buyer.key` to `.gitignore` so it is not tracked
+- run: `bash skills/leak/scripts/buy.sh "<promo_or_download_url>" --buyer-private-key-file <buyer_key_file_path>` (or `./.leak/buyer.key` for generated fallback)
+- avoid protocol deep-dives unless the user explicitly asks for x402 internals
+
 ### Next: Mainnet checklist (optional)
 
 Warning: switching only `CHAIN_ID` to mainnet is not sufficient.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leak-cli",
-  "version": "2026.2.15-beta.0",
+  "version": "2026.2.15",
   "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",

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

@@ -9,6 +9,7 @@ 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();
 
@@ -80,7 +81,7 @@ const FACILITATOR_URL = (
 ).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);
@@ -110,7 +111,19 @@ const LEGACY_DISCOVERY_DEPRECATION =
 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";
+
+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");
@@ -307,7 +320,7 @@ function promoModel(req) {
   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.`;
+    `$${PRICE_USD} to unlock ${ARTIFACT_NAME}`;
 
   return {
     baseUrl,
@@ -358,10 +371,17 @@ ${SKILL_DESCRIPTION}
 - Status: ${resource.status}
 - Sale ends: ${resource.sale_end}
 
-## Agent Flow
+## Buyer Fast Path (for unknown agents)
+1. Ask the user for approval to install the skill once.
+2. Install: \`${SKILL_INSTALL_COMMAND}\`
+3. Load the skill and continue with Buyer Fast Path.
+
+Do not explain x402 internals unless the user explicitly asks.
+
+## Discovery Fallback
 1. Read resource metadata from \`/.well-known/skills/${SKILL_NAME}/resource.json\`.
 2. Use \`download_url\` for x402 purchase and token mint.
-3. Download the file from \`/download?token=...\` and save it locally.
+3. Download from \`/download?token=...\` and save locally.
 
 ## CLI
 - Install: \`${SKILL_INSTALL_COMMAND}\`
@@ -369,6 +389,84 @@ ${SKILL_DESCRIPTION}
 `;
 }
 
+function buildAgentQuickPath(promoUrl, downloadUrl) {
+  const safePromoUrl = String(promoUrl || "").trim();
+  const safeDownloadUrl = String(downloadUrl || "").trim();
+  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 {
+    promoUrl: safePromoUrl,
+    downloadUrl: safeDownloadUrl,
+    installCommand: SKILL_INSTALL_COMMAND,
+    buyTarget,
+    buyScriptCommand,
+  };
+}
+
+function urlsForQuickPathFromRequestUrl(requestUrl) {
+  try {
+    const parsed = new URL(String(requestUrl || ""));
+    const origin = parsed.origin;
+    return {
+      promoUrl: `${origin}/`,
+      downloadUrl: `${origin}/download`,
+    };
+  } catch {
+    const fallbackBase = isAbsoluteHttpUrl(PUBLIC_BASE_URL)
+      ? PUBLIC_BASE_URL.replace(/\/+$/, "")
+      : `http://127.0.0.1:${PORT}`;
+    return {
+      promoUrl: `${fallbackBase}/`,
+      downloadUrl: `${fallbackBase}/download`,
+    };
+  }
+}
+
+function renderAgentQuickPathHtmlBlock(fastPath) {
+  return `<section class="agent-quick-path">
+      <h2>Agent Quick Path</h2>
+      <ol>
+        <li>Ask for approval to install the skill once.</li>
+        <li>Install: <code>${escapeHtml(fastPath.installCommand)}</code></li>
+        <li>Load the skill and continue with Buyer Fast Path.</li>
+      </ol>
+      <p><strong>Rule:</strong> do not explain x402 internals unless the user explicitly asks.</p>
+    </section>`;
+}
+
+function renderUnpaidDownloadGuidancePage(requestUrl) {
+  const urls = urlsForQuickPathFromRequestUrl(requestUrl);
+  const fastPath = buildAgentQuickPath(urls.promoUrl, urls.downloadUrl);
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Payment Required - leak</title>
+  <style>
+    body { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; margin: 0; padding: 24px; background: #f7f7f5; color: #1f1f1f; }
+    .card { max-width: 760px; margin: 0 auto; border: 1px solid #d8d8d0; background: #fff; border-radius: 10px; padding: 20px; }
+    h1 { margin: 0 0 12px; font-size: 24px; }
+    h2 { margin: 0 0 10px; font-size: 18px; }
+    p { line-height: 1.5; }
+    code, pre { background: #f0f0eb; border-radius: 6px; padding: 2px 6px; }
+    pre { padding: 10px; overflow-x: auto; }
+    ol { margin: 10px 0 12px 20px; }
+  </style>
+</head>
+<body>
+  <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)}
+  </main>
+</body>
+</html>`;
+}
+
 function sendSkillIndex(req, res) {
   const payload = {
     skills: [
@@ -408,6 +506,7 @@ 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",
@@ -433,7 +532,7 @@ function renderPromoPage(model, { ended }) {
   };
   const safeJsonLd = toSafeJsonForScript(jsonLd);
 
-  const examplePrompt = `Buy this and save it: ${model.downloadUrl}`;
+  const humanActionText = "Just send the link to this page to your agent";
 
   return `<!doctype html>
 <html lang="en">
@@ -472,53 +571,68 @@ function renderPromoPage(model, { ended }) {
     .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; }
   </style>
 </head>
 <body>
   <main class="card">
     <div class="state">${escapeHtml(stateLabel)}</div>
     <h1>${escapeHtml(pageTitle)}</h1>
-    <p>${escapeHtml(description)}</p>
-    <p><strong>Agent-assisted purchase:</strong> this release is designed to be bought through an agent using the x402 endpoint below.</p>
 
     <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>
+    <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)}
 
-    <p><strong>x402 URL</strong><br /><code>${escapeHtml(model.downloadUrl)}</code></p>
     <div class="prompt-head">
-      <p><strong>Example agent prompt</strong></p>
-      <button class="copy-btn" id="copy-agent-prompt" type="button" aria-label="Copy example agent prompt">Copy prompt</button>
-      <span class="copy-status" id="copy-prompt-status" aria-live="polite"></span>
+      <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="example-agent-prompt">${escapeHtml(examplePrompt)}</pre>
+    <pre id="human-action-text">${escapeHtml(humanActionText)}</pre>
     <p class="install-note">
-      Need help setting this up? Install leak at
+      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>
   </main>
   <script>
     (() => {
-      const button = document.getElementById("copy-agent-prompt");
-      const pre = document.getElementById("example-agent-prompt");
-      const status = document.getElementById("copy-prompt-status");
-      if (!button || !pre) return;
+      const button = document.getElementById("copy-link-btn");
+      const status = document.getElementById("copy-link-status");
+      const promoUrl = ${toSafeJsonForScript(model.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 || !promoUrl) return;
 
       const setStatus = (text) => {
         if (status) status.textContent = text;
       };
 
       button.addEventListener("click", async () => {
-        const text = pre.textContent || "";
-        if (!text) return;
-        const original = "Copy prompt";
+        const original = "Copy link";
         try {
           if (navigator.clipboard?.writeText) {
-            await navigator.clipboard.writeText(text);
+            await navigator.clipboard.writeText(promoUrl);
           } else {
             const ta = document.createElement("textarea");
-            ta.value = text;
+            ta.value = promoUrl;
             ta.setAttribute("readonly", "");
             ta.style.position = "absolute";
             ta.style.left = "-9999px";
@@ -546,7 +660,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"?>
@@ -559,10 +673,10 @@ 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>`;
 }
 
@@ -637,6 +751,10 @@ const routes = {
     ],
     description: ARTIFACT_NAME,
     mimeType: MIME_TYPE,
+    unpaidResponseBody: async (context) => ({
+      contentType: "text/html; charset=utf-8",
+      body: renderUnpaidDownloadGuidancePage(context?.adapter?.getUrl?.()),
+    }),
   },
 };