X402.Plug.HTTPSignatureDirectory (X402 v0.9.0)

Copy Markdown View Source

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.

Summary

Types

options()

Validated options.

Functions

call(conn, options)

Serves the directory for GET requests on the configured path.

init(opts)

Validates the options.

media_type()

Returns the media type of the directory document.

Types

options()

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

Validated options.

Functions

call(conn, options)

(since 0.9.0) 
@spec call(Plug.Conn.t(), options()) :: Plug.Conn.t()

Serves the directory for GET requests on the configured path.

init(opts)

(since 0.9.0) 
@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 (String.t/0) - The request path served. The default value is "/.well-known/http-message-signatures-directory".

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

  • :ttl (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) 
@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"