twin3-sdk 0.2.10-pre-alpha → 0.2.12-pre-alpha

package/README.md

@@ -1,7 +1,7 @@
 # Twin3 SDK (`twin3-sdk`)
 > **The Universal Capability Motherboard for Autonomous AI Agents & Self-Sovereign Humans**
 
-[English](README.md) | [繁體中文](README_ZH.md) | [GitHub: twin3-team/twin3-sdk](https://github.com/twin3-team/twin3-sdk)
+[English](README.md) | [Traditional Chinese](README_ZH.md) | [GitHub: twin3-team/twin3-sdk](https://github.com/twin3-team/twin3-sdk)
 
 [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
 [![Architecture: 7-Layer Symbiosis](https://img.shields.io/badge/Architecture-7--Layer%20Symbiosis-success.svg)](#the-seven-layer-symbiotic-architecture)
@@ -103,22 +103,22 @@ pip install -e /path/to/twin3-sdk
 * Any protocol or algorithm improvement in `twin3-sdk` is reflected in both applications in **0 milliseconds**.
 
 #### 2. Production Distribution
-The next release candidate is `0.2.10-pre-alpha` for npm and `0.2.10a0` for Python. It is not a production dependency until the GitHub release workflows have built, attested, rehearsed, and published the exact tagged artifacts. Consumers must then pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This candidate stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is `next`, not `latest`.
+`v0.2.12-pre-alpha` is the current release candidate: `0.2.12-pre-alpha` for npm and `0.2.12a0` for PyPI. Publication is pending. Consumers must pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This release stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is `next`, not `latest`.
 
 `package.json` `engines` sets Node.js to `>=18` and does not set an npm engine. Any npm that can install a tarball can consume the package. Packing this repository was checked with npm 10 or newer; the stricter npm version in the release runbook applies only to Trusted Publishing.
 
-After the release workflow has published that exact version, install the pin. These commands are not evidence that the registry already serves the package:
+After publication, install the exact released version from the registry:
 
 ```bash
-npm install twin3-sdk@0.2.10-pre-alpha
-pip install twin3-sdk==0.2.10a0
+npm install twin3-sdk@0.2.12-pre-alpha
+pip install twin3-sdk==0.2.12a0
 ```
 
-Until publication, evaluate the packed npm tarball only. Do not install from a git URL or a version range:
+For local evaluation, you can also use the packed npm tarball. Do not install from a git URL or a version range:
 
 ```bash
 npm pack --ignore-scripts
-npm install ./twin3-sdk-0.2.10-pre-alpha.tgz
+npm install ./twin3-sdk-0.2.12-pre-alpha.tgz
 ```
 
 ---

package/index.d.ts

@@ -375,6 +375,38 @@ export declare const A2A_PROTOCOL_VERSION: "1.0";
 export declare const A2A_DOCUMENT_SUFFIXES: readonly string[];
 export declare const A2A_DISCOVERY_DOCUMENT_PATHS: readonly string[];
 export interface A2AInterface { url: string; protocolBinding: "HTTP+JSON" | "JSONRPC" | "GRPC"; protocolVersion: string; }
+export interface A2AAgentCardSignature {
+  protected: string;
+  signature: string;
+  header?: Record<string, unknown>;
+}
+export interface A2AJwks { keys: import("node:crypto").JsonWebKey[]; }
+export interface A2AAgentCard extends Record<string, any> {
+  name: string;
+  description: string;
+  version: string;
+  supportedInterfaces: A2AInterface[];
+  skills: Record<string, any>[];
+  url?: string;
+  protocolVersion?: string;
+  preferredTransport?: A2AInterface["protocolBinding"];
+  signatures?: A2AAgentCardSignature[];
+  signatureStatus?: string;
+}
+export interface A2ASignatureVerification {
+  status: "signed";
+  mode: "a2a_jcs" | "legacy_signature_status_excluded";
+  kid: string;
+  alg: "EdDSA" | "ES256";
+  jku: string | null;
+  protected: { alg: "EdDSA" | "ES256"; typ: "JOSE"; kid: string; jku?: string; [name: string]: unknown };
+}
+/** Signs every supplied field except signatures; preserves signatureStatus.
+ * privateKey accepts Ed25519/P-256 KeyObject or PEM, or a 32-byte Ed25519 seed. */
+export declare function signA2AAgentCard<T extends Record<string, any>>(card: T, privateKey: string | Buffer | import("node:crypto").KeyObject, kid: string, jku?: string | null): Omit<T, "signatures"> & { signatures: A2AAgentCardSignature[] };
+/** Uses caller-trusted public JWKS, without fetching jku. Unsupported headers,
+ * ambiguous/missing kids and invalid keys are errors even in legacy mode. */
+export declare function verifyA2AAgentCardSignature(card: Record<string, any>, jwks: A2AJwks, options?: { allowLegacy?: boolean }): A2ASignatureVerification;
 export interface A2AValidationReport {
   profile: "twin3-discovery-a2a-card-v1";
   skills: string[];

package/js/index.js

@@ -473,6 +473,7 @@ const A2A_KNOWN_FIELDS = [
   "name", "description", "supportedInterfaces", "provider", "version", "documentationUrl", "iconUrl",
   "capabilities", "securitySchemes", "securityRequirements", "defaultInputModes", "defaultOutputModes",
   "skills", "signatures", "signatureStatus", "models", "authenticatedSubject",
+  "url", "protocolVersion", "preferredTransport",
 ];
 const A2A_DEFAULT_MODES = ["application/json", "text/plain"];
 
@@ -557,8 +558,16 @@ function a2aRequirements(value, schemes, code) {
 
 function validateAgentCardV1(card) {
   if (!card || typeof card !== "object" || Array.isArray(card)) fail("a2a_card_invalid");
-  const legacy = A2A_LEGACY_FIELDS.filter((name) => name in card);
+  const legacy = A2A_LEGACY_FIELDS.filter((name) => name in card && !["url", "preferredTransport"].includes(name));
   if (legacy.length) fail("a2a_legacy_shape:" + legacy[0]);
+  if ("url" in card) {
+    a2aUrl(card.url, "a2a_legacy_shape:url");
+    if (!Array.isArray(card.supportedInterfaces) || !card.supportedInterfaces.some((iface) => iface && iface.url === card.url)) {
+      fail("a2a_legacy_shape:url");
+    }
+  }
+  if ("preferredTransport" in card && !A2A_PROTOCOL_BINDINGS.includes(card.preferredTransport)) fail("a2a_field_invalid:preferredTransport");
+  if ("protocolVersion" in card) a2aText(card.protocolVersion, "a2a_field_invalid:protocolVersion");
   a2aText(card.name, "a2a_field_required:name");
   a2aText(card.description, "a2a_field_required:description");
   a2aText(card.version, "a2a_field_required:version");
@@ -613,6 +622,7 @@ function validateAgentCardV1(card) {
     ids.add(skill.id);
   });
   if ("signatures" in card && !Array.isArray(card.signatures)) fail("a2a_field_invalid:signatures");
+  (card.signatures || []).forEach(a2aSignatureEntry);
   return {
     profile: A2A_CARD_PROFILE,
     skills: Array.from(ids).sort(),
@@ -624,6 +634,150 @@ function validateAgentCardV1(card) {
   };
 }
 
+function a2aSignatureEntry(entry, index) {
+  const code = "a2a_signature_invalid:" + index;
+  if (!entry || typeof entry !== "object" || Array.isArray(entry) ||
+      !Object.hasOwn(entry, "protected") || !Object.hasOwn(entry, "signature") ||
+      Object.keys(entry).some((name) => !["protected", "signature", "header"].includes(name))) fail(code);
+  strictB64urlDecode(entry.protected, code);
+  strictB64urlDecode(entry.signature, code);
+  if (Object.hasOwn(entry, "header") && (!entry.header || typeof entry.header !== "object" || Array.isArray(entry.header))) fail(code);
+}
+
+function a2aSignatureBody(card) {
+  if (!card || typeof card !== "object" || Array.isArray(card)) fail("a2a_card_invalid");
+  const body = structuredClone(card);
+  delete body.signatures;
+  return body;
+}
+
+function a2aSignaturePayload(body) {
+  try {
+    return canonicalJsonBuffer(body);
+  } catch (error) {
+    fail("a2a_not_canonicalizable", error);
+  }
+}
+
+function a2aSigningInput(protectedB64, payload) {
+  return Buffer.from(protectedB64 + "." + payload.toString("base64url"), "ascii");
+}
+
+function a2aPrivateKey(value) {
+  let key;
+  try {
+    if (Buffer.isBuffer(value) && value.length === 32) {
+      key = crypto.createPrivateKey({
+        key: Buffer.concat([Buffer.from("302e020100300506032b657004220420", "hex"), value]),
+        format: "der", type: "pkcs8",
+      });
+    } else {
+      key = value instanceof crypto.KeyObject ? value : crypto.createPrivateKey(value);
+    }
+  } catch (error) {
+    fail("a2a_private_key_invalid", error);
+  }
+  if (key.type !== "private") fail("a2a_private_key_invalid");
+  if (key.asymmetricKeyType === "ed25519") return { key, alg: "EdDSA" };
+  if (key.asymmetricKeyType === "ec" && key.asymmetricKeyDetails.namedCurve === "prime256v1") return { key, alg: "ES256" };
+  fail("a2a_private_key_invalid");
+}
+
+/** A2A §8.4 detached JWS. Only signatures is excluded; no status is added. */
+function signA2AAgentCard(card, privateKey, kid, jku = null) {
+  const { key, alg } = a2aPrivateKey(privateKey);
+  a2aText(kid, "a2a_kid_required");
+  const header = { alg, typ: "JOSE", kid };
+  if (jku !== null) {
+    a2aUrl(jku, "a2a_jku_invalid");
+    if (!jku.startsWith("https://")) fail("a2a_jku_invalid");
+    header.jku = jku;
+  }
+  const body = a2aSignatureBody(card);
+  validateAgentCardV1(body);
+  const protectedB64 = canonicalJsonBuffer(header).toString("base64url");
+  const input = a2aSigningInput(protectedB64, a2aSignaturePayload(body));
+  const signature = alg === "EdDSA" ? crypto.sign(null, input, key) :
+    crypto.sign("sha256", input, { key, dsaEncoding: "ieee-p1363" });
+  body.signatures = [{ protected: protectedB64, signature: signature.toString("base64url") }];
+  return body;
+}
+
+function a2aProtectedHeader(entry) {
+  const code = "a2a_protected_invalid";
+  let header;
+  try {
+    header = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(strictB64urlDecode(entry.protected, code)));
+  } catch (error) {
+    fail(code, error);
+  }
+  if (!header || typeof header !== "object" || Array.isArray(header)) fail(code);
+  if (!["EdDSA", "ES256"].includes(header.alg)) fail("a2a_alg_unsupported");
+  a2aText(header.kid, code);
+  if (header.typ !== "JOSE") fail(code);
+  const unprotected = entry.header || {};
+  if (Object.keys(header).some((name) => Object.hasOwn(unprotected, name)) ||
+      [header, unprotected].some((h) => Object.hasOwn(h, "crit") || Object.hasOwn(h, "b64"))) fail(code);
+  if (Object.hasOwn(header, "jku")) {
+    a2aUrl(header.jku, code);
+    if (!header.jku.startsWith("https://")) fail(code);
+  }
+  return header;
+}
+
+function a2aJwksKey(jwks, header) {
+  const matches = jwks.keys.filter((jwk) => jwk.kid === header.kid);
+  if (matches.length === 0) fail("a2a_kid_mismatch");
+  if (matches.length !== 1) fail("a2a_kid_ambiguous");
+  const jwk = matches[0];
+  const code = "a2a_jwk_invalid";
+  if (Object.hasOwn(jwk, "d") || (Object.hasOwn(jwk, "alg") && jwk.alg !== header.alg) ||
+      (Object.hasOwn(jwk, "use") && jwk.use !== "sig")) fail(code);
+  if (Object.hasOwn(jwk, "key_ops") && (!Array.isArray(jwk.key_ops) || !jwk.key_ops.includes("verify") ||
+      jwk.key_ops.some((op) => typeof op !== "string"))) fail(code);
+  const x = strictB64urlDecode(jwk.x, code);
+  if (x.length !== 32) fail(code);
+  if (header.alg === "EdDSA") {
+    if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519") fail(code);
+  } else {
+    if (jwk.kty !== "EC" || jwk.crv !== "P-256" || strictB64urlDecode(jwk.y, code).length !== 32) fail(code);
+  }
+  try {
+    return crypto.createPublicKey({ key: jwk, format: "jwk" });
+  } catch (error) {
+    fail(code, error);
+  }
+}
+
+/** Verify with caller-trusted JWKS; never fetch jku. All standard signatures
+ * are tried before the opt-in signatureStatus-excluded legacy payload. */
+function verifyA2AAgentCardSignature(card, jwks, { allowLegacy = false } = {}) {
+  if (typeof allowLegacy !== "boolean") fail("a2a_options_invalid");
+  validateAgentCardV1(card);
+  if (!card.signatures || card.signatures.length === 0) fail("a2a_signature_required");
+  if (!jwks || typeof jwks !== "object" || Array.isArray(jwks) || !Array.isArray(jwks.keys) ||
+      jwks.keys.some((jwk) => !jwk || typeof jwk !== "object" || Array.isArray(jwk))) fail("a2a_jwks_invalid");
+  const entries = card.signatures.map((entry) => {
+    const header = a2aProtectedHeader(entry);
+    return { protectedB64: entry.protected, header, key: a2aJwksKey(jwks, header),
+      signature: strictB64urlDecode(entry.signature, "a2a_signature_invalid") };
+  });
+  const body = a2aSignatureBody(card);
+  const modes = ["a2a_jcs", ...(allowLegacy ? ["legacy_signature_status_excluded"] : [])];
+  for (const mode of modes) {
+    if (mode === "legacy_signature_status_excluded") delete body.signatureStatus;
+    const payload = a2aSignaturePayload(body);
+    for (const { protectedB64, header, key, signature } of entries) {
+      if (signature.length !== 64) continue;
+      const input = a2aSigningInput(protectedB64, payload);
+      const ok = header.alg === "EdDSA" ? crypto.verify(null, input, key, signature) :
+        crypto.verify("sha256", input, { key, dsaEncoding: "ieee-p1363" }, signature);
+      if (ok) return { status: "signed", mode, kid: header.kid, alg: header.alg, jku: header.jku ?? null, protected: header };
+    }
+  }
+  fail("a2a_signature_invalid");
+}
+
 function agentCardPaths(origin = "") {
   if (typeof origin !== "string") fail("a2a_origin_invalid");
   if (origin) {
@@ -6372,6 +6526,8 @@ module.exports = {
   signDescriptor,
   unsignedDescriptor,
   verifyDescriptor,
+  signA2AAgentCard,
+  verifyA2AAgentCardSignature,
   DESCRIPTOR_CANONICALIZATION,
   DESCRIPTOR_SIGNATURE_FIELDS,
   buildWellKnownDocument,

package/js/local-memory.js

@@ -0,0 +1,64 @@
+"use strict";
+
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+
+function requiredText(value, limit = 1000) {
+  if (typeof value !== "string" || !value.trim() || value.length > limit || value.includes("\0")) throw new TypeError("local_memory_option_invalid");
+  return value;
+}
+
+function startLocalMemory(options) {
+  if (!options || typeof options !== "object") throw new TypeError("local_memory_options_required");
+  const executable = requiredText(options.pythonExecutable);
+  const databasePath = requiredText(options.databasePath);
+  const directory = path.dirname(databasePath);
+  if (!path.isAbsolute(executable) || !path.isAbsolute(databasePath)) throw new TypeError("local_memory_absolute_path_required");
+  if (!["human", "enterprise"].includes(options.namespace)) throw new TypeError("local_memory_namespace_invalid");
+  const subject = requiredText(options.subject, 200);
+  const ontology = requiredText(options.ontology, 200);
+  if (!Array.isArray(options.dimensions) || !options.dimensions.length || options.dimensions.some(value => typeof value !== "string" || !value || value.includes(","))) throw new TypeError("local_memory_dimensions_invalid");
+  const port = options.port ?? 0;
+  if (!Number.isSafeInteger(port) || port < 0 || port > 65535) throw new TypeError("local_memory_port_invalid");
+  const args = ["-I", "-m", "twin3.memory.runtime", "--database", databasePath, "--subject", subject, "--namespace", options.namespace, "--ontology", ontology, "--dimensions", options.dimensions.join(","), "--port", String(port)];
+  if (options.model) args.push("--model", requiredText(options.model, 200));
+  if (options.embeddingModel) args.push("--embedding-model", requiredText(options.embeddingModel, 200));
+  if (options.modelEndpoint) args.push("--model-endpoint", requiredText(options.modelEndpoint, 200));
+  const child = spawn(executable, args, { shell: false, stdio: ["ignore", "pipe", "pipe"] });
+  return new Promise((resolve, reject) => {
+    let stdout = "";
+    let settled = false;
+    const timer = setTimeout(() => fail("local_memory_start_timeout"), 15000);
+    function fail(code) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.kill("SIGINT");
+      reject(new Error(code));
+    }
+    child.stderr.on("data", () => {});
+    child.on("error", () => fail("local_memory_runtime_unavailable"));
+    child.on("exit", () => fail("local_memory_runtime_unavailable"));
+    child.stdout.on("data", chunk => {
+      if (settled) return;
+      stdout += chunk.toString("utf8");
+      if (stdout.length > 16384) return fail("local_memory_start_invalid");
+      if (!stdout.includes("\n")) return;
+      try {
+        const result = JSON.parse(stdout.split("\n")[0]);
+        const url = new URL(result.url);
+        if (result.capability !== "memory.local-v1" || result.identity_assurance !== "local_workspace_only" || url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port || url.pathname !== "/" || url.search || url.hash || url.username || url.password || typeof result.token_file !== "string" || path.dirname(fs.realpathSync(result.token_file)) !== fs.realpathSync(directory) || path.basename(result.token_file) !== `session-${url.port}.token`) return fail("local_memory_start_invalid");
+        settled = true;
+        clearTimeout(timer);
+        child.stdout.removeAllListeners("data");
+        child.stdout.resume();
+        resolve({ url: result.url, tokenFile: result.token_file, identityAssurance: result.identity_assurance, process: child, stop: () => child.kill("SIGINT") });
+      } catch {
+        fail("local_memory_start_invalid");
+      }
+    });
+  });
+}
+
+module.exports = { startLocalMemory };

package/local-memory.d.ts

@@ -0,0 +1,22 @@
+export interface LocalMemoryOptions {
+  pythonExecutable: string;
+  databasePath: string;
+  namespace: "enterprise" | "human";
+  subject: string;
+  ontology: string;
+  dimensions: string[];
+  port?: number;
+  model?: string;
+  embeddingModel?: string;
+  modelEndpoint?: string;
+}
+
+export interface LocalMemoryProcess {
+  url: string;
+  tokenFile: string;
+  identityAssurance: "local_workspace_only";
+  process: import("node:child_process").ChildProcess;
+  stop(): boolean;
+}
+
+export function startLocalMemory(options: LocalMemoryOptions): Promise<LocalMemoryProcess>;

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "twin3-sdk",
-  "version": "0.2.10-pre-alpha",
+  "version": "0.2.12-pre-alpha",
   "description": "Universal Capability Motherboard for Autonomous AI Agents and Self-Sovereign Humans (JS/Node runtime)",
   "type": "commonjs",
   "main": "./js/index.js",
   "types": "./index.d.ts",
   "exports": {
+    "./local-memory": {
+      "types": "./local-memory.d.ts",
+      "require": "./js/local-memory.js",
+      "default": "./js/local-memory.js"
+    },
     ".": {
       "types": "./index.d.ts",
       "require": "./js/index.js",
@@ -19,6 +24,8 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "js/local-memory.js",
+    "local-memory.d.ts",
     "js/index.js",
     "js/comm/counterparty.js",
     "js/state.js",