autodoc updates

docs/01-jwt.md

@@ -371,7 +371,7 @@ func ExampleJWT_ParseWithKeySet() {
       return
     }
     // This is the key we will use to sign
-    realKey, err := jwk.New(privKey)
+    realKey, err := jwk.FromRaw(privKey)
     if err != nil {
       fmt.Printf("failed to create JWK: %s\n", err)
       return
@@ -380,7 +380,11 @@ func ExampleJWT_ParseWithKeySet() {
     realKey.Set(jwk.AlgorithmKey, jwa.RS256)
 
     // For demonstration purposes, we also create a bogus key
-    bogusKey := jwk.NewSymmetricKey()
+    bogusKey, err := jwk.FromRaw([]byte("bogus"))
+    if err != nil {
+      fmt.Printf("failed to create bogus JWK: %s\n", err)
+      return
+    }
     bogusKey.Set(jwk.AlgorithmKey, jwa.NoSignature)
     bogusKey.Set(jwk.KeyIDKey, "otherkey")
 
@@ -593,7 +597,7 @@ func ExampleJWT_ParseWithJKU() {
     }
     // too lazy to write a proper algorithm. just assign every
     // time, and signingKey will end up being the last key generated
-    privkey, err := jwk.New(pk)
+    privkey, err := jwk.FromRaw(pk)
     if err != nil {
       fmt.Printf("failed to create jwk.Key: %s\n", err)
       return
@@ -942,7 +946,7 @@ func ExampleJWT_SerializeJWS() {
     return
   }
 
-  key, err := jwk.New([]byte(`abracadavra`))
+  key, err := jwk.FromRaw([]byte(`abracadavra`))
   if err != nil {
     fmt.Printf("failed to create symmetric key: %s\n", err)
     return
@@ -1001,13 +1005,13 @@ func ExampleJWT_SerializeJWEJWS() {
     return
   }
 
-  enckey, err := jwk.New(privkey.PublicKey)
+  enckey, err := jwk.FromRaw(privkey.PublicKey)
   if err != nil {
     fmt.Printf("failed to create symmetric key: %s\n", err)
     return
   }
 
-  signkey, err := jwk.New([]byte(`abracadavra`))
+  signkey, err := jwk.FromRaw([]byte(`abracadavra`))
   if err != nil {
     fmt.Printf("failed to create symmetric key: %s\n", err)
     return

docs/02-jws.md

@@ -138,7 +138,7 @@ import (
 )
 
 func ExampleJWS_Sign() {
-  key, err := jwk.New([]byte(`abracadavra`))
+  key, err := jwk.FromRaw([]byte(`abracadavra`))
   if err != nil {
     fmt.Printf("failed to create key: %s\n", err)
     return
@@ -179,7 +179,7 @@ func ExampleJWS_SignJSON() {
   var keys []jwk.Key
 
   for i := 0; i < 3; i++ {
-    key, err := jwk.New([]byte(fmt.Sprintf(`abracadavra-%d`, i)))
+    key, err := jwk.FromRaw([]byte(fmt.Sprintf(`abracadavra-%d`, i)))
     if err != nil {
       fmt.Printf("failed to create key: %s\n", err)
       return
@@ -225,7 +225,7 @@ import (
 func ExampleJWS_SignDetachedPayload() {
   payload := `$.02`
 
-  key, err := jwk.New([]byte(`abracadavra`))
+  key, err := jwk.FromRaw([]byte(`abracadavra`))
   if err != nil {
     fmt.Printf("failed to create symmetric key: %s\n", err)
     return
@@ -289,7 +289,7 @@ import (
 func ExampleJWS_VerifyWithKey() {
   const src = `eyJhbGciOiJIUzI1NiJ9.TG9yZW0gaXBzdW0.idbECxA8ZhQbU0ddZmzdRZxQmHjwvw77lT2bwqGgNMo`
 
-  key, err := jwk.New([]byte(`abracadavra`))
+  key, err := jwk.FromRaw([]byte(`abracadavra`))
   if err != nil {
     fmt.Printf("failed to create key: %s\n", err)
     return
@@ -350,13 +350,13 @@ func ExampleJWS_VerifyWithJWKSet() {
   // Create a JWK Set
   set := jwk.NewSet()
   // Add some bogus keys
-  k1, _ := jwk.New([]byte("abracadavra"))
+  k1, _ := jwk.FromRaw([]byte("abracadavra"))
   set.Add(k1)
-  k2, _ := jwk.New([]byte("opensasame"))
+  k2, _ := jwk.FromRaw([]byte("opensasame"))
   set.Add(k2)
   // Add the real thing
   pubkey, _ := jwk.PublicRawKeyOf(privkey)
-  k3, _ := jwk.New(pubkey)
+  k3, _ := jwk.FromRaw(pubkey)
   k3.Set(jwk.AlgorithmKey, jwa.RS256)
   set.Add(k3)
 
@@ -393,7 +393,7 @@ func ExampleJWS_VerifyDetachedPayload() {
   serialized := `eyJhbGciOiJIUzI1NiJ9..eOOVjre9XHILxvHaJpH-ZCb1TiiiTZLOY0Jhr7mwDns`
   payload := `$.02`
 
-  key, err := jwk.New([]byte(`abracadavra`))
+  key, err := jwk.FromRaw([]byte(`abracadavra`))
   if err != nil {
     fmt.Printf("failed to create symmetric key: %s\n", err)
     return

docs/04-jwk.md

@@ -337,6 +337,65 @@ that needs to handle `json.Unmarshal`. To overcome this, you can either define a
 that will intercept the field holding the `jwk.Key`.
 
 <!-- INCLUDE(examples/jwk_struct_field_example_test.go) -->
+```go
+package examples_test
+
+import (
+  "encoding/json"
+  "fmt"
+  "os"
+
+  "github.com/lestrrat-go/jwx/v2/jwk"
+)
+
+type Container struct {
+  Key jwk.Key `json:"key"`
+}
+
+// This is only one way to parse a struct field whose dynamic
+// type is unknown at compile time. In this example we use
+// a proxy/wrapper to trick `Container` from attempting to
+// parse the `.Key` field, and intercept the value that
+// would have gone into the the `Container` struct into
+// `Proxy` struct's `.Key` struct field
+type Proxy struct {
+  Container
+  Key json.RawMessage `json:"key"`
+}
+
+func ExampleJWK_StructField() {
+  const src = `{
+    "key": {
+      "kty":"EC",
+      "crv":"P-256",
+      "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
+      "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
+      "use":"enc",
+      "kid":"1"
+    }
+  }`
+
+  var p Proxy
+  if err := json.Unmarshal([]byte(src), &p); err != nil {
+    fmt.Printf("failed to unmarshal from JSON: %s\n", err)
+    return
+  }
+
+  // Parse the intercepted `Proxy.Key` as a `jwk.Key`
+  // and assign it to `Container.Key`
+  key, err := jwk.ParseKey(p.Key)
+  if err != nil {
+    fmt.Printf("failed to parse key: %s\n", err)
+    return
+  }
+  p.Container.Key = key
+
+  json.NewEncoder(os.Stdout).Encode(p.Container)
+  // OUTPUT:
+  // {"key":{"crv":"P-256","kid":"1","kty":"EC","use":"enc","x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4","y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"}}
+}
+```
+source: [examples/jwk_struct_field_example_test.go](https://github.com/lestrrat-go/jwx/blob/v2/examples/jwk_struct_field_example_test.go)
 <!-- END INCLUDE -->
 
 # Construction
@@ -376,14 +435,14 @@ import (
 )
 
 func ExampleJWK_New() {
-  // First, THIS IS THE WRONG WAY TO USE jwk.New().
+  // First, THIS IS THE WRONG WAY TO USE jwk.FromRaw().
   //
   // Assume that the file contains a JWK in JSON format
   //
   //  buf, _ := os.ReadFile(file)
   //  key, _ := json.New(buf)
   //
-  // This is not right, because the jwk.New() function determines
+  // This is not right, because the jwk.FromRaw() function determines
   // the type of `jwk.Key` to create based on the TYPE of the argument.
   // In this case the type of `buf` is always []byte, and therefore
   // it will always create a symmetric key.
@@ -399,7 +458,7 @@ func ExampleJWK_New() {
   // []byte -> jwk.SymmetricKey
   {
     raw := []byte("Lorem Ipsum")
-    key, err := jwk.New(raw)
+    key, err := jwk.FromRaw(raw)
     if err != nil {
       fmt.Printf("failed to create symmetric key: %s\n", err)
       return
@@ -419,7 +478,7 @@ func ExampleJWK_New() {
       return
     }
 
-    key, err := jwk.New(raw)
+    key, err := jwk.FromRaw(raw)
     if err != nil {
       fmt.Printf("failed to create symmetric key: %s\n", err)
       return
@@ -440,7 +499,7 @@ func ExampleJWK_New() {
       return
     }
 
-    key, err := jwk.New(raw)
+    key, err := jwk.FromRaw(raw)
     if err != nil {
       fmt.Printf("failed to create symmetric key: %s\n", err)
       return
@@ -455,7 +514,7 @@ func ExampleJWK_New() {
   // OUTPUT:
 }
 ```
-source: [examples/jwk_new_example_test.go](https://github.com/lestrrat-go/jwx/blob/v2/examples/jwk_new_example_test.go)
+source: [examples/jwk_from_raw_example_test.go](https://github.com/lestrrat-go/jwx/blob/v2/examples/jwk_from_raw_example_test.go)
 <!-- END INCLUDE -->
 
 ## Construct a specific key type from scratch