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

JWT Secured Authorization Response Mode (JARM).

Builds the signed JWT an authorization server returns to a client as the
single `response` parameter when a JWT response mode (`jwt`, `query.jwt`,
`fragment.jwt`, `form_post.jwt`) is requested, giving the authorization
response non-repudiation and integrity (FAPI 2.0 Message Signing §5.4).

This is conn-free core: it turns the issuer/keystore on the `Attesto.Config`,
the client identifier, and a map of authorization-response parameters (the
`code`/`state`/`iss` of a success, or the `error`/`error_description`/`state`
of a failure) into a compact JWS. The transport layer (the authorization
endpoint) decides the response mode and how the resulting JWT is delivered
(redirect query/fragment or auto-submitting form); nothing here touches HTTP.

## JWT claims (JARM §2.1)

  * `iss` - REQUIRED, the authorization server's issuer identifier.
  * `aud` - REQUIRED, the client the response is addressed to (`client_id`).
  * `exp` - REQUIRED, expiration; the response is short-lived.
  * `iat` - the issuance time.
  * every supplied authorization-response parameter, verbatim, as a top-level
    claim (`code`, `state`, `iss`-echo for success; `error`,
    `error_description`, `error_uri`, `state` for failure).

Signing mirrors `Attesto.IDToken`: the keystore's current signing key and its
algorithm (`Attesto.SigningAlg.for_key/3`), with the `kid` in the JOSE header,
signed with that pinned algorithm (never `none`).

# `opts`

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

# `response_params`

```elixir
@type response_params() :: %{optional(String.t()) => String.t() | nil}
```

# `response_jwt`

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

Build and sign the JARM response JWT for `client_id`, carrying `params`.

`params` is the authorization-response parameter map; `nil` values are
dropped (an absent `state`/`error_uri` is not advertised). Returns
`{:ok, compact_jws}`.

Options:

  * `:now` - the issuance time (integer Unix seconds or `DateTime`), for
    deterministic tests; defaults to the current time.
  * `:lifetime` - the JWT lifetime in seconds; may only shorten the
    `600`-second default.

---

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