diff --git a/.mypy-untyped-defs-baseline b/.mypy-untyped-defs-baseline index 2c36bbdaa0..0d389107a3 100644 --- a/.mypy-untyped-defs-baseline +++ b/.mypy-untyped-defs-baseline @@ -1 +1 @@ -227 +212 diff --git a/.ruff-complexity-baseline b/.ruff-complexity-baseline index bdb3591baa..287e328e0d 100644 --- a/.ruff-complexity-baseline +++ b/.ruff-complexity-baseline @@ -1,5 +1,5 @@ { - "C901": 183, - "PLR0912": 134, - "PLR0915": 108 + "C901": 181, + "PLR0912": 133, + "PLR0915": 106 } diff --git a/docker-compose.e2e.yml b/docker-compose.e2e.yml index 39a09f80f2..0288f9b69f 100644 --- a/docker-compose.e2e.yml +++ b/docker-compose.e2e.yml @@ -58,6 +58,10 @@ services: SUPER_ADMIN_EMAILS: ${SUPER_ADMIN_EMAILS:-} ADCP_TESTING: ${ADCP_TESTING:-true} ADCP_AUTH_TEST_MODE: ${ADCP_AUTH_TEST_MODE:-true} + # Exact callback host admitted by the development-only protocol webhook + # seam. Standalone host tests override this with host.docker.internal; + # the in-network runner uses its stable "tests" alias. + ADCP_WEBHOOK_TEST_HOST: ${ADCP_WEBHOOK_TEST_HOST:-tests} # The SERVER must know about the pinned in-network creative agent: sync/ # create flows resolve format specs server-side, and references carry the # PUBLIC canonical agent_url — without this, the registry's connection @@ -180,6 +184,9 @@ services: # network alias (requires `docker compose run --use-aliases`). 'tests' is # not 'localhost', so the server does NOT rewrite it to host.docker.internal. ADCP_WEBHOOK_HOST: tests + # Exact in-network callback host allowed only by the development-mode + # protocol-webhook validator. Production has no private-host override. + ADCP_WEBHOOK_TEST_HOST: tests # Pinned reference creative agent, reachable in-network by service name # (no host :9999). Clears the 18 test_creative_agent_live integration tests. CREATIVE_AGENT_URL: http://creative-agent:8080/api/creative-agent diff --git a/docker-compose.yml b/docker-compose.yml index eca3fd0367..6d08e274cf 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -86,6 +86,12 @@ services: ADCP_SALES_PORT: "8080" # Enable test login mode for development ADCP_AUTH_TEST_MODE: "true" + # Declare development EXPLICITLY. Security gates that relax for development fail + # closed on an absent or unrecognised value, so the relaxation has to be stated + # rather than inferred from omission — see + # WebhookURLValidator._require_https_for_callback, which requires HTTPS for AdCP + # callbacks unless this reads "development". docker-compose.e2e.yml already sets it. + ENVIRONMENT: development # Development settings (venv at /opt/venv in image — see Dockerfile UV_PROJECT_ENVIRONMENT) PYTHONPATH: "/app" PYTHONUNBUFFERED: "1" diff --git a/docs/adcp-spec-version.md b/docs/adcp-spec-version.md index 792192164f..a0a344528a 100644 --- a/docs/adcp-spec-version.md +++ b/docs/adcp-spec-version.md @@ -41,24 +41,18 @@ uv run python -c "import adcp; print(adcp.get_adcp_spec_version())" across `pyproject.toml`, the test's `EXPECTED_SPEC_VERSION` constant, and this document. -## Behavior target vs SDK pin - -The SDK **pin** (3.1.0-beta.3) fixes the request/response *type shapes* we -build against. It does **not** always fix the graded *behavior*. One field -diverges deliberately: the `media_buy_status` dual-emit on -create-/update-media-buy responses. - -- **beta.3 storyboard** (`dist/compliance/3.1.0-beta.3/.../pending_creatives_to_start.yaml`, - ~L131-134) grades the body `status` as `field_value_or_absent` that MUST equal - `media_buy_status` — the deprecated "both identical" model (#4908). -- **Target GA** — graded by the published **3.1.0** compliance - (`dist/compliance/3.1.0/.../pending_creatives_to_start.yaml`, ~L146-153; - `3.1.1` is byte-identical for this storyboard) — grades `media_buy_status` - as `field_value` (the DOMAIN status) and the top-level `status` as - `field_value` `'completed'` (the PROTOCOL `TaskStatus`, protocol envelope). - The two are DIFFERENT namespaces and are NOT identical. - -Our wire already implements the divergent (target GA) model: +## Behavior sources vs SDK pin + +The pin and the behavior target are the same version (3.1.1). What differs is +the ROLE of each artifact: the SDK **pin** fixes the request/response *type +shapes* we build against, and it does not replace the authoritative prose and +compliance storyboards for protocol behavior. For example, the published +**3.1.1** `pending_creatives_to_start.yaml` storyboard grades `media_buy_status` +as `field_value` (the DOMAIN status) and the top-level `status` as +`field_value` `'completed'` (the PROTOCOL `TaskStatus`, protocol envelope). +The two are DIFFERENT namespaces and are NOT identical. + +Our wire implements that two-namespace model: `TaskResultEnvelope._serialize` sets the top-level `status` to the protocol `TaskStatus`, while the domain status survives under `media_buy_status` (`src/core/schemas/_base.py` `_mirror_media_buy_status`). The dual-emit @@ -66,7 +60,7 @@ validator only backfills the deprecated **body** `status` from the domain `media_buy_status` for the deprecation window; it does not touch the wire top-level `status`. -**Known SDK type defect (SDK not authoritative):** adcp 5.7 types the response +**Historical SDK type defect (SDK not authoritative):** adcp 5.7 typed the response `status` as `MediaBuyStatus | None`, but the wire top-level `status` carries a protocol `TaskStatus` (`submitted` / `completed`). This is fine because that protocol value lives on `TaskResultEnvelope.status` (typed `str`), never on the @@ -77,6 +71,67 @@ SDK-typed body field. Grounding for the divergent behavior is the value-pinned `tests/bdd/steps/domain/uc002_create_media_buy.py` (see PR #1417). `tests/unit/test_adcp_spec_version.py` only guards the SDK pin, not this behavior. +## Authentication error classification + +The immutable AdCP **v3.1.1** source is tag `v3.1.1`, commit +`467fd93d77112baf9e094e18980119edcd3a4d07`. Its +`static/schemas/source/enums/error-code.json` metadata requires sellers to +return: + +- `AUTH_MISSING` when no standard `Authorization` header was included + (`correctable`: provide credentials and retry). +- `AUTH_INVALID` when an `Authorization` header was present but rejected + (`terminal`, except the spec's one-time OAuth refresh allowance). + +Prebid Sales Agent applies that split at every A2A, MCP, and REST wire +boundary. The legacy `x-adcp-auth` extension remains accepted as an input +channel, but it does not change the standard header-presence classifier. +Direct `_impl` helpers retain deprecated `AUTH_REQUIRED` only where no wire +credential-presence information exists. + +This behavior is **ungraded** by the official conformance storyboards: +`dist/compliance/3.1.1/universal/error-compliance.yaml` contains no +`AUTH_*` scenario. The two codes are covered by the repository's cross-transport +wire tests, and by the pinned fixture at +`tests/fixtures/adcp_schemas_pinned/enums/error-code.json`. + +### What the pinned fixture does and does not vendor + +The fixture tree is vendored at commit `04f59d2d5` (the v3.1 cut, 2026-05-13), **not** +at `v3.1.1`. The two AUTH entries above are transplanted from `467fd93d` and declared as +a supplement in `tests/fixtures/adcp_schemas_pinned/_refresh.py`, because production +emits both codes and the recovery-conformance guard resolves them against this file. + +So the fixture is **not** a complete v3.1.1 vocabulary: it carries the base commit's +codes plus exactly that declared supplement, and it lags published 3.1.1 by a number of +codes and several `enumMetadata` suggestion texts. That gap is real and tracked +separately — the point of declaring it is that the tree no longer claims a fidelity it +does not have. + +`tests/unit/test_pinned_schema_provenance.py` enforces the claim against the bytes: +`PINNED_SHA` must match the generated `_manifest.py`, every vendored file must match its +recorded digest, and the error-code enum must equal the base vocabulary plus exactly the +declared supplement. Advancing the pin therefore requires actually re-running +`_refresh.py` — editing the constant alone fails. + +## Protocol callback URL transport policy + +The pinned AdCP **v3.1.1** source defines +`static/schemas/source/core/push-notification-config.json#properties/url` as a +generic URI. It does not mandate acceptance of plaintext HTTP callback URLs. +The authoritative +`dist/compliance/3.1.1/universal/webhook-emission.yaml` storyboard (version +1.3.0) uses an operator-supplied **HTTPS** receiver in `proxy_url` mode and +grades payload idempotency, operation correlation, retry behavior, and RFC 9421 +signing. It does not grade whether an implementation accepts HTTP callback +registration. + +Prebid Sales Agent therefore treats HTTPS-only production callbacks as an +implementation security policy: production rejects HTTP before persisting or +sending a callback, while the exact-host development seam remains available +for the Docker E2E receiver. This restriction is **ungraded** by the 3.1.1 +storyboard and does not replace its signing or idempotency requirements. + ## Wire negotiation AdCP wire values for `adcp_version` are release-precision (`"3.0"`, diff --git a/docs/test-obligations/BR-UC-011-manage-accounts.md b/docs/test-obligations/BR-UC-011-manage-accounts.md index cce03ba056..c0079c4f0a 100644 --- a/docs/test-obligations/BR-UC-011-manage-accounts.md +++ b/docs/test-obligations/BR-UC-011-manage-accounts.md @@ -115,7 +115,7 @@ High impact. Account management is a new protocol domain in adcp 3.x. The schema **Layer** behavioral **Given** no authentication **When** the buyer sends `sync_accounts` -**Then** the request is rejected with AUTH_REQUIRED +**Then** every wire transport rejects the request with AUTH_MISSING **Business Rule:** BR-12 **Priority:** P0 @@ -209,14 +209,14 @@ High impact. Account management is a new protocol domain in adcp 3.x. The schema **Business Rule:** BR-10 **Priority:** P0 -### Extension A: AUTH_REQUIRED +### Extension A: Authentication errors #### Scenario: Missing auth token on sync_accounts **Obligation ID** UC-011-EXT-A-01 **Layer** behavioral **Given** no Bearer token in request **When** the buyer sends `sync_accounts` -**Then** the response is error variant with `AUTH_REQUIRED` +**Then** every wire transport returns an error variant with `AUTH_MISSING` **And** no accounts are modified **And** context is echoed **Business Rule:** BR-12, POST-F1 @@ -227,7 +227,7 @@ High impact. Account management is a new protocol domain in adcp 3.x. The schema **Layer** behavioral **Given** an expired Bearer token **When** the buyer sends `sync_accounts` -**Then** the response is error variant with `AUTH_REQUIRED` +**Then** every wire transport returns an error variant with `AUTH_INVALID` **Priority:** P1 #### Scenario: Malformed auth token on sync_accounts @@ -235,7 +235,7 @@ High impact. Account management is a new protocol domain in adcp 3.x. The schema **Layer** behavioral **Given** a malformed Bearer token **When** the buyer sends `sync_accounts` -**Then** the response is error variant with `AUTH_REQUIRED` +**Then** every wire transport returns an error variant with `AUTH_INVALID` **Priority:** P1 ### Extension B: SYNC_PARTIAL_FAILURE @@ -394,7 +394,7 @@ High impact. Account management is a new protocol domain in adcp 3.x. The schema **Obligation ID** UC-011-EXT-G-03 **Layer** schema **Given** an unauthenticated buyer sending sync_accounts with `context: {"trace": "t1"}` -**When** the AUTH_REQUIRED error is returned +**When** the wire transport returns AUTH_MISSING **Then** the error response includes `context: {"trace": "t1"}` **Business Rule:** POST-F3 **Priority:** P1 @@ -430,7 +430,7 @@ High impact. Account management is a new protocol domain in adcp 3.x. The schema #### Scenario: sync-accounts-response error variant **Obligation ID** UC-011-SCHEMA-03 **Layer** schema -**Given** an operation-level error response (e.g., AUTH_REQUIRED) +**Given** an operation-level error response (e.g., AUTH_MISSING, AUTH_INVALID, or AUTH_REQUIRED) **When** serialized **Then** it validates against `sync-accounts-response.json` (error oneOf variant) **And** has errors array diff --git a/docs/test-obligations/UC-002-create-media-buy.md b/docs/test-obligations/UC-002-create-media-buy.md index 466c534fcb..569c880cf0 100644 --- a/docs/test-obligations/UC-002-create-media-buy.md +++ b/docs/test-obligations/UC-002-create-media-buy.md @@ -768,7 +768,8 @@ Source: UC-002-ext-c.md, BR-RULE-013 **Layer** schema **Given** `start_time` is an ISO 8601 datetime that is in the past **When** the system validates timing -**Then** it returns error: "Invalid start time: {value}. Start time cannot be in the past." +**Then** it returns `INVALID_REQUEST` with static message "Start time cannot be in the past." +**And** the error identifies `field: start_time`, includes a corrective suggestion, and does not echo request timestamps **Business Rule:** BR-RULE-013 INV-2 **Priority:** P0 @@ -777,7 +778,8 @@ Source: UC-002-ext-c.md, BR-RULE-013 **Layer** schema **Given** `end_time` is before or equal to `start_time` **When** the system validates timing -**Then** it returns error: "Invalid time range: end time ({end}) must be after start time ({start})." +**Then** it returns `INVALID_REQUEST` with static message "End time must be after start time." +**And** the error identifies `field: end_time`, includes a corrective suggestion, and does not echo request timestamps **Business Rule:** BR-RULE-013 INV-3 **Priority:** P0 diff --git a/docs/test-obligations/bdd-traceability.yaml b/docs/test-obligations/bdd-traceability.yaml index 54e25e8325..ebc781cf9d 100644 --- a/docs/test-obligations/bdd-traceability.yaml +++ b/docs/test-obligations/bdd-traceability.yaml @@ -876,6 +876,12 @@ mappings: upstream_refs: ["BR-UC-002-ext-d"] business_rules: [] status: new + - adcp_scenario_id: "T-UC-002-ext-nl-unsupported" + adcp_feature: "BR-UC-002-create-media-buy.feature" + obligation_id: null + upstream_refs: ["transport-errors.mdx#Layer-Separation"] + business_rules: [] + status: new - adcp_scenario_id: "T-UC-002-ext-e" adcp_feature: "BR-UC-002-create-media-buy.feature" obligation_id: null diff --git a/docs/test-obligations/business-rules.md b/docs/test-obligations/business-rules.md index a3376934ed..3aaf6a0ce5 100644 --- a/docs/test-obligations/business-rules.md +++ b/docs/test-obligations/business-rules.md @@ -931,16 +931,17 @@ Then an empty accounts array is returned (not an error) ### BR-RULE-055: Account Operation Authentication Policy **Obligation ID** BR-RULE-055-01 **Layer** behavioral -**Invariant:** sync_accounts requires valid auth. list_accounts works without auth but scopes results. Unauthenticated list returns empty array. +**Invariant:** sync_accounts and list_accounts require valid auth. list_accounts scopes results to accounts visible to the authenticated agent. +**Grounded in:** dist/docs/3.1.1/accounts/tasks/list_accounts.mdx:8 ("Returns all accounts the authenticated agent can operate..."); dist/docs/3.1.1/protocol/required-tasks.mdx:118 (list_accounts discovers "seller-assigned accounts" for a resolved credential, unlike the plain "Required" no-auth-caveat discovery tasks in the same table). Not a single explicit "MUST require authentication" sentence — inferred consistently across both passages from a task that is meaningless without a resolved identity to scope against. **Scenario:** ```gherkin -Given no valid authentication -When sync_accounts is called -Then AUTH_REQUIRED error is returned - Given no authentication -When list_accounts is called -Then an empty accounts array is returned (not an error) +When sync_accounts or list_accounts is called +Then every wire transport returns AUTH_MISSING + +Given rejected authentication credentials +When sync_accounts or list_accounts is called +Then every wire transport returns AUTH_INVALID ``` **Priority:** P0 **Affected by 3.6:** Yes -- accounts domain is new in v3 diff --git a/docs/test-obligations/constraints.md b/docs/test-obligations/constraints.md index 5a8e237db4..dcf7da499d 100644 --- a/docs/test-obligations/constraints.md +++ b/docs/test-obligations/constraints.md @@ -1635,11 +1635,14 @@ Then status=pending_approval with setup.message ### account_auth_policy: Account Authentication Policy **Obligation ID** CONSTR-ACCOUNT-AUTH-POLICY-01 **Layer** behavioral -**Requirement:** sync_accounts requires valid auth. list_accounts allows anonymous (empty results). +**Requirement:** sync_accounts and list_accounts require valid authentication. **Scenario:** ```gherkin -Given no auth on sync_accounts -Then AUTH_REQUIRED error +Given no auth on sync_accounts or list_accounts +Then every wire transport returns AUTH_MISSING + +Given rejected auth on sync_accounts or list_accounts +Then every wire transport returns AUTH_INVALID ``` **Priority:** P0 **Affected by 3.6:** Yes -- accounts domain is new in v3 diff --git a/src/a2a_server/adcp_a2a_server.py b/src/a2a_server/adcp_a2a_server.py index 2c4c49a097..e5be20bb87 100644 --- a/src/a2a_server/adcp_a2a_server.py +++ b/src/a2a_server/adcp_a2a_server.py @@ -8,11 +8,12 @@ import json import logging import uuid -from collections.abc import AsyncGenerator, Awaitable, Callable +from collections.abc import AsyncGenerator, Awaitable, Callable, Iterator +from contextlib import contextmanager # Import core functions for direct calls (raw functions without FastMCP decorators) from datetime import UTC, datetime -from typing import Any +from typing import TYPE_CHECKING, Any from a2a.server.context import ServerCallContext from a2a.server.events.event_queue import Event @@ -36,11 +37,11 @@ ListTasksRequest, ListTasksResponse, Message, - MethodNotFoundError, Part, SendMessageRequest, SubscribeToTaskRequest, Task, + TaskNotCancelableError, TaskNotFoundError, TaskPushNotificationConfig, TaskState, @@ -54,25 +55,30 @@ from google.protobuf import json_format, struct_pb2 from src.core.audit_logger import get_audit_logger -from src.core.auth import AUTH_REQUIRED_SUGGESTION from src.core.auth_context import AUTH_CONTEXT_STATE_KEY +from src.core.auth_policy import AUTH_OPTIONAL_SKILLS from src.core.database.models import PushNotificationConfig as DBPushNotificationConfig from src.core.database.repositories import PushNotificationConfigUoW +from src.core.database.repositories.workflow import TERMINAL_STEP_STATUSES, WorkflowRepository from src.core.domain_config import get_a2a_server_url from src.core.exceptions import ( AdCPAuthenticationError, - AdCPAuthRequiredError, + AdCPAuthInvalidError, + AdCPAuthMissingError, AdCPCapabilityNotSupportedError, + AdCPConfigurationError, AdCPError, AdCPValidationError, build_two_layer_error_envelope, - normalize_to_adcp_error, + classify_auth_credentials_error, + safe_adcp_error, ) from src.core.resolved_identity import ResolvedIdentity from src.core.schema_helpers import coerce_creative_filters, to_account_reference, to_brand_reference from src.core.schemas import CreativeStatusEnum +from src.core.schemas.creative import AssignCreativeRequest, CreateCreativeRequest from src.core.tool_context import ToolContext -from src.core.tool_error_logging import record_boundary_error +from src.core.tool_error_logging import best_effort_boundary_identity, record_boundary_error from src.core.tools import ( create_media_buy_raw as core_create_media_buy_tool, ) @@ -119,6 +125,11 @@ ) from src.services.protocol_webhook_service import get_protocol_webhook_service +if TYPE_CHECKING: + from sqlalchemy.orm import Session + + from src.core.database.models import WorkflowStep + logger = logging.getLogger(__name__) @@ -170,83 +181,368 @@ def _dict_to_struct(d: dict) -> struct_pb2.Struct: return s -# ADCP Discovery Skills: Skills that don't require authentication -# Per AdCP spec section 3.2, these endpoints allow optional authentication for public discovery. -# IMPORTANT: This is the single source of truth for auth-optional skills in A2A. -# Add new skills here ONLY if they meet AdCP discovery endpoint requirements: +# AdCP discovery skills that don't require authentication. +# dist/docs/3.1.1/protocol/required-tasks.mdx documents get_products, +# get_adcp_capabilities, and list_creative_formats as plain "Required" discovery +# tasks with no auth caveat. list_accounts is deliberately NOT in this set: +# dist/docs/3.1.1/accounts/tasks/list_accounts.mdx:8 scopes it to "the +# authenticated agent", and required-tasks.mdx:118 ties it to discovering +# "seller-assigned accounts" for a resolved credential — a question that has +# no meaning without an authenticated identity to scope against, unlike the +# genuinely public data the four skills below return. +# The transport-neutral set in auth_policy is the single source of truth. +# Add new skills there ONLY if they meet AdCP discovery endpoint requirements: # 1. Return only public/non-sensitive data # 2. Support tenant-level access control (e.g., brand_manifest_policy) # 3. Never expose user-specific or transactional data # 4. Must be safe to call without authentication -DISCOVERY_SKILLS = frozenset( - { - "get_adcp_capabilities", # Agent capabilities (always public per AdCP spec) - "list_accounts", # Account discovery (public, returns empty for unauthed per BR-RULE-055) - "list_creative_formats", # Creative specifications (always public) - "list_authorized_properties", # Property catalog (always public) - "get_products", # Conditional: depends on tenant brand_manifest_policy setting - } -) +DISCOVERY_SKILLS = AUTH_OPTIONAL_SKILLS + +# Skills whose result can be NON-TERMINAL (submitted, awaiting an out-of-band decision). +# This set governs the push-notification injection: a skill that can answer +# asynchronously is exactly the one whose buyer needs a completion callback. +_ASYNC_TASK_SKILLS = frozenset({"create_media_buy", "sync_creatives", "update_media_buy"}) + +# The subset whose outer ``task_*`` id is threaded through to the durable workflow step, +# so ``tasks/get`` reconciles against it, ``tasks/cancel`` resolves it, and +# ``resolve_webhook_task_id`` keys the completion webhook on it. Derived from the set +# above rather than maintained as a second literal. +# +# ``create_media_buy`` and ``update_media_buy`` bear the id: each call produces at most +# ONE approval step, so the buyer's id names exactly one durable row. +# +# ``sync_creatives`` does NOT, and must not: it creates one workflow step PER CREATIVE +# (``_create_sync_workflow_steps`` loops the creatives needing approval). Stamping the +# single outer id on every one of them makes the key ambiguous — the lookup resolves an +# arbitrary one of N, so a cancel would report CANCELED while the other N-1 kept running +# and later fired their own webhooks. With no id persisted, a sync task resolves to no +# durable step and ``tasks/cancel`` returns an honest ``TaskNotCancelableError``; the +# completion webhook keys on ``step_id`` instead, which is the pre-existing behavior and +# is graded by ``tests/unit/test_creative_webhook_correlation.py``. +_TASK_ID_BEARING_SKILLS = _ASYNC_TASK_SKILLS - {"sync_creatives"} + + +def _sanitized_envelope(exc: Exception) -> tuple[AdCPError, dict[str, Any]]: + """THE A2A sanitize→envelope composition: ``(safe_adcp_error(exc), its two-layer envelope)``. + + Single home for the pipeline every A2A error surface uses — the top-level + ``_internal_error_for`` (→ JSON-RPC ``InternalError``), the per-skill + ``_build_error_envelope`` (→ failed-Task artifact), and the per-skill seam (which + re-raises the sanitized error and lets the dispatcher envelope it). Internal/infra + errors — the SERVICE_UNAVAILABLE family AND terminal ``CONFIGURATION_ERROR`` (whose + secret-decryption raise sites can interpolate a connection string) — are scrubbed to + a generic message with wire code/recovery preserved; client-correctable typed errors + pass through unchanged. The policy lives in ``src/core/exceptions.py`` so the webhook + push path (``ContextManager.audit_workflow_step_failure``) shares one definition. + New buyer-facing error surfaces must use this policy rather than adding another + normalizer that trusts a typed message verbatim. + """ + sanitized = safe_adcp_error(exc) + return sanitized, build_two_layer_error_envelope(sanitized) + + +def _enveloped_invalid_request(exc: AdCPError) -> InvalidRequestError: + """JSON-RPC ``InvalidRequestError`` carrying ``exc``'s sanitized two-layer envelope in ``data``. + + Spec (AdCP 3.1.1 ``building/operating/transport-errors.mdx``): JSON-RPC ``error.data`` is a + sanctioned transport-envelope location, and ``error.data.adcp_error`` is a MUST-check in the + client detection order — so a protocol-level rejection can stay a JSON-RPC error AND still let + a buyer branch on the AdCP code. "Stays on the JSON-RPC wire" and "carries the envelope in + ``data``" are orthogonal; every AdCP-layer rejection routed through this helper does both. + (On the v0.3 method aliases the compat adapter drops ``data`` regardless — see + ``_internal_error_for`` for the measurement and #1670.) + + Twelve raises in this module deliberately BYPASS this helper and ship envelope-free, + because each signals a transport-protocol condition with no corresponding AdCP wire code. + All twelve, not the subset this docstring used to name: + + - ``TaskNotFoundError`` × 4 — unknown/unowned task id on tasks/get, tasks/cancel and the + two push-config lookups. + - ``UnsupportedOperationError`` × 3 — task listing/subscription and the extended agent card. + - ``InvalidParamsError`` × 3 — a required JSON-RPC parameter is absent (``id``, ``url``). + Note this same TYPE also ships WITH an envelope when the rejection is AdCP-layer rather + than protocol-layer (the SSRF webhook-URL check routes through this helper), so the type + alone does not tell you the shape — the layer does. + - ``TaskNotCancelableError`` × 3 — a terminal task cannot be canceled, and (the third) + a task with no durable workflow step behind it cannot be canceled either: cancelling + only this process's in-memory copy would report a stop that did not happen. + + Bypassing also skips ``record_boundary_error``, so none of the thirteen produces a server + log, activity-feed row or audit row, where REST's ``_envelope_response`` records the + analogous not-found. That is deliberate for buyer-correctable protocol outcomes (an + unknown task id is not a seller-side incident) but it is a real observability gap for the + operator; widening it is tracked separately rather than folded in here. + + Both wire layers carry the SAME sanitized message — the JSON-RPC ``message`` is taken from the + envelope — so ``error.message`` and ``error.data.adcp_error.message`` can never disagree. + """ + sanitized, envelope = _sanitized_envelope(exc) + return InvalidRequestError(message=sanitized.message, data=envelope) + + +def _a2a_auth_headers(context: ServerCallContext | None) -> dict[str, str]: + """Return a mutable copy of the headers captured by the A2A auth middleware.""" + auth_ctx = context.state.get(AUTH_CONTEXT_STATE_KEY) if context is not None else None + return dict(auth_ctx.headers) if auth_ctx else {} + + +def _no_usable_identity_error( + identity: ResolvedIdentity | None, +) -> AdCPAuthMissingError | AdCPAuthInvalidError | None: + """Classify a missing identity separately from rejected credentials.""" + if identity is None: + return AdCPAuthMissingError("Authentication required for skill invocation") + if not identity.principal_id: + return AdCPAuthInvalidError("Authentication credentials were rejected.") + return None + + +def _enveloped_auth_error( + auth_error: AdCPAuthenticationError, +) -> InvalidRequestError: + """THE single source for every A2A auth rejection's observability and envelope. + + Covers five auth raises: the missing-token, resolution-failure, and invalid-principal arms of + ``_resolve_a2a_identity`` (inherited by tasks/get, tasks/cancel and the four + push-notification-config methods), the ``message/send`` pre-dispatch check, and the standalone + ``_handle_explicit_skill`` identity guard. Before this, only ``message/send`` carried the + envelope, so a buyer got it there and nowhere else. Missing credentials emit AUTH_MISSING with + correctable recovery; rejected credentials emit AUTH_INVALID with terminal recovery. + (``_resolve_a2a_identity`` has a SIXTH raise — no resolvable tenant for + an otherwise-authenticated principal — that is a seller-side config failure, not an auth + failure, and deliberately routes through ``_enveloped_invalid_request`` with + ``AdCPConfigurationError`` instead; it is excluded from this helper by design, not by omission.) + + Takes the TYPED error rather than a message + optional cause: the wire code, recovery, and + pinned-spec ``suggestion`` then all come from the class defaults (one definition, never re-specified + per raise site), no argument can be silently discarded, and a non-auth ``AdCPError`` cannot be + adopted by a function documented as the authentication-envelope source — that would emit a different wire + code from here. Non-auth rejections use ``_enveloped_invalid_request`` directly. + """ + return _recorded_a2a_auth_rejection(auth_error) + + +def _recorded_a2a_auth_rejection( + error: AdCPError, + *, + principal_id: str | None = None, +) -> InvalidRequestError: + """Record one pre-handler A2A auth rejection, then build its wire envelope. + + Authentication failures remain tenant-unscoped because client-controlled + routing headers do not attest tenant ownership. The helper accepts + ``AdCPError`` because the tenant-resolution failure is a seller-side + ``AdCPConfigurationError`` rather than a buyer auth error; that path may + retain its already-authenticated principal for the privileged server log. + """ + record_boundary_error( + "a2a", + "authentication", + error, + tenant_id=None, + principal_id=principal_id, + ) + return _enveloped_invalid_request(error) def _internal_error_for(operation: str, exc: Exception) -> InternalError: - """Canonical InternalError shape for non-skill A2A boundary failures. - - Skill handlers raise typed ``AdCPError`` (or untyped exceptions that the - dispatcher normalizes), and ``_handle_explicit_skill`` → ``on_message_send`` - surface those as a two-layer envelope on a failed Task's DataPart. Non-skill - paths (``on_message_send`` fallthrough, NL handlers) historically picked their - own prefixes (``"Message processing failed: "``, ``"Error in ..."``) - for semantically identical untyped failures — divergence on the buyer- - facing wire message for the same condition. - - Use this helper at every non-skill ``InternalError(...)`` raise site that - is NOT a deliberate protocol-level convention (see push-notif handlers - below). The canonical prefix is ``"{operation} failed: {exc}"`` so - storyboard runners can parse the failure uniformly. - - The four ``on_*_task_push_notification_config`` JSON-RPC protocol methods use - this helper too — they have no async Task to carry a DataPart, so the two-layer - envelope rides in the error's ``data`` field (``error.data["errors"][0]["code"]`` - / ``error.data["adcp_error"]``). ``InternalError`` stays an ``A2AError`` so the - SDK's ``JsonRpcDispatcher`` serializes it as a structured JSON-RPC error; raising - a non-``A2AError`` (e.g. ``AdCPAdapterError``) would hit the dispatcher's - ``except Exception`` branch and be flattened to a bare ``InternalError`` with no - envelope. + """Canonical JSON-RPC ``InternalError`` for A2A boundary failures — SANITIZED. + + Security (transport-errors.mdx "Security Considerations" § Seller Requirements): raw exception text may + contain credentials, connection strings, SQL, hostnames, filesystem paths, or + upstream responses and MUST NOT reach the client. So: + + - A TYPED ``AdCPError`` passes through with its own wire code, but the message + placed on the JSON-RPC layer is the SANITIZED one from ``_sanitized_envelope`` — + a typed internal-bucket error (``AdCPAdapterError`` et al.) can interpolate + ``str(e)`` into its message, so the ORIGINAL ``exc.message`` must never be + used here (it would leak through ``error.message`` even while ``error.data`` + is scrubbed). + - An UNTYPED exception is replaced with a generic message; the raw ``str(exc)`` is + NEVER placed on the wire (callers log it server-side via ``record_boundary_error``). + The envelope CODE comes from ``safe_adcp_error``, which normalizes semantics before + scrubbing presentation — so a mapped built-in keeps its client-correctable code + (``ValueError`` → VALIDATION_ERROR, ``PermissionError`` → AUTH_REQUIRED) and only a + genuinely unmapped exception falls through to ``SERVICE_UNAVAILABLE``. + + ``InternalError`` stays an ``A2AError`` so the SDK's ``JsonRpcDispatcher`` + serializes it as a structured JSON-RPC error (the four + ``on_*_task_push_notification_config`` methods, the durable ``on_get_task`` / + ``on_cancel_task`` boundaries, and the untyped-crash branch of + ``on_message_send``, all raise through here). The two-layer envelope is attached + as the error's ``data`` (``error.data["adcp_error"]`` / ``error.data["errors"][0]``). + + WHETHER THE BUYER RECEIVES THAT ``data`` DEPENDS ON THE METHOD NAME THEY CALLED. + The app builds its A2A routes with ``enable_v0_3_compat=True`` (``src/app.py``), and + dispatch is selected by method name, so the v0.3 aliases reach + ``a2a/compat/v0_3/jsonrpc_adapter.py``. That adapter's ``handle_request`` has no + ``except A2AError`` arm — only ``except Exception -> CoreInternalError(message=str(e))``, + which takes no ``data`` — so on those names the error is REBUILT as ``-32603`` with + ``data: null`` and only the (already-sanitized) message survives. Measured on an auth + rejection: ``GetTask``/``CancelTask`` return ``-32600`` + envelope; ``tasks/get`` / + ``tasks/cancel`` return ``-32603`` + ``data: null``. The installed ``adcp`` client emits + the v0.3 names, so this is the common path, not a fringe one. + + Nothing leaks — the flattened message is the scrubbed text — but the buyer loses the + machine-readable code they are told to branch on. Raising the typed error here is still + correct: it is what will surface the envelope once the compat adapter maps ``A2AError``. + Tracked in #1670; graded in both directions by ``_TASK_METHOD_DISPATCH`` in + ``tests/unit/test_a2a_transport_contract.py``, so the day that lands, this docstring + goes red with it. + """ + adcp_error, envelope = _sanitized_envelope(exc) + if isinstance(exc, AdCPError): + # adcp_error.message, NOT exc.message: the sanitized message (identical for + # client-correctable errors, scrubbed for the internal bucket). + message = f"{operation} failed: {adcp_error.message}" + else: + message = f"Internal error during {operation}" + return InternalError(message=message, data=envelope) + + +def _record_a2a_boundary_error(op_key: str, identity: ResolvedIdentity | ToolContext | None, exc: Exception) -> None: + """Record an A2A boundary failure with one canonical identity scope. + + Accepts a ``ToolContext`` as well as a ``ResolvedIdentity``: the push-config handlers + hold a resolved tool context rather than a bare identity, and both expose the + ``tenant_id``/``principal_id`` that ``best_effort_boundary_identity`` reads. The two + signatures must stay in step — ``_boundary_internal_error`` forwards straight to here, + so a narrower type on this side rejects exactly the callers that helper exists to serve. """ - return InternalError( - message=f"{operation} failed: {exc}", - data=build_two_layer_error_envelope(normalize_to_adcp_error(exc)), + tenant_id, principal_id = best_effort_boundary_identity(lambda: identity, transport="a2a") + record_boundary_error( + "a2a", + op_key, + exc, + tenant_id=tenant_id, + principal_id=principal_id, ) +def _a2a_activity_scope(identity: ResolvedIdentity | None) -> tuple[str | None, str | None]: + """Derive one fail-closed identity scope for every A2A activity record.""" + return best_effort_boundary_identity(lambda: identity, transport="a2a") + + +def _boundary_internal_error( + op_key: str, + op_label: str, + identity: ResolvedIdentity | ToolContext | None, + exc: Exception, +) -> InternalError: + """THE single untyped-crash boundary arm shared by every A2A request handler. + + Log server-side (``record_boundary_error``) using ONE canonical identity-scope + sentinel, then build the sanitized JSON-RPC ``InternalError`` + (``_internal_error_for``). + + The message/get/cancel handlers and four push-notification-config handlers + previously open-coded this arm. ``on_message_send``'s copy had already drifted + onto a different missing-identity sentinel + (``"unknown"``/``"unknown"``) from ``on_get_task``/``on_cancel_task``'s + (``None``/``"anonymous"``), so the SAME unresolved-identity event logged under two + different sentinels — un-greppable, and the tenant column swung by handler. This + is the single edit that keeps the sentinel from drifting again on the next handler. + + Returns (never raises) so each caller keeps its own ``raise ... from exc`` chaining. + """ + _record_a2a_boundary_error(op_key, identity, exc) + return _internal_error_for(op_label, exc) + + class AdCPRequestHandler(RequestHandler): """Request handler for AdCP A2A operations supporting JSON-RPC 2.0.""" def __init__(self): """Initialize the AdCP A2A request handler.""" self.tasks: dict[str, Task] = {} # In-memory task storage + # Owner (tenant_id, principal_id) of each in-memory task. tasks/get and + # tasks/cancel authorize the CALLER against this before serving or mutating + # an in-memory entry — the map key (task id) is bearer-ish and must not by + # itself grant a same-tenant sibling principal access. See + # _authorized_in_memory_task / _remember_task. + self._task_owner: dict[str, tuple[str, str]] = {} self._task_push_configs: dict[str, TaskPushNotificationConfig] = {} logger.info("AdCP Request Handler initialized for direct function calls") + def _remember_task(self, task_id: str, task: Task, identity: ResolvedIdentity | None) -> None: + """Store an in-memory task together with its owner (tenant, principal). + + Only records an owner when identity carries BOTH tenant and principal. An + ownerless task is never served through the memory path (fail closed), which + is correct for synchronous discovery responses that are returned inline and + never polled. + """ + self.tasks[task_id] = task + if identity is not None and identity.tenant_id and identity.principal_id: + self._task_owner[task_id] = (identity.tenant_id, identity.principal_id) + else: + self._task_owner.pop(task_id, None) + + def _forget_task(self, task_id: str) -> None: + """Drop an in-memory task and all its side state (owner + push config).""" + self.tasks.pop(task_id, None) + self._task_owner.pop(task_id, None) + self._task_push_configs.pop(task_id, None) + + def _authorized_in_memory_task(self, task_id: str, identity: ResolvedIdentity | None) -> Task | None: + """Return the in-memory task ONLY when ``identity`` is its recorded owner. + + Fails closed: an unresolved identity, an ownerless task, or an owner + mismatch (a same-tenant sibling principal, or a cross-tenant caller) all + yield None so the caller can neither read nor mutate another principal's + in-memory task. + """ + task = self.tasks.get(task_id) + if task is None or identity is None: + return None + owner = self._task_owner.get(task_id) + if owner is None: + return None + if (identity.tenant_id, identity.principal_id) != owner: + return None + return task + @staticmethod def _build_error_envelope(exc: Exception) -> dict[str, Any]: """Build a spec-compliant two-layer envelope for any exception. - Single source of truth for "wrap-arbitrary-exception → wire envelope" - used by both the per-skill dispatcher (``_build_failed_skill_result``) - and the top-level ``on_message_send`` error handler. Delegates to - ``normalize_to_adcp_error`` for the type→AdCPError mapping - (``ValueError → AdCPValidationError``, ``PermissionError → - AdCPAuthorizationError``, arbitrary ``Exception → - AdCPError(INTERNAL_ERROR)``) so the wire output stays in - ``WIRE_STANDARD_CODES`` (SDK ``STANDARD_ERROR_CODES`` plus the - pinned-spec supplement) and the envelope shape never degrades to a - flat ``{"error": "..."}`` dict the storyboard runner would synthesize - as ``MCP_ERROR``. + The failed-Task-artifact entry into the shared ``_sanitized_envelope`` + composition (consumed by ``_failed_task_artifact`` and + ``_build_failed_skill_result``); the JSON-RPC entry is + ``_internal_error_for``. Same policy on both: a TYPED ``AdCPError`` keeps + its controlled message + wire code, while any UNTYPED exception becomes a + generic ``AdCPError`` and its raw ``str(exc)`` is NEVER placed on the wire. + (It deliberately does NOT use ``normalize_to_adcp_error``, which maps + ``Exception → AdCPError(str(exc))`` and would leak credentials/SQL/hostnames + through the per-skill failed-Task artifact.) The wire output stays in + ``WIRE_STANDARD_CODES`` (SDK ``STANDARD_ERROR_CODES`` plus the pinned-spec + supplement) and the envelope shape stays a two-layer ``errors[]`` structure, + never a flat ``{"error": "..."}`` dict the storyboard runner would treat as + ``MCP_ERROR``. """ - return build_two_layer_error_envelope(normalize_to_adcp_error(exc)) + _sanitized, envelope = _sanitized_envelope(exc) + return envelope + + @staticmethod + def _failed_task_artifact(exc: Exception) -> "Artifact": + """The ``processing_error`` artifact for a failed Task. + + Per the A2A binding for errors, a failed artifact carries BOTH a + human-readable TextPart and the authoritative structured DataPart (the + two-layer AdCP envelope) — not a DataPart alone. The strict reader REQUIRES + exactly that shape (one DataPart AND one TextPart), and every failed-artifact + emitter — this one, the per-skill ``error_result``, and the durable rebuild in + ``_durable_result_artifact`` — must satisfy it.""" + envelope = AdCPRequestHandler._build_error_envelope(exc) + errors = envelope.get("errors") or [] + text = errors[0].get("message") if errors else "Request failed." + return Artifact( + artifact_id="error_1", + name="processing_error", + parts=[Part(text=text), Part(data=_dict_to_value(envelope))], + ) @staticmethod def _build_failed_skill_result(skill_name: str, exc: Exception) -> dict[str, Any]: @@ -264,6 +560,86 @@ def _build_failed_skill_result(skill_name: str, exc: Exception) -> dict[str, Any "success": False, } + @staticmethod + async def _dispatch_under_sanitize_seam( + operation: str, identity: ResolvedIdentity | ToolContext | None, handler_coro: Awaitable[Any] + ) -> Any: + """Await ``handler_coro`` with the boundary's provenance policy applied to failures. + + The seam every buyer-reachable handler call goes through — explicit-skill dispatch + and natural-language routing alike — so a client-correctable failure reaches the + outer boundary already typed, and is framed as an application-layer failed Task + rather than a transport-layer JSON-RPC error. + + Catches exactly ``(AdCPError, ValueError, PermissionError)``. NOT ``Exception``: + AdCP 3.1.1 ``transport-errors.mdx`` §"Layer Separation" classifies an internal crash + as a TRANSPORT-layer event, so a genuine crash must keep falling through to the + JSON-RPC ``InternalError`` arm. Widening this would also re-expose the raw-text leak + that arm exists to prevent. + + ``safe_adcp_error`` decides SEMANTICS and MESSAGE TRUST separately: ``ValueError`` → + VALIDATION_ERROR, ``PermissionError`` → AUTH_REQUIRED, native ``AdCPError`` + unchanged, while a raw built-in's untrusted ``str(e)`` is scrubbed. Re-raising the + *normalized* error instead would hand the outer sanitizer a trusted + ``AdCPValidationError`` and let a secret survive. ``record_boundary_error`` receives + the ORIGINAL exception, so raw diagnostics stay in the privileged server log while + tenant-visible sinks get the scrubbed copy. + """ + try: + return await handler_coro + except A2AError: + # Already a properly-formatted transport error. + raise + except (AdCPError, ValueError, PermissionError) as e: + _record_a2a_boundary_error(operation, identity, e) + sanitized = safe_adcp_error(e) + if sanitized is not e: + raise sanitized from e + raise + + def _mark_task_failed(self, task: Task) -> None: + """Mark a task FAILED. No webhook — the caller returns this terminal Task + synchronously in the response, and AdCP 3.1.1 a2a-guide.mdx + ("Webhook Trigger Rules") says a push notification is + NOT sent when the initial response is already terminal (the buyer already + has the result). Webhooks fire only for genuinely async transitions + (initial response ``working``/``submitted`` → later terminal); those must + carry the Task's structured artifacts (see ``_send_protocol_webhook``).""" + task.status.CopyFrom(TaskStatus(state=TaskState.TASK_STATE_FAILED)) + + @staticmethod + def _task_artifacts_data(task: Task) -> list[tuple[str, dict[str, Any]]]: + """Every artifact DataPart as an ordered ``(artifact_name, decoded_data)``. + + Single decoder for A2A DataPart → dict (protobuf ``Value`` → JSON), shared + by completed-status detection and the webhook payload builder. Returns a + LIST, not a name-keyed dict, as a general safety property: identically-named + artifacts are all preserved — none silently overwrites another. (The explicit- + skill path emits one artifact per Task under the single-skill gate; the + general shape guards any other producer.)""" + pairs: list[tuple[str, dict[str, Any]]] = [] + for artifact in task.artifacts: + for part in artifact.parts: + if part.HasField("data"): + pairs.append((artifact.name, json.loads(json_format.MessageToJson(part.data)))) + return pairs + + @staticmethod + def _webhook_result_data(task: Task) -> dict[str, Any]: + """Pack all artifact data into one dict for ``create_a2a_webhook_payload``. + + The library renders a single artifact from this dict, so we key by artifact + name but DE-COLLIDE duplicates (``name``, ``name#2``, …) as a general safety + property — preserving every artifact's data on the wire rather than + overwriting, whatever the producing path.""" + result_data: dict[str, Any] = {} + for name, data in AdCPRequestHandler._task_artifacts_data(task): + key, n = name, 2 + while key in result_data: + key, n = f"{name}#{n}", n + 1 + result_data[key] = data + return result_data + def _get_auth_token(self, context: ServerCallContext | None = None) -> str | None: """Extract Bearer token from ServerCallContext. @@ -281,11 +657,12 @@ def _resolve_a2a_identity( require_valid_token: bool = True, context: ServerCallContext | None = None, ) -> ResolvedIdentity: - """Resolve identity at the A2A transport boundary — called ONCE per request. + """Make the authoritative A2A authentication decision for a request. This is the A2A equivalent of REST's _resolve_auth(). It calls - resolve_identity() once and returns the result. All downstream handlers - receive the pre-resolved identity instead of re-resolving from auth_token. + resolve_identity() once and returns the result. Auth-error observability + stays tenant-unscoped and never validates the token again. All + downstream handlers receive the pre-resolved identity. Args: auth_token: Bearer token from Authorization header (None for unauthenticated) @@ -301,11 +678,12 @@ def _resolve_a2a_identity( from src.core.resolved_identity import resolve_identity from src.core.testing_hooks import AdCPTestContext - auth_ctx = context.state.get(AUTH_CONTEXT_STATE_KEY) if context is not None else None - headers = auth_ctx.headers if auth_ctx else {} + headers = _a2a_auth_headers(context) if require_valid_token and not auth_token: - raise InvalidRequestError(message="Missing authentication token") + raise _enveloped_auth_error( + classify_auth_credentials_error(headers, missing_message="Missing authentication token"), + ) # Extract testing context from A2A request headers (same as MCP does) testing_context = AdCPTestContext.from_headers(headers) @@ -319,15 +697,39 @@ def _resolve_a2a_identity( testing_context=testing_context, ) except AdCPAuthenticationError as e: - raise InvalidRequestError(message=str(e)) from e + # Preserve the cause server-side while classifying the wire code from + # the standard Authorization header, as required by AdCP 3.1.1. + raise _enveloped_auth_error( + classify_auth_credentials_error( + headers, + missing_message="Authentication credentials are required via the Authorization header.", + ), + ) from e if require_valid_token: if not identity.principal_id: - raise InvalidRequestError(message="Authentication token is invalid or expired.") + raise _enveloped_auth_error( + classify_auth_credentials_error( + headers, + missing_message="Authentication credentials are required via the Authorization header.", + invalid_message="Authentication token is invalid or expired.", + ), + ) if not identity.tenant: - raise InvalidRequestError( - message=f"Unable to determine tenant from authentication. Principal: {identity.principal_id}" + # The credentials were VALID — the principal authenticated and only the tenant + # lookup failed. That is a seller-side configuration failure, not a buyer auth + # problem, so it must NOT emit AUTH_REQUIRED (which tells the buyer to fix its + # credentials). CONFIGURATION_ERROR is terminal per the pinned 3.1.1 enum, and + # being an internal wire code its message is scrubbed at the boundary — which is + # also what keeps the principal id off the wire, so it is logged here instead. + logger.error( + "[A2A AUTH] authenticated principal has no resolvable tenant: principal=%s", + identity.principal_id, + ) + raise _recorded_a2a_auth_rejection( + AdCPConfigurationError("Unable to determine tenant for the authenticated principal."), + principal_id=identity.principal_id, ) tenant_id = identity.tenant_id or identity.tenant.get("tenant_id", "unknown") @@ -343,6 +745,18 @@ def _resolve_a2a_identity( return identity + def _authenticated_tool_context(self, context: ServerCallContext | None, tool_name: str) -> ToolContext: + """Auth preamble shared by the four push-notification-config methods. + + ``token → identity → ToolContext`` was byte-identical in all four. No missing-token + pre-check: ``_resolve_a2a_identity`` (``require_valid_token=True`` by default) already + raises the single enveloped auth error for exactly that condition, so each of these + methods inherit the shared ``AUTH_MISSING``/``AUTH_INVALID`` envelope source. + """ + auth_token = self._get_auth_token(context) + identity = self._resolve_a2a_identity(auth_token, context=context) + return self._make_tool_context(identity, tool_name) + def _make_tool_context( self, identity: ResolvedIdentity, tool_name: str, context_id: str | None = None ) -> ToolContext: @@ -376,15 +790,15 @@ def _make_tool_context( def _log_a2a_operation( self, operation: str, - tenant_id: str, - principal_id: str, + tenant_id: str | None, + principal_id: str | None, success: bool = True, details: dict[str, Any] | None = None, error: str | None = None, ): """Log A2A operations to audit system for visibility in activity feed.""" try: - if not tenant_id: + if not tenant_id or not principal_id: return audit_logger = get_audit_logger("A2A", tenant_id) @@ -405,8 +819,6 @@ async def _send_protocol_webhook( self, task: Task, status: str, - result: dict[str, Any] | None = None, - error: str | None = None, ): """Send protocol-level push notification if configured. @@ -415,6 +827,13 @@ async def _send_protocol_webhook( - Intermediate states (working, input-required, submitted): Send TaskStatusUpdateEvent Uses create_a2a_webhook_payload from adcp library to automatically select correct type. + + In-process callers notify only the non-terminal ``submitted`` transition + (immediate terminal responses are returned synchronously and do not notify — + see ``_mark_task_failed``; the later async terminal transition is notified by + the durable workflow path in ``ContextManager``). The payload's result data is + always read off the Task's own artifacts (``_webhook_result_data``), never a + caller-supplied dict — one source for what a subscriber sees. """ try: # Check if task has push notification config stored @@ -453,11 +872,12 @@ async def _send_protocol_webhook( logger.warning("Unknown status '%s', defaulting to 'working'", status) status_enum = GeneratedTaskStatus.working - # Build result data for the webhook payload - # Include error information in result if status is failed - result_data: dict[str, Any] = result or {} - if error and status == "failed": - result_data["error"] = error + # Build result data for the webhook payload. ``create_a2a_webhook_payload`` + # renders its artifact FROM this dict, so we pass the Task's own structured + # artifact data — EVERY artifact, de-colliding duplicate names — never a + # lossy ``{"error": "..."}``, a single stale DataPart, an empty dict, or a + # name-overwritten sibling. + result_data: dict[str, Any] = self._webhook_result_data(task) # Use create_a2a_webhook_payload to get the correct payload type: # - Task for final states (completed, failed, canceled) @@ -506,7 +926,7 @@ async def on_message_send( Returns: Task object or Message response """ - logger.info("Handling message/send request: %s", params) + logger.info("Handling message/send request") # Parse message for both text and structured data parts message = params.message @@ -527,9 +947,7 @@ async def on_message_send( # Support both "input" (A2A spec) and "parameters" (legacy) for skill params params_data = data.get("input") or data.get("parameters", {}) skill_invocations.append({"skill": data["skill"], "parameters": params_data}) - logger.info( - f"Found explicit skill invocation: {data['skill']} with params: {list(params_data.keys())}" - ) + logger.info("Found explicit skill invocation") # Combine text for natural language fallback combined_text = " ".join(text_parts).strip().lower() @@ -553,7 +971,10 @@ async def on_message_send( "invocation_type": "explicit_skill" if skill_invocations else "natural_language", } if skill_invocations: - task_metadata["skills_requested"] = [inv["skill"] for inv in skill_invocations] + registered_skills = set(self._skill_handler_map()) + task_metadata["skills_requested"] = [ + inv["skill"] if inv["skill"] in registered_skills else "unsupported_skill" for inv in skill_invocations + ] task = Task( id=task_id, @@ -563,6 +984,11 @@ async def on_message_send( ) self.tasks[task_id] = task + # Initialized before the try so the outer error handler can always read + # it — a failure during auth-token extraction (before resolution) must + # not turn into a NameError inside the except block. + identity: ResolvedIdentity | None = None + try: # Get authentication token auth_token = self._get_auth_token(context) @@ -577,20 +1003,16 @@ async def on_message_send( if non_discovery_skills: requires_auth = True - # Require authentication for non-public skills. Stay a JSON-RPC - # InvalidRequestError (protocol-level rejection, top-level error), but - # carry the two-layer envelope in ``data`` so the buyer-facing - # AUTH_REQUIRED code + AUTH_REQUIRED_SUGGESTION reach the A2A wire — - # matching REST's no-identity envelope (auth_context.py), which the - # bare A2AError previously dropped. (#1417) + # Require authentication for non-public skills. Stays a JSON-RPC + # InvalidRequestError (protocol-level rejection) while carrying the two-layer + # envelope in ``data`` — via the same _enveloped_auth_error source every other + # A2A auth raise uses, so the code/recovery/suggestion and both layers' message + # cannot drift between message/send and the rest. if requires_auth and not auth_token: - raise InvalidRequestError( - message="Missing authentication token - Bearer token required in Authorization header", - data=build_two_layer_error_envelope( - AdCPAuthRequiredError( - "Authentication required - Bearer token required in Authorization header", - suggestion=AUTH_REQUIRED_SUGGESTION, - ) + raise _enveloped_auth_error( + classify_auth_credentials_error( + _a2a_auth_headers(context), + missing_message="Authentication required - Bearer token required in Authorization header", ), ) @@ -606,10 +1028,12 @@ async def on_message_send( if push_notification_config: self._task_push_configs[task_id] = push_notification_config - # ── Transport boundary: resolve identity ONCE ── - # Like REST's _resolve_auth(), identity is resolved here and passed - # to all downstream handlers. No handler should call resolve_identity(). - identity: ResolvedIdentity | None = None + # ── Transport boundary: make one authoritative auth decision ── + # Like REST's _resolve_auth(), identity is resolved here and passed to + # all downstream handlers. Auth-error recording stays unscoped, and + # no handler validates the credential a second time. + # (``identity`` is declared before the enclosing ``try`` above so the + # outer error handler can always read it — not re-declared here.) if auth_token: identity = self._resolve_a2a_identity(auth_token, require_valid_token=requires_auth, context=context) elif not requires_auth: @@ -618,12 +1042,31 @@ async def on_message_send( # Route: Handle explicit skill invocations first, then natural language fallback if skill_invocations: - # Process explicit skill invocations + # Reject a multi-skill batch BEFORE executing ANY skill. Aggregating + # divergent per-skill outcomes into one Task is incoherent when a skill + # has real side effects: e.g. create_media_buy persists a pending + # (submitted) workflow while a sibling fails, which would terminalize + # the Task as failed even though the accepted work keeps running. Until + # per-skill child Tasks exist (tracked as a follow-up), one skill per + # message is the contract. Raised as a typed application error → + # failed Task (UNSUPPORTED_FEATURE); no skill runs, so no side effects. + if len(skill_invocations) > 1: + multi_skill_error = AdCPCapabilityNotSupportedError( + message="Batching multiple skills in one message is not supported; send one skill per message." + ) + # Recorded HERE, at the raise site. This is the one raise reaching the + # outer ``except AdCPError`` that does not pass through + # ``_dispatch_under_sanitize_seam``, and that arm no longer records — + # so an unrecorded raise would vanish from the observability sinks. + _record_a2a_boundary_error("message_processing", identity, multi_skill_error) + raise multi_skill_error + + # Process the single explicit skill invocation. results = [] for invocation in skill_invocations: skill_name = invocation["skill"] parameters = invocation["parameters"] - logger.info("Processing explicit skill: %s with parameters: %s", skill_name, parameters) + logger.info("Processing explicit skill invocation") try: result = await self._handle_explicit_skill( @@ -631,6 +1074,7 @@ async def on_message_send( parameters, identity, push_notification_config=push_notification_config, + task_id=task_id, ) results.append({"skill": skill_name, "result": result, "success": True}) except A2AError: @@ -649,7 +1093,8 @@ async def on_message_send( # except branch (with audit log + activity feed); duplicating # the logger call here would produce two messages for the # same failure. - results.append(self._build_failed_skill_result(skill_name, e)) + safe_skill_name = skill_name if skill_name in self._skill_handler_map() else "unsupported_skill" + results.append(self._build_failed_skill_result(safe_skill_name, e)) except Exception as e: # Untyped fallthrough — same envelope shape as the AdCPError # branch so storyboard runners can `JSON.parse` the DataPart @@ -661,31 +1106,12 @@ async def on_message_send( # (AdCPError/ValueError/PermissionError) failures were already # recorded inside _handle_explicit_skill, so this only fires for # genuinely-unexpected exceptions that escaped it. - record_boundary_error( - "a2a", - skill_name, - e, - tenant_id=getattr(identity, "tenant_id", None), - principal_id=getattr(identity, "principal_id", None) or "anonymous", - ) + _record_a2a_boundary_error(skill_name, identity, e) results.append(self._build_failed_skill_result(skill_name, e)) - # Check for submitted status (manual approval required) - return early without artifacts - # Per AdCP spec, async operations should return Task with status=submitted and no artifacts - for res in results: - if res["success"] and isinstance(res["result"], dict): - result_status = res["result"].get("status") - if result_status == "submitted": - task.status.CopyFrom(TaskStatus(state=TaskState.TASK_STATE_SUBMITTED)) - del task.artifacts[:] # No artifacts for pending tasks - logger.info( - f"Task {task_id} requires manual approval, returning status=submitted with no artifacts" - ) - # Send protocol-level webhook notification - await self._send_protocol_webhook(task, status="submitted") - self.tasks[task_id] = task - return task - + # Create artifacts for ALL skill results FIRST, before any status + # decision. A mixed submitted+failed batch must never lose a failure + # envelope to an early return — status is decided below by precedence. # Create artifacts for all skill results with human-readable text for i, res in enumerate(results): if res["success"]: @@ -705,19 +1131,25 @@ async def on_message_send( ) # Generate human-readable text from response __str__() - # Per A2A spec, use TextPart + DataPart pattern (not description field) + # Per A2A spec, use TextPart + DataPart pattern (not description field). + # A FAILED artifact carries the error message as its TextPart (A2A + # error binding: TextPart + DataPart), never a DataPart alone. # - # The text is READ from the payload, never re-derived from it: - # _stamp_a2a_protocol_fields already stamped str(response) onto - # artifact_data["message"] at serialization time. An outbound - # payload is finished — feeding it back through Model(**data) - # to recover the same string handed pydantic before-validators - # a reference to the dict about to go on the wire, and one of - # them mutated it in place (the list_creatives format_id + # On both arms the text is READ from the payload, never re-derived + # from it: _stamp_a2a_protocol_fields already stamped str(response) + # onto artifact_data["message"] at serialization time, and a failure + # envelope already carries its buyer-facing text in errors[0]. + # An outbound payload is finished — feeding it back through + # Model(**data) to recover the same string handed pydantic + # before-validators a reference to the dict about to go on the wire, + # and one of them mutated it in place (the list_creatives format_id # bare-string defect). Nothing rebuilds an outbound payload. text_message = None if res["success"] and isinstance(artifact_data, dict): text_message = artifact_data.get("message") + elif not res["success"] and isinstance(artifact_data, dict): + errors = artifact_data.get("errors") or [] + text_message = errors[0].get("message") if errors else "Skill invocation failed." # Build parts list per A2A spec: optional text Part + required data Part parts = [] @@ -733,70 +1165,76 @@ async def on_message_send( ) ) - # Check if any skills failed and determine task status - failed_skills = [res["skill"] for res in results if not res["success"]] - successful_skills = [res["skill"] for res in results if res["success"]] - - if failed_skills and not successful_skills: - # All skills failed - mark task as failed - task.status.CopyFrom(TaskStatus(state=TaskState.TASK_STATE_FAILED)) - - # Send protocol-level webhook notification for failure - error_messages = [ - res["error_envelope"]["errors"][0]["message"] for res in results if not res["success"] - ] - await self._send_protocol_webhook(task, status="failed", error="; ".join(error_messages)) + # The single-skill gate above guarantees exactly one result; route its + # outcome: failed → submitted → completed. + outcome = results[0] + + if not outcome["success"]: + # Terminal-failed: the failed skill's two-layer envelope rides in the + # Task body. Immediate terminal response returned synchronously → no + # webhook (a2a-guide.mdx terminal-state rule). Remember the task + # under its owner (like the submitted/successful branches) so the + # buyer can poll tasks/get on a failed explicit skill — a failed Task + # is a Task-layer outcome, and leaving it unremembered both diverges + # from the NL-failed path and strands an ownerless entry in the + # in-memory maps. + self._mark_task_failed(task) + self._remember_task(task_id, task, identity) + return task + if isinstance(outcome["result"], dict) and outcome["result"].get("status") == "submitted": + # Pending approval → non-terminal SUBMITTED. An async op keeps the + # "no artifacts until approved" convention. Non-terminal initial + # response → notify. + task.status.CopyFrom(TaskStatus(state=TaskState.TASK_STATE_SUBMITTED)) + del task.artifacts[:] + await self._send_protocol_webhook(task, status="submitted") + self._remember_task(task_id, task, identity) return task - elif successful_skills: - # Log successful skill invocations with rich context - try: - tenant_id = (identity.tenant_id or "unknown") if identity else "unknown" - principal_id = (identity.principal_id or "unknown") if identity else "unknown" - - # Extract meaningful details from results - log_details = {"skills": successful_skills, "count": len(successful_skills)} - - # Add context from the first successful skill - first_result = next((r for r in results if r["success"]), None) - if first_result and "result" in first_result: - result_data = first_result["result"] - - # Extract budget and package info for create_media_buy - if "create_media_buy" in first_result["skill"]: - if isinstance(result_data, dict): - if "total_budget" in result_data: - log_details["total_budget"] = result_data["total_budget"] - if "packages" in result_data: - log_details["package_count"] = len(result_data["packages"]) - if "media_buy_id" in result_data: - log_details["media_buy_id"] = result_data["media_buy_id"] - - # Extract product count for get_products - elif "get_products" in first_result["skill"]: - if isinstance(result_data, dict) and "products" in result_data: - log_details["product_count"] = len(result_data["products"]) - - # Extract creative count for sync_creatives - elif "sync_creatives" in first_result["skill"]: - if isinstance(result_data, dict) and "creatives" in result_data: - log_details["creative_count"] = len(result_data["creatives"]) - - self._log_a2a_operation( - "explicit_skill_invocation", - tenant_id, - principal_id, - True, - log_details, - ) - except Exception as e: - logger.warning("Could not log skill invocations: %s", e) + + # Completed synchronously — log the successful invocation with rich context. + try: + tenant_id, principal_id = _a2a_activity_scope(identity) + + log_details = {"skills": [outcome["skill"]], "count": 1} + result_data = outcome.get("result") + + # Extract budget and package info for create_media_buy + if "create_media_buy" in outcome["skill"]: + if isinstance(result_data, dict): + if "total_budget" in result_data: + log_details["total_budget"] = result_data["total_budget"] + if "packages" in result_data: + log_details["package_count"] = len(result_data["packages"]) + if "media_buy_id" in result_data: + log_details["media_buy_id"] = result_data["media_buy_id"] + + # Extract product count for get_products + elif "get_products" in outcome["skill"]: + if isinstance(result_data, dict) and "products" in result_data: + log_details["product_count"] = len(result_data["products"]) + + # Extract creative count for sync_creatives + elif "sync_creatives" in outcome["skill"]: + if isinstance(result_data, dict) and "creatives" in result_data: + log_details["creative_count"] = len(result_data["creatives"]) + + self._log_a2a_operation( + "explicit_skill_invocation", + tenant_id, + principal_id, + True, + log_details, + ) + except Exception as e: + logger.warning("Could not log skill invocations: %s", e) # Natural language fallback (existing keyword-based routing) elif any(word in combined_text for word in ["product", "inventory", "available", "catalog"]): - result = await self._get_products(combined_text, identity) - tenant_id = (identity.tenant_id or "unknown") if identity else "unknown" - principal_id = (identity.principal_id or "unknown") if identity else "unknown" + result = await self._dispatch_under_sanitize_seam( + "get_products", identity, self._get_products(combined_text, identity) + ) + tenant_id, principal_id = _a2a_activity_scope(identity) self._log_a2a_operation( "get_products", @@ -818,12 +1256,10 @@ async def on_message_send( ) elif any(word in combined_text for word in ["price", "pricing", "cost", "cpm", "budget"]): # Redirect pricing queries to get_products which has real price_guidance - result = await self._handle_get_products_skill( - {"brief": combined_text}, - identity, + result = await self._dispatch_under_sanitize_seam( + "get_products", identity, self._handle_get_products_skill({"brief": combined_text}, identity) ) - tenant_id = (identity.tenant_id or "unknown") if identity else "unknown" - principal_id = (identity.principal_id or "unknown") if identity else "unknown" + tenant_id, principal_id = _a2a_activity_scope(identity) self._log_a2a_operation( "get_products", @@ -846,9 +1282,10 @@ async def on_message_send( ) elif any(word in combined_text for word in ["target", "audience"]): # Redirect targeting queries to get_adcp_capabilities which has real targeting info - result = await self._handle_get_adcp_capabilities_skill({}, identity) - tenant_id = (identity.tenant_id or "unknown") if identity else "unknown" - principal_id = (identity.principal_id or "unknown") if identity else "unknown" + result = await self._dispatch_under_sanitize_seam( + "get_adcp_capabilities", identity, self._handle_get_adcp_capabilities_skill({}, identity) + ) + tenant_id, principal_id = _a2a_activity_scope(identity) self._log_a2a_operation( "get_adcp_capabilities", @@ -872,10 +1309,13 @@ async def on_message_send( # ``_create_media_buy`` is an NL stub that always raises # ``AdCPCapabilityNotSupportedError`` — the explicit-skill # path is the spec contract for media buy creation. The - # outer error handler at on_message_send catches the raise - # and attaches a spec-compliant two-layer envelope to the - # failed Task artifact. - await self._create_media_buy(combined_text, identity) + # outer error handler at on_message_send catches the raise, + # attaches a spec-compliant two-layer envelope to the failed + # Task artifact, and returns that failed Task (never a + # JSON-RPC error). + await self._dispatch_under_sanitize_seam( + "create_media_buy", identity, self._create_media_buy(combined_text, identity) + ) else: # General help response capabilities = { @@ -892,8 +1332,7 @@ async def on_message_send( "How do I create a media buy?", ], } - tenant_id = (identity.tenant_id or "unknown") if identity else "unknown" - principal_id = (identity.principal_id or "unknown") if identity else "unknown" + tenant_id, principal_id = _a2a_activity_scope(identity) self._log_a2a_operation( "get_capabilities", @@ -916,76 +1355,83 @@ async def on_message_send( task_state = TaskState.TASK_STATE_COMPLETED task_status_str = "completed" - result_data = {} - if task.artifacts: - # Extract result from artifacts — part.data is a protobuf Value - for artifact in task.artifacts: - if artifact.parts: - for part in artifact.parts: - if part.HasField("data"): - data_dict = json.loads(json_format.MessageToJson(part.data)) - result_data[artifact.name] = data_dict - - # Check if this is a sync_creatives response with pending creatives - if artifact.name == "result" and isinstance(data_dict, dict): - creatives = data_dict.get("creatives", []) - if any( - c.get("status") == CreativeStatusEnum.pending_review.value - for c in creatives - if isinstance(c, dict) - ): - task_state = TaskState.TASK_STATE_SUBMITTED - task_status_str = "submitted" - - # Check for explicit status field (e.g., create_media_buy returns this) - result_status = data_dict.get("status") - if result_status == "submitted": - task_state = TaskState.TASK_STATE_SUBMITTED - task_status_str = "submitted" + # Single DataPart decode via the shared helper (consolidated decoder). + for artifact_name, data_dict in self._task_artifacts_data(task): + # sync_creatives returns a "result" artifact whose creatives may be + # pending review → the task is non-terminal (submitted), not completed. + if artifact_name == "result" and isinstance(data_dict, dict): + creatives = data_dict.get("creatives", []) + if any( + c.get("status") == CreativeStatusEnum.pending_review.value + for c in creatives + if isinstance(c, dict) + ): + task_state = TaskState.TASK_STATE_SUBMITTED + task_status_str = "submitted" + + # Explicit status field (e.g. create_media_buy returns this). + if data_dict.get("status") == "submitted": + task_state = TaskState.TASK_STATE_SUBMITTED + task_status_str = "submitted" # Mark task with appropriate status task.status.CopyFrom(TaskStatus(state=task_state)) - # Send protocol-level webhook notification if configured - await self._send_protocol_webhook(task, status=task_status_str) + # Notify ONLY for a non-terminal (submitted) initial response. An + # immediately-completed task is returned synchronously in this response, + # and AdCP 3.1.1 a2a-guide.mdx ("Webhook Trigger Rules") says no webhook is + # sent when the initial response is already terminal — the buyer already + # has the result. Only the + # sync_creatives-pending → submitted transition reaches here as + # non-terminal (create_media_buy submitted returns earlier). + if task_status_str == "submitted": + await self._send_protocol_webhook(task, status="submitted") except A2AError: - # Re-raise A2AError as-is (will be caught by JSON-RPC handler) + # Transport-layer failure (missing auth, invalid request, …) → JSON-RPC + # error, NOT a Task-layer outcome. The provisional WORKING task + push + # config stored before dispatch (and before identity resolution) must not + # survive as ownerless, unservable orphans that grow the maps on repeated + # invalid requests — drop them, mirroring the untyped-crash path below. + self._forget_task(task_id) raise - except Exception as e: - # Use identity resolved at transport boundary (if available) - err_tenant_id = (identity.tenant_id or "unknown") if identity else "unknown" - err_principal_id = (identity.principal_id or "unknown") if identity else "unknown" - - record_boundary_error( - "a2a", - "message_processing", - e, - tenant_id=err_tenant_id, - principal_id=err_principal_id, - ) - - # Send protocol-level webhook notification for failure if configured - task.status.CopyFrom(TaskStatus(state=TaskState.TASK_STATE_FAILED)) - # Attach error to task artifacts as a spec-compliant two-layer - # envelope (same shape as failed-skill DataParts) so storyboard - # runners can ``JSON.parse`` the artifact uniformly regardless of - # which failure path produced it. + except AdCPError as e: + # TYPED application/task failure → failed Task carrying the two-layer + # envelope (transport-errors.mdx "Layer Separation"). The AdCPError + # message is CONTROLLED (e.g. "Unknown skill 'x'", "brief must not be + # empty"), so it is client-safe to surface. Immediate terminal response + # returned synchronously below → no webhook (a2a-guide.mdx). Falls through + # to the shared store-and-return. + # + # This arm is pure FRAMING — it no longer records. Every raise that can reach + # it now records itself exactly once, with the ORIGINAL exception, at its own + # raise site: explicit-skill dispatch and NL routing via + # ``_dispatch_under_sanitize_seam``, the multi-skill rejection inline above. + # Recording again here would double-count, and would relabel the specific + # operation the seam already logged as the generic ``message_processing``. del task.artifacts[:] - task.artifacts.append( - Artifact( - artifact_id="error_1", - name="processing_error", - parts=[Part(data=_dict_to_value(self._build_error_envelope(e)))], - ) - ) - - await self._send_protocol_webhook(task, status="failed") - - # Raise A2A error instead of creating failed task - raise _internal_error_for("message processing", e) - - self.tasks[task_id] = task + task.artifacts.append(self._failed_task_artifact(e)) + self._mark_task_failed(task) + except Exception as e: + # UNTYPED internal crash. The spec table classifies an internal crash as + # a TRANSPORT-layer error, and the security requirements forbid exposing + # raw internals (credentials, SQL, hostnames, paths, upstream responses). + # So we log the raw exception SERVER-SIDE only (record_boundary_error) and + # raise a SANITIZED JSON-RPC InternalError whose client-facing envelope + # carries NO raw exception text. Never build a failed-Task envelope from + # ``str(exc)`` here — that is the leak fixed by this branch. + # NOTE the deliberate split: an untyped crash INSIDE a skill handler is a + # task-layer outcome (the dispatch loop wraps it via + # ``_build_failed_skill_result`` → sanitized failed Task), while a crash in + # THIS boundary — before/after dispatch — is transport-layer (JSON-RPC). + # This path yields a JSON-RPC InternalError (transport-layer), NOT a + # Task-layer outcome — so the provisional WORKING task stored before + # dispatch must not survive as a retrievable orphan. Drop it (and its + # push config) before raising so ``tasks/get`` returns nothing. + self._forget_task(task_id) + raise _boundary_internal_error("message_processing", "message processing", identity, e) from e + + self._remember_task(task_id, task, identity) return task async def on_message_send_stream( @@ -1010,39 +1456,32 @@ async def on_message_send_stream( # result is already Task | Message — yield it directly yield result - def _get_task_or_raise(self, task_id: str) -> Task: - """Return the in-memory task, or raise ``TaskNotFoundError``. + # Terminal persisted workflow-step status → A2A TaskState, for the durable + # tasks/get fallback. Non-terminal steps (in_progress, approved, …) surface as + # WORKING. + _STEP_STATUS_TO_TASK_STATE = { + "completed": TaskState.TASK_STATE_COMPLETED, + "rejected": TaskState.TASK_STATE_REJECTED, + "failed": TaskState.TASK_STATE_FAILED, + "canceled": TaskState.TASK_STATE_CANCELED, + } - A bare ``None`` return makes the SDK synthesize a generic internal error; - the A2A spec defines ``TaskNotFoundError`` for an unknown task id, so - raising it is the correct thing to do here and is what an A2A client - should be able to react to precisely. + # Step statuses that are final outcomes — a buyer's tasks/cancel cannot undo + # work that already completed/failed/was rejected (or was already canceled). + # Single source of truth is the repository's TERMINAL_STEP_STATUSES (the atomic + # cancel guard's vocabulary); the state mapping above must cover exactly that + # set, checked at import time so the two can't silently drift. + _TERMINAL_STEP_STATUSES = TERMINAL_STEP_STATUSES + if frozenset(_STEP_STATUS_TO_TASK_STATE) != _TERMINAL_STEP_STATUSES: + raise RuntimeError("A2A step->TaskState mapping out of sync with WorkflowRepository.TERMINAL_STEP_STATUSES") - What a client sees TODAY is still ``-32603``, not the spec's ``-32001``: - this app builds its A2A routes with ``enable_v0_3_compat=True`` - (``src/app.py:306``), so requests dispatch through - ``a2a.compat.v0_3.jsonrpc_adapter``, whose ``handle_request`` ends in a - bare ``except Exception -> CoreInternalError`` with no ``A2AError -> code`` - mapping — the mapping the SDK's own main dispatcher performs. Returning - ``None`` produces the same ``-32603`` there, so the code cannot be fixed - at this layer (#1670). Raising the right type is still correct and is what - will surface ``-32001`` the moment that gap closes; the xfail'd - live-server test pins the current reality. - - The requested id is put on both the message and structured ``data``. - Only the message reaches a client today: the same compat adapter that - flattens the code to ``-32603`` rebuilds the error as - ``CoreInternalError(message=str(e))``, which drops ``data`` — driving - the real route returns ``data: null``. Populating it is still correct - and becomes readable when #1670 closes, the same as the code. - - Shared by ``on_get_task`` and ``on_cancel_task`` so both surface the - same error. - """ - task = self.tasks.get(task_id) - if task is None: - raise TaskNotFoundError(message=f"Task not found: {task_id}", data={"task_id": task_id}) - return task + _TERMINAL_TASK_STATES = frozenset(_STEP_STATUS_TO_TASK_STATE.values()) + + # Reverse of the mapping above, for rendering an in-memory Task's terminal + # TaskState back into the same lowercase vocabulary the durable leg's step-status + # string already uses — so a cancel refusal reads identically ("current state: + # completed") regardless of which leg (in-memory vs durable) refused it. + _TASK_STATE_TO_STEP_STATUS = {v: k for k, v in _STEP_STATUS_TO_TASK_STATE.items()} async def on_get_task( self, @@ -1051,10 +1490,169 @@ async def on_get_task( ) -> Task: """Handle 'tasks/get' method to retrieve task status. - Raises ``TaskNotFoundError`` for an unknown task id — see - ``_get_task_or_raise`` (and #1670 for why the wire code is still -32603). + Identity is resolved ONCE and gates BOTH stores: the in-memory task is + served only to its recorded owner (``_authorized_in_memory_task``), and the + durable step lookup is tenant+principal-scoped — so a same-tenant sibling + principal who learns a task id can read neither. + + The persisted workflow step is the source of truth for an async task's + outcome: the admin decision that terminalizes it runs in a DIFFERENT + process, so this process's in-memory entry can be stale forever (a + SUBMITTED/WORKING task whose workflow already completed). A poll therefore + returns the owned in-memory task only when IT is already terminal; + otherwise the durable step is consulted and, if it reached a terminal + status, wins (and reconciles the owned in-memory entry). The durable + fallback also serves polls after a restart, when the map is empty. + + Raises ``TaskNotFoundError`` when neither store has the task (unknown id, + or not owned by the caller) — a bare ``None`` return would make the SDK + synthesize a generic internal error instead of the spec's not-found + signal. What a client sees TODAY is still ``-32603``, not the spec's + ``-32001``: this app builds its A2A routes with ``enable_v0_3_compat=True`` + (``src/app.py``), so requests dispatch through + ``a2a.compat.v0_3.jsonrpc_adapter``, whose ``handle_request`` ends in a + bare ``except Exception -> CoreInternalError`` with no ``A2AError -> code`` + mapping — the mapping the SDK's own main dispatcher performs. Raising the + right type is still correct and will surface ``-32001`` once the + compatibility adapter preserves typed A2A error codes. + """ + task_id = params.id + identity: ResolvedIdentity | None = None + try: + identity = self._durable_lookup_identity(context) + owned = self._authorized_in_memory_task(task_id, identity) + if owned is not None and owned.status.state in self._TERMINAL_TASK_STATES: + return owned + durable = self._durable_task_from_step(task_id, identity) + if durable is not None and durable.status.state in self._TERMINAL_TASK_STATES: + if owned is not None: + # Reconcile only our OWN entry — never write a map key we don't own. + self._remember_task(task_id, durable, identity) + return durable + # No terminal durable outcome: the richer owned in-memory task (metadata, + # artifacts) beats the durable WORKING skeleton. + found = owned if owned is not None else durable + if found is None: + raise TaskNotFoundError(message=f"Task not found: {task_id}", data={"task_id": task_id}) + return found + except A2AError: + raise + except Exception as e: + # The durable lookup touches the DB; an untyped failure here must not + # escape to the SDK dispatcher, which would echo str(exc) verbatim on + # the JSON-RPC wire. Mirror every sibling handler's boundary arm. + raise _boundary_internal_error("get_task", "get task", identity, e) from e + + def _durable_lookup_identity(self, context: ServerCallContext | None) -> ResolvedIdentity | None: + """Resolve the caller's identity for a durable (cross-process) task lookup. + + A restart-surviving lookup needs a tenant AND principal scope, so identity + is resolved from the request's own auth (the buyer who created the task + authenticated). Missing or invalid authentication remains a transport-layer + ``InvalidRequestError``; it must not be downgraded to a task-not-found result. + Returns None only when a resolved identity is unexpectedly incomplete — the + durable lookup must then be refused rather than risk serving or mutating + another tenant's (or same-tenant sibling principal's) task. + """ + auth_token = self._get_auth_token(context) + identity = self._resolve_a2a_identity(auth_token, require_valid_token=True, context=context) + if identity is None or not identity.tenant_id or not identity.principal_id: + return None + return identity + + @contextmanager + def _owned_durable_step( + self, task_id: str, identity: ResolvedIdentity | None + ) -> Iterator[tuple["Session", "WorkflowRepository", "WorkflowStep"] | None]: + """Shared preamble for durable (cross-process) task ops carrying an outer ``task_*`` id. + + Identity guard → tenant-scoped session + ``WorkflowRepository`` → the principal-owned step + carrying ``task_id``. Yields ``(session, repo, step)``, or ``None`` when identity is + unresolved/non-owning or no persisted step matches. The caller performs any mutation and + ``commit()``/``rollback()`` inside the ``with`` block (the session stays open for its body). + """ + if identity is None or identity.tenant_id is None or identity.principal_id is None: + yield None + return + + # get_db_session stays function-local: this repo's tests patch it at its SOURCE + # module (20+ call sites across tests/), which only takes effect when the name is + # re-resolved per call rather than bound once at import time. + from src.core.database.database_session import get_db_session + + with get_db_session() as session: + repo = WorkflowRepository(session, identity.tenant_id) + step = repo.get_by_external_task_id(task_id, principal_id=identity.principal_id) + yield (session, repo, step) if step is not None else None + + def _durable_task_from_step(self, task_id: str, identity: ResolvedIdentity | None) -> Task | None: + """Rebuild a terminal Task from the workflow step that stored this transport id. + + ``identity`` is the caller's resolved identity (see ``_durable_lookup_identity``); + the lookup is tenant+principal-scoped, so an unresolved or non-owning identity + yields None. Callers resolve identity once and pass it here. + + A FAILED step is rebuilt with the SAME error framing the synchronous paths emit — + an ``error_result`` artifact carrying a human-readable TextPart alongside the + authoritative envelope DataPart (see ``_failed_task_artifact``). A buyer polling + an async failure must not receive a differently-shaped artifact than the one they + would have received had the same failure surfaced synchronously. + """ + recovery_media_buy_id: str | None = None + with self._owned_durable_step(task_id, identity) as owned: + if owned is not None: + _session, repo, step = owned + if step.status == "approved" and step.tool_name == "create_media_buy": + mappings = repo.get_mappings_for_step(step.step_id) + media_buy_mapping = next((m for m in mappings if m.object_type == "media_buy"), None) + if media_buy_mapping is not None: + recovery_media_buy_id = media_buy_mapping.object_id + + if recovery_media_buy_id is not None and identity is not None and identity.tenant_id is not None: + from src.core.workflow_finalization import reconcile_claimed_media_buy_approval_step + + reconcile_claimed_media_buy_approval_step( + tenant_id=identity.tenant_id, + media_buy_id=recovery_media_buy_id, + ) + + with self._owned_durable_step(task_id, identity) as owned: + if owned is None: + return None + _session, _repo, step = owned + state = self._STEP_STATUS_TO_TASK_STATE.get(step.status, TaskState.TASK_STATE_WORKING) + task = Task(id=task_id, context_id=step.context_id, status=TaskStatus(state=state)) + if step.response_data: + task.artifacts.append( + self._durable_result_artifact( + task_id, step.response_data, failed=state == TaskState.TASK_STATE_FAILED + ) + ) + return task + + @staticmethod + def _durable_result_artifact(task_id: str, response_data: dict[str, Any], *, failed: bool) -> "Artifact": + """The stored-result artifact for a durably-rebuilt Task. + + Success keeps the ``media_buy_result`` DataPart. Failure mirrors the synchronous + error binding: an ``error_result`` artifact whose TextPart is the envelope's + human-readable message and whose DataPart is the two-layer envelope + ``audit_workflow_step_failure`` persisted — one framing for a failed artifact, + whether the buyer saw it synchronously or by polling. """ - return self._get_task_or_raise(params.id) + if not failed: + return Artifact( + artifact_id=f"{task_id}_result", + name="media_buy_result", + parts=[Part(data=_dict_to_value(response_data))], + ) + errors = response_data.get("errors") or [] + text = (errors[0].get("message") if errors else None) or "Request failed." + return Artifact( + artifact_id=f"{task_id}_result", + name="error_result", + parts=[Part(text=text), Part(data=_dict_to_value(response_data))], + ) async def on_cancel_task( self, @@ -1063,16 +1661,108 @@ async def on_cancel_task( ) -> Task: """Handle 'tasks/cancel' method to cancel a task. - Raises ``TaskNotFoundError`` for an unknown task id — cancelling a task - that does not exist is the same not-found condition as get, not a silent - no-op. See ``_get_task_or_raise`` (and #1670 for why the wire code is - still -32603). + Mirrors ``on_get_task``'s durability: the in-memory task is + resolved first, then the persisted workflow step carrying the buyer's outer + ``task_*`` id — so a cancel still lands after a restart or in a different + process than the create. A task/step already in a terminal state cannot be + canceled; the durable check runs even on an in-memory hit so a stale + WORKING task can't cancel a workflow that was approved out-of-band. + + Identity is resolved ONCE and gates both stores: only the recorded owner + can observe or mutate the in-memory task, and the durable cancel is + tenant+principal-scoped — a same-tenant sibling principal can neither + terminalize the in-memory task nor cancel the workflow. + + Grounding: ``tasks/cancel`` semantics are A2A-protocol-native (A2A spec + Task Management: ``TaskNotCancelableError`` for tasks already in a + terminal state; the SDK ``default_request_handler`` is the reference + cross-check). AdCP 3.1.1 prose defines no cancel contract of its own — + a2a-guide.mdx "Webhook Trigger Rules" lists ``canceled`` among the final + states ("Cancellation confirmed"). Storyboard: ungraded. + + Raises ``TaskNotFoundError`` when neither store has the task (unknown id, + or not owned by the caller) — cancelling a task that does not exist is the + same not-found condition as get, not a silent no-op. The compatibility adapter + still emits ``-32603`` rather than the spec's ``-32001`` for typed A2A errors. + + A durable counterpart is REQUIRED to report success. If the durable cancel + resolves nothing, an in-memory hit raises ``TaskNotCancelableError`` rather than + stamping CANCELED: the in-memory task is this process's view, so cancelling only + that would tell the buyer the work stopped while the workflow step kept running + and later fired its own completed webhook. Only ``_TASK_ID_BEARING_SKILLS`` + persist their outer id, so a missing durable counterpart means the task is not + cancellable through this id — which is the honest answer for a ``sync_creatives`` + task, whose N per-creative steps no single id can name. """ - task = self._get_task_or_raise(params.id) - # CopyFrom mutates the stored Task in place — self.tasks already holds - # this exact reference, so re-storing it would rebind the same object. - task.status.CopyFrom(TaskStatus(state=TaskState.TASK_STATE_CANCELED)) - return task + task_id = params.id + identity: ResolvedIdentity | None = None + try: + identity = self._durable_lookup_identity(context) + owned = self._authorized_in_memory_task(task_id, identity) + if owned is not None and owned.status.state in self._TERMINAL_TASK_STATES: + current_status = self._TASK_STATE_TO_STEP_STATUS.get(owned.status.state, "unknown") + raise TaskNotCancelableError(message=f"Task cannot be canceled - current state: {current_status}") + durable = self._durable_cancel_step(task_id, identity) + if durable is None: + # No durable counterpart: REFUSE rather than report a cancellation that + # did not happen. An in-memory hit used to be enough to stamp CANCELED + # here, which made the answer a lie whenever the work outlived the + # request — the buyer was told the task was canceled while the workflow + # step kept running and later fired its own completed webhook. A task we + # cannot resolve durably is one we cannot cancel, and saying so is the + # only honest answer available at this boundary. + if owned is not None: + raise TaskNotCancelableError( + message=("Task cannot be canceled - no durable workflow step is associated with this task id") + ) + raise TaskNotFoundError(message=f"Task not found: {task_id}", data={"task_id": task_id}) + if owned is not None: + owned.status.CopyFrom(TaskStatus(state=TaskState.TASK_STATE_CANCELED)) + self._remember_task(task_id, owned, identity) + return owned + return durable + except A2AError: + raise + except Exception as e: + # The durable cancel touches the DB; an untyped failure must not escape + # to the SDK dispatcher (which echoes str(exc) on the JSON-RPC wire). + raise _boundary_internal_error("cancel_task", "cancel task", identity, e) from e + + def _durable_cancel_step(self, task_id: str, identity: ResolvedIdentity | None) -> Task | None: + """Durably cancel the workflow step carrying this outer task id. + + Tenant- AND principal-scoped via ``identity`` (see ``_durable_lookup_identity``). + Returns None when identity is unresolved/non-owning or no persisted step + matches. Raises ``TaskNotCancelableError`` when the step is not in a + CANCELLABLE status — i.e. already terminal, ``approved``, OR ``in_progress`` + (irreversible ad-server work has begun or is underway): an approved or + executing media buy cannot be canceled. + + The transition itself is a single conditional UPDATE + (``cancel_if_cancellable`` — ``WHERE status IN cancellable``) so a concurrent + approval/execution that commits ``approved``/``in_progress``/``completed`` after + our read cannot be overwritten — the zero-row outcome is reported as + ``TaskNotCancelableError`` with the fresh status, and the decision stands. + """ + with self._owned_durable_step(task_id, identity) as owned: + if owned is None: + return None + session, repo, step = owned + # cancel_if_cancellable refuses to cancel an ``approved`` OR ``in_progress`` step: + # once approved (or once execution has started its adapter side-effects), irreversible + # ad-server work is underway, so a cancel must not strand a real order behind a + # canceled task. + if not repo.cancel_if_cancellable(step.step_id, completed_at=datetime.now(UTC)): + session.rollback() + fresh = repo.get_by_step_id(step.step_id) + current = fresh.status if fresh is not None else "unknown" + raise TaskNotCancelableError(message=f"Task cannot be canceled - current state: {current}") + session.commit() + return Task( + id=task_id, + context_id=step.context_id, + status=TaskStatus(state=TaskState.TASK_STATE_CANCELED), + ) async def on_list_tasks( self, @@ -1102,11 +1792,7 @@ async def on_get_task_push_notification_config( """ tool_context = None try: - auth_token = self._get_auth_token(context) - if not auth_token: - raise InvalidRequestError(message="Missing authentication token") - identity = self._resolve_a2a_identity(auth_token, context=context) - tool_context = self._make_tool_context(identity, "get_push_notification_config") + tool_context = self._authenticated_tool_context(context, "get_push_notification_config") config_id = params.get("id") if isinstance(params, dict) else getattr(params, "id", None) if not config_id: @@ -1144,14 +1830,12 @@ async def on_get_task_push_notification_config( except A2AError: raise except Exception as e: - record_boundary_error( - "a2a", + raise _boundary_internal_error( "get_push_notification_config", + "get push notification config", + tool_context, e, - tenant_id=tool_context.tenant_id if tool_context else None, - principal_id=tool_context.principal_id if tool_context else None, - ) - raise _internal_error_for("get push notification config", e) from e + ) from e async def on_create_task_push_notification_config( self, @@ -1165,11 +1849,7 @@ async def on_create_task_push_notification_config( """ tool_context = None try: - auth_token = self._get_auth_token(context) - if not auth_token: - raise InvalidRequestError(message="Missing authentication token") - identity = self._resolve_a2a_identity(auth_token, context=context) - tool_context = self._make_tool_context(identity, "set_push_notification_config") + tool_context = self._authenticated_tool_context(context, "set_push_notification_config") # In a2a-sdk 1.0, TaskPushNotificationConfig is a flat protobuf message # with fields: tenant, id, task_id, url, token, authentication @@ -1180,7 +1860,6 @@ async def on_create_task_push_notification_config( if not url: raise InvalidParamsError(message="Missing required parameter: url") - _reject_unsafe_a2a_webhook_url(url) auth_type = None @@ -1226,14 +1905,12 @@ async def on_create_task_push_notification_config( except A2AError: raise except Exception as e: - record_boundary_error( - "a2a", + raise _boundary_internal_error( "create_push_notification_config", + "set push notification config", + tool_context, e, - tenant_id=tool_context.tenant_id if tool_context else None, - principal_id=tool_context.principal_id if tool_context else None, - ) - raise _internal_error_for("set push notification config", e) from e + ) from e async def on_list_task_push_notification_configs( self, @@ -1246,11 +1923,7 @@ async def on_list_task_push_notification_configs( """ tool_context = None try: - auth_token = self._get_auth_token(context) - if not auth_token: - raise InvalidRequestError(message="Missing authentication token") - identity = self._resolve_a2a_identity(auth_token, context=context) - tool_context = self._make_tool_context(identity, "list_push_notification_configs") + tool_context = self._authenticated_tool_context(context, "list_push_notification_configs") with PushNotificationConfigUoW(tool_context.tenant_id) as uow: assert uow.push_notification_configs is not None @@ -1284,14 +1957,12 @@ async def on_list_task_push_notification_configs( except A2AError: raise except Exception as e: - record_boundary_error( - "a2a", + raise _boundary_internal_error( "list_push_notification_configs", + "list push notification configs", + tool_context, e, - tenant_id=tool_context.tenant_id if tool_context else None, - principal_id=tool_context.principal_id if tool_context else None, - ) - raise _internal_error_for("list push notification configs", e) from e + ) from e async def on_delete_task_push_notification_config( self, @@ -1304,11 +1975,7 @@ async def on_delete_task_push_notification_config( """ tool_context = None try: - auth_token = self._get_auth_token(context) - if not auth_token: - raise InvalidRequestError(message="Missing authentication token") - identity = self._resolve_a2a_identity(auth_token, context=context) - tool_context = self._make_tool_context(identity, "delete_push_notification_config") + tool_context = self._authenticated_tool_context(context, "delete_push_notification_config") config_id = params.id if not config_id: @@ -1329,14 +1996,12 @@ async def on_delete_task_push_notification_config( except A2AError: raise except Exception as e: - record_boundary_error( - "a2a", + raise _boundary_internal_error( "delete_push_notification_config", + "delete push notification config", + tool_context, e, - tenant_id=tool_context.tenant_id if tool_context else None, - principal_id=tool_context.principal_id if tool_context else None, - ) - raise _internal_error_for("delete push notification config", e) from e + ) from e async def on_get_extended_agent_card( self, @@ -1411,12 +2076,50 @@ def _serialize_for_a2a(response: AdCPBaseModel | dict) -> dict[str, Any]: return AdCPRequestHandler._stamp_a2a_protocol_fields(response) + def _skill_handler_map(self) -> dict[str, Callable[..., Awaitable[Any]]]: + """Explicit-skill dispatch registry: skill name → bound handler. + + The single source of truth for which skills A2A dispatches. Exposed as a + method so the transport-contract suite can assert a registry↔test bijection + (every registered skill is exercised on the wire). Handler signatures are + heterogeneous (discovery skills accept ``identity: ResolvedIdentity | None``; + the rest require non-None), so dispatch is typed dynamically — the + non-discovery guard in ``_handle_explicit_skill`` enforces identity first. + """ + return { + # Core AdCP Discovery Skills + "get_adcp_capabilities": self._handle_get_adcp_capabilities_skill, + # Core AdCP Media Buy Skills + "get_products": self._handle_get_products_skill, + "create_media_buy": self._handle_create_media_buy_skill, + # Discovery Skills + "list_creative_formats": self._handle_list_creative_formats_skill, + "list_accounts": self._handle_list_accounts_skill, + "sync_accounts": self._handle_sync_accounts_skill, + "list_authorized_properties": self._handle_list_authorized_properties_skill, + # Media Buy Management Skills + "update_media_buy": self._handle_update_media_buy_skill, + "get_media_buys": self._handle_get_media_buys_skill, + "get_media_buy_delivery": self._handle_get_media_buy_delivery_skill, + "update_performance_index": self._handle_update_performance_index_skill, + # AdCP Spec Creative Management (centralized library approach) + "sync_creatives": self._handle_sync_creatives_skill, + "list_creatives": self._handle_list_creatives_skill, + "create_creative": self._handle_create_creative_skill, + "assign_creative": self._handle_assign_creative_skill, + # Creative Management & Approval + "approve_creative": self._handle_approve_creative_skill, + "get_media_buy_status": self._handle_get_media_buy_status_skill, + "optimize_media_buy": self._handle_optimize_media_buy_skill, + } + async def _handle_explicit_skill( self, skill_name: str, parameters: dict, identity: ResolvedIdentity | None, push_notification_config: TaskPushNotificationConfig | None = None, + task_id: str | None = None, ) -> dict: """Handle explicit AdCP skill invocations. @@ -1443,7 +2146,7 @@ async def _handle_explicit_skill( # Inject push_notification_config into parameters for skills that need it # Serialize protobuf to dict at the transport boundary — _impl accepts dict - if push_notification_config and skill_name in ("create_media_buy", "sync_creatives"): + if push_notification_config and skill_name in _ASYNC_TASK_SKILLS: pnc_dict = json_format.MessageToDict(push_notification_config) # Translate A2A protobuf authentication.scheme (singular) → AdCP schemes (plural list). # A2A's protobuf AuthenticationInfo uses a single `scheme` field; AdCP's @@ -1459,86 +2162,51 @@ async def _handle_explicit_skill( compat_result = normalize_request_params(skill_name, parameters) parameters = compat_result.params - logger.info("Handling explicit skill: %s with parameters: %s", skill_name, list(parameters.keys())) - # Validate identity for non-discovery skills - if skill_name not in DISCOVERY_SKILLS and (identity is None or not identity.principal_id): - raise InvalidRequestError(message="Authentication required for skill invocation") - - # Map skill names to handlers. Handler signatures are heterogeneous - # (discovery skills accept ``identity: ResolvedIdentity | None``; the rest - # require non-None), so the dispatch is typed dynamically — the non-discovery - # guard above enforces a non-None identity before the call. - skill_handlers: dict[str, Callable[..., Awaitable[Any]]] = { - # Core AdCP Discovery Skills - "get_adcp_capabilities": self._handle_get_adcp_capabilities_skill, - # Core AdCP Media Buy Skills - "get_products": self._handle_get_products_skill, - "create_media_buy": self._handle_create_media_buy_skill, - # ✅ NEW: Missing AdCP Discovery Skills (CRITICAL for protocol compliance) - "list_creative_formats": self._handle_list_creative_formats_skill, - "list_accounts": self._handle_list_accounts_skill, - "sync_accounts": self._handle_sync_accounts_skill, - "list_authorized_properties": self._handle_list_authorized_properties_skill, - # ✅ NEW: Missing Media Buy Management Skills (CRITICAL for campaign lifecycle) - "update_media_buy": self._handle_update_media_buy_skill, - "get_media_buys": self._handle_get_media_buys_skill, - "get_media_buy_delivery": self._handle_get_media_buy_delivery_skill, - "update_performance_index": self._handle_update_performance_index_skill, - # AdCP Spec Creative Management (centralized library approach) - "sync_creatives": self._handle_sync_creatives_skill, - "list_creatives": self._handle_list_creatives_skill, - "create_creative": self._handle_create_creative_skill, - "assign_creative": self._handle_assign_creative_skill, - # Creative Management & Approval - "approve_creative": self._handle_approve_creative_skill, - "get_media_buy_status": self._handle_get_media_buy_status_skill, - "optimize_media_buy": self._handle_optimize_media_buy_skill, - # Note: signals skills removed - should come from dedicated signals agents - # Note: legacy get_pricing/get_targeting removed - use get_products and get_adcp_capabilities instead - } - - if skill_name not in skill_handlers: - available_skills = list(skill_handlers.keys()) - raise MethodNotFoundError(message=f"Unknown skill '{skill_name}'. Available skills: {available_skills}") + if skill_name not in DISCOVERY_SKILLS and (auth_error := _no_usable_identity_error(identity)) is not None: + raise _enveloped_auth_error(auth_error) + + skill_handlers = self._skill_handler_map() + + # Defensive about identity shape — test fixtures sometimes pass a string or + # partially-built identity; the canonical recorder handles None internally. + operation = skill_name if skill_name in skill_handlers else "unsupported_skill" + + async def _invoke() -> Any: + # An unknown SKILL is an application-layer failure — the JSON-RPC method + # (message/send) is valid; routing failed inside skill dispatch. Per AdCP + # transport-errors.mdx "Layer Separation" (present since 3.0.0), it belongs in the + # task body as a failed Task with a two-layer envelope, NOT a JSON-RPC + # MethodNotFoundError (reserved for unknown JSON-RPC methods). Raised + # INSIDE the seam so the boundary observability records it exactly + # once (an unknown skill must not bypass record_boundary_error); the outer + # dispatcher's `except AdCPError` re-wraps it into a failed-skill result, + # preserving accumulated results from earlier skills. + if skill_name not in skill_handlers: + raise AdCPCapabilityNotSupportedError( + message="The requested skill is not supported. Call discovery to list available skills." + ) - try: + logger.info("Handling explicit skill: %s", skill_name) handler = skill_handlers[skill_name] # Handlers return raw Pydantic models (or raise typed AdCPError on validation failure) if skill_name == "create_media_buy": - result = await handler(parameters, identity, raw_wire_payload=raw_wire_payload) + result = await handler(parameters, identity, raw_wire_payload=raw_wire_payload, a2a_task_id=task_id) + elif skill_name in _TASK_ID_BEARING_SKILLS: + # create_media_buy is caught by the branch above (it also needs the raw + # wire payload); the other id-bearing skill takes the outer id as a plain + # keyword. See _TASK_ID_BEARING_SKILLS for which skills bear the id and + # why sync_creatives does not. + result = await handler(parameters, identity, a2a_task_id=task_id) else: result = await handler(parameters, identity) # Serialize at the boundary — models become dicts with protocol fields return self._serialize_for_a2a(result) - except A2AError: - # Re-raise A2AError as-is (already properly formatted) - raise - except (AdCPError, ValueError, PermissionError) as e: - # Normalize ValueError/PermissionError to typed AdCPError via the - # shared normalize_to_adcp_error() helper — same mapping the MCP - # and REST boundaries apply. The outer dispatcher's `except - # AdCPError` branch wraps the result into a failed Task with the - # two-layer envelope. - normalized = normalize_to_adcp_error(e) - - # Defensive about identity shape — test fixtures sometimes pass a - # string or partially-built identity instead of ResolvedIdentity. - # record_boundary_error handles None tenant_id internally. - record_boundary_error( - "a2a", - skill_name, - normalized, - tenant_id=getattr(identity, "tenant_id", None), - principal_id=getattr(identity, "principal_id", None) or "anonymous", - ) - if normalized is not e: - raise normalized from e - raise - # Untyped exceptions fall through to the dispatcher's `except Exception` - # at the call site, which routes them through `_build_failed_skill_result` - # for uniform envelope shape. No catch-all here. + # Untyped exceptions are NOT caught by the seam: they fall through to the + # dispatcher's `except Exception` at the call site, which routes them through + # `_build_failed_skill_result` for uniform envelope shape. + return await self._dispatch_under_sanitize_seam(operation, identity, _invoke()) async def _handle_get_products_skill(self, parameters: dict, identity: ResolvedIdentity | None) -> Any: """Handle explicit get_products skill invocation. @@ -1579,6 +2247,7 @@ async def _handle_create_media_buy_skill( parameters: dict, identity: ResolvedIdentity, raw_wire_payload: dict | None = None, + a2a_task_id: str | None = None, ) -> dict: """Handle explicit create_media_buy skill invocation. @@ -1643,7 +2312,7 @@ async def _handle_create_media_buy_skill( ) # Validate via the shared boundary so every A2A handler emits the same - # field + message + buyer-facing suggestion (AdCP POST-F3, #1417): + # field + message + buyer-facing suggestion (AdCP POST-F3): # idempotency_key_missing / duplicate_product_id rejections include a # non-empty suggestion derived by adcp_validation_boundary. with adcp_validation_boundary(): @@ -1661,23 +2330,39 @@ async def _handle_create_media_buy_skill( push_notification_config=push_notification_config, reporting_webhook=params.get("reporting_webhook"), context=params.get("context"), + # Same omission the update handler had: MCP and REST both forward ext. + ext=params.get("ext"), # Wrap for boundary-pattern consistency with delivery/sync_creatives. A crash is # structurally impossible here (create_media_buy_raw re-coerces via # CreateMediaBuyRequest), and to_account_reference is idempotent on an already # typed/dict account — but resolving at the boundary keeps all three handlers uniform. account=to_account_reference(params.get("account")), idempotency_key=params.get("idempotency_key"), + # Audited against create_media_buy_raw's signature by + # test_create_skill_forwards_every_live_raw_parameter: the only buyer-facing + # parameter not forwarded is ``paused``, and that omission is deliberate and + # matches the REST route — pause-on-create is accepted for AdCP 3.1.1 shape + # compatibility but is not honored by _impl (see #1619), so forwarding it + # would advertise an effect the request does not have. identity=identity, # The DataPart params AS SENT (pre-normalization, pre-mutation) are # the idempotency payload-hash input; the post-processed dict is the # fallback only for direct handler callers. raw_wire_payload=raw_wire_payload if raw_wire_payload is not None else params, + # Persist the outer A2A task id on the workflow step so the completion + # webhook / tasks/get correlate to the id the buyer holds. + external_task_id=a2a_task_id, ) return response async def _handle_sync_creatives_skill(self, parameters: dict, identity: ResolvedIdentity) -> dict: - """Handle explicit sync_creatives skill invocation (AdCP spec endpoint).""" + """Handle explicit sync_creatives skill invocation (AdCP spec endpoint). + + Takes no outer ``a2a_task_id``: a sync creates one workflow step per creative, so + the single buyer-facing id cannot name one durable row. See + ``_TASK_ID_BEARING_SKILLS``. + """ # DEBUG: Log incoming parameters logger.info("[A2A sync_creatives] Received parameters keys: %s", list(parameters.keys())) logger.info("[A2A sync_creatives] assignments param: %s", parameters.get("assignments")) @@ -1692,6 +2377,7 @@ async def _handle_sync_creatives_skill(self, parameters: dict, identity: Resolve raise AdCPValidationError( "Missing required parameter: 'creatives'", suggestion="Required: ['creatives']", + _wire_safe_message=True, ) # Construct typed models at the A2A boundary (Pydantic validation at entry). @@ -1758,23 +2444,16 @@ async def _handle_list_creatives_skill(self, parameters: dict, identity: Resolve async def _handle_create_creative_skill(self, parameters: dict, identity: ResolvedIdentity) -> dict: """Handle explicit create_creative skill invocation.""" - tool_context = self._make_tool_context(identity, "create_creative") - - # Map A2A parameters - format_id, content_uri, and name are required. - # Raise typed AdCPValidationError so the outer dispatcher emits a two-layer envelope. - required_params = ["format_id", "content_uri", "name"] - missing_params = [param for param in required_params if param not in parameters] - - if missing_params: - raise AdCPValidationError( - f"Missing required parameters: {missing_params}", - suggestion=f"Required: {required_params}", - ) + # Project Pydantic failures through the shared safe boundary. This keeps + # declared request paths actionable without echoing rejected values or + # raw validator text onto the A2A wire. + with adcp_validation_boundary(context="create_creative request"): + CreateCreativeRequest.model_validate(parameters) # TODO: Implement create_creative tool # Call core function with individual parameters # response = core_create_creative_tool(...) - raise UnsupportedOperationError(message="create_creative skill not yet implemented") + raise AdCPCapabilityNotSupportedError(message="create_creative skill not yet implemented") async def _handle_get_creatives_skill(self, parameters: dict, identity: ResolvedIdentity) -> dict: """Handle explicit get_creatives skill invocation.""" @@ -1790,22 +2469,12 @@ async def _handle_get_creatives_skill(self, parameters: dict, identity: Resolved # include_assignments=parameters.get("include_assignments", False), # identity=identity, # ) - raise UnsupportedOperationError(message="get_creatives skill not yet implemented") + raise AdCPCapabilityNotSupportedError(message="get_creatives skill not yet implemented") async def _handle_assign_creative_skill(self, parameters: dict, identity: ResolvedIdentity) -> dict: """Handle explicit assign_creative skill invocation.""" - tool_context = self._make_tool_context(identity, "assign_creative") - - # Map A2A parameters - media_buy_id, package_id, and creative_id are required. - # Raise typed AdCPValidationError so the outer dispatcher emits a two-layer envelope. - required_params = ["media_buy_id", "package_id", "creative_id"] - missing_params = [param for param in required_params if param not in parameters] - - if missing_params: - raise AdCPValidationError( - f"Missing required parameters: {missing_params}", - suggestion=f"Required: {required_params}", - ) + with adcp_validation_boundary(context="assign_creative request"): + AssignCreativeRequest.model_validate(parameters) # TODO: Implement assign_creative tool # identity already resolved at transport boundary @@ -1819,21 +2488,21 @@ async def _handle_assign_creative_skill(self, parameters: dict, identity: Resolv # override_click_url=parameters.get("override_click_url"), # identity=identity, # ) - raise UnsupportedOperationError(message="assign_creative skill not yet implemented") + raise AdCPCapabilityNotSupportedError(message="assign_creative skill not yet implemented") async def _handle_approve_creative_skill(self, parameters: dict, identity: ResolvedIdentity) -> dict: """Handle explicit approve_creative skill invocation.""" - raise UnsupportedOperationError(message="approve_creative skill not yet implemented") + raise AdCPCapabilityNotSupportedError(message="approve_creative skill not yet implemented") # Signals skill handlers removed - should come from dedicated signals agents async def _handle_get_media_buy_status_skill(self, parameters: dict, identity: ResolvedIdentity) -> dict: """Handle explicit get_media_buy_status skill invocation.""" - raise UnsupportedOperationError(message="get_media_buy_status skill not yet implemented") + raise AdCPCapabilityNotSupportedError(message="get_media_buy_status skill not yet implemented") async def _handle_optimize_media_buy_skill(self, parameters: dict, identity: ResolvedIdentity) -> dict: """Handle explicit optimize_media_buy skill invocation.""" - raise UnsupportedOperationError(message="optimize_media_buy skill not yet implemented") + raise AdCPCapabilityNotSupportedError(message="optimize_media_buy skill not yet implemented") async def _handle_get_adcp_capabilities_skill(self, parameters: dict, identity: ResolvedIdentity | None) -> Any: """Handle explicit get_adcp_capabilities skill invocation (CRITICAL AdCP discovery endpoint). @@ -1861,26 +2530,15 @@ async def _handle_list_creative_formats_skill(self, parameters: dict, identity: """ # Identity already resolved at transport boundary (on_message_send) - # Build request from parameters (all optional). - from src.core.tools.creative_formats import build_list_creative_formats_request + # Validate the complete parameter object so unknown wire fields are + # rejected instead of being silently dropped by individual .get() + # calls. This is the same request model used by REST and MCP. + from src.core.schemas import ListCreativeFormatsRequest # Same context string as the REST route's boundary so buyer-invalid # input produces a byte-identical envelope on every transport (klkg). with adcp_validation_boundary(context="list_creative_formats request"): - req = build_list_creative_formats_request( - format_ids=parameters.get("format_ids"), - output_format_ids=parameters.get("output_format_ids"), - input_format_ids=parameters.get("input_format_ids"), - is_responsive=parameters.get("is_responsive"), - name_search=parameters.get("name_search"), - asset_types=parameters.get("asset_types"), - wcag_level=parameters.get("wcag_level"), - min_width=parameters.get("min_width"), - max_width=parameters.get("max_width"), - min_height=parameters.get("min_height"), - max_height=parameters.get("max_height"), - context=parameters.get("context"), - ) + req = ListCreativeFormatsRequest.model_validate(parameters) # Call core function with identity response = core_list_creative_formats_tool(req=req, identity=identity) @@ -1890,8 +2548,8 @@ async def _handle_list_creative_formats_skill(self, parameters: dict, identity: async def _handle_list_accounts_skill(self, parameters: dict, identity: ResolvedIdentity | None) -> Any: """Handle explicit list_accounts skill invocation. - Authentication is OPTIONAL per BR-RULE-055 — unauthenticated calls - return an empty account list. + Authentication is REQUIRED per BR-RULE-055 because account visibility + is scoped to the authenticated principal. """ from src.core.schemas.account import ListAccountsRequest @@ -1954,7 +2612,13 @@ async def _handle_list_authorized_properties_skill( return response - async def _handle_update_media_buy_skill(self, parameters: dict, identity: ResolvedIdentity) -> dict: + async def _handle_update_media_buy_skill( + self, + parameters: dict, + identity: ResolvedIdentity, + *, + a2a_task_id: str | None = None, + ) -> dict: """Handle explicit update_media_buy skill invocation (CRITICAL for campaign management).""" # Identity already resolved at transport boundary (on_message_send) @@ -1974,6 +2638,7 @@ async def _handle_update_media_buy_skill(self, parameters: dict, identity: Resol raise AdCPValidationError( "Missing required parameter: media_buy_id", suggestion="Provide the media_buy_id of the media buy to update", + _wire_safe_message=True, ) # Validate top-level fields via typed model (packages validated by _raw @@ -1987,7 +2652,12 @@ async def _handle_update_media_buy_skill(self, parameters: dict, identity: Resol context=params.get("context"), ) - # Call core function with validated fields + raw nested structures and identity + # Call core function with validated fields + raw nested structures and identity. + # The forwarded set is the REST route's set (PUT /media-buys/{id}) exactly — see + # test_update_skill_forwards_every_live_raw_parameter, which derives the expected + # keywords from update_media_buy_raw's own signature so a parameter added there can + # no longer be silently dropped on A2A alone. Two earlier rounds each restored only + # the parameters a reviewer happened to name, which is why this is now signature-derived. response = core_update_media_buy_tool( media_buy_id=req.media_buy_id or "", paused=req.paused, @@ -1997,7 +2667,27 @@ async def _handle_update_media_buy_skill(self, parameters: dict, identity: Resol packages=params.get("packages"), push_notification_config=params.get("push_notification_config"), context=params.get("context"), + # Forwarded for parity with the MCP wrapper and the REST route. Dropping + # them here made an A2A update silently non-idempotent, with no reporting + # webhook and no extension object, for a request that carried all three. + reporting_webhook=params.get("reporting_webhook"), + ext=params.get("ext"), + idempotency_key=params.get("idempotency_key"), + # Legacy date aliases and the flight-level economics fields. The REST body + # accepts and forwards all five; A2A dropped them, so a buyer rescheduling a + # flight or changing currency/pacing/daily cap over A2A had those edits + # silently discarded while the same payload applied over REST. + flight_start_date=params.get("flight_start_date"), + flight_end_date=params.get("flight_end_date"), + currency=params.get("currency"), + pacing=params.get("pacing"), + daily_budget=params.get("daily_budget"), + # targeting_overlay and creatives are DELIBERATELY not forwarded, matching the + # REST route's identical omission: update_media_buy_raw accepts both in its + # signature but drops them before _build_update_request, so forwarding them + # would be a silent no-op that reads like working plumbing (see #1417). identity=identity, + external_task_id=a2a_task_id, ) return response @@ -2304,25 +2994,13 @@ def create_agent_card() -> AgentCard: description="Search and query creative library with advanced filtering (AdCP spec)", tags=["creative", "library", "search", "adcp", "spec"], ), - # Creative Management & Approval - AgentSkill( - id="approve_creative", - name="approve_creative", - description="Review and approve/reject creative assets (admin only)", - tags=["creative", "approval", "review", "adcp"], - ), - AgentSkill( - id="get_media_buy_status", - name="get_media_buy_status", - description="Check status and performance of media buys", - tags=["status", "performance", "tracking", "adcp"], - ), - AgentSkill( - id="optimize_media_buy", - name="optimize_media_buy", - description="Optimize media buy performance and targeting", - tags=["optimization", "performance", "targeting", "adcp"], - ), + # Note: approve_creative, get_media_buy_status, and optimize_media_buy are + # deliberately NOT advertised. Their handlers unconditionally + # raise UNSUPPORTED_FEATURE, so advertising them would promise capabilities + # the agent does not provide. They stay registered in _skill_handler_map and + # remain reachable-but-unsupported (structured UNSUPPORTED_FEATURE failed + # Task) if a buyer invokes them by name — they are just no longer offered on + # the card. The test oracle (SKILL_METADATA) marks them advertised: False. # Note: signals skills removed - should come from dedicated signals agents # Note: legacy get_pricing/get_targeting removed - use get_products and get_adcp_capabilities instead ], diff --git a/src/adapters/broadstreet/adapter.py b/src/adapters/broadstreet/adapter.py index dfb08d887d..470a6fe2bd 100644 --- a/src/adapters/broadstreet/adapter.py +++ b/src/adapters/broadstreet/adapter.py @@ -166,7 +166,7 @@ def _extract_campaign_id(self, media_buy_id: str) -> str: AdCPValidationError: If media_buy_id is empty. """ if not media_buy_id: - raise AdCPValidationError("media_buy_id cannot be empty") + raise AdCPValidationError("media_buy_id cannot be empty", _wire_safe_message=True) if media_buy_id.startswith("bs_"): return media_buy_id[3:] # Remove "bs_" prefix @@ -735,9 +735,15 @@ def update_media_buy( # Budget update: persist to database (Broadstreet has no budget API) if action == "update_package_budget": if not package_id: - raise AdCPValidationError("package_id is required for update_package_budget action", field="package_id") + raise AdCPValidationError( + "package_id is required for update_package_budget action", + field="package_id", + _wire_safe_message=True, + ) if budget is None: - raise AdCPValidationError("budget is required for update_package_budget action", field="budget") + raise AdCPValidationError( + "budget is required for update_package_budget action", field="budget", _wire_safe_message=True + ) with get_db_session() as session: repo = MediaBuyRepository(session, self.tenant_id) @@ -764,12 +770,15 @@ def update_media_buy( if action == "update_package_impressions": if not package_id: raise AdCPValidationError( - "package_id is required for update_package_impressions action", field="package_id" + "package_id is required for update_package_impressions action", + field="package_id", + _wire_safe_message=True, ) if budget is None: raise AdCPValidationError( "budget (impressions) is required for update_package_impressions action", field="budget", + _wire_safe_message=True, ) with get_db_session() as session: diff --git a/src/adapters/mock_ad_server.py b/src/adapters/mock_ad_server.py index dd29238ced..65f19af852 100644 --- a/src/adapters/mock_ad_server.py +++ b/src/adapters/mock_ad_server.py @@ -808,6 +808,7 @@ def _create_media_buy_immediate( raise AdCPValidationError( "Simulated error: Invalid targeting parameters", field="targeting", + _wire_safe_message=True, ) if self._should_force_error("inventory_unavailable"): diff --git a/src/admin/blueprints/creatives.py b/src/admin/blueprints/creatives.py index 9f4afc62a4..839e109422 100644 --- a/src/admin/blueprints/creatives.py +++ b/src/admin/blueprints/creatives.py @@ -22,7 +22,7 @@ ) from src.core.database.repositories.creative import CreativeRepository from src.core.schemas.creative import SyncCreativeResult, SyncCreativesResponse -from src.core.webhook_validator import validate_webhook_task_type +from src.core.webhook_validator import resolve_webhook_task_id, validate_webhook_task_type from src.services.protocol_webhook_service import get_protocol_webhook_service # TODO: Missing module - these functions need to be implemented @@ -44,8 +44,15 @@ def discover_creative_formats_from_url(url): from src.admin.utils import echo_context, require_tenant_access from src.admin.utils.audit_decorator import log_admin_action +from src.core.database.repositories.media_buy import ApprovalTrigger from src.core.database.repositories.uow import AdminCreativeUoW -from src.core.tools.media_buy_create import execute_approved_media_buy, push_creative_to_existing_buy +from src.core.logging_config import log_safe +from src.core.tools.media_buy_create import push_creative_to_existing_buy +from src.core.workflow_finalization import ( + ApprovalExecutionStatus, + execute_and_finalize_media_buy_approval, + prepare_media_buy_approval_execution, +) # Note: CreativeFormat table was dropped in migration f2addf453200 # All format-related routes have been removed @@ -79,31 +86,6 @@ def _cleanup_completed_tasks(): logger.debug(f"Cleaned up completed AI review task: {task_id}") -def _compute_media_buy_status_from_flight_dates(media_buy) -> str: - """Compute status based on flight dates: 'active' if within window, else 'scheduled'.""" - now = datetime.now(UTC) - - start_time = None - if media_buy.start_time: - raw_start = media_buy.start_time - start_time = raw_start.replace(tzinfo=UTC) if raw_start.tzinfo is None else raw_start.astimezone(UTC) - elif media_buy.start_date: - start_time = datetime.combine(media_buy.start_date, datetime.min.time()).replace(tzinfo=UTC) - - end_time = None - if media_buy.end_time: - raw_end = media_buy.end_time - end_time = raw_end.replace(tzinfo=UTC) if raw_end.tzinfo is None else raw_end.astimezone(UTC) - elif media_buy.end_date: - end_time = datetime.combine(media_buy.end_date, datetime.max.time()).replace(tzinfo=UTC) - - # If start time passed and end time not passed, set to active - if start_time and end_time and now >= start_time and now <= end_time: - return "active" - - return "scheduled" - - async def _call_webhook_for_creative_status( creative_id, tenant_id: str, @@ -238,13 +220,17 @@ async def _call_webhook_for_creative_status( # step_tool_name is untrusted (workflow_steps DB column). Validate a # COPY for the SDK payload; keep the original label for metadata - # (salesagent-yi3s, salesagent-yk7o). + # used by delivery metadata. wire_task_type = validate_webhook_task_type(step_tool_name or "sync_creatives") + # Send the buyer-facing correlation id (the id they hold), falling back to the + # step id — same resolution the media-buy approve webhook / context_manager use. + correlation_task_id = resolve_webhook_task_id(step_request_data, step_step_id) + payload: Task | TaskStatusUpdateEvent | McpWebhookPayload if protocol == "a2a": payload = create_a2a_webhook_payload( - task_id=step_step_id, + task_id=correlation_task_id, status=GeneratedTaskStatus.completed, result=result_dict, context_id=step_context_id, @@ -252,7 +238,7 @@ async def _call_webhook_for_creative_status( else: # SDK 5.7: returns McpWebhookPayload directly payload = create_mcp_webhook_payload( - task_id=step_step_id, + task_id=correlation_task_id, status=GeneratedTaskStatus.completed, task_type=wire_task_type, result=result_dict, @@ -587,7 +573,9 @@ def approve_creative(tenant_id, creative_id, **kwargs): assignment_buy_ids = [a.media_buy_id for a in assignments] logger.info( - f"[CREATIVE APPROVAL] Creative {creative_id} approved, checking {len(assignments)} media buy assignments" + "[CREATIVE APPROVAL] Creative %s approved, checking %s media buy assignments", + log_safe(creative_id), + len(assignments), ) # Snapshot buy statuses here to avoid a second UoW after commit @@ -600,29 +588,51 @@ def approve_creative(tenant_id, creative_id, **kwargs): continue assignment_buy_statuses[media_buy_id] = media_buy.status - logger.info(f"[CREATIVE APPROVAL] Media buy {media_buy_id} status: {media_buy.status}") - - if media_buy.status in {"pending_creatives", "draft"}: - # Get all creative assignments for this media buy - all_assignments = uow.assignments.get_by_media_buy(media_buy_id) - - creative_ids = [a.creative_id for a in all_assignments] - all_creatives = uow.creatives.admin_get_by_ids(creative_ids) - - unapproved_creatives = [ - c.creative_id for c in all_creatives if c.status not in ["approved", "active"] - ] + logger.info( + "[CREATIVE APPROVAL] Media buy %s status: %s", + log_safe(media_buy_id), + log_safe(media_buy.status), + ) + # The eligible source states for THIS trigger are derived from the + # canonical set beside its declaration, not restated here. The bare + # ``{"pending_creatives", "draft"}`` literal that used to gate this was a + # hand-copy of that derivation with its reasoning nowhere — and the + # reasoning is the load-bearing part: a buy still awaiting a human + # decision must NOT be promoted by a creative approval. + preparation = prepare_media_buy_approval_execution( + media_buys=uow.media_buys, + assignments=uow.assignments, + creatives=uow.creatives, + media_buy_id=media_buy_id, + # Human approval was recorded when the buy entered + # pending_creatives. Creative unblocking must not replace + # that audit identity or timestamp with a system actor. + approved_by=None, + trigger=ApprovalTrigger.CREATIVE_UNBLOCK, + ) + if preparation.status is ApprovalExecutionStatus.READY: + media_buy_actions.append({"media_buy_id": media_buy_id}) + elif preparation.status is ApprovalExecutionStatus.WAITING_FOR_CREATIVES: logger.info( - f"[CREATIVE APPROVAL] Media buy {media_buy_id} has {len(unapproved_creatives)} unapproved creatives remaining" + "[CREATIVE APPROVAL] Media buy %s still waiting for %s creatives: %s", + log_safe(media_buy_id), + len(preparation.blocking_creative_ids), + log_safe(preparation.blocking_creative_ids), + ) + elif preparation.status is ApprovalExecutionStatus.CLAIM_REFUSED: + logger.info( + "[CREATIVE APPROVAL] Media buy %s execution was already claimed", + log_safe(media_buy_id), + ) + else: + # NOT_EXECUTABLE. Most often the buy is still awaiting a human + # decision, which this trigger deliberately may not promote. + logger.info( + "[CREATIVE APPROVAL] Media buy %s is not executable by a creative unblock (status %s)", + log_safe(media_buy_id), + log_safe(media_buy.status), ) - - if not unapproved_creatives: - media_buy_actions.append({"media_buy_id": media_buy_id}) - else: - logger.info( - f"[CREATIVE APPROVAL] Media buy {media_buy_id} still waiting for {len(unapproved_creatives)} creatives: {unapproved_creatives}" - ) # UoW auto-commits here @@ -639,26 +649,38 @@ def approve_creative(tenant_id, creative_id, **kwargs): # Execute adapter creation for unblocked media buys for action in media_buy_actions: logger.info( - f"[CREATIVE APPROVAL] All creatives approved for media buy {action['media_buy_id']}, executing adapter creation" + "[CREATIVE APPROVAL] All creatives approved for media buy %s, executing adapter creation", + log_safe(action["media_buy_id"]), + ) + + outcome = execute_and_finalize_media_buy_approval( + tenant_id=tenant_id, + media_buy_id=action["media_buy_id"], + step_id=None, + apply_flight_status=True, ) - success, error_msg = execute_approved_media_buy(action["media_buy_id"], tenant_id) - - if success: - # Update media buy status in a separate UoW - with AdminCreativeUoW(tenant_id) as uow2: - assert uow2.media_buys is not None - mb = uow2.media_buys.get_by_id(action["media_buy_id"]) - if mb: - new_status = _compute_media_buy_status_from_flight_dates(mb) - mb.status = new_status - mb.approved_at = datetime.now(UTC) - mb.approved_by = "system" - # auto-commits - - logger.info(f"[CREATIVE APPROVAL] Media buy {action['media_buy_id']} successfully created in adapter") + if outcome.status is ApprovalExecutionStatus.SUCCEEDED: + logger.info( + "[CREATIVE APPROVAL] Media buy %s successfully created in adapter", + log_safe(action["media_buy_id"]), + ) + elif outcome.status is ApprovalExecutionStatus.FAILED: + logger.error( + "[CREATIVE APPROVAL] Adapter creation failed for %s: %s", + log_safe(action["media_buy_id"]), + log_safe(outcome.error_message), + ) + elif outcome.status is ApprovalExecutionStatus.PENDING_RECONCILIATION: + logger.error( + "[CREATIVE APPROVAL] External media buy creation succeeded but activation remains pending for %s", + log_safe(action["media_buy_id"]), + ) else: - logger.error(f"[CREATIVE APPROVAL] Adapter creation failed for {action['media_buy_id']}: {error_msg}") + logger.warning( + "[CREATIVE APPROVAL] Adapter outcome could not finalize workflow for media buy %s", + log_safe(action["media_buy_id"]), + ) # Retroactive push for already-live buys (#1038): # Buys in pending_creatives/draft were handled above. For buys that are @@ -670,7 +692,11 @@ def approve_creative(tenant_id, creative_id, **kwargs): ] for buy_id in buys_to_push: - logger.info(f"[CREATIVE APPROVAL] Retroactive push: creative {creative_id} → live buy {buy_id}") + logger.info( + "[CREATIVE APPROVAL] Retroactive push: creative %s → live buy %s", + log_safe(creative_id), + log_safe(buy_id), + ) push_success, push_err = push_creative_to_existing_buy( creative_id=creative_id, media_buy_id=buy_id, @@ -678,7 +704,10 @@ def approve_creative(tenant_id, creative_id, **kwargs): ) if not push_success: logger.error( - f"[CREATIVE APPROVAL] Retroactive push failed for creative {creative_id} → buy {buy_id}: {push_err}" + "[CREATIVE APPROVAL] Retroactive push failed for creative %s → buy %s: %s", + log_safe(creative_id), + log_safe(buy_id), + log_safe(push_err), ) push_warnings.append(f"Creative push to buy {buy_id} failed — see server logs for details") diff --git a/src/admin/blueprints/operations.py b/src/admin/blueprints/operations.py index efc6a86747..786692c0cf 100644 --- a/src/admin/blueprints/operations.py +++ b/src/admin/blueprints/operations.py @@ -6,18 +6,29 @@ from adcp import Error, create_a2a_webhook_payload, create_mcp_webhook_payload from adcp.types import GeneratedTaskStatus as AdcpTaskStatus - -# FIXME(#1388): Package has a local subclass; import from src.core.schemas (Pattern #7/#4). -from adcp.types import Package from flask import Blueprint, request from sqlalchemy import select - -from src.admin.utils import echo_context, require_auth, require_tenant_access +from werkzeug.wrappers import Response + +from src.admin.utils import echo_context, require_auth, require_tenant_access, session_user_email +from src.admin.utils.approval import ( + APPROVED_MEDIA_BUY_EXECUTION_FAILURE_MESSAGE, + APPROVED_MEDIA_BUY_PENDING_RECONCILIATION_MESSAGE, + waiting_for_creatives_message, +) from src.core.database.models import PushNotificationConfig +from src.core.database.repositories.creative import CreativeAssignmentRepository, CreativeRepository from src.core.database.repositories.media_buy import MediaBuyRepository +from src.core.database.repositories.workflow import WorkflowRepository from src.core.exceptions import AdCPMediaBuyRejectedError -from src.core.schemas import CreateMediaBuyError, CreateMediaBuySuccess -from src.core.webhook_validator import validate_webhook_task_type +from src.core.logging_config import log_safe +from src.core.schemas import CreateMediaBuyError +from src.core.webhook_validator import resolve_webhook_task_id, validate_webhook_task_type +from src.core.workflow_finalization import ( + ApprovalExecutionStatus, + execute_and_finalize_media_buy_approval, + prepare_media_buy_approval_execution, +) from src.services.protocol_webhook_service import get_protocol_webhook_service logger = logging.getLogger(__name__) @@ -25,7 +36,7 @@ def _as_request_dict(value: dict[str, Any] | str | None) -> dict[str, Any]: """Narrow JSONType (dict|str|None) to a dict for .get() / echo_context.""" - return value if isinstance(value, dict) else {} + return dict(value) if isinstance(value, dict) else {} # Create blueprint @@ -109,7 +120,6 @@ def media_buy_detail(tenant_id, media_buy_id): CreativeAssignment, Principal, Product, - WorkflowStep, ) try: @@ -179,20 +189,14 @@ def media_buy_detail(tenant_id, media_buy_id): ctx_manager = ContextManager() workflow_steps = ctx_manager.get_object_lifecycle("media_buy", media_buy_id, tenant_id=tenant_id) - # Find if there's a pending approval step - pending_approval_step = None - for step in workflow_steps: - if step.get("status") in ["requires_approval", "pending_approval"]: - # Get the full workflow step for approval actions (tenant-scoped via Context join) - from src.core.database.models import Context as DBContext - - stmt = ( - select(WorkflowStep) - .join(DBContext) - .where(DBContext.tenant_id == tenant_id, WorkflowStep.step_id == step["step_id"]) - ) - pending_approval_step = db_session.scalars(stmt).first() - break + # Find the step awaiting a decision for this media buy, via the repository so the + # canonical APPROVABLE_STEP_STATUSES (incl. the legacy ``approval`` alias) is used — + # the same set the approve/reject route and the atomic claim/reject methods use. + # An inline {requires_approval, pending_approval} filter here would hide the approval + # UI for legacy ``approval`` steps that the POST route can in fact action. + pending_approval_step = WorkflowRepository(db_session, tenant_id).get_approvable_step_for_object( + "media_buy", media_buy_id + ) # Get computed readiness state (not just raw database status) from src.admin.services.media_buy_readiness_service import MediaBuyReadinessService @@ -302,7 +306,7 @@ def _media_buy_webhook_metadata(step_data: dict, tenant_id: str, media_buy_id: s The protocol webhook service reads task_type/tenant_id/principal_id/ media_buy_id from this dict for delivery logging and the audit trail (protocol_webhook_service.py) — populate all four. Shared by the approve - and reject branches (PR #1567 round-2 cleanup). + and reject branches. """ return { "task_type": step_data["tool_name"], @@ -312,6 +316,19 @@ def _media_buy_webhook_metadata(step_data: dict, tenant_id: str, media_buy_id: s } +def _refused_media_buy_redirect(tenant_id: str, media_buy_id: str, message: str) -> Response: + """Flash ``message`` and redirect back to the media-buy detail page. + + The approve and reject routes both refuse an atomic claim/reject the same way — flash an + error, then redirect to the detail page — differing only in wording. One home so the + redirect target can't drift between the two branches. + """ + from flask import flash, redirect, url_for + + flash(message, "error") + return redirect(url_for("operations.media_buy_detail", tenant_id=tenant_id, media_buy_id=media_buy_id)) + + @operations_bp.route("/media-buy//approve", methods=["POST"]) @require_tenant_access() def approve_media_buy(tenant_id, media_buy_id, **kwargs): @@ -322,36 +339,35 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): from sqlalchemy.orm import attributes from src.core.database.database_session import get_db_session - from src.core.database.models import Context as DBContext - from src.core.database.models import ObjectWorkflowMapping, WorkflowStep try: action = request.form.get("action") # "approve" or "reject" reason = request.form.get("reason", "") + requested_step_id = request.form.get("workflow_step_id") with get_db_session() as db_session: - # Find the pending approval workflow step for this media buy (tenant-scoped via Context join) - stmt = ( - select(WorkflowStep) - .join(ObjectWorkflowMapping, WorkflowStep.step_id == ObjectWorkflowMapping.step_id) - .join(DBContext) - .filter( - DBContext.tenant_id == tenant_id, - ObjectWorkflowMapping.object_type == "media_buy", - ObjectWorkflowMapping.object_id == media_buy_id, - WorkflowStep.status.in_(["requires_approval", "pending_approval"]), + # Find the workflow step awaiting a decision for this media buy, via the repository + # so the lookup uses the CANONICAL APPROVABLE_STEP_STATUSES (incl. the legacy + # ``approval`` alias GAM/Broadstreet emit) — the same source set the atomic + # claim_approval/reject_if_approvable methods guard on. An inline + # {requires_approval, pending_approval} filter here would drop legacy ``approval`` + # steps before they ever reached the claim/reject below. + step = ( + WorkflowRepository(db_session, tenant_id).get_approvable_step_for_object( + "media_buy", media_buy_id, step_id=requested_step_id ) + if requested_step_id + else None ) - step = db_session.scalars(stmt).first() if not step: - flash("No pending approval found for this media buy", "warning") + flash("The selected approval is missing or no longer pending for this media buy", "warning") return redirect(url_for("operations.media_buy_detail", tenant_id=tenant_id, media_buy_id=media_buy_id)) # Extract step data to dict to avoid detached instance errors after commit/nested sessions. # JSONType columns are typed as dict|str|None; narrow before echo_context / .get(). request_data = _as_request_dict(step.request_data) - step_data = { + step_data: dict[str, Any] = { "step_id": step.step_id, "context_id": step.context_id, "tool_name": step.tool_name, @@ -359,10 +375,7 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): } # Get user info for audit - from flask import session as flask_session - - user_info = flask_session.get("user", {}) - user_email = user_info.get("email", "system") if isinstance(user_info, dict) else str(user_info) + user_email = session_user_email(default="system") approve_repo = MediaBuyRepository(db_session, tenant_id) media_buy = approve_repo.get_by_id(media_buy_id) @@ -378,7 +391,19 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): } if action == "approve": - step.status = "approved" + # Atomic compare-and-set claim: requires_approval/pending_approval → approved + # via the source-state-guarded primitive. Because ``approved`` is non-terminal, + # a broad terminal-guard would let a second concurrent approver win an + # approved→approved no-op and ALSO run the irreversible adapter creation below + # (duplicate order). claim_approval admits exactly one approver; a loser (already + # approved, canceled, or otherwise not awaiting approval) returns None → refuse + # and DO NOT run the irreversible adapter creation. + if WorkflowRepository(db_session, tenant_id).claim_approval(step.step_id) is None: + return _refused_media_buy_redirect( + tenant_id, + media_buy_id, + "This step is no longer awaiting approval (already approved or finalized).", + ) step.updated_at = datetime.now(UTC) if not step.comments: @@ -392,91 +417,82 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): ) attributes.flag_modified(step, "comments") - if media_buy and media_buy.status == "pending_approval": - # Check if all creatives are approved before moving to scheduled - from src.core.database.models import Creative, CreativeAssignment - - stmt_assignments = select(CreativeAssignment).filter_by( - tenant_id=tenant_id, media_buy_id=media_buy_id - ) - assignments = db_session.scalars(stmt_assignments).all() - - all_creatives_approved = True - if assignments: - creative_ids = [a.creative_id for a in assignments] - stmt_creatives = select(Creative).filter( - Creative.tenant_id == tenant_id, Creative.creative_id.in_(creative_ids) + # No status pre-filter: prepare_media_buy_approval_execution owns the whole + # eligibility decision and reports NOT_EXECUTABLE. The literal that used to + # sit here recognised only ``pending_approval``, so approving a + # pending_creatives or draft buy fell through to the plain-workflow branch + # below — step terminalized, operator told "approved successfully", buy + # never executed and the creative gate never run. + preparation = prepare_media_buy_approval_execution( + media_buys=approve_repo, + assignments=CreativeAssignmentRepository(db_session, tenant_id), + creatives=CreativeRepository(db_session, tenant_id), + media_buy_id=media_buy_id, + approved_by=user_email, + ) + if preparation.status is not ApprovalExecutionStatus.NOT_EXECUTABLE: + # Commit the human decision and irreversible domain claim + # atomically. A crash after this commit is recoverable from + # ``activating``; no second request may dispatch the adapter. + if preparation.status is ApprovalExecutionStatus.WAITING_FOR_CREATIVES: + db_session.commit() + flash( + waiting_for_creatives_message(len(preparation.blocking_creative_ids)), + "info", + ) + return redirect( + url_for("operations.media_buy_detail", tenant_id=tenant_id, media_buy_id=media_buy_id) + ) + if preparation.status is ApprovalExecutionStatus.CLAIM_REFUSED: + db_session.rollback() + return _refused_media_buy_redirect( + tenant_id, + media_buy_id, + "This media buy is already executing or no longer pending approval.", ) - creatives = db_session.scalars(stmt_creatives).all() - - # Check if any creatives are not approved - for creative in creatives: - if creative.status != "approved": - all_creatives_approved = False - break - else: - # No creatives assigned yet - all_creatives_approved = False - - # Update status based on creative approval state - if all_creatives_approved: - if media_buy.start_time and media_buy.end_time: - # Compute flight window - if media_buy.start_time: - start_time = ( - media_buy.start_time.astimezone(UTC) - if media_buy.start_time.tzinfo - else media_buy.start_time.replace(tzinfo=UTC) - ) - - if media_buy.end_time: - end_time = ( - media_buy.end_time.astimezone(UTC) - if media_buy.end_time.tzinfo - else media_buy.end_time.replace(tzinfo=UTC) - ) - - now = datetime.now(UTC) - if now < start_time: - media_buy.status = "scheduled" - elif now > end_time: - media_buy.status = "completed" - else: - media_buy.status = "active" - else: - # No start or end time - set to active - media_buy.status = "active" - else: - # Keep it in a state that shows it needs creative approval - # Use "draft" which will be displayed as "needs_approval" or "needs_creatives" by readiness service - media_buy.status = "draft" - - media_buy.approved_at = datetime.now(UTC) - media_buy.approved_by = user_email db_session.commit() - # Execute adapter creation for approved media buy - # This creates the order/line items in GAM (or other adapter) - # Uses the same logic as auto-approved media buys - from src.core.tools.media_buy_create import execute_approved_media_buy - - logger.info(f"[APPROVAL] Executing adapter creation for approved media buy {media_buy_id}") - success, error_msg = execute_approved_media_buy(media_buy_id, tenant_id) - - if not success: - # Adapter creation failed - update status and show error - with get_db_session() as error_session: - error_repo = MediaBuyRepository(error_session, tenant_id) - error_buy = error_repo.update_status(media_buy_id, "failed") - if error_buy: - error_session.commit() + logger.info( + "[APPROVAL] Executing adapter creation for approved media buy %s", + log_safe(media_buy_id), + ) + outcome = execute_and_finalize_media_buy_approval( + tenant_id=tenant_id, + media_buy_id=media_buy_id, + step_id=step_data["step_id"], + context=echo_context(request_data), + ) + if outcome.status is ApprovalExecutionStatus.PENDING_RECONCILIATION: + logger.error( + "[APPROVAL] External media buy creation succeeded but activation remains pending for %s", + log_safe(media_buy_id), + ) + flash(APPROVED_MEDIA_BUY_PENDING_RECONCILIATION_MESSAGE, "warning") + return redirect( + url_for("operations.media_buy_detail", tenant_id=tenant_id, media_buy_id=media_buy_id) + ) - flash(f"Media buy approved but adapter creation failed: {error_msg}", "error") + if outcome.status is ApprovalExecutionStatus.FAILED: + logger.error( + "[APPROVAL] Adapter creation failed for %s: %s", + log_safe(media_buy_id), + log_safe(outcome.error_message), + ) + flash(APPROVED_MEDIA_BUY_EXECUTION_FAILURE_MESSAGE, "error") + return redirect( + url_for("operations.media_buy_detail", tenant_id=tenant_id, media_buy_id=media_buy_id) + ) + if outcome.status is ApprovalExecutionStatus.FINALIZATION_FAILED: + logger.error( + "[APPROVAL] Adapter succeeded but workflow step %s could not be finalized", + log_safe(step_data["step_id"]), + ) + flash("Media buy was created but its workflow result could not be finalized", "error") return redirect( url_for("operations.media_buy_detail", tenant_id=tenant_id, media_buy_id=media_buy_id) ) - logger.info(f"[APPROVAL] Adapter creation succeeded for {media_buy_id}") + logger.info("[APPROVAL] Adapter creation succeeded for %s", log_safe(media_buy_id)) # Send webhook notification to buyer webhook_config = None @@ -494,33 +510,21 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): webhook_config = db_session.scalars(stmt_webhook).first() if webhook_config and media_buy_data: - approve_repo = MediaBuyRepository(db_session, tenant_id) - all_packages = approve_repo.get_packages(media_buy_id) - - # Echo the buyer's request context (shared helper, also used by - # the creative approval webhook in blueprints/creatives.py). - approve_context = echo_context(request_data) - - # The buy IS committed at this point, so a confirmed Success - # (status/confirmed_at/revision from the subclass defaults) is - # semantically correct here — route through the sync_success() - # factory like every sibling construction site (PR #1567 round-2 cleanup). - create_media_buy_approved_result = CreateMediaBuySuccess.sync_success( - media_buy_id=media_buy_id, - packages=[Package(package_id=x.package_id) for x in all_packages], - context=approve_context, - ) + assert outcome.finalization is not None + assert outcome.finalization.result is not None + create_media_buy_approved_result = outcome.finalization.result metadata = _media_buy_webhook_metadata(step_data, tenant_id, media_buy_id, media_buy_data) # Determine protocol type from workflow step request_data protocol = step_data["request_data"].get( "protocol", "mcp" ) # Default to MCP for backward compatibility + correlation_task_id = resolve_webhook_task_id(step_data["request_data"], step_data["step_id"]) # Create appropriate webhook payload based on protocol if protocol == "a2a": create_media_buy_approved_payload = create_a2a_webhook_payload( - task_id=step_data["step_id"], + task_id=correlation_task_id, status=AdcpTaskStatus.completed, result=create_media_buy_approved_result, context_id=step_data["context_id"], @@ -528,9 +532,9 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): else: # tool_name is untrusted (workflow_steps DB column). # Validate a COPY for the SDK payload; metadata keeps - # the original label (salesagent-yi3s, salesagent-yk7o). + # the original label for delivery metadata. create_media_buy_approved_payload = create_mcp_webhook_payload( - task_id=step_data["step_id"], + task_id=correlation_task_id, task_type=validate_webhook_task_type(step_data.get("tool_name", "create_media_buy")), result=create_media_buy_approved_result, status=AdcpTaskStatus.completed, @@ -551,12 +555,34 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): flash("Media buy approved and order created successfully", "success") else: + if ( + WorkflowRepository(db_session, tenant_id).complete_claimed_approval(step_data["step_id"]) + is None + ): + db_session.rollback() + flash("Workflow result could not be finalized; please retry approval", "error") + return redirect( + url_for("operations.media_buy_detail", tenant_id=tenant_id, media_buy_id=media_buy_id) + ) db_session.commit() flash("Media buy approved successfully", "success") elif action == "reject": - step.status = "rejected" - step.error_message = reason or "Rejected by administrator" + # Atomic compare-and-set with the SAME source-state guard as approve (mirror): + # a step already approved (execution underway), canceled, or otherwise not + # awaiting a decision returns None → refuse the reject. This prevents rejecting + # an approved step and stranding a live ad-server order behind a rejected workflow. + if ( + WorkflowRepository(db_session, tenant_id).reject_if_approvable( + step.step_id, error_message=reason or "Rejected by administrator" + ) + is None + ): + return _refused_media_buy_redirect( + tenant_id, + media_buy_id, + "This step is no longer awaiting a decision (already approved or finalized).", + ) step.updated_at = datetime.now(UTC) if not step.comments: @@ -570,8 +596,13 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): ) attributes.flag_modified(step, "comments") - if media_buy and media_buy.status == "pending_approval": - media_buy.status = "rejected" + # Guarded in the UPDATE rather than assigned here: a raw write had no + # source-state guard (it could mark a buy rejected after execution was + # already claimed) and recognised only ``pending_approval``, so rejecting + # a pending_creatives or draft buy left it in its old state while its + # workflow step said rejected. + if media_buy: + approve_repo.reject_pending_execution(media_buy_id) db_session.commit() @@ -600,7 +631,7 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): # Route the code through the typed AdCPError cascade so the buyer sees # the same WIRE code the tool path emits for this event # (MEDIA_BUY_REJECTED is internal-only; wire_error_code translates it - # to POLICY_VIOLATION — never hand-pick codes here; PR #1567 round-2 item 1). + # to POLICY_VIOLATION — never hand-pick codes here). rejection = AdCPMediaBuyRejectedError(f"Rejected: {reason or 'No reason provided'}") create_media_buy_rejected_result = CreateMediaBuyError( errors=[Error(code=rejection.wire_error_code, message=rejection.message)] @@ -611,11 +642,12 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): protocol = step_data["request_data"].get( "protocol", "mcp" ) # Default to MCP for backward compatibility + correlation_task_id = resolve_webhook_task_id(step_data["request_data"], step_data["step_id"]) # Create appropriate webhook payload based on protocol if protocol == "a2a": create_media_buy_rejected_payload = create_a2a_webhook_payload( - task_id=step_data["step_id"], + task_id=correlation_task_id, status=AdcpTaskStatus.rejected, result=create_media_buy_rejected_result, context_id=step_data["context_id"], @@ -623,9 +655,9 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): else: # tool_name is untrusted (workflow_steps DB column). # Validate a COPY for the SDK payload; metadata keeps the - # original label (salesagent-yi3s, salesagent-yk7o). + # original label for delivery metadata. create_media_buy_rejected_payload = create_mcp_webhook_payload( - task_id=step_data["step_id"], + task_id=correlation_task_id, task_type=validate_webhook_task_type(step_data.get("tool_name", "create_media_buy")), result=create_media_buy_rejected_result, status=AdcpTaskStatus.rejected, @@ -647,6 +679,11 @@ def approve_media_buy(tenant_id, media_buy_id, **kwargs): flash("Media buy rejected", "info") + else: + # Neither approve nor reject (unknown/missing action) — a no-op would be + # indistinguishable from success to the operator. Flash and redirect. + flash(f"Unknown action: {action!r}", "error") + return redirect(url_for("operations.media_buy_detail", tenant_id=tenant_id, media_buy_id=media_buy_id)) except Exception as e: diff --git a/src/admin/blueprints/policy.py b/src/admin/blueprints/policy.py index 5ab20e02ae..2f0201a0f1 100644 --- a/src/admin/blueprints/policy.py +++ b/src/admin/blueprints/policy.py @@ -6,11 +6,12 @@ from flask import Blueprint, jsonify, redirect, render_template, request, session, url_for from sqlalchemy import select -from src.admin.utils import get_tenant_config_from_db, require_auth +from src.admin.utils import get_tenant_config_from_db, require_tenant_access, session_user_email from src.admin.utils.audit_decorator import log_admin_action from src.core.audit_logger import AuditLogger from src.core.database.database_session import get_db_session -from src.core.database.models import AuditLog, Context, Tenant, WorkflowStep +from src.core.database.models import AuditLog, Tenant, WorkflowStep +from src.core.database.repositories.workflow import WorkflowRepository logger = logging.getLogger(__name__) @@ -19,16 +20,13 @@ @policy_bp.route("/", methods=["GET"]) -@require_auth() +@require_tenant_access() def index(tenant_id): """View and manage policy settings for the tenant.""" - # Check access + # Tenant membership is enforced by require_tenant_access; viewers stay read-blocked. if session.get("role") == "viewer": return "Access denied", 403 - if session.get("role") == "tenant_admin" and session.get("tenant_id") != tenant_id: - return "Access denied", 403 - with get_db_session() as db_session: # Get tenant info tenant = db_session.scalars(select(Tenant).filter_by(tenant_id=tenant_id)).first() @@ -138,17 +136,14 @@ def index(tenant_id): @policy_bp.route("/update", methods=["POST"]) -@require_auth() +@require_tenant_access() @log_admin_action("update_policy") def update(tenant_id): """Update policy settings for the tenant.""" - # Check access - only admins can update policy + # Tenant membership is enforced by require_tenant_access; role gate stays for test-mode. if session.get("role") not in ["super_admin", "tenant_admin"]: return "Access denied", 403 - if session.get("role") == "tenant_admin" and session.get("tenant_id") != tenant_id: - return "Access denied", 403 - try: # Get current config config = get_tenant_config_from_db(tenant_id) @@ -208,24 +203,21 @@ def parse_textarea_lines(field_name): @policy_bp.route("/rules", methods=["GET", "POST"]) -@require_auth() +@require_tenant_access() def rules(tenant_id): """Redirect old policy rules URL to new comprehensive policy settings page.""" return redirect(url_for("policy.index", tenant_id=tenant_id)) @policy_bp.route("/review/", methods=["GET", "POST"]) -@require_auth() +@require_tenant_access() @log_admin_action("review_policy_task") def review_task(tenant_id, task_id): """Review and approve/reject a policy review task.""" - # Check access + # Tenant membership is enforced by require_tenant_access; viewers stay read-blocked. if session.get("role") == "viewer": return "Access denied", 403 - if session.get("role") == "tenant_admin" and session.get("tenant_id") != tenant_id: - return "Access denied", 403 - with get_db_session() as db_session: if request.method == "POST": # Handle approval/rejection @@ -233,33 +225,43 @@ def review_task(tenant_id, task_id): notes = request.form.get("notes", "") try: - # Get the workflow step (tenant-scoped via Context join) - stmt = ( - select(WorkflowStep) - .join(Context, WorkflowStep.context_id == Context.context_id) - .filter(Context.tenant_id == tenant_id, WorkflowStep.step_id == task_id) - ) - step = db_session.scalars(stmt).first() + # Read AND mutate through the same repository: the tenant-scoping join and the + # policy_review type guard live in one place (get_policy_review_step) for both the + # POST and GET legs, so the mutation route can't drift from a hand-rolled read. + repo = WorkflowRepository(db_session, tenant_id) + step = repo.get_policy_review_step(task_id) if not step: return "Task not found", 404 - # Update status based on action + # Atomic terminal-safe transition via the shared conditional-UPDATE + # primitive — a concurrent cancel/terminal decision makes it return + # None → the review is refused (409) rather than overwriting. if action == "approve": - step.status = "completed" - step.response_data = {"approved": True, "notes": notes} + transitioned = repo.transition_if_nonterminal( + task_id, status="completed", response_data={"approved": True, "notes": notes} + ) elif action == "reject": - step.status = "failed" - step.response_data = {"approved": False, "notes": notes} + transitioned = repo.transition_if_nonterminal( + task_id, status="failed", response_data={"approved": False, "notes": notes} + ) + else: + # An unknown/missing action is a bad request, not a finalized-task conflict. + return "Invalid action", 400 + + if transitioned is None: + return "Task was already finalized (e.g. canceled) and cannot be reviewed", 409 db_session.commit() - # Log the action - audit_logger = AuditLogger() - audit_logger.log( - tenant_id=tenant_id, + # Log the action (AuditLogger requires adapter_name; the method is + # log_operation, not a nonexistent .log — the prior call 500'd the route). + reviewer = session_user_email(default="system") + AuditLogger(adapter_name="AdminUI", tenant_id=tenant_id).log_operation( operation="policy_review", - principal_id=session.get("user"), + principal_name=reviewer, + principal_id=reviewer, + adapter_id="AdminUI", success=True, details={"task_id": task_id, "action": action, "notes": notes}, ) @@ -272,12 +274,7 @@ def review_task(tenant_id, task_id): # GET request - show review form try: - stmt = ( - select(WorkflowStep) - .join(Context, WorkflowStep.context_id == Context.context_id) - .filter(Context.tenant_id == tenant_id, WorkflowStep.step_id == task_id) - ) - step = db_session.scalars(stmt).first() + step = WorkflowRepository(db_session, tenant_id).get_policy_review_step(task_id) if not step: return "Task not found", 404 diff --git a/src/admin/blueprints/workflows.py b/src/admin/blueprints/workflows.py index c3fcb874c0..9cb42593dd 100644 --- a/src/admin/blueprints/workflows.py +++ b/src/admin/blueprints/workflows.py @@ -2,18 +2,31 @@ import json import logging -from datetime import UTC, datetime +from typing import Any -from flask import Blueprint, flash, jsonify, redirect, render_template, request, session, url_for +from flask import Blueprint, Response, flash, jsonify, redirect, render_template, request, url_for from sqlalchemy import select - -from src.admin.utils import require_tenant_access +from sqlalchemy.orm import Session + +from src.admin.utils import echo_context, require_tenant_access, session_user_email +from src.admin.utils.approval import ( + APPROVED_MEDIA_BUY_EXECUTION_FAILURE_MESSAGE, + APPROVED_MEDIA_BUY_PENDING_RECONCILIATION_MESSAGE, + waiting_for_creatives_message, +) from src.admin.utils.audit_decorator import log_admin_action from src.core.database.database_session import get_db_session from src.core.database.models import Context from src.core.database.models import Principal as ModelPrincipal from src.core.database.repositories import MediaBuyRepository -from src.core.database.repositories.workflow import WorkflowRepository +from src.core.database.repositories.creative import CreativeAssignmentRepository, CreativeRepository +from src.core.database.repositories.workflow import APPROVABLE_STEP_STATUSES, WorkflowRepository +from src.core.logging_config import log_safe +from src.core.workflow_finalization import ( + ApprovalExecutionStatus, + execute_and_finalize_media_buy_approval, + prepare_media_buy_approval_execution, +) logger = logging.getLogger(__name__) @@ -36,8 +49,10 @@ def list_workflows(tenant_id, **kwargs): workflow_repo = WorkflowRepository(db, tenant_id) all_steps = workflow_repo.get_all_steps() - # Separate pending approval steps for summary - pending_steps = [s for s in all_steps if s.status == "pending_approval"] + # Separate pending approval steps for summary. Uses the canonical approvable set, not an + # inline literal: a subset literal here undercounts (it would drop ``requires_approval`` + # and the legacy ``approval`` alias) and drifts the moment the set changes. + pending_steps = [s for s in all_steps if s.status in APPROVABLE_STEP_STATUSES] # Get media buys for context media_buy_repo = MediaBuyRepository(db, tenant_id) @@ -149,28 +164,155 @@ def review_workflow_step(tenant_id, workflow_id, step_id): ) +def _refused_decision_response( + workflow_repo: WorkflowRepository, step_id: str, awaiting_desc: str +) -> tuple[Response, int]: + """Map a refused approval/rejection compare-and-set to the right HTTP error. + + ``claim_approval`` / ``reject_if_approvable`` return None for EITHER a step that does not + exist (404) OR one that exists but is no longer in an approvable status (409 Conflict — + e.g. already approved by a concurrent request, or canceled). Distinguish via a tenant-scoped + fetch so a genuine concurrency conflict returns 409, not a misleading 404. + """ + existing = workflow_repo.get_by_step_id(step_id) + if existing is None: + return jsonify({"error": "Workflow step not found"}), 404 + return jsonify({"error": f"Workflow step is not {awaiting_desc} (status: {existing.status})"}), 409 + + +def _complete_plain_workflow_approval(db: Session, tenant_id: str, step_id: str) -> tuple[Response, int]: + """Complete a no-execution approval in the claim's original transaction.""" + completed = WorkflowRepository(db, tenant_id).complete_claimed_approval(step_id) + if completed is None: + db.rollback() + logger.error( + "[APPROVAL] Claimed workflow step %s could not be completed atomically", + log_safe(step_id), + ) + return jsonify({"success": False, "error": "Workflow result could not be finalized"}), 503 + db.commit() + flash("Workflow step approved successfully", "success") + return jsonify({"success": True}), 200 + + +def _approve_mapped_media_buy( + *, + db: Session, + tenant_id: str, + step_id: str, + media_buy_id: str, + request_data: dict[str, Any], + user_email: str, +) -> tuple[Response, int]: + """Handle the media-buy-specific portion of a claimed workflow approval.""" + media_buy_repo = MediaBuyRepository(db, tenant_id) + media_buy = media_buy_repo.get_by_id(media_buy_id) + logger.info( + "[APPROVAL] Media buy lookup: found=%s, status=%s", + media_buy is not None, + media_buy.status if media_buy else "N/A", + ) + # No status pre-filter here on purpose: prepare_media_buy_approval_execution owns the + # whole eligibility decision and reports NOT_EXECUTABLE below. The literal that used + # to sit here recognised only ``pending_approval``, so a pending_creatives or draft + # buy took the plain-workflow path — step terminalized, buy never executed, creative + # gate and execution claim both skipped. + preparation = prepare_media_buy_approval_execution( + media_buys=media_buy_repo, + assignments=CreativeAssignmentRepository(db, tenant_id), + creatives=CreativeRepository(db, tenant_id), + media_buy_id=media_buy_id, + approved_by=user_email, + ) + if preparation.status is ApprovalExecutionStatus.NOT_EXECUTABLE: + logger.warning( + "[APPROVAL] Media buy not executable: media_buy=%s, status=%s", + media_buy is not None, + media_buy.status if media_buy else "N/A", + ) + return _complete_plain_workflow_approval(db, tenant_id, step_id) + if preparation.status is ApprovalExecutionStatus.WAITING_FOR_CREATIVES: + blocking_count = len(preparation.blocking_creative_ids) + logger.warning( + "[APPROVAL] Cannot execute adapter creation yet - %s creatives not approved: %s", + blocking_count, + log_safe(preparation.blocking_creative_ids), + ) + flash(waiting_for_creatives_message(blocking_count), "info") + db.commit() + return jsonify({"success": True}), 200 + if preparation.status is ApprovalExecutionStatus.CLAIM_REFUSED: + db.rollback() + return jsonify({"success": False, "error": "Media buy is already executing or no longer pending"}), 409 + + db.commit() + outcome = execute_and_finalize_media_buy_approval( + tenant_id=tenant_id, + media_buy_id=media_buy_id, + step_id=step_id, + context=echo_context(request_data), + ) + if outcome.status is ApprovalExecutionStatus.PENDING_RECONCILIATION: + logger.error( + "[APPROVAL] External media buy creation succeeded but activation remains pending for %s", + log_safe(media_buy_id), + ) + flash(APPROVED_MEDIA_BUY_PENDING_RECONCILIATION_MESSAGE, "warning") + return ( + jsonify({"success": False, "error": APPROVED_MEDIA_BUY_PENDING_RECONCILIATION_MESSAGE, "pending": True}), + 503, + ) + if outcome.status is ApprovalExecutionStatus.FAILED: + logger.error( + "[APPROVAL] Adapter creation failed for %s: %s", + log_safe(media_buy_id), + log_safe(outcome.error_message), + ) + flash(APPROVED_MEDIA_BUY_EXECUTION_FAILURE_MESSAGE, "error") + return jsonify({"success": False, "error": APPROVED_MEDIA_BUY_EXECUTION_FAILURE_MESSAGE}), 500 + if outcome.status is ApprovalExecutionStatus.FINALIZATION_FAILED: + logger.error( + "[APPROVAL] Adapter outcome for workflow step %s could not be finalized", + log_safe(step_id), + ) + return jsonify({"success": False, "error": "Workflow result could not be finalized"}), 500 + + logger.info("[APPROVAL] Media buy %s successfully created in adapter", log_safe(media_buy_id)) + flash("Workflow step approved and media buy created successfully", "success") + return jsonify({"success": True}), 200 + + @workflows_bp.route("//workflows//steps//approve", methods=["POST"]) @require_tenant_access() @log_admin_action("approve_workflow_step") def approve_workflow_step(tenant_id, workflow_id, step_id): - """Approve a workflow step.""" + """Approve a workflow step. + + ``workflow_id`` is a cosmetic path segment only: WorkflowStep has no workflow_id + column and the value is never populated (an unwired stub — see the TODO at + mcp_context_wrapper). The step is a tenant-scoped primary key, so authorization is + complete at (tenant, step_id); there is nothing to scope against the URL's workflow. + Wiring a real workflow grouping (and validating the step against it) is separate work. + """ + del workflow_id # cosmetic; see docstring try: with get_db_session() as db: # Get and update the workflow step via repository (tenant-scoped) workflow_repo = WorkflowRepository(db, tenant_id) - user_info = session.get("user", {}) - user_email = user_info.get("email", "system") if isinstance(user_info, dict) else str(user_info) + user_email = session_user_email(default="system") - step = workflow_repo.update_status( - step_id, - status="approved", - ) + # Atomic compare-and-set: requires_approval/pending_approval → approved. Because + # ``approved`` is non-terminal, a broad terminal-guard would let a second concurrent + # approver win an approved→approved no-op and ALSO run execute_approved_media_buy + # below (duplicate adapter work). claim_approval admits exactly one approver; a + # loser gets None → 409 Conflict (not 404) and does NOT execute. + step = workflow_repo.claim_approval(step_id) if not step: - return jsonify({"error": "Workflow step not found"}), 404 + return _refused_decision_response(workflow_repo, step_id, "awaiting approval") - db.commit() + request_data = dict(step.request_data) if isinstance(step.request_data, dict) else {} # Check if this is a media buy creation workflow step mappings = workflow_repo.get_mappings_for_step(step_id) @@ -187,73 +329,15 @@ def approve_workflow_step(tenant_id, workflow_id, step_id): if mapping: media_buy_id = mapping.object_id logger.info(f"[APPROVAL] Workflow step {step_id} approved for media buy {media_buy_id}") - - # Get the media buy - media_buy_repo = MediaBuyRepository(db, tenant_id) - media_buy = media_buy_repo.get_by_id(media_buy_id) - - logger.info( - f"[APPROVAL] Media buy lookup: found={media_buy is not None}, status={media_buy.status if media_buy else 'N/A'}" + return _approve_mapped_media_buy( + db=db, + tenant_id=tenant_id, + step_id=step_id, + media_buy_id=media_buy_id, + request_data=request_data, + user_email=user_email, ) - - if media_buy and media_buy.status == "pending_approval": - # Check if all required creatives are approved before executing adapter creation - from src.core.database.models import Creative as CreativeModel - from src.core.database.models import CreativeAssignment - - stmt_assignments = select(CreativeAssignment).filter_by(media_buy_id=media_buy_id) - assignments = db.scalars(stmt_assignments).all() - - if assignments: - creative_ids = [a.creative_id for a in assignments] - stmt_creatives = select(CreativeModel).filter(CreativeModel.creative_id.in_(creative_ids)) - creatives = db.scalars(stmt_creatives).all() - - unapproved_creatives = [ - c.creative_id for c in creatives if c.status not in ["approved", "active"] - ] - - if unapproved_creatives: - logger.warning( - f"[APPROVAL] Cannot execute adapter creation yet - " - f"{len(unapproved_creatives)} creatives not approved: {unapproved_creatives}" - ) - flash( - f"Media buy approved! Waiting for {len(unapproved_creatives)} creative(s) to be approved before creating in GAM.", - "info", - ) - media_buy.status = "pending_creatives" - db.commit() - return jsonify({"success": True}), 200 - - # Execute adapter creation - from src.core.tools.media_buy_create import execute_approved_media_buy - - logger.info(f"[APPROVAL] Executing adapter creation for approved media buy {media_buy_id}") - success, error_msg = execute_approved_media_buy(media_buy_id, tenant_id) - - if not success: - logger.error(f"[APPROVAL] Adapter creation failed for {media_buy_id}: {error_msg}") - flash(f"Workflow approved but media buy creation failed: {error_msg}", "error") - return jsonify({"success": False, "error": error_msg}), 500 - - # Update media buy status - media_buy.status = "scheduled" - media_buy.approved_at = datetime.now(UTC) - media_buy.approved_by = user_email - db.commit() - - logger.info(f"[APPROVAL] Media buy {media_buy_id} successfully created in adapter") - flash("Workflow step approved and media buy created successfully", "success") - else: - logger.warning( - f"[APPROVAL] Media buy not executed: media_buy={media_buy is not None}, status={media_buy.status if media_buy else 'N/A'}" - ) - flash("Workflow step approved successfully", "success") - else: - flash("Workflow step approved successfully", "success") - - return jsonify({"success": True}), 200 + return _complete_plain_workflow_approval(db, tenant_id, step_id) except Exception as e: logger.error(f"Error approving workflow step {step_id}: {e}", exc_info=True) @@ -264,7 +348,12 @@ def approve_workflow_step(tenant_id, workflow_id, step_id): @require_tenant_access() @log_admin_action("reject_workflow_step") def reject_workflow_step(tenant_id, workflow_id, step_id): - """Reject a workflow step with a reason.""" + """Reject a workflow step with a reason. + + ``workflow_id`` is a cosmetic path segment only (see ``approve_workflow_step``): no + backing column, never populated; authorization is complete at (tenant, step_id). + """ + del workflow_id # cosmetic; see approve_workflow_step try: data = request.get_json() or {} reason = data.get("reason", "No reason provided") @@ -273,17 +362,16 @@ def reject_workflow_step(tenant_id, workflow_id, step_id): # Get and update the workflow step via repository (tenant-scoped) workflow_repo = WorkflowRepository(db, tenant_id) - user_info = session.get("user", {}) - user_email = user_info.get("email", "system") if isinstance(user_info, dict) else str(user_info) + user_email = session_user_email(default="system") - step = workflow_repo.update_status( - step_id, - status="rejected", - error_message=reason, - ) + # Atomic compare-and-set with the SAME source-state guard as approve: a step that + # has already been approved (execution underway) cannot be rejected — that would + # strand a live ad-server order behind a rejected workflow. A loser gets None → + # 409 Conflict (not 404). + step = workflow_repo.reject_if_approvable(step_id, error_message=reason) if not step: - return jsonify({"error": "Workflow step not found"}), 404 + return _refused_decision_response(workflow_repo, step_id, "awaiting a decision") db.commit() diff --git a/src/admin/utils/__init__.py b/src/admin/utils/__init__.py index 788f24b8d6..d1d3ba3857 100644 --- a/src/admin/utils/__init__.py +++ b/src/admin/utils/__init__.py @@ -16,6 +16,7 @@ parse_json_config, require_auth, require_tenant_access, + session_user_email, translate_custom_targeting, validate_gam_network_response, validate_gam_user_response, @@ -30,6 +31,7 @@ "is_tenant_admin", "require_auth", "require_tenant_access", + "session_user_email", # Utility functions "parse_json_config", "get_tenant_config_from_db", diff --git a/src/admin/utils/approval.py b/src/admin/utils/approval.py new file mode 100644 index 0000000000..f5d763fd74 --- /dev/null +++ b/src/admin/utils/approval.py @@ -0,0 +1,37 @@ +"""Shared buyer-safe messages for admin approval outcomes.""" + +APPROVED_MEDIA_BUY_EXECUTION_FAILURE_MESSAGE = ( + "Workflow approved, but media buy creation failed. Review server logs before retrying." +) + +APPROVED_MEDIA_BUY_PENDING_RECONCILIATION_MESSAGE = ( + "Media buy was created externally, but activation could not be finalized. " + "The workflow remains pending for safe reconciliation." +) + + +def waiting_for_creatives_message(blocking_count: int) -> str: + """The one operator-facing message for an approved media buy still blocked on creatives. + + Both admin approve routes reach this from the SAME + ``ApprovalExecutionStatus.WAITING_FOR_CREATIVES`` returned by + ``prepare_media_buy_approval_execution``, so the wording gets one home rather than one + per route. The text is adapter-agnostic on purpose: this fires for whichever ad server + the tenant is configured with, not only GAM. + + ``blocking_count == 0`` is a DIFFERENT operator situation, not a degenerate case of the + same one. ``_approval_creative_gate`` returns ``(False, ())`` when the buy has no + creative assignments at all — the gate is unsatisfied precisely BECAUSE nothing is + assigned — so a single count-interpolated sentence renders as "Waiting for 0 + creative(s) to be approved", which tells the operator to wait for an empty set. The + two cases need opposite actions: assign creatives, versus wait for the assigned ones + to clear review. + """ + if blocking_count == 0: + return ( + "Media buy approved! No creatives are assigned yet — assign and approve at least one " + "before it can be created in the ad server." + ) + return ( + f"Media buy approved! Waiting for {blocking_count} creative(s) to be approved before creating in the ad server." + ) diff --git a/src/admin/utils/audit_decorator.py b/src/admin/utils/audit_decorator.py index 19426e4dfe..790b83c9f3 100644 --- a/src/admin/utils/audit_decorator.py +++ b/src/admin/utils/audit_decorator.py @@ -15,7 +15,7 @@ from functools import wraps from typing import Any -from flask import g, request, session +from flask import g, request logger = logging.getLogger(__name__) @@ -166,11 +166,9 @@ def decorator(f: Callable[..., Any]) -> Callable[..., Any]: @wraps(f) def decorated_function(*args: Any, **kwargs: Any) -> Any: # Get user from session - user_info = session.get("user", {}) - if isinstance(user_info, dict): - user_email: str = user_info.get("email", "unknown") - else: - user_email = str(user_info) if user_info else "unknown" + from src.admin.utils.helpers import session_user_email + + user_email: str = session_user_email() # Get tenant_id from kwargs (most admin routes have this) tenant_id: str | None = kwargs.get("tenant_id") diff --git a/src/admin/utils/helpers.py b/src/admin/utils/helpers.py index 325c2ae646..f1a8ed620d 100644 --- a/src/admin/utils/helpers.py +++ b/src/admin/utils/helpers.py @@ -137,6 +137,23 @@ def get_tenant_config_from_db(tenant_id): return {} +def session_user_email(default: str = "unknown") -> str: + """The acting user's email from the Flask session, for audit attribution. + + ``session["user"]`` is a dict under OAuth login and a bare string under the test/password + path, so every caller needs the same isinstance split. Keeping it in one place stops an + audit row from recording a dict repr (``{'email': ...}``) instead of an email — a lossy + attribution that is invisible until someone reads the audit log. + + ``default`` is the caller's placeholder for an absent/blank session user (routes that log + an operator action use ``"system"``; generic audit decorators use ``"unknown"``). + """ + user_info = session.get("user") + if isinstance(user_info, dict): + return user_info.get("email") or default + return str(user_info) if user_info else default + + def is_super_admin(email): """Check if user is a super admin based on email or domain. @@ -585,7 +602,7 @@ def echo_context(request_data: dict) -> ContextObject | None: extra=allow passthrough and the dict was already validated at request time. Returns ``None`` when no context was stored (absent/None/non-dict), so ``exclude_none`` keeps the field off the wire. Shared by the media-buy - approve and creative approval webhook paths (PR #1567 round-3 DRY). + approve and creative approval webhook paths. """ context_data = request_data.get("context") if context_data and isinstance(context_data, dict): diff --git a/src/app.py b/src/app.py index 2b29c03ef4..732456979e 100644 --- a/src/app.py +++ b/src/app.py @@ -37,18 +37,25 @@ from src.core.exceptions import ( INVALID_REQUEST_SUGGESTION, VALIDATION_ERROR_SUGGESTION, + AdCPAuthenticationError, AdCPError, AdCPInvalidRequestError, AdCPValidationError, build_two_layer_error_envelope, build_validation_error_details, - normalize_to_adcp_error, + safe_adcp_error, + safe_validation_error_message, + validation_error_field, ) from src.core.http_utils import get_header_case_insensitive as _get_header_case_insensitive from src.core.lifecycle import run_all_shutdown_callbacks from src.core.main import mcp from src.core.resolved_identity import resolve_identity -from src.core.tool_error_logging import handle_tool_error, record_boundary_error +from src.core.tool_error_logging import ( + best_effort_boundary_identity, + handle_tool_error, + record_boundary_error, +) from src.landing import generate_tenant_landing_page from src.landing.landing_page import generate_fallback_landing_page from src.routes.api_v1 import router as api_v1_router @@ -130,9 +137,21 @@ async def app_lifespan(app: FastAPI): # --------------------------------------------------------------------------- -def _envelope_response(request: Request, exc: AdCPError) -> JSONResponse: +def _envelope_response(request: Request, exc: AdCPError, *, original: Exception) -> JSONResponse: """Build a JSONResponse carrying the two-layer envelope for ``exc``. + ``exc`` is the WIRE error — already sanitized, and the sole source of the response + body and HTTP status. ``original`` is the exception as raised, and exists only for the + privileged server log: ``record_boundary_error`` branches on ``isinstance(error, + AdCPError)`` to pick log severity, so handing it the sanitized twin made every REST + failure — including a genuine untyped crash — log at WARNING with no traceback and the + scrubbed message. MCP and A2A both pass the original, so REST was the one boundary that + dropped the diagnostic. Tenant-visible sinks are unaffected: ``record_boundary_error`` + re-derives ``safe_adcp_error`` internally for the activity feed and audit log. + + ``original`` is keyword-only and required so a new handler cannot silently regress to + the sanitized-twin behaviour by omitting it. + Single source of truth for the REST envelope-response shape — used by every exception handler so HTTP status, body envelope, wire codes, and observability (logger + activity feed + audit log) are constructed @@ -141,15 +160,21 @@ def _envelope_response(request: Request, exc: AdCPError) -> JSONResponse: Symmetric with the MCP and A2A boundaries: all three transports delegate to ``record_boundary_error`` so log severity, activity-feed publishing, and audit logging stay in lockstep. Identity is not resolved on - ``request.state`` at the exception-handler boundary, so we resolve it - best-effort here (auth token + tenant headers) to populate the - tenant-scoped sinks (activity feed, audit log) for REST errors the same - way MCP and A2A do. Identity resolution never raises into the error path — - a lookup miss degrades to anonymous and ``record_boundary_error`` falls - back to the WARNING log line carrying the error code, message, and path. + ``request.state`` at the exception-handler boundary, so we recover scope + best-effort here to populate the tenant-scoped sinks (activity feed, audit + log) for REST errors the same way MCP and A2A do. Authentication errors + remain unscoped: client-controlled routing headers do not attest tenant + ownership, and rejected credentials cannot supply a trusted principal. + Other errors may reuse a fully authenticated identity, but tenant routing + hints alone never scope a sink write. Scope lookup never raises into the + error path — a miss degrades to anonymous and + ``record_boundary_error`` falls back to the server log. """ - tenant_id, principal_id = _best_effort_rest_identity(request) - record_boundary_error("rest", request.url.path, exc, tenant_id=tenant_id, principal_id=principal_id) + if isinstance(exc, AdCPAuthenticationError): + tenant_id, principal_id = None, None + else: + tenant_id, principal_id = _best_effort_rest_identity(request) + record_boundary_error("rest", request.url.path, original, tenant_id=tenant_id, principal_id=principal_id) return JSONResponse( status_code=exc.status_code, content=build_two_layer_error_envelope(exc), @@ -161,17 +186,15 @@ def _best_effort_rest_identity(request: Request) -> tuple[str | None, str | None Used solely to scope the activity-feed and audit-log sinks in ``record_boundary_error`` — never to make an authorization decision. - ``require_valid_token=False`` so an invalid/expired token (which may be - the very error being handled) still yields a tenant from the host headers - instead of raising. Any failure degrades to ``(None, None)``; observability - must not shadow the buyer's original error. + ``require_valid_token=False`` avoids replacing the original response while + the shared helper requires a resolved principal before trusting tenant + scope. Any failure or anonymous identity degrades to ``(None, None)``; + observability must not shadow the buyer's original error. """ - try: - identity = resolve_identity(dict(request.headers), protocol="rest", require_valid_token=False) - return identity.tenant_id, identity.principal_id - except Exception: - logger.debug("REST boundary: best-effort identity resolution failed", exc_info=True) - return None, None + return best_effort_boundary_identity( + lambda: resolve_identity(dict(request.headers), protocol="rest", require_valid_token=False), + transport="rest", + ) @app.exception_handler(AdCPError) @@ -193,7 +216,7 @@ async def adcp_error_handler(request: Request, exc: AdCPError) -> JSONResponse: in ``_envelope_response`` so all three handlers leave a uniform breadcrumb. """ - return _envelope_response(request, exc) + return _envelope_response(request, safe_adcp_error(exc), original=exc) @app.exception_handler(ValueError) @@ -209,7 +232,7 @@ async def value_error_handler(request: Request, exc: ValueError) -> JSONResponse Does NOT catch FastAPI's ``RequestValidationError`` (separate class, not a ValueError subclass) — that has its own handler below. """ - return _envelope_response(request, normalize_to_adcp_error(exc)) + return _envelope_response(request, safe_adcp_error(exc), original=exc) @app.exception_handler(RequestValidationError) @@ -234,10 +257,15 @@ async def request_validation_error_handler(request: Request, exc: RequestValidat # location prefix); join the rest into the JSONPath-lite ``field`` the envelope # already uses (e.g. attribution_window.post_click.interval). Stripping at any # position would erase a body field literally named "query"/"body"/"path". - raw_loc = [str(p) for p in first.get("loc", ())] - loc = raw_loc[1:] if raw_loc and raw_loc[0] in ("body", "query", "path") else raw_loc - field = ".".join(loc) or None - message = first.get("msg") or "Request failed schema validation" + projected_errors = [] + for error in errors: + projected = dict(error) + raw_loc = list(error.get("loc", ())) + projected["loc"] = raw_loc[1:] if raw_loc and raw_loc[0] in ("body", "query", "path") else raw_loc + projected_errors.append(projected) + first = projected_errors[0] if projected_errors else {} + field = validation_error_field(first) + message = safe_validation_error_message(first) if first else "Request failed schema validation" # Code selection by failure semantics, grounded in the AdCP graded # error-compliance storyboard: a VALUE/enum/range violation on a # structurally-valid field is canonically VALIDATION_ERROR; a missing/ @@ -253,9 +281,10 @@ async def request_validation_error_handler(request: Request, exc: RequestValidat message, field=field, suggestion=suggestion, - details=build_validation_error_details(errors), + details=build_validation_error_details(projected_errors), + _wire_safe_message=True, ) - return _envelope_response(request, adcp_exc) + return _envelope_response(request, adcp_exc, original=exc) @app.exception_handler(PermissionError) @@ -268,7 +297,7 @@ async def permission_error_handler(request: Request, exc: PermissionError) -> JS error instead of the 403 authorization envelope every transport should emit for the same condition. """ - return _envelope_response(request, normalize_to_adcp_error(exc)) + return _envelope_response(request, safe_adcp_error(exc), original=exc) @app.exception_handler(ToolError) @@ -288,6 +317,17 @@ async def tool_error_handler(request: Request, exc: ToolError) -> JSONResponse: return handle_tool_error(exc) +@app.exception_handler(Exception) +async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONResponse: + """Keep unexpected REST failures on the same sanitized AdCP wire contract. + + No ``logger.exception`` here: passing ``original`` makes ``record_boundary_error`` + take its untyped branch (ERROR + ``exc_info=True``), so the boundary emits exactly one + traceback instead of two. + """ + return _envelope_response(request, safe_adcp_error(exc), original=exc) + + # --------------------------------------------------------------------------- # A2A Integration — add routes directly to the FastAPI app (not as sub-app) # so middleware and scope["state"] propagate correctly within the same ASGI app. diff --git a/src/core/auth_context.py b/src/core/auth_context.py index af7a653c76..64a6d2f371 100644 --- a/src/core/auth_context.py +++ b/src/core/auth_context.py @@ -97,18 +97,19 @@ def _resolve_auth_dep(auth_ctx: AuthContext = get_auth_context) -> "ResolvedIden def _require_auth_dep(auth_ctx: AuthContext = get_auth_context) -> "ResolvedIdentity": - """FastAPI dependency: resolve identity (auth-required, raises 401 if missing). + """FastAPI dependency: resolve identity (auth-required, raises 401 if rejected). - Returns ResolvedIdentity on success. Raises AdCPAuthRequiredError if - no token is present or the token is invalid. The error carries the shared - AUTH_REQUIRED suggestion so the REST 401 envelope tells the buyer how to - recover (parity with require_identity on the _impl path; AdCP POST-F3). + Returns ResolvedIdentity on success. AdCP 3.1.1 requires the REST wire to + distinguish absent credentials (AUTH_MISSING) from rejected credentials + (AUTH_INVALID). """ - from src.core.auth import AUTH_REQUIRED_SUGGESTION - from src.core.exceptions import AdCPAuthRequiredError + from src.core.exceptions import AdCPAuthInvalidError, classify_auth_credentials_error if not auth_ctx.auth_token: - raise AdCPAuthRequiredError("Authentication required", suggestion=AUTH_REQUIRED_SUGGESTION) + raise classify_auth_credentials_error( + auth_ctx.headers, + missing_message="Authentication required", + ) from src.core.resolved_identity import resolve_identity @@ -120,7 +121,7 @@ def _require_auth_dep(auth_ctx: AuthContext = get_auth_context) -> "ResolvedIden ) if not identity.principal_id: - raise AdCPAuthRequiredError("Authentication required", suggestion=AUTH_REQUIRED_SUGGESTION) + raise AdCPAuthInvalidError("Authentication credentials were rejected.") # Set tenant ContextVar at the REST transport boundary if identity.tenant: diff --git a/src/core/auth_policy.py b/src/core/auth_policy.py new file mode 100644 index 0000000000..22f4889871 --- /dev/null +++ b/src/core/auth_policy.py @@ -0,0 +1,46 @@ +"""Transport-neutral authentication policy for AdCP skills.""" + +from __future__ import annotations + +# The sole list of skills safe to invoke without a resolved principal. +# Every transport imports this exact immutable object so an auth-policy change +# cannot expose or reject a skill on only one boundary. +# +# Membership is unchanged from the per-transport lists this replaced — +# consolidation, not re-policy. +# +# Grounded against the pinned 3.1.1 spec PER ENTRY, because the four do not in +# fact share one justification: +# +# get_adcp_capabilities / get_products / list_creative_formats +# building/by-layer/L2/authentication.mdx "Public Operations (No +# Authentication Required)" names exactly these three — the only +# positively-stated public set in the spec. get_products appears in BOTH +# lists: public with a partial catalog, authenticated for full access. +# +# list_authorized_properties +# NOT spec-grounded, and deliberately kept anyway. The spec REMOVED this v2 +# task in v3: its sole mention across the 3.1.1 docs is the migration note +# in protocol/get_adcp_capabilities.mdx ("removed in v3"; its fields moved +# under media_buy.portfolio). It is here because both transports already +# treated it as public before this list existed, and revoking a surface +# buyers may still call belongs with the v2-compat sunset, not with an +# error-boundary change. +# +# list_accounts is EXCLUDED on positive spec text, not on absence from a list: +# accounts/tasks/list_accounts.mdx opens "Returns all accounts the AUTHENTICATED +# agent can operate on this vendor agent", and protocol/required-tasks.mdx marks +# it Conditional for account-id namespaces with "require_operator_auth: true". +# Per BR-RULE-055 (docs/test-obligations/business-rules.md). +# +# Absence from "Public Operations" is NOT itself an argument for exclusion: that +# list omits most operations — including list_authorized_properties above — so +# reading it as a closed prohibition would contradict this very set. +AUTH_OPTIONAL_SKILLS = frozenset( + { + "get_adcp_capabilities", + "get_products", + "list_creative_formats", + "list_authorized_properties", + } +) diff --git a/src/core/context_manager.py b/src/core/context_manager.py index 12f3b1c4c5..415a09aee1 100644 --- a/src/core/context_manager.py +++ b/src/core/context_manager.py @@ -20,8 +20,15 @@ from src.core.database.database_session import DatabaseManager from src.core.database.models import Context, ObjectWorkflowMapping, WorkflowStep from src.core.database.models import Context as DBContext -from src.core.exceptions import AdCPError, build_two_layer_error_envelope, normalize_to_adcp_error +from src.core.database.repositories.workflow import WorkflowRepository + +# NOT AdCPError/normalize_to_adcp_error (which #1697 imports here): this branch's +# audit_workflow_step_failure passes the ORIGINAL exception to safe_adcp_error +# instead — pre-wrapping with normalize_to_adcp_error is the webhook secret-leak +# this PR fixed, so those two names are unused here by design. +from src.core.exceptions import build_two_layer_error_envelope, safe_adcp_error from src.core.webhook_validator import ( + resolve_webhook_task_id, validate_webhook_task_type, webhook_url_for_log, ) @@ -299,73 +306,74 @@ def update_workflow_step( response_data = response_data.model_dump(mode="json") session = self.session try: - stmt = select(WorkflowStep).filter_by(step_id=step_id) - if tenant_id: - stmt = stmt.join(DBContext).where(DBContext.tenant_id == tenant_id) - - step = session.scalars(stmt).first() - if step: - old_status = step.status # Capture old status before changing - - if status: - step.status = status - if status in ["completed", "failed"] and not step.completed_at: - step.completed_at = datetime.now(UTC) - + # Resolve the tenant scope the repository primitive needs. Most callers + # pass it; when absent, the repository derives it from the step's context + # (data access stays in the repository — no raw query here). + scoped_tenant = tenant_id or WorkflowRepository.resolve_tenant_for_step(session, step_id) + if scoped_tenant is None: + return # step (or its context) not found + repo = WorkflowRepository(session, scoped_tenant) + + if status: + # ATOMIC terminal-safe status write via the SHARED conditional-UPDATE + # primitive (WHERE status NOT IN terminal). This closes the cancellation + # TOCTOU even when update_workflow_step runs concurrently with a buyer + # cancel — e.g. MockAdServer._schedule_async_completion() fires this from + # a delayed background thread. A refused transition (None) means the step + # was concurrently terminalized (canceled) or is gone: apply NOTHING and + # send NO webhook, so we never report a completion that lost the race. + completed_at = datetime.now(UTC) if status in ("completed", "failed") else None + step = repo.transition_if_nonterminal( + step_id, + status=status, + completed_at=completed_at, + response_data=response_data, + error_message=error_message, + ) + if step is None: + console.print( + f"[yellow]⚠️ Status change to '{status}' refused for step {step_id} " + f"(already terminal or not found) — no webhook[/yellow]" + ) + return + if transaction_details is not None: + step.transaction_details = transaction_details + self._apply_comment(step, add_comment) + session.commit() + # Webhook fires ONLY because the status transition actually applied. + self._send_push_notifications(step, status, session) + else: + # No status change → plain field update; no terminal concern, no webhook + # (webhooks fire on status changes only, matching prior behavior). + step = repo.get_by_step_id(step_id) + if step is None: + return if response_data is not None: step.response_data = response_data if error_message is not None: step.error_message = error_message if transaction_details is not None: step.transaction_details = transaction_details - - if add_comment: - # Ensure comments is a list - if not isinstance(step.comments, list): - step.comments = [] - # Create a new list to trigger SQLAlchemy change detection - new_comments = list(step.comments) - new_comments.append( - { - "user": add_comment.get("user", "system"), - "timestamp": datetime.now(UTC).isoformat(), - "text": add_comment.get("text", add_comment.get("comment", "")), - } - ) - step.comments = new_comments - - # DEBUG: Log the condition check values BEFORE commit - console.print("[magenta]🔍 PRE-COMMIT WEBHOOK DEBUG:[/magenta]") - console.print("[magenta] update_workflow_step called with:[/magenta]") - console.print(f"[magenta] step_id={step_id}[/magenta]") - console.print(f"[magenta] status parameter={status}[/magenta]") - console.print("[magenta] Database state BEFORE commit:[/magenta]") - console.print(f"[magenta] old_status={old_status}[/magenta]") - console.print(f"[magenta] new step.status={step.status}[/magenta]") - console.print("[magenta] Condition evaluation:[/magenta]") - console.print(f"[magenta] status parameter truthy? {bool(status)}[/magenta]") - console.print(f"[magenta] step object exists? {step is not None}[/magenta]") - console.print(f"[magenta] Will trigger webhook? {status and step}[/magenta]") - + self._apply_comment(step, add_comment) session.commit() - console.print(f"[green]✅ Updated workflow step {step_id} (committed to database)[/green]") - - # DEBUG: Log the condition check values AFTER commit - console.print("[yellow]🔍 POST-COMMIT WEBHOOK DEBUG:[/yellow]") - console.print(f"[yellow] status={status}[/yellow]") - console.print(f"[yellow] old_status={old_status}[/yellow]") - console.print(f"[yellow] step exists={step is not None}[/yellow]") - console.print(f"[yellow] Webhook trigger condition (status and step): {status and step}[/yellow]") - - # Send push notifications if status changed - if status and step: - console.print(f"[blue]🚀 WEBHOOK: Calling _send_push_notifications for step {step_id}[/blue]") - self._send_push_notifications(step, status, session) - else: - console.print(f"[yellow]⚠️ WEBHOOK SKIPPED: status={status}, step={step is not None}[/yellow]") finally: session.close() + @staticmethod + def _apply_comment(step: WorkflowStep, add_comment: dict[str, str] | None) -> None: + """Append a comment to a step's comments list (new list → change detection).""" + if not add_comment: + return + comments = list(step.comments) if isinstance(step.comments, list) else [] + comments.append( + { + "user": add_comment.get("user", "system"), + "timestamp": datetime.now(UTC).isoformat(), + "text": add_comment.get("text", add_comment.get("comment", "")), + } + ) + step.comments = comments + def audit_workflow_step_failure(self, step_id: str, exc: Exception) -> None: """Mark a workflow step failed with the spec two-layer envelope as ``response_data``. @@ -376,38 +384,23 @@ def audit_workflow_step_failure(self, step_id: str, exc: Exception) -> None: (``adcp_error`` + ``errors[]``) via ``build_two_layer_error_envelope`` so async and sync paths see the same wire shape. - Untyped exceptions are normalized to ``AdCPError`` via - ``normalize_to_adcp_error``. Wire-code enforcement ensures webhook - subscribers only see codes in ``WIRE_STANDARD_CODES``. + The shared ``safe_adcp_error`` policy (``src/core/exceptions.py``) does the whole job and + must receive the ORIGINAL exception: it scrubs the message for internal/infra errors (the + SERVICE_UNAVAILABLE family + terminal CONFIGURATION_ERROR) AND for every UNTYPED exception + (``ValueError``, ``PermissionError``, adapter ``RuntimeError``…), so a raw interpolated + ``str(exc)`` — e.g. a connection string — never reaches the buyer's webhook; it coerces any + non-standard code to ``SERVICE_UNAVAILABLE`` and passes only TYPED client-correctable + ``AdCPError`` subclasses through with their buyer-facing message intact. Do NOT pre-wrap + with ``normalize_to_adcp_error`` — that would map an untyped ``ValueError`` to a *trusted* + ``AdCPValidationError`` whose raw message (the secret) then passes through the scrub. This + is the async twin of the synchronous re-raise scrub; both share one definition. Wraps the ``update_workflow_step`` call in ``try/except`` so a DB hiccup during audit doesn't replace the original exception that the caller is about to re-raise. """ - from src.core.exceptions import WIRE_STANDARD_CODES - try: - source = normalize_to_adcp_error(exc) - - # Defensive wire-code enforcement: webhook subscribers must only - # see codes in ``WIRE_STANDARD_CODES``. If the wire code falls - # outside the standard set, override with SERVICE_UNAVAILABLE - # so async subscribers never receive an internal-only code. - # Structured fields (details/field/suggestion/context) carry - # forward so buyer agents and webhook subscribers retain - # machine-actionable correction context across the rewrite. - wire_code = source.wire_error_code - if wire_code not in WIRE_STANDARD_CODES: - source = AdCPError.synthesize( - source.message or str(source), - error_code="SERVICE_UNAVAILABLE", - recovery="terminal", - details=source.details, - field=source.field, - suggestion=source.suggestion, - context=source.context, - ) - + source = safe_adcp_error(exc) response_data = build_two_layer_error_envelope(source) error_message = source.message or str(source) @@ -796,7 +789,12 @@ def _send_push_notifications(self, step: WorkflowStep, new_status: str, session: from src.core.database.models import PushNotificationConfig # Get object mappings for this step - stmt = select(ObjectWorkflowMapping).filter_by(step_id=step.step_id) + # Deterministic order: ``mappings[0]`` below picks ONE mapping, so an + # unordered select makes which one arbitrary. Same order_by as the + # sibling ObjectWorkflowMapping select above. + stmt = ( + select(ObjectWorkflowMapping).filter_by(step_id=step.step_id).order_by(ObjectWorkflowMapping.created_at) + ) mappings = session.scalars(stmt).all() if not mappings: @@ -825,132 +823,148 @@ def _send_push_notifications(self, step: WorkflowStep, new_status: str, session: console.print(f"[cyan]🔍 Found {len(webhooks)} active webhook configs for principal {principal_id}[/cyan]") - # Send notifications for each mapping (media buy, creative, etc.) - for mapping in mappings: - console.print( - f"[cyan]📦 Processing mapping: {mapping.object_type} {mapping.object_id} action={mapping.action}[/cyan]" - ) + # ONE webhook per step status change. The payload depends only on + # (step, new_status): the delivery URL comes from the step's own + # ``request_data.push_notification_config``, so ``mappings`` and + # ``webhooks`` are opt-in gates, not per-item delivery targets. + # Looping over them multiplied identical sends (mappings x configs) + # — a buyer's auto-approved create_media_buy received duplicate + # ``completed`` webhooks. E2E pin: + # test_a2a_webhook_payload_types::test_completed_status_sends_task_payload. + if not webhooks: + console.print(f"[yellow]No active webhook configs for principal {principal_id}; skipping[/yellow]") + return + mapping = mappings[0] + console.print( + f"[cyan]📦 Processing mapping: {mapping.object_type} {mapping.object_id} action={mapping.action}[/cyan]" + ) + # build push notification config from step request data + from uuid import uuid4 - for _webhook_config in webhooks: - # build push notification config from step request data - from uuid import uuid4 - - cfg_dict = (step.request_data or {}).get("push_notification_config") or {} - url = cfg_dict.get("url") - if not url: - console.print("[red]No push notification URL present; skipping webhook[/red]") - continue - - authentication = cfg_dict.get("authentication") or {} - schemes = authentication.get("schemes") or [] - auth_type = schemes[0] if isinstance(schemes, list) and schemes else None - auth_token = authentication.get("credentials") - - # Derive principal/tenant from the step context if available - context_obj = getattr(step, "context", None) - derived_tenant_id = tenant_id or (getattr(context_obj, "tenant_id", None)) - derived_principal_id = getattr(context_obj, "principal_id", None) - - push_notification_config = PushNotificationConfig( - id=cfg_dict.get("id") or f"pnc_{uuid4().hex[:16]}", - tenant_id=derived_tenant_id, - principal_id=derived_principal_id, - url=url, - authentication_type=auth_type, - authentication_token=auth_token, - is_active=True, - ) + cfg_dict = (step.request_data or {}).get("push_notification_config") or {} + url = cfg_dict.get("url") + if not url: + console.print("[red]No push notification URL present; skipping webhook[/red]") + return - service = get_protocol_webhook_service() + authentication = cfg_dict.get("authentication") or {} + schemes = authentication.get("schemes") or [] + auth_type = schemes[0] if isinstance(schemes, list) and schemes else None + auth_token = authentication.get("credentials") + + # Derive principal/tenant from the step context if available + context_obj = getattr(step, "context", None) + derived_tenant_id = tenant_id or (getattr(context_obj, "tenant_id", None)) + derived_principal_id = getattr(context_obj, "principal_id", None) + + push_notification_config = PushNotificationConfig( + id=cfg_dict.get("id") or f"pnc_{uuid4().hex[:16]}", + tenant_id=derived_tenant_id, + principal_id=derived_principal_id, + url=url, + authentication_type=auth_type, + authentication_token=auth_token, + is_active=True, + ) - safe_webhook_url = webhook_url_for_log(push_notification_config.url) - console.print( - f"[cyan]📤 Sending webhook to {safe_webhook_url} for {mapping.object_type} {mapping.object_id}[/cyan]" - ) + service = get_protocol_webhook_service() - # Build webhook payload based on protocol type. - # task_type_str is the ORIGINAL action label — it keys the - # delivery-webhook guards + audit log and must NOT be rewritten - # by the SDK fallback (salesagent-yi3s). wire_task_type is the - # validated COPY passed to the SDK payload builder. - task_type_str = step.tool_name or mapping.action or "unknown" - protocol = (step.request_data or {}).get("protocol", "mcp") # Default to MCP - try: - status_enum = GeneratedTaskStatus(new_status) - except ValueError: - status_enum = GeneratedTaskStatus.unknown - - # SDK 5.7 validates task_type against TaskType enum; coerce a - # COPY for the payload while leaving task_type_str untouched. - wire_task_type = validate_webhook_task_type(task_type_str) - - payload: Task | TaskStatusUpdateEvent | McpWebhookPayload - if protocol == "a2a": - payload = create_a2a_webhook_payload( - task_id=step.step_id, - status=status_enum, - context_id=step.context_id, - result=step.response_data or {}, - ) - else: - # SDK 5.7: returns McpWebhookPayload directly - payload = create_mcp_webhook_payload( - task_id=step.step_id, - status=status_enum, - task_type=wire_task_type, - result=step.response_data, - ) + # Sanitized for every operator-facing line below (#1697): scheme://host/path, + # never credentials or query. + safe_webhook_url = webhook_url_for_log(push_notification_config.url) + console.print( + f"[cyan]📤 Sending webhook to {safe_webhook_url} for {mapping.object_type} {mapping.object_id}[/cyan]" + ) + + # Build webhook payload based on protocol type. + # task_type_str is the ORIGINAL action label — it keys the + # delivery-webhook guards + audit log and must NOT be rewritten + # by the SDK fallback. wire_task_type is the + # validated COPY passed to the SDK payload builder. + task_type_str = step.tool_name or mapping.action or "unknown" + protocol = (step.request_data or {}).get("protocol", "mcp") # Default to MCP + # Correlate to the id the BUYER holds. The A2A boundary persisted its + # outer transport ``task_*`` id on the step's request_data + # (external_task_id) at create time; the buyer polls / receives the + # webhook against THAT id, not the internal step_id. MCP/REST have no + # outer id, so they fall back to step_id (unchanged behavior). + correlation_task_id = resolve_webhook_task_id(step.request_data, step.step_id) + try: + status_enum = GeneratedTaskStatus(new_status) + except ValueError: + status_enum = GeneratedTaskStatus.unknown + + # SDK 5.7 validates task_type against TaskType enum; coerce a + # COPY for the payload while leaving task_type_str untouched. + wire_task_type = validate_webhook_task_type(task_type_str) + + payload: Task | TaskStatusUpdateEvent | McpWebhookPayload + if protocol == "a2a": + payload = create_a2a_webhook_payload( + task_id=correlation_task_id, + status=status_enum, + context_id=step.context_id, + result=step.response_data or {}, + ) + else: + # SDK 5.7: returns McpWebhookPayload directly + payload = create_mcp_webhook_payload( + task_id=correlation_task_id, + status=status_enum, + task_type=wire_task_type, + result=step.response_data, + ) - metadata: dict[str, Any] = { - "task_type": task_type_str, - "tenant_id": derived_tenant_id, - "principal_id": derived_principal_id, - } + metadata: dict[str, Any] = { + "task_type": task_type_str, + "tenant_id": derived_tenant_id, + "principal_id": derived_principal_id, + } + + try: + # If we're already in an event loop, schedule the send; otherwise run it directly + try: + loop = asyncio.get_running_loop() + task = loop.create_task( + service.send_notification( + push_notification_config=push_notification_config, + payload=payload, + metadata=metadata, + ) + ) - try: - # If we're already in an event loop, schedule the send; otherwise run it directly + def _log_task_result( + t: asyncio.Task, + raw_url: str = push_notification_config.url, + safe_url: str = safe_webhook_url, + ) -> None: + # Runs AFTER pin_task's discard (see pin_task + # docstring), so this log-and-swallow can't hold + # the strong ref past completion. + # Pass raw URL — _log_webhook_send_outcome owns sanitize. try: - loop = asyncio.get_running_loop() - task = loop.create_task( - service.send_notification( - push_notification_config=push_notification_config, - payload=payload, - metadata=metadata, - ) - ) - - def _log_task_result( - t: asyncio.Task, - raw_url: str = push_notification_config.url, - safe_url: str = safe_webhook_url, - ) -> None: - # Runs AFTER pin_task's discard (see pin_task - # docstring), so this log-and-swallow can't hold - # the strong ref past completion. - # Pass raw URL — _log_webhook_send_outcome owns sanitize. - try: - _log_webhook_send_outcome(raw_url, t.result()) - except Exception as e: - console.print(f"[red]❌ Webhook failed for {safe_url}: {str(e)}[/red]") - - # Strong-ref pin against asyncio's weak-ref task - # tracker; discard runs before _log_task_result. - pin_task(task, on_done=_log_task_result) - except RuntimeError: - # No running loop; safe to run synchronously - sent = asyncio.run( - service.send_notification( - push_notification_config=push_notification_config, - payload=payload, - metadata=metadata, - ) - ) - _log_webhook_send_outcome(push_notification_config.url, sent) - - except requests.exceptions.Timeout: - console.print(f"[red]❌ Webhook timeout for {safe_webhook_url}[/red]") - except requests.exceptions.RequestException as e: - console.print(f"[red]❌ Webhook failed for {safe_webhook_url}: {str(e)}[/red]") + _log_webhook_send_outcome(raw_url, t.result()) + except Exception as e: + console.print(f"[red]❌ Webhook failed for {safe_url}: {str(e)}[/red]") + + # Strong-ref pin against asyncio's weak-ref task + # tracker; discard runs before _log_task_result. + pin_task(task, on_done=_log_task_result) + except RuntimeError: + # No running loop; safe to run synchronously + sent = asyncio.run( + service.send_notification( + push_notification_config=push_notification_config, + payload=payload, + metadata=metadata, + ) + ) + _log_webhook_send_outcome(push_notification_config.url, sent) + + except requests.exceptions.Timeout: + console.print(f"[red]❌ Webhook timeout for {safe_webhook_url}[/red]") + except requests.exceptions.RequestException as e: + console.print(f"[red]❌ Webhook failed for {safe_webhook_url}: {str(e)}[/red]") except Exception as e: console.print(f"[red]Error sending push notifications: {e}[/red]") diff --git a/src/core/creative_agent_registry.py b/src/core/creative_agent_registry.py index 126ed52875..2f76251a47 100644 --- a/src/core/creative_agent_registry.py +++ b/src/core/creative_agent_registry.py @@ -362,6 +362,19 @@ def _get_tenant_agents(self, tenant_id: str | None) -> list[CreativeAgent]: agents.sort(key=lambda a: a.priority) return [a for a in agents if a.enabled] + def get_registered_agent_urls(self, tenant_id: str | None) -> frozenset[str]: + """Return canonical federation URLs accepted for format references. + + ``CREATIVE_AGENT_URL`` may redirect the standard agent to an in-network + test service, but buyers must continue to reference its public + federation identity. Tenant-specific agents retain their configured + public identities. + """ + agents = self._get_tenant_agents(tenant_id) + urls = {canonical_agent_url(PUBLIC_DEFAULT_AGENT_URL)} + urls.update(canonical_agent_url(agent.agent_url) for agent in agents if agent is not self.DEFAULT_AGENT) + return frozenset(urls) + async def _fetch_formats_from_agent( self, client: ADCPMultiAgentClient, diff --git a/src/core/database/repositories/__init__.py b/src/core/database/repositories/__init__.py index ca606ffda4..1e33227e26 100644 --- a/src/core/database/repositories/__init__.py +++ b/src/core/database/repositories/__init__.py @@ -26,6 +26,7 @@ from src.core.database.repositories.tenant_config import TenantConfigRepository from src.core.database.repositories.uow import ( AccountUoW, + ApprovalUoW, MediaBuyUoW, ProductUoW, PushNotificationConfigUoW, @@ -37,6 +38,7 @@ __all__ = [ "AccountRepository", "AccountUoW", + "ApprovalUoW", "AdapterConfigRepository", "TenantNotConfiguredError", "CurrencyLimitRepository", diff --git a/src/core/database/repositories/creative.py b/src/core/database/repositories/creative.py index f0db77cc3f..f2335776ed 100644 --- a/src/core/database/repositories/creative.py +++ b/src/core/database/repositories/creative.py @@ -465,8 +465,12 @@ def delete(self, assignment_id: str) -> bool: # Cross-model lookups (for assignment workflow) # ------------------------------------------------------------------ - def find_package_with_media_buy(self, package_id: str) -> tuple[MediaPackage, MediaBuy] | None: - """Find a package and its parent media buy within the tenant. + def find_package_with_media_buy( + self, + package_id: str, + principal_id: str, + ) -> tuple[MediaPackage, MediaBuy] | None: + """Find a principal-owned package and its parent buy within the tenant. Delegates to MediaBuyRepository — all MediaPackage queries are owned by that repository per the no-raw-MediaPackage-select guard. @@ -476,7 +480,7 @@ def find_package_with_media_buy(self, package_id: str) -> tuple[MediaPackage, Me from src.core.database.repositories.media_buy import MediaBuyRepository mb_repo = MediaBuyRepository(self._session, self._tenant_id) - return mb_repo.find_package_with_media_buy(package_id) + return mb_repo.find_package_with_media_buy(package_id, principal_id) def get_creative_by_id(self, creative_id: str, principal_id: str) -> Creative | None: """Get a creative by its full composite key (tenant + principal + creative_id). diff --git a/src/core/database/repositories/media_buy.py b/src/core/database/repositories/media_buy.py index db8284a722..2b1ca17053 100644 --- a/src/core/database/repositories/media_buy.py +++ b/src/core/database/repositories/media_buy.py @@ -14,9 +14,10 @@ import datetime from decimal import Decimal +from enum import StrEnum from typing import TYPE_CHECKING, Any -from sqlalchemy import select +from sqlalchemy import select, update from sqlalchemy.orm import Session, joinedload from src.core.database.models import MediaBuy, MediaPackage @@ -25,6 +26,47 @@ from adcp.types import ContextObject +# Every pre-execution state a media buy can be claimed for adapter execution FROM. +APPROVED_EXECUTION_SOURCE_STATUSES = ("pending_approval", "pending_creatives", "draft") + +# The subset still awaiting a human decision. +# +# This split is declared HERE, beside the set it narrows, because deriving it blindly +# would be wrong in a way that is easy to get backwards: a buy in ``pending_approval`` +# has not been approved by anyone yet, so a trigger that is not a human decision — the +# last blocking creative being approved, say — must NOT promote it. Letting it would make +# creative approval a substitute for human approval. +# +# It was previously a bare ``{"pending_creatives", "draft"}`` literal at the creative +# route, i.e. this derivation hand-copied at a call site with the reasoning nowhere. Read +# through ``execution_source_statuses_for`` rather than re-deriving. +HUMAN_DECISION_PENDING_STATUSES = ("pending_approval",) + + +class ApprovalTrigger(StrEnum): + """What is asking for a media buy to be executed. + + The trigger decides which source states are eligible, so the routes name what they + ARE rather than restating which statuses that implies. Four call sites each carried + their own status literal; their union was the canonical set, so no single one looked + wrong and nothing textual flagged the split. + """ + + HUMAN_DECISION = "human_decision" + """An administrator approved the workflow step. Every pre-execution state is eligible.""" + + CREATIVE_UNBLOCK = "creative_unblock" + """The last blocking creative was approved. States still awaiting a human decision are + NOT eligible — see ``HUMAN_DECISION_PENDING_STATUSES``.""" + + +def execution_source_statuses_for(trigger: ApprovalTrigger) -> tuple[str, ...]: + """Source states a media buy may be claimed for execution from, for this trigger.""" + if trigger is ApprovalTrigger.CREATIVE_UNBLOCK: + return tuple(s for s in APPROVED_EXECUTION_SOURCE_STATUSES if s not in HUMAN_DECISION_PENDING_STATUSES) + return APPROVED_EXECUTION_SOURCE_STATUSES + + class MediaBuyRepository: """Tenant-scoped data access for MediaBuy and MediaPackage. @@ -232,11 +274,17 @@ def get_packages_for_ids(self, media_buy_ids: list[str]) -> dict[str, list[Media result.setdefault(pkg.media_buy_id, []).append(pkg) return result - def find_package_with_media_buy(self, package_id: str) -> tuple[MediaPackage, MediaBuy] | None: - """Find a package and its parent media buy by package_id within the tenant. + def find_package_with_media_buy( + self, + package_id: str, + principal_id: str, + ) -> tuple[MediaPackage, MediaBuy] | None: + """Find a package and parent buy owned by the principal in this tenant. Useful when you only have a package_id and need to resolve the parent - media buy (e.g. during creative-to-package assignment). + media buy (e.g. during creative-to-package assignment). Principal + scoping prevents a same-tenant buyer from assigning its creative to + another buyer's package. Returns (MediaPackage, MediaBuy) tuple or None if not found. """ @@ -246,6 +294,7 @@ def find_package_with_media_buy(self, package_id: str) -> tuple[MediaPackage, Me .where( MediaPackage.package_id == package_id, MediaBuy.tenant_id == self._tenant_id, + MediaBuy.principal_id == principal_id, ) ).first() if result is None: @@ -453,6 +502,100 @@ def update_status( self._session.flush() return media_buy + def claim_approved_execution( + self, + media_buy_id: str, + *, + trigger: ApprovalTrigger = ApprovalTrigger.HUMAN_DECISION, + ) -> bool: + """Atomically claim one approved media buy for irreversible execution. + + The source-state guard lets exactly one concurrent admin request move + the buy into ``activating``. A loser must not call the external adapter. + ``activating`` is deliberately durable before dispatch, because an + exception after the request is sent cannot prove whether the ad server + created the order. + + ``trigger`` selects the eligible source states: a creative unblock may not + promote a buy still awaiting a human decision. The guard is enforced IN the + UPDATE, so a buy that changes state between the caller's read and this write + is refused rather than promoted. + """ + return self._transition_approved_execution( + media_buy_id, + source_statuses=execution_source_statuses_for(trigger), + target_status="activating", + ) + + def reject_pending_execution(self, media_buy_id: str) -> bool: + """Atomically reject a media buy that has not begun executing. + + Mirrors ``claim_approved_execution``: same source states, opposite decision. + Exists so the admin reject route stops assigning ``media_buy.status`` directly — + a raw write has no source guard, so it could mark a buy rejected after execution + had already been claimed, and it recognised only ``pending_approval``, leaving a + rejected ``pending_creatives`` or ``draft`` buy sitting in its old state while its + workflow step said rejected. + """ + return self._transition_approved_execution( + media_buy_id, + source_statuses=APPROVED_EXECUTION_SOURCE_STATUSES, + target_status="rejected", + ) + + def mark_approved_execution_unknown( + self, + media_buy_id: str, + *, + expected_updated_at: datetime.datetime | None = None, + ) -> bool: + """Persist an ambiguous post-dispatch outcome without overwriting success.""" + return self._transition_approved_execution( + media_buy_id, + source_statuses=("activating",), + target_status="activation_unknown", + expected_updated_at=expected_updated_at, + ) + + def renew_approved_execution_lease(self, media_buy_id: str) -> bool: + """Renew a live execution claim while its worker is still running.""" + return self._transition_approved_execution( + media_buy_id, + source_statuses=("activating",), + target_status="activating", + ) + + def complete_approved_execution(self, media_buy_id: str) -> bool: + """Mark execution active only while this worker still owns the claim.""" + return self._transition_approved_execution( + media_buy_id, + source_statuses=("activating",), + target_status="active", + ) + + def _transition_approved_execution( + self, + media_buy_id: str, + *, + source_statuses: tuple[str, ...], + target_status: str, + expected_updated_at: datetime.datetime | None = None, + ) -> bool: + """Shared tenant-scoped CAS for the approval execution lifecycle.""" + statement = update(MediaBuy).where( + MediaBuy.tenant_id == self._tenant_id, + MediaBuy.media_buy_id == media_buy_id, + MediaBuy.status.in_(source_statuses), + ) + if expected_updated_at is not None: + statement = statement.where(MediaBuy.updated_at == expected_updated_at) + updated_id = self._session.execute( + statement.values(status=target_status, updated_at=datetime.datetime.now(datetime.UTC)) + .returning(MediaBuy.media_buy_id) + .execution_options(synchronize_session="fetch") + ).scalar_one_or_none() + return updated_id is not None + def update_fields(self, media_buy_id: str, **kwargs: Any) -> MediaBuy | None: """Update arbitrary fields on a media buy within this tenant. diff --git a/src/core/database/repositories/uow.py b/src/core/database/repositories/uow.py index d66ee4856b..e2a385b7a5 100644 --- a/src/core/database/repositories/uow.py +++ b/src/core/database/repositories/uow.py @@ -14,7 +14,7 @@ # auto-commits when exiting the `with` block with WorkflowUoW(tenant_id) as uow: - steps = uow.workflows.list_by_tenant(status="pending") + steps = uow.workflows.list_by_tenant(principal_id=principal_id, status="pending") # auto-commits when exiting the `with` block with TenantConfigUoW(tenant_id) as uow: @@ -192,6 +192,28 @@ def _clear_repos(self) -> None: self.workflows = None +class ApprovalUoW(BaseUoW): + """Single transaction for workflow and media-buy approval orchestration.""" + + workflows: WorkflowRepository | None + media_buys: MediaBuyRepository | None + creatives: CreativeRepository | None + assignments: CreativeAssignmentRepository | None + + def _init_repos(self) -> None: + assert self._session is not None + self.workflows = WorkflowRepository(self._session, self._tenant_id) + self.media_buys = MediaBuyRepository(self._session, self._tenant_id) + self.creatives = CreativeRepository(self._session, self._tenant_id) + self.assignments = CreativeAssignmentRepository(self._session, self._tenant_id) + + def _clear_repos(self) -> None: + self.workflows = None + self.media_buys = None + self.creatives = None + self.assignments = None + + class TenantConfigUoW(BaseUoW): """Unit of Work for tenant configuration reads. diff --git a/src/core/database/repositories/workflow.py b/src/core/database/repositories/workflow.py index e6aa9daf17..b7a97044e5 100644 --- a/src/core/database/repositories/workflow.py +++ b/src/core/database/repositories/workflow.py @@ -16,15 +16,53 @@ from __future__ import annotations -from datetime import datetime +from datetime import UTC, datetime from typing import Any -from sqlalchemy import func, select +from sqlalchemy import ColumnExpressionArgument, Select, func, select, update from sqlalchemy.orm import Session from src.core.database.models import Context as DBContext from src.core.database.models import ObjectWorkflowMapping, Principal, WorkflowStep +# Workflow-step statuses that are final outcomes. Single source of truth for the +# repository's atomic terminal-transition guard and the A2A boundary's step→TaskState map. +TERMINAL_STEP_STATUSES = frozenset({"completed", "rejected", "failed", "canceled"}) + +# Statuses from which a buyer cancel is still safe — i.e. states where NO irreversible +# external (ad-server) work has begun. Deliberately EXCLUDES both ``approved`` and +# ``in_progress``: +# * ``approved`` — the admin-approve path commits it BEFORE execute_approved_media_buy, +# so cancelling it would leave a real order behind a canceled task. +# * ``in_progress`` — the create/update execution paths set it BEFORE running their +# adapter/business side-effects (media_buy_create.py, media_buy_update.py), so it marks +# that irreversible work is already underway; cancelling then would strand external +# state behind a canceled task. +# ``approval`` is the legacy adapter-emitted awaiting-decision alias of ``requires_approval`` +# (GAM/Broadstreet/base_workflow — see APPROVABLE_STEP_STATUSES below): a pre-side-effect state, +# so it is cancellable for the same reason ``requires_approval`` is. Until historic +# ``approval`` rows and their producers are normalized, it is carried in BOTH sets. +# Terminal statuses are (trivially) excluded too. A cancel is only accepted while the step is +# still purely pending human/forecasting action, before any side-effects have run. +CANCELLABLE_STEP_STATUSES = frozenset({"pending", "requires_approval", "pending_approval", "approval"}) + +# Statuses a step can be approved or rejected FROM — i.e. it is still awaiting a human +# decision and no irreversible execution has started. Approval/rejection is a compare-and-set +# from one of these to a decided status. Because ``approved`` is (deliberately) NON-terminal, +# a broad "not terminal" guard would let a SECOND concurrent approver win an ``approved → +# approved`` no-op and also run the irreversible adapter creation (duplicate order), and would +# let a reject run ``approved → rejected`` (stranding a live order behind a rejected workflow). +# Restricting the source states to this set makes exactly one decider win. +# +# ``approval`` is the LEGACY awaiting-decision status emitted by the adapter workflow managers +# (base_workflow.py default; GAM order-activation / manual-order / creative-approval steps; +# Broadstreet via the base manager). It is semantically identical to ``requires_approval`` — +# a step a publisher must approve/reject — so it MUST be approvable, otherwise those live human +# workflows can never be actioned. Normalizing every producer to the canonical +# ``requires_approval`` (including normalizing existing ``approval`` rows) is not +# complete yet; until then this set carries the legacy alias. +APPROVABLE_STEP_STATUSES = frozenset({"requires_approval", "pending_approval", "approval"}) + class WorkflowRepository: """Tenant-scoped data access for WorkflowStep and ObjectWorkflowMapping. @@ -60,15 +98,120 @@ def get_by_step_id(self, step_id: str) -> WorkflowStep | None: ) ).first() - def get_by_step_id_or_raise(self, step_id: str) -> WorkflowStep: - """Get a workflow step by ID or raise ``AdCPTaskNotFoundError``. + def get_policy_review_step(self, step_id: str) -> WorkflowStep | None: + """A tenant-scoped ``policy_review`` step by id, or None. + + The ``step_type`` guard is load-bearing, not cosmetic: the policy review route drives a + step terminal, so without it an arbitrary step id (e.g. a media-buy approval) could be + finalized here with a fabricated ``{"approved": true}`` artifact. Keeping both the + tenant-scoping join and the type predicate in the repository means the POST and GET legs + — and any future caller — share one definition instead of re-inlining the query. + """ + step = self.get_by_step_id(step_id) + if step is None or step.step_type != "policy_review": + return None + return step + + def get_approvable_step_for_object( + self, object_type: str, object_id: str, *, step_id: str | None = None + ) -> WorkflowStep | None: + """The workflow step awaiting a decision for a mapped business object (tenant-scoped). + + Joins ObjectWorkflowMapping and filters status to APPROVABLE_STEP_STATUSES — the + canonical awaiting-decision set (including the legacy ``approval`` alias emitted by the + adapter workflow producers). The admin media-buy detail approve/reject route uses this + so its prefilter matches the ``claim_approval`` / ``reject_if_approvable`` source-state + guard; an inline ``{requires_approval, pending_approval}`` filter previously dropped + legacy ``approval`` steps before they could reach the CAS. + + When ``step_id`` is supplied, the step must also be the exact decision rendered to the + administrator. This prevents a stale form from approving a different mapped workflow + when several approval operations exist for one media buy. Without ``step_id`` (the GET + page), the oldest mapped approval is selected deterministically. + """ + stmt = ( + select(WorkflowStep) + .join(ObjectWorkflowMapping, WorkflowStep.step_id == ObjectWorkflowMapping.step_id) + .join(DBContext, WorkflowStep.context_id == DBContext.context_id) + .where( + DBContext.tenant_id == self._tenant_id, + ObjectWorkflowMapping.object_type == object_type, + ObjectWorkflowMapping.object_id == object_id, + WorkflowStep.status.in_(APPROVABLE_STEP_STATUSES), + ) + ) + if step_id is not None: + stmt = stmt.where(WorkflowStep.step_id == step_id) + return self._session.scalars( + stmt.order_by(ObjectWorkflowMapping.created_at, WorkflowStep.created_at, WorkflowStep.step_id) + ).first() + + def _principal_scoped_steps(self, principal_id: str) -> Select[tuple[WorkflowStep]]: + """Base SELECT over the steps a single principal owns, within the tenant. + + One home for what "principal-scoped" means, so the buyer-facing reads cannot + drift apart: the tenant join every read carries, PLUS ``DBContext.principal_id``. + Step ids and transport task ids are bearer-ish identifiers, so a read that + authorizes only the tenant lets any same-tenant sibling principal who learns an + id read another principal's stored ``response_data`` or drive its workflow. + Callers pass ``principal_id`` as a required keyword so no call site can omit it. + """ + return ( + select(WorkflowStep) + .join(DBContext) + .where( + DBContext.tenant_id == self._tenant_id, + DBContext.principal_id == principal_id, + ) + ) + + def get_by_external_task_id(self, external_task_id: str, *, principal_id: str) -> WorkflowStep | None: + """Get the workflow step carrying a given transport outer task id. + + The A2A boundary persists its outer ``task_*`` id (the id returned to the + buyer) on the create step's ``request_data.external_task_id`` (see + ``_create_media_buy_impl``), so a durable ``tasks/get`` poll can resolve the + buyer's id → step → terminal status + stored ``response_data`` artifact, + surviving a server restart (the admin approval that terminalized the step runs + in a different process, so the in-memory task map is not enough). + + INVARIANT — one writer, one step: an ``external_task_id`` must be written by an + operation that produces AT MOST ONE workflow step, because this lookup returns a + single row for the key. It is deliberately unordered and ungated: with the + invariant held there is nothing to order or count. A caller that writes the same + id across N steps (``sync_creatives`` creates one step per creative) makes the + key ambiguous, and every reader — durable poll, cancel, webhook correlation — + silently acts on an arbitrary one of the N. Such an operation must address its + steps by ``step_id`` instead of being threaded through here. + + Scoped to BOTH the tenant and the owning ``principal_id`` — see + :meth:`_principal_scoped_steps` for why the tenant alone is not an + authorization boundary here. + """ + return self._session.scalars( + self._principal_scoped_steps(principal_id).where( + WorkflowStep.request_data["external_task_id"].as_string() == external_task_id, + ) + ).first() + + def get_by_step_id_or_raise(self, step_id: str, *, principal_id: str) -> WorkflowStep: + """Get a principal's own workflow step by ID or raise ``AdCPTaskNotFoundError``. Collapses the task fetch-and-raise guard shared by get_task/complete_task. No ``context`` parameter by design: those tools carry the FastMCP transport ``Context``, not an AdCP ``ContextObject``, so the task not-found envelope stays context-less rather than echoing a transport object into a repository. + + Principal-scoped (:meth:`_principal_scoped_steps`), unlike the plain + :meth:`get_by_step_id` used by admin and already-authorized internal callers: + these two callers ARE the buyer-facing MCP tools, where the principal is the + authorization boundary. A sibling principal's step is reported not-found — + the same signal an unknown id gets, so the response does not confirm the id + exists. """ - step = self.get_by_step_id(step_id) + step = self._session.scalars( + self._principal_scoped_steps(principal_id).where(WorkflowStep.step_id == step_id) + ).first() if step is None: from src.core.exceptions import AdCPTaskNotFoundError @@ -78,28 +221,26 @@ def get_by_step_id_or_raise(self, step_id: str) -> WorkflowStep: def list_by_tenant( self, *, + principal_id: str, status: str | None = None, object_type: str | None = None, object_id: str | None = None, offset: int = 0, limit: int = 20, ) -> list[WorkflowStep]: - """List workflow steps for the tenant, with optional filters. + """List the steps ``principal_id`` owns in this tenant, with optional filters. Args: + principal_id: Owning principal — required, see :meth:`_principal_scoped_steps`. + The buyer-facing ``list_tasks`` tool is the caller, so leaking a sibling + principal's steps here would expose their ids and summaries. status: Filter by step status (e.g., "pending", "requires_approval"). object_type: Filter by associated object type (e.g., "media_buy"). object_id: Filter by specific object ID (requires object_type). offset: Number of steps to skip. limit: Maximum number of steps to return. """ - stmt = ( - select(WorkflowStep) - .join(DBContext) - .where( - DBContext.tenant_id == self._tenant_id, - ) - ) + stmt = self._principal_scoped_steps(principal_id) if status: stmt = stmt.where(WorkflowStep.status == status) @@ -120,21 +261,18 @@ def list_by_tenant( def count_by_tenant( self, *, + principal_id: str, status: str | None = None, object_type: str | None = None, object_id: str | None = None, ) -> int: - """Count workflow steps matching the given filters. + """Count the steps ``principal_id`` owns in this tenant, matching the filters. - Uses the same filter logic as list_by_tenant but returns only the count. + Uses the same filter logic and the same principal scope as list_by_tenant + but returns only the count — the pagination total must describe the same + rows the page does, or it leaks the existence of a sibling's steps. """ - stmt = ( - select(WorkflowStep) - .join(DBContext) - .where( - DBContext.tenant_id == self._tenant_id, - ) - ) + stmt = self._principal_scoped_steps(principal_id) if status: stmt = stmt.where(WorkflowStep.status == status) @@ -170,6 +308,28 @@ def get_latest_mapping_for_object(self, object_type: str, object_id: str) -> Obj .order_by(ObjectWorkflowMapping.created_at.desc()) ).first() + def get_claimed_create_approval_step_for_media_buy(self, media_buy_id: str) -> WorkflowStep | None: + """Return the claimed create-approval step for a media buy. + + A media buy can have newer update mappings. Creative-unblock execution + must terminalize the original ``create_media_buy`` approval, not an + arbitrary latest mapping. + """ + return self._session.scalars( + select(WorkflowStep) + .join(ObjectWorkflowMapping, WorkflowStep.step_id == ObjectWorkflowMapping.step_id) + .join(DBContext, WorkflowStep.context_id == DBContext.context_id) + .where( + DBContext.tenant_id == self._tenant_id, + ObjectWorkflowMapping.object_type == "media_buy", + ObjectWorkflowMapping.object_id == media_buy_id, + ObjectWorkflowMapping.action.in_(("create", "approve")), + WorkflowStep.tool_name == "create_media_buy", + WorkflowStep.status == "approved", + ) + .order_by(ObjectWorkflowMapping.created_at.desc(), WorkflowStep.created_at.desc()) + ).first() + def get_step_by_id(self, step_id: str) -> WorkflowStep | None: """Alias of :meth:`get_by_step_id` (identical tenant-scoped lookup). @@ -275,34 +435,184 @@ def get_principal_name(self, principal_id: str) -> str | None: # WorkflowStep writes # ------------------------------------------------------------------ - def update_status( + @staticmethod + def resolve_tenant_for_step(session: Session, step_id: str) -> str | None: + """Resolve a step's tenant from its Context (repository owns this join). + + Lets callers that lack a tenant scope up front (e.g. ContextManager) build a + tenant-scoped repository without issuing a raw ``WorkflowStep``/``DBContext`` + query outside the repository layer. Returns None when the step (or its + context) does not exist. Read-only; does not commit. + """ + return session.scalar( + select(DBContext.tenant_id) + .join(WorkflowStep, WorkflowStep.context_id == DBContext.context_id) + .where(WorkflowStep.step_id == step_id) + ) + + def _atomic_transition( self, step_id: str, *, status: str, + status_guard: ColumnExpressionArgument[bool], completed_at: datetime | None = None, response_data: dict[str, Any] | None = None, error_message: str | None = None, ) -> WorkflowStep | None: - """Update the status of a workflow step. - - Returns the updated step, or None if not found. - Does NOT commit — the caller handles that. + """Shared atomic conditional transition: set ``status`` IFF ``status_guard`` holds. + + ONE conditional UPDATE (tenant-scoped ``WHERE step_id … AND ``) + with ``RETURNING`` — the single-statement re-evaluation against committed state + is what makes competing writers safe in either ordering. ``status_guard`` is a + SQLAlchemy predicate on ``WorkflowStep.status`` (e.g. NOT IN terminal, or IN + cancellable). Returns the re-loaded step, or None when no row matched (step + absent or its status failed the guard). Does NOT commit. """ - step = self.get_by_step_id(step_id) - if step is None: - return None - - step.status = status + values: dict[str, Any] = {"status": status} if completed_at is not None: - step.completed_at = completed_at + values["completed_at"] = completed_at if response_data is not None: - step.response_data = response_data + values["response_data"] = response_data if error_message is not None: - step.error_message = error_message + values["error_message"] = error_message elif status == "completed": - # Clear error message on successful completion - step.error_message = None + # Clear error message on successful completion. + values["error_message"] = None - self._session.flush() - return step + scoped_step_ids = ( + select(WorkflowStep.step_id) + .join(DBContext) + .where( + WorkflowStep.step_id == step_id, + DBContext.tenant_id == self._tenant_id, + ) + ) + # returning() makes the DML yield rows, so success is observable without + # the CursorResult.rowcount attribute (untyped on Session.execute's Result). + # synchronize_session="fetch" keeps any already-loaded ORM copy consistent + # so callers that further mutate the returned step see the new status. + updated = ( + self._session.execute( + update(WorkflowStep) + .where(WorkflowStep.step_id.in_(scoped_step_ids), status_guard) + .values(**values) + .returning(WorkflowStep.step_id) + .execution_options(synchronize_session="fetch") + ) + .scalars() + .first() + ) + if updated is None: + return None + return self.get_by_step_id(step_id) + + def transition_if_nonterminal( + self, + step_id: str, + *, + status: str, + completed_at: datetime | None = None, + response_data: dict[str, Any] | None = None, + error_message: str | None = None, + ) -> WorkflowStep | None: + """Atomically set a step's status IFF it is not already terminal. + + The SINGLE terminal-transition primitive shared by every competing writer + (admin approve/reject, background approval, manual complete): a terminal + workflow step (completed/rejected/failed/canceled) is IMMUTABLE. The FIRST + committed writer wins and no later writer — in either ordering — can + overwrite a committed terminal decision. + + Returns the updated step (re-loaded) or None when it does not exist OR is + already terminal (write refused). Does NOT commit. + """ + return self._atomic_transition( + step_id, + status=status, + status_guard=WorkflowStep.status.not_in(TERMINAL_STEP_STATUSES), + completed_at=completed_at, + response_data=response_data, + error_message=error_message, + ) + + def claim_approval(self, step_id: str) -> WorkflowStep | None: + """Atomically claim a step for approval: requires_approval/pending_approval → approved. + + A compare-and-set restricted to APPROVABLE_STEP_STATUSES. Because ``approved`` is + (deliberately) NON-terminal, the broad ``transition_if_nonterminal`` guard would let a + SECOND concurrent approver win an ``approved → approved`` no-op and also run + ``execute_approved_media_buy`` — duplicating irreversible adapter work. This narrower + source-state guard makes exactly ONE approver win; a later approver sees ``approved`` + (not in the source set) and gets None. Returns the updated step, or None when the step + is absent OR not in an approvable status (already approved/executing/terminal). Does + NOT commit. + """ + return self._atomic_transition( + step_id, + status="approved", + status_guard=WorkflowStep.status.in_(APPROVABLE_STEP_STATUSES), + ) + + def complete_claimed_approval(self, step_id: str) -> WorkflowStep | None: + """Atomically complete an approved step that needs no external execution. + + This is intentionally a second update in the caller's SAME transaction + as ``claim_approval``. Committing ``approved`` first and finalizing in + another UoW can strand an unreclaimable nonterminal step if that second + transaction fails. Restricting the source state to ``approved`` also + prevents this convenience path from completing an unclaimed decision. + """ + return self._atomic_transition( + step_id, + status="completed", + status_guard=WorkflowStep.status == "approved", + completed_at=datetime.now(UTC), + response_data={"approved": True}, + ) + + def reject_if_approvable( + self, + step_id: str, + *, + error_message: str | None = None, + response_data: dict[str, Any] | None = None, + ) -> WorkflowStep | None: + """Atomically reject a step awaiting a decision: requires_approval/pending_approval → rejected. + + Mirror of ``claim_approval`` with the SAME source-state guard, so a step that has + already been ``approved`` (irreversible execution underway) cannot be rejected — which + would otherwise strand a live ad-server order behind a rejected workflow. Returns the + updated step, or None when the step is absent OR not in an approvable status. Does NOT + commit. + """ + return self._atomic_transition( + step_id, + status="rejected", + status_guard=WorkflowStep.status.in_(APPROVABLE_STEP_STATUSES), + error_message=error_message, + response_data=response_data, + ) + + def cancel_if_cancellable(self, step_id: str, *, completed_at: datetime) -> bool: + """Atomically cancel a step IFF it is in a CANCELLABLE status. + + The buyer-facing cancel primitive (A2A ``tasks/cancel``). It refuses to cancel a step + once irreversible external work has begun — CANCELLABLE_STEP_STATUSES excludes both + ``approved`` (admin-approve commits it before order creation) and ``in_progress`` (the + create/update paths persist it before their adapter side-effects), as well as all + terminal states — so a cancel can never strand a real order behind a canceled task. The + atomicity is a single conditional UPDATE (``_atomic_transition``): the guard is + re-evaluated against committed state, so competing writers are safe in either ordering. + Returns True when canceled, False when the step is absent or not in a cancellable status. + Does NOT commit. + """ + return ( + self._atomic_transition( + step_id, + status="canceled", + status_guard=WorkflowStep.status.in_(CANCELLABLE_STEP_STATUSES), + completed_at=completed_at, + ) + is not None + ) diff --git a/src/core/exceptions.py b/src/core/exceptions.py index ecadf55826..1c9669855e 100644 --- a/src/core/exceptions.py +++ b/src/core/exceptions.py @@ -11,13 +11,16 @@ from __future__ import annotations import logging -from typing import TYPE_CHECKING, Any, ClassVar, Literal +import re +from collections.abc import Mapping +from types import UnionType +from typing import TYPE_CHECKING, Annotated, Any, ClassVar, Literal, Union, cast, get_args, get_origin from adcp.server.helpers import STANDARD_ERROR_CODES, adcp_error from pydantic import BaseModel, ValidationError if TYPE_CHECKING: - from collections.abc import Iterator, Mapping, Sequence + from collections.abc import Callable, Iterator, Sequence from adcp.types import ContextObject @@ -32,17 +35,14 @@ # WIRE_STANDARD_CODES. Codes in ERROR_CODE_MAPPING are translated at the # transport boundary; codes in INTERNAL_CODES never leave the server. -# Spec codes the SDK helper table has not caught up to. The pinned 3.1 enum -# (enums/error-code.json @ adcp 04f59d2d5) defines these as real wire codes; -# adcp 5.7's ``STANDARD_ERROR_CODES`` predates them, and the SDK is a -# cross-check, not the authority. CREATIVE_NOT_FOUND per the enum: correctable, -# and "Sellers MUST return this code uniformly for any creative_id not owned by -# the calling account" (#1430 review). CONFIGURATION_ERROR per the enum: -# terminal — "the buyer cannot resolve a seller-side deployment -# misconfiguration and MUST NOT auto-retry" (#1430 review). The remaining -# demoted spec code (BILLING_NOT_SUPPORTED) is tracked for the same treatment -# in #1602. +# Spec codes the SDK helper table has not caught up to. The tagged AdCP 3.1.1 +# enum is authoritative; the SDK is a cross-check, not the authority. +# AUTH_MISSING / AUTH_INVALID distinguish no credentials from rejected +# credentials. CREATIVE_NOT_FOUND is correctable; CONFIGURATION_ERROR and +# AUTH_INVALID are terminal. _SPEC_SUPPLEMENT_CODES: dict[str, dict[str, str]] = { + "AUTH_MISSING": {"recovery": "correctable", "message": "Authentication credentials are required"}, + "AUTH_INVALID": {"recovery": "terminal", "message": "Authentication credentials were rejected"}, "CREATIVE_NOT_FOUND": {"recovery": "correctable", "message": "Creative not found"}, "CONFIGURATION_ERROR": {"recovery": "terminal", "message": "Configuration error"}, } @@ -263,6 +263,7 @@ def __init__( suggestion: str | None = None, retry_after: int | None = None, context: ContextObject | dict[str, Any] | None = None, + _wire_safe_message: bool = False, ) -> None: # ``error_code`` and ``status_code`` kwargs are only used by the # sanctioned ``synthesize()`` classmethod for boundary fallback paths @@ -275,6 +276,7 @@ def __init__( self.suggestion = suggestion if suggestion is not None else type(self)._default_suggestion self.retry_after = retry_after self.context = context + self._wire_safe_message = _wire_safe_message self.error_code = error_code if error_code is not None else type(self)._default_error_code self.status_code = status_code if status_code is not None else type(self)._default_status_code self.recovery = recovery if recovery is not None else type(self)._default_recovery @@ -418,12 +420,28 @@ def to_adcp_error(self) -> dict[str, Any]: ) +# Canonical buyer-facing suggestions from error-code.json enumMetadata (AdCP 3.1.1): +# each code carries its own default hint, so a VALIDATION_ERROR must not borrow +# INVALID_REQUEST's text. Text is byte-identical to the pinned enum and graded +# by the pinned-fixture oracle in test_error_boundary_translation. +INVALID_REQUEST_SUGGESTION = "check request parameters and fix" +VALIDATION_ERROR_SUGGESTION = "review error details and fix field values" + + class AdCPValidationError(AdCPError): """Invalid parameters or request data (400).""" _default_status_code: ClassVar[int] = 400 _default_error_code: ClassVar[str] = "VALIDATION_ERROR" _default_recovery: ClassVar[RecoveryHint] = "correctable" + # The buyer gets a hint even when a raise site supplies none — same reason + # AdCPAuthenticationError carries one below. The scrub used to synthesize this + # text on the way out, so a site that opts its message in via + # ``_wire_safe_message`` (and thereby skips the scrub) would otherwise trade a + # restored ``message`` for a lost ``suggestion``; 23 of the opted-in sites pass + # no explicit suggestion. Byte-identical to what the scrub emitted, so the + # opt-in is a pure gain rather than a swap. Per-raise ``suggestion=`` overrides. + _default_suggestion: ClassVar[str | None] = VALIDATION_ERROR_SUGGESTION class AdCPInvalidRequestError(AdCPValidationError): @@ -436,27 +454,27 @@ class AdCPInvalidRequestError(AdCPValidationError): """ _default_error_code: ClassVar[str] = "INVALID_REQUEST" + # Its own code's enum text, NOT the inherited VALIDATION_ERROR one — the two + # codes carry different canonical hints and a subclass must not borrow. + _default_suggestion: ClassVar[str | None] = INVALID_REQUEST_SUGGESTION -AUTH_REQUIRED_SUGGESTION = "Provide valid credentials (x-adcp-auth token)." +AUTH_REQUIRED_CANONICAL_SUGGESTION = ( + "provide credentials when missing; do NOT auto-retry rejected credentials — escalate for rotation" +) +# Backward-compatible name used by legacy AUTH_REQUIRED raise sites. The value +# remains the pinned enumMetadata suggestion so those paths cannot advise an +# unsafe retry for rejected credentials. +AUTH_REQUIRED_SUGGESTION = AUTH_REQUIRED_CANONICAL_SUGGESTION class AdCPAuthenticationError(AdCPError): - """Missing or invalid authentication credentials (401). - - Emits the standard ``AUTH_REQUIRED`` wire code — the sole authentication - error code in the AdCP 3.1 error-code enum and adcp 5.7 - ``STANDARD_ERROR_CODES``. Its enum description explicitly covers both - "credentials missing" and "credentials presented but rejected", so it is - the canonical code for every authentication failure. - - Recovery is ``correctable`` per the pinned AdCP error-code enum - (``AUTH_REQUIRED.recovery == "correctable"``; released 3.1.0 agrees) — - not the ``terminal`` base default. The enum carries operationally distinct - sub-cases (missing credentials → retry; presented-but-rejected → escalate), - but its single canonical ``recovery`` classification is ``correctable``, - and the wire contract is graded against that enum (#1417, - superseding the earlier "storyboards grade only the code" judgment). + """Legacy missing-or-invalid authentication failure (401). + + Emits deprecated ``AUTH_REQUIRED`` only where lower-layer business helpers + lack the wire credential state needed to select AdCP 3.1.1 + ``AUTH_MISSING`` or ``AUTH_INVALID``. Its pinned recovery remains + ``correctable`` and its suggestion preserves both sub-cases. """ _default_status_code: ClassVar[int] = 401 @@ -476,6 +494,42 @@ class AdCPAuthRequiredError(AdCPAuthenticationError): """ +class AdCPAuthMissingError(AdCPAuthenticationError): + """No Authorization credentials were presented (401, ``AUTH_MISSING``).""" + + _default_error_code: ClassVar[str] = "AUTH_MISSING" + _default_recovery: ClassVar[RecoveryHint] = "correctable" + _default_suggestion: ClassVar[str | None] = "provide credentials via the auth header and retry" + + +class AdCPAuthInvalidError(AdCPAuthenticationError): + """Presented Authorization credentials were rejected (401, ``AUTH_INVALID``).""" + + _default_error_code: ClassVar[str] = "AUTH_INVALID" + _default_recovery: ClassVar[RecoveryHint] = "terminal" + _default_suggestion: ClassVar[str | None] = ( + "do NOT auto-retry — credentials were rejected; rotate keys, refresh OAuth tokens once if applicable, " + "otherwise escalate to a human" + ) + + +def classify_auth_credentials_error( + headers: Mapping[str, str], + *, + missing_message: str = "Authentication credentials are required.", + invalid_message: str = "Authentication credentials were rejected.", +) -> AdCPAuthMissingError | AdCPAuthInvalidError: + """Classify absent credentials separately from presented unusable credentials. + + AdCP 3.1.1 defines the split by presence of the standard Authorization + header. The seller may still accept legacy ``x-adcp-auth`` credentials, + but that extension does not change the standard wire classifier. + """ + if any(name.lower() == "authorization" for name in headers): + return AdCPAuthInvalidError(invalid_message) + return AdCPAuthMissingError(missing_message) + + class AdCPAuthorizationError(AdCPError): """Authenticated but not authorized for this resource (403). @@ -1026,13 +1080,6 @@ def build_two_layer_error_envelope(exc: AdCPError) -> dict[str, Any]: return envelope -# Canonical buyer-facing suggestions from error-code.json enumMetadata (AdCP 3.1.1): -# each code carries its own default hint, so a VALIDATION_ERROR must not borrow -# INVALID_REQUEST's text. -INVALID_REQUEST_SUGGESTION = "check request parameters and fix" -VALIDATION_ERROR_SUGGESTION = "review error details and fix field values" - - def first_validation_error_field(validation_error: ValidationError) -> str | None: """Return the bracket-notation path of the first Pydantic error, or ``None``. @@ -1045,24 +1092,216 @@ def first_validation_error_field(validation_error: ValidationError) -> str | Non errors = validation_error.errors() if not errors: return None + return validation_error_field(errors[0]) + + +def _loaded_pydantic_models() -> list[type[BaseModel]]: + """Return every currently loaded Pydantic model exactly once.""" + models: list[type[BaseModel]] = [] + pending = list(BaseModel.__subclasses__()) + seen: set[type[BaseModel]] = set() + while pending: + model = pending.pop() + if model in seen: + continue + seen.add(model) + models.append(model) + pending.extend(model.__subclasses__()) + return models + + +def _expanded_validation_annotations(annotations: Sequence[Any]) -> list[Any]: + """Flatten Annotated and union wrappers used while walking a schema path.""" + result: list[Any] = [] + pending = list(annotations) + while pending: + annotation = pending.pop() + origin = get_origin(annotation) + if origin is Annotated: + args = get_args(annotation) + if args: + pending.append(args[0]) + elif origin in (Union, UnionType): + pending.extend(get_args(annotation)) + else: + result.append(annotation) + return result + + +def _sequence_item_annotations(annotations: Sequence[Any]) -> list[Any]: + """Return element annotations for sequence branches at an integer path segment.""" + items: list[Any] = [] + for annotation in _expanded_validation_annotations(annotations): + if get_origin(annotation) in (list, tuple, set, frozenset): + args = get_args(annotation) + if args: + items.append(args[0]) + return items + + +def _validation_annotation_branches( + annotations: Sequence[Any], +) -> tuple[list[Any], list[type[BaseModel]]]: + """Split schema candidates into mapping-value and model branches.""" + mapping_values: list[Any] = [] + models: list[type[BaseModel]] = [] + for annotation in _expanded_validation_annotations(annotations): + origin = get_origin(annotation) + if origin in (dict, Mapping): + args = get_args(annotation) + mapping_values.append(args[1] if len(args) > 1 else Any) + elif isinstance(annotation, type) and issubclass(annotation, BaseModel): + models.append(annotation) + return mapping_values, models + + +def _safe_validation_location_segment( + segment: object, + annotations: Sequence[Any], +) -> tuple[str, list[Any]]: + """Project one string path segment and advance its trusted schema branches.""" + mapping_values, models = _validation_annotation_branches(annotations) + if not isinstance(segment, str) or not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", segment): + return ("nested_field" if mapping_values else "unrecognized_key"), mapping_values + + declared = [model.model_fields[segment].annotation for model in models if segment in model.model_fields] + if declared: + return segment, declared + + matching_models = [model for model in models if model.__name__ == segment] + if matching_models: + return segment, matching_models + if mapping_values: + return "nested_field", mapping_values + return "nested_field", [] + + +def safe_validation_error_location(error: Mapping[str, Any]) -> list[str | int]: + """Return a field location with client-controlled unknown keys redacted. + + Walk the loaded Pydantic schema graph so declared nested fields remain + actionable while arbitrary mapping keys are replaced. Pydantic represents + both with plain strings in ``loc``; character-shape checks alone are not a + trust boundary because credentials are often identifier-shaped. + """ + + annotations: list[Any] = _loaded_pydantic_models() + location: list[str | int] = [] + for segment in error.get("loc", ()): + if isinstance(segment, int): + location.append(segment) + item_annotations = _sequence_item_annotations(annotations) + if item_annotations: + annotations = item_annotations + continue + + safe_segment, annotations = _safe_validation_location_segment(segment, annotations) + location.append(safe_segment) + + if str(error.get("type", "")) in {"extra_forbidden", "unexpected_keyword_argument"} and location: + location[-1] = "unrecognized_field" + return location + + +def validation_error_field(error: Mapping[str, Any]) -> str | None: + """Render one buyer-safe validation location in bracket notation.""" parts: list[str] = [] - for loc in errors[0]["loc"]: + for loc in safe_validation_error_location(error): if isinstance(loc, int): parts.append(f"[{loc}]") elif parts: parts.append(f".{loc}") else: parts.append(str(loc)) - return "".join(parts) + return "".join(parts) or None + + +_STATIC_VALIDATION_MESSAGES = { + "enum": "Value is not one of the permitted options.", + "finite_number": "Expected a numeric value.", + "float_type": "Expected a numeric value.", + "integer_type": "Expected an integer value.", + "literal_error": "Value is not one of the permitted options.", +} + + +def _safe_length_error_message(error_type: str, context: object) -> str: + """Render trusted numeric length constraints without copying rejected input.""" + if not isinstance(context, Mapping): + return "Value does not satisfy the permitted length constraints." + + is_string = error_type.startswith("string_") + if "too_short" in error_type: + minimum = context.get("min_length") + if isinstance(minimum, int): + unit = "characters" if is_string else "items" + return f"Value must contain at least {minimum} {unit}." + + maximum = context.get("max_length") + if isinstance(maximum, int): + unit = "characters" if is_string else "items" + return f"Value must contain at most {maximum} {unit}." + return "Value does not satisfy the permitted length constraints." + + +def _safe_numeric_range_error_message(context: object) -> str: + """Retain only trusted numeric bounds from a Pydantic range error.""" + if isinstance(context, Mapping): + relation_by_key = { + "ge": "greater than or equal to", + "gt": "greater than", + "le": "less than or equal to", + "lt": "less than", + } + for key, relation in relation_by_key.items(): + bound = context.get(key) + if isinstance(bound, int | float) and not isinstance(bound, bool): + return f"Value must be {relation} {bound}." + return "Value is outside the permitted range." + + +def safe_validation_error_message(error: Mapping[str, Any]) -> str: + """Return static, actionable text for one Pydantic error. + + Pydantic's raw ``msg`` and ``input`` fields are untrusted request-derived + data: custom validators and extra-field failures can embed credentials, + connection strings, or other buyer secrets. Wire diagnostics retain the + structured field path and error category while using only static text. + """ + error_type = str(error.get("type", "")) + if "missing" in error_type: + return "Required field is missing." + if error_type in {"extra_forbidden", "unexpected_keyword_argument"}: + return "Extra field is not allowed by the AdCP request schema." + if "string_type" in error_type: + return "Expected a string value." + if "int_" in error_type or error_type == "integer_type": + return "Expected an integer value." + if "float_" in error_type: + return "Expected a numeric value." + if "bool_" in error_type: + return "Expected a boolean value." + if "pattern" in error_type: + return "Value does not match the required format." + if "too_short" in error_type or "too_long" in error_type: + return _safe_length_error_message(error_type, error.get("ctx")) + if error_type.startswith(("greater_than", "less_than")): + return _safe_numeric_range_error_message(error.get("ctx")) + return _STATIC_VALIDATION_MESSAGES.get(error_type, "Value does not satisfy the field constraints.") def build_validation_error_details(errors: Sequence[Mapping[str, Any]]) -> dict[str, Any]: - """Project Pydantic errors into the buyer-safe structured detail shape.""" + """Project Pydantic errors into the buyer-safe structured detail shape. + + Never copy Pydantic's raw ``msg``, ``input``, or ``ctx`` values. They can + contain rejected request data even when the exception has already been + translated to a typed ``AdCPValidationError``. + """ return { "validation_errors": [ { - "loc": list(error.get("loc", ())), - "msg": error.get("msg"), + "loc": safe_validation_error_location(error), + "msg": safe_validation_error_message(error), "type": error.get("type"), } for error in errors @@ -1070,28 +1309,408 @@ def build_validation_error_details(errors: Sequence[Mapping[str, Any]]) -> dict[ } +def _pydantic_validation_error_kwargs(exc: ValidationError) -> dict[str, Any]: + """Constructor kwargs for a structured ``AdCPValidationError``. + + The projector can populate message/field/details, but it cannot choose the semantic error + class or wire code; the registry's single ``adcp_class`` authority does that at runtime. + """ + errors = exc.errors() + return { + "message": safe_validation_error_message(errors[0]) if errors else "Request failed schema validation", + "field": first_validation_error_field(exc), + "suggestion": VALIDATION_ERROR_SUGGESTION, + "details": build_validation_error_details(errors), + } + + +def _message_only_kwargs(exc: Exception) -> dict[str, Any]: + """Constructor kwargs for built-ins whose semantic mapping needs only their message.""" + return {"message": str(exc)} + + +# Ordered registry of EVERY raw-exception → typed-AdCPError normalizer. The SINGLE SOURCE OF TRUTH +# for ``normalize_to_adcp_error`` AND the completeness guard +# (``test_sanitized_category_registry_covers_all_correctable_builtin_targets``), which pins every +# CLIENT-CORRECTABLE target code into ``_SANITIZED_BY_WIRE_CODE`` — so a future mapping (e.g. +# ``KeyError → AdCPNotFoundError``, or another SPECIAL normalizer) can't silently fall through to +# the misleading generic internal message when scrubbed. Each entry is +# ``(builtin_type, adcp_class, kwargs_projector)``. ``adcp_class`` is the ONE semantic authority: +# runtime always instantiates it, and the completeness guard reads it. The projector can only return +# constructor kwargs (message/field/details/etc.), so input-dependent projection cannot change the +# error class or wire code. ``ValidationError`` is listed FIRST because it IS-A ``ValueError`` and +# needs structured kwargs; first ``isinstance`` match wins. +_BuiltinNormalizer = tuple[type[Exception], type["AdCPError"], "Callable[[Any], dict[str, Any]]"] +_BUILTIN_NORMALIZATION: tuple[_BuiltinNormalizer, ...] = ( + (ValidationError, AdCPValidationError, _pydantic_validation_error_kwargs), + (ValueError, AdCPValidationError, _message_only_kwargs), + (PermissionError, AdCPAuthorizationError, _message_only_kwargs), +) + +# Projectors may populate buyer-facing presentation fields only. Semantic identity belongs solely +# to the registry's ``adcp_class``; allowing constructor overrides such as ``error_code`` or +# ``recovery`` would recreate a second authority behind the completeness guard's back. ``context`` +# is also forbidden because it bypasses the raw-exception scrubbing applied to messages/details. +_NORMALIZATION_PROJECTOR_KEYS = frozenset({"message", "field", "suggestion", "retry_after", "details"}) + + +def _representative_builtin(exc_type: type[Exception]) -> Exception: + """A minimal live instance of a registry builtin, for probing its projector.""" + if exc_type is ValidationError: + + class _Probe(BaseModel): + x: int + + probe_error: ValidationError | None = None + try: + _Probe(x="not-an-int") + except ValidationError as ve: + probe_error = ve + assert probe_error is not None, "probe model failed to raise ValidationError" + return probe_error + return exc_type("probe") + + +def _projector_key_violations(registry: tuple[_BuiltinNormalizer, ...]) -> list[str]: + """Forbidden-key findings per registry projector, probed with a representative builtin. + + Pure detector shared by the import-time gate below and its known-bad self-test, so the + gate's matcher cannot silently degrade. + """ + findings: list[str] = [] + for exc_type, _adcp_class, projector in registry: + forbidden = set(projector(_representative_builtin(exc_type))) - _NORMALIZATION_PROJECTOR_KEYS + if forbidden: + findings.append(f"{exc_type.__name__}: forbidden projector keys {sorted(forbidden)}") + return findings + + +def _build_normalized_error(adcp_class: type[AdCPError], projected_kwargs: dict[str, Any]) -> AdCPError: + """Instantiate the registry's fixed semantic class from presentation-only kwargs. + + The presentation-only contract is enforced at MODULE IMPORT (the gate below probes every + registry projector), never mid-request: this function runs inside boundary exception + handlers at all three transports, where a raise would shadow the original exception and + fail open with no envelope. + """ + return adcp_class(**projected_kwargs) + + +# Import-time gate: a projector emitting a semantic override (``error_code``/``recovery``/ +# ``context``/anything off the allowlist) fails the BUILD here, mirroring the +# ``_NON_STANDARD_TARGETS`` precedent above — never a live request inside a boundary handler. +_PROJECTOR_KEY_VIOLATIONS = _projector_key_violations(_BUILTIN_NORMALIZATION) +assert not _PROJECTOR_KEY_VIOLATIONS, f"normalization projector contract violated: {_PROJECTOR_KEY_VIOLATIONS}" + + def normalize_to_adcp_error(exc: Exception) -> AdCPError: """Normalize untyped exceptions to typed AdCPError subclasses. Single source of truth for the wrapping applied at all three transport boundaries (MCP, A2A, REST). Already-typed ``AdCPError`` passes through - unchanged. Pydantic ``ValidationError`` maps to a structured, sanitized - ``AdCPValidationError``; other ``ValueError`` instances map to the plain - validation error, ``PermissionError`` to ``AdCPAuthorizationError``, and - anything else wraps in base ``AdCPError`` (INTERNAL_ERROR). + unchanged. Every raw-exception normalizer lives in ``_BUILTIN_NORMALIZATION``: + Pydantic ``ValidationError`` → a structured, sanitized ``AdCPValidationError`` (field + + details); other ``ValueError`` → the plain validation error; ``PermissionError`` → + ``AdCPAuthorizationError``. Anything else wraps in base ``AdCPError`` (INTERNAL_ERROR). """ if isinstance(exc, AdCPError): return exc + for exc_type, adcp_class, kwargs_projector in _BUILTIN_NORMALIZATION: + if isinstance(exc, exc_type): + return _build_normalized_error(adcp_class, kwargs_projector(exc)) + return AdCPError(str(exc) or type(exc).__name__) + + +# Internal/infra wire codes whose raise-site message may embed adapter/DB internals (a +# connection string, a stack detail) and MUST be scrubbed before reaching ANY buyer-facing +# wire. The SERVICE_UNAVAILABLE family (base ``AdCPError``, ``AdCPAdapterError`` + subclasses, +# ``AdCPServiceUnavailableError``) plus terminal ``CONFIGURATION_ERROR`` (seller-side +# misconfiguration the buyer can't resolve — its decryption-failure raise sites can interpolate +# a secret) both belong here. Keyed on the wire code, NOT on ``recovery == "transient"`` (which +# would miss the terminal Config/base errors and false-positive on the safe-message RateLimit). +INTERNAL_WIRE_CODES: frozenset[str] = frozenset({"SERVICE_UNAVAILABLE", "CONFIGURATION_ERROR"}) + +_SANITIZED_INTERNAL_MESSAGE = "An internal error occurred while processing the request." +# We always emit a suggestion, though the spec does not require one (error.json requires only +# ``code`` + ``message``); transport-errors.mdx §Security Considerations constrains its CONTENT +# to generic correction guidance, which is what the scrub provides. The raise site's suggestion +# (which, like the message, may interpolate internals) is replaced with static guidance whose +# retry semantics MATCH the emitted ``recovery``. A single retry-later string is WRONG for a +# ``terminal`` internal error (CONFIGURATION_ERROR — per 3.1.1 the buyer MUST NOT auto-retry; +# the seller operator must resolve it): pairing ``recovery: terminal`` with "retry later" emits +# a self-contradictory envelope. Pick the suggestion by recovery so the two never disagree. +# +# Deliberate deviation from the pinned enum: unlike ``_SANITIZED_BY_WIRE_CODE`` below — +# whose suggestions ARE the codes' canonical ``enumMetadata`` text — this bucket is keyed on +# ``recovery``, not on the wire code, so its strings are ours rather than the spec's (the enum +# says "retry with exponential backoff" for SERVICE_UNAVAILABLE; we say "retry later ... contact +# the seller"). The semantics agree; the wording does not. That is the point: this bucket must +# also serve codes with no enum entry at all — an unmapped internal code is coerced to +# SERVICE_UNAVAILABLE by the caller — and keying on the emitted ``recovery`` is what guarantees +# the guidance can never contradict it. Per-code spec text would reintroduce exactly the +# contradiction this table was written to remove. Kept auditable by +# ``test_sanitized_suggestions_match_pinned_spec_enum``, which holds the client-correctable +# codes to the enum and so makes the two-axis split visible rather than accidental. +_SANITIZED_TRANSIENT_SUGGESTION = "Retry the request later; if the problem persists, contact the seller." +_SANITIZED_TERMINAL_SUGGESTION = ( + "This request cannot be retried; the seller must resolve the issue before it can succeed. Contact the seller." +) +_SANITIZED_CORRECTABLE_SUGGESTION = ( + "The request could not be completed as submitted; review and adjust the request before resubmitting." +) + +# Exhaustive over ``RecoveryHint`` — one static, internals-free suggestion per recovery class so +# the guidance can never contradict the emitted ``recovery``. A missing/extra key is caught by +# ``test_..._suggestion_table_covers_all_recovery_hints``. +_SUGGESTION_BY_RECOVERY: dict[RecoveryHint, str] = { + "transient": _SANITIZED_TRANSIENT_SUGGESTION, + "correctable": _SANITIZED_CORRECTABLE_SUGGESTION, + "terminal": _SANITIZED_TERMINAL_SUGGESTION, +} + + +def _sanitized_suggestion_for(recovery: RecoveryHint) -> str: + """Static, internals-free guidance matching ``recovery``: retry for ``transient``, adjust-and- + resubmit for ``correctable``, no-retry/escalation for ``terminal``. Keyed on the SAME + ``recovery`` the sanitized error carries so the suggestion can't contradict it.""" + return _SUGGESTION_BY_RECOVERY[recovery] + + +def _canonical_recovery_for(wire_code: str) -> RecoveryHint: + """The recovery the SDK table (plus the pinned-spec supplement) assigns a wire code + (SERVICE_UNAVAILABLE→transient, CONFIGURATION_ERROR→terminal, …). NOT the pinned spec enum + for every code — the SDK table diverges from it for several codes; both codes this scrub can + emit agree across the two sources, which is what the callers rely on. Internal/infra errors + emit the recovery their CODE mandates, NOT a possibly-inconsistent instance override — a + sanitized SERVICE_UNAVAILABLE tagged ``terminal``/``correctable`` (or a CONFIGURATION_ERROR + tagged ``transient``) is self-contradictory on the wire. Unknown codes are coerced to + SERVICE_UNAVAILABLE by the caller, so they resolve to ``transient`` here too.""" + meta = WIRE_STANDARD_CODES.get(wire_code) + return cast(RecoveryHint, meta["recovery"]) if meta else "transient" + + +# Category-specific sanitized (message, suggestion) for the client-correctable codes a scrub can +# emit, so the human text MATCHES the machine code — a VALIDATION_ERROR must not read "an internal +# error occurred", and an AUTH_REQUIRED must say "authenticate", not "adjust the request". The +# SUGGESTION leg is the code's canonical spec text (error-code.json enumMetadata, via the shared +# spec-derived constants above) — hand-written retry advice here once contradicted the enum, which +# says AUTH_REQUIRED must NOT advise auto-retry. Messages stay ours (the spec defines no canonical +# message); all strings are static and secret-free — ``str(exc)`` is never restored. Codes absent +# here (SERVICE_UNAVAILABLE, CONFIGURATION_ERROR) fall back to the generic internal message + a +# recovery-matched suggestion, which is correct for the internal/infra bucket. +_SANITIZED_BY_WIRE_CODE: dict[str, tuple[str, str]] = { + "INVALID_REQUEST": ( + "The request is malformed or contains unsupported fields; review it and resubmit.", + INVALID_REQUEST_SUGGESTION, + ), + # DELIBERATE mismatch, do not "fix" by rewording: VALIDATION_ERROR_SUGGESTION reads + # "review error details and fix field values", yet the scrub branch in + # ``safe_adcp_error`` withholds ``details`` — so the buyer is pointed at a payload + # this path does not send. The suggestion is nevertheless kept verbatim because it is + # the code's canonical ``enumMetadata`` text from the pinned error-code enum, and + # ``test_sanitized_suggestions_match_pinned_spec_enum`` holds it there. Diverging from + # the enum to describe OUR scrub would trade a spec violation for a wording nicety; + # the ``field`` that IS forwarded remains the actionable half. + "VALIDATION_ERROR": ( + "The request could not be validated; review the submitted fields and resubmit.", + VALIDATION_ERROR_SUGGESTION, + ), + "AUTH_REQUIRED": ( + "Authentication or authorization failed; provide valid credentials or the required permissions.", + AUTH_REQUIRED_CANONICAL_SUGGESTION, + ), +} + + +def _sanitized_text_for(wire_code: str, recovery: RecoveryHint) -> tuple[str, str]: + """The sanitized ``(message, suggestion)`` a scrub emits for ``wire_code``. + + ONE selection rule for BOTH scrub paths: the ``synthesize``-based ``_scrubbed_error`` + below, and the ``AdCPValidationError`` branch of ``safe_adcp_error``, which must return + ``type(exc)(...)`` to preserve the subclass and therefore cannot delegate to + ``_scrubbed_error``. Inlining the lookup at both sites let the same wire code yield + different buyer text depending on whether the exception was a raw built-in or a typed + validation error. Codes without a category entry fall back to the generic internal + message plus a ``recovery``-matched suggestion. + """ + return _SANITIZED_BY_WIRE_CODE.get(wire_code, (_SANITIZED_INTERNAL_MESSAGE, _sanitized_suggestion_for(recovery))) + + +def _scrubbed_error( + *, + error_code: str, + wire_code: str, + recovery: RecoveryHint, + status_code: int, + context: ContextObject | dict[str, Any] | None, + field: str | None = None, +) -> AdCPError: + """A wire-safe ``AdCPError`` carrying the given code/recovery but a SANITIZED, secret-free + message + suggestion selected by the BUYER-FACING ``wire_code`` (so the human text matches the + machine code), with ``details`` dropped. A caller may preserve a field path derived from a + structured validator; raw messages and input values are never retained. The single scrub + constructor for ``safe_adcp_error`` so message replacement can't drift between call sites. + Codes without a category entry fall back to the generic internal message + a + recovery-matched suggestion.""" + message, suggestion = _sanitized_text_for(wire_code, recovery) + return AdCPError.synthesize( + message, + error_code=error_code, + status_code=status_code, + recovery=recovery, + field=field, + suggestion=suggestion, + context=context, + ) + + +def synthesize_safe_adcp_error( + *, + error_code: str, + status_code: int, + context: ContextObject | dict[str, Any] | None = None, +) -> AdCPError: + """Build a synthetic wire error without trusting an untyped source message. + + Boundary fallbacks sometimes have a legacy machine code and HTTP status but + no typed ``AdCPError`` instance. They must preserve those semantics without + copying ``str(exc)`` into a buyer-visible envelope. The machine code is + authoritative for recovery; an untyped source's positional recovery hint + is never trusted because it can contradict the standardized code metadata. + """ + wire_code = to_wire_error_code(error_code) + resolved_recovery = _canonical_recovery_for(wire_code) + return _scrubbed_error( + error_code=wire_code, + wire_code=wire_code, + recovery=resolved_recovery, + status_code=status_code, + context=context, + ) + + +def safe_adcp_error(exc: Exception) -> AdCPError: + """Return a wire-safe ``AdCPError`` — THE sanitization policy for MCP, A2A, REST, and the + webhook push path via ``ContextManager.audit_workflow_step_failure``. + + Buyer-facing boundaries route exceptions through this helper so raw built-in messages cannot + expose secrets. The approval-service webhook still builds its own message and depends on + source-site scrubbing; route any NEW buyer-facing error surface through this policy instead of + adding a second one. + + Two ORTHOGONAL decisions, deliberately kept separate — conflating them is what leaked secrets + (a raw ``ValueError`` pre-normalized to a *trusted* ``AdCPValidationError`` whose raw message + then survived): + + 1. SEMANTIC code/recovery — from ``normalize_to_adcp_error`` (``ValueError`` → + VALIDATION_ERROR, ``PermissionError`` → AUTH_REQUIRED, native ``AdCPError`` unchanged). This + is the SAME mapping the synchronous MCP/REST/A2A boundaries apply, so a webhook audit and + the synchronous response for the SAME exception emit the SAME code — no divergence. + 2. MESSAGE trust — from the ORIGINAL exception's PROVENANCE. A raw built-in's ``str(exc)`` is + UNTRUSTED (it can embed a connection string / token / SQL) and is SCRUBBED even when its + semantic code is client-correctable; only an explicitly-raised typed ``AdCPError`` carries a + controlled buyer-facing message worth preserving. + + Concretely: + - INTERNAL/INFRA codes (``wire_error_code in INTERNAL_WIRE_CODES`` — SERVICE_UNAVAILABLE family + + terminal CONFIGURATION_ERROR): message scrubbed regardless of provenance (a typed + ``AdCPAdapterError(f"...: {e}")`` can interpolate a secret too); recovery normalized to the + wire code's canonical value; suggestion derived from that recovery. + - A wire code not in ``WIRE_STANDARD_CODES`` (internal-only): coerced to SERVICE_UNAVAILABLE and + scrubbed. + - A raw Pydantic ``ValidationError`` uses the dedicated safe projector: + static messages plus structured field paths/error types, never raw + ``msg``/``input``/``ctx`` values. + - Any other CLIENT-CORRECTABLE standard code (VALIDATION_ERROR, + ``*_NOT_FOUND``, AUTH_*, …): the message is kept ONLY when the ORIGINAL + exception is a typed ``AdCPError`` (trusted provenance); a RAW built-in + that merely *normalized* to such a code keeps the semantic code/recovery + but has its untrusted message scrubbed. + """ + # (1) SEMANTIC code/recovery — the mapping the synchronous boundaries also apply. + normalized = normalize_to_adcp_error(exc) + wire_code = normalized.wire_error_code + + if wire_code in INTERNAL_WIRE_CODES: + return _scrubbed_error( + error_code=normalized.error_code, + wire_code=wire_code, + recovery=_canonical_recovery_for(wire_code), + status_code=normalized.status_code, + context=normalized.context, + ) + if wire_code not in WIRE_STANDARD_CODES: + # An internal-only code the wire doesn't model: coerce to SERVICE_UNAVAILABLE + scrub. + return _scrubbed_error( + error_code="SERVICE_UNAVAILABLE", + wire_code="SERVICE_UNAVAILABLE", + recovery=_canonical_recovery_for("SERVICE_UNAVAILABLE"), + status_code=normalized.status_code, + context=normalized.context, + ) + # (2) MESSAGE trust — client-correctable standard code. if isinstance(exc, ValidationError): - errors = exc.errors() - return AdCPValidationError( - errors[0].get("msg") if errors else "Request failed schema validation", - field=first_validation_error_field(exc), - suggestion=VALIDATION_ERROR_SUGGESTION, - details=build_validation_error_details(errors), + # The normalization registry's Pydantic projector is intentionally + # buyer-safe and preserves all invalid field paths. Returning that + # projection retains actionable multi-field diagnostics without + # allowing raw validator messages or rejected values onto the wire. + return normalized + if isinstance(exc, AdCPValidationError) and not exc._wire_safe_message: + # Typed validation text is untrusted by default because business + # validators frequently interpolate exception/adapter internals a raise + # site never audited. ``_wire_safe_message=True`` opts in a message that + # is either static, OR built entirely from values traceable to THIS + # buyer's current request (never adapter/system internals or another + # principal's data). + # + # Grounding — this applies to ``message`` itself, not only ``details``: + # adcp/dist/schemas/3.1.1/core/error.json's own canonical worked example + # echoes the rejected value in BOTH places at once: + # {"code": "INVALID_PRICING_MODEL", + # "message": "Pricing option not found: po_prism_abandoner_cpm", + # "field": "pricing_option_id", + # "details": {"rejected_value": "po_prism_abandoner_cpm", ...}} + # ``details.rejected_value`` is documented there as "the offending value + # the buyer supplied, echoed for buyer-side diagnostic clarity" — the + # same value the example ALSO puts in ``message``. ``message`` itself has + # no documented wording constraint ("Human-readable error message" is the + # entire schema description); error-handling.mdx's only MUST-be-generic + # cases are cross-tenant resource enumeration and seller-internal + # secrets, neither of which this covers. + # + # ``details`` is withheld here DELIBERATELY, not by omission: it has the same + # provenance as ``message`` (the raise site builds both, from the same values, + # with the same absent audit), so one flag governs both channels — trusted + # together or scrubbed together. Do NOT "restore" it by forwarding + # ``normalized.details``: on this branch ``normalize_to_adcp_error`` returned + # ``exc`` itself, so that forwards the very raise-site payload this branch + # exists to withhold. ``field`` IS forwarded because it is a schema path, not + # raise-site prose. The sanctioned way to put ``details`` on the wire is to + # audit the site and opt in — then the untouched ``exc`` passes through below. + # Both halves pinned by test_wire_safe_opt_in_governs_details_and_message_together. + safe_message, safe_suggestion = _sanitized_text_for(wire_code, normalized.recovery) + return type(exc)( + safe_message, + suggestion=safe_suggestion, + retry_after=normalized.retry_after, + recovery=normalized.recovery, + context=normalized.context, + field=normalized.field, + _wire_safe_message=True, ) - if isinstance(exc, ValueError): - return AdCPValidationError(str(exc)) - if isinstance(exc, PermissionError): - return AdCPAuthorizationError(str(exc)) - return AdCPError(str(exc) or type(exc).__name__) + if isinstance(exc, AdCPError): + # Explicitly-raised typed error → controlled buyer-facing message, pass through unchanged. + return exc + # A RAW built-in that normalized to a client-correctable code: keep that SEMANTIC code/recovery + # (so webhook and synchronous responses agree) but SCRUB the untrusted ``str(exc)`` message — + # replaced with a static, category-appropriate message + suggestion (a VALIDATION_ERROR reads + # "review the submitted fields", an AUTH_REQUIRED reads "provide valid credentials"), never the + # generic "internal error" that contradicts the code. + return _scrubbed_error( + error_code=normalized.error_code, + wire_code=wire_code, + recovery=normalized.recovery, + status_code=normalized.status_code, + context=normalized.context, + field=normalized.field, + ) diff --git a/src/core/idempotency_canonical.py b/src/core/idempotency_canonical.py index 8a62569899..57aaa7a4c0 100644 --- a/src/core/idempotency_canonical.py +++ b/src/core/idempotency_canonical.py @@ -61,7 +61,9 @@ def canonical_payload_hash(payload: dict[str, Any]) -> str: except RecursionError as exc: # A pathologically nested payload must reject as a buyer error, not # crash the boundary with an unhandled RecursionError. - raise AdCPValidationError("request payload too deeply nested to canonicalize for idempotency") from exc + raise AdCPValidationError( + "request payload too deeply nested to canonicalize for idempotency", _wire_safe_message=True + ) from exc def canonical_request_hash(request: BaseModel) -> str: diff --git a/src/core/logging_config.py b/src/core/logging_config.py index d5e4eab892..8dcb8f56cf 100644 --- a/src/core/logging_config.py +++ b/src/core/logging_config.py @@ -229,11 +229,10 @@ def setup_oauth_logging() -> None: def log_safe(value: object) -> str: - """Neutralize CR/LF in request-provided values before logging. + """Neutralize CR/LF in untrusted values before logging. - Buyer-supplied ids (creative_id, package_id) flow into log lines; a - newline embedded in one would forge log entries (CodeQL py/log-injection). - Response payloads and exception messages are NOT sanitized — buyers - correlate on exact ids. + Buyer-supplied ids and downstream exception messages can flow into log + lines; a newline embedded in either would forge entries (CodeQL + py/log-injection). Structured-log redaction remains a separate concern. """ return str(value).replace("\r", "").replace("\n", "") diff --git a/src/core/mcp_auth_middleware.py b/src/core/mcp_auth_middleware.py index 070ecdaec7..7ea8e0cf17 100644 --- a/src/core/mcp_auth_middleware.py +++ b/src/core/mcp_auth_middleware.py @@ -1,6 +1,7 @@ """FastMCP middleware for centralized MCP identity resolution. -Resolves identity once per tool call and stores it on FastMCP context state. +Makes one authoritative authentication decision per tool call and stores the +resolved identity on FastMCP context state. Tool functions read the pre-resolved identity via ctx.get_state('identity') instead of calling resolve_identity_from_context() directly. """ @@ -11,21 +12,14 @@ from fastmcp.server.middleware import Middleware, MiddlewareContext from fastmcp.tools.tool import ToolResult -from src.core.transport_helpers import resolve_identity_from_context +from src.core.auth_policy import AUTH_OPTIONAL_SKILLS +from src.core.transport_helpers import extract_headers_from_context, resolve_identity_from_context logger = logging.getLogger(__name__) -# Discovery tools that work without authentication. -# All other tools require a valid auth token. -AUTH_OPTIONAL_TOOLS = frozenset( - { - "get_adcp_capabilities", - "get_products", - "list_accounts", - "list_creative_formats", - "list_authorized_properties", - } -) +# Compatibility alias for callers/tests that import the middleware policy. +# The transport-neutral object is the single source of truth. +AUTH_OPTIONAL_TOOLS = AUTH_OPTIONAL_SKILLS class MCPAuthMiddleware(Middleware): @@ -43,11 +37,58 @@ async def on_call_tool( ) -> ToolResult: tool_name = context.message.name require_auth = tool_name not in AUTH_OPTIONAL_TOOLS + headers = extract_headers_from_context(context.fastmcp_context) - identity = resolve_identity_from_context( - context.fastmcp_context, - require_valid_token=require_auth, - ) + try: + identity = resolve_identity_from_context( + context.fastmcp_context, + require_valid_token=require_auth, + ) + if require_auth and (identity is None or not identity.principal_id): + from src.core.exceptions import classify_auth_credentials_error + + raise classify_auth_credentials_error( + headers, + missing_message="Authentication required for tool invocation", + ) + except Exception as error: + # Identity resolution runs before the decorated tool body, so its + # failures cannot reach with_error_logging. Reuse both halves of the + # shared boundary path: record exactly once, then preserve the + # two-layer MCP wire contract. + from src.core.exceptions import ( + AdCPAuthenticationError, + AdCPAuthInvalidError, + AdCPAuthMissingError, + classify_auth_credentials_error, + ) + from src.core.tool_error_logging import ( + _translate_to_tool_error, + record_boundary_error, + ) + + wire_error = error + if ( + require_auth + and isinstance(error, AdCPAuthenticationError) + and not isinstance(error, (AdCPAuthMissingError, AdCPAuthInvalidError)) + ): + wire_error = classify_auth_credentials_error( + headers, + missing_message="Authentication required for tool invocation", + ) + + # A rejected request has no trusted principal. Client-controlled + # host/x-adcp-tenant headers are routing hints, not proof that the + # caller may write into that tenant's activity or audit sinks. + record_boundary_error( + "mcp", + tool_name, + error, + tenant_id=None, + principal_id=None, + ) + _translate_to_tool_error(wire_error) if context.fastmcp_context: await context.fastmcp_context.set_state("identity", identity, serializable=False) diff --git a/src/core/mcp_compat_middleware.py b/src/core/mcp_compat_middleware.py index d48285b020..27b89af3e1 100644 --- a/src/core/mcp_compat_middleware.py +++ b/src/core/mcp_compat_middleware.py @@ -16,9 +16,12 @@ from mcp.types import CallToolRequestParams from pydantic import ValidationError -from src.core.exceptions import normalize_to_adcp_error from src.core.request_compat import deep_strip_to_schema, normalize_request_params, strip_unknown_params -from src.core.tool_error_logging import _translate_to_tool_error, record_boundary_error +from src.core.tool_error_logging import ( + _translate_to_tool_error, + best_effort_boundary_identity, + record_boundary_error, +) logger = logging.getLogger(__name__) @@ -118,24 +121,21 @@ async def on_call_tool( raise exc = retry_exc - # Normalize once for the audit record, then pass the raw exception to - # _translate_to_tool_error so the emitted AdCPToolError keeps it as - # __cause__. The translator intentionally normalizes it a second time. - typed = normalize_to_adcp_error(exc) - tenant_id = None - principal_id = None + # Preserve raw exception provenance for both observability and wire + # translation. Each boundary derives the semantic VALIDATION_ERROR + # independently while scrubbing validator messages that may include + # rejected secret values. + identity = None if context.fastmcp_context is not None: try: identity = await context.fastmcp_context.get_state("identity") - if identity is not None: - tenant_id = identity.tenant_id - principal_id = identity.principal_id except Exception: logger.debug("Could not read MCP identity for validation error logging", exc_info=True) + tenant_id, principal_id = best_effort_boundary_identity(lambda: identity, transport="mcp") record_boundary_error( "mcp", tool_name, - typed, + exc, tenant_id=tenant_id, principal_id=principal_id, ) diff --git a/src/core/resolved_identity.py b/src/core/resolved_identity.py index bd04648b30..e1b9d4d54b 100644 --- a/src/core/resolved_identity.py +++ b/src/core/resolved_identity.py @@ -171,11 +171,15 @@ def resolve_identity( if principal_id is None: if require_valid_token: - from src.core.exceptions import AdCPAuthenticationError - - raise AdCPAuthenticationError( - f"Authentication token is invalid for tenant '{tenant_id or 'any'}'. " - f"The token may be expired, revoked, or associated with a different tenant.", + from src.core.exceptions import classify_auth_credentials_error + + raise classify_auth_credentials_error( + headers, + missing_message="Authentication credentials are required via the Authorization header.", + invalid_message=( + "Authentication credentials were rejected. " + "The token may be expired, revoked, or associated with a different tenant." + ), ) # For discovery endpoints, continue without auth elif not tenant_context and token_tenant: diff --git a/src/core/schema_helpers.py b/src/core/schema_helpers.py index bb96b6159e..830131f6b2 100644 --- a/src/core/schema_helpers.py +++ b/src/core/schema_helpers.py @@ -164,6 +164,7 @@ def to_brand_reference(brand: dict[str, Any] | BrandReference | str | None) -> B raise AdCPValidationError( "Invalid brand: domain is required", field="brand", + _wire_safe_message=True, ) allowed = BrandReference.model_fields.keys() ref_data = {key: value for key, value in brand.items() if key in allowed} diff --git a/src/core/schemas/_base.py b/src/core/schemas/_base.py index 88ec911157..1cc3e68225 100644 --- a/src/core/schemas/_base.py +++ b/src/core/schemas/_base.py @@ -1981,6 +1981,7 @@ def _validate_package_update_shape(cls, data: Any) -> Any: "package_id is required to identify the package being updated.", field=package_field_path("package_id"), suggestion="Include the package_id of the package you want to update.", + _wire_safe_message=True, ) present = sorted(f for f in cls._IMMUTABLE_PACKAGE_FIELDS if f in data) if present: @@ -2028,6 +2029,7 @@ def validate_idempotency_key_shape(key: str | None) -> None: "idempotency_key contains characters outside [A-Za-z0-9_.:-].", field="idempotency_key", suggestion="Use only letters, digits, and the characters _ . : -", + _wire_safe_message=True, ) diff --git a/src/core/security/url_validator.py b/src/core/security/url_validator.py index cf2f62e342..ec4a3ff731 100644 --- a/src/core/security/url_validator.py +++ b/src/core/security/url_validator.py @@ -118,6 +118,15 @@ def check_url_ssrf( hostname = parsed.hostname if not hostname: return False, "URL must have a valid hostname" + # The password operand is redundant TODAY, and is kept deliberately. Probed across + # every userinfo form urlparse accepts (`:pass@`, `user@`, `user:pass@`, bare, `@`, + # `:@`, `:p@host:port`), a non-None password always arrives with a non-None username — + # the EMPTY STRING, which is not None — so the first operand already covers it. + # Retained as belt-and-braces: this is a credential-leak boundary, the redundancy + # costs one comparison, and keeping it means the guard does not silently depend on + # that urlparse detail holding across versions. + if parsed.username is not None or parsed.password is not None: + return False, "URL must not contain embedded credentials" if hostname.lower() in BLOCKED_HOSTNAMES: return False, f"URL hostname '{hostname}' is blocked (internal/private)" diff --git a/src/core/tool_error_logging.py b/src/core/tool_error_logging.py index d125d1bf7b..354756a7a3 100644 --- a/src/core/tool_error_logging.py +++ b/src/core/tool_error_logging.py @@ -20,7 +20,8 @@ AdCPError, RecoveryHint, build_two_layer_error_envelope, - normalize_to_adcp_error, + safe_adcp_error, + synthesize_safe_adcp_error, ) from src.core.tool_context import ToolContext @@ -192,13 +193,16 @@ def record_boundary_error( ``"anonymous"`` for downstream sinks. Behavior: - 1. stdlib logger: WARNING for typed ``AdCPError`` (expected, - buyer-correctable error path), ERROR with ``exc_info=True`` for - untyped fallthrough so on-call sees the traceback. - 2. ``activity_feed.log_error`` (when ``tenant_id`` present) so the - operator UI surfaces the error in real time. + 1. privileged stdlib logger: the original message at WARNING for typed + ``AdCPError`` (expected, buyer-correctable error path), or ERROR with + ``exc_info=True`` for untyped fallthrough so on-call sees the + traceback. + 2. ``activity_feed.log_error`` (when ``tenant_id`` present) receives a + buyer-safe message so tenant dashboard/WebSocket consumers cannot + see adapter, credential, or connection details. 3. ``get_audit_logger(transport.upper(), tenant_id).log_operation`` - (when ``tenant_id`` present) for the persistent record. + receives the same safe message for the persistent record and any + downstream notification sink. All sinks are defensively wrapped — observability failures cannot replace the buyer's original error. Sink failures log at WARNING (not @@ -232,14 +236,23 @@ def record_boundary_error( # No tenant context — activity feed and audit log require tenant scoping. return + # Tenant-visible and persistent sinks are not privileged diagnostic + # channels. Typed internal errors can contain adapter responses, + # connection strings, or credentials even when their wire envelope is + # scrubbed later, so derive their fields from the same safe representation + # used at transport boundaries. The original remains in the server logger + # above for on-call diagnosis. + sink_error = safe_adcp_error(error) + sink_error_code, sink_error_message, _sink_recovery = extract_error_info(sink_error) + try: from src.services.activity_feed import activity_feed activity_feed.log_error( tenant_id=tenant_id, principal_name=principal_id or "anonymous", - error_message=f"{operation}: {error_message}", - error_code=error_code, + error_message=f"{operation}: {sink_error_message}", + error_code=sink_error_code, ) except Exception as e: logger.warning("Failed to log %s error to activity feed: %s", transport_upper, e) @@ -254,12 +267,40 @@ def record_boundary_error( principal_id=principal_id or "anonymous", adapter_id=f"{transport}_boundary", success=False, - error=error_message, + error=sink_error_message, ) except Exception as e: logger.warning("Failed to log %s error to audit log: %s", transport_upper, e) +def best_effort_boundary_identity( + resolver: Callable[[], Any], + *, + transport: str, +) -> tuple[str | None, str | None]: + """Resolve identity scope for observability without affecting the response. + + Non-authentication failures can reuse an already-permissive identity path to + enrich activity-feed and audit records. Authentication failures stay + unscoped because their client-controlled routing headers are not an + attestation of tenant ownership. Resolution failures degrade to an unscoped + server log and never replace the buyer's original error. + """ + try: + identity = resolver() + except Exception: + logger.debug("%s boundary: best-effort identity resolution failed", transport.upper(), exc_info=True) + return None, None + + principal_id = getattr(identity, "principal_id", None) + if not principal_id: + # Tenant routing hints are client-controlled. Without an authenticated + # principal they cannot authorize writes to tenant-visible activity or + # persistent audit sinks. + return None, None + return getattr(identity, "tenant_id", None), principal_id + + def _log_tool_error(tool_name: str, error: Exception, tenant_id: str | None, principal_id: str | None) -> None: """Backwards-compatible MCP wrapper for record_boundary_error. @@ -285,13 +326,9 @@ def _translate_to_tool_error(error: Exception) -> NoReturn: if isinstance(error, ToolError): # Includes AdCPToolError — already in wire shape. raise error - # Normalize untyped exceptions (ValueError, PermissionError) to typed - # AdCPError via the shared normalize_to_adcp_error() helper — same - # mapping the A2A and REST boundaries apply. The result is always an - # AdCPError; the wrap-vs-passthrough branches produce byte-identical - # AdCPToolError values, so the function unconditionally builds the - # envelope and chains the original exception for traceback fidelity. - typed = normalize_to_adcp_error(error) + # Normalize semantics and scrub untrusted raw-exception presentation + # fields through the shared buyer-facing policy used by every transport. + typed = safe_adcp_error(error) raise AdCPToolError(build_two_layer_error_envelope(typed), status_code=typed.status_code) from error @@ -449,11 +486,9 @@ def handle_tool_error(e: ToolError) -> JSONResponse: # so we copy to preserve the envelope-builder's immutability contract. return JSONResponse(status_code=e.status_code, content=dict(e.envelope)) - error_code, error_message, recovery = extract_error_info(e) - synthetic = AdCPError.synthesize( - error_message, + error_code, _error_message, _recovery = extract_error_info(e) + synthetic = synthesize_safe_adcp_error( error_code=error_code, status_code=_ERROR_CODE_TO_STATUS.get(error_code, 500), - recovery=recovery, ) return JSONResponse(status_code=synthetic.status_code, content=build_two_layer_error_envelope(synthetic)) diff --git a/src/core/tools/_media_buy_status.py b/src/core/tools/_media_buy_status.py index d5edf14bd1..44f32e22ce 100644 --- a/src/core/tools/_media_buy_status.py +++ b/src/core/tools/_media_buy_status.py @@ -96,6 +96,8 @@ "approved": "active", "ready": "active", "scheduled": "active", + "activating": "pending_start", + "activation_unknown": "pending_start", "pending_activation": "pending_start", "paused": "paused", "completed": "completed", diff --git a/src/core/tools/accounts.py b/src/core/tools/accounts.py index 659cc76d9e..8dc267fb8d 100644 --- a/src/core/tools/accounts.py +++ b/src/core/tools/accounts.py @@ -2,7 +2,7 @@ Handles account management per AdCP spec (UC-011): - Agent-scoped results (BR-RULE-054) -- Auth-optional list with empty fallback (BR-RULE-055) +- Authentication required for list and sync operations (BR-RULE-055) - Upsert by natural key (BR-RULE-056) - Atomic XOR response (BR-RULE-057) - Brand echo (BR-RULE-058) @@ -116,7 +116,9 @@ def _list_accounts_impl( ) -> ListAccountsResponse: """List accounts accessible to the authenticated agent. - Per BR-RULE-055: requires authentication, raises AUTH_REQUIRED if missing. + Per BR-RULE-055: requires authentication. This shared implementation raises + legacy AUTH_REQUIRED; transports may reject earlier with their canonical + missing/invalid credential code. Per BR-RULE-054: returns only accounts accessible to the agent. Args: @@ -437,6 +439,7 @@ def _extract_natural_key(entry: Any) -> tuple[str, str | None, str, bool | None] "Each account entry must include 'brand', 'operator', and 'billing'; " "the account-reference (settings-update) form is not supported by this seller.", recovery="correctable", + _wire_safe_message=True, ) brand_domain = brand.domain brand_id = None @@ -482,7 +485,9 @@ async def _sync_accounts_impl( # Validate non-empty accounts array if not req.accounts: - raise AdCPValidationError("accounts array must not be empty — at least one account is required.") + raise AdCPValidationError( + "accounts array must not be empty — at least one account is required.", _wire_safe_message=True + ) dry_run = bool(req.dry_run) delete_missing = bool(req.delete_missing) diff --git a/src/core/tools/creative_formats.py b/src/core/tools/creative_formats.py index 60fbc5c8f3..1e1139ea61 100644 --- a/src/core/tools/creative_formats.py +++ b/src/core/tools/creative_formats.py @@ -208,9 +208,11 @@ def _list_creative_formats_impl( except AdCPError: raise except Exception as e: + # Raw exception logged server-side only — registry init failures may carry + # infra detail (hosts, connection strings). Keep str(e) off the wire. logger.error(f"Failed to create creative agent registry: {e}", exc_info=True) raise AdCPServiceUnavailableError( - f"Creative agent registry initialization failed: {e}", + "Failed to initialize creative agent registry.", context=req.context, ) from e diff --git a/src/core/tools/creatives/_assignments.py b/src/core/tools/creatives/_assignments.py index ff4bda423a..3dc1fa88e1 100644 --- a/src/core/tools/creatives/_assignments.py +++ b/src/core/tools/creatives/_assignments.py @@ -117,7 +117,7 @@ def _process_assignments( for package_id in package_ids: # Find which media buy this package belongs to - pkg_result = assignment_repo.find_package_with_media_buy(package_id) + pkg_result = assignment_repo.find_package_with_media_buy(package_id, principal_id) media_buy_id = None actual_package_id = None diff --git a/src/core/tools/creatives/_processing.py b/src/core/tools/creatives/_processing.py index 4003b70876..be49e09966 100644 --- a/src/core/tools/creatives/_processing.py +++ b/src/core/tools/creatives/_processing.py @@ -20,17 +20,34 @@ from src.core.exceptions import AdCPConfigurationError from src.core.helpers import _extract_format_info, _validate_creative_assets -from src.core.schemas import CreativeStatusEnum, SyncCreativeResult +from src.core.schemas import CreativeStatusEnum, SyncCreativeResult, format_id_identity from src.core.validation_helpers import run_async_in_sync_context from ._assets import _build_creative_data, _extract_message_from_assets, _extract_url_from_assets if TYPE_CHECKING: from src.core.database.repositories.creative import CreativeRepository + from src.core.schemas import Format, LibraryFormatId logger = logging.getLogger(__name__) +def _find_matching_format(all_formats: list[Format], creative_format: LibraryFormatId) -> Format | None: + """Find a format by its canonical AdCP federation identity. + + ``all_formats`` is the registry's pre-fetched ``list[Format]`` (registry.list_all_formats + return type). ``creative_format`` accepts ``LibraryFormatId`` rather than the narrower + local ``FormatId`` subclass because callers pass either — e.g. ``CreativeAsset.format_id`` + is typed ``FormatReferenceStructuredObject`` (an ``adcp.types`` alias for the same + ``LibraryFormatId`` base ``Format.format_id`` also extends). + """ + target_identity = format_id_identity(creative_format) + return next( + (fmt for fmt in all_formats if format_id_identity(fmt.format_id) == target_identity), + None, + ) + + def _failed_sync_result( creative_id: str, error_msg: str, *, recovery: str | None = None, code: str = "SERVICE_UNAVAILABLE" ) -> SyncCreativeResult: @@ -69,7 +86,7 @@ def _update_existing_creative( tenant: dict[str, Any], webhook_url: str | None, context: dict[str, Any] | BaseModel | None, - all_formats: list[Any], + all_formats: list[Format], registry: Any, principal_id: str, ) -> tuple[SyncCreativeResult, bool]: @@ -189,12 +206,7 @@ def _update_existing_creative( # Use pre-fetched formats (fetched outside transaction at function start) # This avoids async HTTP calls inside savepoint - # Find matching format - format_obj = None - for fmt in all_formats: - if fmt.format_id == creative_format: - format_obj = fmt - break + format_obj = _find_matching_format(all_formats, creative_format) if format_obj and format_obj.agent_url: # Check if format is generative (has output_format_ids) @@ -474,7 +486,7 @@ def _create_new_creative( tenant: dict[str, Any], webhook_url: str | None, context: dict[str, Any] | BaseModel | None, - all_formats: list[Any], + all_formats: list[Format], registry: Any, principal_id: str, ) -> tuple[SyncCreativeResult, bool]: @@ -507,12 +519,7 @@ def _create_new_creative( # Use pre-fetched formats (fetched outside transaction at function start) # This avoids async HTTP calls inside savepoint - # Find matching format - format_obj = None - for fmt in all_formats: - if fmt.format_id == creative_format: - format_obj = fmt - break + format_obj = _find_matching_format(all_formats, creative_format) if format_obj and format_obj.agent_url: # Check if format is generative (has output_format_ids) diff --git a/src/core/tools/creatives/_validation.py b/src/core/tools/creatives/_validation.py index 85d9e95d00..7a032dfc93 100644 --- a/src/core/tools/creatives/_validation.py +++ b/src/core/tools/creatives/_validation.py @@ -92,10 +92,10 @@ def _validate_creative_input( # Additional business logic validation if not creative.name or str(creative.name).strip() == "": - raise AdCPValidationError("Creative name cannot be empty", field="name") + raise AdCPValidationError("Creative name cannot be empty", field="name", _wire_safe_message=True) if not creative.format_id: - raise AdCPValidationError("Creative format is required", field="format_id") + raise AdCPValidationError("Creative format is required", field="format_id", _wire_safe_message=True) # Use validated format (auto-upgraded from string if needed) format_value = validated_creative.format diff --git a/src/core/tools/creatives/_workflow.py b/src/core/tools/creatives/_workflow.py index 1c46ce9a72..063d4e0478 100644 --- a/src/core/tools/creatives/_workflow.py +++ b/src/core/tools/creatives/_workflow.py @@ -15,6 +15,45 @@ logger = logging.getLogger(__name__) +def _sync_step_request_data( + *, + creative_info: dict[str, Any], + format_value: Any, + status: str, + approval_mode: str, + push_notification_config: PushNotificationConfig | dict | None, + context: ContextObject | dict | None, + identity: ResolvedIdentity | None, +) -> dict[str, Any]: + """Build the ``request_data`` persisted on a creative-approval workflow step. + + One home for what a creative-approval step carries, because the readers are spread + out: the webhook payload builder reads ``protocol`` and ``context``, and the admin UI + reads the creative fields. Optional keys are OMITTED rather than written as None — + the readers test presence. + + No outer transport task id is written here. A sync creates one step per creative, so + a single ``external_task_id`` would name N rows ambiguously; ``resolve_webhook_task_id`` + therefore falls back to ``step_id`` for creative approvals. + """ + request_data: dict[str, Any] = { + "creative_id": creative_info["creative_id"], + "format": format_value, + "name": creative_info["name"], + "status": status, + "approval_mode": approval_mode, + } + # Engine's _pydantic_json_serializer handles Pydantic models in JSONB automatically. + if push_notification_config: + request_data["push_notification_config"] = push_notification_config + # Echoed back in the webhook. + if context: + request_data["context"] = context + # Drives webhook payload construction. + request_data["protocol"] = identity.protocol if identity else "mcp" + return request_data + + def _create_sync_workflow_steps( creatives_needing_approval: list[dict[str, Any]], principal_id: str, @@ -28,6 +67,10 @@ def _create_sync_workflow_steps( Creates a persistent async context and one workflow step per creative, plus ``ObjectWorkflowMapping`` records linking each creative to its step. + + ONE STEP PER CREATIVE is why no transport-level outer task id is carried in here: + a single id stamped across N steps resolves to an arbitrary one of them. Each step + is addressed by its own ``step_id``. """ from src.core.context_manager import get_context_manager @@ -71,24 +114,15 @@ def _create_sync_workflow_steps( if isinstance(format_value, BaseModel): format_value = format_value.model_dump(mode="json") - request_data_for_workflow = { - "creative_id": creative_info["creative_id"], - "format": format_value, - "name": creative_info["name"], - "status": status, - "approval_mode": approval_mode, - } - # Store push_notification_config if provided for async notification - # Engine's _pydantic_json_serializer handles Pydantic models in JSONB automatically - if push_notification_config: - request_data_for_workflow["push_notification_config"] = push_notification_config - - # Store context if provided (for echoing back in webhook) - if context: - request_data_for_workflow["context"] = context - - # Store protocol type for webhook payload creation - request_data_for_workflow["protocol"] = identity.protocol if identity else "mcp" + request_data_for_workflow = _sync_step_request_data( + creative_info=creative_info, + format_value=format_value, + status=status, + approval_mode=approval_mode, + push_notification_config=push_notification_config, + context=context, + identity=identity, + ) step = ctx_manager.create_workflow_step( context_id=persistent_ctx.context_id, diff --git a/src/core/tools/creatives/listing.py b/src/core/tools/creatives/listing.py index 3d52fe3154..5ca028d427 100644 --- a/src/core/tools/creatives/listing.py +++ b/src/core/tools/creatives/listing.py @@ -105,18 +105,20 @@ def _build_list_creatives_request( created_after_dt = datetime.fromisoformat(created_after.replace("Z", "+00:00")) except ValueError: raise AdCPValidationError( - f"Invalid created_after date format: {created_after}", + "Invalid created_after date format.", field="created_after", suggestion="Provide 'created_after' as an ISO 8601 datetime (e.g. 2026-01-01T00:00:00Z) and resend.", + _wire_safe_message=True, ) if created_before: try: created_before_dt = datetime.fromisoformat(created_before.replace("Z", "+00:00")) except ValueError: raise AdCPValidationError( - f"Invalid created_before date format: {created_before}", + "Invalid created_before date format.", field="created_before", suggestion="Provide 'created_before' as an ISO 8601 datetime (e.g. 2026-01-01T00:00:00Z) and resend.", + _wire_safe_message=True, ) # Validate sort_order is valid Literal diff --git a/src/core/tools/media_buy_create.py b/src/core/tools/media_buy_create.py index 1d185826b3..0c37acadee 100644 --- a/src/core/tools/media_buy_create.py +++ b/src/core/tools/media_buy_create.py @@ -11,11 +11,13 @@ import logging import random import secrets +import threading import time import uuid -from collections.abc import Sequence +from collections.abc import Callable, Sequence from datetime import UTC, datetime from decimal import Decimal +from functools import wraps from typing import TYPE_CHECKING, Annotated, Any, Literal, NoReturn, TypedDict, cast from urllib.parse import urlparse @@ -42,7 +44,6 @@ from src.core.database.repositories.idempotency_attempt import DEFAULT_REPLAY_TTL from src.core.exceptions import ( AdCPAdapterError, - AdCPAuthorizationError, AdCPBudgetExceededError, AdCPBudgetTooLowError, AdCPCapabilityNotSupportedError, @@ -142,6 +143,7 @@ def validate_agent_url(url: str | None) -> bool: Principal, Product, Targeting, + canonical_agent_url, ) from src.core.schemas import ( url as make_url, @@ -158,7 +160,11 @@ def validate_agent_url(url: str | None) -> bool: # Import get_product_catalog from main (after refactor) from src.core.validation_helpers import adcp_validation_boundary, format_validation_error, package_field_path -from src.core.webhook_validator import reject_unsafe_webhook_registration_url, webhook_url_for_log +from src.core.webhook_validator import ( + WebhookURLValidator, + reject_unsafe_webhook_registration_url, + webhook_url_for_log, +) from src.services.activity_feed import activity_feed from src.services.gam_product_config_service import GAMProductConfigService from src.services.targeting_capabilities import ( @@ -178,6 +184,118 @@ def validate_agent_url(url: str | None) -> bool: # See: adcp 2.12.0 changelog +def validate_push_notification_config_url( + push_notification_config: dict[str, Any] | PushNotificationConfig | None, +) -> str | None: + """Validate a protocol callback before any durable media-buy writes. + + Shared by create and update: both accept the same buyer-supplied callback, so + both must reject an unsafe one synchronously. Accepting it and never delivering + is indistinguishable to the buyer from a callback that simply never fired. + + Accepts the typed model (update carries ``req.push_notification_config``) as + well as the dict create's wrappers serialize to. + """ + if not push_notification_config: + return None + url = ( + push_notification_config.get("url") + if isinstance(push_notification_config, dict) + else push_notification_config.url + ) + if not url: + return None + # The typed model declares ``url`` as a Pydantic ``AnyUrl``, NOT a str, so the two + # entry points hand this different types for the same field: create's wrappers + # deserialize JSON into a dict of plain strings, while update passes + # ``req.push_notification_config`` through as the model. Coerce BEFORE the type + # guard — guarding ``isinstance(url, str)`` first is right for the dict path and + # rejects EVERY typed config on the update path, safe or not. A rejection-only test + # cannot catch that: it passes just as well when everything is rejected. + if not isinstance(url, str | dict | list): + url = str(url) + if not isinstance(url, str): + raise AdCPValidationError( + "Push notification URL must resolve to a public HTTPS endpoint", + field="push_notification_config.url", + _wire_safe_message=True, + ) + is_safe, _validation_error = WebhookURLValidator.validate_protocol_webhook_url(url) + if not is_safe: + raise AdCPValidationError( + "Push notification URL must resolve to a public HTTPS endpoint", + field="push_notification_config.url", + _wire_safe_message=True, + ) + return url + + +def _format_agent_compatibility_url(agent_url: object | None) -> str | None: + """Canonicalize an agent identity while accepting supported endpoint aliases. + + FormatId identity remains path-sensitive everywhere else. Create-media-buy + historically accepts an agent's base URL and its ``/mcp`` endpoint as the + same configured agent, so both registration and product compatibility must + apply that policy through this single helper. + """ + if agent_url is None: + return None + return canonical_agent_url(agent_url).removesuffix("/mcp") + + +def _format_reference_compatibility_key(agent_url: object | None, format_id: str) -> tuple[str | None, str]: + """Return the create-media-buy compatibility key for a format reference.""" + return (_format_agent_compatibility_url(agent_url), format_id) + + +def _validate_registered_format_agent( + agent_url: object, + registered_urls: frozenset[str], + *, + field: str, +) -> None: + """Apply the seller's creative-agent allowlist without disclosing its contents.""" + registered_compatibility_urls = { + compatibility_url + for registered_url in registered_urls + if (compatibility_url := _format_agent_compatibility_url(registered_url)) is not None + } + if _format_agent_compatibility_url(agent_url) not in registered_compatibility_urls: + raise AdCPInvalidRequestError( + "Creative agent is not registered.", + field=field, + suggestion="Use list_creative_formats to select a format from a registered creative agent.", + _wire_safe_message=True, + ) + + +def _validate_registered_format_agents(req: CreateMediaBuyRequest, tenant_id: str) -> None: + """Reject format references whose federation agent is not registered. + + AdCP 3.1.1 defines ``FormatId`` identity as ``(agent_url, id)``. Whether a + seller accepts a non-default agent is implementation policy (ungraded), so + this boundary emits a static INVALID_REQUEST rather than exposing registry + contents or the rejected URL. + """ + from src.core.creative_agent_registry import CreativeAgentRegistry + + format_references = [ + (package_index, format_index, format_id) + for package_index, package in enumerate(req.packages or []) + for format_index, format_id in enumerate(package.format_ids or []) + ] + if not format_references: + return + + registered_urls = CreativeAgentRegistry().get_registered_agent_urls(tenant_id) + for package_index, format_index, format_id in format_references: + _validate_registered_format_agent( + format_id.agent_url, + registered_urls, + field=f"packages[{package_index}].format_ids[{format_index}].agent_url", + ) + + def _get_creative_ids(package: AdcpPackageRequest | PackageRequest | Package | MediaPackage) -> list[str] | None: """Safely get creative_ids from a package (backward compatibility). @@ -723,7 +841,105 @@ def _build_adapter_asset_from_creative( return asset, None -def execute_approved_media_buy(media_buy_id: str, tenant_id: str) -> tuple[bool, str | None]: +def _persist_approved_execution_outcome( + execute: Callable[..., tuple[bool | None, str | None]], +) -> Callable[..., tuple[bool | None, str | None]]: + """Persist failure evidence used by workflow reconciliation.""" + + @wraps(execute) + def wrapped( + media_buy_id: str, + tenant_id: str, + *, + execution_claimed: bool = False, + ) -> tuple[bool | None, str | None]: + success, error_message = execute( + media_buy_id, + tenant_id, + execution_claimed=execution_claimed, + ) + if success is False: + from src.core.database.repositories import MediaBuyUoW + + with MediaBuyUoW(tenant_id) as uow: + assert uow.media_buys is not None + uow.media_buys.update_status(media_buy_id, "failed") + return success, error_message + + return wrapped + + +def _mark_approved_execution_unknown( + media_buy_id: str, + tenant_id: str, + error_message: str, +) -> tuple[None, str]: + """Persist a post-dispatch ambiguity without hiding the original outcome.""" + from src.core.database.repositories import MediaBuyUoW + + try: + with MediaBuyUoW(tenant_id) as uow: + assert uow.media_buys is not None + uow.media_buys.mark_approved_execution_unknown(media_buy_id) + except Exception: + # The durable pre-dispatch ``activating`` claim still prevents a + # duplicate order. Its lease-based reconciler handles a failed marker + # write once the in-flight window expires. + logger.exception( + "[APPROVAL] Could not persist ambiguous execution marker for %s", + log_safe(media_buy_id), + ) + return None, error_message + + +class _ApprovalExecutionLease: + """Renew a durable execution claim until the owning worker exits.""" + + _RENEW_INTERVAL_SECONDS = 30.0 + + def __init__(self, media_buy_id: str, tenant_id: str) -> None: + self._media_buy_id = media_buy_id + self._tenant_id = tenant_id + self._stop = threading.Event() + self._thread = threading.Thread( + target=self._run, + name=f"approval-lease-{media_buy_id}", + daemon=True, + ) + + def start(self) -> None: + self._thread.start() + + def close(self) -> None: + self._stop.set() + self._thread.join(timeout=1.0) + + def _renew_once(self) -> bool: + from src.core.database.repositories import MediaBuyUoW + + with MediaBuyUoW(self._tenant_id) as uow: + assert uow.media_buys is not None + return uow.media_buys.renew_approved_execution_lease(self._media_buy_id) + + def _run(self) -> None: + while not self._stop.wait(self._RENEW_INTERVAL_SECONDS): + try: + if not self._renew_once(): + return + except Exception: + logger.exception( + "[APPROVAL] Could not renew execution lease for %s", + log_safe(self._media_buy_id), + ) + + +@_persist_approved_execution_outcome +def execute_approved_media_buy( + media_buy_id: str, + tenant_id: str, + *, + execution_claimed: bool = False, +) -> tuple[bool | None, str | None]: """Execute adapter creation for a manually approved media buy. This function is called after a media buy has been manually approved @@ -739,7 +955,10 @@ def execute_approved_media_buy(media_buy_id: str, tenant_id: str) -> tuple[bool, tenant_id: The tenant ID for context Returns: - Tuple of (success: bool, error_message: str | None) + Tuple of (success, error_message). ``True`` means the external and + local activation completed, ``False`` means external creation was + rejected, and ``None`` means external creation succeeded but later + activation/finalization remains pending. """ from sqlalchemy import select @@ -752,7 +971,23 @@ def execute_approved_media_buy(media_buy_id: str, tenant_id: str) -> tuple[bool, from src.core.config_loader import set_current_tenant from src.core.database.models import Tenant + adapter_invoked = False + external_creation_succeeded = False + execution_lease: _ApprovalExecutionLease | None = None try: + # Claim before dispatching any irreversible adapter work. This is a + # tenant-scoped compare-and-set, so concurrent approval entry points + # cannot both create the same external order. + if not execution_claimed: + with MediaBuyUoW(tenant_id) as claim_uow: + assert claim_uow.media_buys is not None + claimed = claim_uow.media_buys.claim_approved_execution(media_buy_id) + if not claimed: + return None, "Approved media buy execution is already claimed or no longer pending" + + execution_lease = _ApprovalExecutionLease(media_buy_id, tenant_id) + execution_lease.start() + # Load tenant and set context — single UoW for all reads with MediaBuyUoW(tenant_id) as uow: # FIXME(salesagent-9f2): raw session usages below should migrate to repository methods @@ -1039,6 +1274,7 @@ def execute_approved_media_buy(media_buy_id: str, tenant_id: str) -> tuple[bool, _validate_creatives_before_adapter_call(packages, tenant_id, buy_principal_id, session=session) # Execute adapter creation (outside session to avoid conflicts) + adapter_invoked = True response = _execute_adapter_media_buy_creation( request, packages, @@ -1058,25 +1294,27 @@ def execute_approved_media_buy(media_buy_id: str, tenant_id: str) -> tuple[bool, logger.error(f"[APPROVAL] Adapter creation failed for {media_buy_id}: {error_msg}") return False, error_msg + external_creation_succeeded = True logger.info(f"[APPROVAL] Adapter creation succeeded for {media_buy_id}: {response.media_buy_id}") - # Persist adapter IDs to package_config. + # The durable ``activating`` claim was persisted before adapter + # dispatch. Persist adapter IDs now that creation is confirmed. # platform_order_id is per-buy — always write to all packages so retroactive creative # push works regardless of whether the adapter also provides per-package line-item IDs. # platform_line_item_id is per-package and only present when the adapter maps them. platform_line_item_ids = getattr(response, "_platform_line_item_ids", {}) - if response.media_buy_id: - with MediaBuyUoW(tenant_id) as uow_plids: - assert uow_plids.media_buys is not None + with MediaBuyUoW(tenant_id) as uow_external: + assert uow_external.media_buys is not None + if response.media_buy_id: _persist_adapter_package_ids( - uow_plids.media_buys, + uow_external.media_buys, media_buy_id=media_buy_id, platform_order_id=str(response.media_buy_id), platform_line_item_ids=platform_line_item_ids or None, log_label="APPROVAL", ) - else: - logger.info("[APPROVAL] Adapter returned no media_buy_id — skipping ID persistence") + else: + logger.info("[APPROVAL] Adapter returned no media_buy_id — skipping ID persistence") # Upload and associate inline creatives if any exist # This handles inline creatives that were uploaded during initial media buy creation @@ -1157,7 +1395,7 @@ def execute_approved_media_buy(media_buy_id: str, tenant_id: str) -> tuple[bool, + "\n\nAll creatives must have dimensions (width/height) and a content URL." ) logger.error(f"[APPROVAL] {error_msg}") - return False, error_msg + return _mark_approved_execution_unknown(media_buy_id, tenant_id, error_msg) if assets: logger.info(f"[APPROVAL] Uploading {len(assets)} creatives to adapter") @@ -1201,10 +1439,12 @@ def execute_approved_media_buy(media_buy_id: str, tenant_id: str) -> tuple[bool, else: logger.warning("[APPROVAL] Adapter does not support creative upload, skipping") except Exception as creative_error: - # Creative upload failed - this is critical for GAM orders + # The external order already exists. Keep the approval + # pending for reconciliation instead of recording a + # false adapter failure. error_msg = f"Failed to upload creatives to adapter: {str(creative_error)}" logger.error(f"[APPROVAL] {error_msg}", exc_info=True) - return False, error_msg + return _mark_approved_execution_unknown(media_buy_id, tenant_id, error_msg) else: logger.info(f"[APPROVAL] No creative assignments found for {media_buy_id}, skipping creative upload") @@ -1220,28 +1460,39 @@ def execute_approved_media_buy(media_buy_id: str, tenant_id: str) -> tuple[bool, if approval_success: logger.info(f"[APPROVAL] Successfully approved GAM order {response.media_buy_id}") else: - # GAM approval failed - return failure so status can be updated + # External creation already succeeded; approval remains + # incomplete but must not be terminalized as a rejection. error_msg = ( f"Failed to approve order {response.media_buy_id}, " f"it will remain in DRAFT status. This may be due to missing creatives or " f"GAM still processing inventory forecasts." ) logger.warning(f"[APPROVAL] {error_msg}") - return False, error_msg + return _mark_approved_execution_unknown(media_buy_id, tenant_id, error_msg) else: logger.info("[APPROVAL] Adapter does not support order approval, skipping") except Exception as approval_error: - # Approval exception - return failure + # External creation already succeeded; approval outcome remains + # incomplete and requires reconciliation. error_msg = f"Failed to approve order {response.media_buy_id}: {str(approval_error)}" logger.error(f"[APPROVAL] {error_msg}", exc_info=True) - return False, error_msg + return _mark_approved_execution_unknown(media_buy_id, tenant_id, error_msg) # Update media buy status to 'active' after successful adapter execution # (UC-002:437 — "updates the media buy status to active") with MediaBuyUoW(tenant_id) as uow3: assert uow3.media_buys is not None - uow3.media_buys.update_status(media_buy_id, "active") - logger.info(f"[APPROVAL] Updated media buy {media_buy_id} status to 'active'") + completed = uow3.media_buys.complete_approved_execution(media_buy_id) + if not completed: + return _mark_approved_execution_unknown( + media_buy_id, + tenant_id, + "Approved media buy execution lost its durable claim before completion", + ) + logger.info( + "[APPROVAL] Updated media buy %s status to 'active'", + log_safe(media_buy_id), + ) return True, None @@ -1249,9 +1500,20 @@ def execute_approved_media_buy(media_buy_id: str, tenant_id: str) -> tuple[bool, import traceback error_traceback = traceback.format_exc() - error_msg = f"Adapter creation failed: {str(e)}" + if external_creation_succeeded: + outcome = "Post-creation finalization failed" + elif adapter_invoked: + outcome = "Adapter creation outcome is unknown" + else: + outcome = "Adapter creation failed" + error_msg = f"{outcome}: {str(e)}" logger.error(f"[APPROVAL] {error_msg}\n{error_traceback}") + if adapter_invoked: + return _mark_approved_execution_unknown(media_buy_id, tenant_id, error_msg) return False, error_msg + finally: + if execution_lease is not None: + execution_lease.close() def push_creative_to_existing_buy( @@ -1290,7 +1552,7 @@ def push_creative_to_existing_buy( creative = uow.creatives.admin_get_by_id(creative_id) if not creative: return False, f"Creative {creative_id} not found" - if creative.status not in {"approved", "active"}: + if creative.status != "approved": return False, f"Creative {creative_id} is not approved (status={creative.status})" if (creative.data or {}).get("platform_creative_id"): @@ -1555,13 +1817,7 @@ async def _validate_and_convert_format_ids( registry = CreativeAgentRegistry() validated_format_ids = [] - # Get registered agents for this tenant - registered_agents = registry._get_tenant_agents(tenant_id) - # Normalize agent URLs for consistent comparison (strips /mcp, /a2a, /.well-known/*, trailing slashes) - # This ensures all URL variations match: "https://example.com/mcp/" -> "https://example.com" - from src.core.validation import normalize_agent_url - - registered_agent_urls = {normalize_agent_url(agent.agent_url) for agent in registered_agents} + registered_agent_urls = registry.get_registered_agent_urls(tenant_id) for idx, fmt_id in enumerate(format_ids): # STRICT ENFORCEMENT: Reject plain strings @@ -1577,8 +1833,12 @@ async def _validate_and_convert_format_ids( try: validated_fmt = FormatId.model_validate(fmt_id, from_attributes=True) except (ValueError, ValidationError) as e: + # Raw validation error logged server-side; the client message states the + # required structure without interpolating str(e). + logger.warning("Package %s, format_ids[%s]: invalid format_id structure: %s", package_idx + 1, idx, e) raise AdCPValidationError( - f"Package {package_idx + 1}, format_ids[{idx}]: Invalid format_id structure: {e}", + f"Package {package_idx + 1}, format_ids[{idx}]: Invalid format_id structure. " + f"Per AdCP spec, each format_id must be a FormatId object with {{agent_url, id}}.", ) from e agent_url = str(validated_fmt.agent_url).rstrip("/") format_id = validated_fmt.id @@ -1589,15 +1849,12 @@ async def _validate_and_convert_format_ids( f"Both agent_url and id are required. Got: agent_url={agent_url!r}, id={format_id!r}", ) - # VALIDATION: Check agent is registered - # Normalize incoming agent_url for comparison (strips /mcp, /a2a, /.well-known/*, trailing slashes) - normalized_agent_url = normalize_agent_url(agent_url) - if normalized_agent_url not in registered_agent_urls: - raise AdCPAuthorizationError( - f"Package {package_idx + 1}, format_ids[{idx}]: Creative agent not registered: {agent_url}. " - f"Registered agents: {', '.join(sorted(registered_agent_urls))}. " - f"Contact your administrator to register this creative agent.", - ) + # VALIDATION: Check the public federation identity is registered. + _validate_registered_format_agent( + agent_url, + registered_agent_urls, + field=f"packages[{package_idx}].format_ids[{idx}].agent_url", + ) # VALIDATION: Verify format exists on agent try: @@ -1611,11 +1868,13 @@ async def _validate_and_convert_format_ids( except AdCPError: raise except Exception as e: + # Raw fetch error logged server-side only (may carry upstream/network + # detail); the client message drops "Error: {e}" to avoid leaking it. logger.exception(f"Error fetching format {format_id} from {agent_url}: {e}") raise AdCPAdapterError( f"Package {package_idx + 1}, format_ids[{idx}]: Failed to verify format on agent. " - f"agent_url={agent_url}, format_id={format_id!r}. Error: {e}", - ) + f"agent_url={agent_url}, format_id={format_id!r}.", + ) from e # Format validated - add to results validated_format_ids.append({"agent_url": str(agent_url), "id": format_id}) @@ -2010,6 +2269,7 @@ async def _create_media_buy_impl( identity: ResolvedIdentity | None = None, context_id: str | None = None, raw_wire_payload: dict[str, Any] | None = None, + external_task_id: str | None = None, ) -> CreateMediaBuyResult: """Create a media buy with the specified parameters. @@ -2112,6 +2372,12 @@ async def _create_media_buy_impl( # Miss or unusable cached envelope — proceed as a fresh execution; the # MediaBuy backstop resolves any resulting duplicate to the degraded path. + # Reject an unsafe callback before ContextManager persists a context or + # workflow step. The delivery service validates again at connection time to + # cover DNS rebinding between registration and delivery. + push_notification_url = validate_push_notification_config_url(push_notification_config) + _validate_registered_format_agents(req, tenant["tenant_id"]) + # Context management and workflow step creation - create workflow step FIRST # Skip for dry_run mode (no side effects, no database writes) ctx_manager = get_context_manager() @@ -2135,6 +2401,12 @@ async def _create_media_buy_impl( workflow_metadata: dict[str, Any] = {"protocol": identity.protocol} if push_notification_config: workflow_metadata["push_notification_config"] = push_notification_config + # Persist the transport's outer async task id (opaque here — set only by the + # A2A boundary from the Task returned to the buyer) so the completion webhook + # and tasks/get can correlate to the id the BUYER holds, not the internal + # step_id. Durable so a poll survives a server restart. + if external_task_id: + workflow_metadata["external_task_id"] = external_task_id step = ctx_manager.create_workflow_step( context_id=persistent_ctx.context_id, @@ -2152,7 +2424,10 @@ async def _create_media_buy_impl( if push_notification_config: from src.core.database.repositories import PushNotificationConfigUoW - url = push_notification_config.get("url") + # The value our protocol-callback gate above already validated, so what + # gets persisted is exactly what was checked (#1697 dropped the former + # unconditional log here — the guarded one below keeps blank URLs silent). + url = push_notification_url authentication = push_notification_config.get("authentication", {}) # Match the pre-gate: whitespace-only URL must not reach upsert. @@ -2229,11 +2504,11 @@ async def _create_media_buy_impl( computed_start_time = computed_start_time.replace(tzinfo=UTC) if computed_start_time < now: - error_msg = f"Invalid start time: {req.start_time}. Start time cannot be in the past." raise AdCPInvalidRequestError( - error_msg, + "Start time cannot be in the past.", suggestion="Use a future datetime or 'asap' for immediate start.", field="start_time", + _wire_safe_message=True, ) # Validate end_time @@ -2247,11 +2522,11 @@ async def _create_media_buy_impl( computed_end_time = computed_end_time.replace(tzinfo=UTC) if computed_end_time <= computed_start_time: - error_msg = f"Invalid time range: end time ({req.end_time}) must be after start time ({req.start_time})." raise AdCPInvalidRequestError( - error_msg, + "End time must be after start time.", suggestion="Set end_time to a datetime after start_time.", field="end_time", + _wire_safe_message=True, ) # Assign computed times to local variables for use throughout the function @@ -2292,6 +2567,12 @@ async def _create_media_buy_impl( raise AdCPValidationError( error_msg, suggestion="Each package must reference a distinct product_id; remove the duplicate package or change its product_id.", + # Deliberate deviation: echoes product_ids the buyer submitted in this same + # request, not a static string. Sanctioned by adcp/dist/schemas/3.1.1/core/ + # error.json's details.rejected_value convention (echoing the buyer's own + # rejected value back "for buyer-side diagnostic clarity") — see the fuller + # citation in safe_adcp_error's AdCPValidationError branch. + _wire_safe_message=True, ) # 4. Currency-specific budget validation @@ -2643,6 +2924,13 @@ def unwrap_po(po: Any) -> Any: error_msg, suggestion="Check targeting constraints.", field="targeting_overlay", + # Deliberate deviation: all three violation sources interpolate only + # static text, fixed known dimension names, or the buyer's own + # submitted field names/values from this same request — never a + # secret or internal detail. Sanctioned by adcp/dist/schemas/3.1.1/ + # core/error.json's details.rejected_value convention; see the fuller + # citation in safe_adcp_error's AdCPValidationError branch. + _wire_safe_message=True, ) except (AdCPError, ValueError, PermissionError) as e: @@ -3276,15 +3564,12 @@ def unwrap_po(po: Any) -> Any: product_format_keys: set[tuple[str | None, str]] = set() if pkg_product.format_ids: for fmt in pkg_product.format_ids: - agent_url = fmt.agent_url - normalized_url = str(agent_url).rstrip("/") if agent_url else None - product_format_keys.add((normalized_url, fmt.id)) + product_format_keys.add(_format_reference_compatibility_key(fmt.agent_url, fmt.id)) # Build set of requested format keys for comparison requested_format_keys: set[tuple[str | None, str]] = set() for fmt in matching_package.format_ids: - normalized_url = str(fmt.agent_url).rstrip("/") if fmt.agent_url else None - requested_format_keys.add((normalized_url, fmt.id)) + requested_format_keys.add(_format_reference_compatibility_key(fmt.agent_url, fmt.id)) def format_display(url: str | None, fid: str) -> str: """Format a (url, id) pair for display, handling trailing slashes.""" @@ -3295,34 +3580,10 @@ def format_display(url: str | None, fid: str) -> str: clean_url = str(url).rstrip("/") return f"{clean_url}/{fid}" - def _has_supported_key(url: str | None, fid: str, keys: set = product_format_keys) -> bool: - """Check if (url, fid) is supported, allowing an '/mcp' URL variant. - - This does not mutate any of the underlying key sets; it only checks - for the presence of either the exact key or an alternative where - '/mcp' is appended to the end of the URL path. - - Args: - url: The format URL to check - fid: The format ID to check - keys: The set of supported (url, fid) tuples (bound at function definition) - """ - # Exact match first - if (url, fid) in keys: - return True - - # If URL provided, also try with '/mcp' appended (idempotent if already present) - if url: - # Convert to string in case it's an AnyUrl object - base = str(url).rstrip("/") - mcp_url = base if base.endswith("/mcp") else f"{base}/mcp" - if (mcp_url, fid) in keys: - return True - - return False - unsupported_formats = [ - format_display(url, fid) for url, fid in requested_format_keys if not _has_supported_key(url, fid) + format_display(url, fid) + for url, fid in requested_format_keys + if (url, fid) not in product_format_keys ] if unsupported_formats: @@ -3350,11 +3611,9 @@ def _has_supported_key(url: str | None, fid: str, keys: set = product_format_key product_format_dimensions = {} if pkg_product.format_ids: for fmt in pkg_product.format_ids: - agent_url = fmt.agent_url fmt_id = fmt.id - normalized_url = str(agent_url).rstrip("/") if agent_url else None if fmt_id: - product_format_dimensions[(normalized_url, fmt_id)] = ( + product_format_dimensions[_format_reference_compatibility_key(fmt.agent_url, fmt_id)] = ( fmt.width, fmt.height, fmt.duration_ms, @@ -3362,7 +3621,7 @@ def _has_supported_key(url: str | None, fid: str, keys: set = product_format_key # Process request format_ids, merging dimensions from product if missing for req_fmt in matching_package.format_ids: - normalized_url = str(req_fmt.agent_url).rstrip("/") if req_fmt.agent_url else None + compatibility_key = _format_reference_compatibility_key(req_fmt.agent_url, req_fmt.id) # Check if request format has dimensions if req_fmt.width is not None and req_fmt.height is not None: # Request has dimensions, convert to our FormatId type @@ -3377,7 +3636,7 @@ def _has_supported_key(url: str | None, fid: str, keys: set = product_format_key ) else: # Try to get dimensions from product's format_ids - product_dims = product_format_dimensions.get((normalized_url, req_fmt.id)) + product_dims = product_format_dimensions.get(compatibility_key) if product_dims and (product_dims[0] is not None or product_dims[1] is not None): # Merge dimensions from product format_ids_to_use.append( @@ -3506,6 +3765,7 @@ def _has_supported_key(url: str | None, fid: str, keys: set = product_format_key raise AdCPValidationError( "start_time and end_time are required but were not properly set", context=req.context, + _wire_safe_message=True, ) # PRE-VALIDATE: Check all creatives have required fields BEFORE calling adapter @@ -4317,7 +4577,10 @@ def _has_supported_key(url: str | None, fid: str, keys: set = product_format_key # Audit logging failure is non-critical, but we should log it logger.warning(f"Failed to log failed media buy creation to audit: {audit_error}") - raise AdCPAdapterError(f"Failed to create media buy: {str(e)}") + # Raw exception already logged/audited above; keep str(e) off the client + # message (may carry adapter/DB internals). A2A boundary also scrubs this + # SERVICE_UNAVAILABLE-class message; MCP/REST rely on this source scrub. + raise AdCPAdapterError("Failed to create media buy.") from e def _build_create_media_buy_request( @@ -4511,6 +4774,7 @@ async def create_media_buy_raw( ctx: Context | ToolContext | None = None, identity: ResolvedIdentity | None = None, raw_wire_payload: dict[str, Any] | None = None, + external_task_id: str | None = None, ): """Create a new media buy with specified parameters (raw function for A2A server use). @@ -4583,6 +4847,7 @@ async def create_media_buy_raw( identity=identity, context_id=_ctx_id, raw_wire_payload=raw_wire_payload, + external_task_id=external_task_id, ) diff --git a/src/core/tools/media_buy_delivery.py b/src/core/tools/media_buy_delivery.py index bbb469e6ec..dee6175475 100644 --- a/src/core/tools/media_buy_delivery.py +++ b/src/core/tools/media_buy_delivery.py @@ -52,6 +52,7 @@ def _validate_attribution_window(attribution_window: "AttributionWindow | None") "(the window spans the full campaign flight)", field="attribution_window", suggestion="interval must be 1 when unit is 'campaign'", + _wire_safe_message=True, ) @@ -217,6 +218,7 @@ def _get_media_buy_delivery_impl( field="start_date", suggestion="Set start_date to a date before end_date and resend.", context=req.context, + _wire_safe_message=True, ) else: # Default to last 30 days diff --git a/src/core/tools/media_buy_list.py b/src/core/tools/media_buy_list.py index 56db2769cc..d59f26dc5f 100644 --- a/src/core/tools/media_buy_list.py +++ b/src/core/tools/media_buy_list.py @@ -63,6 +63,7 @@ class _PackageData: from src.core.database.repositories import MediaBuyUoW from src.core.database.repositories.creative import CreativeRepository from src.core.exceptions import ( + AdCPAuthRequiredError, AdCPCapabilityNotSupportedError, AdCPValidationError, ) @@ -114,7 +115,10 @@ def _get_media_buys_impl( media_buys=[], errors=[ Error( # structural-guard: advisory: get_media_buys degrades to empty list + error, not a raise - code="AUTH_REQUIRED", message="Principal ID not found in context" + # Code taken from the typed class that owns it, not restated as a + # literal: the raise path and this degraded path must never drift. + code=AdCPAuthRequiredError._default_error_code, + message="Principal ID not found in context", ) ], ) @@ -125,7 +129,8 @@ def _get_media_buys_impl( media_buys=[], errors=[ Error( # structural-guard: advisory: get_media_buys degrades to empty list + error, not a raise - code="AUTH_REQUIRED", message=f"Principal {principal_id} not found" + code=AdCPAuthRequiredError._default_error_code, + message=f"Principal {principal_id} not found", ) ], ) @@ -451,18 +456,29 @@ def _resolve_status_filter( else: raw = [status_filter] - try: - return {MediaBuyStatus(s) for s in raw} - except ValueError as e: - # An unknown status string is a bad request, not a server fault — surface - # a clean VALIDATION_ERROR instead of letting the ValueError escape as a - # 500. (A dedicated STATUS_FILTER_INVALID_VALUE code is a separate, - # unimplemented gap; see the xfailed boundary-status-filter rows.) + # An unknown status string is a bad request, not a server fault — surface a + # clean VALIDATION_ERROR instead of letting a ValueError escape as a 500. + # (A dedicated STATUS_FILTER_INVALID_VALUE code is a separate, unimplemented + # gap; see the xfailed boundary-status-filter rows.) The message echoes the + # buyer's OWN invalid value (safe — it is client-provided input, not a server + # internal) so the error is correctable, but never interpolates a raw caught + # exception (str(e)), which could carry internals. + resolved: set[MediaBuyStatus] = set() + invalid: list[str] = [] + for s in raw: + try: + resolved.add(MediaBuyStatus(s)) + except ValueError: + invalid.append(s) + if invalid: + logger.warning("Invalid status_filter value(s): %s", invalid) + invalid_str = ", ".join(repr(v) for v in invalid) raise AdCPValidationError( - f"Invalid status_filter value: {e}", + f"Invalid status_filter value: {invalid_str} is not a valid MediaBuyStatus.", field="status_filter", suggestion="status_filter values must be valid media-buy statuses", - ) from e + ) + return resolved # Persisted MediaBuy.status -> AdCP MediaBuyStatus wire enum, DERIVED from the diff --git a/src/core/tools/media_buy_update.py b/src/core/tools/media_buy_update.py index 5aaa6899f1..2f745fe655 100644 --- a/src/core/tools/media_buy_update.py +++ b/src/core/tools/media_buy_update.py @@ -94,6 +94,7 @@ validate_max_daily_package_spend, validate_min_package_budget, ) +from src.core.tools.media_buy_create import validate_push_notification_config_url from src.core.transport_helpers import resolve_identity_from_context from src.core.utils import utc_flight_start from src.core.validation_helpers import adcp_validation_boundary, package_field_path @@ -343,10 +344,29 @@ def _verify_principal( ) +def _update_workflow_metadata(identity: ResolvedIdentity, external_task_id: str | None) -> dict[str, Any]: + """Metadata merged into the update step's ``request_data``. + + ``external_task_id`` is the buyer's outer A2A ``task_*`` id. An update that returns + ``status="submitted"`` hands the buyer that id, so it has to reach the durable step: + ``resolve_webhook_task_id`` reads exactly this key to decide whether the completion + webhook carries the buyer's id or falls back to the internal ``step_id``, and + ``tasks/cancel`` refuses outright when no durable step carries it. + + Omitted rather than written as None on MCP/REST, which have no outer task id — the + reader tests presence. + """ + metadata: dict[str, Any] = {"protocol": identity.protocol} + if external_task_id: + metadata["external_task_id"] = external_task_id + return metadata + + def _update_media_buy_impl( req: UpdateMediaBuyRequest, identity: ResolvedIdentity | None = None, context_id: str | None = None, + external_task_id: str | None = None, ) -> UpdateMediaBuyResult | UpdateMediaBuySubmitted: """Shared implementation for update_media_buy (used by both MCP and A2A). @@ -397,7 +417,7 @@ def _update_media_buy_impl( media_buy_id_to_use = req.media_buy_id if not media_buy_id_to_use: - raise AdCPValidationError("media_buy_id is required") + raise AdCPValidationError("media_buy_id is required", _wire_safe_message=True) # Verify principal owns this media buy _verify_principal(media_buy_id_to_use, identity, uow.media_buys, context=req.context) @@ -436,6 +456,12 @@ def _update_media_buy_impl( # Extract testing context early (needed for dry_run check) testing_ctx = identity.testing_context if identity.testing_context else AdCPTestContext() + # Reject an unsafe callback before ContextManager persists a context or + # workflow step — the same fence create applies, through the same validator. + # Without it an update accepts a private callback, reports success, and + # silently never delivers. + validate_push_notification_config_url(req.push_notification_config) + # Create or get persistent context and workflow step # (ctx_manager + step were hoisted before the try block so the # AdCPError / Exception handlers can mark the step as failed) @@ -466,7 +492,7 @@ def _update_media_buy_impl( status="in_progress", tool_name="update_media_buy", request_data=req, - request_metadata={"protocol": identity.protocol}, + request_metadata=_update_workflow_metadata(identity, external_task_id), ) principal = resolve_principal_or_raise(principal_id, tenant_id=identity.tenant_id, context=req.context) @@ -797,6 +823,7 @@ def _update_media_buy_impl( "package_id is required when updating package budget", field=package_field_path("package_id"), context=req.context, + _wire_safe_message=True, ) # Extract budget amount - handle both float and Budget object budget_amount: float @@ -878,6 +905,7 @@ def _update_media_buy_impl( "package_id is required when updating creative_ids", field=package_field_path("package_id"), context=req.context, + _wire_safe_message=True, ) # Resolve media_buy_id @@ -979,6 +1007,7 @@ def _update_media_buy_impl( "package_id is required when uploading creatives", field=package_field_path("package_id"), context=req.context, + _wire_safe_message=True, ) # Sync creatives (upload/update) @@ -1028,6 +1057,7 @@ def _update_media_buy_impl( "package_id is required when updating creative_assignments", field=package_field_path("package_id"), context=req.context, + _wire_safe_message=True, ) # Resolve media_buy_id @@ -1209,6 +1239,7 @@ def _update_media_buy_impl( "package_id is required when updating targeting_overlay", field=package_field_path("package_id"), context=req.context, + _wire_safe_message=True, ) from sqlalchemy.orm import attributes @@ -1513,6 +1544,7 @@ def _build_update_request( "start_time, end_time, packages, budget, push_notification_config, " "reporting_webhook, context, or ext." ), + _wire_safe_message=True, ) return req @@ -1618,6 +1650,7 @@ def update_media_buy_raw( idempotency_key: str | None = None, # AdCP idempotency key for retry safety ctx: Context | ToolContext | None = None, identity: ResolvedIdentity | None = None, + external_task_id: str | None = None, ): """Update an existing media buy (raw function for A2A server use). @@ -1670,4 +1703,4 @@ def update_media_buy_raw( identity = resolve_identity_from_context(ctx, require_valid_token=True) # A2A/REST callers pass identity directly without a FastMCP Context, so there # is no workflow context_id to forward — _impl creates one if needed. - return _update_media_buy_impl(req=req, identity=identity, context_id=None) + return _update_media_buy_impl(req=req, identity=identity, context_id=None, external_task_id=external_task_id) diff --git a/src/core/tools/products.py b/src/core/tools/products.py index 5fe0adfc65..e7496e0cee 100644 --- a/src/core/tools/products.py +++ b/src/core/tools/products.py @@ -169,7 +169,7 @@ async def _get_products_impl( # Require at least one search criterion (brief, brand, or filters) if not req.brief and not req.brand and not req.filters: - raise AdCPValidationError("At least one of 'brief', 'brand', or 'filters' is required") + raise AdCPValidationError("At least one of 'brief', 'brand', or 'filters' is required", _wire_safe_message=True) # Extract identity fields identity = require_identity(identity, context=req.context) @@ -818,9 +818,13 @@ async def get_products( ) except ValueError as e: # Helper raises ValueError for semantic (non-Pydantic) input problems. + # Log the raw exception server-side; do not interpolate str(e) into the + # wire message (boundary sanitization — the raw text may carry internals). + logger.warning("Invalid get_products request: %s", e) raise AdCPValidationError( - f"Invalid get_products request: {e}", + "Invalid get_products request.", suggestion="Correct the get_products request per the AdCP specification and resend.", + _wire_safe_message=True, ) from e # Read identity pre-resolved by MCPAuthMiddleware diff --git a/src/core/tools/properties.py b/src/core/tools/properties.py index c584af1cb2..586dd7ff42 100644 --- a/src/core/tools/properties.py +++ b/src/core/tools/properties.py @@ -187,9 +187,12 @@ def _list_authorized_properties_impl( error=str(e), ) + # Raw exception already logged/audited above; keep str(e) off the client + # message (it may carry adapter/DB internals). The A2A boundary also scrubs + # this SERVICE_UNAVAILABLE-class message, but MCP/REST rely on this source scrub. raise AdCPAdapterError( - f"Failed to list authorized properties: {str(e)}", - ) + "Failed to list authorized properties.", + ) from e async def list_authorized_properties( diff --git a/src/core/tools/signals.py b/src/core/tools/signals.py index d63085fa19..7da25643b1 100644 --- a/src/core/tools/signals.py +++ b/src/core/tools/signals.py @@ -310,8 +310,9 @@ async def _activate_signal_impl( except AdCPError: raise except Exception as e: + # Raw exception logged server-side only; keep str(e) off the client message. logger.error("Error activating signal %s: %s", signal_agent_segment_id, e) - raise AdCPAdapterError(str(e), context=context) from e + raise AdCPAdapterError("Failed to activate signal.", context=context) from e async def activate_signal( diff --git a/src/core/tools/task_management.py b/src/core/tools/task_management.py index 51b4e7f837..7bd5d4c31e 100644 --- a/src/core/tools/task_management.py +++ b/src/core/tools/task_management.py @@ -16,6 +16,7 @@ from src.core.audit_logger import get_audit_logger from src.core.auth import require_identity, require_principal_id, require_tenant from src.core.database.repositories.uow import WorkflowUoW +from src.core.database.repositories.workflow import TERMINAL_STEP_STATUSES from src.core.exceptions import ( AdCPConflictError, AdCPValidationError, @@ -37,7 +38,10 @@ async def list_tasks( """List workflow tasks with filtering options. Args: - status: Filter by task status ("pending", "in_progress", "completed", "failed", "requires_approval") + status: Filter by workflow-step status. Terminal: "completed", "rejected", "failed", + "canceled" (``TERMINAL_STEP_STATUSES``). Non-terminal: "pending", "in_progress", + "approved", "requires_approval", "pending_approval", and the legacy + awaiting-decision alias "approval". object_type: Filter by object type ("media_buy", "creative", "product") object_id: Filter by specific object ID limit: Maximum number of tasks to return (default: 20) @@ -53,18 +57,23 @@ async def list_tasks( identity = require_identity(identity) tenant = require_tenant(identity) - require_principal_id(identity) # F-03: an authenticated (non-anonymous) principal is required + principal_id = require_principal_id(identity) # F-03: an authenticated (non-anonymous) principal is required with WorkflowUoW(tenant["tenant_id"]) as uow: assert uow.workflows is not None + # Principal-scoped, not tenant-scoped: this is a buyer-facing tool, so a sibling + # principal in the same tenant must not see another buyer's task ids or summaries. + # The count carries the same scope as the page, or the total leaks their existence. total = uow.workflows.count_by_tenant( + principal_id=principal_id, status=status, object_type=object_type, object_id=object_id, ) tasks = uow.workflows.list_by_tenant( + principal_id=principal_id, status=status, object_type=object_type, object_id=object_id, @@ -139,12 +148,14 @@ async def get_task( identity = require_identity(identity) tenant = require_tenant(identity) - require_principal_id(identity) # F-03: an authenticated (non-anonymous) principal is required + principal_id = require_principal_id(identity) # F-03: an authenticated (non-anonymous) principal is required with WorkflowUoW(tenant["tenant_id"]) as uow: assert uow.workflows is not None - task = uow.workflows.get_by_step_id_or_raise(task_id) + # Principal-scoped: a sibling principal who learns this task id must not read its + # stored response_data. Reported not-found, like any unknown id. + task = uow.workflows.get_by_step_id_or_raise(task_id, principal_id=principal_id) mappings = uow.workflows.get_mappings_for_step(task_id) @@ -215,22 +226,36 @@ async def complete_task( with WorkflowUoW(tenant["tenant_id"]) as uow: assert uow.workflows is not None - task = uow.workflows.get_by_step_id_or_raise(task_id) - - if task.status not in ["pending", "in_progress", "requires_approval"]: + # Principal-scoped: a sibling principal must not be able to complete or fail + # another buyer's task. This fetch gates reachability for the transition below — + # a step this principal does not own raises not-found before any write is + # attempted, so ``transition_if_nonterminal`` needs no separate scope. + task = uow.workflows.get_by_step_id_or_raise(task_id, principal_id=principal_id) + + # Derived from the canonical terminal set, not a hand-listed positive set: a + # literal enumerating the states that MAY complete silently omits every + # non-terminal state it forgot — it omitted ``pending_approval`` and the legacy + # ``approval`` alias, so this pre-check refused steps the authoritative guard + # (``transition_if_nonterminal``, which keys on ``TERMINAL_STEP_STATUSES``) accepts. + if task.status in TERMINAL_STEP_STATUSES: raise AdCPConflictError(f"Task {task_id} is already {task.status} and cannot be completed") completed_time = datetime.now(UTC) + # transition_if_nonterminal returns None if the step was concurrently + # terminalized (e.g. a buyer cancel committed between the read above and this + # write). The pre-check is a non-atomic hint; this None check is the + # authoritative guard. A lost transition must NOT be reported as a successful + # completion. if status == "completed": - uow.workflows.update_status( + updated = uow.workflows.transition_if_nonterminal( task_id, status=status, completed_at=completed_time, response_data=response_data or {"manually_completed": True, "completed_by": principal_id}, ) else: - uow.workflows.update_status( + updated = uow.workflows.transition_if_nonterminal( task_id, status=status, completed_at=completed_time, @@ -238,6 +263,11 @@ async def complete_task( response_data=response_data, ) + if updated is None: + raise AdCPConflictError( + f"Task {task_id} was concurrently finalized (e.g. canceled) and cannot be marked {status}" + ) + audit_logger = get_audit_logger("task_management", tenant["tenant_id"]) audit_logger.log_operation( operation="complete_task", diff --git a/src/core/transport_helpers.py b/src/core/transport_helpers.py index bcb86658eb..195e414a9b 100644 --- a/src/core/transport_helpers.py +++ b/src/core/transport_helpers.py @@ -34,6 +34,23 @@ def _make_lazy_tenant(tenant_id: str) -> LazyTenantContext: return LazyTenantContext(tenant_id) +def extract_headers_from_context(ctx: Context | ToolContext | None) -> dict[str, str]: + """Read request headers once from FastMCP dependencies or context fallback.""" + headers = None + try: + headers = get_http_headers(include_all=True) + except Exception: + logger.debug("get_http_headers() unavailable, trying fallback", exc_info=True) + + if not headers and ctx is not None: + if hasattr(ctx, "meta") and ctx.meta and "headers" in ctx.meta: + headers = ctx.meta["headers"] + elif hasattr(ctx, "headers"): + headers = ctx.headers + + return dict(headers or {}) + + def resolve_identity_from_context( ctx: Context | ToolContext | None, require_valid_token: bool = True, @@ -66,18 +83,7 @@ def resolve_identity_from_context( ) # Handle FastMCP Context — extract headers and resolve - headers = None - try: - headers = get_http_headers(include_all=True) - except Exception: - logger.debug("get_http_headers() unavailable, trying fallback", exc_info=True) - - # Fallback to context.meta if available - if not headers and ctx is not None: - if hasattr(ctx, "meta") and ctx.meta and "headers" in ctx.meta: - headers = ctx.meta["headers"] - elif hasattr(ctx, "headers"): - headers = ctx.headers + headers = extract_headers_from_context(ctx) if not headers: if ctx is None: diff --git a/src/core/validation_helpers.py b/src/core/validation_helpers.py index 615f97d7da..7b1c7729a4 100644 --- a/src/core/validation_helpers.py +++ b/src/core/validation_helpers.py @@ -14,8 +14,11 @@ from pydantic import ValidationError from src.core.exceptions import ( + VALIDATION_ERROR_SUGGESTION, AdCPValidationError, build_validation_error_details, + safe_validation_error_location, + safe_validation_error_message, ) from src.core.exceptions import ( first_validation_error_field as first_validation_error_field, @@ -56,6 +59,7 @@ def adcp_validation_boundary(context: str = "parameters", field: str | None = No field=field if field is not None else first_validation_error_field(e), suggestion=suggest_validation_fix(e), details=build_validation_error_details(errors), + _wire_safe_message=True, ) from e @@ -180,38 +184,8 @@ def format_validation_error(validation_error: ValidationError, context: str = "r """ error_details = [] for error in validation_error.errors(): - field_path = ".".join(str(loc) for loc in error["loc"]) - error_type = error["type"] - msg = error["msg"] - input_val = error.get("input") - - # Add helpful context for common validation errors - if "string_type" in error_type and isinstance(input_val, dict): - error_details.append( - f" • {field_path}: Expected string, got object. " - f"AdCP spec requires this field to be a simple string, not a structured object." - ) - elif "string_type" in error_type: - error_details.append( - f" • {field_path}: Expected string, got {type(input_val).__name__}. Please provide a string value." - ) - elif "missing" in error_type: - error_details.append(f" • {field_path}: Required field is missing") - elif "extra_forbidden" in error_type: - # For extra_forbidden, show the actual value to help debug what was passed - if input_val is not None: - # Format the input value more verbosely for debugging - try: - input_repr = json.dumps(input_val, indent=2, default=str) - except (TypeError, ValueError): - input_repr = repr(input_val) - error_details.append( - f" • {field_path}: Extra field not allowed by AdCP spec.\n Received value: {input_repr}" - ) - else: - error_details.append(f" • {field_path}: Extra field not allowed by AdCP spec") - else: - error_details.append(f" • {field_path}: {msg}") + field_path = ".".join(str(loc) for loc in safe_validation_error_location(error)) + error_details.append(f" • {field_path}: {safe_validation_error_message(error)}") error_msg = ( f"Invalid {context}: The following fields do not match the AdCP specification:\n\n" @@ -223,31 +197,13 @@ def format_validation_error(validation_error: ValidationError, context: str = "r def suggest_validation_fix(validation_error: ValidationError) -> str: - """Derive a single buyer-facing correction hint from a Pydantic ValidationError. - - Produces the actionable ``suggestion`` companion to - ``format_validation_error``'s diagnostic message, so request-validation - rejections carry a non-empty wire ``suggestion`` (AdCP POST-F3: the buyer - must learn how to fix the request). The hint names the offending field(s) - and the corrective action, keyed off the Pydantic error ``type``: - - * ``missing`` → provide the required field - * ``string_pattern_mismatch`` / ``string_too_short`` / ``string_too_long`` → fix the value to satisfy the constraint - * ``extra_forbidden`` → remove the unrecognized field - * anything else → correct the field per the AdCP spec + """Return AdCP 3.1.1's canonical validation recovery guidance. + + Field-specific diagnostics remain available in ``message``, ``field``, and + ``details.validation_errors``. The top-level suggestion is protocol + metadata and must not drift by Pydantic error type or transport. """ - errors = validation_error.errors() - if not errors: - return "Correct the request to match the AdCP specification and resend." - - first = errors[0] - field_path = ".".join(str(loc) for loc in first.get("loc", ())) or "request" - error_type = first.get("type", "") - - if "missing" in error_type: - return f"Provide the required '{field_path}' field and resend the request." - if "extra_forbidden" in error_type: - return f"Remove the unrecognized '{field_path}' field; it is not part of the AdCP request schema." - if error_type.startswith("string_pattern_mismatch") or "too_short" in error_type or "too_long" in error_type: - return f"Provide a valid '{field_path}' value that satisfies the AdCP field constraints and resend." - return f"Correct the '{field_path}' field to match the AdCP specification and resend." + # Keep the parameter in the shared boundary API: callers provide the + # ValidationError whose safe diagnostics are projected separately. + del validation_error + return VALIDATION_ERROR_SUGGESTION diff --git a/src/core/webhook_validator.py b/src/core/webhook_validator.py index 624007885f..7302f195be 100644 --- a/src/core/webhook_validator.py +++ b/src/core/webhook_validator.py @@ -75,6 +75,20 @@ def validate_webhook_task_type(task_type: str, fallback: str = WEBHOOK_TASK_TYPE return task_type +def resolve_webhook_task_id(request_data: dict[str, Any] | str | None, step_id: str) -> str: + """Return the buyer-visible task id, falling back for legacy workflow rows. + + A2A persists its outer task id in ``request_data.external_task_id``. MCP/REST + workflows and older A2A rows do not have that field and continue to use the + internal workflow step id. + """ + if isinstance(request_data, dict): + external_task_id = request_data.get("external_task_id") + if isinstance(external_task_id, str) and external_task_id: + return external_task_id + return step_id + + def webhook_ssrf_suggestion() -> str: """Buyer-facing suggestion for registration/outbound SSRF rejections.""" if _strict_mode(): @@ -161,6 +175,40 @@ def _require_https() -> bool: """Production requires HTTPS; ADCP_TESTING keeps HTTP for capture servers.""" return _strict_mode() + @staticmethod + def _require_https_for_webhook() -> bool: + """The ONE scheme rule for AdCP protocol callbacks — registration and delivery. + + Require HTTPS unless the deployment says EXPLICITLY that it is development. + Both gates read this, so they cannot disagree about the scheme the way they + previously did (registration on ``_require_https()``, delivery on + ``ENVIRONMENT == "development"``), which on the default stack let an ``http://`` + reporting webhook register with a success response and then silently never + deliver. + + Spec: ``dist/docs/3.1.1/building/by-layer/L1/security.mdx`` requires sellers to + "Reject non-HTTPS URLs in production" (§Counterparty-supplied URLs, item 1) and + to enforce "URL parsing, HTTPS, hostname normalization, and reserved-range + rejection **at write time**" — i.e. at registration, not only at delivery. + + FAIL-SAFE ON UNKNOWN, which is the part two earlier versions of this rule got + wrong in opposite directions. Keying on ``is_production()`` (a literal ``== + "production"`` compare) made ``prod``, ``staging``, ``test`` and unset all + permissive — an ops team writing ``ENVIRONMENT=prod`` would have shipped plaintext + delivery of callbacks carrying Bearer credentials. Keying on ``_strict_mode()`` + lets ``ADCP_TESTING`` downgrade a production deployment. Only an explicit + ``development`` relaxes this; anything unrecognised is strict, so a typo fails + closed rather than open. + + The permissive case must therefore be DECLARED: ``docker-compose.e2e.yml`` sets + ``ENVIRONMENT: development`` already, and ``docker-compose.yml`` now does too. A + deployment that declares nothing gets HTTPS enforcement at BOTH gates, so the + buyer receives an explicit registration rejection instead of a silent delivery + failure. This is the SCHEME axis of the same single-definition fix + ``_matches_development_test_host`` applies to the HOST axis. + """ + return os.getenv("ENVIRONMENT", "").strip().lower() != "development" + @classmethod def validate_webhook_url(cls, url: str) -> tuple[bool, str]: """ @@ -174,6 +222,44 @@ def validate_webhook_url(cls, url: str) -> tuple[bool, str]: """ return check_url_ssrf(url, require_https=cls._require_https()) + @staticmethod + def _matches_development_test_host(url: str) -> bool: + """True iff ``url`` is the ONE development-only callback host the seam admits. + + One TERM of the host rule, not the whole rule. Read on its own this helper + only guarantees the two gates agree about the development test host; the + ``ADCP_TESTING`` loopback allowance is a second term, applied at registration + and NOT at protocol delivery. So the symmetry this docstring used to claim — + "a host admissible for delivery is admissible to register and vice versa" — + does not hold: measured across ENVIRONMENT x ADCP_TESTING x URL, 5 of 32 + combinations register a callback that delivery then refuses. The direction is + fail-safe (silent non-delivery, not an SSRF hole) and closing it is tracked + separately, because the two gates are not interchangeable: this same protocol + validator is also the buyer-supplied callback gate in create_media_buy, so + relaxing it to match registration would widen an SSRF boundary. + + Inert outside ``ENVIRONMENT=development``: in production this returns False + before reading anything else, so no seam can widen the production gate. + Admits exactly one hostname (the configured value), http/https only, and + never a URL carrying credentials — arbitrary private hosts stay blocked. + """ + if os.getenv("ENVIRONMENT", "").lower() != "development": + return False + test_host = os.getenv("ADCP_WEBHOOK_TEST_HOST") + if not test_host: + return False + parsed = urlparse(url) + try: + _port = parsed.port # malformed port raises here, not at comparison time + except ValueError: + return False + return ( + parsed.hostname == test_host + and parsed.scheme in {"http", "https"} + and parsed.username is None + and parsed.password is None + ) + @classmethod def validate_webhook_url_registration(cls, url: str) -> tuple[bool, str]: """Registration-time SSRF gate (no DNS required). @@ -183,21 +269,73 @@ def validate_webhook_url_registration(cls, url: str) -> tuple[bool, str]: (``validate_outbound_webhook_url``). When ``ADCP_TESTING=true``, localhost/loopback are allowed for capture servers. Production requires HTTPS. + + Also honors the development-only test-host seam (see + ``_matches_development_test_host``): the E2E stack's callback host must be + admissible at REGISTRATION as well as at delivery, or the capture server + can never be registered in the first place. Both E2E modes pair the + emitted callback host with this allowed host — ``tests`` in-network + (docker-compose.e2e.yml), ``host.docker.internal`` standalone + (tests/e2e/conftest.py). """ allow_localhost = _adcp_testing() is_valid, error = check_url_ssrf( url, resolve_dns=False, - require_https=cls._require_https(), + require_https=cls._require_https_for_webhook(), ) - return cls._maybe_allow_localhost(is_valid, error, allow_localhost=allow_localhost) + is_valid, error = cls._maybe_allow_localhost(is_valid, error, allow_localhost=allow_localhost) + if is_valid: + return True, "" + if cls._matches_development_test_host(url): + return True, "" + return False, error @classmethod def validate_outbound_webhook_url(cls, url: str) -> tuple[bool, str]: - """Send-time SSRF gate (full DNS), with localhost allowance under ADCP_TESTING.""" - if _adcp_testing(): - return cls.validate_for_testing(url, allow_localhost=True) - return cls.validate_webhook_url(url) + """Send-time SSRF gate (full DNS) for APPLICATION webhook delivery. + + Reads the same ``_require_https_for_webhook`` policy as the AdCP callback gates, + so the scheme decision is one rule across all three delivery sinks. It previously + short-circuited to ``validate_for_testing`` whenever ``ADCP_TESTING`` was set, + which dropped HTTPS enforcement entirely — including in production. That left the + "a testing flag must not downgrade a deployment" property holding at 1 of the 3 + sinks that can deliver the SAME buyer URL with the SAME Bearer token + (``protocol_webhook_service`` had it; ``webhook_delivery_service`` and + ``order_approval_service``, both reaching here via + ``reject_unsafe_outbound_webhook_url``, did not). + + ``ADCP_TESTING`` still governs the HOST axis — capture servers on localhost — + because that is what the flag is for. It no longer governs the SCHEME axis, which + is a deployment property. + """ + is_valid, error = check_url_ssrf(url, require_https=cls._require_https_for_webhook()) + return cls._maybe_allow_localhost(is_valid, error, allow_localhost=_adcp_testing()) + + @classmethod + def validate_protocol_webhook_url(cls, url: str) -> tuple[bool, str]: + """Validate a protocol callback, with one explicit in-network test seam. + + Production callbacks require HTTPS because notification payloads and + legacy Bearer credentials must not cross a plaintext connection. The + E2E Docker stack may use HTTP only for its exact runner hostname while + in development mode so delivery can be exercised without a public + relay. Arbitrary private hosts are never enabled by this seam. + + The HTTPS decision is ``_require_https_for_webhook()``, shared with the + registration gate so the two cannot disagree about the SCHEME — exactly as + ``_matches_development_test_host`` stops them disagreeing about the HOST. + See that helper for the divergence this closed and for why the rule keys on + ``is_production()`` rather than on ``_strict_mode()``. + """ + is_valid, error = check_url_ssrf(url, require_https=cls._require_https_for_webhook()) + if is_valid: + return True, "" + # Same seam definition the registration gate uses — one source of truth, so + # a host admissible for delivery is admissible to register and vice versa. + if cls._matches_development_test_host(url): + return True, "" + return False, error @classmethod def validate_for_testing(cls, url: str, allow_localhost: bool = False) -> tuple[bool, str]: diff --git a/src/core/workflow_finalization.py b/src/core/workflow_finalization.py new file mode 100644 index 0000000000..c3b243c40f --- /dev/null +++ b/src/core/workflow_finalization.py @@ -0,0 +1,682 @@ +"""Shared terminalization for manually approved media-buy workflow steps.""" + +from __future__ import annotations + +import logging +import time +from collections.abc import Callable +from dataclasses import dataclass +from datetime import UTC, date, datetime, timedelta +from enum import StrEnum +from types import SimpleNamespace +from typing import TYPE_CHECKING, Any, cast + +from adcp.types import ContextObject +from sqlalchemy.exc import SQLAlchemyError + +from src.core.database.repositories import ApprovalUoW, WorkflowUoW +from src.core.database.repositories.creative import CreativeAssignmentRepository, CreativeRepository +from src.core.database.repositories.media_buy import ( + ApprovalTrigger, + MediaBuyRepository, + execution_source_statuses_for, +) +from src.core.exceptions import build_two_layer_error_envelope, safe_adcp_error +from src.core.schemas import CreateMediaBuySuccess, Package +from src.core.tools._media_buy_status import resolve_canonical_status + +if TYPE_CHECKING: + from src.core.database.models import WorkflowStep + +logger = logging.getLogger(__name__) + +_FINALIZATION_ATTEMPTS = 3 +_FINALIZATION_RETRY_DELAY_SECONDS = 0.05 +_APPROVAL_EXECUTION_LEASE = timedelta(minutes=15) +_RECOVERABLE_SUCCESS_STATUSES = frozenset({"active", "scheduled", "completed"}) + + +def _retryable_database_error(exc: BaseException) -> bool: + return isinstance(exc, SQLAlchemyError) or ( + isinstance(exc, RuntimeError) and str(exc).startswith("Database is unhealthy") + ) + + +@dataclass(frozen=True) +class ApprovalFinalization: + """Outcome of the terminal compare-and-set after external execution.""" + + applied: bool + result: CreateMediaBuySuccess | None = None + + +class ApprovalExecutionStatus(StrEnum): + """Business states returned by the shared approval execution flow.""" + + READY = "ready" + WAITING_FOR_CREATIVES = "waiting_for_creatives" + NOT_EXECUTABLE = "not_executable" + CLAIM_REFUSED = "claim_refused" + PENDING_RECONCILIATION = "pending_reconciliation" + FAILED = "failed" + SUCCEEDED = "succeeded" + FINALIZATION_FAILED = "finalization_failed" + + +@dataclass(frozen=True) +class ApprovalExecutionOutcome: + """Typed outcome rendered independently by each admin transport.""" + + status: ApprovalExecutionStatus + finalization: ApprovalFinalization | None = None + error_message: str | None = None + blocking_creative_ids: tuple[str, ...] = () + + +@dataclass(frozen=True) +class _ApprovalTerminalPayload: + """Values persisted by one terminal workflow transition.""" + + status: str + response_data: dict[str, Any] + stored_error: str | None + result: CreateMediaBuySuccess | None + + +@dataclass(frozen=True) +class _ApprovalRecoveryState: + """Durable domain state used to reconcile a claimed approval.""" + + step_id: str + request_data: dict[str, Any] + media_buy_status: str + media_buy_updated_at: datetime | None + + +def _run_database_operation_with_retries[T]( + operation: Callable[[], T], + *, + retry_message: str, + exhausted_message: str, +) -> T | None: + """Retry one database-only operation without repeating external work. + + ``exhausted_message`` is REQUIRED and the exhausting exception is logged with it. + Exhaustion returns the same ``None`` a legitimate "nothing to reconcile" returns, so + without a message at every call site the two outcomes are indistinguishable in the + log — and this module exists to recover approvals after a database outage, which + makes its own outage path the one that must not be silent. + """ + for attempt in range(1, _FINALIZATION_ATTEMPTS + 1): + try: + return operation() + except (SQLAlchemyError, RuntimeError) as exc: + if not _retryable_database_error(exc): + raise + if attempt == _FINALIZATION_ATTEMPTS: + logger.error(exhausted_message, exc_info=exc) + return None + logger.warning(retry_message, attempt) + time.sleep(_FINALIZATION_RETRY_DELAY_SECONDS * (2 ** (attempt - 1))) + return None + + +def _approval_terminal_payload( + *, + uow: ApprovalUoW, + media_buy_id: str | None, + succeeded: bool, + error_message: str | None, + context: ContextObject | dict[str, Any] | None, +) -> _ApprovalTerminalPayload: + """Build the safe response and result stored by a terminal transition.""" + assert uow.media_buys is not None + if succeeded: + result: CreateMediaBuySuccess | None = None + response_data: dict[str, Any] = {"approved": True} + if media_buy_id is not None: + packages = uow.media_buys.get_packages(media_buy_id) + result = CreateMediaBuySuccess.sync_success( + media_buy_id=media_buy_id, + packages=[Package(package_id=package.package_id) for package in packages], + context=context, + ) + response_data = result.model_dump(mode="json", exclude_none=True) + return _ApprovalTerminalPayload("completed", response_data, None, result) + + source = safe_adcp_error(RuntimeError(error_message or "Approved media buy execution failed")) + return _ApprovalTerminalPayload( + "failed", + build_two_layer_error_envelope(source), + source.message, + None, + ) + + +def _unknown_execution_claim_result( + *, + uow: ApprovalUoW, + step_id: str, + media_buy_id: str | None, + mark_media_buy_unknown: bool, + media_buy_expected_updated_at: datetime | None, +) -> ApprovalFinalization | None: + """Claim an expired execution lease before publishing a failed task.""" + if not mark_media_buy_unknown or media_buy_id is None: + return None + assert uow.media_buys is not None + assert uow.workflows is not None + if uow.media_buys.mark_approved_execution_unknown( + media_buy_id, + expected_updated_at=media_buy_expected_updated_at, + ): + return None + + existing = uow.workflows.get_by_step_id(step_id) + already_failed = existing is not None and existing.status == "failed" and existing.response_data + return ApprovalFinalization(applied=bool(already_failed)) + + +def _existing_terminal_finalization( + *, + existing: WorkflowStep | None, + expected_status: str, + succeeded: bool, + media_buy_id: str | None, +) -> ApprovalFinalization: + """Return an idempotent result for a transition another worker completed.""" + if existing is not None and existing.status == expected_status and existing.response_data: + if not succeeded or media_buy_id is None: + return ApprovalFinalization(applied=True) + stored_result = CreateMediaBuySuccess.model_validate(existing.response_data) + if stored_result.media_buy_id == media_buy_id: + return ApprovalFinalization(applied=True, result=stored_result) + return ApprovalFinalization(applied=False) + if existing is not None and existing.status == "approved": + raise SQLAlchemyError("approval finalization did not reach a terminal state") + return ApprovalFinalization(applied=False) + + +def _finalize_media_buy_approval_once( + *, + tenant_id: str, + step_id: str, + media_buy_id: str | None, + succeeded: bool, + error_message: str | None, + context: ContextObject | dict[str, Any] | None, + mark_media_buy_failed: bool, + mark_media_buy_unknown: bool, + media_buy_expected_updated_at: datetime | None, + apply_flight_status: bool, +) -> ApprovalFinalization: + """Attempt one atomic terminal transition in a fresh UoW.""" + with ApprovalUoW(tenant_id) as uow: + assert uow.workflows is not None + assert uow.media_buys is not None + claim_result = _unknown_execution_claim_result( + uow=uow, + step_id=step_id, + media_buy_id=media_buy_id, + mark_media_buy_unknown=mark_media_buy_unknown, + media_buy_expected_updated_at=media_buy_expected_updated_at, + ) + if claim_result is not None: + return claim_result + + payload = _approval_terminal_payload( + uow=uow, + media_buy_id=media_buy_id, + succeeded=succeeded, + error_message=error_message, + context=context, + ) + transitioned = uow.workflows.transition_if_nonterminal( + step_id, + status=payload.status, + completed_at=datetime.now(UTC), + response_data=payload.response_data, + error_message=payload.stored_error, + ) + if transitioned is None: + return _existing_terminal_finalization( + existing=uow.workflows.get_by_step_id(step_id), + expected_status=payload.status, + succeeded=succeeded, + media_buy_id=media_buy_id, + ) + if not succeeded and media_buy_id is not None and mark_media_buy_failed and not mark_media_buy_unknown: + uow.media_buys.update_status(media_buy_id, "failed") + elif succeeded and media_buy_id is not None and apply_flight_status: + media_buy = uow.media_buys.get_by_id(media_buy_id) + if media_buy is None: + raise SQLAlchemyError("approved media buy disappeared during terminal finalization") + uow.media_buys.update_status( + media_buy_id, + media_buy_status_from_flight_dates( + start_time=media_buy.start_time, + end_time=media_buy.end_time, + start_date=cast(date, media_buy.start_date), + end_date=cast(date, media_buy.end_date), + ), + ) + return ApprovalFinalization(applied=True, result=payload.result) + + +def finalize_media_buy_approval_step( + *, + tenant_id: str, + step_id: str, + media_buy_id: str | None, + succeeded: bool, + error_message: str | None = None, + context: ContextObject | dict[str, Any] | None = None, + mark_media_buy_failed: bool = True, + mark_media_buy_unknown: bool = False, + media_buy_expected_updated_at: datetime | None = None, + apply_flight_status: bool = False, +) -> ApprovalFinalization: + """Persist the durable terminal outcome of an approval execution. + + The adapter runs in its own UoW, so this helper accepts scalars only and + opens a fresh session. Workflow status, failure-domain status, and stored + response are committed together. The repository's terminal guard ensures + an already-finalized decision is never overwritten. + """ + + def operation() -> ApprovalFinalization: + return _finalize_media_buy_approval_once( + tenant_id=tenant_id, + step_id=step_id, + media_buy_id=media_buy_id, + succeeded=succeeded, + error_message=error_message, + context=context, + mark_media_buy_failed=mark_media_buy_failed, + mark_media_buy_unknown=mark_media_buy_unknown, + media_buy_expected_updated_at=media_buy_expected_updated_at, + apply_flight_status=apply_flight_status, + ) + + result = _run_database_operation_with_retries( + operation, + retry_message=( + "Approval finalization transaction failed; retrying without re-running the adapter (attempt %s)" + ), + exhausted_message=( + "Approval finalization remains pending after bounded retries; " + "tasks/get reconciliation will retry from persisted domain state" + ), + ) + return result or ApprovalFinalization(applied=False) + + +def _claimed_approval_step( + tenant_id: str, + media_buy_id: str, +) -> tuple[str, dict[str, Any]] | None: + """Load the claimed approval needed for creative-unblock finalization.""" + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows is not None + step = uow.workflows.get_claimed_create_approval_step_for_media_buy(media_buy_id) + if step is None: + return None + request_data = dict(step.request_data) if isinstance(step.request_data, dict) else {} + return step.step_id, request_data + + +def finalize_latest_media_buy_approval_step( + *, + tenant_id: str, + media_buy_id: str, + succeeded: bool, + error_message: str | None = None, + apply_flight_status: bool = False, +) -> ApprovalFinalization: + """Finalize the latest claimed approval mapped to a creative-unblocked buy.""" + claimed = _run_database_operation_with_retries( + lambda: _claimed_approval_step(tenant_id, media_buy_id), + retry_message="Claimed approval lookup failed; retrying (attempt %s)", + exhausted_message=( + f"Claimed approval lookup exhausted retries for media buy {media_buy_id} " + f"(tenant {tenant_id}); the approval was NOT finalized and needs reconciliation" + ), + ) + if claimed is None: + return ApprovalFinalization(applied=False) + step_id, request_data = claimed + + return finalize_media_buy_approval_step( + tenant_id=tenant_id, + step_id=step_id, + media_buy_id=media_buy_id, + succeeded=succeeded, + error_message=error_message, + context=request_data.get("context") if isinstance(request_data.get("context"), dict) else None, + apply_flight_status=apply_flight_status, + ) + + +def media_buy_status_from_flight_dates( + *, + start_time: datetime | None, + end_time: datetime | None, + start_date: date | None, + end_date: date | None, + now: datetime | None = None, +) -> str: + """Resolve an approved buy's persisted flight status through the canonical lifecycle resolver.""" + current = now or datetime.now(UTC) + current_utc = current.replace(tzinfo=UTC) if current.tzinfo is None else current.astimezone(UTC) + + def normalize_utc(value: datetime | None) -> datetime | None: + if value is None: + return None + return value.replace(tzinfo=UTC) if value.tzinfo is None else value.astimezone(UTC) + + flight = SimpleNamespace( + status="active", + start_time=normalize_utc(start_time), + end_time=normalize_utc(end_time), + start_date=start_date, + end_date=end_date, + is_paused=False, + ) + canonical = resolve_canonical_status(flight, current_utc.date()) + # Persistence calls this pre-flight state ``scheduled``; the wire lifecycle + # resolver calls the same state ``pending_start``. + return "scheduled" if canonical == "pending_start" else canonical + + +def _approval_creative_gate( + *, + assignments: CreativeAssignmentRepository, + creatives: CreativeRepository, + media_buy_id: str, + principal_id: str, +) -> tuple[bool, tuple[str, ...]]: + """Return whether the buy has at least one assignment and all are approved. + + ``approved`` is the only creative status that satisfies the gate. The other + members of the creative status enum — ``processing``, ``pending_review``, + ``suspended``, ``rejected``, ``archived`` — all block. + """ + creative_ids = list( + dict.fromkeys(assignment.creative_id for assignment in assignments.get_by_media_buy(media_buy_id)) + ) + if not creative_ids: + return False, () + creative_rows = creatives.get_by_ids(creative_ids, principal_id) + status_by_id = {creative.creative_id: creative.status for creative in creative_rows} + blocking_ids = tuple(creative_id for creative_id in creative_ids if status_by_id.get(creative_id) != "approved") + return not blocking_ids, blocking_ids + + +def prepare_media_buy_approval_execution( + *, + media_buys: MediaBuyRepository, + assignments: CreativeAssignmentRepository, + creatives: CreativeRepository, + media_buy_id: str, + approved_by: str | None, + trigger: ApprovalTrigger = ApprovalTrigger.HUMAN_DECISION, +) -> ApprovalExecutionOutcome: + """Decide, and if it applies claim, one adapter execution for a media buy. + + The caller owns the surrounding UoW so the human workflow decision and + the irreversible domain claim can commit together. + + This owns the WHOLE eligibility decision — callers must not pre-filter on + ``media_buy.status``. Four of them used to, each with its own literal, and their + union happened to be the canonical set, so no single site read as wrong: an + approve route that recognised only ``pending_approval`` sent a ``pending_creatives`` + or ``draft`` buy down the plain-workflow path instead, terminalizing the step and + reporting success while the buy was never executed and the creative gate never ran. + + The two refusals are distinct and callers render them differently: + + * ``NOT_EXECUTABLE`` — there is no media buy, or it is not in a state this trigger + may execute from. Nothing was claimed and nothing is wrong; the caller finishes + the workflow step on its own. + * ``CLAIM_REFUSED`` — it WAS a candidate and the atomic claim lost, so another + request is already executing. The caller must not proceed. + """ + source_statuses = execution_source_statuses_for(trigger) + media_buy = media_buys.get_by_id(media_buy_id) + if media_buy is None or media_buy.status not in source_statuses: + return ApprovalExecutionOutcome(ApprovalExecutionStatus.NOT_EXECUTABLE) + + gate_satisfied, blocking_ids = _approval_creative_gate( + assignments=assignments, + creatives=creatives, + media_buy_id=media_buy_id, + principal_id=media_buy.principal_id, + ) + approval_fields: dict[str, Any] = {} + if approved_by is not None: + approval_fields = {"approved_at": datetime.now(UTC), "approved_by": approved_by} + if not gate_satisfied: + media_buys.update_status( + media_buy_id, + "pending_creatives", + **approval_fields, + ) + return ApprovalExecutionOutcome( + ApprovalExecutionStatus.WAITING_FOR_CREATIVES, + blocking_creative_ids=blocking_ids, + ) + + if not media_buys.claim_approved_execution(media_buy_id, trigger=trigger): + return ApprovalExecutionOutcome(ApprovalExecutionStatus.CLAIM_REFUSED) + if approval_fields: + media_buys.update_fields(media_buy_id, **approval_fields) + return ApprovalExecutionOutcome(ApprovalExecutionStatus.READY) + + +def _finalize_approval_execution( + *, + tenant_id: str, + media_buy_id: str, + step_id: str | None, + succeeded: bool, + error_message: str | None, + context: ContextObject | dict[str, Any] | None, + apply_flight_status: bool, +) -> ApprovalFinalization: + """Finalize either an explicitly identified or creative-unblocked step.""" + if step_id is None: + return finalize_latest_media_buy_approval_step( + tenant_id=tenant_id, + media_buy_id=media_buy_id, + succeeded=succeeded, + error_message=error_message, + apply_flight_status=apply_flight_status, + ) + return finalize_media_buy_approval_step( + tenant_id=tenant_id, + step_id=step_id, + media_buy_id=media_buy_id, + succeeded=succeeded, + error_message=error_message, + context=context, + apply_flight_status=apply_flight_status, + ) + + +def apply_media_buy_execution_outcome( + *, + tenant_id: str, + media_buy_id: str, + step_id: str | None, + success: bool | None, + error_message: str | None, + context: ContextObject | dict[str, Any] | None = None, + apply_flight_status: bool = False, +) -> ApprovalExecutionOutcome: + """Own the adapter tri-state to durable workflow-finalization mapping.""" + if success is None: + return ApprovalExecutionOutcome( + ApprovalExecutionStatus.PENDING_RECONCILIATION, + error_message=error_message, + ) + + finalization = _finalize_approval_execution( + tenant_id=tenant_id, + media_buy_id=media_buy_id, + step_id=step_id, + succeeded=success, + error_message=error_message, + context=context, + apply_flight_status=apply_flight_status, + ) + if not finalization.applied or (success and finalization.result is None): + return ApprovalExecutionOutcome( + ApprovalExecutionStatus.FINALIZATION_FAILED, + finalization=finalization, + error_message=error_message, + ) + return ApprovalExecutionOutcome( + ApprovalExecutionStatus.SUCCEEDED if success else ApprovalExecutionStatus.FAILED, + finalization=finalization, + error_message=error_message, + ) + + +def execute_and_finalize_media_buy_approval( + *, + tenant_id: str, + media_buy_id: str, + step_id: str | None, + context: ContextObject | dict[str, Any] | None = None, + apply_flight_status: bool = False, +) -> ApprovalExecutionOutcome: + """Execute one claimed media buy and publish its durable tri-state result.""" + from src.core.tools.media_buy_create import execute_approved_media_buy + + success, error_message = execute_approved_media_buy( + media_buy_id, + tenant_id, + execution_claimed=True, + ) + return apply_media_buy_execution_outcome( + tenant_id=tenant_id, + media_buy_id=media_buy_id, + step_id=step_id, + success=success, + error_message=error_message, + context=context, + apply_flight_status=apply_flight_status, + ) + + +def _approval_recovery_state( + tenant_id: str, + media_buy_id: str, +) -> _ApprovalRecoveryState | None: + """Load workflow and domain rows together for durable reconciliation.""" + with ApprovalUoW(tenant_id) as uow: + assert uow.workflows is not None + assert uow.media_buys is not None + step = uow.workflows.get_claimed_create_approval_step_for_media_buy(media_buy_id) + media_buy = uow.media_buys.get_by_id(media_buy_id) + if step is None or media_buy is None: + return None + request_data = dict(step.request_data) if isinstance(step.request_data, dict) else {} + return _ApprovalRecoveryState( + step_id=step.step_id, + request_data=request_data, + media_buy_status=media_buy.status, + media_buy_updated_at=getattr(media_buy, "updated_at", None), + ) + + +def _approval_context(request_data: dict[str, Any]) -> dict[str, Any] | None: + context = request_data.get("context") + return context if isinstance(context, dict) else None + + +def _utc_datetime(value: datetime | None) -> datetime | None: + if value is not None and value.tzinfo is None: + return value.replace(tzinfo=UTC) + return value + + +def _reconcile_approval_state( + *, + tenant_id: str, + media_buy_id: str, + state: _ApprovalRecoveryState, +) -> ApprovalFinalization: + """Project one persisted media-buy state into a terminal workflow result.""" + if state.media_buy_status in _RECOVERABLE_SUCCESS_STATUSES: + return finalize_media_buy_approval_step( + tenant_id=tenant_id, + step_id=state.step_id, + media_buy_id=media_buy_id, + succeeded=True, + context=_approval_context(state.request_data), + apply_flight_status=True, + ) + if state.media_buy_status == "failed": + return finalize_media_buy_approval_step( + tenant_id=tenant_id, + step_id=state.step_id, + media_buy_id=media_buy_id, + succeeded=False, + error_message="Approved media buy execution failed", + ) + if state.media_buy_status == "activation_unknown": + return finalize_media_buy_approval_step( + tenant_id=tenant_id, + step_id=state.step_id, + media_buy_id=media_buy_id, + succeeded=False, + error_message="Approved media buy execution requires operator reconciliation", + mark_media_buy_failed=False, + ) + if state.media_buy_status != "activating": + return ApprovalFinalization(applied=False) + + observed_updated_at = _utc_datetime(state.media_buy_updated_at) + stale_before = datetime.now(UTC) - _APPROVAL_EXECUTION_LEASE + if observed_updated_at is not None and observed_updated_at > stale_before: + return ApprovalFinalization(applied=False) + return finalize_media_buy_approval_step( + tenant_id=tenant_id, + step_id=state.step_id, + media_buy_id=media_buy_id, + succeeded=False, + error_message="Approved media buy execution requires operator reconciliation", + mark_media_buy_failed=False, + mark_media_buy_unknown=True, + media_buy_expected_updated_at=observed_updated_at, + ) + + +def reconcile_claimed_media_buy_approval_step( + *, + tenant_id: str, + media_buy_id: str, +) -> ApprovalFinalization: + """Recover a claimed approval from persisted domain state only. + + ``execute_approved_media_buy`` durably marks a successful buy active and + its public wrapper marks a failed buy failed. A later tasks/get request can + therefore finish the workflow after a database outage without invoking the + external adapter again. + """ + state = _run_database_operation_with_retries( + lambda: _approval_recovery_state(tenant_id, media_buy_id), + retry_message="Approval reconciliation lookup failed; retrying (attempt %s)", + exhausted_message=( + f"Approval reconciliation lookup exhausted retries for media buy {media_buy_id} " + f"(tenant {tenant_id}); the approval remains unreconciled" + ), + ) + if state is None: + return ApprovalFinalization(applied=False) + return _reconcile_approval_state( + tenant_id=tenant_id, + media_buy_id=media_buy_id, + state=state, + ) diff --git a/src/routes/api_v1.py b/src/routes/api_v1.py index 35fe828806..4538203111 100644 --- a/src/routes/api_v1.py +++ b/src/routes/api_v1.py @@ -9,6 +9,7 @@ import json import logging +from types import MappingProxyType from typing import TYPE_CHECKING, Any if TYPE_CHECKING: @@ -22,6 +23,7 @@ from fastapi import APIRouter, Depends, Request from src.core.auth_context import require_auth, resolve_auth +from src.core.auth_policy import AUTH_OPTIONAL_SKILLS from src.core.schema_helpers import ( coerce_creative_filters, to_account_reference, @@ -49,6 +51,10 @@ router = APIRouter(prefix="/api/v1", tags=["api-v1"]) +# REST imports the same transport-neutral policy as A2A and MCP. Route +# signatures index this immutable map instead of maintaining another allowlist. +REST_AUTH_OPTIONAL_DEPENDENCIES = MappingProxyType(dict.fromkeys(AUTH_OPTIONAL_SKILLS, resolve_auth)) + # Note: ToolError handling lives entirely in the global ``@app.exception_handler`` # in src/app.py — REST routes never catch ToolError or import the MCP-boundary @@ -221,7 +227,10 @@ class SyncAccountsBody(SalesAgentBaseModel): @router.post("/products") -async def get_products(body: GetProductsBody, identity: ResolvedIdentity | None = resolve_auth): +async def get_products( + body: GetProductsBody, + identity: ResolvedIdentity | None = REST_AUTH_OPTIONAL_DEPENDENCIES["get_products"], +): """Get available products matching the brief (auth-optional discovery skill). ``ToolError`` propagates to the global handler in ``src.app`` for envelope @@ -239,14 +248,19 @@ async def get_products(body: GetProductsBody, identity: ResolvedIdentity | None @router.get("/capabilities") -async def get_capabilities(identity: ResolvedIdentity | None = resolve_auth): +async def get_capabilities( + identity: ResolvedIdentity | None = REST_AUTH_OPTIONAL_DEPENDENCIES["get_adcp_capabilities"], +): """Get AdCP capabilities (auth-optional discovery skill).""" response = await capabilities_module.get_adcp_capabilities_raw(identity=identity) return response.model_dump(mode="json") @router.post("/creative-formats") -async def list_creative_formats(body: ListCreativeFormatsBody, identity: ResolvedIdentity | None = resolve_auth): +async def list_creative_formats( + body: ListCreativeFormatsBody, + identity: ResolvedIdentity | None = REST_AUTH_OPTIONAL_DEPENDENCIES["list_creative_formats"], +): """List available creative formats (auth-optional discovery skill).""" from src.core.schemas import ListCreativeFormatsRequest @@ -260,7 +274,8 @@ async def list_creative_formats(body: ListCreativeFormatsBody, identity: Resolve @router.post("/authorized-properties") async def list_authorized_properties( - body: ListAuthorizedPropertiesBody, identity: ResolvedIdentity | None = resolve_auth + body: ListAuthorizedPropertiesBody, + identity: ResolvedIdentity | None = REST_AUTH_OPTIONAL_DEPENDENCIES["list_authorized_properties"], ): """List authorized properties (auth-optional discovery skill).""" from src.core.schemas import ListAuthorizedPropertiesRequest diff --git a/src/services/background_approval_service.py b/src/services/background_approval_service.py index d850a3ef2c..412edfa532 100644 --- a/src/services/background_approval_service.py +++ b/src/services/background_approval_service.py @@ -192,6 +192,27 @@ def _update_approval_progress(tenant_id: str, workflow_step_id: str, progress_da logger.warning(f"Failed to update approval progress: {e}") +def _log_refused_transition(workflow_step_id: str, status: str) -> None: + """Record that ``transition_if_nonterminal`` refused to finalize a step. + + The primitive returns None when the step is ALREADY terminal — a buyer cancel, an + admin rejection or another finalizer committed first — and a terminal step is + immutable, so refusing is the correct outcome of that race, not an error. It must + still be reported honestly: this polling thread is the only observer of its own + writes, so the log line below is the sole operator-visible record of what happened, + and the unconditional "Marked ... as completed" it replaces named a status the row + does not carry. + + Shared by both finalizers so the refusal is worded once (CLAUDE.md DRY invariant). + """ + logger.warning( + "Workflow step %s was NOT marked as %s: it is already terminal (concurrently " + "canceled/rejected/finalized). Leaving the committed outcome in place.", + workflow_step_id, + status, + ) + + def _mark_approval_complete( tenant_id: str, workflow_step_id: str, order_id: str, attempts: int, elapsed_seconds: float ) -> None: @@ -199,7 +220,7 @@ def _mark_approval_complete( try: with WorkflowUoW(tenant_id) as uow: assert uow.workflows is not None - step = uow.workflows.update_status( + step = uow.workflows.transition_if_nonterminal( workflow_step_id, status="completed", completed_at=datetime.now(UTC), @@ -209,7 +230,9 @@ def _mark_approval_complete( "message": f"Order approved successfully after {attempts} attempts ({int(elapsed_seconds)}s)", }, ) - if step: + if step is None: + _log_refused_transition(workflow_step_id, "completed") + else: step.transaction_details = { "approval_status": "approved", "gam_order_status": "APPROVED", @@ -217,7 +240,7 @@ def _mark_approval_complete( "elapsed_seconds": int(elapsed_seconds), "completed_at": datetime.now(UTC).isoformat(), } - logger.info(f"Marked workflow step {workflow_step_id} as completed") + logger.info("Marked workflow step %s as completed", workflow_step_id) except Exception as e: logger.error(f"Failed to mark approval complete: {e}") @@ -227,15 +250,17 @@ def _mark_approval_failed(tenant_id: str, workflow_step_id: str, error_message: try: with WorkflowUoW(tenant_id) as uow: assert uow.workflows is not None - step = uow.workflows.update_status( + step = uow.workflows.transition_if_nonterminal( workflow_step_id, status="failed", error_message=error_message, response_data={"status": "failed", "error": error_message}, ) - if step: + if step is None: + _log_refused_transition(workflow_step_id, "failed") + else: step.transaction_details = {"approval_status": "failed", "failure_reason": error_message} - logger.info(f"Marked workflow step {workflow_step_id} as failed") + logger.info("Marked workflow step %s as failed", workflow_step_id) except Exception as e: logger.error(f"Failed to mark approval failed: {e}") diff --git a/src/services/protocol_webhook_service.py b/src/services/protocol_webhook_service.py index 28446bbce9..7f26b1d7d8 100644 --- a/src/services/protocol_webhook_service.py +++ b/src/services/protocol_webhook_service.py @@ -19,7 +19,6 @@ from collections.abc import Mapping from datetime import UTC, datetime from typing import Any, cast -from urllib.parse import urlparse, urlunparse from uuid import uuid4 import requests @@ -33,10 +32,7 @@ from src.core.database.models import PushNotificationConfig from src.core.database.repositories.delivery import DeliveryRepository from src.core.lifecycle import register_shutdown -from src.core.webhook_validator import ( - reject_unsafe_outbound_webhook_url, - webhook_url_for_log, -) +from src.core.webhook_validator import WebhookURLValidator, webhook_url_for_log logger = logging.getLogger(__name__) @@ -107,25 +103,6 @@ def _to_wire_dict(payload: Any) -> dict[str, Any]: ) -def _normalize_localhost_for_docker(url: str) -> str: - """Replace localhost host with host.docker.internal while preserving userinfo and port.""" - try: - parsed = urlparse(url) - if parsed.hostname and parsed.hostname.lower() == "localhost": - userinfo = "" - if parsed.username: - userinfo = parsed.username - if parsed.password: - userinfo += f":{parsed.password}" - userinfo += "@" - port = f":{parsed.port}" if parsed.port else "" - new_netloc = f"{userinfo}host.docker.internal{port}" - return urlunparse(parsed._replace(netloc=new_netloc)) - except Exception: - logger.debug("Docker URL rewrite failed, using original URL", exc_info=True) - return url - - class ProtocolWebhookService: """ Service for sending protocol-level push notifications to clients. @@ -164,25 +141,22 @@ async def send_notification( ) return False - # SSRF gate on the configured URL *before* docker localhost rewrite. - # Under ADCP_TESTING, localhost/loopback is allowed for capture servers; - # production uses the full DNS-backed check (HTTPS required). - rejected, _error_msg = reject_unsafe_outbound_webhook_url( - push_notification_config.url, - log=logger, - kind="Protocol", - ) - if rejected: - return False - - url = _normalize_localhost_for_docker(push_notification_config.url) + # No docker-localhost rewrite here: this branch replaced that server-side + # dev convenience with the client-side ADCP_WEBHOOK_HOST/ADCP_WEBHOOK_TEST_HOST + # pair set in tests/e2e/conftest.py, so the capture server is registered at its + # reachable host directly. The SSRF gate lives per-attempt in the retry loop + # below (validate_protocol_webhook_url) rather than once here: it re-checks on + # every retry (covering DNS rebinding between attempts) and it is the + # protocol-callback validator, which carries the ADCP_WEBHOOK_TEST_HOST seam + # that #1697's generic validate_outbound_webhook_url does not. + url = push_notification_config.url # Prepare headers headers = {"Content-Type": "application/json", "User-Agent": "AdCP-Sales-Agent/1.0"} # Log sanitized config (exclude sensitive authentication_token) safe_config = { - "url": push_notification_config.url if hasattr(push_notification_config, "url") else None, + "url_configured": bool(push_notification_config.url), "authentication_type": ( push_notification_config.authentication_type if hasattr(push_notification_config, "authentication_type") @@ -217,6 +191,51 @@ async def send_notification( url=url, payload=payload_dict, headers=headers, metadata=metadata ) + def _record_refused_unsafe_url( + self, + *, + reason: str, + log_id: str, + tenant_id: str | None, + principal_id: str | None, + media_buy_id: str | None, + url: str, + task_type: str | None, + sequence_number: int, + notification_type: str | None, + attempt_count: int, + audit_logger: Any = None, + ) -> None: + """Record an SSRF refusal the way every other failure exit in the send loop does. + + A refusal is indistinguishable, from the buyer's side, from a webhook that + silently stopped arriving, so it needs the same delivery-log row and audit line an + HTTP failure gets — not just a server-side warning. It was the one failure exit + that wrote neither, and it discarded the validator's reason, which is precisely + the operator-facing detail that explains why delivery stopped. + + ``reason`` names the rejected host/scheme class and is operator-facing only: it + goes to the log, the delivery row and the audit trail, never onto the wire. + """ + logger.warning("Refusing protocol webhook delivery to an unsafe URL: %s", reason) + if task_type in ("delivery_report", "media_buy_delivery") and media_buy_id and tenant_id and principal_id: + self._write_delivery_log( + log_id=log_id, + tenant_id=tenant_id, + principal_id=principal_id, + media_buy_id=media_buy_id, + webhook_url=url, + task_type=task_type, + status="failed", + sequence_number=sequence_number, + notification_type=notification_type, + attempt_count=attempt_count, + error_message=f"Refused unsafe webhook URL: {reason}", + completed_at=datetime.now(UTC), + ) + if audit_logger: + audit_logger.log_warning(f"{task_type} webhook refused: unsafe URL ({reason})") + @staticmethod def _write_delivery_log( *, @@ -304,6 +323,22 @@ async def _send_with_retry_and_logging( audit_logger.log_info(f"Sending {task_type} webhook for task {task_id} (sequence #{sequence_number})") for attempt in range(max_attempts): + is_safe, validation_error = WebhookURLValidator.validate_protocol_webhook_url(url) + if not is_safe: + self._record_refused_unsafe_url( + reason=validation_error, + log_id=log_id, + tenant_id=tenant_id, + principal_id=principal_id, + media_buy_id=media_buy_id, + url=url, + task_type=task_type, + sequence_number=sequence_number, + notification_type=notification_type, + attempt_count=attempt + 1, + audit_logger=audit_logger, + ) + return False try: safe_url = webhook_url_for_log(url) logger.info( @@ -320,6 +355,11 @@ def _post() -> requests.Response: return self._session.post(url, json=payload, headers=headers, timeout=10.0, allow_redirects=False) response = await asyncio.to_thread(_post) + if 300 <= response.status_code < 400: + raise requests.HTTPError( + "Redirect responses are not accepted for protocol webhooks", + response=response, + ) response.raise_for_status() # Calculate response time @@ -365,9 +405,14 @@ def _post() -> requests.Response: response_time_ms = int((time.time() - start_time) * 1000) error_message = f"HTTP {status_code}: {str(e)}" - # Don't retry on 4xx errors (client errors - permanent failures) - if status_code and 400 <= status_code < 500: - logger.error(f"Webhook failed for task {task_id} with client error {status_code} - not retrying") + # Don't retry redirects or 4xx errors. Redirects are never + # followed because the Location target has not been validated. + if status_code and 300 <= status_code < 500: + logger.error( + "Webhook failed for task %s with non-retryable HTTP status %s", + task_id, + status_code, + ) # Write to webhook_delivery_log (failed) if ( diff --git a/templates/media_buy_detail.html b/templates/media_buy_detail.html index 8d8daef5d8..684c7b4f81 100644 --- a/templates/media_buy_detail.html +++ b/templates/media_buy_detail.html @@ -21,6 +21,7 @@

Media Buy Details

+ @@ -384,6 +385,7 @@

Reject Media Buy

+
diff --git a/tests/a2a_helpers.py b/tests/a2a_helpers.py index 9af2a69ce5..e59c825fef 100644 --- a/tests/a2a_helpers.py +++ b/tests/a2a_helpers.py @@ -2,7 +2,8 @@ Provides make_a2a_context() to build a ServerCallContext the same way AdCPCallContextBuilder.build() does in production, but without needing -a Starlette request object. +a Starlette request object. Message builders and envelope readers live +with the rest of the A2A helper family in tests/utils/a2a_helpers.py. """ from a2a.server.context import ServerCallContext diff --git a/tests/admin/conftest.py b/tests/admin/conftest.py index c02d187ebd..888ed90860 100644 --- a/tests/admin/conftest.py +++ b/tests/admin/conftest.py @@ -8,49 +8,14 @@ from unittest.mock import MagicMock, patch import pytest -from sqlalchemy.orm import Session as SASession # Import integration_db fixture so UI integration tests (e.g. test_product_creation_integration.py) # can access it. The fixture is defined in tests/conftest_db.py (shared across suites). +# ``factory_session`` also lives there now (single shared definition) and reaches this suite via +# the root conftest's ``from tests.conftest_db import *``. from tests.conftest_db import integration_db # noqa: F401 -@pytest.fixture -def factory_session(integration_db): # noqa: F811 — fixture parameter, not a redefinition - """Bind all factory_boy factories to a live PostgreSQL session for the test. - - Use this fixture in new admin blueprint tests to create test data via factories - (e.g. ``TenantFactory(tenant_id="t1")``) instead of inline ``session.add()``. - Factories are unbound on teardown so the binding doesn't leak into other tests. - - Returns the bound session for use in post-POST DB state assertions. - - Note: the factory session binding is stored on class attributes of each factory, - so this fixture mutates process-wide state. Two tests in the same worker cannot - use ``factory_session`` concurrently — the ``assert ... is None`` precondition - below catches nesting. Parallel test runners must assign distinct workers per - test (pytest-xdist's default ``--dist=load`` is fine; avoid ``--dist=each``). - """ - from src.core.database.database_session import get_engine - from tests.factories import ALL_FACTORIES - - for f in ALL_FACTORIES: - assert f._meta.sqlalchemy_session is None, ( - f"Factory {f.__name__} session already bound — nested factory_session fixtures are not supported" - ) - - session = SASession(bind=get_engine()) - for f in ALL_FACTORIES: - f._meta.sqlalchemy_session = session - - try: - yield session - finally: - for f in ALL_FACTORIES: - f._meta.sqlalchemy_session = None - session.close() - - @pytest.fixture def ui_test_mode(): """Enable UI test authentication mode.""" diff --git a/tests/admin/test_creatives_blueprint.py b/tests/admin/test_creatives_blueprint.py index ded6a9bdc4..57fdeb5c4f 100644 --- a/tests/admin/test_creatives_blueprint.py +++ b/tests/admin/test_creatives_blueprint.py @@ -14,6 +14,7 @@ from src.admin.app import create_app from src.core.database.database_session import get_db_session from src.core.database.models import Creative, Principal, Tenant +from src.core.database.repositories import MediaBuyUoW, WorkflowUoW from tests.utils.database_helpers import create_tenant_with_timestamps app = create_app() @@ -256,6 +257,32 @@ def _create_assignment(session, tenant_id: str, creative_id: str, media_buy_id: # Patch at the use site: creatives.py binds this name via `from ... import`, so the # definition module (src.core.tools.media_buy_create) is not where the call resolves. _PUSH_PATCH = "src.admin.blueprints.creatives.push_creative_to_existing_buy" +_EXECUTE_PATCH = "src.core.tools.media_buy_create.execute_approved_media_buy" + + +def _create_claimed_a2a_approval( + tenant_id: str, + media_buy_id: str, + external_task_id: str, + *, + request_context: dict | None = None, +) -> str: + """Persist the exact claimed create step the creative-unblock path must finalize.""" + from src.core.context_manager import ContextManager + + manager = ContextManager() + context = manager.create_context(tenant_id=tenant_id, principal_id=_PRINCIPAL_ID) + step = manager.create_workflow_step( + context_id=context.context_id, + step_type="approval", + owner="publisher", + status="approved", + tool_name="create_media_buy", + request_data={"context": request_context} if request_context is not None else {}, + request_metadata={"protocol": "a2a", "external_task_id": external_task_id}, + object_mappings=[{"object_type": "media_buy", "object_id": media_buy_id, "action": "create"}], + ) + return step.step_id class TestCreativeApprovalRetroactivePush: @@ -305,6 +332,129 @@ def test_pending_creatives_buy_not_retroactively_pushed(self, client, test_tenan assert response.status_code == 200 mock_push.assert_not_called() + @pytest.mark.parametrize("adapter_succeeds", [True, False]) + def test_creative_unblock_terminalizes_durable_a2a_task( + self, + client, + test_tenant, + factory_session, + adapter_succeeds, + ): + """The last creative drives the claimed create step to a durable terminal result.""" + from a2a.types import TaskState + + from src.a2a_server.adcp_a2a_server import AdCPRequestHandler + from tests.factories import PrincipalFactory + from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE + from tests.utils.a2a_helpers import ( + assert_failed_task_envelope, + assert_failed_task_no_secret_leak, + extract_data_from_artifact, + ) + + _auth_session(client, test_tenant) + creative_id = _create_creative_for_retro_push(factory_session, test_tenant, status="pending_review") + media_buy_id, package_id = _create_active_media_buy( + factory_session, + test_tenant, + status="pending_creatives", + ) + _create_assignment(factory_session, test_tenant, creative_id, media_buy_id, package_id) + original_approved_at = datetime(2026, 1, 15, 12, tzinfo=UTC) + with MediaBuyUoW(test_tenant) as uow: + assert uow.media_buys is not None + uow.media_buys.update_fields( + media_buy_id, + approved_at=original_approved_at, + approved_by="human-approver@example.com", + ) + external_task_id = f"task_creative_unblock_{uuid.uuid4().hex[:8]}" + request_context = {"trace_id": f"trace_{uuid.uuid4().hex[:8]}"} + _create_claimed_a2a_approval( + test_tenant, + media_buy_id, + external_task_id, + request_context=request_context, + ) + + adapter_result = (True, None) if adapter_succeeds else (False, SECRET_BEARING_MESSAGE) + with ( + patch(_SIDE_EFFECTS_PATCH), + patch(_EXECUTE_PATCH, return_value=adapter_result), + patch(_PUSH_PATCH, return_value=(True, None)), + ): + response = client.post( + f"/tenant/{test_tenant}/creatives/review/{creative_id}/approve", + content_type="application/json", + json={"approved_by": "test@example.com"}, + ) + + assert response.status_code == 200 + identity = PrincipalFactory.make_identity( + tenant_id=test_tenant, + principal_id=_PRINCIPAL_ID, + protocol="a2a", + ) + task = AdCPRequestHandler()._durable_task_from_step(external_task_id, identity) + assert task is not None + if adapter_succeeds: + assert task.status.state == TaskState.TASK_STATE_COMPLETED + assert task.artifacts and task.artifacts[0].name == "media_buy_result" + result = extract_data_from_artifact(task.artifacts[0]) + assert result["media_buy_id"] == media_buy_id + assert result["status"] == "completed" + assert result["context"] == request_context + else: + assert_failed_task_envelope(task, code="SERVICE_UNAVAILABLE", recovery="transient") + assert_failed_task_no_secret_leak(task) + with MediaBuyUoW(test_tenant) as uow: + assert uow.media_buys is not None + persisted_media_buy = uow.media_buys.get_by_id(media_buy_id) + assert persisted_media_buy is not None + assert persisted_media_buy.approved_by == "human-approver@example.com" + assert persisted_media_buy.approved_at == original_approved_at + + def test_creative_unblock_leaves_ambiguous_execution_nonterminal( + self, + client, + test_tenant, + factory_session, + ): + """A post-dispatch unknown outcome is never rewritten as adapter failure.""" + _auth_session(client, test_tenant) + creative_id = _create_creative_for_retro_push(factory_session, test_tenant, status="pending_review") + media_buy_id, package_id = _create_active_media_buy( + factory_session, + test_tenant, + status="pending_creatives", + ) + _create_assignment(factory_session, test_tenant, creative_id, media_buy_id, package_id) + step_id = _create_claimed_a2a_approval( + test_tenant, + media_buy_id, + f"task_creative_pending_{uuid.uuid4().hex[:8]}", + ) + + with ( + patch(_SIDE_EFFECTS_PATCH), + patch(_EXECUTE_PATCH, return_value=(None, "adapter outcome unknown")), + patch(_PUSH_PATCH, return_value=(True, None)), + patch("src.core.workflow_finalization.finalize_latest_media_buy_approval_step") as mock_finalize, + ): + response = client.post( + f"/tenant/{test_tenant}/creatives/review/{creative_id}/approve", + content_type="application/json", + json={"approved_by": "test@example.com"}, + ) + + assert response.status_code == 200 + with WorkflowUoW(test_tenant) as uow: + assert uow.workflows is not None + persisted = uow.workflows.get_by_step_id(step_id) + assert persisted is not None + assert persisted.status == "approved" + mock_finalize.assert_not_called() + def test_push_failure_returns_200_with_warnings(self, client, test_tenant, factory_session): """Push failure is non-fatal: response is 200 with a warnings field.""" _auth_session(client, test_tenant) diff --git a/tests/admin/test_workflows_blueprint.py b/tests/admin/test_workflows_blueprint.py index 5476fca6bf..e4482cd3a3 100644 --- a/tests/admin/test_workflows_blueprint.py +++ b/tests/admin/test_workflows_blueprint.py @@ -6,13 +6,17 @@ import uuid from datetime import UTC, datetime +from unittest.mock import patch import pytest from sqlalchemy import delete, select from src.admin.app import create_app +from src.admin.utils.approval import APPROVED_MEDIA_BUY_EXECUTION_FAILURE_MESSAGE +from src.core.context_manager import ContextManager from src.core.database.database_session import get_db_session from src.core.database.models import Context, Principal, Tenant, WorkflowStep +from src.core.database.repositories import WorkflowUoW from tests.utils.database_helpers import create_tenant_with_timestamps app = create_app() @@ -114,6 +118,46 @@ def _create_context_and_step(tenant_id: str, status: str = "pending_approval") - return context_id, step_id +def _create_mapped_media_buy_approval(factory_session, tenant_id: str) -> tuple[str, str]: + """Create an executable pending media buy with a mapped approval step.""" + from tests.factories import CreativeAssignmentFactory, CreativeFactory, MediaBuyFactory + + tenant = factory_session.get(Tenant, tenant_id) + principal = factory_session.get(Principal, (tenant_id, "wf_test_principal")) + media_buy = MediaBuyFactory( + tenant=tenant, + principal=principal, + status="pending_approval", + ) + creative = CreativeFactory( + tenant=tenant, + principal=principal, + status="approved", + ) + CreativeAssignmentFactory( + creative=creative, + media_buy=media_buy, + ) + manager = ContextManager() + context = manager.create_context(tenant_id=tenant_id, principal_id=principal.principal_id) + step = manager.create_workflow_step( + context_id=context.context_id, + step_type="approval", + owner="publisher", + status="requires_approval", + tool_name="create_media_buy", + request_data={}, + object_mappings=[ + { + "object_type": "media_buy", + "object_id": media_buy.media_buy_id, + "action": "approve", + } + ], + ) + return context.context_id, step.step_id + + class TestWorkflowsList: """Test the workflows list page.""" @@ -136,8 +180,8 @@ def test_list_shows_pending_steps(self, client, test_tenant): class TestWorkflowApproval: """Test workflow step approval.""" - def test_approve_step_sets_status_approved(self, client, test_tenant): - """POST approve sets the step status to 'approved'.""" + def test_approve_step_without_execution_completes_atomically(self, client, test_tenant): + """A plain approval is terminalized in the same transaction as its claim.""" _auth_session(client, test_tenant) context_id, step_id = _create_context_and_step(test_tenant, status="pending_approval") @@ -150,10 +194,34 @@ def test_approve_step_sets_status_approved(self, client, test_tenant): data = response.get_json() assert data.get("success") is True - with get_db_session() as session: - step = session.get(WorkflowStep, step_id) - assert step is not None - assert step.status == "approved" + with WorkflowUoW(test_tenant) as uow: + assert uow.workflows is not None + step = uow.workflows.get_by_step_id(step_id) + assert step is not None + assert step.status == "completed" + assert step.response_data == {"approved": True} + + def test_plain_approval_completion_failure_rolls_back_claim(self, client, test_tenant): + """A refused same-transaction completion leaves the step reclaimable.""" + _auth_session(client, test_tenant) + context_id, step_id = _create_context_and_step(test_tenant, status="pending_approval") + + with patch( + "src.admin.blueprints.workflows.WorkflowRepository.complete_claimed_approval", + return_value=None, + ): + response = client.post( + f"/tenant/{test_tenant}/workflows/{context_id}/steps/{step_id}/approve", + content_type="application/json", + json={}, + ) + + assert response.status_code == 503 + with WorkflowUoW(test_tenant) as uow: + assert uow.workflows is not None + step = uow.workflows.get_by_step_id(step_id) + assert step is not None + assert step.status == "pending_approval" def test_approve_nonexistent_step_returns_404(self, client, test_tenant): """POST approve for a nonexistent step returns 404.""" @@ -165,6 +233,75 @@ def test_approve_nonexistent_step_returns_404(self, client, test_tenant): ) assert response.status_code == 404 + def test_ambiguous_adapter_outcome_returns_pending_without_failure_finalization( + self, + client, + test_tenant, + factory_session, + ): + """Workflow approval preserves an unknown post-dispatch outcome.""" + _auth_session(client, test_tenant) + context_id, step_id = _create_mapped_media_buy_approval(factory_session, test_tenant) + + with ( + patch( + "src.core.tools.media_buy_create.execute_approved_media_buy", + return_value=(None, "adapter outcome unknown"), + ), + patch("src.core.workflow_finalization.finalize_media_buy_approval_step") as mock_finalize, + ): + response = client.post( + f"/tenant/{test_tenant}/workflows/{context_id}/steps/{step_id}/approve", + content_type="application/json", + json={}, + ) + + assert response.status_code == 503 + assert response.get_json()["pending"] is True + mock_finalize.assert_not_called() + with WorkflowUoW(test_tenant) as uow: + assert uow.workflows is not None + persisted = uow.workflows.get_by_step_id(step_id) + assert persisted is not None + assert persisted.status == "approved" + + def test_adapter_failure_response_does_not_disclose_internal_error( + self, + client, + test_tenant, + factory_session, + ): + """Adapter exception details stay out of the admin response and durable result.""" + from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE, assert_no_secret_leak + + _auth_session(client, test_tenant) + context_id, step_id = _create_mapped_media_buy_approval(factory_session, test_tenant) + + with patch( + "src.core.tools.media_buy_create.execute_approved_media_buy", + return_value=(False, SECRET_BEARING_MESSAGE), + ): + response = client.post( + f"/tenant/{test_tenant}/workflows/{context_id}/steps/{step_id}/approve", + content_type="application/json", + json={}, + ) + + assert response.status_code == 500 + assert response.get_json() == { + "success": False, + "error": APPROVED_MEDIA_BUY_EXECUTION_FAILURE_MESSAGE, + } + assert_no_secret_leak(response.get_data(as_text=True), context="admin approval response") + + with WorkflowUoW(test_tenant) as uow: + assert uow.workflows is not None + persisted = uow.workflows.get_by_step_id(step_id) + assert persisted is not None + assert persisted.status == "failed" + assert_no_secret_leak(persisted.response_data, context="durable approval result") + assert_no_secret_leak(persisted.error_message, context="durable approval error") + class TestWorkflowRejection: """Test workflow step rejection.""" diff --git a/tests/bdd/conftest.py b/tests/bdd/conftest.py index c44937bb20..71edbb66f3 100644 --- a/tests/bdd/conftest.py +++ b/tests/bdd/conftest.py @@ -273,9 +273,7 @@ def pytest_configure(config: pytest.Config) -> None: # FIXME(salesagent-9vgz.6): creative/format_id validation errors lack suggestion field # ext-g: _validate_creatives_before_adapter_call raises INVALID_CREATIVES without suggestion # ext-h: plain string format_id caught by Pydantic, not structured AdCPError - # ext-h-agent: _validate_and_convert_format_ids is dead code — unregistered agent not detected "T-UC-002-ext-h": "plain string format_id produces Pydantic error, not AdCPError with suggestion", - "T-UC-002-ext-h-agent": "unregistered agent_url validation not wired — _validate_and_convert_format_ids is dead code", # FIXME(salesagent-9vgz.8): auth error lacks suggestion field # AdCPAuthenticationError("Principal ID not found...") has no details["suggestion"]. # Spec requires suggestion for buyer remediation (POST-F3). @@ -286,10 +284,11 @@ def pytest_configure(config: pytest.Config) -> None: "T-UC-002-ext-j": "adapter failure raises exception, no failed result envelope or suggestion — spec-production gap", "T-UC-002-inv-026-2": "INVALID_CREATIVES error lacks suggestion field", "T-UC-002-inv-026-4": "INVALID_CREATIVES error lacks suggestion field", - # Graduated (#1417/gh8p.10): the request-construction boundary now derives a - # field-aware suggestion (suggest_validation_fix) and attaches it to the - # AdCPValidationError, so a missing idempotency_key rejects with a non-empty - # wire suggestion. T-UC-002-v31-idempotency-missing passes. + # Graduated (#1417/gh8p.10): the request-construction boundary now attaches + # VALIDATION_ERROR's canonical AdCP 3.1.1 suggestion while retaining the + # field-specific diagnostic in field/details. A missing idempotency_key + # therefore rejects with a non-empty wire suggestion. + # T-UC-002-v31-idempotency-missing passes. # FIXME(salesagent-9vgz.17): optimization_goals not in adcp v3.6.0 or production schemas # PackageRequest(extra='forbid') rejects the field with generic validation error, # not spec-expected UNSUPPORTED_FEATURE / INVALID_REQUEST with structured codes. @@ -439,14 +438,28 @@ def pytest_configure(config: pytest.Config) -> None: ] -# MCP selective xfails: previously the MCP wrapper did not accept the -# disclosure_positions keyword. #1417 added disclosure_positions + -# disclosure_persistence to the MCP list_creative_formats wrapper, so the param -# is now accepted on MCP exactly like A2A/REST. The disclosure *filter* gap -# (_impl does not filter by disclosure) is all-transport and handled by -# _UC005_PARTIAL_TAGS / _XFAIL_TAGS, so no MCP-specific entries remain. +# MCP selective xfails. The former DISCLOSURE entries are gone: the MCP wrapper +# once did not accept the disclosure_positions keyword, but #1417 added +# disclosure_positions + disclosure_persistence to the MCP list_creative_formats +# wrapper, so the param is now accepted on MCP exactly like A2A/REST — and the +# disclosure *filter* gap (_impl does not filter by disclosure) is all-transport, +# handled by _UC005_PARTIAL_TAGS / _XFAIL_TAGS. +# +# ONE MCP-specific entry remains below, T-UC-002-ext-h-agent, whose cause is +# genuinely MCP-only (rfc8785 canonicalization of a structured FormatId carried in +# raw_wire_payload — A2A/REST never reach that path). # (tag, example_substrings, reason, strict) -_MCP_SELECTIVE_XFAIL: list[tuple[str, set[str], str, bool]] = [] +_MCP_SELECTIVE_XFAIL: list[tuple[str, set[str], str, bool]] = [ + ( + "T-UC-002-ext-h-agent", + set(), + "MCP-only: raw_wire_payload carries a structured FormatId, which " + "rfc8785 canonicalization cannot serialize, crashing idempotency " + "hashing before the format-agent validator this scenario targets " + "ever runs. A2A/REST don't hit this path. prebid/salesagent#1768.", + True, + ), +] # NOTE: the former _REST_XFAIL_TAGS set was retired once the stale # CreativeFormatsEnv.build_rest_body override (which returned {}) was removed. @@ -658,12 +671,10 @@ def pytest_collection_modifyitems(items: list[pytest.Item]) -> None: # code doesn't implement the expected validation. _UC003_EXT_XFAILS: dict[str, str] = { # Error code mismatches (production uses different codes than spec) - # Graduated (#1417/gh8p.10): both auth error paths now carry a buyer-facing - # suggestion. The REST auth boundary (_require_auth_dep) raises - # AdCPAuthRequiredError with AUTH_REQUIRED_SUGGESTION (REST no-identity envelope - # no longer drops it), and the unknown-principal ownership check - # (AdCPAuthorizationError) carries a "verify your x-adcp-auth token" suggestion. - # T-UC-003-ext-a / -ext-a-unknown pass on a2a/mcp/rest. + # Graduated (#1417/gh8p.10): both auth error paths now carry pinned + # buyer-facing guidance. Every wire boundary uses the pinned + # AUTH_MISSING/AUTH_INVALID split. The BDD assertion grades each + # transport's exact code, recovery, and suggestion. "T-UC-003-ext-c": "production returns AUTHORIZATION_ERROR, spec expects ACCOUNT_NOT_FOUND", # Graduated: T-UC-003-ext-d, T-UC-003-ext-d-negative (production now returns BUDGET_TOO_LOW) # Production doesn't validate these cases at all @@ -2679,15 +2690,15 @@ def pytest_collection_modifyitems(items: list[pytest.Item]) -> None: if not substrings or any(s in nodeid for s in substrings): item.add_marker(pytest.mark.xfail(reason=reason, strict=False)) - # --- UC-011: xfails for spec-production gaps --- - # FIXME(salesagent-7wan): Production doesn't implement these UC-011 features. + # --- UC-011: no xfails remain. Every entry below graduated; the notes are + # kept so a re-introduced failure is recognisable as a regression rather + # than a never-implemented feature. # Graduated: T-UC-011-list-status-filter payment_required (all 4 transports pass — status now mapped) # Graduated: T-UC-011-ext-g-echo list_accounts (all 4 transports pass — context echo implemented) - # Graduated: no-token/no-principal scenarios now pass after Gherkin - # correction to AUTH_REQUIRED (commit 13b4ca8d). Production returns - # AUTH_REQUIRED on rest/e2e_rest, matching the corrected Gherkin. - # Graduated: expired-token also passes — AUTH_REQUIRED matches. + # Graduated: no-token/no-principal and expired-token scenarios grade the + # pinned auth contract. Every wire transport uses + # AUTH_MISSING/AUTH_INVALID. # T-UC-011-ext-g-echo-error: impl passes (AdCPError carries context=req.context); # a2a/mcp/rest xfail+note via the context-echo Then step (pytest.xfail) because the @@ -2807,7 +2818,6 @@ def pytest_collection_modifyitems(items: list[pytest.Item]) -> None: "T-UC-002-v31-idempotency-replay", "T-UC-002-v31-idempotency-missing", } - # UC-002 manual-approval scenario wired to MediaBuyCreateEnv (PR #1567 round-2 item 2): # grades the spec-3.1.1 CreateMediaBuySubmitted envelope (status="submitted" + # task_id, no media_buy_id/confirmed_at/revision) across all 4 transports — diff --git a/tests/bdd/features/BR-UC-002-account-access.feature b/tests/bdd/features/BR-UC-002-account-access.feature index 9cf2a82075..8ab17da702 100644 --- a/tests/bdd/features/BR-UC-002-account-access.feature +++ b/tests/bdd/features/BR-UC-002-account-access.feature @@ -23,12 +23,16 @@ Feature: BR-UC-002 Account access scoping And the resolved account is the one the agent can access # salesagent-fb2l: an unauthenticated caller (tenant resolved, no principal) must be - # rejected with AUTH_REQUIRED at the account-resolution boundary — it must never reach - # natural-key resolution, which would disclose the tenant-wide match count (info leak). + # rejected at the account-resolution boundary — it must never reach natural-key + # resolution, which would disclose the tenant-wide match count (info leak). @T-UC-002-fb2l-unauth-no-disclosure @account @error Scenario: Unauthenticated natural-key resolution discloses no account information Given a valid create_media_buy request with account natural key brand "leak-brand.com" operator "leak-agency.com" And the natural key matches 2 accounts And the Buyer Agent's token resolves no principal + And natural-key account resolution is being observed When the Buyer Agent sends the create_media_buy request - Then the result should be error "AUTH_REQUIRED" + Then the operation should fail + And the authentication error should match invalid credentials for the active transport + And the authentication error should disclose no account resolution information + And no natural-key account lookup should have been performed diff --git a/tests/bdd/features/BR-UC-002-create-media-buy.feature b/tests/bdd/features/BR-UC-002-create-media-buy.feature index 604180c782..ab083c6af9 100644 --- a/tests/bdd/features/BR-UC-002-create-media-buy.feature +++ b/tests/bdd/features/BR-UC-002-create-media-buy.feature @@ -214,6 +214,20 @@ Feature: BR-UC-002 Create Media Buy # POST-F1: System state is unchanged on failure # POST-F2: Buyer knows what failed # POST-F3: Buyer knows how to fix the issue + + @T-UC-002-ext-nl-unsupported @extension @error @transport-layer-separation @a2a @hand-edited + Scenario: NL media-buy request is unsupported -- returned as a failed task, not a transport error + Given an authenticated buyer + When the buyer sends a natural-language "create a media buy" request + Then the failure is returned as a failed task, not a transport error + And the error code should be "UNSUPPORTED_FEATURE" + And the error recovery should be "correctable" + And the wire error envelope should carry code "UNSUPPORTED_FEATURE" with recovery "correctable" + # HAND-EDITED: no adcp-req id yet; the generated scenario is intentionally preserved. + # @hand-edited classifies this LEGACY-PRESERVE so compile_bdd.py --merge keeps it. + # grounded: AdCP 3.1.1 building/operating/transport-errors.mdx "Layer Separation" + # storyboard: ungraded, pending an upstream obligation. + # drives the top-level on_message_send except -> failed Task envelope, not JSON-RPC # --- ext-e: Duplicate Products --- @T-UC-002-ext-e @extension @ext-e @error @post-f1 @post-f2 @post-f3 diff --git a/tests/bdd/features/BR-UC-002-nfr-enforcement.feature b/tests/bdd/features/BR-UC-002-nfr-enforcement.feature index 21fe9495bb..cdb1f06643 100644 --- a/tests/bdd/features/BR-UC-002-nfr-enforcement.feature +++ b/tests/bdd/features/BR-UC-002-nfr-enforcement.feature @@ -38,7 +38,7 @@ Feature: BR-UC-002 NFR Enforcement (restructured) # matching the 13 sibling UCs that already assert the suggestion on auth # errors. Routes through each transport's REAL auth gate (A2A # on_message_send no-token gate, REST _require_auth_dep, MCP boundary). - And the error code should be "AUTH_REQUIRED" + And the authentication error should match missing credentials for the active transport And the suggestion should contain "credentials" And no adapter calls should have been made diff --git a/tests/bdd/features/BR-UC-003-update-media-buy.feature b/tests/bdd/features/BR-UC-003-update-media-buy.feature index c3dee4b053..dbfe2ccfe8 100644 --- a/tests/bdd/features/BR-UC-003-update-media-buy.feature +++ b/tests/bdd/features/BR-UC-003-update-media-buy.feature @@ -467,29 +467,27 @@ Feature: BR-UC-003 Update Media Buy | paused | true | When the Buyer Agent sends the update_media_buy request Then the operation should fail - And the error code should be "AUTH_REQUIRED" + And the authentication error should match missing credentials for the active transport And the error message should contain "authentication" And the error should include "suggestion" field - And the suggestion should contain "valid credentials" + And the suggestion should contain "provide credentials" # POST-F1: System state unchanged # POST-F2: Error explains authentication failed # POST-F3: Suggestion to obtain valid credentials @T-UC-003-ext-a-unknown @extension @ext-a @error @post-f1 @post-f2 @post-f3 - Scenario: Authentication error -- principal not found in database - Given the Buyer is authenticated as principal "unknown_principal" - And the principal "unknown_principal" does not exist in the database + Scenario: Authentication error -- rejected credentials resolve no principal + Given the Buyer Agent's token resolves no principal And a valid update_media_buy request with: | field | value | | media_buy_id | mb_existing | | paused | true | When the Buyer Agent sends the update_media_buy request Then the operation should fail - And the error code should be "AUTH_REQUIRED" - And the error should include "suggestion" field + And the authentication error should match invalid credentials for the active transport # POST-F1: System state unchanged - # POST-F2: Error explains principal not found - # POST-F3: Suggestion for recovery + # POST-F2: Rejected credentials traverse production token resolution + # POST-F3: Exact code, recovery, and suggestion match the pinned contract @T-UC-003-ext-b @extension @ext-b @error @post-f1 @post-f2 @post-f3 Scenario: Media buy not found -- by media_buy_id diff --git a/tests/bdd/features/BR-UC-011-manage-accounts.feature b/tests/bdd/features/BR-UC-011-manage-accounts.feature index ed1611de2e..f354a748b9 100644 --- a/tests/bdd/features/BR-UC-011-manage-accounts.feature +++ b/tests/bdd/features/BR-UC-011-manage-accounts.feature @@ -73,7 +73,7 @@ Feature: BR-UC-011 Manage Accounts Given the Buyer Agent has an unauthenticated connection When the Buyer Agent sends a list_accounts request without an authentication token Then the response is an error variant with no accounts array - And the error code is "AUTH_REQUIRED" + And the authentication error should match missing credentials for the active transport And the error message describes the authentication requirement # @bva authentication (account operations): no token on list @@ -244,7 +244,7 @@ Feature: BR-UC-011 Manage Accounts | brand.domain | operator | billing | | acme-corp.com | acme-corp.com | operator | Then the response is an error variant with no accounts array - And the error code is "AUTH_REQUIRED" + And the authentication error should match missing credentials for the active transport And the error message describes the authentication requirement And the error should include "suggestion" field with remediation guidance And no accounts were modified on the seller @@ -253,13 +253,13 @@ Feature: BR-UC-011 Manage Accounts # POST-F2: Buyer knows what failed @T-UC-011-ext-a-expired @sync @ext-a @auth @error @partition @boundary - Scenario: Sync with expired token -- sync_invalid_token returns AUTH_REQUIRED (invalid token on sync) - Given the Buyer Agent has an A2A connection with an expired token + Scenario: Sync with expired token -- sync_invalid_token returns the transport auth error + Given the Buyer Agent presents an expired authentication credential When the Buyer Agent sends a sync_accounts request with: | brand.domain | operator | billing | | acme-corp.com | acme-corp.com | operator | Then the response is an error variant - And the error code is "AUTH_REQUIRED" + And the authentication error should match invalid credentials for the active transport And the error should include "suggestion" field with remediation guidance # @bva authentication (account operations): invalid token on sync @@ -462,7 +462,8 @@ Feature: BR-UC-011 Manage Accounts Scenario: Context echoed in sync error response Given the Buyer Agent has an unauthenticated connection When the Buyer Agent sends a sync_accounts request with context {"trace": "err-001"} - Then the response is an error variant with AUTH_REQUIRED + Then the response is an error variant + And the authentication error should match missing credentials for the active transport And the response includes context {"trace": "err-001"} And the error should include "suggestion" field with remediation guidance # POST-F3: Context echoed even on error path diff --git a/tests/bdd/steps/domain/uc002_create_media_buy.py b/tests/bdd/steps/domain/uc002_create_media_buy.py index 1c5abf887e..d6edb3b601 100644 --- a/tests/bdd/steps/domain/uc002_create_media_buy.py +++ b/tests/bdd/steps/domain/uc002_create_media_buy.py @@ -116,6 +116,14 @@ def given_valid_request(ctx: dict) -> None: _ensure_request_defaults(ctx) +@given("an authenticated buyer") +def given_authenticated_buyer(ctx: dict) -> None: + """Bind the scenario to the harness-created A2A buyer identity.""" + from tests.harness.transport import Transport + + ctx["authenticated_identity"] = ctx["env"].identity_for(Transport.A2A) + + @given(parsers.parse('a valid create_media_buy request with account "{account_id}"')) def given_request_with_account(ctx: dict, account_id: str) -> None: """Set up a create_media_buy request with account (short form).""" @@ -176,7 +184,13 @@ def given_account_needs_setup(ctx: dict, account_id: str) -> None: @given(parsers.parse("the natural key matches {count:d} accounts")) def given_multiple_matches(ctx: dict, count: int) -> None: - """Create multiple accounts matching the same natural key.""" + """Create multiple accounts matching the same natural key. + + Records ``natural_key_match_count`` so the non-disclosure Then can assert THIS + scenario's actual count is absent from the wire, rather than guessing at literals + production might use to express it. + """ + ctx["natural_key_match_count"] = count env = ctx["env"] if "tenant" not in ctx: tenant, principal = env.setup_default_data() @@ -199,6 +213,110 @@ def given_multiple_matches(ctx: dict, count: int) -> None: AgentAccountAccessFactory(tenant_id=tenant.tenant_id, principal=principal, account=account) +class _RestoreOnStop: + """Adapts a plain restore callback to the ``ctx["_patchers"]`` cleanup contract. + + The ``ctx`` fixture (``conftest.py``) drains ``ctx["_patchers"]`` and calls + ``.stop()`` on each entry in its own ``finally`` block, so cleanup runs + whether the scenario passes, fails, or errors before reaching a Then step. + Wrapping a plain callable in this shim lets a step use that same guaranteed + teardown without a real ``unittest.mock`` patcher underneath. + """ + + def __init__(self, restore: Any) -> None: + self._restore = restore + self._stopped = False + + def stop(self) -> None: + if not self._stopped: + self._restore() + self._stopped = True + + +@given("natural-key account resolution is being observed") +def given_natural_key_resolution_observed(ctx: dict) -> None: + """Install a call-count spy on ``AccountRepository``'s natural-key queries. + + Proves the auth-ordering claim ("rejected credentials must never reach + natural-key resolution") from the PROCESS side, not just the output. The + envelope-scan Then step (``then_auth_error_discloses_no_account_resolution``) + only inspects the final wire response — it would pass unchanged even if + production queried the tenant-wide match count and then discarded the + result before responding, which is itself the timing/query side channel + the scenario exists to rule out. + + A plain wrapper function, not ``MagicMock(wraps=...)``: patching a class + attribute with a ``MagicMock`` breaks the descriptor protocol that binds + ``self`` on instance-method access, so the wrapped call would be missing + its first argument. Threading ``self`` through explicitly keeps the + patched methods callable exactly like the originals. + """ + from src.core.database.repositories.account import AccountRepository + + original_list = AccountRepository.list_by_natural_key + original_count = AccountRepository.count_by_natural_key + calls: list[str] = [] + + def list_wrapper(self: AccountRepository, *args: Any, **kwargs: Any) -> Any: + calls.append("list_by_natural_key") + return original_list(self, *args, **kwargs) + + def count_wrapper(self: AccountRepository, *args: Any, **kwargs: Any) -> Any: + calls.append("count_by_natural_key") + return original_count(self, *args, **kwargs) + + AccountRepository.list_by_natural_key = list_wrapper # type: ignore[method-assign] + AccountRepository.count_by_natural_key = count_wrapper # type: ignore[method-assign] + + def _restore() -> None: + AccountRepository.list_by_natural_key = original_list # type: ignore[method-assign] + AccountRepository.count_by_natural_key = original_count # type: ignore[method-assign] + + ctx["_natural_key_lookup_calls"] = calls + ctx.setdefault("_patchers", []).append(_RestoreOnStop(_restore)) + + +@then("no natural-key account lookup should have been performed") +def then_no_natural_key_lookup_performed(ctx: dict) -> None: + """Assert the process-side guarantee: the repository queries never ran. + + Complements, does not replace, the output-side + ``then_auth_error_discloses_no_account_resolution`` check — that step + proves the response never DISCLOSES account-resolution data; this step + proves the resolution was never ATTEMPTED. A response that happens to omit + leaked data after the query already ran would satisfy the first check and + fail this one. Restoration of the patched methods is handled by the + ``ctx`` fixture's teardown, not here, so it still runs if this assertion + fails. + + Skipped on e2e_* transports: the create runs in the separate Docker app + process, out of the in-process spy's reach (mirrors + ``then_high_value_alert_observed`` in uc002_nfr.py for the same reason). + ``AccountRepository.list_by_natural_key``/``count_by_natural_key`` are + pure reads with no persisted side effect a test process could read back + out-of-process, so there is no observable signal to re-express this + guarantee against on e2e — the output-side check above still runs there. + """ + import pytest + + from tests.bdd.steps._outcome_helpers import is_e2e + + if is_e2e(ctx): + pytest.skip( + "natural-key lookup spy is in-process only; the e2e create runs in the " + "separate Docker app, out of the spy's reach — see " + "then_auth_error_discloses_no_account_resolution for the output-side " + "check, which still runs on this transport" + ) + + calls = ctx.get("_natural_key_lookup_calls") + assert calls is not None, ( + "No natural-key lookup spy installed — scenario must call " + '"Given natural-key account resolution is being observed" first' + ) + assert calls == [], f"Expected zero natural-key account lookups for rejected credentials, got: {calls}" + + @given(parsers.parse("the natural key matches {total:d} accounts but the agent can access {accessible:d}")) def given_natural_key_partial_access(ctx: dict, total: int, accessible: int) -> None: """Create ``total`` active accounts matching the request natural key, granting the @@ -242,23 +360,12 @@ def given_natural_key_partial_access(ctx: dict, total: int, accessible: int) -> @given("the Buyer Agent's token resolves no principal") def given_unauthenticated_principal(ctx: dict) -> None: - """Force the dispatch identity to an unauthenticated one: a tenant is resolved - (from the host header, as MCP middleware does) but principal_id is None. - - This is the exact shape an unauthenticated MCP caller presents — MCP resolves - a tenant from the host but no principal from a missing/invalid token, so account - resolution at the transport boundary runs with principal_id=None. A2A/REST raise - on the missing token before this point; forcing the identity here exercises the - shared ``enrich_identity_with_account`` boundary guard uniformly on every wire - transport. See #1417. - """ - from tests.factories.principal import PrincipalFactory + """Present a token that the real transport auth chain cannot resolve. - env = ctx["env"] - ctx["dispatch_identity"] = PrincipalFactory.make_identity( - principal_id=None, - tenant_id=env._tenant_id, - ) + No identity is injected: A2A, MCP, and REST must all reject the credential + before account lookup can disclose a tenant-wide match count. See #1417. + """ + ctx["presented_auth_token"] = "rejected-account-access-token" @given(parsers.parse('the account "{account_id}" exists and is active')) @@ -306,6 +413,55 @@ def given_account_active(ctx: dict) -> None: AgentAccountAccessFactory(tenant_id=tenant.tenant_id, principal=principal, account=account) +@when(parsers.parse('the buyer sends a natural-language "{request_text}" request')) +def when_buyer_sends_nl_a2a_request(ctx: dict, request_text: str) -> None: + """Drive real A2A ``on_message_send`` with a natural-language text part. + + Goes through the SAME ``dispatch_request`` seam every other When-step uses, with + ``nl_text`` selecting the natural-language message shape (see + ``BaseTestEnv._run_a2a_handler``). This step previously hand-rolled the entire + dispatch — its own ``AdCPRequestHandler``, its own identity mocks, its own + ``asyncio.run``, its own ``TransportResult`` — four independent chances to drift + from the harness, and it HAD already drifted: it set no ``ctx["result"]``, so the + generic wire-first Then-steps found nothing and silently fell back to grading the + RECONSTRUCTED exception instead of the wire. + """ + from tests.bdd.steps.generic._dispatch import dispatch_request + from tests.harness.transport import Transport + + # The scenario carries @a2a, so pytest_generate_tests skips transport parametrization + # and leaves ctx["transport"] unset — that tag's contract is "the When step picks the + # transport". Natural language IS an A2A-only entry point (neither MCP nor REST + # exposes one), so there is exactly one transport to pick, and naming it here is what + # lets the dispatch go through the shared seam instead of a step-local copy of it. + ctx["transport"] = Transport.A2A + dispatch_request(ctx, nl_text=request_text) + + +@then("the failure is returned as a failed task, not a transport error") +def then_failure_is_a_failed_task(ctx: dict) -> None: + """Pin the PR's actual thesis: layer separation on the A2A boundary. + + An unsupported operation is an APPLICATION outcome, so it must come back as a + completed JSON-RPC call carrying a FAILED Task with the AdCP envelope — not as a + JSON-RPC ``InternalError``, which says the transport itself broke. Asserting only + the error code cannot tell those apart: both carry ``UNSUPPORTED_FEATURE``, and the + JSON-RPC-error shape would satisfy every other Then in this scenario. + + Grounded: AdCP 3.1.1 building/operating/transport-errors.mdx, "Layer Separation". + """ + from a2a.types import Task, TaskState + + task = ctx["env"].last_a2a_task + assert isinstance(task, Task), ( + f"no A2A Task was captured — the request never reached the failed-Task path (got {type(task).__name__})" + ) + assert task.status.state == TaskState.TASK_STATE_FAILED, ( + f"a transport-layer failure would surface as a JSON-RPC error, not a failed Task; " + f"Task state was {task.status.state}" + ) + + @given(parsers.parse("a create_media_buy request with account configuration {partition}")) def given_request_with_partition(ctx: dict, partition: str) -> None: """Set up request based on partition name (for Scenario Outline tables).""" @@ -646,9 +802,8 @@ def given_package_format_id_plain_string(ctx: dict, format_id: str) -> None: def given_package_format_id_unregistered_agent(ctx: dict) -> None: """Set a well-formed FormatId whose agent_url is not a registered creative agent. - Production gap: _validate_and_convert_format_ids (the unregistered-agent - check) is dead code — never called — so the unregistered agent_url is not - detected (ext-h-agent wants a 'not registered' error). + Production validates the registered creative-agent boundary and returns a + buyer-correctable error for this reference. """ pkg = _first_package(ctx) pkg["format_ids"] = [{"agent_url": "https://unregistered-agent.example.com", "id": "banner_300x250"}] @@ -772,9 +927,11 @@ def _dispatch_full_create(ctx: dict) -> None: ctx["error"] = e return - # No-auth scenarios (#1417) stash an unauthenticated identity so the - # transport-boundary account-resolution guard is exercised on the wire. - if "dispatch_identity" in ctx: + # Credential scenarios must run the production auth resolver; missing-auth + # scenarios deliberately pass identity=None through the harness. + if "presented_auth_token" in ctx: + dispatch_request(ctx, req=req, presented_auth_token=ctx["presented_auth_token"]) + elif "dispatch_identity" in ctx: dispatch_request(ctx, req=req, identity=ctx["dispatch_identity"]) else: dispatch_request(ctx, req=req) @@ -1552,10 +1709,9 @@ def given_request_idempotency_key_omitted(ctx: dict) -> None: Uses the harness OMIT sentinel: the request assembler keeps it, and MediaBuyCreateEnv._ensure_idempotency_key pops it so the constructed CreateMediaBuyRequest is missing the REQUIRED field — production rejects it - with a VALIDATION_ERROR naming idempotency_key and a buyer-facing - ``suggestion`` derived by ``suggest_validation_fix`` ("Provide the required - 'idempotency_key' field ..."), surfaced on the wire across all transports - (#1417/gh8p.10). + with a VALIDATION_ERROR naming idempotency_key in the structured diagnostic + and the canonical AdCP 3.1.1 buyer-facing suggestion, surfaced on the wire + across all transports (#1417/gh8p.10). """ from tests.harness.media_buy_create import OMIT_IDEMPOTENCY_KEY diff --git a/tests/bdd/steps/domain/uc002_nfr.py b/tests/bdd/steps/domain/uc002_nfr.py index 6f4e396f67..0c2e906561 100644 --- a/tests/bdd/steps/domain/uc002_nfr.py +++ b/tests/bdd/steps/domain/uc002_nfr.py @@ -126,19 +126,18 @@ def then_error_minimum_spend(ctx: dict) -> None: def then_auth_before_business_logic(ctx: dict) -> None: """Assert authentication is the first gate before any business logic. - Sends a SECOND request with invalid credentials (no principal_id) THROUGH - THE WIRE (the parametrized transport) and verifies: (1) the wire envelope - carries the AUTH_REQUIRED error code, and (2) no adapter calls were made — - proving auth blocks before business logic side effects. + Sends a SECOND request with an invalid token THROUGH THE WIRE (the + parametrized transport) and verifies: (1) production token resolution + emits the pinned invalid-credential contract, and (2) no adapter calls + were made — proving auth blocks before business logic side effects. + Both mirrored error layers are graded against the pinned enum metadata. Per the Error Verification Policy (tests/CLAUDE.md), this asserts on the - wire envelope, not a reconstructed exception. The auth error code is - AUTH_REQUIRED on the wire (a recent reversal flipped AUTH_TOKEN_INVALID -> - AUTH_REQUIRED); the "Principal ID not found" message still holds. + wire envelope, not a reconstructed exception. Every wire transport uses + AUTH_INVALID with terminal recovery. """ from src.core.exceptions import AdCPAuthenticationError from src.core.schemas import CreateMediaBuyRequest - from tests.factories.principal import PrincipalFactory env = ctx["env"] @@ -152,14 +151,6 @@ def then_auth_before_business_logic(ctx: dict) -> None: else: assert resp is not None, "Expected either a response or an error" - # Now make a SECOND call with invalid credentials to prove ordering. - # Build an identity with no principal_id — auth should reject before - # any business logic (adapter, DB writes) executes. - invalid_identity = PrincipalFactory.make_identity( - principal_id=None, - tenant_id=env._tenant_id, - ) - # Reset adapter mock call count to detect any side effects mock_adapter = env.mock["adapter"].return_value mock_adapter.create_media_buy.reset_mock() @@ -168,17 +159,16 @@ def then_auth_before_business_logic(ctx: dict) -> None: request_kwargs = ctx.get("request_kwargs", {}) req = CreateMediaBuyRequest(**request_kwargs) - # Dispatch through the wire with the invalid identity — the parametrized - # transport (a2a/mcp/rest) actually exercises the auth gate on the wire. + # Present a token that has no principal row. The harness deliberately + # disables identity injection/REST dependency overrides in this mode. auth_ctx: dict = {k: ctx[k] for k in ("env", "transport", "e2e_config") if k in ctx} - dispatch_request(auth_ctx, req=req, identity=invalid_identity) + dispatch_request(auth_ctx, req=req, presented_auth_token="expired-bdd-auth-token") + + from tests.helpers.auth_contract import assert_two_layer_auth_contract result = auth_ctx.get("result") - assert result is not None, "dispatch_request did not produce a TransportResult for the invalid-identity request" - # recovery omitted -> defaults to the pinned AUTH_REQUIRED enum (correctable). Do not - # pass an explicit recovery= that shadows the pinned enum (#1417: superseded - # the earlier terminal override; the pinned enum is the single source of truth). - result.assert_wire_error("AUTH_REQUIRED", message_substr="Principal ID not found") + assert result is not None, "dispatch_request did not produce a TransportResult for the invalid-token request" + assert_two_layer_auth_contract(result.wire_error_envelope, ctx["transport"], "invalid") # Verify no business logic side effects occurred assert not mock_adapter.create_media_buy.called, ( diff --git a/tests/bdd/steps/domain/uc002_task_query.py b/tests/bdd/steps/domain/uc002_task_query.py index f3fc076c72..c0f51fea82 100644 --- a/tests/bdd/steps/domain/uc002_task_query.py +++ b/tests/bdd/steps/domain/uc002_task_query.py @@ -222,6 +222,7 @@ def _dispatch_list_tasks_e2e(ctx: dict, **params: Any) -> dict: repo = WorkflowRepository(env._session, env.identity.tenant_id) steps = repo.list_by_tenant( + principal_id=env.identity.principal_id, status=params.get("status"), object_type=params.get("object_type"), object_id=params.get("object_id"), diff --git a/tests/bdd/steps/domain/uc003_update_media_buy.py b/tests/bdd/steps/domain/uc003_update_media_buy.py index 2848d112a7..889d9176bd 100644 --- a/tests/bdd/steps/domain/uc003_update_media_buy.py +++ b/tests/bdd/steps/domain/uc003_update_media_buy.py @@ -816,7 +816,9 @@ def when_send_update_request(ctx: dict) -> None: ctx["error"] = e return - if ctx.get("has_auth") is False: + if "presented_auth_token" in ctx: + dispatch_request(ctx, req=req, presented_auth_token=ctx["presented_auth_token"]) + elif ctx.get("has_auth") is False: dispatch_request(ctx, req=req, identity=None) else: dispatch_request(ctx, req=req) diff --git a/tests/bdd/steps/domain/uc011_accounts.py b/tests/bdd/steps/domain/uc011_accounts.py index edac910cf3..18c6b18a92 100644 --- a/tests/bdd/steps/domain/uc011_accounts.py +++ b/tests/bdd/steps/domain/uc011_accounts.py @@ -172,11 +172,12 @@ def given_unauthenticated(ctx: dict, transport: str | None = None) -> None: ctx["force_identity"] = None -@given("the Buyer Agent has an A2A connection with an expired token") +@given("the Buyer Agent presents an expired authentication credential") def given_expired_token(ctx: dict) -> None: - """Set up A2A connection with an expired/invalid token.""" + """Set up a real wire credential that resolves to no valid principal.""" + _setup_tenant_and_principal(ctx) ctx["has_auth"] = False - ctx["force_identity"] = None + ctx["presented_auth_token"] = "expired-bdd-auth-token" @given("the sync_accounts response schema uses oneOf") @@ -827,7 +828,7 @@ def when_sync_accounts_with_table(ctx: dict, datatable: Any) -> None: """Send sync_accounts with accounts from Gherkin data table. pytest-bdd datatable: list of lists. First row = headers, rest = data rows. - Handles force_identity (unauthenticated) and force_internal_error contexts. + Handles unauthenticated, expired-token, and forced-internal-error contexts. """ from src.core.schemas.account import SyncAccountsRequest @@ -839,9 +840,12 @@ def when_sync_accounts_with_table(ctx: dict, datatable: Any) -> None: kwargs: dict[str, Any] = {} - # Handle forced identity (unauthenticated/expired token) + # Missing credentials use an explicit identity=None. Expired credentials + # are presented on the real transport so production resolves and rejects. if "force_identity" in ctx: kwargs["identity"] = ctx["force_identity"] + if "presented_auth_token" in ctx: + kwargs["presented_auth_token"] = ctx["presented_auth_token"] # Handle forced internal error if ctx.get("force_internal_error"): @@ -2024,6 +2028,8 @@ def when_request_with_context(ctx: dict, operation: str, ctx_json: str) -> None: dispatch_kwargs: dict[str, Any] = {} if "force_identity" in ctx: dispatch_kwargs["identity"] = ctx["force_identity"] + if "presented_auth_token" in ctx: + dispatch_kwargs["presented_auth_token"] = ctx["presented_auth_token"] try: dispatch_request(ctx, req=req, **dispatch_kwargs) @@ -2242,13 +2248,32 @@ def then_error_with_code(ctx: dict, code: str) -> None: @then("the error indicates accounts array must not be empty") def then_empty_accounts_error(ctx: dict) -> None: - """Assert the error is a validation error about empty accounts array. - - Production raises AdCPValidationError with a message containing - 'accounts array must not be empty'. + """Assert the buyer is told WHICH constraint they violated, on the wire. + + The step name is the contract: the error must *indicate* the empty-array + rejection. The wire branch previously asserted the opposite — that the text + was scrubbed OFF the wire — which was right only while every literal + validation message was genericized by default. The raise site interpolates + no request data (a bare literal), so it opts in via ``_wire_safe_message`` + and the buyer keeps the one diagnostic they can act on; the rejection is + ``recovery: correctable``, i.e. they are expected to fix it themselves. """ from src.core.exceptions import AdCPValidationError + result = ctx.get("result") + envelope = getattr(result, "wire_error_envelope", None) if result is not None else None + if envelope: + from tests.helpers import assert_envelope_shape + from tests.helpers.secret_scrub import assert_no_secret_leak + + assert_envelope_shape(envelope, "VALIDATION_ERROR", recovery="correctable") + for layer, error in (("adcp_error", envelope["adcp_error"]), ("errors[0]", envelope["errors"][0])): + assert "accounts array must not be empty" in error["message"], ( + f"{layer} must name the violated constraint on the wire, got {error['message']!r}" + ) + assert_no_secret_leak(envelope) + return + error = _get_error(ctx) assert isinstance(error, (AdCPValidationError, ValueError)), ( f"Expected AdCPValidationError, got {type(error).__name__}: {error}" diff --git a/tests/bdd/steps/generic/then_error.py b/tests/bdd/steps/generic/then_error.py index 886e16be57..baf1c03fc7 100644 --- a/tests/bdd/steps/generic/then_error.py +++ b/tests/bdd/steps/generic/then_error.py @@ -9,8 +9,24 @@ from __future__ import annotations +import json +import re + from pytest_bdd import parsers, then +from tests.helpers.auth_contract import ( + CredentialState, + assert_two_layer_auth_contract, +) + +# The complete key set an auth-rejection envelope layer may carry, verified against what +# AdCPAuthMissingError / AdCPAuthInvalidError actually serialize. Deliberately EXCLUDES +# ``details`` and ``field``: authentication fails BEFORE account resolution, so there is no +# resolution payload to attach, and any such payload is the disclosure the step below exists +# to prevent. Adding a key here is a decision that the new field cannot describe account +# resolution — not a way to make a failing assertion pass. +_AUTH_ENVELOPE_ALLOWED_KEYS = frozenset({"code", "message", "recovery", "suggestion"}) + # ── Helpers ───────────────────────────────────────────────────────── @@ -283,16 +299,138 @@ def then_error_code(ctx: dict, code: str) -> None: assert actual == code, f"Expected error code '{code}', got '{actual}'" +def _assert_transport_auth_contract(ctx: dict, credential_state: CredentialState) -> None: + """Assert the exact pinned auth contract for the scenario's transport.""" + transport = ctx.get("transport") + assert transport is not None, "Auth wire-contract assertion requires an explicit transport" + + result = ctx.get("result") + assert result is not None, "Auth wire-contract assertion requires a TransportResult" + envelope = getattr(result, "wire_error_envelope", None) if result is not None else None + assert envelope is not None, "Auth wire-contract assertion requires the serialized two-layer error envelope" + assert_two_layer_auth_contract(envelope, transport, credential_state) + + +@then("the authentication error should match missing credentials for the active transport") +def then_missing_auth_contract(ctx: dict) -> None: + """Every wire transport reports absent credentials as AUTH_MISSING.""" + _assert_transport_auth_contract(ctx, "missing") + + +@then("the authentication error should match invalid credentials for the active transport") +def then_invalid_auth_contract(ctx: dict) -> None: + """Every wire transport reports rejected credentials as AUTH_INVALID.""" + _assert_transport_auth_contract(ctx, "invalid") + + +@then("the authentication error should disclose no account resolution information") +def then_auth_error_discloses_no_account_resolution(ctx: dict) -> None: + """Reject account identifiers, natural keys, ambiguity, and match details.""" + result = ctx.get("result") + envelope = getattr(result, "wire_error_envelope", None) if result is not None else None + assert envelope is not None, "Non-disclosure assertion requires the serialized wire envelope" + + # STRUCTURE first. A guessed-literal denylist only catches phrasings someone imagined: + # four tokens this used to carry (``matched_count``, ``match_count``, ``matching + # accounts``, ``candidate_accounts``) match nothing anywhere in ``src/``. An auth + # rejection has a fixed pinned shape, so requiring EXACTLY that shape rules out an + # attached resolution payload in any phrasing, including ones nobody anticipated. + for layer_name, layer in (("adcp_error", envelope["adcp_error"]), ("errors[0]", envelope["errors"][0])): + unexpected = set(layer) - _AUTH_ENVELOPE_ALLOWED_KEYS + assert not unexpected, ( + f"{layer_name} carries {sorted(unexpected)} on an auth rejection — an authentication " + f"error has no account-resolution payload to attach. Extend " + f"_AUTH_ENVELOPE_ALLOWED_KEYS only for a field proven not to describe resolution." + ) + + # Then content, restricted to data THIS scenario created, so the check cannot pass by + # ruling out strings production never had a way to emit. The count is the datum the + # ambiguity path would disclose, and the Given now records it. + # ensure_ascii=False on purpose: the default escapes non-ASCII, and the pinned auth + # suggestion contains an em dash, so the serialized form would carry the literal + # "\u2014" — whose digits then collide with a numeric match-count token. + serialized = json.dumps(envelope, sort_keys=True, ensure_ascii=False).lower() + forbidden = { + str(ctx.get("request_brand", "")).lower(), + str(ctx.get("request_operator", "")).lower(), + # The only two remaining literals that exist in src/: the ambiguity code, and the + # account_id prefix the multi-match Given generates. + "account_ambiguous", + "acc-multi-", + } + leaked = sorted(value for value in forbidden if value and value in serialized) + + # The match COUNT is the datum the ambiguity path would disclose, and the Given records + # it. Matched on a word boundary rather than as a substring: a small integer occurs + # inside unrelated tokens (version numbers, escapes, ids) and a bare `in` check would + # fire on those instead of on a disclosed count. + match_count = ctx.get("natural_key_match_count") + if match_count is not None and re.search(rf"\b{re.escape(str(match_count))}\b", serialized): + leaked.append(f"match count {match_count}") + + assert not leaked, f"Authentication envelope leaked account-resolution information: {sorted(leaked)}" + + # ── Error message content (generic) ─────────────────────────────────── @then(parsers.parse('the error message should contain "{text}"')) def then_error_message_contains(ctx: dict, text: str) -> None: - """Assert error message contains the given text (case-insensitive).""" - error = ctx.get("error") - assert error is not None, "No error recorded in ctx" - msg = _get_error_message(error).lower() - assert text.lower() in msg, f"Expected '{text}' in error message: {_get_error_message(error)}" + """Assert the error message contains the given text — wire-first, reconstructed fallback. + + A pure literal containment check, matching every sibling step in this file + (``_wire_code``, ``_wire_suggestion``). It does NOT special-case sanitized + codes: a scenario asserting the buyer-facing NON-DISCLOSURE contract for a + scrubbed message must use ``the error message should be sanitized, not + disclosing "..."`` below instead. An assertion that silently flips to + checking ABSENCE when a code happens to be scrubbed is indistinguishable, + from the Gherkin, from checking PRESENCE — the same English step would mean + opposite things depending on the response code, and 190+ scenarios could + pass after their expected diagnostic silently disappeared. + """ + wire_error = _wire_error_object(ctx) + if wire_error is not None: + msg = str(wire_error.get("message", "")).lower() + else: + error = ctx.get("error") + assert error is not None, "No error recorded in ctx" + msg = _get_error_message(error).lower() + assert text.lower() in msg, f"Expected '{text}' in error message: {msg}" + + +# NOTE ON BINDING: this step is bound by ZERO feature scenarios today. Its intended home was +# the uc011 empty-accounts scenario, but that raise site is a bare literal, so the opt-in sweep +# restored its text to the wire and the scenario correctly asserts PRESENCE instead — the +# opposite contract. It is kept rather than deleted because it is NOT dead: it is exercised by +# tests/unit/test_generic_then_devacuum.py, which uses it to prove the scrub genuinely removes +# an untrusted fragment AND that "should contain" no longer silently flips to an absence check. +# It is the correct primitive for the 17 interpolated raise sites that are still scrubbed; bind +# it when a scenario covers one, rather than letting a containment step double as a +# non-disclosure step. +@then(parsers.parse('the error message should be sanitized, not disclosing "{text}"')) +def then_error_message_sanitized_without_disclosing(ctx: dict, text: str) -> None: + """Assert the wire error uses the canonical scrubbed presentation and never echoes ``text``. + + The dedicated non-disclosure step: production replaces an unaudited raw + message (which may interpolate rejected buyer input or adapter internals) + with the canonical sanitized message/suggestion on BOTH envelope layers. + Distinct from ``the error message should contain "..."`` above, which is a + literal containment check — a scenario asserting non-disclosure must name + that explicitly rather than relying on a containment step to double as one. + """ + result = ctx.get("result") + envelope = getattr(result, "wire_error_envelope", None) if result is not None else None + assert envelope is not None, "Sanitization assertion requires a captured wire error envelope" + + from src.core.exceptions import _SANITIZED_BY_WIRE_CODE + from tests.helpers.secret_scrub import assert_sanitized_wire_error + + code = (envelope.get("adcp_error") or {}).get("code") + assert code in _SANITIZED_BY_WIRE_CODE, ( + f"{code!r} has no canonical sanitized presentation — this step only applies to codes " + "production scrubs (VALIDATION_ERROR / INVALID_REQUEST / AUTH_REQUIRED)" + ) + assert_sanitized_wire_error(envelope, code, rejected_fragments=(text,)) @then(parsers.parse('the suggestion should contain "{text}"')) @@ -435,6 +573,25 @@ def then_error_recovery(ctx: dict, recovery: str) -> None: raise AssertionError(f"Cannot check recovery on non-AdCPError: {type(error).__name__}") +@then(parsers.parse('the wire error envelope should carry code "{code}" with recovery "{recovery}"')) +def then_wire_error_envelope_shape(ctx: dict, code: str, recovery: str) -> None: + """Assert the two-layer AdCP envelope shape on the captured wire envelope. + + Wire-envelope variant of the error-code/recovery steps above (tests/CLAUDE.md + § Error Verification Policy): asserts on ``ctx["wire_error_envelope"]``, the + envelope captured off the wire by the dispatching When step, rather than the + lossy reconstructed exception in ``ctx["error"]``. + """ + from tests.helpers import assert_envelope_shape + + envelope = ctx.get("wire_error_envelope") + assert envelope is not None, ( + f"No wire error envelope captured in ctx — the operation succeeded or the " + f"When step does not populate ctx['wire_error_envelope']. response={ctx.get('response')!r}" + ) + assert_envelope_shape(envelope, code, recovery=recovery) + + @then('the error should include a "suggestion" field') @then('the error should include "suggestion" field') def then_error_has_suggestion(ctx: dict) -> None: diff --git a/tests/conftest_db.py b/tests/conftest_db.py index daa393ae75..a0c5087121 100644 --- a/tests/conftest_db.py +++ b/tests/conftest_db.py @@ -694,3 +694,41 @@ def inspect(engine): from sqlalchemy import inspect as sqlalchemy_inspect return sqlalchemy_inspect(engine) + + +@pytest.fixture +def factory_session(integration_db): + """Bind all factory_boy factories to the isolated integration PostgreSQL session. + + Shared home (star-imported into the root conftest, so it is available to every suite — + admin, integration, bdd). Depends on ``integration_db`` so the bound session points at a + migrated, per-test-isolated database, NOT the runner's base DB. Use it in tests that create + data via factories (e.g. ``MediaBuyFactory(...)``) instead of inline ``session.add()``. + + Returns the bound session for post-write DB state assertions. + + Note: the binding lives on each factory's class attributes, i.e. process-wide state. The + ``assert ... is None`` precondition catches nested/concurrent use within a worker; factories + are unbound on teardown so the binding never leaks. (pytest-xdist ``--dist=load`` is fine; + avoid ``--dist=each``.) + """ + from sqlalchemy.orm import Session as SASession + + from src.core.database.database_session import get_engine + from tests.factories import ALL_FACTORIES + + for f in ALL_FACTORIES: + assert f._meta.sqlalchemy_session is None, ( + f"Factory {f.__name__} session already bound — nested factory_session fixtures are not supported" + ) + + session = SASession(bind=get_engine()) + for f in ALL_FACTORIES: + f._meta.sqlalchemy_session = session + + try: + yield session + finally: + for f in ALL_FACTORIES: + f._meta.sqlalchemy_session = None + session.close() diff --git a/tests/e2e/conftest.py b/tests/e2e/conftest.py index 9515de7f75..db3c0de475 100644 --- a/tests/e2e/conftest.py +++ b/tests/e2e/conftest.py @@ -217,6 +217,11 @@ def docker_services_e2e(request): # test_landing_pages.py) pick up the correct dynamic ports os.environ["ADCP_SALES_PORT"] = str(mcp_port) os.environ["POSTGRES_PORT"] = str(postgres_port) + # The receiver runs on the host while the application runs in Docker. + # Use Docker's explicit host gateway for both the emitted callback URL + # and the server's exact development-only SSRF test seam. + os.environ["ADCP_WEBHOOK_HOST"] = "host.docker.internal" + os.environ["ADCP_WEBHOOK_TEST_HOST"] = "host.docker.internal" env = os.environ.copy() # Set 5 seconds interval for delivery webhooks in E2E tests diff --git a/tests/e2e/test_a2a_endpoints_working.py b/tests/e2e/test_a2a_endpoints_working.py index 32f8e07f2a..a7cb23ed88 100644 --- a/tests/e2e/test_a2a_endpoints_working.py +++ b/tests/e2e/test_a2a_endpoints_working.py @@ -11,7 +11,7 @@ import json import os import sys -from unittest.mock import MagicMock +from unittest.mock import MagicMock, patch import pytest import requests @@ -310,25 +310,40 @@ def test_handler_has_required_methods(self): async def test_unknown_task_id_raises_task_not_found(self, request_cls, method_name): """An unknown task id raises TaskNotFoundError, not the generic internal error a bare None return produces — cancel is the same not-found condition - as get, and both route through the shared ``_get_task_or_raise``. + as get. Both ``on_get_task`` and ``on_cancel_task`` raise it identically + when neither the in-memory nor the durable store has the task. Fast smoke check on the raise only. It does NOT prove the wire code: the exception carries no code, and the client actually sees -32603 — see - ``_get_task_or_raise`` (src/a2a_server/adcp_a2a_server.py) and #1670 for - why, plus the xfail'd live-server test in TestA2AServerIntegration that - grades the code on the wire. Assert on str(exc), not exc.code — there is - none. + # See the xfail'd live-server test in + TestA2AServerIntegration that grades the code on the wire. Assert on + str(exc), not exc.code — there is none. Parametrized over both entry points so the shared assertion cannot drift - between two byte-identical copies. + between the two. + + Identity resolves successfully (both handlers need tenant+principal scope + before consulting either store) but neither store has anything for this + id: the in-memory map is empty, and the durable lookup is mocked to + return None — keeping this a fast unit-altitude smoke check with no real + DB, per the test's own intent, rather than the durable-lookup path itself + (that's covered at integration altitude elsewhere). Both halves of the raise are pinned: the human-readable message AND the structured ``data`` payload clients actually parse. Asserting the message alone would let ``data={"task_id": ...}`` be deleted with the suite still green, since the id appears in the message either way. """ - with pytest.raises(TaskNotFoundError) as exc: - await getattr(self.handler, method_name)(request_cls(id="task_does_not_exist"), MagicMock()) + from tests.utils.a2a_helpers import make_test_a2a_identity + + identity = make_test_a2a_identity() + with ( + patch.object(self.handler, "_resolve_a2a_identity", return_value=identity), + patch.object(self.handler, "_durable_task_from_step", return_value=None), + patch.object(self.handler, "_durable_cancel_step", return_value=None), + ): + with pytest.raises(TaskNotFoundError) as exc: + await getattr(self.handler, method_name)(request_cls(id="task_does_not_exist"), MagicMock()) assert "task_does_not_exist" in str(exc.value) # the requested id is surfaced assert exc.value.data == {"task_id": "task_does_not_exist"} # ...and machine-readable diff --git a/tests/e2e/test_a2a_webhook_payload_types.py b/tests/e2e/test_a2a_webhook_payload_types.py index 2e0e1963dd..82c0e65382 100644 --- a/tests/e2e/test_a2a_webhook_payload_types.py +++ b/tests/e2e/test_a2a_webhook_payload_types.py @@ -9,7 +9,9 @@ This test validates that our A2A server sends the correct payload type based on status. """ +import asyncio import uuid +from threading import Event from time import sleep from typing import Any @@ -118,11 +120,41 @@ def assert_no_classification_errors(received: list[dict[str, Any]]) -> None: class WebhookPayloadCapture(WebhookCaptureHandler): """Webhook receiver that captures each payload with its A2A classification. - Extends the shared capture handler via the ``record`` hook — only the - classification logic lives here, never a copied ``do_POST``. + Extends the shared capture handler via the ``record`` hook. The ``do_POST`` + override adds only the test ordering barrier, then delegates all HTTP + framing and capture behavior to the shared implementation. """ received_webhooks: list[dict[str, Any]] = [] + block_requests = False + request_started = Event() + release_requests = Event() + request_completed = Event() + + @classmethod + def arm_request_barrier(cls) -> None: + """Block webhook responses until the E2E request reaches its ordering checkpoint.""" + cls.request_started.clear() + cls.release_requests.clear() + cls.request_completed.clear() + cls.block_requests = True + + @classmethod + def disarm_request_barrier(cls) -> None: + """Release blocked webhooks and restore normal capture behavior.""" + cls.block_requests = False + cls.release_requests.set() + + def do_POST(self): + """Optionally hold webhook responses so ordering assertions are deterministic.""" + if self.block_requests: + self.request_started.set() + if not self.release_requests.wait(timeout=30.0): + raise TimeoutError("Webhook request barrier was not released") + try: + super().do_POST() + finally: + self.request_completed.set() def record(self, payload): # Extract status @@ -159,8 +191,14 @@ def record(self, payload): @pytest.fixture def webhook_capture_server(): """Start a local HTTP server to capture webhook payloads.""" - with run_webhook_capture_server(WebhookPayloadCapture, WebhookPayloadCapture.received_webhooks) as info: - yield info + WebhookPayloadCapture.disarm_request_barrier() + WebhookPayloadCapture.request_started.clear() + WebhookPayloadCapture.request_completed.clear() + try: + with run_webhook_capture_server(WebhookPayloadCapture, WebhookPayloadCapture.received_webhooks) as info: + yield info + finally: + WebhookPayloadCapture.disarm_request_barrier() class TestA2AWebhookPayloadTypes: @@ -175,11 +213,13 @@ async def test_completed_status_sends_task_payload( webhook_capture_server, ): """ - Test that completed status sends a Task payload (not TaskStatusUpdateEvent). + Test that the completed-status webhook is a Task payload with artifacts. - Per AdCP spec: - - Completed is a final state - - Final states should send Task object with artifacts + `on_message_send` sends no webhook for its immediate-terminal response + (a2a-guide.mdx; unit-pinned separately). The completed *Task* webhook a + buyer receives comes from the async workflow-step completion (context + manager). Per AdCP spec a final-state webhook carries the full Task with + artifacts — this validates that payload shape. """ # Enable auto-approval so create_media_buy completes immediately set_live_adapter_behavior(live_server, manual_approval_required=False) @@ -215,56 +255,86 @@ async def test_completed_status_sends_task_payload( "x-adcp-tenant": "ci-test", } + # Hold the legitimate workflow webhook at the capture boundary while the + # A2A request is in flight. The workflow notification is scheduled in the + # background, so the response must complete while it is blocked. Re-adding + # an immediate-terminal webhook makes ``on_message_send`` await that blocked + # delivery, preventing the response from completing at this checkpoint. + WebhookPayloadCapture.arm_request_barrier() + response_completed_while_blocked = False + response: httpx.Response | None = None async with httpx.AsyncClient(timeout=30.0) as client: - response = await client.post(a2a_url, json=message, headers=headers) + response_task = asyncio.create_task(client.post(a2a_url, json=message, headers=headers)) + try: + webhook_started = await asyncio.to_thread(WebhookPayloadCapture.request_started.wait, 15.0) + if webhook_started: + try: + response = await asyncio.wait_for(asyncio.shield(response_task), timeout=5.0) + response_completed_while_blocked = True + except TimeoutError: + response = None + finally: + WebhookPayloadCapture.disarm_request_barrier() + assert webhook_started, "Workflow completion webhook did not reach the capture barrier" + if response is None: + response = await response_task + assert response_completed_while_blocked, ( + "A2A response waited for a blocked webhook delivery; an immediate-terminal " + "response must not send a webhook" + ) + assert response is not None # Request should succeed assert response.status_code == 200, f"A2A request failed: {response.text}" result = response.json() assert "error" not in result, f"A2A error: {result.get('error')}" + webhook_completed = await asyncio.to_thread(WebhookPayloadCapture.request_completed.wait, 15.0) + assert webhook_completed, "Released workflow webhook did not complete" + + # The A2A message Task completes SYNCHRONOUSLY (auto-approval) and is returned + # in this response; per a2a-guide.mdx `on_message_send` sends NO webhook for + # that immediate-terminal response (unit-pinned in + # test_immediate_completed_task_sends_no_webhook). The completed *Task* webhook + # observed here is the LEGITIMATE async workflow-step completion emitted by the + # context manager (create_a2a_webhook_payload with status=completed), which is + # what a buyer subscribes to — this test verifies THAT payload's shape. + sync_task = result.get("result", {}) + sync_task = sync_task.get("task", sync_task) + assert sync_task.get("id"), "Sync response must be a Task with an 'id'" - # Wait for webhook to be delivered - timeout_seconds = 15 - poll_interval = 0.5 - elapsed = 0 - - while elapsed < timeout_seconds and not webhook_capture_server["received"]: - sleep(poll_interval) - elapsed += poll_interval - - # Verify webhook was received received = webhook_capture_server["received"] - assert received, "Expected at least one webhook delivery" - - # No received webhook may carry a snake_case wire violation (gh-#1299). + assert received, "Expected an async workflow completion webhook" assert_no_classification_errors(received) - # The completed-status webhook MUST be present and MUST be a Task. No - # `if completed_webhooks:` guard — a missing or misclassified webhook is - # a failure, not a silent pass. completed_webhooks = [w for w in received if w["status"] == "completed"] assert completed_webhooks, ( f"Expected a 'completed' status webhook. Received statuses: {[w['status'] for w in received]}" ) - + # a2a-guide.mdx terminal-state rule: an already-terminal initial response must + # NOT trigger its own webhook — the buyer receives exactly ONE completed + # webhook (the async workflow-step completion), never an on_message_send + # duplicate. (Unit pin: test_immediate_completed_task_sends_no_webhook.) + assert len(completed_webhooks) == 1, ( + f"Expected exactly one completed webhook (the async workflow completion); " + f"a second one means on_message_send webhooked its immediate-terminal " + f"response. Received: {[(w['status'], w['payload'].get('id')) for w in received]}" + ) webhook = completed_webhooks[0] - # Per AdCP spec: completed status should send Task (has 'id' field) assert webhook["payload_type"] == "Task", ( - f"Completed status should send Task payload, not {webhook['payload_type']}. " - f"Payload has 'id': {'id' in webhook['payload']}, 'taskId': {'taskId' in webhook['payload']}" + f"completed status must send a Task payload, got {webhook['payload_type']}" + ) + wpayload = webhook["payload"] + assert "id" in wpayload, "Task payload must have 'id'" + assert "status" in wpayload, "Task payload must have 'status'" + assert wpayload.get("artifacts"), "completed Task must carry artifacts" + assert wpayload["artifacts"][0].get("parts"), "artifact must have parts" + # The completion webhook must correlate to the id the BUYER holds — + # the outer task_* returned in the sync response — NOT the internal step_id. + # (Pre-fix this sent task_id=step_id, which the buyer never saw.) + assert wpayload["id"] == sync_task["id"], ( + f"webhook task id {wpayload['id']!r} must equal the returned Task id " + f"{sync_task['id']!r} (buyer correlation), not the internal step_id" ) - - # Verify Task structure - payload = webhook["payload"] - assert "id" in payload, "Task payload must have 'id' field" - assert "status" in payload, "Task payload must have 'status' field" - - # Per AdCP spec: completed status MUST have result in artifacts[0].parts[] - assert "artifacts" in payload, "Completed Task must have 'artifacts' field" - assert len(payload["artifacts"]) > 0, "Completed Task must have at least one artifact" - artifact = payload["artifacts"][0] - assert "parts" in artifact, "Artifact must have 'parts' field" - assert len(artifact["parts"]) > 0, "Artifact must have at least one part" @pytest.mark.asyncio async def test_submitted_status_sends_task_status_update_event( @@ -383,8 +453,11 @@ async def test_webhook_payload_type_matches_status( - Final states (completed, failed, canceled): Task - Intermediate states (working, input-required, submitted): TaskStatusUpdateEvent """ - # Enable auto-approval - set_live_adapter_behavior(live_server, manual_approval_required=False) + # Manual approval → submitted (a non-terminal initial response that DOES webhook), so a + # real wire webhook is delivered to classify. This PR stops immediate terminal A2A tasks + # from webhooking, so auto-approval would deliver nothing and `assert received` below would + # fail — manual approval is required to exercise the payload-type classification. + set_live_adapter_behavior(live_server, manual_approval_required=True) a2a_url = f"{live_server['a2a']}/a2a" context_id = str(uuid.uuid4()) @@ -501,41 +574,33 @@ async def test_task_payload_has_required_fields( } async with httpx.AsyncClient(timeout=30.0) as client: - await client.post(a2a_url, json=message, headers=headers) + response = await client.post(a2a_url, json=message, headers=headers) + assert response.status_code == 200, f"A2A request failed: {response.text}" + result = response.json() + assert "error" not in result, f"A2A error: {result.get('error')}" - # Wait for webhook - timeout_seconds = 15 - elapsed = 0 - while elapsed < timeout_seconds and not webhook_capture_server["received"]: + # `on_message_send` sends no webhook for the immediate-terminal response; + # the Task webhook comes from the async workflow-step completion (context + # manager). Validate its required A2A Task fields. + elapsed = 0.0 + while elapsed < 15.0 and not webhook_capture_server["received"]: sleep(0.5) elapsed += 0.5 - received = webhook_capture_server["received"] - assert received, "Expected at least one webhook delivery" + assert received, "Expected an async workflow completion webhook" assert_no_classification_errors(received) task_webhooks = [w for w in received if w["payload_type"] == "Task"] assert task_webhooks, ( f"Expected at least one Task webhook. Received payload types: {[w['payload_type'] for w in received]}" ) - for webhook in task_webhooks: payload = webhook["payload"] - - # Required Task fields per A2A spec assert "id" in payload, "Task must have 'id' field" - assert "status" in payload, "Task must have 'status' field" - - status = payload["status"] - assert "state" in status, "Task.status must have 'state' field" - - # Per AdCP spec: completed/failed MUST have result in artifacts[0].parts[] - if status["state"] in ("completed", "failed"): - assert "artifacts" in payload, f"Task with status '{status['state']}' must have 'artifacts'" - assert isinstance(payload["artifacts"], list), "artifacts must be a list" - assert len(payload["artifacts"]) > 0, "artifacts must have at least one item" - assert "parts" in payload["artifacts"][0], "artifact must have 'parts'" - assert len(payload["artifacts"][0]["parts"]) > 0, "artifact.parts must have at least one part" + assert "status" in payload and "state" in payload["status"], "Task.status must have 'state'" + if payload["status"]["state"] in ("completed", "failed"): + assert isinstance(payload.get("artifacts"), list) and payload["artifacts"], "must have artifacts" + assert payload["artifacts"][0].get("parts"), "artifact must have parts" @pytest.mark.asyncio async def test_task_status_update_event_has_required_fields( @@ -634,13 +699,23 @@ def _send_and_capture(self, payload) -> dict[str, Any]: # host='127.0.0.1': this class is unit-style (no Docker) — the service # runs in-process, so loopback is always the right callback host. - # Real outbound validator allows localhost when ADCP_TESTING=true - # (do not patch the SSRF gate — that would hide regressions). + # The SSRF gate is NOT patched — that would hide regressions. It is + # satisfied for real by naming this exact loopback host through the + # development-only test-host seam, the same mechanism the Docker E2E + # stack uses for its own callback host, so the real + # validate_protocol_webhook_url still runs and still has to pass. with ( run_webhook_capture_server( WebhookPayloadCapture, WebhookPayloadCapture.received_webhooks, host="127.0.0.1" ) as info, - patch.dict("os.environ", {"ADCP_TESTING": "true"}), + patch.dict( + "os.environ", + { + "ADCP_TESTING": "true", + "ENVIRONMENT": "development", + "ADCP_WEBHOOK_TEST_HOST": "127.0.0.1", + }, + ), ): config = PushNotificationConfig( id="pnc-test", diff --git a/tests/e2e/test_adcp_reference_implementation.py b/tests/e2e/test_adcp_reference_implementation.py index 8ff952ee22..3aef505ad0 100644 --- a/tests/e2e/test_adcp_reference_implementation.py +++ b/tests/e2e/test_adcp_reference_implementation.py @@ -28,9 +28,9 @@ class WebhookReceiver(WebhookCaptureHandler): @pytest.fixture def webhook_server(): - # Loopback-pinned: this lifecycle reaches the server over the host loopback, so the - # callback host stays 127.0.0.1 rather than honoring ADCP_WEBHOOK_HOST. - with run_webhook_capture_server(WebhookReceiver, WebhookReceiver.received_webhooks, host="127.0.0.1") as info: + # Honor ADCP_WEBHOOK_HOST so Docker and in-network runners publish a callback + # hostname that the application container can both validate and reach. + with run_webhook_capture_server(WebhookReceiver, WebhookReceiver.received_webhooks) as info: yield info diff --git a/tests/harness/_base.py b/tests/harness/_base.py index 14d2a71578..c49e01bf70 100644 --- a/tests/harness/_base.py +++ b/tests/harness/_base.py @@ -35,6 +35,7 @@ os.environ.setdefault("ADCP_RUN_BACKGROUND_SCHEDULERS", "false") if TYPE_CHECKING: + from a2a.types import Task from pydantic import BaseModel from sqlalchemy.orm import Session @@ -42,6 +43,13 @@ from tests.harness.transport import E2EConfig, Transport, TransportResult +def _serialize_a2a_parameters(parameters: dict[str, Any]) -> dict[str, Any]: + """Recursively convert A2A parameters to protobuf Struct-compatible JSON.""" + from pydantic import TypeAdapter + + return TypeAdapter(dict[str, Any]).dump_python(parameters, mode="json") + + def _adcp_error_from_code( error_code: str, message: str, @@ -64,6 +72,8 @@ def _adcp_error_from_code( AdCPAccountSuspendedError, AdCPAdapterError, AdCPAuthenticationError, + AdCPAuthInvalidError, + AdCPAuthMissingError, AdCPBudgetExhaustedError, AdCPBudgetTooLowError, AdCPCapabilityNotSupportedError, @@ -88,6 +98,8 @@ def _adcp_error_from_code( for cls in ( AdCPValidationError, AdCPAuthenticationError, + AdCPAuthMissingError, + AdCPAuthInvalidError, AdCPNotFoundError, AdCPAccountNotFoundError, AdCPAccountSetupRequiredError, @@ -264,6 +276,51 @@ def _envelope_to_adcp_error(envelope: dict, fallback_message: str = "") -> Excep return reconstructed +def _read_failed_a2a_task( + task: Task, + *, + fallback_message: str, + expect_processing_error: bool = False, +) -> tuple[dict[str, Any] | None, Exception]: + """Reconstruct ``(wire envelope, error)`` from a failed A2A Task. + + Shared failed-Task reader for the harness A2A dispatcher and the BDD NL + when-step. Skill-dispatch failures carry the envelope in an ``error_result`` + artifact (loose read); ``on_message_send``'s outer-handler failures carry it + in ``processing_error`` — pass ``expect_processing_error=True`` to pin that + strict shape (artifact present, name, single DataPart; violations raise + ``AssertionError``, including an artifact-less failed Task). On the loose + read, a missing artifact or unreconstructable envelope falls back to a bare + ``AdCPError`` describing the task status. + """ + from src.core.exceptions import AdCPError + from tests.utils.a2a_helpers import extract_data_from_artifact, extract_processing_error_envelope + + if expect_processing_error: + envelope = extract_processing_error_envelope(task) + else: + # Scan EVERY artifact for the structured error envelope — not just + # artifacts[0]. A task may carry sibling artifacts in any order, so a + # first-artifact-only read is order-dependent and can surface a non-error + # sibling. Prefer the first artifact whose DataPart is a two-layer envelope + # (``adcp_error``/``errors``); fall back to the first DataPart, then to a + # bare AdCPError. + envelope = None + for artifact in task.artifacts: + data = extract_data_from_artifact(artifact) + if isinstance(data, dict) and ("adcp_error" in data or "errors" in data): + envelope = data + break + if envelope is None and data: + envelope = data + if envelope is None: + return None, AdCPError(f"A2A task failed: {task.status}") + reconstructed = _envelope_to_adcp_error(envelope, fallback_message=fallback_message) + if reconstructed is not None: + return envelope, reconstructed + return envelope, AdCPError(f"A2A task failed: {task.status}") + + def _unwrap_a2a_server_error(exc: Exception) -> Exception: """Translate a2a A2AError back to the corresponding AdCPError. @@ -529,18 +586,31 @@ def call_via(self, transport: Transport, **kwargs: Any) -> TransportResult: """Dispatch through *transport* and return normalized TransportResult. Injects the correct identity for the transport into kwargs (unless - the caller explicitly provides one). Routes to the appropriate - dispatcher. + the caller explicitly provides one or asks the wire boundary to resolve + a presented auth token). Routes to the appropriate dispatcher. """ from tests.harness.dispatchers import DISPATCHERS - # Inject transport-correct identity - kwargs.setdefault("identity", self.identity_for(transport)) + # Presented-token seams put a credential on the transport request so + # production resolves it. Never also inject a pre-resolved identity, + # which would bypass the boundary under test. + presented_auth_key = self._validate_presented_auth_kwargs(kwargs) + if presented_auth_key is not None: + if "identity" in kwargs: + raise ValueError(f"{presented_auth_key} and identity are mutually exclusive") + else: + kwargs.setdefault("identity", self.identity_for(transport)) dispatcher = DISPATCHERS[transport] # Reset success-path wire capture; _run_a2a_handler / _run_mcp_client # set it fresh on success so A2A/MCP dispatchers can surface real wire. self._last_wire_response = None + # Same lifetime for the raw Task. Without this reset a scenario that dispatches + # twice leaves the FIRST call's Task visible, so a guard asserting on Task state + # after a second dispatch that never produced one would pass on the stale value — + # a per-call capture has to be cleared per call, or "absent" is indistinguishable + # from "left over". + self._last_a2a_task = None return dispatcher.dispatch(self, **kwargs) # -- Per-transport hooks (override in subclass) ------------------------- @@ -610,15 +680,30 @@ def _run_a2a_handler( exercises: message parsing → skill routing → normalize_request_params → handler dispatch → _serialize_for_a2a → Task/Artifact framing. - Identity is injected by monkey-patching ``_resolve_a2a_identity`` and - ``_get_auth_token`` on the handler instance — single mock point, same - as the MCP Client approach patches resolve_identity_from_context. + Identity is normally injected by monkey-patching + ``_resolve_a2a_identity`` and ``_get_auth_token`` on the handler + instance. Supplying ``presented_auth_token`` or + ``presented_legacy_auth_token`` instead puts that token in the real + AuthContext and exercises production token resolution. Args: skill_name: A2A skill name (e.g., "get_products"). response_cls: Pydantic model class to parse artifact data into. - **kwargs: Skill parameters. ``identity`` is popped and used for - the identity mock; remaining kwargs become skill parameters. + **kwargs: Skill parameters. ``identity`` or one presented-token + seam is popped for auth; ``nl_text`` (see below) is popped for + message shape; remaining kwargs become skill parameters. + + Passing ``nl_text`` sends that text as a natural-language message part + instead of an explicit skill invocation, driving ``on_message_send``'s + OUTER handler rather than skill routing — ``skill_name`` and the + remaining parameters are then unused. That path frames its failure in a + ``processing_error`` artifact rather than ``error_result``, so the failed + Task is read with ``expect_processing_error=True``, which PINS the strict + shape (artifact present, correct name, single DataPart) instead of + falling back to a bare error. Routing NL through this method rather than + a step-local copy is what keeps identity injection, ``asyncio`` driving, + Task capture and envelope stashing identical across the two message + shapes; a hand-rolled copy silently drifts from all four. """ import asyncio @@ -627,14 +712,26 @@ def _run_a2a_handler( from src.a2a_server.adcp_a2a_server import AdCPRequestHandler from tests.harness.transport import Transport - from tests.utils.a2a_helpers import create_a2a_message_with_skill, extract_data_from_artifact + from tests.utils.a2a_helpers import ( + create_a2a_message_with_skill, + extract_data_from_artifact, + make_nl_send_message_request, + ) self._commit_factory_data() + # Popped before parameter assembly so it can never leak into the skill payload. + nl_text: str | None = kwargs.pop("nl_text", None) + + presented_auth_token, presented_auth_headers = self._pop_presented_auth(kwargs) + # Pop identity — used for the handler mock, not sent as a skill parameter. _NO_OVERRIDE = object() identity = kwargs.pop("identity", _NO_OVERRIDE) - a2a_identity = self.identity_for(Transport.A2A) if identity is _NO_OVERRIDE else identity + if presented_auth_token is not None: + a2a_identity = None + else: + a2a_identity = self.identity_for(Transport.A2A) if identity is _NO_OVERRIDE else identity # The real A2A handler writes audit logs which require the tenant to exist # in the DB. Ensure the tenant record exists (idempotent) so audit logging @@ -650,6 +747,12 @@ def _run_a2a_handler( parameters = {**req_fields, **kwargs} else: parameters = dict(kwargs) + # A2A parameters cross a protobuf Struct boundary. Nested Pydantic + # models (for example ``list[CreativeAsset]``) must therefore be + # converted recursively, not left for protobuf's fallback stringifier. + # The shared serializer keeps this generic for every skill and mirrors + # ``model_dump(mode="json")`` for a top-level request model. + parameters = _serialize_a2a_parameters(parameters) handler = AdCPRequestHandler() @@ -661,14 +764,20 @@ def _run_a2a_handler( # (the in-process equivalent of MCP's get_http_headers seam) — the auth # chain itself is real. When no real token exists (unit mode), inject the # identity directly via the single mock point (unchanged behavior). - auth_token = a2a_identity.auth_token if a2a_identity else None + auth_token = ( + presented_auth_token + if presented_auth_token is not None + else (a2a_identity.auth_token if a2a_identity else None) + ) - if auth_token: + if presented_auth_token is not None or auth_token: + assert auth_token is not None from src.core.auth_context import AUTH_CONTEXT_STATE_KEY, AuthContext + credential_headers = presented_auth_headers or {"x-adcp-auth": auth_token} headers = { - "x-adcp-auth": auth_token, - "x-adcp-tenant": a2a_identity.tenant_id or "", + **credential_headers, + "x-adcp-tenant": (a2a_identity.tenant_id if a2a_identity else self._tenant_id) or "", } server_context = ServerCallContext( state={AUTH_CONTEXT_STATE_KEY: AuthContext(auth_token=auth_token, headers=headers)} @@ -689,8 +798,11 @@ def _run_a2a_handler( set_current_tenant(a2a_identity.tenant) - message = create_a2a_message_with_skill(skill_name=skill_name, parameters=parameters) - params = SendMessageRequest(message=message) + if nl_text is not None: + params = make_nl_send_message_request(nl_text) + else: + message = create_a2a_message_with_skill(skill_name=skill_name, parameters=parameters) + params = SendMessageRequest(message=message) async def _call(): return await handler.on_message_send(params, server_context) @@ -718,14 +830,13 @@ async def _call(): from a2a.types import TaskState if task_result.status.state == TaskState.TASK_STATE_FAILED: - from src.core.exceptions import AdCPError - - if task_result.artifacts: - envelope = extract_data_from_artifact(task_result.artifacts[0]) - reconstructed = _envelope_to_adcp_error(envelope, fallback_message="A2A skill failed") - if reconstructed is not None: - raise reconstructed - raise AdCPError(f"A2A task failed: {task_result.status}") + _envelope, error = _read_failed_a2a_task( + task_result, + fallback_message="A2A natural-language request failed" if nl_text else "A2A skill failed", + # The outer handler frames its failure in processing_error, not error_result. + expect_processing_error=nl_text is not None, + ) + raise error if task_result.status.state == TaskState.TASK_STATE_SUBMITTED: # Async manual-approval path: the server returns a submitted Task with NO @@ -764,10 +875,11 @@ def _run_mcp_client( Uses FastMCP's in-memory transport (FastMCPTransport) to go through the complete server path: middleware chain → TypeAdapter → tool function. - When the identity carries a real ``auth_token`` (integration mode), - patches ``get_http_headers`` so the full auth chain runs: header - extraction → tenant detection → token-to-principal DB lookup → - ResolvedIdentity from real data. + When the identity carries a real ``auth_token`` (integration mode), or + the caller supplies a presented-token seam, patches + ``get_http_headers`` so the full auth chain runs: header extraction → + tenant detection → token-to-principal DB lookup → ResolvedIdentity from + real data. When no real token is available (unit mode), patches ``resolve_identity_from_context`` directly. @@ -775,9 +887,9 @@ def _run_mcp_client( Args: tool_name: MCP tool name (e.g., "get_products"). response_cls: Pydantic model class to parse structured_content into. - **kwargs: Tool arguments. ``identity`` is popped and used for the - auth mock; ``req`` is popped and its fields unpacked into the - arguments dict. + **kwargs: Tool arguments. ``identity`` or one presented-token seam + is popped for auth; ``req`` is popped and its fields unpacked + into the arguments dict. """ import asyncio from unittest.mock import patch @@ -789,10 +901,15 @@ def _run_mcp_client( self._commit_factory_data() + presented_auth_token, presented_auth_headers = self._pop_presented_auth(kwargs) + # Pop identity — used for the auth mock, not sent as a tool argument. _NO_OVERRIDE = object() identity = kwargs.pop("identity", _NO_OVERRIDE) - mcp_identity = self.identity_for(Transport.MCP) if identity is _NO_OVERRIDE else identity + if presented_auth_token is not None: + mcp_identity = None + else: + mcp_identity = self.identity_for(Transport.MCP) if identity is _NO_OVERRIDE else identity # Unpack req object into flat arguments if present. # MCP tools accept individual params, not a request model. @@ -805,16 +922,22 @@ def _run_mcp_client( arguments = dict(kwargs) # Choose auth strategy based on whether we have a real DB token. - auth_token = mcp_identity.auth_token if mcp_identity else None + auth_token = ( + presented_auth_token + if presented_auth_token is not None + else (mcp_identity.auth_token if mcp_identity else None) + ) - if auth_token: + if presented_auth_token is not None or auth_token: + assert auth_token is not None # Real auth chain: header → token → DB lookup → identity. # Patch get_http_headers in BOTH modules that import it: # transport_helpers (called by resolve_identity_from_context) and # mcp_auth_middleware (called for context_id extraction). + credential_headers = presented_auth_headers or {"x-adcp-auth": auth_token} headers = { - "x-adcp-auth": auth_token, - "x-adcp-tenant": mcp_identity.tenant_id or "", + **credential_headers, + "x-adcp-tenant": (mcp_identity.tenant_id if mcp_identity else self._tenant_id) or "", } async def _call(): @@ -901,35 +1024,75 @@ def _run_rest_request(self, endpoint: str, **kwargs: Any) -> Any: 5. Return raw httpx.Response Identity handling (mirrors production auth middleware): - - identity is None → dep raises AUTH_REQUIRED (no token) with suggestion + - identity is None → dep raises AUTH_MISSING (no token) with suggestion - identity is ResolvedIdentity → dep returns it (valid token) - identity absent → uses default self.identity_for(Transport.REST) """ - client, identity = self._prepare_rest_request(kwargs) + client, identity, headers = self._prepare_rest_request(kwargs) body = self.build_rest_body(**kwargs) - return client.post(endpoint, json=body) + return client.post(endpoint, json=body, headers=headers) - def _prepare_rest_request(self, kwargs: dict[str, Any]) -> tuple[Any, Any]: + @staticmethod + def _validate_presented_auth_kwargs(kwargs: dict[str, Any]) -> str | None: + """Validate and identify the single real-auth harness seam in use.""" + keys = [key for key in ("presented_auth_token", "presented_legacy_auth_token") if key in kwargs] + if len(keys) > 1: + raise ValueError("presented_auth_token and presented_legacy_auth_token are mutually exclusive") + if not keys: + return None + key = keys[0] + if not isinstance(kwargs[key], str): + raise TypeError(f"{key} must be a string") + return key + + @classmethod + def _pop_presented_auth(cls, kwargs: dict[str, Any]) -> tuple[str | None, dict[str, str]]: + """Pop a real-auth seam and return its token plus exact wire header.""" + key = cls._validate_presented_auth_kwargs(kwargs) + if key is None: + return None, {} + token = kwargs.pop(key) + header = "Authorization" if key == "presented_auth_token" else "x-adcp-auth" + value = f"Bearer {token}" if header == "Authorization" else token + return token, {header: value} + + def _prepare_rest_request(self, kwargs: dict[str, Any]) -> tuple[Any, Any, dict[str, str]]: """Resolve identity, commit factory data, get the client, and install auth. Single source of truth for the REST request preamble every dispatcher - shares: pops ``identity`` from *kwargs* (defaulting to the REST identity), - commits pending factory rows, creates/returns the TestClient, and installs - the per-request auth-dep override (which must run AFTER ``get_rest_client``). - Returns ``(client, resolved_identity)``; the caller builds the body from the - now-identity-free *kwargs* and issues the HTTP verb. + shares. Either presented-token seam selects the real production + dependency path and is sent as its exact request header; otherwise this + installs the normal per-request identity override. Returns + ``(client, identity, headers)``. """ from tests.harness.transport import Transport + presented_auth_token, presented_auth_headers = self._pop_presented_auth(kwargs) _NO_OVERRIDE = object() identity = kwargs.pop("identity", _NO_OVERRIDE) - if identity is _NO_OVERRIDE: + if presented_auth_token is not None: + identity = None + elif identity is _NO_OVERRIDE: identity = self.identity_for(Transport.REST) self._commit_factory_data() client = self.get_rest_client() - self._configure_rest_auth_override(identity) - return client, identity + headers: dict[str, str] = {} + if presented_auth_token is not None: + self._configure_rest_real_auth() + headers = {**presented_auth_headers, "x-adcp-tenant": self._tenant_id} + else: + self._configure_rest_auth_override(identity) + return client, identity, headers + + @staticmethod + def _configure_rest_real_auth() -> None: + """Remove harness overrides so REST resolves request credentials.""" + from src.app import app + from src.core.auth_context import _require_auth_dep, _resolve_auth_dep + + app.dependency_overrides.pop(_require_auth_dep, None) + app.dependency_overrides.pop(_resolve_auth_dep, None) @staticmethod def _configure_rest_auth_override(identity: Any) -> None: @@ -939,7 +1102,7 @@ def _configure_rest_auth_override(identity: Any) -> None: (must run AFTER ``get_rest_client``). With ``identity=None`` the ``_require_auth_dep`` override is REMOVED so the real production dependency runs against the token-less request and raises the real - ``AUTH_REQUIRED`` error — the harness must not hand-copy the production + ``AUTH_MISSING`` error — the harness must not hand-copy the production raise (a simulated raise drifted from production once already, #1417/cx41); otherwise both deps return the identity. """ diff --git a/tests/harness/assertions.py b/tests/harness/assertions.py index ea6f9384d1..4379aadc0c 100644 --- a/tests/harness/assertions.py +++ b/tests/harness/assertions.py @@ -63,10 +63,11 @@ def assert_rejected( reason: str | None = None, message_contains: str | None = None, ) -> None: - """Assert the request was rejected, checking WHAT field and WHY. + """Assert the buyer-visible wire envelope rejected the request. - Checks observable behavior — what the buyer sees — not which internal - layer caught the error. Works across all transports and environments. + The reconstructed ``result.error`` is deliberately not authoritative: + reconstruction is lossy and may retain privileged internal validation + details that the sanitized wire correctly omits. Args: result: TransportResult from env.call_via() @@ -79,28 +80,35 @@ def assert_rejected( """ assert result.is_error, f"Expected rejection but got success: {result.payload}" - error = result.error - error_str = str(error) + envelope = result.wire_error_envelope or result.synthesized_error_envelope + assert isinstance(envelope, dict), f"Expected a wire error envelope, got: {envelope!r}" + errors = envelope.get("errors") or [] + assert errors and all(isinstance(error, dict) for error in errors), ( + f"Expected buyer-visible errors[] objects, got: {envelope!r}" + ) + adcp_error = envelope.get("adcp_error") or {} if code is not None: - error_code = getattr(error, "error_code", None) - assert error_code == code or code in error_str, ( - f"Expected error code '{code}', got {error_code!r}. Full error: {error_str[:200]}" - ) + assert adcp_error.get("code") == code + assert errors[0].get("code") == code if field is not None: - details = getattr(error, "details", None) or {} - details_str = str(details) - assert field in error_str or field in details_str, ( - f"Expected field '{field}' in error. Error: {error_str[:200]}" + wire_fields = [str(error.get("field") or "") for error in errors] + assert any(actual == field or actual.endswith(f".{field}") for actual in wire_fields), ( + f"Expected field '{field}' in buyer-visible errors[], got: {wire_fields}" ) if reason is not None: - assert reason in error_str, f"Expected reason '{reason}' in error. Got: {error_str[:200]}" + wire_messages = [str(error.get("message") or "") for error in errors] + assert any(reason in message for message in wire_messages), ( + f"Expected reason '{reason}' in buyer-visible errors[], got: {wire_messages}" + ) if message_contains is not None: - message = getattr(error, "message", error_str) - assert message_contains in str(message), f"Expected '{message_contains}' in message. Got: {str(message)[:200]}" + wire_messages = [str(error.get("message") or "") for error in errors] + assert any(message_contains in message for message in wire_messages), ( + f"Expected '{message_contains}' in buyer-visible errors[], got: {wire_messages}" + ) def assert_payload_field( diff --git a/tests/harness/capabilities.py b/tests/harness/capabilities.py index 253f10b064..3f6bf0a68b 100644 --- a/tests/harness/capabilities.py +++ b/tests/harness/capabilities.py @@ -46,9 +46,15 @@ def call_mcp(self, **kwargs: Any) -> Any: return self._run_mcp_client("get_adcp_capabilities", GetAdcpCapabilitiesResponse, **kwargs) def _run_rest_request(self, endpoint: str, **kwargs: Any) -> Any: - """GET /api/v1/capabilities — no request body (unlike the POST discovery routes).""" - client, _identity = self._prepare_rest_request(kwargs) - return client.get(endpoint) + """GET /api/v1/capabilities — no request body (unlike the POST discovery routes). + + Forwards the auth headers ``_prepare_rest_request`` builds: a presented-token + seam selects the real production dependency path and is carried ONLY by those + headers, so dropping them here would silently send the request unauthenticated + and grade the wrong path. + """ + client, _identity, headers = self._prepare_rest_request(kwargs) + return client.get(endpoint, headers=headers) def parse_rest_response(self, data: dict[str, Any]) -> GetAdcpCapabilitiesResponse: """Parse REST JSON into GetAdcpCapabilitiesResponse.""" diff --git a/tests/harness/creative_formats.py b/tests/harness/creative_formats.py index e11122939a..34b4fa418a 100644 --- a/tests/harness/creative_formats.py +++ b/tests/harness/creative_formats.py @@ -147,12 +147,12 @@ def call_mcp(self, **kwargs: Any) -> ListCreativeFormatsResponse: """Call list_creative_formats via Client(mcp) — full pipeline dispatch.""" return self._run_mcp_client("list_creative_formats", ListCreativeFormatsResponse, **kwargs) - # build_rest_body is inherited from IntegrationEnv: it serializes the Pydantic - # ``req`` via model_dump(mode="json", exclude_none=True). ListCreativeFormatsBody - # (src/routes/api_v1.py) declares format_ids + every other filter and the route - # maps them into ListCreativeFormatsRequest, so REST filters for real — there is - # no need to drop kwargs. (A prior override returned {} behind a stale docstring - # claiming the body had no parameters; that suppressed REST filter coverage.) + def build_rest_body(self, **kwargs: Any) -> dict[str, Any]: + """Forward flat creative-format parameters to the REST request body.""" + req = kwargs.pop("req", None) + if req is not None: + return req.model_dump(mode="json", exclude_none=True) + return {key: value for key, value in kwargs.items() if value is not None} def parse_rest_response(self, data: dict[str, Any]) -> ListCreativeFormatsResponse: """Parse REST JSON into ListCreativeFormatsResponse.""" diff --git a/tests/harness/creative_list.py b/tests/harness/creative_list.py index 19cd34a899..f599ec5996 100644 --- a/tests/harness/creative_list.py +++ b/tests/harness/creative_list.py @@ -86,7 +86,25 @@ def call_mcp(self, **kwargs: Any) -> ListCreativesResponse: def build_rest_body(self, **kwargs: Any) -> dict[str, Any]: """Convert kwargs to ListCreativesBody shape for REST POST.""" body: dict[str, Any] = {} - for key in ("media_buy_id", "media_buy_ids", "status", "format"): + for key in ( + "media_buy_id", + "media_buy_ids", + "status", + "format", + "tags", + "created_after", + "created_before", + "search", + "fields", + "include_performance", + "include_assignments", + "include_sub_assets", + "page", + "limit", + "sort_by", + "sort_order", + "context", + ): if key in kwargs and kwargs[key] is not None: body[key] = kwargs[key] # The structured filters travel over REST as a JSON dict — the body field is diff --git a/tests/harness/creative_sync.py b/tests/harness/creative_sync.py index 3777bc222a..c09d8d729f 100644 --- a/tests/harness/creative_sync.py +++ b/tests/harness/creative_sync.py @@ -190,19 +190,9 @@ def call_impl(self, **kwargs: Any) -> SyncCreativesResponse: return _sync_creatives_impl(**kwargs) def call_a2a(self, **kwargs: Any) -> SyncCreativesResponse: - """Call sync_creatives_raw (A2A wrapper) with real DB. - - Note: uses _raw() path instead of _run_a2a_handler because the real - A2A handler's _handle_sync_creatives_skill constructs CreativeAsset - from raw dicts, which fails validation (assets field required). - That handler bug needs a separate fix. - """ - from src.core.tools.creatives.sync_wrappers import sync_creatives_raw - - self._commit_factory_data() - kwargs.setdefault("identity", self.identity) + """Call the real A2A handler and parse its Task artifact.""" kwargs.setdefault("creatives", []) - return sync_creatives_raw(**kwargs) + return self._run_a2a_handler("sync_creatives", SyncCreativesResponse, **kwargs) def call_mcp(self, **kwargs: Any) -> SyncCreativesResponse: """Call sync_creatives via Client(mcp) — full pipeline dispatch. diff --git a/tests/harness/dispatchers.py b/tests/harness/dispatchers.py index 242d9a0112..99f2d60643 100644 --- a/tests/harness/dispatchers.py +++ b/tests/harness/dispatchers.py @@ -47,27 +47,26 @@ def _envelope_from_adcp_error(exc: Exception) -> dict[str, Any] | None: - REST: the HTTP response body, captured directly by RestDispatcher. - MCP: the JSON string in ``ToolError``, parsed by McpDispatcher. """ - from src.core.exceptions import AdCPError, build_two_layer_error_envelope + from src.core.exceptions import AdCPError, build_two_layer_error_envelope, safe_adcp_error if isinstance(exc, AdCPError): - return build_two_layer_error_envelope(exc) + return build_two_layer_error_envelope(safe_adcp_error(exc)) return None def _wire_envelope_from_exception(exc: Exception) -> dict[str, Any] | None: - """Prefer the REAL wire envelope stashed by the harness; fall back to synthesized. + """Return only the REAL wire envelope stashed by the A2A harness. When the A2A pipeline reconstructs an AdCPError from a failed Task's artifact DataPart, ``tests.harness._base._envelope_to_adcp_error`` attaches the captured envelope to the exception as - ``_wire_error_envelope``. This helper returns that real wire envelope - if present; otherwise falls back to ``_envelope_from_adcp_error`` - (synthesized — same helper production calls). + ``_wire_error_envelope``. A raw-wrapper exception has no wire bytes and + must stay ``None`` instead of being mislabeled as A2A wire coverage. """ real_wire = getattr(exc, "_wire_error_envelope", None) if isinstance(real_wire, dict): return real_wire - return _envelope_from_adcp_error(exc) + return None def _envelope_from_mcp_error(exc: Exception) -> dict[str, Any] | None: @@ -215,9 +214,6 @@ def dispatch(self, env: BaseTestEnv, **kwargs: Any) -> TransportResult: return TransportResult( error=error, wire_error_envelope=wire, - # What production WOULD emit for the same exception — see the - # ImplDispatcher caveat; never a substitute for the wire field. - synthesized_error_envelope=_envelope_from_adcp_error(exc), ) # Real MCP wire: the structured_content dict stashed by _run_mcp_client # (declared on BaseTestEnv, reset per call_via — read directly). @@ -247,6 +243,7 @@ def dispatch(self, env: BaseTestEnv, **kwargs: Any) -> TransportResult: if not env.e2e_config: return TransportResult(error=RuntimeError("E2E dispatch requires env.e2e_config (pass e2e_config= to env)")) + presented_auth_token, presented_auth_headers = env._pop_presented_auth(kwargs) identity = kwargs.pop("identity", None) base_url = env.e2e_config.base_url @@ -255,7 +252,10 @@ def dispatch(self, env: BaseTestEnv, **kwargs: Any) -> TransportResult: # but auth_token is None (principal_id=None boundary tests), omit the header # so the server rejects gracefully instead of httpx raising on a None header. headers: dict[str, str] = {"Content-Type": "application/json"} - if identity is not None: + if presented_auth_token is not None: + headers.update(presented_auth_headers) + headers["x-adcp-tenant"] = env._tenant_id + elif identity is not None: if identity.auth_token is not None: headers["x-adcp-auth"] = identity.auth_token tenant = getattr(identity, "tenant", None) diff --git a/tests/harness/media_buy_dual.py b/tests/harness/media_buy_dual.py index 6feda921da..7fad4aa69b 100644 --- a/tests/harness/media_buy_dual.py +++ b/tests/harness/media_buy_dual.py @@ -229,9 +229,9 @@ def _run_update_rest_request(self, **kwargs: Any) -> Any: # Shared preamble (identity resolution + commit + client + auth-dep # override): with no identity the REST auth dep rejects, so the no-auth # update scenario fires instead of test-mode auth letting it through. - client, identity = self._prepare_rest_request(kwargs) + client, identity, auth_headers = self._prepare_rest_request(kwargs) - headers: dict[str, str] = {} + headers: dict[str, str] = dict(auth_headers) if identity is not None: auth_token = identity.auth_token if auth_token: diff --git a/tests/harness/test_forward_compat_acceptance.py b/tests/harness/test_forward_compat_acceptance.py index 5e281e551a..2db18fd788 100644 --- a/tests/harness/test_forward_compat_acceptance.py +++ b/tests/harness/test_forward_compat_acceptance.py @@ -19,6 +19,7 @@ from __future__ import annotations import asyncio +import json import os from unittest.mock import AsyncMock, MagicMock, patch @@ -26,6 +27,8 @@ from src.core.request_compat import normalize_request_params from tests.helpers import assert_envelope_shape +from tests.helpers.pinned_schema import pinned_error_code_suggestion +from tests.helpers.secret_scrub import assert_no_secret_leak # --------------------------------------------------------------------------- # Payloads: each is a (tool_name, params) tuple @@ -651,13 +654,33 @@ async def _call(): raise_on_error=False, ) assert result.is_error, "Empty get_products should return an error, not succeed silently" - # The error should mention what's missing - error_text = str(result.content) if result.content else "" - assert ( - "brief" in error_text.lower() - or "brand" in error_text.lower() - or "filter" in error_text.lower() - ), f"Error should mention missing brief/brand/filters, got: {error_text[:200]}" + assert result.content and len(result.content) == 1 + envelope = json.loads(result.content[0].text) + # The raise site is a bare literal naming the three acceptable + # parameters, so it opts in via ``_wire_safe_message`` and its text + # reaches the wire. This previously pinned the generic scrub sentence + # AND asserted "brief"/"brand"/"filter" were absent from the + # serialized envelope — which contradicted this class's own premise + # ("validation whose errors must reach the buyer"). Those three + # strings are get_products' own public request parameters, already in + # the schema the caller invoked; withholding them discloses nothing + # and costs the buyer the one thing they can act on for a + # ``correctable`` error. + expected_error = { + "code": "VALIDATION_ERROR", + "message": "At least one of 'brief', 'brand', or 'filters' is required", + "recovery": "correctable", + "suggestion": pinned_error_code_suggestion("VALIDATION_ERROR"), + } + assert_envelope_shape(envelope, "VALIDATION_ERROR", recovery="correctable") + assert envelope == { + "adcp_error": expected_error, + "errors": [expected_error], + } + # The real non-disclosure property, unchanged: nothing seller-side + # rides along. Naming the caller's own request parameters is not a + # leak; a connection string or adapter internal would be. + assert_no_secret_leak(envelope) finally: for p in patches: p.stop() diff --git a/tests/harness/test_harness_base.py b/tests/harness/test_harness_base.py index b78df2bc41..b00331e755 100644 --- a/tests/harness/test_harness_base.py +++ b/tests/harness/test_harness_base.py @@ -10,6 +10,30 @@ from unittest.mock import MagicMock, patch +def test_a2a_parameter_serialization_recurses_into_pydantic_models() -> None: + """Nested creative-like models stay structured across protobuf Struct.""" + from pydantic import BaseModel + + from tests.harness._base import _serialize_a2a_parameters + + class _Asset(BaseModel): + url: str + width: int + + parameters = _serialize_a2a_parameters( + {"creatives": [{"creative_id": "creative-1", "assets": [_Asset(url="https://example.test/ad", width=300)]}]} + ) + + assert parameters == { + "creatives": [ + { + "creative_id": "creative-1", + "assets": [{"url": "https://example.test/ad", "width": 300}], + } + ] + } + + class TestBaseClassContract: """BaseTestEnv must work in both integration (use_real_db=True) and unit modes.""" @@ -285,6 +309,185 @@ class _Resp(BaseModel): assert result.is_success assert result.payload.ok is True + def test_impl_synthesized_envelope_applies_production_sanitizer(self): + """The no-wire IMPL oracle mirrors boundary scrubbing without claiming wire coverage.""" + from src.core.exceptions import AdCPServiceUnavailableError + from tests.harness._base import BaseTestEnv + from tests.harness.transport import Transport + from tests.helpers import assert_envelope_shape + + class _TestEnv(BaseTestEnv): + def call_impl(self, **kwargs): + raise AdCPServiceUnavailableError("agent unreachable") + + result = _TestEnv().call_via(Transport.IMPL) + + assert result.wire_error_envelope is None + assert_envelope_shape(result.synthesized_error_envelope, "SERVICE_UNAVAILABLE", recovery="transient") + assert "unreachable" not in str(result.synthesized_error_envelope).lower() + + def test_a2a_raw_exception_is_not_mislabeled_as_wire_coverage(self): + """A raw-wrapper exception has no Task artifact and therefore no wire envelope.""" + from src.core.exceptions import AdCPServiceUnavailableError + from tests.harness._base import BaseTestEnv + from tests.harness.transport import Transport + + class _TestEnv(BaseTestEnv): + def call_a2a(self, **kwargs): + raise AdCPServiceUnavailableError("agent unreachable") + + result = _TestEnv().call_via(Transport.A2A) + + assert result.is_error + assert result.wire_error_envelope is None + assert result.synthesized_error_envelope is None + + def test_a2a_captures_only_handler_artifact_envelope(self): + """The A2A dispatcher forwards the exact envelope reconstructed from a failed Task.""" + from src.core.exceptions import AdCPServiceUnavailableError + from tests.harness._base import BaseTestEnv + from tests.harness.transport import Transport + + envelope = { + "adcp_error": { + "code": "SERVICE_UNAVAILABLE", + "message": "safe", + "recovery": "transient", + }, + "errors": [ + { + "code": "SERVICE_UNAVAILABLE", + "message": "safe", + "recovery": "transient", + } + ], + } + + class _TestEnv(BaseTestEnv): + def call_a2a(self, **kwargs): + error = AdCPServiceUnavailableError("reconstructed") + error.__dict__["_wire_error_envelope"] = envelope + raise error + + result = _TestEnv().call_via(Transport.A2A) + + assert result.wire_error_envelope is envelope + assert result.synthesized_error_envelope is None + + def test_mcp_captures_only_tool_error_envelope(self): + """The MCP dispatcher never adds a synthesized competitor to real wire data.""" + from src.core.exceptions import AdCPServiceUnavailableError + from tests.harness._base import BaseTestEnv + from tests.harness.transport import Transport + + envelope = { + "adcp_error": { + "code": "SERVICE_UNAVAILABLE", + "message": "safe", + "recovery": "transient", + }, + "errors": [ + { + "code": "SERVICE_UNAVAILABLE", + "message": "safe", + "recovery": "transient", + } + ], + } + + class _TestEnv(BaseTestEnv): + def call_mcp(self, **kwargs): + error = AdCPServiceUnavailableError("reconstructed") + error.__dict__["_wire_error_envelope"] = envelope + raise error + + result = _TestEnv().call_via(Transport.MCP) + + assert result.wire_error_envelope is envelope + assert result.synthesized_error_envelope is None + + def test_presented_auth_token_disables_identity_injection(self): + """Real-auth mode forwards the token seam without a resolved identity.""" + from tests.harness._base import BaseTestEnv + from tests.harness.transport import Transport + + class _TestEnv(BaseTestEnv): + def call_a2a(self, **kwargs): + return kwargs + + env = _TestEnv() + result = env.call_via(Transport.A2A, presented_auth_token="rejected-token") + + assert result.is_success + assert result.payload == {"presented_auth_token": "rejected-token"} + + def test_presented_auth_token_rejects_identity_override(self): + """A test cannot silently bypass real auth with two auth inputs.""" + import pytest + + from tests.harness._base import BaseTestEnv + from tests.harness.transport import Transport + + env = BaseTestEnv() + with pytest.raises(ValueError, match="mutually exclusive"): + env.call_via( + Transport.A2A, + identity=env.identity_for(Transport.A2A), + presented_auth_token="rejected-token", + ) + + def test_presented_auth_token_rejects_none(self): + """The real-auth seam cannot silently fall back to identity injection.""" + import pytest + + from tests.harness._base import BaseTestEnv + from tests.harness.transport import Transport + + env = BaseTestEnv() + with pytest.raises(TypeError, match="must be a string"): + env.call_via(Transport.A2A, presented_auth_token=None) + + def test_presented_legacy_auth_token_disables_identity_injection(self): + """Legacy real-auth mode forwards x-adcp-auth without a resolved identity.""" + from tests.harness._base import BaseTestEnv + from tests.harness.transport import Transport + + class _TestEnv(BaseTestEnv): + def call_a2a(self, **kwargs): + return kwargs + + env = _TestEnv() + result = env.call_via(Transport.A2A, presented_legacy_auth_token="rejected-token") + + assert result.is_success + assert result.payload == {"presented_legacy_auth_token": "rejected-token"} + + def test_presented_auth_seams_are_mutually_exclusive(self): + """A request cannot ambiguously present both standard and legacy credentials.""" + import pytest + + from tests.harness._base import BaseTestEnv + from tests.harness.transport import Transport + + env = BaseTestEnv() + with pytest.raises(ValueError, match="mutually exclusive"): + env.call_via( + Transport.A2A, + presented_auth_token="standard-token", + presented_legacy_auth_token="legacy-token", + ) + + def test_presented_legacy_auth_token_rejects_none(self): + """The legacy auth seam cannot silently fall back to identity injection.""" + import pytest + + from tests.harness._base import BaseTestEnv + from tests.harness.transport import Transport + + env = BaseTestEnv() + with pytest.raises(TypeError, match="must be a string"): + env.call_via(Transport.A2A, presented_legacy_auth_token=None) + def test_nested_integration_env_raises(self): """Nesting two IntegrationEnvs must raise to prevent session corruption.""" import pytest diff --git a/tests/harness/transport.py b/tests/harness/transport.py index 32acb3b7b7..019486250f 100644 --- a/tests/harness/transport.py +++ b/tests/harness/transport.py @@ -13,33 +13,13 @@ from __future__ import annotations -import functools from dataclasses import dataclass, field from enum import StrEnum from typing import Any from pydantic import BaseModel -from tests.helpers import pinned_schema - - -@functools.lru_cache(maxsize=1) -def _pinned_error_metadata() -> dict[str, dict[str, str]]: - """code -> {recovery, suggestion} from the installed SDK's error-code enum. - - Only the ``recovery`` field is actually read by this module (assert_wire_error - below) — verified safe to source from the SDK tree: the SDK's enum is a - strict superset of the older vendored fixture (92 vs 64 codes, fixture-only - set empty) and its ``recovery`` classification is IDENTICAL across every one - of the 64 shared codes (0 divergences). ``suggestion`` DOES diverge on 4 - codes between the two sources — but this module never reads that field - (extract_wire_suggestion below reads the WIRE's own suggestion text, not - this metadata), so that divergence has no effect here. Consumers that DO - grade ``suggestion`` content (test_architecture_error_suggestion_enum_conformance.py) - stay on the vendored fixture — see docs/adcp-spec-version.md "Pinned schema sources" - (which also cites the command to reproduce the 64-code fixture count). - """ - return pinned_schema.load("error-code.json")["enumMetadata"] +from tests.helpers.pinned_schema import pinned_error_code_metadata def extract_wire_suggestion(envelope: dict | None) -> str | None: @@ -165,7 +145,7 @@ def assert_wire_error( """ from tests.helpers import assert_envelope_shape - meta = _pinned_error_metadata() + meta = pinned_error_code_metadata() spec = meta.get(code) assert spec is not None, ( f"{code!r} is not a canonical AdCP error code (pinned error-code.json). " @@ -181,5 +161,25 @@ def assert_wire_error( ) assert_envelope_shape(envelope, code, recovery=expected_recovery, message_substr=message_substr) if require_suggestion: - suggestion = extract_wire_suggestion(envelope) - assert suggestion, f"Expected a non-empty suggestion in the {code} wire envelope: {envelope}" + # PRESENCE on both layers, not equality with the pinned enum text. + # + # 3.1.1 `core/error.json` defines `suggestion` as "Suggested fix for the error" — + # optional, free-form, with NO tie to `enumMetadata`. The sibling `recovery` field + # in that same file DOES spell out its enum relationship ("the enumMetadata.recovery + # block ... is the documentary mirror; error.recovery on the wire is authoritative"), + # so the authors wrote the tie-back where they meant one. `enums/error-code.json`'s + # own `$comment` binds SDKs *consuming* the block and scopes its normativity clause + # to `recovery`; it calls the suggestions "remediation hints". The spec's own worked + # examples emit site-specific text that differs from the enum default (BUDGET_TOO_LOW + # ships "Increase budget to at least 500 USD" against an enum default of "increase + # budget or check capabilities.media_buy.limits"). + # + # Equality here was a harness tightening (5b41082ab) that generalized SCRUB-ONLY + # semantics to every error. It held only vacuously — while the raise sites were still + # being scrubbed. `assert_sanitized_wire_error` (tests/helpers/secret_scrub.py) keeps + # that equality where it belongs: verifying the scrub substitution itself. + for layer, error in (("adcp_error", envelope["adcp_error"]), ("errors[0]", envelope["errors"][0])): + assert error.get("suggestion"), ( + f"{layer} carries no buyer-facing suggestion for {code}; the spec places the " + f"hint at the top level of the error object: {envelope}" + ) diff --git a/tests/helpers/auth_contract.py b/tests/helpers/auth_contract.py new file mode 100644 index 0000000000..f5c3bcf3c0 --- /dev/null +++ b/tests/helpers/auth_contract.py @@ -0,0 +1,61 @@ +"""Transport-aware assertions for the pinned AdCP authentication error contract.""" + +from __future__ import annotations + +from typing import Literal + +from tests.helpers.envelope_assertions import assert_envelope_shape +from tests.helpers.pinned_schema import pinned_error_code_metadata, pinned_error_code_suggestion + +CredentialState = Literal["missing", "invalid"] + +_WIRE_TRANSPORTS = frozenset({"a2a", "mcp", "rest", "e2e_a2a", "e2e_mcp", "e2e_rest"}) +_LEGACY_IMPL_TRANSPORTS = frozenset({"impl"}) + + +def expected_auth_contract(transport: object, credential_state: CredentialState) -> tuple[str, str, str]: + """Return the exact code, recovery, and suggestion for an auth rejection. + + Every wire transport implements the AdCP 3.1.1 + ``AUTH_MISSING``/``AUTH_INVALID`` split. Direct implementation calls lack + credential-presence information and retain the deprecated + ``AUTH_REQUIRED`` compatibility code. + """ + if credential_state not in ("missing", "invalid"): + raise AssertionError(f"Unknown credential state: {credential_state!r}") + + transport_name = str(transport) + if transport_name in _WIRE_TRANSPORTS: + code = "AUTH_MISSING" if credential_state == "missing" else "AUTH_INVALID" + elif transport_name in _LEGACY_IMPL_TRANSPORTS: + code = "AUTH_REQUIRED" + else: + raise AssertionError(f"Unknown auth-contract transport: {transport_name!r}") + + metadata = pinned_error_code_metadata()[code] + recovery = metadata.get("recovery") + if not isinstance(recovery, str) or not recovery: + raise AssertionError(f"Pinned error code {code!r} has no non-empty recovery") + return code, recovery, pinned_error_code_suggestion(code) + + +def assert_two_layer_auth_contract( + envelope: dict | None, + transport: object, + credential_state: CredentialState, +) -> None: + """Assert both mirrored wire layers match the pinned auth contract.""" + expected_code, expected_recovery, expected_suggestion = expected_auth_contract(transport, credential_state) + assert_envelope_shape(envelope, expected_code, recovery=expected_recovery) + assert envelope is not None + + errors = envelope.get("errors") or [] + assert errors and isinstance(errors[0], dict), f"Auth envelope has no errors[0] object: {envelope!r}" + adcp_error = envelope.get("adcp_error") + assert isinstance(adcp_error, dict), f"Auth envelope has no adcp_error object: {envelope!r}" + + for layer_name, error_object in (("errors[0]", errors[0]), ("adcp_error", adcp_error)): + assert error_object.get("suggestion") == expected_suggestion, ( + f"{layer_name}.suggestion must match pinned {expected_code} guidance; " + f"expected {expected_suggestion!r}, got {error_object.get('suggestion')!r}" + ) diff --git a/tests/helpers/creative_test_helpers.py b/tests/helpers/creative_test_helpers.py index 2f8827b0ce..20a50ec3d7 100644 --- a/tests/helpers/creative_test_helpers.py +++ b/tests/helpers/creative_test_helpers.py @@ -9,8 +9,10 @@ from __future__ import annotations +from collections.abc import Callable from contextlib import contextmanager from datetime import UTC, datetime +from typing import Any from unittest.mock import MagicMock, Mock, patch from tests.factories.creative_asset import AssetSpec, assert_assets, build_assets, image_spec @@ -97,6 +99,24 @@ def mock_create(**kwargs): return mock_uow, mock_creative_repo +def make_creative_registry_mock( + *, + list_all_formats: Callable[..., Any], + get_format: Callable[..., Any] | None = None, +) -> Mock: + """Build a registry mock with the real async static-preview boundary.""" + + async def preview_creative(**_kwargs: Any) -> dict: + return {} + + registry = Mock() + registry.list_all_formats = list_all_formats + if get_format is not None: + registry.get_format = get_format + registry.preview_creative = preview_creative + return registry + + def sync_patches(): """Context manager returning (mock_creative_repo, mock_registry) with standard patches.""" @@ -108,9 +128,10 @@ async def mock_list_all_formats(tenant_id=None): async def mock_get_format(agent_url, format_id): return mock_format_spec_arg - mock_registry = Mock() - mock_registry.list_all_formats = mock_list_all_formats - mock_registry.get_format = mock_get_format + mock_registry = make_creative_registry_mock( + list_all_formats=mock_list_all_formats, + get_format=mock_get_format, + ) mock_uow, mock_creative_repo = make_creative_uow() diff --git a/tests/helpers/pinned_schema.py b/tests/helpers/pinned_schema.py index 60e655f6df..dfc6caea49 100644 --- a/tests/helpers/pinned_schema.py +++ b/tests/helpers/pinned_schema.py @@ -46,6 +46,7 @@ from __future__ import annotations import json +from functools import lru_cache from pathlib import Path from typing import Any from urllib.parse import urlparse @@ -251,3 +252,47 @@ def validate_against_pinned_schema(filename: str, data: Any) -> None: f" at {'.'.join(str(p) for p in e.absolute_path) or ''}: {e.message}" for e in errors ) raise AssertionError(f"Response is not schema-valid against {filename}:\n{details}") + + +@lru_cache(maxsize=1) +def pinned_error_code_metadata() -> dict[str, dict[str, str]]: + """Return ``{error_code: {recovery, suggestion}}`` from the pinned error-code enum. + + Sourced from the installed SDK's tree like every other consumer of this + module — there is exactly one upstream pin (see + ``tests/unit/test_pinned_schema_single_source.py``). That matters here more + than elsewhere: ``AUTH_MISSING`` and ``AUTH_INVALID`` exist ONLY in the + SDK's current enum, so the auth-split contract this metadata grades is + unreadable from the older vendored fixture. + + The two sources' ``suggestion`` text diverges on 4 codes + (``MEDIA_BUY_NOT_FOUND``, ``PACKAGE_NOT_FOUND``, ``REQUOTE_REQUIRED``, + ``CREDENTIAL_IN_ARGS``) and their ``recovery`` on none. No caller of this + function reads a divergent code — callers grade the auth split plus + ``VALIDATION_ERROR``, all byte-identical across both sources — so the + migration is inert for them. Consumers that grade suggestion text for the + divergent codes stay on the vendored fixture; see + ``docs/adcp-spec-version.md`` "Pinned schema sources" and #1883. + """ + metadata = load("error-code.json").get("enumMetadata") + if not isinstance(metadata, dict): + raise PinnedSchemaError("Pinned error-code.json has no enumMetadata object") + + entries: dict[str, dict[str, str]] = {} + for code, entry in metadata.items(): + if code.startswith("$"): + continue + if not isinstance(entry, dict): + raise PinnedSchemaError(f"Pinned error code {code!r} metadata is not an object") + if not all(isinstance(key, str) and isinstance(value, str) for key, value in entry.items()): + raise PinnedSchemaError(f"Pinned error code {code!r} metadata contains non-string fields") + entries[code] = entry + return entries + + +def pinned_error_code_suggestion(code: str) -> str: + """Return the authoritative buyer suggestion for a pinned error code.""" + suggestion = pinned_error_code_metadata().get(code, {}).get("suggestion") + if not isinstance(suggestion, str) or not suggestion: + raise AssertionError(f"Pinned error code {code!r} has no non-empty suggestion") + return suggestion diff --git a/tests/helpers/secret_scrub.py b/tests/helpers/secret_scrub.py new file mode 100644 index 0000000000..9bb9fb7b28 --- /dev/null +++ b/tests/helpers/secret_scrub.py @@ -0,0 +1,102 @@ +"""Shared oracle for 'no raw secret leaked to a buyer-facing wire'. + +The token set IS the definition of what counts as a leak — keep it in ONE place so +tightening it (adding a new secret shape) is a single edit, not an N-site lockstep +update where a missed copy silently under-asserts. +""" + +from __future__ import annotations + +import json + +from tests.helpers.pinned_schema import pinned_error_code_suggestion + +# A message shaped like the worst realistic leak: a connection string with credentials, +# a bearer token, an internal host, and inline SQL — everything a scrubbed error must never +# echo to the buyer. +SECRET_BEARING_MESSAGE = "postgresql://svc:hunter2@db.internal/prod TOKEN=abc123 SELECT * FROM principals" + +_SECRET_TOKENS = ("hunter2", "postgresql://", "svc", "db.internal", "TOKEN=abc123", "SELECT", "principals") + +# Independently-pinned expected sanitized MESSAGE text per wire code — deliberately literal, +# NOT read from src.core.exceptions._SANITIZED_BY_WIRE_CODE. The AdCP spec (core/error.json) +# does not mandate exact message wording (only that it be human-readable), so there is no +# independent spec/fixture source to read it from the way pinned_error_code_suggestion() reads +# suggestions. Pinning it here as a literal means a change to production's table without a +# matching change here reddens this oracle, instead of both sides moving together silently — +# the exact gap a prior version of this file had (both sides read the same production table). +_EXPECTED_SANITIZED_MESSAGE: dict[str, str] = { + "INVALID_REQUEST": "The request is malformed or contains unsupported fields; review it and resubmit.", + "VALIDATION_ERROR": "The request could not be validated; review the submitted fields and resubmit.", + "AUTH_REQUIRED": "Authentication or authorization failed; provide valid credentials or the required permissions.", +} + + +def serialize_wire_error(wire: object) -> str: + """Serialize one SDK wire-error carrier through the shared test oracle.""" + if isinstance(wire, dict): + payload = wire + else: + model_dump = getattr(wire, "model_dump", None) + assert callable(model_dump), f"Unsupported wire-error carrier: {type(wire).__name__}" + payload = model_dump() + return json.dumps(payload, default=str) + + +def assert_no_secret_leak(blob: object, *, context: str = "") -> None: + """Assert no ``SECRET_BEARING_MESSAGE`` token appears in ``blob`` (a str, or a JSON-able + envelope/dict). Raises with the offending token and a truncated haystack. + + Refuses ``None``: an absent value must not satisfy the oracle vacuously — a caller + asserting on a field that production stopped populating should fail loudly, not pass. + """ + assert blob is not None, ( + f"assert_no_secret_leak given None{f' ({context})' if context else ''} — absent value cannot prove a scrub" + ) + haystack = blob if isinstance(blob, str) else json.dumps(blob, default=str) + where = f" ({context})" if context else "" + for token in _SECRET_TOKENS: + assert token not in haystack, ( + f"secret fragment {token!r} leaked to the buyer-facing wire{where}: {haystack[:300]}" + ) + + +def assert_sanitized_wire_error( + envelope: dict, + code: str, + *, + rejected_fragments: tuple[str, ...] = (), +) -> None: + """Assert both error-envelope layers use the canonical scrubbed presentation. + + Two INDEPENDENT oracles, neither read from production's own scrub table + (``src.core.exceptions._SANITIZED_BY_WIRE_CODE``) — reading expected values from the + same table production writes them from means a change to that table moves both sides + of the assertion together, silently. ``expected_message`` is a literal pinned in THIS + file (``_EXPECTED_SANITIZED_MESSAGE`` — the spec doesn't mandate exact wording, so + there's no independent source to read it from); ``expected_suggestion`` is read from + the vendored AdCP schema pin's ``enumMetadata`` (``pinned_error_code_suggestion``), + which production's own suggestion constants are written to mirror. Callers supply any + raw business/input fragments that must be absent, so replacing a brittle raw-message + assertion still proves the confidential text was removed. + """ + expected_message = _EXPECTED_SANITIZED_MESSAGE.get(code) + assert expected_message is not None, f"{code!r} has no independently-pinned sanitized message in this file" + expected_suggestion = pinned_error_code_suggestion(code) + + adcp_error = envelope.get("adcp_error") or {} + errors = envelope.get("errors") or [] + assert errors, f"Expected errors[0] in two-layer envelope: {envelope}" + for label, error in (("adcp_error", adcp_error), ("errors[0]", errors[0])): + assert error.get("message") == expected_message, ( + f"{label}.message did not use the canonical {code} scrub: {error}" + ) + assert error.get("suggestion") == expected_suggestion, ( + f"{label}.suggestion did not use the canonical {code} guidance: {error}" + ) + + serialized = serialize_wire_error(envelope).lower() + for fragment in rejected_fragments: + assert fragment.lower() not in serialized, ( + f"raw rejected fragment {fragment!r} leaked through the sanitized {code} envelope: {serialized[:500]}" + ) diff --git a/tests/integration/test_a2a_error_responses.py b/tests/integration/test_a2a_error_responses.py index d0ca2a9ec3..80d5bbc22d 100644 --- a/tests/integration/test_a2a_error_responses.py +++ b/tests/integration/test_a2a_error_responses.py @@ -12,18 +12,24 @@ import logging import uuid from datetime import UTC, datetime, timedelta -from unittest.mock import MagicMock +from unittest.mock import AsyncMock, MagicMock import pytest from a2a.server.routes.common import ServerCallContext -from a2a.types import Message, SendMessageRequest, Task +from a2a.types import Message, SendMessageRequest, Task, TaskState from src.a2a_server.adcp_a2a_server import AdCPRequestHandler from tests.factories.principal import PrincipalFactory from tests.helpers import assert_envelope_shape, assert_no_raw_validation_leak from tests.helpers.adcp_factories import create_test_package_request_dict +from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE, assert_no_secret_leak from tests.integration.conftest import seed_error_test_tenant -from tests.utils.a2a_helpers import create_a2a_message_with_skill, extract_data_from_artifact +from tests.utils.a2a_helpers import ( + create_a2a_message_with_skill, + extract_data_from_artifact, + extract_processing_error_envelope, + make_nl_send_message_request, +) pytestmark = [pytest.mark.integration, pytest.mark.requires_db] @@ -105,6 +111,7 @@ async def test_create_media_buy_validation_error_includes_errors_field(self, han ) handler._get_auth_token = MagicMock(return_value=test_principal["access_token"]) handler._resolve_a2a_identity = MagicMock(return_value=identity) + handler._send_protocol_webhook = AsyncMock() from src.core.config_loader import set_current_tenant @@ -138,9 +145,20 @@ async def test_create_media_buy_validation_error_includes_errors_field(self, han assert_envelope_shape( artifact_data, "VALIDATION_ERROR", - message_substr="Missing required AdCP parameters", recovery="correctable", ) + from tests.helpers.secret_scrub import assert_sanitized_wire_error + + assert_sanitized_wire_error( + artifact_data, + "VALIDATION_ERROR", + rejected_fragments=("Missing required AdCP parameters",), + ) + + # Immediate terminal failure returned synchronously → no protocol webhook + # (AdCP 3.1.1 a2a-guide.mdx terminal-state rule); the failure rides + # in the Task body as the two-layer envelope asserted above. + handler._send_protocol_webhook.assert_not_awaited() async def test_create_media_buy_auth_error_includes_errors_field(self, handler, test_tenant): """Principal-not-found surfaces AUTH_REQUIRED as a two-layer envelope on the A2A wire.""" @@ -244,6 +262,16 @@ async def test_create_media_buy_end_before_start_wire_envelope(self, handler, te artifact_data = self.extract_data_from_artifact(result.artifacts[0]) assert_envelope_shape(artifact_data, "INVALID_REQUEST", recovery="correctable") + for error in (artifact_data["adcp_error"], artifact_data["errors"][0]): + assert error["message"] == "End time must be after start time." + assert error["field"] == "end_time" + assert error["suggestion"] == "Set end_time to a datetime after start_time." + + from tests.helpers.secret_scrub import serialize_wire_error + + serialized = serialize_wire_error(artifact_data) + assert start.isoformat() not in serialized + assert end.isoformat() not in serialized async def test_get_media_buy_delivery_malformed_account_wire_envelope(self, handler, test_tenant, test_principal): """A malformed account on get_media_buy_delivery surfaces VALIDATION_ERROR on the A2A wire. @@ -343,6 +371,46 @@ async def test_create_media_buy_negative_budget_wire_envelope(self, handler, tes wire_field = artifact_data["errors"][0].get("field") or "" assert "budget" in wire_field, f"expected a budget field path on the wire, got {wire_field!r}" + async def test_nl_create_media_buy_unsupported_returns_failed_task_envelope( + self, handler, test_tenant, test_principal + ): + """NL create-media-buy is an application failure in a failed Task, not JSON-RPC. + + Grounding: AdCP 3.1.1 + ``building/operating/transport-errors.mdx`` "Layer Separation"; + storyboard: ungraded, pending an upstream obligation. + """ + identity = PrincipalFactory.make_identity( + principal_id=test_principal["principal_id"], + tenant_id=test_tenant["tenant_id"], + tenant=test_tenant, + auth_token=test_principal["access_token"], + protocol="a2a", + ) + handler._get_auth_token = MagicMock(return_value=test_principal["access_token"]) + handler._resolve_a2a_identity = MagicMock(return_value=identity) + + from src.core.config_loader import set_current_tenant + + set_current_tenant(test_tenant) + + params = make_nl_send_message_request("create a media buy") + + result = await handler.on_message_send(params, ServerCallContext()) + + assert isinstance(result, Task) + assert result.status.state == TaskState.TASK_STATE_FAILED + + # Strict reader pins the outer-handler artifact contract (processing_error + # name + single DataPart) at integration altitude, same as the unit tests. + artifact_data = extract_processing_error_envelope(result) + assert_envelope_shape( + artifact_data, + "UNSUPPORTED_FEATURE", + recovery="correctable", + message_substr="Natural-language create_media_buy is not supported", + ) + async def test_create_media_buy_success_has_no_errors_field(self, handler, test_tenant, test_principal): """Test that successful responses don't have errors field (or it's None/empty).""" identity = PrincipalFactory.make_identity( @@ -434,9 +502,14 @@ async def test_sync_creatives_missing_creatives_param_wire_envelope(self, handle assert_envelope_shape( artifact_data, "VALIDATION_ERROR", - message_substr="creatives", recovery="correctable", ) + # Bare static literal → opts in to the wire (see the media_buy_id sibling below); + # the buyer must be told WHICH required parameter is missing, not just "review + # the submitted fields". + for label, error in (("adcp_error", artifact_data["adcp_error"]), ("errors[0]", artifact_data["errors"][0])): + assert "creatives" in error["message"], f"{label} must name the missing parameter, got {error['message']!r}" + assert_no_secret_leak(artifact_data) async def test_create_media_buy_response_includes_all_adcp_fields(self, handler, test_tenant, test_principal): """Test that A2A response includes all AdCP domain fields (not just cherry-picked ones). @@ -545,12 +618,20 @@ async def test_create_creative_missing_required_params_wire_envelope(self, handl artifact_data = self.extract_data_from_artifact(result.artifacts[0]) - # Full two-layer envelope on the wire. + # Full safe, actionable two-layer envelope on the wire. Declared + # schema paths remain visible; rejected input values and raw Pydantic + # diagnostics do not. assert_envelope_shape(artifact_data, "VALIDATION_ERROR", recovery="correctable") - # Per-error message enumerates the missing required fields. - msg = artifact_data["errors"][0]["message"] - detail = f"Per-error message must name all missing required fields, got: {msg}" - assert "format_id" in msg and "content_uri" in msg and "name" in msg, detail + expected_errors = [ + {"loc": ["format_id"], "msg": "Required field is missing.", "type": "missing"}, + {"loc": ["content_uri"], "msg": "Required field is missing.", "type": "missing"}, + {"loc": ["name"], "msg": "Required field is missing.", "type": "missing"}, + ] + for error in (artifact_data["adcp_error"], artifact_data["errors"][0]): + assert error["field"] == "format_id" + assert error["suggestion"] == "review error details and fix field values" + assert error["details"] == {"validation_errors": expected_errors} + assert_no_raw_validation_leak(error["message"]) async def test_assign_creative_missing_required_params_wire_envelope(self, handler, test_tenant, test_principal): """assign_creative missing required params → two-layer envelope on the A2A wire. @@ -589,9 +670,19 @@ async def test_assign_creative_missing_required_params_wire_envelope(self, handl artifact_data = self.extract_data_from_artifact(result.artifacts[0]) assert_envelope_shape(artifact_data, "VALIDATION_ERROR", recovery="correctable") - # Per-error message enumerates ONLY the missing fields (not the provided media_buy_id). - msg = artifact_data["errors"][0]["message"] - assert "package_id" in msg and "creative_id" in msg, f"Per-error message must name missing fields, got: {msg}" + expected_errors = [ + {"loc": ["package_id"], "msg": "Required field is missing.", "type": "missing"}, + {"loc": ["creative_id"], "msg": "Required field is missing.", "type": "missing"}, + ] + for error in (artifact_data["adcp_error"], artifact_data["errors"][0]): + assert error["field"] == "package_id" + assert error["suggestion"] == "review error details and fix field values" + assert error["details"] == {"validation_errors": expected_errors} + assert_no_raw_validation_leak(error["message"]) + + from tests.helpers.secret_scrub import serialize_wire_error + + assert "mb_123" not in serialize_wire_error(artifact_data) async def test_update_media_buy_not_found_wire_envelope(self, handler, test_tenant, test_principal): """update_media_buy with unknown media_buy_id surfaces MEDIA_BUY_NOT_FOUND on the A2A wire. @@ -678,7 +769,16 @@ async def test_update_media_buy_missing_media_buy_id_wire_envelope(self, handler assert result.artifacts is not None and len(result.artifacts) > 0 artifact_data = self.extract_data_from_artifact(result.artifacts[0]) - assert_envelope_shape(artifact_data, "VALIDATION_ERROR", message_substr="media_buy_id", recovery="correctable") + assert_envelope_shape(artifact_data, "VALIDATION_ERROR", recovery="correctable") + # Bare static literal → opts in to the wire (nothing interpolated, nothing to + # leak). Asserting the SCRUB here pinned the diagnostic downgrade the opt-in + # sweep removed: told only "review the submitted fields", a buyer cannot tell + # WHICH required parameter is missing. + for label, error in (("adcp_error", artifact_data["adcp_error"]), ("errors[0]", artifact_data["errors"][0])): + assert "media_buy_id" in error["message"], ( + f"{label} must name the missing parameter, got {error['message']!r}" + ) + assert_no_secret_leak(artifact_data) @pytest.fixture def active_media_buy(self, _seeded): @@ -874,24 +974,30 @@ async def test_adcp_error_carries_recovery_through_a2a_boundary(self, integratio from src.core.exceptions import ( AdCPAdapterError, + AdCPError, AdCPValidationError, build_two_layer_error_envelope, ) - # Test transient recovery (AdCPAdapterError) + # Internal AdCPAdapterError is scrubbed at the seam (its raise sites can interpolate a + # secret) — re-raised as a wire-safe base AdCPError; recovery stays transient (canonical). async def mock_adapter_fail(params, token): - raise AdCPAdapterError("GAM timeout") + raise AdCPAdapterError(f"GAM timeout: {SECRET_BEARING_MESSAGE}") with patch.object(handler, "_handle_get_products_skill", mock_adapter_fail): - with pytest.raises(AdCPAdapterError) as exc_info: + with pytest.raises(AdCPError) as exc_info: await handler._handle_explicit_skill("get_products", {}, "token") error = exc_info.value assert error.recovery == "transient", "AdCPAdapterError must have transient recovery" + assert error.wire_error_code == "SERVICE_UNAVAILABLE" + assert "GAM timeout" not in error.message + assert_no_secret_leak(error.message, context="seam-scrubbed adapter message") # Envelope built from the propagated exception preserves recovery. envelope = build_two_layer_error_envelope(error) assert envelope["adcp_error"]["recovery"] == "transient" assert envelope["errors"][0]["recovery"] == "transient" + assert_no_secret_leak(envelope, context="full adapter-failure envelope") # Test correctable recovery (AdCPValidationError) async def mock_validation_fail(params, token): @@ -930,56 +1036,57 @@ async def mock_transient_not_found(params, token): envelope = build_two_layer_error_envelope(error) assert envelope["adcp_error"]["recovery"] == "transient" - async def test_valueerror_wraps_to_adcp_validation_error(self, integration_db, handler): - """ValueError in a skill handler propagates as AdCPValidationError. + async def test_valueerror_keeps_validation_code_but_scrubs_message(self, integration_db, handler): + """ValueError in a skill handler → wire-safe error keeping the SEMANTIC code but scrubbed. - ``_handle_explicit_skill`` wraps the ValueError as a synthetic - ``AdCPValidationError`` and re-raises, so the outer dispatcher - catches it via ``except AdCPError`` and produces a failed Task - with a two-layer envelope — same wire shape as natively-raised - AdCPErrors. No JSON-RPC ``InvalidParamsError`` translation. + The seam keeps VALIDATION_ERROR + correctable recovery (the same the synchronous boundaries + emit for a ValueError), so a buyer watching the webhook and the synchronous response sees + ONE code — but the untrusted ``str(e)`` is SCRUBBED (a raw ValueError can bear a connection + string). Before the provenance-vs-semantics split this re-raised a *trusted* + ``AdCPValidationError`` whose raw message reached the wire. ``__cause__`` chains the original. """ from unittest.mock import patch - from src.core.exceptions import AdCPValidationError + from src.core.exceptions import AdCPError async def mock_valueerror(params, identity): - raise ValueError("missing required field") + raise ValueError(f"missing field {SECRET_BEARING_MESSAGE}") with patch.object(handler, "_handle_get_products_skill", mock_valueerror): - with pytest.raises(AdCPValidationError) as exc_info: + with pytest.raises(AdCPError) as exc_info: await handler._handle_explicit_skill("get_products", {}, None) - assert "missing required field" in str(exc_info.value) - assert exc_info.value.error_code == "VALIDATION_ERROR" - # AdCPValidationError class default — preserved through the wrap. - assert exc_info.value.recovery == "correctable" - # Original ValueError is chained via __cause__ for traceability. - assert isinstance(exc_info.value.__cause__, ValueError) - - async def test_permissionerror_wraps_to_adcp_authorization_error(self, integration_db, handler): - """PermissionError in a skill handler propagates as AdCPAuthorizationError. - - Symmetric with ValueError handling. Outer dispatcher produces a failed - Task with envelope (AUTH_REQUIRED, recovery=correctable). + error = exc_info.value + assert error.wire_error_code == "VALIDATION_ERROR" + assert error.recovery == "correctable" + assert "missing field" not in error.message + assert_no_secret_leak(error.message, context="seam-scrubbed ValueError message") + # Original ValueError is chained via __cause__ for traceability (server-side only). + assert isinstance(error.__cause__, ValueError) + + async def test_permissionerror_keeps_auth_code_but_scrubs_message(self, integration_db, handler): + """PermissionError in a skill handler → AUTH_REQUIRED + correctable, message scrubbed. + + Symmetric with the ValueError case: semantic code kept for webhook↔sync parity, untrusted + ``str(e)`` (which can bear a token) scrubbed. """ from unittest.mock import patch - from src.core.exceptions import AdCPAuthorizationError + from src.core.exceptions import AdCPError async def mock_permerror(params, identity): - raise PermissionError("tenant scope mismatch") + raise PermissionError(f"tenant scope mismatch {SECRET_BEARING_MESSAGE}") with patch.object(handler, "_handle_get_products_skill", mock_permerror): - with pytest.raises(AdCPAuthorizationError) as exc_info: + with pytest.raises(AdCPError) as exc_info: await handler._handle_explicit_skill("get_products", {}, None) - assert "tenant scope mismatch" in str(exc_info.value) - assert exc_info.value.error_code == "AUTH_REQUIRED" - # AdCPAuthorizationError default recovery is correctable per the pinned AUTH_REQUIRED - # enum (#1417), preserved through the PermissionError wrap. - assert exc_info.value.recovery == "correctable" - assert isinstance(exc_info.value.__cause__, PermissionError) + error = exc_info.value + assert error.wire_error_code == "AUTH_REQUIRED" + assert error.recovery == "correctable" + assert "tenant scope mismatch" not in error.message + assert_no_secret_leak(error.message, context="seam-scrubbed PermissionError message") + assert isinstance(error.__cause__, PermissionError) async def test_untyped_exception_falls_through_to_dispatcher(self, integration_db, handler): """Untyped exceptions from a skill handler are no longer caught locally. diff --git a/tests/integration/test_a2a_skill_invocation.py b/tests/integration/test_a2a_skill_invocation.py index d48773f229..e665968cca 100644 --- a/tests/integration/test_a2a_skill_invocation.py +++ b/tests/integration/test_a2a_skill_invocation.py @@ -7,18 +7,34 @@ """ import logging +import threading import uuid +from typing import Any from unittest.mock import MagicMock, patch import pytest -from a2a.types import Message, Part, Role, SendMessageRequest, Task, TaskState +from a2a.types import ( + CancelTaskRequest, + Message, + Part, + Role, + SendMessageRequest, + Task, + TaskNotCancelableError, + TaskNotFoundError, + TaskState, + TaskStatus, +) from adcp.types import AccountReference as LibraryAccountReference +from sqlalchemy import text from src.a2a_server.adcp_a2a_server import AdCPRequestHandler from tests.factories.creative_asset import build_assets, image_spec +from tests.factories.format import AGENT_URL as FORMAT_AGENT_URL from tests.helpers.a2a_adcp_validation import validate_a2a_skill_payload from tests.utils.a2a_helpers import ( assert_delivery_forwarded_account, + assert_failed_task_envelope, create_a2a_message_with_skill, create_a2a_text_message, ) @@ -162,6 +178,912 @@ def create_message_hybrid(self, text: str, skill: str, parameters: dict) -> Mess msg.parts.append(Part(data=_dict_to_value({"skill": skill, "parameters": parameters}))) return msg + def _persist_a2a_step( + self, + tenant_id: str, + principal_id: str, + external_task_id: str, + response_data: dict | None, + status: str = "completed", + ) -> str: + """Persist an a2a workflow step carrying an outer external_task_id. + + Mirrors what ``_create_media_buy_impl`` writes when the A2A boundary forwards the + buyer's ``task_*`` id. ContextManager manages its own session, so no test-body DB + access is needed. Returns the step id. + """ + from src.core.context_manager import ContextManager + + ctx_manager = ContextManager() + ctx = ctx_manager.create_context(tenant_id=tenant_id, principal_id=principal_id) + step = ctx_manager.create_workflow_step( + context_id=ctx.context_id, + step_type="tool_call", + owner="system", + status=status, + tool_name="create_media_buy", + request_data={"budget": 5000}, + request_metadata={"protocol": "a2a", "external_task_id": external_task_id}, + response_data=response_data, + ) + return step.step_id + + @pytest.mark.asyncio + async def test_durable_get_task_rebuilds_completed_task_from_external_id( + self, handler, sample_tenant, sample_principal, mock_identity + ): + """The durable helper ``_durable_task_from_step`` resolves the buyer's outer task_* id to + the persisted workflow step (cross-process) and rebuilds a terminal Task with the + stored result artifact, even when the task is absent from this process's in-memory + map. The public ``on_get_task`` path is covered by + ``test_get_task_reconciles_stale_in_memory_with_terminal_step``.""" + external_task_id = "task_durable_corr_1" + self._persist_a2a_step( + sample_tenant["tenant_id"], + sample_principal["principal_id"], + external_task_id, + {"media_buy_id": "mb_durable_1", "status": "completed"}, + ) + + # The poll authenticates as the buyer; resolve to the real tenant identity. + handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) + with patch.object(handler, "_resolve_a2a_identity", return_value=mock_identity): + task = handler._durable_task_from_step(external_task_id, mock_identity) + + assert task is not None, "durable fallback must resolve the buyer's outer task id to the step" + assert task.id == external_task_id + assert task.status.state == TaskState.TASK_STATE_COMPLETED + assert task.artifacts, "rebuilt terminal Task must carry the stored result artifact" + assert task.artifacts[0].parts, "result artifact must have parts" + + @pytest.mark.asyncio + async def test_durable_get_task_rebuilds_failed_task_with_the_error_binding( + self, handler, sample_tenant, sample_principal, mock_identity + ): + """A FAILED step polled durably must carry the SAME error framing a synchronous failure + emits — an ``error_result`` artifact with a human-readable TextPart beside the + authoritative envelope DataPart. + + Regression: the durable rebuild emitted one ``media_buy_result`` DataPart for every + state, so a buyer who polled an async failure got a differently-shaped artifact than the + identical failure returned synchronously — and the strict reader would reject it. + Graded through that same strict reader, so the two paths cannot drift apart again. + """ + external_task_id = "task_durable_failed_1" + envelope = { + "adcp_error": { + "code": "SERVICE_UNAVAILABLE", + "message": "An internal error occurred while processing the request.", + "recovery": "transient", + }, + "errors": [ + { + "code": "SERVICE_UNAVAILABLE", + "message": "An internal error occurred while processing the request.", + "recovery": "transient", + } + ], + } + self._persist_a2a_step( + sample_tenant["tenant_id"], + sample_principal["principal_id"], + external_task_id, + envelope, + status="failed", + ) + + handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) + with patch.object(handler, "_resolve_a2a_identity", return_value=mock_identity): + task = handler._durable_task_from_step(external_task_id, mock_identity) + + assert task is not None, "durable fallback must resolve the buyer's outer task id to the step" + assert_failed_task_envelope(task, code="SERVICE_UNAVAILABLE", recovery="transient") + + @pytest.mark.asyncio + async def test_durable_get_task_is_tenant_isolated(self, handler, sample_tenant, sample_principal): + """The durable lookup is tenant-scoped: a poll authenticated as a DIFFERENT tenant must + not resolve another tenant's outer task id.""" + from tests.factories import PrincipalFactory + + external_task_id = "task_durable_corr_2" + self._persist_a2a_step( + sample_tenant["tenant_id"], + sample_principal["principal_id"], + external_task_id, + {"media_buy_id": "mb_durable_2", "status": "completed"}, + ) + + other_identity = PrincipalFactory.make_identity( + tenant_id="a_different_tenant", principal_id="other_buyer", protocol="a2a" + ) + handler._get_auth_token = MagicMock(return_value="other-tenant-token") + with patch.object(handler, "_resolve_a2a_identity", return_value=other_identity): + task = handler._durable_task_from_step(external_task_id, other_identity) + + assert task is None, "durable lookup must not cross tenant boundaries" + + @pytest.mark.asyncio + async def test_durable_cancel_marks_pending_step_canceled( + self, handler, sample_tenant, sample_principal, mock_identity + ): + """The durable helper backing tasks/cancel resolves the buyer's outer task_* id — the + persisted non-terminal workflow step is durably marked canceled (not just the + in-memory map), and a subsequent durable tasks/get sees CANCELED.""" + external_task_id = "task_durable_cancel_1" + self._persist_a2a_step( + sample_tenant["tenant_id"], + sample_principal["principal_id"], + external_task_id, + None, + status="requires_approval", + ) + + handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) + with patch.object(handler, "_resolve_a2a_identity", return_value=mock_identity): + task = await handler.on_cancel_task(CancelTaskRequest(id=external_task_id), context=None) + polled = handler._durable_task_from_step(external_task_id, mock_identity) + + assert task is not None, "durable cancel must resolve the buyer's outer task id to the step" + assert task.id == external_task_id + assert task.status.state == TaskState.TASK_STATE_CANCELED + assert polled is not None, "a durable poll after cancel must still resolve the task" + assert polled.status.state == TaskState.TASK_STATE_CANCELED, ( + "cancel must persist on the workflow step — a poll after restart must see CANCELED" + ) + + @pytest.mark.asyncio + async def test_durable_cancel_of_terminal_step_is_not_cancelable( + self, handler, sample_tenant, sample_principal, mock_identity + ): + """A2A spec tasks/cancel: a task already in a terminal state cannot be canceled — + the persisted completed step stays completed and TaskNotCancelableError is raised.""" + external_task_id = "task_durable_cancel_2" + self._persist_a2a_step( + sample_tenant["tenant_id"], + sample_principal["principal_id"], + external_task_id, + {"media_buy_id": "mb_cancel_terminal", "status": "completed"}, + ) + + handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) + with patch.object(handler, "_resolve_a2a_identity", return_value=mock_identity): + with pytest.raises(TaskNotCancelableError): + await handler.on_cancel_task(CancelTaskRequest(id=external_task_id), context=None) + polled = handler._durable_task_from_step(external_task_id, mock_identity) + + assert polled is not None + assert polled.status.state == TaskState.TASK_STATE_COMPLETED, ( + "a refused cancel must not mutate the persisted terminal step" + ) + + @pytest.mark.asyncio + async def test_durable_cancel_is_tenant_isolated(self, handler, sample_tenant, sample_principal): + """The durable cancel is tenant-scoped: a cancel authenticated as a DIFFERENT tenant + must neither resolve nor mutate another tenant's task — surfaced as TaskNotFoundError, + the same not-found signal an unknown task id gets (no distinction between "doesn't + exist" and "not yours" leaks to the caller).""" + from tests.factories import PrincipalFactory + + external_task_id = "task_durable_cancel_3" + self._persist_a2a_step( + sample_tenant["tenant_id"], + sample_principal["principal_id"], + external_task_id, + None, + status="requires_approval", + ) + + other_identity = PrincipalFactory.make_identity( + tenant_id="a_different_tenant", principal_id="other_buyer", protocol="a2a" + ) + handler._get_auth_token = MagicMock(return_value="other-tenant-token") + with patch.object(handler, "_resolve_a2a_identity", return_value=other_identity): + with pytest.raises(TaskNotFoundError): + await handler.on_cancel_task(CancelTaskRequest(id=external_task_id), context=None) + + @pytest.mark.asyncio + async def test_cancel_of_terminal_in_memory_task_is_not_cancelable(self, handler, mock_identity): + """A2A spec tasks/cancel: the OWNER canceling an already-terminal in-memory task + gets TaskNotCancelableError, not a silent overwrite to CANCELED. + + The refusal message must name the state in the SAME lowercase vocabulary the + durable leg's step-status string uses ("completed"), not the raw protobuf + TaskState enum (which renders as its integer value, e.g. "4") — a buyer hitting + the same terminal outcome must not see an integer on one cancel leg and a word + on the other.""" + task_id = "task_inmem_terminal" + handler._remember_task( + task_id, + Task(id=task_id, context_id="ctx_inmem", status=TaskStatus(state=TaskState.TASK_STATE_COMPLETED)), + mock_identity, + ) + handler._get_auth_token = MagicMock(return_value="owner-token") + with patch.object(handler, "_resolve_a2a_identity", return_value=mock_identity): + with pytest.raises(TaskNotCancelableError) as exc_info: + await handler.on_cancel_task(CancelTaskRequest(id=task_id), context=None) + + assert "current state: completed" in str(exc_info.value) + assert handler.tasks[task_id].status.state == TaskState.TASK_STATE_COMPLETED + + @pytest.mark.asyncio + async def test_cancel_without_a_durable_step_refuses_instead_of_reporting_canceled(self, handler, mock_identity): + """A NON-terminal in-memory task with no durable counterpart must be REFUSED. + + The in-memory map is one process's view; the work lives in the workflow step. So + stamping CANCELED on an in-memory hit alone reports a stop that did not happen — + the buyer is told the task is canceled while the step keeps running and later + fires its own completed webhook. That was reachable for a submitted + ``sync_creatives``, whose outer task id was never persisted, so the durable leg + could never resolve it. + + Refusal, not a lie: ``TaskNotCancelableError``, and the in-memory task keeps its + real state rather than being overwritten. + """ + task_id = "task_inmem_no_durable" + handler._remember_task( + task_id, + Task(id=task_id, context_id="ctx_inmem", status=TaskStatus(state=TaskState.TASK_STATE_WORKING)), + mock_identity, + ) + handler._get_auth_token = MagicMock(return_value="owner-token") + with patch.object(handler, "_resolve_a2a_identity", return_value=mock_identity): + # No durable step carries this id — the production condition for a + # sync_creatives task before its outer id was persisted. + with pytest.raises(TaskNotCancelableError) as exc_info: + await handler.on_cancel_task(CancelTaskRequest(id=task_id), context=None) + + assert "no durable workflow step" in str(exc_info.value) + assert handler.tasks[task_id].status.state == TaskState.TASK_STATE_WORKING, ( + "the in-memory task must NOT be stamped CANCELED when the cancel was refused" + ) + + @pytest.mark.asyncio + async def test_cancel_of_multi_creative_sync_task_refuses( + self, handler, sample_tenant, sample_principal, mock_identity + ): + """A REAL multi-creative ``sync_creatives`` task id must never yield a CANCELED answer. + + A sync creates one workflow step PER CREATIVE, while the buyer is handed ONE + ``task_*`` id. ``get_by_external_task_id`` resolves a key to a single row, so + stamping that one id across all N steps let ``tasks/cancel`` cancel an arbitrary + one of them, commit, and answer CANCELED — while the other N-1 kept running and + later fired their own webhooks. The id is therefore not threaded into sync at all. + + Driven through the real skill so the outcome is production's, not a fixture's: + three creatives go in, three ``requires_approval`` steps come out, and none of + them carries an outer task id. Both cancel legs are then graded: + + * in-process — the sync answered terminally, so the in-memory task is COMPLETED + and the cancel is refused on terminal grounds (``TaskNotCancelableError``). + This leg reads the same either way; it is here to pin that a completed sync is + never silently re-stamped CANCELED. + * cross-process (a fresh handler, i.e. after a restart or on another worker) — + this is the leg the threading broke. With no in-memory task the cancel falls + straight to the durable lookup, which found one of the three steps and returned + a CANCELED Task. It must now find nothing and raise ``TaskNotFoundError``, with + all three steps left awaiting approval. + """ + from tests.a2a_helpers import make_a2a_context + + handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) + + creatives = [ + { + "creative_id": f"creative_multi_sync_{i}", + "name": f"Multi Sync Creative {i}", + "format_id": {"agent_url": FORMAT_AGENT_URL, "id": "display_300x250_image"}, + "assets": build_assets(image_spec(f"asset_{i}", url=f"https://example.com/creative_{i}.jpg")), + } + for i in range(3) + ] + + with patch("src.core.resolved_identity.resolve_identity", return_value=mock_identity): + ctx = make_a2a_context(headers={"host": f"{sample_tenant['subdomain']}.example.com"}) + message = create_a2a_message_with_skill("sync_creatives", {"creatives": creatives}) + task = await handler.on_message_send(SendMessageRequest(message=message), context=ctx) + + assert isinstance(task, Task) + buyer_task_id = task.id + + steps = self._pending_sync_steps(sample_tenant["tenant_id"], sample_principal["principal_id"]) + assert len(steps) == len(creatives), ( + "the sync must have produced one approval step per creative — without N>1 steps " + "this scenario would not exercise the ambiguity it exists to pin" + ) + assert all("external_task_id" not in data for data in steps), ( + "no creative-approval step may carry the buyer's outer task id: one id across N " + "steps resolves to an arbitrary one of them" + ) + + # Leg 1 — same process: refused because the sync already answered terminally. + with patch.object(handler, "_resolve_a2a_identity", return_value=mock_identity): + with pytest.raises(TaskNotCancelableError): + await handler.on_cancel_task(CancelTaskRequest(id=buyer_task_id), context=None) + assert handler.tasks[buyer_task_id].status.state != TaskState.TASK_STATE_CANCELED, ( + "a refused cancel must not stamp the in-memory task CANCELED" + ) + + # Leg 2 — a different process: only the durable store can answer, and it must not. + restarted = AdCPRequestHandler() + assert buyer_task_id not in restarted.tasks, "a fresh handler must have no in-memory view of the task" + restarted._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) + with patch.object(restarted, "_resolve_a2a_identity", return_value=mock_identity): + with pytest.raises(TaskNotFoundError): + await restarted.on_cancel_task(CancelTaskRequest(id=buyer_task_id), context=None) + + after = self._pending_sync_steps(sample_tenant["tenant_id"], sample_principal["principal_id"]) + assert len(after) == len(creatives), ( + "every creative-approval step must still be awaiting approval — cancelling an " + "arbitrary one of N and reporting CANCELED is the defect this pins" + ) + + def _pending_sync_steps(self, tenant_id: str, principal_id: str) -> list[dict]: + """``request_data`` of this principal's still-pending sync_creatives approval steps.""" + from src.core.database.repositories.uow import WorkflowUoW + + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows is not None + return [ + step.request_data or {} + for step in uow.workflows.list_by_tenant(principal_id=principal_id, status="requires_approval") + if step.tool_name == "sync_creatives" + ] + + @pytest.mark.asyncio + async def test_get_in_memory_task_is_principal_isolated( + self, handler, sample_tenant, sample_principal, mock_identity + ): + """A same-tenant sibling principal must not read another principal's + in-memory task via the public on_get_task — for BOTH a terminal and a nonterminal + victim task present in memory (task ids are bearer-ish; the map key alone is not authz). + Surfaced as TaskNotFoundError, the same not-found signal an unknown id gets.""" + from a2a.types import GetTaskRequest + + sibling = self._same_tenant_other_identity(sample_tenant) + for state in (TaskState.TASK_STATE_COMPLETED, TaskState.TASK_STATE_WORKING): + task_id = f"task_inmem_iso_get_{int(state)}" + handler._remember_task( + task_id, + Task(id=task_id, context_id="ctx_victim", status=TaskStatus(state=state)), + mock_identity, # owned by sample_principal + ) + handler._get_auth_token = MagicMock(return_value="sibling-token") + with patch.object(handler, "_resolve_a2a_identity", return_value=sibling): + with pytest.raises(TaskNotFoundError): + await handler.on_get_task(GetTaskRequest(id=task_id), context=None) + + @pytest.mark.asyncio + async def test_cancel_in_memory_task_is_principal_isolated( + self, handler, sample_tenant, sample_principal, mock_identity + ): + """A same-tenant sibling principal must not cancel another principal's + in-memory task via the public on_cancel_task; the victim task stays untouched. Covers + both a nonterminal victim (must not be mutated to CANCELED) and a terminal victim (must + not even be observable → TaskNotFoundError, the same not-found signal an unknown id + gets, not TaskNotCancelableError which would confirm the task's existence/state).""" + sibling = self._same_tenant_other_identity(sample_tenant) + + nonterminal_id = "task_inmem_iso_cancel_working" + handler._remember_task( + nonterminal_id, + Task(id=nonterminal_id, context_id="ctx_victim", status=TaskStatus(state=TaskState.TASK_STATE_WORKING)), + mock_identity, + ) + terminal_id = "task_inmem_iso_cancel_done" + handler._remember_task( + terminal_id, + Task(id=terminal_id, context_id="ctx_victim", status=TaskStatus(state=TaskState.TASK_STATE_COMPLETED)), + mock_identity, + ) + + handler._get_auth_token = MagicMock(return_value="sibling-token") + with patch.object(handler, "_resolve_a2a_identity", return_value=sibling): + with pytest.raises(TaskNotFoundError): + await handler.on_cancel_task(CancelTaskRequest(id=nonterminal_id), context=None) + with pytest.raises(TaskNotFoundError): + await handler.on_cancel_task(CancelTaskRequest(id=terminal_id), context=None) + + assert handler.tasks[nonterminal_id].status.state == TaskState.TASK_STATE_WORKING, ( + "the victim's in-memory task must not be mutated by a sibling's cancel" + ) + assert handler.tasks[terminal_id].status.state == TaskState.TASK_STATE_COMPLETED + + def _same_tenant_other_identity(self, sample_tenant): + """A different principal in the same tenant for isolation tests.""" + from tests.factories import PrincipalFactory + + return PrincipalFactory.make_identity( + tenant_id=sample_tenant["tenant_id"], principal_id="same_tenant_other_buyer", protocol="a2a" + ) + + @pytest.mark.asyncio + async def test_durable_get_is_principal_isolated(self, handler, sample_tenant, sample_principal): + """A different principal in the same tenant who learns a task id + must not read its stored response_data through the durable ``_durable_task_from_step`` helper.""" + external_task_id = "task_prin_iso_get" + self._persist_a2a_step( + sample_tenant["tenant_id"], + sample_principal["principal_id"], + external_task_id, + {"media_buy_id": "mb_prin_iso", "status": "completed"}, + ) + + sibling = self._same_tenant_other_identity(sample_tenant) + handler._get_auth_token = MagicMock(return_value="other-principal-token") + with patch.object(handler, "_resolve_a2a_identity", return_value=sibling): + task = handler._durable_task_from_step(external_task_id, sibling) + + assert task is None, "durable lookup must not cross principal boundaries within a tenant" + + @pytest.mark.asyncio + async def test_durable_cancel_is_principal_isolated(self, handler, sample_tenant, sample_principal, mock_identity): + """A different principal in the same tenant must not be able to + cancel another principal's workflow via its task id — surfaced as TaskNotFoundError, + the same not-found signal an unknown id gets.""" + external_task_id = "task_prin_iso_cancel" + self._persist_a2a_step( + sample_tenant["tenant_id"], + sample_principal["principal_id"], + external_task_id, + None, + status="requires_approval", + ) + + handler._get_auth_token = MagicMock(return_value="other-principal-token") + with patch.object( + handler, "_resolve_a2a_identity", return_value=self._same_tenant_other_identity(sample_tenant) + ): + with pytest.raises(TaskNotFoundError): + await handler.on_cancel_task(CancelTaskRequest(id=external_task_id), context=None) + + # The owner still sees the step untouched (non-terminal → WORKING skeleton). + handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) + with patch.object(handler, "_resolve_a2a_identity", return_value=mock_identity): + owner_view = handler._durable_task_from_step(external_task_id, mock_identity) + assert owner_view is not None + assert owner_view.status.state == TaskState.TASK_STATE_WORKING, ( + "the sibling principal's cancel attempt must not have mutated the step" + ) + + # ------------------------------------------------------------------ + # The same principal-isolation rule, enforced on the MCP task tools. + # + # The A2A durable get/cancel above authorize the caller, not just the tenant. + # list_tasks / get_task / complete_task read and drive the SAME workflow_steps + # rows through WorkflowRepository, so a tenant-only scope there would reopen the + # hole the A2A path closes: a sibling principal who learns (or enumerates) a step + # id could read its stored response_data or terminalize its workflow. These run + # against the real DB, so they grade the repository's WHERE clause, not a mock. + # ------------------------------------------------------------------ + + def _mcp_identity(self, tenant_id: str, principal_id: str): + """A ResolvedIdentity for the MCP task tools (they take identity= directly).""" + from tests.factories import PrincipalFactory + + return PrincipalFactory.make_identity(tenant_id=tenant_id, principal_id=principal_id, protocol="mcp") + + @pytest.mark.asyncio + async def test_list_tasks_is_principal_isolated(self, sample_tenant, sample_principal): + """``list_tasks`` must not list — or count — a sibling principal's steps. + + The total is asserted too: a page correctly filtered but counted tenant-wide + still tells the sibling how many tasks another buyer has. + """ + from src.core.tools.task_management import list_tasks + + tenant_id = sample_tenant["tenant_id"] + step_id = self._persist_a2a_step( + tenant_id, sample_principal["principal_id"], "task_mcp_iso_list", None, status="requires_approval" + ) + + owner = await list_tasks(identity=self._mcp_identity(tenant_id, sample_principal["principal_id"])) + assert step_id in [t["task_id"] for t in owner["tasks"]], ( + "control: the owning principal must see its own step, else the sibling assert is vacuous" + ) + assert owner["total"] == 1 + + sibling = await list_tasks(identity=self._mcp_identity(tenant_id, "same_tenant_other_buyer")) + assert step_id not in [t["task_id"] for t in sibling["tasks"]], ( + "list_tasks must not cross principal boundaries within a tenant" + ) + assert sibling["total"] == 0, "the pagination total must not count another principal's steps" + + @pytest.mark.asyncio + async def test_get_task_is_principal_isolated(self, sample_tenant, sample_principal): + """``get_task`` must not disclose a sibling principal's stored ``response_data``. + + Reported not-found — the same signal an unknown id gets — so the response does + not confirm the id exists. + """ + from src.core.exceptions import AdCPTaskNotFoundError + from src.core.tools.task_management import get_task + + tenant_id = sample_tenant["tenant_id"] + step_id = self._persist_a2a_step( + tenant_id, + sample_principal["principal_id"], + "task_mcp_iso_get", + {"media_buy_id": "mb_mcp_iso", "status": "completed"}, + ) + + owner_view = await get_task( + task_id=step_id, identity=self._mcp_identity(tenant_id, sample_principal["principal_id"]) + ) + assert owner_view["response_data"] == {"media_buy_id": "mb_mcp_iso", "status": "completed"}, ( + "control: the owner must read its own response_data" + ) + + with pytest.raises(AdCPTaskNotFoundError, match=step_id): + await get_task(task_id=step_id, identity=self._mcp_identity(tenant_id, "same_tenant_other_buyer")) + + @pytest.mark.asyncio + async def test_complete_task_is_principal_isolated(self, sample_tenant, sample_principal): + """``complete_task`` must not let a sibling principal terminalize another buyer's step. + + Asserts the step is still non-terminal afterwards: a refusal that had already + written would be a worse bug than the disclosure. + """ + from src.core.exceptions import AdCPTaskNotFoundError + from src.core.tools.task_management import complete_task + + tenant_id = sample_tenant["tenant_id"] + step_id = self._persist_a2a_step( + tenant_id, sample_principal["principal_id"], "task_mcp_iso_complete", None, status="requires_approval" + ) + + with pytest.raises(AdCPTaskNotFoundError, match=step_id): + await complete_task(task_id=step_id, identity=self._mcp_identity(tenant_id, "same_tenant_other_buyer")) + + assert self._step_status(tenant_id, step_id) == "requires_approval", ( + "the sibling principal's completion attempt must not have mutated the step" + ) + + # Control: the step WAS completable — the refusal above is about ownership, not state. + result = await complete_task( + task_id=step_id, identity=self._mcp_identity(tenant_id, sample_principal["principal_id"]) + ) + assert result["status"] == "completed" + assert self._step_status(tenant_id, step_id) == "completed" + + @pytest.mark.asyncio + async def test_get_task_reconciles_stale_in_memory_with_terminal_step( + self, handler, sample_tenant, sample_principal, mock_identity + ): + """The persisted workflow step is the source of truth: a poll of a + task whose in-memory entry is still WORKING but whose workflow was terminalized + in another process must return the terminal outcome, not the stale memory.""" + external_task_id = "task_stale_memory" + self._persist_a2a_step( + sample_tenant["tenant_id"], + sample_principal["principal_id"], + external_task_id, + {"media_buy_id": "mb_stale", "status": "completed"}, + ) + # Stale in-memory entry from the process that created the task (owned by the buyer). + handler._remember_task( + external_task_id, + Task(id=external_task_id, context_id="ctx_stale", status=TaskStatus(state=TaskState.TASK_STATE_WORKING)), + mock_identity, + ) + + from a2a.types import GetTaskRequest + + handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) + with patch.object(handler, "_resolve_a2a_identity", return_value=mock_identity): + task = await handler.on_get_task(GetTaskRequest(id=external_task_id), context=None) + + assert task is not None + assert task.status.state == TaskState.TASK_STATE_COMPLETED, ( + "stale in-memory WORKING must not shadow the terminal durable outcome" + ) + assert task.artifacts, "the reconciled Task must carry the stored result artifact" + assert handler.tasks[external_task_id].status.state == TaskState.TASK_STATE_COMPLETED, ( + "the in-memory map must be reconciled with the durable decision" + ) + + @pytest.mark.asyncio + async def test_get_task_without_step_returns_in_memory_task(self, handler, mock_identity): + """A non-terminal in-memory task with no persisted step (sync/simple + skills) is still served from memory TO ITS OWNER — reconciliation must not lose it.""" + from a2a.types import GetTaskRequest + + task_id = "task_memory_only" + handler._remember_task( + task_id, + Task(id=task_id, context_id="ctx_mem", status=TaskStatus(state=TaskState.TASK_STATE_SUBMITTED)), + mock_identity, + ) + handler._get_auth_token = MagicMock(return_value="owner-token") + with patch.object(handler, "_resolve_a2a_identity", return_value=mock_identity): + task = await handler.on_get_task(GetTaskRequest(id=task_id), context=None) + + assert task is not None + assert task.status.state == TaskState.TASK_STATE_SUBMITTED + + def _step_status(self, tenant_id: str, step_id: str) -> str: + """Read a workflow step's committed status in its own fresh UoW session.""" + from src.core.database.repositories import WorkflowUoW + + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows is not None + step = uow.workflows.get_by_step_id(step_id) + return step.status if step is not None else "missing" + + @pytest.mark.asyncio + async def test_cancel_and_approval_race_preserves_terminal_decision_both_orderings( + self, handler, sample_tenant, sample_principal + ): + """The terminal-transition policy is two-sided: whichever of a buyer + cancel (WorkflowRepository.cancel_if_cancellable) and an approval + (WorkflowRepository.transition_if_nonterminal) COMMITS FIRST wins, and the + loser's conditional UPDATE refuses. + + Orderings 1 and 2 are sequential and grade the committed-first-wins rule from + each side. Ordering 3 is the only one that grades the CAS as a CAS — approval + reads, cancel commits, approval writes stale — and it needs two threads to do so, + because a nested WorkflowUoW shares one thread-local session and would silently + re-grade ordering 1. It asserts the two backend pids differ, so a future change + that collapses them fails loudly instead of quietly reducing coverage.""" + from datetime import UTC, datetime + + from src.core.database.repositories import WorkflowUoW + + tenant_id = sample_tenant["tenant_id"] + principal_id = sample_principal["principal_id"] + now = datetime.now(UTC) + + # ── Ordering 1: cancel commits first → approval refused, stays canceled ── + step1 = self._persist_a2a_step(tenant_id, principal_id, "task_race_1", None, status="requires_approval") + with WorkflowUoW(tenant_id) as u_cancel: + assert u_cancel.workflows.cancel_if_cancellable(step1, completed_at=now) is True + with WorkflowUoW(tenant_id) as u_approve: + refused = u_approve.workflows.transition_if_nonterminal(step1, status="completed", completed_at=now) + assert refused is None, "approval must be refused once the step is terminally canceled" + assert self._step_status(tenant_id, step1) == "canceled" + + # ── Ordering 2: approval commits first → cancel refused, stays completed ── + step2 = self._persist_a2a_step(tenant_id, principal_id, "task_race_2", None, status="requires_approval") + with WorkflowUoW(tenant_id) as u_approve2: + assert ( + u_approve2.workflows.transition_if_nonterminal(step2, status="completed", completed_at=now) is not None + ) + with WorkflowUoW(tenant_id) as u_cancel2: + assert u_cancel2.workflows.cancel_if_cancellable(step2, completed_at=now) is False + assert self._step_status(tenant_id, step2) == "completed" + + # ── Ordering 3 (true TOCTOU overlap): approval reads a pending row, cancel + # commits in between, approval then writes with its STALE knowledge ── + # + # Run in two THREADS. A nested ``WorkflowUoW`` does not give a second session: + # get_db_session resolves through a thread-local ``scoped_session``, so the inner + # UoW hands back the SAME Session object on the SAME backend pid, and its __exit__ + # commits and closes the OUTER transaction. An earlier version of this ordering did + # exactly that, so it re-graded ordering 1 while its docstring claimed "REAL + # separate PostgreSQL sessions" and "a true TOCTOU overlap". Threads make the + # scoped_session hand out genuinely independent connections (verified below by + # asserting the two backend pids differ), and the barrier holds both transactions + # open at once so the approval's read provably precedes the cancel's commit. + step3 = self._persist_a2a_step(tenant_id, principal_id, "task_race_3", None, status="requires_approval") + + read_done = threading.Barrier(2, timeout=30) + cancel_committed = threading.Event() + outcome: dict[str, Any] = {} + + def _approver() -> None: + with WorkflowUoW(tenant_id) as uow: + outcome["approve_pid"] = uow.session.execute(text("SELECT pg_backend_pid()")).scalar() + # Stale read: the row is still pending at this point. + outcome["read_status"] = uow.workflows.get_by_step_id(step3).status + read_done.wait() # release the canceller only AFTER the stale read + assert cancel_committed.wait(timeout=30), "cancel thread never committed" + # Write with stale knowledge; the conditional UPDATE re-evaluates against + # the committed row (READ COMMITTED) and must match zero rows. + outcome["refused"] = uow.workflows.transition_if_nonterminal( + step3, status="completed", completed_at=now + ) + + def _canceller() -> None: + read_done.wait() # do not commit until the approver has read + with WorkflowUoW(tenant_id) as uow: + outcome["cancel_pid"] = uow.session.execute(text("SELECT pg_backend_pid()")).scalar() + outcome["canceled"] = uow.workflows.cancel_if_cancellable(step3, completed_at=now) + cancel_committed.set() # set AFTER __exit__ commits + + threads = [threading.Thread(target=_approver), threading.Thread(target=_canceller)] + for thread in threads: + thread.start() + for thread in threads: + thread.join(timeout=60) + assert not thread.is_alive(), "race thread deadlocked" + + assert outcome["approve_pid"] != outcome["cancel_pid"], ( + f"both halves ran on the same PostgreSQL backend, so this did not race — pid={outcome['approve_pid']}" + ) + assert outcome["read_status"] == "requires_approval", "the approval must read the PRE-cancel row" + assert outcome["canceled"] is True, "the buyer cancel must commit first" + assert outcome["refused"] is None, ( + "approval must refuse after a cancel committed, even from a stale read (TOCTOU)" + ) + assert self._step_status(tenant_id, step3) == "canceled" + + def _step_response_data(self, tenant_id: str, step_id: str) -> dict[str, Any] | None: + """Read a step's committed response_data in its own fresh UoW session.""" + from src.core.database.repositories import WorkflowUoW + + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows is not None + step = uow.workflows.get_by_step_id(step_id) + return step.response_data if step is not None else None + + async def test_context_manager_update_workflow_step_is_atomically_terminal_safe( + self, handler, sample_tenant, sample_principal + ): + """ContextManager.update_workflow_step routes the status write through + the ATOMIC conditional-UPDATE primitive (transition_if_nonterminal), so an + auto-approval that completes a step the buyer just canceled is refused with NO + partial write and NO webhook — closing the async TOCTOU that + MockAdServer._schedule_async_completion() (a delayed background thread) exposes. + The whole write is refused: neither status NOR response_data is overwritten.""" + from datetime import UTC, datetime + + from src.core.context_manager import ContextManager + from src.core.database.repositories import WorkflowUoW + + tenant_id = sample_tenant["tenant_id"] + step_id = self._persist_a2a_step( + tenant_id, sample_principal["principal_id"], "task_cm_terminal", None, status="requires_approval" + ) + # Buyer cancels first (terminal) in a separate committed session. + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.cancel_if_cancellable(step_id, completed_at=datetime.now(UTC)) + + # Auto-approval path (its OWN session) tries to complete the canceled step with new + # response_data → the atomic UPDATE matches zero rows → refused. + ContextManager().update_workflow_step(step_id, status="completed", response_data={"attempted_completion": True}) + assert self._step_status(tenant_id, step_id) == "canceled", "canceled decision must stand" + assert self._step_response_data(tenant_id, step_id) != {"attempted_completion": True}, ( + "a refused transition must not partially write response_data" + ) + + async def test_cancel_if_cancellable_refuses_approved_step(self, handler, sample_tenant, sample_principal): + """cancel_if_cancellable refuses an `approved` step (the point where + irreversible ad-server order creation begins) but accepts `requires_approval` — so a + cancel can never strand a real order behind a canceled task.""" + from datetime import UTC, datetime + + from src.core.database.repositories import WorkflowUoW + + tenant_id = sample_tenant["tenant_id"] + principal_id = sample_principal["principal_id"] + + approved = self._persist_a2a_step(tenant_id, principal_id, "task_appr", None, status="approved") + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.cancel_if_cancellable(approved, completed_at=datetime.now(UTC)) is False + assert self._step_status(tenant_id, approved) == "approved", "an approved step must not be cancellable" + + pending = self._persist_a2a_step(tenant_id, principal_id, "task_pend", None, status="requires_approval") + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.cancel_if_cancellable(pending, completed_at=datetime.now(UTC)) is True + assert self._step_status(tenant_id, pending) == "canceled" + + async def test_cancel_if_cancellable_accepts_legacy_approval_step(self, handler, sample_tenant, sample_principal): + """The legacy adapter-emitted ``approval`` status (GAM/Broadstreet/base_workflow) + is a pre-side-effect awaiting-decision alias of ``requires_approval``, so it is cancellable + for the same reason — a buyer can cancel an awaiting-approval order before any ad-server work + begins. It's approvable AND cancellable (was approvable-but-not-cancellable).""" + from datetime import UTC, datetime + + from src.core.database.repositories import WorkflowUoW + + tenant_id = sample_tenant["tenant_id"] + step_id = self._persist_a2a_step( + tenant_id, sample_principal["principal_id"], "task_legacy_appr_cancel", None, status="approval" + ) + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.cancel_if_cancellable(step_id, completed_at=datetime.now(UTC)) is True + assert self._step_status(tenant_id, step_id) == "canceled" + + @pytest.mark.asyncio + async def test_a2a_cancel_of_approved_task_is_not_cancelable( + self, handler, sample_tenant, sample_principal, mock_identity + ): + """The public A2A tasks/cancel of an `approved` task raises + TaskNotCancelableError and leaves the step approved — no orphaned ad-server order.""" + tenant_id = sample_tenant["tenant_id"] + external_task_id = "task_appr_cancel" + step_id = self._persist_a2a_step( + tenant_id, sample_principal["principal_id"], external_task_id, None, status="approved" + ) + + handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) + with patch.object(handler, "_resolve_a2a_identity", return_value=mock_identity): + with pytest.raises(TaskNotCancelableError): + await handler.on_cancel_task(CancelTaskRequest(id=external_task_id), context=None) + + assert self._step_status(tenant_id, step_id) == "approved" + + async def test_cancel_if_cancellable_refuses_in_progress_step(self, handler, sample_tenant, sample_principal): + """`in_progress` marks active external work (create/update persist it + BEFORE adapter side-effects; the approval worker claims it before approve_order), so + it must NOT be cancellable — otherwise a cancel orphans a real ad-server order behind + a canceled task. `requires_approval` (no side effects yet) stays cancellable.""" + from datetime import UTC, datetime + + from src.core.database.repositories import WorkflowUoW + + tenant_id = sample_tenant["tenant_id"] + principal_id = sample_principal["principal_id"] + + in_progress = self._persist_a2a_step(tenant_id, principal_id, "task_inprog", None, status="in_progress") + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.cancel_if_cancellable(in_progress, completed_at=datetime.now(UTC)) is False + assert self._step_status(tenant_id, in_progress) == "in_progress", "in_progress must not be cancellable" + + pending = self._persist_a2a_step(tenant_id, principal_id, "task_inprog_ctl", None, status="requires_approval") + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.cancel_if_cancellable(pending, completed_at=datetime.now(UTC)) is True + assert self._step_status(tenant_id, pending) == "canceled" + + @pytest.mark.asyncio + @pytest.mark.parametrize( + "step_status", + ["pending", "in_progress", "requires_approval", "pending_approval", "approval", "approved"], + ) + async def test_complete_task_accepts_every_nonterminal_step( + self, sample_tenant, sample_principal, mock_identity, step_status + ): + """``complete_task``'s pre-check must admit exactly what its authoritative guard admits. + + The guard it fronts is ``transition_if_nonterminal``, which keys on + ``TERMINAL_STEP_STATUSES``. The pre-check used to hand-list the three states it + remembered ("pending", "in_progress", "requires_approval"), so ``pending_approval`` + and the legacy adapter-emitted ``approval`` alias raised ``AdCPConflictError`` on + steps the guard would have accepted. Reverting to that literal reddens the + ``pending_approval`` / ``approval`` / ``approved`` rows here. + """ + from src.core.tools.task_management import complete_task + + tenant_id = sample_tenant["tenant_id"] + step_id = self._persist_a2a_step( + tenant_id, + sample_principal["principal_id"], + f"task_complete_{step_status}", + None, + status=step_status, + ) + + result = await complete_task(task_id=step_id, status="completed", identity=mock_identity) + + assert result["status"] == "completed" + assert self._step_status(tenant_id, step_id) == "completed" + + @pytest.mark.asyncio + @pytest.mark.parametrize("step_status", ["completed", "rejected", "failed", "canceled"]) + async def test_complete_task_refuses_every_terminal_step( + self, sample_tenant, sample_principal, mock_identity, step_status + ): + """The counter-control: every terminal status must still be refused. + + Without it, widening the pre-check to "not terminal" could not be told apart from + removing it entirely. + """ + from src.core.exceptions import AdCPConflictError + from src.core.tools.task_management import complete_task + + tenant_id = sample_tenant["tenant_id"] + step_id = self._persist_a2a_step( + tenant_id, + sample_principal["principal_id"], + f"task_terminal_{step_status}", + None, + status=step_status, + ) + + with pytest.raises(AdCPConflictError, match="cannot be completed"): + await complete_task(task_id=step_id, status="completed", identity=mock_identity) + + assert self._step_status(tenant_id, step_id) == step_status + @pytest.mark.asyncio async def test_natural_language_get_products( self, handler, sample_tenant, sample_principal, sample_products, mock_identity, validator @@ -481,7 +1403,13 @@ async def test_hybrid_invocation( async def test_multiple_skill_invocations( self, handler, sample_tenant, sample_principal, mock_identity, sample_products ): - """Test multiple skill invocations in a single message.""" + """A message with multiple skills is REJECTED before any skill runs. + + Aggregating divergent per-skill outcomes into one Task is incoherent once a + skill has real side effects (a submitted create_media_buy persists a workflow + while a sibling fails), so a multi-skill batch is rejected up front as a typed + UNSUPPORTED_FEATURE failed Task — no skill executes. Full-Task identity across + real per-skill child Tasks remains a separate follow-up.""" # Mock authentication token handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) @@ -526,26 +1454,23 @@ async def test_multiple_skill_invocations( ) params = SendMessageRequest(message=message) - # Process the message - this will execute the real code path + # Process the message - this executes the real code path. result = await handler.on_message_send(params, context=ctx) - # Verify both skills were processed - assert isinstance(result, Task) - assert result.metadata["invocation_type"] == "explicit_skill" - assert len(result.metadata["skills_requested"]) == 2 - assert "get_products" in result.metadata["skills_requested"] - assert "list_creative_formats" in result.metadata["skills_requested"] - assert len(result.artifacts) == 2 - - # Verify both artifacts have data (parts may have TextPart before DataPart) - for artifact in result.artifacts: - data_part_found = False - for part in artifact.parts: - # a2a-sdk 1.0 protobuf: Part uses oneof 'content' with text/raw/url/data - if part.HasField("data"): - data_part_found = True - break - assert data_part_found, "Expected DataPart in artifact.parts" + # Rejected up front → terminal failed Task with UNSUPPORTED_FEATURE, and no + # skill ran (a real get_products would have produced a product_catalog). + envelope = assert_failed_task_envelope( + result, code="UNSUPPORTED_FEATURE", recovery="correctable", artifact_name="processing_error" + ) + assert "multiple skills" in envelope["errors"][0]["message"].lower() + + # Missing/invalid authentication for tasks/get, tasks/cancel, and every other + # auth-guarded method is covered at the real JSON-RPC transport altitude by + # tests/unit/test_a2a_transport_contract.py::TestA2AAuthContract + # (test_task_management_auth_errors_use_json_rpc_dispatcher drives the real + # SDK dispatcher via TestClient(app).post("/a2a", ...); the auth-required vs. + # discovery matrix is covered by test_auth_required_skills_reject_no_auth / + # test_discovery_skills_accept_no_auth). @pytest.mark.asyncio async def test_artifact_text_part_is_the_data_part_message( @@ -590,9 +1515,6 @@ async def test_artifact_text_part_is_the_data_part_message( f"from the payload — TextPart={text_parts[0]!r} DataPart.message={data['message']!r}" ) - # TODO: Add test_missing_authentication once we understand how A2A server handles auth errors - # TODO: Needs investigation of proper error handling approach (A2AError not in current a2a library) - # test_adcp_schema_validation_integration removed (#1838 review): it built a # hand-rolled mock A2A Task/Artifact instead of exercising the real production path # — pure mocking in a file whose whole point is DB-backed integration coverage — and @@ -752,7 +1674,7 @@ async def test_list_creative_formats_skill( ctx = make_a2a_context(headers={"host": f"{sample_tenant['subdomain']}.example.com"}) # Create skill invocation - skill_params = {"brief": "display formats"} + skill_params = {} message = create_a2a_message_with_skill("list_creative_formats", skill_params) params = SendMessageRequest(message=message) @@ -1017,9 +1939,7 @@ async def test_get_media_buy_delivery_skill_forwards_typed_account( @pytest.mark.asyncio async def test_approve_creative_skill(self, handler, sample_tenant, sample_principal, mock_identity, validator): - """Test approve_creative skill raises UnsupportedOperationError.""" - from a2a.utils.errors import A2AError - + """Test approve_creative skill returns a failed Task with UNSUPPORTED_FEATURE (not JSON-RPC).""" handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) with patch("src.core.resolved_identity.resolve_identity", return_value=mock_identity): @@ -1031,14 +1951,14 @@ async def test_approve_creative_skill(self, handler, sample_tenant, sample_princ message = create_a2a_message_with_skill("approve_creative", skill_params) params = SendMessageRequest(message=message) - with pytest.raises(A2AError): - await handler.on_message_send(params, context=ctx) + result = await handler.on_message_send(params, context=ctx) + + # Application-layer failure → failed Task with UNSUPPORTED_FEATURE, not JSON-RPC. + assert_failed_task_envelope(result, code="UNSUPPORTED_FEATURE", recovery="correctable") @pytest.mark.asyncio async def test_get_media_buy_status_skill(self, handler, sample_tenant, sample_principal, mock_identity, validator): - """Test get_media_buy_status skill raises UnsupportedOperationError.""" - from a2a.utils.errors import A2AError - + """Test get_media_buy_status skill returns a failed Task with UNSUPPORTED_FEATURE (not JSON-RPC).""" handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) with patch("src.core.resolved_identity.resolve_identity", return_value=mock_identity): @@ -1050,14 +1970,14 @@ async def test_get_media_buy_status_skill(self, handler, sample_tenant, sample_p message = create_a2a_message_with_skill("get_media_buy_status", skill_params) params = SendMessageRequest(message=message) - with pytest.raises(A2AError): - await handler.on_message_send(params, context=ctx) + result = await handler.on_message_send(params, context=ctx) + + # Application-layer failure → failed Task with UNSUPPORTED_FEATURE, not JSON-RPC. + assert_failed_task_envelope(result, code="UNSUPPORTED_FEATURE", recovery="correctable") @pytest.mark.asyncio async def test_optimize_media_buy_skill(self, handler, sample_tenant, sample_principal, mock_identity, validator): - """Test optimize_media_buy skill raises UnsupportedOperationError.""" - from a2a.utils.errors import A2AError - + """Test optimize_media_buy skill returns a failed Task with UNSUPPORTED_FEATURE (not JSON-RPC).""" handler._get_auth_token = MagicMock(return_value=sample_principal["access_token"]) with patch("src.core.resolved_identity.resolve_identity", return_value=mock_identity): @@ -1069,8 +1989,10 @@ async def test_optimize_media_buy_skill(self, handler, sample_tenant, sample_pri message = create_a2a_message_with_skill("optimize_media_buy", skill_params) params = SendMessageRequest(message=message) - with pytest.raises(A2AError): - await handler.on_message_send(params, context=ctx) + result = await handler.on_message_send(params, context=ctx) + + # Application-layer failure → failed Task with UNSUPPORTED_FEATURE, not JSON-RPC. + assert_failed_task_envelope(result, code="UNSUPPORTED_FEATURE", recovery="correctable") if __name__ == "__main__": diff --git a/tests/integration/test_admin_approval_atomicity.py b/tests/integration/test_admin_approval_atomicity.py new file mode 100644 index 0000000000..ae7c9ce765 --- /dev/null +++ b/tests/integration/test_admin_approval_atomicity.py @@ -0,0 +1,1021 @@ +"""Admin approve/reject routes use the atomic terminal-transition primitive. + +operations.py (media-buy approve/reject) and policy.py (review_task) previously wrote +``step.status = "..."`` with raw ORM after a pending read, bypassing +``WorkflowRepository.transition_if_nonterminal`` — so a buyer cancel committing in between +was silently overwritten (and, for approve, irreversible adapter order creation ran anyway). +They now route through the atomic conditional UPDATE and treat a refused transition (None) +as a conflict: no overwrite, and no ``execute_approved_media_buy``. +""" + +import uuid +from unittest.mock import patch + +import pytest + +from src.admin.app import create_app +from src.core.context_manager import ContextManager +from src.core.database.repositories import MediaBuyUoW, WorkflowUoW + +app = create_app() + +pytestmark = [pytest.mark.integration, pytest.mark.requires_db] + + +@pytest.fixture +def client(): + app.config["TESTING"] = True + app.config["WTF_CSRF_ENABLED"] = False + app.config["SESSION_COOKIE_PATH"] = "/" + with app.test_client() as c: + yield c + + +def _auth(client, tenant_id): + with client.session_transaction() as sess: + sess["authenticated"] = True + sess["user"] = {"email": "admin@example.com", "is_super_admin": True} + sess["email"] = "admin@example.com" + sess["tenant_id"] = tenant_id + sess["test_user"] = "admin@example.com" + sess["test_user_role"] = "super_admin" + sess["test_tenant_id"] = tenant_id + + +def _make_step( + tenant_id: str, + principal_id: str, + status: str, + *, + media_buy_id: str | None = None, + step_type: str = "approval", + external_task_id: str | None = None, + mapping_action: str = "approve", + request_data: dict | None = None, +) -> str: + """Create a Context + WorkflowStep (optionally mapped to a media_buy) via ContextManager + (no raw session.add — factory/persistence-layer pattern). Returns the step id.""" + cm = ContextManager() + ctx = cm.create_context(tenant_id=tenant_id, principal_id=principal_id) + mappings = ( + [{"object_type": "media_buy", "object_id": media_buy_id, "action": mapping_action}] if media_buy_id else None + ) + step = cm.create_workflow_step( + context_id=ctx.context_id, + step_type=step_type, + owner="publisher", + status=status, + tool_name="create_media_buy", + request_data=request_data or {}, + request_metadata=( + {"protocol": "a2a", "external_task_id": external_task_id} if external_task_id is not None else None + ), + object_mappings=mappings, + ) + return step.step_id + + +def _status(tenant_id: str, step_id: str) -> str: + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows is not None + step = uow.workflows.get_by_step_id(step_id) + return step.status if step else "missing" + + +def _authed_media_buy_awaiting_approval( + client, + step_status: str = "requires_approval", + *, + external_task_id: str | None = None, + request_data: dict | None = None, + with_approved_creative: bool = True, +): + """A uniquely-suffixed tenant/principal/media-buy plus an authed session and an approval step. + + Returns ``(tenant_id, media_buy_id, step_id)``. The uuid suffix keeps the rows collision-free + under xdist. Extracted because the identical block appeared verbatim in the route-level tests + below — the clone checker cannot see an intra-file duplicate, so it has to be caught by hand. + """ + from tests.factories import CreativeAssignmentFactory, CreativeFactory, MediaBuyFactory + + suffix = uuid.uuid4().hex[:8] + media_buy = MediaBuyFactory( + tenant__tenant_id=f"t_{suffix}", + tenant__subdomain=f"sub-{suffix}", + principal__principal_id=f"p_{suffix}", + principal__access_token=f"tok_{suffix}", + media_buy_id=f"mb_{suffix}", + status="pending_approval", + ) + if with_approved_creative: + creative = CreativeFactory( + tenant=media_buy.tenant, + principal=media_buy.principal, + status="approved", + ) + CreativeAssignmentFactory( + creative=creative, + media_buy=media_buy, + package_id=f"pkg_{suffix}", + ) + _auth(client, media_buy.tenant_id) + step_id = _make_step( + media_buy.tenant_id, + media_buy.principal_id, + step_status, + media_buy_id=media_buy.media_buy_id, + external_task_id=external_task_id, + request_data=request_data, + ) + return media_buy.tenant_id, media_buy.media_buy_id, step_id + + +class TestPolicyReviewAtomicity: + def test_review_approve_of_canceled_step_is_conflict(self, client, sample_tenant, sample_principal): + """Policy review of an already-canceled step is refused (409), not + overwritten to completed.""" + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + step_id = _make_step(tenant_id, sample_principal["principal_id"], "canceled", step_type="policy_review") + + resp = client.post(f"/tenant/{tenant_id}/policy/review/{step_id}", data={"action": "approve", "notes": "n"}) + assert resp.status_code == 409 + assert _status(tenant_id, step_id) == "canceled" + + def test_review_approve_of_pending_step_completes(self, client, sample_tenant, sample_principal): + """Positive control: a pending review approves to completed.""" + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + step_id = _make_step( + tenant_id, sample_principal["principal_id"], "requires_approval", step_type="policy_review" + ) + + resp = client.post(f"/tenant/{tenant_id}/policy/review/{step_id}", data={"action": "approve", "notes": "n"}) + assert resp.status_code in (200, 302) + assert _status(tenant_id, step_id) == "completed" + + def test_review_refused_for_authenticated_outsider(self, client, sample_tenant, sample_principal): + """A session authenticated to the app but with NO User record in the tenant must not + be able to review the tenant's steps. Regression guard: the route previously used the + bare authentication decorator (no tenant lookup), and its inline role gate never fired + for regular OAuth users — so any signed-in outsider could drive a cross-tenant + approve/reject.""" + tenant_id = sample_tenant["tenant_id"] + step_id = _make_step( + tenant_id, sample_principal["principal_id"], "requires_approval", step_type="policy_review" + ) + + with client.session_transaction() as sess: + sess.clear() + sess["user"] = "outsider@evil.example" + + resp = client.post(f"/tenant/{tenant_id}/policy/review/{step_id}", data={"action": "approve", "notes": "n"}) + assert resp.status_code == 403, f"outsider must be refused, got {resp.status_code}" + assert _status(tenant_id, step_id) == "requires_approval", "outsider must not transition the step" + + def test_review_refuses_non_policy_step(self, client, sample_tenant, sample_principal): + """The policy review route must action POLICY steps only: an arbitrary step id (e.g. a + media-buy approval awaiting decision) is 404, not driven terminal with a fabricated + {"approved": true} artifact — which would strand the media buy unapprovable while the + buyer's durable read showed completed.""" + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + step_id = _make_step(tenant_id, sample_principal["principal_id"], "requires_approval") + + resp = client.post(f"/tenant/{tenant_id}/policy/review/{step_id}", data={"action": "approve", "notes": "n"}) + assert resp.status_code == 404, f"non-policy step must be 404, got {resp.status_code}" + assert _status(tenant_id, step_id) == "requires_approval", "non-policy step must be left untouched" + + def test_review_unknown_action_is_bad_request_not_conflict(self, client, sample_tenant, sample_principal): + """An unknown/missing action is a client error (400 Bad Request), distinct from the 409 + finalized-task conflict, and must not transition a still-pending step. Regression guard: + the else branch previously fell through with ``transitioned = None`` and mislabeled the + bad request as a 409 conflict.""" + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + step_id = _make_step( + tenant_id, sample_principal["principal_id"], "requires_approval", step_type="policy_review" + ) + + resp = client.post(f"/tenant/{tenant_id}/policy/review/{step_id}", data={"action": "frobnicate", "notes": "n"}) + assert resp.status_code == 400 + assert _status(tenant_id, step_id) == "requires_approval", "an unknown action must not transition the step" + + +class TestOperationsApproveAtomicity: + def test_media_buy_approve_refused_claim_skips_adapter(self, client, sample_tenant, sample_principal): + """When the approval claim is refused (a concurrent approve/cancel won the + race), the media-buy approve route must NOT run the irreversible execute_approved_media_buy + and must surface a conflict (redirect) — the step is not overwritten. The route uses the + source-state-guarded ``claim_approval`` (NOT the broad transition_if_nonterminal, which + would let approved→approved slip through).""" + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + media_buy_id = f"mb_{uuid.uuid4().hex[:8]}" + step_id = _make_step( + tenant_id, sample_principal["principal_id"], "requires_approval", media_buy_id=media_buy_id + ) + + with ( + patch( + "src.admin.blueprints.operations.WorkflowRepository.claim_approval", + return_value=None, + ) as mock_claim, + patch("src.core.tools.media_buy_create.execute_approved_media_buy") as mock_execute, + ): + resp = client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "approve", "workflow_step_id": step_id}, + follow_redirects=False, + ) + + mock_claim.assert_called_once_with(step_id) + mock_execute.assert_not_called() + assert _status(tenant_id, step_id) == "requires_approval", "refused claim must not overwrite the step" + assert resp.status_code in (302, 303) + + def test_plain_approval_completion_failure_rolls_back_claim( + self, + client, + sample_tenant, + sample_principal, + ): + """A no-execution approval stays reclaimable when atomic completion is refused.""" + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + media_buy_id = f"missing_mb_{uuid.uuid4().hex[:8]}" + step_id = _make_step( + tenant_id, + sample_principal["principal_id"], + "requires_approval", + media_buy_id=media_buy_id, + ) + + with ( + patch( + "src.admin.blueprints.operations.WorkflowRepository.complete_claimed_approval", + return_value=None, + ), + patch("src.core.tools.media_buy_create.execute_approved_media_buy") as mock_execute, + ): + response = client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "approve", "workflow_step_id": step_id}, + follow_redirects=False, + ) + + mock_execute.assert_not_called() + assert response.status_code in (302, 303) + assert _status(tenant_id, step_id) == "requires_approval" + + def test_media_buy_unknown_action_is_flagged_not_silent(self, client, factory_session): + """An action that is neither approve nor reject must not silently no-op (indistinguishable + from success to the operator). The route flashes an error and does not transition the step + or run the adapter. Regression guard: the route previously fell through both branches to a + bare redirect, while the sibling policy route already returned an explicit error.""" + tenant_id, media_buy_id, step_id = _authed_media_buy_awaiting_approval(client) + + with patch("src.core.tools.media_buy_create.execute_approved_media_buy") as mock_execute: + resp = client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "frobnicate", "workflow_step_id": step_id}, + follow_redirects=True, + ) + + mock_execute.assert_not_called() + assert _status(tenant_id, step_id) == "requires_approval", "unknown action must not transition the step" + assert "unknown action" in resp.get_data(as_text=True).lower() + + def test_successful_approve_does_run_the_adapter(self, client, factory_session): + """POSITIVE CONTROL for the ``execute_approved_media_buy`` patch target. + + Every other test in this file asserts the adapter was NOT called. If the patch target were + wrong (the route body-imports the symbol, so it must be patched at its SOURCE module), all + of those would pass vacuously — the mock would simply never be the object the route calls. + This test drives a genuine approve to completion through the SAME target and asserts it WAS + called, so the negative assertions are anchored to a target proven to intercept. + """ + tenant_id, media_buy_id, step_id = _authed_media_buy_awaiting_approval(client) + + with patch( + "src.core.tools.media_buy_create.execute_approved_media_buy", return_value=(True, None) + ) as mock_execute: + client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "approve", "workflow_step_id": step_id}, + follow_redirects=True, + ) + + mock_execute.assert_called_once_with(media_buy_id, tenant_id, execution_claimed=True) + assert _status(tenant_id, step_id) == "completed", ( + "a successful adapter execution must terminalize the claimed step" + ) + + def test_media_buy_detail_approval_honors_shared_creative_gate(self, client, factory_session): + """The detail route must not bypass the creative gate used by workflow approval.""" + from src.core.database.models import MediaBuy + from tests.factories import CreativeAssignmentFactory, CreativeFactory + + tenant_id, media_buy_id, step_id = _authed_media_buy_awaiting_approval(client) + media_buy = factory_session.get(MediaBuy, media_buy_id) + assert media_buy is not None + creative = CreativeFactory( + tenant=media_buy.tenant, + principal=media_buy.principal, + status="pending_review", + ) + CreativeAssignmentFactory( + creative=creative, + media_buy=media_buy, + package_id="pkg_creative_gate", + ) + + with patch("src.core.tools.media_buy_create.execute_approved_media_buy") as mock_execute: + response = client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "approve", "workflow_step_id": step_id}, + follow_redirects=False, + ) + + assert response.status_code in (302, 303) + mock_execute.assert_not_called() + assert _status(tenant_id, step_id) == "approved" + with MediaBuyUoW(tenant_id) as uow: + assert uow.media_buys is not None + persisted = uow.media_buys.get_by_id(media_buy_id) + assert persisted is not None + assert persisted.status == "pending_creatives" + + def test_detail_route_approves_a_pending_creatives_buy_instead_of_silently_completing( + self, client, factory_session + ): + """A buy in a non-``pending_approval`` source state must still go through the gate. + + The route used to pre-filter on ``media_buy.status == "pending_approval"``, so a + ``pending_creatives`` buy fell to the plain-workflow branch: the workflow step was + terminalized, the operator was told "approved successfully", and the buy was never + executed and never gated. Every eligibility decision now belongs to + ``prepare_media_buy_approval_execution``. + + Here the buy is ``pending_creatives`` with an APPROVED creative, so the gate is + satisfied and the adapter must actually run — the pre-filter's failure mode was + silence, so a test that only asserted "not executed" would have passed on it. + """ + from src.core.database.models import MediaBuy + from tests.factories import CreativeAssignmentFactory, CreativeFactory + + tenant_id, media_buy_id, step_id = _authed_media_buy_awaiting_approval(client) + media_buy = factory_session.get(MediaBuy, media_buy_id) + assert media_buy is not None + creative = CreativeFactory( + tenant=media_buy.tenant, + principal=media_buy.principal, + status="approved", + ) + CreativeAssignmentFactory( + creative=creative, + media_buy=media_buy, + package_id="pkg_already_gated", + ) + # The state the old literal did not recognise. + media_buy.status = "pending_creatives" + factory_session.commit() + + with patch( + "src.core.tools.media_buy_create.execute_approved_media_buy", return_value=(True, None) + ) as mock_execute: + response = client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "approve", "workflow_step_id": step_id}, + follow_redirects=False, + ) + + assert response.status_code in (302, 303) + mock_execute.assert_called_once_with(media_buy_id, tenant_id, execution_claimed=True) + with MediaBuyUoW(tenant_id) as uow: + assert uow.media_buys is not None + persisted = uow.media_buys.get_by_id(media_buy_id) + assert persisted is not None + assert persisted.status != "pending_creatives", ( + "the buy must have been claimed for execution, not left in its source state" + ) + + def test_media_buy_detail_approval_without_assignments_waits_for_creatives(self, client, factory_session): + """The detail route cannot execute a buy that has no creative assignment.""" + tenant_id, media_buy_id, step_id = _authed_media_buy_awaiting_approval( + client, + with_approved_creative=False, + ) + + with patch("src.core.tools.media_buy_create.execute_approved_media_buy") as mock_execute: + response = client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "approve", "workflow_step_id": step_id}, + follow_redirects=False, + ) + + assert response.status_code in (302, 303) + mock_execute.assert_not_called() + assert _status(tenant_id, step_id) == "approved" + with MediaBuyUoW(tenant_id) as uow: + assert uow.media_buys is not None + persisted = uow.media_buys.get_by_id(media_buy_id) + assert persisted is not None + assert persisted.status == "pending_creatives" + + def test_media_buy_is_claimed_before_adapter_dispatch(self, client, factory_session): + """The route commits ``activating`` before entering the execution helper.""" + from src.core.database.repositories import MediaBuyUoW + + tenant_id, media_buy_id, step_id = _authed_media_buy_awaiting_approval(client) + + def assert_claimed_at_adapter_boundary( + observed_media_buy_id, + observed_tenant_id, + *, + execution_claimed, + ): + assert execution_claimed is True + with MediaBuyUoW(observed_tenant_id) as uow: + assert uow.media_buys is not None + media_buy = uow.media_buys.get_by_id(observed_media_buy_id) + assert media_buy is not None + assert media_buy.status == "activating" + uow.media_buys.update_status(observed_media_buy_id, "active") + return True, None + + with patch( + "src.core.tools.media_buy_create.execute_approved_media_buy", + side_effect=assert_claimed_at_adapter_boundary, + ): + client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "approve", "workflow_step_id": step_id}, + follow_redirects=False, + ) + + assert _status(tenant_id, step_id) == "completed" + + def test_post_creation_pending_outcome_does_not_terminalize_failure(self, client, factory_session): + """External success plus local uncertainty remains safely nonterminal.""" + from src.a2a_server.adcp_a2a_server import AdCPRequestHandler + from tests.factories import PrincipalFactory + from tests.utils.a2a_helpers import assert_failed_task_envelope + + external_task_id = f"task_activation_pending_{uuid.uuid4().hex[:8]}" + tenant_id, media_buy_id, step_id = _authed_media_buy_awaiting_approval( + client, + external_task_id=external_task_id, + ) + + def leave_ambiguous_claim( + observed_media_buy_id, + observed_tenant_id, + *, + execution_claimed, + ): + assert execution_claimed is True + with MediaBuyUoW(observed_tenant_id) as uow: + assert uow.media_buys is not None + assert uow.media_buys.mark_approved_execution_unknown(observed_media_buy_id) is True + return None, "local activation commit failed" + + with patch( + "src.core.tools.media_buy_create.execute_approved_media_buy", + side_effect=leave_ambiguous_claim, + ): + response = client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "approve", "workflow_step_id": step_id}, + follow_redirects=False, + ) + + assert response.status_code == 302 + assert _status(tenant_id, step_id) == "approved" + + identity = PrincipalFactory.make_identity( + tenant_id=tenant_id, + principal_id=f"p_{tenant_id.removeprefix('t_')}", + protocol="a2a", + ) + task = AdCPRequestHandler()._durable_task_from_step(external_task_id, identity) + assert task is not None + assert_failed_task_envelope(task, code="SERVICE_UNAVAILABLE", recovery="transient") + assert _status(tenant_id, step_id) == "failed" + + def test_successful_approve_is_durably_completed_for_fresh_a2a_handler(self, client, factory_session): + """A cross-process tasks/get sees the terminal result after admin approval.""" + from a2a.types import TaskState + + from src.a2a_server.adcp_a2a_server import AdCPRequestHandler + from tests.factories import PrincipalFactory + from tests.utils.a2a_helpers import extract_data_from_artifact + + external_task_id = f"task_admin_success_{uuid.uuid4().hex[:8]}" + request_context = {"trace_id": f"trace_{uuid.uuid4().hex[:8]}"} + tenant_id, media_buy_id, _step_id = _authed_media_buy_awaiting_approval( + client, + external_task_id=external_task_id, + request_data={"context": request_context}, + ) + + with patch("src.core.tools.media_buy_create.execute_approved_media_buy", return_value=(True, None)): + client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "approve", "workflow_step_id": _step_id}, + follow_redirects=False, + ) + + identity = PrincipalFactory.make_identity( + tenant_id=tenant_id, + principal_id=f"p_{tenant_id.removeprefix('t_')}", + protocol="a2a", + ) + task = AdCPRequestHandler()._durable_task_from_step(external_task_id, identity) + + assert task is not None + assert task.status.state == TaskState.TASK_STATE_COMPLETED + assert task.artifacts and task.artifacts[0].name == "media_buy_result" + result = extract_data_from_artifact(task.artifacts[0]) + assert result["media_buy_id"] == media_buy_id + assert result["status"] == "completed" + assert result["context"] == request_context + + def test_failed_approve_is_durably_failed_for_fresh_a2a_handler(self, client, factory_session): + """Adapter failure persists a sanitized failed artifact for tasks/get.""" + from src.a2a_server.adcp_a2a_server import AdCPRequestHandler + from tests.factories import PrincipalFactory + from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE + from tests.utils.a2a_helpers import assert_failed_task_envelope, assert_failed_task_no_secret_leak + + external_task_id = f"task_admin_failure_{uuid.uuid4().hex[:8]}" + tenant_id, media_buy_id, step_id = _authed_media_buy_awaiting_approval( + client, + external_task_id=external_task_id, + ) + + with patch( + "src.core.tools.media_buy_create.execute_approved_media_buy", + return_value=(False, SECRET_BEARING_MESSAGE), + ): + client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "approve", "workflow_step_id": step_id}, + follow_redirects=False, + ) + + identity = PrincipalFactory.make_identity( + tenant_id=tenant_id, + principal_id=f"p_{tenant_id.removeprefix('t_')}", + protocol="a2a", + ) + task = AdCPRequestHandler()._durable_task_from_step(external_task_id, identity) + + assert task is not None + assert_failed_task_envelope(task, code="SERVICE_UNAVAILABLE", recovery="transient") + assert_failed_task_no_secret_leak(task) + + def test_media_buy_detail_approves_legacy_approval_status_step(self, client, sample_tenant, sample_principal): + """The media-buy detail approve route finds and approves a legacy ``approval`` + step — its lookup previously prefiltered on {requires_approval, pending_approval} only and + returned 'No pending approval found' before reaching the canonical claim.""" + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + media_buy_id = f"mb_{uuid.uuid4().hex[:8]}" + step_id = _make_step(tenant_id, sample_principal["principal_id"], "approval", media_buy_id=media_buy_id) + + resp = client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "approve", "workflow_step_id": step_id}, + follow_redirects=False, + ) + + assert resp.status_code in (200, 302, 303) + assert _status(tenant_id, step_id) == "completed", ( + "a legacy approval step must be approvable and terminalized via the detail route" + ) + + def test_creative_unblock_ignores_newer_update_mapping(self, client, factory_session): + """Creative unblock terminalizes the claimed create step, not a later update mapping.""" + from src.core.workflow_finalization import finalize_latest_media_buy_approval_step + + tenant_id, media_buy_id, create_step_id = _authed_media_buy_awaiting_approval(client) + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.claim_approval(create_step_id) is not None + + update_step_id = _make_step( + tenant_id, + f"p_{tenant_id.removeprefix('t_')}", + "in_progress", + media_buy_id=media_buy_id, + step_type="tool_call", + mapping_action="update", + ) + + finalization = finalize_latest_media_buy_approval_step( + tenant_id=tenant_id, + media_buy_id=media_buy_id, + succeeded=True, + ) + + assert finalization.applied + assert _status(tenant_id, create_step_id) == "completed" + assert _status(tenant_id, update_step_id) == "in_progress" + + def test_media_buy_detail_rejects_legacy_approval_status_step(self, client, sample_tenant, sample_principal): + """The media-buy detail reject action (same route, action=reject) rejects a + legacy ``approval`` step through the canonical reject_if_approvable.""" + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + media_buy_id = f"mb_{uuid.uuid4().hex[:8]}" + step_id = _make_step(tenant_id, sample_principal["principal_id"], "approval", media_buy_id=media_buy_id) + + resp = client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "reject", "reason": "no", "workflow_step_id": step_id}, + follow_redirects=False, + ) + + assert resp.status_code in (200, 302, 303) + assert _status(tenant_id, step_id) == "rejected", ( + "a legacy approval step must be rejectable via the detail route" + ) + + +class TestApprovalClaimCompareAndSet: + """claim_approval / reject_if_approvable are source-state-guarded compare-and-sets. + + Because ``approved`` is (deliberately) non-terminal, the broad ``transition_if_nonterminal`` + guard would admit an ``approved → approved`` no-op — a second concurrent approver that also + runs execute_approved_media_buy (duplicate order). These pin the narrower guard. + """ + + def test_claim_approval_admits_exactly_one_approver(self, sample_tenant, sample_principal): + tenant_id = sample_tenant["tenant_id"] + step_id = _make_step(tenant_id, sample_principal["principal_id"], "requires_approval") + + with WorkflowUoW(tenant_id) as uow: + first = uow.workflows.claim_approval(step_id) + assert first is not None and first.status == "approved" + with WorkflowUoW(tenant_id) as uow: + second = uow.workflows.claim_approval(step_id) + assert second is None, "a second approver must not re-claim an already-approved step" + assert _status(tenant_id, step_id) == "approved" + + def test_media_buy_execution_claim_admits_exactly_one_claim(self, factory_session): + """The durable domain claim closes the creative-approval dispatch race.""" + from tests.factories import MediaBuyFactory + + suffix = uuid.uuid4().hex[:8] + media_buy = MediaBuyFactory( + tenant__tenant_id=f"t_claim_{suffix}", + tenant__subdomain=f"claim-{suffix}", + principal__principal_id=f"p_claim_{suffix}", + principal__access_token=f"tok_claim_{suffix}", + media_buy_id=f"mb_claim_{suffix}", + status="pending_creatives", + ) + + with MediaBuyUoW(media_buy.tenant_id) as uow: + assert uow.media_buys is not None + assert uow.media_buys.claim_approved_execution(media_buy.media_buy_id) is True + with MediaBuyUoW(media_buy.tenant_id) as uow: + assert uow.media_buys is not None + assert uow.media_buys.claim_approved_execution(media_buy.media_buy_id) is False + claimed = uow.media_buys.get_by_id(media_buy.media_buy_id) + assert claimed is not None + assert claimed.status == "activating" + + def test_expired_claim_takeover_blocks_late_success(self, factory_session): + """A worker cannot publish active after reconciliation owns the row.""" + from tests.factories import MediaBuyFactory + + suffix = uuid.uuid4().hex[:8] + media_buy = MediaBuyFactory( + tenant__tenant_id=f"t_takeover_{suffix}", + tenant__subdomain=f"takeover-{suffix}", + principal__principal_id=f"p_takeover_{suffix}", + principal__access_token=f"tok_takeover_{suffix}", + media_buy_id=f"mb_takeover_{suffix}", + status="pending_approval", + ) + + with MediaBuyUoW(media_buy.tenant_id) as uow: + assert uow.media_buys is not None + assert uow.media_buys.claim_approved_execution(media_buy.media_buy_id) is True + assert uow.media_buys.mark_approved_execution_unknown(media_buy.media_buy_id) is True + with MediaBuyUoW(media_buy.tenant_id) as uow: + assert uow.media_buys is not None + assert uow.media_buys.complete_approved_execution(media_buy.media_buy_id) is False + recovered = uow.media_buys.get_by_id(media_buy.media_buy_id) + assert recovered is not None + assert recovered.status == "activation_unknown" + + def test_heartbeat_between_observation_and_takeover_wins_timestamp_cas(self, factory_session): + """A renewed lease cannot be stolen using an older observed version.""" + from tests.factories import MediaBuyFactory + + suffix = uuid.uuid4().hex[:8] + media_buy = MediaBuyFactory( + tenant__tenant_id=f"t_renew_{suffix}", + tenant__subdomain=f"renew-{suffix}", + principal__principal_id=f"p_renew_{suffix}", + principal__access_token=f"tok_renew_{suffix}", + media_buy_id=f"mb_renew_{suffix}", + status="pending_approval", + ) + + with MediaBuyUoW(media_buy.tenant_id) as uow: + assert uow.media_buys is not None + assert uow.media_buys.claim_approved_execution(media_buy.media_buy_id) is True + claimed = uow.media_buys.get_by_id(media_buy.media_buy_id) + assert claimed is not None + observed_updated_at = claimed.updated_at + with MediaBuyUoW(media_buy.tenant_id) as uow: + assert uow.media_buys is not None + assert uow.media_buys.renew_approved_execution_lease(media_buy.media_buy_id) is True + with MediaBuyUoW(media_buy.tenant_id) as uow: + assert uow.media_buys is not None + assert ( + uow.media_buys.mark_approved_execution_unknown( + media_buy.media_buy_id, + expected_updated_at=observed_updated_at, + ) + is False + ) + assert uow.media_buys.complete_approved_execution(media_buy.media_buy_id) is True + completed = uow.media_buys.get_by_id(media_buy.media_buy_id) + assert completed is not None + assert completed.status == "active" + + def test_claim_approval_refuses_non_approvable_statuses(self, sample_tenant, sample_principal): + tenant_id = sample_tenant["tenant_id"] + principal_id = sample_principal["principal_id"] + for status in ("pending", "in_progress", "approved", "completed", "rejected", "canceled"): + step_id = _make_step(tenant_id, principal_id, status) + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.claim_approval(step_id) is None, f"{status} must not be claimable" + assert _status(tenant_id, step_id) == status, f"{status} must be left unchanged" + # Positive control: pending_approval is claimable. + ok = _make_step(tenant_id, principal_id, "pending_approval") + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.claim_approval(ok) is not None + assert _status(tenant_id, ok) == "approved" + + def test_reject_if_approvable_refuses_approved_step(self, sample_tenant, sample_principal): + tenant_id = sample_tenant["tenant_id"] + principal_id = sample_principal["principal_id"] + approved = _make_step(tenant_id, principal_id, "approved") + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.reject_if_approvable(approved, error_message="no") is None + assert _status(tenant_id, approved) == "approved", "an approved step must not be rejectable" + # Positive control: a step still awaiting a decision rejects. + pending = _make_step(tenant_id, principal_id, "requires_approval") + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.reject_if_approvable(pending, error_message="bad") is not None + assert _status(tenant_id, pending) == "rejected" + + def test_legacy_approval_status_is_claimable_and_rejectable(self, sample_tenant, sample_principal): + """Regression guard: the legacy adapter-emitted ``approval`` status (GAM / + Broadstreet / base_workflow default) is awaiting-decision and MUST be approvable and + rejectable; excluding it would return 409 for live human workflows.""" + tenant_id = sample_tenant["tenant_id"] + principal_id = sample_principal["principal_id"] + + to_approve = _make_step(tenant_id, principal_id, "approval") + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.claim_approval(to_approve) is not None + assert _status(tenant_id, to_approve) == "approved" + + to_reject = _make_step(tenant_id, principal_id, "approval") + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.reject_if_approvable(to_reject, error_message="no") is not None + assert _status(tenant_id, to_reject) == "rejected" + + def test_get_approvable_step_for_object_uses_canonical_set(self, sample_tenant, sample_principal): + """get_approvable_step_for_object finds a mapped step in any canonical + approvable status — including the legacy ``approval`` alias — and returns None once the + step is no longer approvable (so the admin media-buy detail lookup matches the CAS guard).""" + tenant_id = sample_tenant["tenant_id"] + principal_id = sample_principal["principal_id"] + for status in ("requires_approval", "pending_approval", "approval"): + mb = f"mb_{uuid.uuid4().hex[:8]}" + step_id = _make_step(tenant_id, principal_id, status, media_buy_id=mb) + with WorkflowUoW(tenant_id) as uow: + found = uow.workflows.get_approvable_step_for_object("media_buy", mb) + # Read attributes INSIDE the session (the ORM object detaches on exit). + assert found is not None and found.step_id == step_id, f"a {status} step must be found" + # A step that is no longer awaiting a decision is not returned. + mb_done = f"mb_{uuid.uuid4().hex[:8]}" + _make_step(tenant_id, principal_id, "approved", media_buy_id=mb_done) + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows.get_approvable_step_for_object("media_buy", mb_done) is None + + def test_get_approvable_step_for_object_selects_exact_rendered_step(self, sample_tenant, sample_principal): + """Multiple approval operations may map to one media buy; POST must revalidate the + exact step rendered by GET instead of selecting an arbitrary sibling.""" + tenant_id = sample_tenant["tenant_id"] + principal_id = sample_principal["principal_id"] + media_buy_id = f"mb_{uuid.uuid4().hex[:8]}" + first_id = _make_step(tenant_id, principal_id, "approval", media_buy_id=media_buy_id) + second_id = _make_step(tenant_id, principal_id, "requires_approval", media_buy_id=media_buy_id) + + with WorkflowUoW(tenant_id) as uow: + default = uow.workflows.get_approvable_step_for_object("media_buy", media_buy_id) + exact = uow.workflows.get_approvable_step_for_object("media_buy", media_buy_id, step_id=second_id) + assert default is not None and default.step_id == first_id + assert exact is not None and exact.step_id == second_id + + def test_media_buy_detail_post_actions_only_selected_step(self, client, sample_tenant, sample_principal): + """A stale/multi-step form actions its explicit step and leaves siblings untouched.""" + tenant_id = sample_tenant["tenant_id"] + principal_id = sample_principal["principal_id"] + _auth(client, tenant_id) + media_buy_id = f"mb_{uuid.uuid4().hex[:8]}" + first_id = _make_step(tenant_id, principal_id, "approval", media_buy_id=media_buy_id) + second_id = _make_step(tenant_id, principal_id, "requires_approval", media_buy_id=media_buy_id) + + response = client.post( + f"/tenant/{tenant_id}/media-buy/{media_buy_id}/approve", + data={"action": "reject", "reason": "selected", "workflow_step_id": second_id}, + follow_redirects=False, + ) + + assert response.status_code in (302, 303) + assert _status(tenant_id, first_id) == "approval" + assert _status(tenant_id, second_id) == "rejected" + + def test_media_buy_detail_refuses_step_mapped_to_different_buy(self, client, sample_tenant, sample_principal): + """A hidden step id is only a selector: POST must re-authorize its URL object mapping.""" + tenant_id = sample_tenant["tenant_id"] + principal_id = sample_principal["principal_id"] + _auth(client, tenant_id) + requested_buy_id = f"mb_{uuid.uuid4().hex[:8]}" + other_buy_id = f"mb_{uuid.uuid4().hex[:8]}" + requested_step_id = _make_step(tenant_id, principal_id, "requires_approval", media_buy_id=requested_buy_id) + other_step_id = _make_step(tenant_id, principal_id, "requires_approval", media_buy_id=other_buy_id) + + with ( + patch("src.admin.blueprints.operations.WorkflowRepository.claim_approval") as mock_claim, + patch("src.core.tools.media_buy_create.execute_approved_media_buy") as mock_execute, + ): + response = client.post( + f"/tenant/{tenant_id}/media-buy/{requested_buy_id}/approve", + data={"action": "approve", "workflow_step_id": other_step_id}, + follow_redirects=False, + ) + + assert response.status_code in (302, 303) + mock_claim.assert_not_called() + mock_execute.assert_not_called() + assert _status(tenant_id, requested_step_id) == "requires_approval" + assert _status(tenant_id, other_step_id) == "requires_approval" + + +class TestWorkflowsRouteConflict: + """The generic workflow approve/reject JSON route distinguishes a genuine + concurrency conflict (409) from a missing step (404), and never double-executes.""" + + def test_approve_of_already_approved_step_returns_409(self, client, sample_tenant, sample_principal): + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + step_id = _make_step(tenant_id, sample_principal["principal_id"], "approved") + + with patch("src.core.tools.media_buy_create.execute_approved_media_buy") as mock_execute: + resp = client.post(f"/tenant/{tenant_id}/workflows/wf_x/steps/{step_id}/approve") + + assert resp.status_code == 409, "a second approve of an approved step is a conflict, not 404" + mock_execute.assert_not_called() + assert _status(tenant_id, step_id) == "approved" + + def test_approve_of_nonexistent_step_returns_404(self, client, sample_tenant): + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + resp = client.post(f"/tenant/{tenant_id}/workflows/wf_x/steps/step_missing/approve") + assert resp.status_code == 404 + + def test_mapped_buy_without_assignments_waits_for_creatives(self, client, factory_session): + """The generic workflow route shares the zero-assignment creative gate.""" + tenant_id, media_buy_id, step_id = _authed_media_buy_awaiting_approval( + client, + with_approved_creative=False, + ) + + with patch("src.core.tools.media_buy_create.execute_approved_media_buy") as mock_execute: + response = client.post(f"/tenant/{tenant_id}/workflows/wf_x/steps/{step_id}/approve") + + assert response.status_code == 200 + mock_execute.assert_not_called() + assert _status(tenant_id, step_id) == "approved" + with MediaBuyUoW(tenant_id) as uow: + assert uow.media_buys is not None + persisted = uow.media_buys.get_by_id(media_buy_id) + assert persisted is not None + assert persisted.status == "pending_creatives" + + def test_reject_of_approved_step_returns_409(self, client, sample_tenant, sample_principal): + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + step_id = _make_step(tenant_id, sample_principal["principal_id"], "approved") + + resp = client.post(f"/tenant/{tenant_id}/workflows/wf_x/steps/{step_id}/reject", json={"reason": "x"}) + + assert resp.status_code == 409, "rejecting an approved step is a conflict — no rejecting a live order" + assert _status(tenant_id, step_id) == "approved" + + def test_route_approves_legacy_approval_status_step(self, client, sample_tenant, sample_principal): + """The generic approve route actions a legacy ``approval``-status step (200), + not a spurious 409.""" + tenant_id = sample_tenant["tenant_id"] + _auth(client, tenant_id) + step_id = _make_step(tenant_id, sample_principal["principal_id"], "approval") + + resp = client.post(f"/tenant/{tenant_id}/workflows/wf_x/steps/{step_id}/approve") + + assert resp.status_code == 200, "a legacy approval-status step must be approvable, not 409" + assert _status(tenant_id, step_id) == "completed" + + +class TestMediaBuyDetailApprovalUI: + """The media-buy detail page must render controls for a legacy ``approval`` step. + + Repository and POST-route tests do not prove the GET page renders the + controls, so this separately guards the template-facing lookup. + """ + + def test_detail_page_renders_approval_controls_for_legacy_approval_step(self, client, factory_session): + tenant_id, media_buy_id, step_id = _authed_media_buy_awaiting_approval(client, "approval") + + resp = client.get(f"/tenant/{tenant_id}/media-buy/{media_buy_id}") + + assert resp.status_code == 200 + html = resp.get_data(as_text=True) + # The approval alert + approve/reject controls render ONLY inside {% if pending_approval_step %}. + assert "Manual Approval Required" in html, "detail page must show the approval alert for a legacy approval step" + assert "Approve" in html and "Reject" in html, "approve/reject controls must render" + # And the approve control posts to the media-buy approve route for THIS buy. + assert f"/media-buy/{media_buy_id}/approve" in html + assert f'name="workflow_step_id" value="{step_id}"' in html + + +class TestAtomicTransitionTenantScope: + """``_atomic_transition`` must not reach across tenants. + + Every conditional transition on this repository — ``transition_if_nonterminal``, + ``claim_approval``, ``complete_claimed_approval``, ``cancel_if_cancellable`` — funnels + through the one ``UPDATE workflow_steps`` in ``_atomic_transition``, so its + ``DBContext.tenant_id`` predicate is the single tenant boundary for all of them. + + That predicate had no oracle: deleting it reddened nothing across the suite. The + repository-pattern guard (``test_architecture_workflow_tenant_isolation``) matches + ``select(WorkflowStep)``, while this method scopes with ``select(WorkflowStep.step_id)`` + and writes with ``update(WorkflowStep)`` — different node shapes, so a static guard + that reads correct passes over it. Widening that matcher is separate work; this is the + behavioural oracle the boundary needs regardless of what any guard can see. + """ + + @staticmethod + def _step_in_its_own_tenant(suffix: str, status: str) -> tuple[str, str]: + from tests.factories import PrincipalFactory, TenantFactory + + tenant = TenantFactory(tenant_id=f"t_{suffix}", subdomain=f"sub-{suffix}") + principal = PrincipalFactory(tenant=tenant, principal_id=f"p_{suffix}", access_token=f"tok_{suffix}") + return tenant.tenant_id, _make_step(tenant.tenant_id, principal.principal_id, status) + + def test_transition_does_not_cross_tenants(self, integration_db, factory_session): + """A repo scoped to tenant A cannot transition tenant B's step. + + Asserts on B's PERSISTED status, not merely on the returned value: ``_atomic_transition`` + ends with ``get_by_step_id``, which is itself tenant-scoped, so a cross-tenant UPDATE + that actually applied would STILL return None. A return-value-only assertion would pass + while the row was being mutated — the write is the thing to observe. + """ + suffix_a, suffix_b = uuid.uuid4().hex[:8], uuid.uuid4().hex[:8] + tenant_a, _step_a = self._step_in_its_own_tenant(suffix_a, "requires_approval") + tenant_b, step_b = self._step_in_its_own_tenant(suffix_b, "requires_approval") + + with WorkflowUoW(tenant_a) as uow: + assert uow.workflows is not None + result = uow.workflows.transition_if_nonterminal(step_b, status="completed") + + assert result is None, f"tenant {tenant_a} must not transition tenant {tenant_b}'s step" + assert _status(tenant_b, step_b) == "requires_approval", ( + "the cross-tenant UPDATE applied — _atomic_transition's DBContext.tenant_id " + "predicate is not scoping the write" + ) + + def test_transition_still_applies_within_the_owning_tenant(self, integration_db, factory_session): + """The scoping must not block the legitimate same-tenant transition. + + Without this, the isolation test above is satisfiable by a predicate that matches + nothing at all. + """ + suffix = uuid.uuid4().hex[:8] + tenant_id, step_id = self._step_in_its_own_tenant(suffix, "requires_approval") + + with WorkflowUoW(tenant_id) as uow: + assert uow.workflows is not None + result = uow.workflows.transition_if_nonterminal(step_id, status="completed") + + assert result is not None, "the owning tenant's transition must apply" + assert _status(tenant_id, step_id) == "completed" diff --git a/tests/integration/test_admin_media_buy_reject_webhook.py b/tests/integration/test_admin_media_buy_reject_webhook.py index 5bc0f0253b..9c3b2671df 100644 --- a/tests/integration/test_admin_media_buy_reject_webhook.py +++ b/tests/integration/test_admin_media_buy_reject_webhook.py @@ -48,6 +48,8 @@ def make_pending_media_buy(integration_db): from src.core.database.database_session import get_engine from tests.factories import ( ALL_FACTORIES, + CreativeAssignmentFactory, + CreativeFactory, MediaBuyFactory, MediaPackageFactory, PricingOptionFactory, @@ -57,11 +59,16 @@ def make_pending_media_buy(integration_db): PushNotificationConfigFactory, TenantFactory, ) + from tests.factories.creative_asset import build_assets, image_spec, url_spec engine = get_engine() session = SASession(bind=engine) - def _make(request_data_context: dict | None = None, protocol: str = "mcp"): + def _make( + request_data_context: dict | None = None, + protocol: str = "mcp", + external_task_id: str | None = None, + ): tenant = TenantFactory(tenant_id="reject_wh_tenant") PropertyTagFactory(tenant=tenant, tag_id="all_inventory", name="All Inventory") principal = PrincipalFactory( @@ -94,7 +101,7 @@ def _make(request_data_context: dict | None = None, protocol: str = "mcp"): ) # Persisted package row — the approve path's adapter execution reads the # buy's MediaPackage records ("No packages found" aborts before the webhook). - MediaPackageFactory( + media_package = MediaPackageFactory( media_buy=media_buy, package_id="pkg_reject_wh_1", package_config={ @@ -104,6 +111,28 @@ def _make(request_data_context: dict | None = None, protocol: str = "mcp"): "pricing_option_id": "cpm_usd_fixed", }, ) + approved_creative = CreativeFactory( + tenant=tenant, + principal=principal, + creative_id="creative_reject_wh_1", + # Approval performs real format resolution before firing the + # webhook. Use the catalog-backed image format rather than the + # CreativeFactory's legacy display_300x250 default, and populate + # the asset roles required by that catalog format. + format="display_300x250_image", + data={ + "assets": build_assets( + image_spec("banner_image"), + url_spec("click_url", url="https://buyer.example.com/landing"), + ) + }, + status="approved", + ) + CreativeAssignmentFactory( + creative=approved_creative, + media_buy=media_buy, + package_id=media_package.package_id, + ) PushNotificationConfigFactory( tenant=tenant, principal=principal, @@ -118,12 +147,14 @@ def _make(request_data_context: dict | None = None, protocol: str = "mcp"): } if request_data_context is not None: request_data["context"] = request_data_context + if external_task_id is not None: + request_data["external_task_id"] = external_task_id cm = ContextManager() context = cm.create_context( tenant_id=tenant.tenant_id, principal_id=principal.principal_id, ) - cm.create_workflow_step( + step = cm.create_workflow_step( context_id=context.context_id, step_type="approval", owner="publisher", @@ -142,6 +173,8 @@ def _make(request_data_context: dict | None = None, protocol: str = "mcp"): return { "tenant_id": tenant.tenant_id, "media_buy_id": media_buy.media_buy_id, + "workflow_step_id": step.step_id, + "external_task_id": external_task_id, } try: @@ -179,18 +212,25 @@ async def _capture(*, push_notification_config=None, payload=None, metadata=None mock_service = MagicMock() mock_service.send_notification = AsyncMock(side_effect=_capture) captured["service"] = mock_service - with patch( - "src.admin.blueprints.operations.get_protocol_webhook_service", - return_value=mock_service, + with ( + patch( + "src.admin.blueprints.operations.get_protocol_webhook_service", + return_value=mock_service, + ), + patch( + "src.core.utils.naming.generate_auto_name", + return_value="reject-wh.example.com", + ), ): yield captured def _post_approval_action(admin_session, ids: dict, data: dict): """Drive the real admin approve/reject route and assert the 302 redirect.""" + form_data = {"workflow_step_id": ids["workflow_step_id"], **data} resp = admin_session.post( f"/tenant/{ids['tenant_id']}/media-buy/{ids['media_buy_id']}/approve", - data=data, + data=form_data, ) assert resp.status_code == 302, f"expected redirect, got {resp.status_code}" @@ -383,6 +423,24 @@ def test_a2a_reject_webhook_carries_policy_violation_task( "A2A reject artifact embeds confirmed_at — the buy was rejected, not confirmed" ) + @pytest.mark.parametrize("action", ["approve", "reject"]) + def test_a2a_decision_webhook_uses_buyer_task_id( + self, + authenticated_admin_session, + make_pending_media_buy, + webhook_capture, + action, + ): + """Admin decisions correlate their webhook to the outer A2A task id.""" + buyer_task_id = f"task_buyer_{action}" + ids = make_pending_media_buy(protocol="a2a", external_task_id=buyer_task_id) + + _post_approval_action(authenticated_admin_session, ids, {"action": action, "reason": "test"}) + task = webhook_capture["payload"] + + assert task.id == buyer_task_id + assert task.id != ids["workflow_step_id"] + def test_approve_webhook_echoes_buyer_request_context( self, authenticated_admin_session, make_pending_media_buy, webhook_capture ): diff --git a/tests/integration/test_auth_suggestion_parity.py b/tests/integration/test_auth_suggestion_parity.py index 75400b46cb..209670faae 100644 --- a/tests/integration/test_auth_suggestion_parity.py +++ b/tests/integration/test_auth_suggestion_parity.py @@ -1,49 +1,40 @@ -"""Auth AUTH_REQUIRED raises must carry error.json's top-level suggestion (#1417 round-8 review, items 3-4). - -Core Invariant: every AUTH_REQUIRED rejection carries a non-empty TOP-LEVEL -``suggestion`` in the two-layer wire envelope (AdCP 3.1, pinned ref -v3.1-04f59d2d5, static/schemas/source/core/error.json — "Suggested action to -resolve the error"). ``require_identity`` already passes -``suggestion=AUTH_REQUIRED_SUGGESTION``; its four siblings in -``src/core/auth.py`` (invalid-token, ``resolve_principal_or_raise``, -``require_principal_id``, ``require_tenant``) raised with the hint only in -message text, leaving the graded top-level ``suggestion`` field EMPTY -(PR #1417 review round 8, item 4 → #1417 round-8 review item 4). +"""Authentication rejections must carry the pinned error-code suggestion on the wire. + +Core invariant: every authentication rejection carries the pinned top-level +``suggestion`` in the two-layer wire envelope. Every wire boundary uses the +``AUTH_MISSING``/``AUTH_INVALID`` split from the pinned AdCP 3.1.1 enum; direct +implementation helpers retain ``AUTH_REQUIRED`` where credential state is +unknowable. Wire-first per tests/CLAUDE.md § Error Verification Policy: the -``require_principal_id`` case drives the REAL A2A wire (it is the -account-resolution boundary the PR newly routes onto); the remaining helpers -are graded on the envelope the production boundary translator builds for -their raise (``build_two_layer_error_envelope`` — the same builder every -transport dispatcher calls). +missing-principal case drives the real A2A wire; the remaining helpers are +checked on the envelope the production boundary translator builds for their +raise (``build_two_layer_error_envelope`` — the same builder every transport +dispatcher calls). """ +from typing import Any + import pytest from src.core.exceptions import AdCPError, build_two_layer_error_envelope -from tests.helpers import assert_envelope_shape +from tests.helpers.auth_contract import assert_two_layer_auth_contract pytestmark = [pytest.mark.integration, pytest.mark.requires_db] -def _assert_auth_required_with_suggestion(envelope: dict) -> None: - from tests.harness.transport import extract_wire_suggestion - - assert_envelope_shape(envelope, "AUTH_REQUIRED", recovery="correctable") - suggestion = extract_wire_suggestion(envelope) - assert suggestion, ( - "Expected a non-empty TOP-LEVEL suggestion in the AUTH_REQUIRED wire " - f"envelope (error.json @v3.1-04f59d2d5), got: {envelope}" - ) +def _assert_legacy_impl_auth_with_suggestion(envelope: dict[str, Any]) -> None: + assert_two_layer_auth_contract(envelope, "impl", "missing") class TestRequirePrincipalIdA2ASuggestion: - """require_principal_id rejection on the real A2A wire carries a suggestion.""" + """A rejected A2A identity on the real wire carries the AUTH_INVALID suggestion.""" def test_missing_principal_a2a_envelope_carries_suggestion(self, integration_db): - """An identity with no principal_id rejected on the A2A wire must - produce the AUTH_REQUIRED envelope WITH a top-level ``suggestion`` — - parity with ``require_identity``. + """A resolved identity with no principal_id represents rejected credentials. + + The A2A wire must therefore carry AUTH_INVALID with terminal recovery + and the pinned no-retry suggestion. """ from tests.factories import PrincipalFactory, TenantFactory from tests.harness.media_buy_list import MediaBuyListEnv @@ -59,12 +50,70 @@ def test_missing_principal_a2a_envelope_carries_suggestion(self, integration_db) f"A missing principal_id must be rejected on the A2A wire, got success payload: {result.payload!r}" ) result.assert_wire_error( - "AUTH_REQUIRED", - recovery="correctable", + "AUTH_INVALID", + recovery="terminal", require_suggestion=True, ) +class TestRestAuthSuggestion: + """The real REST dependency path emits the pinned missing-auth suggestion.""" + + def test_missing_rest_credentials_emit_pinned_suggestion(self, integration_db): + from tests.factories import TenantFactory + from tests.harness.account_list import AccountListEnv + from tests.harness.transport import Transport + + with AccountListEnv(tenant_id="rest_auth_sugg", principal_id="rest_auth_principal") as env: + TenantFactory(tenant_id="rest_auth_sugg") + + result = env.call_via(Transport.REST, identity=None) + + assert result.is_error, f"Expected REST auth rejection, got payload: {result.payload!r}" + assert_two_layer_auth_contract(result.wire_error_envelope, "rest", "missing") + + +class TestRejectedCredentialWireBoundaries: + """Every wire transport resolves and rejects a token with no principal row.""" + + @pytest.mark.parametrize("transport", ["a2a", "mcp", "rest"]) + def test_rejected_token_runs_real_auth_chain(self, integration_db, transport): + from tests.factories import TenantFactory + from tests.harness.account_list import AccountListEnv + from tests.harness.transport import Transport + + wire_transport = Transport(transport) + tenant_id = f"rejected_token_{transport}" + with AccountListEnv(tenant_id=tenant_id, principal_id=f"principal_{transport}") as env: + TenantFactory(tenant_id=tenant_id) + result = env.call_via( + wire_transport, + presented_auth_token="expired-or-revoked-token", + ) + + assert result.is_error, f"Expected {transport} to reject a token with no principal row" + assert_two_layer_auth_contract(result.wire_error_envelope, wire_transport, "invalid") + + @pytest.mark.parametrize("transport", ["a2a", "mcp", "rest"]) + def test_rejected_legacy_token_is_missing_standard_authorization(self, integration_db, transport): + """A rejected legacy credential does not satisfy the v3.1.1 Authorization split.""" + from tests.factories import TenantFactory + from tests.harness.account_list import AccountListEnv + from tests.harness.transport import Transport + + wire_transport = Transport(transport) + tenant_id = f"rejected_legacy_token_{transport}" + with AccountListEnv(tenant_id=tenant_id, principal_id=f"principal_{transport}") as env: + TenantFactory(tenant_id=tenant_id) + result = env.call_via( + wire_transport, + presented_legacy_auth_token="expired-or-revoked-legacy-token", + ) + + assert result.is_error, f"Expected {transport} to reject a legacy token with no principal row" + assert_two_layer_auth_contract(result.wire_error_envelope, wire_transport, "missing") + + class TestAuthHelperFamilySuggestion: """The remaining AUTH_REQUIRED raise sites in src/core/auth.py carry a suggestion. @@ -85,7 +134,7 @@ def test_resolve_principal_not_found_carries_suggestion(self, integration_db): with pytest.raises(AdCPError) as exc_info: resolve_principal_or_raise("nonexistent-principal", tenant_id="auth_sugg_t1") - _assert_auth_required_with_suggestion(build_two_layer_error_envelope(exc_info.value)) + _assert_legacy_impl_auth_with_suggestion(build_two_layer_error_envelope(exc_info.value)) def test_require_tenant_missing_carries_suggestion(self): from src.core.auth import require_tenant @@ -96,7 +145,7 @@ def test_require_tenant_missing_carries_suggestion(self): with pytest.raises(AdCPError) as exc_info: require_tenant(identity) - _assert_auth_required_with_suggestion(build_two_layer_error_envelope(exc_info.value)) + _assert_legacy_impl_auth_with_suggestion(build_two_layer_error_envelope(exc_info.value)) def test_invalid_token_carries_suggestion(self, integration_db): """get_principal_from_context with an invalid token (require_valid_token=True) @@ -123,4 +172,4 @@ class _HeaderCarrier: with pytest.raises(AdCPError) as exc_info: get_principal_from_context(_HeaderCarrier()) - _assert_auth_required_with_suggestion(build_two_layer_error_envelope(exc_info.value)) + _assert_legacy_impl_auth_with_suggestion(build_two_layer_error_envelope(exc_info.value)) diff --git a/tests/integration/test_create_media_buy_behavioral.py b/tests/integration/test_create_media_buy_behavioral.py index 7dd41e2bda..3c48f02d21 100644 --- a/tests/integration/test_create_media_buy_behavioral.py +++ b/tests/integration/test_create_media_buy_behavioral.py @@ -53,6 +53,7 @@ AdCPCapabilityNotSupportedError, AdCPCreativeRejectedError, AdCPFormatNotFoundError, + AdCPInvalidRequestError, AdCPNotFoundError, AdCPProductNotFoundError, AdCPValidationError, @@ -1636,21 +1637,18 @@ async def test_unregistered_creative_agent_rejected(self): with patch("src.core.creative_agent_registry.CreativeAgentRegistry") as mock_registry_cls: mock_registry = MagicMock() - mock_registry._get_tenant_agents.return_value = [] # No agents registered + mock_registry.get_registered_agent_urls.return_value = frozenset() mock_registry_cls.return_value = mock_registry - with patch("src.core.validation.normalize_agent_url", side_effect=lambda x: x): - from src.core.exceptions import AdCPAuthorizationError - - with pytest.raises(AdCPAuthorizationError) as exc_info: - await _validate_and_convert_format_ids( - format_ids=[{"agent_url": "https://unknown-agent.example.com", "id": "banner_300x250"}], - tenant_id="test_tenant", - package_idx=0, - ) + with pytest.raises(AdCPInvalidRequestError) as exc_info: + await _validate_and_convert_format_ids( + format_ids=[{"agent_url": "https://unknown-agent.example.com", "id": "banner_300x250"}], + tenant_id="test_tenant", + package_idx=0, + ) - assert "not registered" in str(exc_info.value).lower() - assert exc_info.value.error_code == "AUTH_REQUIRED" + assert exc_info.value.message == "Creative agent is not registered." + assert exc_info.value.error_code == "INVALID_REQUEST" @pytest.mark.asyncio async def test_format_not_found_on_agent(self): @@ -1660,15 +1658,9 @@ async def test_format_not_found_on_agent(self): """ from src.core.tools.media_buy_create import _validate_and_convert_format_ids - mock_agent = MagicMock() - mock_agent.agent_url = "https://creative.example.com" - - with ( - patch("src.core.creative_agent_registry.CreativeAgentRegistry") as mock_registry_cls, - patch("src.core.validation.normalize_agent_url", side_effect=lambda x: x), - ): + with patch("src.core.creative_agent_registry.CreativeAgentRegistry") as mock_registry_cls: mock_registry = MagicMock() - mock_registry._get_tenant_agents.return_value = [mock_agent] + mock_registry.get_registered_agent_urls.return_value = frozenset({"https://creative.example.com"}) mock_registry.get_format = AsyncMock(return_value=None) # Format not found mock_registry_cls.return_value = mock_registry diff --git a/tests/integration/test_create_media_buy_callback_validation.py b/tests/integration/test_create_media_buy_callback_validation.py new file mode 100644 index 0000000000..7c4630e539 --- /dev/null +++ b/tests/integration/test_create_media_buy_callback_validation.py @@ -0,0 +1,111 @@ +"""Wire coverage for media-buy callback URL validation (create and update).""" + +from __future__ import annotations + +import uuid +from datetime import UTC, datetime, timedelta + +import pytest + +from src.core.schemas import CreateMediaBuyRequest +from tests.harness.media_buy_create import MediaBuyCreateEnv +from tests.harness.transport import Transport +from tests.helpers import assert_envelope_shape +from tests.helpers.secret_scrub import serialize_wire_error + +pytestmark = [pytest.mark.integration, pytest.mark.requires_db] + + +@pytest.mark.parametrize("transport", [Transport.MCP, Transport.REST]) +def test_private_callback_is_rejected_on_wire_before_workflow_writes(integration_db, transport): + """MCP and REST reject a private callback before creating durable workflow state. + + The A2A protocol-level configuration has its own earlier boundary and is + covered by ``test_message_send_rejects_private_push_notification_url_before_storage``. + """ + now = datetime.now(UTC) + request = CreateMediaBuyRequest( + brand={"domain": "callback-validation.example"}, + packages=[ + { + "product_id": "prod_1", + "budget": 5000.0, + "pricing_option_id": "cpm_usd_fixed", + } + ], + start_time=(now + timedelta(days=1)).isoformat(), + end_time=(now + timedelta(days=8)).isoformat(), + idempotency_key=f"callback-test-{uuid.uuid4().hex}", + ) + rejected_url = "https://127.0.0.1/internal-callback" + + with MediaBuyCreateEnv() as env: + env.setup_media_buy_data() + arguments = request.model_dump(mode="json", exclude_none=True) + arguments["push_notification_config"] = {"url": rejected_url} + + result = env.call_via(transport, **arguments) + + assert result.is_error + assert_envelope_shape( + result.wire_error_envelope, + "VALIDATION_ERROR", + recovery="correctable", + ) + for error in ( + result.wire_error_envelope["adcp_error"], + result.wire_error_envelope["errors"][0], + ): + assert error["message"] == "Push notification URL must resolve to a public HTTPS endpoint" + assert error["field"] == "push_notification_config.url" + assert rejected_url not in serialize_wire_error(result.wire_error_envelope) + env.mock["context_mgr"].assert_not_called() + + +@pytest.mark.parametrize("transport", [Transport.A2A, Transport.MCP, Transport.REST]) +def test_update_rejects_private_callback_on_wire(integration_db, transport): + """update_media_buy rejects a private callback with the same envelope create does. + + update previously accepted an unsafe callback, returned success, and silently + never delivered — a buyer could not tell that outcome apart from a webhook that + simply never fired. Removing the validation call from ``_update_media_buy_impl`` + reddens this test on every transport. + """ + from src.core.schemas import UpdateMediaBuyRequest + from tests.bdd.conftest import _setup_existing_media_buy + from tests.harness.media_buy_dual import MediaBuyDualEnv + + rejected_url = "https://127.0.0.1/internal-callback" + + with MediaBuyDualEnv() as env: + tenant, principal, product, _ = env.setup_media_buy_data() + ctx: dict = {} + _setup_existing_media_buy(ctx, env, tenant, principal, product) + media_buy_id = ctx["existing_media_buy"].media_buy_id + env._seeded_media_buy_id = media_buy_id + + result = env.call_via( + transport, + req=UpdateMediaBuyRequest( + media_buy_id=media_buy_id, + paused=True, + push_notification_config={"url": rejected_url}, + ), + ) + + assert result.is_error + assert result.wire_error_envelope is not None + assert_envelope_shape( + result.wire_error_envelope, + "VALIDATION_ERROR", + recovery="correctable", + ) + envelope = ( + result.wire_error_envelope.envelope + if hasattr(result.wire_error_envelope, "envelope") + else result.wire_error_envelope + ) + for error in (envelope["adcp_error"], envelope["errors"][0]): + assert error["message"] == "Push notification URL must resolve to a public HTTPS endpoint" + assert error["field"] == "push_notification_config.url" + assert rejected_url not in serialize_wire_error(envelope) diff --git a/tests/integration/test_creative_formats_validation_a.py b/tests/integration/test_creative_formats_validation_a.py index a3757d1076..2555efb30d 100644 --- a/tests/integration/test_creative_formats_validation_a.py +++ b/tests/integration/test_creative_formats_validation_a.py @@ -292,7 +292,7 @@ def test_malformed_format_ids_via_mcp_raises_adcp_error(self, integration_db): TenantFactory(tenant_id="test_tenant") result = env.call_via(Transport.MCP, format_ids=[{"id": "no_agent_url"}]) - assert_rejected(result, field="agent_url", reason="Field required") + assert_rejected(result, field="agent_url") def test_valid_format_ids_accepted(self, integration_db): """UC-005-EXT-B-02 (positive counterpart): well-formed FormatId objects are accepted. diff --git a/tests/integration/test_creative_formats_validation_b.py b/tests/integration/test_creative_formats_validation_b.py index c9144c5d06..522fb138bc 100644 --- a/tests/integration/test_creative_formats_validation_b.py +++ b/tests/integration/test_creative_formats_validation_b.py @@ -83,7 +83,7 @@ def test_dimension_type_mismatch_via_mcp_wrapper(self, integration_db): TenantFactory(tenant_id="test_tenant") env.set_registry_formats([]) result = env.call_via(Transport.MCP, max_width="not_a_number") - assert_rejected(result, field="max_width", reason="valid integer") + assert_rejected(result, field="max_width") def test_formatted_error_identifies_dimension_field(self, integration_db): """Covers: UC-005-EXT-B-03 — error message identifies the dimension field. @@ -232,5 +232,9 @@ def test_mcp_wrapper_multi_field_error_contains_field_details(self, integration_ max_width="not_a_number", min_height="also_invalid", ) - assert_rejected(result, field="max_width", reason="valid integer") - assert_rejected(result, field="min_height", reason="valid integer") + assert_rejected(result, field="max_width") + error = result.wire_error_envelope["errors"][0] + validation_errors = error["details"]["validation_errors"] + fields = {".".join(str(part) for part in item["loc"]) for item in validation_errors} + assert {"max_width", "min_height"} <= fields + assert all(item["msg"] for item in validation_errors) diff --git a/tests/integration/test_creative_sync_behavioral.py b/tests/integration/test_creative_sync_behavioral.py index f7ad801a70..94ce1a22b6 100644 --- a/tests/integration/test_creative_sync_behavioral.py +++ b/tests/integration/test_creative_sync_behavioral.py @@ -813,6 +813,58 @@ def test_assignment_persists_to_db(self, integration_db): ).all() assert len(assignments) == 1 + def test_cross_principal_package_reference_is_not_assignable(self, integration_db): + """A same-tenant buyer cannot attach its creative to another buyer's package.""" + from src.core.database.models import CreativeAssignment as DBAssignment + from tests.factories import CreativeFactory + + with CreativeSyncEnv() as env: + tenant = TenantFactory(tenant_id="test_tenant") + requester = PrincipalFactory(tenant=tenant, principal_id="test_principal") + other = PrincipalFactory(tenant=tenant, principal_id="other_principal") + CreativeFactory( + tenant=tenant, + principal=requester, + creative_id="c_requester", + format="display_300x250", + agent_url=DEFAULT_AGENT_URL, + ) + requester_buy = MediaBuyFactory(tenant=tenant, principal=requester) + requester_package = MediaPackageFactory(media_buy=requester_buy) + other_buy = MediaBuyFactory(tenant=tenant, principal=other) + other_package = MediaPackageFactory(media_buy=other_buy) + + response = env.call_impl( + creatives=[], + assignments={ + "c_requester": [ + requester_package.package_id, + other_package.package_id, + ] + }, + validation_mode="lenient", + ) + + entry = next(result for result in response.creatives if result.creative_id == "c_requester") + assert entry.assigned_to == [requester_package.package_id] + assert entry.assignment_errors == { + other_package.package_id: f"Package not found: {other_package.package_id}" + } + requester_rows = env.query( + DBAssignment, + tenant_id=tenant.tenant_id, + creative_id="c_requester", + package_id=requester_package.package_id, + ) + cross_principal_rows = env.query( + DBAssignment, + tenant_id=tenant.tenant_id, + creative_id="c_requester", + package_id=other_package.package_id, + ) + assert len(requester_rows) == 1 + assert cross_principal_rows == [] + def test_cross_principal_creative_reference_does_not_500_or_leak(self, integration_db): """A principal referencing ANOTHER principal's creative_id in assignments must get a clean response — not a raw FK IntegrityError 500 — no @@ -1304,8 +1356,8 @@ def test_unreachable_agent_fails_with_retry(self, integration_db): result.wire_error_envelope, "SERVICE_UNAVAILABLE", recovery="transient", - message_substr="unreachable", ) + assert "unreachable" not in str(result.wire_error_envelope).lower() def test_package_not_found_lenient_logs_error(self, integration_db): """Covers: UC-006-EXT-J-02 — lenient: missing package → assignment_errors.""" diff --git a/tests/integration/test_creative_sync_transport.py b/tests/integration/test_creative_sync_transport.py index 532fde8d76..f5b21a25e7 100644 --- a/tests/integration/test_creative_sync_transport.py +++ b/tests/integration/test_creative_sync_transport.py @@ -753,13 +753,19 @@ def test_unreachable_agent_fails_creative(self, integration_db, transport): ) assert result.is_error, f"[{transport.value}] transient agent failure must fail the request" - envelope = result.wire_error_envelope or result.synthesized_error_envelope + if transport is Transport.IMPL: + assert result.wire_error_envelope is None + envelope = result.synthesized_error_envelope + else: + assert result.synthesized_error_envelope is None + envelope = result.wire_error_envelope + assert envelope is not None, f"[{transport.value}] must capture a real serialized wire envelope" assert_envelope_shape( envelope, "SERVICE_UNAVAILABLE", recovery="transient", - message_substr="unreachable", ) + assert "unreachable" not in str(envelope).lower() # --------------------------------------------------------------------------- @@ -1040,7 +1046,7 @@ def test_no_format_action_failed(self, integration_db, transport): if result.is_error: # MCP: TypeAdapter rejected missing format_id — correct behavior - assert_rejected(result, field="format_id", reason="Field required") + assert_rejected(result, field="format_id") else: # impl/a2a/rest: _impl handled it, returned action=failed assert_envelope(result, transport) @@ -1098,7 +1104,7 @@ def test_no_preview_no_url_fails(self, integration_db, transport): # MCP: TypeAdapter rejects missing assets field — correct schema rejection from tests.harness.assertions import assert_rejected - assert_rejected(result, field="assets", reason="Field required") + assert_rejected(result, field="assets") else: # impl/a2a/rest: _impl handles it, returns action=failed assert_envelope(result, transport) diff --git a/tests/integration/test_format_conversion_approval.py b/tests/integration/test_format_conversion_approval.py index 7b1ff31f61..34b49594f2 100644 --- a/tests/integration/test_format_conversion_approval.py +++ b/tests/integration/test_format_conversion_approval.py @@ -340,7 +340,7 @@ def test_invalid_format_missing_agent_url( # Execute approval - should fail success, message = execute_approved_media_buy(media_buy_id, test_tenant) - assert not success, "Approval should fail with missing agent_url" + assert success is False, "Approval should fail with missing agent_url" assert "agent_url" in message.lower() assert "format validation failed" in message.lower() @@ -441,7 +441,7 @@ def test_invalid_format_empty_agent_url(self, test_tenant, test_principal, test_ # Execute approval - should fail success, message = execute_approved_media_buy(media_buy_id, test_tenant) - assert not success, "Approval should fail with empty agent_url" + assert success is False, "Approval should fail with empty agent_url" assert "agent_url" in message.lower() # Cleanup @@ -541,7 +541,7 @@ def test_invalid_agent_url_not_http(self, test_tenant, test_principal, test_curr # Execute approval - should fail success, message = execute_approved_media_buy(media_buy_id, test_tenant) - assert not success, "Approval should fail with non-HTTP URL" + assert success is False, "Approval should fail with non-HTTP URL" assert "agent_url" in message.lower() assert "http" in message.lower() @@ -644,7 +644,7 @@ def test_invalid_format_missing_format_id( # Execute approval - should fail success, message = execute_approved_media_buy(media_buy_id, test_tenant) - assert not success, "Approval should fail with missing format_id" + assert success is False, "Approval should fail with missing format_id" # Error message varies: "no valid formats" or "format validation failed" assert "format" in message.lower() or "id" in message.lower() @@ -845,7 +845,7 @@ def test_invalid_dict_missing_id(self, test_tenant, test_principal, test_currenc # Execute approval - should fail success, message = execute_approved_media_buy(media_buy_id, test_tenant) - assert not success, "Approval should fail with missing id/format_id" + assert success is False, "Approval should fail with missing id/format_id" assert "id" in message.lower() # Cleanup @@ -940,7 +940,7 @@ def test_empty_formats_list_fails(self, test_tenant, test_principal, test_curren # Execute approval - should fail success, message = execute_approved_media_buy(media_buy_id, test_tenant) - assert not success, "Approval should fail with empty formats" + assert success is False, "Approval should fail with empty formats" assert "no valid formats" in message.lower() # Cleanup @@ -1146,7 +1146,7 @@ def test_invalid_format_unknown_type(self, test_tenant, test_principal, test_cur # Execute approval - should fail success, message = execute_approved_media_buy(media_buy_id, test_tenant) - assert not success, "Approval should fail with unknown format type" + assert success is False, "Approval should fail with unknown format type" assert "unknown format type" in message.lower() or "format validation failed" in message.lower() # Cleanup diff --git a/tests/integration/test_list_accounts.py b/tests/integration/test_list_accounts.py index 1e740f5207..0e2e1b0837 100644 --- a/tests/integration/test_list_accounts.py +++ b/tests/integration/test_list_accounts.py @@ -3,7 +3,7 @@ Verifies agent-scoped account listing with real PostgreSQL. beads: salesagent-hl0 -Business rules: BR-RULE-054 (agent scoping), BR-RULE-055 (auth optional) +Business rules: BR-RULE-054 (agent scoping), BR-RULE-055 (auth required) """ import pytest diff --git a/tests/integration/test_list_creatives_auth.py b/tests/integration/test_list_creatives_auth.py index b994d2791b..7e67d359db 100644 --- a/tests/integration/test_list_creatives_auth.py +++ b/tests/integration/test_list_creatives_auth.py @@ -33,10 +33,10 @@ def test_bad_token_string_rejected(self, integration_db): tenant = TenantFactory(tenant_id="token_test_tenant") # Pass a fabricated bad token that doesn't match any principal in the DB headers = { - "x-adcp-auth": "bad-token-xyz-not-a-real-token", + "Authorization": "Bearer bad-token-xyz-not-a-real-token", "x-adcp-tenant": tenant.tenant_id, } - with pytest.raises(AdCPAuthenticationError, match="invalid"): + with pytest.raises(AdCPAuthenticationError, match="rejected"): resolve_identity(headers, require_valid_token=True) diff --git a/tests/integration/test_mcp_error_envelope.py b/tests/integration/test_mcp_error_envelope.py index 9a42dc072a..2ffcb788fa 100644 --- a/tests/integration/test_mcp_error_envelope.py +++ b/tests/integration/test_mcp_error_envelope.py @@ -31,6 +31,7 @@ from tests.factories.principal import PrincipalFactory from tests.helpers import assert_envelope_shape from tests.helpers.adcp_factories import create_test_package_request_dict +from tests.helpers.auth_contract import assert_two_layer_auth_contract from tests.helpers.mcp_envelope_capture import call_mcp_tool_capturing_envelope from tests.integration.conftest import seed_error_test_tenant @@ -193,21 +194,225 @@ def test_create_media_buy_validation_error_emits_envelope_on_wire(self, mcp_real assert is_error, "INVALID_REQUEST must produce a tool error" assert envelope is not None, "Error must include content text carrying the envelope" assert_envelope_shape(envelope, "INVALID_REQUEST", recovery="correctable") - msg_lower = envelope["adcp_error"]["message"].lower() - past_or_start_msg = f"Envelope message must explain the failure, got: {envelope['adcp_error']['message']}" - assert "past" in msg_lower or "start" in msg_lower, past_or_start_msg + for error in (envelope["adcp_error"], envelope["errors"][0]): + assert error["message"] == "Start time cannot be in the past." + assert error["field"] == "start_time" + assert error["suggestion"] == "Use a future datetime or 'asap' for immediate start." + + from tests.helpers.secret_scrub import serialize_wire_error + + serialized = serialize_wire_error(envelope) + assert "2020-01-01" not in serialized + assert "2020-02-01" not in serialized + + def test_duplicate_product_id_echoes_the_buyers_value_on_the_real_wire(self, mcp_real_tenant_setup): + """Production's _wire_safe_message=True opt-in (media_buy_create.py ~2537) actually + reaches the wire — not just the mechanism tested in isolation by + tests/unit/test_exception_normalization.py's mirrored-template tests. + + Drives REAL duplicate product_ids through the full pipeline, no ``_impl`` patching. + Removing the opt-in at that raise site would redden this test (the message would + fall back to the generic VALIDATION_ERROR scrub text and no longer contain + "Duplicate" or the product_id) — mutation-verified during this fix's development. + + Uses a credential-/URL-shaped product_id (duplicate-detection runs before any + catalog lookup — media_buy_create.py's duplicate check at ~2528 precedes the + AdCPProductNotFoundError check at ~2572, so this value never needs to resolve to a + real product) to show the echo carries a value of that SHAPE intact, rather than + only the tidy fixture id. + + What ``assert_no_secret_leak`` below does and does not prove: it is a regression + guard that no SERVER-side fragment (connection string, token, inline SQL — the + fixed set in tests/helpers/secret_scrub.py) joins this message. It is NOT made + stronger by the buyer value above, which deliberately contains none of those + fragments; it reads the same either way. The guard was shown to bite by mutation + during development — appending a fake connection string to the raise site's + f-string reddened it — not by anything this particular product_id contributes. + A sentinel cannot be threaded through this path instead: the buyer value is + expected to echo, so it cannot simultaneously serve as a must-be-absent marker. + """ + identity = mcp_real_tenant_setup + credential_shaped_product_id = "https://example.com/callback?token=buyer-rotated-secret-789" + + is_error, envelope = call_mcp_tool_capturing_envelope( + "create_media_buy", + { + "brand": {"domain": "wiretest.example"}, + "idempotency_key": f"int-key-{uuid.uuid4().hex}", + "packages": [ + create_test_package_request_dict( + product_id=credential_shaped_product_id, pricing_option_id="cpm_usd_fixed", budget=5000.0 + ), + create_test_package_request_dict( + product_id=credential_shaped_product_id, pricing_option_id="cpm_usd_fixed", budget=5000.0 + ), + ], + "start_time": (datetime.now(UTC) + timedelta(days=1)).isoformat(), + "end_time": (datetime.now(UTC) + timedelta(days=31)).isoformat(), + }, + identity, + ) + + assert is_error, "duplicate product_id must produce a tool error" + assert envelope is not None, "Error must include content text carrying the envelope" + assert_envelope_shape(envelope, "VALIDATION_ERROR", recovery="correctable") + for error in (envelope["adcp_error"], envelope["errors"][0]): + assert "Duplicate" in error["message"] + assert credential_shaped_product_id in error["message"] + + from tests.helpers.secret_scrub import assert_no_secret_leak + + assert_no_secret_leak(envelope) + + def test_managed_only_targeting_dimension_emits_envelope_on_wire(self, mcp_real_tenant_setup): + """Production's _wire_safe_message=True opt-in (media_buy_create.py ~2893) actually + reaches the wire for the targeting-overlay raise site. + + Drives a REAL managed-only dimension (key_value_pairs) through the full pipeline — + the same trigger tests/bdd/steps/generic/given_media_buy.py's + given_managed_targeting_dimension uses for the BDD scenario covering this raise + site. Removing the opt-in would redden this test the same way it reddens that + scenario (mutation-verified during this fix's development). + """ + identity = mcp_real_tenant_setup + + is_error, envelope = call_mcp_tool_capturing_envelope( + "create_media_buy", + { + "brand": {"domain": "wiretest.example"}, + "idempotency_key": f"int-key-{uuid.uuid4().hex}", + "packages": [ + create_test_package_request_dict( + product_id=_PRODUCT_ID, + pricing_option_id="cpm_usd_fixed", + budget=5000.0, + targeting_overlay={"key_value_pairs": {"section": "sports"}}, + ) + ], + "start_time": (datetime.now(UTC) + timedelta(days=1)).isoformat(), + "end_time": (datetime.now(UTC) + timedelta(days=31)).isoformat(), + }, + identity, + ) + + assert is_error, "managed-only targeting dimension must produce a tool error" + assert envelope is not None, "Error must include content text carrying the envelope" + assert_envelope_shape(envelope, "INVALID_REQUEST", recovery="correctable") + for error in (envelope["adcp_error"], envelope["errors"][0]): + assert "managed" in error["message"].lower() + + from tests.helpers.secret_scrub import assert_no_secret_leak + + assert_no_secret_leak(envelope) + + def test_typed_validation_failure_from_impl_emits_scrubbed_envelope_on_wire( + self, mcp_real_tenant_setup, monkeypatch + ): + """A TYPED failure escaping the create implementation keeps its envelope on the MCP wire. + + This is intentionally injected below request parsing and above the normal + tool boundary: it proves the middleware/tool translator, rather than a + particular business validator, preserves both error-envelope layers. + + The injected exception is typed on purpose — this grades that an ``AdCPValidationError`` + raise-site message is SCRUBBED off the wire, which nothing else covers. The untyped + crash path is a different branch with a different code, graded by its own sibling + below; the two cannot share one test because SERVICE_UNAVAILABLE has no canonical + sanitized presentation for ``assert_sanitized_wire_error`` to check. + """ + from src.core.exceptions import AdCPValidationError + + async def _raise_top_level_failure(*_args, **_kwargs): + raise AdCPValidationError("forced MCP top-level failure") + + monkeypatch.setattr("src.core.tools.media_buy_create._create_media_buy_impl", _raise_top_level_failure) + identity = mcp_real_tenant_setup + + is_error, envelope = call_mcp_tool_capturing_envelope( + "create_media_buy", + { + "brand": {"domain": "wiretest.example"}, + "idempotency_key": f"int-key-{uuid.uuid4().hex}", + "packages": [ + create_test_package_request_dict( + product_id=_PRODUCT_ID, + pricing_option_id="cpm_usd_fixed", + budget=5000.0, + ) + ], + "start_time": (datetime.now(UTC) + timedelta(days=1)).isoformat(), + "end_time": (datetime.now(UTC) + timedelta(days=31)).isoformat(), + }, + identity, + ) + + assert is_error, "top-level implementation failure must produce an MCP tool error" + assert envelope is not None, "MCP tool error must carry the two-layer envelope" + assert_envelope_shape( + envelope, + "VALIDATION_ERROR", + recovery="correctable", + ) + from tests.helpers.secret_scrub import assert_sanitized_wire_error + + assert_sanitized_wire_error( + envelope, + "VALIDATION_ERROR", + rejected_fragments=("forced MCP top-level failure",), + ) + + def test_untyped_impl_crash_emits_sanitized_envelope_on_wire(self, mcp_real_tenant_setup, monkeypatch): + """An UNTYPED crash in the implementation still reaches the buyer as an AdCP envelope. + + The typed sibling above travels a path that already carried an envelope before this + boundary existed. This one drives the fall-through arm — an exception the + normalization registry does not recognise — which is the branch that turns a real + crash into ``SERVICE_UNAVAILABLE``/``transient`` instead of a bare transport error. + + Distinct from the unit-level oracle in ``test_error_boundary_translation.py``: this + one runs through a real ``Client(mcp)`` call, so it also proves FastMCP does not + replace the message before the buyer sees it. + """ + + from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE, assert_no_secret_leak + + async def _raise_untyped_crash(*_args, **_kwargs): + raise RuntimeError(SECRET_BEARING_MESSAGE) + + monkeypatch.setattr("src.core.tools.media_buy_create._create_media_buy_impl", _raise_untyped_crash) + identity = mcp_real_tenant_setup + + is_error, envelope = call_mcp_tool_capturing_envelope( + "create_media_buy", + { + "brand": {"domain": "wiretest.example"}, + "idempotency_key": f"int-key-{uuid.uuid4().hex}", + "packages": [ + create_test_package_request_dict( + product_id=_PRODUCT_ID, + pricing_option_id="cpm_usd_fixed", + budget=5000.0, + ) + ], + "start_time": (datetime.now(UTC) + timedelta(days=1)).isoformat(), + "end_time": (datetime.now(UTC) + timedelta(days=31)).isoformat(), + }, + identity, + ) + + assert is_error, "untyped implementation crash must produce an MCP tool error" + assert envelope is not None, "MCP tool error must carry the two-layer envelope" + assert_envelope_shape(envelope, "SERVICE_UNAVAILABLE", recovery="transient") + assert_no_secret_leak(envelope, context="MCP untyped crash wire envelope") def test_get_media_buy_delivery_missing_identity_emits_auth_envelope_on_wire(self, integration_db): - """Missing identity in get_media_buy_delivery surfaces AUTH_REQUIRED on the MCP wire. + """Missing identity in get_media_buy_delivery surfaces AUTH_MISSING on the MCP wire. Flow: Client(mcp).call_tool("get_media_buy_delivery", {...}) with identity=None - → MCP wrapper resolve_identity returns None - → _get_media_buy_delivery_impl raises AdCPAuthRequiredError("Authentication required...") - → AdCPAuthRequiredError carries error_code="AUTH_REQUIRED" (passthrough STANDARD code) - → with_error_logging → _translate_to_tool_error → wire envelope - - AUTH_REQUIRED is a STANDARD spec code — passes through unchanged. + → middleware classifies absent transport credentials + → AdCPAuthMissingError carries error_code="AUTH_MISSING" + → _translate_to_tool_error emits the two-layer wire envelope """ is_error, envelope = call_mcp_tool_capturing_envelope( "get_media_buy_delivery", @@ -218,9 +423,8 @@ def test_get_media_buy_delivery_missing_identity_emits_auth_envelope_on_wire(sel assert is_error, "Missing identity must produce a tool error" assert envelope is not None, "Error must include content text carrying the envelope" - # AdCPAuthRequiredError -> AUTH_REQUIRED (AdCP 3.1 spec code, passed through unchanged). - # Recovery is correctable per the pinned error-code enum (#1417). - assert_envelope_shape(envelope, "AUTH_REQUIRED", recovery="correctable") + # AdCPAuthMissingError -> AUTH_MISSING with correctable recovery (#1417). + assert_two_layer_auth_contract(envelope, "mcp", "missing") assert "identity" in envelope["adcp_error"]["message"].lower() or ( "auth" in envelope["adcp_error"]["message"].lower() ), f"Envelope message must mention identity/auth, got: {envelope['adcp_error']['message']}" diff --git a/tests/integration/test_mcp_typeadapter_validation_envelope.py b/tests/integration/test_mcp_typeadapter_validation_envelope.py index 5cc0b106cc..e6f566d73a 100644 --- a/tests/integration/test_mcp_typeadapter_validation_envelope.py +++ b/tests/integration/test_mcp_typeadapter_validation_envelope.py @@ -29,9 +29,10 @@ def test_typeadapter_validation_error_emits_adcp_envelope_on_mcp_wire(): assert is_error, f"{tool_name}: invalid typed params must produce a tool error" assert envelope is not None, f"{tool_name}: no MCP wire error envelope captured" - assert_envelope_shape(envelope, "VALIDATION_ERROR", recovery="correctable", message_substr="List should have") + assert_envelope_shape(envelope, "VALIDATION_ERROR", recovery="correctable") assert envelope["errors"][0].get("suggestion"), f"{tool_name}: envelope must include a recovery suggestion" assert envelope["errors"][0].get("field") == "filters.concept_ids" + assert "List should have" not in envelope["errors"][0]["message"] assert_no_raw_validation_leak(envelope["errors"][0]["message"]) diff --git a/tests/integration/test_mcp_unknown_field_handling.py b/tests/integration/test_mcp_unknown_field_handling.py index 30bcf43f3e..9835f44bc2 100644 --- a/tests/integration/test_mcp_unknown_field_handling.py +++ b/tests/integration/test_mcp_unknown_field_handling.py @@ -53,9 +53,9 @@ def test_unknown_field_rejected(self, integration_db): result.wire_error_envelope, "VALIDATION_ERROR", recovery="correctable", - message_substr="Unexpected keyword argument", ) - assert result.wire_error_envelope["errors"][0]["field"] == "nonsense_field" + assert result.wire_error_envelope["errors"][0]["field"] == "unrecognized_field" + assert "Unexpected keyword argument" not in result.wire_error_envelope["errors"][0]["message"] def test_deprecated_field_translated_even_in_dev(self, integration_db): """Deprecated field translation works in dev mode (always active).""" diff --git a/tests/integration/test_media_buy_v3.py b/tests/integration/test_media_buy_v3.py index f993f1afed..c4739546c7 100644 --- a/tests/integration/test_media_buy_v3.py +++ b/tests/integration/test_media_buy_v3.py @@ -319,6 +319,48 @@ async def test_manual_approval_stores_raw_request(self, mb_tenant_with_approval, assert mb is not None, "Media buy record should exist in DB" assert mb.raw_request is not None, "raw_request should be stored" + @pytest.mark.asyncio + async def test_a2a_external_task_id_forwarded_to_persisted_step( + self, mb_tenant_with_approval, mb_principal, mb_products + ): + """The A2A raw wrapper must FORWARD its outer ``external_task_id`` all the way into the + persisted workflow step's ``request_metadata`` — this is what lets ``tasks/get`` correlate + a durable poll to the id the buyer holds. Drives the real ``create_media_buy_raw`` (not the + hand-written metadata the durable-lookup tests use), so deleting the wrapper's forwarding + reddens this test as well as the boundary guard.""" + from src.core.tools.media_buy_create import create_media_buy_raw + + identity = _make_identity( + principal_id=mb_principal["principal_id"], + tenant_id=mb_tenant_with_approval["tenant_id"], + tenant=mb_tenant_with_approval, + ) + outer_task_id = f"task_{uuid.uuid4().hex[:12]}" + + result = await create_media_buy_raw( + brand={"domain": "testbrand.com"}, + packages=[{"product_id": "guaranteed_display", "budget": 4000.0, "pricing_option_id": "cpm_usd_fixed"}], + start_time=datetime.now(UTC) + timedelta(days=1), + end_time=datetime.now(UTC) + timedelta(days=8), + idempotency_key=f"int-key-{uuid.uuid4().hex}", + identity=identity, + external_task_id=outer_task_id, + ) + assert result.status == "submitted" + + # The submitted response's task_id IS the persisted workflow step id — read it back + # through the repository (no raw session), and assert the outer task id was forwarded. + # request_metadata is merged into request_data at the persistence boundary. + from src.core.database.repositories import WorkflowUoW + + with WorkflowUoW(mb_tenant_with_approval["tenant_id"]) as uow: + step = uow.workflows.get_by_step_id(result.response.task_id) + assert step is not None, "manual-approval create must persist a workflow step" + forwarded = (step.request_data or {}).get("external_task_id") + assert forwarded == outer_task_id, ( + "the A2A outer task id must be forwarded into the persisted step's request_data" + ) + @pytest.mark.asyncio async def test_execute_approved_calls_adapter(self, mb_tenant_with_approval, mb_principal, mb_products): """UC-002-MA03: approved buy triggers adapter creation. @@ -439,8 +481,14 @@ async def test_adapter_failure_no_db_changes(self, mb_tenant, mb_principal, mb_p with patch("src.core.tools.media_buy_create._execute_adapter_media_buy_creation") as mock_adapter_call: mock_adapter_call.side_effect = RuntimeError("Simulated adapter failure") - with pytest.raises(AdCPAdapterError, match="Simulated adapter failure"): + # The client-facing message is sanitized — the raw adapter exception text + # ("Simulated adapter failure") is logged server-side only, not interpolated + # into the AdCPAdapterError message. The original + # RuntimeError is still chained via __cause__ for server-side traceability. + with pytest.raises(AdCPAdapterError, match="Failed to create media buy") as exc_info: await _create_media_buy_impl(req=req, identity=mb_identity) + assert "Simulated adapter failure" not in str(exc_info.value) + assert isinstance(exc_info.value.__cause__, RuntimeError) # Verify NO media buy record persisted (workflow step may exist, that's OK) with get_db_session() as session: diff --git a/tests/integration/test_request_validation_suggestion_parity.py b/tests/integration/test_request_validation_suggestion_parity.py index 6a603f0be7..b7d862eb45 100644 --- a/tests/integration/test_request_validation_suggestion_parity.py +++ b/tests/integration/test_request_validation_suggestion_parity.py @@ -36,6 +36,104 @@ INVALID_ASSET_TYPES = ["not_an_asset_type"] # rejected by ListCreativeFormatsRequest +@pytest.mark.requires_db +class TestValidationSecretScrubTransportParity: + """Boundary-wrapped Pydantic errors are safe on every buyer wire.""" + + @pytest.mark.parametrize("transport", ["a2a", "mcp", "rest"]) + def test_extra_field_value_is_never_echoed(self, integration_db, transport): + from tests.factories import TenantFactory + from tests.harness import CreativeFormatsEnv + from tests.harness.transport import Transport + from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE, assert_no_secret_leak + + wire_transport = Transport(transport) + tenant_id = f"validation_scrub_{transport}" + with CreativeFormatsEnv(tenant_id=tenant_id, principal_id=f"principal_{transport}") as env: + TenantFactory(tenant_id=tenant_id) + result = env.call_via( + wire_transport, + **{SECRET_BEARING_MESSAGE: SECRET_BEARING_MESSAGE}, + ) + + assert result.is_error, f"Expected {transport} to reject the extra field" + # REST rejects the unknown top-level body member in FastAPI before the + # route-level request model; AdCP classifies that structural failure as + # INVALID_REQUEST. A2A/MCP reach the shared strict request model and + # classify the value as VALIDATION_ERROR. + expected_code = "INVALID_REQUEST" if transport == "rest" else "VALIDATION_ERROR" + result.assert_wire_error( + expected_code, + recovery="correctable", + require_suggestion=True, + ) + assert_no_secret_leak(result.wire_error_envelope) + error = result.wire_error_envelope["errors"][0] + assert error["field"] == "unrecognized_field" + validation_errors = error["details"]["validation_errors"] + assert validation_errors == [ + { + "loc": ["unrecognized_field"], + "msg": "Extra field is not allowed by the AdCP request schema.", + "type": "unexpected_keyword_argument" if transport == "mcp" else "extra_forbidden", + } + ] + + @pytest.mark.parametrize("transport", ["a2a", "mcp", "rest"]) + def test_mapping_key_is_never_echoed(self, integration_db, transport): + from src.core.product_conversion import convert_pricing_option_to_adcp + from tests.harness.media_buy_create import MediaBuyCreateEnv + from tests.harness.transport import Transport + from tests.helpers.secret_scrub import assert_no_secret_leak + + identifier_secret = "hunter2" + with MediaBuyCreateEnv() as env: + _tenant, _principal, product, pricing = env.setup_media_buy_data() + pricing_option_id = convert_pricing_option_to_adcp(pricing).pricing_option_id + result = env.call_via( + Transport(transport), + brand={"domain": "acme.example"}, + packages=[ + { + "product_id": product.product_id, + "budget": 5000.0, + "pricing_option_id": pricing_option_id, + "targeting_overlay": { + "key_value_pairs": { + identifier_secret: {"invalid": "value"}, + } + }, + } + ], + start_time="asap", + end_time="2099-12-31T23:59:59Z", + idempotency_key=f"mapping-key-scrub-{transport}", + ) + + assert result.is_error + result.assert_wire_error("VALIDATION_ERROR", recovery="correctable") + assert_no_secret_leak(result.wire_error_envelope) + assert identifier_secret not in str(result.wire_error_envelope) + assert "nested_field" in result.wire_error_envelope["errors"][0]["field"] + + @pytest.mark.parametrize("transport", ["a2a", "mcp", "rest"]) + def test_typed_validation_message_is_never_trusted(self, integration_db, transport): + from tests.harness.creative_list import CreativeListEnv + from tests.harness.transport import Transport + from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE, assert_no_secret_leak + + with CreativeListEnv() as env: + result = env.call_via( + Transport(transport), + created_after=SECRET_BEARING_MESSAGE, + ) + + assert result.is_error + result.assert_wire_error("VALIDATION_ERROR", recovery="correctable") + assert_no_secret_leak(result.wire_error_envelope) + assert result.wire_error_envelope["errors"][0]["field"] == "created_after" + + @pytest.mark.requires_db class TestGetMediaBuyDeliveryRestSuggestionParity: """REST get_media_buy_delivery request-validation must carry a top-level suggestion.""" @@ -228,9 +326,9 @@ def test_invalid_asset_types_a2a_envelope_carries_suggestion(self, integration_d produce the AdCP two-layer VALIDATION_ERROR envelope WITH a top-level ``suggestion`` — parity with ``/api/v1/creative-formats``. - Pins that ``_handle_list_creative_formats_skill`` calls - ``build_list_creative_formats_request`` inside the boundary; a bare - call drops the suggestion. + Pins that ``_handle_list_creative_formats_skill`` validates the complete + ``ListCreativeFormatsRequest`` inside ``adcp_validation_boundary``; a + bare model-validation call drops the canonical suggestion. """ from tests.harness import CreativeFormatsEnv from tests.harness.transport import Transport @@ -347,6 +445,23 @@ def test_invalid_reporting_webhook_rest_envelope_carries_suggestion(self, integr "Expected a non-empty TOP-LEVEL suggestion in the VALIDATION_ERROR " f"wire envelope (error.json @v3.1-04f59d2d5), got: {envelope}" ) + # Suggestion PRESENCE cannot prove the pre-validation ran. AdCPValidationError + # carries a class-level ``_default_suggestion`` (the canonical enumMetadata + # text), so every VALIDATION_ERROR has one whether the boundary ran or not — + # this assertion alone stayed green with the boundary removed. Pin what ONLY + # full-request pre-validation produces: the schema field path, and the + # structured message naming each missing sub-field. + wire_error = envelope["errors"][0] + assert wire_error.get("field"), ( + f"the boundary attaches the failing schema path; without it the envelope carries no field: {envelope}" + ) + assert "do not match the AdCP specification" in wire_error["message"], ( + f"expected the boundary's structured multi-field validation message, got {wire_error['message']!r}" + ) + assert "reporting_frequency" in wire_error["message"], ( + "the message must name the missing sub-fields — the enumeration is what a " + f"boundary-less coercion cannot produce: {wire_error['message']!r}" + ) @pytest.mark.requires_db @@ -392,6 +507,24 @@ def test_invalid_reporting_webhook_a2a_envelope_carries_suggestion(self, integra recovery="correctable", require_suggestion=True, ) + # Suggestion PRESENCE cannot prove the pre-validation ran. AdCPValidationError + # carries a class-level ``_default_suggestion`` (the canonical enumMetadata + # text), so every VALIDATION_ERROR has one whether the boundary ran or not — + # this assertion alone stayed green with the boundary removed. Pin what ONLY + # full-request pre-validation produces: the schema field path, and the + # structured message naming each missing sub-field. + envelope = result.wire_error_envelope + wire_error = envelope["errors"][0] + assert wire_error.get("field"), ( + f"the boundary attaches the failing schema path; without it the envelope carries no field: {envelope}" + ) + assert "do not match the AdCP specification" in wire_error["message"], ( + f"expected the boundary's structured multi-field validation message, got {wire_error['message']!r}" + ) + assert "reporting_frequency" in wire_error["message"], ( + "the message must name the missing sub-fields — the enumeration is what a " + f"boundary-less coercion cannot produce: {wire_error['message']!r}" + ) @pytest.mark.requires_db diff --git a/tests/integration/test_rest_error_envelope.py b/tests/integration/test_rest_error_envelope.py index b121987385..07a8ffea44 100644 --- a/tests/integration/test_rest_error_envelope.py +++ b/tests/integration/test_rest_error_envelope.py @@ -13,6 +13,7 @@ import pytest from tests.harness.transport import Transport +from tests.helpers import assert_envelope_shape pytestmark = [pytest.mark.integration, pytest.mark.requires_db] @@ -82,3 +83,37 @@ def test_rest_reconstructed_error_has_suggestion(self, env_with_data): assert result.error.suggestion == wire_suggestion, ( f"result.error.suggestion '{result.error.suggestion}' != wire suggestion '{wire_suggestion}'" ) + + def test_rest_typed_validation_failure_emits_scrubbed_envelope(self, env_with_data, monkeypatch): + """A TYPED failure from the REST route's raw implementation reaches the global envelope handler. + + Typed on purpose: this grades that an ``AdCPValidationError`` raise-site message is + SCRUBBED off the wire. An ``AdCPError`` is caught by the typed handler, never the + untyped catch-all — that arm is graded by + ``test_untyped_impl_failure_returns_sanitized_two_layer_envelope`` in + ``tests/unit/test_error_boundary_translation.py``, which injects a real crash. + """ + from src.core.exceptions import AdCPValidationError + + async def _raise_top_level_failure(*_args, **_kwargs): + raise AdCPValidationError("forced REST top-level failure") + + monkeypatch.setattr("src.routes.api_v1.media_buy_create_module.create_media_buy_raw", _raise_top_level_failure) + request = self._zero_budget_req() + request.packages[0].budget = 5000.0 + + result = env_with_data.call_via(Transport.REST, req=request) + + assert result.is_error, f"Expected error, got payload: {result.payload}" + assert_envelope_shape( + result.wire_error_envelope, + "VALIDATION_ERROR", + recovery="correctable", + ) + from tests.helpers.secret_scrub import assert_sanitized_wire_error + + assert_sanitized_wire_error( + result.wire_error_envelope, + "VALIDATION_ERROR", + rejected_fragments=("forced REST top-level failure",), + ) diff --git a/tests/integration/test_uc003_mcp_update_error_capture.py b/tests/integration/test_uc003_mcp_update_error_capture.py index ab6349732a..ef43c8af2e 100644 --- a/tests/integration/test_uc003_mcp_update_error_capture.py +++ b/tests/integration/test_uc003_mcp_update_error_capture.py @@ -153,10 +153,31 @@ def test_empty_update_surfaces_wire_error_envelope(self, env_with_media_buy, tra result.wire_error_envelope, "INVALID_REQUEST", recovery="correctable", - message_substr="at least one updatable field", ) + from tests.helpers.secret_scrub import assert_no_secret_leak + + # Bare static literal → opts in to the wire (nothing interpolated, nothing to + # leak). Asserting the SCRUB here pinned the diagnostic downgrade the opt-in + # sweep removed: an INVALID_REQUEST is recovery=correctable, so the buyer is + # expected to self-correct — "review the submitted fields and resubmit" does + # not tell them WHICH field to add. + envelope = result.wire_error_envelope + env_dict = envelope.envelope if hasattr(envelope, "envelope") else envelope + for label, error in (("adcp_error", env_dict["adcp_error"]), ("errors[0]", env_dict["errors"][0])): + assert "at least one updatable field" in error["message"], ( + f"{transport}: {label} must carry the actionable empty-update text, got {error['message']!r}" + ) + assert_no_secret_leak(env_dict) + + # The graded property is PLACEMENT: a buyer-facing hint at the SPEC top level + # (error.json), never buried in details. This previously pinned the literal + # "check request parameters and fix" — INVALID_REQUEST's generic enum text — + # which is what the scrub substituted. With the opt-in, the raise site's own + # strictly-more-actionable hint survives (it names the acceptable fields), so + # assert that instead. The enum constants themselves stay pinned to the spec by + # test_architecture_error_suggestion_enum_conformance.py; that guard constrains + # the module-level constants, not what an individual raise site may supply. suggestion = self._top_level_suggestion(result.wire_error_envelope) - assert suggestion and "at least one updatable field" in suggestion.lower(), ( - f"{transport}: empty-update rejection must carry a non-empty TOP-LEVEL " - f"'suggestion' (error.json) naming the updatable fields, got {suggestion!r}" + assert suggestion and "at least one updatable field" in suggestion, ( + f"{transport}: empty-update rejection must carry its actionable TOP-LEVEL suggestion, got {suggestion!r}" ) diff --git a/tests/unit/_architecture_helpers.py b/tests/unit/_architecture_helpers.py index 73a287d41c..e52408a522 100644 --- a/tests/unit/_architecture_helpers.py +++ b/tests/unit/_architecture_helpers.py @@ -187,6 +187,12 @@ def select_call_model_name(call: ast.Call) -> str | None: Matches only bare-name ``select(...)`` calls (not attribute access) and resolves the first argument whether written as ``Model`` or ``mod.Model``. + + NOTE: this resolves the leading attribute name, so a COLUMN-select + ``select(Model.column)`` resolves to ``"column"`` (the attr), not the model — + i.e. column-selects of ORM models are invisible to callers that match the + result against ORM model names. Use ``select_target_model_name`` when + column-selects of ORM models must also be detected. """ if not (isinstance(call.func, ast.Name) and call.func.id == "select") or not call.args: return None @@ -198,6 +204,31 @@ def select_call_model_name(call: ast.Call) -> str | None: return None +def select_target_model_name(call: ast.Call, model_names: set[str]) -> str | None: + """ORM model targeted by ``select(...)`` — including ``select(Model.column)``. + + Closes the blind spot in ``select_call_model_name``: a column-select of an ORM + model (``select(Model.tenant_id)``) is a raw model query just as much as + ``select(Model)`` is, but the bare resolver returns the column name and misses + it. This resolver disambiguates against ``model_names``: + * ``select(Model)`` → ``Model`` (if a model); + * ``select(pkg.Model)`` → ``Model`` (attr is the model); + * ``select(Model.column)`` → ``Model`` (value is the model — a column-select). + Returns the model name when the select targets an ORM model, else None. + """ + if not (isinstance(call.func, ast.Name) and call.func.id == "select") or not call.args: + return None + arg = call.args[0] + if isinstance(arg, ast.Name): + return arg.id if arg.id in model_names else None + if isinstance(arg, ast.Attribute): + if arg.attr in model_names: # select(pkg.Model) + return arg.attr + if isinstance(arg.value, ast.Name) and arg.value.id in model_names: # select(Model.column) + return arg.value.id + return None + + def extract_select_calls( source_path: Path, func_name: str, diff --git a/tests/unit/test_a2a_create_media_buy_push_config_validation.py b/tests/unit/test_a2a_create_media_buy_push_config_validation.py index f91852dbcb..46d200b01e 100644 --- a/tests/unit/test_a2a_create_media_buy_push_config_validation.py +++ b/tests/unit/test_a2a_create_media_buy_push_config_validation.py @@ -53,15 +53,10 @@ async def test_short_webhook_credentials_do_not_block_create_media_buy(): manual-approval (submitted) path is never reached. """ from src.a2a_server.adcp_a2a_server import AdCPRequestHandler - from tests.factories.principal import PrincipalFactory + from tests.utils.a2a_helpers import make_test_a2a_identity handler = AdCPRequestHandler() - identity = PrincipalFactory.make_identity( - principal_id="test-principal", - tenant_id="test-tenant", - tenant={"tenant_id": "test-tenant"}, - protocol="a2a", - ) + identity = make_test_a2a_identity() params = _valid_packages_params() # Transport-layer push notification config (as injected by @@ -122,15 +117,10 @@ async def test_no_auth_push_config_still_works(): """Control: a no-auth push_notification_config must keep working (the bug only manifests when the authentication block forces the MinLen(32) check).""" from src.a2a_server.adcp_a2a_server import AdCPRequestHandler - from tests.factories.principal import PrincipalFactory + from tests.utils.a2a_helpers import make_test_a2a_identity handler = AdCPRequestHandler() - identity = PrincipalFactory.make_identity( - principal_id="test-principal", - tenant_id="test-tenant", - tenant={"tenant_id": "test-tenant"}, - protocol="a2a", - ) + identity = make_test_a2a_identity() params = _valid_packages_params() params["push_notification_config"] = {"url": "http://localhost:9999/webhook"} diff --git a/tests/unit/test_a2a_error_routing.py b/tests/unit/test_a2a_error_routing.py new file mode 100644 index 0000000000..5160ec786a --- /dev/null +++ b/tests/unit/test_a2a_error_routing.py @@ -0,0 +1,1172 @@ +"""A2A error routing: application failures ride in failed Tasks, not JSON-RPC. + +Compliance finding F7. Per AdCP 3.1.x transport rules (spec prose: +building/operating/transport-errors.mdx "Layer Separation" and the two-layer +error-handling model), application/task-execution failures must be RETURNED in +the task response body as a failed Task carrying the two-layer AdCP error +envelope artifact. JSON-RPC errors (``A2AError``) are reserved for genuine +transport faults — malformed requests, missing auth, and unknown JSON-RPC +*methods*. Unknown or unimplemented *skills* are application-layer failures +(the ``message/send`` method is valid; routing failed inside skill dispatch), +so they return a failed Task with ``UNSUPPORTED_FEATURE`` — see the dispatch- +registry wire assertions in ``test_a2a_transport_contract.py``. + +Pre-fix bug: ``on_message_send``'s outer exception handler built the correct +failed Task with the ``processing_error`` envelope artifact, then threw it +away by raising ``InternalError`` (a JSON-RPC error) instead of returning the +Task. These tests pin the returned-failed-Task contract on the wire artifact. +""" + +import json +from datetime import UTC, datetime +from types import SimpleNamespace +from unittest.mock import AsyncMock, MagicMock, patch + +import pytest +from a2a.server.request_handlers.response_helpers import build_error_response +from a2a.types import ( + Artifact, + CancelTaskRequest, + GetTaskRequest, + InternalError, + InvalidParamsError, + InvalidRequestError, + Part, + SendMessageConfiguration, + SendMessageRequest, + Task, + TaskPushNotificationConfig, + TaskState, + TaskStatus, +) + +from src.a2a_server.adcp_a2a_server import AdCPRequestHandler, _dict_to_value +from src.core.exceptions import ( + AUTH_REQUIRED_CANONICAL_SUGGESTION, + VALIDATION_ERROR_SUGGESTION, + AdCPAuthenticationError, + AdCPAuthInvalidError, + AdCPError, + AdCPValidationError, +) +from src.core.tool_context import ToolContext +from tests.a2a_helpers import make_a2a_context +from tests.factories import PrincipalFactory +from tests.helpers import assert_envelope_shape +from tests.helpers.pinned_schema import pinned_error_code_suggestion +from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE, assert_no_secret_leak, serialize_wire_error +from tests.utils.a2a_helpers import ( + assert_failed_task_envelope, + assert_failed_task_no_secret_leak, + create_a2a_message_with_skill, + extract_processing_error_envelope, + make_nl_send_message_request, + make_test_a2a_identity, +) + +_TEST_IDENTITY = make_test_a2a_identity() + + +def _capture_a2a_auth_records(): + """Return a semantic recorder spy for pre-identity A2A auth failures.""" + records = [] + + def _record(transport, operation, error, *, tenant_id=None, principal_id=None): + records.append((transport, operation, error.error_code, tenant_id, principal_id)) + + return records, _record + + +def _make_handler() -> tuple[AdCPRequestHandler, object]: + """Handler + authenticated call context for driving on_message_send.""" + handler = AdCPRequestHandler() + handler._get_auth_token = MagicMock(return_value="test-token") + ctx = make_a2a_context(auth_token="test-token", headers={"host": "test.example.com"}) + return handler, ctx + + +@pytest.mark.asyncio +async def test_message_send_rejects_private_push_notification_url_before_storage(): + """A message-scoped callback cannot target seller-internal services.""" + handler, ctx = _make_handler() + params = SendMessageRequest( + message=create_a2a_message_with_skill("get_products", {"brief": "video"}), + configuration=SendMessageConfiguration( + task_push_notification_config=TaskPushNotificationConfig( + id="pnc_private", + # https:// on purpose: registration requires HTTPS unless the deployment + # declares ENVIRONMENT=development, so http:// is refused on the SCHEME + # before the host is examined — and the host verdict is this test's subject. + url="https://169.254.169.254/latest/meta-data", + ) + ), + ) + + # Pins the field AND the concrete block reason. #1697 replaced the former generic + # "must resolve to a public HTTPS endpoint" text with the specific SSRF verdict, so + # matching the reason is both current and a stronger assertion than the old phrase. + with pytest.raises(InvalidParamsError, match=r"push_notification_config\.url.*blocked"): + await handler.on_message_send(params, context=ctx) + + assert handler._task_push_configs == {} + assert handler.tasks == {} + + +@pytest.mark.asyncio +async def test_standalone_push_config_rejects_private_url_before_repository_write(): + """The durable A2A config endpoint rejects unsafe URLs before opening its UoW.""" + handler, ctx = _make_handler() + handler._authenticated_tool_context = MagicMock(return_value=SimpleNamespace(tenant_id="tenant_1")) + + with ( + patch("src.a2a_server.adcp_a2a_server.PushNotificationConfigUoW") as uow, + # See the sibling above: pins the field + the concrete block reason (#1697's + # specific SSRF verdict) rather than the retired generic phrase. + pytest.raises(InvalidParamsError, match=r"push_notification_config\.url.*blocked"), + ): + await handler.on_create_task_push_notification_config( + TaskPushNotificationConfig( + id="pnc_private", + # https:// on purpose. Registration requires HTTPS unless the deployment + # declares ENVIRONMENT=development, so an http:// URL is refused on the + # SCHEME before the host is ever examined — and the subject of this test + # is the private-host verdict the regex above pins. Over https the + # reserved-range check is what produces the rejection. + url="https://10.0.0.5/internal", + ), + context=ctx, + ) + + uow.assert_not_called() + + +def _boundary_recording_spy(): + """Capture the stable boundary-record fields without asserting mock internals.""" + records: list[tuple[str, str, str, str | None, str]] = [] + + def record(transport, operation, error, *, tenant_id, principal_id): + # ``error_code``, matching BOTH the sibling spy above and what production's + # ``record_boundary_error`` actually stores (``extract_error_info`` reads + # ``error.error_code``). Recording ``wire_error_code`` here graded a + # translation the boundary recorder never performs. + records.append((transport, operation, error.error_code, tenant_id, principal_id)) + + return records, record + + +@pytest.mark.asyncio +async def test_untyped_crash_raises_sanitized_internal_error_without_leaking_secrets(): + """An untyped internal crash → sanitized JSON-RPC InternalError; the raw exception + text (which may carry credentials/SQL/hostnames) never reaches the client. + + Per transport-errors.mdx an internal crash is a TRANSPORT-layer error, and the + error-security requirements forbid exposing internals. So untyped exceptions are + logged server-side and surfaced as a generic InternalError — only TYPED + ``AdCPError`` (controlled messages) become failed Tasks. Uses a secret-shaped + message to pin that it is not echoed back. + """ + handler, ctx = _make_handler() + params = make_nl_send_message_request("Show me available products in the catalog") + secret = SECRET_BEARING_MESSAGE + + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY): + with patch("src.a2a_server.adcp_a2a_server.core_get_products_tool", side_effect=RuntimeError(secret)): + with pytest.raises(InternalError) as exc_info: + await handler.on_message_send(params, context=ctx) + + err = exc_info.value + client_facing = f"{err.message} {json.dumps(err.data)}" + assert_no_secret_leak(client_facing) + # Still a structured error with a safe, generic wire code + message. + assert err.data["adcp_error"]["code"] == "SERVICE_UNAVAILABLE" + assert "internal error" in err.message.lower() + + +@pytest.mark.asyncio +async def test_untyped_crash_leaves_no_orphan_working_task(): + """An untyped crash routes to a sanitized InternalError AND leaves no retrievable task. + + Regression: the provisional Task is stored WORKING before dispatch; the untyped-error + branch used to raise the sanitized InternalError without finalizing or removing it, so + ``tasks/get`` still returned a task stuck in WORKING. The crash is a TRANSPORT-layer + error (a JSON-RPC InternalError), not a Task-layer outcome, so the branch now drops the + provisional task + push config before raising — nothing should remain retrievable. + """ + handler, ctx = _make_handler() + params = make_nl_send_message_request("Show me available products in the catalog") + + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY): + with patch("src.a2a_server.adcp_a2a_server.core_get_products_tool", side_effect=RuntimeError("boom")): + with pytest.raises(InternalError): + await handler.on_message_send(params, context=ctx) + + # The provisional WORKING task (and any push config) must be gone — no orphan. + assert handler.tasks == {}, f"orphan task(s) left in WORKING after untyped crash: {list(handler.tasks)}" + assert handler._task_push_configs == {}, "orphan push config left after untyped crash" + + +@pytest.mark.asyncio +async def test_explicit_skill_untyped_crash_scrubs_secret_from_failed_task(): + """An untyped crash inside an EXPLICIT-skill invocation returns a failed Task whose + artifact is scrubbed of the raw exception — in BOTH the DataPart envelope and the + human-readable TextPart. + + Regression: the explicit-skill path routed ``str(exc)`` onto the wire (via + ``normalize_to_adcp_error`` → ``AdCPError(str(exc))``) while the outer/NL path was + already sanitized. Both paths now share the single ``safe_adcp_error`` policy, so an + untyped crash becomes a generic internal error regardless of which path caught it. + Reproduces the failure by patching ``_handle_explicit_skill`` to raise a + secret-shaped exception and inspect the returned failed Task. + """ + handler, ctx = _make_handler() + params = SendMessageRequest(message=create_a2a_message_with_skill("get_products", {"brief": "video"})) + secret = SECRET_BEARING_MESSAGE + + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY): + with patch.object(handler, "_handle_explicit_skill", new_callable=AsyncMock, side_effect=RuntimeError(secret)): + result = await handler.on_message_send(params, context=ctx) + + # The shared strict oracle pins the whole wire contract at once: FAILED state, artifact name, + # exactly one DataPart + one TextPart, and BOTH envelope layers agreeing on code + recovery. + envelope = assert_failed_task_envelope(result, code="SERVICE_UNAVAILABLE", recovery="transient") + # No secret on ANY client-facing carrier of the failed Task (the surface definition lives once). + assert_failed_task_no_secret_leak(result) + # Sanitized to a generic internal error, not a str(exc)-derived message. + assert "internal error" in envelope["errors"][0]["message"].lower() + + +@pytest.mark.asyncio +async def test_failed_explicit_skill_task_is_pollable_via_tasks_get(): + """The buyer must be able to poll tasks/get on a synchronously-returned FAILED explicit-skill + Task — a failed Task is a Task-layer outcome, not a transport error, and the NL-failed path is + already pollable. Regression: the failed-batch branch returned without `_remember_task`, so the + task was an ownerless orphan and `on_get_task` served None to its own owner. + + Drives the REAL `on_get_task` (not the private owner map). No durable step exists in this + in-memory context (no DB), so the durable lookup is stubbed to None and the assertion rests on + the in-memory owned path — which is exactly what the fix populates. Before the fix this returns + None (mutation-verified).""" + handler, ctx = _make_handler() + params = SendMessageRequest(message=create_a2a_message_with_skill("get_products", {"brief": "video"})) + + async def _boom(params, identity): + raise ValueError("boom") + + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY): + with patch.object(handler, "_handle_get_products_skill", new_callable=AsyncMock, side_effect=_boom): + result = await handler.on_message_send(params, context=ctx) + + assert isinstance(result, Task) and result.status.state == TaskState.TASK_STATE_FAILED + + # The owner polls tasks/get. Resolve to the same identity that created the task; no durable + # step in a unit context, so on_get_task must serve the failed Task from the owned in-memory + # path — which requires the failed branch to have remembered it under its owner. + handler._resolve_a2a_identity = MagicMock(return_value=_TEST_IDENTITY) + with patch.object(handler, "_durable_task_from_step", return_value=None): + polled = await handler.on_get_task(GetTaskRequest(id=result.id), context=ctx) + + assert polled is not None, "owner cannot poll their failed explicit-skill task (ownerless orphan)" + assert polled.id == result.id + assert polled.status.state == TaskState.TASK_STATE_FAILED + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("exc_factory", "expected_code", "msg_keyword", "expected_suggestion"), + [ + pytest.param( + lambda s: ValueError(s), "VALIDATION_ERROR", "validate", VALIDATION_ERROR_SUGGESTION, id="ValueError" + ), + pytest.param( + lambda s: PermissionError(s), + "AUTH_REQUIRED", + "credential", + AUTH_REQUIRED_CANONICAL_SUGGESTION, + id="PermissionError", + ), + ], +) +async def test_explicit_skill_raw_builtin_scrubs_secret_but_keeps_semantic_code( + exc_factory, expected_code, msg_keyword, expected_suggestion +): + """A raw ``ValueError``/``PermissionError`` raised INSIDE a skill returns a failed Task whose + envelope keeps the SEMANTIC code the synchronous boundaries emit (VALIDATION_ERROR / + AUTH_REQUIRED) but is scrubbed of the raw ``str(e)``. + + This patches the SKILL (``_handle_get_products_skill``), NOT ``_handle_explicit_skill``, so the + exception flows through the real normalization seam at ``_handle_explicit_skill`` — the seam the + prior secret test bypassed by patching ``_handle_explicit_skill`` itself. Before the + provenance-vs-semantics split, that seam normalized the built-in to a *trusted* + ``AdCPValidationError``/``AdCPAuthorizationError`` and its raw message survived to the wire. + """ + handler, ctx = _make_handler() + params = SendMessageRequest(message=create_a2a_message_with_skill("get_products", {"brief": "video"})) + secret = SECRET_BEARING_MESSAGE + + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY): + with patch.object( + handler, "_handle_get_products_skill", new_callable=AsyncMock, side_effect=exc_factory(secret) + ): + result = await handler.on_message_send(params, context=ctx) + + # SEMANTIC code preserved (matches the synchronous boundary) and both envelope layers agree; + # a raw built-in normalizes to a CLIENT-CORRECTABLE code, never a transient/terminal one. + envelope = assert_failed_task_envelope(result, code=expected_code, recovery="correctable") + assert_failed_task_no_secret_leak(result) + # Message scrubbed AND category-appropriate — a VALIDATION_ERROR / AUTH_REQUIRED must not + # read "internal error". + message = envelope["errors"][0]["message"].lower() + assert msg_keyword in message + assert "internal error" not in message + # The suggestion reaches the WIRE, not just the error object. Chain of custody: this pins + # wire == module constant, and test_sanitized_suggestions_match_pinned_spec_enum pins + # module constant == the pinned spec fixture's enumMetadata. + assert envelope["errors"][0]["suggestion"] == expected_suggestion + + +@pytest.mark.asyncio +async def test_explicit_skill_raw_error_scrubs_activity_and_audit_sinks(): + """A2A preserves raw provenance until tenant-visible observability is scrubbed.""" + handler = AdCPRequestHandler() + feed_records: list[dict[str, object]] = [] + audit_records: list[dict[str, object]] = [] + audit_logger = SimpleNamespace(log_operation=lambda **kwargs: audit_records.append(kwargs)) + + with ( + patch.object( + handler, + "_handle_get_products_skill", + new_callable=AsyncMock, + side_effect=ValueError(SECRET_BEARING_MESSAGE), + ), + patch( + "src.services.activity_feed.activity_feed.log_error", + side_effect=lambda **kwargs: feed_records.append(kwargs), + ), + patch("src.core.audit_logger.get_audit_logger", return_value=audit_logger), + pytest.raises(AdCPError) as exc_info, + ): + await handler._handle_explicit_skill( + "get_products", + {"brief": "video"}, + _TEST_IDENTITY, + ) + + assert exc_info.value.wire_error_code == "VALIDATION_ERROR" + assert len(feed_records) == 1 + assert len(audit_records) == 1 + assert_no_secret_leak(feed_records[0], context="A2A activity error payload") + assert_no_secret_leak(audit_records[0], context="A2A audit error payload") + + +@pytest.mark.asyncio +async def test_unknown_skill_records_boundary_error_exactly_once(): + """An unknown skill emits exactly one boundary-observability record. + + Regression for the observability gap: the unknown-skill check used to raise + BEFORE the logged try, so `record_boundary_error` never fired for it while the + outer catch assumed the inner boundary had already logged. The check now lives + inside the logged boundary, so an unknown skill records exactly once — not zero, + not twice. + """ + handler, ctx = _make_handler() + params = SendMessageRequest(message=create_a2a_message_with_skill("nonexistent_skill", {})) + records, record = _boundary_recording_spy() + + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY): + with patch("src.a2a_server.adcp_a2a_server.record_boundary_error", side_effect=record): + result = await handler.on_message_send(params, context=ctx) + + assert_failed_task_envelope( + result, + code="UNSUPPORTED_FEATURE", + recovery="correctable", + artifact_name="error_result", + ) + assert records == [ + ("a2a", "unsupported_skill", "UNSUPPORTED_FEATURE", _TEST_IDENTITY.tenant_id, _TEST_IDENTITY.principal_id) + ] + + +@pytest.mark.parametrize( + ("identity", "expected_tenant_id", "expected_principal_id"), + [ + pytest.param(None, None, None, id="no-identity"), + pytest.param( + PrincipalFactory.make_identity(tenant_id="t_boundary", principal_id="p_boundary", protocol="a2a"), + "t_boundary", + "p_boundary", + id="resolved-identity", + ), + pytest.param( + ToolContext( + context_id="ctx_boundary", + tenant_id="t_tool", + principal_id="p_tool", + tool_name="set_push_notification_config", + request_timestamp=datetime.now(UTC), + ), + "t_tool", + "p_tool", + id="tool-context", + ), + ], +) +def test_boundary_internal_error_uses_one_scope_policy_regardless_of_caller( + identity, expected_tenant_id, expected_principal_id +): + """``_boundary_internal_error`` — the single home shared by all seven A2A + request handlers — logs the SAME identity-scope policy for resolved identities, + tool contexts, and unresolved callers. + + Regression: ``on_message_send``'s boundary arm used to open-code + ``(identity.tenant_id or "unknown") if identity else "unknown"`` while + ``on_get_task``/``on_cancel_task`` open-coded + ``getattr(identity, "tenant_id", None)`` / ``getattr(..., "principal_id", None) or + "anonymous"`` — the SAME unresolved-identity event logged under two different + sentinels (``"unknown"``/``"unknown"`` vs ``None``/``"anonymous"``), un-greppable + across handlers. All seven now delegate to this one function, so there is exactly + one scope and sentinel definition to test. + """ + from src.a2a_server.adcp_a2a_server import _boundary_internal_error + + exc = RuntimeError("boom") + with patch("src.a2a_server.adcp_a2a_server.record_boundary_error") as mock_record: + result = _boundary_internal_error("some_op", "some operation", identity, exc) + + mock_record.assert_called_once_with( + "a2a", + "some_op", + exc, + tenant_id=expected_tenant_id, + principal_id=expected_principal_id, + ) + assert isinstance(result, InternalError) + + +def test_anonymous_discovery_boundary_error_is_tenant_unscoped(): + """A header-selected tenant cannot receive anonymous discovery failures.""" + from src.a2a_server.adcp_a2a_server import _record_a2a_boundary_error + + identity = PrincipalFactory.make_identity( + tenant_id="header-selected-tenant", + principal_id=None, + protocol="a2a", + ) + exc = ValueError("anonymous get_products validation failed") + + with patch("src.a2a_server.adcp_a2a_server.record_boundary_error") as mock_record: + _record_a2a_boundary_error("get_products", identity, exc) + + mock_record.assert_called_once_with( + "a2a", + "get_products", + exc, + tenant_id=None, + principal_id=None, + ) + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("handler_name", "op_key", "op_label"), + [ + pytest.param( + "on_get_task_push_notification_config", + "get_push_notification_config", + "get push notification config", + id="get", + ), + pytest.param( + "on_create_task_push_notification_config", + "create_push_notification_config", + "set push notification config", + id="create", + ), + pytest.param( + "on_list_task_push_notification_configs", + "list_push_notification_configs", + "list push notification configs", + id="list", + ), + pytest.param( + "on_delete_task_push_notification_config", + "delete_push_notification_config", + "delete push notification config", + id="delete", + ), + ], +) +async def test_push_config_handlers_share_boundary_internal_error(handler_name, op_key, op_label): + """Every push-config handler delegates its untyped-crash arm to the same scope, + audit, and sanitization helper as message/send and task get/cancel. + """ + handler = AdCPRequestHandler() + exc = RuntimeError("boom") + handler._authenticated_tool_context = MagicMock(side_effect=exc) + translated = InternalError(message="sanitized") + + with patch( + "src.a2a_server.adcp_a2a_server._boundary_internal_error", + return_value=translated, + ) as mock_boundary: + with pytest.raises(InternalError) as exc_info: + await getattr(handler, handler_name)(MagicMock(), MagicMock()) + + assert exc_info.value is translated + mock_boundary.assert_called_once_with(op_key, op_label, None, exc) + + +@pytest.mark.asyncio +async def test_typed_adcp_error_keeps_its_own_wire_code_on_failed_task(): + """A typed AdCPError escaping to the outer handler keeps its own wire code. + + The envelope must carry the AdCPError's code (here ``VALIDATION_ERROR``), + not a blanket ``INTERNAL_ERROR`` — ``_build_error_envelope`` passes typed + errors through ``safe_adcp_error`` unchanged (only untyped crashes are + replaced with a generic error). + """ + handler, ctx = _make_handler() + params = make_nl_send_message_request("Show me available products in the catalog") + + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY): + with patch( + "src.a2a_server.adcp_a2a_server.core_get_products_tool", + side_effect=AdCPValidationError("brief must not be empty", _wire_safe_message=True), + ): + result = await handler.on_message_send(params, context=ctx) + + assert isinstance(result, Task), f"expected a returned Task, got {type(result).__name__}" + assert result.status.state == TaskState.TASK_STATE_FAILED, ( + f"expected TASK_STATE_FAILED, got {result.status.state!r}" + ) + assert_envelope_shape( + extract_processing_error_envelope(result), + "VALIDATION_ERROR", + recovery="correctable", + message_substr="brief must not be empty", + ) + + +@pytest.mark.parametrize( + ("raised", "expected_code"), + [ + (ValueError(SECRET_BEARING_MESSAGE), "VALIDATION_ERROR"), + (PermissionError(SECRET_BEARING_MESSAGE), "AUTH_REQUIRED"), + ], + ids=["value_error", "permission_error"], +) +@pytest.mark.asyncio +async def test_nl_client_correctable_builtin_becomes_failed_task_not_internal_error(raised, expected_code): + """A client-correctable built-in from an NL handler is an APPLICATION-layer failure. + + AdCP 3.1.1 ``transport-errors.mdx`` §"Layer Separation" puts AdCP errors in the task + response, not the transport error channel, and classifies a malformed request as a + Validation Error rather than a Protocol Error. Explicit-skill dispatch already honoured + that; NL routing did not, because its handlers were invoked outside the sanitize seam — + so a raw ``ValueError`` surfaced as a JSON-RPC ``InternalError``. The envelope inside it + already said ``correctable``, which told the buyer not to auto-retry while the transport + frame told them it was a server fault. + + Ungraded by the 3.1.1 conformance storyboards (``check: error_code`` is shape-agnostic + and accepts ``error.data``), so this test is the contract. + + The recorder assertion is on the exception TYPE, not its wire code: the seam must hand + ``record_boundary_error`` the ORIGINAL built-in so the privileged log keeps the raw text + and traceback, while the wire gets the scrubbed copy. + """ + handler, ctx = _make_handler() + params = make_nl_send_message_request("Show me available products in the catalog") + + recorded: list[tuple[str, str]] = [] + + def record(transport, operation, error, *, tenant_id, principal_id): + recorded.append((operation, type(error).__name__)) + + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY): + with patch("src.a2a_server.adcp_a2a_server.core_get_products_tool", side_effect=raised): + with patch("src.a2a_server.adcp_a2a_server.record_boundary_error", side_effect=record): + result = await handler.on_message_send(params, context=ctx) + + assert isinstance(result, Task), f"expected a failed Task, got {type(result).__name__}" + assert result.status.state == TaskState.TASK_STATE_FAILED + + envelope = extract_processing_error_envelope(result) + assert_envelope_shape(envelope, expected_code, recovery="correctable") + assert_no_secret_leak(envelope, context=f"NL {type(raised).__name__} failed-Task envelope") + + # Recorded exactly once, with the ORIGINAL exception, under its own operation label. + assert recorded == [("get_products", type(raised).__name__)] + + # The failed Task is retained: it is a task-layer outcome, so tasks/get can serve it. + assert handler.tasks, "a failed Task must not be dropped like a transport-layer crash" + + +@pytest.mark.asyncio +async def test_nl_typed_failure_records_once_under_its_own_operation(): + """A typed NL-routing failure is recorded exactly once, labelled by the operation. + + The record moved from the outer task boundary into the shared dispatch seam, so it now + carries the specific operation (``get_products``) instead of the generic + ``message_processing`` — matching what explicit-skill dispatch has always logged, and + making the two paths greppable together. "Once" remains the load-bearing half: the + outer arm is pure framing now, so a re-added record there would show up as a second + entry. + """ + handler, ctx = _make_handler() + params = make_nl_send_message_request("Show me available products in the catalog") + records, record = _boundary_recording_spy() + + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY): + with patch( + "src.a2a_server.adcp_a2a_server.core_get_products_tool", + side_effect=AdCPValidationError("brief must not be empty"), + ): + with patch("src.a2a_server.adcp_a2a_server.record_boundary_error", side_effect=record): + result = await handler.on_message_send(params, context=ctx) + + assert_failed_task_envelope( + result, + code="VALIDATION_ERROR", + recovery="correctable", + artifact_name="processing_error", + ) + assert records == [ + ("a2a", "get_products", "VALIDATION_ERROR", _TEST_IDENTITY.tenant_id, _TEST_IDENTITY.principal_id) + ] + + +@pytest.mark.asyncio +async def test_auth_extraction_failure_raises_sanitized_internal_error_no_nameerror(): + """A crash before identity resolution raises a sanitized InternalError, no NameError. + + Pins the ``identity = None`` hoist: auth-token extraction happens before identity + resolution, so the untyped-crash handler must read ``identity`` (None) without a + ``NameError`` while logging. The crash is untyped → sanitized JSON-RPC + InternalError (not a failed Task), the raw text is not leaked, and no webhook. + """ + handler = AdCPRequestHandler() + handler._get_auth_token = MagicMock(side_effect=RuntimeError(SECRET_BEARING_MESSAGE)) + handler._send_protocol_webhook = AsyncMock() + ctx = make_a2a_context(headers={"host": "test.example.com"}) + params = make_nl_send_message_request("Show me available products in the catalog") + + with pytest.raises(InternalError) as exc_info: + await handler.on_message_send(params, context=ctx) + + err = exc_info.value + client_facing = f"{err.message} {json.dumps(err.data)}" + assert_no_secret_leak(client_facing, context="auth-extraction crash on the JSON-RPC wire") + assert_envelope_shape(err.data, "SERVICE_UNAVAILABLE", recovery="transient") + handler._send_protocol_webhook.assert_not_awaited() + + +@pytest.mark.asyncio +async def test_multi_skill_message_rejected_before_any_side_effect(): + """A message carrying >1 skill is rejected up front — no skill runs, no side effects. + + Aggregating divergent per-skill outcomes into one Task is incoherent when a skill + has real side effects (a submitted create_media_buy persists a workflow while a + sibling fails). So a multi-skill batch is rejected as a typed application failure + (UNSUPPORTED_FEATURE) BEFORE dispatch — ``_handle_explicit_skill`` is never + called, and the immediate terminal failure sends no webhook. + """ + handler, ctx = _make_handler() + handler._send_protocol_webhook = AsyncMock() + handler._handle_explicit_skill = AsyncMock() # must NOT be called + message = create_a2a_message_with_skill("create_media_buy", {}) + message.parts.append(create_a2a_message_with_skill("approve_creative", {}).parts[0]) + params = SendMessageRequest(message=message) + + records, record = _boundary_recording_spy() + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY): + with patch("src.a2a_server.adcp_a2a_server.record_boundary_error", side_effect=record): + result = await handler.on_message_send(params, context=ctx) + + assert isinstance(result, Task) + assert result.status.state == TaskState.TASK_STATE_FAILED + envelope = extract_processing_error_envelope(result) + assert envelope["adcp_error"]["code"] == "UNSUPPORTED_FEATURE", envelope + assert envelope["adcp_error"]["recovery"] == "correctable", envelope + assert "multiple skills" in envelope["errors"][0]["message"].lower() + handler._handle_explicit_skill.assert_not_awaited() # zero side effects + handler._send_protocol_webhook.assert_not_awaited() + assert records == [ + ("a2a", "message_processing", "UNSUPPORTED_FEATURE", _TEST_IDENTITY.tenant_id, _TEST_IDENTITY.principal_id) + ] + + +@pytest.mark.asyncio +async def test_immediate_completed_task_sends_no_webhook(): + """An immediately-completed task returns synchronously and sends no webhook. + + a2a-guide.mdx "Webhook Trigger Rules": no push is sent + when the initial response is already terminal — the buyer has the result in + the response. Only non-terminal (submitted) initial responses notify. + """ + handler, ctx = _make_handler() + handler._send_protocol_webhook = AsyncMock() + # A plain completed result (no "status": "submitted") → task completes immediately. + handler._handle_explicit_skill = AsyncMock(return_value={"products": [{"id": "p1"}]}) + message = create_a2a_message_with_skill("get_products", {}) + params = SendMessageRequest(message=message) + + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY): + result = await handler.on_message_send(params, context=ctx) + + assert result.status.state == TaskState.TASK_STATE_COMPLETED + handler._send_protocol_webhook.assert_not_awaited() + + +@pytest.mark.asyncio +async def test_send_protocol_webhook_serializes_every_artifact_including_duplicate_names(): + """``_send_protocol_webhook`` puts EVERY artifact's data on the wire — including + duplicate-named ones — never a single stale value or a flattened error string. + + Scope note: this is a focused unit test of the webhook serializer at the status + production actually calls it with (``submitted``); the real async *failure* + transition is emitted elsewhere (``src/core/context_manager.py``) and is out of + this helper's scope. Two artifacts share the name ``error_result`` (repeated + skill in one message) plus a distinct sibling — all three must survive + serialization, so name-based overwriting is caught. + """ + from google.protobuf import json_format + + handler = AdCPRequestHandler() + + env_a = AdCPRequestHandler._build_error_envelope( + AdCPValidationError("first skill exploded", _wire_safe_message=True) + ) + env_b = AdCPRequestHandler._build_error_envelope( + AdCPValidationError("second skill exploded", _wire_safe_message=True) + ) + task = Task(id="task_sub", context_id="ctx_sub", status=TaskStatus(state=TaskState.TASK_STATE_SUBMITTED)) + # Two artifacts with the SAME name (repeated skill) + a distinct sibling. + task.artifacts.append( + Artifact(artifact_id="skill_result_1", name="error_result", parts=[Part(data=_dict_to_value(env_a))]) + ) + task.artifacts.append( + Artifact(artifact_id="skill_result_2", name="error_result", parts=[Part(data=_dict_to_value(env_b))]) + ) + task.artifacts.append( + Artifact( + artifact_id="skill_result_3", + name="get_products_result", + parts=[Part(data=_dict_to_value({"products": [{"id": "p-sibling"}]}))], + ) + ) + handler._task_push_configs[task.id] = TaskPushNotificationConfig(id="pnc_1", url="https://buyer.example/webhook") + + captured: dict = {} + + async def _capture(*, push_notification_config, payload, metadata): + captured["payload"] = payload + + service = MagicMock() + service.send_notification = AsyncMock(side_effect=_capture) + + # create_a2a_webhook_payload is NOT mocked — we verify the real emitted wire payload. + with patch("src.a2a_server.adcp_a2a_server.get_protocol_webhook_service", return_value=service): + await handler._send_protocol_webhook(task, status="submitted") + + service.send_notification.assert_awaited_once() + wire = json.dumps(json_format.MessageToDict(captured["payload"])) + # BOTH same-named error envelopes AND the sibling survive (no name overwrite, no flatten). + assert "first skill exploded" in wire, f"first same-named artifact dropped: {wire}" + assert "second skill exploded" in wire, f"second same-named artifact overwritten by name collision: {wire}" + assert "p-sibling" in wire, f"sibling artifact dropped: {wire}" + + +def test_read_failed_a2a_task_strict_asserts_on_artifactless_task(): + """Strict mode must trip the artifact-present pin on an artifact-less failed Task. + + Pins the branch order in ``_read_failed_a2a_task``: the + ``expect_processing_error`` dispatch happens BEFORE the ``task.artifacts`` + guard, so the strict reader's "failed Task must carry the error envelope + artifact" assertion is reachable. Reverting to guard-first silently + downgrades strict mode to the loose fallback and this test goes red. + """ + from a2a.types import TaskStatus + + from tests.harness._base import _read_failed_a2a_task + + bare_failed = Task(id="t-bare", status=TaskStatus(state=TaskState.TASK_STATE_FAILED)) + + with pytest.raises(AssertionError, match="must carry the error envelope artifact"): + _read_failed_a2a_task(bare_failed, fallback_message="x", expect_processing_error=True) + + +def test_read_failed_a2a_task_loose_falls_back_on_artifactless_task(): + """Loose mode keeps the harness fallback: (None, bare AdCPError) — no raise.""" + from a2a.types import TaskStatus + + from src.core.exceptions import AdCPError + from tests.harness._base import _read_failed_a2a_task + + bare_failed = Task(id="t-bare", status=TaskStatus(state=TaskState.TASK_STATE_FAILED)) + + envelope, error = _read_failed_a2a_task(bare_failed, fallback_message="x") + + assert envelope is None + assert type(error) is AdCPError, f"expected bare AdCPError fallback, got {type(error).__name__}" + assert "A2A task failed" in str(error) + + +@pytest.mark.parametrize( + ("artifact", "expected_match"), + [ + pytest.param(None, "must carry the error envelope artifact", id="no-artifact"), + pytest.param( + Artifact(artifact_id="e1", name="wrong_name", parts=[Part(text="boom"), Part(data=_dict_to_value({}))]), + "expected 'error_result' artifact", + id="wrong-artifact-name", + ), + pytest.param( + Artifact(artifact_id="e1", name="error_result", parts=[Part(data=_dict_to_value({}))]), + "must carry a human-readable TextPart", + id="datapart-alone", + ), + pytest.param( + Artifact( + artifact_id="e1", + name="error_result", + parts=[Part(text="boom"), Part(data=_dict_to_value({})), Part(data=_dict_to_value({}))], + ), + "exactly one authoritative DataPart", + id="two-dataparts", + ), + ], +) +def test_failed_task_artifact_reader_rejects_off_contract_shapes(artifact, expected_match): + """Known-bad self-tests for the strict failed-Task reader every A2A error test depends on. + + The reader's pins are what make ``assert_failed_task_envelope`` stronger than a raw + ``artifacts[0]`` read. Without these, DELETING one of its assertions reddens nothing + test-side — the oracle could silently weaken while every call site stayed green. + Mirrors the harness twin's self-tests one file over. + """ + from tests.utils.a2a_helpers import _read_failed_task_artifact + + task = Task(id="t-shape", status=TaskStatus(state=TaskState.TASK_STATE_FAILED)) + if artifact is not None: + task.artifacts.append(artifact) + + with pytest.raises(AssertionError, match=expected_match): + _read_failed_task_artifact(task, "error_result") + + +@pytest.mark.asyncio +async def test_genuine_transport_fault_still_raises_json_rpc_error(): + """A transport-protocol fault must still surface as a JSON-RPC error. + + Missing authentication for a non-discovery skill is a transport-layer + fault (the request cannot be routed at all), so ``on_message_send`` + re-raises the ``A2AError`` (here ``InvalidRequestError``) onto the + JSON-RPC layer instead of returning a failed Task. + """ + handler = AdCPRequestHandler() + # No auth token at all — create_media_buy is a non-discovery skill. + ctx = make_a2a_context(auth_token=None, headers={"host": "test.example.com"}) + message = create_a2a_message_with_skill("create_media_buy", {"product_ids": ["prod_1"]}) + params = SendMessageRequest(message=message) + + with pytest.raises(InvalidRequestError) as exc_info: + await handler.on_message_send(params, context=ctx) + + assert "authentication" in str(exc_info.value).lower(), ( + f"transport fault should name the missing authentication; got: {exc_info.value}" + ) + + +@pytest.mark.parametrize( + ("handler_method", "params"), + [ + ("on_get_task", GetTaskRequest(id="task_auth")), + ("on_cancel_task", CancelTaskRequest(id="task_auth")), + ], +) +@pytest.mark.parametrize("auth_token", [None, "invalid-token"]) +@pytest.mark.asyncio +async def test_task_management_auth_failures_stay_on_json_rpc_wire(handler_method, params, auth_token): + """Missing/invalid task-management auth must remain a serialized transport error. + + ``_durable_lookup_identity`` previously swallowed every resolver exception and made + tasks/get + tasks/cancel return ``None`` (indistinguishable from task-not-found). + Drive both public handlers and serialize the real ``InvalidRequestError`` through + the SDK dispatcher helper so the regression is pinned at the JSON-RPC wire altitude. + """ + handler = AdCPRequestHandler() + handler._get_auth_token = MagicMock(return_value=auth_token) + if auth_token: + handler._resolve_a2a_identity = MagicMock( + side_effect=InvalidRequestError(message="Authentication token is invalid or expired.") + ) + + with pytest.raises(InvalidRequestError) as exc_info: + await getattr(handler, handler_method)(params, context=None) + + wire = build_error_response("req-auth", exc_info.value) + serialized = serialize_wire_error(wire) + assert "Authentication" in serialized or "authentication" in serialized + assert "task_auth" not in serialized, "auth failures must not be downgraded to task-not-found output" + + +def _auth_guarded_methods(): + """Every A2A method whose auth failure a buyer can branch on, with minimal params. + + Built as a function (not a module constant) so the request objects are fresh per test. + + Includes ``on_message_send`` — it is the method the helper docstring names first, and + omitting it while claiming coverage is exactly the gap this list exists to close. Its + params carry a NON-discovery skill so the request actually requires auth (a discovery + skill is public and would resolve anonymously instead of rejecting). + """ + from a2a.types import ( + DeleteTaskPushNotificationConfigRequest, + GetTaskPushNotificationConfigRequest, + ListTaskPushNotificationConfigsRequest, + ) + + return [ + ( + "on_message_send", + SendMessageRequest(message=create_a2a_message_with_skill("create_media_buy", {"buyer_ref": "b1"})), + ), + ("on_get_task", GetTaskRequest(id="task_envelope")), + ("on_cancel_task", CancelTaskRequest(id="task_envelope")), + ( + "on_get_task_push_notification_config", + GetTaskPushNotificationConfigRequest(id="pnc_1", task_id="task_envelope"), + ), + ("on_create_task_push_notification_config", TaskPushNotificationConfig(id="pnc_1", task_id="task_envelope")), + ("on_list_task_push_notification_configs", ListTaskPushNotificationConfigsRequest(task_id="task_envelope")), + ( + "on_delete_task_push_notification_config", + DeleteTaskPushNotificationConfigRequest(id="pnc_1", task_id="task_envelope"), + ), + ] + + +@pytest.mark.parametrize(("handler_method", "params"), _auth_guarded_methods()) +@pytest.mark.asyncio +async def test_every_auth_guarded_method_carries_the_auth_missing_envelope(handler_method, params): + """EVERY A2A method's missing-credential failure carries AUTH_MISSING in ``data``. + + "Stays on the JSON-RPC wire" and "carries the envelope in ``data``" are orthogonal: the + sibling test above pins only the former. Regression this closes: the envelope was attached + at the message/send arm alone, so a buyer branching on + ``error.data.adcp_error.code == "AUTH_MISSING"`` got it from message/send but NOT from + tasks/get, tasks/cancel, or any push-notification-config method. All auth raises now share + one enveloped source, so this parametrization reddens if any arm regresses to a bare error. + """ + handler = AdCPRequestHandler() + handler._get_auth_token = MagicMock(return_value=None) + context = make_a2a_context( + auth_token=None, + headers={"x-adcp-tenant": "tenant-from-a2a-headers"}, + ) + records, recorder = _capture_a2a_auth_records() + + with ( + patch("src.core.resolved_identity.resolve_identity") as mock_resolve, + patch("src.a2a_server.adcp_a2a_server.record_boundary_error", side_effect=recorder), + ): + with pytest.raises(InvalidRequestError) as exc_info: + await getattr(handler, handler_method)(params, context=context) + + mock_resolve.assert_not_called() + err = exc_info.value + assert records == [("a2a", "authentication", "AUTH_MISSING", None, None)] + assert err.data is not None, f"{handler_method} auth failure dropped the AdCP envelope from error.data" + # Assert on the SERIALIZED JSON-RPC body the buyer actually receives, not the raised exception + # object: ``build_error_response`` is the SDK dispatcher's own serializer, so a payload that + # failed to survive it would never reach a buyer regardless of what the object held. + body = build_error_response("req-auth", err) + assert_envelope_shape(body["error"]["data"], "AUTH_MISSING", recovery="correctable") + # Both wire layers must carry the SAME sanitized message (per _enveloped_invalid_request's + # contract), and the suggestion must be the pinned-spec AUTH_MISSING hint — neither property was + # pinned above, so a regression that desynced ``error.message`` from the envelope's message, or + # dropped/replaced the suggestion, would have gone undetected. + assert body["error"]["message"] == body["error"]["data"]["adcp_error"]["message"] + assert body["error"]["data"]["adcp_error"]["suggestion"] == pinned_error_code_suggestion("AUTH_MISSING") + + +# The parametrization above drives only the MISSING-TOKEN arm. The remaining auth arms each +# need their own trigger, and without these a revert of any one of them to a bare +# InvalidRequestError reddens nothing. + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("handler_method", "params"), _auth_guarded_methods()) +async def test_auth_resolution_failure_arm_carries_the_auth_invalid_envelope(handler_method, params): + """Every A2A auth boundary classifies a rejected presented token as AUTH_INVALID.""" + handler = AdCPRequestHandler() + handler._get_auth_token = MagicMock(return_value="a-rejected-token") + auth_error = AdCPAuthenticationError("Token rejected by the credential store.") + + context = make_a2a_context( + auth_token="a-rejected-token", + headers={ + "Authorization": "Bearer a-rejected-token", + "x-adcp-tenant": "tenant-from-a2a-headers", + }, + ) + records, recorder = _capture_a2a_auth_records() + + with ( + patch( + "src.core.resolved_identity.resolve_identity", + side_effect=auth_error, + ) as mock_resolve, + patch("src.a2a_server.adcp_a2a_server.record_boundary_error", side_effect=recorder), + ): + with pytest.raises(InvalidRequestError) as exc_info: + await getattr(handler, handler_method)(params, context=context) + + assert len(mock_resolve.call_args_list) == 1 + resolve_call = mock_resolve.call_args_list[0] + assert resolve_call.kwargs["auth_token"] == "a-rejected-token" + assert resolve_call.kwargs["require_valid_token"] is True + assert resolve_call.kwargs["protocol"] == "a2a" + assert records == [("a2a", "authentication", "AUTH_INVALID", None, None)] + assert_envelope_shape(exc_info.value.data, "AUTH_INVALID", recovery="terminal") + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("handler_method", "params"), _auth_guarded_methods()) +async def test_principal_less_identity_arm_carries_the_auth_invalid_envelope(handler_method, params): + """Every A2A auth boundary classifies a principal-less token as AUTH_INVALID.""" + handler = AdCPRequestHandler() + handler._get_auth_token = MagicMock(return_value="a-stale-token") + principal_less = PrincipalFactory.make_identity( + principal_id=None, tenant_id="test-tenant", tenant={"tenant_id": "test-tenant"}, protocol="a2a" + ) + records, recorder = _capture_a2a_auth_records() + + with ( + patch("src.core.resolved_identity.resolve_identity", return_value=principal_less) as mock_resolve, + patch("src.a2a_server.adcp_a2a_server.record_boundary_error", side_effect=recorder), + ): + with pytest.raises(InvalidRequestError) as exc_info: + await getattr(handler, handler_method)( + params, + context=make_a2a_context( + auth_token="a-stale-token", + headers={"Authorization": "Bearer a-stale-token"}, + ), + ) + + assert len(mock_resolve.call_args_list) == 1 + assert mock_resolve.call_args_list[0].kwargs["require_valid_token"] is True + assert records == [("a2a", "authentication", "AUTH_INVALID", None, None)] + assert_envelope_shape(exc_info.value.data, "AUTH_INVALID", recovery="terminal") + + +@pytest.mark.asyncio +async def test_rejected_legacy_a2a_token_without_authorization_is_auth_missing(): + """A2A must not let the accepted legacy header redefine the v3.1.1 split.""" + handler = AdCPRequestHandler() + context = make_a2a_context( + auth_token="legacy-rejected-token", + headers={ + "x-adcp-auth": "legacy-rejected-token", + "x-adcp-tenant": "header-selected-tenant", + }, + ) + + with patch( + "src.core.resolved_identity.resolve_identity", + side_effect=AdCPAuthInvalidError("legacy token rejected"), + ): + with pytest.raises(InvalidRequestError) as exc_info: + handler._resolve_a2a_identity( + "legacy-rejected-token", + require_valid_token=True, + context=context, + ) + + assert_envelope_shape(exc_info.value.data, "AUTH_MISSING", recovery="correctable") + + +@pytest.mark.asyncio +async def test_explicit_skill_identity_guard_carries_the_envelope(): + """The standalone `_handle_explicit_skill` guard — a non-discovery skill with no identity. + + Not reachable through the missing-token parametrization: it fires after dispatch, on the + identity object rather than the token. + """ + handler = AdCPRequestHandler() + records, recorder = _capture_a2a_auth_records() + + with patch("src.a2a_server.adcp_a2a_server.record_boundary_error", side_effect=recorder): + with pytest.raises(InvalidRequestError) as exc_info: + await handler._handle_explicit_skill("create_media_buy", {"buyer_ref": "b1"}, None) + + assert records == [("a2a", "authentication", "AUTH_MISSING", None, None)] + assert_envelope_shape(exc_info.value.data, "AUTH_MISSING", recovery="correctable") + + +@pytest.mark.asyncio +async def test_tenantless_authenticated_principal_is_a_terminal_config_error_not_auth_required(): + """Valid credentials + no resolvable tenant is a SELLER-side failure, not a buyer auth problem. + + Emitting AUTH_REQUIRED here would tell a buyer to fix credentials that are already correct. + The pinned 3.1.1 enum classifies CONFIGURATION_ERROR as terminal, and it is an internal wire + code — so the message is scrubbed, which is what keeps the principal id off the wire. + """ + handler = AdCPRequestHandler() + handler._get_auth_token = MagicMock(return_value="a-valid-token") + tenantless = PrincipalFactory.make_identity(principal_id="p-orphan", tenant_id=None, tenant=None, protocol="a2a") + records, recorder = _capture_a2a_auth_records() + + with ( + patch("src.core.resolved_identity.resolve_identity", return_value=tenantless), + patch("src.a2a_server.adcp_a2a_server.record_boundary_error", side_effect=recorder), + ): + with pytest.raises(InvalidRequestError) as exc_info: + await handler.on_get_task(GetTaskRequest(id="task_envelope"), context=None) + + assert records == [("a2a", "authentication", "CONFIGURATION_ERROR", None, "p-orphan")] + err = exc_info.value + assert_envelope_shape(err.data, "CONFIGURATION_ERROR", recovery="terminal") + assert "p-orphan" not in json.dumps(err.data, default=str), "principal id leaked to the wire" + + +def test_failed_task_reader_finds_the_error_artifact_behind_a_sibling(): + """``_read_failed_a2a_task`` must scan EVERY artifact, not just the first. + + The loose read is the reader nearly every A2A error assertion routes through. Its + comment names the defect the scan prevents — a first-artifact-only read being + order-dependent and surfacing a non-error sibling — but the property was prose-only: + reverting the loop to ``task.artifacts[:1]`` left 313 tests green, because no test + anywhere builds a FAILED Task whose FIRST artifact is a non-error sibling. The one + multi-artifact builder in this file is a SUBMITTED-status webhook-serializer test, + which never reaches this reader. + + Ordering is the whole point, so the sibling is placed FIRST: a reader that stops at + artifacts[0] returns the products payload, whose two-layer reconstruction yields no + error code and therefore the bare fallback AdCPError instead of the real rejection. + """ + from tests.harness._base import _read_failed_a2a_task + + envelope = AdCPRequestHandler._build_error_envelope( + AdCPValidationError("package_id is required", _wire_safe_message=True) + ) + task = Task(id="task_multi", context_id="ctx_multi", status=TaskStatus(state=TaskState.TASK_STATE_FAILED)) + task.artifacts.append( + Artifact( + artifact_id="a1", + name="get_products_result", + parts=[Part(data=_dict_to_value({"products": [{"id": "p-sibling"}]}))], + ) + ) + task.artifacts.append(Artifact(artifact_id="a2", name="error_result", parts=[Part(data=_dict_to_value(envelope))])) + + read_envelope, error = _read_failed_a2a_task(task, fallback_message="A2A skill failed") + + assert read_envelope is not None + assert read_envelope["adcp_error"]["code"] == "VALIDATION_ERROR" + assert "products" not in read_envelope, "the non-error sibling was returned as the envelope" + assert getattr(error, "error_code", None) == "VALIDATION_ERROR", ( + f"the reconstructed error fell back instead of using the real envelope: {error!r}" + ) diff --git a/tests/unit/test_a2a_handler_correctness.py b/tests/unit/test_a2a_handler_correctness.py index 9b7b2eb9e3..9f30b39bc4 100644 --- a/tests/unit/test_a2a_handler_correctness.py +++ b/tests/unit/test_a2a_handler_correctness.py @@ -10,6 +10,8 @@ import pytest from a2a.utils.errors import A2AError +from src.core.exceptions import AdCPCapabilityNotSupportedError + class TestTaskIdCollisionFree: """task_id generation must be collision-free under concurrent access.""" @@ -78,11 +80,19 @@ def test_no_debug_prefix_in_info_logs(self): class TestStubSkillsRaiseErrors: - """Unimplemented skills must raise A2AError, not return success:False dicts.""" + """Unimplemented skills must raise a typed AdCP error (application-layer), not + a JSON-RPC ``A2AError`` and not a ``success:False`` dict. + + A recognized-but-unimplemented skill is an application failure — the outer + dispatcher surfaces it as a failed Task with an ``UNSUPPORTED_FEATURE`` + two-layer envelope, per AdCP 3.1.1 "Layer Separation". Raising an + ``A2AError`` (UnsupportedOperationError) would leak it onto the JSON-RPC + transport layer, discarding any accumulated results in a multi-skill message. + """ @pytest.mark.asyncio - async def test_approve_creative_raises_error(self): - """approve_creative must raise UnsupportedOperationError (A2AError subclass).""" + async def test_approve_creative_raises_capability_not_supported(self): + """approve_creative must raise AdCPCapabilityNotSupportedError, not A2AError.""" from src.a2a_server.adcp_a2a_server import AdCPRequestHandler from tests.factories.principal import PrincipalFactory @@ -90,12 +100,14 @@ async def test_approve_creative_raises_error(self): identity = PrincipalFactory.make_identity( principal_id="test", tenant_id="test", tenant={"tenant_id": "test"}, protocol="a2a" ) - with pytest.raises(A2AError): + with pytest.raises(AdCPCapabilityNotSupportedError) as exc_info: await handler._handle_approve_creative_skill({}, identity) + assert not isinstance(exc_info.value, A2AError) + assert exc_info.value.error_code == "UNSUPPORTED_FEATURE" @pytest.mark.asyncio - async def test_get_media_buy_status_raises_error(self): - """get_media_buy_status must raise UnsupportedOperationError (A2AError subclass).""" + async def test_get_media_buy_status_raises_capability_not_supported(self): + """get_media_buy_status must raise AdCPCapabilityNotSupportedError, not A2AError.""" from src.a2a_server.adcp_a2a_server import AdCPRequestHandler from tests.factories.principal import PrincipalFactory @@ -103,12 +115,14 @@ async def test_get_media_buy_status_raises_error(self): identity = PrincipalFactory.make_identity( principal_id="test", tenant_id="test", tenant={"tenant_id": "test"}, protocol="a2a" ) - with pytest.raises(A2AError): + with pytest.raises(AdCPCapabilityNotSupportedError) as exc_info: await handler._handle_get_media_buy_status_skill({}, identity) + assert not isinstance(exc_info.value, A2AError) + assert exc_info.value.error_code == "UNSUPPORTED_FEATURE" @pytest.mark.asyncio - async def test_optimize_media_buy_raises_error(self): - """optimize_media_buy must raise UnsupportedOperationError (A2AError subclass).""" + async def test_optimize_media_buy_raises_capability_not_supported(self): + """optimize_media_buy must raise AdCPCapabilityNotSupportedError, not A2AError.""" from src.a2a_server.adcp_a2a_server import AdCPRequestHandler from tests.factories.principal import PrincipalFactory @@ -116,5 +130,7 @@ async def test_optimize_media_buy_raises_error(self): identity = PrincipalFactory.make_identity( principal_id="test", tenant_id="test", tenant={"tenant_id": "test"}, protocol="a2a" ) - with pytest.raises(A2AError): + with pytest.raises(AdCPCapabilityNotSupportedError) as exc_info: await handler._handle_optimize_media_buy_skill({}, identity) + assert not isinstance(exc_info.value, A2AError) + assert exc_info.value.error_code == "UNSUPPORTED_FEATURE" diff --git a/tests/unit/test_a2a_nl_auth_redundancy.py b/tests/unit/test_a2a_nl_auth_redundancy.py index 9cb825930e..b0709ad2ac 100644 --- a/tests/unit/test_a2a_nl_auth_redundancy.py +++ b/tests/unit/test_a2a_nl_auth_redundancy.py @@ -8,33 +8,19 @@ This test verifies resolve_identity() is called at most once per NL request. """ -import uuid from unittest.mock import MagicMock, patch import pytest from src.a2a_server.adcp_a2a_server import AdCPRequestHandler from tests.a2a_helpers import make_a2a_context -from tests.factories.principal import PrincipalFactory - -_MOCK_IDENTITY = PrincipalFactory.make_identity( - principal_id="test-principal", - tenant_id="test-tenant", - tenant={"tenant_id": "test-tenant"}, - protocol="a2a", +from tests.utils.a2a_helpers import ( + extract_processing_error_envelope, + make_nl_send_message_request, + make_test_a2a_identity, ) - -def _make_nl_message(text: str): - """Build a minimal A2A SendMessageRequest with NL text (no skills).""" - from a2a.types import Message, Part, Role, SendMessageRequest - - message = Message( - message_id=str(uuid.uuid4()), - role=Role.ROLE_USER, - ) - message.parts.append(Part(text=text)) - return SendMessageRequest(message=message) +_TEST_IDENTITY = make_test_a2a_identity() @pytest.mark.asyncio @@ -51,9 +37,9 @@ async def test_nl_product_query_calls_resolve_identity_once(): handler._get_auth_token = MagicMock(return_value="test-token") ctx = make_a2a_context(auth_token="test-token", headers={"host": "test.example.com"}) - params = _make_nl_message("Show me available products in the catalog") + params = make_nl_send_message_request("Show me available products in the catalog") - with patch("src.core.resolved_identity.resolve_identity", return_value=_MOCK_IDENTITY) as mock_resolve: + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) as mock_resolve: with patch("src.a2a_server.adcp_a2a_server.core_get_products_tool") as mock_products: # core_get_products_tool returns a Pydantic GetProductsResponse; # NL _get_products iterates response.products so the mock must @@ -79,9 +65,9 @@ async def test_nl_pricing_query_calls_resolve_identity_once(): handler._get_auth_token = MagicMock(return_value="test-token") ctx = make_a2a_context(auth_token="test-token", headers={"host": "test.example.com"}) - params = _make_nl_message("What is the pricing for CPM ads?") + params = make_nl_send_message_request("What is the pricing for CPM ads?") - with patch("src.core.resolved_identity.resolve_identity", return_value=_MOCK_IDENTITY) as mock_resolve: + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) as mock_resolve: with patch("src.a2a_server.adcp_a2a_server.core_get_products_tool") as mock_products: # Return a dict to bypass model_dump() path mock_products.return_value = {"products": [], "message": "No products found"} @@ -104,9 +90,9 @@ async def test_nl_targeting_query_calls_resolve_identity_once(): handler._get_auth_token = MagicMock(return_value="test-token") ctx = make_a2a_context(auth_token="test-token", headers={"host": "test.example.com"}) - params = _make_nl_message("Show me audience targeting options") + params = make_nl_send_message_request("Show me audience targeting options") - with patch("src.core.resolved_identity.resolve_identity", return_value=_MOCK_IDENTITY) as mock_resolve: + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) as mock_resolve: # Mock the core capabilities function (not the handler — to expose both calls) with patch("src.core.tools.capabilities.get_adcp_capabilities_raw") as mock_caps: mock_caps.return_value = {"protocols": [], "targeting": {}} @@ -119,7 +105,7 @@ async def test_nl_targeting_query_calls_resolve_identity_once(): @pytest.mark.asyncio -async def test_nl_media_buy_raises_capability_not_supported(): +async def test_nl_media_buy_returns_failed_task_with_envelope(): """NL media buy is not supported — invocation must surface a typed AdCPError. Pre-fix the NL stub returned ``{"success": False, "message": "use explicit"}`` @@ -127,32 +113,38 @@ async def test_nl_media_buy_raises_capability_not_supported(): parsed the artifact as ``MCP_ERROR``. The handler now raises ``AdCPCapabilityNotSupportedError`` which propagates to the outer ``on_message_send`` error handler that attaches a spec-compliant - envelope to the failed Task artifact. + envelope to the failed Task artifact and RETURNS the failed Task + (per AdCP 3.1.x transport-errors.mdx "Layer Separation" — JSON-RPC + errors are reserved for transport faults, never application failures). Pin: identity resolution still runs once (the route dispatch happens before ``_create_media_buy`` raises), and the failed Task must surface - a wire envelope (not a fake-success dict). + a wire envelope (not a fake-success dict, not a raised InternalError). """ + from a2a.types import TaskState + + from tests.helpers import assert_envelope_shape + handler = AdCPRequestHandler() handler._get_auth_token = MagicMock(return_value="test-token") ctx = make_a2a_context(auth_token="test-token", headers={"host": "test.example.com"}) - params = _make_nl_message("Create a campaign for Nike") + params = make_nl_send_message_request("Create a campaign for Nike") - with patch("src.core.resolved_identity.resolve_identity", return_value=_MOCK_IDENTITY) as mock_resolve: - # NL media buy raises AdCPCapabilityNotSupportedError; outer - # on_message_send catches and surfaces it as InternalError after - # attaching the envelope to the failed Task artifact. - from a2a.utils.errors import InternalError - - with pytest.raises(InternalError) as exc_info: - await handler.on_message_send(params, context=ctx) + with patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) as mock_resolve: + task = await handler.on_message_send(params, context=ctx) # Identity is resolved once during route dispatch before the raise. assert mock_resolve.call_count == 1, ( f"resolve_identity called {mock_resolve.call_count} times for media buy NL request. Expected 1." ) - # InternalError message names the original capability failure (sanity check). - assert "create_media_buy" in str(exc_info.value).lower() or "explicit" in str(exc_info.value).lower(), ( - f"InternalError should reference the unsupported capability; got: {exc_info.value}" + assert task.status.state == TaskState.TASK_STATE_FAILED, f"Expected failed Task, got state {task.status.state!r}" + envelope = extract_processing_error_envelope(task) + # AdCPCapabilityNotSupportedError → UNSUPPORTED_FEATURE (correctable — + # matches AdCP error-code.json enumMetadata). + assert_envelope_shape( + envelope, + "UNSUPPORTED_FEATURE", + recovery="correctable", + message_substr="create_media_buy", ) diff --git a/tests/unit/test_a2a_transport_contract.py b/tests/unit/test_a2a_transport_contract.py index bce816b342..cfb9ede921 100644 --- a/tests/unit/test_a2a_transport_contract.py +++ b/tests/unit/test_a2a_transport_contract.py @@ -14,46 +14,115 @@ import json import uuid -from unittest.mock import patch +from contextlib import nullcontext +from unittest.mock import ANY, patch import pytest from starlette.testclient import TestClient +from src.a2a_server.adcp_a2a_server import DISCOVERY_SKILLS as _PROD_DISCOVERY_SKILLS +from src.a2a_server.adcp_a2a_server import AdCPRequestHandler from src.app import app -from tests.factories.principal import PrincipalFactory - -_MOCK_IDENTITY = PrincipalFactory.make_identity( - principal_id="test-principal", - tenant_id="test-tenant", - tenant={"tenant_id": "test-tenant"}, - protocol="a2a", -) +from src.core.auth_policy import AUTH_OPTIONAL_SKILLS +from src.core.exceptions import AdCPAuthenticationError +from src.core.mcp_auth_middleware import AUTH_OPTIONAL_TOOLS +from tests.helpers import assert_envelope_shape +from tests.helpers.pinned_schema import pinned_error_code_suggestion +from tests.utils.a2a_helpers import make_test_a2a_identity + +_TEST_IDENTITY = make_test_a2a_identity() +_AUTH_MISSING_SUGGESTION = pinned_error_code_suggestion("AUTH_MISSING") +_AUTH_INVALID_SUGGESTION = pinned_error_code_suggestion("AUTH_INVALID") + +# Task-management dispatch is selected by METHOD NAME, not by the version header: the app +# builds its A2A routes with ``enable_v0_3_compat=True`` (src/app.py), so the v0.3 names +# reach ``a2a/compat/v0_3/jsonrpc_adapter.py``. That adapter's ``handle_request`` has no +# ``except A2AError`` arm — only ``except Exception -> CoreInternalError(message=str(e))``, +# which takes no ``data``. So a raised ``InternalError(message=..., data=envelope)`` is +# REBUILT without its envelope on that path. +# +# Both halves are graded because the v1.0 rows alone cannot see the gap, and the installed +# adcp client emits the v0.3 names. Observed at this head, auth rejection on each: +# GetTask v1.0 -> code -32600, data = two-layer envelope +# tasks/get v0.3 -> code -32603, data = null +# CancelTask v1.0 -> code -32600, data = two-layer envelope +# tasks/cancel v0.3 -> code -32603, data = null +# Tracked as #1670. Raising the typed error is still correct — it is what will surface the +# envelope once the compat adapter maps A2AError — so the fix is upstream, not here. +_TASK_METHOD_DISPATCH = [ + pytest.param("GetTask", "1.0", True, id="GetTask-v1.0"), + pytest.param("CancelTask", "1.0", True, id="CancelTask-v1.0"), + pytest.param("tasks/get", "0.3", False, id="tasks-get-v0.3-envelope-dropped"), + pytest.param("tasks/cancel", "0.3", False, id="tasks-cancel-v0.3-envelope-dropped"), +] # --------------------------------------------------------------------------- -# All 13 A2A skills from the dispatch map (adcp_a2a_server.py:1416-1438) +# Explicit per-skill contract. Every registered skill MUST have an entry here +# (asserted), and each entry is INDEPENDENTLY authored — NOT derived from the +# registry — so the checks are not tautological: a new dispatch entry can't pass +# without a human classifying it, and a skill routed to the wrong handler is +# caught by the per-skill wire assertion. +# classification: "implemented" (must NOT return UNSUPPORTED_FEATURE) or +# "unsupported" (must return a UNSUPPORTED_FEATURE failed Task) +# advertised: whether the agent card advertises it (asserted for exact equality) +# discovery: whether the skill is auth-OPTIONAL (no principal required); HAND-AUTHORED +# here and asserted for exact equality against production's DISCOVERY_SKILLS, +# so a skill wrongly flipped into/out of the discovery set in production +# reddens the build instead of silently re-partitioning the test. +# params: request params that reach the skill's terminal branch # --------------------------------------------------------------------------- -ALL_SKILLS = [ - "get_adcp_capabilities", - "get_products", - "create_media_buy", - "list_creative_formats", - "list_authorized_properties", - "update_media_buy", - "get_media_buy_delivery", - "update_performance_index", - "sync_creatives", - "list_creatives", - "approve_creative", - "get_media_buy_status", - "optimize_media_buy", -] - -DISCOVERY_SKILLS = [ - "get_adcp_capabilities", - "list_creative_formats", - "list_authorized_properties", - "get_products", -] +SKILL_METADATA: dict[str, dict] = { + "get_adcp_capabilities": {"classification": "implemented", "advertised": True, "discovery": True, "params": {}}, + "get_products": {"classification": "implemented", "advertised": True, "discovery": True, "params": {}}, + "create_media_buy": {"classification": "implemented", "advertised": True, "discovery": False, "params": {}}, + "list_creative_formats": {"classification": "implemented", "advertised": True, "discovery": True, "params": {}}, + "list_accounts": {"classification": "implemented", "advertised": True, "discovery": False, "params": {}}, + "sync_accounts": {"classification": "implemented", "advertised": True, "discovery": False, "params": {}}, + "list_authorized_properties": { + "classification": "implemented", + "advertised": True, + "discovery": True, + "params": {}, + }, + "update_media_buy": {"classification": "implemented", "advertised": True, "discovery": False, "params": {}}, + "get_media_buys": {"classification": "implemented", "advertised": True, "discovery": False, "params": {}}, + "get_media_buy_delivery": {"classification": "implemented", "advertised": True, "discovery": False, "params": {}}, + "update_performance_index": { + "classification": "implemented", + "advertised": True, + "discovery": False, + "params": {}, + }, + "sync_creatives": {"classification": "implemented", "advertised": True, "discovery": False, "params": {}}, + "list_creatives": {"classification": "implemented", "advertised": True, "discovery": False, "params": {}}, + # Unsupported + NOT advertised: handlers raise UNSUPPORTED_FEATURE, so they + # are hidden from the agent card but stay reachable-but-unsupported by name. + "approve_creative": {"classification": "unsupported", "advertised": False, "discovery": False, "params": {}}, + "get_media_buy_status": {"classification": "unsupported", "advertised": False, "discovery": False, "params": {}}, + "optimize_media_buy": {"classification": "unsupported", "advertised": False, "discovery": False, "params": {}}, + "create_creative": { + "classification": "unsupported", + "advertised": False, + "discovery": False, + "params": {"format_id": "display_300x250", "content_uri": "https://ex/c.jpg", "name": "c"}, + }, + "assign_creative": { + "classification": "unsupported", + "advertised": False, + "discovery": False, + "params": {"media_buy_id": "mb-1", "package_id": "pkg-1", "creative_id": "cr-1"}, + }, +} + +ALL_SKILLS = sorted(AdCPRequestHandler()._skill_handler_map().keys()) +IMPLEMENTED_SKILLS = sorted(s for s, m in SKILL_METADATA.items() if m["classification"] == "implemented") +UNSUPPORTED_SKILLS = sorted(s for s, m in SKILL_METADATA.items() if m["classification"] == "unsupported") +ADVERTISED_SKILLS = {s for s, m in SKILL_METADATA.items() if m["advertised"]} + +# Discovery (no-auth) skills come from the HAND-AUTHORED oracle above (not the production +# frozenset), so the auth-boundary tests can't move in lockstep with a production mis-classification. +# ``test_discovery_metadata_matches_production`` pins this set equal to production's DISCOVERY_SKILLS. +DISCOVERY_SKILLS = sorted(s for s, m in SKILL_METADATA.items() if m["discovery"]) AUTH_REQUIRED_SKILLS = [s for s in ALL_SKILLS if s not in DISCOVERY_SKILLS] @@ -204,6 +273,202 @@ def test_auth_required_skills_reject_no_auth(self, client, no_auth_headers, skil assert "auth" in error_msg or "token" in error_msg, ( f"Error for '{skill}' should mention auth/token: {body['error']['message']}" ) + assert_envelope_shape(body["error"]["data"], "AUTH_MISSING", recovery="correctable") + assert body["error"]["data"]["adcp_error"]["suggestion"] == _AUTH_MISSING_SUGGESTION + + @pytest.mark.parametrize( + ("headers", "resolver_error", "expected_code", "expected_recovery", "expected_suggestion"), + [ + ( + {"Content-Type": "application/json", "A2A-Version": "1.0"}, + None, + "AUTH_MISSING", + "correctable", + _AUTH_MISSING_SUGGESTION, + ), + ( + { + "Authorization": "Basic malformed", + "Content-Type": "application/json", + "A2A-Version": "1.0", + }, + None, + "AUTH_INVALID", + "terminal", + _AUTH_INVALID_SUGGESTION, + ), + ( + { + "Authorization": "Bearer ", + "Content-Type": "application/json", + "A2A-Version": "1.0", + }, + None, + "AUTH_INVALID", + "terminal", + _AUTH_INVALID_SUGGESTION, + ), + ( + { + "Authorization": "Bearer invalid-task-token", + "Content-Type": "application/json", + "A2A-Version": "1.0", + }, + "Authentication token is invalid or expired.", + "AUTH_INVALID", + "terminal", + _AUTH_INVALID_SUGGESTION, + ), + ], + ids=["missing-token", "malformed-authorization", "empty-bearer", "invalid-token"], + ) + @pytest.mark.parametrize(("method", "version", "envelope_survives"), _TASK_METHOD_DISPATCH) + def test_task_management_auth_errors_use_json_rpc_dispatcher( + self, + client, + method, + version, + envelope_survives, + headers, + resolver_error, + expected_code, + expected_recovery, + expected_suggestion, + ): + """The real dispatcher must serialize task auth failures as JSON-RPC errors, carrying the + full two-layer auth envelope in ``error.data`` on the v1.0 names — and NOT on their v0.3 + aliases, which is graded here rather than assumed. + + Drives the ACTUAL SDK dispatcher via a real HTTP POST (not a direct handler call), so this + catches regressions in dispatcher routing, request parsing, and response serialization that + a unit test calling the handler method directly cannot see. + + The invalid-token case patches ``resolve_identity`` at its SOURCE module (not + ``_resolve_a2a_identity`` itself) so the REAL ``_resolve_a2a_identity`` exception + handling — and its own enveloping via ``_enveloped_auth_error`` — actually runs. An + earlier version of this test patched ``_resolve_a2a_identity`` with a bare + ``InvalidRequestError`` side effect, which bypassed that enveloping entirely and made + the invalid-token case silently untested for ``error.data``. + """ + headers = {**headers, "A2A-Version": version} + payload = {"jsonrpc": "2.0", "id": "task-auth-request", "method": method, "params": {"id": "task_auth"}} + resolver_patch = ( + patch( + "src.core.resolved_identity.resolve_identity", + side_effect=AdCPAuthenticationError(resolver_error), + ) + if resolver_error + else nullcontext() + ) + + with resolver_patch as mock_resolve: + response = client.post("/a2a", json=payload, headers=headers) + + if resolver_error: + assert mock_resolve is not None + assert len(mock_resolve.call_args_list) == 1 + resolve_call = mock_resolve.call_args_list[0] + assert resolve_call.kwargs["auth_token"] == "invalid-task-token" + assert resolve_call.kwargs["require_valid_token"] is True + assert resolve_call.kwargs["protocol"] == "a2a" + body = response.json() + assert body["jsonrpc"] == "2.0" + assert body["id"] == "task-auth-request" + assert "result" not in body + # Holds on BOTH paths: the message is the sanitized text and no task id rides along, + # so the compat flattening costs the machine-readable code, never disclosure. + assert "auth" in body["error"]["message"].lower() + assert "task_auth" not in json.dumps(body) + + if not envelope_survives: + # v0.3 compat path (#1670): the adapter's bare `except Exception` rebuilds the error + # as CoreInternalError(message=str(e)), so the code becomes -32603 and `data` is gone. + # Asserted rather than skipped, so the day #1670 restores the mapping this row goes + # red and forces `_internal_error_for`'s docstring to be corrected with it. + assert body["error"]["code"] == -32603 + assert body["error"].get("data") is None, ( + f"{method} now carries error.data — the v0.3 compat adapter gained an A2AError " + f"mapping. Update this table and _internal_error_for's docstring together (#1670)." + ) + return + + assert body["error"]["code"] == -32600 + # The two-layer envelope must ALSO reach the real wire, not just a bare JSON-RPC message — + # a buyer branches on error.data.adcp_error.code, and this is what previously required a + # separate unit test calling the handler directly (which cannot prove the real dispatcher + # actually places the envelope in the serialized HTTP response body). + assert_envelope_shape(body["error"]["data"], expected_code, recovery=expected_recovery) + adcp_error = body["error"]["data"]["adcp_error"] + assert adcp_error["suggestion"] == expected_suggestion + assert body["error"]["message"] == adcp_error["message"] + + @pytest.mark.parametrize("skill", ["create_media_buy", "list_accounts"]) + @pytest.mark.parametrize("authorization", ["Basic malformed", "Bearer "], ids=["basic", "empty-bearer"]) + def test_non_discovery_skill_rejects_presented_unusable_credentials(self, client, authorization, skill): + """The message/send auth guard classifies malformed presented credentials as AUTH_INVALID.""" + response = client.post( + "/a2a", + json=_build_jsonrpc(skill), + headers={ + "Authorization": authorization, + "Content-Type": "application/json", + "A2A-Version": "1.0", + }, + ) + + body = response.json() + assert body["error"]["code"] == -32600 + assert_envelope_shape(body["error"]["data"], "AUTH_INVALID", recovery="terminal") + assert body["error"]["data"]["adcp_error"]["suggestion"] == _AUTH_INVALID_SUGGESTION + + @patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) + def test_x_adcp_auth_precedes_malformed_authorization(self, mock_resolve, client): + """The A2A middleware resolves the x-adcp-auth credential when both headers are present.""" + response = client.post( + "/a2a", + json=_build_jsonrpc("create_media_buy"), + headers={ + "x-adcp-auth": "valid-x-adcp-token", + "Authorization": "Basic malformed", + "Content-Type": "application/json", + "A2A-Version": "1.0", + }, + ) + + assert response.json().get("result") is not None + mock_resolve.assert_called_once_with( + headers=ANY, + auth_token="valid-x-adcp-token", + require_valid_token=True, + protocol="a2a", + testing_context=ANY, + ) + + @patch("src.core.resolved_identity.resolve_identity") + @pytest.mark.parametrize("skill", ["create_media_buy", "list_accounts"]) + def test_invalid_x_adcp_auth_does_not_fall_back_to_valid_bearer(self, mock_resolve, client, skill): + """A rejected x-adcp-auth credential cannot be bypassed by a valid-looking Bearer token.""" + mock_resolve.side_effect = AdCPAuthenticationError("Authentication token is invalid or expired.") + response = client.post( + "/a2a", + json=_build_jsonrpc(skill), + headers={ + "x-adcp-auth": "rejected-x-adcp-token", + "Authorization": "Bearer valid-looking-fallback", + "Content-Type": "application/json", + "A2A-Version": "1.0", + }, + ) + + body = response.json() + assert body["error"]["code"] == -32600 + assert_envelope_shape(body["error"]["data"], "AUTH_INVALID", recovery="terminal") + assert body["error"]["data"]["adcp_error"]["suggestion"] == _AUTH_INVALID_SUGGESTION + calls = mock_resolve.call_args_list + assert len(calls) == 1 + assert calls[0].kwargs["require_valid_token"] is True + assert calls[0].kwargs["auth_token"] == "rejected-x-adcp-token" + assert calls[0].kwargs["protocol"] == "a2a" # --------------------------------------------------------------------------- @@ -221,12 +486,31 @@ def test_invalid_method_returns_error(self, client, auth_headers): body = response.json() assert "error" in body, "Unknown method should return JSON-RPC error" - def test_unknown_skill_returns_error(self, client, auth_headers): - """Unknown skill name should return error (not crash).""" - payload = _build_jsonrpc("nonexistent_skill", {}) + @patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) + def test_unknown_skill_returns_failed_task_not_transport_error(self, mock_resolve, client, auth_headers): + """Unknown skill name returns a failed Task with UNSUPPORTED_FEATURE, not JSON-RPC. + + The JSON-RPC method (message/send) is valid; routing failed *inside* + skill dispatch, which is an application-layer failure. Per AdCP + 3.1.1 transport-errors.mdx "Layer Separation" it belongs in the + task body as a failed Task carrying a two-layer envelope — JSON-RPC + MethodNotFoundError is reserved for unknown JSON-RPC *methods* + (see test_invalid_method_returns_error). Identity is mocked so the + request reaches skill dispatch. + """ + buyer_controlled_skill = "Bearer_secret_hunter2" + payload = _build_jsonrpc(buyer_controlled_skill, {}) response = client.post("/a2a", json=payload, headers=auth_headers) body = response.json() - assert "error" in body, "Unknown skill should return JSON-RPC error" + + assert "error" not in body, f"unknown skill must not be a JSON-RPC error: {body.get('error')}" + assert "result" in body, f"expected a failed-Task result, got: {json.dumps(body)[:400]}" + data = _extract_artifact_data(body["result"]) + assert_envelope_shape(data, "UNSUPPORTED_FEATURE", recovery="correctable") + assert data["errors"][0]["message"] == ( + "The requested skill is not supported. Call discovery to list available skills." + ) + assert buyer_controlled_skill not in json.dumps(body) def test_response_echoes_request_id(self, client, auth_headers): """JSON-RPC response must echo the request id.""" @@ -267,7 +551,7 @@ class TestA2AResponseShape: testing the full transport chain: middleware → dispatch → serialization. """ - @patch("src.core.resolved_identity.resolve_identity", return_value=_MOCK_IDENTITY) + @patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) @patch("src.core.tools.products._get_products_impl") def test_get_products_response_shape(self, mock_impl, mock_resolve, client, auth_headers): """get_products response must contain 'products' list.""" @@ -286,7 +570,7 @@ def test_get_products_response_shape(self, mock_impl, mock_resolve, client, auth assert "products" in data, "get_products response must have 'products' field" assert isinstance(data["products"], list) - @patch("src.core.resolved_identity.resolve_identity", return_value=_MOCK_IDENTITY) + @patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) @patch("src.core.tools.media_buy_create._create_media_buy_impl") def test_create_media_buy_response_shape(self, mock_impl, mock_resolve, client, auth_headers): """create_media_buy response must have media_buy_id.""" @@ -331,7 +615,7 @@ def test_error_format_is_jsonrpc(self, client, auth_headers): assert "code" in body["error"], "JSON-RPC error must have 'code'" assert "message" in body["error"], "JSON-RPC error must have 'message'" - @patch("src.core.resolved_identity.resolve_identity", return_value=_MOCK_IDENTITY) + @patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) @patch("src.a2a_server.adcp_a2a_server.core_sync_creatives_tool") def test_sync_creatives_response_shape(self, mock_impl, mock_resolve, client, auth_headers): """sync_creatives response must contain 'creatives' or 'synced_creatives'.""" @@ -349,7 +633,7 @@ def test_sync_creatives_response_shape(self, mock_impl, mock_resolve, client, au "sync_creatives response must have 'creatives' field" ) - @patch("src.core.resolved_identity.resolve_identity", return_value=_MOCK_IDENTITY) + @patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) @patch("src.a2a_server.adcp_a2a_server.core_list_creatives_tool") def test_list_creatives_response_shape(self, mock_impl, mock_resolve, client, auth_headers): """list_creatives response must contain 'creatives' list.""" @@ -371,7 +655,7 @@ def test_list_creatives_response_shape(self, mock_impl, mock_resolve, client, au assert "creatives" in data, "list_creatives response must have 'creatives' field" assert isinstance(data["creatives"], list) - @patch("src.core.resolved_identity.resolve_identity", return_value=_MOCK_IDENTITY) + @patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) @patch("src.a2a_server.adcp_a2a_server.core_update_media_buy_tool") def test_update_media_buy_response_shape(self, mock_impl, mock_resolve, client, auth_headers): """update_media_buy response must have media_buy_id.""" @@ -393,7 +677,7 @@ def test_update_media_buy_response_shape(self, mock_impl, mock_resolve, client, data = _extract_artifact_data(body["result"]) assert "media_buy_id" in data, "update_media_buy response must have 'media_buy_id'" - @patch("src.core.resolved_identity.resolve_identity", return_value=_MOCK_IDENTITY) + @patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) @patch("src.a2a_server.adcp_a2a_server.core_get_media_buy_delivery_tool") def test_get_media_buy_delivery_response_shape(self, mock_impl, mock_resolve, client, auth_headers): """get_media_buy_delivery response must have 'deliveries' or 'media_buys'.""" @@ -416,7 +700,7 @@ def test_get_media_buy_delivery_response_shape(self, mock_impl, mock_resolve, cl "get_media_buy_delivery response must have 'media_buy_deliveries' field" ) - @patch("src.core.resolved_identity.resolve_identity", return_value=_MOCK_IDENTITY) + @patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) @patch("src.a2a_server.adcp_a2a_server.core_update_performance_index_tool") def test_update_performance_index_response_shape(self, mock_impl, mock_resolve, client, auth_headers): """update_performance_index response must have acknowledgment fields.""" @@ -447,19 +731,94 @@ def test_update_performance_index_response_shape(self, mock_impl, mock_resolve, class TestA2AStubHandlers: - """Verify stub handlers return JSON-RPC responses (not crashes).""" + """Unimplemented-but-registered skills surface UNSUPPORTED_FEATURE in the task body. + + Table-driven wire assertions across the dispatch registry: a recognized-but- + unimplemented skill is an application-layer failure, so it must return a + failed Task carrying a two-layer ``UNSUPPORTED_FEATURE``/``correctable`` + envelope — NOT a JSON-RPC ``UnsupportedOperationError`` (-32004). Reserving + JSON-RPC for transport faults is the AdCP 3.1.1 "Layer Separation" + contract; direct calls to a recognized stub must get a structured, + recoverable AdCP error rather than a transport exception even though the + unsupported skill is intentionally omitted from the agent card. + """ - STUB_SKILLS = ["approve_creative", "get_media_buy_status", "optimize_media_buy"] + @pytest.mark.parametrize("skill", UNSUPPORTED_SKILLS) + @patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) + def test_unsupported_skill_returns_failed_task_not_transport_error(self, mock_resolve, client, auth_headers, skill): + """Each unsupported skill returns a failed Task with UNSUPPORTED_FEATURE, not JSON-RPC.""" + payload = _build_jsonrpc(skill, SKILL_METADATA[skill]["params"]) + response = client.post("/a2a", json=payload, headers=auth_headers) + body = response.json() - @pytest.mark.parametrize("skill", STUB_SKILLS) - def test_stub_handler_returns_jsonrpc_response(self, client, auth_headers, skill): - """Stub handlers must return valid JSON-RPC (result or error), not crash.""" + assert "error" not in body, f"'{skill}' must not be a JSON-RPC error: {body.get('error')}" + assert "result" in body, f"'{skill}' expected a failed-Task result, got: {json.dumps(body)[:400]}" + data = _extract_artifact_data(body["result"]) + assert data.get("adcp_error", {}).get("code") == "UNSUPPORTED_FEATURE", ( + f"'{skill}' must surface UNSUPPORTED_FEATURE in the task body: {data}" + ) + assert data.get("adcp_error", {}).get("recovery") == "correctable", f"'{skill}': {data}" + + @pytest.mark.parametrize("skill", IMPLEMENTED_SKILLS) + @patch("src.core.resolved_identity.resolve_identity", return_value=_TEST_IDENTITY) + def test_implemented_skill_does_not_return_unsupported_feature(self, mock_resolve, client, auth_headers, skill): + """A skill classified 'implemented' must NOT surface UNSUPPORTED_FEATURE. + + This is the non-tautological half: a skill mis-routed to an unsupported + handler would return a UNSUPPORTED_FEATURE failed + Task and fail here, even without a DB (empty params yield VALIDATION_ERROR or + a JSON-RPC error, never UNSUPPORTED_FEATURE, for a genuinely-implemented skill). + """ payload = _build_jsonrpc(skill, {}) response = client.post("/a2a", json=payload, headers=auth_headers) body = response.json() + # An implemented skill with empty params yields a result Task (the skill ran and + # returned VALIDATION_ERROR, never UNSUPPORTED_FEATURE). A JSON-RPC "error" body + # here would mean the skill never reached its handler — assert the shape rather + # than silently skipping, so a routing regression can't pass by changing the shape. + assert "result" in body, f"'{skill}' produced a JSON-RPC error, not a result Task: {body}" + data = _extract_artifact_data(body["result"]) + assert data.get("adcp_error", {}).get("code") != "UNSUPPORTED_FEATURE", ( + f"'{skill}' is classified implemented but routed to an unsupported handler: {data}" + ) + + +class TestA2ARegistryContract: + """Explicit skill metadata ↔ production registry & agent card (non-tautological).""" + + def test_metadata_covers_exactly_the_production_registry(self): + """SKILL_METADATA must be a bijection with the production registry. + + Both sides are independently authored (the metadata is NOT derived from the + registry), so a skill added to ``_skill_handler_map`` without a metadata entry + — or a stale metadata entry — fails here. Combined with the per-skill wire + assertions (implemented ≠ UNSUPPORTED_FEATURE, unsupported = UNSUPPORTED_FEATURE), + a mis-classified or mis-routed skill can no longer pass silently. + """ + registry = set(AdCPRequestHandler()._skill_handler_map()) + assert set(SKILL_METADATA) == registry, ( + f"metadata↔registry drift — missing: {registry - set(SKILL_METADATA)}, " + f"stale: {set(SKILL_METADATA) - registry}" + ) - assert "result" in body or "error" in body, f"Stub skill '{skill}' must return JSON-RPC result or error" - assert body.get("jsonrpc") == "2.0" + def test_discovery_metadata_matches_production(self): + """The HAND-AUTHORED ``discovery`` flags must equal production's + ``DISCOVERY_SKILLS`` frozenset. The auth-boundary tests derive their partitions from the + oracle, so without this pin they would move in lockstep with production and a skill + wrongly flipped into (or out of) the no-auth discovery set would still pass. Combined with + the metadata↔registry bijection above (which forces every skill to carry a ``discovery`` + bool), a production classification change reddens here. + """ + hand_authored = {s for s, m in SKILL_METADATA.items() if m["discovery"]} + assert hand_authored == set(_PROD_DISCOVERY_SKILLS), ( + f"discovery classification drift — production-only: {set(_PROD_DISCOVERY_SKILLS) - hand_authored}, " + f"oracle-only: {hand_authored - set(_PROD_DISCOVERY_SKILLS)}" + ) + + def test_transports_share_the_canonical_auth_optional_policy(self): + """A2A and MCP must import, not copy, the transport-neutral auth policy.""" + assert _PROD_DISCOVERY_SKILLS is AUTH_OPTIONAL_SKILLS + assert AUTH_OPTIONAL_TOOLS is AUTH_OPTIONAL_SKILLS # --------------------------------------------------------------------------- @@ -468,7 +827,7 @@ def test_stub_handler_returns_jsonrpc_response(self, client, auth_headers, skill class TestA2AAllSkillsDispatch: - """Verify all 13 skills are reachable through the transport layer.""" + """Verify every registered skill (ALL_SKILLS, derived from the production registry) is reachable.""" @pytest.mark.parametrize("skill", ALL_SKILLS) def test_skill_dispatches_not_404(self, client, auth_headers, skill): @@ -504,14 +863,23 @@ def test_all_skills_return_valid_jsonrpc(self, client, auth_headers, skill): class TestAgentCardContract: """Verify agent card advertises all skills and has required structure.""" - def test_agent_card_skills_match_dispatch(self, client): - """Agent card must advertise at least the skills in the dispatch map.""" + def test_agent_card_advertises_exactly_the_metadata_advertised_set(self, client): + """The agent card's advertised skills must EXACTLY equal ``ADVERTISED_SKILLS``. + + Exact set equality (not ``⊇``) catches both a dispatchable skill that stops + being advertised and an arbitrary extra skill advertised by accident, + because the expected set is the independently-authored + metadata, not something derived from the card itself. + """ response = client.get("/.well-known/agent-card.json") card = response.json() advertised_skills = {s["name"] for s in card.get("skills", [])} - for skill in ALL_SKILLS: - assert skill in advertised_skills, f"Skill '{skill}' in dispatch map but not advertised in agent card" + assert advertised_skills == ADVERTISED_SKILLS, ( + f"agent card advertised set drifted from SKILL_METADATA — " + f"unexpected: {sorted(advertised_skills - ADVERTISED_SKILLS)}, " + f"missing: {sorted(ADVERTISED_SKILLS - advertised_skills)}" + ) def test_agent_card_url_no_trailing_slash(self, client): """Agent card URL must not have trailing slash (causes redirects).""" @@ -527,3 +895,349 @@ def test_agent_card_has_adcp_extension(self, client): extensions = card.get("capabilities", {}).get("extensions", []) adcp_uris = [e.get("uri", "") for e in extensions] assert any("adcp-extension" in uri for uri in adcp_uris), "Agent card must have AdCP extension in capabilities" + + +class TestEnvelopeFreeProtocolRaises: + """The envelope-free JSON-RPC raises stay enumerable, not just described. + + ``_enveloped_invalid_request``'s docstring enumerates every raise in the A2A module + that deliberately ships WITHOUT the two-layer envelope, because each signals a + transport-protocol condition with no AdCP wire code. An enumeration in prose drifts + the moment someone adds a raise — an earlier version named 7 of the 12 and read as + complete, which is what made a reviewer check by hand. + """ + + # Type -> count, mirroring the docstring. Update BOTH together, deliberately: adding a + # protocol raise is a decision about whether the buyer gets an AdCP code, not a detail. + _EXPECTED_ENVELOPE_FREE_RAISES = { + "InvalidParamsError": 3, + "TaskNotCancelableError": 3, + "TaskNotFoundError": 4, + "UnsupportedOperationError": 3, + } + + @staticmethod + def _raise_counts() -> dict[str, int]: + """Count `raise (...)` per type in the A2A server module.""" + import ast + from pathlib import Path + + src = Path(__file__).resolve().parents[2] / "src" / "a2a_server" / "adcp_a2a_server.py" + counts: dict[str, int] = {} + for node in ast.walk(ast.parse(src.read_text())): + if not isinstance(node, ast.Raise) or node.exc is None: + continue + exc = node.exc.func if isinstance(node.exc, ast.Call) else node.exc + name = exc.id if isinstance(exc, ast.Name) else (exc.attr if isinstance(exc, ast.Attribute) else None) + if name in TestEnvelopeFreeProtocolRaises._EXPECTED_ENVELOPE_FREE_RAISES: + counts[name] = counts.get(name, 0) + 1 + return counts + + def test_docstring_enumeration_matches_the_code(self): + assert self._raise_counts() == self._EXPECTED_ENVELOPE_FREE_RAISES, ( + "The envelope-free protocol raises changed. Update BOTH this table and the " + "enumeration in _enveloped_invalid_request's docstring — and decide whether the " + "new raise should carry an AdCP envelope instead of being protocol-native." + ) + + def test_detector_actually_counts(self): + """The count must come from the code, not from the expectation it is compared to.""" + counts = self._raise_counts() + assert sum(counts.values()) == 13 + assert set(counts) == set(self._EXPECTED_ENVELOPE_FREE_RAISES), ( + "a declared type vanished from the module entirely — the equality above would " + "still fail, but this states which half moved" + ) + + +class TestAsyncTaskSkillsThreadTheOuterTaskId: + """Which async skills carry the buyer's outer task id down to the workflow step. + + Two sets, deliberately different, one derived from the other: + + * ``_ASYNC_TASK_SKILLS`` — can answer non-terminally, so they get the + push-notification config injected. + * ``_TASK_ID_BEARING_SKILLS`` — additionally persist the outer ``task_*`` id on the + durable step, so ``tasks/get`` reconciles against it, ``tasks/cancel`` resolves it, + and ``resolve_webhook_task_id`` keys the completion webhook on it. + + ``sync_creatives`` is in the first and NOT the second, and that asymmetry is the + contract these tests pin. It creates one workflow step PER CREATIVE, so a single + outer id stamped across all of them resolves to an arbitrary one of N: cancel would + report CANCELED while the other N-1 kept running and later fired their own webhooks. + + Signature-and-set pins rather than wire tests on purpose — the defect they guard is a + membership edit made without confronting how many steps the skill creates. + """ + + def test_every_task_id_bearing_skill_handler_accepts_the_outer_task_id(self): + import inspect + + from src.a2a_server.adcp_a2a_server import _TASK_ID_BEARING_SKILLS, AdCPRequestHandler + + handler_map = AdCPRequestHandler._skill_handler_map(AdCPRequestHandler) + missing = [] + for skill in sorted(_TASK_ID_BEARING_SKILLS): + assert skill in handler_map, f"{skill} is in _TASK_ID_BEARING_SKILLS but has no handler" + params = inspect.signature(handler_map[skill]).parameters + if "a2a_task_id" not in params: + missing.append(skill) + + assert not missing, ( + f"{missing} are declared task-id-bearing but their handlers do not accept " + "a2a_task_id, so the buyer's task id is never persisted on the workflow step — " + "tasks/cancel cannot resolve it and the completion webhook keys on step_id." + ) + + def test_sync_creatives_is_async_but_does_not_bear_the_outer_task_id(self): + """The asymmetry is the contract, and re-adding sync must be a deliberate act. + + ``sync_creatives`` gets the push-notification config (it is async) but must NOT + get the outer task id: ``_create_sync_workflow_steps`` creates one step per + creative, and ``WorkflowRepository.get_by_external_task_id`` returns ONE row for + the key. Stamping one id on N steps makes every reader — durable poll, cancel, + webhook correlation — act on an arbitrary one of them, so cancel answers CANCELED + while the remaining steps keep running. + + Pinned on BOTH the set and the handler signature: re-adding it requires editing + the set AND widening the handler, so neither half can drift back in on its own. + The honest behavior without the id is a ``TaskNotCancelableError`` refusal, graded + end-to-end by + ``tests/integration/test_a2a_skill_invocation.py::test_cancel_of_multi_creative_sync_task_refuses``. + """ + import inspect + + from src.a2a_server.adcp_a2a_server import _ASYNC_TASK_SKILLS, _TASK_ID_BEARING_SKILLS, AdCPRequestHandler + + assert "sync_creatives" in _ASYNC_TASK_SKILLS, "sync_creatives is async — it must still receive a push config" + assert "sync_creatives" not in _TASK_ID_BEARING_SKILLS, ( + "sync_creatives creates one workflow step per creative; a single outer task id " + "cannot name one of them. Address its steps by step_id instead." + ) + + handler = AdCPRequestHandler._skill_handler_map(AdCPRequestHandler)["sync_creatives"] + assert "a2a_task_id" not in inspect.signature(handler).parameters, ( + "the sync_creatives handler must not accept a2a_task_id — a parameter that is " + "never passed reads like working correlation" + ) + + def test_the_task_id_set_is_derived_from_the_async_set(self): + """One definition, not two literals that can drift. + + The task-id-bearing set is a proper subset of the async set, computed from it — + so a new async skill cannot silently appear in one and not the other without the + subtraction being edited on purpose. + """ + from src.a2a_server.adcp_a2a_server import _ASYNC_TASK_SKILLS, _TASK_ID_BEARING_SKILLS + + assert _TASK_ID_BEARING_SKILLS < _ASYNC_TASK_SKILLS, ( + "_TASK_ID_BEARING_SKILLS must be derived from _ASYNC_TASK_SKILLS, not maintained as an independent literal" + ) + # sync_creatives is the sole subtraction, for the N-steps-per-call reason above. + assert _ASYNC_TASK_SKILLS - _TASK_ID_BEARING_SKILLS == {"sync_creatives"} + + def test_the_set_names_every_skill_that_can_return_a_non_terminal_task(self): + """Membership pin: the three skills whose result can be ``submitted``. + + Derived from what each skill can RETURN, not from what the dispatch happens to + thread — create_media_buy and update_media_buy can answer with a submitted + result awaiting approval, and sync_creatives with creatives pending review. + A fourth async skill added without joining this set gets no push-notification + config, which is the drift this pins. + """ + from src.a2a_server.adcp_a2a_server import _ASYNC_TASK_SKILLS + + assert _ASYNC_TASK_SKILLS == {"create_media_buy", "sync_creatives", "update_media_buy"} + + +class TestA2ASkillParameterForwarding: + """The A2A skill handlers must forward the request-level parameters their + siblings do. + + MCP (``update_media_buy`` / ``create_media_buy``) and REST + (``PUT /media-buys/{id}`` / ``POST /media-buys``) both plumb + ``idempotency_key``, ``reporting_webhook`` and ``ext`` through to the shared + raw function. The A2A handlers silently dropped them, so the same buyer + payload was non-idempotent, had no reporting webhook and lost its extension + object on A2A alone — a divergence no schema check can see, because dropping a + keyword argument is not a type error. + + Driven through the REAL handler with the core tool spied, so removing any + forwarded keyword reddens these. + """ + + _WEBHOOK = { + "url": "https://buyer.example/reporting", + "reporting_frequency": "daily", + "authentication": { + "schemes": ["Bearer"], + "credentials": "reporting-webhook-credential-value", + }, + } + _EXT = {"vendor_trace_id": "trace-42"} + + @pytest.mark.asyncio + async def test_update_skill_forwards_idempotency_reporting_and_ext(self): + handler = AdCPRequestHandler() + identity = make_test_a2a_identity() + + with patch("src.a2a_server.adcp_a2a_server.core_update_media_buy_tool") as spy: + spy.return_value = {"ok": True} + await handler._handle_update_media_buy_skill( + { + "media_buy_id": "mb_1", + "paused": True, + "reporting_webhook": self._WEBHOOK, + "ext": self._EXT, + "idempotency_key": "idempotency-key-update-1", + }, + identity, + ) + + assert spy.call_count == 1, "the core update tool must be invoked exactly once" + forwarded = spy.call_args.kwargs + assert forwarded["idempotency_key"] == "idempotency-key-update-1" + assert forwarded["reporting_webhook"] == self._WEBHOOK + assert forwarded["ext"] == self._EXT + + @pytest.mark.asyncio + async def test_create_skill_forwards_idempotency_reporting_and_ext(self): + handler = AdCPRequestHandler() + identity = make_test_a2a_identity() + + with patch("src.a2a_server.adcp_a2a_server.core_create_media_buy_tool") as spy: + spy.return_value = {"ok": True} + await handler._handle_create_media_buy_skill( + { + "brand": {"domain": "forwarding.example"}, + "packages": [{"product_id": "prod_1", "budget": 5000.0, "pricing_option_id": "cpm_usd_fixed"}], + "start_time": "2030-01-01T00:00:00Z", + "end_time": "2030-01-08T00:00:00Z", + "reporting_webhook": self._WEBHOOK, + "ext": self._EXT, + "idempotency_key": "idempotency-key-create-1", + }, + identity, + ) + + assert spy.call_count == 1, "the core create tool must be invoked exactly once" + forwarded = spy.call_args.kwargs + assert forwarded["idempotency_key"] == "idempotency-key-create-1" + assert forwarded["reporting_webhook"] == self._WEBHOOK + assert forwarded["ext"] == self._EXT + + # Parameters the A2A handlers legitimately do NOT forward, each with the reason it is + # excluded. This is the ONLY hand-written list in the two tests below — the expected + # set itself is derived from the raw function's signature, so a NEW parameter added to + # update_media_buy_raw / create_media_buy_raw appears in the expected set automatically + # and reddens until it is either forwarded or consciously excluded here. Hand-listing + # the FORWARDED parameters is what let this gap survive two rounds of review. + _UPDATE_NOT_FORWARDED = { + # Transport-specific: the FastMCP Context belongs to the MCP wrapper. A2A resolves + # identity at its own boundary and passes `identity` instead. + "ctx": "MCP-only transport handle; A2A passes identity", + # Accepted by update_media_buy_raw's signature but dropped before + # _build_update_request, so forwarding would be a silent no-op. The REST route + # omits both for the same documented reason (#1417). + "targeting_overlay": "dead in update_media_buy_raw; REST omits it too (#1417)", + "creatives": "dead in update_media_buy_raw; REST omits it too (#1417)", + } + _CREATE_NOT_FORWARDED = { + "ctx": "MCP-only transport handle; A2A passes identity", + # Accepted for AdCP 3.1.1 request-shape compatibility but not honored by _impl; + # the REST route declares it and likewise does not forward it (#1619). + "paused": "pause-on-create not honored by _impl; REST omits it too (#1619)", + } + + @staticmethod + def _expected_forwarded(raw_fn, excluded: dict[str, str]) -> set[str]: + """Every parameter of ``raw_fn`` the A2A handler is obliged to forward. + + Derived from the live signature rather than transcribed, so the set cannot drift + away from the function it is meant to mirror. + """ + import inspect + + params = set(inspect.signature(raw_fn).parameters) + stale = excluded.keys() - params + assert not stale, f"exclusion list names parameters that no longer exist: {sorted(stale)}" + return params - excluded.keys() + + @pytest.mark.asyncio + async def test_update_skill_forwards_every_live_raw_parameter(self): + """No parameter of update_media_buy_raw may be silently dropped by the A2A handler.""" + from src.core.tools.media_buy_update import update_media_buy_raw + + handler = AdCPRequestHandler() + identity = make_test_a2a_identity() + + with patch("src.a2a_server.adcp_a2a_server.core_update_media_buy_tool") as spy: + spy.return_value = {"ok": True} + await handler._handle_update_media_buy_skill({"media_buy_id": "mb_1"}, identity) + + expected = self._expected_forwarded(update_media_buy_raw, self._UPDATE_NOT_FORWARDED) + missing = expected - set(spy.call_args.kwargs) + assert not missing, ( + f"A2A update handler drops {sorted(missing)}; forward them, or add each to " + "_UPDATE_NOT_FORWARDED with the reason it must not be forwarded" + ) + + @pytest.mark.asyncio + async def test_create_skill_forwards_every_live_raw_parameter(self): + """No parameter of create_media_buy_raw may be silently dropped by the A2A handler.""" + from src.core.tools.media_buy_create import create_media_buy_raw + + handler = AdCPRequestHandler() + identity = make_test_a2a_identity() + + with patch("src.a2a_server.adcp_a2a_server.core_create_media_buy_tool") as spy: + spy.return_value = {"ok": True} + await handler._handle_create_media_buy_skill( + { + "brand": {"domain": "forwarding.example"}, + "packages": [{"product_id": "prod_1", "budget": 5000.0, "pricing_option_id": "cpm_usd_fixed"}], + "start_time": "2030-01-01T00:00:00Z", + "end_time": "2030-01-08T00:00:00Z", + # Required by CreateMediaBuyRequest; the boundary rejects without it. + "idempotency_key": "idempotency-key-create-signature-1", + }, + identity, + ) + + expected = self._expected_forwarded(create_media_buy_raw, self._CREATE_NOT_FORWARDED) + missing = expected - set(spy.call_args.kwargs) + assert not missing, ( + f"A2A create handler drops {sorted(missing)}; forward them, or add each to " + "_CREATE_NOT_FORWARDED with the reason it must not be forwarded" + ) + + @pytest.mark.asyncio + async def test_update_skill_forwards_flight_and_economics_values(self): + """The newly-forwarded parameters must carry the buyer's VALUES, not just appear. + + A presence-only assertion passes on ``flight_start_date=None`` hardcoded at the + call site; these pin the actual payload through to the core tool. + """ + handler = AdCPRequestHandler() + identity = make_test_a2a_identity() + + with patch("src.a2a_server.adcp_a2a_server.core_update_media_buy_tool") as spy: + spy.return_value = {"ok": True} + await handler._handle_update_media_buy_skill( + { + "media_buy_id": "mb_1", + "flight_start_date": "2030-02-01", + "flight_end_date": "2030-02-28", + "currency": "EUR", + "pacing": "even", + "daily_budget": 250.0, + }, + identity, + ) + + forwarded = spy.call_args.kwargs + assert forwarded["flight_start_date"] == "2030-02-01" + assert forwarded["flight_end_date"] == "2030-02-28" + assert forwarded["currency"] == "EUR" + assert forwarded["pacing"] == "even" + assert forwarded["daily_budget"] == 250.0 diff --git a/tests/unit/test_admin_workflow_finalization.py b/tests/unit/test_admin_workflow_finalization.py new file mode 100644 index 0000000000..401c31cdd9 --- /dev/null +++ b/tests/unit/test_admin_workflow_finalization.py @@ -0,0 +1,1197 @@ +"""Approval finalization retries DB commits without repeating adapter work.""" + +import ast +import os +from contextlib import contextmanager +from datetime import UTC, date, datetime, timedelta +from pathlib import Path +from types import SimpleNamespace +from unittest.mock import ANY, Mock, patch + +import pytest +from sqlalchemy.exc import SQLAlchemyError + +from src.core.database.repositories.media_buy import ( + APPROVED_EXECUTION_SOURCE_STATUSES, + ApprovalTrigger, +) +from src.core.database.repositories.workflow import WorkflowRepository +from src.core.workflow_finalization import ( + ApprovalExecutionStatus, + ApprovalFinalization, + execute_and_finalize_media_buy_approval, + finalize_media_buy_approval_step, + media_buy_status_from_flight_dates, + prepare_media_buy_approval_execution, + reconcile_claimed_media_buy_approval_step, +) +from tests.factories import PrincipalFactory + +_TRANSITIONED = object() + + +class _WorkflowRepo: + def __init__(self, *, transition_result=_TRANSITIONED, existing=None) -> None: + self.transitions = 0 + self.transition_result = transition_result + self.existing = existing + + def transition_if_nonterminal(self, step_id, **kwargs): + self.transitions += 1 + return self.transition_result + + def get_by_step_id(self, step_id): + return self.existing + + def get_claimed_create_approval_step_for_media_buy(self, media_buy_id): + return self.existing + + +class _MediaBuyRepo: + def __init__(self, *, media_buy=None) -> None: + self.package_reads = 0 + self.media_buy = media_buy + + def get_packages(self, media_buy_id): + self.package_reads += 1 + return [] + + def update_status(self, media_buy_id, status): + raise AssertionError("success finalization must not mark the buy failed") + + def get_by_id(self, media_buy_id): + return self.media_buy + + +class _FailureMediaBuyRepo(_MediaBuyRepo): + def __init__(self, *, media_buy=None) -> None: + super().__init__(media_buy=media_buy) + self.status_updates = [] + self.unknown_updates = [] + self.expected_lease_versions = [] + + def update_status(self, media_buy_id, status): + self.status_updates.append((media_buy_id, status)) + + def mark_approved_execution_unknown(self, media_buy_id, *, expected_updated_at=None): + self.unknown_updates.append(media_buy_id) + self.expected_lease_versions.append(expected_updated_at) + return True + + +class _LostLeaseMediaBuyRepo(_FailureMediaBuyRepo): + def mark_approved_execution_unknown(self, media_buy_id, *, expected_updated_at=None): + self.unknown_updates.append(media_buy_id) + self.expected_lease_versions.append(expected_updated_at) + return False + + +class _ApprovalUoW: + def __init__( + self, + *, + fail_commit: bool, + workflows: _WorkflowRepo | None = None, + media_buys: _MediaBuyRepo | None = None, + ) -> None: + self.fail_commit = fail_commit + self.workflows = workflows or _WorkflowRepo() + self.media_buys = media_buys or _MediaBuyRepo() + + def __enter__(self): + return self + + def __exit__(self, exc_type, exc_val, exc_tb): + if self.fail_commit: + raise SQLAlchemyError("simulated commit outage") + + +class _StopSignal: + def __init__(self, waits): + self._waits = iter(waits) + self.set_called = False + + def wait(self, _timeout): + return next(self._waits) + + def set(self): + self.set_called = True + + +class _ThreadRecorder: + def __init__(self): + self.join_timeout = None + + def join(self, *, timeout): + self.join_timeout = timeout + + +def test_plain_approval_completion_is_guarded_and_terminal(): + """No-execution approval completion accepts only an already-claimed step.""" + repo = WorkflowRepository(Mock(), "tenant_1") + transitioned = SimpleNamespace(status="completed") + with patch.object(repo, "_atomic_transition", return_value=transitioned) as transition: + result = repo.complete_claimed_approval("step_1") + + transition.assert_called_once_with( + "step_1", + status="completed", + status_guard=ANY, + completed_at=ANY, + response_data={"approved": True}, + ) + call = transition.call_args + assert call.kwargs["status_guard"].right.value == "approved" + assert call.kwargs["completed_at"].tzinfo is UTC + assert result is transitioned + + +def test_transient_finalization_commit_failure_retries_without_rerunning_adapter(): + """Bounded request retries can recover without repeating adapter work.""" + adapter = Mock(return_value=(True, None)) + failing_uows = [_ApprovalUoW(fail_commit=True) for _ in range(2)] + successful_uow = _ApprovalUoW(fail_commit=False) + uows = iter((*failing_uows, successful_uow)) + + succeeded, error_message = adapter("mb_1", "tenant_1") + with ( + patch("src.core.workflow_finalization.ApprovalUoW", side_effect=lambda _tenant_id: next(uows)) as uow_type, + patch("src.core.workflow_finalization.time.sleep"), + ): + result = finalize_media_buy_approval_step( + tenant_id="tenant_1", + step_id="step_1", + media_buy_id="mb_1", + succeeded=succeeded, + error_message=error_message, + ) + + assert result.applied is True + assert result.result is not None + assert result.result.media_buy_id == "mb_1" + adapter.assert_called_once_with("mb_1", "tenant_1") + assert uow_type.call_count == 3 + assert all(uow.workflows.transitions == 1 for uow in failing_uows) + assert successful_uow.workflows.transitions == 1 + + +def test_success_finalization_applies_requested_flight_status_atomically(): + """Workflow completion resolves creative-unblock status in the terminal UoW.""" + media_buy = SimpleNamespace( + start_time=None, + end_time=None, + start_date=date(2099, 1, 1), + end_date=date(2099, 1, 31), + ) + media_buys = _FailureMediaBuyRepo(media_buy=media_buy) + uow = _ApprovalUoW(fail_commit=False, media_buys=media_buys) + + with ( + patch("src.core.workflow_finalization.ApprovalUoW", return_value=uow), + patch( + "src.core.workflow_finalization.media_buy_status_from_flight_dates", + return_value="scheduled", + ) as resolve_status, + ): + result = finalize_media_buy_approval_step( + tenant_id="tenant_1", + step_id="step_1", + media_buy_id="mb_1", + succeeded=True, + apply_flight_status=True, + ) + + assert result.applied is True + resolve_status.assert_called_once_with( + start_time=None, + end_time=None, + start_date=date(2099, 1, 1), + end_date=date(2099, 1, 31), + ) + assert media_buys.status_updates == [("mb_1", "scheduled")] + + +def test_permanent_finalization_outage_returns_retryable_pending_without_rerunning_adapter(): + """A sustained outage releases the request worker and leaves reconciliation work.""" + adapter = Mock(return_value=(True, None)) + failing_uows = [_ApprovalUoW(fail_commit=True) for _ in range(3)] + uows = iter(failing_uows) + + succeeded, error_message = adapter("mb_1", "tenant_1") + with ( + patch("src.core.workflow_finalization.ApprovalUoW", side_effect=lambda _tenant_id: next(uows)) as uow_type, + patch("src.core.workflow_finalization.time.sleep"), + ): + result = finalize_media_buy_approval_step( + tenant_id="tenant_1", + step_id="step_1", + media_buy_id="mb_1", + succeeded=succeeded, + error_message=error_message, + ) + + assert result.applied is False + adapter.assert_called_once_with("mb_1", "tenant_1") + assert uow_type.call_count == 3 + + +def test_post_commit_unknown_verifies_stored_terminal_result(): + """A retry recognizes the first commit instead of reporting false failure.""" + persisted = { + "media_buy_id": "mb_1", + "packages": [], + "status": "completed", + "confirmed_at": "2026-01-01T00:00:00Z", + "revision": 1, + } + first = _ApprovalUoW(fail_commit=True) + terminal_repo = _WorkflowRepo( + transition_result=None, + existing=SimpleNamespace(status="completed", response_data=persisted), + ) + second = _ApprovalUoW(fail_commit=False, workflows=terminal_repo) + uows = iter((first, second)) + + with ( + patch("src.core.workflow_finalization.ApprovalUoW", side_effect=lambda _tenant_id: next(uows)), + patch("src.core.workflow_finalization.time.sleep"), + ): + result = finalize_media_buy_approval_step( + tenant_id="tenant_1", + step_id="step_1", + media_buy_id="mb_1", + succeeded=True, + ) + + assert result.applied is True + assert result.result is not None + assert result.result.media_buy_id == "mb_1" + assert terminal_repo.transitions == 1 + + +def test_reconciliation_uses_persisted_domain_state_without_adapter_call(): + """tasks/get recovery terminalizes success and re-derives its flight status.""" + claimed_step = SimpleNamespace( + step_id="step_1", + request_data={"context": {"trace_id": "trace_1"}}, + ) + lookup_uow = _ApprovalUoW( + fail_commit=False, + workflows=_WorkflowRepo(existing=claimed_step), + media_buys=_MediaBuyRepo(media_buy=SimpleNamespace(status="active")), + ) + finalization_media_buy = SimpleNamespace( + start_time=None, + end_time=None, + start_date=date(2099, 1, 1), + end_date=date(2099, 1, 31), + ) + finalization_media_repo = _FailureMediaBuyRepo(media_buy=finalization_media_buy) + finalization_uow = _ApprovalUoW(fail_commit=False, media_buys=finalization_media_repo) + uows = iter((lookup_uow, finalization_uow)) + + with ( + patch("src.core.workflow_finalization.ApprovalUoW", side_effect=lambda _tenant_id: next(uows)), + patch("src.core.workflow_finalization.media_buy_status_from_flight_dates", return_value="scheduled"), + ): + result = reconcile_claimed_media_buy_approval_step( + tenant_id="tenant_1", + media_buy_id="mb_1", + ) + + assert result.applied is True + assert result.result is not None + assert result.result.media_buy_id == "mb_1" + assert result.result.context is not None + assert result.result.context.trace_id == "trace_1" + assert finalization_media_repo.status_updates == [("mb_1", "scheduled")] + + +def test_reconciliation_keeps_pre_adapter_pending_state_nonterminal(): + """An absent post-adapter marker can never be synthesized as success.""" + claimed_step = SimpleNamespace(step_id="step_1", request_data={}) + lookup_uow = _ApprovalUoW( + fail_commit=False, + workflows=_WorkflowRepo(existing=claimed_step), + media_buys=_MediaBuyRepo(media_buy=SimpleNamespace(status="pending_approval")), + ) + + with patch("src.core.workflow_finalization.ApprovalUoW", return_value=lookup_uow): + result = reconcile_claimed_media_buy_approval_step( + tenant_id="tenant_1", + media_buy_id="mb_1", + ) + + assert result.applied is False + assert result.result is None + + +def test_reconciliation_terminalizes_ambiguous_activation_without_marking_buy_failed(): + """A durable execution claim becomes an operator-recoverable task failure.""" + claimed_step = SimpleNamespace(step_id="step_1", request_data={}) + lookup_uow = _ApprovalUoW( + fail_commit=False, + workflows=_WorkflowRepo(existing=claimed_step), + media_buys=_MediaBuyRepo(media_buy=SimpleNamespace(status="activation_unknown")), + ) + finalization_media_repo = _FailureMediaBuyRepo() + finalization_uow = _ApprovalUoW(fail_commit=False, media_buys=finalization_media_repo) + uows = iter((lookup_uow, finalization_uow)) + + with patch("src.core.workflow_finalization.ApprovalUoW", side_effect=lambda _tenant_id: next(uows)): + result = reconcile_claimed_media_buy_approval_step( + tenant_id="tenant_1", + media_buy_id="mb_1", + ) + + assert result.applied is True + assert result.result is None + assert finalization_uow.workflows.transitions == 1 + assert finalization_media_repo.status_updates == [] + + +def test_reconciliation_keeps_recent_execution_claim_working(): + """Polling cannot fail a request while its adapter lease is active.""" + claimed_step = SimpleNamespace(step_id="step_1", request_data={}) + lookup_uow = _ApprovalUoW( + fail_commit=False, + workflows=_WorkflowRepo(existing=claimed_step), + media_buys=_MediaBuyRepo( + media_buy=SimpleNamespace( + status="activating", + updated_at=datetime.now(UTC), + ) + ), + ) + + with patch("src.core.workflow_finalization.ApprovalUoW", return_value=lookup_uow): + result = reconcile_claimed_media_buy_approval_step( + tenant_id="tenant_1", + media_buy_id="mb_1", + ) + + assert result.applied is False + assert result.result is None + + +def test_reconciliation_terminalizes_expired_execution_claim(): + """A crashed pre-dispatch claim cannot leave tasks/get working forever.""" + claimed_step = SimpleNamespace(step_id="step_1", request_data={}) + lookup_uow = _ApprovalUoW( + fail_commit=False, + workflows=_WorkflowRepo(existing=claimed_step), + media_buys=_MediaBuyRepo( + media_buy=SimpleNamespace( + status="activating", + updated_at=datetime.now(UTC) - timedelta(minutes=16), + ) + ), + ) + finalization_media_repo = _FailureMediaBuyRepo() + finalization_uow = _ApprovalUoW(fail_commit=False, media_buys=finalization_media_repo) + uows = iter((lookup_uow, finalization_uow)) + + with patch("src.core.workflow_finalization.ApprovalUoW", side_effect=lambda _tenant_id: next(uows)): + result = reconcile_claimed_media_buy_approval_step( + tenant_id="tenant_1", + media_buy_id="mb_1", + ) + + assert result.applied is True + assert finalization_media_repo.status_updates == [] + assert finalization_media_repo.unknown_updates == ["mb_1"] + assert finalization_media_repo.expected_lease_versions == [ + lookup_uow.media_buys.media_buy.updated_at, + ] + + +def test_expired_reconciliation_cannot_fail_task_after_worker_completes(): + """A lost takeover CAS leaves the workflow untouched for late success.""" + media_repo = _LostLeaseMediaBuyRepo() + uow = _ApprovalUoW(fail_commit=False, media_buys=media_repo) + observed_lease_version = datetime.now(UTC) - timedelta(minutes=16) + + with patch("src.core.workflow_finalization.ApprovalUoW", return_value=uow): + result = finalize_media_buy_approval_step( + tenant_id="tenant_1", + step_id="step_1", + media_buy_id="mb_1", + succeeded=False, + mark_media_buy_failed=False, + mark_media_buy_unknown=True, + media_buy_expected_updated_at=observed_lease_version, + ) + + assert result.applied is False + assert uow.workflows.transitions == 0 + assert media_repo.unknown_updates == ["mb_1"] + assert media_repo.expected_lease_versions == [observed_lease_version] + + +def test_adapter_failure_wrapper_persists_reconcilable_failed_status(): + """The public execution helper leaves durable evidence for reconciliation.""" + from src.core.tools.media_buy_create import _persist_approved_execution_outcome + + media_repo = _FailureMediaBuyRepo() + uow = _ApprovalUoW(fail_commit=False, media_buys=media_repo) + execute_once = Mock(return_value=(False, "adapter rejected")) + execute_with_outcome = _persist_approved_execution_outcome(execute_once) + + with patch("src.core.database.repositories.MediaBuyUoW", return_value=uow): + result = execute_with_outcome("mb_1", "tenant_1") + + assert result == (False, "adapter rejected") + execute_once.assert_called_once_with("mb_1", "tenant_1", execution_claimed=False) + assert media_repo.status_updates == [("mb_1", "failed")] + + +def test_post_creation_pending_wrapper_does_not_persist_false_failure(): + """An externally created order must never be rewritten as failed.""" + from src.core.tools.media_buy_create import _persist_approved_execution_outcome + + media_repo = _FailureMediaBuyRepo() + uow = _ApprovalUoW(fail_commit=False, media_buys=media_repo) + execute_once = Mock(return_value=(None, "local status commit failed")) + execute_with_outcome = _persist_approved_execution_outcome(execute_once) + + with patch("src.core.database.repositories.MediaBuyUoW", return_value=uow) as uow_type: + result = execute_with_outcome("mb_1", "tenant_1") + + assert result == (None, "local status commit failed") + execute_once.assert_called_once_with("mb_1", "tenant_1", execution_claimed=False) + uow_type.assert_not_called() + assert media_repo.status_updates == [] + + +def test_live_execution_lease_renews_durable_claim(): + """The worker heartbeat prevents age-only takeover while it is alive.""" + from src.core.tools.media_buy_create import _ApprovalExecutionLease + + media_repo = Mock() + media_repo.renew_approved_execution_lease.return_value = True + uow = _ApprovalUoW(fail_commit=False, media_buys=media_repo) + lease = _ApprovalExecutionLease("mb_1", "tenant_1") + + with patch("src.core.database.repositories.MediaBuyUoW", return_value=uow): + renewed = lease._renew_once() + + assert renewed is True + media_repo.renew_approved_execution_lease.assert_called_once_with("mb_1") + + +def test_live_execution_lease_loop_renews_and_stops_after_lease_loss(): + """The heartbeat loop renews once and exits when its CAS loses.""" + from src.core.tools.media_buy_create import _ApprovalExecutionLease + + lease = _ApprovalExecutionLease("mb_1", "tenant_1") + stop = _StopSignal([False]) + renewals = [] + + def lose_lease(): + renewals.append("renewed") + return False + + lease._stop = stop + lease._renew_once = lose_lease + lease._run() + + assert renewals == ["renewed"] + + +def test_live_execution_lease_error_log_sanitizes_media_buy_id(caplog): + """A crafted identifier cannot inject a second approval log record.""" + from src.core.tools.media_buy_create import _ApprovalExecutionLease + + lease = _ApprovalExecutionLease("mb_1\r\nFORGED", "tenant_1") + lease._stop = _StopSignal([False, True]) + + def failed_renewal(): + raise RuntimeError("renewal failed") + + lease._renew_once = failed_renewal + with caplog.at_level("ERROR", logger="src.core.tools.media_buy_create"): + lease._run() + + message = next( + record.getMessage() for record in caplog.records if "Could not renew execution lease" in record.getMessage() + ) + assert "\r" not in message + assert "\n" not in message + assert "mb_1FORGED" in message + + +def test_live_execution_lease_stop_prevents_renewal_and_joins_thread(): + """Closing the heartbeat wakes its wait and joins without another renewal.""" + from src.core.tools.media_buy_create import _ApprovalExecutionLease + + lease = _ApprovalExecutionLease("mb_1", "tenant_1") + stop = _StopSignal([True]) + thread = _ThreadRecorder() + + def unexpected_renewal(): + raise AssertionError("stopped lease must not renew") + + lease._stop = stop + lease._thread = thread + lease._renew_once = unexpected_renewal + lease._run() + lease.close() + + assert stop.set_called is True + assert thread.join_timeout == 1.0 + + +def test_blocking_creative_log_sanitizes_identifiers(caplog): + """The workflow creative gate neutralizes CR/LF before logging IDs.""" + from flask import Flask + + from src.admin.blueprints import workflows as workflows_module + + app = Flask(__name__) + app.secret_key = "test-only" + db = Mock() + media_buy_repo = Mock() + media_buy_repo.get_by_id.return_value = SimpleNamespace( + status="pending_approval", + principal_id="principal_1", + ) + preparation = SimpleNamespace( + status=ApprovalExecutionStatus.WAITING_FOR_CREATIVES, + blocking_creative_ids=("creative_1\r\nFORGED",), + ) + + with ( + app.test_request_context("/"), + patch.object(workflows_module, "MediaBuyRepository", return_value=media_buy_repo), + patch.object( + workflows_module, + "prepare_media_buy_approval_execution", + return_value=preparation, + ), + caplog.at_level("WARNING", logger="src.admin.blueprints.workflows"), + ): + _response, status = workflows_module._approve_mapped_media_buy( + db=db, + tenant_id="tenant_1", + step_id="step_1", + media_buy_id="mb_1", + request_data={}, + user_email="reviewer@example.com", + ) + + assert status == 200 + message = next(record.getMessage() for record in caplog.records if "creatives not approved" in record.getMessage()) + assert "\r" not in message + assert "\n" not in message + + +def test_shared_preparation_applies_creative_gate_before_execution_claim(): + """Every admin entry point uses the same blocking-creative business rule.""" + media_buy_repo = Mock() + media_buy_repo.get_by_id.return_value = SimpleNamespace( + status="pending_approval", + principal_id="principal_1", + ) + assignments = Mock() + assignments.get_by_media_buy.return_value = [SimpleNamespace(creative_id="creative_1")] + creatives = Mock() + creatives.get_by_ids.return_value = [SimpleNamespace(creative_id="creative_1", status="pending_review")] + + outcome = prepare_media_buy_approval_execution( + media_buys=media_buy_repo, + assignments=assignments, + creatives=creatives, + media_buy_id="mb_1", + approved_by="approver@example.com", + ) + + assert outcome.status is ApprovalExecutionStatus.WAITING_FOR_CREATIVES + assert outcome.blocking_creative_ids == ("creative_1",) + media_buy_repo.update_status.assert_called_once_with( + "mb_1", + "pending_creatives", + approved_at=ANY, + approved_by="approver@example.com", + ) + # ``ANY`` above matches a naive datetime just as happily as an aware one, so pin + # the tzinfo the same way the completed_at sibling does. + assert media_buy_repo.update_status.call_args.kwargs["approved_at"].tzinfo is UTC + creatives.get_by_ids.assert_called_once_with(["creative_1"], "principal_1") + media_buy_repo.claim_approved_execution.assert_not_called() + + +def test_shared_preparation_uses_repository_execution_source_statuses(): + """The precheck and atomic CAS share one exact eligibility vocabulary.""" + assert APPROVED_EXECUTION_SOURCE_STATUSES == ("pending_approval", "pending_creatives", "draft") + + for status in APPROVED_EXECUTION_SOURCE_STATUSES: + media_buy_repo = Mock() + media_buy_repo.get_by_id.return_value = SimpleNamespace( + status=status, + principal_id="principal_1", + ) + media_buy_repo.claim_approved_execution.return_value = True + assignments = Mock() + assignments.get_by_media_buy.return_value = [SimpleNamespace(creative_id="creative_1")] + creatives = Mock() + creatives.get_by_ids.return_value = [SimpleNamespace(creative_id="creative_1", status="approved")] + + outcome = prepare_media_buy_approval_execution( + media_buys=media_buy_repo, + assignments=assignments, + creatives=creatives, + media_buy_id="mb_1", + approved_by=None, + ) + + assert outcome.status is ApprovalExecutionStatus.READY + # The trigger travels to the CAS, which enforces the source guard IN the UPDATE. + media_buy_repo.claim_approved_execution.assert_called_once_with("mb_1", trigger=ApprovalTrigger.HUMAN_DECISION) + + +def test_creative_unblock_may_not_promote_a_buy_awaiting_a_human_decision(): + """A creative approval must never stand in for the human approval it is not. + + ``pending_approval`` is in the canonical execution source set, so a trigger that + ignored the split would claim and execute a buy no human has approved. The route + used to encode this as a bare ``{"pending_creatives", "draft"}`` literal with the + reasoning nowhere; the split now lives beside the canonical set and is derived. + + Graded both ways so this cannot pass by refusing everything. + """ + for status, trigger, expected in ( + ("pending_approval", ApprovalTrigger.CREATIVE_UNBLOCK, ApprovalExecutionStatus.NOT_EXECUTABLE), + ("pending_approval", ApprovalTrigger.HUMAN_DECISION, ApprovalExecutionStatus.READY), + ("pending_creatives", ApprovalTrigger.CREATIVE_UNBLOCK, ApprovalExecutionStatus.READY), + ("draft", ApprovalTrigger.CREATIVE_UNBLOCK, ApprovalExecutionStatus.READY), + ): + media_buy_repo = Mock() + media_buy_repo.get_by_id.return_value = SimpleNamespace(status=status, principal_id="principal_1") + media_buy_repo.claim_approved_execution.return_value = True + assignments = Mock() + assignments.get_by_media_buy.return_value = [SimpleNamespace(creative_id="creative_1")] + creatives = Mock() + creatives.get_by_ids.return_value = [SimpleNamespace(creative_id="creative_1", status="approved")] + + outcome = prepare_media_buy_approval_execution( + media_buys=media_buy_repo, + assignments=assignments, + creatives=creatives, + media_buy_id="mb_1", + approved_by=None, + trigger=trigger, + ) + + assert outcome.status is expected, f"{status} + {trigger} should be {expected}, got {outcome.status}" + if expected is ApprovalExecutionStatus.NOT_EXECUTABLE: + media_buy_repo.claim_approved_execution.assert_not_called() + + +def test_not_executable_is_distinct_from_claim_refused(): + """The two refusals mean different things and callers render them differently. + + NOT_EXECUTABLE says "nothing to execute here, finish the workflow step yourself"; + CLAIM_REFUSED says "this WAS a candidate and another request already claimed it, do + not proceed". Collapsing them is what made the routes pre-filter in the first place. + """ + assignments = Mock() + assignments.get_by_media_buy.return_value = [SimpleNamespace(creative_id="creative_1")] + creatives = Mock() + creatives.get_by_ids.return_value = [SimpleNamespace(creative_id="creative_1", status="approved")] + + absent = Mock() + absent.get_by_id.return_value = None + assert ( + prepare_media_buy_approval_execution( + media_buys=absent, + assignments=assignments, + creatives=creatives, + media_buy_id="mb_1", + approved_by=None, + ).status + is ApprovalExecutionStatus.NOT_EXECUTABLE + ) + + lost_the_claim = Mock() + lost_the_claim.get_by_id.return_value = SimpleNamespace(status="pending_approval", principal_id="principal_1") + lost_the_claim.claim_approved_execution.return_value = False + assert ( + prepare_media_buy_approval_execution( + media_buys=lost_the_claim, + assignments=assignments, + creatives=creatives, + media_buy_id="mb_1", + approved_by=None, + ).status + is ApprovalExecutionStatus.CLAIM_REFUSED + ) + + +@pytest.mark.parametrize( + ("creative_status", "expected_status"), + [ + ("approved", ApprovalExecutionStatus.READY), + ("active", ApprovalExecutionStatus.WAITING_FOR_CREATIVES), + ("pending_review", ApprovalExecutionStatus.WAITING_FOR_CREATIVES), + ("rejected", ApprovalExecutionStatus.WAITING_FOR_CREATIVES), + ], +) +def test_creative_gate_admits_only_approved(creative_status, expected_status): + """``approved`` is the only creative status that satisfies the gate. + + The two approve routes had drifted: one used ``not in ["approved", "active"]`` while the + other used ``!= "approved"``. The reconciliation had resolved to the permissive rule, but + ``active`` is not a member of the creative status enum (``processing``, ``pending_review``, + ``approved``, ``suspended``, ``rejected``, ``archived``) and no producer writes it for a + creative — so the permissive branch graded nothing real. The ``active`` row is kept here on + the REFUSAL side so the gate is pinned against re-admitting it. + + Parametrized rather than added as a fifth near-identical scaffold, because the missing row + is exactly what a table makes visible and four copy-pasted mock blocks hid. + """ + media_buy_repo = Mock() + media_buy_repo.get_by_id.return_value = SimpleNamespace(status="pending_approval", principal_id="principal_1") + media_buy_repo.claim_approved_execution.return_value = True + assignments = Mock() + assignments.get_by_media_buy.return_value = [SimpleNamespace(creative_id="creative_1")] + creatives = Mock() + creatives.get_by_ids.return_value = [SimpleNamespace(creative_id="creative_1", status=creative_status)] + + outcome = prepare_media_buy_approval_execution( + media_buys=media_buy_repo, + assignments=assignments, + creatives=creatives, + media_buy_id="mb_1", + approved_by=None, + ) + + assert outcome.status is expected_status + if expected_status is ApprovalExecutionStatus.WAITING_FOR_CREATIVES: + assert outcome.blocking_creative_ids == ("creative_1",) + + +def test_shared_preparation_blocks_buy_without_creative_assignments(): + """No-assignment buys remain pending_creatives and never claim execution.""" + media_buy_repo = Mock() + media_buy_repo.get_by_id.return_value = SimpleNamespace( + status="pending_approval", + principal_id="principal_1", + ) + assignments = Mock() + assignments.get_by_media_buy.return_value = [] + creatives = Mock() + + outcome = prepare_media_buy_approval_execution( + media_buys=media_buy_repo, + assignments=assignments, + creatives=creatives, + media_buy_id="mb_1", + approved_by="approver@example.com", + ) + + assert outcome.status is ApprovalExecutionStatus.WAITING_FOR_CREATIVES + assert outcome.blocking_creative_ids == () + creatives.get_by_ids.assert_not_called() + media_buy_repo.update_status.assert_called_once_with( + "mb_1", + "pending_creatives", + approved_at=ANY, + approved_by="approver@example.com", + ) + # ``ANY`` above matches a naive datetime just as happily as an aware one, so pin + # the tzinfo the same way the completed_at sibling does. + assert media_buy_repo.update_status.call_args.kwargs["approved_at"].tzinfo is UTC + media_buy_repo.claim_approved_execution.assert_not_called() + + +def test_shared_preparation_treats_missing_creative_rows_as_blocking(): + """A dangling assignment cannot satisfy the canonical creative gate.""" + media_buy_repo = Mock() + media_buy_repo.get_by_id.return_value = SimpleNamespace( + status="pending_approval", + principal_id="principal_1", + ) + assignments = Mock() + assignments.get_by_media_buy.return_value = [SimpleNamespace(creative_id="creative_missing")] + creatives = Mock() + creatives.get_by_ids.return_value = [] + + outcome = prepare_media_buy_approval_execution( + media_buys=media_buy_repo, + assignments=assignments, + creatives=creatives, + media_buy_id="mb_1", + approved_by=None, + ) + + assert outcome.status is ApprovalExecutionStatus.WAITING_FOR_CREATIVES + assert outcome.blocking_creative_ids == ("creative_missing",) + creatives.get_by_ids.assert_called_once_with(["creative_missing"], "principal_1") + media_buy_repo.claim_approved_execution.assert_not_called() + + +def test_flight_status_uses_canonical_pre_active_and_completed_lifecycle(): + """Creative unblocking preserves the buy's flight-aware status semantics.""" + start = datetime(2026, 8, 1, tzinfo=UTC) + end = datetime(2026, 8, 31, 23, 59, tzinfo=UTC) + + assert ( + media_buy_status_from_flight_dates( + start_time=start, + end_time=end, + start_date=None, + end_date=None, + now=datetime(2026, 7, 1, tzinfo=UTC), + ) + == "scheduled" + ) + assert ( + media_buy_status_from_flight_dates( + start_time=None, + end_time=None, + start_date=date(2026, 8, 1), + end_date=date(2026, 8, 31), + now=datetime(2026, 8, 15, tzinfo=UTC), + ) + == "active" + ) + assert ( + media_buy_status_from_flight_dates( + start_time=start, + end_time=end, + start_date=None, + end_date=None, + now=datetime(2026, 9, 1, tzinfo=UTC), + ) + == "completed" + ) + # UTC normalization happens before the canonical date resolver: this end + # instant is September 1 UTC even though its source-zone date is August 31. + assert ( + media_buy_status_from_flight_dates( + start_time=datetime.fromisoformat("2026-08-01T00:00:00-03:00"), + end_time=datetime.fromisoformat("2026-08-31T23:30:00-03:00"), + start_date=None, + end_date=None, + now=datetime(2026, 9, 1, 1, tzinfo=UTC), + ) + == "active" + ) + assert ( + media_buy_status_from_flight_dates( + start_time=None, + end_time=None, + start_date=date(2026, 8, 1), + end_date=date(2026, 8, 31), + now=datetime(2026, 9, 1, tzinfo=UTC), + ) + == "completed" + ) + + +def test_shared_execution_success_finalizes_exact_step_once(): + """The L2 orchestration owns adapter tri-state interpretation and finalization.""" + result = SimpleNamespace(media_buy_id="mb_1") + with ( + patch( + "src.core.tools.media_buy_create.execute_approved_media_buy", + return_value=(True, None), + ) as execute, + patch( + "src.core.workflow_finalization.finalize_media_buy_approval_step", + return_value=ApprovalFinalization(applied=True, result=result), + ) as finalize, + ): + outcome = execute_and_finalize_media_buy_approval( + tenant_id="tenant_1", + media_buy_id="mb_1", + step_id="step_1", + context={"trace_id": "trace_1"}, + ) + + assert outcome.status is ApprovalExecutionStatus.SUCCEEDED + assert outcome.finalization == ApprovalFinalization(applied=True, result=result) + execute.assert_called_once_with("mb_1", "tenant_1", execution_claimed=True) + finalize.assert_called_once_with( + tenant_id="tenant_1", + step_id="step_1", + media_buy_id="mb_1", + succeeded=True, + error_message=None, + context={"trace_id": "trace_1"}, + apply_flight_status=False, + ) + + +def test_shared_execution_persists_flight_aware_status_with_terminal_step(): + """The creative-unblock status correction is part of terminal finalization.""" + result = SimpleNamespace(media_buy_id="mb_1") + with ( + patch( + "src.core.tools.media_buy_create.execute_approved_media_buy", + return_value=(True, None), + ), + patch( + "src.core.workflow_finalization.finalize_latest_media_buy_approval_step", + return_value=ApprovalFinalization(applied=True, result=result), + ) as finalize, + ): + outcome = execute_and_finalize_media_buy_approval( + tenant_id="tenant_1", + media_buy_id="mb_1", + step_id=None, + apply_flight_status=True, + ) + + assert outcome.status is ApprovalExecutionStatus.SUCCEEDED + finalize.assert_called_once_with( + tenant_id="tenant_1", + media_buy_id="mb_1", + succeeded=True, + error_message=None, + apply_flight_status=True, + ) + + +def test_shared_execution_ambiguous_outcome_stays_nonterminal(): + """A post-dispatch unknown never enters either terminal finalizer.""" + with ( + patch( + "src.core.tools.media_buy_create.execute_approved_media_buy", + return_value=(None, "adapter outcome unknown"), + ), + patch("src.core.workflow_finalization.finalize_media_buy_approval_step") as finalize_exact, + patch("src.core.workflow_finalization.finalize_latest_media_buy_approval_step") as finalize_latest, + ): + outcome = execute_and_finalize_media_buy_approval( + tenant_id="tenant_1", + media_buy_id="mb_1", + step_id="step_1", + ) + + assert outcome.status is ApprovalExecutionStatus.PENDING_RECONCILIATION + finalize_exact.assert_not_called() + finalize_latest.assert_not_called() + + +def test_tasks_get_reconciles_approved_step_before_building_terminal_artifact(): + """The durable polling path invokes reconciliation and re-reads the step.""" + from a2a.types import TaskState + + from src.a2a_server.adcp_a2a_server import AdCPRequestHandler + from tests.utils.a2a_helpers import extract_data_from_artifact + + handler = AdCPRequestHandler() + identity = PrincipalFactory.make_identity( + tenant_id="tenant_1", + principal_id="principal_1", + tenant={"tenant_id": "tenant_1"}, + protocol="a2a", + ) + approved_step = SimpleNamespace( + step_id="step_1", + context_id="context_1", + status="approved", + tool_name="create_media_buy", + response_data=None, + ) + completed_payload = { + "media_buy_id": "mb_1", + "packages": [], + "status": "completed", + "confirmed_at": "2026-01-01T00:00:00Z", + "revision": 1, + } + completed_step = SimpleNamespace( + step_id="step_1", + context_id="context_1", + status="completed", + tool_name="create_media_buy", + response_data=completed_payload, + ) + first_repo = Mock() + first_repo.get_mappings_for_step.return_value = [ + SimpleNamespace(object_type="media_buy", object_id="mb_1"), + ] + owned_results = iter( + ( + (object(), first_repo, approved_step), + (object(), Mock(), completed_step), + ) + ) + + @contextmanager + def owned_step(*_args, **_kwargs): + yield next(owned_results) + + with ( + patch.object(handler, "_owned_durable_step", side_effect=owned_step), + patch("src.core.workflow_finalization.reconcile_claimed_media_buy_approval_step") as reconcile, + ): + task = handler._durable_task_from_step("task_1", identity) + + reconcile.assert_called_once_with(tenant_id="tenant_1", media_buy_id="mb_1") + assert task is not None + assert task.status.state == TaskState.TASK_STATE_COMPLETED + assert task.artifacts and task.artifacts[0].name == "media_buy_result" + assert extract_data_from_artifact(task.artifacts[0])["media_buy_id"] == "mb_1" + + +def _source_string_literals(tree: ast.AST) -> list[str]: + """Every string literal in ``tree``, as the AUTHOR wrote it semantically. + + Reading literals off the AST rather than scanning source lines is what makes the + re-inline guards below survive wrapping: these messages are longer than the repo's + 120-char line limit, so a real copy-paste is re-wrapped by the formatter into + implicit-concatenation pieces that NO single source line contains. A per-line + substring scan therefore misses exactly the re-inline it exists to catch. Python + folds adjacent literals into one ``ast.Constant``, so the AST sees the joined + string the author meant. + + F-strings arrive as ``ast.JoinedStr``; their literal parts are joined with a NUL + placeholder standing in for each interpolation, so a fragment is matched only when + it lies wholly within literal text and can never span an interpolated value. + """ + literals: list[str] = [] + for node in ast.walk(tree): + if isinstance(node, ast.Constant) and isinstance(node.value, str): + literals.append(node.value) + elif isinstance(node, ast.JoinedStr): + literals.append("".join(part.value if isinstance(part, ast.Constant) else "\x00" for part in node.values)) + return literals + + +def _reinline_offenders(fragment: str) -> list[str]: + """Files under ``src/`` outside ``approval.py`` whose source carries ``fragment``.""" + src_root = Path(__file__).resolve().parents[2] / "src" + offenders = [] + for path in sorted(src_root.rglob("*.py")): + if path.name == "approval.py": + continue + try: + tree = ast.parse(path.read_text()) + except SyntaxError: # pragma: no cover - a syntax error fails elsewhere, loudly + continue + if any(fragment in literal for literal in _source_string_literals(tree)): + offenders.append(str(path.relative_to(src_root))) + return offenders + + +class TestWaitingForCreativesMessage: + """One adapter-agnostic message for the WAITING_FOR_CREATIVES outcome. + + Both admin approve routes branch on the SAME + ``ApprovalExecutionStatus.WAITING_FOR_CREATIVES`` from + ``prepare_media_buy_approval_execution``, but each hand-wrote its own flash text. The + copies drifted on a business fact: one said "in the ad server", the other "in GAM" — + wrong for every tenant on a non-GAM adapter, and this branch fires for all of them. + """ + + def test_message_is_adapter_agnostic(self): + from src.admin.utils.approval import waiting_for_creatives_message + + message = waiting_for_creatives_message(3) + + assert message == ( + "Media buy approved! Waiting for 3 creative(s) to be approved before creating in the ad server." + ) + # The drift that shipped: GAM is one of several registered adapters. + assert "GAM" not in message + + def test_zero_blocking_creatives_gets_its_own_message(self): + """No assignments at all is a different situation, not "waiting for 0". + + ``_approval_creative_gate`` returns ``(False, ())`` when the buy has NO creative + assignments — the gate is unsatisfied precisely because nothing is assigned — so a + single count-interpolated sentence renders "Waiting for 0 creative(s) to be + approved", telling the operator to wait for an empty set. The two cases need + opposite actions: assign creatives, versus wait for the assigned ones to clear. + """ + from src.admin.utils.approval import waiting_for_creatives_message + + message = waiting_for_creatives_message(0) + + assert "0 creative(s)" not in message + assert "No creatives are assigned yet" in message + assert "assign" in message.lower(), "the operator must be told the action, not just the state" + assert "GAM" not in message + + def test_no_route_reinlines_the_message(self): + """The wording lives in exactly one place — checked on the DISTINCTIVE clause. + + A route that re-inlines the sentence can drift again without any behavioural test + noticing, so this guard carries the single-source property. + + Fragment selection is the whole difficulty, and two earlier versions got it wrong + in opposite ways: + + * the text AFTER "creative(s)" — "...before creating in the ad server" — which is + exactly the clause that HAD drifted to "...in GAM", so a re-inline of the + historical variant did not match and the guard passed. It caught only re-inlines + of the wording that was already correct. + * ``os.path.commonprefix`` of the two branches, which is "Media buy approved!" — + a generic salutation. A re-inline of the distinctive clause WITHOUT that opener + sails past it, and both mutations used to verify that version happened to include + the salutation, so it looked verified. + + So match each branch on the clause that identifies it and is not shared with + anything else: the count-interpolated wait text, and the zero-assignment text. Both + are checked, because the guard exists to stop EITHER branch being re-inlined. + """ + from src.admin.utils.approval import waiting_for_creatives_message + + salutation = os.path.commonprefix([waiting_for_creatives_message(0), waiting_for_creatives_message(2)]).strip() + # Everything after the shared opener is what actually distinguishes each branch. + distinctive = [ + waiting_for_creatives_message(0)[len(salutation) :].strip(), + waiting_for_creatives_message(2)[len(salutation) :].strip(), + ] + # The wait branch needs care: the count is interpolated (so the fragment must start + # after it) AND the trailing "before creating in the ad server" is the clause that + # HAS drifted (to "...in GAM"), so the fragment must end before it. What is left — + # "creative(s) to be approved" — is both distinctive and drift-stable. Taking the + # tail after "creative(s)" instead, as two earlier versions did, matches only the + # wording that is currently correct and lets a re-inline of the GAM variant pass. + wait = distinctive[1] + distinctive[1] = wait[wait.index("creative(s)") : wait.index("before")].strip() + for fragment in distinctive: + assert len(fragment) >= 25, ( + f"message shape changed — {fragment!r} is too short to identify a branch. " + f"Re-derive this guard's fragments rather than letting them match broadly; a " + f"short fragment is how the salutation-only version passed." + ) + + offenders = sorted({site for fragment in distinctive for site in _reinline_offenders(fragment)}) + + assert offenders == [], f"WAITING_FOR_CREATIVES wording re-inlined outside approval.py: {offenders}" + + +class TestPendingReconciliationMessage: + """One operator-facing message for the PENDING_RECONCILIATION outcome. + + Both admin approve routes (operations.py, workflows.py) branch on the SAME + ``ApprovalExecutionStatus.PENDING_RECONCILIATION`` from + ``prepare_media_buy_approval_execution``, but each hand-inlined the identical sentence — + the exact shape that let WAITING_FOR_CREATIVES's copies drift (see + TestWaitingForCreativesMessage above). This mirrors that guard for the sibling outcome. + """ + + def test_no_route_reinlines_the_message(self): + """The wording lives in exactly one place. + + Derives the fragment FROM the constant rather than hardcoding it, so rewording the + message re-points the guard automatically instead of silently disarming it. Uses the + opening clause rather than the closing one: the message is already written as two + implicitly-concatenated pieces in its own source, so a re-inline is re-wrapped by the + formatter at whatever column it lands in, and the leading clause is the stable half. + """ + from src.admin.utils.approval import APPROVED_MEDIA_BUY_PENDING_RECONCILIATION_MESSAGE + + fragment = APPROVED_MEDIA_BUY_PENDING_RECONCILIATION_MESSAGE.split(".", 1)[0].strip() + assert len(fragment) >= 15, ( + f"message shape changed — {fragment!r} is too short to discriminate; re-derive this guard's fragment" + ) + + offenders = _reinline_offenders(fragment) + + assert offenders == [], f"PENDING_RECONCILIATION wording re-inlined outside approval.py: {offenders}" diff --git a/tests/unit/test_architecture_bdd_no_request_in_then.py b/tests/unit/test_architecture_bdd_no_request_in_then.py index 3055795a91..9851ec448c 100644 --- a/tests/unit/test_architecture_bdd_no_request_in_then.py +++ b/tests/unit/test_architecture_bdd_no_request_in_then.py @@ -78,9 +78,9 @@ def then_auth_error(ctx): # the parametrized transport on the wire (#1417). Rate limiting and # payload size remain spec-production gaps (FIXME salesagent-9vgz.92). "bdd/steps/domain/uc002_nfr.py:126 then_auth_before_business_logic", - "bdd/steps/domain/uc002_nfr.py:190 then_rate_limiting_enforced", - "bdd/steps/domain/uc002_nfr.py:237 then_payload_size_limits", - "bdd/steps/domain/uc002_nfr.py:413 then_budget_validated_against_min_order", + "bdd/steps/domain/uc002_nfr.py:180 then_rate_limiting_enforced", + "bdd/steps/domain/uc002_nfr.py:227 then_payload_size_limits", + "bdd/steps/domain/uc002_nfr.py:403 then_budget_validated_against_min_order", } _ASSERT_ON_REQUEST_ALLOWLIST: set[str] = set() diff --git a/tests/unit/test_architecture_bdd_scenario_merge_durability.py b/tests/unit/test_architecture_bdd_scenario_merge_durability.py new file mode 100644 index 0000000000..b17c5ba77e --- /dev/null +++ b/tests/unit/test_architecture_bdd_scenario_merge_durability.py @@ -0,0 +1,320 @@ +"""Guard: hand-added BDD scenarios must survive ``compile_bdd.py --merge``. + +Compiled feature files are regenerated from the adcp-req sources; a scenario +that exists only locally (no ``BR-*`` adcp-req id) is classified +``LEGACY-DELETE`` and silently dropped on the next ``--merge`` unless it +carries a hand-edit marker — an ``@hand-edited`` tag OR a ``# HAND-EDITED`` +comment (``classify_scenario_pair`` / ``_has_hand_edited_marker`` in +``scripts/compile_bdd.py``). This guard pins that marker for every scenario we +deliberately maintain by hand, using the compiler's own classifier — if the +marker is ever lost, this goes red instead of the scenario vanishing. + +Two invariants: + 1. Each registered scenario classifies ``LEGACY-PRESERVE`` (marker present). + 2. The registry and the on-disk marked scenarios are a bijection — a future + hand-added scenario that forgets to register here (or a stale registry + entry) is caught, closing the "added a marked scenario, forgot to + register it" gap that (1) alone cannot see. + +KNOWN GAP — this guard is blind to scenarios with NO ``@T-*`` id tag. +``_marked_scenarios()`` filters on ``if sid:``, so an id-less scenario never +enters the candidate universe at all. Nine such scenarios classify +``LEGACY-DELETE`` right now (three in ``BR-UC-007-list-authorized-properties``, +six in ``BR-UC-GET-PRODUCTS-inventory-profile``) while ``_untracked_scenarios()`` +returns ``[]``, and appending a synthetic id-less, marker-less, traceability-less +scenario leaves this suite green. So invariant 2 holds only for scenarios that +carry an id — a scenario missing its marker AND its id is exactly the case that +vanishes silently, which is the failure this guard was written to prevent. + +Closing it means keying id-less scenarios by ``(feature, scenario.name)`` so they +enter the universe, plus a negative self-test with an id-less fixture; the nine +existing ones then need registering or marking, which is a separate decision. +Tracked in #1810. Stated here rather than left implicit because a guard that +reads as complete is worse than one that names its blind spot. +""" + +import re +import sys + +import yaml + +from tests.unit._architecture_helpers import assert_violations_match_allowlist, repo_root + +_ROOT = repo_root() +FEATURES_DIR = _ROOT / "tests" / "bdd" / "features" +TRACEABILITY_PATH = _ROOT / "docs" / "test-obligations" / "bdd-traceability.yaml" + +# (feature file, scenario id tag) pairs that are hand-maintained pending an +# upstream adcp-req id. Add new hand-edited scenarios here when introduced. +HAND_MAINTAINED_SCENARIOS = [ + # Grounded in transport-errors.mdx "Layer Separation"; upstream obligation + # Until the upstream obligation lands, only @hand-edited keeps it alive. + ("BR-UC-002-create-media-buy.feature", "@T-UC-002-ext-nl-unsupported"), +] + + +def _load_compiler(): + scripts_dir = str(_ROOT / "scripts") + if scripts_dir not in sys.path: + sys.path.insert(0, scripts_dir) + import compile_bdd + + return compile_bdd + + +def _is_adcp_req_id(ref: str) -> bool: + """True if ``ref`` is a bare adcp-req requirement id (``BR-*``/``SR-*``). + + A row whose ``upstream_refs`` carry at least one such id RENDERS from adcp-req, so + ``compile_bdd.py --merge`` keeps it. Anything else — a spec artifact (``*.mdx``/URL), + an unmodeled ref shape (``docs/x.md#Anchor``, a bare path), OR an EMPTY list — has no + adcp-req render and is a LEGACY-DELETE risk. Keying on the ABSENCE of a requirement id + (rather than the PRESENCE of a recognized artifact form) is what makes the discovery + exhaustive: an empty or unmodeled ``upstream_refs`` can no longer slip past. + + The id GRAMMAR is matched in full, not just the prefix: feature files and spec artifacts are + themselves named ``BR-UC-002-create-media-buy.feature``, so a bare-prefix test would read such + a ref as a requirement id and silently drop the row from the candidate set — a blind spot in + exactly the direction this guard exists to close. + """ + ref = str(ref) + return bool(re.fullmatch(r"\s*(BR|SR)-[A-Za-z0-9_-]+\s*", ref)) and not _is_spec_artifact_ref(ref) + + +def _row_has_adcp_req_source(refs) -> bool: + """True if any of a traceability row's ``upstream_refs`` is an adcp-req requirement id.""" + return any(_is_adcp_req_id(ref) for ref in (refs or [])) + + +def _is_spec_artifact_ref(ref: str) -> bool: + """True if ``ref`` points at an AdCP spec ARTIFACT (a file or URL) rather than + an adcp-req requirement id. Retained for the discriminator self-test; the candidate + derivation now keys on ``_row_has_adcp_req_source`` so empty/unmodeled refs are caught. + """ + ref = str(ref) + if "://" in ref: + return True + return bool(re.search(r"\.(mdx|ya?ml|json|feature)(\b|#|$)", ref, re.IGNORECASE)) + + +def _is_merge_set_feature(feature_name: str) -> bool: + """True if the feature file is compiled/merged from adcp-req (so a source-less scenario + in it is a real LEGACY-DELETE risk), rather than a hand-authored feature the merger never + reaches. Hand-authored files carry a ``# Hand-authored feature`` header; the merge set is + everything else (the ``# DO NOT EDIT -- re-run: compile_bdd.py`` outputs).""" + path = FEATURES_DIR / feature_name + if not path.exists(): + return False + return "Hand-authored feature" not in path.read_text()[:500] + + +def _handmaintained_candidates_from_traceability(): + """Hand-maintained scenarios enumerated from the *independent* traceability + inventory (``bdd-traceability.yaml``), keyed ``(feature file, @T- id tag)``. + + A candidate is a MERGE-SET scenario with no adcp-req requirement id in its + ``upstream_refs`` — a spec artifact (``*.mdx``/URL), an unmodeled ref, OR an EMPTY + list. Such a scenario has no adcp-req render, so ``compile_bdd.py --merge`` classifies + it ``LEGACY-DELETE`` and drops it unless it carries a hand-edit marker. Keying on the + ABSENCE of a requirement id (not the presence of a recognized artifact form) catches + empty/unmodeled refs; scoping to merge-set files excludes hand-authored features the + merger never touches. Deriving the inventory here — NOT from the on-disk markers — is + what lets the guard see a scenario missing BOTH a marker and a registry entry. + """ + data = yaml.safe_load(TRACEABILITY_PATH.read_text()) or {} + candidates = [] + for rows in (data.get("mappings") or {}).values(): + for row in rows: + # Source-less = no adcp-req requirement id (catches spec-artifact, unmodeled, AND + # empty refs), AND the file is in the merge set (a hand-authored feature the merger + # never touches is not at LEGACY-DELETE risk, so it is not a candidate). + if _row_has_adcp_req_source(row.get("upstream_refs")): + continue + if not _is_merge_set_feature(row["adcp_feature"]): + continue + candidates.append((row["adcp_feature"], f"@{row['adcp_scenario_id']}")) + return candidates + + +def _all_feature_scenarios(compile_bdd): + """``(feature file, @T- id tag)`` for EVERY scenario in the compiled features.""" + out = [] + for feature_path in sorted(FEATURES_DIR.glob("*.feature")): + feature = compile_bdd.parse_feature_file(feature_path.read_text()) + for scenario in feature.scenarios: + sid = compile_bdd._extract_id_from_tags(scenario.tags) + if sid: + out.append((feature_path.name, f"@{sid}")) + return out + + +def _traceability_scenarios(): + """``(feature file, @T- id tag)`` for every row in the traceability inventory.""" + data = yaml.safe_load(TRACEABILITY_PATH.read_text()) or {} + return [ + (row["adcp_feature"], f"@{row['adcp_scenario_id']}") + for rows in (data.get("mappings") or {}).values() + for row in rows + ] + + +def _untracked_scenarios(compile_bdd): + """Compiled scenarios with NO traceability row at all — completely SOURCE-LESS. + + A scenario present in a feature file but absent from ``bdd-traceability.yaml`` has + no adcp-req (or hand-edit) provenance, so ``compile_bdd.py --merge`` classifies it + ``LEGACY-DELETE``. This closes the unguarded case where a scenario missing its + marker, registry entry, AND traceability row is invisible to any check that starts + from markers or from traceability — but it IS visible here, by comparing the + compiled feature files against the traceability inventory.""" + tracked = set(_traceability_scenarios()) + return [s for s in _all_feature_scenarios(compile_bdd) if s not in tracked] + + +def _marked_scenarios_on_disk(compile_bdd): + """Every scenario under ``features/`` carrying a hand-edit marker, keyed by + its ``(feature file, @T- id tag)`` — the same key shape as the registry.""" + marked = [] + for feature_path in sorted(FEATURES_DIR.glob("*.feature")): + feature = compile_bdd.parse_feature_file(feature_path.read_text()) + for scenario in feature.scenarios: + if not compile_bdd._has_hand_edited_marker(scenario): + continue + scenario_id = compile_bdd._extract_id_from_tags(scenario.tags) + tag = f"@{scenario_id}" if scenario_id else None + marked.append((feature_path.name, tag)) + return marked + + +def test_hand_maintained_scenarios_classify_legacy_preserve(): + """Each hand-maintained scenario must classify LEGACY-PRESERVE, not LEGACY-DELETE.""" + compile_bdd = _load_compiler() + + for feature_name, scenario_tag in HAND_MAINTAINED_SCENARIOS: + feature = compile_bdd.parse_feature_file((FEATURES_DIR / feature_name).read_text()) + matches = [s for s in feature.scenarios if scenario_tag in s.tags] + assert matches, f"{scenario_tag} not found in {feature_name} — was it dropped by a merge?" + for scenario in matches: + bucket = compile_bdd.classify_scenario_pair(scenario, None) + assert bucket == "LEGACY-PRESERVE", ( + f"{scenario_tag} in {feature_name} classifies {bucket}: the next " + f"compile_bdd.py --merge would delete it. " + f"Restore the @hand-edited tag or a # HAND-EDITED comment." + ) + + +def test_registry_is_bijection_with_marked_scenarios(): + """Registry ↔ marked SOURCE-LESS scenarios must match exactly. + + Direction 1 (marked source-less ⊆ registry): a hand-edited source-less + scenario missing from the registry would be dropped by ``--merge`` while the + classify test above stays green — it only checks scenarios already + registered. Direction 2 (registry ⊆ marked): a stale entry whose scenario + was renamed or lost its marker must surface, not silently pass. + + Scoped to the source-less candidate universe (same derivation as the + completeness test below): a marked scenario that HAS a proper adcp-req + source (upstream hand-edits arriving via main merges) is protected by its + marker in ``classify_scenario_pair`` and needs no registry entry — the + registry is exactly the source-less set, so the two tests can't demand + contradictory registrations for it. + """ + compile_bdd = _load_compiler() + candidates = set(_handmaintained_candidates_from_traceability()) | set(_untracked_scenarios(compile_bdd)) + + assert_violations_match_allowlist( + found=set(_marked_scenarios_on_disk(compile_bdd)) & candidates, + allowlist=set(HAND_MAINTAINED_SCENARIOS), + fix_hint=( + "A hand-edited SOURCE-LESS scenario (an @hand-edited tag or # HAND-EDITED comment " + "under tests/bdd/features/, with a spec-artifact upstream_ref or no traceability row) " + "must appear in HAND_MAINTAINED_SCENARIOS, and every registry entry must still exist " + "and carry its marker. Add new ones; drop or re-mark stale ones." + ), + ) + + +def test_is_spec_artifact_ref_discriminates_source_from_requirement_id(): + """Self-test for the scenario-discovery discriminator so a silently-degraded + ``_is_spec_artifact_ref`` (a broken regex, a traceability-schema drift) can't empty the + candidate set and let the set-equality guards below pass vacuously — the guard "passes when + the candidate set is empty" only in its stale direction. Mirrors the committed known-bad/good + detector self-test in ``test_architecture_no_raw_select.py::TestColumnSelectDetection``. + """ + # POSITIVE — a source-less scenario grounds itself in a spec ARTIFACT (prose/storyboard/schema + # by path or URL); each must be recognized as a candidate ref. + for ref in ( + "dist/docs/3.1.1/media-buy/task-reference/create_media_buy.mdx", + "dist/compliance/3.1.1/uc-004.yaml", + "dist/compliance/3.1.1/uc-004.yml", + "schemas/v1/media-buy.json", + "https://github.com/adcontextprotocol/adcp/blob/main/spec.mdx", + "docs/foo.mdx#create-media-buy", + ): + assert _is_spec_artifact_ref(ref) is True, f"{ref!r} is a spec artifact and must be detected" + # NEGATIVE — a bare adcp-req requirement id renders from adcp-req (not source-less); must NOT match. + for ref in ("BR-UC-004-MAIN-01", "SR-RULE-055", "adcp-req-123", "UC-004"): + assert _is_spec_artifact_ref(ref) is False, f"{ref!r} is a requirement id, not a spec artifact" + + +def test_source_less_predicate_catches_empty_and_unmodeled_refs(): + """The candidate predicate keys on ABSENCE of an adcp-req id, so an empty or unmodeled + ``upstream_refs`` is discovered, not only recognized spec-artifact + extensions. Known-bad/good self-test so a degraded predicate can't empty the candidate set.""" + # adcp-req-sourced rows are NOT source-less (BR-*/SR- present anywhere in the list). + assert _row_has_adcp_req_source(["BR-UC-004-MAIN-01"]) is True + assert _row_has_adcp_req_source(["transport-errors.mdx#x", "SR-RULE-055"]) is True + # Source-less shapes the OLD spec-artifact predicate would have missed: + assert _row_has_adcp_req_source([]) is False # empty — the exact miss this fix closes + assert _row_has_adcp_req_source(["docs/x.md#Anchor"]) is False # unmodeled extension + assert _row_has_adcp_req_source(["building/operating/transport-errors"]) is False # bare path + assert _row_has_adcp_req_source(["spec.txt"]) is False + # A ref NAMED like a requirement id but pointing at an artifact is not a requirement id — + # our own feature files are called BR-UC-*.feature, so a bare-prefix match would read this + # as adcp-req-sourced and silently drop the row from the candidate set. + assert _row_has_adcp_req_source(["BR-UC-002-create-media-buy.feature"]) is False + assert _row_has_adcp_req_source(["BR-UC-002.mdx"]) is False + assert _row_has_adcp_req_source(["https://example.test/BR-UC-002"]) is False + + +def test_merge_set_scoping_excludes_hand_authored_features(): + """Source-less rows in a HAND-AUTHORED feature (the merger never reaches them) are not + LEGACY-DELETE candidates; source-less rows in a merge-set (# DO NOT EDIT) file are.""" + # The one registered hand-maintained scenario lives in a merge-set file and must be in scope. + assert _is_merge_set_feature("BR-UC-002-create-media-buy.feature") is True + # Hand-authored features (their empty-ref rows must NOT become candidates). + assert _is_merge_set_feature("BR-ADMIN-ACCOUNTS.feature") is False + assert _is_merge_set_feature("BR-UC-002-account-access.feature") is False + + +def test_source_less_scenarios_are_marked_and_registered(): + """Independent-source completeness — every SOURCE-LESS compiled scenario must be + registered (and, via the bijection above, marked). + + The marker-derived checks above cannot see a scenario missing BOTH a marker and a + registry entry. This check derives candidates two independent ways so no orphan + hides: + + * spec-grounded — a traceability row whose ``upstream_refs`` point at a spec + artifact (``*.mdx``/``*.yaml``/``*.json``/URL), which has no adcp-req render; and + * untracked — a compiled scenario with NO traceability row at all. + + Both are ``LEGACY-DELETE`` risks, so the union must equal the registry. This closes + the adversarial case where an unmarked scenario has no registry entry and no + traceability row is invisible to marker- or traceability-only scans, but appears here + as an untracked candidate. + """ + compile_bdd = _load_compiler() + candidates = set(_handmaintained_candidates_from_traceability()) | set(_untracked_scenarios(compile_bdd)) + + assert_violations_match_allowlist( + found=candidates, + allowlist=set(HAND_MAINTAINED_SCENARIOS), + fix_hint=( + "A source-less scenario — grounded in a spec artifact (upstream_refs → *.mdx/*.yaml/" + "*.json) OR with no traceability row at all — would be LEGACY-DELETE'd by " + "compile_bdd.py --merge. It must carry an @hand-edited / # HAND-EDITED marker AND be " + "registered in HAND_MAINTAINED_SCENARIOS (or be given a proper adcp-req source + " + "traceability row)." + ), + ) diff --git a/tests/unit/test_architecture_behavioral_mock_cap.py b/tests/unit/test_architecture_behavioral_mock_cap.py index 0b26df6adc..f08a07b324 100644 --- a/tests/unit/test_architecture_behavioral_mock_cap.py +++ b/tests/unit/test_architecture_behavioral_mock_cap.py @@ -34,7 +34,7 @@ # Frozen at the current count; can only shrink. New behavioral files with mock # constructions fail immediately (force a deliberate cap entry or harness use). BEHAVIORAL_MOCK_CONSTRUCTION_CAP: dict[str, int] = { - "tests/integration/test_create_media_buy_behavioral.py": 38, + "tests/integration/test_create_media_buy_behavioral.py": 35, "tests/integration/test_creative_sync_behavioral.py": 1, "tests/integration/test_delivery_poll_behavioral.py": 2, "tests/integration/test_delivery_webhook_behavioral.py": 5, diff --git a/tests/unit/test_architecture_boundary_completeness.py b/tests/unit/test_architecture_boundary_completeness.py index 159f2852a2..39a2944284 100644 --- a/tests/unit/test_architecture_boundary_completeness.py +++ b/tests/unit/test_architecture_boundary_completeness.py @@ -44,8 +44,20 @@ # Format: "module::impl_name::wrapper_kind::param_name" KNOWN_VIOLATIONS: set[str] = set() -# Parameters resolved at the boundary, not forwarded from the caller -BOUNDARY_RESOLVED_PARAMS = {"identity"} +# Parameters resolved at the boundary, not forwarded from the caller — keyed to the +# wrapper KINDS they are resolved for, so an exemption for one transport does not blind +# the others. ``identity`` is resolved at every boundary. ``external_task_id`` is the +# transport's OUTER async task id: only the A2A boundary has one (the ``task_*`` returned +# to the buyer), and it MUST forward it — MCP/REST have no outer id and legitimately do +# not. Exempting it for A2A too would leave the A2A forwarding unguarded (deleting it +# would keep the guard green). +_ALL_WRAPPER_KINDS = frozenset({"mcp", "a2a", "rest"}) +BOUNDARY_RESOLVED_PARAMS: dict[str, frozenset[str]] = { + "identity": _ALL_WRAPPER_KINDS, + "external_task_id": frozenset({"mcp", "rest"}), +} +# Params resolved at EVERY boundary — stripped from the impl-param list before checking. +_UNIVERSALLY_RESOLVED = frozenset(p for p, kinds in BOUNDARY_RESOLVED_PARAMS.items() if kinds == _ALL_WRAPPER_KINDS) def _module_to_filepath(module_path: str) -> Path: @@ -66,7 +78,7 @@ def _get_impl_params(module_path: str, func_name: str) -> list[str]: mod = importlib.import_module(module_path) func = getattr(mod, func_name) sig = inspect.signature(func) - return [name for name in sig.parameters if name not in BOUNDARY_RESOLVED_PARAMS] + return [name for name in sig.parameters if name not in _UNIVERSALLY_RESOLVED] def _find_wrapper_info(module_path: str, impl_name: str) -> dict: @@ -156,7 +168,7 @@ def _check_wrapper_completeness( violations = [] for kwargs, n_positional in call_arg_sets: for i, param in enumerate(impl_params): - if param in BOUNDARY_RESOLVED_PARAMS: + if wrapper_kind in BOUNDARY_RESOLVED_PARAMS.get(param, frozenset()): continue key = f"{module_path}::{impl_name}::{wrapper_kind}::{param}" if param not in kwargs and i >= n_positional: diff --git a/tests/unit/test_architecture_capability_constant_parity.py b/tests/unit/test_architecture_capability_constant_parity.py index e4265a27c3..d5eaa3279d 100644 --- a/tests/unit/test_architecture_capability_constant_parity.py +++ b/tests/unit/test_architecture_capability_constant_parity.py @@ -15,9 +15,8 @@ """ import ast -from pathlib import Path -from tests.unit._architecture_helpers import iter_call_expressions +from tests.unit._architecture_helpers import REPO_ROOT, iter_call_expressions # Capability keywords whose value must be derived from an enforced constant, not a literal. _DERIVED_CAPABILITY_KEYWORDS = {"replay_ttl_seconds"} @@ -47,7 +46,11 @@ def test_capability_values_are_derived_not_literal(): silently (the #1b bug class). """ offenders: list[str] = [] - for path in Path("src").rglob("*.py"): + # Anchored on the repo root derived from __file__, not the cwd: a cwd-relative glob + # silently matches nothing when pytest runs from anywhere else, and a guard that scans + # zero files passes rather than fails (same escape as _discover_integration_test_files + # in test_architecture_repository_pattern.py). + for path in (REPO_ROOT / "src").rglob("*.py"): try: for site in _literal_capability_sites_in(path.read_text()): offenders.append(f"{path}:{site.split('@')[1]} ({site.split('@')[0]})") diff --git a/tests/unit/test_architecture_error_recovery_enum_conformance.py b/tests/unit/test_architecture_error_recovery_enum_conformance.py index e5e70bcf3d..901787a3d6 100644 --- a/tests/unit/test_architecture_error_recovery_enum_conformance.py +++ b/tests/unit/test_architecture_error_recovery_enum_conformance.py @@ -32,13 +32,13 @@ import pytest from src.core.exceptions import ERROR_CODE_MAPPING, AdCPError, translate_error_code -from tests.helpers import pinned_schema +from tests.helpers.pinned_schema import pinned_error_code_metadata def _pinned_recovery_by_code() -> dict[str, str]: """Return ``{error_code: recovery}`` from the pinned enumMetadata block.""" - meta = pinned_schema.load("error-code.json")["enumMetadata"] - return {code: entry["recovery"] for code, entry in meta.items() if isinstance(entry, dict) and "recovery" in entry} + meta = pinned_error_code_metadata() + return {code: entry["recovery"] for code, entry in meta.items() if "recovery" in entry} _RECOVERY_BY_CODE = _pinned_recovery_by_code() @@ -148,3 +148,20 @@ def test_internal_only_codes_are_documented() -> None: f"escape the recovery oracle. Either add the code to the AdCP error-code enum (and the " f"pin) or, if it is genuinely internal-only, add it to known_internal here." ) + + +@pytest.mark.parametrize("code", ["AUTH_MISSING", "AUTH_INVALID"]) +def test_production_emitted_auth_codes_are_graded(code: str) -> None: + """The auth codes production emits are in the vocabulary this oracle grades against. + + The AUTH_MISSING/AUTH_INVALID split is emitted at every wire boundary, so the + codes must resolve in the pinned enum or the split silently escapes grading + (the parametrized oracle above only walks codes present in ``_RECOVERY_BY_CODE``). + They exist only in the installed SDK's enum, not in the older vendored fixture + the sibling suggestion oracle reads — which is the concrete reason this reader + resolves through the SDK tree. + """ + assert code in _RECOVERY_BY_CODE, ( + f"{code} is emitted by production but absent from the pinned error-code enum, " + "so its recovery classification is ungraded." + ) diff --git a/tests/unit/test_architecture_error_suggestion_enum_conformance.py b/tests/unit/test_architecture_error_suggestion_enum_conformance.py index d7e9d582d3..2855e74340 100644 --- a/tests/unit/test_architecture_error_suggestion_enum_conformance.py +++ b/tests/unit/test_architecture_error_suggestion_enum_conformance.py @@ -16,22 +16,16 @@ from __future__ import annotations -import json -from pathlib import Path - import pytest from src.core import exceptions - -_PINNED_ENUM_PATH = Path(__file__).parent.parent / "fixtures" / "adcp_schemas_pinned" / "enums" / "error-code.json" +from tests.helpers.pinned_schema import pinned_error_code_metadata def _pinned_suggestion_by_code() -> dict[str, str]: """Return ``{error_code: suggestion}`` from the pinned enumMetadata block.""" - meta = json.loads(_PINNED_ENUM_PATH.read_text())["enumMetadata"] - return { - code: entry["suggestion"] for code, entry in meta.items() if isinstance(entry, dict) and entry.get("suggestion") - } + meta = pinned_error_code_metadata() + return {code: entry["suggestion"] for code, entry in meta.items() if entry.get("suggestion")} _SUGGESTION_BY_CODE = _pinned_suggestion_by_code() @@ -40,6 +34,8 @@ def _pinned_suggestion_by_code() -> dict[str, str]: # canonical buyer-facing suggestion. Add a row when a new canonical-suggestion # constant is introduced so it is pinned to the spec from birth. _CANONICAL_SUGGESTION_CONSTANTS = [ + ("AUTH_REQUIRED_CANONICAL_SUGGESTION", "AUTH_REQUIRED"), + ("AUTH_REQUIRED_SUGGESTION", "AUTH_REQUIRED"), ("INVALID_REQUEST_SUGGESTION", "INVALID_REQUEST"), ("VALIDATION_ERROR_SUGGESTION", "VALIDATION_ERROR"), ] @@ -51,6 +47,9 @@ def test_pinned_enum_suggestions_loaded() -> None: assert len(_SUGGESTION_BY_CODE) >= 50, ( f"Expected the pinned enumMetadata to define suggestions for many codes, got {len(_SUGGESTION_BY_CODE)}" ) + assert "$comment" not in pinned_error_code_metadata(), ( + "Schema annotations must not leak through the typed error-code metadata accessor" + ) @pytest.mark.parametrize( diff --git a/tests/unit/test_architecture_local_schema_imports.py b/tests/unit/test_architecture_local_schema_imports.py index a2024e1e4a..52257421a4 100644 --- a/tests/unit/test_architecture_local_schema_imports.py +++ b/tests/unit/test_architecture_local_schema_imports.py @@ -52,7 +52,6 @@ def _get_local_schema_names() -> set[str]: ("src/adapters/xandr.py", "DeliveryMeasurement"), ("src/adapters/xandr.py", "DeliveryType"), # FIXME(#1388): admin blueprints import SDK types directly - ("src/admin/blueprints/operations.py", "Package"), # FIXME(#1388): core modules import SDK types directly ("src/core/creative_agent_registry.py", "ListCreativeFormatsRequest"), ("src/core/schema_helpers.py", "GetProductsResponse"), diff --git a/tests/unit/test_architecture_no_error_code_kwarg_in_impl.py b/tests/unit/test_architecture_no_error_code_kwarg_in_impl.py index 1d110dcc03..75db3e2e5c 100644 --- a/tests/unit/test_architecture_no_error_code_kwarg_in_impl.py +++ b/tests/unit/test_architecture_no_error_code_kwarg_in_impl.py @@ -3,12 +3,12 @@ The wire error code is the identity of a typed AdCPError subclass. Passing ``error_code=`` to an ``AdCP*Error(...)`` constructor bypasses that hierarchy and can leak a code that is neither standard nor mapped (the original A1 defect). The -only sanctioned override is ``AdCPError.synthesize(error_code=...)``, used by the two -boundary helpers that must construct a wire code the class hierarchy does not model. +only sanctioned override is ``AdCPError.synthesize(error_code=...)``, used by the +shared scrub constructor for wire codes the class hierarchy does not model. This guard scans ``src/core/`` and ``src/adapters/`` for any call that passes ``error_code=`` to an ``AdCP*Error`` constructor OR to ``.synthesize()``. After the -error-emission migration, the only such calls are the two ``synthesize()`` sites — +error-emission migration, the only such call is the shared ``_scrubbed_error`` site — pinned in the allowlist so a new bypass (or a new synthesize caller) fails the build. """ @@ -21,12 +21,11 @@ REPO_ROOT = Path(__file__).resolve().parents[2] SCAN_DIRS = [REPO_ROOT / "src" / "core", REPO_ROOT / "src" / "adapters"] -# The only sanctioned error_code= sites: the two boundary helpers that call +# The only sanctioned error_code= site: the shared scrub constructor that calls # AdCPError.synthesize(). Keyed by (relative_path, enclosing_function_name) so the -# allowlist survives line-number shifts. This cap is exactly two. +# allowlist survives line-number shifts. KNOWN_VIOLATIONS = { - ("src/core/context_manager.py", "audit_workflow_step_failure"), - ("src/core/tool_error_logging.py", "handle_tool_error"), + ("src/core/exceptions.py", "_scrubbed_error"), } @@ -94,10 +93,10 @@ def _find_error_code_in_details() -> list[tuple[str, str, int]]: class TestNoErrorCodeKwargInImpl: - """error_code= on AdCPError constructors/synthesize is allowlisted to two sites.""" + """error_code= on AdCPError constructors/synthesize is allowlisted to one site.""" def test_no_new_error_code_kwargs(self): - """No NEW error_code= bypass beyond the two sanctioned synthesize() callers.""" + """No NEW error_code= bypass beyond the shared scrub constructor.""" new_violations = [ f" {rel}:{lineno} in {func}()" for rel, func, lineno in _find_error_code_kwargs() @@ -106,7 +105,7 @@ def test_no_new_error_code_kwargs(self): assert not new_violations, ( f"Found {len(new_violations)} NEW error_code= site(s) on AdCP*Error/synthesize.\n" "Raise a typed AdCPError subclass instead; the only sanctioned override is " - "AdCPError.synthesize() at the two allowlisted boundary helpers.\n" + "\n".join(new_violations) + "AdCPError.synthesize() at the allowlisted shared scrub constructor.\n" + "\n".join(new_violations) ) def test_known_violations_not_stale(self): @@ -118,8 +117,8 @@ def test_known_violations_not_stale(self): fix_hint="Remove fixed entries from KNOWN_VIOLATIONS.", ) - def test_violation_count_capped_at_two(self): - """Exactly two sanctioned error_code= sites exist (the synthesize() callers).""" + def test_violation_count_capped_at_one(self): + """Exactly one sanctioned error_code= site exists.""" all_sites = {(rel, func) for rel, func, _ in _find_error_code_kwargs()} msg = f"error_code= sites changed.\nFound: {sorted(all_sites)}\nAllowlist: {sorted(KNOWN_VIOLATIONS)}" assert all_sites == KNOWN_VIOLATIONS, msg diff --git a/tests/unit/test_architecture_no_raw_select.py b/tests/unit/test_architecture_no_raw_select.py index bd9a673c77..ab0ede5e04 100644 --- a/tests/unit/test_architecture_no_raw_select.py +++ b/tests/unit/test_architecture_no_raw_select.py @@ -174,7 +174,6 @@ def _discover_orm_model_names() -> set[str]: ("src/admin/blueprints/operations.py", "media_buy_detail"), ("src/admin/blueprints/operations.py", "reporting"), ("src/admin/blueprints/policy.py", "index"), - ("src/admin/blueprints/policy.py", "review_task"), ("src/admin/blueprints/policy.py", "update"), ("src/admin/blueprints/principals.py", "create_principal"), ("src/admin/blueprints/principals.py", "delete_principal"), @@ -236,7 +235,6 @@ def _discover_orm_model_names() -> set[str]: ("src/admin/blueprints/users.py", "remove_domain"), ("src/admin/blueprints/users.py", "toggle_user"), ("src/admin/blueprints/users.py", "update_role"), - ("src/admin/blueprints/workflows.py", "approve_workflow_step"), # select(CreativeAssignment) — no creative repo yet ("src/admin/blueprints/workflows.py", "list_workflows"), # select(Tenant) — no tenant repo yet ("src/admin/blueprints/workflows.py", "review_workflow_step"), # select(Context) — context lookup # ── Admin services / utils ── @@ -288,7 +286,6 @@ def _discover_orm_model_names() -> set[str]: ("src/core/context_manager.py", "get_pending_steps"), ("src/core/context_manager.py", "link_workflow_to_object"), ("src/core/context_manager.py", "update_activity"), - ("src/core/context_manager.py", "update_workflow_step"), ("src/core/database/queries.py", "get_ai_accuracy_metrics"), ("src/core/database/queries.py", "get_ai_review_stats"), ("src/core/database/queries.py", "get_creative_reviews"), @@ -394,6 +391,45 @@ def _find_raw_selects() -> list[tuple[str, str, str, int]]: # ── Tests ─────────────────────────────────────────────────────────── +class TestColumnSelectDetection: + """Known-bad case: a column-select of an ORM model is a raw model query too. + + Documents and locks the detector gap that let + ``select(DBContext.tenant_id)`` in ContextManager slip through: the bare + ``select_call_model_name`` resolves ``select(Model.column)`` to the column name, + so matching against ORM model names misses it. ``select_target_model_name`` + closes that gap. (The actual violation was removed by moving tenant resolution + into ``WorkflowRepository.resolve_tenant_for_step``; enabling this detector across + all of src/ requires migrating ~30 pre-existing column-selects and is tracked in + a dedicated follow-up.) + """ + + def _select_call(self, expr: str) -> ast.Call: + node = ast.parse(expr, mode="eval").body + assert isinstance(node, ast.Call) + return node + + def test_bare_resolver_misses_column_select(self): + from tests.unit._architecture_helpers import select_call_model_name + + call = self._select_call("select(DBContext.tenant_id)") + # The bare resolver returns the COLUMN name, so an ORM-model-name match misses it. + assert select_call_model_name(call) == "tenant_id" + assert select_call_model_name(call) not in ORM_MODEL_NAMES + + def test_column_aware_resolver_flags_column_select_of_model(self): + from tests.unit._architecture_helpers import select_target_model_name + + models = {"DBContext", "WorkflowStep"} + # select(Model.column) → the MODEL is flagged (a raw model query). + assert select_target_model_name(self._select_call("select(DBContext.tenant_id)"), models) == "DBContext" + # select(Model) and select(pkg.Model) still resolve to the model. + assert select_target_model_name(self._select_call("select(WorkflowStep)"), models) == "WorkflowStep" + assert select_target_model_name(self._select_call("select(mod.WorkflowStep)"), models) == "WorkflowStep" + # A non-model column select is not flagged. + assert select_target_model_name(self._select_call("select(func.count())"), models) is None + + class TestNoRawSelectOutsideRepositories: """No raw select(OrmModel) outside repository/infrastructure files.""" diff --git a/tests/unit/test_architecture_repository_pattern.py b/tests/unit/test_architecture_repository_pattern.py index 6934d971a4..17e5a90e9f 100644 --- a/tests/unit/test_architecture_repository_pattern.py +++ b/tests/unit/test_architecture_repository_pattern.py @@ -18,9 +18,7 @@ import pytest -from tests.unit._architecture_helpers import assert_violations_match_allowlist, iter_call_expressions - -ROOT = Path(__file__).resolve().parents[2] +from tests.unit._architecture_helpers import REPO_ROOT, assert_violations_match_allowlist, iter_call_expressions # --------------------------------------------------------------------------- # Invariant 1: No get_db_session() in _impl functions @@ -64,19 +62,31 @@ def _discover_integration_test_files() -> list[str]: conftest.py files. These suites all exercise real DB state and must use factories, not inline session.add() / get_db_session() in test bodies. - Also scans every module under tests/helpers/. Shared DB-seed helpers there are - not named test_*.py but must follow the same factory-only rule, so that new + Also scans every module under tests/helpers/ AND tests/utils/. Shared DB-seed helpers + there are not named test_*.py but must follow the same factory-only rule, so that new session.add() debt in helper code is caught at the source rather than hidden - behind a module the guard never reads. + behind a module the guard never reads. tests/utils/ was outside the scan set while + holding shared harness helpers — the same escape hatch tests/helpers/ was added to close; + a directory the guard does not read is a place debt can land unseen. + + Globs are anchored on the repo root derived from ``__file__``, not the cwd: a cwd-relative + glob silently matches NOTHING when pytest is invoked from anywhere else, and a guard that + scans zero files passes rather than fails. Same escape closed in + test_architecture_capability_constant_parity.py, which had the identical cwd-relative + ``Path("src").rglob(...)`` defect. """ + root_dir = REPO_ROOT roots = ("tests/integration*", "tests/admin", "tests/e2e") test_files: list[str] = [] conftest_files: list[str] = [] for root in roots: - test_files.extend(glob.glob(f"{root}/**/test_*.py", recursive=True)) - conftest_files.extend(glob.glob(f"{root}/conftest.py", recursive=True)) - helper_files = glob.glob("tests/helpers/**/*.py", recursive=True) - return sorted(set(test_files + conftest_files + helper_files)) + test_files.extend(glob.glob(str(root_dir / root / "**" / "test_*.py"), recursive=True)) + conftest_files.extend(glob.glob(str(root_dir / root / "**" / "conftest.py"), recursive=True)) + helper_files = glob.glob(str(root_dir / "tests" / "helpers" / "**" / "*.py"), recursive=True) + util_files = glob.glob(str(root_dir / "tests" / "utils" / "**" / "*.py"), recursive=True) + discovered = test_files + conftest_files + helper_files + util_files + # Return repo-relative paths so the allowlist keys stay stable regardless of checkout path. + return sorted({str(Path(p).resolve().relative_to(root_dir)) for p in discovered}) INTEGRATION_TEST_FILES = _discover_integration_test_files() @@ -512,7 +522,7 @@ def _find_matching_calls(file_path: str, predicate: Callable[[ast.expr], bool]) Returns list of (file_path, function_name, line_number) — one per function. """ - source_path = ROOT / file_path + source_path = REPO_ROOT / file_path if not source_path.exists(): return [] @@ -686,7 +696,6 @@ def test_allowlist_entries_still_exist(self): ("tests/admin/test_product_creation_integration.py", "test_list_products_json_parsing"), ("tests/admin/test_product_creation_integration.py", "test_tenant"), ("tests/admin/test_workflows_blueprint.py", "_create_context_and_step"), - ("tests/admin/test_workflows_blueprint.py", "test_approve_step_sets_status_approved"), ("tests/admin/test_workflows_blueprint.py", "test_reject_step_sets_status_rejected"), ("tests/admin/test_workflows_blueprint.py", "test_reject_step_without_reason_uses_default"), ("tests/admin/test_workflows_blueprint.py", "test_tenant"), diff --git a/tests/unit/test_architecture_resolved_identity_inline_cap.py b/tests/unit/test_architecture_resolved_identity_inline_cap.py index 234b73b122..1cb8d04899 100644 --- a/tests/unit/test_architecture_resolved_identity_inline_cap.py +++ b/tests/unit/test_architecture_resolved_identity_inline_cap.py @@ -77,7 +77,7 @@ "tests/unit/test_delivery.py": 2, "tests/unit/test_delivery_poll_behavioral.py": 3, "tests/unit/test_dry_run_no_persistence.py": 1, - "tests/unit/test_error_format_consistency.py": 9, + "tests/unit/test_error_format_consistency.py": 8, "tests/unit/test_gam_placement_targeting.py": 2, "tests/unit/test_get_media_buys_architecture.py": 2, "tests/unit/test_get_products_impl_coverage.py": 1, diff --git a/tests/unit/test_architecture_rest_body_completeness.py b/tests/unit/test_architecture_rest_body_completeness.py index 52307b4f25..37da317ca0 100644 --- a/tests/unit/test_architecture_rest_body_completeness.py +++ b/tests/unit/test_architecture_rest_body_completeness.py @@ -39,8 +39,10 @@ # Raw-wrapper parameters that are transport plumbing, never buyer-facing body fields. # Server-injected plumbing, never buyer-supplied body fields: ctx/identity are # resolved at the transport boundary; raw_wire_payload is the raw wire request -# body captured server-side for idempotency hashing (FastAPI raw_json_body dependency). -_TRANSPORT_PARAMS = {"ctx", "identity", "raw_wire_payload"} +# body captured server-side for idempotency hashing (FastAPI raw_json_body dependency); +# external_task_id is the A2A boundary's outer task_* id threaded for webhook/poll +# correlation — REST/MCP have no outer id, so a buyer must not set it. +_TRANSPORT_PARAMS = {"ctx", "identity", "raw_wire_payload", "external_task_id"} # Body-only meta field (not a raw-wrapper param). _BODY_META = {"adcp_version"} diff --git a/tests/unit/test_architecture_static_validation_message_opt_in.py b/tests/unit/test_architecture_static_validation_message_opt_in.py new file mode 100644 index 0000000000..183a241bc2 --- /dev/null +++ b/tests/unit/test_architecture_static_validation_message_opt_in.py @@ -0,0 +1,230 @@ +"""Guard: a bare static validation message must opt in to reaching the wire. + +``safe_adcp_error`` scrubs an ``AdCPValidationError``'s message by default, because +business validators frequently interpolate rejected request values. That default is +right for interpolated messages and pure collateral damage for a bare string literal: +there is no request-derived value in a constant, so nothing can leak, and genericizing +it costs the buyer the one diagnostic they could have acted on — for errors whose +``recovery`` is ``correctable``, i.e. exactly the ones the buyer is expected to fix. + +This guard scans ``src/`` for ``AdCP{Validation,InvalidRequest}Error(...)`` calls whose +FIRST positional argument is a plain string literal and which do NOT pass +``_wire_safe_message=True``. Interpolated messages (f-strings, ``.format()``, ``+``, +variables) are deliberately out of scope: those need a per-site audit of what they +interpolate, tracked separately, and must keep scrubbing until that audit happens. + +Why a guard and not a one-time sweep: 31 such sites had accumulated by the time this +was noticed, all silently downgraded the moment the scrub landed. Nothing failed — +the wire contract stayed valid (code/recovery/status/field are all preserved), only +the human-readable half regressed, which no existing assertion covered. +""" + +import ast +from pathlib import Path + +from tests.unit._architecture_helpers import assert_violations_match_allowlist, iter_call_expressions + +REPO_ROOT = Path(__file__).resolve().parents[2] +SCAN_DIR = REPO_ROOT / "src" + + +def _target_class_names() -> set[str]: + """The class names the scrub actually applies to, derived from the closure. + + ``safe_adcp_error`` gates on ``isinstance(exc, AdCPValidationError)``, so the + scanned set is ``AdCPValidationError`` plus every subclass, transitively — NOT a + hand-listed pair. A new subclass would otherwise be scrubbed by production while + invisible to this guard, which is the exact silent downgrade the guard exists to + catch. + """ + from src.core.exceptions import AdCPValidationError + + names = {AdCPValidationError.__name__} + frontier = [AdCPValidationError] + while frontier: + for sub in frontier.pop().__subclasses__(): + if sub.__name__ not in names: + names.add(sub.__name__) + frontier.append(sub) + return names + + +_TARGET_CLASSES = _target_class_names() + +# Empty by design. A new bare-literal raise site without the opt-in is a diagnostic +# regression, not debt to be parked here — add ``_wire_safe_message=True`` instead. +# Only add an entry if a literal message genuinely must be scrubbed, with the reason. +KNOWN_VIOLATIONS: set[tuple[str, int]] = set() + +# The OTHER direction, and the one that can actually leak: an INTERPOLATED message that +# opts in. Each entry is an assertion that a human traced every interpolated value to +# something the buyer already has — their own request data or a sanitized projection — +# and never to adapter, DB or seller internals. Keep this small; a new entry is a claim +# about a specific f-string, not a place to park an unreviewed site. +AUDITED_INTERPOLATED_OPT_INS: dict[tuple[str, int], str] = { + ( + "src/core/tools/media_buy_create.py", + 2567, + ): "interpolates the duplicate product_ids from the buyer's OWN packages[] — their data, echoed back", + ( + "src/core/tools/media_buy_create.py", + 2923, + ): "interpolates targeting-validator violations describing the buyer's OWN targeting_overlay", + ( + "src/core/validation_helpers.py", + 57, + ): "format_validation_error() — the sanitized Pydantic projection: field paths and error types, never raw msg/input/ctx", +} + + +def _message_expr(node: ast.Call) -> ast.expr | None: + """The expression supplying the error message, positional OR ``message=`` kwarg. + + Reading only ``args[0]`` made the kwarg form invisible to this guard, so a site + written ``AdCPValidationError(message="...")`` was scanned by neither direction. + """ + if node.args: + return node.args[0] + for kw in node.keywords: + if kw.arg == "message": + return kw.value + return None + + +def _is_bare_string_literal_message(node: ast.Call) -> bool: + """True iff the message expression is a plain string constant. + + An f-string is an ``ast.JoinedStr`` and a concatenation is an ``ast.BinOp``, so + neither matches here — only a literal (including implicit adjacent-string + concatenation, which the parser folds into one ``ast.Constant``). + """ + expr = _message_expr(node) + return isinstance(expr, ast.Constant) and isinstance(expr.value, str) + + +def _iter_target_calls(): + """Yield ``(relative_path, node)`` for every construction of a target class.""" + for path in sorted(SCAN_DIR.rglob("*.py")): + try: + tree = ast.parse(path.read_text()) + except SyntaxError: # pragma: no cover - a syntax error fails elsewhere, loudly + continue + rel = str(path.relative_to(REPO_ROOT)) + for cls_name in sorted(_TARGET_CLASSES): + # iter_call_expressions also matches attribute calls (mod.AdCP...); + # both forms are equally in scope for this guard. + for node in iter_call_expressions(tree, cls_name): + yield rel, node + + +def _opts_in(node: ast.Call) -> bool: + return any(kw.arg == "_wire_safe_message" for kw in node.keywords) + + +def _iter_unopted_literal_sites() -> list[tuple[str, int, str]]: + """Yield (relative_path, lineno, message_prefix) for each unopted literal site.""" + violations: list[tuple[str, int, str]] = [] + for rel, node in _iter_target_calls(): + if _opts_in(node) or not _is_bare_string_literal_message(node): + continue + expr = _message_expr(node) + assert isinstance(expr, ast.Constant) + violations.append((rel, node.lineno, expr.value[:60])) + return violations + + +def _iter_unaudited_interpolated_opt_ins() -> list[tuple[str, int]]: + """Yield each INTERPOLATED message that opts in without an audit entry.""" + return [ + (rel, node.lineno) + for rel, node in _iter_target_calls() + if _opts_in(node) + and _message_expr(node) is not None + and not _is_bare_string_literal_message(node) + and (rel, node.lineno) not in AUDITED_INTERPOLATED_OPT_INS + ] + + +def test_static_validation_messages_opt_in_to_the_wire(): + """A bare literal message must carry ``_wire_safe_message=True``. + + Fails loudly with each offending site so the fix is a one-line edit at a named + location, not a hunt. + """ + violations = _iter_unopted_literal_sites() + unexpected = [(f, ln, msg) for f, ln, msg in violations if (f, ln) not in KNOWN_VIOLATIONS] + + assert not unexpected, ( + "Bare static validation message(s) will be scrubbed off the wire for no security " + "benefit — a literal interpolates nothing, so there is nothing to leak.\n" + "Add `_wire_safe_message=True` to each site below:\n" + + "\n".join(f" {f}:{ln} {msg!r}" for f, ln, msg in unexpected) + ) + + +def test_interpolated_opt_ins_match_the_audit_list_exactly(): + """An INTERPOLATED message may reach the wire only with an audit entry, and every + audit entry must still point at one. + + This is the direction that can actually leak, and the guard originally checked only + the other one. A bare literal interpolates nothing, so opting it in is safe by + construction; an f-string can carry whatever is in scope — an adapter response, a + connection string, another principal's data — and ``_wire_safe_message=True`` on it + is an unreviewed assertion that it does not. + + Exact-match rather than one-directional, so both failure modes are caught by one + assertion: + + * a NEW interpolated opt-in with no audit entry — trace every interpolated value to + buyer-supplied data or a sanitized projection before adding it; + * a STALE entry whose site was deleted, reworded to a literal, or had its opt-in + removed — a licence nobody is using, which left in place silently pre-approves + whatever later lands on that line. + """ + live = { + (rel, node.lineno) + for rel, node in _iter_target_calls() + if _opts_in(node) and _message_expr(node) is not None and not _is_bare_string_literal_message(node) + } + + assert_violations_match_allowlist( + live, + set(AUDITED_INTERPOLATED_OPT_INS), + fix_hint=( + "An f-string reaching the buyer wire can carry adapter/DB/seller internals. " + "Trace every interpolated value to the buyer's own request data or a sanitized " + "projection, then record that reason in AUDITED_INTERPOLATED_OPT_INS." + ), + ) + + +def test_guard_detects_a_bare_literal_site(): + """The detector itself must fire — otherwise the guard above passes vacuously. + + Pins the discrimination the guard depends on: a bare literal without the opt-in + is caught, the same literal WITH the opt-in is not, and an f-string is ignored + either way (interpolated messages are out of scope by design, not by accident). + """ + caught = ast.parse('AdCPValidationError("media_buy_id is required")').body[0].value + opted = ast.parse('AdCPValidationError("x", _wire_safe_message=True)').body[0].value + interpolated = ast.parse('AdCPValidationError(f"rejected {value}")').body[0].value + + assert _is_bare_string_literal_message(caught) + assert _is_bare_string_literal_message(opted) # literal, but the opt-in kwarg exempts it + assert not any(kw.arg == "_wire_safe_message" for kw in caught.keywords) + assert any(kw.arg == "_wire_safe_message" for kw in opted.keywords) + assert not _is_bare_string_literal_message(interpolated) + + # The kwarg form must be visible to both directions — reading only args[0] made + # `AdCPValidationError(message="...")` invisible to the guard entirely. + kwarg_literal = ast.parse('AdCPValidationError(message="media_buy_id is required")').body[0].value + kwarg_interpolated = ast.parse('AdCPValidationError(message=f"rejected {value}")').body[0].value + assert _is_bare_string_literal_message(kwarg_literal) + assert not _is_bare_string_literal_message(kwarg_interpolated) + assert _message_expr(kwarg_interpolated) is not None + + # And the leak direction: an interpolated message WITH the opt-in is what the second + # detector must see. Detected structurally here; the scan applies the audit list. + interpolated_opt_in = ast.parse('AdCPValidationError(f"leaked {secret}", _wire_safe_message=True)').body[0].value + assert _opts_in(interpolated_opt_in) + assert not _is_bare_string_literal_message(interpolated_opt_in) diff --git a/tests/unit/test_context_manager_fail_workflow_step.py b/tests/unit/test_context_manager_fail_workflow_step.py index e8536c598f..e4db48c22b 100644 --- a/tests/unit/test_context_manager_fail_workflow_step.py +++ b/tests/unit/test_context_manager_fail_workflow_step.py @@ -15,12 +15,20 @@ failure. """ +from typing import Any from unittest.mock import MagicMock import pytest from src.core.context_manager import ContextManager -from src.core.exceptions import AdCPValidationError +from src.core.exceptions import ( + _SANITIZED_INTERNAL_MESSAGE, + AdCPConfigurationError, + AdCPValidationError, + build_two_layer_error_envelope, + safe_adcp_error, +) +from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE, assert_no_secret_leak def _new_ctx_manager_with_mocked_update() -> tuple[ContextManager, MagicMock]: @@ -35,33 +43,30 @@ def _new_ctx_manager_with_mocked_update() -> tuple[ContextManager, MagicMock]: return cm, cm.update_workflow_step -def _expected_response_data( - code: str, message: str, *, recovery: str, field: str | None = None, details: dict | None = None -) -> dict: - """Build the two-layer wire-shape ``response_data`` the helper must emit. - - Constructs a temporary ``AdCPError`` and calls - ``build_two_layer_error_envelope`` — the same function the production code - now uses — so the test asserts on EXACTLY the dict shape - ``update_workflow_step`` will receive. +def _scrubbed_response_data(exc: Exception) -> dict[str, Any]: + """The scrubbed two-layer ``response_data`` the audit helper must emit for an INTERNAL + error — built through the exact production policy (``safe_adcp_error`` → + ``build_two_layer_error_envelope``, on the ORIGINAL exception, NOT pre-normalized). If the + helper stops scrubbing, the raw message survives and no longer matches this expected shape + (the mutation reddens). The independent secret-absence tests below don't route through this + helper — they assert the literal secret is nowhere in the payload — so a shared regression in + both helper and production can't hide the leak. """ - from src.core.exceptions import AdCPError, build_two_layer_error_envelope - - exc = AdCPError(message, field=field, details=details, recovery=recovery) - exc.error_code = code - return build_two_layer_error_envelope(exc) + return build_two_layer_error_envelope(safe_adcp_error(exc)) class TestFailWorkflowStepForExceptionWebhookPayload: """Webhook subscribers must receive the two-layer envelope, not just error_message.""" - def test_adcp_error_threads_envelope_into_response_data(self): + def test_adcp_validation_error_threads_scrubbed_envelope_into_response_data(self): + """Typed validation errors are fail-closed unless explicitly audited as static.""" cm, mock_update = _new_ctx_manager_with_mocked_update() exc = AdCPValidationError( - "bad budget", + f"bad budget: {SECRET_BEARING_MESSAGE}", field="packages[].budget", - details={"violations": ["below minimum"]}, + details={"rejected": SECRET_BEARING_MESSAGE}, ) + expected = safe_adcp_error(exc) cm.audit_workflow_step_failure("step_abc", exc) @@ -72,51 +77,100 @@ def test_adcp_error_threads_envelope_into_response_data(self): mock_update.assert_called_once_with( "step_abc", status="failed", - error_message="bad budget", - response_data=_expected_response_data( - "VALIDATION_ERROR", - "bad budget", - recovery="correctable", - field="packages[].budget", - details={"violations": ["below minimum"]}, - ), + error_message=expected.message, + response_data=_scrubbed_response_data(exc), ) + assert_no_secret_leak(expected.message) + assert_no_secret_leak(_scrubbed_response_data(exc)) - def test_untyped_exception_wrapped_with_wire_safe_code(self): - """Bare exceptions get a synthetic AdCPError so the wire code stays standard. + def test_untyped_internal_error_scrubs_secret_from_webhook_payload(self): + """An untyped/internal exception's raw message — which may embed a connection string — + is SCRUBBED to the sanitized generic message before it reaches the webhook subscriber. - ``AdCPError`` defaults to ``INTERNAL_ERROR`` which is in - ``INTERNAL_CODES``; the helper's defensive wire-code enforcement - falls back to ``SERVICE_UNAVAILABLE`` so async subscribers only see - codes from ``STANDARD_ERROR_CODES`` even when the source was untyped. - Recovery is transient — the pinned enumMetadata classification of the - SERVICE_UNAVAILABLE wire code (salesagent-nr2q). + The async webhook path is the twin of the synchronous re-raise scrub; both route + internal/infra errors through ``safe_adcp_error`` so ``str(exc)`` never reaches the + buyer. The wire code stays standard (SERVICE_UNAVAILABLE) and recovery transient. """ cm, mock_update = _new_ctx_manager_with_mocked_update() + secret = SECRET_BEARING_MESSAGE - cm.audit_workflow_step_failure("step_abc", RuntimeError("kaboom")) + cm.audit_workflow_step_failure("step_abc", RuntimeError(secret)) + # error_message + response_data carry the sanitized message, NOT the secret. mock_update.assert_called_once_with( "step_abc", status="failed", - error_message="kaboom", - response_data=_expected_response_data("SERVICE_UNAVAILABLE", "kaboom", recovery="transient"), + error_message=_SANITIZED_INTERNAL_MESSAGE, + response_data=_scrubbed_response_data(RuntimeError(secret)), ) - def test_empty_exception_message_falls_back_to_type_name(self): + def test_config_error_scrubs_secret_from_webhook_payload(self): + """``AdCPConfigurationError`` (wire code CONFIGURATION_ERROR) is terminal-internal and + also scrubbed — its decryption-failure raise sites can interpolate a secret. Before the + shared-policy fix this leg passed through unscrubbed.""" cm, mock_update = _new_ctx_manager_with_mocked_update() + secret = SECRET_BEARING_MESSAGE - cm.audit_workflow_step_failure("step_abc", RuntimeError()) + cm.audit_workflow_step_failure("step_abc", AdCPConfigurationError(f"decrypt failed: {secret}")) - # Empty message is replaced with type name so the wire envelope and - # error_message never carry blank strings. mock_update.assert_called_once_with( "step_abc", status="failed", - error_message="RuntimeError", - response_data=_expected_response_data("SERVICE_UNAVAILABLE", "RuntimeError", recovery="transient"), + error_message=_SANITIZED_INTERNAL_MESSAGE, + response_data=_scrubbed_response_data(AdCPConfigurationError(f"decrypt failed: {secret}")), ) + @pytest.mark.parametrize( + ("exc_factory", "expected_code", "msg_keyword"), + [ + pytest.param(lambda s: ValueError(s), "VALIDATION_ERROR", "validate", id="ValueError"), + pytest.param(lambda s: PermissionError(s), "AUTH_REQUIRED", "credential", id="PermissionError"), + ], + ) + def test_untyped_valueerror_permissionerror_scrub_secret_from_webhook_payload( + self, exc_factory, expected_code, msg_keyword + ): + """Untyped ``ValueError``/``PermissionError`` on the webhook path: message scrubbed, but the + SEMANTIC code matches what the synchronous boundary emits (webhook↔sync parity). + + Two properties are required: + 1. Message trust — the raw ``str(exc)`` (a connection string / token / SQL) is scrubbed, + because these are raw built-ins (untrusted provenance). + 2. Semantic parity — the persisted wire code is VALIDATION_ERROR / AUTH_REQUIRED (the code + the synchronous transport also emits for the same exception via + ``normalize_to_adcp_error``), NOT a divergent SERVICE_UNAVAILABLE. Otherwise a buyer + watching both channels sees two different codes for one failure. + + Authored INDEPENDENTLY of ``safe_adcp_error``: secret-absence is asserted against the literal + payload, and the parity code is checked against ``normalize_to_adcp_error`` (the shared + semantic mapping), not reconstructed through the sanitizer under test. + """ + from src.core.exceptions import normalize_to_adcp_error + + # Record the persisted payload via a plain callable (not a Mock) so the assertions can do + # substring-absence checks on the ACTUAL emitted values without the assert_called_once() + + # call_args split-assertion pattern the weak-mock guard forbids. + calls: list[dict] = [] + cm = ContextManager.__new__(ContextManager) + cm.update_workflow_step = lambda step_id, **kw: calls.append({"step_id": step_id, **kw}) # type: ignore[method-assign] + secret = SECRET_BEARING_MESSAGE + + cm.audit_workflow_step_failure("step_abc", exc_factory(secret)) + + assert len(calls) == 1, "audit must persist exactly one failed-step update" + payload = calls[0] + # The message is category-appropriate, NOT the generic "internal error" (which would + # contradict a client-correctable code), and secret-free. The shared oracle IS the + # definition of a leak (incl. the bearer-token shape) — assert both webhook sinks. + assert msg_keyword in payload["error_message"].lower() + assert "internal error" not in payload["error_message"].lower() + assert_no_secret_leak(payload["response_data"], context="webhook response_data") + assert_no_secret_leak(payload["error_message"], context="error_message") + # Webhook↔sync semantic parity: the persisted code equals the synchronous boundary's code. + persisted_code = payload["response_data"]["adcp_error"]["code"] + assert persisted_code == expected_code + assert persisted_code == normalize_to_adcp_error(exc_factory(secret)).wire_error_code + class TestFailWorkflowStepForExceptionAuditFailureNonFatal: """A DB hiccup during the audit write must NOT shadow the original exception.""" diff --git a/tests/unit/test_context_manager_webhook_dedup.py b/tests/unit/test_context_manager_webhook_dedup.py new file mode 100644 index 0000000000..c53cbaa5c3 --- /dev/null +++ b/tests/unit/test_context_manager_webhook_dedup.py @@ -0,0 +1,69 @@ +"""Regression pin: one webhook per workflow-step status change. + +``ContextManager._send_push_notifications`` used to send inside +``for mapping in mappings: for _webhook_config in webhooks:`` while building the +delivery target from the STEP's own ``request_data.push_notification_config`` — +the loop variables were never used as targets. Every extra ObjectWorkflowMapping +(create_media_buy links the media_buy to its step at two call sites) and every +extra active PushNotificationConfig row multiplied IDENTICAL sends, so a buyer's +auto-approved create_media_buy received duplicate ``completed`` webhooks +(caught live by the E2E single-completed-webhook assertion in +``test_a2a_webhook_payload_types::test_completed_status_sends_task_payload``). + +The fix treats ``mappings`` and ``webhooks`` as opt-in gates and sends exactly +once per status change. +""" + +from __future__ import annotations + +from types import SimpleNamespace +from unittest.mock import AsyncMock, MagicMock, patch + +from src.core import context_manager +from tests.unit._push_notification_helpers import make_push_step, session_returning + + +def _drive_with(mappings, webhooks): + """Drive the REAL _send_push_notifications; return the mocked webhook service.""" + context = SimpleNamespace(tenant_id="tenant_1", principal_id="principal_1") + session = session_returning(mappings, context, webhooks) + + fake_service = MagicMock() + fake_service.send_notification = AsyncMock() + + cm = context_manager.ContextManager() + with patch.object(context_manager, "get_protocol_webhook_service", return_value=fake_service): + cm._send_push_notifications(make_push_step(), "completed", session) + return fake_service + + +def _mapping(object_id: str) -> SimpleNamespace: + return SimpleNamespace(object_type="media_buy", object_id=object_id, action="create") + + +def test_multiple_mappings_and_configs_send_exactly_one_webhook(): + """2 mappings x 2 active configs must still deliver ONE webhook, not four. + + The payload depends only on (step, new_status); the rows are gates. Any + count > 1 is the duplicate-webhook regression the E2E pin caught live. + """ + service = _drive_with( + mappings=[_mapping("mb_1"), _mapping("mb_1")], + webhooks=[SimpleNamespace(id="pnc_1"), SimpleNamespace(id="pnc_2")], + ) + assert service.send_notification.await_count == 1, ( + f"expected exactly one webhook per status change, got {service.send_notification.await_count} " + "(mappings x configs multiplied identical sends)" + ) + + +def test_no_active_configs_sends_no_webhook(): + """The registered-config gate is preserved: zero active configs -> zero sends.""" + service = _drive_with(mappings=[_mapping("mb_1")], webhooks=[]) + assert service.send_notification.await_count == 0 + + +def test_no_mappings_sends_no_webhook(): + """The mapping gate is preserved: an unlinked step sends nothing.""" + service = _drive_with(mappings=[], webhooks=[SimpleNamespace(id="pnc_1")]) + assert service.send_notification.await_count == 0 diff --git a/tests/unit/test_creative.py b/tests/unit/test_creative.py index 0479b3313a..97dd77b889 100644 --- a/tests/unit/test_creative.py +++ b/tests/unit/test_creative.py @@ -1815,7 +1815,6 @@ def _setup_generative_mocks(self, mock_session, *, gemini_key="test-gemini-key") Note: mock_format_obj.format_id uses _adcp_format_id() (the library type) to match the CreativeAsset.format_id type from _make_creative_asset(). - FormatId equality requires same type instances. """ mock_format_obj = MagicMock() mock_format_obj.format_id = _adcp_format_id() @@ -1827,6 +1826,22 @@ def _setup_generative_mocks(self, mock_session, *, gemini_key="test-gemini-key") return mock_format_obj, mock_config + def test_format_matching_uses_canonical_federation_identity(self): + """Equivalent agent URLs match across transport serialization differences.""" + from src.core.tools.creatives._processing import _find_matching_format + + listed_format = MagicMock() + listed_format.format_id = AdcpFormatId( + agent_url=f"{DEFAULT_AGENT_URL}/formats/", + id="display_300x250_image", + ) + requested_format = AdcpFormatId( + agent_url=f"{DEFAULT_AGENT_URL}/formats", + id="display_300x250_image", + ) + + assert _find_matching_format([listed_format], requested_format) is listed_format + def test_format_with_output_format_ids_classified_as_generative(self): """Format with output_format_ids is classified as a generative creative. @@ -3183,7 +3198,8 @@ def test_lenient_mode_continues_on_assignment_error(self): mock_media_buy.status = "draft" mock_media_buy.approved_at = None - def find_pkg(package_id): + def find_pkg(package_id, principal_id): + assert principal_id == "principal_1" if package_id == "pkg_ok": return (mock_package, mock_media_buy) return None diff --git a/tests/unit/test_creative_agent_registry.py b/tests/unit/test_creative_agent_registry.py index 0050c87876..d7ecad838d 100644 --- a/tests/unit/test_creative_agent_registry.py +++ b/tests/unit/test_creative_agent_registry.py @@ -51,6 +51,26 @@ async def mock_fetch(*args, **kwargs): class TestCreativeAgentRegistry: """Test suite for Creative Agent Registry adcp integration.""" + def test_registered_agent_urls_keep_default_public_identity(self, monkeypatch): + """An internal default transport alias is never exposed as federation identity.""" + registry = CreativeAgentRegistry() + custom_agent = CreativeAgent( + agent_url="https://Tenant-Agent.Example.com/mcp/", + name="Tenant Agent", + ) + monkeypatch.setattr( + registry, + "_get_tenant_agents", + lambda _tenant_id: [registry.DEFAULT_AGENT, custom_agent], + ) + + assert registry.get_registered_agent_urls("tenant_1") == frozenset( + { + "https://creative.adcontextprotocol.org", + "https://tenant-agent.example.com/mcp", + } + ) + def test_build_adcp_client_with_custom_auth_header(self): """Test _build_adcp_client correctly maps custom auth headers.""" registry = CreativeAgentRegistry() diff --git a/tests/unit/test_creative_coverage_gaps.py b/tests/unit/test_creative_coverage_gaps.py index ac9de603dc..399dfc7ac3 100644 --- a/tests/unit/test_creative_coverage_gaps.py +++ b/tests/unit/test_creative_coverage_gaps.py @@ -15,7 +15,7 @@ import pytest from adcp import PushNotificationConfig -from adcp.types import CreativeAction +from adcp.types import CreativeAction, FormatId from pydantic import BaseModel from tests.factories import PrincipalFactory @@ -49,8 +49,12 @@ def identity(): @pytest.fixture def mock_format_spec(): spec = Mock() - spec.format_id = "display_300x250_image" + spec.format_id = FormatId( + agent_url="https://creative.adcontextprotocol.org", + id="display_300x250_image", + ) spec.agent_url = "https://creative.adcontextprotocol.org" + spec.output_format_ids = [] spec.name = "Medium Rectangle" return spec diff --git a/tests/unit/test_creative_webhook_correlation.py b/tests/unit/test_creative_webhook_correlation.py new file mode 100644 index 0000000000..e520576bb3 --- /dev/null +++ b/tests/unit/test_creative_webhook_correlation.py @@ -0,0 +1,75 @@ +"""Wire-level task-correlation tests for creative-completion webhooks.""" + +from __future__ import annotations + +from types import SimpleNamespace +from unittest.mock import AsyncMock, MagicMock, patch + +import pytest + +from src.admin.blueprints.creatives import _call_webhook_for_creative_status + + +def _creative_webhook_uow(*, protocol: str, external_task_id: str | None) -> MagicMock: + """Build the read-only UoW view consumed by the creative webhook helper.""" + request_data = { + "protocol": protocol, + "push_notification_config": { + "url": "https://callbacks.example.test/creative-status", + "authentication": {"schemes": ["Bearer"], "credentials": "test-credential"}, + }, + } + if external_task_id is not None: + request_data["external_task_id"] = external_task_id + + mapping = SimpleNamespace(step_id="step_internal_1", object_type="creative", object_id="creative_1") + step = SimpleNamespace( + step_id="step_internal_1", + tool_name="sync_creatives", + request_data=request_data, + context_id="ctx_creative_1", + context=SimpleNamespace(tenant_id="tenant_creative_1", principal_id="principal_creative_1"), + ) + creative = SimpleNamespace( + creative_id="creative_1", + status="approved", + data={}, + ) + + uow = MagicMock() + uow.workflows.get_latest_mapping_for_object.return_value = mapping + uow.workflows.get_step_by_id.return_value = step + uow.workflows.get_mappings_for_step.return_value = [mapping] + uow.creatives.admin_get_by_ids.return_value = [creative] + + manager = MagicMock() + manager.__enter__.return_value = uow + return manager + + +@pytest.mark.asyncio +@pytest.mark.parametrize("protocol", ["a2a", "mcp"]) +@pytest.mark.parametrize( + ("external_task_id", "expected_task_id"), + [ + ("task_buyer_1", "task_buyer_1"), + (None, "step_internal_1"), + ], +) +async def test_creative_completion_webhook_uses_buyer_task_id_or_step_fallback( + protocol: str, external_task_id: str | None, expected_task_id: str +) -> None: + """Both protocol payloads correlate to the buyer task id, with the legacy step-id fallback.""" + uow_manager = _creative_webhook_uow(protocol=protocol, external_task_id=external_task_id) + service = MagicMock() + service.send_notification = AsyncMock() + + with patch("src.admin.blueprints.creatives.AdminCreativeUoW", return_value=uow_manager): + with patch("src.admin.blueprints.creatives.get_protocol_webhook_service", return_value=service): + delivered = await _call_webhook_for_creative_status("creative_1", "tenant_creative_1") + + assert delivered is True + service.send_notification.assert_awaited_once() + payload = service.send_notification.await_args.kwargs["payload"] + task_id = getattr(payload, "id", None) or getattr(payload, "task_id", None) + assert task_id == expected_task_id diff --git a/tests/unit/test_delivery.py b/tests/unit/test_delivery.py index a9bd48819d..24eb78d8b5 100644 --- a/tests/unit/test_delivery.py +++ b/tests/unit/test_delivery.py @@ -2061,6 +2061,10 @@ def test_auth_rejection_marks_webhook_failed(self): with ( patch("src.core.webhook_delivery.time.sleep"), + patch( + "src.core.security.url_validator.socket.gethostbyname", + return_value="93.184.216.34", + ), patch("requests.post") as mock_post, ): mock_response = MagicMock() diff --git a/tests/unit/test_error_boundary_translation.py b/tests/unit/test_error_boundary_translation.py index f8ac9a3292..205ff1812e 100644 --- a/tests/unit/test_error_boundary_translation.py +++ b/tests/unit/test_error_boundary_translation.py @@ -7,9 +7,10 @@ - ValueError and PermissionError are caught at boundaries - extract_error_info handles AdCPError instances -beads: salesagent-pyeu, salesagent-d50c """ +import json +from types import SimpleNamespace from unittest.mock import patch import pytest @@ -28,6 +29,8 @@ # the envelope is now a one-place update. # --------------------------------------------------------------------------- from tests.helpers import assert_envelope_shape # noqa: E402 +from tests.helpers.pinned_schema import pinned_error_code_metadata +from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE, assert_no_secret_leak, serialize_wire_error # Per-boundary assertion wrappers were removed in favor of the canonical # `assert_envelope_shape` helper. Call sites use keyword flags directly: @@ -36,11 +39,176 @@ # REST: assert_envelope_shape(body, code, recovery=..., message_substr=...) +class TestBestEffortBoundaryIdentity: + """Observability scope resolution must enrich when possible and fail closed.""" + + def test_returns_resolved_tenant_and_principal(self): + from src.core.tool_error_logging import best_effort_boundary_identity + + identity = SimpleNamespace(tenant_id="tenant-observed", principal_id="principal-observed") + + assert best_effort_boundary_identity(lambda: identity, transport="mcp") == ( + "tenant-observed", + "principal-observed", + ) + + def test_resolution_failure_degrades_to_unscoped_record(self): + from src.core.tool_error_logging import best_effort_boundary_identity + + def fail_resolution(): + raise RuntimeError("identity backend unavailable") + + assert best_effort_boundary_identity(fail_resolution, transport="a2a") == (None, None) + + def test_tenant_hint_without_principal_is_unscoped(self): + """Anonymous resolution cannot authorize tenant-visible sink writes.""" + from src.core.tool_error_logging import best_effort_boundary_identity + + identity = SimpleNamespace(tenant_id="header-selected-tenant", principal_id=None) + + assert best_effort_boundary_identity(lambda: identity, transport="rest") == (None, None) + + def test_a2a_activity_scope_does_not_fabricate_unknown_tenant(self): + """Anonymous discovery activity remains unscoped like A2A boundary errors.""" + from src.a2a_server.adcp_a2a_server import _a2a_activity_scope + + assert _a2a_activity_scope(None) == (None, None) + + +class TestBoundaryObservabilitySanitization: + """Tenant-visible and persistent sinks must never receive raw internal details.""" + + def test_typed_internal_error_is_scrubbed_before_activity_and_audit_sinks(self): + from src.core.tool_error_logging import record_boundary_error + + feed_records: list[dict[str, object]] = [] + audit_records: list[dict[str, object]] = [] + audit_logger = SimpleNamespace(log_operation=lambda **kwargs: audit_records.append(kwargs)) + + with ( + patch( + "src.services.activity_feed.activity_feed.log_error", + side_effect=lambda **kwargs: feed_records.append(kwargs), + ), + patch( + "src.core.audit_logger.get_audit_logger", + return_value=audit_logger, + ), + ): + record_boundary_error( + "a2a", + "create_media_buy", + AdCPAdapterError(SECRET_BEARING_MESSAGE), + tenant_id="tenant-safe", + principal_id="principal-safe", + ) + + assert len(feed_records) == 1 + assert len(audit_records) == 1 + feed_payload = feed_records[0] + audit_payload = audit_records[0] + assert feed_payload["tenant_id"] == "tenant-safe" + assert feed_payload["error_code"] == "SERVICE_UNAVAILABLE" + feed_message = feed_payload["error_message"] + audit_error = audit_payload["error"] + assert isinstance(feed_message, str) + assert isinstance(audit_error, str) + assert feed_message.endswith(audit_error) + assert_no_secret_leak(feed_payload, context="tenant activity error payload") + assert_no_secret_leak(audit_payload, context="persistent audit error payload") + + # --------------------------------------------------------------------------- # MCP Boundary: extract_error_info # --------------------------------------------------------------------------- +class TestAuthCodeConformance: + """The auth taxonomy follows tagged AdCP 3.1.1, not the SDK's older vocabulary.""" + + @pytest.mark.parametrize( + ("error_class", "code"), + [ + pytest.param("AdCPAuthMissingError", "AUTH_MISSING", id="missing-credentials"), + pytest.param("AdCPAuthInvalidError", "AUTH_INVALID", id="rejected-credentials"), + ], + ) + def test_split_auth_error_defaults_match_pinned_enum_metadata(self, error_class, code): + """Absent versus rejected credentials carry their spec code, recovery, and suggestion.""" + from src.core import exceptions + + metadata = pinned_error_code_metadata()[code] + error = getattr(exceptions, error_class)("test auth failure") + + assert error.wire_error_code == code + assert error.recovery == metadata["recovery"] + assert error.suggestion == metadata["suggestion"] + + +class TestAuthContractOracle: + """The shared transport oracle grades exact codes and both suggestion mirrors.""" + + @pytest.mark.parametrize( + ("transport", "credential_state", "expected_code"), + [ + pytest.param("a2a", "missing", "AUTH_MISSING", id="a2a-missing"), + pytest.param("a2a", "invalid", "AUTH_INVALID", id="a2a-invalid"), + pytest.param("e2e_a2a", "missing", "AUTH_MISSING", id="e2e-a2a-missing"), + pytest.param("mcp", "invalid", "AUTH_INVALID", id="mcp-invalid"), + pytest.param("rest", "missing", "AUTH_MISSING", id="rest-missing"), + pytest.param("e2e_mcp", "missing", "AUTH_MISSING", id="e2e-mcp-missing"), + pytest.param("e2e_rest", "invalid", "AUTH_INVALID", id="e2e-rest-invalid"), + pytest.param("impl", "invalid", "AUTH_REQUIRED", id="impl-invalid"), + ], + ) + def test_expected_auth_contract_is_transport_aware(self, transport, credential_state, expected_code): + from tests.helpers.auth_contract import expected_auth_contract + + code, recovery, suggestion = expected_auth_contract(transport, credential_state) + metadata = pinned_error_code_metadata()[expected_code] + + assert code == expected_code + assert recovery == metadata["recovery"] + assert suggestion == metadata["suggestion"] + + @pytest.mark.parametrize("unknown_transport", [None, "a22", "future_transport"]) + def test_expected_auth_contract_rejects_unknown_transport(self, unknown_transport): + from tests.helpers.auth_contract import expected_auth_contract + + with pytest.raises(AssertionError, match="Unknown auth-contract transport"): + expected_auth_contract(unknown_transport, "missing") + + def test_expected_auth_contract_rejects_unknown_credential_state(self): + from tests.helpers.auth_contract import expected_auth_contract + + with pytest.raises(AssertionError, match="Unknown credential state"): + expected_auth_contract("a2a", "invalidd") # type: ignore[arg-type] + + @pytest.mark.parametrize("mutated_layer", ["errors", "adcp_error"]) + def test_two_layer_auth_contract_rejects_suggestion_drift(self, mutated_layer): + from tests.helpers.auth_contract import assert_two_layer_auth_contract, expected_auth_contract + + code, recovery, suggestion = expected_auth_contract("a2a", "missing") + envelope = { + "errors": [ + {"code": code, "message": "Credentials required", "recovery": recovery, "suggestion": suggestion} + ], + "adcp_error": { + "code": code, + "message": "Credentials required", + "recovery": recovery, + "suggestion": suggestion, + }, + } + if mutated_layer == "errors": + envelope["errors"][0]["suggestion"] = "drifted guidance" + else: + envelope["adcp_error"]["suggestion"] = "drifted guidance" + + with pytest.raises(AssertionError, match=r"suggestion must match pinned AUTH_MISSING guidance"): + assert_two_layer_auth_contract(envelope, "a2a", "missing") + + class TestExtractErrorInfoAdCPError: """extract_error_info must recognize AdCPError and extract error_code + message + recovery.""" @@ -57,7 +225,7 @@ def test_adcp_validation_error_extracts_code_and_message(self): def test_adcp_not_found_extracts_code_and_message(self): """AdCPNotFoundError → ('NOT_FOUND', 'resource missing', 'correctable'). - Recovery follows the wire code INVALID_REQUEST=correctable (salesagent-nr2q). + Recovery follows the wire code INVALID_REQUEST=correctable. """ from src.core.tool_error_logging import extract_error_info @@ -111,7 +279,7 @@ def test_adcp_service_unavailable_error_extracts_code_and_message(self): def test_adcp_base_error_extracts_code_and_message(self): """AdCPError base → ('INTERNAL_ERROR', 'something broke', 'transient'). - Recovery follows the wire code SERVICE_UNAVAILABLE=transient (salesagent-nr2q). + Recovery follows the wire code SERVICE_UNAVAILABLE=transient. """ from src.core.tool_error_logging import extract_error_info @@ -211,7 +379,7 @@ def failing_tool(): assert_envelope_shape(exc_info.value, "VALIDATION_ERROR", check_mcp_tool_error=True, recovery="correctable") def test_adcp_adapter_tool_error_carries_transient_recovery(self): - """AdCPAdapterError → ToolError envelope carries 'transient' recovery.""" + """AdCPAdapterError → scrubbed ToolError envelope carries canonical recovery.""" from fastmcp.exceptions import ToolError from src.core.tool_error_logging import with_error_logging @@ -229,8 +397,8 @@ def failing_tool(): "SERVICE_UNAVAILABLE", check_mcp_tool_error=True, recovery="transient", - message_substr="GAM down", ) + assert "GAM down" not in str(exc_info.value) @pytest.mark.asyncio async def test_async_adcp_validation_becomes_tool_error(self): @@ -266,41 +434,382 @@ def failing_tool(): # Should be the same ToolError, not wrapped assert exc_info.value.args[0] == "EXISTING_CODE" - def test_valueerror_becomes_tool_error(self): - """ValueError from tool → ToolError with VALIDATION_ERROR code.""" + def test_valueerror_becomes_scrubbed_tool_error(self): + """ValueError from tool → scrubbed ToolError with VALIDATION_ERROR code.""" from fastmcp.exceptions import ToolError from src.core.tool_error_logging import with_error_logging def failing_tool(): - raise ValueError("invalid input") + raise ValueError(SECRET_BEARING_MESSAGE) wrapped = with_error_logging(failing_tool) with pytest.raises(ToolError) as exc_info: wrapped() - assert "VALIDATION_ERROR" in str(exc_info.value) or ( - exc_info.value.args and exc_info.value.args[0] == "VALIDATION_ERROR" + assert_envelope_shape( + exc_info.value, + "VALIDATION_ERROR", + check_mcp_tool_error=True, + recovery="correctable", ) + assert_no_secret_leak(str(exc_info.value), context="MCP ValueError envelope") - def test_permission_error_becomes_tool_error(self): - """PermissionError from tool → ToolError with AUTH_REQUIRED code.""" + def test_permission_error_becomes_scrubbed_tool_error(self): + """PermissionError from tool → scrubbed ToolError with AUTH_REQUIRED code.""" from fastmcp.exceptions import ToolError from src.core.tool_error_logging import with_error_logging def failing_tool(): - raise PermissionError("access denied") + raise PermissionError(SECRET_BEARING_MESSAGE) wrapped = with_error_logging(failing_tool) with pytest.raises(ToolError) as exc_info: wrapped() - assert "AUTH_REQUIRED" in str(exc_info.value) or ( - exc_info.value.args and exc_info.value.args[0] == "AUTH_REQUIRED" + assert_envelope_shape( + exc_info.value, + "AUTH_REQUIRED", + check_mcp_tool_error=True, + recovery="correctable", + ) + assert_no_secret_leak(str(exc_info.value), context="MCP PermissionError envelope") + + def test_untyped_crash_becomes_scrubbed_tool_error(self): + """A generic, unmapped exception → scrubbed SERVICE_UNAVAILABLE ToolError. + + The fifth ``normalize_to_adcp_error`` outcome, and the only one this class did not + drive: the fall-through for an exception that is neither an ``AdCPError`` nor one of + the mapped built-ins. The sibling cases above all inject something the normalization + registry recognises, so removing the boundary's untyped arm left the whole suite + green — the branch that turns a real crash into an AdCP envelope was unlocked. + + ``assert_sanitized_wire_error`` is deliberately not used: it requires the code to + have a canonical sanitized presentation, and SERVICE_UNAVAILABLE is in the internal + bucket rather than ``_SANITIZED_BY_WIRE_CODE``. + """ + from fastmcp.exceptions import ToolError + + from src.core.tool_error_logging import with_error_logging + + def failing_tool(): + raise RuntimeError(SECRET_BEARING_MESSAGE) + + wrapped = with_error_logging(failing_tool) + + with pytest.raises(ToolError) as exc_info: + wrapped() + + assert_envelope_shape( + exc_info.value, + "SERVICE_UNAVAILABLE", + check_mcp_tool_error=True, + recovery="transient", + ) + assert exc_info.value.status_code == 500 + assert_no_secret_leak(str(exc_info.value), context="MCP untyped crash envelope") + + +def _uncovered_correctable_targets(registry, sanitized_by_code, internal_codes, standard_codes): + """Registry semantic targets lacking a sanitized client-correctable category. + + ``adcp_class`` is the single authority read here and instantiated by production. Projectors + provide kwargs only, so they cannot make runtime emit a different wire code. Pure over its + inputs so the same logic grades the real registry and a known-bad synthetic registry. + """ + uncovered = [] + for _exc_type, adcp_class, _kwargs_projector in registry: + wire_code = adcp_class("probe").wire_error_code + if wire_code in internal_codes or wire_code not in standard_codes: + continue + if wire_code not in sanitized_by_code: + uncovered.append((adcp_class.__name__, wire_code)) + return uncovered + + +class TestSafeAdcpErrorSuggestionMatchesRecovery: + """``safe_adcp_error``'s sanitized suggestion must not contradict the preserved recovery. + + The sanitizer scrubs the (possibly secret-bearing) message on every internal error but keeps + the wire code + recovery. A terminal ``CONFIGURATION_ERROR`` (per 3.1.1 the buyer MUST NOT + auto-retry; a seller operator must resolve it) paired with a "retry the request later" + suggestion is a self-contradictory envelope. These pins are authored independently of the + module's suggestion CONSTANTS — they assert the semantic ``retry`` property directly — so they + are not tautological with the sanitizer that produces the value (the config webhook payload + test derives its expected envelope through ``safe_adcp_error`` itself and only checks the + generic message, so it can't see this). + """ + + def test_terminal_config_error_suggestion_does_not_advise_retry(self): + from src.core.exceptions import AdCPConfigurationError, safe_adcp_error + + # A raise site that interpolates a secret into a CONFIGURATION_ERROR (recovery=terminal). + safe = safe_adcp_error(AdCPConfigurationError(f"decrypt failed: {SECRET_BEARING_MESSAGE}")) + + assert safe.recovery == "terminal", "CONFIGURATION_ERROR recovery must be preserved as terminal" + assert "retry" not in safe.suggestion.lower(), ( + f"a terminal error must not advise the buyer to retry, got: {safe.suggestion!r}" + ) + # The secret is still scrubbed from BOTH message and suggestion (shared leak oracle). + assert_no_secret_leak(safe.suggestion, context="suggestion") + assert_no_secret_leak(safe.message, context="message") + + def test_transient_service_unavailable_suggestion_advises_retry(self): + from src.core.exceptions import AdCPServiceUnavailableError, safe_adcp_error + + safe = safe_adcp_error(AdCPServiceUnavailableError("db connection pool exhausted")) + + assert safe.recovery == "transient", "SERVICE_UNAVAILABLE recovery must be preserved as transient" + assert "retry" in safe.suggestion.lower(), ( + f"a transient error should advise the buyer to retry, got: {safe.suggestion!r}" + ) + + def test_untyped_internal_error_advises_retry(self): + """An untyped crash sanitizes to a transient base error, so retry guidance is correct.""" + from src.core.exceptions import safe_adcp_error + + safe = safe_adcp_error(RuntimeError(f"kaboom {SECRET_BEARING_MESSAGE}")) + + assert safe.recovery == "transient" + assert "retry" in safe.suggestion.lower() + assert_no_secret_leak(safe.suggestion, context="suggestion") + assert_no_secret_leak(safe.message, context="message") + + def test_unknown_internal_code_coerces_to_transient_service_unavailable(self): + """An internal code the wire doesn't model coerces to SERVICE_UNAVAILABLE — whose canonical + recovery is transient. The fallback must NOT emit SERVICE_UNAVAILABLE paired with terminal + (the code and recovery would disagree); it emits transient + retry guidance.""" + from src.core.exceptions import AdCPError, safe_adcp_error + + safe = safe_adcp_error( + AdCPError.synthesize(SECRET_BEARING_MESSAGE, error_code="UNKNOWN_INTERNAL", recovery="correctable") + ) + + assert safe.wire_error_code == "SERVICE_UNAVAILABLE" + assert safe.recovery == "transient", "SERVICE_UNAVAILABLE's canonical recovery is transient, not terminal" + assert "retry" in safe.suggestion.lower() + assert_no_secret_leak(safe.message, context="message") + assert_no_secret_leak(safe.suggestion, context="suggestion") + + def test_internal_error_recovery_normalized_to_canonical_not_instance_override(self): + """A raise site can tag an internal error with a recovery that contradicts its wire code + (AdCPAdapterError → SERVICE_UNAVAILABLE, but recovery='correctable'). The sanitizer + NORMALIZES recovery to the code's canonical value so code + recovery + suggestion agree — + the buyer never sees SERVICE_UNAVAILABLE + correctable + a 'retry later' suggestion.""" + from src.core.exceptions import AdCPAdapterError, safe_adcp_error + + safe = safe_adcp_error(AdCPAdapterError(f"db pool: {SECRET_BEARING_MESSAGE}", recovery="correctable")) + + assert safe.wire_error_code == "SERVICE_UNAVAILABLE" + assert safe.recovery == "transient", "recovery must be normalized to the code's canonical value" + assert "retry" in safe.suggestion.lower() + assert_no_secret_leak(safe.message, context="message") + assert_no_secret_leak(safe.suggestion, context="suggestion") + + def test_suggestion_table_covers_all_recovery_hints(self): + """The suggestion table must be exhaustive over RecoveryHint — a new recovery value added + without a suggestion would KeyError at runtime instead of silently mis-guiding.""" + from typing import get_args + + from src.core.exceptions import RecoveryHint, _sanitized_suggestion_for + + for recovery in get_args(RecoveryHint): + assert _sanitized_suggestion_for(recovery), f"no sanitized suggestion for recovery={recovery!r}" + + def test_three_way_suggestion_semantics(self): + """Each recovery class gets guidance matching its semantics: transient→retry, + correctable→adjust/resubmit (NOT retry-later), terminal→no-retry.""" + from src.core.exceptions import _sanitized_suggestion_for + + assert "retry" in _sanitized_suggestion_for("transient").lower() + assert "retry" not in _sanitized_suggestion_for("terminal").lower() + correctable = _sanitized_suggestion_for("correctable").lower() + assert "retry" not in correctable, "correctable is not a retry-later case" + assert any(word in correctable for word in ("adjust", "resubmit", "review")), ( + "correctable must give correction guidance, not silence" + ) + + def test_sanitized_suggestions_match_pinned_spec_enum(self): + """The category suggestion a scrub emits IS the code's canonical spec text. + + Grounds ``_SANITIZED_BY_WIRE_CODE``'s suggestion legs (and the shared spec-derived + constants they source from) in the PINNED enum fixture — the independent authority — + so a hand-edited suggestion that drifts from ``error-code.json`` enumMetadata reddens + here. This is the oracle that caught the AUTH_REQUIRED suggestion advising retry while + the spec enum says "do NOT auto-retry rejected credentials". + """ + from src.core.exceptions import _SANITIZED_BY_WIRE_CODE, safe_adcp_error + + enum_meta = pinned_error_code_metadata() + + for wire_code, (_message, suggestion) in _SANITIZED_BY_WIRE_CODE.items(): + assert suggestion == enum_meta[wire_code]["suggestion"], ( + f"{wire_code} sanitized suggestion drifted from the pinned spec enum" + ) + # And on the emitted error itself, not just the table. + assert safe_adcp_error(ValueError("x")).suggestion == enum_meta["VALIDATION_ERROR"]["suggestion"] + assert safe_adcp_error(PermissionError("x")).suggestion == enum_meta["AUTH_REQUIRED"]["suggestion"] + + def test_scrubbed_message_and_suggestion_match_semantic_category(self): + """A scrubbed error's MESSAGE and SUGGESTION match its wire code — the machine field and + the human guidance must not contradict. A VALIDATION_ERROR must not read "internal error", + and an AUTH_REQUIRED must say authenticate/credentials, not "adjust the request". All are + static and secret-free.""" + from src.core.exceptions import safe_adcp_error + + # VALIDATION_ERROR (raw ValueError): about the submitted fields, not an internal error. + v = safe_adcp_error(ValueError(SECRET_BEARING_MESSAGE)) + assert v.wire_error_code == "VALIDATION_ERROR" + assert "internal error" not in v.message.lower() + assert "validate" in v.message.lower() + assert "retry" not in v.suggestion.lower() + assert "field" in v.suggestion.lower() + + # AUTH_REQUIRED (raw PermissionError): about credentials/permissions, not field correction. + a = safe_adcp_error(PermissionError(SECRET_BEARING_MESSAGE)) + assert a.wire_error_code == "AUTH_REQUIRED" + assert "internal error" not in a.message.lower() + assert any(w in a.message.lower() for w in ("authenticat", "authoriz", "credential")) + assert any(w in a.suggestion.lower() for w in ("credential", "permission")) + + # SERVICE_UNAVAILABLE (untyped internal): the generic internal message + retry IS correct. + s = safe_adcp_error(RuntimeError(SECRET_BEARING_MESSAGE)) + assert s.wire_error_code == "SERVICE_UNAVAILABLE" + assert "internal error" in s.message.lower() + assert "retry" in s.suggestion.lower() + + for e in (v, a, s): + assert_no_secret_leak(e.message, context=f"{e.wire_error_code} message") + assert_no_secret_leak(e.suggestion, context=f"{e.wire_error_code} suggestion") + + def test_typed_and_raw_validation_scrubs_share_one_category_text(self): + """Both scrub paths select sanitized text from ONE table. + + ``safe_adcp_error`` reaches the scrub two ways: the ``synthesize``-based + ``_scrubbed_error`` (raw built-in) and the subclass-preserving ``type(exc)(...)`` + branch (untrusted ``AdCPValidationError``). The second cannot delegate to the first, + so the selection lived at both sites — and the same wire code could yield different + buyer text depending on the exception's provenance. Pin that they agree. + """ + from src.core.exceptions import _SANITIZED_BY_WIRE_CODE, AdCPValidationError, safe_adcp_error + + expected_message, expected_suggestion = _SANITIZED_BY_WIRE_CODE["VALIDATION_ERROR"] + + typed = safe_adcp_error(AdCPValidationError(SECRET_BEARING_MESSAGE)) + raw = safe_adcp_error(ValueError(SECRET_BEARING_MESSAGE)) + + assert typed.wire_error_code == raw.wire_error_code == "VALIDATION_ERROR" + assert typed.message == expected_message == raw.message + assert typed.suggestion == expected_suggestion == raw.suggestion + # The typed branch exists to preserve the subclass; losing that would silently + # change the raised type even though the text now matches. + assert type(typed) is AdCPValidationError + + for e in (typed, raw): + assert_no_secret_leak(e.message, context=f"{type(e).__name__} scrubbed message") + assert_no_secret_leak(e.suggestion, context=f"{type(e).__name__} scrubbed suggestion") + + def test_sanitized_category_registry_covers_all_correctable_builtin_targets(self): + """Completeness guard reconciling ``_BUILTIN_NORMALIZATION`` with ``_SANITIZED_BY_WIRE_CODE``. + + Production instantiates each entry's ``adcp_class`` directly; the kwargs projector cannot + select another semantic class. The guard reads that same single authority. Every correctable + standard target must have a category entry; internal/non-standard targets are exempt. + """ + from src.core.exceptions import ( + _BUILTIN_NORMALIZATION, + _SANITIZED_BY_WIRE_CODE, + INTERNAL_WIRE_CODES, + WIRE_STANDARD_CODES, + ) + + uncovered = _uncovered_correctable_targets( + _BUILTIN_NORMALIZATION, _SANITIZED_BY_WIRE_CODE, INTERNAL_WIRE_CODES, WIRE_STANDARD_CODES + ) + assert uncovered == [], ( + f"raw-exception normalizers whose client-correctable target lacks a " + f"_SANITIZED_BY_WIRE_CODE entry (a scrubbed built-in would read 'An internal error " + f"occurred'): {uncovered}. Add a category (message, suggestion) for each code." + ) + + def test_uncovered_detector_flags_special_projector_target(self): + """Known-bad: a custom structured projector targeting an uncovered class is flagged. + + Projectors return constructor kwargs, not errors, so even input-dependent projector logic + cannot vary the semantic target behind the guard's back. + """ + from src.core.exceptions import ( + _SANITIZED_BY_WIRE_CODE, + INTERNAL_WIRE_CODES, + WIRE_STANDARD_CODES, + AdCPNotFoundError, + AdCPValidationError, + ) + + def _special_kwargs(exc): + return {"message": "resource missing", "field": "id", "details": {"probe": str(exc)}} + + registry_without_invalid_request = dict(_SANITIZED_BY_WIRE_CODE) + registry_without_invalid_request.pop("INVALID_REQUEST") + known_bad_registry = ( + (KeyError, AdCPNotFoundError, _special_kwargs), + (LookupError, AdCPValidationError, _special_kwargs), # covered control + ) + + uncovered = _uncovered_correctable_targets( + known_bad_registry, registry_without_invalid_request, INTERNAL_WIRE_CODES, WIRE_STANDARD_CODES + ) + assert ("AdCPNotFoundError", "INVALID_REQUEST") in uncovered, ( + "detector must flag a special projector whose target is an uncovered correctable code" + ) + assert all(code != "VALIDATION_ERROR" for _name, code in uncovered), ( + "a factory returning a covered code must NOT be flagged" + ) + + def test_normalization_projector_cannot_override_semantic_identity(self): + """Known-bad: a projector emitting semantic overrides is caught at import time. + + ``AdCPError`` constructors accept ``error_code``/``status_code``/``recovery`` overrides. + Without the allowlist gate, a projector could declare ``AdCPValidationError`` to the + completeness guard but emit ``INVALID_REQUEST`` at runtime via ``error_code='NOT_FOUND'``. + Enforcement moved OUT of the hot exception path (a raise inside a boundary translator + shadows the original exception and fails open with no envelope) to a module-import gate; + this drives the gate's shared detector with known-bad registries so a degraded matcher + reddens here. + """ + from src.core.exceptions import ( + AdCPValidationError, + _build_normalized_error, + _projector_key_violations, + ) + + bad_error_code = ((ValueError, AdCPValidationError, lambda e: {"message": str(e), "error_code": "NOT_FOUND"}),) + findings = _projector_key_violations(bad_error_code) + assert findings and "error_code" in findings[0], findings + + bad_context = ( + ( + ValueError, + AdCPValidationError, + lambda e: {"message": str(e), "context": {"debug": "postgresql://svc:TOPSECRET@db/prod"}}, + ), + ) + findings = _projector_key_violations(bad_context) + assert findings and "context" in findings[0], findings + + # The shipped registry passes the gate (the module imported), and presentation-only + # kwargs construct the fixed semantic class. + assert _projector_key_violations(()) == [] + built = _build_normalized_error( + AdCPValidationError, + {"message": "bad field", "field": "packages[0].budget", "details": {"safe": True}}, ) + assert built.wire_error_code == "VALIDATION_ERROR" + assert built.field == "packages[0].budget" + assert built.details == {"safe": True} # --------------------------------------------------------------------------- @@ -309,19 +818,25 @@ def failing_tool(): class TestA2AHandlerExplicitSkillReraises: - """``_handle_explicit_skill`` re-raises typed AdCPError verbatim. - - This class verifies the handler-internal contract: the skill dispatcher - catches the typed exception, audits the workflow step, and re-raises so - the OUTER ``on_message_send`` boundary wraps the failure into a Task - artifact carrying the two-layer envelope DataPart. + """``_handle_explicit_skill`` re-raises a WIRE-SAFE error (provenance decided at the seam). + + This class verifies the handler-internal contract: the skill dispatcher catches the + exception, audits, and re-raises via ``safe_adcp_error`` so the OUTER ``on_message_send`` + boundary wraps a failure that is ALREADY sanitized: + + - CLIENT-CORRECTABLE typed errors (``AdCPValidationError``, ``AdCPNotFoundError``, …) re-raise + VERBATIM — their controlled buyer-facing message is preserved. + - INTERNAL typed errors (``AdCPAdapterError``/``AdCPServiceUnavailableError`` → SERVICE_UNAVAILABLE, + terminal ``CONFIGURATION_ERROR``) are SCRUBBED at the seam — re-raised as a wire-safe base + ``AdCPError`` with a generic message (a raise site can interpolate a secret). + - RAW built-ins (``ValueError``/``PermissionError``) keep their SEMANTIC code (VALIDATION_ERROR / + AUTH_REQUIRED — the same the synchronous boundaries emit) but their untrusted ``str(e)`` is + scrubbed. Re-raising the *normalized typed* error here instead would hand the outer sanitizer + a trusted ``AdCPValidationError`` and let the secret survive. Wire-envelope coverage for the A2A boundary lives in - ``tests/integration/test_a2a_error_responses.py`` — those tests drive - ``handler.on_message_send(...)`` and assert on ``result.artifacts[0]`` - (the gold-standard pattern). The tests in this class stop at the - handler-internal re-raise so they're cheap unit-level pins for the - re-raise contract; they do NOT validate the envelope reaches the wire. + ``tests/integration/test_a2a_error_responses.py`` and the public failed-Task tests in + ``tests/unit/test_a2a_error_routing.py``. """ @pytest.mark.asyncio @@ -332,7 +847,7 @@ async def test_adcp_validation_propagates_for_dispatcher_wrap(self): handler = AdCPRequestHandler() async def mock_skill(params, token): - raise AdCPValidationError("invalid param") + raise AdCPValidationError("invalid param", _wire_safe_message=True) with patch.object(handler, "_handle_get_products_skill", mock_skill): with pytest.raises(AdCPValidationError) as exc_info: @@ -343,23 +858,58 @@ async def mock_skill(params, token): assert exc_info.value.recovery == "correctable" @pytest.mark.asyncio - @pytest.mark.asyncio - async def test_adcp_adapter_propagates_for_dispatcher_wrap(self): - """AdCPAdapterError propagates with transient recovery.""" + async def test_adcp_adapter_scrubbed_at_seam(self): + """AdCPAdapterError (internal → SERVICE_UNAVAILABLE) is scrubbed at the seam. + + Its raise sites do ``AdCPAdapterError(f"...: {e}")`` where ``e`` can bear a connection + string, so the seam must not re-raise the raw message. Recovery stays transient (the + code's canonical value).""" from src.a2a_server.adcp_a2a_server import AdCPRequestHandler + from src.core.exceptions import AdCPError handler = AdCPRequestHandler() async def mock_skill(params, token): - raise AdCPAdapterError("GAM down") + raise AdCPAdapterError(f"GAM down: {SECRET_BEARING_MESSAGE}") with patch.object(handler, "_handle_get_products_skill", mock_skill): - with pytest.raises(AdCPAdapterError) as exc_info: + with pytest.raises(AdCPError) as exc_info: await handler._handle_explicit_skill("get_products", {}, "token") - assert "GAM down" in exc_info.value.message + assert_no_secret_leak(exc_info.value.message, context="seam-scrubbed message") + assert "GAM down" not in exc_info.value.message + assert exc_info.value.wire_error_code == "SERVICE_UNAVAILABLE" assert exc_info.value.recovery == "transient" + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("exc_factory", "expected_code"), + [ + pytest.param(lambda s: ValueError(s), "VALIDATION_ERROR", id="ValueError"), + pytest.param(lambda s: PermissionError(s), "AUTH_REQUIRED", id="PermissionError"), + ], + ) + async def test_raw_builtin_keeps_semantic_code_but_scrubs_message(self, exc_factory, expected_code): + """A raw ``ValueError``/``PermissionError`` raised in a skill keeps the SEMANTIC code the + synchronous boundaries emit (VALIDATION_ERROR / AUTH_REQUIRED) but has its untrusted + ``str(e)`` scrubbed — the seam must not re-raise a normalized typed error carrying the + secret.""" + from src.a2a_server.adcp_a2a_server import AdCPRequestHandler + from src.core.exceptions import AdCPError + + handler = AdCPRequestHandler() + secret = SECRET_BEARING_MESSAGE + + async def mock_skill(params, token): + raise exc_factory(secret) + + with patch.object(handler, "_handle_get_products_skill", mock_skill): + with pytest.raises(AdCPError) as exc_info: + await handler._handle_explicit_skill("get_products", {}, "token") + + assert exc_info.value.wire_error_code == expected_code + assert_no_secret_leak(exc_info.value.message, context="seam-scrubbed builtin message") + @pytest.mark.asyncio async def test_server_error_still_passes_through(self): """Existing A2AError behavior preserved — re-raised unchanged.""" @@ -394,7 +944,10 @@ def test_adcp_error_keeps_typed_code(self): """AdCPError instances flow through unchanged — typed code preserved.""" from src.a2a_server.adcp_a2a_server import AdCPRequestHandler - result = AdCPRequestHandler._build_failed_skill_result("get_products", AdCPValidationError("bad input")) + result = AdCPRequestHandler._build_failed_skill_result( + "get_products", + AdCPValidationError("bad input", _wire_safe_message=True), + ) assert result["success"] is False assert result["skill"] == "get_products" @@ -404,37 +957,210 @@ def test_adcp_error_keeps_typed_code(self): assert env["errors"][0]["code"] == "VALIDATION_ERROR" assert env["errors"][0]["recovery"] == "correctable" - def test_untyped_exception_wrapped_in_synthetic_adcp_error(self): - """Bare ``Exception`` is wrapped in a synthetic AdCPError with wire-safe code. + def test_untyped_exception_wrapped_in_sanitized_adcp_error(self): + """Bare ``Exception`` is wrapped in a SANITIZED synthetic AdCPError. - ``AdCPError`` defaults to ``INTERNAL_ERROR`` which lives in - ``INTERNAL_CODES`` — ``wire_error_code`` translates it to - ``SERVICE_UNAVAILABLE`` so buyer agents only see standard codes. + Per the A2A boundary security policy (``safe_adcp_error``), an untyped + exception must NOT expose its raw ``str(exc)`` — which may carry credentials, + connection strings, SQL, or hostnames. The message is replaced with a generic + internal error, and the wire code is the safe ``SERVICE_UNAVAILABLE`` + (``AdCPError`` defaults to ``INTERNAL_ERROR`` → translated by ``wire_error_code``). """ from src.a2a_server.adcp_a2a_server import AdCPRequestHandler - result = AdCPRequestHandler._build_failed_skill_result("get_products", RuntimeError("unexpected boom")) + result = AdCPRequestHandler._build_failed_skill_result( + "get_products", RuntimeError(f"{SECRET_BEARING_MESSAGE} unexpected boom") + ) assert result["success"] is False env = result["error_envelope"] # Wire code is translated via ERROR_CODE_MAPPING assert env["adcp_error"]["code"] == "SERVICE_UNAVAILABLE" assert env["errors"][0]["code"] == "SERVICE_UNAVAILABLE" - # The original RuntimeError message is preserved verbatim - assert "unexpected boom" in env["errors"][0]["message"] + # The raw exception text is NEVER on the wire — only a generic internal message. + assert_no_secret_leak(env, context="full failed-skill envelope") + message = env["errors"][0]["message"] + assert "unexpected boom" not in message + assert "internal error" in message.lower() + + def test_untyped_exception_with_empty_message_still_sanitized(self): + """An untyped exception with no string content still yields the generic sanitized + message — never an empty ``message`` (spec requires non-empty) and never the raw + exception class name (which could itself hint at internals). + """ + from src.a2a_server.adcp_a2a_server import AdCPRequestHandler - def test_exception_with_empty_message_falls_back_to_type_name(self): - """Untyped exceptions with no string content get the exception class name. + result = AdCPRequestHandler._build_failed_skill_result("get_products", RuntimeError()) - Avoids emitting an empty ``message`` field that violates the spec's - non-empty-message expectation on the wire envelope. + env = result["error_envelope"] + message = env["errors"][0]["message"] + assert message, "wire envelope message must be non-empty" + assert message != "RuntimeError", "must not fall back to the exception class name" + assert "internal error" in message.lower() + + def test_internal_bucket_typed_error_message_is_scrubbed(self): + """A TYPED internal/infra error (SERVICE_UNAVAILABLE bucket) that interpolated a + secret into its message is scrubbed at the boundary — code + recovery preserved. + + Reachable handlers build e.g. ``AdCPAdapterError(f"...: {e}")`` where ``e`` carries a + DB connection string. Because it is already an ``AdCPError`` a naive sanitizer would + trust it; ``safe_adcp_error`` instead replaces the message for the + ``wire_error_code == "SERVICE_UNAVAILABLE"`` bucket while keeping the wire code and the + buyer-facing retry semantics (``recovery``). """ from src.a2a_server.adcp_a2a_server import AdCPRequestHandler - result = AdCPRequestHandler._build_failed_skill_result("get_products", RuntimeError()) + secret = SECRET_BEARING_MESSAGE + result = AdCPRequestHandler._build_failed_skill_result( + "create_media_buy", AdCPAdapterError(f"Failed to create media buy: {secret}") + ) env = result["error_envelope"] - assert env["errors"][0]["message"] == "RuntimeError" + blob = json.dumps(env) + assert_no_secret_leak(blob) + # Wire code preserved (adapter → SERVICE_UNAVAILABLE); recovery preserved (transient). + assert env["adcp_error"]["code"] == "SERVICE_UNAVAILABLE" + assert env["errors"][0]["code"] == "SERVICE_UNAVAILABLE" + assert env["errors"][0]["recovery"] == "transient" + assert "internal error" in env["errors"][0]["message"].lower() + + def test_internal_error_for_scrubs_full_jsonrpc_wire(self): + """A typed internal-bucket error must not leak through the + JSON-RPC ``error.message`` even while ``error.data`` is scrubbed. + + ``_internal_error_for`` previously built the top-level JSON-RPC message from the + ORIGINAL ``exc.message`` — so an ``AdCPAdapterError(f"...{e}")`` carrying a DB URL + had a sanitized envelope in ``error.data`` while the URL stayed visible in + ``error.message``. Both layers of the FULL wire object must be clean. (The + REACHABLE-handler proof — that a real push-config handler produces this scrubbed + InternalError — is ``test_push_config_handler_scrubs_secret_on_full_wire`` below.) + """ + from src.a2a_server.adcp_a2a_server import _internal_error_for + + secret = SECRET_BEARING_MESSAGE + err = _internal_error_for( + "set_task_push_notification_config", AdCPAdapterError(f"Failed to store config: {secret}") + ) + + full_wire = json.dumps({"message": err.message, "data": err.data}) + assert_no_secret_leak(full_wire) + # Wire code + recovery still accurate in the envelope. + assert err.data["adcp_error"]["code"] == "SERVICE_UNAVAILABLE" + assert err.data["errors"][0]["recovery"] == "transient" + + @pytest.mark.asyncio + async def test_push_config_handler_scrubs_secret_on_full_wire(self): + """Reachable-path and serialized-wire proof: a real push-config + handler whose backing store raises a secret-bearing internal error produces a + JSON-RPC error whose full serialized wire (``{jsonrpc, id, error:{code,message,data}}``) + leaks nothing. + + Drives the actual ``on_get_task_push_notification_config`` handler (one of the four + push-config methods that surface through ``_internal_error_for``), captures the REAL + raised ``InternalError``, and serializes it through the a2a SDK's own + ``build_error_response`` — the exact function ``JsonRpcDispatcher._generate_error_response`` + uses to produce the wire — so the assertion is on the actual serialized JSON-RPC + output, not a hand-built ``{message, data}`` dict. + """ + from types import SimpleNamespace + + from a2a.server.request_handlers.response_helpers import build_error_response + from a2a.types import InternalError + + import src.a2a_server.adcp_a2a_server as a2a_mod + from src.a2a_server.adcp_a2a_server import AdCPRequestHandler + + secret = SECRET_BEARING_MESSAGE + + handler = AdCPRequestHandler() + handler._get_auth_token = lambda context: "tok" # noqa: ARG005 + # Identity object is irrelevant — _make_tool_context is stubbed to the scope the + # handler actually reads. This keeps the test at unit altitude (no DB). + handler._resolve_a2a_identity = lambda *a, **k: object() + handler._make_tool_context = lambda *a, **k: SimpleNamespace(tenant_id="t", principal_id="p") + + class _BoomUoW: + def __init__(self, *a, **k): + pass + + def __enter__(self): + raise AdCPAdapterError(f"Config store unavailable: {secret}") + + def __exit__(self, *a): + return False + + with patch.object(a2a_mod, "PushNotificationConfigUoW", _BoomUoW): + with pytest.raises(InternalError) as exc_info: + await handler.on_get_task_push_notification_config({"id": "cfg_1"}, context=None) + + err = exc_info.value + # Serialize through the SDK's real JSON-RPC error builder (the dispatcher's path). + wire_dict = build_error_response("req-1", err) + serialized = serialize_wire_error(wire_dict) + assert_no_secret_leak(serialized) + assert wire_dict["error"]["data"]["adcp_error"]["code"] == "SERVICE_UNAVAILABLE" + + @pytest.mark.asyncio + @pytest.mark.parametrize("method_name", ["on_get_task", "on_cancel_task"]) + async def test_durable_task_handlers_scrub_secret_on_full_wire(self, method_name): + """A DB failure inside tasks/get or tasks/cancel must surface as a sanitized + JSON-RPC InternalError, never the raw exception text. These two handlers gained + durable DB access without the boundary arm their siblings have — an untyped + escape reached the SDK dispatcher, which echoes ``str(exc)`` verbatim on the + wire. Serializes through the SDK's own ``build_error_response`` (the dispatcher's + path) and asserts the full wire via the shared leak oracle.""" + from types import SimpleNamespace + + from a2a.server.request_handlers.response_helpers import build_error_response + from a2a.types import GetTaskRequest, InternalError + + from src.a2a_server.adcp_a2a_server import AdCPRequestHandler + + handler = AdCPRequestHandler() + handler._get_auth_token = lambda context: "tok" # noqa: ARG005 + handler._resolve_a2a_identity = lambda *a, **k: SimpleNamespace(tenant_id="t", principal_id="p") + + def _boom_db(): + raise RuntimeError(SECRET_BEARING_MESSAGE) + + # No owned in-memory task, so both handlers fall through to the durable + # (DB-touching) path, which is where the untyped failure fires. + with patch("src.core.database.database_session.get_db_session", _boom_db): + with pytest.raises(InternalError) as exc_info: + await getattr(handler, method_name)(GetTaskRequest(id="task_x"), context=None) + + err = exc_info.value + wire_dict = build_error_response("req-1", err) + serialized = serialize_wire_error(wire_dict) + assert_no_secret_leak(serialized, context=f"{method_name} JSON-RPC wire") + assert wire_dict["error"]["data"]["adcp_error"]["code"] == "SERVICE_UNAVAILABLE" + + def test_internal_error_for_preserves_correctable_message(self): + """The JSON-RPC message keeps the controlled text of a + client-correctable typed error — the fix must not over-sanitize.""" + from src.a2a_server.adcp_a2a_server import _internal_error_for + + err = _internal_error_for( + "set_task_push_notification_config", + AdCPValidationError("url is required", _wire_safe_message=True), + ) + assert "url is required" in err.message + + def test_client_correctable_typed_error_message_is_preserved(self): + """A client-correctable typed error keeps its controlled message — the boundary must + NOT over-sanitize. Buyers need the specific guidance to fix their request. + """ + from src.a2a_server.adcp_a2a_server import AdCPRequestHandler + + result = AdCPRequestHandler._build_failed_skill_result( + "get_products", + AdCPValidationError("brief must not be empty", _wire_safe_message=True), + ) + + env = result["error_envelope"] + assert env["errors"][0]["code"] == "VALIDATION_ERROR" + assert env["errors"][0]["recovery"] == "correctable" + assert env["errors"][0]["message"] == "brief must not be empty" def test_envelope_shape_matches_typed_branch(self): """Untyped fallthrough produces the SAME envelope shape as the typed branch. @@ -448,7 +1174,11 @@ def test_envelope_shape_matches_typed_branch(self): """ from src.a2a_server.adcp_a2a_server import AdCPRequestHandler - typed = AdCPRequestHandler._build_failed_skill_result("s", AdCPValidationError("bad")) + # Conformant raise sites carry a top-level suggestion; the untyped + # branch synthesizes one, so the typed sample must too for shape parity. + typed = AdCPRequestHandler._build_failed_skill_result( + "s", AdCPValidationError("bad", suggestion="Correct the request and resend.") + ) untyped = AdCPRequestHandler._build_failed_skill_result("s", RuntimeError("boom")) assert set(typed.keys()) == set(untyped.keys()) @@ -491,6 +1221,108 @@ def test_envelope_shape_matches_typed_branch(self): class TestRESTBoundaryAdCPErrorTranslation: """REST endpoints propagate AdCPError to the app-level exception handler with recovery.""" + def test_auth_error_observability_ignores_client_selected_tenant_scope(self): + """REST auth rejection stays unscoped and performs no second identity lookup.""" + from starlette.requests import Request + + from src.app import _envelope_response + from src.core.exceptions import AdCPAuthenticationError + + request = Request( + { + "type": "http", + "method": "GET", + "path": "/api/v1/capabilities", + "headers": [(b"x-adcp-tenant", b"tenant-rest")], + } + ) + error = AdCPAuthenticationError("rejected") + + with ( + patch("src.app._best_effort_rest_identity") as mock_identity, + patch("src.app.record_boundary_error") as mock_record, + ): + response = _envelope_response(request, error, original=error) + + mock_identity.assert_not_called() + mock_record.assert_called_once_with( + "rest", + "/api/v1/capabilities", + error, + tenant_id=None, + principal_id=None, + ) + assert response.status_code == error.status_code + + def test_anonymous_validation_error_cannot_write_to_header_selected_tenant(self): + """Pre-auth validation failures remain unscoped despite tenant hints.""" + from starlette.requests import Request + + from src.app import _envelope_response + + request = Request( + { + "type": "http", + "method": "POST", + "path": "/api/v1/media-buys", + "headers": [(b"x-adcp-tenant", b"victim-tenant")], + } + ) + error = AdCPValidationError("malformed request") + anonymous = SimpleNamespace(tenant_id="victim-tenant", principal_id=None) + + with ( + patch("src.app.resolve_identity", return_value=anonymous), + patch("src.app.record_boundary_error") as mock_record, + ): + response = _envelope_response(request, error, original=error) + + mock_record.assert_called_once_with( + "rest", + "/api/v1/media-buys", + error, + tenant_id=None, + principal_id=None, + ) + assert response.status_code == error.status_code + + def test_boundary_log_receives_the_original_not_the_sanitized_twin(self): + """The privileged server log must see the exception as raised. + + ``record_boundary_error`` picks log severity from ``isinstance(error, AdCPError)``: + an untyped crash gets ERROR + ``exc_info=True``, a typed error gets WARNING. Handing + it ``safe_adcp_error(exc)`` made that test always true, so a genuine REST crash + logged at WARNING with the scrubbed message and no traceback — while MCP and A2A, + which pass the original, kept theirs. + + Identity (``is``) is the load-bearing check: an equality assertion would also pass + on a re-derived sanitized twin, which is exactly the bug. + """ + import json as _json + + from starlette.requests import Request + + from src.app import _envelope_response + from src.core.exceptions import safe_adcp_error + + request = Request({"type": "http", "method": "GET", "path": "/api/v1/capabilities", "headers": []}) + original = RuntimeError(SECRET_BEARING_MESSAGE) + wire_error = safe_adcp_error(original) + + with ( + patch("src.app._best_effort_rest_identity", return_value=(None, None)), + patch("src.app.record_boundary_error") as mock_record, + ): + response = _envelope_response(request, wire_error, original=original) + + # Count-guarded: ``call_args`` reads only the LAST call, so without this the + # sole oracle for this path would pass on a duplicate (or extra) boundary record. + assert mock_record.call_count == 1, f"expected exactly one boundary record, got {mock_record.call_count}" + assert mock_record.call_args.args[2] is original + # The wire still carries the sanitized error, never the original's text. + assert response.status_code == wire_error.status_code + assert_no_secret_leak(_json.loads(response.body), context="REST envelope body") + def test_adcp_validation_from_impl_returns_400(self): """AdCPValidationError raised in _impl → REST returns 400 with correctable recovery.""" from starlette.testclient import TestClient @@ -499,7 +1331,7 @@ def test_adcp_validation_from_impl_returns_400(self): with patch( "src.core.tools.capabilities.get_adcp_capabilities_raw", - side_effect=AdCPValidationError("invalid request"), + side_effect=AdCPValidationError("invalid request", _wire_safe_message=True), ): client = TestClient(app, raise_server_exceptions=False) response = client.get("/api/v1/capabilities") @@ -508,11 +1340,28 @@ def test_adcp_validation_from_impl_returns_400(self): response.json(), "VALIDATION_ERROR", recovery="correctable", message_substr="invalid request" ) + def test_untyped_impl_failure_returns_sanitized_two_layer_envelope(self): + """Unexpected REST crashes stay typed without exposing raw exception text.""" + from starlette.testclient import TestClient + + from src.app import app + + with patch( + "src.core.tools.capabilities.get_adcp_capabilities_raw", + side_effect=RuntimeError(SECRET_BEARING_MESSAGE), + ): + client = TestClient(app, raise_server_exceptions=False) + response = client.get("/api/v1/capabilities") + + assert response.status_code == 500 + assert_envelope_shape(response.json(), "SERVICE_UNAVAILABLE", recovery="transient") + assert_no_secret_leak(response.json(), context="REST untyped failure envelope") + def test_adcp_not_found_from_impl_returns_404(self): """AdCPNotFoundError raised in _impl → REST returns 404 with correctable recovery. Recovery matches the pinned enumMetadata of the WIRE code: - INVALID_REQUEST=correctable (salesagent-nr2q). + INVALID_REQUEST=correctable. """ from starlette.testclient import TestClient @@ -634,25 +1483,32 @@ class TestRESTSymmetricValueErrorAndPermissionError: same wire shape. """ - def test_value_error_returns_400_with_validation_envelope(self): - """Raw ValueError → 400 with VALIDATION_ERROR envelope (mirrors MCP wrapper).""" + @pytest.mark.parametrize( + ("exception", "expected_code", "expected_status"), + [ + pytest.param(ValueError(SECRET_BEARING_MESSAGE), "VALIDATION_ERROR", 400, id="value-error"), + pytest.param(PermissionError(SECRET_BEARING_MESSAGE), "AUTH_REQUIRED", 403, id="permission-error"), + ], + ) + def test_raw_error_returns_scrubbed_envelope(self, exception, expected_code, expected_status): + """Raw built-ins retain their semantic code without exposing their message.""" from starlette.testclient import TestClient from src.app import app with patch( "src.core.tools.capabilities.get_adcp_capabilities_raw", - side_effect=ValueError("invalid input shape"), + side_effect=exception, ): client = TestClient(app, raise_server_exceptions=False) response = client.get("/api/v1/capabilities") - assert response.status_code == 400 + assert response.status_code == expected_status assert_envelope_shape( response.json(), - "VALIDATION_ERROR", + expected_code, recovery="correctable", - message_substr="invalid input shape", ) + assert_no_secret_leak(response.json(), context=f"REST {type(exception).__name__} envelope") def test_request_validation_error_unaffected(self): """FastAPI's RequestValidationError handler is NOT overridden by our ValueError handler. @@ -716,13 +1572,14 @@ def test_preserves_source_status_code(self, source_cls_name, message, expected_s assert response.status_code == expected_status def test_plain_tool_error_falls_back_to_500(self): - """Plain ToolError with no recognized wire code defaults to 500.""" + """Plain ToolError defaults to a scrubbed 500 envelope.""" from fastmcp.exceptions import ToolError from src.core.tool_error_logging import handle_tool_error - response = handle_tool_error(ToolError("unstructured failure")) + response = handle_tool_error(ToolError(SECRET_BEARING_MESSAGE)) assert response.status_code == 500 + assert_no_secret_leak(response.body) def test_plain_tool_error_with_known_code_uses_status_map(self): """Plain ToolError("VALIDATION_ERROR", "msg") → 400 via _ERROR_CODE_TO_STATUS. @@ -736,8 +1593,9 @@ def test_plain_tool_error_with_known_code_uses_status_map(self): from src.core.tool_error_logging import handle_tool_error - response = handle_tool_error(ToolError("VALIDATION_ERROR", "missing required field")) + response = handle_tool_error(ToolError("VALIDATION_ERROR", SECRET_BEARING_MESSAGE)) assert response.status_code == 400 + assert_no_secret_leak(response.body) def test_plain_tool_error_with_auth_code_returns_403(self): """Plain ToolError("AUTH_REQUIRED", "msg") → 403 via _ERROR_CODE_TO_STATUS. @@ -774,6 +1632,29 @@ def test_plain_tool_error_with_unknown_code_falls_back_to_500(self): response = handle_tool_error(ToolError("WEIRD_LEGACY_CODE", "what is this")) assert response.status_code == 500 + @pytest.mark.parametrize( + ("error_code", "contradictory_recovery", "expected_recovery"), + [ + ("SERVICE_UNAVAILABLE", "terminal", "transient"), + ("CONFIGURATION_ERROR", "transient", "terminal"), + ], + ) + def test_plain_tool_error_recovery_is_canonicalized( + self, + error_code, + contradictory_recovery, + expected_recovery, + ): + """An untyped positional hint cannot contradict standardized code metadata.""" + from fastmcp.exceptions import ToolError + + from src.core.tool_error_logging import handle_tool_error + from tests.helpers import assert_envelope_shape + + response = handle_tool_error(ToolError(error_code, SECRET_BEARING_MESSAGE, contradictory_recovery)) + assert_envelope_shape(json.loads(response.body), error_code, recovery=expected_recovery) + assert_no_secret_leak(response.body) + # --------------------------------------------------------------------------- # to_dict() serialization: recovery field present and correct @@ -798,7 +1679,7 @@ def test_to_dict_includes_recovery_for_all_subclasses(self): ) cases = [ - # Recovery follows the wire code (salesagent-nr2q): base + # Recovery follows the wire code: base # AdCPError→SERVICE_UNAVAILABLE=transient, # AdCPNotFoundError→INVALID_REQUEST=correctable. (AdCPError("internal"), "transient"), @@ -822,7 +1703,7 @@ def test_to_dict_custom_recovery_override(self): """Custom recovery= kwarg overrides class default in to_dict() output.""" from src.core.exceptions import AdCPNotFoundError - # Default is "correctable" (wire INVALID_REQUEST, salesagent-nr2q) + # Default is "correctable" (wire INVALID_REQUEST) default_exc = AdCPNotFoundError("gone") assert default_exc.to_dict()["recovery"] == "correctable" @@ -911,11 +1792,11 @@ async def mock_skill(params, token): assert exc_info.value.recovery == "transient" -class TestCustomRecoveryOverrideRESTBoundary: - """Custom recovery= override must propagate through REST boundary (exception handler).""" +class TestInternalRecoveryCanonicalizationRESTBoundary: + """Internal errors use the pinned recovery at the REST wire boundary.""" - def test_custom_recovery_propagates_through_rest_boundary(self): - """AdCPAdapterError(recovery='terminal') -> REST JSON body has 'terminal'.""" + def test_custom_internal_recovery_is_canonicalized_at_rest_boundary(self): + """AdCPAdapterError(recovery='terminal') emits scrubbed canonical SERVICE_UNAVAILABLE.""" from starlette.testclient import TestClient from src.app import app @@ -928,7 +1809,8 @@ def test_custom_recovery_propagates_through_rest_boundary(self): client = TestClient(app, raise_server_exceptions=False) response = client.get("/api/v1/capabilities") assert response.status_code == 502 - assert_envelope_shape(response.json(), "SERVICE_UNAVAILABLE", recovery="terminal") + assert_envelope_shape(response.json(), "SERVICE_UNAVAILABLE", recovery="transient") + assert "permanent failure" not in response.text # --------------------------------------------------------------------------- @@ -959,7 +1841,7 @@ def test_mcp_roundtrip_all_subclasses(self): # and INVALID_REQUEST respectively). Other subclasses already use STANDARD codes. cases = [ # Recovery matches the pinned classification of the WIRE code - # (salesagent-nr2q): SERVICE_UNAVAILABLE=transient, INVALID_REQUEST=correctable. + #: SERVICE_UNAVAILABLE=transient, INVALID_REQUEST=correctable. (AdCPError, "internal", "SERVICE_UNAVAILABLE", "transient"), (AdCPValidationError, "bad", "VALIDATION_ERROR", "correctable"), (AdCPNotFoundError, "missing", "INVALID_REQUEST", "correctable"), @@ -998,15 +1880,17 @@ def failing(): @pytest.mark.asyncio async def test_a2a_handler_explicit_skill_reraises_all_subclasses(self): - """All 11 AdCPError subclasses propagate verbatim from ``_handle_explicit_skill``. + """Recovery is preserved for every AdCPError subclass through ``_handle_explicit_skill``, + but INTERNAL subclasses are scrubbed at the seam (generic message, wire SERVICE_UNAVAILABLE) + while CLIENT-CORRECTABLE subclasses re-raise verbatim (original type + message). - Scope: handler-internal re-raise. The outer ``on_message_send`` - boundary wraps the propagated exception into a Task artifact - carrying the two-layer envelope; that wire-level coverage is in + Scope: handler-internal re-raise. The outer ``on_message_send`` boundary wraps the + propagated exception into a Task artifact; wire-level coverage is in ``tests/integration/test_a2a_error_responses.py``. """ from src.a2a_server.adcp_a2a_server import AdCPRequestHandler from src.core.exceptions import ( + _SANITIZED_INTERNAL_MESSAGE, AdCPAdapterError, AdCPBudgetExhaustedError, AdCPConflictError, @@ -1018,30 +1902,40 @@ async def test_a2a_handler_explicit_skill_reraises_all_subclasses(self): AdCPValidationError, ) + # Recovery matches the pinned classification of the WIRE code. The + # SERVICE_UNAVAILABLE trio is the internal bucket — scrubbed at the seam; the rest are + # client-correctable and re-raise verbatim. cases = [ - # Recovery matches the pinned classification of the WIRE code (salesagent-nr2q). - (AdCPError, "internal", "transient"), - (AdCPValidationError, "bad", "correctable"), - (AdCPNotFoundError, "missing", "correctable"), - (AdCPConflictError, "dup", "transient"), - (AdCPGoneError, "expired", "correctable"), - (AdCPBudgetExhaustedError, "broke", "terminal"), - (AdCPRateLimitError, "slow", "transient"), - (AdCPAdapterError, "down", "transient"), - (AdCPServiceUnavailableError, "offline", "transient"), + (AdCPError, "internal", "transient", True), + (AdCPValidationError, "bad", "correctable", False), + (AdCPNotFoundError, "missing", "correctable", False), + (AdCPConflictError, "dup", "transient", False), + (AdCPGoneError, "expired", "correctable", False), + (AdCPBudgetExhaustedError, "broke", "terminal", False), + (AdCPRateLimitError, "slow", "transient", False), + (AdCPAdapterError, "down", "transient", True), + (AdCPServiceUnavailableError, "offline", "transient", True), ] handler = AdCPRequestHandler() - for exc_class, msg, expected_recovery in cases: + for exc_class, msg, expected_recovery, scrubbed in cases: async def mock_skill(params, token, klass=exc_class, message=msg): - raise klass(message) + kwargs = {"_wire_safe_message": True} if issubclass(klass, AdCPValidationError) else {} + raise klass(message, **kwargs) with patch.object(handler, "_handle_get_products_skill", mock_skill): - with pytest.raises(exc_class) as exc_info: + with pytest.raises(AdCPError) as exc_info: await handler._handle_explicit_skill("get_products", {}, "token") - assert exc_info.value.recovery == expected_recovery + raised = exc_info.value + assert raised.recovery == expected_recovery, f"{exc_class.__name__}: recovery" + if scrubbed: + assert raised.message == _SANITIZED_INTERNAL_MESSAGE, f"{exc_class.__name__}: not scrubbed" + assert raised.wire_error_code == "SERVICE_UNAVAILABLE", f"{exc_class.__name__}: wire code" + else: + assert isinstance(raised, exc_class), f"{exc_class.__name__}: client-correctable must be verbatim" + assert raised.message == msg, f"{exc_class.__name__}: message must be preserved" def test_rest_roundtrip_all_subclasses(self): """All 11 AdCPError subclasses: raise -> REST handler -> JSON body -> verify recovery.""" @@ -1064,7 +1958,7 @@ def test_rest_roundtrip_all_subclasses(self): # tests above. HTTP status_code is preserved (it comes from the exception # class directly, not from the wire code translation). cases = [ - # Recovery matches the pinned classification of the WIRE code (salesagent-nr2q). + # Recovery matches the pinned classification of the WIRE code. (AdCPError, "internal", 500, "SERVICE_UNAVAILABLE", "transient"), (AdCPValidationError, "bad", 400, "VALIDATION_ERROR", "correctable"), (AdCPNotFoundError, "missing", 404, "INVALID_REQUEST", "correctable"), diff --git a/tests/unit/test_error_format_consistency.py b/tests/unit/test_error_format_consistency.py index 9eb7439c63..f2237ddd25 100644 --- a/tests/unit/test_error_format_consistency.py +++ b/tests/unit/test_error_format_consistency.py @@ -18,8 +18,15 @@ from pydantic import ValidationError from src.a2a_server.adcp_a2a_server import AdCPRequestHandler -from src.core.exceptions import AdCPAuthenticationError, AdCPError, AdCPValidationError +from src.core.exceptions import ( + AdCPAuthenticationError, + AdCPCapabilityNotSupportedError, + AdCPError, + AdCPValidationError, +) from src.core.resolved_identity import ResolvedIdentity +from tests.factories import PrincipalFactory +from tests.helpers import assert_envelope_shape class TestMCPErrorShapes: @@ -156,33 +163,45 @@ async def test_auth_required_error_is_server_error(self): error = exc_info.value assert isinstance(error, A2AError) - assert "Authentication required" in str(error) + assert_envelope_shape( + error.data, + "AUTH_MISSING", + recovery="correctable", + message_substr="Authentication required", + ) @pytest.mark.asyncio - async def test_unknown_skill_raises_server_error(self): - """A2A raises A2AError for unknown skill names.""" + async def test_unknown_skill_raises_capability_not_supported(self): + """A2A raises a typed AdCP error for unknown skills (application-layer, not JSON-RPC). + + The message/send method is valid; routing failed inside skill dispatch, so + per AdCP "Layer Separation" this is an application error surfaced as a failed + Task with UNSUPPORTED_FEATURE — never a JSON-RPC ``A2AError``. + """ from src.core.resolved_identity import ResolvedIdentity mock_identity = ResolvedIdentity( principal_id="test_principal", tenant_id="default", tenant={"tenant_id": "default"}, protocol="a2a" ) - with pytest.raises(A2AError) as exc_info: + with pytest.raises(AdCPCapabilityNotSupportedError) as exc_info: await self.handler._handle_explicit_skill( skill_name="nonexistent_skill", parameters={}, identity=mock_identity, ) - error = exc_info.value - assert isinstance(error, A2AError) - assert "Unknown skill" in str(error) + assert not isinstance(exc_info.value, A2AError) + assert exc_info.value.error_code == "UNSUPPORTED_FEATURE" + assert str(exc_info.value) == ("The requested skill is not supported. Call discovery to list available skills.") @pytest.mark.asyncio async def test_invalid_auth_identity_raises_server_error(self): - """A2A raises A2AError when identity has no principal (auth required skill).""" - # Identity with no principal_id simulates invalid auth - invalid_identity = ResolvedIdentity( - principal_id=None, tenant_id="default", tenant={"tenant_id": "default"}, protocol="a2a" + """A rejected A2A identity emits the terminal AUTH_INVALID wire envelope.""" + invalid_identity = PrincipalFactory.make_identity( + principal_id=None, + tenant_id="default", + tenant={"tenant_id": "default"}, + protocol="a2a", ) with pytest.raises(A2AError) as exc_info: @@ -192,7 +211,12 @@ async def test_invalid_auth_identity_raises_server_error(self): identity=invalid_identity, ) - assert "Authentication required" in str(exc_info.value) + assert_envelope_shape( + exc_info.value.data, + "AUTH_INVALID", + recovery="terminal", + message_substr="credentials were rejected", + ) @pytest.mark.asyncio async def test_missing_params_raises_typed_validation_error(self): @@ -492,7 +516,11 @@ async def test_unknown_skill_only_affects_a2a(self): """Unknown skill errors only apply to A2A (MCP validates tool names separately). MCP uses FastMCP's tool registry which rejects unknown tools at the protocol level. - A2A uses _handle_explicit_skill which maps skill names to handlers. + A2A uses _handle_explicit_skill which maps skill names to handlers. An unknown + skill is an APPLICATION-layer failure (the message/send method is valid; routing + failed inside skill dispatch), so per AdCP "Layer Separation" the dispatcher + raises a typed ``AdCPCapabilityNotSupportedError`` (UNSUPPORTED_FEATURE), which + the outer handler surfaces as a failed Task — NOT a JSON-RPC ``A2AError``. """ handler = AdCPRequestHandler() @@ -501,15 +529,15 @@ async def test_unknown_skill_only_affects_a2a(self): mock_identity = ResolvedIdentity( principal_id="test_principal", tenant_id="default", tenant={"tenant_id": "default"}, protocol="a2a" ) - with pytest.raises(A2AError) as exc_info: + with pytest.raises(AdCPCapabilityNotSupportedError) as exc_info: await handler._handle_explicit_skill( skill_name="totally_fake_skill", parameters={}, identity=mock_identity, ) - error_str = str(exc_info.value) - assert "Unknown skill" in error_str or "totally_fake_skill" in error_str + assert exc_info.value.error_code == "UNSUPPORTED_FEATURE" + assert str(exc_info.value) == ("The requested skill is not supported. Call discovery to list available skills.") @pytest.mark.asyncio async def test_serialize_for_a2a_error_response_structure(self): @@ -581,20 +609,19 @@ def test_mcp_tool_error_carries_recovery(self, exc_class, msg, expected_code, ex klass = getattr(exc_mod, exc_class) def failing_tool(): - raise klass(msg) + kwargs = {"_wire_safe_message": True} if exc_class == "AdCPValidationError" else {} + raise klass(msg, **kwargs) wrapped = with_error_logging(failing_tool) with pytest.raises(ToolError) as exc_info: wrapped() - from tests.helpers import assert_envelope_shape - assert_envelope_shape( exc_info.value, expected_code, recovery=expected_recovery, - message_substr=msg, + message_substr=None if expected_code == "SERVICE_UNAVAILABLE" else msg, check_mcp_tool_error=True, ) @@ -696,8 +723,8 @@ def test_custom_recovery_override_in_to_dict(self): overridden = AdCPConflictError("permanent conflict", recovery="terminal") assert overridden.to_dict()["recovery"] == "terminal" - def test_custom_recovery_survives_mcp_then_extract(self): - """Custom recovery: AdCPError(recovery=X) -> ToolError -> extract_error_info -> X.""" + def test_internal_recovery_is_canonicalized_by_mcp_boundary(self): + """Internal wire codes use pinned recovery rather than a raise-site override.""" from fastmcp.exceptions import ToolError from src.core.exceptions import AdCPAdapterError @@ -712,7 +739,9 @@ def failing(): wrapped() code, message, recovery = extract_error_info(exc_info.value) - assert recovery == "terminal" # Custom, not default "transient" + assert code == "SERVICE_UNAVAILABLE" + assert recovery == "transient" + assert message != "permanent failure" # --------------------------------------------------------------------------- @@ -740,6 +769,8 @@ class TestErrorCodeVocabularyConsistency: "VALIDATION_ERROR", # adcp-req: Generic Errors "INVALID_REQUEST", # SDK standard: AdCPInvalidRequestError (semantically-invalid value) "AUTH_REQUIRED", # SDK standard: auth failures (AdCPAuthenticationError + AdCPAuthorizationError) + "AUTH_MISSING", # Spec supplement: absent Authorization credentials + "AUTH_INVALID", # Spec supplement: presented credentials rejected "POLICY_VIOLATION", # SDK standard: AdCPPolicyViolationError (content/advertising policy block) "NOT_FOUND", # Base class for entity-specific codes (internal only) "ACCOUNT_NOT_FOUND", # adcp-req: Account resolution (BR-RULE-080) @@ -786,6 +817,8 @@ def test_all_exception_error_codes_are_canonical(self): from src.core.exceptions import ( AdCPAdapterError, AdCPAuthenticationError, + AdCPAuthInvalidError, + AdCPAuthMissingError, AdCPAuthorizationError, AdCPBudgetExhaustedError, AdCPConflictError, @@ -800,6 +833,8 @@ def test_all_exception_error_codes_are_canonical(self): AdCPError, AdCPValidationError, AdCPAuthenticationError, + AdCPAuthMissingError, + AdCPAuthInvalidError, AdCPAuthorizationError, AdCPNotFoundError, AdCPConflictError, diff --git a/tests/unit/test_exception_normalization.py b/tests/unit/test_exception_normalization.py index 1df79b37cd..52480fe514 100644 --- a/tests/unit/test_exception_normalization.py +++ b/tests/unit/test_exception_normalization.py @@ -1,9 +1,17 @@ import pytest from pydantic import ValidationError -from src.core.exceptions import AdCPValidationError, normalize_to_adcp_error +from src.core.exceptions import ( + VALIDATION_ERROR_SUGGESTION, + AdCPInvalidRequestError, + AdCPValidationError, + build_two_layer_error_envelope, + normalize_to_adcp_error, + safe_adcp_error, +) from src.core.validation_helpers import adcp_validation_boundary from tests.helpers import assert_no_raw_validation_leak +from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE, assert_no_secret_leak def test_pydantic_validation_error_normalization_is_structured_and_sanitized(): @@ -21,13 +29,13 @@ def test_pydantic_validation_error_normalization_is_structured_and_sanitized(): normalized = normalize_to_adcp_error(error) assert isinstance(normalized, AdCPValidationError) - assert normalized.message == "Field required" + assert normalized.message == "Required field is missing." assert normalized.field == "packages[0].product_id" assert normalized.details == { "validation_errors": [ { "loc": ["packages", 0, "product_id"], - "msg": "Field required", + "msg": "Required field is missing.", "type": "missing", } ] @@ -55,15 +63,374 @@ def test_a2a_validation_boundary_preserves_contextual_error_format(): assert "Invalid parameters:" in exc_info.value.message assert "packages.0.product_id: Required field is missing" in exc_info.value.message assert exc_info.value.field == "packages[0].product_id" - assert exc_info.value.suggestion == ("Provide the required 'packages.0.product_id' field and resend the request.") + assert exc_info.value.suggestion == VALIDATION_ERROR_SUGGESTION assert exc_info.value.details == { "validation_errors": [ { "loc": ["packages", 0, "product_id"], - "msg": "Field required", + "msg": "Required field is missing.", "type": "missing", } ] } assert "buyer-input" not in exc_info.value.message assert_no_raw_validation_leak(exc_info.value.message) + + +def test_boundary_wrapped_extra_field_value_is_wire_safe(): + """A typed boundary translation must not become a sanitizer bypass.""" + error = ValidationError.from_exception_data( + title="Request", + line_errors=[ + { + "type": "extra_forbidden", + "loc": (SECRET_BEARING_MESSAGE,), + "input": SECRET_BEARING_MESSAGE, + } + ], + ) + + with pytest.raises(AdCPValidationError) as exc_info: + with adcp_validation_boundary(context="request"): + raise error + + envelope = build_two_layer_error_envelope(safe_adcp_error(exc_info.value)) + assert_no_secret_leak(envelope) + assert envelope["errors"][0]["field"] == "unrecognized_field" + assert envelope["errors"][0]["details"] == { + "validation_errors": [ + { + "loc": ["unrecognized_field"], + "msg": "Extra field is not allowed by the AdCP request schema.", + "type": "extra_forbidden", + } + ] + } + + +def test_unexpected_keyword_argument_is_reported_as_unrecognized_field(): + """MCP call-signature errors use the same safe field label as Pydantic extras.""" + error = ValidationError.from_exception_data( + title="call[list_creative_formats]", + line_errors=[ + { + "type": "unexpected_keyword_argument", + "loc": (SECRET_BEARING_MESSAGE,), + "input": SECRET_BEARING_MESSAGE, + } + ], + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + + assert_no_secret_leak(envelope) + assert envelope["errors"][0]["field"] == "unrecognized_field" + assert envelope["errors"][0]["details"]["validation_errors"] == [ + { + "loc": ["unrecognized_field"], + "msg": "Extra field is not allowed by the AdCP request schema.", + "type": "unexpected_keyword_argument", + } + ] + + +def test_raw_pydantic_projection_preserves_safe_multi_field_details(): + """Raw TypeAdapter validation keeps every field without raw values.""" + error = ValidationError.from_exception_data( + title="call[list_creative_formats]", + line_errors=[ + {"type": "int_parsing", "loc": ("max_width",), "input": SECRET_BEARING_MESSAGE}, + {"type": "int_parsing", "loc": ("min_height",), "input": SECRET_BEARING_MESSAGE}, + ], + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + assert_no_secret_leak(envelope) + assert envelope["errors"][0]["field"] == "max_width" + assert envelope["errors"][0]["details"]["validation_errors"] == [ + {"loc": ["max_width"], "msg": "Expected an integer value.", "type": "int_parsing"}, + {"loc": ["min_height"], "msg": "Expected an integer value.", "type": "int_parsing"}, + ] + + +def test_mapping_key_location_is_redacted(): + """Non-schema mapping keys are request data, not safe field metadata.""" + error = ValidationError.from_exception_data( + title="Targeting", + line_errors=[ + { + "type": "string_type", + "loc": ("key_value_pairs", SECRET_BEARING_MESSAGE), + "input": {"bad": "value"}, + } + ], + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + assert_no_secret_leak(envelope) + assert envelope["errors"][0]["field"] == "key_value_pairs.nested_field" + assert envelope["errors"][0]["details"]["validation_errors"][0]["loc"] == [ + "key_value_pairs", + "nested_field", + ] + + +def test_identifier_shaped_mapping_key_location_is_redacted(): + """Mapping-key safety cannot depend on punctuation in the secret.""" + secret_key = "hunter2" + error = ValidationError.from_exception_data( + title="Targeting", + line_errors=[ + { + "type": "string_type", + "loc": ("key_value_pairs", secret_key), + "input": {"bad": "value"}, + } + ], + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + assert secret_key not in str(envelope) + assert envelope["errors"][0]["field"] == "key_value_pairs.nested_field" + + +def test_untrusted_typed_validation_preserves_transient_recovery(): + """Explicitly untrusted typed text is scrubbed without changing retry semantics.""" + error = AdCPValidationError( + SECRET_BEARING_MESSAGE, + recovery="transient", + _wire_safe_message=False, + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + + assert envelope["adcp_error"]["recovery"] == "transient" + assert envelope["errors"][0]["recovery"] == "transient" + assert_no_secret_leak(envelope) + + +def test_untrusted_typed_validation_message_is_scrubbed(): + """Typed validation text is untrusted unless a caller explicitly opts in.""" + error = AdCPValidationError( + f"Invalid created_after date format: {SECRET_BEARING_MESSAGE}", + field="created_after", + suggestion=f"Remove {SECRET_BEARING_MESSAGE} and retry", + details={"rejected": SECRET_BEARING_MESSAGE}, + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + assert_no_secret_leak(envelope) + assert envelope["errors"][0]["field"] == "created_after" + assert "details" not in envelope["errors"][0] + + +def test_string_length_projection_retains_numeric_schema_constraint(): + """Safe numeric constraint metadata remains actionable on the wire.""" + error = ValidationError.from_exception_data( + title="WebhookAuth", + line_errors=[ + { + "type": "string_too_short", + "loc": ("authentication", "credentials"), + "input": SECRET_BEARING_MESSAGE, + "ctx": {"min_length": 32}, + } + ], + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + assert_no_secret_leak(envelope) + assert "at least 32 characters" in envelope["errors"][0]["message"] + + +def test_numeric_range_projection_retains_safe_schema_bound(): + """Numeric constraint metadata is actionable without echoing rejected input.""" + error = ValidationError.from_exception_data( + title="Package", + line_errors=[ + { + "type": "greater_than_equal", + "loc": ("budget",), + "input": SECRET_BEARING_MESSAGE, + "ctx": {"ge": 0}, + } + ], + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + + assert_no_secret_leak(envelope) + assert envelope["errors"][0]["message"] == "Value must be greater than or equal to 0." + + +def test_deliberate_typed_validation_message_requires_explicit_wire_safe_opt_in(): + """Audited static business guidance remains actionable after explicit opt-in.""" + error = AdCPValidationError( + "At least one field must be provided for update.", + field="request", + suggestion="Provide a field to update and resend.", + _wire_safe_message=True, + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + + assert envelope["errors"][0]["message"] == "At least one field must be provided for update." + assert envelope["errors"][0]["suggestion"] == "Provide a field to update and resend." + + +def test_wire_safe_opt_in_governs_details_and_message_together(): + """``_wire_safe_message`` is ONE gate over BOTH untrusted text channels. + + ``message`` and ``details`` on a typed ``AdCPValidationError`` have the same + provenance — the raise site builds both, from the same values, with the same + (absent) audit. So they are trusted together or scrubbed together; there is no + state where the raise site's prose is too untrusted to emit but its structured + payload of the same values is fine. + + The scrubbed half is pinned by + ``test_untrusted_typed_validation_message_is_scrubbed`` (``details`` absent). + This pins the OTHER half, which was unenforced: an audited site that opts in + keeps its structured diagnostics, so opting in — not weakening the scrub — is + the sanctioned route to putting ``details`` on the wire. + + Why this needs an oracle at all: read from the scrub branch alone, the dropped + ``details`` looks like an oversight (a reviewer read it exactly that way and + proposed forwarding ``normalize_to_adcp_error(exc).details``). On that branch + ``normalize_to_adcp_error`` returns the SAME typed instance it was given, so + that forward would re-emit the very raise-site payload the branch exists to + withhold — 8 of the 9 ``details=``-passing sites in ``src/`` sit on it. + """ + audited = AdCPValidationError( + "Budget must be positive.", + field="budget", + details={"rejected_value": -5, "minimum": 0}, + _wire_safe_message=True, + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(audited)) + + # Spec 3.1.1 core/error.json documents details.rejected_value as the buyer's own + # offending value, "echoed for buyer-side diagnostic clarity" — and VALIDATION_ERROR's + # canonical suggestion ("review error details and fix field values") points AT it. + assert envelope["errors"][0]["details"] == {"rejected_value": -5, "minimum": 0} + assert envelope["adcp_error"]["details"] == {"rejected_value": -5, "minimum": 0} + + # Same raise site, same details, opt-in withdrawn -> both channels withheld together. + unaudited = AdCPValidationError( + "Budget must be positive.", + field="budget", + details={"rejected_value": -5, "minimum": 0}, + ) + + scrubbed = build_two_layer_error_envelope(safe_adcp_error(unaudited)) + + assert "details" not in scrubbed["errors"][0] + assert "details" not in scrubbed["adcp_error"] + assert scrubbed["errors"][0]["message"] != "Budget must be positive." + + +# A URL/token-shaped string standing in for "the buyer's own submitted value" in the four +# tests below. These tests prove TWO SEPARATE properties, not one — do not read the +# assertions as contradictory: +# 1. THIS value echoes to the wire — that's the expected, spec-sanctioned behavior (it's +# the buyer's own data; they already have it — see safe_adcp_error's grounding comment). +# 2. No OTHER content — specifically nothing from SECRET_BEARING_MESSAGE's _SECRET_TOKENS, +# standing in for genuine system/adapter secrets — ever rides along with it. +# Property 2 is only STATABLE if this constant is a different literal than +# SECRET_BEARING_MESSAGE: asserting "value X is present" and "value X's own tokens are +# absent" on the identical string is a contradiction, not a stronger test. Using a distinct +# literal here is what lets the test prove "this raise site interpolates ONLY the buyer's +# value, nothing adapter/system-sourced" — which is the actual security property that +# matters, not "this specific fixture never appears." +_BUYER_SUPPLIED_CREDENTIAL_SHAPED_VALUE = "https://example.com/callback?token=buyer-rotated-secret-789" + + +def test_duplicate_product_id_echoes_the_buyers_own_value_after_audited_opt_in(): + """Mirrors media_buy_create.py's duplicate-product_id raise site exactly. + + Proves the AdCP spec's sanctioned buyer-value echo (dist/schemas/3.1.1/core/error.json + ``details.rejected_value``: "the offending value the buyer supplied, echoed for + buyer-side diagnostic clarity") survives to the wire for a credential-/URL-shaped + value, while confirming this exact template has no path for a genuine system secret + to leak alongside it — the template only ever interpolates the buyer's own submitted + product_ids, nothing adapter- or system-sourced. + """ + duplicate_products = [_BUYER_SUPPLIED_CREDENTIAL_SHAPED_VALUE] + error_msg = ( + f"Duplicate product_id(s) found in packages: {', '.join(duplicate_products)}. " + "Each product can only be used once per media buy." + ) + error = AdCPValidationError( + error_msg, + suggestion="Each package must reference a distinct product_id; remove the duplicate package or change its product_id.", + _wire_safe_message=True, + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + + assert _BUYER_SUPPLIED_CREDENTIAL_SHAPED_VALUE in envelope["errors"][0]["message"] + assert_no_secret_leak(envelope) + + +def test_duplicate_product_id_without_wire_safe_opt_in_is_scrubbed(): + """Same buyer value, opt-in removed — proves the flag is load-bearing, not decorative.""" + error_msg = ( + f"Duplicate product_id(s) found in packages: {_BUYER_SUPPLIED_CREDENTIAL_SHAPED_VALUE}. " + "Each product can only be used once per media buy." + ) + error = AdCPValidationError( + error_msg, + suggestion="Each package must reference a distinct product_id; remove the duplicate package or change its product_id.", + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + + assert _BUYER_SUPPLIED_CREDENTIAL_SHAPED_VALUE not in envelope["errors"][0]["message"] + + +def test_targeting_overlay_echoes_the_buyers_own_unknown_field_after_audited_opt_in(): + """Mirrors media_buy_create.py's targeting-overlay raise site exactly. + + ``validate_unknown_targeting_fields`` (the real production validator) reports + ``model_extra`` keys — a duck-typed stub stands in for ``Targeting`` here because + this environment's ``extra='forbid'`` config (CLAUDE.md's Schema Validation + pattern) rejects an unknown field at construction time, before model_extra could + ever be populated for a direct Targeting() construction; the validator itself + accepts ``Any`` and only reads ``.model_extra``, so the stub exercises the same + code the raise site calls. + """ + from types import SimpleNamespace + + from src.services.targeting_capabilities import validate_unknown_targeting_fields + + stub = SimpleNamespace(model_extra={_BUYER_SUPPLIED_CREDENTIAL_SHAPED_VALUE: "irrelevant"}) + violations = validate_unknown_targeting_fields(stub) + assert violations == [f"{_BUYER_SUPPLIED_CREDENTIAL_SHAPED_VALUE} is not a recognized targeting field"] + + error_msg = f"Targeting validation failed: {'; '.join(violations)}" + error = AdCPInvalidRequestError( + error_msg, + suggestion="Check targeting constraints.", + field="targeting_overlay", + _wire_safe_message=True, + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + + assert _BUYER_SUPPLIED_CREDENTIAL_SHAPED_VALUE in envelope["errors"][0]["message"] + assert_no_secret_leak(envelope) + + +def test_targeting_overlay_without_wire_safe_opt_in_is_scrubbed(): + """Same buyer value, opt-in removed — proves the flag is load-bearing, not decorative.""" + violations = [f"{_BUYER_SUPPLIED_CREDENTIAL_SHAPED_VALUE} is not a recognized targeting field"] + error_msg = f"Targeting validation failed: {'; '.join(violations)}" + error = AdCPInvalidRequestError( + error_msg, + suggestion="Check targeting constraints.", + field="targeting_overlay", + ) + + envelope = build_two_layer_error_envelope(safe_adcp_error(error)) + + assert _BUYER_SUPPLIED_CREDENTIAL_SHAPED_VALUE not in envelope["errors"][0]["message"] diff --git a/tests/unit/test_execute_approved_pending_review_filter.py b/tests/unit/test_execute_approved_pending_review_filter.py index 8862681c01..b75e54247a 100644 --- a/tests/unit/test_execute_approved_pending_review_filter.py +++ b/tests/unit/test_execute_approved_pending_review_filter.py @@ -17,7 +17,12 @@ def test_pending_review_creative_not_uploaded(self): """A pending_review creative is excluded from the adapter asset list.""" from src.core.tools.media_buy_create import execute_approved_media_buy - # UoW chain: first UoW loads data, second updates status + # UoW chain: claim, load data, persist IDs, creative handling, active status + claim_uow = MagicMock() + claim_uow.__enter__ = MagicMock(return_value=claim_uow) + claim_uow.__exit__ = MagicMock(return_value=False) + claim_uow.media_buys.claim_approved_execution.return_value = True + uow1 = MagicMock() uow1.__enter__ = MagicMock(return_value=uow1) uow1.__exit__ = MagicMock(return_value=False) @@ -34,7 +39,12 @@ def test_pending_review_creative_not_uploaded(self): uow3.__exit__ = MagicMock(return_value=False) uow3.media_buys = MagicMock() - uow_iter = iter([uow1, uow2, uow3]) + uow4 = MagicMock() + uow4.__enter__ = MagicMock(return_value=uow4) + uow4.__exit__ = MagicMock(return_value=False) + uow4.media_buys = MagicMock() + + uow_iter = iter([claim_uow, uow1, uow2, uow3, uow4]) # Tenant tenant = MagicMock() @@ -54,8 +64,8 @@ def test_pending_review_creative_not_uploaded(self): mb.advertiser_name = "Advertiser" mb.start_date = datetime.now(UTC).date() mb.end_date = (datetime.now(UTC) + timedelta(days=7)).date() - mb.start_time = None - mb.end_time = None + mb.start_time = datetime.now(UTC) + timedelta(days=1) + mb.end_time = datetime.now(UTC) + timedelta(days=8) mb.budget = Decimal("1000.00") mb.currency = "USD" mb.raw_request = { @@ -70,6 +80,24 @@ def test_pending_review_creative_not_uploaded(self): pkg.package_id = "pkg_1" pkg.package_config = {"product_id": "prod_1", "name": "Pkg", "budget": 1000.0, "pricing_model": "CPM"} + product = MagicMock() + product.name = "Product" + product.delivery_type = "non_guaranteed" + product.format_ids = [ + { + "agent_url": "https://formats.example.com", + "id": "display_300x250", + "format_id": "display_300x250", + } + ] + pricing_option = MagicMock() + pricing_option.pricing_model = "CPM" + pricing_option.rate = Decimal("10") + pricing_option.currency = "USD" + pricing_option.is_fixed = True + pricing_option.root = pricing_option + product.pricing_options = [pricing_option] + # Creative assignment — status is pending_review assignment = MagicMock() assignment.creative_id = "cre_pending" @@ -81,12 +109,11 @@ def test_pending_review_creative_not_uploaded(self): pending_creative.status = "pending_review" session = uow1.session - session.scalars.return_value.first.side_effect = [tenant, mb] - session.scalars.return_value.all.side_effect = [ - [pkg], # db_packages - [assignment], # assignments - [pending_creative], # creatives - ] + session.scalars.return_value.first.side_effect = [tenant, mb, product] + session.scalars.return_value.all.return_value = [pkg] + creative_session = MagicMock() + creative_session.scalars.return_value.all.side_effect = [[assignment], [pending_creative]] + uow3.session = creative_session from src.core.schemas import CreateMediaBuySuccess, Principal @@ -104,14 +131,15 @@ def test_pending_review_creative_not_uploaded(self): patch("src.core.database.repositories.MediaBuyUoW", side_effect=lambda _: next(uow_iter)), patch("src.core.config_loader.set_current_tenant"), patch("src.core.config_loader.get_tenant_by_id", return_value={"tenant_id": "t1"}), - patch(f"{_MODULE}.get_principal_object", return_value=principal), + patch("src.core.auth.get_principal_object", return_value=principal), patch(f"{_MODULE}._execute_adapter_media_buy_creation", return_value=adapter_response), patch(f"{_MODULE}._validate_creatives_before_adapter_call"), - patch(f"{_MODULE}.get_adapter", return_value=mock_adapter), + patch("src.core.helpers.adapter_helpers.get_adapter", return_value=mock_adapter), ): success, error = execute_approved_media_buy("mb_1", "t1") # The pending_review creative must NOT have been uploaded + assert success is True, error mock_adapter.creatives_manager.add_creative_assets.assert_not_called() diff --git a/tests/unit/test_execute_approved_status_update.py b/tests/unit/test_execute_approved_status_update.py index cc5615fe7d..d84c7cf5cf 100644 --- a/tests/unit/test_execute_approved_status_update.py +++ b/tests/unit/test_execute_approved_status_update.py @@ -106,11 +106,12 @@ def test_status_updated_to_active_after_adapter_success(self): mock_adapter = MagicMock() mock_adapter.orders_manager = None - # Set up four UoW instances the function opens: - # 1. Load tenant, media_buy, packages, products - # 2. Persist platform_order_id after adapter success - # 3. Handle creative uploads - # 4. Update media buy status to 'active' (the fix) + # Set up the UoW instances the function opens: + # 1. Claim irreversible execution + # 2. Load tenant, media_buy, packages, products + # 3. Persist platform_order_id after adapter success + # 4. Handle creative uploads + # 5. Update media buy status to 'active' (the fix) mock_session_1 = MagicMock() mock_session_2 = MagicMock() mock_session_3 = MagicMock() @@ -128,6 +129,11 @@ def test_status_updated_to_active_after_adapter_success(self): mock_session_2.scalars = MagicMock(return_value=MagicMock(all=MagicMock(return_value=[]))) # Build mock UoWs — each call to MediaBuyUoW() returns the next one + mock_uow_claim = MagicMock() + mock_uow_claim.__enter__ = MagicMock(return_value=mock_uow_claim) + mock_uow_claim.__exit__ = MagicMock(return_value=None) + mock_uow_claim.media_buys.claim_approved_execution.return_value = True + mock_uow_1 = MagicMock() mock_uow_1.__enter__ = MagicMock(return_value=mock_uow_1) mock_uow_1.__exit__ = MagicMock(return_value=None) @@ -155,7 +161,7 @@ def test_status_updated_to_active_after_adapter_success(self): mock_uow_3.session = mock_session_3 mock_uow_3.media_buys = mock_repo_3 - uow_iter = iter([mock_uow_1, mock_uow_plids, mock_uow_2, mock_uow_3]) + uow_iter = iter([mock_uow_claim, mock_uow_1, mock_uow_plids, mock_uow_2, mock_uow_3]) with ( patch("src.core.database.repositories.MediaBuyUoW", side_effect=lambda _: next(uow_iter)), @@ -180,5 +186,26 @@ def test_status_updated_to_active_after_adapter_success(self): assert success is True, f"Expected success but got error: {error}" assert error is None - # THE KEY ASSERTION: update_status must be called with 'active' - mock_repo_3.update_status.assert_called_once_with("mb_test_001", "active") + # THE KEY ASSERTION: active is a CAS from the still-owned lease. + mock_repo_3.complete_approved_execution.assert_called_once_with("mb_test_001") + mock_uow_claim.media_buys.claim_approved_execution.assert_called_once_with("mb_test_001") + + def test_lost_execution_claim_never_dispatches_adapter(self): + """Only the atomic media-buy claim winner may create an external order.""" + claim_uow = MagicMock() + claim_uow.__enter__ = MagicMock(return_value=claim_uow) + claim_uow.__exit__ = MagicMock(return_value=None) + claim_uow.media_buys.claim_approved_execution.return_value = False + + with ( + patch("src.core.database.repositories.MediaBuyUoW", return_value=claim_uow), + patch("src.core.config_loader.set_current_tenant"), + patch("src.core.tools.media_buy_create._execute_adapter_media_buy_creation") as mock_adapter, + ): + from src.core.tools.media_buy_create import execute_approved_media_buy + + success, error = execute_approved_media_buy("mb_test_001", "tenant_1") + + assert success is None + assert error == "Approved media buy execution is already claimed or no longer pending" + mock_adapter.assert_not_called() diff --git a/tests/unit/test_generic_then_devacuum.py b/tests/unit/test_generic_then_devacuum.py index b482d4679d..c555e5eeb7 100644 --- a/tests/unit/test_generic_then_devacuum.py +++ b/tests/unit/test_generic_then_devacuum.py @@ -28,11 +28,16 @@ import pytest from src.core.schemas import ListCreativeFormatsResponse +from tests.bdd.steps.generic.then_error import ( + then_error_message_contains, + then_error_message_sanitized_without_disclosing, +) from tests.bdd.steps.generic.then_payload import ( then_boundary_handling_result, then_partition_filtering_result, ) from tests.bdd.steps.generic.then_success import then_response_status +from tests.harness.transport import TransportResult def _valid_uc005_ctx() -> dict: @@ -135,3 +140,65 @@ def test_response_status_completed_valid_still_passes() -> None: def test_response_status_non_completed_against_statusless_fails() -> None: with pytest.raises(AssertionError): then_response_status(_valid_uc005_ctx(), status="working") + + +def test_sanitized_step_proves_untrusted_fragment_was_scrubbed() -> None: + """The dedicated non-disclosure step catches a scrubbed wire message correctly. + + Was ``test_wire_message_assertion_proves_untrusted_fragment_was_scrubbed``, + calling ``then_error_message_contains(ctx, text="past")`` — which passed only + because THAT step used to silently switch to an ABSENCE check whenever the + wire message happened to already equal the canonical scrubbed text. SF-1 + removed that switching behavior (see ``then_error.py``): "should contain" is + now pure containment, always, and this non-disclosure assertion has its own + dedicated step. This test proves the invariant through the correct step. + """ + from src.core.exceptions import AdCPValidationError, build_two_layer_error_envelope, safe_adcp_error + + raw_fragment = "start time is in the past" + wire_error = safe_adcp_error(AdCPValidationError(raw_fragment)) + envelope = build_two_layer_error_envelope(wire_error) + ctx = { + "error": AdCPValidationError(raw_fragment), + "result": TransportResult(error=wire_error, wire_error_envelope=envelope), + } + + then_error_message_sanitized_without_disclosing(ctx, text="past") + + # And the containment step now means exactly what it says: the raw fragment + # is genuinely absent from the scrubbed wire message, so asserting its + # PRESENCE via "should contain" correctly fails. + with pytest.raises(AssertionError): + then_error_message_contains(ctx, text="past") + + +def test_error_code_step_grades_the_wire_not_the_reconstruction() -> None: + """``the error code should be`` follows the wire whenever one was captured. + + A step that stashes ``ctx['error']`` but never sets ``ctx['result']`` looks green while + grading only the reconstructed exception — and reconstruction is lossy, so a wire-only + regression cannot redden it. Pin the precedence directly: with the two disagreeing, the + wire code is the one that must decide. + """ + import pytest + + from src.core.exceptions import ( + AdCPCapabilityNotSupportedError, + AdCPValidationError, + build_two_layer_error_envelope, + safe_adcp_error, + ) + from tests.bdd.steps.generic.then_error import then_error_code + + # Reconstruction says VALIDATION_ERROR; the wire says UNSUPPORTED_FEATURE. + wire_error = safe_adcp_error(AdCPCapabilityNotSupportedError("nl create_media_buy is not supported")) + envelope = build_two_layer_error_envelope(wire_error) + ctx = { + "error": AdCPValidationError("reconstructed and lossy"), + "result": TransportResult(error=wire_error, wire_error_envelope=envelope), + } + + then_error_code(ctx, code=envelope["adcp_error"]["code"]) + + with pytest.raises(AssertionError): + then_error_code(ctx, code="VALIDATION_ERROR") diff --git a/tests/unit/test_mcp_auth_middleware.py b/tests/unit/test_mcp_auth_middleware.py index 40f48a0f84..140042aa68 100644 --- a/tests/unit/test_mcp_auth_middleware.py +++ b/tests/unit/test_mcp_auth_middleware.py @@ -1,8 +1,9 @@ """Tests for MCPAuthMiddleware — centralized identity resolution for MCP tools. -Core Invariant: Identity resolution happens exactly once per MCP request in the -middleware; tool functions read the pre-resolved identity from FastMCP context -state and never call resolve_identity_from_context() directly. +Core Invariant: The middleware makes exactly one authentication/identity +resolution call per MCP request; an auth failure may inspect tenant headers for +observability, but never performs a second credential validation. Tool +functions read the pre-resolved identity from FastMCP context state. These tests verify: 1. MCPAuthMiddleware class exists and inherits from Middleware @@ -59,9 +60,7 @@ def test_auth_optional_tools_defined(self): "list_creative_formats", "list_authorized_properties", } - assert expected_discovery.issubset(AUTH_OPTIONAL_TOOLS), ( - f"AUTH_OPTIONAL_TOOLS missing discovery tools: {expected_discovery - AUTH_OPTIONAL_TOOLS}" - ) + assert AUTH_OPTIONAL_TOOLS == expected_discovery class TestMCPAuthMiddlewareBehavior: @@ -100,6 +99,7 @@ async def test_auth_required_tool_stores_identity(self, middleware, mock_context mock_context.message.name = "create_media_buy" # auth-required mock_identity = MagicMock(spec=ResolvedIdentity) + mock_identity.principal_id = "principal-1" call_next = AsyncMock(return_value=MagicMock()) with patch( @@ -127,6 +127,7 @@ async def test_discovery_tool_stores_identity_without_requiring_auth(self, middl mock_context.message.name = "get_products" # discovery/auth-optional mock_identity = MagicMock(spec=ResolvedIdentity) + mock_identity.principal_id = "principal-1" call_next = AsyncMock(return_value=MagicMock()) with patch( @@ -144,24 +145,114 @@ async def test_discovery_tool_stores_identity_without_requiring_auth(self, middl @pytest.mark.asyncio async def test_auth_failure_raises_before_tool_runs(self, middleware, mock_context): - """Auth-required tool with invalid token: error before tool body.""" + """Auth-required tool with no credentials fails before the tool body.""" + from fastmcp.exceptions import ToolError + from src.core.exceptions import AdCPAuthenticationError + from tests.helpers import assert_envelope_shape mock_context.message = MagicMock() mock_context.message.name = "create_media_buy" call_next = AsyncMock() + auth_error = AdCPAuthenticationError("Invalid token") - with patch( - "src.core.mcp_auth_middleware.resolve_identity_from_context", - side_effect=AdCPAuthenticationError("Invalid token"), + with ( + patch( + "src.core.mcp_auth_middleware.resolve_identity_from_context", + side_effect=auth_error, + ) as mock_resolve, + patch("src.core.tool_error_logging.record_boundary_error") as mock_record, ): - with pytest.raises(AdCPAuthenticationError): + with pytest.raises(ToolError) as exc_info: await middleware.on_call_tool(mock_context, call_next) + mock_resolve.assert_called_once_with( + mock_context.fastmcp_context, + require_valid_token=True, + ) + mock_record.assert_called_once_with( + "mcp", + "create_media_buy", + auth_error, + tenant_id=None, + principal_id=None, + ) + assert_envelope_shape( + exc_info.value, + "AUTH_MISSING", + check_mcp_tool_error=True, + recovery="correctable", + ) # Tool was NOT called call_next.assert_not_awaited() + @pytest.mark.asyncio + async def test_presented_rejected_credentials_emit_auth_invalid(self, middleware, mock_context): + """A legacy resolver error is classified from credential presence.""" + from fastmcp.exceptions import ToolError + + from src.core.exceptions import AdCPAuthenticationError + from tests.helpers import assert_envelope_shape + + mock_context.message = MagicMock() + mock_context.message.name = "create_media_buy" + call_next = AsyncMock() + + with ( + patch( + "src.core.mcp_auth_middleware.extract_headers_from_context", + return_value={"authorization": "Bearer rejected-token"}, + ), + patch( + "src.core.mcp_auth_middleware.resolve_identity_from_context", + side_effect=AdCPAuthenticationError("Invalid token"), + ), + patch("src.core.tool_error_logging.record_boundary_error"), + ): + with pytest.raises(ToolError) as exc_info: + await middleware.on_call_tool(mock_context, call_next) + + assert_envelope_shape( + exc_info.value, + "AUTH_INVALID", + check_mcp_tool_error=True, + recovery="terminal", + ) + call_next.assert_not_awaited() + + @pytest.mark.asyncio + async def test_existing_tenant_header_auth_failure_never_reaches_tenant_sinks(self, middleware, mock_context): + """A known client-selected tenant cannot receive unauthenticated observability.""" + from fastmcp.exceptions import ToolError + + from src.core.exceptions import AdCPAuthenticationError + + mock_context.message = MagicMock() + mock_context.message.name = "create_media_buy" + mock_context.fastmcp_context.headers = {"x-adcp-tenant": "known-existing-tenant"} + call_next = AsyncMock() + auth_error = AdCPAuthenticationError("Invalid token") + + with ( + patch( + "src.core.mcp_auth_middleware.resolve_identity_from_context", + side_effect=auth_error, + ) as mock_resolve, + patch("src.services.activity_feed.activity_feed.log_error") as mock_feed, + patch("src.core.audit_logger.get_audit_logger") as mock_audit, + ): + with pytest.raises(ToolError): + await middleware.on_call_tool(mock_context, call_next) + + mock_resolve.assert_called_once_with( + mock_context.fastmcp_context, + require_valid_token=True, + ) + mock_feed.assert_not_called() + mock_audit.assert_not_called() + call_next.assert_not_awaited() + @pytest.mark.asyncio async def test_context_id_extracted_from_headers(self, middleware, mock_context): """x-context-id extracted from headers and stored on state.""" @@ -169,6 +260,7 @@ async def test_context_id_extracted_from_headers(self, middleware, mock_context) mock_context.message.name = "create_media_buy" mock_identity = MagicMock(spec=ResolvedIdentity) + mock_identity.principal_id = "principal-1" call_next = AsyncMock(return_value=MagicMock()) with ( diff --git a/tests/unit/test_mcp_compat_middleware.py b/tests/unit/test_mcp_compat_middleware.py index 8b60ab0a3d..33d7ddb99d 100644 --- a/tests/unit/test_mcp_compat_middleware.py +++ b/tests/unit/test_mcp_compat_middleware.py @@ -4,15 +4,16 @@ the context message when translations are applied. """ +from types import SimpleNamespace from unittest.mock import ANY, AsyncMock, MagicMock, patch import pytest -from src.core.exceptions import AdCPValidationError from src.core.mcp_compat_middleware import RequestCompatMiddleware from src.core.request_compat import NormalizationResult from src.core.tool_error_logging import AdCPToolError from tests.helpers import assert_envelope_shape, assert_no_raw_validation_leak +from tests.helpers.secret_scrub import SECRET_BEARING_MESSAGE, assert_no_secret_leak @pytest.fixture() @@ -52,16 +53,6 @@ def _typeadapter_validation_error(tool_name: str, line_error: dict): ) -class _ValidationErrorRecord: - """Matcher that pins the typed boundary error passed to the recorder.""" - - def __eq__(self, other: object) -> bool: - return isinstance(other, AdCPValidationError) and other.error_code == "VALIDATION_ERROR" - - def __repr__(self) -> str: - return "AdCPValidationError(error_code='VALIDATION_ERROR')" - - class TestMiddlewareCallsNormalizer: """Middleware delegates to normalize_request_params.""" @@ -228,11 +219,11 @@ async def test_typeadapter_validation_errors_are_adcp_tool_errors( exc_info.value, "VALIDATION_ERROR", recovery="correctable", - message_substr=message, check_mcp_tool_error=True, ) assert exc_info.value.envelope["errors"][0]["field"] == field wire_message = exc_info.value.envelope["errors"][0]["message"] + assert message not in wire_message assert_no_raw_validation_leak(wire_message) @pytest.mark.asyncio @@ -262,11 +253,77 @@ async def test_typeadapter_validation_errors_are_recorded_at_mcp_boundary(self, record_error.assert_called_once_with( "mcp", "list_creatives", - _ValidationErrorRecord(), + validation_error, tenant_id="tenant-1", principal_id="buyer-1", ) + @pytest.mark.asyncio + async def test_anonymous_discovery_validation_error_is_tenant_unscoped(self, middleware): + """Client-selected tenant hints cannot authorize observability writes.""" + ctx = _make_context("get_products", {"brief": []}) + identity = MagicMock(tenant_id="header-selected-tenant", principal_id=None) + ctx.fastmcp_context = MagicMock() + ctx.fastmcp_context.get_state = AsyncMock(return_value=identity) + validation_error = _typeadapter_validation_error( + "get_products", + { + "type": "string_type", + "loc": ("brief",), + "input": [], + }, + ) + + with ( + patch("src.core.config.is_production", return_value=False), + patch("src.core.mcp_compat_middleware.record_boundary_error") as record_error, + pytest.raises(AdCPToolError), + ): + await middleware.on_call_tool(ctx, AsyncMock(side_effect=validation_error)) + + record_error.assert_called_once_with( + "mcp", + "get_products", + validation_error, + tenant_id=None, + principal_id=None, + ) + + @pytest.mark.asyncio + async def test_typeadapter_secret_is_scrubbed_from_activity_and_audit_sinks(self, middleware): + """Raw validator provenance reaches the recorder so tenant sinks receive safe text.""" + ctx = _make_context("sync_creatives", {SECRET_BEARING_MESSAGE: SECRET_BEARING_MESSAGE}) + identity = MagicMock(tenant_id="tenant-1", principal_id="buyer-1") + ctx.fastmcp_context = MagicMock() + ctx.fastmcp_context.get_state = AsyncMock(return_value=identity) + validation_error = _typeadapter_validation_error( + "sync_creatives", + { + "type": "extra_forbidden", + "loc": (SECRET_BEARING_MESSAGE,), + "input": SECRET_BEARING_MESSAGE, + }, + ) + feed_records: list[dict[str, object]] = [] + audit_records: list[dict[str, object]] = [] + audit_logger = SimpleNamespace(log_operation=lambda **kwargs: audit_records.append(kwargs)) + + with ( + patch("src.core.config.is_production", return_value=False), + patch( + "src.services.activity_feed.activity_feed.log_error", + side_effect=lambda **kwargs: feed_records.append(kwargs), + ), + patch("src.core.audit_logger.get_audit_logger", return_value=audit_logger), + pytest.raises(AdCPToolError), + ): + await middleware.on_call_tool(ctx, AsyncMock(side_effect=validation_error)) + + assert len(feed_records) == 1 + assert len(audit_records) == 1 + assert_no_secret_leak(feed_records[0], context="MCP validation activity payload") + assert_no_secret_leak(audit_records[0], context="MCP validation audit payload") + class TestMiddlewareEdgeCases: """Edge cases: None arguments, empty arguments.""" diff --git a/tests/unit/test_media_buy.py b/tests/unit/test_media_buy.py index d1ccd61023..c6cef4f16e 100644 --- a/tests/unit/test_media_buy.py +++ b/tests/unit/test_media_buy.py @@ -30,6 +30,7 @@ AdCPBudgetExceededError, AdCPContextNotFoundError, AdCPCreativeRejectedError, + AdCPInvalidRequestError, AdCPProductNotFoundError, AdCPValidationError, ) @@ -58,6 +59,7 @@ ) from src.core.testing_hooks import AdCPTestContext from src.core.tools.media_buy_delivery import _get_media_buy_delivery_impl +from src.core.webhook_validator import WebhookURLValidator # --------------------------------------------------------------------------- # Shared helpers @@ -1153,6 +1155,28 @@ def test_pending_when_before_start(self): class TestCreateMediaBuyImplAuth: """UC-002 auth extension: identity and principal validation.""" + def test_format_agent_mcp_alias_is_shared_by_registration_and_product_matching(self): + """The supported base/``/mcp`` alias cannot diverge across create validators.""" + from src.core.tools.media_buy_create import ( + _format_reference_compatibility_key, + _validate_registered_format_agent, + ) + + base_url = "https://creative.adcontextprotocol.org" + endpoint_url = f"{base_url}/mcp/" + assert _format_reference_compatibility_key(base_url, "display_300x250") == ( + _format_reference_compatibility_key(endpoint_url, "display_300x250") + ) + for distinct_path in (f"{base_url}/a2a", f"{base_url}/.well-known/adcp/sales"): + assert _format_reference_compatibility_key(base_url, "display_300x250") != ( + _format_reference_compatibility_key(distinct_path, "display_300x250") + ) + _validate_registered_format_agent( + endpoint_url, + frozenset({base_url}), + field="packages[0].format_ids[0].agent_url", + ) + @pytest.mark.asyncio async def test_missing_identity_raises_validation_error(self): """UC-002-A01: None identity raises error. @@ -1208,6 +1232,82 @@ async def test_missing_tenant_raises_auth_error(self): with pytest.raises(AdCPAuthenticationError, match="(?i)tenant"): await _create_media_buy_impl(req, identity=identity) + @pytest.mark.asyncio + async def test_unsafe_push_url_is_rejected_before_workflow_writes(self): + """An invalid callback cannot leave a context or workflow-step artifact.""" + from src.core.tools.media_buy_create import _create_media_buy_impl + + req = _make_request() + identity = _make_identity() + + with ( + patch("src.core.tools.media_buy_create.validate_setup_complete"), + patch("src.core.tools.media_buy_create.resolve_principal_or_raise", return_value=MagicMock()), + patch("src.core.tools.media_buy_create._lookup_cached_replay", return_value=None), + patch.object( + WebhookURLValidator, + "validate_protocol_webhook_url", + return_value=(False, "blocked"), + ), + patch("src.core.tools.media_buy_create.get_context_manager") as get_context_manager, + pytest.raises(AdCPValidationError) as exc_info, + ): + await _create_media_buy_impl( + req, + # https:// on purpose: the registration gate now refuses http:// on the + # SCHEME before this path's host check runs, and the host check is what + # the patched validate_protocol_webhook_url below stands in for. + push_notification_config={"url": "https://127.0.0.1/internal"}, + identity=identity, + ) + + assert exc_info.value.field == "push_notification_config.url" + assert exc_info.value.message == "Push notification URL must resolve to a public HTTPS endpoint" + assert exc_info.value.error_code == "VALIDATION_ERROR" + get_context_manager.assert_not_called() + + @pytest.mark.asyncio + async def test_unregistered_format_agent_is_rejected_before_workflow_writes(self): + """A foreign FormatId federation identity is rejected on the real impl path.""" + from src.core.creative_agent_registry import CreativeAgentRegistry + from src.core.tools.media_buy_create import _create_media_buy_impl + + req = _make_request( + packages=[ + { + "product_id": "prod_1", + "budget": 5000.0, + "pricing_option_id": "cpm_usd_fixed", + "format_ids": [ + { + "agent_url": "https://unregistered-agent.example.com", + "id": "banner_300x250", + } + ], + } + ] + ) + identity = _make_identity() + + with ( + patch("src.core.tools.media_buy_create.validate_setup_complete"), + patch("src.core.tools.media_buy_create.resolve_principal_or_raise", return_value=MagicMock()), + patch("src.core.tools.media_buy_create._lookup_cached_replay", return_value=None), + patch.object( + CreativeAgentRegistry, + "get_registered_agent_urls", + return_value=frozenset({"https://creative.adcontextprotocol.org"}), + ), + patch("src.core.tools.media_buy_create.get_context_manager") as get_context_manager, + pytest.raises(AdCPInvalidRequestError) as exc_info, + ): + await _create_media_buy_impl(req, identity=identity) + + assert exc_info.value.error_code == "INVALID_REQUEST" + assert exc_info.value.message == "Creative agent is not registered." + assert exc_info.value.field == "packages[0].format_ids[0].agent_url" + get_context_manager.assert_not_called() + @pytest.mark.asyncio async def test_setup_incomplete_raises_error(self): """UC-002-A04: incomplete tenant setup raises validation error. diff --git a/tests/unit/test_media_buy_status_consistency.py b/tests/unit/test_media_buy_status_consistency.py index 05c3707b3c..56c0c20393 100644 --- a/tests/unit/test_media_buy_status_consistency.py +++ b/tests/unit/test_media_buy_status_consistency.py @@ -160,6 +160,8 @@ class TestAdcpProjectionAgreesWithCanonicalMap: "approved": "active", "ready": "pending_start", # sanctioned adaptation #2 "scheduled": "pending_start", # sanctioned adaptation #2 + "activating": "pending_start", + "activation_unknown": "pending_start", "pending_activation": "pending_start", "paused": "paused", "completed": "completed", diff --git a/tests/unit/test_protocol_webhook_ssrf.py b/tests/unit/test_protocol_webhook_ssrf.py index 9b5dd216f0..4547e7213e 100644 --- a/tests/unit/test_protocol_webhook_ssrf.py +++ b/tests/unit/test_protocol_webhook_ssrf.py @@ -37,13 +37,26 @@ from src.core.testing_hooks import AdCPTestContext from src.core.tools.creatives._sync import _sync_creatives_impl from src.core.tools.media_buy_create import _create_media_buy_impl -from src.core.webhook_validator import WEBHOOK_SSRF_SUGGESTION_DEV, reject_unsafe_webhook_registration_url +from src.core.webhook_validator import ( + WEBHOOK_SSRF_SUGGESTION_DEV, + WebhookURLValidator, + reject_unsafe_webhook_registration_url, +) from src.services.protocol_webhook_service import ProtocolWebhookService from tests.factories.principal import PrincipalFactory from tests.helpers import assert_envelope_shape from tests.helpers.adcp_factories import create_test_media_buy_request_dict, valid_reporting_webhook -_METADATA_URL = "http://169.254.169.254/latest/meta-data/" +# https:// on purpose: an http:// URL lets the scheme check reject before the host is +# ever examined, so the test would pass without the host defence running at all. +# +# Note what this does NOT establish. check_url_ssrf blocks hosts in two independent +# layers — BLOCKED_HOSTNAMES (a string set) and _blocked_ip_error (networks + the +# is_private/is_loopback/is_link_local predicates) — and both of these URLs are caught +# by the HOSTNAME layer, so disabling the IP layer entirely still leaves them green. +# Switching to https removes the scheme short-circuit; making either individual layer +# load-bearing needs a host that only that layer catches, which is separate work. +_METADATA_URL = "https://169.254.169.254/latest/meta-data/" def _config(url: str) -> PushNotificationConfig: @@ -105,7 +118,7 @@ async def test_send_notification_rejects_localhost_without_post(monkeypatch: pyt service = ProtocolWebhookService() with patch.object(service._session, "post", autospec=True) as mock_post: sent = await service.send_notification( - _config("http://localhost:9999/webhook"), + _config("https://localhost:9999/webhook"), # https: blocklist is the sole rejector payload={"task_id": "t1", "status": "completed"}, metadata={"task_type": "create_media_buy"}, ) @@ -122,8 +135,14 @@ async def test_send_notification_posts_when_url_is_public() -> None: response.raise_for_status = MagicMock() with ( + # Patches the validator this branch's delivery path actually calls. #1697 gated + # sends with the generic validate_outbound_webhook_url; this branch gates + # per-attempt inside the retry loop with validate_protocol_webhook_url — the + # protocol-callback validator, which carries the ADCP_WEBHOOK_TEST_HOST dev seam + # the e2e capture server needs. Intent of this test is unchanged: stub the gate + # open so the POST path itself is what's exercised. patch( - "src.core.webhook_validator.WebhookURLValidator.validate_outbound_webhook_url", + "src.core.webhook_validator.WebhookURLValidator.validate_protocol_webhook_url", return_value=(True, ""), ), patch.object(service._session, "post", return_value=response) as mock_post, @@ -162,8 +181,14 @@ async def test_send_notification_does_not_follow_redirect_to_metadata() -> None: redirect.raise_for_status.side_effect = requests.HTTPError("302 redirect") with ( + # Patches the validator this branch's delivery path actually calls. #1697 gated + # sends with the generic validate_outbound_webhook_url; this branch gates + # per-attempt inside the retry loop with validate_protocol_webhook_url — the + # protocol-callback validator, which carries the ADCP_WEBHOOK_TEST_HOST dev seam + # the e2e capture server needs. Intent of this test is unchanged: stub the gate + # open so the POST path itself is what's exercised. patch( - "src.core.webhook_validator.WebhookURLValidator.validate_outbound_webhook_url", + "src.core.webhook_validator.WebhookURLValidator.validate_protocol_webhook_url", return_value=(True, ""), ), patch.object(service._session, "post", return_value=redirect) as mock_post, @@ -202,6 +227,265 @@ def test_reject_unsafe_webhook_registration_url_raises_validation_error() -> Non assert exc_info.value.recovery == "correctable" +@pytest.mark.parametrize("callback_host", ["tests", "host.docker.internal"]) +def test_registration_admits_the_configured_e2e_callback_host(monkeypatch, callback_host: str) -> None: + """The E2E callback host must survive the create_media_buy registration gate. + + Drives the exact production helper both create_media_buy call sites use for + reporting_webhook.url and push_notification_config.url. When this gate did not + consult the development-only test-host seam, every E2E webhook flow died here + — before any delivery was attempted — with VALIDATION_ERROR on those fields. + + Both configured pairings are covered: "tests" for the in-network runner + (docker-compose.e2e.yml) and "host.docker.internal" for the standalone + fixture (tests/e2e/conftest.py), so neither CI mode can regress alone. + """ + monkeypatch.setenv("ENVIRONMENT", "development") + monkeypatch.setenv("ADCP_TESTING", "true") + monkeypatch.setenv("ADCP_WEBHOOK_TEST_HOST", callback_host) + + for field in ("reporting_webhook.url", "push_notification_config.url"): + # Does not raise — that IS the assertion (the helper's contract is + # raise-or-return-None, so a rejection surfaces as AdCPValidationError). + reject_unsafe_webhook_registration_url( + f"http://{callback_host}:9999/webhook", + field=field, + ) + + +def test_registration_seam_does_not_admit_other_hosts_in_development(monkeypatch) -> None: + """Admitting the E2E callback host must not admit private hosts generally.""" + monkeypatch.setenv("ENVIRONMENT", "development") + monkeypatch.setenv("ADCP_TESTING", "true") + monkeypatch.setenv("ADCP_WEBHOOK_TEST_HOST", "host.docker.internal") + + with pytest.raises(AdCPValidationError): + reject_unsafe_webhook_registration_url( + "http://metadata.google.internal/computeMetadata/v1/", + field="reporting_webhook.url", + ) + + +# EXPECTED VALUE per deployment shape — not "the two gates agree". +# +# An agreement-only assertion is what let a regression ship: unifying the two gates onto +# is_production() dropped HTTPS enforcement on DELIVERY for staging/test/prod/unset (5 of +# 7 shapes, where the previous rule was strict), and a test asserting only that the gates +# MATCH cannot see a change that moves both. Every row below therefore states the value. +# +# The rule is "HTTPS unless EXPLICITLY development", so every unrecognised or absent value +# is strict: `prod` is the sharp one — it reads as production to an operator and is not +# the literal `production` that is_production() compares against. +# +# ADCP_TESTING is varied deliberately and never changes a row: a testing flag must not be +# able to downgrade a deployment to plaintext for callbacks carrying Bearer credentials. +_ENV_MATRIX = [ + pytest.param(None, None, True, id="unset-strict"), + pytest.param(None, "true", True, id="unset-testing-still-strict"), + pytest.param("", None, True, id="empty-strict"), + pytest.param("development", None, False, id="development-permissive"), + pytest.param("development", "true", False, id="development-testing-permissive"), + pytest.param("DEVELOPMENT", None, False, id="development-case-insensitive"), + pytest.param("test", None, True, id="test-strict"), + pytest.param("staging", None, True, id="staging-strict"), + pytest.param("staging", "true", True, id="staging-testing-still-strict"), + pytest.param("prod", None, True, id="prod-abbrev-strict"), + pytest.param("prod", "true", True, id="prod-abbrev-testing-still-strict"), + pytest.param("production", None, True, id="production-strict"), + pytest.param("production", "true", True, id="production-testing-still-strict"), +] + + +def _requires_https(gate, host: str) -> bool: + """Whether ``gate`` admits ``https://host`` but refuses ``http://host``. + + Isolates the SCHEME axis. The two gates deliberately differ on the DNS axis — + registration passes ``resolve_dns=False`` so an unresolvable public hostname is + admissible at registration and re-checked at send time — so comparing their raw + verdicts on one URL measures DNS, not scheme (an earlier draft of this test did + exactly that and "failed" identically with and without the fix). Holding the host + fixed and flipping only the scheme cancels every other axis out. + """ + https_ok, _ = gate(f"https://{host}/webhook") + http_ok, _ = gate(f"http://{host}/webhook") + assert https_ok, f"{gate.__name__} rejected https://{host} — the probe host must clear every other axis" + return not http_ok + + +@pytest.mark.parametrize("environment,adcp_testing,expect_https_required", _ENV_MATRIX) +def test_callback_scheme_policy_per_environment(monkeypatch, environment, adcp_testing, expect_https_required) -> None: + """Both callback gates enforce the EXPECTED scheme for every deployment shape. + + Two properties in one assertion, and the second is the one a previous version of this + test lacked: + + 1. Registration and delivery agree — the host axis has ``_matches_development_test_host`` + keeping them on one definition, and this is the scheme equivalent. Without it, an + ``http://`` reporting webhook registered with a success response and then silently + never delivered on the default stack. + 2. They agree on the RIGHT value. The previous version asserted only that the two gates + MATCH, which cannot observe a change that moves both — and one did: unifying onto + ``is_production()`` dropped HTTPS enforcement on delivery for staging/test/prod/unset, + 5 of the 7 shapes it covered, with every test still green. + + ``ADCP_TESTING`` is varied across otherwise-identical rows and never changes the + expectation: a testing flag must not downgrade a deployment to plaintext for callbacks + carrying notification payloads and legacy Bearer credentials. + """ + for var, value in (("ENVIRONMENT", environment), ("ADCP_TESTING", adcp_testing)): + monkeypatch.delenv(var, raising=False) + if value is not None: + monkeypatch.setenv(var, value) + monkeypatch.delenv("ADCP_WEBHOOK_TEST_HOST", raising=False) + + # A resolvable public host, so DNS (the axis the gates legitimately differ on) is + # satisfied for both and only the scheme varies. + host = "reporting.example.com" + with patch("src.core.security.url_validator.socket.gethostbyname", return_value="93.184.216.34"): + register_strict = _requires_https(WebhookURLValidator.validate_webhook_url_registration, host) + deliver_strict = _requires_https(WebhookURLValidator.validate_protocol_webhook_url, host) + + context = f"ENVIRONMENT={environment!r} ADCP_TESTING={adcp_testing!r}" + assert register_strict == deliver_strict, ( + f"{context}: registration {'requires HTTPS' if register_strict else 'accepts http'} but " + f"delivery {'requires HTTPS' if deliver_strict else 'accepts http'}. A callback that " + f"registers and never delivers is invisible to the buyer." + ) + assert register_strict is expect_https_required, ( + f"{context}: expected HTTPS to be {'REQUIRED' if expect_https_required else 'optional'} " + f"at both callback gates, got {'required' if register_strict else 'optional'}. Only an " + f"explicit 'development' may relax this — anything unrecognised fails closed." + ) + + +# Loopback hosts, where the ADCP_TESTING allowance is the term that decides the verdict. +# A public host would clear the host axis for both gates in every row and grade nothing. +_HOST_AXIS_URLS = [ + pytest.param("https://localhost:9999/callback", id="https-localhost"), + pytest.param("https://127.0.0.1:9999/callback", id="https-loopback-ip"), +] + + +@pytest.mark.parametrize("url", _HOST_AXIS_URLS) +@pytest.mark.parametrize("environment,adcp_testing,_expect_https_required", _ENV_MATRIX) +def test_registration_is_more_permissive_than_delivery_on_loopback( + monkeypatch, environment, adcp_testing, _expect_https_required, url +) -> None: + """Characterizes the KNOWN host-axis divergence, in both directions. + + ``_matches_development_test_host``'s docstring used to claim the two gates agree on + the host axis. They do not: it is one TERM of the rule, and the ``ADCP_TESTING`` + loopback allowance is a second term applied at registration and not at protocol + delivery. Measured across ENVIRONMENT x ADCP_TESTING x URL, 5 of 32 combinations + register a callback delivery then refuses — a buyer accepted at registration whose + webhooks silently never arrive. + + This pins the divergence rather than asserting it away, because the two gates are NOT + interchangeable and the obvious unification is wrong in the dangerous direction: + ``validate_protocol_webhook_url`` is also the buyer-supplied callback gate in + ``create_media_buy``, so relaxing it to match registration widens an SSRF boundary. + Closing this properly means tightening REGISTRATION, which is tracked separately. + + Graded in both directions: delivery must never be the permissive one, and where + ``ADCP_TESTING`` is off the two must agree. So a change to either gate reddens this. + """ + for var, value in (("ENVIRONMENT", environment), ("ADCP_TESTING", adcp_testing)): + monkeypatch.delenv(var, raising=False) + if value is not None: + monkeypatch.setenv(var, value) + monkeypatch.delenv("ADCP_WEBHOOK_TEST_HOST", raising=False) + + with patch("src.core.security.url_validator.socket.gethostbyname", return_value="127.0.0.1"): + register_ok, _ = WebhookURLValidator.validate_webhook_url_registration(url) + deliver_ok, _ = WebhookURLValidator.validate_protocol_webhook_url(url) + + context = f"ENVIRONMENT={environment!r} ADCP_TESTING={adcp_testing!r} {url}" + assert not (deliver_ok and not register_ok), ( + f"{context}: delivery accepted a loopback callback that registration refused. " + "Delivery is the SSRF boundary for buyer-supplied callbacks and must never be " + "the more permissive of the two." + ) + if adcp_testing != "true": + assert register_ok == deliver_ok, ( + f"{context}: the gates diverge with ADCP_TESTING off, so the cause is not the " + "known loopback allowance — one of them changed." + ) + + +# The three sinks that can deliver the SAME buyer URL with the SAME Bearer token. They +# reach different validators, which is exactly how the scheme policy drifted apart. +_DELIVERY_SINKS = [ + pytest.param("validate_protocol_webhook_url", id="adcp-callback-delivery"), + pytest.param("validate_webhook_url_registration", id="adcp-callback-registration"), + # webhook_delivery_service and order_approval_service both arrive here via + # reject_unsafe_outbound_webhook_url. + pytest.param("validate_outbound_webhook_url", id="application-delivery"), +] + + +@pytest.mark.parametrize("gate_name", _DELIVERY_SINKS) +@pytest.mark.parametrize("environment", ["production", "prod", "staging", None], ids=lambda v: f"env-{v}") +def test_adcp_testing_never_downgrades_a_non_development_deployment(monkeypatch, gate_name, environment) -> None: + """A testing flag must not relax the SCHEME on any delivery sink. + + ``ADCP_TESTING`` exists to admit localhost capture servers — a HOST-axis allowance. + It used to also drop HTTPS enforcement entirely on ``validate_outbound_webhook_url``, + which short-circuited to ``validate_for_testing(require_https=False)`` whenever the + flag was set. Since a deployment can carry that flag, a production deployment could + ship plaintext delivery of callbacks carrying Bearer credentials. + + The property held at ONE of these three sinks and not the other two, for the same + buyer URL — which is why this is parametrized over the sinks rather than asserted on + whichever one a given test happened to reach. + """ + monkeypatch.delenv("ENVIRONMENT", raising=False) + if environment is not None: + monkeypatch.setenv("ENVIRONMENT", environment) + monkeypatch.setenv("ADCP_TESTING", "true") + monkeypatch.delenv("ADCP_WEBHOOK_TEST_HOST", raising=False) + + gate = getattr(WebhookURLValidator, gate_name) + with patch("src.core.security.url_validator.socket.gethostbyname", return_value="93.184.216.34"): + accepts_plaintext, _ = gate("http://buyer.example.com/adcp-callback") + + assert not accepts_plaintext, ( + f"{gate_name} accepted a plaintext callback with ENVIRONMENT={environment!r} because " + f"ADCP_TESTING was set. That flag governs the HOST axis (localhost capture servers), " + f"never the scheme — these callbacks carry notification payloads and Bearer tokens." + ) + + +@pytest.mark.parametrize("adcp_testing", [None, "true"], ids=["no-testing-flag", "testing-flag-set"]) +def test_production_rejects_plaintext_callbacks_at_both_gates(monkeypatch, adcp_testing) -> None: + """Unifying the scheme policy must not weaken real production. + + The pairing above only proves the two gates AGREE; this pins WHERE they agree for + the one deployment that matters, so agreement cannot be satisfied by making both + gates permissive. + + Parametrized over ``ADCP_TESTING`` on purpose, and that is the load-bearing half. + A first attempt at this fix unified both gates onto ``_require_https()`` + (``_strict_mode()`` = production AND NOT ADCP_TESTING) on the reasoning that the + protocol gate was the odd one out of three. That direction is backwards for a + security gate: "the other two are permissive" argues for tightening them, not for + loosening the strict one. It let a testing flag downgrade a production deployment + to plaintext for callbacks carrying notification payloads and legacy Bearer + credentials. The whole unit suite sets ADCP_TESTING=true via an autouse fixture, so + that cell is exactly where the weakening would hide. + """ + monkeypatch.setenv("ENVIRONMENT", "production") + monkeypatch.delenv("ADCP_TESTING", raising=False) + if adcp_testing is not None: + monkeypatch.setenv("ADCP_TESTING", adcp_testing) + monkeypatch.setenv("ADCP_WEBHOOK_TEST_HOST", "host.docker.internal") + + for url in ("http://reporting.example.com/webhook", "http://host.docker.internal:9999/webhook"): + registers, _ = WebhookURLValidator.validate_webhook_url_registration(url) + delivers, _ = WebhookURLValidator.validate_protocol_webhook_url(url) + assert not registers, f"production must not register plaintext {url} (ADCP_TESTING={adcp_testing!r})" + assert not delivers, f"production must not deliver to plaintext {url} (ADCP_TESTING={adcp_testing!r})" + + @pytest.mark.parametrize("blank", [None, "", " "]) def test_reject_unsafe_webhook_registration_url_noop_on_blank(blank: str | None) -> None: """Blank / missing URL is not a rejection — callers extract-then-call unconditionally.""" diff --git a/tests/unit/test_push_notification_url_validation.py b/tests/unit/test_push_notification_url_validation.py new file mode 100644 index 0000000000..6fc936515d --- /dev/null +++ b/tests/unit/test_push_notification_url_validation.py @@ -0,0 +1,78 @@ +"""The buyer-callback validator must give the same verdict for both input shapes. + +``validate_push_notification_config_url`` is reached from two entry points that hand it +different types for the same field: ``create_media_buy``'s wrappers deserialize JSON into +a dict of plain strings, while ``update_media_buy`` passes ``req.push_notification_config`` +through as the typed model — whose ``url`` is a Pydantic ``AnyUrl``, not a ``str``. + +The regression this pins: the validator type-guarded ``isinstance(url, str)`` before +coercing, which is correct for the dict path and rejected EVERY typed config on the update +path, safe URL or not. Every buyer updating a media buy with a callback got +``VALIDATION_ERROR`` on a perfectly good URL. + +It shipped because the only test was a REJECTION test — "update rejects a private +callback" — and a rejection test passes just as well when everything is rejected. So this +grades BOTH directions on BOTH shapes: an accept case is what makes the reject case +meaningful. +""" + +from __future__ import annotations + +import pytest +from adcp.types import PushNotificationConfig + +from src.core.exceptions import AdCPValidationError +from src.core.tools.media_buy_create import validate_push_notification_config_url + +# A resolvable public host, so the accept case exercises the real SSRF check rather than +# failing on DNS and looking like a correct rejection. +PUBLIC_URL = "https://example.com/callback" +LOOPBACK_URL = "https://127.0.0.1/callback" + + +def _as_dict(url: str) -> dict[str, str]: + """The shape create's wrappers produce (JSON -> plain strings).""" + return {"url": url} + + +def _as_model(url: str) -> PushNotificationConfig: + """The shape update passes through (``url`` is an ``AnyUrl``).""" + return PushNotificationConfig(url=url) + + +@pytest.mark.parametrize("build", [_as_dict, _as_model], ids=["dict", "typed-model"]) +def test_public_callback_is_accepted_on_both_input_shapes(build): + """A safe callback must be accepted however it arrives. + + This is the case the original rejection-only test could not see. + """ + assert validate_push_notification_config_url(build(PUBLIC_URL)) == PUBLIC_URL + + +@pytest.mark.parametrize("build", [_as_dict, _as_model], ids=["dict", "typed-model"]) +def test_loopback_callback_is_rejected_on_both_input_shapes(build): + """An unsafe callback must be refused however it arrives.""" + with pytest.raises(AdCPValidationError) as exc_info: + validate_push_notification_config_url(build(LOOPBACK_URL)) + assert exc_info.value.field == "push_notification_config.url" + + +def test_both_shapes_agree_url_for_url(): + """The two entry points cannot diverge on the same URL. + + Asserted as an equality between the two verdicts rather than two independent + expectations, so a future change that loosens or tightens one path alone reddens here + even if both individual cases still look reasonable on their own. + """ + for url in (PUBLIC_URL, LOOPBACK_URL): + + def verdict(cfg): + try: + return ("accepted", validate_push_notification_config_url(cfg)) + except AdCPValidationError: + return ("rejected", None) + + assert verdict(_as_dict(url)) == verdict(_as_model(url)), ( + f"create and update disagree about {url!r} — the same buyer-supplied callback " + "must get the same answer from both entry points" + ) diff --git a/tests/unit/test_repository_or_raise_helpers.py b/tests/unit/test_repository_or_raise_helpers.py index 7259f69a86..3b2a808025 100644 --- a/tests/unit/test_repository_or_raise_helpers.py +++ b/tests/unit/test_repository_or_raise_helpers.py @@ -75,11 +75,21 @@ class TestWorkflowOrRaise: def test_get_by_step_id_or_raise_returns_when_present(self): step = MagicMock() repo = _repo_with_first(WorkflowRepository, step) - assert repo.get_by_step_id_or_raise("step-1") is step + assert repo.get_by_step_id_or_raise("step-1", principal_id="principal-1") is step def test_get_by_step_id_or_raise_raises_when_absent(self): repo = _repo_with_first(WorkflowRepository, None) with pytest.raises(AdCPTaskNotFoundError) as exc: - repo.get_by_step_id_or_raise("step-missing") + repo.get_by_step_id_or_raise("step-missing", principal_id="principal-1") assert exc.value.error_code == "TASK_NOT_FOUND" assert "step-missing" in str(exc.value) + + def test_get_by_step_id_or_raise_requires_principal_scope(self): + """``principal_id`` is keyword-REQUIRED, so no call site can silently fetch unscoped. + + A default would mean "unscoped" at every site that forgot it — exactly the + defect this scoping closes — so the omission has to be a TypeError. + """ + repo = _repo_with_first(WorkflowRepository, MagicMock()) + with pytest.raises(TypeError, match="principal_id"): + repo.get_by_step_id_or_raise("step-1") # type: ignore[call-arg] diff --git a/tests/unit/test_resolved_identity.py b/tests/unit/test_resolved_identity.py index 37bd927f9b..bddf0a2e96 100644 --- a/tests/unit/test_resolved_identity.py +++ b/tests/unit/test_resolved_identity.py @@ -140,6 +140,44 @@ def test_resolve_anonymous_discovery(self, mock_get_subdomain, mock_get_vhost): assert identity.tenant_id == "default" assert identity.is_authenticated is False + @patch("src.core.auth_utils.get_principal_from_token", return_value=(None, None)) + @patch("src.core.resolved_identity.get_tenant_by_virtual_host", return_value=None) + @patch("src.core.resolved_identity.get_tenant_by_subdomain", return_value={"tenant_id": "default"}) + def test_rejected_legacy_token_without_authorization_is_auth_missing( + self, mock_get_subdomain, mock_get_vhost, mock_get_principal + ): + """Legacy credentials do not change the standard Authorization classifier.""" + from src.core.exceptions import AdCPAuthMissingError + + with pytest.raises(AdCPAuthMissingError) as exc_info: + resolve_identity( + headers={"x-adcp-tenant": "default", "x-adcp-auth": "rejected"}, + auth_token="rejected", + protocol="mcp", + ) + + assert exc_info.value.error_code == "AUTH_MISSING" + assert exc_info.value.recovery == "correctable" + mock_get_principal.assert_called_once_with("rejected", "default") + + @patch("src.core.auth_utils.get_principal_from_token", return_value=(None, None)) + @patch("src.core.resolved_identity.get_tenant_by_virtual_host", return_value=None) + @patch("src.core.resolved_identity.get_tenant_by_subdomain", return_value={"tenant_id": "hunter2"}) + def test_rejected_authorization_token_is_auth_invalid(self, mock_get_subdomain, mock_get_vhost, mock_get_principal): + from src.core.exceptions import AdCPAuthInvalidError + + with pytest.raises(AdCPAuthInvalidError) as exc_info: + resolve_identity( + headers={"x-adcp-tenant": "hunter2", "Authorization": "Bearer rejected"}, + auth_token="rejected", + protocol="mcp", + ) + + assert exc_info.value.error_code == "AUTH_INVALID" + assert exc_info.value.recovery == "terminal" + assert "hunter2" not in exc_info.value.message + mock_get_principal.assert_called_once_with("rejected", "hunter2") + @patch("src.core.resolved_identity.get_tenant_by_virtual_host", return_value=None) @patch("src.core.resolved_identity.get_tenant_by_subdomain") def test_resolve_localhost_defaults_to_default_tenant(self, mock_get_subdomain, mock_get_vhost): diff --git a/tests/unit/test_rest_depends_auth.py b/tests/unit/test_rest_depends_auth.py index 1c90afe28b..084ea0d821 100644 --- a/tests/unit/test_rest_depends_auth.py +++ b/tests/unit/test_rest_depends_auth.py @@ -13,6 +13,26 @@ from fastapi.params import Depends +from src.core.auth_policy import AUTH_OPTIONAL_SKILLS + +_REST_HANDLER_BY_SKILL = { + "get_adcp_capabilities": "get_capabilities", + "get_products": "get_products", + "list_authorized_properties": "list_authorized_properties", + "list_creative_formats": "list_creative_formats", +} +_REST_REQUIRED_HANDLERS = { + "create_media_buy", + "get_media_buy_delivery", + "list_accounts", + "list_creatives", + "sync_accounts", + "sync_creatives", + "update_media_buy", + "update_performance_index", +} +_ALL_REST_HANDLERS = set(_REST_HANDLER_BY_SKILL.values()) | _REST_REQUIRED_HANDLERS + class TestResolveAuthDependencyExists: """auth_context.py should export resolve_auth and require_auth Depends.""" @@ -127,19 +147,10 @@ def test_no_route_has_request_parameter(self): """No route handler should take a raw Request parameter anymore.""" import src.routes.api_v1 as api_v1_mod - route_names = [ - "get_products", - "get_capabilities", - "list_creative_formats", - "list_authorized_properties", - "create_media_buy", - "update_media_buy", - "get_media_buy_delivery", - "sync_creatives", - "list_creatives", - "update_performance_index", - ] - for name in route_names: + actual_route_names = {route.endpoint.__name__ for route in api_v1_mod.router.routes} + assert actual_route_names == _ALL_REST_HANDLERS + + for name in actual_route_names: func = getattr(api_v1_mod, name) sig = inspect.signature(func) assert "request" not in sig.parameters, ( @@ -147,6 +158,37 @@ def test_no_route_has_request_parameter(self): ) +class TestRestAuthOptionalPolicyParity: + """REST route signatures must implement the shared cross-transport policy.""" + + def test_optional_handler_oracle_covers_exactly_the_shared_policy(self): + assert set(_REST_HANDLER_BY_SKILL) == set(AUTH_OPTIONAL_SKILLS) + + def test_optional_handlers_use_the_dependency_derived_from_shared_policy(self): + import src.routes.api_v1 as api_v1_mod + from src.core.auth_context import resolve_auth + + dependencies = api_v1_mod.REST_AUTH_OPTIONAL_DEPENDENCIES + assert set(dependencies) == set(AUTH_OPTIONAL_SKILLS) + assert all(dependency is resolve_auth for dependency in dependencies.values()) + + for skill_name, handler_name in _REST_HANDLER_BY_SKILL.items(): + handler = getattr(api_v1_mod, handler_name) + identity = inspect.signature(handler).parameters["identity"] + assert identity.default is dependencies[skill_name], ( + f"{handler_name} does not use the shared auth-optional dependency for {skill_name}" + ) + + def test_every_non_optional_handler_remains_auth_required(self): + import src.routes.api_v1 as api_v1_mod + from src.core.auth_context import require_auth + + for handler_name in _REST_REQUIRED_HANDLERS: + handler = getattr(api_v1_mod, handler_name) + identity = inspect.signature(handler).parameters["identity"] + assert identity.default is require_auth, f"{handler_name} must require authentication" + + class TestResolveAuthDepBehavior: """Test the resolve_auth dependency function behavior directly.""" @@ -194,16 +236,47 @@ class TestRequireAuthDepBehavior: """Test the require_auth dependency function behavior directly.""" def test_raises_without_token(self): - """require_auth dep should raise AdCPAuthenticationError without token.""" + """require_auth dep should raise AUTH_MISSING without a credential header.""" import pytest from src.core.auth_context import AuthContext, _require_auth_dep - from src.core.exceptions import AdCPAuthenticationError + from src.core.exceptions import AdCPAuthMissingError auth_ctx = AuthContext.unauthenticated() - with pytest.raises(AdCPAuthenticationError, match="Authentication required"): + with pytest.raises(AdCPAuthMissingError, match="Authentication required") as exc_info: _require_auth_dep(auth_ctx) + assert exc_info.value.error_code == "AUTH_MISSING" + assert exc_info.value.recovery == "correctable" + + def test_rejects_malformed_presented_credentials_as_auth_invalid(self): + """A credential header that yields no token is rejected, not treated as absent.""" + import pytest + + from src.core.auth_context import AuthContext, _require_auth_dep + from src.core.exceptions import AdCPAuthInvalidError + + auth_ctx = AuthContext.unauthenticated(headers={"Authorization": "not-bearer"}) + with pytest.raises(AdCPAuthInvalidError) as exc_info: + _require_auth_dep(auth_ctx) + + assert exc_info.value.error_code == "AUTH_INVALID" + assert exc_info.value.recovery == "terminal" + + def test_empty_legacy_header_without_authorization_is_auth_missing(self): + """The spec split is defined by the standard Authorization header.""" + import pytest + + from src.core.auth_context import AuthContext, _require_auth_dep + from src.core.exceptions import AdCPAuthMissingError + + auth_ctx = AuthContext.unauthenticated(headers={"x-adcp-auth": ""}) + with pytest.raises(AdCPAuthMissingError) as exc_info: + _require_auth_dep(auth_ctx) + + assert exc_info.value.error_code == "AUTH_MISSING" + assert exc_info.value.recovery == "correctable" + def test_returns_identity_with_valid_token(self): """require_auth dep should return ResolvedIdentity with valid token.""" from unittest.mock import patch diff --git a/tests/unit/test_secret_scrub_oracle.py b/tests/unit/test_secret_scrub_oracle.py new file mode 100644 index 0000000000..90591aa031 --- /dev/null +++ b/tests/unit/test_secret_scrub_oracle.py @@ -0,0 +1,297 @@ +"""Known-bad self-tests for the shared secret-leak oracle. + +``assert_no_secret_leak`` backs ~30 leak assertions across the A2A, webhook, and boundary +suites. Without a self-test the oracle can be silently defanged — emptying ``_SECRET_TOKENS``, +or dropping a single token, leaves every one of those callers GREEN while proving nothing. + +The expectations here are stated INDEPENDENTLY of the constants they grade (see +``_EXPECTED_LEAK_FRAGMENTS``): a test parametrized over ``_SECRET_TOKENS`` would delete its own +case when a token was removed rather than reddening, which is no oracle at all. +""" + +import pytest + +from tests.helpers.secret_scrub import ( + _EXPECTED_SANITIZED_MESSAGE, + _SECRET_TOKENS, + SECRET_BEARING_MESSAGE, + assert_no_secret_leak, + assert_sanitized_wire_error, +) + +# INDEPENDENT restatement of what the oracle must detect — deliberately NOT derived from +# ``_SECRET_TOKENS``. Parametrizing over the constant under test is circular: deleting a token +# would delete its own test case instead of reddening one, so the suite would stay green while +# the oracle silently weakened. Declared here, every drop from the shared set fails +# ``test_shared_token_set_matches_the_independent_expectation`` below. +# +# Not listed: the ``prod`` database name from the connection string. It is a real secret +# fragment but unusable as a bare substring — it matches the legitimate word "product", which +# appears throughout this codebase's buyer-facing copy, so tokenizing it would fire on clean +# messages now and for as long as "product" stays in that copy. The surrounding +# ``postgresql://`` and ``db.internal`` fragments already catch any leak of that connection +# string. The ``svc`` username has no such collision (verified: no hit for "svc" anywhere in +# src/) and IS tokenized below. +_EXPECTED_LEAK_FRAGMENTS = ( + "hunter2", # password + "postgresql://", # connection-string scheme + "svc", # connection-string username + "db.internal", # internal hostname + "TOKEN=abc123", # bearer credential + "SELECT", # inline SQL + "principals", # internal table name +) + + +def test_oracle_rejects_the_secret_bearing_message_as_a_string(): + """The canonical leak payload must trip the oracle in its string form. + + Reddens if ``_SECRET_TOKENS`` is emptied — the exact defang the oracle can't otherwise see. + """ + with pytest.raises(AssertionError, match="leaked to the buyer-facing wire"): + assert_no_secret_leak(SECRET_BEARING_MESSAGE) + + +def test_oracle_rejects_the_secret_bearing_message_inside_an_envelope_dict(): + """Same payload nested in a two-layer envelope — the shape most callers actually pass. + + The oracle JSON-serializes non-str input, so a secret buried in a nested error object must + be caught just as it is in a flat string. + """ + envelope = { + "adcp_error": {"code": "SERVICE_UNAVAILABLE", "message": SECRET_BEARING_MESSAGE}, + "errors": [{"code": "SERVICE_UNAVAILABLE", "message": SECRET_BEARING_MESSAGE}], + } + with pytest.raises(AssertionError, match="leaked to the buyer-facing wire"): + assert_no_secret_leak(envelope) + + +@pytest.mark.parametrize("fragment", _EXPECTED_LEAK_FRAGMENTS) +def test_oracle_detects_every_expected_fragment_individually(fragment): + """Each fragment must trip the oracle ON ITS OWN. + + Parametrized over the INDEPENDENT list, not ``_SECRET_TOKENS``: dropping a token from the + shared set leaves this case standing and RED, which is the whole point. A blanket + "the whole message trips it" check would stay green with a single token removed, because + the remaining fragments would still fire. + """ + with pytest.raises(AssertionError, match="leaked to the buyer-facing wire"): + assert_no_secret_leak(f"prefix {fragment} suffix") + + +def test_shared_token_set_matches_the_independent_expectation(): + """The shared ``_SECRET_TOKENS`` must equal the independent list above. + + This is the tie that makes the parametrization non-circular: a token added to the shared set + without updating the expectation (or removed from it) fails here, so the two literals cannot + drift apart silently. + """ + assert set(_SECRET_TOKENS) == set(_EXPECTED_LEAK_FRAGMENTS), ( + "shared token set drifted from the independent expectation — update both deliberately" + ) + + +@pytest.mark.parametrize("fragment", _EXPECTED_LEAK_FRAGMENTS) +def test_canonical_message_actually_carries_every_fragment(fragment): + """``SECRET_BEARING_MESSAGE`` must literally contain each fragment it is supposed to model. + + The message and the token set are two independent literals; nothing else ties them. Without + this, the canonical payload could stop carrying (say) the bearer token while every caller + that injects it kept passing — proving the scrub only against the fragments that remained. + """ + assert fragment in SECRET_BEARING_MESSAGE, ( + f"{fragment!r} is expected to leak but is absent from SECRET_BEARING_MESSAGE" + ) + + +def test_oracle_passes_a_clean_blob(): + """The counter-control: a scrubbed message must NOT trip the oracle. + + Without this, an oracle that raised unconditionally would satisfy every known-bad test + above while making all ~30 callers vacuous in the opposite direction. + """ + assert_no_secret_leak("An internal error occurred while processing the request.") + assert_no_secret_leak({"adcp_error": {"code": "SERVICE_UNAVAILABLE", "message": "Request failed."}}) + + +def test_oracle_refuses_none_rather_than_passing_vacuously(): + """An absent value must fail loudly: a caller asserting on a field production stopped + populating would otherwise "pass" while proving nothing.""" + with pytest.raises(AssertionError, match="cannot prove a scrub"): + assert_no_secret_leak(None) + + +def test_expected_sanitized_message_keys_match_production_table(): + """``_EXPECTED_SANITIZED_MESSAGE``'s key set must equal ``_SANITIZED_BY_WIRE_CODE``'s. + + Key-set equality ONLY — never value equality, which would reintroduce the exact + circularity ``_EXPECTED_SANITIZED_MESSAGE`` exists to avoid (assert_sanitized_wire_error's + message check is independently pinned literal text, deliberately not read from + production; see that function's docstring). Without this, a code added to + ``_SANITIZED_BY_WIRE_CODE`` without a matching literal added here wouldn't surface until + some later scenario happened to call ``assert_sanitized_wire_error`` for that new code — + this test catches the gap immediately, the same role + ``test_shared_token_set_matches_the_independent_expectation`` plays for ``_SECRET_TOKENS``. + """ + from src.core.exceptions import _SANITIZED_BY_WIRE_CODE + + assert set(_EXPECTED_SANITIZED_MESSAGE.keys()) == set(_SANITIZED_BY_WIRE_CODE.keys()), ( + "_EXPECTED_SANITIZED_MESSAGE (tests/helpers/secret_scrub.py) drifted from " + "_SANITIZED_BY_WIRE_CODE (src/core/exceptions.py) — update both deliberately" + ) + + +# --------------------------------------------------------------------------- +# Known-bad self-tests for ``assert_sanitized_wire_error`` +# +# The sibling of the ``assert_no_secret_leak`` block above, which this file +# previously lacked. ``assert_sanitized_wire_error`` pins two EQUALITIES — the +# canonical scrubbed message and the pinned suggestion — on both envelope layers. +# Weakening either to a truthiness check (``assert error.get("message")``) leaves +# every one of its ~160 callers green while proving only that SOME text is present: +# an envelope echoing the raw, unscrubbed error would satisfy it. The cases below +# feed the oracle values that are non-empty but WRONG, so a truthiness weakening +# reddens here. +# --------------------------------------------------------------------------- + +_SANITIZED_CASE_CODE = "VALIDATION_ERROR" + + +def _canonical_sanitized_envelope(code: str = _SANITIZED_CASE_CODE) -> dict: + """A two-layer envelope that ``assert_sanitized_wire_error`` must ACCEPT.""" + from tests.helpers.pinned_schema import pinned_error_code_suggestion + + layer = { + "code": code, + "message": _EXPECTED_SANITIZED_MESSAGE[code], + "suggestion": pinned_error_code_suggestion(code), + } + return {"adcp_error": dict(layer), "errors": [dict(layer)]} + + +def test_sanitized_oracle_accepts_the_canonical_envelope(): + """Counter-control: the canonical scrub must PASS. + + Without it, an oracle that raised unconditionally would satisfy every known-bad + case below while making all of its callers vacuous in the opposite direction. + """ + assert_sanitized_wire_error(_canonical_sanitized_envelope(), _SANITIZED_CASE_CODE) + + +@pytest.mark.parametrize("layer", ["adcp_error", "errors"]) +@pytest.mark.parametrize( + ("field", "wrong_value", "expected_match"), + [ + ( + "message", + "Something went wrong while validating your request.", + "did not use the canonical VALIDATION_ERROR scrub", + ), + ( + "suggestion", + "Please try again later or contact support.", + "did not use the canonical VALIDATION_ERROR guidance", + ), + ], +) +def test_sanitized_oracle_rejects_wrong_but_non_empty_text(layer, field, wrong_value, expected_match): + """A plausible-but-wrong message/suggestion must trip the oracle, on EITHER layer. + + Reddens if the corresponding equality pin is weakened to truthiness — the exact + defang the oracle cannot otherwise see, since every value fed here is non-empty. + Parametrized across both layers because asserting only ``adcp_error`` would let a + divergence between the two layers pass every call site. + """ + envelope = _canonical_sanitized_envelope() + if layer == "adcp_error": + envelope["adcp_error"][field] = wrong_value + else: + envelope["errors"][0][field] = wrong_value + + with pytest.raises(AssertionError, match=expected_match): + assert_sanitized_wire_error(envelope, _SANITIZED_CASE_CODE) + + +def test_sanitized_oracle_rejects_a_leaked_rejected_fragment(): + """``rejected_fragments`` must actually be scanned, case-insensitively.""" + envelope = _canonical_sanitized_envelope() + envelope["adcp_error"]["details"] = {"echo": "SuperSecretBrief"} + + with pytest.raises(AssertionError, match="leaked through the sanitized"): + assert_sanitized_wire_error( + envelope, + _SANITIZED_CASE_CODE, + rejected_fragments=("supersecretbrief",), + ) + + +# --------------------------------------------------------------------------- +# Known-bad self-test for ``assert_failed_task_no_secret_leak``'s SURFACE +# +# That oracle's whole reason to exist is that a failed A2A Task has MORE than one +# client-facing carrier: the structured DataPart envelope AND every human-readable +# TextPart. Narrowing the scanned surface to the envelope alone leaves all 62 tests +# in test_a2a_error_routing.py green — none of them produces a Task whose TextPart +# carries a secret the envelope does not. The case below is exactly that Task. +# --------------------------------------------------------------------------- + + +def _failed_task_with(text: str, envelope: dict) -> object: + """A failed Task whose error artifact carries ``text`` and ``envelope``.""" + from a2a.types import Artifact, Part, Task, TaskState, TaskStatus + + from tests.utils.a2a_helpers import _dict_to_value + + return Task( + id="t-scrub", + status=TaskStatus(state=TaskState.TASK_STATE_FAILED), + artifacts=[ + Artifact( + artifact_id="e1", + name="error_result", + parts=[Part(text=text), Part(data=_dict_to_value(envelope))], + ) + ], + ) + + +_CLEAN_FAILED_ENVELOPE = { + "adcp_error": {"code": "SERVICE_UNAVAILABLE", "message": "Request failed."}, + "errors": [{"code": "SERVICE_UNAVAILABLE", "message": "Request failed."}], +} + + +def test_failed_task_oracle_scans_the_textpart_not_only_the_envelope(): + """A clean DataPart envelope with a secret-bearing TextPart must TRIP the oracle. + + Reddens if the scanned surface is narrowed to the envelope alone — the one + weakening no existing A2A error-routing test would catch, because none of them + produces a Task whose TextPart leaks something its envelope does not. + """ + from tests.utils.a2a_helpers import assert_failed_task_no_secret_leak + + task = _failed_task_with(SECRET_BEARING_MESSAGE, _CLEAN_FAILED_ENVELOPE) + + with pytest.raises(AssertionError, match="leaked to the buyer-facing wire"): + assert_failed_task_no_secret_leak(task) + + +def test_failed_task_oracle_still_scans_the_envelope(): + """The mirror case: a clean TextPart cannot excuse a leaking DataPart.""" + from tests.utils.a2a_helpers import assert_failed_task_no_secret_leak + + leaking = { + "adcp_error": {"code": "SERVICE_UNAVAILABLE", "message": SECRET_BEARING_MESSAGE}, + "errors": [{"code": "SERVICE_UNAVAILABLE", "message": SECRET_BEARING_MESSAGE}], + } + task = _failed_task_with("Request failed.", leaking) + + with pytest.raises(AssertionError, match="leaked to the buyer-facing wire"): + assert_failed_task_no_secret_leak(task) + + +def test_failed_task_oracle_passes_a_fully_clean_task(): + """Counter-control: a Task clean on BOTH carriers must not trip the oracle.""" + from tests.utils.a2a_helpers import assert_failed_task_no_secret_leak + + assert_failed_task_no_secret_leak(_failed_task_with("Request failed.", _CLEAN_FAILED_ENVELOPE)) diff --git a/tests/unit/test_sync_creatives_format_validation.py b/tests/unit/test_sync_creatives_format_validation.py index 4a6624db60..7b4e85403c 100644 --- a/tests/unit/test_sync_creatives_format_validation.py +++ b/tests/unit/test_sync_creatives_format_validation.py @@ -7,12 +7,14 @@ from unittest.mock import Mock, patch import pytest +from adcp.types import FormatId from src.core.resolved_identity import ResolvedIdentity from src.core.tools.creatives import _sync_creatives_impl from tests.factories.creative_asset import build_assets, image_spec from tests.helpers.creative_test_helpers import ( make_creative_dict, + make_creative_registry_mock, ) from tests.helpers.creative_test_helpers import ( make_creative_uow as _make_creative_uow_shared, @@ -54,8 +56,12 @@ def valid_creative_dict(self): def mock_format_spec(self): """Mock format specification from creative agent.""" format_spec = Mock() - format_spec.format_id = "display_300x250_image" + format_spec.format_id = FormatId( + agent_url="https://creative.adcontextprotocol.org", + id="display_300x250_image", + ) format_spec.agent_url = "https://creative.adcontextprotocol.org" + format_spec.output_format_ids = [] format_spec.name = "Medium Rectangle - Image" return format_spec @@ -79,9 +85,10 @@ async def mock_list_all_formats(tenant_id=None): async def mock_get_format(agent_url, format_id): return mock_format_spec - mock_registry = Mock() - mock_registry.list_all_formats = mock_list_all_formats - mock_registry.get_format = mock_get_format + mock_registry = make_creative_registry_mock( + list_all_formats=mock_list_all_formats, + get_format=mock_get_format, + ) mock_registry_getter.return_value = mock_registry # Execute @@ -112,9 +119,10 @@ async def mock_list_all_formats(tenant_id=None): async def mock_get_format(agent_url, format_id): return None # Format not found - mock_registry = Mock() - mock_registry.list_all_formats = mock_list_all_formats - mock_registry.get_format = mock_get_format + mock_registry = make_creative_registry_mock( + list_all_formats=mock_list_all_formats, + get_format=mock_get_format, + ) mock_registry_getter.return_value = mock_registry # Execute @@ -160,9 +168,10 @@ async def mock_list_all_formats(tenant_id=None): async def mock_get_format(agent_url, format_id): raise AdCPServiceUnavailableError("Connection failed: agent unreachable — Connection refused") - mock_registry = Mock() - mock_registry.list_all_formats = mock_list_all_formats - mock_registry.get_format = mock_get_format + mock_registry = make_creative_registry_mock( + list_all_formats=mock_list_all_formats, + get_format=mock_get_format, + ) mock_registry_getter.return_value = mock_registry with pytest.raises(AdCPServiceUnavailableError, match="Connection refused") as exc_info: @@ -196,9 +205,10 @@ async def mock_list_all_formats(tenant_id=None): async def mock_get_format(agent_url, format_id): return mock_format_spec - mock_registry = Mock() - mock_registry.list_all_formats = mock_list_all_formats - mock_registry.get_format = mock_get_format + mock_registry = make_creative_registry_mock( + list_all_formats=mock_list_all_formats, + get_format=mock_get_format, + ) mock_registry_getter.return_value = mock_registry # Execute @@ -243,9 +253,10 @@ async def mock_get_format(agent_url, format_id): return mock_format_spec return None - mock_registry = Mock() - mock_registry.list_all_formats = mock_list_all_formats - mock_registry.get_format = mock_get_format + mock_registry = make_creative_registry_mock( + list_all_formats=mock_list_all_formats, + get_format=mock_get_format, + ) mock_registry_getter.return_value = mock_registry # Execute @@ -294,9 +305,10 @@ async def mock_list_all_formats(tenant_id=None): async def mock_get_format(agent_url, format_id): return mock_format_spec - mock_registry = Mock() - mock_registry.list_all_formats = mock_list_all_formats - mock_registry.get_format = mock_get_format + mock_registry = make_creative_registry_mock( + list_all_formats=mock_list_all_formats, + get_format=mock_get_format, + ) mock_registry_getter.return_value = mock_registry # Execute @@ -331,8 +343,7 @@ def test_format_validation_missing_format_id(self, identity, mock_tenant): async def mock_list_all_formats(tenant_id=None): return [] - mock_registry = Mock() - mock_registry.list_all_formats = mock_list_all_formats + mock_registry = make_creative_registry_mock(list_all_formats=mock_list_all_formats) mock_registry_getter.return_value = mock_registry # Execute @@ -384,9 +395,10 @@ async def mock_get_format(agent_url, format_id): if "offline.example.com" in agent_url: raise AdCPServiceUnavailableError("Connection failed: Connection refused") - mock_registry = Mock() - mock_registry.list_all_formats = mock_list_all_formats - mock_registry.get_format = mock_get_format + mock_registry = make_creative_registry_mock( + list_all_formats=mock_list_all_formats, + get_format=mock_get_format, + ) mock_registry_getter.return_value = mock_registry # Unknown format: per-item terminal failure — the creative is wrong. diff --git a/tests/unit/test_task_management_tools.py b/tests/unit/test_task_management_tools.py index a131ca1813..c92bae654e 100644 --- a/tests/unit/test_task_management_tools.py +++ b/tests/unit/test_task_management_tools.py @@ -12,6 +12,7 @@ from src.core.database.models import WorkflowStep from src.core.exceptions import AdCPTaskNotFoundError from src.core.resolved_identity import ResolvedIdentity +from tests.helpers import assert_envelope_shape class TestListTasksTool: @@ -104,9 +105,18 @@ async def test_list_tasks_filters_by_status( assert "tasks" in result mock_workflow_repo.count_by_tenant.assert_called_once_with( + principal_id="principal_123", + status="requires_approval", + object_type=None, + object_id=None, + ) + mock_workflow_repo.list_by_tenant.assert_called_once_with( + principal_id="principal_123", status="requires_approval", object_type=None, object_id=None, + offset=0, + limit=20, ) @@ -180,6 +190,7 @@ async def test_get_task_returns_task_details( assert result["task_id"] == "step_123" assert result["status"] == "requires_approval" + mock_workflow_repo.get_by_step_id_or_raise.assert_called_once_with("step_123", principal_id="principal_123") async def test_get_task_not_found_raises_error(self, mock_uow, mock_workflow_repo, sample_tenant): """Test that get_task raises ToolError when task not found. @@ -260,7 +271,7 @@ async def test_complete_task_updates_status(self, mock_uow, mock_workflow_repo, complete_task_fn = await self._get_complete_task_fn() mock_workflow_repo.get_by_step_id_or_raise.return_value = sample_pending_step - mock_workflow_repo.update_status.return_value = sample_pending_step + mock_workflow_repo.transition_if_nonterminal.return_value = sample_pending_step identity = self._make_identity(sample_tenant) @@ -269,13 +280,37 @@ async def test_complete_task_updates_status(self, mock_uow, mock_workflow_repo, assert result["status"] == "completed" assert result["task_id"] == "step_123" - mock_workflow_repo.update_status.assert_called_once_with( + mock_workflow_repo.get_by_step_id_or_raise.assert_called_once_with("step_123", principal_id="principal_123") + mock_workflow_repo.transition_if_nonterminal.assert_called_once_with( "step_123", status="completed", completed_at=ANY, response_data={"manually_completed": True, "completed_by": "principal_123"}, ) + async def test_complete_task_conflict_when_concurrently_finalized( + self, mock_uow, mock_workflow_repo, sample_tenant, sample_pending_step + ): + """A lost transition must not be reported as success. + + ``transition_if_nonterminal`` is an atomic conditional transition that returns None when the + step was concurrently terminalized (e.g. a buyer cancel committed between the + read and the write). complete_task must raise a conflict, not return a successful + completion + audit. The MCP boundary translates the AdCPConflictError to ToolError. + """ + from fastmcp.exceptions import ToolError + + complete_task_fn = await self._get_complete_task_fn() + + mock_workflow_repo.get_by_step_id_or_raise.return_value = sample_pending_step + mock_workflow_repo.transition_if_nonterminal.return_value = None # transition refused (lost the race) + + identity = self._make_identity(sample_tenant) + + with patch("src.core.tools.task_management.WorkflowUoW", return_value=mock_uow): + with pytest.raises(ToolError, match="concurrently finalized"): + await complete_task_fn(task_id="step_123", status="completed", identity=identity) + async def test_complete_task_rejects_invalid_status(self, mock_uow, mock_workflow_repo, sample_tenant): """Test that complete_task rejects invalid status values. @@ -288,5 +323,14 @@ async def test_complete_task_rejects_invalid_status(self, mock_uow, mock_workflo identity = self._make_identity(sample_tenant) - with pytest.raises(ToolError, match="Invalid status"): + with pytest.raises(ToolError) as exc_info: await complete_task_fn(task_id="step_123", status="invalid_status", identity=identity) + + assert_envelope_shape( + exc_info.value, + "VALIDATION_ERROR", + recovery="correctable", + check_mcp_tool_error=True, + ) + assert '"field": "status"' in str(exc_info.value) + assert "invalid_status" not in str(exc_info.value) diff --git a/tests/unit/test_validation_errors.py b/tests/unit/test_validation_errors.py index 3ef466cbc6..3a5e12b9c5 100644 --- a/tests/unit/test_validation_errors.py +++ b/tests/unit/test_validation_errors.py @@ -3,7 +3,7 @@ import pytest from pydantic import BaseModel, ValidationError -from src.core.exceptions import AdCPValidationError +from src.core.exceptions import VALIDATION_ERROR_SUGGESTION, AdCPValidationError from src.core.schemas import CreateMediaBuyRequest from src.core.validation_helpers import first_validation_error_field, format_validation_error @@ -11,10 +11,8 @@ def test_first_validation_error_field_uses_bracket_notation(): """first_validation_error_field renders list indices as [i] (bracket form). - The boundary-derived field path must match the hand-rolled field= strings - raised inside the _impl layer (e.g. packages[].budget), so the wire - envelope's `field` attribute has one consistent shape regardless of where - the validation error originated. + The schema-aware sanitizer keeps declared nested fields while redacting + arbitrary mapping keys. """ class _Pkg(BaseModel): @@ -34,8 +32,8 @@ def test_first_validation_error_field_is_owned_by_exception_leaf_module(): assert first_validation_error_field.__module__ == "src.core.exceptions" -def test_create_media_buy_boundary_validation_preserves_field_suggestion(): - """Boundary request construction keeps the current field-specific hint.""" +def test_create_media_buy_boundary_validation_uses_canonical_suggestion(): + """Boundary diagnostics keep the field while suggestion follows the pin.""" from src.core.tools.media_buy_create import _build_create_media_buy_request with pytest.raises(AdCPValidationError) as exc_info: @@ -55,7 +53,7 @@ def test_create_media_buy_boundary_validation_preserves_field_suggestion(): error = exc_info.value assert error.field == "idempotency_key" - assert error.suggestion == ("Provide the required 'idempotency_key' field and resend the request.") + assert error.suggestion == VALIDATION_ERROR_SUGGESTION def test_brand_target_audience_must_be_string(): @@ -117,9 +115,10 @@ def test_validation_error_formatting(): # Check that we got a helpful error message assert "Invalid test request:" in error_msg - assert "brand_manifest.BrandManifest.target_audience" in error_msg - assert "Expected string, got object" in error_msg - assert "AdCP spec requires this field to be a simple string" in error_msg + # BrandManifest is a removed legacy union branch, so it is not trusted + # schema metadata in the current model graph. + assert "brand_manifest.nested_field.nested_field" in error_msg + assert "Expected a string value" in error_msg assert "https://adcontextprotocol.org/schemas/v1/" in error_msg @@ -138,7 +137,7 @@ def test_validation_error_formatting_missing_field(): def test_validation_error_formatting_extra_field(): - """Test formatting for extra forbidden fields shows the actual value.""" + """Extra-field diagnostics identify the field without echoing its value.""" try: raise ValidationError.from_exception_data( "CreateMediaBuyRequest", @@ -154,14 +153,14 @@ def test_validation_error_formatting_extra_field(): except ValidationError as e: error_msg = format_validation_error(e) - assert "unknown_field: Extra field not allowed by AdCP spec" in error_msg - # Now we show the actual value for debugging - assert "some_value" in error_msg - assert "Received value:" in error_msg + assert "unrecognized_field: Extra field is not allowed by the AdCP request schema" in error_msg + assert "unknown_field" not in error_msg + assert "some_value" not in error_msg + assert "Received value:" not in error_msg def test_validation_error_formatting_extra_field_with_dict(): - """Test formatting for extra forbidden fields with dict values shows full structure.""" + """Nested extra-field diagnostics never echo the rejected structure.""" # This tests the scenario from the bug where format_ids had an agent_url key # that was incorrectly placed, and Pydantic truncated it try: @@ -179,9 +178,8 @@ def test_validation_error_formatting_extra_field_with_dict(): except ValidationError as e: error_msg = format_validation_error(e) - # Error message should show the full value, not truncated - assert "format_ids.agent_url: Extra field not allowed by AdCP spec" in error_msg - assert "Received value:" in error_msg - # The full URL should be visible, not truncated like "ht...id" - assert "https://creative.adcontextprotocol.org/" in error_msg - assert "display_300x250" in error_msg + assert "format_ids.unrecognized_field: Extra field is not allowed by the AdCP request schema" in error_msg + assert "agent_url" not in error_msg + assert "Received value:" not in error_msg + assert "https://creative.adcontextprotocol.org/" not in error_msg + assert "display_300x250" not in error_msg diff --git a/tests/unit/test_webhook_delivery.py b/tests/unit/test_webhook_delivery.py index 071b121815..1f3cdbb2b8 100644 --- a/tests/unit/test_webhook_delivery.py +++ b/tests/unit/test_webhook_delivery.py @@ -2,6 +2,7 @@ from unittest.mock import Mock, call, patch +import pytest import requests from src.core.webhook_delivery import WebhookDelivery, deliver_webhook_with_retry @@ -11,6 +12,14 @@ class TestWebhookDelivery: """Test cases for webhook delivery with exponential backoff retry.""" + @pytest.fixture(autouse=True) + def _resolve_example_com(self, monkeypatch): + """Keep delivery unit tests independent of external DNS availability.""" + monkeypatch.setattr( + "src.core.security.url_validator.socket.gethostbyname", + lambda hostname: "93.184.216.34", + ) + def test_successful_delivery_first_attempt(self, mock_sleep): """Test successful delivery on first attempt (200 OK).""" delivery = WebhookDelivery( diff --git a/tests/unit/test_webhook_security.py b/tests/unit/test_webhook_security.py index 4d32a572a7..9e9a46e391 100644 --- a/tests/unit/test_webhook_security.py +++ b/tests/unit/test_webhook_security.py @@ -4,8 +4,11 @@ import hmac import json import time +from types import SimpleNamespace +from unittest.mock import ANY, MagicMock, patch import pytest +from a2a.types import TaskState, TaskStatus, TaskStatusUpdateEvent from adcp.types import TaskType from src.core.webhook_authenticator import WebhookAuthenticator @@ -16,6 +19,15 @@ ) +@pytest.fixture +def public_dns(monkeypatch): + """Resolve the documentation host without relying on external DNS.""" + monkeypatch.setattr( + "src.core.security.url_validator.socket.gethostbyname", + lambda hostname: "93.184.216.34", + ) + + class TestValidateWebhookTaskType: """Coercion of untrusted action labels to SDK-accepted TaskType values.""" @@ -47,13 +59,13 @@ def test_fallback_must_be_valid_caller_choice(self): class TestWebhookURLValidator: """Test SSRF protection in webhook URL validation.""" - def test_valid_public_https_url(self): + def test_valid_public_https_url(self, public_dns): """Valid public HTTPS URLs should pass.""" is_valid, error = WebhookURLValidator.validate_webhook_url("https://example.com/webhook") assert is_valid assert error == "" - def test_valid_public_http_url(self): + def test_valid_public_http_url(self, public_dns): """Valid public HTTP URLs should pass (for testing).""" is_valid, error = WebhookURLValidator.validate_webhook_url("http://example.com/webhook") assert is_valid @@ -127,6 +139,84 @@ def test_invalid_url_format(self): assert not is_valid assert error != "" + def test_blocks_embedded_url_credentials(self, public_dns): + """Authentication belongs in the config, never in a loggable URL.""" + is_valid, error = WebhookURLValidator.validate_webhook_url("https://svc:hunter2@example.com/webhook") + assert not is_valid + assert "credentials" in error.lower() + + def test_protocol_test_host_override_is_exact_and_development_only(self, monkeypatch): + """The Docker callback seam cannot admit arbitrary private destinations.""" + monkeypatch.setenv("ENVIRONMENT", "development") + monkeypatch.setenv("ADCP_WEBHOOK_TEST_HOST", "tests") + monkeypatch.setattr( + "src.core.security.url_validator.socket.gethostbyname", + lambda hostname: "172.18.0.5", + ) + + assert WebhookURLValidator.validate_protocol_webhook_url("http://tests:8080/webhook") == (True, "") + is_valid, _error = WebhookURLValidator.validate_protocol_webhook_url("http://internal-service:8080/webhook") + assert not is_valid + malformed_is_valid, _error = WebhookURLValidator.validate_protocol_webhook_url( + "http://tests:not-a-port/webhook" + ) + assert not malformed_is_valid + + def test_registration_and_protocol_gates_agree_on_the_dev_test_host(self, monkeypatch): + """Both gates must admit the SAME development-only callback host. + + The E2E capture server is registered through the registration gate and + delivered to through the protocol gate. When only the protocol gate honored + the seam, every E2E webhook flow failed at REGISTRATION (VALIDATION_ERROR on + reporting_webhook.url / push_notification_config.url) and no delivery was + ever attempted. Covers both configured pairings: "tests" in-network + (docker-compose.e2e.yml), "host.docker.internal" standalone (e2e/conftest.py). + """ + monkeypatch.setenv("ENVIRONMENT", "development") + monkeypatch.setenv("ADCP_TESTING", "true") + for host in ("tests", "host.docker.internal"): + monkeypatch.setenv("ADCP_WEBHOOK_TEST_HOST", host) + url = f"http://{host}:9999/webhook" + assert WebhookURLValidator.validate_webhook_url_registration(url) == (True, ""), ( + f"registration gate rejected the configured dev callback host {host!r}" + ) + assert WebhookURLValidator.validate_protocol_webhook_url(url) == (True, ""), ( + f"protocol gate rejected the configured dev callback host {host!r}" + ) + + def test_registration_seam_is_exact_and_never_widens_production(self, monkeypatch): + """The registration seam admits exactly one host, in development only.""" + monkeypatch.setenv("ADCP_TESTING", "true") + monkeypatch.setenv("ADCP_WEBHOOK_TEST_HOST", "host.docker.internal") + + monkeypatch.setenv("ENVIRONMENT", "development") + # A different private host is NOT admitted just because a seam is configured. + assert not WebhookURLValidator.validate_webhook_url_registration("http://10.0.0.5/webhook")[0] + # Nor is the seam host when the URL smuggles credentials. + assert not WebhookURLValidator.validate_webhook_url_registration( + "http://user:pw@host.docker.internal:9999/webhook" + )[0] + + # Production ignores the seam even with the env var still set. + monkeypatch.setenv("ENVIRONMENT", "production") + assert not WebhookURLValidator.validate_webhook_url_registration("http://host.docker.internal:9999/webhook")[0] + + def test_protocol_callback_requires_https_outside_development(self, monkeypatch, public_dns): + """Production never sends payloads or legacy credentials over plaintext HTTP.""" + monkeypatch.setenv("ENVIRONMENT", "production") + + is_valid, error = WebhookURLValidator.validate_protocol_webhook_url("http://example.com/webhook") + + assert not is_valid + assert "https" in error.lower() + assert WebhookURLValidator.validate_protocol_webhook_url("https://example.com/webhook") == (True, "") + + def test_protocol_public_http_is_allowed_in_development(self, monkeypatch, public_dns): + """Development may use public HTTP independently of the private-host E2E seam.""" + monkeypatch.setenv("ENVIRONMENT", "development") + + assert WebhookURLValidator.validate_protocol_webhook_url("http://example.com/webhook") == (True, "") + def test_validate_for_testing_allows_localhost(self): """Testing mode should allow localhost when enabled.""" is_valid, error = WebhookURLValidator.validate_for_testing( @@ -328,3 +418,82 @@ def test_tampered_payload(self): tampered_str, headers["X-Webhook-Signature"], headers["X-Webhook-Timestamp"], secret ) assert not is_valid + + +class TestProtocolWebhookDeliverySecurity: + """The actual protocol sender enforces URL safety at the connection seam.""" + + @staticmethod + def _event() -> TaskStatusUpdateEvent: + return TaskStatusUpdateEvent( + task_id="task_security", + context_id="ctx_security", + status=TaskStatus(state=TaskState.TASK_STATE_SUBMITTED), + ) + + @pytest.mark.asyncio + async def test_private_destination_never_reaches_http_client(self): + from src.services.protocol_webhook_service import ProtocolWebhookService + + service = ProtocolWebhookService() + service._session.post = MagicMock() + config = SimpleNamespace( + url="http://127.0.0.1:8999/internal", + authentication_type=None, + authentication_token=None, + ) + + sent = await service.send_notification(config, self._event(), {"task_type": "create_media_buy"}) + + assert sent is False + service._session.post.assert_not_called() + + @pytest.mark.asyncio + async def test_delivery_disables_redirect_following(self): + from src.services.protocol_webhook_service import ProtocolWebhookService + + service = ProtocolWebhookService() + response = MagicMock(status_code=204) + service._session.post = MagicMock(return_value=response) + config = SimpleNamespace( + url="https://buyer.example/webhook", + authentication_type=None, + authentication_token=None, + ) + + with patch.object(WebhookURLValidator, "validate_protocol_webhook_url", return_value=(True, "")): + sent = await service.send_notification(config, self._event(), {"task_type": "create_media_buy"}) + + assert sent is True + service._session.post.assert_called_once_with( + "https://buyer.example/webhook", + json=ANY, + headers=ANY, + timeout=10.0, + allow_redirects=False, + ) + + @pytest.mark.asyncio + async def test_redirect_response_is_not_reported_as_success(self): + from src.services.protocol_webhook_service import ProtocolWebhookService + + service = ProtocolWebhookService() + response = MagicMock(status_code=302) + service._session.post = MagicMock(return_value=response) + config = SimpleNamespace( + url="https://buyer.example/webhook", + authentication_type=None, + authentication_token=None, + ) + + with patch.object(WebhookURLValidator, "validate_protocol_webhook_url", return_value=(True, "")): + sent = await service.send_notification(config, self._event(), {"task_type": "create_media_buy"}) + + assert sent is False + service._session.post.assert_called_once_with( + "https://buyer.example/webhook", + json=ANY, + headers=ANY, + timeout=10.0, + allow_redirects=False, + ) diff --git a/tests/unit/test_workflow_cancellable_statuses.py b/tests/unit/test_workflow_cancellable_statuses.py new file mode 100644 index 0000000000..095f662b22 --- /dev/null +++ b/tests/unit/test_workflow_cancellable_statuses.py @@ -0,0 +1,62 @@ +"""Exact-membership pins for the workflow-step cancellation taxonomy. + +``CANCELLABLE_STEP_STATUSES`` is the single source of truth for which statuses a buyer +cancel (A2A ``tasks/cancel`` → ``WorkflowRepository.cancel_if_cancellable``) is still safe +from. These tests pin the *exact* partition — every included status and every excluded +status — as a pure-value contract, independent of any DB-backed behavior test. A silent +addition (e.g. re-adding ``in_progress`` or ``approved``, which would let a cancel strand a +real ad-server order behind a canceled task) fails here immediately. +""" + +from src.core.database.repositories.workflow import ( + APPROVABLE_STEP_STATUSES, + CANCELLABLE_STEP_STATUSES, + TERMINAL_STEP_STATUSES, +) + +# Hardcoded expectations (NOT derived from the production constants) so a drift in the +# source set is caught, not mirrored. ``approval`` is the legacy adapter-emitted alias of +# ``requires_approval`` (a pre-side-effect awaiting-decision state) — cancellable for the same +# reason, and carried here until the alias is normalized away. +_CANCELLABLE = {"pending", "requires_approval", "pending_approval", "approval"} +# Non-terminal statuses that are nonetheless NOT cancellable because irreversible external +# work has committed (``approved``) or is underway (``in_progress``). +_NONCANCELLABLE_NONTERMINAL = {"in_progress", "approved"} +_TERMINAL = {"completed", "rejected", "failed", "canceled"} +# Statuses an approve/reject compare-and-set may fire FROM (still awaiting a decision). MUST +# exclude ``approved`` so a second approver can't win approved→approved and duplicate the +# irreversible adapter work, and so a reject can't run approved→rejected on a live order. +# ``approval`` is the legacy adapter-emitted alias of ``requires_approval`` (base_workflow / +# GAM / Broadstreet) — it MUST be approvable or those live human workflows can't be actioned. +_APPROVABLE = {"requires_approval", "pending_approval", "approval"} + + +def test_cancellable_set_is_exactly_the_pre_sideeffect_statuses(): + assert CANCELLABLE_STEP_STATUSES == _CANCELLABLE + + +def test_terminal_set_is_exact(): + assert TERMINAL_STEP_STATUSES == _TERMINAL + + +def test_every_noncancellable_status_is_excluded(): + # in_progress + approved (work underway/committed) and every terminal status must be + # absent from the cancellable set. + for status in _NONCANCELLABLE_NONTERMINAL | _TERMINAL: + assert status not in CANCELLABLE_STEP_STATUSES, f"{status!r} must NOT be cancellable" + + +def test_cancellable_and_terminal_are_disjoint(): + assert CANCELLABLE_STEP_STATUSES.isdisjoint(TERMINAL_STEP_STATUSES) + + +def test_approvable_set_is_exactly_the_pending_decision_statuses(): + assert APPROVABLE_STEP_STATUSES == _APPROVABLE + + +def test_approved_is_not_approvable(): + # The crux of the double-approve fix: an already-approved step is NOT a valid source for + # another approve/reject compare-and-set. + assert "approved" not in APPROVABLE_STEP_STATUSES + for status in _TERMINAL | {"in_progress", "pending"}: + assert status not in APPROVABLE_STEP_STATUSES, f"{status!r} must not be approvable" diff --git a/tests/utils/a2a_helpers.py b/tests/utils/a2a_helpers.py index 9aba74fb79..a879244a1a 100644 --- a/tests/utils/a2a_helpers.py +++ b/tests/utils/a2a_helpers.py @@ -7,12 +7,17 @@ import json import uuid -from typing import Any +from typing import TYPE_CHECKING, Any from unittest.mock import ANY -from a2a.types import Artifact, Message, Part, Role +from a2a.types import Artifact, Message, Part, Role, SendMessageRequest, Task, TaskState from google.protobuf import json_format, struct_pb2 +from tests.helpers.envelope_assertions import assert_envelope_shape + +if TYPE_CHECKING: + from src.core.resolved_identity import ResolvedIdentity + def assert_delivery_forwarded_account(mock_delivery, expected_account) -> None: """Assert ``core_get_media_buy_delivery_tool`` was called once forwarding ``expected_account``. @@ -57,6 +62,122 @@ def extract_data_from_artifact(artifact: Artifact) -> dict[str, Any]: return {} +def _locate_failed_task_artifact(task: Task, artifact_name: str) -> Artifact: + """THE single locator of a failed Task's error artifact — presence + NAME. + + Split from the strict reader so the reader and the leak oracle share one definition of + "which artifact carries the failure"; a change to how it is located (position, naming) is + then a single edit rather than two that can drift. + """ + assert task.artifacts, "failed Task must carry the error envelope artifact" + artifact = task.artifacts[0] + assert artifact.name == artifact_name, f"expected {artifact_name!r} artifact, got {artifact.name!r}" + return artifact + + +def _artifact_texts(artifact: Artifact) -> list[str]: + """The human-readable TextPart strings of ``artifact``. + + One definition of "which parts are the readable text", shared by the strict reader (which + counts them) and the leak oracle (which scans them) — the same reason the locator above is + shared. If A2A ever changes how text is carried, this is the single edit. + """ + return [p.text for p in artifact.parts if p.HasField("text")] + + +def _read_failed_task_artifact(task: Task, artifact_name: str) -> dict[str, Any]: + """THE single strict reader of a failed Task's error artifact. + + Pins the artifact NAME (via the shared locator), exactly one authoritative DataPart, AND + exactly one human-readable TextPart (the A2A error binding: a FAILED artifact carries the + error message as its TextPart, never a DataPart alone), then decodes the + DataPart. Both public entries (``extract_processing_error_envelope`` and + ``assert_failed_task_envelope``) route through here so the shape contract has + exactly one home. + """ + artifact = _locate_failed_task_artifact(task, artifact_name) + data_parts = [p for p in artifact.parts if p.HasField("data")] + text_parts = _artifact_texts(artifact) + assert len(data_parts) == 1, f"error artifact must carry exactly one authoritative DataPart, got {len(data_parts)}" + assert len(text_parts) == 1, ( + f"error artifact must carry a human-readable TextPart (A2A error binding), got {len(text_parts)}" + ) + return extract_data_from_artifact(artifact) + + +def extract_processing_error_envelope(task: Task) -> dict[str, Any]: + """Read the two-layer AdCP envelope from a failed Task's ``processing_error`` artifact. + + ``on_message_send``'s outer error handler attaches the envelope built by + ``AdCPRequestHandler._build_error_envelope`` to the failed Task as a + ``processing_error`` artifact. Thin wrapper over the shared strict reader. + """ + return _read_failed_task_artifact(task, "processing_error") + + +def assert_failed_task_envelope( + task: Task, *, code: str, recovery: str, artifact_name: str = "error_result" +) -> dict[str, Any]: + """Assert a synchronously-returned failed A2A Task carries the two-layer AdCP envelope with the + given wire ``code`` and ``recovery``. + + Pins the FAILED state and the A2A ARTIFACT framing (name, single DataPart, single TextPart) + via the shared strict reader, then delegates the ENVELOPE assertion to the canonical + ``assert_envelope_shape`` — so both layers (``adcp_error`` and ``errors[0]``) are required to + agree here exactly as they are at every other transport boundary. Asserting only + ``adcp_error`` would let a divergence between the two layers pass every call site. + ``recovery`` is REQUIRED: silent drift between a typed exception's recovery and the wire is + exactly the regression this helper exists to catch. The artifact NAME differs by path: a + per-skill failure emits ``error_result`` (the default), while a top-level rejection (e.g. the + multi-skill guard) emits ``processing_error`` — pass ``artifact_name`` for the latter. + Returns the decoded envelope for any test-specific follow-up assertions. + """ + assert isinstance(task, Task), f"expected a failed Task, got {type(task).__name__}" + assert task.status.state == TaskState.TASK_STATE_FAILED, f"expected FAILED task, got {task.status.state!r}" + envelope = _read_failed_task_artifact(task, artifact_name) + assert_envelope_shape(envelope, code, recovery=recovery) + return envelope + + +def assert_failed_task_no_secret_leak(task: Task, *, artifact_name: str = "error_result") -> None: + """Assert NO secret fragment leaks on ANY client-facing carrier of a failed Task. + + One home for "which bytes of a failed Task are the buyer-facing surface": the structured + DataPart envelope AND every human-readable TextPart. If a failed artifact ever grows a third + client-visible carrier (a new part type, a status message, metadata), it is added here once + and every scrub test tightens in lockstep — rather than each test hand-rolling the surface + definition and silently under-covering the new carrier when one copy is missed. + """ + from tests.helpers.secret_scrub import assert_no_secret_leak + + artifact = _locate_failed_task_artifact(task, artifact_name) + envelope = extract_data_from_artifact(artifact) + text_parts = _artifact_texts(artifact) + client_facing = json.dumps(envelope) + " " + " ".join(text_parts) + assert_no_secret_leak(client_facing, context=f"failed Task {artifact_name!r} artifact") + + +def make_test_a2a_identity() -> "ResolvedIdentity": + """Standard factory-built ResolvedIdentity for A2A handler unit tests. + + Not a ``unittest.mock`` object — a real identity from + ``PrincipalFactory.make_identity`` with canned A2A test values. + """ + from tests.factories import PrincipalFactory + + return PrincipalFactory.make_identity( + principal_id="test-principal", + tenant_id="test-tenant", + tenant={"tenant_id": "test-tenant"}, + protocol="a2a", + ) + + +def make_nl_send_message_request(text: str) -> SendMessageRequest: + """Build a minimal A2A SendMessageRequest carrying NL text (no skills).""" + return SendMessageRequest(message=create_a2a_text_message(text)) + + def _dict_to_value(d: dict) -> struct_pb2.Value: """Convert a Python dict to a protobuf Value for use in Part.data.""" val = struct_pb2.Value()