@pikku/core 0.12.62 → 0.12.64

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

@@ -6,12 +6,12 @@ import {
   getFunctionNames,
   runPikkuFunc,
 } from './function-runner.js'
-import { addTagMiddleware, addTagPermission } from '../index.js'
+import { addGlobalPermission, addTagMiddleware } from '../index.js'
 import { resetPikkuState, pikkuState } from '../pikku-state.js'
 import type { CoreServices, CorePikkuMiddleware } from '../types/core.types.js'
 import type { CorePermissionGroup } from './functions.types.js'
 import { PikkuSessionService } from '../services/user-session-service.js'
-import { ReadonlySessionError } from '../errors/errors.js'
+import { MissingScopeError, ReadonlySessionError } from '../errors/errors.js'
 import { createInvocationAudit } from '../services/audit-service.js'
 
 beforeEach(() => {
@@ -21,21 +21,17 @@ beforeEach(() => {
 // Helper function to add function with metadata for tests
 const addTestFunction = (funcName: string, funcConfig: any) => {
   addFunction(funcName, funcConfig)
-  // Convert tags to middleware metadata
+  // Convert tags to middleware metadata (tags are organizational only; they no
+  // longer carry permissions in the session+function authorization model).
   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(null, 'function', 'meta')[funcName] = {
     pikkuFuncId: funcName,
     inputSchemaName: null,
     outputSchemaName: null,
     sessionless: true,
     middleware,
-    permissions,
   }
 }
 
@@ -101,31 +97,16 @@ describe('runPikkuFunc - Integration Tests', () => {
     ])
   })
 
-  test('should execute permissions in correct order: wiringTags → wiringPermissions → funcTags → funcPermissions', async () => {
+  test('runs global (AND) then function (OR) permissions before the handler', async () => {
     const executionOrder: string[] = []
 
-    // Setup tagged permissions
-    const wiringTagPermission = async () => {
-      executionOrder.push('wiringTag')
-      return true
-    }
-    const funcTagPermission = async () => {
-      executionOrder.push('funcTag')
-      return true
-    }
-
-    addTagPermission('wiringTag', [wiringTagPermission])
-    addTagPermission('funcTag', [funcTagPermission])
+    addGlobalPermission([
+      async () => {
+        executionOrder.push('globalPermission')
+        return true
+      },
+    ])
 
-    // Setup direct permissions
-    const wiringPermissions: CorePermissionGroup = {
-      permissions: [
-        async () => {
-          executionOrder.push('wiringPermission')
-          return true
-        },
-      ],
-    }
     const funcPermissions: CorePermissionGroup = {
       permissions: [
         async () => {
@@ -135,14 +116,12 @@ describe('runPikkuFunc - Integration Tests', () => {
       ],
     }
 
-    // Register function with permissions and tags
     addTestFunction('testFunc', {
       func: async () => {
         executionOrder.push('main')
         return 'success'
       },
       permissions: funcPermissions,
-      tags: ['funcTag'],
     })
 
     const result = await runPikkuFunc(
@@ -153,49 +132,33 @@ describe('runPikkuFunc - Integration Tests', () => {
         singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
         data: () => ({}),
-        wirePermissions: wiringPermissions,
-        tags: ['wiringTag'],
         auth: false,
         wire: {},
       }
     )
 
     assert.equal(result, 'success')
-    // Order: wiringTags → main (short-circuit on first passing group)
-    assert.deepEqual(executionOrder, ['wiringTag', 'main'])
-  })
-
-  test('should throw specific error for wiring tag permission failures', async () => {
-    const failingWiringTagPermission = async () => false
-
-    addTagPermission('wiringTag', [failingWiringTagPermission])
-
-    addTestFunction('testFunc', {
-      func: async () => 'success',
-    })
-
-    await assert.rejects(
-      runPikkuFunc('rpc', Math.random().toString(), 'testFunc', {
-        singletonServices: mockSingletonServices,
-        getAllServices: () => mockServices,
-        data: () => ({}),
-        tags: ['wiringTag'],
-        auth: false,
-        wire: {},
-      }),
-      {
-        message: 'Permission denied',
-      }
-    )
+    assert.deepEqual(executionOrder, [
+      'globalPermission',
+      'funcPermission',
+      'main',
+    ])
   })
 
-  test('should throw specific error for wiring permission failures', async () => {
-    const wiringPermissions: CorePermissionGroup = {
-      permissions: [async () => false],
-    }
+  test('a failing global permission denies before the function permission runs', async () => {
+    let funcPermissionRan = false
+    addGlobalPermission([async () => false])
 
     addTestFunction('testFunc', {
       func: async () => 'success',
+      permissions: {
+        allow: [
+          async () => {
+            funcPermissionRan = true
+            return true
+          },
+        ],
+      },
     })
 
     await assert.rejects(
@@ -203,7 +166,6 @@ describe('runPikkuFunc - Integration Tests', () => {
         singletonServices: mockSingletonServices,
         getAllServices: () => mockServices,
         data: () => ({}),
-        wirePermissions: wiringPermissions,
         auth: false,
         wire: {},
       }),
@@ -211,16 +173,15 @@ describe('runPikkuFunc - Integration Tests', () => {
         message: 'Permission denied',
       }
     )
+    assert.equal(funcPermissionRan, false)
   })
 
-  test('should throw specific error for function tag permission failures', async () => {
-    const failingFuncTagPermission = async () => false
-
-    addTagPermission('funcTag', [failingFuncTagPermission])
+  test('a passing global permission does not satisfy a failing function permission', async () => {
+    addGlobalPermission([async () => true])
 
     addTestFunction('testFunc', {
       func: async () => 'success',
-      tags: ['funcTag'],
+      permissions: { admin: [async () => false] },
     })
 
     await assert.rejects(
@@ -294,39 +255,31 @@ describe('runPikkuFunc - Integration Tests', () => {
     assert.equal(executionCount, 1)
   })
 
-  test('should handle mixed permission types correctly', async () => {
+  test('should OR function permission groups and short-circuit on the first pass', async () => {
     const executionOrder: string[] = []
 
-    // Mix of array and object permissions
-    const arrayPermission = [
-      async () => {
-        executionOrder.push('arrayPermission1')
-        return false
-      },
-      async () => {
-        executionOrder.push('arrayPermission2')
-        return true
-      },
-    ]
-
-    const objectPermission: CorePermissionGroup = {
-      permissions: [
+    // Two groups ORed together: the first (owner) fails, the second (admin) passes.
+    const permissions: CorePermissionGroup = {
+      owner: [
+        async () => {
+          executionOrder.push('owner')
+          return false
+        },
+      ],
+      admin: [
         async () => {
-          executionOrder.push('objectPermission')
+          executionOrder.push('admin')
           return true
         },
       ],
     }
 
-    addTagPermission('mixedTag', arrayPermission)
-
     addTestFunction('testFunc', {
       func: async () => {
         executionOrder.push('main')
         return 'success'
       },
-      permissions: objectPermission,
-      tags: ['mixedTag'],
+      permissions,
     })
 
     const result = await runPikkuFunc(
@@ -343,12 +296,7 @@ describe('runPikkuFunc - Integration Tests', () => {
     )
 
     assert.equal(result, 'success')
-    // Should execute tag permissions and short-circuit before function permissions
-    assert.deepEqual(executionOrder, [
-      'arrayPermission1',
-      'arrayPermission2',
-      'main',
-    ])
+    assert.deepEqual(executionOrder, ['owner', 'admin', 'main'])
   })
 
   test('should work without any middleware or permissions', async () => {
@@ -372,7 +320,7 @@ describe('runPikkuFunc - Integration Tests', () => {
     assert.equal(result, 'simple success')
   })
 
-  test('should work with only wiring-level middleware and permissions', async () => {
+  test('should work with only wiring-level middleware', async () => {
     const executionOrder: string[] = []
 
     const wiringMiddleware: CorePikkuMiddleware = async (
@@ -384,15 +332,6 @@ describe('runPikkuFunc - Integration Tests', () => {
       await next()
     }
 
-    const wiringPermissions: CorePermissionGroup = {
-      permissions: [
-        async () => {
-          executionOrder.push('wiringPermission')
-          return true
-        },
-      ],
-    }
-
     addTestFunction('testFunc', {
       func: async () => {
         executionOrder.push('main')
@@ -409,19 +348,13 @@ describe('runPikkuFunc - Integration Tests', () => {
         getAllServices: () => mockServices,
         data: () => ({}),
         wireMiddleware: [wiringMiddleware],
-        wirePermissions: wiringPermissions,
         auth: false,
         wire: {},
       }
     )
 
     assert.equal(result, 'success')
-    // Permissions run after middleware (middleware can set/modify session)
-    assert.deepEqual(executionOrder, [
-      'wiringMiddleware',
-      'wiringPermission',
-      'main',
-    ])
+    assert.deepEqual(executionOrder, ['wiringMiddleware', 'main'])
   })
 
   test('should work with only function-level middleware and permissions', async () => {
@@ -1212,7 +1145,10 @@ describe('runPikkuFunc - Integration Tests', () => {
     addTestFunction('auditedInner', {
       audit: true,
       func: async (services: any) => {
-        await services.auditLog.write({ type: 'booking.update', source: 'explicit' })
+        await services.auditLog.write({
+          type: 'booking.update',
+          source: 'explicit',
+        })
         return 'inner-ok'
       },
     })
@@ -1223,15 +1159,20 @@ describe('runPikkuFunc - Integration Tests', () => {
       },
     })
 
-    const result = await runPikkuFunc('http', 'exposed-rpc-route', 'rpcCallerLike', {
-      singletonServices,
-      data: () => ({}),
-      auth: false,
-      wire: {},
-      createWireServices: async (services: any, wire: any) => ({
-        auditLog: createInvocationAudit(services.audit, wire),
-      }),
-    })
+    const result = await runPikkuFunc(
+      'http',
+      'exposed-rpc-route',
+      'rpcCallerLike',
+      {
+        singletonServices,
+        data: () => ({}),
+        auth: false,
+        wire: {},
+        createWireServices: async (services: any, wire: any) => ({
+          auditLog: createInvocationAudit(services.audit, wire),
+        }),
+      }
+    )
 
     assert.equal(result, 'inner-ok')
     assert.equal(events.length, 1)
@@ -1249,7 +1190,10 @@ describe('runPikkuFunc - Integration Tests', () => {
     addTestFunction('auditedChildWriter', {
       audit: true,
       func: async (services: any) => {
-        await services.auditLog.write({ type: 'child.event', source: 'explicit' })
+        await services.auditLog.write({
+          type: 'child.event',
+          source: 'explicit',
+        })
         return 'child-ok'
       },
     })
@@ -1257,17 +1201,25 @@ describe('runPikkuFunc - Integration Tests', () => {
     addTestFunction('auditedParentWriter', {
       audit: true,
       func: async (services: any, _data: any, wire: any) => {
-        await services.auditLog.write({ type: 'parent.event', source: 'explicit' })
+        await services.auditLog.write({
+          type: 'parent.event',
+          source: 'explicit',
+        })
         return wire.rpc.invoke('auditedChildWriter', {})
       },
     })
 
-    const result = await runPikkuFunc('rpc', 'audited-parent-child', 'auditedParentWriter', {
-      singletonServices,
-      data: () => ({}),
-      auth: false,
-      wire: {},
-    })
+    const result = await runPikkuFunc(
+      'rpc',
+      'audited-parent-child',
+      'auditedParentWriter',
+      {
+        singletonServices,
+        data: () => ({}),
+        auth: false,
+        wire: {},
+      }
+    )
 
     assert.equal(result, 'child-ok')
     const byType = Object.fromEntries(events.map((e) => [e.type, e.functionId]))
@@ -1279,26 +1231,41 @@ describe('runPikkuFunc - Integration Tests', () => {
     const warnings: any[] = []
     const singletonServices = {
       ...mockSingletonServices,
-      logger: { ...mockSingletonServices.logger, warn: (msg: any) => warnings.push(msg) },
+      logger: {
+        ...mockSingletonServices.logger,
+        warn: (msg: any) => warnings.push(msg),
+      },
       audit: { audit: async () => {} },
     }
 
     addTestFunction('unauditedWriter', {
       func: async (services: any) => {
-        await services.auditLog.write({ type: 'dropped.event', source: 'explicit' })
+        await services.auditLog.write({
+          type: 'dropped.event',
+          source: 'explicit',
+        })
         return 'ok'
       },
     })
 
-    const result = await runPikkuFunc('rpc', 'unaudited-writer', 'unauditedWriter', {
-      singletonServices,
-      data: () => ({}),
-      auth: false,
-      wire: {},
-      createWireServices: async (services: any, wire: any) => ({
-        auditLog: createInvocationAudit(services.audit, wire, services.logger),
-      }),
-    })
+    const result = await runPikkuFunc(
+      'rpc',
+      'unaudited-writer',
+      'unauditedWriter',
+      {
+        singletonServices,
+        data: () => ({}),
+        auth: false,
+        wire: {},
+        createWireServices: async (services: any, wire: any) => ({
+          auditLog: createInvocationAudit(
+            services.audit,
+            wire,
+            services.logger
+          ),
+        }),
+      }
+    )
 
     assert.equal(result, 'ok')
     assert.equal(warnings.length, 1)
@@ -1361,3 +1328,170 @@ describe('function-runner helpers', () => {
     ])
   })
 })
+
+describe('runPikkuFunc - scopes', () => {
+  const runWithScopes = (
+    funcName: string,
+    {
+      scopes,
+      sessionScopes,
+      data = () => ({}),
+    }: {
+      scopes?: string[]
+      sessionScopes?: string[]
+      data?: () => any
+    }
+  ) =>
+    runPikkuFunc('rpc', Math.random().toString(), funcName, {
+      singletonServices: mockSingletonServices,
+      data,
+      auth: false,
+      wire: { session: { userId: 'u1', scopes: sessionScopes } as any },
+    })
+
+  test('runs the function when the session holds the required scope', async () => {
+    addTestFunction('scoped', {
+      func: async () => 'ok',
+      scopes: ['invoices:create'],
+    })
+
+    const result = await runWithScopes('scoped', {
+      sessionScopes: ['invoices:create'],
+    })
+
+    assert.equal(result, 'ok')
+  })
+
+  test('throws MissingScopeError when the session lacks the scope', async () => {
+    addTestFunction('scoped', {
+      func: async () => 'ok',
+      scopes: ['invoices:create'],
+    })
+
+    await assert.rejects(
+      () => runWithScopes('scoped', { sessionScopes: ['billing:read'] }),
+      MissingScopeError
+    )
+  })
+
+  test('honours wildcards held by the session', async () => {
+    addTestFunction('scoped', {
+      func: async () => 'ok',
+      scopes: ['admin:invoices:create'],
+    })
+
+    const result = await runWithScopes('scoped', { sessionScopes: ['admin:*'] })
+
+    assert.equal(result, 'ok')
+  })
+
+  test('does not gate a function that declares no scopes', async () => {
+    addTestFunction('unscoped', { func: async () => 'ok' })
+
+    const result = await runWithScopes('unscoped', { sessionScopes: [] })
+
+    assert.equal(result, 'ok')
+  })
+
+  test('reads scopes from function meta when the config omits them', async () => {
+    addTestFunction('metaScoped', { func: async () => 'ok' })
+    pikkuState(null, 'function', 'meta').metaScoped.scopes = ['invoices:create']
+
+    await assert.rejects(
+      () => runWithScopes('metaScoped', { sessionScopes: [] }),
+      MissingScopeError
+    )
+  })
+
+  // The load-bearing test. Scopes are an AND gate separate from permissions, so
+  // a passing global (or function) permission must never satisfy a scope.
+  test('a passing global permission does not satisfy a scope', async () => {
+    addGlobalPermission([async () => true])
+    addTestFunction('scoped', { func: async () => 'ok', scopes: ['admin'] })
+
+    await assert.rejects(
+      () => runWithScopes('scoped', { sessionScopes: [] }),
+      MissingScopeError
+    )
+  })
+
+  test('a passing function permission does not satisfy a scope', async () => {
+    addTestFunction('scoped', {
+      func: async () => 'ok',
+      scopes: ['admin'],
+      permissions: { allow: [async () => true] },
+    })
+
+    await assert.rejects(
+      () => runWithScopes('scoped', { sessionScopes: [] }),
+      MissingScopeError
+    )
+  })
+
+  test('a held scope does not bypass a failing permission', async () => {
+    addTestFunction('scoped', {
+      func: async () => 'ok',
+      scopes: ['admin'],
+      permissions: { deny: [async () => false] },
+    })
+
+    await assert.rejects(
+      () => runWithScopes('scoped', { sessionScopes: ['admin'] }),
+      { message: 'Permission denied' }
+    )
+  })
+
+  test('a failing scope short-circuits before permissions run', async () => {
+    let permissionRan = false
+    addTestFunction('scoped', {
+      func: async () => 'ok',
+      scopes: ['admin'],
+      permissions: {
+        allow: [
+          async () => {
+            permissionRan = true
+            return true
+          },
+        ],
+      },
+    })
+
+    await assert.rejects(
+      () => runWithScopes('scoped', { sessionScopes: [] }),
+      MissingScopeError
+    )
+    assert.equal(permissionRan, false)
+  })
+
+  // Scopes depend only on the session, so a denied request must never pay to
+  // parse or validate its body.
+  test('a failing scope short-circuits before the data is evaluated', async () => {
+    addTestFunction('scoped', { func: async () => 'ok', scopes: ['admin'] })
+
+    await assert.rejects(
+      () =>
+        runWithScopes('scoped', {
+          sessionScopes: [],
+          data: () => {
+            throw new Error('data should not have been evaluated')
+          },
+        }),
+      MissingScopeError
+    )
+  })
+
+  test('fails closed when there is no session at all', async () => {
+    addTestFunction('scoped', { func: async () => 'ok', scopes: ['admin'] })
+
+    await assert.rejects(
+      () =>
+        runPikkuFunc('rpc', Math.random().toString(), 'scoped', {
+          singletonServices: mockSingletonServices,
+          data: () => ({}),
+          auth: false,
+          wire: {},
+        }),
+      MissingScopeError
+    )
+  })
+})