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

package/src/loop.mjs

@@ -0,0 +1,71 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { randomUUID } from "node:crypto";
+const DEFAULT_BUDGET={maxSends:100,maxBytesOut:256000,maxRepliesPerPeer:8,maxWallClockMs:900000,windowMs:3600000,windowMaxSends:200,windowMaxBytes:2000000,windowMaxRepliesPerPeer:40};
+const SPONTANEOUS_KEYS=new Set(["recipient","profileId","namespace","body","thread","kind"]);
+/**
+ * Bounded agent loop. Budget (all enforced BEFORE a send):
+ *  - per-run: maxSends, maxBytesOut, maxRepliesPerPeer (stops reply ping-pong), maxWallClockMs
+ *  - per-window, persisted in runtime.store (survives loop restarts): windowMaxSends/Bytes/RepliesPerPeer
+ * The agent cannot raise these: callers pass `budget`; values are clamped to hard ceilings.
+ * Spontaneous actions may only be plain "message" sends to a peer already in policy.
+ */
+export async function runAgentLoop({runtime,respond,spontaneous=null,maxTurns=16,intervalMs=2000,signal,onEvent=()=>{},budget={}}){
+  if(!runtime||typeof respond!=="function"||!Number.isInteger(maxTurns)||maxTurns<1||maxTurns>100||!Number.isInteger(intervalMs)||intervalMs<500)throw new Error("Invalid bounded agent loop");
+  const limits={...DEFAULT_BUDGET};
+  for(const [k,v] of Object.entries(budget??{})){if(!(k in DEFAULT_BUDGET)||!Number.isSafeInteger(v)||v<1||v>DEFAULT_BUDGET[k])throw new Error(`Invalid loop budget ${k}`);limits[k]=v}
+  const started=Date.now(),run={sends:0,bytes:0,peers:{}},store=runtime.store&&typeof runtime.store.get==="function"?runtime.store:null;
+  const record=(reason,extra={})=>{try{store?.append?.(randomUUID(),{kind:"loop-budget-stop",reason,...extra})}catch{}};
+  // Returns a refusal reason or null, and reserves the budget when allowed.
+  const reserve=(peer,bytes)=>{
+    if(Date.now()-started>=limits.maxWallClockMs)return "wall-clock";
+    if(run.sends+1>limits.maxSends)return "run-sends";
+    if(run.bytes+bytes>limits.maxBytesOut)return "run-bytes";
+    if((run.peers[peer]??0)+1>limits.maxRepliesPerPeer)return "run-peer-replies";
+    let meter=null;
+    if(store){
+      meter=store.get("loopMeter",null);const now=Date.now();
+      if(!meter||now-meter.start>=limits.windowMs)meter={start:now,sends:0,bytes:0,peers:{}};
+      if(meter.sends+1>limits.windowMaxSends)return "window-sends";
+      if(meter.bytes+bytes>limits.windowMaxBytes)return "window-bytes";
+      if((meter.peers[peer]??0)+1>limits.windowMaxRepliesPerPeer)return "window-peer-replies";
+      meter.sends++;meter.bytes+=bytes;meter.peers[peer]=(meter.peers[peer]??0)+1;
+      if(Object.keys(meter.peers).length>1000)return "window-peers";
+      store.set("loopMeter",meter);
+    }
+    run.sends++;run.bytes+=bytes;run.peers[peer]=(run.peers[peer]??0)+1;return null;
+  };
+  let turns=0,stopped=null;
+  const send=async(action)=>{
+    const reason=reserve(String(action.recipient),Buffer.byteLength(String(action.body??"")));
+    if(reason){stopped=`budget:${reason}`;record(reason,{peer:String(action.recipient).slice(0,120)});onEvent({rejected:true,state:"budget-refused",reason});return false}
+    onEvent(await runtime.send(action));return true;
+  };
+  while(turns<maxTurns&&!signal?.aborted&&!stopped){
+    const packets=await runtime.poll();
+    for(const packet of packets){
+      if(packet.duplicate||packet.rejected||packet.deferred||typeof packet.body!=="string"){onEvent(packet);continue}
+      let reply;
+      try{reply=await respond({packet,status:runtime.status(),signal})}
+      catch(error){turns++;onEvent({rejected:true,state:"responder-failed",reason:String(error?.message??error).slice(0,200)});if(turns>=maxTurns||signal?.aborted)break;continue}
+      turns++;
+      if(reply!==null&&reply!==undefined){
+        if(typeof reply!=="string")throw new Error("Agent responder must return bounded plain text or null");
+        if(!await send({recipient:packet.sender,profileId:packet.profileId,thread:packet.thread,body:reply}))break;
+      }
+      if(turns>=maxTurns||signal?.aborted)break;
+    }
+    if(stopped)break;
+    if(!packets.length&&spontaneous&&turns<maxTurns){
+      const action=await spontaneous({status:runtime.status(),signal});
+      turns++;
+      if(action){
+        const allowedPeers=runtime.policy?.agents;
+        if(typeof action!=="object"||Object.keys(action).some(k=>!SPONTANEOUS_KEYS.has(k))||(action.kind!==undefined&&action.kind!=="message")||typeof action.recipient!=="string"||typeof action.body!=="string"||(allowedPeers&&!Object.hasOwn(allowedPeers,action.recipient))){onEvent({rejected:true,state:"spontaneous-action-refused"});record("spontaneous-action-refused")}
+        else if(!await send(action))break;
+      }
+    }
+    await runtime.flush();
+    if(turns<maxTurns&&!signal?.aborted)try{await delay(intervalMs,null,{signal})}catch(error){if(error.name!=="AbortError")throw error}
+  }
+  return {turns,stopped:stopped??(signal?.aborted?"aborted":"turn-limit"),usage:{...run,peers:undefined}};
+}

package/src/offline.d.mts

@@ -0,0 +1,7 @@
+export const OFFLINE_ENV: "AGENT_COMMONS_OFFLINE";
+export function isLoopbackHost(hostname: string): boolean;
+export function isLoopbackUrl(url: string): boolean;
+export function isOffline(
+  env?: Record<string, string | undefined>,
+  policy?: { mode?: string; offline?: boolean },
+): boolean;

package/src/offline.mjs

@@ -0,0 +1,29 @@
+// Offline mode. Default on for a local run.
+// AGENT_COMMONS_OFFLINE=1 forces offline, including policy.mode "global".
+// AGENT_COMMONS_OFFLINE=0 is the only opt-in that allows outbound calls.
+// Unset: offline, unless policy.offline is false, or policy.mode is "global"
+// and the policy does not set offline. Loopback is a local carrier, not egress.
+
+export const OFFLINE_ENV = "AGENT_COMMONS_OFFLINE";
+
+export function isLoopbackHost(hostname) {
+  const host = String(hostname ?? "").toLowerCase().replace(/^\[|\]$/g, "");
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+
+export function isLoopbackUrl(url) {
+  try {
+    return isLoopbackHost(new URL(String(url)).hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function isOffline(env = process.env, policy) {
+  const flag = env?.[OFFLINE_ENV];
+  if (flag === "1") return true;
+  if (flag === "0") return false;
+  if (policy && Object.prototype.hasOwnProperty.call(policy, "offline")) return policy.offline !== false;
+  if (policy?.mode === "global") return false;
+  return true;
+}

package/src/pillar.mjs

@@ -0,0 +1,59 @@
+// Unmodified upstream modules are covered by NOTICE and PROVENANCE.json.
+// CarrierClient is wrapped here. The vendored module stays byte-identical to
+// @uuaid/pillar 2.2.0. Offline refusal happens before any vendored method runs.
+import { CarrierClient as VendoredCarrierClient } from "./vendor/pillar/net/carrier-client.mjs";
+import { isLoopbackUrl, isOffline } from "./offline.mjs";
+
+export { Keychain, localIdFromKey } from "./vendor/pillar/identity/keychain.mjs";
+export { jcs } from "./vendor/pillar/identity/jcs.mjs";
+export { seal, open, decrypt, envelopeSha, ENVELOPE_VERSION } from "./vendor/pillar/net/envelope.mjs";
+
+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;
+}
+
+export class CarrierClient extends VendoredCarrierClient {
+  constructor(options = {}) {
+    super(options);
+    // Upstream pillar 2.2.0 does not store env. The package seam does.
+    this._offlineEnv = options.env ?? process.env;
+  }
+
+  async deliver(envelope, options) {
+    const blocked = refusedCarrier(this.carriers, this._offlineEnv);
+    if (blocked) throw offlineError(blocked);
+    return super.deliver(envelope, options);
+  }
+
+  async fetchInbox(base, options) {
+    const blocked = refusedCarrier([base], this._offlineEnv);
+    if (blocked) throw offlineError(blocked);
+    return super.fetchInbox(base, options);
+  }
+
+  startPolling(options = {}) {
+    const blocked = refusedCarrier(this.carriers, this._offlineEnv);
+    if (blocked) {
+      const error = offlineError(blocked);
+      options.onError?.(error, { carrier: blocked });
+      const cursors = { ...(options.cursors ?? {}) };
+      return {
+        stop() {},
+        cursors: () => ({ ...cursors }),
+        done: Promise.resolve([]),
+      };
+    }
+    return super.startPolling(options);
+  }
+}

package/src/profiles.d.mts

@@ -0,0 +1,12 @@
+import type { Profile, Keychain } from "./index.d.ts";
+export function createProfile(options:{namespace:string;name:string;fixtures:string[];scope?:"local"|"tenant"|"global";lexicon?:Record<string,string>;parent?:string|null;revision?:number;quorum?:number}):Profile;
+export function verifyProfile(profile:Profile):Profile;
+export function proposeAlias(profile:Profile,phrase:string):any;
+export function contribution(profile:Profile,options?:{includeFixtures?:boolean}):any;
+export function signDocument(keychain:Keychain,kind:string,payload:any):any;
+export function digest(value:any):string;
+export function benchmark(lexicon:Record<string,string>,fixtures:string[]):Profile["benchmark"];
+export function encode(text:string,lexicon:Record<string,string>):string;
+export function decode(text:string,lexicon:Record<string,string>):string;
+export function verifyDocument(document:any):any;
+export const BASE_PROTOCOL:"agent-commons/1";

package/src/profiles.mjs

@@ -0,0 +1,92 @@
+import { createHash, randomUUID } from "node:crypto";
+import { jcs, Keychain } from "./pillar.mjs";
+import { SELF_CERTIFYING_AGENT_UUAID } from "./uuaid-namespace.mjs";
+
+export const BASE_PROTOCOL = "agent-commons/1";
+export function digest(value) { assertJSON(value);return createHash("sha256").update(jcs(value)).digest("hex"); }
+export function assertJSON(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number" && Number.isSafeInteger(value)) return;
+  if (Array.isArray(value)) return value.forEach(assertJSON);
+  if (value && Object.getPrototypeOf(value) === Object.prototype) {
+    for (const [key, item] of Object.entries(value)) {
+      if (!/^[\x20-\x7e]+$/.test(key) || ["__proto__", "prototype", "constructor"].includes(key)) throw new Error("Unsafe canonical key");
+      assertJSON(item);
+    }
+    return;
+  }
+  throw new Error("Expected canonical JSON; decimal measurements must be strings");
+}
+export function encode(body, lexicon) {
+  let wire=body.replaceAll("~","~~");
+  for (const [phrase,alias] of Object.entries(lexicon).sort((a,b)=>b[0].length-a[0].length)) wire=wire.split(phrase).join(alias);
+  return wire;
+}
+export function decode(wire, lexicon) {
+  const reverse=new Map(Object.entries(lexicon).map(([k,v])=>[v,k]));
+  return wire.replace(/~~|~\d+~/g,t=>t==="~~"?"~":reverse.get(t)??t);
+}
+export function validateLexicon(lexicon) {
+  if (!lexicon || typeof lexicon!=="object" || Array.isArray(lexicon) || Object.keys(lexicon).length>128) throw new Error("Invalid lexicon");
+  const symbols=new Set();
+  for (const [phrase,symbol] of Object.entries(lexicon)) {
+    if (!/^[A-Za-z][A-Za-z ]{7,79}$/.test(phrase) || phrase!==phrase.trim() || !/^~\d{1,3}~$/.test(symbol) || symbols.has(symbol)) throw new Error("Invalid or colliding alias");
+    symbols.add(symbol);
+  }
+}
+export function benchmark(lexicon, fixtures) {
+  validateLexicon(lexicon);
+  let originalBytes=0,wireBytes=0,passed=0;
+  for (const fixture of fixtures) {
+    const wire=encode(fixture,lexicon);
+    if(decode(wire,lexicon)===fixture)passed++;
+    originalBytes+=Buffer.byteLength(fixture);wireBytes+=Buffer.byteLength(wire);
+  }
+  return {tests:fixtures.length,passed,originalBytes,wireBytes,reductionBps:originalBytes?Math.round(10000*(originalBytes-wireBytes)/originalBytes):0};
+}
+const safetyFixtures=["","~0~","~~","~123~","தமிழ் மொழி","🧬","\n\\\"", "a".repeat(128)];
+export function createProfile({ namespace, name, fixtures, scope="local", lexicon={}, parent=null, revision=0, quorum=2 }) {
+  if (!/^[a-z0-9][a-z0-9._/-]{1,119}$/.test(namespace)||typeof name!=="string"||name.length<2||name.length>120) throw new Error("Invalid profile name or namespace");
+  if (!["local","tenant","global"].includes(scope)) throw new Error("Invalid profile scope");
+  if(!Array.isArray(fixtures)||fixtures.length<2||fixtures.length>100||fixtures.some(f=>typeof f!=="string"||f.length>8000)||Buffer.byteLength(JSON.stringify(fixtures))>256000) throw new Error("Provide 2–100 bounded text fixtures");
+  if(!Number.isSafeInteger(revision)||revision<0||!Number.isSafeInteger(quorum)||quorum<2||quorum>10)throw new Error("Invalid profile revision or quorum");
+  validateLexicon(lexicon);
+  const report=benchmark(lexicon,[...fixtures,...safetyFixtures]);
+  if(report.tests!==report.passed)throw new Error("Profile fails lossless gate");
+  const document={v:BASE_PROTOCOL,namespace,name,scope,parent,revision,quorum,lexicon,fixtureHash:digest(fixtures),fixtures};
+  assertJSON(document);
+  return {...document,id:digest(document),benchmark:report};
+}
+export function verifyProfile(profile) {
+  const allowed=new Set(["v","namespace","name","scope","parent","revision","quorum","lexicon","fixtureHash","fixtures","id","benchmark"]);
+  if(Object.keys(profile??{}).some(key=>!allowed.has(key)))throw new Error("Unknown profile field");
+  const rebuilt=createProfile(profile);
+  if(rebuilt.id!==profile.id || digest(rebuilt.benchmark)!==digest(profile.benchmark))throw new Error("Profile digest or benchmark mismatch");
+  return rebuilt;
+}
+export function proposeAlias(profile, phrase) {
+  verifyProfile(profile);
+  if(Object.hasOwn(profile.lexicon,phrase))throw new Error("Alias already exists");
+  const numbers=Object.values(profile.lexicon).map(s=>Number(s.slice(1,-1)));
+  const alias=`~${numbers.length?Math.max(...numbers)+1:0}~`;
+  const candidate=createProfile({...profile,lexicon:{...profile.lexicon,[phrase]:alias},parent:profile.id,revision:profile.revision+1});
+  if(candidate.benchmark.wireBytes>=profile.benchmark.wireBytes)throw new Error("Candidate does not improve the local benchmark");
+  return {id:randomUUID(),parent:profile.id,candidate,phrase,alias,status:"pending",votes:{}};
+}
+export function signDocument(keychain, kind, payload) {
+  assertJSON(payload);
+  const body={v:BASE_PROTOCOL,id:randomUUID(),kind,issuer:keychain._identity.uuaid,publicKey:keychain._identity.publicKeyHex,createdAt:new Date().toISOString(),payload};
+  return {...body,signature:keychain.sign(Buffer.from(jcs(body))).toString("hex")};
+}
+export function verifyDocument(document) {
+  assertJSON(document);
+  const {signature,...body}=document;
+  if(body.v!==BASE_PROTOCOL||!["profile-proposal","profile-vote","profile-contribution","profile-recovery"].includes(body.kind)||!SELF_CERTIFYING_AGENT_UUAID.test(body.issuer)||!/^[0-9a-f]{64}$/.test(body.publicKey)||!/^[0-9a-f]{128}$/.test(signature))throw new Error("Invalid agent document");
+  if(Keychain.localIdFromKey(Buffer.from(body.publicKey,"hex"))!==body.issuer.split(":")[3])throw new Error("Agent key is not bound to UUAID");
+  if(!Keychain.verifyDetached(body.publicKey,Buffer.from(jcs(body)),Buffer.from(signature,"hex")))throw new Error("Invalid document signature");
+  return body;
+}
+export function contribution(profile, { includeFixtures=false }={}) {
+  verifyProfile(profile);
+  return {profileId:profile.id,namespace:profile.namespace,parent:profile.parent,base:BASE_PROTOCOL,lexicon:profile.lexicon,fixtureHash:profile.fixtureHash,benchmark:profile.benchmark,visibility:includeFixtures?"shared-fixtures":"metadata-only",...(includeFixtures?{profile}:{}),stage:"candidate",standardization:"requires-IAASO-review"};
+}

package/src/relay/auth.mjs

@@ -0,0 +1,294 @@
+// Cloud Commons relay: request authentication and response signing (spec v3.4.5 sections 6.1,
+// 6.2, 6.3 and 6.5 "Signer = by").
+//
+// Port source (B1): the identity repo at commit cf48f0e, ported verbatim:
+//   packages/pillar-client/src/identity-request.ts - the header name and grammar, the strict
+//     parser (:95-114), the descriptor (:54-66), the body hash (:71-74), the signing bytes
+//     (:77-79) and verifyIdentityRequest;
+//   packages/pillar-client/src/identity.ts - isStrictEd25519PublicKey and verifyBytesStrict
+//     (RFC 8032 strict: canonical A and R, never a small-order or mixed-order key);
+//   apps/api/src/self-auth.ts:41-77 - the verifier order: a stale request is refused unverified;
+//     a future-dated one is verified and refused only after its nonce is spent.
+// The port passes the vector docs/standards/agent-vault-wallet/vectors/identity-auth.json at that
+// commit, with the vector's own audience and namespace (test/relay-auth.test.mjs), before it is
+// used with the relay's.
+//
+// The relay's differences (6.1, 6.3): the audience is one configured string compared byte for byte
+// (never the Host header); the principal header `commons-principal` names the agent and must be an
+// agentnet id (B3); the key comes from the relay's own keys table (D-i); every principal failure is
+// the same 401 {"error":"unauthorized"} after a check against a fixed dummy key; the nonce is spent
+// (UNIQUE(principal, nonce)) before the future check; a replay is 409. On every fleet record
+// the authenticated signer must equal the body's `by` (6.5).
+//
+// 6.2: every relay response carries `commons-relay-sig`, Ed25519 by the relay key over
+// JCS({aud, request_nonce, status, body_sha256}); signRelayResponse takes the relay key seed from
+// its caller (the server) and verifyRelayResponse is the client's check against the pinned key.
+//
+// This module performs no network I/O and stores no private key. The server applies the size
+// cap, the route inventory and the browser-origin refusal before calling authenticateRequest.
+
+import { createHash, randomBytes } from "node:crypto";
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { jcs } from "../pillar.mjs";
+import { localIdFromKey } from "../vendor/pillar/identity/keychain.mjs";
+import { keyBindsAgentUuaid } from "../uuaid-namespace.mjs";
+import { RelayError, assertIntegerOnly } from "./records.mjs";
+import { tx } from "./schema.mjs";
+
+// --- verbatim port: identity-request.ts (cf48f0e) ----------------------------------------
+
+export const IDENTITY_AUTH_HEADER = "uuaid-identity-auth";
+export const IDENTITY_REQUEST_TYPE = "uuaid.identity.request.v1";
+/** The methods an identity key may sign. */
+export const IDENTITY_REQUEST_METHODS = Object.freeze(["GET", "PUT", "POST", "DELETE", "PATCH"]);
+
+/** The object the identity key signs. Never transmitted: the verifier rebuilds it. */
+export function identityRequestDescriptor(i) {
+  return {
+    type: IDENTITY_REQUEST_TYPE,
+    aud: i.audience,
+    agent: i.agent,
+    method: i.method.toUpperCase(),
+    path: i.path,
+    query: i.query ?? "",
+    body_sha256: i.bodySha256,
+    created: i.created,
+    nonce: i.nonce,
+  };
+}
+
+/** sha256 hex of JCS(body); null when there is no body. */
+export function identityRequestBodyHash(body) {
+  if (body === undefined || body === null) return null;
+  return createHash("sha256").update(Buffer.from(jcs(body), "utf8")).digest("hex");
+}
+
+/** The exact bytes the identity key signs. */
+export function identityRequestSigningBytes(d) {
+  return Buffer.from(`${IDENTITY_REQUEST_TYPE}\n${jcs(d)}`, "utf8");
+}
+
+export function formatIdentityAuthHeader(h) {
+  return `v=${h.v}; created=${h.created}; nonce=${h.nonce}; ed25519=${h.ed25519}`;
+}
+
+const CREATED_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+
+/** Parse the header strictly: every field once, nothing else. Null on any defect. */
+export function parseIdentityAuthHeader(value) {
+  if (typeof value !== "string" || value.length > 512) return null;
+  const fields = new Map();
+  for (const part of value.split(";")) {
+    const t = part.trim();
+    const eq = t.indexOf("=");
+    if (eq <= 0) return null;
+    const k = t.slice(0, eq);
+    if (fields.has(k)) return null;
+    fields.set(k, t.slice(eq + 1));
+  }
+  const keys = ["v", "created", "nonce", "ed25519"];
+  if (fields.size !== keys.length || !keys.every((k) => fields.has(k))) return null;
+  const created = fields.get("created");
+  if (fields.get("v") !== "1") return null;
+  if (!CREATED_RE.test(created) || Number.isNaN(Date.parse(created))) return null;
+  if (!/^[0-9a-f]{32,64}$/.test(fields.get("nonce"))) return null;
+  if (!/^[0-9a-f]{128}$/.test(fields.get("ed25519"))) return null;
+  return { v: "1", created, nonce: fields.get("nonce"), ed25519: fields.get("ed25519") };
+}
+
+// --- verbatim port: identity.ts (cf48f0e) -------------------------------------------------
+
+export function isStrictEd25519PublicKey(pubKeyHex) {
+  if (typeof pubKeyHex !== "string" || !/^[0-9a-f]{64}$/i.test(pubKeyHex)) return false;
+  const hex = pubKeyHex.toLowerCase();
+  try {
+    const point = ed25519.Point.fromHex(hex, false);
+    return point.toHex() === hex && !point.isSmallOrder() && point.isTorsionFree();
+  } catch {
+    return false;
+  }
+}
+
+export function verifyBytesStrict(pubKeyHex, msg, sigHex) {
+  if (!isStrictEd25519PublicKey(pubKeyHex)) return false;
+  if (typeof sigHex !== "string" || !/^[0-9a-f]{128}$/i.test(sigHex)) return false;
+  try {
+    return ed25519.verify(Buffer.from(sigHex.toLowerCase(), "hex"), msg, Buffer.from(pubKeyHex.toLowerCase(), "hex"), { zip215: false });
+  } catch {
+    return false;
+  }
+}
+
+/** Verify a parsed header against a rebuilt descriptor and the agent's identity key (RFC 8032, prime-order key). */
+export function verifyIdentityRequest(d, h, publicKeyHex) {
+  if (d.created !== h.created || d.nonce !== h.nonce) return false;
+  return verifyBytesStrict(publicKeyHex, identityRequestSigningBytes(d), h.ed25519);
+}
+
+/**
+ * Sign a request with an identity key seed (the reference client's signer; tests). Returns the
+ * header value. The seed never leaves the caller. `created` and `nonce` overrides are for fixed
+ * test vectors only.
+ */
+export function signIdentityRequest({ seedHex, namespace = "agentnet", method, path, query, body, audience, created, nonce }) {
+  const seed = Buffer.from(seedHex, "hex");
+  const pub = Buffer.from(ed25519.getPublicKey(seed));
+  const agent = `uuaid:${namespace}:agent:${localIdFromKey(pub)}`;
+  const c = created ?? new Date().toISOString();
+  const n = nonce ?? randomBytes(16).toString("hex");
+  const d = identityRequestDescriptor({ audience, agent, method, path, query, bodySha256: identityRequestBodyHash(body), created: c, nonce: n });
+  const sig = Buffer.from(ed25519.sign(identityRequestSigningBytes(d), seed)).toString("hex");
+  return { agent, publicKey: pub.toString("hex"), header: formatIdentityAuthHeader({ v: "1", created: c, nonce: n, ed25519: sig }) };
+}
+
+// --- the relay verifier (6.1, 6.3) ----------------------------------------------------------
+
+export const PRINCIPAL_HEADER = "commons-principal";
+/** The test audience (6.1, B5): `.test` is reserved (RFC 6761); a deployed relay is configured with its own origin. */
+export const RELAY_TEST_AUD = "http://commons-relay.test:8080";
+export const AUTH_MAX_AGE_MS = 5 * 60 * 1000;
+export const AUTH_MAX_FUTURE_MS = 60 * 1000;
+export const NONCE_KEEP_MS = 10 * 60 * 1000;   // covers the 6-minute acceptance span (6.1)
+
+/** The uniform refusal (6.3): the same status and body for every principal or signature failure. */
+export const UNAUTHORIZED = Object.freeze({ status: 401, body: Object.freeze({ error: "unauthorized" }) });
+const STALE = Object.freeze({ status: 401, body: Object.freeze({ error: "stale" }) });   // principal-independent (6.3)
+const REPLAY = Object.freeze({ status: 409, body: Object.freeze({ error: "replay" }) });   // reachable only with a valid signature
+
+// A fixed, valid, strict key with no known seed holder: the refusal path for an unknown or
+// ineligible principal still runs one signature check, so it takes similar time (6.3).
+const DUMMY_PUBLIC_KEY = Buffer.from(ed25519.getPublicKey(createHash("sha256").update("commons-relay.dummy-key.v1").digest())).toString("hex");
+
+const AGENTNET_AGENT = /^uuaid:agentnet:agent:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** B3: an agentnet agent id (the only namespace the relay accepts). */
+export const isAgentnetAgent = (value) => typeof value === "string" && AGENTNET_AGENT.test(value);
+const header = (headers, name) => {
+  const v = headers?.[name] ?? headers?.[name.toLowerCase()];
+  return Array.isArray(v) ? null : v;   // a repeated header is a malformed request
+};
+
+/**
+ * The principal a key row names, with the facts the verifier needs, read from the relay's tables
+ * on every request with no cache (M3). Null when the agent has no key row.
+ */
+function principalOf(db, agent) {
+  const k = db.prepare("SELECT public_key, agent, principal_kind, principal_id, status FROM keys WHERE agent = ?").get(agent);
+  if (!k) return null;
+  if (k.principal_kind === "fleet") {
+    const f = db.prepare("SELECT kind, status FROM fleet_principals WHERE principal_id = ?").get(k.principal_id);
+    return { kind: "fleet", id: k.principal_id, agent, publicKey: k.public_key, keyStatus: k.status, fleetKind: f?.kind ?? null, status: f?.status ?? null };
+  }
+  const m = db.prepare("SELECT status, role FROM members WHERE member_id = ?").get(k.principal_id);
+  return { kind: "member", id: k.principal_id, agent, publicKey: k.public_key, keyStatus: k.status, status: m?.status ?? null, role: m?.role ?? null };
+}
+
+/**
+ * Whether this principal may be authenticated on this request (6.1 step 3):
+ * - a fleet principal: an active key of an active roster principal;
+ * - a member: an active key and status active; or, only where `allowPending` (GET /v1/status
+ *   only), a pending member on its pending enrollment key.
+ * Suspended, revoked, unknown, retired and revoked-key principals are ineligible: uniform 401.
+ */
+function eligible(p, allowPending) {
+  if (!p) return false;
+  if (p.kind === "fleet") return p.keyStatus === "active" && p.status === "active";
+  if (p.keyStatus === "active" && p.status === "active") return true;
+  return allowPending && p.keyStatus === "pending" && p.status === "pending";
+}
+
+/**
+ * Authenticate one request (6.1 steps 2-6; 3 and 8 read the tables on every request).
+ * `req` = { method, path, query, headers, body } with `body` the parsed JSON body (undefined when
+ * there is none); `aud` the relay's configured audience; `now` the relay clock in ms.
+ * Returns { ok: true, principal } or { ok: false, status, body }. Throws RelayError
+ * non-integer-number (400) for a body JCS cannot hash, before any signature or nonce work (B4).
+ */
+/** 6.1 `created`: the header grammar's RFC 3339 UTC form (shared with the enrollment flow). */
+export const isCreated = (value) => typeof value === "string" && CREATED_RE.test(value) && !Number.isNaN(Date.parse(value));
+/** 6.1 `nonce`: 32-64 lower-case hex (shared with the enrollment flow). */
+export const isNonce = (value) => typeof value === "string" && /^[0-9a-f]{32,64}$/.test(value);
+
+/**
+ * 6.1 step 5 / 5.2 step 6 (B9): spend (principal, nonce) in the one request-nonce table, pruning
+ * expired rows. Returns false on a replay. The row is kept NONCE_KEEP_MS past max(created, now).
+ */
+export function spendNonce(db, principal, nonce, createdMs, now) {
+  return tx(db, () => {
+    db.prepare("DELETE FROM request_nonces WHERE expires_at <= ?").run(now);
+    const r = db.prepare("INSERT INTO request_nonces(principal, nonce, expires_at) VALUES (?, ?, ?) ON CONFLICT DO NOTHING")
+      .run(principal, nonce, Math.max(createdMs, now) + NONCE_KEEP_MS);
+    return r.changes === 1;
+  });
+}
+
+export function authenticateRequest(db, req, { aud, now, allowPending = false }) {
+  if (typeof aud !== "string" || !aud) throw new RelayError("relay-aud-unset", 500);
+  if (!Number.isSafeInteger(now)) throw new RelayError("invalid-time", 500);
+  // Step 2: parse; a stale request is refused before any principal or signature work.
+  const h = parseIdentityAuthHeader(header(req.headers, IDENTITY_AUTH_HEADER));
+  const agent = header(req.headers, PRINCIPAL_HEADER);
+  if (!h || typeof agent !== "string") return { ok: false, ...UNAUTHORIZED };
+  const created = Date.parse(h.created);
+  if (created < now - AUTH_MAX_AGE_MS) return { ok: false, ...STALE };
+  // B4: integer-only bodies; hashing fails before any signature work, so no nonce is spent.
+  if (req.body !== undefined && req.body !== null) assertIntegerOnly(req.body);
+  const bodySha256 = identityRequestBodyHash(req.body);
+  // Step 3: the principal's current key, from the relay's own tables (D-i); never from the request.
+  const p = AGENTNET_AGENT.test(agent) ? principalOf(db, agent) : null;
+  const ok = eligible(p, allowPending);
+  const key = ok ? p.publicKey : DUMMY_PUBLIC_KEY;
+  // Step 4: strict Ed25519; the key derives the agent in agentnet (B3); the signature over the
+  // descriptor the relay rebuilds from the request it received, with its own audience (B5).
+  const d = identityRequestDescriptor({ audience: aud, agent, method: req.method, path: req.path, query: req.query ?? "", bodySha256, created: h.created, nonce: h.nonce });
+  const verified = verifyIdentityRequest(d, h, key) && isStrictEd25519PublicKey(key) && keyBindsAgentUuaid(agent, key);
+  if (!ok || !verified) return { ok: false, ...UNAUTHORIZED };
+  // Step 5: spend the nonce before the future check. It stays spent even if a later step fails.
+  if (!spendNonce(db, agent, h.nonce, created, now)) return { ok: false, ...REPLAY };
+  // Step 6: more than 60 s ahead is refused, after the nonce is spent.
+  if (created > now + AUTH_MAX_FUTURE_MS) return { ok: false, ...STALE };
+  return { ok: true, principal: { kind: p.kind, id: p.id, agent, status: p.status, ...(p.kind === "fleet" ? { fleetKind: p.fleetKind } : { role: p.role }) } };
+}
+
+/**
+ * 6.5 "Signer = by": a fleet record is accepted only from the fleet principal its
+ * body names. A member principal, or any other fleet principal, gets the uniform 401, so a captured
+ * signed body cannot be re-submitted by another principal.
+ */
+export function signerMatchesBy(principal, body) {
+  return !!principal && principal.kind === "fleet" && !!body && typeof body === "object" && body.by === principal.id;
+}
+
+// --- relay authenticity (6.2) ----------------------------------------------------------------
+
+/** 6.2: the header that carries the relay's signature on every response. */
+export const RELAY_SIG_HEADER = "commons-relay-sig";
+
+/**
+ * 6.2: the bytes the relay signs for one response: JCS({aud, request_nonce, status, body_sha256}),
+ * with body_sha256 defined as in 6.1 (sha256 hex of JCS(body), or null when there is no body).
+ * `requestNonce` is the request's own 6.1 nonce, or null when the request carried no header that parses.
+ */
+export function relayResponseSigningBytes({ aud, requestNonce, status, body }) {
+  if (typeof aud !== "string" || !aud) throw new RelayError("relay-aud-unset", 500);
+  if (!Number.isSafeInteger(status) || status < 100 || status > 599) throw new RelayError("invalid-status", 500);
+  if (requestNonce !== null && !(typeof requestNonce === "string" && /^[0-9a-f]{32,64}$/.test(requestNonce))) throw new RelayError("invalid-nonce", 500);
+  return Buffer.from(jcs({ aud, request_nonce: requestNonce, status, body_sha256: identityRequestBodyHash(body) }), "utf8");
+}
+
+/** Sign a response with the relay key seed (32-byte hex, held by the server only). Returns 128 hex. */
+export function signRelayResponse(relaySeedHex, response) {
+  return Buffer.from(ed25519.sign(relayResponseSigningBytes(response), Buffer.from(relaySeedHex, "hex"))).toString("hex");
+}
+
+/** A client's check (6.2): strict Ed25519 against the pinned 64-hex relay key, byte for byte. */
+export function verifyRelayResponse(relayPublicKeyHex, response, sigHex) {
+  if (typeof relayPublicKeyHex !== "string" || !/^[0-9a-f]{64}$/.test(relayPublicKeyHex)) return false;
+  let bytes;
+  try { bytes = relayResponseSigningBytes(response); } catch { return false; }
+  return isStrictEd25519PublicKey(relayPublicKeyHex) && verifyBytesStrict(relayPublicKeyHex, bytes, sigHex);
+}
+
+/** The request's 6.1 nonce for the response signature: the strict header parse, or null. */
+export function requestNonceOf(headers) {
+  return parseIdentityAuthHeader(header(headers, IDENTITY_AUTH_HEADER))?.nonce ?? null;
+}