Attesto.Plug.OAuthError (Attesto v0.13.0)

Copy Markdown View Source

Render the RFC 6750 / RFC 9449 error responses for the Attesto plugs.

Translates the verifier's error atoms into the wire responses a protected resource owes a client:

  • invalid_token (RFC 6750 §3.1) - 401 with a WWW-Authenticate challenge for the scheme the request used (Bearer or DPoP).
  • invalid_dpop_proof (RFC 9449 §7.1) - 401 with a DPoP challenge, for a DPoP proof that failed verification.
  • use_dpop_nonce (RFC 9449 §8) - 401 with a DPoP challenge and a fresh DPoP-Nonce header, telling the client to retry with the nonce.
  • insufficient_scope (RFC 6750 §3.1) - 403 naming the required scope.

Each helper sets the status, the WWW-Authenticate header (and DPoP-Nonce when relevant), writes a small JSON body, and halts the pipeline. Hosts may override only the transport details with :send_error, :www_authenticate, and :no_store callbacks; the OAuth error code, status, and challenge semantics remain owned here. This module is part of the optional Attesto.Plug layer; it only compiles when Plug is available.

Summary

Types

scheme()

Functions

insufficient_scope(conn, required, scheme \\ :bearer, opts \\ [])

Respond 403 insufficient_scope naming the required scope list (RFC 6750 §3.1). The optional opts accepts :resource_metadata (RFC 9728 §5.1: the URL of this resource's protected-resource metadata, advertised as a resource_metadata auth-param) and the SAME transport hooks unauthorized/4 honors - :send_error, :www_authenticate, and :no_store - so a resource server can override the 403 response envelope and inject a per-conn challenge (e.g. a host-derived resource_metadata pointer) on the scope-rejection path too. The insufficient_scope error code, 403 status, and the error_description / scope challenge semantics remain owned here. Halts.

insufficient_user_authentication(conn, scheme, challenge, opts \\ [])

Respond RFC 9470 §3 insufficient_user_authentication (401): the presented token does not meet the route's step-up requirement.

unauthorized(conn, scheme, error, opts \\ [])

Respond 401 with a WWW-Authenticate challenge for scheme carrying error (an OAuth error code string). Options: :description (error_description), :dpop_nonce (sets the DPoP-Nonce header, for use_dpop_nonce), and :resource_metadata (RFC 9728 §5.1: the URL of this resource's protected-resource metadata, advertised as a resource_metadata auth-param so the client can discover the authorization server). Halts.

Types

scheme()

@type scheme() :: :bearer | :dpop

Functions

insufficient_scope(conn, required, scheme \\ :bearer, opts \\ [])

@spec insufficient_scope(Plug.Conn.t(), [String.t()], scheme(), keyword()) ::
  Plug.Conn.t()

Respond 403 insufficient_scope naming the required scope list (RFC 6750 §3.1). The optional opts accepts :resource_metadata (RFC 9728 §5.1: the URL of this resource's protected-resource metadata, advertised as a resource_metadata auth-param) and the SAME transport hooks unauthorized/4 honors - :send_error, :www_authenticate, and :no_store - so a resource server can override the 403 response envelope and inject a per-conn challenge (e.g. a host-derived resource_metadata pointer) on the scope-rejection path too. The insufficient_scope error code, 403 status, and the error_description / scope challenge semantics remain owned here. Halts.

insufficient_user_authentication(conn, scheme, challenge, opts \\ [])

@spec insufficient_user_authentication(Plug.Conn.t(), scheme(), map(), keyword()) ::
  Plug.Conn.t()

Respond RFC 9470 §3 insufficient_user_authentication (401): the presented token does not meet the route's step-up requirement.

challenge is the Attesto.StepUp challenge map carrying the :acr_values (space-delimited) and/or :max_age the client must re-request at the authorization endpoint; both are appended as WWW-Authenticate auth-params. This is an authentication error (401, like invalid_token), built on the same machinery as unauthorized/4, honoring the same :description, :resource_metadata, and :send_error / :www_authenticate / :no_store transport hooks. Halts.

unauthorized(conn, scheme, error, opts \\ [])

@spec unauthorized(Plug.Conn.t(), scheme(), String.t(), keyword()) :: Plug.Conn.t()

Respond 401 with a WWW-Authenticate challenge for scheme carrying error (an OAuth error code string). Options: :description (error_description), :dpop_nonce (sets the DPoP-Nonce header, for use_dpop_nonce), and :resource_metadata (RFC 9728 §5.1: the URL of this resource's protected-resource metadata, advertised as a resource_metadata auth-param so the client can discover the authorization server). Halts.