xoonya 3.1.12 → 3.1.14

package/RELEASE_NOTES.md

@@ -1 +1 @@
-`xoonya` 3.1.12 is a synchronized-line release with no change to the proof engine, verification behavior, vectors, routes, or package contents. It keeps the naxytra release line aligned across xytara, xoonya, and the naxytra bootstrap package.
+`xoonya` 3.1.14 is a synchronized-line release with no change to the proof engine, verification behavior, vectors, routes, or package contents. It is published through npm trusted publishing (GitHub OIDC), with no npm token involved.

package/lib/external_proof_verify.js

@@ -1,189 +1,196 @@
-"use strict";
-
-// Cryptographic verification of IMPORTED external proofs.
-//
-// xoonya binds external proof material into its own bundles. This module lets it
-// additionally VERIFY the external material's own signature — reporting the
-// cryptographic FACTS it can establish, without over-claiming trust.
-//
-// Honesty model (important): from a single self-contained request, xoonya can
-// only establish that "a signature is valid under key K" (signature_valid) and
-// report K's fingerprint (signing_key_ref). It CANNOT establish that K is the
-// legitimate issuer/attester, nor revocation or DID-resolution status. Trust in K
-// is the consumer's decision. The only way a caller gets a trust-anchored result
-// (expected_key_match=true) is by DECLARING, out of band, the key fingerprint they
-// already trust (expected_key_ref) and having the signer match it. A key supplied
-// in the same request — or a self-asserted key embedded in the proof — is NOT, by
-// itself, treated as trusted.
-//
-// Dependency-free (node crypto). Supports compact JWS (EdDSA, ES256/384/512,
-// ES256K, RS256/384/512, PS256/384/512) and generic detached signatures. Private
-// key material (e.g. a JWK with a `d` component) is refused.
-
-const crypto = require("crypto");
-
-function b64urlToBuffer(s) {
-  const str = String(s || "").replace(/-/g, "+").replace(/_/g, "/");
-  const pad = str.length % 4 === 0 ? "" : "=".repeat(4 - (str.length % 4));
-  return Buffer.from(str + pad, "base64");
-}
-
-// alg -> { hash, kind, keyType?/curve? } ; curve/keyType bind the declared alg to
-// the actual key so the reported alg describes how it was really validated.
-const JWS_ALG = {
-  EdDSA: { hash: null, kind: "eddsa", keyType: "ed25519" },
-  ES256: { hash: "sha256", kind: "ecdsa", curve: "prime256v1" },
-  ES384: { hash: "sha384", kind: "ecdsa", curve: "secp384r1" },
-  ES512: { hash: "sha512", kind: "ecdsa", curve: "secp521r1" },
-  ES256K: { hash: "sha256", kind: "ecdsa", curve: "secp256k1" },
-  RS256: { hash: "sha256", kind: "rsa" },
-  RS384: { hash: "sha384", kind: "rsa" },
-  RS512: { hash: "sha512", kind: "rsa" },
-  PS256: { hash: "sha256", kind: "rsapss" },
-  PS384: { hash: "sha384", kind: "rsapss" },
-  PS512: { hash: "sha512", kind: "rsapss" }
-};
-
-function isPrivateJwk(obj) {
-  return Boolean(obj && typeof obj === "object" && !Buffer.isBuffer(obj) && typeof obj.d === "string" && obj.d.length > 0);
-}
-
-// Build a PUBLIC KeyObject from PEM / base64 DER SPKI / public JWK. Refuses
-// private key material. Returns null on any problem.
-function toPublicKeyObject(input) {
-  if (!input) return null;
-  try {
-    if (typeof input === "object" && !Buffer.isBuffer(input)) {
-      if (isPrivateJwk(input)) return null; // never accept private material
-      return crypto.createPublicKey({ key: input, format: "jwk" });
-    }
-    const s = String(input).trim();
-    if (/BEGIN (EC |RSA |DSA |OPENSSH |PGP )?PRIVATE KEY/.test(s)) return null;
-    if (s.includes("BEGIN ")) return crypto.createPublicKey({ key: s, format: "pem" });
-    return crypto.createPublicKey({ key: Buffer.from(s, "base64"), format: "der", type: "spki" });
-  } catch (_) {
-    return null;
-  }
-}
-
-function keyRef(keyObject) {
-  try {
-    const spki = keyObject.export({ type: "spki", format: "der" });
-    const algo = keyObject.asymmetricKeyType || "key";
-    return `${algo}-spki-sha256:` + crypto.createHash("sha256").update(spki).digest("hex");
-  } catch (_) {
-    return null;
-  }
-}
-
-// The declared alg must be consistent with the actual key type/curve.
-function keyMatchesAlg(keyObject, alg) {
-  const spec = JWS_ALG[alg];
-  if (!spec || !keyObject) return false;
-  const t = keyObject.asymmetricKeyType;
-  if (spec.kind === "eddsa") return t === "ed25519";
-  if (spec.kind === "ecdsa") {
-    if (t !== "ec") return false;
-    const details = keyObject.asymmetricKeyDetails || {};
-    return details.namedCurve === spec.curve;
-  }
-  if (spec.kind === "rsa" || spec.kind === "rsapss") return t === "rsa" || t === "rsa-pss";
-  return false;
-}
-
-function verifyWithAlg(alg, signingInput, signature, keyObject) {
-  const spec = JWS_ALG[alg];
-  if (!spec || !keyObject) return false;
-  if (!keyMatchesAlg(keyObject, alg)) return false; // bind declared alg to the key
-  const data = Buffer.isBuffer(signingInput) ? signingInput : Buffer.from(String(signingInput), "utf8");
-  try {
-    if (spec.kind === "eddsa") return crypto.verify(null, data, keyObject, signature);
-    if (spec.kind === "ecdsa") return crypto.verify(spec.hash, data, { key: keyObject, dsaEncoding: "ieee-p1363" }, signature);
-    if (spec.kind === "rsa") return crypto.verify(spec.hash, data, keyObject, signature);
-    if (spec.kind === "rsapss") {
-      return crypto.verify(spec.hash, data, { key: keyObject, padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST }, signature);
-    }
-  } catch (_) {
-    return false;
-  }
-  return false;
-}
-
-function trustResult(signatureValid, keyObject, keySource, expectedKeyRef, alg, extra) {
-  const kref = keyRef(keyObject);
-  const expected = typeof expectedKeyRef === "string" && expectedKeyRef.trim() ? expectedKeyRef.trim() : null;
-  const expectedMatch = expected ? kref === expected : null;
-  return {
-    ok: true,
-    signature_valid: signatureValid === true,
-    signing_key_ref: kref,
-    key_source: keySource,
-    expected_key_ref: expected,
-    // true only when the caller declared a trusted key fingerprint AND the signer
-    // matches it; null when no expectation was declared. Trust in signing_key_ref
-    // is otherwise the consumer's decision.
-    expected_key_match: expectedMatch,
-    trust_anchored: signatureValid === true && expectedMatch === true,
-    alg,
-    ...(extra || {})
-  };
-}
-
-// Verify a compact JWS. opts = { trusted_public_key?, expected_key_ref? }.
-function verifyJws(jwsCompact, opts) {
-  const o = opts && typeof opts === "object" ? opts : {};
-  const parts = String(jwsCompact || "").split(".");
-  if (parts.length !== 3) return { ok: false, reason: "jws_malformed" };
-  const [protectedB64, payloadB64, signatureB64] = parts;
-  let header;
-  try {
-    header = JSON.parse(b64urlToBuffer(protectedB64).toString("utf8"));
-  } catch (_) {
-    return { ok: false, reason: "jws_header_invalid" };
-  }
-  const alg = header && typeof header.alg === "string" ? header.alg : null;
-  if (alg === "none") return { ok: false, reason: "jws_alg_none_rejected" };
-  if (!alg || !JWS_ALG[alg]) return { ok: false, reason: "jws_alg_unsupported", alg: alg || null };
-  // Refuse unknown critical extensions and non-standard signing-input variants.
-  if (Array.isArray(header.crit) && header.crit.length > 0) return { ok: false, reason: "jws_crit_unsupported" };
-  if (header.b64 === false) return { ok: false, reason: "jws_unencoded_payload_unsupported" };
-
-  const trustedKey = o.trusted_public_key ? toPublicKeyObject(o.trusted_public_key) : null;
-  const embeddedKey = !trustedKey && header.jwk ? toPublicKeyObject(header.jwk) : null;
-  const keyObject = trustedKey || embeddedKey;
-  if (!keyObject) return { ok: false, reason: "no_public_key" };
-
-  const valid = verifyWithAlg(alg, `${protectedB64}.${payloadB64}`, b64urlToBuffer(signatureB64), keyObject);
-  return trustResult(valid, keyObject, trustedKey ? "caller_supplied" : "embedded_self_asserted", o.expected_key_ref, alg, {
-    header,
-    payload_b64url: payloadB64
-  });
-}
-
-// Verify a detached signature over `material`. opts = { material, signature,
-// signature_encoding?, public_key, algorithm, expected_key_ref? }.
-function verifyDetachedSignature(opts) {
-  const o = opts && typeof opts === "object" ? opts : {};
-  const alg = typeof o.algorithm === "string" ? o.algorithm : null;
-  if (!alg || !JWS_ALG[alg]) return { ok: false, reason: "algorithm_unsupported", alg: alg || null };
-  const keyObject = toPublicKeyObject(o.public_key);
-  if (!keyObject) return { ok: false, reason: "no_public_key" };
-  if (o.material === undefined || o.material === null) return { ok: false, reason: "material_required" };
-  const material = Buffer.isBuffer(o.material) ? o.material : Buffer.from(String(o.material), "utf8");
-  let signature;
-  try {
-    const enc = o.signature_encoding === "hex" ? "hex" : o.signature_encoding === "base64url" ? null : "base64";
-    signature = enc ? Buffer.from(String(o.signature || ""), enc) : b64urlToBuffer(o.signature);
-  } catch (_) {
-    return { ok: false, reason: "signature_invalid" };
-  }
-  if (signature.length === 0) return { ok: false, reason: "signature_invalid" };
-  const valid = verifyWithAlg(alg, material, signature, keyObject);
-  return trustResult(valid, keyObject, "caller_supplied", o.expected_key_ref, alg);
-}
-
-function looksLikeCompactJws(s) {
-  return typeof s === "string" && /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(s.trim());
-}
-
-module.exports = { verifyJws, verifyDetachedSignature, toPublicKeyObject, isPrivateJwk, looksLikeCompactJws };
+"use strict";
+
+// Cryptographic verification of IMPORTED external proofs.
+//
+// xoonya binds external proof material into its own bundles. This module lets it
+// additionally VERIFY the external material's own signature — reporting the
+// cryptographic FACTS it can establish, without over-claiming trust.
+//
+// Honesty model (important): from a single self-contained request, xoonya can
+// only establish that "a signature is valid under key K" (signature_valid) and
+// report K's fingerprint (signing_key_ref). It CANNOT establish that K is the
+// legitimate issuer/attester, nor revocation or DID-resolution status. Trust in K
+// is the consumer's decision. The only way a caller gets a trust-anchored result
+// (expected_key_match=true) is by DECLARING, out of band, the key fingerprint they
+// already trust (expected_key_ref) and having the signer match it. A key supplied
+// in the same request — or a self-asserted key embedded in the proof — is NOT, by
+// itself, treated as trusted.
+//
+// Dependency-free (node crypto). Supports compact JWS (EdDSA, ES256/384/512,
+// ES256K, RS256/384/512, PS256/384/512) and generic detached signatures, which
+// additionally accept ML-DSA-44/65/87 (FIPS-204, SPKI keys). Private key material
+// (e.g. a JWK with a `d` component) is refused.
+
+const crypto = require("crypto");
+
+function b64urlToBuffer(s) {
+  const str = String(s || "").replace(/-/g, "+").replace(/_/g, "/");
+  const pad = str.length % 4 === 0 ? "" : "=".repeat(4 - (str.length % 4));
+  return Buffer.from(str + pad, "base64");
+}
+
+// alg -> { hash, kind, keyType?/curve? } ; curve/keyType bind the declared alg to
+// the actual key so the reported alg describes how it was really validated.
+const JWS_ALG = {
+  EdDSA: { hash: null, kind: "eddsa", keyType: "ed25519" },
+  ES256: { hash: "sha256", kind: "ecdsa", curve: "prime256v1" },
+  ES384: { hash: "sha384", kind: "ecdsa", curve: "secp384r1" },
+  ES512: { hash: "sha512", kind: "ecdsa", curve: "secp521r1" },
+  ES256K: { hash: "sha256", kind: "ecdsa", curve: "secp256k1" },
+  RS256: { hash: "sha256", kind: "rsa" },
+  RS384: { hash: "sha384", kind: "rsa" },
+  RS512: { hash: "sha512", kind: "rsa" },
+  PS256: { hash: "sha256", kind: "rsapss" },
+  PS384: { hash: "sha384", kind: "rsapss" },
+  PS512: { hash: "sha512", kind: "rsapss" },
+  // FIPS-204 ML-DSA (pure mode, as named by the JOSE ML-DSA draft). Needs Node >= 24
+  // (node:crypto ML-DSA); on an older runtime the key cannot be parsed and verify fails closed.
+  "ML-DSA-44": { hash: null, kind: "mldsa", keyType: "ml-dsa-44" },
+  "ML-DSA-65": { hash: null, kind: "mldsa", keyType: "ml-dsa-65" },
+  "ML-DSA-87": { hash: null, kind: "mldsa", keyType: "ml-dsa-87" }
+};
+
+function isPrivateJwk(obj) {
+  return Boolean(obj && typeof obj === "object" && !Buffer.isBuffer(obj) && typeof obj.d === "string" && obj.d.length > 0);
+}
+
+// Build a PUBLIC KeyObject from PEM / base64 DER SPKI / public JWK. Refuses
+// private key material. Returns null on any problem.
+function toPublicKeyObject(input) {
+  if (!input) return null;
+  try {
+    if (typeof input === "object" && !Buffer.isBuffer(input)) {
+      if (isPrivateJwk(input)) return null; // never accept private material
+      return crypto.createPublicKey({ key: input, format: "jwk" });
+    }
+    const s = String(input).trim();
+    if (/BEGIN (EC |RSA |DSA |OPENSSH |PGP )?PRIVATE KEY/.test(s)) return null;
+    if (s.includes("BEGIN ")) return crypto.createPublicKey({ key: s, format: "pem" });
+    return crypto.createPublicKey({ key: Buffer.from(s, "base64"), format: "der", type: "spki" });
+  } catch (_) {
+    return null;
+  }
+}
+
+function keyRef(keyObject) {
+  try {
+    const spki = keyObject.export({ type: "spki", format: "der" });
+    const algo = keyObject.asymmetricKeyType || "key";
+    return `${algo}-spki-sha256:` + crypto.createHash("sha256").update(spki).digest("hex");
+  } catch (_) {
+    return null;
+  }
+}
+
+// The declared alg must be consistent with the actual key type/curve.
+function keyMatchesAlg(keyObject, alg) {
+  const spec = JWS_ALG[alg];
+  if (!spec || !keyObject) return false;
+  const t = keyObject.asymmetricKeyType;
+  if (spec.kind === "eddsa") return t === "ed25519";
+  if (spec.kind === "mldsa") return t === spec.keyType;
+  if (spec.kind === "ecdsa") {
+    if (t !== "ec") return false;
+    const details = keyObject.asymmetricKeyDetails || {};
+    return details.namedCurve === spec.curve;
+  }
+  if (spec.kind === "rsa" || spec.kind === "rsapss") return t === "rsa" || t === "rsa-pss";
+  return false;
+}
+
+function verifyWithAlg(alg, signingInput, signature, keyObject) {
+  const spec = JWS_ALG[alg];
+  if (!spec || !keyObject) return false;
+  if (!keyMatchesAlg(keyObject, alg)) return false; // bind declared alg to the key
+  const data = Buffer.isBuffer(signingInput) ? signingInput : Buffer.from(String(signingInput), "utf8");
+  try {
+    if (spec.kind === "eddsa" || spec.kind === "mldsa") return crypto.verify(null, data, keyObject, signature);
+    if (spec.kind === "ecdsa") return crypto.verify(spec.hash, data, { key: keyObject, dsaEncoding: "ieee-p1363" }, signature);
+    if (spec.kind === "rsa") return crypto.verify(spec.hash, data, keyObject, signature);
+    if (spec.kind === "rsapss") {
+      return crypto.verify(spec.hash, data, { key: keyObject, padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST }, signature);
+    }
+  } catch (_) {
+    return false;
+  }
+  return false;
+}
+
+function trustResult(signatureValid, keyObject, keySource, expectedKeyRef, alg, extra) {
+  const kref = keyRef(keyObject);
+  const expected = typeof expectedKeyRef === "string" && expectedKeyRef.trim() ? expectedKeyRef.trim() : null;
+  const expectedMatch = expected ? kref === expected : null;
+  return {
+    ok: true,
+    signature_valid: signatureValid === true,
+    signing_key_ref: kref,
+    key_source: keySource,
+    expected_key_ref: expected,
+    // true only when the caller declared a trusted key fingerprint AND the signer
+    // matches it; null when no expectation was declared. Trust in signing_key_ref
+    // is otherwise the consumer's decision.
+    expected_key_match: expectedMatch,
+    trust_anchored: signatureValid === true && expectedMatch === true,
+    alg,
+    ...(extra || {})
+  };
+}
+
+// Verify a compact JWS. opts = { trusted_public_key?, expected_key_ref? }.
+function verifyJws(jwsCompact, opts) {
+  const o = opts && typeof opts === "object" ? opts : {};
+  const parts = String(jwsCompact || "").split(".");
+  if (parts.length !== 3) return { ok: false, reason: "jws_malformed" };
+  const [protectedB64, payloadB64, signatureB64] = parts;
+  let header;
+  try {
+    header = JSON.parse(b64urlToBuffer(protectedB64).toString("utf8"));
+  } catch (_) {
+    return { ok: false, reason: "jws_header_invalid" };
+  }
+  const alg = header && typeof header.alg === "string" ? header.alg : null;
+  if (alg === "none") return { ok: false, reason: "jws_alg_none_rejected" };
+  if (!alg || !JWS_ALG[alg]) return { ok: false, reason: "jws_alg_unsupported", alg: alg || null };
+  // Refuse unknown critical extensions and non-standard signing-input variants.
+  if (Array.isArray(header.crit) && header.crit.length > 0) return { ok: false, reason: "jws_crit_unsupported" };
+  if (header.b64 === false) return { ok: false, reason: "jws_unencoded_payload_unsupported" };
+
+  const trustedKey = o.trusted_public_key ? toPublicKeyObject(o.trusted_public_key) : null;
+  const embeddedKey = !trustedKey && header.jwk ? toPublicKeyObject(header.jwk) : null;
+  const keyObject = trustedKey || embeddedKey;
+  if (!keyObject) return { ok: false, reason: "no_public_key" };
+
+  const valid = verifyWithAlg(alg, `${protectedB64}.${payloadB64}`, b64urlToBuffer(signatureB64), keyObject);
+  return trustResult(valid, keyObject, trustedKey ? "caller_supplied" : "embedded_self_asserted", o.expected_key_ref, alg, {
+    header,
+    payload_b64url: payloadB64
+  });
+}
+
+// Verify a detached signature over `material`. opts = { material, signature,
+// signature_encoding?, public_key, algorithm, expected_key_ref? }.
+function verifyDetachedSignature(opts) {
+  const o = opts && typeof opts === "object" ? opts : {};
+  const alg = typeof o.algorithm === "string" ? o.algorithm : null;
+  if (!alg || !JWS_ALG[alg]) return { ok: false, reason: "algorithm_unsupported", alg: alg || null };
+  const keyObject = toPublicKeyObject(o.public_key);
+  if (!keyObject) return { ok: false, reason: "no_public_key" };
+  if (o.material === undefined || o.material === null) return { ok: false, reason: "material_required" };
+  const material = Buffer.isBuffer(o.material) ? o.material : Buffer.from(String(o.material), "utf8");
+  let signature;
+  try {
+    const enc = o.signature_encoding === "hex" ? "hex" : o.signature_encoding === "base64url" ? null : "base64";
+    signature = enc ? Buffer.from(String(o.signature || ""), enc) : b64urlToBuffer(o.signature);
+  } catch (_) {
+    return { ok: false, reason: "signature_invalid" };
+  }
+  if (signature.length === 0) return { ok: false, reason: "signature_invalid" };
+  const valid = verifyWithAlg(alg, material, signature, keyObject);
+  return trustResult(valid, keyObject, "caller_supplied", o.expected_key_ref, alg);
+}
+
+function looksLikeCompactJws(s) {
+  return typeof s === "string" && /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(s.trim());
+}
+
+module.exports = { verifyJws, verifyDetachedSignature, toPublicKeyObject, isPrivateJwk, looksLikeCompactJws };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xoonya",
-  "version": "3.1.12",
+  "version": "3.1.14",
   "description": "Deterministic proof and review engine with post-quantum verification (Ed25519 + ML-DSA-65 hybrid) for receipts, handoffs, governance, and the native XNYA machine-evidence format. Verified live via the paid x402 lane.",
   "main": "index.js",
   "bin": {