@uuaid/agent-commons 0.0.0 → 0.2.0-alpha.4

package/src/vendor/pillar/net/envelope.mjs

@@ -0,0 +1,258 @@
+/**
+ * Envelope v2 — the wire format for pillar-to-pillar messages.
+ *
+ * ENCRYPTION IS FUNDAMENTAL.  There is no plaintext payload mode.  Every
+ * envelope's payload is sealed to the recipient's key before the envelope
+ * is signed.  Anyone can VERIFY an envelope (transport signature is public);
+ * only the recipient can READ it.
+ *
+ * Envelope v2 = {
+ *   version:   "uuaid-pillar-envelope/2",
+ *   id:        "env-...",
+ *   sender:    "uuaid:...",
+ *   recipient: "uuaid:...",
+ *   kind:      "message" | "work-order" | ...   (routing hint, NOT secret)
+ *   createdAt: ISO 8601,
+ *   enc: { alg: "x25519-hkdf-sha256-aes256gcm", epk, iv, ct },   // sealed payload
+ *   transportSignature: { alg: "ed25519", keyId, publicKey, signature, created },
+ * }
+ *
+ * The transport signature covers everything (including the ciphertext), so
+ * tamper detection works WITHOUT decrypting — carriers verify-then-store.
+ * The GCM AAD binds the ciphertext to the envelope id, so a valid ciphertext
+ * cannot be transplanted into a different envelope even by the sender.
+ *
+ * seal() enforces identity binding: recipient UUAID local-id must equal
+ * sha256(recipientPublicKey) — you cannot encrypt to a key that doesn't own
+ * the UUAID you're addressing.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain, isStrictEd25519PublicKey } from "../identity/keychain.mjs";
+import { sealPayload, openPayload, E2E_ALG } from "../crypto/e2e.mjs";
+import { verifyDelegationDoc, delegationCoversKind, CAPABILITY_ONLY_KINDS } from "./delegation.mjs";
+
+export const ENVELOPE_VERSION = "uuaid-pillar-envelope/2";
+export { E2E_ALG };
+
+/**
+ * Build, encrypt, and sign an envelope.
+ *
+ * keychain: a loaded Keychain (has .sign()).
+ * body: {
+ *   recipient:           "uuaid:..."          REQUIRED
+ *   recipientPublicKey:  ed25519 pubkey hex   REQUIRED (E2E is not optional)
+ *   kind, payload, id, createdAt              optional
+ * }
+ */
+export function seal(keychain, body) {
+  const identity = keychain._identity;
+  if (!identity) throw new Error("keychain not loaded");
+  const sender = body.sender ?? identity.uuaid;
+  if (sender !== identity.uuaid) {
+    throw new Error(`envelope.sender ${sender} does not match keychain identity ${identity.uuaid}`);
+  }
+  if (!body.recipient || typeof body.recipient !== "string") {
+    throw new Error("seal: recipient required");
+  }
+  if (!body.recipientPublicKey || !/^[0-9a-f]{64}$/i.test(body.recipientPublicKey)) {
+    throw new Error("seal: recipientPublicKey (ed25519 hex) is REQUIRED — encryption is not optional");
+  }
+  // Identity binding: the key must own the UUAID.
+  const expectedLocalId = Keychain._localIdFromKey(Buffer.from(body.recipientPublicKey, "hex"));
+  const recipientLocalId = body.recipient.split(":")[3];
+  if (recipientLocalId !== expectedLocalId) {
+    throw new Error(`seal: recipientPublicKey does not derive recipient UUAID (key owns ...${expectedLocalId.slice(0, 13)}, envelope addressed to ...${String(recipientLocalId).slice(0, 13)})`);
+  }
+
+  const id = body.id ?? mkEnvelopeId();
+  const enc = sealPayload(body.recipientPublicKey, body.payload ?? {}, { aad: id });
+
+  const envelope = {
+    version: ENVELOPE_VERSION,
+    id,
+    sender,
+    recipient: body.recipient,
+    kind: body.kind ?? "message",
+    enc,
+    createdAt: body.createdAt ?? new Date().toISOString(),
+  };
+  const canonical = jcs(envelope);
+  const sigBytes = keychain.sign(Buffer.from(canonical, "utf-8"));
+  envelope.transportSignature = {
+    alg: "ed25519",
+    keyId: identity.uuaid,
+    publicKey: identity.publicKeyHex,
+    signature: sigBytes.toString("hex"),
+    created: envelope.createdAt,
+  };
+  return envelope;
+}
+
+/**
+ * Verify an envelope's transport signature and structure.  Does NOT decrypt.
+ * Anyone (carriers, relays, auditors) can call this.
+ * Returns { ok: true } or { ok: false, reason }.
+ *
+ * DELEGATED ENVELOPES (UACP/1.0 ext): when the optional `delegation` field is
+ * present, the self-authenticating-sender rule is replaced by the delegation
+ * chain — see openDelegated() below and src/net/delegation.mjs.  When the
+ * field is ABSENT the checks below are byte-for-byte the legacy behavior.
+ */
+export function open(envelope, { cryptoInventory } = {}) {
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) return { ok: false, reason: "not-object" };
+  if (envelope.version !== ENVELOPE_VERSION) return { ok: false, reason: `bad-version ${envelope.version}` };
+  const sig = envelope.transportSignature;
+  if (!sig || typeof sig !== "object" || sig.alg !== "ed25519") return { ok: false, reason: "missing-or-bad-alg" };
+  if (cryptoInventory && cryptoInventory[sig.alg] !== "active") {
+    return { ok: false, reason: `alg-not-active:${sig.alg}` };
+  }
+  if (envelope.delegation !== undefined) {
+    return openDelegated(envelope, { cryptoInventory });
+  }
+  if (sig.keyId !== envelope.sender) return { ok: false, reason: "keyId-sender-mismatch" };
+  if (typeof sig.publicKey !== "string" || !/^[0-9a-f]{64}$/i.test(sig.publicKey)) return { ok: false, reason: "bad-publicKey" };
+  if (!isStrictEd25519PublicKey(sig.publicKey)) return { ok: false, reason: "weak-publicKey" }; // @rule envelope.open-strict-key
+  if (typeof sig.signature !== "string" || !/^[0-9a-f]{128}$/i.test(sig.signature)) return { ok: false, reason: "bad-signature-encoding" };
+  // Structural checks on the encryption block — an envelope without one is invalid.
+  const enc = envelope.enc;
+  if (!enc || typeof enc !== "object") return { ok: false, reason: "missing-enc" };
+  if (enc.alg !== E2E_ALG) return { ok: false, reason: `enc-alg-not-supported:${enc.alg}` };
+  if (cryptoInventory && cryptoInventory[enc.alg] && cryptoInventory[enc.alg] !== "active") {
+    return { ok: false, reason: `enc-alg-not-active:${enc.alg}` };
+  }
+  if (typeof enc.epk !== "string" || !/^[0-9a-f]{64}$/i.test(enc.epk)) return { ok: false, reason: "bad-epk" };
+  if (typeof enc.iv !== "string" || !/^[0-9a-f]{24}$/i.test(enc.iv)) return { ok: false, reason: "bad-iv" };
+  if (typeof enc.ct !== "string" || !/^[0-9a-f]{32,}$/i.test(enc.ct)) return { ok: false, reason: "bad-ct" };
+  // Verify the signature over the envelope WITHOUT the signature block.
+  const { transportSignature: _sig, ...withoutSig } = envelope;
+  let canonical;
+  try { canonical = jcs(withoutSig); } catch (_e) { return { ok: false, reason: "bad-canonical" }; }
+  let okSig;
+  try {
+    okSig = Keychain.verifyDetached(sig.publicKey, Buffer.from(canonical, "utf-8"), Buffer.from(sig.signature, "hex"));
+  } catch (_e) {
+    return { ok: false, reason: "verify-threw" };
+  }
+  if (!okSig) return { ok: false, reason: "bad-signature" };
+  // Sender binding (self-authenticating identity): the sender UUAID's
+  // local-id MUST derive from the signing key — the sender-side mirror of
+  // seal()'s recipient binding.  Without this, anyone can sign an envelope
+  // with their own key while claiming another agent's sender UUAID.
+  const expectedSenderLocalId = Keychain._localIdFromKey(Buffer.from(sig.publicKey, "hex"));
+  if (expectedSenderLocalId !== String(envelope.sender).split(":")[3]) {
+    return { ok: false, reason: "publicKey-sender-mismatch" };
+  }
+  return { ok: true };
+}
+
+/**
+ * Delegated path of open() — UACP/1.0 extension.  Invoked when the envelope
+ * carries a `delegation` document; the legacy self-authenticating-sender rule
+ * is REPLACED by the five delegation checks (see delegation.mjs):
+ *
+ *   (a) envelope signature valid under the DELEGATE's key,
+ *       transportSignature.keyId === delegation.delegate;
+ *   (b) delegation document signature valid under the PRINCIPAL's key,
+ *       delegation.principal === envelope.sender,
+ *       delegation.delegate === the signing key's uuaid;
+ *   (c) local-id binding for BOTH identities (inside verifyDelegationDoc);
+ *   (d) now within [notBefore, notAfter] (inside verifyDelegationDoc);
+ *   (e) envelope.kind covered by delegation.kinds.
+ *
+ * Fail-open is not an option: any failure rejects with
+ * { ok: false, reason: "delegation-invalid:<reason>", code: 403 }.  Pure
+ * wire-format failures (enc block, hex encodings) keep the legacy reasons and
+ * 400 status — they are not delegation verdicts.
+ *
+ * The `delegation` field is part of the SIGNED body (sealed inside the
+ * canonicalization by the delegate), so a carrier cannot strip or swap it
+ * without breaking the envelope signature.
+ */
+function openDelegated(envelope, { cryptoInventory } = {}) {
+  const reject = (reason) => ({ ok: false, reason: `delegation-invalid:${reason}`, code: 403 });
+  const sig = envelope.transportSignature;
+  if (typeof sig.publicKey !== "string" || !/^[0-9a-f]{64}$/i.test(sig.publicKey)) return { ok: false, reason: "bad-publicKey" };
+  if (!isStrictEd25519PublicKey(sig.publicKey)) return { ok: false, reason: "weak-publicKey" }; // @rule envelope.open-delegated-strict-key
+  if (typeof sig.signature !== "string" || !/^[0-9a-f]{128}$/i.test(sig.signature)) return { ok: false, reason: "bad-signature-encoding" };
+  // Structural checks on the encryption block — same rules as the legacy path.
+  const enc = envelope.enc;
+  if (!enc || typeof enc !== "object") return { ok: false, reason: "missing-enc" };
+  if (enc.alg !== E2E_ALG) return { ok: false, reason: `enc-alg-not-supported:${enc.alg}` };
+  if (cryptoInventory && cryptoInventory[enc.alg] && cryptoInventory[enc.alg] !== "active") {
+    return { ok: false, reason: `enc-alg-not-active:${enc.alg}` };
+  }
+  if (typeof enc.epk !== "string" || !/^[0-9a-f]{64}$/i.test(enc.epk)) return { ok: false, reason: "bad-epk" };
+  if (typeof enc.iv !== "string" || !/^[0-9a-f]{24}$/i.test(enc.iv)) return { ok: false, reason: "bad-iv" };
+  if (typeof enc.ct !== "string" || !/^[0-9a-f]{32,}$/i.test(enc.ct)) return { ok: false, reason: "bad-ct" };
+
+  const d = envelope.delegation;
+  // (b-i) + (c) + (d): the delegation document itself — shape, both local-id
+  // bindings, time window, and the principal's signature over it.
+  const dv = verifyDelegationDoc(d);
+  if (!dv.ok) return reject(dv.reason);
+  // (b-ii) the persona this envelope acts as must be the delegation principal.
+  if (d.principal !== envelope.sender) return reject("sender-not-principal");
+  // (b-iii) the actual signer must be the named delegate, key and all.
+  if (sig.keyId !== d.delegate) return reject("signer-not-delegate");
+  if (sig.publicKey !== d.delegatePublicKey) return reject("signer-key-mismatch");
+  // (e) the delegation must cover this envelope kind.
+  //
+  // A capability name is checked FIRST and unconditionally — including under
+  // kinds:["*"] — because these names are not envelope kinds at all. Without
+  // this, a read-only kinds:["inbox"] poll token doubles as authority to send
+  // envelopes of kind "inbox" as the principal. See CAPABILITY_ONLY_KINDS.
+  if (CAPABILITY_ONLY_KINDS.has(envelope.kind)) return reject("kind-reserved-capability");
+  if (!delegationCoversKind(d, envelope.kind)) return reject("kind-not-covered");
+  // (a) the envelope signature under the delegate key, over the canonical
+  // body INCLUDING the delegation field (exactly what the delegate signed).
+  const { transportSignature: _sig, ...withoutSig } = envelope;
+  let canonical;
+  try { canonical = jcs(withoutSig); } catch (_e) { return { ok: false, reason: "bad-canonical" }; }
+  let okSig;
+  try {
+    okSig = Keychain.verifyDetached(sig.publicKey, Buffer.from(canonical, "utf-8"), Buffer.from(sig.signature, "hex"));
+  } catch (_e) {
+    return { ok: false, reason: "verify-threw" };
+  }
+  if (!okSig) return reject("bad-envelope-signature");
+  return { ok: true, delegated: true, actingFor: d.principal };
+}
+
+/**
+ * Decrypt an envelope's payload.  Only the recipient can do this.
+ * keychain must be the recipient's loaded keychain.
+ * Throws on wrong recipient, wrong key, tamper, or AAD mismatch.
+ */
+export function decrypt(keychain, envelope) {
+  const identity = keychain._identity;
+  if (!identity) throw new Error("decrypt: keychain not loaded");
+  if (envelope.recipient !== identity.uuaid) {
+    throw new Error(`decrypt: envelope addressed to ${envelope.recipient}, not us (${identity.uuaid})`);
+  }
+  const seed = keychainSeed(keychain);
+  return openPayload(seed, envelope.enc, { aad: envelope.id });
+}
+
+/** Extract the 32-byte Ed25519 seed from a loaded keychain. */
+export function keychainSeed(keychain) {
+  const der = keychain._identity.privateKey.export({ type: "pkcs8", format: "der" });
+  return Buffer.from(der.subarray(der.length - 32));
+}
+
+/**
+ * Envelope id: 16 random bytes hex + a small timestamp prefix for
+ * human-readable sort.  Not sensitive; not secret.  Used as GCM AAD.
+ */
+export function mkEnvelopeId() {
+  const now = Date.now().toString(36);
+  const rnd = randomBytes(8).toString("hex");
+  return `env-${now}-${rnd}`;
+}
+
+/**
+ * Content-hash of an envelope, computable by anyone.
+ */
+export function envelopeSha(envelope) {
+  return createHash("sha256").update(jcs(envelope)).digest("hex");
+}

package/src/vendor/pillar/net/refusals.mjs

@@ -0,0 +1,129 @@
+/**
+ * Refusals in agent language: every refusal is a stable `code` plus one
+ * imperative `fix` line, and the CLIs print exactly `<code>: <fix>`.
+ *
+ * The carrier's codes are the `reason` (refused send) or `error` (refused
+ * inbox read) values it has always sent (carrier-server.mjs, envelope.mjs,
+ * delegation.mjs). Those values and their status codes never change here;
+ * the carrier only ADDS a `fix` field, and a client talking to an older
+ * carrier looks the fix up in this same map. The blob broker sends its own
+ * `code` + `fix`, which is printed as received.
+ *
+ * CLOSED AND STATIC. Every fix this package produces is a value of
+ * REFUSAL_FIXES: a fixed string, never built from request data, a remote
+ * reason or an exception message. A parameterised reason
+ * (`delegation-invalid:<why>`, `bad-version <v>`, `alg-not-active:<alg>`)
+ * resolves by its family key, so the parameter never reaches the fix.
+ *
+ * Documented, with statuses, in HOSTING-LIMITS.md "Refusal codes".
+ */
+
+const RESEAL = "re-seal the envelope with seal() from @uuaid/pillar or @uuaid/pillar-client; this one does not verify";
+
+/** code -> one-line fix. Frozen: add, never rename, never interpolate. */
+export const REFUSAL_FIXES = Object.freeze({
+  // Carrier, POST /v1/envelopes
+  "rate-limited": "back off: budgets refill over a sliding 60 s, so retry after 5 s, doubling to 60 s",
+  "body-too-large": "send the payload as a blob (pillar-blob send); maxBodyBytes is your tier's inline limit",
+  "stale-envelope": "seal a new envelope and check your clock; createdAt must be within 24 h of carrier time",
+  "carrier-full": "use your other carriers and do not retry this one soon; its store is full",
+  "bad-recipient": "address the envelope to a full UUAID (uuaid:<namespace>:<type>:<id>)",
+  "bad-json": "POST the envelope as one JSON object",
+  "keyId-sender-mismatch": "sign with transportSignature.keyId equal to the sender UUAID, or send under a delegation",
+  "publicKey-sender-mismatch": "send from the UUAID your signing key derives, or attach the principal's delegation",
+  "bad-signature": "sign again with this identity's own key over the exact bytes; the signature does not verify",
+  "weak-publicKey": "use a real Ed25519 identity key; this key is a small-order or non-canonical point that can sign anything, so no signature under it counts",
+  "delegation-invalid": "mint a fresh delegation from the principal, then resend",
+  "envelope-id-conflict": "seal a new envelope with a fresh id; this carrier already holds a different envelope under this id",
+  // Carrier, envelope shape and crypto (envelope.mjs open()): one fix for all
+  "not-object": RESEAL,
+  "bad-version": RESEAL,
+  "missing-or-bad-alg": RESEAL,
+  "alg-not-active": RESEAL,
+  "bad-publicKey": RESEAL,
+  "bad-signature-encoding": RESEAL,
+  "missing-enc": RESEAL,
+  "enc-alg-not-supported": RESEAL,
+  "enc-alg-not-active": RESEAL,
+  "bad-epk": RESEAL,
+  "bad-iv": RESEAL,
+  "bad-ct": RESEAL,
+  "bad-canonical": RESEAL,
+  "verify-threw": RESEAL,
+  // Carrier, GET /v1/inbox/<uuaid>
+  "missing-auth-headers": "send x-pillar-pubkey, x-pillar-ts and x-pillar-sig",
+  "bad-pubkey": "send x-pillar-pubkey as the raw Ed25519 key in 64 hex characters",
+  "bad-sig-encoding": "send x-pillar-sig as 128 hex characters",
+  "clock-skew": "fix your clock (NTP) to within 5 min of the carrier; retrying does not help",
+  "uuaid-pubkey-mismatch": "read the inbox of the UUAID your key derives, or send that UUAID's delegation in x-pillar-delegation",
+  "delegation-unparseable": "send x-pillar-delegation as the JSON delegation document",
+  "delegation-too-large": "send a delegation document under 8,192 bytes",
+  "delegation-principal-mismatch": "use a delegation whose principal is the inbox UUAID",
+  "delegation-delegate-key-mismatch": "sign with the key the delegation names as delegate",
+  "delegation-inbox-denied": "ask the principal for a delegation that covers inbox (or *)",
+  "busy": "retry after at least 2 s with jitter, or poll with wait=0 for a while",
+  // Carrier, any route
+  "not-found": "use POST /v1/envelopes or GET /v1/inbox/<uuaid>",
+  "not-a-seed": "do not list this carrier as a seed; it runs without a seed identity",
+  "internal-error": "retry later; if it repeats, tell the carrier operator",
+  // Client side: no server gave a code
+  "carrier-unreachable": "check the carrier URLs and your network, then retry",
+  "carrier-bad-response": "retry, or use another carrier; the carrier or its proxy answered without a reason",
+  "over-tier-limit": "send the payload as a blob (pillar-blob send, or Pillar.sendBlob)",
+  "blob-key-unproven": "use a self-certifying agent UUAID derived from this key (pillar init), or get a registry badge that names this key",
+  "sender-key-not-active": "ask the sender to send from a self-certifying agent UUAID derived from its own key, or to get a registry badge naming its key",
+  "group-v2-use-v2-send": "send to this pillar-group/2 group with pillar group send <group>; v1 group sends (send-group, sendGroup) do not reach it",
+});
+
+/**
+ * The fix for a carrier reason, or null for a reason this map does not know.
+ * An exact key wins; otherwise the reason's family (the part before the
+ * first ":" or space) is looked up, so `delegation-invalid:expired` and
+ * `bad-version 2` resolve to their family's fix. The result is always a
+ * value of REFUSAL_FIXES or null; nothing from `reason` is copied into it.
+ */
+export function carrierFix(reason) {
+  if (typeof reason !== "string" || !reason) return null;
+  if (Object.hasOwn(REFUSAL_FIXES, reason)) return REFUSAL_FIXES[reason];
+  const family = reason.split(/[: ]/, 1)[0];
+  return family !== reason && Object.hasOwn(REFUSAL_FIXES, family) ? REFUSAL_FIXES[family] : null;
+}
+
+/**
+ * A carrier response body with its `fix` added. Pure addition: only a
+ * refusal (status >= 400) that names a `reason` or `error` and has no `fix`
+ * yet gains one; every other field, and every other body, is returned as is.
+ */
+export function withCarrierFix(status, body) {
+  if (!(status >= 400) || !body || typeof body !== "object" || Array.isArray(body) || body.fix !== undefined) return body;
+  const fix = carrierFix(typeof body.reason === "string" ? body.reason : body.error);
+  return fix ? { ...body, fix } : body;
+}
+
+/**
+ * Terminal safety only: a line break or control character a remote sent
+ * becomes a space, so the output stays one line and cannot drive the
+ * terminal. Every other character is printed as received.
+ */
+function oneLine(value) {
+  return String(value).replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").trim();
+}
+
+/**
+ * `<code>: <fix>` for an error that carries both (a carrier or broker
+ * refusal, or a client error that knows its next step), else null so the
+ * caller keeps its old output. A server's fix is printed as received.
+ */
+export function refusalLine(error) {
+  const code = typeof error?.code === "string" ? oneLine(error.code) : "";
+  const fix = typeof error?.fix === "string" ? oneLine(error.fix) : "";
+  return code && fix ? `${code}: ${fix}` : null;
+}
+
+/** `{ code, fix }` of an error, for a result row, omitting what is absent. */
+export function refusalFields(error) {
+  return {
+    ...(typeof error?.code === "string" && error.code ? { code: error.code } : {}),
+    ...(typeof error?.fix === "string" && error.fix ? { fix: error.fix } : {}),
+  };
+}

package/src/vendor/pillar/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 };
+}