@furystack/rest-service 13.0.0 → 14.1.0

package/src/http-user-context.ts

@@ -1,17 +1,20 @@
 import type { User } from '@furystack/core'
 import { useSystemIdentityContext } from '@furystack/core'
 import type { Injector } from '@furystack/inject'
-import { Injectable, Injected } from '@furystack/inject'
+import { defineService, type Token } from '@furystack/inject'
 import { PasswordAuthenticator, UnauthenticatedError } from '@furystack/security'
 import { EventHub, type ListenerErrorPayload } from '@furystack/utils'
 import { randomBytes } from 'crypto'
 import type { IncomingMessage } from 'http'
+import type { AuthenticationProvider } from './authentication-providers/authentication-provider.js'
 import { extractSessionIdFromCookies } from './authentication-providers/helpers.js'
 import { HttpAuthenticationSettings } from './http-authentication-settings.js'
-import type { DefaultSession } from './models/default-session.js'
+import { IdentityEventBus } from './identity-event-bus.js'
+import { resolveUserCacheKey, UserResolutionCache } from './user-resolution-cache.js'
 
 /**
- * Events emitted by the {@link HttpUserContext}
+ * Events emitted by a per-request {@link HttpUserContext} instance. Since
+ * the context is scoped, each request sees its own event stream.
  */
 export type HttpUserContextEvents = {
   onLogin: { user: User }
@@ -21,45 +24,78 @@ export type HttpUserContextEvents = {
 }
 
 /**
- * Injectable UserContext for FuryStack HTTP Api
+ * Request-scoped authentication/authorization facade.
+ *
+ * `HttpUserContext` consolidates identity lookup, authentication-provider
+ * walk-through and cookie session helpers behind a single object.
+ * Successful resolutions are memoized in the singleton
+ * {@link UserResolutionCache} keyed by the cache key produced by the
+ * matching {@link AuthenticationProvider} (e.g. `cookie:${sessionId}`
+ * for cookie auth) and expire after
+ * {@link HttpAuthenticationSettings.userCacheTtlMs}. Requests whose
+ * providers all opt out of caching (Basic Auth, JWT Bearer, anonymous
+ * traffic) bypass the cache and walk the provider chain on every call.
  */
-@Injectable({ lifetime: 'scoped' })
-export class HttpUserContext extends EventHub<HttpUserContextEvents> {
-  public getUserDataSet = () => this.authentication.getUserDataSet(this.systemInjector)
-
-  public getSessionDataSet = () => this.authentication.getSessionDataSet(this.systemInjector)
-
-  private getUserByName = async (userName: string) => {
-    const userDataSet = this.getUserDataSet()
-    const users = await userDataSet.find(this.systemInjector, { filter: { username: { $eq: userName } }, top: 2 })
-    if (users.length !== 1) {
-      throw new UnauthenticatedError()
-    }
-    return users[0]
-  }
-
-  private user?: User
+export interface HttpUserContext extends EventHub<HttpUserContextEvents> {
+  /** The active {@link HttpAuthenticationSettings} captured at resolve time. */
+  readonly authentication: HttpAuthenticationSettings
+  /** Whether the current user is authenticated according to the bound providers. */
+  isAuthenticated(request: Pick<IncomingMessage, 'headers'>): Promise<boolean>
+  /** Returns `true` when the current user has **all** of the supplied roles. */
+  isAuthorized(request: Pick<IncomingMessage, 'headers'>, ...roles: string[]): Promise<boolean>
+  /** Verifies a username/password pair against the system `PasswordAuthenticator`. */
+  authenticateUser(userName: string, password: string): Promise<User>
+  /** Returns the cached user for this request or resolves it via the provider chain. */
+  getCurrentUser(request: Pick<IncomingMessage, 'headers'>): Promise<User>
+  /** Extracts the session id for `request` using the configured cookie name. */
+  getSessionIdFromRequest(request: Pick<IncomingMessage, 'headers'>): string | null
+  /** Walks the configured authentication providers and returns the first match. */
+  authenticateRequest(request: Pick<IncomingMessage, 'headers'>): Promise<User>
+  /** Creates and persists a session for `user`, setting the cookie on `response`. */
+  cookieLogin(user: User, response: { setHeader: (header: string, value: string) => void }): Promise<User>
+  /** Clears the session identified by the request's cookie (if any). */
+  cookieLogout(
+    request: Pick<IncomingMessage, 'headers'>,
+    response: { setHeader: (header: string, value: string) => void },
+  ): Promise<void>
+}
 
+/**
+ * Internal concrete {@link EventHub}-backed implementation of
+ * {@link HttpUserContext}. Exposed via the `HttpUserContext` token;
+ * constructed by its factory.
+ */
+class HttpUserContextImpl extends EventHub<HttpUserContextEvents> implements HttpUserContext {
   /**
-   * @param request The request to be authenticated
-   * @returns whether the current user is authenticated
+   * `authenticator` is resolved lazily so that tests (and applications) that
+   * never invoke `authenticateUser` don't need to bind password-credential
+   * stores.
+   *
+   * The shared {@link UserResolutionCache} memoizes successful authentications
+   * across requests within the process. Cache keys are produced by the
+   * configured providers via `getCacheKey`; requests whose providers all
+   * opt out (e.g. Basic Auth, anonymous traffic) bypass the cache.
    */
-  public async isAuthenticated(request: IncomingMessage) {
+  constructor(
+    public readonly authentication: HttpAuthenticationSettings,
+    private readonly resolveAuthenticator: () => PasswordAuthenticator,
+    private readonly systemInjector: Injector,
+    private readonly userCache: UserResolutionCache,
+    private readonly identityEventBus: IdentityEventBus,
+  ) {
+    super()
+  }
+
+  public async isAuthenticated(request: Pick<IncomingMessage, 'headers'>): Promise<boolean> {
     try {
       const currentUser = await this.getCurrentUser(request)
       return currentUser !== null
-    } catch (error) {
+    } catch {
       return false
     }
   }
 
-  /**
-   * Returns whether the current user can be authorized with ALL of the specified roles
-   * @param request The request to be authenticated
-   * @param roles The list of roles to authorize
-   * @returns a boolean value that indicates whether the user is authorized
-   */
-  public async isAuthorized(request: IncomingMessage, ...roles: string[]): Promise<boolean> {
+  public async isAuthorized(request: Pick<IncomingMessage, 'headers'>, ...roles: string[]): Promise<boolean> {
     const currentUser = await this.getCurrentUser(request)
     for (const role of roles) {
       if (!currentUser || !currentUser.roles.some((c) => c === role)) {
@@ -69,15 +105,8 @@ export class HttpUserContext extends EventHub<HttpUserContextEvents> {
     return true
   }
 
-  /**
-   * Checks if the system contains a user with the provided name and password, throws an error otherwise
-   * @param userName The username
-   * @param password The password
-   * @returns the authenticated User
-   */
-  public async authenticateUser(userName: string, password: string) {
-    const result = await this.authenticator.checkPasswordForUser(userName, password)
-
+  public async authenticateUser(userName: string, password: string): Promise<User> {
+    const result = await this.resolveAuthenticator().checkPasswordForUser(userName, password)
     if (!result.isValid) {
       throw new UnauthenticatedError()
     }
@@ -88,24 +117,18 @@ export class HttpUserContext extends EventHub<HttpUserContextEvents> {
     return user
   }
 
-  public async getCurrentUser(request: Pick<IncomingMessage, 'headers'>) {
-    if (!this.user) {
-      this.user = await this.authenticateRequest(request)
-      return this.user
+  public async getCurrentUser(request: Pick<IncomingMessage, 'headers'>): Promise<User> {
+    const cacheKey = resolveUserCacheKey(this.authentication, request)
+    if (!cacheKey) {
+      return this.authenticateRequest(request)
     }
-    return this.user
+    return this.userCache.resolve(cacheKey, () => this.authenticateRequest(request))
   }
 
   public getSessionIdFromRequest(request: Pick<IncomingMessage, 'headers'>): string | null {
     return extractSessionIdFromCookies(request, this.authentication.cookieName)
   }
 
-  /**
-   * Iterates registered authentication providers in order.
-   * - A provider returning `User` means authentication succeeded.
-   * - A provider returning `null` means it does not apply; try the next one.
-   * - A provider throwing means it owns the request but auth failed; propagate the error.
-   */
   public async authenticateRequest(request: Pick<IncomingMessage, 'headers'>): Promise<User> {
     for (const provider of this.authentication.authenticationProviders) {
       const user = await provider.authenticate(request)
@@ -114,20 +137,14 @@ export class HttpUserContext extends EventHub<HttpUserContextEvents> {
     throw new UnauthenticatedError()
   }
 
-  /**
-   * Creates and sets up a cookie-based session for the provided user
-   * @param user The user to create a session for
-   * @param serverResponse A serverResponse to set the cookie
-   * @returns the current User
-   */
   public async cookieLogin(
     user: User,
-    serverResponse: { setHeader: (header: string, value: string) => void },
+    response: { setHeader: (header: string, value: string) => void },
   ): Promise<User> {
     const sessionId = randomBytes(32).toString('hex')
-    await this.getSessionDataSet().add(this.systemInjector, { sessionId, username: user.username })
-    serverResponse.setHeader('Set-Cookie', `${this.authentication.cookieName}=${sessionId}; Path=/; HttpOnly`)
-    this.user = user
+    const sessionDataSet = this.systemInjector.get(this.authentication.sessionDataSet)
+    await sessionDataSet.add(this.systemInjector, { sessionId, username: user.username })
+    response.setHeader('Set-Cookie', `${this.authentication.cookieName}=${sessionId}; Path=/; HttpOnly`)
     this.emit('onLogin', { user })
     return user
   }
@@ -135,45 +152,58 @@ export class HttpUserContext extends EventHub<HttpUserContextEvents> {
   public async cookieLogout(
     request: Pick<IncomingMessage, 'headers'>,
     response: { setHeader: (header: string, value: string) => void },
-  ) {
-    this.user = undefined
+  ): Promise<void> {
     const sessionId = this.getSessionIdFromRequest(request)
     response.setHeader('Set-Cookie', `${this.authentication.cookieName}=; Path=/; HttpOnly`)
 
     if (sessionId) {
-      const sessionDataSet = this.getSessionDataSet()
-      const sessions = await sessionDataSet.find(this.systemInjector, { filter: { sessionId: { $eq: sessionId } } })
-      await sessionDataSet.remove(this.systemInjector, ...sessions.map((s) => s[sessionDataSet.primaryKey]))
+      const sessionDataSet = this.systemInjector.get(this.authentication.sessionDataSet)
+      const sessions = await sessionDataSet.find(this.systemInjector, {
+        filter: { sessionId: { $eq: sessionId } },
+      })
+      await sessionDataSet.remove(this.systemInjector, ...sessions.map((s) => s.sessionId))
+      // Cross-node identity invalidation: the facade applies the local cache
+      // drop synchronously, then broadcasts so siblings collapse the
+      // staleness window from `userCacheTtlMs` to bus latency.
+      await this.identityEventBus.publish({ type: 'userLoggedOut', sessionId })
     }
     this.emit('onLogout', undefined)
   }
 
-  @Injected(HttpAuthenticationSettings)
-  declare public readonly authentication: HttpAuthenticationSettings<User, DefaultSession>
-
-  @Injected((injector: Injector) => useSystemIdentityContext({ injector, username: 'HttpUserContext' }))
-  declare private readonly systemInjector: Injector
-
-  @Injected(PasswordAuthenticator)
-  declare private readonly authenticator: PasswordAuthenticator
-
-  public init() {
-    this.getUserDataSet().addListener('onEntityUpdated', ({ id, change }) => {
-      if (this.user?.username === id) {
-        this.user = { ...this.user, ...change }
-      }
-    })
-
-    this.getUserDataSet().addListener('onEntityRemoved', ({ key }) => {
-      if (this.user?.username === key) {
-        this.user = undefined
-        this.emit('onSessionInvalidated', undefined)
-      }
-    })
-
-    this.getSessionDataSet().addListener('onEntityRemoved', () => {
-      this.user = undefined
-      this.emit('onSessionInvalidated', undefined)
+  private async getUserByName(userName: string): Promise<User> {
+    const userDataSet = this.systemInjector.get(this.authentication.userDataSet)
+    const users = await userDataSet.find(this.systemInjector, {
+      filter: { username: { $eq: userName } },
+      top: 2,
     })
+    if (users.length !== 1) {
+      throw new UnauthenticatedError()
+    }
+    return users[0]
   }
 }
+
+/**
+ * DI token for the per-request {@link HttpUserContext}. Scoped — each HTTP
+ * request resolves its own instance with a fresh `user` cache.
+ */
+export const HttpUserContext: Token<HttpUserContext, 'scoped'> = defineService({
+  name: 'furystack/rest-service/HttpUserContext',
+  lifetime: 'scoped',
+  factory: ({ inject, injector, onDispose }): HttpUserContext => {
+    const authentication = inject(HttpAuthenticationSettings)
+    const userCache = inject(UserResolutionCache)
+    const identityEventBus = inject(IdentityEventBus)
+    const systemInjector = useSystemIdentityContext({ injector, username: 'HttpUserContext' })
+    onDispose(() => systemInjector[Symbol.asyncDispose]())
+    // Password authenticator resolution is deferred: tests that exercise only
+    // unauthenticated endpoints never have to bind credential stores.
+    return new HttpUserContextImpl(
+      authentication,
+      () => injector.get(PasswordAuthenticator),
+      systemInjector,
+      userCache,
+      identityEventBus,
+    )
+  },
+})

package/src/identity-cache-keys.spec.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { sessionCacheKey, userCacheTag } from './identity-cache-keys.js'
+
+describe('identity-cache-keys', () => {
+  describe('sessionCacheKey', () => {
+    it('prefixes the session id with `cookie:`', () => {
+      expect(sessionCacheKey('abc')).toBe('cookie:abc')
+    })
+
+    it('preserves the empty string suffix shape', () => {
+      expect(sessionCacheKey('')).toBe('cookie:')
+    })
+  })
+
+  describe('userCacheTag', () => {
+    it('prefixes the username with `user:`', () => {
+      expect(userCacheTag('alice')).toBe('user:alice')
+    })
+
+    it('preserves the empty string suffix shape', () => {
+      expect(userCacheTag('')).toBe('user:')
+    })
+  })
+})

package/src/identity-cache-keys.ts

@@ -0,0 +1,31 @@
+/**
+ * Single source of truth for the cache key and cache tag shapes used by the
+ * identity-resolution path. Producer (`cookie-auth-provider.getCacheKey`),
+ * local invalidation (`HttpUserContext.cookieLogout`,
+ * `UserResolutionCache.invalidateByUser`), and any future
+ * `IdentityEventBus` subscribers all derive their strings here so the
+ * local-vs-replicated invalidation paths cannot drift.
+ */
+
+/**
+ * Cache key shape for the cookie-authentication provider. Keying by
+ * session id is safe because session invalidation drops the session
+ * row and the {@link UserResolutionCache} TTL bounds staleness.
+ */
+export type SessionCacheKey = `cookie:${string}`
+
+/**
+ * Tag attached to every {@link UserResolutionCache} entry, derived from
+ * the resolved user's `username`. Enables `removeByTag` invalidation
+ * across every cached session that resolved to a given user — used by
+ * `invalidateByUser` and (later) by `IdentityEventBus` subscribers
+ * acting on `userRolesChanged` / `userDeleted` / `passwordChanged`
+ * events.
+ */
+export type UserCacheTag = `user:${string}`
+
+/** Builds the cookie-auth cache key for `sessionId`. */
+export const sessionCacheKey = (sessionId: string): SessionCacheKey => `cookie:${sessionId}`
+
+/** Builds the user-resolution cache tag for `username`. */
+export const userCacheTag = (username: string): UserCacheTag => `user:${username}`

package/src/identity-event-bus.spec.ts

@@ -0,0 +1,285 @@
+import type { User } from '@furystack/core'
+import { CrossNodeBus, defineInProcessCrossNodeBus, type BusMessage } from '@furystack/cross-node-bus'
+import { createInProcessBusNetwork } from '@furystack/cross-node-bus/testing'
+import { createInjector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { describe, expect, it, vi } from 'vitest'
+import { sessionCacheKey, userCacheTag } from './identity-cache-keys.js'
+import {
+  applyLocalIdentityInvalidation,
+  IDENTITY_EVENT_TOPIC,
+  IdentityEventBus,
+  type IdentityEvent,
+} from './identity-event-bus.js'
+import { UserResolutionCache } from './user-resolution-cache.js'
+
+const userOf = (username: string, roles: readonly string[] = []): User => ({ username, roles: [...roles] })
+
+const populateCache = async (cache: UserResolutionCache, sessionId: string, user: User): Promise<void> => {
+  await cache.resolve(sessionCacheKey(sessionId), async () => user)
+}
+
+describe('IdentityEventBus', () => {
+  describe('applyLocalIdentityInvalidation', () => {
+    it('invalidates by session id for `userLoggedOut`', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        const cache = i.get(UserResolutionCache)
+        await populateCache(cache, 's1', userOf('alice'))
+        expect(cache.size).toBe(1)
+        applyLocalIdentityInvalidation({ type: 'userLoggedOut', sessionId: 's1' }, cache)
+        expect(cache.size).toBe(0)
+      })
+    })
+
+    it('invalidates by session id for `sessionInvalidated`', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        const cache = i.get(UserResolutionCache)
+        await populateCache(cache, 's2', userOf('alice'))
+        applyLocalIdentityInvalidation({ type: 'sessionInvalidated', sessionId: 's2' }, cache)
+        expect(cache.size).toBe(0)
+      })
+    })
+
+    for (const type of ['userRolesChanged', 'userDeleted', 'passwordChanged'] as const) {
+      it(`invalidates every cached session for the named user on \`${type}\``, async () => {
+        await usingAsync(createInjector(), async (i) => {
+          const cache = i.get(UserResolutionCache)
+          await populateCache(cache, 's-a-1', userOf('alice'))
+          await populateCache(cache, 's-a-2', userOf('alice'))
+          await populateCache(cache, 's-b-1', userOf('bob'))
+          expect(cache.size).toBe(3)
+          applyLocalIdentityInvalidation({ type, username: 'alice' }, cache)
+          expect(cache.size).toBe(1)
+          // The remaining entry is bob's.
+          await populateCache(cache, 's-a-3', userOf('alice'))
+          expect(cache.size).toBe(2)
+        })
+      })
+    }
+  })
+
+  describe('publish', () => {
+    it('invalidates the local cache synchronously before awaiting the bus', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        const cache = i.get(UserResolutionCache)
+        await populateCache(cache, 's1', userOf('alice'))
+        const bus = i.get(IdentityEventBus)
+        const pending = bus.publish({ type: 'userLoggedOut', sessionId: 's1' })
+        // Local invalidation must already be visible — the bus.publish promise
+        // is irrelevant for in-process correctness on the originating node.
+        expect(cache.size).toBe(0)
+        await pending
+      })
+    })
+
+    it('fires local subscribers with the typed payload on every event variant', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        const bus = i.get(IdentityEventBus)
+        const events: IdentityEvent[] = []
+        using _u = bus.subscribe('userLoggedOut', (event) => events.push(event))
+        using _s = bus.subscribe('sessionInvalidated', (event) => events.push(event))
+        using _r = bus.subscribe('userRolesChanged', (event) => events.push(event))
+        using _d = bus.subscribe('userDeleted', (event) => events.push(event))
+        using _p = bus.subscribe('passwordChanged', (event) => events.push(event))
+
+        await bus.publish({ type: 'userLoggedOut', sessionId: 's1' })
+        await bus.publish({ type: 'sessionInvalidated', sessionId: 's2' })
+        await bus.publish({ type: 'userRolesChanged', username: 'alice' })
+        await bus.publish({ type: 'userDeleted', username: 'bob' })
+        await bus.publish({ type: 'passwordChanged', username: 'carol' })
+
+        expect(events).toEqual([
+          { type: 'userLoggedOut', sessionId: 's1' },
+          { type: 'sessionInvalidated', sessionId: 's2' },
+          { type: 'userRolesChanged', username: 'alice' },
+          { type: 'userDeleted', username: 'bob' },
+          { type: 'passwordChanged', username: 'carol' },
+        ])
+      })
+    })
+
+    it('does not fire subscribers for other event types', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        const bus = i.get(IdentityEventBus)
+        const handler = vi.fn()
+        using _u = bus.subscribe('userLoggedOut', handler)
+
+        await bus.publish({ type: 'sessionInvalidated', sessionId: 'x' })
+        await bus.publish({ type: 'userRolesChanged', username: 'alice' })
+
+        expect(handler).not.toHaveBeenCalled()
+      })
+    })
+
+    it('rejects when called after dispose', async () => {
+      const injector = createInjector()
+      const bus = injector.get(IdentityEventBus)
+      await injector[Symbol.asyncDispose]()
+      await expect(bus.publish({ type: 'userLoggedOut', sessionId: 's1' })).rejects.toThrow(/disposed/)
+    })
+
+    it('publishes onto the underlying CrossNodeBus topic', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        const crossNodeBus = i.get(CrossNodeBus)
+        const wireHandler = vi.fn<(message: BusMessage) => void>()
+        using _sub = crossNodeBus.subscribe(IDENTITY_EVENT_TOPIC, wireHandler)
+
+        await i.get(IdentityEventBus).publish({ type: 'userRolesChanged', username: 'alice' })
+
+        expect(wireHandler).toHaveBeenCalledTimes(1)
+        expect(wireHandler.mock.calls[0][0].payload).toEqual({ type: 'userRolesChanged', username: 'alice' })
+      })
+    })
+  })
+
+  describe('subscribe', () => {
+    it('returns a Disposable that removes the listener', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        const bus = i.get(IdentityEventBus)
+        const handler = vi.fn()
+        const sub = bus.subscribe('userLoggedOut', handler)
+        await bus.publish({ type: 'userLoggedOut', sessionId: 's1' })
+        sub[Symbol.dispose]()
+        await bus.publish({ type: 'userLoggedOut', sessionId: 's2' })
+        expect(handler).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('isolates listener errors so peers still run', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        const bus = i.get(IdentityEventBus)
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+        try {
+          const peer = vi.fn()
+          using _bad = bus.subscribe('userLoggedOut', () => {
+            throw new Error('boom')
+          })
+          using _good = bus.subscribe('userLoggedOut', peer)
+
+          await bus.publish({ type: 'userLoggedOut', sessionId: 's1' })
+
+          expect(peer).toHaveBeenCalledTimes(1)
+          expect(errorSpy).toHaveBeenCalled()
+        } finally {
+          errorSpy.mockRestore()
+        }
+      })
+    })
+
+    it('lets a handler dispose its own subscription mid-emit without skipping peers', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        const bus = i.get(IdentityEventBus)
+        const peer = vi.fn()
+        let selfDispose: Disposable | null = null
+        selfDispose = bus.subscribe('userLoggedOut', () => {
+          selfDispose?.[Symbol.dispose]()
+        })
+        using _peer = bus.subscribe('userLoggedOut', peer)
+
+        await bus.publish({ type: 'userLoggedOut', sessionId: 's1' })
+
+        expect(peer).toHaveBeenCalledTimes(1)
+      })
+    })
+  })
+
+  describe('cross-node delivery', () => {
+    it('logout on node A invalidates the cached session on node B', async () => {
+      using network = createInProcessBusNetwork({ count: 2 })
+      const [busA, busB] = network.buses
+      await usingAsync(createInjector(), async (a) => {
+        await usingAsync(createInjector(), async (b) => {
+          a.bind(CrossNodeBus, defineInProcessCrossNodeBus({ broker: network.broker, nodeId: busA.nodeId }))
+          b.bind(CrossNodeBus, defineInProcessCrossNodeBus({ broker: network.broker, nodeId: busB.nodeId }))
+
+          const cacheA = a.get(UserResolutionCache)
+          const cacheB = b.get(UserResolutionCache)
+          await populateCache(cacheA, 's1', userOf('alice'))
+          await populateCache(cacheB, 's1', userOf('alice'))
+
+          // Force the bus singletons to materialise so subscriptions are live.
+          const facadeA = a.get(IdentityEventBus)
+          b.get(IdentityEventBus)
+
+          await facadeA.publish({ type: 'userLoggedOut', sessionId: 's1' })
+
+          expect(cacheA.size).toBe(0)
+          expect(cacheB.size).toBe(0)
+        })
+      })
+    })
+
+    it('userRolesChanged on node A drops every alice entry on node B', async () => {
+      using network = createInProcessBusNetwork({ count: 2 })
+      const [busA, busB] = network.buses
+      await usingAsync(createInjector(), async (a) => {
+        await usingAsync(createInjector(), async (b) => {
+          a.bind(CrossNodeBus, defineInProcessCrossNodeBus({ broker: network.broker, nodeId: busA.nodeId }))
+          b.bind(CrossNodeBus, defineInProcessCrossNodeBus({ broker: network.broker, nodeId: busB.nodeId }))
+
+          const cacheB = b.get(UserResolutionCache)
+          await populateCache(cacheB, 's-a-1', userOf('alice'))
+          await populateCache(cacheB, 's-a-2', userOf('alice'))
+          await populateCache(cacheB, 's-b-1', userOf('bob'))
+          a.get(IdentityEventBus)
+          b.get(IdentityEventBus)
+
+          await a.get(IdentityEventBus).publish({ type: 'userRolesChanged', username: 'alice' })
+
+          expect(cacheB.size).toBe(1)
+        })
+      })
+    })
+
+    it('local subscribers on node A see the event before the bus broadcasts', async () => {
+      using network = createInProcessBusNetwork({ count: 2 })
+      const [busA, busB] = network.buses
+      await usingAsync(createInjector(), async (a) => {
+        await usingAsync(createInjector(), async (b) => {
+          a.bind(CrossNodeBus, defineInProcessCrossNodeBus({ broker: network.broker, nodeId: busA.nodeId }))
+          b.bind(CrossNodeBus, defineInProcessCrossNodeBus({ broker: network.broker, nodeId: busB.nodeId }))
+
+          const order: string[] = []
+          using _localA = a.get(IdentityEventBus).subscribe('userDeleted', () => order.push('A-local'))
+          using _remoteB = b.get(IdentityEventBus).subscribe('userDeleted', () => order.push('B-remote'))
+
+          await a.get(IdentityEventBus).publish({ type: 'userDeleted', username: 'bob' })
+
+          // A-local fires synchronously inside `publish`; B-remote fires after
+          // the bus accepts the message — same tick in-process, but ordering
+          // is guaranteed by the publish path's local-first contract.
+          expect(order).toEqual(['A-local', 'B-remote'])
+        })
+      })
+    })
+
+    it('drops malformed payloads received over the bus without invalidating the cache', async () => {
+      using network = createInProcessBusNetwork({ count: 2 })
+      const [busA, busB] = network.buses
+      await usingAsync(createInjector(), async (a) => {
+        await usingAsync(createInjector(), async (b) => {
+          a.bind(CrossNodeBus, defineInProcessCrossNodeBus({ broker: network.broker, nodeId: busA.nodeId }))
+          b.bind(CrossNodeBus, defineInProcessCrossNodeBus({ broker: network.broker, nodeId: busB.nodeId }))
+
+          const cacheB = b.get(UserResolutionCache)
+          await populateCache(cacheB, 's1', userOf('alice'))
+          b.get(IdentityEventBus)
+          a.get(IdentityEventBus)
+
+          await a.get(CrossNodeBus).publish(IDENTITY_EVENT_TOPIC, { type: 'unknownEvent', sessionId: 's1' })
+          await a.get(CrossNodeBus).publish(IDENTITY_EVENT_TOPIC, null)
+          await a.get(CrossNodeBus).publish(IDENTITY_EVENT_TOPIC, { type: 'userLoggedOut' })
+
+          expect(cacheB.size).toBe(1)
+        })
+      })
+    })
+  })
+
+  describe('shared helpers', () => {
+    it('exposes the cache-key shape used by the facade subscribers', () => {
+      expect(sessionCacheKey('s1')).toBe('cookie:s1')
+      expect(userCacheTag('alice')).toBe('user:alice')
+    })
+  })
+})