@pikku/core 0.6.13 → 0.6.15

package/src/middleware/auth-api-key.ts

@@ -0,0 +1,32 @@
+import { PikkuMiddleware } from '../types/core.types.js'
+
+/**
+ * API key middleware that retrieves a session from the 'x-api-key' header using a provided callback.
+ *
+ * @param options.getSessionForAPIKey - A function that returns a session when provided an API key.
+ */
+export const apiKeyMiddleware = (
+  options: { getSessionForAPIKey?: (apiKey: string) => Promise<any> } = {}
+) => {
+  const middleware: PikkuMiddleware = async (
+    { userSessionService },
+    { http },
+    next
+  ) => {
+    if (!http?.request || userSessionService.get()) {
+      return next()
+    }
+
+    if (options.getSessionForAPIKey) {
+      const apiKey = http.request.getHeader('x-api-key')
+      if (apiKey) {
+        const userSession = await options.getSessionForAPIKey(apiKey)
+        if (userSession) {
+          await userSessionService.set(userSession)
+        }
+      }
+    }
+    return next()
+  }
+  return middleware
+}

package/src/middleware/auth-cookie-middleware.ts

@@ -0,0 +1,54 @@
+import { PikkuMiddleware } from '../types/core.types.js'
+
+/**
+ * Cookie middleware that extracts a session from cookies.
+ *
+ * @param options.cookieNames - List of cookie names to check.
+ * @param options.getSessionForCookieValue - Function to retrieve a session using a cookie value.
+ */
+export const cookieMiddleware = (
+  options: {
+    cookieNames?: string[]
+    getSessionForCookieValue?: (
+      cookieValue: string,
+      cookieName: string
+    ) => Promise<any>
+  } = {}
+): PikkuMiddleware => {
+  const middleware: PikkuMiddleware = async (
+    { userSessionService },
+    { http },
+    next
+  ) => {
+    if (!http?.request || userSessionService.get()) {
+      return next()
+    }
+
+    if (options.getSessionForCookieValue && options.cookieNames) {
+      const cookies = http.request.getCookies()
+      if (cookies) {
+        let cookieName: string | undefined
+        for (const name of options.cookieNames) {
+          if (cookies[name]) {
+            cookieName = name
+            break
+          }
+        }
+        if (cookieName) {
+          const cookieValue = cookies[cookieName]
+          if (cookieValue) {
+            const userSession = await options.getSessionForCookieValue(
+              cookieValue,
+              cookieName
+            )
+            if (userSession) {
+              await userSessionService.set(userSession)
+            }
+          }
+        }
+      }
+    }
+    return next()
+  }
+  return middleware
+}

package/src/middleware/auth-jwt-middleware.ts

@@ -0,0 +1,47 @@
+import { InvalidSessionError } from '../errors/errors.js'
+import { PikkuMiddleware } from '../types/core.types.js'
+
+/**
+ * JWT middleware that extracts the Bearer token from the Authorization header,
+ * decodes it via the jwtService, and sets the session if found.
+ *
+ * @param options.debugJWTDecode - Optional flag for debugging the JWT decode process.
+ */
+export const jwtMiddleware = (
+  options: { debugJWTDecode?: boolean } = {}
+): PikkuMiddleware => {
+  const middleware: PikkuMiddleware = async (
+    { jwt, userSessionService },
+    { http },
+    next
+  ) => {
+    if (!jwt) {
+      throw new Error('JWT service not found')
+    }
+
+    // Skip if session already exists.
+    if (!http?.request || userSessionService.get()) {
+      return next()
+    }
+
+    const authHeader =
+      http.request.getHeader('authorization') ||
+      http.request.getHeader('Authorization')
+    if (authHeader) {
+      const [scheme, token] = authHeader.split(' ')
+      if (scheme !== 'Bearer' || !token) {
+        throw new InvalidSessionError()
+      }
+      const userSession = await jwt.decode<any>(
+        token,
+        undefined,
+        options.debugJWTDecode
+      )
+      if (userSession) {
+        await userSessionService.set(userSession)
+      }
+    }
+    return next()
+  }
+  return middleware
+}

package/src/middleware/auth-query-middleware.ts

@@ -0,0 +1,33 @@
+import { PikkuQuery } from '../http/http-routes.types.js'
+import { PikkuMiddleware } from '../types/core.types.js'
+
+/**
+ * Query middleware that retrieves a session using query parameters.
+ *
+ * @param options.getSessionForQueryValue - A function that returns a session based on query parameters.
+ */
+export const queryMiddleware = (
+  options: {
+    getSessionForQueryValue?: (query: PikkuQuery) => Promise<any>
+  } = {}
+): PikkuMiddleware => {
+  const middleware: PikkuMiddleware = async (
+    { userSessionService },
+    { http },
+    next
+  ) => {
+    if (!http?.request || userSessionService.get()) {
+      return next()
+    }
+
+    if (options.getSessionForQueryValue) {
+      const query = http.request.getQuery()
+      const userSession = await options.getSessionForQueryValue(query)
+      if (userSession) {
+        await userSessionService.set(userSession)
+      }
+    }
+    return next()
+  }
+  return middleware
+}

package/src/middleware/index.ts

@@ -0,0 +1,4 @@
+export * from './auth-api-key.js'
+export * from './auth-cookie-middleware.js'
+export * from './auth-jwt-middleware.js'
+export * from './auth-query-middleware.js'

package/src/middleware-runner.ts

@@ -0,0 +1,43 @@
+import { UserSessionService } from './services/user-session-service.js'
+import {
+  CoreSingletonServices,
+  PikkuInteraction,
+  PikkuMiddleware,
+} from './types/core.types.js'
+
+/**
+ * Runs a chain of middleware functions in sequence before executing the main function.
+ *
+ * @param services - An object containing services (e.g., singletonServices, userSessionService, etc.)
+ * @param interaction - The interaction context, e.g., { http }.
+ * @param middlewares - An array of middleware functions to run.
+ * @param main - The main function to execute after all middleware have run.
+ * @returns A promise resolving to the result of the main function.
+ *
+ * @example
+ * runMiddleware(
+ *   { ...services, userSessionService },
+ *   { http },
+ *   [middleware1, middleware2, middleware3],
+ *   async () => { return await runMain(); }
+ * );
+ */
+export const runMiddleware = async (
+  services: CoreSingletonServices & {
+    userSessionService: UserSessionService<any>
+  },
+  interaction: PikkuInteraction,
+  middlewares: PikkuMiddleware[],
+  main?: () => Promise<void>
+): Promise<void> => {
+  const dispatch = async (index: number): Promise<any> => {
+    if (middlewares && index < middlewares.length) {
+      await middlewares[index]!(services, interaction, () =>
+        dispatch(index + 1)
+      )
+    } else if (main) {
+      return await main()
+    }
+  }
+  await dispatch(0)
+}

package/src/scheduler/scheduler.types.ts

@@ -10,6 +10,7 @@ export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> =
     schedule: string
     session?: UserSession
     docs?: APIDocs
+    tags?: string[]
   }>
 
 /**
@@ -24,4 +25,5 @@ export type CoreScheduledTask<
   func: APIFunction
   docs?: APIDocs
   session?: UserSession
+  tags?: string[]
 }

package/src/schema.ts

@@ -98,12 +98,11 @@ export const coerceQueryStringToArray = (schemaName: string, data: any) => {
   }
 }
 
-export const validateAndCoerce = (
+export const validateSchema = async (
   logger: Logger,
   schemaService: SchemaService | undefined,
   schemaName: string | undefined | null,
-  data: any,
-  coerceToArray: boolean
+  data: any
 ) => {
   if (schemaService) {
     if (!schemaName) {
@@ -115,10 +114,7 @@ export const validateAndCoerce = (
       }
     }
     const schema = getSchema(schemaName)
-    schemaService.compileSchema(schemaName, schema)
-    if (coerceToArray) {
-      coerceQueryStringToArray(schemaName, data)
-    }
-    schemaService.validateSchema(schemaName, data)
+    await schemaService.compileSchema(schemaName, schema)
+    await schemaService.validateSchema(schemaName, data)
   }
 }

package/src/services/index.ts

@@ -10,6 +10,7 @@ export * from './logger-console.js'
 export * from './secret-service.js'
 export * from './variables-service.js'
 export * from './schema-service.js'
+export * from './user-session-service.js'
 
 // Local implementations
 export * from './local-secrets.js'

package/src/services/user-session-service.ts

@@ -1,7 +1,49 @@
+import { ChannelStore } from '../channel/channel-store.js'
 import { CoreUserSession } from '../types/core.types.js'
 
 export interface UserSessionService<UserSession extends CoreUserSession> {
-  setSession: (session: UserSession) => Promise<void> | void
-  deleteSession: () => Promise<void> | void
-  getSession: () => Promise<UserSession | void> | UserSession | void
+  set(session: UserSession): Promise<void> | void
+  clear(): Promise<void> | void
+  get(): Promise<UserSession | undefined> | UserSession | undefined
+}
+
+export class LocalUserSessionService<UserSession extends CoreUserSession>
+  implements UserSessionService<UserSession>
+{
+  constructor(private session: UserSession | undefined = undefined) {}
+
+  public set(session: UserSession) {
+    this.session = session
+  }
+
+  public clear() {
+    this.session = undefined
+  }
+
+  public get(): UserSession | undefined {
+    return this.session
+  }
+}
+
+export class RemoteUserSessionService<UserSession extends CoreUserSession>
+  implements UserSessionService<UserSession>
+{
+  constructor(
+    private channelStore: ChannelStore<unknown, unknown, UserSession>,
+    private channelId: string,
+    public session: UserSession | undefined = undefined
+  ) {}
+
+  public async set(session: UserSession) {
+    await this.channelStore.setUserSession(this.channelId, session)
+  }
+
+  public async clear() {
+    await this.channelStore.setUserSession(this.channelId, undefined)
+  }
+
+  public async get(): Promise<UserSession | undefined> {
+    const channel = await this.channelStore.getChannel(this.channelId)
+    return channel.userSession
+  }
 }

package/src/types/core.types.ts

@@ -1,10 +1,8 @@
 import type { Logger, LogLevel } from '../services/logger.js'
-import type { HTTPSessionService } from '../http/http-session-service.js'
 import { VariablesService } from '../services/variables-service.js'
 import { EventHubService } from '../channel/eventhub-service.js'
 import { SchemaService } from '../services/schema-service.js'
-import { enforceChannelAccess } from '../channel/channel.types.js'
-import { enforceHTTPAccess, PikkuHTTP } from '../http/http-routes.types.js'
+import { PikkuHTTP } from '../http/http-routes.types.js'
 import { UserSessionService } from '../services/user-session-service.js'
 import { JWTService } from '../services/jwt-service.js'
 import { SecretService } from '../services/secret-service.js'
@@ -51,8 +49,6 @@ export type RequireAtLeastOne<T> = {
 export type CoreConfig<Config extends Record<string, unknown> = {}> = {
   /** The log level for the application. */
   logLevel?: LogLevel
-  /** The maximum compute time allowed, in milliseconds (optional). */
-  maximumComputeTime?: number
   /** Secrets used by the application (optional). */
   secrets?: {}
 } & Config
@@ -69,14 +65,8 @@ export interface CoreSingletonServices<
   Config extends CoreConfig = CoreConfig,
   UserSession extends CoreUserSession = CoreUserSession,
 > {
-  /** The http permission service used for authorization (optional). */
-  enforceHTTPAccess?: enforceHTTPAccess
-  /** The channel permission service used by the application (optional). */
-  enforceChannelAccess?: enforceChannelAccess
   /** JWT Service */
   jwt?: JWTService<UserSession>
-  /** The session service used by the application (optional). */
-  httpSessionService?: HTTPSessionService
   /** The schema library used to validate data */
   schemaService?: SchemaService
   /** The core configuration for the application. */
@@ -94,10 +84,24 @@ export interface CoreSingletonServices<
 /**
  * Represents different forms of interaction within Pikku and the outside world.
  */
-export interface PikkuInteractions {
+export interface PikkuInteraction {
   http?: PikkuHTTP
 }
 
+/**
+ * A function that can wrap an interaction and be called before or after
+ */
+export type PikkuMiddleware<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = (
+  services: SingletonServices & {
+    userSessionService: UserSessionService<UserSession>
+  },
+  interactions: PikkuInteraction,
+  next: () => Promise<void>
+) => Promise<void>
+
 /**
  * Represents the core services used by Pikku, including singleton services and the request/response interaction.
  */
@@ -106,17 +110,14 @@ export type CoreServices<
   UserSession extends CoreUserSession = CoreUserSession,
   CoreServices extends Record<string, unknown> = {},
 > = SingletonServices &
-  PikkuInteractions & {
+  PikkuInteraction & {
     userSession?: UserSessionService<UserSession>
   } & CoreServices
 
 export type SessionServices<
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   Services = CoreServices<SingletonServices>,
-> = Omit<
-  Services,
-  keyof SingletonServices | keyof PikkuInteractions | 'session'
->
+> = Omit<Services, keyof SingletonServices | keyof PikkuInteraction | 'session'>
 
 /**
  * Defines a function type for creating singleton services from the given configuration.
@@ -139,7 +140,7 @@ export type CreateSessionServices<
   UserSession extends CoreUserSession = CoreUserSession,
 > = (
   services: SingletonServices,
-  interaction: PikkuInteractions,
+  interaction: PikkuInteraction,
   session: UserSession | undefined
 ) => Promise<SessionServices<Services, SingletonServices>>
 

package/src/types/functions.types.ts

@@ -1,4 +1,8 @@
-import type { CoreServices, CoreUserSession } from './core.types.js'
+import type {
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+} from './core.types.js'
 
 /**
  * Represents a core API function that performs an operation using core services and a user session.
@@ -11,8 +15,8 @@ import type { CoreServices, CoreUserSession } from './core.types.js'
 export type CoreAPIFunction<
   In,
   Out,
-  Services = CoreServices,
-  Session = CoreUserSession,
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
 > = (services: Services, data: In, session: Session) => Promise<Out>
 
 /**
@@ -26,8 +30,8 @@ export type CoreAPIFunction<
 export type CoreAPIFunctionSessionless<
   In,
   Out,
-  Services = CoreServices,
-  Session = CoreUserSession,
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
 > = (services: Services, data: In, session?: Session) => Promise<Out>
 
 /**
@@ -39,6 +43,6 @@ export type CoreAPIFunctionSessionless<
  */
 export type CoreAPIPermission<
   In = any,
-  Services = CoreServices,
-  Session = CoreUserSession,
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
 > = (services: Services, data: In, session?: Session) => Promise<boolean>