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

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 };
+}

package/test/channels.test.mjs

@@ -0,0 +1,268 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  classifyThread,
+  assertChannelSendAdmission,
+  assertChannelReceiveAdmission,
+  assertForwardingPermission,
+  validateTenantBinding,
+  CANONICAL_CHANNEL_REGEX,
+  RESERVED_CHANNEL_PREFIX
+} from "../src/channels.mjs";
+
+test("Channel classifier: C2 Input / Mode Decision Table (two-pole)", () => {
+  const canonicalUris = [
+    "channel://commons/dm/agent-session-123",
+    "channel://zilligon/community/welcome",
+    "channel://local/topic/node-events",
+    "channel://commons/session/delib-456"
+  ];
+
+  // 1. Canonical structured channels succeed across all policy modes
+  for (const uri of canonicalUris) {
+    for (const channelsEnabled of [false, true, undefined]) {
+      const result = classifyThread(uri, { channelsEnabled });
+      assert.equal(result.ok, true, `Expected ${uri} to succeed with channelsEnabled=${channelsEnabled}`);
+      assert.equal(result.classification, "structured");
+      assert.equal(result.channelUri, uri);
+      assert.ok(result.parsed.provider);
+      assert.ok(result.parsed.channelType);
+      assert.ok(result.parsed.channelId);
+    }
+  }
+
+  // 2. Non-canonical channel-like spellings fail closed with INVALID_CHANNEL_URI
+  const nonCanonicalUris = [
+    "CHANNEL://commons/dm/agent-123", // Uppercase scheme (must NOT fall back to legacy bypass)
+    "channel:/commons/dm/123",        // Missing slash
+    "channel://commons",              // Missing segments
+    "channel://commons/dm",           // Only two segments
+    "channel://comm@ns/dm/123",       // Disallowed characters
+    "Channel://local/topic/test",     // Mixed case scheme
+    "CHANNEL://LOCAL/TOPIC/TEST"      // All uppercase
+  ];
+
+  for (const badUri of nonCanonicalUris) {
+    for (const channelsEnabled of [false, true, undefined]) {
+      const result = classifyThread(badUri, { channelsEnabled });
+      // Control pole: Must fail closed with INVALID_CHANNEL_URI
+      assert.equal(
+        result.ok,
+        false,
+        `Expected non-canonical ${badUri} to fail with channelsEnabled=${channelsEnabled}`
+      );
+      assert.equal(result.classification, "reserved-malformed");
+      assert.equal(result.error, "INVALID_CHANNEL_URI");
+
+      // Mutant pole check: verify that a naive startsWith("channel://") would have incorrectly bypassed
+      const naivePrefixMatches = badUri.startsWith("channel://");
+      const reservedPrefixMatches = RESERVED_CHANNEL_PREFIX.test(badUri);
+      assert.equal(
+        reservedPrefixMatches,
+        true,
+        `Reserved regex must catch channel-like spelling ${badUri}`
+      );
+    }
+  }
+
+  // 3. Ordinary legacy strings under default / disabled mode: ALLOWED
+  const legacyStrings = ["commons", "app-topic", "default-thread", "session-789"];
+  for (const legacy of legacyStrings) {
+    for (const channelsEnabled of [false, undefined]) {
+      const result = classifyThread(legacy, { channelsEnabled });
+      assert.equal(result.ok, true);
+      assert.equal(result.classification, "legacy-allowed");
+      assert.equal(result.thread, legacy);
+    }
+  }
+
+  // 4. Ordinary legacy strings under channelsEnabled === true: DENIED
+  for (const legacy of legacyStrings) {
+    const result = classifyThread(legacy, { channelsEnabled: true });
+    // Control pole: Denied with STRUCTURED_CHANNELS_REQUIRED
+    assert.equal(result.ok, false);
+    assert.equal(result.classification, "legacy-denied");
+    assert.equal(result.error, "STRUCTURED_CHANNELS_REQUIRED");
+  }
+
+  // 5. Invalid thread inputs
+  assert.equal(classifyThread("").error, "INVALID_THREAD_LENGTH");
+  assert.equal(classifyThread("a".repeat(121)).error, "INVALID_THREAD_LENGTH");
+  assert.equal(classifyThread(null).error, "INVALID_THREAD_LENGTH");
+  assert.equal(classifyThread(undefined).error, "INVALID_THREAD_LENGTH");
+});
+
+test("Bidirectional channel admission: outbound send assertions (two-pole)", () => {
+  const channelUri = "channel://commons/dm/thread-1";
+  const policy = {
+    channels: {
+      [channelUri]: {
+        visibility: "private",
+        members: ["agent-alice", "agent-bob"]
+      }
+    }
+  };
+
+  // Control pole: sender and all recipients admitted
+  assert.doesNotThrow(() => {
+    assertChannelSendAdmission(channelUri, "agent-alice", ["agent-bob"], policy);
+  });
+
+  // Mutant pole 1: unauthorized sender fails closed
+  assert.throws(
+    () => assertChannelSendAdmission(channelUri, "agent-eve", ["agent-bob"], policy),
+    (err) => err.code === "UNAUTHORIZED_CHANNEL_SENDER"
+  );
+
+  // Mutant pole 2: unauthorized recipient fails closed
+  assert.throws(
+    () => assertChannelSendAdmission(channelUri, "agent-alice", ["agent-eve"], policy),
+    (err) => err.code === "UNAUTHORIZED_CHANNEL_RECIPIENT"
+  );
+
+  // Mutant pole 3: unconfigured channel fails closed
+  assert.throws(
+    () => assertChannelSendAdmission("channel://commons/dm/unconfigured", "agent-alice", ["agent-bob"], policy),
+    (err) => err.code === "UNCONFIGURED_CHANNEL"
+  );
+});
+
+test("Bidirectional channel admission: inbound receive assertions (two-pole)", () => {
+  const channelUri = "channel://commons/dm/thread-1";
+  const policy = {
+    channels: {
+      [channelUri]: {
+        visibility: "private",
+        members: ["agent-alice", "agent-bob"]
+      }
+    }
+  };
+
+  // Control pole: decrypted sender and local receiver admitted
+  assert.doesNotThrow(() => {
+    assertChannelReceiveAdmission(channelUri, "agent-alice", "agent-bob", policy);
+  });
+
+  // Mutant pole 1: unauthorized sender fails closed
+  assert.throws(
+    () => assertChannelReceiveAdmission(channelUri, "agent-eve", "agent-bob", policy),
+    (err) => err.code === "UNAUTHORIZED_CHANNEL_SENDER"
+  );
+
+  // Mutant pole 2: unauthorized receiver fails closed
+  assert.throws(
+    () => assertChannelReceiveAdmission(channelUri, "agent-alice", "agent-eve", policy),
+    (err) => err.code === "UNAUTHORIZED_CHANNEL_RECEIVER"
+  );
+
+  // Mutant pole 3: unconfigured inbound channel fails closed with UNCONFIGURED_CHANNEL
+  assert.throws(
+    () => assertChannelReceiveAdmission("channel://commons/dm/unconfigured", "agent-alice", "agent-bob", policy),
+    (err) => err.code === "UNCONFIGURED_CHANNEL"
+  );
+});
+
+test("Cross-channel forwarding assertions (two-pole)", () => {
+  const sourceChannel = "channel://commons/dm/source-1";
+  const targetChannel = "channel://zilligon/community/announcements";
+
+  const policy = {
+    agents: {
+      "agent-forwarder": { capabilities: ["commons:message", "commons:forward"] },
+      "agent-regular": { capabilities: ["commons:message"] }
+    },
+    channels: {
+      [targetChannel]: {
+        visibility: "public",
+        allowForwarding: true
+      },
+      "channel://commons/dm/strict-target": {
+        visibility: "private",
+        allowForwarding: false
+      }
+    }
+  };
+
+  // Control pole: authorized forwarder and target permits forwarding
+  assert.doesNotThrow(() => {
+    assertForwardingPermission(sourceChannel, targetChannel, "agent-forwarder", policy);
+  });
+
+  // Mutant pole 1: sender lacks commons:forward capability
+  assert.throws(
+    () => assertForwardingPermission(sourceChannel, targetChannel, "agent-regular", policy),
+    (err) => err.code === "CROSS_CHANNEL_FORWARDING_DENIED"
+  );
+
+  // Mutant pole 2: target channel disallows forwarding
+  assert.throws(
+    () => assertForwardingPermission(sourceChannel, "channel://commons/dm/strict-target", "agent-forwarder", policy),
+    (err) => err.code === "CROSS_CHANNEL_FORWARDING_DENIED"
+  );
+});
+
+test("Tenant namespace binding assertions (two-pole)", () => {
+  const boundTenantProfile = {
+    id: "sha256-bound-profile-digest",
+    scope: "tenant"
+  };
+  const unboundTenantProfile = {
+    id: "sha256-unbound-tenant-profile",
+    scope: "tenant"
+  };
+  const unboundLocalProfile = {
+    id: "sha256-unbound-local-profile",
+    scope: "local"
+  };
+
+  const policy = {
+    tenantProfiles: {
+      [boundTenantProfile.id]: "tenant-acme"
+    },
+    agents: {
+      "agent-acme-1": { tenantId: "tenant-acme" },
+      "agent-acme-2": { tenantId: "tenant-acme" },
+      "agent-corp-x": { tenantId: "tenant-corp" }
+    }
+  };
+
+  // Control pole 1: matching tenant passes
+  assert.doesNotThrow(() => {
+    validateTenantBinding("agent-acme-1", "agent-acme-2", boundTenantProfile, policy);
+  });
+
+  // Mutant pole 1: sender tenant mismatch fails closed
+  assert.throws(
+    () => validateTenantBinding("agent-corp-x", "agent-acme-2", boundTenantProfile, policy),
+    (err) => err.code === "TENANT_NAMESPACE_MISMATCH"
+  );
+
+  // Mutant pole 2: recipient tenant mismatch fails closed
+  assert.throws(
+    () => validateTenantBinding("agent-acme-1", "agent-corp-x", boundTenantProfile, policy),
+    (err) => err.code === "TENANT_NAMESPACE_MISMATCH"
+  );
+
+  // Control pole 2: unbound tenant profile MUST fail closed with UNBOUND_PROFILE_TENANT (R4)
+  assert.throws(
+    () => validateTenantBinding("agent-acme-1", "agent-acme-2", unboundTenantProfile, policy),
+    (err) => err.code === "UNBOUND_PROFILE_TENANT"
+  );
+
+  // Control pole 3: unbound local profile passes unconstrained without tenant binding requirement
+  assert.doesNotThrow(() => {
+    validateTenantBinding("agent-acme-1", "agent-corp-x", unboundLocalProfile, policy);
+  });
+
+  // Mutant pole: unbound bare digest string fails closed with UNBOUND_PROFILE_TENANT (R4)
+  assert.throws(
+    () => validateTenantBinding("agent-acme-1", "agent-corp-x", "sha256-unbound-digest", policy),
+    (err) => err.code === "UNBOUND_PROFILE_TENANT"
+  );
+
+  // Mutant pole: unbound scope-less ProfileRef fails closed with UNBOUND_PROFILE_TENANT (R4)
+  assert.throws(
+    () => validateTenantBinding("agent-acme-1", "agent-corp-x", { id: "profile-no-scope" }, policy),
+    (err) => err.code === "UNBOUND_PROFILE_TENANT"
+  );
+});

package/test/cohort.test.mjs

@@ -0,0 +1,36 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { initializeCohort, cohortStatus, FOUNDING_ROSTER } from "../src/cohort.mjs";
+
+test("Seven nodes persist distinct identity and scoped policy without remote enrollment",()=>{
+  const root=mkdtempSync(join(tmpdir(),"commons-cohort-")),home=join(root,"nodes");
+  try{
+    const manifest=initializeCohort({home,target:"zilligon.com"});
+    assert.equal(manifest.members.length,7);
+    assert.equal(new Set(manifest.members.map(m=>m.uuaid)).size,7);
+    assert.equal(manifest.registration,"not-performed");
+    assert.equal(manifest.certified,false);
+    const next=cohortStatus(home);
+    assert.deepEqual(next.members.map(m=>m.uuaid),manifest.members.map(m=>m.uuaid));
+    assert(next.members.every(m=>m.status.auditVerified));
+    const config=JSON.parse(readFileSync(join(home,"security","config.json"),"utf8"));
+    assert.equal(Object.keys(config.policy.agents).length,7);
+    const security=manifest.members.find(m=>m.id==="security");
+    assert(!config.policy.agents[security.uuaid].capabilities.includes("commons:evolve"));
+    assert(Object.values(config.policy.agents).every(a=>!a.capabilities.includes("commons:recover")));
+    assert.throws(()=>initializeCohort({home}),/not overwritten/);
+  }finally{rmSync(root,{recursive:true,force:true})}
+});
+test("Cohort manifest cannot redirect identity loading to arbitrary paths",()=>{
+  const root=mkdtempSync(join(tmpdir(),"commons-cohort-")),home=join(root,"nodes");
+  try{
+    const m=initializeCohort({home});
+    m.members[0].home=root;
+    writeFileSync(join(home,"cohort.json"),JSON.stringify(m));
+    assert.throws(()=>cohortStatus(home),/Unsafe/);
+    assert.equal(FOUNDING_ROSTER.length,7);
+  }finally{rmSync(root,{recursive:true,force:true})}
+});