@quantpass/pqc-liboqs

A unified, environment-aware TypeScript library providing Post-Quantum Cryptographic (PQC) primitives for the QuantPass ecosystem. This library wraps the NIST-standardized liboqs C-library using WebAssembly (WASM), providing pure-JavaScript portability without requiring native C++ compilation (node-gyp).

🛡️ Patent Implementation Reference

This library serves as the core "Enablement" engine for the following QuantPass patents:

• QP-02 (Hybrid Storage): Implements the AES-PQC key wrapping logic via TigerKEM (Kyber/ML-KEM).
• QP-05 (Trust Audit): Provides the Dilithium (ML-DSA) signature verification used in apps/admin-dashboard.

🏗️ Architecture

This package is designed as a Universal Isomorphic Library. It runs flawlessly in Node.js (CLI / AWS Lambda) and the Browser (Next.js / Browser Extensions) using a single, unified codebase.

Core Modules (/src)

• wasm_bindings.ts: A custom, memory-safe wrapper around the raw WebAssembly C-pointers. Bypasses Emscripten's WebIDL generator to manually manage WASM heap allocations (_malloc, _free) and memory bridging (getValue, setValue).
• web/wasm-wrapper.ts: The universal loader.
  • In Node: Injects the .wasm binary into an isolated node:vm sandbox, wiring up node:crypto to supply secure entropy directly to the C-engine.
  • In Browser: Utilizes dynamic imports and the native Web Crypto API.

🚀 Getting Started

Installation

This is a private workspace package. Link it to your application via pnpm:

pnpm add @quantpass/pqc-liboqs --workspace

Usage: Dilithium (ML-DSA) Signatures

import { Signature, getOqsWasm } from '@quantpass/pqc-liboqs/web';

async function generateAndSign() {
  // 1. Load the universal WASM module
  const oqs = await getOqsWasm();
  
  // 2. Instantiate the Dilithium primitive
  const sig = new Signature(oqs, 'Dilithium2');
  
  try {
    // 3. Generate Post-Quantum Keys
    const keys = sig.generate_keypair();
    console.log(`Public Key: ${keys.publicKey.length} bytes`);
    console.log(`Secret Key: ${keys.privateKey.length} bytes`);
    
    // 4. Sign a message
    const message = new TextEncoder().encode("Hello, Quantum World!");
    const signature = sig.sign(message, keys.privateKey);
    console.log(`Signature: ${signature.length} bytes`);
    
  } finally {
    // 5. CRITICAL: Free the C-pointers to prevent WASM memory leaks
    sig.free();
  }
}

Usage: Kyber (ML-KEM) Key Encapsulation

import { TigerKEM, getOqsWasm } from '@quantpass/pqc-liboqs/web';

async function encapsulate() {
  const oqs = await getOqsWasm();
  const kem = new TigerKEM(oqs, 'Kyber512');
  
  try {
    const keys = kem.generateKeypair();
    // ... logic to encapsulate/decapsulate AES keys ...
  } finally {
    kem.free();
  }
}

⚠️ Important Developer Notes

• Memory Management (CRITICAL): Because this library interfaces directly with C-pointers, JavaScript's garbage collector cannot automatically clean up WASM heap allocations. You must call .free() on instances of Signature and TigerKEM inside a finally block when you are done with them to prevent memory leaks in production.
• Never use naive .wasm imports: Do not attempt to natively import oqs from './liboqs.wasm'. This will crash Node's module loader. Always use the getOqsWasm() wrapper to ensure the Node.js vm sandbox successfully bridges the environment and supplies the required cryptographic entropy.