kxco-pq-audit 1.4.3 → 1.4.5

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.4.5
+
+`verify(publicKey, { checkpoint })` takes the `{ count, tip }` an earlier verify
+returned, and fails a log that has since lost or replaced its last entry.
+Verify results carry `tip`.
+
+A file line that is JSON but not an entry, and a torn or edited `.seals` line,
+are refused with KxcoPqAuditError naming the line. The README Security section
+says when each kind of removal is caught.
+
+## 1.4.4
+
+Documentation. No source change.
+
+A NOTICE file names the copyright owner, Knightsbridge Financial Ltd, trading
+as KXCO, and ships in the package, so anyone who redistributes it carries the
+attribution, as section 4(d) of the Apache License requires.
+
 ## 1.4.3
 
 Documentation. No source change.

package/NOTICE

@@ -0,0 +1,6 @@
+kxco-pq-audit
+Copyright 2026 Knightsbridge Financial Ltd, trading as KXCO.
+Registered in England and Wales, company number 15684975.
+
+Licensed under the Apache License, Version 2.0. See LICENSE.
+https://kxco.ai

package/README.md

@@ -315,13 +315,13 @@ Evidenced, and reproducible on your own machine:
 
 Dependency audit history is recorded in [AUDIT.md](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/blob/main/AUDIT.md).
 
-The hash chain means a compromised or deleted entry cannot be hidden: any gap breaks verification of every subsequent entry.
+The hash chain means a compromised or deleted entry cannot be hidden. Removing any entry before the last breaks the chain at the entry after it, and `verify()` names that entry. Removing the last entry is caught by verifying against a checkpoint: pass the `{ count, tip }` an earlier `verify()` returned, as `log.verify(publicKey, { checkpoint })`, and a log that has since lost or replaced its last entry fails. On a sealed log, the seal that covers the last entry catches its removal as well.
 
 To report a vulnerability, open a [private security advisory](https://github.com/KnightsbridgeAIQ/kxco-pq-audit/security/advisories/new) or email **security@kxco.ai**.
 
 ## License
 
-Apache-2.0 © 2026 KXCO by Knightsbridge
+Apache-2.0 © 2026 Knightsbridge Financial Ltd, trading as KXCO. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
 
 ## Maintainers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-pq-audit",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "description": "Tamper-evident post-quantum audit trail for regulated institutions. ML-DSA-65 signed, SHA-256 hash-chained entries: any edit, gap or reorder fails verification and names the entry. 46,544 entries a second sealed, with checkpoints anchored on Armature L1.",
   "keywords": [
     "post-quantum",
@@ -61,6 +61,7 @@
   "files": [
     "CHANGELOG.md",
     "LICENSE",
+    "NOTICE",
     "README.md",
     "src",
     "ASSESSMENT.md"
@@ -73,12 +74,15 @@
     "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 test/property.test.js",
     "evidence": "node scripts/build-evidence.mjs"
   },
   "funding": "https://kxco.ai",
   "publishConfig": {
     "provenance": true,
     "access": "public"
+  },
+  "devDependencies": {
+    "fast-check": "4.10.2"
   }
 }

package/src/audit-log.js

@@ -62,6 +62,33 @@ function candidatesFrom(publicKey) {
   })
 }
 
+/**
+ * Normalise a checkpoint: what a verifier kept from an earlier look at the log.
+ *
+ * `count` is how many entries the log held and `tip` the hash of the last of
+ * them, so any earlier verify() result is a checkpoint as it stands. Either may
+ * be given alone. Checked strictly, because a checkpoint that names nothing
+ * would check nothing and read as a pass.
+ */
+function checkpointFrom(checkpoint) {
+  if (checkpoint === undefined) return null
+  const count = checkpoint?.count
+  const tip   = checkpoint?.tip ?? undefined
+  if (count !== undefined && !(Number.isSafeInteger(count) && count >= 0)) {
+    throw new KxcoPqAuditError('verify: checkpoint.count must be a whole number of entries')
+  }
+  if (tip !== undefined && typeof tip !== 'string') {
+    throw new KxcoPqAuditError('verify: checkpoint.tip must be the hash string an earlier verify() returned')
+  }
+  if (count === undefined && tip === undefined) {
+    throw new KxcoPqAuditError('verify: a checkpoint needs a count, a tip or both')
+  }
+  if (count === 0 && tip !== undefined) {
+    throw new KxcoPqAuditError('verify: a checkpoint with a tip covers at least one entry')
+  }
+  return { count, tip }
+}
+
 function verifySignature(candidates, recordKid, msg, signatureB64, label) {
   const sigHex = () => Buffer.from(fromB64url(signatureB64)).toString('hex')
 
@@ -298,10 +325,18 @@ export class AuditLog {
   /**
    * Replay the log from entry 0. Streams, so memory is bounded by one entry and
    * the seal list rather than by the log.
+   *
+   * The chain catches an entry removed from before the last, because the entry
+   * after it stops linking. Nothing follows the last entry, so its removal is
+   * caught against a checkpoint: the `{ count, tip }` an earlier verify()
+   * returned. The log may have grown since, but the entry the checkpoint was
+   * taken at must still be there, unchanged.
    */
-  async verify(publicKey) {
+  async verify(publicKey, { checkpoint } = {}) {
     const candidates = candidatesFrom(publicKey)
+    const pin        = checkpointFrom(checkpoint)
     const usedKids   = new Set()
+    let tipSeen      = false
 
     const seals = this.#sealed ? await this._seals() : []
     let sealIndex    = 0
@@ -348,11 +383,32 @@ export class AuditLog {
       }
 
       prevHash = hashEntry(entry)
+      if (pin?.tip !== undefined) {
+        if (pin.count === undefined) {
+          tipSeen ||= prevHash === pin.tip
+        } else if (count === pin.count - 1) {
+          if (prevHash !== pin.tip) {
+            return { valid: false, error: `checkpoint: entry ${count} does not match the checkpoint tip` }
+          }
+          tipSeen = true
+        }
+      }
       expectedSeq = entry.seq + 1
       count++
     }
 
-    if (!this.#sealed) return { valid: true, count, kids: [...usedKids] }
+    if (pin?.count !== undefined && count < pin.count) {
+      return { valid: false, error: `checkpoint: covers seq ${pin.count - 1}, log ends at ${count - 1}` }
+    }
+    if (pin?.tip !== undefined && !tipSeen) {
+      return { valid: false, error: 'checkpoint: no entry matches the checkpoint tip' }
+    }
+
+    // The hash of the last entry, which the next one will chain to. With
+    // `count`, it is the checkpoint a later verify() can be held to.
+    const tip = prevHash
+
+    if (!this.#sealed) return { valid: true, count, kids: [...usedKids], tip }
 
     if (sealIndex < seals.length) {
       const s = seals[sealIndex]
@@ -367,6 +423,7 @@ export class AuditLog {
       sealedThrough: expectedFrom - 1,
       unsealed: count - expectedFrom,
       kids: [...usedKids],
+      tip,
     }
   }
 

package/src/backends/file.js

@@ -4,6 +4,9 @@ import { createInterface } from 'node:readline'
 import { AuditLog } from '../audit-log.js'
 import { KxcoPqAuditError } from '../errors.js'
 
+/** An entry or a seal is a JSON object: not null, not an array, not a scalar. */
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
 /**
  * Append-only NDJSON backend.
  *
@@ -58,8 +61,9 @@ export class FileAuditLog extends AuditLog {
       for await (const line of lines) {
         lineNo++
         if (!line) continue
+        let entry
         try {
-          yield JSON.parse(line)
+          entry = JSON.parse(line)
         } catch {
           // A line that will not parse is either a torn write from a crash or
           // an edit. Either way it is not something to skip past in silence.
@@ -69,6 +73,14 @@ export class FileAuditLog extends AuditLog {
             'anywhere else means the file was edited.'
           )
         }
+        // JSON that is not an object cannot be an entry, and a torn write never
+        // produces one, since every entry line starts with `{`.
+        if (!isRecord(entry)) {
+          throw new KxcoPqAuditError(
+            `${this.#path}: line ${lineNo} is JSON but not an audit entry, which means the file was edited.`
+          )
+        }
+        yield entry
       }
     } finally {
       lines.close()
@@ -108,7 +120,31 @@ export class FileAuditLog extends AuditLog {
   async _seals() {
     let text
     try { text = await readFile(this.#sealPath, 'utf8') } catch { return [] }
-    return text.trim().split('\n').filter(Boolean).map(line => JSON.parse(line))
+    // Read line by line, so a torn or edited seal is named the same way a bad
+    // entry line is. A line may end in \r if the file was edited with CRLF.
+    const seals = []
+    const lines = text.split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].endsWith('\r') ? lines[i].slice(0, -1) : lines[i]
+      if (!line) continue
+      let seal
+      try {
+        seal = JSON.parse(line)
+      } catch {
+        throw new KxcoPqAuditError(
+          `${this.#sealPath}: line ${i + 1} is not valid JSON. ` +
+          'A partial last line is an interrupted seal and can be truncated; ' +
+          'anywhere else means the file was edited.'
+        )
+      }
+      if (!isRecord(seal)) {
+        throw new KxcoPqAuditError(
+          `${this.#sealPath}: line ${i + 1} is JSON but not a seal, which means the file was edited.`
+        )
+      }
+      seals.push(seal)
+    }
+    return seals
   }
 
   async _storeSeal(seal) {

package/src/index.d.ts

@@ -64,6 +64,32 @@ export interface AuditVerifySuccess {
    * order first seen. More than one means the log spans a key rotation.
    */
   kids: string[]
+  /**
+   * base64url SHA-256 of the last entry, the hash the next entry will chain
+   * to, or null for an empty log. With `count`, it is a checkpoint: keep this
+   * result and pass it to a later `verify()` as `{ checkpoint }`.
+   */
+  tip: string | null
+}
+
+/**
+ * What a verifier kept from an earlier look at the log. Any earlier
+ * `AuditVerifySuccess` is one. Either field may be given alone.
+ */
+export interface AuditCheckpoint {
+  /** The log must still hold at least this many entries. */
+  count?: number
+  /** The entry at `count - 1`, or with no count some entry, must hash to this. */
+  tip?: string | null
+}
+
+export interface AuditVerifyOptions {
+  /**
+   * Fail unless the log still holds, unchanged, the entry this checkpoint was
+   * taken at. The log may have grown since. This is what catches the last
+   * entry being removed or replaced, which leaves no later entry to break.
+   */
+  checkpoint?: AuditCheckpoint
 }
 
 export interface AuditVerifyFailure {
@@ -138,9 +164,13 @@ export declare class AuditLog {
    *
    * A record naming a key that was not supplied is a failure that says so,
    * rather than a generic invalid signature.
+   *
+   * Pass `{ checkpoint }`, the `{ count, tip }` of an earlier result, to also
+   * catch the last entry being removed or replaced since then.
    */
   verify(
     publicKey: Uint8Array | Buffer | Array<Uint8Array | Buffer>,
+    options?: AuditVerifyOptions,
   ): Promise<AuditVerifyResult>
 
   /** The kid of the key this log signs with. */