wownerogue/docs/CHAT_AND_NOSTR.md

Chat and Nostr

Chat has two layers: local delivery (Socket.IO plus Postgres history) and an optional nostr fan-out that carries the same conversation across servers and into the Smirk ecosystem. Both sit behind one seam, so callers are identical either way.

The provider seam

src/network/chat/ChatProvider.js is the abstraction every chat caller uses:

publish(msg)                 deliver and (optionally) persist a message
getHistory({scope, limit})   recent messages, oldest to newest
relaySignedEvent(req)        deliver a client-signed nostr event (per-player identity)
initialize() / shutdown()

Application concerns (commands, moderation, rate limiting, HTML escaping) stay in the caller; a provider only delivers and stores.

Two implementations:

• SocketChatProvider is the default. Scope global persists through ChatHistoryManager and broadcasts chat_broadcast to every client; a room scope such as tavern:<id> delivers only to that Socket.IO room and persists nothing. Broadcasts carry a short publicId (the user id, or the first 6 characters of the socket id) rather than the full socket id.
• NostrChatProvider decorates a local provider. Every message still delivers in-game and persists; in addition, global messages fan out to nostr relays, and messages arriving from a relay are delivered locally only, never re-published, so there are no echo loops.

buildChatProvider({local, env}) in src/network/chat/index.js chooses between them. With NOSTR_CHAT_ENABLED unset, or with NOSTR_CHAT_SCOPE set to anything other than global, it returns the plain local provider unchanged; otherwise it wraps that provider in a NostrChatProvider.

ChatHandler constructs the local provider (sharing its own ChatHistoryManager instance so ban checks and stats keep working) and passes it through buildChatProvider.

Unified global chat

TavernManager accepts the lobby's provider as globalChatProvider and publishes tavern messages to the global scope, sending the global backlog as chat_history on join. Lobby and tavern are therefore one conversation with persistent history, and when nostr is enabled tavern chat rides the relay too. When no global provider is injected, the tavern falls back to its own room-scoped, ephemeral provider.

Topology is always client to server to relay. The server remains the moderation authority (bans, rate limits, history in Postgres); the relay is transport and fan-out.

Identity models

NostrChatProvider takes an injectable signer with the contract { pubkey, sign(template) }. That one object is the whole difference between the two identity models.

Server bridge signer

The server signs every outbound global message with a single key from NOSTR_BRIDGE_SK (createBridgeSigner, accepting an nsec or 64-hex secret). The player's display name rides in an ['n', name] tag. This works for every player, including anonymous ones, but on nostr the whole server reads as one account. The bridge pubkey must be accepted by the relay's write policy, either by being a registered npub or by sitting in the relay write allowlist. With no key configured the signer is null and global chat is receive-only.

Client per-player signing

The client signs with the player's own Smirk npub and sends the finished event; the server verifies it and relays it unmodified, so on nostr the author is genuinely the player.

client                          server (ChatHandler)                  relay
  build kind-1 event
  window.smirk.signNostrEvent
  emit chat_signed {event}  -->  rate limit
                                 look up session npub
                                 verifyChatEvent(event, npub)
                                   signature, id, freshness, channel tag,
                                   pubkey equals session npub
                                 relaySignedEvent            ---------->  published under
                                                                          the player's npub
       <-------------------  chat_broadcast (all in-game clients)

• src/utils/verifyChatEvent.js is the security core. It validates shape and types, rebuilds a clean event from primitives only, independently recomputes the event id, verifies the BIP-340 schnorr signature, enforces freshness (120 seconds by default), and requires the t tag to match the configured channel tag so the server cannot be used to relay arbitrary events. Critically, event.pubkey must equal the session's authenticated npub (users.smirk_public_key, set at NIP-98 login); a valid signature by any other key is rejected with pubkey-mismatch. Content is capped at 280 characters.
• ChatHandler.handleSignedChatMessage runs the sequence: rate limit, resolve the session's npub from the database, verify, escape, relay. A session with no linked npub is told to sign in with Smirk. The display name comes from display_name or username, falling back to the first 8 characters of the npub.
• NostrChatProvider.relaySignedEvent performs local delivery and then transport.publish(event) with no re-signing, marking the event id as seen so the relay round-trip does not deliver it twice.
• html/js/smirkChatSign.js is the client helper. It signs through window.smirk.signNostrEvent and emits chat_signed. Signing is attempted first; on NOT_AUTHORIZED it calls getNostrPublicKey() once to obtain the nostr scope grant and retries, the same pattern as SmirkAuth, so a returning user sees a single approval. It resolves false whenever Smirk is unavailable or declines, and the caller then falls back to the ordinary unsigned send. The helper is loaded on tavern.html, whose send path tries it before tavern_chat.

The server registers the chat_signed socket event in src/network/socketHandlers.js.

Relays and tiers

The game publishes each event to every relay in NOSTR_RELAYS and lets each relay's policy accept or reject it; there is no per-player routing or allowlist in game code. Reading is the mirror: subscribe to all relays and dedupe by event id.

Player	Signs as	Reaches
Anonymous	not signed	in-game chat only
Signed in with Smirk	own npub	in-game chat plus every relay whose write policy accepts that npub

A premium subscription also sets the player's entitlement tier, which unlocks cosmetics; see MONETIZATION.md. Entitlements are per-pack tier based (src/multiplayer/entitlements.js): buying credits maps to tier 0 and unlocks packs by lifetime credits purchased, while a subscription tier unlocks the packs at or below that tier.

Relay policy (smirk-backend-core)

Relay admission is configured on the relay side, in the Smirk backend that fronts nostr-rs-relay:

• RELAY_WRITE_POLICY is one of inbox-outbox (the default), author-allowlist, open, or premium-post. premium-post lets registered users publish wallet kinds and reserves general posting for premium members; PREMIUM_ENABLED requires this policy.
• RELAY_WRITE_ALLOWLIST_NPUBS (comma-separated npub1… or hex) exempts specific keys from the policy. This is how a server bridge key is registered.
• RELAY_INBOUND_POW_BITS applies a NIP-13 proof-of-work gate to authors that are not registered or allowlisted, so registered and allowlisted npubs post without PoW.
• Reading is open under every policy.

Moderation and limits

• Inbound chat is rate limited through the shared RateLimiter under the chat:message bucket (12 messages per 10 seconds), keyed by a stable session id plus client IP so reconnecting cannot reset it. Plain lobby broadcasts add a 2 second per-socket cooldown; tavern occupants have a 900 ms per-occupant cooldown.
• Lobby messages are rejected above 200 characters and HTML-escaped before delivery. Signed messages are escaped and capped at 200 characters for in-game rendering; the event published to nostr is the client's original, unmodified.
• Chat bans are checked against ChatHistoryManager.isUserChatBanned before a message is published. The tavern applies the same rate limiter and ban check before anything reaches global chat.
• Remote (relay-sourced) messages are escaped with escapeChatText, capped at 200 characters, attributed from the n tag or the first 8 characters of the author pubkey, and rate limited to maxRemotePerMin (120 per minute by default) so a hostile relay cannot flood in-game clients.
• Event ids are deduped through a bounded FIFO of the last 1000 ids, covering both the server's own echoes and repeats across relays.
• The relay subscription filters on since = now at startup, so connecting does not flood clients with history; local Postgres history covers the past.
• NostrTransport degrades to a warning and a no-op if nostr-tools or ws cannot load, so enabling nostr chat cannot crash the server.

Configuration

Variable	Meaning
NOSTR_CHAT_ENABLED	Master switch. Unset means plain local chat. Accepts 1, true, yes, on.
NOSTR_CHAT_SCOPE	global (fan out) or anything else (plain local provider). Default global.
NOSTR_RELAYS	Comma-separated relay URLs. Default wss://relay.smirk.cash.
NOSTR_CHAT_TAG	Shared channel topic. Default wowngeon-global.
NOSTR_CHAT_KIND	Event kind. Default 1.
NOSTR_BRIDGE_SK	Bridge secret key (nsec or 64-hex). Omit for receive-only global chat.
NOSTR_SERVER_ORIGIN	Value for the origin tag on bridge-signed events. Falls back to SERVER_ID.

The full server environment template is src/.env.example.

Loader shim

nostr-tools pulls ESM-only dependencies. loadNostrTools() in src/utils/nostrLoader.js require()s the package under Node 22, which natively requires those dependencies, and falls back to the pre-bundled self-contained IIFE build under a CJS-only test runtime. Chat and NIP-98 auth both load nostr through it.

Files

src/network/chat/ChatProvider.js           seam, including the default relaySignedEvent
src/network/chat/SocketChatProvider.js     local delivery and history
src/network/chat/NostrChatProvider.js      decorator: local plus nostr fan-out plus signed relay
src/network/chat/index.js                  buildChatProvider (env to provider)
src/network/chat/nostr/NostrTransport.js   SimplePool wrapper, multi-relay, degrades to no-op
src/network/chat/nostr/bridgeSigner.js     server bridge signer
src/network/chatHandler.js                 commands, moderation, signed-event handling
src/network/tavernManager.js               tavern chat routed into global chat
src/utils/verifyChatEvent.js               verify a client-signed event (impersonation guard)
src/utils/escapeChat.js                    HTML escape and length cap
src/utils/nostrLoader.js                   nostr-tools loader shim
html/js/smirkChatSign.js                   client per-player signing helper