@pikku/core 0.9.11 → 0.10.0

package/src/middleware/auth-apikey.ts

@@ -1,66 +1,51 @@
-import {
-  CoreConfig,
-  CoreSingletonServices,
-  CoreUserSession,
-  CorePikkuMiddleware,
-} from '../types/core.types.js'
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 
 /**
- * API key middleware that retrieves a session from the 'x-api-key' header using a provided callback.
+ * API key middleware that retrieves a session from the 'x-api-key' header using JWT decoding.
  *
- * @param options.getSessionForAPIKey - A function that returns a session when provided an API key.
+ * Extracts API key from either the 'x-api-key' header or 'apiKey' query parameter
+ * and decodes it using the JWT service.
+ *
+ * @param options.source - Where to look for the API key: 'header', 'query', or 'all'
+ *
+ * @example
+ * ```typescript
+ * import { authAPIKey } from '@pikku/core/middleware'
+ *
+ * addHTTPMiddleware([
+ *   authAPIKey({ source: 'header' })
+ * ])
+ * ```
  */
-export const authAPIKey = <
-  SingletonServices extends CoreSingletonServices<CoreConfig>,
-  UserSession extends CoreUserSession,
->({
-  source,
-  getSessionForAPIKey,
-  jwt,
-}: {
+export const authAPIKey = pikkuMiddlewareFactory<{
   source: 'header' | 'query' | 'all'
-} & (
-  | {
-      getSessionForAPIKey?: undefined
-      jwt?: true
-    }
-  | {
-      getSessionForAPIKey: (
-        services: SingletonServices,
-        apiKey: string
-      ) => Promise<any>
-      jwt?: false
-    }
-)) => {
-  const middleware: CorePikkuMiddleware = async (services, { http }, next) => {
-    const { userSession: userSessionService, jwt: jwtService } = services as any
-    if (!http?.request || userSessionService.get()) {
-      return next()
-    }
+}>(({ source }) =>
+  pikkuMiddleware(
+    async (
+      { userSession: userSessionService, jwt: jwtService },
+      { http },
+      next
+    ) => {
+      if (!http?.request || userSessionService.get()) {
+        return next()
+      }
 
-    let apiKey: string | null = null
-    if (source === 'header' || source === 'all') {
-      apiKey = http.request.header('x-api-key') as string | null
-    }
-    if (!apiKey && (source === 'query' || source === 'all')) {
-      apiKey = http.request.query().apiKey as string | null
-    }
-    if (apiKey) {
-      let userSession: UserSession | null = null
-      if (jwt) {
-        if (!jwtService) {
-          throw new Error('JWT service is required for JWT decoding.')
-        }
-        userSession = await jwtService.decode(apiKey)
-      } else {
-        userSession = await getSessionForAPIKey!(services as any, apiKey)
+      let apiKey: string | null = null
+      if (source === 'header' || source === 'all') {
+        apiKey = http.request.header('x-api-key') as string | null
       }
-      if (userSession) {
-        userSessionService.setInitial(userSession)
+      if (!apiKey && (source === 'query' || source === 'all')) {
+        apiKey = http.request.query().apiKey as string | null
+      }
+
+      if (apiKey && jwtService) {
+        const userSession = await jwtService.decode(apiKey)
+        if (userSession) {
+          userSessionService.setInitial(userSession)
+        }
       }
-    }
-    return next()
-  }
 
-  return middleware
-}
+      return next()
+    }
+  )
+)

package/src/middleware/auth-bearer.ts

@@ -1,66 +1,83 @@
 import { InvalidSessionError } from '../errors/errors.js'
 import {
-  CoreConfig,
-  CoreSingletonServices,
   CoreUserSession,
-  CorePikkuMiddleware,
+  pikkuMiddleware,
+  pikkuMiddlewareFactory,
 } from '../types/core.types.js'
 
 /**
- * Extracts the Bearer token from the Authorization header
+ * Bearer token middleware that extracts and validates tokens from the Authorization header.
+ *
+ * Supports two modes:
+ * - JWT decoding (default): Decodes bearer tokens using the JWT service
+ * - Static token: Provide a `token` object with a value and userSession for simple token validation
+ *
+ * @param options.token - Optional static token configuration { value: string, userSession: CoreUserSession }
+ *
+ * @example
+ * ```typescript
+ * import { authBearer } from '@pikku/core/middleware'
+ *
+ * // JWT mode (default)
+ * addHTTPMiddleware('*', [
+ *   authBearer()
+ * ])
+ *
+ * // Static token mode
+ * addHTTPMiddleware('*', [
+ *   authBearer({
+ *     token: {
+ *       value: process.env.API_TOKEN,
+ *       userSession: { userId: 'system', role: 'admin' }
+ *     }
+ *   })
+ * ])
+ * ```
  */
-export const authBearer = <
-  SingletonServices extends CoreSingletonServices<CoreConfig>,
-  UserSession extends CoreUserSession,
->({
-  token,
-  jwt,
-  getSession,
-}: {
+export const authBearer = pikkuMiddlewareFactory<{
   token?: {
     value: string
-    userSession: UserSession
+    userSession: CoreUserSession
   }
-  jwt?: boolean
-  getSession?: (
-    services: SingletonServices,
-    token: string
-  ) => Promise<UserSession> | UserSession
-} = {}): CorePikkuMiddleware => {
-  const middleware: CorePikkuMiddleware = async (services, { http }, next) => {
-    const { userSession: userSessionService, jwt: jwtService } = services as any
-    // Skip if session already exists.
-    if (!http?.request || userSessionService.get()) {
-      return next()
-    }
-
-    const authHeader =
-      http.request.header('authorization') ||
-      http.request.header('Authorization')
-    if (authHeader) {
-      const [scheme, bearerToken] = authHeader.split(' ')
-      if (scheme !== 'Bearer' || !token || !bearerToken) {
-        throw new InvalidSessionError()
+}>(({ token } = {}) =>
+  pikkuMiddleware(
+    async (
+      { userSession: userSessionService, jwt: jwtService },
+      { http },
+      next
+    ) => {
+      // Skip if session already exists.
+      if (!http?.request || userSessionService.get()) {
+        return next()
       }
-      let userSession: UserSession | null = null
-      if (jwt) {
-        if (!jwtService) {
-          throw new Error('JWT service is required for JWT decoding.')
+
+      const authHeader =
+        http.request.header('authorization') ||
+        http.request.header('Authorization')
+
+      if (authHeader) {
+        const [scheme, bearerToken] = authHeader.split(' ')
+        if (scheme !== 'Bearer' || !bearerToken) {
+          throw new InvalidSessionError()
         }
-        userSession = await jwtService.decode(bearerToken)
-      } else if (token) {
-        if (bearerToken === token.value) {
+
+        let userSession: CoreUserSession | null = null
+
+        // If static token provided, validate against it
+        if (token && bearerToken === token.value) {
           userSession = token.userSession
         }
-      } else if (getSession) {
-        userSession = await getSession(services as any, token)
-      }
+        // Otherwise, default to JWT decoding
+        else if (jwtService && !token) {
+          userSession = await jwtService.decode(bearerToken)
+        }
 
-      if (userSession) {
-        userSessionService.setInitial(userSession)
+        if (userSession) {
+          userSessionService.setInitial(userSession)
+        }
       }
+
+      return next()
     }
-    return next()
-  }
-  return middleware
-}
+  )
+)

package/src/middleware/auth-cookie.ts

@@ -1,103 +1,84 @@
 import { SerializeOptions } from 'cookie'
-import {
-  CoreConfig,
-  CoreSingletonServices,
-  CoreUserSession,
-  CorePikkuMiddleware,
-} from '../types/core.types.js'
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 import {
   getRelativeTimeOffsetFromNow,
   RelativeTimeInput,
 } from '../time-utils.js'
 
 /**
- * Cookie middleware that extracts a session from cookies.
+ * Cookie-based session middleware that uses JWT for encoding/decoding session data.
+ *
+ * Reads session from a cookie on incoming requests and automatically updates the cookie
+ * when the session changes (e.g., after login).
+ *
+ * @param options.name - Cookie name
+ * @param options.expiresIn - Cookie expiration time (e.g., { value: 30, unit: 'day' })
+ * @param options.options - Cookie serialization options (httpOnly, secure, sameSite, etc.)
  *
- * @param options.name - List of cookie names to check.
- * @param options.getSessionForCookieValue - Function to retrieve a session using a cookie value.
+ * @example
+ * ```typescript
+ * import { authCookie } from '@pikku/core/middleware'
+ *
+ * addHTTPMiddleware([
+ *   authCookie({
+ *     name: 'session',
+ *     expiresIn: { value: 30, unit: 'day' },
+ *     options: {
+ *       httpOnly: true,
+ *       secure: true,
+ *       sameSite: 'strict',
+ *       path: '/'
+ *     }
+ *   })
+ * ])
+ * ```
  */
-export const authCookie = <
-  SingletonServices extends CoreSingletonServices<CoreConfig>,
-  UserSession extends CoreUserSession,
->({
-  name,
-  getSessionForCookieValue,
-  jwt,
-  options,
-  expiresIn,
-}: {
+export const authCookie = pikkuMiddlewareFactory<{
   name: string
   options: SerializeOptions
   expiresIn: RelativeTimeInput
-} & (
-  | {
-      getSessionForCookieValue: (
-        services: SingletonServices,
-        cookieValue: string,
-        cookieName: string
-      ) => Promise<UserSession>
-      jwt?: false
-    }
-  | {
-      getSessionForCookieValue?: undefined
-      jwt: true
-    }
-)): CorePikkuMiddleware => {
-  const middleware: CorePikkuMiddleware = async (services, { http }, next) => {
-    const {
-      userSession: userSessionService,
-      jwt: jwtService,
-      logger,
-    } = services as any
-    if (!http?.request || userSessionService.get()) {
-      return next()
-    }
+}>(({ name, options, expiresIn }) =>
+  pikkuMiddleware(
+    async (
+      { userSession: userSessionService, jwt: jwtService, logger },
+      { http },
+      next
+    ) => {
+      if (!http?.request || userSessionService.get()) {
+        return next()
+      }
 
-    let userSession: UserSession | null = null
-    const cookieValue = http.request.cookie(name)
-    if (cookieValue) {
-      if (jwt) {
-        if (!jwtService) {
-          throw new Error('JWT service is required for JWT decoding.')
+      // Try to decode session from cookie
+      const cookieValue = http.request.cookie(name)
+      if (cookieValue && jwtService) {
+        const userSession = await jwtService.decode(cookieValue)
+        if (userSession) {
+          userSessionService.setInitial(userSession)
         }
-        userSession = await jwtService.decode(cookieValue)
-      } else if (getSessionForCookieValue) {
-        userSession = await getSessionForCookieValue(
-          services as any,
-          cookieValue,
-          name
-        )
       }
-    }
 
-    if (userSession) {
-      userSessionService.setInitial(userSession)
-    }
-    await next()
+      await next()
 
-    // Set the cookie in the response if the session has changed
-    if (!http?.response) {
-      return
-    }
+      // Set the cookie in the response if the session has changed
+      if (!http?.response) {
+        return
+      }
 
-    if (userSessionService.sessionChanged) {
-      const session = userSessionService.get()
-      if (jwt) {
-        if (!jwtService) {
-          throw new Error('JWT service is required for JWT encoding.')
+      if (userSessionService.sessionChanged) {
+        const session = userSessionService.get()
+        if (jwtService) {
+          http.response.cookie(
+            name,
+            await jwtService.encode(expiresIn, session),
+            {
+              ...options,
+              expires: getRelativeTimeOffsetFromNow(expiresIn),
+            }
+          )
+        } else {
+          logger.warn('No JWT service available, unable to set cookie')
         }
-        http.response.cookie(
-          name,
-          await jwtService.encode(expiresIn, session),
-          {
-            ...options,
-            expires: getRelativeTimeOffsetFromNow(expiresIn),
-          }
-        )
-      } else {
-        logger.warn('No JWT service available, unable to set cookie')
       }
     }
-  }
-  return middleware
-}
+  )
+)

package/src/middleware/timeout.ts

@@ -1,17 +1,13 @@
 import { RequestTimeoutError } from '../errors/errors.js'
-import { CorePikkuMiddleware } from '../types/core.types.js'
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 
-export const timeout = (timeout: number) => {
-  const middleware: CorePikkuMiddleware = async (
-    _services,
-    _interaction,
-    next
-  ) => {
-    setTimeout(() => {
-      throw new RequestTimeoutError()
-    }, timeout)
+export const timeout = () =>
+  pikkuMiddlewareFactory<{ timeout: number }>(({ timeout }) =>
+    pikkuMiddleware(async (_services, _interaction, next) => {
+      setTimeout(() => {
+        throw new RequestTimeoutError()
+      }, timeout)
 
-    await next()
-  }
-  return middleware
-}
+      await next()
+    })
+  )

package/src/middleware-runner.test.ts

@@ -55,7 +55,7 @@ describe('combineMiddleware', () => {
       PikkuWiringTypes.http,
       Math.random().toString(),
       {
-        wiringMiddleware: [mockMiddleware1, mockMiddleware2],
+        wireMiddleware: [mockMiddleware1, mockMiddleware2],
       }
     )
 
@@ -93,7 +93,7 @@ describe('combineMiddleware', () => {
     assert.equal(result[1], mockMiddleware2)
   })
 
-  test('should execute middleware in correct order: wiringTags → wiringMiddleware → funcMiddleware → funcTags', () => {
+  test('should execute middleware in correct order: wireInheritedMiddleware (tags) → wireMiddleware → funcInheritedMiddleware (tags) → funcMiddleware', () => {
     // Setup tagged middleware
     const wiringTagMiddleware: CorePikkuMiddleware = async (
       services,
@@ -132,19 +132,19 @@ describe('combineMiddleware', () => {
       PikkuWiringTypes.http,
       Math.random().toString(),
       {
-        wiringMiddleware: [wiringMiddleware],
-        wiringTags: ['wiringTag'],
+        wireInheritedMiddleware: [{ type: 'tag', tag: 'wiringTag' }],
+        wireMiddleware: [wiringMiddleware],
+        funcInheritedMiddleware: [{ type: 'tag', tag: 'funcTag' }],
         funcMiddleware: [funcMiddleware],
-        funcTags: ['funcTag'],
       }
     )
 
     assert.equal(result.length, 4)
-    // Order: wiringTags, wiringMiddleware, funcMiddleware, funcTags
-    assert.equal(result[0], wiringTagMiddleware) // wiringTags first
-    assert.equal(result[1], wiringMiddleware) // wiringMiddleware second
-    assert.equal(result[2], funcMiddleware) // funcMiddleware third
-    assert.equal(result[3], funcTagMiddleware) // funcTags last
+    // Order: wireInheritedMiddleware (tags), wireMiddleware, funcInheritedMiddleware (tags), funcMiddleware
+    assert.equal(result[0], wiringTagMiddleware) // wireInheritedMiddleware tags first
+    assert.equal(result[1], wiringMiddleware) // wireMiddleware second
+    assert.equal(result[2], funcTagMiddleware) // funcInheritedMiddleware tags third
+    assert.equal(result[3], funcMiddleware) // funcMiddleware last
   })
 
   test('should handle wiring tags only', () => {
@@ -162,7 +162,7 @@ describe('combineMiddleware', () => {
       PikkuWiringTypes.http,
       Math.random().toString(),
       {
-        wiringTags: ['testTag'],
+        wireInheritedMiddleware: [{ type: 'tag', tag: 'testTag' }],
       }
     )
 
@@ -185,7 +185,7 @@ describe('combineMiddleware', () => {
       PikkuWiringTypes.http,
       Math.random().toString(),
       {
-        funcTags: ['funcTestTag'],
+        funcInheritedMiddleware: [{ type: 'tag', tag: 'funcTestTag' }],
       }
     )
 
@@ -216,7 +216,10 @@ describe('combineMiddleware', () => {
       PikkuWiringTypes.http,
       Math.random().toString(),
       {
-        wiringTags: ['tag1', 'tag2'],
+        wireInheritedMiddleware: [
+          { type: 'tag', tag: 'tag1' },
+          { type: 'tag', tag: 'tag2' },
+        ],
       }
     )
 
@@ -240,8 +243,13 @@ describe('combineMiddleware', () => {
       PikkuWiringTypes.http,
       Math.random().toString(),
       {
-        wiringTags: ['existingTag', 'nonExistentTag'],
-        funcTags: ['anotherNonExistentTag'],
+        wireInheritedMiddleware: [
+          { type: 'tag', tag: 'existingTag' },
+          { type: 'tag', tag: 'nonExistentTag' },
+        ],
+        funcInheritedMiddleware: [
+          { type: 'tag', tag: 'anotherNonExistentTag' },
+        ],
       }
     )
 
@@ -276,7 +284,7 @@ describe('runMiddleware', () => {
       {} as any,
       {} as any,
       combineMiddleware(PikkuWiringTypes.rpc, Math.random().toString(), {
-        wiringMiddleware: [middleware1, middleware2, middleware1, middleware2],
+        wireMiddleware: [middleware1, middleware2, middleware1, middleware2],
       }),
       async () => {
         executionOrder.push('main')