@furystack/rest-service 13.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.spec.ts

@@ -1,16 +1,21 @@
-import { Injector } from '@furystack/inject'
+import { IdentityContext } from '@furystack/core'
+import { createInjector } from '@furystack/inject'
 import { usingAsync } from '@furystack/utils'
-import { IsAuthenticated } from './is-authenticated.js'
 import type { IncomingMessage, ServerResponse } from 'http'
-import { IdentityContext } from '@furystack/core'
-import { describe, it, expect } from 'vitest'
+import { describe, expect, it } from 'vitest'
+import { IsAuthenticated } from './is-authenticated.js'
 
 describe('isAuthenticated', () => {
   const request = { url: 'https://google.com' } as IncomingMessage
   const response = {} as ServerResponse
-  it('exec', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      i.setExplicitInstance({ isAuthenticated: async () => true }, IdentityContext)
+
+  it('returns the authentication status from the identity context', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      i.bind(IdentityContext, () => ({
+        isAuthenticated: () => Promise.resolve(true),
+        isAuthorized: () => Promise.resolve(true),
+        getCurrentUser: () => Promise.reject(new Error('not needed')),
+      }))
       const result = await IsAuthenticated({ injector: i, request, response })
       expect(result.statusCode).toBe(200)
       expect(result.chunk).toEqual({ isAuthenticated: true })

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-action.spec.ts

@@ -1,28 +1,28 @@
-import { Injector } from '@furystack/inject'
+import { createInjector } from '@furystack/inject'
+import { EventHub } from '@furystack/utils'
 import { usingAsync } from '@furystack/utils'
 import type { IncomingMessage, ServerResponse } from 'http'
 import { describe, expect, it, vi } from 'vitest'
-import { HttpUserContext } from '../http-user-context.js'
+import type { HttpUserContext } from '../http-user-context.js'
+import { HttpUserContext as HttpUserContextToken } from '../http-user-context.js'
 import { LogoutAction } from './logout.js'
 
 describe('LogoutAction', () => {
   const request = { url: 'https://google.com' } as IncomingMessage
   const response = {} as ServerResponse
 
-  it('exec', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const cookieLogout = vi.fn(async () => true)
-      i.setExplicitInstance(
-        {
-          cookieLogout,
-        },
-        HttpUserContext,
-      )
+  it('delegates to HttpUserContext.cookieLogout and returns an empty result', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const cookieLogout = vi.fn(async () => {
+        /* noop */
+      })
+      const stub = Object.assign(new EventHub(), { cookieLogout }) as unknown as HttpUserContext
+      i.bind(HttpUserContextToken, () => stub)
 
       const result = await LogoutAction({ request, response, injector: i })
       expect(result.statusCode).toBe(200)
       expect(result.chunk).toBe(undefined)
-      expect(cookieLogout).toBeCalled()
+      expect(cookieLogout).toHaveBeenCalled()
     })
   })
 })

package/src/actions/logout.ts

@@ -3,14 +3,10 @@ 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.getInstance(HttpUserContext).cookieLogout(request, response)
+  await injector.get(HttpUserContext).cookieLogout(request, response)
   return EmptyResult()
 }

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.spec.ts

@@ -1,37 +1,37 @@
-import { InMemoryStore, StoreManager, User, addStore } from '@furystack/core'
-import { Injector } from '@furystack/inject'
-import { getRepository } from '@furystack/repository'
-import { PasswordAuthenticator, PasswordCredential, PasswordResetToken, usePasswordPolicy } from '@furystack/security'
+import type { User } from '@furystack/core'
+import { InMemoryStore, User as UserModel } 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 type { IncomingMessage, ServerResponse } from 'http'
 import { describe, expect, it, vi } from 'vitest'
-
 import { useHttpAuthentication } from '../helpers.js'
 import type { LoginResponseStrategy } from '../login-response-strategy.js'
 import { DefaultSession } from '../models/default-session.js'
 import { JsonResult } from '../request-action-implementation.js'
+import { SessionStore, UserStore } from '../user-store.js'
+import { PasswordAuthenticator } from '@furystack/security'
 import { createPasswordLoginAction } from './password-login-action.js'
 
 const setupInjector = async (i: Injector, username: string, password: string) => {
-  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)
 
-  const sm = i.getInstance(StoreManager)
-  const pw = i.getInstance(PasswordAuthenticator)
-  const cred = await pw.hasher.createCredential(username, password)
-  await sm.getStoreFor(PasswordCredential, 'userName').add(cred)
-  await sm.getStoreFor(User, 'username').add({ username, roles: ['admin'] })
+  const authenticator = i.get(PasswordAuthenticator)
+  const cred = await authenticator.hasher.createCredential(username, password)
+  await i.get(PasswordCredentialStore).add(cred)
+  await i.get(UserStore).add({ username, roles: ['admin'] })
 }
 
 const mockStrategy: LoginResponseStrategy<User> = {
@@ -42,8 +42,8 @@ describe('createPasswordLoginAction', () => {
   const request = {} as IncomingMessage
   const response = {} as ServerResponse
 
-  it('Should delegate to the strategy on successful authentication', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('delegates to the strategy on successful authentication', async () => {
+    await usingAsync(createInjector(), async (i) => {
       await setupInjector(i, 'testuser', 'testpass')
       const action = createPasswordLoginAction(mockStrategy)
       const result = await action({
@@ -57,8 +57,8 @@ describe('createPasswordLoginAction', () => {
     })
   })
 
-  it('Should pass the correct user to the strategy', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('passes the authenticated user to the strategy', async () => {
+    await usingAsync(createInjector(), async (i) => {
       await setupInjector(i, 'testuser', 'testpass')
       const strategyFn = vi.fn(async (user: User) => JsonResult(user, 200))
       const strategy: LoginResponseStrategy<User> = { createLoginResponse: strategyFn }
@@ -73,8 +73,8 @@ describe('createPasswordLoginAction', () => {
     })
   })
 
-  it('Should throw RequestError on invalid credentials', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('throws RequestError on invalid password', async () => {
+    await usingAsync(createInjector(), async (i) => {
       await setupInjector(i, 'testuser', 'testpass')
       const action = createPasswordLoginAction(mockStrategy)
       await expect(
@@ -88,8 +88,8 @@ describe('createPasswordLoginAction', () => {
     })
   })
 
-  it('Should throw RequestError for nonexistent user', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('throws RequestError for an unknown user', async () => {
+    await usingAsync(createInjector(), async (i) => {
       await setupInjector(i, 'testuser', 'testpass')
       const action = createPasswordLoginAction(mockStrategy)
       await expect(
@@ -103,8 +103,8 @@ describe('createPasswordLoginAction', () => {
     })
   })
 
-  it('Should work with a custom result type from strategy', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('supports strategies returning custom result shapes', async () => {
+    await usingAsync(createInjector(), async (i) => {
       await setupInjector(i, 'testuser', 'testpass')
       const tokenStrategy: LoginResponseStrategy<{ accessToken: string }> = {
         createLoginResponse: async () => JsonResult({ accessToken: 'tok123' }, 200),

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>,
@@ -25,7 +18,7 @@ export const createPasswordLoginAction = <TResult>(
   return async ({ injector, getBody }) => {
     const body = await getBody()
     try {
-      const user = await injector.getInstance(HttpUserContext).authenticateUser(body.username, body.password)
+      const user = await injector.get(HttpUserContext).authenticateUser(body.username, body.password)
       return strategy.createLoginResponse(user, injector)
     } catch {
       await sleepAsync(Math.random() * 1000)

package/src/authenticate.spec.ts

@@ -1,84 +1,78 @@
 import { IdentityContext } from '@furystack/core'
-import { Injector } from '@furystack/inject'
-import { usingAsync } from '@furystack/utils'
+import { createInjector } from '@furystack/inject'
+import { EventHub, usingAsync } from '@furystack/utils'
 import type { IncomingMessage, ServerResponse } from 'http'
 import { describe, expect, it, vi } from 'vitest'
 import { Authenticate } from './authenticate.js'
-import { HttpUserContext } from './http-user-context.js'
+import type { HttpUserContext } from './http-user-context.js'
+import { HttpUserContext as HttpUserContextToken } from './http-user-context.js'
 import { EmptyResult } from './request-action-implementation.js'
 
+const makeHttpUserContextStub = (providers: Array<{ name: string }>): HttpUserContext =>
+  Object.assign(new EventHub(), {
+    authentication: { authenticationProviders: providers },
+  }) as unknown as HttpUserContext
+
 describe('Authenticate', () => {
-  const response = {} as any as ServerResponse
+  const response = {} as ServerResponse
   const request = { url: 'http://google.com' } as IncomingMessage
 
-  it('Should return 401 without WWW-Authenticate header when no basic-auth provider is registered', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const isAuthenticatedAction = vi.fn(async () => false)
-
-      i.setExplicitInstance(
-        { isAuthenticated: isAuthenticatedAction, getCurrentUser: async () => Promise.reject(new Error(':(')) },
-        IdentityContext,
-      )
+  it('returns 401 without WWW-Authenticate when no basic-auth provider is registered', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const isAuthenticated = vi.fn(async () => false)
+      i.bind(IdentityContext, () => ({
+        isAuthenticated,
+        getCurrentUser: () => Promise.reject(new Error(':(')),
+        isAuthorized: () => Promise.resolve(false),
+      }))
+      i.bind(HttpUserContextToken, () => makeHttpUserContextStub([]))
 
-      i.setExplicitInstance(
-        {
-          authentication: { authenticationProviders: [] },
-        },
-        HttpUserContext,
-      )
-      const exampleAuthenticatedAction = vi.fn(async () => EmptyResult())
-      const authorized = Authenticate()(exampleAuthenticatedAction)
+      const exampleAction = vi.fn(async () => EmptyResult())
+      const authorized = Authenticate()(exampleAction)
 
       const result = await authorized({ injector: i, request, response })
       expect(result.statusCode).toBe(401)
       expect(result.chunk).toEqual({ error: 'unauthorized' })
       expect(result.headers).toEqual({ 'Content-Type': 'application/json' })
-      expect(exampleAuthenticatedAction).not.toBeCalled()
+      expect(exampleAction).not.toHaveBeenCalled()
     })
   })
 
-  it('Should return 401 with WWW-Authenticate: Basic header when basic-auth provider is registered', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const isAuthenticatedAction = vi.fn(async () => false)
-
-      i.setExplicitInstance(
-        { isAuthenticated: isAuthenticatedAction, getCurrentUser: async () => Promise.reject(new Error(':(')) },
-        IdentityContext,
-      )
+  it('returns 401 with WWW-Authenticate: Basic when a basic-auth provider is registered', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const isAuthenticated = vi.fn(async () => false)
+      i.bind(IdentityContext, () => ({
+        isAuthenticated,
+        getCurrentUser: () => Promise.reject(new Error(':(')),
+        isAuthorized: () => Promise.resolve(false),
+      }))
+      i.bind(HttpUserContextToken, () => makeHttpUserContextStub([{ name: 'basic-auth' }]))
 
-      i.setExplicitInstance(
-        {
-          authentication: {
-            authenticationProviders: [{ name: 'basic-auth', authenticate: async () => null }],
-          },
-        },
-        HttpUserContext,
-      )
-      const exampleAuthenticatedAction = vi.fn(async () => EmptyResult())
-      const authorized = Authenticate()(exampleAuthenticatedAction)
+      const exampleAction = vi.fn(async () => EmptyResult())
+      const authorized = Authenticate()(exampleAction)
 
       const result = await authorized({ injector: i, request, response })
       expect(result.statusCode).toBe(401)
       expect(result.chunk).toEqual({ error: 'unauthorized' })
       expect(result.headers).toEqual({ 'Content-Type': 'application/json', 'WWW-Authenticate': 'Basic' })
-      expect(exampleAuthenticatedAction).not.toBeCalled()
+      expect(exampleAction).not.toHaveBeenCalled()
     })
   })
 
-  it('Should exec the original action if authorized', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const isAuthenticatedAction = vi.fn(async () => true)
-      i.setExplicitInstance(
-        { isAuthenticated: isAuthenticatedAction, getCurrentUser: async () => Promise.reject(new Error(':(')) },
-        IdentityContext,
-      )
-      const exampleAuthenticatedAction = vi.fn(async () => EmptyResult())
-      const authorized = Authenticate()(exampleAuthenticatedAction)
-      const params = { injector: i, body: undefined, query: undefined, request, response }
+  it('invokes the wrapped action when the caller is authenticated', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      i.bind(IdentityContext, () => ({
+        isAuthenticated: () => Promise.resolve(true),
+        getCurrentUser: () => Promise.reject(new Error(':(')),
+        isAuthorized: () => Promise.resolve(true),
+      }))
+      const exampleAction = vi.fn(async () => EmptyResult())
+      const authorized = Authenticate()(exampleAction)
+      const params = { injector: i, request, response }
       const result = await authorized(params)
       expect(result.statusCode).toBe(200)
       expect(result.chunk).toBe(undefined)
-      expect(exampleAuthenticatedAction).toBeCalledWith(params)
+      expect(exampleAction).toHaveBeenCalledWith(params)
     })
   })
 })

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) },
  * }
  * ```
  */
@@ -32,7 +26,7 @@ export const Authenticate =
       if (!authenticated) {
         await sleepAsync(Math.random() * 1000)
         const hasBasicAuth = injector
-          .getInstance(HttpUserContext)
+          .get(HttpUserContext)
           .authentication.authenticationProviders.some((p) => p.name === 'basic-auth')
         return JsonResult(
           { error: 'unauthorized' },

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.spec.ts

@@ -1,6 +1,6 @@
 import type { User } from '@furystack/core'
 import { AuthorizationError, IdentityContext } from '@furystack/core'
-import { Injector } from '@furystack/inject'
+import { createInjector } from '@furystack/inject'
 import { usingAsync } from '@furystack/utils'
 import type { IncomingMessage, ServerResponse } from 'http'
 import { describe, expect, it, vi } from 'vitest'
@@ -8,59 +8,57 @@ import { Authorize } from './authorize.js'
 import { EmptyResult } from './request-action-implementation.js'
 
 describe('Authorize', () => {
-  const response = {} as any as ServerResponse
+  const response = {} as ServerResponse
   const request = { url: 'http://google.com' } as IncomingMessage
 
-  it('Should return 403 when failed to get current user', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const isAuthorizedAction = vi.fn(async () => false)
-      i.setExplicitInstance(
-        { isAuthorized: isAuthorizedAction, getCurrentUser: () => Promise.reject(new Error(':(')) },
-        IdentityContext,
-      )
-      const exampleAuthorizedAction = vi.fn(async () => EmptyResult())
-      const authorized = Authorize('Role1')(exampleAuthorizedAction)
+  it('throws AuthorizationError when the current user cannot be resolved', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const isAuthorized = vi.fn(async () => false)
+      i.bind(IdentityContext, () => ({
+        isAuthorized,
+        getCurrentUser: () => Promise.reject(new Error(':(')),
+        isAuthenticated: () => Promise.resolve(false),
+      }))
+      const exampleAction = vi.fn(async () => EmptyResult())
+      const authorized = Authorize('Role1')(exampleAction)
 
       await expect(() => authorized({ injector: i, request, response })).rejects.toThrow(AuthorizationError)
-      expect(exampleAuthorizedAction).not.toBeCalled()
+      expect(exampleAction).not.toHaveBeenCalled()
     })
   })
 
-  it('Should return 403 if the current user does not have the role', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const isAuthorizedAction = vi.fn(async () => false)
-      i.setExplicitInstance(
-        {
-          isAuthorized: isAuthorizedAction,
-          getCurrentUser: async () => Promise.resolve<User>({ username: 'a', roles: ['Role1'] }),
-        },
-        IdentityContext,
-      )
-      const exampleAuthorizedAction = vi.fn(async () => EmptyResult())
-      const authorized = Authorize('Role2')(exampleAuthorizedAction)
+  it('throws AuthorizationError when the current user does not have the required role', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const isAuthorized = vi.fn(async () => false)
+      i.bind(IdentityContext, () => ({
+        isAuthorized,
+        getCurrentUser: <TUser extends User>() =>
+          Promise.resolve({ username: 'a', roles: ['Role1'] } as unknown as TUser),
+        isAuthenticated: () => Promise.resolve(true),
+      }))
+      const exampleAction = vi.fn(async () => EmptyResult())
+      const authorized = Authorize('Role2')(exampleAction)
 
       await expect(() => authorized({ injector: i, request, response })).rejects.toThrow(AuthorizationError)
-      expect(exampleAuthorizedAction).not.toBeCalled()
+      expect(exampleAction).not.toHaveBeenCalled()
     })
   })
 
-  it('Should exec the original action if authorized', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const isAuthorizedAction = vi.fn(async () => true)
-      i.setExplicitInstance(
-        {
-          isAuthorized: isAuthorizedAction,
-          getCurrentUser: async () => Promise.resolve<User>({ username: 'a', roles: ['Role1'] }),
-        },
-        IdentityContext,
-      )
-      const exampleAuthorizedAction = vi.fn(async () => EmptyResult())
-      const authorized = Authorize('Role1')(exampleAuthorizedAction)
-      const params = { injector: i, body: undefined, query: undefined, request, response }
+  it('invokes the wrapped action when the current user holds the required role', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      i.bind(IdentityContext, () => ({
+        isAuthorized: () => Promise.resolve(true),
+        getCurrentUser: <TUser extends User>() =>
+          Promise.resolve({ username: 'a', roles: ['Role1'] } as unknown as TUser),
+        isAuthenticated: () => Promise.resolve(true),
+      }))
+      const exampleAction = vi.fn(async () => EmptyResult())
+      const authorized = Authorize('Role1')(exampleAction)
+      const params = { injector: i, request, response }
       const result = await authorized(params)
       expect(result.statusCode).toBe(200)
       expect(result.chunk).toBe(undefined)
-      expect(exampleAuthorizedAction).toBeCalledWith(params)
+      expect(exampleAction).toHaveBeenCalledWith(params)
     })
   })
 })

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[]) =>