@twin3-ai/agent-id 0.3.48 → 0.3.49

package/browser-sdk.js

@@ -16,7 +16,7 @@
   // browser script and shipped in the package byte-for-byte, so it can
   // neither read the package at runtime nor go through a build step:
   // the version is written once here and CI refuses a mismatch.
-  var SDK_VERSION = "0.3.48";
+  var SDK_VERSION = "0.3.49";
   var w = window;
   var d = document;
   var s = d.currentScript || {};

package/inbox-counterparty.js

@@ -0,0 +1,233 @@
+"use strict";
+
+// Counterparty-side SDK for the xAgent Inbox: what an *external* agent needs
+// to complete a KYA handshake with an owner and send it signed envelopes.
+//
+// This side never holds the owner's credentials. It produces three things -
+// a public key, a signed handshake answer, and signed envelopes - and hands
+// them to the owner over whatever channel the two agents already share
+// (A2A, a relay, a test harness). The owner's own agent then calls its
+// /api/site_agents/v1/inbox/* routes. `createRelayTransport` covers the case
+// where one party operates both ends, e.g. integration tests.
+//
+// Wire compatibility with agent_id/inbox/kya.py is guaranteed two ways:
+//   1. The handshake answer signs the exact bytes the server publishes as
+//      `sign_payload`, so no re-serialization happens on this side.
+//   2. Envelopes use integer timestamps and canonical JSON (sorted keys, no
+//      spaces, non-ASCII unescaped), which is byte-identical to Python's
+//      json.dumps(sort_keys=True, separators=(",",":"), ensure_ascii=False)
+//      for the value types an envelope may carry.
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+
+const ENVELOPE_SCHEMA = "agentx-inbox-envelope-v1";
+const CHALLENGE_SCHEMA = "agentx-inbox-kya-challenge-v1";
+const SIGNATURE_SCHEMA = "agentx-inbox-envelope-signature-v1";
+// The owner is migrating the published schema prefix from agentx-* to twin3-*.
+// Accept both while that is in flight; the owner signature covers the schema
+// field itself, so accepting a second name does not widen what is verified.
+const VALID_CHALLENGE_SCHEMAS = new Set([CHALLENGE_SCHEMA, "twin3-trust-kya-challenge-v1"]);
+const ENVELOPE_KINDS = new Set(["quote_request", "task_offer", "introduction", "message"]);
+const CHALLENGE_SIGNED_FIELDS = ["schema", "handshake_id", "owner", "identity", "counterparty_key_id", "owner_key_id", "nonce", "issued_at", "expires_at"];
+
+function sdkError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+}
+
+function canonicalJson(value) {
+  return Buffer.from(JSON.stringify(stableValue(value)), "utf8");
+}
+
+function b64url(buffer) {
+  return Buffer.from(buffer).toString("base64url");
+}
+
+function b64urlDecode(text) {
+  return Buffer.from(String(text || ""), "base64url");
+}
+
+// --- keys --------------------------------------------------------------------
+
+function loadPrivateKey({ keyPath, privateKeyPem } = {}) {
+  const pem = privateKeyPem || (keyPath ? fs.readFileSync(keyPath, "utf8") : "");
+  if (!pem) throw sdkError("private_key_required");
+  const key = crypto.createPrivateKey(pem);
+  if (key.asymmetricKeyType !== "ed25519") throw sdkError("private_key_not_ed25519");
+  return key;
+}
+
+function rawPublicBytes(publicKey) {
+  // SPKI DER for Ed25519 is a fixed 12-byte prefix followed by the 32 raw bytes.
+  const der = publicKey.export({ type: "spki", format: "der" });
+  return der.subarray(der.length - 32);
+}
+
+function keyId(publicKey) {
+  return "ed25519:" + crypto.createHash("sha256").update(rawPublicBytes(publicKey)).digest("hex").slice(0, 24);
+}
+
+function exportPublicKey(publicKey, format = "compact") {
+  if (format === "pem") return publicKey.export({ type: "spki", format: "pem" });
+  if (format === "compact") return "ed25519:" + b64url(rawPublicBytes(publicKey));
+  throw sdkError("public_key_format_unknown");
+}
+
+function loadPublicKey(value) {
+  const text = String(value || "").trim();
+  if (!text) throw sdkError("public_key_required");
+  if (text.startsWith("-----BEGIN")) {
+    const key = crypto.createPublicKey(text);
+    if (key.asymmetricKeyType !== "ed25519") throw sdkError("public_key_not_ed25519");
+    return key;
+  }
+  if (text.startsWith("ed25519:")) {
+    const raw = b64urlDecode(text.slice("ed25519:".length));
+    if (raw.length !== 32) throw sdkError("invalid_ed25519_public_key_length");
+    const prefix = Buffer.from("302a300506032b6570032100", "hex");
+    return crypto.createPublicKey({ key: Buffer.concat([prefix, raw]), type: "spki", format: "der" });
+  }
+  throw sdkError("public_key_format_unknown");
+}
+
+// --- handshake ---------------------------------------------------------------------
+
+function challengeSignedBody(challenge) {
+  return Object.fromEntries(CHALLENGE_SIGNED_FIELDS.map((field) => [field, challenge[field]]));
+}
+
+function verifyOwnerSignature(challenge, ownerPublicKey) {
+  if (!challenge || !VALID_CHALLENGE_SCHEMAS.has(challenge.schema)) throw sdkError("challenge_schema_mismatch");
+  const key = loadPublicKey(ownerPublicKey);
+  const ok = crypto.verify(null, canonicalJson(challengeSignedBody(challenge)), key, b64urlDecode(challenge.owner_signature));
+  if (!ok) throw sdkError("owner_signature_invalid");
+  return true;
+}
+
+// --- envelope ------------------------------------------------------------------------
+
+function envelopeDigest(envelope) {
+  const body = Object.fromEntries(Object.entries(envelope).filter(([k]) => k !== "digest" && k !== "sender_signature"));
+  return crypto.createHash("sha256").update(canonicalJson(body)).digest("hex");
+}
+
+function buildEnvelope(identity, kind, payload, { ttlSeconds = 900, now = Math.floor(Date.now() / 1000) } = {}) {
+  if (!identity || !identity.kind || !identity.value) throw sdkError("identity_required");
+  if (!ENVELOPE_KINDS.has(kind)) throw sdkError("envelope_kind_unknown");
+  if (!payload || typeof payload !== "object" || Array.isArray(payload) || Object.keys(payload).length === 0) throw sdkError("envelope_payload_empty");
+  const at = Math.floor(now);
+  const envelope = {
+    schema: ENVELOPE_SCHEMA,
+    envelope_id: crypto.randomUUID(),
+    sender: { kind: String(identity.kind), value: String(identity.value) },
+    kind,
+    authority: "none",
+    payload: JSON.parse(JSON.stringify(payload)),
+    provenance: Object.fromEntries(Object.keys(payload).map((field) => [field, { origin: "counterparty", treat_as: "data", at }])),
+    nonce: crypto.randomBytes(16).toString("hex"),
+    issued_at: at,
+    deadline: at + Math.floor(ttlSeconds),
+  };
+  envelope.digest = envelopeDigest(envelope);
+  return envelope;
+}
+
+function signEnvelope(envelope, privateKey) {
+  const body = Object.fromEntries(Object.entries(envelope).filter(([k]) => k !== "sender_signature"));
+  const signed = JSON.parse(JSON.stringify(body));
+  signed.sender_signature = {
+    schema: SIGNATURE_SCHEMA,
+    key_id: keyId(crypto.createPublicKey(privateKey)),
+    value: b64url(crypto.sign(null, canonicalJson(body), privateKey)),
+  };
+  return signed;
+}
+
+// --- the agent -------------------------------------------------------------------------
+
+function createCounterpartyAgent({ identity, keyPath, privateKeyPem, now = () => Math.floor(Date.now() / 1000) } = {}) {
+  if (!identity || !identity.kind || !identity.value) throw sdkError("identity_required");
+  const privateKey = loadPrivateKey({ keyPath, privateKeyPem });
+  const publicKey = crypto.createPublicKey(privateKey);
+  const self = {
+    identity: { kind: String(identity.kind), value: String(identity.value) },
+    keyId: keyId(publicKey),
+    publicKey: (format = "compact") => exportPublicKey(publicKey, format),
+
+    // Step 1 of the handshake is the owner's; the counterparty's part is to
+    // check who is asking, then sign exactly what the owner published.
+    answerChallenge(challenge, { ownerPublicKey, signPayload } = {}) {
+      if (!challenge || !VALID_CHALLENGE_SCHEMAS.has(challenge.schema)) throw sdkError("challenge_schema_mismatch");
+      if (challenge.counterparty_key_id !== self.keyId) throw sdkError("challenge_key_mismatch");
+      const id = challenge.identity || {};
+      if (String(id.kind) !== self.identity.kind.toLowerCase() || String(id.value) !== self.identity.value) throw sdkError("challenge_identity_mismatch");
+      const at = now();
+      if (!(at <= Number(challenge.expires_at))) throw sdkError("challenge_expired");
+      if (ownerPublicKey) verifyOwnerSignature(challenge, ownerPublicKey);
+      if (!signPayload) throw sdkError("sign_payload_required");
+      return { handshake_id: challenge.handshake_id, signature: b64url(crypto.sign(null, b64urlDecode(signPayload), privateKey)) };
+    },
+
+    buildEnvelope: (kind, payload, options = {}) => buildEnvelope(self.identity, kind, payload, { ...options, now: options.now ?? now() }),
+    signEnvelope: (envelope) => signEnvelope(envelope, privateKey),
+    envelope: (kind, payload, options = {}) => signEnvelope(buildEnvelope(self.identity, kind, payload, { ...options, now: options.now ?? now() }), privateKey),
+
+    // Full flow when a transport to the owner's routes is available.
+    async handshake(transport) {
+      const opened = await transport.post("/api/site_agents/v1/inbox/kya/challenge", { identity: self.identity, public_key: self.publicKey("pem") });
+      const answer = self.answerChallenge(opened.challenge, { ownerPublicKey: opened.owner_public_key, signPayload: opened.sign_payload });
+      return transport.post("/api/site_agents/v1/inbox/kya/complete", answer);
+    },
+    async submit(transport, kind, payload, { idempotencyKey, minimumTier = "G1", ttlSeconds } = {}) {
+      if (!idempotencyKey) throw sdkError("idempotency_key_required");
+      const envelope = self.envelope(kind, payload, { ttlSeconds });
+      return transport.post("/api/site_agents/v1/inbox/submit", { envelope, idempotency_key: idempotencyKey, minimum_tier: minimumTier });
+    },
+  };
+  return self;
+}
+
+// A transport that speaks to the owner's routes with the owner's access
+// token. Only meaningful when the same operator runs both ends.
+function createRelayTransport({ serviceOrigin, accessToken, fetch: fetcher = globalThis.fetch } = {}) {
+  const origin = String(serviceOrigin || "").replace(/\/+$/, "");
+  if (!origin) throw sdkError("service_origin_required");
+  return {
+    async post(pathname, body) {
+      const token = typeof accessToken === "function" ? await accessToken() : accessToken;
+      const response = await fetcher(origin + pathname, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: "Bearer " + token },
+        body: JSON.stringify(body),
+      });
+      const payload = await response.json();
+      if (!response.ok || payload.ok === false) {
+        const error = sdkError(payload && payload.error ? payload.error : `inbox_http_${response.status}`);
+        error.verdict = payload && payload.verdict;
+        throw error;
+      }
+      return payload;
+    },
+  };
+}
+
+module.exports = {
+  createCounterpartyAgent,
+  createRelayTransport,
+  buildEnvelope,
+  signEnvelope,
+  envelopeDigest,
+  verifyOwnerSignature,
+  loadPublicKey,
+  exportPublicKey,
+  keyId,
+  canonicalJson,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twin3-ai/agent-id",
-  "version": "0.3.48",
+  "version": "0.3.49",
   "description": "Domain-bound AgentX portable alias, AEO evidence, and website-Agent integration SDK.",
   "license": "UNLICENSED",
   "private": false,
@@ -20,7 +20,7 @@
     "npm": ">=10"
   },
   "scripts": {
-    "prepublishOnly": "node --check bin/agent-id.js && node --check bin/agent-id-cloudflare-a1.js && node --check bin/agent-id-b1-sync.js && node --check installer.js && node --check enterprise-identity.js && node --check domain-proof.js && node --check release-verifier.js && node --check production-preflight.js && node --check static-edge-adapter.js && node --check edge-html-injection.js && node --check optimization-loop.js && node --check artifact-bundle.js && node --check cloudflare-a1-sync.js && node --check b1-sync.js"
+    "prepublishOnly": "node --check bin/agent-id.js && node --check bin/agent-id-cloudflare-a1.js && node --check bin/agent-id-b1-sync.js && node --check installer.js && node --check enterprise-identity.js && node --check inbox-counterparty.js && node --check domain-proof.js && node --check release-verifier.js && node --check production-preflight.js && node --check static-edge-adapter.js && node --check edge-html-injection.js && node --check optimization-loop.js && node --check artifact-bundle.js && node --check cloudflare-a1-sync.js && node --check b1-sync.js"
   },
   "main": "site-agent.js",
   "exports": {
@@ -31,6 +31,7 @@
     "./sync-service": "./sync-service.js",
     "./installer": "./installer.js",
     "./enterprise-identity": "./enterprise-identity.js",
+    "./inbox-counterparty": "./inbox-counterparty.js",
     "./domain-proof": "./domain-proof.js",
     "./local-policy": "./local-policy.js",
     "./task-executor": "./task-executor.js",