twin3-sdk 0.2.10-pre-alpha → 0.2.11-pre-alpha

package/README.md

@@ -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`.
+The next release candidate is `0.2.11-pre-alpha` for npm and `0.2.11a0` 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`.
 
 `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:
 
 ```bash
-npm install twin3-sdk@0.2.10-pre-alpha
-pip install twin3-sdk==0.2.10a0
+npm install twin3-sdk@0.2.11-pre-alpha
+pip install twin3-sdk==0.2.11a0
 ```
 
 Until publication, evaluate the packed npm tarball only. 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.11-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twin3-sdk",
-  "version": "0.2.10-pre-alpha",
+  "version": "0.2.11-pre-alpha",
   "description": "Universal Capability Motherboard for Autonomous AI Agents and Self-Sovereign Humans (JS/Node runtime)",
   "type": "commonjs",
   "main": "./js/index.js",