@pikku/core 0.12.64 → 0.12.67

package/src/wirings/credential/validate-credential-definitions.ts

@@ -56,6 +56,7 @@ export function validateAndBuildCredentialDefinitionsMeta(
       type: def.type,
       schema: def.schema,
       oauth2: def.oauth2,
+      docsUrl: def.docsUrl,
       sourceFile: def.sourceFile,
     }
   }

package/src/wirings/gateway/gateway-authorization.test.ts

@@ -0,0 +1,444 @@
+import { test, describe, beforeEach } from 'node:test'
+import * as assert from 'assert'
+import { wireGateway, createListenerMessageHandler } from './gateway-runner.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { httpRouter } from '../http/routers/http-router.js'
+import { fetch } from '../http/http-runner.js'
+import {
+  addGlobalPermission,
+  clearPermissionsCache,
+} from '../../permissions.js'
+import type {
+  GatewayAdapter,
+  GatewayInboundMessage,
+  GatewayOutboundMessage,
+} from './gateway.types.js'
+
+const createMockAdapter = (): GatewayAdapter & {
+  sentMessages: Array<{ senderId: string; message: GatewayOutboundMessage }>
+} => {
+  const sentMessages: Array<{
+    senderId: string
+    message: GatewayOutboundMessage
+  }> = []
+
+  return {
+    name: 'mock',
+    sentMessages,
+    parse(data: unknown): GatewayInboundMessage | null {
+      const d = data as Record<string, any>
+      if (!d?.text) return null
+      return { senderId: d.senderId ?? 'sender-1', text: d.text, raw: data }
+    },
+    send: async (senderId, message) => {
+      sentMessages.push({ senderId, message })
+    },
+    init: async () => {},
+    close: async () => {},
+  }
+}
+
+const singletonServices = {
+  config: {},
+  logger: {
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+  },
+  variables: {},
+  secrets: {},
+}
+
+const setupState = () => {
+  resetPikkuState()
+  httpRouter.reset()
+  clearPermissionsCache()
+  pikkuState(null, 'package', 'singletonServices', singletonServices as any)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: async () => ({}),
+  } as any)
+}
+
+const seedCompiledMeta = () => {
+  const httpMeta = pikkuState(null, 'http', 'meta') as any
+  const funcMeta = pikkuState(null, 'function', 'meta') as any
+  for (const config of pikkuState(null, 'gateway', 'gateways').values()) {
+    if (config.type !== 'webhook' || !config.route) continue
+    for (const [method, funcId] of [
+      ['post', `gateway__${config.name}__post`],
+      ['get', `gateway__${config.name}__verify`],
+    ] as const) {
+      httpMeta[method][config.route] = {
+        pikkuFuncId: funcId,
+        route: config.route,
+        method,
+      }
+      funcMeta[funcId] = {
+        pikkuFuncId: funcId,
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sessionless: true,
+      }
+    }
+  }
+}
+
+const postMessage = async (route: string) => {
+  const request = new Request(`http://localhost${route}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ senderId: 'user-1', text: 'hello' }),
+  })
+  return await fetch(request)
+}
+
+describe('gateway handler authorization', () => {
+  beforeEach(() => {
+    setupState()
+  })
+
+  describe('webhook gateway', () => {
+    test('a denying permission on the handler blocks it', async () => {
+      const calls: string[] = []
+
+      wireGateway({
+        name: 'perm-deny',
+        type: 'webhook',
+        route: '/webhooks/perm-deny',
+        adapter: createMockAdapter(),
+        func: {
+          permissions: { denied: async () => false },
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/perm-deny')
+
+      assert.equal(response.status, 403)
+      assert.deepEqual(calls, [], 'handler must not run when permissions deny')
+    })
+
+    test('a passing permission on the handler allows it', async () => {
+      const calls: string[] = []
+
+      wireGateway({
+        name: 'perm-allow',
+        type: 'webhook',
+        route: '/webhooks/perm-allow',
+        adapter: createMockAdapter(),
+        func: {
+          permissions: { allowed: async () => true },
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/perm-allow')
+
+      assert.equal(response.status, 200)
+      assert.deepEqual(calls, ['ran'])
+    })
+
+    test('handler scopes are enforced and fail closed without a session', async () => {
+      const calls: string[] = []
+
+      wireGateway({
+        name: 'scope-gate',
+        type: 'webhook',
+        route: '/webhooks/scope-gate',
+        adapter: createMockAdapter(),
+        func: {
+          scopes: ['admin:webhooks'],
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/scope-gate')
+
+      assert.equal(response.status, 403)
+      assert.deepEqual(calls, [], 'handler must not run without the scope')
+    })
+
+    test('global permissions apply to gateway handlers', async () => {
+      const calls: string[] = []
+
+      addGlobalPermission([async () => false])
+
+      wireGateway({
+        name: 'global-deny',
+        type: 'webhook',
+        route: '/webhooks/global-deny',
+        adapter: createMockAdapter(),
+        func: {
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/global-deny')
+
+      assert.equal(response.status, 403)
+      assert.deepEqual(calls, [], 'a denying global must block the handler')
+    })
+
+    test('a handler with no authorization declared still runs', async () => {
+      const calls: string[] = []
+
+      wireGateway({
+        name: 'open',
+        type: 'webhook',
+        route: '/webhooks/open',
+        adapter: createMockAdapter(),
+        func: {
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/open')
+
+      assert.equal(response.status, 200)
+      assert.deepEqual(calls, ['ran'])
+    })
+
+    test('gateway-level auth: true requires a session', async () => {
+      const calls: string[] = []
+
+      wireGateway({
+        name: 'gw-auth',
+        type: 'webhook',
+        route: '/webhooks/gw-auth',
+        adapter: createMockAdapter(),
+        auth: true,
+        func: {
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/gw-auth')
+
+      assert.equal(response.status, 403)
+      assert.deepEqual(calls, [], 'auth: true must require a session')
+    })
+
+    test('handler-level auth: true requires a session', async () => {
+      const calls: string[] = []
+
+      wireGateway({
+        name: 'handler-auth',
+        type: 'webhook',
+        route: '/webhooks/handler-auth',
+        adapter: createMockAdapter(),
+        func: {
+          auth: true,
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/handler-auth')
+
+      assert.equal(response.status, 403)
+      assert.deepEqual(calls, [], 'auth: true must require a session')
+    })
+
+    test('the adapter still auto-sends the handler reply', async () => {
+      const adapter = createMockAdapter()
+
+      wireGateway({
+        name: 'reply',
+        type: 'webhook',
+        route: '/webhooks/reply',
+        adapter,
+        func: {
+          permissions: { allowed: async () => true },
+          func: async () => ({ text: 'pong' }),
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      await postMessage('/webhooks/reply')
+
+      assert.equal(adapter.sentMessages.length, 1)
+      assert.equal(adapter.sentMessages[0].message.text, 'pong')
+    })
+
+    test('a session set by gateway middleware satisfies the handler gate', async () => {
+      const seen: any[] = []
+
+      wireGateway({
+        name: 'mw-session',
+        type: 'webhook',
+        route: '/webhooks/mw-session',
+        adapter: createMockAdapter(),
+        auth: true,
+        middleware: [
+          async (_s: any, wire: any, next: any) => {
+            await wire.setSession({
+              userId: 'mapped-user',
+              scopes: ['gateway:inbound'],
+            })
+            await next()
+          },
+        ] as any,
+        func: {
+          scopes: ['gateway:inbound'],
+          func: async (_s: any, _d: any, wire: any) => {
+            seen.push(wire.session)
+            return { text: 'ok' }
+          },
+        } as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      const response = await postMessage('/webhooks/mw-session')
+
+      assert.equal(response.status, 200)
+      assert.equal(seen[0]?.userId, 'mapped-user')
+    })
+
+    test('handler middleware still runs, and only once', async () => {
+      const order: string[] = []
+
+      wireGateway({
+        name: 'mw',
+        type: 'webhook',
+        route: '/webhooks/mw',
+        adapter: createMockAdapter(),
+        func: {
+          middleware: [
+            async (_s: any, _w: any, next: any) => {
+              order.push('func-mw')
+              await next()
+            },
+          ],
+          func: async () => {
+            order.push('handler')
+            return { text: 'ok' }
+          },
+        } as any,
+        middleware: [
+          async (_s: any, _w: any, next: any) => {
+            order.push('gateway-mw')
+            await next()
+          },
+        ] as any,
+      })
+
+      seedCompiledMeta()
+      httpRouter.initialize()
+
+      await postMessage('/webhooks/mw')
+
+      assert.deepEqual(order, ['gateway-mw', 'func-mw', 'handler'])
+    })
+  })
+
+  describe('listener gateway', () => {
+    test('a denying permission on the handler blocks it', async () => {
+      const calls: string[] = []
+      const adapter = createMockAdapter()
+
+      const config = {
+        name: 'listen-deny',
+        type: 'listener' as const,
+        adapter,
+        func: {
+          permissions: { denied: async () => false },
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        },
+      }
+
+      wireGateway(config as any)
+
+      const handler = createListenerMessageHandler(
+        config.name,
+        config as any,
+        singletonServices as any
+      )
+
+      await assert.rejects(
+        () => handler({ senderId: 'user-1', text: 'hello' }),
+        /Permission denied/
+      )
+      assert.deepEqual(calls, [], 'handler must not run when permissions deny')
+    })
+
+    test('a passing permission on the handler allows it', async () => {
+      const calls: string[] = []
+      const adapter = createMockAdapter()
+
+      const config = {
+        name: 'listen-allow',
+        type: 'listener' as const,
+        adapter,
+        func: {
+          permissions: { allowed: async () => true },
+          func: async () => {
+            calls.push('ran')
+            return { text: 'reply' }
+          },
+        },
+      }
+
+      wireGateway(config as any)
+
+      const handler = createListenerMessageHandler(
+        config.name,
+        config as any,
+        singletonServices as any
+      )
+
+      await handler({ senderId: 'user-1', text: 'hello' })
+
+      assert.deepEqual(calls, ['ran'])
+      assert.equal(adapter.sentMessages.length, 1)
+    })
+  })
+})

package/src/wirings/gateway/gateway-runner.ts

@@ -1,6 +1,6 @@
 import { pikkuState } from '../../pikku-state.js'
 import { NotFoundError, UnauthorizedError } from '../../errors/errors.js'
-import { addFunction } from '../../function/function-runner.js'
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { runMiddleware } from '../../middleware-runner.js'
 import { httpRouter } from '../http/routers/http-router.js'
 import type {
@@ -17,6 +17,54 @@ import type {
  */
 const resolvedAdapters = new WeakMap<CoreGateway, Promise<GatewayAdapter>>()
 
+/**
+ * The generated function id a gateway's handler is registered under.
+ */
+const gatewayHandlerFuncId = (name: string) => `gateway__${name}__handler`
+
+/**
+ * Bridges a session established by gateway middleware onto the wire so the
+ * handler's gate can see it.
+ *
+ * Gateway middleware is the only place a webhook can acquire a session (e.g.
+ * mapping a verified platform sender to a user). Middleware that assigns
+ * `wire.session` needs nothing, but middleware using the idiomatic
+ * `wire.setSession()` writes to the enclosing wiring's session service, which
+ * the handler's own invocation does not read — without this the session would
+ * be silently invisible to `auth` and `scopes`.
+ */
+const bridgeMiddlewareSession = async (wire: PikkuRawWire): Promise<void> => {
+  if (wire.session || !wire.getSession) return
+  const session = await wire.getSession()
+  if (session) {
+    wire.session = session
+  }
+}
+
+/**
+ * Registers a gateway's handler as a real pikku function so that invoking it
+ * goes through the function runner's gate. Without this the handler is called
+ * directly and its own `auth`, `scopes` and `permissions` are never evaluated.
+ *
+ * The handler is registered as sessionless: a gateway's inbound traffic is
+ * platform-authenticated (adapter signature verification), not session-bearing,
+ * so requiring a session by default would break every webhook. A handler that
+ * does need one declares `auth: true`, exactly like `pikkuSessionlessFunc`.
+ * `scopes` and `permissions` are always enforced when declared.
+ */
+const registerGatewayHandler = (config: CoreGateway): string => {
+  const funcId = gatewayHandlerFuncId(config.name)
+  const funcMeta = pikkuState(null, 'function', 'meta')
+  funcMeta[funcId] = {
+    pikkuFuncId: funcId,
+    inputSchemaName: null,
+    outputSchemaName: null,
+    sessionless: true,
+  }
+  addFunction(funcId, config.func as any)
+  return funcId
+}
+
 export const resolveGatewayAdapter = (
   config: CoreGateway,
   services: CoreSingletonServices
@@ -142,15 +190,13 @@ const wireWebhookGateway = (config: CoreGateway): void => {
  *  2. Parse body via adapter → GatewayInboundMessage (or null to ignore)
  *  3. Populate `wire.gateway`
  *  4. Run user middleware (which can read `wire.gateway` for auth)
- *  5. Call user func with parsed message
+ *  5. Invoke the handler through the function runner, which enforces its
+ *     `auth`/`scopes`/`permissions` before running it
  *  6. Auto-send response via adapter if func returns outbound content
  */
 const createWebhookPostHandler = (config: CoreGateway) => {
-  const { name, func: userFunc, middleware: userMiddleware } = config
-  const userFuncConfig = userFunc as {
-    func: Function
-    middleware?: CorePikkuMiddleware[]
-  }
+  const { name, middleware: userMiddleware } = config
+  const handlerFuncId = registerGatewayHandler(config)
 
   return async (
     services: CoreSingletonServices,
@@ -183,26 +229,32 @@ const createWebhookPostHandler = (config: CoreGateway) => {
     }
     ;(wire as any).gateway = gateway
 
-    // Build combined middleware chain: gateway-level + func-level
-    const allMiddleware: CorePikkuMiddleware[] = [
-      ...((userMiddleware as CorePikkuMiddleware[] | undefined) || []),
-      ...(userFuncConfig.middleware || []),
-    ]
-
-    const exec = async () => {
-      const result = await userFuncConfig.func(services, parsed, wire)
-      // Auto-send response if the func returns outbound content
-      if (result && (result.text || result.richContent || result.attachments)) {
-        await adapter.send(parsed.senderId, result as GatewayOutboundMessage)
-      }
-      return { ok: true }
+    // Gateway middleware runs first and outside the gate, so it can establish
+    // the session the gate then checks. The handler is invoked through the
+    // function runner, which enforces its auth, scopes and permissions and
+    // applies the handler's own middleware.
+    const invoke = async () => {
+      await bridgeMiddlewareSession(wire as any)
+      return await runPikkuFunc('gateway', name, handlerFuncId, {
+        singletonServices: services,
+        data: () => parsed,
+        auth: config.auth,
+        wire: wire as any,
+      })
     }
 
-    if (allMiddleware.length > 0) {
-      return await runMiddleware(services, wire, allMiddleware, exec)
-    }
+    const gatewayMiddleware = userMiddleware as
+      | CorePikkuMiddleware[]
+      | undefined
+    const result: any = gatewayMiddleware?.length
+      ? await runMiddleware(services, wire, gatewayMiddleware, invoke)
+      : await invoke()
 
-    return await exec()
+    // Auto-send response if the func returns outbound content
+    if (result && (result.text || result.richContent || result.attachments)) {
+      await adapter.send(parsed.senderId, result as GatewayOutboundMessage)
+    }
+    return { ok: true }
   }
 }
 
@@ -281,11 +333,8 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
     message: { pikkuFuncId: messageFuncId },
   } as any
 
-  const userFuncConfig = config.func as {
-    func: Function
-    middleware?: CorePikkuMiddleware[]
-  }
   const userMiddleware = config.middleware as CorePikkuMiddleware[] | undefined
+  const handlerFuncId = registerGatewayHandler(config)
 
   // Register onConnect
   addFunction(connectFuncId, {
@@ -321,25 +370,25 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
       }
       ;(wire as any).gateway = gateway
 
-      const allMiddleware: CorePikkuMiddleware[] = [
-        ...(userMiddleware || []),
-        ...(userFuncConfig.middleware || []),
-      ]
-
-      const exec = async () => {
-        const result = await userFuncConfig.func(services, parsed, wire)
-        if (
-          result &&
-          (result.text || result.richContent || result.attachments)
-        ) {
-          wire.channel?.send(result)
-        }
+      const invoke = async () => {
+        await bridgeMiddlewareSession(wire as any)
+        return await runPikkuFunc('gateway', name, handlerFuncId, {
+          singletonServices: services,
+          data: () => parsed,
+          auth: config.auth,
+          wire: wire as any,
+        })
       }
 
-      if (allMiddleware.length > 0) {
-        await runMiddleware(services, wire, allMiddleware, exec)
-      } else {
-        await exec()
+      const gatewayMiddleware = userMiddleware as
+        | CorePikkuMiddleware[]
+        | undefined
+      const result: any = gatewayMiddleware?.length
+        ? await runMiddleware(services, wire, gatewayMiddleware, invoke)
+        : await invoke()
+
+      if (result && (result.text || result.richContent || result.attachments)) {
+        wire.channel?.send(result)
       }
     },
   } as any)
@@ -384,11 +433,8 @@ export const createListenerMessageHandler = (
   config: CoreGateway,
   singletonServices: CoreSingletonServices
 ): ((rawData: unknown) => Promise<void>) => {
-  const userFuncConfig = config.func as {
-    func: Function
-    middleware?: CorePikkuMiddleware[]
-  }
   const userMiddleware = config.middleware as CorePikkuMiddleware[] | undefined
+  const handlerFuncId = registerGatewayHandler(config)
 
   return async (rawData: unknown): Promise<void> => {
     const adapter = await resolveGatewayAdapter(config, singletonServices)
@@ -404,27 +450,27 @@ export const createListenerMessageHandler = (
     }
     ;(wire as any).gateway = gateway
 
-    const allMiddleware: CorePikkuMiddleware[] = [
-      ...(userMiddleware || []),
-      ...(userFuncConfig.middleware || []),
-    ]
-
-    const exec = async () => {
-      const result = await userFuncConfig.func(singletonServices, parsed, wire)
-      if (result && (result.text || result.richContent || result.attachments)) {
-        await adapter.send(parsed.senderId, result as GatewayOutboundMessage)
-      }
+    const invoke = async () => {
+      await bridgeMiddlewareSession(wire)
+      return await runPikkuFunc('gateway', name, handlerFuncId, {
+        singletonServices,
+        data: () => parsed,
+        auth: config.auth,
+        wire,
+      })
     }
 
-    if (allMiddleware.length > 0) {
-      await runMiddleware(
-        singletonServices,
-        wire as unknown as PikkuWire,
-        allMiddleware,
-        exec
-      )
-    } else {
-      await exec()
+    const result: any = userMiddleware?.length
+      ? await runMiddleware(
+          singletonServices,
+          wire as any,
+          userMiddleware,
+          invoke
+        )
+      : await invoke()
+
+    if (result && (result.text || result.richContent || result.attachments)) {
+      await adapter.send(parsed.senderId, result as GatewayOutboundMessage)
     }
   }
 }