kxco-pq-sdk

Institution identity layer for the KXCO stack — ML-DSA-65 hierarchical credentials, HSM-backed signing, and optional on-chain anchoring via Armature L1.

Release integrity

Every release of this package is checkable without asking us for anything.

• Provenance. Each release carries a SLSA provenance attestation tying the published tarball to the commit and workflow that built it. Verify with npm audit signatures, or read it directly from registry.npmjs.org/-/npm/v1/attestations/kxco-pq-sdk@<version>.
• Bill of materials. A CycloneDX SBOM is published as a GitHub Release asset at releases/download/v<version>/sbom.cyclonedx.json, a permanent unauthenticated URL. Not an expiring build artifact.
• Pinned where it matters. Third-party dependencies are pinned to exact versions, never ranges, so the code that performs the cryptography cannot change without a release. Sibling kxco-* packages sit on caret ranges deliberately: it means a correctness fix in the base package reaches you without a release of every package above it. That is not theoretical. When @noble/post-quantum 0.7.1 was found to fail NIST SLH-DSA verification vectors, the revert in the base package propagated here on the next install. Every GitHub Action is pinned by 40-character commit SHA.
• Conformance underneath. The cryptography comes from kxco-post-quantum, which is run against 2,103 NIST ACVP vectors: 1,793 passed, 0 failed, 310 skipped and a 225-check cross-implementation interoperability matrix against liboqs, Bouncy Castle and two pure-Python implementations, in both directions and with negative controls. Its published tarball also rebuilds bit-for-bit from its own tag, verified in CI on every run.

When to use this

This package is for institutions participating in the KXCO network. Use it when you need to:

• Issue post-quantum credentials to KYC-verified users
• Sign attestations (documents, trades, regulatory submissions) as an institution or user
• Verify the full credential chain offline — no network call required
• Store institution keys in a hardware security module (PKCS#11, encrypted file, or memory)

If you are building an agent, relay, or encrypted channel, this is not the right package.

Install

npm install kxco-pq-sdk

Quick start

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

// Institution: generate identity once, store keypair securely
const institution = await KxcoIdentity.create()

// User: generate keypair (e.g. in a browser or mobile app)
const userKeypair = mlDsa.ml_dsa65.keygen()

// Institution: issue a credential after KYC approval
const credential = await institution.issue(userKeypair.publicKey, {
  role:      'verified-user',
  authority: ['sign:transactions'],
  expiresIn: '365d',
})

// User: reconstruct a signing identity from keypair + credential
const userIdentity = KxcoIdentity.fromCredential({ keypair: userKeypair, credential })

// User: sign a document or transaction
const envelope = await userIdentity.attest(
  { action: 'transfer', amount: 1000, currency: 'GBP' },
  { purpose: 'trade-confirmation' },
)

// Verifier: check the full chain offline
const result = KxcoIdentity.verifyChain({
  envelope,
  credential,
  institutionPublicKey: await institution.getPublicKey(),
})
// result.valid, result.role, result.authority, result.issuedBy

API

KxcoIdentity.create(opts?)

Creates an institution (root) identity. Generates a new ML-DSA-65 keypair unless keypair or hsm is supplied.

| Option | Type | Description | |---|---|---| | keypair | { publicKey, secretKey } | Existing keypair — generated if omitted | | hsm | PqHsm \| AuditedHsm | HSM instance for production key storage | | label | string | Required when hsm is provided | | auditLog | AuditLog | Logs identity:created | | chain | KxcoChain | Registers institution on Armature L1 | | metadataUrl | string | Passed to chain registration |

institution.issue(userPublicKey, opts)

Issues a signed credential to a user. Institution identities only.

| Option | Type | Description | |---|---|---| | role | string | Required. e.g. 'verified-user', 'compliance-officer' | | authority | string[] | Default []. e.g. ['sign:transactions'] | | metadata | object | Arbitrary key/value — e.g. Sumsub applicant ID | | expiresIn | string | '365d', '24h', '30m', '60s' | | auditLog | AuditLog | Logs credential:issued | | chain | KxcoChain | Anchors credential on Armature L1 |

Returns a plain JSON object. Serialise and deliver to the user over HTTP.

institution.revoke(userKid, opts?)

Revokes a user credential. Institution identities only. Does nothing locally — side effects are the audit log entry and the on-chain revocation.

| Option | Type | Description | |---|---|---| | reason | string | Optional revocation reason | | auditLog | AuditLog | Logs credential:revoked | | chain | KxcoChain | Anchors revocation on Armature L1 |

KxcoIdentity.fromCredential({ keypair, credential })

Reconstructs a user's signing identity from their keypair and a received credential. Returns a KxcoIdentity with role, authority, parentKid, and metadata populated.

identity.attest(data, opts?)

Signs arbitrary data and returns a self-contained envelope. data can be a string, Buffer, Uint8Array, or any JSON-serialisable object.

| Option | Type | Description | |---|---|---| | purpose | string | e.g. 'regulatory-report', 'trade-confirmation' | | aud | string | Intended audience | | exp | string | ISO 8601 expiry | | context | object | Additional fields merged into the envelope |

identity.sign(message)

Raw ML-DSA-65 signing. Returns a Uint8Array signature. Prefer attest() for structured envelopes.

identity.verify(envelope)

Verifies that this identity signed the envelope. Returns { valid, payload, iss, role, authority, iat, ... }.

KxcoIdentity.verifyChain({ envelope, credential, institutionPublicKey })

Verifies the full chain offline: institution signed the credential, user signed the envelope, iss matches userKid, nothing expired.

const result = KxcoIdentity.verifyChain({
  envelope,
  credential,
  institutionPublicKey,  // Uint8Array — fetch from institution's well-known URL
})
// result.valid, result.role, result.authority, result.metadata, result.issuedBy

Identity properties

| Property | Institution | User | |---|---|---| | kid | 16-hex fingerprint | 16-hex fingerprint | | role | null | e.g. 'verified-user' | | authority | null | string[] | | parentKid | null | institution kid | | credential | null | signed credential object | | metadata | {} | {} |

HSM backends

Import from kxco-pq-sdk. All implement the PqHsm interface.

| Backend | Use case | |---|---| | MemoryBackend | Testing only — keys are not persisted | | FileBackend | Encrypted JSON file — suitable for server environments without hardware HSM | | Pkcs11Backend | Hardware HSM via PKCS#11 — production institution keys | | AuditedHsm | Wraps any backend and writes every keygen/sign/delete to an AuditLog |

import { KxcoIdentity, AuditedHsm, PqHsm, FileBackend, AuditLog, mlDsa } from 'kxco-pq-sdk'

const logKeypair = mlDsa.ml_dsa65.keygen()
const log        = new AuditLog({ keypair: logKeypair })
const hsm        = new PqHsm(new FileBackend({ path: './institution.json', password: process.env.HSM_PASSWORD }))
const auditedHsm = new AuditedHsm(hsm, log)

const institution = await KxcoIdentity.create({ hsm: auditedHsm, label: 'institution-key' })

Chain integration

Pass a KxcoChain instance from kxco-pq-chain to create, issue, or revoke to anchor operations on Armature L1. The chain parameter is optional on all three methods — omit it to run fully offline. When provided, create calls chain.registerInstitution, issue calls chain.issueCredential, and revoke calls chain.revokeCredential. Credential chain verification via verifyChain is always offline and requires no chain connection.

Where this fits

Institutions and the users they issue credentials to. That is the whole scope, and the rest of the stack covers what sits either side.

• kxco-pq-chain for relay and chain communication
• kxco-pq-attest for signed envelopes over arbitrary payloads
• kxco-pq-vault when the payload must be encrypted rather than signed

Part of the KXCO stack

| Package | Role | |---|---| | kxco-post-quantum | ML-DSA-65, ML-KEM primitives | | kxco-pq-attest | Standalone attestation without identity | | kxco-pq-audit | Tamper-evident audit log | | kxco-pq-hsm | HSM backends | | kxco-pq-sdk | This package — institution identity layer | | kxco-pq-chain | Armature L1 chain client |

Security

ML-DSA-65 (NIST FIPS 204) and ML-KEM-768 (NIST FIPS 203) via kxco-post-quantum, running on the OpenSSL 3.5 primitives where the runtime provides them. No custom cryptography.

Evidenced, and reproducible on your own machine:

• 2,103 NIST ACVP vectors across FIPS 203, 204 and 205, pinned by digest: 1,793 passed, 0 failed, 310 skipped, where each skip is the library refusing a pre-hash weaker than the parameter set
• 225 interoperability checks passed, 0 failed, 42 not applicable against OpenSSL 3.5, liboqs, Bouncy Castle and dilithium-py/kyber-py, in both directions
• SLSA provenance on every published release — verify with npm audit signatures
• CycloneDX SBOM published with each release
• npm run evidence regenerates the whole bundle from source

Dependency audit history is recorded in AUDIT.md.

To report a vulnerability: [email protected] — do not open a public issue.

Authors

Shayne Heffernan and John Heffernan — kxco.ai

Supported runtimes

Node.js 20.19+ (current LTS and later). ESM-only. New features and bug fixes land on the latest major version; security fixes are backported one major version.

License

Apache-2.0 © 2026 KXCO by Knightsbridge