@spec challenge(keyword()) :: map()

Builds the server-side challenge advertised under PaymentRequired.extensions["sign-in-with-x"].

Every call produces a fresh nonce (unless :nonce is given) and timestamps; advertise a new challenge on every 402 response. Raises NimbleOptions.ValidationError for invalid options (programmer error).

Options

• :domain (String.t/0) - Required. The server's public host (info.domain), e.g. "api.example.com".

• :uri (String.t/0) - Required. The URI the proof is bound to (info.uri), e.g. "https://api.example.com".

• :supported_chains - Required. Chains proofs are accepted from: a list of maps or keyword lists with :chain_id (CAIP-2, eip155:* or solana:*), an optional :type ("eip191" for eip155, "ed25519" for solana; derived from the chain when omitted), and an optional :signature_scheme hint ("eip191", "eip1271", "eip6492", or "siws").

• :statement - Human-readable purpose shown by the wallet (info.statement). The default value is nil.

• :resources (list of String.t/0) - URIs associated with the request (info.resources); omitted when empty. The default value is [].

• :version (String.t/0) - CAIP-122 version. Always "1". The default value is "1".

• :nonce - Explicit nonce; a fresh generate_nonce/0 value when omitted. The default value is nil.

• :issued_at - Challenge creation time; DateTime.utc_now/0 when omitted. The default value is nil.

• :expiration_seconds (pos_integer/0) - Seconds after issued_at at which the challenge expires (info.expirationTime). The default value is 300.

• :not_before - Optional info.notBefore. The default value is nil.

• :request_id - Optional correlation id (info.requestId). The default value is nil.

Examples

iex> challenge = X402.Extensions.SIWX.challenge(
...>   domain: "api.example.com",
...>   uri: "https://api.example.com",
...>   supported_chains: [[chain_id: "eip155:8453"], [chain_id: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"]],
...>   statement: "Sign in to access premium data"
...> )
iex> challenge["supportedChains"]
[
  %{"chainId" => "eip155:8453", "type" => "eip191"},
  %{"chainId" => "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "type" => "ed25519"}
]
iex> challenge["info"]["statement"]
"Sign in to access premium data"
iex> challenge["schema"] == X402.Extensions.SIWX.schema()
true

@spec decode(String.t()) :: {:ok, message_payload()} | {:error, decode_error()}

Decodes an EIP-4361 SIWX message into payload fields.

Examples

iex> payload = %{
...>   domain: "example.com",
...>   address: "0x1111111111111111111111111111111111111111",
...>   statement: "Access purchased content",
...>   uri: "https://example.com/protected",
...>   version: "1",
...>   chain_id: "eip155:1",
...>   nonce: "abc12345",
...>   issued_at: "2026-02-16T12:00:00Z",
...>   expiration_time: "2026-02-16T13:00:00Z"
...> }
iex> {:ok, message} = X402.Extensions.SIWX.encode(payload)
iex> X402.Extensions.SIWX.decode(message)
{:ok, payload}

@spec encode(map()) :: {:ok, String.t()} | {:error, encode_error()}

Encodes a SIWX payload into an EIP-4361 message.

:chain_id accepts either "eip155:<id>" or a positive integer. This is the strict pre-0.7.0 codec (every field, including :statement and :expiration_time, is required); message/1 builds the spec's message from proof fields.

Examples

iex> payload = %{
...>   domain: "example.com",
...>   address: "0x1111111111111111111111111111111111111111",
...>   statement: "Access purchased content",
...>   uri: "https://example.com/protected",
...>   version: "1",
...>   chain_id: "eip155:1",
...>   nonce: "abc12345",
...>   issued_at: "2026-02-16T12:00:00Z",
...>   expiration_time: "2026-02-16T13:00:00Z"
...> }
iex> {:ok, message} = X402.Extensions.SIWX.encode(payload)
iex> is_binary(message)
true

@spec extension_key() :: String.t()

Returns the extension key on the wire.

Examples

iex> X402.Extensions.SIWX.extension_key()
"sign-in-with-x"

@spec generate_nonce() :: String.t()

Generates a challenge nonce: 32 lowercase hex characters from 16 random bytes.

Examples

iex> nonce = X402.Extensions.SIWX.generate_nonce()
iex> String.length(nonce)
32

@spec message(map()) ::
  {:ok, String.t()} | {:error, X402.Extensions.SIWX.Message.build_error()}

Builds the CAIP-122 message text a wallet signs for a fields map.

Delegates to X402.Extensions.SIWX.Message.build/1; see it for the exact formats.

Examples

iex> {:ok, text} = X402.Extensions.SIWX.message(%{
...>   "domain" => "api.example.com",
...>   "address" => "BSmWDgE9ex6dZYbiTsJGcwMEgFp8q4aWh92hdErQPeVW",
...>   "uri" => "https://api.example.com",
...>   "version" => "1",
...>   "chainId" => "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
...>   "nonce" => "a1b2c3d4e5f67890a1b2c3d4e5f67890",
...>   "issuedAt" => "2024-01-15T10:30:00.000Z"
...> })
iex> String.split(text, "\n") |> Enum.take(3)
["api.example.com wants you to sign in with your Solana account:", "BSmWDgE9ex6dZYbiTsJGcwMEgFp8q4aWh92hdErQPeVW", ""]

@spec schema() :: map()

Returns the JSON schema of a proof, advertised under schema.

Examples

iex> X402.Extensions.SIWX.schema()["properties"]["issuedAt"]
%{"type" => "string", "format" => "date-time"}

@spec sign(map(), X402.Signer.t(), keyword()) ::
  {:ok, fields()} | {:error, sign_error()}

Signs a challenge with an X402.Signer, producing the proof fields.

challenge is the advertised extension value (%{"info" => ..., "supportedChains" => ...}) or its bare info map. The server's fields are copied verbatim, the signer's address (or :address) and the chain's chainId / type are added, and the CAIP-122 message is signed: eip155:* chains through X402.Signer.sign_message/2 (EIP-191), solana:* chains through X402.Signer.sign_ed25519/2 with the signature Base58-encoded.

Returns {:error, :unsupported_chain} when the chain's namespace is not supported or the challenge's supportedChains does not list it, {:error, :invalid_chain_id} for a malformed reference, {:error, :invalid_payload} when the challenge lacks required info fields, and signer errors (:unsupported_signer, :missing_dependency, ...) as they are.

Options

• :chain_id (String.t/0) - Required. CAIP-2 chain the proof is for; must be one the challenge supports.

• :address - Address to place in the proof; the signer's address when omitted. The default value is nil.

• :signature_scheme - Optional signatureScheme hint copied into the proof. The default value is nil.

Examples

iex> {:ok, signer} = X402.Signer.SolanaKey.new(:binary.copy(<<1>>, 32))
iex> challenge = X402.Extensions.SIWX.challenge(
...>   domain: "api.example.com",
...>   uri: "https://api.example.com",
...>   supported_chains: [%{chain_id: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"}]
...> )
iex> {:ok, signed} = X402.Extensions.SIWX.sign(challenge, signer, chain_id: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp")
iex> {signed["address"], signed["type"]}
{"AKnL4NNf3DGWZJS6cPknBuEGnVsV4A4m5tgebLHaRSZ9", "ed25519"}

iex> {:ok, signer} = X402.Signer.SolanaKey.new(:binary.copy(<<1>>, 32))
iex> challenge = X402.Extensions.SIWX.challenge(
...>   domain: "api.example.com",
...>   uri: "https://api.example.com",
...>   supported_chains: [%{chain_id: "eip155:8453"}]
...> )
iex> X402.Extensions.SIWX.sign(challenge, signer, chain_id: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp")
{:error, :unsupported_chain}

@spec validate_fields(map()) :: {:ok, fields()} | {:error, :invalid_payload}

Validates and normalizes spec-format proof fields.

Requires domain, address, uri, version ("1"), chainId, type, nonce, and issuedAt as non-empty strings; expirationTime, notBefore, requestId, statement, signatureScheme, and signature must be non-empty strings when present and resources a list of strings. Unknown keys are dropped. Accepts wire (camelCase string) keys or their snake_case atoms and always returns wire keys.

Examples

iex> {:ok, fields} = X402.Extensions.SIWX.validate_fields(%{
...>   domain: "api.example.com",
...>   address: "0x857b06519E91e3A54538791bDbb0E22373e36b66",
...>   uri: "https://api.example.com",
...>   version: "1",
...>   chain_id: "eip155:8453",
...>   type: "eip191",
...>   nonce: "a1b2c3d4e5f67890a1b2c3d4e5f67890",
...>   issued_at: "2024-01-15T10:30:00.000Z",
...>   resources: ["https://api.example.com/premium-data"]
...> })
iex> Map.keys(fields) |> Enum.sort()
["address", "chainId", "domain", "issuedAt", "nonce", "resources", "type", "uri", "version"]

iex> X402.Extensions.SIWX.validate_fields(%{"domain" => "api.example.com"})
{:error, :invalid_payload}