docs(ecdhkw): describe the migration from v0.1.0

Wrap and Unwrap now take the recipient's serialized protected header,
and the KEK derivation changed, so v0.1.0 callers have both an API and
a data migration ahead of them. Spell out the new call shape and say
plainly that old wraps cannot be unwrapped: the two derivations differ
and alg -31 covers both, so affected envelopes need decrypting with
v0.1.0 and re-encrypting.

Signed-off-by: Miroslav Bajtoš <oss@bajtos.net>
Assisted-by: Claude:claude-opus-5

Author: bajtos

README.md

@@ -351,7 +351,11 @@ recipient   = [ {1: alg}, {4: kid, ...}, wrappedKey ]           # alg -31 or -5
   as the info parameter: `AlgorithmID` −5 (A256KW), empty PartyU/PartyV,
   `keyDataLength` 256, and the recipient's serialized protected header
   `h'a101381e'`. JOSE derives ECDH-ES differently (RFC 7518 §4.6 uses the NIST
-  SP 800-56A single-step KDF); a KEK derived that way will not unwrap.
+  SP 800-56A single-step KDF); a KEK derived that way will not unwrap. v0.1.0
+  used the COSE Concat-KDF here, so envelopes it encrypted to X25519 recipients
+  need decrypting with v0.1.0 and re-encrypting with this version; see the
+  [`ecdhkw` package documentation](https://pkg.go.dev/github.com/filecoin-project/go-fee/ecdhkw)
+  for the API change that comes with it.
 
 ## Security notes
 

ecdhkw/ecdhkw.go

@@ -26,6 +26,30 @@
 // CEK as the recipient ciphertext, keyed by a kid) is the job of the
 // higher-level fee package. Keys are passed as crypto/ecdh values directly; any
 // custody or key-provider abstraction lives above this layer.
+//
+// # Migrating from v0.1.0
+//
+// v0.1.0 derived the KEK with the COSE Concat-KDF and took no protected header:
+// Wrap(recipientPub, cek) and Unwrap(recipientPriv, w). Both signatures now take
+// the serialized COSE_Recipient protected header as a trailing argument, and the
+// derivation is HKDF-SHA-256 as RFC 9053 §6.3.1 requires.
+//
+// Callers that build the recipient with the cose package pass the bytes that
+// package produces:
+//
+//	protected, err := cose.Headers{Protected: hdr}.ProtectedBytes()
+//	w, err := ecdhkw.Wrap(recipientPub, cek, protected)
+//
+// A recipient with an empty protected bucket takes a nil or zero-length slice,
+// which reproduces v0.1.0's context except for the KDF itself. On the unwrap
+// side, pass the recipient's protected bytes exactly as they arrived on the
+// wire; cose.Headers.ProtectedBytes returns those for a decoded envelope.
+//
+// Wraps written by v0.1.0 do not survive the change. The two derivations produce
+// different KEKs from the same ECDH secret, so Unwrap on an old wrap fails with
+// aeskw.ErrIntegrity, and nothing on the wire distinguishes the two: both use
+// alg -31. Envelopes encrypted to X25519 recipients under v0.1.0 have to be
+// decrypted with v0.1.0 and re-encrypted with this version.
 package ecdhkw
 
 import (