@uuaid/pillar 0.2.0-alpha.13 → 0.2.0-alpha.17

package/src/net/seed-registry.mjs

@@ -0,0 +1,467 @@
+/**
+ * Seed registry — permissionless enrollment and earned promotion for seeds.
+ *
+ * THE PROBLEM THIS EXISTS TO FIX
+ *
+ * `pillar-seed` has always been able to run a carrier. What it could not do
+ * was JOIN: the seed list agents bootstrap from was a static directory.json
+ * edited by hand on one operator's host. A stranger who stood up a perfect
+ * seed had no way in and no reason to bother, so the mesh had one seed — the
+ * one belonging to whoever owned the file. A store-and-forward network whose
+ * survivability argument is "many independent seeds" cannot be run that way.
+ *
+ * The registry replaces the file with a process:
+ *
+ *   1. ENROLL     the operator announces a URL. The registry fetches
+ *                 <url>/v1/seed-info and checks the signature over it. That
+ *                 proves the announcer controls both the URL and the key —
+ *                 no account, no review, no operator in the loop.
+ *   2. OBSERVE    the registry probes the seed on a schedule: liveness, and
+ *                 a real envelope round-tripped through it. Only what the
+ *                 registry measures itself can promote a seed.
+ *   3. PROMOTE    thresholds crossed (net/seed-tier.mjs) raise the rung and
+ *                 issue the operator a signed tier grant — the "extra".
+ *   4. PUBLISH    directory.json is rendered from this table, ordered by
+ *                 rung, so agents bootstrap onto proven seeds first.
+ *
+ * WHAT A SEED OPERATOR IS ACTUALLY BUYING
+ *
+ * Grants are issued to the operator's own identity, so the reward for
+ * carrying other agents' traffic is that the operator's OWN traffic gets
+ * raised budgets and a reserved admission lane at every carrier trusting
+ * this issuer. The incentive points the right way: the cheapest route to
+ * priority is to become infrastructure for everyone else.
+ */
+import { createHash } from "node:crypto";
+import { isIP } from "node:net";
+import Database from "better-sqlite3";
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+import { makeTierGrant } from "../identity/tier.mjs";
+import { seal } from "./envelope.mjs";
+import { evaluateSeedTier, seedTier, GRANT_TTL_DAYS, DEMOTE_AFTER_FAILURES } from "./seed-tier.mjs";
+
+const PROBE_TIMEOUT_MS = 10_000;
+const ROUND_TRIP_WAIT_S = 5;
+/** Keep the observation window bounded so uptime reflects recent behaviour. */
+export const PROBE_WINDOW = 1000;
+
+/**
+ * Hostnames that must never be probed from a public registry. Enrollment
+ * takes a URL from an unauthenticated stranger and makes the registry fetch
+ * it, which is a server-side request forgery primitive unless it is fenced.
+ * Tests pass allowPrivateUrls to reach a loopback seed.
+ */
+function isPrivateHost(host) {
+  const h = host.toLowerCase();
+  if (h === "localhost" || h.endsWith(".localhost") || h.endsWith(".local") || h.endsWith(".internal")) return true;
+  if (isIP(h) === 4) {
+    const [a, b] = h.split(".").map(Number);
+    if (a === 10 || a === 127 || a === 0) return true;
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    if (a === 192 && b === 168) return true;
+    if (a === 169 && b === 254) return true;   // link-local / cloud metadata
+    if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT
+    return false;
+  }
+  if (isIP(h) === 6) {
+    return h === "::1" || h === "::" || h.startsWith("fc") || h.startsWith("fd") || h.startsWith("fe80");
+  }
+  return false;
+}
+
+/** Normalise + fence a candidate seed URL. Returns { ok, url } or { ok:false, reason }. */
+export function checkSeedUrl(raw, { allowPrivateUrls = false } = {}) {
+  let u;
+  try { u = new URL(String(raw)); } catch (_e) { return { ok: false, reason: "bad-url" }; }
+  if (u.protocol !== "https:" && !(allowPrivateUrls && u.protocol === "http:")) {
+    return { ok: false, reason: "https-required" };
+  }
+  if (u.username || u.password) return { ok: false, reason: "credentials-in-url" };
+  if (u.search || u.hash) return { ok: false, reason: "query-in-url" };
+  if (!allowPrivateUrls && isPrivateHost(u.hostname)) return { ok: false, reason: "private-address" };
+  const url = `${u.protocol}//${u.host}${u.pathname}`.replace(/\/+$/, "");
+  return { ok: true, url };
+}
+
+/** Verify a /v1/seed-info document: signature, key/uuaid binding, URL match. */
+export function verifySeedInfo(doc, expectedUrl) {
+  if (doc?.v !== 1) return { ok: false, reason: "bad-version" };
+  if (typeof doc.publicKey !== "string" || !/^[0-9a-f]{64}$/i.test(doc.publicKey)) {
+    return { ok: false, reason: "bad-public-key" };
+  }
+  if (typeof doc.uuaid !== "string" || !doc.uuaid.startsWith("uuaid:")) return { ok: false, reason: "bad-uuaid" };
+  // The seed's UUAID must be derived from the key that signed — the same
+  // self-authenticating rule the carrier applies to inbox reads.
+  const localId = Keychain._localIdFromKey(Buffer.from(doc.publicKey, "hex"));
+  if (doc.uuaid.split(":")[3] !== localId) return { ok: false, reason: "uuaid-key-mismatch" };
+  if (typeof doc.sig !== "string" || !/^[0-9a-f]{128}$/i.test(doc.sig)) return { ok: false, reason: "bad-sig-encoding" };
+  // The URL is inside the signed body, so a third party cannot enroll a URL
+  // it does not operate by replaying someone else's seed-info.
+  if (expectedUrl && doc.url !== expectedUrl) return { ok: false, reason: "url-mismatch" };
+  const { sig, ...rest } = doc;
+  let verified = false;
+  try { verified = Keychain.verifyDetached(doc.publicKey, Buffer.from(jcs(rest), "utf-8"), Buffer.from(sig, "hex")); }
+  catch (_e) { return { ok: false, reason: "verify-threw" }; }
+  if (!verified) return { ok: false, reason: "bad-signature" };
+  return { ok: true, doc };
+}
+
+export class SeedRegistry {
+  /**
+   * @param {object} opts
+   *   keychain      loaded Keychain — signs tier grants AND owns the probe
+   *                 identity whose inbox the round-trip test uses.
+   *   carrierUrl    the primary carrier published as directory.carrier
+   *   dbPath        SQLite path
+   *   protocol      directory.protocol string
+   *   fetchImpl     injectable fetch (tests)
+   *   allowPrivateUrls  permit loopback seeds (tests / local networks)
+   */
+  constructor({ keychain, carrierUrl, dbPath = "seed-registry.db", protocol = "uacp/1.0-draft", fetchImpl = globalThis.fetch, allowPrivateUrls = false } = {}) {
+    if (!keychain?._identity) throw new Error("SeedRegistry needs a loaded keychain");
+    this.keychain = keychain;
+    this.carrierUrl = carrierUrl ? String(carrierUrl).replace(/\/+$/, "") : null;
+    this.protocol = protocol;
+    this.fetch = fetchImpl;
+    this.allowPrivateUrls = allowPrivateUrls;
+    this.db = new Database(dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.exec(`
+      create table if not exists seeds (
+        uuaid        text primary key,
+        url          text not null unique,
+        public_key   text not null,
+        operator     text,
+        region       text,
+        enrolled_at  text not null,
+        tier         text not null default 'probation',
+        probes_total integer not null default 0,
+        probes_passed integer not null default 0,
+        rt_total     integer not null default 0,
+        rt_passed    integer not null default 0,
+        consecutive_failures integer not null default 0,
+        last_probe_at text,
+        last_pass_at  text,
+        claimed      text,
+        promoted_at  text,
+        -- The last PROBE_WINDOW outcomes, oldest first, as '1'/'0'. Storing
+        -- the outcomes rather than a running ratio is what makes the window
+        -- actually slide: probes_total/probes_passed are derived from it.
+        probe_log    text not null default ''
+      );
+      create index if not exists idx_seeds_tier on seeds(tier);
+    `);
+    // Idempotent migration for registries created before probe_log existed.
+    const cols = this.db.pragma("table_info(seeds)").map(c => c.name);
+    if (!cols.includes("probe_log")) {
+      this.db.exec("alter table seeds add column probe_log text not null default ''");
+    }
+  }
+
+  close() { if (this.db.open) this.db.close(); }
+
+  get uuaid() { return this.keychain._identity.uuaid; }
+  get issuerKey() { return this.keychain._identity.publicKeyHex; }
+
+  /** Row -> the record shape evaluateSeedTier expects. */
+  static _record(row) {
+    return {
+      enrolledAt: row.enrolled_at,
+      probes: { total: row.probes_total, passed: row.probes_passed },
+      roundTrips: { total: row.rt_total, passed: row.rt_passed },
+      consecutiveFailures: row.consecutive_failures,
+    };
+  }
+
+  get(uuaid) { return this.db.prepare("select * from seeds where uuaid = ?").get(uuaid); }
+  all() { return this.db.prepare("select * from seeds").all(); }
+
+  /**
+   * Enroll a seed by announced URL. Permissionless: the only gate is that
+   * <url>/v1/seed-info answers with a document signed by the key whose UUAID
+   * it claims, naming this exact URL.
+   *
+   * Re-announcing an already-enrolled URL is a no-op that returns the current
+   * standing rather than an error, so an operator restarting a seed does not
+   * have to care whether it enrolled before.
+   */
+  async enroll({ url, operator = null, region = null, now = Date.now() }) {
+    const checked = checkSeedUrl(url, { allowPrivateUrls: this.allowPrivateUrls });
+    if (!checked.ok) return { ok: false, reason: checked.reason };
+
+    let doc;
+    try {
+      const res = await this.fetch(`${checked.url}/v1/seed-info`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+      if (!res.ok) return { ok: false, reason: `seed-info-${res.status}` };
+      doc = await res.json();
+    } catch (e) {
+      return { ok: false, reason: `seed-unreachable: ${e.message}` };
+    }
+    const v = verifySeedInfo(doc, checked.url);
+    if (!v.ok) return { ok: false, reason: `seed-info-invalid:${v.reason}` };
+
+    const existing = this.get(doc.uuaid);
+    if (existing) {
+      if (existing.url !== checked.url) return { ok: false, reason: "uuaid-already-enrolled-at-other-url" };
+      return { ok: true, already: true, ...this.status(doc.uuaid) };
+    }
+    // A URL can only ever belong to one identity: otherwise a second key
+    // could enroll the same host and inherit its observed history.
+    const urlTaken = this.db.prepare("select uuaid from seeds where url = ?").get(checked.url);
+    if (urlTaken) return { ok: false, reason: "url-already-enrolled" };
+
+    this.db.prepare(`
+      insert into seeds (uuaid, url, public_key, operator, region, enrolled_at, tier, claimed)
+      values (?,?,?,?,?,?,'probation',?)
+    `).run(doc.uuaid, checked.url, doc.publicKey.toLowerCase(), operator, region,
+           new Date(now).toISOString(), JSON.stringify(doc.stats ?? {}));
+    return { ok: true, already: false, ...this.status(doc.uuaid) };
+  }
+
+  /**
+   * Record one health-probe outcome into an exact sliding window of the last
+   * PROBE_WINDOW probes.
+   *
+   * The obvious cheap alternatives both misreport a seed that has been up a
+   * long time and then degrades. Capping the counters freezes the ratio, so
+   * 1000/1000 stays 100% through any number of later failures. Decaying them
+   * multiplicatively has integer fixed points — floor(950 * 0.999) + 1 is
+   * 950 — so a recovered seed can never climb back. Keeping the outcomes
+   * themselves costs ~1 KiB per seed and is simply correct in both
+   * directions.
+   */
+  recordProbe(uuaid, passed, now = Date.now()) {
+    const row = this.get(uuaid);
+    if (!row) return;
+    const log = ((row.probe_log ?? "") + (passed ? "1" : "0")).slice(-PROBE_WINDOW);
+    const total = log.length;
+    let pass = 0;
+    for (let i = 0; i < log.length; i++) if (log[i] === "1") pass++;
+    const iso = new Date(now).toISOString();
+    this.db.prepare(`
+      update seeds set
+        probe_log = ?,
+        probes_total = ?,
+        probes_passed = ?,
+        consecutive_failures = case when ? then 0 else consecutive_failures + 1 end,
+        last_probe_at = ?,
+        last_pass_at = case when ? then ? else last_pass_at end
+      where uuaid = ?
+    `).run(log, total, pass, passed ? 1 : 0, iso, passed ? 1 : 0, iso, uuaid);
+  }
+
+  /** Record one relay round-trip outcome. */
+  recordRoundTrip(uuaid, passed) {
+    this.db.prepare(`
+      update seeds set rt_total = rt_total + 1,
+                       rt_passed = case when ? then rt_passed + 1 else rt_passed end
+      where uuaid = ?
+    `).run(passed ? 1 : 0, uuaid);
+  }
+
+  /** GET <url>/v1/health — the liveness half of an observation. */
+  async healthProbe(row) {
+    try {
+      const res = await this.fetch(`${row.url}/v1/health`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+      if (!res.ok) return false;
+      const body = await res.json();
+      return body?.ok === true;
+    } catch (_e) { return false; }
+  }
+
+  /**
+   * Push a real signed envelope THROUGH the seed and read it back out.
+   *
+   * This is the load-bearing measurement: a seed passes only by doing the
+   * exact job it exists for — accept a signed envelope, store it, and serve
+   * it to an authenticated poller. Uptime alone would promote a host that
+   * answers /v1/health and drops mail.
+   */
+  async roundTripProbe(row, { now = Date.now() } = {}) {
+    const me = this.keychain._identity;
+    let envelope;
+    try {
+      envelope = seal(this.keychain, {
+        recipient: me.uuaid,
+        recipientPublicKey: me.publicKeyHex,
+        kind: "seed-probe",
+        payload: { probe: true, seed: row.uuaid, at: new Date(now).toISOString() },
+      });
+    } catch (e) { return { ok: false, reason: `seal-failed: ${e.message}` }; }
+
+    try {
+      const post = await this.fetch(`${row.url}/v1/envelopes`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(envelope),
+        signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+      });
+      if (post.status !== 202) return { ok: false, reason: `deliver-${post.status}` };
+      const receipt = await post.json();
+      if (!receipt?.accepted) return { ok: false, reason: "deliver-not-accepted" };
+
+      // Poll from just below the receipt seq so the probe envelope is in
+      // range regardless of how much unrelated traffic the seed carries.
+      const since = Math.max(0, Number(receipt.seq) - 1);
+      const path = `GET /v1/inbox/${me.uuaid}?since=${since}`;
+      const ts = String(Date.now());
+      const sig = this.keychain.sign(Buffer.from(`${path}\n${ts}`, "utf-8")).toString("hex");
+      const res = await this.fetch(
+        `${row.url}/v1/inbox/${encodeURIComponent(me.uuaid)}?since=${since}&wait=${ROUND_TRIP_WAIT_S}`,
+        {
+          headers: { "x-pillar-pubkey": me.publicKeyHex, "x-pillar-ts": ts, "x-pillar-sig": sig },
+          signal: AbortSignal.timeout(PROBE_TIMEOUT_MS + ROUND_TRIP_WAIT_S * 1000),
+        },
+      );
+      if (res.status !== 200) return { ok: false, reason: `inbox-${res.status}` };
+      const body = await res.json();
+      const found = (body?.envelopes ?? []).some(e => e?.envelope?.id === envelope.id);
+      return found ? { ok: true } : { ok: false, reason: "envelope-not-returned" };
+    } catch (e) {
+      return { ok: false, reason: `probe-threw: ${e.message}` };
+    }
+  }
+
+  /**
+   * One full observation of one seed: liveness, then (only if live) a relay
+   * round trip. A dead seed is not charged a failed round-trip on top of a
+   * failed health probe — one outage, one mark.
+   */
+  async observe(row, { now = Date.now() } = {}) {
+    const alive = await this.healthProbe(row);
+    this.recordProbe(row.uuaid, alive, now);
+    let rt = null;
+    if (alive) {
+      rt = await this.roundTripProbe(row, { now });
+      this.recordRoundTrip(row.uuaid, rt.ok);
+    }
+    const evaluated = this.evaluate(row.uuaid, now);
+    return { uuaid: row.uuaid, url: row.url, alive, roundTrip: rt, ...evaluated };
+  }
+
+  /** Observe every enrolled seed. Sequential: probes are cheap and ordering keeps logs readable. */
+  async observeAll({ now = Date.now() } = {}) {
+    const out = [];
+    for (const row of this.all()) out.push(await this.observe(row, { now }));
+    return out;
+  }
+
+  /**
+   * Recompute a seed's rung from observations and persist it. Returns the
+   * evaluation plus whether the rung moved, so callers can log promotions
+   * without diffing.
+   */
+  evaluate(uuaid, now = Date.now()) {
+    const row = this.get(uuaid);
+    if (!row) return { ok: false, reason: "unknown-seed" };
+    const before = row.tier;
+    const ev = evaluateSeedTier(SeedRegistry._record(row), now);
+    if (ev.tier !== before) {
+      this.db.prepare("update seeds set tier = ?, promoted_at = ? where uuaid = ?")
+        .run(ev.tier, new Date(now).toISOString(), uuaid);
+    }
+    return { ok: true, ...ev, previousTier: before, changed: ev.tier !== before };
+  }
+
+  /**
+   * The earned grant for a seed's current rung, or null on `probation`.
+   *
+   * Issued fresh each call with a GRANT_TTL_DAYS expiry. That TTL is the
+   * whole revocation story: a seed that stops serving stops being re-issued,
+   * and its last grant dies on its own within the window.
+   */
+  grantFor(uuaid, now = Date.now()) {
+    const row = this.get(uuaid);
+    if (!row) return null;
+    const rung = seedTier(row.tier);
+    if (!rung.grant) return null;
+    return makeTierGrant(this.keychain, {
+      uuaid: row.uuaid,
+      tier: rung.grant,
+      expires: new Date(now + GRANT_TTL_DAYS * 86_400_000).toISOString(),
+      priority: rung.priority,
+      seedTier: rung.name,
+      seedUrl: row.url,
+    });
+  }
+
+  /** Operator-facing standing: rung, what it earned, and what is left to earn. */
+  status(uuaid, now = Date.now()) {
+    const row = this.get(uuaid);
+    if (!row) return { ok: false, reason: "unknown-seed" };
+    const ev = evaluateSeedTier(SeedRegistry._record(row), now);
+    const rung = seedTier(ev.tier);
+    return {
+      ok: true,
+      uuaid: row.uuaid,
+      url: row.url,
+      operator: row.operator,
+      region: row.region,
+      enrolledAt: row.enrolled_at,
+      tier: ev.tier,
+      blurb: rung.blurb,
+      priority: rung.priority,
+      grantTier: rung.grant,
+      demoted: ev.demoted,
+      next: ev.next,
+      missing: ev.missing,
+      observed: {
+        probes: { total: row.probes_total, passed: row.probes_passed },
+        roundTrips: { total: row.rt_total, passed: row.rt_passed },
+        uptime: Number(ev.uptime.toFixed(4)),
+        consecutiveFailures: row.consecutive_failures,
+        lastProbeAt: row.last_probe_at,
+        lastPassAt: row.last_pass_at,
+      },
+    };
+  }
+
+  /**
+   * Render directory.json.
+   *
+   * Seeds are ordered by rung (proven first) and demoted seeds are dropped
+   * entirely: the directory is what a fresh agent bootstraps its carrier list
+   * from, and handing it a host that failed its last three probes is how you
+   * get a first-run experience of silent message loss.
+   */
+  directory({ agents = [], now = Date.now(), includeProbation = true } = {}) {
+    const rows = this.all()
+      .map(r => ({ r, ev: evaluateSeedTier(SeedRegistry._record(r), now) }))
+      .filter(({ ev }) => !ev.demoted)
+      .filter(({ ev }) => includeProbation || ev.tier !== "probation")
+      .sort((a, b) => {
+        const d = seedTier(a.ev.tier).listRank - seedTier(b.ev.tier).listRank;
+        return d !== 0 ? d : a.r.enrolled_at.localeCompare(b.r.enrolled_at);
+      });
+    return {
+      protocol: this.protocol,
+      carrier: this.carrierUrl,
+      updated: new Date(now).toISOString(),
+      issuer: this.issuerKey,
+      agents,
+      seeds: rows.map(({ r, ev }) => ({
+        url: r.url,
+        operator: r.operator ?? undefined,
+        region: r.region ?? undefined,
+        since: r.enrolled_at.slice(0, 10),
+        // Published so a client can rank carriers without asking the
+        // registry a second question (see CarrierClient carrierTiers).
+        tier: ev.tier,
+        priority: seedTier(ev.tier).priority,
+        // String decimal, not a float: directory.json has to survive JCS
+        // canonicalization (directoryEtag, and any future signed directory),
+        // and JCS admits no non-integer number.
+        uptime: ev.uptime.toFixed(4),
+      })),
+    };
+  }
+
+  /** Stable id for a directory render — lets a publisher skip no-op writes. */
+  static directoryEtag(dir) {
+    const { updated, ...rest } = dir;
+    return createHash("sha256").update(jcs(rest)).digest("hex").slice(0, 16);
+  }
+}
+
+export { DEMOTE_AFTER_FAILURES };

package/src/net/seed-tier.mjs

@@ -0,0 +1,185 @@
+/**
+ * Seed tiers — what a seed operator EARNS by staying up.
+ *
+ * A seed is just a carrier server with a public URL (see bin/pillar-seed.mjs).
+ * Running one costs money and attention, and until now it bought the operator
+ * nothing: the only reward was altruism, which is why the mesh had exactly one
+ * seed. This module defines the ladder that turns sustained service into
+ * concrete privileges.
+ *
+ * WHAT COUNTS AS SERVICE (and why it is not self-reported)
+ *
+ * A seed cannot promote itself by claiming numbers. Every threshold below is
+ * measured from observations the REGISTRAR makes against the seed:
+ *
+ *   - health probes   GET /v1/health on a schedule. Unfakeable: the seed
+ *                     either answers within the timeout or it does not.
+ *   - round trips     the registrar seals a real envelope to its own probe
+ *                     identity, POSTs it THROUGH the seed, then polls the
+ *                     seed's inbox for it. Passing means the seed genuinely
+ *                     stored and served a signed envelope — the exact job a
+ *                     seed exists to do. "A few exchanges" is this counter.
+ *
+ * The seed's own counters (envelopes relayed, distinct peers) are collected
+ * for display via /v1/seed-info but never gate a promotion, because a seed
+ * operator controls them.
+ *
+ * REVOCATION IS EXPIRY
+ *
+ * A promotion issues a short-TTL tier grant (GRANT_TTL_DAYS). Continued
+ * service renews it on the next evaluation; a seed that goes dark simply
+ * stops being renewed and its grant lapses. There is no revocation list to
+ * distribute, and no way for a stale grant to outlive the service that
+ * earned it by more than one TTL.
+ */
+
+const DAY = 86_400_000;
+
+/** How long an earned grant lives before it must be re-earned. */
+export const GRANT_TTL_DAYS = 14;
+
+/**
+ * Consecutive failed probes that knock a seed back to `probation`.
+ * Deliberately small: a seed that cannot answer three probes in a row is not
+ * one an agent should be told to depend on.
+ */
+export const DEMOTE_AFTER_FAILURES = 3;
+
+/**
+ * The ladder, lowest first. Each rung is cumulative — a seed holds the
+ * HIGHEST rung whose every threshold it meets.
+ *
+ * `grant` names the row of TIER_DEFAULTS (identity/tier.mjs) the operator's
+ * own identity is granted while it holds this rung. That is the "extra": the
+ * budgets that previously required off-wire foundation review are earned
+ * automatically by keeping a seed alive.
+ *
+ * `priority` marks the rungs whose holders get the reserved admission lane at
+ * every carrier that trusts the issuer (see carrier-server.mjs).
+ */
+export const SEED_TIERS = [
+  {
+    name: "probation",
+    minAgeMs: 0,
+    minProbes: 0,
+    minUptime: 0,
+    minRoundTrips: 0,
+    grant: null,
+    priority: false,
+    /** Sort key for directory.json — lower is listed first. */
+    listRank: 3,
+    blurb: "enrolled; still proving it stays up",
+  },
+  {
+    name: "steady",
+    minAgeMs: DAY,
+    minProbes: 20,
+    minUptime: 0.95,
+    minRoundTrips: 10,
+    grant: "supporter",
+    priority: false,
+    listRank: 2,
+    blurb: "up a day, relaying real traffic",
+  },
+  {
+    name: "durable",
+    minAgeMs: 7 * DAY,
+    minProbes: 150,
+    minUptime: 0.99,
+    minRoundTrips: 100,
+    grant: "org",
+    priority: true,
+    listRank: 1,
+    blurb: "a week of near-perfect uptime",
+  },
+  {
+    name: "anchor",
+    minAgeMs: 30 * DAY,
+    minProbes: 700,
+    minUptime: 0.995,
+    minRoundTrips: 1000,
+    grant: "enterprise",
+    priority: true,
+    listRank: 0,
+    blurb: "a month; the mesh can be pinned to it",
+  },
+];
+
+export const SEED_TIER_NAMES = SEED_TIERS.map(t => t.name);
+
+/** Look a rung up by name. Unknown names resolve to `probation` (fail low). */
+export function seedTier(name) {
+  return SEED_TIERS.find(t => t.name === name) ?? SEED_TIERS[0];
+}
+
+/** True when `a` sits at or above `b` on the ladder. */
+export function seedTierAtLeast(a, b) {
+  return SEED_TIERS.findIndex(t => t.name === a) >= SEED_TIERS.findIndex(t => t.name === b);
+}
+
+/**
+ * Observed uptime as a fraction, or 0 when nothing has been observed yet.
+ * Kept explicit so "no probes" can never read as "100% uptime".
+ */
+export function uptimeOf(record) {
+  const total = record?.probes?.total ?? 0;
+  if (total <= 0) return 0;
+  return (record.probes.passed ?? 0) / total;
+}
+
+/**
+ * Decide a seed's rung from the registrar's observation record.
+ *
+ * @param {object} record  { enrolledAt, probes:{total,passed}, roundTrips:{passed},
+ *                           consecutiveFailures }
+ * @param {number} now     epoch ms (injectable for tests)
+ * @returns {{ tier: string, demoted: boolean, next: string|null, missing: string[],
+ *             ageMs: number, uptime: number, roundTrips: number }}
+ *          `missing` names the thresholds blocking the NEXT rung, so an
+ *          operator can be told what is actually left to do rather than just
+ *          "not yet".
+ */
+export function evaluateSeedTier(record, now = Date.now()) {
+  const enrolledMs = Date.parse(record?.enrolledAt ?? "");
+  const ageMs = Number.isFinite(enrolledMs) ? Math.max(0, now - enrolledMs) : 0;
+  const uptime = uptimeOf(record);
+  const probes = record?.probes?.total ?? 0;
+  const roundTrips = record?.roundTrips?.passed ?? 0;
+  const failures = record?.consecutiveFailures ?? 0;
+
+  // A currently-failing seed is not a seed anyone should be routed to, no
+  // matter how good its history looks.
+  if (failures >= DEMOTE_AFTER_FAILURES) {
+    return {
+      tier: "probation",
+      demoted: true,
+      next: null,
+      missing: [`answer a health probe (${failures} consecutive failures)`],
+      ageMs, uptime, roundTrips,
+    };
+  }
+
+  const meets = (t) =>
+    ageMs >= t.minAgeMs &&
+    probes >= t.minProbes &&
+    uptime >= t.minUptime &&
+    roundTrips >= t.minRoundTrips;
+
+  let held = SEED_TIERS[0];
+  for (const t of SEED_TIERS) {
+    if (meets(t)) held = t; else break;
+  }
+  const nextRung = SEED_TIERS[SEED_TIERS.indexOf(held) + 1] ?? null;
+
+  const missing = [];
+  if (nextRung) {
+    if (ageMs < nextRung.minAgeMs) {
+      missing.push(`${Math.ceil((nextRung.minAgeMs - ageMs) / DAY)}d more enrolled`);
+    }
+    if (probes < nextRung.minProbes) missing.push(`${nextRung.minProbes - probes} more health probes`);
+    if (uptime < nextRung.minUptime) missing.push(`uptime ${(uptime * 100).toFixed(1)}% < ${(nextRung.minUptime * 100).toFixed(1)}%`);
+    if (roundTrips < nextRung.minRoundTrips) missing.push(`${nextRung.minRoundTrips - roundTrips} more relay round-trips`);
+  }
+
+  return { tier: held.name, demoted: false, next: nextRung?.name ?? null, missing, ageMs, uptime, roundTrips };
+}

package/src/node-check.mjs

@@ -0,0 +1,32 @@
+/**
+ * Node.js version gate for the pillar command-line tools.
+ *
+ * Every bin imports this module FIRST, so it runs before any dependency does.
+ * Measured 2026-09-24 with the published alpha.16: on Node 20 and 21 the
+ * libp2p stack calls Promise.withResolvers (first shipped unflagged in Node
+ * 22.0.0) deep inside its peer store, so `pillar id` died with "TypeError:
+ * Promise.withResolvers is not a function" instead of saying what was wrong.
+ * package.json `engines` states the same floor, but npm only warns about
+ * engines; this turns the warning into a clear refusal.
+ */
+import { basename } from "node:path";
+
+export const MIN_NODE_MAJOR = 22;
+
+/**
+ * Returns a human-readable reason this Node.js version cannot run pillar, or
+ * null when it can. An unparseable version passes: this gate exists to explain
+ * a known failure, not to guess about builds it cannot read.
+ */
+export function nodeVersionProblem(version = process.versions.node, tool = "pillar") {
+  const major = Number.parseInt(String(version).split(".")[0], 10);
+  if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR) return null;
+  return `${tool} needs Node.js ${MIN_NODE_MAJOR} or newer (found v${version}). ` +
+    `Install the current LTS from https://nodejs.org and run it again.`;
+}
+
+const problem = nodeVersionProblem(process.versions.node, basename(process.argv[1] ?? "pillar").replace(/\.mjs$/, ""));
+if (problem) {
+  process.stderr.write(`${problem}\n`);
+  process.exit(1);
+}