kxco-verify 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 1.3.0
+
+Additive. The library is byte-for-byte unchanged: same one dependency, same
+offline behaviour, no notion of a chain anywhere in `src/`.
+
+### A command line
+
+`npx kxco-verify <url>` fetches and verifies an attestation, with `--file` for
+a manifest you already have and `--json` for CI. Exit codes: 0 valid, 1 invalid
+or revoked, 2 fetch or parse error, 3 rotated.
+
+The default path contacts nothing but the site being checked. No KXCO server,
+no licence, no account. That is what this package is for and it is not
+changing.
+
+### `--live`
+
+Asks the KXCO key registry whether the signing kid is still active, after the
+maths has passed. A signature made by a key revoked an hour ago is still a
+perfectly valid signature, and no offline check can tell you otherwise.
+
+It **fails closed**: an unreachable registry means not valid. A check that
+could not run has not passed.
+
+It needs `kxco-pq-network`, declared as an **optional** peer dependency so it
+is not installed by default. Without it the flag prints what to install and
+exits 2; everything else is unaffected. This is deliberate: making it a real
+dependency would put a chain-aware package in the install path of a library
+whose whole claim is that it has neither.
+
+The registry is asked only once the signature has verified. A forged manifest
+is a forged manifest whatever the registry says about the key it names, and
+reporting it as a revocation would mislead.
+
 ## 1.2.1
 
 Released to carry an npm provenance attestation. **No functional change**: no

package/README.md

@@ -55,7 +55,56 @@ If you need to **sign** attestations, see the packages listed under [Part of the
 npm install kxco-verify
 ```
 
-Node 18+. ESM only.
+Node 18+. ESM only. One dependency, and no KXCO server in the trust path.
+
+---
+
+## Command line
+
+```bash
+npx kxco-verify https://example.com/.well-known/kxco-pq-attestation
+```
+
+```
+VALID  example.com
+  algorithm    ML-DSA-65
+  kid          aa29f37ab7f4b2cf
+
+This means the site signed its own manifest with a key it published.
+It is not an endorsement of the site, its owner, or its content.
+```
+
+`--file <path>` verifies a manifest you already have. `--json` prints a machine-readable result.
+
+Exit codes are meant for CI: **0** valid, **1** invalid or revoked, **2** could not fetch or parse, **3** rotated.
+
+### `--live`
+
+A signature made by a key that was revoked an hour ago is still a perfectly valid signature. The maths cannot tell you so. `--live` asks the KXCO key registry whether the signing kid is still active:
+
+```bash
+npx kxco-verify https://example.com/.well-known/kxco-pq-attestation --live
+```
+
+```
+VALID  example.com
+  kid          aa29f37ab7f4b2cf
+  registry     revoked
+```
+
+That exits **1**. The signature is still valid; the key is not trusted any more, and those are different facts.
+
+`--live` **fails closed**: if the registry cannot be reached, the result is not valid. A check that could not run has not passed.
+
+It needs [`kxco-pq-network`](https://www.npmjs.com/package/kxco-pq-network), an **optional** peer dependency. It is not installed by default and nothing else here needs it — install it only if you want the flag:
+
+```bash
+npm install kxco-pq-network
+```
+
+Registry base URL defaults to `https://chain.kxco.ai` and can be changed with `--registry`. A licence key, via `--licence` or `KXCO_LICENCE_KEY`, meters the reads; reads without one are allowed and rate-limited.
+
+Everything above the `--live` heading works offline, forever, with no account and no licence. That is not changing.
 
 ---
 
@@ -254,7 +303,7 @@ The verifier is architecturally independent of the signer — the two share no c
 
 ## Security
 
-Signature verification uses [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) ML-DSA-65, with no transitive dependencies. That package has **not** been independently audited by a third party; it has been self-audited by its maintainer. Cure53's 2023 NDS-01 audit of the `@noble` ecosystem covered `ciphers`, `curves` and `hashes`, and did not cover `@noble/post-quantum`. We state this plainly because you should not adopt a verification library on the strength of an audit that does not exist.
+Signature verification uses [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) ML-DSA-65, with no transitive dependencies. That package has **not** been independently audited by a third party; it has been self-audited by its maintainer. 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. We state this plainly because you should not adopt a verification library on the strength of an audit that does not exist.
 
 The library makes no outbound requests beyond the attestation URL you supply and the `pinAt` endpoint declared in the manifest. No data is sent to KXCO.
 

package/bin/kxco-verify.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// kxco-verify — check a site's post-quantum deploy attestation from a terminal.
+//
+// The default is the whole point of this package: the maths, and nothing else.
+// No KXCO server is contacted, no licence is needed, no account exists. It
+// fetches the manifest the site publishes and checks the signature against the
+// key the site published. That path must keep working forever, offline, for
+// anyone, which is why the library this CLI wraps has one dependency and no
+// notion of a chain.
+//
+// `--live` is the other thing. A signature made by a key that was revoked an
+// hour ago is still a perfectly valid signature, and the maths cannot tell you
+// so. `--live` asks the KXCO key registry whether the kid is still active.
+// That needs kxco-pq-network, which is an OPTIONAL peer: install it and the
+// flag works, leave it out and everything else is unaffected.
+//
+// Exit codes are meant for CI:
+//   0  valid
+//   1  invalid, or revoked under --live
+//   2  could not reach or parse the target
+//   3  rotated (the signature checks, but the live key differs)
+
+import { verifyUrl, verifyManifest } from '../src/index.js'
+import { readFileSync } from 'node:fs'
+
+const ANSI = process.stdout.isTTY
+  ? { reset: '\x1b[0m', bold: '\x1b[1m', green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m', dim: '\x1b[2m' }
+  : { reset: '', bold: '', green: '', yellow: '', red: '', dim: '' }
+
+const USAGE = `
+kxco-verify — verify a post-quantum deploy attestation
+
+  kxco-verify <url>                    fetch and verify. No KXCO server involved.
+  kxco-verify --file <path>            verify a manifest you already have
+  kxco-verify <url> --live             also ask the registry whether the key is still active
+  kxco-verify <url> --json             machine-readable output
+
+Options
+  --live                  check the signing kid against the KXCO key registry.
+                          Needs kxco-pq-network installed. Fails CLOSED: if the
+                          registry cannot be reached, the result is not valid.
+  --registry <url>        registry base URL (default https://chain.kxco.ai)
+  --licence <key>         licence key for the registry, or set KXCO_LICENCE_KEY
+  --timeout <ms>          network timeout (default 10000)
+  --json                  print JSON instead of a human summary
+  --help
+
+Exit codes
+  0 valid    1 invalid or revoked    2 fetch/parse error    3 rotated
+`.trimStart()
+
+function parseArgs(argv) {
+  const opts = { live: false, json: false, timeout: 10_000, registry: undefined, licence: undefined, file: undefined }
+  const positional = []
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    switch (arg) {
+      case '--help': case '-h': opts.help = true; break
+      case '--live': opts.live = true; break
+      case '--json': opts.json = true; break
+      case '--file': opts.file = argv[++i]; break
+      case '--registry': opts.registry = argv[++i]; break
+      case '--licence': case '--license': opts.licence = argv[++i]; break
+      case '--timeout': opts.timeout = Number(argv[++i]); break
+      default:
+        if (arg.startsWith('-')) throw new Error(`unknown option ${arg}`)
+        positional.push(arg)
+    }
+  }
+  opts.url = positional[0]
+  return opts
+}
+
+// Loaded only when --live is asked for, so the default path has no chance of
+// reaching for a package that may not be installed.
+async function loadNetwork() {
+  try {
+    return await import('kxco-pq-network')
+  } catch {
+    throw new Error(
+      '--live needs kxco-pq-network, which is an optional peer dependency.\n' +
+      '  npm install kxco-pq-network\n' +
+      'Without it, kxco-verify still checks the signature offline, which is what it is for.',
+    )
+  }
+}
+
+async function checkLive(kid, opts) {
+  const { networkConfig, KeyRegistry, KxcoPqNetworkError } = await loadNetwork()
+  const config = networkConfig({
+    registryUrl: opts.registry,
+    licenceKey: opts.licence ?? process.env.KXCO_LICENCE_KEY ?? null,
+    timeoutMs: opts.timeout,
+  })
+  try {
+    return { ok: true, record: await new KeyRegistry(config).lookup(kid) }
+  } catch (err) {
+    if (!(err instanceof KxcoPqNetworkError)) throw err
+    // Fails closed. A check that cannot run has not passed.
+    return { ok: false, error: err.message }
+  }
+}
+
+function render(result, live, opts) {
+  if (opts.json) {
+    console.log(JSON.stringify({ ...result, live }, null, 2))
+    return
+  }
+
+  const colour = { valid: ANSI.green, rotated: ANSI.yellow }[result.state] ?? ANSI.red
+  console.log(`${ANSI.bold}${colour}${result.state.toUpperCase()}${ANSI.reset}  ${result.site ?? result.attestationUrl ?? ''}`)
+  if (result.algorithm) console.log(`  algorithm    ${result.algorithm}`)
+  if (result.manifestKid) console.log(`  kid          ${result.manifestKid}`)
+  if (result.livePubkeyKid && result.livePubkeyKid !== result.manifestKid) {
+    console.log(`  live kid     ${result.livePubkeyKid}`)
+  }
+  if (result.error) console.log(`  ${ANSI.dim}${result.error.message}${ANSI.reset}`)
+
+  if (live) {
+    const label = live.ok ? live.record.status : 'unreachable'
+    const c = live.ok && live.record.status === 'active' ? ANSI.green : ANSI.red
+    console.log(`  registry     ${c}${label}${ANSI.reset}${live.ok && live.record.cached ? ' (cached)' : ''}`)
+    if (!live.ok) console.log(`  ${ANSI.dim}${live.error}${ANSI.reset}`)
+    if (live.ok && live.record.rotatedTo) console.log(`  rotated to   ${live.record.rotatedTo}`)
+  }
+
+  // A valid result means one thing, and people read more into it than it says.
+  if (result.state === 'valid') {
+    console.log(`\n${ANSI.dim}This means the site signed its own manifest with a key it published.`)
+    console.log(`It is not an endorsement of the site, its owner, or its content.${ANSI.reset}`)
+  }
+}
+
+async function main() {
+  let opts
+  try {
+    opts = parseArgs(process.argv.slice(2))
+  } catch (err) {
+    console.error(err.message)
+    process.exit(2)
+  }
+
+  if (opts.help || (!opts.url && !opts.file)) {
+    console.log(USAGE)
+    process.exit(opts.help ? 0 : 2)
+  }
+
+  let result
+  if (opts.file) {
+    result = await verifyManifest(readFileSync(opts.file, 'utf8'))
+  } else {
+    result = await verifyUrl(opts.url, { timeoutMs: opts.timeout })
+  }
+
+  if (result.state === 'error') {
+    render(result, null, opts)
+    process.exit(2)
+  }
+
+  // The registry is only asked once the maths has passed. A forged manifest is
+  // a forged manifest whatever the registry says about the key it names, and
+  // reporting it as a revocation would mislead.
+  let live = null
+  if (opts.live && result.state !== 'invalid') {
+    try {
+      live = await checkLive(result.manifestKid, opts)
+    } catch (err) {
+      console.error(err.message)
+      process.exit(2)
+    }
+  }
+
+  render(result, live, opts)
+
+  if (result.state === 'invalid') process.exit(1)
+  if (live && (!live.ok || live.record.status !== 'active')) process.exit(1)
+  if (result.state === 'rotated') process.exit(3)
+  process.exit(0)
+}
+
+main().catch((err) => {
+  console.error(err.stack ?? err.message)
+  process.exit(2)
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxco-verify",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Standalone, browser-safe verifier for KXCO ML-DSA-65 post-quantum signed attestations and credentials, for auditors, regulators, counterparties, and anyone who needs to confirm a signature without running the full KXCO SDK.",
   "keywords": [
     "post-quantum",
@@ -63,10 +63,11 @@
     }
   },
   "files": [
-    "src",
-    "README.md",
+    "CHANGELOG.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "README.md",
+    "bin",
+    "src"
   ],
   "engines": {
     "node": ">=20.19"
@@ -83,5 +84,16 @@
   "publishConfig": {
     "provenance": true,
     "access": "public"
+  },
+  "bin": {
+    "kxco-verify": "bin/kxco-verify.js"
+  },
+  "peerDependencies": {
+    "kxco-pq-network": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "kxco-pq-network": {
+      "optional": true
+    }
   }
 }