Get the algorithm (alg) from a JWS.

Get the content type (cty) from a JWS header.

Decode custom headers from a parsed JWS using a custom decoder.

This allows reading non-standard header fields that were present during parsing. For JWS built via new, you already know what headers you set.

Decode the unprotected header using a custom decoder.

Security Warning: Unprotected headers are NOT integrity protected. They can be modified by an attacker without invalidating the signature. Only use for non-security-critical metadata.

This function only works on parsed JWS instances. When building a JWS, you already know what unprotected headers you set - use has_unprotected_header to check their presence.

Check if the JWS uses an unencoded payload (b64=false per RFC 7797).

Check if the JWS has unprotected headers.

Returns True if the JWS was parsed from JSON with unprotected headers, or if unprotected headers were added via with_unprotected.

Check if the JWS has a detached payload.

Get the key ID (kid) from a JWS header.

Security Warning: The kid value comes from the token and is untrusted input. If you use it to look up keys (from a database, filesystem, or key store), you must sanitize it first to prevent injection attacks:

• Use parameterized queries for database lookups
• Validate the format matches your expected key ID pattern
• Never use it directly in file paths or shell commands

Create a new unsigned JWS with the specified signing algorithm. The payload is provided at sign time via sign.

Example

let assert Ok(signed) = jws.new(gose.Mac(gose.Hmac(gose.HmacSha256)))
  |> jws.sign(key, <<"hello":utf8>>)

Parse a JWS from compact format.

Returns a signed JWS that can be verified with a Verifier. An empty payload segment (header..signature) is treated as a detached payload; use verify_detached to verify with the out-of-band payload.

Parse a JWS from JSON format (supports both General and Flattened).

Get the payload from a JWS.

Serialize a signed JWS to compact format.

Format: {base64url(header)}.{base64url(payload)}.{base64url(signature)}

For detached payloads: {base64url(header)}..{base64url(signature)}

For unencoded payloads (b64=false): {base64url(header)}.{payload}.{base64url(signature)}

Returns an error if the payload contains . characters when using b64=false, as this would create an invalid compact serialization (RFC 7797). Use JSON serialization instead for payloads containing periods.

Example

let assert Ok(token) = jws.serialize_compact(signed)

Serialize a signed JWS to JSON Flattened format.

Format: {"payload":"...","protected":"...","signature":"..."}

For detached payloads, the payload field is omitted. If unprotected headers are present, includes the header field.

Example

let assert Ok(signed) =
  jws.new(gose.Mac(gose.Hmac(gose.HmacSha256)))
  |> jws.sign(key, payload)
let json_str =
  jws.serialize_json_flattened(signed)
  |> json.to_string

Serialize a signed JWS to JSON General format.

Format: {"payload":"...","signatures":[{"protected":"...","signature":"..."}]}

For detached payloads, the payload field is omitted. If unprotected headers are present, includes the header field in the signature entry.

Example

let assert Ok(signed) =
  jws.new(gose.Mac(gose.Hmac(gose.HmacSha256)))
  |> jws.sign(key, payload)
let json_str =
  jws.serialize_json_general(signed)
  |> json.to_string

Sign an unsigned JWS with the provided key.

JWK metadata (use, key_ops) is enforced when present:

• Keys with use=enc are rejected
• Keys with key_ops that don’t include sign are rejected

Get the type (typ) from a JWS header.

Create a verifier for JWS signature verification.

Accepts one or more keys for key rotation scenarios. The verifier pins the expected algorithm and will reject tokens with different algorithms.

Key selection during verification:

1. If the JWS has a kid header, prioritize keys with matching kid
2. Try keys in order until one succeeds
3. Fail if no key verifies the signature

Verify a JWS signature using the verifier.

Checks:

1. Token’s alg header matches the verifier’s expected algorithm
2. Signature is valid for one of the verifier’s keys

When multiple keys are configured, keys with matching kid are tried first.

Example

let assert Ok(v) =
  jws.verifier(gose.Mac(gose.Hmac(gose.HmacSha256)), [key])
let assert Ok(parsed) = jws.parse_compact(token)
let assert Ok(Nil) = jws.verify(v, parsed)

Verify a JWS with a detached payload using the verifier.

Use this when the payload was not included in the serialized JWS.

Example

let assert Ok(v) =
  jws.verifier(gose.Mac(gose.Hmac(gose.HmacSha256)), [key])
let assert Ok(parsed) = jws.parse_compact(detached_token)
let assert Ok(Nil) = jws.verify_detached(v, parsed, payload)

Set the content type (cty) header parameter.

Mark this JWS as using a detached payload.

The payload will not be included in the serialized output, but is still provided at sign time and used for signature computation.

Add a custom protected header field.

Custom headers are sorted alphabetically by name and appear after standard fields (alg, kid, typ, cty). Returns an error if the name is a reserved header (alg, kid, typ, cty, crit, b64) to prevent security issues like algorithm confusion.

If the same header name is set multiple times, the last value wins.

Set the key ID (kid) header parameter.

Set the type (typ) header parameter (e.g., “JWT”).

Mark this JWS as using an unencoded payload (RFC 7797, b64=false).

The payload will be included directly in the serialized output without base64 encoding. The header will include "crit":["b64"],"b64":false. The payload is still provided at sign time.

Add an unprotected header field (for JSON serialization only).

Security Warning: Unprotected headers are NOT integrity protected. They can be modified by an attacker without invalidating the signature. Only use for non-security-critical metadata.

Returns an error if the name is a protected-only header (crit, b64) which MUST be integrity protected per RFC 7515/7797.

Compact serialization will return an error if unprotected headers are present.

If the same header name is set multiple times, the last value wins.