Skip to content

feat(signing): explain a failing signed request (signature-base reconstruction + per-check diagnostics) #1267

Open

Description

@bokelley

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) and build_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-vector checks 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-Input and Signature for 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_base when 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), JWK alg/use/adcp_use, and keyid resolution
  • created/expires/skew, nonce presence and tag
  • the final verdict, with the same spec error code the 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 explain CLI: 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/sdk so 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 @query becomes "" 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 code match verify_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

  1. added
    enhancementNew feature or request
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 30, 2026
  2. bokelley commented on Sep 30, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Feature request
    Bucket(s): signing (label absent from repo — noted in run summary)
    Status: ready-to-implement

    What the experts said:

    • ad-tech-protocol-expert: Sound-with-caveats — explain path must never consume nonces (protocol side-effect); report must include AdCP-profile key_origins step (step 7, request_signature_key_origin_mismatch/_missing); annotate ECDSA byte encoding as raw r‖s per RFC 9421 §3.3.2.
    • security-reviewer: Needs-guardrails — two ship-blockers: (1) never expose step-10 crypto verdict independently of the full pipeline verdict (timing oracle enabling offline key-validity probing); (2) strip credential-bearing headers from HAR input before processing. Also: scrub JWK private-key scalars from report output; fence report as untrusted data before LLM injection; mark return type as non-authoritative.

    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 aggregate verdict/code only (no per-step crypto status); no replay_store param (must never call claim()); key_origins section matching verifier step 7; JWK output scrubbed of private scalars (d, dp, dq, qi, p, q, k); is_authoritative: bool = False on return type; ECDSA annotated "64-byte raw r‖s per RFC 9421 §3.3.2". Export from signing/__init__.py.
    • adcp signing explain CLI: Accept HAR / raw HTTP / JSON. Before processing: strip Authorization, Cookie, Set-Cookie, X-Amz-*, X-Api-Key, and Bearer/Basic value patterns; warn to stderr. Support --json.
    • Tests: All rc.7 vectors produce verdict + code matching verify_request_signature; unit tests for base diffing, content-digest mismatch, keyid mismatch, nonce non-consumption, HAR credential scrubbing; is_authoritative=False assertion.
    • Non-breaking: No edits to verify_request_signature or 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

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions