kxco-post-quantum

60-second quickstart

Install the package, fetch a freshly signed test vector from the live KXCO platform, post it back to verify — 200 OK. The same code path every production webhook runs.

# 1. Install
npm install kxco-post-quantum

# 2. Fetch a freshly signed test vector from the live KXCO platform
curl -s https://chain.kxco.ai/wallet/api/verify-demo > vector.json

# 3. Post it back — the server verifies HMAC + ML-DSA-65 against the live key
node --input-type=module -e '
  import fs from "node:fs"
  const v = JSON.parse(fs.readFileSync("vector.json", "utf8"))
  const h = v.headers
  const res = await fetch("https://chain.kxco.ai/wallet/api/verify-demo", {
    method:  "POST",
    headers: { "Content-Type": "application/json" },
    body:    JSON.stringify({
      timestamp:  h["X-KXCO-Timestamp"],
      body:       v.body,
      hmacSecret: v.hmacSecret,
      hmacSig:    h["X-KXCO-Signature"],
      pqSig:      h["X-KXCO-PQ-Signature"].replace(/^ml-dsa-65=/, ""),
      pqKid:      h["X-KXCO-PQ-Kid"],
    }),
  })
  console.log(res.status, await res.json())
'

# → 200 { kidMatch: true, hmac: { ok: true }, pq: { ok: true }, ... }

The platform signs every fetch fresh — no cached fixtures, no replay. verify-demo exposes the HMAC secret for the demo only; in production the HMAC secret never leaves the receiving server.

Pin the platform key

Production integrators should pin the KXCO platform public key & kid at the canonical well-known URL, not via the demo endpoint. The well-known JSON document declares the algorithm, FIPS spec, kid format, rotation policy, and contact addresses.

# Fetch and pin the canonical KXCO platform public key
curl -s https://kxco.ai/.well-known/kxco-pq-pubkey | jq .

# Returns:
# {
#   "version":   1,
#   "issuer":    "KXCO by Knightsbridge Group",
#   "algorithm": "ML-DSA-65",
#   "spec":      "NIST FIPS 204",
#   "kid":       "aa29f37ab7f4b2cf",
#   "publicKey": "648b1e9b...",      // 1952-byte hex
#   "rotation":  { "policy": ... },
#   "endpoints": { ... },
#   ...
# }

Pin both the kid and the publicKey. Reject signatures where X-KXCO-PQ-Kid doesn't match the pinned kid — that prevents acceptance of a rotated or compromised key until you've consciously updated your pin.

Install

npm install kxco-post-quantum

Requires Node.js 18+. ESM-only (use import, not require).

What's in the box

Sign a webhook (hybrid HMAC + ML-DSA-65)

Production pattern used across KXCO services. Every webhook delivery carries an HMAC for speed plus an ML-DSA-65 signature for non-repudiation. A kid fingerprint identifies the signing key without revealing it.

import { webhook, mlDsa, fingerprint, deriveSeed } from 'kxco-post-quantum'

// Derive an ML-DSA-65 keypair deterministically from a master secret + scope
const seed   = deriveSeed(MASTER_SECRET, 'webhook/v1')
const { publicKey, secretKey } = mlDsa.keygen(seed)
const kid    = fingerprint(publicKey)  // short, stable ID for the header

// Sign an outgoing webhook payload
const { headers, body } = webhook.sign({
  payload:   JSON.stringify({ event: 'transfer.settled', amount: '1000.00' }),
  hmacKey:   HMAC_SHARED_SECRET,
  pqcSecret: secretKey,
  kid,
})

// headers now contains:
//   sig-hmac    — HMAC-SHA-256 of payload (fast verify)
//   sig-pqc     — ML-DSA-65 signature   (non-repudiation)
//   sig-kid     — fingerprint identifying the signing key
//   sig-ts      — unix timestamp (replay window enforced on verify)

Verify on the receiving end:

import { webhook } from 'kxco-post-quantum'

const valid = webhook.verify({
  payload,
  headers,
  hmacKey:    HMAC_SHARED_SECRET,
  pqcPublic:  publicKeyForKid(headers['sig-kid']),
  maxAgeMs:   5 * 60 * 1000,   // 5 minute replay window
})
if (!valid) throw new Error('Invalid webhook signature')

ML-DSA-65 signatures (FIPS 204)

import { mlDsa } from 'kxco-post-quantum/ml-dsa'

const { publicKey, secretKey } = mlDsa.keygen()      // random
const sig = mlDsa.sign(secretKey, new TextEncoder().encode('hello'))
const ok  = mlDsa.verify(publicKey, sig, new TextEncoder().encode('hello'))
// ok === true

ML-KEM-768 key encapsulation (FIPS 203)

import { mlKem } from 'kxco-post-quantum/ml-kem'

// Recipient generates a keypair
const { publicKey, secretKey } = mlKem.keygen()

// Sender encapsulates a shared secret using recipient's public key
const { cipherText, sharedSecret: senderSecret } = mlKem.encapsulate(publicKey)

// Recipient decapsulates
const recipientSecret = mlKem.decapsulate(cipherText, secretKey)

// senderSecret === recipientSecret  (32-byte shared key)

Deterministic key derivation

One master secret → many scoped child keys via HKDF-SHA-512 with domain separation. Rotate or revoke individual scopes without rotating everything.

import { deriveSeed } from 'kxco-post-quantum/derive'

const seedWebhook     = deriveSeed(MASTER, 'webhook/v1')
const seedAttestation = deriveSeed(MASTER, 'attestation/v1')
const seedVault       = deriveSeed(MASTER, 'vault-signer/v3')

// Each seed is independent; compromise of one does not affect the others.

What this isn't

• Not a TLS library. Use OpenSSL 3.5+ or BoringSSL for X25519MLKEM768 hybrid at the network edge.
• Not a KMS. Use AWS KMS, HashiCorp Vault, or an HSM for production secret storage. This package handles cryptographic operations on keys you load.
• Not FIPS 140-3 certified. The underlying algorithms are FIPS-standardised (203/204); the module is not currently CMVP-validated.