@agentsdock/server 1.0.7-beta.5

package/server/execution_control.py

@@ -0,0 +1,233 @@
+"""Callback-listener-only controls for the persistent execution owner.
+
+Do not wrap the application exposed over execution IPC with this middleware.
+The private control token is independent of all client/provider credentials.
+Lease admission and persistence remain the execution owner's responsibility.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hmac
+import ipaddress
+import json
+import re
+import uuid
+from typing import Any
+
+
+CONTROL_PREFIX = "/api/admin/execution"
+STATUS_PATH = CONTROL_PREFIX + "/status"
+MAINTENANCE_PATH = CONTROL_PREFIX + "/maintenance"
+MAX_BODY_BYTES = 4096
+MAX_RESPONSE_BYTES = 64 * 1024
+
+
+class ExecutionControlError(RuntimeError):
+    """An expected control refusal raised by an execution-owner callback."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        if type(status_code) is not int or not 400 <= status_code <= 599:
+            raise ValueError("Invalid execution control error status")
+        super().__init__(detail)
+        self.status_code = status_code
+        self.detail = detail
+
+
+def _pairs(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for name, value in pairs:
+        if name in result:
+            raise ExecutionControlError(400, "Duplicate JSON field")
+        result[name] = value
+    return result
+
+
+def _constant(_value: str) -> None:
+    raise ExecutionControlError(400, "Invalid JSON number")
+
+
+def _loopback(scope: dict[str, Any]) -> bool:
+    client = scope.get("client")
+    if not isinstance(client, (tuple, list)) or len(client) != 2:
+        return False
+    try:
+        address = ipaddress.ip_address(client[0])
+    except (ValueError, TypeError):
+        return False
+    if isinstance(address, ipaddress.IPv6Address) and address.ipv4_mapped:
+        address = address.ipv4_mapped
+    return address.is_loopback
+
+
+def _headers(scope: dict[str, Any]) -> list[tuple[bytes, bytes]]:
+    headers = scope.get("headers", [])
+    if not isinstance(headers, (list, tuple)) or len(headers) > 128:
+        raise ExecutionControlError(400, "Invalid control headers")
+    result = []
+    size = 0
+    for item in headers:
+        if (not isinstance(item, (list, tuple)) or len(item) != 2
+                or not all(isinstance(part, bytes) for part in item)):
+            raise ExecutionControlError(400, "Invalid control headers")
+        size += len(item[0]) + len(item[1])
+        if size > 16384:
+            raise ExecutionControlError(400, "Control headers exceed their limit")
+        result.append((item[0].lower(), item[1]))
+    return result
+
+
+def _header_values(headers: list[tuple[bytes, bytes]], name: bytes) -> list[bytes]:
+    return [value for key, value in headers if key == name]
+
+
+def _content_length(headers: list[tuple[bytes, bytes]]) -> int | None:
+    if _header_values(headers, b"transfer-encoding"):
+        raise ExecutionControlError(400, "Control requests do not accept transfer encoding")
+    values = _header_values(headers, b"content-length")
+    if not values:
+        return None
+    if len(values) != 1 or re.fullmatch(rb"0|[1-9][0-9]{0,9}", values[0]) is None:
+        raise ExecutionControlError(400, "Invalid control content length")
+    length = int(values[0])
+    if length > MAX_BODY_BYTES:
+        raise ExecutionControlError(413, "Control request exceeds its size limit")
+    return length
+
+
+async def _body(receive: Any, declared: int | None) -> bytes:
+    async def read() -> bytes:
+        body = bytearray()
+        while True:
+            message = await receive()
+            if message.get("type") != "http.request" or not isinstance(message.get("body", b""), bytes):
+                raise ExecutionControlError(400, "Control request body was interrupted")
+            chunk = message.get("body", b"")
+            if len(chunk) > MAX_BODY_BYTES - len(body):
+                raise ExecutionControlError(413, "Control request exceeds its size limit")
+            body.extend(chunk)
+            if declared is not None and len(body) > declared:
+                raise ExecutionControlError(400, "Control content length does not match its body")
+            more = message.get("more_body", False)
+            if type(more) is not bool:
+                raise ExecutionControlError(400, "Invalid control body framing")
+            if not more:
+                if declared is not None and declared != len(body):
+                    raise ExecutionControlError(400, "Control content length does not match its body")
+                return bytes(body)
+
+    try:
+        return await asyncio.wait_for(read(), timeout=5.0)
+    except asyncio.TimeoutError:
+        raise ExecutionControlError(408, "Control request body timed out") from None
+
+
+class ExecutionControl:
+    """Guard private status/maintenance requests before invoking owner callbacks."""
+
+    def __init__(self, app: Any, *, token: str, worker_instance_id: str,
+                 status_callback: Any, maintenance_callback: Any) -> None:
+        if not isinstance(token, str) or re.fullmatch(r"[0-9a-f]{64}", token) is None:
+            raise ValueError("Invalid execution control token")
+        if (not isinstance(worker_instance_id, str) or not worker_instance_id
+                or len(worker_instance_id) > 128 or not worker_instance_id.isascii()
+                or any(character.isspace() for character in worker_instance_id)):
+            raise ValueError("Invalid worker instance identity")
+        self.app = app
+        self._token = token
+        self.worker_instance_id = worker_instance_id
+        self.status_callback = status_callback
+        self.maintenance_callback = maintenance_callback
+
+    async def _respond(self, send: Any, status: int, value: dict[str, Any]) -> None:
+        try:
+            content = json.dumps(value, allow_nan=False, ensure_ascii=True,
+                                 separators=(",", ":")).encode("ascii")
+            if len(content) > MAX_RESPONSE_BYTES or self._token.encode("ascii") in content:
+                raise ValueError("Invalid private control response")
+        except (ValueError, TypeError, RecursionError):
+            status = 500
+            content = b'{"detail":"Execution control response unavailable"}'
+        await send({"type": "http.response.start", "status": status, "headers": [
+            (b"content-type", b"application/json"), (b"content-length", str(len(content)).encode("ascii")),
+            (b"cache-control", b"no-store"), (b"x-content-type-options", b"nosniff"),
+        ]})
+        await send({"type": "http.response.body", "body": content})
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        path = str(scope.get("path", ""))
+        if not path.startswith(CONTROL_PREFIX):
+            await self.app(scope, receive, send)
+            return
+        if scope.get("type") == "websocket":
+            await send({"type": "websocket.close", "code": 4403, "reason": "Private HTTP control required"})
+            return
+        if scope.get("type") != "http":
+            return
+        try:
+            headers = _headers(scope)
+            forbidden = {b"cookie", b"origin", b"forwarded", b"via", b"x-real-ip",
+                         b"x-agentsdock-token", b"x-zenithdock-token"}
+            if (not _loopback(scope) or scope.get("query_string", b"")
+                    or any(name in forbidden or name.startswith((b"sec-fetch-", b"x-forwarded-", b"tailscale-user-"))
+                           for name, _ in headers)):
+                raise ExecutionControlError(403, "Private control transport is forbidden")
+            authorization = _header_values(headers, b"authorization")
+            expected = b"Bearer " + self._token.encode("ascii")
+            if len(authorization) != 1 or not hmac.compare_digest(authorization[0], expected):
+                raise ExecutionControlError(401, "Execution control authentication required")
+            if path not in {STATUS_PATH, MAINTENANCE_PATH}:
+                raise ExecutionControlError(404, "Unknown execution control")
+            method = scope.get("method")
+            if method != ("GET" if path == STATUS_PATH else "POST"):
+                raise ExecutionControlError(405, "Execution control method is not allowed")
+            length = _content_length(headers)
+            if path == STATUS_PATH:
+                if length not in {None, 0}:
+                    raise ExecutionControlError(400, "Status requests do not accept a body")
+                result = await self.status_callback()
+            else:
+                content_types = _header_values(headers, b"content-type")
+                if (len(content_types) != 1 or content_types[0].lower()
+                        not in {b"application/json", b"application/json; charset=utf-8"}):
+                    raise ExecutionControlError(415, "Execution control requires JSON")
+                raw = await _body(receive, length)
+                try:
+                    value = json.loads(raw.decode("utf-8"), object_pairs_hook=_pairs, parse_constant=_constant)
+                except (ValueError, UnicodeError, RecursionError):
+                    raise ExecutionControlError(400, "Invalid execution control JSON") from None
+                required = {"action", "expected_worker_instance_id", "operation_id"}
+                if not isinstance(value, dict) or not required <= value.keys() or value.keys() - required - {"lease_id", "lifetime_seconds"}:
+                    raise ExecutionControlError(422, "Invalid execution control fields")
+                if value["expected_worker_instance_id"] != self.worker_instance_id:
+                    raise ExecutionControlError(409, "Execution worker instance changed")
+                action = value["action"]
+                if not isinstance(action, str) or action not in {"acquire", "renew", "seal", "release"}:
+                    raise ExecutionControlError(422, "Invalid maintenance action")
+                operation_id = value["operation_id"]
+                try:
+                    if not isinstance(operation_id, str) or str(uuid.UUID(operation_id)) != operation_id:
+                        raise ValueError("noncanonical operation")
+                except (ValueError, AttributeError):
+                    raise ExecutionControlError(422, "Operation ID must be a canonical UUID") from None
+                lease_id = value.get("lease_id")
+                if action == "acquire":
+                    if "lease_id" in value:
+                        raise ExecutionControlError(422, "Acquire must not supply a lease ID")
+                elif (not isinstance(lease_id, str) or not 1 <= len(lease_id) <= 128
+                      or re.fullmatch(r"[A-Za-z0-9_-]+", lease_id) is None):
+                    raise ExecutionControlError(422, "Maintenance requires a valid lease ID")
+                lifetime = value.get("lifetime_seconds", 120)
+                if type(lifetime) is not int or not 30 <= lifetime <= 300:
+                    raise ExecutionControlError(422, "Maintenance lifetime must be 30 to 300 seconds")
+                result = await self.maintenance_callback(action, operation_id, lease_id, lifetime)
+            if not isinstance(result, dict):
+                raise ExecutionControlError(500, "Execution control response unavailable")
+            response_status, response_value = 200, result
+        except ExecutionControlError as exc:
+            response_status, response_value = exc.status_code, {"detail": exc.detail}
+        except Exception:
+            response_status, response_value = 500, {"detail": "Execution control unavailable"}
+        # Response transport loss must not invoke a handler again or attempt a
+        # second response after an already committed lease operation.
+        await self._respond(send, response_status, response_value)

package/server/execution_durability.py

@@ -0,0 +1,184 @@
+"""Flush retained executable generations before an admitted native service stop.
+
+This is a durability barrier, not an alternate integrity or admission proof.
+The caller owns the install lock and supplies an already validated outer journal.
+No bytes, modes, links, configuration or service state are changed here.
+"""
+from __future__ import annotations
+
+import fcntl
+import os
+from pathlib import Path
+import re
+import stat
+import sys
+
+import activation_transaction as activation
+
+MAX_ENTRIES = 250_000
+MAX_BYTES = 16 * 1024 * 1024 * 1024
+
+
+def _identity(info):
+    return (info.st_dev, info.st_ino, info.st_mode, info.st_uid, info.st_size,
+            info.st_mtime_ns, info.st_ctime_ns, info.st_nlink)
+
+
+def _file_barrier(descriptor: int) -> None:
+    os.fsync(descriptor)
+
+
+def _full_barrier(path: Path) -> None:
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    try:
+        if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+            raise RuntimeError("durability anchor is not a regular file")
+        os.fsync(descriptor)
+        if sys.platform == "darwin":
+            # fsync alone need not drain a device's volatile write cache on macOS.
+            fcntl.fcntl(descriptor, getattr(fcntl, "F_FULLFSYNC", 51))
+    finally:
+        os.close(descriptor)
+
+
+def flush_tree(root: Path, *, dependency_prefix: bool = False) -> dict[str, int]:
+    """Flush one owned tree without following directory links or special files."""
+    root = Path(root)
+    if not root.is_absolute() or root.resolve(strict=True) != root:
+        raise ValueError("durability tree must have no linked ancestors")
+    root_info = root.lstat()
+    if (not stat.S_ISDIR(root_info.st_mode) or root_info.st_uid != os.getuid()
+            or root_info.st_mode & 0o022):
+        raise PermissionError("durability tree root is unsafe")
+    total = {"entries": 0, "bytes": 0}
+    external: set[Path] = set()
+    observed = {}
+
+    def visit(directory: Path, parent_fd: int | None = None) -> None:
+        before = directory.lstat()
+        descriptor = os.open(directory if parent_fd is None else directory.name,
+                             os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parent_fd)
+        try:
+            if (_identity(before) != _identity(os.fstat(descriptor))
+                    or before.st_uid != os.getuid() or before.st_dev != root_info.st_dev):
+                raise PermissionError("durability directory ownership or device changed")
+            names = sorted(os.listdir(descriptor))
+            for name in names:
+                if any(ord(character) < 32 for character in name):
+                    raise ValueError("durability member contains control characters")
+                child = directory / name
+                info = os.stat(name, dir_fd=descriptor, follow_symlinks=False)
+                if info.st_uid != os.getuid() or info.st_dev != root_info.st_dev:
+                    raise PermissionError("durability member ownership or device changed")
+                if dependency_prefix and not stat.S_ISLNK(info.st_mode) and info.st_mode & 0o022:
+                    raise PermissionError("standalone Python durability member is writable by others")
+                total["entries"] += 1
+                if total["entries"] > MAX_ENTRIES:
+                    raise ValueError("durability tree exceeds entry limit")
+                if stat.S_ISDIR(info.st_mode):
+                    visit(child, descriptor)
+                elif stat.S_ISREG(info.st_mode):
+                    total["bytes"] += info.st_size
+                    if total["bytes"] > MAX_BYTES:
+                        raise ValueError("durability tree exceeds byte limit")
+                    fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=descriptor)
+                    try:
+                        if _identity(info) != _identity(os.fstat(fd)):
+                            raise RuntimeError("durability file changed before flush")
+                        _file_barrier(fd)
+                        if _identity(info) != _identity(os.fstat(fd)):
+                            raise RuntimeError("durability file changed while flushing")
+                    finally:
+                        os.close(fd)
+                elif stat.S_ISLNK(info.st_mode):
+                    target = os.readlink(name, dir_fd=descriptor)
+                    resolved = child.resolve(strict=True)
+                    if root not in resolved.parents:
+                        relative = child.relative_to(root).parts
+                        if (dependency_prefix or len(relative) != 3 or relative[:2] != (".venv", "bin")
+                                or not re.fullmatch(r"python(?:[0-9]+(?:\.[0-9]+)*)?", relative[2])
+                                or not re.fullmatch(r"python(?:[0-9]+(?:\.[0-9]+)*)?", resolved.name)):
+                            raise ValueError("external durability link is not a Python interpreter")
+                        external.add(resolved)
+                    if target != os.readlink(name, dir_fd=descriptor):
+                        raise RuntimeError("durability link changed while flushing")
+                else:
+                    raise ValueError("durability tree contains a special file")
+                if _identity(info) != _identity(os.stat(name, dir_fd=descriptor, follow_symlinks=False)):
+                    raise RuntimeError("durability member changed while flushing")
+                observed[child] = _identity(info)
+            if names != sorted(os.listdir(descriptor)) or _identity(before) != _identity(directory.lstat()):
+                raise RuntimeError("durability directory changed while flushing")
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+
+    visit(root)
+    for interpreter in sorted(external):
+        info = interpreter.lstat()
+        if (not stat.S_ISREG(info.st_mode) or info.st_uid not in {0, os.getuid()}
+                or info.st_mode & 0o022 or not info.st_mode & 0o111):
+            raise PermissionError("external durability interpreter is unsafe")
+        if info.st_uid == 0:
+            # System interpreters are provisioned outside this updater. Never
+            # traverse /usr or another OS-managed Python installation.
+            continue
+        prefix = interpreter.parent.parent
+        match = re.fullmatch(r"python([0-9]+\.[0-9]+)", interpreter.name)
+        standalone = re.fullmatch(r"cpython-[0-9]+\.[0-9]+\.[0-9]+(?:[a-z0-9.]*)?-(?:macos|linux)-[a-z0-9_]+-[a-z0-9_]+", prefix.name)
+        if standalone:
+            if (interpreter.parent.name != "bin" or match is None
+                    or not (prefix / "lib" / ("python" + match[1])).is_dir()
+                    or not (prefix / "BUILD").is_file() or (prefix / "BUILD").is_symlink()):
+                raise ValueError("owned uv Python has no bounded standalone runtime")
+            flush_tree(prefix, dependency_prefix=True)
+            parent_fd = os.open(prefix.parent, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+            try:
+                os.fsync(parent_fd)
+            finally:
+                os.close(parent_fd)
+        # Other selected interpreters (for example Homebrew) are preexisting
+        # prerequisites. Do not infer and recursively scan an arbitrary prefix.
+        _full_barrier(interpreter)
+        if _identity(info) != _identity(interpreter.lstat()):
+            raise RuntimeError("external durability interpreter changed")
+    for path, identity in observed.items():
+        if _identity(path.lstat()) != identity:
+            raise RuntimeError("durability tree changed after flush")
+    if _identity(root.lstat()) != _identity(root_info):
+        raise RuntimeError("durability root changed after flush")
+    return total
+
+
+def flush_activation(root: Path, value: dict) -> None:
+    root_info = root.lstat()
+    if (not stat.S_ISDIR(root_info.st_mode) or root_info.st_uid != os.getuid()
+            or stat.S_IMODE(root_info.st_mode) != 0o700):
+        raise PermissionError("activation durability requires a private install root")
+    if value.get("phase") not in {"prepared", "guarded"}:
+        raise RuntimeError("runtime durability must precede native quiescing")
+    releases = [value["candidate_release"], value["old_release"], value["execution"]["old_worker_release"]]
+    seen: set[Path] = set()
+    for release in releases:
+        if not release:
+            continue
+        path = activation._locate_release(release)
+        if path is None:
+            raise RuntimeError("durability runtime is not retained by the journal")
+        if path in seen:
+            continue
+        seen.add(path)
+        flush_tree(path)
+        descriptor = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+        try:
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+        _full_barrier(path / "VERSION")
+        if not activation._release_matches(path, release):
+            raise RuntimeError("durability runtime identity changed")
+    descriptor = os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)

package/server/execution_http.py

@@ -0,0 +1,256 @@
+"""Credential HTTP transport pinned to the connected native process.
+
+The Linux /proc and Darwin lsof tuple checks are shared in design with
+install.sh:pinned_managed_http_get. No HTTP bytes, including credentials, leave
+the connected socket before process ownership and caller authority are proven.
+"""
+from __future__ import annotations
+
+import ipaddress
+import json
+import os
+from pathlib import Path
+import socket
+import subprocess
+import time
+from typing import Callable
+from urllib.parse import urlsplit
+
+MAXIMUM_HEADERS = 64 * 1024
+
+
+def address_from_proc(raw, ipv6):
+    packed = bytes.fromhex(raw)
+    if not ipv6:
+        packed = packed[::-1]
+    else:
+        packed = b"".join(
+            packed[offset : offset + 4][::-1]
+            for offset in range(0, 16, 4)
+        )
+    return ipaddress.ip_address(packed)
+
+
+def linux_connection_owned(pid, server, client):
+    inodes = set()
+    try:
+        entries = (Path("/proc") / str(pid) / "fd").iterdir()
+        for entry in entries:
+            try:
+                target = os.readlink(entry)
+            except OSError:
+                continue
+            if target.startswith("socket:[") and target.endswith("]"):
+                inodes.add(target[8:-1])
+    except OSError:
+        return False
+    if not inodes:
+        return False
+    expected_server = (ipaddress.ip_address(server[0]), int(server[1]))
+    expected_client = (ipaddress.ip_address(client[0]), int(client[1]))
+    for table, ipv6 in ((Path("/proc/net/tcp"), False), (Path("/proc/net/tcp6"), True)):
+        try:
+            lines = table.read_text(encoding="ascii").splitlines()[1:]
+        except OSError:
+            continue
+        for line in lines:
+            fields = line.split()
+            if len(fields) < 10 or fields[3] != "01" or fields[9] not in inodes:
+                continue
+            try:
+                local_address, local_port = fields[1].rsplit(":", 1)
+                remote_address, remote_port = fields[2].rsplit(":", 1)
+                observed_server = (
+                    address_from_proc(local_address, ipv6),
+                    int(local_port, 16),
+                )
+                observed_client = (
+                    address_from_proc(remote_address, ipv6),
+                    int(remote_port, 16),
+                )
+            except (IndexError, ValueError):
+                continue
+            if observed_server == expected_server and observed_client == expected_client:
+                return True
+    return False
+
+
+def parse_lsof_endpoint(value):
+    value = value.strip().split(None, 1)[0]
+    if value.startswith("["):
+        closing = value.find("]:")
+        if closing < 0:
+            raise ValueError
+        host = value[1:closing]
+        port = value[closing + 2 :]
+    else:
+        host, port = value.rsplit(":", 1)
+    return ipaddress.ip_address(host), int(port)
+
+
+def darwin_connection_owned(pid, server, client, timeout):
+    try:
+        result = subprocess.run(
+            [
+                "/usr/sbin/lsof",
+                "-nP",
+                "-a",
+                "-p",
+                str(pid),
+                "-iTCP",
+                "-sTCP:ESTABLISHED",
+                "-Fn",
+            ],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            timeout=max(0.05, timeout),
+            check=False,
+            env={"PATH": "/usr/bin:/bin:/usr/sbin:/sbin", "LC_ALL": "C"},
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    if result.returncode != 0:
+        return False
+    expected_server = (ipaddress.ip_address(server[0]), int(server[1]))
+    expected_client = (ipaddress.ip_address(client[0]), int(client[1]))
+    for raw_line in result.stdout.decode("ascii", "strict").splitlines():
+        if not raw_line.startswith("n") or "->" not in raw_line:
+            continue
+        try:
+            local, remote = raw_line[1:].split("->", 1)
+            if (
+                parse_lsof_endpoint(local) == expected_server
+                and parse_lsof_endpoint(remote) == expected_client
+            ):
+                return True
+        except (UnicodeError, ValueError):
+            continue
+    return False
+
+
+def receive_response(connection, deadline, maximum_body):
+    payload = bytearray()
+    header_end = -1
+    while header_end < 0:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise RuntimeError("pinned HTTP response is invalid")
+        connection.settimeout(remaining)
+        chunk = connection.recv(min(64 * 1024, MAXIMUM_HEADERS + 4 - len(payload)))
+        if not chunk:
+            raise RuntimeError("pinned HTTP response is invalid")
+        payload.extend(chunk)
+        header_end = payload.find(b"\r\n\r\n")
+        if header_end > MAXIMUM_HEADERS or (header_end < 0 and len(payload) > MAXIMUM_HEADERS):
+            raise RuntimeError("pinned HTTP response is invalid")
+    raw_headers = bytes(payload[:header_end])
+    body = bytearray(payload[header_end + 4 :])
+    try:
+        lines = raw_headers.decode("latin-1").split("\r\n")
+    except UnicodeError:
+        raise RuntimeError("pinned HTTP response is invalid")
+    status_parts = lines[0].split(" ", 2) if lines else []
+    if (
+        len(status_parts) < 2
+        or status_parts[0] not in ("HTTP/1.0", "HTTP/1.1")
+        or status_parts[1] != "200"
+    ):
+        raise RuntimeError("pinned HTTP response is invalid")
+    headers = {}
+    for line in lines[1:]:
+        if not line or line[:1] in " \t" or ":" not in line:
+            raise RuntimeError("pinned HTTP response is invalid")
+        name, value = line.split(":", 1)
+        name = name.strip().lower()
+        value = value.strip()
+        if not name or name in headers:
+            raise RuntimeError("pinned HTTP response is invalid")
+        headers[name] = value
+    if "transfer-encoding" in headers:
+        raise RuntimeError("pinned HTTP response is invalid")
+    content_length = None
+    if "content-length" in headers:
+        try:
+            content_length = int(headers["content-length"], 10)
+        except ValueError:
+            raise RuntimeError("pinned HTTP response is invalid")
+        if content_length < 0 or content_length > maximum_body:
+            raise RuntimeError("pinned HTTP response is invalid")
+    if len(body) > maximum_body or (
+        content_length is not None and len(body) > content_length
+    ):
+        raise RuntimeError("pinned HTTP response is invalid")
+    while content_length is None or len(body) < content_length:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise RuntimeError("pinned HTTP response is invalid")
+        connection.settimeout(remaining)
+        chunk = connection.recv(min(64 * 1024, maximum_body + 1 - len(body)))
+        if not chunk:
+            break
+        body.extend(chunk)
+        if len(body) > maximum_body:
+            raise RuntimeError("pinned HTTP response is invalid")
+    if content_length is not None and len(body) != content_length:
+        raise RuntimeError("pinned HTTP response is invalid")
+    return bytes(body)
+
+
+def request_json(url: str, token: str, *, expected_pid: int, platform: str,
+                 verify_owner: Callable[[], None], body: dict | None = None,
+                 timeout: float = 5.0, maximum_body: int = 1024 * 1024) -> dict:
+    """Connect once, prove the exact peer PID, then send one GET or POST."""
+    if type(expected_pid) is not int or expected_pid <= 1 or platform not in {"Linux", "Darwin"}:
+        raise ValueError("pinned HTTP process identity is invalid")
+    parsed = urlsplit(url)
+    if (parsed.scheme != "http" or not parsed.hostname or not parsed.port
+            or parsed.username or parsed.password or parsed.fragment):
+        raise ValueError("pinned HTTP requires an exact local IP endpoint")
+    # Numeric addresses avoid DNS or proxy rewriting the admitted endpoint.
+    ipaddress.ip_address(parsed.hostname)
+    path = parsed.path or "/"
+    if parsed.query:
+        path += "?" + parsed.query
+    if any(ord(char) < 33 or ord(char) > 126 for char in path):
+        raise ValueError("pinned HTTP path is invalid")
+    if (not isinstance(token, str) or not 1 <= len(token) <= 4096
+            or any(ord(char) < 33 or ord(char) > 126 for char in token)):
+        raise ValueError("pinned HTTP credential format is invalid")
+    if not 0 < timeout <= 60 or not 0 < maximum_body <= 16 * 1024 * 1024:
+        raise ValueError("pinned HTTP bounds are invalid")
+    payload = b"" if body is None else json.dumps(body, separators=(",", ":"), allow_nan=False).encode()
+    if len(payload) > maximum_body:
+        raise ValueError("pinned HTTP request exceeds limit")
+    deadline = time.monotonic() + timeout
+    with socket.create_connection((parsed.hostname, parsed.port), timeout=timeout) as connection:
+        server, client = connection.getpeername()[:2], connection.getsockname()[:2]
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise RuntimeError("pinned HTTP connection ownership could not be proven")
+            owned = (linux_connection_owned(expected_pid, server, client) if platform == "Linux" else
+                     darwin_connection_owned(expected_pid, server, client, remaining))
+            if owned:
+                break
+            time.sleep(min(0.01, max(0.0, deadline - time.monotonic())))
+        # A valid socket belonging to a stale epoch is still not the admitted
+        # native role. Recheck its service manager and owned receipt now.
+        verify_owner()
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise RuntimeError("pinned HTTP ownership verification timed out")
+        host = parsed.hostname
+        host_header = f"[{host}]:{parsed.port}" if ":" in host else f"{host}:{parsed.port}"
+        headers = (("POST" if body is not None else "GET") + " " + path + " HTTP/1.1\r\n"
+                   + "Host: " + host_header + "\r\nAuthorization: Bearer " + token
+                   + "\r\nAccept: application/json\r\nConnection: close\r\n")
+        if body is not None:
+            headers += "Content-Type: application/json\r\nContent-Length: " + str(len(payload)) + "\r\n"
+        connection.settimeout(remaining)
+        connection.sendall(headers.encode("ascii") + b"\r\n" + payload)
+        response = receive_response(connection, deadline, maximum_body)
+    result = json.loads(response)
+    if not isinstance(result, dict):
+        raise RuntimeError("pinned HTTP returned an invalid object")
+    return result