xoonya 2.6.0 → 2.8.0

package/reference/python/README.md

@@ -0,0 +1,35 @@
+# XNYA Python Candidate Reference
+
+This folder contains an independent Python candidate for the XNYA atom, payload profile, and line-rate frame vector floor.
+
+It does not import the JavaScript implementation. It is not yet a full `XNYA-compatible` reference implementation because full promotion also requires proof-envelope parity, round-trip generation, and conformance-mark review.
+
+Run:
+
+```bash
+python reference/python/verify_vectors.py
+```
+
+Current boundary:
+
+- implemented: XNYA atom v1/v2 creation, parsing, verification, deterministic reject codes
+- implemented: XNYP payload profile encoding/parsing
+- implemented: line-rate frame checksum vector
+- implemented: canonical event hash parity
+- implemented: receipt emission for external assertion, native digest, legacy OP_RETURN, and native anchored methods
+- implemented: proof-bundle build/verify parity for non-signed native methods
+- implemented: adversarial reason parity for non-signed proof-bundle checks
+- implemented when optional dependency exists: Ed25519 native signed verification with `cryptography`
+- implemented without optional dependency: deterministic `native_signature_crypto_dependency_missing` gate
+- not claimed: always-on native signed cryptographic verification
+- not claimed: secp256k1 or P-256 Python signature-suite verification
+- not claimed: PQ/hybrid verification
+- not claimed: external issuer, chain, custody, auth, or settlement truth
+
+Optional Ed25519 suite check:
+
+```bash
+npm run verify:reference-python-crypto
+```
+
+The crypto-enabled command creates a temporary isolated virtual environment, installs `requirements-optional.txt`, and requires the Ed25519 vector to verify.

package/reference/python/requirements-optional.txt

@@ -0,0 +1 @@
+cryptography>=42.0.0

package/reference/python/verify_vectors.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""Verify Python XNYA candidate helpers against the published vector floor."""
+
+from __future__ import annotations
+
+import json
+import pathlib
+import sys
+
+from xnya_reference import (
+    XnyaReferenceError,
+    build_proof_bundle,
+    canonicalize_event,
+    create_atom_v1,
+    create_atom_v2,
+    emit_receipt,
+    encode_payload_profile,
+    hash_event,
+    line_rate_frame_checksum,
+    parse_atom,
+    parse_payload_profile,
+    verify_proof_bundle,
+    verify_atom,
+    _ed25519_crypto_available,
+)
+
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+
+
+def load_json(relative_path: str) -> dict:
+    with (ROOT / relative_path).open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def assert_equal(actual, expected, message: str) -> None:
+    if actual != expected:
+        raise AssertionError(f"{message}: expected {expected!r}, got {actual!r}")
+
+
+def verify_atom_vectors() -> tuple[int, int]:
+    vectors_doc = load_json("vectors/native-atom-vectors.json")
+    identity = vectors_doc["identity_material_hex"]
+    payload = vectors_doc["payload_ascii"].encode("ascii")
+    positive_count = 0
+    adversarial_count = 0
+    for vector in vectors_doc["vectors"]:
+        actual = (
+            create_atom_v1(identity, payload if "with-payload" in vector["id"] else None)
+            if vector["atom_version"] == "xoonya-native-atom/v1"
+            else create_atom_v2(identity, payload if "with-payload" in vector["id"] else None)
+        )
+        assert_equal(actual["atom_hex"], vector["atom_hex"], f"{vector['id']} atom hex")
+        assert_equal(actual["agent_id"], vector["agent_id"], f"{vector['id']} agent id")
+        assert_equal(actual["payload_hash_sha256"], vector["payload_hash_sha256"], f"{vector['id']} payload hash")
+        parsed = parse_atom(vector["atom_hex"])
+        assert_equal(parsed.byte_length, vector["byte_length"], f"{vector['id']} byte length")
+        if "atom_hash_sha256" in vector:
+            assert_equal(parsed.atom_hash_sha256, vector["atom_hash_sha256"], f"{vector['id']} atom hash")
+        verification = verify_atom(vector["atom_hex"], identity_material_hex=identity)
+        assert_equal(verification["valid"], True, f"{vector['id']} verify")
+        positive_count += 1
+
+    for vector in vectors_doc["adversarial"]:
+        try:
+            result = verify_atom(
+                vector["atom_hex"],
+                identity_material_hex=vector.get("identity_material_hex"),
+                payload=vector.get("payload_ascii", "").encode("ascii") if "payload_ascii" in vector else None,
+            )
+            if result["valid"]:
+                raise AssertionError(f"{vector['id']} unexpectedly passed")
+            assert_equal(result["error_code"], vector["expected_error_code"], f"{vector['id']} error code")
+        except XnyaReferenceError as error:
+            assert_equal(error.code, vector["expected_error_code"], f"{vector['id']} error code")
+        adversarial_count += 1
+    return positive_count, adversarial_count
+
+
+def verify_payload_profile_vectors() -> tuple[int, int]:
+    vectors_doc = load_json("vectors/native-payload-profile-vectors.json")
+    profile_vector = vectors_doc["profile_vector"]
+    encoded = encode_payload_profile(profile_vector["input"])
+    expected = profile_vector["expected"]
+    assert_equal(encoded["canonical_bytes_hex"], expected["canonical_bytes_hex"], "payload profile canonical bytes")
+    assert_equal(encoded["payload_hash_sha256"], expected["payload_hash_sha256"], "payload profile hash")
+    assert_equal(encoded["schema_hash_sha256"], expected["schema_hash_sha256"], "payload profile schema hash")
+    assert_equal(encoded["field_order"], expected["field_order"], "payload profile field order")
+    parsed = parse_payload_profile(expected["canonical_bytes_hex"])
+    assert_equal(parsed["payload_hash_sha256"], expected["payload_hash_sha256"], "payload profile parsed hash")
+
+    frame_vector = vectors_doc["line_rate_frame_vector"]
+    checksum = line_rate_frame_checksum(bytes.fromhex(frame_vector["atom_hex"]))
+    assert_equal(checksum, frame_vector["checksum_hex"], "line-rate frame checksum")
+    assert_equal(frame_vector["atom_hex"] + checksum, frame_vector["frame_hex"], "line-rate frame hex")
+    return 1, 1
+
+
+def verify_proof_vectors() -> tuple[int, int, int, int]:
+    vectors_doc = load_json("vectors/conformance-vectors.json")
+    positive_count = 0
+    verified_count = 0
+    signed_crypto_gated_count = 0
+    signed_crypto_verified_count = 0
+    signed_dependency_missing_count = 0
+    anchored_count = 0
+    ed25519_available = _ed25519_crypto_available()
+    for vector in vectors_doc["vectors"]:
+        event = vector["event"]
+        expected = vector["expected"]
+        canonical_event = canonicalize_event(event)
+        assert_equal(hash_event(canonical_event), expected["event_commitment"], f"{vector['id']} event commitment")
+        options = dict(vector.get("receipt_options", {}))
+        if expected["receipt"].get("algorithm") == "xoonya-native-signed-v1":
+            assert_equal(expected["receipt"]["native_proof"]["method"], "xoonya-native-signed-v1", f"{vector['id']} native signed method")
+            assert_equal(expected["receipt"]["native_proof"]["signature_suite"], options.get("signature_suite"), f"{vector['id']} native signed suite")
+            bundle = {
+                "version": expected["proof_bundle_version"],
+                "ceb": canonical_event,
+                "receipt": expected["receipt"],
+            }
+            verification = verify_proof_bundle(bundle)
+            if ed25519_available:
+                assert_equal(verification["valid"], True, f"{vector['id']} native signed verification")
+                assert_equal(verification["verification_state"], "verified_native_signature", f"{vector['id']} native signed state")
+                signed_crypto_verified_count += 1
+                verified_count += 1
+            else:
+                assert_equal(verification["valid"], False, f"{vector['id']} native signed dependency gate")
+                assert_equal(verification["reason"], "native_signature_crypto_dependency_missing", f"{vector['id']} native signed dependency reason")
+                signed_dependency_missing_count += 1
+                signed_crypto_gated_count += 1
+            positive_count += 1
+            continue
+        if expected["receipt"].get("algorithm") == "xoonya-native-anchored-v1":
+            options["anchors"] = vector["anchors"]
+        receipt = emit_receipt(canonical_event, options)
+        assert_equal(receipt, expected["receipt"], f"{vector['id']} emitted receipt")
+        bundle_input = {"event": event, "receipt_options": options}
+        if "anchors" in vector:
+            bundle_input["anchors"] = vector["anchors"]
+        bundle = build_proof_bundle(bundle_input)
+        assert_equal(bundle["version"], expected["proof_bundle_version"], f"{vector['id']} proof bundle version")
+        assert_equal(bundle["receipt"], expected["receipt"], f"{vector['id']} proof bundle receipt")
+        verification = verify_proof_bundle(bundle)
+        assert_equal(verification["valid"], True, f"{vector['id']} proof bundle verification")
+        if expected["receipt"].get("algorithm") == "xoonya-native-anchored-v1":
+            anchored_count += 1
+        verified_count += 1
+        positive_count += 1
+
+    adversarial_doc = load_json("vectors/adversarial-vectors.json")
+    adversarial_count = 0
+    for vector in adversarial_doc["vectors"]:
+        if vector["kind"] == "canonicalize_event_error":
+            try:
+                canonicalize_event(vector["event"])
+                raise AssertionError(f"{vector['id']} unexpectedly passed")
+            except ValueError as error:
+                assert_equal(str(error), vector["expected_reason"], f"{vector['id']} reason")
+            adversarial_count += 1
+            continue
+        if vector["kind"] != "verify_bundle_reason":
+            continue
+        result = verify_proof_bundle(vector["bundle"])
+        expected_reason = vector["expected_reason"]
+        if expected_reason == "native_signature_invalid" and not ed25519_available:
+            expected_reason = "native_signature_crypto_dependency_missing"
+        assert_equal(result["valid"], False, f"{vector['id']} adversarial should fail")
+        assert_equal(result["reason"], expected_reason, f"{vector['id']} adversarial reason")
+        adversarial_count += 1
+    return positive_count, verified_count, signed_crypto_gated_count, adversarial_count + anchored_count, signed_crypto_verified_count, signed_dependency_missing_count
+
+
+def main() -> int:
+    atom_positive, atom_adversarial = verify_atom_vectors()
+    payload_positive, frame_positive = verify_payload_profile_vectors()
+    (
+        proof_positive,
+        proof_verified,
+        signed_crypto_gated,
+        proof_adversarial_and_anchor,
+        signed_crypto_verified,
+        signed_dependency_missing,
+    ) = verify_proof_vectors()
+    summary = {
+        "ok": True,
+        "product": "xoonya",
+        "category": "xnya-python-reference-vector-parity",
+        "status": "candidate_atom_payload_and_proof_bundle_vector_parity_passed",
+        "atom_vector_count": atom_positive,
+        "atom_adversarial_count": atom_adversarial,
+        "payload_profile_vector_count": payload_positive,
+        "line_rate_frame_vector_count": frame_positive,
+        "proof_bundle_vector_count": proof_positive,
+        "proof_bundle_verified_vector_count": proof_verified,
+        "native_signed_crypto_gated_vector_count": signed_crypto_gated,
+        "native_signed_crypto_verified_vector_count": signed_crypto_verified,
+        "native_signature_crypto_dependency_missing_count": signed_dependency_missing,
+        "verified_signature_suite_count": 1 if signed_crypto_verified else 0,
+        "proof_adversarial_and_anchor_check_count": proof_adversarial_and_anchor,
+        "boundary": "python_candidate_verifies_ed25519_native_signed_vectors_when_cryptography_dependency_is_available_other_signature_suites_stay_gated"
+    }
+    print(json.dumps(summary, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())