30817:nip-xx-webrtc-sessions
NIP-XX: WebRTC Sessions
NIP-XX
Session Adverts
draft optional
This NIP defines an addressable event that announces a live, joinable session (a multiplayer game, a collaborative music jam, a shared whiteboard, a co-editing session, a watch party) and says how to join it: which application protocol it speaks, which relays to signal on, how many people it holds, and who is allowed in.
It covers discovery and admission rules only. Connecting peers is left to a signaling scheme such as NIP-100. Everything that happens inside the session belongs to the application protocol.
Motivation
Peers that want to connect need to agree on three things before any signaling can start: that a session exists, where to meet (relays and a room identifier), and whether they are allowed in. Today each application invents its own answer, usually a code shared out of band, and nothing says which relays to use. Two clients with different relay lists can sit in the "same" room and never see each other.
A shared advert format lets any client that speaks a given application protocol find sessions, including sessions hosted by a different client implementation of the same protocol.
Adverts are public. Sessions that should not be listed do not publish an advert. They reach people through invites: a gift-wrapped kind 2050 invite to a specific npub, or a link.
Event
Kind 35050: an addressable event. The number mirrors NIP-100's ephemeral signaling kind 25050, so the advert (where to meet) and the signaling (how to connect) are easy to pair. The content is an optional human-readable description and MAY be empty.
| Tag | Required | Format | Meaning |
|---|---|---|---|
d |
yes | ["d", <advert id>] |
Random identifier for this advert, at least 128 bits, hex. |
a (protocol) |
yes | ["a", <kind>:<pubkey>:<d>, <relay hint>, "protocol"] |
The application protocol, as the coordinate of the addressable event that defines it. Repeatable. See Protocol references. |
version |
yes | ["version", <protocol version>] |
Protocol version. Interpretation belongs to the protocol. |
relay |
yes | ["relay", <wss url>] |
Signaling relay. Repeatable; at least one. |
gate |
yes | see Gates | Who may join. Repeatable; all gates apply, except that an invited pubkey bypasses network gates (see invite). |
room |
see gates | ["room", <room id>] |
The signaling room identifier. MUST be absent from a public advert when any password gate is present. |
capacity |
no | ["capacity", <max>, <current>] |
Decimal integers. |
status |
no | ["status", "open" | "full" | "closed"] |
Defaults to open. |
identity |
no | ["identity", "account" | "any"] |
Whether participants must sign signaling with their Nostr account. Defaults to any. A network gate implies account. |
title |
no | ["title", <text>] |
Short human-readable name. |
client |
no | ["client", <identifier>] |
The client or app hosting the session, informational. |
expiration |
yes | ["expiration", <unix seconds>] |
NIP-40. SHOULD be at most 10 minutes ahead. |
The event's pubkey is the host. A host that does not want the session linked to its usual identity MAY sign the advert with a different key; participants then only know the host by that key.
Protocol references
The a tag with the protocol marker says what the session speaks by pointing at a Nostr event, not a free-text name. The referenced event is any addressable event that defines the protocol, published by whoever defines it. Different apps that implement the protocol reference the same coordinate and find each other's sessions, and nobody can claim a protocol just by picking the same name.
Relays index a, so clients filter adverts with #a. An app that speaks a protocol subscribes to adverts referencing it, so people already using that app see new sessions as they appear.
The reference also gives anyone who meets an advert or invite outside a compatible app a way forward. A general-purpose client that cannot run the session can still fetch the referenced protocol event, show what the session is, and use it as the key for finding an application that implements that protocol. How it finds one (application handler discovery, recommendations, a runtime's own catalog) is up to the client.
An advert MAY carry several protocol references, for example when a session is compatible with more than one protocol. A client lists the advert when any of them matches. The version tag versions the protocol, independently of the referenced event's own revisions.
Room identifiers
A room identifier is an opaque string the signaling scheme uses to scope a session. For open sessions the host generates at least 128 random bits and publishes them hex-encoded in the room tag. For password sessions both sides derive it (below). Clients pass the room identifier and the relay list to their signaling layer unchanged.
Gates
Each gate tag adds one condition. A participant must satisfy every gate, except that an invited pubkey bypasses network gates.
open
["gate", "open"]
Anyone may join. The room tag MUST be present. open MUST NOT be combined with other gates.
password
["gate", "password", <salt hex>, "pbkdf2-sha256", <iterations>]
The room identifier is never published. Host and participants derive it:
room = hex( PBKDF2-HMAC-SHA256( password, salt, iterations, 32 bytes ) )
passwordis the UTF-8 encoding of the user's input after Unicode NFKC normalization.saltMUST be at least 16 random bytes, unique per advert.iterationsMUST be at least 100,000 and SHOULD be at least 600,000.- The password is shared out of band and MUST NOT be sent to any relay or peer.
A participant without the password cannot find the signaling room, so it never reaches the host. A wrong password produces a room nobody is in; clients SHOULD time out with a message that suggests checking the password.
Other KDF identifiers MAY be defined later. Clients MUST ignore adverts whose KDF they do not support.
network
["gate", "network", "follows"]
["gate", "network", "follows-of-follows"]
["gate", "network", "list", <naddr>]
Only participants in the named network may join:
follows: pubkeys in the host's latest kind 3 (NIP-02).follows-of-follows: the above, plus pubkeys in their kind 3 lists.list: public items of the NIP-51 list atnaddr.
Network gates require participants to sign signaling with their Nostr account, since an anonymous key cannot belong to anyone's network. When there is no password gate, the room tag MUST be present: the network gate controls admission, not discovery.
invite
["gate", "invite"]
Only pubkeys the host invited may join, plus anyone who satisfies the advert's other gates if any are present. In practice:
invitealone: invite-only.invite+network: the host's network or anyone invited.invite+password: invited pubkeys still need the password unless their invite carries it.
The guest list is never published. The host keeps it and checks each peer's signaling pubkey against it before exchanging connection details. Invited participants MUST sign signaling with their Nostr account. An invite gate implies identity account.
When invite is the only gate, the public advert (if the host publishes one at all) MUST NOT carry a room tag. The room travels only inside invites.
Invites
There are two ways to invite people: an addressed invite to a specific npub, and a link anyone holding it can use.
Addressed invites
Kind 2050: a session invite. It is never published on its own. The host builds it as an unsigned NIP-59 rumor, seals it, and gift-wraps it to each invitee. The number follows the x050 pattern of NIP-100's 25050 and the advert's 35050.
It carries everything the invitee needs to join, so it works whether or not a public advert exists:
| Tag | Required | Format | Meaning |
|---|---|---|---|
p |
yes | ["p", <invitee pubkey>] |
The person invited. |
a (protocol) |
yes | as in the advert | Application protocol. |
version |
yes | as in the advert | Protocol version. |
relay |
yes | as in the advert | Signaling relays. |
room |
one of | ["room", <room id>] |
The room identifier. |
gate |
one of | ["gate", "password", <salt>, <kdf>, <iterations>] |
For password sessions: the KDF parameters, used with password or a password shared another way. |
password |
no | ["password", <password>] |
Saves the invitee a separate message. |
a (advert) |
no | ["a", "35050:<host pubkey>:<d>", <relay hint>, "advert"] |
The public advert, when one exists. Clients follow it for status and capacity. |
title |
no | as in the advert | Session name. |
expiration |
no | ["expiration", <unix seconds>] |
When the invite stops being valid. MAY be longer than a public advert's. |
The invite MUST carry either room or a password gate. content MAY hold a personal note. The rumor's pubkey is the host.
The gift wrap is published to the invitee's inbox relays (NIP-17 kind 10050, falling back to their NIP-65 read relays). The invitee's client unwraps it, checks that the rumor's pubkey matches the seal's author (as NIP-59 requires), and shows it as an invitation. Joining follows Joining using the invite's tags, with the user's account key. A client that cannot run the session SHOULD still show the invitation and resolve the protocol reference to help the user open it in an application that can (see Protocol references).
A forwarded invite does not admit anyone else: the host admits by signaling pubkey, not by possession of the invite. To revoke an invite, the host removes the pubkey from its guest list. To cancel the session for everyone, the host closes it as usual. Invitees that follow the advert reference see closed, and the rest find no host.
Invite links
A link lets anyone who holds it join, including people without a Nostr account. It is a nostr: URI holding a NIP-19 naddr for the session advert (kind 35050, the host's pubkey, the advert's d, and the signaling relays), followed by a fragment that carries what the advert does not:
nostr:naddr1…#room=<room id>
nostr:naddr1…#secret=<secret>
room=: the room identifier itself. Anyone with the link can join until the host moves the session to a new room.secret=: a random secret of at least 128 bits used in place of a password. The advert carries apasswordgate, and the room is derived from the secret with that gate's KDF. Hosts SHOULD use this form rather than putting a human-chosen password in a link.
The fragment is never sent to relays. Clients MUST NOT publish it in events. Links are bearer credentials: they cannot be made single-use or limited to one person without an admission check after connecting, which would expose the host's network address to whoever holds the link. Use addressed invites for that.
For unlisted sessions with no public advert, the naddr still identifies the host and relays. The fragment then MUST carry room=, and clients join without fetching an advert.
Joining
- Query for adverts with
{"kinds": [35050], "#a": [<protocol coordinate>, …]}on relays the client already reads, plus any relays the protocol recommends. - Discard adverts that are expired,
closed, have an unsupportedversionor KDF, or are malformed. - For
networkgates, clients SHOULD only list sessions the user qualifies for. The relevant lists are public, so the client can check this itself. - Determine the room identifier: the advert's or invite's
roomtag, a link fragment, or the password derivation (with an invite'spasswordwhen it carries one). - Open a signaling session in that room on the advert's
relayURLs, signing with the user's account whenidentityisaccountor anetworkorinvitegate is present. - The host admits or rejects each peer before exchanging connection details (see Host behavior).
Host behavior
- Republish the advert before
expirationwhile the session accepts participants, updatingcapacityandstatus. - On close, publish the advert with
["status", "closed"]and a shortexpiration, and MAY delete it with a NIP-09 deletion request. - Enforce every gate before exchanging connection details with a peer, not after. For
networkgates, check the peer's signaling pubkey against the network. Signaling layers that reveal network addresses (WebRTC offers, answers and candidates) SHOULD NOT send them to a peer the host has not admitted. - For
invitegates, keep the guest list privately and admit invited pubkeys even when they fail anetworkgate. - Enforce
capacitythe same way. Hosts MAY reserve seats for invitees. - Treat everything a peer sends after connecting as untrusted input to the application protocol.
Security and privacy considerations
- Adverts are public. Anyone can see that the host's key is running a session of a given protocol, when, and with roughly how many participants. Hosts who mind should sign with a key that is not their usual identity, or not publish an advert.
- Signaling metadata. Participants who sign signaling with their account reveal to relays which sessions they joined. That is the cost of
identity: account. - Password strength. The derivation stops casual joining and keeps the password off the wire. It does not stop offline guessing: anyone who observes signaling events that reference the derived room (or a hash of it) can test guesses against the salt. Use long passwords for anything sensitive.
- Network gates reveal nothing new about the network (the lists are public). Attempting to join reveals the joiner's pubkey to the host and to the signaling relays.
- Spoofed adverts. Anyone can publish an advert for any protocol. Clients SHOULD verify the protocol and version during the application handshake and SHOULD let users mute or block advert authors.
- Invites. Gift wrapping hides the invite's contents and its sender from relays. Relays can still see that the invitee received a gift wrap. An invite that carries a
passwordorroomis as sensitive as the password: anyone who compromises the invitee's key can read it, though the host still admits only the invited pubkey. - Invite links are bearer credentials. Anyone who sees the link can join. Share them over private channels and rotate the room when a link leaks.
- Network addresses. Peer-to-peer transports reveal network addresses to admitted peers. Gating before connection limits that exposure to people the host chose; relaying through TURN hides it entirely.
Relationship to other NIPs
- NIP-100 (draft): connects peers once they know the room and relays. This NIP supplies those inputs. The two can be used independently.
- NIP-02, NIP-51: source of
networkgate membership. - NIP-01:
acoordinates reference the protocol (and, in invites, the advert). - NIP-40, NIP-09: advert expiry and removal.
- NIP-59, NIP-17: kind
2050invites are gift-wrapped rumors delivered to the invitee's inbox relays. - NIP-19:
naddrin invite links.
Example
A password-protected jam session open to the host's follows and to anyone they invite:
{
"kind": 35050,
"pubkey": "<host pubkey>",
"created_at": 1763000000,
"content": "Sunday ambient jam, bring a synth",
"tags": [
["d", "6f1c0e3a9b2d4c8e7a5f1b3d9c2e4a6b"],
["a", "<protocol kind>:<protocol author pubkey>:jam-sync", "wss://relay.example.com", "protocol"],
["version", "1"],
["relay", "wss://relay.example.com"],
["relay", "wss://bucket.coracle.social"],
["gate", "password", "a3f9c1d27b4e86f05c9d3e1a7b2f4c60", "pbkdf2-sha256", "600000"],
["gate", "network", "follows"],
["gate", "invite"],
["identity", "account"],
["capacity", "6", "2"],
["status", "open"],
["title", "Sunday ambient jam"],
["expiration", "1763000600"]
],
"id": "<id>",
"sig": "<sig>"
}
A participant whom the host follows and who knows the password derives the room, opens signaling on the two relays with their account key, and is admitted after the host checks its follow list.
An addressed invite to the same session (the kind 2050 rumor, before sealing and gift wrapping):
{
"kind": 2050,
"pubkey": "<host pubkey>",
"created_at": 1763000100,
"content": "Come jam on Sunday",
"tags": [
["p", "<invitee pubkey>"],
["a", "35050:<host pubkey>:6f1c0e3a9b2d4c8e7a5f1b3d9c2e4a6b", "wss://relay.example.com", "advert"],
["a", "<protocol kind>:<protocol author pubkey>:jam-sync", "wss://relay.example.com", "protocol"],
["version", "1"],
["relay", "wss://relay.example.com"],
["relay", "wss://bucket.coracle.social"],
["gate", "password", "a3f9c1d27b4e86f05c9d3e1a7b2f4c60", "pbkdf2-sha256", "600000"],
["password", "<password>"],
["title", "Sunday ambient jam"],
["expiration", "1763604000"]
]
}
The invitee may not be one of the host's follows; the advert's invite gate admits them anyway, and the carried password spares them a second message.
Discussion
Connect a key to comment.