gose/jwk_set

A JWK Set is a JSON object containing an array of JWK values. The keys member is REQUIRED and contains the array.

Example

// Build a key set
let key =
  jwk.generate_ec(ec.P256)
  |> jwk.with_kid("key-1")
let set =
  jwk_set.new()
  |> jwk_set.insert(key)

// Serialize to JSON and parse back
let json_string = jwk_set.to_json(set)
  |> json.to_string()
let assert Ok(parsed) = jwk_set.from_json(json_string)

// Look up a key by kid
let assert Ok(found) = jwk_set.get(parsed, "key-1")

Types

JwkSet

opaque </>

A JSON Web Key Set containing zero or more JWKs.

pub opaque type JwkSet

Values

delete

</>

pub fn delete(jwk_set: JwkSet, kid kid: String) -> JwkSet

Remove a key by its key ID (kid).

Parameters

jwk_set - The JWK Set to remove from.
kid - The key ID of the key to remove.

Returns

A new JwkSet without the matching key. If no key with the given kid exists, returns the set unchanged.

filter

</>

pub fn filter(
  jwk_set: JwkSet,
  keeping predicate: fn(jwk.Jwk) -> Bool,
) -> JwkSet

Filter keys by a predicate function.

Parameters

jwk_set - The JWK Set to filter.
predicate - A function applied to each key; keys returning True are kept.

Returns

A new JwkSet containing only the keys for which the predicate returns True.

first

</>

pub fn first(jwk_set: JwkSet) -> Result(jwk.Jwk, Nil)

Get the first key in the set.

Useful for single-key sets or when any key will suffice.

Parameters

jwk_set - The JWK Set to query.

Returns

Ok(Jwk) with the first key, or Error(Nil) if the set is empty.

from_json

</>

pub fn from_json(
  json_str: String,
) -> Result(JwkSet, gose.GoseError)

Parse a JWK Set from a JSON string.

The keys array is required. Unknown top-level members are ignored per RFC.

Parameters

json_str - The JSON string containing a JWK Set object.

Returns

Ok(JwkSet) with the parsed key set (silently skipping invalid keys), or Error(ParseError) if the keys array is missing or malformed.

from_json_bits

</>

pub fn from_json_bits(
  json_bits: BitArray,
) -> Result(JwkSet, gose.GoseError)

Parse a JWK Set from a JSON BitArray.

The keys array is required. Unknown top-level members are ignored per RFC.

Parameters

json_bits - The JSON BitArray containing a JWK Set object.

Returns

Ok(JwkSet) with the parsed key set (silently skipping invalid keys), or Error(ParseError) if the keys array is missing or malformed.

from_json_strict

</>

pub fn from_json_strict(
  json_str: String,
) -> Result(JwkSet, gose.GoseError)

Parse a JWK Set from a JSON string, failing on any invalid key.

Unlike from_json which silently skips invalid keys, this function 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.

Parameters

json_str - The JSON string containing a JWK Set object.

Returns

Ok(JwkSet) with all parsed keys, or Error(ParseError) if the keys array is missing, malformed, or any individual key fails to parse.

from_json_strict_bits

</>

pub fn from_json_strict_bits(
  json_bits: BitArray,
) -> Result(JwkSet, gose.GoseError)

Parse a JWK Set from a JSON BitArray, failing on any invalid key.

Unlike from_json_bits which silently skips invalid keys, this function returns an error if any key in the array fails to parse. The error message includes the index of the invalid key.

Parameters

json_bits - The JSON BitArray containing a JWK Set object.

Returns

Ok(JwkSet) with all parsed keys, or Error(ParseError) if the keys array is missing, malformed, or any individual key fails to parse.

from_list

</>

pub fn from_list(keys: List(jwk.Jwk)) -> JwkSet

Create a JWK Set from a list of keys.

Parameters

keys - The list of JWKs to include in the set.

Returns

A new JwkSet containing the given keys.

get

</>

pub fn get(jwk_set: JwkSet, kid: String) -> Result(jwk.Jwk, Nil)

Find a key by its key ID (kid).

Parameters

jwk_set - The JWK Set to search.
kid - The key ID to look up.

Returns

Ok(Jwk) with the matching key, or Error(Nil) if no key with the given kid exists.

insert

</>

pub fn insert(jwk_set: JwkSet, key key: jwk.Jwk) -> JwkSet

Add a key to the set.

Keys are prepended, so if a key with the same kid already exists, the newer key shadows the older one — get will return the most recently inserted key.

Parameters

jwk_set - The JWK Set to add the key to.
key - The JWK to insert.

Returns

A new JwkSet with the key prepended.

new

</>

pub fn new() -> JwkSet

Create an empty JWK Set.

Returns

A new JwkSet with no keys.

to_json

</>

pub fn to_json(jwk_set: JwkSet) -> json.Json

Serialize a JWK Set to its JSON representation.

Parameters

jwk_set - The JWK Set to serialize.

Returns

A json.Json value containing {"keys": [...]} with each key serialized via jwk.to_json().

to_list

</>

pub fn to_list(jwk_set: JwkSet) -> List(jwk.Jwk)

Get all keys from a JWK Set as a list.

Parameters

jwk_set - The JWK Set to extract keys from.

Returns

The list of JWKs contained in the set.