llmt-cli 0.2.0__py3-none-any.whl

llmt/manifest.py

@@ -0,0 +1,314 @@
+"""Ed25519 manifest verification — llmt's authenticity layer (Fix M2, Option A).
+
+For every published torrent the catalog serves a manifest document signed
+with the site's Ed25519 manifest key (FROZEN contract: llmt-manifest-spec
+v0.1.0, WP-3.3 signing, WP-8.1 endpoint):
+
+    GET /api/manifests/{info_hash} ->
+        {"data": <manifest doc, incl. its `signature` block>,
+         "meta": {"schema_version", "signature", "signed_at"}}
+
+SIGNING INPUT (must match the server byte-for-byte):
+    canonical JSON of the manifest WITHOUT its `signature` key — object keys
+    sorted recursively by UTF-8 byte order, array order preserved,
+    separators "," and ":", unicode NOT escaped, slashes NOT escaped, UTF-8,
+    no trailing newline. In Python that is exactly
+    ``json.dumps(body, sort_keys=True, separators=(",", ":"),
+    ensure_ascii=False).encode("utf-8")``.
+    The signature is a DETACHED Ed25519 signature (libsodium
+    ``crypto_sign_detached``), base64 in ``signature.sig`` alongside
+    ``signature.algo`` ("ed25519") and ``signature.key_id``.
+
+TRUST ROOT: the public key PINNED IN THIS PACKAGE
+(``llmt/data/manifest-pubkey.json``) — decided 2026-07-13 (M2, Option A).
+The key published at https://llmtorrents.com/manifest-pubkey is NEVER
+fetched at runtime for trust decisions; a manifest signed by any other key
+does not verify here. Key rotation therefore ships as a new llmt release —
+the wrong-key failure message says so.
+
+Every failure raises :class:`~llmt.errors.ManifestVerificationError` with a
+distinct, honest reason. There is no silent fallback to the old TLS-only
+"file matches the catalog sha256" claim: unverifiable means NOT verified.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from nacl.exceptions import BadSignatureError
+from nacl.signing import VerifyKey
+
+from .errors import LlmtError, ManifestVerificationError
+
+_PINNED_RESOURCE = "manifest-pubkey.json"
+_ED25519_KEY_BYTES = 32
+_ED25519_SIG_BYTES = 64
+
+
+@dataclass(frozen=True)
+class PinnedKey:
+    """The packaged trust root: algo + key id + raw 32-byte public key."""
+
+    algo: str
+    key_id: str
+    public_key: bytes
+
+    @property
+    def fingerprint(self) -> str:
+        """SHA-256 hex of the raw public-key bytes (for display/audit)."""
+        return hashlib.sha256(self.public_key).hexdigest()
+
+
+def load_pinned_key() -> PinnedKey:
+    """Load the Ed25519 public key shipped inside the llmt package.
+
+    This file is part of the installed package — it is the trust anchor, so
+    a damaged/missing/inconsistent pin is a hard failure, never a downgrade.
+    """
+    from importlib import resources
+
+    try:
+        text = (resources.files("llmt") / "data" / _PINNED_RESOURCE
+                ).read_text("utf-8")
+        data = json.loads(text)
+        algo = data["algo"]
+        key_id = data["key_id"]
+        public_key = bytes.fromhex(data["public_key_hex"])
+        expected_fp = data.get("public_key_sha256_fingerprint")
+    except Exception as exc:
+        raise ManifestVerificationError(
+            "cannot load the manifest public key pinned in this llmt build "
+            f"({exc.__class__.__name__}: {exc}); the installation is damaged "
+            "— reinstall llmt. Nothing was verified."
+        ) from exc
+
+    if (algo != "ed25519" or len(public_key) != _ED25519_KEY_BYTES
+            or not key_id):
+        raise ManifestVerificationError(
+            "the manifest public key pinned in this llmt build is invalid "
+            "(wrong algo, key id, or key length); the installation is "
+            "damaged — reinstall llmt. Nothing was verified."
+        )
+    pinned = PinnedKey(algo=algo, key_id=key_id, public_key=public_key)
+    if expected_fp and pinned.fingerprint != expected_fp.lower():
+        raise ManifestVerificationError(
+            "the manifest public key pinned in this llmt build does not "
+            "match its recorded fingerprint; the installation is damaged — "
+            "reinstall llmt. Nothing was verified."
+        )
+    return pinned
+
+
+def canonical_json(value: Any) -> bytes:
+    """Serialize per the frozen canonicalization (llmt-manifest-spec).
+
+    ``json.dumps(sort_keys=True)`` sorts object keys recursively by code
+    point, which equals UTF-8 byte order; list order is preserved;
+    ``separators=(",", ":")`` removes whitespace; ``ensure_ascii=False``
+    leaves unicode unescaped (Python never escapes slashes).
+    """
+    _reject_floats(value)
+    return json.dumps(value, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=False).encode("utf-8")
+
+
+def _reject_floats(value: Any) -> None:
+    # The frozen spec defines canonical encoding only for objects, arrays,
+    # strings, booleans, null and INTEGERS. Float formatting differs across
+    # languages, so a float in a manifest is unverifiable — refuse rather
+    # than guess (fail closed).
+    if isinstance(value, float):
+        raise ManifestVerificationError(
+            "manifest contains a non-integer number; the frozen "
+            "canonicalization does not define float encoding — refusing to "
+            "verify (not verified)."
+        )
+    if isinstance(value, dict):
+        for v in value.values():
+            _reject_floats(v)
+    elif isinstance(value, list):
+        for v in value:
+            _reject_floats(v)
+
+
+def signing_input(doc: dict) -> bytes:
+    """Canonical bytes of the manifest with its ``signature`` block removed."""
+    body = {k: v for k, v in doc.items() if k != "signature"}
+    return canonical_json(body)
+
+
+def verify_manifest_document(doc: Any, *, info_hash: Optional[str] = None,
+                             pinned: Optional[PinnedKey] = None) -> dict:
+    """Verify a manifest document's Ed25519 signature against the pinned key.
+
+    Returns the document iff EVERYTHING checks out; otherwise raises
+    :class:`ManifestVerificationError` with a distinct reason. When
+    ``info_hash`` is given, additionally requires the SIGNED document to
+    name that info hash (v1 or v2) — a validly-signed manifest for a
+    *different* torrent is a substitution, not a verification.
+    """
+    if pinned is None:
+        pinned = load_pinned_key()
+
+    if not isinstance(doc, dict) or not isinstance(doc.get("signature"), dict):
+        raise ManifestVerificationError(
+            "the catalog's manifest is malformed (no signature block) — "
+            "not verified."
+        )
+    sig_block = doc["signature"]
+    algo = sig_block.get("algo")
+    key_id = sig_block.get("key_id")
+    sig_b64 = sig_block.get("sig")
+
+    if algo != pinned.algo:
+        raise ManifestVerificationError(
+            f"manifest signature algorithm {algo!r} is not the pinned "
+            f"{pinned.algo!r} — refusing to verify (not verified)."
+        )
+    if key_id != pinned.key_id:
+        raise ManifestVerificationError(
+            f"manifest is signed with key id {key_id!r} but this llmt build "
+            f"pins {pinned.key_id!r}. If the catalog has rotated its signing "
+            "key, a newer llmt release carries the new pinned key — upgrade "
+            "llmt via pip/your package manager. Not verified."
+        )
+
+    sig: Optional[bytes] = None
+    if isinstance(sig_b64, str):
+        try:
+            sig = base64.b64decode(sig_b64, validate=True)
+        except (binascii.Error, ValueError):
+            sig = None
+    if sig is None or len(sig) != _ED25519_SIG_BYTES:
+        raise ManifestVerificationError(
+            "manifest signature is not a valid base64-encoded Ed25519 "
+            "signature — not verified."
+        )
+
+    message = signing_input(doc)
+    try:
+        VerifyKey(pinned.public_key).verify(message, sig)
+    except BadSignatureError:
+        raise ManifestVerificationError(
+            "manifest signature is INVALID: the document does not verify "
+            "against the catalog public key pinned in this llmt build. The "
+            "manifest may be forged, tampered with, or corrupted — not "
+            "verified."
+        ) from None
+
+    if info_hash:
+        torrent = doc.get("torrent")
+        torrent = torrent if isinstance(torrent, dict) else {}
+        needle = info_hash.strip().lower()
+        named = {str(torrent.get(k) or "").lower()
+                 for k in ("info_hash_v1", "info_hash_v2")}
+        if needle not in named:
+            raise ManifestVerificationError(
+                "the signed manifest describes a DIFFERENT torrent (info "
+                f"hash {needle} is not named by the manifest) — possible "
+                "manifest substitution; not verified."
+            )
+    return doc
+
+
+def fetch_verified_manifest(client: Any, info_hash: Optional[str], *,
+                            pinned: Optional[PinnedKey] = None) -> dict:
+    """Fetch ``/api/manifests/{info_hash}`` and verify it. Fail closed.
+
+    ``client`` is an :class:`llmt.api.ApiClient`. ANY failure — no info
+    hash, network/API error (including offline), malformed envelope, bad
+    signature — raises :class:`ManifestVerificationError`; there is no
+    quiet degradation to unauthenticated hashes.
+    """
+    if not info_hash:
+        raise ManifestVerificationError(
+            "the catalog supplied no info hash for this download, so its "
+            "signed manifest cannot be fetched — not verified."
+        )
+    try:
+        payload = client.get_manifest(info_hash)
+    except LlmtError as exc:
+        raise ManifestVerificationError(
+            f"could not fetch the signed manifest for {info_hash} ({exc}) — "
+            "without the Ed25519-signed manifest llmt cannot authenticate "
+            "the catalog's hashes, so nothing is reported as verified. "
+            "(TLS alone is not treated as verification; if you are offline, "
+            "re-run when the catalog is reachable.)"
+        ) from exc
+    doc = payload.get("data") if isinstance(payload, dict) else None
+    if not isinstance(doc, dict):
+        raise ManifestVerificationError(
+            "the catalog's manifest response is malformed (no manifest "
+            "document) — not verified."
+        )
+    return verify_manifest_document(doc, info_hash=info_hash, pinned=pinned)
+
+
+def manifest_files(doc: dict) -> list[dict[str, Any]]:
+    """Normalise a VERIFIED manifest's ``files[]`` to {path, sha256, size}.
+
+    The manifest schema requires ``path``/``size_bytes``/``sha256`` on every
+    entry; anything else is malformed and refused (fail closed).
+    """
+    files = doc.get("files")
+    if not isinstance(files, list) or not files:
+        raise ManifestVerificationError(
+            "the signed manifest lists no files — nothing can be verified "
+            "against it (not verified)."
+        )
+    out: list[dict[str, Any]] = []
+    for f in files:
+        if (not isinstance(f, dict) or not f.get("path")
+                or not f.get("sha256")):
+            raise ManifestVerificationError(
+                "the signed manifest has a malformed files[] entry (missing "
+                "path or sha256) — not verified."
+            )
+        size = f.get("size_bytes")
+        out.append({
+            "path": f["path"],
+            "sha256": str(f["sha256"]).lower(),
+            "size": int(size)
+            if isinstance(size, int) and not isinstance(size, bool) else None,
+        })
+    return out
+
+
+def check_catalog_consistency(catalog_files: list[dict[str, Any]],
+                              verified_files: list[dict[str, Any]]) -> None:
+    """The catalog's ``download.files[]`` must agree with the SIGNED manifest.
+
+    The manifest is the authenticated source of truth; the catalog's file
+    block is unauthenticated convenience data. If they disagree, something
+    between us and the signer is lying — refuse loudly rather than attest
+    against either version.
+    """
+    cat = {f["path"]: f for f in catalog_files if f.get("path")}
+    man = {f["path"]: f for f in verified_files}
+    problems = []
+    for path in sorted(set(cat) | set(man)):
+        c, m = cat.get(path), man.get(path)
+        if c is None:
+            problems.append(f"{path!r} is in the signed manifest but not "
+                            "the catalog")
+        elif m is None:
+            problems.append(f"{path!r} is in the catalog but not the signed "
+                            "manifest")
+        elif (c.get("sha256") or "").lower() != m["sha256"]:
+            problems.append(f"{path!r}: catalog sha256 differs from the "
+                            "signed manifest")
+        elif (c.get("size") is not None and m["size"] is not None
+              and c["size"] != m["size"]):
+            problems.append(f"{path!r}: catalog size differs from the "
+                            "signed manifest")
+    if problems:
+        raise ManifestVerificationError(
+            "the catalog's file list does not match the Ed25519-signed "
+            "manifest — refusing to verify (not verified): "
+            + "; ".join(problems)
+        )

llmt/matcher.py

@@ -0,0 +1,358 @@
+"""Match locally-hashed files against the registry via the frozen WP-14.2
+artifact-lookup API, and assemble seedable matches.
+
+``POST /api/artifacts/lookup`` body ``{"sha256":[... <=100 ...]}`` returns
+``{"data":{"results":[...]},"meta":{...}}`` with results in INPUT ORDER.
+
+Trust model (red-team axes):
+  * **HTTPS enforced** — we refuse to send file hashes over a non-HTTPS API
+    base (except explicit loopback for local dev). A downgraded/plaintext base
+    is a MITM vector.
+  * **Local hash is the only seedability proof** — a file is only ever offered
+    for seeding when the registry reports ``known:true`` for the EXACT digest we
+    computed locally from the full file. A right-size / wrong-hash / truncated
+    file yields a different digest and therefore can never match. We never match
+    on size alone.
+  * **Response is untrusted** — shapes are validated defensively; results are
+    re-keyed by their own ``sha256`` field (not blindly by position), so a
+    reordered / duplicated / spoofed response cannot cross-wire one file's
+    digest onto another's containers. A declared ``size_bytes`` that disagrees
+    with the local file size is treated as a corruption/spoof signal and the
+    file is NOT offered.
+  * **Distribution fields are untrusted** — ``magnet`` is only carried for an
+    ``available`` non-revoked container; webseed URLs are never stored or
+    surfaced (they can carry credentials). ``info_hash`` values are hex-checked.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Optional
+from urllib.parse import parse_qsl, urlsplit
+
+import requests
+
+from .api import ApiClient
+from .errors import ApiError, RateLimitedError, TimeoutErrorLlmt
+from .scanner import HashedFile
+
+MAX_BATCH = 100
+_HEX64_RE = re.compile(r"^[0-9a-f]{64}$")
+_HEX40_RE = re.compile(r"^[0-9a-f]{40}$")
+_VALID_STATUS = {"active", "superseded", "revoked"}
+_LOOPBACK = {"localhost", "127.0.0.1", "::1"}
+
+
+# --------------------------------------------------------------------------- #
+# Validated response objects
+# --------------------------------------------------------------------------- #
+
+@dataclass
+class Container:
+    torrent_id: Any
+    torrent_name: str
+    path: str
+    file_name: str
+    status: str
+    available: bool
+    quants: list = field(default_factory=list)
+    magnet: Optional[str] = None
+    info_hash_v1: Optional[str] = None
+    info_hash_v2: Optional[str] = None
+    seeders: Optional[int] = None
+    leechers: Optional[int] = None
+
+    def container_dict(self) -> dict[str, Any]:
+        """Minimal dict the frozen layout mapper consumes (path/file_name)."""
+        return {"path": self.path, "file_name": self.file_name}
+
+    def describe(self) -> str:
+        for q in self.quants:
+            if isinstance(q, dict):
+                name = q.get("model_name") or q.get("model_slug") or "?"
+                ql = q.get("quant_label") or "?"
+                fmt = q.get("format") or "?"
+                return f"{name} {ql} ({fmt})"
+        return self.torrent_name or self.file_name or "?"
+
+
+@dataclass
+class LookupEntry:
+    sha256: str
+    known: bool
+    size_bytes: Optional[int] = None
+    kind: Optional[str] = None
+    containers: list = field(default_factory=list)
+
+
+@dataclass
+class Match:
+    file: HashedFile
+    entry: LookupEntry
+    container: Container
+
+
+# --------------------------------------------------------------------------- #
+# Defensive field cleaners
+# --------------------------------------------------------------------------- #
+
+def _clean_magnet(raw: Any) -> Optional[str]:
+    if not isinstance(raw, str):
+        return None
+    m = raw.strip()
+    if not m.startswith("magnet:?"):
+        return None
+    if any(c in m for c in (" ", "\n", "\r", "\t", "\x00")):
+        return None
+    if len(m) > 8192:
+        return None
+    # Untrusted server string: drop a magnet whose embedded tracker/webseed URL
+    # smuggles userinfo (user:pass@host) even though the frozen API sanitizes.
+    try:
+        for key, val in parse_qsl(urlsplit(m).query, keep_blank_values=True):
+            if key.lower() in ("tr", "ws", "xs", "as", "mt") and "://" in val:
+                if "@" in urlsplit(val).netloc:
+                    return None
+    except ValueError:
+        return None
+    return m
+
+
+def _clean_hash(raw: Any, *, length: int) -> Optional[str]:
+    if not isinstance(raw, str):
+        return None
+    h = raw.strip().lower()
+    if length == 40 and _HEX40_RE.match(h):
+        return h
+    if length == 64 and _HEX64_RE.match(h):
+        return h
+    return None
+
+
+def _int_or_none(raw: Any) -> Optional[int]:
+    if isinstance(raw, bool):
+        return None
+    if isinstance(raw, int):
+        return raw
+    return None
+
+
+def _parse_container(raw: Any) -> Optional[Container]:
+    if not isinstance(raw, dict):
+        return None
+    path = raw.get("path")
+    file_name = raw.get("file_name")
+    if not isinstance(path, str) and not isinstance(file_name, str):
+        return None  # nothing to map a layout from
+    if not isinstance(path, str):
+        path = file_name
+    if not isinstance(file_name, str):
+        file_name = path.replace("\\", "/").rsplit("/", 1)[-1]
+    status = raw.get("status")
+    if status not in _VALID_STATUS:
+        status = "unknown"
+    available = bool(raw.get("available"))
+    quants = raw.get("quants")
+    quants = quants if isinstance(quants, list) else []
+
+    magnet = ihv1 = ihv2 = None
+    seeders = leechers = None
+    # Distribution fields exist ONLY for an available, non-revoked container.
+    if available and status != "revoked":
+        magnet = _clean_magnet(raw.get("magnet"))
+        ihv1 = _clean_hash(raw.get("info_hash_v1"), length=40)
+        ihv2 = _clean_hash(raw.get("info_hash_v2"), length=64)
+        seeders = _int_or_none(raw.get("seeders"))
+        leechers = _int_or_none(raw.get("leechers"))
+    return Container(
+        torrent_id=raw.get("torrent_id"),
+        torrent_name=str(raw.get("torrent_name") or ""),
+        path=path, file_name=file_name, status=status, available=available,
+        quants=quants, magnet=magnet, info_hash_v1=ihv1, info_hash_v2=ihv2,
+        seeders=seeders, leechers=leechers,
+    )
+
+
+def _parse_entry(sha: str, raw: Any) -> LookupEntry:
+    if not isinstance(raw, dict):
+        return LookupEntry(sha256=sha, known=False)
+    # Defensive: an entry must echo OUR digest. A mismatch means the response is
+    # reordered/spoofed for this slot -> treat as unknown (never cross-wire).
+    got = raw.get("sha256")
+    if not isinstance(got, str) or got.strip().lower() != sha:
+        return LookupEntry(sha256=sha, known=False)
+    if raw.get("valid") is False:
+        return LookupEntry(sha256=sha, known=False)
+    if not raw.get("known"):
+        return LookupEntry(sha256=sha, known=False)
+    size = raw.get("size_bytes")
+    size = size if isinstance(size, int) and not isinstance(size, bool) else None
+    containers = []
+    for c in raw.get("containers") or []:
+        parsed = _parse_container(c)
+        if parsed is not None:
+            containers.append(parsed)
+    return LookupEntry(
+        sha256=sha, known=True, size_bytes=size,
+        kind=(raw.get("kind") if isinstance(raw.get("kind"), str) else None),
+        containers=containers,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# HTTPS enforcement + POST
+# --------------------------------------------------------------------------- #
+
+def require_https(base: str) -> None:
+    parts = urlsplit(base)
+    host = (parts.hostname or "").lower()
+    if parts.scheme == "https":
+        return
+    if parts.scheme == "http" and host in _LOOPBACK:
+        return
+    raise ApiError(
+        f"refusing to send file hashes over a non-HTTPS API base: {base!r}. "
+        f"Use an https:// endpoint (MITM/spoofing defense).",
+        code="insecure_api_base",
+    )
+
+
+def _post_lookup(client: ApiClient, chunk: list[str]) -> dict[str, Any]:
+    url = f"{client.base}/artifacts/lookup"
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": "llmt-cli",
+    }
+    if client.key:
+        headers["Authorization"] = f"Bearer {client.key}"
+    try:
+        resp = client.session.post(
+            url, json={"sha256": chunk}, headers=headers, timeout=client.timeout,
+        )
+    except requests.Timeout as exc:
+        raise TimeoutErrorLlmt(f"artifact lookup timed out: {url}") from exc
+    except requests.RequestException as exc:
+        raise ApiError(f"artifact lookup failed: {exc}") from exc
+
+    if resp.status_code == 422:
+        raise ApiError("artifact lookup rejected the batch (batch_too_large).",
+                       code="batch_too_large", status=422)
+    if resp.status_code == 429:
+        # Scan F1: a 429 is a typed RateLimitedError (honors Retry-After),
+        # aligned with the telemetry write-API's 429 handling.
+        ra = resp.headers.get("Retry-After")
+        retry_after = None
+        if ra is not None:
+            try:
+                retry_after = int(ra)
+            except ValueError:
+                retry_after = None
+        raise RateLimitedError(
+            "artifact lookup rate-limited (429).",
+            retry_after=retry_after, code="rate_limited", status=429)
+    if resp.status_code != 200:
+        raise ApiError(f"artifact lookup returned HTTP {resp.status_code}.",
+                       status=resp.status_code)
+    try:
+        payload = resp.json()
+    except ValueError as exc:
+        raise ApiError("artifact lookup returned non-JSON.",
+                       code="bad_response") from exc
+    return payload
+
+
+def _merge(results: dict[str, LookupEntry], chunk: list[str],
+           payload: dict[str, Any]) -> None:
+    data = payload.get("data") if isinstance(payload, dict) else None
+    res = data.get("results") if isinstance(data, dict) else None
+    if not isinstance(res, list):
+        raise ApiError("malformed lookup response: missing data.results[].",
+                       code="bad_response")
+    # Results are contractually in input order, but we re-key by each entry's
+    # OWN sha256 so a reordered/duplicated response cannot mis-assign. Any
+    # requested sha with no self-consistent entry stays unknown.
+    by_sha: dict[str, Any] = {}
+    for item in res:
+        if isinstance(item, dict):
+            s = item.get("sha256")
+            if isinstance(s, str) and _HEX64_RE.match(s.strip().lower()):
+                by_sha.setdefault(s.strip().lower(), item)
+    for sha in chunk:
+        results[sha] = _parse_entry(sha, by_sha.get(sha))
+
+
+def lookup_shas(client: ApiClient, shas: list[str]) -> dict[str, LookupEntry]:
+    """Look up digests in chunks of <=100. Returns ``{sha256 -> LookupEntry}``."""
+    require_https(client.base)
+    uniq: list[str] = []
+    seen: set[str] = set()
+    for s in shas:
+        if isinstance(s, str):
+            sl = s.strip().lower()
+            if _HEX64_RE.match(sl) and sl not in seen:
+                seen.add(sl)
+                uniq.append(sl)
+    results: dict[str, LookupEntry] = {}
+    for i in range(0, len(uniq), MAX_BATCH):
+        chunk = uniq[i:i + MAX_BATCH]
+        _merge(results, chunk, _post_lookup(client, chunk))
+    return results
+
+
+# --------------------------------------------------------------------------- #
+# Match assembly (the seed/refuse gate)
+# --------------------------------------------------------------------------- #
+
+#: The ONLY catalog statuses ever offered for seeding. Any other value —
+#: ``revoked``, or an unrecognized/garbage status normalized to ``unknown`` by
+#: ``_parse_container`` — FAILS CLOSED and is never seeded. Untrusted status
+#: must not open a seeding path.
+_SEEDABLE_STATUS = ("active", "superseded")
+
+
+def choose_container(entry: LookupEntry) -> Optional[Container]:
+    """Pick the best seedable container: available, has a magnet, and a status
+    we explicitly recognize as seedable. Prefer ``active`` over ``superseded``.
+    Revoked / unavailable / unknown-status containers are never returned."""
+    seedable = [c for c in entry.containers
+                if c.available and c.status in _SEEDABLE_STATUS and c.magnet]
+    for pref in _SEEDABLE_STATUS:
+        for c in seedable:
+            if c.status == pref:
+                return c
+    return None
+
+
+def assemble_matches(
+    hashed: list[HashedFile], results: dict[str, LookupEntry],
+) -> tuple[list[Match], list[HashedFile], list[tuple[HashedFile, LookupEntry]]]:
+    """Split scanned files into (matches, unmatched, size-disagreements).
+
+    A Match requires ALL of:
+      * registry ``known:true`` keyed by the local full-file digest,
+      * the entry's echoed digest equals the local digest,
+      * declared ``size_bytes`` (if any) equals the local file size,
+      * a seedable container (available, non-revoked, valid magnet).
+    Anything else is never offered for seeding.
+    """
+    matches: list[Match] = []
+    unmatched: list[HashedFile] = []
+    size_bad: list[tuple[HashedFile, LookupEntry]] = []
+    for hf in hashed:
+        entry = results.get(hf.sha256)
+        if entry is None or not entry.known or entry.sha256 != hf.sha256:
+            unmatched.append(hf)
+            continue
+        if entry.size_bytes is not None and entry.size_bytes != hf.size:
+            # Digest matched but the server's declared size disagrees with the
+            # bytes on disk: refuse (spoof / metadata-corruption signal).
+            size_bad.append((hf, entry))
+            continue
+        container = choose_container(entry)
+        if container is None:
+            unmatched.append(hf)  # known but nothing seedable (revoked/gated)
+            continue
+        matches.append(Match(file=hf, entry=entry, container=container))
+    return matches, unmatched, size_bad