Attesto.StatusList (Attesto v2.28.0)

Copy Markdown View Source

IETF Token Status List (draft-ietf-oauth-status-list-21) construction and verification.

Status values are packed into a compact bit array, compressed with zlib, and carried in a signed JWT or CWT. fetch/3 provides a bounded, SSRF-screened default resolver using the optional Mint dependency. Hosts may also supply their own resolver functions.

Summary

Functions

Build an unsigned status_list claim.

Verify a credential's revocation status against a fetched Status List Token (statuslist+jwt or statuslist+cwt) or ISO 18013-5 Identifier List Token (identifierlist+cwt).

Fetch a status or identifier list over HTTPS. DNS and the pinned connection share a five-second deadline; redirects are refused, the response media type must match accept, and the body is limited to 1 MiB. No credentials or cookies are sent. Requires the optional :mint dependency.

Build and sign a Status List Token for uri.

Build and sign a CWT Status List Token (statuslist+cwt) as a CBOR-tagged COSE_Sign1.

Build and sign an ISO 18013-5 CWT Identifier List Token (identifierlist+cwt) as a CBOR-tagged COSE_Sign1.

Maximum accepted wire size in bytes of a compact statuslist+jwt or CWT status list.

Pack status values into bytes, placing the first entry in each byte's least significant field.

Build the status claim carried by a token that references a status list.

Resolve a referenced token's status without performing HTTP.

Resolve credential verification's :resolve_status option. Omission selects the screened default fetcher. Explicit false is reserved for offline inspection; applications making acceptance decisions must enforce status.

Sign a caller-supplied Status List Token claim set with the required type.

Read the status value at idx from a packed status array.

Verify and decode a Status List Token.

Verify and decode a CWT Status List Token (statuslist+cwt / application/statuslist+cwt).

Verify and decode an ISO 18013-5 CWT Identifier List Token (identifierlist+cwt / application/identifierlist+cwt).

Types

bits()

@type bits() :: 1 | 2 | 4 | 8

verified()

@type verified() :: %{
  bits: bits(),
  statuses_binary: binary(),
  sub: String.t(),
  claims: map()
}

verified_identifier_list()

@type verified_identifier_list() :: %{
  identifiers: MapSet.t(binary()),
  sub: String.t(),
  claims: map()
}

Functions

build(statuses, opts \\ [])

@spec build(
  [non_neg_integer()],
  keyword()
) :: %{required(String.t()) => term()}

Build an unsigned status_list claim.

:bits defaults to 1.

check_status(status_claim, resolver, trusted, opts \\ [])

@spec check_status(map() | nil, function(), term(), keyword()) ::
  :ok | {:error, term()}

Verify a credential's revocation status against a fetched Status List Token (statuslist+jwt or statuslist+cwt) or ISO 18013-5 Identifier List Token (identifierlist+cwt).

Returns :ok when the credential has no status reference (nil) or when the referenced status entry is valid (0 in a status list, or absent from an identifier list). Returns {:error, :credential_revoked} when the status list entry is 1 or the credential identifier is present in the identifier list. Status 2 returns :credential_suspended; other nonzero values return {:credential_status, value}. Fails closed with {:error, reason} when the reference or list token cannot be fetched or verified.

resolver is a 1-arity function of the URI or a 2-arity function of the URI and the accepted media type. Either returns {:ok, binary()} or {:error, term()}. :status_trusted_certificates restricts list signers to the supplied DER anchors without changing credential verification trust.

fetch(uri, accept, opts \\ [])

@spec fetch(String.t(), String.t(), keyword()) :: {:ok, binary()} | {:error, term()}

Fetch a status or identifier list over HTTPS. DNS and the pinned connection share a five-second deadline; redirects are refused, the response media type must match accept, and the body is limited to 1 MiB. No credentials or cookies are sent. Requires the optional :mint dependency.

Options: :timeout in milliseconds, :resolver for DNS, and :allow_loopback for local development (default false).

issue(keystore, uri, statuses, opts \\ [])

@spec issue(module(), String.t(), [non_neg_integer()], keyword()) :: String.t()

Build and sign a Status List Token for uri.

Options are :bits (default 1), :exp, :ttl, and :now.

issue_cwt(pem, uri, statuses, opts \\ [])

@spec issue_cwt(String.t(), String.t(), [non_neg_integer()], keyword()) :: binary()

Build and sign a CWT Status List Token (statuslist+cwt) as a CBOR-tagged COSE_Sign1.

issue_identifier_list_cwt(pem, uri, identifiers, opts \\ [])

@spec issue_identifier_list_cwt(String.t(), String.t(), [binary()] | map(), keyword()) ::
  binary()

Build and sign an ISO 18013-5 CWT Identifier List Token (identifierlist+cwt) as a CBOR-tagged COSE_Sign1.

max_status_list_token_bytes()

@spec max_status_list_token_bytes() :: pos_integer()

Maximum accepted wire size in bytes of a compact statuslist+jwt or CWT status list.

pack(statuses, bits)

@spec pack([non_neg_integer()], bits()) :: binary()

Pack status values into bytes, placing the first entry in each byte's least significant field.

reference(uri, idx)

@spec reference(String.t(), non_neg_integer()) :: %{required(String.t()) => term()}

Build the status claim carried by a token that references a status list.

resolve(status_claim, resolver, jwks_or_resolver, opts \\ [])

@spec resolve(
  map(),
  (String.t() -> {:ok, String.t()} | {:error, term()}),
  term(),
  keyword()
) ::
  {:ok, non_neg_integer()} | {:error, term()}

Resolve a referenced token's status without performing HTTP.

resolver fetches the Status List Token for a URI and returns {:ok, token}. The third argument may be trusted JWKS directly or a function that resolves the trusted JWKS for that URI.

A Status List Token without an exp claim is treated as non-expiring by verify/3 (matching draft-ietf-oauth-status-list §11.5). The host's resolver must therefore bound how long a fetched token is cached: honor the verified token's ttl claim when present, and enforce a fixed maximum cache age when ttl is absent.

resolver(opts)

@spec resolver(keyword()) :: false | function()

Resolve credential verification's :resolve_status option. Omission selects the screened default fetcher. Explicit false is reserved for offline inspection; applications making acceptance decisions must enforce status.

sign(keystore, claims, opts \\ [])

@spec sign(module(), map(), keyword()) :: String.t()

Sign a caller-supplied Status List Token claim set with the required type.

status_at(packed, bits, idx)

@spec status_at(binary(), bits(), non_neg_integer()) :: non_neg_integer()

Read the status value at idx from a packed status array.

verify(token, jwks, opts \\ [])

@spec verify(String.t(), map() | [map()] | nil, keyword()) ::
  {:ok, verified()} | {:error, atom()}

Verify and decode a Status List Token.

:accepted_algs limits the trusted signing algorithms. By default all asymmetric algorithms supported by Attesto are accepted.

verify_cwt(token, trusted, opts \\ [])

@spec verify_cwt(binary(), term(), keyword()) :: {:ok, verified()} | {:error, atom()}

Verify and decode a CWT Status List Token (statuslist+cwt / application/statuslist+cwt).

verify_identifier_list_cwt(token, trusted, opts \\ [])

@spec verify_identifier_list_cwt(binary(), term(), keyword()) ::
  {:ok, verified_identifier_list()} | {:error, atom()}

Verify and decode an ISO 18013-5 CWT Identifier List Token (identifierlist+cwt / application/identifierlist+cwt).