@pikku/core 0.12.14 → 0.12.16

package/src/function/functions.types.ts

@@ -257,6 +257,7 @@ export const pikkuAuth = <
     if (!session) return false
     return fn(services, session as Session)
   }
+  ;(wrapper as any).__pikkuAuth = true
   return wrapper as any
 }
 

package/src/function/index.ts

@@ -1,5 +1,15 @@
 export { addFunction, getAllFunctionNames } from './function-runner.js'
+export {
+  pikkuAuth,
+  pikkuPermission,
+  pikkuPermissionFactory,
+  pikkuApprovalDescription,
+} from './functions.types.js'
 export type {
   CorePikkuFunction,
   CorePikkuFunctionSessionless,
+  CorePikkuFunctionConfig,
+  CorePikkuAuth,
+  CorePikkuAuthConfig,
+  CorePikkuPermission,
 } from './functions.types.js'

package/src/handle-error.test.ts

@@ -91,7 +91,7 @@ describe('handleHTTPError', () => {
     assert.deepStrictEqual(http._state.jsonBody, {
       message: 'The server cannot find the requested resource.',
       payload: undefined,
-      traceId: 'tracker-1',
+      errorId: 'tracker-1',
     })
   })
 
@@ -112,7 +112,7 @@ describe('handleHTTPError', () => {
 
     assert.strictEqual(http._state.statusCode, 400)
     assert.ok(http._state.jsonBody.message.includes('client error'))
-    assert.strictEqual(http._state.jsonBody.traceId, 'tracker-2')
+    assert.strictEqual(http._state.jsonBody.errorId, 'tracker-2')
   })
 
   test('should set status 403 for ForbiddenError', () => {

package/src/handle-error.ts

@@ -9,7 +9,7 @@ import type { PikkuHTTP } from './wirings/http/http.types.js'
  *
  * @param {any} e - The error that occurred
  * @param {PikkuHTTP | undefined} http - HTTP wire object
- * @param {string} trackerId - Unique ID for tracking this error
+ * @param {string} traceId - Unique ID for tracking this error
  * @param {Logger} logger - Logger service
  * @param {number[]} logWarningsForStatusCodes - HTTP status codes to log as warnings
  * @param {boolean} respondWith404 - Whether to respond with 404 for NotFoundError
@@ -18,7 +18,7 @@ import type { PikkuHTTP } from './wirings/http/http.types.js'
 export const handleHTTPError = (
   e: any,
   http: PikkuHTTP | undefined,
-  trackerId: string | undefined,
+  traceId: string | undefined,
   logger: Logger,
   logWarningsForStatusCodes: number[],
   respondWith404: boolean,
@@ -38,13 +38,13 @@ export const handleHTTPError = (
     http?.response?.json({
       message: errorResponse.message,
       payload: (e as any).payload,
-      traceId: trackerId,
+      errorId: traceId,
     })
 
     // Log certain status codes as warnings
     if (logWarningsForStatusCodes.includes(errorResponse.status)) {
-      if (trackerId) {
-        logger.warn(`Warning id: ${trackerId}`)
+      if (traceId) {
+        logger.warn(`Warning id: ${traceId}`)
       }
       logger.warn(e instanceof Error ? e.message : e)
     }
@@ -53,9 +53,9 @@ export const handleHTTPError = (
     logger.error(e instanceof Error ? e.message : e)
     http?.response?.status(500)
 
-    if (trackerId) {
-      logger.warn(`Error id: ${trackerId}`)
-      const errorBody: Record<string, unknown> = { errorId: trackerId }
+    if (traceId) {
+      logger.warn(`Error id: ${traceId}`)
+      const errorBody: Record<string, unknown> = { errorId: traceId }
       if (exposeErrors && !isProduction() && e instanceof Error) {
         errorBody.message = e.message
         errorBody.stack = e.stack

package/src/index.ts

@@ -22,6 +22,7 @@ export type {
   JSONValue,
   MakeRequired,
   MiddlewareMetadata,
+  MiddlewarePriority,
   PermissionMetadata,
   PickOptional,
   PickRequired,
@@ -103,12 +104,11 @@ export type { AIStorageService } from './services/ai-storage-service.js'
 export type { HTTPMethod } from './wirings/http/http.types.js'
 export type { GraphNodeConfig } from './wirings/workflow/graph/workflow-graph.types.js'
 export { createGraph } from './wirings/workflow/graph/graph-node.js'
-export { workflow as wireWorkflow } from './wirings/workflow/workflow-helpers.js'
 export { wireAddon } from './wirings/rpc/wire-addon.js'
 export type { WireAddonConfig } from './wirings/rpc/wire-addon.js'
 export type { PikkuPackageState } from './types/state.types.js'
 export { runMiddleware, addMiddleware } from './middleware-runner.js'
-export { addPermission } from './permissions.js'
+export { addPermission, checkAuthPermissions } from './permissions.js'
 export { isSerializable, stopSingletonServices } from './utils.js'
 export { getSingletonServices, getCreateWireServices } from './pikku-state.js'
 export {

package/src/middleware/index.ts

@@ -3,3 +3,6 @@ export { authCookie } from './auth-cookie.js'
 export { authBearer } from './auth-bearer.js'
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js'
 export { cors } from './cors.js'
+export { telemetryOuter, telemetryInner } from './telemetry.js'
+export { addMiddleware, runMiddleware } from '../middleware-runner.js'
+export { addPermission } from '../permissions.js'

package/src/middleware/remote-auth.test.ts

@@ -252,7 +252,7 @@ describe('pikkuRemoteAuthMiddleware', () => {
               http: {
                 request: createMockRequest(
                   { authorization: 'Bearer valid-token' },
-                  '/rpc/otherFunc'
+                  '/remote/rpc/otherFunc'
                 ),
               },
             } as any,
@@ -273,7 +273,7 @@ describe('pikkuRemoteAuthMiddleware', () => {
           http: {
             request: createMockRequest(
               { authorization: 'Bearer valid-token' },
-              '/rpc/myFunc'
+              '/remote/rpc/myFunc'
             ),
           },
         } as any,
@@ -295,7 +295,7 @@ describe('pikkuRemoteAuthMiddleware', () => {
           http: {
             request: createMockRequest(
               { authorization: 'Bearer valid-token' },
-              '/rpc/anyFunc'
+              '/remote/rpc/anyFunc'
             ),
           },
         } as any,
@@ -339,7 +339,7 @@ describe('pikkuRemoteAuthMiddleware', () => {
           http: {
             request: createMockRequest(
               { authorization: 'Bearer valid-token' },
-              '/rpc/my%20func'
+              '/remote/rpc/my%20func'
             ),
           },
         } as any,

package/src/middleware/remote-auth.ts

@@ -12,6 +12,9 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(
     try {
       secret = await secrets.getSecret('PIKKU_REMOTE_SECRET')
     } catch {
+      if (http.request.path().startsWith('/remote/rpc/')) {
+        throw new UnauthorizedError()
+      }
       return next()
     }
     if (!jwt) {
@@ -42,8 +45,10 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(
       throw new UnauthorizedError()
     }
 
-    if (payload?.fn && http.request.path().startsWith('/rpc/')) {
-      const fn = decodeURIComponent(http.request.path().slice('/rpc/'.length))
+    if (payload?.fn && http.request.path().startsWith('/remote/rpc/')) {
+      const fn = decodeURIComponent(
+        http.request.path().slice('/remote/rpc/'.length)
+      )
       if (fn && payload.fn !== fn) {
         throw new UnauthorizedError()
       }

package/src/middleware/telemetry.ts

@@ -0,0 +1,110 @@
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
+
+/**
+ * Outer telemetry middleware that captures total request duration and outcome.
+ * Runs at `highest` priority (outermost in the middleware chain).
+ *
+ * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
+ * - Total duration (including all middleware)
+ * - Outcome (ok/error)
+ * - Wire metadata (wireType, wireId, traceId)
+ * - HTTP details (method, path, status) if applicable
+ *
+ * @example
+ * ```typescript
+ * import { telemetryOuter } from '@pikku/core/middleware'
+ * addMiddleware('myTag', [telemetryOuter()])
+ * ```
+ */
+export const telemetryOuter = pikkuMiddlewareFactory<{
+  environmentId?: string
+  orgId?: string
+} | void>(({ environmentId, orgId } = {}) => {
+  return pikkuMiddleware({
+    name: 'telemetry-outer',
+    priority: 'highest',
+    func: async (services, wire, next) => {
+      const start = performance.now()
+      let outcome = 'ok'
+      let errorMessage: string | undefined
+      try {
+        await next()
+      } catch (e) {
+        outcome = 'error'
+        errorMessage = e instanceof Error ? e.message : String(e)
+        throw e
+      } finally {
+        services.logger.info({
+          __pikku_telemetry: 'end',
+          __pikku_layer: 'outer',
+          traceId: wire.traceId,
+          wireType: wire.wireType,
+          wireId: wire.wireId,
+          totalDuration: Math.round(performance.now() - start),
+          outcome,
+          ...(errorMessage ? { errorMessage } : {}),
+          ...(wire.http
+            ? {
+                httpStatus: wire.http.response?.statusCode,
+                httpMethod: wire.http.request?.method(),
+                httpPath: wire.http.request?.path(),
+              }
+            : {}),
+          ...(environmentId ? { environmentId } : {}),
+          ...(orgId ? { orgId } : {}),
+        })
+      }
+    },
+  })
+})
+
+/**
+ * Inner telemetry middleware that captures function execution duration and user context.
+ * Runs at `lowest` priority (innermost, closest to the function).
+ *
+ * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
+ * - Function-only duration (excluding outer middleware like auth)
+ * - User identity (pikkuUserId) if authenticated
+ * - Wire metadata (wireType, wireId, traceId)
+ *
+ * @example
+ * ```typescript
+ * import { telemetryInner } from '@pikku/core/middleware'
+ * addMiddleware('myTag', [telemetryInner()])
+ * ```
+ */
+export const telemetryInner = pikkuMiddlewareFactory<{
+  environmentId?: string
+  orgId?: string
+} | void>(({ environmentId, orgId } = {}) => {
+  return pikkuMiddleware({
+    name: 'telemetry-inner',
+    priority: 'lowest',
+    func: async (services, wire, next) => {
+      const start = performance.now()
+      let outcome = 'ok'
+      let errorMessage: string | undefined
+      try {
+        await next()
+      } catch (e) {
+        outcome = 'error'
+        errorMessage = e instanceof Error ? e.message : String(e)
+        throw e
+      } finally {
+        services.logger.info({
+          __pikku_telemetry: 'end',
+          __pikku_layer: 'inner',
+          traceId: wire.traceId,
+          wireType: wire.wireType,
+          wireId: wire.wireId,
+          functionDuration: Math.round(performance.now() - start),
+          outcome,
+          pikkuUserId: wire.pikkuUserId,
+          ...(errorMessage ? { errorMessage } : {}),
+          ...(environmentId ? { environmentId } : {}),
+          ...(orgId ? { orgId } : {}),
+        })
+      }
+    },
+  })
+})

package/src/middleware-runner.test.ts

@@ -6,7 +6,27 @@ import {
   runMiddleware,
 } from './middleware-runner.js'
 import { resetPikkuState } from './pikku-state.js'
-import type { CorePikkuMiddleware } from './types/core.types.js'
+import type {
+  CorePikkuMiddleware,
+  MiddlewarePriority,
+} from './types/core.types.js'
+import { pikkuMiddleware } from './types/core.types.js'
+
+const withPriority = (
+  name: string,
+  priority: MiddlewarePriority,
+  log: string[]
+): CorePikkuMiddleware => {
+  return pikkuMiddleware({
+    name,
+    priority,
+    func: async (_services, _wire, next) => {
+      log.push(`start:${name}`)
+      await next()
+      log.push(`end:${name}`)
+    },
+  })
+}
 
 beforeEach(() => {
   resetPikkuState()
@@ -329,6 +349,56 @@ describe('combineMiddleware', () => {
     assert.equal(result.length, 1)
     assert.equal(result[0], middleware)
   })
+
+  test('should sort middleware by priority', () => {
+    const log: string[] = []
+    const low = withPriority('low', 'low', log)
+    const highest = withPriority('highest', 'highest', log)
+    const medium = withPriority('medium', 'medium', log)
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireMiddleware: [low, highest, medium],
+    })
+
+    assert.equal(result.length, 3)
+    assert.equal(result[0], highest)
+    assert.equal(result[1], medium)
+    assert.equal(result[2], low)
+  })
+
+  test('should default unprioritized middleware to medium', () => {
+    const log: string[] = []
+    const highest = withPriority('highest', 'highest', log)
+    const lowest = withPriority('lowest', 'lowest', log)
+    const noPriority: CorePikkuMiddleware = async (_services, _wire, next) => {
+      await next()
+    }
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireMiddleware: [lowest, noPriority, highest],
+    })
+
+    assert.equal(result.length, 3)
+    assert.equal(result[0], highest)
+    assert.equal(result[1], noPriority) // defaults to medium
+    assert.equal(result[2], lowest)
+  })
+
+  test('should preserve registration order within same priority', () => {
+    const log: string[] = []
+    const first = withPriority('first', 'medium', log)
+    const second = withPriority('second', 'medium', log)
+    const third = withPriority('third', 'medium', log)
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireMiddleware: [first, second, third],
+    })
+
+    assert.equal(result.length, 3)
+    assert.equal(result[0], first)
+    assert.equal(result[1], second)
+    assert.equal(result[2], third)
+  })
 })
 
 describe('runMiddleware', () => {
@@ -415,4 +485,82 @@ describe('runMiddleware', () => {
 
     assert.deepEqual(executionOrder, ['middleware'])
   })
+
+  test('should execute middleware in priority order (highest first, lowest last)', async () => {
+    const log: string[] = []
+    const low = withPriority('low', 'low', log)
+    const highest = withPriority('highest', 'highest', log)
+    const medium = withPriority('medium', 'medium', log)
+
+    await runMiddleware(
+      {} as any,
+      {} as any,
+      [low, highest, medium],
+      async () => {
+        log.push('main')
+      }
+    )
+
+    assert.deepEqual(log, [
+      'start:highest',
+      'start:medium',
+      'start:low',
+      'main',
+      'end:low',
+      'end:medium',
+      'end:highest',
+    ])
+  })
+
+  test('should sort unsorted middleware passed directly to runMiddleware', async () => {
+    const log: string[] = []
+    const lowest = withPriority('lowest', 'lowest', log)
+    const highest = withPriority('highest', 'highest', log)
+
+    await runMiddleware({} as any, {} as any, [lowest, highest], async () => {
+      log.push('main')
+    })
+
+    // highest should run first (outermost), lowest last (innermost)
+    assert.deepEqual(log, [
+      'start:highest',
+      'start:lowest',
+      'main',
+      'end:lowest',
+      'end:highest',
+    ])
+  })
+
+  test('should handle all five priority levels in correct order', async () => {
+    const log: string[] = []
+    const lowest = withPriority('lowest', 'lowest', log)
+    const low = withPriority('low', 'low', log)
+    const medium = withPriority('medium', 'medium', log)
+    const high = withPriority('high', 'high', log)
+    const highest = withPriority('highest', 'highest', log)
+
+    // Pass in reverse order to verify sorting
+    await runMiddleware(
+      {} as any,
+      {} as any,
+      [lowest, low, medium, high, highest],
+      async () => {
+        log.push('main')
+      }
+    )
+
+    assert.deepEqual(log, [
+      'start:highest',
+      'start:high',
+      'start:medium',
+      'start:low',
+      'start:lowest',
+      'main',
+      'end:lowest',
+      'end:low',
+      'end:medium',
+      'end:high',
+      'end:highest',
+    ])
+  })
 })

package/src/middleware-runner.ts

@@ -5,10 +5,34 @@ import type {
   CorePikkuMiddlewareGroup,
   PikkuWiringTypes,
   MiddlewareMetadata,
+  MiddlewarePriority,
 } from './types/core.types.js'
 import { pikkuState } from './pikku-state.js'
 import { freezeDedupe, getTagGroups } from './utils.js'
 
+const PRIORITY_ORDER: Record<MiddlewarePriority, number> = {
+  highest: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+  lowest: 4,
+}
+
+const getMiddlewarePriority = (fn: CorePikkuMiddleware): number => {
+  const priority = (
+    fn as CorePikkuMiddleware & { __priority?: MiddlewarePriority }
+  ).__priority
+  return PRIORITY_ORDER[priority ?? 'medium']
+}
+
+const sortByPriority = (
+  middlewares: CorePikkuMiddleware[]
+): CorePikkuMiddleware[] => {
+  return middlewares.sort(
+    (a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b)
+  )
+}
+
 /**
  * Runs a chain of middleware functions in sequence before executing the main function.
  *
@@ -32,11 +56,16 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
   middlewares: readonly Middleware[],
   main?: () => Promise<unknown>
 ): Promise<unknown> => {
-  // Deduplicate middleware using Set to avoid running the same middleware multiple times
+  // Sort by priority if not already sorted (cached middleware is pre-sorted)
+  const sorted = isSortedByPriority(middlewares)
+    ? middlewares
+    : ([...middlewares].sort(
+        (a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b)
+      ) as readonly Middleware[])
   let result: any
   const dispatch = async (index: number): Promise<any> => {
-    if (middlewares && index < middlewares.length) {
-      return await middlewares[index]!(services as any, wire, () =>
+    if (sorted && index < sorted.length) {
+      return await sorted[index]!(services as any, wire, () =>
         dispatch(index + 1)
       )
     } else if (main) {
@@ -47,6 +76,20 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
   return result
 }
 
+const isSortedByPriority = (
+  middlewares: readonly CorePikkuMiddleware[]
+): boolean => {
+  for (let i = 1; i < middlewares.length; i++) {
+    if (
+      getMiddlewarePriority(middlewares[i]) <
+      getMiddlewarePriority(middlewares[i - 1])
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
 /**
  * Registers global middleware for a specific tag.
  *
@@ -231,7 +274,8 @@ export const combineMiddleware = (
     resolved.push(...funcMiddleware)
   }
 
-  // Deduplicate and freeze
+  // Sort by priority, deduplicate, and freeze
+  sortByPriority(resolved)
   middlewareCache[wireType][uid] = freezeDedupe(
     resolved
   ) as readonly CorePikkuMiddleware[]

package/src/permissions.ts

@@ -1,5 +1,6 @@
 import type {
   CoreServices,
+  CoreUserSession,
   PikkuWiringTypes,
   PermissionMetadata,
   PikkuWire,
@@ -325,3 +326,72 @@ export const runPermissions = async (
     throw new ForbiddenError('Permission denied')
   }
 }
+
+/**
+ * Checks whether a session passes the auth checks (pikkuAuth only) for a
+ * given function/agent. Skips pikkuPermission checks since those require
+ * request data which isn't available at filter time.
+ *
+ * @param funcPermissions - The PermissionMetadata[] from function or agent metadata
+ * @param session - The user's session
+ * @param services - Singleton services
+ * @param packageName - Optional package namespace
+ * @returns true if the session passes all auth checks (or no auth checks exist)
+ */
+export const checkAuthPermissions = async (
+  funcPermissions: PermissionMetadata[] | undefined,
+  session: CoreUserSession,
+  services: CoreServices,
+  packageName: string | null = null
+): Promise<boolean> => {
+  if (!funcPermissions?.length) return true
+
+  const allPermissions = combinePermissions(
+    'agent',
+    `authcheck:${Math.random()}`,
+    {
+      funcInheritedPermissions: funcPermissions,
+      packageName,
+    }
+  )
+
+  if (allPermissions.length === 0) return true
+
+  const wire = { session } as unknown as PikkuWire<
+    any,
+    never,
+    any,
+    never,
+    never,
+    never
+  >
+
+  // Extract only pikkuAuth permissions (marked with __pikkuAuth)
+  const authPerms: CorePikkuPermission[] = []
+  for (const permission of allPermissions) {
+    if (typeof permission === 'function') {
+      if ((permission as any).__pikkuAuth) {
+        authPerms.push(permission)
+      }
+    } else if (permission && typeof permission === 'object') {
+      for (const funcs of Object.values(permission)) {
+        const arr = Array.isArray(funcs) ? funcs : [funcs]
+        for (const fn of arr) {
+          if (typeof fn === 'function' && (fn as any).__pikkuAuth) {
+            authPerms.push(fn)
+          }
+        }
+      }
+    }
+  }
+
+  // No auth permissions = allowed (only data-dependent permissions exist)
+  if (authPerms.length === 0) return true
+
+  // All auth permissions must pass
+  for (const perm of authPerms) {
+    const result = await perm(services, null, wire)
+    if (result) return true
+  }
+  return false
+}

package/src/pikku-state.test.ts

@@ -7,7 +7,6 @@ import {
   getAllPackageStates,
   getSingletonServices,
   getCreateWireServices,
-  getPikkuMetaDir,
   addPackageServiceFactories,
 } from './pikku-state.js'
 
@@ -176,31 +175,6 @@ describe('getCreateWireServices', () => {
   })
 })
 
-describe('getPikkuMetaDir', () => {
-  test('should return null by default', () => {
-    const result = getPikkuMetaDir()
-    assert.strictEqual(result, null)
-  })
-
-  test('should return metaDir when set', () => {
-    pikkuState(null, 'package', 'metaDir', '/some/path' as any)
-    const result = getPikkuMetaDir()
-    assert.strictEqual(result, '/some/path')
-  })
-
-  test('should return metaDir for specific package', () => {
-    pikkuState('@test/pkg', 'package', 'metaDir', '/addon/path' as any)
-    const result = getPikkuMetaDir('@test/pkg')
-    assert.strictEqual(result, '/addon/path')
-  })
-
-  test('should treat null packageName as main', () => {
-    pikkuState(null, 'package', 'metaDir', '/main/path' as any)
-    const result = getPikkuMetaDir(null)
-    assert.strictEqual(result, '/main/path')
-  })
-})
-
 describe('addPackageServiceFactories', () => {
   test('should register factories for addon package', () => {
     const mockFactories = {

package/src/pikku-state.ts

@@ -156,8 +156,8 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   package: {
     factories: null,
     singletonServices: null,
-    metaDir: null,
     credentialsMeta: null,
+    requiredParentServices: null,
   },
 })
 
@@ -188,10 +188,6 @@ if (!getAllPackageStates().has('__main__')) {
   resetPikkuState()
 }
 
-export const getPikkuMetaDir = (packageName?: string | null): string | null => {
-  return pikkuState(packageName ?? null, 'package', 'metaDir')
-}
-
 export const getSingletonServices = (): CoreSingletonServices => {
   const services = pikkuState(null, 'package', 'singletonServices')
   if (!services) throw new Error('Singleton services not initialized')