Atex.OAuth.DPoP (atex v0.10.0)

View Source

DPoP (Demonstrating Proof of Possession) token creation and request handling.

Provides functions to create DPoP proof JWTs and send DPoP-protected HTTP requests, handling the nonce retry dance required by the AT Protocol OAuth specification.

Summary

Functions

create_dpop_token(jwk, request, nonce \\ nil, attrs \\ %{})

Create a DPoP proof token for a given request.

request_protected_dpop_resource(request, issuer, access_token, dpop_key, nonce \\ nil)

Send a DPoP-protected request to a resource server (e.g., a PDS endpoint).

send_oauth_dpop_request(request, dpop_key, nonce \\ nil)

Send a DPoP-protected request to a token endpoint.

Functions

create_dpop_token(jwk, request, nonce \\ nil, attrs \\ %{})

@spec create_dpop_token(JOSE.JWK.t(), Req.Request.t(), String.t() | nil, map()) ::
  String.t()

Create a DPoP proof token for a given request.

Builds a signed JWT containing the HTTP method, URL (without query string), a random jti, the current timestamp, and an optional server nonce. Extra claims (e.g., iss, ath) can be merged in via attrs.

Parameters

  • jwk - Private JWK used to sign the proof
  • request - The Req.Request the token is being produced for
  • nonce - Server-provided nonce (optional; omitted from JWT when nil)
  • attrs - Extra claims to merge into the JWT payload (default: %{})

request_protected_dpop_resource(request, issuer, access_token, dpop_key, nonce \\ nil)

@spec request_protected_dpop_resource(
  Req.Request.t(),
  String.t(),
  String.t(),
  JOSE.JWK.t(),
  String.t() | nil
) :: {:ok, Req.Response.t(), String.t() | nil} | {:error, any()}

Send a DPoP-protected request to a resource server (e.g., a PDS endpoint).

Attaches both the Authorization: DPoP <token> header (assumed already set on request) and a fresh DPoP proof. If the server returns a 401 with a WWW-Authenticate: DPoP ... header, retries once with the returned nonce.

Parameters

  • request - A Req.Request with the Authorization header already set
  • issuer - Authorization server issuer URL (used in the iss claim)
  • access_token - The access token (used to compute the ath hash claim)
  • dpop_key - Private JWK for signing the DPoP proof
  • nonce - Current DPoP nonce, if any (default: nil)

send_oauth_dpop_request(request, dpop_key, nonce \\ nil)

@spec send_oauth_dpop_request(Req.Request.t(), JOSE.JWK.t(), String.t() | nil) ::
  {:ok, map(), String.t() | nil} | {:error, any(), String.t() | nil}

Send a DPoP-protected request to a token endpoint.

Attaches a DPoP proof to request and sends it. If the server responds with use_dpop_nonce, retries once with the returned nonce.

Parameters

  • request - A Req.Request already configured with URL, method, and body
  • dpop_key - Private JWK for signing the DPoP proof
  • nonce - Current DPoP nonce, if any (default: nil)