Repository navigation
Description
Problem
When a signed request fails verification, the adopter gets a SignatureVerificationError with code, step and sometimes detail. That tells them which checklist step failed, but not why. They can't see the signature base we reconstructed, which covered component differed from what the signer used, or whether the content-digest, alg or keyid resolution was the culprit. Signature-base mismatches are the most common RFC 9421 integration failure, and today the only way to debug one is to add prints to canonical.py.
What exists
-
Python:
verify_request_signature(src/adcp/signing/verifier.py:228) andbuild_signature_base(src/adcp/signing/canonical.py:99). Correct and vector-tested, but they fail fast with an error code. -
JS (
@adcp/sdk):adcp grade request-signing <url>grades a verifier against the spec vectors.- The signer grader grades a signer.
adcp signing verify-vectorchecks a single vector.
All three grade an implementation. None of them explains an arbitrary captured request.
Proposal
A diagnostics function that runs every check to completion (no fast fail) and returns a structured report:
report = explain_request_signature(
method=..., url=..., headers=..., body=...,
jwks=... | jwks_uri=... | options=VerifyOptions(...),
expected_base: str | None = None, # optional: the signer's base, to diff against
)The report should include:
- the parsed
Signature-InputandSignaturefor each label - the reconstructed signature base, line by line, with the source value of each covered component (
@method,@target-uri,@authority, headers, …) - a line-level diff against
expected_basewhen one is supplied - the content-digest result: recomputed value vs. header value, and the algorithm
- alg / key checks: AdCP profile algs (
ed25519,ecdsa-p256-sha256), JWKalg/use/adcp_use, and keyid resolution created/expires/skew, nonce presence andtag- the final verdict, with the same spec error
codethe verifier would raise
It should sit next to the verifier and reuse the same canonicalization code, so the explanation and the verdict can't disagree. It must never log or return private key material.
On top of the function:
adcp signing explainCLI: takes a captured request (HAR / raw HTTP / JSON) and prints the report, or--json.- Addie can call the same function (or the JSON output) as the conversational front end.
- JS parity: ideally the same report shape in
@adcp/sdkso both SDKs explain failures the same way.
Why now
A third-party tool, adcp-test, just shipped a signing debugger that implementers are going to use. Its reconstruction has RFC 9421 bugs:
- it verifies ECDSA as DER instead of raw r‖s (§3.3.4), so it rejects valid ES256 signatures from our SDKs
- an empty
@querybecomes""instead of? - it lists unregistered algorithms
The UX is right. We should ship a correct version built on the verifier.
Acceptance
- Every rc.7 request-signing vector (positive and negative) produces a report whose verdict and
codematchverify_request_signature. - For each negative vector, the report points at the specific failing component or check.
- Unit tests for base diffing, content-digest mismatch, and unknown/mismatched keyid.
Activity
bokelley commentedon Sep 30, 2026
Triage
Classification: Feature request
Bucket(s): signing (label absent from repo — noted in run summary)
Status: ready-to-implement
What the experts said:
key_originsstep (step 7,request_signature_key_origin_mismatch/_missing); annotate ECDSA byte encoding as raw r‖s per RFC 9421 §3.3.2.My take: Cleanly additive feature with clear acceptance criteria; both experts approve the concept. The constraints below are design pre-conditions, not objections.
src/adcp/signing/explain.py:explain_request_signature()+SignatureDiagnosticReport. Single aggregateverdict/codeonly (no per-step crypto status); noreplay_storeparam (must never callclaim());key_originssection matching verifier step 7; JWK output scrubbed of private scalars (d,dp,dq,qi,p,q,k);is_authoritative: bool = Falseon return type; ECDSA annotated "64-byte raw r‖s per RFC 9421 §3.3.2". Export fromsigning/__init__.py.adcp signing explainCLI: Accept HAR / raw HTTP / JSON. Before processing: stripAuthorization,Cookie,Set-Cookie,X-Amz-*,X-Api-Key, andBearer/Basicvalue patterns; warn to stderr. Support--json.verify_request_signature; unit tests for base diffing, content-digest mismatch, keyid mismatch, nonce non-consumption, HAR credential scrubbing;is_authoritative=Falseassertion.verify_request_signatureor any existing public API. Docstring must state: pass report to an LLM only inside an untrusted-data fence (<untrusted_diagnostic_report>).Triaged by Claude Code. Session: https://claude.ai/code/session_01ELt9JSmSrzLNe1hNY2SKy4
Generated by Claude Code