kxco-pq-audit 1.4.4 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.5.0
+**ML-DSA-87 logs.** A log given an ML-DSA-87 keypair signs its entries, or its
+seals, with ML-DSA-87; `log.signingAlg` reports the set. Each such record
+carries `alg: 'ML-DSA-87'` and is signed over v1.1 bytes (`kxco-audit-v1.1`,
+`kxco-audit-seal-v1.1`) whose second line is the algorithm, so it is inside the
+signed bytes. An ML-DSA-65 log writes exactly the v1 records it always has, so
+logs from this version still verify under 1.4.x and earlier.
+
+**The verifier takes the algorithm from the key.** A record whose `alg` names
+the other set from the key its `kid` selects is refused and the error says so; a
+record with no `kid` is tried only against keys of the set it states. A record
+with no `alg` is read as ML-DSA-65, and a test verifies a classic and a sealed
+log written by 1.4.5. A log that rotated from ML-DSA-65 to ML-DSA-87 verifies
+with both keys.
+
+The `kxco-post-quantum` floor is now ^1.6.0.
+
+## 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.

package/README.md

@@ -109,7 +109,7 @@ In-memory log, for tests and short-lived processes. Use `FileAuditLog` to persis
 
 | Option | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `keypair` | `{ secretKey, publicKey }` | Yes | none | ML-DSA-65 keypair from `kxco-post-quantum` |
+| `keypair` | `{ secretKey, publicKey }` | Yes | none | ML-DSA-65 or ML-DSA-87 keypair from `kxco-post-quantum`. The key decides which set signs; `log.signingAlg` reports it |
 | `chain` | `KxcoChain` | No | `null` | Chain instance for checkpoint anchoring |
 | `checkpointEvery` | `number` | No | `100` | Anchor a checkpoint every N entries |
 | `institutionKid` | `string` | No | `null` | Identifier included in checkpoint metadata |
@@ -149,7 +149,7 @@ Appending needs the previous entry's hash, not the log, so it costs the same on
 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
+2. The ML-DSA signature is valid over the canonical signing bytes, under the set the verifying key belongs to
 
 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`.
 
@@ -179,6 +179,26 @@ Recording the kid is also what makes a log answerable to the rest of the stack.
 Pair `verify()` with that lookup and a log proves both that it is intact and
 that every signing key was trusted: live revocation, from the KXCO network.
 
+#### ML-DSA-87 logs
+
+A log given an ML-DSA-87 keypair signs every entry, or every seal, with
+ML-DSA-87. Each such record carries `alg: 'ML-DSA-87'` and is signed over v1.1
+bytes: `kxco-audit-v1.1` (or `kxco-audit-seal-v1.1`) on the first line, the
+algorithm on the second, then the v1 fields unchanged, so the algorithm is
+inside the signed bytes. An ML-DSA-65 log writes exactly the v1 records it
+always has, with no `alg`, so it still verifies under 1.4.x and earlier.
+
+The verifier takes the algorithm from the key. A record whose `alg` names the
+other set from the key its `kid` selects is refused:
+
+```
+entry 0: signed as ML-DSA-65, but kid a1b2c3d4e5f60718 is an ML-DSA-87 key
+```
+
+A record with no `alg` is read as ML-DSA-65, which is how every record made
+before the field reads. A log that rotated from an ML-DSA-65 key to an ML-DSA-87
+key verifies as one artefact when both keys are passed.
+
 ### `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`.
@@ -220,7 +240,7 @@ Sealed logs only. Entries appended since the last seal, without replaying the lo
 }
 ```
 
-`prevHash` is the SHA-256 of the complete previous entry (signature included). The first entry always has `prevHash: null`. The signing message covers every field except `signature` itself.
+`prevHash` is the SHA-256 of the complete previous entry (signature included). The first entry always has `prevHash: null`. The signing message covers every field except `signature` itself. An entry signed with ML-DSA-87 also carries `"alg": "ML-DSA-87"`, which the signing message covers.
 
 ## Sealed logs
 
@@ -315,7 +335,7 @@ 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**.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-pq-audit",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "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",
@@ -71,15 +71,18 @@
   },
   "dependencies": {
     "@noble/hashes": "2.4.0",
-    "kxco-post-quantum": "^1.3.0"
+    "kxco-post-quantum": "^1.6.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 test/ml-dsa-87.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

@@ -1,7 +1,36 @@
-import { mlDsa, fingerprint } from 'kxco-post-quantum'
+import { mlDsa, mlDsa87, fingerprint } from 'kxco-post-quantum'
 import { sha256 } from '@noble/hashes/sha2.js'
 import { KxcoPqAuditError } from './errors.js'
 
+/**
+ * The ML-DSA parameter sets a log can be signed with. The KEY decides which:
+ * a key's length names its set, on the writing side and the verifying side.
+ *
+ * An ML-DSA-65 record is signed over the v1 bytes, exactly as before, and
+ * carries no `alg`, so a log written by this version still verifies under
+ * 1.4.x and earlier. An ML-DSA-87 record carries `alg: 'ML-DSA-87'` and is
+ * signed over v1.1 bytes, whose first line differs from v1 and whose second
+ * line is the algorithm, so the algorithm is inside the signed bytes. A record
+ * whose `alg` names neither set is read as v1, which means ML-DSA-65: that is
+ * how every record made before the field existed reads.
+ */
+const SETS = Object.freeze({
+  'ML-DSA-65': Object.freeze({ module: mlDsa,   publicKeyBytes: 1952, secretKeyBytes: 4032 }),
+  'ML-DSA-87': Object.freeze({ module: mlDsa87, publicKeyBytes: 2592, secretKeyBytes: 4896 }),
+})
+const DEFAULT_ALG = 'ML-DSA-65'
+
+function algForKey(key, field) {
+  for (const [name, set] of Object.entries(SETS)) if (key?.length === set[field]) return name
+  return null
+}
+
+const statedAlg = (value) => (Object.hasOwn(SETS, value) ? value : null)
+
+function versionLine(tag, alg) {
+  return alg === null ? `${tag}-v1` : `${tag}-v1.1\n${alg}`
+}
+
 const enc = new TextEncoder()
 
 function b64url(bytes)  { return Buffer.from(bytes).toString('base64url') }
@@ -11,15 +40,15 @@ function hashEntry(entry) {
   return b64url(sha256(enc.encode(JSON.stringify(entry))))
 }
 
-function signingBytes(seq, timestamp, operation, metadata, prevHash) {
+function signingBytes(seq, timestamp, operation, metadata, prevHash, alg = null) {
   return enc.encode(
-    `kxco-audit-v1\n${seq}\n${timestamp}\n${operation}\n${prevHash ?? 'null'}\n${JSON.stringify(metadata)}`
+    `${versionLine('kxco-audit', alg)}\n${seq}\n${timestamp}\n${operation}\n${prevHash ?? 'null'}\n${JSON.stringify(metadata)}`
   )
 }
 
-function sealBytes(fromSeq, toSeq, prevRoot, rootHash, timestamp) {
+function sealBytes(fromSeq, toSeq, prevRoot, rootHash, timestamp, alg = null) {
   return enc.encode(
-    `kxco-audit-seal-v1\n${fromSeq}\n${toSeq}\n${prevRoot}\n${rootHash}\n${timestamp}`
+    `${versionLine('kxco-audit-seal', alg)}\n${fromSeq}\n${toSeq}\n${prevRoot}\n${rootHash}\n${timestamp}`
   )
 }
 
@@ -58,12 +87,54 @@ function candidatesFrom(publicKey) {
   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 }
+    return { kid: kidOf(bytes), publicKey: bytes, alg: algForKey(bytes, 'publicKeyBytes') }
   })
 }
 
-function verifySignature(candidates, recordKid, msg, signatureB64, label) {
+/**
+ * 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 }
+}
+
+/**
+ * Check one record's signature. `messageFor(alg)` builds the signed bytes for
+ * the algorithm the record states (null for a v1 record).
+ *
+ * The key decides the algorithm. A record stating the other set from the key
+ * its kid names is refused rather than tried, and a record with no kid is
+ * tried only against keys of the set it states.
+ */
+function verifySignature(candidates, recordKid, recordAlg, messageFor, signatureB64, label) {
   const sigHex = () => Buffer.from(fromB64url(signatureB64)).toString('hex')
+  const stated = statedAlg(recordAlg)
+  const alg    = stated ?? DEFAULT_ALG
+  const msg    = messageFor(stated)
+  const verifyWith = (c) => {
+    if (c.alg !== alg) return false
+    try { return SETS[alg].module.verify(c.publicKey, msg, sigHex()) } catch { return false }
+  }
 
   // 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
@@ -76,16 +147,15 @@ function verifySignature(candidates, recordKid, msg, signatureB64, label) {
                `${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` }
+    if (match.alg !== null && match.alg !== alg) {
+      return { error: `${label}: signed as ${alg}, but kid ${recordKid} is an ${match.alg} key` }
+    }
+    return verifyWith(match) ? { kid: match.kid } : { error: `${label}: signature invalid` }
   }
 
-  // No kid: a log written before this version. Try each key.
+  // No kid: a log written before 1.4.0. Try each key of the stated set.
   for (const c of candidates) {
-    let ok
-    try { ok = mlDsa.verify(c.publicKey, msg, sigHex()) } catch { ok = false }
-    if (ok) return { kid: c.kid }
+    if (verifyWith(c)) return { kid: c.kid }
   }
   return { error: `${label}: signature invalid` }
 }
@@ -148,6 +218,24 @@ export class AuditLog {
     return this.#kidCache
   }
 
+  /** The set this log signs with, decided by its secret key. */
+  #signingAlg() {
+    const alg = algForKey(this.#keypair.secretKey, 'secretKeyBytes')
+    if (alg === null) throw new KxcoPqAuditError('the signing key is neither ML-DSA-65 nor ML-DSA-87')
+    return alg
+  }
+
+  /** Sign `bytesFor(stated)`; returns the base64url signature and the alg to record, if any. */
+  #sign(bytesFor) {
+    const alg    = this.#signingAlg()
+    const stated = alg === DEFAULT_ALG ? null : alg
+    const sig    = SETS[alg].module.sign(new Uint8Array(this.#keypair.secretKey), bytesFor(stated))
+    return { signature: b64url(Buffer.from(sig, 'hex')), stated }
+  }
+
+  /** The parameter set this log signs with: 'ML-DSA-65' or 'ML-DSA-87'. */
+  get signingAlg() { return this.#signingAlg() }
+
   /**
    * 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
@@ -204,11 +292,13 @@ export class AuditLog {
     // entry costs ~2ms and ~4.4KB and does not survive agent-scale volume.
     const entry = { seq, timestamp: ts, operation, metadata, prevHash: prev }
     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'))
+      const { signature, stated } = this.#sign((alg) => signingBytes(seq, ts, operation, metadata, prev, alg))
+      entry.signature = signature
       // 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()
+      // ML-DSA-87 only; inside the signed bytes. An ML-DSA-65 entry is v1.
+      if (stated) entry.alg = stated
     }
 
     await this._store(entry)
@@ -255,8 +345,7 @@ export class AuditLog {
     const fromSeq   = run[0].seq
     const toSeq     = run[run.length - 1].seq
     const timestamp = new Date().toISOString()
-    const msg       = sealBytes(fromSeq, toSeq, prevRoot, rootHash, timestamp)
-    const signature = b64url(Buffer.from(mlDsa.sign(new Uint8Array(this.#keypair.secretKey), msg), 'hex'))
+    const { signature, stated } = this.#sign((alg) => sealBytes(fromSeq, toSeq, prevRoot, rootHash, timestamp, alg))
 
     const seal = {
       fromSeq,
@@ -270,6 +359,8 @@ export class AuditLog {
       // The signing key, distinct from institutionKid, which names the
       // institution rather than the key that produced this signature.
       kid: this.#signingKid(),
+      // ML-DSA-87 only; inside the signed bytes. An ML-DSA-65 seal is v1.
+      ...(stated && { alg: stated }),
     }
     await this._storeSeal(seal)
     this.#pending = []
@@ -298,10 +389,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
@@ -324,8 +423,8 @@ export class AuditLog {
       }
 
       if (!this.#sealed) {
-        const msg = signingBytes(entry.seq, entry.timestamp, entry.operation, entry.metadata, entry.prevHash)
-        const res = verifySignature(candidates, entry.kid, msg, entry.signature, `entry ${count}`)
+        const msgFor = (alg) => signingBytes(entry.seq, entry.timestamp, entry.operation, entry.metadata, entry.prevHash, alg)
+        const res = verifySignature(candidates, entry.kid, entry.alg, msgFor, entry.signature, `entry ${count}`)
         if (res.error) return { valid: false, error: res.error }
         usedKids.add(res.kid)
       } else if (sealIndex < seals.length) {
@@ -348,11 +447,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 +487,7 @@ export class AuditLog {
       sealedThrough: expectedFrom - 1,
       unsealed: count - expectedFrom,
       kids: [...usedKids],
+      tip,
     }
   }
 
@@ -374,8 +495,8 @@ export class AuditLog {
     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)
-    const res = verifySignature(candidates, s.kid, msg, s.signature, `seal ${index}`)
+    const msgFor = (alg) => sealBytes(s.fromSeq, s.toSeq, s.prevRoot, s.rootHash, s.timestamp, alg)
+    const res = verifySignature(candidates, s.kid, s.alg, msgFor, s.signature, `seal ${index}`)
     if (res.error) return { valid: false, error: res.error }
     usedKids.add(res.kid)
     return null

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

@@ -8,10 +8,16 @@ export interface AuditEntry {
   /** SHA-256 of the previous entry (entire JSON including signature). Null for the first entry. */
   prevHash:  string | null
   /**
-   * base64url ML-DSA-65 signature over a canonical representation of all other
+   * base64url ML-DSA signature over a canonical representation of all other
    * fields. Absent on a sealed log, where the run is signed once by `seal()`.
    */
   signature?: string
+  /**
+   * The signing algorithm, inside the signed bytes. Present on entries an
+   * ML-DSA-87 key signed; absent means ML-DSA-65, which is how every entry
+   * written before this field reads.
+   */
+  alg?: 'ML-DSA-87' | 'ML-DSA-65'
   /**
    * 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,
@@ -34,8 +40,10 @@ export interface AuditSeal {
   /** base64url SHA-256 over prevRoot followed by every entry hash in the run. */
   rootHash:   string
   timestamp:  string
-  /** base64url ML-DSA-65 signature over the seal's canonical form. */
+  /** base64url ML-DSA signature over the seal's canonical form. */
   signature:  string
+  /** As on an entry: present when an ML-DSA-87 key sealed the run. */
+  alg?: 'ML-DSA-87' | 'ML-DSA-65'
   institutionKid: string | null
   /**
    * 16 hex characters identifying the key that signed this seal, present from
@@ -64,6 +72,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,14 +172,21 @@ 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. */
   readonly signingKid: string
 
+  /** The parameter set this log signs with, decided by its secret key. */
+  readonly signingAlg: 'ML-DSA-65' | 'ML-DSA-87'
+
   /**
    * Sign everything appended since the last seal, as one run. Returns the seal,
    * or null when nothing is unsealed. Throws unless the log was constructed