@verbeth/sdk 0.1.4

package/README.md

@@ -0,0 +1,202 @@
+# @verbeth/sdk
+
+Verbeth enables secure, E2EE messaging using Ethereum event logs as the only transport layer. No servers, no relays—just the blockchain.
+
+## Features
+
+- **End-to-end encryption** using NaCl Box (X25519 + XSalsa20-Poly1305)
+- **Forward secrecy** with ephemeral keys per message
+- **Handshake protocol** for secure key exchange
+- **Privacy-focused** with minimal metadata via `recipientHash`
+- **EOA & Smart Account support** (ERC-1271/6492 compatible)
+- **Fully on-chain** - no centralized infrastructure
+
+## Installation
+
+```bash
+npm install @verbeth/sdk ethers tweetnacl
+```
+
+## Quick Start
+
+### 1. Initialize with VerbethClient (Recommended)
+
+```typescript
+import { VerbethClient, ExecutorFactory, deriveIdentityKeyPairWithProof } from '@verbeth/sdk';
+import { Contract, BrowserProvider } from 'ethers';
+import { LogChainV1__factory } from '@verbeth/contracts/typechain-types';
+
+// Setup
+const provider = new BrowserProvider(window.ethereum);
+const signer = await provider.getSigner();
+const address = await signer.getAddress();
+
+// Create contract instance
+const contract = LogChainV1__factory.connect(LOGCHAIN_ADDRESS, signer);
+
+// Derive identity keys (done once, then stored)
+const { identityKeyPair, identityProof } = await deriveIdentityKeyPairWithProof(signer);
+
+// Create executor (handles transaction submission)
+const executor = ExecutorFactory.createEOA(contract);
+
+// Initialize client
+const client = new VerbethClient({
+  executor,
+  identityKeyPair,
+  identityProof,
+  signer,
+  address
+});
+
+// Send a handshake to start chatting
+const { tx, ephemeralKeyPair } = await client.sendHandshake(
+  '0xRecipientAddress...',
+  'Hello! Want to chat?'
+);
+
+// Store ephemeralKeyPair. you'll just need it to decrypt the handshake response!
+
+// Accept a handshake
+const { tx, duplexTopics } = await client.acceptHandshake(
+  handshakeEvent.ephemeralPubKey,
+  handshakeEvent.identityPubKey,
+  'Sure, lets chat!'
+);
+
+// Send encrypted messages
+await client.sendMessage(
+  duplexTopics.topicOut,
+  recipientIdentityPubKey,
+  'This message is encrypted!'
+);
+
+// Decrypt received messages
+const decrypted = await client.decryptMessage(
+  messageEvent.ciphertext,
+  senderIdentityPubKey
+);
+```
+
+### 2. Low-level API
+
+For more control, use the low-level functions:
+
+```typescript
+import {
+  initiateHandshake,
+  respondToHandshake,
+  sendEncryptedMessage,
+  decryptMessage,
+  deriveIdentityKeyPairWithProof
+} from '@verbeth/sdk';
+
+// Generate identity keys
+const { identityKeyPair, identityProof } = await deriveIdentityKeyPairWithProof(signer);
+
+// Initiate handshake
+const ephemeralKeyPair = nacl.box.keyPair();
+const tx = await initiateHandshake({
+  executor,
+  recipientAddress: '0xBob...',
+  ephemeralPubKey: ephemeralKeyPair.publicKey,
+  identityKeyPair,
+  identityProof,
+  plaintextPayload: 'Hi Bob!'
+});
+
+// Send encrypted message
+await sendEncryptedMessage({
+  executor,
+  topic: derivedTopic,
+  message: 'Secret message',
+  recipientPubKey: bobsIdentityKey,
+  senderAddress: myAddress,
+  senderSignKeyPair: identityKeyPair,
+  timestamp: Date.now()
+});
+
+// Decrypt message
+const plaintext = decryptMessage(
+  ciphertext,
+  senderIdentityPubKey,
+  myIdentityKeyPair.secretKey
+);
+```
+
+## Smart Account Support
+
+Verbeth works with ERC-4337 smart accounts:
+
+```typescript
+import { ExecutorFactory } from '@verbeth/sdk';
+
+// For UserOp-based execution
+const executor = ExecutorFactory.createUserOp(
+  contract,
+  bundler,
+  smartAccount,
+  signer
+);
+
+// For direct EntryPoint execution
+const executor = ExecutorFactory.createDirectEntryPoint(
+  contract,
+  entryPoint,
+  smartAccountAddress,
+  signer
+);
+```
+
+## Contract Addresses
+
+**LogChainV1 Singleton:** `0x41a3eaC0d858028E9228d1E2092e6178fc81c4f0`
+
+**ERC1967Proxy:** `0x62720f39d5Ec6501508bDe4D152c1E13Fd2F6707`
+
+## How It Works
+
+1. **Identity Keys**: Each account derives long-term X25519 (encryption) + Ed25519 (signing) keys bound to their address via signature
+2. **Handshake**: Alice sends her ephemeral key + identity proof to Bob via a `Handshake` event
+3. **Response**: Bob verifies Alice's identity and responds with his keys + duplex topics
+4. **Messaging**: Both parties derive shared topics and exchange encrypted messages via `MessageSent` events
+5. **Decryption**: Recipients monitor their inbound topic and decrypt with their identity key
+
+
+## Security Considerations
+
+- **Forward Secrecy**: Fresh ephemeral keys per message provide sender-side forward secrecy
+- **Identity Binding**: Addresses are cryptographically bound to long-term keys via signature
+- **Non-Repudiation**: Optional Ed25519 signatures prove message origin
+- **Privacy**: RecipientHash hides recipient identity; duplex topics separate communication channels
+
+⚠️ **Note**: Current design provides sender-side forward secrecy. Recipient-side FS requires ephemeral↔ephemeral or session ratcheting (e.g., Double Ratchet).
+
+## Built With
+
+- [TweetNaCl](https://tweetnacl.js.org/) - Encryption primitives
+- [Ethers v6](https://docs.ethers.org/v6/) - Ethereum interactions
+- [Viem](https://viem.sh/) - EIP-1271/6492 verification
+- [Noble Curves](https://github.com/paulmillr/noble-curves) - Elliptic curve operations
+
+## Examples
+
+Check out the [demo application](https://github.com/okrame/verbeth-sdk/tree/main/apps/demo) for a complete implementation.
+
+## Documentation
+
+For detailed protocol documentation, security analysis, and improvement proposals, see the [main repository](https://github.com/okrame/verbeth-sdk).
+
+## License
+
+MPL-2.0
+
+## Links
+
+- [GitHub Repository](https://github.com/okrame/verbeth-sdk)
+- [Demo App](https://verbeth-demo.vercel.app/)
+- [Contract Source](https://github.com/okrame/verbeth-sdk/tree/main/packages/contracts)
+
+---
+
+**Questions or feedback?** Open an issue on [GitHub](https://github.com/okrame/verbeth-sdk/issues).

package/dist/esm/src/client/VerbethClient.d.ts

@@ -0,0 +1,134 @@
+import type { VerbethClientConfig, HandshakeResult, HandshakeResponseResult } from './types.js';
+import type { IExecutor } from '../executor.js';
+import type { IdentityKeyPair } from '../types.js';
+import * as crypto from '../crypto.js';
+import * as payload from '../payload.js';
+import * as verify from '../verify.js';
+import * as utils from '../utils.js';
+import * as identity from '../identity.js';
+/**
+ * High-level client for Verbeth E2EE messaging
+ *
+ * VerbethClient provides a simplified API for common operations while
+ * maintaining access to all low-level functions.
+ *
+ * @example
+ * ```typescript
+ * const client = new VerbethClient({
+ *   executor,
+ *   identityKeyPair,
+ *   identityProof,
+ *   signer,
+ *   address: '0x...'
+ * });
+ *
+ * // Send a handshake
+ * const { tx, ephemeralKeyPair } = await client.sendHandshake(
+ *   '0xBob...',
+ *   'Hello Bob!'
+ * );
+ *
+ * // Send a message
+ * await client.sendMessage(
+ *   contact.topicOutbound,
+ *   contact.identityPubKey,
+ *   'Hello again!'
+ * );
+ * ```
+ */
+export declare class VerbethClient {
+    private readonly executor;
+    private readonly identityKeyPair;
+    private readonly identityProof;
+    private readonly signer;
+    private readonly address;
+    /**
+     * creates a new VerbethClient instance
+     *
+     * @param config - Client configuration with session-level parameters
+     */
+    constructor(config: VerbethClientConfig);
+    /**
+     * Initiates a handshake with a recipient
+     *
+     * generates an ephemeral keypair for this handshake.
+     * the ephemeralKeyPair must be stored to decrypt the response later.
+     *
+     * @param recipientAddress - Blockchain address of the recipient
+     * @param message - Plaintext message to include in the handshake
+     * @returns Transaction response and the ephemeral keypair (must be stored!)
+     *
+     * @example
+     * ```typescript
+     * const { tx, ephemeralKeyPair } = await client.sendHandshake(
+     *   '0xBob...',
+     *   'Hi Bob!'
+     * );
+     *
+     * // Store ephemeralKeyPair.secretKey to decrypt Bob's response
+     * await storage.saveContact({
+     *   address: '0xBob...',
+     *   ephemeralKey: ephemeralKeyPair.secretKey,
+     *   // ...
+     * });
+     * ```
+     */
+    sendHandshake(recipientAddress: string, message: string): Promise<HandshakeResult>;
+    /**
+     * Accepts a handshake from an initiator
+     *
+     * derives duplex topics for the conversation and returns them.
+     *
+     * @param initiatorEphemeralPubKey - initiator's ephemeral public key from handshake event
+     * @param initiatorIdentityPubKey - initiator's long-term X25519 identity key
+     * @param note - response message to send back
+     * @returns transaction, derived duplex topics, and response tag
+     *
+     * @example
+     * ```typescript
+     * const { tx, duplexTopics } = await client.acceptHandshake(
+     *   handshake.ephemeralPubKey,
+     *   handshake.identityPubKey,
+     *   'Hello Alice!'
+     * );
+     *
+     * // Store the topics for future messaging
+     * await storage.saveContact({
+     *   address: handshake.sender,
+     *   topicOutbound: duplexTopics.topicIn,  // Responder writes to topicIn
+     *   topicInbound: duplexTopics.topicOut,  // Responder reads from topicOut
+     *   // ...
+     * });
+     * ```
+     */
+    acceptHandshake(initiatorEphemeralPubKey: Uint8Array, initiatorIdentityPubKey: Uint8Array, note: string): Promise<HandshakeResponseResult>;
+    /**
+     * Sends an encrypted message to a contact
+     *
+     * handles timestamp, signing keys, and sender address.
+     *
+     * @param topicOutbound - The outbound topic for this conversation
+     * @param recipientPubKey - Recipient's X25519 public key (from handshake)
+     * @param message - Plaintext message to encrypt and send
+     * @returns Transaction response
+     *
+     * @example
+     * ```typescript
+     * await client.sendMessage(
+     *   contact.topicOutbound,
+     *   contact.identityPubKey,
+     *   'Hello again!'
+     * );
+     * ```
+     */
+    sendMessage(topicOutbound: string, recipientPubKey: Uint8Array, message: string): Promise<any>;
+    get crypto(): typeof crypto;
+    get payload(): typeof payload;
+    get verify(): typeof verify;
+    get utils(): typeof utils;
+    get identity(): typeof identity;
+    get executorInstance(): IExecutor;
+    get identityKeyPairInstance(): IdentityKeyPair;
+    get userAddress(): string;
+}
+//# sourceMappingURL=VerbethClient.d.ts.map

package/dist/esm/src/client/VerbethClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VerbethClient.d.ts","sourceRoot":"","sources":["../../../../src/client/VerbethClient.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAChG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,aAAa,CAAC;AAGlE,OAAO,KAAK,MAAM,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,OAAO,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,MAAM,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,KAAK,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAY;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;OAIG;gBACS,MAAM,EAAE,mBAAmB;IAQvC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,aAAa,CACjB,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,CAAC;IAgB3B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,eAAe,CACnB,wBAAwB,EAAE,UAAU,EACpC,uBAAuB,EAAE,UAAU,EACnC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,uBAAuB,CAAC;IAoBnC;;;;;;;;;;;;;;;;;;OAkBG;IACG,WAAW,CACf,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,UAAU,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,GAAG,CAAC;IAqBf,IAAI,MAAM,kBAET;IAED,IAAI,OAAO,mBAEV;IAED,IAAI,MAAM,kBAET;IAED,IAAI,KAAK,iBAER;IAED,IAAI,QAAQ,oBAEX;IAED,IAAI,gBAAgB,IAAI,SAAS,CAEhC;IAGD,IAAI,uBAAuB,IAAI,eAAe,CAE7C;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;CACF"}

package/dist/esm/src/client/VerbethClient.js

@@ -0,0 +1,191 @@
+// packages/sdk/src/client/VerbethClient.ts
+import nacl from 'tweetnacl';
+import { initiateHandshake, respondToHandshake, sendEncryptedMessage } from '../send.js';
+import { deriveDuplexTopics } from '../crypto.js';
+import * as crypto from '../crypto.js';
+import * as payload from '../payload.js';
+import * as verify from '../verify.js';
+import * as utils from '../utils.js';
+import * as identity from '../identity.js';
+/**
+ * High-level client for Verbeth E2EE messaging
+ *
+ * VerbethClient provides a simplified API for common operations while
+ * maintaining access to all low-level functions.
+ *
+ * @example
+ * ```typescript
+ * const client = new VerbethClient({
+ *   executor,
+ *   identityKeyPair,
+ *   identityProof,
+ *   signer,
+ *   address: '0x...'
+ * });
+ *
+ * // Send a handshake
+ * const { tx, ephemeralKeyPair } = await client.sendHandshake(
+ *   '0xBob...',
+ *   'Hello Bob!'
+ * );
+ *
+ * // Send a message
+ * await client.sendMessage(
+ *   contact.topicOutbound,
+ *   contact.identityPubKey,
+ *   'Hello again!'
+ * );
+ * ```
+ */
+export class VerbethClient {
+    /**
+     * creates a new VerbethClient instance
+     *
+     * @param config - Client configuration with session-level parameters
+     */
+    constructor(config) {
+        this.executor = config.executor;
+        this.identityKeyPair = config.identityKeyPair;
+        this.identityProof = config.identityProof;
+        this.signer = config.signer;
+        this.address = config.address;
+    }
+    /**
+     * Initiates a handshake with a recipient
+     *
+     * generates an ephemeral keypair for this handshake.
+     * the ephemeralKeyPair must be stored to decrypt the response later.
+     *
+     * @param recipientAddress - Blockchain address of the recipient
+     * @param message - Plaintext message to include in the handshake
+     * @returns Transaction response and the ephemeral keypair (must be stored!)
+     *
+     * @example
+     * ```typescript
+     * const { tx, ephemeralKeyPair } = await client.sendHandshake(
+     *   '0xBob...',
+     *   'Hi Bob!'
+     * );
+     *
+     * // Store ephemeralKeyPair.secretKey to decrypt Bob's response
+     * await storage.saveContact({
+     *   address: '0xBob...',
+     *   ephemeralKey: ephemeralKeyPair.secretKey,
+     *   // ...
+     * });
+     * ```
+     */
+    async sendHandshake(recipientAddress, message) {
+        const ephemeralKeyPair = nacl.box.keyPair();
+        const tx = await initiateHandshake({
+            executor: this.executor,
+            recipientAddress,
+            identityKeyPair: this.identityKeyPair,
+            ephemeralPubKey: ephemeralKeyPair.publicKey,
+            plaintextPayload: message,
+            identityProof: this.identityProof,
+            signer: this.signer,
+        });
+        return { tx, ephemeralKeyPair };
+    }
+    /**
+     * Accepts a handshake from an initiator
+     *
+     * derives duplex topics for the conversation and returns them.
+     *
+     * @param initiatorEphemeralPubKey - initiator's ephemeral public key from handshake event
+     * @param initiatorIdentityPubKey - initiator's long-term X25519 identity key
+     * @param note - response message to send back
+     * @returns transaction, derived duplex topics, and response tag
+     *
+     * @example
+     * ```typescript
+     * const { tx, duplexTopics } = await client.acceptHandshake(
+     *   handshake.ephemeralPubKey,
+     *   handshake.identityPubKey,
+     *   'Hello Alice!'
+     * );
+     *
+     * // Store the topics for future messaging
+     * await storage.saveContact({
+     *   address: handshake.sender,
+     *   topicOutbound: duplexTopics.topicIn,  // Responder writes to topicIn
+     *   topicInbound: duplexTopics.topicOut,  // Responder reads from topicOut
+     *   // ...
+     * });
+     * ```
+     */
+    async acceptHandshake(initiatorEphemeralPubKey, initiatorIdentityPubKey, note) {
+        const { tx, salt, tag } = await respondToHandshake({
+            executor: this.executor,
+            initiatorPubKey: initiatorEphemeralPubKey,
+            responderIdentityKeyPair: this.identityKeyPair,
+            note,
+            identityProof: this.identityProof,
+            signer: this.signer,
+            initiatorIdentityPubKey,
+        });
+        const duplexTopics = deriveDuplexTopics(this.identityKeyPair.secretKey, initiatorIdentityPubKey, salt);
+        return { tx, duplexTopics, tag };
+    }
+    /**
+     * Sends an encrypted message to a contact
+     *
+     * handles timestamp, signing keys, and sender address.
+     *
+     * @param topicOutbound - The outbound topic for this conversation
+     * @param recipientPubKey - Recipient's X25519 public key (from handshake)
+     * @param message - Plaintext message to encrypt and send
+     * @returns Transaction response
+     *
+     * @example
+     * ```typescript
+     * await client.sendMessage(
+     *   contact.topicOutbound,
+     *   contact.identityPubKey,
+     *   'Hello again!'
+     * );
+     * ```
+     */
+    async sendMessage(topicOutbound, recipientPubKey, message) {
+        const signingKeyPair = {
+            publicKey: this.identityKeyPair.signingPublicKey,
+            secretKey: this.identityKeyPair.signingSecretKey,
+        };
+        const timestamp = Math.floor(Date.now() / 1000);
+        return sendEncryptedMessage({
+            executor: this.executor,
+            topic: topicOutbound,
+            message,
+            recipientPubKey,
+            senderAddress: this.address,
+            senderSignKeyPair: signingKeyPair,
+            timestamp,
+        });
+    }
+    // ========== low-level API ==========
+    get crypto() {
+        return crypto;
+    }
+    get payload() {
+        return payload;
+    }
+    get verify() {
+        return verify;
+    }
+    get utils() {
+        return utils;
+    }
+    get identity() {
+        return identity;
+    }
+    get executorInstance() {
+        return this.executor;
+    }
+    get identityKeyPairInstance() {
+        return this.identityKeyPair;
+    }
+    get userAddress() {
+        return this.address;
+    }
+}

package/dist/esm/src/client/index.d.ts

@@ -0,0 +1,3 @@
+export { VerbethClient } from './VerbethClient.js';
+export type { VerbethClientConfig, HandshakeResult, HandshakeResponseResult } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/src/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,uBAAuB,EACxB,MAAM,YAAY,CAAC"}

package/dist/esm/src/client/index.js

@@ -0,0 +1,2 @@
+// packages/sdk/src/client/index.ts
+export { VerbethClient } from './VerbethClient.js';

package/dist/esm/src/client/types.d.ts

@@ -0,0 +1,30 @@
+import type { Signer } from 'ethers';
+import type { IExecutor } from '../executor.js';
+import type { IdentityKeyPair, IdentityProof, DuplexTopics } from '../types.js';
+import type nacl from 'tweetnacl';
+/**
+ * Configuration for creating a VerbethClient instance
+ */
+export interface VerbethClientConfig {
+    executor: IExecutor;
+    identityKeyPair: IdentityKeyPair;
+    identityProof: IdentityProof;
+    signer: Signer;
+    address: string;
+}
+/**
+ * Result from initiating a handshake
+ */
+export interface HandshakeResult {
+    tx: any;
+    ephemeralKeyPair: nacl.BoxKeyPair;
+}
+/**
+ * Result from accepting a handshake
+ */
+export interface HandshakeResponseResult {
+    tx: any;
+    duplexTopics: DuplexTopics;
+    tag: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/src/client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/client/types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,SAAS,CAAC;IACpB,eAAe,EAAE,eAAe,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,GAAG,CAAC;IACR,gBAAgB,EAAE,IAAI,CAAC,UAAU,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,GAAG,CAAC;IACR,YAAY,EAAE,YAAY,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;CACb"}

package/dist/esm/src/client/types.js

@@ -0,0 +1,2 @@
+// packages/sdk/src/client/types.ts
+export {};

package/dist/esm/src/crypto.d.ts

@@ -0,0 +1,46 @@
+import { HandshakeResponseContent } from './payload.js';
+import { IdentityProof } from './types.js';
+/**
+ * Encrypts a structured payload (JSON-serializable objects)
+ */
+export declare function encryptStructuredPayload<T>(payload: T, recipientPublicKey: Uint8Array, ephemeralSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, staticSigningSecretKey?: Uint8Array, staticSigningPublicKey?: Uint8Array): string;
+/**
+ * Decrypts a structured payload with converter function
+ */
+export declare function decryptStructuredPayload<T>(payloadJson: string, recipientSecretKey: Uint8Array, converter: (obj: any) => T, staticSigningPublicKey?: Uint8Array): T | null;
+export declare function encryptMessage(message: string, recipientPublicKey: Uint8Array, ephemeralSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, staticSigningSecretKey?: Uint8Array, staticSigningPublicKey?: Uint8Array): string;
+export declare function decryptMessage(payloadJson: string, recipientSecretKey: Uint8Array, staticSigningPublicKey?: Uint8Array): string | null;
+/**
+ * Decrypts handshake response and extracts individual keys from unified format
+ */
+export declare function decryptHandshakeResponse(payloadJson: string, initiatorEphemeralSecretKey: Uint8Array): HandshakeResponseContent | null;
+/**
+ * helper to decrypt handshake response and extract individual keys
+ */
+export declare function decryptAndExtractHandshakeKeys(payloadJson: string, initiatorEphemeralSecretKey: Uint8Array): {
+    identityPubKey: Uint8Array;
+    signingPubKey: Uint8Array;
+    ephemeralPubKey: Uint8Array;
+    note?: string;
+    identityProof: IdentityProof;
+} | null;
+/**
+ * Responder: tag = H( KDF( ECDH(r, viewPubA), "verbeth:hsr"))
+ */
+export declare function computeTagFromResponder(rSecretKey: Uint8Array, viewPubA: Uint8Array): `0x${string}`;
+/**
+ * Initiator: tag = H( KDF( ECDH(viewPrivA, R), "verbeth:hsr"))
+ */
+export declare function computeTagFromInitiator(viewPrivA: Uint8Array, R: Uint8Array): `0x${string}`;
+export declare function deriveLongTermShared(myIdentitySecretKey: Uint8Array, theirIdentityPublicKey: Uint8Array): Uint8Array;
+/**
+ * Directional duplex topics (Initiator-Responder, Responder-Initiator).
+ * Recommended salt: tag (bytes)
+ */
+export declare function deriveDuplexTopics(myIdentitySecretKey: Uint8Array, theirIdentityPublicKey: Uint8Array, salt?: Uint8Array): {
+    topicOut: `0x${string}`;
+    topicIn: `0x${string}`;
+    checksum: `0x${string}`;
+};
+export declare function verifyDuplexTopicsChecksum(topicOut: `0x${string}`, topicIn: `0x${string}`, checksum: `0x${string}`): boolean;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/esm/src/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../../src/crypto.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,wBAAwB,EAEzB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,OAAO,EAAE,CAAC,EACV,kBAAkB,EAAE,UAAU,EAC9B,kBAAkB,EAAE,UAAU,EAC9B,kBAAkB,EAAE,UAAU,EAC9B,sBAAsB,CAAC,EAAE,UAAU,EACnC,sBAAsB,CAAC,EAAE,UAAU,GAClC,MAAM,CAcR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,UAAU,EAC9B,SAAS,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,EAC1B,sBAAsB,CAAC,EAAE,UAAU,GAClC,CAAC,GAAG,IAAI,CAaV;AAGD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,kBAAkB,EAAE,UAAU,EAC9B,kBAAkB,EAAE,UAAU,EAC9B,kBAAkB,EAAE,UAAU,EAC9B,sBAAsB,CAAC,EAAE,UAAU,EACnC,sBAAsB,CAAC,EAAE,UAAU,GAClC,MAAM,CAUR;AAED,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,UAAU,EAC9B,sBAAsB,CAAC,EAAE,UAAU,GAClC,MAAM,GAAG,IAAI,CAQf;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,2BAA2B,EAAE,UAAU,GACtC,wBAAwB,GAAG,IAAI,CAgBjC;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,EACnB,2BAA2B,EAAE,UAAU,GACtC;IACD,cAAc,EAAE,UAAU,CAAC;IAC3B,aAAa,EAAE,UAAU,CAAC;IAC1B,eAAe,EAAE,UAAU,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,aAAa,CAAC;CAC9B,GAAG,IAAI,CAcP;AAWD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,UAAU,GACnB,KAAK,MAAM,EAAE,CAGf;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,UAAU,EACrB,CAAC,EAAE,UAAU,GACZ,KAAK,MAAM,EAAE,CAGf;AAkBD,wBAAgB,oBAAoB,CAClC,mBAAmB,EAAE,UAAU,EAC/B,sBAAsB,EAAE,UAAU,GACjC,UAAU,CAEZ;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,mBAAmB,EAAE,UAAU,EAC/B,sBAAsB,EAAE,UAAU,EAClC,IAAI,CAAC,EAAE,UAAU,GAChB;IAAE,QAAQ,EAAE,KAAK,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,KAAK,MAAM,EAAE,CAAA;CAAE,CAW9E;AAED,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,KAAK,MAAM,EAAE,EACvB,OAAO,EAAE,KAAK,MAAM,EAAE,EACtB,QAAQ,EAAE,KAAK,MAAM,EAAE,GACtB,OAAO,CAOT"}