xoonya 3.1.8 → 3.1.9

package/RELEASE_NOTES.md

@@ -1,10 +1,11 @@
-`xoonya` 3.1.8 is the synchronized release that keeps the proof line aligned with the runtime.
+`xoonya` 3.1.9 turns proof verification into a paid, pay-per-call machine service while keeping every existing free verification path and the deterministic proof engine unchanged.
 
-This release carries no change to the proof engine, the native XNYA standard, the verification methods, the conformance vectors, or the public proof surfaces. It exists to keep the proof package on the same synchronized line as the runtime, which in this cycle refreshed the public MCP executor's machine-readable description to lead with its pay-per-call story.
+This is the first release to carry the monetization backend: the proof verifier can now be offered as a metered service behind the runtime's x402 payment spine, and imported external proofs are verified cryptographically rather than only hash-bound.
 
 Highlights:
 
-- keeps the deterministic hash, sign, and verify core, the verification-class and strict-mode behavior, and the trust-root options unchanged
-- keeps the conformance and forgery-resistance vectors and the full verifier suite passing
-- keeps the canonical `https://naxytra.com/xoonya` public product URL and the synchronized package posture intact
-- tracks the runtime's discovery-description refresh so the proof and runtime packages stay on one release number
+- adds a bearer-authed `POST /execute` backend so proof verification can be sold per call behind the runtime's x402 settlement (fail-closed: 503 when the bearer is unset, 401 on a bad token, constant-time token comparison)
+- bills only on a positively-successful verification — unknown tool, unprocessable input, a structural reject, or a negative verdict all return non-2xx so the runtime never settles for a non-result
+- adds an optional paywall flag (`XOONYA_REQUIRE_PAID_VERIFICATION`, default off) that makes the free direct verify routes return 402 pointing to the paid lane, so the free HTTP path cannot undercut the paid product; `/execute` and `/health` always stay free
+- verifies imported external proofs (compact JWS and detached signatures) cryptographically with `node:crypto` instead of only binding their hash — a real cross-runtime verifier, with `alg:none`/alg-confusion/private-key material rejected
+- keeps the deterministic hash/sign/verify core, the native XNYA standard, the classical and post-quantum (ML-DSA-65, SLH-DSA-SHA2-128f) verification suites, the conformance and forgery-resistance vectors, strict-mode and trust-root options, and the canonical `https://naxytra.com/xoonya` product URL unchanged

package/lib/external_proof_verify.js

@@ -0,0 +1,189 @@
+"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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xoonya",
-  "version": "3.1.8",
+  "version": "3.1.9",
   "description": "Deterministic proof and review engine for receipts, handoffs, governance, and verification.",
   "main": "index.js",
   "bin": {
@@ -76,6 +76,9 @@
     "verify:package": "node scripts/verify_all.js",
     "verify:conformance": "node scripts/verify_vectors.js",
     "verify:external-proof-import-gate": "node scripts/verify_external_proof_import_gate.js",
+    "verify:external-proof-signature": "node scripts/verify_external_proof_signature.js",
+    "verify:paid-execute": "node scripts/verify_paid_execute.js",
+    "verify:paywall-flag": "node scripts/verify_paywall_flag.js",
     "verify:integrations": "node scripts/verify_integrations.js",
     "verify:tooling": "node scripts/verify_tooling.js",
     "verify:reference-python": "node scripts/verify_reference_python.js",
@@ -92,7 +95,7 @@
     "verify:service": "node scripts/verify_service.js",
     "verify:forgery-resistance": "node scripts/verify_forgery_resistance.js",
     "verify:release-candidate": "node scripts/verify_release_candidate.js",
-    "verify:all": "node scripts/verify_all.js && node scripts/verify_external_proof_import_gate.js && node scripts/verify_integrations.js && node scripts/verify_tooling.js && node scripts/verify_vectors.js && node scripts/verify_reference_python.js && node scripts/verify_reference_promotion_gate.js && node scripts/verify_reference_rust_scaffold.js && node scripts/verify_native_hybrid_design_gate.js && node scripts/verify_verification_services.js && node scripts/verify_trust_portability.js && node scripts/verify_control_plane_contracts.js && node scripts/verify_control_plane_routes.js && node scripts/verify_examples.js && node scripts/verify_service.js && node scripts/verify_forgery_resistance.js",
+    "verify:all": "node scripts/verify_all.js && node scripts/verify_external_proof_import_gate.js && node scripts/verify_integrations.js && node scripts/verify_tooling.js && node scripts/verify_vectors.js && node scripts/verify_reference_python.js && node scripts/verify_reference_promotion_gate.js && node scripts/verify_reference_rust_scaffold.js && node scripts/verify_native_hybrid_design_gate.js && node scripts/verify_verification_services.js && node scripts/verify_trust_portability.js && node scripts/verify_control_plane_contracts.js && node scripts/verify_control_plane_routes.js && node scripts/verify_examples.js && node scripts/verify_service.js && node scripts/verify_forgery_resistance.js && node scripts/verify_external_proof_signature.js && node scripts/verify_paid_execute.js && node scripts/verify_paywall_flag.js",
     "prepublishOnly": "npm run verify:release-candidate"
   }
 }