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

package/profiles/agentnet.chat.json

@@ -0,0 +1,11 @@
+{
+  "namespace":"tenant/agentnet.chat",
+  "name":"AgentNet private conversations",
+  "scope":"tenant",
+  "quorum":2,
+  "fixtures":[
+    "Negotiate the communication profile before initiating a private agent conversation.",
+    "A private agent conversation requires the communication profile and verified agent identity.",
+    "Publish a signed contribution only after consent to share local benchmark fixtures."
+  ]
+}

package/profiles/local.json

@@ -0,0 +1,11 @@
+{
+  "namespace":"local/fleet",
+  "name":"Local fleet utility",
+  "scope":"local",
+  "quorum":2,
+  "fixtures":[
+    "Run the local validation suite before accepting a communication profile.",
+    "A communication profile must pass the local validation suite before adoption.",
+    "The local validation suite checks every communication profile without changing identity policy."
+  ]
+}

package/profiles/zilligon.com.json

@@ -0,0 +1,11 @@
+{
+  "namespace":"tenant/zilligon.com",
+  "name":"Zilligon fleet communications",
+  "scope":"tenant",
+  "quorum":2,
+  "fixtures":[
+    "Route the build task to the code forge agent and require a signed delivery receipt.",
+    "Require a signed delivery receipt before marking the build task complete.",
+    "The code forge agent returns verifiable provenance with a signed delivery receipt."
+  ]
+}

package/profiles/zilligons.com.json

@@ -0,0 +1,11 @@
+{
+  "namespace":"tenant/zilligons.com",
+  "name":"Zilligons fleet communications",
+  "scope":"tenant",
+  "quorum":2,
+  "fixtures":[
+    "Route the build task to the code forge agent and require a signed delivery receipt.",
+    "Require a signed delivery receipt before marking the build task complete.",
+    "The code forge agent returns verifiable provenance with a signed delivery receipt."
+  ]
+}

package/src/carrier.mjs

@@ -0,0 +1,84 @@
+import { createServer } from "node:http";
+import { open, envelopeSha, Keychain, jcs } from "./pillar.mjs";
+import { CommonsStore } from "./store.mjs";
+import { RegistryTrust } from "./trust.mjs";
+
+export class CommonsCarrier {
+  constructor({store=new CommonsStore(),trust=new RegistryTrust(),keychain=null,publicUrl=null,onEnvelope=null}={}){
+    this.store=store;this.trust=trust;this.keychain=keychain;this.publicUrl=publicUrl;this.onEnvelope=onEnvelope;this.server=null;this.startedAt=Date.now();this.rates=new Map();
+    this.waiters=new Map();this.waitCount=0;
+  }
+  async listen(port=0,host="127.0.0.1"){
+    if(!["127.0.0.1","::1","localhost"].includes(host)&&(!this.publicUrl?.startsWith("https://")||this.trust.policy.mode!=="global"))throw new Error("Public bind requires global fail-closed policy and an HTTPS reverse-proxy URL");
+    if(!["127.0.0.1","::1","localhost"].includes(host)){
+      if(!this.keychain?._identity)throw new Error("Public carrier requires its own admitted agent identity");
+      await this.trust.authorize(this.keychain._identity.uuaid,this.keychain._identity.publicKeyHex,"commons:relay");
+    }
+    if(!this.store.verify())throw new Error("Carrier audit integrity failure");
+    this.server=createServer((req,res)=>void this.handle(req,res));
+    this.server.headersTimeout=15000;this.server.requestTimeout=15000;
+    await new Promise((resolve,reject)=>{this.server.once("error",reject);this.server.listen(port,host,resolve)});
+    return this.server.address();
+  }
+  json(res,status,body){res.writeHead(status,{"content-type":"application/json","cache-control":"no-store","x-content-type-options":"nosniff"});res.end(JSON.stringify(body))}
+  rate(ip){
+    const now=Date.now();if(this.rates.size>1000)this.rates.clear();
+    const bucket=this.rates.get(ip)??{start:now,count:0};if(now-bucket.start>60000){bucket.start=now;bucket.count=0}
+    bucket.count++;this.rates.set(ip,bucket);return bucket.count<=120;
+  }
+  async read(req){let size=0;const chunks=[];for await(const chunk of req){size+=chunk.length;if(size>512000)throw new Error("Payload exceeds bounded carrier limit");chunks.push(chunk)}return JSON.parse(Buffer.concat(chunks).toString())}
+  async waitFor(recipient,ms,res){
+    if(this.waitCount>=32)throw new Error("Long-poll concurrency budget exhausted");
+    this.waitCount++;
+    await new Promise(resolve=>{
+      const set=this.waiters.get(recipient)??new Set();this.waiters.set(recipient,set);
+      const done=()=>{clearTimeout(timer);set.delete(done);if(!set.size)this.waiters.delete(recipient);this.waitCount--;res.off("close",done);resolve()};
+      const timer=setTimeout(done,ms);set.add(done);res.once("close",done);
+    });
+  }
+  async handle(req,res){
+    try {
+      if(!this.rate(req.socket.remoteAddress))return this.json(res,429,{error:"rate-limited"});
+      const url=new URL(req.url,"http://localhost");
+      if(req.method==="GET"&&url.pathname==="/v1/health")return this.json(res,200,{ok:true,implementation:"Agent Commons",protocol:"uuaid-pillar-envelope/2",uptime:Math.round((Date.now()-this.startedAt)/1000),auditVerified:this.store.verify()});
+      if(req.method==="GET"&&url.pathname==="/.well-known/agent-commons")return this.json(res,200,{v:"agent-commons/1",role:this.onEnvelope?"host-client-and-carrier":"carrier",uuaid:this.keychain?._identity.uuaid??null,publicKey:this.keychain?._identity.publicKeyHex??null,transports:["pillar-carrier/v1"],mode:this.trust.policy.mode??"local",admission:"policy-gated-agent-identities",globalStandardization:"requires-IAASO-publication"});
+      if(req.method==="GET"&&url.pathname==="/v1/seed-info"){
+        if(!this.keychain||!this.publicUrl)return this.json(res,404,{error:"private-carrier"});
+        const doc={v:1,url:this.publicUrl,uuaid:this.keychain._identity.uuaid,publicKey:this.keychain._identity.publicKeyHex,startedAt:new Date(this.startedAt).toISOString(),firstSeen:new Date(this.startedAt).toISOString(),stats:{relayed:this.store.db.prepare("SELECT COUNT(*) AS n FROM envelopes").get().n,served:0,stored:this.store.db.prepare("SELECT COUNT(*) AS n FROM envelopes").get().n},now:new Date().toISOString()};
+        return this.json(res,200,{...doc,sig:this.keychain.sign(Buffer.from(jcs(doc))).toString("hex")});
+      }
+      if(req.method==="POST"&&url.pathname==="/v1/envelopes"){
+        const envelope=await this.read(req),valid=open(envelope);
+        if(!valid.ok)return this.json(res,400,{accepted:false,reason:valid.reason});
+        if(envelope.delegation!==undefined)return this.json(res,403,{accepted:false,reason:"delegated-admission-not-configured"});
+        const timestamp=Date.parse(envelope.createdAt);
+        if(!Number.isFinite(timestamp)||Math.abs(Date.now()-timestamp)>86400000)return this.json(res,400,{accepted:false,reason:"envelope-stale"});
+        await this.trust.authorize(envelope.sender,envelope.transportSignature.publicKey,"commons:relay");
+        if(this.onEnvelope&&envelope.recipient===this.keychain?._identity.uuaid)await this.onEnvelope(envelope);
+        const receipt=this.store.transaction(()=>{const receipt=this.store.retain(envelope,envelopeSha(envelope));if(!receipt.duplicate)this.store.append(`carrier-${envelope.id}`,{kind:"carrier-recorded",envelopeId:envelope.id,sender:envelope.sender,recipient:envelope.recipient,sha:receipt.sha});return receipt});
+        for(const done of [...(this.waiters.get(envelope.recipient)??[])])done();
+        return this.json(res,202,{accepted:true,...receipt,proof:"carrier-recorded-not-recipient-read"});
+      }
+      if(req.method==="GET"&&url.pathname.startsWith("/v1/inbox/")){
+        const uuaid=decodeURIComponent(url.pathname.slice("/v1/inbox/".length)),since=Number(url.searchParams.get("since")??0);
+        const pub=req.headers["x-pillar-pubkey"],ts=req.headers["x-pillar-ts"],sig=req.headers["x-pillar-sig"];
+        if(!Number.isSafeInteger(since)||since<0||typeof pub!=="string"||typeof ts!=="string"||typeof sig!=="string"||!/^[0-9a-f]{128}$/.test(sig)||Math.abs(Date.now()-Number(ts))>300000||!Number.isFinite(Number(ts)))return this.json(res,401,{error:"invalid-inbox-auth"});
+        const signed=Buffer.from(`GET /v1/inbox/${uuaid}?since=${since}\n${ts}`);
+        if(!Keychain.verifyDetached(pub,signed,Buffer.from(sig,"hex")))return this.json(res,401,{error:"bad-inbox-signature"});
+        await this.trust.authorize(uuaid,pub,"commons:message");
+        const wait=Number(url.searchParams.get("wait")??0);
+        if(!Number.isFinite(wait)||wait<0)return this.json(res,400,{error:"invalid-wait"});
+        if(!this.store.inbox(uuaid,since).length&&wait>0){
+          await this.waitFor(uuaid,Math.min(wait,25)*1000,res);
+          if(res.destroyed)return;
+          // A long poll may outlive its admission: re-check before handing over mail, so a key
+          // blocked (under any spelling) or removed during the wait gets the fresh-request refusal.
+          await this.trust.authorize(uuaid,pub,"commons:message");
+        }
+        return this.json(res,200,{envelopes:this.store.inbox(uuaid,since),now:Date.now()});
+      }
+      return this.json(res,404,{error:"not-found"});
+    } catch(error){return this.json(res,error.code?403:400,{accepted:false,reason:error.code??"invalid-request",message:error.message.slice(0,200)})}
+  }
+  async close(){for(const set of [...this.waiters.values()])for(const done of [...set])done();if(this.server){await new Promise(resolve=>this.server.close(resolve));this.server=null}}
+}

package/src/channels.d.mts

@@ -0,0 +1,75 @@
+export const CANONICAL_CHANNEL_REGEX: RegExp;
+export const RESERVED_CHANNEL_PREFIX: RegExp;
+
+export type ChannelClassification =
+  | "structured"
+  | "reserved-malformed"
+  | "legacy-allowed"
+  | "legacy-denied"
+  | "invalid";
+
+export interface ParsedChannelUri {
+  readonly provider: string;
+  readonly channelType: string;
+  readonly channelId: string;
+}
+
+export interface ChannelClassificationResult {
+  readonly ok: boolean;
+  readonly classification: ChannelClassification;
+  readonly channelUri?: string;
+  readonly thread?: string;
+  readonly parsed?: ParsedChannelUri;
+  readonly error?: string;
+}
+
+export interface ChannelDefinition {
+  readonly visibility?: "public" | "private" | "invite_only";
+  readonly members?: readonly string[];
+  readonly allowForwarding?: boolean;
+  readonly metadata?: Record<string, any>;
+}
+
+export interface ChannelPolicy {
+  readonly channelsEnabled?: boolean;
+  readonly channels?: Record<string, ChannelDefinition>;
+  readonly tenantProfiles?: Record<string, string>;
+  readonly agents?: Record<string, { tenantId?: string; capabilities?: string[]; [key: string]: any }>;
+  [key: string]: any;
+}
+
+export function classifyThread(thread: unknown, policy?: ChannelPolicy): ChannelClassificationResult;
+
+export function assertChannelSendAdmission(
+  channelUri: string,
+  sender: string,
+  recipients: string[],
+  policy?: ChannelPolicy
+): void;
+
+export function assertChannelReceiveAdmission(
+  channelUri: string,
+  sender: string,
+  receiver: string,
+  policy?: ChannelPolicy
+): void;
+
+export function assertForwardingPermission(
+  sourceChannelUri: string,
+  targetChannelUri: string,
+  sender: string,
+  policy?: ChannelPolicy
+): void;
+
+export interface ProfileRef {
+  readonly id: string;
+  readonly scope: "local" | "tenant" | "global" | string;
+  [key: string]: any;
+}
+
+export function validateTenantBinding(
+  sender: string,
+  recipient: string,
+  profile: string | ProfileRef,
+  policy?: ChannelPolicy
+): void;

package/src/channels.mjs

@@ -0,0 +1,158 @@
+export const CANONICAL_CHANNEL_REGEX = /^channel:\/\/[a-z0-9._-]+\/[a-z0-9._-]+\/[a-zA-Z0-9._-]+$/;
+export const RESERVED_CHANNEL_PREFIX = /^channel:/i;
+
+/**
+ * Classifies an inbound or outbound thread parameter.
+ * Strictly prioritizes reserved-channel classification over legacy thread fallback.
+ */
+export function classifyThread(thread, policy) {
+  if (typeof thread !== "string" || thread.length === 0 || thread.length > 120) {
+    return {
+      ok: false,
+      classification: "invalid",
+      error: "INVALID_THREAD_LENGTH"
+    };
+  }
+
+  // First precedence: Reserved channel classification
+  if (RESERVED_CHANNEL_PREFIX.test(thread)) {
+    if (!CANONICAL_CHANNEL_REGEX.test(thread)) {
+      return {
+        ok: false,
+        classification: "reserved-malformed",
+        error: "INVALID_CHANNEL_URI"
+      };
+    }
+    const [provider, channelType, channelId] = thread.slice("channel://".length).split("/");
+    return {
+      ok: true,
+      classification: "structured",
+      channelUri: thread,
+      parsed: { provider, channelType, channelId }
+    };
+  }
+
+  // Second precedence: Ordinary legacy thread handling
+  if (policy?.channelsEnabled === true) {
+    return {
+      ok: false,
+      classification: "legacy-denied",
+      error: "STRUCTURED_CHANNELS_REQUIRED"
+    };
+  }
+
+  return {
+    ok: true,
+    classification: "legacy-allowed",
+    thread
+  };
+}
+
+/**
+ * Asserts bidirectional admission for outbound channel messages.
+ * Both sender and every intended recipient must be members of the structured channel.
+ */
+export function assertChannelSendAdmission(channelUri, sender, recipients, policy) {
+  const channel = policy?.channels?.[channelUri];
+  if (!channel) {
+    const err = new Error(`Channel is unconfigured: ${channelUri}`);
+    err.code = "UNCONFIGURED_CHANNEL";
+    throw err;
+  }
+
+  const members = new Set(channel.members ?? []);
+  if (!members.has(sender)) {
+    const err = new Error(`Sender ${sender} is unauthorized for channel ${channelUri}`);
+    err.code = "UNAUTHORIZED_CHANNEL_SENDER";
+    throw err;
+  }
+
+  for (const recipient of recipients) {
+    if (!members.has(recipient)) {
+      const err = new Error(`Recipient ${recipient} is unauthorized for channel ${channelUri}`);
+      err.code = "UNAUTHORIZED_CHANNEL_RECIPIENT";
+      throw err;
+    }
+  }
+}
+
+/**
+ * Asserts bidirectional admission for inbound channel messages upon decryption.
+ * Both the decrypted sender and the local receiver must be members of the structured channel.
+ */
+export function assertChannelReceiveAdmission(channelUri, sender, receiver, policy) {
+  const channel = policy?.channels?.[channelUri];
+  if (!channel) {
+    const err = new Error(`Channel is unconfigured: ${channelUri}`);
+    err.code = "UNCONFIGURED_CHANNEL";
+    throw err;
+  }
+
+  const members = new Set(channel.members ?? []);
+  if (!members.has(sender)) {
+    const err = new Error(`Sender ${sender} is unauthorized for channel ${channelUri}`);
+    err.code = "UNAUTHORIZED_CHANNEL_SENDER";
+    throw err;
+  }
+
+  if (!members.has(receiver)) {
+    const err = new Error(`Receiver ${receiver} is unauthorized for channel ${channelUri}`);
+    err.code = "UNAUTHORIZED_CHANNEL_RECEIVER";
+    throw err;
+  }
+}
+
+/**
+ * Asserts explicit permission for cross-channel message forwarding.
+ * Sender requires 'commons:forward' and target channel must allow forwarding.
+ */
+export function assertForwardingPermission(sourceChannelUri, targetChannelUri, sender, policy) {
+  const senderCaps = policy?.agents?.[sender]?.capabilities ?? [];
+  if (!senderCaps.includes("commons:forward")) {
+    const err = new Error(`Sender ${sender} lacks commons:forward capability`);
+    err.code = "CROSS_CHANNEL_FORWARDING_DENIED";
+    throw err;
+  }
+
+  const targetChannel = policy?.channels?.[targetChannelUri];
+  if (targetChannel?.allowForwarding !== true) {
+    const err = new Error(`Target channel ${targetChannelUri} does not permit forwarded messages`);
+    err.code = "CROSS_CHANNEL_FORWARDING_DENIED";
+    throw err;
+  }
+}
+
+/**
+ * Validates tenant namespace binding between sender, recipient, and profile.
+ * Unbound tenant profiles fail closed with UNBOUND_PROFILE_TENANT.
+ * Unbound local profiles are permitted without error.
+ * Mismatches fail closed with TENANT_NAMESPACE_MISMATCH.
+ */
+export function validateTenantBinding(sender, recipient, profileOrRef, policy) {
+  const profileId = typeof profileOrRef === "string" ? profileOrRef : profileOrRef?.id;
+  const scope = typeof profileOrRef === "object" && profileOrRef !== null ? profileOrRef.scope : undefined;
+
+  const boundTenant = policy?.tenantProfiles?.[profileId];
+  if (!boundTenant) {
+    if (scope !== "local") {
+      const err = new Error(`Unbound tenant profile: ${profileId}`);
+      err.code = "UNBOUND_PROFILE_TENANT";
+      throw err;
+    }
+    return;
+  }
+
+  const senderTenant = policy?.agents?.[sender]?.tenantId;
+  if (senderTenant !== boundTenant) {
+    const err = new Error(`Sender tenant mismatch: expected ${boundTenant}, got ${senderTenant}`);
+    err.code = "TENANT_NAMESPACE_MISMATCH";
+    throw err;
+  }
+
+  const recipientTenant = policy?.agents?.[recipient]?.tenantId;
+  if (recipientTenant !== boundTenant) {
+    const err = new Error(`Recipient tenant mismatch: expected ${boundTenant}, got ${recipientTenant}`);
+    err.code = "TENANT_NAMESPACE_MISMATCH";
+    throw err;
+  }
+}

package/src/cohort.mjs

@@ -0,0 +1,61 @@
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { initialize, loadRuntime, saveConfig } from "./config.mjs";
+
+export const FOUNDING_ROSTER = Object.freeze([
+  {id:"continuity",name:"Mneme",model:"claude_fable_5_1",label:"Claude Fable 5.1",provider:"Anthropic",role:"Continuity architect"},
+  {id:"governance",name:"Sol",model:"gpt_6_1_sol",label:"GPT 6.1 Sol",provider:"OpenAI",role:"Peer oversight engineer"},
+  {id:"collaboration",name:"Nexus",model:"claude_opus_5_5",label:"Claude Opus 5.5",provider:"Anthropic",role:"Collaboration runtime engineer"},
+  {id:"release",name:"Forge",model:"grok_4_7",label:"Grok 4.7",provider:"xAI",role:"Release and supply-chain engineer"},
+  {id:"integration",name:"Prism",model:"gemini_3_8_flash",label:"Gemini 3.8 Flash",provider:"Google",role:"Trust integration researcher"},
+  {id:"sustainability",name:"Terra",model:"gpt_5_6_terra",label:"GPT 5.6 Terra",provider:"OpenAI",role:"Sustainability and SOP steward"},
+  {id:"security",name:"Aegis",model:"claude_sonnet_5_5",label:"Claude Sonnet 5.5",provider:"Anthropic",role:"Independent safety reviewer"},
+].map(Object.freeze));
+
+/** Generate seven private local identities. No remote registry or model call. */
+export function initializeCohort({home,target="local",controllerId="local-operator"}={}){
+  if(typeof home!=="string"||!home)throw new Error("An explicit private cohort --home directory is required");
+  if(typeof controllerId!=="string"||controllerId.length<1||controllerId.length>120)throw new Error("Explicit controller identifier required");
+  home=resolve(home);
+  // Refuse partially populated destinations rather than silently clobber identities.
+  if(existsSync(join(home,"cohort.json"))||FOUNDING_ROSTER.some(a=>existsSync(join(home,a.id))))
+    throw new Error("Cohort destination already contains a manifest or member; identities were not overwritten");
+  mkdirSync(home,{recursive:true,mode:0o700});
+  const members=FOUNDING_ROSTER.map(member=>{
+    const nodeHome=join(home,member.id);
+    const initialized=initialize({home:nodeHome,target,name:member.name});
+    return {...member,home:nodeHome,uuaid:initialized.identity.uuaid,publicKey:initialized.identity.publicKeyHex,controllerId};
+  });
+  for(const member of members){
+    const node=loadRuntime(member.home);
+    node.config.policy.agents=Object.fromEntries(members.map(peer=>[peer.uuaid,{
+      kind:"agent",publicKey:peer.publicKey,controllerId,affiliations:[],
+      capabilities:peer.id==="security"?["commons:message","commons:relay"]:["commons:message","commons:relay","commons:evolve","commons:contribute"],
+    }]));
+    // Recovery is an explicit operator grant, not a default peer privilege.
+    saveConfig(member.home,node.config);node.store.close();
+  }
+  const manifest={version:1,product:"Agent Commons",target:target==="zilligons.com"?"zilligon.com":target,
+    members,registration:"not-performed",remoteMemory:"not-configured",certified:false,
+    ownerIndependence:"Single controller: seven keys do not establish independent owners",
+    modelAccess:"Configure an adapter; model selection alone is not provider access",
+    invitation:{autoJoin:false,autoBroadcast:false,consent:"explicit scoped admission required"}};
+  writeFileSync(join(home,"cohort.json"),JSON.stringify(manifest,null,2),{mode:0o600});
+  return manifest;
+}
+
+export function cohortStatus(home){
+  if(typeof home!=="string"||!home)throw new Error("Explicit cohort home required");
+  home=resolve(home);
+  const manifest=JSON.parse(readFileSync(join(home,"cohort.json"),"utf8"));
+  if(manifest.version!==1||manifest.members?.length!==7)throw new Error("Invalid cohort manifest");
+  const expected=new Set(FOUNDING_ROSTER.map(a=>a.id));
+  return {...manifest,members:manifest.members.map(member=>{
+    if(!expected.delete(member.id)||member.home!==join(home,member.id))throw new Error("Unsafe or duplicate cohort member path");
+    const node=loadRuntime(member.home);
+    try{
+      if(member.uuaid!==node.runtime.uuaid||member.publicKey!==node.runtime.publicKey)throw new Error("Cohort identity mismatch");
+      return {...member,status:node.runtime.status()};
+    }finally{node.store.close()}
+  })};
+}