npm package: @pyusstudio/pqc-hybrid
Description: Production-ready Post-Quantum & Classical Hybrid cryptography library for Node.js
Author: pyusstudio
Latest version: 1.0.1

# @pyusstudio/pqc-hybrid (Open PQC Hybrid)

`@pyusstudio/pqc-hybrid` is a developer-friendly, production-ready, Node.js-native library providing Post-Quantum Cryptography (PQC) integrated seamlessly with proven traditional classical algorithms into unified **Hybrid Cryptography** methods.

As NIST FIPS 203, 204, and 205 dictate, the future is Post-Quantum. However, to hedge against theoretical mathematical vulnerabilities in brand-new algorithms, a "Defense-in-Depth" Hybrid Cryptography approach ensures that communication and authenticated data remain secure as long as *at least one* algorithm (either classical or PQC) remains unbroken. 

> **Important Statement on Execution:** PQC algorithms demand significantly larger payloads and varied CPU times. This library relies on asynchronous, non-blocking integrations wrapping synchronous Node operations using `Promise` to avoid event-loop starvation, specifically targeting the aggressive multi-threaded background pools available in Node.js. 
> 
> *Requires Node.js v24.7.0 or higher for native `ml-kem`, `ml-dsa`, and `slh-dsa` support directly in the `node:crypto` matrix, avoiding heavy WASM fallback degradation.*

## Features & The "Best Combinations"

Based on extensive industry research focusing on computational latency, memory overhead, and network bandwidth (MTU compatibility), this package standardizes the "Best Combinations":

- **Hybrid Key Exchange (KEM): `X25519 + ML-KEM-768`**
  - **Why?** X25519 is computationally efficient and mathematically completely distinct from lattices. ML-KEM-768 executes in microseconds on modern processors natively, making the performance penalty trivial while providing Category 3 security constraints.
- **Hybrid General Signatures: `Ed25519 + ML-DSA-65`**
  - **Why?** Ed25519 offers ultra-compact signatures. ML-DSA provides rapid verification, acting as the ultimate digital signature replacement. *Warning: Signatures will exceed 3.3 KB, ensure your network MTU parameter configurations do not block large data packets.*
- **Hybrid Offline/Conservative Signatures: `Ed25519 + SLH-DSA-SHA2-128f`**
  - **Why?** SLH-DSA provides conservative, unassailable security based exclusively on hashes (dodging lattice-breaking algorithms entirely). Due to its computational latency (seconds to execute) and 17KB footprints, this method should exclusively be utilized for offline operations like long-lived root CA and document signing architectures.
- **Hybrid AEAD (Authenticated Encryption):** Complete end-to-end wrapper bridging `AES-256-GCM` encryption directly to the `Hybrid Post-Quantum Key Exchange` process securely.

## Installation

```bash
npm install @pyusstudio/pqc-hybrid
```

## Quick Start
```typescript
import { 
  generateHybridKemKeyPair, 
  encryptHybrid, 
  decryptHybrid, 
  generateHybridSigKeyPair, 
  signHybrid, 
  verifyHybrid 
} from '@pyusstudio/pqc-hybrid';

// 1. Authenticated Encryption via Hybrid KEM
(async () => {
    // Receiver generates Keys
    const keyPair = await generateHybridKemKeyPair();

    // Sender encapsulates AES key and encrypts
    const payload = "Secure Payload via X25519 + ML-KEM-768";
    const encryptedBundle = await encryptHybrid(payload, keyPair.publicKey);

    // Receiver decapsulates symmetric bundle and decrypts
    const decryptedMessage = await decryptHybrid(encryptedBundle, keyPair.privateKey);
    console.log(decryptedMessage.toString('utf8')); // "Secure Payload via X25519 + ML-KEM-768"
})();

// 2. Hybrid Signatures
(async () => {
    // Generate Ed25519 + ML-DSA-65 keys
    const signKeys = await generateHybridSigKeyPair('ml-dsa-65');
    
    // Sign payload
    const signature = await signHybrid("Banking transaction details", signKeys.privateKey);

    // Verify
    const isValid = await verifyHybrid("Banking transaction details", signature, signKeys.publicKey);
    console.log("Is Payload Genuine?", isValid); // true
})();
```

## Project Structure

```text
.
├── dist/                # Build artifacts
├── docs/                # Extended documentation and guides
├── examples/            # Usage examples and scratch files
├── src/                 # Source code (TypeScript)
│   ├── aead.ts          # Hybrid AEAD Implementation
│   ├── index.ts         # Main entry point
│   ├── kem.ts           # Hybrid KEM Implementation
│   └── sig.ts           # Hybrid Signature Implementation
├── tests/               # Test suite (Vitest)
├── package.json         # Project configuration & scripts
└── README.md            # Project overview
```

## Development & Maintenance

### Build
To compile the TypeScript source to the `dist` directory:
```bash
npm run build
```

### Test
To run the test suite:
```bash
npm run test
```

### Cleanup
To remove build artifacts and reset the environment:
```bash
npm run clean
```

## Anti Race-Condition Measures
This project bundles algorithms serially ensuring that cross-protocol misconfigurations and partial memory leaks do not race. Native crypto module APIs are structured specifically avoiding partial application payload overlaps.