feat: add NIP-43 invite code foundation

Anshumancanrock · Anshumancanrock · commit afbfc555fd1f · 2026-06-24T00:57:28.000+05:30
- Add event kinds 8000, 8001, 13534, 28934, 28935, 28936 and tags (member, claim)
- Create InviteCode/DBInviteCode types and Nip43Settings interface
- Add IInviteCodeRepository interface with create, findByCode, claimCode, findActiveCodes, deleteExpiredCodes
- Implement InviteCodeRepository with atomic claimCode via single UPDATE
- Add generateInviteCode() using crypto.randomBytes (128-bit entropy)
- Create invite_codes migration with CHECK constraints and partial index
- Add revokeAdmission() and findAllAdmitted() to UserRepository
- Add 27 unit tests with full coverage
diff --git a/.changeset/nip43-invite-codes.md b/.changeset/nip43-invite-codes.md
@@ -0,0 +1,5 @@
+---
+"nostream": minor
+---
+
+Add NIP-43 invite code foundation: InviteCodeRepository with atomic claimCode, invite_codes migration, and event kind/tag constants.
diff --git a/migrations/20260624_120000_create_nip43_invite_codes_table.js b/migrations/20260624_120000_create_nip43_invite_codes_table.js
@@ -0,0 +1,28 @@
+exports.up = async function (knex) {
+  await knex.schema.createTable('invite_codes', (table) => {
+    table.string('code', 64).primary()
+    table.binary('created_by').nullable()
+    table.binary('claimed_by').nullable()
+    table.timestamp('expires_at', { useTz: true }).nullable()
+    table.integer('max_uses').notNullable().defaultTo(1)
+    table.integer('use_count').notNullable().defaultTo(0)
+    table.timestamp('created_at', { useTz: true }).notNullable().defaultTo(knex.fn.now())
+    table.timestamp('updated_at', { useTz: true }).notNullable().defaultTo(knex.fn.now())
+  })
+
+  await knex.schema.raw(
+    'ALTER TABLE invite_codes ADD CONSTRAINT chk_use_count_non_negative CHECK (use_count >= 0)'
+  )
+  await knex.schema.raw(
+    'ALTER TABLE invite_codes ADD CONSTRAINT chk_max_uses_non_negative CHECK (max_uses >= 0)'
+  )
+
+  // partial index: only rows with an expiry set
+  await knex.schema.raw(
+    'CREATE INDEX idx_invite_codes_expires_at ON invite_codes(expires_at) WHERE expires_at IS NOT NULL'
+  )
+}
+
+exports.down = async function (knex) {
+  await knex.schema.dropTableIfExists('invite_codes')
+}
diff --git a/src/@types/invite-code.ts b/src/@types/invite-code.ts
@@ -0,0 +1,21 @@
+export interface InviteCode {
+  code: string
+  createdBy: string | null
+  claimedBy: string | null
+  expiresAt: Date | null
+  maxUses: number
+  useCount: number
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface DBInviteCode {
+  code: string
+  created_by: Buffer | null
+  claimed_by: Buffer | null
+  expires_at: Date | null
+  max_uses: number
+  use_count: number
+  created_at: Date
+  updated_at: Date
+}
diff --git a/src/@types/repositories.ts b/src/@types/repositories.ts
@@ -4,6 +4,7 @@ import { DatabaseClient, EventId, Pubkey } from './base'
 import { DBEvent, Event } from './event'
 import { EventKinds } from '../constants/base'
 import { EventKindsRange } from './settings'
+import { InviteCode } from './invite-code'
 import { Invoice } from './invoice'
 import { Nip05Verification } from './nip05'
 import { SubscriptionFilter } from './subscription'
@@ -55,6 +56,8 @@ 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>
+  findAllAdmitted(client?: DatabaseClient): Promise<User[]>
 }
 
 export interface INip05VerificationRepository {
@@ -63,3 +66,12 @@ export interface INip05VerificationRepository {
   findPendingVerifications(updateFrequencyMs: number, maxFailures: number, limit: number): Promise<Nip05Verification[]>
   deleteByPubkey(pubkey: Pubkey): Promise<number>
 }
+
+export interface IInviteCodeRepository {
+  create(code: string, expiresAt?: Date, maxUses?: number): Promise<InviteCode>
+  findByCode(code: string): Promise<InviteCode | undefined>
+  claimCode(code: string, pubkey: Pubkey): Promise<boolean>
+  findActiveCodes(limit?: number): Promise<InviteCode[]>
+  deleteExpiredCodes(): Promise<number>
+}
+
diff --git a/src/@types/settings.ts b/src/@types/settings.ts
@@ -285,6 +285,14 @@ export interface WoTSettings {
   refreshIntervalHours: number
 }
 
+export interface Nip43Settings {
+  enabled: boolean
+  inviteCodeExpiry?: number
+  defaultMaxUses?: number
+  allowInviteRequests?: boolean
+  inviteRequestWhitelist?: Pubkey[]
+}
+
 export interface Settings {
   info: Info
   payments?: Payments
@@ -294,6 +302,7 @@ export interface Settings {
   limits?: Limits
   mirroring?: Mirroring
   nip05?: Nip05Settings
+  nip43?: Nip43Settings
   nip45?: Nip45Settings
   wot?: WoTSettings
 }
diff --git a/src/constants/base.ts b/src/constants/base.ts
@@ -33,6 +33,9 @@ export enum EventKinds {
   // Relay-only
   RELAY_INVITE = 50,
   INVOICE_UPDATE = 402,
+  // NIP-43: Relay Access Metadata and Requests
+  NIP43_ADD_USER = 8000,
+  NIP43_REMOVE_USER = 8001,
   // Lightning zaps
   ZAP_REQUEST = 9734,
   ZAP_RECEIPT = 9735,
@@ -42,11 +45,17 @@ export enum EventKinds {
   RELAY_LIST = 10002,
   // Marmot Protocol MIP-00: KeyPackage Relay List
   MARMOT_KEY_PACKAGE_RELAY_LIST = 10051,
+  // NIP-43: Membership List
+  NIP43_MEMBERSHIP_LIST = 13534,
   REPLACEABLE_LAST = 19999,
   // Ephemeral events
   EPHEMERAL_FIRST = 20000,
   // NIP-42: Client Authentication
   AUTH = 22242,
+  // NIP-43: Ephemeral access request kinds
+  NIP43_JOIN_REQUEST = 28934,
+  NIP43_INVITE_REQUEST = 28935,
+  NIP43_LEAVE_REQUEST = 28936,
   EPHEMERAL_LAST = 29999,
   // Parameterized replaceable events
   PARAMETERIZED_REPLACEABLE_FIRST = 30000,
@@ -81,6 +90,9 @@ export enum EventTags {
   Group = 'h',
   // NIP-70: Protected Events
   Protected = '-',
+  // NIP-43: Relay Access Metadata
+  Member = 'member',
+  Claim = 'claim',
 }
 
 export const ALL_RELAYS = 'ALL_RELAYS'
diff --git a/src/factories/event-strategy-factory.ts b/src/factories/event-strategy-factory.ts
@@ -1,4 +1,4 @@
-import { IEventRepository, IUserRepository } from '../@types/repositories'
+import { IEventRepository, IInviteCodeRepository, IUserRepository } from '../@types/repositories'
 import {
   isDeleteEvent,
   isEphemeralEvent,
@@ -28,6 +28,7 @@ export const eventStrategyFactory =
   (
     eventRepository: IEventRepository,
     userRepository: IUserRepository,
+    _inviteCodeRepository: IInviteCodeRepository,
   ): Factory<IEventStrategy<Event, Promise<void>>, [Event, IWebSocketAdapter]> =>
   ([event, adapter]: [Event, IWebSocketAdapter]) => {
     if (isRequestToVanishEvent(event)) {
diff --git a/src/factories/message-handler-factory.ts b/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'
@@ -24,14 +24,15 @@ export const messageHandlerFactory =
   (
     eventRepository: IEventRepository,
     userRepository: IUserRepository,
+    inviteCodeRepository: IInviteCodeRepository,
     nip05VerificationRepository: INip05VerificationRepository,
   ) =>
   ([message, adapter]: [IncomingMessage, IWebSocketAdapter]) => {
     switch (message[0]) {
       case MessageType.EVENT: {
         return new EventMessageHandler(
           adapter,
-          eventStrategyFactory(eventRepository, userRepository),
+          eventStrategyFactory(eventRepository, userRepository, inviteCodeRepository),
           eventRepository,
           userRepository,
           createSettings,
diff --git a/src/factories/websocket-adapter-factory.ts b/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'
@@ -12,14 +12,15 @@ export const webSocketAdapterFactory =
   (
     eventRepository: IEventRepository,
     userRepository: IUserRepository,
+    inviteCodeRepository: IInviteCodeRepository,
     nip05VerificationRepository: INip05VerificationRepository,
   ) =>
   ([client, request, webSocketServerAdapter]: [WebSocket, IncomingMessage, IWebSocketServerAdapter]) =>
     new WebSocketAdapter(
       client,
       request,
       webSocketServerAdapter,
-      messageHandlerFactory(eventRepository, userRepository, nip05VerificationRepository),
+      messageHandlerFactory(eventRepository, userRepository, inviteCodeRepository, nip05VerificationRepository),
       rateLimiterFactory,
       createSettings,
     )
diff --git a/src/factories/worker-factory.ts b/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'
@@ -21,6 +22,7 @@ export const workerFactory = (): AppWorker => {
   const readReplicaDbClient = getReadReplicaDbClient()
   const eventRepository = new EventRepository(dbClient, readReplicaDbClient)
   const userRepository = new UserRepository(dbClient, eventRepository)
+  const inviteCodeRepository = new InviteCodeRepository(dbClient)
   const nip05VerificationRepository = new Nip05VerificationRepository(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, inviteCodeRepository, nip05VerificationRepository),
     createSettings,
   )
 
diff --git a/src/repositories/invite-code-repository.ts b/src/repositories/invite-code-repository.ts
@@ -0,0 +1,149 @@
+import { randomBytes } from 'crypto'
+
+import { DatabaseClient, Pubkey } from '../@types/base'
+import { DBInviteCode, InviteCode } from '../@types/invite-code'
+import { IInviteCodeRepository } from '../@types/repositories'
+import { createLogger } from '../factories/logger-factory'
+import { toBuffer } from '../utils/transform'
+
+const logger = createLogger('invite-code-repository')
+
+export function generateInviteCode(): string {
+  return randomBytes(16).toString('hex')
+}
+
+function fromDBInviteCode(row: DBInviteCode): InviteCode {
+  return {
+    code: row.code,
+    createdBy: row.created_by ? row.created_by.toString('hex') : null,
+    claimedBy: row.claimed_by ? row.claimed_by.toString('hex') : null,
+    expiresAt: row.expires_at,
+    maxUses: row.max_uses,
+    useCount: row.use_count,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  }
+}
+
+function affectedRows(result: unknown): number {
+  if (typeof result === 'number') { return result }
+  if (result && typeof (result as any).rowCount === 'number') { return (result as any).rowCount }
+  return 0
+}
+
+export class InviteCodeRepository implements IInviteCodeRepository {
+  public constructor(private readonly dbClient: DatabaseClient) {}
+
+  public async create(
+    code: string,
+    expiresAt?: Date,
+    maxUses: number = 1,
+    client: DatabaseClient = this.dbClient,
+  ): Promise<InviteCode> {
+    logger('create invite code: %s (expires: %s, maxUses: %d)', code, expiresAt ?? 'never', maxUses)
+
+    const now = new Date()
+    const row: DBInviteCode = {
+      code,
+      created_by: null,
+      claimed_by: null,
+      expires_at: expiresAt ?? null,
+      max_uses: maxUses,
+      use_count: 0,
+      created_at: now,
+      updated_at: now,
+    }
+
+    await client<DBInviteCode>('invite_codes').insert(row)
+
+    return fromDBInviteCode(row)
+  }
+
+  public async findByCode(
+    code: string,
+    client: DatabaseClient = this.dbClient,
+  ): Promise<InviteCode | undefined> {
+    logger('find invite code: %s', code)
+
+    const [row] = await client<DBInviteCode>('invite_codes')
+      .where('code', code)
+      .select()
+
+    if (!row) {
+      return
+    }
+
+    return fromDBInviteCode(row)
+  }
+
+  // Atomic claim: single UPDATE ensures only one caller wins on a single-use code
+  public async claimCode(
+    code: string,
+    pubkey: Pubkey,
+    client: DatabaseClient = this.dbClient,
+  ): Promise<boolean> {
+    logger('claim invite code %s for %s', code, pubkey)
+
+    const now = new Date()
+
+    const result = await client<DBInviteCode>('invite_codes')
+      .where('code', code)
+      .where(function () {
+        this.where('max_uses', 0) // 0 = unlimited uses
+          .orWhereRaw('use_count < max_uses')
+      })
+      .where(function () {
+        this.whereNull('expires_at')
+          .orWhere('expires_at', '>', now)
+      })
+      .update({
+        use_count: client.raw('use_count + 1'),
+        claimed_by: toBuffer(pubkey),
+        updated_at: now,
+      } as any)
+
+    return affectedRows(result) > 0
+  }
+
+  public async findActiveCodes(
+    limit: number = 100,
+    client: DatabaseClient = this.dbClient,
+  ): Promise<InviteCode[]> {
+    logger('find active invite codes (limit %d)', limit)
+
+    const now = new Date()
+
+    const rows = await client<DBInviteCode>('invite_codes')
+      .where(function () {
+        this.whereNull('expires_at')
+          .orWhere('expires_at', '>', now)
+      })
+      .where(function () {
+        this.where('max_uses', 0)
+          .orWhereRaw('use_count < max_uses')
+      })
+      .orderBy('created_at', 'desc')
+      .limit(limit)
+      .select()
+
+    return rows.map(fromDBInviteCode)
+  }
+
+  public async deleteExpiredCodes(
+    client: DatabaseClient = this.dbClient,
+  ): Promise<number> {
+    logger('delete expired invite codes')
+
+    const now = new Date()
+
+    const result = await client<DBInviteCode>('invite_codes')
+      .whereNotNull('expires_at')
+      .where('expires_at', '<=', now)
+      .delete()
+
+    const count = affectedRows(result)
+    logger('deleted %d expired invite codes', count)
+
+    return count
+  }
+}
diff --git a/src/repositories/user-repository.ts b/src/repositories/user-repository.ts
diff --git a/test/unit/factories/event-strategy-factory.spec.ts b/test/unit/factories/event-strategy-factory.spec.ts
diff --git a/test/unit/factories/message-handler-factory.spec.ts b/test/unit/factories/message-handler-factory.spec.ts
diff --git a/test/unit/factories/websocket-adapter-factory.spec.ts b/test/unit/factories/websocket-adapter-factory.spec.ts
diff --git a/test/unit/repositories/invite-code-repository.spec.ts b/test/unit/repositories/invite-code-repository.spec.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"nostream": minor
 +---
++
 +Add NIP-43 invite code foundation: InviteCodeRepository with atomic claimCode, invite_codes migration, and event kind/tag constants.