Aegis Hybrid Crypto

a TypeScript/Node.js library for recipient encryption using a hybrid classical and post-quantum construction. It uses standardized, reviewed primitives from Node.js/OpenSSL and the Noble cryptography projects; it does not implement cryptographic algorithms itself.

Construction

• Key exchange: ephemeral X25519 ECDH plus ML-KEM-768 (FIPS 203). The two 32-byte secrets are concatenated and processed with HKDF-SHA384. The encapsulation transcript is hashed into the HKDF salt.
• Payload encryption: AES-256-GCM with a fresh, CSPRNG-generated 96-bit nonce and a 128-bit authentication tag. The version, suite, ephemeral X25519 key, ML-KEM ciphertext, and hash of caller-supplied associated data are authenticated.
• Signatures: ML-DSA-65 (FIPS 204) plus Ed25519. Verification requires both signatures to be valid.
• Randomness: Node's cryptographic random source, used by Noble and node:crypto.

The hybrid combines independent classical and post-quantum shared secrets so the derived payload key remains protected if at least one component remains secure. It uses NIST-standardized post-quantum algorithms with no known practical attacks; it is not “unbreakable,” and security still depends on correct integration, endpoint security, dependency integrity, and key handling.

Requirements

• Node.js 20.19 or newer
• ESM

npm install
npm test
npm run build

Usage

import {
  decrypt,
  encrypt,
  generateEncryptionKeyPair,
  generateSigningKeyPair,
  sign,
  verify,
} from 'aegis-hybrid-crypto';

const bytes = new TextEncoder();

// Recipient generates and securely stores this private key bundle.
const recipient = generateEncryptionKeyPair();

// Sender needs only the recipient's authenticated public key bundle.
const message = bytes.encode('hello');
const context = bytes.encode('message-id:123');
const envelope = encrypt(message, recipient.publicKey, context);

// Recipient must supply the identical associated data.
const plaintext = decrypt(envelope, recipient.privateKey, context);

// Independent hybrid signing keys.
const signer = generateSigningKeyPair();
const signature = sign(message, signer.privateKey);
if (!verify(message, signature, signer.publicKey)) throw new Error('Invalid signature');

serializeCiphertext / deserializeCiphertext and serializeSignature / deserializeSignature provide base64-in-JSON transport helpers. Key serialization and storage are intentionally application-specific; store private key material in a platform keystore or secrets manager, never in source control or logs.

Threat model and limits

this package protects message confidentiality and integrity against passive capture and active ciphertext modification, including “harvest now, decrypt later” adversaries, assuming either X25519 or ML-KEM-768 remains secure and the recipient public key is authentic. Hybrid signatures provide authentication while both ML-DSA-65 and Ed25519 verification are required.

It does not provide identity certification, public-key distribution, replay protection, forward secrecy after recipient private-key compromise, streaming/file framing, traffic-analysis resistance, or secure key storage. Applications should authenticate public keys, include a unique protocol/message identifier as associated data, enforce replay policy, limit input sizes before parsing, and rotate keys. A recipient private-key compromise permits decryption of previously recorded envelopes because ML-KEM uses the recipient's static key.

Decryption intentionally returns one generic error for malformed inputs, wrong keys, and failed authentication. JavaScript cannot guarantee memory locking or reliable zeroization; temporary derived-secret buffers are overwritten on the normal path as defense in depth, but callers should not treat that as a hard guarantee. Constant-time-sensitive primitive operations are delegated to the underlying libraries; orchestration and parsing code are not promised to be constant-time.

Password-derived keys are not part of recipient public-key encryption. If an application encrypts exported keys with a password, use a maintained Argon2id implementation with deployment-specific, reviewed memory/time parameters and a random salt; do not substitute a password directly for any key accepted here.