Attesto.NumericDate (Attesto v1.12.0)

Copy Markdown View Source

Value-level helpers for JWT NumericDate comparisons and Unix-second clocks.

This module deliberately does not choose protocol policy. Callers provide requiredness, non-negative validation, leeway, future skew, and maximum age, then map the result to their own error atom.

Summary

Types

fetch_result()
freshness_result()

Functions

bounded_lifetime(opts, key, default)

Resolve a positive lifetime option that may only shorten default.

fetch(claims, key, opts \\ [])

Fetch a NumericDate claim from claims.

fresh?(iat, now, opts \\ [])

Classify an issued-at value against a future-skew and maximum-age window.

not_before_reached?(nbf, now, opts \\ [])

Return whether a not-before NumericDate has been reached.

not_expired?(exp, now, opts \\ [])

Return whether an expiry remains strictly beyond now - leeway.

now(opts, policy \\ [])

Resolve a Unix-second clock from options.

valid?(value, opts \\ [])

Return whether value is an integer NumericDate for the selected policy.

within_lifetime?(finish, start, max_seconds)

Return whether finish is no more than max_seconds after start.

Types

fetch_result()

@type fetch_result() :: {:ok, integer()} | :missing | {:error, :missing | :invalid}

freshness_result()

@type freshness_result() :: :ok | :future | :stale | :invalid

Functions

bounded_lifetime(opts, key, default)

@spec bounded_lifetime(keyword(), atom(), pos_integer()) :: pos_integer()

Resolve a positive lifetime option that may only shorten default.

A missing, non-positive, non-integer, or longer requested lifetime falls back to the supplied default.

fetch(claims, key, opts \\ [])

@spec fetch(map(), term(), keyword()) :: fetch_result()

Fetch a NumericDate claim from claims.

Missing optional claims return :missing; missing required claims return {:error, :missing}. A present value that is not an integer, or is negative when non_negative: true, returns {:error, :invalid}.

fresh?(iat, now, opts \\ [])

@spec fresh?(term(), term(), keyword()) :: freshness_result()

Classify an issued-at value against a future-skew and maximum-age window.

Boundary values are accepted: iat == now + future_skew and iat == now - max_age both return :ok.

not_before_reached?(nbf, now, opts \\ [])

@spec not_before_reached?(term(), term(), keyword()) :: boolean()

Return whether a not-before NumericDate has been reached.

not_expired?(exp, now, opts \\ [])

@spec not_expired?(term(), term(), keyword()) :: boolean()

Return whether an expiry remains strictly beyond now - leeway.

now(opts, policy \\ [])

@spec now(keyword(), keyword()) :: integer()

Resolve a Unix-second clock from options.

`default: :datetime:system` preserves the caller's original live-clock
source. `invalid_override: :raise:fallback` preserves whether an invalid

:now override raised or silently used that live clock.

valid?(value, opts \\ [])

@spec valid?(
  term(),
  keyword()
) :: boolean()

Return whether value is an integer NumericDate for the selected policy.

within_lifetime?(finish, start, max_seconds)

@spec within_lifetime?(term(), term(), term()) :: boolean()

Return whether finish is no more than max_seconds after start.