Nostr.NIP98 (Nostr Lib v0.2.1) (nip98)

NIP-98: HTTP Auth helpers.

This module validates the event-side semantics of NIP-98 HTTP authorization events (kind 27235).

Summary

Types

payload_policy()

How payload validation should be applied.

request_context()

Request data required to validate a NIP-98 event against an HTTP request.

validation_error()

Validation errors returned by validate_request/3.

Functions

payload_hash(payload)

Computes a SHA256 hash hex string for request payload bytes.

validate_request(event_or_auth, request_context, opts \\ [])

Validates a NIP-98 HTTP auth event against request context.

Types

payload_policy()

@type payload_policy() :: :if_present | :require | :ignore

How payload validation should be applied.

request_context()

@type request_context() :: %{
  :url => String.t(),
  :method => String.t(),
  optional(:body) => binary() | nil,
  optional(:payload_hash) => String.t() | nil
}

Request data required to validate a NIP-98 event against an HTTP request.

validation_error()

@type validation_error() ::
  :invalid_request_context
  | :invalid_kind
  | :missing_created_at
  | {:created_at_too_old, now_unix :: integer(), event_unix :: integer()}
  | {:created_at_too_new, now_unix :: integer(), event_unix :: integer()}
  | :missing_u_tag
  | :missing_method_tag
  | :duplicate_u_tag
  | :duplicate_method_tag
  | :duplicate_payload_tag
  | {:url_mismatch, expected :: String.t(), got :: String.t()}
  | {:method_mismatch, expected :: String.t(), got :: String.t()}
  | :missing_payload_tag
  | :invalid_payload_tag
  | :invalid_payload_hash
  | :missing_request_body
  | {:payload_mismatch, expected :: String.t(), got :: String.t()}
  | :non_empty_content

Validation errors returned by validate_request/3.

Functions

payload_hash(payload)

@spec payload_hash(binary()) :: String.t()

Computes a SHA256 hash hex string for request payload bytes.

validate_request(event_or_auth, request_context, opts \\ [])

@spec validate_request(
  Nostr.Event.t() | Nostr.Event.HttpAuth.t(),
  request_context(),
  Keyword.t()
) ::
  :ok | {:error, validation_error()}

Validates a NIP-98 HTTP auth event against request context.

This function validates only event semantics. Authorization header decoding, replay protection, and pubkey authorization policy are intentionally out of scope and should be handled by application/adapter layers.

Options

:max_age_seconds - max age of event from now (default: 60)
:max_future_seconds - allowed future skew (default: 0)
:now - current time as DateTime.t() or unix seconds
:payload_policy - one of :if_present, :require, :ignore (default: :if_present)
:enforce_content_empty? - enforce empty content (default: false)