@furystack/rest-service 12.3.5 → 14.0.0

package/src/http-user-context.ts

@@ -1,17 +1,17 @@
 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 { extractSessionIdFromCookies } from './authentication-providers/helpers.js'
 import { HttpAuthenticationSettings } from './http-authentication-settings.js'
-import type { DefaultSession } from './models/default-session.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 +21,77 @@ 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. 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.
  */
-@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]
-  }
+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>
+}
 
-  private user?: User
+/**
+ * Internal concrete EventHub-backed {@link HttpUserContext}. Exposed via
+ * the {@link HttpUserContextToken} 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>>()
 
   /**
-   * @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.
    */
-  public async isAuthenticated(request: IncomingMessage) {
+  constructor(
+    public readonly authentication: HttpAuthenticationSettings,
+    private readonly resolveAuthenticator: () => PasswordAuthenticator,
+    private readonly systemInjector: Injector,
+  ) {
+    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 +101,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 +113,26 @@ 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 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
     }
-    return this.user
   }
 
   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 +141,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 +156,47 @@ 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> {
+    this.userCache.delete(request.headers)
     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))
     }
     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 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)
+  },
+})

package/src/index.ts

@@ -1,6 +1,5 @@
 export * from './actions/index.js'
 export * from './add-cors-header.js'
-export * from './api-manager.js'
 export * from './authenticate.js'
 export * from './authentication-providers/index.js'
 export * from './authorize.js'
@@ -8,15 +7,18 @@ export * from './endpoint-generators/index.js'
 export * from './get-schema-from-api.js'
 export * from './helpers.js'
 export * from './http-authentication-settings.js'
+export * from './http-server-pool.js'
 export * from './http-user-context.js'
 export * from './login-response-strategy.js'
 export * from './mime-types.js'
 export * from './models/index.js'
-export * from './proxy-manager.js'
+export * from './proxy-runtime.js'
 export * from './read-post-body.js'
 export * from './request-action-implementation.js'
+export * from './rest-api-runtime.js'
 export * from './schema-validator/index.js'
-export * from './server-manager.js'
 export * from './server-response-extensions.js'
-export * from './static-server-manager.js'
+export * from './server-telemetry.js'
+export * from './static-site-runtime.js'
+export * from './user-store.js'
 export * from './validate.js'

package/src/login-response-strategy.spec.ts

@@ -1,25 +1,25 @@
-import { InMemoryStore, User, addStore } from '@furystack/core'
-import { Injector } from '@furystack/inject'
-import { getRepository } from '@furystack/repository'
-import { PasswordCredential, PasswordResetToken, usePasswordPolicy } from '@furystack/security'
+import type { User } from '@furystack/core'
+import { InMemoryStore, User as UserModel, useSystemIdentityContext } from '@furystack/core'
+import { createInjector, type Injector } from '@furystack/inject'
+import {
+  PasswordCredential,
+  PasswordCredentialStore,
+  PasswordResetToken,
+  PasswordResetTokenStore,
+  usePasswordPolicy,
+} from '@furystack/security'
 import { usingAsync } from '@furystack/utils'
 import { describe, expect, it } from 'vitest'
-
 import { useHttpAuthentication } from './helpers.js'
 import { createCookieLoginStrategy } from './login-response-strategy.js'
 import { DefaultSession } from './models/default-session.js'
+import { SessionDataSet, SessionStore, UserStore } from './user-store.js'
 
 const setupInjector = (i: Injector) => {
-  addStore(i, new InMemoryStore({ model: User, primaryKey: 'username' }))
-    .addStore(new InMemoryStore({ model: DefaultSession, primaryKey: 'sessionId' }))
-    .addStore(new InMemoryStore({ model: PasswordCredential, primaryKey: 'userName' }))
-    .addStore(new InMemoryStore({ model: PasswordResetToken, primaryKey: 'token' }))
-
-  const repo = getRepository(i)
-  repo.createDataSet(User, 'username')
-  repo.createDataSet(DefaultSession, 'sessionId')
-  repo.createDataSet(PasswordCredential, 'userName')
-  repo.createDataSet(PasswordResetToken, 'token')
+  i.bind(UserStore, () => new InMemoryStore({ model: UserModel, primaryKey: 'username' }))
+  i.bind(SessionStore, () => new InMemoryStore({ model: DefaultSession, primaryKey: 'sessionId' }))
+  i.bind(PasswordCredentialStore, () => new InMemoryStore({ model: PasswordCredential, primaryKey: 'userName' }))
+  i.bind(PasswordResetTokenStore, () => new InMemoryStore({ model: PasswordResetToken, primaryKey: 'token' }))
 
   usePasswordPolicy(i)
   useHttpAuthentication(i)
@@ -28,8 +28,8 @@ const setupInjector = (i: Injector) => {
 describe('createCookieLoginStrategy', () => {
   const testUser: User = { username: 'testuser', roles: ['admin'] }
 
-  it('Should return the user as the response body', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('returns the user as the response body', async () => {
+    await usingAsync(createInjector(), async (i) => {
       setupInjector(i)
       const strategy = createCookieLoginStrategy(i)
       const result = await strategy.createLoginResponse(testUser, i)
@@ -37,8 +37,8 @@ describe('createCookieLoginStrategy', () => {
     })
   })
 
-  it('Should return status code 200', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('returns status code 200', async () => {
+    await usingAsync(createInjector(), async (i) => {
       setupInjector(i)
       const strategy = createCookieLoginStrategy(i)
       const result = await strategy.createLoginResponse(testUser, i)
@@ -46,8 +46,8 @@ describe('createCookieLoginStrategy', () => {
     })
   })
 
-  it('Should include a Set-Cookie header with the session ID', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('emits a Set-Cookie header with the generated session id', async () => {
+    await usingAsync(createInjector(), async (i) => {
       setupInjector(i)
       const strategy = createCookieLoginStrategy(i)
       const result = await strategy.createLoginResponse(testUser, i)
@@ -59,23 +59,24 @@ describe('createCookieLoginStrategy', () => {
     })
   })
 
-  it('Should persist the session in the DataSet', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('persists the session via SessionDataSet', async () => {
+    await usingAsync(createInjector(), async (i) => {
       setupInjector(i)
       const strategy = createCookieLoginStrategy(i)
       await strategy.createLoginResponse(testUser, i)
 
-      const repo = getRepository(i)
-      const sessionDataSet = repo.getDataSetFor(DefaultSession, 'sessionId')
-      const sessions = await sessionDataSet.find(i, { filter: { username: { $eq: 'testuser' } } })
-      expect(sessions).toHaveLength(1)
-      expect(sessions[0].username).toBe('testuser')
-      expect(sessions[0].sessionId).toBeTruthy()
+      await usingAsync(useSystemIdentityContext({ injector: i, username: 'spec' }), async (systemScope) => {
+        const sessionDataSet = systemScope.get(SessionDataSet)
+        const sessions = await sessionDataSet.find(systemScope, { filter: { username: { $eq: 'testuser' } } })
+        expect(sessions).toHaveLength(1)
+        expect(sessions[0].username).toBe('testuser')
+        expect(sessions[0].sessionId).toBeTruthy()
+      })
     })
   })
 
-  it('Should create unique session IDs for each call', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('creates unique session ids for each call', async () => {
+    await usingAsync(createInjector(), async (i) => {
       setupInjector(i)
       const strategy = createCookieLoginStrategy(i)
 

package/src/login-response-strategy.ts

@@ -9,14 +9,14 @@ import { JsonResult } from './request-action-implementation.js'
 
 /**
  * A pluggable strategy that turns an authenticated {@link User} into an
- * {@link ActionResult} containing the session/token data for the client.
+ * {@link ActionResult} carrying the session/token payload for the client.
  *
- * Pass a concrete strategy to action factories like
- * {@link createPasswordLoginAction} or `createGoogleLoginAction` to
- * decouple the authentication mechanism from the session/token mechanism.
+ * Pass a concrete strategy to action factories such as
+ * {@link createPasswordLoginAction} or `createGoogleLoginAction` to decouple
+ * the authentication mechanism from the session/token mechanism.
  *
- * @typeParam TResult The shape of the response body (e.g. `User` for cookies,
- *   `{ accessToken: string; refreshToken: string }` for JWT)
+ * @typeParam TResult The shape of the response body — e.g. `User` for
+ *   cookies, `{ accessToken, refreshToken }` for JWT.
  */
 export type LoginResponseStrategy<TResult> = {
   createLoginResponse: (user: User, injector: Injector) => Promise<ActionResult<TResult>>
@@ -25,19 +25,20 @@ export type LoginResponseStrategy<TResult> = {
 /**
  * Creates a cookie-based {@link LoginResponseStrategy}.
  *
- * On each login it generates a random session ID, persists it in the session
- * DataSet, and returns the user with a `Set-Cookie` header.
+ * On each login it generates a random session id, persists it via the
+ * configured session DataSet and returns the user with a `Set-Cookie`
+ * response header.
  *
- * @param injector The root injector (must have {@link HttpAuthenticationSettings} configured)
- * @returns A strategy that returns `ActionResult<User>`
+ * @param injector - The injector scope (typically the root) that carries
+ *   `HttpAuthenticationSettings` and a persistent session store.
  */
 export const createCookieLoginStrategy = (injector: Injector): LoginResponseStrategy<User> => {
-  const settings = injector.getInstance(HttpAuthenticationSettings)
+  const settings = injector.get(HttpAuthenticationSettings)
   const systemInjector = useSystemIdentityContext({ injector, username: 'CookieLoginStrategy' })
+  const sessionDataSet = systemInjector.get(settings.sessionDataSet)
 
   return {
     createLoginResponse: async (user) => {
-      const sessionDataSet = settings.getSessionDataSet(systemInjector)
       const sessionId = randomBytes(32).toString('hex')
       await sessionDataSet.add(systemInjector, { sessionId, username: user.username })
       return JsonResult(user, 200, {

package/src/openapi/generate-openapi-document.ts

@@ -193,6 +193,3 @@ export const generateOpenApiDocument = ({
 
   return doc
 }
-
-/** @deprecated Use generateOpenApiDocument instead */
-export const generateSwaggerJsonFromApiSchema = generateOpenApiDocument