@pyusstudio/pqc-hybrid (Open PQC Hybrid) v2.1

@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. Version 2.0 introduces the HPQT (Hybrid Post-Quantum Token) ecosystem, an elite, proprietary architecture completely immune to the "Harvest Now, Decrypt Later" threat model.

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

npm install @pyusstudio/pqc-hybrid

Quick Start

import { 
  generateHybridKemKeyPair, 
  encryptHybrid, 
  decryptHybrid, 
  generateHybridSigKeyPair, 
  signHybrid, 
  verifyHybrid,
  generateHPQTKeys,
  signHPQT,
  verifyHPQT,
  decodeHPQT,
  HPKSManager
} 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
})();

3. Built-in HPQT Authentication (The PQC Token Ecosystem)

HPQT is your proprietary drop-in replacement for standard JWTs. It actively defends your distributed applications against state-actor "Harvest Now, Decrypt Later" execution capabilities.

import { generateHPQTKeys, signHPQT, verifyHPQT } from '@pyusstudio/pqc-hybrid';

(async () => {
    // A. Generate Native Proprietary Post-Quantum Bindings
    const hpqtKeys = await generateHPQTKeys();
    
    // B. Signing an HPQT organically enforcing micro-expiration spans natively
    const payloadOpts = { 
      expiresIn: 3600, // Mandated 1-hour HNDL defensive limit recommendation
      hkid: 'key-A-prod', // Hybrid Key ID directly binding the algorithm map
      issuer: 'core-auth-server' 
    };
    
    const token = await signHPQT({ userId: 'dev_555', role: 'admin' }, hpqtKeys.privateKey, payloadOpts);
    
    // C. Rigorous Mathematical Validation preventing Token Stripping
    try {
        const payload = await verifyHPQT(token, hpqtKeys.publicKey, { issuer: 'core-auth-server' });
        console.log("Authorized Session Confirmed:", payload);
    } catch (err) {
        console.error("Compromised validation:", err); // Traps invalid mathematical M' bindings safely
    }
})();

4. Enterprise-Grade HPKS & Express.js Zero-Downtime Rotation

To prevent global backend architecture collapses from massive PQC token execution scaling, use the fully optimized Node.js HPKSManager dynamically interacting via the included Express hpksEndpoint middleware caching endpoints natively.

import express from 'express';
import { 
  generateHPQTKeys, 
  HPKSManager, 
  hpqtAuthMiddleware, 
  hpksEndpoint 
} from '@pyusstudio/pqc-hybrid';

const app = express();
const hpksManager = new HPKSManager();

(async () => {
   // A. Initialize Zero-Downtime Controller Ecosystem
   const key2025 = await generateHPQTKeys();
   hpksManager.addActiveKey(key2025.publicKey, 'active-key-25');

   // B. Dynamically Rotate Key state (Leaves 2025 mathematically query-able but flags 'retired', activates 2026)
   const key2026 = await generateHPQTKeys();
   hpksManager.rotateKey(key2026.publicKey, 'active-key-26'); 
})();

// C. Instantly export keys externally with highly optimized ETag processing bandwidth defenses!
app.get('/.well-known/hpks.json', hpksEndpoint(hpksManager));

// D. Rigorous automatic Bearer Validation
app.get('/secure-dashboard', hpqtAuthMiddleware({ hpksManager }), (req, res) => {
    // req.hpqt securely populates after checking the ETag and verifying the M' matrix
    res.json({ data: "Top Secret Quantum Level Code", user: req.hpqt.userId });
});

app.listen(3000);

5. HPQP: Hybrid Post-Quantum Password Storage

HPQP implements a 3-layer, defense-in-depth password hashing architecture—modeled after Dropbox's proven design—upgraded with ML-KEM post-quantum key encapsulation to neutralize "Harvest Now, Decrypt Later" attacks against stolen credential databases.

| Layer | Mechanism | Defends Against | |:------|:----------|:---------------| | L1 — scrypt | Memory-hard password hashing (native node:crypto) | GPU/ASIC brute-force + Grover's quadratic speedup | | L2 — HMAC-SHA512 | Server-side pepper binding | Database-only theft (attacker needs pepper separately) | | L3 — Hybrid KEM | Encrypt hash with X25519 + ML-KEM-768 + AES-256-GCM | Quantum HNDL + offline cracking |

Each password hash receives a unique, ephemeral KEM encapsulation — even bulk database theft cannot enable offline brute-force without the ML-KEM private key.

import {
  generateHPQPKeys,
  hashPassword,
  verifyPassword,
  HPQP_PRESETS
} from '@pyusstudio/pqc-hybrid';
import * as crypto from 'node:crypto';

(async () => {
  // A. One-time server setup
  const serverKeys = await generateHPQPKeys();
  const pepper = crypto.randomBytes(32); // Store in HSM or env, NOT in DB

  // B. Registration: hash a password (unique KEM encapsulation per user)
  const stored = await hashPassword(
    'my-secure-password',
    serverKeys.publicKey,
    pepper,
    HPQP_PRESETS.standard  // ~500ms, 128 MiB memory
  );
  // → Save ~1.5KB Buffer to your database

  // C. Login: verify a password
  const isValid = await verifyPassword(
    'my-secure-password',
    stored,
    serverKeys.privateKey,
    pepper
  );
  console.log('Password valid:', isValid); // true
})();

Difficulty Presets:

| Preset | scrypt Cost (N) | Target Latency | Use Case | |:-------|:---------------|:---------------|:---------| | interactive | 2^15 (32,768) | < 200ms | Login forms, real-time auth | | standard | 2^17 (131,072) | < 1s | Default; general-purpose | | sensitive | 2^20 (1,048,576) | < 3s | Admin accounts, financial systems |

The binary serialization format includes a version byte (0x01) enabling future algorithm migration (e.g., Argon2id) without breaking stored passwords.

6. Solving "The PQ Scaling Cliff": Verify-Only Builds

Standard Post-Quantum token parsing requires massive memory footprints causing Maximum Transmission Unit (MTU) fragmentation limits dropping HTTP execution heavily on edge networking systems.

You can completely bypass all heavy internal matrix calculations when deploying code to verifying environments (e.g., AWS Lambda@Edge, Cloudflare Workers). Exclusively import from the verify-only ecosystem:

// Extremely lightweight distributed edge imports bypassing all key generation matrix logic
import { verifyHPQT, decodeHPQT } from '@pyusstudio/pqc-hybrid/verify-only';

// You use this specifically on receiving validation APIs

For advanced security context defining algorithmic bindings, MTU mitigation parameters, and absolute theoretical references confirming zero-side channel extraction processes, view the comprehensive HPQT Advanced Security Whitepaper.

Project Structure

.
├── dist/                  # Build artifacts
├── docs/                  # Extended documentation and guides
├── examples/              # Usage examples and scratch files
├── src/                   # Source code (TypeScript)
│   ├── aead.ts            # Hybrid AEAD (AES-256-GCM + KEM)
│   ├── hpks.ts            # HPKS Key Set Manager (zero-downtime rotation)
│   ├── hpqp.ts            # HPQP Password Storage (3-layer: scrypt + HMAC + KEM)
│   ├── hpqt.ts            # HPQT Token System (JWT replacement)
│   ├── index.ts           # Main entry point
│   ├── kem.ts             # Hybrid KEM (X25519 + ML-KEM-768)
│   ├── middleware.ts      # Express.js Auth Middleware
│   ├── sig.ts             # Hybrid Signatures (Ed25519 + ML-DSA-65/SLH-DSA)
│   ├── utils.ts           # Binary bundle/unbundle utilities
│   └── verify-only.ts     # Lightweight verify-only exports
├── 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:

npm run build

Test

To run the test suite:

npm run test

Cleanup

To remove build artifacts and reset the environment:

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.