@pikku/core 0.9.4 → 0.9.5

package/src/permissions.test.ts

@@ -1,58 +1,419 @@
-import { test, describe } from 'node:test'
-import assert from 'assert'
-import { getErrorResponse, addError } from './errors/error-handler.js'
+import { describe, test, beforeEach } from 'node:test'
+import * as assert from 'node:assert'
 import {
-  ForbiddenError,
-  BadRequestError,
-  NotFoundError,
-} from './errors/errors.js'
-
-describe('getErrorResponse', () => {
-  test('should return the correct error response for BadRequestError', () => {
-    const error = new BadRequestError()
-    const response = getErrorResponse(error)
-    assert.deepStrictEqual(response, {
-      status: 400,
-      message:
-        'The server cannot or will not process the request due to client error (e.g., malformed request syntax).',
+  addPermission,
+  getPermissionsForTags,
+  runPermissions,
+} from './permissions.js'
+import { resetPikkuState } from './pikku-state.js'
+import { CoreServices, CoreUserSession } from './types/core.types.js'
+import { CorePermissionGroup } from './function/functions.types.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+const mockServices: CoreServices = {
+  logger: {
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+  },
+} as any
+
+const mockSession: CoreUserSession = {
+  userId: 'test-user',
+} as any
+
+describe('addPermission', () => {
+  test('should add single permission for a tag', () => {
+    const mockPermission = async () => true
+
+    addPermission('testTag', [mockPermission])
+
+    const permissions = getPermissionsForTags(['testTag'])
+    assert.equal(permissions.length, 1)
+    assert.equal(permissions[0], mockPermission)
+  })
+
+  test('should add multiple permissions for a tag', () => {
+    const mockPermission1 = async () => true
+    const mockPermission2 = async () => false
+
+    addPermission('multiTestTag', [mockPermission1, mockPermission2])
+
+    const permissions = getPermissionsForTags(['multiTestTag'])
+    assert.equal(permissions.length, 2)
+    assert.equal(permissions[0], mockPermission1)
+    assert.equal(permissions[1], mockPermission2)
+  })
+
+  test('should add permission group object for a tag', () => {
+    const mockPermissionGroup: CorePermissionGroup = {
+      permissions: [async () => true, async () => false],
+    }
+
+    addPermission('groupTestTag', mockPermissionGroup)
+
+    const permissions = getPermissionsForTags(['groupTestTag'])
+    assert.equal(permissions.length, 1)
+    assert.equal(permissions[0], mockPermissionGroup)
+  })
+
+  test('should throw error when tag already exists', () => {
+    const mockPermission = async () => true
+
+    addPermission('duplicateTag', [mockPermission])
+
+    assert.throws(
+      () => {
+        addPermission('duplicateTag', [mockPermission])
+      },
+      {
+        message:
+          "Permissions for tag 'duplicateTag' already exist. Use a different tag or remove the existing permissions first.",
+      }
+    )
+  })
+})
+
+describe('getPermissionsForTags', () => {
+  test('should return empty array when no tags provided', () => {
+    const permissions = getPermissionsForTags([])
+    assert.deepEqual(permissions, [])
+  })
+
+  test('should return empty array when tags is undefined', () => {
+    const permissions = getPermissionsForTags(undefined)
+    assert.deepEqual(permissions, [])
+  })
+
+  test('should return permissions for single tag', () => {
+    const mockPermission = async () => true
+    addPermission('singleTestTag', [mockPermission])
+
+    const permissions = getPermissionsForTags(['singleTestTag'])
+    assert.equal(permissions.length, 1)
+    assert.equal(permissions[0], mockPermission)
+  })
+
+  test('should return permissions for multiple tags', () => {
+    const mockPermission1 = async () => true
+    const mockPermission2 = async () => false
+
+    addPermission('tag1', [mockPermission1])
+    addPermission('tag2', [mockPermission2])
+
+    const permissions = getPermissionsForTags(['tag1', 'tag2'])
+    assert.equal(permissions.length, 2)
+    assert.equal(permissions[0], mockPermission1)
+    assert.equal(permissions[1], mockPermission2)
+  })
+
+  test('should handle array permissions correctly', () => {
+    const mockPermission1 = async () => true
+    const mockPermission2 = async () => false
+
+    addPermission('arrayHandleTestTag', [mockPermission1, mockPermission2])
+
+    const permissions = getPermissionsForTags(['arrayHandleTestTag'])
+    assert.equal(permissions.length, 2)
+    assert.equal(permissions[0], mockPermission1)
+    assert.equal(permissions[1], mockPermission2)
+  })
+
+  test('should handle non-array permissions correctly', () => {
+    const mockPermissionGroup: CorePermissionGroup = {
+      permissions: [async () => true],
+    }
+
+    addPermission('objectHandleTestTag', mockPermissionGroup)
+
+    const permissions = getPermissionsForTags(['objectHandleTestTag'])
+    assert.equal(permissions.length, 1)
+    assert.equal(permissions[0], mockPermissionGroup)
+  })
+
+  test('should deduplicate tags', () => {
+    const mockPermission = async () => true
+    addPermission('dedupeTestTag', [mockPermission])
+
+    const permissions = getPermissionsForTags([
+      'dedupeTestTag',
+      'dedupeTestTag',
+    ])
+    assert.equal(permissions.length, 1)
+    assert.equal(permissions[0], mockPermission)
+  })
+
+  test('should ignore non-existent tags', () => {
+    const mockPermission = async () => true
+    addPermission('existingTag', [mockPermission])
+
+    const permissions = getPermissionsForTags(['existingTag', 'nonExistentTag'])
+    assert.equal(permissions.length, 1)
+    assert.equal(permissions[0], mockPermission)
+  })
+})
+
+describe('runPermissions', () => {
+  test('should pass when no permissions are defined', async () => {
+    // Should not throw
+    await runPermissions({
+      allServices: mockServices,
+      data: {},
+      session: mockSession,
     })
   })
 
-  test('should return the correct error response for NotFoundError', () => {
-    const error = new NotFoundError()
-    const response = getErrorResponse(error)
-    assert.deepStrictEqual(response, {
-      status: 404,
-      message: 'The server cannot find the requested resource.',
+  test('should execute wiring tag permissions first', async () => {
+    const executionOrder: string[] = []
+    const wiringTagPermission = async () => {
+      executionOrder.push('wiringTag')
+      return true
+    }
+
+    addPermission('wiringTag', [wiringTagPermission])
+
+    await runPermissions({
+      wiringTags: ['wiringTag'],
+      allServices: mockServices,
+      data: {},
+      session: mockSession,
+    })
+
+    assert.deepEqual(executionOrder, ['wiringTag'])
+  })
+
+  test('should execute all permission levels in correct order', async () => {
+    const executionOrder: string[] = []
+
+    const wiringTagPermission = async () => {
+      executionOrder.push('wiringTag')
+      return true
+    }
+    const funcTagPermission = async () => {
+      executionOrder.push('funcTag')
+      return true
+    }
+
+    addPermission('wiringTag', [wiringTagPermission])
+    addPermission('funcTag', [funcTagPermission])
+
+    const wiringPermissions: CorePermissionGroup = {
+      permissions: [
+        async () => {
+          executionOrder.push('wiringPermission')
+          return true
+        },
+      ],
+    }
+
+    const funcPermissions: CorePermissionGroup = {
+      permissions: [
+        async () => {
+          executionOrder.push('funcPermission')
+          return true
+        },
+      ],
+    }
+
+    await runPermissions({
+      wiringTags: ['wiringTag'],
+      wiringPermissions,
+      funcTags: ['funcTag'],
+      funcPermissions,
+      allServices: mockServices,
+      data: {},
+      session: mockSession,
     })
+
+    // Order: wiringTags → wiringPermissions → funcTags → funcPermissions
+    assert.deepEqual(executionOrder, [
+      'wiringTag',
+      'wiringPermission',
+      'funcTag',
+      'funcPermission',
+    ])
   })
 
-  test('should return the correct error response for ForbiddenError', () => {
-    const error = new ForbiddenError()
-    const response = getErrorResponse(error)
-    assert.deepStrictEqual(response, {
-      status: 403,
-      message:
-        'The client does not have permission to access the requested resource.',
+  test('should implement "at least one must pass" logic for tag permissions', async () => {
+    const failingPermission = async () => false
+    const passingPermission = async () => true
+
+    addPermission('atLeastOneTestTag', [failingPermission, passingPermission])
+
+    // Should not throw because at least one permission passes
+    await runPermissions({
+      wiringTags: ['atLeastOneTestTag'],
+      allServices: mockServices,
+      data: {},
+      session: mockSession,
     })
   })
 
-  test('should return undefined for an unknown error', () => {
-    class UnknownError extends Error {}
-    const error = new UnknownError()
-    const response = getErrorResponse(error)
-    assert.strictEqual(response, undefined)
+  test('should throw error when all wiring tag permissions fail', async () => {
+    const failingPermission1 = async () => false
+    const failingPermission2 = async () => false
+
+    addPermission('allFailTestTag', [failingPermission1, failingPermission2])
+
+    await assert.rejects(
+      runPermissions({
+        wiringTags: ['allFailTestTag'],
+        allServices: mockServices,
+        data: {},
+        session: mockSession,
+      }),
+      {
+        message: 'Permission denied - wiring tag permissions',
+      }
+    )
+  })
+
+  test('should throw error when wiring permissions fail', async () => {
+    const wiringPermissions: CorePermissionGroup = {
+      permissions: [async () => false],
+    }
+
+    await assert.rejects(
+      runPermissions({
+        wiringPermissions,
+        allServices: mockServices,
+        data: {},
+        session: mockSession,
+      }),
+      {
+        message: 'Permission denied - wiring permissions',
+      }
+    )
+  })
+
+  test('should throw error when all function tag permissions fail', async () => {
+    const failingPermission = async () => false
+
+    addPermission('funcTag', [failingPermission])
+
+    await assert.rejects(
+      runPermissions({
+        funcTags: ['funcTag'],
+        allServices: mockServices,
+        data: {},
+        session: mockSession,
+      }),
+      {
+        message: 'Permission denied - function tag permissions',
+      }
+    )
   })
 
-  test('should return the correct error response for a custom error added to apiErrors', () => {
-    class CustomError extends Error {}
-    const customError = new CustomError()
-    const customErrorDetails = { status: 400, message: 'Custom Error' }
+  test('should throw error when function permissions fail', async () => {
+    const funcPermissions: CorePermissionGroup = {
+      permissions: [async () => false],
+    }
 
-    // Add the custom error to the apiErrors map
-    addError(CustomError, customErrorDetails)
+    await assert.rejects(
+      runPermissions({
+        funcPermissions,
+        allServices: mockServices,
+        data: {},
+        session: mockSession,
+      }),
+      {
+        message: 'Permission denied - function permissions',
+      }
+    )
+  })
+
+  test('should stop execution at first failing level', async () => {
+    const executionOrder: string[] = []
+
+    const failingWiringTagPermission = async () => {
+      executionOrder.push('wiringTag')
+      return false
+    }
+
+    addPermission('failingWiringTag', [failingWiringTagPermission])
+
+    const wiringPermissions: CorePermissionGroup = {
+      permissions: [
+        async () => {
+          executionOrder.push('wiringPermission')
+          return true
+        },
+      ],
+    }
+
+    await assert.rejects(
+      runPermissions({
+        wiringTags: ['failingWiringTag'],
+        wiringPermissions,
+        allServices: mockServices,
+        data: {},
+        session: mockSession,
+      })
+    )
+
+    // Should only execute wiring tag permissions, not wiring permissions
+    assert.deepEqual(executionOrder, ['wiringTag'])
+  })
+
+  test('should handle array permissions in tag-based permissions', async () => {
+    const arrayPermission = [async () => true, async () => false]
+
+    addPermission('arrayTestTag', arrayPermission)
+
+    // Should not throw because verifyPermissions handles array properly
+    await runPermissions({
+      wiringTags: ['arrayTestTag'],
+      allServices: mockServices,
+      data: {},
+      session: mockSession,
+    })
+  })
+
+  test('should handle permission group objects in tag-based permissions', async () => {
+    const permissionGroup: CorePermissionGroup = {
+      permissions: [async () => true],
+    }
+
+    addPermission('objectTestTag', permissionGroup)
+
+    // Should not throw because verifyPermissions handles objects properly
+    await runPermissions({
+      wiringTags: ['objectTestTag'],
+      allServices: mockServices,
+      data: {},
+      session: mockSession,
+    })
+  })
+
+  test('should pass correct parameters to permission functions', async () => {
+    let receivedServices: any
+    let receivedData: any
+    let receivedSession: any
+
+    const testPermission = async (services: any, data: any, session: any) => {
+      receivedServices = services
+      receivedData = data
+      receivedSession = session
+      return true
+    }
+
+    const testData = { test: 'data' }
+
+    addPermission('paramTestTag', [testPermission])
+
+    await runPermissions({
+      wiringTags: ['paramTestTag'],
+      allServices: mockServices,
+      data: testData,
+      session: mockSession,
+    })
 
-    const response = getErrorResponse(customError)
-    assert.deepStrictEqual(response, customErrorDetails)
+    assert.equal(receivedServices, mockServices)
+    assert.equal(receivedData, testData)
+    assert.equal(receivedSession, mockSession)
   })
 })

package/src/permissions.ts

@@ -1,6 +1,10 @@
 import { CoreServices, CoreUserSession } from './types/core.types.js'
-import { CorePermissionGroup } from './function/functions.types.js'
+import {
+  CorePermissionGroup,
+  CorePikkuPermission,
+} from './function/functions.types.js'
 import { pikkuState } from './pikku-state.js'
+import { ForbiddenError } from './errors/errors.js'
 
 /**
  * This function validates permissions by iterating over permission groups and executing the corresponding permission functions. If all functions in at least one group return true, the permission is considered valid.
@@ -66,7 +70,10 @@ export const verifyPermissions = async (
  * addPermission('api', [readPermission])
  * ```
  */
-export const addPermission = (tag: string, permissions: any[]) => {
+export const addPermission = (
+  tag: string,
+  permissions: CorePermissionGroup | CorePikkuPermission[]
+) => {
   const permissionsStore = pikkuState('misc', 'permissions')
 
   // Check if tag already exists
@@ -94,21 +101,124 @@ export const addPermission = (tag: string, permissions: any[]) => {
  * const permissions = getPermissionsForTags(['api', 'auth'])
  * ```
  */
-export const getPermissionsForTags = (tags?: string[]): any[] => {
+export const getPermissionsForTags = (
+  tags?: string[]
+): Array<CorePermissionGroup | CorePikkuPermission> => {
   if (!tags || tags.length === 0) {
     return []
   }
 
   const permissionsStore = pikkuState('misc', 'permissions')
-  const applicablePermissions: any[] = []
+  const applicablePermissions: Array<
+    CorePermissionGroup | CorePikkuPermission
+  > = []
 
   // Collect permissions for all matching tags
   for (const tag of new Set(tags)) {
     const tagPermissions = permissionsStore[tag]
     if (tagPermissions) {
-      applicablePermissions.push(...tagPermissions)
+      if (Array.isArray(tagPermissions)) {
+        applicablePermissions.push(...tagPermissions)
+      } else {
+        applicablePermissions.push(tagPermissions)
+      }
     }
   }
 
   return applicablePermissions
 }
+
+/**
+ * Runs permission checks in the specified order:
+ * 1) wiring tag permissions - at least one must pass if any exist
+ * 2) wiring permissions - must pass if defined
+ * 3) function tag permissions - at least one must pass if any exist
+ * 4) function permissions - must pass if defined
+ */
+export const runPermissions = async ({
+  wiringTags,
+  wiringPermissions,
+  funcTags,
+  funcPermissions,
+  allServices,
+  data,
+  session,
+}: {
+  wiringTags?: string[]
+  wiringPermissions?: CorePermissionGroup
+  funcTags?: string[]
+  funcPermissions?: CorePermissionGroup
+  allServices: CoreServices
+  data: any
+  session?: CoreUserSession
+}) => {
+  let permissioned = true
+
+  // 1. Wiring tag permissions - at least one must pass if any exist
+  const wiringTaggedPermissions = getPermissionsForTags(wiringTags || [])
+  if (wiringTaggedPermissions.length > 0) {
+    permissioned = false // Start false, need at least one to pass
+    for (const permissions of wiringTaggedPermissions) {
+      const result = await verifyPermissions(
+        typeof permissions === 'function' ? { permissions } : permissions,
+        allServices,
+        data,
+        session
+      )
+      if (result) {
+        permissioned = true
+        break // At least one passed, we're good at this level
+      }
+    }
+    if (!permissioned) {
+      throw new ForbiddenError('Permission denied - wiring tag permissions')
+    }
+  }
+
+  // 2. Wiring permissions - must pass if defined
+  if (wiringPermissions) {
+    permissioned = await verifyPermissions(
+      wiringPermissions,
+      allServices,
+      data,
+      session
+    )
+    if (!permissioned) {
+      throw new ForbiddenError('Permission denied - wiring permissions')
+    }
+  }
+
+  // 3. Function tag permissions - at least one must pass if any exist
+  const funcTaggedPermissions = getPermissionsForTags(funcTags || [])
+  if (funcTaggedPermissions.length > 0) {
+    permissioned = false // Start false, need at least one to pass
+    for (const permissions of funcTaggedPermissions) {
+      const result = await verifyPermissions(
+        typeof permissions === 'function' ? { permissions } : permissions,
+        allServices,
+        data,
+        session
+      )
+      if (result) {
+        permissioned = true
+        break // At least one passed, we're good at this level
+      }
+    }
+    if (!permissioned) {
+      throw new ForbiddenError('Permission denied - function tag permissions')
+    }
+  }
+
+  // 4. Function permissions - must pass if defined
+  if (funcPermissions) {
+    permissioned = await verifyPermissions(
+      funcPermissions,
+      allServices,
+      data,
+      session
+    )
+    if (!permissioned) {
+      throw new ForbiddenError('Permission denied - function permissions')
+    }
+  }
+}

package/src/pikku-state.ts

@@ -10,7 +10,11 @@ import {
   ScheduledTasksMeta,
 } from './wirings/scheduler/scheduler.types.js'
 import { ErrorDetails, PikkuError } from './errors/error-handler.js'
-import { CorePikkuFunctionConfig } from './function/functions.types.js'
+import {
+  CorePermissionGroup,
+  CorePikkuFunctionConfig,
+  CorePikkuPermission,
+} from './function/functions.types.js'
 import {
   queueWorkersMeta,
   CoreQueueWorker,
@@ -68,7 +72,7 @@ interface PikkuState {
     errors: Map<PikkuError, ErrorDetails>
     schemas: Map<string, any>
     middleware: Record<string, CorePikkuMiddleware[]>
-    permissions: Record<string, any[]>
+    permissions: Record<string, CorePermissionGroup | CorePikkuPermission[]>
   }
 }
 
@@ -109,9 +113,9 @@ export const resetPikkuState = () => {
     },
     misc: {
       errors: globalThis.pikkuState?.misc?.errors || new Map(),
-      schemas: globalThis.pikkuState?.misc?.schema || new Map(),
-      middleware: globalThis.pikkuState?.misc?.middleware || {},
-      permissions: globalThis.pikkuState?.misc?.permissions || {},
+      schemas: new Map(),
+      middleware: {},
+      permissions: {},
     },
   } as PikkuState
 }

package/src/types/core.types.ts

@@ -114,14 +114,13 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
 /**
  * Represents different forms of interaction within Pikku and the outside world.
  */
-export type PikkuInteraction = Partial<{
-  http: PikkuHTTP
+export type PikkuInteraction<In = unknown, Out = unknown> = Partial<{
+  http: PikkuHTTP<In>
   mcp: PikkuMCP
   rpc: PikkuRPC
-  channel: PikkuChannel<unknown, unknown>
+  channel: PikkuChannel<unknown, Out>
   scheduledTask: PikkuScheduledTask
   queue: PikkuQueue
-  s
 }>
 
 /**

package/src/wirings/channel/local/local-channel-runner.ts

@@ -10,10 +10,7 @@ import {
 import { PikkuLocalChannelHandler } from './local-channel-handler.js'
 import { SessionServices } from '../../../types/core.types.js'
 import { handleHTTPError } from '../../../handle-error.js'
-import {
-  addMiddlewareForTags,
-  runMiddleware,
-} from '../../../middleware-runner.js'
+import { combineMiddleware, runMiddleware } from '../../../middleware-runner.js'
 import { PikkuUserSessionService } from '../../../services/user-session-service.js'
 import { PikkuHTTP } from '../../http/http.types.js'
 import { runPikkuFuncDirectly } from '../../../function/function-runner.js'
@@ -149,7 +146,10 @@ export const runLocalChannel = async ({
       userSession,
     },
     { http },
-    addMiddlewareForTags(channelConfig.middleware, channelConfig.tags),
+    combineMiddleware({
+      wiringMiddleware: channelConfig.middleware,
+      wiringTags: channelConfig.tags,
+    }),
     main
   )