docs: add v0.6.0 release notes draft and README upgrade guide

Document jwx v4 migration, ML-DSA foreign JWS usage, and SignAlg/SetAllowedAlgs for v0.6.0 callers.

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

Author: yaronf

README.md

@@ -26,9 +26,39 @@ in the [API reference](https://pkg.go.dev/github.com/yaronf/httpsign).
 	serverText, _ := io.ReadAll(res.Body)
 	_ = res.Body.Close()
 ```
+
+### Upgrading from v0.5.x
+
+**v0.6.0** is a breaking release for foreign-JWS users and raises the Go floor to **1.27+**.
+
+| 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). |
+
+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`.
+
+Full migration notes: [internal-docs/RELEASE-v0.6.0.md](internal-docs/RELEASE-v0.6.0.md) (maintainers: paste **Summary** into the GitHub release).
+
+### 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`).
+
+**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).
+
+```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)
+```
+
+HMAC keys must be `[]byte` (minimum length per RFC 7518).
+
 ### Notes and Missing Features
 * Requires **Go 1.27+**.
-* Optional foreign JWS (including **ML-DSA** via `crypto/mldsa`) uses [`lestrrat-go/jwx/v4`](https://github.com/lestrrat-go/jwx) through `NewJWSSigner` / `NewJWSVerifier`.
 * The `Accept-Signature` header is unimplemented.
 * In responses, when using the "wrapped handler" feature, the `Content-Type` header is only signed if set explicitly by the server. This is different, but arguably more secure, than the normal `net.http` behavior.
 * **Behind a TLS-terminating reverse proxy:** The `@scheme` derived component defaults to `req.TLS != nil`. Behind nginx, Envoy, AWS ALB, etc., `req.TLS` is nil, so `@scheme` becomes `"http"` even for HTTPS traffic. Use `SetSchemeFromRequest` on `SignConfig` and `VerifyConfig` to derive the scheme from `X-Forwarded-Proto` or similar headers.

internal-docs/README.md

@@ -5,6 +5,7 @@ This directory contains internal documentation for maintainers of the httpsign l
 ## Contents
 
 - **JWX.md** — Optional jwx / foreign-JWS: cut over to jwx v4.4.0+ on Go 1.27+ as **httpsign `v0.6.0`**, with **ML-DSA PQ signatures** as an explicit goal. Gate met 2026-08-26.
+- **RELEASE-v0.6.0.md** — Draft GitHub release text and upgrade guide for **v0.6.0** (copy Summary into the release when tagging).
 
 ## Purpose
 

internal-docs/RELEASE-v0.6.0.md

@@ -0,0 +1,63 @@
+# Release notes draft: httpsign v0.6.0
+
+Copy the **Summary** section below into the GitHub release when tagging `v0.6.0`.
+
+---
+
+## Summary
+
+**Breaking release:** requires **Go 1.27+** and replaces dual `jwx/v2` + `jwx/v3` foreign-JWS support with a single **`github.com/lestrrat-go/jwx/v4`** dependency (≥ v4.4.0).
+
+### Highlights
+
+- **One foreign-JWS API:** `NewJWSSigner` / `NewJWSVerifier` only (`NewJWSSignerV3`, `NewJWSVerifierV3`, and the old v2-typed overloads are removed).
+- **Post-quantum (ML-DSA):** sign and verify HTTP messages with `crypto/mldsa` keys and `jwa.MLDSA44()` / `MLDSA65()` / `MLDSA87()` through the same constructors (Go 1.27 stdlib; no extra modules).
+- **Constructor hardening:** foreign JWS keys are validated at `NewJWS*` time (algorithm family, ECDSA curve bind per RFC 7518, HMAC minimum length, private key for signers / public key for verifiers). `jwa.NoSignature()` is rejected.
+- **Native algorithms unchanged** in API shape (HMAC-SHA256, RSA, RSA-PSS, P-256/P-384, Ed25519); only the Go toolchain floor moves to 1.27.
+
+### Upgrade from v0.5.x
+
+| You use | Action |
+|---------|--------|
+| **Native signers/verifiers only** | Bump Go to **1.27+** and upgrade httpsign. No API changes. |
+| **`NewJWSSignerV3` / `NewJWSVerifierV3`** | Rename to `NewJWSSigner` / `NewJWSVerifier`; change `github.com/lestrrat-go/jwx/v3/jwa` → `.../jwx/v4/jwa`. |
+| **`NewJWSSigner` / `NewJWSVerifier` (v2)** | Same as above: v4 import path and algorithm values (e.g. `jwa.ES256()`). |
+| **Foreign JWS signing** | Keep `SignConfig.SignAlg(false)` — RFC 9421 has no `alg` parameter for arbitrary JWS algorithms. |
+| **Foreign JWS verifying** | `VerifyConfig.SetAllowedAlgs` filters the HTTP **Signature** `alg` parameter if present; it does **not** select the JWS algorithm (that comes from `NewJWSVerifier`). |
+
+**jwx v4 algorithm values** are functions, not string constants:
+
+```go
+import "github.com/lestrrat-go/jwx/v4/jwa"
+
+signer, err := httpsign.NewJWSSigner(jwa.ES256(), privKey, config.SignAlg(false), fields)
+verifier, err := httpsign.NewJWSVerifier(jwa.ES256(), &privKey.PublicKey, verifyConfig, fields)
+```
+
+**ML-DSA example** (RFC 9421 does not register HTTP-sig algorithm names for ML-DSA; use foreign JWS with `SignAlg(false)`):
+
+```go
+priv, _ := mldsa.GenerateKey(mldsa.MLDSA65())
+pub := priv.Public().(*mldsa.PublicKey)
+config := httpsign.NewSignConfig().SignAlg(false)
+
+signer, _ := httpsign.NewJWSSigner(jwa.MLDSA65(), priv, config, fields)
+verifier, _ := httpsign.NewJWSVerifier(jwa.MLDSA65(), pub, httpsign.NewVerifyConfig(), fields)
+```
+
+HMAC keys for foreign JWS must be `[]byte` (not `string`), at least 32/48/64 bytes for HS256/384/512 per RFC 7518.
+
+### Toolchain
+
+- **Go:** 1.27.0+ (`encoding/json/v2` in stdlib; no `GOEXPERIMENT=jsonv2`).
+- **jwx:** v4.4.0+ only; v2 and v3 are no longer pulled transitively.
+
+### Upstream references
+
+- [jwx v4 MIGRATION.md](https://github.com/lestrrat-go/jwx/blob/v4.4.0/MIGRATION.md)
+- [jwx v4 Changes-v4.md](https://github.com/lestrrat-go/jwx/blob/v4.4.0/Changes-v4.md)
+
+### Also in v0.6.0 (non-breaking behavior fixes)
+
+- `SetVerifyDateWithin` now correctly reads the HTTP `Date` header (lowercase key in parsed messages).
+- Defensive checks for malformed ECDSA keys, empty header value lists, and nil client/signer/verifier config.