# 🔐 Crystalline Lattice Protocol (CLP) - TypeScript

[![Build Status](https://github.com/clplab/clp-typescript/workflows/CI/badge.svg)](https://github.com/clplab/clp-typescript/actions)
[![npm version](https://badge.fury.io/js/%40clplab%2Fclp-typescript.svg)](https://www.npmjs.com/package/@clplab/clp-typescript)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)

> Next-generation post-quantum cryptography library built with TypeScript for maximum security and performance.

## ✨ Features

- 🛡️ **Post-Quantum Security**: Lattice-based cryptography resistant to quantum attacks
- 🚀 **High Performance**: Optimized algorithms with minimal memory footprint
- 🔄 **Auto-Evolution**: Dynamic security enhancement through protocol evolution
- 🎯 **Multiple Security Levels**: STANDARD, HIGH, and ULTIMATE configurations
- 🔐 **Authentication**: Built-in message authentication and integrity verification
- 📦 **Compression**: Optional data compression for reduced payload size
- 🌊 **Streaming Support**: Process large data efficiently with streaming API
- 🌐 **Universal**: Works in Node.js and browsers

## 🚀 Quick Start

### Installation

```bash
npm install @clplab/clp-typescript
```

### Basic Usage

```typescript
import CLP, { CLPConfigManager } from '@clplab/clp-typescript';

// Create a CLP instance with HIGH security
const config = CLPConfigManager.create('HIGH');
const clp = new CLP(config);

// Encrypt a message
const message = "Hello, quantum-resistant world!";
const encrypted = await clp.encrypt(message)
  .withAuthentication()
  .execute();

// Decrypt the message
const decrypted = await clp.decrypt(encrypted);
console.log(decrypted); // "Hello, quantum-resistant world!"

// Clean up resources
clp.destroy();
```

## 🔒 Security Levels

### 📊 STANDARD Security
- **Complexity**: ~18K operations
- **Use Case**: Fast operations, basic security needs
- **Features**: Basic encryption/decryption
- **Performance**: Fastest

### 🔒 HIGH Security
- **Complexity**: ~72K operations  
- **Use Case**: Balanced security and performance
- **Features**: Authentication, strict validation
- **Performance**: Balanced

### 🛡️ ULTIMATE Security
- **Complexity**: ~283K operations
- **Use Case**: Maximum enterprise-grade security
- **Features**: Authentication, compression, auto-growth, evolution
- **Performance**: High security with excellent speed

## 📖 API Reference

### Core Methods

```typescript
// Encryption with fluent API
const encrypted = await clp.encrypt(message)
  .withAuthentication()
  .withCompression()
  .withParallel()
  .execute();

// Direct decryption
const decrypted = await clp.decrypt(encrypted);

// Protocol evolution
await clp.evolve();

// Get protocol information
const info = clp.getInfo();
```

### Configuration

```typescript
import { CLPConfigManager } from '@clplab/clp-typescript';

// Pre-defined security levels
const standardConfig = CLPConfigManager.create('STANDARD');
const highConfig = CLPConfigManager.create('HIGH');
const ultimateConfig = CLPConfigManager.create('ULTIMATE');

// Custom configuration
const customConfig = CLPConfigManager.create('HIGH', {
  security: {
    lattice_dimension: 512,
    polynomial_degree: 128
  },
  features: {
    authenticated_encryption: true,
    auto_growth: true
  }
});
```

### Streaming API

```typescript
// Create a stream
const stream = clp.createStream({
  authentication: true,
  compression: true
});

// Process data in chunks
await stream.write("chunk 1");
await stream.write("chunk 2");

// Get encrypted result
const encrypted = await stream.flush();

// Clean up
stream.destroy();
```

### Utilities

```typescript
import { CLPUtils } from '@clplab/clp-typescript';

// System capabilities
const capabilities = CLPUtils.getCapabilities();

// Configuration validation
const validation = CLPUtils.validateConfig(config);

// Performance benchmarking
const benchmark = await CLPUtils.benchmark(100);

// Comprehensive testing
const testResults = await CLPUtils.test('HIGH');
```

## 🧪 Testing & Benchmarks

Run the comprehensive test suite:

```bash
# Run all tests
npm test

# Run specific test categories
npm run test:core     # Core functionality
npm run test:crypto   # Cryptographic layers
npm run test:config   # Configuration
npm run test:utils    # Utilities

# Development testing (faster)
npm run test:dev
npm run test:fast
```

Run benchmarks:

```bash
# Run the demo with all security levels
node demo.js
```

## 🔧 Development

### Build from Source

```bash
# Clone the repository
git clone https://github.com/clplab/clp-typescript.git
cd clp-typescript

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run demo
node demo.js
```


## 📊 Performance

| Security Level | Complexity | Encryption Time | Decryption Time |
|---------------|------------|-----------------|-----------------|
| STANDARD      | 18K        | ~0.5ms         | ~0.3ms          |
| HIGH          | 72K        | ~0.3ms         | ~0.2ms          |
| ULTIMATE      | 283K       | ~0.1ms         | ~0.1ms          |

*Benchmarks run on modern hardware. Results may vary.*

## 🛡️ Security

CLP implements state-of-the-art post-quantum cryptography:

- **Lattice-based encryption** resistant to quantum computer attacks
- **Multi-layer security** with hybrid cryptographic approaches
- **Dynamic evolution** to enhance security over time
- **Authentication tags** for message integrity verification
- **Memory-safe operations** with automatic cleanup

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Development Workflow

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Run the test suite: `npm test`
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔬 Research

Based on cutting-edge research in post-quantum cryptography. For technical details, see our [WHITEPAPER.md](WHITEPAPER.md).

## 📞 Support

- 📧 Email: support@clplab.org
- 💬 Discord: [CLP Community](https://discord.gg/clplab)
- 📚 Documentation: [docs.clplab.org](https://docs.clplab.org)
- 🐛 Issues: [GitHub Issues](https://github.com/clplab/clp-typescript/issues)

## 🙏 Acknowledgments

- Post-quantum cryptography research community
- TypeScript and Node.js ecosystems
- Open source contributors

---

**⚠️ Security Notice**: While CLP implements state-of-the-art post-quantum cryptography, this library is currently in development. For production use in critical systems, please conduct thorough security audits.

**Built with ❤️ by the CLP Research Collective**