opencode-a2a 1.2.0__tar.gz → 1.3.1__tar.gz

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/.github/workflows/publish.yml

@@ -146,11 +146,30 @@ jobs:
 
           ensure_release
 
+          python - <<'PY'
+          import hashlib
+          from pathlib import Path
+
+          dist_dir = Path("dist")
+          lines = []
+          for asset in sorted(
+              (
+                  path
+                  for path in dist_dir.iterdir()
+                  if path.is_file() and path.name.endswith((".whl", ".tar.gz"))
+              ),
+              key=lambda item: item.name,
+          ):
+              digest = hashlib.sha256(asset.read_bytes()).hexdigest()
+              lines.append(f"{digest}  {asset.name}")
+          (dist_dir / "SHA256SUMS").write_text("\n".join(lines) + "\n", encoding="utf-8")
+          PY
+
           mapfile -t existing_assets < <(
             retry 3 5 gh release view "$RELEASE_TAG" --json assets --jq '.assets[].name'
           )
 
-          for asset in dist/*.tar.gz dist/*.whl; do
+          for asset in dist/*.tar.gz dist/*.whl dist/SHA256SUMS; do
             asset_name="$(basename "$asset")"
             if printf '%s\n' "${existing_assets[@]}" | grep -Fxq "$asset_name"; then
               echo "Release asset already present: $asset_name"

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/CONTRIBUTING.md

@@ -71,6 +71,14 @@ uv run pytest tests/contracts/test_extension_contract_consistency.py
 uv run mypy src/opencode_a2a
 ```
 
+If you change outbound authentication, tracing, protocol-version, or extension headers, run the SDK transport regression directly:
+
+```bash
+uv run pytest --no-cov tests/client/test_client_http_headers.py
+```
+
+Assertions against a mocked SDK client or `ClientCallContext` alone do not prove that headers reached the HTTP request. Keep at least one regression test across Agent Card resolution, the real SDK transport, and the final `httpx.Request` boundary.
+
 ## Change Expectations
 
 - Keep code, comments, and docs in English.

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-a2a
-Version: 1.2.0
+Version: 1.3.1
 Summary: OpenCode A2A runtime
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -218,6 +218,7 @@ Read before deployment:
 - [docs/maintainer-architecture.md](docs/maintainer-architecture.md) Internal module boundaries and maintainer call chains.
 - [docs/compatibility.md](docs/compatibility.md) Compatibility-sensitive surface and contract-honesty guidance.
 - [docs/guide.md](docs/guide.md) Usage guide, transport details, streaming behavior, extensions, and examples.
+- [docs/security-architecture.md](docs/security-architecture.md) Security surface, boundaries, and residual-risk register.
 - [docs/conformance.md](docs/conformance.md) External TCK experiment workflow and artifact handling.
 - [SECURITY.md](SECURITY.md) Threat model, deployment caveats, and vulnerability disclosure guidance.
 

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/README.md

@@ -176,6 +176,7 @@ Read before deployment:
 - [docs/maintainer-architecture.md](docs/maintainer-architecture.md) Internal module boundaries and maintainer call chains.
 - [docs/compatibility.md](docs/compatibility.md) Compatibility-sensitive surface and contract-honesty guidance.
 - [docs/guide.md](docs/guide.md) Usage guide, transport details, streaming behavior, extensions, and examples.
+- [docs/security-architecture.md](docs/security-architecture.md) Security surface, boundaries, and residual-risk register.
 - [docs/conformance.md](docs/conformance.md) External TCK experiment workflow and artifact handling.
 - [SECURITY.md](SECURITY.md) Threat model, deployment caveats, and vulnerability disclosure guidance.
 

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/SECURITY.md

@@ -24,6 +24,9 @@ This project is currently best suited for trusted or internal environments. Impo
 - static credential auth only by default; stronger identity propagation is still a follow-up hardening area
 - operators remain responsible for host hardening, secret rotation, process access controls, and reverse-proxy exposure strategy
 
+For the security surface mapping and residual-risk register, see
+[docs/security-architecture.md](./docs/security-architecture.md).
+
 ## Reporting a Vulnerability
 
 Please avoid posting active secrets, bearer tokens, or reproduction payloads that contain private data in public issues.

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/docs/architecture.md

@@ -96,6 +96,7 @@ Use the docs by responsibility:
 - [Usage Guide](guide.md): runtime configuration, transport contracts, extensions, and examples
 - [Maintainer Architecture Guide](maintainer-architecture.md): internal module boundaries, request call chains, and persistence touchpoints
 - [Extension Specifications](extension-specifications.md): stable extension URI/spec index and disclosure policy
+- [Security Architecture](security-architecture.md): security surface mapping and residual-risk register
 - [Conformance Notes](conformance.md): external TCK experiment workflow
 - [Contributing Guide](../CONTRIBUTING.md): contributor workflow and validation
 - [Security Policy](../SECURITY.md): threat model and disclosure guidance

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/docs/compatibility.md

@@ -100,7 +100,7 @@ The supported persistence profile is one application process using its own local
 - Deployment-conditional methods must be declared as conditional rather than silently disappearing.
 - `opencode.sessions.prompt_async` input-part passthrough is compatibility-sensitive. Changes to supported part types, passthrough field semantics, or rejection behavior should be treated as wire-level changes.
 - `opencode.sessions.shell` is compatibility-sensitive as a deployment-conditional shell snapshot surface. It should not silently widen into a general interactive shell API.
-- `opencode.workspaces.*` and `opencode.worktrees.*` are boundary-sensitive and should remain explicitly provider-private, operator-scoped, and deployment-conditional where applicable.
+- `opencode.workspaces.*` and `opencode.worktrees.*` are boundary-sensitive and should remain explicitly provider-private, operator-scoped, and deployment-conditional where applicable. Discovery responses are normalized summaries that exclude upstream local paths (`directory`, `canonical`, worktree paths) and raw/internal fields.
 - Interrupt callback and recovery methods are compatibility-sensitive because clients may depend on request ID lifecycle, expiry semantics, and identity scoping.
 - Agent Card media modes and `acceptedOutputModes` handling are compatibility-sensitive. Changes to declared chat modes, to task-scoped negotiation persistence, or to output filtering of structured tool payloads should be treated as wire-level changes.
 - Agent Card and OpenAPI publication of `protocol_compatibility`, `service_behaviors`, and runtime feature toggles is compatibility-sensitive discoverability surface.

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/docs/extension-specifications.md

@@ -130,6 +130,7 @@ Extension URI: `urn:opencode-a2a:extension:workspace-control:v1`
 - Methods: stable project discovery plus experimental workspace/worktree discovery and deployment-conditional mutation methods
 - Dependencies: none declared by this version
 - Security boundary: this extension is provider-private, operator-scoped, and partly deployment-conditional
+- Response hygiene: discovery responses are normalized summaries; upstream local paths (`directory`, `canonical`, worktree paths), raw entries, and credential-like fields are excluded
 - Versioning: breaking changes require a new versioned URI
 
 ## OpenCode Interrupt Recovery v1

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/docs/guide.md

@@ -32,12 +32,15 @@ Key variables to understand protocol behavior:
 - `A2A_ALLOW_DIRECTORY_OVERRIDE`: controls whether clients may pass `metadata.opencode.directory`.
 - `A2A_ENABLE_SESSION_SHELL`: gates high-risk JSON-RPC method `opencode.sessions.shell`.
 - `A2A_ENABLE_WORKSPACE_MUTATIONS`: gates operator-only workspace/worktree mutation methods such as `opencode.workspaces.create` and `opencode.worktrees.reset`.
+- `A2A_EXPOSE_WORKSPACE_ROOT_IN_CARD`: default `false`; controls whether the authenticated extended Agent Card includes the local `OPENCODE_WORKSPACE_ROOT` in the structured profile `runtime_context`. Keep disabled unless trusted callers explicitly need the host path.
 - `A2A_SANDBOX_MODE` / `A2A_SANDBOX_FILESYSTEM_SCOPE` / `A2A_SANDBOX_WRITABLE_ROOTS`: declarative execution-boundary metadata for sandbox mode, filesystem scope, and optional writable roots.
 - `A2A_NETWORK_ACCESS` / `A2A_NETWORK_ALLOWED_DOMAINS`: declarative execution-boundary metadata for network policy and optional allowlist disclosure.
 - `A2A_APPROVAL_POLICY` / `A2A_APPROVAL_ESCALATION_BEHAVIOR`: declarative execution-boundary metadata for approval workflow.
 - `A2A_WRITE_ACCESS_SCOPE` / `A2A_WRITE_ACCESS_OUTSIDE_WORKSPACE`: declarative execution-boundary metadata for write scope and whether writes may extend outside the primary workspace boundary.
 - `A2A_HOST` / `A2A_PORT`: runtime bind address. Defaults: `127.0.0.1:8000`.
 - `A2A_PUBLIC_URL`: public base URL advertised by the Agent Card. Default: `http://127.0.0.1:8000`.
+- `A2A_ALLOWED_ORIGINS`: comma-separated extra browser-origin allowlist for inbound requests. Requests carrying an `Origin` header must match the origin of `A2A_PUBLIC_URL` or an entry here; mismatches are rejected with `403` (CSRF guard). Requests without an `Origin` header (CLI/SDK clients) are unaffected.
+- `A2A_ALLOWED_HOSTS`: comma-separated `Host` header allowlist (exact names or `*.example.com` wildcards). When configured, every inbound request must present a matching `Host` header. Binding to a non-loopback address without this allowlist logs a startup warning (DNS rebinding risk).
 - `A2A_LOG_LEVEL`: runtime log level. Default: `WARNING`.
 - `A2A_LOG_PAYLOADS` / `A2A_LOG_BODY_LIMIT`: payload logging behavior and truncation. When `A2A_LOG_LEVEL=DEBUG`, upstream OpenCode stream events are also logged with preview truncation controlled by `A2A_LOG_BODY_LIMIT`.
 - The runtime accepts W3C `traceparent` / `tracestate` headers on inbound requests. When `traceparent` is missing or invalid, the runtime generates a fresh valid value and exposes it on the HTTP response header.
@@ -45,6 +48,8 @@ Key variables to understand protocol behavior:
 - Logs derive a stable `trace_id` from the active `traceparent` so request-scoped log lines can be correlated without introducing high-cardinality metric labels.
 - `A2A_HTTP_GZIP_MINIMUM_SIZE`: minimum eligible response-body size in bytes for global non-streaming HTTP gzip compression. Default: `8192`.
 - `A2A_MAX_REQUEST_BODY_BYTES`: runtime request-body limit. Oversized requests return HTTP `413`.
+- `A2A_RATE_LIMIT_ENABLED` / `A2A_RATE_LIMIT_WINDOW_SECONDS` / `A2A_RATE_LIMIT_MAX_REQUESTS`: per-credential sliding-window rate limiting (per-peer-IP for the unauthenticated Agent Card surface). Defaults: `true` / `60` seconds / `120` requests. Exceeding the window returns HTTP `429` with a `Retry-After` header; `A2A_RATE_LIMIT_ENABLED=false` disables the limiter.
+- `A2A_STREAM_MAX_BYTES` / `A2A_STREAM_MAX_DURATION_SECONDS` / `A2A_STREAM_IDLE_TIMEOUT_SECONDS`: streaming (SSE) response budgets for total bytes, total duration, and idle gap. Defaults: `67108864` bytes / `3600` seconds / `120` seconds; `0` disables the respective budget.
 - `A2A_PENDING_SESSION_CLAIM_TTL_SECONDS`: lease duration for pending preferred session claims before they expire and stop blocking other identities.
 - `A2A_INTERRUPT_REQUEST_TTL_SECONDS`: active retention window for the interrupt request binding registry used by `a2a.interrupt.*` callback methods. Default: `10800` seconds (`180` minutes).
 - `A2A_INTERRUPT_REQUEST_TOMBSTONE_TTL_SECONDS`: retention window for expired interrupt tombstones after active TTL has elapsed. During this window, repeated replies keep returning `INTERRUPT_REQUEST_EXPIRED` instead of falling through to `INTERRUPT_REQUEST_NOT_FOUND`. Default: `600` seconds (`10` minutes).
@@ -59,6 +64,8 @@ Key variables to understand protocol behavior:
 - `A2A_CLIENT_BEARER_TOKEN`: optional bearer token attached to outbound peer calls made by the embedded A2A client and `a2a_call` tool path.
 - `A2A_CLIENT_BASIC_AUTH`: optional Basic auth credential attached to outbound peer calls made by the embedded A2A client and `a2a_call` tool path.
 - `A2A_CLIENT_SUPPORTED_TRANSPORTS`: ordered outbound transport preference list.
+- `A2A_CLIENT_ALLOWED_HOSTS`: comma-separated allowlist of outbound target hosts for the embedded A2A client and `a2a_call` tool path (exact names or `*.example.com` wildcards). When configured, outbound calls are restricted to matching hosts, and outbound credentials (`A2A_CLIENT_BEARER_TOKEN` / `A2A_CLIENT_BASIC_AUTH`) are only sent to allowlisted hosts.
+- `A2A_CLIENT_ALLOW_PRIVATE_HOSTS`: default `false`. When `false`, outbound `a2a_call(...)` targets that resolve to private, loopback, link-local, reserved, or multicast addresses are rejected (SSRF / DNS-rebinding guard). Set to `true` only when the deployment intentionally targets A2A peers on the local network.
 - `A2A_TASK_STORE_BACKEND`: unified lightweight persistence backend for SDK task rows plus adapter-managed session / interrupt state. Supported values: `database`, `memory`. Default: `database`.
 - `A2A_TASK_STORE_DATABASE_URL`: database URL used by the unified durable backend when `A2A_TASK_STORE_BACKEND=database`. Default: `sqlite+aiosqlite:///./opencode-a2a.db`.
 - On startup, the runtime only auto-migrates adapter-owned state tables; existing SDK-owned task tables must be upgraded explicitly with upstream `a2a-db`.
@@ -84,6 +91,20 @@ Key variables to understand protocol behavior:
   - `A2A_CLIENT_BASIC_AUTH`
   - `A2A_CLIENT_SUPPORTED_TRANSPORTS`
 
+## Inbound Origin and Host Boundary
+
+Browsers store and automatically attach Basic credentials, and they send an `Origin` header with every request. Without an origin boundary, a malicious web page could cross-site trigger `SendMessage`, `CancelTask`, or task subscription against a Basic-protected service. The runtime therefore enforces:
+
+- every request carrying an `Origin` header must match the origin of `A2A_PUBLIC_URL` (scheme, host, and non-default port) or an entry in `A2A_ALLOWED_ORIGINS`; mismatches return `403` before authentication. `Origin: null` (sandboxed iframes) is rejected unless explicitly allowlisted;
+- requests without an `Origin` header — normal CLI/SDK peers — are not subject to origin checks;
+- when `A2A_ALLOWED_HOSTS` is configured, every request must present a matching `Host` header (exact names, optional `host:port`, or `*.example.com` wildcards); mismatches return `403`. This also blocks DNS rebinding, where an attacker-controlled hostname resolves to the service address and the browser sends that hostname as `Host`;
+- binding to a non-loopback address (`0.0.0.0`, `::`, or a LAN/interface address) without `A2A_ALLOWED_HOSTS` logs a startup warning: the service is then exposed to DNS rebinding and should only run behind a trusted network boundary or a reverse proxy that validates `Host`.
+
+For browser-based clients, prefer the same origin as `A2A_PUBLIC_URL`, or explicitly allow the dashboard origin via `A2A_ALLOWED_ORIGINS` and treat `A2A_ALLOWED_HOSTS` as part of the deployment contract. Basic authentication should not be relied on as the sole browser-facing boundary: combine it with the origin/host checks above, short-lived credentials, and TLS at the public URL.
+
+The security surface mapping and residual-risk register live in
+[security-architecture.md](./security-architecture.md).
+
 ## Client Initialization Facade (Preview)
 
 `opencode-a2a` now includes a minimal client bootstrap module in `src/opencode_a2a/client/` to support downstream consumer usage while keeping server and client concerns separate.
@@ -103,6 +124,14 @@ Current client facade API:
 
 Server-side outbound peer calls read outbound credentials from environment variables. Configure `A2A_CLIENT_BEARER_TOKEN` or `A2A_CLIENT_BASIC_AUTH` when the remote agent protects its runtime surface. CLI outbound calls follow the same environment-only model.
 
+The embedded `a2a_call(...)` tool lets the upstream model choose the target URL, so the adapter applies a fail-closed network policy before opening any connection:
+
+- only `http`/`https` schemes are accepted, and URLs carrying userinfo credentials are rejected;
+- when `A2A_CLIENT_ALLOWED_HOSTS` is set, the target host must match the allowlist (exact or `*.example.com` wildcard);
+- unless `A2A_CLIENT_ALLOW_PRIVATE_HOSTS=true`, the resolved addresses must be public; private/loopback/link-local/reserved addresses are rejected even when the hostname matches the allowlist (DNS rebinding defense);
+- outbound credentials are only attached to allowlisted hosts. If credentials are configured without an allowlist, they are never sent and a warning is logged;
+- the `opencode-a2a call` CLI remains a manual operator action and is not subject to the allowlist, but still rejects non-http(s) schemes through the shared client URL handling.
+
 CLI outbound example:
 
 ```bash
@@ -181,6 +210,24 @@ The supported persistence profile is one `opencode-a2a` application process usin
 
 The runtime configures local durability-oriented SQLite connection settings (`WAL`, `busy_timeout`, `synchronous=NORMAL`) and creates missing parent directories for file-backed database paths.
 
+### SQLite Persistence Hardening
+
+File-backed SQLite databases are hardened at startup and on every new connection on POSIX systems:
+
+- the database file must be a regular file; symlinks are rejected and fail startup;
+- the file must be owned by the user running `opencode-a2a`; a database owned by another user fails startup;
+- the database file is forced to mode `0600`, and existing SQLite sidecar files (`-wal`/`-shm`/`-journal`) are converged to the same mode;
+- the parent directory is created with mode `0700` when it does not exist; keep the database directory private (no group/world access);
+- if the database is replaced by a symlink, a special file, or a foreign-owned file while the service is running, the next connection fails closed.
+
+`A2A_TASK_STORE_DATABASE_URL` values that do not map to a plain file path are exempt: `:memory:` and `file:` URI-style database components (including in-memory shared-cache databases) are not hardened. Prefer a plain absolute file path for deployments that need the startup guarantees. Non-POSIX platforms rely on the user account ACLs of the hosting directory; the same private-directory requirement applies there.
+
+Deployment requirements:
+
+- run `opencode-a2a` as a dedicated user and keep the database directory outside world-readable workspace trees;
+- do not place the SQLite file on network-mounted or sync-managed directories;
+- when migrating an existing database, fix ownership and mode before startup: `chown <service-user> <db>` and `chmod 600 <db>`, and ensure the parent directory is not group/world accessible.
+
 The runtime automatically applies lightweight schema migrations for its custom state tables and records the applied version in `a2a_schema_version`. Schema-version writes are idempotent across concurrent first-start races, pending preferred-session claims now persist absolute `expires_at` timestamps, legacy rows without `expires_at` are pruned during migration instead of being reconstructed from historical TTL assumptions, and the built-in path currently targets the local SQLite deployment profile without requiring Alembic.
 
 Database-backed task persistence also keeps the existing first-terminal-state-wins contract while tightening the SQLite path with an atomic terminal-write guard instead of relying only on process-local read-before-write checks.
@@ -260,6 +307,8 @@ If one deployment works while another fails against the same upstream provider,
 
 - Requests require either `Authorization: Bearer <token>` or a configured `Authorization: Basic <base64(username:password)>`; otherwise `401` is returned. Agent Card endpoints are public.
 - Requests above `A2A_MAX_REQUEST_BODY_BYTES` are rejected with HTTP `413` before transport handling.
+- Inbound requests are rate limited with a sliding window keyed by `credential_id` when configured, otherwise by the authenticated principal; the public Agent Card surface is keyed by the direct peer IP (never `X-Forwarded-For`). Exceeding `A2A_RATE_LIMIT_MAX_REQUESTS` within `A2A_RATE_LIMIT_WINDOW_SECONDS` returns HTTP `429` with a `Retry-After` header. The limiter is process-local; multi-process deployments should place a shared gateway in front or rely on per-instance limits.
+- Streaming responses (JSON-RPC `SendStreamingMessage` / `SubscribeToTask` and REST `/message:stream` / `/tasks/{id}:subscribe`) are bounded by `A2A_STREAM_MAX_BYTES`, `A2A_STREAM_MAX_DURATION_SECONDS`, and `A2A_STREAM_IDLE_TIMEOUT_SECONDS`; when a budget is exceeded the server ends the stream with an SSE `event: error` frame. If the very first event already exceeds the budget, REST requests are rejected with HTTP `429` `RESOURCE_EXHAUSTED` before the SSE stream starts.
 - For validation failures, missing context (`task_id` / `context_id`), or internal errors, the service attempts to return standard A2A failure events via `event_queue`.
 - Failure events include concrete error details with `failed` state.
 
@@ -1039,6 +1088,7 @@ Behavior notes:
 - `metadata.opencode.workspace.id` is declared consistently across the adapter, but current workspace-control methods do not use it to change the target project.
 - `opencode.workspaces.*` and `opencode.worktrees.*` currently wrap upstream `/experimental/workspace` and `/experimental/worktree` endpoints; treat them as experimental-upstream surfaces even when declared by the adapter.
 - Mutating methods should be treated as operator-only control-plane actions and are disabled by default.
+- Discovery responses are normalized provider-private summaries: upstream entries are filtered to stable fields only (`id`/`name`/`vcs` for projects, `id`/`type`/`name`/`branch` for workspaces, `name`/`branch` for worktrees) and never include upstream local paths (`directory`, `canonical`, worktree paths), raw entries, or credential-like fields.
 
 ### Project Discovery (`opencode.projects.list`, `opencode.projects.current`)
 
@@ -1056,8 +1106,8 @@ curl -sS http://127.0.0.1:8000/ \
 
 Response:
 
-- `opencode.projects.list` => `{"items": [...]}`
-- `opencode.projects.current` => `{"item": {...}}`
+- `opencode.projects.list` => `{"items": [{"id": "<id>", "name": "<name>", "vcs": "<vcs>"}]}` (normalized summaries; no local paths)
+- `opencode.projects.current` => `{"item": {"id": "<id>", "name": "<name>", "vcs": "<vcs>"}}` (normalized summary; no local paths)
 
 ### Workspace Discovery
 
@@ -1075,7 +1125,7 @@ curl -sS http://127.0.0.1:8000/ \
 
 Response:
 
-- `opencode.workspaces.list` => `{"items": [...]}`
+- `opencode.workspaces.list` => `{"items": [{"id": "<id>", "type": "<type>", "name": "<name>", "branch": "<branch>"}]}` (normalized summaries; no local paths)
 
 ### Workspace Mutation
 

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/docs/maintainer-architecture.md

@@ -128,4 +128,7 @@ For maintainers new to the codebase, this order usually gives the fastest payoff
 3. `src/opencode_a2a/server/application.py`
 4. `src/opencode_a2a/execution/executor.py`
 5. `src/opencode_a2a/contracts/extensions/`
+
+For security-focused contributors, `docs/security-architecture.md` additionally
+consolidates the security surface mapping and residual-risk register.
 6. `docs/guide.md`

opencode_a2a-1.3.1/docs/security-architecture.md

@@ -0,0 +1,175 @@
+# Security Architecture, Surface, and Residual Risks
+
+This document is the single source of truth for the adapter's security
+surface: network listeners and routes, authentication and authorization, input
+limits and boundary guards, outbound side effects, the end-to-end mapping from
+remote A2A input to OpenCode side effects, and the residual-risk register.
+
+It is a living document. Security-relevant changes must update the mapping and
+the risk register in the same change that alters the behavior. It complements,
+and does not replace:
+
+- [SECURITY.md](../SECURITY.md) — threat model, trust boundary, and
+  vulnerability reporting;
+- [guide.md](./guide.md) — operational configuration, defaults, and runbooks;
+- [compatibility.md](./compatibility.md) — wire-level compatibility promises.
+
+One-off audit conclusions, review records, and test plans are intentionally
+not stored here; they live in the issue/PR history of the repository.
+
+## Network Surface
+
+### Listeners and Bind
+
+- The service is a FastAPI/uvicorn app bound to `A2A_HOST:A2A_PORT`
+  (defaults `127.0.0.1:8000`).
+- Binding to a non-loopback address without `A2A_ALLOWED_HOSTS` logs a startup
+  warning (DNS-rebinding exposure); see residual risk R-3.
+
+### HTTP+JSON (REST) Routes
+
+All REST routes are served at the root path (no `/v1` prefix).
+
+| Method | Path | Purpose | Auth |
+| --- | --- | --- | --- |
+| GET | `/.well-known/agent-card.json` | Public Agent Card | Anonymous |
+| GET | `/extendedAgentCard` | Authenticated extended Agent Card | Credential |
+| POST | `/message:send` | Send a task message (unary) | Credential |
+| POST | `/message:stream` | Send a task message (SSE stream) | Credential |
+| POST | `/tasks/{id}:cancel` | Cancel a task | Credential |
+| GET/POST | `/tasks/{id}:subscribe` | Subscribe to a task stream | Credential |
+| GET | `/tasks/{id}` | Get a task | Credential |
+| GET | `/tasks` | List tasks | Credential |
+| GET/POST/DELETE | `/tasks/{id}/pushNotificationConfigs[/{push_id}]` | Push notification config (exposed-but-unsupported) | Credential |
+| POST | `/` | JSON-RPC endpoint (core + extensions) | Credential |
+| GET | `/health` | Health / runtime profile | Anonymous |
+| GET | `/openapi.json` | Sanitized OpenAPI contract | Anonymous |
+
+### JSON-RPC Surface
+
+- Core A2A methods from the SDK dispatcher: `message/send`, `message/stream`,
+  `tasks/get`, `tasks/cancel`, `tasks/list`, `tasks/subscribe`,
+  `tasks/pushNotificationConfig/*`.
+- Provider-private `opencode.*` extensions (authenticated extended card only):
+  - `opencode.sessions.*`: `status`, `list`, `messages.list`, `get`, `children`,
+    `todo`, `diff`, `message.get`, `prompt_async`, `command`, `fork`, `share`,
+    `unshare`, `summarize`, `revert`, `unrevert`, `shell`
+    (deployment-conditional);
+  - `opencode.providers.*` / `opencode.models.*`: `list_providers`,
+    `list_models`;
+  - `opencode.projects.*` / `opencode.workspaces.*` / `opencode.worktrees.*`:
+    discovery plus gated mutations (`create_workspace`, `remove_workspace`,
+    `create_worktree`, `remove_worktree`, `reset_worktree`);
+  - `opencode.interrupt.*`: `list_permissions`, `list_questions`,
+    `reply_permission`, `reply_question`, `reject_question`.
+
+### Authentication and Authorization
+
+- `A2A_STATIC_AUTH_CREDENTIALS` (Basic/Bearer) is enforced before routing on
+  every credential-protected endpoint; the public Agent Card and `/health` are
+  anonymous.
+- `credential_id` is carried as runtime metadata for audit/logging/rotation; it
+  does not participate in principal resolution or authorization.
+- Capability gates:
+  - `A2A_ENABLE_SESSION_SHELL` → `CAPABILITY_SESSION_SHELL`;
+  - `A2A_ENABLE_WORKSPACE_MUTATIONS` → `CAPABILITY_WORKSPACE_MUTATION`;
+  - enforced via `request_has_capability` at the handler boundary.
+- The runtime is a single-tenant trust boundary by design; see
+  [SECURITY.md](../SECURITY.md) for the threat model.
+
+### Input Limits and Boundary Guards
+
+| Guard | Mechanism | Defaults / Notes |
+| --- | --- | --- |
+| CSRF / Origin | `A2A_ALLOWED_ORIGINS` + `A2A_PUBLIC_URL` origin | `Origin`-bearing requests must match; `Origin: null` rejected |
+| DNS rebinding / Host | `A2A_ALLOWED_HOSTS` | Enforced when configured; startup warning otherwise on non-loopback bind |
+| Body size | `A2A_MAX_REQUEST_BODY_BYTES` | 1 MiB |
+| Rate limit | `A2A_RATE_LIMIT_ENABLED` / `_WINDOW_SECONDS` / `_MAX_REQUESTS` | On by default; 60 s window, 120 requests; 429 + `Retry-After` |
+| Stream budgets | `A2A_STREAM_MAX_BYTES` / `_MAX_DURATION_SECONDS` / `_IDLE_TIMEOUT_SECONDS` | 64 MiB / 3600 s / 120 s; `0` disables |
+| Payload logging | `A2A_LOG_PAYLOADS` / `A2A_LOG_BODY_LIMIT` | Opt-in; logs treated as sensitive |
+
+### Outbound Side Effects
+
+- `a2a_call` tool execution → `server/client_manager.py` (`borrow_client`) →
+  `client/network_policy.py` validation: http/https only, no userinfo,
+  `A2A_CLIENT_ALLOWED_HOSTS` allowlist, private/loopback address rejection, and
+  credentials attached to allowlisted hosts only.
+- CLI `opencode-a2a call` is operator-invoked and shares URL handling, but is
+  not allowlist-bound.
+- The upstream OpenCode client (`OPENCODE_BASE_URL`, auth, timeouts, concurrency
+  caps) is the only other outbound path.
+
+## Security Controls
+
+### Error Text Redaction
+
+Client-visible error text must never expose absolute local filesystem paths.
+All error responses that can leave the process pass through a single
+deterministic masker (`opencode_a2a.redact.redact_absolute_paths`) before
+serialization; masked output uses the fixed placeholder `<redacted-path>`.
+
+Boundaries covered:
+
+- Streaming task error messages — `execution/executor.py:_emit_error`
+  (task status messages and streamed error artifacts).
+- JSON-RPC error responses — `jsonrpc/error_responses.py:adapt_jsonrpc_error`
+  (message, metadata values, and standard JSON-RPC error-code `data`).
+- REST/HTTP error bodies — `jsonrpc/error_responses.py:build_http_error_body`.
+- Raw-exception fallback — `jsonrpc/application.py:_generate_error_response`
+  (SDK base-class wrapping of non-JSON-RPC exceptions).
+
+Masked: POSIX/Windows/UNC absolute paths and `file://` local URIs. Preserved:
+remote URLs (`scheme://host/path`), relative paths, ordinary prose, and
+slash-prefixed API route tokens such as `/message:send` or `/tasks/{id}:cancel`
+(a path-like token immediately followed by a `:` method suffix or `{` route
+template is treated as an API route, not a local path). Server-side logs
+intentionally retain full exception context for diagnosability; logs that
+leave the host must be redacted or access-restricted before export.
+
+Remote peer error text (for example the upstream `detail` field surfaced by
+`execution/upstream_error_translator.py`) is remote content, not a local path
+leak; it is out of scope for this control and should be assessed separately if
+it becomes a trust concern.
+
+### Release Integrity
+
+Every GitHub Release must ship a `SHA256SUMS` checksum manifest alongside the
+wheel and sdist artifacts so consumers can verify artifact integrity
+independently of the registry. `.github/workflows/publish.yml` regenerates
+`dist/SHA256SUMS` at publish time from the built assets (sorted by basename,
+`sha256sum -c` compatible) and uploads it as a release asset; existing assets
+are skipped idempotently.
+
+## End-to-End Mapping: Remote A2A Input → OpenCode Side Effects
+
+| A2A input | Adapter path | OpenCode / host side effects |
+| --- | --- | --- |
+| `message/send` / `message/stream` | REST or JSON-RPC → middleware guards → `execution/executor.py` → `opencode_upstream_client.py` | Upstream OpenCode session prompt/command; stream normalization; task/message persistence |
+| Session extension queries/mutations | `jsonrpc/handlers/session_*.py` | Read/shape session state; `fork`/`share`/`revert` mutate upstream session state |
+| Workspace/worktree control | `jsonrpc/handlers/workspace_control.py` (mutation gated) | Project/workspace/worktree create/remove/reset → filesystem side effects inside the OpenCode workspace; responses normalized (no local paths) |
+| Interrupt recovery/callback | `jsonrpc/handlers/interrupt_*.py` | Request-ID lifecycle, expiry, identity-scoped state |
+| Tool execution during a session | `execution/tool_orchestration.py` | `a2a_call` may trigger remote agent work; other tools remain OpenCode-runtime behavior |
+| Task/session persistence | `server/task_store.py`, `state_store.py`, `migrations.py` | SQLite task/state rows (hardened file access) |
+
+## Residual Risk Register
+
+| ID | Risk | Status | Mitigation / Reference |
+| --- | --- | --- | --- |
+| R-1 | Outbound DNS-rebinding TOCTOU: `a2a_call` validation resolves the host, then the connection re-resolves (resolve-then-connect) | Accepted | Allowlist + private-IP rejection reduce exposure; pinned-IP connect is not implemented. [guide.md](./guide.md) "Client Initialization Facade" |
+| R-2 | Rate limiter is process-local; multi-process deployments bypass per-credential limits | Accepted | Documented; use a gateway-level limiter or per-instance limits. [guide.md](./guide.md) "Auth, Limits, and Failure Contract" |
+| R-3 | Non-loopback bind without `A2A_ALLOWED_HOSTS` only warns at startup | Accepted | Operator contract: trusted network or reverse proxy validates Host. [guide.md](./guide.md) "Inbound Origin and Host Boundary" |
+| R-4 | Single-tenant shared-workspace boundary; static credentials only by default | Accepted by design | Threat model and tenant guidance in [SECURITY.md](../SECURITY.md) |
+| R-5 | Payload logging can capture sensitive data when enabled | Accepted | Opt-in with `A2A_LOG_BODY_LIMIT` cap; treat logs as sensitive. [SECURITY.md](../SECURITY.md) |
+| R-6 | Push notification config surface exposed-but-unsupported (HTTP 501 / JSON-RPC unsupported) | Accepted | Contract kept explicitly unsupported; capability recovery is intentionally deferred |
+| R-7 | SQLite hardening exempts `:memory:` / `file:` URIs and non-POSIX platforms | Accepted | Plain absolute file path recommended for deployments. [guide.md](./guide.md) "SQLite Persistence Hardening" |
+
+## Maintenance Rules
+
+- This document is the canonical security-surface reference. Update the route
+  table, mapping, or risk register in the same change that alters listeners,
+  routes, authentication/authorization, input limits, outbound policy,
+  persistence hardening, error-text redaction boundaries, release integrity,
+  or known residual risks.
+- Do not turn this document into a report for a specific review cycle: keep it
+  focused on facts that remain true for the current code and must stay
+  maintainable. One-off conclusions belong in issue/PR history.

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/pyproject.toml

@@ -102,3 +102,8 @@ ignore_missing_imports = true
 
 [tool.pytest.ini_options]
 addopts = "--cov=src/opencode_a2a --cov-report=term-missing --cov-report=json:.coverage.json --cov-fail-under=90"
+filterwarnings = [
+    "error::pytest.PytestUnhandledThreadExceptionWarning",
+    "error::pytest.PytestUnraisableExceptionWarning",
+    "always:.*was deleted before being closed.*:ResourceWarning:aiosqlite.core",
+]

opencode_a2a-1.3.1/src/opencode_a2a/client/network_policy.py

@@ -0,0 +1,155 @@
+"""Outbound A2A client network policy (SSRF guard and credential binding).
+
+The embedded ``a2a_call`` tool lets the upstream model choose the target URL,
+so without an explicit policy the adapter could connect to private/loopback/
+link-local addresses (cloud metadata, internal services) and would attach
+globally configured outbound credentials to any endpoint.
+
+This module centralizes the checks:
+
+- only ``http``/``https`` schemes are accepted;
+- userinfo credentials in the URL are rejected;
+- when ``A2A_CLIENT_ALLOWED_HOSTS`` is configured, the host must match the
+  allowlist (exact or ``*.example.com`` wildcard);
+- unless ``A2A_CLIENT_ALLOW_PRIVATE_HOSTS`` is set, DNS resolution results are
+  validated and private/loopback/link-local/reserved addresses are rejected
+  (DNS-rebinding defense);
+- outbound credentials may only be attached to hosts that match the allowlist.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import logging
+import socket
+from collections.abc import Sequence
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+logger = logging.getLogger(__name__)
+
+_ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+_Address = ipaddress.IPv4Address | ipaddress.IPv6Address
+
+
+class A2ANetworkPolicyError(ValueError):
+    """Raised when an outbound agent URL violates the network policy."""
+
+
+@dataclass(frozen=True)
+class NetworkPolicyDecision:
+    """Outcome of validating an outbound agent URL."""
+
+    host: str
+    allowed_host: bool
+    credentials_allowed: bool
+
+
+def matches_allowed_host(host: str, allowed_hosts: Sequence[str]) -> bool:
+    """Return whether ``host`` matches an allowlist entry.
+
+    Entries may be exact hostnames or ``*.example.com`` wildcards. A wildcard
+    matches any number of subdomain labels but never the bare apex domain.
+    """
+
+    normalized = (host or "").strip().lower().rstrip(".")
+    if not normalized:
+        return False
+    for raw_entry in allowed_hosts or ():
+        entry = (raw_entry or "").strip().lower().rstrip(".")
+        if not entry:
+            continue
+        if entry.startswith("*."):
+            suffix = entry[1:]  # ".example.com"
+            apex = suffix[1:]  # "example.com"
+            if normalized != apex and normalized.endswith(suffix):
+                return True
+        elif normalized == entry:
+            return True
+    return False
+
+
+def _is_private_address(address: _Address) -> bool:
+    return bool(
+        address.is_private
+        or address.is_loopback
+        or address.is_link_local
+        or address.is_reserved
+        or address.is_multicast
+        or address.is_unspecified
+    )
+
+
+async def resolve_host_addresses(host: str) -> tuple[str, ...]:
+    """Resolve ``host`` to a de-duplicated tuple of IP address strings."""
+
+    loop = asyncio.get_running_loop()
+    try:
+        infos = await loop.getaddrinfo(host, None, type=socket.SOCK_STREAM)
+    except socket.gaierror as exc:
+        raise A2ANetworkPolicyError(f"Agent URL host could not be resolved: {host!r}") from exc
+    addresses: list[str] = []
+    for info in infos:
+        ip = str(info[4][0])
+        if ip not in addresses:
+            addresses.append(ip)
+    return tuple(addresses)
+
+
+async def validate_agent_url(
+    agent_url: str,
+    *,
+    allowed_hosts: Sequence[str] | None = None,
+    allow_private_hosts: bool = False,
+) -> NetworkPolicyDecision:
+    """Validate an outbound agent URL against the configured network policy."""
+
+    normalized = (agent_url or "").strip()
+    if not normalized:
+        raise A2ANetworkPolicyError("agent_url is required")
+
+    parsed = urlsplit(normalized)
+    scheme = (parsed.scheme or "").lower()
+    if scheme not in _ALLOWED_SCHEMES:
+        raise A2ANetworkPolicyError(
+            f"Agent URL scheme must be http or https, got {scheme or 'empty'}"
+        )
+    host = (parsed.hostname or "").strip().lower()
+    if not host:
+        raise A2ANetworkPolicyError("Agent URL must include a host")
+    if parsed.username or parsed.password:
+        raise A2ANetworkPolicyError("Agent URL must not include userinfo credentials")
+
+    allowlist = tuple(
+        (item or "").strip().lower().rstrip(".")
+        for item in allowed_hosts or ()
+        if (item or "").strip()
+    )
+    matched = matches_allowed_host(host, allowlist)
+    if allowlist and not matched:
+        raise A2ANetworkPolicyError(
+            f"Agent URL host {host!r} is not allowed by A2A_CLIENT_ALLOWED_HOSTS"
+        )
+
+    if not allow_private_hosts:
+        try:
+            addresses = await resolve_host_addresses(host)
+        except A2ANetworkPolicyError:
+            raise
+        except OSError as exc:
+            raise A2ANetworkPolicyError(f"Agent URL host could not be resolved: {host!r}") from exc
+        private = [
+            address for address in addresses if _is_private_address(ipaddress.ip_address(address))
+        ]
+        if private:
+            raise A2ANetworkPolicyError(
+                f"Agent URL host {host!r} resolves to a private/loopback address: {private[0]}"
+            )
+
+    return NetworkPolicyDecision(
+        host=host,
+        allowed_host=matched,
+        credentials_allowed=bool(allowlist) and matched,
+    )

{opencode_a2a-1.2.0 → opencode_a2a-1.3.1}/src/opencode_a2a/client/request_context.py

@@ -79,16 +79,13 @@ def build_call_context(
     if extra_headers:
         merged_headers.update(extra_headers)
     normalized_extensions = [value for value in (extensions or ()) if value]
-    service_parameters = None
-    if normalized_extensions:
-        service_parameters = ServiceParametersFactory.create_from(
-            None,
-            [with_a2a_extensions(normalized_extensions)],
-        )
-    return ClientCallContext(
-        state={
-            "headers": dict(merged_headers),
-            "http_kwargs": {"headers": dict(merged_headers)},
-        },
-        service_parameters=service_parameters,
+    service_parameter_updates = (
+        [with_a2a_extensions(normalized_extensions)] if normalized_extensions else []
     )
+    # a2a-sdk transports serialize service parameters as HTTP headers or gRPC
+    # metadata. This is also the channel used by the SDK's AuthInterceptor.
+    service_parameters = ServiceParametersFactory.create_from(
+        merged_headers,
+        service_parameter_updates,
+    )
+    return ClientCallContext(service_parameters=service_parameters)