@pikku/core 0.11.1 → 0.12.0

package/src/middleware/cors.ts

@@ -0,0 +1,96 @@
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
+
+/**
+ * CORS middleware that handles cross-origin requests including OPTIONS preflight.
+ *
+ * Sets appropriate CORS headers on all responses and short-circuits OPTIONS
+ * preflight requests with a 204 No Content response.
+ *
+ * @param options.origin - Allowed origin(s). Use `'*'` for any origin, a string for a single origin, or an array for multiple origins. Defaults to `'*'`.
+ * @param options.methods - Allowed HTTP methods. Defaults to common methods.
+ * @param options.headers - Allowed request headers. Defaults to common headers.
+ * @param options.credentials - Whether to allow credentials. Defaults to `false`.
+ * @param options.maxAge - Preflight cache duration in seconds. Defaults to `86400` (24 hours).
+ *
+ * @example
+ * ```typescript
+ * import { cors } from '@pikku/core/middleware'
+ *
+ * // Allow all origins
+ * addHTTPMiddleware('*', [cors()])
+ *
+ * // Specific origin with credentials
+ * addHTTPMiddleware('*', [
+ *   cors({
+ *     origin: 'https://app.example.com',
+ *     credentials: true,
+ *   })
+ * ])
+ *
+ * // Multiple origins
+ * addHTTPMiddleware('*', [
+ *   cors({
+ *     origin: ['https://app.example.com', 'https://admin.example.com'],
+ *   })
+ * ])
+ * ```
+ */
+export const cors = pikkuMiddlewareFactory<{
+  origin?: string | string[]
+  methods?: string[]
+  headers?: string[]
+  credentials?: boolean
+  maxAge?: number
+}>(
+  ({
+    origin = '*',
+    methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+    headers = ['Content-Type', 'Authorization', 'x-api-key'],
+    credentials = false,
+    maxAge = 86400,
+  } = {}) =>
+    pikkuMiddleware({
+      name: 'CORS',
+      description: 'Handles cross-origin requests including OPTIONS preflight',
+      func: async (_services, wires, next) => {
+        const request = wires.http?.request
+        const response = wires.http?.response
+
+        if (!request || !response) {
+          return next()
+        }
+
+        const requestOrigin = request.header('origin')
+
+        let allowedOrigin: string
+        if (Array.isArray(origin)) {
+          allowedOrigin =
+            requestOrigin && origin.includes(requestOrigin)
+              ? requestOrigin
+              : origin[0]
+        } else {
+          allowedOrigin = origin
+        }
+
+        response.header('Access-Control-Allow-Origin', allowedOrigin)
+        response.header('Access-Control-Allow-Methods', methods.join(', '))
+        response.header('Access-Control-Allow-Headers', headers.join(', '))
+
+        if (credentials) {
+          response.header('Access-Control-Allow-Credentials', 'true')
+        }
+
+        if (Array.isArray(origin)) {
+          response.header('Vary', 'Origin')
+        }
+
+        if (request.method() === 'options') {
+          response.header('Access-Control-Max-Age', String(maxAge))
+          response.status(204).json(undefined as any)
+          return
+        }
+
+        return next()
+      },
+    })
+)

package/src/middleware/index.ts

@@ -1,3 +1,5 @@
-export * from './auth-apikey.js'
-export * from './auth-cookie.js'
-export * from './auth-bearer.js'
+export { authAPIKey } from './auth-apikey.js'
+export { authCookie } from './auth-cookie.js'
+export { authBearer } from './auth-bearer.js'
+export { pikkuRemoteAuthMiddleware } from './remote-auth.js'
+export { cors } from './cors.js'

package/src/middleware/remote-auth.ts

@@ -0,0 +1,68 @@
+import { UnauthorizedError } from '../errors/errors.js'
+import { pikkuMiddleware } from '../types/core.types.js'
+import { decryptJSON } from '../crypto-utils.js'
+
+export const pikkuRemoteAuthMiddleware = pikkuMiddleware(
+  async ({ secrets, jwt }, { http, setSession }, next) => {
+    if (!http?.request || !secrets) {
+      return next()
+    }
+
+    let secret: string
+    try {
+      secret = await secrets.getSecret('PIKKU_REMOTE_SECRET')
+    } catch {
+      return next()
+    }
+    if (!jwt) {
+      throw new Error('PIKKU_REMOTE_SECRET set but JWT service missing')
+    }
+
+    const authHeader =
+      http.request.header('authorization') ||
+      http.request.header('Authorization')
+
+    if (!authHeader) {
+      throw new UnauthorizedError()
+    }
+
+    const [scheme, token] = authHeader.split(' ')
+    if (scheme !== 'Bearer' || !token) {
+      throw new UnauthorizedError()
+    }
+
+    let payload: any
+    try {
+      payload = await jwt.decode(token)
+    } catch {
+      throw new UnauthorizedError()
+    }
+
+    if (payload?.aud !== 'pikku-remote') {
+      throw new UnauthorizedError()
+    }
+
+    if (payload?.fn && http.request.path().startsWith('/rpc/')) {
+      const fn = decodeURIComponent(http.request.path().slice('/rpc/'.length))
+      if (fn && payload.fn !== fn) {
+        throw new UnauthorizedError()
+      }
+    }
+
+    if (payload?.session) {
+      try {
+        const decrypted = await decryptJSON<{ session?: unknown }>(
+          secret,
+          payload.session
+        )
+        if (decrypted?.session && setSession) {
+          await setSession(decrypted.session)
+        }
+      } catch {
+        throw new UnauthorizedError()
+      }
+    }
+
+    return next()
+  }
+)

package/src/middleware-runner.test.ts

@@ -189,6 +189,128 @@ describe('combineMiddleware', () => {
     assert.equal(result[1], middleware2)
   })
 
+  test('should apply parent tag middleware to namespaced tag', () => {
+    const billingMiddleware: CorePikkuMiddleware = async (
+      services,
+      wire,
+      next
+    ) => {
+      await next()
+    }
+
+    addMiddleware('billing', [billingMiddleware])
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireInheritedMiddleware: [{ type: 'tag', tag: 'billing:read' }],
+    })
+
+    assert.equal(result.length, 1)
+    assert.equal(result[0], billingMiddleware)
+  })
+
+  test('should apply exact tag middleware for non-namespaced tag', () => {
+    const billingMiddleware: CorePikkuMiddleware = async (
+      services,
+      wire,
+      next
+    ) => {
+      await next()
+    }
+
+    addMiddleware('billing', [billingMiddleware])
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireInheritedMiddleware: [{ type: 'tag', tag: 'billing' }],
+    })
+
+    assert.equal(result.length, 1)
+    assert.equal(result[0], billingMiddleware)
+  })
+
+  test('should apply both exact and parent tag middleware (specific first)', () => {
+    const billingMiddleware: CorePikkuMiddleware = async (
+      services,
+      wire,
+      next
+    ) => {
+      await next()
+    }
+    const billingReadMiddleware: CorePikkuMiddleware = async (
+      services,
+      wire,
+      next
+    ) => {
+      await next()
+    }
+
+    addMiddleware('billing', [billingMiddleware])
+    addMiddleware('billing:read', [billingReadMiddleware])
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireInheritedMiddleware: [{ type: 'tag', tag: 'billing:read' }],
+    })
+
+    assert.equal(result.length, 2)
+    assert.equal(result[0], billingReadMiddleware)
+    assert.equal(result[1], billingMiddleware)
+  })
+
+  test('should resolve multi-level namespace tags', () => {
+    const billingMiddleware: CorePikkuMiddleware = async (
+      services,
+      wire,
+      next
+    ) => {
+      await next()
+    }
+    const billingReadMiddleware: CorePikkuMiddleware = async (
+      services,
+      wire,
+      next
+    ) => {
+      await next()
+    }
+    const billingReadAdminMiddleware: CorePikkuMiddleware = async (
+      services,
+      wire,
+      next
+    ) => {
+      await next()
+    }
+
+    addMiddleware('billing', [billingMiddleware])
+    addMiddleware('billing:read', [billingReadMiddleware])
+    addMiddleware('billing:read:admin', [billingReadAdminMiddleware])
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireInheritedMiddleware: [{ type: 'tag', tag: 'billing:read:admin' }],
+    })
+
+    assert.equal(result.length, 3)
+    assert.equal(result[0], billingReadAdminMiddleware)
+    assert.equal(result[1], billingReadMiddleware)
+    assert.equal(result[2], billingMiddleware)
+  })
+
+  test('should apply parent tag middleware via funcInheritedMiddleware', () => {
+    const billingMiddleware: CorePikkuMiddleware = async (
+      services,
+      wire,
+      next
+    ) => {
+      await next()
+    }
+
+    addMiddleware('billing', [billingMiddleware])
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      funcInheritedMiddleware: [{ type: 'tag', tag: 'billing:write' }],
+    })
+
+    assert.equal(result.length, 1)
+    assert.equal(result[0], billingMiddleware)
+  })
+
   test('should ignore non-existent tags', () => {
     const middleware: CorePikkuMiddleware = async (services, wire, next) => {
       await next()

package/src/middleware-runner.ts

@@ -7,7 +7,7 @@ import {
   MiddlewareMetadata,
 } from './types/core.types.js'
 import { pikkuState } from './pikku-state.js'
-import { freezeDedupe } from './utils.js'
+import { freezeDedupe, getTagGroups } from './utils.js'
 
 /**
  * Runs a chain of middleware functions in sequence before executing the main function.
@@ -82,9 +82,10 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
  */
 export const addMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
   tag: string,
-  middleware: CorePikkuMiddlewareGroup
+  middleware: CorePikkuMiddlewareGroup,
+  packageName: string | null = null
 ): CorePikkuMiddlewareGroup => {
-  const tagGroups = pikkuState('middleware', 'tagGroup')
+  const tagGroups = pikkuState(packageName, 'middleware', 'tagGroup')
   tagGroups[tag] = middleware
   return middleware
 }
@@ -95,15 +96,13 @@ export const addMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
  * This function looks up middleware that was registered with registerMiddleware.
  * It's used internally by the framework to resolve middleware references in metadata.
  *
- * @param {string} name - The unique name (pikkuFuncName) of the middleware function.
+ * @param {string} name - The unique name (pikkuFuncId) of the middleware function.
  * @returns {CorePikkuMiddleware | undefined} The middleware function, or undefined if not found.
  *
  * @internal
  */
-export const getMiddlewareByName = (
-  name: string
-): CorePikkuMiddleware | undefined => {
-  const middlewareStore = pikkuState('misc', 'middleware')
+const getMiddlewareByName = (name: string): CorePikkuMiddleware | undefined => {
+  const middlewareStore = pikkuState(null, 'misc', 'middleware')
   const middleware = middlewareStore[name]
   return middleware?.[0]
 }
@@ -117,7 +116,9 @@ const middlewareCache: Record<
   channel: {},
   queue: {},
   scheduler: {},
+  trigger: {},
   mcp: {},
+  agent: {},
   cli: {},
   workflow: {},
 }
@@ -152,11 +153,13 @@ export const combineMiddleware = (
     wireMiddleware,
     funcInheritedMiddleware,
     funcMiddleware,
+    packageName = null,
   }: {
     wireInheritedMiddleware?: MiddlewareMetadata[]
     wireMiddleware?: CorePikkuMiddleware[]
     funcInheritedMiddleware?: MiddlewareMetadata[]
     funcMiddleware?: CorePikkuMiddleware[]
+    packageName?: string | null
   } = {}
 ): readonly CorePikkuMiddleware[] => {
   if (middlewareCache[wireType][uid]) {
@@ -170,16 +173,19 @@ export const combineMiddleware = (
     for (const meta of wireInheritedMiddleware) {
       if (meta.type === 'http') {
         // Look up HTTP middleware group from pikkuState
-        const group = pikkuState('middleware', 'httpGroup')[meta.route]
+        const group = pikkuState(packageName, 'middleware', 'httpGroup')[
+          meta.route
+        ]
         if (group) {
           // At runtime, all factories should be resolved to middleware
           resolved.push(...(group as CorePikkuMiddleware[]))
         }
       } else if (meta.type === 'tag') {
-        // Look up tag middleware group from pikkuState
-        const group = pikkuState('middleware', 'tagGroup')[meta.tag]
-        if (group) {
-          // At runtime, all factories should be resolved to middleware
+        const groups = getTagGroups(
+          pikkuState(packageName, 'middleware', 'tagGroup'),
+          meta.tag
+        )
+        for (const group of groups) {
           resolved.push(...(group as CorePikkuMiddleware[]))
         }
       } else if (meta.type === 'wire') {
@@ -201,10 +207,11 @@ export const combineMiddleware = (
   if (funcInheritedMiddleware) {
     for (const meta of funcInheritedMiddleware) {
       if (meta.type === 'tag') {
-        // Look up tag middleware group from pikkuState
-        const group = pikkuState('middleware', 'tagGroup')[meta.tag]
-        if (group) {
-          // At runtime, all factories should be resolved to middleware
+        const groups = getTagGroups(
+          pikkuState(packageName, 'middleware', 'tagGroup'),
+          meta.tag
+        )
+        for (const group of groups) {
           resolved.push(...(group as CorePikkuMiddleware[]))
         }
       }

package/src/permissions.test.ts

@@ -1,18 +1,39 @@
 import { describe, test, beforeEach } from 'node:test'
 import * as assert from 'node:assert'
-import {
-  addPermission,
-  getPermissionsForTags,
-  runPermissions,
-} from './permissions.js'
-import { resetPikkuState } from './pikku-state.js'
+import { addPermission, runPermissions } from './permissions.js'
+import { pikkuState, resetPikkuState } from './pikku-state.js'
 import { CoreServices, CoreUserSession } from './types/core.types.js'
-import { CorePermissionGroup } from './function/functions.types.js'
+import {
+  CorePermissionGroup,
+  CorePikkuPermission,
+} from './function/functions.types.js'
 
 beforeEach(() => {
   resetPikkuState()
 })
 
+// Test helper to get permissions for tags (not exported from core to keep it lean)
+const getPermissionsForTags = (
+  tags?: string[]
+): (CorePermissionGroup | CorePikkuPermission)[] => {
+  if (!tags || tags.length === 0) {
+    return []
+  }
+  const permissionsStore = pikkuState(null, 'permissions', 'tagGroup')
+  const result: (CorePermissionGroup | CorePikkuPermission)[] = []
+  for (const tag of new Set(tags)) {
+    const tagPermissions = permissionsStore[tag]
+    if (tagPermissions) {
+      if (Array.isArray(tagPermissions)) {
+        result.push(...tagPermissions)
+      } else {
+        result.push(tagPermissions)
+      }
+    }
+  }
+  return result
+}
+
 const mockServices: CoreServices = {
   logger: {
     info: () => {},
@@ -61,99 +82,99 @@ describe('addPermission', () => {
     assert.equal(permissions[0], mockPermissionGroup)
   })
 
-  test('should throw error when tag already exists', () => {
-    const mockPermission = async () => true
+  test('should apply parent tag permission to namespaced tag via runPermissions', async () => {
+    const billingPermission = async () => true
 
-    addPermission('duplicateTag', [mockPermission])
+    addPermission('billing', [billingPermission])
 
-    assert.throws(
-      () => {
-        addPermission('duplicateTag', [mockPermission])
-      },
-      {
-        message:
-          "Permissions for tag 'duplicateTag' already exist. Use a different tag or remove the existing permissions first.",
-      }
-    )
+    await runPermissions('rpc', Math.random().toString(), {
+      wireInheritedPermissions: [{ type: 'tag', tag: 'billing:write' }],
+      services: mockServices,
+      wire: {},
+      data: {},
+    })
   })
-})
 
-describe('getPermissionsForTags', () => {
-  test('should return empty array when no tags provided', () => {
-    const permissions = getPermissionsForTags([])
-    assert.deepEqual(permissions, [])
-  })
+  test('should apply both parent and exact tag permissions', async () => {
+    const executionOrder: string[] = []
+    const billingPermission = async () => {
+      executionOrder.push('billing')
+      return true
+    }
+    const billingReadPermission = async () => {
+      executionOrder.push('billing:read')
+      return true
+    }
 
-  test('should return empty array when tags is undefined', () => {
-    const permissions = getPermissionsForTags(undefined)
-    assert.deepEqual(permissions, [])
-  })
+    addPermission('billing', [billingPermission])
+    addPermission('billing:read', [billingReadPermission])
 
-  test('should return permissions for single tag', () => {
-    const mockPermission = async () => true
-    addPermission('singleTestTag', [mockPermission])
+    await runPermissions('rpc', Math.random().toString(), {
+      wireInheritedPermissions: [{ type: 'tag', tag: 'billing:read' }],
+      services: mockServices,
+      wire: {},
+      data: {},
+    })
 
-    const permissions = getPermissionsForTags(['singleTestTag'])
-    assert.equal(permissions.length, 1)
-    assert.equal(permissions[0], mockPermission)
+    assert.deepEqual(executionOrder, ['billing:read'])
   })
 
-  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 resolve multi-level namespace permissions', async () => {
+    const executionOrder: string[] = []
+    const billingPermission = async () => {
+      executionOrder.push('billing')
+      return false
+    }
+    const billingReadPermission = async () => {
+      executionOrder.push('billing:read')
+      return false
+    }
+    const billingReadAdminPermission = async () => {
+      executionOrder.push('billing:read:admin')
+      return true
+    }
 
-  test('should handle array permissions correctly', () => {
-    const mockPermission1 = async () => true
-    const mockPermission2 = async () => false
+    addPermission('billing', [billingPermission])
+    addPermission('billing:read', [billingReadPermission])
+    addPermission('billing:read:admin', [billingReadAdminPermission])
 
-    addPermission('arrayHandleTestTag', [mockPermission1, mockPermission2])
+    await runPermissions('rpc', Math.random().toString(), {
+      wireInheritedPermissions: [{ type: 'tag', tag: 'billing:read:admin' }],
+      services: mockServices,
+      wire: {},
+      data: {},
+    })
 
-    const permissions = getPermissionsForTags(['arrayHandleTestTag'])
-    assert.equal(permissions.length, 2)
-    assert.equal(permissions[0], mockPermission1)
-    assert.equal(permissions[1], mockPermission2)
+    assert.deepEqual(executionOrder, ['billing:read:admin'])
   })
 
-  test('should handle non-array permissions correctly', () => {
-    const mockPermissionGroup: CorePermissionGroup = {
-      permissions: [async () => true],
-    }
+  test('should apply parent tag permission via funcInheritedPermissions', async () => {
+    const billingPermission = async () => true
 
-    addPermission('objectHandleTestTag', mockPermissionGroup)
+    addPermission('billing', [billingPermission])
 
-    const permissions = getPermissionsForTags(['objectHandleTestTag'])
-    assert.equal(permissions.length, 1)
-    assert.equal(permissions[0], mockPermissionGroup)
+    await runPermissions('rpc', Math.random().toString(), {
+      funcInheritedPermissions: [{ type: 'tag', tag: 'billing:delete' }],
+      services: mockServices,
+      wire: {},
+      data: {},
+    })
   })
 
-  test('should deduplicate tags', () => {
+  test('should throw error when tag already exists', () => {
     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])
+    addPermission('duplicateTag', [mockPermission])
 
-    const permissions = getPermissionsForTags(['existingTag', 'nonExistentTag'])
-    assert.equal(permissions.length, 1)
-    assert.equal(permissions[0], mockPermission)
+    assert.throws(
+      () => {
+        addPermission('duplicateTag', [mockPermission])
+      },
+      {
+        message:
+          "Permissions for tag 'duplicateTag' already exist. Use a different tag or remove the existing permissions first.",
+      }
+    )
   })
 })
 
@@ -229,13 +250,8 @@ describe('runPermissions', () => {
       data: {},
     })
 
-    // Order: wireInheritedPermissions (wiringTag) → wirePermissions → funcInheritedPermissions (funcTag) → funcPermissions
-    assert.deepEqual(executionOrder, [
-      'wiringTag',
-      'wiringPermission',
-      'funcTag',
-      'funcPermission',
-    ])
+    // Order: wireInheritedPermissions (wiringTag) only (short-circuit on first passing group)
+    assert.deepEqual(executionOrder, ['wiringTag'])
   })
 
   test('should implement "at least one must pass" logic for tag permissions', async () => {