mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/hosted_acquisition.py

@@ -0,0 +1,974 @@
+"""Requester-bound Studio acquisition for hosts without the reviewed local clean room."""
+
+from __future__ import annotations
+
+import importlib
+import re
+import ssl
+import tempfile
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from typing import Any, Protocol
+from urllib.error import HTTPError
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, HTTPSHandler, ProxyHandler, Request, build_opener
+from uuid import UUID
+
+from mostlyright.data_harness.acquisition.result_download import (
+    RESULT_CHUNK_BYTES,
+    ResultBytesVerifier,
+    ResultDownloadError,
+    ValidatedResultDownload,
+    validate_result_download,
+)
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_json_bytes,
+    canonical_sha256,
+    parse_foreign_json,
+    sha256_bytes,
+)
+from mostlyright.data_harness.formats import FORMAT_MEDIA_TYPES, FORMAT_SUFFIXES
+from mostlyright.data_harness.hosted_crawler_protocol import (
+    CRAWLER_FAILURE_SCHEMA,
+    PUBLIC_HTTPS_EGRESS_POLICY_ATTESTATION,
+    HostedCrawlerProtocolError,
+    HostedCrawlerRequest,
+    parse_crawler_failure,
+    parse_crawler_result,
+)
+from mostlyright.data_harness.local_contracts import ContractError, validate_source_locator
+from mostlyright.data_harness.readers.contracts import DECODE_FLAGS, ReaderPin
+from mostlyright.data_harness.readers.registry import TOOLBOX
+from mostlyright.data_harness.studio_boundary import (
+    StudioBoundaryError,
+    StudioClientIncompatibleError,
+    ensure_studio_client,
+    studio_wire_dict,
+)
+from mostlyright.data_harness.ux.credentials import ResolvedCloudCredentials, StoredCredentials
+from mostlyright.data_harness.ux.login import DeviceFlowTransport, UrlLibDeviceFlowTransport
+
+TOKEN_EXCHANGE_PATH = "/api/cli/public-acquisition-token"
+TOKEN_EXCHANGE_MAX_BYTES = 16 * 1024
+POLL_TIMEOUT_SECONDS = 1800.0
+# A transferred result smaller than this never touches the disk; a larger one spills to a temporary
+# file that is unlinked before a byte is written to it.  Eight mebibytes is the threshold the
+# viewer's spool already uses, and a hosted result is either a small refusal bundle or a very large
+# one, so the value only decides which side of that gap the common cases land on.
+DOWNLOAD_SPOOL_BYTES = 8 * 1024 * 1024
+# One sentence for the three transfer bounds it covers, so the status, media-type and length
+# refusals stay indistinguishable to a caller no matter which of them fired.
+_DOWNLOAD_INVALID_DETAIL = (
+    "the hosted acquisition result violated its media type, status, or byte bound"
+)
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+_FAILURE_CODE = re.compile(r"^[A-Z][A-Z0-9_]{2,127}$")
+_BARE_FILENAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,254}$")
+_RECEIPT_FIELDS = {
+    "schema_version",
+    "source_id",
+    "adapter_id",
+    "adapter_version",
+    "request_digest",
+    "source_url",
+    "final_url",
+    "fetched_media_type",
+    "normalized_media_type",
+    "normalized_data_format",
+    "normalized_filename",
+    "acquired_at",
+    "raw_content_sha256",
+    "raw_size_bytes",
+    "normalized_content_sha256",
+    "normalized_size_bytes",
+    "row_count",
+    "column_names",
+    "parsed_schema_digest",
+    "family_id",
+    "family_version",
+    "decode_options_digest",
+    "decode_flags",
+    "resource_caps",
+    "reader_budgets",
+    "transport_evidence_digest",
+    "egress_policy_attestation",
+    "clean_room",
+}
+
+
+class HostedAcquisitionError(RuntimeError):
+    """One hosted acquisition boundary failed with a safe, stable code."""
+
+    def __init__(self, code: str, detail: str, *, retry_after_seconds: int | None = None) -> None:
+        self.code = code
+        self.detail = detail
+        self.retry_after_seconds = retry_after_seconds
+        super().__init__(f"{detail} [{code}]")
+
+
+def _failure_code(value: Any, fallback: str) -> str:
+    """Admit Studio's bounded worker-result code, never an arbitrary failure body."""
+
+    return value if isinstance(value, str) and _FAILURE_CODE.fullmatch(value) else fallback
+
+
+@dataclass(frozen=True)
+class StudioToken:
+    base_url: str
+    workspace_id: UUID
+    token: str
+    expires_at: datetime
+    crawler_results_bucket: str | None = None
+    principal_id: UUID | None = None
+
+    def __repr__(self) -> str:
+        return (
+            f"StudioToken(base_url={self.base_url!r}, workspace_id={self.workspace_id!r}, "
+            f"expires_at={self.expires_at!r}, token='<redacted>')"
+        )
+
+
+@dataclass(frozen=True)
+class HostedAcquisition:
+    content: bytes
+    source_url: str
+    final_url: str
+    media_type: str
+    data_format: str
+    raw_content_sha256: str
+    transport_evidence_digest: str
+    parsed_schema_digest: str
+    family_id: str | None
+    family_version: str | None
+    decode_options_digest: str | None
+    decode_flags: tuple[str, ...]
+    egress_policy_attestation: str
+    request_digest: str
+
+
+class StudioExchange(Protocol):
+    def acquire(
+        self,
+        *,
+        workspace_id: UUID,
+        source_id: str,
+        source_authority_digest: str,
+        acquisition_attempt_id: str,
+        query: Mapping[str, Any],
+    ) -> tuple[Mapping[str, Any], bytes]: ...
+
+
+def _https_origin(value: Any, label: str) -> str:
+    if not isinstance(value, str) or not 1 <= len(value) <= 2_048 or value.endswith("/"):
+        raise HostedAcquisitionError(
+            "HOSTED_CONFIG_INVALID", f"{label} is not a plain HTTPS origin"
+        )
+    try:
+        parsed = urlsplit(value)
+        port = parsed.port
+    except ValueError as error:
+        raise HostedAcquisitionError(
+            "HOSTED_CONFIG_INVALID", f"{label} is not a plain HTTPS origin"
+        ) from error
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.path not in {"", "/"}
+        or parsed.query
+        or parsed.fragment
+        or port not in {None, 443}
+    ):
+        raise HostedAcquisitionError(
+            "HOSTED_CONFIG_INVALID", f"{label} is not a plain HTTPS origin"
+        )
+    return value
+
+
+def exchange_studio_token(
+    credentials: StoredCredentials | ResolvedCloudCredentials,
+    *,
+    transport: DeviceFlowTransport | None = None,
+) -> StudioToken:
+    """Exchange the selected cloud key without ever sending it to Studio."""
+
+    cloud = _https_origin(credentials.cloud_url, "configured cloud URL")
+    try:
+        status, raw = (transport or UrlLibDeviceFlowTransport()).request(
+            "POST",
+            cloud + TOKEN_EXCHANGE_PATH,
+            {
+                "Authorization": f"Bearer {credentials.raw_key}",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+            b"{}",
+            TOKEN_EXCHANGE_MAX_BYTES,
+        )
+    except Exception as error:
+        raise HostedAcquisitionError(
+            "HOSTED_TOKEN_EXCHANGE_UNAVAILABLE",
+            "the Mostly Right cloud could not prepare a short-lived Studio credential",
+        ) from error
+    try:
+        value = parse_foreign_json(raw)
+    except CanonicalJSONError as error:
+        raise HostedAcquisitionError(
+            "HOSTED_TOKEN_EXCHANGE_INVALID",
+            "the Mostly Right cloud returned an invalid Studio credential response",
+        ) from error
+    if (
+        status != 200
+        or not isinstance(value, dict)
+        or set(value)
+        != {
+            "studio_base_url",
+            "workspace_id",
+            "token",
+            "expires_at",
+            "crawler_results_bucket",
+            "studio_principal_id",
+        }
+    ):
+        if status == 401 and value == {"error": "missing or invalid access key"}:
+            code = "HOSTED_AUTHENTICATION_REQUIRED"
+        elif status == 402 and value == {"error": "subscription required"}:
+            code = "HOSTED_ENTITLEMENT_REQUIRED"
+        else:
+            code = "HOSTED_TOKEN_EXCHANGE_UNAVAILABLE"
+        retry_after_seconds = None
+        if (
+            status == 503
+            and isinstance(value, dict)
+            and set(value) == {"error", "retry_after_seconds"}
+            and value.get("error") == "temporarily unavailable"
+            and isinstance(value.get("retry_after_seconds"), int)
+            and not isinstance(value.get("retry_after_seconds"), bool)
+            and 1 <= value["retry_after_seconds"] <= 3_600
+        ):
+            retry_after_seconds = value["retry_after_seconds"]
+        retry_detail = (
+            f"; retry after {retry_after_seconds} seconds"
+            if retry_after_seconds is not None
+            else ""
+        )
+        raise HostedAcquisitionError(
+            code,
+            "the Mostly Right cloud did not issue a usable Studio credential" + retry_detail,
+            retry_after_seconds=retry_after_seconds,
+        )
+    try:
+        workspace_id = UUID(value["workspace_id"])
+        principal_id = UUID(value["studio_principal_id"])
+        expires_at = datetime.fromisoformat(value["expires_at"].replace("Z", "+00:00"))
+    except (KeyError, TypeError, ValueError, AttributeError) as error:
+        raise HostedAcquisitionError(
+            "HOSTED_TOKEN_EXCHANGE_INVALID",
+            "the Mostly Right cloud returned an invalid Studio credential response",
+        ) from error
+    token = value["token"]
+    results_bucket = value["crawler_results_bucket"]
+    if (
+        not isinstance(token, str)
+        or not 32 <= len(token) <= 16_384
+        or expires_at.tzinfo is None
+        or expires_at.astimezone(UTC) <= datetime.now(UTC)
+        or (
+            results_bucket is not None
+            and (
+                not isinstance(results_bucket, str)
+                or re.fullmatch(r"[a-z0-9][a-z0-9._-]{1,61}[a-z0-9]", results_bucket) is None
+            )
+        )
+    ):
+        raise HostedAcquisitionError(
+            "HOSTED_TOKEN_EXCHANGE_INVALID",
+            "the Mostly Right cloud returned an invalid Studio credential response",
+        )
+    return StudioToken(
+        base_url=_https_origin(value["studio_base_url"], "Studio base URL"),
+        workspace_id=workspace_id,
+        token=token,
+        expires_at=expires_at.astimezone(UTC),
+        crawler_results_bucket=results_bucket,
+        principal_id=principal_id,
+    )
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+
+def _download_bundle(download: ValidatedResultDownload) -> bytes:
+    """Transfer, bound, and verify one hosted result without holding a second copy of it.
+
+    The transfer used to be a single ``response.read(download.size + 1)``.  That asks the runtime
+    for one contiguous allocation sized by a number Studio supplied -- up to
+    ``MAX_CRAWLER_RESULT_BYTES`` -- before any check has run, and on a chunked response
+    ``http.client`` satisfies it by accumulating every chunk in a list and joining it, so the
+    2.6 GB result that opened issue #204 peaked at roughly twice itself in the interpreter heap
+    with nothing verified yet.  Every check that ran on that buffer is accumulative, so the result
+    is now transferred in ``RESULT_CHUNK_BYTES`` units into a spool while
+    :class:`ResultBytesVerifier` folds each unit into the length and the pinned integrity value.
+
+    The verdict is unchanged in what it accepts.  The same ``size + 1`` transfer bound still
+    detects a longer body, the status and media type still gate, the length is still decided
+    before the integrity value is, and acceptance still requires the exact generation-pinned
+    digest -- through the same code ``verify_result_bytes`` runs.  What changed is when the
+    process has to be able to hold the result: a refused download now never materialises it at
+    all, and an accepted one materialises it once, at the end, from bytes already verified.
+
+    Status and media type are read from the head and refused before the body is transferred
+    rather than after it.  The refusal is the same ``HOSTED_DOWNLOAD_INVALID`` it was; only the
+    quantity of untrusted bytes pulled across before it fires changes, from the whole body to
+    none.
+
+    The spool is a :class:`tempfile.SpooledTemporaryFile`, so a result under
+    ``DOWNLOAD_SPOOL_BYTES`` stays in memory -- the residency claims above are about results
+    larger than that, which is every result the claims matter for -- and a larger one rolls over
+    to a ``tempfile.TemporaryFile``, which is unlinked at creation.  A partial or refused
+    transfer therefore leaves nothing behind on any exit path, including a crash: there is no
+    name for it to be left under.
+
+    What the spill buys is bounded by where it lands.  The staging area is the temporary
+    directory, so that filesystem must have room for one result -- up to
+    ``MAX_CRAWLER_RESULT_BYTES`` -- and a ``TMPDIR`` on a memory-backed filesystem stages in RAM,
+    which keeps the transfer bounded and the refusal cheap but gives back most of the accepted
+    case's saving.  A staging write that cannot complete is refused with its own detail rather
+    than the transport one, because a full disk and a dead connection are different things to be
+    told.
+    """
+
+    opener = build_opener(
+        ProxyHandler({}), HTTPSHandler(context=ssl.create_default_context()), _NoRedirect()
+    )
+    request = Request(download.url, method="GET", headers={"Accept": download.media_type})
+    try:
+        response = opener.open(request, timeout=30.0)
+    except HTTPError as error:
+        response = error
+    except Exception as error:
+        raise HostedAcquisitionError(
+            "HOSTED_DOWNLOAD_FAILED", "the hosted acquisition result could not be downloaded"
+        ) from error
+    # The response is the outermost context deliberately: nothing constructed after the open --
+    # not the verifier, not the spool -- can strand the socket by raising before a `with` that
+    # would have closed it.
+    with response:
+        media_type = response.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
+        status = int(response.status)
+        if status != 200 or media_type != download.media_type:
+            raise HostedAcquisitionError("HOSTED_DOWNLOAD_INVALID", _DOWNLOAD_INVALID_DETAIL)
+        verifier = ResultBytesVerifier(download)
+        with tempfile.SpooledTemporaryFile(max_size=DOWNLOAD_SPOOL_BYTES, mode="w+b") as spool:
+            remaining = download.size + 1
+            while remaining > 0:
+                # Each guard covers one call and no more. A wider one would rewrite the code of
+                # any refusal that later moves inside this loop into the transport code below.
+                try:
+                    chunk = response.read(min(RESULT_CHUNK_BYTES, remaining))
+                except Exception as error:
+                    raise HostedAcquisitionError(
+                        "HOSTED_DOWNLOAD_FAILED",
+                        "the hosted acquisition result could not be downloaded",
+                    ) from error
+                if not chunk:
+                    break
+                try:
+                    spool.write(chunk)
+                except OSError as error:
+                    raise HostedAcquisitionError(
+                        "HOSTED_DOWNLOAD_FAILED",
+                        "the hosted acquisition result could not be staged for verification",
+                    ) from error
+                remaining -= len(chunk)
+                verifier.update(chunk)
+            if verifier.length != download.size:
+                raise HostedAcquisitionError("HOSTED_DOWNLOAD_INVALID", _DOWNLOAD_INVALID_DETAIL)
+            try:
+                verifier.verify()
+            except ResultDownloadError as error:
+                raise HostedAcquisitionError(
+                    "HOSTED_DOWNLOAD_INTEGRITY",
+                    "the hosted acquisition result violated its generation-pinned integrity",
+                ) from error
+            spool.seek(0)
+            return spool.read()
+
+
+class GeneratedStudioExchange:
+    """The generated-client-only Studio HTTP boundary plus signed-result transfer."""
+
+    def __init__(
+        self,
+        token: StudioToken,
+        *,
+        downloader: Callable[[ValidatedResultDownload], bytes] = _download_bundle,
+        clock: Callable[[], float] = time.monotonic,
+        utc_now: Callable[[], datetime] = lambda: datetime.now(UTC),
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.token = token
+        self.downloader = downloader
+        self.clock = clock
+        self.utc_now = utc_now
+        self.sleep = sleep
+        try:
+            ensure_studio_client()
+            client_module = importlib.import_module("mostlyright_studio.client")
+            self.create_endpoint = importlib.import_module(
+                "mostlyright_studio.api.sources.create_public_acquisition"
+            )
+            self.get_endpoint = importlib.import_module(
+                "mostlyright_studio.api.sources.get_public_acquisition"
+            )
+            self.models = importlib.import_module("mostlyright_studio.models")
+            self.client = client_module.AuthenticatedClient(
+                base_url=token.base_url,
+                token=token.token,
+                timeout=30.0,
+                follow_redirects=False,
+            )
+        except StudioBoundaryError as error:
+            raise HostedAcquisitionError(
+                "HOSTED_CLIENT_UNAVAILABLE",
+                "the installed Studio client cannot perform hosted public acquisition",
+            ) from error
+        except (ModuleNotFoundError, AttributeError, TypeError):
+            incompatible = StudioClientIncompatibleError(
+                "generated Studio client lacks hosted public acquisition support"
+            )
+            raise HostedAcquisitionError(
+                "HOSTED_CLIENT_UNAVAILABLE",
+                "the installed Studio client cannot perform hosted public acquisition",
+            ) from incompatible
+
+    def acquire(
+        self,
+        *,
+        workspace_id: UUID,
+        source_id: str,
+        source_authority_digest: str,
+        acquisition_attempt_id: str,
+        query: Mapping[str, Any],
+    ) -> tuple[Mapping[str, Any], bytes]:
+        command_wire = {
+            "schema_version": "3.0.0",
+            "workspace_id": str(workspace_id),
+            "source_id": source_id,
+            "source_authority_digest": source_authority_digest,
+            "query": dict(query),
+        }
+        try:
+            command = self.models.CreateHostedPublicHTTPSAcquisitionCommand.from_dict(command_wire)
+            response = self.create_endpoint.sync_detailed(
+                workspace_id,
+                client=self.client,
+                body=command,
+                idempotency_key=_acquisition_idempotency_key(
+                    workspace_id=workspace_id,
+                    source_authority_digest=source_authority_digest,
+                    acquisition_attempt_id=acquisition_attempt_id,
+                ),
+            )
+        except Exception as error:
+            raise HostedAcquisitionError(
+                "HOSTED_REQUEST_INVALID", "the hosted acquisition request was not admitted"
+            ) from error
+        if int(response.status_code) != 202 or type(response.parsed).__name__ != (
+            "HostedPublicHTTPSAcquisitionSession"
+        ):
+            if type(response.parsed).__name__ in {"StableAPIError", "StudioV3Error"}:
+                error_wire = studio_wire_dict(response.parsed)
+                error_code = error_wire.get("code")
+                retry_after = error_wire.get("retry_after_seconds")
+                if retry_after is None:
+                    header = response.headers.get("Retry-After")
+                    if header is not None and header.isascii() and header.isdecimal():
+                        retry_after = int(header)
+                if (
+                    isinstance(error_code, str)
+                    and error_code
+                    and (
+                        retry_after is None
+                        or (
+                            isinstance(retry_after, int)
+                            and not isinstance(retry_after, bool)
+                            and 1 <= retry_after <= 3_600
+                        )
+                    )
+                ):
+                    retry_detail = (
+                        f"; retry after {retry_after} seconds" if retry_after is not None else ""
+                    )
+                    raise HostedAcquisitionError(
+                        error_code,
+                        "Studio refused the hosted public acquisition request" + retry_detail,
+                        retry_after_seconds=retry_after,
+                    )
+            raise HostedAcquisitionError(
+                "HOSTED_REQUEST_REFUSED", "Studio refused the hosted public acquisition request"
+            )
+        session = studio_wire_dict(response.parsed)
+        _validate_initial_session(
+            session,
+            workspace_id=workspace_id,
+            source_id=source_id,
+            source_authority_digest=source_authority_digest,
+            principal_id=self.token.principal_id,
+            query=query,
+            now=self.utc_now(),
+        )
+        deadline = self.clock() + POLL_TIMEOUT_SECONDS
+        delay = 0.5
+        while session["status"] not in {"result_ready", "failed"}:
+            if self.clock() >= deadline:
+                raise HostedAcquisitionError(
+                    "HOSTED_ACQUISITION_TIMEOUT", "the hosted public acquisition did not finish"
+                )
+            self.sleep(delay)
+            delay = min(delay * 2, 5.0)
+            try:
+                observed = self.get_endpoint.sync_detailed(
+                    workspace_id,
+                    UUID(session["crawler_session_id"]),
+                    client=self.client,
+                )
+            except Exception as error:
+                raise HostedAcquisitionError(
+                    "HOSTED_POLL_UNAVAILABLE",
+                    "the hosted acquisition status could not be checked",
+                ) from error
+            if int(observed.status_code) != 200 or type(observed.parsed).__name__ != (
+                "HostedPublicHTTPSAcquisitionSession"
+            ):
+                raise HostedAcquisitionError(
+                    "HOSTED_POLL_REFUSED", "Studio refused the hosted acquisition status check"
+                )
+            next_session = studio_wire_dict(observed.parsed)
+            for field in (
+                "schema_version",
+                "crawler_session_id",
+                "workspace_id",
+                "requester_principal_id",
+                "source_id",
+                "source_authority_digest",
+                "adapter_id",
+                "adapter_version",
+                "request_id",
+                "request_digest",
+                "egress_policy_attestation",
+                "created_at",
+                "expires_at",
+            ):
+                if next_session[field] != session[field]:
+                    raise HostedAcquisitionError(
+                        "HOSTED_SESSION_BINDING",
+                        "Studio changed an immutable hosted acquisition coordinate",
+                    )
+            session = next_session
+        if session["status"] == "failed":
+            raise HostedAcquisitionError(
+                _failure_code(session.get("failure_code"), "HOSTED_ACQUISITION_FAILED"),
+                "the hosted public acquisition failed inside the isolated Courier",
+            )
+        try:
+            validated_download = validate_result_download(
+                session.get("result_download"),
+                base_url=self.token.base_url,
+                crawler_session_id=session["crawler_session_id"],
+                request_digest=session["request_digest"],
+                source_id=source_id,
+                source_authority_digest=source_authority_digest,
+                now=self.utc_now(),
+                expected_gcs_bucket=self.token.crawler_results_bucket,
+            )
+        except (KeyError, ResultDownloadError) as error:
+            raise HostedAcquisitionError(
+                "HOSTED_DOWNLOAD_BINDING", "Studio returned an unbound result download"
+            ) from error
+        return session, self.downloader(validated_download)
+
+
+def _validate_initial_session(
+    session: Mapping[str, Any],
+    *,
+    workspace_id: UUID,
+    source_id: str,
+    source_authority_digest: str,
+    principal_id: UUID | None,
+    query: Mapping[str, Any],
+    now: datetime,
+) -> None:
+    """Refuse an unbound Studio session before polling or touching its download URL."""
+
+    try:
+        crawler_session_id = UUID(session["crawler_session_id"])
+        requester_principal_id = UUID(session["requester_principal_id"])
+        request_id = UUID(session["request_id"])
+        created = datetime.fromisoformat(session["created_at"].replace("Z", "+00:00"))
+        expires = datetime.fromisoformat(session["expires_at"].replace("Z", "+00:00"))
+    except (KeyError, TypeError, ValueError, AttributeError) as error:
+        raise HostedAcquisitionError(
+            "HOSTED_SESSION_BINDING", "Studio returned an invalid hosted acquisition session"
+        ) from error
+    if (
+        session.get("schema_version") != "mostlyright-public-acquisition-session.v1"
+        or session.get("workspace_id") != str(workspace_id)
+        or session.get("source_id") != source_id
+        or session.get("source_authority_digest") != source_authority_digest
+        or session.get("adapter_id") != "public.https"
+        or session.get("adapter_version") != "1.0.0"
+        or session.get("egress_policy_attestation") != PUBLIC_HTTPS_EGRESS_POLICY_ATTESTATION
+        or str(crawler_session_id) != session.get("crawler_session_id")
+        or str(requester_principal_id) != session.get("requester_principal_id")
+        or principal_id is None
+        or requester_principal_id != principal_id
+        or str(request_id) != session.get("request_id")
+        or not isinstance(session.get("request_digest"), str)
+        or _DIGEST.fullmatch(session["request_digest"]) is None
+        or session.get("status") not in {"enqueue_pending", "enqueued", "result_ready", "failed"}
+        or created.tzinfo is None
+        or expires.tzinfo is None
+        or created.astimezone(UTC) >= expires.astimezone(UTC)
+        or now.astimezone(UTC) >= expires.astimezone(UTC)
+    ):
+        raise HostedAcquisitionError(
+            "HOSTED_SESSION_BINDING", "Studio returned an unbound hosted acquisition session"
+        )
+    try:
+        expected_request = HostedCrawlerRequest(
+            request_id=str(request_id),
+            source_id=source_id,
+            adapter_id="public.https",
+            adapter_version="1.0.0",
+            requested_at=session["created_at"],
+            query=dict(query),
+            egress_policy_attestation=PUBLIC_HTTPS_EGRESS_POLICY_ATTESTATION,
+        )
+    except (HostedCrawlerProtocolError, TypeError, ValueError) as error:
+        raise HostedAcquisitionError(
+            "HOSTED_SESSION_BINDING", "the exact hosted Courier request is invalid"
+        ) from error
+    if expected_request.digest != session["request_digest"]:
+        raise HostedAcquisitionError(
+            "HOSTED_SESSION_BINDING", "Studio changed the exact hosted Courier request"
+        )
+
+
+def acquire_public_https(
+    *,
+    exchange: StudioExchange,
+    workspace_id: UUID,
+    source_id: str,
+    source_authority_digest: str,
+    acquisition_attempt_id: str,
+    query: Mapping[str, Any],
+) -> HostedAcquisition:
+    """Acquire and independently bind the exact Studio session, result, and Reader evidence."""
+
+    try:
+        expected_url = validate_source_locator(
+            query.get("url"), "https_url", "hosted_acquisition.query.url"
+        )
+    except ContractError as error:
+        raise HostedAcquisitionError(
+            "HOSTED_RESULT_BINDING",
+            "the hosted public acquisition locator is not credential-free and canonical",
+        ) from error
+    if urlsplit(expected_url).port is not None:
+        raise HostedAcquisitionError(
+            "HOSTED_RESULT_BINDING",
+            "the hosted public acquisition locator must use implicit HTTPS port 443",
+        )
+
+    session, bundle = exchange.acquire(
+        workspace_id=workspace_id,
+        source_id=source_id,
+        source_authority_digest=source_authority_digest,
+        acquisition_attempt_id=acquisition_attempt_id,
+        query=query,
+    )
+    if (
+        session.get("workspace_id") != str(workspace_id)
+        or session.get("source_id") != source_id
+        or session.get("source_authority_digest") != source_authority_digest
+        or session.get("adapter_id") != "public.https"
+        or session.get("adapter_version") != "1.0.0"
+        or session.get("egress_policy_attestation") != PUBLIC_HTTPS_EGRESS_POLICY_ATTESTATION
+    ):
+        raise HostedAcquisitionError(
+            "HOSTED_SESSION_BINDING", "hosted acquisition session differs from the request"
+        )
+    try:
+        document = parse_foreign_json(bundle)
+        if isinstance(document, dict) and document.get("schema_version") == CRAWLER_FAILURE_SCHEMA:
+            failure = parse_crawler_failure(document)
+            if (
+                failure.request_digest != session.get("request_digest")
+                or failure.source_id != source_id
+                or failure.adapter_id != "public.https"
+                or failure.adapter_version != "1.0.0"
+            ):
+                raise HostedAcquisitionError(
+                    "HOSTED_RESULT_BINDING", "hosted Courier failure differs from its session"
+                )
+            raise HostedAcquisitionError(
+                failure.failure_code,
+                "the hosted public acquisition was safely refused inside the isolated Courier",
+            )
+        result = parse_crawler_result(document)
+    except HostedAcquisitionError:
+        raise
+    except (CanonicalJSONError, HostedCrawlerProtocolError) as error:
+        raise HostedAcquisitionError(
+            "HOSTED_RESULT_INVALID", "hosted Courier result is not a valid bound bundle"
+        ) from error
+    if (
+        result.request_digest != session.get("request_digest")
+        or result.source_id != source_id
+        or result.adapter_id != "public.https"
+        or result.adapter_version != "1.0.0"
+    ):
+        raise HostedAcquisitionError(
+            "HOSTED_RESULT_BINDING", "hosted Courier result differs from its Studio session"
+        )
+    receipt = result.acquisition_receipt
+    reader_value = query.get("reader_pin")
+    pin = None
+    family = None
+    if reader_value is not None and not isinstance(reader_value, Mapping):
+        raise HostedAcquisitionError(
+            "HOSTED_READER_BINDING", "hosted acquisition Reader pin is invalid"
+        )
+    if isinstance(reader_value, Mapping):
+        try:
+            pin = ReaderPin(
+                reader_value["family_id"],
+                reader_value["family_version"],
+                reader_value["decode_options"],
+            )
+        except (KeyError, TypeError, ValueError) as error:
+            raise HostedAcquisitionError(
+                "HOSTED_READER_BINDING", "hosted acquisition Reader pin is invalid"
+            ) from error
+    expected_decode = (
+        (None, None, None)
+        if pin is None
+        else (pin.family_id, pin.family_version, pin.options_digest)
+    )
+    returned_decode = (
+        receipt.get("family_id"),
+        receipt.get("family_version"),
+        receipt.get("decode_options_digest"),
+    )
+    resource_caps = query.get("resource_caps")
+    if pin is None:
+        if resource_caps is not None:
+            raise HostedAcquisitionError(
+                "HOSTED_READER_BINDING", "resource caps require a hosted Reader pin"
+            )
+        expected_resource_caps = None
+        expected_reader_budgets = None
+    else:
+        if resource_caps is not None and not isinstance(resource_caps, Mapping):
+            raise HostedAcquisitionError(
+                "HOSTED_READER_BINDING", "hosted Reader resource caps are invalid"
+            )
+        try:
+            family = TOOLBOX.resolve(pin.family_id, pin.family_version)
+            expected_reader_budgets = asdict(
+                family.default_budgets.narrowed_by(
+                    {
+                        "max_input_bytes": query["limits"]["max_source_bytes"],
+                        "max_output_bytes": query["limits"]["max_normalized_bytes"],
+                        "max_rows": query["limits"]["max_rows"],
+                        "max_columns": query["limits"]["max_columns"],
+                        **({} if resource_caps is None else dict(resource_caps)),
+                    }
+                )
+            )
+        except (KeyError, TypeError, ValueError) as error:
+            raise HostedAcquisitionError(
+                "HOSTED_READER_BINDING", "hosted Reader budgets are invalid"
+            ) from error
+        expected_resource_caps = None if resource_caps is None else dict(resource_caps)
+    try:
+        final_url = validate_source_locator(
+            receipt.get("final_url"), "https_url", "hosted_acquisition.receipt.final_url"
+        )
+        original_parsed = urlsplit(expected_url)
+        final_parsed = urlsplit(final_url)
+        original_host = original_parsed.hostname
+        final_host = final_parsed.hostname
+    except (ContractError, ValueError) as error:
+        raise HostedAcquisitionError(
+            "HOSTED_RESULT_BINDING", "hosted Courier returned an invalid final locator"
+        ) from error
+    limits = query.get("limits")
+    if not isinstance(limits, Mapping):
+        raise HostedAcquisitionError("HOSTED_RESULT_BINDING", "hosted limits are unavailable")
+    data_format = query.get("data_format")
+    filename = query.get("filename")
+    if data_format not in FORMAT_MEDIA_TYPES or not isinstance(filename, str):
+        raise HostedAcquisitionError(
+            "HOSTED_RESULT_BINDING", "hosted output format coordinates are unavailable"
+        )
+    expected_fetched_media_types = (
+        FORMAT_MEDIA_TYPES[data_format]
+        if family is None
+        else frozenset(family.accepted_media_types)
+    )
+    expected_output_format = data_format if family is None else family.output_format
+    normalized_filename = receipt.get("normalized_filename")
+    decode_flags = receipt.get("decode_flags")
+    try:
+        acquired_at = datetime.fromisoformat(receipt.get("acquired_at", "").replace("Z", "+00:00"))
+        session_created_at = datetime.fromisoformat(session["created_at"].replace("Z", "+00:00"))
+    except (KeyError, TypeError, ValueError, AttributeError) as error:
+        raise HostedAcquisitionError(
+            "HOSTED_RESULT_BINDING", "hosted Courier returned an invalid acquisition time"
+        ) from error
+    required_receipt = {
+        "schema_version": "hosted-public-https-acquisition-receipt.v1",
+        "source_id": source_id,
+        "adapter_id": "public.https",
+        "adapter_version": "1.0.0",
+        "request_digest": result.request_digest,
+        "source_url": expected_url,
+        "normalized_content_sha256": sha256_bytes(result.normalized_content),
+        "normalized_size_bytes": len(result.normalized_content),
+        "normalized_data_format": expected_output_format,
+        "egress_policy_attestation": PUBLIC_HTTPS_EGRESS_POLICY_ATTESTATION,
+    }
+    if (
+        set(receipt) != _RECEIPT_FIELDS
+        or any(receipt.get(key) != value for key, value in required_receipt.items())
+        or original_host is None
+        or final_host != original_host
+        or original_parsed.port is not None
+        or final_parsed.port is not None
+        or acquired_at.tzinfo is None
+        or session_created_at.tzinfo is None
+        or acquired_at.astimezone(UTC) != session_created_at.astimezone(UTC)
+        or receipt.get("fetched_media_type") not in expected_fetched_media_types
+        or receipt.get("normalized_media_type") not in FORMAT_MEDIA_TYPES[expected_output_format]
+        or not isinstance(normalized_filename, str)
+        or _BARE_FILENAME.fullmatch(normalized_filename) is None
+        or not any(
+            normalized_filename.endswith(suffix)
+            for suffix in FORMAT_SUFFIXES[expected_output_format]
+        )
+        or (family is None and normalized_filename != filename)
+        or returned_decode != expected_decode
+        or receipt.get("resource_caps") != expected_resource_caps
+        or receipt.get("reader_budgets") != expected_reader_budgets
+        or type(receipt.get("normalized_size_bytes")) is not int
+        or type(receipt.get("raw_size_bytes")) is not int
+        or not 1 <= receipt["raw_size_bytes"] <= limits.get("max_source_bytes", 0)
+        # The normalized decode output is bounded by its own budget, not the fetched-byte
+        # budget, with the same fallback the query composition uses.
+        or not 1
+        <= len(result.normalized_content)
+        <= limits.get("max_normalized_bytes", limits.get("max_source_bytes", 0))
+        or not isinstance(receipt.get("raw_content_sha256"), str)
+        or _DIGEST.fullmatch(receipt["raw_content_sha256"]) is None
+        or not isinstance(receipt.get("transport_evidence_digest"), str)
+        or _DIGEST.fullmatch(receipt["transport_evidence_digest"]) is None
+        or not isinstance(receipt.get("parsed_schema_digest"), str)
+        or _DIGEST.fullmatch(receipt["parsed_schema_digest"]) is None
+        or type(receipt.get("row_count")) is not int
+        or not 1 <= receipt["row_count"] <= limits.get("max_rows", 0)
+        or not isinstance(receipt.get("column_names"), list)
+        or not 1 <= len(receipt["column_names"]) <= limits.get("max_columns", 0)
+        or not all(
+            isinstance(column, str) and 1 <= len(column) <= 255
+            for column in receipt["column_names"]
+        )
+        or receipt.get("clean_room")
+        != {
+            "host_platform": "linux-amd64",
+            "parser_network_syscalls": "denied",
+            "parser_process_creation": "denied",
+            "no_new_privs": True,
+        }
+        or not isinstance(decode_flags, list)
+        or not all(isinstance(flag, str) and flag in DECODE_FLAGS for flag in decode_flags)
+        or decode_flags != sorted(set(decode_flags))
+        or (family is None and decode_flags != [])
+        or (
+            pin is None
+            and (
+                receipt["raw_content_sha256"] != receipt["normalized_content_sha256"]
+                or receipt["raw_size_bytes"] != receipt["normalized_size_bytes"]
+            )
+        )
+    ):
+        raise HostedAcquisitionError(
+            "HOSTED_RESULT_BINDING", "hosted Courier evidence differs from the exact request"
+        )
+    return HostedAcquisition(
+        content=result.normalized_content,
+        source_url=receipt["source_url"],
+        final_url=receipt["final_url"],
+        media_type=receipt["normalized_media_type"],
+        data_format=receipt["normalized_data_format"],
+        raw_content_sha256=receipt["raw_content_sha256"],
+        transport_evidence_digest=receipt["transport_evidence_digest"],
+        parsed_schema_digest=receipt["parsed_schema_digest"],
+        family_id=receipt["family_id"],
+        family_version=receipt["family_version"],
+        decode_options_digest=receipt["decode_options_digest"],
+        decode_flags=tuple(receipt["decode_flags"]),
+        egress_policy_attestation=receipt["egress_policy_attestation"],
+        request_digest=result.request_digest,
+    )
+
+
+def source_authority_digest(source_id: str, query: Mapping[str, Any]) -> str:
+    return sha256_bytes(
+        canonical_json_bytes(
+            {
+                "schema_version": "mr-data-hosted-public-source-authority.v1",
+                "source_id": source_id,
+                "adapter_id": "public.https",
+                "adapter_version": "1.0.0",
+                "query": dict(query),
+            }
+        )
+    )
+
+
+def _acquisition_idempotency_key(
+    *,
+    workspace_id: UUID,
+    source_authority_digest: str,
+    acquisition_attempt_id: str,
+) -> str:
+    """Retry one attempt consistently without replaying an expired prior acquisition."""
+
+    return "mr-data-acquire-" + canonical_sha256(
+        {
+            "schema_version": "hosted-public-acquisition-idempotency.v1",
+            "workspace_id": str(workspace_id),
+            "source_authority_digest": source_authority_digest,
+            "acquisition_attempt_id": acquisition_attempt_id,
+        }
+    )
+
+
+__all__ = [
+    "GeneratedStudioExchange",
+    "HostedAcquisition",
+    "HostedAcquisitionError",
+    "StudioExchange",
+    "StudioToken",
+    "acquire_public_https",
+    "exchange_studio_token",
+    "source_authority_digest",
+]