KXCO Post-Quantum SDK

Install

Install the umbrella package for the full stack, or add individual packages for targeted capabilities.

# Full stack — one install, every module
npm install kxco-pq

# Individual packages:
npm install kxco-pq-sdk               # hierarchical quantum-resistant identity
npm install kxco-pq-hsm               # HSM key management
npm install kxco-pq-audit             # tamper-evident audit logging
npm install kxco-pq-attest            # cryptographically signed attestations
npm install kxco-pq-tls               # post-quantum secure channels
npm install kxco-pq-vault             # file and data encryption vault
npm install kxco-post-quantum-webhook # hybrid webhook signing
npm install kxco-post-quantum         # core PQC primitives
npm install kxco-pq-cli               # CLI key management tooling
npm install kxco-verify               # browser-safe attestation verifier
npm install kxco-pq-chain             # meta-transaction relay client (Armature L1)
npm install kxco-pq-agent             # machine identity — AI agents, robots, IoT (commercial)

All thirteen packages

From raw cryptographic primitives to enterprise identity management. Eleven packages are open-source under Apache-2.0 or MIT. kxco-pq-chain and kxco-pq-agent are commercial — contact us for licensing.

Identity — institution-issued, KYC-gated credentials

The core pattern powering KXCOIdentity. An institution creates a root identity (held in HSM), issues a signed post-quantum credential to a user after KYC verification, and the user signs documents and transactions with that credential. Any counterparty — bank, regulator, legal counterparty — verifies the full chain offline. No central registry. No network call.

Use cases: digital document execution · trade confirmation signing · regulated platform onboarding · credential-gated API access

import { KxcoIdentity, mlDsa } from 'kxco-pq'

// Step 1 — Institution: create root identity once, store keypair in HSM
const institution = await KxcoIdentity.create()

// Step 2 — User: generate keypair (browser, mobile app, or server-side)
const userKeypair = mlDsa.ml_dsa65.keygen()

// Step 3 — Institution: issue a signed credential post-KYC approval
const credential = await institution.issue(userKeypair.publicKey, {
  role:      'verified-user',
  authority: ['sign:transactions', 'sign:documents', 'access:platform'],
  metadata:  { sumsubApplicantId: 'ap_a3f2b8c9', country: 'GB', tier: 'institutional' },
  expiresIn: '365d',
})

// Step 4 — User: activate identity from credential + keypair
const user = KxcoIdentity.fromCredential({ keypair: userKeypair, credential })

// Step 5 — User: sign a document, trade confirmation, or regulatory submission
const envelope = await user.attest(
  { action: 'trade-confirmation', amount: 5_000_000, currency: 'USD', counterparty: 'c_vault_42' },
  { purpose: 'regulated-trade-record', jurisdiction: 'UK' },
)

// Step 6 — Anyone: verify the full trust chain offline — no server, no registry
const result = KxcoIdentity.verifyChain({
  envelope,
  credential,
  institutionPublicKey: await institution.getPublicKey(),
})
// { valid: true, role: 'verified-user', authority: [...], expiresAt: '2026-05-27T...' }

HSM key management — PKCS#11, encrypted file, and memory backends

Institutional-grade key storage across three backends. In production, institution root keys never leave the HSM boundary. The same HsmManager API works across all backends — swap without changing application code.

import { HsmManager, Pkcs11Backend, FileBackend, MemoryBackend } from 'kxco-pq'

// Production — PKCS#11 hardware (Luna, Utimaco, YubiKey, SoftHSM2)
const hsmProd = new HsmManager({
  backend: new Pkcs11Backend({
    library: '/usr/lib/softhsm/libsofthsm2.so',
    slot:    0,
    pin:     process.env.HSM_PIN,
  }),
})

// Staging — AES-256-GCM encrypted file (Argon2id passphrase)
const hsmStage = new HsmManager({
  backend: new FileBackend({
    path:       './keys/institution.enc',
    passphrase: process.env.KEY_PASSPHRASE,
  }),
})

// Generate and store a named ML-DSA-65 root keypair
const kid = await hsmProd.generateKey('institution-root', { algorithm: 'ML-DSA-65' })

// Sign payloads — key material never leaves the HSM
const signature = await hsmProd.sign(kid, documentHashBytes)
const verified  = await hsmProd.verify(kid, signature, documentHashBytes)

Audit log — tamper-evident ML-DSA-65-signed hash chain

Every entry is ML-DSA-65-signed and SHA-256-chained to the previous. Append-only — no entry can be modified, deleted, or reordered without detection. verify() replays every signature and every chain link. Required for regulatory reporting, legal discovery, and MiFID II / DORA audit trails.

import { AuditLog } from 'kxco-pq'

const log = new AuditLog({
  keypair: institutionKeypair,
  backend: 'file',
  path:    './audit/operations.ndjson',  // append-only NDJSON
})

// Record all lifecycle events — each entry is signed and chained
await log.append('credential:issued',  { userId: 'u_a3f2', role: 'verified-user', kyc: 'ap_a3f2b8c9' })
await log.append('document:signed',    { docId: 'doc_88',  purpose: 'trade-confirmation', amount: 5_000_000 })
await log.append('credential:revoked', { userId: 'u_a3f2', reason: 'account-closure', revokedBy: 'compliance' })
await log.append('key:rotated',        { oldKid: 'aa29f37a', newKid: 'b3c8d2e1', approvedBy: 'cto' })

// Full integrity verification — every signature, every chain link
const result = await log.verify()
// { valid: true, entries: 4, chainIntact: true, allSignaturesValid: true }

Attestations — signed document and payload envelopes

Create cryptographically signed, portable JSON attestation envelopes for any payload — contracts, term sheets, trade confirmations, regulatory submissions. Each envelope is self-contained and independently verifiable by any party holding the signer's public key.

import { Attester, verifyAttestation } from 'kxco-pq'

const attester = new Attester({ keypair: signingKeypair })

// Sign any structured payload
const envelope = await attester.sign({
  documentHash: 'sha256:a4c3b2d1...',
  documentType: 'loan-agreement',
  parties:      ['counterparty_A', 'counterparty_B'],
  jurisdiction: 'England and Wales',
  signedAt:     new Date().toISOString(),
}, {
  purpose:  'legal-execution',
  expireAt: '2027-06-01',
})

// Self-contained portable envelope — store, transmit, or anchor on-chain
// { payload, signature, publicKey, kid, algorithm: 'ML-DSA-65', timestamp, ... }

// Verification — standalone, no network, no registry required
const result = await verifyAttestation(envelope)
// { valid: true, signer: { kid: 'aa29f37a', algorithm: 'ML-DSA-65' }, signedAt: '...' }

Secure channels — ML-KEM-768 + X25519 hybrid key exchange

Hybrid post-quantum channel establishment: ML-KEM-768 (FIPS 203) combined with classical X25519, then AES-256-GCM for data. Wraps existing Node.js streams or Cloudflare Workers WebSockets — no protocol rewrite needed.

import { initiatorHandshake, responderHandshake, wrapStream } from 'kxco-pq'
import net from 'node:net'

// Server — accept and upgrade to PQ-encrypted channel
const server = net.createServer(async (socket) => {
  const channel = await responderHandshake(socket, { identity: serverIdentity })
  const secure  = wrapStream(channel)
  secure.on('data', (msg) => processInstruction(JSON.parse(msg)))
})

// Client — initiate PQ handshake and transmit
const socket  = net.connect(443, 'settlement.internal')
const channel = await initiatorHandshake(socket, {
  identity:        clientIdentity,
  serverPublicKey: serverIdentity.publicKey,
})
const secure = wrapStream(channel)
secure.write(JSON.stringify({ type: 'settlement-instruction', amount: 5_000_000, currency: 'USD' }))

Compatible with: Node.js TCP/TLS streams · Cloudflare Workers WebSockets · any duplex stream interface.

Vault — post-quantum file and data encryption

Encrypt files and structured data for one or multiple recipients. Each recipient receives the content key wrapped under their ML-KEM-768 public key. Defeats harvest-now-decrypt-later attacks — documents encrypted today remain secure after cryptographically-relevant quantum computers exist.

# CLI — generate a keypair and encrypt
npx kxco-vault keygen > alice.pub
kxco-vault encrypt --recipient alice.pub --out report.enc quarterly-report.pdf
kxco-vault decrypt --key alice.key report.enc

# Multi-recipient (compliance + legal + client — any one key can decrypt)
kxco-vault encrypt \
  --recipient compliance.pub \
  --recipient legal.pub \
  --recipient client.pub \
  --out agreement.enc executed-agreement.pdf

# Library
import { KxcoVault } from 'kxco-pq'

const vault     = new KxcoVault()
const keypair   = vault.generateKeypair()

const encrypted = await vault.encrypt(fileBytes, [keypair.publicKey, auditorPublicKey])
const decrypted = await vault.decrypt(encrypted, keypair.secretKey)

Webhook signing — hybrid HMAC-SHA-256 + ML-DSA-65

Hybrid signing used across all KXCO production services. HMAC-SHA-256 for fast first-pass verification; ML-DSA-65 for post-quantum non-repudiation. Both are verified before the payload is processed. One line of middleware on the receiving end.

import { createSigner, expressReceiver, fingerprint } from 'kxco-pq'

// Sender — sign outbound webhook deliveries
const signer = createSigner({
  hmacSecret:  process.env.WEBHOOK_SECRET,
  pqSecretKey: signingKeypair.secretKey,
  pqKid:       fingerprint(signingKeypair.publicKey),
})
const headers = signer.sign(JSON.stringify(payload), { event: 'kyc.approved' })
// Attach headers to your outbound request — X-KXCO-Signature, X-KXCO-PQ-Signature, X-KXCO-PQ-Kid

// Receiver — single middleware (Express)
app.use('/webhook', expressReceiver({
  hmacSecret:  process.env.WEBHOOK_SECRET,
  pinnedKids:  { [kid]: publicKey },
  required:    'both',          // reject unless both HMAC + ML-DSA-65 pass
  maxAgeMs:    5 * 60 * 1000,  // 5-minute replay window
}))

Framework adapters: Express · Fastify · Hono · Cloudflare Workers · Vercel Functions. Response signing and verifiedFetch also available.

Chain relay — meta-transactions on Armature L1

Institutions submit transactions to Armature L1 by signing ML-DSA-65 intents — KXCO validates the signature, pays gas in ARMR, and submits the EVM transaction. Institutions never hold a wallet or pay gas directly. Billed monthly by invoice. All relay methods return { txHash, blockNumber }.

import { KxcoChain } from 'kxco-pq-chain'

// identity is a KxcoIdentity from kxco-pq-sdk
const chain = new KxcoChain({
  relay:    'https://relay.kxco.ai',
  identity: institutionIdentity,
})

// Register institution on-chain (once, during onboarding)
await chain.registerInstitution({
  publicKeyHex: Buffer.from(identity.publicKey).toString('hex'),
  metadataUrl:  'https://yourplatform.com/institution.json',
})

// Issue a credential on-chain after KYC
await chain.issueCredential({
  userKid:          'aa29f37ab7f4b2cf',
  userPublicKeyHex: Buffer.from(userPublicKey).toString('hex'),
  role:             'verified-user',
  expiresAt:        1800000000,
})

// Anchor an audit log checkpoint
await chain.anchorAuditRoot({ rootHash: 'a3f1...', entryCount: 100 })

// Anchor a signed attestation envelope hash
await chain.anchorAttestation({ payloadHash: 'b7c2...', purpose: 'regulatory-report' })

// Revoke a credential
await chain.revokeCredential({ userKid: 'aa29f37ab7f4b2cf', reason: 'kyc-expired' })

// Record a key rotation
await chain.rotateKey({ newKid: 'bb39a48bc5e4d1f0', newPublicKeyHex: '...' })

Every request is a signed JSON intent. Replay protection: ±5-minute timestamp window + per-nonce deduplication. Error codes: CREDIT_EXHAUSTED · TIMEOUT · NETWORK_ERROR · RELAY_ERROR.

Machine identity — AI agents, robots, IoT, and automated processes

A KYC'd institution sponsors a machine identity — the institution signs the agent's ML-DSA-65 public key and a locked capability scope (payment limits, allowed recipients, attestation purposes). The KXCO relay validates both the credential (institution's signature) and each intent (agent's own signature) before submitting to chain.

Agent types: llm · robot · iot · process — Not open source. Contact us for licensing.

import { KxcoAgentIdentity } from 'kxco-pq-agent'

// sponsor is a KxcoIdentity from kxco-pq-sdk
const agent = await KxcoAgentIdentity.create({
  sponsor,
  label:     'Trading Bot v2',
  agentType: 'llm',
  model:     'claude-opus-4-7',
  scope: {
    payments: {
      maxPerTransaction: 5000,
      maxPerDay:         50000,
      allowedRecipients: ['0xAbC123...', 'aa29f37ab7f4b2cf'],
    },
    attestations: { purposes: ['trade-confirmation', 'settlement-receipt'] },
    auditLog:     true,
    credentials:  false,
  },
  expiresIn: '90d',
  chain,   // optional KxcoChain — records the credential on-chain
})

// Agent signs intents with its own private key
const client = agent.toChainClient('https://relay.kxco.ai')
await client.anchorAttestation({ payloadHash: '9f86...', purpose: 'trade-confirmation' })
await client.anchorAuditRoot({ rootHash: '...', entryCount: 100 })
await client.transfer({ recipientKid: 'aa29f37ab7f4b2cf', amount: 1000 })

// Verify an agent credential
const result = await KxcoAgentIdentity.verify(agent.credential, {
  sponsorPublicKey: sponsor.publicKey,
})
// { valid: true, agentKid: '...', sponsorKid: '...', scope: { ... } }

// Export / import for persistence
const exported = agent.export()
const restored = await KxcoAgentIdentity.import(exported)

// Revoke
await KxcoAgentIdentity.revoke(agent.credential.agentKid, { chain, reason: 'Decommissioned' })

60-second quickstart — verify against the live platform

Fetch a freshly-signed vector from the live KXCO platform and verify it against the production public key. The same code path every KXCO webhook receiver runs in production.

npm install kxco-post-quantum

curl -s https://chain.kxco.ai/wallet/api/verify-demo > vector.json

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 live — no cached fixtures, no replay.

Raw primitives — kxco-post-quantum

For integrations requiring only the low-level algorithms — without higher-level identity or audit patterns. Six named subpath exports, all Cure53-audited. 10.9k downloads/month.

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

// ML-DSA-65 — digital signatures (FIPS 204)
const { publicKey, secretKey } = mlDsa.keygen()
const sig = mlDsa.sign(secretKey, new TextEncoder().encode('document payload'))
const ok  = mlDsa.verify(publicKey, sig, new TextEncoder().encode('document payload'))

// ML-KEM-768 — key encapsulation (FIPS 203)
const kem = mlKem.keygen()
const { cipherText, sharedSecret: ss1 } = mlKem.encapsulate(kem.publicKey)
const ss2 = mlKem.decapsulate(cipherText, kem.secretKey)
// ss1 === ss2  (32-byte shared secret, use as AES-256-GCM key)

Pin the KXCO platform key

Production integrators should pin the KXCO platform public key at the canonical well-known URL. Reject any signature where X-KXCO-PQ-Kid doesn't match your pin — this prevents accepting a rotated or compromised key until you explicitly update.

curl -s https://kxco.ai/.well-known/kxco-pq-pubkey | jq .
# {
#   "algorithm": "ML-DSA-65",
#   "spec":      "NIST FIPS 204",
#   "kid":       "aa29f37ab7f4b2cf",
#   "publicKey": "648b1e9b...",    // 1952-byte hex — pin this value
#   ...
# }

What this SDK is not

• Not a network TLS library. For post-quantum TLS at the network edge, use OpenSSL 3.5+ or BoringSSL with X25519MLKEM768. This SDK handles application-layer cryptography.
• Not a general-purpose KMS. For full key lifecycle management, pair this SDK with AWS KMS, HashiCorp Vault, or a certified HSM. This library performs cryptographic operations on keys you load — key lifecycle policy is your responsibility.
• Not FIPS 140-3 module-certified. The algorithms implement NIST-standardised FIPS 203/204 — the module itself is not currently CMVP-validated. Contact us if CMVP certification is a hard requirement.
• Not a standalone compliance product. For a deployable compliance and identity system with white-label UI, SLA support, and pre-configured HSM key management — that is KXCOIdentity.