atrib 0.1.0__py3-none-any.whl

atrib/__init__.py

@@ -0,0 +1,237 @@
+# SPDX-License-Identifier: Apache-2.0
+"""atrib — verifiable agent actions, Python client SDK.
+
+The first non-TypeScript implementation of the atrib record layer
+(spec §1) and SDK contract (spec §5). Byte-identical to the TypeScript
+implementation: identical inputs produce identical JCS canonical forms,
+signatures, record hashes, and propagation tokens, verified against the
+shared conformance corpora under ``spec/conformance/``.
+"""
+
+from .canon import (
+    canonical_cross_attestation_input,
+    canonical_record,
+    canonical_signing_input,
+    jcs,
+)
+from .anchors import (
+    ANCHOR_CLAIM_PREFIX,
+    ANCHOR_TYPES,
+    BUILT_IN_DEFAULT_ANCHOR_SET,
+    AnchorDescriptor,
+    AnchorPostureResolution,
+    AnchorSetConfig,
+    anchor_claim_artifact,
+    resolve_anchor_posture,
+    resolve_effective_anchors,
+)
+from .attribution import (
+    ATTRIBUTION_EXTENSION_KEY,
+    ATTRIBUTION_LOG_SUBMISSION_STATUSES,
+    AttributionReceiptBlock,
+    AttributionReceiptConsistency,
+    AttributionReceiptVerification,
+    check_attribution_receipt_consistency,
+    parse_attribution_receipt_block,
+    verify_attribution_receipt,
+)
+from .chain import chain_root, genesis_chain_root, resolve_chain_root
+from .client import AnchorSpec, AtribClient, AttestRef, AttestResult, RecallOutcome
+from .evidence import (
+    ATRIB_PROFILE_BASE,
+    ATRIB_PROFILE_REGISTRY,
+    EVIDENCE_CONSTRAINT_STATUSES,
+    EVIDENCE_REF_KINDS,
+    EVIDENCE_TIERS,
+    FROZEN_LEGACY_PROTOCOLS,
+    LEGACY_PROTOCOL_TO_PROFILE,
+    EnvelopeReproducibility,
+    EnvelopeValidation,
+    EvidenceConstraint,
+    EvidenceEnvelope,
+    EvidencePayload,
+    EvidencePayloadRef,
+    EvidenceResult,
+    EvidenceVerifier,
+    ProfileClassification,
+    assess_reproducibility,
+    build_evidence_envelope,
+    classify_profile,
+    evidence_envelope_key,
+    evidence_tier_rank,
+    from_legacy_evidence_block,
+    is_relay_identity_swap,
+    is_valid_envelope,
+    jcs_sha256,
+    map_legacy_evidence_block,
+    order_envelope_instances,
+    raw_sha256,
+    render_envelope_opaque,
+    validate_envelope,
+)
+from .content_id import compute_content_id, normalize_server_url
+from .encoding import base64url_decode, base64url_encode, hex_decode, hex_encode
+from .hashes import (
+    derive_provenance_token,
+    record_hash_bytes,
+    record_hash_hex,
+    record_hash_ref,
+    sha256,
+)
+from .keys import ResolvedKey, resolve_key
+from .mirror import (
+    MirrorLine,
+    append_mirror_line,
+    default_mirror_read_path,
+    default_mirror_write_path,
+    mirror_tail_hash_hex,
+    parse_mirror_line,
+    read_mirror,
+    read_mirror_tail,
+)
+from .records import (
+    SYNTHETIC_SERVER_URL,
+    build_and_sign_emit_record,
+    content_hash,
+    leaf_of_event_type_uri,
+)
+from .signing import (
+    get_public_key,
+    sign_record,
+    sign_transaction_attestation,
+    sign_transaction_record,
+    verify_record,
+)
+from .submission import DEFAULT_LOG_ENDPOINT, SubmissionQueue, normalize_log_endpoint
+from .token import DecodedToken, decode_token, encode_token
+from .types import (
+    EVENT_TYPE_ANNOTATION_URI,
+    EVENT_TYPE_DIRECTORY_ANCHOR_URI,
+    EVENT_TYPE_OBSERVATION_URI,
+    EVENT_TYPE_REVISION_URI,
+    EVENT_TYPE_TOOL_CALL_URI,
+    EVENT_TYPE_TRANSACTION_URI,
+    SPEC_VERSION,
+    AtribRecord,
+    SignerEntry,
+    event_type_uri_to_byte,
+    is_normative_event_type_uri,
+    is_valid_event_type_uri,
+    normalize_event_type,
+)
+from .validation import ValidationResult, validate_submission
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ANCHOR_CLAIM_PREFIX",
+    "ANCHOR_TYPES",
+    "ATRIB_PROFILE_BASE",
+    "ATRIB_PROFILE_REGISTRY",
+    "ATTRIBUTION_EXTENSION_KEY",
+    "ATTRIBUTION_LOG_SUBMISSION_STATUSES",
+    "AnchorDescriptor",
+    "AnchorPostureResolution",
+    "AnchorSetConfig",
+    "AnchorSpec",
+    "AttributionReceiptBlock",
+    "AttributionReceiptConsistency",
+    "AttributionReceiptVerification",
+    "BUILT_IN_DEFAULT_ANCHOR_SET",
+    "anchor_claim_artifact",
+    "check_attribution_receipt_consistency",
+    "parse_attribution_receipt_block",
+    "resolve_anchor_posture",
+    "resolve_effective_anchors",
+    "verify_attribution_receipt",
+    "AtribClient",
+    "AtribRecord",
+    "AttestRef",
+    "AttestResult",
+    "DecodedToken",
+    "DEFAULT_LOG_ENDPOINT",
+    "EVIDENCE_CONSTRAINT_STATUSES",
+    "EVIDENCE_REF_KINDS",
+    "EVIDENCE_TIERS",
+    "FROZEN_LEGACY_PROTOCOLS",
+    "LEGACY_PROTOCOL_TO_PROFILE",
+    "EnvelopeReproducibility",
+    "EnvelopeValidation",
+    "EvidenceConstraint",
+    "EvidenceEnvelope",
+    "EvidencePayload",
+    "EvidencePayloadRef",
+    "EvidenceResult",
+    "EvidenceVerifier",
+    "ProfileClassification",
+    "assess_reproducibility",
+    "build_evidence_envelope",
+    "classify_profile",
+    "evidence_envelope_key",
+    "evidence_tier_rank",
+    "from_legacy_evidence_block",
+    "is_relay_identity_swap",
+    "is_valid_envelope",
+    "jcs_sha256",
+    "map_legacy_evidence_block",
+    "order_envelope_instances",
+    "raw_sha256",
+    "render_envelope_opaque",
+    "validate_envelope",
+    "EVENT_TYPE_ANNOTATION_URI",
+    "EVENT_TYPE_DIRECTORY_ANCHOR_URI",
+    "EVENT_TYPE_OBSERVATION_URI",
+    "EVENT_TYPE_REVISION_URI",
+    "EVENT_TYPE_TOOL_CALL_URI",
+    "EVENT_TYPE_TRANSACTION_URI",
+    "MirrorLine",
+    "RecallOutcome",
+    "ResolvedKey",
+    "SPEC_VERSION",
+    "SignerEntry",
+    "SubmissionQueue",
+    "SYNTHETIC_SERVER_URL",
+    "ValidationResult",
+    "append_mirror_line",
+    "base64url_decode",
+    "base64url_encode",
+    "build_and_sign_emit_record",
+    "canonical_cross_attestation_input",
+    "canonical_record",
+    "canonical_signing_input",
+    "chain_root",
+    "compute_content_id",
+    "content_hash",
+    "decode_token",
+    "default_mirror_read_path",
+    "default_mirror_write_path",
+    "derive_provenance_token",
+    "encode_token",
+    "event_type_uri_to_byte",
+    "genesis_chain_root",
+    "get_public_key",
+    "hex_decode",
+    "hex_encode",
+    "is_normative_event_type_uri",
+    "is_valid_event_type_uri",
+    "jcs",
+    "leaf_of_event_type_uri",
+    "mirror_tail_hash_hex",
+    "normalize_event_type",
+    "normalize_log_endpoint",
+    "normalize_server_url",
+    "parse_mirror_line",
+    "read_mirror",
+    "read_mirror_tail",
+    "record_hash_bytes",
+    "record_hash_hex",
+    "record_hash_ref",
+    "resolve_chain_root",
+    "resolve_key",
+    "sha256",
+    "sign_record",
+    "sign_transaction_attestation",
+    "sign_transaction_record",
+    "validate_submission",
+    "verify_record",
+]

atrib/anchors.py

@@ -0,0 +1,200 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Producer-side anchor plurality (D138, spec §2.11.7-§2.11.13).
+
+Python port of ``packages/mcp/src/anchors.ts``: the §2.11.8 anchor-type
+registry, the typed anchor-set configuration, the §2.11.12 posture
+resolution (``resolve_anchor_posture`` / ``resolve_effective_anchors``)
+including the ``allow_single_anchor`` opt-in gate, and the §2.11.10
+anchoring-claim artifact bytes (``anchor_claim_artifact``).
+
+Submission fan-out lives in :mod:`atrib.client`: ``AtribClient`` builds one
+:class:`atrib.submission.SubmissionQueue` per effective ``atrib-log``
+anchor endpoint, so every leg keeps the §5.3.5 non-blocking contract.
+Non-``atrib-log`` anchor types (``sigstore-rekor``, ``rfc3161-tsa``,
+``opentimestamps``) have no Python transport yet — the TypeScript
+reference stubs them too — so the client skips those legs with an
+``atrib:`` warning naming the type.
+
+Nothing here changes any signed byte: proof bundles are post-signing
+artifacts (§2.8) and anchoring is permissionless and post-hoc (§2.11.7).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TypedDict
+
+from typing_extensions import NotRequired
+
+# ── Anchor type registry (§2.11.8, v1) ───────────────────────────────────
+
+ANCHOR_TYPES = ("atrib-log", "sigstore-rekor", "rfc3161-tsa", "opentimestamps")
+
+# §2.11.10 domain-separation prefix for the anchoring-claim artifact.
+# JCS-canonical records begin with '{'; the prefix makes the separation
+# between anchoring signatures and record signatures explicit.
+ANCHOR_CLAIM_PREFIX = "atrib-anchor/v1:"
+
+_RECORD_HASH_RE = re.compile(r"^sha256:[0-9a-f]{64}\Z")
+
+
+# ── Anchor-set configuration (§2.11.12) ──────────────────────────────────
+
+
+class AnchorDescriptor(TypedDict, total=False):
+    """One anchor in a producer's anchor set. ``anchor_type`` absent (or
+    ``None``, mirroring the TS ``??`` coalescing) means ``atrib-log`` — the
+    same absence-defaulting rule the ``log_proofs`` discriminator uses
+    (§2.11.9 rule (a)). ``url`` wins over ``endpoint`` when both are set."""
+
+    anchor_type: NotRequired[str]
+    anchor_id: NotRequired[str]
+    url: NotRequired[str]
+    endpoint: NotRequired[str]  # alias for `url`; `url` wins when both set
+    calendars: NotRequired[list[str]]  # opentimestamps only
+    public_key_b64: NotRequired[str]  # verifier trust material passthrough
+
+
+class AnchorSetConfig(TypedDict, total=False):
+    """Producer anchor configuration per §2.11.12."""
+
+    anchors: NotRequired[list[AnchorDescriptor]]
+    # Opt-in acknowledgment that a sub-plurality anchor set is deliberate
+    # (§2.11.12 rule 3) — the single-anchor analog of a deliberate dangling
+    # informed_by claim per D113. Defaults to False.
+    allow_single_anchor: NotRequired[bool]
+
+
+#: The SDK's built-in default anchor set (§2.11.12 rule 1): two independent
+#: anchors so zero-config producers get plurality without opting in. Values
+#: match ``BUILT_IN_DEFAULT_ANCHOR_SET`` in ``packages/mcp/src/anchors.ts``
+#: exactly. The OpenTimestamps member has no transport in this SDK yet, so
+#: zero-config fan-out submits to the atrib log exactly as today and the
+#: client reports the OTS leg skipped.
+BUILT_IN_DEFAULT_ANCHOR_SET: tuple[AnchorDescriptor, ...] = (
+    {
+        "anchor_type": "atrib-log",
+        "anchor_id": "log.atrib.dev",
+        "url": "https://log.atrib.dev/v1",
+    },
+    {
+        "anchor_type": "opentimestamps",
+        "anchor_id": "opentimestamps-calendars",
+        "calendars": ["https://a.pool.opentimestamps.org"],
+    },
+)
+
+
+@dataclass(frozen=True)
+class AnchorPostureResolution:
+    """Result of resolving a producer anchor config per the §2.11.12
+    precedence rules. Field names match the conformance corpus
+    (``spec/conformance/2.11/anchors/cases/allow-single-anchor-config.json``)
+    and the TS ``AnchorPostureResolution`` exactly."""
+
+    effective_anchor_count: int
+    used_default_set: bool
+    warn: bool
+    # §5.9.3 sidecar degradation marker written when a sub-plurality config
+    # lacks allow_single_anchor (§2.11.12 rule 4), else None:
+    # {"configured": <n>, "allow_single_anchor": False}
+    sidecar_anchor_config: Mapping[str, object] | None
+
+
+def resolve_anchor_posture(
+    config: Mapping[str, object] | None = None,
+) -> AnchorPostureResolution:
+    """Resolve a producer anchor config per §2.11.12, exact precedence:
+
+    1. No anchor config at all ⇒ the built-in default set (two anchors).
+    2. Explicit config with ≥ 2 entries ⇒ used as given.
+    3. Explicit config with < 2 entries and ``allow_single_anchor: True``
+       ⇒ used as given, no warning.
+    4. Explicit config with < 2 entries and no flag ⇒ ``warn=True`` plus
+       the sidecar degradation marker. The operation continues; this
+       function is PURE (no output, no raise) — the client emits the
+       ``atrib:``-prefixed warning so pure-function callers stay silent.
+
+    Never raises (§5.8). A malformed config resolves as if empty.
+    """
+    mapping: Mapping[str, object] = config if isinstance(config, Mapping) else {}
+    anchors = mapping.get("anchors")
+    if not isinstance(anchors, list):
+        return AnchorPostureResolution(
+            effective_anchor_count=len(BUILT_IN_DEFAULT_ANCHOR_SET),
+            used_default_set=True,
+            warn=False,
+            sidecar_anchor_config=None,
+        )
+    configured = len(anchors)
+    if configured >= 2 or mapping.get("allow_single_anchor") is True:
+        return AnchorPostureResolution(
+            effective_anchor_count=configured,
+            used_default_set=False,
+            warn=False,
+            sidecar_anchor_config=None,
+        )
+    return AnchorPostureResolution(
+        effective_anchor_count=configured,
+        used_default_set=False,
+        warn=True,
+        sidecar_anchor_config={"configured": configured, "allow_single_anchor": False},
+    )
+
+
+def resolve_effective_anchors(
+    config: Mapping[str, object] | None = None,
+) -> list[AnchorDescriptor]:
+    """The effective anchor set for a config: the built-in default set when
+    no config was given (§2.11.12 rule 1), the caller's entries otherwise —
+    including deliberate or warned sub-plurality sets, which are used as
+    given (rules 3-4: warn, never block). Never raises."""
+    mapping: Mapping[str, object] = config if isinstance(config, Mapping) else {}
+    anchors = mapping.get("anchors")
+    if isinstance(anchors, list):
+        # Entries are returned as given (hostile members included) so the
+        # transport-build layer can skip them with a warning per §5.8.
+        return list(anchors)
+    return list(BUILT_IN_DEFAULT_ANCHOR_SET)
+
+
+# ── §2.11.10 anchoring-claim artifact ────────────────────────────────────
+
+
+def anchor_claim_artifact(record_hash: str) -> bytes:
+    """Build the §2.11.10 anchor-claim artifact bytes for a record hash:
+    the UTF-8 bytes of ``"atrib-anchor/v1:" + record_hash`` with
+    ``record_hash`` in canonical ``"sha256:" + 64-lowercase-hex`` form.
+    Deterministically reconstructible from ``record_hash`` alone; reveals
+    nothing beyond the commitment itself (§8.3 posture preserved).
+
+    Byte-identical to the TS ``anchorClaimArtifact``. Raises ``ValueError``
+    on a malformed record hash — this is a pure builder for programmer
+    input; fan-out paths catch everything per §5.8.
+    """
+    if not isinstance(record_hash, str) or not _RECORD_HASH_RE.match(record_hash):
+        raise ValueError(
+            "atrib: anchor claim requires a canonical "
+            f'"sha256:<64 lowercase hex>" record hash, got {record_hash!r:.90}'
+        )
+    return (ANCHOR_CLAIM_PREFIX + record_hash).encode("utf-8")
+
+
+# ── Descriptor helpers (shared with the client fan-out) ──────────────────
+
+
+def anchor_descriptor_type(descriptor: Mapping[str, object]) -> object:
+    """§2.11.9 rule (a) analog: absent (or ``None``, matching the TS ``??``)
+    ``anchor_type`` means ``atrib-log``. Non-string values pass through as
+    given so callers can name them in skip warnings."""
+    anchor_type = descriptor.get("anchor_type")
+    return "atrib-log" if anchor_type is None else anchor_type
+
+
+def anchor_descriptor_endpoint(descriptor: Mapping[str, object]) -> object:
+    """Submission endpoint: ``url`` wins over ``endpoint`` (both spellings
+    accepted per §2.11.12; the spec sample uses ``url``)."""
+    url = descriptor.get("url")
+    return url if url is not None else descriptor.get("endpoint")

atrib/attribution.py

@@ -0,0 +1,229 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``dev.atrib/attribution`` extension receipts (accepted as D141).
+
+Python parity for the TypeScript SDK's receipt surface: lenient parsing of
+the extension block from a tool result's ``_meta``, and a consistency check
+of a receipt's claims against the signed record it names. Receipts are
+advisory — a mismatch never invalidates the tool result; it means the
+receipt must not be trusted or cited. Conformance:
+``spec/conformance/mcp-extension/cases/receipt--*.json``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import cast
+
+from .encoding import base64url_encode, hex_encode
+from .hashes import record_hash_hex, record_hash_ref
+from .token import decode_token, encode_token
+from .types import AtribRecord, normalize_event_type
+
+ATTRIBUTION_EXTENSION_KEY = "dev.atrib/attribution"
+
+_RECEIPT_STRING_FIELDS = (
+    "record_hash",
+    "creator_key",
+    "context_id",
+    "event_type",
+    "chain_root",
+    "log_submission",
+)
+
+ATTRIBUTION_LOG_SUBMISSION_STATUSES = ("queued", "submitted", "disabled", "failed")
+
+
+@dataclass(frozen=True)
+class AttributionReceiptBlock:
+    token: str | None = None
+    receipt: Mapping[str, str] | None = None
+    record: AtribRecord | None = None
+
+
+@dataclass(frozen=True)
+class AttributionReceiptConsistency:
+    receipt_valid: bool
+    mismatched_fields: list[str] = field(default_factory=list)
+    attached_record_hash: str | None = None
+    claimed_record_hash: str | None = None
+
+
+def parse_attribution_receipt_block(meta: object) -> AttributionReceiptBlock | None:
+    """Extract the extension block from a tool result's ``_meta``. Lenient
+    parse: anything malformed yields None, never a raise; wrong-typed
+    fields drop; an all-wrong-typed receipt reads as absent."""
+    if not isinstance(meta, Mapping):
+        return None
+    raw = meta.get(ATTRIBUTION_EXTENSION_KEY)
+    if not isinstance(raw, Mapping):
+        return None
+    token = raw.get("token")
+    parsed_token = token if isinstance(token, str) else None
+    parsed_receipt: dict[str, str] | None = None
+    raw_receipt = raw.get("receipt")
+    if isinstance(raw_receipt, Mapping):
+        kept = {
+            fld: value
+            for fld in _RECEIPT_STRING_FIELDS
+            if isinstance(value := raw_receipt.get(fld), str)
+        }
+        if kept:
+            parsed_receipt = kept
+    raw_record = raw.get("record")
+    parsed_record = (
+        cast(AtribRecord, dict(raw_record)) if isinstance(raw_record, Mapping) else None
+    )
+    if parsed_token is None and parsed_receipt is None and parsed_record is None:
+        return None
+    return AttributionReceiptBlock(
+        token=parsed_token, receipt=parsed_receipt, record=parsed_record
+    )
+
+
+def check_attribution_receipt_consistency(
+    block: AttributionReceiptBlock,
+    record: AtribRecord | None = None,
+) -> AttributionReceiptConsistency:
+    """Check a receipt block's claims against the signed record they name
+    (the attached ``block.record`` or a caller-retrieved record). Absent
+    receipt fields are not mismatches. Never raises."""
+    attached = record if record is not None else block.record
+    receipt = block.receipt or {}
+    claimed = receipt.get("record_hash")
+    if attached is None:
+        return AttributionReceiptConsistency(
+            receipt_valid=False,
+            mismatched_fields=["record"],
+            claimed_record_hash=claimed,
+        )
+    try:
+        attached_hash = record_hash_ref(attached)
+        token = encode_token(attached)
+    except Exception:  # noqa: BLE001 — unhashable record cannot back a receipt
+        return AttributionReceiptConsistency(
+            receipt_valid=False,
+            mismatched_fields=["record"],
+            claimed_record_hash=claimed,
+        )
+    mismatched: list[str] = []
+    if claimed is not None and claimed != attached_hash:
+        mismatched.append("record_hash")
+    if block.token is not None and block.token != token:
+        mismatched.append("token")
+    for fld in ("creator_key", "context_id", "chain_root"):
+        value = receipt.get(fld)
+        if value is not None and value != attached.get(fld):
+            mismatched.append(fld)
+    claimed_event = receipt.get("event_type")
+    attached_event = attached.get("event_type")
+    if claimed_event is not None and normalize_event_type(claimed_event) != (
+        normalize_event_type(attached_event) if isinstance(attached_event, str) else None
+    ):
+        mismatched.append("event_type")
+    return AttributionReceiptConsistency(
+        receipt_valid=not mismatched,
+        mismatched_fields=mismatched,
+        attached_record_hash=attached_hash,
+        claimed_record_hash=claimed,
+    )
+
+
+# ── Receipt verification (extension spec §6.2, consumer side) ────────────
+
+_RECEIPT_REQUIRED_STRING_FIELDS = _RECEIPT_STRING_FIELDS
+
+
+@dataclass(frozen=True)
+class AttributionReceiptVerification:
+    """Outcome of :func:`verify_attribution_receipt`. ``mismatched`` uses
+    the TS vocabulary exactly: ``'token'``, ``'record_hash'``,
+    ``'creator_key'``, ``'context_id'``, ``'chain_root'``,
+    ``'log_submission'``, or ``['malformed']`` when the block is not
+    structurally a v0.1 result block."""
+
+    valid: bool
+    mismatched: list[str] = field(default_factory=list)
+
+
+def _is_structurally_receipt_block(block: object) -> bool:
+    if not isinstance(block, Mapping):
+        return False
+    if not isinstance(block.get("token"), str):
+        return False
+    receipt = block.get("receipt")
+    if not isinstance(receipt, Mapping):
+        return False
+    for fld in _RECEIPT_REQUIRED_STRING_FIELDS:
+        if not isinstance(receipt.get(fld), str):
+            return False
+    # TS parity: `record !== undefined && !isPlainObject(record)` — a
+    # present-but-null (None) record is malformed; an absent one is fine.
+    if "record" in block and not isinstance(block["record"], Mapping):
+        return False
+    return True
+
+
+def verify_attribution_receipt(block: object) -> AttributionReceiptVerification:
+    """Consumer-side receipt integrity check (extension spec §6.2), the
+    exact port of the TS ``verifyAttributionReceipt``: the token,
+    ``record_hash``, and ``creator_key`` must agree with each other and —
+    when the full record body is attached — recompute from the record's
+    canonical bytes. A consumer that detects an internal inconsistency MUST
+    treat the receipt as invalid and discard it; receipt invalidity never
+    invalidates the tool result itself.
+
+    This checks internal consistency only; it is not a proof. Callers
+    wanting Tier-3 assurance additionally verify the attached record's
+    Ed25519 signature (:func:`atrib.verify_record`) and, where required,
+    log inclusion via an independently fetched proof bundle.
+
+    Never raises: hostile input yields ``valid=False`` with
+    ``mismatched=['malformed']``.
+    """
+    if not _is_structurally_receipt_block(block):
+        return AttributionReceiptVerification(valid=False, mismatched=["malformed"])
+    mblock = cast("Mapping[str, object]", block)  # narrowed by the structural check
+    receipt = cast("Mapping[str, object]", mblock["receipt"])
+    token = cast(str, mblock["token"])
+    mismatched: list[str] = []
+    decoded = decode_token(token)
+    if decoded is None:
+        return AttributionReceiptVerification(valid=False, mismatched=["token"])
+    token_hash_hex = hex_encode(decoded.record_hash)
+    token_key = base64url_encode(decoded.creator_key)
+
+    if receipt["record_hash"] != f"sha256:{token_hash_hex}":
+        mismatched.append("record_hash")
+    if receipt["creator_key"] != token_key:
+        mismatched.append("creator_key")
+    if receipt["log_submission"] not in ATTRIBUTION_LOG_SUBMISSION_STATUSES:
+        mismatched.append("log_submission")
+
+    record = mblock.get("record")
+    if isinstance(record, Mapping):
+        try:
+            record_hex = record_hash_hex(record)
+            record_token = encode_token(record)
+        except Exception:  # noqa: BLE001 — unhashable attached record
+            # The TS reference would propagate here; Python keeps the
+            # never-raise contract and reports the block as malformed.
+            return AttributionReceiptVerification(valid=False, mismatched=["malformed"])
+        if token != record_token and "token" not in mismatched:
+            mismatched.append("token")
+        if (
+            receipt["record_hash"] != f"sha256:{record_hex}"
+            and "record_hash" not in mismatched
+        ):
+            mismatched.append("record_hash")
+        if (
+            receipt["creator_key"] != record.get("creator_key")
+            and "creator_key" not in mismatched
+        ):
+            mismatched.append("creator_key")
+        if receipt["context_id"] != record.get("context_id"):
+            mismatched.append("context_id")
+        if receipt["chain_root"] != record.get("chain_root"):
+            mismatched.append("chain_root")
+
+    return AttributionReceiptVerification(valid=not mismatched, mismatched=mismatched)