romulus/CLAUDE.md

CLAUDE.md

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

Project Overview

This is romulus-js, a TypeScript implementation of the Romulus-M cryptography specification. It provides authenticated encryption with associated data (AEAD) functionality.

Development Commands

• npm run build - Compile TypeScript to JavaScript (outputs to dist/)
• npm run test - Run Jest test suite
• npm run lint - Run ts-standard linter
• npm install - Install dependencies (automatically runs tsc via postinstall)

Architecture

The codebase implements the Romulus-M AEAD cipher with the following structure:

Core Files

• src/romulus-m.ts - Main cryptographic implementation containing cryptoAeadEncrypt and cryptoAeadDecrypt functions
• src/skinny-128-384-plus.ts - SKINNY-128-384+ block cipher implementation used by Romulus-M
• src/constants.ts - Cryptographic constants

Public API

• src/encrypt.ts - High-level encrypt function that auto-generates nonces using UUID v4
• src/decrypt.ts - High-level decrypt function that handles nonce extraction
• src/index.ts - Main entry point exporting encrypt/decrypt functions

Key Implementation Details

• Uses 128-bit keys, nonces, and block sizes
• Implements LFSR-based counter with 56-bit precision
• Uses domain separation for different encryption phases
• Nonces are automatically prepended to ciphertext in the high-level API
• Low-level API (romulus-m.ts) works with number[] arrays
• High-level API works with Uint8Array for better developer experience

Testing

Tests are located in tests/ directory using Jest framework. Test files include:

• romulus-m.test.ts - Tests for core cryptographic functions
• encrypt.test.ts and decrypt.test.ts - Tests for high-level API
• romulus-m-reference.test.ts - Reference implementation tests

The TypeScript configuration automatically compiles on install and uses ts-jest for testing.