@a2a-exposed/encryption 0.0.0-stage → 0.8.55

package/carriers.mjs

@@ -0,0 +1,45 @@
+// Structural carrier validation only. Signature, trust, replay and assignment validation are separate gates.
+import {createHash}from'node:crypto';
+import {validateAssignmentStructure}from'./assignment.mjs';
+import {EXTENSION,canonicalJSON,parseJSON,EncryptionError,validateEnvelopeStructure} from './index.mjs';
+const fail=()=>{throw new EncryptionError('carrier_invalid');};
+const fields=(value,names)=>value&&typeof value==='object'&&!Array.isArray(value)&&Object.keys(value).sort().join('\0')===[...names].sort().join('\0');
+const id=value=>typeof value==='string'&&/^[\x21-\x7e]{1,200}$/.test(value);
+function headerBinding(envelope){
+ if(!fields(envelope,['v','suite','header','recipient','sender','signature']))fail();const h=envelope.header;
+ if(!h||!id(h.contextId)||!id(h.messageId)||(h.taskId!==null&&!id(h.taskId))||!['user','agent'].includes(h.role)||!['message','status'].includes(h.kind))fail();
+ return h;
+}
+export function makeMessageCarrier(envelope,version){
+ if(!['0.3','1.0'].includes(version))fail();const copy=validateEnvelopeStructure(envelope),h=headerBinding(copy);
+ const result={...(version==='0.3'?{kind:'message'}:{}),messageId:h.messageId,contextId:h.contextId,...(h.taskId===null?{}:{taskId:h.taskId}),role:version==='0.3'?h.role:h.role==='agent'?'ROLE_AGENT':'ROLE_USER',parts:[{...(version==='0.3'?{kind:'data'}:{}),data:copy,metadata:{[EXTENSION]:{v:1}}}],extensions:[EXTENSION]};
+ if(Buffer.byteLength(canonicalJSON(result))>1024*1024)fail();return result;
+}
+export function readMessageCarrier(text,version){
+ if(typeof text!=='string'||!['0.3','1.0'].includes(version))fail();const carrier=parseJSON(text),names=['messageId','contextId','role','parts','extensions',...(version==='0.3'?['kind']:[]),...(carrier?.taskId===undefined?[]:['taskId'])];
+ if(!fields(carrier,names)||(version==='0.3'&&carrier.kind!=='message')||!Array.isArray(carrier.parts)||carrier.parts.length!==1||!Array.isArray(carrier.extensions)||carrier.extensions.length!==1||carrier.extensions[0]!==EXTENSION)fail();
+ const part=carrier.parts[0];if(!fields(part,['data','metadata',...(version==='0.3'?['kind']:[])])||(version==='0.3'&&part.kind!=='data')||!fields(part.metadata,[EXTENSION])||!fields(part.metadata[EXTENSION],['v'])||part.metadata[EXTENSION].v!==1)fail();
+ if(Object.hasOwn(carrier,'taskId')&&!id(carrier.taskId))fail();
+ const envelope=validateEnvelopeStructure(part.data),h=headerBinding(envelope),role=version==='0.3'?h.role:h.role==='agent'?'ROLE_AGENT':'ROLE_USER';
+ if(carrier.messageId!==h.messageId||carrier.contextId!==h.contextId||(carrier.taskId??null)!==h.taskId||carrier.role!==role)fail();return envelope;
+}
+
+// Assignment-bearing variants never silently discard their control receipt.
+export function makeReceiptCarrier(receipt,version){
+ if(!['0.3','1.0'].includes(version))fail();const value=validateAssignmentStructure(receipt);if(value.responseDigest!==null)fail();
+ return {...(version==='0.3'?{kind:'message'}:{}),messageId:value.ackId,contextId:value.contextId,taskId:value.taskId,role:version==='0.3'?'agent':'ROLE_AGENT',parts:[{...(version==='0.3'?{kind:'text'}:{}),text:'[encrypted request accepted]'}],extensions:[EXTENSION],metadata:{[EXTENSION]:{v:1,assignment:value}}};
+}
+export function readReceiptCarrier(text,version){
+ if(typeof text!=='string')fail();const value=parseJSON(text);if(!fields(value,['messageId','contextId','taskId','role','parts','extensions','metadata',...(version==='0.3'?['kind']:[])])||!fields(value.metadata,[EXTENSION])||!fields(value.metadata[EXTENSION],['v','assignment'])||value.metadata[EXTENSION].v!==1)fail();
+ const receipt=validateAssignmentStructure(value.metadata[EXTENSION].assignment),expected=makeReceiptCarrier(receipt,version);if(canonicalJSON(value)!==canonicalJSON(expected))fail();return receipt;
+}
+function assignedBindings(envelope,receipt){
+ const h=envelope.header;if(receipt.responseDigest===null||receipt.responseDigest!==createHash('sha256').update(canonicalJSON(envelope)).digest('base64url')||canonicalJSON(receipt.from)!==canonicalJSON(h.from)||canonicalJSON(receipt.to)!==canonicalJSON(h.to)||receipt.contextId!==h.contextId||receipt.taskId!==h.taskId||h.role!=='agent')fail();
+}
+export function makeAssignedCarrier(envelope,receipt,version){
+ const carrier=makeMessageCarrier(envelope,version),value=validateAssignmentStructure(receipt);assignedBindings(carrier.parts[0].data,value);carrier.metadata={[EXTENSION]:{v:1,assignment:value}};if(Buffer.byteLength(canonicalJSON(carrier))>1024*1024)fail();return carrier;
+}
+export function readAssignedCarrier(text,version){
+ if(typeof text!=='string')fail();const value=parseJSON(text);if(!value||typeof value!=='object'||Array.isArray(value))fail();if(!fields(value.metadata,[EXTENSION])||!fields(value.metadata[EXTENSION],['v','assignment'])||value.metadata[EXTENSION].v!==1)fail();
+ const receipt=validateAssignmentStructure(value.metadata[EXTENSION].assignment),{metadata,...rest}=value,envelope=readMessageCarrier(canonicalJSON(rest),version);assignedBindings(envelope,receipt);return {envelope,receipt};
+}

package/content.mjs

@@ -0,0 +1,82 @@
+// Lossless supported-part mapping and exact decrypted-content validation.
+// Validation is not replay authorization or model delivery; trust/ledger gates remain required.
+import {canonicalJSON,parseJSON,EncryptionError,MAX_PLAINTEXT} from './index.mjs';
+const refuse=code=>{throw new EncryptionError(code||'content_unsupported');};
+const object=value=>value&&typeof value==='object'&&!Array.isArray(value)&&Object.getPrototypeOf(value)===Object.prototype;
+const exact=(value,keys)=>object(value)&&Object.keys(value).sort().join('\0')===[...keys].sort().join('\0');
+const optional=(value,required,allowed)=>object(value)&&required.every(key=>Object.hasOwn(value,key))&&Object.keys(value).every(key=>allowed.includes(key));
+const string=(value,max)=>typeof value==='string'&&[...value].length<=max;
+const nullable=(value,max)=>value===null||string(value,max);
+const id=value=>typeof value==='string'&&/^[\x21-\x7e]{1,200}$/.test(value);
+const digest=value=>typeof value==='string'&&/^[A-Za-z0-9_-]{43}$/.test(value)&&Buffer.from(value,'base64url').toString('base64url')===value;
+const states=['submitted','working','input-required','completed','failed','canceled','rejected','auth-required'];
+const terminal=new Set(['completed','failed','canceled','rejected']);
+function base64(value){return typeof value==='string'&&Buffer.from(value,'base64').toString('base64')===value;}
+function metadata(value){if(!object(value))refuse();}
+function parts(values){
+ if(!Array.isArray(values)||values.length<1||values.length>100)refuse();
+ for(const part of values){
+  if(!object(part)||!nullable(part.mediaType,256))refuse();metadata(part.metadata);
+  if(part.kind==='text'){if(!exact(part,['kind','text','mediaType','metadata'])||!string(part.text,200000))refuse();}
+  else if(part.kind==='data'){if(!exact(part,['kind','data','mediaType','metadata'])||!object(part.data))refuse();}
+  else if(part.kind==='file'){if(!exact(part,['kind','file','mediaType','metadata'])||!exact(part.file,['name','bytes'])||!nullable(part.file.name,512)||!base64(part.file.bytes))refuse();}
+  else refuse();
+ }
+}
+function strings(value,max,predicate){if(!Array.isArray(value)||value.length>max||value.some(x=>!predicate(x)))refuse();}
+function message(value){
+ if(!exact(value,['kind','authorRole','parts','metadata','extensions','referenceTaskIds',...(value?.authorRole==='agent'?['requestDigest']:[])])||value.kind!=='message'||!['user','agent'].includes(value.authorRole))refuse();
+ if(value.authorRole==='agent'&&!digest(value.requestDigest))refuse('request_binding_required');
+ parts(value.parts);metadata(value.metadata);strings(value.extensions,100,x=>string(x,4096)&&x.length>0);strings(value.referenceTaskIds,100,id);
+}
+export function validateContent(value,header,{expectedRequestDigest}={}){
+ try{
+  const text=canonicalJSON(value);if(Buffer.byteLength(text)>MAX_PLAINTEXT-128)refuse('content_too_large');
+  if(!object(header)||!['user','agent'].includes(header.role)||!id(header.contextId)||!id(header.messageId)||(header.taskId!==null&&!id(header.taskId)))refuse();
+  if(header.taskId===null&&(header.role!=='user'||header.kind!=='message'))refuse();
+  if(header.kind==='message'){
+   message(value);if(header.state!==null||value.authorRole!==header.role)refuse('message_role_unsupported');
+  }else if(header.kind==='status'){
+   if(!exact(value,['kind','authorRole','revision','previousDigest','state','statusMessage','artifacts','metadata','terminal',...(value?.authorRole==='agent'?['requestDigest']:[])])||value.kind!=='snapshot'||value.authorRole!==header.role||header.taskId===null||!states.includes(value.state)||value.state!==header.state||value.terminal!==terminal.has(value.state)||!Number.isSafeInteger(value.revision)||value.revision<0||(value.revision===0?value.previousDigest!==null:!digest(value.previousDigest)))refuse();
+   if(value.authorRole==='agent'&&!digest(value.requestDigest))refuse('request_binding_required');
+   if(value.statusMessage!==null){message(value.statusMessage);if(value.statusMessage.authorRole!==value.authorRole||(value.authorRole==='agent'&&value.statusMessage.requestDigest!==value.requestDigest))refuse();}
+   metadata(value.metadata);if(!Array.isArray(value.artifacts)||value.artifacts.length>100)refuse();const seen=new Set();
+   for(const artifact of value.artifacts){if(!exact(artifact,['artifactId','name','description','parts','metadata','extensions'])||!id(artifact.artifactId)||seen.has(artifact.artifactId)||!nullable(artifact.name,512)||!nullable(artifact.description,4000))refuse();seen.add(artifact.artifactId);parts(artifact.parts);metadata(artifact.metadata);strings(artifact.extensions,100,x=>string(x,4096)&&x.length>0);}
+  }else refuse('content_kind_unsupported');
+  if(expectedRequestDigest!==undefined&&value.requestDigest!==expectedRequestDigest)refuse('request_binding_mismatch');
+  return parseJSON(text);
+ }catch(error){if(error instanceof EncryptionError)throw error;refuse();}
+}
+export function fromProtocolParts(value,version){
+ try{
+  // Clone/validate JSON representation before touching values; never execute getters.
+  const raw=parseJSON(canonicalJSON(value));if(!['0.3','1.0'].includes(version)||!Array.isArray(raw)||raw.length<1||raw.length>100)refuse();
+  const mapped=raw.map(part=>{
+   let kind;if(version==='0.3')kind=part?.kind;else if(object(part)){const choices=['text','data','raw','url'].filter(key=>Object.hasOwn(part,key));if(choices.length!==1)refuse();kind=choices[0]==='raw'||choices[0]==='url'?'file':choices[0];}
+   if(object(part)&&Object.hasOwn(part,'mediaType')&&typeof part.mediaType!=='string')refuse();
+   const common={kind,mediaType:part?.mediaType??null,metadata:part?.metadata===undefined?{}:part.metadata};
+   if(kind==='text'){if(!optional(part,version==='0.3'?['kind','text']:['text'],version==='0.3'?['kind','text','mediaType','metadata']:['text','mediaType','metadata']))refuse();return {...common,text:part.text};}
+   if(kind==='data'){if(!optional(part,version==='0.3'?['kind','data']:['data'],version==='0.3'?['kind','data','mediaType','metadata']:['data','mediaType','metadata']))refuse();return {...common,data:part.data};}
+   if(kind==='file'){
+    if(version==='0.3'){
+     if(!optional(part,['kind','file'],['kind','file','metadata'])||!optional(part.file,['bytes'],['bytes','name','mimeType']))refuse('file_uri_unsupported');
+     for(const key of ['name','mimeType'])if(Object.hasOwn(part.file,key)&&typeof part.file[key]!=='string')refuse();
+     return {...common,mediaType:part.file.mimeType??null,file:{name:part.file.name??null,bytes:part.file.bytes}};
+    }
+    if(!optional(part,['raw'],['raw','filename','mediaType','metadata']))refuse('file_uri_unsupported');if(Object.hasOwn(part,'filename')&&typeof part.filename!=='string')refuse();return {...common,file:{name:part.filename??null,bytes:part.raw}};
+   }
+   refuse();
+  });
+  parts(mapped);return mapped;
+ }catch(error){if(error instanceof EncryptionError)throw error;refuse();}
+}
+export function toProtocolParts(value,version){
+ try{
+  const copy=parseJSON(canonicalJSON(value));parts(copy);if(!['0.3','1.0'].includes(version))refuse();
+  return copy.map(part=>{
+   const meta={metadata:part.metadata};
+   if(part.kind==='file')return version==='0.3'?{kind:'file',file:{bytes:part.file.bytes,...(part.file.name===null?{}:{name:part.file.name}),...(part.mediaType===null?{}:{mimeType:part.mediaType})},...meta}:{raw:part.file.bytes,...(part.file.name===null?{}:{filename:part.file.name}),...(part.mediaType===null?{}:{mediaType:part.mediaType}),...meta};
+   return {...(version==='0.3'?{kind:part.kind}:{}),[part.kind]:part[part.kind],...(part.mediaType===null?{}:{mediaType:part.mediaType}),...meta};
+  });
+ }catch(error){if(error instanceof EncryptionError)throw error;refuse();}
+}

package/index.mjs

@@ -0,0 +1,230 @@
+// Local-only primitives for a review-draft extension. No transport/key storage is enabled here.
+import { CipherSuite, HkdfSha256 } from "@hpke/core";
+import { DhkemX25519HkdfSha256 } from "@hpke/dhkem-x25519";
+import { Chacha20Poly1305 } from "@hpke/chacha20poly1305";
+
+export const EXTENSION = "https://a2a.exposed/ext/sealed/v1";
+export const SUITE = "HPKE-X25519-SHA256-ChaCha20Poly1305";
+export const MAX_PLAINTEXT = 300 * 1024;
+const encoder = new TextEncoder(), decoder = new TextDecoder("utf-8", { fatal: true });
+const suite = new CipherSuite({ kem: new DhkemX25519HkdfSha256(), kdf: new HkdfSha256(), aead: new Chacha20Poly1305() });
+const encode = value => encoder.encode(value);
+const b64 = bytes => Buffer.from(bytes).toString("base64url");
+export class EncryptionError extends Error {
+ constructor(code) { super(code); this.name = "EncryptionError"; this.code = code; }
+}
+const refuse = (code = "verification_failed") => { throw new EncryptionError(code); };
+function raw(value, length) {
+ if (typeof value !== "string" || value.length > Math.ceil((length ?? (MAX_PLAINTEXT + 16)) * 4 / 3) || !/^[A-Za-z0-9_-]+$/.test(value)) refuse();
+ const bytes = Buffer.from(value, "base64url");
+ if (b64(bytes) !== value || (length !== undefined && bytes.length !== length)) refuse();
+ return new Uint8Array(bytes);
+}
+function fields(value, names) {
+ if (!value || typeof value !== "object" || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype) refuse();
+ const keys = Object.keys(value).sort();
+ if (keys.join("\0") !== [...names].sort().join("\0")) refuse();
+}
+function validString(value) {
+ if (typeof value !== "string") refuse();
+ for (const char of value) { const point = char.codePointAt(0); if (point >= 0xd800 && point <= 0xdfff) refuse(); }
+}
+export function canonicalJSON(value, depth = 0) {
+ if (depth > 32) refuse("content_unsupported");
+ if (value === null || typeof value === "boolean") return JSON.stringify(value);
+ if (typeof value === "string") { validString(value); return JSON.stringify(value); }
+ if (typeof value === "number") { if (!Number.isFinite(value)) refuse("content_unsupported"); return JSON.stringify(value); }
+ if (Array.isArray(value)) {
+  if (Object.getPrototypeOf(value) !== Array.prototype || Reflect.ownKeys(value).length !== value.length + 1) refuse("content_unsupported");
+  const items = [];
+  for (let index = 0; index < value.length; index++) {
+   const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+   if (!descriptor || !("value" in descriptor)) refuse("content_unsupported");
+   items.push(canonicalJSON(descriptor.value, depth + 1));
+  }
+  return "[" + items.join(",") + "]";
+ }
+ if (!value || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype || Reflect.ownKeys(value).length !== Object.keys(value).length) refuse("content_unsupported");
+ return "{" + Object.keys(value).sort().map(key => {
+  validString(key); const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  if (!descriptor || !("value" in descriptor)) refuse("content_unsupported");
+  return JSON.stringify(key) + ":" + canonicalJSON(descriptor.value, depth + 1);
+ }).join(",") + "}";
+}
+// JSON.parse first establishes grammar. Then a bounded token walk rejects duplicate members
+// before normalisation could erase a signed/unsigned disagreement.
+export function parseJSON(text, maxBytes = 1024 * 1024) {
+ if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 32 * 1024 * 1024) refuse("content_too_large");
+ if (typeof text !== "string" || Buffer.byteLength(text) > maxBytes) refuse("content_too_large");
+ let value; try { value = JSON.parse(text); } catch { refuse(); }
+ const tokens = text.match(/"(?:[^"\\]|\\.)*"|[{}\[\]:,]|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null/g) || [];
+ let offset = 0;
+ function walk(depth) {
+  if (depth > 32) refuse("content_unsupported");
+  const token = tokens[offset++];
+  if (token === "{") {
+   const seen = new Set();
+   if (tokens[offset] === "}") { offset++; return; }
+   for (;;) {
+    const key = JSON.parse(tokens[offset++]); if (seen.has(key)) refuse(); seen.add(key);
+    offset++; walk(depth + 1);
+    if (tokens[offset++] === "}") return;
+   }
+  }
+  if (token === "[") {
+   if (tokens[offset] === "]") { offset++; return; }
+   for (;;) { walk(depth + 1); if (tokens[offset++] === "]") return; }
+  }
+ }
+ walk(0); canonicalJSON(value); return value;
+}
+const digest = async bytes => b64(await crypto.subtle.digest("SHA-256", bytes));
+const sign = async (key, bytes) => b64(await crypto.subtle.sign("Ed25519", key, bytes));
+async function verify(key, signature, bytes) {
+ const publicKey = await crypto.subtle.importKey("raw", raw(key, 32), "Ed25519", false, ["verify"]);
+ if (!await crypto.subtle.verify("Ed25519", publicKey, raw(signature, 64), bytes)) refuse();
+}
+function clock(now) {
+ if (!Number.isSafeInteger(now) || now < 0 || now > 8640000000000000) refuse();
+}
+function timestamp(value) {
+ if (typeof value !== "string" || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value) refuse();
+}
+function card(value) {
+ if (typeof value !== "string" || value.length > 2048) refuse();
+ let url; try { url = new URL(value); } catch { refuse(); }
+ if (url.protocol !== "https:" || url.username || url.password || url.hash || url.search || url.href !== value) refuse();
+ // DNS/SSRF checks are the transport's responsibility. Key bundles never cause a fetch.
+}
+function peer(value) { fields(value, ["cardUrl", "identityKey", "keyId"]); card(value.cardUrl); raw(value.identityKey, 32); raw(value.keyId, 32); }
+export function validatePeerStructure(value) { const copy = parseJSON(canonicalJSON(value)); peer(copy); return copy; }
+const identityOf = bundle => ({ cardUrl: bundle.cardUrl, identityKey: bundle.identityKey, keyId: bundle.keyId });
+function header(value, now, fresh = true) {
+ if (fresh) clock(now);
+ fields(value, ["from", "to", "contextId", "messageId", "taskId", "role", "state", "kind", "sentAt", "commitment"]);
+ peer(value.from); peer(value.to);
+ for (const id of [value.contextId, value.messageId]) if (typeof id !== "string" || !/^[\x21-\x7e]{1,200}$/.test(id)) refuse();
+ if (value.taskId !== null && (typeof value.taskId !== "string" || !/^[\x21-\x7e]{1,200}$/.test(value.taskId))) refuse();
+ if (!["user", "agent"].includes(value.role) || !["message", "status", "artifact"].includes(value.kind)) refuse();
+ if (value.state !== null && !["submitted", "working", "input-required", "completed", "failed", "canceled", "rejected", "auth-required"].includes(value.state)) refuse();
+ if (value.taskId === null && (value.role !== "user" || value.kind !== "message" || value.state !== null)) refuse();
+ timestamp(value.sentAt); raw(value.commitment, 32);
+ if (fresh && (Date.parse(value.sentAt) < now - 30 * 86400000 || Date.parse(value.sentAt) > now + 300000)) refuse("replay");
+}
+export function validateEnvelopeStructure(value) {
+ // Clone before asynchronous users can observe it. This checks structure/bytes,
+ // not signature authenticity, freshness, local trust or replay authorization.
+ const envelope = typeof value === "string" ? parseJSON(value) : parseJSON(canonicalJSON(value));
+ fields(envelope, ["v", "suite", "header", "recipient", "sender", "signature"]);
+ if (envelope.v !== 1 || envelope.suite !== SUITE) refuse("extension_unsupported");
+ header(envelope.header, undefined, false);
+ for (const copy of [envelope.recipient, envelope.sender]) {
+  fields(copy, ["enc", "ct"]); raw(copy.enc, 32); const ct = raw(copy.ct);
+  if (ct.length < 16 || ct.length > MAX_PLAINTEXT + 16) refuse("content_too_large");
+ }
+ raw(envelope.signature, 64);
+ return envelope;
+}
+function bundleBody(bundle) { const { signature, ...body } = bundle; return body; }
+function envelopeBody(envelope) { const { signature, ...body } = envelope; return body; }
+async function verifyBundleRaw(bundle, { cardUrl, identityKey, now = Date.now() }) {
+ clock(now);
+ fields(bundle, ["v", "suite", "cardUrl", "identityKey", "encryptionKey", "keyId", "notBefore", "signature"]);
+ if (bundle.v !== 1 || bundle.suite !== SUITE) refuse("extension_unsupported");
+ card(bundle.cardUrl); timestamp(bundle.notBefore);
+ if (bundle.cardUrl !== cardUrl || bundle.identityKey !== identityKey || Date.parse(bundle.notBefore) > now + 300000) refuse("key_changed");
+ if (await digest(raw(bundle.encryptionKey, 32)) !== bundle.keyId) refuse();
+ await verify(identityKey, bundle.signature, encode("a2a-exposed sealed key v1\n" + canonicalJSON(bundleBody(bundle))));
+ return bundle;
+}
+async function generateIdentityRaw(cardUrl, now = Date.now()) {
+ clock(now); card(cardUrl);
+ const signing = await crypto.subtle.generateKey("Ed25519", true, ["sign", "verify"]);
+ const encryption = await suite.kem.generateKeyPair();
+ const body = { v: 1, suite: SUITE, cardUrl, identityKey: b64(await crypto.subtle.exportKey("raw", signing.publicKey)), encryptionKey: b64(await suite.kem.serializePublicKey(encryption.publicKey)), notBefore: new Date(now).toISOString() };
+ body.keyId = await digest(raw(body.encryptionKey, 32));
+ const bundle = { ...body, signature: await sign(signing.privateKey, encode("a2a-exposed sealed key v1\n" + canonicalJSON(body))) };
+ return { signingKey: signing.privateKey, encryptionKey: encryption.privateKey, bundle };
+}
+async function rotateEncryptionKeyRaw(identity, now = Date.now()) {
+ clock(now);
+ await verifyBundle(identity.bundle, { cardUrl: identity.bundle.cardUrl, identityKey: identity.bundle.identityKey, now });
+ const encryption = await suite.kem.generateKeyPair();
+ const body = { ...bundleBody(identity.bundle), encryptionKey: b64(await suite.kem.serializePublicKey(encryption.publicKey)), notBefore: new Date(now).toISOString() };
+ body.keyId = await digest(raw(body.encryptionKey, 32));
+ const bundle = { ...body, signature: await sign(identity.signingKey, encode("a2a-exposed sealed key v1\n" + canonicalJSON(body))) };
+ await verifyBundle(bundle, { cardUrl: body.cardUrl, identityKey: body.identityKey, now });
+ return { signingKey: identity.signingKey, encryptionKey: encryption.privateKey, bundle };
+}
+async function commitment(nonce, content) {
+ const bytes = encode(canonicalJSON(content)), salt = raw(nonce, 32);
+ const joined = new Uint8Array(salt.length + bytes.length); joined.set(salt); joined.set(bytes, salt.length);
+ return digest(joined);
+}
+async function sealCopy(bundle, plaintext, aad, purpose) {
+ const publicKey = await suite.kem.deserializePublicKey(raw(bundle.encryptionKey, 32));
+ const context = await suite.createSenderContext({ recipientPublicKey: publicKey, info: encode("a2a-exposed sealed v1 " + purpose) });
+ return { enc: b64(context.enc), ct: b64(await context.seal(plaintext, aad)) };
+}
+// The caller must supply locally pinned bundles, and must enforce policy and replay state.
+async function sealRaw({ identity, recipient, binding, content, now = Date.now() }) {
+ fields(binding, ["contextId", "messageId", "taskId", "role", "state", "kind"]);
+ await verifyBundle(identity.bundle, { cardUrl: identity.bundle.cardUrl, identityKey: identity.bundle.identityKey, now });
+ await verifyBundle(recipient, { cardUrl: recipient.cardUrl, identityKey: recipient.identityKey, now });
+ const nonce = b64(crypto.getRandomValues(new Uint8Array(32)));
+ const plaintext = encode(canonicalJSON({ nonce, content }));
+ if (plaintext.length > MAX_PLAINTEXT) refuse("content_too_large");
+ const h = { ...binding, from: identityOf(identity.bundle), to: identityOf(recipient), sentAt: new Date(now).toISOString(), commitment: await commitment(nonce, content) };
+ header(h, now); const aad = encode(canonicalJSON(h));
+ const body = { v: 1, suite: SUITE, header: h, recipient: await sealCopy(recipient, plaintext, aad, "recipient"), sender: await sealCopy(identity.bundle, plaintext, aad, "sender") };
+ const envelope = { ...body, signature: await sign(identity.signingKey, encode("a2a-exposed sealed envelope v1\n" + canonicalJSON(body))) };
+ if (Buffer.byteLength(canonicalJSON(envelope)) > 1024 * 1024) refuse("content_too_large");
+ await open({ envelope, identity, sender: identity.bundle, recipient, expected: binding, purpose: "sender", now });
+ return envelope;
+}
+async function verifyEnvelopeSignatureRaw({ envelope, sender, recipient, now = Date.now() }) {
+ envelope = validateEnvelopeStructure(envelope); sender = parseJSON(canonicalJSON(sender)); recipient = parseJSON(canonicalJSON(recipient));
+ header(envelope.header, now);
+ if (canonicalJSON(envelope.header.from) !== canonicalJSON(identityOf(sender)) || canonicalJSON(envelope.header.to) !== canonicalJSON(identityOf(recipient))) refuse("key_changed");
+ await verifyBundle(sender, { cardUrl: sender.cardUrl, identityKey: sender.identityKey, now });
+ await verifyBundle(recipient, { cardUrl: recipient.cardUrl, identityKey: recipient.identityKey, now });
+ await verify(sender.identityKey, envelope.signature, encode("a2a-exposed sealed envelope v1\n" + canonicalJSON(envelopeBody(envelope))));
+ return { envelope, sender, recipient };
+}
+async function openRaw({ envelope, identity, sender, recipient, expected, purpose = "recipient", now = Date.now() }) {
+ try {
+  // Capture caller-owned public objects and private key references before awaiting.
+  identity = { bundle: parseJSON(canonicalJSON(identity.bundle)), encryptionKey: identity.encryptionKey };
+  expected = parseJSON(canonicalJSON(expected));
+  if (!["recipient", "sender"].includes(purpose)) refuse();
+  fields(expected, ["contextId", "messageId", "taskId", "role", "state", "kind"]);
+  const verified = await verifyEnvelopeSignatureRaw({ envelope, sender, recipient, now });
+  ({ envelope, sender, recipient } = verified);
+  for (const key of Object.keys(expected)) if (expected[key] !== envelope.header[key]) refuse();
+  const own = purpose === "sender" ? sender : recipient;
+  if (canonicalJSON(identityOf(identity.bundle)) !== canonicalJSON(identityOf(own))) refuse("key_lost");
+  const copy = envelope[purpose];
+  const context = await suite.createRecipientContext({ recipientKey: identity.encryptionKey, enc: raw(copy.enc, 32), info: encode("a2a-exposed sealed v1 " + purpose) });
+  const plaintext = await context.open(raw(copy.ct), encode(canonicalJSON(envelope.header)));
+  if (plaintext.byteLength > MAX_PLAINTEXT) refuse("content_too_large");
+  const payload = parseJSON(decoder.decode(plaintext)); fields(payload, ["nonce", "content"]);
+  if (await commitment(payload.nonce, payload.content) !== envelope.header.commitment) refuse();
+  return payload.content;
+ } catch (error) {
+  if (error instanceof EncryptionError) throw error;
+  refuse(); // Never expose HPKE/JSON/provider exception strings or material.
+ }
+}
+
+async function safeCall(action) {
+ try { return await action(); } catch (error) {
+  if (error instanceof EncryptionError) throw error;
+  refuse();
+ }
+}
+export const verifyBundle = (...args) => safeCall(() => verifyBundleRaw(...args));
+export const generateIdentity = (...args) => safeCall(() => generateIdentityRaw(...args));
+export const rotateEncryptionKey = (...args) => safeCall(() => rotateEncryptionKeyRaw(...args));
+export const seal = (...args) => safeCall(() => sealRaw(...args));
+export const verifyEnvelopeSignature = (...args) => safeCall(() => verifyEnvelopeSignatureRaw(...args));
+export const open = (...args) => safeCall(() => openRaw(...args));

package/keyring-worker.mjs

@@ -0,0 +1,19 @@
+// Private child-process protocol. Never invoke from an agent tool or return its output directly.
+import { AsyncEntry } from "@napi-rs/keyring";
+let text = "";
+try {
+ for await (const chunk of process.stdin) { text += chunk; if (Buffer.byteLength(text) > 16384) throw Error(); }
+ const input = JSON.parse(text);
+ if (!/^[a-f0-9-]{36}$/.test(input.namespace) || !/^[a-f0-9-]{36}\/[A-Za-z0-9_-]{43}$/.test(input.account)) throw Error();
+ const entry = new AsyncEntry("a2a-exposed.local-encryption.v1." + input.namespace, input.account, { linux: { store: "secret-service" } });
+ let value;
+ if (input.op === "get") value = await entry.getPassword();
+ else if (input.op === "set" && typeof input.value === "string" && input.value.length < 12000) {
+  await entry.setPassword(input.value);
+  if (await entry.getPassword() !== input.value) throw Error();
+ } else if (input.op === "delete") {
+  await entry.deleteCredential();
+  if (await entry.getPassword() !== null) throw Error();
+ } else throw Error();
+ process.stdout.write(JSON.stringify({ ok: true, ...(input.op === "get" ? { value } : {}) }));
+} catch { process.stdout.write('{"ok":false,"code":"key_store_unavailable"}'); process.exitCode = 1; }