superqode 2.2.1__tar.gz → 2.2.3__tar.gz

{superqode-2.2.1 → superqode-2.2.3}/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.3] - 2026-09-13
+
+Security fixes for the UHP client and the BYOK server bind shipped in 2.2.2.
+Anyone who ran `superqode connect uhp` on 2.2.2 sent their model key to the
+address they connected to, including on the anonymous discovery request, so
+upgrading is worth doing before the next connect. No API changed and no
+protocol behaviour changed: the Core conformance result is the same 38/40.
+
+### 🔐 UHP security
+
+- The client sends `X-Provider-Api-Key` on a task submission only. It was
+  attached to every request, including the anonymous discovery and catalog
+  GETs, so `connect uhp --base-url <address>` handed that address the caller's
+  model key before the caller had decided to trust it. The key is also
+  withheld from a remote plaintext `http://` origin, with a warning.
+- A caller's model key no longer races with another caller's. It is written to
+  every environment variable the provider reads, and BYOK turns are serialised
+  for as long as it is in the process environment, which LiteLLM reads
+  credentials from. Concurrent turns previously overwrote each other's key.
+- `Dockerfile.uhp` no longer passes `--api-key` on the command line. The bearer
+  came from the environment either way, and the argument published it in
+  `/proc/1/cmdline`, which the bound harness's shell tool can read.
+- On a remote bind each session gets its own directory under the working
+  directory, so callers cannot read each other's files or session transcripts.
+  A local bind still runs in the directory it was given.
+- Request metadata can no longer set harness runtime controls such as
+  `agent_max_iterations`. Caller context is still passed through.
+- Bearer comparison is constant time.
+
+## [2.2.2] - 2026-09-12
+
+The installed CLI can complete a harness turn against a BYOK UHP host such as
+`uhp.superqode.dev`. The client sends the caller's provider key
+(`GEMINI_API_KEY` / `GOOGLE_API_KEY` when the provider is Google). The public
+Core bind stays catalog-open and does not attach a model key. A separate Cloud
+Run image (`Dockerfile.uhp`) deploys that bind without touching A2A.
+
+### 🧩 Unified Harness Protocol
+
+- `UHPClient` and `harness run uhp` send `X-Provider-Api-Key` from the
+  caller's environment so a remote Core host can run a turn without a
+  server-side `GEMINI_API_KEY`.
+- Remote `serve uhp --allow-remote` requires `--api-key`. Catalog GETs stay
+  public; `POST /v1/responses` without the caller provider key returns
+  `missing_provider_key` and does not start LiteLLM.
+- Public bind defaults: provider `google`, model `gemini-flash-latest`, harness
+  `chrn_superqode_core`. Image and Cloud Build files are `Dockerfile.uhp` and
+  `cloudbuild.uhp.yaml` (service `superqode-uhp`).
+
 ## [2.2.1] - 2026-09-12
 
 Local UHP for the package cut: SuperQode speaks it as a client (connect, run,

{superqode-2.2.1 → superqode-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.2.1
+Version: 2.2.3
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
@@ -483,6 +483,12 @@ superqode harness run uhp --prompt "summarise this repository"
 to HarnessRouter, which wraps third-party CLIs as a catalog. Core names the
 surface SuperQode implements; it is not a conformance-suite certificate.
 
+The public hostname for that bind is [`uhp.superqode.dev`](https://uhp.superqode.dev/v1/uhp).
+Anonymous callers get discovery and the static harness catalog (no model call).
+A harness turn requires a SuperQode UHP API key and the caller's own provider
+key. SuperQode does not pay for that model. Until the hostname is mapped, use
+local `serve uhp` as above.
+
 Read the [UHP guide](docs/providers/uhp.md).
 
 ## Harness Execution Model

{superqode-2.2.1 → superqode-2.2.3}/README.md

@@ -332,6 +332,12 @@ superqode harness run uhp --prompt "summarise this repository"
 to HarnessRouter, which wraps third-party CLIs as a catalog. Core names the
 surface SuperQode implements; it is not a conformance-suite certificate.
 
+The public hostname for that bind is [`uhp.superqode.dev`](https://uhp.superqode.dev/v1/uhp).
+Anonymous callers get discovery and the static harness catalog (no model call).
+A harness turn requires a SuperQode UHP API key and the caller's own provider
+key. SuperQode does not pay for that model. Until the hostname is mapped, use
+local `serve uhp` as above.
+
 Read the [UHP guide](docs/providers/uhp.md).
 
 ## Harness Execution Model

{superqode-2.2.1 → superqode-2.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superqode"
-version = "2.2.1"
+version = "2.2.3"
 description = "The harness layer for coding agents"
 readme = "README.md"
 license = "Apache-2.0"

{superqode-2.2.1 → superqode-2.2.3}/src/superqode/__init__.py

@@ -38,7 +38,7 @@ __all__ = [
     "sidebar",
 ]
 
-__version__ = "2.2.1"
+__version__ = "2.2.3"
 
 # Stable, lightweight public extension surface.  Importing this package does
 # not discover or execute third-party extensions; discovery happens only when

{superqode-2.2.1 → superqode-2.2.3}/src/superqode/commands/serve.py

@@ -351,7 +351,7 @@ def serve_a2a(
     "--api-key",
     envvar="SUPERQODE_UHP_API_KEY",
     default=None,
-    help="Optional bearer token; when set, all routes except discovery require it",
+    help="Bearer token. Required with --allow-remote. Catalog GETs stay public.",
 )
 @click.option("--allow-remote", is_flag=True, help="Allow binding outside localhost")
 @click.option(
@@ -380,10 +380,11 @@ def serve_uhp(
     is_loopback = host in {"127.0.0.1", "localhost", "::1"}
     if not is_loopback and not allow_remote:
         raise click.ClickException("Use --allow-remote to bind outside localhost.")
-    if allow_remote and not api_key:
-        console.print(
-            "[yellow]Remote UHP bind without --api-key / SUPERQODE_UHP_API_KEY; "
-            "discovery is public and every other route is open.[/yellow]"
+    if allow_remote and not (api_key or "").strip():
+        raise click.ClickException(
+            "Remote UHP bind requires --api-key / SUPERQODE_UHP_API_KEY. "
+            "Catalog GETs stay public; harness turns need the bearer and "
+            "the caller's X-Provider-Api-Key."
         )
 
     server = create_uhp_server(
@@ -393,6 +394,8 @@ def serve_uhp(
         working_directory=working_dir.resolve(),
         api_key=api_key,
         harness_id=harness_id,
+        public_catalog=allow_remote,
+        require_caller_provider_key=allow_remote,
     )
     console.print(
         f"[cyan]Serving SuperQode UHP {server.discovery_document()['default_version']} "

{superqode-2.2.1 → superqode-2.2.3}/src/superqode/harness/uhp_client.py

@@ -13,15 +13,20 @@ from __future__ import annotations
 
 import base64
 import json
+import logging
 import mimetypes
+import os
 import uuid
 from collections.abc import AsyncIterator, Mapping, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
+from urllib.parse import urlparse
 
 import httpx
 
+logger = logging.getLogger(__name__)
+
 UHP_PROTOCOL_VERSION = "2026-08-11"
 
 #: Sent on every request so a server does not silently answer at another
@@ -32,6 +37,22 @@ VERSION_HEADER = "UHP-Version"
 #: workspace, so every task submission carries one.
 IDEMPOTENCY_HEADER = "Idempotency-Key"
 
+#: Caller model key for a BYOK UHP server. SuperQode does not send its own.
+#: A SuperQode extension, not part of UHP. Task submission only.
+PROVIDER_KEY_HEADER = "X-Provider-Api-Key"
+
+#: Plaintext http is safe enough to carry a key to these.
+_LOOPBACK_HOSTS = frozenset({"127.0.0.1", "::1", "localhost"})
+
+
+def _caller_provider_api_key() -> str:
+    """Return the caller's model key for a BYOK UHP server, if present."""
+    provider = (os.environ.get("SUPERQODE_PROVIDER") or "google").strip() or "google"
+    if provider in {"google", "gemini"}:
+        return (os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY") or "").strip()
+    return (os.environ.get(f"{provider.upper()}_API_KEY") or "").strip()
+
+
 _TERMINAL_STREAM_EVENTS = frozenset(
     {
         "response.completed",
@@ -481,7 +502,8 @@ class UHPClient:
             timeout, because a harness can work for minutes between events.
         headers: Extra headers merged into every request.  A cookie header
             belongs here for a server that gates the API with a console
-            session instead of a bearer token.
+            session instead of a bearer token.  ``PROVIDER_KEY_HEADER`` is the
+            exception: it rides task submission only.
         client: An existing ``httpx.AsyncClient`` to borrow instead of creating
             one.  A borrowed client is never closed by ``aclose``.
     """
@@ -498,16 +520,46 @@ class UHPClient:
         self.base_url = self._normalize_base_url(base_url)
         self.api_key = api_key
         self.timeout = timeout
-        self._headers = {
+        merged = {
             "Accept": "application/json",
             VERSION_HEADER: UHP_PROTOCOL_VERSION,
             **dict(headers or {}),
         }
+        # Held aside, not merged: a model key rides task submission only.
+        self._provider_key = str(merged.pop(PROVIDER_KEY_HEADER, "") or "").strip()
+        self._headers = merged
         if api_key:
             self._headers["Authorization"] = f"Bearer {api_key}"
         self._client = client
         self._owns_client = client is None
 
+    def _origin_is_confidential(self) -> bool:
+        """Whether this base URL protects a credential in transit."""
+        parsed = urlparse(self.base_url)
+        if parsed.scheme == "https":
+            return True
+        return (parsed.hostname or "").lower() in _LOOPBACK_HOSTS
+
+    def _provider_key_headers(self) -> dict[str, str]:
+        """The caller's model key, for a task submission only.
+
+        Withheld from a plaintext origin, not refused there: a server reached
+        over http may not want the key at all, and one that does answers
+        ``missing_provider_key``.
+        """
+        key = self._provider_key or _caller_provider_api_key()
+        if not key:
+            return {}
+        if not self._origin_is_confidential():
+            logger.warning(
+                "Not sending %s to %s: the connection is plaintext http, which would put the "
+                "model key on the wire in clear. Use an https base URL if this server needs it.",
+                PROVIDER_KEY_HEADER,
+                self.base_url,
+            )
+            return {}
+        return {PROVIDER_KEY_HEADER: key}
+
     @staticmethod
     def _normalize_base_url(base_url: str) -> str:
         """Return the server root without a trailing slash or ``/v1`` suffix."""
@@ -800,7 +852,10 @@ class UHPClient:
             message, input_files=input_files, inline_files=inline_files
         )
         body = self.build_response_body(prepared, stream=False, **kwargs)
-        headers = {IDEMPOTENCY_HEADER: idempotency_key or self.new_idempotency_key()}
+        headers = {
+            IDEMPOTENCY_HEADER: idempotency_key or self.new_idempotency_key(),
+            **self._provider_key_headers(),
+        }
         payload = await self._request("POST", "responses", json_body=body, headers=headers)
         if not isinstance(payload, Mapping):
             raise UHPServerError("UHP server returned no response object")
@@ -834,6 +889,7 @@ class UHPClient:
             **self._headers,
             "Accept": "text/event-stream",
             IDEMPOTENCY_HEADER: idempotency_key or self.new_idempotency_key(),
+            **self._provider_key_headers(),
         }
         pending_error: UHPError | None = None
         try:

{superqode-2.2.1 → superqode-2.2.3}/src/superqode/harness/uhp_server.py

@@ -13,11 +13,14 @@ session listing) are deferred.
 from __future__ import annotations
 
 import asyncio
+import hmac
 import json
+import os
 import re
 import time
 import uuid
 from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
+from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
@@ -27,7 +30,11 @@ try:
 except Exception:  # pragma: no cover - optional at import time
     FastAPIRequest = Any  # type: ignore[misc,assignment]
 
-from superqode.harness.uhp_client import UHP_PROTOCOL_VERSION, VERSION_HEADER
+from superqode.harness.uhp_client import (
+    PROVIDER_KEY_HEADER,
+    UHP_PROTOCOL_VERSION,
+    VERSION_HEADER,
+)
 
 #: Advertised and accepted protocol version.
 SUPPORTED_VERSION = UHP_PROTOCOL_VERSION
@@ -37,6 +44,20 @@ DISCOVERY_OBJECT = "uhp.discovery"
 
 IDEMPOTENCY_HEADER = "Idempotency-Key"
 
+#: Runtime controls, not caller context. A request body may not set these.
+RESERVED_METADATA_KEYS = frozenset(
+    {
+        "agent_max_iterations",
+        "delegation_depth",
+        "harness_digest",
+        "harness_source",
+        "provider_api_key",
+    }
+)
+
+#: Guards the caller key in os.environ, which the whole process shares.
+_PROVIDER_ENV_LOCK = asyncio.Lock()
+
 HarnessRunner = Callable[["UHPRunRequest"], Awaitable["UHPRunResult"]]
 
 
@@ -158,6 +179,13 @@ class UHPServerConfig:
     implementation_version: str = ""
     #: Honest claim: core endpoints only; suite not yet run.
     conformance_class: str = "core"
+    #: GET catalog without a bearer (remote public host). POST still requires api_key.
+    public_catalog: bool = False
+    #: Refuse a harness turn unless the caller sent PROVIDER_KEY_HEADER.
+    require_caller_provider_key: bool = False
+    #: Per-session directory under working_directory, so callers on a shared
+    #: bind cannot read each other's files. Off locally: work in the project.
+    isolate_session_workspaces: bool = False
 
 
 def _package_version() -> str:
@@ -169,6 +197,60 @@ def _package_version() -> str:
         return "0.0.0"
 
 
+def _provider_key_envs(provider: str) -> tuple[str, ...]:
+    """Every env var LiteLLM may read for this provider (caller BYOK).
+
+    All of them, not just the first: which one LiteLLM reads is its choice,
+    and Google alone has two.
+    """
+    try:
+        from superqode.providers.registry import PROVIDERS
+
+        pdef = PROVIDERS.get(provider)
+        names = tuple(str(name) for name in (getattr(pdef, "env_vars", None) or ()) if name)
+        if names:
+            return names
+    except Exception:
+        pass
+    return (f"{(provider or 'OPENAI').upper()}_API_KEY",)
+
+
+@asynccontextmanager
+async def _caller_provider_key(token: str, env_names: Sequence[str]) -> AsyncIterator[None]:
+    """Hold one caller's model key in ``os.environ`` for the length of a turn.
+
+    Serialises BYOK turns: the environment is process-global, so overlapping
+    turns would otherwise send each other's key.
+    """
+    if not token:
+        yield
+        return
+    async with _PROVIDER_ENV_LOCK:
+        previous = {name: os.environ.get(name) for name in env_names}
+        for name in env_names:
+            os.environ[name] = token
+        try:
+            yield
+        finally:
+            for name, value in previous.items():
+                if value is None:
+                    os.environ.pop(name, None)
+                else:
+                    os.environ[name] = value
+
+
+def _caller_metadata(body: Mapping[str, Any]) -> dict[str, Any]:
+    """Caller-supplied metadata with the runtime's own control keys removed."""
+    raw = body.get("metadata")
+    if not isinstance(raw, Mapping):
+        return {}
+    return {
+        str(key): value
+        for key, value in raw.items()
+        if str(key) not in RESERVED_METADATA_KEYS and not str(key).startswith("_")
+    }
+
+
 def harness_id_from_name(name: str) -> str:
     """Build a ``chrn_…`` id from a harness/spec name."""
     slug = re.sub(r"[^a-z0-9]+", "_", (name or "superqode").lower()).strip("_")
@@ -369,8 +451,8 @@ class UHPServer:
                     content=negotiated,
                     headers={VERSION_HEADER: SUPPORTED_VERSION},
                 )
-            # Discovery is unauthenticated per the OpenAPI contract.
-            if not server._is_public_path(request.url.path):
+            # Discovery (and optional catalog GETs) stay unauthenticated.
+            if not server._is_public_request(request.method, request.url.path):
                 auth_error = server._check_auth(request.headers.get("authorization"))
                 if auth_error is not None:
                     return JSONResponse(
@@ -504,8 +586,27 @@ class UHPServer:
                 status, envelope = harness_error
                 return JSONResponse(status_code=status, content=envelope)
 
+            provider_api_key = (http_request.headers.get(PROVIDER_KEY_HEADER) or "").strip()
+            if server.config.require_caller_provider_key and not provider_api_key:
+                return JSONResponse(
+                    status_code=403,
+                    content=_error_envelope(
+                        error_type="permission_error",
+                        code="missing_provider_key",
+                        message=(
+                            f"Harness turns on this host require header '{PROVIDER_KEY_HEADER}' "
+                            "(your provider key). SuperQode does not attach a model key."
+                        ),
+                        param=PROVIDER_KEY_HEADER,
+                    ),
+                )
+
             stream = bool(body.get("stream"))
-            started = await server._start_response(body, idempotency_key=idempotency_key or None)
+            started = await server._start_response(
+                body,
+                idempotency_key=idempotency_key or None,
+                provider_api_key=provider_api_key or None,
+            )
             if isinstance(started, tuple):
                 status, envelope = started
                 return JSONResponse(status_code=status, content=envelope)
@@ -620,9 +721,18 @@ class UHPServer:
 
     # -- auth / version ---------------------------------------------------------
 
-    @staticmethod
-    def _is_public_path(path: str) -> bool:
-        return path in {"/v1/uhp", "/health", "/docs", "/openapi.json", "/redoc"}
+    def _is_public_request(self, method: str, path: str) -> bool:
+        path = path.rstrip("/") or "/"
+        if path in {"/v1/uhp", "/health", "/docs", "/openapi.json", "/redoc"}:
+            return True
+        if not self.config.public_catalog or method.upper() != "GET":
+            return False
+        if path in {"/v1/harnesses", "/v1/models"}:
+            return True
+        if path.startswith("/v1/harnesses/"):
+            rest = path[len("/v1/harnesses/") :]
+            return "/" not in rest or rest.endswith("/models")
+        return False
 
     def _negotiate_version(self, requested: str | None) -> dict[str, Any] | None:
         if not requested or not requested.strip():
@@ -655,7 +765,8 @@ class UHPServer:
                 code="invalid_credential",
                 message="Authorization must be a Bearer token.",
             )
-        if token != expected:
+        # Bytes, because compare_digest rejects a non-ASCII str.
+        if not hmac.compare_digest(token.encode("utf-8"), expected.encode("utf-8")):
             return _error_envelope(
                 error_type="authentication_error",
                 code="invalid_credential",
@@ -663,6 +774,15 @@ class UHPServer:
             )
         return None
 
+    def _workspace_for(self, session_id: str) -> Path:
+        """The directory a turn runs in."""
+        root = Path(self.config.working_directory)
+        if not self.config.isolate_session_workspaces:
+            return root
+        workspace = root / "sessions" / session_id
+        workspace.mkdir(parents=True, exist_ok=True)
+        return workspace
+
     def _validate_harness_selection(
         self, body: Mapping[str, Any]
     ) -> tuple[int, dict[str, Any]] | None:
@@ -684,7 +804,11 @@ class UHPServer:
     # -- response lifecycle -----------------------------------------------------
 
     async def _start_response(
-        self, body: Mapping[str, Any], *, idempotency_key: str | None
+        self,
+        body: Mapping[str, Any],
+        *,
+        idempotency_key: str | None,
+        provider_api_key: str | None = None,
     ) -> dict[str, Any]:
         prompt = _extract_prompt(body.get("input"))
         previous_response_id = body.get("previous_response_id")
@@ -761,7 +885,7 @@ class UHPServer:
             prompt=prompt,
             model=model,
             provider=self.config.provider,
-            working_directory=Path(self.config.working_directory),
+            working_directory=self._workspace_for(session_id),
             session_id=session_id,
             response_id=response_id,
             previous_response_id=previous_response_id,
@@ -772,7 +896,8 @@ class UHPServer:
             cancel_event=self._cancel_events[response_id],
             metadata={
                 "harness_id": self.config.harness_id,
-                **(dict(body["metadata"]) if isinstance(body.get("metadata"), Mapping) else {}),
+                **_caller_metadata(body),
+                **({"provider_api_key": provider_api_key} if provider_api_key else {}),
             },
         )
 
@@ -979,14 +1104,19 @@ class UHPServer:
         if request.instructions:
             prompt = f"{request.instructions.rstrip()}\n\n{prompt}"
 
+        run_metadata = {
+            key: value for key, value in dict(request.metadata).items() if key != "provider_api_key"
+        }
+        token = str(request.metadata.get("provider_api_key") or "")
         try:
-            result = await session.prompt(
-                prompt,
-                provider=provider,
-                model=model,
-                working_directory=request.working_directory,
-                metadata=dict(request.metadata),
-            )
+            async with _caller_provider_key(token, _provider_key_envs(provider)):
+                result = await session.prompt(
+                    prompt,
+                    provider=provider,
+                    model=model,
+                    working_directory=request.working_directory,
+                    metadata=run_metadata,
+                )
         except Exception:
             return UHPRunResult(
                 status="failed",
@@ -1015,8 +1145,14 @@ def create_uhp_server(
     harness_id: str | None = None,
     harness_name: str | None = None,
     runner: HarnessRunner | None = None,
+    public_catalog: bool = False,
+    require_caller_provider_key: bool = False,
+    isolate_session_workspaces: bool | None = None,
 ) -> UHPServer:
-    """Build a UHP server bound to one SuperQode HarnessSpec."""
+    """Build a UHP server bound to one SuperQode HarnessSpec.
+
+    ``isolate_session_workspaces`` defaults to whether the bind is BYOK.
+    """
     from superqode.harness import get_harness_template, load_harness_spec
 
     if spec is None:
@@ -1047,5 +1183,12 @@ def create_uhp_server(
         api_key=api_key,
         implementation_version=_package_version(),
         conformance_class="core",
+        public_catalog=public_catalog,
+        require_caller_provider_key=require_caller_provider_key,
+        isolate_session_workspaces=(
+            require_caller_provider_key
+            if isolate_session_workspaces is None
+            else isolate_session_workspaces
+        ),
     )
     return UHPServer(config, runner=runner, spec=loaded)

{superqode-2.2.1 → superqode-2.2.3}/src/superqode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.2.1
+Version: 2.2.3
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
@@ -483,6 +483,12 @@ superqode harness run uhp --prompt "summarise this repository"
 to HarnessRouter, which wraps third-party CLIs as a catalog. Core names the
 surface SuperQode implements; it is not a conformance-suite certificate.
 
+The public hostname for that bind is [`uhp.superqode.dev`](https://uhp.superqode.dev/v1/uhp).
+Anonymous callers get discovery and the static harness catalog (no model call).
+A harness turn requires a SuperQode UHP API key and the caller's own provider
+key. SuperQode does not pay for that model. Until the hostname is mapped, use
+local `serve uhp` as above.
+
 Read the [UHP guide](docs/providers/uhp.md).
 
 ## Harness Execution Model