@pikku/core 0.9.12-next.0 → 0.10.0

package/src/function/function-runner.test.ts

@@ -21,11 +21,16 @@ const addTestFunction = (funcName: string, funcConfig: any) => {
   const middleware = funcConfig.tags
     ? funcConfig.tags.map((tag: string) => ({ type: 'tag' as const, tag }))
     : undefined
+  // Convert tags to permissions metadata
+  const permissions = funcConfig.tags
+    ? funcConfig.tags.map((tag: string) => ({ type: 'tag' as const, tag }))
+    : undefined
   pikkuState('function', 'meta')[funcName] = {
     pikkuFuncName: funcName,
     inputSchemaName: null,
     outputSchemaName: null,
     middleware,
+    permissions,
   }
 }
 
@@ -143,7 +148,7 @@ describe('runPikkuFunc - Integration Tests', () => {
         singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
         data: () => ({}),
-        permissions: wiringPermissions,
+        wirePermissions: wiringPermissions,
         tags: ['wiringTag'],
         auth: false,
         interaction: {},
@@ -199,7 +204,7 @@ describe('runPikkuFunc - Integration Tests', () => {
         singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
         data: () => ({}),
-        permissions: wiringPermissions,
+        wirePermissions: wiringPermissions,
         auth: false,
         interaction: {},
       }),
@@ -411,7 +416,7 @@ describe('runPikkuFunc - Integration Tests', () => {
         getAllServices: () => mockServices,
         data: () => ({}),
         wireMiddleware: [wiringMiddleware],
-        permissions: wiringPermissions,
+        wirePermissions: wiringPermissions,
         auth: false,
         interaction: {},
       }

package/src/function/function-runner.ts

@@ -10,10 +10,12 @@ import {
   CoreSingletonServices,
   PikkuInteraction,
   MiddlewareMetadata,
+  PermissionMetadata,
 } from '../types/core.types.js'
 import {
   CorePermissionGroup,
   CorePikkuFunctionConfig,
+  CorePikkuPermission,
 } from './functions.types.js'
 import { UserSessionService } from '../services/user-session-service.js'
 import { ForbiddenError } from '../errors/errors.js'
@@ -48,9 +50,10 @@ export const runPikkuFunc = async <In = any, Out = any>(
     data,
     userSession,
     auth: wiringAuth,
-    permissions: wiringPermissions,
     inheritedMiddleware,
     wireMiddleware,
+    inheritedPermissions,
+    wirePermissions,
     coerceDataFromSchema,
     tags = [],
     interaction,
@@ -62,9 +65,10 @@ export const runPikkuFunc = async <In = any, Out = any>(
     userSession?: UserSessionService<CoreUserSession>
     data: () => Promise<In> | In
     auth?: boolean
-    permissions?: CorePermissionGroup
     inheritedMiddleware?: MiddlewareMetadata[]
     wireMiddleware?: CorePikkuMiddleware[]
+    inheritedPermissions?: PermissionMetadata[]
+    wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
     coerceDataFromSchema?: boolean
     tags?: string[]
     interaction: PikkuInteraction
@@ -79,6 +83,12 @@ export const runPikkuFunc = async <In = any, Out = any>(
     throw new Error(`Function meta not found: ${funcName}`)
   }
 
+  // Convert tags to PermissionMetadata and merge with inheritedPermissions
+  const mergedInheritedPermissions: PermissionMetadata[] = [
+    ...(inheritedPermissions || []),
+    ...(tags?.map((tag) => ({ type: 'tag' as const, tag })) || []),
+  ]
+
   // Helper function to run permissions and execute the function
   const executeFunction = async () => {
     const session = userSession?.get()
@@ -115,15 +125,18 @@ export const runPikkuFunc = async <In = any, Out = any>(
     }
 
     const allServices = await getAllServices(session)
+
+    // Run permissions check with combined permissions: inheritedPermissions (including tags) → wirePermissions → funcPermissions
     await runPermissions(wireType, wireId, {
-      wiringTags: tags,
-      wiringPermissions,
-      funcTags: funcConfig.tags,
+      wireInheritedPermissions: mergedInheritedPermissions,
+      wirePermissions: wirePermissions,
+      funcInheritedPermissions: funcMeta.permissions,
       funcPermissions: funcConfig.permissions,
       allServices,
       data: actualData,
       session,
     })
+
     return await funcConfig.func(allServices, actualData, session!)
   }
 

package/src/function/functions.types.ts

@@ -12,6 +12,7 @@ import type {
  *
  * @template In - The input type.
  * @template Out - The output type.
+ * @template ChannelData - The channel data type.
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Session - The session type, defaults to `CoreUserSession`.
  */
@@ -39,6 +40,7 @@ export type CorePikkuFunction<
  *
  * @template In - The input type.
  * @template Out - The output type.
+ * @template ChannelData - The channel data type.
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Session - The session type, defaults to `CoreUserSession`.
  */
@@ -74,17 +76,98 @@ export type CorePikkuPermission<
   Session extends CoreUserSession = CoreUserSession,
 > = (services: Services, data: In, session?: Session) => Promise<boolean>
 
+/**
+ * Configuration object for creating a permission with metadata
+ *
+ * @template In - The input type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CorePikkuPermissionConfig<
+  In = any,
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = {
+  /** The permission function */
+  func: CorePikkuPermission<In, Services, Session>
+  /** Optional human-readable name for the permission */
+  name?: string
+  /** Optional description of what the permission checks */
+  description?: string
+}
+
 /**
  * Factory function for creating permissions with tree-shaking support
+ * Supports both direct function and configuration object syntax
+ *
+ * @example
+ * ```typescript
+ * // Direct function syntax
+ * export const adminPermission = pikkuPermission(
+ *   async ({ logger }, data, session) => {
+ *     return session?.role === 'admin'
+ *   }
+ * )
+ *
+ * // Configuration object syntax with metadata
+ * export const adminPermission = pikkuPermission({
+ *   name: 'Admin Permission',
+ *   description: 'Checks if user has admin role',
+ *   func: async ({ logger }, data, session) => {
+ *     return session?.role === 'admin'
+ *   }
+ * })
+ * ```
  */
 export const pikkuPermission = <
   In = any,
   Services extends CoreSingletonServices = CoreServices,
   Session extends CoreUserSession = CoreUserSession,
 >(
-  permission: CorePikkuPermission<In, Services, Session>
+  permission:
+    | CorePikkuPermission<In, Services, Session>
+    | CorePikkuPermissionConfig<In, Services, Session>
 ): CorePikkuPermission<In, Services, Session> => {
-  return permission
+  return typeof permission === 'function' ? permission : permission.func
+}
+
+/**
+ * A factory function that takes input and returns a permission
+ * Used when permissions need configuration/input parameters
+ *
+ * @template In - The input type for the factory.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CorePikkuPermissionFactory<
+  In = any,
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = (input: In) => CorePikkuPermission<any, Services, Session>
+
+/**
+ * Factory function for creating permission factories
+ * Use this when your permission needs configuration/input parameters
+ *
+ * @example
+ * ```typescript
+ * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
+ *   role
+ * }) => {
+ *   return pikkuPermission(async ({ logger }, data, session) => {
+ *     if (!session || session.role !== role) {
+ *       logger.warn(`Permission denied: required role '${role}'`)
+ *       return false
+ *     }
+ *     return true
+ *   })
+ * })
+ * ```
+ */
+export const pikkuPermissionFactory = <In = any>(
+  factory: CorePikkuPermissionFactory<In>
+): CorePikkuPermissionFactory<In> => {
+  return factory
 }
 
 export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =

package/src/index.ts

@@ -24,27 +24,7 @@ export * from './time-utils.js'
 export { pikkuState } from './pikku-state.js'
 export {
   runMiddleware,
-  registerMiddleware,
-  getMiddlewareByName,
   addMiddleware,
+  getMiddlewareByName,
 } from './middleware-runner.js'
 export { addPermission } from './permissions.js'
-export { wireHTTP, addHTTPMiddleware } from './wirings/http/http-runner.js'
-export { wireChannel } from './wirings/channel/channel-runner.js'
-export { wireScheduler } from './wirings/scheduler/scheduler-runner.js'
-export { wireQueueWorker } from './wirings/queue/queue-runner.js'
-export {
-  wireMCPResource,
-  wireMCPTool,
-  wireMCPPrompt,
-  runMCPResource,
-  runMCPTool,
-  runMCPPrompt,
-  getMCPTools,
-  getMCPResources,
-  getMCPPrompts,
-  getMCPResourcesMeta,
-  getMCPToolsMeta,
-  getMCPPromptsMeta,
-} from './wirings/mcp/mcp-runner.js'
-export { wireCLI, runCLICommand } from './wirings/cli/cli-runner.js'

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
-}
+  )
+)