@agentvault/crypto

Shared cryptographic primitives and telemetry types for the AgentVault ecosystem. Used by @agentvault/agentvault, @agentvault/client, and the Expo web app.

Installation

npm install @agentvault/crypto

Features

• XChaCha20-Poly1305 -- Authenticated encryption with 192-bit nonces (no nonce reuse risk)
• Ed25519 -- Identity keypairs, document signing, proof of possession
• X25519 -- Ephemeral keypairs for X3DH key agreement
• Double Ratchet -- Signal-protocol message ratcheting with forward secrecy
• X3DH -- Extended Triple Diffie-Hellman for session establishment
• Sender Key -- Group encryption for multi-agent rooms with chain ratcheting
• DID Documents -- W3C DID document building and signing (did:hub method)
• Verifiable Credentials -- W3C VC issuance, signing, and verification
• ScanEngine -- Client-side policy rule evaluation
• Merkle Proofs -- DID hash computation and on-chain anchor verification
• Backup -- Encrypted backup code generation, key derivation, and bundle encrypt/decrypt
• Approval Artifacts -- Cryptographic approval flow creation and verification
• Telemetry -- 21 OTel-shaped span builders with W3C TraceContext propagation
• Transport -- Binary/hex/base64 serialization for encrypted messages

Quick Start

import {
  generateIdentityKeypair,
  generateEphemeralKeypair,
  performX3DH,
  DoubleRatchet,
} from "@agentvault/crypto";

// Generate identity keypair (Ed25519)
const identity = await generateIdentityKeypair();

// Generate ephemeral keypair (X25519)
const ephemeral = await generateEphemeralKeypair();

// Perform X3DH key agreement
const sharedSecret = await performX3DH({
  myIdentity: identity,
  myEphemeral: ephemeral,
  theirIdentityPub: peerIdentityPublicKey,
  theirEphemeralPub: peerEphemeralPublicKey,
});

// Initialize Double Ratchet
const ratchet = DoubleRatchet.initSender(sharedSecret, peerRatchetPub);
const encrypted = ratchet.encrypt(plaintext);

API Reference

Key Generation

generateIdentityKeypair(): Promise<IdentityKeypair>
generateEphemeralKeypair(): Promise<EphemeralKeypair>
computeFingerprint(publicKey: Uint8Array): string
createProofOfPossession(keypair: IdentityKeypair, challenge: Uint8Array): Uint8Array
verifyProofOfPossession(publicKey: Uint8Array, challenge: Uint8Array, proof: Uint8Array): boolean

X3DH Key Agreement

performX3DH(params: X3DHParams): Promise<Uint8Array>

Double Ratchet

DoubleRatchet.initSender(sharedSecret, peerRatchetPub): DoubleRatchet
DoubleRatchet.initReceiver(sharedSecret, keypair): DoubleRatchet
ratchet.encrypt(plaintext: Uint8Array): EncryptedMessage
ratchet.decrypt(message: EncryptedMessage): Uint8Array

Sender Key (Group Encryption)

SenderKeyChain     // Chain ratchet for group message encryption
SenderKeyState     // Manages sender key distribution and rotation

File Encryption

encryptFile(plaintext: Uint8Array): Promise<EncryptedFileResult>
decryptFile(ciphertext: Uint8Array, key: Uint8Array, nonce: Uint8Array): Promise<Uint8Array>
computeFileDigest(data: Uint8Array): Promise<string>

DID Documents

buildDidDocument(params: BuildDidDocumentParams): DidDocument
signDocument(document: object, keypair: IdentityKeypair, domain: string): Promise<Uint8Array>
verifyDocumentSignature(document: object, signature: Uint8Array, publicKey: Uint8Array, domain: string): Promise<boolean>
publicKeyToMultibase(publicKey: Uint8Array): string
multibaseToPublicKey(multibase: string): Uint8Array

Verifiable Credentials

buildAgentTrustCredential(params): UnsignedCredential
buildSkillAttestation(params): UnsignedCredential
buildPerformanceRecord(params): UnsignedCredential
buildAgentTrustReportCredential(params): UnsignedCredential
issueCredential(unsigned, keypair): Promise<VerifiableCredential>
presentCredentials(credentials, keypair): Promise<VerifiablePresentation>
signWithDataIntegrity(document, keypair): Promise<DataIntegrityProof>
verifyDataIntegrity(document, proof, publicKey): Promise<boolean>

Client-Side Scanning

const engine = new ScanEngine(rules: ScanRule[]);
const result: ScanResult = engine.scan(content: string);
// result.violations: ScanViolation[]

Merkle Proofs

computeDidHash(did: string): Uint8Array
verifyMerkleProof(leaf: Uint8Array, proof: MerkleProofSibling[], root: Uint8Array): boolean

Backup

generateBackupCode(): string
formatBackupCode(code: string): string
deriveBackupKey(code: string): Promise<Uint8Array>
encryptBackup(data: Uint8Array, code: string): Promise<BackupBundle>
decryptBackup(bundle: BackupBundle, code: string): Promise<Uint8Array>
hashBackupCode(code: string): Promise<string>

Approval Artifacts

createApprovalArtifact(params): Promise<ApprovalArtifact>
verifyApprovalArtifact(artifact, publicKey): Promise<boolean>

Telemetry (21 Span Types)

All span builders return a TelemetrySpan object compatible with the OTel push endpoint.

| Builder | Span Name | Description | |---------|-----------|-------------| | buildLlmSpan | av.llm | LLM inference call | | buildToolSpan | av.tool | Tool invocation | | buildErrorSpan | av.error | Error event | | buildHttpSpan | av.http | HTTP request | | buildActionSpan | av.action | Generic action | | buildNavSpan | av.nav | Navigation event | | buildEvalSpan | av.eval | Single evaluation | | buildTaskSpan | av.task | Task execution | | buildSkillInvocationSpan | av.skill_invocation | Skill invocation | | buildForgeSpan | av.forge | Skill Builder session | | buildPolicyViolationSpan | av.policy_violation | Policy violation | | buildDecisionSpan | av.decision | Decision request/response | | buildResyncSpan | av.resync | Ratchet resync | | buildA2aSpan | av.a2a | A2A channel event | | buildScanSpan | av.scan | Client-side scan | | buildWorkspaceSpan | av.workspace | Workspace operation | | buildCapabilitySpan | av.capability | Capability check | | buildEnrollmentSpan | av.enrollment | Device enrollment | | buildRoomSpan | av.room | Room operation | | buildTrustSpan | av.trust | Trust score event | | buildEvalRunSpan | av.eval_run | Eval framework run |

W3C TraceContext

buildTraceparent(traceId, spanId, sampled?): string
parseTraceparent(header: string): TraceContext | null
spanToTraceContext(span: TelemetrySpan): TraceContext
spanToW3CHeaders(span: TelemetrySpan): Record<string, string>
propagateContext(parent: TelemetrySpan, child: TelemetrySpan): void

TelemetryReporter

Batches and pushes spans to the AgentVault backend on a configurable interval.

import { TelemetryReporter } from "@agentvault/crypto";

const reporter = new TelemetryReporter({
  endpoint: "https://api.agentvault.chat/api/v1/otel/push",
  deviceId: "...",
  hubId: "...",       // Must be a UUID
  intervalMs: 30000,  // Push every 30s (default)
});

reporter.report(span);
await reporter.flush();
reporter.stop();

Transport Helpers

Serialize EncryptedMessage for network transport:

encryptedMessageToTransport(msg): TransportMessage       // Uint8Array fields
encryptedMessageToHexTransport(msg): HexTransportMessage  // Hex string fields
encryptedMessageToTransportV2(msg): TransportMessageV2    // V2 compact format
transportToEncryptedMessage(transport): EncryptedMessage
hexTransportToEncryptedMessage(transport): EncryptedMessage
transportV2ToEncryptedMessage(transport): EncryptedMessage

Related Packages

| Package | Description | |---------|-------------| | @agentvault/agentvault | OpenClaw plugin with E2E messaging, skills, and delivery | | @agentvault/sdk | SDK for third-party agent integration | | @agentvault/client | Lightweight client for third-party agents | | @agentvault/verify | Agent verification SDK |

License

MIT