# `X402.Plug.HTTPSignatureDirectory`
[🔗](https://github.com/cardotrejos/x402/blob/v0.9.0/lib/x402/plug/http_signature_directory.ex#L2)

Plug serving a signature agent's key directory at
`/.well-known/http-message-signatures-directory`.

The `http-message-signatures` extension asks paying agents to host
the public keys they sign with as a JWKS document
(`X402.HTTPSignature.directory/1`), served with the
`application/http-message-signatures-directory+json` media type and
signed with each of those keys so a verifier can check the directory
belongs to the origin serving it
(draft-meunier-http-message-signatures-directory).

    plug X402.Plug.HTTPSignatureDirectory, keys: [key]

Requests for any other path, or with another method, pass through
untouched, so the plug can sit anywhere in a pipeline. Keys are given
as `X402.HTTPSignature.Key` structs carrying private material (needed
to sign the response) or as a zero-arity function returning them, for
keys rotated at runtime.

## Response signatures

Each key signs the response over `@authority` bound to the request
(`("@authority";req)`, as RFC 9421 §2.4 requires of a request
component in a response signature), with `created`, `expires`,
`keyid` (the key's `kid`), `alg`, `nonce` and the
`http-message-signatures-directory` tag. Labels are `sig1`, `sig2`,
and so on, in key order.

# `options`

```elixir
@type options() :: %{
  keys: [X402.HTTPSignature.Key.t()] | (-> [X402.HTTPSignature.Key.t()]),
  path: String.t(),
  sign: boolean(),
  ttl: pos_integer()
}
```

Validated options.

# `call`
*since 0.9.0* 

```elixir
@spec call(Plug.Conn.t(), options()) :: Plug.Conn.t()
```

Serves the directory for `GET` requests on the configured path.

# `init`
*since 0.9.0* 

```elixir
@spec init(keyword()) :: options()
```

Validates the options.

## Options

* `:keys` - Required. The keys to publish: a list of `X402.HTTPSignature.Key` with private
  material, or a zero-arity function returning such a list.

* `:path` (`t:String.t/0`) - The request path served. The default value is `"/.well-known/http-message-signatures-directory"`.

* `:sign` (`t:boolean/0`) - Whether to sign the response with each published key. The default value is `true`.

* `:ttl` (`t:pos_integer/0`) - Seconds between the signatures' `created` and `expires`. The default value is `3600`.

## Examples

    iex> {:ok, key} = X402.HTTPSignature.Key.generate("ed25519")
    iex> options = X402.Plug.HTTPSignatureDirectory.init(keys: [key])
    iex> {options.path, options.sign, options.ttl}
    {"/.well-known/http-message-signatures-directory", true, 3600}

# `media_type`
*since 0.9.0* 

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

Returns the media type of the directory document.

## Examples

    iex> X402.Plug.HTTPSignatureDirectory.media_type()
    "application/http-message-signatures-directory+json"

---

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