agentconnect-cli 0.1.0a1__py3-none-any.whl

agentconnect/a2a_adapter/cards.py

@@ -0,0 +1,149 @@
+"""Agent Cards: signature checks and the cards the facade serves.
+
+Signatures (A2A v1.0 ``AgentCard.signatures``, JWS over the RFC 8785 form of
+the card) are checked against keys the user pinned in a JWKS file
+(``a2a.card_keys_file``). A key is never fetched from a URL a card names
+(``jku``): for a peer's card that URL is peer-controlled.
+
+* ``verified``: a signature checks out with a pinned key.
+* ``unsigned``: the card has no signature.
+* ``unverified``: signed, but with no pinned key for it.
+* ``invalid``: signed with a pinned key, and no signature checks out. An
+  invalid card is not used.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+
+from a2a.types import (
+    AgentCapabilities,
+    AgentCard,
+    AgentInterface,
+    AgentSkill,
+    HTTPAuthSecurityScheme,
+    SecurityRequirement,
+    SecurityScheme,
+    StringList,
+)
+from a2a.utils.signing import SignatureVerificationError, create_signature_verifier
+from jwt import PyJWK
+from jwt.exceptions import PyJWKError, PyJWTError
+from jwt.utils import base64url_decode
+
+# Asymmetric only: a symmetric (HS*) key in a JWKS would let anyone holding
+# it forge cards, and accepting HS* invites algorithm confusion.
+ALGORITHMS = ["ES256", "ES384", "ES512", "RS256", "RS384", "RS512", "PS256", "PS384", "EdDSA"]
+BEARER = "agentconnectBearer"
+
+
+def load_jwks(path: Path | None) -> dict[str, PyJWK]:
+    """The pinned card-signing keys, by ``kid``."""
+    if path is None:
+        return {}
+    data = json.loads(path.read_text(encoding="utf-8"))
+    keys: dict[str, PyJWK] = {}
+    for jwk in data.get("keys", []) if isinstance(data, dict) else []:
+        if not isinstance(jwk, dict) or not isinstance(jwk.get("kid"), str):
+            continue
+        if jwk.get("kty") == "oct":
+            continue  # symmetric keys are refused, see ALGORITHMS
+        try:
+            keys[jwk["kid"]] = PyJWK(jwk)
+        except PyJWTError:
+            continue
+    return keys
+
+
+def _kids(card: AgentCard) -> list[str | None]:
+    kids: list[str | None] = []
+    for sig in card.signatures:
+        try:
+            header = json.loads(base64url_decode(sig.protected.encode("ascii")))
+        except (ValueError, UnicodeError):
+            kids.append(None)
+            continue
+        kid = header.get("kid") if isinstance(header, dict) else None
+        kids.append(kid if isinstance(kid, str) else None)
+    return kids
+
+
+def signature_status(card: AgentCard, keys: Mapping[str, PyJWK]) -> str:
+    """``verified``, ``unsigned``, ``unverified`` or ``invalid`` (above)."""
+    if len(card.signatures) == 0:
+        return "unsigned"
+    if not any(kid in keys for kid in _kids(card) if kid is not None):
+        return "unverified"
+
+    def key_for(kid: str | None, _jku: str | None) -> PyJWK:
+        if kid is None or kid not in keys:
+            msg = "no pinned key"
+            raise PyJWKError(msg)
+        return keys[kid]
+
+    try:
+        create_signature_verifier(key_for, ALGORITHMS)(card)
+    except SignatureVerificationError:
+        return "invalid"
+    return "verified"
+
+
+def _bearer(card: AgentCard) -> None:
+    card.security_schemes[BEARER].CopyFrom(
+        SecurityScheme(
+            http_auth_security_scheme=HTTPAuthSecurityScheme(
+                scheme="Bearer", description="The facade token (a2a-facade-token)."
+            )
+        )
+    )
+    card.security_requirements.append(SecurityRequirement(schemes={BEARER: StringList(list=[])}))
+
+
+def facade_card(
+    url: str,
+    name: str,
+    description: str,
+    skills: list[AgentSkill],
+    source: AgentCard | None = None,
+) -> AgentCard:
+    """A card for the local facade at ``url``: ``source`` (a peer's card)
+    mirrored with the facade's interface and auth, or a composite one."""
+    card = AgentCard()
+    if source is not None:
+        card.CopyFrom(source)
+        # The peer's interfaces, auth and signatures don't apply here.
+        card.ClearField("supported_interfaces")
+        card.ClearField("security_schemes")
+        card.ClearField("security_requirements")
+        card.ClearField("signatures")
+    else:
+        card.name = name
+        card.description = description
+        card.version = "0"
+        card.default_input_modes.extend(["text/plain", "application/json"])
+        card.default_output_modes.extend(["text/plain", "application/json"])
+        card.skills.extend(skills)
+    card.supported_interfaces.append(
+        AgentInterface(url=url, protocol_binding="JSONRPC", protocol_version="1.0")
+    )
+    card.capabilities.CopyFrom(AgentCapabilities(streaming=True, push_notifications=True))
+    _bearer(card)
+    return card
+
+
+def composite_skills(cards: Mapping[str, AgentCard], names: Mapping[str, str]) -> list[AgentSkill]:
+    """Every member's skills, ids prefixed by the member so they stay unique
+    and say whom to address (``metadata.to``)."""
+    out: list[AgentSkill] = []
+    for identity in sorted(cards):
+        for skill in cards[identity].skills:
+            s = AgentSkill()
+            s.CopyFrom(skill)
+            s.id = f"{identity}/{skill.id}"
+            label = names.get(identity) or identity
+            s.name = f"{label}: {skill.name}"
+            s.tags.append(f"member:{identity}")
+            out.append(s)
+    return out

agentconnect/a2a_adapter/convert.py

@@ -0,0 +1,157 @@
+"""Conversions between inner-message bodies (A2A v1.0 JSON, SPEC §7.2) and
+the ``a2a-sdk`` protobuf types.
+
+Bodies are peer-controlled. Parsing ignores unknown fields and never raises:
+a body that isn't a valid A2A ``Message`` becomes a message carrying its
+``text`` (or the whole body as a ``data`` part), so a peer can't crash the
+adapter with a malformed body.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from a2a.types import (
+    AgentCard,
+    CancelTaskRequest,
+    Message,
+    Part,
+    Role,
+    StreamResponse,
+    TaskArtifactUpdateEvent,
+    TaskState,
+    TaskStatusUpdateEvent,
+)
+from google.protobuf.json_format import MessageToDict, ParseDict, ParseError
+from google.protobuf.message import Message as ProtoMessage
+
+from agentconnect.limits import part_kind
+
+TERMINAL = frozenset(
+    {
+        TaskState.TASK_STATE_COMPLETED,
+        TaskState.TASK_STATE_FAILED,
+        TaskState.TASK_STATE_CANCELED,
+        TaskState.TASK_STATE_REJECTED,
+    }
+)
+INTERRUPTED = frozenset({TaskState.TASK_STATE_INPUT_REQUIRED, TaskState.TASK_STATE_AUTH_REQUIRED})
+
+
+def to_json(msg: ProtoMessage) -> dict[str, Any]:
+    """The A2A v1.0 JSON form (camelCase) of a protobuf message."""
+    return MessageToDict(msg)
+
+
+def _parse[T: ProtoMessage](body: Any, into: T) -> T | None:
+    if not isinstance(body, dict):
+        return None
+    try:
+        ParseDict(body, into, ignore_unknown_fields=True)
+    except (ParseError, TypeError, ValueError, RecursionError):
+        return None
+    return into
+
+
+def parse_message(body: dict[str, Any]) -> Message:
+    """A peer's ``a2a.message`` body as an A2A ``Message`` (never raises).
+    Malformed parts are left out (agentconnect.limits.part_kind): the daemon
+    has dropped any message carrying one, and this keeps it so here too."""
+    parts = body.get("parts")
+    if isinstance(parts, list):
+        msg = _parse({**body, "parts": [p for p in parts if part_kind(p) != "invalid"]}, Message())
+        return Message() if msg is None else msg
+    msg = _parse(body, Message())
+    if msg is not None and len(msg.parts) > 0:
+        return msg
+    out = Message() if msg is None else msg
+    text = body.get("text")
+    if isinstance(text, str):
+        out.parts.append(Part(text=text))
+        return out
+    fallback = _parse({"parts": [{"data": body}]}, Message())
+    if fallback is not None:
+        out.parts.extend(fallback.parts)
+    return out
+
+
+def parse_status(body: dict[str, Any]) -> TaskStatusUpdateEvent | None:
+    return _parse(body, TaskStatusUpdateEvent())
+
+
+def parse_artifact(body: dict[str, Any]) -> TaskArtifactUpdateEvent | None:
+    return _parse(body, TaskArtifactUpdateEvent())
+
+
+def parse_card(body: dict[str, Any]) -> AgentCard | None:
+    return _parse(body, AgentCard())
+
+
+def stream_to_inner(resp: StreamResponse, group_id: str) -> list[tuple[str, dict[str, Any]]]:
+    """What one event from the local agent becomes in the group: a list of
+    ``(kind, body)``. ``contextId`` is always the group (SPEC §7.2)."""
+    out: list[tuple[str, dict[str, Any]]] = []
+    payload = resp.WhichOneof("payload")
+    if payload == "task":
+        task = resp.task
+        status = TaskStatusUpdateEvent(task_id=task.id, context_id=group_id)
+        status.status.CopyFrom(task.status)
+        out.append(("a2a.task_status", to_json(status)))
+        for artifact in task.artifacts:
+            event = TaskArtifactUpdateEvent(task_id=task.id, context_id=group_id)
+            event.artifact.CopyFrom(artifact)
+            out.append(("a2a.task_artifact", to_json(event)))
+    elif payload == "status_update":
+        event = TaskStatusUpdateEvent()
+        event.CopyFrom(resp.status_update)
+        event.context_id = group_id
+        out.append(("a2a.task_status", to_json(event)))
+    elif payload == "artifact_update":
+        event = TaskArtifactUpdateEvent()
+        event.CopyFrom(resp.artifact_update)
+        event.context_id = group_id
+        out.append(("a2a.task_artifact", to_json(event)))
+    elif payload == "message":
+        msg = Message()
+        msg.CopyFrom(resp.message)
+        msg.context_id = group_id
+        out.append(("a2a.message", to_json(msg)))
+    return out
+
+
+def task_id_of(resp: StreamResponse) -> str:
+    payload = resp.WhichOneof("payload")
+    if payload == "task":
+        return resp.task.id
+    if payload == "status_update":
+        return resp.status_update.task_id
+    if payload == "artifact_update":
+        return resp.artifact_update.task_id
+    return ""
+
+
+def is_final(resp: StreamResponse) -> bool:
+    """Whether the stream has nothing more for this call."""
+    payload = resp.WhichOneof("payload")
+    if payload == "message":
+        return True
+    if payload == "task":
+        return resp.task.status.state in TERMINAL | INTERRUPTED
+    if payload == "status_update":
+        return resp.status_update.status.state in TERMINAL | INTERRUPTED
+    return False
+
+
+def cancel_body(task_id: str) -> dict[str, Any]:
+    """The ``a2a.task_cancel`` body (an A2A ``CancelTaskRequest``, SPEC 7.2)
+    a requester sends to cancel a bridged task."""
+    return to_json(CancelTaskRequest(id=task_id))
+
+
+def parse_cancel(body: dict[str, Any]) -> CancelTaskRequest | None:
+    request = _parse(body, CancelTaskRequest())
+    return request if request is not None and request.id else None
+
+
+def agent_text(text: str, group_id: str) -> Message:
+    return Message(role=Role.ROLE_AGENT, parts=[Part(text=text)], context_id=group_id)