Nostr.NIP51 (Nostr Lib v0.2.1) (nip51)

View Source

NIP-51 Lists - Shared utilities for list event types.

This module provides common functionality for all NIP-51 list types including:

  • Encryption/decryption of private list items
  • Tag parsing utilities
  • Auto-detection of encryption version (NIP-44 vs legacy NIP-04)

Encryption

Private items in lists are encrypted using the author's own keys (shared key computed from author's public and private key). New lists should use NIP-44 encryption. For backward compatibility, this module can decrypt both NIP-44 and legacy NIP-04 encrypted content.

Detection is automatic: NIP-04 ciphertext contains ?iv= suffix, NIP-44 does not.

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

Summary

Functions

decrypt_private_items(content, seckey, pubkey)

Decrypts private list items with auto-detection of encryption version.

detect_encryption_version(content)

Detects whether encrypted content uses NIP-04 or NIP-44 encryption.

encrypt_private_items(tags, seckey, pubkey)

Encrypts private list items using NIP-44.

get_identifier(event)

Extracts the d tag identifier from a parameterized replaceable event.

get_set_metadata(event)

Extracts optional set metadata (title, image, description) from an event.

get_tag_values(event, type)

Extracts tag data values of a specific type from an event.

get_tags_by_type(event, type)

Extracts tags of a specific type from an event.

tag_to_array(list)

Converts a tag to its JSON array representation.

Functions

decrypt_private_items(content, seckey, pubkey)

@spec decrypt_private_items(binary(), binary(), binary()) ::
  {:ok, [Nostr.Tag.t()]} | {:error, term()}

Decrypts private list items with auto-detection of encryption version.

Automatically detects whether the content is encrypted with NIP-44 or legacy NIP-04 by checking for the ?iv= suffix that NIP-04 uses.

Parameters

  • content - Encrypted content from event
  • seckey - Author's secret key (hex-encoded)
  • pubkey - Author's public key (hex-encoded)

Returns

  • {:ok, tags} - List of parsed Nostr.Tag structs
  • {:error, reason} - Decryption or parsing failed

Example

iex> {:ok, tags} = Nostr.NIP51.decrypt_private_items(content, seckey, pubkey)
iex> Enum.map(tags, & &1.type)
[:p, :t, :word]

detect_encryption_version(content)

@spec detect_encryption_version(binary()) :: :nip04 | :nip44

Detects whether encrypted content uses NIP-04 or NIP-44 encryption.

NIP-04 ciphertext has the format: <base64_ciphertext>?iv=<base64_iv> NIP-44 ciphertext is plain base64 without the ?iv= suffix.

Returns

  • :nip04 - Legacy NIP-04 encryption detected
  • :nip44 - Modern NIP-44 encryption (default)

encrypt_private_items(tags, seckey, pubkey)

@spec encrypt_private_items([Nostr.Tag.t() | list()], binary(), binary()) :: binary()

Encrypts private list items using NIP-44.

The private items are a list of tags that will be JSON-encoded and encrypted using the author's own keypair (same pubkey as sender and recipient).

Parameters

  • tags - List of Nostr.Tag structs or raw tag arrays
  • seckey - Author's secret key (hex-encoded)
  • pubkey - Author's public key (hex-encoded)

Returns

Base64-encoded encrypted payload (NIP-44 format)

Example

iex> tags = [Nostr.Tag.create(:p, "abc123"), Nostr.Tag.create(:t, "nostr")]
iex> Nostr.NIP51.encrypt_private_items(tags, seckey, pubkey)
"AgKK5..."

get_identifier(event)

@spec get_identifier(Nostr.Event.t()) :: binary() | nil

Extracts the d tag identifier from a parameterized replaceable event.

Returns

  • identifier - The d tag value if present
  • nil - If no d tag exists

get_set_metadata(event)

@spec get_set_metadata(Nostr.Event.t()) :: %{
  title: binary() | nil,
  image: binary() | nil,
  description: binary() | nil
}

Extracts optional set metadata (title, image, description) from an event.

Returns

Map with :title, :image, and :description keys (values may be nil)

get_tag_values(event, type)

@spec get_tag_values(Nostr.Event.t(), atom()) :: [binary()]

Extracts tag data values of a specific type from an event.

Convenience function that returns just the data field of matching tags.

Parameters

Returns

List of data values (strings)

get_tags_by_type(event, type)

@spec get_tags_by_type(Nostr.Event.t(), atom()) :: [Nostr.Tag.t()]

Extracts tags of a specific type from an event.

Parameters

  • event - A Nostr.Event struct
  • type - Tag type atom (e.g., :p, :e, :t, :relay)

Returns

List of matching Nostr.Tag structs

tag_to_array(list)

@spec tag_to_array(Nostr.Tag.t() | list()) :: list()

Converts a tag to its JSON array representation.

Examples

iex> Nostr.NIP51.tag_to_array(Nostr.Tag.create(:p, "abc123"))
["p", "abc123"]

iex> Nostr.NIP51.tag_to_array(["e", "event_id", "wss://relay.com"])
["e", "event_id", "wss://relay.com"]