pubsub/LLM.md

Hanzo PubSub

Overview

NATS server fork with Quasar PQ consensus, ZAP control plane, zapdb persistence, and PQ-safe encrypted replication via luxfi/age (ML-KEM-768 + X25519).

Upstream: NATS Server (Apache-2.0). server/ imports nats-io/* directly; the rest is Hanzo-built.

Go module: github.com/hanzoai/pubsub Binary: pubsub JetStream (persistent streams/consumers/KV) enabled by default.

Architecture

• NATS protocol (port 4222): pub/sub messaging
• PubSub (JetStream): persistent streams, consumers, KV store — enabled by default
• ZAP mgmt (port 9222): binary RPC control plane with HMAC auth
• ZAP consensus (port 9223): Quasar P2P with BLS+PQ signature verification
• HTTP mgmt (port 9280): REST API with bearer token auth
• Quasar consensus (opt-in): dual PQ consensus (BLS + ML-DSA/Corona)
• zapdb store (opt-in): embedded KV with AES-256 at rest + PQ-safe backup via age

Storage Stack

PubSub streams → zapdb (AES-256 at rest) → age (ML-KEM-768+X25519) → S3/disk

• At rest: AES-256 via zapdb EncryptionKey
• Backups: PQ-encrypted with luxfi/age HybridRecipient (ML-KEM-768 + X25519, X-Wing)
• Restore: PQ-decrypted with luxfi/age HybridIdentity

Quasar Consensus

Upstream luxfi/consensus HEAD implements triple consensus (BLS + Corona + ML-DSA). PubSub pins luxfi/consensus v1.22.0 which has dual consensus (BLS + ML-DSA/Corona):

1. BLS12-381 — classical fast-path, 48-byte aggregate proof
2. PQ proof (ML-DSA-65 or Corona Ring-LWE) — post-quantum, variable size

Triple mode (TripleSignRound1, all 3 in parallel) available when pubsub upgrades to v1.23+.

Types: QuasarConsensus, QuasarSignature (aliases for upstream v1.22.0 legacy names).

Security

• HTTP: bearer token auth (PUBSUB_HTTP_TOKEN), constant-time comparison
• ZAP mgmt: shared secret auth (PUBSUB_ZAP_SECRET), peer-allowlist on first message
• ZAP consensus: BLS+ML-DSA signature verification per vote, peer-validator identity binding
• Finality: requires op in pending set with verified votes (no trust-peer finality)
• Proposal: hash-payload binding verified (SHA-256(opJSON) == claimed hash)
• Pending: capped at 65536 to prevent OOM
• HTTP body: capped at 1MB
• Health: minimal response without auth, full details with auth
• zapdb: AES encryption enforced for disk stores (key length validated: 16/24/32)
• Backups: 0o600 file permissions

ZAP Opcodes

Management (0x01-0x06, HMAC auth)

• 0x01: CreateStream
• 0x02: DeleteStream
• 0x03: ListStreams
• 0x04: Publish
• 0x05: GetStreamInfo
• 0x06: HealthCheck (unauthenticated)

Quasar Control (0x10-0x13, HMAC auth)

• 0x10: QuasarSubmit
• 0x11: QuasarStatus
• 0x12: QuasarVerify
• 0x13: QuasarRotate

Quasar P2P (0x20-0x24, crypto-verified)

• 0x20: Propose (hash-verified)
• 0x21: Vote (BLS+PQ signature verified, peer-identity bound)
• 0x22: Finalized (requires pending op + verified votes)
• 0x23: SyncReq (capped at 100 responses)
• 0x24: SyncResp

Environment Variables

PUBSUB_ZAP_PORT          ZAP mgmt port (default: 9222)
PUBSUB_HTTP_PORT         HTTP management port (default: 9280)
PUBSUB_HTTP_TOKEN        HTTP bearer token (empty = no auth)
PUBSUB_ZAP_SECRET        ZAP shared secret for HMAC (empty = no auth)
PUBSUB_QUASAR_ENABLED    Enable Quasar consensus (true/1)
PUBSUB_QUASAR_THRESHOLD  Signature threshold (default: 1)
PUBSUB_QUASAR_VALIDATORS Comma-separated validator IDs
PUBSUB_QUASAR_VALIDATOR_ID  This node's validator identity
PUBSUB_QUASAR_ZAP_PORT  Consensus ZAP port (default: 9223)
PUBSUB_QUASAR_PEERS     Comma-separated peer addresses (host:port)
PUBSUB_QUASAR_DISCOVER  Enable mDNS peer discovery (true)
PUBSUB_STORE_ENABLED    Enable zapdb store (true/1)
PUBSUB_STORE_DIR        zapdb data directory

Build & Test

go build ./...
go test ./internal/... -v
./pubsub                              # JetStream enabled by default
./pubsub -sd /data/pubsub             # with storage directory
PUBSUB_QUASAR_ENABLED=true ./pubsub   # with Quasar consensus

Key Packages

• internal/consensus/ — Quasar consensus + ZAP P2P (7 tests)
• internal/store/ — zapdb + PQ-safe age backup/restore (9 tests)
• internal/mgmt/ — ZAP + HTTP management with auth (9 tests)
• server/ — NATS/PubSub server core

Dependencies

• github.com/hanzoai/pubsub-go — PubSub Go client (NATS client fork)
• github.com/luxfi/zap — Zero-copy binary RPC
• github.com/luxfi/consensus — BLS + PQ consensus engine
• github.com/luxfi/zapdb/v4 — Embedded KV store (BadgerDB fork)
• github.com/luxfi/age — PQ-safe encryption (ML-KEM-768 + X25519)
• server/ imports nats-io/* (upstream fork, not our code)