kxco-pq-audit 1.3.0 → 1.4.0

package/ASSESSMENT.md

@@ -0,0 +1,130 @@
+# Assessment notes
+
+The answers a buyer's readiness assessment asks for: what this package does,
+how it moves when keys and algorithms move, and what it takes to run it.
+
+Algorithm conformance belongs to
+[`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum), which
+runs 2,103 NIST ACVP vectors and a cross-implementation interoperability matrix
+and publishes the lot. Cited here, proven there.
+
+## What this package is
+
+An append-only record whose tampering is detectable and locatable. Entries are
+SHA-256 hash-chained and ML-DSA-65 signed, so **an edited or deleted entry
+fails `verify()` and the failure names the entry**. That is the guarantee, and
+it is the reason to use this rather than a table with a timestamp column.
+
+**Two modes, and the second is what makes it viable at volume.** By default
+every entry carries its own signature. In sealed mode entries are chained and
+`seal()` signs the run once. Measured over a 10,000 entry run:
+
+| | entries/s | bytes/entry | 10k run | verify |
+|---|---|---|---|---|
+| signature per entry | 129 | 4,794 | 45.7 MB | 20.1 s |
+| signature per run | 46,544 | 367 | 3.5 MB | 0.11 s |
+
+361x the append rate, a thirteenth of the bytes, verification 183x faster, and
+the tamper evidence is identical: every entry is still hash-chained, and the
+signature binding the run to the key is produced once instead of ten thousand
+times. Agent-scale volume is a solved problem here, and the numbers are in the
+README to be reproduced.
+
+**Writes are serialised, so the chain cannot fork.** Two appends in flight
+would otherwise read the same tail and mint the same `seq`. They go through a
+queue, which is the difference between a chain that is strongest under load and
+one that is weakest.
+
+**Verification streams.** Memory is bounded by one entry and the seal list
+rather than by the log: 50,000 entries verify in 729 ms without holding them.
+
+**An unsealed tail is never counted as proven.** `verify()` reports
+`sealedThrough` and `unsealed` separately, so the window between the last seal
+and the newest entry is visible rather than quietly folded into a pass.
+
+**Time is anchored where it matters.** Entry timestamps are the operator's
+clock, signed so they cannot be altered after the fact. For an independent
+bound, a checkpoint anchors the run's root on Armature L1, proving at least N
+entries existed at a given block height, which is what a regulator or a
+counterparty who does not trust the log operator can confirm on chain.
+Anchoring is fire-and-forget so chain latency never blocks an audit write.
+
+## Keys, over the life of a log
+
+A record that must outlive its signing key is the hard case, and it is handled.
+
+Entries and seals record the `kid` of the key that signed them, `verify()`
+accepts an array of keys, and each record is checked against the key its kid
+names:
+
+```js
+await log.verify([oldKey.publicKey, newKey.publicKey])
+// { valid: true, count: 3, kids: ['a1b2…', 'c3d4…'] }
+```
+
+`kids` reports which keys actually signed, in the order first seen. Supply too
+few and the failure names the one that is missing, rather than reporting a
+generic bad signature. `log.signingKid` exposes the kid a log is currently
+writing with.
+
+**Compatible in both directions, by design.** The kid is not part of the signed
+bytes. Including it would have forced a new signing-message version and every
+log written here would have stopped verifying under an older reader. As a
+selector it cannot make a forged record verify, because that still needs a key
+the verifier was given, and tampering with it produces the same refusal
+tampering with anything else already produces. So logs written by 1.4.0 verify
+under 1.3.x, logs written before 1.4.0 verify here, and passing a single key
+behaves exactly as it always did.
+
+**It also makes a log answerable to the rest of the stack.** Every kid is the
+identifier [`kxco-pq-network`](https://www.npmjs.com/package/kxco-pq-network)
+resolves against the registry as `active`, `revoked`, `rotated` or `expired`,
+and that [`kxco-pq-chain`](https://www.npmjs.com/package/kxco-pq-chain)'s
+`revokeKid()` writes on chain, where the credential carries `expiresAt`. This
+package proves which key signed; those resolve whether it should be trusted.
+That division is deliberate: verification here stays offline and dependency-free,
+and a caller who wants key status has an explicit place to ask.
+
+## Scope
+
+This package writes and verifies a file. Search belongs in a database you index
+into, because reading is line by line by design. Nothing in `src/` opens a
+socket: chain anchoring goes through a `chain` object the caller injects, so the
+network call belongs to whatever implements it, normally `kxco-pq-chain`.
+
+Single-writer per file. The in-process queue makes concurrent appends safe
+within a process, which is the deployment shape this is built for.
+
+## Agility
+
+**Inherited.** The signature primitive and its two interchangeable backends
+belong to `kxco-post-quantum`.
+
+**Versioned formats.** Signed bytes are domain-separated and prefixed,
+`kxco-audit-v1` for entries and `kxco-audit-seal-v1` for seals, so a v2 format
+can be introduced without a v1 signature becoming ambiguous. That is the
+mechanism a format migration needs, present before it is needed, and the kid
+work above is the proof it functions: a change shipped without breaking a single
+existing log in either direction.
+
+## Running it
+
+**Release integrity.** Every release carries a SLSA provenance attestation and
+a CycloneDX SBOM at a permanent unauthenticated URL, plus an evidence bundle
+from `npm run evidence` recording identity, the test run, the SBOM and the
+`kxco-post-quantum` version actually installed rather than the range declared.
+All checkable without asking us for anything.
+
+**Supported versions.** One line moving forward. Fixes land in the next release.
+
+**Cost.** No hardware ceiling. Append is O(1) whether the log holds ten entries
+or ten million: a new entry needs the previous hash and the next seq, never the
+log. The throughput table above is the sizing guide.
+
+**Runtime.** Node 20.19 and later, with Node 24 and later running the primitives
+in OpenSSL 3.5 for roughly 4x to 8x per operation.
+
+## Correcting this document
+
+Every figure here is reproducible from this repository. If one does not match,
+that is a defect worth reporting through the repository's issues.

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 1.4.0
+
+A log that outlives its signing key can now be verified as one artefact.
+
+**`verify()` accepts several public keys.** It took one, and applied it to every
+record, so a log whose key rotated part-way through could not be verified at
+all: entries before the rotation were signed by a key `verify` was no longer
+being given. Hierarchical credentials exist so that keys can change, which made
+this the gap most likely to be hit by the deployments least able to work around
+it.
+
+```js
+await log.verify([oldKey.publicKey, newKey.publicKey])
+// { valid: true, count: 3, kids: ['a1b2…', 'c3d4…'] }
+```
+
+**Entries and seals record a `kid`.** Sixteen hex characters naming the key that
+signed them, so verification selects the right key instead of forcing one across
+the whole file. `log.signingKid` exposes the same value for the key a log is
+writing with. `verify()` returns `kids`, every key that actually signed, in the
+order first seen; more than one means the log spans a rotation.
+
+**A missing key is now named.** Supplying too few keys reports which one is
+absent rather than a generic bad signature:
+
+```
+entry 0: signed by kid a1b2c3d4e5f60718, which was not among the 1 key(s) supplied
+```
+
+That message replaces `entry N: signature invalid` for this case. A wrong key
+that shares no kid with the record is still refused; only the wording changed.
+
+**Compatible in both directions, deliberately.** `kid` is not part of the signed
+bytes. Including it would have meant a new signing-message version, and every
+log written here would have stopped verifying under an older reader. So logs
+written by 1.4.0 verify under 1.3.x, and logs written before 1.4.0 carry no kid
+and are checked against each supplied key in turn. Passing a single key keeps
+working exactly as before.
+
+As a selector rather than a claim, a tampered `kid` makes verification pick the
+wrong key and fail. It cannot make a forged record verify, because that still
+needs a key the verifier was given.
+
+**It also makes a log answerable to the rest of the stack.** Before this an
+entry named no key, so there was nothing to look up. Every kid is the identifier
+`kxco-pq-network` resolves against the registry as `active`, `revoked`,
+`rotated` or `expired`, and that `kxco-pq-chain`'s `revokeKid()` writes on
+chain; the on-chain credential carries `expiresAt`.
+
+This package still does not make that call. `verify()` proves which key signed
+each entry and that the chain is intact, and will not refuse an entry signed by
+a since-revoked key because it does not ask. Pairing the two is the caller's,
+and as of this release it is possible.
+
+**ASSESSMENT.md.** Where this package's boundary falls, what cryptographic
+agility it has beyond what the primitives provide, and what constrains its
+lifecycle. It references the `kxco-post-quantum` evidence rather than restating
+it, because a second copy of a conformance claim invites the reader to count it
+twice.
+
+**An evidence bundle.** `npm run evidence` records identity, this package's own
+tests, its SBOM, registry signature verification, and the `kxco-post-quantum`
+version actually installed rather than the range declared.
+
+## 1.3.1
+
+Documentation and a dependency refresh. No source change.
+
+**ASSESSMENT.md.** Where this package's boundary falls, what cryptographic
+agility it has beyond what the primitives provide, and what constrains its
+lifecycle. It references the `kxco-post-quantum` evidence rather than restating
+it, because a second copy of a conformance claim invites the reader to count it
+twice.
+
+**`npm run evidence` now exists.** The README already told you to run it and
+there was no such script, so the command failed for anyone who followed it.
+The bundle records identity, this package's own tests, its SBOM, registry
+signature verification, and the `kxco-post-quantum` version actually installed
+rather than the range declared.
+
+**`kxco-post-quantum` refreshed to 1.7.2**, from 1.4.0 in the previous
+lockfile. Within the existing range, so no declared dependency changed. Tests
+pass unchanged.
+
 ## 1.3.0
 
 ### Added

package/README.md

@@ -134,10 +134,33 @@ Replays the entire log from entry 0. For each entry, checks:
 1. `prevHash` matches the SHA-256 of the previous entry (including its signature)
 2. The ML-DSA-65 signature is valid over the canonical signing bytes
 
-Returns `{ valid: true, count }` or `{ valid: false, error }` describing the first failure. On a sealed log it checks the chain and every seal instead, and adds `sealedThrough` and `unsealed`.
+Returns `{ valid: true, count, kids }` or `{ valid: false, error }` describing the first failure. On a sealed log it checks the chain and every seal instead, and adds `sealedThrough` and `unsealed`.
 
 It streams, so memory is bounded by one entry rather than by the log: 50,000 entries verify in 729 ms without holding them.
 
+#### Logs that outlive a key rotation
+
+A long-lived log will outlast the key it started with. Pass every key it was signed under and it verifies as one artefact:
+
+```js
+const result = await log.verify([oldKey.publicKey, newKey.publicKey])
+// { valid: true, count: 3, kids: ['a1b2…', 'c3d4…'] }
+```
+
+Each entry records the `kid` of the key that signed it, so verification selects the right key rather than trying to force one across the whole file. `kids` reports which keys actually signed, in the order first seen — more than one means the log spans a rotation.
+
+Supply too few keys and the failure names what is missing, rather than reporting a generic bad signature:
+
+```
+entry 0: signed by kid a1b2c3d4e5f60718, which was not among the 1 key(s) supplied
+```
+
+Order does not matter. Entries written before 1.4.0 carry no `kid` and are checked against each supplied key in turn, so **older logs verify unchanged** — and because `kid` is not part of the signed bytes, logs written by 1.4.0 still verify under 1.3.x.
+
+Recording the kid is also what makes a log answerable to the rest of the stack. Before 1.4.0 an entry named no key, so there was nothing to look up. Every `kid` in `kids` is the identifier [`kxco-pq-network`](https://www.npmjs.com/package/kxco-pq-network) resolves against the registry as `active`, `revoked`, `rotated` or `expired`, and that [`kxco-pq-chain`](https://www.npmjs.com/package/kxco-pq-chain)'s `revokeKid()` writes on chain.
+
+This package does not make that call. `verify()` proves which key signed each entry and that the chain is intact; it will not refuse an entry signed by a since-revoked key, because it does not ask. Putting the two together is the caller's, and it is now possible.
+
 ### `log.seal()`
 
 Sealed logs only. Signs everything appended since the last seal, as one run, and returns the seal. Returns `null` when nothing is unsealed, and throws on a log built without `sealed: true`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-pq-audit",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Tamper-evident post-quantum audit log for regulated institutions. ML-DSA-65-signed, SHA-256 hash-chained entries, so any tampering breaks the chain and shows exactly where. Checkpoint to Armature L1 for an anchor a regulator can confirm on-chain.",
   "keywords": [
     "post-quantum",
@@ -53,7 +53,8 @@
     "CHANGELOG.md",
     "LICENSE",
     "README.md",
-    "src"
+    "src",
+    "ASSESSMENT.md"
   ],
   "engines": {
     "node": ">=20.19"
@@ -63,7 +64,8 @@
     "kxco-post-quantum": "^1.3.0"
   },
   "scripts": {
-    "test": "node --test --test-timeout=30000 test/audit.test.js"
+    "test": "node --test --test-timeout=30000 test/audit.test.js",
+    "evidence": "node scripts/build-evidence.mjs"
   },
   "funding": "https://kxco.ai",
   "publishConfig": {

package/src/audit-log.js

@@ -1,4 +1,4 @@
-import { mlDsa } from 'kxco-post-quantum'
+import { mlDsa, fingerprint } from 'kxco-post-quantum'
 import { sha256 } from '@noble/hashes/sha2.js'
 import { KxcoPqAuditError } from './errors.js'
 
@@ -26,6 +26,70 @@ function sealBytes(fromSeq, toSeq, prevRoot, rootHash, timestamp) {
 /** The first seal has no predecessor; this stands in for one so the seals chain too. */
 const GENESIS_ROOT = '0'.repeat(64)
 
+/**
+ * Which key signed a record.
+ *
+ * `kid` is deliberately NOT part of the signed bytes. Including it would mean a
+ * new signing-message version, and every log written by this package would stop
+ * verifying under an older reader. Left out, it is a selector rather than a
+ * claim: tampering with it makes verification select the wrong key and fail,
+ * which is the same outcome tampering with anything else already produces. It
+ * cannot make a forged record verify, because that still needs a key the
+ * verifier was given.
+ *
+ * The consequence worth stating: a log written by this version verifies
+ * unchanged under 1.3.x, and a log written by 1.3.x verifies here.
+ */
+function kidOf(publicKey) {
+  return fingerprint(new Uint8Array(publicKey))
+}
+
+/**
+ * Normalise whatever verify() was handed into a candidate list.
+ *
+ * One key keeps the original call shape working. An array is what a log that
+ * outlived a key rotation needs, because no single key signed all of it.
+ */
+function candidatesFrom(publicKey) {
+  const list = Array.isArray(publicKey) ? publicKey : [publicKey]
+  if (list.length === 0) {
+    throw new KxcoPqAuditError('verify: at least one public key is required')
+  }
+  return list.map((pk) => {
+    if (!pk) throw new KxcoPqAuditError('verify: a public key was null or undefined')
+    const bytes = new Uint8Array(pk)
+    return { kid: kidOf(bytes), publicKey: bytes }
+  })
+}
+
+function verifySignature(candidates, recordKid, msg, signatureB64, label) {
+  const sigHex = () => Buffer.from(fromB64url(signatureB64)).toString('hex')
+
+  // A record that names its key is checked against that key and no other.
+  // Falling back to the rest would let a swapped kid pass under a different
+  // key, which is not a forgery but is a confusing thing to report as valid.
+  if (recordKid) {
+    const match = candidates.find((c) => c.kid === recordKid)
+    if (!match) {
+      return {
+        error: `${label}: signed by kid ${recordKid}, which was not among the ` +
+               `${candidates.length} key(s) supplied`,
+      }
+    }
+    let ok
+    try { ok = mlDsa.verify(match.publicKey, msg, sigHex()) } catch { ok = false }
+    return ok ? { kid: match.kid } : { error: `${label}: signature invalid` }
+  }
+
+  // No kid: a log written before this version. Try each key.
+  for (const c of candidates) {
+    let ok
+    try { ok = mlDsa.verify(c.publicKey, msg, sigHex()) } catch { ok = false }
+    if (ok) return { kid: c.kid }
+  }
+  return { error: `${label}: signature invalid` }
+}
+
 /**
  * A run's root: the previous seal's root followed by every entry hash in seq
  * order. Chaining the roots means removing a whole seal breaks the next one,
@@ -46,6 +110,7 @@ export class AuditLog {
   #keypair
   #entries = []
   #sealsList = []
+  #kidCache  = null
   #chain
   #checkpointEvery
   #institutionKid
@@ -77,6 +142,19 @@ export class AuditLog {
   /** True when this log signs once per sealed run rather than once per entry. */
   get sealed() { return this.#sealed }
 
+  /** The kid of the key this log signs with. Derived once; it cannot change. */
+  #signingKid() {
+    this.#kidCache ??= kidOf(this.#keypair.publicKey)
+    return this.#kidCache
+  }
+
+  /**
+   * The kid a verifier needs for the records this log is writing. Publishing it
+   * alongside the log means a reader does not have to derive it from a key they
+   * may not have yet.
+   */
+  get signingKid() { return this.#signingKid() }
+
   /**
    * One pass over whatever is already stored, to find the tail and, on a sealed
    * log, the entries the next seal will cover. Everything after this is O(1).
@@ -128,6 +206,9 @@ export class AuditLog {
     if (!this.#sealed) {
       const msg = signingBytes(seq, ts, operation, metadata, prev)
       entry.signature = b64url(Buffer.from(mlDsa.sign(new Uint8Array(this.#keypair.secretKey), msg), 'hex'))
+      // Which key signed this entry, so a log that outlives a rotation can say
+      // so per entry rather than forcing one key across the whole file.
+      entry.kid = this.#signingKid()
     }
 
     await this._store(entry)
@@ -186,6 +267,9 @@ export class AuditLog {
       timestamp,
       signature,
       institutionKid: this.#institutionKid,
+      // The signing key, distinct from institutionKid, which names the
+      // institution rather than the key that produced this signature.
+      kid: this.#signingKid(),
     }
     await this._storeSeal(seal)
     this.#pending = []
@@ -216,6 +300,9 @@ export class AuditLog {
    * the seal list rather than by the log.
    */
   async verify(publicKey) {
+    const candidates = candidatesFrom(publicKey)
+    const usedKids   = new Set()
+
     const seals = this.#sealed ? await this._seals() : []
     let sealIndex    = 0
     let expectedFrom = 0
@@ -238,10 +325,9 @@ export class AuditLog {
 
       if (!this.#sealed) {
         const msg = signingBytes(entry.seq, entry.timestamp, entry.operation, entry.metadata, entry.prevHash)
-        let ok
-        try { ok = mlDsa.verify(new Uint8Array(publicKey), msg, Buffer.from(fromB64url(entry.signature)).toString('hex')) }
-        catch { ok = false }
-        if (!ok) return { valid: false, error: `entry ${count}: signature invalid` }
+        const res = verifySignature(candidates, entry.kid, msg, entry.signature, `entry ${count}`)
+        if (res.error) return { valid: false, error: res.error }
+        usedKids.add(res.kid)
       } else if (sealIndex < seals.length) {
         const s = seals[sealIndex]
         if (s.fromSeq !== expectedFrom) {
@@ -252,7 +338,7 @@ export class AuditLog {
         }
         if (entry.seq >= s.fromSeq) runHashes.push(hashEntry(entry))
         if (entry.seq === s.toSeq) {
-          const bad = this.#closeSeal(s, sealIndex, prevRoot, runHashes, publicKey)
+          const bad = this.#closeSeal(s, sealIndex, prevRoot, runHashes, candidates, usedKids)
           if (bad) return bad
           prevRoot     = s.rootHash
           expectedFrom = s.toSeq + 1
@@ -266,7 +352,7 @@ export class AuditLog {
       count++
     }
 
-    if (!this.#sealed) return { valid: true, count }
+    if (!this.#sealed) return { valid: true, count, kids: [...usedKids] }
 
     if (sealIndex < seals.length) {
       const s = seals[sealIndex]
@@ -280,18 +366,18 @@ export class AuditLog {
       count,
       sealedThrough: expectedFrom - 1,
       unsealed: count - expectedFrom,
+      kids: [...usedKids],
     }
   }
 
-  #closeSeal(s, index, prevRoot, runHashes, publicKey) {
+  #closeSeal(s, index, prevRoot, runHashes, candidates, usedKids) {
     if (rootOf(prevRoot, runHashes) !== s.rootHash) {
       return { valid: false, error: `seal ${index}: entries do not reproduce rootHash` }
     }
     const msg = sealBytes(s.fromSeq, s.toSeq, s.prevRoot, s.rootHash, s.timestamp)
-    let ok
-    try { ok = mlDsa.verify(new Uint8Array(publicKey), msg, Buffer.from(fromB64url(s.signature)).toString('hex')) }
-    catch { ok = false }
-    if (!ok) return { valid: false, error: `seal ${index}: signature invalid` }
+    const res = verifySignature(candidates, s.kid, msg, s.signature, `seal ${index}`)
+    if (res.error) return { valid: false, error: res.error }
+    usedKids.add(res.kid)
     return null
   }
 

package/src/index.d.ts

@@ -12,6 +12,16 @@ export interface AuditEntry {
    * fields. Absent on a sealed log, where the run is signed once by `seal()`.
    */
   signature?: string
+  /**
+   * 16 hex characters identifying the key that signed this entry, present from
+   * 1.4.0. Absent on entries written by earlier versions and on sealed logs,
+   * where the seal carries it instead.
+   *
+   * Not part of the signed bytes: it selects a key rather than asserting one.
+   * Tampering with it makes verification pick the wrong key and fail; it cannot
+   * make a forged entry verify.
+   */
+  kid?: string
 }
 
 /** One signed run of a sealed log. Seals chain to each other by `prevRoot`. */
@@ -27,6 +37,12 @@ export interface AuditSeal {
   /** base64url ML-DSA-65 signature over the seal's canonical form. */
   signature:  string
   institutionKid: string | null
+  /**
+   * 16 hex characters identifying the key that signed this seal, present from
+   * 1.4.0. Distinct from `institutionKid`, which names the institution rather
+   * than the signing key.
+   */
+  kid?: string
 }
 
 export interface AuditVerifySuccess {
@@ -43,6 +59,11 @@ export interface AuditVerifySuccess {
    * either — seal() closes the window.
    */
   unsealed?: number
+  /**
+   * Every signing key that actually produced a signature in this log, in the
+   * order first seen. More than one means the log spans a key rotation.
+   */
+  kids: string[]
 }
 
 export interface AuditVerifyFailure {
@@ -107,7 +128,23 @@ export declare class AuditLog {
    * Verify the full hash chain, plus every entry's signature on a classic log
    * or every seal on a sealed one.
    */
-  verify(publicKey: Uint8Array | Buffer): Promise<AuditVerifyResult>
+  /**
+   * Replay the log and check every signature.
+   *
+   * Pass one key for a log signed by one key. Pass several for a log that
+   * outlived a key rotation: each record is checked against the key its `kid`
+   * names, and records written before 1.4.0 carry no kid and are checked
+   * against each key in turn.
+   *
+   * A record naming a key that was not supplied is a failure that says so,
+   * rather than a generic invalid signature.
+   */
+  verify(
+    publicKey: Uint8Array | Buffer | Array<Uint8Array | Buffer>,
+  ): Promise<AuditVerifyResult>
+
+  /** The kid of the key this log signs with. */
+  readonly signingKid: string
 
   /**
    * Sign everything appended since the last seal, as one run. Returns the seal,