@agentvault/secure-channel 0.4.0 → 0.4.2

package/README.md

@@ -0,0 +1,229 @@
+# @agentvault/secure-channel
+
+End-to-end encrypted communication channel for AI agents on the [AgentVault](https://agentvault.chat) platform. Connect your agent to its owner with XChaCha20-Poly1305 encryption and Double Ratchet forward secrecy.
+
+## What's New in v0.4.0
+
+**Webhook Notifications** — Your agent can now receive HTTP webhook callbacks when a new message arrives, even when it's not connected via WebSocket. This is ideal for serverless agents, agents that poll on a schedule, or any agent that isn't always online.
+
+### Upgrading from v0.3.x
+
+```bash
+npm install @agentvault/secure-channel@latest
+```
+
+Add `webhookUrl` to your config to enable:
+
+```js
+const channel = new SecureChannel({
+  inviteToken: "your-token",
+  dataDir: "./agentvault-data",
+  apiUrl: "https://api.agentvault.chat",
+  webhookUrl: "https://your-server.com/webhook/agentvault", // NEW in 0.4.0
+});
+```
+
+No other code changes required — fully backward-compatible.
+
+---
+
+## Installation
+
+```bash
+npm install @agentvault/secure-channel
+```
+
+## Quick Start
+
+### Option 1: CLI (Interactive)
+
+Run directly with npx using the invite token from your AgentVault dashboard:
+
+```bash
+npx @agentvault/secure-channel --token=YOUR_INVITE_TOKEN
+```
+
+The CLI will:
+1. Enroll your agent with the server
+2. Display a fingerprint for the owner to verify
+3. Wait for owner approval
+4. Establish an encrypted channel
+5. Enter interactive mode where you can send/receive messages
+
+**CLI Flags:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--token` | (required on first run) | Invite token from dashboard |
+| `--name` | `"CLI Agent"` | Agent display name |
+| `--data-dir` | `./agentvault-data` | Directory for persistent state |
+| `--api-url` | `https://api.agentvault.chat` | API endpoint |
+
+Environment variables (`AGENTVAULT_INVITE_TOKEN`, `AGENTVAULT_AGENT_NAME`, `AGENTVAULT_DATA_DIR`, `AGENTVAULT_API_URL`) work as alternatives to flags.
+
+### Option 2: SDK (Programmatic)
+
+```js
+import { SecureChannel } from "@agentvault/secure-channel";
+
+const channel = new SecureChannel({
+  inviteToken: "YOUR_INVITE_TOKEN",
+  dataDir: "./agentvault-data",
+  apiUrl: "https://api.agentvault.chat",
+  agentName: "My Agent",
+});
+
+channel.on("message", (text, metadata) => {
+  console.log(`Received: ${text}`);
+  // Echo back
+  channel.send(`You said: ${text}`);
+});
+
+channel.on("ready", () => {
+  console.log("Secure channel established!");
+});
+
+await channel.start();
+```
+
+---
+
+## Webhook Notifications (v0.4.0+)
+
+Enable webhook notifications so your agent gets an HTTP POST when a new message arrives — useful for agents that aren't always connected via WebSocket.
+
+### Setup
+
+Add `webhookUrl` to your config:
+
+```js
+const channel = new SecureChannel({
+  inviteToken: "YOUR_INVITE_TOKEN",
+  dataDir: "./agentvault-data",
+  apiUrl: "https://api.agentvault.chat",
+  webhookUrl: "https://your-server.com/webhook/agentvault",
+});
+```
+
+The webhook URL is registered automatically during device activation. The channel emits a `webhook_registered` event on success:
+
+```js
+channel.on("webhook_registered", ({ url, secret }) => {
+  console.log(`Webhook registered at ${url}`);
+  // Save the secret to verify incoming webhooks
+});
+```
+
+### Webhook Payload
+
+When the owner sends a message, your webhook endpoint receives:
+
+```http
+POST /webhook/agentvault HTTP/1.1
+Content-Type: application/json
+X-AgentVault-Event: new_message
+X-AgentVault-Signature: sha256=<hmac-hex>
+
+{
+  "event": "new_message",
+  "conversation_id": "uuid",
+  "sender_device_id": "uuid",
+  "message_id": "uuid",
+  "timestamp": "2026-02-17T12:00:00Z"
+}
+```
+
+### Verifying Webhook Signatures
+
+Each webhook includes an HMAC-SHA256 signature in the `X-AgentVault-Signature` header. Verify it using the secret from the `webhook_registered` event:
+
+```js
+import crypto from "crypto";
+
+function verifyWebhook(body, signature, secret) {
+  const expected = "sha256=" +
+    crypto.createHmac("sha256", secret).update(body).digest("hex");
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expected),
+  );
+}
+```
+
+---
+
+## Configuration Reference
+
+```ts
+interface SecureChannelConfig {
+  // Required
+  inviteToken: string;       // Invite token from the AgentVault dashboard
+  dataDir: string;           // Directory for persistent state files
+  apiUrl: string;            // API endpoint (e.g., "https://api.agentvault.chat")
+
+  // Optional
+  agentName?: string;        // Display name (default: "CLI Agent")
+  platform?: string;         // Platform identifier (e.g., "node")
+  maxHistorySize?: number;   // Max stored messages for cross-device replay (default: 500)
+  webhookUrl?: string;       // Webhook URL for new message notifications (v0.4.0+)
+
+  // Callbacks (alternative to event listeners)
+  onMessage?: (text: string, metadata: MessageMetadata) => void;
+  onStateChange?: (state: ChannelState) => void;
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `message` | `(text: string, metadata: MessageMetadata)` | Owner sent a message |
+| `ready` | none | WebSocket connected, channel operational |
+| `state` | `(state: ChannelState)` | State transition occurred |
+| `error` | `(error: Error)` | Fatal error |
+| `webhook_registered` | `({ url: string, secret: string })` | Webhook registered (v0.4.0+) |
+
+## Channel States
+
+`idle` → `enrolling` → `polling` → `activating` → `connecting` → `ready`
+
+If disconnected: `ready` → `disconnected` → `connecting` → `ready` (auto-reconnect)
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `start()` | Initialize, enroll, and connect |
+| `send(text)` | Encrypt and send message to all owner devices |
+| `stop()` | Gracefully disconnect |
+
+| Property | Description |
+|----------|-------------|
+| `state` | Current channel state |
+| `deviceId` | Agent's device ID (after enrollment) |
+| `fingerprint` | Device fingerprint for verification |
+| `conversationId` | Primary conversation ID |
+| `conversationIds` | All active conversation IDs (multi-device) |
+| `sessionCount` | Number of active encrypted sessions |
+
+## Multi-Device Support
+
+AgentVault supports multiple owner devices (e.g., desktop + mobile). The channel automatically:
+- Maintains independent encrypted sessions per owner device
+- Fans out `send()` to all active sessions
+- Stores message history for cross-device replay (up to `maxHistorySize`)
+- Replays history when a new device connects
+
+No additional configuration needed — multi-device is handled transparently.
+
+## Security
+
+- **XChaCha20-Poly1305** symmetric encryption (192-bit nonces)
+- **X3DH** key agreement (Ed25519 + X25519)
+- **Double Ratchet** for forward secrecy — old keys deleted after use
+- **Zero-knowledge server** — the server never sees plaintext
+- **HMAC-SHA256** webhook signatures for authenticity verification
+
+## License
+
+MIT

package/dist/channel.d.ts

@@ -33,8 +33,28 @@ export declare class SecureChannel extends EventEmitter {
      * Encrypt and send a message to ALL owner devices (fanout).
      * Each session gets the same plaintext encrypted independently.
      */
-    send(plaintext: string): Promise<void>;
+    send(plaintext: string, options?: {
+        topicId?: string;
+    }): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * Create a new topic within the conversation group.
+     * Requires the channel to be initialized with a groupId (from activation).
+     */
+    createTopic(name: string): Promise<{
+        id: string;
+        name: string;
+        isDefault: boolean;
+    }>;
+    /**
+     * List all topics in the conversation group.
+     * Requires the channel to be initialized with a groupId (from activation).
+     */
+    listTopics(): Promise<Array<{
+        id: string;
+        name: string;
+        isDefault: boolean;
+    }>>;
     private _enroll;
     private _poll;
     private _activate;

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAa3C,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EAKb,MAAM,YAAY,CAAC;AAiDpB,qBAAa,aAAc,SAAQ,YAAY;IAiBjC,OAAO,CAAC,MAAM;IAhB1B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,sBAAsB,CAAc;IAC5C,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,SAAS,CAGH;IACd,OAAO,CAAC,GAAG,CAA0B;IACrC,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,eAAe,CAA8C;IACrE,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,UAAU,CAA+B;gBAE7B,MAAM,EAAE,mBAAmB;IAI/C,IAAI,KAAK,IAAI,YAAY,CAExB;IAED,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IAED,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IAED,iEAAiE;IACjE,IAAI,cAAc,IAAI,MAAM,GAAG,IAAI,CAElC;IAED,2CAA2C;IAC3C,IAAI,eAAe,IAAI,MAAM,EAAE,CAE9B;IAED,6CAA6C;IAC7C,IAAI,YAAY,IAAI,MAAM,CAEzB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsC5B;;OAEG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;OAGG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCtC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAoBb,OAAO;IAgDrB,OAAO,CAAC,KAAK;YAgCC,SAAS;IA2HvB,OAAO,CAAC,QAAQ;IA4DhB;;;;OAIG;YACW,sBAAsB;IAoFpC;;;OAGG;YACW,oBAAoB;IAmClC;;;OAGG;YACW,uBAAuB;IAkCrC;;;;OAIG;YACW,mBAAmB;IAkEjC;;;OAGG;YACW,mBAAmB;IAwFjC,OAAO,CAAC,kBAAkB;IAgB1B,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,YAAY;IAKpB;;;OAGG;YACW,aAAa;CAc5B"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAa3C,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EAKb,MAAM,YAAY,CAAC;AAiDpB,qBAAa,aAAc,SAAQ,YAAY;IAiBjC,OAAO,CAAC,MAAM;IAhB1B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,sBAAsB,CAAc;IAC5C,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,SAAS,CAGH;IACd,OAAO,CAAC,GAAG,CAA0B;IACrC,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,eAAe,CAA8C;IACrE,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,UAAU,CAA+B;gBAE7B,MAAM,EAAE,mBAAmB;IAI/C,IAAI,KAAK,IAAI,YAAY,CAExB;IAED,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IAED,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IAED,iEAAiE;IACjE,IAAI,cAAc,IAAI,MAAM,GAAG,IAAI,CAElC;IAED,2CAA2C;IAC3C,IAAI,eAAe,IAAI,MAAM,EAAE,CAE9B;IAED,6CAA6C;IAC7C,IAAI,YAAY,IAAI,MAAM,CAEzB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsC5B;;OAEG;IACH,OAAO,CAAC,cAAc;IAuBtB;;;OAGG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCtE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B;;;OAGG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IAsC1F;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;YAiCtE,OAAO;IAgDrB,OAAO,CAAC,KAAK;YAgCC,SAAS;IAyIvB,OAAO,CAAC,QAAQ;IAsEhB;;;;OAIG;YACW,sBAAsB;IAwFpC;;;OAGG;YACW,oBAAoB;IAqClC;;;OAGG;YACW,uBAAuB;IAkCrC;;;;OAIG;YACW,mBAAmB;IAkEjC;;;OAGG;YACW,mBAAmB;IA4FjC,OAAO,CAAC,kBAAkB;IAiB1B,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,YAAY;IAKpB;;;OAGG;YACW,aAAa;CAc5B"}

package/dist/cli.js

@@ -45129,17 +45129,21 @@ var SecureChannel = class extends EventEmitter {
   /**
    * Append a message to persistent history for cross-device replay.
    */
-  _appendHistory(sender, text) {
+  _appendHistory(sender, text, topicId) {
     if (!this._persisted) return;
     if (!this._persisted.messageHistory) {
       this._persisted.messageHistory = [];
     }
     const maxSize = this.config.maxHistorySize ?? 500;
-    this._persisted.messageHistory.push({
+    const entry = {
       sender,
       text,
       ts: (/* @__PURE__ */ new Date()).toISOString()
-    });
+    };
+    if (topicId) {
+      entry.topicId = topicId;
+    }
+    this._persisted.messageHistory.push(entry);
     if (this._persisted.messageHistory.length > maxSize) {
       this._persisted.messageHistory = this._persisted.messageHistory.slice(-maxSize);
     }
@@ -45148,11 +45152,12 @@ var SecureChannel = class extends EventEmitter {
    * Encrypt and send a message to ALL owner devices (fanout).
    * Each session gets the same plaintext encrypted independently.
    */
-  async send(plaintext) {
+  async send(plaintext, options) {
     if (this._state !== "ready" || this._sessions.size === 0 || !this._ws) {
       throw new Error("Channel is not ready");
     }
-    this._appendHistory("agent", plaintext);
+    const topicId = options?.topicId ?? this._persisted?.defaultTopicId;
+    this._appendHistory("agent", plaintext, topicId);
     const messageGroupId = randomUUID();
     for (const [convId, session] of this._sessions) {
       if (!session.activated) {
@@ -45167,7 +45172,8 @@ var SecureChannel = class extends EventEmitter {
             conversation_id: convId,
             header_blob: transport.header_blob,
             ciphertext: transport.ciphertext,
-            message_group_id: messageGroupId
+            message_group_id: messageGroupId,
+            topic_id: topicId
           }
         })
       );
@@ -45191,6 +45197,72 @@ var SecureChannel = class extends EventEmitter {
     }
     this._setState("disconnected");
   }
+  // --- Topic management ---
+  /**
+   * Create a new topic within the conversation group.
+   * Requires the channel to be initialized with a groupId (from activation).
+   */
+  async createTopic(name2) {
+    if (!this._persisted?.groupId) {
+      throw new Error("Channel not initialized or groupId unknown");
+    }
+    if (!this._deviceJwt) {
+      throw new Error("Channel not authenticated");
+    }
+    const res = await fetch(`${this.config.apiUrl}/api/v1/topics`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this._deviceJwt}`
+      },
+      body: JSON.stringify({
+        group_id: this._persisted.groupId,
+        name: name2,
+        creator_device_id: this._persisted.deviceId
+      })
+    });
+    if (!res.ok) {
+      const detail = await res.text();
+      throw new Error(`Create topic failed (${res.status}): ${detail}`);
+    }
+    const resp = await res.json();
+    const topic = { id: resp.id, name: resp.name, isDefault: resp.is_default };
+    if (!this._persisted.topics) {
+      this._persisted.topics = [];
+    }
+    this._persisted.topics.push(topic);
+    await this._persistState();
+    return topic;
+  }
+  /**
+   * List all topics in the conversation group.
+   * Requires the channel to be initialized with a groupId (from activation).
+   */
+  async listTopics() {
+    if (!this._persisted?.groupId) {
+      throw new Error("Channel not initialized or groupId unknown");
+    }
+    if (!this._deviceJwt) {
+      throw new Error("Channel not authenticated");
+    }
+    const res = await fetch(
+      `${this.config.apiUrl}/api/v1/topics?group_id=${encodeURIComponent(this._persisted.groupId)}`,
+      {
+        headers: {
+          Authorization: `Bearer ${this._deviceJwt}`
+        }
+      }
+    );
+    if (!res.ok) {
+      const detail = await res.text();
+      throw new Error(`List topics failed (${res.status}): ${detail}`);
+    }
+    const resp = await res.json();
+    const topics = resp.map((t2) => ({ id: t2.id, name: t2.name, isDefault: t2.is_default }));
+    this._persisted.topics = topics;
+    await this._persistState();
+    return topics;
+  }
   // --- Internal lifecycle ---
   async _enroll() {
     this._setState("enrolling");
@@ -45317,6 +45389,15 @@ var SecureChannel = class extends EventEmitter {
         sessions,
         messageHistory: this._persisted.messageHistory ?? []
       };
+      if (conversations.length > 0) {
+        const firstConv = conversations[0];
+        if (firstConv.group_id) {
+          this._persisted.groupId = firstConv.group_id;
+        }
+        if (firstConv.default_topic_id) {
+          this._persisted.defaultTopicId = firstConv.default_topic_id;
+        }
+      }
       await saveState(this.config.dataDir, this._persisted);
       if (this.config.webhookUrl) {
         try {
@@ -45354,6 +45435,14 @@ var SecureChannel = class extends EventEmitter {
   }
   _connect() {
     if (this._stopped) return;
+    if (this._ws) {
+      this._ws.removeAllListeners();
+      try {
+        this._ws.close();
+      } catch {
+      }
+      this._ws = null;
+    }
     this._setState("connecting");
     const wsUrl = this.config.apiUrl.replace(/^http/, "ws");
     const url = `${wsUrl}/api/v1/ws?token=${encodeURIComponent(this._deviceJwt)}&device_id=${this._deviceId}`;
@@ -45438,15 +45527,17 @@ var SecureChannel = class extends EventEmitter {
       return;
     }
     if (messageType === "message") {
-      this._appendHistory("owner", messageText);
+      const topicId = msgData.topic_id;
+      this._appendHistory("owner", messageText, topicId);
       const metadata = {
         messageId: msgData.message_id,
         conversationId: convId,
-        timestamp: msgData.created_at
+        timestamp: msgData.created_at,
+        topicId
       };
       this.emit("message", messageText, metadata);
       this.config.onMessage?.(messageText, metadata);
-      await this._relaySyncToSiblings(convId, session.ownerDeviceId, messageText);
+      await this._relaySyncToSiblings(convId, session.ownerDeviceId, messageText, topicId);
     }
     if (this._persisted) {
       this._persisted.lastMessageTimestamp = msgData.created_at;
@@ -45457,13 +45548,14 @@ var SecureChannel = class extends EventEmitter {
    * Relay an owner's message to all sibling sessions as encrypted sync messages.
    * This allows all owner devices to see messages from any single device.
    */
-  async _relaySyncToSiblings(sourceConvId, senderOwnerDeviceId, messageText) {
+  async _relaySyncToSiblings(sourceConvId, senderOwnerDeviceId, messageText, topicId) {
     if (!this._ws || this._sessions.size <= 1) return;
     const syncPayload = JSON.stringify({
       type: "sync",
       sender: senderOwnerDeviceId,
       text: messageText,
-      ts: (/* @__PURE__ */ new Date()).toISOString()
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      topicId
     });
     for (const [siblingConvId, siblingSession] of this._sessions) {
       if (siblingConvId === sourceConvId) continue;
@@ -45613,11 +45705,13 @@ var SecureChannel = class extends EventEmitter {
             messageText = plaintext;
           }
           if (messageType === "message") {
-            this._appendHistory("owner", messageText);
+            const topicId = msg.topic_id;
+            this._appendHistory("owner", messageText, topicId);
             const metadata = {
               messageId: msg.id,
               conversationId: msg.conversation_id,
-              timestamp: msg.created_at
+              timestamp: msg.created_at,
+              topicId
             };
             this.emit("message", messageText, metadata);
             this.config.onMessage?.(messageText, metadata);
@@ -45634,6 +45728,7 @@ var SecureChannel = class extends EventEmitter {
   }
   _scheduleReconnect() {
     if (this._stopped) return;
+    if (this._reconnectTimer) return;
     const delay = Math.min(
       RECONNECT_BASE_MS * Math.pow(2, this._reconnectAttempt),
       RECONNECT_MAX_MS