kxco-pq-audit 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+## 1.3.0
+
+### Added
+
+`sealed: true` signs once per run instead of once per entry.
+
+Every entry is still hash-chained, which is what detects an edit, a removal, a
+reorder or an insertion. The per-entry signature only bound one entry to the
+key, and it was the entire cost of the log. Measured here on ML-DSA-65 over
+10,000 entries:
+
+| | entries/s | bytes/entry | verify |
+|---|---|---|---|
+| per entry | 129 | 4,794 | 20.1 s |
+| per run | 46,544 | 367 | 0.11 s |
+
+Of those 4,794 bytes, 4,412 were the signature. Any workload with real entry
+volume, agent tool calls being the case this was built for, cannot afford one
+signature per entry.
+
+`seal()` returns the run it signed, or null when nothing is unsealed. `seals()`
+returns them all. Seals chain to each other by `prevRoot`, so removing an entire
+seal breaks the one after it, the same way removing an entry breaks the next
+entry's `prevHash`. `FileAuditLog` writes them to `<path>.seals`.
+
+`verify()` on a sealed log reports `sealedThrough` and `unsealed`. Entries
+appended since the last seal are chained and unsigned, and that window is
+reported rather than counted as proven.
+
+Two things it costs: a single entry can no longer be verified on its own, only
+as part of its run, and the unsealed window is real until `seal()` runs.
+
+Default is unchanged. A log built without the option behaves exactly as before,
+signature per entry included.
+
+`stream()` yields entries one at a time, and `unsealedCount()` reports the
+window without replaying the log.
+
+### Fixed
+
+**Concurrent appends forked the chain.** Every `append()` read the log to find
+the next seq, so two in flight together both read the same tail and both claimed
+it. Fifty parallel appends produced fifty entries all numbered `seq 0`, and the
+resulting log fails its own `verify()`. Writes are now serialised internally, so
+the same fifty produce seq 0 to 49 and verify clean. Any log written
+concurrently under 1.2.3 or earlier should be checked with `verify()`.
+
+**Appending was quadratic.** `append()` loaded every entry to work out the next
+seq and prevHash, and `FileAuditLog` re-read and re-parsed the whole file each
+time. A log now loads once and keeps only the tail, so cost per entry no longer
+depends on length.
+
+| entries | before | after |
+|---|---|---|
+| 500 | 1,635 us/entry | 66 us/entry |
+| 2,000 | 2,279 us/entry | 66 us/entry |
+| 4,000 | 3,262 us/entry | 66 us/entry |
+| 50,000 | not measured, still climbing | 66 us/entry |
+
+`FileAuditLog` also holds one write handle rather than reopening the file per
+entry, which is ~46us a write against ~421us. It is released after 2 seconds
+idle, so forgetting `close()` costs nothing, and `close()` is there for a
+deterministic hand-back.
+
+**`verify()` loaded the whole log to check it.** It now streams, so memory is
+bounded by one entry and the seal list. 50,000 entries verify in 729 ms.
+
+### Added, smaller
+
+`FileAuditLog` refuses to append to a file that changed size underneath it,
+rather than forking the chain and failing much later at `verify()`. One file has
+one writer; `assertSoleWriter()` checks it on demand and runs on every seal and
+close.
+
+A line that will not parse is now named with its line number and told apart from
+a torn final line, instead of surfacing as a bare `SyntaxError`.
+
+## 1.2.3
+
+### Corrected
+
+The README claimed `@noble/post-quantum` was audited by Cure53 in 2024.
+It is maintainer-audited (v0.6.1, April 2026), not Cure53-audited.
+
+The other Noble packages were audited separately and at different dates, and
+none of those engagements reached the post-quantum package:
+
+| Package | Audited by |
+|---|---|
+| `@noble/post-quantum` | maintainer-audited |
+| `@noble/hashes` | Cure53, Jan 2022, v1.0.0 |
+| `@noble/curves` | Trail of Bits Feb 2023; Kudelski Sep 2023; Cure53 Sep 2024 |
+| `@noble/ciphers` | Cure53, Sep 2024, v1.0.0 |
+
+Dates from `kxco-post-quantum/audit/dependency-review.json`, which is generated
+by `audit/run-audit.mjs` rather than written by hand.
+
+Documentation only. No code changed and no behaviour changed.
+
+`.socket.yml` said `@noble/hashes` was audited by Cure53 in 2024. The audit
+was real but the date was wrong: January 2022, at v1.0.0.

package/README.md

@@ -28,7 +28,7 @@ Every release of this package is checkable without asking us for anything.
   Every GitHub Action is pinned by 40-character commit SHA.
 - **Conformance underneath.** The cryptography comes from
   [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum), which
-  is run against **2,103 NIST ACVP vectors (0 failed)** and a **225-check
+  is run against **2,103 NIST ACVP vectors: 1,793 passed, 0 failed, 310 skipped** and a **225-check
   cross-implementation interoperability matrix** against liboqs, Bouncy Castle
   and two pure-Python implementations, in both directions and with negative
   controls. Its published tarball also rebuilds bit-for-bit from its own tag,
@@ -78,7 +78,7 @@ await log.append('key.rotate',  { keyId: 'signing-key-v2', alg: 'ml-dsa-65' })
 const result = await log.verify(keypair.publicKey)
 // { valid: true, count: 3 }
 
-const entries = await log.entries()
+const entries = await log.export()
 // array of signed entry objects
 ```
 
@@ -96,6 +96,7 @@ In-memory log. Entries are lost when the process exits.
 | `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 |
+| `sealed` | `boolean` | No | `false` | Sign once per run instead of once per entry. See [Sealed logs](#sealed-logs) |
 
 ### `new FileAuditLog(options)`
 
@@ -104,6 +105,15 @@ Append-only NDJSON file backend. Survives process restarts. Accepts all the same
 | Option | Type | Required | Description |
 |---|---|---|---|
 | `path` | `string` | Yes | Path to the `.ndjson` file (created if absent) |
+| `idleReleaseMs` | `number` | No | Release the write handle after this long without a write (default `2000`) |
+
+Entries are read as a stream and never all at once, and writes go through one handle held open while the log is busy. Both mean cost per entry does not grow with the file.
+
+**One file has one writer.** A signed chain cannot have two: both would build on the same tail and the second entry would take the first one's place. Every seal and every `close()` checks the file is the size this instance left it, and throws if it is not.
+
+### `log.close()`
+
+`FileAuditLog` only. Releases the write handle. Not required, since the handle is released after `idleReleaseMs` without a write, but call it when you want the descriptor back at a known point. Throws if another writer has touched the file.
 
 ### `log.append(operation, metadata)`
 
@@ -115,6 +125,8 @@ Appends a signed, hash-chained entry.
 
 If chain anchoring is configured and the entry count is a multiple of `checkpointEvery`, a fire-and-forget checkpoint is sent to the relay. The `append` call resolves immediately — it does not wait for the chain.
 
+Appending needs the previous entry's hash, not the log, so it costs the same on ten entries and on ten million. Concurrent calls are serialised internally: two appends in flight together cannot take the same `seq`.
+
 ### `log.verify(publicKey)`
 
 Replays the entire log from entry 0. For each entry, checks:
@@ -122,11 +134,37 @@ 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.
+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`.
+
+It streams, so memory is bounded by one entry rather than by the log: 50,000 entries verify in 729 ms without holding them.
+
+### `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`.
+
+If chain anchoring is configured, the run's root is anchored fire-and-forget. A sealed log anchors when it seals rather than every `checkpointEvery` entries.
+
+### `log.seals()`
+
+Sealed logs only. Returns every seal, oldest first.
+
+### `log.export()`
 
-### `log.entries()`
+Returns all entries as an array, in seq order. Holds the whole log in memory by definition; prefer `stream()` on a large one.
 
-Returns all entries as an array. Equivalent to `log.export()`.
+### `log.stream()`
+
+Yields entries one at a time, in seq order. Memory stays bounded by a single entry however long the log is.
+
+```js
+for await (const entry of log.stream()) {
+  if (entry.operation === 'tool_call') console.log(entry.seq, entry.metadata.tool)
+}
+```
+
+### `log.unsealedCount()`
+
+Sealed logs only. Entries appended since the last seal, without replaying the log. Always `0` on a classic log.
 
 ## Entry format
 
@@ -143,6 +181,45 @@ Returns all entries as an array. Equivalent to `log.export()`.
 
 `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.
 
+## Sealed logs
+
+By default every entry carries its own ML-DSA-65 signature. That signature is also the entire cost of the log. Measured here over 10,000 entries:
+
+| | 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 |
+
+Of those 4,794 bytes, 4,412 are the signature. Anything with real entry volume cannot afford one per entry.
+
+`sealed: true` keeps the hash chain on every entry and moves the signature to the run:
+
+```js
+const log = new AuditLog({ keypair, sealed: true })
+
+for (const call of agentToolCalls) {
+  await log.append('tool_call', call)   // chained, not signed
+}
+
+const seal = await log.seal()           // one signature for the whole run
+// { fromSeq: 0, toSeq: 9999, entryCount: 10000, prevRoot, rootHash, timestamp, signature }
+```
+
+The chain is what detects tampering, and it is untouched. An entry edited, removed, reordered or inserted after sealing fails to reproduce the run's `rootHash`. Seals chain to one another by `prevRoot`, so removing a whole seal breaks the seal that follows it.
+
+`verify()` on a sealed log reports where the signed record stops:
+
+```js
+await log.verify(publicKey)
+// { valid: true, count: 10002, sealedThrough: 9999, unsealed: 2 }
+```
+
+Entries appended since the last seal are chained and unsigned. `unsealed` is that window, reported rather than counted as proven. Call `seal()` to close it.
+
+What sealing costs you: a single entry can no longer be verified on its own, only as part of its run.
+
+`FileAuditLog` writes seals to `<path>.seals`, so a reader that knows only about entries is unaffected.
+
 ## Chain anchoring
 
 When a `chain` is passed and `checkpointEvery` is set, every Nth entry triggers a call to `chain.anchorAuditRoot({ rootHash, entryCount })` via the KXCO relay.
@@ -151,12 +228,18 @@ The anchor is fire-and-forget: `append` does not await it, so chain latency neve
 
 The checkpoint provides an on-chain timestamp proving that at least N entries existed at a specific block height. This supplements the local NDJSON file for long-term tamper evidence, particularly where the log operator and the verifier are separate parties.
 
-## What this does NOT do
+## Where this fits
+
+An append-only, ML-DSA-65-signed, hash-chained record. **Entries cannot be
+edited or deleted without `verify()` failing and naming the entry** — that is
+the guarantee, and the reason to use it.
 
-- **Not a database.** Entries cannot be queried by field, filtered, or indexed. Read the file line by line.
-- **Not queryable.** There is no search API. If you need search, index entries into a database alongside the NDJSON file.
-- **Append-only.** Entries cannot be edited or deleted without breaking `verify()`. This is intentional.
-- **Not a transport.** This package writes and verifies. It does not expose HTTP endpoints or stream entries to external systems.
+It writes and verifies a file. Reading is line by line, so index entries into
+your own database if you need search, and checkpoint to Armature L1 when a
+regulator needs an anchor they can confirm on-chain.
+
+- [`kxco-pq-chain`](https://www.npmjs.com/package/kxco-pq-chain) for the checkpoint anchor
+- [`kxco-pq-attest`](https://www.npmjs.com/package/kxco-pq-attest) for signed envelopes that travel on their own
 
 ## Part of the KXCO stack
 
@@ -172,7 +255,19 @@ The checkpoint provides an on-chain timestamp proving that at least N entries ex
 
 ## Security
 
-Entry signing uses [Noble post-quantum](https://github.com/paulmillr/noble-post-quantum) ML-DSA-65 (NIST FIPS 204) and [Noble hashes](https://github.com/paulmillr/noble-hashes) SHA-256 — independently audited by Cure53 (2024). The hash chain means a compromised or deleted entry cannot be hidden: any gap breaks verification of every subsequent entry.
+**ML-DSA-65** (NIST FIPS 204) via [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum), running on the OpenSSL 3.5 primitives where the runtime provides them. No custom cryptography.
+
+Evidenced, and reproducible on your own machine:
+
+- **2,103 NIST ACVP vectors** across FIPS 203, 204 and 205, pinned by digest: 1,793 passed, 0 failed, 310 skipped, where each skip is the library refusing a pre-hash weaker than the parameter set
+- **225 interoperability checks passed, 0 failed, 42 not applicable** against OpenSSL 3.5, liboqs, Bouncy Castle and dilithium-py/kyber-py, in both directions
+- **SLSA provenance** on every published release — verify with `npm audit signatures`
+- **CycloneDX SBOM** published with each release
+- `npm run evidence` regenerates the whole bundle from source
+
+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.
 
 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,7 +1,7 @@
 {
   "name": "kxco-pq-audit",
-  "version": "1.2.2",
-  "description": "Tamper-evident post-quantum audit log for regulated institutions. ML-DSA-65-signed, SHA-256 hash-chained entries. Any tampering breaks the chain. Optional Armature L1 checkpoint anchoring via the KXCO relay.",
+  "version": "1.3.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",
     "pqc",
@@ -50,14 +50,16 @@
     }
   },
   "files": [
-    "src",
-    "LICENSE"
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "src"
   ],
   "engines": {
     "node": ">=20.19"
   },
   "dependencies": {
-    "@noble/hashes": "2.3.0",
+    "@noble/hashes": "2.4.0",
     "kxco-post-quantum": "^1.3.0"
   },
   "scripts": {

package/src/audit-log.js

@@ -17,14 +17,53 @@ function signingBytes(seq, timestamp, operation, metadata, prevHash) {
   )
 }
 
+function sealBytes(fromSeq, toSeq, prevRoot, rootHash, timestamp) {
+  return enc.encode(
+    `kxco-audit-seal-v1\n${fromSeq}\n${toSeq}\n${prevRoot}\n${rootHash}\n${timestamp}`
+  )
+}
+
+/** The first seal has no predecessor; this stands in for one so the seals chain too. */
+const GENESIS_ROOT = '0'.repeat(64)
+
+/**
+ * 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,
+ * the same way removing an entry breaks the next entry's prevHash.
+ */
+function rootOf(prevRoot, entryHashes) {
+  return b64url(sha256(enc.encode(prevRoot + entryHashes.join(''))))
+}
+
+/**
+ * Tamper-evident append-only log.
+ *
+ * Appending costs the same whether the log holds ten entries or ten million:
+ * a new entry needs the previous entry's hash and the next seq, never the log.
+ * Verification streams, so it is bounded by one entry rather than by the log.
+ */
 export class AuditLog {
   #keypair
   #entries = []
+  #sealsList = []
   #chain
   #checkpointEvery
   #institutionKid
+  #sealed
 
-  constructor({ keypair, chain, checkpointEvery = 100, institutionKid } = {}) {
+  /** { seq, hash } of the last entry, or null for an empty log. Loaded once. */
+  #tail = null
+  /** Sealed logs only: entries since the last seal, which is what seal() signs. */
+  #pending = []
+  #ready = null
+  /**
+   * Writes run one at a time. Two appends in flight together would both read
+   * the same tail and mint the same seq, which forks the chain at the point it
+   * is supposed to be strongest.
+   */
+  #queue = Promise.resolve()
+
+  constructor({ keypair, chain, checkpointEvery = 100, institutionKid, sealed = false } = {}) {
     if (!keypair?.secretKey || !keypair?.publicKey) {
       throw new KxcoPqAuditError('keypair with secretKey and publicKey is required')
     }
@@ -32,24 +71,72 @@ export class AuditLog {
     this.#chain           = chain           ?? null
     this.#checkpointEvery = checkpointEvery
     this.#institutionKid  = institutionKid  ?? null
+    this.#sealed          = Boolean(sealed)
+  }
+
+  /** True when this log signs once per sealed run rather than once per entry. */
+  get sealed() { return this.#sealed }
+
+  /**
+   * 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).
+   */
+  #load() {
+    if (this.#ready) return this.#ready
+    this.#ready = (async () => {
+      const seals = await this._seals()
+      const sealedThrough = seals.length === 0 ? -1 : seals[seals.length - 1].toSeq
+      let last = null
+      const pending = []
+      for await (const entry of this._iterate()) {
+        last = entry
+        if (this.#sealed && entry.seq > sealedThrough) pending.push(entry)
+      }
+      this.#tail    = last === null ? null : { seq: last.seq, hash: hashEntry(last) }
+      this.#pending = pending
+    })()
+    return this.#ready
+  }
+
+  /** Run a write with no other write in flight. A failure must not poison the queue. */
+  #serial(fn) {
+    const run = this.#queue.then(fn, fn)
+    this.#queue = run.then(() => {}, () => {})
+    return run
   }
 
   async append(operation, metadata = {}) {
+    // Validate before queueing, so a bad call fails now rather than behind
+    // however much work is already in flight.
     if (typeof operation !== 'string' || !operation) {
       throw new KxcoPqAuditError('operation must be a non-empty string')
     }
-    const all  = await this._entries()
-    const seq  = all.length
+    return this.#serial(() => this.#appendOne(operation, metadata))
+  }
+
+  async #appendOne(operation, metadata) {
+    await this.#load()
+
+    const seq  = this.#tail === null ? 0 : this.#tail.seq + 1
+    const prev = this.#tail === null ? null : this.#tail.hash
     const ts   = new Date().toISOString()
-    const prev = seq === 0 ? null : hashEntry(all[seq - 1])
-    const msg  = signingBytes(seq, ts, operation, metadata, prev)
-    const sig  = Buffer.from(mlDsa.sign(new Uint8Array(this.#keypair.secretKey), msg), 'hex')
 
-    const entry = { seq, timestamp: ts, operation, metadata, prevHash: prev, signature: b64url(sig) }
+    // A sealed log chains every entry and signs none of them. The signature that
+    // binds the run to the key is produced once, by seal(), because signing every
+    // 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'))
+    }
+
     await this._store(entry)
+    this.#tail = { seq, hash: hashEntry(entry) }
+    if (this.#sealed) this.#pending.push(entry)
 
+    // A sealed log anchors when it seals, not every N entries.
     const entryCount = seq + 1
-    if (this.#chain && entryCount % this.#checkpointEvery === 0) {
+    if (!this.#sealed && this.#chain && entryCount % this.#checkpointEvery === 0) {
       const rootHash = Buffer.from(sha256(enc.encode(JSON.stringify(entry)))).toString('hex')
       this.#chain.anchorAuditRoot({ rootHash, entryCount }).catch((err) => {
         console.warn(`[kxco-pq-audit] chain checkpoint failed (entry ${entryCount}): ${err.message}`)
@@ -59,29 +146,183 @@ export class AuditLog {
     return entry
   }
 
+  /**
+   * Sign every entry written since the last seal, as one run.
+   *
+   * Returns the seal, or null when there is nothing unsealed. Safe to call
+   * repeatedly. Entries appended after a seal are chained but carry no
+   * signature until the next one, which is the honest cost of not signing
+   * inline: verify() always reports how many are in that window.
+   */
+  async seal() {
+    if (!this.#sealed) throw new KxcoPqAuditError('seal() requires sealed: true')
+    // Sealing shares the write queue with append, so a run can never be sealed
+    // half way through an entry being written into it.
+    return this.#serial(() => this.#sealPending())
+  }
+
+  async #sealPending() {
+    await this.#load()
+    if (this.#pending.length === 0) return null
+
+    const seals = await this._seals()
+    const last  = seals.length === 0 ? null : seals[seals.length - 1]
+    const run   = this.#pending
+
+    const prevRoot  = last === null ? GENESIS_ROOT : last.rootHash
+    const rootHash  = rootOf(prevRoot, run.map(hashEntry))
+    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 seal = {
+      fromSeq,
+      toSeq,
+      entryCount: run.length,
+      prevRoot,
+      rootHash,
+      timestamp,
+      signature,
+      institutionKid: this.#institutionKid,
+    }
+    await this._storeSeal(seal)
+    this.#pending = []
+
+    if (this.#chain) {
+      this.#chain.anchorAuditRoot({ rootHash, entryCount: toSeq + 1 }).catch((err) => {
+        console.warn(`[kxco-pq-audit] chain checkpoint failed (seal ${fromSeq}-${toSeq}): ${err.message}`)
+      })
+    }
+
+    return seal
+  }
+
+  /** Every seal this log holds, oldest first. */
+  async seals() {
+    return this._seals()
+  }
+
+  /** Entries appended since the last seal. Sealed logs only. */
+  async unsealedCount() {
+    if (!this.#sealed) return 0
+    await this.#load()
+    return this.#pending.length
+  }
+
+  /**
+   * Replay the log from entry 0. Streams, so memory is bounded by one entry and
+   * the seal list rather than by the log.
+   */
   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 seals = this.#sealed ? await this._seals() : []
+    let sealIndex    = 0
+    let expectedFrom = 0
+    let prevRoot     = GENESIS_ROOT
+    let runHashes    = []
+
+    let count    = 0
+    let prevHash = null
+    let expectedSeq = 0
+
+    for await (const entry of this._iterate()) {
+      if (entry.seq !== expectedSeq) {
+        return { valid: false, error: `entry ${count}: expected seq ${expectedSeq}, got ${entry.seq}` }
+      }
+      if (entry.prevHash !== prevHash) {
+        return count === 0
+          ? { valid: false, error: 'entry 0: prevHash must be null' }
+          : { valid: false, error: `entry ${count}: prevHash mismatch` }
       }
-      const msg = signingBytes(e.seq, e.timestamp, e.operation, e.metadata, e.prevHash)
-      let ok
-      try { ok = mlDsa.verify(new Uint8Array(publicKey), msg, Buffer.from(fromB64url(e.signature)).toString('hex')) }
-      catch { ok = false }
-      if (!ok) return { valid: false, error: `entry ${i}: signature invalid` }
+
+      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` }
+      } else if (sealIndex < seals.length) {
+        const s = seals[sealIndex]
+        if (s.fromSeq !== expectedFrom) {
+          return { valid: false, error: `seal ${sealIndex}: expected fromSeq ${expectedFrom}, got ${s.fromSeq}` }
+        }
+        if (s.prevRoot !== prevRoot) {
+          return { valid: false, error: `seal ${sealIndex}: prevRoot does not chain to the seal before it` }
+        }
+        if (entry.seq >= s.fromSeq) runHashes.push(hashEntry(entry))
+        if (entry.seq === s.toSeq) {
+          const bad = this.#closeSeal(s, sealIndex, prevRoot, runHashes, publicKey)
+          if (bad) return bad
+          prevRoot     = s.rootHash
+          expectedFrom = s.toSeq + 1
+          runHashes    = []
+          sealIndex++
+        }
+      }
+
+      prevHash = hashEntry(entry)
+      expectedSeq = entry.seq + 1
+      count++
+    }
+
+    if (!this.#sealed) return { valid: true, count }
+
+    if (sealIndex < seals.length) {
+      const s = seals[sealIndex]
+      return { valid: false, error: `seal ${sealIndex}: covers seq ${s.toSeq}, log ends at ${count - 1}` }
+    }
+
+    // Never let an unsealed tail read as proven. sealedThrough is where the
+    // signed record stops; unsealed entries are chained and nothing more.
+    return {
+      valid: true,
+      count,
+      sealedThrough: expectedFrom - 1,
+      unsealed: count - expectedFrom,
     }
-    return { valid: true, count: all.length }
   }
 
+  #closeSeal(s, index, prevRoot, runHashes, publicKey) {
+    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` }
+    return null
+  }
+
+  /**
+   * Every entry as an array. Holds the whole log in memory by definition; on a
+   * large log prefer `stream()`.
+   */
   async export() {
-    return this._entries()
+    const out = []
+    for await (const entry of this._iterate()) out.push(entry)
+    return out
+  }
+
+  /** Every entry, in seq order, one at a time. */
+  stream() {
+    return this._iterate()
   }
 
+  // --- storage hooks; a backend overrides these ---
+
   async _entries() { return [...this.#entries] }
   async _store(entry) { this.#entries.push(entry) }
+  async _seals() { return [...this.#sealsList] }
+  async _storeSeal(seal) { this.#sealsList.push(seal) }
+
+  /**
+   * Entries in seq order. The default reads them all through `_entries()`, so a
+   * backend that only overrides `_entries()` still works; one that can stream
+   * should override this instead.
+   */
+  async *_iterate() {
+    for (const entry of await this._entries()) yield entry
+  }
 }

package/src/backends/file.js

@@ -1,23 +1,157 @@
-import { readFile, appendFile } from 'node:fs/promises'
+import { createReadStream } from 'node:fs'
+import { readFile, appendFile, open, stat } from 'node:fs/promises'
+import { createInterface } from 'node:readline'
 import { AuditLog } from '../audit-log.js'
 import { KxcoPqAuditError } from '../errors.js'
 
+/**
+ * Append-only NDJSON backend.
+ *
+ * Entries are read as a stream, never all at once, so appending and verifying
+ * both stay flat as the file grows. Seals go to `<path>.seals`, so a reader
+ * that only knows about entries is unaffected by a sealed log.
+ *
+ * Writes go through one handle held open for the life of the instance, which
+ * costs ~46us an entry against ~421us for reopening the file every time. Call
+ * `close()` when done with the log; the data is already with the OS either way,
+ * so a missed close leaks a descriptor and nothing else.
+ *
+ * One file has one writer. A signed chain cannot have two: both would build on
+ * the same tail, and the second entry would take the first one's place. The
+ * size the file should be is recorded on open and checked whenever the log
+ * seals or closes, so a second writer surfaces as an error rather than as a
+ * chain that only fails much later at verify().
+ */
 export class FileAuditLog extends AuditLog {
   #path
+  #sealPath
+  #handle = null
+  #size = null
+  #idleTimer = null
+  #idleMs
 
-  constructor({ keypair, path, chain, checkpointEvery, institutionKid }) {
-    super({ keypair, chain, checkpointEvery, institutionKid })
+  constructor({ keypair, path, chain, checkpointEvery, institutionKid, sealed, idleReleaseMs = 2000 }) {
+    super({ keypair, chain, checkpointEvery, institutionKid, sealed })
     if (!path) throw new KxcoPqAuditError('FileAuditLog: path is required')
-    this.#path = path
+    this.#path     = path
+    this.#sealPath = path + '.seals'
+    this.#idleMs   = idleReleaseMs
+  }
+
+  async *_iterate() {
+    let stream
+    try {
+      stream = createReadStream(this.#path, { encoding: 'utf8' })
+      await new Promise((resolve, reject) => {
+        stream.once('readable', resolve)
+        stream.once('end', resolve)
+        stream.once('error', reject)
+      })
+    } catch (err) {
+      if (err.code === 'ENOENT') return
+      throw err
+    }
+
+    const lines = createInterface({ input: stream, crlfDelay: Infinity })
+    let lineNo = 0
+    try {
+      for await (const line of lines) {
+        lineNo++
+        if (!line) continue
+        try {
+          yield 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.
+          throw new KxcoPqAuditError(
+            `${this.#path}: line ${lineNo} is not valid JSON. ` +
+            'A partial last line is an interrupted append and can be truncated; ' +
+            'anywhere else means the file was edited.'
+          )
+        }
+      }
+    } finally {
+      lines.close()
+      stream.destroy()
+    }
   }
 
   async _entries() {
+    const out = []
+    for await (const entry of this._iterate()) out.push(entry)
+    return out
+  }
+
+  async _store(entry) {
+    const line = JSON.stringify(entry) + '\n'
+    const handle = await this.#open()
+    await handle.write(line, null, 'utf8')
+    this.#size += Buffer.byteLength(line, 'utf8')
+    this.#idleRelease()
+  }
+
+  /**
+   * Let go of the handle once writing stops.
+   *
+   * A busy log never goes idle and keeps the fast path. A short-lived one hands
+   * the descriptor back on its own, so forgetting `close()` costs nothing
+   * instead of failing when the handle is finally collected. The timer is
+   * unref'd, so it never holds the process open, and it holds a reference to
+   * this log, so the handle cannot be collected while a release is pending.
+   */
+  #idleRelease() {
+    clearTimeout(this.#idleTimer)
+    this.#idleTimer = setTimeout(() => { this.close().catch(() => {}) }, this.#idleMs)
+    this.#idleTimer.unref?.()
+  }
+
+  async _seals() {
     let text
-    try { text = await readFile(this.#path, 'utf8') } catch { return [] }
+    try { text = await readFile(this.#sealPath, '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')
+  async _storeSeal(seal) {
+    await this.assertSoleWriter()
+    await appendFile(this.#sealPath, JSON.stringify(seal) + '\n', 'utf8')
+  }
+
+  /**
+   * Throw if the entry file is not the size this instance left it. Runs on open
+   * and on every seal; call it directly to check at any other point.
+   */
+  async assertSoleWriter() {
+    if (this.#size === null) return
+    let actual = 0
+    try { actual = (await stat(this.#path)).size } catch (err) {
+      if (err.code !== 'ENOENT') throw err
+    }
+    if (actual !== this.#size) {
+      throw new KxcoPqAuditError(
+        `${this.#path}: file is ${actual} bytes, expected ${this.#size}. ` +
+        'Something else wrote to this log. Appending now would fork the chain, ' +
+        'so open a new instance to pick up the current tail.'
+      )
+    }
+  }
+
+  /** Release the write handle. Safe to call more than once, and after any write. */
+  async close() {
+    clearTimeout(this.#idleTimer)
+    this.#idleTimer = null
+    if (!this.#handle) return
+    const handle = this.#handle
+    this.#handle = null
+    try { await this.assertSoleWriter() } finally { await handle.close() }
+  }
+
+  async #open() {
+    if (this.#handle) return this.#handle
+    try { this.#size = (await stat(this.#path)).size } catch (err) {
+      if (err.code !== 'ENOENT') throw err
+      this.#size = 0
+    }
+    this.#handle = await open(this.#path, 'a')
+    return this.#handle
   }
 }

package/src/index.d.ts

@@ -7,13 +7,42 @@ export interface AuditEntry {
   metadata:  Record<string, unknown>
   /** 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 fields. */
-  signature: string
+  /**
+   * base64url ML-DSA-65 signature over a canonical representation of all other
+   * fields. Absent on a sealed log, where the run is signed once by `seal()`.
+   */
+  signature?: string
+}
+
+/** One signed run of a sealed log. Seals chain to each other by `prevRoot`. */
+export interface AuditSeal {
+  fromSeq:    number
+  toSeq:      number
+  entryCount: number
+  /** The previous seal's rootHash, or 64 zeroes for the first seal. */
+  prevRoot:   string
+  /** 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. */
+  signature:  string
+  institutionKid: string | null
 }
 
 export interface AuditVerifySuccess {
   valid: true
   count: number
+  /**
+   * Sealed logs only: the highest seq covered by a verified seal, or -1 when
+   * nothing is sealed yet.
+   */
+  sealedThrough?: number
+  /**
+   * Sealed logs only: entries appended since the last seal. They are chained
+   * but carry no signature. A non-zero value is not a failure and is not proof
+   * either — seal() closes the window.
+   */
+  unsealed?: number
 }
 
 export interface AuditVerifyFailure {
@@ -39,14 +68,34 @@ export interface AuditLogOptions {
   checkpointEvery?: number
   /** Institution kid used to tag the anchor. Derived from keypair if omitted. */
   institutionKid?: string
+  /**
+   * Sign once per sealed run instead of once per entry (default: false).
+   *
+   * Every entry is still hash-chained, which is what detects an edit, a
+   * removal, a reorder or an insertion. The signature binds the run to the
+   * key. Measured on ML-DSA-65: per-entry signing runs at a few hundred
+   * entries per second and ~4.8KB per entry; sealing runs at tens of thousands
+   * per second and ~370 bytes. Use it wherever entry volume is high enough
+   * that a signature per entry does not fit, such as agent tool calls.
+   *
+   * The tradeoff: a single entry can no longer be verified in isolation, and
+   * entries written since the last seal are chained but unsigned.
+   */
+  sealed?: boolean
 }
 
 /**
  * In-memory tamper-evident audit log.
  *
- * Each entry is ML-DSA-65-signed and SHA-256 hash-chained to its predecessor.
+ * Every entry is SHA-256 hash-chained to its predecessor, and signed with
+ * ML-DSA-65 either per entry or, with `sealed: true`, once per run.
  * `verify()` replays the entire chain — any gap, reorder, or edit breaks either
  * the chain or a signature.
+ *
+ * Appending costs the same on a log of ten entries and a log of ten million:
+ * a new entry needs the previous entry's hash, never the log. Concurrent
+ * `append()` calls are serialised internally, so two in flight together cannot
+ * take the same seq.
  */
 export declare class AuditLog {
   constructor(options: AuditLogOptions)
@@ -54,16 +103,51 @@ export declare class AuditLog {
   /** Append a signed, hash-chained entry. Returns the created entry. */
   append(operation: string, metadata?: Record<string, unknown>): Promise<AuditEntry>
 
-  /** Verify every entry's signature and the full hash chain. */
+  /**
+   * 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>
 
-  /** Return a copy of all entries. */
+  /**
+   * 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
+   * with `sealed: true`. Anchors the root when a chain client is configured.
+   */
+  seal(): Promise<AuditSeal | null>
+
+  /** Every seal this log holds, oldest first. */
+  seals(): Promise<AuditSeal[]>
+
+  /** Entries appended since the last seal. Always 0 on a classic log. */
+  unsealedCount(): Promise<number>
+
+  /** True when this log signs per run rather than per entry. */
+  readonly sealed: boolean
+
+  /**
+   * Every entry as an array. Holds the whole log in memory by definition; on a
+   * large log prefer `stream()`.
+   */
   export(): Promise<AuditEntry[]>
+
+  /** Every entry, in seq order, one at a time. Memory is bounded by one entry. */
+  stream(): AsyncIterableIterator<AuditEntry>
 }
 
 export interface FileAuditLogOptions extends AuditLogOptions {
-  /** Path to the append-only NDJSON file. Created on first write if absent. */
+  /**
+   * Path to the append-only NDJSON file. Created on first write if absent.
+   * On a sealed log the seals are written to `<path>.seals`, so a reader that
+   * knows only about entries is unaffected.
+   */
   path: string
+  /**
+   * Release the write handle after this many ms without a write (default:
+   * 2000). A busy log never goes idle and keeps the handle; a short-lived one
+   * hands the descriptor back on its own, so a missed `close()` costs nothing.
+   */
+  idleReleaseMs?: number
 }
 
 /**
@@ -72,6 +156,19 @@ export interface FileAuditLogOptions extends AuditLogOptions {
  */
 export declare class FileAuditLog extends AuditLog {
   constructor(options: FileAuditLogOptions)
+
+  /**
+   * Release the write handle. Safe to call more than once. Not required — the
+   * handle is released on idle — but call it for a deterministic hand-back.
+   * Throws if another writer has touched the file.
+   */
+  close(): Promise<void>
+
+  /**
+   * Throw unless the entry file is the size this instance left it. Runs on
+   * every seal and on close; call it directly to check at any other point.
+   */
+  assertSoleWriter(): Promise<void>
 }
 
 export class KxcoPqAuditError extends Error {