@furystack/rest-service 14.0.0 → 14.1.0

package/src/actions/get-current-user.ts

@@ -4,10 +4,7 @@ import { Authenticate } from '../authenticate.js'
 import type { RequestAction } from '../request-action-implementation.js'
 import { JsonResult } from '../request-action-implementation.js'
 
-/**
- * Action that returns the current authenticated user
- * @param injector The injector from the current stack
- */
+/** Returns the current authenticated user; 401 if no user is bound. */
 export const GetCurrentUser: RequestAction<{
   result: User
 }> = Authenticate()(async ({ injector }) => {

package/src/actions/is-authenticated.ts

@@ -3,10 +3,9 @@ import type { RequestAction } from '../request-action-implementation.js'
 import { JsonResult } from '../request-action-implementation.js'
 
 /**
- * Action that returns if the current user is authenticated
- * @param options The options for the Custom Action
- * @param options.injector The Injector from the current context
- * @returns A standard authentication result
+ * Returns `{ isAuthenticated: boolean }`. Unauthenticated callers receive
+ * a 200 with `false` rather than a 401 — use this when the client needs to
+ * branch on auth state without triggering a re-login flow.
  */
 export const IsAuthenticated: RequestAction<{ result: { isAuthenticated: boolean } }> = async ({ injector }) => {
   const isAuthenticatedResult = await isAuthenticated(injector)

package/src/actions/logout.ts

@@ -3,12 +3,8 @@ import type { RequestAction } from '../request-action-implementation.js'
 import { EmptyResult } from '../request-action-implementation.js'
 
 /**
- * Action that logs out the current user
- * @param root0 The Options object
- * @param root0.injector The injector from the context
- * @param root0.request The current Request object
- * @param root0.response The Response object
- * @returns An empty result that indicates the success
+ * Logs out via {@link HttpUserContext.cookieLogout} — clears the session
+ * cookie and removes the session row from the session DataSet.
  */
 export const LogoutAction: RequestAction<{ result: unknown }> = async ({ injector, request, response }) => {
   await injector.get(HttpUserContext).cookieLogout(request, response)

package/src/actions/not-found-action.ts

@@ -1,9 +1,7 @@
 import type { RequestAction } from '../request-action-implementation.js'
 import { JsonResult } from '../request-action-implementation.js'
 
-/**
- * @returns The standard Not Found action result
- */
+/** Default `404` action. Returns `{ error: 'Content not found' }`. */
 export const NotFoundAction: RequestAction<{ result: { error: string } }> = async () => {
   return JsonResult(
     {

package/src/actions/password-login-action.ts

@@ -6,18 +6,11 @@ import type { LoginResponseStrategy } from '../login-response-strategy.js'
 import type { RequestAction } from '../request-action-implementation.js'
 
 /**
- * Creates a login {@link RequestAction} that authenticates a user by
- * username + password, then delegates session/token creation to the
- * provided {@link LoginResponseStrategy}.
- *
- * The return type is inferred from the strategy:
- * - Cookie strategy -> `ActionResult<User>`
- * - JWT strategy   -> `ActionResult<{ accessToken: string; refreshToken: string }>`
- *
- * A random delay (0-1 s) is added on failure to mitigate timing attacks.
- *
- * @param strategy The login response strategy that produces the session/token result
- * @returns A `RequestAction` that can be wired into a REST API route
+ * Username + password login action. Authenticates via {@link HttpUserContext},
+ * then delegates session/token creation to `strategy`. The result type is
+ * inferred from the strategy (e.g. `User` for cookies, `{ accessToken,
+ * refreshToken }` for JWT). Adds a 0–1 s random delay on failure to mitigate
+ * timing attacks; rethrows as `RequestError(400)`.
  */
 export const createPasswordLoginAction = <TResult>(
   strategy: LoginResponseStrategy<TResult>,

package/src/authenticate.ts

@@ -5,21 +5,15 @@ import type { ActionResult, RequestAction, RequestActionOptions } from './reques
 import { JsonResult } from './request-action-implementation.js'
 
 /**
- * Higher-order function that wraps a request action to require authentication.
- * If the user is not authenticated, returns a 401 Unauthorized response.
- * Includes a random delay on unauthorized requests to mitigate timing attacks.
+ * Wraps a {@link RequestAction} to require authentication. Unauthenticated
+ * requests return `401 Unauthorized` (with `WWW-Authenticate: Basic` when
+ * the chain includes Basic Auth). Adds a 0–1 s random delay on rejection to
+ * mitigate timing attacks.
  *
- * @returns A function that wraps the provided action with authentication check
  * @example
  * ```ts
- * // Wrap an endpoint to require authentication
- * const protectedEndpoint = Authenticate()(myEndpoint)
- *
- * // Or use directly in API definition
  * api: {
- *   GET: {
- *     '/users': Authenticate()(getUsersEndpoint)
- *   }
+ *   GET: { '/users': Authenticate()(getUsersEndpoint) },
  * }
  * ```
  */

package/src/authentication-providers/authentication-provider.ts

@@ -22,4 +22,21 @@ export type AuthenticationProvider = {
    */
   readonly name: string
   authenticate: (request: Pick<IncomingMessage, 'headers'>) => Promise<User | null>
+  /**
+   * Optional cache-key resolver consulted by the user-resolution cache before
+   * the provider chain is walked.
+   *
+   * Returns a stable, opaque string identifying the authenticated principal
+   * for the given request, or `null` when this provider does not apply to
+   * the request (or refuses to participate in caching — e.g. Basic Auth,
+   * which must verify the password on every request).
+   *
+   * The first non-null key returned by the configured providers is used as
+   * the cache key. Keys returned by different providers must not collide;
+   * built-in providers prefix their keys (`cookie:`, `jwt:`).
+   *
+   * If no provider returns a key, the request bypasses the cache entirely
+   * and the provider chain is walked on every call.
+   */
+  readonly getCacheKey?: (request: Pick<IncomingMessage, 'headers'>) => string | null
 }

package/src/authentication-providers/basic-auth-provider.ts

@@ -3,6 +3,13 @@ import type { AuthenticationProvider } from './authentication-provider.js'
 
 /**
  * Creates an authentication provider for HTTP Basic Authentication.
+ *
+ * **Caching note:** this provider intentionally does **not** implement
+ * `getCacheKey`. Caching authenticated users by username would bypass
+ * password verification on every cache hit — the cache cannot revalidate the
+ * password without re-running the authenticator. Basic Auth requests
+ * therefore always walk the provider chain, which is also where the password
+ * is verified.
  * @param authenticateUser Callback that verifies credentials and returns a User or throws
  */
 export const createBasicAuthProvider = (

package/src/authentication-providers/cookie-auth-provider.ts

@@ -1,5 +1,6 @@
 import type { User } from '@furystack/core'
 import { UnauthenticatedError } from '@furystack/security'
+import { sessionCacheKey, type SessionCacheKey } from '../identity-cache-keys.js'
 import type { DefaultSession } from '../models/default-session.js'
 import type { AuthenticationProvider } from './authentication-provider.js'
 import { extractSessionIdFromCookies } from './helpers.js'
@@ -23,4 +24,11 @@ export const createCookieAuthProvider = (
     if (!session) throw new UnauthenticatedError()
     return await getUserByName(session.username)
   },
+  // The session id alone uniquely identifies the principal — caching by it is
+  // safe because session invalidation (logout, expiry) drops the session row,
+  // and the TTL on the user-resolution cache bounds staleness across nodes.
+  getCacheKey: (request): SessionCacheKey | null => {
+    const sessionId = extractSessionIdFromCookies(request, cookieName)
+    return sessionId ? sessionCacheKey(sessionId) : null
+  },
 })

package/src/authorize.ts

@@ -1,25 +1,14 @@
 import { AuthorizationError, isAuthorized } from '@furystack/core'
 import { sleepAsync } from '@furystack/utils'
+import type { Authenticate } from './authenticate.js'
 import type { ActionResult, RequestAction, RequestActionOptions } from './request-action-implementation.js'
 
 /**
- * Higher-order function that wraps a request action to require specific roles.
- * If the user does not have the required roles, throws an AuthorizationError.
- * Includes a random delay on unauthorized requests to mitigate timing attacks.
- *
- * @param roles - The roles required to access the endpoint
- * @returns A function that wraps the provided action with authorization check
- * @example
- * ```ts
- * // Require 'admin' role
- * const adminEndpoint = Authorize('admin')(myEndpoint)
- *
- * // Require multiple roles (user must have ALL specified roles)
- * const superAdminEndpoint = Authorize('admin', 'superuser')(myEndpoint)
- *
- * // Chain with Authenticate for authentication + authorization
- * const protectedEndpoint = Authenticate()(Authorize('admin')(myEndpoint))
- * ```
+ * Wraps a {@link RequestAction} to require **all** specified roles. Throws
+ * {@link AuthorizationError} (translated to 403 by `ErrorAction`) when any
+ * role is missing. Adds a 0–1 s random delay on rejection to mitigate
+ * timing attacks. Compose with {@link Authenticate} to require both:
+ * `Authenticate()(Authorize('admin')(myEndpoint))`.
  */
 export const Authorize =
   (...roles: string[]) =>

package/src/get-schema-from-api.ts

@@ -61,6 +61,7 @@ export const getSchemaFromApi = <T extends RestApiImplementation<RestApi>>({
     if (!endpoints[methodKey]) {
       endpoints[methodKey] = {}
     }
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- false positive: TS narrows `endpointList` to a union the iterator can't index without this cast
     Object.entries(endpointList as Record<string, RequestAction<{ result: unknown }>>).forEach(
       ([url, requestAction]) => {
         if (method && url && requestAction) {

package/src/helpers.ts

@@ -1,6 +1,5 @@
-import { useSystemIdentityContext, type User } from '@furystack/core'
+import { useSystemIdentityContext } from '@furystack/core'
 import type { Injector } from '@furystack/inject'
-import type { DataSet } from '@furystack/repository'
 import type { RestApi } from '@furystack/rest'
 import { PasswordAuthenticator } from '@furystack/security'
 import { PathHelper } from '@furystack/utils'
@@ -18,10 +17,12 @@ import { buildProxyServerApi, type ProxyOptions } from './proxy-runtime.js'
 import { compileApi, onRestApiMessage, type RestApiImplementation, shouldExecRequest } from './rest-api-runtime.js'
 import { ServerTelemetryToken } from './server-telemetry.js'
 import { buildStaticSiteServerApi, type StaticServerOptions } from './static-site-runtime.js'
+import type { SessionStore, UserStore } from './user-store.js'
 
 /**
- * Options accepted by {@link useRestService}. Mirrors the pre-migration
- * shape, minus fields that have moved to tokens.
+ * Options accepted by {@link useRestService}. Cross-cutting concerns
+ * (authentication, telemetry) have moved to DI tokens — they are not
+ * configured here.
  */
 export interface ImplementApiOptions<T extends RestApi> {
   /** The structure of the implemented API. */
@@ -49,11 +50,10 @@ export interface ImplementApiOptions<T extends RestApi> {
 }
 
 /**
- * Acquires a pooled HTTP server, compiles the user-supplied API definition
+ * Acquires a pooled HTTP server (creating one if needed), compiles `api`
  * and attaches a {@link ServerApi} that dispatches matching requests.
- *
- * Public contract is unchanged from the pre-migration release; internally
- * everything goes through the functional tokens.
+ * Multiple `useRestService` calls on the same `port` + `hostName` share a
+ * single underlying HTTP server.
  */
 export const useRestService = async <T extends RestApi>(options: ImplementApiOptions<T>): Promise<ServerApi> => {
   const {
@@ -71,14 +71,14 @@ export const useRestService = async <T extends RestApi>(options: ImplementApiOpt
   } = options
 
   const extendedApi: typeof api = enableGetSchema
-    ? ({
+    ? {
         ...api,
         GET: {
           ...api.GET,
           '/schema': CreateGetSchemaAction(api, name, description, version),
           '/openapi.json': CreateGetOpenApiDocumentAction(api, name, description, version),
         },
-      } as typeof api)
+      }
     : api
 
   const supportedMethods = Object.keys(extendedApi)
@@ -129,7 +129,7 @@ export const useHttpAuthentication = (injector: Injector, overrides?: Partial<Ht
   }
   const systemInjector = useSystemIdentityContext({ injector, username: 'useHttpAuthentication' })
   const passwordAuthenticator = injector.get(PasswordAuthenticator)
-  const userDataSet = systemInjector.get(mergedSettings.userDataSet) as unknown as DataSet<User, 'username'>
+  const userDataSet = systemInjector.get(mergedSettings.userDataSet)
   const sessionDataSet = systemInjector.get(mergedSettings.sessionDataSet)
 
   const providers: AuthenticationProvider[] = []

package/src/http-authentication-settings.ts

@@ -1,7 +1,10 @@
 import type { User } from '@furystack/core'
+import type { Injector } from '@furystack/inject'
 import { defineService, type Token } from '@furystack/inject'
 import type { DataSetToken } from '@furystack/repository'
 import type { AuthenticationProvider } from './authentication-providers/authentication-provider.js'
+import type { useHttpAuthentication } from './helpers.js'
+import type { HttpUserContext } from './http-user-context.js'
 import type { DefaultSession } from './models/default-session.js'
 import { SessionDataSet, UserDataSet } from './user-store.js'
 
@@ -10,12 +13,10 @@ import { SessionDataSet, UserDataSet } from './user-store.js'
  * during application setup and consumed by {@link HttpUserContext},
  * cookie-login strategies and OpenAPI generators.
  *
- * The field shape reflects the functional-DI redesign:
- *
- * - `userDataSet` / `sessionDataSet` are token references (not accessors).
- *   Consumers resolve them through the injector at the appropriate scope.
- * - `authenticationProviders` is a simple ordered list; `HttpUserContext`
- *   walks it on every unauthenticated request.
+ * `userDataSet` / `sessionDataSet` are token references — consumers resolve
+ * them through the injector at the appropriate scope. `authenticationProviders`
+ * is an ordered list walked by {@link HttpUserContext} on every
+ * unauthenticated request.
  */
 export interface HttpAuthenticationSettings {
   /** Data set token for user lookups. */
@@ -32,8 +33,33 @@ export interface HttpAuthenticationSettings {
    * `useJwtAuthentication`.
    */
   authenticationProviders: AuthenticationProvider[]
+  /**
+   * TTL applied to the user-resolution cache. Every authenticated request
+   * runs at most one provider chain walk per cache key per TTL window;
+   * subsequent calls within the window return the cached `User`.
+   *
+   * Bounds the staleness window for out-of-band identity changes
+   * (session invalidation on a sibling instance, role mutation in storage,
+   * etc.) when the application is deployed across multiple nodes.
+   *
+   * Set to `0` to disable caching entirely. When omitted, the default
+   * {@link DEFAULT_USER_CACHE_TTL_MS} is used by `UserResolutionCache`.
+   */
+  userCacheTtlMs?: number
+  /**
+   * Maximum number of entries in the user-resolution cache before LRU
+   * eviction kicks in. When omitted, the default
+   * {@link DEFAULT_USER_CACHE_CAPACITY} is used by `UserResolutionCache`.
+   */
+  userCacheCapacity?: number
 }
 
+/** Default TTL applied to the user-resolution cache (30 seconds). */
+export const DEFAULT_USER_CACHE_TTL_MS = 30_000
+
+/** Default LRU capacity ceiling for the user-resolution cache. */
+export const DEFAULT_USER_CACHE_CAPACITY = 10_000
+
 /**
  * Returns a fresh copy of the default {@link HttpAuthenticationSettings}.
  * Used as the starting point inside {@link useHttpAuthentication}.
@@ -44,6 +70,8 @@ export const defaultHttpAuthenticationSettings = (): HttpAuthenticationSettings
   cookieName: 'fss',
   enableBasicAuth: true,
   authenticationProviders: [],
+  userCacheTtlMs: DEFAULT_USER_CACHE_TTL_MS,
+  userCacheCapacity: DEFAULT_USER_CACHE_CAPACITY,
 })
 
 /**

package/src/http-server-pool.spec.ts

@@ -179,7 +179,7 @@ describe('HttpServerPool', () => {
       cb?.(closeError)
       return record.server
     })
-    record.server.close = closeSpy as unknown as typeof record.server.close
+    record.server.close = closeSpy
     ;(record.server as unknown as { off: (...args: unknown[]) => void }).off = () => undefined
 
     await expect(injector[Symbol.asyncDispose]()).resolves.toBeUndefined()

package/src/http-user-context.spec.ts

@@ -185,7 +185,7 @@ describe('HttpUserContext', () => {
         await setupUser(i, 'testuser', 'password')
         const result = await i.get(HttpUserContext).authenticateRequest({
           headers: { authorization: `Basic dGVzdHVzZXI6cGFzc3dvcmQ=` },
-        } as IncomingMessage)
+        })
         expect(result.username).toBe('testuser')
       })
     })
@@ -197,7 +197,7 @@ describe('HttpUserContext', () => {
         await expect(
           i.get(HttpUserContext).authenticateRequest({
             headers: { authorization: `Basic dGVzdHVzZXI6cGFzc3dvcmQ=` },
-          } as IncomingMessage),
+          }),
         ).rejects.toBeInstanceOf(UnauthenticatedError)
       })
     })
@@ -209,7 +209,7 @@ describe('HttpUserContext', () => {
         await expect(
           ctx.authenticateRequest({
             headers: { cookie: `${ctx.authentication.cookieName}=666;` },
-          } as IncomingMessage),
+          }),
         ).rejects.toBeInstanceOf(UnauthenticatedError)
       })
     })
@@ -223,7 +223,7 @@ describe('HttpUserContext', () => {
 
         const result = await ctx.authenticateRequest({
           headers: { cookie: `${ctx.authentication.cookieName}=666;` },
-        } as IncomingMessage)
+        })
         expect(result).toEqual(testUser)
       })
     })
@@ -273,26 +273,33 @@ describe('HttpUserContext', () => {
   })
 
   describe('getCurrentUser', () => {
-    it('caches the result of authenticateRequest within the request scope', async () => {
+    it('caches the result of authenticateRequest by session id when the cookie provider yields a key', async () => {
       await usingAsync(createInjector(), async (i) => {
         prepareInjector(i)
         const ctx = i.get(HttpUserContext)
+        const cookiedRequest = {
+          headers: { cookie: `${ctx.authentication.cookieName}=session-1;` },
+        } as IncomingMessage
         ctx.authenticateRequest = vi.fn(async () => testUser)
-        const first = await ctx.getCurrentUser(request)
-        const second = await ctx.getCurrentUser(request)
+        const first = await ctx.getCurrentUser(cookiedRequest)
+        const second = await ctx.getCurrentUser(cookiedRequest)
         expect(ctx.authenticateRequest).toHaveBeenCalledTimes(1)
         expect(first).toBe(testUser)
         expect(second).toBe(testUser)
       })
     })
 
-    it('does not leak a cached user between distinct requests on the same instance', async () => {
+    it('treats distinct sessions as distinct cache entries', async () => {
       await usingAsync(createInjector(), async (i) => {
         prepareInjector(i)
         const ctx = i.get(HttpUserContext)
         const otherUser: User = { username: 'otherUser', roles: [] }
-        const requestA = { headers: {} } as IncomingMessage
-        const requestB = { headers: {} } as IncomingMessage
+        const requestA = {
+          headers: { cookie: `${ctx.authentication.cookieName}=session-a;` },
+        } as IncomingMessage
+        const requestB = {
+          headers: { cookie: `${ctx.authentication.cookieName}=session-b;` },
+        } as IncomingMessage
         const authenticateRequest = vi
           .fn<(req: Pick<IncomingMessage, 'headers'>) => Promise<User>>()
           .mockResolvedValueOnce(testUser)
@@ -305,6 +312,47 @@ describe('HttpUserContext', () => {
       })
     })
 
+    it('bypasses the cache when no provider yields a key (e.g. Basic Auth, anonymous)', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        prepareInjector(i)
+        const ctx = i.get(HttpUserContext)
+        const anonRequest = { headers: {} } as IncomingMessage
+        const authenticateRequest = vi
+          .fn<(req: Pick<IncomingMessage, 'headers'>) => Promise<User>>()
+          .mockResolvedValue(testUser)
+        ctx.authenticateRequest = authenticateRequest
+        await ctx.getCurrentUser(anonRequest)
+        await ctx.getCurrentUser(anonRequest)
+        expect(authenticateRequest).toHaveBeenCalledTimes(2)
+      })
+    })
+
+    it('drops the local cache entry on cookieLogout so the next request re-authenticates', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        prepareInjector(i)
+        const ctx = i.get(HttpUserContext)
+        const sessionId = 'session-logout'
+        const cookiedRequest = {
+          headers: { cookie: `${ctx.authentication.cookieName}=${sessionId};` },
+        } as IncomingMessage
+        await i.get(SessionStore).add({ sessionId, username: testUser.username })
+        await i.get(UserStore).add(testUser)
+
+        const authenticateRequest = vi
+          .fn<(req: Pick<IncomingMessage, 'headers'>) => Promise<User>>()
+          .mockResolvedValue(testUser)
+        ctx.authenticateRequest = authenticateRequest
+
+        await ctx.getCurrentUser(cookiedRequest)
+        expect(authenticateRequest).toHaveBeenCalledTimes(1)
+
+        await ctx.cookieLogout(cookiedRequest, { setHeader: vi.fn() })
+
+        await ctx.getCurrentUser(cookiedRequest)
+        expect(authenticateRequest).toHaveBeenCalledTimes(2)
+      })
+    })
+
     it('re-walks providers after a failed authenticateRequest', async () => {
       await usingAsync(createInjector(), async (i) => {
         prepareInjector(i)
@@ -358,7 +406,7 @@ describe('HttpUserContext', () => {
 
         const logoutSetHeader = vi.fn()
         await ctx.cookieLogout(
-          { headers: { cookie: `${ctx.authentication.cookieName}=${sessionId};` } } as IncomingMessage,
+          { headers: { cookie: `${ctx.authentication.cookieName}=${sessionId};` } },
           { setHeader: logoutSetHeader },
         )
         expect(logoutSetHeader).toHaveBeenCalledWith(

package/src/http-user-context.ts

@@ -6,8 +6,11 @@ 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 { IdentityEventBus } from './identity-event-bus.js'
+import { resolveUserCacheKey, UserResolutionCache } from './user-resolution-cache.js'
 
 /**
  * Events emitted by a per-request {@link HttpUserContext} instance. Since
@@ -24,11 +27,14 @@ export type HttpUserContextEvents = {
  * Request-scoped authentication/authorization facade.
  *
  * `HttpUserContext` consolidates identity lookup, authentication-provider
- * walk-through and cookie session helpers behind a single object. Resolved
- * users are memoized per `request.headers` via a {@link WeakMap} so repeated
- * calls within the same request skip re-authentication — and so ancestor
- * scopes caching the same `HttpUserContext` instance cannot leak an
- * authenticated user into sibling requests.
+ * 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.
  */
 export interface HttpUserContext extends EventHub<HttpUserContextEvents> {
   /** The active {@link HttpAuthenticationSettings} captured at resolve time. */
@@ -55,29 +61,27 @@ export interface HttpUserContext extends EventHub<HttpUserContextEvents> {
 }
 
 /**
- * Internal concrete EventHub-backed {@link HttpUserContext}. Exposed via
- * the {@link HttpUserContextToken} token; constructed by its factory.
+ * 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 {
-  /**
-   * Per-request user cache keyed by the request's `headers` object identity.
-   * Each incoming HTTP/WS message allocates its own `headers` object, so
-   * entries here never leak between requests — even when this
-   * `HttpUserContext` instance happens to be cached by an ancestor scope
-   * (e.g. because setup code resolved it on the root injector before any
-   * per-request child scope existed).
-   */
-  private readonly userCache = new WeakMap<object, Promise<User>>()
-
   /**
    * `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.
    */
   constructor(
     public readonly authentication: HttpAuthenticationSettings,
     private readonly resolveAuthenticator: () => PasswordAuthenticator,
     private readonly systemInjector: Injector,
+    private readonly userCache: UserResolutionCache,
+    private readonly identityEventBus: IdentityEventBus,
   ) {
     super()
   }
@@ -114,19 +118,11 @@ class HttpUserContextImpl extends EventHub<HttpUserContextEvents> implements Htt
   }
 
   public async getCurrentUser(request: Pick<IncomingMessage, 'headers'>): Promise<User> {
-    const key = request.headers
-    const cached = this.userCache.get(key)
-    if (cached) {
-      return cached
-    }
-    const pending = this.authenticateRequest(request)
-    this.userCache.set(key, pending)
-    try {
-      return await pending
-    } catch (error) {
-      this.userCache.delete(key)
-      throw error
+    const cacheKey = resolveUserCacheKey(this.authentication, request)
+    if (!cacheKey) {
+      return this.authenticateRequest(request)
     }
+    return this.userCache.resolve(cacheKey, () => this.authenticateRequest(request))
   }
 
   public getSessionIdFromRequest(request: Pick<IncomingMessage, 'headers'>): string | null {
@@ -157,7 +153,6 @@ class HttpUserContextImpl extends EventHub<HttpUserContextEvents> implements Htt
     request: Pick<IncomingMessage, 'headers'>,
     response: { setHeader: (header: string, value: string) => void },
   ): Promise<void> {
-    this.userCache.delete(request.headers)
     const sessionId = this.getSessionIdFromRequest(request)
     response.setHeader('Set-Cookie', `${this.authentication.cookieName}=; Path=/; HttpOnly`)
 
@@ -167,6 +162,10 @@ class HttpUserContextImpl extends EventHub<HttpUserContextEvents> implements Htt
         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)
   }
@@ -193,10 +192,18 @@ export const HttpUserContext: Token<HttpUserContext, 'scoped'> = defineService({
   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)
+    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:')
+    })
+  })
+})