# FalconTS

A TypeScript implementation of the Falcon signature scheme with a custom mnemonic implementation for key management.

## Overview

This project provides a TypeScript implementation of the Falcon signature scheme, along with a custom mnemonic implementation for generating, storing, and recovering Falcon keys using human-readable phrases.

## Features

- Falcon signature scheme implementation
- Custom mnemonic implementation for Falcon keys
- Key generation, signing, and verification
- Mnemonic phrase generation and validation
- Key recovery from mnemonic phrases

## Installation

```bash
npm install
```

## Usage

### Basic Falcon Usage

```typescript
import { Falcon } from './src/falcon';

// Create a Falcon instance
const falcon = new Falcon();
await falcon.init();

// Generate a key pair
await falcon.genkey();

// Get the key pair
const keypair = await falcon.getKeypair();
const publicKey = keypair.pk;
const privateKey = keypair.sk;

// Sign a message
const message = 'Hello, Falcon!';
const signature = await falcon.sign(message);

// Verify the signature
const isValid = await falcon.verify(message, signature);
console.log('Signature verification:', isValid ? 'Valid' : 'Invalid');
```

### Mnemonic Implementation

```typescript
import { generateMnemonic, mnemonicToUint8Array, uint8ArrayToMnemonic, validateMnemonic } from './src/mnemonic';
import { Falcon } from './src/falcon';

// Generate a random mnemonic
const mnemonic = generateMnemonic();
console.log('Generated mnemonic:', mnemonic);

// Convert mnemonic to seed
const seed = mnemonicToUint8Array(mnemonic);

// Create a Falcon instance
const falcon = new Falcon();
await falcon.init();

// Generate a key pair using the seed
await falcon.genkey(seed);

// Get the key pair
const keypair = await falcon.getKeypair();
const publicKey = keypair.pk;
const privateKey = keypair.sk;

// Later, recover the keys from the mnemonic
const recoveredSeed = mnemonicToUint8Array(mnemonic);
const recoveredFalcon = new Falcon();
await recoveredFalcon.init();
await recoveredFalcon.genkey(recoveredSeed);
const recoveredKeypair = await recoveredFalcon.getKeypair();
```

## Examples

Run the examples to see the mnemonic implementation in action:

```bash
# Run the basic example
npx ts-node src/example.ts

# Run the mnemonic example
npx ts-node mnemonic_example.ts
```

## How It Works

### Falcon Signature Scheme

Falcon is a lattice-based signature scheme that offers strong security with relatively small key and signature sizes. This implementation provides a TypeScript interface to the Falcon signature scheme.

### Custom Mnemonic Implementation

The mnemonic implementation converts between binary data (Uint8Array) and human-readable mnemonic phrases. It uses a list of 2048 common English words, with each word representing 11 bits of entropy. A mnemonic phrase consists of 12 words, providing 132 bits of entropy, which is sufficient for Falcon keys.

The implementation includes the following functions:

- `uint8ArrayToMnemonic(data: Uint8Array): string` - Converts a Uint8Array to a mnemonic phrase
- `mnemonicToUint8Array(mnemonic: string): Uint8Array` - Converts a mnemonic phrase to a Uint8Array
- `validateMnemonic(mnemonic: string): boolean` - Validates a mnemonic phrase
- `generateMnemonic(): string` - Generates a random mnemonic phrase

## License

MIT