kxco-post-quantum 1.5.2 → 1.6.0

package/BENCHMARKS.md

@@ -85,15 +85,19 @@ Milliseconds. 100 iterations except where the `n` column says otherwise.
 
 **Two numbers to design around.**
 
-**ML-DSA signing has a long tail.** ML-DSA-65 signs in 11 ms at the median and
-51 ms at p99, a factor of 4.5. Rejection sampling means an unlucky signature does
-several more rounds. Size request budgets from p99, not the median.
-
-**SLH-DSA-SHA2-192s signs in about 6.8 seconds.** That is the set `slhDsa` wraps,
-and it is not a per-request operation. It suits infrequent, high-value signatures
-such as firmware or root attestations. Verification is cheap, around 5 ms, so an
-SLH-DSA signature is expensive to make and cheap to check. The `f` variants trade
-signature size for signing speed: SHA2-128f signs in 151 ms.
+**ML-DSA signing has a long tail, on both backends.** ML-DSA-65 signs in 8.1 ms
+at the median and 40.8 ms at p99 in JavaScript, a factor of 5.1. On OpenSSL it is
+1.3 ms and 4.6 ms, a factor of 3.5. Rejection sampling means an unlucky signature
+does several more rounds, and no backend removes that. Size request budgets from
+p99, not the median, and from the p99 of the backend you will actually run.
+
+**SLH-DSA-SHA2-192s signs in seconds, not milliseconds:** about 4.3 s in
+JavaScript and 1.7 s on OpenSSL. That is the set `slhDsa` wraps, and on either
+backend it is not a per-request operation. It suits infrequent, high-value
+signatures such as firmware or root attestations. Verification is cheap, 7.5 ms
+and 1.3 ms respectively, so an SLH-DSA signature is expensive to make and cheap
+to check. The `f` variants trade signature size for signing speed: SHA2-128f
+signs in 98 ms in JavaScript and 69 ms on OpenSSL.
 
 ## Key encapsulation
 
@@ -155,11 +159,12 @@ collection timing, not evidence that the larger parameter set allocates less.
 
 - **One machine, one run.** Node v26.1.0 on win32-x64. Absolute numbers move with
   hardware and runtime; the ratios between operations are the portable part.
-- **Not a cross-vendor comparison.** Nothing here was measured against another
-  implementation, so it says nothing about how this compares to a native or
-  hardware-backed stack. It will be slower than both.
+- **Not a cross-vendor comparison.** The two backends here are both ours to
+  ship, so the comparison above is between two paths through this package, not
+  between this package and someone else's. It says nothing about how either
+  compares to a hardware-backed stack.
 - **Reduced samples where marked.** SLH-DSA slow variants take 3 to 20 samples
-  rather than 100, because 100 signatures at 6.8 seconds each is not a benchmark,
+  rather than 100, because 100 signatures at seconds each is not a benchmark,
   it is an afternoon. Where n is small, p95 and p99 collapse onto the maximum and
   are reported that way rather than dressed up.
 - **Not a side-channel measurement.** Timing here is throughput, gathered without

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # Changelog
 
+## 1.6.0
+
+Additive. No existing export changes shape in a way a caller can observe, no
+wire format moves, and the pinned vectors still match bit-for-bit.
+
+**Seed-form keys.** FIPS 203 and 204 expand a keypair from a short seed, and
+the expanded private key does not contain the seed it came from. So seed export
+had to start at derivation: `keypairFromMaster` now also returns the seed it
+already derived. Callers destructuring `{ publicKey, secretKey }` see no
+difference. `seed.seedFromMaster` reproduces exactly the same bytes, which is
+what makes seed export possible for keys already in production.
+
+New `seed` namespace: `keypairFromSeed`, `seedFromMaster`, `exportJwk`,
+`importJwk`, `exportSeedPkcs8`, `importSeedPkcs8`, for ML-DSA-65, ML-DSA-87,
+ML-KEM-768 and ML-KEM-1024. JWKs are RFC 9964 `kty: "AKP"`, where `priv` is the
+seed; PKCS#8 is the LAMPS seed form, the `[0] IMPLICIT OCTET STRING` CHOICE.
+Both load directly into OpenSSL 3.5 and Node 24+. The existing expanded-key
+export is untouched and old keys verify unchanged.
+
+None of that is read off the specification. `test/seed.test.js` asserts the DER
+this package writes is byte-identical to what OpenSSL writes, for every
+parameter set, and that a seed expands to the same public key under both
+backends. Where there is no native backend those tests skip with a reason
+rather than passing quietly, because a green suite on a runtime without OpenSSL
+is not evidence about OpenSSL.
+
+An expanded secret key is refused where a seed belongs, and an expanded-form
+PKCS#8 key is refused rather than truncated. Both would otherwise silently
+produce a different keypair: the first 32 bytes of an expanded ML-DSA key are
+not its seed.
+
+**Compact JWS.** New `jws` namespace: `signJws`, `verifyJws`,
+`decodeJwsHeader`, using the RFC 9964 algorithm names `ML-DSA-65` and
+`ML-DSA-87`. Format only — no network, no configuration, no licence, and a
+token stays verifiable offline for as long as the holder keeps the public key.
+The algorithm is resolved from an allowlist inside the module rather than from
+the token, so a token cannot name its own verification routine; `crit` and `b64`
+are refused rather than ignored; and the key length must match the declared
+algorithm, so a mixed-up key reports itself instead of looking like a bad
+signature. SLH-DSA is deliberately not offered: FIPS 205 signing takes about a
+second and a half and does not belong on a request path.
+
+**A second correction to AUDIT.md.** The v1.1.2 correction fixed a false claim
+that `@noble/post-quantum` was Cure53-audited, and in doing so introduced a
+different inaccuracy: it described a single "Cure53 2023 NDS-01" audit covering
+`@noble/ciphers`, `@noble/curves` and `@noble/hashes`. There is no such
+engagement. Those are three separate audits at three different dates, and this
+repository's own `audit/dependency-review.json` — generated by
+`audit/run-audit.mjs`, not written by hand — recorded them correctly the whole
+time:
+
+| Package | Audited by |
+|---|---|
+| `@noble/post-quantum` | maintainer-audited, v0.6.1, Apr 2026 |
+| `@noble/hashes` | Cure53, Jan 2022, v1.0.0 (Ethereum Foundation with Nomic Labs) |
+| `@noble/curves` | Trail of Bits Feb 2023; Kudelski Sep 2023; Cure53 Sep 2024 |
+| `@noble/ciphers` | Cure53, Sep 2024, v1.0.0 (OpenSats) |
+
+The load-bearing claim never changed and was correct throughout:
+**`@noble/post-quantum` has never been audited by a third party.** What was
+wrong was the supporting detail, and the wrong wording had been copied into
+sibling repositories before it was caught. AUDIT.md now matches the generated
+record, and the v1.1.2 changelog entry is left as it was written — a released
+entry is a record of what was said at the time, not a place to rewrite it.
+
+**An evidence bundle.** `npm run evidence` writes `dist/evidence/`: versions,
+the commit, the toolchain, which backend did the maths, the ACVP and interop
+conformance output, the test suite output, a CycloneDX SBOM, the registry
+signature check, and copies of AUDIT.md, THREAT-MODEL.md, SECURITY.md,
+CONFORMANCE.md, DEPENDENCIES.md and LICENCE-PRODUCT.md.
+
+**It is not an audit and it says so three times** — in the manifest's
+`disclaimer` field, in the bundle README, and in the copied AUDIT.md. A CI step
+asserts both disclaimers are still present, because the one sentence that must
+never be edited out of an evidence bundle is the one saying it is not an audit.
+
+A step that fails is recorded as a failure in the manifest rather than aborting
+the build: a bundle missing a section with no explanation is worse than one
+that says what did not run and why. Optional steps (peers needing a JVM, a
+registry check needing a token) do not fail the build; required ones do.
+
+The `evidence` workflow runs on Node 22 and 24 — the first has no OpenSSL 3.5
+FIPS primitives and so exercises the JavaScript backend, the second exercises
+OpenSSL. Shipping only one bundle would let a reader draw a conclusion about
+code that never ran. Push builds subsample and record that they did; scheduled
+and release builds do a full pass.
+
+New `LICENCE-PRODUCT.md` states what is free (the maths, permanently, and
+chain-agnostic) and what is paid (the hosted registry, the relay, anchoring,
+live revocation, SLA), that the `KXCO Verified` mark needs a contract, and that
+no third party has assessed this code and a customer may re-run the published
+vectors without asking.
+
+**`backend()` and `isNative(alg)`.** The package chooses its backend by probing
+the runtime, so the only honest way to state which one a deployment used is to
+ask it. These report; neither switches. The ACVP conformance report now records
+`backendUnderTest` explicitly, saying that it drives the JavaScript primitives
+directly and that the OpenSSL backend is evidenced by the interop matrix
+instead. The same pass count previously described either implementation.
+
+## 1.5.3
+
+Documentation and metadata. No code change.
+
+Corrects stale performance figures. The README and BENCHMARKS.md both quoted a
+4.5x median-to-p99 tail for ML-DSA signing and about 6.8 seconds for
+SLH-DSA-SHA2-192s. Measured now, across both backends: the tail is 5.1x in
+JavaScript and 3.5x on OpenSSL, and SLH-DSA-SHA2-192s signs in 4.3 s and 1.7 s.
+
+Says what the package does. The README still described it as a wrapper around
+@noble/post-quantum without mentioning that on Node 24 and later the primitives
+run in OpenSSL 3.5. The npm description, which is what appears in registry search
+results, listed the algorithms and nothing else: not the 2,103 NIST ACVP vectors,
+not the 225-check interoperability matrix, not the reproducible build or the
+provenance attestation. Those are the parts that distinguish this from any other
+post-quantum wrapper, and they were absent from the one line most readers see.
+
+A dependabot ignore blocks @noble/post-quantum 0.7.1 specifically, so it is not
+reproposed weekly. The ACVP job fails the build on it regardless; this stops the
+pull request being opened. 0.7.2 and later will still be offered and should be
+accepted once the vectors pass.
+
 ## 1.5.2
 
 **Reverts `@noble/post-quantum` to 0.7.0. Upgrade from 1.5.1 immediately if you

package/CONFORMANCE.md

@@ -1,12 +1,15 @@
 # Conformance and interoperability evidence
 
-Two claims, each with a harness in this repository that anyone can run:
+Three claims, each with a harness in this repository that anyone can run:
 
 1. **This package computes what FIPS 203, 204 and 205 say it should.** Evidenced
    against NIST's own ACVP test vectors.
 2. **Independent implementations can consume what it produces, and it can
    consume theirs.** Evidenced against liboqs (C), Bouncy Castle (Java) and
    dilithium-py / kyber-py (Python), in both directions.
+3. **The PKI artefacts standard tooling issues validate here.** Evidenced by
+   having OpenSSL 3.5 issue ML-DSA certificates and signed messages, and
+   verifying them from this package with its own DER parsing.
 
 The second claim is the one that matters in deployment and the one that vector
 files cannot make. Passing NIST's vectors proves agreement with NIST. It does
@@ -19,9 +22,10 @@ Everything below is reproducible:
 npm run conformance:fetch      # pinned NIST vectors, digest-checked
 npm run conformance:acvp       # claim 1
 npm run conformance:interop    # claim 2
+npm run conformance:protocol   # claim 3
 ```
 
-Both harnesses run in CI on every push and in full weekly. See
+All three harnesses run in CI on every push and in full weekly. See
 [.github/workflows/conformance.yml](.github/workflows/conformance.yml).
 
 ---
@@ -243,6 +247,72 @@ keys, both carrying these identifiers, which is what makes the two backends
 interchangeable with each other and with any X.509 or CMS consumer that speaks
 the same encodings.
 
+## 5. Protocol artefacts: X.509 and CMS
+
+Claims 1 and 2 are about primitives and encodings. Neither answers the question a
+PKI team asks first, which is whether a certificate issued by the tooling they
+already run will validate.
+
+So OpenSSL issues and this package verifies. Nothing in the chain is ours on both
+sides, and the artefacts are generated fresh on every run rather than committed,
+because a fixture keeps passing after an encoding has drifted.
+
+| Issuer | Version | Base image |
+|---|---|---|
+| OpenSSL | 3.5.8, asserted at image build time | `alpine:3.22` |
+
+Pinned as `openssl` in
+[conformance/interop/peers-lock.json](conformance/interop/peers-lock.json). The
+exact build string is recorded in every report rather than the family, because
+"OpenSSL 3.5" names a line and not the binary that signed the bytes.
+
+### X.509
+
+A self-signed certificate per parameter set. Verification walks the DER to the
+`tbsCertificate`, takes it including its own tag and length octets, which is what
+RFC 5280 actually signs, and checks the `signature` BIT STRING over it with the
+public key read out of a separately supplied SubjectPublicKeyInfo.
+
+### CMS SignedData
+
+A signed message per parameter set, `-nodetach`, SHA-256 digest. ML-DSA carries no
+default digest in OpenSSL 3.5, so `-md` has to be named explicitly; without it
+`CMS_add1_signer` fails with "no default digest". That is a property of the CMS
+layer rather than of the key.
+
+The signature in a SignedData does not cover the message. It covers the DER
+encoding of the signed attributes, re-tagged from the `[0] IMPLICIT` they travel
+in to the `SET OF` they are signed as (RFC 5652 s5.4). Verifying it therefore
+takes four checks that only mean something together:
+
+| Check | What it establishes |
+|---|---|
+| `signatureVerified` | the signature is valid over the signed attributes |
+| `digestBindsMessage` | the `messageDigest` attribute is the digest of the content |
+| `contentTypeBound` | the signed `contentType` matches `eContentType` (RFC 5652 s5.3) |
+| `contentMatches` | the embedded content is the message that was submitted |
+
+The first alone would hold equally for a signature over somebody else's message.
+
+### Controls
+
+Every row carries OpenSSL's own verdict on the artefact, so a disagreement is
+attributable rather than assumed, and a tamper control that flips one bit of the
+signed body and requires the verification to fail. The controls are not
+decoration: the first version of the certificate parser sliced the wrong byte
+range and returned false for everything, which passed the tamper control and
+failed the positive check. Without the pair, a verifier that always returned true
+and one that always returned false would both have looked green.
+
+`algorithmOid` additionally checks that the SignerInfo names the OID in section 4
+for the set it claims. An implementation that verifies the bytes but disagrees
+about which algorithm they belong to still fails to interoperate.
+
+### Result
+
+33 checks across 6 rows, all passing, none not applicable. Reports are published
+as CI artefacts per Node version.
+
 ## What this evidence does not cover
 
 Stated plainly, because a conformance report that only lists what passed is
@@ -264,9 +334,11 @@ marketing.
   these modules change. The accurate sentences are "NIST FIPS 203/204/205
   conformant" and "supports ML-DSA-87 and ML-KEM-1024". Anything stronger,
   including "CNSA 2.0 ready", would be an overclaim.
-- **Protocol-level interop is not covered here.** Key and signature bytes
-  interoperate. Certificate and message encodings, X.509, CMS, COSE, JOSE and
-  TLS group negotiation are separate surfaces and no claim is made about them.
+- **Protocol coverage is X.509 and CMS, for the ML-DSA sets.** Section 5 covers
+  certificates and CMS SignedData against OpenSSL 3.5 for ML-DSA-44/65/87. COSE,
+  JOSE and TLS group negotiation are separate surfaces, and ML-KEM and SLH-DSA
+  are covered at the key and signature layer rather than in certificates,
+  because OpenSSL 3.5 issues neither.
 - **Self-administered.** Every number above was produced by harnesses in this
   repository, run by us. That is why they are reproducible and why the pins,
   digests and negative controls are there. It is not third-party attestation and

package/DEPENDENCIES.md

@@ -0,0 +1,137 @@
+# Dependency audit
+
+Four production dependencies. No development dependencies. Every one of them
+reviewed by a person, and every mechanical fact in that review re-checked by a
+harness that fails when reality moves away from it.
+
+```
+npm run audit:deps
+```
+
+- Curated review: [audit/dependency-review.json](audit/dependency-review.json)
+- Harness: [audit/run-audit.mjs](audit/run-audit.mjs)
+- Report: `audit/results/dependencies.json`, published as a CI artefact
+
+Current result: **26 checks passed, 0 failed, 0 skipped.**
+
+---
+
+## The tree
+
+| Package | Version | Licence | Pinning | On the code path | Independently reviewed by |
+|---|---|---|---|---|---|
+| `@noble/post-quantum` | 0.7.0 | MIT | exact | yes | maintainer self-audit at 0.6.1, Apr 2026 |
+| `@noble/hashes` | 2.3.0 | MIT | exact | yes | Cure53, Jan 2022 |
+| `@noble/curves` | 2.3.0 | MIT | transitive | yes | Trail of Bits, Feb 2023; Kudelski Security, Sep 2023; Cure53, Sep 2024 |
+| `@noble/ciphers` | 2.3.0 | MIT | transitive | no | Cure53, Sep 2024 |
+
+One maintainer publishes all four, and all four carry a verified npm registry
+signature and a verified SLSA provenance attestation, with nothing invalid and
+nothing missing across the installed tree. Nothing in the tree runs code at
+install time, and `npm audit` reports no advisory at any severity.
+
+## Why each one is there
+
+**`@noble/post-quantum`** supplies the FIPS 203, 204 and 205 primitives. This
+package is the layer above: parameter-set selection, FIPS 204 context strings,
+key derivation, fingerprinting, webhook signing and the OpenSSL backend. It does
+not reimplement the arithmetic.
+
+It is also the one package in the tree with no independent review, and that is
+the reason [conformance/](CONFORMANCE.md) exists. Every parameter set is checked
+against NIST's own ACVP vectors, cross-checked against liboqs, Bouncy Castle and
+dilithium-py / kyber-py in both directions, and checked against certificates and
+signed messages that OpenSSL 3.5 issued. The primitives are evidenced here rather
+than accepted on the dependency's word, and that evidence is reproducible on any
+machine.
+
+The pin is exact and deliberately so. Version 0.7.1 regressed nine NIST SLH-DSA
+verification vectors that 0.7.0 passes. It shipped in this package's 1.5.1, was
+reverted in 1.5.2, is deprecated on npm and is blocked in dependabot. A caret
+range would have taken that regression automatically, which is why the harness
+fails the build on any range in `dependencies`.
+
+**`@noble/hashes`** supplies SHA-256, SHA-512, SHAKE-256 and HKDF, for key
+derivation from a master secret, public-key fingerprinting and the hashing FIPS
+205 requires. It is declared directly rather than inherited, so the version in
+use is visible in this package's own manifest instead of resolved out of a
+transitive range. The 2022 Cure53 scope covered everything except `blake3`,
+`sha3-addons`, `sha1` and `argon2`; none of those four are used here.
+
+**`@noble/curves`** is not named anywhere in this package's source. It arrives
+through `@noble/post-quantum`, and it is on the hot path: `ml-dsa.js` takes
+`abool` from `@noble/curves/utils.js`, and `_crystals.js`, which both ML-DSA and
+ML-KEM are built on, takes `FFTCore` and `reverseBits` from
+`@noble/curves/abstract/fft.js`. So every signature and every encapsulation this
+package performs runs through it.
+
+That was established by the reachability walk, not by reading manifests. It is
+also the most heavily reviewed package in the tree: three independent firms
+across four years.
+
+**`@noble/ciphers`** arrives the same way and is the one package in the tree that
+nothing here reaches. It is present in `node_modules` and absent from every code
+path from every published entry point.
+
+## What the harness checks
+
+The review is a human document. The harness re-derives each of its mechanical
+claims from the lockfile, the registry and the installed tree, and exits non-zero
+on any disagreement:
+
+| Check | Source of truth |
+|---|---|
+| every dependency in the tree appears in the review | `package-lock.json` |
+| the review names nothing that has left the tree | `package-lock.json` |
+| the tree is within the declared ceiling of four | `package-lock.json` |
+| every direct dependency is pinned to an exact version | `package.json` |
+| no development dependencies | `package.json` |
+| each package is at the reviewed version | `package-lock.json` |
+| each licence is on the allowed list | `package-lock.json` |
+| no package declares an install script | lockfile flag and every installed manifest |
+| reachability matches the review, in both directions | static import walk |
+| no known advisories | `npm audit` |
+| no invalid registry signature or attestation anywhere | `npm audit signatures --json` |
+| no missing registry signature or attestation anywhere | `npm audit signatures --json` |
+
+The reachability check is bidirectional, and that matters. A package the review
+calls unused becoming reachable fails the build, and so does a package the review
+calls used becoming unreachable. The first version of the review recorded
+`@noble/curves` as unused; the harness rejected it, and the entry above is what
+replaced it.
+
+Adding or bumping a dependency fails this harness until somebody updates the
+review. That is the mechanism by which the document stays true, rather than being
+accurate on the day it was written.
+
+## How reachability is derived
+
+A breadth-first walk from all nine entry points in the `exports` map, reading
+every import, export-from, dynamic `import()` and `require()` specifier out of
+the source and resolving each with `import.meta.resolve` from the importing file.
+Using Node's own resolver means subpath exports, export maps and the `#native`
+conditional import resolve the way Node resolves them at run time.
+
+Both branches of `#native` are walked, because the Node backend and the browser
+stub both live in `src/`. The reported set is therefore the union of the Node and
+browser paths, which can only over-report what is reachable. Current figures: 33
+files walked, three packages reached, and one Node builtin, `node:crypto`, used
+by the OpenSSL backend.
+
+## Supply-chain posture in one paragraph
+
+Four packages, one publisher, all MIT, all exactly locked by integrity hash, all
+carrying registry signatures and SLSA provenance with nothing invalid or missing,
+none able to execute at install time, none carrying an advisory, three of four independently reviewed by named
+firms, and the fourth evidenced directly against NIST's vectors and three
+independent implementations in this repository. The whole tree is small enough
+that "all dependencies audited" is a statement someone can check in an afternoon,
+which is the only reason it is worth making.
+
+---
+
+## Correcting this document
+
+Every figure comes from `npm run audit:deps`. If one does not reproduce on your
+machine, that is a defect worth reporting through [SECURITY.md](SECURITY.md);
+include the generated `audit/results/dependencies.json` from your run.

package/LICENCE-PRODUCT.md

@@ -0,0 +1,90 @@
+# Licensing: what is free, what is paid
+
+Two different things share the KXCO name, and confusing them wastes everyone's time. This document draws the line.
+
+---
+
+## Free, and permanently so: the maths
+
+Apache-2.0. Use it commercially, fork it, ship it inside a product, never speak to us.
+
+| Package | What it does |
+|---|---|
+| [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum) | ML-DSA-65, ML-KEM-768, SLH-DSA, seed-form keys, compact JWS, deterministic derivation, kid fingerprints |
+| [`kxco-verify`](https://www.npmjs.com/package/kxco-verify) | Verify a site's deploy attestation, in a terminal or a browser |
+
+These are **chain-agnostic**. There is no chain id, no relay URL and no licence check anywhere in their source. They do not phone home. Signing and verification work with the network unplugged and keep working if KXCO stops existing, which is the only sense in which a signature is worth anything ten years from now.
+
+The other Apache-2.0 packages — `kxco-pq-attest`, `kxco-pq-audit`, `kxco-pq-hsm`, `kxco-pq-tls`, `kxco-pq-vault`, `kxco-post-quantum-webhook`, `kxco-pq-sdk`, `kxco-pq-agent`, `kxco-pq-chain`, `kxco-pq-network` — are also Apache-2.0 source. **The licence covers the code, not the service.** Reading and modifying the source is free. Calling the KXCO-operated registry and relay is not.
+
+---
+
+## Paid: the service
+
+What you buy is not cryptography. Cryptography is free, and we could not charge for it honestly if we wanted to.
+
+What you buy is **an answer about the present**.
+
+A signature made by a key that was revoked an hour ago is still a perfectly valid signature. No amount of offline mathematics can tell you it was revoked. Only something that knows what happened after the signature was made can, and that something has to be operated, kept available, and answerable when it is wrong.
+
+| Paid | Why it cannot be free |
+|---|---|
+| **Hosted key registry** (`chain.kxco.ai/kids/:kid`) | Answers whether a key is active, revoked or rotated. Someone has to run it and stand behind the answer |
+| **Meta-transaction relay** (`relay.kxco.ai`) | KXCO validates your signed intent, **pays the gas in ARMR**, and submits the transaction. You never hold a token or run a node |
+| **On-chain anchoring** | Writes to Armature L1, chain 1111111 |
+| **Live revocation** (`anchored+live`) | The registry lookup at verification time |
+| **Support and SLA** | Availability commitments, an escalation path, a name to call |
+
+Priced **in USD, per seat**. You do not need to hold ARMR, run a node, configure an RPC endpoint or touch a wallet. If a vendor tells you post-quantum identity requires you to buy a token, that is a different product from this one.
+
+See [`SALES-SKU.md`](https://github.com/KnightsbridgeAIQ/kxco-pq-network/blob/main/SALES-SKU.md) in `kxco-pq-network` for the seat definitions.
+
+---
+
+## Which mode you are in
+
+| Mode | Network at verify time | Licence | What it proves |
+|---|---|---|---|
+| `signature` | none | no | The holder of this key signed this |
+| `anchored` | none | no | …and it was written to Armature L1 |
+| `anchored+live` | yes, fails closed | **yes** | …and that key is still trusted **now** |
+
+`signature` and `anchored` will not start requiring a licence. Envelopes issued today verify in those modes forever, with no KXCO server in the path. That is a commitment about the format, not a pricing tier that may move.
+
+Writes to the hosted relay require a licence, and always did in substance — this is now enforced in the client rather than only at the server, so a misconfigured service fails at boot instead of at a customer's first transaction.
+
+---
+
+## Trademark
+
+The name **KXCO** and the mark **"KXCO Verified"** are not covered by the Apache-2.0 licence.
+
+You may fork the code, ship it, and say so. You may not describe your deployment as "KXCO Verified", or use the mark on a badge, a certificate, a report or a sales page, without a written agreement with us. The mark is meant to tell a reader that KXCO stands behind a specific claim, and it is worthless the moment anyone can apply it to themselves.
+
+Describing your product as "built on kxco-post-quantum" is fine and accurate. Describing it as "KXCO Verified" is not, unless it is.
+
+---
+
+## Assurance
+
+The cryptography is NIST-standardised and the conformance is published, pinned and reproducible.
+
+| | |
+|---|---|
+| Algorithms | ML-DSA-65 (FIPS 204), ML-KEM-768 (FIPS 203), SLH-DSA (FIPS 205) |
+| Backend | OpenSSL 3.5 where the runtime provides it, `@noble/post-quantum` elsewhere. Identical on the wire, checked in both directions |
+| Conformance | 2,103 NIST ACVP vectors across FIPS 203, 204 and 205. Vectors pinned by digest |
+| Interoperability | 225 checks against OpenSSL 3.5, liboqs, Bouncy Castle and dilithium-py/kyber-py |
+| Supply chain | SLSA provenance attestation on every release; CycloneDX SBOM; reproducible build |
+| Evidence bundle | `npm run evidence` regenerates all of it from source, on your machine |
+
+**You do not have to take any of it on our word.** Every figure above comes from a command you can run yourself against the same commit, and the vectors are NIST's, not ours. A customer may re-run them at any time without asking us and without telling us. If your result differs from ours we want to know: `john@knightsbridgelaw.com`, acknowledged within 2 business days.
+
+Dependency audit history — which upstream libraries were reviewed, by whom, and when — is recorded in [`AUDIT.md`](AUDIT.md), kept current by a generated dependency review rather than by hand.
+
+---
+
+## Support
+
+Commercial terms, seat pricing and SLA: **hello@kxco.ai**
+Security and vulnerability reports: **john@knightsbridgelaw.com**, or a private advisory on the relevant repository. Full policy, including safe harbour for good-faith research: <https://kxco.ai/security>

package/README.md

@@ -7,15 +7,18 @@ Post-quantum cryptography primitives for the KXCO stack.
 [![conformance](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/actions/workflows/conformance.yml/badge.svg)](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/actions/workflows/conformance.yml)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
 
-ML-DSA-65 (FIPS 204) and SLH-DSA-SHA2-192s (FIPS 205) signatures, ML-KEM-768 (FIPS 203) key encapsulation, and key fingerprinting utilities. Category 5 sets ML-DSA-87 and ML-KEM-1024 are also available. Wraps [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum). All other `kxco-pq-*` packages depend on this one.
+ML-DSA-65 (FIPS 204) and SLH-DSA-SHA2-192s (FIPS 205) signatures, ML-KEM-768 (FIPS 203) key encapsulation, and key fingerprinting utilities. Category 5 sets ML-DSA-87 and ML-KEM-1024 are also available. All other `kxco-pq-*` packages depend on this one.
+
+**On Node 24 and later the primitives run in OpenSSL 3.5**, not in JavaScript. Older Node and browsers use [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum). The two are interchangeable on the wire, which is checked rather than assumed: the interoperability matrix runs in full against both, and every report records which one produced it.
 
 **Evidence, not adjectives:**
 
 - [CONFORMANCE.md](./CONFORMANCE.md): NIST ACVP vectors for FIPS 203/204/205 (2,103 tests, 0 failed), and a cross-implementation interop matrix against liboqs, Bouncy Castle and two pure-Python implementations (225 checks, 0 failed, both directions, with negative controls), run against both backends. Reproducible: `npm run conformance:acvp`, `npm run conformance:interop`.
-- [BENCHMARKS.md](./BENCHMARKS.md): per-algorithm latency at p95/p99, plus memory. Two figures worth designing around: ML-DSA signing has a 4.5x tail between median and p99, and SLH-DSA-SHA2-192s signs in about 6.8 seconds.
+- [BENCHMARKS.md](./BENCHMARKS.md): per-algorithm latency at p95/p99 on both backends and on x86-64 and arm64, plus memory. Two figures worth designing around: ML-DSA signing keeps a rejection-sampling tail on either backend (5.1x median-to-p99 in JavaScript, 3.5x on OpenSSL), and SLH-DSA-SHA2-192s signs in seconds rather than milliseconds (4.3 s and 1.7 s).
 - [THREAT-MODEL.md](./THREAT-MODEL.md): what this defends against and what it does not. Read the side-channel section before deciding where a signing key lives.
 - [MIGRATION.md](./MIGRATION.md): moving an RSA or ECDSA system across, and moving between versions of this package.
-- [SECURITY.md](./SECURITY.md): reporting, and release integrity.
+- [SECURITY.md](./SECURITY.md): reporting, release integrity, and the dependency policy.
+- **Every release is reproducible and attested.** The published tarball rebuilds bit-for-bit from its own tag, verified in CI on every run, and each release carries a SLSA provenance attestation plus a CycloneDX SBOM at a permanent unauthenticated URL. A provenance attestation says a build happened in CI; the reproducible build says the artefact is the source. They are different claims and both are checkable without asking us for anything.
 
 ---
 
@@ -132,7 +135,7 @@ separation.
 
 | Export | Signature | Description |
 |---|---|---|
-| `keypairFromMaster` | `(master, info?) → { publicKey, secretKey }` | Deterministic keypair via HKDF-SHA-512. `info` defaults to `'ml-dsa-65-v1'`. |
+| `keypairFromMaster` | `(master, info?) → { publicKey, secretKey, seed }` | Deterministic keypair via HKDF-SHA-512. `info` defaults to `'ml-dsa-65-v1'`. `seed` is the 32 bytes the pair was expanded from — see [`seed`](#seed--seed-form-keys-rfc-9964-lamps). |
 | `sign` | `(secretKey, message) → string` | Signs a message. Returns a hex-encoded signature (6618 chars). |
 | `verify` | `(publicKey, message, sigHex) → boolean` | Verifies a hex-encoded signature. Returns `false` on any failure. |
 | `ml_dsa65` | raw primitive | The underlying `@noble/post-quantum` primitive, re-exported. |
@@ -156,7 +159,7 @@ Hash-based, stateless signatures. Security Category 3 (matching ML-DSA-65), but
 
 | Export | Signature | Description |
 |---|---|---|
-| `keypairFromMaster` | `(master, info?) → { publicKey, secretKey }` | Deterministic keypair via HKDF-SHA-512. `info` defaults to `'ml-kem-768-v1'`. |
+| `keypairFromMaster` | `(master, info?) → { publicKey, secretKey, seed }` | Deterministic keypair via HKDF-SHA-512. `info` defaults to `'ml-kem-768-v1'`. `seed` is the 64 bytes the pair was expanded from. |
 | `encapsulate` | `(publicKey) → { ciphertext, sharedSecret }` | Generates a shared secret and ciphertext to send to the key holder. |
 | `decapsulate` | `(ciphertext, secretKey) → Buffer` | Recovers the shared secret from a ciphertext. Returns 32 bytes. |
 | `ml_kem768` | raw primitive | The underlying `@noble/post-quantum` primitive, re-exported. |
@@ -175,6 +178,70 @@ Constant-time comparison of two kid strings. Use this when comparing user-suppli
 
 HKDF-SHA-512 derivation. `master` must be at least 16 bytes. `info` is a required domain-separation string. Returns `length` bytes.
 
+### `seed` — seed-form keys (RFC 9964, LAMPS)
+
+FIPS 203 and 204 expand a keypair from a short seed. The expanded private key
+this package returns is derived from that seed and does not contain it, so a
+seed cannot be recovered from an expanded key. `keypairFromMaster` therefore
+returns the seed it derived alongside the pair — additive, so callers that
+destructure `{ publicKey, secretKey }` are unaffected.
+
+Seed form is 32 bytes for ML-DSA and 64 for ML-KEM. It fits in a KMS secret, an
+HSM object or an env var, and it is the only private form an RFC 9964 AKP JWK
+accepts.
+
+| Export | Signature | Description |
+|---|---|---|
+| `SEED_ALGORITHMS` | `string[]` | `ML-DSA-65`, `ML-DSA-87`, `ML-KEM-768`, `ML-KEM-1024`. SLH-DSA has no seed form. |
+| `seedFromMaster` | `(alg, master, info?) → bytes` | Same HKDF-SHA-512 derivation `keypairFromMaster` uses, so it reproduces keys already in production. |
+| `keypairFromSeed` | `(alg, seed) → { publicKey, secretKey, seed }` | Expands a seed. Byte-identical to what OpenSSL 3.5 derives from the same seed. |
+| `exportJwk` | `(alg, { publicKey, seed? }, opts?) → jwk` | RFC 9964 AKP JWK. `priv` carries the seed. |
+| `importJwk` | `(jwk) → { alg, publicKey, secretKey?, seed? }` | Rejects a JWK whose seed and `pub` disagree. |
+| `exportSeedPkcs8` | `(alg, seed) → bytes` | PKCS#8 in LAMPS seed form, the `[0] IMPLICIT` CHOICE. |
+| `importSeedPkcs8` | `(der) → { alg, seed }` | Refuses an expanded-form key rather than truncating it into a seed. |
+
+The encodings are not read off the specification. `test/seed.test.js` asserts
+that the DER this package writes is byte-identical to what this machine's
+OpenSSL writes, for every parameter set, and skips with a reason where there is
+no native backend to compare against.
+
+```js
+import { mlDsa, seed } from 'kxco-post-quantum'
+
+const key = mlDsa.keypairFromMaster(process.env.KXCO_MASTER_KEY)
+const jwk = seed.exportJwk('ML-DSA-65', key, { kid: fingerprint(key.publicKey) })
+// { kty: 'AKP', alg: 'ML-DSA-65', pub: '...', priv: '<32-byte seed>', kid: '...' }
+```
+
+### `jws` — compact JWS with the RFC 9964 algorithm names
+
+Format only. A token signed here verifies in any process holding the public
+key, offline, with no configuration and no licence. RFC 9964 registered
+`ML-DSA-65` and `ML-DSA-87` as JWS algorithms so a post-quantum signature can
+travel the path an institution's gateway, IdP and partner verifier already
+parse.
+
+| Export | Signature | Description |
+|---|---|---|
+| `signJws` | `(payload, secretKey, opts?) → string` | Compact JWS. Objects are JSON-serialised. `opts.alg` defaults to `ML-DSA-65`. |
+| `verifyJws` | `(token, publicKey, opts?) → { valid, ... }` | Fails closed. `{ alg }` and `{ kid }` pin what the header may declare. |
+| `decodeJwsHeader` | `(token) → object \| null` | Unauthenticated read, for choosing which key to fetch. |
+
+The algorithm is resolved from an allowlist inside the module, never from the
+token, so a token cannot name its own verification routine. `crit` and `b64`
+headers are refused rather than ignored, and the public key's length must match
+the algorithm the header declares.
+
+There is no SLH-DSA option here: FIPS 205 signing takes on the order of a
+second and a half, which does not belong on a request path.
+
+### `backend()` and `isNative(alg)`
+
+Reports which implementation is doing the maths in this process — `openssl`
+with its version and parameter sets, or `javascript` with the reason the native
+backend is unavailable. For evidence bundles and support tickets. It reports;
+there is deliberately no way to switch backend from here.
+
 ### `webhook` — hybrid HMAC + ML-DSA-65 delivery signing
 
 Low-level helpers for the KXCO hybrid webhook pattern: `envelope`, `hmacHex`, `verifyHmac`, `pqSign`, `verifyPq`, `signDelivery`, `verifyDelivery`. HMAC-SHA-256 gives symmetric verification with no library dependency; ML-DSA-65 adds non-repudiation over the same `${timestamp}.${body}` envelope. The full identity/credential surface lives in `kxco-pq-sdk`.
@@ -186,7 +253,6 @@ Low-level helpers for the KXCO hybrid webhook pattern: `envelope`, `hmacHex`, `v
 - No identity credentials or verifiable claims (those are in `kxco-pq-sdk`)
 - No relay, transport, or network layer
 - No key storage or KMS integration
-- No FIPS 140-3 module validation (the algorithms are FIPS-standardised; the module is not validated)
 
 ---