adcp 1.5.0__tar.gz → 1.6.1__tar.gz

{adcp-1.5.0/src/adcp.egg-info → adcp-1.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 1.5.0
+Version: 1.6.1
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0
@@ -461,6 +461,50 @@ auth = index.get_agent_authorizations("https://agent-x.com")
 premium = index.find_agents_by_property_tags(["premium", "ctv"])
 ```
 
+## Publisher Authorization Validation
+
+Verify sales agents are authorized to sell publisher properties via adagents.json:
+
+```python
+from adcp import (
+    fetch_adagents,
+    verify_agent_authorization,
+    verify_agent_for_property,
+)
+
+# Fetch and parse adagents.json from publisher
+adagents_data = await fetch_adagents("publisher.com")
+
+# Verify agent authorization for a property
+is_authorized = verify_agent_authorization(
+    adagents_data=adagents_data,
+    agent_url="https://sales-agent.example.com",
+    property_type="website",
+    property_identifiers=[{"type": "domain", "value": "publisher.com"}]
+)
+
+# Or use convenience wrapper (fetch + verify in one call)
+is_authorized = await verify_agent_for_property(
+    publisher_domain="publisher.com",
+    agent_url="https://sales-agent.example.com",
+    property_identifiers=[{"type": "domain", "value": "publisher.com"}],
+    property_type="website"
+)
+```
+
+**Domain Matching Rules:**
+- Exact match: `example.com` matches `example.com`
+- Common subdomains: `www.example.com` matches `example.com`
+- Wildcards: `api.example.com` matches `*.example.com`
+- Protocol-agnostic: `http://agent.com` matches `https://agent.com`
+
+**Use Cases:**
+- Sales agents verify authorization before accepting media buys
+- Publishers test their adagents.json files
+- Developer tools build authorization validators
+
+See `examples/adagents_validation.py` for complete examples.
+
 ## CLI Tool
 
 The `adcp` command-line tool provides easy interaction with AdCP agents without writing code.

{adcp-1.5.0 → adcp-1.6.1}/README.md

@@ -424,6 +424,50 @@ auth = index.get_agent_authorizations("https://agent-x.com")
 premium = index.find_agents_by_property_tags(["premium", "ctv"])
 ```
 
+## Publisher Authorization Validation
+
+Verify sales agents are authorized to sell publisher properties via adagents.json:
+
+```python
+from adcp import (
+    fetch_adagents,
+    verify_agent_authorization,
+    verify_agent_for_property,
+)
+
+# Fetch and parse adagents.json from publisher
+adagents_data = await fetch_adagents("publisher.com")
+
+# Verify agent authorization for a property
+is_authorized = verify_agent_authorization(
+    adagents_data=adagents_data,
+    agent_url="https://sales-agent.example.com",
+    property_type="website",
+    property_identifiers=[{"type": "domain", "value": "publisher.com"}]
+)
+
+# Or use convenience wrapper (fetch + verify in one call)
+is_authorized = await verify_agent_for_property(
+    publisher_domain="publisher.com",
+    agent_url="https://sales-agent.example.com",
+    property_identifiers=[{"type": "domain", "value": "publisher.com"}],
+    property_type="website"
+)
+```
+
+**Domain Matching Rules:**
+- Exact match: `example.com` matches `example.com`
+- Common subdomains: `www.example.com` matches `example.com`
+- Wildcards: `api.example.com` matches `*.example.com`
+- Protocol-agnostic: `http://agent.com` matches `https://agent.com`
+
+**Use Cases:**
+- Sales agents verify authorization before accepting media buys
+- Publishers test their adagents.json files
+- Developer tools build authorization validators
+
+See `examples/adagents_validation.py` for complete examples.
+
 ## CLI Tool
 
 The `adcp` command-line tool provides easy interaction with AdCP agents without writing code.

{adcp-1.5.0 → adcp-1.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "adcp"
-version = "1.5.0"
+version = "1.6.1"
 description = "Official Python client for the Ad Context Protocol (AdCP)"
 authors = [
     {name = "AdCP Community", email = "maintainers@adcontextprotocol.org"}

{adcp-1.5.0 → adcp-1.6.1}/src/adcp/__init__.py

@@ -7,8 +7,21 @@ Official Python client for the Ad Context Protocol (AdCP).
 Supports both A2A and MCP protocols with full type safety.
 """
 
+from adcp.adagents import (
+    domain_matches,
+    fetch_adagents,
+    get_all_properties,
+    get_all_tags,
+    get_properties_by_agent,
+    identifiers_match,
+    verify_agent_authorization,
+    verify_agent_for_property,
+)
 from adcp.client import ADCPClient, ADCPMultiAgentClient
 from adcp.exceptions import (
+    AdagentsNotFoundError,
+    AdagentsTimeoutError,
+    AdagentsValidationError,
     ADCPAuthenticationError,
     ADCPConnectionError,
     ADCPError,
@@ -150,7 +163,7 @@ from adcp.types.generated import (
     TaskStatus as GeneratedTaskStatus,
 )
 
-__version__ = "1.5.0"
+__version__ = "1.6.1"
 
 __all__ = [
     # Client classes
@@ -162,6 +175,15 @@ __all__ = [
     "TaskResult",
     "TaskStatus",
     "WebhookMetadata",
+    # Adagents validation
+    "fetch_adagents",
+    "verify_agent_authorization",
+    "verify_agent_for_property",
+    "domain_matches",
+    "identifiers_match",
+    "get_all_properties",
+    "get_all_tags",
+    "get_properties_by_agent",
     # Test helpers
     "test_agent",
     "test_agent_a2a",
@@ -185,6 +207,9 @@ __all__ = [
     "ADCPToolNotFoundError",
     "ADCPWebhookError",
     "ADCPWebhookSignatureError",
+    "AdagentsValidationError",
+    "AdagentsNotFoundError",
+    "AdagentsTimeoutError",
     # Request/Response types
     "ActivateSignalRequest",
     "ActivateSignalResponse",

adcp-1.6.1/src/adcp/adagents.py

@@ -0,0 +1,521 @@
+from __future__ import annotations
+
+"""
+Utilities for fetching, parsing, and validating adagents.json files per the AdCP specification.
+
+Publishers declare authorized sales agents via adagents.json files hosted at
+https://{publisher_domain}/.well-known/adagents.json. This module provides utilities
+for sales agents to verify they are authorized for specific properties.
+"""
+
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from adcp.exceptions import AdagentsNotFoundError, AdagentsTimeoutError, AdagentsValidationError
+
+
+def _normalize_domain(domain: str) -> str:
+    """Normalize domain for comparison - strip, lowercase, remove trailing dots/slashes.
+
+    Args:
+        domain: Domain to normalize
+
+    Returns:
+        Normalized domain string
+
+    Raises:
+        AdagentsValidationError: If domain contains invalid patterns
+    """
+    domain = domain.strip().lower()
+    # Remove both trailing slashes and dots iteratively
+    while domain.endswith("/") or domain.endswith("."):
+        domain = domain.rstrip("/").rstrip(".")
+
+    # Check for invalid patterns
+    if not domain or ".." in domain:
+        raise AdagentsValidationError(f"Invalid domain format: {domain!r}")
+
+    return domain
+
+
+def _validate_publisher_domain(domain: str) -> str:
+    """Validate and sanitize publisher domain for security.
+
+    Args:
+        domain: Publisher domain to validate
+
+    Returns:
+        Validated and normalized domain
+
+    Raises:
+        AdagentsValidationError: If domain is invalid or contains suspicious characters
+    """
+    # Check for suspicious characters BEFORE stripping (to catch injection attempts)
+    suspicious_chars = ["\\", "@", "\n", "\r", "\t"]
+    for char in suspicious_chars:
+        if char in domain:
+            raise AdagentsValidationError(
+                f"Invalid character in publisher domain: {char!r}"
+            )
+
+    domain = domain.strip()
+
+    # Check basic constraints
+    if not domain:
+        raise AdagentsValidationError("Publisher domain cannot be empty")
+    if len(domain) > 253:  # DNS maximum length
+        raise AdagentsValidationError(f"Publisher domain too long: {len(domain)} chars (max 253)")
+
+    # Check for spaces after stripping leading/trailing whitespace
+    if " " in domain:
+        raise AdagentsValidationError(
+            "Invalid character in publisher domain: ' '"
+        )
+
+    # Remove protocol if present (common user error) - do this BEFORE checking for slashes
+    if "://" in domain:
+        domain = domain.split("://", 1)[1]
+
+    # Remove path if present (should only be domain) - do this BEFORE checking for slashes
+    if "/" in domain:
+        domain = domain.split("/", 1)[0]
+
+    # Normalize
+    domain = _normalize_domain(domain)
+
+    # Final validation - must look like a domain
+    if "." not in domain:
+        raise AdagentsValidationError(
+            f"Publisher domain must contain at least one dot: {domain!r}"
+        )
+
+    return domain
+
+
+def normalize_url(url: str) -> str:
+    """Normalize URL by removing protocol and trailing slash.
+
+    Args:
+        url: URL to normalize
+
+    Returns:
+        Normalized URL (domain/path without protocol or trailing slash)
+    """
+    parsed = urlparse(url)
+    normalized = parsed.netloc + parsed.path
+    return normalized.rstrip("/")
+
+
+def domain_matches(property_domain: str, agent_domain_pattern: str) -> bool:
+    """Check if domains match per AdCP rules.
+
+    Rules:
+    - Exact match always succeeds
+    - 'example.com' matches www.example.com, m.example.com (common subdomains)
+    - 'subdomain.example.com' matches that specific subdomain only
+    - '*.example.com' matches all subdomains
+
+    Args:
+        property_domain: Domain from property
+        agent_domain_pattern: Domain pattern from adagents.json
+
+    Returns:
+        True if domains match per AdCP rules
+    """
+    # Normalize both domains for comparison
+    try:
+        property_domain = _normalize_domain(property_domain)
+        agent_domain_pattern = _normalize_domain(agent_domain_pattern)
+    except AdagentsValidationError:
+        # Invalid domain format - no match
+        return False
+
+    # Exact match
+    if property_domain == agent_domain_pattern:
+        return True
+
+    # Wildcard pattern (*.example.com)
+    if agent_domain_pattern.startswith("*."):
+        base_domain = agent_domain_pattern[2:]
+        return property_domain.endswith(f".{base_domain}")
+
+    # Bare domain matches common subdomains (www, m)
+    # If agent pattern is a bare domain (no subdomain), match www/m subdomains
+    if "." in agent_domain_pattern and not agent_domain_pattern.startswith("www."):
+        # Check if this looks like a bare domain (e.g., example.com)
+        parts = agent_domain_pattern.split(".")
+        if len(parts) == 2:  # Looks like bare domain
+            common_subdomains = ["www", "m"]
+            for subdomain in common_subdomains:
+                if property_domain == f"{subdomain}.{agent_domain_pattern}":
+                    return True
+
+    return False
+
+
+def identifiers_match(
+    property_identifiers: list[dict[str, str]],
+    agent_identifiers: list[dict[str, str]],
+) -> bool:
+    """Check if any property identifier matches agent's authorized identifiers.
+
+    Args:
+        property_identifiers: Identifiers from property
+            (e.g., [{"type": "domain", "value": "cnn.com"}])
+        agent_identifiers: Identifiers from adagents.json
+
+    Returns:
+        True if any identifier matches
+
+    Notes:
+        - Domain identifiers use AdCP domain matching rules
+        - Other identifiers (bundle_id, roku_store_id, etc.) require exact match
+    """
+    for prop_id in property_identifiers:
+        prop_type = prop_id.get("type", "")
+        prop_value = prop_id.get("value", "")
+
+        for agent_id in agent_identifiers:
+            agent_type = agent_id.get("type", "")
+            agent_value = agent_id.get("value", "")
+
+            # Type must match
+            if prop_type != agent_type:
+                continue
+
+            # Domain identifiers use special matching rules
+            if prop_type == "domain":
+                if domain_matches(prop_value, agent_value):
+                    return True
+            else:
+                # Other identifier types require exact match
+                if prop_value == agent_value:
+                    return True
+
+    return False
+
+
+def verify_agent_authorization(
+    adagents_data: dict[str, Any],
+    agent_url: str,
+    property_type: str | None = None,
+    property_identifiers: list[dict[str, str]] | None = None,
+) -> bool:
+    """Check if agent is authorized for a property.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+        agent_url: URL of the sales agent to verify
+        property_type: Type of property (website, app, etc.) - optional
+        property_identifiers: List of identifiers to match - optional
+
+    Returns:
+        True if agent is authorized, False otherwise
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+
+    Notes:
+        - If property_type/identifiers are None, checks if agent is authorized
+          for ANY property on this domain
+        - Implements AdCP domain matching rules
+        - Agent URLs are matched ignoring protocol and trailing slash
+    """
+    # Validate structure
+    if not isinstance(adagents_data, dict):
+        raise AdagentsValidationError("adagents_data must be a dictionary")
+
+    authorized_agents = adagents_data.get("authorized_agents")
+    if not isinstance(authorized_agents, list):
+        raise AdagentsValidationError("adagents.json must have 'authorized_agents' array")
+
+    # Normalize the agent URL for comparison
+    normalized_agent_url = normalize_url(agent_url)
+
+    # Check each authorized agent
+    for agent in authorized_agents:
+        if not isinstance(agent, dict):
+            continue
+
+        agent_url_from_json = agent.get("url", "")
+        if not agent_url_from_json:
+            continue
+
+        # Match agent URL (protocol-agnostic)
+        if normalize_url(agent_url_from_json) != normalized_agent_url:
+            continue
+
+        # Found matching agent - now check properties
+        properties = agent.get("properties")
+
+        # If properties field is missing or empty, agent is authorized for all properties
+        if properties is None or (isinstance(properties, list) and len(properties) == 0):
+            return True
+
+        # If no property filters specified, we found the agent - authorized
+        if property_type is None and property_identifiers is None:
+            return True
+
+        # Check specific property authorization
+        if isinstance(properties, list):
+            for prop in properties:
+                if not isinstance(prop, dict):
+                    continue
+
+                # Check property type if specified
+                if property_type is not None:
+                    prop_type = prop.get("property_type", "")
+                    if prop_type != property_type:
+                        continue
+
+                # Check identifiers if specified
+                if property_identifiers is not None:
+                    prop_identifiers = prop.get("identifiers", [])
+                    if not isinstance(prop_identifiers, list):
+                        continue
+
+                    if identifiers_match(property_identifiers, prop_identifiers):
+                        return True
+                else:
+                    # Property type matched and no identifier check needed
+                    return True
+
+    return False
+
+
+async def fetch_adagents(
+    publisher_domain: str,
+    timeout: float = 10.0,
+    user_agent: str = "AdCP-Client/1.0",
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """Fetch and parse adagents.json from publisher domain.
+
+    Args:
+        publisher_domain: Domain hosting the adagents.json file
+        timeout: Request timeout in seconds
+        user_agent: User-Agent header for HTTP request
+        client: Optional httpx.AsyncClient for connection pooling.
+            If provided, caller is responsible for client lifecycle.
+            If None, a new client is created for this request.
+
+    Returns:
+        Parsed adagents.json data
+
+    Raises:
+        AdagentsNotFoundError: If adagents.json not found (404)
+        AdagentsValidationError: If JSON is invalid or malformed
+        AdagentsTimeoutError: If request times out
+
+    Notes:
+        For production use with multiple requests, pass a shared httpx.AsyncClient
+        to enable connection pooling and improve performance.
+    """
+    # Validate and normalize domain for security
+    publisher_domain = _validate_publisher_domain(publisher_domain)
+
+    # Construct URL
+    url = f"https://{publisher_domain}/.well-known/adagents.json"
+
+    try:
+        # Use provided client or create a new one
+        if client is not None:
+            # Reuse provided client (connection pooling)
+            response = await client.get(
+                url,
+                headers={"User-Agent": user_agent},
+                timeout=timeout,
+                follow_redirects=True,
+            )
+        else:
+            # Create new client for single request
+            async with httpx.AsyncClient() as new_client:
+                response = await new_client.get(
+                    url,
+                    headers={"User-Agent": user_agent},
+                    timeout=timeout,
+                    follow_redirects=True,
+                )
+
+        # Process response (same for both paths)
+        if response.status_code == 404:
+            raise AdagentsNotFoundError(publisher_domain)
+
+        if response.status_code != 200:
+            raise AdagentsValidationError(
+                f"Failed to fetch adagents.json: HTTP {response.status_code}"
+            )
+
+        # Parse JSON
+        try:
+            data = response.json()
+        except Exception as e:
+            raise AdagentsValidationError(f"Invalid JSON in adagents.json: {e}") from e
+
+        # Validate basic structure
+        if not isinstance(data, dict):
+            raise AdagentsValidationError("adagents.json must be a JSON object")
+
+        if "authorized_agents" not in data:
+            raise AdagentsValidationError(
+                "adagents.json must have 'authorized_agents' field"
+            )
+
+        if not isinstance(data["authorized_agents"], list):
+            raise AdagentsValidationError("'authorized_agents' must be an array")
+
+        return data
+
+    except httpx.TimeoutException as e:
+        raise AdagentsTimeoutError(publisher_domain, timeout) from e
+    except httpx.RequestError as e:
+        raise AdagentsValidationError(f"Failed to fetch adagents.json: {e}") from e
+
+
+async def verify_agent_for_property(
+    publisher_domain: str,
+    agent_url: str,
+    property_identifiers: list[dict[str, str]],
+    property_type: str | None = None,
+    timeout: float = 10.0,
+    client: httpx.AsyncClient | None = None,
+) -> bool:
+    """Convenience wrapper to fetch adagents.json and verify authorization in one call.
+
+    Args:
+        publisher_domain: Domain hosting the adagents.json file
+        agent_url: URL of the sales agent to verify
+        property_identifiers: List of identifiers to match
+        property_type: Type of property (website, app, etc.) - optional
+        timeout: Request timeout in seconds
+        client: Optional httpx.AsyncClient for connection pooling
+
+    Returns:
+        True if agent is authorized, False otherwise
+
+    Raises:
+        AdagentsNotFoundError: If adagents.json not found (404)
+        AdagentsValidationError: If JSON is invalid or malformed
+        AdagentsTimeoutError: If request times out
+    """
+    adagents_data = await fetch_adagents(publisher_domain, timeout=timeout, client=client)
+    return verify_agent_authorization(
+        adagents_data=adagents_data,
+        agent_url=agent_url,
+        property_type=property_type,
+        property_identifiers=property_identifiers,
+    )
+
+
+def get_all_properties(adagents_data: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract all properties from adagents.json data.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+
+    Returns:
+        List of all properties across all authorized agents, with agent_url added
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+    """
+    if not isinstance(adagents_data, dict):
+        raise AdagentsValidationError("adagents_data must be a dictionary")
+
+    authorized_agents = adagents_data.get("authorized_agents")
+    if not isinstance(authorized_agents, list):
+        raise AdagentsValidationError("adagents.json must have 'authorized_agents' array")
+
+    properties = []
+    for agent in authorized_agents:
+        if not isinstance(agent, dict):
+            continue
+
+        agent_url = agent.get("url", "")
+        if not agent_url:
+            continue
+
+        agent_properties = agent.get("properties", [])
+        if not isinstance(agent_properties, list):
+            continue
+
+        # Add each property with the agent URL for reference
+        for prop in agent_properties:
+            if isinstance(prop, dict):
+                # Create a copy and add agent_url
+                prop_with_agent = {**prop, "agent_url": agent_url}
+                properties.append(prop_with_agent)
+
+    return properties
+
+
+def get_all_tags(adagents_data: dict[str, Any]) -> set[str]:
+    """Extract all unique tags from properties in adagents.json data.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+
+    Returns:
+        Set of all unique tags across all properties
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+    """
+    properties = get_all_properties(adagents_data)
+    tags = set()
+
+    for prop in properties:
+        prop_tags = prop.get("tags", [])
+        if isinstance(prop_tags, list):
+            for tag in prop_tags:
+                if isinstance(tag, str):
+                    tags.add(tag)
+
+    return tags
+
+
+def get_properties_by_agent(adagents_data: dict[str, Any], agent_url: str) -> list[dict[str, Any]]:
+    """Get all properties authorized for a specific agent.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+        agent_url: URL of the agent to filter by
+
+    Returns:
+        List of properties for the specified agent (empty if agent not found or no properties)
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+    """
+    if not isinstance(adagents_data, dict):
+        raise AdagentsValidationError("adagents_data must be a dictionary")
+
+    authorized_agents = adagents_data.get("authorized_agents")
+    if not isinstance(authorized_agents, list):
+        raise AdagentsValidationError("adagents.json must have 'authorized_agents' array")
+
+    # Normalize the agent URL for comparison
+    normalized_agent_url = normalize_url(agent_url)
+
+    for agent in authorized_agents:
+        if not isinstance(agent, dict):
+            continue
+
+        agent_url_from_json = agent.get("url", "")
+        if not agent_url_from_json:
+            continue
+
+        # Match agent URL (protocol-agnostic)
+        if normalize_url(agent_url_from_json) != normalized_agent_url:
+            continue
+
+        # Found the agent - return their properties
+        properties = agent.get("properties", [])
+        if not isinstance(properties, list):
+            return []
+
+        return [p for p in properties if isinstance(p, dict)]
+
+    return []