feat: add Fields.AddRequestComponent for ;req bindings

Convenience wrapper for required associated-request components, with
tests and a v0.6.1 release-notes mention.

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

Author: yaronf

fields.go

@@ -131,6 +131,13 @@ func (fs *Fields) AddHeaderOptional(hdr string) *Fields {
 	return fs.AddHeaderExt(hdr, true, false, false, false)
 }
 
+// AddRequestComponent appends a required component from the associated request (sets ;req).
+// Equivalent to AddHeaderExt(name, false, false, true, false). Typical for response signatures
+// that bind derived components such as @method, @path, or @query from the request (RFC 9421 §2.2).
+func (fs *Fields) AddRequestComponent(name string) *Fields {
+	return fs.AddHeaderExt(name, false, false, true, false)
+}
+
 func fromQueryParam(qp string) *field {
 	i := httpsfv.NewItem("@query-param")
 	i.Params.Add("name", QueryEscapeForSignature(qp))

fields_test.go

@@ -1,9 +1,11 @@
 package httpsign
 
 import (
+	"testing"
+
 	"github.com/dunglas/httpsfv"
 	"github.com/stretchr/testify/assert"
-	"testing"
+	"github.com/stretchr/testify/require"
 )
 
 func TestFields_asSignatureInput(t *testing.T) {
@@ -80,6 +82,12 @@ func TestFields_hasHeader(t *testing.T) {
 			header: "Content-Digest",
 			want:   true,
 		},
+		{
+			name:   "associated-request component via AddRequestComponent",
+			fields: NewFields().AddRequestComponent("@method"),
+			header: "@method",
+			want:   true,
+		},
 		{
 			name:   "header not in fields",
 			fields: NewFields().AddHeaders("content-type"),
@@ -101,6 +109,25 @@ func TestFields_hasHeader(t *testing.T) {
 	}
 }
 
+func TestAddRequestComponent(t *testing.T) {
+	got := NewFields().AddRequestComponent("@method").AddRequestComponent("@path")
+	want := NewFields().
+		AddHeaderExt("@method", false, false, true, false).
+		AddHeaderExt("@path", false, false, true, false)
+	require.Equal(t, len(want.f), len(got.f))
+	for i := range got.f {
+		assert.True(t, got.f[i].Equal(want.f[i]), "field %d: got %s want %s", i, got.f[i], want.f[i])
+		req, err := got.f[i].associatedRequest()
+		require.NoError(t, err)
+		assert.True(t, req)
+		opt, err := got.f[i].optional()
+		require.NoError(t, err)
+		assert.False(t, opt)
+	}
+	assert.Equal(t, `"@method";req`, got.f[0].String())
+	assert.Equal(t, `"@path";req`, got.f[1].String())
+}
+
 func Test_field_String(t *testing.T) {
 	tests := []struct {
 		name string

internal-docs/RELEASE-v0.6.1.md

@@ -14,6 +14,7 @@ Copy the **Summary** section below into the GitHub release when tagging `v0.6.1`
 - **Escape hatch:** `NewJWSVerifierWithAlg(allowed, alg, key, …)` when alg cannot be inferred (raw RSA/HMAC) or the store already chose alg. Today’s `NewJWSVerifier(alg, key, …)` migrates here.
 - **`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)`.
 - **jwx** bump to **≥ v4.5.0** (if not already on the release branch).
 
 ### Upgrade from v0.6.0
@@ -24,6 +25,7 @@ Copy the **Summary** section below into the GitHub release when tagging `v0.6.1`
 | **`NewJWSVerifier(alg, key, …)`** | Prefer `NewJWSVerifier(allowed, key, …)` when the key is inferrable; else `NewJWSVerifierWithAlg(allowed, alg, key, …)`. |
 | **`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)`. |
 
 ```go
 allowed, _ := httpsign.NewJWSAlgAllowlist(jwa.ES256(), jwa.MLDSA65())

signatures_test.go

@@ -2036,7 +2036,7 @@ func TestSignResponseNilRequestWhenAssocFieldsRequired(t *testing.T) {
 	priv, pub, err := genP256KeyPair()
 	assert.NoError(t, err)
 	fields := *NewFields().AddHeaders("@status", "date").
-		AddHeaderExt("@authority", false, false, true, false) // requires associated request
+		AddRequestComponent("@authority") // requires associated request
 	signer, err := NewP256Signer(*priv, NewSignConfig().SetKeyID("key"), fields)
 	assert.NoError(t, err)
 	res := readResponse(httpres2)
@@ -3221,10 +3221,10 @@ func TestRequestBinding17(t *testing.T) {
 	pubKey2, err := parseECPublicKeyFromPemStr(p256PubKey2)
 	assert.NoError(t, err, "read pub key")
 	fields2 := *NewFields().AddHeaders("@status", "content-digest", "content-type").
-		AddHeaderExt("@authority", false, false, true, false).
-		AddHeaderExt("@method", false, false, true, false).
-		AddHeaderExt("@path", false, false, true, false).
-		AddHeaderExt("content-digest", false, false, true, false)
+		AddRequestComponent("@authority").
+		AddRequestComponent("@method").
+		AddRequestComponent("@path").
+		AddRequestComponent("content-digest")
 	verifier2, err := NewP256Verifier(*pubKey2, NewVerifyConfig().SetVerifyCreated(false).SetKeyID("test-key-ecc-p256"), fields2)
 	assert.NoError(t, err, "create verifier")
 	sigBase, err := verifyResponseDebug("reqres", *verifier2, res, req)
@@ -3257,10 +3257,10 @@ func TestMessageRequestBinding17(t *testing.T) {
 	pubKey2, err := parseECPublicKeyFromPemStr(p256PubKey2)
 	assert.NoError(t, err, "read pub key")
 	fields2 := *NewFields().AddHeaders("@status", "content-digest", "content-type").
-		AddHeaderExt("@authority", false, false, true, false).
-		AddHeaderExt("@method", false, false, true, false).
-		AddHeaderExt("@path", false, false, true, false).
-		AddHeaderExt("content-digest", false, false, true, false)
+		AddRequestComponent("@authority").
+		AddRequestComponent("@method").
+		AddRequestComponent("@path").
+		AddRequestComponent("content-digest")
 	verifier2, err := NewP256Verifier(*pubKey2, NewVerifyConfig().SetVerifyCreated(false).SetKeyID("test-key-ecc-p256"), fields2)
 	assert.NoError(t, err, "create verifier")
 	sigBase, _, err := verifyDebug("reqres", *verifier2, msg)
@@ -3393,11 +3393,11 @@ func TestRequestBindingSignedResponse17(t *testing.T) {
 	pubKey2, err := parseECPublicKeyFromPemStr(p256PubKey2)
 	assert.NoError(t, err, "read pub key")
 	fields2 := *NewFields().AddHeaders("@status", "content-digest", "content-type").
-		AddHeaderExt("@authority", false, false, true, false).
-		AddHeaderExt("@method", false, false, true, false).
-		AddHeaderExt("@path", false, false, true, false).
-		AddHeaderExt("@query", false, false, true, false).
-		AddHeaderExt("content-digest", false, false, true, false)
+		AddRequestComponent("@authority").
+		AddRequestComponent("@method").
+		AddRequestComponent("@path").
+		AddRequestComponent("@query").
+		AddRequestComponent("content-digest")
 	verifier2, err := NewP256Verifier(*pubKey2, NewVerifyConfig().SetVerifyCreated(false).SetKeyID("test-key-ecc-p256"), fields2)
 	assert.NoError(t, err, "create verifier")
 	sigBase, err := verifyResponseDebug("reqres", *verifier2, res, req)
@@ -3521,11 +3521,11 @@ func TestMessageRequestBindingSignedResponse17(t *testing.T) {
 	pubKey2, err := parseECPublicKeyFromPemStr(p256PubKey2)
 	assert.NoError(t, err, "read pub key")
 	fields2 := *NewFields().AddHeaders("@status", "content-digest", "content-type").
-		AddHeaderExt("@authority", false, false, true, false).
-		AddHeaderExt("@method", false, false, true, false).
-		AddHeaderExt("@path", false, false, true, false).
-		AddHeaderExt("@query", false, false, true, false).
-		AddHeaderExt("content-digest", false, false, true, false)
+		AddRequestComponent("@authority").
+		AddRequestComponent("@method").
+		AddRequestComponent("@path").
+		AddRequestComponent("@query").
+		AddRequestComponent("content-digest")
 	verifier2, err := NewP256Verifier(*pubKey2, NewVerifyConfig().SetVerifyCreated(false).SetKeyID("test-key-ecc-p256"), fields2)
 	assert.NoError(t, err, "create verifier")
 	sigBase, _, err := verifyDebug("reqres", *verifier2, msg)