@uuaid/pillar 0.2.0-alpha.8 → 2.0.1

package/bin/pillar-directory.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+/**
+ * pillar-directory — serve directory.json from the seed registry.
+ *
+ *   pillar-directory --port 8800 --carrier https://pillar.uuaid.org \
+ *                    --agents ./agents.json --db /opt/pillar-directory/registry.db
+ *
+ * Replaces the hand-edited directory.json that every agent bootstraps from.
+ * The file could only be changed by whoever had shell on the host serving it,
+ * which is the reason the mesh had exactly one seed. Here the seed list is a
+ * table any operator can enter by proving they run a live seed, and the rung
+ * they hold is computed from probes this process makes itself.
+ *
+ * Routes:
+ *   GET  /directory.json          the directory (carrier + agents + ranked seeds)
+ *   POST /v1/seeds                enroll { url, operator?, region? }
+ *   GET  /v1/seeds                every enrolled seed and its standing
+ *   GET  /v1/seeds/<uuaid>        one seed's standing + what is left to earn
+ *   GET  /v1/seeds/<uuaid>/grant  that seed's current earned tier grant
+ *   GET  /v1/health
+ *
+ * `agents.json` is passed through untouched: this process owns the seed list,
+ * not the address book.
+ */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
+import { createServer } from "node:http";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { SeedRegistry } from "../src/net/seed-registry.mjs";
+import { Keychain } from "../src/identity/keychain.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 home = args.home ?? process.env.DIRECTORY_HOME ?? join(homedir(), ".pillar-directory");
+const port = Number(args.port ?? process.env.DIRECTORY_PORT ?? 8800);
+const host = args.host ?? process.env.DIRECTORY_HOST ?? "127.0.0.1";
+const dbPath = args.db ?? process.env.DIRECTORY_DB ?? join(home, "registry.db");
+const carrier = args.carrier ?? process.env.DIRECTORY_CARRIER ?? null;
+const agentsPath = args.agents ?? process.env.DIRECTORY_AGENTS ?? null;
+const protocol = args.protocol ?? process.env.DIRECTORY_PROTOCOL ?? "uacp/1.0-draft";
+const probeMinutes = Number(args["probe-minutes"] ?? process.env.DIRECTORY_PROBE_MINUTES ?? 10);
+const allowPrivateUrls = Boolean(args["allow-private-urls"]);
+
+const MAX_ENROLLMENTS_PER_HOUR = 10; // per client IP
+const MAX_BODY = 8 * 1024;
+
+mkdirSync(home, { recursive: true });
+const keychain = new Keychain(join(home, "registry-keychain.json"));
+if (!keychain.exists()) {
+  keychain.save(Keychain.generate());
+  console.log(`minted registry identity -> ${join(home, "registry-keychain.json")}`);
+}
+keychain.load();
+
+const registry = new SeedRegistry({ keychain, carrierUrl: carrier, dbPath, protocol, allowPrivateUrls });
+
+/**
+ * agents[] is read fresh on each render rather than cached at boot, so
+ * updating the address book does not require restarting the directory and
+ * dropping every in-flight enrollment.
+ */
+function agents() {
+  if (!agentsPath || !existsSync(agentsPath)) return [];
+  try {
+    const raw = JSON.parse(readFileSync(agentsPath, "utf-8"));
+    return Array.isArray(raw) ? raw : (raw.agents ?? []);
+  } catch (e) {
+    console.error(`[directory] agents file unreadable: ${e.message}`);
+    return [];
+  }
+}
+
+const enrollRate = new Map(); // ip -> [ms]
+function enrollAllowed(ip) {
+  const now = Date.now();
+  const arr = (enrollRate.get(ip) ?? []).filter(t => t > now - 3600_000);
+  if (arr.length >= MAX_ENROLLMENTS_PER_HOUR) { enrollRate.set(ip, arr); return false; }
+  arr.push(now);
+  enrollRate.set(ip, arr);
+  if (enrollRate.size > 10_000) {
+    for (const [k, v] of enrollRate) if (!v.some(t => t > now - 3600_000)) enrollRate.delete(k);
+  }
+  return true;
+}
+
+function send(res, code, obj) {
+  const body = JSON.stringify(obj, null, 2);
+  res.writeHead(code, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(body),
+    // The directory is public bootstrap data; browsers fetch it directly.
+    "access-control-allow-origin": "*",
+    "cache-control": "public, max-age=60",
+  });
+  res.end(body);
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0; const chunks = [];
+    req.on("data", c => {
+      size += c.length;
+      if (size > MAX_BODY) { reject(new Error("body too large")); req.destroy(); return; }
+      chunks.push(c);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+const clientIp = (req) => {
+  const fwd = req.headers["x-forwarded-for"];
+  return fwd ? String(fwd).split(",")[0].trim() : (req.socket.remoteAddress ?? "unknown");
+};
+
+const server = createServer(async (req, res) => {
+  try {
+    const url = new URL(req.url, `http://${req.headers.host ?? "localhost"}`);
+
+    if (req.method === "GET" && (url.pathname === "/directory.json" || url.pathname === "/")) {
+      return send(res, 200, registry.directory({ agents: agents() }));
+    }
+
+    if (req.method === "POST" && url.pathname === "/v1/seeds") {
+      const ip = clientIp(req);
+      if (!enrollAllowed(ip)) return send(res, 429, { ok: false, reason: "rate-limited" });
+      let payload;
+      try { payload = JSON.parse(await readBody(req)); }
+      catch { return send(res, 400, { ok: false, reason: "bad-json" }); }
+      const r = await registry.enroll({
+        url: payload?.url,
+        operator: payload?.operator ?? null,
+        region: payload?.region ?? null,
+      });
+      if (!r.ok) console.log(`[directory] enroll refused ${payload?.url}: ${r.reason}`);
+      else if (!r.already) console.log(`[directory] enrolled ${r.url} as ${r.uuaid}`);
+      return send(res, r.ok ? 200 : 400, r);
+    }
+
+    if (req.method === "GET" && url.pathname === "/v1/seeds") {
+      return send(res, 200, { seeds: registry.all().map(r => registry.status(r.uuaid)) });
+    }
+
+    const grantMatch = /^\/v1\/seeds\/([^/]+)\/grant$/.exec(url.pathname);
+    if (req.method === "GET" && grantMatch) {
+      const uuaid = decodeURIComponent(grantMatch[1]);
+      // Served unauthenticated on purpose: a grant is only usable by the
+      // identity it names, and using it means signing an envelope with that
+      // identity's key. Holding someone else's grant buys nothing.
+      const grant = registry.grantFor(uuaid);
+      if (!grant) {
+        const known = registry.get(uuaid);
+        return send(res, known ? 200 : 404,
+          known ? { ok: true, grant: null, reason: "tier-earns-no-grant", tier: known.tier }
+                : { ok: false, reason: "unknown-seed" });
+      }
+      return send(res, 200, { ok: true, grant });
+    }
+
+    const seedMatch = /^\/v1\/seeds\/([^/]+)$/.exec(url.pathname);
+    if (req.method === "GET" && seedMatch) {
+      const st = registry.status(decodeURIComponent(seedMatch[1]));
+      return send(res, st.ok ? 200 : 404, st);
+    }
+
+    if (req.method === "GET" && url.pathname === "/v1/health") {
+      return send(res, 200, {
+        ok: true,
+        seeds: registry.all().length,
+        issuer: registry.issuerKey,
+        uptimeMs: Date.now() - startedAt,
+      });
+    }
+
+    send(res, 404, { error: "not-found" });
+  } catch (e) {
+    console.error(`[directory] 500: ${e.message}`);
+    send(res, 500, { error: "internal-error" });
+  }
+});
+
+const startedAt = Date.now();
+await new Promise(r => server.listen(port, host, r));
+console.log(`pillar-directory listening on http://${host}:${port}`);
+console.log(`  issuer: ${registry.issuerKey}`);
+console.log(`  carrier: ${carrier ?? "(none — set --carrier)"}`);
+console.log(`  db: ${dbPath}`);
+console.log(`  seeds: ${registry.all().length}`);
+console.log(`  probing every ${probeMinutes} min`);
+
+/**
+ * The observation loop. Every seed is probed on the same cadence, so the
+ * probe counts in the ladder translate directly into wall-clock time:
+ * at the default 10 minutes, `steady`'s 20 probes is ~3.3 hours of proof on
+ * top of its 1-day minimum age.
+ */
+let probing = false;
+const probeTimer = setInterval(async () => {
+  if (probing) return; // never overlap: a slow seed must not stack rounds
+  probing = true;
+  try {
+    for (const r of await registry.observeAll()) {
+      if (r.changed) console.log(`[directory] ${r.url} ${r.previousTier} -> ${r.tier}`);
+      else if (!r.alive) console.log(`[directory] ${r.url} probe failed`);
+    }
+  } catch (e) {
+    console.error(`[directory] probe round failed: ${e.message}`);
+  } finally {
+    probing = false;
+  }
+}, Math.max(1, probeMinutes) * 60_000);
+
+const shutdown = async () => {
+  clearInterval(probeTimer);
+  await new Promise(r => server.close(r));
+  registry.close();
+  process.exit(0);
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);