kxco-post-quantum

Post-quantum cryptography primitives for the KXCO stack.

ML-DSA-65 (FIPS 204) signatures and ML-KEM-768 (FIPS 203) key encapsulation, with key fingerprinting utilities. Wraps @noble/post-quantum — the Cure53-audited NIST reference implementation. All other kxco-pq-* packages depend on this one.

Install

npm install kxco-post-quantum

Requires Node.js 20.19+. ESM-only.

Quick start

import { mlDsa, mlKem, fingerprint, kidEquals } from 'kxco-post-quantum'

// ML-DSA-65 — sign and verify
const { publicKey, secretKey } = mlDsa.keypairFromMaster(masterSecret, 'signing-v1')
const sig = mlDsa.sign(secretKey, 'hello')
const ok  = mlDsa.verify(publicKey, 'hello', sig)  // true

// Key fingerprint
const kid = fingerprint(publicKey)  // e.g. '4a7c9e2f1b3d5680'
kidEquals(kid, kid)                 // true (constant-time)

// ML-KEM-768 — key encapsulation
const kemKeys = mlKem.keypairFromMaster(masterSecret, 'encryption-v1')
const { ciphertext, sharedSecret } = mlKem.encapsulate(kemKeys.publicKey)
const recovered = mlKem.decapsulate(ciphertext, kemKeys.secretKey)
// sharedSecret and recovered are the same 32 bytes

masterSecret is a Buffer or Uint8Array with at least 16 bytes of entropy (typically 32–64 bytes from an env var or KMS).

API

mlDsa — ML-DSA-65 (NIST FIPS 204)

| Export | Signature | Description | |---|---|---| | keypairFromMaster | (master, info?) → { publicKey, secretKey } | Deterministic keypair via HKDF-SHA-512. info defaults to 'ml-dsa-65-v1'. | | sign | (secretKey, message) → string | Signs a message. Returns a hex-encoded signature (6618 chars). | | verify | (publicKey, message, sigHex) → boolean | Verifies a hex-encoded signature. Returns false on any failure. | | ml_dsa65 | raw primitive | The underlying @noble/post-quantum primitive, re-exported. |

publicKey is 1952 bytes. secretKey is 4032 bytes. message accepts Buffer, Uint8Array, or string.

mlKem — ML-KEM-768 (NIST FIPS 203)

| Export | Signature | Description | |---|---|---| | keypairFromMaster | (master, info?) → { publicKey, secretKey } | Deterministic keypair via HKDF-SHA-512. info defaults to 'ml-kem-768-v1'. | | encapsulate | (publicKey) → { ciphertext, sharedSecret } | Generates a shared secret and ciphertext to send to the key holder. | | decapsulate | (ciphertext, secretKey) → Buffer | Recovers the shared secret from a ciphertext. Returns 32 bytes. | | ml_kem768 | raw primitive | The underlying @noble/post-quantum primitive, re-exported. |

publicKey is 1184 bytes. ciphertext is 1088 bytes. sharedSecret is 32 bytes.

fingerprint(publicKey) → string

First 16 hex characters of SHA-256 of the public key. Stable for the lifetime of the key. Accepts raw bytes or a hex string.

kidEquals(a, b) → boolean

Constant-time comparison of two kid strings. Use this when comparing user-supplied input — not ===.

deriveSeed(master, info, length) → Buffer

HKDF-SHA-512 derivation. master must be at least 16 bytes. info is a required domain-separation string. Returns length bytes.

What this does NOT do

• No identity credentials or verifiable claims
• No webhook signing or HMAC utilities (those are in kxco-pq-sdk)
• No relay, transport, or network layer
• No key storage or KMS integration
• No FIPS 140-3 module validation (the algorithms are FIPS-standardised; the module is not validated)

Part of the KXCO stack

kxco-post-quantum is the primitive layer. Everything else builds on it:

• kxco-pq-sdk — identity credentials, webhook signing, verifiable claims
• Other kxco-pq-* packages — domain-specific integrations

Install this package directly when you need ML-DSA or ML-KEM without the rest of the identity stack.

Security

Cryptographic operations delegate entirely to @noble/post-quantum and @noble/hashes, audited by Cure53 (2024). This package does not reimplement any NIST primitive.

To report a vulnerability: open a private security advisory or email [email protected].

License

MIT. See LICENSE.

Maintainers

Shayne Heffernan and John Heffernan — KXCO by Knightsbridge