@pikku/core 0.9.3 → 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,5 +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.
@@ -41,3 +46,179 @@ export const verifyPermissions = async (
   }
   return false
 }
+
+/**
+ * Adds global permissions for a specific tag.
+ *
+ * This function allows you to register permissions that will be applied to
+ * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
+ *
+ * @param {string} tag - The tag that the permissions should apply to.
+ * @param {any[]} permissions - The permissions array to apply for the specified tag.
+ *
+ * @throws {Error} If permissions for the tag already exist.
+ *
+ * @example
+ * ```typescript
+ * // Add admin permissions for admin endpoints
+ * addPermission('admin', [adminPermission])
+ *
+ * // Add authentication permissions for auth endpoints
+ * addPermission('auth', [authPermission])
+ *
+ * // Add read permissions for all API endpoints
+ * addPermission('api', [readPermission])
+ * ```
+ */
+export const addPermission = (
+  tag: string,
+  permissions: CorePermissionGroup | CorePikkuPermission[]
+) => {
+  const permissionsStore = pikkuState('misc', 'permissions')
+
+  // Check if tag already exists
+  if (permissionsStore[tag]) {
+    throw new Error(
+      `Permissions for tag '${tag}' already exist. Use a different tag or remove the existing permissions first.`
+    )
+  }
+
+  permissionsStore[tag] = permissions
+}
+
+/**
+ * Retrieves permissions for a given set of tags.
+ *
+ * This function looks up all permissions registered for any of the provided tags
+ * and returns them as a flattened array.
+ *
+ * @param {string[]} tags - Array of tags to look up permissions for.
+ * @returns {any[]} Array of permission functions that apply to the given tags.
+ *
+ * @example
+ * ```typescript
+ * // Get all permissions for tags 'api' and 'auth'
+ * const permissions = getPermissionsForTags(['api', 'auth'])
+ * ```
+ */
+export const getPermissionsForTags = (
+  tags?: string[]
+): Array<CorePermissionGroup | CorePikkuPermission> => {
+  if (!tags || tags.length === 0) {
+    return []
+  }
+
+  const permissionsStore = pikkuState('misc', 'permissions')
+  const applicablePermissions: Array<
+    CorePermissionGroup | CorePikkuPermission
+  > = []
+
+  // Collect permissions for all matching tags
+  for (const tag of new Set(tags)) {
+    const tagPermissions = permissionsStore[tag]
+    if (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,
@@ -67,6 +71,8 @@ interface PikkuState {
   misc: {
     errors: Map<PikkuError, ErrorDetails>
     schemas: Map<string, any>
+    middleware: Record<string, CorePikkuMiddleware[]>
+    permissions: Record<string, CorePermissionGroup | CorePikkuPermission[]>
   }
 }
 
@@ -107,7 +113,9 @@ export const resetPikkuState = () => {
     },
     misc: {
       errors: globalThis.pikkuState?.misc?.errors || new Map(),
-      schemas: globalThis.pikkuState?.misc?.schema || new Map(),
+      schemas: new Map(),
+      middleware: {},
+      permissions: {},
     },
   } as PikkuState
 }