@heysummon/consumer-sdk 0.1.1 → 0.2.6

package/src/client.ts

@@ -1,12 +1,24 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
 import type {
   SubmitRequestOptions,
   SubmitRequestResult,
   PendingEvent,
   Message,
+  DecryptedMessage,
+  MessagesResponse,
   WhoamiResult,
   HeySummonClientOptions,
   RequestStatusResponse,
 } from "./types.js";
+import type { KeyMaterial } from "./crypto.js";
+import {
+  generateKeyMaterial,
+  encryptWithKeys,
+  decryptWithKeys,
+  publicKeyFromHex,
+} from "./crypto.js";
 
 /** HTTP error with status code for callers to inspect */
 export class HeySummonHttpError extends Error {
@@ -31,10 +43,14 @@ export class HeySummonHttpError extends Error {
 export class HeySummonClient {
   private readonly baseUrl: string;
   private readonly apiKey: string;
+  private readonly e2e: boolean;
+  private readonly keyStore: Map<string, KeyMaterial> = new Map();
+  private readonly providerKeyCache: Map<string, { encPub: string; signPub: string }> = new Map();
 
   constructor(opts: HeySummonClientOptions) {
     this.baseUrl = opts.baseUrl.replace(/\/$/, ""); // trim trailing slash
     this.apiKey = opts.apiKey;
+    this.e2e = opts.e2e !== false; // default true
   }
 
   private async request<T>(
@@ -59,22 +75,41 @@ export class HeySummonClient {
     return res.json() as Promise<T>;
   }
 
-  /** Identify which provider this API key is linked to */
+  /** Identify which expert this API key is linked to */
   async whoami(): Promise<WhoamiResult> {
     return this.request<WhoamiResult>("GET", "/api/v1/whoami");
   }
 
-  /** Submit a help request */
+  /** Submit a help request (auto-generates E2E keys unless consumer provides their own or e2e is disabled) */
   async submitRequest(opts: SubmitRequestOptions): Promise<SubmitRequestResult> {
-    return this.request<SubmitRequestResult>("POST", "/api/v1/help", {
+    let signPublicKey = opts.signPublicKey;
+    let encryptPublicKey = opts.encryptPublicKey;
+
+    const consumerProvidedKeys = !!(opts.signPublicKey && opts.encryptPublicKey);
+    const shouldAutoKeygen = this.e2e && !consumerProvidedKeys;
+
+    let keys: KeyMaterial | undefined;
+    if (shouldAutoKeygen) {
+      keys = generateKeyMaterial();
+      signPublicKey = keys.signPublicKey;
+      encryptPublicKey = keys.encryptPublicKey;
+    }
+
+    const result = await this.request<SubmitRequestResult>("POST", "/api/v1/help", {
       apiKey: this.apiKey,
       question: opts.question,
       messages: opts.messages,
-      signPublicKey: opts.signPublicKey,
-      encryptPublicKey: opts.encryptPublicKey,
-      providerName: opts.providerName,
+      signPublicKey,
+      encryptPublicKey,
+      expertName: opts.expertName,
       requiresApproval: opts.requiresApproval,
     });
+
+    if (keys && result.requestId) {
+      this.keyStore.set(result.requestId, keys);
+    }
+
+    return result;
   }
 
   /** Poll for pending events (writes lastPollAt heartbeat on the server) */
@@ -87,12 +122,96 @@ export class HeySummonClient {
     await this.request<unknown>("POST", `/api/v1/events/ack/${requestId}`, {});
   }
 
-  /** Fetch the full message history for a request */
-  async getMessages(requestId: string): Promise<{ messages: Message[] }> {
-    return this.request<{ messages: Message[] }>(
+  /** Fetch the full message history for a request (auto-decrypts when keys are available) */
+  async getMessages(requestId: string): Promise<{ messages: DecryptedMessage[] }> {
+    const res = await this.request<MessagesResponse>(
       "GET",
       `/api/v1/messages/${requestId}`
     );
+
+    const keys = this.keyStore.get(requestId);
+    const hasExpertKeys = !!(res.expertEncryptPubKey && res.expertSignPubKey);
+
+    // Cache expert public keys for sendMessage() to avoid N+1 fetches
+    if (hasExpertKeys) {
+      this.providerKeyCache.set(requestId, {
+        encPub: res.expertEncryptPubKey!,
+        signPub: res.expertSignPubKey!,
+      });
+    }
+
+    const messages: DecryptedMessage[] = res.messages.map((msg) => {
+      // Plaintext messages: return as-is
+      if (msg.iv === "plaintext" || msg.plaintext) {
+        return {
+          id: msg.id,
+          from: msg.from,
+          messageId: msg.messageId,
+          createdAt: msg.createdAt,
+          plaintext: msg.plaintext ?? Buffer.from(msg.ciphertext, "base64").toString("utf8"),
+        };
+      }
+
+      // No keys available for decryption: return raw message
+      if (!keys || !hasExpertKeys) {
+        return {
+          id: msg.id,
+          from: msg.from,
+          ciphertext: msg.ciphertext,
+          iv: msg.iv,
+          authTag: msg.authTag,
+          signature: msg.signature,
+          messageId: msg.messageId,
+          createdAt: msg.createdAt,
+        };
+      }
+
+      // Auto-decrypt with stored keys
+      try {
+        // Always use expert's key for DH shared secret — DH is symmetric:
+        // DH(consumer_priv, expert_pub) = DH(expert_priv, consumer_pub)
+        const senderEncPub = publicKeyFromHex(res.expertEncryptPubKey!, "x25519");
+        // Only vary the signing key for signature verification
+        const senderSignPub = msg.from === "expert"
+          ? publicKeyFromHex(res.expertSignPubKey!, "ed25519")
+          : publicKeyFromHex(res.consumerSignPubKey!, "ed25519");
+
+        const plaintext = decryptWithKeys(
+          {
+            ciphertext: msg.ciphertext,
+            iv: msg.iv,
+            authTag: msg.authTag,
+            signature: msg.signature,
+            messageId: msg.messageId,
+          },
+          senderEncPub,
+          senderSignPub,
+          keys.encryptKeyPair.privateKey
+        );
+
+        return {
+          id: msg.id,
+          from: msg.from,
+          messageId: msg.messageId,
+          createdAt: msg.createdAt,
+          plaintext,
+        };
+      } catch {
+        return {
+          id: msg.id,
+          from: msg.from,
+          ciphertext: msg.ciphertext,
+          iv: msg.iv,
+          authTag: msg.authTag,
+          signature: msg.signature,
+          messageId: msg.messageId,
+          createdAt: msg.createdAt,
+          decryptError: true,
+        };
+      }
+    });
+
+    return { messages };
   }
 
   /** Get the current status of a help request */
@@ -114,4 +233,100 @@ export class HeySummonClient {
       `/api/v1/requests/by-ref/${refCode}`
     );
   }
+
+  /** Report that the client's blocking poll timed out */
+  async reportTimeout(requestId: string): Promise<void> {
+    await this.request<unknown>("POST", `/api/v1/help/${requestId}/timeout`, {});
+  }
+
+  /** Send an encrypted message to the expert (falls back to plaintext if no keys) */
+  async sendMessage(
+    requestId: string,
+    text: string
+  ): Promise<{ success: boolean; messageId: string; createdAt: string }> {
+    const keys = this.keyStore.get(requestId);
+
+    if (!keys) {
+      // No local keys: send as plaintext (content-safety checked server-side)
+      return this.request("POST", `/api/v1/message/${requestId}`, {
+        from: "consumer",
+        plaintext: text,
+      });
+    }
+
+    // Use cached expert keys to avoid N+1 API calls; fetch only on cache miss
+    let cached = this.providerKeyCache.get(requestId);
+    if (!cached) {
+      const res = await this.request<MessagesResponse>(
+        "GET",
+        `/api/v1/messages/${requestId}`
+      );
+      if (res.expertEncryptPubKey && res.expertSignPubKey) {
+        cached = { encPub: res.expertEncryptPubKey, signPub: res.expertSignPubKey };
+        this.providerKeyCache.set(requestId, cached);
+      }
+    }
+
+    if (!cached) {
+      throw new Error(
+        "Cannot send encrypted message: expert has not completed key exchange yet"
+      );
+    }
+
+    const expertEncPub = publicKeyFromHex(cached.encPub, "x25519");
+
+    const payload = encryptWithKeys(
+      text,
+      expertEncPub,
+      keys.signKeyPair.privateKey,
+      keys.encryptKeyPair.privateKey
+    );
+
+    return this.request("POST", `/api/v1/message/${requestId}`, {
+      from: "consumer",
+      ciphertext: payload.ciphertext,
+      iv: payload.iv,
+      authTag: payload.authTag,
+      signature: payload.signature,
+      messageId: payload.messageId,
+    });
+  }
+
+  /** Remove keys from the store for a completed/closed request */
+  releaseKeys(requestId: string): void {
+    this.keyStore.delete(requestId);
+    this.providerKeyCache.delete(requestId);
+  }
+
+  /** Import persistent keys from PEM files into the key store for a given request */
+  importKeys(requestId: string, keyDir: string): void {
+    const signPubPem = fs.readFileSync(path.join(keyDir, "sign_public.pem"), "utf8");
+    const signPrivPem = fs.readFileSync(path.join(keyDir, "sign_private.pem"), "utf8");
+    const encPubPem = fs.readFileSync(path.join(keyDir, "encrypt_public.pem"), "utf8");
+    const encPrivPem = fs.readFileSync(path.join(keyDir, "encrypt_private.pem"), "utf8");
+
+    const signPublicKey = crypto
+      .createPublicKey(signPubPem)
+      .export({ type: "spki", format: "der" })
+      .toString("hex");
+    const encryptPublicKey = crypto
+      .createPublicKey(encPubPem)
+      .export({ type: "spki", format: "der" })
+      .toString("hex");
+
+    const keys: KeyMaterial = {
+      signPublicKey,
+      encryptPublicKey,
+      signKeyPair: {
+        publicKey: crypto.createPublicKey(signPubPem),
+        privateKey: crypto.createPrivateKey(signPrivPem),
+      },
+      encryptKeyPair: {
+        publicKey: crypto.createPublicKey(encPubPem),
+        privateKey: crypto.createPrivateKey(encPrivPem),
+      },
+    };
+
+    this.keyStore.set(requestId, keys);
+  }
 }

package/src/crypto.ts

@@ -7,6 +7,21 @@ export interface KeyPair {
   encryptPublicKey: string;
 }
 
+export interface EncryptedPayload {
+  ciphertext: string;
+  iv: string;
+  authTag: string;
+  signature: string;
+  messageId: string;
+}
+
+export interface KeyMaterial {
+  signPublicKey: string;
+  encryptPublicKey: string;
+  signKeyPair: { publicKey: crypto.KeyObject; privateKey: crypto.KeyObject };
+  encryptKeyPair: { publicKey: crypto.KeyObject; privateKey: crypto.KeyObject };
+}
+
 /**
  * Generate ephemeral Ed25519 + X25519 key pairs in memory.
  * Returns hex-encoded DER public keys for the HeySummon API.
@@ -203,3 +218,133 @@ export function decrypt(
 
   return Buffer.concat([decipher.update(ciphertextBuf), decipher.final()]).toString("utf8");
 }
+
+/**
+ * Generate full key material (Ed25519 + X25519) with retained private keys.
+ * Unlike generateEphemeralKeys(), private keys are kept as KeyObject instances
+ * for use with encryptWithKeys/decryptWithKeys.
+ */
+export function generateKeyMaterial(): KeyMaterial {
+  const signKeyPair = crypto.generateKeyPairSync("ed25519");
+  const encryptKeyPair = crypto.generateKeyPairSync("x25519");
+
+  return {
+    signPublicKey: signKeyPair.publicKey
+      .export({ type: "spki", format: "der" })
+      .toString("hex"),
+    encryptPublicKey: encryptKeyPair.publicKey
+      .export({ type: "spki", format: "der" })
+      .toString("hex"),
+    signKeyPair,
+    encryptKeyPair,
+  };
+}
+
+/**
+ * Reconstruct a crypto.KeyObject from a hex-encoded DER public key.
+ */
+export function publicKeyFromHex(
+  hex: string,
+  type: "ed25519" | "x25519"
+): crypto.KeyObject {
+  const derBuffer = Buffer.from(hex, "hex");
+  return crypto.createPublicKey({
+    key: derBuffer,
+    format: "der",
+    type: "spki",
+  });
+}
+
+/**
+ * Encrypt plaintext using KeyObject instances directly (no file I/O).
+ * Same X25519 DH + HKDF + AES-256-GCM + Ed25519 signing as encrypt().
+ */
+export function encryptWithKeys(
+  plaintext: string,
+  recipientEncryptPub: crypto.KeyObject,
+  ownSignPriv: crypto.KeyObject,
+  ownEncPriv: crypto.KeyObject,
+  messageId?: string
+): EncryptedPayload {
+  const sharedSecret = crypto.diffieHellman({
+    privateKey: ownEncPriv,
+    publicKey: recipientEncryptPub,
+  });
+
+  const msgId = messageId || crypto.randomUUID();
+
+  const messageKey = crypto.hkdfSync(
+    "sha256",
+    sharedSecret,
+    msgId,
+    "heysummon-msg",
+    32
+  );
+
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv(
+    "aes-256-gcm",
+    Buffer.from(messageKey),
+    iv
+  );
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, "utf8"),
+    cipher.final(),
+  ]);
+  const authTag = cipher.getAuthTag();
+
+  const signature = crypto.sign(null, encrypted, ownSignPriv);
+
+  return {
+    ciphertext: encrypted.toString("base64"),
+    iv: iv.toString("base64"),
+    authTag: authTag.toString("base64"),
+    signature: signature.toString("base64"),
+    messageId: msgId,
+  };
+}
+
+/**
+ * Decrypt an encrypted payload using KeyObject instances directly (no file I/O).
+ * Verifies the Ed25519 signature before decrypting.
+ */
+export function decryptWithKeys(
+  payload: EncryptedPayload,
+  senderEncryptPub: crypto.KeyObject,
+  senderSignPub: crypto.KeyObject,
+  ownEncPriv: crypto.KeyObject
+): string {
+  const ciphertextBuf = Buffer.from(payload.ciphertext, "base64");
+  const valid = crypto.verify(
+    null,
+    ciphertextBuf,
+    senderSignPub,
+    Buffer.from(payload.signature, "base64")
+  );
+
+  if (!valid) {
+    throw new Error("Signature verification failed");
+  }
+
+  const sharedSecret = crypto.diffieHellman({
+    privateKey: ownEncPriv,
+    publicKey: senderEncryptPub,
+  });
+
+  const messageKey = crypto.hkdfSync(
+    "sha256",
+    sharedSecret,
+    payload.messageId,
+    "heysummon-msg",
+    32
+  );
+
+  const decipher = crypto.createDecipheriv(
+    "aes-256-gcm",
+    Buffer.from(messageKey),
+    Buffer.from(payload.iv, "base64")
+  );
+  decipher.setAuthTag(Buffer.from(payload.authTag, "base64"));
+
+  return Buffer.concat([decipher.update(ciphertextBuf), decipher.final()]).toString("utf8");
+}

package/src/{provider-store.ts → expert-store.ts}

@@ -1,59 +1,59 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { dirname } from "path";
-import type { Provider } from "./types.js";
+import type { Expert } from "./types.js";
 
-interface ProvidersFile {
-  providers: Provider[];
+interface ExpertsFile {
+  experts: Expert[];
 }
 
 /**
  * Typed replacement for the inline `node -e` JSON manipulation in the bash scripts.
- * Reads/writes providers.json with deduplication by API key and case-insensitive name.
+ * Reads/writes experts.json with deduplication by API key and case-insensitive name.
  */
-export class ProviderStore {
+export class ExpertStore {
   private readonly filePath: string;
 
   constructor(filePath: string) {
     this.filePath = filePath;
   }
 
-  load(): Provider[] {
+  load(): Expert[] {
     if (!existsSync(this.filePath)) return [];
     try {
-      const data = JSON.parse(readFileSync(this.filePath, "utf8")) as ProvidersFile;
-      return Array.isArray(data.providers) ? data.providers : [];
+      const data = JSON.parse(readFileSync(this.filePath, "utf8")) as ExpertsFile;
+      return Array.isArray(data.experts) ? data.experts : [];
     } catch {
       return [];
     }
   }
 
-  save(providers: Provider[]): void {
+  save(experts: Expert[]): void {
     const dir = dirname(this.filePath);
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true });
     }
-    writeFileSync(this.filePath, JSON.stringify({ providers }, null, 2));
+    writeFileSync(this.filePath, JSON.stringify({ experts }, null, 2));
   }
 
   /**
-   * Add or update a provider entry.
+   * Add or update an expert entry.
    * Deduplicates by API key and case-insensitive name (same logic as the bash script).
    */
-  add(entry: Omit<Provider, "addedAt" | "nameLower"> & { addedAt?: string }): Provider {
-    const providers = this.load();
+  add(entry: Omit<Expert, "addedAt" | "nameLower"> & { addedAt?: string }): Expert {
+    const experts = this.load();
     const nameLower = entry.name.toLowerCase();
 
     // Remove existing entries with same key or name (case-insensitive)
-    const filtered = providers.filter(
+    const filtered = experts.filter(
       (p) => p.apiKey !== entry.apiKey && p.nameLower !== nameLower
     );
 
-    const newEntry: Provider = {
+    const newEntry: Expert = {
       name: entry.name,
       nameLower,
       apiKey: entry.apiKey,
-      providerId: entry.providerId,
-      providerName: entry.providerName,
+      expertId: entry.expertId,
+      expertName: entry.expertName,
       addedAt: entry.addedAt ?? new Date().toISOString(),
     };
 
@@ -63,25 +63,25 @@ export class ProviderStore {
   }
 
   /** Case-insensitive lookup by name or alias */
-  findByName(name: string): Provider | undefined {
+  findByName(name: string): Expert | undefined {
     const lower = name.toLowerCase();
     return this.load().find((p) => p.nameLower === lower || p.name.toLowerCase() === lower);
   }
 
   /** Look up by exact API key */
-  findByKey(apiKey: string): Provider | undefined {
+  findByKey(apiKey: string): Expert | undefined {
     return this.load().find((p) => p.apiKey === apiKey);
   }
 
-  /** Returns the first provider (default when only one is registered) */
-  getDefault(): Provider | undefined {
+  /** Returns the first expert (default when only one is registered) */
+  getDefault(): Expert | undefined {
     return this.load()[0];
   }
 
   remove(apiKey: string): boolean {
-    const providers = this.load();
-    const filtered = providers.filter((p) => p.apiKey !== apiKey);
-    if (filtered.length === providers.length) return false;
+    const experts = this.load();
+    const filtered = experts.filter((p) => p.apiKey !== apiKey);
+    if (filtered.length === experts.length) return false;
     this.save(filtered);
     return true;
   }

package/src/index.ts

@@ -1,23 +1,26 @@
 export { HeySummonClient, HeySummonHttpError } from "./client.js";
-export { PollingWatcher } from "./poller.js";
-export { ProviderStore } from "./provider-store.js";
-export { RequestTracker } from "./request-tracker.js";
+export { ExpertStore } from "./expert-store.js";
 export {
   generateEphemeralKeys,
   generatePersistentKeys,
   loadPublicKeys,
   encrypt,
   decrypt,
+  generateKeyMaterial,
+  publicKeyFromHex,
+  encryptWithKeys,
+  decryptWithKeys,
 } from "./crypto.js";
 export type {
-  Provider,
+  Expert,
   SubmitRequestOptions,
   SubmitRequestResult,
   PendingEvent,
   Message,
+  DecryptedMessage,
+  MessagesResponse,
   RequestStatusResponse,
   WhoamiResult,
   HeySummonClientOptions,
 } from "./types.js";
-export type { PollingWatcherOptions } from "./poller.js";
-export type { KeyPair } from "./crypto.js";
+export type { KeyPair, KeyMaterial, EncryptedPayload } from "./crypto.js";