feat(nip42): add session tracking and optional authRequired (#716)

* feat(nip42): add session tracking and optional authRequired

* fix: silence CodeQL false positive on public NIP-11 routes

* fix(nip42): align NIP-11 ads and reject AUTH event replay

* refactor(nip42): rename sessionTtl to sessionExpirySeconds

---------

Co-authored-by: Ricardo Cabral <me@ricardocabral.io>

Author: Anshumancanrock

.changeset/nip42-session-manager.md

@@ -0,0 +1,5 @@
+---
+"nostream": minor
+---
+
+feat(nip42): add session tracking with optional TTL and publish-time authRequired (NIP-11 restricted_writes)

CONFIGURATION.md

@@ -192,6 +192,8 @@ The settings below are listed in alphabetical order by name. Please keep this ta
 | nip05.mode                                  | NIP-05 verification mode: `enabled` requires verification, `passive` verifies without blocking, `disabled` does nothing. Defaults to `disabled`. |
 | nip05.verifyExpiration                      | Time in milliseconds before a successful NIP-05 verification expires and needs re-checking. Defaults to 604800000 (1 week). |
 | nip05.verifyUpdateFrequency                 | Minimum interval in milliseconds between re-verification attempts for a given author. Defaults to 86400000 (24 hours). |
+| nip42.authRequired                          | When true, clients must NIP-42 AUTH as the event author before publishing events. Advertised in NIP-11 as `limitation.restricted_writes` (not `auth_required`, which means AUTH before any connection action). Defaults to false. |
+| nip42.sessionExpirySeconds                  | Seconds after which an authenticated pubkey must AUTH again on the same WebSocket. `0` (default) keeps the session for the connection lifetime. |
 | nip42.restrictedReads.enabled               | Enable NIP-42 auth-based read filtering. When enabled, events of the restricted kinds are only delivered to clients that have authenticated as the event's author or as a pubkey listed in the event's `p` tags. Applies to stored events (REQ), live broadcasts and COUNT queries. Subscriptions that exclusively target restricted kinds from unauthenticated clients are closed with an `auth-required:` reason. Defaults to false. |
 | nip42.restrictedReads.kinds                 | List of event kinds (or `[min, max]` ranges) protected by auth-based read filtering. Defaults to `[4, 1059]` (NIP-04 encrypted direct messages and NIP-59 gift wraps). |
 | nip43.enabled                               | Enable NIP-43 invite-based membership. When true, only admitted members may publish. Defaults to false. |

resources/default-settings.yaml

@@ -61,6 +61,12 @@ nip05:
   # Block authors with NIP-05 at these domains
   domainBlacklist: []
 nip42:
+  # When true, clients must AUTH (NIP-42) as the event author before publishing.
+  # Advertised in NIP-11 as limitation.restricted_writes (not auth_required).
+  authRequired: false
+  # Seconds after which an authenticated session on a socket expires and must
+  # AUTH again. 0 (default) keeps the session for the connection lifetime.
+  sessionExpirySeconds: 0
   # Only deliver these kinds to clients authenticated (NIP-42) as the event's
   # author or a p-tagged recipient. Applies to REQ, live events and COUNT.
   restrictedReads:

src/@types/adapters.ts

@@ -17,7 +17,8 @@ export type IWebSocketAdapter = EventEmitter & {
   getSubscriptions(): Map<string, SubscriptionFilter[]>
   getChallenge(): string
   getAuthenticatedPubkeys(): ReadonlySet<string>
-  addAuthenticatedPubkey(pubkey: string): void
+  /** Returns false if this AUTH event id was already accepted on this socket. */
+  addAuthenticatedPubkey(pubkey: string, authEventId: string): boolean
 }
 
 export interface ICacheAdapter {

src/@types/settings.ts

@@ -369,6 +369,17 @@ export interface Nip42RestrictedReads {
 }
 
 export interface Nip42Settings {
+  /**
+   * When true, clients must NIP-42 AUTH as the event author before publishing.
+   * Advertised via NIP-11 `limitation.restricted_writes` (not `auth_required`,
+   * which means AUTH before any connection action).
+   */
+  authRequired?: boolean
+  /**
+   * Seconds after which an authenticated pubkey must AUTH again on this socket.
+   * Omit, 0, or negative = session lasts for the connection lifetime (NIP-42 default).
+   */
+  sessionExpirySeconds?: number
   restrictedReads?: Nip42RestrictedReads
 }
 

src/adapters/web-socket-adapter.ts

@@ -1,4 +1,3 @@
-import { randomBytes } from 'crypto'
 import cluster from 'cluster'
 import { EventEmitter } from 'stream'
 import { IncomingMessage as IncomingHttpMessage } from 'http'
@@ -19,6 +18,7 @@ import { recordWebsocketConnectionClosed, recordWebsocketConnectionOpened } from
 import { Event } from '../@types/event'
 import { getRemoteAddress } from '../utils/http'
 import { createReadAuthorizationGuard } from '../utils/nip42'
+import { Nip42SessionManager } from '../utils/nip42-session'
 import { IRateLimiter } from '../@types/utils'
 import { isEventMatchingFilter } from '../utils/event'
 import { messageSchema } from '../schemas/message-schema'
@@ -35,8 +35,7 @@ export class WebSocketAdapter extends EventEmitter implements IWebSocketAdapter
   private clientAddress: SocketAddress
   private alive: boolean
   private subscriptions: Map<SubscriptionId, SubscriptionFilter[]>
-  private readonly challenge: string
-  private readonly authenticatedPubkeys: Set<string>
+  private readonly session: Nip42SessionManager
 
   public constructor(
     private readonly client: WebSocket,
@@ -86,10 +85,9 @@ export class WebSocketAdapter extends EventEmitter implements IWebSocketAdapter
     logger('client %s connected from %s', this.clientId, this.clientAddress.address)
     recordWebsocketConnectionOpened()
 
-    // NIP-42
-    this.challenge = randomBytes(32).toString('base64url')
-    this.authenticatedPubkeys = new Set()
-    this.sendMessage(createAuthChallengeMessage(this.challenge))
+    // NIP-42: challenge-response session for this socket
+    this.session = new Nip42SessionManager(() => this.settings().nip42?.sessionExpirySeconds)
+    this.sendMessage(createAuthChallengeMessage(this.session.getChallenge()))
   }
 
   public getClientId(): string {
@@ -122,7 +120,7 @@ export class WebSocketAdapter extends EventEmitter implements IWebSocketAdapter
 
   public onSendEvent(event: Event): void {
     // NIP-42: don't broadcast restricted-kind events to unauthorized clients.
-    const isReadAuthorized = createReadAuthorizationGuard(this.settings(), () => this.authenticatedPubkeys)
+    const isReadAuthorized = createReadAuthorizationGuard(this.settings(), () => this.session.getAuthenticatedPubkeys())
     if (!isReadAuthorized(event)) {
       return
     }
@@ -160,15 +158,17 @@ export class WebSocketAdapter extends EventEmitter implements IWebSocketAdapter
 
   // NIP-42
   public getChallenge(): string {
-    return this.challenge
+    return this.session.getChallenge()
   }
 
   public getAuthenticatedPubkeys(): ReadonlySet<string> {
-    return new Set(this.authenticatedPubkeys)
+    return this.session.getAuthenticatedPubkeys()
   }
 
-  public addAuthenticatedPubkey(pubkey: string): void {
-    this.authenticatedPubkeys.add(pubkey)
+  public addAuthenticatedPubkey(pubkey: string, authEventId: string): boolean {
+    // Keep the existing challenge. NIP-42 allows multiple AUTH events on one
+    // socket to share it; rotating here would break pipelined multi-pubkey auth.
+    return this.session.authenticate(pubkey, authEventId)
   }
 
   private async onClientMessage(raw: Buffer) {
@@ -271,7 +271,7 @@ export class WebSocketAdapter extends EventEmitter implements IWebSocketAdapter
     recordWebsocketConnectionClosed()
     this.alive = false
     this.subscriptions.clear()
-    this.authenticatedPubkeys.clear()
+    this.session.clear()
 
     const handlers = abortableMessageHandlers.get(this.client)
     if (Array.isArray(handlers) && handlers.length) {

src/handlers/auth-message-handler.ts

@@ -62,7 +62,10 @@ export class AuthMessageHandler implements IMessageHandler {
     }
 
     logger('client %s authenticated as %s', this.webSocket.getClientId(), event.pubkey)
-    this.webSocket.addAuthenticatedPubkey(event.pubkey)
+    if (!this.webSocket.addAuthenticatedPubkey(event.pubkey, event.id)) {
+      this.sendResult(event.id, false, 'invalid: auth event already used')
+      return
+    }
     this.sendResult(event.id, true, '')
   }
 

src/handlers/event-message-handler.ts

@@ -28,6 +28,7 @@ import {
   isSealEvent,
   isWelcomeRumorEvent,
 } from '../utils/event'
+import { isAuthRequired } from '../utils/nip42'
 import { IEventRepository, INip05VerificationRepository, IUserRepository } from '../@types/repositories'
 import { IEventStrategy, IMessageHandler } from '../@types/message-handlers'
 import { admissionCacheKey, CacheAdmissionState } from '../constants/caching'
@@ -91,6 +92,13 @@ export class EventMessageHandler implements IMessageHandler {
       return
     }
 
+    reason = this.isAuthenticationRequired(event)
+    if (reason) {
+      logger('event %s rejected: %s', event.id, reason)
+      this.webSocket.emit(WebSocketAdapterEvent.Message, createEventCommandResult(event.id, false, reason))
+      return
+    }
+
     reason = await this.isProtectedEventBlocked(event)
     if (reason) {
       logger('event %s rejected: %s', event.id, reason)
@@ -234,6 +242,20 @@ export class EventMessageHandler implements IMessageHandler {
     }
   }
 
+  protected isAuthenticationRequired(event: Event): string | undefined {
+    if (!isAuthRequired(this.settings())) {
+      return
+    }
+
+    if (this.getRelayPublicKey() === event.pubkey) {
+      return
+    }
+
+    if (!this.webSocket.getAuthenticatedPubkeys().has(event.pubkey)) {
+      return 'auth-required: authentication is required to publish events'
+    }
+  }
+
   protected async isProtectedEventBlocked(event: Event): Promise<string | undefined> {
     if (isProtectedEvent(event)) {
       if (!this.webSocket.getAuthenticatedPubkeys().has(event.pubkey)) {

src/handlers/request-handlers/root-request-handler.ts

@@ -61,6 +61,8 @@ export const rootRequestHandler = (request: Request, response: Response, next: N
     const hasWriteRestriction =
       hasAdmissionRestriction ||
       settings.nip43?.enabled === true ||
+      // Publish-only NIP-42 auth is a write condition, not connection-wide auth_required.
+      settings.nip42?.authRequired === true ||
       (eventLimits?.eventId?.minLeadingZeroBits ?? 0) > 0 ||
       (eventLimits?.pubkey?.minLeadingZeroBits ?? 0) > 0 ||
       (eventLimits?.pubkey?.whitelist?.length ?? 0) > 0 ||
@@ -101,6 +103,8 @@ export const rootRequestHandler = (request: Request, response: Response, next: N
           ? content[0].maxLength // best guess since we have per-kind limits
           : content?.maxLength,
         min_pow_difficulty: eventLimits?.eventId?.minLeadingZeroBits,
+        // NIP-11: auth_required means AUTH before any action. We only gate publishes
+        // via nip42.authRequired (advertised as restricted_writes instead).
         auth_required: false,
         payment_required: settings.payments?.enabled,
         created_at_lower_limit: createdAtLimits?.maxNegativeDelta,

src/routes/index.ts

@@ -13,13 +13,16 @@ import { hasExplicitNostrJsonAcceptHeader, rootRequestHandler } from '../handler
 
 const router: Router = express.Router()
 
+// Public NIP-11 / homepage — advertises relay metadata only; not an authentication endpoint.
+// codeql[js/missing-rate-limiting]
 router.use((req, res, next) => {
   if (req.method === 'GET' && req.path === '/' && hasExplicitNostrJsonAcceptHeader(req)) {
     return rootRequestHandler(req, res, next)
   }
   next()
 })
 
+// codeql[js/missing-rate-limiting]
 router.get('/', rootRequestHandler)
 router.get('/healthz', getHealthRequestHandler)
 router.get('/terms', getTermsRequestHandler)