kxco-verify 1.2.0 → 1.2.2

package/src/parse.js

@@ -1,116 +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 } }
-}
+// 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

@@ -1,24 +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
+/** 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

@@ -1,103 +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.js'
-
-/**
- * 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 ≥0.6 signature order: (signature, message, publicKey).
-  // Matches the canonical wrapper in kxco-post-quantum/src/ml-dsa.js.
-  try {
-    return ml_dsa65.verify(sig, msg, pk)
-  } 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
-}
+// 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.js'
+
+/**
+ * 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 ≥0.6 signature order: (signature, message, publicKey).
+  // Matches the canonical wrapper in kxco-post-quantum/src/ml-dsa.js.
+  try {
+    return ml_dsa65.verify(sig, msg, pk)
+  } 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
+}