defmodule AttestoClient do
  @moduledoc """
  Client-side OAuth 2.0 / OpenID Connect / FAPI 2.0 artifacts and verification.

  `AttestoClient` is the relying-party (client) counterpart to
  [`attesto`](https://hex.pm/packages/attesto) (the authorization server). Where
  attesto *verifies* client artifacts and *issues* server artifacts with the
  authorization server's keystore, this library *builds* client-side wire
  artifacts and *verifies* the server artifacts a client receives:

    * `AttestoClient.ClientAssertion` - build a `private_key_jwt` client
      authentication assertion (RFC 7523 / OpenID Connect Core §9).
    * `AttestoClient.RequestObject` - build a signed authorization request object
      (JAR, RFC 9101 / FAPI 2.0 Message Signing §5.3.1).
    * `AttestoClient.IDToken` - verify OpenID Connect ID Tokens, including
      nonce, `max_age`, and `at_hash` / `c_hash` / `s_hash`.
    * `AttestoClient.JARM` - verify a signed authorization response (JARM,
      FAPI 2.0 Message Signing §5.4).
    * `AttestoClient.IdentityAssertion` - build Identity Assertion JWT
      Authorization Grant assertions (ID-JAG / EMA).
    * `AttestoClient.PKCE` - generate S256 PKCE verifier/challenge pairs.
    * `AttestoClient.SignedIntrospection` - verify RFC 9701 signed
      introspection responses.
    * `AttestoClient.UserInfo` - verify signed OpenID Connect UserInfo
      responses.
    * `AttestoClient.Discovery` - fetch and read authorization-server metadata
      and JWKS (RFC 8414 / OpenID Connect Discovery 1.0).

  It is deliberately **not** a full OAuth client framework: it has no flow
  orchestrator, token store, or session handling. It produces and checks the
  cryptographic, wire-format artifacts an OAuth/OIDC/FAPI client needs, leaving
  HTTP orchestration to the host (DPoP-bound requests are
  [`req_dpop`](https://hex.pm/packages/req_dpop)'s job).

  ## Assurance

  The build-side artifacts carry cross-language parity tests where practical,
  and the mirror modules are covered by in-family interop tests against the
  corresponding attesto server-side issuer or verifier.
  """
end