fix(signing): align brand-authz with ADCP #3690 security profile

Stage 4 spec research surfaced two conformance gaps in the just-landed
brand_authz code. Both are fix-now-before-review issues, not stage-4
scope; landing on this PR keeps the security-relevant deltas in one
review pass instead of shipping a known-divergent impl behind a
"spec-conformant" label.

1. **PSL PRIVATE section must be in scope** (security)

   Per security.mdx §"Origin binding": "ICANN+PRIVATE sections both in
   scope so platforms like vercel.app, pages.dev, github.io are treated
   as suffixes". Without include_psl_private_domains=True, an attacker's
   ``attacker.vercel.app`` and a victim's ``victim.vercel.app`` would
   share an eTLD+1 of ``vercel.app`` — and the attacker's deployment
   would falsely satisfy the binding check against the victim's
   vercel-hosted brand.json.

   Fix: enable include_psl_private_domains on the singleton extractor.
   Regression test covers vercel.app / pages.dev / github.io.

2. **agents[] match must be byte-equal, not canonicalized**

   Per security.mdx §"Discovering an agent's signing keys": "Find the
   entry in agents[] whose url byte-equals A (no canonicalization at
   this step — the most common failure mode is a trailing-slash or
   scheme mismatch)." Canonicalizing silently authorizes URLs that
   drift from the operator's declaration.

   Also per spec: multiple matches → ``request_signature_brand_json_ambiguous``.
   Schema does not constrain agents[] to be unique-by-URL, so dupes
   from operator misconfig must fail closed rather than silently picking
   the first match.

   Fix: _find_listed_agent → _find_listed_agents (plural, returns full
   match list). Byte-equal comparison. New ``agent_ambiguous`` reason
   on the BrandAuthorizationReason taxonomy (maps to the spec's
   ``request_signature_brand_json_ambiguous`` at the framework
   boundary in stage 5). New tests cover trailing-slash mismatch,
   case mismatch, and duplicate entries.

Removes the now-unused _canonicalize_agent_url helper and its imports.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bokelley

src/adcp/signing/brand_authz.py

@@ -38,7 +38,6 @@
 from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any, Literal, Protocol, runtime_checkable
-from urllib.parse import urlsplit
 
 from adcp.signing.brand_jwks import (
     DEFAULT_BRAND_JSON_TIMEOUT_SECONDS,
@@ -51,7 +50,6 @@
     BrandJsonResolverError,
     _BrandJsonFetcher,
     _BrandJsonSnapshot,
-    _canonicalize_url,
     _ClientFactory,
 )
 from adcp.signing.etld import host_from, registrable_domain, same_registrable_domain
@@ -64,6 +62,7 @@
     "etld1_match",
     "operator_delegation",
     "agent_not_listed",
+    "agent_ambiguous",
     "agent_type_mismatch",
     "binding_failed",
     "brand_json_unavailable",
@@ -220,22 +219,39 @@ async def check(
                 fetch_error=snap,
             )
 
-        matched = _find_listed_agent(
+        listing = _find_listed_agents(
             snap.data,
             agent_url=agent_url,
             agent_type=agent_type,
             brand_id=brand_id,
         )
 
-        if matched is None:
+        if len(listing) == 0:
             # Distinguish "not present at all" from "present but wrong type":
-            # the latter is a stronger signal of misconfiguration.
+            # the latter is a stronger signal of misconfiguration. Spec
+            # folds both into ``request_signature_agent_not_in_brand_json``;
+            # we keep the finer reason so the framework can choose to
+            # surface it in diagnostics.
             if agent_type is not None and _has_listed_agent_at(
                 snap.data, agent_url=agent_url, brand_id=brand_id
             ):
                 return BrandAuthorizationResult(False, reason="agent_type_mismatch")
             return BrandAuthorizationResult(False, reason="agent_not_listed")
 
+        if len(listing) > 1:
+            # Multiple agents[] entries byte-equal the agent URL. Per
+            # ADCP #3690 this maps to ``request_signature_brand_json_ambiguous``:
+            # the brand.json schema does not constrain agents[] to be
+            # unique-by-URL, so an operator misconfig can produce duplicates
+            # — fail closed rather than silently picking one.
+            return BrandAuthorizationResult(
+                False,
+                reason="agent_ambiguous",
+                matched_agent_url=listing[0].url,
+            )
+
+        matched = listing[0]
+
         # Step 2a: eTLD+1 binding.
         if same_registrable_domain(agent_url, brand_host):
             return BrandAuthorizationResult(
@@ -363,38 +379,51 @@ class _ListedAgent:
     type: BrandAgentType | None
 
 
-def _find_listed_agent(
+def _find_listed_agents(
     data: dict[str, Any],
     *,
     agent_url: str,
     agent_type: BrandAgentType | None,
     brand_id: str | None,
-) -> _ListedAgent | None:
-    """Search ``agents[]`` arrays for an entry matching ``agent_url``.
-
-    Walks (in order) top-level ``agents``, ``house.agents``, and per-
-    brand ``brands[].agents`` — bounded by ``brand_id`` when provided.
-    Returns the first canonical-URL match (with ``type`` filter when
-    set); ``None`` if no entry matches.
+) -> list[_ListedAgent]:
+    """Search ``agents[]`` arrays for entries matching ``agent_url``.
+
+    Walks top-level ``agents``, ``house.agents``, and per-brand
+    ``brands[].agents`` (bounded by ``brand_id`` when provided),
+    returning every entry whose ``url`` **byte-equals** ``agent_url``.
+
+    **Byte-equal match by spec mandate.** Per ADCP #3690 security
+    profile: "Find the entry in ``agents[]`` whose ``url`` byte-equals
+    A (no canonicalization at this step). The most common failure
+    mode is a trailing-slash or scheme mismatch (e.g.,
+    ``https://x.com/mcp`` ≠ ``https://x.com/mcp/``)." Canonicalizing
+    would silently authorize agents whose URL is "close enough" to
+    what the brand declared — operators must be deliberate about what
+    they list.
+
+    Returning the full match list (rather than the first match) lets
+    the caller distinguish ``agent_not_listed`` (0 matches),
+    ``agent_type_mismatch`` (0 type-filtered matches but the URL is
+    listed), and ``agent_ambiguous`` (>1 matches — operator misconfig,
+    spec maps to ``request_signature_brand_json_ambiguous``).
     """
-    target = _canonicalize_agent_url(agent_url)
-
+    matches: list[_ListedAgent] = []
     for entry in _walk_agents(data, brand_id=brand_id):
         if not isinstance(entry, dict):
             continue
         url = entry.get("url")
-        if not isinstance(url, str):
-            continue
-        if _canonicalize_agent_url(url) != target:
+        if not isinstance(url, str) or url != agent_url:
             continue
         if agent_type is not None and entry.get("type") != agent_type:
             continue
         listed_type = entry.get("type")
-        return _ListedAgent(
-            url=url,
-            type=listed_type if isinstance(listed_type, str) else None,  # type: ignore[arg-type]
+        matches.append(
+            _ListedAgent(
+                url=url,
+                type=listed_type if isinstance(listed_type, str) else None,  # type: ignore[arg-type]
+            )
         )
-    return None
+    return matches
 
 
 def _has_listed_agent_at(
@@ -403,15 +432,14 @@ def _has_listed_agent_at(
     agent_url: str,
     brand_id: str | None,
 ) -> bool:
-    """Return True if ``agent_url`` appears in ``agents[]`` regardless
-    of ``type`` — used to distinguish ``agent_type_mismatch`` from
-    ``agent_not_listed`` for caller diagnostics."""
-    target = _canonicalize_agent_url(agent_url)
+    """Return True if ``agent_url`` byte-equals any listed ``agents[].url``
+    regardless of ``type`` — used to distinguish ``agent_type_mismatch``
+    from ``agent_not_listed`` for caller diagnostics."""
     for entry in _walk_agents(data, brand_id=brand_id):
         if not isinstance(entry, dict):
             continue
         url = entry.get("url")
-        if isinstance(url, str) and _canonicalize_agent_url(url) == target:
+        if isinstance(url, str) and url == agent_url:
             return True
     return False
 
@@ -518,31 +546,6 @@ def _find_authorized_operator(
     return None
 
 
-def _canonicalize_agent_url(url: str) -> str:
-    """Canonicalize an agent URL for byte-equal comparison.
-
-    Reuses the brand.json URL canonicalizer (scheme/host lowercased,
-    default port stripped, fragment stripped, userinfo rejected).
-    Falls back to a basic ``urlsplit``-based lowercase on inputs the
-    canonicalizer rejects (the comparison is best-effort here — a URL
-    we cannot canonicalize will never match a properly-canonicalized
-    target, which is the correct failure direction).
-    """
-    try:
-        return _canonicalize_url(url, allow_private=True)
-    except BrandJsonResolverError:
-        # Fall back to a permissive normalization so the comparison can
-        # still proceed (the caller's verified agent_url has already
-        # been validated upstream; the brand.json's listed url is the
-        # one we can't structurally trust).
-        parts = urlsplit(url)
-        if not parts.scheme or not parts.netloc:
-            return url.lower()
-        netloc = parts.netloc.lower()
-        path = parts.path or "/"
-        return f"{parts.scheme.lower()}://{netloc}{path}"
-
-
 __all__ = [
     "BrandAuthorizationReason",
     "BrandAuthorizationResolver",

src/adcp/signing/etld.py

@@ -40,8 +40,21 @@ def _extractor() -> tldextract.TLDExtract:
     First-call PSL parsing is non-trivial (~hundreds of ms on cold disk
     cache); subsequent calls are cheap. The singleton keeps that cost
     paid-once-per-process.
+
+    **Both ICANN and PRIVATE PSL sections are in scope.** Per ADCP
+    spec #3690, the eTLD+1 binding must treat platform-shared suffixes
+    like ``vercel.app``, ``pages.dev``, and ``github.io`` (in the PSL
+    PRIVATE section) as suffixes — otherwise ``attacker.vercel.app``
+    and ``victim.vercel.app`` would share an eTLD+1 of ``vercel.app``
+    and an attacker's vercel deployment would falsely satisfy the
+    binding against a vercel-hosted brand. ``include_psl_private_domains=True``
+    closes that vector.
     """
-    return tldextract.TLDExtract(suffix_list_urls=(), fallback_to_snapshot=True)
+    return tldextract.TLDExtract(
+        suffix_list_urls=(),
+        fallback_to_snapshot=True,
+        include_psl_private_domains=True,
+    )
 
 
 def host_from(value: str) -> str:

tests/test_brand_authz.py

@@ -491,6 +491,82 @@ async def test_authz_brand_json_404_returns_brand_json_unavailable() -> None:
     assert result.fetch_error is not None
 
 
+# ----- byte-equal agents[] matching (spec mandate) -----
+
+
+@pytest.mark.asyncio
+async def test_authz_trailing_slash_mismatch_fails_byte_equal() -> None:
+    # Per ADCP #3690: agents[].url match MUST be byte-equal. A trailing
+    # slash on the request side vs no trailing slash on the brand.json
+    # side is a mismatch — operators must list the exact URL.
+    body = _brand_json(
+        {"agents": [{"type": "signals", "id": "s", "url": "https://ads.brand.com/agent"}]}
+    )
+    transport = _MockTransport({"https://brand.com/.well-known/brand.json": {"body": body}})
+    resolver = BrandJsonAuthorizationResolver(
+        "https://brand.com/.well-known/brand.json",
+        _client_factory=_factory(transport),
+    )
+
+    result = await resolver.check(
+        agent_url="https://ads.brand.com/agent/",  # extra trailing slash
+        brand_domain="brand.com",
+    )
+    assert result.authorized is False
+    assert result.reason == "agent_not_listed"
+
+
+@pytest.mark.asyncio
+async def test_authz_case_mismatch_fails_byte_equal() -> None:
+    # Scheme/host case differences are NOT canonicalized at this step.
+    # The spec's rationale: operators must be deliberate about what
+    # they list; a canonicalization-permissive match silently authorizes
+    # URLs that drift from what the brand declared.
+    body = _brand_json(
+        {"agents": [{"type": "signals", "id": "s", "url": "https://ads.brand.com/agent"}]}
+    )
+    transport = _MockTransport({"https://brand.com/.well-known/brand.json": {"body": body}})
+    resolver = BrandJsonAuthorizationResolver(
+        "https://brand.com/.well-known/brand.json",
+        _client_factory=_factory(transport),
+    )
+
+    result = await resolver.check(
+        agent_url="https://ADS.brand.com/agent",  # uppercase host
+        brand_domain="brand.com",
+    )
+    assert result.authorized is False
+    assert result.reason == "agent_not_listed"
+
+
+@pytest.mark.asyncio
+async def test_authz_duplicate_agents_entry_returns_ambiguous() -> None:
+    # brand.json schema does NOT constrain agents[] to be unique-by-URL.
+    # If an operator misconfigures with duplicate entries for the same
+    # URL, fail closed rather than silently picking one — maps to
+    # ``request_signature_brand_json_ambiguous`` at the framework boundary.
+    body = _brand_json(
+        {
+            "agents": [
+                {"type": "signals", "id": "a", "url": "https://ads.brand.com/agent"},
+                {"type": "signals", "id": "b", "url": "https://ads.brand.com/agent"},
+            ]
+        }
+    )
+    transport = _MockTransport({"https://brand.com/.well-known/brand.json": {"body": body}})
+    resolver = BrandJsonAuthorizationResolver(
+        "https://brand.com/.well-known/brand.json",
+        _client_factory=_factory(transport),
+    )
+
+    result = await resolver.check(
+        agent_url="https://ads.brand.com/agent",
+        brand_domain="brand.com",
+    )
+    assert result.authorized is False
+    assert result.reason == "agent_ambiguous"
+
+
 # ----- shared-fetcher builder -----
 
 

tests/test_etld.py

@@ -143,6 +143,20 @@ def test_same_registrable_domain_cross_tld_with_shared_label() -> None:
     assert same_registrable_domain("brand.com", "brand.org") is False
 
 
+def test_registrable_domain_psl_private_section_in_scope() -> None:
+    # Per ADCP #3690, the PSL PRIVATE section must be in scope so
+    # platform-shared suffixes (``vercel.app``, ``pages.dev``,
+    # ``github.io``) are treated as suffixes. Without this,
+    # ``attacker.vercel.app`` and ``victim.vercel.app`` would share an
+    # eTLD+1 and the binding check would authorize an attacker's
+    # vercel deployment for a victim's vercel-hosted brand.
+    assert registrable_domain("attacker.vercel.app") == "attacker.vercel.app"
+    assert registrable_domain("victim.vercel.app") == "victim.vercel.app"
+    assert same_registrable_domain("attacker.vercel.app", "victim.vercel.app") is False
+    assert registrable_domain("brand.github.io") == "brand.github.io"
+    assert registrable_domain("brand.pages.dev") == "brand.pages.dev"
+
+
 def test_registrable_domain_reserved_tld_returns_none() -> None:
     # ``.example``, ``.test``, ``.invalid``, ``.localhost`` are RFC 2606
     # reserved names — NOT in the PSL — so they fail closed. The spec's