kxco-pq-audit 1.0.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "kxco-pq-audit",
+  "version": "1.0.0",
+  "description": "Tamper-evident post-quantum audit log: ML-DSA-65-signed, hash-chained operation entries. Prove cryptographic operations happened, in order, and were not altered. Memory and append-only file backends.",
+  "keywords": [
+    "post-quantum",
+    "pqc",
+    "audit-log",
+    "ml-dsa",
+    "nist",
+    "fips-204",
+    "tamper-evident",
+    "compliance",
+    "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-audit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JackKXCO/kxco-pq-audit/issues"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.7.0",
+    "kxco-post-quantum": "^1.1.6"
+  },
+  "scripts": {
+    "test": "node --test --test-timeout=30000 test/audit.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/audit-log.js

@@ -0,0 +1,72 @@
+import { mlDsa } from 'kxco-post-quantum'
+import { sha256 } from '@noble/hashes/sha2'
+import { KxcoPqAuditError } from './errors.js'
+
+const enc = new TextEncoder()
+
+function b64url(bytes)  { return Buffer.from(bytes).toString('base64url') }
+function fromB64url(s)  { return new Uint8Array(Buffer.from(s, 'base64url')) }
+
+function hashEntry(entry) {
+  return b64url(sha256(enc.encode(JSON.stringify(entry))))
+}
+
+function signingBytes(seq, timestamp, operation, metadata, prevHash) {
+  return enc.encode(
+    `kxco-audit-v1\n${seq}\n${timestamp}\n${operation}\n${prevHash ?? 'null'}\n${JSON.stringify(metadata)}`
+  )
+}
+
+export class AuditLog {
+  #keypair
+  #entries = []
+
+  constructor({ keypair }) {
+    if (!keypair?.secretKey || !keypair?.publicKey) {
+      throw new KxcoPqAuditError('keypair with secretKey and publicKey is required')
+    }
+    this.#keypair = keypair
+  }
+
+  async append(operation, metadata = {}) {
+    if (typeof operation !== 'string' || !operation) {
+      throw new KxcoPqAuditError('operation must be a non-empty string')
+    }
+    const all  = await this._entries()
+    const seq  = all.length
+    const ts   = new Date().toISOString()
+    const prev = seq === 0 ? null : hashEntry(all[seq - 1])
+    const msg  = signingBytes(seq, ts, operation, metadata, prev)
+    const sig  = mlDsa.ml_dsa65.sign(new Uint8Array(this.#keypair.secretKey), msg)
+
+    const entry = { seq, timestamp: ts, operation, metadata, prevHash: prev, signature: b64url(sig) }
+    await this._store(entry)
+    return entry
+  }
+
+  async verify(publicKey) {
+    const all = await this._entries()
+    for (let i = 0; i < all.length; i++) {
+      const e = all[i]
+      if (i === 0) {
+        if (e.prevHash !== null) return { valid: false, error: 'entry 0: prevHash must be null' }
+      } else {
+        const expected = hashEntry(all[i - 1])
+        if (e.prevHash !== expected) return { valid: false, error: `entry ${i}: prevHash mismatch` }
+      }
+      const msg = signingBytes(e.seq, e.timestamp, e.operation, e.metadata, e.prevHash)
+      let ok
+      try { ok = mlDsa.ml_dsa65.verify(new Uint8Array(publicKey), msg, fromB64url(e.signature)) }
+      catch { ok = false }
+      if (!ok) return { valid: false, error: `entry ${i}: signature invalid` }
+    }
+    return { valid: true, count: all.length }
+  }
+
+  async export() {
+    return this._entries()
+  }
+
+  async _entries() { return [...this.#entries] }
+  async _store(entry) { this.#entries.push(entry) }
+}

package/src/backends/file.js

@@ -0,0 +1,23 @@
+import { readFile, appendFile } from 'node:fs/promises'
+import { AuditLog } from '../audit-log.js'
+import { KxcoPqAuditError } from '../errors.js'
+
+export class FileAuditLog extends AuditLog {
+  #path
+
+  constructor({ keypair, path }) {
+    super({ keypair })
+    if (!path) throw new KxcoPqAuditError('FileAuditLog: path is required')
+    this.#path = path
+  }
+
+  async _entries() {
+    let text
+    try { text = await readFile(this.#path, 'utf8') } catch { return [] }
+    return text.trim().split('\n').filter(Boolean).map(line => JSON.parse(line))
+  }
+
+  async _store(entry) {
+    await appendFile(this.#path, JSON.stringify(entry) + '\n', 'utf8')
+  }
+}

package/src/errors.js

@@ -0,0 +1,6 @@
+export class KxcoPqAuditError extends Error {
+  constructor(msg) {
+    super(msg)
+    this.name = 'KxcoPqAuditError'
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { AuditLog } from './audit-log.js'
+export { FileAuditLog } from './backends/file.js'
+export { KxcoPqAuditError } from './errors.js'