kxco-pq-audit 1.5.0 → 1.5.2

package/ASSESSMENT.md

@@ -11,13 +11,13 @@ 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
+SHA-256 hash-chained and ML-DSA-87 or ML-DSA-65 signed, as the key decides, 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:
+`seal()` signs the run once. Measured over a 10,000 entry run with an ML-DSA-65 key:
 
 | | entries/s | bytes/entry | 10k run | verify |
 |---|---|---|---|---|

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.5.2 (2026-10-07)
+
+Documentation. No source change.
+
+ML-DSA-87 is the parameter set KXCO recommends for every new key. The quick
+start now makes an ML-DSA-87 keypair with `mlDsa87.ml_dsa87.keygen()`, and its
+`key.rotate` example names `ml-dsa-87`. The entry format example is an
+ML-DSA-87 entry, with the `alg` field it carries.
+
+"Sealed logs" said every entry carries its own ML-DSA-65 signature by default.
+The key decides the set; the default is one signature per entry. It now says
+so, and that the figures were measured with an ML-DSA-65 key.
+An ML-DSA-87 signature is 4,627 bytes, 6,170 base64url characters against 4,412 for ML-DSA-65, per FIPS 204, table 2.
+ASSESSMENT.md and the type declarations name ML-DSA-87 first.
+
+`DEFAULT_ALG` stays `ML-DSA-65`. It is how a record with no `alg` reads, and
+every such record predates the field. An ML-DSA-65 key still writes v1 records
+with no `alg`, so they verify under 1.4.x. It never picks the set a log signs
+with, and its comment now says so.
+
+## 1.5.1
+Documentation. No source change.
+
+The npm description and the README lead name ML-DSA-87 beside ML-DSA-65: the
+log has signed and verified both since 1.5.0. The description no longer quotes
+the sealed-mode rate, which was measured with an ML-DSA-65 key; the README keeps
+it with that context.
+
 ## 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

package/README.md

@@ -10,7 +10,7 @@
 [![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)
 
-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.
+Every operation produces a signed entry: an ML-DSA-87 or ML-DSA-65 signature (the key decides), SHA-256 chained to the previous entry. `verify()` replays the entire log, and any gap, reorder or edit breaks the chain or a signature.
 
 - **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).
@@ -52,9 +52,9 @@ npm install kxco-pq-audit
 ```js
 import { FileAuditLog } from 'kxco-pq-audit'
 import { KxcoChain }    from 'kxco-pq-chain'   // optional, for anchoring
-import { mlDsa }        from 'kxco-post-quantum'
+import { mlDsa87 }      from 'kxco-post-quantum'
 
-const keypair = mlDsa.ml_dsa65.keygen()
+const keypair = mlDsa87.ml_dsa87.keygen()
 
 // Persist to disk, anchor a checkpoint on Armature L1 every 50 entries
 const chain = new KxcoChain({
@@ -70,7 +70,7 @@ const log = new FileAuditLog({
 
 await log.append('user.login',  { userId: 'u_001', ip: '10.0.0.1' })
 await log.append('wire.auth',   { txId: 'tx_abc', amount: 50000, currency: 'USD' })
-await log.append('key.rotate',  { keyId: 'signing-key-v2', alg: 'ml-dsa-65' })
+await log.append('key.rotate',  { keyId: 'signing-key-v2', alg: 'ml-dsa-87' })
 
 const result = await log.verify(keypair.publicKey)
 // { valid: true, count: 3 }
@@ -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 or ML-DSA-87 keypair from `kxco-post-quantum`. The key decides which set signs; `log.signingAlg` reports it |
+| `keypair` | `{ secretKey, publicKey }` | Yes | none | ML-DSA-87 or ML-DSA-65 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 |
@@ -236,22 +236,23 @@ Sealed logs only. Entries appended since the last seal, without replaying the lo
   "operation": "wire.auth",
   "metadata": { "txId": "tx_abc", "amount": 50000 },
   "prevHash": null,
-  "signature": "<base64url ML-DSA-65>"
+  "signature": "<base64url ML-DSA-87>",
+  "alg": "ML-DSA-87"
 }
 ```
 
-`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.
+`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. Only an entry signed with ML-DSA-87 carries `alg`, which the signing message covers. An entry signed with ML-DSA-65 carries none, exactly as before.
 
 ## Sealed logs
 
-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):
+By default every entry carries its own signature, made under the set of the log's key. That signature is also the entire cost of the log. Measured over 10,000 entries with an ML-DSA-65 key, 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, per [ASSESSMENT.md](./ASSESSMENT.md), 4,412 are the base64url-encoded signature, which is why sealed mode is the one for real entry volume.
+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. An ML-DSA-87 signature is 4,627 bytes ([FIPS 204](https://csrc.nist.gov/pubs/fips/204/final), table 2), or 6,170 base64url characters, so an entry signed with it is larger and sealed mode saves more.
 
 `sealed: true` keeps the hash chain on every entry and moves the signature to the run:
 
@@ -323,7 +324,7 @@ 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.
+**ML-DSA-87 and 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:
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "kxco-pq-audit",
-  "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.",
+  "version": "1.5.2",
+  "description": "Tamper-evident post-quantum audit trail for regulated institutions. ML-DSA-87 or ML-DSA-65 signed, SHA-256 hash-chained entries: any edit, gap or reorder fails verification and names the entry. Checkpoints anchored on Armature L1.",
   "keywords": [
+    "ml-dsa-87",
     "post-quantum",
     "pqc",
     "audit-log",

package/src/audit-log.js

@@ -18,6 +18,8 @@ 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 }),
 })
+// How a record with no `alg` reads, and so the set whose records carry none.
+// It never picks the set a log signs with: the key's length does.
 const DEFAULT_ALG = 'ML-DSA-65'
 
 function algForKey(key, field) {
@@ -233,7 +235,7 @@ export class AuditLog {
     return { signature: b64url(Buffer.from(sig, 'hex')), stated }
   }
 
-  /** The parameter set this log signs with: 'ML-DSA-65' or 'ML-DSA-87'. */
+  /** The parameter set this log signs with: 'ML-DSA-87' or 'ML-DSA-65'. */
   get signingAlg() { return this.#signingAlg() }
 
   /**

package/src/index.d.ts

@@ -143,7 +143,8 @@ export interface AuditLogOptions {
  * In-memory tamper-evident audit log.
  *
  * 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.
+ * ML-DSA-87 or ML-DSA-65, as the key decides, 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.
  *
@@ -185,7 +186,7 @@ export declare class AuditLog {
   readonly signingKid: string
 
   /** The parameter set this log signs with, decided by its secret key. */
-  readonly signingAlg: 'ML-DSA-65' | 'ML-DSA-87'
+  readonly signingAlg: 'ML-DSA-87' | 'ML-DSA-65'
 
   /**
    * Sign everything appended since the last seal, as one run. Returns the seal,