agentic-runner 3.7.0__tar.gz → 3.8.0__tar.gz

{agentic_runner-3.7.0 → agentic_runner-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentic-runner
-Version: 3.7.0
+Version: 3.8.0
 Summary: The Agentic OS Runner: an activity-only Temporal executor for workspaces, Agent Runtimes and verb seams
 License-Expression: AGPL-3.0-only
 License-File: LICENSE

{agentic_runner-3.7.0 → agentic_runner-3.8.0}/src/agentic_runner/__init__.py

@@ -7,6 +7,6 @@ stay on the platform; this package imports none of them, and a CI partition test
 (``tests/test_package_partition.py``) fails the build if that changes.
 """
 
-__version__ = "3.7.0"
+__version__ = "3.8.0"
 
 __all__ = ["__version__"]

agentic_runner-3.8.0/src/agentic_runner/integrations/oauth/__init__.py

@@ -0,0 +1,68 @@
+"""The OAuth provider port: one form POST to a token or revocation endpoint (issue 30).
+
+RFC 6749 §4.1.3 / §6 and RFC 7009 are each a form POST answered with JSON, so the port is
+exactly that and the protocol lives in :mod:`agentic_runner.oauth_connectors`, where a
+fake provider exercises all of it. ``HttpOAuthProvider`` is the Runner's own outbound HTTPS
+-- the exchange never touches the control plane.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Final, Protocol
+
+import httpx
+
+__all__ = [
+    "HttpOAuthProvider",
+    "OAuthProvider",
+    "OAuthProviderError",
+    "ProviderResponse",
+]
+
+# One beat's budget: the exchange and a refresh run on the heartbeat, so a provider that
+# hangs must cost a failed step and not a stale link.
+_TIMEOUT: Final[float] = 10.0
+
+
+class OAuthProviderError(RuntimeError):
+    """The provider could not be reached or did not answer HTTP. Never carries a body."""
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderResponse:
+    status: int
+    # repr=False: a token response is the one body that must never reach a log line.
+    body: Mapping[str, object] = field(default_factory=dict, repr=False)
+
+
+class OAuthProvider(Protocol):
+    async def post_form(self, url: str, form: Mapping[str, str]) -> ProviderResponse: ...
+
+
+class HttpOAuthProvider:
+    """The real provider: HTTPS only, no redirects, JSON asked for.
+
+    Redirects are not followed because a 30x on a token endpoint would re-send the code
+    and the verifier to wherever it points. ``Accept: application/json`` because GitHub,
+    among others, answers form-encoded unless asked.
+    """
+
+    async def post_form(self, url: str, form: Mapping[str, str]) -> ProviderResponse:
+        try:
+            async with httpx.AsyncClient(timeout=_TIMEOUT, follow_redirects=False) as client:
+                response = await client.post(
+                    url, data=dict(form), headers={"Accept": "application/json"}
+                )
+        except httpx.HTTPError as error:
+            # The type only: an httpx error's text can carry the request URL, and a
+            # refresh's form is in no URL, but nothing here needs more than the class.
+            raise OAuthProviderError(type(error).__name__) from None
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+        return ProviderResponse(
+            status=response.status_code, body=body if isinstance(body, dict) else {}
+        )

agentic_runner-3.8.0/src/agentic_runner/integrations/oauth/fake_provider.py

@@ -0,0 +1,134 @@
+"""A fake OAuth provider that enforces what a real one does (issue 30's Runner tests).
+
+Strict on purpose: a code is single-use and bound to its client, redirect and S256
+challenge; a refresh token rotates and the old one stops working; revocation ends both.
+A Runner that sent the wrong verifier, replayed a code or kept an old refresh token fails
+here the way it would fail against a provider.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from urllib.parse import parse_qs, urlsplit
+
+from agentic_runner.integrations.oauth import ProviderResponse
+
+__all__ = ["FakeOAuthProvider"]
+
+AUTHORIZE = "https://provider.test/authorize"
+TOKEN = "https://provider.test/token"
+REVOKE = "https://provider.test/revoke"
+
+
+@dataclass
+class _Grant:
+    client_id: str
+    redirect_uri: str
+    challenge: str
+    scope: str
+
+
+@dataclass
+class FakeOAuthProvider:
+    client_id: str = "client-123"
+    client_secret: str | None = None
+    expires_in: int | None = 3600
+    authorize_endpoint: str = AUTHORIZE
+    token_endpoint: str = TOKEN
+    revocation_endpoint: str = REVOKE
+    requests: list[tuple[str, dict[str, str]]] = field(default_factory=list)
+    issued: list[str] = field(default_factory=list)
+    revoked: set[str] = field(default_factory=set)
+    _codes: dict[str, _Grant] = field(default_factory=dict)
+    # token -> the grant it belongs to; a refresh token also keeps the grant's scope.
+    _access: dict[str, str] = field(default_factory=dict)
+    _refresh: dict[str, tuple[str, str]] = field(default_factory=dict)
+
+    def consent(self, authorize_url: str) -> tuple[str, str]:
+        """The person approves: the ``(code, state)`` the callback URL would carry."""
+
+        query = {key: values[0] for key, values in parse_qs(urlsplit(authorize_url).query).items()}
+        assert query["response_type"] == "code"
+        assert query["code_challenge_method"] == "S256"
+        code = f"code-{secrets.token_hex(8)}"
+        self._codes[code] = _Grant(
+            client_id=query["client_id"],
+            redirect_uri=query["redirect_uri"],
+            challenge=query["code_challenge"],
+            scope=query.get("scope", ""),
+        )
+        return code, query["state"]
+
+    def access_valid(self, token: str) -> bool:
+        return token in self._access and token not in self.revoked
+
+    async def post_form(self, url: str, form: Mapping[str, str]) -> ProviderResponse:
+        self.requests.append((url, dict(form)))
+        if url == self.revocation_endpoint:
+            return self._revoke(form)
+        if url != self.token_endpoint:
+            return ProviderResponse(404)
+        if not self._client_ok(form):
+            return _error(401, "invalid_client")
+        if form.get("grant_type") == "authorization_code":
+            return self._exchange(form)
+        if form.get("grant_type") == "refresh_token":
+            return self._rotate(form)
+        return _error(400, "unsupported_grant_type")
+
+    def _client_ok(self, form: Mapping[str, str]) -> bool:
+        if form.get("client_id") != self.client_id:
+            return False
+        return self.client_secret is None or form.get("client_secret") == self.client_secret
+
+    def _exchange(self, form: Mapping[str, str]) -> ProviderResponse:
+        grant = self._codes.pop(form.get("code", ""), None)
+        if grant is None or grant.redirect_uri != form.get("redirect_uri"):
+            return _error(400, "invalid_grant")
+        verifier = form.get("code_verifier", "")
+        digest = hashlib.sha256(verifier.encode("ascii")).digest()
+        if base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii") != grant.challenge:
+            return _error(400, "invalid_grant")
+        return self._tokens(f"grant-{secrets.token_hex(8)}", grant.scope)
+
+    def _rotate(self, form: Mapping[str, str]) -> ProviderResponse:
+        held = self._refresh.pop(form.get("refresh_token", ""), None)
+        if held is None:
+            return _error(400, "invalid_grant")
+        return self._tokens(*held)
+
+    def _tokens(self, grant_id: str, scope: str) -> ProviderResponse:
+        access = f"at-{secrets.token_hex(16)}"
+        refresh = f"rt-{secrets.token_hex(16)}"
+        self._access[access] = grant_id
+        self._refresh[refresh] = (grant_id, scope)
+        self.issued += [access, refresh]
+        body: dict[str, object] = {
+            "access_token": access,
+            "refresh_token": refresh,
+            "token_type": "Bearer",
+            "scope": scope,
+        }
+        if self.expires_in is not None:
+            body["expires_in"] = self.expires_in
+        return ProviderResponse(200, body)
+
+    def _revoke(self, form: Mapping[str, str]) -> ProviderResponse:
+        if not self._client_ok(form):
+            return _error(401, "invalid_client")
+        token = form.get("token", "")
+        self.revoked.add(token)
+        # RFC 7009 §2.1: revoking a refresh token may revoke the grant's access tokens;
+        # this provider does, so the test can see the access token stop working.
+        held = self._refresh.pop(token, None)
+        if held is not None:
+            self.revoked.update(t for t, grant_id in self._access.items() if grant_id == held[0])
+        return ProviderResponse(200)
+
+
+def _error(status: int, code: str) -> ProviderResponse:
+    return ProviderResponse(status, {"error": code, "error_description": "fake provider"})

agentic_runner-3.8.0/src/agentic_runner/oauth_connectors.py

@@ -0,0 +1,592 @@
+"""OAuth Connectors, the Runner's half: start, exchange, refresh, revoke (console-v2 issue 30).
+
+ADR-0017 §3 and slice 24's flow: the platform never holds a readable OAuth token, so every
+step that touches the verifier, the code or a token runs here.
+
+* **Start** (step 2). A PKCE verifier and its S256 challenge (RFC 7636) and a ``state``
+  nonce, kept in process memory only; the authorise URL goes out on the next beat.
+* **Exchange** (step 4). The code arrives sealed to this installation's Recipient Key. It is
+  spent only if ``state`` matches and the authorisation is still waiting, and spending it
+  ends the authorisation, so a replay finds nothing to spend. The tokens are sealed to the
+  Recipient Key as the slot's next version and only that ciphertext leaves.
+* **Refresh** (step 5), when the access token is within :data:`REFRESH_MARGIN` of expiry or
+  when a caller saw a 401: re-sealed and uploaded the same way.
+* **Revoke** (step 6). On Disconnect the plaintext goes, and the provider's revocation
+  endpoint is called where the template has one (RFC 7009).
+
+**Backed by the sealed slot, not by a file.** The token set is the slot's plaintext, so the
+ack hands it back after a restart and to every other Runner of the installation, which open
+it with the same key. The Runner writes no token to disk and does not write the host store:
+``put`` there stays the host operator's act (``host_store``).
+
+**Only a token set this installation sealed is one.** A funder can seal any value to the
+same slot through Credential Delivery, and it opens exactly as the Runner's own upload does,
+so the Runner adopts a slot as a token set only when its tag, keyed off the Recipient
+private key, verifies (``SealedCredentialStream.authored``). Anything else is served as the
+funder delivered it and is never refreshed or revoked -- a forged token set would otherwise
+name the endpoint the Runner posts the host's client secret to.
+
+**What a Tool Server sees** is the access token, under the slot's name, through the same
+resolver as any delivered value. The token set's own shape -- refresh token, endpoint,
+client -- is Runner-private and is in no contracts model.
+
+**Two Runners, one slot.** Both may refresh near expiry. The upload is the slot's next
+version, and the first one the platform stores wins; the other Runner adopts it from the
+next ack (:meth:`OAuthConnectors.resolved`). A provider that revokes a whole grant on refresh
+token reuse can still end the loser's grant -- the slot then reports ``refresh_failed`` and
+the Connector card asks for a reconnect.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import hmac
+import json
+import logging
+import re
+import secrets
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field, replace
+from datetime import UTC, datetime, timedelta
+from typing import Annotated, Final
+from urllib.parse import urlencode, urlsplit, urlunsplit
+from uuid import UUID
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, StringConstraints, ValidationError
+
+from agentic_runner.credentials import CredentialResolver, UnresolvableCredentialReferenceError
+from agentic_runner.integrations.oauth import OAuthProvider, OAuthProviderError, ProviderResponse
+from agentic_runner.sealed_box import SealedCredentialStream
+from agentic_runner_contracts.oauth_connector import (
+    OAUTH_WINDOW,
+    HttpsUrl,
+    OAuthAuthorizeUrl,
+    OAuthClient,
+    OAuthDisconnect,
+    OAuthOutcome,
+    OAuthOutcomeKind,
+    OAuthStart,
+    SealedOAuthCode,
+)
+from agentic_runner_contracts.sealed_credential import (
+    CIPHERTEXT_MAX_CHARS,
+    SealedCredential,
+    SlotName,
+)
+
+__all__ = ["REFRESH_MARGIN", "TOKEN_SET_PREFIX", "OAuthConnectors", "TokenSet"]
+
+_logger = logging.getLogger(__name__)
+
+# Marks an authored slot value (``SealedCredentialStream.authored``) as a token set.
+# Versioned like a seal domain, so a later shape is a new prefix. Not what tells a token
+# set from a funder's key -- anyone can write a prefix; only the authored tag says that.
+TOKEN_SET_PREFIX: Final[str] = "agentic-os/oauth-token/v1:"
+
+# Two beats and change: a token refreshed this early is never spent expired by a Tool
+# Server between beats, and a provider's clock skew of a minute or two does not matter.
+REFRESH_MARGIN: Final[timedelta] = timedelta(minutes=5)
+
+# Bounds memory against a control plane that keeps starting authorisations nobody finishes.
+_PENDING_MAX: Final[int] = 64
+
+_PROVIDER_ERROR = re.compile(r"^[a-z][a-z0-9_.-]{0,63}$")
+
+SlotKey = tuple[str, str]
+
+
+class _TokenSetBody(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    access_token: Annotated[str, StringConstraints(min_length=1)]
+    refresh_token: Annotated[str, StringConstraints(min_length=1)] | None
+    expires_at: AwareDatetime | None
+    token_endpoint: HttpsUrl
+    client_id: Annotated[str, StringConstraints(min_length=1, max_length=512)]
+    client_secret_slot: SlotName | None
+
+
+@dataclass(frozen=True, slots=True)
+class TokenSet:
+    """One slot's tokens and what refreshing them needs. Process memory and sealed only."""
+
+    access_token: str = field(repr=False)
+    refresh_token: str | None = field(repr=False)
+    expires_at: datetime | None
+    token_endpoint: str
+    client_id: str
+    client_secret_slot: str | None
+
+    def encode(self) -> str:
+        return TOKEN_SET_PREFIX + json.dumps(
+            {
+                "access_token": self.access_token,
+                "refresh_token": self.refresh_token,
+                "expires_at": self.expires_at.isoformat() if self.expires_at else None,
+                "token_endpoint": self.token_endpoint,
+                "client_id": self.client_id,
+                "client_secret_slot": self.client_secret_slot,
+            },
+            separators=(",", ":"),
+        )
+
+    @classmethod
+    def decode(cls, value: str) -> TokenSet | None:
+        """The token set an authored slot value holds, or None for anything malformed.
+
+        Validated although only an authored value reaches here: the endpoint is where a
+        refresh sends the refresh token and the client secret, so it meets the same https
+        rule an :class:`OAuthClient` does, and a body this Runner cannot read must cost one
+        slot, never the beat.
+        """
+
+        if not value.startswith(TOKEN_SET_PREFIX):
+            return None
+        try:
+            body = _TokenSetBody.model_validate_json(value[len(TOKEN_SET_PREFIX) :])
+        except ValidationError:
+            return None
+        return cls(**body.model_dump())
+
+
+@dataclass(slots=True)
+class _Pending:
+    contract_id: str
+    slot: str
+    client: OAuthClient
+    redirect_uri: str
+    started_at: datetime
+    verifier: str = field(repr=False)
+    state: str = field(repr=False)
+
+
+@dataclass(slots=True)
+class _Held:
+    tokens: TokenSet
+    version: int
+    # The ciphertext this Runner sealed and has not yet seen the ack echo back. Re-sent
+    # every beat until it is, so a lost heartbeat cannot lose a refreshed token.
+    upload: SealedCredential | None = None
+
+
+class OAuthConnectors:
+    """Every OAuth step on this Runner, driven by the heartbeat (``service``)."""
+
+    def __init__(
+        self,
+        *,
+        sealed: SealedCredentialStream,
+        provider: OAuthProvider,
+        credentials: CredentialResolver,
+        clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+    ) -> None:
+        self._sealed = sealed
+        self._provider = provider
+        self._credentials = credentials
+        self._clock = clock
+        self._pending: dict[str, _Pending] = {}
+        self._held: dict[SlotKey, _Held] = {}
+        # The version a Disconnect saw; an ack still carrying that ciphertext is not
+        # re-adopted, and a reconnect seals above it.
+        self._dropped: dict[SlotKey, int] = {}
+        # A failed refresh is not retried every beat; a new version, or a 401, retries it.
+        self._failed: set[SlotKey] = set()
+        self._authorizations: list[OAuthAuthorizeUrl] = []
+        self._outcomes: list[OAuthOutcome] = []
+        self._lock = asyncio.Lock()
+
+    # ------------------------------------------------------------------ the envelope
+
+    def take_authorizations(self) -> list[OAuthAuthorizeUrl]:
+        taken, self._authorizations = self._authorizations, []
+        return taken
+
+    def take_outcomes(self) -> list[OAuthOutcome]:
+        taken, self._outcomes = self._outcomes, []
+        return taken
+
+    def uploads(self) -> list[SealedCredential]:
+        """Token ciphertext the control plane has not stored yet. Not drained (see _Held)."""
+
+        return [held.upload for _, held in sorted(self._held.items()) if held.upload is not None]
+
+    # ------------------------------------------------------------------ the ack
+
+    async def apply(
+        self,
+        *,
+        starts: list[OAuthStart],
+        codes: list[SealedOAuthCode],
+        disconnects: list[OAuthDisconnect],
+    ) -> None:
+        """One ack's OAuth items. Disconnects first: a slot connected and disconnected in
+        quick succession must end disconnected, whatever order the platform queued them."""
+
+        async with self._lock:
+            for disconnect in disconnects:
+                await self._disconnect(disconnect)
+            for start in starts:
+                self._start(start)
+            for code in codes:
+                await self._exchange(code)
+
+    def _start(self, start: OAuthStart) -> None:
+        verifier = secrets.token_urlsafe(64)
+        state = secrets.token_urlsafe(32)
+        self._pending[start.authorization_id] = _Pending(
+            contract_id=str(start.contract_id),
+            slot=start.slot,
+            client=start.client,
+            redirect_uri=start.redirect_uri,
+            started_at=self._clock(),
+            verifier=verifier,
+            state=state,
+        )
+        while len(self._pending) > _PENDING_MAX:
+            self._pending.pop(next(iter(self._pending)))
+        query = {
+            "response_type": "code",
+            "client_id": start.client.client_id,
+            "redirect_uri": start.redirect_uri,
+            "state": state,
+            "code_challenge": _challenge(verifier),
+            "code_challenge_method": "S256",
+        }
+        if start.client.scopes:
+            query["scope"] = " ".join(start.client.scopes)
+        self._authorizations.append(
+            OAuthAuthorizeUrl(
+                contract_id=start.contract_id,
+                slot=start.slot,
+                authorization_id=start.authorization_id,
+                authorize_url=_with_query(start.client.authorize_endpoint, query),
+            )
+        )
+
+    async def _exchange(self, sealed: SealedOAuthCode) -> None:
+        authorization_id = sealed.authorization_id
+        pending = self._pending.get(authorization_id)
+        if pending is None or pending.contract_id != str(sealed.contract_id):
+            self._report(str(sealed.contract_id), None, authorization_id, OAuthOutcomeKind.UNKNOWN)
+            return
+        if self._clock() - pending.started_at > OAUTH_WINDOW:
+            del self._pending[authorization_id]
+            self._report(
+                pending.contract_id, pending.slot, authorization_id, OAuthOutcomeKind.EXPIRED
+            )
+            return
+        # A wrong `state` leaves the authorisation waiting: the code was injected, or is
+        # another tab's, and either way the person's own callback can still land.
+        if not hmac.compare_digest(sealed.state.encode(), pending.state.encode()):
+            self._report(
+                pending.contract_id,
+                pending.slot,
+                authorization_id,
+                OAuthOutcomeKind.STATE_MISMATCH,
+            )
+            return
+        code = self._sealed.open_oauth_code(sealed)
+        if code is None:
+            self._report(
+                pending.contract_id, pending.slot, authorization_id, OAuthOutcomeKind.UNOPENABLE
+            )
+            return
+        # Spent from here on, whatever the provider says: a code is single-use at the
+        # provider, and the verifier must not outlive the one exchange it was made for.
+        del self._pending[authorization_id]
+        client = pending.client
+        form = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": pending.redirect_uri,
+            "client_id": client.client_id,
+            "code_verifier": pending.verifier,
+        }
+        del code
+        key = (pending.contract_id, pending.slot)
+        response = await self._post(key, client.client_secret_slot, client.token_endpoint, form)
+        if response is None:
+            self._report(*key, authorization_id, OAuthOutcomeKind.CLIENT_SECRET_MISSING)
+            return
+        tokens = _token_set(response, client=client, now=self._clock())
+        if tokens is None:
+            self._report(
+                *key,
+                authorization_id,
+                OAuthOutcomeKind.EXCHANGE_FAILED,
+                provider_error=_provider_error(response),
+            )
+            return
+        outcome = self._seal(key, tokens)
+        self._report(*key, authorization_id, outcome)
+
+    async def _disconnect(self, disconnect: OAuthDisconnect) -> None:
+        key = (str(disconnect.contract_id), disconnect.slot)
+        held = self._held.pop(key, None)
+        self._failed.discard(key)
+        self._dropped[key] = max(
+            held.version if held is not None else 0, self._sealed.version(*key) or 0
+        )
+        for authorization_id in [
+            authorization_id
+            for authorization_id, pending in self._pending.items()
+            if (pending.contract_id, pending.slot) == key
+        ]:
+            del self._pending[authorization_id]
+        client = disconnect.client
+        if held is None or client.revocation_endpoint is None:
+            self._report(*key, None, OAuthOutcomeKind.DROPPED)
+            return
+        # The refresh token, where there is one: RFC 7009 §2.1 lets the provider end the
+        # whole grant from it, which an access token's revocation does not promise.
+        token, hint = (
+            (held.tokens.refresh_token, "refresh_token")
+            if held.tokens.refresh_token
+            else (held.tokens.access_token, "access_token")
+        )
+        form = {"token": token, "token_type_hint": hint, "client_id": client.client_id}
+        response = await self._post(
+            key, client.client_secret_slot, client.revocation_endpoint, form
+        )
+        if response is None:
+            self._report(*key, None, OAuthOutcomeKind.CLIENT_SECRET_MISSING)
+        elif response.status == 200:
+            self._report(*key, None, OAuthOutcomeKind.REVOKED)
+        else:
+            self._report(
+                *key,
+                None,
+                OAuthOutcomeKind.REVOKE_FAILED,
+                provider_error=_provider_error(response),
+            )
+
+    # ------------------------------------------------------------------ refresh
+
+    async def before_beat(self) -> None:
+        """Forget authorisations past their window, then refresh every token set within
+        :data:`REFRESH_MARGIN` of expiry (step 5) -- so the upload rides this beat."""
+
+        async with self._lock:
+            now = self._clock()
+            for authorization_id, pending in list(self._pending.items()):
+                if now - pending.started_at > OAUTH_WINDOW:
+                    del self._pending[authorization_id]
+                    self._report(
+                        pending.contract_id,
+                        pending.slot,
+                        authorization_id,
+                        OAuthOutcomeKind.EXPIRED,
+                    )
+            for key, held in sorted(self._held.items()):
+                expires_at = held.tokens.expires_at
+                if key in self._failed or held.tokens.refresh_token is None:
+                    continue
+                if expires_at is not None and expires_at - now <= REFRESH_MARGIN:
+                    await self._refresh(key)
+
+    async def refresh(self, contract_id: UUID | str, slot: str) -> bool:
+        """Refresh now, because a provider answered 401 to the access token (step 5).
+
+        Retries a slot whose last refresh failed, unlike :meth:`before_beat`: a 401 is new
+        information that the token is dead.
+        """
+
+        async with self._lock:
+            return await self._refresh((str(contract_id), slot))
+
+    async def _refresh(self, key: SlotKey) -> bool:
+        held = self._held.get(key)
+        if held is None or held.tokens.refresh_token is None:
+            return False
+        tokens = held.tokens
+        form = {
+            "grant_type": "refresh_token",
+            "refresh_token": tokens.refresh_token,
+            "client_id": tokens.client_id,
+        }
+        response = await self._post(key, tokens.client_secret_slot, tokens.token_endpoint, form)
+        if response is None:
+            self._failed.add(key)
+            self._report(*key, None, OAuthOutcomeKind.CLIENT_SECRET_MISSING)
+            return False
+        fresh = _token_set(response, client=None, now=self._clock(), previous=tokens)
+        if fresh is None:
+            self._failed.add(key)
+            self._report(
+                *key,
+                None,
+                OAuthOutcomeKind.REFRESH_FAILED,
+                provider_error=_provider_error(response),
+            )
+            return False
+        outcome = self._seal(key, fresh)
+        if outcome is OAuthOutcomeKind.CONNECTED:
+            outcome = OAuthOutcomeKind.REFRESHED
+        else:
+            self._failed.add(key)
+        self._report(*key, None, outcome)
+        return outcome is OAuthOutcomeKind.REFRESHED
+
+    # ------------------------------------------------------------------ the resolver
+
+    def resolved(self) -> dict[SlotKey, str]:
+        """What the resolver serves: every opened slot, a token set as its access token.
+
+        Also where the ack's token sets are adopted. A version at or above what this
+        Runner holds replaces it -- another Runner of the installation refreshed, or the
+        upload landed; a lower one is the ack not yet carrying this Runner's own upload
+        and is ignored. A slot the ack no longer carries is dropped once its upload was
+        confirmed, which is how a Disconnect handled by another Runner reaches this one.
+        """
+
+        served: dict[SlotKey, str] = {}
+        carried: set[SlotKey] = set()
+        for key, value in self._sealed.plaintext.items():
+            # Only a value this installation authored is ever read as a token set: its
+            # endpoint and client secret slot steer where the Runner sends a secret, and a
+            # funder can seal anything to the slot. Any other value is served as delivered.
+            body = self._sealed.authored(*key, value)
+            if body is None:
+                served[key] = value
+                continue
+            tokens = TokenSet.decode(body)
+            if tokens is None:
+                _logger.warning("OAuth token set for %s/%s is unreadable; not served", *key)
+                continue
+            version = self._sealed.version(*key) or 0
+            if version <= self._dropped.get(key, 0):
+                continue
+            carried.add(key)
+            held = self._held.get(key)
+            if held is None or version >= held.version:
+                if held is None or held.version != version:
+                    self._failed.discard(key)
+                self._held[key] = _Held(tokens=tokens, version=version)
+        for key in [key for key, held in self._held.items() if key not in carried]:
+            if self._held[key].upload is None:
+                del self._held[key]
+        for key, held in self._held.items():
+            served[key] = held.tokens.access_token
+        return served
+
+    # ------------------------------------------------------------------ helpers
+
+    def _seal(self, key: SlotKey, tokens: TokenSet) -> OAuthOutcomeKind:
+        held = self._held.get(key)
+        version = 1 + max(
+            held.version if held is not None else 0,
+            self._sealed.version(*key) or 0,
+            self._dropped.get(key, 0),
+        )
+        upload = self._sealed.seal_authored(*key, version=version, value=tokens.encode())
+        if len(upload.ciphertext) > CIPHERTEXT_MAX_CHARS:
+            return OAuthOutcomeKind.TOKEN_TOO_LARGE
+        self._held[key] = _Held(tokens=tokens, version=version, upload=upload)
+        self._failed.discard(key)
+        return OAuthOutcomeKind.CONNECTED
+
+    async def _post(
+        self, key: SlotKey, secret_slot: str | None, url: str, form: Mapping[str, str | None]
+    ) -> ProviderResponse | None:
+        """POST to the provider with client authentication; None if the secret is missing.
+
+        ``client_secret_post`` (RFC 6749 §2.3.1): every provider that issues a secret
+        accepts it, and it keeps the secret out of a header a proxy might log.
+        """
+
+        body = {name: value for name, value in form.items() if value is not None}
+        if secret_slot is not None:
+            try:
+                credentials = self._credentials.resolve(contract_id=key[0], manifest=[secret_slot])
+            except UnresolvableCredentialReferenceError:
+                return None
+            body["client_secret"] = credentials.for_runner_hosted_server(secret_slot)
+        try:
+            return await self._provider.post_form(url, body)
+        except OAuthProviderError as error:
+            _logger.warning("OAuth provider unreachable for %s/%s: %s", *key, error)
+            return ProviderResponse(status=0)
+
+    def _report(
+        self,
+        contract_id: str,
+        slot: str | None,
+        authorization_id: str | None,
+        outcome: OAuthOutcomeKind,
+        *,
+        provider_error: str | None = None,
+    ) -> None:
+        _logger.info("OAuth %s for %s/%s (%s)", outcome.value, contract_id, slot, authorization_id)
+        self._outcomes.append(
+            OAuthOutcome(
+                contract_id=UUID(contract_id),
+                slot=slot,
+                authorization_id=authorization_id,
+                outcome=outcome,
+                provider_error=provider_error,
+            )
+        )
+
+
+def _challenge(verifier: str) -> str:
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+def _with_query(endpoint: str, query: Mapping[str, str]) -> str:
+    # An authorize endpoint may carry its own query (a tenant, an audience); RFC 6749
+    # §3.1 says to keep it and add ours.
+    parts = urlsplit(endpoint)
+    joined = f"{parts.query}&{urlencode(query)}" if parts.query else urlencode(query)
+    return urlunsplit(parts._replace(query=joined))
+
+
+def _token_set(
+    response: ProviderResponse,
+    *,
+    client: OAuthClient | None,
+    now: datetime,
+    previous: TokenSet | None = None,
+) -> TokenSet | None:
+    """RFC 6749 §5.1, or None. A refresh that returns no new refresh token keeps the old
+    one (§6: the provider *may* issue a new one)."""
+
+    body = response.body
+    access_token = body.get("access_token")
+    if response.status != 200 or not isinstance(access_token, str) or not access_token:
+        return None
+    token_type = body.get("token_type")
+    if isinstance(token_type, str) and token_type.lower() != "bearer":
+        return None
+    refresh_token = body.get("refresh_token")
+    expires_in = body.get("expires_in")
+    expires_at = (
+        now + timedelta(seconds=expires_in)
+        if isinstance(expires_in, int) and not isinstance(expires_in, bool) and expires_in > 0
+        else None
+    )
+    if previous is not None:
+        return replace(
+            previous,
+            access_token=access_token,
+            refresh_token=refresh_token
+            if isinstance(refresh_token, str)
+            else previous.refresh_token,
+            expires_at=expires_at,
+        )
+    assert client is not None
+    return TokenSet(
+        access_token=access_token,
+        refresh_token=refresh_token if isinstance(refresh_token, str) else None,
+        expires_at=expires_at,
+        token_endpoint=client.token_endpoint,
+        client_id=client.client_id,
+        client_secret_slot=client.client_secret_slot,
+    )
+
+
+def _provider_error(response: ProviderResponse) -> str | None:
+    error = response.body.get("error")
+    return error if isinstance(error, str) and _PROVIDER_ERROR.match(error) else None

{agentic_runner-3.7.0 → agentic_runner-3.8.0}/src/agentic_runner/sealed_box.py

@@ -34,6 +34,7 @@ from __future__ import annotations
 
 import base64
 import binascii
+import hmac
 import json
 import logging
 import secrets
@@ -55,6 +56,7 @@ from cryptography.hazmat.primitives.kdf.hkdf import HKDF
 
 from agentic_runner.auth_mode import SETUP_TOKEN_REFUSED_RULE, is_setup_token
 from agentic_runner.private_state import private_read, private_write
+from agentic_runner_contracts.oauth_connector import SealedOAuthCode
 from agentic_runner_contracts.runner_registration import RecipientKey
 from agentic_runner_contracts.sealed_credential import (
     RENEWAL_INTERVAL,
@@ -81,6 +83,12 @@ __all__ = [
 
 RECIPIENT_KEY_FILENAME: Final[str] = "recipient-key.json"
 
+# What marks a slot value as one this installation sealed for itself, rather than one a
+# funder delivered: the prefix, then an HMAC keyed off the Recipient private key
+# (:meth:`SealedCredentialStream.authored`). Versioned like a seal domain.
+AUTHORED_PREFIX: Final[str] = "agentic-os/runner-authored/v1:"
+AUTHORED_MAC_DOMAIN: Final[bytes] = b"agentic-os/runner-authored-mac/v1"
+
 _PUBLIC_KEY_BYTES: Final[int] = 32
 _KEY_BYTES: Final[int] = 32
 _NONCE: Final[bytes] = bytes(12)
@@ -328,6 +336,35 @@ def _derive(shared: bytes, ephemeral_public: bytes, recipient_public: bytes) ->
     ).derive(shared)
 
 
+def _authored_mac(pair: RecipientKeyPair, contract_id: str, slot: str, body: str) -> bytes:
+    # Its own HKDF domain, so the MAC key shares nothing with any seal's AEAD key. A
+    # contract id is a UUID and a slot name has no NUL, so the joined message is unambiguous.
+    mac_key = HKDF(
+        algorithm=hashes.SHA256(), length=_KEY_BYTES, salt=b"", info=AUTHORED_MAC_DOMAIN
+    ).derive(_raw_key(pair.private_key, "private"))
+    message = "\x00".join((contract_id, slot, body)).encode("utf-8")
+    return hmac.digest(mac_key, message, "sha256")
+
+
+def _tag_authored(pair: RecipientKeyPair, contract_id: str, slot: str, body: str) -> str:
+    tag = base64.urlsafe_b64encode(_authored_mac(pair, contract_id, slot, body)).decode("ascii")
+    return f"{AUTHORED_PREFIX}{tag}:{body}"
+
+
+def _untag_authored(pair: RecipientKeyPair, contract_id: str, slot: str, value: str) -> str | None:
+    if not value.startswith(AUTHORED_PREFIX):
+        return None
+    tag, separator, body = value[len(AUTHORED_PREFIX) :].partition(":")
+    if not separator:
+        return None
+    try:
+        claimed = base64.urlsafe_b64decode(tag.encode("ascii"))
+    except (binascii.Error, ValueError):
+        return None
+    expected = _authored_mac(pair, contract_id, slot, body)
+    return body if hmac.compare_digest(claimed, expected) else None
+
+
 def _public_key(value: str) -> X25519PublicKey:
     return X25519PublicKey.from_public_bytes(_raw_key(value, "public"))
 
@@ -494,7 +531,7 @@ class SealedCredentialStream:
                     binding=delivery_binding(
                         contract_id=contract_id, slot=slot, recipient_key_id=fresh.key_id
                     ),
-                    plaintext=value,
+                    plaintext=self._retagged(contract_id, slot, value, fresh),
                 ),
             )
             for (contract_id, slot), value in sorted(self._plaintext.items())
@@ -526,6 +563,63 @@ class SealedCredentialStream:
 
         return self._open_with(sealed.recipient_key_id, sealed.binding(), sealed.ciphertext)
 
+    def open_oauth_code(self, sealed: SealedOAuthCode) -> str | None:
+        """A relayed OAuth code, or None when it does not open (console-v2 issue 30).
+
+        Never held, like a sign-in code: the caller spends it on the token endpoint and
+        drops it.
+        """
+
+        return self._open_with(sealed.recipient_key_id, sealed.binding(), sealed.ciphertext)
+
+    def seal_authored(
+        self, contract_id: str, slot: str, *, version: int, value: str
+    ) -> SealedCredential:
+        """Seal a value this Runner made to its own current key, as one slot's delivery.
+
+        How an OAuth token set leaves the Runner (console-v2 issue 30): bound to the same
+        ``(contract, slot, key)`` triple a funder's delivery is, so every Runner of the
+        installation opens it through :meth:`apply` and no other installation can. Tagged
+        so :meth:`authored` can tell it from a funder's value in the same slot.
+        """
+
+        key = self._keys.current()
+        return SealedCredential(
+            contract_id=UUID(contract_id),
+            slot=slot,
+            recipient_key_id=key.key_id,
+            version=version,
+            ciphertext=seal(
+                public_key=key.public_key,
+                binding=delivery_binding(
+                    contract_id=contract_id, slot=slot, recipient_key_id=key.key_id
+                ),
+                plaintext=_tag_authored(key, contract_id, slot, value),
+            ),
+        )
+
+    def authored(self, contract_id: str, slot: str, value: str) -> str | None:
+        """The value :meth:`seal_authored` tagged, or None for anything a funder delivered.
+
+        Sealing is public-key, so anyone holding the Recipient public key -- every funder --
+        can seal a value to this slot that opens exactly as the Runner's own upload does.
+        Only the tag, keyed off the private half, says this installation wrote it. Checked
+        against the previous key too, so a value tagged before a renewal still verifies
+        until its re-seal (re-tagged in :meth:`renew`) is the one held.
+        """
+
+        for pair in (self._keys.current(), self._keys.previous()):
+            if pair is None:
+                continue
+            body = _untag_authored(pair, contract_id, slot, value)
+            if body is not None:
+                return body
+        return None
+
+    def _retagged(self, contract_id: str, slot: str, value: str, fresh: RecipientKeyPair) -> str:
+        body = self.authored(contract_id, slot, value)
+        return value if body is None else _tag_authored(fresh, contract_id, slot, body)
+
     def _open(self, sealed: SealedCredential) -> str | None:
         return self._open_with(sealed.recipient_key_id, sealed.binding(), sealed.ciphertext)
 

{agentic_runner-3.7.0 → agentic_runner-3.8.0}/src/agentic_runner/service.py

@@ -61,6 +61,7 @@ from agentic_runner.heartbeat_link import WAKE_DIVERGENCE, HeartbeatLink
 from agentic_runner.hooks import AttemptFacts, HookName, HookRunner
 from agentic_runner.integrations.git.workspace import LocalGitWorkspace
 from agentic_runner.integrations.github.gh_client import GitHubAppClient
+from agentic_runner.integrations.oauth import HttpOAuthProvider
 from agentic_runner.lifecycle import LIFECYCLE_FILENAME, LifecycleOutbox
 from agentic_runner.llm_proxy import (
     LLM_SLOT_REFERENCES,
@@ -73,6 +74,7 @@ from agentic_runner.llm_proxy import (
 )
 from agentic_runner.mcp import ToolServerHealthLog
 from agentic_runner.message_store import MESSAGES_DIR, MessageStore, TemporalWorkflowSignaller
+from agentic_runner.oauth_connectors import OAuthConnectors
 from agentic_runner.private_state import (
     UnsafeStateError,
     ensure_private_dir,
@@ -593,6 +595,8 @@ class ControlPlaneStream:
     llm_slots: Mapping[str, LlmProvider] = field(default_factory=lambda: dict(LLM_SLOT_REFERENCES))
     # Local-agents 05: the Claude Code sign-ins a relayed code is typed into.
     sign_ins: ClaudeSignIns | None = None
+    # Console-v2 issue 30: the OAuth Connectors whose code, tokens and verifier stay here.
+    oauth: OAuthConnectors | None = None
     # Reported once, on the beat after the relay: a lost beat loses the outcome, and the
     # console's own wait on the sign-in is what tells the person.
     _sign_in_outcomes: list[SignInCodeRelay] = field(default_factory=list)
@@ -678,6 +682,8 @@ class ControlPlaneStream:
         self._observe_sleep(now)
         lifecycle = self.lifecycle.pending() if self.lifecycle is not None else []
         renewed, resealed = self.sealed.renew(now)
+        if self.oauth is not None:
+            await self.oauth.before_beat()
         envelope = HeartbeatEnvelope(
             runner_version=runner_version,
             contracts_version=contracts_version,
@@ -704,6 +710,9 @@ class ControlPlaneStream:
             source_status=self.sources.statuses() if self.sources is not None else [],
             tool_servers=self.tool_servers.latest() if self.tool_servers is not None else [],
             sign_in_codes=self._sign_in_outcomes,
+            oauth_authorizations=self.oauth.take_authorizations() if self.oauth else [],
+            oauth_tokens=self.oauth.uploads() if self.oauth else [],
+            oauth_outcomes=self.oauth.take_outcomes() if self.oauth else [],
         )
         self._sign_in_outcomes = []
         ack = await self.client.heartbeat(self.state, envelope)
@@ -711,6 +720,12 @@ class ControlPlaneStream:
             self.sources.assign(ack.user_sources)
         await self._deliver_transcripts(ack)
         await self._relay_sign_in_codes(ack)
+        if self.oauth is not None:
+            # Before the sealed values are applied: a Disconnect revokes with the tokens
+            # this Runner holds, and the same ack may already have withdrawn their ciphertext.
+            await self.oauth.apply(
+                starts=ack.oauth_starts, codes=ack.oauth_codes, disconnects=ack.oauth_disconnects
+            )
         if self.lifecycle is not None:
             self.lifecycle.acknowledge(lifecycle)
         if self.heartbeat_stamp is not None:
@@ -782,7 +797,7 @@ class ControlPlaneStream:
     def _sync_delivered(self) -> None:
         """The resolver holds exactly what the last ack let this installation open."""
 
-        plaintext = self.sealed.plaintext
+        plaintext = self.oauth.resolved() if self.oauth is not None else self.sealed.plaintext
         for (contract_id, slot), value in plaintext.items():
             self.credentials.deliver(contract_id, slot, value)
         for contract_id, slot in self._delivered - set(plaintext):
@@ -1074,6 +1089,9 @@ async def _serve_registered(
     stream.messages = messages
     sign_ins = ClaudeSignIns(build_contract_isolation(settings, can_separate_uids=can_change_uid))
     stream.sign_ins = sign_ins
+    stream.oauth = OAuthConnectors(
+        sealed=stream.sealed, provider=HttpOAuthProvider(), credentials=credentials
+    )
     tool_servers = ToolServerHealthLog()
     stream.tool_servers = tool_servers
     link = HeartbeatLink(stream, ceilings=proxy.ceilings)