mycomesh-consumer 0.1.53 → 0.2.1

package/src/disputes.mjs

@@ -0,0 +1,54 @@
+// V11 Consumer disputes: keep each request's plaintexts locally, reveal them as evidence on demand.
+import { chmodSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { canonicalJson } from "./secure-envelope.mjs";
+import { encodeCall, encodeWords, hex, keccak, settlementKey } from "./eip712.mjs";
+
+export const EVIDENCE_SCHEMA = "mycomesh.v11.evidence.v1";
+const JOURNAL_RETENTION_MS = 3 * 24 * 3600 * 1000; // the dispute window is 24 hours
+
+const journal = (dir) => join(dir, "requests");
+
+export function recordRequest(dir, prepared, opened, relayUrl) {
+  const folder = journal(dir);
+  mkdirSync(folder, { recursive: true, mode: 0o700 });
+  const key = settlementKey(prepared.authorization.key, prepared.authorization.request_id);
+  const path = join(folder, `${key}.json`);
+  writeFileSync(path, JSON.stringify({
+    settlement_key: key, relay_url: relayUrl, recorded_at: Math.floor(Date.now() / 1000),
+    signed_receipt: opened.receipt, request: Buffer.from(prepared.requestPlaintext).toString("base64"),
+    response: Buffer.from(opened.responsePlaintext).toString("base64"),
+  }), { mode: 0o600 });
+  chmodSync(path, 0o600);
+  for (const name of readdirSync(folder)) {
+    const file = join(folder, name);
+    if (Date.now() - statSync(file).mtimeMs > JOURNAL_RETENTION_MS) unlinkSync(file);
+  }
+  return key;
+}
+
+export function loadRequest(dir, which) {
+  const folder = journal(dir);
+  let name = `${String(which).toLowerCase()}.json`;
+  if (which === "last") {
+    const files = readdirSync(folder).filter((file) => file.endsWith(".json"));
+    if (!files.length) throw new Error("no recorded requests");
+    name = files.sort((a, b) => statSync(join(folder, b)).mtimeMs - statSync(join(folder, a)).mtimeMs)[0];
+  }
+  return JSON.parse(readFileSync(join(folder, name), "utf8"));
+}
+
+export function buildEvidence(record, { reasonCode, statement }) {
+  return {
+    schema: EVIDENCE_SCHEMA, settlement_key: record.settlement_key, signed_receipt: record.signed_receipt,
+    request: record.request, response: record.response,
+    allegation: { reason_code: String(reasonCode).slice(0, 64), statement: String(statement).slice(0, 4000) },
+  };
+}
+
+export const evidenceHash = (evidence) => hex(keccak(Buffer.from(canonicalJson(evidence), "utf8")));
+
+export const reportId = (key, reporter, digest) =>
+  hex(keccak(encodeWords([["bytes32", key], ["address", reporter], ["bytes32", digest]])));
+
+export const openDisputeCall = (key, digest) => encodeCall("openDispute(bytes32,bytes32)", [["bytes32", key], ["bytes32", digest]]);

package/src/eip712.mjs

@@ -0,0 +1,151 @@
+// EVM primitives for the V11 Consumer; mirrors mycomesh/evm.py and mycomesh/settlement.py.
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { keccak_256 } from "@noble/hashes/sha3.js";
+
+export const DOMAIN_NAME = "MycoMesh Settlement";
+export const DOMAIN_VERSION = "11";
+export const MAX_AUTHORIZATION_TTL = 3 * 60 * 60;
+
+const enc = new TextEncoder();
+export const keccak = (bytes) => Buffer.from(keccak_256(bytes));
+export const hex = (bytes) => `0x${Buffer.from(bytes).toString("hex")}`;
+export const unhex = (value) => Buffer.from(String(value).replace(/^0x/, ""), "hex");
+const typehash = (text) => keccak(enc.encode(text));
+
+export const AUTHORIZATION_TYPEHASH = typehash(
+  "PaymentAuthorization(bytes32 requestId,bytes32 requestHash,address key,address providerSigner,"
+  + "address relaySigner,uint256 maxFee,uint64 issuedAt,uint64 executeBy,uint64 deadline)");
+export const RECEIPT_TYPEHASH = typehash(
+  "UsageReceipt(bytes32 authorizationHash,bytes32 dispatchHash,bytes32 responseHash,uint256 inputTokens,"
+  + "uint256 outputTokens,uint256 actualFee)");
+export const DISPATCH_TYPEHASH = typehash("RelayDispatch(bytes32 authorizationHash)");
+export const PROVIDER_TRANSPORT_TYPEHASH = typehash(
+  "ProviderTransport(address providerSigner,bytes32 identityPublicKey,bytes32 transportKeyId,uint64 expiresAt)");
+const DOMAIN_TYPEHASH = typehash("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)");
+
+export function normalizeAddress(value) {
+  if (typeof value !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(value)) throw new Error(`invalid address: ${value}`);
+  return value.toLowerCase();
+}
+
+export function word(kind, value) {
+  if (kind === "bytes32") {
+    if (typeof value !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(value)) throw new Error(`invalid bytes32: ${value}`);
+    return unhex(value);
+  }
+  if (kind === "address") return Buffer.concat([Buffer.alloc(12), unhex(normalizeAddress(value))]);
+  if (kind === "uint") {
+    const number = BigInt(value);
+    if (number < 0n || number >= 1n << 256n) throw new Error("uint out of range");
+    return Buffer.from(number.toString(16).padStart(64, "0"), "hex");
+  }
+  if (kind === "bool") return word("uint", value ? 1 : 0);
+  throw new Error(`unsupported word type ${kind}`);
+}
+
+export const encodeWords = (pairs) => Buffer.concat(pairs.map(([kind, value]) => word(kind, value)));
+
+export function addressOf(privateKey) {
+  const pub = secp256k1.getPublicKey(unhex(privateKey), false);
+  return hex(keccak(pub.subarray(1)).subarray(12));
+}
+
+export function signDigest(privateKey, digest) {
+  const signature = secp256k1.sign(digest, unhex(privateKey), { lowS: true });
+  return hex(Buffer.concat([
+    Buffer.from(signature.r.toString(16).padStart(64, "0"), "hex"),
+    Buffer.from(signature.s.toString(16).padStart(64, "0"), "hex"),
+    Buffer.from([27 + signature.recovery]),
+  ]));
+}
+
+export function recoverAddress(digest, signatureHex) {
+  const raw = unhex(signatureHex);
+  if (raw.length !== 65) throw new Error("signature must be 65 bytes");
+  const v = raw[64] >= 27 ? raw[64] - 27 : raw[64];
+  const r = BigInt(hex(raw.subarray(0, 32)));
+  const s = BigInt(hex(raw.subarray(32, 64)));
+  if (s > secp256k1.CURVE.n / 2n || (v !== 0 && v !== 1)) throw new Error("signature is not canonical");
+  const point = new secp256k1.Signature(r, s).addRecoveryBit(v).recoverPublicKey(digest);
+  return hex(keccak(point.toRawBytes(false).subarray(1)).subarray(12));
+}
+
+export function domainSeparator(chainId, verifyingContract) {
+  return keccak(encodeWords([
+    ["bytes32", hex(DOMAIN_TYPEHASH)], ["bytes32", hex(keccak(enc.encode(DOMAIN_NAME)))],
+    ["bytes32", hex(keccak(enc.encode(DOMAIN_VERSION)))], ["uint", chainId], ["address", verifyingContract],
+  ]));
+}
+
+export const typedDigest = (deployment, structHash) =>
+  keccak(Buffer.concat([Buffer.from([0x19, 0x01]), domainSeparator(deployment.chainId, deployment.settlement), structHash]));
+
+export function authorizationStructHash(a) {
+  return keccak(encodeWords([
+    ["bytes32", hex(AUTHORIZATION_TYPEHASH)], ["bytes32", a.request_id], ["bytes32", a.request_hash],
+    ["address", a.key], ["address", a.provider_signer], ["address", a.relay_signer], ["uint", a.max_fee],
+    ["uint", a.issued_at], ["uint", a.execute_by], ["uint", a.deadline],
+  ]));
+}
+
+export const dispatchStructHash = (authorizationHash) =>
+  keccak(encodeWords([["bytes32", hex(DISPATCH_TYPEHASH)], ["bytes32", hex(authorizationHash)]]));
+
+export function receiptStructHash(r) {
+  return keccak(encodeWords([
+    ["bytes32", hex(RECEIPT_TYPEHASH)], ["bytes32", r.authorization_hash], ["bytes32", r.dispatch_hash],
+    ["bytes32", r.response_hash], ["uint", r.input_tokens], ["uint", r.output_tokens], ["uint", r.actual_fee],
+  ]));
+}
+
+export const requestIdFor = (key, nonce) => hex(keccak(encodeWords([["address", key], ["bytes32", nonce]])));
+export const settlementKey = (key, requestId) => hex(keccak(encodeWords([["address", key], ["bytes32", requestId]])));
+
+/** Every check the settlement contract makes that needs no chain state. */
+export function verifySignedReceipt(signed, deployment) {
+  const a = signed.authorization;
+  const r = signed.receipt;
+  const authHash = authorizationStructHash(a);
+  if (r.authorization_hash !== hex(authHash) || r.dispatch_hash !== hex(dispatchStructHash(authHash))) {
+    throw new Error("receipt is not bound to its authorization");
+  }
+  if (!(BigInt(r.actual_fee) > 0n && BigInt(r.actual_fee) <= BigInt(a.max_fee))) throw new Error("receipt fee exceeds the authorization");
+  if (recoverAddress(typedDigest(deployment, authHash), signed.key_signature) !== a.key) throw new Error("bad consumer key signature");
+  if (recoverAddress(typedDigest(deployment, dispatchStructHash(authHash)), signed.relay_signature) !== a.relay_signer) {
+    throw new Error("bad relay dispatch signature");
+  }
+  if (recoverAddress(typedDigest(deployment, receiptStructHash(r)), signed.provider_signature) !== a.provider_signer) {
+    throw new Error("bad provider signature");
+  }
+}
+
+// ---------------- transactions (Consumer setup: approve, deposit, registerKey) ----------------
+
+function rlp(value) {
+  if (Array.isArray(value)) return prefix(Buffer.concat(value.map(rlp)), 0xc0);
+  let bytes;
+  if (typeof value === "bigint" || typeof value === "number") {
+    const number = BigInt(value);
+    bytes = number === 0n ? Buffer.alloc(0) : Buffer.from(number.toString(16).padStart(Math.ceil(number.toString(16).length / 2) * 2, "0"), "hex");
+  } else bytes = Buffer.from(value);
+  if (bytes.length === 1 && bytes[0] < 0x80) return bytes;
+  return prefix(bytes, 0x80);
+}
+
+function prefix(payload, offset) {
+  if (payload.length <= 55) return Buffer.concat([Buffer.from([offset + payload.length]), payload]);
+  const lengthHex = payload.length.toString(16);
+  const length = Buffer.from(lengthHex.padStart(Math.ceil(lengthHex.length / 2) * 2, "0"), "hex");
+  return Buffer.concat([Buffer.from([offset + 55 + length.length]), length, payload]);
+}
+
+export function signLegacyTransaction(privateKey, { nonce, gasPrice, gasLimit, to, value = 0n, data, chainId }) {
+  const fields = [BigInt(nonce), BigInt(gasPrice), BigInt(gasLimit), to ? unhex(normalizeAddress(to)) : Buffer.alloc(0),
+    BigInt(value), unhex(data)];
+  const signature = secp256k1.sign(keccak(rlp([...fields, BigInt(chainId), 0n, 0n])), unhex(privateKey), { lowS: true });
+  return hex(rlp([...fields, BigInt(chainId) * 2n + 35n + BigInt(signature.recovery), signature.r, signature.s]));
+}
+
+export function encodeCall(signature, pairs) {
+  return hex(Buffer.concat([keccak(enc.encode(signature)).subarray(0, 4), encodeWords(pairs)]));
+}

package/src/protocol.mjs

@@ -0,0 +1,90 @@
+// V11 sealed request/response protocol; mirrors mycomesh/protocol.py and mycomesh/consumer.py.
+import { createHash, randomBytes } from "node:crypto";
+import {
+  PROVIDER_TRANSPORT_TYPEHASH, addressOf, authorizationStructHash, encodeWords, hex, keccak, normalizeAddress,
+  recoverAddress, requestIdFor, signDigest, typedDigest, verifySignedReceipt,
+} from "./eip712.mjs";
+import {
+  canonicalJson, generateIdentity, generateTransportKey, openFrame, sealFrame, verifyTransportKeyBinding,
+} from "./secure-envelope.mjs";
+
+export const REQUEST_SCHEMA = "mycomesh.v11.request.v1";
+export const RESPONSE_SCHEMA = "mycomesh.v11.response.v1";
+export const SEALED_REQUEST_PURPOSE = "mycomesh.v11.sealed-request";
+export const SEALED_RESPONSE_PURPOSE = "mycomesh.v11.sealed-response";
+
+export const sha256Hex = (bytes) => `0x${createHash("sha256").update(bytes).digest("hex")}`;
+
+export function buildRequest({ endpoint, model, content, maxOutputTokens, replyKeyId, options = {} }) {
+  if (!["responses", "chat"].includes(endpoint)) throw new Error("unsupported endpoint");
+  if (!Number.isSafeInteger(maxOutputTokens) || maxOutputTokens < 1) throw new Error("invalid max_output_tokens");
+  const document = {
+    schema: REQUEST_SCHEMA, endpoint, model, [endpoint === "chat" ? "messages" : "input"]: content,
+    max_output_tokens: maxOutputTokens, options, reply_key_id: replyKeyId,
+  };
+  return Buffer.from(canonicalJson(document), "utf8");
+}
+
+/** Return the Provider signer a descriptor's own EVM attestation proves; a Relay cannot forge it. */
+export function verifiedProvider(descriptor, deployment, now) {
+  const binding = verifyTransportKeyBinding(descriptor.transport_key, { now });
+  const attestation = descriptor.transport_attestation || {};
+  const signer = normalizeAddress(attestation.provider_signer);
+  if (!Number.isSafeInteger(attestation.expires_at) || attestation.expires_at <= now) throw new Error("transport attestation expired");
+  const structHash = keccak(encodeWords([
+    ["bytes32", hex(PROVIDER_TRANSPORT_TYPEHASH)], ["address", signer],
+    ["bytes32", `0x${binding.identityPublicKey}`], ["bytes32", `0x${binding.keyId.replace(/^x25519_/, "")}`],
+    ["uint", attestation.expires_at],
+  ]));
+  if (recoverAddress(typedDigest(deployment, structHash), attestation.signature) !== signer) {
+    throw new Error("transport attestation signature is invalid");
+  }
+  if (String(descriptor.provider_signer || "").toLowerCase() !== signer) throw new Error("descriptor signer differs from its attestation");
+  return { signer, binding: descriptor.transport_key };
+}
+
+export function prepareRequest({ descriptor, deployment, keyPrivate, relaySigner, endpoint, model, content,
+  maxOutputTokens, maxFee, options = {}, now = Math.floor(Date.now() / 1000) }) {
+  const { signer, binding } = verifiedProvider(descriptor, deployment, now);
+  const identity = generateIdentity();
+  const replyKey = generateTransportKey(identity, { lifetimeSeconds: 3600, now });
+  const plaintext = buildRequest({ endpoint, model, content, maxOutputTokens, replyKeyId: replyKey.binding.key_id, options });
+  const key = addressOf(keyPrivate);
+  const authorization = {
+    request_id: requestIdFor(key, hex(randomBytes(32))), request_hash: sha256Hex(plaintext), key,
+    provider_signer: signer, relay_signer: normalizeAddress(relaySigner), max_fee: maxFee,
+    issued_at: now, execute_by: now + 300, deadline: now + 7200,
+  };
+  const sealed = sealFrame(plaintext, {
+    sender: identity, recipientBinding: binding, expectedRecipientPeerId: binding.peer_id,
+    purpose: SEALED_REQUEST_PURPOSE, ttlSeconds: 300, now,
+  });
+  return {
+    authorization, replyKey, providerPeerId: binding.peer_id, requestPlaintext: plaintext,
+    payload: {
+      authorization,
+      key_signature: signDigest(keyPrivate, typedDigest(deployment, authorizationStructHash(authorization))),
+      sealed_request: sealed.toString("base64"),
+      reply_transport_key: replyKey.binding,
+    },
+  };
+}
+
+/** Decrypt the response and prove it is exactly what the Provider signed for. */
+export function openResponse(prepared, result, deployment, now = Math.floor(Date.now() / 1000)) {
+  const signed = result.receipt;
+  if (canonicalJson(signed.authorization) !== canonicalJson(prepared.authorization)) {
+    throw new Error("receipt is for a different authorization");
+  }
+  verifySignedReceipt(signed, deployment);
+  const opened = openFrame(Buffer.from(result.sealed_response, "base64"), {
+    recipientKey: prepared.replyKey, expectedPurpose: SEALED_RESPONSE_PURPOSE, replaySet: new Set(),
+    expectedSenderPeerId: prepared.providerPeerId, now,
+  });
+  if (sha256Hex(opened.payload) !== signed.receipt.response_hash) throw new Error("response differs from the Provider-signed receipt");
+  const response = JSON.parse(opened.payload.toString("utf8"));
+  if (response.schema !== RESPONSE_SCHEMA || response.request_hash !== prepared.authorization.request_hash) {
+    throw new Error("response is not bound to this request");
+  }
+  return { response, receipt: signed, responsePlaintext: opened.payload };
+}

package/src/secure-envelope.mjs

@@ -0,0 +1,324 @@
+// Byte-compatible port of gateway/secure_transport.py for the Consumer.
+//
+// A Consumer seals V10 request content directly to the Provider's transport
+// key so a Relay only forwards ciphertext, and opens the Provider's sealed
+// response with its own short-lived transport key. The formats, canonical
+// JSON, signatures, key ids and KDF match the Python implementation exactly;
+// tests/test_secure_envelope_interop.py checks both directions.
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { ed25519, x25519 } from "@noble/curves/ed25519";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha2";
+
+export const SECURE_ENVELOPE_VERSION = "mycomesh-secure-envelope-v1";
+export const TRANSPORT_KEY_VERSION = "mycomesh-transport-key-v1";
+export const TRANSPORT_KEY_PURPOSE = "mycomesh.transport.key_binding.v1";
+export const ENVELOPE_SIGNATURE_PURPOSE = "mycomesh.transport.envelope.v1";
+export const TRANSPORT_KEY_ALGORITHM = "X25519";
+export const ENVELOPE_ALGORITHM = "X25519-HKDF-SHA256-CHACHA20POLY1305";
+
+const MAX_PLAINTEXT_BYTES = 8 * 1024 * 1024;
+const MAX_SECURE_FRAME_BYTES = 12 * 1024 * 1024;
+const MAX_ENVELOPE_TTL_SECONDS = 5 * 60;
+const MAX_TRANSPORT_KEY_LIFETIME_SECONDS = 30 * 24 * 60 * 60;
+const MAX_CLOCK_SKEW_SECONDS = 30;
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+const KDF_INFO = Buffer.concat([Buffer.from("mycomesh-secure-envelope-v1", "utf8"), Buffer.from([0]), Buffer.from("X25519-HKDF-SHA256-CHACHA20POLY1305", "utf8")]);
+const HEX32 = /^[0-9a-f]{64}$/;
+const HEX16 = /^[0-9a-f]{32}$/;
+const HEX_NONCE = /^[0-9a-f]{24}$/;
+const SIGNATURE = /^[0-9a-f]{128}$/;
+const KEY_ID = /^x25519_[0-9a-f]{64}$/;
+const PURPOSE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+const BINDING_FIELDS = ["version", "algorithm", "peer_id", "identity_public_key", "encryption_public_key",
+  "key_id", "not_before", "expires_at", "signature"];
+const ENVELOPE_FIELDS = ["version", "algorithm", "message_id", "purpose", "sender_peer_id", "sender_public_key",
+  "recipient_peer_id", "recipient_public_key", "recipient_key_id", "ephemeral_public_key", "nonce",
+  "issued_at", "expires_at", "ciphertext", "signature"];
+const BINDING_SIGNATURE_FIELDS = ["nonce", "public_key", "purpose", "timestamp", "signature"];
+const ENVELOPE_SIGNATURE_FIELDS = [...BINDING_SIGNATURE_FIELDS, "audience"];
+
+export class SecureEnvelopeError extends Error {}
+
+// Python: json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+export function canonicalJson(value) {
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "number" && !Number.isFinite(value)) throw new SecureEnvelopeError("canonical JSON rejects non-finite numbers");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+}
+
+const hex = (bytes) => Buffer.from(bytes).toString("hex");
+const nowSeconds = (now) => (now === undefined ? Math.floor(Date.now() / 1000) : now);
+const base64url = (bytes) => Buffer.from(bytes).toString("base64url");
+
+function fail(message) { throw new SecureEnvelopeError(message); }
+
+function exactFields(value, fields, label) {
+  const keys = Object.keys(value).sort();
+  const expected = [...fields].sort();
+  if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) fail(`${label} fields are invalid`);
+}
+
+function integer(value, label) {
+  if (!Number.isSafeInteger(value) || value < 0) fail(`${label} must be a non-negative integer`);
+  return value;
+}
+
+export function peerIdFromPublicKey(publicKeyHex) {
+  if (!HEX32.test(publicKeyHex)) fail("public key must be 32 bytes of lowercase hex");
+  return `peer_${createHash("sha256").update(Buffer.from(publicKeyHex, "hex")).digest("hex").slice(0, 24)}`;
+}
+
+export function generateIdentity() {
+  const privateKey = randomBytes(32);
+  const publicKey = hex(ed25519.getPublicKey(privateKey));
+  return { privateKey: privateKey.toString("hex"), publicKey, peerId: peerIdFromPublicKey(publicKey) };
+}
+
+function signatureMessage(document, signaturePayload) {
+  return Buffer.from(canonicalJson({ document, signature: signaturePayload }), "utf8");
+}
+
+export function signDocument(document, privateKeyHex, { purpose, timestamp, nonce, audience } = {}) {
+  if (Object.hasOwn(document, "signature")) fail("document is already signed");
+  const publicKey = hex(ed25519.getPublicKey(Buffer.from(privateKeyHex, "hex")));
+  const payload = { nonce: nonce || randomBytes(16).toString("hex"), public_key: publicKey, purpose, timestamp: nowSeconds(timestamp) };
+  if (audience) payload.audience = String(audience);
+  const signature = hex(ed25519.sign(signatureMessage(document, payload), Buffer.from(privateKeyHex, "hex")));
+  return { ...document, signature: { ...payload, signature } };
+}
+
+function verifyDocumentSignature(document, { purpose, audience }) {
+  const signature = document.signature;
+  if (!signature || typeof signature !== "object") fail("missing signature");
+  if (signature.purpose !== purpose) fail("bad signature purpose");
+  if (audience !== undefined && signature.audience !== audience) fail("bad signature audience");
+  const { signature: _unused, ...unsigned } = document;
+  const { signature: signatureHex, ...payload } = signature;
+  let valid = false;
+  try {
+    valid = ed25519.verify(Buffer.from(signatureHex, "hex"), signatureMessage(unsigned, payload), Buffer.from(signature.public_key, "hex"));
+  } catch { valid = false; }
+  if (!valid) fail("bad signature");
+  return unsigned;
+}
+
+function validateSignatureShape(signature, { fields, purpose, audience }) {
+  if (!signature || typeof signature !== "object") fail("missing secure transport signature");
+  exactFields(signature, fields, "secure transport signature");
+  if (typeof signature.nonce !== "string" || !HEX16.test(signature.nonce)) fail("secure transport signature nonce must be 16 bytes of lowercase hex");
+  if (typeof signature.public_key !== "string" || !HEX32.test(signature.public_key)) fail("secure transport signer public key is invalid");
+  if (signature.purpose !== purpose) fail("secure transport signature purpose mismatch");
+  integer(signature.timestamp, "secure transport signature timestamp");
+  if (audience !== undefined && signature.audience !== audience) fail("secure transport signature audience mismatch");
+  if (typeof signature.signature !== "string" || !SIGNATURE.test(signature.signature)) fail("secure transport signature must be 64 bytes of lowercase hex");
+}
+
+export function transportKeyId(publicKeyBytes) {
+  const digest = createHash("sha256").update(Buffer.concat([Buffer.from("mycomesh-transport-key-v1", "utf8"), Buffer.from([0]), Buffer.from(publicKeyBytes)])).digest("hex");
+  return `x25519_${digest}`;
+}
+
+export function generateTransportKey(identity, { lifetimeSeconds = 24 * 60 * 60, now } = {}) {
+  const current = nowSeconds(now);
+  if (!Number.isSafeInteger(lifetimeSeconds) || lifetimeSeconds < 1 || lifetimeSeconds > MAX_TRANSPORT_KEY_LIFETIME_SECONDS) {
+    fail("transport key lifetime is invalid");
+  }
+  const privateKey = randomBytes(32);
+  const publicKey = x25519.getPublicKey(privateKey);
+  const document = {
+    version: TRANSPORT_KEY_VERSION,
+    algorithm: TRANSPORT_KEY_ALGORITHM,
+    peer_id: identity.peerId,
+    identity_public_key: identity.publicKey,
+    encryption_public_key: hex(publicKey),
+    key_id: transportKeyId(publicKey),
+    not_before: current,
+    expires_at: current + lifetimeSeconds,
+  };
+  const binding = signDocument(document, identity.privateKey, { purpose: TRANSPORT_KEY_PURPOSE, timestamp: current });
+  return { binding, privateKey: privateKey.toString("hex") };
+}
+
+export function verifyTransportKeyBinding(binding, { expectedPeerId, expectedIdentityPublicKey, now } = {}) {
+  const current = nowSeconds(now);
+  if (!binding || typeof binding !== "object" || Array.isArray(binding)) fail("transport key binding must be an object");
+  exactFields(binding, BINDING_FIELDS, "transport key binding");
+  if (binding.version !== TRANSPORT_KEY_VERSION) fail("unsupported transport key binding version");
+  if (binding.algorithm !== TRANSPORT_KEY_ALGORITHM) fail("unsupported transport key algorithm");
+  const { peer_id: peerId, identity_public_key: identityPublicKey, encryption_public_key: encryptionPublicKey, key_id: keyId } = binding;
+  if (typeof peerId !== "string" || !peerId || peerId.length > 160) fail("transport peer_id is invalid");
+  if (typeof identityPublicKey !== "string" || !HEX32.test(identityPublicKey)) fail("transport identity public key is invalid");
+  if (typeof encryptionPublicKey !== "string" || !HEX32.test(encryptionPublicKey)) fail("transport encryption public key is invalid");
+  if (typeof keyId !== "string" || !KEY_ID.test(keyId)) fail("transport key_id is malformed");
+  if (keyId !== transportKeyId(Buffer.from(encryptionPublicKey, "hex"))) fail("transport key_id does not match encryption public key");
+  if (peerId !== peerIdFromPublicKey(identityPublicKey)) fail("transport peer_id does not match identity public key");
+  if (expectedPeerId !== undefined && peerId !== String(expectedPeerId)) fail("transport key binding peer_id mismatch");
+  if (expectedIdentityPublicKey !== undefined && identityPublicKey !== String(expectedIdentityPublicKey).toLowerCase()) {
+    fail("transport key binding identity public key mismatch");
+  }
+  const notBefore = integer(binding.not_before, "transport key not_before");
+  const expiresAt = integer(binding.expires_at, "transport key expires_at");
+  if (expiresAt <= notBefore) fail("transport key expiry must follow not_before");
+  if (expiresAt - notBefore > MAX_TRANSPORT_KEY_LIFETIME_SECONDS) fail("transport key lifetime exceeds the maximum");
+  const signature = binding.signature;
+  validateSignatureShape(signature, { fields: BINDING_SIGNATURE_FIELDS, purpose: TRANSPORT_KEY_PURPOSE });
+  if (signature.timestamp < notBefore - MAX_CLOCK_SKEW_SECONDS) fail("transport key was signed too early");
+  if (signature.timestamp > notBefore + MAX_CLOCK_SKEW_SECONDS) fail("transport key signature timestamp does not match not_before");
+  if (signature.timestamp > current + MAX_CLOCK_SKEW_SECONDS) fail("transport key signature timestamp is in the future");
+  if (notBefore > current + MAX_CLOCK_SKEW_SECONDS) fail("transport key is not active yet");
+  if (expiresAt <= current) fail("transport key has expired");
+  if (signature.public_key !== identityPublicKey) fail("transport key signer does not match identity public key");
+  verifyDocumentSignature(binding, { purpose: TRANSPORT_KEY_PURPOSE });
+  return { peerId, identityPublicKey, encryptionPublicKey, keyId, notBefore, expiresAt };
+}
+
+function contentKey(sharedSecret, aad) {
+  return Buffer.from(hkdf(sha256, sharedSecret, sha256(aad), KDF_INFO, 32));
+}
+
+function encodeFrame(envelope) {
+  const raw = Buffer.from(canonicalJson(envelope), "utf8");
+  if (raw.length + 4 > MAX_SECURE_FRAME_BYTES) fail(`secure frame exceeds ${MAX_SECURE_FRAME_BYTES} bytes`);
+  const prefix = Buffer.alloc(4);
+  prefix.writeUInt32BE(raw.length);
+  return Buffer.concat([prefix, raw]);
+}
+
+function decodeFrame(frame) {
+  if (!Buffer.isBuffer(frame)) fail("secure frame must be bytes");
+  if (frame.length < 4) fail("secure frame is truncated");
+  if (frame.length > MAX_SECURE_FRAME_BYTES) fail(`secure frame exceeds ${MAX_SECURE_FRAME_BYTES} bytes`);
+  const declared = frame.readUInt32BE(0);
+  if (declared === 0) fail("secure frame payload is empty");
+  if (declared !== frame.length - 4) fail("secure frame length mismatch");
+  const raw = frame.subarray(4);
+  let value;
+  try { value = JSON.parse(raw.toString("utf8")); } catch { fail("secure frame is not JSON"); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail("secure frame payload must be an object");
+  if (!raw.equals(Buffer.from(canonicalJson(value), "utf8"))) fail("secure frame JSON is not canonical");
+  return value;
+}
+
+export function sealFrame(payload, { sender, recipientBinding, expectedRecipientPeerId, expectedRecipientPublicKey,
+  purpose, ttlSeconds = 60, now } = {}) {
+  const current = nowSeconds(now);
+  if (!Buffer.isBuffer(payload)) fail("secure envelope payload must be bytes");
+  if (payload.length > MAX_PLAINTEXT_BYTES) fail(`secure envelope plaintext exceeds ${MAX_PLAINTEXT_BYTES} bytes`);
+  if (typeof purpose !== "string" || !PURPOSE.test(purpose)) fail("secure envelope purpose is invalid");
+  if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > MAX_ENVELOPE_TTL_SECONDS) fail("secure envelope TTL is invalid");
+  const recipient = verifyTransportKeyBinding(recipientBinding, {
+    expectedPeerId: expectedRecipientPeerId, expectedIdentityPublicKey: expectedRecipientPublicKey, now: current,
+  });
+  const expiresAt = current + ttlSeconds;
+  if (expiresAt > recipient.expiresAt) fail("secure envelope outlives the recipient transport key");
+  const ephemeralPrivate = randomBytes(32);
+  const ephemeralPublic = x25519.getPublicKey(ephemeralPrivate);
+  const messageId = randomBytes(16).toString("hex");
+  const nonce = randomBytes(NONCE_BYTES);
+  const header = {
+    version: SECURE_ENVELOPE_VERSION,
+    algorithm: ENVELOPE_ALGORITHM,
+    message_id: messageId,
+    purpose,
+    sender_peer_id: sender.peerId,
+    sender_public_key: sender.publicKey,
+    recipient_peer_id: recipient.peerId,
+    recipient_public_key: recipient.identityPublicKey,
+    recipient_key_id: recipient.keyId,
+    ephemeral_public_key: hex(ephemeralPublic),
+    nonce: nonce.toString("hex"),
+    issued_at: current,
+    expires_at: expiresAt,
+  };
+  const aad = Buffer.from(canonicalJson(header), "utf8");
+  const shared = x25519.getSharedSecret(ephemeralPrivate, Buffer.from(recipient.encryptionPublicKey, "hex"));
+  const cipher = createCipheriv("chacha20-poly1305", contentKey(shared, aad), nonce, { authTagLength: TAG_BYTES });
+  cipher.setAAD(aad, { plaintextLength: payload.length });
+  const ciphertext = Buffer.concat([cipher.update(payload), cipher.final(), cipher.getAuthTag()]);
+  const envelope = { ...header, ciphertext: base64url(ciphertext) };
+  const signed = signDocument(envelope, sender.privateKey, {
+    purpose: ENVELOPE_SIGNATURE_PURPOSE, timestamp: current, nonce: messageId, audience: recipient.identityPublicKey,
+  });
+  return encodeFrame(signed);
+}
+
+export function sealJsonFrame(document, options) {
+  if (!document || typeof document !== "object" || Array.isArray(document)) fail("secure envelope JSON document must be an object");
+  return sealFrame(Buffer.from(canonicalJson(document), "utf8"), options);
+}
+
+// replaySet: an in-process Set; a Consumer opens each response frame once.
+export function openFrame(frame, { recipientKey, expectedPurpose, replaySet, expectedSenderPeerId, expectedSenderPublicKey, now } = {}) {
+  const current = nowSeconds(now);
+  if (!(replaySet instanceof Set)) fail("a replay set is required");
+  const recipient = verifyTransportKeyBinding(recipientKey?.binding, { now: current });
+  if (hex(x25519.getPublicKey(Buffer.from(recipientKey.privateKey, "hex"))) !== recipient.encryptionPublicKey) {
+    fail("recipient private key does not match its binding");
+  }
+  const envelope = decodeFrame(frame);
+  exactFields(envelope, ENVELOPE_FIELDS, "secure envelope");
+  if (envelope.version !== SECURE_ENVELOPE_VERSION) fail("unsupported secure envelope version");
+  if (envelope.algorithm !== ENVELOPE_ALGORITHM) fail("unsupported secure envelope algorithm");
+  if (typeof envelope.message_id !== "string" || !HEX16.test(envelope.message_id)) fail("secure envelope message_id is invalid");
+  if (envelope.purpose !== expectedPurpose) fail("secure envelope purpose mismatch");
+  if (typeof envelope.sender_public_key !== "string" || !HEX32.test(envelope.sender_public_key)) fail("secure envelope sender public key is invalid");
+  if (envelope.sender_peer_id !== peerIdFromPublicKey(envelope.sender_public_key)) fail("secure envelope sender peer_id does not match public key");
+  if (expectedSenderPeerId !== undefined && envelope.sender_peer_id !== expectedSenderPeerId) fail("secure envelope sender peer_id mismatch");
+  if (expectedSenderPublicKey !== undefined && envelope.sender_public_key !== String(expectedSenderPublicKey).toLowerCase()) {
+    fail("secure envelope sender public key mismatch");
+  }
+  if (envelope.recipient_peer_id !== recipient.peerId) fail("secure envelope audience peer_id mismatch");
+  if (envelope.recipient_public_key !== recipient.identityPublicKey) fail("secure envelope audience public key mismatch");
+  if (envelope.recipient_key_id !== recipient.keyId) fail("secure envelope recipient key_id mismatch");
+  if (typeof envelope.ephemeral_public_key !== "string" || !HEX32.test(envelope.ephemeral_public_key)) fail("secure envelope ephemeral public key is invalid");
+  if (typeof envelope.nonce !== "string" || !HEX_NONCE.test(envelope.nonce)) fail("secure envelope nonce is invalid");
+  const issuedAt = integer(envelope.issued_at, "secure envelope issued_at");
+  const expiresAt = integer(envelope.expires_at, "secure envelope expires_at");
+  if (expiresAt <= issuedAt) fail("secure envelope expiry must follow issued_at");
+  if (expiresAt - issuedAt > MAX_ENVELOPE_TTL_SECONDS) fail("secure envelope TTL exceeds the maximum");
+  if (issuedAt > current + MAX_CLOCK_SKEW_SECONDS) fail("secure envelope was issued in the future");
+  if (expiresAt <= current) fail("secure envelope has expired");
+  if (issuedAt < recipient.notBefore - MAX_CLOCK_SKEW_SECONDS) fail("secure envelope predates the recipient transport key");
+  if (expiresAt > recipient.expiresAt) fail("secure envelope outlives the recipient transport key");
+  const signature = envelope.signature;
+  validateSignatureShape(signature, { fields: ENVELOPE_SIGNATURE_FIELDS, purpose: ENVELOPE_SIGNATURE_PURPOSE, audience: recipient.identityPublicKey });
+  if (signature.public_key !== envelope.sender_public_key) fail("secure envelope signer does not match sender public key");
+  if (signature.nonce !== envelope.message_id) fail("secure envelope signature nonce does not match message_id");
+  if (signature.timestamp !== issuedAt) fail("secure envelope signature timestamp does not match issued_at");
+  verifyDocumentSignature(envelope, { purpose: ENVELOPE_SIGNATURE_PURPOSE, audience: recipient.identityPublicKey });
+  if (typeof envelope.ciphertext !== "string" || !BASE64URL.test(envelope.ciphertext)) fail("secure envelope ciphertext must be canonical base64url");
+  const ciphertext = Buffer.from(envelope.ciphertext, "base64url");
+  if (base64url(ciphertext) !== envelope.ciphertext) fail("secure envelope ciphertext is not canonical base64url");
+  if (ciphertext.length < TAG_BYTES) fail("secure envelope ciphertext is too short");
+  if (ciphertext.length > MAX_PLAINTEXT_BYTES + TAG_BYTES) fail(`secure envelope plaintext exceeds ${MAX_PLAINTEXT_BYTES} bytes`);
+  const header = Object.fromEntries(ENVELOPE_FIELDS.filter((key) => key !== "ciphertext" && key !== "signature").map((key) => [key, envelope[key]]));
+  const aad = Buffer.from(canonicalJson(header), "utf8");
+  let plaintext;
+  try {
+    const shared = x25519.getSharedSecret(Buffer.from(recipientKey.privateKey, "hex"), Buffer.from(envelope.ephemeral_public_key, "hex"));
+    const decipher = createDecipheriv("chacha20-poly1305", contentKey(shared, aad), Buffer.from(envelope.nonce, "hex"), { authTagLength: TAG_BYTES });
+    decipher.setAAD(aad, { plaintextLength: ciphertext.length - TAG_BYTES });
+    decipher.setAuthTag(ciphertext.subarray(ciphertext.length - TAG_BYTES));
+    plaintext = Buffer.concat([decipher.update(ciphertext.subarray(0, ciphertext.length - TAG_BYTES)), decipher.final()]);
+  } catch {
+    fail("secure envelope authentication failed");
+  }
+  const replayKey = `${envelope.sender_public_key}:${recipient.keyId}:${envelope.message_id}`;
+  if (replaySet.has(replayKey)) fail("secure envelope was already accepted");
+  replaySet.add(replayKey);
+  return {
+    payload: plaintext,
+    messageId: envelope.message_id,
+    purpose: envelope.purpose,
+    senderPeerId: envelope.sender_peer_id,
+    senderPublicKey: envelope.sender_public_key,
+    issuedAt,
+    expiresAt,
+  };
+}