Skip to content

fix(rest): verify dual-audience (WBA-shape) request signatures - #279

Open
SergeevDmitry wants to merge 5 commits into
Universal-Commerce-Protocol:mainfrom
SergeevDmitry:fix/rest-dual-audience-signatures
Open

SergeevDmitry wants to merge 5 commits into
Universal-Commerce-Protocol:mainfrom
SergeevDmitry:fix/rest-dual-audience-signatures

Conversation

@SergeevDmitry

@SergeevDmitry SergeevDmitry commented Nov 5, 2026 •

Copy link
Copy Markdown

Description

signatures.md recommends a single dual-audience signature for Web Bot Auth interop, one that both a UCP verifier (resolving via UCP-Agent) and a WBA verifier accept (L246-L252). It covers "signature-agent";key="sig1" and carries tag="web-bot-auth" with the key's RFC 7638 thumbprint as keyid. For a UCP verifier the spec says the key parameter "selects a Dictionary member per RFC 9421 §2.1.2" (L368-L372), and its verification routine requires signature-agent coverage when the header is present and the thumbprint keyid under tag="web-bot-auth" (L693-L698, L717).

Both reference verifiers return no parse result for any component with a parameter (ucp_signing.py L217, signature.ts L170), so the recommended signature is answered signature_missing. The code lists this as a follow-up (L324); this PR is that follow-up, for Python and Node.

The spec's example request, signed with the RFC 9421 test-key-ed25519 key, whose thumbprint is the example's keyid:

Request main this PR
the dual-audience signature 401 signature_missing verifies
same, keyid is not the key's thumbprint 401 signature_missing 401 signature_invalid
same, Signature-Agent present but not covered verifies 401 signature_invalid (coverage)
a second label using "@method";sf next to the valid one 401 signature_missing the valid one verifies

The third row is a coverage gap on main: a signature that leaves the request's Signature-Agent unsigned is accepted.

Changes, the same in rest/python/server/ucp_signing.py and rest/nodejs/src/utils/signature.ts:

  • The Signature-Input parser keeps each component's key parameter. A component with any other parameter, a key on a derived component, or a repeated key marks only its own signature unsupported, which is then skipped like any other failing candidate (RFC 9421 Section 4.3) instead of failing the whole header.
  • A covered (name, key) resolves to that Dictionary member's value, re-serialized without optional whitespace, as RFC 9421 Section 2.1.2 defines it (dictionary_member / dictionaryMember).
  • A required component counts only when it is covered without a key parameter, since a key binds one Dictionary member and leaves the rest of the field unbound. required_components / requiredComponents require signature-agent when the header is present, and it may also be covered as ;key="<label>" with the signature's own label, which signatures.md binds together.
  • Under tag="web-bot-auth", keyid must equal the RFC 7638 thumbprint of the resolved JWK (jwk_thumbprint / jwkThumbprint).
  • The signature base writes "signature-agent";key="sig1" for such a component. buildSignatureBase in Node is generic over the component type, so existing callers are unchanged.

created and expires are not enforced; the spec leaves that to the application (L374-L379).

Testing:

  • New tests in ucp_signing_test.py and test/signing.test.ts: RFC 7638 vectors (RFC 8037 A.3 and the spec's keyid), Dictionary member serialization, key parameter parsing, and the four rows above against a signature base built by hand in the test. After review: a required component signed as one member (content-digest, idempotency-key, ucp-agent), signature-agent signed as another label's member, a kty that is not a key type name, the parser edge cases and an empty Dictionary item; each fails without the fix.
  • Python (3.14): pytest 402 passed; ruff check and ruff format --check clean (ruff 0.17.4). The new tests fail on main.
  • Node (20.17): npm run build (tsc, which also type-checks the tests) and npm test 199 passed; prettier@4.0.0-alpha.8 --check clean. On main the test file does not load, since the new helpers do not exist there; run against the main verifier, the dual-audience and ;sf cases answer signature_missing.

Category (Required)

  • Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
  • Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
  • Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
  • Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
  • Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
  • Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
  • SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
  • Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
  • UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
  • Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

None.

Checklist

  • I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.
  • (For Core/Capability) I have included/updated the relevant JSON schemas.
  • I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

signatures.md recommends one dual-audience signature for Web Bot Auth
interop and says a UCP verifier accepts it. That signature covers
"signature-agent";key="sig1" and carries tag="web-bot-auth" with the
key's RFC 7638 thumbprint as keyid. parse_signature_input returned None
for any component with a parameter, so such a request was answered
signature_missing.

Select the Dictionary member a key parameter names (RFC 9421 Section
2.1.2), require signature-agent coverage when the header is present,
and under tag="web-bot-auth" require keyid to be the key's thumbprint,
as the verification routine in signatures.md does. A component
parameter other than key now skips only that signature, not the whole
header.
The Node verifier had the same gap as the Python one: a component with
a parameter made parseSignatureInput return null, so the dual-audience
signature signatures.md recommends was answered signature_missing.

Mirror the Python change: Dictionary member selection for the key
parameter (RFC 9421 Section 2.1.2), signature-agent coverage when the
header is present, the RFC 7638 keyid check under tag="web-bot-auth",
and skipping only the signature that uses another component parameter.
buildSignatureBase takes a name or a [name, key] pair.
@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Nov 5, 2026

@damaz91 damaz91 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thank you @SergeevDmitry for implementing dual-audience (tag="web-bot-auth") verification across both the Python and Node.js reference servers and including clear RFC 7638 / WBA test vectors!

We found two blocking edge cases during review that need tightening before we can merge:

  1. Required-component coverage bypass via ;key="..." (ucp_signing.py:240-250, 668 & signature.ts:198-212, 518):

    • parse_signature_input / parseSignatureInput currently accepts ;key="..." on any component without setting unsupported, and the coverage check tests required against bare desc["components"] names before pairing with component_keys / componentKeys.
    • As a result, a signature covering "content-digest";key="a" with Content-Digest: a=1, sha-256=:<tampered-body-digest>: passes both content_digest_matches (which scans comma-separated members for sha-256) and verify_request (resolving ("content-digest", "a") → "1"), leaving the body unbound. The same applies to "idempotency-key";key="a" (replay with Idempotency-Key: a=1, <new-key>), "ucp-agent";key="a", and cross-label "signature-agent";key="other" on sig1 (where signatures.md binds the Signature-Input label, ;key="<label>", and the Signature-Agent member key together).
    • Suggested fix: Enforce coverage on the (name, key) / [name, key] pairs so that (a) every required component other than "signature-agent" must be covered unparameterized (key is None), (b) when "signature-agent" is required, it must be covered either unparameterized ("signature-agent") or with ;key="<label>" matching the candidate signature's own label, and (c) ;key="..." on derived @... components sets unsupported = True (RFC 9421 §2.2).
  2. Unhandled TypeError (500) in jwk_thumbprint / jwkThumbprint on malformed profile JWKs (ucp_signing.py:376, 685 & signature.ts:44-48, 303-307):

    • Python: Because jwk_thumbprint(jwk) runs before public_key_from_jwk(jwk), a malformed JWK with "kty": ["EC"] raises TypeError: unhashable type: 'list' in _THUMBPRINT_MEMBERS.get(jwk.get("kty")), escaping verify_request as a 500 (regressing #263).
    • Node.js: Because THUMBPRINT_MEMBERS is a plain object, a JWK with "kty": "toString" resolves Object.prototype.toString and throws TypeError: members.every is not a function (which verifySignature rethrows as a 500 even when REQUIRE_SIGNATURES is unset).
    • Suggested fix: Guard isinstance(kty, str) in Python and typeof jwk.kty === "string" && Object.hasOwn(THUMBPRINT_MEMBERS, jwk.kty) in Node.js, and check thumbprint is None or keyid != thumbprint under tag == "web-bot-auth".

Optional minor parser polish: Checking len(v) >= 2 before slicing quotes on v (v == '"' currently passes startswith('"') and endswith('"')), flagging duplicate ;key=... parameters on the same component as unsupported, and returning None/null in dictionary_member when parts[0] is empty (e.g. sig1=;type=jwks_uri) would harden the structured-field edge cases nicely.

A required component signed with a key parameter selected one Dictionary
member and left the rest of the field unbound, so "content-digest";key="a"
passed coverage while the body digest sat in an unsigned member. Coverage
now checks (name, key) pairs: a required component counts only without a
key, and signature-agent also as ;key="<label>" with the signature's own
label, which signatures.md binds together. A key on a derived component, a
repeated key and a key of a lone quote mark the signature unsupported.

jwk_thumbprint took kty from the profile as is, so a kty that is a list
raised TypeError before public_key_from_jwk could report the key as
malformed. It now reads only a string kty, and the WBA check rejects a
missing thumbprint explicitly. dictionary_member returns None for an
empty item such as sig1=;type=jwks_uri.
A required component signed with a key parameter selected one Dictionary
member and left the rest of the field unbound, so "content-digest";key="a"
passed coverage while the body digest sat in an unsigned member. Coverage
now checks [name, key] pairs: a required component counts only without a
key, and signature-agent also as ;key="<label>" with the signature's own
label, which signatures.md binds together. A key on a derived component, a
repeated key and a key of a lone quote mark the signature unsupported.

jwkThumbprint looked kty up on a plain object, so "toString" resolved
through the prototype and threw a TypeError that verifySignature answers
with a 500. It now reads only a string kty that is an own member of the
table, and the WBA check rejects a missing thumbprint explicitly.
dictionaryMember returns null for an empty item such as sig1=;type=jwks_uri.
@SergeevDmitry

Copy link
Copy Markdown
Author

Thanks for the careful review. Both are fixed, in ca1c173 (Python) and 97c1a98 (Node.js), on top of a merge of main (#263, #264):

  1. Coverage now checks (name, key) / [name, key] pairs. A required component counts only when it is covered without a key parameter, so "content-digest";key="a", "idempotency-key";key="a" and "ucp-agent";key="a" no longer satisfy the gate. signature-agent may also be covered as ;key="<label>" with the candidate's own label, so ;key="other" on sig1 is rejected. A key on a derived component, a repeated key and a key of a lone quote mark the signature unsupported.
  2. jwk_thumbprint reads only a string kty, and jwkThumbprint only a string kty that is an own member of THUMBPRINT_MEMBERS. The WBA check rejects a null thumbprint explicitly, so a kty of ["OKP"] or "toString" now ends in signature_invalid instead of a TypeError.

From the minor notes: both parsers check the length before unquoting a value, and dictionary_member / dictionaryMember return None/null for an empty item such as sig1=;type=jwks_uri.

Each case from the review has a test in ucp_signing_test.py and test/signing.test.ts, and each fails without the fix. A positive test covers signature-agent signed without a key parameter.

Python 3.14: pytest 402 passed; ruff check and ruff format --check clean
Node 20.17:  tsc clean; npm test 199 passed; prettier@4.0.0-alpha.8 --check clean

@damaz91 damaz91 added status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Nov 12, 2026

@damaz91 damaz91 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thank you @SergeevDmitry for the clean follow-up in ca1c173 and 97c1a98!

Both blocking items from the previous review (whole-field required-component coverage with label-bound signature-agent;key="<label>", and jwk_thumbprint / jwkThumbprint type/own-property guards) as well as all three structured-field parser edge cases are cleanly resolved and well covered by tests across Python and Node.js. LGTM!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants