settld 0.1.2 → 0.2.0

package/scripts/load/webhook-receiver.js

@@ -0,0 +1,131 @@
+import http from "node:http";
+import crypto from "node:crypto";
+
+function parsePositiveInt(name, fallback) {
+  const raw = process.env[name] ?? null;
+  if (raw === null || raw === undefined || String(raw).trim() === "") return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isSafeInteger(n) || n <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+  return n;
+}
+
+function parseNonNegativeInt(name, fallback) {
+  const raw = process.env[name] ?? null;
+  if (raw === null || raw === undefined || String(raw).trim() === "") return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isSafeInteger(n) || n < 0) throw new TypeError(`${name} must be a non-negative safe integer`);
+  return n;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+const port = parsePositiveInt("PORT", 4010);
+const timeoutRatePct = parseNonNegativeInt("TIMEOUT_RATE_PCT", 5);
+const errorRatePct = parseNonNegativeInt("ERROR_RATE_PCT", 5);
+const timeoutDelayMs = parsePositiveInt("TIMEOUT_DELAY_MS", 10_000);
+
+const seen = new Map(); // dedupeKey -> { count, hashes: Set }
+let total = 0;
+let ok = 0;
+let errored = 0;
+let delayed = 0;
+
+function header(req, name) {
+  const lower = name.toLowerCase();
+  const v = req.headers[lower] ?? null;
+  return v === null || v === undefined ? "" : String(v);
+}
+
+function sha256Hex(text) {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+const server = http.createServer(async (req, res) => {
+  if (req.method === "GET" && req.url === "/health") {
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify({ ok: true }));
+    return;
+  }
+
+  if (req.method === "GET" && req.url === "/stats") {
+    const top = [];
+    for (const [dedupeKey, v] of seen.entries()) {
+      top.push({ dedupeKey, count: v.count, uniqueBodies: v.hashes.size });
+    }
+    top.sort((a, b) => b.count - a.count);
+
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify({ total, ok, errored, delayed, top: top.slice(0, 50) }));
+    return;
+  }
+
+  if (req.method !== "POST") {
+    res.statusCode = 404;
+    res.end("not found");
+    return;
+  }
+
+  const body = await new Promise((resolve) => {
+    let chunks = "";
+    req.on("data", (d) => {
+      chunks += d;
+      // Avoid unbounded memory on misuse.
+      if (chunks.length > 2_000_000) req.destroy();
+    });
+    req.on("end", () => resolve(chunks));
+    req.on("error", () => resolve(""));
+  });
+
+  total += 1;
+
+  const dedupeKey = header(req, "x-proxy-dedupe-key");
+  if (dedupeKey) {
+    const row = seen.get(dedupeKey) ?? { count: 0, hashes: new Set() };
+    row.count += 1;
+    row.hashes.add(sha256Hex(body));
+    seen.set(dedupeKey, row);
+  }
+
+  const roll = Math.random() * 100;
+  if (roll < timeoutRatePct) {
+    delayed += 1;
+    await sleep(timeoutDelayMs);
+    res.statusCode = 200;
+    res.end("ok");
+    ok += 1;
+    return;
+  }
+
+  if (roll < timeoutRatePct + errorRatePct) {
+    errored += 1;
+    res.statusCode = 500;
+    res.end("error");
+    return;
+  }
+
+  ok += 1;
+  res.statusCode = 200;
+  res.end("ok");
+});
+
+server.listen(port, () => {
+  process.stdout.write(
+    JSON.stringify({
+      ts: new Date().toISOString(),
+      level: "info",
+      msg: "load.webhook_receiver.listening",
+      port,
+      timeoutRatePct,
+      errorRatePct,
+      timeoutDelayMs
+    }) + "\n"
+  );
+});
+
+process.on("SIGINT", () => server.close(() => process.exit(0)));
+process.on("SIGTERM", () => server.close(() => process.exit(0)));
+

package/scripts/magic-link/migrate-run-records-to-db.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import os from "node:os";
+import path from "node:path";
+
+import { migrateRunRecordsFromFsToDbBestEffort, runStoreModeInfo } from "../../services/magic-link/src/run-records.js";
+
+const dataDir = process.env.MAGIC_LINK_DATA_DIR ? path.resolve(process.env.MAGIC_LINK_DATA_DIR) : path.join(os.tmpdir(), "settld-magic-link");
+const tenantIds =
+  process.env.MAGIC_LINK_MIGRATE_TENANT_IDS && process.env.MAGIC_LINK_MIGRATE_TENANT_IDS.trim()
+    ? process.env.MAGIC_LINK_MIGRATE_TENANT_IDS.split(",").map((x) => x.trim()).filter(Boolean)
+    : null;
+const max = Number.parseInt(String(process.env.MAGIC_LINK_MIGRATE_MAX ?? "500000"), 10);
+
+const info = runStoreModeInfo();
+if (!info.dbEnabled) {
+  // eslint-disable-next-line no-console
+  console.error(
+    JSON.stringify(
+      {
+        ok: false,
+        code: "DB_DISABLED",
+        message:
+          "DB run store is disabled. Set MAGIC_LINK_RUN_STORE_MODE=dual|db and MAGIC_LINK_RUN_STORE_DATABASE_URL (or DATABASE_URL) before running migration."
+      },
+      null,
+      2
+    )
+  );
+  process.exit(2);
+}
+
+const result = await migrateRunRecordsFromFsToDbBestEffort({ dataDir, tenantIds, max: Number.isInteger(max) && max > 0 ? max : 500000 });
+// eslint-disable-next-line no-console
+console.log(JSON.stringify({ ok: true, dataDir, mode: info.mode, ...result }, null, 2));
+

package/scripts/mcp/probe.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * MCP spike probe: spawns the stdio MCP server, sends initialize + tools/list, prints results, exits.
+ *
+ * Usage:
+ *   npm run mcp:probe
+ *   node scripts/mcp/probe.mjs --call settld.about '{}'
+ */
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function parseArgs(argv) {
+  const out = { call: null, timeoutMs: null, x402Smoke: false, x402SmokeFile: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--call") {
+      const name = argv[i + 1] || "";
+      const argsRaw = argv[i + 2] || "{}";
+      out.call = { name, argsRaw };
+      i += 2;
+    }
+    if (a === "--call-file") {
+      const name = argv[i + 1] || "";
+      const file = argv[i + 2] || "";
+      out.call = { name, argsRaw: null, file };
+      i += 2;
+    }
+    if (a === "--timeout-ms") {
+      const raw = argv[i + 1];
+      out.timeoutMs = raw;
+      i += 1;
+    }
+    if (a === "--x402-smoke") {
+      out.x402Smoke = true;
+    }
+    if (a === "--x402-smoke-file") {
+      out.x402Smoke = true;
+      out.x402SmokeFile = argv[i + 1] || "";
+      i += 1;
+    }
+  }
+  return out;
+}
+
+function assertProbeEnv() {
+  const apiKey = process.env.SETTLD_API_KEY;
+  if (typeof apiKey === "string" && apiKey.trim() !== "") return;
+  throw new Error(
+    [
+      "[mcp:probe] missing required env var: SETTLD_API_KEY",
+      "Set env and retry:",
+      "  export SETTLD_BASE_URL=http://127.0.0.1:3000",
+      "  export SETTLD_TENANT_ID=tenant_default",
+      "  export SETTLD_API_KEY='sk_live_or_sk_test_keyid.secret'",
+      "Docs: docs/QUICKSTART_MCP.md"
+    ].join("\n")
+  );
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  assertProbeEnv();
+
+  const child = spawn(process.execPath, ["scripts/mcp/settld-mcp-server.mjs"], {
+    cwd: process.cwd(),
+    stdio: ["pipe", "pipe", "inherit"],
+    env: { ...process.env }
+  });
+
+  child.stdout.setEncoding("utf8");
+  let buf = "";
+  const pending = new Map();
+  let shuttingDown = false;
+
+  child.on("exit", (code, signal) => {
+    if (shuttingDown) return;
+    const reason = `mcp server exited before probe completed (code=${code ?? "null"} signal=${signal ?? ""})`;
+    for (const { reject } of pending.values()) {
+      reject(new Error(reason));
+    }
+    pending.clear();
+  });
+
+  function onLine(line) {
+    let msg = null;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return;
+    }
+    const id = msg?.id;
+    if (id !== undefined && pending.has(String(id))) {
+      const { resolve } = pending.get(String(id));
+      pending.delete(String(id));
+      resolve(msg);
+    } else {
+      // Unexpected response; print it anyway.
+      process.stdout.write(line + "\n");
+    }
+  }
+
+  child.stdout.on("data", (chunk) => {
+    buf += chunk;
+    for (;;) {
+      const idx = buf.indexOf("\n");
+      if (idx === -1) break;
+      const line = buf.slice(0, idx).trim();
+      buf = buf.slice(idx + 1);
+      if (!line) continue;
+      onLine(line);
+    }
+  });
+
+  const timeoutMsRaw =
+    args.timeoutMs !== null && args.timeoutMs !== undefined
+      ? Number(args.timeoutMs)
+      : typeof process !== "undefined"
+        ? Number(process.env.MCP_PROBE_TIMEOUT_MS ?? 30_000)
+        : 30_000;
+  const timeoutMs = Number.isFinite(timeoutMsRaw) && timeoutMsRaw > 0 ? Math.floor(timeoutMsRaw) : 30_000;
+
+  function rpc(method, params) {
+    if (child.exitCode !== null) {
+      throw new Error(`cannot call ${method}: mcp server already exited (code=${child.exitCode})`);
+    }
+    const id = String(Math.random()).slice(2);
+    const payload = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    child.stdin.write(payload + "\n");
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+      setTimeout(() => {
+        if (!pending.has(id)) return;
+        pending.delete(id);
+        reject(new Error(`timeout waiting for ${method}`));
+      }, timeoutMs).unref?.();
+    });
+  }
+
+  const init = await rpc("initialize", {
+    protocolVersion: "2024-11-05",
+    clientInfo: { name: "settld-mcp-probe", version: "s23" },
+    capabilities: {}
+  });
+  process.stdout.write(JSON.stringify(init, null, 2) + "\n");
+
+  const list = await rpc("tools/list", {});
+  process.stdout.write(JSON.stringify(list, null, 2) + "\n");
+
+  function parseToolCallResult(callResponse, fallbackName = "unknown") {
+    const text = callResponse?.result?.content?.[0]?.text ?? "";
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { tool: fallbackName, rawText: text };
+    }
+  }
+
+  if (args.call) {
+    let callArgs = {};
+    try {
+      if (args.call.file) {
+        const raw = fs.readFileSync(String(args.call.file), "utf8");
+        callArgs = JSON.parse(raw);
+      } else {
+        callArgs = JSON.parse(args.call.argsRaw);
+      }
+    } catch (err) {
+      const flag = args.call.file ? "--call-file" : "--call";
+      throw new Error(`${flag} args must be JSON: ${err?.message ?? err}`);
+    }
+    const called = await rpc("tools/call", { name: args.call.name, arguments: callArgs });
+    process.stdout.write(JSON.stringify(called, null, 2) + "\n");
+  }
+
+  if (args.x402Smoke) {
+    let smokeCfg = {};
+    if (args.x402SmokeFile) {
+      try {
+        const raw = fs.readFileSync(String(args.x402SmokeFile), "utf8");
+        smokeCfg = JSON.parse(raw);
+      } catch (err) {
+        throw new Error(`--x402-smoke-file must be valid JSON: ${err?.message ?? err}`);
+      }
+    }
+
+    const seed = String(Date.now());
+    const createArgs = {
+      gateId: `x402gate_probe_${seed}`,
+      payerAgentId: `agt_probe_payer_${seed}`,
+      payeeAgentId: `agt_probe_payee_${seed}`,
+      amountCents: 100,
+      autoFundPayerCents: 1000,
+      idempotencyKey: `mcp_probe_x402_gate_create_${seed}`,
+      ...(smokeCfg?.create && typeof smokeCfg.create === "object" ? smokeCfg.create : {})
+    };
+    const createRes = await rpc("tools/call", { name: "settld.x402_gate_create", arguments: createArgs });
+    process.stdout.write(JSON.stringify(createRes, null, 2) + "\n");
+    const createParsed = parseToolCallResult(createRes, "settld.x402_gate_create");
+    const gateId =
+      createParsed?.result?.gateId ??
+      createParsed?.result?.gate?.gateId ??
+      createParsed?.gateId ??
+      createParsed?.gate?.gateId ??
+      createArgs.gateId;
+
+    const verifyArgs = {
+      gateId,
+      ensureAuthorized: true,
+      authorizeIdempotencyKey: `mcp_probe_x402_gate_authorize_${seed}`,
+      idempotencyKey: `mcp_probe_x402_gate_verify_${seed}`,
+      ...(smokeCfg?.verify && typeof smokeCfg.verify === "object" ? smokeCfg.verify : {})
+    };
+    const verifyRes = await rpc("tools/call", { name: "settld.x402_gate_verify", arguments: verifyArgs });
+    process.stdout.write(JSON.stringify(verifyRes, null, 2) + "\n");
+
+    const getArgs = {
+      gateId,
+      ...(smokeCfg?.get && typeof smokeCfg.get === "object" ? smokeCfg.get : {})
+    };
+    const getRes = await rpc("tools/call", { name: "settld.x402_gate_get", arguments: getArgs });
+    process.stdout.write(JSON.stringify(getRes, null, 2) + "\n");
+  }
+
+  shuttingDown = true;
+  child.kill("SIGTERM");
+  await Promise.race([sleep(50), new Promise((r) => child.once("exit", r))]);
+}
+
+main().catch((err) => {
+  const message = typeof err?.message === "string" ? err.message : String(err);
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+});

package/scripts/mcp/settld-mcp-http-gateway.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * Sprint 23 MCP spike: HTTP -> stdio gateway.
+ *
+ * Why:
+ * - Some environments can call HTTP endpoints but cannot spawn a local MCP process.
+ * - This gateway runs the stdio MCP server as a single child process and forwards JSON-RPC requests.
+ *
+ * Transport:
+ * - HTTP POST /rpc with a JSON-RPC 2.0 request object.
+ *
+ * Notes:
+ * - This gateway is intentionally minimal and only supports single-request (non-batch) JSON-RPC.
+ * - Production hardening (auth, SSE, rate limits, multi-tenant routing) belongs in later sprints.
+ */
+
+import http from "node:http";
+import { spawn } from "node:child_process";
+
+function assertNonEmptyString(v, name) {
+  if (typeof v !== "string" || v.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function readJson(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => {
+      const text = Buffer.concat(chunks).toString("utf8");
+      try {
+        resolve(JSON.parse(text));
+      } catch (err) {
+        reject(new Error(`invalid JSON: ${err?.message ?? err}`));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res, statusCode, body) {
+  res.writeHead(statusCode, { "content-type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+function main() {
+  // Pass-through: the child MCP server reads these.
+  const baseUrl = process.env.SETTLD_BASE_URL ?? "";
+  const tenantId = process.env.SETTLD_TENANT_ID ?? "";
+  const apiKey = process.env.SETTLD_API_KEY ?? "";
+  assertNonEmptyString(baseUrl, "SETTLD_BASE_URL");
+  assertNonEmptyString(tenantId, "SETTLD_TENANT_ID");
+  assertNonEmptyString(apiKey, "SETTLD_API_KEY");
+
+  const port = Number(process.env.MCP_HTTP_PORT ?? process.env.PORT ?? 8787);
+  // Allow 0 for ephemeral ports in tests.
+  if (!Number.isSafeInteger(port) || port < 0) throw new TypeError("PORT must be a non-negative integer");
+
+  const child = spawn(process.execPath, ["scripts/mcp/settld-mcp-server.mjs"], {
+    cwd: process.cwd(),
+    stdio: ["pipe", "pipe", "pipe"],
+    env: { ...process.env }
+  });
+
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+
+  // Never write child stderr to stdout.
+  child.stderr.on("data", (chunk) => {
+    process.stderr.write(String(chunk));
+  });
+
+  let buf = "";
+  const pending = new Map(); // id -> { resolve, timeout }
+
+  function onLine(line) {
+    let msg = null;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return;
+    }
+    const id = msg?.id;
+    if (id === undefined || id === null) return;
+    const key = String(id);
+    const item = pending.get(key);
+    if (!item) return;
+    pending.delete(key);
+    clearTimeout(item.timeout);
+    item.resolve(msg);
+  }
+
+  child.stdout.on("data", (chunk) => {
+    buf += chunk;
+    for (;;) {
+      const idx = buf.indexOf("\n");
+      if (idx === -1) break;
+      const line = buf.slice(0, idx).trim();
+      buf = buf.slice(idx + 1);
+      if (!line) continue;
+      onLine(line);
+    }
+  });
+
+  function forwardRpc(payload) {
+    const id = payload?.id;
+    if (id === undefined || id === null) {
+      // Notifications: no response expected.
+      child.stdin.write(JSON.stringify(payload) + "\n");
+      return Promise.resolve(null);
+    }
+    const key = String(id);
+    if (pending.has(key)) {
+      return Promise.resolve({
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32000, message: "duplicate id in-flight" }
+      });
+    }
+    child.stdin.write(JSON.stringify(payload) + "\n");
+    return new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        pending.delete(key);
+        resolve({ jsonrpc: "2.0", id, error: { code: -32001, message: "gateway timeout waiting for response" } });
+      }, 10_000).unref?.();
+      pending.set(key, { resolve, timeout });
+    });
+  }
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      if (req.method === "GET" && req.url === "/healthz") {
+        return sendJson(res, 200, { ok: true, transport: "http->stdio", server: "settld-mcp-http-gateway", version: "s23" });
+      }
+
+      if (req.method === "POST" && (req.url === "/rpc" || req.url === "/mcp")) {
+        const body = await readJson(req);
+        if (Array.isArray(body)) return sendJson(res, 400, { error: "batch JSON-RPC not supported (spike)" });
+        if (!body || typeof body !== "object") return sendJson(res, 400, { error: "JSON-RPC body must be an object" });
+        if (body.jsonrpc !== "2.0") return sendJson(res, 400, { error: "jsonrpc must be 2.0" });
+        const out = await forwardRpc(body);
+        if (out === null) return sendJson(res, 204, null);
+        return sendJson(res, 200, out);
+      }
+
+      return sendJson(res, 404, { error: "not found" });
+    } catch (err) {
+      return sendJson(res, 500, { error: err?.message ?? String(err) });
+    }
+  });
+
+  // Default to loopback to avoid exposing the spike gateway on the LAN by accident.
+  // Override with MCP_HTTP_HOST=0.0.0.0 if you intentionally want a non-loopback bind.
+  const host = String(process.env.MCP_HTTP_HOST ?? "127.0.0.1").trim() || "127.0.0.1";
+
+  server.listen(port, host, () => {
+    const addr = server.address();
+    const effectivePort = addr && typeof addr === "object" ? addr.port : port;
+    process.stderr.write(`[mcp-http] listening on :${effectivePort} (POST /rpc)\n`);
+  });
+
+  function shutdown() {
+    try {
+      server.close();
+    } catch {
+      // ignore
+    }
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      // ignore
+    }
+  }
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+main();