xoonya 2.7.0 → 2.9.0

package/reference/python/xnya_reference.py

@@ -0,0 +1,810 @@
+"""Independent Python candidate reference helpers for XNYA atom/payload vectors.
+
+This module intentionally does not import or shell out to the JavaScript
+implementation. It is a vector-parity scaffold, not yet a full
+XNYA-compatible reference implementation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import base64
+from dataclasses import dataclass
+from typing import Any
+
+
+XNYA_MAGIC = bytes.fromhex("584e5941")
+VERSION_V1 = 0x01
+VERSION_V2 = 0x02
+VALID_RECORD_TYPES = {0x01, 0x02, 0x03}
+ZERO_HASH32 = bytes(32)
+IDENTITY_PREFIXES = {"01", "02", "03", "04", "05", "06", "07"}
+
+XNYA_DS_AGENT_V1 = b"xoonya:agent:v1:"
+XNYA_DS_AGENT_V2 = b"xoonya:agent:v2:"
+XNYA_DS_PAYLOAD_V1 = b"xoonya:payload:v1:"
+XNYA_DS_PAYLOAD_V2 = b"xoonya:payload:v2:"
+XNYA_DS_PAYLOAD_PROFILE_V1 = b"xoonya:payload-profile:v1:"
+XNYA_DS_LINE_RATE_FRAME_V1 = b"xoonya:line-rate-frame:v1:"
+CANONICAL_EVENT_BUNDLE_VERSION = "canonical-event-bundle/v1"
+CANONICAL_RECEIPT_VERSION = "receipt/v1"
+PROOF_BUNDLE_VERSION = "proof-bundle/v1"
+XOONYA_NATIVE_SHA256_METHOD = "xoonya-native-sha256-v1"
+XOONYA_NATIVE_SIGNED_METHOD = "xoonya-native-signed-v1"
+XOONYA_NATIVE_ANCHORED_METHOD = "xoonya-native-anchored-v1"
+XOONYA_NATIVE_HYBRID_METHOD = "xoonya-native-hybrid-v1"
+XOONYA_NATIVE_PROOF_FORMAT_VERSION = "xoonya-native-proof/v1"
+LEGACY_OPRETURN_METHOD = "legacy-opreturn-v1"
+DETACHED_ASSERTION_METHOD = "detached-assertion-v1"
+EXTERNAL_ASSERTION_METHODS = {
+    "detached-assertion-v1",
+    "jwt-assertion-v1",
+    "did-vc-v1",
+    "sd-jwt-vc-v1",
+    "signed-envelope-v1",
+    "partner-proof-envelope-v1",
+}
+
+FIELD_TYPES = {
+    "bytes32": (1, 32),
+    "bytes20": (2, 20),
+    "uint64": (3, 8),
+    "utf8": (4, None),
+    "bool": (5, 1),
+}
+FIELD_TYPES_BY_ID = {spec[0]: (name, spec[1]) for name, spec in FIELD_TYPES.items()}
+
+
+class XnyaReferenceError(ValueError):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class ParsedAtom:
+    atom_version: str
+    spec_version: str
+    byte_length: int
+    record_type_hex: str
+    agent_id: str
+    payload_hash_sha256: str
+    atom_hash_sha256: str
+    atom_hex: str
+
+
+def sha256(data: bytes) -> bytes:
+    return hashlib.sha256(data).digest()
+
+
+def sha256_hex(data: bytes) -> str:
+    return sha256(data).hex()
+
+
+def hash160_hex(data: bytes) -> str:
+    return hashlib.new("ripemd160", sha256(data)).hexdigest()
+
+
+def canonicalize(value: Any) -> str:
+    if isinstance(value, list):
+        return "[" + ",".join(canonicalize(item) for item in value) + "]"
+    if isinstance(value, dict):
+        return "{" + ",".join(
+            json.dumps(str(key), separators=(",", ":"), ensure_ascii=False) + ":" + canonicalize(value[key])
+            for key in sorted(value.keys())
+        ) + "}"
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+
+
+def canonical_json_sha256_hex(value: Any) -> str:
+    return sha256_hex(canonicalize(value).encode("utf-8"))
+
+
+def normalize_string(value: Any) -> str:
+    return str("" if value is None else value).strip()
+
+
+def normalize_string_array(values: Any, label: str) -> list[str] | None:
+    if values is None:
+        return None
+    if not isinstance(values, list):
+        raise ValueError(f"{label} must be an array")
+    normalized = [normalize_string(value) for value in values]
+    normalized = [value for value in normalized if value]
+    return normalized or None
+
+
+def canonicalize_event(event: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(event, dict):
+        raise ValueError("event must be an object")
+    normalized = {
+        "version": normalize_string(event.get("version") or CANONICAL_EVENT_BUNDLE_VERSION),
+        "domain_id": normalize_string(event.get("domain_id")),
+        "sequence": normalize_string(event.get("sequence")),
+        "actor_id": normalize_string(event.get("actor_id")),
+        "adapter_source": normalize_string(event.get("adapter_source")),
+        "event_type": normalize_string(event.get("event_type")),
+        "event_hash": normalize_string(event.get("event_hash")).lower(),
+    }
+    for key, value in normalized.items():
+        if not value:
+            raise ValueError(f"event.{key} required")
+    if normalized["version"] != CANONICAL_EVENT_BUNDLE_VERSION:
+        raise ValueError(f"event.version must be {CANONICAL_EVENT_BUNDLE_VERSION}")
+    assert_hex(normalized["event_hash"], "event_hash_invalid", "event.event_hash must be 32 byte hex")
+
+    timestamp_ns = normalize_string(event.get("timestamp_ns"))
+    if timestamp_ns:
+        normalized["timestamp_ns"] = timestamp_ns
+    parent_refs = normalize_string_array(event.get("parent_refs"), "event.parent_refs")
+    if parent_refs:
+        normalized["parent_refs"] = parent_refs
+    capability_refs = normalize_string_array(event.get("capability_refs"), "event.capability_refs")
+    if capability_refs:
+        normalized["capability_refs"] = capability_refs
+    attestation_ref = normalize_string(event.get("attestation_ref"))
+    if attestation_ref:
+        normalized["attestation_ref"] = attestation_ref
+    semantic_slots = event.get("semantic_slots")
+    if semantic_slots is not None:
+        if not isinstance(semantic_slots, dict):
+            raise ValueError("event.semantic_slots must be an object")
+        normalized["semantic_slots"] = semantic_slots
+    return normalized
+
+
+def hash_event(event: dict[str, Any]) -> str:
+    return canonical_json_sha256_hex(canonicalize_event(event))
+
+
+def build_canonical_receipt_signing_material(receipt: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "agent_identity": receipt.get("agent_identity"),
+        "domain_id": receipt.get("domain_id"),
+        "event_commitment": receipt.get("event_commitment"),
+        "receipt_id": receipt.get("receipt_id"),
+        "sequence": receipt.get("sequence"),
+        "version": receipt.get("version"),
+    }
+
+
+def create_legacy_receipt(identity_material_hex: str, payload: bytes) -> dict[str, Any]:
+    material = bytes.fromhex(assert_hex(identity_material_hex, "non_hex", "identityMaterialHex must be hex"))
+    agent_id = hash160_hex(material)
+    payload_hash = sha256_hex(payload) if payload else ZERO_HASH32.hex()
+    opreturn_hex = "50524654" + "01" + "01" + agent_id + payload_hash
+    return {
+        "agent_id": agent_id,
+        "opreturn_hex": opreturn_hex,
+        "payload_hash": payload_hash,
+        "spec_version": "v1",
+    }
+
+
+def verify_legacy_receipt(opreturn_hex: str, payload: bytes) -> dict[str, Any]:
+    normalized = str(opreturn_hex or "").strip().lower()
+    try:
+        bytes.fromhex(normalized)
+    except ValueError:
+        return {"valid": False, "reason": "non_hex", "agent_id": None}
+    if len(normalized) != 116:
+        return {"valid": False, "reason": "invalid_length", "agent_id": None}
+    if normalized[:8] != "50524654":
+        return {"valid": False, "reason": "bad_magic", "agent_id": None}
+    if normalized[8:10] != "01":
+        return {"valid": False, "reason": "bad_version", "agent_id": None}
+    if normalized[10:12] not in {"01", "02", "03"}:
+        return {"valid": False, "reason": "bad_type", "agent_id": None}
+    expected_payload = sha256_hex(payload) if payload else ZERO_HASH32.hex()
+    if normalized[52:116] != expected_payload:
+        return {"valid": False, "reason": "payload_mismatch", "agent_id": normalized[12:52]}
+    return {"valid": True, "reason": None, "agent_id": normalized[12:52]}
+
+
+def select_receipt_algorithm(options: dict[str, Any], compatibility: dict[str, Any] | None) -> str:
+    requested = normalize_string(options.get("algorithm"))
+    if requested:
+        return requested
+    if compatibility:
+        return LEGACY_OPRETURN_METHOD
+    if options.get("signature") is not None:
+        return DETACHED_ASSERTION_METHOD
+    return XOONYA_NATIVE_SHA256_METHOD
+
+
+def build_native_receipt_signature(receipt: dict[str, Any], canonical_event: dict[str, Any]) -> str:
+    material = {
+        "method": XOONYA_NATIVE_SHA256_METHOD,
+        "receipt_signing_material": build_canonical_receipt_signing_material(receipt),
+        "event_commitment": hash_event(canonical_event),
+    }
+    return XOONYA_NATIVE_SHA256_METHOD + ":" + sha256_hex(canonicalize(material).encode("utf-8"))
+
+
+def _base64url_decode(value: str) -> bytes:
+    normalized = normalize_string(value)
+    padded = normalized + ("=" * ((4 - (len(normalized) % 4)) % 4))
+    return base64.urlsafe_b64decode(padded.encode("ascii"))
+
+
+def _spki_der_from_pem(public_key_pem: str) -> bytes:
+    pem = str(public_key_pem or "").replace("\r\n", "\n").strip()
+    begin = "-----BEGIN PUBLIC KEY-----"
+    end = "-----END PUBLIC KEY-----"
+    if begin not in pem or end not in pem:
+        raise ValueError("native public key must be SPKI PEM")
+    body = pem.split(begin, 1)[1].split(end, 1)[0]
+    return base64.b64decode("".join(body.split()))
+
+
+def _ed25519_crypto_available() -> bool:
+    try:
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey  # noqa: F401
+        from cryptography.hazmat.primitives.serialization import load_pem_public_key  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+def build_native_signed_proof_material(receipt: dict[str, Any], canonical_event: dict[str, Any], proof_descriptor: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "identity_ref": proof_descriptor.get("identity_ref"),
+        "method": XOONYA_NATIVE_SIGNED_METHOD,
+        "public_key_ref": proof_descriptor.get("public_key_ref"),
+        "receipt_signing_material": build_canonical_receipt_signing_material(receipt),
+        "event_commitment": hash_event(canonical_event),
+        "signature_suite": proof_descriptor.get("signature_suite"),
+        "standard_version": XOONYA_NATIVE_PROOF_FORMAT_VERSION,
+    }
+
+
+def verify_native_signed_receipt_proof(receipt: dict[str, Any], ceb: dict[str, Any]) -> dict[str, Any]:
+    proof = receipt.get("native_proof")
+    if not isinstance(proof, dict):
+        return {"valid": False, "reason": "native_proof_missing"}
+    if normalize_string(proof.get("method")) != XOONYA_NATIVE_SIGNED_METHOD:
+        return {"valid": False, "reason": "native_proof_method_mismatch"}
+    signature_suite = normalize_string(proof.get("signature_suite"))
+    if signature_suite != "ed25519":
+        return {"valid": False, "reason": "native_signature_suite_crypto_unavailable_in_python_candidate"}
+    identity_ref = normalize_string(proof.get("identity_ref"))
+    if not identity_ref:
+        return {"valid": False, "reason": "native_identity_ref_missing"}
+    public_key_material = proof.get("public_key_material")
+    if not isinstance(public_key_material, dict):
+        return {"valid": False, "reason": "native_public_key_material_missing"}
+    if normalize_string(public_key_material.get("format")) != "spki-pem":
+        return {"valid": False, "reason": "native_public_key_format_mismatch"}
+    try:
+        der = _spki_der_from_pem(public_key_material.get("value", ""))
+    except Exception as error:
+        return {"valid": False, "reason": str(error)}
+    expected_public_key_ref = "ed25519-spki-sha256:" + sha256_hex(der)
+    if normalize_string(proof.get("public_key_ref")) != expected_public_key_ref:
+        return {"valid": False, "reason": "native_public_key_ref_mismatch"}
+    proof_material = proof.get("proof_material")
+    if not isinstance(proof_material, dict):
+        return {"valid": False, "reason": "native_proof_material_missing"}
+    signature = normalize_string(proof_material.get("signature"))
+    if not signature:
+        return {"valid": False, "reason": "native_signature_missing"}
+    if normalize_string(receipt.get("signature")) != XOONYA_NATIVE_SIGNED_METHOD + ":ed25519:" + signature:
+        return {"valid": False, "reason": "signature_native_signed_mismatch"}
+    signing_material = build_native_signed_proof_material(receipt, ceb, {
+        "identity_ref": identity_ref,
+        "public_key_ref": expected_public_key_ref,
+        "signature_suite": "ed25519",
+    })
+    signing_bytes = canonicalize(signing_material).encode("utf-8")
+    if normalize_string(proof_material.get("signing_material_sha256")).lower() != sha256_hex(signing_bytes):
+        return {"valid": False, "reason": "native_signing_material_hash_mismatch"}
+    if not _ed25519_crypto_available():
+        return {
+            "valid": False,
+            "reason": "native_signature_crypto_dependency_missing",
+            "dependency": "cryptography",
+        }
+    try:
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+        from cryptography.hazmat.primitives.serialization import load_pem_public_key
+
+        public_key = load_pem_public_key(public_key_material["value"].encode("utf-8"))
+        if not isinstance(public_key, Ed25519PublicKey):
+            return {"valid": False, "reason": "native_public_key_suite_mismatch"}
+        public_key.verify(_base64url_decode(signature), signing_bytes)
+    except Exception:
+        return {"valid": False, "reason": "native_signature_invalid"}
+    return {
+        "valid": True,
+        "verification_state": "verified_native_signature",
+        "signature_suite": "ed25519",
+    }
+
+
+def assert_hex(value: str, code: str, message: str) -> str:
+    normalized = str(value or "").strip().lower()
+    if not normalized or len(normalized) % 2 != 0:
+        raise XnyaReferenceError(code, message)
+    try:
+        bytes.fromhex(normalized)
+    except ValueError as exc:
+        raise XnyaReferenceError(code, message) from exc
+    return normalized
+
+
+def normalize_identity_material(identity_material_hex: str) -> bytes:
+    material_hex = assert_hex(
+        identity_material_hex,
+        "identity_unsupported_type_prefix",
+        "identityMaterialHex has unsupported identity type prefix",
+    )
+    prefix = material_hex[:2]
+    if prefix not in IDENTITY_PREFIXES:
+        raise XnyaReferenceError(
+            "identity_unsupported_type_prefix",
+            "identityMaterialHex has unsupported identity type prefix",
+        )
+    if len(material_hex) == 2:
+        raise XnyaReferenceError(
+            "identity_missing_raw_bytes",
+            "identityMaterialHex must include raw identity bytes",
+        )
+    return bytes.fromhex(material_hex)
+
+
+def hash_payload(payload: bytes | None, domain: bytes) -> bytes:
+    if not payload:
+        return ZERO_HASH32
+    digest = sha256(domain + payload)
+    if digest == ZERO_HASH32:
+        raise XnyaReferenceError("payload_hash_mismatch", "payload hash cannot equal absent sentinel")
+    return digest
+
+
+def create_atom_v1(identity_material_hex: str, payload: bytes | None, record_type_hex: str = "01") -> dict[str, Any]:
+    material = normalize_identity_material(identity_material_hex)
+    record_type = int(record_type_hex, 16)
+    if record_type not in VALID_RECORD_TYPES:
+        raise XnyaReferenceError("atom_unsupported_record_type", "atomHex has unsupported record type")
+    agent_id = bytes.fromhex(hash160_hex(XNYA_DS_AGENT_V1 + material))
+    payload_hash = hash_payload(payload, XNYA_DS_PAYLOAD_V1)
+    atom = XNYA_MAGIC + bytes([VERSION_V1, record_type]) + agent_id + payload_hash
+    return {
+        "atom_hex": atom.hex(),
+        "atom_version": "xoonya-native-atom/v1",
+        "spec_version": "v1",
+        "byte_length": len(atom),
+        "record_type_hex": f"{record_type:02x}",
+        "agent_id": agent_id.hex(),
+        "payload_hash_sha256": payload_hash.hex(),
+        "atom_hash_sha256": sha256_hex(atom),
+    }
+
+
+def create_atom_v2(identity_material_hex: str, payload: bytes | None, record_type_hex: str = "01") -> dict[str, Any]:
+    material = normalize_identity_material(identity_material_hex)
+    record_type = int(record_type_hex, 16)
+    if record_type not in VALID_RECORD_TYPES:
+        raise XnyaReferenceError("atom_unsupported_record_type", "atomHex has unsupported record type")
+    agent_id = sha256(XNYA_DS_AGENT_V2 + material)
+    payload_hash = hash_payload(payload, XNYA_DS_PAYLOAD_V2)
+    atom = XNYA_MAGIC + bytes([VERSION_V2, record_type]) + agent_id + payload_hash
+    return {
+        "atom_hex": atom.hex(),
+        "atom_version": "xoonya-native-atom/v2",
+        "spec_version": "v2",
+        "byte_length": len(atom),
+        "record_type_hex": f"{record_type:02x}",
+        "agent_id": agent_id.hex(),
+        "payload_hash_sha256": payload_hash.hex(),
+        "atom_hash_sha256": sha256_hex(atom),
+    }
+
+
+def parse_atom(atom_hex: str) -> ParsedAtom:
+    hex_value = str(atom_hex or "").strip().lower()
+    try:
+        atom = bytes.fromhex(hex_value)
+    except ValueError as exc:
+        raise XnyaReferenceError("atom_hex_not_hex", "atomHex must be hex") from exc
+    if len(atom) not in (58, 70):
+        raise XnyaReferenceError("atom_unsupported_length", "atomHex must be a supported Xoonya native atom")
+    if atom[:4] != XNYA_MAGIC:
+        raise XnyaReferenceError("atom_bad_magic", "atomHex has bad Xoonya native atom magic")
+    record_type = atom[5]
+    if record_type not in VALID_RECORD_TYPES:
+        raise XnyaReferenceError("atom_unsupported_record_type", "atomHex has unsupported record type")
+    version = atom[4]
+    if version == VERSION_V1 and len(atom) == 58:
+        return ParsedAtom(
+            atom_version="xoonya-native-atom/v1",
+            spec_version="v1",
+            byte_length=58,
+            record_type_hex=f"{record_type:02x}",
+            agent_id=atom[6:26].hex(),
+            payload_hash_sha256=atom[26:58].hex(),
+            atom_hash_sha256=sha256_hex(atom),
+            atom_hex=hex_value,
+        )
+    if version == VERSION_V2 and len(atom) == 70:
+        return ParsedAtom(
+            atom_version="xoonya-native-atom/v2",
+            spec_version="v2",
+            byte_length=70,
+            record_type_hex=f"{record_type:02x}",
+            agent_id=atom[6:38].hex(),
+            payload_hash_sha256=atom[38:70].hex(),
+            atom_hash_sha256=sha256_hex(atom),
+            atom_hex=hex_value,
+        )
+    raise XnyaReferenceError("atom_version_length_mismatch", "atomHex/version length mismatch")
+
+
+def verify_atom(atom_hex: str, *, identity_material_hex: str | None = None, payload: bytes | None = None) -> dict[str, Any]:
+    parsed = parse_atom(atom_hex)
+    if identity_material_hex is not None:
+        material = normalize_identity_material(identity_material_hex)
+        expected_agent_id = (
+            hash160_hex(XNYA_DS_AGENT_V1 + material)
+            if parsed.spec_version == "v1"
+            else sha256_hex(XNYA_DS_AGENT_V2 + material)
+        )
+        if parsed.agent_id != expected_agent_id:
+            return {"valid": False, "reason": "agent_id_mismatch", "error_code": "agent_id_mismatch"}
+    if payload is not None:
+        expected_payload_hash = (
+            hash_payload(payload, XNYA_DS_PAYLOAD_V1)
+            if parsed.spec_version == "v1"
+            else hash_payload(payload, XNYA_DS_PAYLOAD_V2)
+        ).hex()
+        if parsed.payload_hash_sha256 != expected_payload_hash:
+            return {"valid": False, "reason": "payload_hash_mismatch", "error_code": "payload_hash_mismatch"}
+    return {"valid": True, "reason": None, "error_code": None, "parsed": parsed}
+
+
+def _encode_field(field: dict[str, Any]) -> tuple[int, int, bytes]:
+    field_id = int(field.get("field_id", field.get("id")))
+    field_type = str(field.get("field_type", field.get("type"))).strip()
+    if field_id < 1 or field_id > 0xFFFF:
+        raise ValueError("payload profile field_id must be uint16")
+    if field_type not in FIELD_TYPES:
+        raise ValueError("payload profile field_type unsupported")
+    field_type_id, fixed_len = FIELD_TYPES[field_type]
+    if field_type in ("bytes32", "bytes20"):
+        value = bytes.fromhex(str(field.get("value_hex", field.get("value"))).strip().lower())
+        if len(value) != fixed_len:
+            raise ValueError("payload profile fixed field length mismatch")
+    elif field_type == "uint64":
+        n = int(field.get("value"))
+        if n < 0 or n > 0xFFFFFFFFFFFFFFFF:
+            raise ValueError("payload profile uint64 out of range")
+        value = n.to_bytes(8, "big")
+    elif field_type == "utf8":
+        value = str(field.get("value", "")).encode("utf-8")
+        if not value or len(value) > 1024:
+            raise ValueError("payload profile utf8 length unsupported")
+    elif field_type == "bool":
+        raw = field.get("value")
+        if not isinstance(raw, bool):
+            raise ValueError("payload profile bool must be boolean")
+        value = b"\x01" if raw else b"\x00"
+    return field_id, field_type_id, value
+
+
+def encode_payload_profile(input_value: dict[str, Any]) -> dict[str, Any]:
+    schema_ref = str(input_value.get("schema_ref", input_value.get("schemaRef", "xoonya.payload.schema.generic.v1"))).strip()
+    schema_hash = sha256_hex(f"xoonya:payload-schema:v1:{schema_ref}".encode("utf-8"))
+    encoded_fields = sorted((_encode_field(field) for field in input_value["fields"]), key=lambda item: (item[0], item[1]))
+    canonical = bytearray()
+    canonical.extend(b"XNYP")
+    canonical.append(1)
+    canonical.extend(bytes.fromhex(schema_hash))
+    canonical.append(len(encoded_fields))
+    for field_id, field_type_id, value in encoded_fields:
+        canonical.extend(field_id.to_bytes(2, "big"))
+        canonical.append(field_type_id)
+        canonical.extend(len(value).to_bytes(2, "big"))
+        canonical.extend(value)
+    canonical_bytes = bytes(canonical)
+    return {
+        "profile": "xoonya-native-payload-profile/v1",
+        "schema_ref": schema_ref,
+        "schema_hash_sha256": schema_hash,
+        "field_count": len(encoded_fields),
+        "canonical_bytes_hex": canonical_bytes.hex(),
+        "payload_hash_sha256": sha256_hex(XNYA_DS_PAYLOAD_PROFILE_V1 + canonical_bytes),
+        "field_order": [field_id for field_id, _, _ in encoded_fields],
+    }
+
+
+def parse_payload_profile(canonical_bytes_hex: str) -> dict[str, Any]:
+    canonical = bytes.fromhex(canonical_bytes_hex)
+    if len(canonical) < 38:
+        raise ValueError("payload profile bytes too short")
+    if canonical[:4] != b"XNYP":
+        raise ValueError("payload profile magic mismatch")
+    if canonical[4] != 1:
+        raise ValueError("payload profile version unsupported")
+    field_count = canonical[37]
+    offset = 38
+    fields = []
+    for _ in range(field_count):
+        if offset + 5 > len(canonical):
+            raise ValueError("payload profile truncated field header")
+        field_id = int.from_bytes(canonical[offset : offset + 2], "big")
+        field_type_id = canonical[offset + 2]
+        length = int.from_bytes(canonical[offset + 3 : offset + 5], "big")
+        offset += 5
+        value = canonical[offset : offset + length]
+        offset += length
+        if field_type_id not in FIELD_TYPES_BY_ID:
+            raise ValueError("payload profile field type unsupported")
+        field_type, fixed_len = FIELD_TYPES_BY_ID[field_type_id]
+        if fixed_len is not None and len(value) != fixed_len:
+            raise ValueError("payload profile fixed field length mismatch")
+        fields.append({"field_id": field_id, "field_type": field_type, "field_type_id": field_type_id, "value_hex": value.hex()})
+    if offset != len(canonical):
+        raise ValueError("payload profile trailing bytes")
+    sorted_fields = sorted(fields, key=lambda item: (item["field_id"], item["field_type_id"]))
+    if fields != sorted_fields:
+        raise ValueError("payload profile fields not canonical order")
+    return {
+        "profile": "xoonya-native-payload-profile/v1",
+        "schema_hash_sha256": canonical[5:37].hex(),
+        "field_count": field_count,
+        "fields": fields,
+        "canonical_bytes_hex": canonical.hex(),
+        "payload_hash_sha256": sha256_hex(XNYA_DS_PAYLOAD_PROFILE_V1 + canonical),
+    }
+
+
+def line_rate_frame_checksum(atom: bytes) -> str:
+    return sha256_hex(XNYA_DS_LINE_RATE_FRAME_V1 + atom)[:4]
+
+
+def normalize_anchor_refs(anchor_refs: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    if not isinstance(anchor_refs, list) or not anchor_refs:
+        raise ValueError("native anchors must be a non-empty array")
+    normalized = []
+    for index, anchor in enumerate(anchor_refs):
+        if not isinstance(anchor, dict):
+            raise ValueError(f"native anchors[{index}] must be an object")
+        entry = {
+            "anchor_id": normalize_string(anchor.get("anchor_id") or anchor.get("id")),
+            "anchor_kind": normalize_string(anchor.get("anchor_kind") or anchor.get("kind")),
+            "anchor_ref": normalize_string(anchor.get("anchor_ref") or anchor.get("ref")),
+            "anchor_hash_sha256": normalize_string(anchor.get("anchor_hash_sha256") or anchor.get("hash_sha256") or anchor.get("anchor_hash")).lower(),
+        }
+        if not entry["anchor_id"]:
+            raise ValueError(f"native anchors[{index}].anchor_id required")
+        if not entry["anchor_kind"]:
+            raise ValueError(f"native anchors[{index}].anchor_kind required")
+        if not entry["anchor_ref"]:
+            raise ValueError(f"native anchors[{index}].anchor_ref required")
+        assert_hex(entry["anchor_hash_sha256"], "anchor_hash_invalid", f"native anchors[{index}].anchor_hash_sha256 must be 32 byte hex")
+        for key in ("network", "finality_state", "observed_at_iso", "provider_ref", "inclusion_proof_ref"):
+            value = normalize_string(anchor.get(key))
+            if value:
+                entry[key] = value
+        normalized.append(entry)
+    return sorted(normalized, key=canonicalize)
+
+
+def build_native_anchor_binding_material(receipt: dict[str, Any], canonical_event: dict[str, Any], anchor_refs: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "anchor_refs": normalize_anchor_refs(anchor_refs),
+        "base_method": XOONYA_NATIVE_SHA256_METHOD,
+        "event_commitment": hash_event(canonical_event),
+        "method": XOONYA_NATIVE_ANCHORED_METHOD,
+        "receipt_signing_material": build_canonical_receipt_signing_material(receipt),
+        "standard_version": "xoonya-native-proof/v1",
+    }
+
+
+def build_native_anchored_receipt_proof(receipt: dict[str, Any], canonical_event: dict[str, Any], anchors: list[dict[str, Any]]) -> dict[str, Any]:
+    anchor_refs = normalize_anchor_refs(anchors)
+    binding_material = build_native_anchor_binding_material(receipt, canonical_event, anchor_refs)
+    binding_hash = sha256_hex(canonicalize(binding_material).encode("utf-8"))
+    anchor_root_hash = canonical_json_sha256_hex(anchor_refs)
+    return {
+        "method": XOONYA_NATIVE_ANCHORED_METHOD,
+        "base_method": XOONYA_NATIVE_SHA256_METHOD,
+        "anchor_refs": anchor_refs,
+        "proof_material": {
+            "anchor_root_sha256": anchor_root_hash,
+            "binding_material_sha256": binding_hash,
+        },
+        "compact_signature": XOONYA_NATIVE_ANCHORED_METHOD + ":" + binding_hash,
+    }
+
+
+def emit_receipt(event: dict[str, Any], options: dict[str, Any] | None = None) -> dict[str, Any]:
+    options = options or {}
+    canonical_event = canonicalize_event(event)
+    event_commitment = hash_event(canonical_event)
+    agent_identity = normalize_string(options.get("agent_identity") or options.get("agentIdentity") or canonical_event["actor_id"])
+    if not agent_identity:
+        raise ValueError("agent_identity required")
+    compatibility = None
+    legacy_identity = options.get("legacy_identity_material_hex")
+    if legacy_identity:
+        legacy_receipt = create_legacy_receipt(str(legacy_identity).strip().lower(), canonicalize(canonical_event).encode("utf-8"))
+        compatibility = {"legacy_receipt": legacy_receipt}
+    receipt_id = sha256_hex(canonicalize({
+        "agent_identity": agent_identity,
+        "domain_id": canonical_event["domain_id"],
+        "event_commitment": event_commitment,
+        "sequence": canonical_event["sequence"],
+        "version": CANONICAL_RECEIPT_VERSION,
+    }).encode("utf-8"))
+    receipt = {
+        "version": CANONICAL_RECEIPT_VERSION,
+        "receipt_id": receipt_id,
+        "agent_identity": agent_identity,
+        "domain_id": canonical_event["domain_id"],
+        "sequence": canonical_event["sequence"],
+        "event_commitment": event_commitment,
+        "algorithm": select_receipt_algorithm(options, compatibility),
+    }
+    if compatibility:
+        receipt["compatibility"] = compatibility
+    signature = normalize_string(options.get("signature"))
+    native_proof = options.get("native_proof") if isinstance(options.get("native_proof"), dict) else None
+    if not signature and receipt["algorithm"] == XOONYA_NATIVE_ANCHORED_METHOD:
+        native_proof = build_native_anchored_receipt_proof(receipt, canonical_event, options.get("anchors") or options.get("anchor_refs") or [])
+        signature = native_proof.pop("compact_signature")
+    if not signature and receipt["algorithm"] == XOONYA_NATIVE_SHA256_METHOD:
+        signature = build_native_receipt_signature(receipt, canonical_event)
+    if not signature and compatibility:
+        signature = compatibility["legacy_receipt"]["opreturn_hex"]
+    if not signature:
+        raise ValueError("signature or legacy_identity_material_hex required")
+    if native_proof:
+        receipt["native_proof"] = native_proof
+    receipt["signature"] = signature
+    return receipt
+
+
+def build_proof_bundle(input_value: dict[str, Any]) -> dict[str, Any]:
+    ceb = canonicalize_event(input_value.get("ceb") or input_value.get("event"))
+    anchors = input_value.get("anchors") if isinstance(input_value.get("anchors"), list) else None
+    receipt_options = input_value.get("receipt_options") if isinstance(input_value.get("receipt_options"), dict) else {}
+    if anchors and not any(key in receipt_options for key in ("anchors", "native_anchor_refs", "anchor_refs")):
+        receipt_options = {**receipt_options, "anchors": anchors}
+    receipt = input_value.get("receipt") if isinstance(input_value.get("receipt"), dict) else emit_receipt(ceb, receipt_options)
+    bundle = {
+        "version": PROOF_BUNDLE_VERSION,
+        "ceb": ceb,
+        "receipt": receipt,
+    }
+    if anchors is not None:
+        bundle["anchors"] = anchors
+    for key in ("attestations", "evidence_refs", "batch_refs"):
+        if isinstance(input_value.get(key), list):
+            bundle[key] = input_value[key]
+    if isinstance(input_value.get("metadata"), dict):
+        bundle["metadata"] = input_value["metadata"]
+    return bundle
+
+
+def _verify_native_anchored(receipt: dict[str, Any], ceb: dict[str, Any], bundle: dict[str, Any]) -> dict[str, Any]:
+    proof = receipt.get("native_proof")
+    if not isinstance(proof, dict):
+        return {"valid": False, "reason": "native_proof_missing"}
+    if normalize_string(proof.get("method")) != XOONYA_NATIVE_ANCHORED_METHOD:
+        return {"valid": False, "reason": "native_proof_method_mismatch"}
+    if normalize_string(proof.get("base_method")) != XOONYA_NATIVE_SHA256_METHOD:
+        return {"valid": False, "reason": "native_anchor_base_method_unsupported"}
+    if not isinstance(bundle.get("anchors"), list):
+        return {"valid": False, "reason": "native_anchor_bundle_missing"}
+    proof_anchors = normalize_anchor_refs(proof.get("anchor_refs"))
+    bundle_anchors = normalize_anchor_refs(bundle.get("anchors"))
+    if canonicalize(proof_anchors) != canonicalize(bundle_anchors):
+        return {"valid": False, "reason": "native_anchor_bundle_mismatch"}
+    proof_material = proof.get("proof_material")
+    if not isinstance(proof_material, dict):
+        return {"valid": False, "reason": "native_anchor_proof_material_missing"}
+    expected_anchor_root = canonical_json_sha256_hex(proof_anchors)
+    if normalize_string(proof_material.get("anchor_root_sha256")).lower() != expected_anchor_root:
+        return {"valid": False, "reason": "native_anchor_root_mismatch"}
+    binding_material = build_native_anchor_binding_material(receipt, ceb, proof_anchors)
+    binding_hash = sha256_hex(canonicalize(binding_material).encode("utf-8"))
+    if normalize_string(proof_material.get("binding_material_sha256")).lower() != binding_hash:
+        return {"valid": False, "reason": "native_anchor_binding_hash_mismatch"}
+    if normalize_string(receipt.get("signature")) != XOONYA_NATIVE_ANCHORED_METHOD + ":" + binding_hash:
+        return {"valid": False, "reason": "signature_native_anchored_mismatch"}
+    return {"valid": True, "verification_state": "verified_native_anchor_binding", "anchor_count": len(proof_anchors), "anchor_root_sha256": expected_anchor_root}
+
+
+def verify_proof_bundle(bundle: dict[str, Any]) -> dict[str, Any]:
+    try:
+        if not isinstance(bundle, dict):
+            return {"valid": False, "reason": "bundle_not_object"}
+        if normalize_string(bundle.get("version")) != PROOF_BUNDLE_VERSION:
+            return {"valid": False, "reason": "bad_bundle_version"}
+        ceb = canonicalize_event(bundle.get("ceb"))
+        receipt = bundle.get("receipt")
+        if not isinstance(receipt, dict):
+            return {"valid": False, "reason": "receipt_not_object"}
+        if normalize_string(receipt.get("version")) != CANONICAL_RECEIPT_VERSION:
+            return {"valid": False, "reason": "bad_receipt_version"}
+        if normalize_string(receipt.get("domain_id")) != ceb["domain_id"]:
+            return {"valid": False, "reason": "receipt_domain_mismatch"}
+        if normalize_string(receipt.get("sequence")) != ceb["sequence"]:
+            return {"valid": False, "reason": "receipt_sequence_mismatch"}
+        expected_commitment = hash_event(ceb)
+        if normalize_string(receipt.get("event_commitment")).lower() != expected_commitment:
+            return {"valid": False, "reason": "event_commitment_mismatch"}
+        expected_receipt_id = sha256_hex(canonicalize({
+            "agent_identity": normalize_string(receipt.get("agent_identity")),
+            "domain_id": ceb["domain_id"],
+            "event_commitment": expected_commitment,
+            "sequence": ceb["sequence"],
+            "version": CANONICAL_RECEIPT_VERSION,
+        }).encode("utf-8"))
+        if normalize_string(receipt.get("receipt_id")).lower() != expected_receipt_id:
+            return {"valid": False, "reason": "receipt_id_mismatch"}
+        if not normalize_string(receipt.get("agent_identity")):
+            return {"valid": False, "reason": "agent_identity_missing"}
+        if not normalize_string(receipt.get("signature")):
+            return {"valid": False, "reason": "signature_missing"}
+        algorithm = normalize_string(receipt.get("algorithm"))
+        if not algorithm:
+            return {"valid": False, "reason": "verification_method_missing"}
+        if algorithm == "none":
+            return {"valid": False, "reason": "verification_method_none"}
+        if algorithm == XOONYA_NATIVE_HYBRID_METHOD:
+            return {"valid": False, "reason": "native_hybrid_design_gated"}
+        if algorithm == LEGACY_OPRETURN_METHOD:
+            legacy_receipt = (receipt.get("compatibility") or {}).get("legacy_receipt")
+            if not isinstance(legacy_receipt, dict):
+                return {"valid": False, "reason": "legacy_receipt_missing"}
+            legacy_verification = verify_legacy_receipt(legacy_receipt.get("opreturn_hex"), canonicalize(ceb).encode("utf-8"))
+            if not legacy_verification["valid"]:
+                return {"valid": False, "reason": "legacy_receipt_" + legacy_verification["reason"]}
+            if normalize_string(receipt.get("signature")).lower() != normalize_string(legacy_receipt.get("opreturn_hex")).lower():
+                return {"valid": False, "reason": "signature_legacy_mismatch"}
+            state = "verified_legacy_opreturn"
+        elif algorithm == XOONYA_NATIVE_SHA256_METHOD:
+            expected_signature = build_native_receipt_signature(receipt, ceb)
+            if normalize_string(receipt.get("signature")) != expected_signature:
+                return {"valid": False, "reason": "signature_native_mismatch"}
+            state = "verified_native_digest"
+        elif algorithm == XOONYA_NATIVE_ANCHORED_METHOD:
+            anchored = _verify_native_anchored(receipt, ceb, bundle)
+            if not anchored["valid"]:
+                return {"valid": False, "reason": anchored["reason"]}
+            state = anchored["verification_state"]
+        elif algorithm == XOONYA_NATIVE_SIGNED_METHOD:
+            signed = verify_native_signed_receipt_proof(receipt, ceb)
+            if not signed["valid"]:
+                return {
+                    "valid": False,
+                    "reason": signed["reason"],
+                    **({"dependency": signed["dependency"]} if signed.get("dependency") else {}),
+                }
+            state = signed["verification_state"]
+        elif algorithm in EXTERNAL_ASSERTION_METHODS:
+            signature = normalize_string(receipt.get("signature"))
+            if signature.startswith((
+                XOONYA_NATIVE_SHA256_METHOD + ":",
+                XOONYA_NATIVE_SIGNED_METHOD + ":",
+                XOONYA_NATIVE_ANCHORED_METHOD + ":",
+                XOONYA_NATIVE_HYBRID_METHOD + ":",
+            )):
+                return {"valid": False, "reason": "signature_method_mismatch"}
+            state = "accepted_detached_assertion" if algorithm == DETACHED_ASSERTION_METHOD else "accepted_external_proof_envelope"
+        else:
+            return {"valid": False, "reason": "verification_method_unsupported"}
+        return {
+            "valid": True,
+            "reason": None,
+            "version": PROOF_BUNDLE_VERSION,
+            "event_commitment": expected_commitment,
+            "receipt_id": expected_receipt_id,
+            "verification_method": algorithm,
+            "verification_state": state,
+        }
+    except Exception as error:
+        return {"valid": False, "reason": str(error)}