feat(signing): ship signing/signingtest subpackage + ObserveOnly mode

[bokelley]

Policy-compliant relay of external contribution #479 so repository-default CodeQL can run. The original contributor remains the commit author; maintainer and Ladon reviews plus CI passed on #479.

Closes #53.

Summary

• adcp/v3/signing/signingtest — NewTestAgent(t) builds a matched Ed25519 *signing.Signer + signing.MiddlewareOptions (a fresh StaticJWKSResolver seeded with the signer's public key, a fresh NewMemoryReplayStore(0), no revocation). SignAndSend(t, signer, handler, req) signs req (with CoverContentDigest: true) and delivers it to handler in-process via httptest.NewRecorder, returning the *http.Response. Together these collapse the ~30-line keypair/JWK/resolver/replay-store pattern middleware_test.go currently hand-rolls into two lines of setup + one line to send.
• MiddlewareOptions.ObserveOnly bool — a real behavioral branch in Middleware(), not a passthrough field. When true, VerifyRequestSignature still runs; on failure the request is logged at slog.LevelInfo (vs the normal slog.LevelWarn) with an observe_only=true attribute and passed to next.ServeHTTP with no VerifiedSigner in its context — i.e., treated exactly as unsigned. On success, behavior is unchanged.

ObserveOnly ↔ spec mapping

This maps to the AdCP transport spec's warn_for rollout stop (supported_for → warn_for → required_for, see Transport capability advertisement). Per spec: "A missing signature or a well-formed signature that fails verification or body binding MUST NOT establish verified-signer identity ... A partial or malformed Signature / Signature-Input pair always hard-rejects."

ObserveOnly implements that split precisely, not just "log and let everything through":

• A well-formed signature that fails verification (bad crypto, unknown/revoked key, expired window, replay, wrong content-digest, an unsigned request to a RequiredFor op, ...) is observed: INFO log, request passes through unauthenticated.
• A partial or malformed Signature/Signature-Input header pair — one header present without the other, or either header present but unparseable (*Error{Code: CodeHeaderMalformed}) — still hard-rejects with 401 even under ObserveOnly, because the spec says it "cannot be safely interpreted as either signed or unsigned traffic."

adcp/v3/signing/MIGRATION.md's "Step B — warn_for" section previously described this exact mode as not yet landed, with an OnReject-based logs-and-passes-through shim as the interim workaround (and a "delete this before enabling RequiredFor" warning). This PR replaces that shim guidance with the real ObserveOnly API throughout the migration guide (bootstrap → step B → common pitfalls → pre-enforcement checklist).

Module note

This targets adcp/v3/signing, not adcp/signing. Per the repo's README.md "Modules & versioning" table and MIGRATING.md, adcp (the pre-v3 module) is frozen at v2.1.1 and receives security backports only — adcp/v3 is the actively developed module for AdCP 3.x. A new DX/feature package belongs there, so adcp/signing (the frozen copy) is untouched by this PR.

Testing

• signingtest's own tests (adcp/v3/signing/signingtest/signingtest_test.go) prove NewTestAgent + SignAndSend produce a request a real signing.Middleware-wrapped handler accepts (VerifiedSignerFromContext populated, correct algorithm), that the wired verifier is real and not a stub (rejects unsigned traffic on a RequiredFor op, rejects a replayed signature), and that SignAndSend fails fast on a non-absolute request URL (verified via a re-exec'd subprocess, since a subtest's t.Fatalf can't be observed without failing the parent test/package).
• middleware_test.go gets three new tests: ObserveOnly lets an unsigned request to a RequiredFor operation through (INFO log, no VerifiedSigner); ObserveOnly lets a well-formed-but-cryptographically-invalid signature through, with a matching ObserveOnly=false subtest proving the existing 401 behavior is unchanged; and ObserveOnly still hard-rejects a malformed Signature/Signature-Input pair (WARN log, 401, WWW-Authenticate: ... request_signature_header_malformed), proving the spec carve-out is real.
• go build ./..., go vet ./..., gofmt -l, and golangci-lint run ./signing/... are clean for every file this PR touches. The three staticcheck findings golangci-lint reports in adcp/v3/signing/jwk.go (deprecated ecdsa.PublicKey.X/.Y/.PrivateKey.D field access, Go 1.26) are pre-existing on main and untouched by this PR.
• go test ./... passes for both the adcp/v3 module (this change) and the root module (unaffected).

On item 5 of the issue ("refactor an existing boilerplate-heavy test as a demonstration")

I looked for one and came up empty, honestly reported: the request-signing profile's StaticJWKSResolver/NewMemoryReplayStore boilerplate pattern this issue targets appears nowhere else in the repo outside adcp/signing and adcp/v3/signing themselves. adcp/v3/webhook's test files (signing_test.go, publisher_test.go, e2e_test.go) use the webhook-signing profile via a different, already-existing dedicated helper (webhookKeypair) and a different verifier entry point (webhook.HTTPHandler, not signing.Middleware) — not a good refactor target for signingtest, which is scoped to the request-signing/signing.Middleware path the issue describes.

I also couldn't refactor adcp/v3/signing/middleware_test.go's own TestMiddlewareEndToEndSignAndVerify (the literal ~30-line pattern quoted in the issue) in place: that file is package signing (internal, white-box), and signingtest imports signing — importing signingtest from inside package signing would be a cyclic import. Instead, signingtest's own TestNewTestAgentSignAndSendRoundTrip reproduces the same scenario (sign, verify via middleware, assert on VerifiedSignerFromContext) using the new two-line + one-line helpers, as the concrete demonstration of the line-count reduction, and the package's README.md/doc.go cross-reference it for discoverability.

Test plan

• cd adcp/v3 && go build ./... && go vet ./... && go test ./...
• cd adcp/v3 && golangci-lint run ./signing/...
• go build ./... && go vet ./... && go test ./... at repo root (unaffected — confirms no accidental frozen-module edits)
• git status clean in the working tree aside from the files this PR touches

[aao-secretariat]

Ladon verdict: Approve

Approve — 1 medium finding, no blockers, no escalation triggers.

What I checked

• ObserveOnly shadow-mode signing branch (adcp/v3/signing/middleware.go): well-shaped and tested; does not weaken TMP signature verification, replay-window, or canonicalization semantics.
• tmproto SSRF URL validator (tmproto/urlsecurity.go, added): new file, thoroughly tested.
• Context-agent error sanitization (targeting/contextagent/handler.go): modification preserves contract; no medium-or-higher concern raised.
• Seller-agent newServer refactor + MCP tests: well-wired and covered.

Medium findings

• tmproto/urlsecurity.go — SSRF pre-flight's net.ParseIP gate misses non-canonical IPv4 literals (decimal/octal/hex). Mitigated for Go stdlib callers; a completeness gap for the canonical validator, not a load-bearing break.

Decision path

• Row 1: no critical/high findings.
• Row 2: gated_paths is false — not applicable.
• Row 3: no (deleted) reasons.
• Row 4: the single medium is a URL/SSRF validation gap, not data-loss/schema/infra category — not applicable.
• Row 5: high_risk is true with (modified) files, but this fires only if a finding is medium AND on a modified high-risk file. The SSRF medium is on tmproto/urlsecurity.go, which is (added), not (modified) — row 5 does not fire.
• Row 6: no prior escalation.
• Row 7: no no-auto-approve team match.
• Row 8: only 1 medium finding (need ≥3).
• Row 9: approve.

The high_risk flag is a heuristic; the only medium sits on a newly added file, and modified high-risk files carry no medium-or-higher concerns. Falls through to approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean, additive security hardening.

Reviewed the delta since the prior clean pass. This PR adds a DNS-free SSRF pre-flight validator (tmproto/urlsecurity.go) wired into Artifact/asset Validate() and reachable via ValidateContextRequest, fixes a context-agent err.Error() leak (now returns a generic response and logs server-side with an elided unsafe request_id), and extracts a seller-agent newServer() with new MCP-level and ForceAccountStatus tests. Verified IP-range masks/boundaries, non-echoing error text, and validator reachability; the extraction is a no-logic move.

No Critical/High/Medium findings.

Decision-table walk: rows 1 (no critical/high) and 4/5 (no medium) do not fire. gated_paths is false, so row 2 does not apply. high_risk is true but the only high-risk-path changes are (added) (new files — inherently low risk) or (modified) files with no medium-or-higher findings, so rows 3 and 5 do not fire. Prior decision was approve, so sticky escalation (row 6) does not apply. No no-auto-approve team match (row 7). Fewer than three medium findings (row 8). Falls through to row 9 → approve.

The merge-base changed after approval.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean pass, no blocking findings.

Checked:

• All changes confined to adcp/v3/signing/** — documentation (MIGRATION.md, README.md, doc.go), one additive MiddlewareOptions.ObserveOnly shadow-mode field in middleware.go, a new signingtest test-helper subpackage, and accompanying tests.
• No schema (adcp/schemas/**) or generated-type (adcp/types_gen.go) changes — coherence gate N/A.
• No tmproto/* signing/verification/replay/canonicalization/header changes; the ObserveOnly field is additive and the CodeHeaderMalformed carve-out fails closed (rejects more, not fewer). Default enforcement is byte-identical and regression-covered; no VerifiedSigner leaks under observe mode.
• No identity-agent TEE changes, no protocol-managed skills edits, no breaking wire/public-API removals — conventional-commit marker gate N/A.

Gates: gated_paths false, high_risk false, no no-auto-approve team match. Prior decision was approve. No critical/high/medium findings — falls through to row 9 (approve).