@spec audience_matches?(term(), term(), audience_mode()) :: boolean()

Compare an audience claim with an expected audience under an explicit protocol mode.

The caller must select the mode because audience forms are protocol policy, not a single shared rule:

• :scalar_only accepts only a binary claim.
• :array accepts a binary claim or a non-empty all-binary array with intersection semantics.
• :single_element accepts a scalar or exactly [expected].
• :all_array_members requires every member of an array to be expected.

This is a value-level predicate; callers retain responsibility for error mapping and any surrounding claim validation.

@spec merge_registered(map(), map(), keyword()) ::
  {:ok, map()} | {:error, normalize_error() | :reserved_claim_conflict}

Merge caller-supplied claims into authoritative registered claims.

The caller map is normalized first. Keys in reserved are rejected before the merge; by default every key already present in registered is reserved. atom_keys is passed to normalize_keys/2 as its :atoms policy.

@spec normalize_keys(
  map(),
  keyword()
) :: {:ok, map()} | {:error, normalize_error()}

Normalize the keys in map to JSON member-name binaries.

With atoms: :reject (the default), every key must already be a binary. With atoms: :convert, atom keys are converted with Atom.to_string/1; all other non-binary keys are rejected.

@spec typ_matches?(term(), [String.t() | nil], keyword()) :: boolean()

Match a JOSE typ value against an explicit accepted set using the RFC 7515 application/ bare-subtype convention.

The normalization option is intentionally required. Callers with exact or otherwise protocol-specific type rules must keep those rules local.