hiloop-sdk 0.1.0 → 0.3.0

package/dist/client.d.ts

@@ -7,6 +7,8 @@ export declare class HiloopError extends Error {
 }
 export interface HiloopClientOptions {
     apiKey: string;
+    /** Agent name. Auto-creates the agent if it doesn't exist (space API keys only). */
+    agentName?: string;
     baseUrl?: string;
     /** Agent's X25519 secret key (base64). Required for E2E encryption. */
     secretKey?: string;
@@ -27,7 +29,19 @@ 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 buildHeaders;
+    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,104 @@ 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). */
+    buildHeaders() {
+        const h = {
+            "Content-Type": "application/json",
+            "X-API-Key": this.apiKey,
+        };
+        if (this.options.agentName)
+            h["X-Agent"] = this.options.agentName;
+        return h;
+    }
+    async rawRequest(method, path, options) {
+        const url = `${this.baseUrl}/v1${path}`;
+        const res = await fetch(url, {
+            method,
+            headers: this.buildHeaders(),
+            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);
@@ -28,6 +120,7 @@ export class HiloopClient {
      * with the same (scope, recipientKeyId) are silently dropped.
      */
     async encryptFields(fields) {
+        await this.ensureInitialized();
         const encrypted = {};
         const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
         if (entries.length === 0)
@@ -59,6 +152,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();
@@ -70,10 +164,7 @@ export class HiloopClient {
         try {
             const res = await fetch(url, {
                 method,
-                headers: {
-                    "X-API-Key": this.apiKey,
-                    "Content-Type": "application/json",
-                },
+                headers: this.buildHeaders(),
                 body: options?.body !== undefined ? JSON.stringify(options.body) : undefined,
                 signal: controller.signal,
             });
@@ -89,13 +180,14 @@ 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);
         try {
             const res = await fetch(url, {
                 method: "GET",
-                headers: { "X-API-Key": this.apiKey },
+                headers: this.buildHeaders(),
                 signal: controller.signal,
             });
             if (!res.ok) {
@@ -269,6 +361,7 @@ export class HiloopClient {
     }
     /** Push content blocks to an interaction. */
     async pushContentBlocks(interactionId, blocks) {
+        await this.ensureInitialized();
         const encryptedBlocks = await Promise.all(blocks.map(async (block) => {
             const plaintext = JSON.stringify(block.data);
             const wrapped = await this.crypto.encryptWithWrapping(plaintext);
@@ -399,6 +492,7 @@ export class HiloopClient {
     }
     // -- Conversation Sessions -------------------------------------------------
     async createConvSession(opts) {
+        await this.ensureInitialized();
         const body = {
             sessionType: opts.sessionType ?? "direct",
             isPublic: opts.isPublic ?? false,
@@ -458,6 +552,7 @@ export class HiloopClient {
      * using the session message key (`{agentPub}:{AES-GCM ciphertext}` format).
      */
     async sendConvSessionMessage(sessionId, content) {
+        await this.ensureInitialized();
         const encryptedContent = await this.crypto.encryptSessionMessage(content);
         const data = await this.request("POST", `/agent/sessions/${sessionId}/messages`, { body: { encryptedContent } });
         return parseConvSessionMessage(data);
@@ -950,6 +1045,7 @@ export class HiloopClient {
     // -- Channels ---------------------------------------------------------------
     /** Create a new agent-to-agent channel. */
     async createChannel(opts) {
+        await this.ensureInitialized();
         const body = {};
         if (opts.name !== undefined) {
             const w = await this.crypto.encryptWithWrapping(opts.name);
@@ -1006,6 +1102,7 @@ export class HiloopClient {
     }
     /** Send a message in a channel. */
     async sendChannelMessage(channelId, content) {
+        await this.ensureInitialized();
         const wrapped = await this.crypto.encryptWithWrapping(content);
         const body = {
             encryptedContent: wrapped.ciphertext,

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.3.0",
   "description": "TypeScript SDK for Hiloop — zero-trust human-AI agent interaction platform",
   "type": "module",
   "main": "dist/index.js",