# 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.