# `Attesto.SignedIntrospection`
[🔗](https://github.com/XukuLLC/attesto/blob/v0.13.0/lib/attesto/signed_introspection.ex#L1)

JWT response for OAuth 2.0 Token Introspection (RFC 9701).

Builds the signed JWT an authorization server returns from its introspection
endpoint (RFC 7662) when the caller requests
`application/token-introspection+jwt`, giving the introspection response
integrity and non-repudiation (FAPI 2.0 Message Signing §5.5).

This is conn-free core: it turns the issuer/keystore on the `Attesto.Config`,
the caller the response is addressed to, and the RFC 7662 introspection
response map into a compact JWS. The transport layer (the introspection
endpoint) decides - by content negotiation - whether to return the plain JSON
response or this signed JWT; nothing here touches HTTP.

## JWT claims (RFC 9701 §5)

  * `iss` - REQUIRED, the authorization server's issuer identifier.
  * `aud` - REQUIRED, the entity that requested the introspection (the
    authenticated `client_id`).
  * `iat` - REQUIRED, the issuance time.
  * `token_introspection` - REQUIRED, a JSON object that is the RFC 7662
    introspection response (`active` plus, when active, the token's claims).

The JOSE header `typ` is fixed to `"token-introspection+jwt"` (RFC 9701 §5),
the explicit type that distinguishes a signed introspection response from any
other JWT. Signing mirrors `Attesto.IDToken` / `Attesto.JARM`: the keystore's
current signing key and algorithm, with the `kid` in the header, signed
with that pinned algorithm (never `none`).

# `opts`

```elixir
@type opts() :: [now: integer() | DateTime.t(), lifetime: pos_integer()]
```

# `response`

```elixir
@type response() :: %{optional(String.t()) => term()}
```

# `header_typ`

```elixir
@spec header_typ() :: String.t()
```

The JOSE header `typ` a signed introspection response carries (RFC 9701 §5).

# `response_jwt`

```elixir
@spec response_jwt(Attesto.Config.t(), String.t(), response(), opts()) ::
  {:ok, String.t()}
```

Build and sign the RFC 9701 introspection response JWT addressed to
`audience`, wrapping the RFC 7662 `introspection_response`. Returns
`{:ok, compact_jws}`.

Options:

  * `:now` - the issuance time (integer Unix seconds or `DateTime`), for
    deterministic tests; defaults to the current time.
  * `:lifetime` - when given (seconds), adds an `exp` that many seconds after
    `iat`; omitted by default.

---

*Consult [api-reference.md](api-reference.md) for complete listing*