CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is bennc-js, a TypeScript implementation of the BENNCv1 (Butlersaurus Ephemeral No NONCEnse Chat) protocol specification. It provides client functionality for a binary pub/sub messaging protocol with encryption and compression support.

Development Commands

npm run build - Compile TypeScript to JavaScript (outputs to dist/)
npm run test - Run Jest test suite
npm run lint - Check code formatting with Prettier
npm run format - Format code with Prettier
npm install - Install dependencies (automatically runs tsc via postinstall)

Architecture

The codebase implements the BENNC protocol specification with the following structure:

Core Files

src/index.ts - Main entry point exporting all public APIs
src/mapping.ts - Central registry mapping message types (0x0000-0xFFFF) to their pack/unpack functions
src/common.ts - Protocol constants including MAX_DATA_LENGTH (1000 bytes), DEFAULT_KEY, and MessageTypes enum
src/messages/packet.ts - Core packet handling with packOutgoingPacket and unpackIncomingPacket functions

Message Types Implementation

Each BENNC message type has its own module in src/messages/:

subscribe.ts (0x0000) - Subscribe to message types
basic.ts (0x0001) - Basic encrypted chat messages
userDataRequest.ts (0x0002) - Request user information
userDataResponse.ts (0x0003) - Respond with user information
keepalive.ts (0x0005) - Connection keepalive messages
history.ts (0xFFFE) - Message history requests
unsubscribe.ts (0xFFFF) - Unsubscribe from message types

Protocol Implementation Details

Binary Protocol: Big-endian integers, UTF-8 strings
Message Structure: Client sends [Type(2)|Length(2)|Data(0-1000)], Server responds [Type(2)|SenderId(4)|Length(2)|Data(0-1000)]
Encryption: Uses Romulus-M AEAD (via romulus-js dependency) with 16-byte nonces for message types 0x0001, 0x0002, 0x0003
Max Data Size: 1000 bytes including nonce for encrypted messages
Dependencies: Includes local romulus-js cryptography implementation and color library for user data

Utilities

src/utilities/number.ts - Big-endian number conversion functions (numberToUint16BE, numberToUint32BE)
src/utilities/smart-buffer.ts - Buffer manipulation utility for packet construction/parsing

Key Architecture Patterns

Mapping System: Central packers and unpackers objects in mapping.ts provide type-safe message handling
Interface Separation: IncomingPacket vs OutgoingPacket interfaces handle client/server message structure differences
Encryption Integration: Encrypted message types automatically handle nonce generation and Romulus-M encryption
Protocol Compliance: Strict adherence to BENNC specification including reserved sender IDs (0xFFFFFF00-0xFFFFFFFF)

The codebase serves as a complete client-side implementation for connecting to BENNC chat servers via TCP or WebSocket protocols.

3.1 KiB Raw Blame History