@a2a-exposed/encryption 0.0.0-stage → 0.8.56

package/native-store.mjs

@@ -0,0 +1,55 @@
+// Bounded native child protocol. Secrets travel only through local pipes, never argv/env.
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+export class NativeStoreError extends Error {
+ constructor(code, pid) { super(code); this.code = code; if (pid) this.pid = pid; }
+}
+export async function nativeCredentialOperation(input, { allowOsConsent = false, onSpawn, spawnImpl = spawn, timeoutMs = 5000, graceMs = 500, platform = process.platform } = {}) {
+ if (allowOsConsent !== true) throw new NativeStoreError("key_store_consent");
+ if (!["get", "set", "delete"].includes(input?.op) || !/^[a-f0-9-]{36}$/.test(input.namespace || "") || !/^[a-f0-9-]{36}\/[A-Za-z0-9_-]{43}$/.test(input.account || "")) throw new NativeStoreError("key_store_inputs");
+ const body = JSON.stringify(input); if (Buffer.byteLength(body) > 16384) throw new NativeStoreError("key_store_inputs");
+ const write = input.op !== "get";
+ return new Promise((resolve, reject) => {
+  let child, output = "", done = false, exited = false, stopping, timer, escalation, reap;
+  const unavailable = () => new NativeStoreError(write ? "native_outcome_unknown" : "key_store_unavailable", child?.pid);
+  function finish(error, value) {
+   if (done) return; done = true; clearTimeout(timer); clearTimeout(escalation); clearTimeout(reap);
+   child?.stdin?.destroy(); child?.stdout?.destroy();
+   if (error?.code === "native_process_unreaped") child?.unref?.();
+   error ? reject(error) : resolve(value);
+  }
+  function stop(error = unavailable()) {
+   if (done || stopping) return; stopping = error;
+   child?.stdin?.destroy();
+   try { child?.kill(platform === "win32" ? "SIGKILL" : "SIGTERM"); } catch {}
+   escalation = setTimeout(() => {
+    if (done) return;
+    try { child?.kill("SIGKILL"); } catch {}
+    reap = setTimeout(() => finish(new NativeStoreError("native_process_unreaped", child?.pid)), graceMs);
+   }, graceMs);
+  }
+  try {
+   const env = { PATH: process.env.PATH, ...(process.env.HOME ? { HOME: process.env.HOME } : {}), ...(process.env.DBUS_SESSION_BUS_ADDRESS ? { DBUS_SESSION_BUS_ADDRESS: process.env.DBUS_SESSION_BUS_ADDRESS } : {}), ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}), ...(process.env.USERPROFILE ? { USERPROFILE: process.env.USERPROFILE } : {}) };
+   child = spawnImpl(process.execPath, [fileURLToPath(new URL("./keyring-worker.mjs", import.meta.url))], { stdio: ["pipe", "pipe", "ignore"], windowsHide: true, env });
+   child.on("error", () => { if (!child.pid) finish(new NativeStoreError("key_store_unavailable")); else stop(); });
+   child.on("exit", () => { exited = true; });
+   child.stdout.on("data", chunk => { if (done) return; output += chunk; if (Buffer.byteLength(output) > 16384) stop(); });
+   child.stdin.on("error", () => stop());
+   child.on("close", code => {
+    if (done) return;
+    if (!exited && child.pid) { stop(); return; }
+    if (stopping) { finish(stopping); return; }
+    try {
+     const value = JSON.parse(output);
+     if (code || value.ok !== true || Object.keys(value).some(key => !["ok", "value"].includes(key))) throw Error();
+     if (input.op === "get" && value.value !== null && typeof value.value !== "string") throw Error();
+     finish(null, value.value);
+    } catch { finish(unavailable()); }
+   });
+   timer = setTimeout(() => stop(), timeoutMs);
+   // Durably record the broker PID before giving it private input.
+   onSpawn?.(child.pid);
+   child.stdin.end(body);
+  } catch { if (child?.pid) stop(); else finish(new NativeStoreError("key_store_unavailable")); }
+ });
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@a2a-exposed/encryption",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.56",
+  "description": "Local sealed A2A envelope primitives and key custody for opt-in CLI and stdio MCP encryption.",
+  "type": "module",
+  "exports": {
+    ".": "./index.mjs",
+    "./local-state": "./local-state.mjs",
+    "./backup": "./backup.mjs",
+    "./content": "./content.mjs",
+    "./carriers": "./carriers.mjs",
+    "./assignment": "./assignment.mjs",
+    "./ledger": "./ledger.mjs",
+    "./tasks": "./tasks.mjs",
+    "./transport": "./transport.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md",
+    "LICENSE",
+    "local-state.mjs",
+    "keyring-worker.mjs",
+    "native-store.mjs",
+    "backup.mjs",
+    "LOCAL-CUSTODY-DRAFT.md",
+    "DEPENDENCIES.md",
+    "content.mjs",
+    "carriers.mjs",
+    "schemas/",
+    "assignment.mjs",
+    "ledger.mjs",
+    "tasks.mjs",
+    "transport.mjs"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepack": "node -e \"require('fs').copyFileSync('../LICENSE','LICENSE')\""
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "@hpke/chacha20poly1305": "1.8.1",
+    "@hpke/core": "1.10.1",
+    "@hpke/dhkem-x25519": "1.8.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telegraphic-dev/a2a-exposed.git",
+    "directory": "encryption"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "2.1.2"
+  }
+}

package/schemas/assigned-carrier.schema.json

@@ -0,0 +1,271 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a2a.exposed/ext/sealed/v1/assigned-carrier.schema.json",
+  "description": "Co-carried sealed response and non-null response-bound receipt. Runtime also compares all header bindings and the ciphertext digest before authentication.",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "const": "message"
+        },
+        "messageId": {
+          "type": "string",
+          "pattern": "^[!-~]{1,200}$"
+        },
+        "contextId": {
+          "type": "string",
+          "pattern": "^[!-~]{1,200}$"
+        },
+        "taskId": {
+          "type": "string",
+          "pattern": "^[!-~]{1,200}$"
+        },
+        "role": {
+          "enum": [
+            "user",
+            "agent"
+          ]
+        },
+        "parts": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "items": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "data"
+              },
+              "data": {
+                "$ref": "https://a2a.exposed/ext/sealed/v1/envelope.schema.json",
+                "properties": {
+                  "header": {
+                    "properties": {
+                      "kind": {
+                        "enum": [
+                          "message",
+                          "status"
+                        ]
+                      }
+                    }
+                  }
+                }
+              },
+              "metadata": {
+                "type": "object",
+                "properties": {
+                  "https://a2a.exposed/ext/sealed/v1": {
+                    "type": "object",
+                    "properties": {
+                      "v": {
+                        "const": 1
+                      }
+                    },
+                    "required": [
+                      "v"
+                    ],
+                    "additionalProperties": false
+                  }
+                },
+                "required": [
+                  "https://a2a.exposed/ext/sealed/v1"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "kind",
+              "data",
+              "metadata"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "extensions": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "items": {
+            "const": "https://a2a.exposed/ext/sealed/v1"
+          }
+        },
+        "metadata": {
+          "type": "object",
+          "properties": {
+            "https://a2a.exposed/ext/sealed/v1": {
+              "type": "object",
+              "properties": {
+                "v": {
+                  "const": 1
+                },
+                "assignment": {
+                  "allOf": [
+                    {
+                      "$ref": "https://a2a.exposed/ext/sealed/v1/assignment.schema.json"
+                    },
+                    {
+                      "properties": {
+                        "responseDigest": {
+                          "type": "string",
+                          "pattern": "^[A-Za-z0-9_-]{43}$"
+                        }
+                      }
+                    }
+                  ]
+                }
+              },
+              "required": [
+                "v",
+                "assignment"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "required": [
+            "https://a2a.exposed/ext/sealed/v1"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "kind",
+        "messageId",
+        "contextId",
+        "role",
+        "parts",
+        "extensions",
+        "metadata"
+      ],
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "properties": {
+        "messageId": {
+          "type": "string",
+          "pattern": "^[!-~]{1,200}$"
+        },
+        "contextId": {
+          "type": "string",
+          "pattern": "^[!-~]{1,200}$"
+        },
+        "taskId": {
+          "type": "string",
+          "pattern": "^[!-~]{1,200}$"
+        },
+        "role": {
+          "enum": [
+            "ROLE_USER",
+            "ROLE_AGENT"
+          ]
+        },
+        "parts": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "items": {
+            "type": "object",
+            "properties": {
+              "data": {
+                "$ref": "https://a2a.exposed/ext/sealed/v1/envelope.schema.json",
+                "properties": {
+                  "header": {
+                    "properties": {
+                      "kind": {
+                        "enum": [
+                          "message",
+                          "status"
+                        ]
+                      }
+                    }
+                  }
+                }
+              },
+              "metadata": {
+                "type": "object",
+                "properties": {
+                  "https://a2a.exposed/ext/sealed/v1": {
+                    "type": "object",
+                    "properties": {
+                      "v": {
+                        "const": 1
+                      }
+                    },
+                    "required": [
+                      "v"
+                    ],
+                    "additionalProperties": false
+                  }
+                },
+                "required": [
+                  "https://a2a.exposed/ext/sealed/v1"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "data",
+              "metadata"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "extensions": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "items": {
+            "const": "https://a2a.exposed/ext/sealed/v1"
+          }
+        },
+        "metadata": {
+          "type": "object",
+          "properties": {
+            "https://a2a.exposed/ext/sealed/v1": {
+              "type": "object",
+              "properties": {
+                "v": {
+                  "const": 1
+                },
+                "assignment": {
+                  "allOf": [
+                    {
+                      "$ref": "https://a2a.exposed/ext/sealed/v1/assignment.schema.json"
+                    },
+                    {
+                      "properties": {
+                        "responseDigest": {
+                          "type": "string",
+                          "pattern": "^[A-Za-z0-9_-]{43}$"
+                        }
+                      }
+                    }
+                  ]
+                }
+              },
+              "required": [
+                "v",
+                "assignment"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "required": [
+            "https://a2a.exposed/ext/sealed/v1"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "messageId",
+        "contextId",
+        "role",
+        "parts",
+        "extensions",
+        "metadata"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}

package/schemas/assignment.schema.json

@@ -0,0 +1,73 @@
+{
+  "type": "object",
+  "properties": {
+    "v": {
+      "const": 1
+    },
+    "kind": {
+      "const": "assignment"
+    },
+    "requestDigest": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{43}$"
+    },
+    "from": {
+      "$ref": "https://a2a.exposed/ext/sealed/v1/envelope.schema.json#/properties/header/properties/from"
+    },
+    "to": {
+      "$ref": "https://a2a.exposed/ext/sealed/v1/envelope.schema.json#/properties/header/properties/from"
+    },
+    "contextId": {
+      "type": "string",
+      "pattern": "^[!-~]{1,200}$"
+    },
+    "requestMessageId": {
+      "type": "string",
+      "pattern": "^[!-~]{1,200}$"
+    },
+    "taskId": {
+      "type": "string",
+      "pattern": "^[!-~]{1,200}$"
+    },
+    "responseKind": {
+      "const": "task"
+    },
+    "responseDigest": {
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]{43}$"
+        }
+      ]
+    },
+    "ackId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{86}$"
+    }
+  },
+  "required": [
+    "v",
+    "kind",
+    "requestDigest",
+    "from",
+    "to",
+    "contextId",
+    "requestMessageId",
+    "taskId",
+    "responseKind",
+    "responseDigest",
+    "ackId",
+    "signature"
+  ],
+  "additionalProperties": false,
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a2a.exposed/ext/sealed/v1/assignment.schema.json",
+  "description": "Signed assignment receipt structure. Runtime verifies exact request/task/endpoint binding, canonical bytes and Ed25519 signature; durable acceptance requires the local transaction."
+}

package/schemas/capability.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a2a.exposed/ext/sealed/v1/capability.schema.json",
+  "description": "Discovery shape only. Runtime requires full equality to the current locally approved bundle and a separately approved same-origin RPC endpoint; a card never approves trust. Bundle signatures/key derivation/URLs/dates need runtime checks.",
+  "type": "object",
+  "properties": {
+    "uri": {
+      "const": "https://a2a.exposed/ext/sealed/v1"
+    },
+    "required": {
+      "const": false
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 4096
+    },
+    "params": {
+      "type": "object",
+      "properties": {
+        "bundle": {
+          "type": "object",
+          "properties": {
+            "v": {
+              "const": 1
+            },
+            "suite": {
+              "const": "HPKE-X25519-SHA256-ChaCha20Poly1305"
+            },
+            "cardUrl": {
+              "type": "string",
+              "maxLength": 2048,
+              "pattern": "^https://"
+            },
+            "identityKey": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$"
+            },
+            "encryptionKey": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$"
+            },
+            "keyId": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$"
+            },
+            "notBefore": {
+              "type": "string",
+              "pattern": "^\\d{4}-\\d\\d-\\d\\dT\\d\\d:\\d\\d:\\d\\d\\.\\d{3}Z$"
+            },
+            "signature": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9_-]{85}[AQgw]$"
+            }
+          },
+          "required": [
+            "v",
+            "suite",
+            "cardUrl",
+            "identityKey",
+            "encryptionKey",
+            "keyId",
+            "notBefore",
+            "signature"
+          ],
+          "additionalProperties": false
+        },
+        "responseKind": {
+          "const": "task"
+        }
+      },
+      "required": [
+        "bundle",
+        "responseKind"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "uri",
+    "required",
+    "params"
+  ],
+  "additionalProperties": false
+}