From 9f68009b2a8b64644f5bcab9264fd5339e7e5dd4 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 12:00:36 -0800 Subject: [PATCH 1/8] feat(a2a-agent): atif/1 reads leave out the secrets the SDK knows Every atif/1 read, inline, uploaded or paged, writes each secret the SDK holds or is handed as [redacted:] wherever it occurs: the control token, the model key and extra headers' values, write-only agent-config values, MCP and CDP credentials, the parts of every transfer grant that carry its credential, a clock follower's read token, and whatever the agent registers with self.register_secret(value). Secrets are taken from each extension call before any handler runs and scrubbed at read time, matched raw, JSON-escaped and percent-encoded, the longest first; one under 8 characters is left with a warning. Cursor pages count their byte budget as they serve. Native reads are untouched. Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 25 ++ .../agentenv_protocol/a2a_agent/_atif_copy.py | 16 +- .../agentenv_protocol/a2a_agent/_secrets.py | 179 +++++++++++ .../a2a_agent/_trajectory_log.py | 14 +- .../agentenv_protocol/a2a_agent/framework.py | 42 ++- .../src/agentenv_protocol/atif/PROFILE.md | 2 + .../tests/test_a2a_atif_scrubbing.py | 303 ++++++++++++++++++ src/agent_env/agents/AGENTS.md | 4 +- ...test_prompt_agent_live_trajectory_local.py | 34 +- tst/util/a2a_test_agent.py | 5 +- 10 files changed, 603 insertions(+), 21 deletions(-) create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py create mode 100644 packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 8f0e3a4c7..40656289a 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1666,6 +1666,31 @@ extension names the state the SDK keeps (`"state": ["turns"]` in its params, `SNAPSHOT_STATE_PARAM`), and agent-env grants the object only to an agent whose card has it, since an SDK from before it refuses the object. +Every `atif/1` read leaves out the secrets the SDK knows, each written +`[redacted:]` wherever it occurs: in the document, the aux log and the +turn context, inline, uploaded and in cursor pages, whose byte budget counts +what they serve. The SDK knows: + +- its control token, and the model credentials in its environment: + `LITELLM_API_KEY` and the values of `LITELLM_EXTRA_HEADERS`; +- write-only agent-config values; +- an MCP registration's header and query values, and a CDP endpoint's header + values and its URLs, unless one is a bare origin; +- every transfer grant an extension call hands the agent: its URL whole, its + path and query as a request line names them, its query values, its headers + other than `Content-Type` and the like, and a signed upload form's signing + fields; +- a clock follower's read token; +- whatever the agent registers with `self.register_secret(value)`, once its app + exists (in `run`, say). + +They're taken from each extension call before any handler runs, the agent's own +included. A value under 8 characters isn't scrubbed, with a warning naming where +it came from. Each is matched raw, JSON-escaped and percent-encoded, the longest +first, and a read scrubs as it serves, so a secret learned after a step was +written is left out too. Native reads keep every secret byte for byte, so a +replay of the served inputs holds what the served copy redacts. + `enable(..., description="...")` is reserved for declarations carrying configuration or metadata. It preserves the agent-specific extension prose published in the Agent Card. The versioned SDK definition provides a generic diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py index 47f3e4749..a252f3de9 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py @@ -13,7 +13,7 @@ from contextlib import contextmanager from dataclasses import dataclass, field from datetime import datetime, timezone -from typing import Any, Iterable, Iterator, Sequence +from typing import Any, Callable, Iterable, Iterator, Sequence from urllib.parse import urlsplit, urlunsplit from ..atif import FORMAT, Adapter, AdapterRun, AuxEntry, Media, ServedTurn, TurnContext @@ -143,11 +143,13 @@ def context_read(self) -> dict[str, Any] | None: self._check() return self._run.page() - def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | None = None) -> AtifPage: + def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | None = None, + scrub: Callable[[Any], Any] = lambda served: served) -> AtifPage: """The closed steps after step ``after``, of the whole context or of task ``task_id``, within both budgets; the first is always returned, so one larger than ``max_bytes`` can't stall a reader. With them, the sub-agents of every task they belong to, as far as each is served: a sub-agent can gain steps while its task runs, and the - page that serves a task's last step, which closes only as the task ends, carries them whole.""" + page that serves a task's last step, which closes only as the task ends, carries them whole. Everything is + served through ``scrub``, and the byte budget counts what it serves.""" with self._lock: self._check() document = self._run.page() @@ -163,6 +165,7 @@ def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | Non tasks: set[str | None] = set() used = 0 for step, owner in pending[:max_steps]: + step = scrub(step) size = len(json.dumps(step)) if served and used + size > max_bytes: break @@ -172,9 +175,10 @@ def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | Non header = None subagents: list[dict[str, Any]] = [] if document is not None: - header = {key: value for key, value in document.items() if key not in ("steps", "subagent_trajectories")} - subagents = [sub for sub in document.get("subagent_trajectories", []) - if sub_tasks.get(sub["trajectory_id"]) in tasks] + header = scrub({key: value for key, value in document.items() + if key not in ("steps", "subagent_trajectories")}) + subagents = scrub([sub for sub in document.get("subagent_trajectories", []) + if sub_tasks.get(sub["trajectory_id"]) in tasks]) return AtifPage(header=header, subagents=subagents, steps=served, next=served[-1]["step_id"] if served else after, has_more=len(served) < len(pending)) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py new file mode 100644 index 000000000..c66f8f65c --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py @@ -0,0 +1,179 @@ +"""The secrets an agent's atif/1 reads leave out: every value the SDK holds or is handed (its control token, write-only +agent-config values, MCP and CDP registrations' credentials, the grants and tokens in extension calls, the model +credentials in its environment) and every one the agent registers. Each read scrubs every string it serves, so a +secret learned after a step was written is still left out; native reads are never scrubbed.""" + +from __future__ import annotations + +import json +import logging +import os +import re +import threading +from collections.abc import Iterable, Iterator, Mapping +from typing import Any, TypeVar +from urllib.parse import parse_qsl, quote, urlsplit + +from pydantic import BaseModel, SecretStr + +from ..transfers import HttpGetGrant, HttpPostPolicyGrant, HttpPutGrant +from .extensions import CdpAddRequest, ClockSyncTimeRequest, McpAddRequest + +logger = logging.getLogger(__name__) + +#: A shorter value isn't scrubbed: replacing it everywhere it occurs would mangle ordinary text. +MIN_SECRET_LENGTH = 8 +#: The model credentials an agent's environment holds, which a tool can echo. +MODEL_KEY_ENV = "LITELLM_API_KEY" +MODEL_HEADERS_ENV = "LITELLM_EXTRA_HEADERS" +#: Header names whose values describe a request rather than authorize it. +_PLAIN_HEADERS = frozenset({"accept", "content-encoding", "content-length", "content-type", "user-agent"}) +#: Words in a signed upload form's field names that mark the values that sign it. +_SIGNING_FIELDS = ("policy", "signature", "credential", "token", "accesskey", "accessid") +#: A path segment a URL with no query can carry its credential in, as a grant server's signed token. +_TOKEN_SEGMENT = re.compile(r"[A-Za-z0-9_.=~+-]{16,}") + +T = TypeVar("T") + + +class Secrets: + """The values an agent's atif/1 reads leave out, each written ``[redacted:]`` wherever it occurs, in its raw, + JSON-escaped and percent-encoded forms. Safe to add to from the agent's threads while the loop scrubs.""" + + def __init__(self) -> None: + self._lock = threading.Lock() + self._forms: set[str] = set() + self._pattern: re.Pattern[str] | None = None + self._short: set[str] = set() + + def add(self, value: str | SecretStr | None, *, source: str, warn: bool = True) -> None: + """Leave ``value`` out of every atif/1 read from now on; ``source`` names it in the warning a value too short to + scrub gets, never the value, unless ``warn`` is off, as for the parts of a URL.""" + text = value.get_secret_value() if isinstance(value, SecretStr) else value + if not isinstance(text, str) or not text: + return + if len(text) < MIN_SECRET_LENGTH: + if warn and source not in self._short: + self._short.add(source) + logger.warning("a secret from %s is shorter than %d characters, so atif/1 reads don't scrub it", + source, MIN_SECRET_LENGTH) + return + forms = {text, json.dumps(text)[1:-1], quote(text, safe="")} + with self._lock: + if forms <= self._forms: + return + self._forms |= forms + ordered = sorted(self._forms, key=len, reverse=True) + self._pattern = re.compile("|".join(re.escape(form) for form in ordered)) + + def add_all(self, values: Iterable[str | SecretStr | None], *, source: str, warn: bool = True) -> None: + for value in values: + self.add(value, source=source, warn=warn) + + def add_environment(self, environ: Mapping[str, str] | None = None) -> None: + """The model credentials in the agent's environment: its key, and its extra headers' values.""" + environ = os.environ if environ is None else environ + self.add(environ.get(MODEL_KEY_ENV), source=MODEL_KEY_ENV) + try: + headers = json.loads(environ.get(MODEL_HEADERS_ENV) or "{}") + except ValueError: + return + if isinstance(headers, dict): + self.add_all(_header_values(headers), source=MODEL_HEADERS_ENV) + + def add_request(self, request: BaseModel | None) -> None: + """Every secret an extension call hands the agent: its grants' URLs, query values, headers and signing fields, + an MCP or CDP registration's credentials and a clock follower's read token, wherever the request holds them.""" + for item in _models(request): + if isinstance(item, (HttpGetGrant, HttpPutGrant, HttpPostPolicyGrant)): + self.add_all(_url_secrets(str(item.url)), source="a transfer grant", warn=False) + self.add_all(_grant_secrets(item), source="a transfer grant") + elif isinstance(item, McpAddRequest): + self.add_all(_query_values(item.url), source="an MCP registration", warn=False) + self.add_all(_header_values(item.headers), source="an MCP registration's headers") + elif isinstance(item, CdpAddRequest): + self.add_all([*_url_secrets(item.http_url), *_url_secrets(item.ws_url)], source="a CDP registration", + warn=False) + self.add_all(_header_values(item.headers), source="a CDP registration's headers") + elif isinstance(item, ClockSyncTimeRequest): + self.add(item.read_token, source="a clock follower's read token") + + def add_values(self, value: Any, *, source: str) -> None: + """Every string ``value`` holds, in fields, lists and mappings, as a write-only config value may.""" + self.add_all(_strings(value), source=source) + + def scrub(self, value: T) -> T: + """``value`` with every secret in its strings, its mappings' values and its lists' items redacted.""" + pattern = self._pattern + return value if pattern is None else _scrub(value, pattern) + + +def _scrub(value: Any, pattern: re.Pattern[str]) -> Any: + if isinstance(value, str): + return pattern.sub(lambda match: f"[redacted:{len(match.group(0))}]", value) + if isinstance(value, dict): + return {key: _scrub(item, pattern) for key, item in value.items()} + if isinstance(value, list): + return [_scrub(item, pattern) for item in value] + return value + + +def _models(value: Any) -> Iterator[BaseModel]: + """``value`` and every model it holds, in fields, lists and mappings.""" + if isinstance(value, BaseModel): + yield value + for name in type(value).model_fields: + yield from _models(getattr(value, name)) + elif isinstance(value, (list, tuple)): + for item in value: + yield from _models(item) + elif isinstance(value, Mapping): + for item in value.values(): + yield from _models(item) + + +def _strings(value: Any) -> Iterator[str | SecretStr]: + if isinstance(value, (str, SecretStr)): + yield value + elif isinstance(value, BaseModel): + for name in type(value).model_fields: + yield from _strings(getattr(value, name)) + elif isinstance(value, (list, tuple, set)): + for item in value: + yield from _strings(item) + elif isinstance(value, Mapping): + for item in value.values(): + yield from _strings(item) + + +def _grant_secrets(grant: HttpGetGrant | HttpPutGrant | HttpPostPolicyGrant) -> list[str]: + """A grant's credential headers, and a signed upload form's signing fields.""" + secrets = _header_values(grant.headers) + if isinstance(grant, HttpPostPolicyGrant): + secrets += [value for name, value in grant.fields.items() + if name != grant.path_field and any(word in name.lower() for word in _SIGNING_FIELDS)] + return secrets + + +def _url_secrets(url: str) -> list[str]: + """A URL that can carry a credential, in its path, query or user info: whole, and the part that carries it. A + presigned URL keeps its signature in its query, so its query's values and its path and query as a request line + names them (``curl -v`` prints that); a URL with no query keeps its token in a long path segment. A bare origin + carries none.""" + parts = urlsplit(url) + if not parts.path.strip("/") and not parts.query and parts.password is None: + return [] + if parts.query: + carried = [f"{parts.path}?{parts.query}", *_query_values(url)] + else: + carried = [segment for segment in parts.path.split("/") if _TOKEN_SEGMENT.fullmatch(segment)] + return [url, *carried, *([parts.password] if parts.password else [])] + + +def _query_values(url: str) -> list[str]: + return [value for _, value in parse_qsl(urlsplit(url).query)] + + +def _header_values(headers: Mapping[str, Any] | None) -> list[str]: + return [value for name, value in (headers or {}).items() + if isinstance(value, str) and name.lower() not in _PLAIN_HEADERS] diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py index 4d108b918..5858ce1b0 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py @@ -6,7 +6,7 @@ import logging from collections import OrderedDict from dataclasses import dataclass -from typing import Any, Sequence +from typing import Any, Callable, Sequence from ..atif import Adapter, AuxEntry, ServedTurn from ._atif_copy import AtifCopy, AtifPage, TurnStart @@ -287,29 +287,29 @@ def atif_context(self, context_id: str) -> dict[str, Any] | None: return copy.context_read() def atif_task_page( - self, task_id: str, after: int, max_steps: int, max_bytes: int + self, task_id: str, after: int, max_steps: int, max_bytes: int, *, scrub: Callable[[Any], Any] ) -> AtifCursor | None: - """A cursor page of the task's closed atif/1 steps, in the task's state.""" + """A cursor page of the task's closed atif/1 steps, in the task's state, served through ``scrub``.""" record = self._tasks.get(task_id) copy = self._copies.get(record.context_id) if record is not None else None if copy is None: return None self._touch(record.context_id) state = record.state - page = copy.page(after, max_steps, max_bytes, task_id=task_id) + page = copy.page(after, max_steps, max_bytes, task_id=task_id, scrub=scrub) return AtifCursor(page=page, context_id=record.context_id, task_id=task_id, state=state) def atif_context_page( - self, context_id: str, after: int, max_steps: int, max_bytes: int + self, context_id: str, after: int, max_steps: int, max_bytes: int, *, scrub: Callable[[Any], Any] ) -> AtifCursor | None: """A cursor page of the context's closed atif/1 steps, on the task the context is on and in - the context's state.""" + the context's state, served through ``scrub``.""" copy = self._copies.get(context_id) records = self._context_records(context_id) if copy is not None else None if copy is None or records is None: return None task_id, state = self._context_progress(context_id, records) - page = copy.page(after, max_steps, max_bytes) + page = copy.page(after, max_steps, max_bytes, scrub=scrub) return AtifCursor(page=page, context_id=context_id, task_id=task_id, state=state) def _context_progress( diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index cb311637d..04daa1c54 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -34,6 +34,7 @@ from ..atif import PROFILE_VERSION as ATIF_PROFILE_VERSION from ..atif import SCHEMA_VERSION as ATIF_SCHEMA_VERSION from ._atif_copy import TurnStart +from ._secrets import Secrets from ._snapshot_state import SnapshotStates from ._trajectory_log import MAX_TRAJECTORY_READ_BYTES, TaskTrajectories from ._triggers import TriggerEngine, TriggerError @@ -259,6 +260,15 @@ def session_ref_for_context(self, context_id: str) -> str | None: raise RuntimeError("session references are available after create_app()") return application.services.session_ref_for_context(context_id) + def register_secret(self, value: str) -> None: + """Leave ``value`` out of this agent's atif/1 reads from now on, wherever it occurs, as the SDK does with the + secrets it holds and is handed; one under 8 characters isn't, with a warning. Native reads keep it.""" + application = getattr(self, "_agentenv_a2a_application", None) + if application is None: + raise RuntimeError("secrets are registered after create_app()") + if application.services.secrets is not None: + application.services.secrets.add(value, source="the agent") + def set_session_ref_for_context(self, context_id: str, session_ref: str) -> None: """Associate a native session reference with an A2A context.""" if not context_id: @@ -583,6 +593,14 @@ def __init__( self.serves_atif = atif is not None #: The SDK's state in the agent's snapshots, which only an agent that serves atif/1 keeps. self.snapshot_states = SnapshotStates(self.task_trajectories) if atif is not None else None + #: The secrets the agent's atif/1 reads leave out; an agent that serves none has none to scrub. + self.secrets = Secrets() if atif is not None else None + if self.secrets is not None: + self.secrets.add_environment() + self.secrets.add_values( + [value for name, value in self.config_defaults.items() if name in self._write_only_config_fields], + source="a write-only agent-config default", + ) self._context_sessions = _BoundedContextSessions() self.skills: list[Mapping[str, Any]] = [] self.identity_skills: dict[str, str] = {} @@ -727,6 +745,20 @@ async def agent_config_set(self, request: AgentConfig) -> dict[str, Any]: self.card.description = validated.description return {"status": "updated"} + def note_secrets(self, request: Any) -> None: + """Keep the secrets an extension call hands the agent out of its atif/1 reads, whichever handler takes it: + its grants and registrations' credentials, and a write-only agent-config value.""" + if self.secrets is None: + return + self.secrets.add_request(request) + if isinstance(request, AgentConfig): + wire_names = _config_wire_names(type(request)) + write_only = _config_write_only_wire_names(type(request)) + self.secrets.add_values( + [getattr(request, name) for name in request.model_fields_set if wire_names[name] in write_only], + source="a write-only agent-config value", + ) + async def agent_config_get(self) -> dict[str, Any]: config = _thaw(self.config) for wire_name in self._write_only_config_fields: @@ -877,12 +909,12 @@ def _atif_events( try: if isinstance(request, TaskEventsTrajectoryRequest): cursor = self.task_trajectories.atif_task_page( - request.task_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES + request.task_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES, scrub=self.secrets.scrub ) unknown = f"Unknown task '{request.task_id}'" else: cursor = self.task_trajectories.atif_context_page( - request.context_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES + request.context_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES, scrub=self.secrets.scrub ) unknown = f"Unknown context '{request.context_id}'" except ValueError as exc: @@ -911,7 +943,7 @@ async def _atif_document( ) -> dict[str, Any]: """A whole atif/1 document: a task read's as it stood when the task ended, with the task's aux log and turn context, or a context read's live page; inline, or uploaded - through the request's grants.""" + through the request's grants, its secrets scrubbed either way.""" served: dict[str, Any] = {} if isinstance(request, (TaskTrajectoryRequest, TaskObjectTrajectoryRequest)): read = self.task_trajectories.atif_task(request.task_id) @@ -931,6 +963,7 @@ async def _atif_document( status_code=404, detail=f"Context '{request.context_id}' has no {ATIF_FORMAT} step to serve yet", ) + document, served = self.secrets.scrub(document), self.secrets.scrub(served) versions = _atif_versions(document) if isinstance(request, (TaskTrajectoryRequest, ContextTrajectoryRequest)): return {"trajectory": document, "format": ATIF_FORMAT, **versions, **served} @@ -1116,6 +1149,8 @@ def _taking_the_control_token( async def lifespan(app: Starlette) -> AsyncIterator[Any]: application.control_token = take_control_token() or application.control_token log_guard(application.control_token) + if application.services.secrets is not None: + application.services.secrets.add(application.control_token, source="the control token") if inner is None: yield None else: @@ -1332,6 +1367,7 @@ async def invoke(request: Request) -> JSONResponse: extension_request = None else: extension_request = request_model.model_validate(payload) + self.services.note_secrets(extension_request) if extension_uri == TRAJECTORY_V1.uri: self.services.check_trajectory_format(extension_request.format) if extension_request.format == ATIF_FORMAT: diff --git a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md index bab883ace..709942e9e 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md +++ b/packages/agentenv-protocol/src/agentenv_protocol/atif/PROFILE.md @@ -23,6 +23,8 @@ to native exactly. - One document per agent per A2A context. Each A2A task starts at a `source: user` step that holds the inbound message, with the task's ids in that step's profile. Steps number from 1 across the whole document. +- A served document leaves out the secrets its agent's SDK knows: each is written `[redacted:]` wherever it + occurs, in any string, the aux log and turn context served with it included. The native log keeps them. - A context's record may span several documents: after an agent instance restarts or drops the context from memory, after a snapshot restore, and when long runs are sealed into segments. They share `session_id`, the first user step of each carries the continuing turn index, and each earlier document names the next in `continued_trajectory_ref`. The worker that stores the earlier diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py new file mode 100644 index 000000000..e1a22c3c8 --- /dev/null +++ b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py @@ -0,0 +1,303 @@ +"""An agent's atif/1 reads leave out every secret its SDK holds or is handed, and every one it registers, each written +``[redacted:]`` wherever it occurs: in the document, the aux log and the turn context, inline, uploaded and in +cursor pages. Native reads keep them, byte for byte.""" +from __future__ import annotations + +import json +import logging +from datetime import datetime, timedelta, timezone +from typing import Any, Callable +from urllib.parse import quote + +import pytest +from starlette.testclient import TestClient +from test_a2a_atif_serving import _ended, _send + +from agentenv_protocol.a2a_agent import ( + CDP_CONFIG_V1, + MCP_CONFIG_V1, + TRAJECTORY_V1, + AgentConfig, + AgentEnvAgent, + AgentIdentity, + TaskRequest, + TaskResult, + TextPart, + TrajectoryState, + Uploaded, + WriteOnly, + a2a_agent, + enable, + framework, +) +from agentenv_protocol.a2a_agent._atif_copy import AtifCopy, TurnStart +from agentenv_protocol.a2a_agent._secrets import Secrets +from agentenv_protocol.a2a_agent.extensions import ClockSyncTimeRequest +from agentenv_protocol.atif import FORMAT, Adapter, atif_adapter, aux, errors_in, native, validate +from agentenv_protocol.transfers import HttpGetGrant, HttpPostPolicyGrant, HttpPutGrant, ReadObject +from agentenv_protocol.types import CONTROL_TOKEN_ENV, CONTROL_TOKEN_HEADER + +NATIVE = "echo-secrets/1" +SECRET = "sk-registered-0123456789" + + +@atif_adapter(native_format=NATIVE, version="1", input_includes_cache=False) +class Echoes(Adapter): + @native(type="say") + def say(self, record: dict[str, Any], turn: Any) -> None: + turn.message(step="said", text=record["text"]) + turn.step(key="said", llm_call_count=1, model_name="toy-model") + + @aux("notes", type="note") + def note(self, record: dict[str, Any], turn: Any) -> None: + turn.message(step="said", text=record["text"]) + + +class ToyConfig(AgentConfig): + api_token: WriteOnly[str | None] = None + + +def _echoing(*, register: str | None = None, atif: bool = True) -> AgentEnvAgent: + """An agent whose turn says its prompt, notes it in an aux record and answers it, so a secret in the prompt is in + every string an atif/1 read serves: the user step, a message, the aux log, the final response, the turn context.""" + trajectory = enable(TRAJECTORY_V1, live=True, native=NATIVE, **({"atif": Echoes} if atif else {})) + + @a2a_agent(identity=AgentIdentity(name="echoes", description="test", version="1"), config=ToyConfig, + extensions=(trajectory, MCP_CONFIG_V1, CDP_CONFIG_V1)) + class Echoing(AgentEnvAgent): + async def run(self, request: TaskRequest) -> TaskResult: + if register is not None: + self.register_secret(register) + prompt = request.parts[0].text + request.trajectory.set_format(NATIVE) + request.trajectory.append({"type": "say", "text": prompt}) + if atif: + request.trajectory.aux("notes", {"type": "note", "text": f"noted {prompt}"}) + return TaskResult.text(f"answer: {prompt}") + + return Echoing() + + +def _grant(name: str) -> dict[str, Any]: + expires = (datetime.now(timezone.utc) + timedelta(hours=1)).isoformat(timespec="seconds").replace("+00:00", "Z") + return {"media_type": "application/json", "max_bytes": 1_000_000, + "write": {"kind": "http-put", "url": f"https://objects.example.test/{name}", "expires_at": expires}} + + +def _reads(client: TestClient, task_id: str, monkeypatch: pytest.MonkeyPatch) -> list[Any]: + """Every atif/1 read of the task and its context: inline, uploaded and paged.""" + uploads: dict[str, bytes] = {} + + async def upload(target, body: bytes) -> Uploaded: + uploads[target.write.url.rsplit("/", 1)[-1]] = body + return Uploaded(size_bytes=len(body)) + + monkeypatch.setattr(framework, "upload", upload) + reads = [ + client.post("/ext/trajectory", json={"task_id": task_id, "format": FORMAT}).json(), + client.post("/ext/trajectory", json={"context_id": "ctx-1", "format": FORMAT}).json(), + client.post("/ext/trajectory", json={"task_id": task_id, "format": FORMAT, "after": 0}).json(), + client.post("/ext/trajectory", json={"context_id": "ctx-1", "format": FORMAT, "after": 0}).json(), + ] + client.post("/ext/trajectory", json={"task_id": task_id, "format": FORMAT, "objects": { + name: _grant(name) for name in ("trajectory", "aux", "turn_context")}}) + return [*reads, *(json.loads(body) for body in uploads.values())] + + +def _native(client: TestClient, task_id: str) -> Any: + return client.post("/ext/trajectory", json={"task_id": task_id}).json()["trajectory"] + + +def _strings(value: Any) -> list[str]: + if isinstance(value, str): + return [value] + if isinstance(value, dict): + return [s for item in value.values() for s in _strings(item)] + if isinstance(value, list): + return [s for item in value for s in _strings(item)] + return [] + + +def _turn(client: TestClient, prompt: str) -> str: + task_id = _send(client, prompt, "m-1") + _ended(client, task_id) + return task_id + + +def _assert_redacted(reads: list[Any], secret: str) -> None: + served = [s for read in reads for s in _strings(read)] + assert not [s for s in served if secret in s] + assert any(f"[redacted:{len(secret)}]" in s for s in served) + + +def test_a_secret_the_agent_registers_is_redacted_in_every_atif_read_and_kept_in_the_native_log( + monkeypatch: pytest.MonkeyPatch) -> None: + with TestClient(_echoing(register=SECRET).create_app()) as client: + task_id = _turn(client, f"the key is {SECRET}") + reads = _reads(client, task_id, monkeypatch) + native_read = _native(client, task_id) + _assert_redacted(reads, SECRET) + document = reads[0]["trajectory"] + assert errors_in(validate(document)) == [] + assert [step["message"] for step in document["steps"]][0] == f"the key is [redacted:{len(SECRET)}]" + assert reads[0]["aux"][0]["record"]["text"] == f"noted the key is [redacted:{len(SECRET)}]" + assert native_read == [{"type": "say", "text": f"the key is {SECRET}"}] + + +def _model_key(monkeypatch: pytest.MonkeyPatch, client: Callable[[], TestClient]) -> tuple[TestClient, str]: + monkeypatch.setenv("LITELLM_API_KEY", "sk-model-key-0123456789") + return client(), "sk-model-key-0123456789" + + +def _model_headers(monkeypatch: pytest.MonkeyPatch, client: Callable[[], TestClient]) -> tuple[TestClient, str]: + monkeypatch.setenv("LITELLM_EXTRA_HEADERS", json.dumps({"X-Gateway-Key": "gw-header-0123456789", + "Content-Type": "application/json"})) + return client(), "gw-header-0123456789" + + +def _control_token(monkeypatch: pytest.MonkeyPatch, client: Callable[[], TestClient]) -> tuple[TestClient, str]: + monkeypatch.setenv(CONTROL_TOKEN_ENV, "control-token-0123456789") + return client(headers={CONTROL_TOKEN_HEADER: "control-token-0123456789"}), "control-token-0123456789" + + +def _write_only_config(monkeypatch: pytest.MonkeyPatch, client: Callable[[], TestClient]) -> tuple[TestClient, str]: + opened = client() + assert opened.post("/ext/agent-config", json={"api_token": "config-token-0123456789"}).status_code == 200 + return opened, "config-token-0123456789" + + +def _mcp_headers(monkeypatch: pytest.MonkeyPatch, client: Callable[[], TestClient]) -> tuple[TestClient, str]: + opened = client() + added = opened.post("/ext/mcp-config", json={"url": "https://gateway.example.test/mcp", "name": "env", + "headers": {"Authorization": "Bearer mcp-token-0123456789"}}) + assert added.status_code == 200, added.text + return opened, "Bearer mcp-token-0123456789" + + +def _cdp_url(monkeypatch: pytest.MonkeyPatch, client: Callable[[], TestClient]) -> tuple[TestClient, str]: + opened = client() + ws_url = "wss://gateway.example.test/browser/web/cdp/cdp-token-0123456789/devtools/browser/1" + added = opened.post("/ext/cdp-config", json={"name": "web", "http_url": "https://gateway.example.test", + "ws_url": ws_url}) + assert added.status_code == 200, added.text + return opened, ws_url + + +@pytest.mark.parametrize("handed", [_model_key, _model_headers, _control_token, _write_only_config, _mcp_headers, + _cdp_url], + ids=["model-key", "model-headers", "control-token", "write-only-config", "mcp-headers", + "cdp-url"]) +def test_a_secret_the_sdk_holds_or_is_handed_is_redacted(monkeypatch: pytest.MonkeyPatch, handed) -> None: + app = None + + def client(**kwargs: Any) -> TestClient: + nonlocal app + app = _echoing().create_app() + return TestClient(app, **kwargs).__enter__() + + opened, secret = handed(monkeypatch, client) + try: + task_id = _turn(opened, f"echo: {secret}") + reads = _reads(opened, task_id, monkeypatch) + assert _native(opened, task_id) == [{"type": "say", "text": f"echo: {secret}"}] + finally: + opened.__exit__(None, None, None) + _assert_redacted(reads, secret) + + +def test_a_presigned_grant_is_redacted_whole_as_a_request_line_names_it_and_by_its_signature() -> None: + secrets = Secrets() + url = "https://bucket.example.test/runs/1/trajectory.json?X-Amz-Signature=abcdef0123456789&X-Amz-Expires=900" + secrets.add_request(ReadObject(media_type="application/json", max_bytes=10, read=HttpGetGrant( + kind="http-get", url=url, expires_at=datetime.now(timezone.utc) + timedelta(hours=1)))) + target = "/runs/1/trajectory.json?X-Amz-Signature=abcdef0123456789&X-Amz-Expires=900" + assert secrets.scrub([url, f"GET {target} HTTP/1.1", "sig abcdef0123456789", f"wrapped {quote(url, safe='')}"]) == [ + f"[redacted:{len(url)}]", f"GET [redacted:{len(target)}] HTTP/1.1", "sig [redacted:16]", + f"wrapped [redacted:{len(quote(url, safe=''))}]"] + + +def test_a_tokened_url_is_redacted_by_its_token_and_plain_paths_and_values_are_left_unwarned( + caplog: pytest.LogCaptureFixture) -> None: + secrets = Secrets() + token = "eyJvcCI6ImdldCJ9.c2lnbmF0dXJlLXRoYXQtaXMtbG9uZw" + expires = datetime.now(timezone.utc) + timedelta(hours=1) + with caplog.at_level(logging.WARNING): + secrets.add_request(HttpGetGrant(kind="http-get", url=f"https://host.example.test:8443/v1/grants/{token}", + expires_at=expires)) + secrets.add_request(HttpPutGrant(kind="http-put", headers={"Content-Type": "application/json"}, + url="https://objects.example.test/runs/trajectory.json?X-Amz-Expires=900", + expires_at=expires)) + text = f"token {token} under /v1/grants and /runs/trajectory.json, as application/json for 900 s" + assert secrets.scrub(text) == text.replace(token, f"[redacted:{len(token)}]") + assert not caplog.records + + +def test_a_signed_upload_form_is_redacted_by_its_signing_fields_alone() -> None: + secrets = Secrets() + form = HttpPostPolicyGrant(kind="http-post-policy", url="https://bucket.example.test/", path_field="key", + file_field="file", headers={"Content-Type": "application/json"}, fields={ + "key": "runs/1/${filename}", "x-amz-algorithm": "AWS4-HMAC-SHA256", + "x-amz-credential": "AKIAEXAMPLE/20261119/us-east-1/s3", "policy": "eyJwb2xpY3kiOnt9", + "x-amz-signature": "0123456789abcdef"}) + secrets.add_request(form) + text = "runs/1/${filename} AWS4-HMAC-SHA256 application/json AKIAEXAMPLE/20261119/us-east-1/s3 eyJwb2xpY3kiOnt9" + assert secrets.scrub(text) == "runs/1/${filename} AWS4-HMAC-SHA256 application/json [redacted:33] [redacted:16]" + + +def test_a_clock_followers_read_token_is_redacted_and_a_bare_cdp_origin_is_not() -> None: + secrets = Secrets() + secrets.add_request(ClockSyncTimeRequest(env_get_time_url="https://gw.example.test/clock", + read_token="clock-token-0123456789")) + assert secrets.scrub("token clock-token-0123456789 at https://gw.example.test/clock") == ( + "token [redacted:22] at https://gw.example.test/clock") + + +def test_the_longest_secret_wins_and_an_escaped_one_is_redacted_too() -> None: + secrets = Secrets() + secrets.add("abcdefgh", source="test") + secrets.add("abcdefgh-ijkl", source="test") + secrets.add('pa"ss-wörd-0123', source="test") + assert secrets.scrub({"a": ["abcdefgh-ijkl and abcdefgh"], "b": json.dumps({"p": 'pa"ss-wörd-0123'})}) == { + "a": ["[redacted:13] and [redacted:8]"], "b": '{"p": "[redacted:21]"}'} + + +def test_a_short_secret_is_left_with_one_warning_per_source(caplog: pytest.LogCaptureFixture) -> None: + secrets = Secrets() + with caplog.at_level(logging.WARNING): + for _ in range(2): + secrets.add("short", source="the agent") + assert secrets.scrub("a short note") == "a short note" + assert sum("shorter than 8 characters" in record.message for record in caplog.records) == 1 + assert "short" not in [record.args for record in caplog.records] + + +def test_a_cursor_page_counts_its_bytes_as_it_serves_them() -> None: + copy = AtifCopy(Echoes, "ctx-1") + copy.start("t1", 0, TurnStart(message_id=None, parts=(TextPart(text="hi"),), agent_name="toy", agent_version="1", + agent_model=None)) + for text in ("one", "two", "three"): + copy.native("t1", {"type": "say", "text": text}) + copy.end("t1", state=TrajectoryState.COMPLETED.value, final=(TextPart(text="done"),)) + plain = copy.page(0, 10, 10_000) + budget = sum(len(json.dumps(step)) for step in plain.steps[:2]) + assert len(copy.page(0, 10, budget).steps) == 2 + padded = copy.page(0, 10, budget, scrub=lambda value: _pad(value)) + assert len(padded.steps) == 1 and padded.has_more + + +def _pad(value: Any) -> Any: + if isinstance(value, str): + return value + "x" * 200 + if isinstance(value, dict): + return {key: _pad(item) for key, item in value.items()} + if isinstance(value, list): + return [_pad(item) for item in value] + return value + + +def test_an_agent_that_serves_no_atif_registers_nothing_and_registering_before_its_app_is_refused() -> None: + with TestClient(_echoing(register=SECRET, atif=False).create_app()) as client: + task_id = _turn(client, f"the key is {SECRET}") + assert _native(client, task_id) == [{"type": "say", "text": f"the key is {SECRET}"}] + with pytest.raises(RuntimeError, match="after create_app"): + _echoing().register_secret(SECRET) diff --git a/src/agent_env/agents/AGENTS.md b/src/agent_env/agents/AGENTS.md index 3555ae2e2..31518dfae 100644 --- a/src/agent_env/agents/AGENTS.md +++ b/src/agent_env/agents/AGENTS.md @@ -147,7 +147,9 @@ must be in it. It needs a protocol floor that has `native`. A context read you b `format` in its response. `atif=` there, an `@atif_adapter` class for that native format, has the SDK serve `atif/1` too, built from your log as you append it: write the adapter (`agentenv_protocol.atif`, its `PROFILE.md`), feed records that aren't in the native log, such as hooks' notes, with -`request.trajectory.aux(name, record)`, and append or return a native trajectory, not both. +`request.trajectory.aux(name, record)`, and append or return a native trajectory, not both. Its reads leave out the +secrets the SDK holds and is handed (the model key, write-only config, MCP and CDP credentials, grants); register any +other with `self.register_secret(value)`, in `run` or later, and the SDK writes it `[redacted:]` there. Reference: `enable(TRAJECTORY_V1, live=True, ...)`, `ClaudeCodeAgent.run` passing `event_callback=request.trajectory.append`, and `get_context_trajectory` / `upload_context_trajectory`. A runtime diff --git a/tst/integration/task_step/test_prompt_agent_live_trajectory_local.py b/tst/integration/task_step/test_prompt_agent_live_trajectory_local.py index 04d115a30..1b6f44491 100644 --- a/tst/integration/task_step/test_prompt_agent_live_trajectory_local.py +++ b/tst/integration/task_step/test_prompt_agent_live_trajectory_local.py @@ -4,8 +4,9 @@ in more than one chunk, and its chunks join to that turn's final trajectory; each turn names the one after it, and the last none. The echo agent declares its native format and an ATIF adapter, so its card offers both; its native reads name their format, its atif/1 reads are valid ATIF, and a read naming another format is refused with a code agent-env -reads. A snapshot of it carries its atif/1 copy's turn count to the fresh agent it is restored into. Needs Docker and a -throwaway local registry.""" +reads. A snapshot of it carries its atif/1 copy's turn count to the fresh agent it is restored into, and its atif/1 +reads leave out the model key a command it runs prints, which its native read keeps. Needs Docker and a throwaway local +registry.""" import json import re @@ -226,3 +227,32 @@ async def test_a_snapshot_carries_the_turn_count_to_the_fresh_agent_it_is_restor assert [(user["turn"], user["context_id"]) for user in after_users] == [(2, restored)] assert (after["session_id"], [step["message"] for step in after["steps"]]) == (restored, ["three", "Echo: three"]) assert after["trajectory_id"] != before["trajectory_id"] + + +@pytest.mark.asyncio +async def test_a_model_key_a_command_prints_is_redacted_in_atif_and_kept_in_the_native_log(local_registry): + suffix = uuid.uuid4().hex[:8] + context_id = f"scrub-{suffix}" + agent = put_test_agent(f"scrub-agent-{suffix}", env={"LITELLM_API_KEY": f"sk-echo-{uuid.uuid4().hex}"}) + task = Task.put(id=f"scrub-{suffix}", steps=[ + _deploy(agent, "solver"), + PromptAgentTaskStep(id="ask", version=None, prompt_id="ask", agent_name="solver", + prompt="run printenv LITELLM_API_KEY", context_id=context_id), + ]) + + context = await task.run() + + assert not context.metadata.get("failed_steps"), context.metadata.get("failed_steps") + [deployed] = context.deployed_agents + url = deployed.a2a_url + A2AAgent.find_extension(deployed.a2a_card, A2AAgent.EXT_TRAJECTORY)["params"]["endpoint"] + async with httpx.AsyncClient(timeout=30, headers=deployed.control_headers) as client: + page = (await client.post(url, json={"context_id": context_id, "after": 0})).json() + native = (await client.post(url, json={"task_id": page["task_id"]})).json()["trajectory"] + atif = (await client.post(url, json={"task_id": page["task_id"], "format": ATIF})).json() + # The key the agent's sandbox holds, as the command printed it: the deploy may resolve one of its own. + [echo] = [event for event in native if event["type"] == "echo"] + key = re.search(r"ran printenv LITELLM_API_KEY: (\S+)", echo["output"]).group(1) + assert len(key) >= 8 + served = json.dumps(atif) + assert key not in served and f"[redacted:{len(key)}]" in served + assert errors_in(validate(atif["trajectory"])) == [] diff --git a/tst/util/a2a_test_agent.py b/tst/util/a2a_test_agent.py index cca089e53..275c5a32f 100644 --- a/tst/util/a2a_test_agent.py +++ b/tst/util/a2a_test_agent.py @@ -41,9 +41,10 @@ def build_test_agent_image(artifact_id: str) -> DockerImageArtifact: _NO_MODEL_ENV = {"LITELLM_API_KEY": "unused", "LITELLM_BASE_URL": "http://unused.invalid"} -def put_test_agent(agent_id: str) -> A2AAgent: +def put_test_agent(agent_id: str, *, env: dict[str, str] | None = None) -> A2AAgent: + """The echo agent, its environment ``env`` over the stand-in model variables.""" return A2AAgent.put( id=agent_id, docker_image_artifact=build_test_agent_image(f"{agent_id}-image"), - default_env_vars=_NO_MODEL_ENV, + default_env_vars={**_NO_MODEL_ENV, **(env or {})}, ) From aa7e84ee9c310a653c3f5dd796b191d31cd8c082 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 12:37:08 -0800 Subject: [PATCH 2/8] fix(a2a-agent): scrub mapping keys and non-ASCII JSON, and match secrets as a trie built once per change A secret used as a mapping key, or written JSON-escaped without ASCII escapes as an inbound DataPart's compact JSON is, was served as it was. Keys are scrubbed too, and each secret's non-ASCII JSON form is matched. Adding a secret no longer rebuilds the match: it is compiled when a read next needs it, as a prefix trie, so a call that hands the agent a grant per file, or a run that accumulates thousands, compiles once and scans no slower. Co-Authored-By: Claude Opus 5.5 --- .../agentenv_protocol/a2a_agent/_secrets.py | 54 +++++++++++++++---- .../tests/test_a2a_atif_scrubbing.py | 50 +++++++++++++++++ 2 files changed, 94 insertions(+), 10 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py index c66f8f65c..66f39ac74 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py @@ -38,12 +38,16 @@ class Secrets: """The values an agent's atif/1 reads leave out, each written ``[redacted:]`` wherever it occurs, in its raw, - JSON-escaped and percent-encoded forms. Safe to add to from the agent's threads while the loop scrubs.""" + JSON-escaped (ASCII or not) and percent-encoded forms. Safe to add to from the agent's threads while the loop + scrubs. The match is compiled as a prefix trie, once per change and when a read needs it, so a call that hands the + agent a grant per file, or a run that accumulates thousands, costs neither a rebuild per secret nor a slower + scan.""" def __init__(self) -> None: self._lock = threading.Lock() self._forms: set[str] = set() self._pattern: re.Pattern[str] | None = None + self._stale = False self._short: set[str] = set() def add(self, value: str | SecretStr | None, *, source: str, warn: bool = True) -> None: @@ -58,13 +62,11 @@ def add(self, value: str | SecretStr | None, *, source: str, warn: bool = True) logger.warning("a secret from %s is shorter than %d characters, so atif/1 reads don't scrub it", source, MIN_SECRET_LENGTH) return - forms = {text, json.dumps(text)[1:-1], quote(text, safe="")} + forms = {text, json.dumps(text)[1:-1], json.dumps(text, ensure_ascii=False)[1:-1], quote(text, safe="")} with self._lock: - if forms <= self._forms: - return - self._forms |= forms - ordered = sorted(self._forms, key=len, reverse=True) - self._pattern = re.compile("|".join(re.escape(form) for form in ordered)) + if not forms <= self._forms: + self._forms |= forms + self._stale = True def add_all(self, values: Iterable[str | SecretStr | None], *, source: str, warn: bool = True) -> None: for value in values: @@ -103,21 +105,53 @@ def add_values(self, value: Any, *, source: str) -> None: self.add_all(_strings(value), source=source) def scrub(self, value: T) -> T: - """``value`` with every secret in its strings, its mappings' values and its lists' items redacted.""" - pattern = self._pattern + """``value`` with every secret redacted in its strings: its mappings' keys and values and its lists' items.""" + pattern = self._match() return value if pattern is None else _scrub(value, pattern) + def _match(self) -> re.Pattern[str] | None: + with self._lock: + if self._stale: + self._pattern = re.compile(_trie(self._forms)) + self._stale = False + return self._pattern + def _scrub(value: Any, pattern: re.Pattern[str]) -> Any: if isinstance(value, str): return pattern.sub(lambda match: f"[redacted:{len(match.group(0))}]", value) if isinstance(value, dict): - return {key: _scrub(item, pattern) for key, item in value.items()} + return {_scrub(key, pattern): _scrub(item, pattern) for key, item in value.items()} if isinstance(value, list): return [_scrub(item, pattern) for item in value] return value +def _trie(forms: Iterable[str]) -> str: + """One expression matching each of ``forms``, the longest at any position: a prefix trie, whose shared prefixes + are matched once, with each unbranching run written as one literal, so its nesting is its branching.""" + root: dict[str, Any] = {} + for form in forms: + node = root + for char in form: + node = node.setdefault(char, {}) + node[""] = {} + return _branch(root) + + +def _branch(node: dict[str, Any]) -> str: + run: list[str] = [] + while len(node) == 1 and "" not in node: + [(char, node)] = node.items() + run.append(re.escape(char)) + children = sorted(char for char in node if char) + if not children: + return "".join(run) + group = "(?:" + "|".join(re.escape(char) + _branch(node[char]) for char in children) + ")" + # An end here as well: the longer match first, the end if it fails. + return "".join(run) + (f"{group}?" if "" in node else group) + + def _models(value: Any) -> Iterator[BaseModel]: """``value`` and every model it holds, in fields, lists and mappings.""" if isinstance(value, BaseModel): diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py index e1a22c3c8..b11fbc566 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py @@ -5,6 +5,8 @@ import json import logging +import random +import re from datetime import datetime, timedelta, timezone from typing import Any, Callable from urllib.parse import quote @@ -31,6 +33,7 @@ framework, ) from agentenv_protocol.a2a_agent._atif_copy import AtifCopy, TurnStart +from agentenv_protocol.a2a_agent import _secrets from agentenv_protocol.a2a_agent._secrets import Secrets from agentenv_protocol.a2a_agent.extensions import ClockSyncTimeRequest from agentenv_protocol.atif import FORMAT, Adapter, atif_adapter, aux, errors_in, native, validate @@ -261,6 +264,53 @@ def test_the_longest_secret_wins_and_an_escaped_one_is_redacted_too() -> None: "a": ["[redacted:13] and [redacted:8]"], "b": '{"p": "[redacted:21]"}'} +def test_a_secret_is_redacted_in_mapping_keys_too() -> None: + secrets = Secrets() + secrets.add(SECRET, source="test") + assert secrets.scrub({SECRET: 1, "nested": [{f"key {SECRET}": SECRET}]}) == { + f"[redacted:{len(SECRET)}]": 1, "nested": [{f"key [redacted:{len(SECRET)}]": f"[redacted:{len(SECRET)}]"}]} + + +def test_a_non_ascii_secret_in_an_inbound_data_part_is_redacted(monkeypatch: pytest.MonkeyPatch) -> None: + secret = 'pä"ss-wörd-0123' + with TestClient(_echoing(register=secret).create_app()) as client: + task_id = _send(client, "hello", "m-1", extra_parts=[{"kind": "data", "data": {"password": secret}}]) + _ended(client, task_id) + reads = _reads(client, task_id, monkeypatch) + served = [text for read in reads for text in _strings(read)] + assert not [text for text in served if "ss-wörd-0123" in text or "ss-w\\u00f6rd" in text] + assert any('{"password":"[redacted:16]"}' in text for text in served) + + +def test_the_trie_matches_what_a_longest_first_alternation_does() -> None: + rng = random.Random(7) + alphabet = "ab/?=-ü" + forms = {"".join(rng.choice(alphabet) for _ in range(rng.randint(8, 14))) for _ in range(60)} + forms |= {form[:9] for form in list(forms)[:20]} + naive = re.compile("|".join(re.escape(form) for form in sorted(forms, key=len, reverse=True))) + trie = re.compile(_secrets._trie(forms)) + for _ in range(300): + text = "".join(rng.choice(alphabet + "xyz ") for _ in range(rng.randint(0, 80))) + assert trie.sub("#", text) == naive.sub("#", text) + + +def test_many_grants_compile_once_when_a_read_needs_them(monkeypatch: pytest.MonkeyPatch) -> None: + compiled = [] + trie = _secrets._trie + monkeypatch.setattr(_secrets, "_trie", lambda forms: compiled.append(len(forms)) or trie(forms)) + secrets = Secrets() + expires = datetime.now(timezone.utc) + timedelta(hours=1) + urls = [f"https://bucket.example.test/skills/s/file-{n}.md?X-Amz-Signature={n:024d}" for n in range(3000)] + secrets.add_request(ReadObject(media_type="text/markdown", max_bytes=10, read=HttpGetGrant( + kind="http-get", url=urls[0], expires_at=expires))) + for url in urls[1:]: + secrets.add_request(HttpGetGrant(kind="http-get", url=url, expires_at=expires)) + assert compiled == [] + text = " ".join(["fetched", urls[1234], "and", "x" * 50_000]) + assert secrets.scrub(text).startswith(f"fetched [redacted:{len(urls[1234])}] and") + assert secrets.scrub("again") == "again" and len(compiled) == 1 + + def test_a_short_secret_is_left_with_one_warning_per_source(caplog: pytest.LogCaptureFixture) -> None: secrets = Secrets() with caplog.at_level(logging.WARNING): From 95c509232cc0aeb84c892802bf15ecfd76994287 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 14:36:02 -0800 Subject: [PATCH 3/8] fix(a2a-agent): tell credentials by their names, so ordinary words aren't redacted Every query value of a presigned URL was registered, so AWS4-HMAC-SHA256 and the signing date were redacted wherever an agent met them, and every string in a write-only mapping was, so pi's model_params had words like "priority" redacted and short ones warned about. One rule now tells a credential by its name (signature, credential, token, key, password, auth, policy, ...) for query parameters, a signed form's fields and the keys of a write-only mapping, taking everything below a credential-like key; a write-only string is still taken whole, and a grant's URL and request line still are. Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 11 ++-- .../agentenv_protocol/a2a_agent/_secrets.py | 52 +++++++++++++------ .../agentenv_protocol/a2a_agent/framework.py | 14 +++-- .../tests/test_a2a_atif_scrubbing.py | 25 +++++++-- 4 files changed, 69 insertions(+), 33 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 40656289a..2f60423b9 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1673,11 +1673,14 @@ what they serve. The SDK knows: - its control token, and the model credentials in its environment: `LITELLM_API_KEY` and the values of `LITELLM_EXTRA_HEADERS`; -- write-only agent-config values; -- an MCP registration's header and query values, and a CDP endpoint's header - values and its URLs, unless one is a bare origin; +- write-only agent-config values: a string whole, and in a mapping what a + credential-like key names (`Authorization`, `api_key`, `token`, `password`, + ...), so a mapping of sampling parameters keeps its ordinary words; +- an MCP registration's header values and credential-like query values, and a + CDP endpoint's header values and its URLs, unless one is a bare origin; - every transfer grant an extension call hands the agent: its URL whole, its - path and query as a request line names them, its query values, its headers + path and query as a request line names them, its credential-like query + values (`X-Amz-Signature` is one, `X-Amz-Algorithm` isn't), its headers other than `Content-Type` and the like, and a signed upload form's signing fields; - a clock follower's read token; diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py index 66f39ac74..02bcdfe35 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py @@ -28,8 +28,15 @@ MODEL_HEADERS_ENV = "LITELLM_EXTRA_HEADERS" #: Header names whose values describe a request rather than authorize it. _PLAIN_HEADERS = frozenset({"accept", "content-encoding", "content-length", "content-type", "user-agent"}) -#: Words in a signed upload form's field names that mark the values that sign it. -_SIGNING_FIELDS = ("policy", "signature", "credential", "token", "accesskey", "accessid") +#: The words of a name (a query parameter, a signed form's field, a key in a write-only mapping) that mark its value as a +#: credential, and the endings that do: ``X-Amz-Signature`` and Azure's ``sig`` are, ``X-Amz-Algorithm``, ``X-Amz-Date`` +#: and ``X-Amz-SignedHeaders`` aren't, so ``AWS4-HMAC-SHA256`` is left in an agent's text. +_CREDENTIAL_WORDS = frozenset({ + "auth", "authorization", "bearer", "cookie", "credential", "credentials", "jwt", "key", "passwd", "password", + "policy", "pwd", "secret", "sig", "signature", "token", "accessid", "googleaccessid", "awsaccesskeyid", +}) +_CREDENTIAL_ENDINGS = ("key", "token", "secret", "password", "signature", "credential") +_NAME_WORD = re.compile(r"[a-z0-9]+") #: A path segment a URL with no query can carry its credential in, as a grant server's signed token. _TOKEN_SEGMENT = re.compile(r"[A-Za-z0-9_.=~+-]{16,}") @@ -101,8 +108,10 @@ def add_request(self, request: BaseModel | None) -> None: self.add(item.read_token, source="a clock follower's read token") def add_values(self, value: Any, *, source: str) -> None: - """Every string ``value`` holds, in fields, lists and mappings, as a write-only config value may.""" - self.add_all(_strings(value), source=source) + """The credentials a write-only config value holds: a string or list of strings whole, and in a mapping or a model + only what a credential-like key names (and everything below it), so a write-only mapping of sampling parameters, + as pi's ``model_params`` is, doesn't have ``priority`` or a provider's name redacted wherever it occurs.""" + self.add_all(_credentials(value, whole=not isinstance(value, (Mapping, BaseModel))), source=source) def scrub(self, value: T) -> T: """``value`` with every secret redacted in its strings: its mappings' keys and values and its lists' items.""" @@ -166,18 +175,26 @@ def _models(value: Any) -> Iterator[BaseModel]: yield from _models(item) -def _strings(value: Any) -> Iterator[str | SecretStr]: +def _credentials(value: Any, *, whole: bool) -> Iterator[str | SecretStr]: + """The strings ``value`` holds that are credentials: all of them when ``whole`` (a write-only string field, or what a + credential-like key names), else those a credential-like key or field name marks, and everything below it.""" if isinstance(value, (str, SecretStr)): - yield value - elif isinstance(value, BaseModel): - for name in type(value).model_fields: - yield from _strings(getattr(value, name)) + if whole: + yield value elif isinstance(value, (list, tuple, set)): for item in value: - yield from _strings(item) + yield from _credentials(item, whole=whole) + elif isinstance(value, BaseModel): + for name in type(value).model_fields: + yield from _credentials(getattr(value, name), whole=whole or _names_credential(name)) elif isinstance(value, Mapping): - for item in value.values(): - yield from _strings(item) + for key, item in value.items(): + yield from _credentials(item, whole=whole or isinstance(key, str) and _names_credential(key)) + + +def _names_credential(name: str) -> bool: + words = _NAME_WORD.findall(name.lower()) + return any(word in _CREDENTIAL_WORDS or word.endswith(_CREDENTIAL_ENDINGS) for word in words) def _grant_secrets(grant: HttpGetGrant | HttpPutGrant | HttpPostPolicyGrant) -> list[str]: @@ -185,15 +202,15 @@ def _grant_secrets(grant: HttpGetGrant | HttpPutGrant | HttpPostPolicyGrant) -> secrets = _header_values(grant.headers) if isinstance(grant, HttpPostPolicyGrant): secrets += [value for name, value in grant.fields.items() - if name != grant.path_field and any(word in name.lower() for word in _SIGNING_FIELDS)] + if name != grant.path_field and _names_credential(name)] return secrets def _url_secrets(url: str) -> list[str]: """A URL that can carry a credential, in its path, query or user info: whole, and the part that carries it. A - presigned URL keeps its signature in its query, so its query's values and its path and query as a request line - names them (``curl -v`` prints that); a URL with no query keeps its token in a long path segment. A bare origin - carries none.""" + presigned URL keeps its signature in its query, so its credential-like query values and its path and query as a + request line names them (``curl -v`` prints that); a URL with no query keeps its token in a long path segment. A + bare origin carries none.""" parts = urlsplit(url) if not parts.path.strip("/") and not parts.query and parts.password is None: return [] @@ -205,7 +222,8 @@ def _url_secrets(url: str) -> list[str]: def _query_values(url: str) -> list[str]: - return [value for _, value in parse_qsl(urlsplit(url).query)] + """The values of a URL's credential-like query parameters: a signature, a credential, a token, a key.""" + return [value for name, value in parse_qsl(urlsplit(url).query) if _names_credential(name)] def _header_values(headers: Mapping[str, Any] | None) -> list[str]: diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index 04daa1c54..dbd91bdb5 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -597,10 +597,9 @@ def __init__( self.secrets = Secrets() if atif is not None else None if self.secrets is not None: self.secrets.add_environment() - self.secrets.add_values( - [value for name, value in self.config_defaults.items() if name in self._write_only_config_fields], - source="a write-only agent-config default", - ) + for name, value in self.config_defaults.items(): + if name in self._write_only_config_fields: + self.secrets.add_values(value, source="a write-only agent-config default") self._context_sessions = _BoundedContextSessions() self.skills: list[Mapping[str, Any]] = [] self.identity_skills: dict[str, str] = {} @@ -754,10 +753,9 @@ def note_secrets(self, request: Any) -> None: if isinstance(request, AgentConfig): wire_names = _config_wire_names(type(request)) write_only = _config_write_only_wire_names(type(request)) - self.secrets.add_values( - [getattr(request, name) for name in request.model_fields_set if wire_names[name] in write_only], - source="a write-only agent-config value", - ) + for name in request.model_fields_set: + if wire_names[name] in write_only: + self.secrets.add_values(getattr(request, name), source="a write-only agent-config value") async def agent_config_get(self) -> dict[str, Any]: config = _thaw(self.config) diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py index b11fbc566..aff497513 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py @@ -58,6 +58,7 @@ def note(self, record: dict[str, Any], turn: Any) -> None: class ToyConfig(AgentConfig): api_token: WriteOnly[str | None] = None + model_params: WriteOnly[dict[str, Any] | None] = None def _echoing(*, register: str | None = None, atif: bool = True) -> AgentEnvAgent: @@ -210,12 +211,15 @@ def client(**kwargs: Any) -> TestClient: def test_a_presigned_grant_is_redacted_whole_as_a_request_line_names_it_and_by_its_signature() -> None: secrets = Secrets() - url = "https://bucket.example.test/runs/1/trajectory.json?X-Amz-Signature=abcdef0123456789&X-Amz-Expires=900" + url = ("https://bucket.example.test/runs/1/trajectory.json?X-Amz-Algorithm=AWS4-HMAC-SHA256" + "&X-Amz-Date=20261119T204500Z&X-Amz-Signature=abcdef0123456789&X-Amz-Expires=900") secrets.add_request(ReadObject(media_type="application/json", max_bytes=10, read=HttpGetGrant( kind="http-get", url=url, expires_at=datetime.now(timezone.utc) + timedelta(hours=1)))) - target = "/runs/1/trajectory.json?X-Amz-Signature=abcdef0123456789&X-Amz-Expires=900" - assert secrets.scrub([url, f"GET {target} HTTP/1.1", "sig abcdef0123456789", f"wrapped {quote(url, safe='')}"]) == [ - f"[redacted:{len(url)}]", f"GET [redacted:{len(target)}] HTTP/1.1", "sig [redacted:16]", + target = url.removeprefix("https://bucket.example.test") + plain = "signed with AWS4-HMAC-SHA256 at 20261119T204500Z" + assert secrets.scrub([url, f"GET {target} HTTP/1.1", "sig abcdef0123456789", plain, + f"wrapped {quote(url, safe='')}"]) == [ + f"[redacted:{len(url)}]", f"GET [redacted:{len(target)}] HTTP/1.1", "sig [redacted:16]", plain, f"wrapped [redacted:{len(quote(url, safe=''))}]"] @@ -235,6 +239,19 @@ def test_a_tokened_url_is_redacted_by_its_token_and_plain_paths_and_values_are_l assert not caplog.records +def test_a_write_only_mapping_is_redacted_by_its_credentials_alone(monkeypatch: pytest.MonkeyPatch, + caplog: pytest.LogCaptureFixture) -> None: + params = {"service_tier": "priority", "thinking": {"type": "enabled"}, + "extra_headers": {"Authorization": "Bearer params-0123456789", "X-Title": "toy agent app"}, + "auth": {"user": "bob-the-builder"}} + with caplog.at_level(logging.WARNING), TestClient(_echoing().create_app()) as client: + assert client.post("/ext/agent-config", json={"model_params": params}).status_code == 200 + task_id = _turn(client, "priority enabled toy agent app Bearer params-0123456789 bob-the-builder") + document = client.post("/ext/trajectory", json={"task_id": task_id, "format": FORMAT}).json()["trajectory"] + assert document["steps"][0]["message"] == "priority enabled toy agent app [redacted:24] [redacted:15]" + assert not [record for record in caplog.records if "shorter than" in record.message] + + def test_a_signed_upload_form_is_redacted_by_its_signing_fields_alone() -> None: secrets = Secrets() form = HttpPostPolicyGrant(kind="http-post-policy", url="https://bucket.example.test/", path_field="key", From d48a03c3aeffe42a9a1d4f4c4ef5885fb9855965 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 14:48:46 -0800 Subject: [PATCH 4/8] refactor(a2a-agent): name the token-segment length a URL's credential needs Co-Authored-By: Claude Opus 5.5 --- .../src/agentenv_protocol/a2a_agent/_secrets.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py index 02bcdfe35..126457de7 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py @@ -37,8 +37,10 @@ }) _CREDENTIAL_ENDINGS = ("key", "token", "secret", "password", "signature", "credential") _NAME_WORD = re.compile(r"[a-z0-9]+") -#: A path segment a URL with no query can carry its credential in, as a grant server's signed token. -_TOKEN_SEGMENT = re.compile(r"[A-Za-z0-9_.=~+-]{16,}") +#: How long a path segment of a URL with no query must be to be taken as its credential, as a grant server's signed +#: token is: longer than an ordinary path's words, unlike ``MIN_SECRET_LENGTH``, which bounds what is scrubbed at all. +MIN_TOKEN_SEGMENT_LENGTH = 16 +_TOKEN_SEGMENT = re.compile(rf"[A-Za-z0-9_.=~+-]{{{MIN_TOKEN_SEGMENT_LENGTH},}}") T = TypeVar("T") From ff69a2c5af2f6e85a1f81bd2405d347154e20e78 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 15:13:02 -0800 Subject: [PATCH 5/8] fix(a2a-agent): a grant adds only the parts of its URL that carry its credential Each grant registered its whole URL and its path and query, about 4,700 unique characters for a 1,200-character S3 URL with a session token, so 500 grants made the trie 2.4M characters: a 5.2 s compile on the event loop and 410 MiB after each new grant. A URL now gives its credential-like query values, or the token-like path segments of a URL with no query, and its password: every copy of the URL holds them, and the session token and access key a role signs every grant with are one secret each, so a grant adds its signature. 500 such grants compile in 0.07 s and 6 MiB. Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 14 +++++----- .../agentenv_protocol/a2a_agent/_secrets.py | 18 ++++++------- .../tests/test_a2a_atif_scrubbing.py | 26 ++++++++++++++----- 3 files changed, 36 insertions(+), 22 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 2f60423b9..b6baf82cb 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1677,12 +1677,14 @@ what they serve. The SDK knows: credential-like key names (`Authorization`, `api_key`, `token`, `password`, ...), so a mapping of sampling parameters keeps its ordinary words; - an MCP registration's header values and credential-like query values, and a - CDP endpoint's header values and its URLs, unless one is a bare origin; -- every transfer grant an extension call hands the agent: its URL whole, its - path and query as a request line names them, its credential-like query - values (`X-Amz-Signature` is one, `X-Amz-Algorithm` isn't), its headers - other than `Content-Type` and the like, and a signed upload form's signing - fields; + CDP endpoint's header values and the token in its URLs; +- every transfer grant an extension call hands the agent: the parts of its URL + that carry the credential (a presigned URL's credential-like query values, + `X-Amz-Signature` but not `X-Amz-Algorithm`; a token-like path segment of a + URL with no query; a password), its headers other than `Content-Type` and the + like, and a signed upload form's signing fields. Every copy of the URL holds + those parts, so a URL an agent prints keeps its host and path and loses its + signature; - a clock follower's read token; - whatever the agent registers with `self.register_secret(value)`, once its app exists (in `run`, say). diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py index 126457de7..a03674130 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py @@ -93,7 +93,8 @@ def add_environment(self, environ: Mapping[str, str] | None = None) -> None: self.add_all(_header_values(headers), source=MODEL_HEADERS_ENV) def add_request(self, request: BaseModel | None) -> None: - """Every secret an extension call hands the agent: its grants' URLs, query values, headers and signing fields, + """Every secret an extension call hands the agent: the parts of its grants' URLs that carry their credentials, + their headers and signing fields, an MCP or CDP registration's credentials and a clock follower's read token, wherever the request holds them.""" for item in _models(request): if isinstance(item, (HttpGetGrant, HttpPutGrant, HttpPostPolicyGrant)): @@ -209,18 +210,17 @@ def _grant_secrets(grant: HttpGetGrant | HttpPutGrant | HttpPostPolicyGrant) -> def _url_secrets(url: str) -> list[str]: - """A URL that can carry a credential, in its path, query or user info: whole, and the part that carries it. A - presigned URL keeps its signature in its query, so its credential-like query values and its path and query as a - request line names them (``curl -v`` prints that); a URL with no query keeps its token in a long path segment. A - bare origin carries none.""" + """The parts of a URL that carry its credential: a presigned URL's credential-like query values, the token-like path + segments of a URL with no query, as a grant server's, and its password. Every copy of the URL, whole or as a + request line, holds them, so redacting them is enough; the rest (its host, its path, ``X-Amz-Algorithm``) isn't + secret, and leaving it keeps each grant's share of the match to its signature: the session token and access key a + role signs every grant with are each one secret.""" parts = urlsplit(url) - if not parts.path.strip("/") and not parts.query and parts.password is None: - return [] if parts.query: - carried = [f"{parts.path}?{parts.query}", *_query_values(url)] + carried = _query_values(url) else: carried = [segment for segment in parts.path.split("/") if _TOKEN_SEGMENT.fullmatch(segment)] - return [url, *carried, *([parts.password] if parts.password else [])] + return [*carried, *([parts.password] if parts.password else [])] def _query_values(url: str) -> list[str]: diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py index aff497513..98d5b466c 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py @@ -184,7 +184,7 @@ def _cdp_url(monkeypatch: pytest.MonkeyPatch, client: Callable[[], TestClient]) added = opened.post("/ext/cdp-config", json={"name": "web", "http_url": "https://gateway.example.test", "ws_url": ws_url}) assert added.status_code == 200, added.text - return opened, ws_url + return opened, "cdp-token-0123456789" @pytest.mark.parametrize("handed", [_model_key, _model_headers, _control_token, _write_only_config, _mcp_headers, @@ -209,7 +209,7 @@ def client(**kwargs: Any) -> TestClient: _assert_redacted(reads, secret) -def test_a_presigned_grant_is_redacted_whole_as_a_request_line_names_it_and_by_its_signature() -> None: +def test_a_presigned_grant_is_redacted_by_its_signature_wherever_it_is_printed() -> None: secrets = Secrets() url = ("https://bucket.example.test/runs/1/trajectory.json?X-Amz-Algorithm=AWS4-HMAC-SHA256" "&X-Amz-Date=20261119T204500Z&X-Amz-Signature=abcdef0123456789&X-Amz-Expires=900") @@ -217,10 +217,8 @@ def test_a_presigned_grant_is_redacted_whole_as_a_request_line_names_it_and_by_i kind="http-get", url=url, expires_at=datetime.now(timezone.utc) + timedelta(hours=1)))) target = url.removeprefix("https://bucket.example.test") plain = "signed with AWS4-HMAC-SHA256 at 20261119T204500Z" - assert secrets.scrub([url, f"GET {target} HTTP/1.1", "sig abcdef0123456789", plain, - f"wrapped {quote(url, safe='')}"]) == [ - f"[redacted:{len(url)}]", f"GET [redacted:{len(target)}] HTTP/1.1", "sig [redacted:16]", plain, - f"wrapped [redacted:{len(quote(url, safe=''))}]"] + printed = [url, f"GET {target} HTTP/1.1", "sig abcdef0123456789", plain, f"wrapped {quote(url, safe='')}"] + assert secrets.scrub(printed) == [text.replace("abcdef0123456789", "[redacted:16]") for text in printed] def test_a_tokened_url_is_redacted_by_its_token_and_plain_paths_and_values_are_left_unwarned( @@ -252,6 +250,20 @@ def test_a_write_only_mapping_is_redacted_by_its_credentials_alone(monkeypatch: assert not [record for record in caplog.records if "shorter than" in record.message] +def test_a_roles_grants_add_their_signatures_alone() -> None: + """Every grant a role signs carries the same session token and access key: each is one secret, so a grant's share of + the match is its signature, however long its URL.""" + secrets = Secrets() + token = "IQoJb3JpZ2luX2VjEJr" + "x" * 800 + expires = datetime.now(timezone.utc) + timedelta(hours=1) + for n in range(200): + secrets.add_request(HttpPutGrant(kind="http-put", expires_at=expires, url=( + f"https://store.s3.ca-central-1.amazonaws.com/runs/{n}/trajectory.json?X-Amz-Algorithm=AWS4-HMAC-SHA256" + "&X-Amz-Credential=ASIAEXAMPLE0123%2F20261119%2Fca-central-1%2Fs3%2Faws4_request" + f"&X-Amz-Security-Token={token}&X-Amz-Signature={n:064x}"))) + assert sum(map(len, secrets._forms)) < 200 * 64 + 5 * (len(token) + 80) + + def test_a_signed_upload_form_is_redacted_by_its_signing_fields_alone() -> None: secrets = Secrets() form = HttpPostPolicyGrant(kind="http-post-policy", url="https://bucket.example.test/", path_field="key", @@ -324,7 +336,7 @@ def test_many_grants_compile_once_when_a_read_needs_them(monkeypatch: pytest.Mon secrets.add_request(HttpGetGrant(kind="http-get", url=url, expires_at=expires)) assert compiled == [] text = " ".join(["fetched", urls[1234], "and", "x" * 50_000]) - assert secrets.scrub(text).startswith(f"fetched [redacted:{len(urls[1234])}] and") + assert secrets.scrub(text).startswith(f"fetched {urls[1234].replace(f'{1234:024d}', '[redacted:24]')} and") assert secrets.scrub("again") == "again" and len(compiled) == 1 From 72c0634386eeb36b698764d4680c878ba294f9f2 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 15:22:56 -0800 Subject: [PATCH 6/8] refactor(a2a-agent): secrets wired in _secrets and scrubbed where atif/1 is served Secrets.for_agent takes the agent's environment and write-only config defaults, and add_request now takes an agent-config call's write-only values too, so framework.py only builds it and hands it the control token and each extension call. AtifCopy is built with the scrub and serves everything through it, the task read's aux log and turn context as wire dicts, so no read path passes a scrub of its own; its cursor pages take each step's id from the step before scrubbing. Secrets._forms names a secret's four forms, the two name rules share one comment, and the tests share one string walker. Co-Authored-By: Claude Opus 5.5 --- .../agentenv_protocol/a2a_agent/_atif_copy.py | 43 +++++++++++-------- .../agentenv_protocol/a2a_agent/_secrets.py | 43 +++++++++++++++---- .../a2a_agent/_trajectory_log.py | 25 ++++++----- .../agentenv_protocol/a2a_agent/framework.py | 42 +++++++----------- .../tests/test_a2a_atif_scrubbing.py | 42 +++++++++--------- 5 files changed, 112 insertions(+), 83 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py index a252f3de9..6e6790437 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_atif_copy.py @@ -64,12 +64,15 @@ class AtifPage: class AtifCopy: - """One A2A context's atif/1 document. Safe to feed from the agent's thread while the loop reads it.""" + """One A2A context's atif/1 document. Safe to feed from the agent's thread while the loop reads it. Everything it + serves goes through ``scrub``, the agent's secrets redacted.""" - def __init__(self, adapter: type[Adapter], context_id: str) -> None: + def __init__(self, adapter: type[Adapter], context_id: str, *, + scrub: Callable[[Any], Any] = lambda served: served) -> None: self._run = AdapterRun(adapter, trajectory_id=uuid.uuid4().hex) self._adapter = adapter.__name__ self._context_id = context_id + self._scrub = scrub self._lock = threading.Lock() self._tasks: dict[str, _Task] = {} self._failed: str | None = None @@ -126,8 +129,9 @@ def end(self, task_id: str, *, state: str, final: Sequence[Any] = (), error: Tas task.turn = ServedTurn.of(task.context, **ending) task.ended = True - def task_read(self, task_id: str) -> tuple[dict[str, Any], list[AuxEntry], ServedTurn] | None: - """An ended task's document as it stood when the task ended, its aux log and its served turn context.""" + def task_read(self, task_id: str) -> tuple[dict[str, Any], list[dict[str, Any]], dict[str, Any]] | None: + """An ended task's document as it stood when the task ended, its aux log and its served turn context, as served: + on the wire and scrubbed.""" with self._lock: self._check() task = self._tasks.get(task_id) @@ -135,21 +139,22 @@ def task_read(self, task_id: str) -> tuple[dict[str, Any], list[AuxEntry], Serve return None document = self._run.document(through=task.place) assert document is not None - return document, list(task.aux), task.turn + return (self._scrub(document), self._scrub([entry.wire() for entry in task.aux]), + self._scrub(task.turn.wire())) def context_read(self) -> dict[str, Any] | None: """The context's live page: every closed step a reader may be served, or None before the first.""" with self._lock: self._check() - return self._run.page() + page = self._run.page() + return None if page is None else self._scrub(page) - def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | None = None, - scrub: Callable[[Any], Any] = lambda served: served) -> AtifPage: + def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | None = None) -> AtifPage: """The closed steps after step ``after``, of the whole context or of task ``task_id``, within both budgets; the first is always returned, so one larger than ``max_bytes`` can't stall a reader. With them, the sub-agents of every task they belong to, as far as each is served: a sub-agent can gain steps while its task runs, and the - page that serves a task's last step, which closes only as the task ends, carries them whole. Everything is - served through ``scrub``, and the byte budget counts what it serves.""" + page that serves a task's last step, which closes only as the task ends, carries them whole. The byte budget + counts what it serves, scrubbed.""" with self._lock: self._check() document = self._run.page() @@ -164,23 +169,25 @@ def page(self, after: int, max_steps: int, max_bytes: int, *, task_id: str | Non served: list[dict[str, Any]] = [] tasks: set[str | None] = set() used = 0 + last = after for step, owner in pending[:max_steps]: - step = scrub(step) - size = len(json.dumps(step)) + scrubbed = self._scrub(step) + size = len(json.dumps(scrubbed)) if served and used + size > max_bytes: break - served.append(step) + served.append(scrubbed) tasks.add(owner) used += size + last = step["step_id"] header = None subagents: list[dict[str, Any]] = [] if document is not None: - header = scrub({key: value for key, value in document.items() - if key not in ("steps", "subagent_trajectories")}) - subagents = scrub([sub for sub in document.get("subagent_trajectories", []) - if sub_tasks.get(sub["trajectory_id"]) in tasks]) + header = self._scrub({key: value for key, value in document.items() + if key not in ("steps", "subagent_trajectories")}) + subagents = self._scrub([sub for sub in document.get("subagent_trajectories", []) + if sub_tasks.get(sub["trajectory_id"]) in tasks]) return AtifPage(header=header, subagents=subagents, steps=served, - next=served[-1]["step_id"] if served else after, has_more=len(served) < len(pending)) + next=last, has_more=len(served) < len(pending)) def _open(self, task_id: str) -> _Task | None: if self._failed is not None: diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py index a03674130..9953597a3 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py @@ -18,6 +18,7 @@ from ..transfers import HttpGetGrant, HttpPostPolicyGrant, HttpPutGrant from .extensions import CdpAddRequest, ClockSyncTimeRequest, McpAddRequest +from .tasks.v1 import AgentConfig logger = logging.getLogger(__name__) @@ -26,10 +27,11 @@ #: The model credentials an agent's environment holds, which a tool can echo. MODEL_KEY_ENV = "LITELLM_API_KEY" MODEL_HEADERS_ENV = "LITELLM_EXTRA_HEADERS" -#: Header names whose values describe a request rather than authorize it. +# Two rules tell a credential by its name. A header is one unless it plainly describes the request, since a header an +# agent is handed is there to authorize it. A query parameter, a signed form's field or a write-only mapping's key is +# one only when named like one, since most of them aren't: X-Amz-Algorithm, a key path, a sampling parameter. _PLAIN_HEADERS = frozenset({"accept", "content-encoding", "content-length", "content-type", "user-agent"}) -#: The words of a name (a query parameter, a signed form's field, a key in a write-only mapping) that mark its value as a -#: credential, and the endings that do: ``X-Amz-Signature`` and Azure's ``sig`` are, ``X-Amz-Algorithm``, ``X-Amz-Date`` +#: The words of such a name that mark its value as a credential, and the endings that do: ``X-Amz-Signature`` and Azure's ``sig`` are, ``X-Amz-Algorithm``, ``X-Amz-Date`` #: and ``X-Amz-SignedHeaders`` aren't, so ``AWS4-HMAC-SHA256`` is left in an agent's text. _CREDENTIAL_WORDS = frozenset({ "auth", "authorization", "bearer", "cookie", "credential", "credentials", "jwt", "key", "passwd", "password", @@ -52,7 +54,9 @@ class Secrets: agent a grant per file, or a run that accumulates thousands, costs neither a rebuild per secret nor a slower scan.""" - def __init__(self) -> None: + def __init__(self, *, write_only: Mapping[str, str] | None = None) -> None: + #: The agent's write-only config fields, each to its wire name, whose values an agent-config call hands it. + self._write_only = dict(write_only or {}) self._lock = threading.Lock() self._forms: set[str] = set() self._pattern: re.Pattern[str] | None = None @@ -71,12 +75,26 @@ def add(self, value: str | SecretStr | None, *, source: str, warn: bool = True) logger.warning("a secret from %s is shorter than %d characters, so atif/1 reads don't scrub it", source, MIN_SECRET_LENGTH) return - forms = {text, json.dumps(text)[1:-1], json.dumps(text, ensure_ascii=False)[1:-1], quote(text, safe="")} + forms = _forms(text) with self._lock: if not forms <= self._forms: self._forms |= forms self._stale = True + @classmethod + def for_agent(cls, *, write_only: Mapping[str, str], defaults: Mapping[str, Any], + environ: Mapping[str, str] | None = None) -> Secrets: + """What an agent's SDK knows from the start: the model credentials in its environment, and its write-only + config's defaults (``defaults`` by wire name). Its control token comes when it's served, the rest with each + extension call (``add_request``) and from the agent (``add``).""" + secrets = cls(write_only=write_only) + secrets.add_environment(environ) + wire_names = set(write_only.values()) + for name, value in defaults.items(): + if name in wire_names: + secrets.add_values(value, source="a write-only agent-config default") + return secrets + def add_all(self, values: Iterable[str | SecretStr | None], *, source: str, warn: bool = True) -> None: for value in values: self.add(value, source=source, warn=warn) @@ -93,9 +111,12 @@ def add_environment(self, environ: Mapping[str, str] | None = None) -> None: self.add_all(_header_values(headers), source=MODEL_HEADERS_ENV) def add_request(self, request: BaseModel | None) -> None: - """Every secret an extension call hands the agent: the parts of its grants' URLs that carry their credentials, - their headers and signing fields, - an MCP or CDP registration's credentials and a clock follower's read token, wherever the request holds them.""" + """Every secret an extension call hands the agent, whichever handler takes it: the parts of its grants' URLs + that carry their credentials, their headers and signing fields, an MCP or CDP registration's credentials, a clock + follower's read token, wherever the request holds them, and an agent-config call's write-only values.""" + if isinstance(request, AgentConfig): + for name in request.model_fields_set & self._write_only.keys(): + self.add_values(getattr(request, name), source="a write-only agent-config value") for item in _models(request): if isinstance(item, (HttpGetGrant, HttpPutGrant, HttpPostPolicyGrant)): self.add_all(_url_secrets(str(item.url)), source="a transfer grant", warn=False) @@ -129,6 +150,12 @@ def _match(self) -> re.Pattern[str] | None: return self._pattern +def _forms(text: str) -> set[str]: + """How a secret can appear in a served string: raw, JSON-escaped with and without ASCII escapes (inbound DataParts + are written without), and percent-encoded, as in another URL's query.""" + return {text, json.dumps(text)[1:-1], json.dumps(text, ensure_ascii=False)[1:-1], quote(text, safe="")} + + def _scrub(value: Any, pattern: re.Pattern[str]) -> Any: if isinstance(value, str): return pattern.sub(lambda match: f"[redacted:{len(match.group(0))}]", value) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py index 5858ce1b0..70a09c901 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_trajectory_log.py @@ -8,7 +8,7 @@ from dataclasses import dataclass from typing import Any, Callable, Sequence -from ..atif import Adapter, AuxEntry, ServedTurn +from ..atif import Adapter from ._atif_copy import AtifCopy, AtifPage, TurnStart from ._turn_index import TurnIndex from .extensions import TrajectoryState @@ -60,8 +60,8 @@ class AtifTaskRead: """An ended task's atif/1 document as it stood when the task ended, its aux log and its served turn context.""" document: dict[str, Any] - aux: list[AuxEntry] - turn: ServedTurn + aux: list[dict[str, Any]] + turn: dict[str, Any] @dataclass(frozen=True, slots=True) @@ -87,6 +87,7 @@ def __init__( *, native: str | None = None, atif: type[Adapter] | None = None, + scrub: Callable[[Any], Any] | None = None, ) -> None: if max_contexts < 1: raise ValueError("max_contexts must be positive") @@ -95,6 +96,8 @@ def __init__( self._atif = atif #: Each context's count of started tasks, kept only for an agent that serves atif/1. self._turns = TurnIndex() if atif is not None else None + #: What every atif/1 read goes through: the agent's secrets redacted. + self._scrub = scrub self._tasks: dict[str, _TaskRecord] = {} self._contexts: OrderedDict[str, list[str]] = OrderedDict() self._copies: dict[str, AtifCopy] = {} @@ -129,7 +132,9 @@ def start(self, task_id: str, turn: TurnStart | None = None) -> None: if self._atif is not None and turn is not None: copy = self._copies.get(record.context_id) if copy is None: - copy = self._copies[record.context_id] = AtifCopy(self._atif, record.context_id) + copy = self._copies[record.context_id] = AtifCopy( + self._atif, record.context_id, **({"scrub": self._scrub} if self._scrub is not None else {}) + ) copy.start(task_id, self._turns.next(record.context_id), turn) record.log._atif = _CopySink(copy, task_id) self._touch(record.context_id) @@ -287,29 +292,29 @@ def atif_context(self, context_id: str) -> dict[str, Any] | None: return copy.context_read() def atif_task_page( - self, task_id: str, after: int, max_steps: int, max_bytes: int, *, scrub: Callable[[Any], Any] + self, task_id: str, after: int, max_steps: int, max_bytes: int ) -> AtifCursor | None: - """A cursor page of the task's closed atif/1 steps, in the task's state, served through ``scrub``.""" + """A cursor page of the task's closed atif/1 steps, in the task's state.""" record = self._tasks.get(task_id) copy = self._copies.get(record.context_id) if record is not None else None if copy is None: return None self._touch(record.context_id) state = record.state - page = copy.page(after, max_steps, max_bytes, task_id=task_id, scrub=scrub) + page = copy.page(after, max_steps, max_bytes, task_id=task_id) return AtifCursor(page=page, context_id=record.context_id, task_id=task_id, state=state) def atif_context_page( - self, context_id: str, after: int, max_steps: int, max_bytes: int, *, scrub: Callable[[Any], Any] + self, context_id: str, after: int, max_steps: int, max_bytes: int ) -> AtifCursor | None: """A cursor page of the context's closed atif/1 steps, on the task the context is on and in - the context's state, served through ``scrub``.""" + the context's state.""" copy = self._copies.get(context_id) records = self._context_records(context_id) if copy is not None else None if copy is None or records is None: return None task_id, state = self._context_progress(context_id, records) - page = copy.page(after, max_steps, max_bytes, scrub=scrub) + page = copy.page(after, max_steps, max_bytes) return AtifCursor(page=page, context_id=context_id, task_id=task_id, state=state) def _context_progress( diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index dbd91bdb5..63f954de7 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -588,18 +588,19 @@ def __init__( self.trajectory_formats: tuple[str, ...] = ( (native, ATIF_FORMAT) if atif is not None else (native,) if native else () ) - self.task_trajectories = TaskTrajectories(native=native, atif=atif) + #: The secrets the agent's atif/1 reads leave out; an agent that serves none has none to scrub. + self.secrets = Secrets.for_agent( + write_only={field: wire for field, wire in _config_wire_names(self.config_model).items() + if wire in self._write_only_config_fields}, + defaults=self.config_defaults, + ) if atif is not None else None + self.task_trajectories = TaskTrajectories( + native=native, atif=atif, scrub=self.secrets.scrub if self.secrets is not None else None + ) #: Whether the card offers atif/1, served from the copy an adapter builds. self.serves_atif = atif is not None #: The SDK's state in the agent's snapshots, which only an agent that serves atif/1 keeps. self.snapshot_states = SnapshotStates(self.task_trajectories) if atif is not None else None - #: The secrets the agent's atif/1 reads leave out; an agent that serves none has none to scrub. - self.secrets = Secrets() if atif is not None else None - if self.secrets is not None: - self.secrets.add_environment() - for name, value in self.config_defaults.items(): - if name in self._write_only_config_fields: - self.secrets.add_values(value, source="a write-only agent-config default") self._context_sessions = _BoundedContextSessions() self.skills: list[Mapping[str, Any]] = [] self.identity_skills: dict[str, str] = {} @@ -744,19 +745,6 @@ async def agent_config_set(self, request: AgentConfig) -> dict[str, Any]: self.card.description = validated.description return {"status": "updated"} - def note_secrets(self, request: Any) -> None: - """Keep the secrets an extension call hands the agent out of its atif/1 reads, whichever handler takes it: - its grants and registrations' credentials, and a write-only agent-config value.""" - if self.secrets is None: - return - self.secrets.add_request(request) - if isinstance(request, AgentConfig): - wire_names = _config_wire_names(type(request)) - write_only = _config_write_only_wire_names(type(request)) - for name in request.model_fields_set: - if wire_names[name] in write_only: - self.secrets.add_values(getattr(request, name), source="a write-only agent-config value") - async def agent_config_get(self) -> dict[str, Any]: config = _thaw(self.config) for wire_name in self._write_only_config_fields: @@ -907,12 +895,12 @@ def _atif_events( try: if isinstance(request, TaskEventsTrajectoryRequest): cursor = self.task_trajectories.atif_task_page( - request.task_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES, scrub=self.secrets.scrub + request.task_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES ) unknown = f"Unknown task '{request.task_id}'" else: cursor = self.task_trajectories.atif_context_page( - request.context_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES, scrub=self.secrets.scrub + request.context_id, request.after, max_steps, MAX_TRAJECTORY_READ_BYTES ) unknown = f"Unknown context '{request.context_id}'" except ValueError as exc: @@ -941,7 +929,7 @@ async def _atif_document( ) -> dict[str, Any]: """A whole atif/1 document: a task read's as it stood when the task ended, with the task's aux log and turn context, or a context read's live page; inline, or uploaded - through the request's grants, its secrets scrubbed either way.""" + through the request's grants, as the copy serves it, its secrets scrubbed.""" served: dict[str, Any] = {} if isinstance(request, (TaskTrajectoryRequest, TaskObjectTrajectoryRequest)): read = self.task_trajectories.atif_task(request.task_id) @@ -951,7 +939,7 @@ async def _atif_document( detail=f"No completed trajectory available for task '{request.task_id}'", ) document = read.document - served = {"aux": [entry.wire() for entry in read.aux], "turn_context": read.turn.wire()} + served = {"aux": read.aux, "turn_context": read.turn} else: if isinstance(request, ContextObjectTrajectoryRequest): _refuse_turn_objects(request) @@ -961,7 +949,6 @@ async def _atif_document( status_code=404, detail=f"Context '{request.context_id}' has no {ATIF_FORMAT} step to serve yet", ) - document, served = self.secrets.scrub(document), self.secrets.scrub(served) versions = _atif_versions(document) if isinstance(request, (TaskTrajectoryRequest, ContextTrajectoryRequest)): return {"trajectory": document, "format": ATIF_FORMAT, **versions, **served} @@ -1365,7 +1352,8 @@ async def invoke(request: Request) -> JSONResponse: extension_request = None else: extension_request = request_model.model_validate(payload) - self.services.note_secrets(extension_request) + if self.services.secrets is not None: + self.services.secrets.add_request(extension_request) if extension_uri == TRAJECTORY_V1.uri: self.services.check_trajectory_format(extension_request.format) if extension_request.format == ATIF_FORMAT: diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py index 98d5b466c..7f0f2fc57 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py @@ -112,14 +112,21 @@ def _native(client: TestClient, task_id: str) -> Any: return client.post("/ext/trajectory", json={"task_id": task_id}).json()["trajectory"] -def _strings(value: Any) -> list[str]: +def _map_strings(value: Any, change: Callable[[str], str]) -> Any: + """``value`` with ``change`` applied to every string it holds, mapping keys included.""" if isinstance(value, str): - return [value] + return change(value) if isinstance(value, dict): - return [s for item in value.values() for s in _strings(item)] + return {_map_strings(key, change): _map_strings(item, change) for key, item in value.items()} if isinstance(value, list): - return [s for item in value for s in _strings(item)] - return [] + return [_map_strings(item, change) for item in value] + return value + + +def _strings(value: Any) -> list[str]: + found: list[str] = [] + _map_strings(value, lambda text: found.append(text) or text) + return found def _turn(client: TestClient, prompt: str) -> str: @@ -350,28 +357,23 @@ def test_a_short_secret_is_left_with_one_warning_per_source(caplog: pytest.LogCa assert "short" not in [record.args for record in caplog.records] -def test_a_cursor_page_counts_its_bytes_as_it_serves_them() -> None: - copy = AtifCopy(Echoes, "ctx-1") +def _three_steps(**scrub: Any) -> AtifCopy: + copy = AtifCopy(Echoes, "ctx-1", **scrub) copy.start("t1", 0, TurnStart(message_id=None, parts=(TextPart(text="hi"),), agent_name="toy", agent_version="1", agent_model=None)) for text in ("one", "two", "three"): copy.native("t1", {"type": "say", "text": text}) copy.end("t1", state=TrajectoryState.COMPLETED.value, final=(TextPart(text="done"),)) - plain = copy.page(0, 10, 10_000) - budget = sum(len(json.dumps(step)) for step in plain.steps[:2]) - assert len(copy.page(0, 10, budget).steps) == 2 - padded = copy.page(0, 10, budget, scrub=lambda value: _pad(value)) - assert len(padded.steps) == 1 and padded.has_more + return copy -def _pad(value: Any) -> Any: - if isinstance(value, str): - return value + "x" * 200 - if isinstance(value, dict): - return {key: _pad(item) for key, item in value.items()} - if isinstance(value, list): - return [_pad(item) for item in value] - return value +def test_a_cursor_page_counts_its_bytes_as_it_serves_them() -> None: + plain = _three_steps() + budget = sum(len(json.dumps(step)) for step in plain.page(0, 10, 10_000).steps[:2]) + assert len(plain.page(0, 10, budget).steps) == 2 + # A scrub that lengthens every string, as a redaction longer than its secret does. + padded = _three_steps(scrub=lambda value: _map_strings(value, lambda text: text + "x" * 200)).page(0, 10, budget) + assert len(padded.steps) == 1 and padded.has_more def test_an_agent_that_serves_no_atif_registers_nothing_and_registering_before_its_app_is_refused() -> None: From 011ab9c81d37810ef638bb90de1ff10e2254e924 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 15:43:08 -0800 Subject: [PATCH 7/8] fix(a2a-agent): a URL's path token beside a plain query, and its query secrets as written A grant server's /v1/grants/?download=1 gave no secret, since only a URL with no query had its path tokens taken: path tokens are now taken whenever the query carries no credential. A signed URL percent-encoded again, as inside another URL's query, held its token encoded twice, which no form matched: each credential query value is now taken as the URL writes it too, whose own encoding is that copy's. Co-Authored-By: Claude Opus 5.5 --- .../agentenv_protocol/a2a_agent/_secrets.py | 27 +++++++++++-------- .../tests/test_a2a_atif_scrubbing.py | 15 +++++++++++ 2 files changed, 31 insertions(+), 11 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py index 9953597a3..a8580de35 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/_secrets.py @@ -12,7 +12,7 @@ import threading from collections.abc import Iterable, Iterator, Mapping from typing import Any, TypeVar -from urllib.parse import parse_qsl, quote, urlsplit +from urllib.parse import quote, unquote_plus, urlsplit from pydantic import BaseModel, SecretStr @@ -237,22 +237,27 @@ def _grant_secrets(grant: HttpGetGrant | HttpPutGrant | HttpPostPolicyGrant) -> def _url_secrets(url: str) -> list[str]: - """The parts of a URL that carry its credential: a presigned URL's credential-like query values, the token-like path - segments of a URL with no query, as a grant server's, and its password. Every copy of the URL, whole or as a - request line, holds them, so redacting them is enough; the rest (its host, its path, ``X-Amz-Algorithm``) isn't - secret, and leaving it keeps each grant's share of the match to its signature: the session token and access key a - role signs every grant with are each one secret.""" + """The parts of a URL that carry its credential: a presigned URL's credential-like query values, else its token-like + path segments, as a grant server's (``/v1/grants/``, with or without a plain query such as ``?download=1``), + and its password. Every copy of the URL, whole or as a request line, holds them, so redacting them is enough; the + rest (its host, its path, ``X-Amz-Algorithm``) isn't secret, and leaving it keeps each grant's share of the match + to its signature: the session token and access key a role signs every grant with are each one secret.""" parts = urlsplit(url) - if parts.query: - carried = _query_values(url) - else: + carried = _query_values(url) + if not carried: carried = [segment for segment in parts.path.split("/") if _TOKEN_SEGMENT.fullmatch(segment)] return [*carried, *([parts.password] if parts.password else [])] def _query_values(url: str) -> list[str]: - """The values of a URL's credential-like query parameters: a signature, a credential, a token, a key.""" - return [value for name, value in parse_qsl(urlsplit(url).query) if _names_credential(name)] + """The values of a URL's credential-like query parameters (a signature, a credential, a token, a key), decoded and + as the URL writes them, whose own percent-encoding is what a copy of the URL inside another URL's query holds.""" + values: list[str] = [] + for pair in urlsplit(url).query.split("&"): + name, _, written = pair.partition("=") + if written and _names_credential(unquote_plus(name)): + values += [unquote_plus(written), written] + return values def _header_values(headers: Mapping[str, Any] | None) -> list[str]: diff --git a/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py index 7f0f2fc57..9168ed816 100644 --- a/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py +++ b/packages/agentenv-protocol/tests/test_a2a_atif_scrubbing.py @@ -257,6 +257,21 @@ def test_a_write_only_mapping_is_redacted_by_its_credentials_alone(monkeypatch: assert not [record for record in caplog.records if "shorter than" in record.message] +def test_a_path_token_beside_a_plain_query_and_a_signed_url_encoded_again_are_redacted() -> None: + secrets = Secrets() + token = "eyJvcCI6ImdldCJ9.c2lnbmF0dXJlLXRoYXQtaXMtbG9uZw" + expires = datetime.now(timezone.utc) + timedelta(hours=1) + secrets.add_request(HttpGetGrant(kind="http-get", url=f"https://host.example.test/v1/grants/{token}?download=1", + expires_at=expires)) + signed = "https://store.example.test/runs/1.json?X-Amz-Security-Token=abc%2Fdef%2Bghi%3D123456789&X-Amz-Expires=900" + secrets.add_request(HttpGetGrant(kind="http-get", url=signed, expires_at=expires)) + nested = f"https://viewer.example.test/open?src={quote(signed, safe='')}" + assert "abc%252Fdef%252Bghi%253D123456789" in nested + scrubbed = secrets.scrub([f"GET /v1/grants/{token}?download=1", signed, nested]) + assert not [text for text in scrubbed if token in text or "abc" in text] + assert all("[redacted:" in text for text in scrubbed) + + def test_a_roles_grants_add_their_signatures_alone() -> None: """Every grant a role signs carries the same session token and access key: each is one secret, so a grant's share of the match is its signature, however long its URL.""" From eb906b2d7f16837d984a82f114b2a38cc054153c Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Thu, 19 Nov 2026 15:43:34 -0800 Subject: [PATCH 8/8] docs(a2a-agent): the README names how a grant URL's secrets are taken Co-Authored-By: Claude Opus 5.5 --- packages/agentenv-protocol/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index b6baf82cb..c8f1e7c27 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1680,8 +1680,8 @@ what they serve. The SDK knows: CDP endpoint's header values and the token in its URLs; - every transfer grant an extension call hands the agent: the parts of its URL that carry the credential (a presigned URL's credential-like query values, - `X-Amz-Signature` but not `X-Amz-Algorithm`; a token-like path segment of a - URL with no query; a password), its headers other than `Content-Type` and the + `X-Amz-Signature` but not `X-Amz-Algorithm`, decoded and as the URL writes + them; else a token-like path segment; a password), its headers other than `Content-Type` and the like, and a signed upload form's signing fields. Every copy of the URL holds those parts, so a URL an agent prints keeps its host and path and loses its signature;