@uuaid/pillar 0.2.0-alpha.10

package/bin/pillar-responder.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * pillar-responder — always-on auto-attendant for the Pillar Interaction
+ * Convention.  Runs as a standalone process (with its own identity/home, so
+ * it never races a live agent daemon on the same mailbox) and answers
+ * kind=request envelopes IMMEDIATELY — no waiting for a live agent turn:
+ *
+ *   request → journal → ack (inReplyTo = request id) → reply (thread + inReplyTo + text)
+ *
+ * Reply text comes from, in order:
+ *   1. --reply-text / config responder.replyText  (static text)
+ *   2. --command / config responder.command       (spawn hook: JSON request on
+ *      stdin, stdout = reply text, non-zero exit or timeout → status:"error"
+ *      with the stderr tail as reason) — LLM-agnostic, any program works
+ *   3. builtin default text
+ *
+ * Optional --forward-to <uuaid> --forward-pubkey <hex> re-sends the request
+ * payload as kind=message to an owner identity so a live agent picks it up.
+ *
+ * At-least-once delivery: every request is journaled to
+ * <home>/responder-journal.jsonl BEFORE the ack; on startup, journaled
+ * requests without a done record from the last 24h get ack+reply re-sent
+ * (default text — the hook is not re-run, so a restart never double-executes
+ * a side-effecting command).  Duplicate acks/replies are harmless: the
+ * convention is idempotent by envelope id.
+ *
+ * Carrier-only by default (outbound HTTPS only — runs on any machine or
+ * webserver; no inbound ports, no libp2p).  Pass --libp2p to also listen.
+ *
+ *   pillar-responder --home ~/.pillar-fleet/zz-master-responder \
+ *     --reply-text "zz-master is away — left a message" \
+ *     --forward-to uuaid:foundation:agent:… --forward-pubkey <hex>
+ */
+import { existsSync, readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { argv, exit } from "node:process";
+import { spawn } from "node:child_process";
+import { Keychain } from "../src/identity/keychain.mjs";
+import { Pillar } from "../src/pillar.mjs";
+
+const DEFAULT_REPLY = "pillar-responder: request acked — owner will respond through the normal channel";
+const MAX_REPLY_BYTES = 8192;
+const HOOK_TIMEOUT_MS = 60_000;
+const REPLAY_WINDOW_MS = 24 * 3600_000;
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const [k, ...rest] = a.slice(2).split("=");
+      args[k] = rest.length ? rest.join("=") : (argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : true);
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function homePath(args) {
+  return args.home || process.env.PILLAR_HOME || join(homedir(), ".pillar");
+}
+
+// --- journal (at-least-once) -------------------------------------------------
+
+function journalPath(home) {
+  return join(home, "responder-journal.jsonl");
+}
+
+function journalRequest(home, env) {
+  appendFileSync(journalPath(home), JSON.stringify({
+    ts: new Date().toISOString(),
+    event: "request",
+    id: env.id,
+    sender: env.sender,
+    senderPublicKey: env.transportSignature.publicKey,
+    payload: env.payload,
+  }) + "\n");
+}
+
+function journalDone(home, id, reply) {
+  appendFileSync(journalPath(home), JSON.stringify({
+    ts: new Date().toISOString(),
+    event: "done",
+    id,
+    replyText: reply.text,
+    replyStatus: reply.status,
+  }) + "\n");
+}
+
+// Requests journaled but never completed, within the replay window.
+function loadPending(home) {
+  const p = journalPath(home);
+  if (!existsSync(p)) return [];
+  const done = new Set();
+  const requests = new Map();
+  for (const line of readFileSync(p, "utf-8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e.event === "done") done.add(e.id);
+      else if (e.event === "request") requests.set(e.id, e);
+    } catch (_e) { /* skip torn line */ }
+  }
+  const cutoff = Date.now() - REPLAY_WINDOW_MS;
+  return [...requests.values()].filter((r) => !done.has(r.id) && Date.parse(r.ts) > cutoff);
+}
+
+// --- command hook -------------------------------------------------------------
+
+function runHook(cmd, req, { timeoutMs, maxBytes }) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, { shell: true, stdio: ["pipe", "pipe", "pipe"] });
+    let out = Buffer.alloc(0);
+    let err = Buffer.alloc(0);
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+    child.stdout.on("data", (d) => { out = Buffer.concat([out, d]); });
+    child.stderr.on("data", (d) => { err = Buffer.concat([err, d]); });
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      resolve({ ok: false, reason: `hook spawn failed: ${e.message}` });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) {
+        const text = out.toString("utf-8").trim();
+        resolve({ ok: true, text: text ? text.slice(0, maxBytes) : null });
+      } else if (code === null) {
+        resolve({ ok: false, reason: "hook timed out" });
+      } else {
+        resolve({ ok: false, reason: (err.toString("utf-8").trim() || `hook exited ${code}`).slice(0, 300) });
+      }
+    });
+    child.stdin.write(JSON.stringify(req));
+    child.stdin.end();
+  });
+}
+
+// --- main ----------------------------------------------------------------------
+
+const args = parseArgs(process.argv.slice(2));
+const home = homePath(args);
+const kcPath = join(home, "keychain.json");
+const cfgPath = join(home, "config.json");
+
+if (!existsSync(kcPath)) {
+  console.error(`no pillar identity at ${home}. run: pillar init --home ${home}`);
+  exit(2);
+}
+const cfg = existsSync(cfgPath) ? JSON.parse(readFileSync(cfgPath, "utf-8")) : {};
+const rcfg = cfg.responder ?? {};
+
+const carriers = args.carrier
+  ? [args.carrier]
+  : (process.env.PILLAR_CARRIERS ? process.env.PILLAR_CARRIERS.split(",") : (cfg.carriers ?? []));
+const enableLibp2p = args["libp2p"] === true;
+if (!carriers.length && !enableLibp2p) {
+  console.error("responder needs at least one carrier (--carrier URL or carriers[] in config.json) or --libp2p");
+  exit(2);
+}
+
+const replyText = args["reply-text"] ?? rcfg.replyText ?? DEFAULT_REPLY;
+const hookCmd = args.command ?? rcfg.command ?? null;
+const hookTimeoutMs = Number(args["timeout-ms"] ?? rcfg.timeoutMs ?? HOOK_TIMEOUT_MS);
+const hookMaxBytes = Number(args["max-reply-bytes"] ?? MAX_REPLY_BYTES);
+const fwd = args["forward-to"] || rcfg.forwardTo?.uuaid
+  ? { uuaid: args["forward-to"] ?? rcfg.forwardTo?.uuaid, publicKey: args["forward-pubkey"] ?? rcfg.forwardTo?.publicKey }
+  : null;
+if (fwd && (!fwd.uuaid || !fwd.publicKey)) {
+  console.error("--forward-to needs both a UUAID and --forward-pubkey (encryption is mandatory)");
+  exit(2);
+}
+
+const kc = new Keychain(kcPath);
+kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+const p = new Pillar({
+  keychain: kc,
+  mailboxPath: join(home, "mailbox.db"),
+  listenAddrs: cfg.listenAddrs ?? ["/ip4/127.0.0.1/tcp/0"],
+  bootstrapPeers: cfg.bootstrapPeers ?? [],
+  enableRelay: cfg.enableRelay ?? false,
+  dhtClientMode: cfg.dhtClientMode ?? true,
+  carriers,
+  enableLibp2p,
+});
+
+await p.start();
+
+console.log(`pillar-responder up — ${p.uuaid}`);
+console.log(`  pubkey:    ${p.publicKeyHex}`);
+console.log(`  carriers:  ${carriers.length ? carriers.join(", ") : "(none — libp2p only)"}`);
+console.log(`  reply:     ${hookCmd ? `hook ${hookCmd}` : "builtin text"}`);
+if (fwd) console.log(`  forwardTo: ${fwd.uuaid}`);
+
+// Replay journaled-but-unfinished requests first (at-least-once).
+for (const r of loadPending(home)) {
+  try {
+    await p.send({ recipient: r.sender, recipientPublicKey: r.senderPublicKey, kind: "ack", payload: { inReplyTo: r.id } });
+    const replyPayload = { thread: r.payload?.thread ?? r.id, inReplyTo: r.id, status: "ok", text: replyText };
+    await p.send({ recipient: r.sender, recipientPublicKey: r.senderPublicKey, kind: "reply", payload: replyPayload });
+    journalDone(home, r.id, replyPayload);
+    console.log(`  replay: ack+reply re-sent for ${r.id.slice(0, 16)}…`);
+  } catch (e) {
+    console.error(`  replay failed for ${r.id.slice(0, 16)}…: ${e.message}`);
+  }
+}
+
+// Register the handler BEFORE polling starts so fast deliveries are caught.
+p.onEnvelope(async (env) => {
+  if (env.kind !== "request") return; // ack/reply/message stay passive (owner daemon handles them)
+  const senderKey = env.transportSignature.publicKey; // open() F1: sender derives from this key
+  try {
+    journalRequest(home, env);
+    const thread = env.payload?.thread ?? env.id;
+    let status = "ok";
+    let text = replyText;
+    if (hookCmd) {
+      const r = await runHook(hookCmd, {
+        id: env.id,
+        sender: env.sender,
+        senderPublicKey: senderKey,
+        payload: env.payload,
+        thread,
+      }, { timeoutMs: hookTimeoutMs, maxBytes: hookMaxBytes });
+      if (r.ok) {
+        if (r.text) text = r.text;
+      } else {
+        status = "error";
+        text = r.reason;
+      }
+    }
+    await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "ack", payload: { inReplyTo: env.id } });
+    const replyPayload = { thread, inReplyTo: env.id, status, text };
+    await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "reply", payload: replyPayload });
+    journalDone(home, env.id, replyPayload);
+    console.log(`  ${env.sender.slice(-8)} request ${env.id.slice(0, 16)}… → ack + reply (${status})`);
+    if (fwd) {
+      await p.send({
+        recipient: fwd.uuaid,
+        recipientPublicKey: fwd.publicKey,
+        kind: "message",
+        payload: { ...env.payload, _forwarded: { from: env.sender, requestId: env.id, thread } },
+      });
+    }
+  } catch (e) {
+    console.error(`  request ${env.id.slice(0, 16)}… failed: ${e.message} (journaled — replayed on restart)`);
+  }
+});
+
+// p.start() does NOT poll on its own — the pillar-ask trap.  waitS=20 keeps us
+// inside the carrier's MAX_WAIT_S=30 long-poll cap + the 30s ack window.
+if (p.carrierClient) p.startCarrierPolling({ waitS: 20 });
+console.log("  polling started — Ctrl-C to stop");
+
+const shutdown = async () => {
+  if (p.carrierClient) p.stopCarrierPolling();
+  process.exit(0);
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/bin/pillar-seed.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * pillar-seed — run a pillar seed: a carrier server that makes you part of
+ * the p2p store-and-forward mesh, like a LimeWire/BitTorrent seed peer.
+ *
+ *   pillar-seed --port 8799 --db /opt/pillar-seed/seed.db
+ *
+ * A seed IS a carrier server with a public URL — nothing else.  Agents
+ * anywhere list your URL in their carriers[] and then:
+ *   - deliver() replicates every envelope to you (so messages survive any
+ *     single seed dying — the BitTorrent property), and
+ *   - poll you for their inbox in parallel with every other seed.
+ * Minimal ongoing requirements: one process, one SQLite file, outbound-free
+ * (all traffic comes TO you).  That is the whole contract.
+ *
+ * Defaults to loopback (RedTeam F5).  To become a real seed, put it behind a
+ * TLS-terminating proxy (nginx/Caddy) and advertise the PUBLIC https:// URL —
+ * never the loopback one — as a seeds[] entry in a pillar directory.json:
+ *
+ *   { "url": "https://<your-host>", "operator": "<you>", "region": "<region>", "since": "<ISO date>" }
+ *
+ * Anyone running `pillar init --directory <directory-url>` then picks you up
+ * automatically as one of their carriers.  You can also be someone's ENTIRE
+ * carrier set (`--carriers https://<your-host>`) — two agents can talk with
+ * only your seed between them, no official carrier involved.
+ */
+import { CarrierServer } from "../src/net/carrier-server.mjs";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const k = a.slice(2);
+      args[k] = (argv[i + 1] && !argv[i + 1].startsWith("--")) ? argv[++i] : true;
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const port = Number(args.port ?? process.env.SEED_PORT ?? 8799);
+const host = args.host ?? process.env.SEED_HOST ?? "127.0.0.1";
+const dbPath = args.db ?? process.env.SEED_DB ?? "pillar-seed.db";
+const ttlDays = Number(args.ttl ?? process.env.SEED_TTL_DAYS ?? 14);
+
+const server = new CarrierServer({ dbPath, ttlDays });
+const addr = await server.listen(port, host);
+console.log(`pillar-seed listening on http://${addr.address}:${addr.port}`);
+console.log(`  db:  ${dbPath}`);
+console.log(`  ttl: ${ttlDays} days`);
+
+// Boot self-check on the address we actually serve — verify before claim.
+try {
+  const probeHost = addr.address === "0.0.0.0" || addr.address === "::" ? "127.0.0.1" : addr.address;
+  const res = await fetch(`http://${probeHost}:${addr.port}/v1/health`);
+  if (res.ok) console.log(`  health: ok (${res.status})`);
+  else console.log(`  health: WARN ${res.status}`);
+} catch (e) {
+  console.log(`  health: unreachable — ${e.message}`);
+}
+
+if (host === "127.0.0.1") {
+  console.log(`\n  loopback seed — reachable only from this machine.`);
+  console.log(`  To join the mesh as a real seed: TLS-terminate a public URL and list it:`);
+  console.log(`    { "url": "https://<your-host>", "operator": "<you>", "region": "<region>", "since": "${new Date().toISOString().slice(0, 10)}" }`);
+  console.log(`  in the seeds[] array of your pillar directory.json.`);
+}
+
+// Vacuum expired envelopes hourly.
+const vacuumTimer = setInterval(() => {
+  const n = server.vacuum();
+  if (n > 0) console.log(`vacuumed ${n} expired envelopes`);
+}, 3600_000);
+
+const shutdown = async () => {
+  clearInterval(vacuumTimer);
+  await server.close();
+  process.exit(0);
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);