@pikku/core 0.9.4 → 0.9.6

package/src/permissions.test.ts

@@ -1,58 +1,423 @@
-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,
+  PikkuWiringTypes,
+} 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(PikkuWiringTypes.rpc, Math.random().toString(), {
+      allServices: mockServices,
+      data: {},
+      session: mockSession,
+    })
+  })
+
+  test('should execute wiring tag permissions first', async () => {
+    const executionOrder: string[] = []
+    const wiringTagPermission = async () => {
+      executionOrder.push('wiringTag')
+      return true
+    }
+
+    addPermission('wiringTag', [wiringTagPermission])
+
+    await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
+      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(PikkuWiringTypes.rpc, Math.random().toString(), {
+      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 NotFoundError', () => {
-    const error = new NotFoundError()
-    const response = getErrorResponse(error)
-    assert.deepStrictEqual(response, {
-      status: 404,
-      message: 'The server cannot find 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(PikkuWiringTypes.rpc, Math.random().toString(), {
+      wiringTags: ['atLeastOneTestTag'],
+      allServices: mockServices,
+      data: {},
+      session: mockSession,
     })
   })
 
-  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 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(PikkuWiringTypes.rpc, Math.random().toString(), {
+        wiringTags: ['allFailTestTag'],
+        allServices: mockServices,
+        data: {},
+        session: mockSession,
+      }),
+      {
+        message: 'Permission denied',
+      }
+    )
+  })
+
+  test('should throw error when wiring permissions fail', async () => {
+    const wiringPermissions: CorePermissionGroup = {
+      permissions: [async () => false],
+    }
+
+    await assert.rejects(
+      runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
+        wiringPermissions,
+        allServices: mockServices,
+        data: {},
+        session: mockSession,
+      }),
+      {
+        message: 'Permission denied',
+      }
+    )
+  })
+
+  test('should throw error when all function tag permissions fail', async () => {
+    const failingPermission = async () => false
+
+    addPermission('funcTag', [failingPermission])
+
+    await assert.rejects(
+      runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
+        funcTags: ['funcTag'],
+        allServices: mockServices,
+        data: {},
+        session: mockSession,
+      }),
+      {
+        message: 'Permission denied',
+      }
+    )
+  })
+
+  test('should throw error when function permissions fail', async () => {
+    const funcPermissions: CorePermissionGroup = {
+      permissions: [async () => false],
+    }
+
+    await assert.rejects(
+      runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
+        funcPermissions,
+        allServices: mockServices,
+        data: {},
+        session: mockSession,
+      }),
+      {
+        message: 'Permission denied',
+      }
+    )
+  })
+
+  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(PikkuWiringTypes.rpc, Math.random().toString(), {
+        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(PikkuWiringTypes.rpc, Math.random().toString(), {
+      wiringTags: ['arrayTestTag'],
+      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 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(PikkuWiringTypes.rpc, Math.random().toString(), {
+      wiringTags: ['objectTestTag'],
+      allServices: mockServices,
+      data: {},
+      session: mockSession,
+    })
   })
 
-  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 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
+    }
 
-    // Add the custom error to the apiErrors map
-    addError(CustomError, customErrorDetails)
+    const testData = { test: 'data' }
+
+    addPermission('paramTestTag', [testPermission])
+
+    await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
+      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,14 @@
-import { CoreServices, CoreUserSession } from './types/core.types.js'
-import { CorePermissionGroup } from './function/functions.types.js'
+import {
+  CoreServices,
+  CoreUserSession,
+  PikkuWiringTypes,
+} from './types/core.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 +74,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
@@ -79,6 +90,8 @@ export const addPermission = (tag: string, permissions: any[]) => {
   permissionsStore[tag] = permissions
 }
 
+const EMPTY: readonly (CorePermissionGroup | CorePikkuPermission)[] = []
+
 /**
  * Retrieves permissions for a given set of tags.
  *
@@ -94,21 +107,160 @@ export const addPermission = (tag: string, permissions: any[]) => {
  * const permissions = getPermissionsForTags(['api', 'auth'])
  * ```
  */
-export const getPermissionsForTags = (tags?: string[]): any[] => {
+export const getPermissionsForTags = (
+  tags?: string[]
+): readonly (CorePermissionGroup | CorePikkuPermission)[] => {
   if (!tags || tags.length === 0) {
-    return []
+    return EMPTY
   }
 
   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
 }
+
+const permissionCache: Record<
+  PikkuWiringTypes,
+  Partial<
+    Record<
+      string,
+      {
+        wiringTags: readonly (CorePermissionGroup | CorePikkuPermission)[]
+        funcTags: readonly (CorePermissionGroup | CorePikkuPermission)[]
+      }
+    >
+  >
+> = {
+  [PikkuWiringTypes.http]: {},
+  [PikkuWiringTypes.rpc]: {},
+  [PikkuWiringTypes.channel]: {},
+  [PikkuWiringTypes.queue]: {},
+  [PikkuWiringTypes.scheduler]: {},
+  [PikkuWiringTypes.mcp]: {},
+}
+
+/**
+ * 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 (
+  wireType: PikkuWiringTypes,
+  uid: string,
+  {
+    wiringTags,
+    wiringPermissions,
+    funcTags,
+    funcPermissions,
+    allServices,
+    data,
+    session,
+  }: {
+    wiringTags?: string[]
+    wiringPermissions?: CorePermissionGroup
+    funcTags?: string[]
+    funcPermissions?: CorePermissionGroup
+    allServices: CoreServices
+    data: any
+    session?: CoreUserSession
+  }
+) => {
+  let cachedPermission = permissionCache[wireType][uid]
+  if (!cachedPermission) {
+    cachedPermission = {
+      wiringTags: getPermissionsForTags(wiringTags),
+      funcTags: getPermissionsForTags(funcTags),
+    }
+    permissionCache[wireType][uid] = cachedPermission
+  }
+  let permissioned = true
+
+  // 1. Wiring tag permissions - at least one must pass if any exist
+  const wiringTaggedPermissions = cachedPermission.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) {
+      allServices.logger.debug('Permission denied - wiring tag permissions')
+      throw new ForbiddenError('Permission denied')
+    }
+  }
+
+  // 2. Wiring permissions - must pass if defined
+  if (wiringPermissions) {
+    permissioned = await verifyPermissions(
+      wiringPermissions,
+      allServices,
+      data,
+      session
+    )
+    if (!permissioned) {
+      allServices.logger.debug('Permission denied - wiring permissions')
+      throw new ForbiddenError('Permission denied')
+    }
+  }
+
+  // 3. Function tag permissions - at least one must pass if any exist
+  const funcTaggedPermissions = cachedPermission.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) {
+      allServices.logger.debug('Permission denied - function tag permissions')
+      throw new ForbiddenError('Permission denied')
+    }
+  }
+
+  // 4. Function permissions - must pass if defined
+  if (funcPermissions) {
+    permissioned = await verifyPermissions(
+      funcPermissions,
+      allServices,
+      data,
+      session
+    )
+    if (!permissioned) {
+      allServices.logger.debug('Permission denied - function permissions')
+      throw new ForbiddenError('Permission denied')
+    }
+  }
+}