ANNEX

Autonomous Network Negotiated eXchange

Post-quantum encrypted point-to-point communication channels

v2.8.2

"Deep within the ice caves of the Khumbu, encrypted channels flow like glacial streams — invisible to the surface world. Changes pass through math alone."

Overview

YAKMESH ANNEX establishes encrypted point-to-point channels between mesh peers using post-quantum cryptography. All payload transformations are cryptographically autonomous with no plaintext touching the network.

Key Exchange

ML-KEM-768 (Kyber) — NIST FIPS 203 post-quantum KEM

Encryption

AES-256-GCM authenticated symmetric encryption

Authentication

ML-DSA-65 signatures on all messages

Forward Secrecy

Automatic re-key every 5 minutes or 10,000 messages

Use Cases

• Beacon Acknowledgments — Encrypted responses to emergency broadcasts without revealing recipient identity
• Authenticated Content Delivery — Private content transfer vs public gossip propagation
• App-Specific Payloads — Private application data requiring confidentiality
• CDN Authentication Tokens — Secure token exchange for site/CDN access
• Direct P2P Messaging — Secure peer-to-peer communication

Quick Start

import { Annex } from 'yakmesh/mesh/annex.js';

// Initialize with node identity and mesh connection
const annex = new Annex({ identity, mesh });

// Open encrypted channel to a peer
await annex.openChannel(peerNodeId);

// Send encrypted message
await annex.send(peerNodeId, {
  type: 'private_message',
  content: 'Hello from the annexed territory!',
});

// Handle incoming messages
annex.onMessage(({ from, payload, sessionId }) => {
  console.log(`Decrypted from ${from}:`, payload);
});

// Close channel when done
await annex.closeChannel(peerNodeId);

API Reference

async annex.openChannel(remoteNodeId)

Establishes an encrypted channel with a peer using ML-KEM-768 key exchange.

Parameters

remoteNodeId

string

The target peer's node ID

Returns

Promise<AnnexSession> // The established session object

async annex.send(remoteNodeId, payload)

Sends an encrypted message through an established ANNEX channel. Automatically opens a channel if needed.

Parameters

remoteNodeId	string	Target peer's node ID
payload	object \| string	Message content to encrypt and send

Returns

{
  sent: true,
  sessionId: "abc123...",
  sequence: 42
}

annex.onMessage(handler)

Registers a callback for decrypted incoming messages.

Handler Receives

{
  from: "node-abc123...",      // Sender's node ID
  sessionId: "session-xyz...", // Session identifier
  payload: { ... },            // Decrypted message content
  timestamp: 1736766000000     // Message timestamp
}

Returns

Handler ID (string) — use with offMessage() to remove

async annex.closeChannel(remoteNodeId)

Closes the ANNEX channel with a peer, releasing the session and notifying the remote node.

Parameters

remoteNodeId

string

The peer's node ID

annex.getStats()

Returns statistics about ANNEX operations.

Returns

{
  sessionsCreated: 5,
  messagesEncrypted: 142,
  messagesDecrypted: 138,
  handshakesFailed: 1,
  replaysBlocked: 0,
  activeSessions: 2,
  pendingHandshakes: 0
}

annex.listAnnexes()

Returns a list of all active ANNEX sessions (annexed territories).

Returns

[
  {
    nodeId: "node-abc123...",
    sessionId: "session-xyz...",
    established: true,
    createdAt: 1736766000000,
    lastActivity: 1736766300000,
    messageCount: 42,
    isExpired: false
  }
]

Security Properties

Post-Quantum Confidentiality

ML-KEM-768 (Kyber) key exchange is resistant to Shor's algorithm and HNDL attacks

Message Authentication

Every envelope is signed with ML-DSA-65 — recipients verify sender identity

Replay Protection

Sequence numbers bound to session ID via AAD in GCM authentication tag

Perfect Forward Secrecy

Automatic ephemeral key rotation every 5 minutes or 10,000 messages

Authenticated Encryption

AES-256-GCM provides both confidentiality and integrity with 128-bit auth tag

Protocol Stack Position

ANNEX sits above the mesh layer as the private messaging channel:

┌─────────────────────────────────────────────────────────────┐
│                    YAKMESH PROTOCOL STACK                   │
├─────────────────────────────────────────────────────────────┤
│  HTTP API          │ Public content delivery (CDN layer)    │
├─────────────────────────────────────────────────────────────┤
│  ANNEX             │ ML-KEM768 + AES-256-GCM encrypted P2P  │  ◄── You are here
├─────────────────────────────────────────────────────────────┤
│  Gossip            │ ML-DSA-65 signed message propagation   │
├─────────────────────────────────────────────────────────────┤
│  Beacon            │ Flood-based priority broadcasts        │
├─────────────────────────────────────────────────────────────┤
│  NAKPAK            │ Post-quantum onion routing             │
├─────────────────────────────────────────────────────────────┤
│  Mesh Core         │ WebSocket + Code Proof Protocol        │
└─────────────────────────────────────────────────────────────┘

Internal Message Types

Type	Description
annex:key_exchange	Initiates ML-KEM-768 key exchange with peer
annex:key_response	Completes key encapsulation and establishes session
annex:encrypted	Encrypted payload with sequence number
annex:rekey	Initiates perfect forward secrecy re-key
annex:close	Releases annexed territory (closes session)

YAKMESH ANNEX — v2.8.2

GitHub · npm · Discord

Continue the Journey

← Previous

YAK://

Content addressing

JHILKE

Key lifecycle