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.