# `Parrhesia.API.Auth`

Public helpers for event validation and NIP-98 HTTP authentication.

This module is intended for callers that need a programmatic API surface:

- `validate_event/1` returns validator reason atoms.
- `compute_event_id/1` computes the canonical Nostr event id.
- `validate_nip98/3` and `validate_nip98/4` turn an `Authorization` header into a
  shared auth context that can be reused by the rest of the API surface.

For transport-facing validation messages, see `Parrhesia.Protocol.validate_event/1`.

# `compute_event_id`

```elixir
@spec compute_event_id(map()) :: String.t()
```

Computes the canonical Nostr event id for an event payload.

The event does not need to be persisted first. This is useful when building or signing
events locally.

# `validate_event`

```elixir
@spec validate_event(map()) :: :ok | {:error, term()}
```

Validates a Nostr event and returns validator-friendly error atoms.

This is the low-level validation entrypoint used by the API surface. Unlike
`Parrhesia.Protocol.validate_event/1`, it preserves the raw validator reason so callers
can branch on it directly.

# `validate_nip98`

```elixir
@spec validate_nip98(String.t() | nil, String.t(), String.t()) ::
  {:ok, Parrhesia.API.Auth.Context.t()} | {:error, term()}
```

Validates a NIP-98 `Authorization` header using default options.

# `validate_nip98`

```elixir
@spec validate_nip98(String.t() | nil, String.t(), String.t(), keyword()) ::
  {:ok, Parrhesia.API.Auth.Context.t()} | {:error, term()}
```

Validates a NIP-98 `Authorization` header and returns a shared auth context.

The returned `Parrhesia.API.Auth.Context` includes:

- the decoded auth event
- the authenticated pubkey
- a `Parrhesia.API.RequestContext` with `caller: :http`

Supported options are forwarded to `Parrhesia.Auth.Nip98.validate_authorization_header/4`,
including `:max_age_seconds` and `:replay_cache`.

---

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