@prismnetwork/agent-sdk 0.6.0 → 0.7.0

package/e2ee.d.mts

@@ -0,0 +1,89 @@
+import type { KeyObject } from "node:crypto";
+
+export declare const E2EE_VERSION: string;
+export declare const X25519_SUITE: string;
+
+export declare class E2eeError extends Error {}
+
+export interface KeysetKey {
+  key_id: string;
+  algo: string;
+  public_key: string;
+}
+
+export interface AttestedKeyset {
+  e2ee_public_keys?: KeysetKey[];
+  [key: string]: unknown;
+}
+
+/// The client half of one encrypted exchange: the static key the response is
+/// encrypted to, and the request context every field's associated data binds.
+export interface ClientKey {
+  privateKey: KeyObject;
+  publicKey: string;
+  algo: string;
+  keyId: string;
+  model: string;
+  nonce: string;
+  ts: number;
+}
+
+export interface SealedRequest {
+  /// The body to send, with every message content replaced by its envelope.
+  bytes: Buffer;
+  /// The compact plaintext body the workload restores and hashes into the
+  /// receipt (§8 of the E2EE v2 protocol).
+  restored: Buffer;
+  /// All five headers a v2 request must carry; without any one of them the
+  /// service rejects the request.
+  headers: Record<string, string>;
+  clientKey: ClientKey;
+}
+
+export declare function selectE2eeKey(keyset: AttestedKeyset): KeysetKey;
+
+/// §5 restoration: a decrypted whole-content plaintext that parses as a JSON
+/// array comes back as structured content, and anything else stays a string.
+export declare function restoreContent(plaintext: string): string | unknown[];
+
+export declare function encryptChatRequest(
+  body: Record<string, unknown>,
+  keyset: AttestedKeyset,
+  options?: { now?: number; rand?: (length: number) => Uint8Array },
+): SealedRequest;
+
+export declare function decryptResponse(
+  bodyBytes: Uint8Array | string,
+  clientKey: ClientKey,
+  options?: { model?: string },
+): Record<string, unknown>;
+
+export declare function requestAad(input: {
+  algo: string;
+  model: string;
+  field: string;
+  nonce: string;
+  ts: number;
+}): Uint8Array;
+
+export declare function responseAad(input: {
+  algo: string;
+  model: string;
+  id: string;
+  field: string;
+  nonce: string;
+  ts: number;
+}): Uint8Array;
+
+export declare function sealField(
+  recipientRaw: Uint8Array,
+  plaintext: string,
+  aad: Uint8Array,
+  rand?: (length: number) => Uint8Array,
+): string;
+
+export declare function openField(privateKey: KeyObject, envelopeHex: string, aad: Uint8Array): string;
+
+export declare function publicKeyFromRaw(raw: Uint8Array): KeyObject;
+export declare function privateKeyFromSeed(seed: Uint8Array): KeyObject;
+export declare function rawPublicKey(key: KeyObject): Uint8Array;

package/e2ee.mjs

@@ -0,0 +1,215 @@
+// E2EE v2 client for attested confidential inference: the field-level
+// encryption an agent puts around a chat request so the relay that carries it
+// holds ciphertext only, and the enclave holding the attested key is the one
+// thing that can read the prompt.
+//
+// The wire contract is the X25519 suite of the ACI E2EE v2 protocol. Each
+// protected field value is hex(ephemeral_public_key(32) || gcm_nonce(12) ||
+// ciphertext || tag(16)); the AES-256-GCM key is HKDF-SHA256 over the X25519
+// shared secret with an empty salt and the suite's info string; the AEAD's
+// associated data is the JCS form of a purpose-tagged object that pins the
+// field path, the model, the request nonce and the timestamp, so a ciphertext
+// cannot be moved to another field, request or model.
+import {
+  createCipheriv,
+  createDecipheriv,
+  createPrivateKey,
+  createPublicKey,
+  diffieHellman,
+  hkdfSync,
+  randomBytes,
+} from "node:crypto";
+import { jcsBytes } from "./vendor/aci-verifier/index.mjs";
+
+export const E2EE_VERSION = "2";
+export const X25519_SUITE = "x25519-aes-256-gcm-hkdf-sha256";
+const HKDF_INFO = "aci.e2ee.v2.x25519";
+const REQUEST_PURPOSE = "aci.e2ee.request.v2";
+const RESPONSE_PURPOSE = "aci.e2ee.response.v2";
+
+// Node's X25519 keys travel as DER. Raw 32-byte keys are the wire form on both
+// sides, so wrap them in the one fixed SPKI/PKCS8 prefix each rather than
+// pulling in a curve library to do it.
+const SPKI_PREFIX = Buffer.from("302a300506032b656e032100", "hex");
+const PKCS8_PREFIX = Buffer.from("302e020100300506032b656e04220420", "hex");
+
+const RESPONSE_FIELDS = ["content", "reasoning", "reasoning_content"];
+
+export class E2eeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "E2eeError";
+  }
+}
+
+/// The x25519 entry of a quote-bound key set. The service publishes a secp256k1
+/// suite too; this client speaks the x25519 one, which is the suite the spec
+/// recommends and the only one it implements.
+export function selectE2eeKey(keyset) {
+  const keys = Array.isArray(keyset?.e2ee_public_keys) ? keyset.e2ee_public_keys : [];
+  const entry = keys.find((k) => k.algo === X25519_SUITE);
+  if (!entry) throw new E2eeError(`the attested key set publishes no ${X25519_SUITE} key`);
+  return entry;
+}
+
+export function publicKeyFromRaw(raw) {
+  return createPublicKey({
+    key: Buffer.concat([SPKI_PREFIX, Buffer.from(raw)]),
+    format: "der",
+    type: "spki",
+  });
+}
+
+export function privateKeyFromSeed(seed) {
+  if (seed.length !== 32) throw new E2eeError("an x25519 private key is 32 bytes");
+  return createPrivateKey({
+    key: Buffer.concat([PKCS8_PREFIX, Buffer.from(seed)]),
+    format: "der",
+    type: "pkcs8",
+  });
+}
+
+export function rawPublicKey(key) {
+  return key.export({ type: "spki", format: "der" }).subarray(SPKI_PREFIX.length);
+}
+
+/// The associated data for one request field (§6). Byte-exact: the test vectors
+/// pin this string.
+export function requestAad({ algo, model, field, nonce, ts }) {
+  return jcsBytes({ purpose: REQUEST_PURPOSE, algo, model, field, nonce, ts });
+}
+
+/// The response variant, which additionally binds the response id.
+export function responseAad({ algo, model, id, field, nonce, ts }) {
+  return jcsBytes({ purpose: RESPONSE_PURPOSE, algo, model, id, field, nonce, ts });
+}
+
+/// One field envelope, encrypted to `recipientRaw` under a fresh ephemeral key.
+export function sealField(recipientRaw, plaintext, aad, rand = randomBytes) {
+  const ephemeral = privateKeyFromSeed(Buffer.from(rand(32)));
+  const shared = diffieHellman({ privateKey: ephemeral, publicKey: publicKeyFromRaw(recipientRaw) });
+  const key = Buffer.from(hkdfSync("sha256", shared, Buffer.alloc(0), Buffer.from(HKDF_INFO), 32));
+  const nonce = Buffer.from(rand(12));
+  const cipher = createCipheriv("aes-256-gcm", key, nonce);
+  cipher.setAAD(aad);
+  const body = Buffer.concat([cipher.update(Buffer.from(plaintext, "utf8")), cipher.final()]);
+  return Buffer.concat([rawPublicKey(createPublicKey(ephemeral)), nonce, body, cipher.getAuthTag()]).toString("hex");
+}
+
+/// The inverse. A tampered envelope, AAD or key fails the AEAD tag and throws.
+export function openField(privateKey, envelopeHex, aad) {
+  const blob = Buffer.from(envelopeHex.startsWith("0x") ? envelopeHex.slice(2) : envelopeHex, "hex");
+  if (blob.length < 32 + 12 + 16) throw new E2eeError("e2ee envelope is too short to hold a field");
+  const shared = diffieHellman({ privateKey, publicKey: publicKeyFromRaw(blob.subarray(0, 32)) });
+  const key = Buffer.from(hkdfSync("sha256", shared, Buffer.alloc(0), Buffer.from(HKDF_INFO), 32));
+  const decipher = createDecipheriv("aes-256-gcm", key, blob.subarray(32, 44));
+  decipher.setAAD(aad);
+  decipher.setAuthTag(blob.subarray(blob.length - 16));
+  try {
+    return Buffer.concat([decipher.update(blob.subarray(44, blob.length - 16)), decipher.final()]).toString("utf8");
+  } catch {
+    throw new E2eeError("e2ee field did not authenticate: wrong key, wrong context, or altered ciphertext");
+  }
+}
+
+/// §5 restoration: a decrypted whole-content plaintext that parses as a JSON
+/// array is restored as structured content, and anything else stays the string
+/// it was. The receipt covers what the workload restored, so a client that
+/// reproduces the hash has to apply the same rule to its own copy.
+export function restoreContent(plaintext) {
+  if (typeof plaintext !== "string" || plaintext.trimStart()[0] !== "[") return plaintext;
+  try {
+    const value = JSON.parse(plaintext);
+    return Array.isArray(value) ? value : plaintext;
+  } catch {
+    return plaintext;
+  }
+}
+
+/// Encrypt every message content of a chat-completions body to the attested
+/// service key. Returns the bytes to send, the five headers that must travel
+/// with them, the client key the response is encrypted to, and the compact
+/// restored-plaintext bytes the receipt's `request.received` hash covers.
+///
+/// `now` and `rand` are injectable so a test can pin the whole envelope; both
+/// default to the real clock and the system CSPRNG.
+export function encryptChatRequest(body, keyset, { now = Math.floor(Date.now() / 1000), rand = randomBytes } = {}) {
+  if (typeof body?.model !== "string") throw new E2eeError("an e2ee request needs a top-level model string");
+  if (!Array.isArray(body.messages) || body.messages.length === 0) {
+    throw new E2eeError("an e2ee chat request needs a messages array");
+  }
+  const serviceKey = selectE2eeKey(keyset);
+  const serviceRaw = Buffer.from(serviceKey.public_key.replace(/^0x/, ""), "hex");
+  if (serviceRaw.length !== 32) throw new E2eeError("the attested x25519 key is not 32 bytes");
+
+  const clientPrivate = privateKeyFromSeed(Buffer.from(rand(32)));
+  const clientPublic = rawPublicKey(createPublicKey(clientPrivate));
+  const nonce = Buffer.from(rand(32)).toString("hex");
+  const ts = now;
+
+  // The plaintext copy is what the workload hashes into the receipt after it
+  // restores the fields (§8 of the v2 protocol), so it is built alongside the
+  // encrypted one from the same object and in the same member order.
+  const restored = { ...body, messages: [] };
+  const sealed = { ...body, messages: [] };
+  body.messages.forEach((message, index) => {
+    if (typeof message?.content !== "string") {
+      // Any plaintext string at a protected path fails the request upstream, so
+      // a body this client cannot fully protect is refused here instead.
+      throw new E2eeError(`messages.${index}.content must be a string to be encrypted`);
+    }
+    const field = `messages.${index}.content`;
+    const aad = requestAad({ algo: serviceKey.algo, model: body.model, field, nonce, ts });
+    restored.messages.push({ ...message, content: restoreContent(message.content) });
+    sealed.messages.push({ ...message, content: sealField(serviceRaw, message.content, aad, rand) });
+  });
+
+  return {
+    bytes: Buffer.from(JSON.stringify(sealed), "utf8"),
+    restored: Buffer.from(JSON.stringify(restored), "utf8"),
+    headers: {
+      "X-E2EE-Version": E2EE_VERSION,
+      "X-Client-Pub-Key": Buffer.from(clientPublic).toString("hex"),
+      "X-Model-Pub-Key": serviceKey.public_key,
+      "X-E2EE-Nonce": nonce,
+      "X-E2EE-Timestamp": String(ts),
+    },
+    clientKey: {
+      privateKey: clientPrivate,
+      publicKey: Buffer.from(clientPublic).toString("hex"),
+      algo: serviceKey.algo,
+      keyId: serviceKey.key_id,
+      model: body.model,
+      nonce,
+      ts,
+    },
+  };
+}
+
+/// Decrypt a buffered chat-completions response in place. Every generated
+/// content field the service encrypted is authenticated against the AAD that
+/// names its position, so a field lifted from another response does not open.
+export function decryptResponse(bodyBytes, clientKey, { model = clientKey.model } = {}) {
+  const text = typeof bodyBytes === "string" ? bodyBytes : Buffer.from(bodyBytes).toString("utf8");
+  const body = JSON.parse(text);
+  const id = typeof body.id === "string" ? body.id : "";
+  const choices = Array.isArray(body.choices) ? body.choices : [];
+  choices.forEach((choice, position) => {
+    const index = Number.isInteger(choice?.index) ? choice.index : position;
+    const message = choice?.message;
+    if (message === null || typeof message !== "object") return;
+    for (const name of RESPONSE_FIELDS) {
+      if (typeof message[name] !== "string" || message[name] === "") continue;
+      const aad = responseAad({
+        algo: clientKey.algo,
+        model,
+        id,
+        field: `choices.${index}.message.${name}`,
+        nonce: clientKey.nonce,
+        ts: clientKey.ts,
+      });
+      message[name] = openField(clientKey.privateKey, message[name], aad);
+    }
+  });
+  return body;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismnetwork/agent-sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Headless GPU leasing and renter-encrypted storage on Prism Network for wallet-holding agents.",
   "type": "module",
   "main": "prism.mjs",
@@ -9,6 +9,14 @@
       "types": "./prism.d.mts",
       "default": "./prism.mjs"
     },
+    "./attest": {
+      "types": "./attest.d.mts",
+      "default": "./attest.mjs"
+    },
+    "./e2ee": {
+      "types": "./e2ee.d.mts",
+      "default": "./e2ee.mjs"
+    },
     "./toolset": {
       "types": "./toolset.d.mts",
       "default": "./toolset.mjs"
@@ -24,15 +32,22 @@
   },
   "files": [
     "prism.mjs",
-    "relay.mjs",
-    "toolset.d.mts",
     "prism.d.mts",
+    "attest.mjs",
+    "attest.d.mts",
+    "e2ee.mjs",
+    "e2ee.d.mts",
+    "relay.mjs",
     "toolset.mjs",
+    "toolset.d.mts",
     "vault.mjs",
     "vault.d.ts",
     "workspace.mjs",
     "workspace.d.ts",
-    "README.md"
+    "vendor/aci-verifier/*.mjs",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
   ],
   "engines": {
     "node": ">=20"
@@ -47,7 +62,9 @@
     "web3",
     "usdg",
     "compute",
-    "llm"
+    "llm",
+    "tee",
+    "attestation"
   ],
   "homepage": "https://prismnetwork.tech",
   "repository": {
@@ -62,5 +79,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "types": "prism.d.mts"
+  "types": "prism.d.mts",
+  "dependencies": {
+    "@phala/dcap-qvl": "^0.6.1",
+    "jose": "^6.0.0"
+  }
 }

package/prism.d.mts

@@ -1,8 +1,13 @@
+import type { AttestationResult, VerifyConfidentialOptions, WorkloadPin } from "./attest.d.mts";
+
 export declare const robinhoodChain: unknown;
 export declare const USDG: string;
 export declare const DEFAULT_IMAGE: string;
 export declare const TRUST_CLASSES: readonly ["open", "isolated", "attested", "confidential"];
 
+export { DEFAULT_CONFIDENTIAL_BASE, EXPECTED_WORKLOAD, renderChecks, verifyConfidential } from "./attest.d.mts";
+export type { AttestationCheck, AttestationResult, WorkloadPin } from "./attest.d.mts";
+
 /// `mode` says which of the two shapes arrived. Brokered capacity fills in
 /// `ssh_host` and `ssh_port`; a node that accepts nothing inbound fills in the
 /// gateway fields instead and is reached through a relay.
@@ -54,6 +59,35 @@ export interface RunResult {
   timedOut: boolean;
 }
 
+export interface PaidResponse {
+  status: number;
+  headers: Headers;
+  /// The response bytes exactly as they arrived, which is what a signed receipt
+  /// over the exchange commits to.
+  bytes: Buffer;
+  tx: string;
+  /// The request as the attempt that was served built it. Under E2EE each
+  /// attempt seals its own envelope, so this is the one the receipt covers.
+  sent: { bytes: Buffer; headers?: Record<string, string>; [key: string]: unknown };
+}
+
+/// One confidential generation, with everything needed to check it afterwards.
+export interface ConfidentialRun {
+  model: string;
+  content: string | null;
+  usage: Record<string, unknown> | null;
+  receiptId: string | null;
+  receipt: Record<string, unknown> | null;
+  /// The key set the prompt was encrypted to, when e2ee was on.
+  keysetDigest: string | null;
+  e2ee: boolean;
+  priceMicros: string;
+  priceUsdg: string;
+  tx: string;
+  bytes: { request: Buffer; response: Buffer; restoredRequest?: Buffer };
+  verify(options?: Partial<VerifyConfidentialOptions>): Promise<AttestationResult>;
+}
+
 export declare class PrismAgent {
   constructor(options: { privateKey: string; escrow: string; apiBase?: string; rpcUrl?: string });
   readonly address: string;
@@ -96,6 +130,35 @@ export declare class PrismAgent {
   /// not a one-shot command: scp, a notebook client, an interactive shell.
   forward(lease: LeaseHandle, options?: { service?: "ssh" | "jupyter" }): Promise<RelayForwarder>;
   endLease(lease: LeaseHandle): void;
+  /// Pay for one call to a metered endpoint, keeping the payment until the
+  /// endpoint serves. Bytes are sent verbatim. Pass `seal` instead of `body` for
+  /// a request that has to be rebuilt per attempt, with `fingerprint` so the
+  /// kept payment still recognises the two attempts as the same request.
+  payAndPost(options: {
+    base: string;
+    path: string;
+    price: bigint | number | string;
+    payTo: string;
+    body?: Uint8Array | string | Record<string, unknown> | null;
+    headers?: Record<string, string>;
+    seal?: (() => { bytes: Uint8Array; headers?: Record<string, string> }) | null;
+    fingerprint?: Uint8Array | string | null;
+    retryDelayMs?: number;
+    caller?: string;
+  }): Promise<PaidResponse>;
+  /// One generation from the confidential tier, end-to-end encrypted by default
+  /// to a key the serving enclave's attestation quote commits to, from an
+  /// enclave running the code `expectedWorkload` pins.
+  confidentialInfer(options: {
+    prompt?: string;
+    messages?: Array<{ role: string; content: string }>;
+    model?: string | null;
+    maxUsdg?: number;
+    maxTokens?: number;
+    e2ee?: boolean;
+    expectedWorkload?: WorkloadPin | null;
+    endpoint?: string;
+  }): Promise<ConfidentialRun>;
 }
 
 export declare class PrismError extends Error {