@uuaid/pillar 0.2.0-alpha.8 → 2.0.1

package/bin/pillar-responder.mjs

@@ -31,6 +31,7 @@
  *     --reply-text "zz-master is away — left a message" \
  *     --forward-to uuaid:foundation:agent:… --forward-pubkey <hex>
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
 import { existsSync, readFileSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -38,11 +39,16 @@ 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";
+import { loadTrustPolicy, evaluateTrust, POLICIES } from "../src/identity/trust.mjs";
+import { loadFleetAddressBook } from "../src/address-book.mjs";
 
 const DEFAULT_REPLY = "pillar-responder: request acked — owner will respond through the normal channel";
+const STRANGER_REPLY = "pillar-responder: request received. This responder runs its command hook only for enrolled senders; ask the operator to `pillar trust allow` your uuaid.";
 const MAX_REPLY_BYTES = 8192;
 const HOOK_TIMEOUT_MS = 60_000;
 const REPLAY_WINDOW_MS = 24 * 3600_000;
+const SENDER_REPLIES_PER_HOUR = 30; // amplification cap: max hook/reply cycles per sender
+const RATE_WINDOW_MS = 3600_000;
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -162,6 +168,26 @@ if (!carriers.length && !enableLibp2p) {
 
 const replyText = args["reply-text"] ?? rcfg.replyText ?? DEFAULT_REPLY;
 const hookCmd = args.command ?? rcfg.command ?? null;
+// Trust gate. Default policy for the COMMAND HOOK is "directory": strangers
+// still get ack + a fixed reply (universality preserved — first contact
+// works), but attacker-controlled JSON only reaches the hook process from
+// senders the operator knows. --hook-policy open restores old behavior.
+const trust = loadTrustPolicy(home);
+const hookPolicy = args["hook-policy"] ?? rcfg.hookPolicy ?? "directory";
+if (!POLICIES.includes(hookPolicy)) {
+  console.error(`--hook-policy must be one of ${POLICIES.join("|")}`);
+  exit(2);
+}
+const senderRate = new Map(); // sender uuaid -> [ms timestamps]
+function senderAllowed(sender) {
+  const now = Date.now();
+  let arr = senderRate.get(sender);
+  if (!arr) { arr = []; senderRate.set(sender, arr); }
+  while (arr.length && now - arr[0] > RATE_WINDOW_MS) arr.shift();
+  if (arr.length >= SENDER_REPLIES_PER_HOUR) return false;
+  arr.push(now);
+  return true;
+}
 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
@@ -187,10 +213,14 @@ const p = new Pillar({
 
 await p.start();
 
+// Address book feeds the "directory" hook policy (known senders = fleet.json).
+const abCount = loadFleetAddressBook(join(home, "fleet.json"), p);
+
 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 (hookCmd) console.log(`  hook gate: policy=${hookPolicy}, known senders=${abCount}, cap=${SENDER_REPLIES_PER_HOUR}/h per sender`);
 if (fwd) console.log(`  forwardTo: ${fwd.uuaid}`);
 
 // Replay journaled-but-unfinished requests first (at-least-once).
@@ -215,7 +245,21 @@ p.onEnvelope(async (env) => {
     const thread = env.payload?.thread ?? env.id;
     let status = "ok";
     let text = replyText;
-    if (hookCmd) {
+    // Amplification cap: over-budget senders get ack only, no reply/hook.
+    if (!senderAllowed(env.sender)) {
+      await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "ack", payload: { inReplyTo: env.id } });
+      journalDone(home, env.id, { text: "(rate-capped: ack only)", status: "capped" });
+      console.log(`  ${env.sender.slice(-8)} request ${env.id.slice(0, 16)}… → ack only (rate cap)`);
+      return;
+    }
+    // Hook gate: strangers get the fixed reply, never the command hook.
+    const gate = evaluateTrust({ ...trust, policy: hookPolicy }, env.sender, new Set(p.addressBook?.keys() ?? []));
+    if (gate.reason === "blocked") {
+      journalDone(home, env.id, { text: "(blocked sender: dropped)", status: "blocked" });
+      console.log(`  ${env.sender.slice(-8)} request ${env.id.slice(0, 16)}… → dropped (blocked)`);
+      return;
+    }
+    if (hookCmd && gate.deliver) {
       const r = await runHook(hookCmd, {
         id: env.id,
         sender: env.sender,
@@ -229,6 +273,8 @@ p.onEnvelope(async (env) => {
         status = "error";
         text = r.reason;
       }
+    } else if (hookCmd && !gate.deliver) {
+      text = STRANGER_REPLY; // stranger: fixed reply, hook never sees the payload
     }
     await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "ack", payload: { inReplyTo: env.id } });
     const replyPayload = { thread, inReplyTo: env.id, status, text };

package/bin/pillar-seed.mjs

@@ -4,6 +4,8 @@
  * the p2p store-and-forward mesh, like a LimeWire/BitTorrent seed peer.
  *
  *   pillar-seed --port 8799 --db /opt/pillar-seed/seed.db
+ *   pillar-seed --public-url https://seed.example.org --announce https://pillar.uuaid.org
+ *   pillar-seed --status --announce https://pillar.uuaid.org
  *
  * A seed IS a carrier server with a public URL — nothing else.  Agents
  * anywhere list your URL in their carriers[] and then:
@@ -13,18 +15,36 @@
  * 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:
+ * JOINING
+ *
+ * Announce yourself to a registry with --announce and you are enrolled: the
+ * registry fetches /v1/seed-info from the URL you gave, checks that it is
+ * signed by your seed key, and lists you.  No account, no review, no waiting
+ * on whoever owns the directory file.
+ *
+ * WHAT YOU EARN
+ *
+ * The registry then probes you — liveness plus a real envelope round-tripped
+ * through your seed — and promotes you as the evidence accumulates:
+ *
+ *   probation -> steady (a day) -> durable (a week) -> anchor (a month)
  *
- *   { "url": "https://<your-host>", "operator": "<you>", "region": "<region>", "since": "<ISO date>" }
+ * From `steady` up, your OWN identity is issued a signed tier grant: raised
+ * send budgets at every carrier that trusts the registry's issuer key.  From
+ * `durable` up that grant also carries priority, which reserves you
+ * admission capacity at those carriers when they are shedding load.  Run
+ * --status to see your rung and exactly what is left to reach the next one.
  *
- * 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.
+ * Defaults to loopback (RedTeam F5).  To become a real seed, put it behind a
+ * TLS-terminating proxy (nginx/Caddy) and pass the PUBLIC https:// URL as
+ * --public-url — never the loopback one.
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { CarrierServer } from "../src/net/carrier-server.mjs";
+import { Keychain } from "../src/identity/keychain.mjs";
 
 function parseArgs(argv) {
   const args = {};
@@ -39,16 +59,68 @@ function parseArgs(argv) {
 }
 
 const args = parseArgs(process.argv.slice(2));
+const home = args.home ?? process.env.SEED_HOME ?? join(homedir(), ".pillar-seed");
 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 publicUrl = args["public-url"] ?? process.env.SEED_PUBLIC_URL ?? null;
+const registryUrl = typeof args.announce === "string" ? args.announce.replace(/\/+$/, "") : null;
+const operator = args.operator ?? process.env.SEED_OPERATOR ?? null;
+const region = args.region ?? process.env.SEED_REGION ?? null;
+
+/**
+ * The seed's identity. Distinct from any agent keychain on the box: it names
+ * the SEED, is what /v1/seed-info is signed with, and is the subject of any
+ * tier grant the seed earns.
+ */
+mkdirSync(home, { recursive: true });
+const keychain = new Keychain(join(home, "seed-keychain.json"));
+if (!keychain.exists()) {
+  keychain.save(Keychain.generate());
+  console.log(`minted seed identity -> ${join(home, "seed-keychain.json")}`);
+}
+keychain.load();
 
-const server = new CarrierServer({ dbPath, ttlDays });
+/** Ask a registry where we stand and print the ladder position. */
+async function printStanding(registry, uuaid) {
+  try {
+    const res = await fetch(`${registry}/v1/seeds/${encodeURIComponent(uuaid)}`);
+    if (res.status === 404) {
+      console.log(`  standing: not enrolled at ${registry} — run with --announce ${registry}`);
+      return;
+    }
+    if (!res.ok) { console.log(`  standing: registry ${res.status}`); return; }
+    const s = await res.json();
+    console.log(`  tier:    ${s.tier}${s.demoted ? " (DEMOTED — failing probes)" : ""} — ${s.blurb}`);
+    console.log(`  earned:  ${s.grantTier ? `${s.grantTier} grant${s.priority ? " + priority delivery" : ""}` : "nothing yet"}`);
+    const o = s.observed ?? {};
+    console.log(`  observed: ${o.probes?.passed ?? 0}/${o.probes?.total ?? 0} probes (${((o.uptime ?? 0) * 100).toFixed(1)}% uptime), ${o.roundTrips?.passed ?? 0} relay round-trips`);
+    if (s.next) console.log(`  next:    ${s.next} — needs ${s.missing.join(", ")}`);
+    else if (!s.demoted) console.log(`  next:    top of the ladder`);
+  } catch (e) {
+    console.log(`  standing: unreachable — ${e.message}`);
+  }
+}
+
+// --status is a query, not a server: report and exit.
+if (args.status) {
+  if (!registryUrl) {
+    console.error("--status needs --announce <registry-url> to know which registry to ask");
+    process.exit(1);
+  }
+  console.log(`seed ${keychain._identity.uuaid}`);
+  await printStanding(registryUrl, keychain._identity.uuaid);
+  process.exit(0);
+}
+
+const server = new CarrierServer({ dbPath, ttlDays, keychain, publicUrl });
 const addr = await server.listen(port, host);
 console.log(`pillar-seed listening on http://${addr.address}:${addr.port}`);
+console.log(`  uuaid: ${keychain._identity.uuaid}`);
 console.log(`  db:  ${dbPath}`);
 console.log(`  ttl: ${ttlDays} days`);
+if (publicUrl) console.log(`  public url: ${publicUrl}`);
 
 // Boot self-check on the address we actually serve — verify before claim.
 try {
@@ -60,11 +132,39 @@ try {
   console.log(`  health: unreachable — ${e.message}`);
 }
 
-if (host === "127.0.0.1") {
+if (registryUrl) {
+  if (!publicUrl) {
+    console.log(`\n  --announce needs --public-url <https://your-host>: the registry enrolls a URL,`);
+    console.log(`  and it must be one it can reach and that you can prove you operate.`);
+  } else {
+    console.log(`\n  announcing ${publicUrl} to ${registryUrl} ...`);
+    try {
+      const res = await fetch(`${registryUrl}/v1/seeds`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ url: publicUrl, operator, region }),
+      });
+      const body = await res.json().catch(() => ({}));
+      if (res.ok && body.ok) {
+        console.log(`  enrolled${body.already ? " (already)" : ""} as ${body.uuaid}`);
+        await printStanding(registryUrl, keychain._identity.uuaid);
+      } else {
+        console.log(`  enrollment refused: ${body.reason ?? res.status}`);
+        if (String(body.reason ?? "").startsWith("seed-unreachable")) {
+          console.log(`  (the registry could not fetch ${publicUrl}/v1/seed-info — check DNS, TLS, and your proxy)`);
+        }
+      }
+    } catch (e) {
+      console.log(`  enrollment failed: ${e.message}`);
+    }
+  }
+} else 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.`);
+  console.log(`  To join the mesh as a real seed: TLS-terminate a public URL, then`);
+  console.log(`    pillar-seed --host 0.0.0.0 --public-url https://<your-host> \\`);
+  console.log(`                --announce https://pillar.uuaid.org --operator <you> --region <region>`);
+  console.log(`  Enrollment is permissionless: the registry verifies the URL against your`);
+  console.log(`  seed key and lists you. Staying up is what earns the rest.`);
 }
 
 // Vacuum expired envelopes hourly.