Repository navigation
fix(rest): verify dual-audience (WBA-shape) request signatures - #279
SergeevDmitry wants to merge 5 commits into
Conversation
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
left a comment
There was a problem hiding this comment.
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:
-
Required-component coverage bypass via
;key="..."(ucp_signing.py:240-250, 668&signature.ts:198-212, 518):parse_signature_input/parseSignatureInputcurrently accepts;key="..."on any component without settingunsupported, and the coverage check testsrequiredagainst baredesc["components"]names before pairing withcomponent_keys/componentKeys.- As a result, a signature covering
"content-digest";key="a"withContent-Digest: a=1, sha-256=:<tampered-body-digest>:passes bothcontent_digest_matches(which scans comma-separated members forsha-256) andverify_request(resolving("content-digest", "a")→"1"), leaving the body unbound. The same applies to"idempotency-key";key="a"(replay withIdempotency-Key: a=1, <new-key>),"ucp-agent";key="a", and cross-label"signature-agent";key="other"onsig1(wheresignatures.mdbinds theSignature-Inputlabel,;key="<label>", and theSignature-Agentmember 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 ownlabel, and (c);key="..."on derived@...components setsunsupported = True(RFC 9421 §2.2).
-
Unhandled
TypeError(500) injwk_thumbprint/jwkThumbprinton malformed profile JWKs (ucp_signing.py:376, 685&signature.ts:44-48, 303-307):- Python: Because
jwk_thumbprint(jwk)runs beforepublic_key_from_jwk(jwk), a malformed JWK with"kty": ["EC"]raisesTypeError: unhashable type: 'list'in_THUMBPRINT_MEMBERS.get(jwk.get("kty")), escapingverify_requestas a500(regressing #263). - Node.js: Because
THUMBPRINT_MEMBERSis a plain object, a JWK with"kty": "toString"resolvesObject.prototype.toStringand throwsTypeError: members.every is not a function(whichverifySignaturerethrows as a500even whenREQUIRE_SIGNATURESis unset). - Suggested fix: Guard
isinstance(kty, str)in Python andtypeof jwk.kty === "string" && Object.hasOwn(THUMBPRINT_MEMBERS, jwk.kty)in Node.js, and checkthumbprint is None or keyid != thumbprintundertag == "web-bot-auth".
- Python: Because
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.
|
Thanks for the careful review. Both are fixed, in ca1c173 (Python) and 97c1a98 (Node.js), on top of a merge of main (#263, #264):
From the minor notes: both parsers check the length before unquoting a value, and Each case from the review has a test in |
damaz91
left a comment
There was a problem hiding this comment.
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!
Description
signatures.mdrecommends a single dual-audience signature for Web Bot Auth interop, one that both a UCP verifier (resolving viaUCP-Agent) and a WBA verifier accept (L246-L252). It covers"signature-agent";key="sig1"and carriestag="web-bot-auth"with the key's RFC 7638 thumbprint askeyid. For a UCP verifier the spec says thekeyparameter "selects a Dictionary member per RFC 9421 §2.1.2" (L368-L372), and its verification routine requiressignature-agentcoverage when the header is present and the thumbprintkeyidundertag="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-ed25519key, whose thumbprint is the example'skeyid:mainsignature_missingkeyidis not the key's thumbprintsignature_missingsignature_invalidSignature-Agentpresent but not coveredsignature_invalid(coverage)"@method";sfnext to the valid onesignature_missingThe third row is a coverage gap on
main: a signature that leaves the request'sSignature-Agentunsigned is accepted.Changes, the same in
rest/python/server/ucp_signing.pyandrest/nodejs/src/utils/signature.ts:Signature-Inputparser keeps each component'skeyparameter. A component with any other parameter, akeyon a derived component, or a repeatedkeymarks 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.(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).keyparameter, since akeybinds one Dictionary member and leaves the rest of the field unbound.required_components/requiredComponentsrequiresignature-agentwhen the header is present, and it may also be covered as;key="<label>"with the signature's own label, whichsignatures.mdbinds together.tag="web-bot-auth",keyidmust equal the RFC 7638 thumbprint of the resolved JWK (jwk_thumbprint/jwkThumbprint)."signature-agent";key="sig1"for such a component.buildSignatureBasein Node is generic over the component type, so existing callers are unchanged.createdandexpiresare not enforced; the spec leaves that to the application (L374-L379).Testing:
ucp_signing_test.pyandtest/signing.test.ts: RFC 7638 vectors (RFC 8037 A.3 and the spec'skeyid), Dictionary member serialization,keyparameter 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-agentsigned as another label's member, aktythat is not a key type name, the parser edge cases and an empty Dictionary item; each fails without the fix.pytest402 passed;ruff checkandruff format --checkclean (ruff 0.17.4). The new tests fail onmain.npm run build(tsc, which also type-checks the tests) andnpm test199 passed;prettier@4.0.0-alpha.8 --checkclean. Onmainthe test file does not load, since the new helpers do not exist there; run against themainverifier, the dual-audience and;sfcases answersignature_missing.Category (Required)
ucp-schematool (resolver, linter, validator). (Requires Maintainer approval)Related Issues
None.
Checklist
!for breaking changes).