falconTS/README.md

# FalconTS

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

This project is based on: https://github.com/pqcsf/falcon-sign-js

The only purpose of this project is to provide an easy-to-use Typescript module that allows the Falcon implementation of the above repository to be used in TS projects with types included and with some utilities.

## 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
- Hex and Base64 encoding/decoding utilities

## Installation

This will install https://github.com/pqcsf/falcon-sign-js.

```bash
npm install
```

## Usage

### Basic Falcon Usage

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

// 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();
```

### Hex and Base64 Encoding

The Falcon class provides utilities for working with hex and base64 encoded keys and signatures:

```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 keys in hex format
const publicKeyHex = await falcon.getPublicKeyHex();
const privateKeyHex = await falcon.getPrivateKeyHex();

// Get keys in base64 format
const publicKeyBase64 = await falcon.getPublicKeyBase64();
const privateKeyBase64 = await falcon.getPrivateKeyBase64();

// Sign a message and get the signature in hex
const message = 'Hello, Falcon!';
const signatureHex = await falcon.signHex(message);

// Verify a hex signature
const isValid = await falcon.verifyHex(message, signatureHex);

// Sign a message and get the signature in base64
const signatureBase64 = await falcon.signBase64(message);

// Verify a base64 signature
const isValidBase64 = await falcon.verifyBase64(message, signatureBase64);

// Create a public key from a private key in hex format
const derivedPublicKeyHex = await falcon.publicKeyCreateHex(privateKeyHex);

// Set a private key from hex format
const newPublicKeyHex = await falcon.setPrivateKeyHex(privateKeyHex);

// Create a public key from a private key in base64 format
const derivedPublicKeyBase64 = await falcon.publicKeyCreateBase64(privateKeyBase64);

// Set a private key from base64 format
const newPublicKeyBase64 = await falcon.setPrivateKeyBase64(privateKeyBase64);
```

## Examples

Run the examples to see the mnemonic implementation in action:

```bash
# Run the basic example
npx ts-node 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

## Tests

Run the test suite using:

```bash
npm test
```

## Credits

This project is a TypeScript wrapper around the [falcon-sign-js](https://github.com/pqcsf/falcon-sign-js) library, which provides the core Falcon signature implementation. We've added TypeScript types, a custom mnemonic implementation, and additional utilities to make it easier to use in TypeScript projects.

## License

MIT