feat(nip43): add join/leave request event strategies

.changeset/nip43-join-leave.md

@@ -0,0 +1,5 @@
+---
+"nostream": minor
+---
+
+Add NIP-43 join/leave request event strategies (kinds 28934/28936) with NIP-42 auth enforcement, created_at freshness validation, invite code claiming, and admission management. When `nip43.enabled` is set, publishing is restricted to admitted members even without payments enabled, and NIP-43 is advertised in the NIP-11 document (hidden when disabled). Join/leave update the admission cache so membership changes take effect immediately.

.knip.json

@@ -14,8 +14,7 @@
     "lzma-native"
   ],
   "ignore": [
-    ".nostr/**",
-    "src/repositories/invite-code-repository.ts"
+    ".nostr/**"
   ],
   "commitlint": false,
   "eslint": false,

package.json

@@ -22,6 +22,7 @@
     28,
     33,
     40,
+    43,
     44,
     45,
     50,

resources/default-settings.yaml

@@ -60,6 +60,11 @@ nip05:
   domainWhitelist: []
   # Block authors with NIP-05 at these domains
   domainBlacklist: []
+nip43:
+  # NIP-43: invite-based relay membership. When enabled, only admitted members
+  # (users who claimed an invite code via a kind 28934 join request) may
+  # publish events. Enabling this on an open relay blocks all non-members.
+  enabled: false
 nip45:
   enabled: true
 nip50:

src/@types/repositories.ts

@@ -56,6 +56,7 @@ export interface IUserRepository {
   isVanished(pubkey: Pubkey, client?: DatabaseClient): Promise<boolean>
   setVanished(pubkey: Pubkey, vanished: boolean, client?: DatabaseClient): Promise<number>
   admitUser(pubkey: Pubkey, admittedAt: Date, client?: DatabaseClient): Promise<void>
+  revokeAdmission(pubkey: Pubkey, client?: DatabaseClient): Promise<number>
 }
 
 export interface INip05VerificationRepository {
@@ -72,4 +73,3 @@ export interface IInviteCodeRepository {
   findActiveCodes(limit?: number): Promise<InviteCode[]>
   deleteExpiredCodes(): Promise<number>
 }
-

src/constants/caching.ts

@@ -3,3 +3,5 @@ export enum CacheAdmissionState {
   BLOCKED_NOT_ADMITTED = 'blocked_not_admitted',
   BLOCKED_INSUFFICIENT_BALANCE = 'blocked_insufficient_balance',
 }
+
+export const admissionCacheKey = (pubkey: string): string => `${pubkey}:is-admitted`

src/factories/event-strategy-factory.ts

@@ -1,4 +1,5 @@
-import { IEventRepository, IUserRepository } from '../@types/repositories'
+import { ICacheAdapter, IWebSocketAdapter } from '../@types/adapters'
+import { IEventRepository, IInviteCodeRepository, IUserRepository } from '../@types/repositories'
 import {
   isDeleteEvent,
   isEphemeralEvent,
@@ -9,6 +10,7 @@ import {
   isReplaceableEvent,
   isRequestToVanishEvent,
 } from '../utils/event'
+import { isNip43JoinRequest, isNip43LeaveRequest } from '../utils/nip43'
 import { isRelayListEvent } from '../utils/nip65'
 import { DefaultEventStrategy } from '../handlers/event-strategies/default-event-strategy'
 import { DeleteEventStrategy } from '../handlers/event-strategies/delete-event-strategy'
@@ -18,16 +20,21 @@ import { Factory } from '../@types/base'
 import { GiftWrapEventStrategy } from '../handlers/event-strategies/gift-wrap-event-strategy'
 import { GroupEventStrategy } from '../handlers/event-strategies/group-event-strategy'
 import { IEventStrategy } from '../@types/message-handlers'
-import { IWebSocketAdapter } from '../@types/adapters'
+import { JoinRequestEventStrategy } from '../handlers/event-strategies/join-request-event-strategy'
+import { LeaveRequestEventStrategy } from '../handlers/event-strategies/leave-request-event-strategy'
 import { ParameterizedReplaceableEventStrategy } from '../handlers/event-strategies/parameterized-replaceable-event-strategy'
 import { ReplaceableEventStrategy } from '../handlers/event-strategies/replaceable-event-strategy'
+import { Settings } from '../@types/settings'
 import { TimestampEventStrategy } from '../handlers/event-strategies/timestamp-event-strategy'
 import { VanishEventStrategy } from '../handlers/event-strategies/vanish-event-strategy'
 
 export const eventStrategyFactory =
   (
     eventRepository: IEventRepository,
     userRepository: IUserRepository,
+    inviteCodeRepository: IInviteCodeRepository,
+    cache: ICacheAdapter,
+    settings: () => Settings,
   ): Factory<IEventStrategy<Event, Promise<void>>, [Event, IWebSocketAdapter]> =>
   ([event, adapter]: [Event, IWebSocketAdapter]) => {
     if (isRequestToVanishEvent(event)) {
@@ -40,6 +47,12 @@ export const eventStrategyFactory =
       return new TimestampEventStrategy(adapter, eventRepository)
     } else if (isRelayListEvent(event) || isReplaceableEvent(event)) {
       return new ReplaceableEventStrategy(adapter, eventRepository)
+    // NIP-43: Join/Leave requests MUST be checked before the generic ephemeral
+    // handler, because kinds 28934/28936 fall in the ephemeral range (20000-29999).
+    } else if (isNip43JoinRequest(event)) {
+      return new JoinRequestEventStrategy(adapter, inviteCodeRepository, userRepository, cache, settings)
+    } else if (isNip43LeaveRequest(event)) {
+      return new LeaveRequestEventStrategy(adapter, userRepository, cache, settings)
     } else if (isEphemeralEvent(event)) {
       return new EphemeralEventStrategy(adapter)
     } else if (isDeleteEvent(event)) {

src/factories/message-handler-factory.ts

@@ -1,5 +1,5 @@
 import { ICacheAdapter, IWebSocketAdapter } from '../@types/adapters'
-import { IEventRepository, INip05VerificationRepository, IUserRepository } from '../@types/repositories'
+import { IEventRepository, IInviteCodeRepository, INip05VerificationRepository, IUserRepository } from '../@types/repositories'
 import { IncomingMessage, MessageType } from '../@types/messages'
 import { createSettings } from './settings-factory'
 import { AuthMessageHandler } from '../handlers/auth-message-handler'
@@ -25,13 +25,14 @@ export const messageHandlerFactory =
     eventRepository: IEventRepository,
     userRepository: IUserRepository,
     nip05VerificationRepository: INip05VerificationRepository,
+    inviteCodeRepository: IInviteCodeRepository,
   ) =>
   ([message, adapter]: [IncomingMessage, IWebSocketAdapter]) => {
     switch (message[0]) {
       case MessageType.EVENT: {
         return new EventMessageHandler(
           adapter,
-          eventStrategyFactory(eventRepository, userRepository),
+          eventStrategyFactory(eventRepository, userRepository, inviteCodeRepository, getCache(), createSettings),
           eventRepository,
           userRepository,
           createSettings,

src/factories/websocket-adapter-factory.ts

@@ -1,7 +1,7 @@
 import { IncomingMessage } from 'http'
 import { WebSocket } from 'ws'
 
-import { IEventRepository, INip05VerificationRepository, IUserRepository } from '../@types/repositories'
+import { IEventRepository, IInviteCodeRepository, INip05VerificationRepository, IUserRepository } from '../@types/repositories'
 import { createSettings } from './settings-factory'
 import { IWebSocketServerAdapter } from '../@types/adapters'
 import { messageHandlerFactory } from './message-handler-factory'
@@ -13,13 +13,14 @@ export const webSocketAdapterFactory =
     eventRepository: IEventRepository,
     userRepository: IUserRepository,
     nip05VerificationRepository: INip05VerificationRepository,
+    inviteCodeRepository: IInviteCodeRepository,
   ) =>
   ([client, request, webSocketServerAdapter]: [WebSocket, IncomingMessage, IWebSocketServerAdapter]) =>
     new WebSocketAdapter(
       client,
       request,
       webSocketServerAdapter,
-      messageHandlerFactory(eventRepository, userRepository, nip05VerificationRepository),
+      messageHandlerFactory(eventRepository, userRepository, nip05VerificationRepository, inviteCodeRepository),
       rateLimiterFactory,
       createSettings,
     )

src/factories/worker-factory.ts

@@ -9,6 +9,7 @@ import { createLogger } from './logger-factory'
 import { createSettings } from '../factories/settings-factory'
 import { createWebApp } from './web-app-factory'
 import { EventRepository } from '../repositories/event-repository'
+import { InviteCodeRepository } from '../repositories/invite-code-repository'
 import { Nip05VerificationRepository } from '../repositories/nip05-verification-repository'
 import { UserRepository } from '../repositories/user-repository'
 import { webSocketAdapterFactory } from './websocket-adapter-factory'
@@ -22,6 +23,7 @@ export const workerFactory = (): AppWorker => {
   const eventRepository = new EventRepository(dbClient, readReplicaDbClient, createSettings)
   const userRepository = new UserRepository(dbClient, eventRepository)
   const nip05VerificationRepository = new Nip05VerificationRepository(dbClient)
+  const inviteCodeRepository = new InviteCodeRepository(dbClient)
 
   const settings = createSettings()
 
@@ -63,7 +65,7 @@ export const workerFactory = (): AppWorker => {
   const adapter = new WebSocketServerAdapter(
     server,
     webSocketServer,
-    webSocketAdapterFactory(eventRepository, userRepository, nip05VerificationRepository),
+    webSocketAdapterFactory(eventRepository, userRepository, nip05VerificationRepository, inviteCodeRepository),
     createSettings,
   )
 

src/handlers/event-message-handler.ts

@@ -30,7 +30,7 @@ import {
 } from '../utils/event'
 import { IEventRepository, INip05VerificationRepository, IUserRepository } from '../@types/repositories'
 import { IEventStrategy, IMessageHandler } from '../@types/message-handlers'
-import { CacheAdmissionState } from '../constants/caching'
+import { admissionCacheKey, CacheAdmissionState } from '../constants/caching'
 import { createEventCommandResult } from '../telemetry/event-metrics'
 import { createLogger } from '../factories/logger-factory'
 import { Factory } from '../@types/base'
@@ -372,25 +372,40 @@ export class EventMessageHandler implements IMessageHandler {
 
   protected async isUserAdmitted(event: Event): Promise<string | undefined> {
     const currentSettings = this.settings()
-    if (!currentSettings.payments?.enabled) {
+    const paymentsEnabled = currentSettings.payments?.enabled === true
+    // NIP-43: membership mode gates writes on admission even without payments
+    const nip43Enabled = currentSettings.nip43?.enabled === true
+    if (!paymentsEnabled && !nip43Enabled) {
       return
     }
 
     if (this.getRelayPublicKey() === event.pubkey) {
       return
     }
 
+    // NIP-43: join/leave requests must bypass admission — they ARE the admission flow
+    if (event.kind === EventKinds.NIP43_JOIN_REQUEST || event.kind === EventKinds.NIP43_LEAVE_REQUEST) {
+      return
+    }
+
     const isApplicableFee = (feeSchedule: FeeSchedule) =>
       feeSchedule.enabled &&
       !feeSchedule.whitelists?.pubkeys?.includes(event.pubkey) &&
       !feeSchedule.whitelists?.event_kinds?.some(isEventKindOrRangeMatch(event))
 
-    const feeSchedules = currentSettings.payments?.feeSchedules?.admission?.filter(isApplicableFee)
-    if (!Array.isArray(feeSchedules) || !feeSchedules.length) {
+    const feeSchedules = paymentsEnabled
+      ? currentSettings.payments?.feeSchedules?.admission?.filter(isApplicableFee)
+      : undefined
+    const admissionFeeRequired = Array.isArray(feeSchedules) && feeSchedules.length > 0
+    if (!admissionFeeRequired && !nip43Enabled) {
       return
     }
 
-    const cacheKey = `${event.pubkey}:is-admitted`
+    const notAdmittedReason = nip43Enabled
+      ? 'restricted: pubkey not admitted; send a join request (kind 28934) with a valid invite code'
+      : 'blocked: pubkey not admitted'
+
+    const cacheKey = admissionCacheKey(event.pubkey)
 
     try {
       const cachedValue = await this.cache.getKey(cacheKey)
@@ -400,7 +415,7 @@ export class EventMessageHandler implements IMessageHandler {
       }
       if (cachedValue === CacheAdmissionState.BLOCKED_NOT_ADMITTED) {
         logger('cache hit for %s admission: blocked', event.pubkey)
-        return 'blocked: pubkey not admitted'
+        return notAdmittedReason
       }
       if (cachedValue === CacheAdmissionState.BLOCKED_INSUFFICIENT_BALANCE) {
         logger('cache hit for %s admission: insufficient balance', event.pubkey)
@@ -413,10 +428,10 @@ export class EventMessageHandler implements IMessageHandler {
     const user = await this.userRepository.findByPubkey(event.pubkey)
     if (!user || !user.isAdmitted) {
       this.cacheSet(cacheKey, CacheAdmissionState.BLOCKED_NOT_ADMITTED, 60)
-      return 'blocked: pubkey not admitted'
+      return notAdmittedReason
     }
 
-    const minBalance = currentSettings.limits?.event?.pubkey?.minBalance ?? 0n
+    const minBalance = paymentsEnabled ? currentSettings.limits?.event?.pubkey?.minBalance ?? 0n : 0n
     if (minBalance > 0n && user.balance < minBalance) {
       this.cacheSet(cacheKey, CacheAdmissionState.BLOCKED_INSUFFICIENT_BALANCE, 60)
       return 'blocked: insufficient balance'
@@ -453,6 +468,12 @@ export class EventMessageHandler implements IMessageHandler {
       return
     }
 
+    // NIP-43: join/leave requests bypass NIP-05 — a new user won't have a
+    // verification record yet, and requiring one would block the join flow.
+    if (event.kind === EventKinds.NIP43_JOIN_REQUEST || event.kind === EventKinds.NIP43_LEAVE_REQUEST) {
+      return
+    }
+
     if (event.kind === EventKinds.SET_METADATA) {
       return
     }

src/handlers/event-strategies/join-request-event-strategy.ts

@@ -0,0 +1,89 @@
+import { getClaimTag, isNip43RequestTimestampValid } from '../../utils/nip43'
+import { ICacheAdapter, IWebSocketAdapter } from '../../@types/adapters'
+import { IInviteCodeRepository, IUserRepository } from '../../@types/repositories'
+import { admissionCacheKey } from '../../constants/caching'
+import { createEventCommandResult } from '../../telemetry/event-metrics'
+import { createLogger } from '../../factories/logger-factory'
+import { Event } from '../../@types/event'
+import { IEventStrategy } from '../../@types/message-handlers'
+import { Settings } from '../../@types/settings'
+import { WebSocketAdapterEvent } from '../../constants/adapter'
+
+const logger = createLogger('join-request-event-strategy')
+
+// Join requests are answered with an OK result but never broadcast to
+// subscribers: the claim tag would leak the invite code to anyone
+// subscribed to kind 28934.
+export class JoinRequestEventStrategy implements IEventStrategy<Event, Promise<void>> {
+  public constructor(
+    private readonly webSocket: IWebSocketAdapter,
+    private readonly inviteCodeRepository: IInviteCodeRepository,
+    private readonly userRepository: IUserRepository,
+    private readonly cache: ICacheAdapter,
+    private readonly settings: () => Settings,
+  ) {}
+
+  public async execute(event: Event): Promise<void> {
+    const currentSettings = this.settings()
+
+    if (!currentSettings.nip43?.enabled) {
+      logger('NIP-43 disabled, rejecting join request from %s', event.pubkey)
+      this.sendResult(event.id, false, 'restricted: NIP-43 is not enabled on this relay')
+      return
+    }
+
+    if (!isNip43RequestTimestampValid(event)) {
+      logger('join request from %s has stale created_at', event.pubkey)
+      this.sendResult(event.id, false, 'invalid: created_at is too far from the current time')
+      return
+    }
+
+    if (!this.webSocket.getAuthenticatedPubkeys().has(event.pubkey)) {
+      logger('unauthenticated join request from %s', event.pubkey)
+      this.sendResult(event.id, false, 'auth-required: authentication required (NIP-42)')
+      return
+    }
+
+    const claimCode = getClaimTag(event)
+    if (!claimCode) {
+      logger('join request from %s missing claim tag', event.pubkey)
+      this.sendResult(event.id, false, 'invalid: join request requires a claim tag')
+      return
+    }
+
+    const existingUser = await this.userRepository.findByPubkey(event.pubkey)
+    if (existingUser?.isAdmitted) {
+      logger('join request from %s: already admitted', event.pubkey)
+      this.sendResult(event.id, true, 'duplicate: you are already a member of this relay')
+      return
+    }
+
+    const claimed = await this.inviteCodeRepository.claimCode(claimCode, event.pubkey)
+    if (!claimed) {
+      logger('join request from %s: claim failed', event.pubkey)
+      this.sendResult(event.id, false, 'restricted: invalid or expired invite code')
+      return
+    }
+
+    // Not transactional with claimCode: if admitUser throws, one code use is
+    // wasted. Acceptable — the alternative order (admit before claim) could
+    // admit users without a valid code.
+    await this.userRepository.admitUser(event.pubkey, new Date())
+
+    // Drop any cached "not admitted" verdict so the new member's next event
+    // isn't rejected by a stale admission cache entry.
+    try {
+      await this.cache.deleteKey(admissionCacheKey(event.pubkey))
+    } catch (error) {
+      logger('unable to invalidate admission cache for %s: %o', event.pubkey, error)
+    }
+
+    const relayUrl = currentSettings.info?.relay_url ?? 'this relay'
+    logger('admitted %s via invite code', event.pubkey)
+    this.sendResult(event.id, true, `info: welcome to ${relayUrl}!`)
+  }
+
+  private sendResult(eventId: string, successful: boolean, message: string): void {
+    this.webSocket.emit(WebSocketAdapterEvent.Message, createEventCommandResult(eventId, successful, message))
+  }
+}