hiloop-sdk 0.1.0 → 0.2.0

package/dist/client.d.ts

@@ -27,7 +27,18 @@ export declare class HiloopClient {
     private crypto;
     private secretKeyB64;
     private publicKeyB64;
+    private initialized;
+    private initPromise;
+    private options;
     constructor(options: HiloopClientOptions);
+    /**
+     * Initialize encryption: derive keypair from API key, register public key,
+     * and fetch space encryption info. Called automatically on first API call.
+     */
+    private ensureInitialized;
+    private doInit;
+    /** Raw HTTP request without triggering auto-init (used during init itself). */
+    private rawRequest;
     private encryptField;
     /**
      * Encrypt multiple fields with a SINGLE shared content key (AES-256-GCM).

package/dist/client.js

@@ -1,5 +1,5 @@
 /** Hiloop SDK client for agents to interact with the Hiloop platform. */
-import { CryptoContext, decryptAes, deriveWrappingKey, encryptAes, generateKeyPair } from "./crypto.js";
+import { CryptoContext, computeFingerprint, decryptAes, deriveKeyPairFromApiKey, deriveWrappingKey, encryptAes, generateKeyPair } from "./crypto.js";
 import { parseChannel, parseChannelMessage, parseChannelParticipant, parseConvSession, parseConvSessionMessage, parseGuestToken, parseInteraction, parseMessage, } from "./types.js";
 export class HiloopError extends Error {
     constructor(statusCode, message) {
@@ -10,12 +10,99 @@ export class HiloopError extends Error {
 }
 export class HiloopClient {
     constructor(options) {
+        this.secretKeyB64 = "";
+        this.publicKeyB64 = "";
+        this.initialized = false;
+        this.initPromise = null;
         this.apiKey = options.apiKey;
-        this.baseUrl = (options.baseUrl ?? "http://localhost:8000").replace(/\/$/, "");
+        this.baseUrl = (options.baseUrl ?? "https://api.hi-loop.com").replace(/\/$/, "");
         this.timeout = options.timeout ?? 30000;
-        this.secretKeyB64 = options.secretKey ?? "";
-        this.publicKeyB64 = options.publicKey ?? "";
-        this.crypto = new CryptoContext(options.secretKey ?? "", options.publicKey ?? "", options.spacePublicKey ?? "", options.spaceKeyId ?? "", options.serverKeyId);
+        this.options = options;
+        // If all crypto keys provided, initialize synchronously (advanced usage)
+        if (options.secretKey && options.publicKey && options.spacePublicKey && options.spaceKeyId) {
+            this.secretKeyB64 = options.secretKey;
+            this.publicKeyB64 = options.publicKey;
+            this.crypto = new CryptoContext(options.secretKey, options.publicKey, options.spacePublicKey, options.spaceKeyId, options.serverKeyId);
+            this.initialized = true;
+        }
+        else {
+            // Placeholder — real init happens lazily on first API call
+            this.crypto = new CryptoContext("", "", "", "");
+        }
+    }
+    /**
+     * Initialize encryption: derive keypair from API key, register public key,
+     * and fetch space encryption info. Called automatically on first API call.
+     */
+    async ensureInitialized() {
+        if (this.initialized)
+            return;
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = this.doInit();
+        await this.initPromise;
+    }
+    async doInit() {
+        // 1. Derive keypair from API key (or use provided keys)
+        let secretKey = this.options.secretKey;
+        let publicKey = this.options.publicKey;
+        if (!secretKey || !publicKey) {
+            const kp = await deriveKeyPairFromApiKey(this.apiKey);
+            secretKey = kp.secretKey;
+            publicKey = kp.publicKey;
+        }
+        this.secretKeyB64 = secretKey;
+        this.publicKeyB64 = publicKey;
+        // 2. Register agent public key (idempotent)
+        const fingerprint = await computeFingerprint(publicKey);
+        try {
+            const existing = await this.rawRequest("GET", "/agent/keys/me");
+            if (existing.fingerprint !== fingerprint) {
+                await this.rawRequest("PUT", "/agent/keys/me", { body: { publicKey, fingerprint } });
+            }
+        }
+        catch {
+            try {
+                await this.rawRequest("PUT", "/agent/keys/me", { body: { publicKey, fingerprint } });
+            }
+            catch {
+                // Non-fatal — key registration may fail in dev environments
+            }
+        }
+        // 3. Fetch space encryption info
+        let spacePublicKey = this.options.spacePublicKey ?? "";
+        let spaceKeyId = this.options.spaceKeyId ?? "";
+        if (!spacePublicKey || !spaceKeyId) {
+            try {
+                const info = await this.rawRequest("GET", "/agent/encryption-info");
+                spacePublicKey = info.spacePublicKey;
+                spaceKeyId = info.spaceKeyId;
+            }
+            catch {
+                // Space key not available — crypto operations will fail but non-crypto calls work
+            }
+        }
+        // 4. Create CryptoContext
+        this.crypto = new CryptoContext(secretKey, publicKey, spacePublicKey, spaceKeyId, this.options.serverKeyId);
+        this.initialized = true;
+    }
+    /** Raw HTTP request without triggering auto-init (used during init itself). */
+    async rawRequest(method, path, options) {
+        const url = `${this.baseUrl}/v1${path}`;
+        const headers = {
+            "Content-Type": "application/json",
+            "X-API-Key": this.apiKey,
+        };
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: options?.body ? JSON.stringify(options.body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new HiloopError(res.status, text);
+        }
+        return await res.json();
     }
     encryptField(text) {
         return this.crypto.encryptForApi(text);
@@ -59,6 +146,7 @@ export class HiloopClient {
         return btoa(binary);
     }
     async request(method, path, options) {
+        await this.ensureInitialized();
         let url = `${this.baseUrl}/v1${path}`;
         if (options?.params !== undefined) {
             const qs = new URLSearchParams(options.params).toString();
@@ -89,6 +177,7 @@ export class HiloopClient {
     }
     /** Fetch binary content (e.g. file download). Returns raw ArrayBuffer. */
     async requestBinary(path) {
+        await this.ensureInitialized();
         const url = `${this.baseUrl}/v1${path}`;
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeout);

package/dist/crypto.d.ts

@@ -3,8 +3,16 @@ export interface KeyPair {
     publicKey: string;
     secretKey: string;
 }
-/** Generate an X25519 keypair. */
+/** Generate a random X25519 keypair. */
 export declare function generateKeyPair(): KeyPair;
+/**
+ * Derive a deterministic X25519 keypair from an API key.
+ * Uses HKDF-SHA256 with context "hiloop-agent-encrypt-v1" — same derivation
+ * as the MCP server, so the same API key produces the same keypair everywhere.
+ */
+export declare function deriveKeyPairFromApiKey(apiKey: string): Promise<KeyPair>;
+/** Compute SHA-256 fingerprint of a base64 public key string. */
+export declare function computeFingerprint(publicKeyBase64: string): Promise<string>;
 /** Encrypt plaintext for a recipient using NaCl box. Returns base64 ciphertext. */
 export declare function encrypt(plaintext: string, senderSecretKeyB64: string, recipientPublicKeyB64: string): string;
 /** Decrypt base64 ciphertext. Returns plaintext. */

package/dist/crypto.js

@@ -1,7 +1,7 @@
 /** E2E encryption for the Hiloop SDK using tweetnacl (X25519 + XSalsa20-Poly1305). */
 import nacl from "tweetnacl";
 import util from "tweetnacl-util";
-/** Generate an X25519 keypair. */
+/** Generate a random X25519 keypair. */
 export function generateKeyPair() {
     const kp = nacl.box.keyPair();
     return {
@@ -9,6 +9,32 @@ export function generateKeyPair() {
         secretKey: util.encodeBase64(kp.secretKey),
     };
 }
+/**
+ * Derive a deterministic X25519 keypair from an API key.
+ * Uses HKDF-SHA256 with context "hiloop-agent-encrypt-v1" — same derivation
+ * as the MCP server, so the same API key produces the same keypair everywhere.
+ */
+export async function deriveKeyPairFromApiKey(apiKey) {
+    const keyMaterial = await crypto.subtle.importKey("raw", new TextEncoder().encode(apiKey), "HKDF", false, ["deriveBits"]);
+    const secretKeyBits = await crypto.subtle.deriveBits({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new Uint8Array(32),
+        info: new TextEncoder().encode("hiloop-agent-encrypt-v1"),
+    }, keyMaterial, 256);
+    const secretKey = new Uint8Array(secretKeyBits);
+    const kp = nacl.box.keyPair.fromSecretKey(secretKey);
+    return {
+        publicKey: util.encodeBase64(kp.publicKey),
+        secretKey: util.encodeBase64(kp.secretKey),
+    };
+}
+/** Compute SHA-256 fingerprint of a base64 public key string. */
+export async function computeFingerprint(publicKeyBase64) {
+    const data = new TextEncoder().encode(publicKeyBase64);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
 /** Encrypt plaintext for a recipient using NaCl box. Returns base64 ciphertext. */
 export function encrypt(plaintext, senderSecretKeyB64, recipientPublicKeyB64) {
     const sk = util.decodeBase64(senderSecretKeyB64);

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { HiloopClient, HiloopError } from "./client.js";
 export type { HiloopClientOptions } from "./client.js";
-export { generateKeyPair, encrypt, decrypt, encryptAes, decryptAes, deriveWrappingKey, CryptoContext } from "./crypto.js";
+export { generateKeyPair, deriveKeyPairFromApiKey, computeFingerprint, encrypt, decrypt, encryptAes, decryptAes, deriveWrappingKey, CryptoContext } from "./crypto.js";
 export type { KeyPair, ContentWrappingResult } from "./crypto.js";
 export type { Interaction, InteractionType, InteractionStatus, Priority, Message, PaginatedResult, CreateInteractionOptions, ConvSession, ConvSessionType, ConvSessionStatus, ConvSessionRole, ConvSessionParticipant, ConvSessionMessage, GuestToken, CreateConvSessionOptions, Channel, ChannelStatus, ChannelMessage, ChannelParticipant, CreateChannelOptions, FileChangeStatus, CommandInvocationStatus, AgentCommand, CommandInvocation, } from "./types.js";
 export { parseInteraction, parseMessage, parseConvSession, parseConvSessionMessage, parseGuestToken, parseChannel, parseChannelMessage, parseChannelParticipant, } from "./types.js";

package/dist/index.js

@@ -1,3 +1,3 @@
 export { HiloopClient, HiloopError } from "./client.js";
-export { generateKeyPair, encrypt, decrypt, encryptAes, decryptAes, deriveWrappingKey, CryptoContext } from "./crypto.js";
+export { generateKeyPair, deriveKeyPairFromApiKey, computeFingerprint, encrypt, decrypt, encryptAes, decryptAes, deriveWrappingKey, CryptoContext } from "./crypto.js";
 export { parseInteraction, parseMessage, parseConvSession, parseConvSessionMessage, parseGuestToken, parseChannel, parseChannelMessage, parseChannelParticipant, } from "./types.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hiloop-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript SDK for Hiloop — zero-trust human-AI agent interaction platform",
   "type": "module",
   "main": "dist/index.js",