Skip to content

docs(signing): clarify signing-agent operator key discovery - #1430

Merged
bokelley merged 1 commit into
mainfrom
bokelley/adcp-client-python-1426
Oct 7, 2026
Merged

bokelley merged 1 commit into
mainfrom
bokelley/adcp-client-python-1426

Conversation

@bokelley

@bokelley bokelley commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Signing documentation used “operator” without distinguishing the signing agent's operator from the request account's operator or brand. That led sellers to discover signing keys at an agency's account domain and reject legitimate requests.

Clarify the trust source in both signing guides and the resolver docstrings. Lead with agent URL discovery and onboarded key mappings, explain the onboarding refresh responsibility, and present direct BrandJsonJwksResolver construction as a lower-level option. Account and signing-agent operator roles remain distinct even when their domains coincide. Executable code is unchanged.

Closes #1426.

Validation:

  • Independent documentation, protocol, and security expert reviews found no blockers; their clarity improvements are incorporated.
  • 156 existing signing tests passed across test_brand_jwks.py, test_agent_resolver.py, and test_signed_request_verification.py.
  • Ruff, Black, and mypy checks passed; Python snippets parse and documented imports, signatures, and resolver constructors match the SDK.
  • AST comparison confirmed that Python changes affect docstrings only.

Open workspace in Conductor

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Approve

Approve — docs + docstring-only clarification, no blocking or Medium findings.

This PR clarifies that signing keys root through the signing agent's operator (brand.json via get_adcp_capabilities / onboarding), closing the #1426 footgun. The reviewer verified every referenced SDK symbol and signature (verify_from_agent_url, async_resolve_agent, JwksUriSignerKeys, StaticSignerKeys, BrandJsonJwksResolver) as accurate. Changes to src/adcp/signing/brand_jwks.py are confined to module and class docstrings — no executable code change, matching the AST claim. Much of agent-resolution-33.md is reorganization of existing prose.

The high_risk flag fired only because brand_jwks.py matches src/adcp/signing/**, but the entry is (modified) with no Medium-or-higher finding, so it is presumed safe (no row-5 trigger). gated_paths is false, and the author matches no no-auto-approve team. No findings of any severity. None of rows 1–8 fire → row 9 approve.

@bokelley
bokelley merged commit 3c5fa30 into main Oct 7, 2026
47 checks passed
@bokelley
bokelley deleted the bokelley/adcp-client-python-1426 branch October 7, 2026 01:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: say that key-discovery "operator" is the signing agent's operator, never account.operator

1 participant