kxco-pq-audit 1.3.1 → 1.4.1

package/ASSESSMENT.md

@@ -1,122 +1,130 @@
 # Assessment notes
 
-What a buyer assessing this package needs that the README does not tell them:
-where the product boundary falls, what cryptographic agility it has, and what
-constrains its lifecycle.
+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.
 
-This package does not implement ML-DSA, ML-KEM or SLH-DSA. It calls
+Algorithm conformance belongs to
 [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum), which
-runs the NIST ACVP vectors and the cross-implementation interoperability matrix
-and publishes them in its own evidence bundle. Algorithm conformance is a claim
-about that package, is referenced here, and is deliberately not restated. A
-second copy of a conformance claim invites you to count it twice.
-
-## Boundary
-
-**What the assessed thing is.** A library that writes and verifies an
-append-only NDJSON file. One storage backend exists, `src/backends/file.js`.
-
-**Operate: no network of its own.** Nothing in `src/` opens a socket. Chain
-anchoring happens through a `chain` object the caller injects, so the network
-call belongs to whatever implements it, normally
-[`kxco-pq-chain`](https://www.npmjs.com/package/kxco-pq-chain). Assess that
-package for the connection; this one only calls a method.
-
-**Operate: writes are serialised.** Appends run through a promise queue,
-because two appends in flight would read the same tail and mint the same `seq`,
-forking the chain at the point it is supposed to be strongest. That is a
-property of a single process. Two processes appending to one file is not a
-supported configuration and there is no lock that would make it one.
-
-**Protect records.** This is the package's whole purpose, so state the parts
-separately:
-
-- *Integrity* is a SHA-256 hash chain over entries, plus an ML-DSA-65
-  signature. In default mode every entry is signed. In sealed mode entries are
-  chained and unsigned, and `seal()` signs the run once, which is what makes
-  high append rates affordable.
-- *Timestamps in an entry are the local clock.* They are signed, so they cannot
-  be altered after the fact, and a signed clock is still the operator's clock.
-  They are not a trusted time source and nothing here claims they are.
-- *The independent time bound is the on-chain checkpoint*, which proves at
-  least N entries existed at a given block height. Anchoring is deliberately
-  fire-and-forget: `append` does not await it so chain latency never blocks an
-  audit write, and a failed anchor writes a warning to stderr while the log
-  continues.
-
-  The consequence is worth stating plainly. A log with no anchor and a log
-  whose anchor call failed look identical from the file alone. If the anchor is
-  part of your control, monitor that it happened; the log will not tell you.
-
-**Start and update.** This package has no release signing of its own. The
-primitives package signs its release assets with ML-DSA-65 against a committed
-public key; this one is an ordinary npm package published through CI with npm
-provenance and nothing further. That is a real difference between the two and
-should not be read across.
-
-**Retain history: the limitation that matters.** `verify(publicKey)` takes one
-public key and applies it to the whole log. A log whose signing key was rotated
-part-way through cannot be verified as a single artefact, because entries
-before the rotation were signed by a key `verify` is no longer being given.
-
-There is no key identifier in the entry format and no validity window, so the
-package cannot select the right key per entry, and it cannot tell you a key was
-still trusted when a signature was made. Long-lived logs need either one key
-for the life of the log, or a segmentation strategy the caller imposes from
-outside. This is the open long-term-validation question for the KXCO stack and
-it is not solved here.
+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, with one addition and one hard limit.
+**Inherited.** The signature primitive and its two interchangeable backends
+belong to `kxco-post-quantum`.
 
-**Inherited.** The signature primitive, its two interchangeable backends and
-the parameter-set surface all belong to `kxco-post-quantum`. See that package's
-`AGILITY.md`. Nothing in this package constrains which backend runs.
+**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.
 
-**The addition: the format carries a version.** Signed bytes are domain
-separated and prefixed, `kxco-audit-v1` for entries and `kxco-audit-seal-v1`
-for seals. A v2 entry format can therefore be introduced without a v1 signature
-becoming ambiguous, which is the property a format migration needs.
+## Running it
 
-**The limit: the algorithm is not selectable.** Entries are signed with
-ML-DSA-65 and there is no algorithm field in the entry. A move to a different
-parameter set is a format change and a release of this package, not a
-configuration. Given the file is the artefact and old entries have to keep
-verifying, that is the conservative choice, and it is a ceiling rather than a
-feature.
+**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.
 
-## Lifecycle
+**Supported versions.** One line moving forward. Fixes land in the next release.
 
-**Supported versions.** One line moving forward, matching the rest of the
-family. Fixes land in the next release rather than being backported.
+**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.
 
-**The primitives are declared as a range, and that is the assessed-configuration
-problem.** This package declares `kxco-post-quantum` as `^1.3.0`. The primitives
-package states, in its own `SECURITY.md`, that a range would let the code that
-runs the cryptography change without a release, and pins its own dependencies
-exactly for that reason. We do not apply the same rule here.
-
-The practical effect is measurable rather than theoretical: the tree this
-package's evidence bundle was last built from resolved `^1.3.0` to **1.4.0**,
-old enough to predate `backend()`, so it could not even report which
-implementation performed the signatures. `02-primitives.json` in the bundle
-records the resolved version for exactly this reason. Read it before treating
-any claim here as applying to your install.
-
-Changing this is a policy decision with a maintenance cost: an exact pin means
-every primitives release needs a release of this package. It has not been made.
-
-**Ceiling.** No hardware ceiling. One storage backend, and reads are line by
-line, so search belongs in a database you index into rather than here. The
-practical limit is append throughput in default mode, where every entry is
-signed; sealed mode exists because that limit is real.
-
-**Roadmap.** No external audit of this package, no bug bounty, no module
-certification. The primitives package publishes its roadmap in `AUDIT.md`;
-nothing equivalent has been committed for this one.
+**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 claim here is checkable against `src/`. If one does not match, that is a
-defect worth reporting through the repository's issues.
+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,81 @@
 # Changelog
 
+## 1.4.1
+
+Documentation. No source change.
+
+**The npm page leads with what the package proves.** The first screen now leads with the tamper-evidence guarantee, the sealed-mode
+throughput, key rotation and the migration dates set by NIST, Executive Order
+14412, OMB M-26-15 and the UK NCSC.
+
+A family table maps every KXCO package to the job it does, and a new For
+institutions section sets out the operated services and how to reach us. The
+evidence documents are unchanged and linked from the page.
+
+## 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.

package/README.md

@@ -1,38 +1,32 @@
 # kxco-pq-audit
 
+**A tamper-evident post-quantum audit trail: any edit, gap or reorder fails verification and names the entry.**
+
 [![npm](https://img.shields.io/npm/v/kxco-pq-audit?label=npm&color=b0964f)](https://www.npmjs.com/package/kxco-pq-audit)
+[![downloads](https://img.shields.io/npm/dm/kxco-pq-audit?label=downloads&color=b0964f)](https://www.npmjs.com/package/kxco-pq-audit)
+[![NIST ACVP](https://img.shields.io/badge/NIST_ACVP-1,793_passed,_0_failed-2ea44f)](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/blob/main/CONFORMANCE.md)
+[![npm provenance](https://img.shields.io/badge/npm-provenance-2ea44f)](https://www.npmjs.com/package/kxco-pq-audit)
 [![Socket](https://socket.dev/api/badge/npm/package/kxco-pq-audit)](https://socket.dev/npm/package/kxco-pq-audit)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
 [![node](https://img.shields.io/node/v/kxco-pq-audit.svg)](https://nodejs.org)
 
-Tamper-evident post-quantum audit log. Every operation produces an ML-DSA-65-signed entry chained to the previous via SHA-256. `verify()` replays the entire log — any gap, reorder, or edit breaks the chain or a signature.
+Every operation produces a signed entry: an ML-DSA-65 signature, SHA-256 chained to the previous entry. `verify()` replays the entire log, and any gap, reorder or edit breaks the chain or a signature.
 
-## Release integrity
+- **Tampering is detectable and locatable.** `verify()` replays the log from entry 0 and names the first entry that fails.
+- **Fast enough for real volume.** Sealed mode signs once per run: 46,544 entries a second at 367 bytes an entry, with 10,000 entries verified in 0.11 s, per [Sealed logs](#sealed-logs).
+- **Verifies across key rotation.** Pass every key the log was signed under and it verifies as one artefact, with each entry naming the kid that signed it.
+- **Streams, so size is no limit.** Memory stays bounded by one entry: 50,000 entries verify in 729 ms, per [`log.verify`](#logverifypublickey).
+- **An anchor a regulator can confirm.** Checkpoints on Armature L1 prove that at least N entries existed at a given block height.
+- **Built for auditors.** Evidence for SOC 2 and ISO 27001 controls that a third party can check without trusting the log operator.
+- **Proven underneath.** 1,793 NIST ACVP vectors passed, 0 failed, and 225 interoperability checks against liboqs, Bouncy Castle and the Python reference implementations, 0 failed, in [`kxco-post-quantum`](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/blob/main/CONFORMANCE.md).
+
+**The migration has dates.**
+
+- **NIST** published [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final), [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final) and [FIPS 205](https://csrc.nist.gov/pubs/fips/205/final) in August 2024.
+- **United States:** [Executive Order 14412](https://www.federalregister.gov/documents/2026/06/25/2026-12909/securing-the-nation-against-advanced-cryptographic-attacks), signed on 22 June 2026, moves federal high-value and high-impact systems to post-quantum key establishment by 31 December 2030 and to post-quantum signatures by 31 December 2031. [OMB M-26-15](https://www.whitehouse.gov/wp-content/uploads/2026/06/M-26-15-Execution-of-the-Migration-to-Post-Quantum-Cryptography.pdf) requires PQC-agile libraries for all new applications.
+- **United Kingdom:** the [NCSC](https://www.ncsc.gov.uk/guidance/pqc-migration-timelines) sets 2028, 2031 and 2035 as its migration milestones.
 
-Every release of this package is checkable without asking us for anything.
-
-- **Provenance.** Each release carries a SLSA provenance attestation tying the
-  published tarball to the commit and workflow that built it. Verify with
-  `npm audit signatures`, or read it directly from
-  `registry.npmjs.org/-/npm/v1/attestations/kxco-pq-audit@<version>`.
-- **Bill of materials.** A CycloneDX SBOM is published as a GitHub Release asset
-  at `releases/download/v<version>/sbom.cyclonedx.json`, a permanent
-  unauthenticated URL. Not an expiring build artifact.
-- **Pinned where it matters.** Third-party dependencies are pinned to exact
-  versions, never ranges, so the code that performs the cryptography cannot
-  change without a release. Sibling `kxco-*` packages sit on caret ranges
-  deliberately: it means a correctness fix in the base package reaches you
-  without a release of every package above it. That is not theoretical. When
-  `@noble/post-quantum` 0.7.1 was found to fail NIST SLH-DSA verification
-  vectors, the revert in the base package propagated here on the next install.
-  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: 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,
-  verified in CI on every run.
+[Quick start](#quick-start) · [Sealed logs](#sealed-logs) · [For institutions](#for-institutions) · [Assessment notes](./ASSESSMENT.md) · [Changelog](./CHANGELOG.md) · [kxco.ai](https://kxco.ai)
 
 ## When to use this
 
@@ -45,7 +39,7 @@ Designed for:
 - SOC 2 and ISO 27001 implementations requiring evidence that access and operations cannot be silently edited
 - Any system where "the log said X happened" must be verifiable by a third party without trusting the log operator
 
-This is not a logging framework. It is a cryptographic integrity primitive — a chain of signed, hash-linked records that proves the log has not been tampered with.
+It is a cryptographic integrity primitive: a chain of signed, hash-linked records that proves the log is exactly as written.
 
 ## Install
 
@@ -57,13 +51,16 @@ npm install kxco-pq-audit
 
 ```js
 import { FileAuditLog } from 'kxco-pq-audit'
-import { KxcoChain }    from 'kxco-pq-chain'   // optional — omit if not anchoring
+import { KxcoChain }    from 'kxco-pq-chain'   // optional, for anchoring
 import { mlDsa }        from 'kxco-post-quantum'
 
 const keypair = mlDsa.ml_dsa65.keygen()
 
 // Persist to disk, anchor a checkpoint on Armature L1 every 50 entries
-const chain = new KxcoChain({ endpoint: 'https://relay.kxco.ai' })
+const chain = new KxcoChain({
+  identity:   institutionIdentity,           // a KxcoIdentity from kxco-pq-sdk
+  licenceKey: process.env.KXCO_LICENCE_KEY,  // the hosted anchoring service
+})
 const log = new FileAuditLog({
   keypair,
   path: './audit.ndjson',
@@ -84,15 +81,35 @@ const entries = await log.export()
 
 Chain anchoring is optional. Remove the `chain` and `checkpointEvery` options to run without it.
 
+## For institutions
+
+The cryptography is free under Apache-2.0, works offline and needs nothing from
+KXCO, now or in ten years. What KXCO sells is the part that has to be operated:
+an answer about the present.
+
+| Service | What you get |
+|---|---|
+| Hosted key registry | Whether a key is active, revoked or rotated, answered at verification time |
+| Meta-transaction relay | KXCO validates your signed intent, pays the gas and submits it, so you never hold a token or run a node |
+| On-chain anchoring | A timestamp on Armature L1 that the chain itself has verified |
+| Live revocation | `anchored+live` verification, which confirms the signing key is still trusted now |
+| Support and SLA | Availability commitments, an escalation path and a named contact |
+
+Priced in USD, per seat, per year. No tokens, no nodes and no wallets. The line
+between free and paid is set out in
+[LICENCE-PRODUCT.md](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/blob/main/LICENCE-PRODUCT.md).
+
+**Talk to us: [admin@kxco.ai](mailto:admin@kxco.ai)** · [kxco.ai](https://kxco.ai)
+
 ## API
 
 ### `new AuditLog(options)`
 
-In-memory log. Entries are lost when the process exits.
+In-memory log, for tests and short-lived processes. Use `FileAuditLog` to persist.
 
 | Option | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `keypair` | `{ secretKey, publicKey }` | Yes | — | ML-DSA-65 keypair from `kxco-post-quantum` |
+| `keypair` | `{ secretKey, publicKey }` | Yes | none | ML-DSA-65 keypair from `kxco-post-quantum` |
 | `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 |
@@ -119,11 +136,11 @@ Entries are read as a stream and never all at once, and writes go through one ha
 
 Appends a signed, hash-chained entry.
 
-- `operation` — non-empty string identifying the operation (e.g. `'wire.auth'`, `'key.rotate'`)
-- `metadata` — plain object, serialised into the signed payload
+- `operation`: non-empty string identifying the operation (e.g. `'wire.auth'`, `'key.rotate'`)
+- `metadata`: plain object, serialised into the signed payload
 - Returns the entry object
 
-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.
+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, without waiting 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`.
 
@@ -134,9 +151,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, per [ASSESSMENT.md](./ASSESSMENT.md).
+
+#### 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.
 
-It streams, so memory is bounded by one entry rather than by the log: 50,000 entries verify in 729 ms without holding them.
+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.
 
 ### `log.seal()`
 
@@ -183,14 +224,14 @@ Sealed logs only. Entries appended since the last seal, without replaying the lo
 
 ## 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:
+By default every entry carries its own ML-DSA-65 signature. That signature is also the entire cost of the log. Measured over 10,000 entries, per [ASSESSMENT.md](./ASSESSMENT.md):
 
 | | 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.
+Of those 4,794 bytes, per [ASSESSMENT.md](./ASSESSMENT.md), 4,412 are the base64url-encoded signature, which is why sealed mode is the one for real entry volume.
 
 `sealed: true` keeps the hash chain on every entry and moves the signature to the run:
 
@@ -214,54 +255,61 @@ 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.
+Entries appended since the last seal are chained and awaiting a signature. `unsealed` reports that window, and `seal()` closes it. A sealed entry verifies 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.
+When you pass a chain and set `checkpointEvery`, every Nth entry triggers a call to `chain.anchorAuditRoot({ rootHash, entryCount })` via the KXCO relay.
 
 The anchor is fire-and-forget: `append` does not await it, so chain latency never blocks audit operations. If the relay call fails, a warning is written to stderr and the local log continues unaffected.
 
 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.
 
-## 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.
-
-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
+## The KXCO post-quantum family
 
-## Part of the KXCO stack
-
-| Package | Role |
+| You need to | Install |
 |---|---|
-| [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum) | ML-DSA-65 primitives |
-| [`kxco-pq-hsm`](https://www.npmjs.com/package/kxco-pq-hsm) | HSM-backed key management |
-| [`kxco-pq-attest`](https://www.npmjs.com/package/kxco-pq-attest) | Payload attestation |
-| [`kxco-pq-sdk`](https://www.npmjs.com/package/kxco-pq-sdk) | `AuditedHsm` — wires HSM + audit log automatically |
-| [`kxco-pq-chain`](https://www.npmjs.com/package/kxco-pq-chain) | Armature L1 relay for checkpoint anchoring |
+| Put the whole stack in one install | [`kxco-pq`](https://www.npmjs.com/package/kxco-pq) |
+| Use ML-DSA, ML-KEM and SLH-DSA directly | [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum) |
+| Keep signing keys on the HSM you already run | [`kxco-pq-hsm`](https://www.npmjs.com/package/kxco-pq-hsm) |
+| Sign a document or record anyone can verify offline | [`kxco-pq-attest`](https://www.npmjs.com/package/kxco-pq-attest) |
+| Keep a tamper-evident audit trail | [`kxco-pq-audit`](https://www.npmjs.com/package/kxco-pq-audit) |
+| Verify a signature in a browser, with no server | [`kxco-verify`](https://www.npmjs.com/package/kxco-verify) |
+| Issue institution identity credentials | [`kxco-pq-sdk`](https://www.npmjs.com/package/kxco-pq-sdk) |
+| Encrypt files and payloads to one or many recipients | [`kxco-pq-vault`](https://www.npmjs.com/package/kxco-pq-vault) |
+| Encrypt Node streams and WebSockets | [`kxco-pq-tls`](https://www.npmjs.com/package/kxco-pq-tls) |
+| Sign and verify webhooks | [`kxco-post-quantum-webhook`](https://www.npmjs.com/package/kxco-post-quantum-webhook) |
+| Give an AI agent an identity a verified institution sponsors | [`kxco-pq-agent`](https://www.npmjs.com/package/kxco-pq-agent) |
+| Have Armature L1 verify a signature in consensus | [`kxco-pq-chain`](https://www.npmjs.com/package/kxco-pq-chain) |
+| Prove an envelope at three levels, offline to on-chain | [`kxco-pq-network`](https://www.npmjs.com/package/kxco-pq-network) |
+| Generate and rotate keys from a terminal | [`kxco-pq-cli`](https://www.npmjs.com/package/kxco-pq-cli) |
+| Find quantum-vulnerable cryptography in a dependency tree | [`kxco-pq-scan`](https://www.npmjs.com/package/kxco-pq-scan) |
+| Fail the build when code reaches past the wrapper | [`eslint-plugin-kxco-pq`](https://www.npmjs.com/package/eslint-plugin-kxco-pq) |
 
 [kxco.ai](https://kxco.ai) · [Knightsbridge Law](https://knightsbridge.law) · [target150.com](https://target150.com)
 
+## Release integrity
+
+Each release carries a SLSA provenance attestation tying the published tarball to
+the commit and workflow that built it: verify with `npm audit signatures`, or read
+it from `registry.npmjs.org/-/npm/v1/attestations/kxco-pq-audit@<version>`. A CycloneDX
+SBOM is published as a GitHub Release asset at
+`releases/download/v<version>/sbom.cyclonedx.json`, a permanent unauthenticated
+URL. Sibling `kxco-*` packages sit on caret ranges so a correctness fix in the
+base package reaches you on the next install, with no release of every package
+above it.
+
 ## Security
 
 **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`
+- **1,793 NIST ACVP vectors passed, 0 failed** across FIPS 203, 204 and 205, pinned by digest, per [CONFORMANCE.md](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/blob/main/CONFORMANCE.md). The other 310 are pairings the library refuses as weaker than the parameter set
+- **225 interoperability checks passed, 0 failed**, 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
 
@@ -277,4 +325,4 @@ Apache-2.0 © 2026 KXCO by Knightsbridge
 
 ## Maintainers
 
-Shayne Heffernan and John Heffernan — [KXCO by Knightsbridge](https://kxco.ai)
+Shayne Heffernan and John Heffernan, [KXCO by Knightsbridge](https://kxco.ai)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kxco-pq-audit",
-  "version": "1.3.1",
-  "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.",
+  "version": "1.4.1",
+  "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",
     "pqc",
@@ -19,7 +19,17 @@
     "integrity",
     "immutable-log",
     "signed-log",
-    "sequence"
+    "sequence",
+    "quantum-safe",
+    "pqc-migration",
+    "digital-signature",
+    "soc2",
+    "iso27001",
+    "append-only",
+    "event-log",
+    "non-repudiation",
+    "ai-agent",
+    "crypto-agility"
   ],
   "license": "Apache-2.0",
   "author": "Shayne Heffernan and John Heffernan",

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,