kxco-verify 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The
+format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-05-22
+
+Initial release. Phase 1 of the [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum) evolution brief.
+
+### Added
+- `verifyManifest(input)` — verify an attestation manifest object or JSON string. Returns the 3-state result envelope (`valid` / `invalid` / `error`).
+- `verifyUrl(url, opts?)` — fetch and verify an attestation by URL. May additionally return `rotated` when the live well-known endpoint serves a different kid than the manifest declared.
+- `parseManifest(input)` — typed-ish parser with byte-count sanity for ML-DSA-65 publicKey (1952 bytes) and signature (3309 bytes).
+- `verifySignature(publicKey, message, signature)` — ML-DSA-65 (NIST FIPS 204) verification via `@noble/post-quantum`.
+- `computeKid(publicKey)` — first 16 hex chars of SHA-256(rawPubkeyBytes). Matches the algorithm used by `kxco-post-quantum`'s `fingerprint()`.
+- `getJsonBody(url, opts?)` — fetch helper with timeout (default 3000ms), max-byte cap (default 200KB), and SSRF-aware URL validation.
+- Browser-safe implementation throughout — no `Buffer`, no `node:crypto`, no `process`. Uses `crypto.subtle` where available, falls back to `node:crypto` on Node 18.
+- Live production fixtures captured in `fixtures/` for `chain.kxco.ai/wallet` and `www.target150.com`.
+- Test suite: 50 tests, 97.5%+ line coverage, includes adversarial cases (signature tampering, kid mismatch, malformed JSON, byte-length attacks).
+- Smoke script (`npm run smoke`) that exercises both production endpoints end-to-end.
+
+### Known limitations (deliberately deferred to later phases)
+- No KXCO-controlled key registry. Verification is a math claim only.
+- No SLH-DSA-128s or hybrid envelopes — ML-DSA-65 only.
+- No transparency log.
+- The browser app at `verify.kxco.ai` is gated by CORS on the target site. Sites that don't serve `Access-Control-Allow-Origin: *` on their attestation endpoint require the "paste the JSON" fallback path.
+
+### License
+Apache 2.0. Independent of the (MIT-licensed) `kxco-post-quantum` signer.
+
+[0.1.0]: https://github.com/JackKXCO/kxco-verify/releases/tag/v0.1.0

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,163 @@
+# kxco-verify
+
+[![npm](https://img.shields.io/npm/v/kxco-verify?label=npm&color=b0964f)](https://www.npmjs.com/package/kxco-verify)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
+[![verify.kxco.ai](https://img.shields.io/badge/verify.kxco.ai-live-22c55e)](https://verify.kxco.ai)
+
+**Independent, browser-safe verifier for post-quantum signed deploy attestations** produced by sites using [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum).
+
+Zero runtime dependencies beyond [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum). Apache 2.0. Works the same in Node 18+ and in any modern browser — the library never imports anything Node-specific. The public [`verify.kxco.ai`](https://verify.kxco.ai) web app runs this exact library entirely client-side; nothing is sent to a KXCO server.
+
+> **Read this before you use the result.** A `"valid"` result means the signature math checks out against the public key the site itself declared, AND that key currently matches the live well-known endpoint. **It does not mean KXCO has vetted the site, its operator, or its content.** A self-signed attestation from a brand-new domain looks the same as one from a real institution — that's the point of cryptography, not a bug in the verifier. See [`docs/threat-model.md`](./docs/threat-model.md) for what is and isn't proven.
+
+---
+
+## Install
+
+```bash
+npm install kxco-verify
+```
+
+Node ≥18. ESM only.
+
+## Quick start
+
+### Verify a URL
+
+```js
+import { verifyUrl } from 'kxco-verify'
+
+const r = await verifyUrl('https://www.target150.com/api/attestation')
+
+console.log(r.state)         // 'valid' | 'rotated' | 'invalid' | 'error'
+console.log(r.algorithm)     // 'ML-DSA-65'
+console.log(r.manifestKid)   // '680f9af0bb44de3f'
+console.log(r.deployment)    // { git_commit: '...', env: 'production', ... }
+```
+
+### Verify a manifest you already have
+
+```js
+import { verifyManifest } from 'kxco-verify'
+
+const body = await fetch('https://www.target150.com/api/attestation').then(r => r.text())
+const r    = await verifyManifest(body)
+```
+
+### CLI smoke against the production endpoints
+
+```bash
+npx kxco-verify-smoke
+# or, if cloned locally:
+npm run smoke
+```
+
+---
+
+## The 3-state result
+
+This is the single most important thing to understand before consuming this library.
+
+| `state` | What it means | What it does not mean |
+|---|---|---|
+| `"valid"`   | Signature mathematically checks out against the manifest-declared key, AND that key matches the live `pinAt` well-known endpoint. | That the site is trustworthy, that KXCO endorses it, or that its content is what it claims to be. |
+| `"rotated"` | Signature checks out against the kid the manifest declared, but the well-known endpoint now serves a different kid. The site is mid key-rotation. Retry shortly. | That the site is compromised. |
+| `"invalid"` | The signature does NOT verify under the manifest's declared key, OR the kid does not match SHA-256 of the published pubkey bytes. | Necessarily that the site is malicious — could also be a misconfigured signer or tampering in flight. |
+| `"error"`   | The verifier could not run (network failure, malformed JSON, unsupported algorithm). | That the signature is invalid. |
+
+The full shape returned by `verifyUrl` / `verifyManifest` is documented in [`src/index.d.ts`](./src/index.d.ts).
+
+---
+
+## What the library does NOT do (yet)
+
+Tracked for later phases of [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum):
+
+- **No KXCO-controlled key registry.** There is no mapping from `domain → approved kid`. Anyone can generate an ML-DSA-65 keypair in 30 seconds and publish a self-signed manifest; this library will mark it `"valid"`. That is intentional for this release — verification is a math claim, not an endorsement. Future phases will add a registry; the verifier will then surface registry-status alongside the math result.
+- **No SLH-DSA-128s or hybrid envelopes.** ML-DSA-65 (NIST FIPS 204) only.
+- **No transparency log.** Whether a given attestation has been publicly seen before is not tracked here.
+
+If your threat model requires any of the above, do not call a `"valid"` result a "trust verdict" in your UI without your own additional checks.
+
+---
+
+## Browser usage
+
+The library is browser-safe by construction — no `Buffer`, no `node:crypto`, no `process`. SHA-256 is taken from `crypto.subtle` where available (every browser, Node 20+) and falls back to `node:crypto` on Node 18.
+
+Use a bundler (Vite, esbuild, Rollup, webpack) or load as ESM directly via an import map:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "@noble/post-quantum/ml-dsa": "/lib/@noble/post-quantum/ml-dsa.js",
+    "kxco-verify":                "/lib/kxco-verify/src/index.js"
+  }
+}
+</script>
+<script type="module">
+  import { verifyUrl } from 'kxco-verify'
+  const r = await verifyUrl('https://example.com/api/attestation')
+  console.log(r.state)
+</script>
+```
+
+This is exactly what [`verify.kxco.ai`](https://verify.kxco.ai) does.
+
+---
+
+## Manifest shape
+
+The verifier accepts the manifest shape produced by `kxco-post-quantum` since v1.0.x. The reference document is [`docs/verification.md`](./docs/verification.md). In brief:
+
+```json
+{
+  "manifest": {
+    "site": "example.com",
+    "alg":  "ML-DSA-65",
+    "spec": "NIST FIPS 204",
+    "kid":  "<16 hex chars>",
+    "deployment": { "<opaque-site-defined-fields>": "..." },
+    "msgFormat":  "<template describing what was signed>"
+  },
+  "signedMessage": "<the actual bytes that were signed, as a string>",
+  "signature": { "alg": "ML-DSA-65", "encoding": "hex", "value": "<6618 hex chars>" },
+  "publicKey": {
+    "alg": "ML-DSA-65", "encoding": "hex", "value": "<3904 hex chars>",
+    "kid": "<same as manifest.kid>",
+    "pinAt": "<relative URL of the live well-known pubkey endpoint>"
+  }
+}
+```
+
+Two live, real-world examples ship in [`fixtures/`](./fixtures):
+- `wallet-attestation.json`    — `https://chain.kxco.ai/wallet/api/.well-known/kxco-pq-attestation`
+- `target150-attestation.json` — `https://www.target150.com/api/attestation`
+
+The test suite verifies the math against both.
+
+---
+
+## Stability + versioning
+
+- **v0.1.x:** initial release. The 3-state result envelope is the public API; new states will be added only on a major bump. New optional fields on the result object are non-breaking.
+- **No telemetry.** The library makes only the HTTP requests you ask it to (the attestation URL + the publisher-declared `pinAt`). No KXCO endpoint is contacted.
+- **Reproducible builds + SLSA provenance.** Every published version of this package carries an npm provenance attestation showing the exact commit and GitHub Actions workflow that produced it. Verify with `npm view kxco-verify --json | jq .dist.attestations`.
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](./LICENSE).
+
+This library is deliberately permissively licensed and architecturally independent of the (MIT-licensed) [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum) signer. The two never share code. That separation makes the verifier auditable in isolation: a change to the signer cannot trick the verifier into trusting an unverified key.
+
+---
+
+## See also
+
+- [`kxco-post-quantum`](https://www.npmjs.com/package/kxco-post-quantum) — the production-tested signing library used by KnightsVault, KXCO Bank, target150, and others
+- [`verify.kxco.ai`](https://verify.kxco.ai) — public web verifier (runs this library client-side)
+- [`docs/verification.md`](./docs/verification.md) — full end-to-end verification flow
+- [`docs/threat-model.md`](./docs/threat-model.md) — what this library does and does not protect against

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "kxco-verify",
+  "version": "0.1.0",
+  "description": "Independent, browser-safe verifier for KXCO post-quantum signed deploy attestations. Verifies ML-DSA-65 (NIST FIPS 204) signatures emitted by sites that use kxco-post-quantum. No trust delegation: this library tells you whether the signature math checks out and whether the manifest-declared key matches the live well-known endpoint — it does NOT vouch for any site.",
+  "keywords": [
+    "post-quantum",
+    "pqc",
+    "ml-dsa",
+    "dilithium",
+    "nist",
+    "fips-204",
+    "verification",
+    "attestation",
+    "verify",
+    "kxco-post-quantum"
+  ],
+  "license": "Apache-2.0",
+  "author": "KXCO by Knightsbridge <hello@kxco.ai>",
+  "homepage": "https://verify.kxco.ai",
+  "funding": "https://kxco.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JackKXCO/kxco-verify.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JackKXCO/kxco-verify/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types":  "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./parse": {
+      "types":  "./src/parse.d.ts",
+      "import": "./src/parse.js"
+    },
+    "./verify": {
+      "types":  "./src/verify.d.ts",
+      "import": "./src/verify.js"
+    },
+    "./fetch": {
+      "types":  "./src/fetch.d.ts",
+      "import": "./src/fetch.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@noble/post-quantum": "^0.2.1"
+  },
+  "scripts": {
+    "test":       "node --test --test-reporter=spec test/parse.test.js test/verify.test.js test/fetch.test.js test/index.test.js",
+    "test:cov":   "node --test --experimental-test-coverage test/parse.test.js test/verify.test.js test/fetch.test.js test/index.test.js",
+    "smoke":      "node scripts/smoke.js",
+    "lint":       "node -c src/index.js && node -c src/parse.js && node -c src/verify.js && node -c src/fetch.js"
+  },
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
+  }
+}

package/src/fetch.d.ts

@@ -0,0 +1,28 @@
+export interface FetchOk {
+  ok: true
+  url: string
+  status: number
+  body: string
+}
+
+export interface FetchErr {
+  ok: false
+  error: {
+    kind: 'fetch'
+    code: 'no_fetch' | 'invalid_url' | 'timeout' | 'network' | 'http_status' | 'too_large' | 'read'
+    message: string
+    url?: string
+    status?: number
+  }
+}
+
+export interface GetJsonBodyOpts {
+  timeoutMs?: number
+  maxBytes?: number
+  fetchImpl?: typeof fetch
+}
+
+export function getJsonBody(
+  url: string,
+  opts?: GetJsonBodyOpts,
+): Promise<FetchOk | FetchErr>

package/src/fetch.js

@@ -0,0 +1,100 @@
+// Network fetching. Browser-safe (uses global `fetch`), with a hard timeout
+// per request via AbortController so a slow target site cannot hang the
+// verifier. Returns either { ok: true, body, url, status } or
+// { ok: false, error: { kind: 'fetch', code, message } }.
+
+const DEFAULT_TIMEOUT_MS = 3000
+const DEFAULT_MAX_BYTES  = 200_000   // attestation manifests are ~11KB; cap at 200KB
+
+/**
+ * @typedef {Object} FetchOk
+ * @property {true}    ok
+ * @property {string}  url
+ * @property {number}  status
+ * @property {string}  body
+ *
+ * @typedef {Object} FetchErr
+ * @property {false}  ok
+ * @property {{ kind: 'fetch', code: string, message: string, url?: string, status?: number }} error
+ */
+
+/**
+ * GET a URL with a timeout, returning the body as a UTF-8 string. Caps the
+ * response at maxBytes to defend against memory blow-ups from a hostile
+ * target. Does NOT throw — always returns a tagged result.
+ *
+ * @param {string} url
+ * @param {{ timeoutMs?: number, maxBytes?: number, fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<FetchOk | FetchErr>}
+ */
+export async function getJsonBody(url, opts = {}) {
+  const timeoutMs = typeof opts.timeoutMs === 'number' ? opts.timeoutMs : DEFAULT_TIMEOUT_MS
+  const maxBytes  = typeof opts.maxBytes  === 'number' ? opts.maxBytes  : DEFAULT_MAX_BYTES
+  const f         = opts.fetchImpl || globalThis.fetch
+
+  if (typeof f !== 'function') {
+    return errFetch_('no_fetch', 'global fetch() not available; pass opts.fetchImpl', { url })
+  }
+  if (typeof url !== 'string' || (!url.startsWith('http://') && !url.startsWith('https://'))) {
+    return errFetch_('invalid_url', 'url must be an absolute http(s) URL', { url })
+  }
+
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+  let res
+  try {
+    res = await f(url, { signal: ctrl.signal, redirect: 'follow', headers: { 'Accept': 'application/json' } })
+  } catch (err) {
+    clearTimeout(timer)
+    const code = err && err.name === 'AbortError' ? 'timeout' : 'network'
+    return errFetch_(code, code === 'timeout' ? `fetch timed out after ${timeoutMs}ms` : `network error: ${err.message}`, { url })
+  }
+  clearTimeout(timer)
+
+  if (!res.ok) {
+    return errFetch_('http_status', `HTTP ${res.status}`, { url, status: res.status })
+  }
+
+  // Read with a byte cap to prevent OOM on hostile responses.
+  let body
+  try {
+    body = await readWithCap_(res, maxBytes)
+  } catch (err) {
+    if (err && err.code === 'too_large') {
+      return errFetch_('too_large', `response exceeded ${maxBytes} bytes`, { url, status: res.status })
+    }
+    return errFetch_('read', `failed to read response body: ${err.message}`, { url, status: res.status })
+  }
+
+  return { ok: true, url, status: res.status, body }
+}
+
+async function readWithCap_(res, maxBytes) {
+  if (!res.body || typeof res.body.getReader !== 'function') {
+    // Fallback for environments without streams: read the whole text, check size.
+    const text = await res.text()
+    if (text.length > maxBytes * 4) { const e = new Error('too large'); e.code = 'too_large'; throw e }
+    return text
+  }
+  const reader = res.body.getReader()
+  const chunks = []
+  let total = 0
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    total += value.length
+    if (total > maxBytes) {
+      try { await reader.cancel() } catch {}
+      const e = new Error('too large'); e.code = 'too_large'; throw e
+    }
+    chunks.push(value)
+  }
+  const merged = new Uint8Array(total)
+  let off = 0
+  for (const c of chunks) { merged.set(c, off); off += c.length }
+  return new TextDecoder('utf-8').decode(merged)
+}
+
+function errFetch_(code, message, extra = {}) {
+  return { ok: false, error: { kind: 'fetch', code, message, ...extra } }
+}

package/src/index.d.ts

@@ -0,0 +1,57 @@
+export type VerifyState = 'valid' | 'rotated' | 'invalid' | 'error'
+
+export interface VerifyResultError {
+  kind: 'parse' | 'fetch' | 'signature' | 'consistency' | 'rotation'
+  code: string
+  message: string
+  /** true when the error is non-fatal (math succeeded but a soft check failed). */
+  soft?: boolean
+  [k: string]: unknown
+}
+
+export interface VerifyResult {
+  state: VerifyState
+  algorithm?: 'ML-DSA-65'
+  /** kid as declared inside the manifest itself */
+  manifestKid?: string
+  /** kid currently served at the live well-known pubkey endpoint (when fetched) */
+  livePubkeyKid?: string
+  /** site identifier as declared by the manifest */
+  site?: string
+  /** opaque deployment metadata from the manifest */
+  deployment?: Record<string, unknown>
+  /** full parsed manifest JSON, for UI display */
+  manifestRaw?: Record<string, unknown>
+  /** present when state is "error", "invalid", or "rotated" */
+  error?: VerifyResultError
+  attestationUrl?: string
+  /** URL of the live well-known pubkey endpoint (only present when fetched) */
+  pubkeyUrl?: string
+  /** Date.now() at the moment verification finished */
+  verifiedAtMs?: number
+}
+
+export interface VerifyUrlOpts {
+  timeoutMs?: number
+  maxBytes?: number
+  fetchImpl?: typeof fetch
+  /** When true, skip fetching the live well-known pubkey (no rotation detection). */
+  skipLivePubkey?: boolean
+}
+
+/**
+ * Verify an attestation manifest you already have in hand.
+ * Result is "valid" / "invalid" / "error" — never "rotated" (no live fetch).
+ */
+export function verifyManifest(manifestBody: string | object): Promise<VerifyResult>
+
+/**
+ * Verify an attestation by URL. May return "rotated" if the live well-known
+ * pubkey endpoint serves a different kid than the manifest declared.
+ */
+export function verifyUrl(attestationUrl: string, opts?: VerifyUrlOpts): Promise<VerifyResult>
+
+// Re-exports.
+export { parseManifest, ParseResult, ParsedManifest, ParseError } from './parse.js'
+export { verifySignature, computeKid, hexToBytes, bytesToHex, hexEquals } from './verify.js'
+export { getJsonBody, FetchOk, FetchErr, GetJsonBodyOpts }            from './fetch.js'

package/src/index.js

@@ -0,0 +1,212 @@
+// kxco-verify — public entry point.
+//
+// What this library is for:
+//   Given a URL (or an attestation manifest you already have), determine
+//   whether a site's post-quantum deploy attestation is mathematically valid.
+//
+// What it deliberately does NOT do:
+//   - Endorse any site. A "valid" result means "the site signed its own
+//     manifest with a key it published" — nothing about who the site is or
+//     whether its content is trustworthy.
+//   - Maintain a registry of approved (domain, kid) pairs. That is a future
+//     phase of kxco-post-quantum / verify.kxco.ai and not in this library.
+//   - Speak any algorithm other than ML-DSA-65 with hex encoding in this
+//     release. SLH-DSA-128s and hybrid envelopes are deferred.
+//
+// The result envelope is intentionally three-valued so the UI can distinguish
+// signature failure from in-flight key rotation:
+//
+//   "valid"    — signature checks against the manifest's declared kid AND
+//                that kid matches the live well-known pubkey endpoint
+//   "rotated"  — signature checks against the manifest's declared kid, BUT
+//                the live well-known endpoint now serves a different kid
+//                (interpret as: site is in the middle of a key rotation;
+//                ask the user to retry shortly)
+//   "invalid"  — signature does not check against the manifest-declared key
+//                (interpret as: signature is forged, manifest was tampered
+//                with, or the publisher's signing pipeline is broken)
+//
+// All other failure modes (network, malformed JSON, unsupported algorithm)
+// surface as { state: "error", error: {...} }.
+
+import { parseManifest }    from './parse.js'
+import { verifySignature,
+         computeKid,
+         hexEquals }         from './verify.js'
+import { getJsonBody }       from './fetch.js'
+
+/**
+ * @typedef {'valid'|'rotated'|'invalid'|'error'} VerifyState
+ *
+ * @typedef {Object} VerifyResult
+ * @property {VerifyState} state
+ * @property {string=}     algorithm        — e.g. "ML-DSA-65"
+ * @property {string=}     manifestKid      — kid the manifest declared
+ * @property {string=}     livePubkeyKid    — kid currently served at the well-known endpoint (only present when fetched)
+ * @property {string=}     site             — site identifier as declared by the manifest
+ * @property {object=}     deployment       — opaque deployment metadata from the manifest
+ * @property {object=}     manifestRaw      — full parsed manifest JSON (for UI display)
+ * @property {{ kind: string, code: string, message: string, [k: string]: any }=} error
+ * @property {string=}     attestationUrl
+ * @property {string=}     pubkeyUrl
+ * @property {number=}     verifiedAtMs     — Date.now() at the moment verification finished
+ */
+
+/**
+ * Verify an attestation manifest you already have in hand (e.g. paste from
+ * the user, or already fetched). Does NOT contact the live well-known
+ * endpoint — so the result is at best "valid" or "invalid" but never "rotated".
+ *
+ * @param {string|object} manifestBody — raw JSON body or parsed object
+ * @returns {Promise<VerifyResult>}
+ */
+export async function verifyManifest(manifestBody) {
+  const parsed = parseManifest(manifestBody)
+  if (!parsed.ok) return { state: 'error', error: parsed.error, verifiedAtMs: Date.now() }
+  const m = parsed.manifest
+
+  // The publisher's own consistency check: the kid embedded inside the
+  // publicKey block must match what manifest.kid says, AND must match the
+  // SHA-256 fingerprint of the pubkey bytes. If either disagrees, the
+  // manifest is internally inconsistent — treat as invalid before we even
+  // run the slow signature math.
+  const recomputedKid = await computeKid(m.publicKeyHex)
+  if (!hexEquals(recomputedKid, m.kid) || !hexEquals(recomputedKid, m.publicKeyKid)) {
+    return {
+      state:       'invalid',
+      algorithm:   m.alg,
+      manifestKid: m.kid,
+      site:        m.site,
+      manifestRaw: m.raw,
+      error: {
+        kind: 'consistency',
+        code: 'kid_mismatch_internal',
+        message: `manifest.kid (${m.kid}) and/or publicKey.kid (${m.publicKeyKid}) disagree with SHA-256(publicKey) (${recomputedKid})`,
+      },
+      verifiedAtMs: Date.now(),
+    }
+  }
+
+  const sigValid = verifySignature(m.publicKeyHex, m.signedMessage, m.signatureHex)
+  return {
+    state:       sigValid ? 'valid' : 'invalid',
+    algorithm:   m.alg,
+    manifestKid: m.kid,
+    site:        m.site,
+    deployment:  m.deployment,
+    manifestRaw: m.raw,
+    error: sigValid ? undefined : {
+      kind: 'signature',
+      code: 'invalid_signature',
+      message: 'signature does not verify under the manifest-declared public key',
+    },
+    verifiedAtMs: Date.now(),
+  }
+}
+
+/**
+ * Verify an attestation by URL.
+ *
+ *   1. Fetch the attestation URL.
+ *   2. Parse + math-verify it (as verifyManifest does).
+ *   3. If the manifest declared `publicKey.pinAt`, also fetch that endpoint
+ *      and compare its kid to the manifest's. A mismatch downgrades a "valid"
+ *      result to "rotated" — the signature checks against the kid the
+ *      manifest declared, but the live endpoint now serves a different kid.
+ *
+ * @param {string} attestationUrl
+ * @param {{ timeoutMs?: number, maxBytes?: number, fetchImpl?: typeof fetch, skipLivePubkey?: boolean }} [opts]
+ * @returns {Promise<VerifyResult>}
+ */
+export async function verifyUrl(attestationUrl, opts = {}) {
+  const t0 = Date.now()
+  const fetched = await getJsonBody(attestationUrl, opts)
+  if (!fetched.ok) {
+    return { state: 'error', error: fetched.error, attestationUrl, verifiedAtMs: Date.now() }
+  }
+
+  const result = await verifyManifest(fetched.body)
+  result.attestationUrl = attestationUrl
+
+  // Math failed already; no benefit in fetching the live pubkey.
+  if (result.state !== 'valid' || opts.skipLivePubkey) {
+    result.verifiedAtMs = Date.now()
+    return result
+  }
+
+  // Resolve pinAt against the attestation URL's origin.
+  const pinAt = result.manifestRaw?.publicKey?.pinAt
+  if (typeof pinAt !== 'string' || !pinAt) {
+    // No pinAt → publisher didn't tell us where the live pubkey is, so we
+    // cannot detect rotation. Return valid as-is and let the UI explain.
+    result.verifiedAtMs = Date.now()
+    return result
+  }
+
+  let pubkeyUrl
+  try {
+    pubkeyUrl = new URL(pinAt, attestationUrl).toString()
+  } catch (err) {
+    result.error = { kind: 'consistency', code: 'invalid_pinAt', message: `manifest.publicKey.pinAt is not a resolvable URL: ${err.message}` }
+    result.state = 'invalid'
+    result.verifiedAtMs = Date.now()
+    return result
+  }
+
+  const livePk = await getJsonBody(pubkeyUrl, opts)
+  if (!livePk.ok) {
+    // Couldn't fetch the live pubkey. Don't downgrade — the math succeeded.
+    // Tell the UI we couldn't confirm rotation status.
+    result.pubkeyUrl = pubkeyUrl
+    result.error = { kind: 'fetch', code: livePk.error.code, message: `could not fetch live pubkey at ${pubkeyUrl}: ${livePk.error.message}`, soft: true }
+    result.verifiedAtMs = Date.now()
+    return result
+  }
+
+  let liveJson
+  try { liveJson = JSON.parse(livePk.body) }
+  catch (err) {
+    result.pubkeyUrl = pubkeyUrl
+    result.error = { kind: 'parse', code: 'invalid_live_pubkey_json', message: `live pubkey body is not JSON: ${err.message}`, soft: true }
+    result.verifiedAtMs = Date.now()
+    return result
+  }
+
+  // Two ways the publisher may serve the kid: explicit "kid" field, or we
+  // recompute from the publicKey hex. Prefer recompute as the source of truth.
+  const livePubkeyHex = typeof liveJson.publicKey === 'string'
+    ? liveJson.publicKey
+    : (typeof liveJson?.value === 'string' ? liveJson.value : null)
+  if (!livePubkeyHex) {
+    result.pubkeyUrl = pubkeyUrl
+    result.error = { kind: 'consistency', code: 'live_pubkey_missing', message: 'live well-known endpoint did not return a publicKey field', soft: true }
+    result.verifiedAtMs = Date.now()
+    return result
+  }
+  const liveKid = await computeKid(livePubkeyHex)
+  result.pubkeyUrl     = pubkeyUrl
+  result.livePubkeyKid = liveKid
+
+  if (!hexEquals(liveKid, result.manifestKid)) {
+    // Signature checked against manifest.kid but the well-known now serves
+    // a different kid. This is the rotation signal.
+    result.state = 'rotated'
+    result.error = {
+      kind: 'rotation',
+      code: 'live_kid_mismatch',
+      message: `signature is valid for kid ${result.manifestKid}, but the live well-known endpoint now serves kid ${liveKid}. The site is likely mid key-rotation; retry shortly.`,
+    }
+  }
+
+  result.verifiedAtMs = Date.now()
+  return result
+}
+
+// Re-export the lower-level helpers for users who want to compose.
+export { parseManifest }      from './parse.js'
+export { verifySignature,
+         computeKid,
+         hexToBytes,
+         bytesToHex,
+         hexEquals }          from './verify.js'
+export { getJsonBody }        from './fetch.js'

package/src/parse.d.ts

@@ -0,0 +1,31 @@
+export interface ParsedManifest {
+  site: string
+  alg: 'ML-DSA-65'
+  kid: string
+  signedMessage: string
+  signatureHex: string
+  publicKeyHex: string
+  publicKeyKid: string
+  pinAt?: string
+  deployment?: Record<string, unknown>
+  raw: Record<string, unknown>
+}
+
+export interface ParseError {
+  kind: 'parse'
+  code:
+    | 'invalid_json'
+    | 'invalid_input'
+    | 'missing_field'
+    | 'invalid_field'
+    | 'unsupported_algorithm'
+    | 'unsupported_encoding'
+  message: string
+  field?: string
+}
+
+export type ParseResult =
+  | { ok: true;  manifest: ParsedManifest }
+  | { ok: false; error: ParseError }
+
+export function parseManifest(input: string | object): ParseResult

package/src/parse.js

@@ -0,0 +1,116 @@
+// Manifest parsing.
+//
+// Takes the raw JSON body served by an `/api/attestation`-style endpoint and
+// returns a normalised, typed-ish shape that the verifier can work with —
+// or a structured error if the shape is wrong.
+//
+// The reference manifest shape is what target150.com/api/attestation and
+// chain.kxco.ai/wallet/api/.well-known/kxco-pq-attestation emit today:
+//
+// {
+//   "manifest": {
+//     "site": "example.com",
+//     "alg": "ML-DSA-65",
+//     "spec": "NIST FIPS 204",
+//     "kid": "<16-hex-char fingerprint>",
+//     "deployment": { ...site-defined fields... },
+//     "msgFormat": "<template describing what was signed>"
+//   },
+//   "signedMessage": "<the actual bytes that were signed, as a string>",
+//   "signature": { "alg": "ML-DSA-65", "encoding": "hex", "value": "<6618 hex chars>" },
+//   "publicKey": { "alg": "ML-DSA-65", "encoding": "hex", "value": "<3904 hex chars>", "kid": "<same as manifest.kid>", "pinAt": "<relative URL>" }
+// }
+//
+// We accept only ML-DSA-65 with hex encoding in this version. SLH-DSA-128s
+// and Ed25519+ML-DSA hybrid envelopes are reserved for later.
+
+const HEX_RE = /^[0-9a-f]+$/i
+
+/**
+ * @typedef {Object} ParsedManifest
+ * @property {string}  site
+ * @property {string}  alg                — must be "ML-DSA-65" in this version
+ * @property {string}  kid
+ * @property {string}  signedMessage      — the exact bytes the signature covers
+ * @property {string}  signatureHex
+ * @property {string}  publicKeyHex
+ * @property {string}  publicKeyKid       — kid as declared inside the publicKey block
+ * @property {string=} pinAt              — relative path where the publisher recommends re-fetching the pubkey
+ * @property {object=} deployment         — site-defined metadata, opaque to us
+ * @property {object}  raw                — the parsed JSON in its entirety, for the UI to display
+ */
+
+/**
+ * @typedef {Object} ParseError
+ * @property {'parse'} kind
+ * @property {string}  code        — short stable identifier (e.g. "missing_field")
+ * @property {string}  message
+ * @property {string=} field
+ */
+
+/**
+ * Parse an attestation manifest from a JSON body. Returns either
+ * { ok: true, manifest } or { ok: false, error }.
+ *
+ * @param {string|object} input — raw JSON string OR an already-parsed object
+ * @returns {{ ok: true, manifest: ParsedManifest } | { ok: false, error: ParseError }}
+ */
+export function parseManifest(input) {
+  let raw
+  if (typeof input === 'string') {
+    try { raw = JSON.parse(input) }
+    catch (err) { return err_('invalid_json', `body is not valid JSON: ${err.message}`) }
+  } else if (input && typeof input === 'object') {
+    raw = input
+  } else {
+    return err_('invalid_input', 'input must be a JSON string or an object')
+  }
+
+  const m  = raw.manifest
+  const s  = raw.signature
+  const pk = raw.publicKey
+
+  if (!m  || typeof m  !== 'object') return err_('missing_field', 'top-level "manifest" is missing or not an object',  'manifest')
+  if (!s  || typeof s  !== 'object') return err_('missing_field', 'top-level "signature" is missing or not an object', 'signature')
+  if (!pk || typeof pk !== 'object') return err_('missing_field', 'top-level "publicKey" is missing or not an object', 'publicKey')
+
+  // We only verify ML-DSA-65 with hex-encoded signature + pubkey in this
+  // release. Anything else is a feature we deferred to a later version.
+  if (m.alg  !== 'ML-DSA-65') return err_('unsupported_algorithm', `manifest.alg must be "ML-DSA-65" (got ${JSON.stringify(m.alg)})`,  'manifest.alg')
+  if (s.alg  !== 'ML-DSA-65') return err_('unsupported_algorithm', `signature.alg must be "ML-DSA-65" (got ${JSON.stringify(s.alg)})`, 'signature.alg')
+  if (pk.alg !== 'ML-DSA-65') return err_('unsupported_algorithm', `publicKey.alg must be "ML-DSA-65" (got ${JSON.stringify(pk.alg)})`, 'publicKey.alg')
+  if (s.encoding  && s.encoding  !== 'hex') return err_('unsupported_encoding', `signature.encoding must be "hex" (got ${JSON.stringify(s.encoding)})`,  'signature.encoding')
+  if (pk.encoding && pk.encoding !== 'hex') return err_('unsupported_encoding', `publicKey.encoding must be "hex" (got ${JSON.stringify(pk.encoding)})`, 'publicKey.encoding')
+
+  if (typeof m.kid !== 'string'  || !HEX_RE.test(m.kid))  return err_('invalid_field', 'manifest.kid must be a hex string', 'manifest.kid')
+  if (typeof m.site !== 'string' || !m.site.length)       return err_('invalid_field', 'manifest.site must be a non-empty string', 'manifest.site')
+  if (typeof raw.signedMessage !== 'string')              return err_('missing_field', 'top-level "signedMessage" must be a string', 'signedMessage')
+  if (typeof s.value  !== 'string' || !HEX_RE.test(s.value))  return err_('invalid_field', 'signature.value must be a hex string',  'signature.value')
+  if (typeof pk.value !== 'string' || !HEX_RE.test(pk.value)) return err_('invalid_field', 'publicKey.value must be a hex string', 'publicKey.value')
+  if (typeof pk.kid   !== 'string' || !HEX_RE.test(pk.kid))   return err_('invalid_field', 'publicKey.kid must be a hex string',   'publicKey.kid')
+
+  // ML-DSA-65 size sanity. Don't trust the message saying "ML-DSA-65" —
+  // verify the byte counts match the spec. Catches malformed payloads early.
+  if (pk.value.length !== 3904) return err_('invalid_field', `publicKey.value must be 1952 bytes (3904 hex chars); got ${pk.value.length / 2}`, 'publicKey.value')
+  if (s.value.length  !== 6618) return err_('invalid_field', `signature.value must be 3309 bytes (6618 hex chars); got ${s.value.length / 2}`,  'signature.value')
+
+  return {
+    ok: true,
+    manifest: {
+      site:           m.site,
+      alg:            m.alg,
+      kid:            m.kid.toLowerCase(),
+      signedMessage:  raw.signedMessage,
+      signatureHex:   s.value.toLowerCase(),
+      publicKeyHex:   pk.value.toLowerCase(),
+      publicKeyKid:   pk.kid.toLowerCase(),
+      pinAt:          typeof pk.pinAt === 'string' ? pk.pinAt : undefined,
+      deployment:     m.deployment && typeof m.deployment === 'object' ? m.deployment : undefined,
+      raw,
+    },
+  }
+}
+
+function err_(code, message, field) {
+  return { ok: false, error: { kind: 'parse', code, message, field } }
+}

package/src/verify.d.ts

@@ -0,0 +1,24 @@
+/** Hex string → Uint8Array. Throws on malformed input. */
+export function hexToBytes(hex: string): Uint8Array
+
+/** Uint8Array → hex string (lowercase). */
+export function bytesToHex(bytes: Uint8Array): string
+
+/** UTF-8 string → Uint8Array. */
+export function utf8(s: string): Uint8Array
+
+/**
+ * Compute the kxco kid (key identifier) of a public key —
+ * first 16 hex chars of SHA-256(rawBytes).
+ */
+export function computeKid(publicKey: Uint8Array | string): Promise<string>
+
+/** Verify an ML-DSA-65 signature. */
+export function verifySignature(
+  publicKey: Uint8Array | string,
+  message:   Uint8Array | string,
+  signature: Uint8Array | string,
+): boolean
+
+/** Length-equal hex comparison. */
+export function hexEquals(a: string, b: string): boolean

package/src/verify.js

@@ -0,0 +1,103 @@
+// Signature math + kid math. Pure functions. No network, no I/O.
+//
+// We call @noble/post-quantum directly with Uint8Array so the same code runs
+// in Node 18+ and in any modern browser without a polyfill. SHA-256 is taken
+// from the Web Crypto API where available (browser, Node 20+), fallback to
+// node:crypto's createHash where SubtleCrypto.digest is not present.
+
+import { ml_dsa65 } from '@noble/post-quantum/ml-dsa'
+
+/**
+ * Hex string → Uint8Array. Throws on malformed input.
+ * @param {string} hex
+ * @returns {Uint8Array}
+ */
+export function hexToBytes(hex) {
+  if (typeof hex !== 'string' || hex.length % 2 !== 0) {
+    throw new TypeError('hex input must be a string of even length')
+  }
+  const out = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < out.length; i++) {
+    const byte = parseInt(hex.substr(i * 2, 2), 16)
+    if (Number.isNaN(byte)) throw new TypeError(`malformed hex at offset ${i * 2}`)
+    out[i] = byte
+  }
+  return out
+}
+
+/**
+ * Uint8Array → hex string (lowercase).
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export function bytesToHex(bytes) {
+  let out = ''
+  for (let i = 0; i < bytes.length; i++) out += bytes[i].toString(16).padStart(2, '0')
+  return out
+}
+
+/**
+ * UTF-8 string → Uint8Array.
+ * @param {string} s
+ * @returns {Uint8Array}
+ */
+export function utf8(s) {
+  return new TextEncoder().encode(s)
+}
+
+/**
+ * Compute the kxco kid (key identifier) of a public key — first 16 hex chars
+ * of SHA-256(rawBytes). Matches the algorithm in kxco-post-quantum's
+ * `fingerprint()`. Async because SubtleCrypto.digest is async.
+ *
+ * @param {Uint8Array|string} publicKey — raw bytes or hex string
+ * @returns {Promise<string>} 16-char lowercase hex
+ */
+export async function computeKid(publicKey) {
+  const bytes = typeof publicKey === 'string' ? hexToBytes(publicKey) : publicKey
+  const subtle = globalThis.crypto && globalThis.crypto.subtle
+  let hashBytes
+  if (subtle && typeof subtle.digest === 'function') {
+    const ab = await subtle.digest('SHA-256', bytes)
+    hashBytes = new Uint8Array(ab)
+  } else {
+    // Node fallback. Only reached on Node <20 without globalThis.crypto.
+    const { createHash } = await import('node:crypto')
+    hashBytes = createHash('sha256').update(bytes).digest()
+  }
+  return bytesToHex(hashBytes.subarray(0, 8))
+}
+
+/**
+ * Verify an ML-DSA-65 signature.
+ * @param {string|Uint8Array} publicKey   — 1952 bytes (3904 hex chars)
+ * @param {string|Uint8Array} message     — string (utf8'd) or raw bytes
+ * @param {string|Uint8Array} signature   — 3309 bytes (6618 hex chars)
+ * @returns {boolean}
+ */
+export function verifySignature(publicKey, message, signature) {
+  const pk  = typeof publicKey === 'string' ? hexToBytes(publicKey) : publicKey
+  const sig = typeof signature === 'string' ? hexToBytes(signature) : signature
+  const msg = typeof message   === 'string' ? utf8(message)         : message
+  // @noble/post-quantum signature: (publicKey, message, signature). Matches
+  // the canonical wrapper in kxco-post-quantum/src/ml-dsa.js.
+  try {
+    return ml_dsa65.verify(pk, msg, sig)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Constant-time-ish hex comparison. Both inputs are hex strings.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function hexEquals(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  return diff === 0
+}