v0.6.1: foreign-JWS allowlist, DetailsByTag, AddRequestComponent, SignerFromJWK (#25)

* deps: bump lestrrat-go/jwx/v4 to v4.5.0

Update the foreign-JWS dependency and docs that pinned the previous floor.

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

* docs: add foreign-JWS algorithm policy plan

Capture the agreed allowlist + infer-alg NewJWSVerifier design for v0.6.x so it is not lost before implementation.

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

* feat: foreign-JWS allowlist, infer-alg verify, registry-only algs

Break NewJWSVerifier into infer vs WithAlg with JWSAlgAllowlist policy,
require SignAlg(false) on NewJWSSigner, and resolve algs via the jwx
registry so handcrafted none/unknown names cannot bypass hardening.

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

* fix: satisfy lint on JWK public-key export asserts

Use comma-ok type assertions for ML-DSA/Ed25519 Public() results and
avoid deprecated ecdsa.PublicKey X/Y fields in nil-curve tests.

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

* 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>

* 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>

* refactor: single-pass Signature-Input walk for DetailsByTag

Build all MessageDetails from headers once instead of listing labels
and re-parsing per name; share psiSignatureFromInnerList with parse path.

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

* test: broaden ByTag and signatureDetailsListFromHeaders coverage

Cover response ambiguity, multi-tag/combined headers, missing Signature
members, and nil/empty/malformed SFV edge cases.

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

* fix: treat EdDSA and Ed25519 as equivalent for JWK infer

Map OKP crv Ed25519 to RFC 9864 EdDSAEd25519, and accept legacy JWK
alg "EdDSA" (and matching allowlist entries) as the same crypto.

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

* test: fuzz foreign JWS sign/verify, infer, and ML-DSA

Add dedicated fuzz targets for ES256 and ML-DSA-44 round-trips,
Signature-header panic hunting, JWK inference, and constructor alg checks.

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

* feat: add NewJWSSignerFromJWK for private JWK signing

Infer alg from a private jwk.Key (same rules as verify), export raw
private material, and construct a foreign JWS signer. Closes #24.

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

* fix: disambiguate fuzz target names for CI -fuzz regexp

Rename FuzzVerifyRequestJWS to FuzzJWSVerifyRequest so it is not a
substring of FuzzVerifyRequest, and anchor CI/local -fuzz patterns.

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

---------

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

Author: yaronf

.github/workflows/test.yml

@@ -29,11 +29,23 @@ jobs:
           go-version: '1.27'
           cache: false
       - name: Fuzz smoke
-        # Short per-target budget (~75s total). See internal-docs/FUZZ.md.
+        # Short per-target budget. -fuzz is a regexp — use ^Name$ so names are not
+        # substrings of each other (see internal-docs/FUZZ.md).
         run: |
           set -euo pipefail
-          for target in FuzzVerifyRequest FuzzVerifyViaMessage FuzzSignAndVerifyHMAC FuzzHMACViaMessage FuzzNewMessage; do
+          for target in \
+            FuzzVerifyRequest \
+            FuzzVerifyViaMessage \
+            FuzzSignAndVerifyHMAC \
+            FuzzHMACViaMessage \
+            FuzzNewMessage \
+            FuzzSignAndVerifyJWS \
+            FuzzJWSVerifyRequest \
+            FuzzSignAndVerifyMLDSA \
+            FuzzInferJWSVerifier \
+            FuzzNewJWSConstructors
+          do
             echo "::group::fuzz $target"
-            go test -run='^$' -fuzz="$target" -fuzztime=15s .
+            go test -run='^$' -fuzz="^${target}$" -fuzztime=15s .
             echo "::endgroup::"
           done

.gitignore

@@ -3,6 +3,11 @@
 /.idea/inspectionProfiles/Project_Default.xml
 /.idea/copilot.data.migration.*.xml
 /testdata/fuzz/FuzzSignAndVerifyHMAC/
+/testdata/fuzz/FuzzSignAndVerifyJWS/
+/testdata/fuzz/FuzzJWSVerifyRequest/
+/testdata/fuzz/FuzzSignAndVerifyMLDSA/
+/testdata/fuzz/FuzzInferJWSVerifier/
+/testdata/fuzz/FuzzNewJWSConstructors/
 
 .vscode/
 coverage.out

CLAUDE.md

@@ -44,15 +44,16 @@ fields.go / digest.go      ← Component field abstraction + Content-Digest head
 ### Key types
 
 - **`Signer` / `Verifier`** (`crypto.go`) — hold algorithm, key, and signing config. Created via `NewXxxSigner` / `NewXxxVerifier` constructors (HMAC-SHA256, RSA, RSA-PSS, P-256, P-384, Ed25519, JWS).
-- Foreign JWS key↔alg checks live in **`jwskey.go`** (explicit stdlib types; does not use deprecated `jws.AlgorithmsForKey`).
+- Foreign JWS key↔alg checks live in **`jwskey.go`** / **`jwsinfer.go`** (explicit stdlib types + JWK/ECDSA/ML-DSA alg inference; does not use deprecated `jws.AlgorithmsForKey`).
 - **`SignConfig` / `VerifyConfig`** (`config.go`) — builder-style configuration for signature metadata (keyID, nonce, tag, expiry, clock tolerance). Constructed via `NewSignConfig()` / `NewVerifyConfig()` with method chaining.
+- **`JWSAlgAllowlist`** (`jwsallow.go`) — foreign-verify alg policy for `NewJWSVerifier` / `NewJWSVerifierWithAlg` (`nil` = no policy).
 - **`Fields`** (`fields.go`) — specifies which HTTP components (headers, derived components) to include in the signature. Use the `Fields("header1", "@method", ...)` helper or `NewFields()` for complex cases.
 - **`Message` / `MessageDetails`** (`message.go`) — internal canonicalized request/response representation. `MessageDetails` is the public output of `RequestDetails` / `ResponseDetails`.
 - **`HandlerConfig` / `ClientConfig`** (`config.go`) — configures server-side and client-side HTTP wrappers.
 
 ### JWX dual-version support
 
-Optional foreign JWS uses `lestrrat-go/jwx/v4` via `NewJWSSigner` / `NewJWSVerifier` (including ML-DSA with `crypto/mldsa` on Go 1.27+). Requires Go 1.27+.
+Optional foreign JWS uses `lestrrat-go/jwx/v4` via `NewJWSSigner` / `NewJWSSignerFromJWK` / `NewJWSVerifier` (infer) / `NewJWSVerifierWithAlg` (including ML-DSA with `crypto/mldsa` on Go 1.27+). Requires Go 1.27+.
 
 ### Content-Digest
 

README.md

@@ -27,35 +27,37 @@ in the [API reference](https://pkg.go.dev/github.com/yaronf/httpsign).
 	_ = res.Body.Close()
 ```
 
-### Upgrading from v0.5.x
+### Upgrading
 
-**v0.6.0** is a breaking release for foreign-JWS users and raises the Go floor to **1.27+**.
+**v0.6.0** (shipped) raised the Go floor to **1.27+** and cut foreign JWS over to **jwx v4** + ML-DSA. See [internal-docs/RELEASE-v0.6.0.md](internal-docs/RELEASE-v0.6.0.md).
 
-| Caller | Change |
-|--------|--------|
-| Native algorithms only (RSA, ECDSA, Ed25519, HMAC) | Upgrade Go to 1.27+; no API changes. |
-| `NewJWSSignerV3` / `NewJWSVerifierV3` | Use `NewJWSSigner` / `NewJWSVerifier` with `github.com/lestrrat-go/jwx/v4/jwa`. |
-| `NewJWSSigner` / `NewJWSVerifier` (jwx v2) | Same: v4 import path; algorithms are functions (`jwa.ES256()`, not string constants). |
+**v0.6.1** breaks foreign-JWS **verify** again: prefer `NewJWSVerifier(allowed, key, …)` (infer alg); use `NewJWSVerifierWithAlg` when needed; pass a `JWSAlgAllowlist` (`nil` skips policy). `NewJWSSigner` defaults to / requires `SignAlg(false)`; use `NewJWSSignerFromJWK` when the private key is a JWK.
 
-Foreign JWS signing must use `SignConfig.SignAlg(false)` — RFC 9421 does not define an HTTP `alg` value for arbitrary JWS algorithms. Verification policy `SetAllowedAlgs` applies to the optional HTTP `alg` signature parameter in the message, not to the JWS algorithm passed to `NewJWSVerifier`.
+| Caller | Change in v0.6.1 |
+|--------|------------------|
+| Native algorithms only | None. |
+| `NewJWSVerifier(alg, key, …)` (v0.6.0) | Prefer `NewJWSVerifier(allowed, key, …)`; else `NewJWSVerifierWithAlg(allowed, alg, key, …)`. |
+| `NewJWSSigner` | Nil config ⇒ `SignAlg(false)`; `SignAlg(true)` errors. Prefer `NewJWSSignerFromJWK` for private JWKs. |
 
-Full migration notes: [internal-docs/RELEASE-v0.6.0.md](internal-docs/RELEASE-v0.6.0.md) (maintainers: paste **Summary** into the GitHub release).
+Pass a non-nil allowlist when `keyid` can select among keys. `SetAllowedAlgs` still only filters Signature-Input `alg`, not JWS `jwa`.
+
+Full notes: [internal-docs/RELEASE-v0.6.1.md](internal-docs/RELEASE-v0.6.1.md).
 
 ### Foreign JWS and ML-DSA
 
-Optional algorithms beyond the native set use [`lestrrat-go/jwx/v4`](https://github.com/lestrrat-go/jwx) (≥ v4.4.0) via `NewJWSSigner` / `NewJWSVerifier`. Requires **Go 1.27+** (stdlib `encoding/json/v2`; no `GOEXPERIMENT`).
+Optional algorithms beyond the native set use [`lestrrat-go/jwx/v4`](https://github.com/lestrrat-go/jwx) (≥ v4.5.0) via `NewJWSSigner` / `NewJWSSignerFromJWK` / `NewJWSVerifier`.
 
-**ML-DSA (FIPS 204)** is supported through the same constructors with `crypto/mldsa` keys and `jwa.MLDSA44()` / `MLDSA65()` / `MLDSA87()`. RFC 9421 does not assign HTTP Message Signatures algorithm identifiers for ML-DSA; treat it like other foreign JWS algorithms (`SignAlg(false)`, JWS `alg` in the JWS layer only if your profile requires it).
+**ML-DSA (FIPS 204)** works through the same path with `crypto/mldsa` keys. Prefer inferring the alg from the public key:
 
 ```go
 priv, _ := mldsa.GenerateKey(mldsa.MLDSA65())
 pub := priv.Public().(*mldsa.PublicKey)
-signer, _ := httpsign.NewJWSSigner(jwa.MLDSA65(), priv,
-    httpsign.NewSignConfig().SignAlg(false), fields)
-verifier, _ := httpsign.NewJWSVerifier(jwa.MLDSA65(), pub, httpsign.NewVerifyConfig(), fields)
+signer, _ := httpsign.NewJWSSigner(jwa.MLDSA65(), priv, nil, fields) // SignAlg(false) by default
+allowed, _ := httpsign.NewJWSAlgAllowlist(jwa.MLDSA65())
+verifier, _ := httpsign.NewJWSVerifier(allowed, pub, httpsign.NewVerifyConfig(), fields)
 ```
 
-HMAC keys must be `[]byte` (minimum length per RFC 7518).
+HMAC keys must be `[]byte` (minimum length per RFC 7518). Raw RSA verify needs `NewJWSVerifierWithAlg` (or a JWK that carries `alg`).
 
 ### Notes and Missing Features
 * Requires **Go 1.27+**.

config.go

@@ -43,8 +43,8 @@ func NewSignConfig() *SignConfig {
 	}
 }
 
-// SignAlg indicates that an "alg" signature parameter must be generated and signed (default: true).
-// Must be false when using NewJWSSigner (foreign JWS has no HTTP Message Signatures algorithm id).
+// SignAlg indicates that an "alg" signature parameter must be generated and signed (default: true for native signers).
+// NewJWSSigner rejects SignAlg(true) and defaults nil configs to SignAlg(false).
 func (c *SignConfig) SignAlg(b bool) *SignConfig {
 	c.signAlg = b
 	return c

crypto.go

@@ -14,6 +14,7 @@ import (
 	"fmt"
 
 	"github.com/lestrrat-go/jwx/v4/jwa"
+	"github.com/lestrrat-go/jwx/v4/jwk"
 	"github.com/lestrrat-go/jwx/v4/jws"
 )
 
@@ -129,19 +130,27 @@ func NewEd25519SignerFromSeed(seed []byte, config *SignConfig, fields Fields) (*
 // NewJWSSigner creates a generic signer for JWS algorithms via github.com/lestrrat-go/jwx/v4.
 // The particular key type for each algorithm is documented in that package (including
 // crypto/mldsa keys for ML-DSA on Go 1.27+). HMAC keys must be []byte (not string).
-// Config may be nil for a default configuration; SignAlg must be false (see SignConfig.SignAlg).
-func NewJWSSigner(alg jwa.SignatureAlgorithm, key interface{}, config *SignConfig, fields Fields) (*Signer, error) {
+// Do not pass jwk.Key here — use NewJWSSignerFromJWK so alg can be taken from the JWK.
+// Config may be nil (defaults with SignAlg(false)). A non-nil config that would emit
+// HTTP Signature-Input "alg" is rejected — foreign JWS has no RFC 9421 algorithm id.
+func NewJWSSigner(alg jwa.SignatureAlgorithm, key any, config *SignConfig, fields Fields) (*Signer, error) {
 	if key == nil {
 		return nil, fmt.Errorf("key must not be nil")
 	}
-	if alg == jwa.NoSignature() {
-		return nil, fmt.Errorf("the NONE signing algorithm is expressly disallowed")
+	if err := rejectJWKKeyForSigner(key); err != nil {
+		return nil, err
+	}
+	alg, err := resolveRegisteredJWSAlg(alg)
+	if err != nil {
+		return nil, err
 	}
 	if err := validateJWSKeyAlg(alg, key, true); err != nil {
 		return nil, err
 	}
 	if config == nil {
-		config = NewSignConfig()
+		config = NewSignConfig().SignAlg(false)
+	} else if config.signAlg {
+		return nil, fmt.Errorf("NewJWSSigner requires SignAlg(false): foreign JWS has no HTTP Message Signatures algorithm identifier")
 	}
 	jwsSigner, err := jws.SignerFor(alg)
 	if err != nil {
@@ -156,6 +165,18 @@ func NewJWSSigner(alg jwa.SignatureAlgorithm, key interface{}, config *SignConfi
 	}, nil
 }
 
+// NewJWSSignerFromJWK creates a foreign-JWS signer by inferring the algorithm from a private jwk.Key
+// (JWK alg and/or unambiguous crv), then exporting raw private key material. Preferred when keys
+// are stored as JWKs (e.g. WIMSE WIT cnf.jwk). Public-only JWKs are rejected.
+// Config may be nil (defaults with SignAlg(false)); SignAlg(true) is rejected as for NewJWSSigner.
+func NewJWSSignerFromJWK(key jwk.Key, config *SignConfig, fields Fields) (*Signer, error) {
+	alg, raw, err := inferJWSSignerKeyFromJWK(key)
+	if err != nil {
+		return nil, err
+	}
+	return NewJWSSigner(alg, raw, config, fields)
+}
+
 func (s Signer) sign(buff []byte) ([]byte, error) {
 	if s.foreignSigner != nil {
 		signer, ok := s.foreignSigner.(jws.Signer)
@@ -327,17 +348,41 @@ func NewEd25519Verifier(key ed25519.PublicKey, config *VerifyConfig, fields Fiel
 	}, nil
 }
 
-// NewJWSVerifier creates a generic verifier for JWS algorithms via github.com/lestrrat-go/jwx/v4.
-// The particular key type for each algorithm is documented in that package (including
-// crypto/mldsa keys for ML-DSA on Go 1.27+). HMAC keys must be []byte (not string).
-// Set config to nil for a default configuration.
-// Fields is the list of required headers and fields, which may be empty (but this is typically insecure).
-func NewJWSVerifier(alg jwa.SignatureAlgorithm, key interface{}, config *VerifyConfig, fields Fields) (*Verifier, error) {
+// NewJWSVerifier creates a foreign-JWS verifier by inferring the JWS algorithm from key.
+// Preferred over NewJWSVerifierWithAlg when the key type uniquely determines the alg.
+//
+// Allowed key types:
+//   - jwk.Key with alg, or EC/OKP with unambiguous crv (P-256→ES256, …, Ed25519→EdDSAEd25519; legacy JWK alg "EdDSA" also accepted)
+//   - *ecdsa.PublicKey (curve → ES256/384/512)
+//   - *mldsa.PublicKey (Parameters → ML-DSA-44/65/87)
+//
+// Raw RSA/HMAC keys cannot be inferred — use NewJWSVerifierWithAlg.
+// allowed may be nil to skip alg policy; prefer a non-nil allowlist when keyid can select keys.
+func NewJWSVerifier(allowed *JWSAlgAllowlist, key any, config *VerifyConfig, fields Fields) (*Verifier, error) {
+	alg, raw, err := inferJWSVerifierKey(key)
+	if err != nil {
+		return nil, err
+	}
+	return NewJWSVerifierWithAlg(allowed, alg, raw, config, fields)
+}
+
+// NewJWSVerifierWithAlg creates a foreign-JWS verifier for an explicit JWS algorithm.
+// Use when the algorithm cannot be inferred (raw RSA/HMAC) or the store already chose alg.
+// Do not pass jwk.Key here — use NewJWSVerifier so alg can be taken from the JWK.
+// allowed may be nil to skip alg policy.
+func NewJWSVerifierWithAlg(allowed *JWSAlgAllowlist, alg jwa.SignatureAlgorithm, key any, config *VerifyConfig, fields Fields) (*Verifier, error) {
 	if key == nil {
 		return nil, fmt.Errorf("key must not be nil")
 	}
-	if alg == jwa.NoSignature() {
-		return nil, fmt.Errorf("the NONE signing algorithm is expressly disallowed")
+	if err := rejectJWKKey(key); err != nil {
+		return nil, err
+	}
+	alg, err := resolveRegisteredJWSAlg(alg)
+	if err != nil {
+		return nil, err
+	}
+	if err := checkJWSAlgAllowed(allowed, alg); err != nil {
+		return nil, err
 	}
 	if err := validateJWSKeyAlg(alg, key, false); err != nil {
 		return nil, err