ape-claw 0.1.0

package/src/server/routes/quotes.mjs

@@ -0,0 +1,161 @@
+/**
+ * Routes: /api/quotes/*, /api/bridge-requests/*
+ *
+ * Server-side quote and bridge-request management.
+ * When CLI agents use APE_CLAW_TELEMETRY_URL, they POST/GET quotes and
+ * bridge requests here instead of reading/writing local state files.
+ * This ensures daily spend caps are enforced globally.
+ */
+
+import { getStorage } from "../storage/index.mjs";
+import { verifyClawbot } from "../../lib/clawbots.mjs";
+import { collectBody } from "../middleware/body-limit.mjs";
+
+function requireAgentAuth(req, res) {
+  const agentId = String(req.headers["x-agent-id"] || "").trim();
+  const agentToken = String(req.headers["x-agent-token"] || "").trim();
+  if (!agentId || !agentToken) {
+    res.writeHead(401, { "content-type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ error: "missing credentials" }));
+    return null;
+  }
+  const v = verifyClawbot({ agentId, agentToken });
+  if (!v.verified) {
+    res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ error: "not verified", reason: v.reason }));
+    return null;
+  }
+  return agentId;
+}
+
+// ── Quotes ──
+
+export async function handleCreateQuote(req, res) {
+  const agentId = requireAgentAuth(req, res);
+  if (!agentId) return;
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+  try {
+    const body = JSON.parse(raw);
+    const quoteId = body.quoteId || `q_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const store = getStorage();
+    const data = { ...body, quoteId, agentId, createdAt: new Date().toISOString() };
+    store.saveQuote(quoteId, data);
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, quote: data }));
+  } catch (err) {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+export function handleGetQuote(req, res, reqUrl) {
+  const agentId = requireAgentAuth(req, res);
+  if (!agentId) return;
+  const quoteId = reqUrl.pathname.split("/").pop();
+  const store = getStorage();
+  const quote = store.getQuote(quoteId);
+  if (!quote) {
+    res.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: "quote not found" }));
+  }
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify({ ok: true, quote }));
+}
+
+export async function handlePatchQuote(req, res, reqUrl) {
+  const agentId = requireAgentAuth(req, res);
+  if (!agentId) return;
+  const quoteId = reqUrl.pathname.split("/").pop();
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+  try {
+    const patch = JSON.parse(raw);
+    const store = getStorage();
+    const updated = store.updateQuote(quoteId, patch);
+    if (!updated) {
+      res.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ error: "quote not found" }));
+    }
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, quote: updated }));
+  } catch (err) {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+export function handleQuotesSpendToday(req, res) {
+  const agentId = requireAgentAuth(req, res);
+  if (!agentId) return;
+  const store = getStorage();
+  const spent = store.getQuotesSpendToday();
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify({ ok: true, spentToday: spent }));
+}
+
+// ── Bridge requests ──
+
+export async function handleCreateBridgeRequest(req, res) {
+  const agentId = requireAgentAuth(req, res);
+  if (!agentId) return;
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+  try {
+    const body = JSON.parse(raw);
+    const requestId = body.requestId || `br_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const store = getStorage();
+    const data = { ...body, requestId, agentId, createdAt: new Date().toISOString() };
+    store.saveBridgeRequest(requestId, data);
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, bridgeRequest: data }));
+  } catch (err) {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+export function handleGetBridgeRequest(req, res, reqUrl) {
+  const agentId = requireAgentAuth(req, res);
+  if (!agentId) return;
+  const requestId = reqUrl.pathname.split("/").pop();
+  const store = getStorage();
+  const request = store.getBridgeRequest(requestId);
+  if (!request) {
+    res.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: "bridge request not found" }));
+  }
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify({ ok: true, bridgeRequest: request }));
+}
+
+export async function handlePatchBridgeRequest(req, res, reqUrl) {
+  const agentId = requireAgentAuth(req, res);
+  if (!agentId) return;
+  const requestId = reqUrl.pathname.split("/").pop();
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+  try {
+    const patch = JSON.parse(raw);
+    const store = getStorage();
+    const updated = store.updateBridgeRequest(requestId, patch);
+    if (!updated) {
+      res.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+      return res.end(JSON.stringify({ error: "bridge request not found" }));
+    }
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, bridgeRequest: updated }));
+  } catch (err) {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+export function handleBridgeSpendToday(req, res) {
+  const agentId = requireAgentAuth(req, res);
+  if (!agentId) return;
+  const store = getStorage();
+  const spent = store.getBridgeSpendToday();
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify({ ok: true, spentToday: spent }));
+}

package/src/server/routes/skills.mjs

@@ -0,0 +1,239 @@
+/**
+ * Routes: /api/skills/*, /api/skillcards/*, /skillcards/*
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { ROOT as PROJECT_ROOT } from "../../lib/paths.mjs";
+import { getStorage } from "../storage/index.mjs";
+import { requireSkillWriteAuth } from "../middleware/auth.mjs";
+import { collectBody } from "../middleware/body-limit.mjs";
+
+function toSlug(input) {
+  return String(input || "").toLowerCase().trim()
+    .replace(/®/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+function safeVersion(v) {
+  const s = String(v || "").trim();
+  if (!s) return "";
+  if (!/^[0-9]+(\.[0-9]+){0,3}([\-+][0-9A-Za-z._-]+)?$/.test(s)) return "";
+  return s;
+}
+
+export function handleSkillsSearch(req, res, reqUrl) {
+  try {
+    const store = getStorage();
+    const query = String(reqUrl.searchParams.get("q") || "").trim().toLowerCase();
+    const sourceFilter = String(reqUrl.searchParams.get("source") || "").trim().toLowerCase();
+    const vettedFilter = String(reqUrl.searchParams.get("vetted") || "").trim();
+    const page = Math.max(1, Number(reqUrl.searchParams.get("page") || 1));
+    const limit = Math.min(5000, Math.max(1, Number(reqUrl.searchParams.get("limit") || 50)));
+    let results = store.getMergedSkillIndex();
+    if (sourceFilter && ["seed", "imported", "user"].includes(sourceFilter)) results = results.filter((s) => s.source === sourceFilter);
+    if (vettedFilter === "1") results = results.filter((s) => s.vettedOk === true);
+    if (query) {
+      results = results.filter((s) => {
+        const n = String(s.name || "").toLowerCase();
+        const sl = String(s.slug || "").toLowerCase();
+        const d = String(s.description || "").toLowerCase();
+        return n.includes(query) || sl.includes(query) || d.includes(query);
+      });
+    }
+    const total = results.length;
+    const pages = Math.ceil(total / limit);
+    const start = (page - 1) * limit;
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, total, page, limit, pages, results: results.slice(start, start + limit) }));
+  } catch (err) {
+    res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: err.message || "search failed" }));
+  }
+}
+
+export function handleSkillsGet(req, res, reqUrl) {
+  try {
+    const store = getStorage();
+    const slug = String(reqUrl.searchParams.get("slug") || "").trim();
+    if (!slug) { res.writeHead(400, { "content-type": "application/json; charset=utf-8" }); return res.end(JSON.stringify({ ok: false, error: "missing slug" })); }
+    const all = store.getMergedSkillIndex();
+    const match = all.find((s) => s.slug === slug);
+    if (!match) { res.writeHead(404, { "content-type": "application/json; charset=utf-8" }); return res.end(JSON.stringify({ ok: false, error: "skill not found" })); }
+    let fullCard = null;
+    if (match.fileName) {
+      const fp = store.resolveSkillFilePath(match.source, match.fileName);
+      if (fp) try { fullCard = JSON.parse(fs.readFileSync(fp, "utf8")); } catch {}
+    }
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, skill: match, card: fullCard }));
+  } catch (err) {
+    res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: err.message || "get failed" }));
+  }
+}
+
+export function handleSkillsStats(req, res) {
+  try {
+    const store = getStorage();
+    const all = store.getMergedSkillIndex();
+    const seed = all.filter((s) => s.source === "seed").length;
+    const imported = all.filter((s) => s.source === "imported").length;
+    const user = all.filter((s) => s.source === "user").length;
+    const vetted = all.filter((s) => s.vettedOk === true).length;
+    const onchain = all.filter((s) => s.onchainTokenId != null).length;
+    let recent = all.filter((s) => s.addedAt).sort((a, b) => new Date(b.addedAt) - new Date(a.addedAt));
+    if (recent.length === 0) recent = all.slice(-20).reverse();
+    recent = recent.slice(0, 10).map((s) => ({
+      name: s.name, slug: s.slug, source: s.source, addedAt: s.addedAt,
+      riskTier: s.riskTier, description: String(s.description || "").slice(0, 150),
+      onchainTokenId: s.onchainTokenId ?? null,
+    }));
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, total: all.length, seed, imported, user, vetted, onchain, recent }));
+  } catch (err) {
+    res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: err.message || "stats failed" }));
+  }
+}
+
+export function handleSkillcardsUserGet(req, res) {
+  try {
+    const store = getStorage();
+    const raw = store.getUserSkillsIndex();
+    const skills = Array.isArray(raw?.skills) ? raw.skills : [];
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, skills }));
+  } catch (err) {
+    res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: err.message || "failed to load index" }));
+  }
+}
+
+export function handleSkillcardsAuthCheck(req, res) {
+  const auth = requireSkillWriteAuth(req);
+  res.writeHead(auth.ok ? 200 : 401, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify({ ok: auth.ok, mode: auth.mode, agentId: auth.agentId }));
+}
+
+export async function handleSkillcardsUserAdd(req, res) {
+  const auth = requireSkillWriteAuth(req);
+  if (!auth.ok) {
+    res.writeHead(401, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "unauthorized (set x-agent-id/x-agent-token or x-registration-key)" }));
+  }
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+  try {
+    const body = JSON.parse(raw);
+    const skillcard = body?.skillcard || body?.card || body;
+    if (!skillcard || typeof skillcard !== "object") throw new Error("missing skillcard object");
+    const name = String(skillcard.name || "").trim();
+    if (!name) throw new Error("skillcard.name required");
+    const slug = toSlug(skillcard.slug || name);
+    if (!slug) throw new Error("skillcard.slug required");
+    const version = safeVersion(skillcard.version || "1.0.0");
+    if (!version) throw new Error("skillcard.version invalid (expected semver-ish)");
+    const desc = String(skillcard.description || "").trim();
+    const riskTierRaw = Number(skillcard?.constraints?.riskTier ?? skillcard?.riskTier ?? 2);
+    const riskTier = Number.isFinite(riskTierRaw) ? Math.max(1, Math.min(3, Math.round(riskTierRaw))) : 2;
+    const createdAt = new Date().toISOString();
+    const sourceUrl = String(body?.sourceUrl || skillcard?.provenance?.sourceUrl || "").trim();
+    const fileName = `${slug}.v${version}.json`;
+    const store = getStorage();
+    store.writeUserSkillFile(fileName, { ...skillcard, slug, version, name, description: desc });
+    const idx = store.getUserSkillsIndex();
+    const skills = Array.isArray(idx?.skills) ? idx.skills : [];
+    const entry = { fileName, name, slug, version, description: desc, riskTier, sourceUrl, createdAt, addedBy: auth.mode, addedByAgentId: auth.agentId };
+    const next = skills.filter((s) => String(s?.fileName || "") !== fileName);
+    next.unshift(entry);
+    store.writeUserSkillsIndex({ skills: next });
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true, entry, fileHref: `/skillcards/user/${encodeURIComponent(fileName)}` }));
+  } catch (err) {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: err.message || "invalid request" }));
+  }
+}
+
+export async function handleSkillcardsUserDelete(req, res) {
+  const auth = requireSkillWriteAuth(req);
+  if (!auth.ok) {
+    res.writeHead(401, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "unauthorized" }));
+  }
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+  try {
+    const body = JSON.parse(raw);
+    const fileName = String(body?.fileName || "").trim();
+    if (!fileName || fileName.includes("..") || fileName.includes("/") || fileName.includes("\\")) throw new Error("invalid fileName");
+    const store = getStorage();
+    store.deleteUserSkillFile(fileName);
+    const idx = store.getUserSkillsIndex();
+    const skills = Array.isArray(idx?.skills) ? idx.skills : [];
+    store.writeUserSkillsIndex({ skills: skills.filter((s) => String(s?.fileName || "") !== fileName) });
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true }));
+  } catch (err) {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: err.message || "invalid request" }));
+  }
+}
+
+export async function handleSkillcardsUserMarkOnchain(req, res) {
+  const auth = requireSkillWriteAuth(req);
+  if (!auth.ok) {
+    res.writeHead(401, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "unauthorized" }));
+  }
+  const raw = await collectBody(req, res);
+  if (raw === null) return;
+  try {
+    const body = JSON.parse(raw);
+    const fileName = String(body?.fileName || "").trim();
+    if (!fileName || fileName.includes("..") || fileName.includes("/") || fileName.includes("\\")) throw new Error("invalid fileName");
+    const skillIdNum = Number(body?.skillId);
+    if (!Number.isFinite(skillIdNum) || skillIdNum <= 0) throw new Error("invalid skillId");
+    const txHash = String(body?.txHash || "").trim();
+    const store = getStorage();
+    const idx = store.getUserSkillsIndex();
+    const skills = Array.isArray(idx?.skills) ? idx.skills : [];
+    let found = false;
+    const next = skills.map((s) => {
+      if (String(s?.fileName || "") !== fileName) return s;
+      found = true;
+      return { ...s, onchain: { skillId: Math.floor(skillIdNum), txHash, markedAt: new Date().toISOString() } };
+    });
+    if (!found) throw new Error("skill not found");
+    store.writeUserSkillsIndex({ skills: next });
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: true }));
+  } catch (err) {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: err.message || "invalid request" }));
+  }
+}
+
+export function handleSkillcardFile(req, res, pathname) {
+  const store = getStorage();
+  const segments = pathname.slice("/skillcards/".length).split("/");
+  const bucket = segments[0];
+  const fileName = segments.length > 1 ? decodeURIComponent(segments.slice(1).join("/")) : "";
+  const ALLOWED_BUCKETS = {
+    user: store.SKILLCARDS_USER_DIR,
+    imported: path.join(PROJECT_ROOT, "skillcards", "imported"),
+    seed: store.SKILLCARDS_SEED_DIR,
+  };
+  const baseDir = ALLOWED_BUCKETS[bucket];
+  if (!baseDir || !fileName || fileName.includes("..") || fileName.includes("\\")) {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: "invalid file" }));
+  }
+  const filePath = path.join(baseDir, fileName);
+  if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+    res.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ error: "not found" }));
+  }
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return fs.createReadStream(filePath).pipe(res);
+}

package/src/server/routes/static.mjs

@@ -0,0 +1,161 @@
+/**
+ * Routes: static file serving and local UX rewrites
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { ROOT as PROJECT_ROOT, POLICY_PATH, ALLOWLIST_PATH, OPENSEA_OVERRIDES_PATH } from "../../lib/paths.mjs";
+
+const OPENSEA_API_BASE = "https://api.opensea.io/api/v2";
+const ICON_CACHE_TTL_MS = 10 * 60 * 1000;
+let allowlistIconCache = { expiresAt: 0, data: null, inFlight: null };
+
+const REWRITES = {
+  "/ui": "/ui/index.html", "/app": "/ui/index.html",
+  "/docs": "/ui/docs.html", "/pod": "/ui/pod.html", "/skills": "/ui/skills.html",
+  "/favicon-lobster.png": "/ui/favicon-lobster.png",
+  "/ui/favicon.svg": "/ui/favicon.svg", "/ui/favicon-32.png": "/ui/favicon-32.png",
+  "/ui/favicon-180.png": "/ui/favicon-180.png", "/ui/favicon-192.png": "/ui/favicon-192.png",
+};
+
+const MIME_TYPES = {
+  ".html": "text/html", ".css": "text/css", ".js": "application/javascript",
+  ".json": "application/json", ".png": "image/png", ".jpg": "image/jpeg",
+  ".svg": "image/svg+xml", ".ico": "image/x-icon", ".webp": "image/webp",
+  ".md": "text/plain; charset=utf-8", ".txt": "text/plain; charset=utf-8", ".woff2": "font/woff2",
+};
+
+function toSlug(input) {
+  return String(input || "").toLowerCase().trim()
+    .replace(/®/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function unique(items) { return [...new Set(items.filter(Boolean))]; }
+function buildSlugCandidates(item, overrides = {}) {
+  const raw = String(item?.name || "");
+  const base = toSlug(raw);
+  const fromOverride = overrides[raw] || overrides[base] || [];
+  return unique([
+    item?.slug, base, base.replace(/-on-apechain$/, ""), base.replace(/-on-ape$/, ""),
+    base.replace(/-/g, ""),
+    ...(Array.isArray(fromOverride) ? fromOverride : [fromOverride]),
+  ]);
+}
+async function fetchJson(url, headers = {}) {
+  const res = await fetch(url, { headers });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return res.json();
+}
+function extractCollectionImage(payload) {
+  const c = payload?.collection || payload || {};
+  return c?.image_url || c?.imageUrl || c?.banner_image_url || c?.bannerImageUrl || null;
+}
+async function resolveCollectionIcon(item, headers, overrides) {
+  const candidates = buildSlugCandidates(item, overrides);
+  for (const slug of candidates) {
+    try {
+      const data = await fetchJson(`${OPENSEA_API_BASE}/collections/${encodeURIComponent(slug)}`, headers);
+      const imageUrl = extractCollectionImage(data);
+      if (imageUrl) return { imageUrl, openseaSlug: slug };
+    } catch {}
+    try {
+      const nftData = await fetchJson(`${OPENSEA_API_BASE}/collection/${encodeURIComponent(slug)}/nfts?limit=1`, headers);
+      const first = Array.isArray(nftData?.nfts) ? nftData.nfts[0] : null;
+      const imageUrl = first?.image_url || first?.display_image_url || first?.imageUrl || null;
+      if (imageUrl) return { imageUrl, openseaSlug: slug };
+    } catch {}
+  }
+  return { imageUrl: null, openseaSlug: null };
+}
+async function mapWithConcurrency(items, limit, mapper) {
+  const out = new Array(items.length);
+  let i = 0;
+  async function worker() { while (i < items.length) { const idx = i++; out[idx] = await mapper(items[idx], idx); } }
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, () => worker()));
+  return out;
+}
+
+async function getAllowlistWithIcons() {
+  const now = Date.now();
+  if (allowlistIconCache.data && allowlistIconCache.expiresAt > now) return allowlistIconCache.data;
+  if (allowlistIconCache.inFlight) return allowlistIconCache.inFlight;
+  allowlistIconCache.inFlight = (async () => {
+    const raw = fs.readFileSync(ALLOWLIST_PATH, "utf8");
+    const allowlist = JSON.parse(raw);
+    const key = process.env.OPENSEA_API_KEY || "";
+    if (!key) {
+      const plain = allowlist.map((c) => ({ ...c, imageUrl: null, openseaSlug: c.slug || null }));
+      allowlistIconCache = { expiresAt: now + ICON_CACHE_TTL_MS, data: plain, inFlight: null };
+      return plain;
+    }
+    let overrides = {};
+    if (fs.existsSync(OPENSEA_OVERRIDES_PATH)) {
+      try { overrides = JSON.parse(fs.readFileSync(OPENSEA_OVERRIDES_PATH, "utf8")); } catch { overrides = {}; }
+    }
+    const headers = { "x-api-key": key, accept: "application/json" };
+    const enriched = await mapWithConcurrency(allowlist, 8, async (item) => {
+      const icon = await resolveCollectionIcon(item, headers, overrides);
+      return { ...item, imageUrl: icon.imageUrl, openseaSlug: icon.openseaSlug || item.slug || null };
+    });
+    allowlistIconCache = { expiresAt: Date.now() + ICON_CACHE_TTL_MS, data: enriched, inFlight: null };
+    return enriched;
+  })();
+  try { return await allowlistIconCache.inFlight; } finally {
+    if (allowlistIconCache.inFlight && allowlistIconCache.expiresAt < Date.now()) allowlistIconCache.inFlight = null;
+  }
+}
+
+export function handleAllowlist(req, res) {
+  getAllowlistWithIcons()
+    .then((data) => {
+      res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+      res.end(JSON.stringify(data));
+    })
+    .catch((err) => {
+      res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+      res.end(JSON.stringify({ error: err.message }));
+    });
+}
+
+export function handlePolicy(req, res) {
+  if (!fs.existsSync(POLICY_PATH)) {
+    res.writeHead(404, { "content-type": "application/json" });
+    return res.end(JSON.stringify({ error: "not found" }));
+  }
+  const raw = fs.readFileSync(POLICY_PATH, "utf8");
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(raw);
+}
+
+export function handleRewrite(req, res, pathname) {
+  const cleanPath = String(pathname || "").replace(/\/+$/, "").toLowerCase() || pathname;
+  const rewrite = REWRITES[pathname] || REWRITES[String(pathname || "").replace(/\/+$/, "")] || REWRITES[cleanPath] || "";
+  if (!rewrite) return false;
+  const p = path.join(PROJECT_ROOT, rewrite);
+  if (!fs.existsSync(p)) { res.writeHead(404); res.end(`missing: ${rewrite}`); return true; }
+  const ext = path.extname(p).toLowerCase();
+  const mime = ext === ".html" ? "text/html; charset=utf-8" : ext === ".png" ? "image/png" : "application/octet-stream";
+  res.writeHead(200, { "content-type": mime });
+  fs.createReadStream(p).pipe(res);
+  return true;
+}
+
+export function handleIndex(req, res) {
+  const landingPath = path.join(PROJECT_ROOT, "index.html");
+  const uiPath = path.join(PROJECT_ROOT, "ui", "index.html");
+  const p = fs.existsSync(landingPath) ? landingPath : uiPath;
+  if (!fs.existsSync(p)) { res.writeHead(404); return res.end("index.html not found"); }
+  res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+  return fs.createReadStream(p).pipe(res);
+}
+
+export function handleStaticFile(req, res, pathname) {
+  const safePath = decodeURIComponent(pathname);
+  if (safePath.includes("..") || safePath.includes("~")) return false;
+  const filePath = path.join(PROJECT_ROOT, safePath);
+  if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) return false;
+  const ext = path.extname(filePath).toLowerCase();
+  const mime = MIME_TYPES[ext] || "application/octet-stream";
+  res.writeHead(200, { "content-type": mime });
+  fs.createReadStream(filePath).pipe(res);
+  return true;
+}

package/src/server/routes/v2.mjs

@@ -0,0 +1,48 @@
+/**
+ * Routes: /api/v2/*
+ */
+
+import { createPublicClient, getContract, http as viemHttp, keccak256, toHex } from "viem";
+import { ReceiptRegistry_ABI } from "../../lib/v2-onchain-abi.mjs";
+import { getStorage } from "../storage/index.mjs";
+import { resolveV2ReceiptReadConfig } from "./health.mjs";
+
+const bigintReplacer = (_k, v) => (typeof v === "bigint" ? v.toString() : v);
+
+export async function handleV2ReceiptGet(req, res, reqUrl) {
+  const traceId = String(reqUrl.searchParams.get("traceId") || reqUrl.searchParams.get("trace") || "").trim();
+  if (!traceId) {
+    res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "missing traceId" }));
+  }
+  const cfg = resolveV2ReceiptReadConfig();
+  if (!cfg.ok) {
+    res.writeHead(501, { "content-type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: cfg.reason, inferredRpc: cfg.inferredRpc || false }));
+  }
+  try {
+    const publicClient = createPublicClient({ transport: viemHttp(cfg.rpcUrl) });
+    const receipts = getContract({ address: cfg.receiptsAddress, abi: ReceiptRegistry_ABI, client: { public: publicClient } });
+    const traceIdHash = keccak256(toHex(traceId));
+    const isRecorded = await receipts.read.isRecorded([traceIdHash]);
+    const receipt = isRecorded ? await receipts.read.getReceipt([traceIdHash]) : null;
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ ok: true, traceId, traceIdHash, isRecorded: Boolean(isRecorded), receipt }, bigintReplacer));
+  } catch (err) {
+    if (res.headersSent || res.writableEnded) return;
+    res.writeHead(502, { "content-type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ ok: false, error: err?.message || "receipt read failed" }));
+  }
+}
+
+export function handleV2Config(req, res) {
+  const store = getStorage();
+  const rec = store.resolveV2DeploymentRecord();
+  const v2Cfg = resolveV2ReceiptReadConfig();
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify({
+    ok: true, deployment: rec, receiptsRead: v2Cfg,
+    podVault: rec?.podVault || null, agentAccount: rec?.agentAccount || null,
+    record: rec, ts: new Date().toISOString(),
+  }, bigintReplacer));
+}