# @agentvault/agentvault

The security infrastructure layer for AI agents — cryptographic identity, earned trust, and Signal-grade encrypted communications natively integrated with OpenClaw.

Connect your agent to its owner with XChaCha20-Poly1305 encryption, Double Ratchet forward secrecy, and W3C Decentralized Identifiers (DIDs).

## What's New in v0.14.30 (Gen2)

* **OpenClaw Native Plugin:** AgentVault now integrates directly into OpenClaw as a first-class channel (`agentvault`).
* **W3C Decentralized Identifiers (DIDs):** Agents are now addressed using cryptographic identities (`did:hub:<address>`).
* **Room Cryptography & Sender Keys:** Advanced group chat encryption using sender key distribution, automatic force rekeying, and robust ratchet state snapshot/restore mechanisms.
* **Trust Scoring & Telemetry:** Native OpenTelemetry (OTel) auto-instrumentation to compute real-time trust scores.
* **Skill Permission Tokens (SPTs):** Support for explicit-deny authorization and cryptographic capability access grants.

---

## Installation & Quick Start

### 1. OpenClaw Channel Integration (Recommended)

To install AgentVault globally as an OpenClaw channel plugin:

```bash
# Using pnpm (adjust path to your global installation)
PNPM_HOME=~/Library/pnpm /opt/homebrew/bin/pnpm add -g @agentvault/agentvault@latest
```

After installation, configure the channel with your invite token from the AgentVault dashboard:

```bash
npx @agentvault/agentvault setup --token=YOUR_INVITE_TOKEN
```

⚠️ **CRITICAL WARNING FOR UPGRADES:**
> There is currently a known bug in `setup.js` where running `setup` on an already enrolled agent will wipe the existing account configuration. **Always back up your `agentvault.json` and `agentvault-data` directories before updating the plugin or re-running setup.**

### 2. Standalone CLI Usage

If you are not using OpenClaw, you can run AgentVault as a standalone interactive CLI:

```bash
npx @agentvault/agentvault setup --token=YOUR_INVITE_TOKEN
npx @agentvault/agentvault
```

The CLI will:
1. Generate an Ed25519 identity keypair
2. Enroll your agent with the server (anchoring a `did:hub` identity)
3. Wait for owner approval
4. Establish an end-to-end encrypted channel

---

## Programmatic SDK Integration

You can easily integrate AgentVault directly into custom Node.js/TypeScript agent architectures.

```ts
import { SecureChannel } from "@agentvault/agentvault";

const channel = new SecureChannel({
  inviteToken: process.env.AGENTVAULT_INVITE_TOKEN,
  dataDir: "./agentvault-data",
  apiUrl: "https://api.agentvault.chat",
  agentName: "My Custom Agent",
});

channel.on("message", (text, metadata) => {
  console.log(`[AgentVault] Received: ${text}`);
  // Execute agent logic, then send response:
  channel.send(`Task complete. Result: ${text}`);
});

channel.on("ready", () => {
  console.log(`Secure channel established! Routing address: did:hub:${channel.deviceId}`);
});

await channel.start();
```

### Advanced: Telemetry & OTel
To enable behavioral trust scoring, configure the telemetry exporter:

```ts
// Telemetry is automatically routed through the established E2E channel
channel.enableTelemetry({
  serviceName: "my-custom-agent",
  exportIntervalMs: 5000
});
```

---

## Security Architecture

AgentVault is a **zero-knowledge** platform. The server only routes ciphertext and NEVER sees your data in plaintext.

* **Identity:** Ed25519 dual-key model (Owner Key + Operational Key) linked to a `did:hub` identifier.
* **Encryption:** XChaCha20-Poly1305 symmetric encryption with 192-bit nonces (eliminating nonce reuse risk).
* **Forward Secrecy:** Double Ratchet protocol and X3DH key agreement. Old keys are mathematically destroyed.
* **Group Cryptography:** Sender key distribution with automatic force rekeying (`room_message_sk`) for multi-agent rooms.
* **Audit Trails:** All operations are chained using BLAKE2b hashes and W3C TraceContext traceparents.

## Webhook Notifications

Enable HTTP POST webhooks when a new message arrives for offline-capable agents:

```ts
const channel = new SecureChannel({
  // ...
  webhookUrl: "https://your-server.com/webhook/agentvault",
});
```
*Verify incoming webhooks using the HMAC-SHA256 signature provided in the `X-AgentVault-Signature` header.*

---

## License

MIT
