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

package/src/transport.mjs

@@ -0,0 +1,267 @@
+import { randomUUID } from "node:crypto";
+import { CarrierClient, envelopeSha } from "./pillar.mjs";
+import { isOffline, isLoopbackUrl } from "./offline.mjs";
+
+let anonymousInstanceCounter = 0;
+const activeLoopbackInstances = new Set();
+
+function refusedCarrier(urls, env) {
+  if (!isOffline(env)) return null;
+  for (const url of urls ?? []) {
+    if (!isLoopbackUrl(url)) return url;
+  }
+  return null;
+}
+
+function offlineError(url) {
+  const error = new Error(`offline: refused outbound carrier call to ${url}`);
+  error.code = "offline";
+  error.carrier = url;
+  return error;
+}
+
+/**
+ * In-memory loopback transport for local unit testing and development.
+ * Never performs network operations; assigns stable instance-qualified source IDs.
+ * Enforces per-source FIFO execution for live subscriptions.
+ */
+export class MemoryLoopbackTransport {
+  #inboxes = new Map();
+  #subscribers = new Map();
+  #seq = 0;
+  #closed = false;
+
+  constructor(options = {}) {
+    if (options.instanceId !== undefined) {
+      if (typeof options.instanceId !== "string" || options.instanceId.trim() === "") {
+        throw new TypeError("instanceId must be a non-empty string when specified");
+      }
+      if (activeLoopbackInstances.has(options.instanceId)) {
+        const err = new Error(`Duplicate MemoryLoopbackTransport instance qualifier: ${options.instanceId}`);
+        err.code = "DUPLICATE_TRANSPORT_INSTANCE";
+        throw err;
+      }
+      this.instanceId = options.instanceId;
+    } else {
+      anonymousInstanceCounter += 1;
+      this.instanceId = `auto-${anonymousInstanceCounter}-${randomUUID().slice(0, 8)}`;
+    }
+
+    activeLoopbackInstances.add(this.instanceId);
+    this.sourceId = `memory://loopback/${this.instanceId}`;
+
+    this.capabilities = Object.freeze({
+      name: "memory",
+      canPush: true,
+      canPoll: true,
+      supportsStreaming: true,
+      maxMessageBytes: 64000,
+      loopbackSafe: true,
+      ...(options.capabilities ?? {})
+    });
+
+    this.#inboxes.set(this.sourceId, []);
+    this.#subscribers.set(this.sourceId, new Set());
+  }
+
+  sources() {
+    return [this.sourceId];
+  }
+
+  async deliver(envelope, options = {}) {
+    if (this.#closed) {
+      const err = new Error("Transport is closed");
+      err.code = "TRANSPORT_CLOSED";
+      throw err;
+    }
+    if (!envelope || typeof envelope !== "object" || !envelope.id) {
+      const err = new Error("Invalid envelope: missing envelope id");
+      err.code = "INVALID_ENVELOPE";
+      throw err;
+    }
+
+    this.#seq += 1;
+    const seq = this.#seq;
+    const sha = envelopeSha(envelope);
+    const item = { seq, envelope: structuredClone(envelope) };
+
+    const queue = this.#inboxes.get(this.sourceId);
+    queue.push(item);
+
+    const subs = this.#subscribers.get(this.sourceId);
+    if (subs && subs.size > 0) {
+      const event = { sourceId: this.sourceId, seq, envelope: structuredClone(envelope) };
+      for (const subRecord of subs) {
+        // Enqueue onto subscriber's promise tail to guarantee per-subscriber FIFO execution
+        subRecord.tail = subRecord.tail
+          .then(async () => {
+            await subRecord.callback(event);
+          })
+          .catch(() => {});
+      }
+    }
+
+    return {
+      accepted: true,
+      carrier: this.sourceId,
+      seq,
+      sha,
+      duplicate: false,
+      all: []
+    };
+  }
+
+  async fetchInbox(sourceId, options = {}) {
+    if (this.#closed) {
+      const err = new Error("Transport is closed");
+      err.code = "TRANSPORT_CLOSED";
+      throw err;
+    }
+    if (sourceId !== this.sourceId) {
+      const err = new Error(`Unknown source ID: ${sourceId}`);
+      err.code = "UNKNOWN_SOURCE_ID";
+      throw err;
+    }
+
+    const since = options.since ?? 0;
+    const queue = this.#inboxes.get(this.sourceId) ?? [];
+    const matching = queue.filter(item => item.seq > since);
+
+    return {
+      sourceId,
+      envelopes: matching.map(item => ({
+        sourceId,
+        seq: item.seq,
+        envelope: structuredClone(item.envelope)
+      })),
+      now: Date.now()
+    };
+  }
+
+  subscribe(sourceId, onEnvelope) {
+    if (this.#closed) {
+      const err = new Error("Transport is closed");
+      err.code = "TRANSPORT_CLOSED";
+      throw err;
+    }
+    if (sourceId !== this.sourceId) {
+      const err = new Error(`Unknown source ID: ${sourceId}`);
+      err.code = "UNKNOWN_SOURCE_ID";
+      throw err;
+    }
+    if (typeof onEnvelope !== "function") {
+      throw new TypeError("onEnvelope callback must be a function");
+    }
+
+    const subRecord = {
+      callback: onEnvelope,
+      tail: Promise.resolve()
+    };
+
+    const subs = this.#subscribers.get(this.sourceId);
+    subs.add(subRecord);
+
+    return () => {
+      subs.delete(subRecord);
+    };
+  }
+
+  async close() {
+    this.#closed = true;
+    activeLoopbackInstances.delete(this.instanceId);
+    for (const subs of this.#subscribers.values()) {
+      subs.clear();
+    }
+    this.#subscribers.clear();
+    for (const queue of this.#inboxes.values()) {
+      queue.length = 0;
+    }
+    this.#inboxes.clear();
+  }
+}
+
+/**
+ * Adapter wrapping the package-owned guarded CarrierClient to conform to MessageTransport.
+ * Enforces offline refusal before ANY delivery or fetch, including for injected clients.
+ * Normalizes delivery receipts to include accepted: true and annotates inbox items with sourceId.
+ */
+export class PillarCarrierTransport {
+  constructor(options = {}) {
+    this._offlineEnv = options.env ?? options.client?._offlineEnv ?? process.env;
+    this.client = options.client ?? new CarrierClient({
+      keychain: options.keychain,
+      carriers: options.carriers,
+      env: this._offlineEnv
+    });
+    this.capabilities = Object.freeze({
+      name: "pillar",
+      canPush: false,
+      canPoll: true,
+      supportsStreaming: false,
+      maxMessageBytes: 512000,
+      loopbackSafe: false,
+      ...(options.capabilities ?? {})
+    });
+  }
+
+  sources() {
+    return this.client.carriers ?? [];
+  }
+
+  async deliver(envelope, options = {}) {
+    // Enforce offline refusal before invoking any injected or vendored client
+    if (isOffline(this._offlineEnv)) {
+      const declared = this.sources();
+      if (declared.length === 0) {
+        throw offlineError("unspecified");
+      }
+      const blocked = refusedCarrier(declared, this._offlineEnv)
+        ?? (envelope?.carrier ? refusedCarrier([envelope.carrier], this._offlineEnv) : null);
+      if (blocked) throw offlineError(blocked);
+    }
+
+    const res = await this.client.deliver(envelope, options);
+    const targetSources = this.sources().length ? this.sources() : (envelope?.carrier ? [envelope.carrier] : []);
+    return {
+      accepted: true,
+      carrier: res.carrier ?? targetSources[0] ?? "unknown",
+      seq: res.seq,
+      sha: res.sha ?? envelopeSha(envelope),
+      duplicate: res.duplicate ?? false,
+      all: res.all ?? []
+    };
+  }
+
+  async fetchInbox(sourceId, options = {}) {
+    // Enforce offline refusal before invoking any injected or vendored client
+    if (isOffline(this._offlineEnv)) {
+      if (!sourceId) {
+        throw offlineError("unspecified");
+      }
+      const blocked = refusedCarrier([sourceId], this._offlineEnv);
+      if (blocked) throw offlineError(blocked);
+    }
+
+    const knownSources = this.sources();
+    if (knownSources.length > 0 && !knownSources.includes(sourceId)) {
+      const err = new Error(`Unexpected source ID: ${sourceId}`);
+      err.code = "UNEXPECTED_SOURCE_ID";
+      throw err;
+    }
+
+    const res = await this.client.fetchInbox(sourceId, options);
+    return {
+      sourceId,
+      envelopes: (res.envelopes ?? []).map(item => ({
+        sourceId,
+        seq: item.seq,
+        envelope: item.envelope
+      })),
+      now: res.now ?? Date.now()
+    };
+  }
+
+  async close() {
+    // CarrierClient is stateless HTTP; no persistent resource to tear down.
+  }
+}

package/src/trust.mjs

@@ -0,0 +1,65 @@
+import { UuaidClient } from "@uuaid/sdk";
+import { Keychain } from "./pillar.mjs";
+import { isLoopbackUrl, isOffline } from "./offline.mjs";
+
+export const REQUIRED_STANDARDS=["IAASO-1001","IAASO-2001","IAASO-3101","IAASO-3301"];
+export class TrustError extends Error { constructor(code,message,{transient=false}={}){super(message);this.code=code;this.transient=transient} }
+// Network/5xx/429/timeout failures of the trust backend are transient: callers must retry, never treat them as a verdict on the sender.
+export function isTransientTrustFailure(error){if(error?.transient===true)return true;const status=error?.status??error?.statusCode;return error!=null&&!(error instanceof TrustError)&&(!Number.isInteger(status)||status>=500||status===408||status===429)}
+async function backend(fn,code){try{return await fn()}catch(error){if(error instanceof TrustError)throw error;if(isTransientTrustFailure(error))throw new TrustError(code,`Trust backend unavailable: ${String(error?.message??error).slice(0,120)}`,{transient:true});throw error}}
+export class RegistryTrust {
+  constructor({policy={},client,fetchImpl=fetch,env=process.env}={}) {
+    if(policy.mode!==undefined&&!["local","global"].includes(policy.mode))throw new TrustError("INVALID_POLICY_MODE","Policy mode must be explicitly local or global");
+    this.policy=policy;this.policy.mode??="local";this.env=env;
+    // One gate. policy.mode "local" skips only registry verification in authorize() (trust.mjs:44); policy.agents, key binding, and capability checks run in both modes; standards() still fetched (measured 2026-10-04).
+    this.fetch=async(url,init)=>{
+      if(isOffline(this.env,this.policy)&&!isLoopbackUrl(String(url)))throw new TrustError("OFFLINE","Offline mode refused an outbound fetch; no request was sent");
+      return fetchImpl(url,init);
+    };
+    this.client=client??new UuaidClient({baseUrl:policy.registryUrl??"https://api.uuaid.org",timeoutMs:10000,fetchImpl:this.fetch});
+  }
+  async standards(){
+    const pins=this.policy.standardPins??{};
+    if(REQUIRED_STANDARDS.some(code=>!/^[0-9a-f]{64}$/.test(pins[code]??"")))throw new TrustError("STANDARDS_UNPINNED","All required IAASO standard digests must be pinned before global admission");
+    const url=this.policy.authorityUrl??"https://authority.iaaso.org";
+    if(!url.startsWith("https://"))throw new TrustError("INSECURE_AUTHORITY","Global authority reads require HTTPS");
+    const response=await backend(()=>this.fetch(`${url.replace(/\/$/,"")}/v1/standards`,{signal:AbortSignal.timeout(10000)}),"AUTHORITY_UNAVAILABLE");
+    if(!response.ok)throw new TrustError("AUTHORITY_UNAVAILABLE","IAASO register could not be read",{transient:response.status>=500||response.status===429||response.status===408});
+    const list=(await backend(()=>response.json(),"AUTHORITY_UNAVAILABLE")).standards;
+    if(!Array.isArray(list))throw new TrustError("REGISTER_SHAPE","Invalid IAASO register response");
+    for(const code of REQUIRED_STANDARDS){
+      const record=list.find(r=>r.code===code);
+      if(record?.stage!=="published"||record.content_hash!==pins[code])throw new TrustError("STANDARD_PIN_MISMATCH",`${code} is not published at the configured digest`);
+    }
+    return list;
+  }
+  async authorize(uuaid,publicKey,capability="commons:message"){
+    if(!/^uuaid:[a-z0-9-]+:agent:[0-9a-f-]{36}$/.test(uuaid)||!/^[0-9a-f]{64}$/.test(publicKey))throw new TrustError("AGENT_ONLY","A cryptographically bound agent UUAID is required");
+    if(Keychain.localIdFromKey(Buffer.from(publicKey,"hex"))!==uuaid.split(":")[3])throw new TrustError("KEY_BINDING","Agent UUAID is not owned by the presented key");
+    if(this.policy.blocked?.includes(uuaid))throw new TrustError("SUBJECT_BLOCKED","Subject is blocked");
+    const binding=this.policy.agents?.[uuaid];
+    // One key must be one voice: reject any policy that admits the same key under several UUAID spellings.
+    if(binding&&Object.values(this.policy.agents).filter(a=>a?.publicKey===publicKey).length!==1)throw new TrustError("DUPLICATE_KEY","One public key is admitted under more than one UUAID; Sybil-ambiguous policy is denied");
+    if(!binding||binding.publicKey!==publicKey||binding.kind!=="agent"||!binding.capabilities?.includes(capability))throw new TrustError("NOT_ADMITTED","Subject/key/capability has not been admitted by this deployment");
+    if(this.policy.mode!=="global")return {tier:"local-policy-pinned",uuaid,capability,certified:false};
+    if(!(this.policy.registryUrl??"https://api.uuaid.org").startsWith("https://"))throw new TrustError("INSECURE_REGISTRY","Global registry verification requires HTTPS");
+    await this.standards();
+    const resolution=await backend(()=>this.client.resolve(uuaid),"REGISTRY_UNAVAILABLE");
+    const agent=resolution?.agent??resolution?.subject??resolution;
+    if(agent?.uuaid!==uuaid||agent.status!=="active")throw new TrustError("SUBJECT_INACTIVE","Registry subject is not explicitly active");
+    if(!binding.credentialId)throw new TrustError("CREDENTIAL_REQUIRED","Global agent admission requires a pinned credential");
+    const verdict=await backend(()=>this.client.verify(binding.credentialId),"REGISTRY_UNAVAILABLE");
+    if(verdict.credential_id!==binding.credentialId||verdict.agent_uuaid!==uuaid||![verdict.valid,verdict.signatureValid,verdict.active,verdict.notExpired].every(v=>v===true))throw new TrustError("CREDENTIAL_INVALID","Credential signature, subject, active status, or expiry failed");
+    // Capabilities are operator policy grants. A valid credential alone does not
+    // imply an IAASO accreditation role or permission to ratify a standard.
+    return {tier:"registry-credential-and-policy",uuaid,capability,credentialId:binding.credentialId,certified:false};
+  }
+  async publishedProfilePin(code,profileHash){
+    await this.standards();
+    const response=await backend(()=>this.fetch(`${(this.policy.authorityUrl??"https://authority.iaaso.org").replace(/\/$/,"")}/v1/standards`,{signal:AbortSignal.timeout(10000)}),"AUTHORITY_UNAVAILABLE");
+    if(!response.ok)throw new TrustError("AUTHORITY_UNAVAILABLE","Cannot inspect global profile authority",{transient:response.status>=500||response.status===429||response.status===408});
+    const record=(await backend(()=>response.json(),"AUTHORITY_UNAVAILABLE")).standards?.find(s=>s.code===code);
+    if(record?.stage!=="published"||record.content_hash!==profileHash)throw new TrustError("GLOBAL_NOT_RATIFIED","The exact global profile document is not published at this IAASO pin");
+    return record;
+  }
+}