Nostr.Event.FileMessage (Nostr Lib v0.2.1) (event) (nip17)

Private File Message (Kind 15)

This is an unsigned event (rumor) for encrypted file messages per NIP-17. Messages MUST be wrapped in a Seal (kind 13) and GiftWrap (kind 1059) before publishing.

The file content is encrypted with AES-GCM and stored externally. The decryption key and nonce are included in the event tags.

Defined in NIP 17 https://github.com/nostr-protocol/nips/blob/master/17.md

Summary

Types

receiver()

Receiver with optional relay URL

t()

Functions

create(sender_pubkey, receiver_pubkeys, file_url, file_metadata, opts \\ [])

Create a new file message (unsigned rumor)

parse(rumor)

Parse a kind 15 event or rumor into a FileMessage struct

Types

receiver()

@type receiver() :: %{pubkey: binary(), relay: URI.t() | nil}

Receiver with optional relay URL

t()

@type t() :: %Nostr.Event.FileMessage{
  blurhash: binary() | nil,
  decryption_key: binary(),
  decryption_nonce: binary(),
  dimensions: %{width: non_neg_integer(), height: non_neg_integer()} | nil,
  encryption_algorithm: binary(),
  fallbacks: [binary()],
  file_type: binary(),
  file_url: binary(),
  hash: binary(),
  original_hash: binary() | nil,
  receivers: [receiver()],
  reply_to: binary() | nil,
  rumor: Nostr.Event.Rumor.t(),
  size: non_neg_integer() | nil,
  subject: binary() | nil,
  thumbnail: binary() | nil
}

Functions

create(sender_pubkey, receiver_pubkeys, file_url, file_metadata, opts \\ [])

@spec create(
  sender_pubkey :: binary(),
  receiver_pubkeys :: [binary() | map()],
  file_url :: binary(),
  file_metadata :: map(),
  opts :: Keyword.t()
) :: t()

Create a new file message (unsigned rumor)

Arguments

sender_pubkey - public key of the sender
receiver_pubkeys - list of receiver public keys (or maps with pubkey and optional relay)
file_url - URL of the encrypted file
file_metadata - map with file encryption metadata:
- :file_type - MIME type (required)
- :encryption_algorithm - e.g., "aes-gcm" (required)
- :decryption_key - symmetric key for decryption (required)
- :decryption_nonce - nonce for decryption (required)
- :hash - SHA-256 of encrypted file (required)
- :original_hash - SHA-256 of original file (optional)
- :size - file size in bytes (optional)
- :dimensions - %{width: w, height: h} for images (optional)
- :blurhash - blurhash preview (optional)
- :thumbnail - thumbnail URL (optional)
- :fallbacks - list of fallback URLs (optional)
opts - optional arguments:
- :reply_to - event ID this message is replying to
- :subject - conversation title
- :created_at - timestamp (defaults to now)

Example

iex> msg = Nostr.Event.FileMessage.create(
...>   "sender_pubkey",
...>   ["receiver_pubkey"],
...>   "https://example.com/file.enc",
...>   %{
...>     file_type: "image/jpeg",
...>     encryption_algorithm: "aes-gcm",
...>     decryption_key: "key123",
...>     decryption_nonce: "nonce456",
...>     hash: "abc123"
...>   }
...> )
iex> msg.file_url
"https://example.com/file.enc"
iex> msg.rumor.kind
15

parse(rumor)

@spec parse(Nostr.Event.Rumor.t() | Nostr.Event.t() | map()) :: t()

Parse a kind 15 event or rumor into a FileMessage struct