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.

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.

What this does NOT do

• No relay client — use kxco-pq-chain directly for chain communication
• No agent identity — this package is for institutions and their issued users
• No encrypted channels — attestation envelopes are signed, not encrypted

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

Cryptography: ML-DSA-65 (NIST FIPS 204) via @noble/post-quantum, independently audited by Cure53 in 2024. No custom cryptography.

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

Authors

Shayne Heffernan and John Heffernan — kxco.ai

License

Apache-2.0 © 2026 KXCO by Knightsbridge