61 lines
3.1 KiB
Markdown
61 lines
3.1 KiB
Markdown
# 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.
|