Kind 15: File Message

Overview

File Message events (kind 15) are used for sharing encrypted files in direct messages. They extend the private messaging system defined in NIP-17, providing a structured way to transmit file metadata and references while maintaining privacy and security.

Specification

Property	Value
Kind Number	15
Event Range	Regular
Defined in	NIP-17

Content Format

The content field contains the URL where the encrypted file can be accessed.

Schema

"content": "https://example.com/path/to/encrypted_file.jpg"

Tags

Tag Name	Description	Format	Required
p	Recipient public key(s)	["p", "<pubkey-hex>", "<relay-url>"]	Yes
file-type	MIME type of the file	["file-type", "image/jpeg"]	Yes
encryption-algorithm	Algorithm used for file encryption	["encryption-algorithm", "aes-gcm"]	Yes
decryption-key	Key for decrypting the file	["decryption-key", "<key>"]	Yes
decryption-nonce	Nonce for decryption	["decryption-nonce", "<nonce>"]	Yes
x	SHA-256 hash of the file	["x", "<hex-encoded-hash>"]	Yes
e	Referenced message (for replies)	["e", "<event-id>", "<relay-url>"]	No
subject	Conversation title/topic	["subject", "Conversation subject"]	No
size	File size in bytes	["size", "1024000"]	No
dim	Image dimensions	["dim", "1920x1080"]	No
blurhash	BlurHash for image preview	["blurhash", "<blurhash-code>"]	No
thumb	URL for thumbnail	["thumb", "<thumbnail-url>"]	No
fallback	Backup file sources	["fallback", "<fallback-url>"]	No

Client Behavior

Clients should:

1. Create file messages as unsigned kind 15 events (rumors)

2. Never sign or broadcast raw kind 15 events directly

3. Encrypt the actual file being shared using the specified encryption algorithm

4. Upload the encrypted file to a file hosting service

5. Create a kind 15 event with the file URL and decryption information

6. Encrypt and wrap the message using the NIP-59 Gift Wrap protocol:

   • Wrap the unsigned message in a Seal (kind 13)
   • Wrap the Seal in a Gift Wrap (kind 1059)
   • Create individual wrapped messages for each recipient
   • Create a copy for the sender too, for consistent history display

7. When receiving file messages:

   • Unwrap the Gift Wrap and Seal layers
   • Verify that the inner message's pubkey matches the Seal's pubkey
   • Download the encrypted file from the provided URL
   • Decrypt the file using the provided decryption key and nonce
   • Validate the file hash against the provided x tag
   • Display the file appropriately based on its MIME type

Relay Behavior

Relays should:

1. Only serve kind 1059 Gift Wrap events to their intended recipients
2. Consider requiring authentication (NIP-42) for DM access
3. Not retain or log the encrypted content of messages
4. Note that relays do not typically host the actual file content - only the event metadata

Use Cases

• Sharing images in private conversations
• Exchanging documents securely
• Sending audio or video files privately
• Encrypted backup of important files
• Secure transmission of sensitive information

Example

// Note: This is how the UNSIGNED event looks before being sealed and wrapped
{
  "id": "4376c65d2f232afbe9b882a35baa4f6fe8667c4e684749af565f981833ed6a65",
  "pubkey": "79dff8f82963424e0bb02708a22e44b4980893e3a4be0fa3cb60a43b946764e3",
  "created_at": 1671217411,
  "kind": 15,
  "tags": [
    ["p", "f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca", "wss://relay.example.com"],
    ["file-type", "image/jpeg"],
    ["encryption-algorithm", "aes-gcm"],
    ["decryption-key", "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"],
    ["decryption-nonce", "q1w2e3r4t5y6u7i8"],
    ["x", "3f8e512f9a0435b63c4ca9a9748eb474b04cd72c9b02c5f9133e577e4c6f3cd4"],
    ["size", "2621440"],
    ["dim", "1920x1080"],
    ["blurhash", "LGF5]+Yk^6#M@-5c,1J5@[or[Q6."]
  ],
  "content": "https://example.com/files/encrypted_vacation_photo.jpg"
}

// This event would never be broadcast directly - it would be wrapped in a Seal and Gift Wrap

Security Considerations

1. File Encryption: Files should be encrypted before uploading to prevent the hosting service from accessing the content.
2. Metadata Protection: The event containing file information is encrypted using the Gift Wrap protocol.
3. Hash Verification: The x tag provides a hash of the file for integrity verification.
4. File Type Validation: Clients should verify the MIME type before opening files to prevent malicious content.

References

• NIP-17: Private Direct Messages
• NIP-59: Gift Wrap
• NIP-44: Encrypted Payloads

Related Kinds

• Kind 14: Direct Message - Text-based direct messages
• Kind 13: Seal - Used to wrap and sign the message
• Kind 1059: Gift Wrap - Outer encryption layer

Notes

• Like kind 14 messages, kind 15 file messages must never be signed or broadcast directly
• The hosting of the actual file content is outside the Nostr protocol
• The BlurHash tag allows clients to show a blurred preview of images while downloading
• Multiple fallback URLs can be provided for redundancy
• Despite the encryption of the event metadata, the file size and type are still potentially visible to the file hosting provider