|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Build and Test Commands |
| 6 | + |
| 7 | +```shell |
| 8 | +# Run all tests with coverage |
| 9 | +go test -v -coverprofile=coverage.out ./... |
| 10 | + |
| 11 | +# Run a single test |
| 12 | +go test -v -run TestName ./pkg/enchantrix |
| 13 | + |
| 14 | +# Run tests with race detection (as CI does) |
| 15 | +go test -race -coverprofile=coverage.out -covermode=atomic ./... |
| 16 | + |
| 17 | +# Run fuzz tests (CI runs 10s) |
| 18 | +go test -run=Fuzz -fuzz=Fuzz -fuzztime=10s ./pkg/trix |
| 19 | + |
| 20 | +# Build |
| 21 | +go build -v ./... |
| 22 | + |
| 23 | +# Vet |
| 24 | +go vet ./... |
| 25 | + |
| 26 | +# Format |
| 27 | +go fmt ./... |
| 28 | +``` |
| 29 | + |
| 30 | +If Task is installed, these are available: |
| 31 | +- `task test` - Run tests with coverage |
| 32 | +- `task build` - Build project |
| 33 | +- `task fmt` - Format code |
| 34 | +- `task vet` - Run go vet |
| 35 | + |
| 36 | +## Architecture |
| 37 | + |
| 38 | +Enchantrix is an encryption library with a custom `.trix` file format and CLI tool. |
| 39 | + |
| 40 | +### Core Packages |
| 41 | + |
| 42 | +**pkg/enchantrix** - Core transformation framework |
| 43 | +- `Sigil` interface: defines `In(data)` and `Out(data)` for reversible/irreversible transforms |
| 44 | +- `Transmute()`: applies a chain of sigils to data |
| 45 | +- Built-in sigils: `reverse`, `hex`, `base64`, `gzip`, `json`, `json-indent` |
| 46 | +- Hash sigils: `md4`, `md5`, `sha1`, `sha224`, `sha256`, `sha384`, `sha512`, `ripemd160`, `sha3-*`, `sha512-*`, `blake2s-256`, `blake2b-*` |
| 47 | +- `NewSigil(name)`: factory function to create sigils by string name |
| 48 | +- `ChaChaPolySigil`: encryption sigil using XChaCha20-Poly1305 with pre-obfuscation layer |
| 49 | + |
| 50 | +**pkg/trix** - Binary file format (.trix) |
| 51 | +- Format: `[4-byte magic][1-byte version][4-byte header len][JSON header][payload]` |
| 52 | +- `Encode()`: serializes Trix struct to binary |
| 53 | +- `Decode()`: deserializes binary to Trix struct |
| 54 | +- `Pack()`/`Unpack()`: apply/reverse sigils on payload |
| 55 | +- Supports optional checksums via `ChecksumAlgo` field |
| 56 | + |
| 57 | +**pkg/crypt** - Cryptographic services facade |
| 58 | +- `Service`: aggregates hashing, checksums, RSA, and PGP operations |
| 59 | +- Hash types: `lthn` (custom), `sha512`, `sha256`, `sha1`, `md5` |
| 60 | +- Checksums: `Luhn()`, `Fletcher16/32/64()` |
| 61 | +- RSA: key generation, encrypt/decrypt via `pkg/crypt/std/rsa` |
| 62 | +- PGP: key generation, encrypt/decrypt, sign/verify, symmetric encrypt via `pkg/crypt/std/pgp` |
| 63 | + |
| 64 | +**cmd/trix** - CLI tool (Cobra-based) |
| 65 | +- `trix encode --magic XXXX --output file [sigils...]` |
| 66 | +- `trix decode --magic XXXX --output file [sigils...]` |
| 67 | +- `trix hash [algorithm]` |
| 68 | +- `trix [sigil]` - apply any sigil directly |
| 69 | + |
| 70 | +### Key Design Patterns |
| 71 | + |
| 72 | +1. **Sigil Chain**: Transformations are composable. Encoding chains sigils in order; decoding reverses. |
| 73 | +2. **Pre-Obfuscation**: `ChaChaPolySigil` applies XOR or shuffle-mask obfuscation before encryption so raw plaintext never goes directly to CPU encryption routines. |
| 74 | +3. **Streaming Support**: `Encode()`/`Decode()` accept optional `io.Writer`/`io.Reader` for streaming. |
| 75 | + |
| 76 | +## Testing Conventions |
| 77 | + |
| 78 | +- Tests use `testify/assert` and `testify/require` |
| 79 | +- Test files follow `*_test.go` pattern adjacent to implementation |
| 80 | +- `examples_test.go` files contain example functions for godoc |
| 81 | +- Fuzz tests exist in `pkg/trix` (`go test -fuzz`) |
| 82 | + |
| 83 | +## Go Version |
| 84 | + |
| 85 | +Minimum Go 1.25. Uses `go.work` for workspace management. |
0 commit comments