kxco-pq-network 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+## 1.0.0
+
+First release. This package is the boundary between what is free and what is
+sold, and it exists because that boundary needed a name.
+
+The maths stays free. `kxco-post-quantum` and `kxco-verify` are Apache-2.0,
+chain-agnostic, and work with the network unplugged. Nothing here changes that.
+
+What this adds is the answer to a question offline cryptography cannot answer:
+is this key still allowed to sign, today. A signature made by a key that was
+revoked an hour ago is still a perfectly valid signature, and a verifier that
+only checks the maths will accept it forever.
+
+### The three modes
+
+- `signature` — the maths. Offline, free, no server in the path.
+- `anchored` — plus an Armature L1 anchor carried by the envelope. Still no
+  HTTP at verify time, so an air-gapped verifier can check it.
+- `anchored+live` — plus a live registry lookup. Needs a licence.
+
+`applyVerifyMode` does no cryptography. Each package owns its own envelope
+shape and signing message, and a second definition of "valid signature" here
+would be one definition too many. The caller checks the maths and hands the
+outcome in.
+
+### It fails closed
+
+An unreachable registry makes `anchored+live` return **invalid**, not
+valid-with-a-warning. A mode whose entire purpose is to catch a revoked key
+must not degrade into the mode that cannot, precisely when the network is
+behaving oddly — which is precisely when an attacker would arrange for it to
+be.
+
+A **JSON** 404 is treated as an **answer**, not a failure: the registry was
+reached and has never heard of that key. That reports as `kid_unknown`, not
+`registry_unreachable`. The distinction is the whole design.
+
+A 404 that is not JSON is the opposite, and this was found by probing the live
+endpoint rather than by reasoning about it. `https://chain.kxco.ai/kids/<kid>`
+currently serves the marketing site's HTML 404 page, and an earlier draft of
+this client read that as a confident "this key is unknown" — stating a fact
+about a key on the strength of a misconfigured URL. The content type now
+decides which of the two a 404 is.
+
+### Caching, and what it costs
+
+Lookups are cached by kid for `registryTtlMs`, 60 seconds by default, and
+concurrent lookups of one kid collapse into a single request. **At the default,
+a revoked key stays accepted for up to a minute.** That is a real limit, it is
+stated in the README rather than buried, and `registryTtlMs: 0` or
+`clearCache()` trades it away.
+
+### Refusals
+
+`chainId` is not configurable. Anything but 1111111 throws at construction:
+accepting another chain would mean an anchor written elsewhere could satisfy a
+KXCO verify, which is the one thing the anchor exists to prove.
+
+A registry record whose kid does not match what was asked for is refused, using
+the constant-time comparison from `kxco-post-quantum`. A status this build does
+not recognise becomes `unknown` rather than passing through, so a status added
+in a later release cannot fall out of the "is it active" check as though it
+were active.
+
+### Metering
+
+`meter()` and `usageEvent()` emit structured records. They emit; they do not
+aggregate, invoice, or phone home. **The licence key is never emitted in full**
+— only its first 8 characters, which is enough to attribute an event and
+useless to whoever reads the log. The test suite asserts a full key never
+appears in a record.
+
+### Why a separate package
+
+`kxco-pq-sdk` already depends on `kxco-pq-attest`. Putting this module inside
+the SDK and having attest import it would make a dependency cycle. It is
+separate because it has to be, not for tidiness.
+
+### Not assessed
+
+No third party has assessed this code. `@noble/post-quantum`, reached through
+`kxco-post-quantum`, has been self-audited by its maintainer only — The other Noble packages have been audited, but separately and at different times: `@noble/hashes` by Cure53 in January 2022, `@noble/curves` by Trail of Bits in February 2023, Kudelski in September 2023 and Cure53 in September 2024, and `@noble/ciphers` by Cure53 in September 2024. None of those engagements covered the post-quantum package.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,184 @@
+# kxco-pq-network
+
+Verification modes for KXCO post-quantum envelopes.
+
+This package is the boundary between what is free and what is sold.
+
+The maths is free and stays free. `kxco-post-quantum` and `kxco-verify` are Apache-2.0, chain-agnostic, and work offline with no KXCO server anywhere in the path. Nothing here changes that.
+
+What this package adds is the answer to a question offline cryptography cannot answer: **is this key still allowed to sign, today?** A signature made by a key that was revoked an hour ago is still a perfectly valid signature. A verifier that only checks the maths will accept it forever.
+
+---
+
+## Install
+
+```bash
+npm install kxco-pq-network
+```
+
+Node 20.19+. ESM only.
+
+---
+
+## The three modes
+
+| Mode | Checks | Network at verify time | Licence |
+|---|---|---|---|
+| `signature` | The maths | None | No |
+| `anchored` | The maths, plus an Armature L1 anchor carried by the envelope | None | No |
+| `anchored+live` | Anchored, plus a live key-registry lookup | Yes, fails closed | **Yes** |
+
+`signature` is what `kxco-post-quantum` has always done. It works offline, forever.
+
+`anchored` additionally requires the envelope to carry chain id `1111111` and a transaction hash. The anchor travels inside the envelope, so an air-gapped verifier can check it. What it cannot tell you is whether the key is still good.
+
+`anchored+live` answers "should I act on this now". It needs a hosted registry, and that is the part we sell.
+
+```js
+import { networkConfigFromEnv, applyVerifyMode, FAILURE } from 'kxco-pq-network'
+import { verify } from 'kxco-pq-attest'
+
+const config = networkConfigFromEnv()             // reads KXCO_VERIFY_MODE etc.
+const signature = verify(envelope, publicKey)     // your own crypto check
+
+const result = await applyVerifyMode({
+  envelope,
+  signatureValid: signature.valid,
+  kid: envelope.kid,
+  config,
+})
+
+if (!result.valid) {
+  switch (result.reason) {
+    case FAILURE.SIGNATURE_INVALID:      // the document is not what it claims
+    case FAILURE.KID_REVOKED:            // valid signature, key no longer trusted
+    case FAILURE.REGISTRY_UNREACHABLE:   // we could not ask; see below
+  }
+}
+```
+
+`applyVerifyMode` does no cryptography. Each package owns its own envelope shape and signing message, and a second definition of "valid signature" here would be one definition too many. You check the maths; this decides what the mode requires on top of it.
+
+---
+
+## It fails closed
+
+If the registry cannot be reached, `anchored+live` returns **invalid**. Not valid-with-a-warning.
+
+A mode whose entire purpose is to catch 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 be. Callers who would rather have the weaker answer than no answer should ask for `anchored` and get it deterministically.
+
+A **JSON** `404` is treated as an **answer**, not a failure: the registry was reached and has never heard of that key. That is a definite "do not trust", and it is reported as `kid_unknown`, not `registry_unreachable`. The distinction is the whole design.
+
+A `404` that is **not** JSON is the opposite. Point `registryUrl` at a web app and you get that app's 404 page back, and reading a page of HTML as "this key is unknown" would state a fact about a key on the strength of a misconfigured URL. The content type decides which of the two it is.
+
+---
+
+## Caching, and what it costs you
+
+Lookups are cached by kid for `registryTtlMs`, 60 seconds by default. Concurrent lookups of the same kid collapse into one request, so a batch of envelopes from one signer arriving on a cold cache opens one connection, not one per envelope.
+
+**The limit this creates, stated plainly:** at the 60 second default, a revoked key stays accepted for up to a minute after revocation. Set `registryTtlMs: 0` to trade that for a lookup per verification, or call `registry.clearCache()` when you receive a rotation webhook.
+
+---
+
+## Configuration
+
+Everything a customer sets to go live:
+
+```bash
+KXCO_VERIFY_MODE=anchored+live
+KXCO_LICENCE_KEY=kxco_live_...
+KXCO_REGISTRY_URL=https://chain.kxco.ai     # default
+KXCO_RELAY_URL=https://relay.kxco.ai        # default
+KXCO_REGISTRY_TTL_MS=60000                  # default
+```
+
+`chainId` is not a configuration option. It is `1111111` and passing anything else throws. Accepting another chain would mean an anchor written somewhere else could satisfy a KXCO verify, which is the one thing the anchor exists to prove.
+
+---
+
+## Registry contract
+
+`GET /kids/:kid` on the registry base URL. `kid` is 16 lowercase hex characters.
+
+> **Status, 3 September 2026.** This endpoint is **implemented but not yet deployed**. The handler lives in `kxco-chain-live/explorer-public` (`src/pages/api/kids/[kid].js`, published at `/kids/:kid` by a rewrite) and reads the `KXCOIdentityRegistry` contract at `0x87776E97F981DdEF0b77469c67E222B106B94319` on chain 1111111. It is verified end to end against a scripted chain, including the `kxco-pq-network` client itself.
+>
+> Until it is deployed, `https://chain.kxco.ai/kids/<kid>` still serves the marketing site's HTML 404. The client detects that and reports `REGISTRY_UNREACHABLE` rather than reading it as "this key is unknown", so `anchored+live` fails closed against production and `anchored` is the strongest mode that works end to end today.
+
+```json
+{
+  "kid": "aa29f37ab7f4b2cf",
+  "publicKey": "<hex or jwk>",
+  "status": "active",
+  "rotatedTo": null,
+  "institutionId": "org_...",
+  "chainId": 1111111,
+  "asOfBlock": 1234567
+}
+```
+
+`status` is `active`, `revoked` or `rotated`. **Any value this build does not recognise is treated as `unknown`**, so a status added in a later release cannot fall out of the "is it active" check as though it were active.
+
+A record whose `kid` does not match what was asked for is refused. The comparison is constant-time. A registry that answers about a different key is either broken or being interposed, and either way its answer is unusable.
+
+The registry read is metered where a licence is configured and rate-limited where one is not. Reads without a licence are allowed — that is how the free path stays free.
+
+---
+
+## Metering
+
+`meter()` and `usageEvent()` emit structured events for `anchor_written`, `kid_registered`, `kid_revoked`, `kid_rotated`, `relay_post`, `registry_read` and `verify`.
+
+They emit; they do not aggregate, invoice, or phone home. The default sink is one JSON line on stdout, because that is what every log shipper already parses.
+
+**The licence key is never emitted in full.** Only the first 8 characters, which is enough to attribute an event and useless to anyone who reads the log. Logs get shipped to places the key was never meant to reach.
+
+---
+
+## Where this fits
+
+This decides what a verification mode *requires* on top of a signature check
+you have already performed. Keeping that decision separate from the
+cryptography is deliberate: policy changes without touching a signature path.
+
+- [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum) performs the signature check itself
+- [`kxco-pq-chain`](https://www.npmjs.com/package/kxco-pq-chain) performs relay writes
+
+## Why this is its own package
+
+`kxco-pq-sdk` already depends on `kxco-pq-attest`. Putting this module inside the SDK and having attest import it would make a dependency cycle. It is separate because it has to be, not for tidiness.
+
+---
+
+## 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.
+
+This package adds no cryptography of its own, so the evidence that matters is the
+base package's, and it is reproducible on your own machine:
+
+- **2,103 NIST ACVP vectors (0 failed)** across FIPS 203, 204 and 205, pinned by digest
+- **225 interoperability checks** against OpenSSL 3.5, liboqs, Bouncy Castle and dilithium-py/kyber-py, in both directions and with negative controls
+- **SLSA provenance** on every [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum) release — verify with `npm audit signatures kxco-post-quantum`
+- `npm run evidence` in that package regenerates the whole bundle from source
+
+Third-party dependencies here are pinned to exact versions, never ranges, so the
+code that performs the cryptography cannot change without a release.
+
+Dependency audit history is recorded in [AUDIT.md](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/blob/main/AUDIT.md).
+
+This package adds no cryptography of its own. It decides what a verification mode requires on top of a signature check the caller performed, and it fails closed: an unreachable registry returns invalid, never valid-with-a-warning.
+
+To report a vulnerability, email **security@kxco.ai**.
+
+---
+
+## License
+
+Apache-2.0. Use of the hosted registry, relay and anchoring service is governed separately — see `LICENCE-PRODUCT.md`.
+
+---
+
+## Maintainers
+
+Shayne Heffernan and John Heffernan — [KXCO by Knightsbridge](https://kxco.ai)

package/SALES-SKU.md

@@ -0,0 +1,134 @@
+# Seats and metering
+
+What is sold, how it is counted, and where in the code the counting happens.
+
+Prices are **USD, per seat, per year**, invoiced. No customer holds ARMR, runs a node, sets a gas price or touches a wallet. If that changes, this document is wrong and should be corrected rather than quietly reinterpreted.
+
+Commercial terms: **hello@kxco.ai**
+
+---
+
+## The line
+
+Free: the maths. `kxco-post-quantum` and `kxco-verify` are Apache-2.0, chain-agnostic, and work with the network unplugged. They keep working if KXCO stops existing.
+
+Paid: **an answer about the present.** A signature made by a key that was revoked an hour ago is still a perfectly valid signature. No offline check can tell you it was revoked. Only an operated service can, and only an operated service can be held to an answer.
+
+See [`LICENCE-PRODUCT.md`](https://github.com/KnightsbridgeAIQ/kxco-post-quantum/blob/main/LICENCE-PRODUCT.md).
+
+---
+
+## Seats
+
+### 1. Network seat
+
+The unit of subscription. One institution, one licence key.
+
+Entitles: registry reads at metered volume, `anchored+live` verification, relay writes, and the `KXCO Verified` mark under contract.
+
+Counted by `institutionId`. A licence key belongs to exactly one institution; sharing one across legal entities is what the contract prohibits, not what the code prevents.
+
+### 2. Anchor quota
+
+On-chain writes to Armature L1 — `anchorHash`, `anchorAuditRoot`, `anchorAttestation`.
+
+Each anchor is an EVM transaction whose gas KXCO pays in ARMR. That is a real cost per write, which is why this is a quota and not unlimited.
+
+Sold in blocks per year. Overage is invoiced, not blocked: a compliance anchor that fails because a counter rolled over is worse for the customer than an invoice.
+
+### 3. Agent kids
+
+Machine identities registered under an institution — `registerAgent` / `issueAgentCredential` for `llm`, `robot`, `iot` and `process` types.
+
+Counted as **distinct agent kids ever registered**, not concurrent. A kid revoked and replaced counts as two, because registering it consumed a chain write either way.
+
+### 4. Webhook verified
+
+Outbound deliveries signed with ML-DSA-65, and the optional compact-JWS path, from `kxco-post-quantum-webhook`.
+
+**Signing and verifying webhooks needs no licence.** The package is Apache-2.0 and does not call anything. What is sold here is the hosted key-rotation endpoint and the registry lookup that lets a receiver confirm a signing kid is still current, which is the part a receiver cannot do for themselves.
+
+### 5. SLA
+
+Availability commitment on `chain.kxco.ai` and `relay.kxco.ai`, an escalation path, and a named contact.
+
+Worth stating plainly: `anchored+live` **fails closed**. When the registry is unreachable, verification returns invalid. That is deliberate — a revocation check that quietly passes when it could not run is not a check — and it means registry availability is directly a customer's availability. That is what the SLA is for, and it is why a customer who cannot tolerate it should use `anchored`, which needs no registry at all.
+
+---
+
+## Metering hooks
+
+Billing is metered **server-side**. The relay and the registry are the source of truth, because a client-side counter is a counter the customer controls.
+
+The hooks below exist for the customer's own observability, and to reconcile an invoice against their own logs. They emit; they do not aggregate, invoice, or phone home.
+
+| Event | Emitted by |
+|---|---|
+| `relay_post` | `kxco-pq-chain`, on every relay write |
+| `anchor_written` | callers, on a successful anchor |
+| `kid_registered` | callers, on identity or agent registration |
+| `kid_revoked`, `kid_rotated` | callers, on revocation or rotation |
+| `registry_read` | `kxco-pq-network`, on a registry lookup |
+| `verify` | callers, per verification |
+
+Every record carries:
+
+```json
+{
+  "event": "relay_post",
+  "at": "2026-09-03T00:00:00.000Z",
+  "chainId": 1111111,
+  "operation": "anchorHash",
+  "institutionKid": "aa29f37ab7f4b2cf",
+  "kid": "bb29f37ab7f4b2cf",
+  "licencePrefix": "kxco_liv",
+  "txHash": "0x…",
+  "blockNumber": 90633
+}
+```
+
+**`licencePrefix` is the first 8 characters and never more.** Enough to attribute an event to a customer, useless to whoever reads the log. Logs get shipped to places the key was never meant to reach, and the test suites in both packages assert that a full licence key never appears in an emitted record.
+
+### Turning them on
+
+```js
+// kxco-pq-chain — off by default; a library should not write to your logs uninvited
+new KxcoChain({ identity, licenceKey, onUsageEvent: (e) => logger.info(e) })
+
+// kxco-pq-network — build a record, or emit one through your own sink
+import { meter, usageEvent } from 'kxco-pq-network'
+meter('registry_read', { institutionId, kid, licenceKey }, (r) => logger.info(r))
+```
+
+---
+
+## Going live
+
+Everything a customer sets:
+
+```bash
+KXCO_LICENCE_KEY=kxco_live_...          # required for relay writes and anchored+live
+KXCO_VERIFY_MODE=anchored+live          # or anchored, or signature
+KXCO_REGISTRY_URL=https://chain.kxco.ai # default
+KXCO_RELAY_URL=https://relay.kxco.ai    # default
+KXCO_REGISTRY_TTL_MS=60000              # default
+```
+
+A missing licence throws at **construction**, not at the first write. A service that boots looking healthy and fails on a customer's first transaction has already told someone their onboarding succeeded.
+
+`KXCO_LICENSE_KEY` is accepted as well, because half the world spells it that way and a failed deployment over a vowel helps nobody.
+
+---
+
+## What the buyer is getting
+
+- **A named counterparty.** Four known validators under QBFT proof-of-authority, an operator with a legal entity behind it, and a contract. The question a supervisor asks — who approved this — has an answer here and does not on a permissionless chain.
+- **On-chain post-quantum verification.** Armature L1 verifies ML-DSA-65 in consensus at precompile `0x0b`, executed by every validator, ~50,000 gas.
+- **Category 5 available today.** ML-DSA-87 and ML-KEM-1024, the parameter sets CNSA 2.0 specifies, shipped and ACVP-checked.
+- **Evidence, not assertions.** 2,103 NIST ACVP vectors, a 225-check interoperability matrix, SLSA provenance and a CycloneDX SBOM on every release — all reproducible by the customer.
+
+## What is not sold
+
+- **Not the cryptography.** It is Apache-2.0 and it is not going to stop being.
+- **Not a token.** No ARMR to buy, no wallet, no gas.
+- **Not an audit.** What is sold is the operated service. The cryptographic evidence — ACVP vectors, the interoperability matrix, provenance, SBOM — is published and free to re-run; see the `evidence` job in `kxco-post-quantum`.

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "kxco-pq-network",
+  "version": "1.0.0",
+  "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 by kxco-pq-sdk, kxco-pq-attest, kxco-post-quantum-webhook and kxco-pq-agent.",
+  "keywords": [
+    "post-quantum",
+    "pqc",
+    "ml-dsa",
+    "verification",
+    "revocation",
+    "key-registry",
+    "anchoring",
+    "armature",
+    "kxco",
+    "identity",
+    "compliance",
+    "fail-closed"
+  ],
+  "license": "Apache-2.0",
+  "author": "Shayne Heffernan and John Heffernan",
+  "contributors": [
+    {
+      "name": "Shayne Heffernan"
+    },
+    {
+      "name": "John Heffernan"
+    }
+  ],
+  "homepage": "https://kxco.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KnightsbridgeAIQ/kxco-pq-network.git"
+  },
+  "bugs": {
+    "url": "https://github.com/KnightsbridgeAIQ/kxco-pq-network/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "SALES-SKU.md",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "kxco-post-quantum": "^1.6.0"
+  },
+  "scripts": {
+    "test": "node --test --test-timeout=30000 test/network.test.js test/registry.test.js"
+  },
+  "funding": "https://kxco.ai",
+  "publishConfig": {
+    "access": "public"
+  }
+}