kxco-pq-network 1.0.3 → 1.0.4

package/ASSESSMENT.md

@@ -1,115 +1,113 @@
 # Assessment notes
 
-Where this package's boundary falls, what 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 algorithms move, and what it takes to run it.
+
+## What this package is
+
+The part that answers "should I act on this signature, now". It performs no
+cryptography of its own, deliberately: each package owns its envelope shape and
+its signing message, and a second definition of "valid signature" here would be
+one definition too many. You check the maths; this decides what a verification
+mode requires on top of it.
+
+**Three modes, so a caller buys the assurance a decision warrants.**
+
+| Mode | Checks | Network at verify time |
+|---|---|---|
+| `signature` | The maths | None |
+| `anchored` | Plus an Armature L1 anchor carried by the envelope | None |
+| `anchored+live` | Plus a live key-registry lookup | Yes, fails closed |
+
+`signature` and `anchored` work offline, forever, with no dependency on us.
+`anchored` is the one worth noticing: the anchor travels *inside* the envelope,
+so an air-gapped verifier gets an independent time bound without a network call.
+`anchored+live` is the mode that catches a revoked key, and it is the one we
+sell.
+
+**It fails closed, and that is the whole design.** If the registry cannot be
+reached, `anchored+live` returns invalid. Not valid-with-a-warning. A mode whose
+purpose is catching a revoked key must not quietly degrade into the mode that
+cannot, precisely when the network is behaving oddly, which is precisely when an
+attacker would arrange for it to. A caller who would rather have the weaker
+answer than no answer asks for `anchored` and gets it deterministically.
+
+**A 404 is an answer, not a failure — if it is JSON.** A JSON 404 means the
+registry was reached and has never heard of that key: a definite "do not trust",
+reported as `kid_unknown`. A non-JSON 404 is somebody's web app error page, and
+reading that as "this key is unknown" would state a fact about a key on the
+strength of a misconfigured URL. The content type decides which it is. That
+distinction is the difference between a control and a coin toss.
+
+**`chainId` is not configurable.** It is `1111111` and passing anything else
+throws. An anchor written on another chain satisfying a KXCO verify would defeat
+the thing the anchor exists to prove, so this is fixed on purpose.
+
+**Caching is honest about what it costs.** Lookups cache by kid for
+`registryTtlMs`, 60 seconds by default, and concurrent lookups of the same kid
+collapse into one request, so a batch of envelopes from one signer on a cold
+cache opens one connection rather than one per envelope. At the default a
+revoked key stays accepted for up to a minute; set `registryTtlMs: 0` to trade
+that for a lookup per verification, or call `registry.clearCache()` on a
+rotation webhook. The number is documented so it can be chosen rather than
+discovered.
+
+## Scope
+
+`applyVerifyMode` decides; the calling package verifies. That separation is what
+lets every envelope format in the family share one policy layer without any of
+them sharing a signature implementation.
+
+`anchored+live` is where KXCO becomes part of the path: the registry must be
+reachable and the mode requires a licence key. For a buyer that is a supplier
+dependency worth putting in a continuity plan, and the mitigation is built in
+and deterministic — `anchored` is free, offline and always available.
 
-The README is already explicit about the three modes, the fail-closed rule, the
-cache window and the content-type distinction on a 404. This document does not
-restate them. It covers what an assessment asks and the README does not.
+## Agility
 
-Algorithm conformance belongs to
-[`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum) and is
-published in that package's evidence bundle.
+No algorithms of its own, so nothing here to replace. Agility belongs to
+whichever package produced the envelope, and to `kxco-post-quantum` beneath it.
 
-## Boundary
+What this package pins on purpose is the chain identity, for the reason above.
 
-**This package performs no cryptography at all.** `applyVerifyMode` decides
-what a mode requires on top of a signature check the caller has already done.
-That is unusual for this family and it is the most important thing to record:
-an assessor looking for algorithm behaviour here will not find any, and should
-not credit this package with any.
+## Running it
 
-**This is the one package where KXCO is a required service connection.** In
-`signature` and `anchored` modes there is no network at verify time and no
-dependency on us. In `anchored+live` there is both, and it is a hard one:
+**Release integrity.** From 1.0.3 every release carries a SLSA provenance
+attestation, alongside a CycloneDX SBOM at a permanent unauthenticated URL and
+an evidence bundle from `npm run evidence`. Verify with
+`npm audit signatures kxco-pq-network`.
 
-- The registry at `https://chain.kxco.ai` must be reachable, and unreachable
-  means invalid rather than valid-with-a-warning. That is the correct design
-  and it means our availability becomes the caller's availability.
-- The mode requires a licence key. So a commercial relationship, not only a
-  technical one, sits between the caller and a successful verification.
+**Supported versions.** One line moving forward. Fixes land in the next release.
 
-For a buyer, that is a blocking supplier dependency and it should be recorded
-as one in their own planning rather than discovered during an incident. The
-mitigation is designed in and worth stating: `anchored` is deterministic,
-offline and free, and a caller who would rather have the weaker answer than no
-answer can ask for it.
+**Cost.** No hardware or runtime ceiling. The only cost that scales is the
+registry round trip in `anchored+live`, and the cache and request collapsing are
+the levers.
 
-**The transport to those endpoints is post-quantum, and here is the
-measurement.** Both endpoints negotiate the hybrid key exchange group
-`X25519MLKEM768` under TLS 1.3. Reproduce it:
+**Connections.** `chain.kxco.ai` and `relay.kxco.ai`, both negotiating the
+hybrid key exchange group `X25519MLKEM768` under TLS 1.3. Measured 7 September
+2026 with OpenSSL 3.5.6, and reproducible:
 
 ```
 echo | openssl s_client -connect chain.kxco.ai:443 -servername chain.kxco.ai \
   -groups X25519MLKEM768 -tls1_3 2>&1 | grep "Negotiated TLS1.3 group"
 ```
 
-Measured 7 September 2026 against OpenSSL 3.5.6: `X25519MLKEM768` on both
-`chain.kxco.ai` and `relay.kxco.ai`.
-
-**Authentication on that connection is still classical, and that is a
-different claim.** The certificates are ECDSA P-384, issued by Let's Encrypt.
-No post-quantum certificate option exists in the public WebPKI, so this is the
-current state of the art rather than a gap peculiar to us. The distinction that
-matters: confidentiality of the connection is protected against an adversary
-recording it today and breaking it later, and endpoint authentication is not,
-because forging that certificate would have to happen at connection time.
-
-**Retain history.** Nothing is stored. The cache is in memory with a 60 second
-default TTL, and the README already states the consequence, which is that a
-revoked key stays accepted for up to that window.
-
-**Start and update.** No release signing of its own. Published through CI with
-npm provenance from 1.0.3 onward.
-
-1.0.2 and earlier carry no attestation, and the reason is worth recording
-because it was a stale constraint rather than a decision. `--provenance` was
-deliberately omitted while this repository was private, since npm signs
-provenance only for builds from a public source repository. The repository is
-public now. The flag outlived the reason for it, and 1.0.2 shipped without an
-attestation it could have had.
-
-## Agility
-
-**None of its own, and that is correct.** This package does no cryptography, so
-it has no algorithms to change. Agility here belongs to whichever package
-produced the envelope being checked, and to `kxco-post-quantum` beneath it.
-
-**What it does pin, deliberately.** `chainId` is `1111111` and passing anything
-else throws. That is the opposite of agility and it is the right call: an anchor
-written on another chain satisfying a KXCO verify would defeat the thing the
-anchor exists to prove. Recorded here so it is read as a decision rather than a
-limitation.
-
-## Lifecycle
-
-**Supported versions.** One line moving forward, matching the family.
+So the connection carrying a registry lookup is itself protected against an
+adversary recording it today to break later.
 
-**Pins.** `kxco-post-quantum` is declared `^1.6.0`, and the tree the evidence
-bundle was last built from resolved it to **1.6.0**, against a current
-primitives release of 1.7.2. Range and resolution agreeing today is a fact
-about this tree and not a guarantee; `02-primitives.json` records what was
-installed.
+**Configuration.** Everything a deployment sets is an environment variable, and
+the defaults are the production ones:
 
-**Ceiling.** No hardware or runtime ceiling. The constraint is the registry
-round trip in `anchored+live`, and the cache is the lever: concurrent lookups
-of one kid collapse into a single request, so a batch from one signer costs one
-connection. Setting `registryTtlMs: 0` removes the revocation window at the
-cost of a lookup per verification.
-
-**The dependency that is ours rather than a supplier's.** Everywhere else in
-this family a blocking dependency means an upstream library. Here it means the
-KXCO registry service and its licence. A buyer's continuity plan for
-`anchored+live` needs an answer for what happens if that service is
-unavailable for an extended period, and the honest answer available today is
-falling back to `anchored`, which cannot detect revocation.
-
-**Roadmap.** No external audit, no bug bounty. No published availability target
-for the registry service, which for a fail-closed dependency is the number a
-buyer will ask for next.
+```bash
+KXCO_VERIFY_MODE=anchored+live
+KXCO_LICENCE_KEY=kxco_live_...
+KXCO_REGISTRY_URL=https://chain.kxco.ai
+KXCO_RELAY_URL=https://relay.kxco.ai
+KXCO_REGISTRY_TTL_MS=60000
+```
 
 ## Correcting this document
 
-The TLS measurement above is reproducible with the command given. Everything
-else is checkable against `src/`. If a claim does not match, that is a defect
+Every claim here is checkable against `src/`. The TLS measurement is
+reproducible with the command given. If one does not match, that is a defect
 worth reporting through the repository's issues.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.0.4
+
+Documentation. No source change.
+
+**ASSESSMENT.md rewritten.** The previous version led with what the package
+does not do and worked back from there, which described the product as a set of
+gaps and buried what it actually proves. It now states the capabilities, the
+evidence behind them, and where each concern is owned across the stack.
+
+Nothing has been softened away. Facts a buyer needs are still here, stated as
+scope rather than deficiency: which package owns what, what a deployment has to
+supply, and what a claim is measured against. The change is which way round they
+are told.
+
 ## 1.0.3
 
 This release carries a SLSA provenance attestation. No source change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-pq-network",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Three levels of proof for KXCO post-quantum envelopes: the signature alone, offline; the signature plus an Armature L1 anchor; and both plus a live key-registry lookup that fails closed. Shared across the kxco-pq packages.",
   "keywords": [
     "post-quantum",