# Pegasus

[![Package Version](https://img.shields.io/hexpm/v/pegasus)](https://hex.pm/packages/pegasus)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/pegasus/)

![Wide logo](img/logo-wide.jpeg)

A modern cryptography library for Gleam, built with safety and ease of use in mind.

```sh
gleam add pegasus_crypto
```

## Features

- **Hash**: Secure hashing using BLAKE2b
- **Authentication**: Message authentication (HMAC)
- **Encryption**: XChaCha20 encryption

Pegasus is backed by the [Orion](https://github.com/orion-rs/orion) Rust cryptography library (via NIFs), providing high-performance cryptographic primitives.

## Examples

### Hashing

```gleam
import pegasus/hash
import gleam/bit_array

pub fn main() {
  let data = bit_array.from_string("Hello, world!")
  
  // Create a secure hash
  let assert Ok(digest) = hash.digest(data)
  
  // Use digest...
}
```

### Authentication

```gleam
import pegasus/authentication
import gleam/bit_array

pub fn main() {
  let data = bit_array.from_string("Message to authenticate")
  
  // Create a key from raw bytes
  let key_data = bit_array.from_string("AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH")
  let key = authentication.key_from_bitarray(key_data)
  
  // Create authentication tag
  let assert Ok(tag) = authentication.authenticate(data, key)
  
  // Verify the authentication tag
  let assert Ok(_) = authentication.verify(data, key, tag)
}
```

### Encryption

```gleam
import pegasus/xchacha20
import gleam/bit_array

pub fn main() {
  let plaintext = bit_array.from_string("Secret message")
  
  // Generate key and nonce
  let assert Ok(key) = xchacha20.generate_key()
  let assert Ok(nonce) = xchacha20.generate_nonce()
  
  // Encrypt data
  let assert Ok(ciphertext) = xchacha20.encrypt(key, nonce, plaintext)
  
  // Decrypt data
  let assert Ok(decrypted) = xchacha20.decrypt(key, nonce, ciphertext)
}
```

## Safety

Pegasus inherits strong security properties from Orion:

- Memory zeroization to prevent sensitive data leakage
- Constant-time implementations to prevent timing attacks
- Side-channel resistance

Additionally, Pegasus emphasizes safety through:
- Strong typing for cryptographic keys and operations
- Result types for proper error handling

## License

Pegasus is MIT licensed. The underlying cryptographic library, Orion, is also MIT licensed.

## Roadmap

Pegasus aims to support all cryptographic primitives available in the Orion library:

- **AEAD**: 
  - ✅ XChaCha20-Poly1305
  - ⬜ ChaCha20-Poly1305
- **Hashing**: 
  - ✅ BLAKE2b
  - ⬜ SHA2
  - ⬜ SHA3
- **XOF**: 
  - ⬜ SHAKE128
  - ⬜ SHAKE256
- **KDF**: 
  - ⬜ HKDF
  - ⬜ PBKDF2
  - ⬜ Argon2i
- **Key exchange**: 
  - ⬜ X25519
- **MAC**: 
  - ✅ HMAC (via BLAKE2b)
  - ⬜ Poly1305
- **Stream ciphers**: 
  - ✅ XChaCha20
  - ⬜ ChaCha20
- **KEM**: 
  - ⬜ ML-KEM
  - ⬜ DHKEM(X25519, HKDF-SHA256)

## Development

```sh
gleam run   # Run the project
gleam test  # Run the tests
cd native && cargo build --release  # Build Rust components
cp native/target/release/libpegasus_native.so priv/  # Copy NIF to priv directory for Erlang
```

Further documentation can be found at <https://hexdocs.pm/pegasus>.