fix(signing): authorized_operators[] is top-level on brand.json, re-export new types

Addresses PR #770 reviewer feedback (aao-ipr-bot, two reviews on commit
d3536c2).

**Blocking — authorized_operators[] location.** Per the canonical
brand.json schema (House Portfolio variant in schemas/cache/3.0/brand.json),
``authorized_operators`` is a TOP-LEVEL property of the document —
sibling of ``house`` / ``brands`` / ``contact`` / ``trademarks`` — and
ADCP #3690 security.mdx step 3 reads it unqualified at the document
root.

I had misread the schema indentation and was reading from
``data["house"]["authorized_operators"]``. As written, the SDK would
have silently failed closed against every conforming brand.json the
TS/Go reference impls accept, AND would have created an
operator-delegation bypass via cross-verifier disagreement once Stage 5
wires it into the verifier path. Fix reads from the document root and
adds a defensive test asserting that operators misplaced under
``house`` are IGNORED (the wrong-location reading must fail closed).

**Non-blocking — re-export new public symbols.** Reviewer noted the
PR description says adopters can use the resolver today, but the new
types live in submodules and aren't exported from ``adcp.signing``.
The sibling ``BrandJsonJwksResolver`` IS exported via that surface,
so the new types should follow the same pattern. Adds to ``__init__``
and ``__all__``:

  - BrandAuthorizationResolver / BrandJsonAuthorizationResolver
  - BrandAuthorizationResult / BrandAuthorizationReason
  - build_brand_json_resolvers
  - host_from / registrable_domain / same_registrable_domain

**Not addressed in this commit** (deferring to Stage 4 PR or
follow-ups; reviewer flagged as non-blocking):

- BrandAuthorizationReason taxonomy overlap with spec codes — the
  taxonomy is intentionally finer than the spec's framework-boundary
  codes (e.g. ``agent_type_mismatch`` vs spec's
  ``agent_not_in_brand_json``); Stage 5 maps reasons to spec codes at
  the dispatch boundary. Confirmed with reviewer reading.
- Protocol returns ``bool`` not ``BrandAuthorizationResult`` — Stage 5
  consumers use ``check()`` on the concrete impl. Widening the
  Protocol can come with Stage 5 when the framework wire-up exposes
  the real ergonomic shape.
- IDNA-2008 A-label canonicalization in ``host_from`` — existing
  codebase uses stdlib ``host.encode("idna")`` (IDNA 2003) consistently
  (jwks.py, ip_pinned_transport.py, revocation_fetcher.py). Migrating
  all of them to IDNA 2008 is a separate concern, deserves its own
  spec-conformance pass.
- shared-fetcher test should exercise the JWKS resolver too — agreed,
  trivial follow-up.

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

Author: bokelley

src/adcp/signing/__init__.py

@@ -101,6 +101,13 @@
     SigningDecision,
     operation_needs_signing,
 )
+from adcp.signing.brand_authz import (
+    BrandAuthorizationReason,
+    BrandAuthorizationResolver,
+    BrandAuthorizationResult,
+    BrandJsonAuthorizationResolver,
+    build_brand_json_resolvers,
+)
 from adcp.signing.brand_jwks import (
     BrandAgentType,
     BrandJsonJwksResolver,
@@ -175,6 +182,11 @@
     REQUEST_SIGNATURE_WINDOW_INVALID,
     SignatureVerificationError,
 )
+from adcp.signing.etld import (
+    host_from,
+    registrable_domain,
+    same_registrable_domain,
+)
 from adcp.signing.ip_pinned_transport import (
     AsyncIpPinnedTransport,
     IpPinnedTransport,
@@ -293,6 +305,10 @@ def __init__(self, *args: object, **kwargs: object) -> None:
     "AsyncJwksResolver",
     "AsyncRevocationListFetcher",
     "BrandAgentType",
+    "BrandAuthorizationReason",
+    "BrandAuthorizationResolver",
+    "BrandAuthorizationResult",
+    "BrandJsonAuthorizationResolver",
     "BrandJsonJwksResolver",
     "BrandJsonResolverError",
     "BrandJsonResolverErrorCode",
@@ -373,6 +389,7 @@ def __init__(self, *args: object, **kwargs: object) -> None:
     "b64url_decode",
     "b64url_encode",
     "build_async_ip_pinned_transport",
+    "build_brand_json_resolvers",
     "build_capability_cache_key",
     "build_ip_pinned_transport",
     "build_signature_base",
@@ -388,15 +405,18 @@ def __init__(self, *args: object, **kwargs: object) -> None:
     "extract_signature_bytes",
     "format_signature_header",
     "generate_signing_keypair",
+    "host_from",
     "install_signing_event_hook",
     "load_private_key_pem",
     "operation_needs_signing",
     "parse_signature_input_header",
     "pem_to_adcp_jwk",
     "private_key_from_jwk",
     "public_key_from_jwk",
+    "registrable_domain",
     "resolve_agent",
     "resolve_and_validate_host",
+    "same_registrable_domain",
     "sign_request",
     "sign_signature_base",
     "sign_standard_webhook",

src/adcp/signing/brand_authz.py

@@ -498,11 +498,18 @@ def _find_authorized_operator(
     domain == declared operator domain registrable domain) so an
     operator declared as ``wpp.com`` covers ``api.wpp.com``,
     ``us-east.wpp.com``, etc. — same posture as eTLD+1 step 2a.
+
+    **Location: top-level on the brand.json document**, not nested
+    under ``house``. Per the canonical brand.json schema (House
+    Portfolio variant), ``authorized_operators`` is a sibling of
+    ``house`` / ``brands`` / ``contact`` / ``trademarks``, and ADCP
+    #3690 ``security.mdx`` step 3 reads it unqualified at the document
+    root. Reading it from ``data["house"]["authorized_operators"]``
+    would silently fail closed against every conforming brand.json
+    (binding_failed everywhere) and would create cross-verifier
+    disagreement with the TS reference impl.
     """
-    house = data.get("house")
-    if not isinstance(house, dict):
-        return None
-    operators = house.get("authorized_operators")
+    operators = data.get("authorized_operators")
     if not isinstance(operators, list):
         return None
 

tests/test_brand_authz.py

@@ -243,11 +243,11 @@ async def test_authz_operator_delegation_with_wildcard_brands() -> None:
                 "agents": [
                     {"type": "signals", "id": "s", "url": "https://wpp.com/brand/agent"},
                 ],
-                "authorized_operators": [
-                    {"domain": "wpp.com", "brands": ["*"]},
-                ],
             },
             "brands": [{"id": "brand_one"}],
+            "authorized_operators": [
+                {"domain": "wpp.com", "brands": ["*"]},
+            ],
         }
     )
     transport = _MockTransport({"https://brand.com/.well-known/brand.json": {"body": body}})
@@ -273,11 +273,11 @@ async def test_authz_operator_delegation_scoped_brand_id_matches() -> None:
                 "agents": [
                     {"type": "signals", "id": "s", "url": "https://wpp.com/agent"},
                 ],
-                "authorized_operators": [
-                    {"domain": "wpp.com", "brands": ["nike"]},
-                ],
             },
             "brands": [{"id": "nike"}, {"id": "adidas"}],
+            "authorized_operators": [
+                {"domain": "wpp.com", "brands": ["nike"]},
+            ],
         }
     )
     transport = _MockTransport({"https://brand.com/.well-known/brand.json": {"body": body}})
@@ -304,11 +304,11 @@ async def test_authz_operator_delegation_scoped_brand_id_misses() -> None:
                 "agents": [
                     {"type": "signals", "id": "s", "url": "https://wpp.com/agent"},
                 ],
-                "authorized_operators": [
-                    {"domain": "wpp.com", "brands": ["nike"]},
-                ],
             },
             "brands": [{"id": "nike"}, {"id": "adidas"}],
+            "authorized_operators": [
+                {"domain": "wpp.com", "brands": ["nike"]},
+            ],
         }
     )
     transport = _MockTransport({"https://brand.com/.well-known/brand.json": {"body": body}})
@@ -337,10 +337,10 @@ async def test_authz_operator_without_wildcard_fails_unscoped_request() -> None:
                 "agents": [
                     {"type": "signals", "id": "s", "url": "https://wpp.com/agent"},
                 ],
-                "authorized_operators": [
-                    {"domain": "wpp.com", "brands": ["nike"]},
-                ],
             },
+            "authorized_operators": [
+                {"domain": "wpp.com", "brands": ["nike"]},
+            ],
         }
     )
     transport = _MockTransport({"https://brand.com/.well-known/brand.json": {"body": body}})
@@ -368,10 +368,10 @@ async def test_authz_operator_etld1_compared_not_byte_equal() -> None:
                 "agents": [
                     {"type": "signals", "id": "s", "url": "https://api.wpp.com/agent"},
                 ],
-                "authorized_operators": [
-                    {"domain": "wpp.com", "brands": ["*"]},
-                ],
             },
+            "authorized_operators": [
+                {"domain": "wpp.com", "brands": ["*"]},
+            ],
         }
     )
     transport = _MockTransport({"https://brand.com/.well-known/brand.json": {"body": body}})
@@ -388,6 +388,42 @@ async def test_authz_operator_etld1_compared_not_byte_equal() -> None:
     assert result.reason == "operator_delegation"
 
 
+@pytest.mark.asyncio
+async def test_authz_operator_declared_under_house_is_ignored() -> None:
+    # Per the canonical brand.json schema, ``authorized_operators`` is
+    # top-level on the House Portfolio variant — sibling of ``house`` /
+    # ``brands`` / ``contact``. A document that misplaces the array
+    # inside ``house`` MUST fail closed (the spec's reference verifier
+    # reads top-level; honoring the nested location would create cross-
+    # verifier disagreement and an operator-delegation bypass via the
+    # wrong-location reading).
+    body = _brand_json(
+        {
+            "house": {
+                "agents": [
+                    {"type": "signals", "id": "s", "url": "https://wpp.com/agent"},
+                ],
+                # Wrong location — should be ignored.
+                "authorized_operators": [
+                    {"domain": "wpp.com", "brands": ["*"]},
+                ],
+            },
+        }
+    )
+    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://wpp.com/agent",
+        brand_domain="brand.com",
+    )
+    assert result.authorized is False
+    assert result.reason == "binding_failed"
+
+
 # ----- brand_id scopes the agents[] walk -----