kxco-pq-hsm 1.0.0

package/LICENSE

@@ -0,0 +1,34 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution.
+"Licensor" shall mean KXCO by Knightsbridge.
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity.
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+"Source" form shall mean the preferred form for making modifications.
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form.
+"Work" shall mean the work of authorship made available under the License.
+"Derivative Works" shall mean any work that is based on the Work.
+"Contribution" shall mean any work of authorship submitted to the Licensor for inclusion in the Work.
+"Contributor" shall mean Licensor and any Legal Entity on behalf of whom a Contribution has been received by the Licensor and incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work; and (d) If the Work includes a "NOTICE" text file, You must include a readable copy of the attribution notices contained within such NOTICE file.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor.
+
+7. Disclaimer of Warranty. THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+
+8. Limitation of Liability. IN NO EVENT SHALL ANY CONTRIBUTOR BE LIABLE FOR ANY DAMAGES ARISING FROM THIS LICENSE OR THE USE OF THE WORK.
+
+Copyright 2026 KXCO by Knightsbridge

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "kxco-pq-hsm",
+  "version": "1.0.0",
+  "description": "HSM-backed post-quantum key management: ML-DSA-65 signing and ML-KEM-768 decapsulation through a hardware security module boundary. Three backends: in-memory (dev), Argon2id-encrypted file, and PKCS#11 (SoftHSM2, Luna, Utimaco, YubiKey).",
+  "keywords": [
+    "post-quantum",
+    "pqc",
+    "hsm",
+    "pkcs11",
+    "ml-dsa",
+    "ml-kem",
+    "nist",
+    "fips-203",
+    "fips-204",
+    "key-management",
+    "kxco"
+  ],
+  "license": "Apache-2.0",
+  "author": "KXCO by Knightsbridge <hello@kxco.ai>",
+  "homepage": "https://kxco.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JackKXCO/kxco-pq-hsm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JackKXCO/kxco-pq-hsm/issues"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^1.0.0",
+    "@noble/hashes": "^1.7.0",
+    "kxco-post-quantum": "^1.1.6"
+  },
+  "optionalDependencies": {
+    "pkcs11js": "^2.1.0"
+  },
+  "scripts": {
+    "test": "node --test --test-timeout=60000 test/hsm.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/backends/file.js

@@ -0,0 +1,92 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { argon2id } from '@noble/hashes/argon2'
+import { gcm } from '@noble/ciphers/aes'
+import { randomBytes } from '@noble/ciphers/webcrypto'
+import { KxcoPqHsmError } from '../errors.js'
+
+const VERSION = '1'
+// Argon2id params: OWASP recommended minimum for sensitive key material
+const KDF = { t: 3, m: 65536, p: 1 }
+
+const b64u = (b) => Buffer.from(b).toString('base64url')
+const unb64u = (s) => new Uint8Array(Buffer.from(s, 'base64url'))
+
+export class FileBackend {
+  #path
+  #password
+  #store
+  #derivedKey = null  // cached after first derivation
+
+  constructor({ path, password }) {
+    if (!path)     throw new KxcoPqHsmError('FileBackend: path is required')
+    if (!password) throw new KxcoPqHsmError('FileBackend: password is required')
+    this.#path     = path
+    this.#password = typeof password === 'string'
+      ? new TextEncoder().encode(password)
+      : new Uint8Array(password)
+    this.#store = this.#load()
+  }
+
+  #load() {
+    if (!existsSync(this.#path)) {
+      const store = {
+        'kxco-hsm': VERSION,
+        kdf: { alg: 'argon2id', ...KDF, salt: b64u(randomBytes(32)) },
+        keys: {},
+      }
+      writeFileSync(this.#path, JSON.stringify(store, null, 2), 'utf-8')
+      return store
+    }
+    const store = JSON.parse(readFileSync(this.#path, 'utf-8'))
+    if (store['kxco-hsm'] !== VERSION) {
+      throw new KxcoPqHsmError(`unsupported store version: ${store['kxco-hsm']}`)
+    }
+    return store
+  }
+
+  #save() {
+    writeFileSync(this.#path, JSON.stringify(this.#store, null, 2), 'utf-8')
+  }
+
+  #key() {
+    if (this.#derivedKey) return this.#derivedKey
+    const { salt, t, m, p } = this.#store.kdf
+    this.#derivedKey = argon2id(this.#password, unb64u(salt), { t, m, p, dkLen: 32 })
+    return this.#derivedKey
+  }
+
+  async store(label, alg, publicKey, secretKey) {
+    const nonce = randomBytes(12)
+    const ct    = gcm(this.#key(), nonce).encrypt(new Uint8Array(secretKey))
+    this.#store.keys[label] = {
+      alg,
+      publicKey:  b64u(publicKey),
+      nonce:      b64u(nonce),
+      ciphertext: b64u(ct),
+    }
+    this.#save()
+  }
+
+  async loadSecret(label) {
+    const entry = this.#store.keys[label]
+    if (!entry) throw new KxcoPqHsmError(`key not found: ${label}`)
+    const secretKey = gcm(this.#key(), unb64u(entry.nonce)).decrypt(unb64u(entry.ciphertext))
+    return { alg: entry.alg, secretKey }
+  }
+
+  async getPublicKey(label) {
+    const entry = this.#store.keys[label]
+    if (!entry) throw new KxcoPqHsmError(`key not found: ${label}`)
+    return { alg: entry.alg, publicKey: unb64u(entry.publicKey) }
+  }
+
+  async listKeys() {
+    return Object.entries(this.#store.keys).map(([label, { alg }]) => ({ label, alg }))
+  }
+
+  async deleteKey(label) {
+    if (!this.#store.keys[label]) throw new KxcoPqHsmError(`key not found: ${label}`)
+    delete this.#store.keys[label]
+    this.#save()
+  }
+}

package/src/backends/memory.js

@@ -0,0 +1,36 @@
+import { KxcoPqHsmError } from '../errors.js'
+
+export class MemoryBackend {
+  #keys = new Map()  // label → { alg, publicKey, secretKey }
+
+  async store(label, alg, publicKey, secretKey) {
+    this.#keys.set(label, {
+      alg,
+      publicKey: new Uint8Array(publicKey),
+      secretKey: new Uint8Array(secretKey),
+    })
+  }
+
+  async loadSecret(label) {
+    const entry = this.#keys.get(label)
+    if (!entry) throw new KxcoPqHsmError(`key not found: ${label}`)
+    return { alg: entry.alg, secretKey: new Uint8Array(entry.secretKey) }
+  }
+
+  async getPublicKey(label) {
+    const entry = this.#keys.get(label)
+    if (!entry) throw new KxcoPqHsmError(`key not found: ${label}`)
+    return { alg: entry.alg, publicKey: new Uint8Array(entry.publicKey) }
+  }
+
+  async listKeys() {
+    return [...this.#keys.entries()].map(([label, { alg }]) => ({ label, alg }))
+  }
+
+  async deleteKey(label) {
+    const entry = this.#keys.get(label)
+    if (!entry) throw new KxcoPqHsmError(`key not found: ${label}`)
+    entry.secretKey.fill(0)
+    this.#keys.delete(label)
+  }
+}

package/src/backends/pkcs11.js

@@ -0,0 +1,169 @@
+import { KxcoPqHsmError } from '../errors.js'
+
+// Lazy-load pkcs11js so the package installs cleanly without it if only using other backends
+let _pkcs11mod = null
+async function loadMod() {
+  if (_pkcs11mod) return _pkcs11mod
+  try {
+    const imported = await import('pkcs11js')
+    // Native CJS addon: ESM import() wraps it in { default: exports }; named exports are unavailable
+    _pkcs11mod = imported.default ?? imported
+    return _pkcs11mod
+  } catch {
+    throw new KxcoPqHsmError('pkcs11js is not installed — run: npm install pkcs11js')
+  }
+}
+
+const b64u   = (b) => Buffer.from(b).toString('base64url')
+const unb64u = (s) => Buffer.from(s, 'base64url')
+
+export class Pkcs11Backend {
+  #lib
+  #slotIndex
+  #pin
+  #wrapLabel
+  #p11 = null
+  #session = null
+  #wrapKey = null
+  // Wrapped key store: label → { alg, publicKey: b64u, nonce: b64u, wrapped: b64u }
+  #store = new Map()
+
+  /**
+   * @param {object} opts
+   * @param {string}  opts.libraryPath  Path to PKCS#11 shared library (.so / .dll)
+   * @param {number}  [opts.slot=0]     Index into C_GetSlotList(true) result
+   * @param {string}  opts.pin          User PIN
+   * @param {string}  [opts.wrapKeyLabel='kxco-pq-wrap']  Label for the AES-256 wrapping key
+   */
+  constructor({ libraryPath, slot = 0, pin, wrapKeyLabel = 'kxco-pq-wrap' }) {
+    if (!libraryPath) throw new KxcoPqHsmError('Pkcs11Backend: libraryPath is required')
+    if (!pin)         throw new KxcoPqHsmError('Pkcs11Backend: pin is required')
+    this.#lib       = libraryPath
+    this.#slotIndex = slot
+    this.#pin       = pin
+    this.#wrapLabel = wrapKeyLabel
+  }
+
+  /** Connect to the HSM, login, and locate or create the AES wrapping key. */
+  async open() {
+    const mod = await loadMod()
+    const { PKCS11,
+      CKF_SERIAL_SESSION, CKF_RW_SESSION, CKU_USER,
+      CKM_AES_KEY_GEN, CKO_SECRET_KEY, CKK_AES,
+      CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE_LEN, CKA_LABEL,
+      CKA_TOKEN, CKA_SENSITIVE, CKA_EXTRACTABLE,
+      CKA_ENCRYPT, CKA_DECRYPT,
+    } = mod
+
+    this.#p11 = new PKCS11()
+    this.#p11.load(this.#lib)
+    this.#p11.C_Initialize()
+
+    const slots = this.#p11.C_GetSlotList(true)
+    if (this.#slotIndex >= slots.length) {
+      throw new KxcoPqHsmError(
+        `PKCS#11 slot index ${this.#slotIndex} out of range (${slots.length} slot(s) available)`
+      )
+    }
+
+    this.#session = this.#p11.C_OpenSession(
+      slots[this.#slotIndex],
+      CKF_SERIAL_SESSION | CKF_RW_SESSION
+    )
+    this.#p11.C_Login(this.#session, CKU_USER, this.#pin)
+
+    // Find or generate the persistent AES-256 wrapping key
+    this.#p11.C_FindObjectsInit(this.#session, [
+      { type: CKA_CLASS, value: CKO_SECRET_KEY },
+      { type: CKA_LABEL, value: this.#wrapLabel },
+    ])
+    const found = this.#p11.C_FindObjects(this.#session, 1)
+    this.#p11.C_FindObjectsFinal(this.#session)
+
+    if (found.length > 0) {
+      this.#wrapKey = found[0]
+    } else {
+      this.#wrapKey = this.#p11.C_GenerateKey(
+        this.#session,
+        { mechanism: CKM_AES_KEY_GEN },
+        [
+          { type: CKA_CLASS,       value: CKO_SECRET_KEY },
+          { type: CKA_KEY_TYPE,    value: CKK_AES },
+          { type: CKA_VALUE_LEN,   value: 32 },
+          { type: CKA_LABEL,       value: this.#wrapLabel },
+          { type: CKA_TOKEN,       value: true   },   // persists across sessions
+          { type: CKA_SENSITIVE,   value: true   },
+          { type: CKA_EXTRACTABLE, value: false  },   // never leaves the HSM
+          { type: CKA_ENCRYPT,     value: true   },
+          { type: CKA_DECRYPT,     value: true   },
+        ]
+      )
+    }
+    return this
+  }
+
+  /** Logout and finalise — call when done. */
+  close() {
+    if (!this.#p11) return
+    try { this.#p11.C_Logout(this.#session)      } catch { /* best-effort */ }
+    try { this.#p11.C_CloseSession(this.#session) } catch { /* best-effort */ }
+    try { this.#p11.C_Finalize()                  } catch { /* best-effort */ }
+    this.#p11 = null
+  }
+
+  #assertOpen() {
+    if (!this.#p11) throw new KxcoPqHsmError('Pkcs11Backend is not open — call .open() first')
+  }
+
+  #cbcParams(mod, iv) {
+    return { mechanism: mod.CKM_AES_CBC_PAD, parameter: Buffer.from(iv) }
+  }
+
+  async store(label, alg, publicKey, secretKey) {
+    this.#assertOpen()
+    const mod  = await loadMod()
+    const iv   = this.#p11.C_GenerateRandom(this.#session, Buffer.alloc(16))
+    const data = Buffer.from(secretKey)
+    // pkcs11js v2: C_Encrypt(session, input, outputBuffer) — AES-CBC-PAD always adds one full padding block
+    const encOut = Buffer.alloc((Math.floor(data.length / 16) + 1) * 16)
+    this.#p11.C_EncryptInit(this.#session, this.#cbcParams(mod, iv), this.#wrapKey)
+    const wrapped = this.#p11.C_Encrypt(this.#session, data, encOut)
+
+    this.#store.set(label, {
+      alg,
+      publicKey: b64u(publicKey),
+      iv:        b64u(iv),
+      wrapped:   b64u(wrapped),
+    })
+  }
+
+  async loadSecret(label) {
+    this.#assertOpen()
+    const mod   = await loadMod()
+    const entry = this.#store.get(label)
+    if (!entry) throw new KxcoPqHsmError(`key not found: ${label}`)
+
+    const enc    = unb64u(entry.wrapped)
+    // pkcs11js v2: C_Decrypt(session, input, outputBuffer) — output ≤ input length after padding removal
+    const decOut = Buffer.alloc(enc.length)
+    this.#p11.C_DecryptInit(this.#session, this.#cbcParams(mod, unb64u(entry.iv)), this.#wrapKey)
+    const secretKey = this.#p11.C_Decrypt(this.#session, enc, decOut)
+    return { alg: entry.alg, secretKey: new Uint8Array(secretKey) }
+  }
+
+  async getPublicKey(label) {
+    this.#assertOpen()
+    const entry = this.#store.get(label)
+    if (!entry) throw new KxcoPqHsmError(`key not found: ${label}`)
+    return { alg: entry.alg, publicKey: new Uint8Array(unb64u(entry.publicKey)) }
+  }
+
+  async listKeys() {
+    return [...this.#store.entries()].map(([label, { alg }]) => ({ label, alg }))
+  }
+
+  async deleteKey(label) {
+    if (!this.#store.has(label)) throw new KxcoPqHsmError(`key not found: ${label}`)
+    this.#store.delete(label)
+  }
+}

package/src/errors.js

@@ -0,0 +1,3 @@
+export class KxcoPqHsmError extends Error {
+  constructor(message) { super(message); this.name = 'KxcoPqHsmError' }
+}

package/src/hsm.js

@@ -0,0 +1,60 @@
+import { mlDsa, mlKem } from 'kxco-post-quantum'
+import { KxcoPqHsmError } from './errors.js'
+
+export class PqHsm {
+  constructor(backend) {
+    if (!backend) throw new KxcoPqHsmError('backend is required')
+    this._backend = backend
+  }
+
+  async keygen(label, alg = 'ml-dsa-65') {
+    if (alg !== 'ml-dsa-65' && alg !== 'ml-kem-768') {
+      throw new KxcoPqHsmError(`unsupported algorithm '${alg}' — use 'ml-dsa-65' or 'ml-kem-768'`)
+    }
+    const kp = alg === 'ml-dsa-65'
+      ? mlDsa.ml_dsa65.keygen()
+      : mlKem.ml_kem768.keygen()
+
+    await this._backend.store(label, alg, kp.publicKey, kp.secretKey)
+    kp.secretKey.fill(0)
+    return { publicKey: kp.publicKey }
+  }
+
+  async sign(label, message) {
+    const { alg, secretKey } = await this._backend.loadSecret(label)
+    if (alg !== 'ml-dsa-65') {
+      throw new KxcoPqHsmError(`key '${label}' is ${alg} — sign requires ml-dsa-65`)
+    }
+    try {
+      return mlDsa.ml_dsa65.sign(secretKey, new Uint8Array(message))
+    } finally {
+      secretKey.fill(0)
+    }
+  }
+
+  async decapsulate(label, ciphertext) {
+    const { alg, secretKey } = await this._backend.loadSecret(label)
+    if (alg !== 'ml-kem-768') {
+      throw new KxcoPqHsmError(`key '${label}' is ${alg} — decapsulate requires ml-kem-768`)
+    }
+    try {
+      return new Uint8Array(
+        mlKem.ml_kem768.decapsulate(new Uint8Array(ciphertext), new Uint8Array(secretKey))
+      )
+    } finally {
+      secretKey.fill(0)
+    }
+  }
+
+  async getPublicKey(label) {
+    return (await this._backend.getPublicKey(label)).publicKey
+  }
+
+  async listKeys() {
+    return this._backend.listKeys()
+  }
+
+  async deleteKey(label) {
+    return this._backend.deleteKey(label)
+  }
+}

package/src/index.js

@@ -0,0 +1,5 @@
+export { PqHsm }          from './hsm.js'
+export { MemoryBackend }  from './backends/memory.js'
+export { FileBackend }    from './backends/file.js'
+export { Pkcs11Backend }  from './backends/pkcs11.js'
+export { KxcoPqHsmError } from './errors.js'