feat: locate signatures by tag via MessageDetails

Add MessageDetails.Label and Request/Response DetailsByTag (strict) and
DetailsListByTag (lenient) helpers with sentinel errors, example, and
v0.6.1 release notes.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: yaronf

internal-docs/RELEASE-v0.6.1.md

@@ -15,6 +15,7 @@ Copy the **Summary** section below into the GitHub release when tagging `v0.6.1`
 - **`JWSAlgAllowlist`:** both verify constructors take an allowlist (`nil` skips policy for tests/lazy use). Prefer a non-nil allowlist when `keyid` can select among keys.
 - **`NewJWSSigner`:** nil config defaults to `SignAlg(false)`; configs with `SignAlg(true)` are rejected.
 - **`Fields.AddRequestComponent`:** convenience for required associated-request components (`;req`), equivalent to `AddHeaderExt(name, false, false, true, false)`.
+- **Details by tag:** `RequestDetailsByTag` / `ResponseDetailsByTag` (strict) and `*DetailsListByTag` (lenient) locate signatures by the `tag` parameter; `MessageDetails.Label` holds the dictionary member name for `Verify*`. Sentinels: `ErrSignatureTagNotFound` / `ErrSignatureTagAmbiguous`.
 - **jwx** bump to **≥ v4.5.0** (if not already on the release branch).
 
 ### Upgrade from v0.6.0
@@ -26,6 +27,7 @@ Copy the **Summary** section below into the GitHub release when tagging `v0.6.1`
 | **`NewJWSSigner`** | Omit config or keep `SignAlg(false)`; `SignAlg(true)` now errors. |
 | **HTTP `SetAllowedAlgs`** | Unchanged — Signature-Input `alg` only, not JWS `jwa`. |
 | **Response `;req` fields** | Prefer `AddRequestComponent("@method")` (etc.) over `AddHeaderExt(..., false, false, true, false)`. |
+| **Locate signature by `tag`** | Prefer `RequestDetailsByTag` / `ResponseDetailsByTag`, then `Verify*` on `details.Label` (see below). |
 
 ```go
 allowed, _ := httpsign.NewJWSAlgAllowlist(jwa.ES256(), jwa.MLDSA65())
@@ -34,6 +36,17 @@ verifier, err := httpsign.NewJWSVerifier(allowed, pubKey, verifyConfig, fields)
 verifier, err := httpsign.NewJWSVerifierWithAlg(allowed, jwa.RS256(), rsaPub, verifyConfig, fields)
 ```
 
+**Details by tag** (when the dictionary label is not semantic):
+
+```go
+details, err := httpsign.RequestDetailsByTag(req, "app")
+if err != nil {
+	return err // includes ErrSignatureTagNotFound / ErrSignatureTagAmbiguous
+}
+// use details.KeyID to obtain verifier, then:
+err = httpsign.VerifyRequest(details.Label, *verifier, req)
+```
+
 **ML-DSA:**
 
 ```go

message.go

@@ -10,6 +10,7 @@ import (
 
 // MessageDetails aggregates the details of a signed message, for a given signature
 type MessageDetails struct {
+	Label        string  // Signature dictionary member name (the label in Signature / Signature-Input)
 	KeyID        *string // nil when keyid parameter is absent (RFC 9421 does not require it)
 	Alg          string
 	Fields       Fields
@@ -18,8 +19,8 @@ type MessageDetails struct {
 	Nonce        *string
 	Tag          *string
 	CustomParams map[string]interface{} // non-standard parameters; values are int64, string, or bool. Nil if none present.
-	// Note: when populated via RequestDetails/ResponseDetails, the message has not been cryptographically
-	// verified — treat CustomParams (and all other fields) as untrusted until verified.
+	// Note: when populated via RequestDetails/ResponseDetails (or *ByTag), the message has not been
+	// cryptographically verified — treat CustomParams (and all other fields) as untrusted until verified.
 }
 
 // Message represents a parsed HTTP message ready for signature verification.
@@ -223,5 +224,5 @@ func (m *Message) Verify(signatureName string, verifier Verifier) (*MessageDetai
 	if err != nil {
 		return nil, err
 	}
-	return signatureDetails(psiSig)
+	return signatureDetails(signatureName, psiSig)
 }

signatures.go

@@ -513,7 +513,7 @@ func RequestDetails(signatureName string, req *http.Request) (details *MessageDe
 	if err != nil {
 		return nil, fmt.Errorf("could not extract signature: %w", err)
 	}
-	return signatureDetails(psiSig)
+	return signatureDetails(signatureName, psiSig)
 }
 
 func verifyDebug(signatureName string, verifier Verifier, message *Message) (string, *psiSignature, error) {
@@ -571,7 +571,7 @@ func ResponseDetails(signatureName string, res *http.Response) (details *Message
 	if err != nil {
 		return nil, fmt.Errorf("could not extract signature: %w", err)
 	}
-	return signatureDetails(psiSig)
+	return signatureDetails(signatureName, psiSig)
 }
 
 // RequestSignatureNames returns the list of signature names present in a request (empty list if none found).
@@ -619,7 +619,7 @@ func messageSignatureNames(parsedMessage *parsedMessage, withTrailers bool) ([]s
 	return names, nil
 }
 
-func signatureDetails(signature *psiSignature) (details *MessageDetails, err error) {
+func signatureDetails(label string, signature *psiSignature) (details *MessageDetails, err error) {
 	var keyID *string
 	if keyIDParam, ok := signature.params["keyid"]; ok {
 		k, ok := keyIDParam.(string)
@@ -637,6 +637,7 @@ func signatureDetails(signature *psiSignature) (details *MessageDetails, err err
 		}
 	}
 	details = &MessageDetails{
+		Label:  label,
 		KeyID:  keyID,
 		Alg:    alg,
 		Fields: signature.fields,

signaturesex_test.go

@@ -3,6 +3,9 @@ package httpsign_test
 import (
 	"bufio"
 	"bytes"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
 	"fmt"
 	"net/http"
 	"strings"
@@ -45,3 +48,31 @@ Signature:       sig77=:3e9KqLP62NHfHY5OMG4036+U6tvBowZF35ALzTjpsf0=:
 	fmt.Printf("verified: %t", err == nil)
 	// Output: verified: true
 }
+
+func ExampleRequestDetailsByTag() {
+	priv, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	fields := httpsign.Headers("@authority", "Date", "@method")
+	reqStr := `GET /foo HTTP/1.1
+Host: example.org
+Date: Tue, 20 Apr 2021 02:07:55 GMT
+
+`
+	req, _ := http.ReadRequest(bufio.NewReader(strings.NewReader(reqStr)))
+
+	signer, _ := httpsign.NewP256Signer(*priv,
+		httpsign.NewSignConfig().SignCreated(false).SetTag("app").SetKeyID("key1"), fields)
+	sigInput, sig, _ := httpsign.SignRequest("sig1", *signer, req)
+	req.Header.Add("Signature-Input", sigInput)
+	req.Header.Add("Signature", sig)
+
+	details, err := httpsign.RequestDetailsByTag(req, "app")
+	if err != nil {
+		fmt.Printf("details: %v\n", err)
+		return
+	}
+	verifier, _ := httpsign.NewP256Verifier(priv.PublicKey,
+		httpsign.NewVerifyConfig().SetKeyID("key1").SetVerifyCreated(false), fields)
+	err = httpsign.VerifyRequest(details.Label, *verifier, req)
+	fmt.Printf("label=%s tag=%s verified=%t", details.Label, *details.Tag, err == nil)
+	// Output: label=sig1 tag=app verified=true
+}

signtag.go

@@ -0,0 +1,120 @@
+package httpsign
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+)
+
+// ErrSignatureTagNotFound is returned by *DetailsByTag when no signature
+// carries the requested tag parameter.
+var ErrSignatureTagNotFound = errors.New("no signature with the given tag")
+
+// ErrSignatureTagAmbiguous is returned by *DetailsByTag when more than one
+// signature carries the requested tag parameter.
+var ErrSignatureTagAmbiguous = errors.New("multiple signatures with the given tag")
+
+// RequestDetailsByTag returns MessageDetails for the unique Signature whose
+// Signature-Input tag equals tag. Matching uses parsed headers only (not trailers)
+// and does not cryptographically verify. Returns ErrSignatureTagNotFound or
+// ErrSignatureTagAmbiguous when the match count is not exactly one.
+// Use details.Label with VerifyRequest after obtaining a Verifier (e.g. via details.KeyID).
+func RequestDetailsByTag(req *http.Request, tag string) (*MessageDetails, error) {
+	if req == nil {
+		return nil, fmt.Errorf("nil request")
+	}
+	names, err := RequestSignatureNames(req, false)
+	if err != nil {
+		return nil, err
+	}
+	return detailsByTag(names, tag, func(name string) (*MessageDetails, error) {
+		return RequestDetails(name, req)
+	})
+}
+
+// ResponseDetailsByTag returns MessageDetails for the unique Signature whose
+// Signature-Input tag equals tag. Matching uses parsed headers only (not trailers)
+// and does not cryptographically verify. Returns ErrSignatureTagNotFound or
+// ErrSignatureTagAmbiguous when the match count is not exactly one.
+// Use details.Label with VerifyResponse after obtaining a Verifier (e.g. via details.KeyID).
+func ResponseDetailsByTag(res *http.Response, tag string) (*MessageDetails, error) {
+	if res == nil {
+		return nil, fmt.Errorf("nil response")
+	}
+	names, err := ResponseSignatureNames(res, false)
+	if err != nil {
+		return nil, err
+	}
+	return detailsByTag(names, tag, func(name string) (*MessageDetails, error) {
+		return ResponseDetails(name, res)
+	})
+}
+
+// RequestDetailsListByTag returns MessageDetails for every Signature whose
+// Signature-Input tag equals tag (possibly empty). Matching uses parsed headers
+// only (not trailers) and does not cryptographically verify. Each result has Label set.
+func RequestDetailsListByTag(req *http.Request, tag string) ([]*MessageDetails, error) {
+	if req == nil {
+		return nil, fmt.Errorf("nil request")
+	}
+	names, err := RequestSignatureNames(req, false)
+	if err != nil {
+		return nil, err
+	}
+	return detailsListByTag(names, tag, func(name string) (*MessageDetails, error) {
+		return RequestDetails(name, req)
+	})
+}
+
+// ResponseDetailsListByTag returns MessageDetails for every Signature whose
+// Signature-Input tag equals tag (possibly empty). Matching uses parsed headers
+// only (not trailers) and does not cryptographically verify. Each result has Label set.
+func ResponseDetailsListByTag(res *http.Response, tag string) ([]*MessageDetails, error) {
+	if res == nil {
+		return nil, fmt.Errorf("nil response")
+	}
+	names, err := ResponseSignatureNames(res, false)
+	if err != nil {
+		return nil, err
+	}
+	return detailsListByTag(names, tag, func(name string) (*MessageDetails, error) {
+		return ResponseDetails(name, res)
+	})
+}
+
+func detailsListByTag(names []string, tag string, detailsFn func(string) (*MessageDetails, error)) ([]*MessageDetails, error) {
+	var found []*MessageDetails
+	for _, name := range names {
+		details, err := detailsFn(name)
+		if err != nil {
+			return nil, fmt.Errorf("details for %q: %w", name, err)
+		}
+		if details.Tag != nil && *details.Tag == tag {
+			found = append(found, details)
+		}
+	}
+	return found, nil
+}
+
+func detailsByTag(names []string, tag string, detailsFn func(string) (*MessageDetails, error)) (*MessageDetails, error) {
+	var match *MessageDetails
+	n := 0
+	for _, name := range names {
+		details, err := detailsFn(name)
+		if err != nil {
+			return nil, fmt.Errorf("details for %q: %w", name, err)
+		}
+		if details.Tag == nil || *details.Tag != tag {
+			continue
+		}
+		n++
+		if n > 1 {
+			return nil, fmt.Errorf("%w: %q", ErrSignatureTagAmbiguous, tag)
+		}
+		match = details
+	}
+	if n == 0 {
+		return nil, fmt.Errorf("%w: %q", ErrSignatureTagNotFound, tag)
+	}
+	return match, nil
+}

signtag_test.go

@@ -0,0 +1,138 @@
+package httpsign
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestRequestDetailsByTag(t *testing.T) {
+	priv, _, err := genP256KeyPair()
+	require.NoError(t, err)
+	fields := *NewFields().AddHeader("@method")
+	req := readRequest(httpreq1)
+
+	signerA, err := NewP256Signer(*priv, NewSignConfig().SetTag("app").setFakeCreated(1618884475).SetKeyID("k1"), fields)
+	require.NoError(t, err)
+	inA, sigA, err := SignRequest("sig-a", *signerA, req)
+	require.NoError(t, err)
+	req.Header.Add("Signature-Input", inA)
+	req.Header.Add("Signature", sigA)
+
+	signerB, err := NewP256Signer(*priv, NewSignConfig().SetTag("other").setFakeCreated(1618884475).SetKeyID("k1"), fields)
+	require.NoError(t, err)
+	inB, sigB, err := SignRequest("sig-b", *signerB, req)
+	require.NoError(t, err)
+	req.Header.Add("Signature-Input", inB)
+	req.Header.Add("Signature", sigB)
+
+	t.Run("unique", func(t *testing.T) {
+		details, err := RequestDetailsByTag(req, "app")
+		require.NoError(t, err)
+		assert.Equal(t, "sig-a", details.Label)
+		require.NotNil(t, details.Tag)
+		assert.Equal(t, "app", *details.Tag)
+	})
+
+	t.Run("list", func(t *testing.T) {
+		list, err := RequestDetailsListByTag(req, "other")
+		require.NoError(t, err)
+		require.Len(t, list, 1)
+		assert.Equal(t, "sig-b", list[0].Label)
+		list, err = RequestDetailsListByTag(req, "missing")
+		require.NoError(t, err)
+		assert.Empty(t, list)
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		_, err := RequestDetailsByTag(req, "nope")
+		require.Error(t, err)
+		assert.True(t, errors.Is(err, ErrSignatureTagNotFound))
+	})
+
+	t.Run("ambiguous", func(t *testing.T) {
+		signerC, err := NewP256Signer(*priv, NewSignConfig().SetTag("app").setFakeCreated(1618884475).SetKeyID("k1"), fields)
+		require.NoError(t, err)
+		inC, sigC, err := SignRequest("sig-c", *signerC, req)
+		require.NoError(t, err)
+		req.Header.Add("Signature-Input", inC)
+		req.Header.Add("Signature", sigC)
+
+		_, err = RequestDetailsByTag(req, "app")
+		require.Error(t, err)
+		assert.True(t, errors.Is(err, ErrSignatureTagAmbiguous))
+
+		list, err := RequestDetailsListByTag(req, "app")
+		require.NoError(t, err)
+		require.Len(t, list, 2)
+		labels := []string{list[0].Label, list[1].Label}
+		assert.ElementsMatch(t, []string{"sig-a", "sig-c"}, labels)
+	})
+
+	t.Run("nil request", func(t *testing.T) {
+		_, err := RequestDetailsByTag(nil, "app")
+		require.Error(t, err)
+		_, err = RequestDetailsListByTag(nil, "app")
+		require.Error(t, err)
+	})
+}
+
+func TestResponseDetailsByTag(t *testing.T) {
+	priv, _, err := genP256KeyPair()
+	require.NoError(t, err)
+	fields := *NewFields().AddHeader("@status")
+	res := readResponse(httpres2)
+
+	signerA, err := NewP256Signer(*priv, NewSignConfig().SetTag("ctx1").setFakeCreated(1660755826).SetKeyID("k1"), fields)
+	require.NoError(t, err)
+	inA, sigA, err := SignResponse("sig1", *signerA, res, nil)
+	require.NoError(t, err)
+	res.Header.Add("Signature-Input", inA)
+	res.Header.Add("Signature", sigA)
+
+	signerB, err := NewP256Signer(*priv, NewSignConfig().SetTag("ctx2").setFakeCreated(1660755826).SetKeyID("k1"), fields)
+	require.NoError(t, err)
+	inB, sigB, err := SignResponse("sig2", *signerB, res, nil)
+	require.NoError(t, err)
+	res.Header.Add("Signature-Input", inB)
+	res.Header.Add("Signature", sigB)
+
+	details, err := ResponseDetailsByTag(res, "ctx2")
+	require.NoError(t, err)
+	assert.Equal(t, "sig2", details.Label)
+	require.NotNil(t, details.Tag)
+	assert.Equal(t, "ctx2", *details.Tag)
+
+	list, err := ResponseDetailsListByTag(res, "ctx1")
+	require.NoError(t, err)
+	require.Len(t, list, 1)
+	assert.Equal(t, "sig1", list[0].Label)
+
+	_, err = ResponseDetailsByTag(res, "missing")
+	require.Error(t, err)
+	assert.True(t, errors.Is(err, ErrSignatureTagNotFound))
+
+	_, err = ResponseDetailsByTag(nil, "ctx1")
+	require.Error(t, err)
+	_, err = ResponseDetailsListByTag(nil, "ctx1")
+	require.Error(t, err)
+}
+
+func TestRequestDetailsSetsLabel(t *testing.T) {
+	priv, _, err := genP256KeyPair()
+	require.NoError(t, err)
+	fields := *NewFields().AddHeader("@method")
+	req := readRequest(httpreq1)
+	signer, err := NewP256Signer(*priv, NewSignConfig().SetTag("app").setFakeCreated(1618884475).SetKeyID("k1"), fields)
+	require.NoError(t, err)
+	in, sig, err := SignRequest("mysig", *signer, req)
+	require.NoError(t, err)
+	req.Header.Add("Signature-Input", in)
+	req.Header.Add("Signature", sig)
+
+	details, err := RequestDetails("mysig", req)
+	require.NoError(t, err)
+	assert.Equal(t, "mysig", details.Label)
+}