agentic-runner 2.6.0__py3-none-any.whl

agentic_runner/credentials.py

@@ -0,0 +1,252 @@
+"""Credential References on the Runner (PRD issue 48; map 22 A1-A2, 25 §11, 17 A4/A10).
+
+The **norm**, and the thing this module is mostly about: the Contract's credential
+manifest names each credential -- name, type, scope -- and the control plane holds those
+names and nothing else. The value is installed by whoever hosts the Runner, in their own
+store: a Kubernetes Secret mounted ``0400`` (issue 46) or the workstation store (issue
+47), under the reference's name. Endpoints are plain Profile config and are not secrets,
+so they are nowhere near here.
+
+Release 1's default for a **cross-party** value is hand-over (22 A2): the funder gives it
+to the host operator out of band, who installs it as any other reference. That is a
+legitimate answer, not a gap -- :mod:`agentic_runner.sealed_box` is the exception path for
+a funder who does not host, and its opened values land in the same resolver below, under
+the same reference name, precisely so nothing downstream can tell the two apart.
+
+Two rules, and the second is the reason this is a module rather than a dictionary:
+
+* **The manifest bounds what a Contract may resolve.** 17 asks how one Contract is kept
+  off another's credentials on a shared Runner; the structural answer is that resolution
+  is a lookup in the Contract's own manifest first and the host store second, so a
+  reference the Contract never declared is unresolvable however the host store is laid
+  out. An unknown reference fails the Directive **closed**, with Evidence naming it.
+* **Values reach verb seams and Runner-hosted MCP servers only** (17 A10). Never the
+  Agent Runtime's environment -- that process is the one on the box that must hold no
+  org credential (ADR-0011 §9) -- and never a hook, which is repository-adjacent code the
+  Agent itself can influence. :class:`DirectiveCredentials` has two accessors and both
+  are named after the one place they may be spent; there is deliberately no ``env()``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final, Protocol
+from uuid import UUID
+
+__all__ = [
+    "CREDENTIAL_RESOLVED_SOURCE",
+    "CREDENTIAL_UNRESOLVABLE_SOURCE",
+    "CredentialResolver",
+    "DirectiveCredentials",
+    "DirectoryCredentialStore",
+    "EmptyCredentialStore",
+    "FakeCredentialStore",
+    "HostCredentialStore",
+    "UnresolvableCredentialReferenceError",
+]
+
+# The Evidence a Directive that failed closed on a reference appends (ids and the
+# reference *name*, never a value and never a digest of one).
+CREDENTIAL_UNRESOLVABLE_SOURCE: Final[str] = "runner.credential_unresolvable"
+# The Evidence a Directive appends when its references resolved. Names only.
+CREDENTIAL_RESOLVED_SOURCE: Final[str] = "runner.credential_resolved"
+
+
+class HostCredentialStore(Protocol):
+    """Where the host operator installed the values. The Runner reads; it never writes."""
+
+    def get(self, reference: str) -> str | None: ...
+
+
+class DirectoryCredentialStore:
+    """A mounted Secret or a workstation store: one file per Credential Reference.
+
+    The Kubernetes shape (issue 46) and the workstation shape (issue 47) are the same
+    shape -- a directory of ``0400`` files named after the reference -- so one reader
+    serves both and neither installer has to teach the Runner a format.
+
+    A reference is a single path segment (:meth:`_path` refuses anything else) because a
+    manifest is operator-authored data and a Contract must not be able to name
+    ``../another-contract/key``.
+    """
+
+    def __init__(self, root: Path) -> None:
+        self._root = root
+
+    def get(self, reference: str) -> str | None:
+        path = self._path(reference)
+        if path is None or not path.is_file():
+            return None
+        # A Secret written by `kubectl create secret --from-literal` and one written by
+        # an editor differ by exactly one trailing newline; stripping it is the
+        # difference between a working key and a 401 nobody can explain.
+        return path.read_text(encoding="utf-8").strip()
+
+    def _path(self, reference: str) -> Path | None:
+        if not reference or "/" in reference or reference in {".", ".."}:
+            return None
+        return self._root / reference
+
+
+class FakeCredentialStore:
+    """The host store a test wires (``integrations/*/fake_*`` keep the same shape)."""
+
+    def __init__(self, values: Mapping[str, str] | None = None) -> None:
+        self._values = dict(values or {})
+
+    def get(self, reference: str) -> str | None:
+        return self._values.get(reference)
+
+    def put(self, reference: str, value: str) -> None:
+        self._values[reference] = value
+
+
+class EmptyCredentialStore:
+    """The store a Runner with none configured behaves as: everything is uninstalled.
+
+    Not a null object for convenience -- it is the fail-closed reading. A Contract that
+    declares a manifest and lands on a Runner with no host store gets a refused Directive
+    naming the reference, instead of one that ran without the credential it was told to use.
+    """
+
+    def get(self, reference: str) -> str | None:
+        return None
+
+
+class UnresolvableCredentialReferenceError(RuntimeError):
+    """A Directive named a Credential Reference it cannot have (22 A1's fail-closed half).
+
+    ``reason`` is ``not_in_manifest`` (the Contract never declared it) or
+    ``not_installed`` (declared, but the host has not put a value there yet, and no
+    funder has sealed one). Both fail the Directive; they differ in who fixes it, which
+    is why the Evidence carries the distinction.
+    """
+
+    def __init__(self, reference: str, *, contract_id: str | None, reason: str) -> None:
+        super().__init__(
+            f"Credential Reference {reference!r} is unresolvable for Contract "
+            f"{contract_id or 'unknown'}: {reason}"
+        )
+        self.reference = reference
+        self.contract_id = contract_id
+        self.reason = reason
+
+    def evidence(self) -> dict[str, object]:
+        """The Evidence payload naming the reference -- the whole point of failing here."""
+
+        return {
+            "event": "credential_reference.unresolvable",
+            "reference": self.reference,
+            "contract_id": self.contract_id,
+            "reason": self.reason,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class DirectiveCredentials:
+    """The values one Directive may spend, resolved once at its start (22 A1).
+
+    Held for the life of the attempt and no longer. Both accessors are named after the
+    only two consumers 17 A10 admits; there is no accessor that yields an environment
+    mapping, because the two processes that take one -- the Agent Runtime subprocess and
+    a Runner Hook -- are exactly the two that must never see a value.
+    """
+
+    contract_id: str | None
+    _values: Mapping[str, str]
+
+    def for_verb_seam(self, reference: str) -> str:
+        """The value a privileged verb seam spends (push, PR, review, merge)."""
+
+        return self._require(reference)
+
+    def for_runner_hosted_server(self, reference: str) -> str:
+        """The value a Runner-hosted MCP server is started with (issue 58)."""
+
+        return self._require(reference)
+
+    def references(self) -> tuple[str, ...]:
+        """The reference *names* resolved, for Evidence and for a server's config."""
+
+        return tuple(sorted(self._values))
+
+    def runner_hosted_server_env(self, references: Iterable[str]) -> dict[str, str]:
+        """The environment one Runner-hosted MCP server is started with (issue 58).
+
+        A *subset*, named by the server's own registry entry: a server declaring one
+        reference is handed that one, not the Contract's whole manifest. The Agent talks
+        to the server over the Runner's socket and never holds what the server holds,
+        which is the arrangement 17 A10 admits.
+        """
+
+        return {reference: self.for_runner_hosted_server(reference) for reference in references}
+
+    def _require(self, reference: str) -> str:
+        value = self._values.get(reference)
+        if value is None:
+            raise UnresolvableCredentialReferenceError(
+                reference, contract_id=self.contract_id, reason="not_in_manifest"
+            )
+        return value
+
+
+class CredentialResolver:
+    """Resolves a Contract's manifest into values, at Directive time (22 A1, 25 §11).
+
+    Per Directive rather than per process, for the same reason the LLM slot is read per
+    request (22 A8): a value the host replaced or a funder re-delivered takes effect at
+    the next Directive rather than at the next Runner restart.
+
+    ``delivered`` is the sealed half's output -- ``{(contract_id, slot): plaintext}``,
+    opened by :class:`agentic_runner.sealed_box.RecipientKeyStore`'s private key and held
+    in memory only. It is consulted before the host store because a funder who delivered a
+    value is stating it is theirs to state; the host's own install is the fallback, which
+    is exactly the hand-over default.
+    """
+
+    def __init__(
+        self,
+        *,
+        store: HostCredentialStore,
+        delivered: Mapping[tuple[str, str], str] | None = None,
+    ) -> None:
+        self._store = store
+        self._delivered = dict(delivered or {})
+
+    @property
+    def host_store(self) -> HostCredentialStore:
+        """The host's own store, for the one reader that is not a Directive: a
+        user-connected Source's connector (PRD issue 50), whose Source row -- not a
+        Contract manifest -- names the reference, and whose value is its owner's own."""
+
+        return self._store
+
+    def deliver(self, contract_id: UUID | str, slot: str, value: str) -> None:
+        self._delivered[(str(contract_id), slot)] = value
+
+    def drop(self, contract_id: UUID | str, slot: str) -> None:
+        """Termination and revocation (22 A9): the value goes, it is not listed."""
+
+        self._delivered.pop((str(contract_id), slot), None)
+
+    def resolve(self, *, contract_id: str | None, manifest: Iterable[str]) -> DirectiveCredentials:
+        """Every reference the Contract declares, or the first failure, named.
+
+        Fails on the *first* unresolvable reference rather than collecting them: a
+        Directive that cannot have one of its credentials is not going to run, and a
+        partial resolution left lying around is a value held for no reason.
+        """
+
+        values: dict[str, str] = {}
+        for reference in manifest:
+            value = self._delivered.get((str(contract_id), reference))
+            if value is None:
+                value = self._store.get(reference)
+            if value is None:
+                raise UnresolvableCredentialReferenceError(
+                    reference, contract_id=contract_id, reason="not_installed"
+                )
+            values[reference] = value
+        return DirectiveCredentials(contract_id=contract_id, _values=values)

agentic_runner/device_login_activities.py

@@ -0,0 +1,79 @@
+"""The Runner's activities behind the Contract device-login workflows (PRD issue 31).
+
+Dispatched to ``runner.{runner_id}`` (the locality rule, ADR-0013 §2): the only place a
+Contract's harness root lives is the Runner's own disk (ADR-0015 §4), so they ship with
+the Runner distribution and the platform's workflow module only names them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import UTC, datetime
+
+from temporalio import activity
+
+from agentic_runner.workers.contract_device_login import ContractDeviceLogin
+from agentic_runner.workers.contract_isolation import ContractIsolation
+from agentic_runner_contracts.activity_io import (
+    ContractDeviceLoginInput,
+    ContractDeviceLoginResult,
+    ContractDeviceLoginStatusInput,
+    ContractDeviceLoginStatusResult,
+)
+
+
+class ContractDeviceLoginActivities:
+    """Temporal activities for one Contract's device-code sign-in: start it, and
+    separately check whether the funder has finished it."""
+
+    def __init__(
+        self,
+        *,
+        contract_isolation: ContractIsolation,
+        device_login: ContractDeviceLogin | None = None,
+    ) -> None:
+        self._contract_isolation = contract_isolation
+        # Injectable for tests; None falls through to the real `codex` subprocess.
+        self._device_login = device_login or ContractDeviceLogin(contract_isolation)
+
+    def activity_callables(self) -> list[Callable[..., object]]:
+        return [
+            self.sign_in_contract_device_login,
+            self.check_contract_device_login_status,
+        ]
+
+    @activity.defn(name="sign_in_contract_device_login")
+    async def sign_in_contract_device_login(
+        self, request: ContractDeviceLoginInput
+    ) -> ContractDeviceLoginResult:
+        prompt = await self._device_login.sign_in(
+            request.contract_id, runtime_kind=request.runtime_kind
+        )
+        return ContractDeviceLoginResult(
+            contract_id=prompt.contract_id,
+            runtime_kind=prompt.runtime_kind,
+            verification_uri=prompt.verification_uri,
+            user_code=prompt.user_code,
+            expires_at=prompt.expires_at.isoformat(),
+        )
+
+    @activity.defn(name="check_contract_device_login_status")
+    async def check_contract_device_login_status(
+        self, request: ContractDeviceLoginStatusInput
+    ) -> ContractDeviceLoginStatusResult:
+        present = self._device_login.token_present(
+            request.contract_id, runtime_kind=request.runtime_kind
+        )
+        delivered_at = None
+        if present:
+            mtime = self._device_login.token_delivered_at(
+                request.contract_id, runtime_kind=request.runtime_kind
+            )
+            if mtime is not None:
+                delivered_at = datetime.fromtimestamp(mtime, tz=UTC).isoformat()
+        return ContractDeviceLoginStatusResult(
+            contract_id=request.contract_id,
+            runtime_kind=request.runtime_kind,
+            token_present=present,
+            delivered_at=delivered_at,
+        )

agentic_runner/egress.py

@@ -0,0 +1,243 @@
+"""Scoped egress for one Directive (PRD issue 58, map 06 §4, ticket 05's open item).
+
+``CODEX_NETWORK_ACCESS`` was all-or-nothing: a Directive either reached the whole internet
+or nothing, and a VPC-only Streamable HTTP MCP server needs neither. The Agent Runtime
+Profile's ``network_policy`` now names the destinations a Directive may reach; the Runner
+adds the ones it knows the Directive needs (the git remote, each granted HTTP MCP
+server), and this forward proxy on loopback is where the list is enforced: every
+Directive under a Profile allow-list is handed ``HTTPS_PROXY`` / ``HTTP_PROXY`` /
+``ALL_PROXY`` naming it, with the attempt's bearer as the proxy credential so another
+Contract's uid on the same loopback cannot borrow this attempt's list.
+
+What this is *not* is a kernel boundary. A process that ignores the proxy variables and
+opens a raw socket is stopped only by what the host adds underneath (a pod
+NetworkPolicy); a workstation adds nothing, which is why it reports its posture as
+``unenforced`` in the heartbeat rather than claiming the list binds.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import contextlib
+import hmac
+from collections.abc import Awaitable, Callable, Iterable
+from fnmatch import fnmatchcase
+from types import TracebackType
+from typing import Final
+from urllib.parse import urlsplit
+
+from agentic_runner.tiny_http import HttpRequest, read_request, response_head
+
+__all__ = [
+    "EGRESS_ENV_NAMES",
+    "EGRESS_REFUSED_SOURCE",
+    "EgressProxy",
+    "Resolver",
+    "destination_allowed",
+    "host_of",
+]
+
+EGRESS_REFUSED_SOURCE: Final[str] = "runner.egress_refused"
+
+# Both spellings: curl and git read the lower-case ones, most language runtimes the
+# upper. Reserved on a Directive's environment so a hook cannot point the Agent round it.
+EGRESS_ENV_NAMES: Final[frozenset[str]] = frozenset(
+    {
+        "HTTPS_PROXY",
+        "HTTP_PROXY",
+        "ALL_PROXY",
+        "NO_PROXY",
+        "https_proxy",
+        "http_proxy",
+        "all_proxy",
+        "no_proxy",
+    }
+)
+
+# Loopback is the LLM proxy, the callback socket's neighbours and every Runner-hosted MCP
+# server: all the Runner's own, none of it egress.
+_LOOPBACK: Final[str] = "127.0.0.1,localhost,::1"
+_PROXY_USER: Final[str] = "agentic"
+_PIPE_CHUNK: Final[int] = 65536
+
+Resolver = Callable[[str, int], Awaitable[tuple[str, int]]]
+
+
+async def _system_resolver(host: str, port: int) -> tuple[str, int]:
+    infos = await asyncio.get_running_loop().getaddrinfo(host, port, type=0)
+    address = infos[0][4]
+    return str(address[0]), int(address[1])
+
+
+def destination_allowed(allow_list: Iterable[str], host: str, port: int) -> bool:
+    """``host``, ``host:port`` or a ``*.domain`` pattern; a bare host admits any port."""
+
+    host = host.lower().strip("[]")
+    for entry in allow_list:
+        pattern, _, entry_port = entry.lower().partition(":")
+        if entry_port and entry_port != str(port):
+            continue
+        if fnmatchcase(host, pattern):
+            return True
+    return False
+
+
+def host_of(url: str) -> str | None:
+    """The allow-list entry a URL needs: its host, with the port when it names one."""
+
+    parts = urlsplit(url)
+    if not parts.hostname:
+        return None
+    return parts.hostname if parts.port is None else f"{parts.hostname}:{parts.port}"
+
+
+class EgressProxy:
+    """One attempt's forward proxy: CONNECT for TLS, absolute-form for plain HTTP."""
+
+    def __init__(
+        self,
+        allow_list: Iterable[str],
+        *,
+        token: str,
+        resolver: Resolver | None = None,
+        on_refused: Callable[[str, int], Awaitable[None]] | None = None,
+        host: str = "127.0.0.1",
+    ) -> None:
+        self.allow_list = tuple(dict.fromkeys(allow_list))
+        self._token = token
+        self._resolver = resolver or _system_resolver
+        self._on_refused = on_refused
+        self._host = host
+        self._server: asyncio.Server | None = None
+        self._port = 0
+
+    async def __aenter__(self) -> EgressProxy:
+        self._server = await asyncio.start_server(self._serve, host=self._host, port=0)
+        self._port = int(self._server.sockets[0].getsockname()[1])
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if self._server is not None:
+            self._server.close()
+            with contextlib.suppress(Exception):
+                await self._server.wait_closed()
+
+    def env(self) -> dict[str, str]:
+        url = f"http://{_PROXY_USER}:{self._token}@{self._host}:{self._port}"
+        env = {name: url for name in EGRESS_ENV_NAMES if "no_proxy" not in name.lower()}
+        env.update({"NO_PROXY": _LOOPBACK, "no_proxy": _LOOPBACK})
+        return env
+
+    async def _serve(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            request = await read_request(reader)
+            if isinstance(request, tuple):
+                await self._reply(writer, request[0])
+                return
+            if not self._authorized(request):
+                await self._reply(writer, 407)
+                return
+            destination = _destination(request)
+            if destination is None:
+                await self._reply(writer, 400)
+                return
+            host, port = destination
+            if not destination_allowed(self.allow_list, host, port):
+                if self._on_refused is not None:
+                    await self._on_refused(host, port)
+                await self._reply(writer, 403)
+                return
+            try:
+                address, resolved_port = await self._resolver(host, port)
+                upstream_reader, upstream_writer = await asyncio.open_connection(
+                    address, resolved_port
+                )
+            except OSError:
+                await self._reply(writer, 502)
+                return
+            if request.method == "CONNECT":
+                writer.write(b"HTTP/1.1 200 Connection Established\r\n\r\n")
+                await writer.drain()
+            else:
+                upstream_writer.write(_origin_form(request))
+                await upstream_writer.drain()
+            await _pipe_both(reader, writer, upstream_reader, upstream_writer)
+        finally:
+            writer.close()
+            with contextlib.suppress(Exception):
+                await writer.wait_closed()
+
+    def _authorized(self, request: HttpRequest) -> bool:
+        scheme, _, encoded = request.headers.get("proxy-authorization", "").partition(" ")
+        if scheme.lower() != "basic":
+            return False
+        try:
+            _, _, offered = base64.b64decode(encoded.strip()).decode().partition(":")
+        except (ValueError, UnicodeDecodeError):
+            return False
+        return hmac.compare_digest(offered, self._token)
+
+    @staticmethod
+    async def _reply(writer: asyncio.StreamWriter, status: int) -> None:
+        head = response_head(status, content_type="text/plain", content_length=0)
+        if status == 407:
+            head = head.replace(
+                b"\r\n\r\n", b'\r\nProxy-Authenticate: Basic realm="agentic-runner"\r\n\r\n', 1
+            )
+        writer.write(head)
+        with contextlib.suppress(ConnectionError):
+            await writer.drain()
+
+
+def _destination(request: HttpRequest) -> tuple[str, int] | None:
+    if request.method == "CONNECT":
+        host, _, port = request.target.rpartition(":")
+        return (host, int(port)) if host and port.isdigit() else None
+    parts = urlsplit(request.target)
+    if parts.scheme != "http" or not parts.hostname:
+        return None
+    return parts.hostname, parts.port or 80
+
+
+def _origin_form(request: HttpRequest) -> bytes:
+    parts = urlsplit(request.target)
+    path = (parts.path or "/") + (f"?{parts.query}" if parts.query else "")
+    headers = {
+        name: value
+        for name, value in request.headers.items()
+        if name not in {"proxy-authorization", "proxy-connection", "connection"}
+    }
+    head = f"{request.method} {path} HTTP/1.1\r\n" + "".join(
+        f"{name}: {value}\r\n" for name, value in headers.items()
+    )
+    return (head + "Connection: close\r\n\r\n").encode("latin-1") + request.body
+
+
+async def _pipe_both(
+    client_reader: asyncio.StreamReader,
+    client_writer: asyncio.StreamWriter,
+    upstream_reader: asyncio.StreamReader,
+    upstream_writer: asyncio.StreamWriter,
+) -> None:
+    async def pipe(source: asyncio.StreamReader, sink: asyncio.StreamWriter) -> None:
+        with contextlib.suppress(ConnectionError, asyncio.IncompleteReadError):
+            while chunk := await source.read(_PIPE_CHUNK):
+                sink.write(chunk)
+                await sink.drain()
+        with contextlib.suppress(Exception):
+            sink.write_eof()
+
+    try:
+        await asyncio.gather(
+            pipe(client_reader, upstream_writer), pipe(upstream_reader, client_writer)
+        )
+    finally:
+        upstream_writer.close()
+        with contextlib.suppress(Exception):
+            await upstream_writer.wait_closed()