ts-algochat

Pre-1.0 Notice: This library is under active development. The API may change between minor versions until 1.0.

TypeScript implementation of the AlgoChat protocol for encrypted messaging on Algorand.

Features

• End-to-End Encryption - X25519 + ChaCha20-Poly1305
• Forward Secrecy - Per-message ephemeral keys
• PSK Mode (v1.1) - Hybrid ECDH + pre-shared key ratcheting for quantum defense-in-depth
• Bidirectional Decryption - Sender can decrypt own messages
• Reply Support - Thread conversations with context
• Zero Dependencies - Uses @noble crypto libraries (audited)
• TypeScript First - Full type safety

Security Properties

Property	Status
Message content confidentiality	Protected (E2EE)
Message integrity	Protected (authenticated encryption)
Forward secrecy	Protected (ephemeral keys per message)
Replay attacks	Protected (blockchain uniqueness + PSK counter)
Quantum resistance (key exchange)	Optional (PSK mode provides defense-in-depth)
PSK session forward secrecy	Optional (100-message session boundaries in PSK mode)
Metadata privacy	Not protected (addresses, timing visible)
Traffic analysis	Not protected

Installation

# npm
npm install @corvidlabs/ts-algochat

# bun
bun add @corvidlabs/ts-algochat

# pnpm
pnpm add @corvidlabs/ts-algochat
Copy

Quick Start

import {
    AlgorandService,
    createChatAccountFromMnemonic,
} from '@corvidlabs/ts-algochat';

// Initialize service
const service = new AlgorandService({
    algodToken: '',
    algodServer: 'https://testnet-api.algonode.cloud',
    indexerToken: '',
    indexerServer: 'https://testnet-idx.algonode.cloud',
});

// Create account from mnemonic
const account = createChatAccountFromMnemonic('your 25 word mnemonic...');

// Discover recipient's encryption key
const recipientKey = await service.discoverPublicKey('RECIPIENT_ADDRESS');

// Send encrypted message
const result = await service.sendMessage(
    account,
    'RECIPIENT_ADDRESS',
    recipientKey,
    'Hello from AlgoChat!'
);

console.log('Transaction ID:', result.txid);

// Fetch messages
const messages = await service.fetchMessages(account, 'RECIPIENT_ADDRESS');
Copy

API Reference

Account Management

// Create from mnemonic
const account = createChatAccountFromMnemonic('word1 word2 ...');

// Generate new account
const newAccount = createRandomChatAccount();
console.log('Address:', newAccount.address);
console.log('Mnemonic:', newAccount.mnemonic);

// Validate mnemonic
if (validateMnemonic('word1 word2 ...')) {
    // Valid 25-word mnemonic
}

// Validate address
if (validateAddress('ALGO...')) {
    // Valid Algorand address
}
Copy

Sending Messages

// Simple message
await service.sendMessage(account, recipient, recipientKey, 'Hello!');

// Reply to a message
await service.sendReply(account, recipient, recipientKey, 'Reply text', {
    txid: 'original-tx-id',
    preview: 'Original message preview...',
});
Copy

Fetching Messages

// Get all messages with an address
const messages = await service.fetchMessages(account, 'ADDRESS');

// Get all conversations
const conversations = await service.fetchConversations(account);

// Discover public key
const pubKey = await service.discoverPublicKey('ADDRESS');
Copy

Low-Level Crypto

import {
    deriveEncryptionKeys,
    encryptMessage,
    decryptMessage,
    encodeEnvelope,
    decodeEnvelope,
} from '@corvidlabs/ts-algochat';

// Derive keys from seed
const keys = deriveEncryptionKeys(seed);

// Encrypt message
const envelope = encryptMessage(
    'Hello!',
    senderPrivateKey,
    senderPublicKey,
    recipientPublicKey
);

// Encode for transmission
const bytes = encodeEnvelope(envelope);

// Decode received envelope
const decoded = decodeEnvelope(bytes);

// Decrypt message
const content = decryptMessage(decoded, myPrivateKey, myPublicKey);
Copy

Types

interface ChatAccount {
    address: string;
    publicKey: Uint8Array;
    privateKey: Uint8Array;
    encryptionKeys: X25519KeyPair;
    mnemonic?: string;
}

interface Message {
    id: string;
    sender: string;
    recipient: string;
    content: string;
    timestamp: Date;
    confirmedRound: number;
    direction: 'sent' | 'received';
    replyContext?: ReplyContext;
}

interface Conversation {
    participant: string;
    participantPublicKey?: Uint8Array;
    messages: Message[];
    lastMessage?: Message;
}
Copy

Protocol

This library implements the AlgoChat Protocol v1 and the PSK v1.1 extension.

Wire Format (v1.0 Standard)

[version: 1][protocol: 1][sender_pubkey: 32][ephemeral_pubkey: 32][nonce: 12][encrypted_sender_key: 48][ciphertext: variable]
Copy

Wire Format (v1.1 PSK)

[version: 1][protocol: 2][ratchet_counter: 4][sender_pubkey: 32][ephemeral_pubkey: 32][nonce: 12][encrypted_sender_key: 48][ciphertext: variable]
Copy

Cryptographic Primitives

Function	Algorithm
Key Agreement	X25519 ECDH
Encryption	ChaCha20-Poly1305
Key Derivation	HKDF-SHA256

PSK v1.1 Protocol

The PSK (Pre-Shared Key) v1.1 protocol adds an additional layer of authentication and security on top of standard ECDH encryption by incorporating a pre-shared key into the key derivation process.

Features

• Two-level key ratchet - Session keys derived per 100 messages, position keys per message
• Hybrid encryption - Combines ECDH forward secrecy with PSK authentication
• Replay protection - Counter-based sliding window prevents message replay
• Out-of-band key exchange - URI scheme for sharing PSK keys (QR code compatible)

Quantum Defense-in-Depth

PSK mode provides defense against future quantum attacks through hybrid key derivation:

symmetricKey = HKDF(
  ikm = ephemeralECDH || currentPSK,
  salt = ephemeralPublicKey,
  info = "algochat-psk-v1" || senderPubKey || recipientPubKey
)
Copy

The encryption key is derived from both the ephemeral ECDH shared secret and the ratcheted PSK, concatenated before HKDF. This means an attacker must break both layers:

1. ECDH only broken (quantum computer): Attacker still needs the PSK
2. PSK only compromised: Attacker still cannot break ECDH (per-message ephemeral keys)
3. Both compromised: Only then can messages be decrypted

This hybrid approach ensures that even if quantum computers eventually break X25519 ECDH, messages encrypted with PSK mode remain secure as long as the pre-shared key was exchanged securely.

Two-Level Ratcheting

PSK mode derives per-message keys using a two-level ratchet:

1. Session derivation: sessionPSK = HKDF(initialPSK, sessionIndex) where sessionIndex = counter / 100
2. Position derivation: currentPSK = HKDF(sessionPSK, position) where position = counter % 100

This creates 100-message session boundaries. Compromising a session PSK exposes at most 100 messages.

Exchange URI Format

PSK exchange URIs are designed for QR code sharing:

algochat-psk://v1?addr=<algorand_address>&psk=<base64url>&label=<optional>
Copy

Use any QR library (e.g., qrcode) to encode the URI for easy scanning between devices.

Usage

import {
    derivePSKAtCounter,
    encryptPSKMessage,
    decryptPSKMessage,
    encodePSKEnvelope,
    decodePSKEnvelope,
    isPSKMessage,
    createPSKState,
    advanceSendCounter,
    validateCounter,
    recordReceive,
    createPSKExchangeURI,
    parsePSKExchangeURI,
} from '@corvidlabs/ts-algochat';

// Derive PSK for a specific counter
const psk = derivePSKAtCounter(sharedSecret, counter);

// Encrypt a PSK message
const envelope = encryptPSKMessage(
    'Hello with PSK!',
    senderPublicKey,
    recipientPublicKey,
    psk,
    counter,
);

// Encode for transmission
const bytes = encodePSKEnvelope(envelope);

// Check if received data is a PSK message
if (isPSKMessage(bytes)) {
    const decoded = decodePSKEnvelope(bytes);
    const content = decryptPSKMessage(decoded, myPrivateKey, myPublicKey, psk);
}

// Counter state management
let state = createPSKState();
const { counter: sendCounter, state: newState } = advanceSendCounter(state);
state = newState;

// Exchange URI for out-of-band key sharing
const uri = createPSKExchangeURI('ALGO_ADDRESS', pskBytes, 'My Chat');
const parsed = parsePSKExchangeURI(uri);
Copy

Testing

bun test
Copy

Cross-Implementation Compatibility

This implementation is fully compatible with:

• swift-algochat (Swift)
• rs-algochat (Rust)
• py-algochat (Python)
• kt-algochat (Kotlin)

License

MIT License - See LICENSE for details.