feat: add decoder() for JWK and JWK Set types

Expose Decoder values so JWK and JWK Set parsing can
compose with gleam/dynamic/decode pipelines. JWK Set
provides both a lenient decoder (skips invalid keys)
and a strict_decoder (fails on any invalid key).

Author: jtdowney

src/gose/jwk.gleam

@@ -1741,6 +1741,40 @@ pub fn from_json_bits(json_bits: BitArray) -> Result(Jwk, gose.GoseError) {
   from_dynamic(dyn)
 }
 
+/// Return a decoder for JWK values.
+///
+/// This lets you compose JWK decoding inside larger decode pipelines, for
+/// example with `decode.field`, `decode.list`, or `json.parse`.
+///
+/// ## Returns
+///
+/// A `Decoder(Jwk)` that succeeds on valid JWK JSON objects and fails on
+/// anything else.
+///
+/// ## Example
+///
+/// ```gleam
+/// // Parse a JWK directly from a JSON string
+/// let assert Ok(key) = json.parse(json_string, jwk.decoder())
+///
+/// // Use inside a larger decoder
+/// use key <- decode.field("signing_key", jwk.decoder())
+/// ```
+pub fn decoder() -> decode.Decoder(Jwk) {
+  let placeholder =
+    Jwk(
+      material: OctetKey(secret: <<>>),
+      kid: None,
+      key_use: None,
+      key_ops: None,
+      alg: None,
+    )
+  decode.new_primitive_decoder("Jwk", fn(dyn) {
+    from_dynamic(dyn)
+    |> result.replace_error(placeholder)
+  })
+}
+
 fn key_op_from_string(s: String) -> Result(KeyOp, gose.GoseError) {
   case s {
     "sign" -> Ok(Sign)

src/gose/jwk_set.gleam

@@ -126,7 +126,10 @@ pub fn from_json_bits(json_bits: BitArray) -> Result(JwkSet, gose.GoseError) {
 /// returns an error if any key in the array fails to parse. The error
 /// message includes the index of the invalid key.
 ///
-/// Use this for strict validation where all keys must be valid.
+/// Note that RFC 7517 Section 5 says implementations SHOULD ignore JWKs
+/// with unrecognised key types, missing required members, or unsupported
+/// parameter values. Prefer `from_json` unless you need to guarantee
+/// every key in the set is valid.
 ///
 /// ## Parameters
 ///
@@ -148,6 +151,11 @@ pub fn from_json_strict(json_str: String) -> Result(JwkSet, gose.GoseError) {
 /// returns an error if any key in the array fails to parse. The error
 /// message includes the index of the invalid key.
 ///
+/// Note that RFC 7517 Section 5 says implementations SHOULD ignore JWKs
+/// with unrecognised key types, missing required members, or unsupported
+/// parameter values. Prefer `from_json_bits` unless you need to guarantee
+/// every key in the set is valid.
+///
 /// ## Parameters
 ///
 /// - `json_bits` - The JSON BitArray containing a JWK Set object.
@@ -164,6 +172,49 @@ pub fn from_json_strict_bits(
   |> result.map(JwkSet)
 }
 
+/// Return a lenient decoder for JWK Set values.
+///
+/// Invalid keys are silently skipped, matching `from_json` behavior.
+///
+/// ## Returns
+///
+/// A `Decoder(JwkSet)` that parses the `keys` array, skipping any
+/// individual key that fails to parse.
+///
+/// ## Example
+///
+/// ```gleam
+/// let assert Ok(set) = json.parse(json_string, jwk_set.decoder())
+/// ```
+pub fn decoder() -> decode.Decoder(JwkSet) {
+  use keys_dyn <- decode.field("keys", decode.list(decode.dynamic))
+  decode.success(parse_keys_lenient(keys_dyn))
+}
+
+/// Return a strict decoder for JWK Set values.
+///
+/// Unlike `decoder()`, this fails if any key in the set is invalid.
+///
+/// Note that RFC 7517 Section 5 says implementations SHOULD ignore JWKs
+/// with unrecognised key types, missing required members, or unsupported
+/// parameter values. Prefer `decoder()` unless you need to guarantee
+/// every key in the set is valid.
+///
+/// ## Returns
+///
+/// A `Decoder(JwkSet)` that parses the `keys` array and fails if any
+/// individual key is invalid.
+///
+/// ## Example
+///
+/// ```gleam
+/// let assert Ok(set) = json.parse(json_string, jwk_set.strict_decoder())
+/// ```
+pub fn strict_decoder() -> decode.Decoder(JwkSet) {
+  use keys <- decode.field("keys", decode.list(jwk.decoder()))
+  decode.success(JwkSet(keys:))
+}
+
 fn parse_keys_array(
   parse: fn(decode.Decoder(List(decode.Dynamic))) ->
     Result(List(decode.Dynamic), json.DecodeError),

test/gose/jwk_set_test.gleam

@@ -1,5 +1,6 @@
 import birdie
 import gleam/bit_array
+import gleam/dynamic/decode
 import gleam/json
 import gleam/list
 import gose
@@ -622,3 +623,100 @@ pub fn from_json_strict_bits_roundtrip_test() {
     },
   )
 }
+
+pub fn decoder_skips_invalid_keys_test() {
+  let json_str =
+    json.object([
+      #(
+        "keys",
+        json.preprocessed_array([
+          json.object([
+            #("kty", json.string("oct")),
+            #("k", json.string("dGVzdA")),
+          ]),
+          json.object([#("kty", json.string("invalid"))]),
+        ]),
+      ),
+    ])
+    |> json.to_string
+  let assert Ok(dyn) = json.parse(json_str, decode.dynamic)
+  let assert Ok(set) = decode.run(dyn, jwk_set.decoder())
+  assert list.length(jwk_set.to_list(set)) == 1
+}
+
+pub fn decoder_all_valid_test() {
+  let key1 = jwk.generate_hmac_key(jwa.HmacSha256)
+  let key2 = jwk.generate_ec(ec.P256)
+  let set = jwk_set.from_list([key1, key2])
+  let json_str = jwk_set.to_json(set) |> json.to_string
+  let assert Ok(parsed) = json.parse(json_str, jwk_set.decoder())
+  assert list.length(jwk_set.to_list(parsed)) == 2
+}
+
+pub fn strict_decoder_test() {
+  let key1 = jwk.generate_hmac_key(jwa.HmacSha256)
+  let key2 = jwk.generate_ec(ec.P256)
+  let set = jwk_set.from_list([key1, key2])
+  let json_str = jwk_set.to_json(set) |> json.to_string
+  let assert Ok(parsed) = json.parse(json_str, jwk_set.strict_decoder())
+  assert list.length(jwk_set.to_list(parsed)) == 2
+}
+
+pub fn strict_decoder_invalid_key_test() {
+  let json_str =
+    json.object([
+      #(
+        "keys",
+        json.preprocessed_array([
+          json.object([
+            #("kty", json.string("oct")),
+            #("k", json.string("dGVzdA")),
+          ]),
+          json.object([#("kty", json.string("invalid"))]),
+        ]),
+      ),
+    ])
+    |> json.to_string
+  let assert Error(json.UnableToDecode([
+    decode.DecodeError(expected: "Jwk", found: _, path: ["keys", "1"]),
+  ])) = json.parse(json_str, jwk_set.strict_decoder())
+}
+
+pub fn decoder_missing_keys_field_test() {
+  let json_str = json.object([]) |> json.to_string
+  let assert Error(json.UnableToDecode([
+    decode.DecodeError(expected: "Field", found: "Nothing", path: ["keys"]),
+  ])) = json.parse(json_str, jwk_set.decoder())
+}
+
+pub fn decoder_keys_not_array_test() {
+  let json_str =
+    json.object([#("keys", json.string("not-an-array"))]) |> json.to_string
+  let assert Error(json.UnableToDecode([
+    decode.DecodeError(expected: "List", found: _, path: ["keys"]),
+  ])) = json.parse(json_str, jwk_set.decoder())
+}
+
+pub fn strict_decoder_missing_keys_field_test() {
+  let json_str = json.object([]) |> json.to_string
+  let assert Error(json.UnableToDecode([
+    decode.DecodeError(expected: "Field", found: "Nothing", path: ["keys"]),
+  ])) = json.parse(json_str, jwk_set.strict_decoder())
+}
+
+pub fn strict_decoder_keys_not_array_test() {
+  let json_str =
+    json.object([#("keys", json.string("not-an-array"))]) |> json.to_string
+  let assert Error(json.UnableToDecode([
+    decode.DecodeError(expected: "List", found: _, path: ["keys"]),
+  ])) = json.parse(json_str, jwk_set.strict_decoder())
+}
+
+pub fn decoder_with_json_parse_test() {
+  let key = jwk.generate_hmac_key(jwa.HmacSha256) |> jwk.with_kid("test-key")
+  let set = jwk_set.from_list([key])
+  let json_str = jwk_set.to_json(set) |> json.to_string
+  let assert Ok(parsed) = json.parse(json_str, jwk_set.decoder())
+  let assert Ok(found) = jwk_set.first(parsed)
+  assert jwk.kid(found) == Ok("test-key")
+}

test/gose/jwk_test.gleam

@@ -1315,3 +1315,53 @@ pub fn from_dynamic_test() {
   let assert Ok(parsed) = jwk.from_dynamic(dyn)
   assert jwk.key_type(parsed) == jwk.OctKeyType
 }
+
+pub fn decoder_with_decode_run_test() {
+  let key = jwk.generate_hmac_key(jwa.HmacSha256)
+  let json_str = jwk.to_json(key) |> json.to_string
+  let assert Ok(dyn) = json.parse(json_str, decode.dynamic)
+  let assert Ok(parsed) = decode.run(dyn, jwk.decoder())
+  assert jwk.key_type(parsed) == jwk.OctKeyType
+}
+
+pub fn decoder_with_json_parse_test() {
+  let key =
+    jwk.generate_ec(ec.P256)
+    |> jwk.with_kid("ec-key")
+  let json_str = jwk.to_json(key) |> json.to_string
+  let assert Ok(parsed) = json.parse(json_str, jwk.decoder())
+  assert jwk.key_type(parsed) == jwk.EcKeyType
+  assert jwk.kid(parsed) == Ok("ec-key")
+}
+
+pub fn decoder_in_nested_field_test() {
+  let key = jwk.generate_hmac_key(jwa.HmacSha256)
+  let inner_json = jwk.to_json(key)
+  let wrapper =
+    json.object([#("signing_key", inner_json)])
+    |> json.to_string
+  let wrapper_decoder = {
+    use k <- decode.field("signing_key", jwk.decoder())
+    decode.success(k)
+  }
+  let assert Ok(dyn) = json.parse(wrapper, decode.dynamic)
+  let assert Ok(parsed) = decode.run(dyn, wrapper_decoder)
+  assert jwk.key_type(parsed) == jwk.OctKeyType
+}
+
+pub fn decoder_list_test() {
+  let key1 = jwk.generate_hmac_key(jwa.HmacSha256)
+  let key2 = jwk.generate_ec(ec.P256)
+  let json_str =
+    json.preprocessed_array([jwk.to_json(key1), jwk.to_json(key2)])
+    |> json.to_string
+  let assert Ok(keys) = json.parse(json_str, decode.list(jwk.decoder()))
+  assert list.length(keys) == 2
+}
+
+pub fn decoder_invalid_input_test() {
+  let json_str =
+    json.object([#("not", json.string("a-jwk"))])
+    |> json.to_string
+  let assert Error(_) = json.parse(json_str, jwk.decoder())
+}