livery_auth (livery v0.2.0)

View Source

JWT verification against a JWK set.

Verifies compact-serialization JSON Web Tokens signed with RS256 or ES256, then validates the registered claims (exp, nbf, iss, aud). Signature verification and key handling use the OTP public_key and crypto modules; no third-party crypto is pulled in.

The JWK set is supplied by the caller. OIDC discovery and live JWKS rotation over HTTP are a thin layer that can sit on top of this module (a follow-up); keeping verification network-free makes it cheap to test and embed.

{ok, Claims} = livery_auth:verify(Token, #{
    keys     => JwkList,
    issuer   => <<"https://issuer.example">>,
    audience => <<"my-api">>
}).

A JWK is a map with binary keys, e.g. for RSA: #{<<"kty">> => <<"RSA">>, <<"kid">> => _, <<"n">> => _, <<"e">> => _} and for EC P-256: #{<<"kty">> => <<"EC">>, <<"crv">> => <<"P-256">>, <<"x">> => _, <<"y">> => _}.

Summary

Types

claims()
error_reason()
jwk()
verify_opts()

Functions

tls_opts()

TLS client options for verifying an HTTPS peer's certificate.

verify(Token, Opts)

Verify a JWT and return its validated claims.

Types

claims()

-type claims() :: #{binary() => term()}.

error_reason()

-type error_reason() ::
          malformed | invalid_json |
          {unsupported_alg, binary()} |
          no_matching_key | bad_signature | expired | not_yet_valid |
          {issuer_mismatch, binary()} |
          audience_mismatch.

jwk()

-type jwk() :: #{binary() => binary()}.

verify_opts()

-type verify_opts() ::
          #{keys := [jwk()],
            issuer => binary() | undefined,
            audience => binary() | [binary()] | undefined,
            now => non_neg_integer(),
            leeway => non_neg_integer()}.

Functions

tls_opts()

-spec tls_opts() -> [ssl:tls_client_option()].

TLS client options for verifying an HTTPS peer's certificate.

Used by the OIDC/JWKS/introspection fetchers so the channel that discovers signing keys (and thus the identity trust root) is authenticated: a forged JWK set served by an on-path attacker would otherwise let them mint tokens this node accepts. Verifies against the OS trust store with hostname checking.

verify(Token, Opts)

-spec verify(binary(), verify_opts()) -> {ok, claims()} | {error, error_reason()}.

Verify a JWT and return its validated claims.

Steps: split the compact token, decode the header to pick the algorithm and key id, find the matching JWK, verify the signature, then validate exp/nbf/iss/aud.