moca-reader 0.6.0__py3-none-any.whl

moca_reader/__init__.py

@@ -0,0 +1,84 @@
+"""The MOCA Reader for Python: open, verify, search and cite MOCA packages.
+
+    from moca_reader import read_package, Library
+
+    pkg = read_package("support-kb.moca", trust_root="trust-root.json")
+    library = Library().add(pkg)
+    for record in library.search("refund window"):
+        print(record["node"]["title"], record["node"]["ref"])
+
+Names follow the Reader interface (moca-spec spec/moca-reader-interface.md) in Python's style.
+"""
+
+from .attestations import TrustRoot
+from .backends.dense import DenseBackend, model_mismatch, similarity
+from .backends.hybrid import HybridBackend
+from .backends.lexical import LexicalBackend
+from .backends.memory_store import MemoryStoreBackend
+from .citation import CitationRecord, citation_for, passes_default_policy, pick_representation
+from .codes import CODES
+from .content import ContentNode, Representation
+from .diagnostics import Diagnostic
+from .evidence_text import selector_matches
+from .library import Library, Overlay
+from .metadata import FLAT_FIELDS, flat_metadata
+from .profiles import KNOWN_PROFILES, PROFILE_ONTOLOGY
+from .reader import MOCA_VERSION, Member, PackageResult, Review, read_package
+from .resolver import directory_resolver
+from .search import Embedder, HookContext, Search, SearchBackend, SearchHooks, StoreScope
+from .sidecar import SidecarBinding, bind_sidecar
+from .source import DEFAULT_LIMITS, HostSource, SourceEntry
+from .state import package_state
+from .strategies.diversify import diversify
+from .strategies.ontology_guided import ontology_guided
+from .structure import structure_view
+from .structure_ops import StructureIndex
+
+__version__ = "0.6.0"
+
+__all__ = [
+    "CODES",
+    "DEFAULT_LIMITS",
+    "FLAT_FIELDS",
+    "KNOWN_PROFILES",
+    "MOCA_VERSION",
+    "PROFILE_ONTOLOGY",
+    "CitationRecord",
+    "ContentNode",
+    "DenseBackend",
+    "Diagnostic",
+    "Embedder",
+    "HookContext",
+    "HostSource",
+    "HybridBackend",
+    "LexicalBackend",
+    "Library",
+    "Member",
+    "MemoryStoreBackend",
+    "Overlay",
+    "PackageResult",
+    "Representation",
+    "Review",
+    "Search",
+    "SearchBackend",
+    "SearchHooks",
+    "SidecarBinding",
+    "SourceEntry",
+    "StoreScope",
+    "StructureIndex",
+    "TrustRoot",
+    "bind_sidecar",
+    "citation_for",
+    "directory_resolver",
+    "diversify",
+    "flat_metadata",
+    "model_mismatch",
+    "ontology_guided",
+    "package_state",
+    "passes_default_policy",
+    "pick_representation",
+    "read_package",
+    "selector_matches",
+    "similarity",
+    "structure_view",
+]

moca_reader/_js.py

@@ -0,0 +1,291 @@
+"""Behaviours of the reference Reader (JavaScript) that every Reader matches.
+
+These are the places where Python's defaults differ from JavaScript's, and so from what the
+reference Reader and the conformance corpus expect.
+"""
+
+from __future__ import annotations
+
+import base64
+import math
+import re
+from datetime import UTC, datetime
+from typing import Any
+
+
+def utf16_key(text: str) -> bytes:
+    """Sort key for JavaScript's string order: UTF-16 code units, not code points."""
+    return text.encode("utf-16-be", "surrogatepass")
+
+
+def js_sorted(values: Any, key: Any = None) -> list[Any]:
+    """``sorted`` in JavaScript's string order."""
+    if key is None:
+        return sorted(values, key=utf16_key)
+    return sorted(values, key=lambda v: utf16_key(key(v)))
+
+
+_FULL_DATE = re.compile(r"^([0-9]{4})-([0-9]{2})-([0-9]{2})\Z")
+_DATE_TIME = re.compile(
+    r"^([0-9]{4})-([0-9]{2})-([0-9]{2})[Tt]([0-9]{2}):([0-9]{2}):([0-9]{2})(\.[0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})\Z"
+)
+
+
+def parse_date(value: Any) -> datetime | None:
+    """A date or date-time as a UTC instant, or None (package spec §4.4, attestations §6).
+
+    A full date (YYYY-MM-DD) is 00:00:00Z on that day. A date-time is RFC 3339 and carries an offset (Z or
+    ±hh:mm); without one it does not parse, so no Reader guesses a time zone. Anything else does not parse.
+    """
+    if not isinstance(value, str):
+        return None
+    try:
+        m = _FULL_DATE.match(value)
+        if m:
+            return datetime(int(m[1]), int(m[2]), int(m[3]), tzinfo=UTC)
+        if not _DATE_TIME.match(value):
+            return None
+        parsed = datetime.fromisoformat(value.upper().replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed.astimezone(UTC)
+
+
+def effective_window(
+    package_from: Any, package_until: Any, node_from: Any, node_until: Any
+) -> tuple[Any, Any, datetime | None, datetime | None]:
+    """The node's validity window (package spec §4.4): the intersection of the package's window and its own.
+
+    A bound that does not parse, or a window whose end is not after its start, is ignored. Returns the bounds as
+    written (or None) and as instants (or None).
+    """
+
+    def window(start: Any, end: Any) -> tuple[datetime | None, datetime | None]:
+        f, u = parse_date(start), parse_date(end)
+        if f is not None and u is not None and u <= f:
+            return None, None
+        return f, u
+
+    pf, pu = window(package_from, package_until)
+    nf, nu = window(node_from, node_until)
+    from_pick = (node_from, nf) if nf is not None and (pf is None or nf >= pf) else (package_from, pf)
+    until_pick = (node_until, nu) if nu is not None and (pu is None or nu <= pu) else (package_until, pu)
+    return (
+        from_pick[0] if from_pick[1] is not None else None,
+        until_pick[0] if until_pick[1] is not None else None,
+        from_pick[1],
+        until_pick[1],
+    )
+
+
+_BASE64_JUNK = re.compile(r"[^A-Za-z0-9+/\-_]")
+
+
+def b64decode(text: str) -> bytes:
+    """Base64 decoded as Node's ``Buffer.from(text, 'base64')`` does: leniently, never raising."""
+    clean = _BASE64_JUNK.sub("", text.split("=", 1)[0]).replace("-", "+").replace("_", "/")
+    clean = clean[: len(clean) - (len(clean) % 4 == 1)]
+    try:
+        return base64.b64decode(clean + "=" * (-len(clean) % 4))
+    except ValueError:  # pragma: no cover - the input is already clean
+        return b""
+
+
+def math_round(value: float) -> float:
+    """JavaScript's ``Math.round``: the nearest integer, and halves go towards +infinity (-2.5 gives -2)."""
+    if math.isnan(value) or math.isinf(value):
+        return value
+    floor = math.floor(value)
+    return float(floor + 1 if value - floor >= 0.5 else floor)
+
+
+def round_scaled(value: float, scale: float) -> float:
+    """``Math.round(value * scale) / scale``, as the reference Reader rounds scores."""
+    return math_round(value * scale) / scale
+
+
+def truthy(value: Any) -> bool:
+    """JavaScript truthiness: empty lists and objects are truthy; 0, NaN, "" and null are not."""
+    if value is None or value is False:
+        return False
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return value != 0 and not math.isnan(value)
+    if isinstance(value, str):
+        return value != ""
+    return True
+
+
+def get(obj: Any, key: str) -> Any:
+    """``obj?.key`` on parsed JSON or YAML: None unless ``obj`` is an object with that key."""
+    return obj.get(key) if isinstance(obj, dict) else None
+
+
+def is_object(value: Any) -> bool:
+    return isinstance(value, dict)
+
+
+def _no_constants(name: str) -> Any:
+    raise ValueError(f"{name} is not valid JSON")
+
+
+def json_loads(text: str, unique_keys: bool = False) -> Any:
+    """``JSON.parse``: NaN and Infinity are not JSON. With ``unique_keys``, a repeated member name raises ValueError
+    (I-JSON, RFC 7493)."""
+    import json
+
+    def pairs(items: list[tuple[str, Any]]) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        for key, value in items:
+            if key in out:
+                raise ValueError(f'member "{key}" appears more than once')
+            out[key] = value
+        return out
+
+    if unique_keys:
+        return json.loads(text, parse_constant=_no_constants, object_pairs_hook=pairs)
+    return json.loads(text, parse_constant=_no_constants)
+
+
+def number_to_string(value: float | int) -> str:
+    """ECMAScript ``Number.prototype.toString`` for finite numbers."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if math.isnan(value):
+        return "NaN"
+    if math.isinf(value):
+        return "Infinity" if value > 0 else "-Infinity"
+    if value == 0:
+        return "0"
+    sign = "-" if value < 0 else ""
+    digits, _, exp = f"{abs(value):.17e}".partition("e")
+    # The shortest round-tripping digits, as repr gives them.
+    r = repr(abs(value))
+    mantissa, _, e = r.partition("e")
+    exponent = int(e) if e else 0
+    if "." in mantissa:
+        whole, frac = mantissa.split(".")
+    else:
+        whole, frac = mantissa, ""
+    if frac == "0":
+        frac = ""
+    s_digits = (whole + frac).lstrip("0")
+    n = exponent + len(whole) - (len(whole + frac) - len((whole + frac).lstrip("0")))
+    s_digits = s_digits.rstrip("0") or "0"
+    k = len(s_digits)
+    del digits, exp
+    if k <= n <= 21:
+        out = s_digits + "0" * (n - k)
+    elif 0 < n <= 21:
+        out = s_digits[:n] + "." + s_digits[n:]
+    elif -6 < n <= 0:
+        out = "0." + "0" * (-n) + s_digits
+    else:
+        e_val = n - 1
+        e_str = f"e{'+' if e_val >= 0 else '-'}{abs(e_val)}"
+        out = s_digits[0] + ("." + s_digits[1:] if k > 1 else "") + e_str
+    return sign + out
+
+
+def stringify(value: Any) -> str:
+    """``JSON.stringify`` with no spacing, for comparing JSON documents as the reference Reader does."""
+    import json
+
+    if value is None or isinstance(value, (bool, str)):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, (int, float)):
+        return (
+            "null" if isinstance(value, float) and (math.isnan(value) or math.isinf(value)) else number_to_string(value)
+        )
+    if isinstance(value, list):
+        return "[" + ",".join(stringify(v) for v in value) + "]"
+    if isinstance(value, dict):
+        return (
+            "{" + ",".join(f"{json.dumps(str(k), ensure_ascii=False)}:{stringify(v)}" for k, v in value.items()) + "}"
+        )
+    return "null"
+
+
+def decode_uri_component(text: str) -> str:
+    """``decodeURIComponent``: raises ValueError on a malformed escape, as JavaScript throws URIError."""
+    from urllib.parse import unquote_to_bytes
+
+    if re.search(r"%(?![0-9A-Fa-f]{2})", text):
+        raise ValueError("URI malformed")
+    try:
+        return unquote_to_bytes(text).decode("utf-8")
+    except UnicodeDecodeError as err:
+        raise ValueError("URI malformed") from err
+
+
+def posix_normalize(path: str) -> str:
+    """Node's ``path.posix.normalize``: keeps a trailing slash, collapses repeated slashes, '' gives '.'."""
+    if path == "":
+        return "."
+    absolute = path.startswith("/")
+    trailing = path.endswith("/")
+    parts: list[str] = []
+    for seg in path.split("/"):
+        if seg in ("", "."):
+            continue
+        if seg == "..":
+            if parts and parts[-1] != "..":
+                parts.pop()
+            elif not absolute:
+                parts.append("..")
+            continue
+        parts.append(seg)
+    out = "/".join(parts)
+    if not out and not absolute:
+        out = "."
+    if out and trailing:
+        out += "/"
+    return ("/" + out) if absolute else out
+
+
+def posix_dirname(path: str) -> str:
+    import posixpath
+
+    d = posixpath.dirname(path.rstrip("/") if path != "/" else path)
+    return d or "."
+
+
+def posix_join(*parts: str) -> str:
+    joined = "/".join(p for p in parts if p != "")
+    return posix_normalize(joined) if joined else "."
+
+
+def js_string(value: Any, present: bool = True) -> str:
+    """``String(value)``; ``present=False`` stands for JavaScript's ``undefined``."""
+    if not present:
+        return "undefined"
+    if value is None:
+        return "null"
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (bool, int, float)):
+        return number_to_string(value)
+    if isinstance(value, list):
+        return ",".join("" if v is None else js_string(v) for v in value)
+    return "[object Object]"
+
+
+def timestamp(value: Any) -> float:
+    """``Date.parse(value)`` in milliseconds, or NaN, so comparisons with it are false as in JavaScript."""
+    parsed = parse_date(value if isinstance(value, str) else js_string(value))
+    return parsed.timestamp() * 1000 if parsed is not None else math.nan
+
+
+# Package spec §2: white space is ECMAScript's. Python's str.strip() and str.split() use another set.
+JS_WHITESPACE = "\t\n\v\f\r \u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
+
+
+def js_trim(text: str) -> str:
+    """String.prototype.trim."""
+    return text.strip(JS_WHITESPACE)
+
+
+def js_split_ws(text: str) -> list[str]:
+    """``text.trim().split(/\\s+/)`` without empty parts, as ``str.split()`` but with ECMAScript white space."""
+    return [p for p in re.split(f"[{JS_WHITESPACE}]+", text) if p]

moca_reader/attestations.py

@@ -0,0 +1,271 @@
+"""Detached attestations (moca-attestations.md).
+
+A package carries its attestations under attestations/, which the digest excludes. Each file is a DSSE
+envelope (*.dsse.json) or a Sigstore bundle (*.sigstore.json) wrapping an in-toto v1 Statement with one of
+two MOCA predicate types: package/v1 ("this exact package was published by this signer") and review/v1
+("this reviewer checked these exact node files").
+
+This Reader verifies DSSE envelopes, and Sigstore bundles when the ``sigstore`` extra is installed
+(``moca-reader[sigstore]``): offline only, against the host's ``sigstore.trustedRoot`` (attestations §6). Without
+the extra or a trusted root, a Sigstore bundle is unverifiable (A003).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+from ._js import get, json_loads, parse_date
+from .dsse import decode_base64, verify_envelope
+from .schemas import validate_against
+from .unicode import normalize
+
+STATEMENT_TYPE = "https://in-toto.io/Statement/v1"
+PAYLOAD_TYPE = "application/vnd.in-toto+json"
+PREDICATE_PACKAGE = "https://w3id.org/moca/attestation/package/v1"
+PREDICATE_REVIEW = "https://w3id.org/moca/attestation/review/v1"
+
+
+def _hex_of(digest: str) -> str:
+    return digest.removeprefix("sha256:")
+
+
+def package_statement(package_id: str, version: str, digest: str) -> dict[str, Any]:
+    return {
+        "_type": STATEMENT_TYPE,
+        "subject": [{"name": f"{package_id}@{version}", "digest": {"sha256": _hex_of(digest)}}],
+        "predicateType": PREDICATE_PACKAGE,
+        "predicate": {},
+    }
+
+
+class TrustRoot:
+    """A host trust root (moca-attestations.md §6): whose signatures to accept, and for what."""
+
+    def __init__(self, doc: dict[str, Any]) -> None:
+        errors = validate_against("trustRoot", doc)
+        if errors:
+            raise ValueError(f"invalid trust root: {'; '.join(errors)}")
+        self.doc = doc
+        # Attestations §6: keyids are unique.
+        self._keys: dict[str, dict[str, Any]] = {}
+        for k in doc.get("keys", []):
+            if k["keyid"] in self._keys:
+                raise ValueError(f'invalid trust root: keyid "{k["keyid"]}" appears more than once')
+            self._keys[k["keyid"]] = k
+
+    @staticmethod
+    def load(source: str | os.PathLike[str] | dict[str, Any] | TrustRoot) -> TrustRoot:
+        if isinstance(source, TrustRoot):
+            return source
+        if isinstance(source, dict):
+            return TrustRoot(source)
+        with open(source, encoding="utf-8") as f:
+            return TrustRoot(json.load(f))
+
+    @staticmethod
+    def _allows(entry: dict[str, Any], role: str) -> bool:
+        # Attestations §6: `roles` is required; an empty list trusts the entry for nothing.
+        roles = entry.get("roles")
+        return isinstance(roles, list) and role in roles
+
+    def key_entry(self, keyid: str) -> dict[str, Any] | None:
+        """The trust-root entry for a keyid, or None."""
+        return self._keys.get(keyid)
+
+    def key(self, keyid: str, role: str, now: datetime | None = None) -> tuple[str, str] | None:
+        """(public key PEM, identity), or None when the key is unknown, not trusted for the role, or expired."""
+        entry = self._keys.get(keyid)
+        if entry is None or not self._allows(entry, role):
+            return None
+        expires = parse_date(entry.get("expires"))
+        # Attestations §6: a key is not trusted from the instant it expires; one whose expiry does not parse is
+        # not trusted at all.
+        if entry.get("expires") is not None and (expires is None or (now or datetime.now(UTC)) >= expires):
+            return None
+        return entry["publicKey"], entry.get("identity") or keyid
+
+    def sigstore_identities(self, role: str) -> list[dict[str, Any]]:
+        identities = get(self.doc.get("sigstore"), "identities") or []
+        return [i for i in identities if self._allows(i, role)]
+
+
+@dataclass
+class ParsedAttestation:
+    format: str
+    container: Any
+    statement: dict[str, Any]
+
+
+def parse_attestation(path: str, data: bytes) -> ParsedAttestation | str:
+    """The envelope and statement of an attestation file, or the reason it is malformed."""
+    fmt = "sigstore" if path.endswith(".sigstore.json") else "dsse" if path.endswith(".dsse.json") else None
+    if fmt is None:
+        return "attestation files must end in .dsse.json or .sigstore.json"
+    try:
+        container = json_loads(data.decode("utf-8", errors="replace"))
+    except ValueError:
+        return "not valid JSON"
+    envelope = container if fmt == "dsse" else get(container, "dsseEnvelope")
+    if not isinstance(get(envelope, "payload"), str) or not isinstance(get(envelope, "payloadType"), str):
+        return "not a DSSE envelope" if fmt == "dsse" else "Sigstore bundle has no dsseEnvelope"
+    if envelope["payloadType"] != PAYLOAD_TYPE:
+        return f"unexpected payloadType {envelope['payloadType']}"
+    payload = decode_base64(envelope["payload"])
+    if payload is None:
+        return "payload is not base64 or base64url"
+    try:
+        statement = json_loads(payload.decode("utf-8", errors="replace"), unique_keys=True)
+    except ValueError:
+        return "payload is not a JSON in-toto statement"
+    if (
+        get(statement, "_type") != STATEMENT_TYPE
+        or not isinstance(statement.get("subject"), list)
+        or not isinstance(statement.get("predicateType"), str)
+    ):
+        return "payload is not an in-toto v1 Statement"
+    return ParsedAttestation(fmt, container, statement)
+
+
+@dataclass
+class SignatureResult:
+    outcome: str  # valid | invalid | unverifiable | indeterminate
+    signer: str | None = None
+    reason: str | None = None
+    ids: list[str] = field(default_factory=list)
+    reviewers: list[str] | None = None
+
+
+def verify_signature(
+    parsed: ParsedAttestation, trust_root: TrustRoot | None, role: str, now: datetime | None = None
+) -> SignatureResult:
+    """Verifies the signature against the host trust root; not what the statement says."""
+    if trust_root is None:
+        return SignatureResult("unverifiable", reason="no trust root was supplied")
+    if parsed.format == "dsse":
+        signer: list[str] = []
+
+        def resolve(keyid: str) -> str | None:
+            found = trust_root.key(keyid, role, now)
+            if found:
+                signer.append(found[1])
+            return found[0] if found else None
+
+        result = verify_envelope(parsed.container, resolve)
+        if not result.ok:
+            return SignatureResult("invalid", reason=result.reason)
+        found = trust_root.key(result.keyid or "", role, now)
+        entry = trust_root.key_entry(result.keyid or "")
+        ids = [i for i in (entry or {}).get("ids", []) if isinstance(i, str)]
+        listed = (entry or {}).get("reviewers")
+        reviewers = [r for r in listed if isinstance(r, str)] if isinstance(listed, list) else None
+        return SignatureResult(
+            "valid",
+            signer=found[1] if found else (signer[-1] if signer else result.keyid),
+            ids=ids,
+            reviewers=reviewers,
+        )
+    return _verify_sigstore(parsed, trust_root, role)
+
+
+def _verify_sigstore(parsed: ParsedAttestation, trust_root: TrustRoot, role: str) -> SignatureResult:
+    # Attestations §7, step 6: unverifiable only when the trust root lists no Sigstore identities at all, or there
+    # is no trust material; identities that exist but are not trusted for this role make it invalid.
+    sigstore_doc = trust_root.doc.get("sigstore")
+    if not (get(sigstore_doc, "identities") or []):
+        return SignatureResult("unverifiable", reason="the trust root lists no Sigstore identities")
+    trusted_root = get(sigstore_doc, "trustedRoot")
+    if not isinstance(trusted_root, dict):
+        return SignatureResult(
+            "unverifiable",
+            reason="no sigstore.trustedRoot: this Reader verifies Sigstore offline, against the host's trusted root",
+        )
+    try:
+        from sigstore.errors import Error as SigstoreError
+        from sigstore.models import Bundle
+        from sigstore.models import TrustedRoot as SigstoreTrustedRoot
+        from sigstore.verify import Verifier, policy
+        from sigstore_models.trustroot import v1 as trustroot_v1
+    except ImportError:
+        return SignatureResult(
+            "unverifiable", reason="Sigstore verification needs the sigstore extra: pip install moca-reader[sigstore]"
+        )
+    identities = trust_root.sigstore_identities(role)
+    if not identities:
+        return SignatureResult(
+            "invalid", reason=f"no Sigstore identity in the trust root is trusted for the {role} role"
+        )
+    try:
+        verifier = Verifier(
+            trusted_root=SigstoreTrustedRoot(trustroot_v1.TrustedRoot.from_json(json.dumps(trusted_root).encode()))
+        )
+    except Exception as err:  # any failure here: the trust material is unusable
+        return SignatureResult("unverifiable", reason=f"sigstore.trustedRoot cannot be used: {err}")
+    try:
+        bundle = Bundle.from_json(json.dumps(parsed.container))
+    except Exception as err:  # a bundle the library cannot read signs nothing
+        return SignatureResult("invalid", reason=f"not a valid Sigstore bundle: {err}")
+    last = "verification failed"
+    for identity in identities:
+        issuer, subject = identity.get("issuer"), identity.get("subject")
+        if not isinstance(issuer, str) or not isinstance(subject, str):
+            continue
+        try:
+            # Attestations §6: issuer and subject alternative name match exactly; no patterns.
+            verifier.verify_dsse(bundle, policy.Identity(identity=subject, issuer=issuer))
+        except (SigstoreError, ValueError) as err:
+            last = str(err)
+            continue
+        ids = [i for i in identity.get("ids", []) if isinstance(i, str)]
+        listed = identity.get("reviewers")
+        reviewers = [r for r in listed if isinstance(r, str)] if isinstance(listed, list) else None
+        return SignatureResult("valid", signer=f"{issuer} {subject}", ids=ids, reviewers=reviewers)
+    return SignatureResult("invalid", reason=last)
+
+
+def check_package_statement(statement: dict[str, Any], package_id: Any, version: Any, digest: str) -> str | None:
+    """The reason the statement does not attest this package, or None."""
+    if statement.get("predicateType") != PREDICATE_PACKAGE:
+        return "not a package attestation"
+    subjects = statement["subject"]
+    subject = subjects[0] if subjects else None
+    name = get(subject, "name")
+    if len(subjects) != 1 or name != f"{package_id}@{version}":
+        return f'subject "{name}" does not name {package_id}@{version}'
+    if get(get(subject, "digest"), "sha256") != _hex_of(digest):
+        return "subject digest does not match the package digest"
+    return None
+
+
+@dataclass
+class ReviewCheck:
+    error: str | None = None
+    current: list[str] = field(default_factory=list)
+    outdated: list[str] = field(default_factory=list)
+    predicate: dict[str, Any] | None = None
+
+
+def check_review_statement(statement: dict[str, Any], package_id: Any, file_digests: dict[str, str]) -> ReviewCheck:
+    predicate: Any = statement.get("predicate")
+    errors = validate_against("reviewPredicate", predicate)
+    if errors:
+        return ReviewCheck(f"review predicate is invalid: {'; '.join(errors)}")
+    if predicate["package"] != package_id:
+        return ReviewCheck(f"review names package {predicate['package']}, not {package_id}")
+    check = ReviewCheck(predicate=predicate)
+    for s in statement["subject"]:
+        name, sha = get(s, "name"), get(get(s, "digest"), "sha256")
+        if not isinstance(name, str) or not isinstance(sha, str):
+            return ReviewCheck("review subject entries need a name and a sha256 digest")
+        (check.current if file_digests.get(normalize("NFC", name)) == sha else check.outdated).append(name)
+    return check
+
+
+def scope_covers(scopes: list[str], package_id: Any) -> bool:
+    """Package spec §7.2: whether a signer's ``ids`` cover a package id (exact, or a prefix ending in /, : or #)."""
+    if not isinstance(package_id, str):
+        return False
+    return any(s == package_id or (s[-1:] in ("/", ":", "#") and package_id.startswith(s)) for s in scopes)