@agentfield/sdk 0.1.92-rc.17 → 0.1.92-rc.18

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { z } from 'zod';
 import { AxiosInstance } from 'axios';
 import { WriteStream } from 'node:tty';
 import { ToolSet } from 'ai';
+import { JWK } from 'jose';
 
 type ZodSchema<T> = z.Schema<T, z.ZodTypeDef, any>;
 interface AIRequestOptions {
@@ -1269,6 +1270,67 @@ declare class DidManager {
     getIdentitySummary(): Record<string, any>;
 }
 
+/**
+ * DID-based payload encryption (JWE over X25519 keyAgreement keys).
+ *
+ * Encrypt a payload *to* an agent's DID so that only that agent — the holder of
+ * the matching X25519 private key — can decrypt it. This underpins the
+ * discuss/aggregator split: hax-sdk encrypts a scoped payload to the
+ * aggregator's DID; the untrusted discuss agent forwards the ciphertext but
+ * cannot read it; only the aggregator decrypts.
+ *
+ * Wire format is standard **JWE compact, `ECDH-ES` + `A256GCM`** over an X25519
+ * key (RFC 7518 / RFC 8037), interoperable with the Python SDK's
+ * `encrypt_for_did` / `decrypt` (which use `joserfc`). A ciphertext produced
+ * here decrypts there and vice-versa.
+ *
+ * Key-ownership model: the agent owns its keypair. The X25519 private key lives
+ * in the agent's environment; the public key is published in the agent's DID
+ * document as a `keyAgreement` verification method of type
+ * `X25519KeyAgreementKey2020`. The control plane never holds the private key.
+ */
+
+/** JOSE parameters. Must match the Python SDK exactly for interop. */
+declare const JWE_ALG: "ECDH-ES";
+declare const JWE_ENC: "A256GCM";
+/** W3C verification-method type published in the DID document for the X25519 key. */
+declare const KEY_AGREEMENT_TYPE: "X25519KeyAgreementKey2020";
+declare class PayloadEncryptionError extends Error {
+    constructor(message: string);
+}
+/** Resolves a DID string to its document (or a control-plane resolve response). */
+type DidResolver = (did: string) => Promise<Record<string, unknown> | null>;
+type Payload = string | Uint8Array | Record<string, unknown>;
+/**
+ * Generate a fresh X25519 keypair for an agent. Persist `privateJwk` into the
+ * agent's environment and publish `publicJwk` as the DID `keyAgreement` key.
+ */
+declare function generateX25519KeyPair(): Promise<{
+    privateJwk: JWK;
+    publicJwk: JWK;
+}>;
+/**
+ * Pull the X25519 `keyAgreement` public JWK out of a resolved DID document.
+ * Handles a bare W3C document or a control-plane response wrapping it under
+ * `did_document`, and a `keyAgreement` entry that is either inline (with
+ * `publicKeyJwk`) or a string reference into `verificationMethod`.
+ */
+declare function extractKeyAgreementJwk(didDocument: Record<string, unknown>): JWK;
+/** Encrypt `payload` to an X25519 public JWK, returning a compact JWE string. */
+declare function encryptToJwk(publicJwk: JWK, payload: Payload): Promise<string>;
+/**
+ * Resolve `did`, read its X25519 keyAgreement key, and encrypt `payload` to it.
+ * Returns a compact JWE that only the DID's owner can decrypt.
+ */
+declare function encryptForDid(did: string, payload: Payload, resolver: DidResolver): Promise<string>;
+/**
+ * Decrypt a compact JWE produced by {@link encryptForDid} or the Python SDK.
+ * Returns the raw plaintext bytes.
+ */
+declare function decrypt(token: string, privateJwk: JWK): Promise<Uint8Array>;
+/** Convenience: decrypt and decode the plaintext as UTF-8 text. */
+declare function decryptToString(token: string, privateJwk: JWK): Promise<string>;
+
 declare class RateLimitError extends Error {
     retryAfter?: number;
     status?: number;
@@ -1990,4 +2052,4 @@ declare class SessionTransportError extends Error {
 declare function normalizeSessionTransportValue(value: string): string;
 declare function validateSessionTransport(provider: string, transport: string): SessionTransportCapability;
 
-export { ACTIVE_STATUSES, AIClient, type AIConfig, type AIEmbeddingOptions, type AIRequestOptions, type AIStream, type AIToolRequestOptions, Agent, type AgentCapability, type AgentConfig, type AgentHandler, AgentRouter, type AgentRouterOptions, type AgentState, ApprovalClient, type ApprovalRequestResponse, type ApprovalStatusResponse, Audio, type AudioOutput, type AudioRequest, type AuditTrailExport, type AuditTrailFilters, type Awaitable, CANONICAL_STATUSES, type CompactCapability, type CompactDiscoveryResponse, DIDAuthenticator, type DIDIdentity, type DIDIdentityPackage, type DIDRegistrationRequest, type DIDRegistrationResponse, type DeploymentType, DidClient, DidInterface, DidManager, type DiscoveryFormat, type DiscoveryOptions, type DiscoveryPagination, type DiscoveryResponse, type DiscoveryResult, ExecutionContext, type ExecutionCredential, type ExecutionLogAttributes, type ExecutionLogBatchPayload, type ExecutionLogContext, type ExecutionLogEmitOptions, type ExecutionLogEntry, type ExecutionLogLevel, type ExecutionLogTransport, type ExecutionLogTransportPayload, type ExecutionLogWireEntry, ExecutionLogger, type ExecutionLoggerOptions, type ExecutionMetadata, ExecutionStatus, type ExecutionStatusValue, File, type FileOutput, type GenerateCredentialOptions, type GenerateCredentialParams, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, type HarnessConfig, type HarnessOptions, type HarnessProvider, type HarnessResult, HarnessRunner, type HealthStatus, Image, type ImageOutput, type ImageRequest, type MediaProvider, MediaProviderError, type MediaResponse, MediaRouter, type MemoryChangeEvent, MemoryClient, MemoryClientBase, type MemoryConfig, MemoryEventClient, type MemoryEventHandler, type MemoryEventHistoryOptions, MemoryInterface, type MemoryRequestMetadata, type MemoryRequestOptions, type MemoryScope, type MemoryWatchHandler, type Metrics, type MultimodalContent, MultimodalResponse, OpenRouterMediaProvider, type OpenRouterMediaProviderOptions, RateLimitError, type RateLimiterOptions, type RawExecutionContext, type RawResult, RealtimeSession, type ReasonerCapability, ReasonerContext, type ReasonerDefinition, type ReasonerHandler, type ReasonerOptions, type RequestApprovalPayload, SUPPORTED_PROVIDERS, SUPPORTED_SESSION_TRANSPORTS, type ServerlessAdapter, type ServerlessEvent, type ServerlessResponse, type SessionDefinition, type SessionOptions, type SessionProvider, type SessionTransport, type SessionTransportCapability, SessionTransportError, type SessionTurn, type SkillCapability, SkillContext, type SkillDefinition, type SkillHandler, type SkillOptions, StatelessRateLimiter, TERMINAL_STATUSES, Text, type ToolCallConfig, type ToolCallRecord, type ToolCallTrace, type ToolsOption, type VectorSearchOptions, type VectorSearchResult, Video, type VideoFrameImage, type VideoInputReference, type VideoRequest, type WaitForApprovalOptions, type WorkflowCredential, type WorkflowMetadata, type WorkflowProgressOptions, WorkflowReporter, type ZodSchema, audioFromBase64, audioFromBuffer, audioFromFile, audioFromUrl, buildProvider, buildSessionDefinition, buildToolConfig, capabilitiesToTools, capabilityToMetadataTool, capabilityToTool, createExecutionLogger, createHarnessResult, createMetrics, createMultimodalResponse, createRawResult, executeToolCallLoop, fileFromBase64, fileFromBuffer, fileFromPath, fileFromUrl, getCurrentContext, getCurrentSkillContext, imageFromBase64, imageFromBuffer, imageFromFile, imageFromUrl, isActive, isExecutionLogBatchPayload, isTerminal, normalizeExecutionLogEntry, normalizeSessionTransportValue, normalizeStatus, serializeExecutionLogEntry, text, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };
+export { ACTIVE_STATUSES, AIClient, type AIConfig, type AIEmbeddingOptions, type AIRequestOptions, type AIStream, type AIToolRequestOptions, Agent, type AgentCapability, type AgentConfig, type AgentHandler, AgentRouter, type AgentRouterOptions, type AgentState, ApprovalClient, type ApprovalRequestResponse, type ApprovalStatusResponse, Audio, type AudioOutput, type AudioRequest, type AuditTrailExport, type AuditTrailFilters, type Awaitable, CANONICAL_STATUSES, type CompactCapability, type CompactDiscoveryResponse, DIDAuthenticator, type DIDIdentity, type DIDIdentityPackage, type DIDRegistrationRequest, type DIDRegistrationResponse, type DeploymentType, DidClient, DidInterface, DidManager, type DidResolver, type DiscoveryFormat, type DiscoveryOptions, type DiscoveryPagination, type DiscoveryResponse, type DiscoveryResult, ExecutionContext, type ExecutionCredential, type ExecutionLogAttributes, type ExecutionLogBatchPayload, type ExecutionLogContext, type ExecutionLogEmitOptions, type ExecutionLogEntry, type ExecutionLogLevel, type ExecutionLogTransport, type ExecutionLogTransportPayload, type ExecutionLogWireEntry, ExecutionLogger, type ExecutionLoggerOptions, type ExecutionMetadata, ExecutionStatus, type ExecutionStatusValue, File, type FileOutput, type GenerateCredentialOptions, type GenerateCredentialParams, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, type HarnessConfig, type HarnessOptions, type HarnessProvider, type HarnessResult, HarnessRunner, type HealthStatus, Image, type ImageOutput, type ImageRequest, JWE_ALG, JWE_ENC, KEY_AGREEMENT_TYPE, type MediaProvider, MediaProviderError, type MediaResponse, MediaRouter, type MemoryChangeEvent, MemoryClient, MemoryClientBase, type MemoryConfig, MemoryEventClient, type MemoryEventHandler, type MemoryEventHistoryOptions, MemoryInterface, type MemoryRequestMetadata, type MemoryRequestOptions, type MemoryScope, type MemoryWatchHandler, type Metrics, type MultimodalContent, MultimodalResponse, OpenRouterMediaProvider, type OpenRouterMediaProviderOptions, type Payload, PayloadEncryptionError, RateLimitError, type RateLimiterOptions, type RawExecutionContext, type RawResult, RealtimeSession, type ReasonerCapability, ReasonerContext, type ReasonerDefinition, type ReasonerHandler, type ReasonerOptions, type RequestApprovalPayload, SUPPORTED_PROVIDERS, SUPPORTED_SESSION_TRANSPORTS, type ServerlessAdapter, type ServerlessEvent, type ServerlessResponse, type SessionDefinition, type SessionOptions, type SessionProvider, type SessionTransport, type SessionTransportCapability, SessionTransportError, type SessionTurn, type SkillCapability, SkillContext, type SkillDefinition, type SkillHandler, type SkillOptions, StatelessRateLimiter, TERMINAL_STATUSES, Text, type ToolCallConfig, type ToolCallRecord, type ToolCallTrace, type ToolsOption, type VectorSearchOptions, type VectorSearchResult, Video, type VideoFrameImage, type VideoInputReference, type VideoRequest, type WaitForApprovalOptions, type WorkflowCredential, type WorkflowMetadata, type WorkflowProgressOptions, WorkflowReporter, type ZodSchema, audioFromBase64, audioFromBuffer, audioFromFile, audioFromUrl, buildProvider, buildSessionDefinition, buildToolConfig, capabilitiesToTools, capabilityToMetadataTool, capabilityToTool, createExecutionLogger, createHarnessResult, createMetrics, createMultimodalResponse, createRawResult, decrypt, decryptToString, encryptForDid, encryptToJwk, executeToolCallLoop, extractKeyAgreementJwk, fileFromBase64, fileFromBuffer, fileFromPath, fileFromUrl, generateX25519KeyPair, getCurrentContext, getCurrentSkillContext, imageFromBase64, imageFromBuffer, imageFromFile, imageFromUrl, isActive, isExecutionLogBatchPayload, isTerminal, normalizeExecutionLogEntry, normalizeSessionTransportValue, normalizeStatus, serializeExecutionLogEntry, text, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };

package/dist/index.js

@@ -23,6 +23,7 @@ import https from 'https';
 import WebSocket from 'ws';
 import { Buffer as Buffer$1 } from 'buffer';
 import { zodToJsonSchema } from 'zod-to-json-schema';
+import { generateKeyPair, exportJWK, importJWK, CompactEncrypt, compactDecrypt } from 'jose';
 import { readFile } from 'fs/promises';
 
 var __defProp = Object.defineProperty;
@@ -5197,6 +5198,105 @@ var AgentRouter = class {
 function sanitize(value) {
   return value.replace(/[^0-9a-zA-Z]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
 }
+var JWE_ALG = "ECDH-ES";
+var JWE_ENC = "A256GCM";
+var KEY_AGREEMENT_TYPE = "X25519KeyAgreementKey2020";
+var PayloadEncryptionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PayloadEncryptionError";
+  }
+};
+var encoder = new TextEncoder();
+function payloadToBytes(payload) {
+  if (payload instanceof Uint8Array) return payload;
+  if (typeof payload === "string") return encoder.encode(payload);
+  return encoder.encode(JSON.stringify(payload));
+}
+async function generateX25519KeyPair() {
+  const { privateKey, publicKey } = await generateKeyPair("ECDH-ES", {
+    crv: "X25519",
+    extractable: true
+  });
+  const privateJwk = await exportJWK(privateKey);
+  const publicJwk = await exportJWK(publicKey);
+  return { privateJwk, publicJwk };
+}
+function extractKeyAgreementJwk(didDocument) {
+  if (typeof didDocument !== "object" || didDocument === null) {
+    throw new PayloadEncryptionError("DID document must be an object");
+  }
+  const doc = didDocument["did_document"] ?? didDocument;
+  const flat = doc["key_agreement"];
+  if (flat && typeof flat === "object" && flat.crv === "X25519") {
+    return flat;
+  }
+  const keyAgreement = doc["keyAgreement"];
+  if (!keyAgreement || Array.isArray(keyAgreement) && keyAgreement.length === 0) {
+    throw new PayloadEncryptionError(
+      "DID document has no keyAgreement key; the agent has not published an X25519 encryption key"
+    );
+  }
+  const verificationMethods = /* @__PURE__ */ new Map();
+  for (const vm2 of doc["verificationMethod"] ?? []) {
+    if (vm2 && typeof vm2 === "object" && typeof vm2["id"] === "string") {
+      verificationMethods.set(vm2["id"], vm2);
+    }
+  }
+  const entry = Array.isArray(keyAgreement) ? keyAgreement[0] : keyAgreement;
+  let vm;
+  if (typeof entry === "string") {
+    vm = verificationMethods.get(entry);
+    if (!vm) {
+      throw new PayloadEncryptionError(
+        `keyAgreement references unknown verification method ${entry}`
+      );
+    }
+  } else if (entry && typeof entry === "object") {
+    vm = entry;
+  } else {
+    throw new PayloadEncryptionError("unsupported keyAgreement entry shape");
+  }
+  const jwk = vm["publicKeyJwk"];
+  if (!jwk || jwk.crv !== "X25519") {
+    throw new PayloadEncryptionError(
+      "keyAgreement verification method does not carry an X25519 publicKeyJwk"
+    );
+  }
+  return jwk;
+}
+async function encryptToJwk(publicJwk, payload) {
+  if (!publicJwk || publicJwk.crv !== "X25519") {
+    throw new PayloadEncryptionError("publicJwk must be an X25519 OKP JWK");
+  }
+  try {
+    const key = await importJWK(publicJwk, JWE_ALG);
+    return await new CompactEncrypt(payloadToBytes(payload)).setProtectedHeader({ alg: JWE_ALG, enc: JWE_ENC }).encrypt(key);
+  } catch (err) {
+    if (err instanceof PayloadEncryptionError) throw err;
+    throw new PayloadEncryptionError(`encryption failed: ${err.message}`);
+  }
+}
+async function encryptForDid(did, payload, resolver) {
+  const document = await resolver(did);
+  if (!document) {
+    throw new PayloadEncryptionError(`could not resolve DID ${did}`);
+  }
+  const publicJwk = extractKeyAgreementJwk(document);
+  return encryptToJwk(publicJwk, payload);
+}
+async function decrypt(token, privateJwk) {
+  try {
+    const key = await importJWK(privateJwk, JWE_ALG);
+    const { plaintext } = await compactDecrypt(token, key);
+    return Uint8Array.from(plaintext);
+  } catch (err) {
+    throw new PayloadEncryptionError(`decryption failed: ${err.message}`);
+  }
+}
+async function decryptToString(token, privateJwk) {
+  return new TextDecoder().decode(await decrypt(token, privateJwk));
+}
 var IMAGE_MIME_TYPES = {
   ".jpg": "image/jpeg",
   ".jpeg": "image/jpeg",
@@ -6618,6 +6718,6 @@ function sleep2(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
-export { ACTIVE_STATUSES, AIClient, Agent, AgentRouter, ApprovalClient, Audio, CANONICAL_STATUSES, DIDAuthenticator, DidClient, DidInterface, DidManager, ExecutionContext, ExecutionLogger, ExecutionStatus, File, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, HarnessRunner, Image, MediaProviderError, MediaRouter, MemoryClient, MemoryClientBase, MemoryEventClient, MemoryInterface, MultimodalResponse, OpenRouterMediaProvider, RateLimitError, RealtimeSession, ReasonerContext, SUPPORTED_PROVIDERS, SUPPORTED_SESSION_TRANSPORTS, SessionTransportError, SkillContext, StatelessRateLimiter, TERMINAL_STATUSES, Text, Video, WorkflowReporter, audioFromBase64, audioFromBuffer, audioFromFile, audioFromUrl, buildProvider, buildSessionDefinition, buildToolConfig, capabilitiesToTools, capabilityToMetadataTool, capabilityToTool, createExecutionLogger, createHarnessResult, createMetrics, createMultimodalResponse, createRawResult, executeToolCallLoop, fileFromBase64, fileFromBuffer, fileFromPath, fileFromUrl, getCurrentContext, getCurrentSkillContext, imageFromBase64, imageFromBuffer, imageFromFile, imageFromUrl, isActive, isExecutionLogBatchPayload, isTerminal, normalizeExecutionLogEntry, normalizeSessionTransportValue, normalizeStatus, serializeExecutionLogEntry, text, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };
+export { ACTIVE_STATUSES, AIClient, Agent, AgentRouter, ApprovalClient, Audio, CANONICAL_STATUSES, DIDAuthenticator, DidClient, DidInterface, DidManager, ExecutionContext, ExecutionLogger, ExecutionStatus, File, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, HarnessRunner, Image, JWE_ALG, JWE_ENC, KEY_AGREEMENT_TYPE, MediaProviderError, MediaRouter, MemoryClient, MemoryClientBase, MemoryEventClient, MemoryInterface, MultimodalResponse, OpenRouterMediaProvider, PayloadEncryptionError, RateLimitError, RealtimeSession, ReasonerContext, SUPPORTED_PROVIDERS, SUPPORTED_SESSION_TRANSPORTS, SessionTransportError, SkillContext, StatelessRateLimiter, TERMINAL_STATUSES, Text, Video, WorkflowReporter, audioFromBase64, audioFromBuffer, audioFromFile, audioFromUrl, buildProvider, buildSessionDefinition, buildToolConfig, capabilitiesToTools, capabilityToMetadataTool, capabilityToTool, createExecutionLogger, createHarnessResult, createMetrics, createMultimodalResponse, createRawResult, decrypt, decryptToString, encryptForDid, encryptToJwk, executeToolCallLoop, extractKeyAgreementJwk, fileFromBase64, fileFromBuffer, fileFromPath, fileFromUrl, generateX25519KeyPair, getCurrentContext, getCurrentSkillContext, imageFromBase64, imageFromBuffer, imageFromFile, imageFromUrl, isActive, isExecutionLogBatchPayload, isTerminal, normalizeExecutionLogEntry, normalizeSessionTransportValue, normalizeStatus, serializeExecutionLogEntry, text, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map