API Reference

// Generate or load Ed25519 keypair
loadOrCreateIdentity(): Promise<Identity>

// Sign messages with private key
signMessage(identity: Identity, message: Uint8Array): Uint8Array

// Verify signatures with DID
verifySignature(
  did: string,
  message: Uint8Array,
  signature: Uint8Array
): boolean

// Identity type
interface Identity {
  did: string;           // "did:zeta:<base58(publicKey)>"
  publicKey: Uint8Array;
  privateKey: Uint8Array;
}

// Create mutual trust ticket
createTrustTicket(
  from: Identity,
  to: string,                    // Recipient DID
  permissions: Permissions,
  ttlSec: number
): TrustTicket

// Verify trust ticket validity
verifyTrustTicket(ticket: TrustTicket): boolean

// Permissions type
interface Permissions {
  autoMesh: boolean;         // Auto-connect to peer
  autoSyncState: boolean;    // Auto-sync Bulletin state
  allowRelay: boolean;       // Allow message relay
  allowLanUpgrade: boolean;  // Allow LAN optimization
}

// Derive session key from room code (PBKDF2-SHA256, 10k iterations)
deriveSessionKey(
  identity: Identity,
  roomCode: string
): Promise<CryptoKey>

// HMAC signing for room messages
hmacSign(key: CryptoKey, data: Uint8Array): Promise<Uint8Array>

// HMAC verification
hmacVerify(
  key: CryptoKey,
  data: Uint8Array,
  signature: Uint8Array
): Promise<boolean>

// Block malicious peer
blockDid(did: string): void

// Check if peer is blocked
isBlocked(did: string): boolean

// Unblock peer
unblockDid(did: string): void

// Generate PNG data URL for web
generateQRDataURL(data: QRData): Promise<string>

// Generate SVG for scalability
generateQRSVG(data: QRData, options?: { width: number }): Promise<string>

// Generate for terminal display
generateQRTerminal(data: QRData): Promise<string>

// QR data format
interface QRData {
  version: number;
  did: string;
  sceneId?: string;  // Optional room/scene ID
  wsUrl?: string;    // Optional signaling server
}

// Generate new identity with mnemonic
generateMnemonic(options?: {
  strength?: 128 | 256;      // 12 or 24 words
  passphrase?: string;       // Optional extra security
}): Promise<MnemonicResult>

// Recover identity from mnemonic phrase
recoverFromMnemonic(
  mnemonic: string,
  passphrase?: string
): Promise<Identity>

// Validate mnemonic phrase
validateMnemonic(mnemonic: string): boolean

// Result type
interface MnemonicResult {
  mnemonic: string;
  identity: Identity;
  wordCount: number;
}

// Create WebRTC mesh transport
createTransport(opts: TransportOpts): Transport

interface TransportOpts {
  identity: Identity;
  signalingUrl: string;      // WebSocket signaling server
  roomCode: string;          // Room for discovery
  iceServers?: RTCIceServer[];  // Optional STUN/TURN
}

// Send data to specific peer
transport.send(peerId: string, data: Uint8Array): Promise<void>

// Broadcast to all connected peers
transport.broadcast(data: Uint8Array): Promise<void>

// Get list of connected peer DIDs
transport.getPeers(): string[]

// Disconnect from all peers
transport.disconnect(): Promise<void>

// Receive messages from peers
transport.onMessage(cb: (peerId: string, data: Uint8Array) => void): void

// Peer joined the mesh
transport.onPeerJoined(cb: (peerId: string) => void): void

// Peer left the mesh
transport.onPeerLeft(cb: (peerId: string) => void): void

// Connection state changed
transport.onConnectionStateChange(
  cb: (state: ConnectionState) => void
): void

type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'failed';

// Create new vector clock
createVectorClock(): VectorClock

// Increment clock for this peer
increment(clock: VectorClock, peerId: string): VectorClock

// Merge two clocks (max of each peer's count)
merge(clock1: VectorClock, clock2: VectorClock): VectorClock

// Compare causality
compare(clock1: VectorClock, clock2: VectorClock):
  'before' | 'after' | 'concurrent' | 'equal'

// Check if clock1 happened before clock2
happenedBefore(clock1: VectorClock, clock2: VectorClock): boolean

// Check if clocks are concurrent
areConcurrent(clock1: VectorClock, clock2: VectorClock): boolean

type VectorClock = Record<string, number>;  // { peerId: count }

// Create counter
createGCounter(): GCounter

// Increment counter for peer
increment(counter: GCounter, peerId: string, amount?: number): GCounter

// Get total value (sum of all peers)
value(counter: GCounter): number

// Merge two counters (max of each peer's count)
merge(counter1: GCounter, counter2: GCounter): GCounter

// Get specific peer's count
getPeerCount(counter: GCounter, peerId: string): number

type GCounter = Record<string, number>;  // { peerId: count }

// Create map
createLWWMap<K, V>(): LWWMap<K, V>

// Set key with timestamp
set<K, V>(
  map: LWWMap<K, V>,
  key: K,
  value: V,
  timestamp: Timestamp,  // Usually vector clock
  peerId: string
): LWWMap<K, V>

// Get current value
get<K, V>(map: LWWMap<K, V>, key: K): V | undefined

// Remove key (uses tombstone)
remove<K, V>(
  map: LWWMap<K, V>,
  key: K,
  timestamp: Timestamp,
  peerId: string
): LWWMap<K, V>

// Check if key exists
has<K, V>(map: LWWMap<K, V>, key: K): boolean

// Merge two maps (keeps highest timestamp)
merge<K, V>(map1: LWWMap<K, V>, map2: LWWMap<K, V>): LWWMap<K, V>

// Get all keys
keys<K, V>(map: LWWMap<K, V>): K[]

// Get all values
values<K, V>(map: LWWMap<K, V>): V[]

// Get all entries
entries<K, V>(map: LWWMap<K, V>): Array<[K, V]>

// Build tree from data blocks
buildMerkleTree(data: Uint8Array[]): MerkleNode | null

// Get root hash for comparison
getRootHash(tree: MerkleNode | null): Hash | null

// Generate inclusion proof
generateProof(tree: MerkleNode | null, data: Uint8Array): MerkleProof | null

// Verify proof
verifyProof(proof: MerkleProof): boolean

// Find differences between two trees
findDifferences(
  tree1: MerkleNode | null,
  tree2: MerkleNode | null
): Hash[]

// Get all leaf hashes
getLeaves(tree: MerkleNode | null): Hash[]

type Hash = string;  // Hex-encoded SHA-256

// Create bulletin instance
const bulletin = new Bulletin();

// Set field with TTL
bulletin.set(field: string, value: any, options: { ttlSec: number }): void

// Get current field value
bulletin.get(field: string): any

// Get snapshot for sync
bulletin.getSnapshot(): BulletinSnapshot

// Merge remote state (CRDT operation)
bulletin.merge(patch: BulletinSnapshot): void

// Listen for field changes
bulletin.onChange(callback: (field: string, value: any) => void): void

// Remove expired fields (called automatically)
bulletin.purgeExpired(): void

// Create mailbox queue
const mailbox = new MailboxQueue();

// Send message to offline peer
mailbox.send(to: string, message: any): Promise<void>

// Receive queued messages
mailbox.receive(): Promise<MailboxMessage[]>

// Encrypt data (AES-256-GCM)
encrypt(data: Uint8Array, key: CryptoKey): Promise<EncryptedData>

// Decrypt data
decrypt(encrypted: EncryptedData, key: CryptoKey): Promise<Uint8Array>

// Derive session key for encryption
deriveSessionKey(identity: Identity, roomCode: string): Promise<CryptoKey>

interface MailboxMessage {
  id: string;
  from: string;      // Sender DID
  to: string;        // Recipient DID
  payload: Uint8Array;
  timestamp: number;
  ttl: number;       // Seconds until expiry
}

// Create headless node (Lighthouse)
const lighthouse = new HeadlessNode({
  storagePath: string;  // e.g. '~/.lighthouse'
  port: number;         // HTTP API port
});

// Start daemon
await lighthouse.start(): Promise<void>

// Stop daemon
await lighthouse.stop(): Promise<void>