Skip to content

02.md

Latest commit

 

History

History
159 lines (112 loc) · 7.83 KB

02.md

File metadata and controls

159 lines (112 loc) · 7.83 KB
Raw

MIP-02

Welcome Events

review mandatory

This document defines Welcome Events (kind: 444) that enable secure group invitations in Marmot Protocol. Welcome Events provide everything new members need to join groups and start participating.

Welcome Event Flow

The Process

  1. Admin commits: Group admin includes a new member via a Commit message
  2. Wait for confirmation: Admin waits for relay acknowledgment of the Group Event
  3. Send Welcome: Admin sends a private Welcome Event to the new member
  4. New member joins: New member processes the Welcome and can start messaging

Timing Requirements

Clients creating Welcome Events MUST:

  1. Wait for confirmation: Don't send the Welcome until relays confirm receipt of the Commit
  2. Process before welcoming: Ensure the group state change is committed before inviting

This sequencing prevents race conditions where a new member receives a Welcome for a group state that hasn't been finalized yet.

CRITICAL: State Fork Prevention

This timing requirement applies to ALL member additions after initial group creation. When adding members to an existing group, the Commit message MUST be accepted by relays BEFORE sending the Welcome message.

Why this matters: The Welcome message contains the group state at a specific epoch. If the Welcome is delivered before the Commit reaches existing members, a state fork occurs:

  • The new member activates at epoch N+1 (from the Welcome)
  • Existing members remain at epoch N (haven't received the Commit yet)
  • Messages sent by the new member cannot be decrypted by existing members
  • Messages sent by existing members cannot be decrypted by the new member
  • The group state diverges, requiring manual recovery

This is not a theoretical concern—distributed relay networks can deliver messages out of order. The only reliable prevention is waiting for relay confirmation of the Commit before sending the Welcome.

Note: Initial group creation (single-member group with no prior epochs) does not require this wait because there are no existing members who could have a conflicting state.

Privacy and Security

Welcome Events use NIP-59 gift-wrapping for privacy and unlinkability.

Welcome Event Structure

{
  "id": "def456...",
  "kind": 444,
  "created_at": 1693876600,
  "pubkey": "02a1633cafe37eeebe2b39b4ec5f3d74c35e61fa7e7e6b7b8c5f7c4f3b2a1b2c3d",
  "content": "MDk4NzY1NDMyMWZlZGNiYS4uLg==",
  "tags": [
    ["e", "keypackage_event_id_123..."],
    ["relays", "wss://relay1.com", "wss://relay2.com"],
    ["encoding", "base64"]
  ]
}

Important: This event is NOT signed ("sig" field omitted) to prevent accidental public publishing if it leaks.

Field Details

Required fields:

  • content: Serialized MLSMessage containing the MLS Welcome object, base64-encoded.
  • encoding: Specifies the encoding format of the content field. MUST be ["encoding", "base64"]. Implementations MUST reject events with missing or unrecognized encoding tags. Hex encoding was used by early implementations but is no longer supported and MUST be rejected.
  • e tag: ID of the KeyPackage Event used to add this user
  • relays tag: List of relays where the new member should look for Group Events

Security note: The unsigned nature prevents the event from being accidentally published to public relays, as most relays reject unsigned events.

Welcome Event Content

MLS Welcome Object

The content field contains a base64-encoded MLS Welcome object. The encoding format (base64 or hex) is specified by the encoding tag. The Welcome object includes:

  • Group secrets: Cryptographic keys needed to decrypt group messages
  • Group state: Current member list and group configuration
  • Ratchet tree: Key tree structure for the group
  • Extensions: Group metadata including Marmot Group Data Extension

Processing Requirements

When receiving a Welcome Event, clients MUST:

  1. Verify KeyPackage match: Ensure the referenced KeyPackage belongs to this user
  2. Process MLS Welcome: Use MLS library to process the Welcome and join the group
  3. Validate group state: Verify all group extensions and configurations, including the mandatory Marmot Group Data Extension (0xF2EE)
  4. Store group information: Save group keys, member list, and relay information
  5. Rotate KeyPackage: Remove the consumed KeyPackage from relays, optionally post a new fresh Keypackage
  6. Delete init_key: Securely delete the private init_key material from local storage (see MIP-00 Private Key Material Management)
  7. Perform self-update: Create and commit an Update proposal for your own LeafNode before sending any application messages (see below)

Post-Join Self-Update Requirement

After successfully processing a Welcome message, clients SHOULD perform a self-update (MLS Update proposal for their own LeafNode) before sending any application messages. This is strongly recommended for forward secrecy.

Why Self-Update Matters

When a member joins via a Welcome message, their LeafNode contains the key material from the KeyPackage that was used to add them. This means:

  1. The init_key was potentially exposed: The KeyPackage was published to relays and may have been observed or captured by adversaries
  2. Forward secrecy is limited: Until the member updates their LeafNode, any compromise of the init_key private material could allow decryption of group secrets

By performing an immediate self-update:

  • Fresh key material is generated that was never published or observable
  • The group epoch advances, providing forward secrecy for subsequent messages
  • The risk window from KeyPackage exposure is minimized

Self-Update Timing

  • RECOMMENDED: Perform self-update immediately after processing Welcome, before sending any application messages
  • MUST: Perform self-update within 24 hours of joining the group

Implementation Note

Self-update Commits are explicitly allowed from any group member, regardless of admin status (see MIP-03). This ensures all members can maintain their own key hygiene without requiring admin privileges.

Large Groups

For groups above ~150 participants, welcome messages will become larger than is permitted by many Nostr relays. There is currently work underway on the MLS protocol to support "light" client Welcome objects that don't require the full Ratchet Tree state to be sent to the new member. This section will be updated with recommendations for how to handle large groups.

Error Handling

Welcome Processing Failures

If Welcome processing fails, clients SHOULD:

  1. Retain KeyPackage: Do NOT delete the KeyPackage from relays
  2. Display clear errors: Show user-friendly error messages
  3. Log technical details: Capture technical information for debugging

Common Failure Scenarios

  • Signing key unavailable: KeyPackage was created on a different device thus the secret key for the KeyPackage used to add the user to the group is not available.

Summary

Welcome Events are the secure onboarding mechanism for Marmot groups:

Key Components

  1. MLS Welcome Object: Contains all cryptographic material for group access
  2. Gift-Wrapping: Provides privacy and unlinkability using NIP-59
  3. KeyPackage Reference: Links Welcome to the consuming KeyPackage
  4. Relay Information: Tells new members where to find Group Events

Implementation Requirements

MUST implement:

  • NIP-59 gift-wrapping with unsigned events
  • Proper timing (wait for Commit confirmation)
  • KeyPackage lifecycle management (relay deletion)
  • Private init_key secure deletion after Welcome processing
  • Self-update within 24 hours of joining (RECOMMENDED: immediately before sending messages)
  • Graceful error handling with clear user messages