@pikku/core 0.9.12-next.0 → 0.10.0

package/src/middleware/timeout.ts

@@ -1,17 +1,13 @@
 import { RequestTimeoutError } from '../errors/errors.js'
-import { CorePikkuMiddleware } from '../types/core.types.js'
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 
-export const timeout = (timeout: number) => {
-  const middleware: CorePikkuMiddleware = async (
-    _services,
-    _interaction,
-    next
-  ) => {
-    setTimeout(() => {
-      throw new RequestTimeoutError()
-    }, timeout)
+export const timeout = () =>
+  pikkuMiddlewareFactory<{ timeout: number }>(({ timeout }) =>
+    pikkuMiddleware(async (_services, _interaction, next) => {
+      setTimeout(() => {
+        throw new RequestTimeoutError()
+      }, timeout)
 
-    await next()
-  }
-  return middleware
-}
+      await next()
+    })
+  )

package/src/middleware-runner.ts

@@ -92,31 +92,6 @@ export const addMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
   return middleware
 }
 
-/**
- * Registers a single middleware function by name in the global middleware store.
- *
- * This function is used by CLI-generated code to register middleware functions
- * that can be referenced by name in metadata. It stores middleware in a special
- * namespace to avoid conflicts with tag-based middleware.
- *
- * @param {string} name - The unique name (pikkuFuncName) of the middleware function.
- * @param {CorePikkuMiddleware} middleware - The middleware function to register.
- *
- * @example
- * ```typescript
- * // Called by CLI-generated pikku-middleware.gen.ts
- * registerMiddleware('authMiddleware_src_middleware_ts_10_5', authMiddleware)
- * registerMiddleware('loggingMiddleware_src_middleware_ts_20_10', loggingMiddleware)
- * ```
- */
-export const registerMiddleware = (
-  name: string,
-  middleware: CorePikkuMiddleware
-) => {
-  const middlewareStore = pikkuState('misc', 'middleware')
-  middlewareStore[name] = [middleware]
-}
-
 /**
  * Retrieves a registered middleware function by its name.
  *

package/src/permissions.test.ts

@@ -181,7 +181,7 @@ describe('runPermissions', () => {
     addPermission('wiringTag', [wiringTagPermission])
 
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['wiringTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'wiringTag' }],
       allServices: mockServices,
       data: {},
       session: mockSession,
@@ -205,7 +205,7 @@ describe('runPermissions', () => {
     addPermission('wiringTag', [wiringTagPermission])
     addPermission('funcTag', [funcTagPermission])
 
-    const wiringPermissions: CorePermissionGroup = {
+    const wirePermissions: CorePermissionGroup = {
       permissions: [
         async () => {
           executionOrder.push('wiringPermission')
@@ -224,16 +224,16 @@ describe('runPermissions', () => {
     }
 
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['wiringTag'],
-      wiringPermissions,
-      funcTags: ['funcTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'wiringTag' }],
+      wirePermissions,
+      funcInheritedPermissions: [{ type: 'tag', tag: 'funcTag' }],
       funcPermissions,
       allServices: mockServices,
       data: {},
       session: mockSession,
     })
 
-    // Order: wiringTags → wiringPermissions → funcTags → funcPermissions
+    // Order: wireInheritedPermissions (wiringTag) → wirePermissions → funcInheritedPermissions (funcTag) → funcPermissions
     assert.deepEqual(executionOrder, [
       'wiringTag',
       'wiringPermission',
@@ -250,7 +250,7 @@ describe('runPermissions', () => {
 
     // Should not throw because at least one permission passes
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['atLeastOneTestTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'atLeastOneTestTag' }],
       allServices: mockServices,
       data: {},
       session: mockSession,
@@ -265,7 +265,7 @@ describe('runPermissions', () => {
 
     await assert.rejects(
       runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-        wiringTags: ['allFailTestTag'],
+        wireInheritedPermissions: [{ type: 'tag', tag: 'allFailTestTag' }],
         allServices: mockServices,
         data: {},
         session: mockSession,
@@ -277,13 +277,13 @@ describe('runPermissions', () => {
   })
 
   test('should throw error when wiring permissions fail', async () => {
-    const wiringPermissions: CorePermissionGroup = {
+    const wirePermissions: CorePermissionGroup = {
       permissions: [async () => false],
     }
 
     await assert.rejects(
       runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-        wiringPermissions,
+        wirePermissions,
         allServices: mockServices,
         data: {},
         session: mockSession,
@@ -301,7 +301,7 @@ describe('runPermissions', () => {
 
     await assert.rejects(
       runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-        funcTags: ['funcTag'],
+        funcInheritedPermissions: [{ type: 'tag', tag: 'funcTag' }],
         allServices: mockServices,
         data: {},
         session: mockSession,
@@ -330,7 +330,7 @@ describe('runPermissions', () => {
     )
   })
 
-  test('should stop execution at first failing level', async () => {
+  test('should evaluate all permissions and pass if at least one succeeds', async () => {
     const executionOrder: string[] = []
 
     const failingWiringTagPermission = async () => {
@@ -340,7 +340,7 @@ describe('runPermissions', () => {
 
     addPermission('failingWiringTag', [failingWiringTagPermission])
 
-    const wiringPermissions: CorePermissionGroup = {
+    const wirePermissions: CorePermissionGroup = {
       permissions: [
         async () => {
           executionOrder.push('wiringPermission')
@@ -349,18 +349,17 @@ describe('runPermissions', () => {
       ],
     }
 
-    await assert.rejects(
-      runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-        wiringTags: ['failingWiringTag'],
-        wiringPermissions,
-        allServices: mockServices,
-        data: {},
-        session: mockSession,
-      })
-    )
+    // Should NOT throw because at least one permission (wirePermissions) passes
+    await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
+      wireInheritedPermissions: [{ type: 'tag', tag: 'failingWiringTag' }],
+      wirePermissions,
+      allServices: mockServices,
+      data: {},
+      session: mockSession,
+    })
 
-    // Should only execute wiring tag permissions, not wiring permissions
-    assert.deepEqual(executionOrder, ['wiringTag'])
+    // Both permissions should be evaluated
+    assert.deepEqual(executionOrder, ['wiringTag', 'wiringPermission'])
   })
 
   test('should handle array permissions in tag-based permissions', async () => {
@@ -370,7 +369,7 @@ describe('runPermissions', () => {
 
     // Should not throw because verifyPermissions handles array properly
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['arrayTestTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'arrayTestTag' }],
       allServices: mockServices,
       data: {},
       session: mockSession,
@@ -386,7 +385,7 @@ describe('runPermissions', () => {
 
     // Should not throw because verifyPermissions handles objects properly
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['objectTestTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'objectTestTag' }],
       allServices: mockServices,
       data: {},
       session: mockSession,
@@ -410,7 +409,7 @@ describe('runPermissions', () => {
     addPermission('paramTestTag', [testPermission])
 
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['paramTestTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'paramTestTag' }],
       allServices: mockServices,
       data: testData,
       session: mockSession,

package/src/permissions.ts

@@ -2,6 +2,7 @@ import {
   CoreServices,
   CoreUserSession,
   PikkuWiringTypes,
+  PermissionMetadata,
 } from './types/core.types.js'
 import {
   CorePermissionGroup,
@@ -9,6 +10,7 @@ import {
 } from './function/functions.types.js'
 import { pikkuState } from './pikku-state.js'
 import { ForbiddenError } from './errors/errors.js'
+import { freezeDedupe } from './utils.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.
@@ -51,43 +53,93 @@ export const verifyPermissions = async (
   return false
 }
 
+/**
+ * Registers a single permission function by name in the global permission store.
+ *
+ * This function is used by CLI-generated code to register permission functions
+ * that can be referenced by name in metadata. It stores permissions in a special
+ * namespace to avoid conflicts with tag-based permissions.
+ *
+ * @param {string} name - The unique name (pikkuFuncName) of the permission function.
+ * @param {CorePikkuPermission} permission - The permission function to register.
+ *
+ * @example
+ * ```typescript
+ * // Called by CLI-generated pikku-permissions.gen.ts
+ * registerPermission('adminPermission_src_permissions_ts_10_5', adminPermission)
+ * registerPermission('readPermission_src_permissions_ts_20_10', readPermission)
+ * ```
+ */
+export const registerPermission = (
+  name: string,
+  permission: CorePikkuPermission<any>
+) => {
+  const permissionStore = pikkuState('misc', 'permissions')
+  permissionStore[name] = [permission]
+}
+
+/**
+ * Retrieves a registered permission function by its name.
+ *
+ * This function looks up permissions that was registered with registerPermission.
+ * It's used internally by the framework to resolve permission references in metadata.
+ *
+ * @param {string} name - The unique name (pikkuFuncName) of the permission function.
+ * @returns {CorePikkuPermission | undefined} The permission function, or undefined if not found.
+ *
+ * @internal
+ */
+export const getPermissionByName = (
+  name: string
+): CorePikkuPermission | undefined => {
+  const permissionStore = pikkuState('misc', 'permissions')
+  const permission = permissionStore[name]
+  if (Array.isArray(permission) && permission.length === 1) {
+    return permission[0]
+  }
+  return undefined
+}
+
 /**
  * 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.
  *
+ * For tree-shaking benefits, wrap in a factory function:
+ * `export const x = () => addPermission('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.
+ * @returns {CorePermissionGroup | CorePikkuPermission[]} The permissions (for chaining/wrapping).
  *
  * @example
  * ```typescript
- * // Add admin permissions for admin endpoints
- * addPermission('admin', [adminPermission])
- *
- * // Add authentication permissions for auth endpoints
- * addPermission('auth', [authPermission])
+ * // Recommended: tree-shakeable
+ * export const adminPermissions = () => addPermission('admin', [
+ *   adminPermission,
+ *   rolePermission({ role: 'admin' })
+ * ])
  *
- * // Add read permissions for all API endpoints
- * addPermission('api', [readPermission])
+ * // Also works: no tree-shaking
+ * export const apiPermissions = addPermission('api', [
+ *   readPermission
+ * ])
  * ```
  */
 export const addPermission = (
   tag: string,
   permissions: CorePermissionGroup | CorePikkuPermission[]
-) => {
-  const permissionsStore = pikkuState('misc', 'permissions')
-
-  // Check if tag already exists
-  if (permissionsStore[tag]) {
+): CorePermissionGroup | CorePikkuPermission[] => {
+  const tagGroups = pikkuState('permissions', 'tagGroup')
+  if (tagGroups[tag]) {
     throw new Error(
       `Permissions for tag '${tag}' already exist. Use a different tag or remove the existing permissions first.`
     )
   }
-
-  permissionsStore[tag] = permissions
+  tagGroups[tag] = permissions
+  return permissions
 }
 
 const EMPTY: readonly (CorePermissionGroup | CorePikkuPermission)[] = []
@@ -114,7 +166,7 @@ export const getPermissionsForTags = (
     return EMPTY
   }
 
-  const permissionsStore = pikkuState('misc', 'permissions')
+  const permissionsStore = pikkuState('permissions', 'tagGroup')
   const applicablePermissions: Array<
     CorePermissionGroup | CorePikkuPermission
   > = []
@@ -134,17 +186,9 @@ export const getPermissionsForTags = (
   return applicablePermissions
 }
 
-const permissionCache: Record<
+const combinedPermissionsCache: Record<
   PikkuWiringTypes,
-  Partial<
-    Record<
-      string,
-      {
-        wiringTags: readonly (CorePermissionGroup | CorePikkuPermission)[]
-        funcTags: readonly (CorePermissionGroup | CorePikkuPermission)[]
-      }
-    >
-  >
+  Record<string, readonly (CorePermissionGroup | CorePikkuPermission)[]>
 > = {
   [PikkuWiringTypes.http]: {},
   [PikkuWiringTypes.rpc]: {},
@@ -156,111 +200,178 @@ const permissionCache: Record<
 }
 
 /**
- * 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
+ * Combines wiring-specific permissions with function-level permissions.
+ *
+ * This function resolves permission metadata into actual permission functions and combines them.
+ * It filters out wire permissions without tags from inheritedPermissions to avoid duplication
+ * (those are passed separately as wirePermissions).
+ *
+ * @param {object} options - Configuration object for combining permissions.
+ * @param {PermissionMetadata[] | undefined} options.wireInheritedPermissions - Metadata from wiring (HTTP + tags + wire with tags).
+ * @param {CorePermissionGroup | CorePikkuPermission[] | undefined} options.wirePermissions - Inline wire permissions.
+ * @param {PermissionMetadata[] | undefined} options.funcInheritedPermissions - Function permissions metadata (only tags).
+ * @param {CorePermissionGroup | CorePikkuPermission[] | undefined} options.funcPermissions - Inline function permissions.
+ * @returns {(CorePermissionGroup | CorePikkuPermission)[]} Combined array of resolved permissions.
+ *
+ * @example
+ * ```typescript
+ * const combined = combinePermissions(wireType, wireId, {
+ *   wireInheritedPermissions: meta.permissions,
+ *   wirePermissions: inlinePermissions,
+ *   funcInheritedPermissions: funcMeta.permissions,
+ *   funcPermissions: funcConfig.permissions
+ * })
+ * ```
  */
-export const runPermissions = async (
+export const combinePermissions = (
   wireType: PikkuWiringTypes,
   uid: string,
   {
-    wiringTags,
-    wiringPermissions,
-    funcTags,
+    wireInheritedPermissions,
+    wirePermissions,
+    funcInheritedPermissions,
     funcPermissions,
-    allServices,
-    data,
-    session,
   }: {
-    wiringTags?: string[]
-    wiringPermissions?: CorePermissionGroup
-    funcTags?: string[]
-    funcPermissions?: CorePermissionGroup
-    allServices: CoreServices
-    data: any
-    session?: CoreUserSession
+    wireInheritedPermissions?: PermissionMetadata[]
+    wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
+    funcInheritedPermissions?: PermissionMetadata[]
+    funcPermissions?: CorePermissionGroup | CorePikkuPermission[]
+  } = {}
+): readonly (CorePermissionGroup | CorePikkuPermission)[] => {
+  if (combinedPermissionsCache[wireType][uid]) {
+    return combinedPermissionsCache[wireType][uid]
   }
-) => {
-  let cachedPermission = permissionCache[wireType][uid]
-  if (!cachedPermission) {
-    cachedPermission = {
-      wiringTags: getPermissionsForTags(wiringTags),
-      funcTags: getPermissionsForTags(funcTags),
+
+  const resolved: (CorePermissionGroup | CorePikkuPermission)[] = []
+
+  // 1. Resolve wire inherited permissions (HTTP + tag groups + individual wire permissions)
+  if (wireInheritedPermissions) {
+    for (const meta of wireInheritedPermissions) {
+      if (meta.type === 'http') {
+        // Look up HTTP permission group from pikkuState
+        const group = pikkuState('permissions', 'httpGroup')[meta.route]
+        if (group) {
+          if (Array.isArray(group)) {
+            resolved.push(...group)
+          } else {
+            resolved.push(group)
+          }
+        }
+      } else if (meta.type === 'tag') {
+        // Look up tag permission group from pikkuState
+        const group = pikkuState('permissions', 'tagGroup')[meta.tag]
+        if (group) {
+          if (Array.isArray(group)) {
+            resolved.push(...group)
+          } else {
+            resolved.push(group)
+          }
+        }
+      } else if (meta.type === 'wire') {
+        // Individual wire permission (exported, not inline)
+        const permission = getPermissionByName(meta.name)
+        if (permission) {
+          resolved.push(permission)
+        }
+      }
     }
-    permissionCache[wireType][uid] = cachedPermission
   }
-  let permissioned = true
 
-  // 1. Wiring tag permissions - at least one must pass if any exist
-  const wiringTaggedPermissions = cachedPermission.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
-      }
+  // 2. Add inline wire permissions
+  if (wirePermissions) {
+    if (Array.isArray(wirePermissions)) {
+      resolved.push(...wirePermissions)
+    } else {
+      resolved.push(wirePermissions)
     }
-    if (!permissioned) {
-      allServices.logger.debug('Permission denied - wiring tag permissions')
-      throw new ForbiddenError('Permission denied')
+  }
+
+  // 3. Resolve function inherited permissions (only tags, wire permissions already handled)
+  if (funcInheritedPermissions) {
+    for (const meta of funcInheritedPermissions) {
+      if (meta.type === 'tag') {
+        // Look up tag permission group from pikkuState
+        const group = pikkuState('permissions', 'tagGroup')[meta.tag]
+        if (group) {
+          if (Array.isArray(group)) {
+            resolved.push(...group)
+          } else {
+            resolved.push(group)
+          }
+        }
+      }
+      // Note: wire permissions are already handled in wireInheritedPermissions
     }
   }
 
-  // 2. Wiring permissions - must pass if defined
-  if (wiringPermissions) {
-    permissioned = await verifyPermissions(
-      wiringPermissions,
-      allServices,
-      data,
-      session
-    )
-    if (!permissioned) {
-      allServices.logger.debug('Permission denied - wiring permissions')
-      throw new ForbiddenError('Permission denied')
+  // 4. Add inline function permissions
+  if (funcPermissions) {
+    if (Array.isArray(funcPermissions)) {
+      resolved.push(...funcPermissions)
+    } else {
+      resolved.push(funcPermissions)
     }
   }
 
-  // 3. Function tag permissions - at least one must pass if any exist
-  const funcTaggedPermissions = cachedPermission.funcTags
-  if (funcTaggedPermissions.length > 0) {
-    permissioned = false // Start false, need at least one to pass
-    for (const permissions of funcTaggedPermissions) {
+  // Deduplicate and freeze
+  combinedPermissionsCache[wireType][uid] = freezeDedupe(resolved) as readonly (
+    | CorePermissionGroup
+    | CorePikkuPermission
+  )[]
+
+  return combinedPermissionsCache[wireType][uid]
+}
+
+/**
+ * Runs permission checks using combined permissions from all sources.
+ * Combines permissions from wire and function levels, then validates them.
+ */
+export const runPermissions = async (
+  wireType: PikkuWiringTypes,
+  uid: string,
+  {
+    wireInheritedPermissions,
+    wirePermissions,
+    funcInheritedPermissions,
+    funcPermissions,
+    allServices,
+    data,
+    session,
+  }: {
+    wireInheritedPermissions?: PermissionMetadata[]
+    wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
+    funcInheritedPermissions?: PermissionMetadata[]
+    funcPermissions?: CorePermissionGroup | CorePikkuPermission[]
+    allServices: CoreServices
+    data: any
+    session?: CoreUserSession
+  }
+) => {
+  // Combine all permissions: wireInheritedPermissions → wirePermissions → funcInheritedPermissions → funcPermissions
+  const allPermissions = combinePermissions(wireType, uid, {
+    wireInheritedPermissions,
+    wirePermissions,
+    funcInheritedPermissions,
+    funcPermissions,
+  })
+
+  // Check all combined permissions - at least one must pass if any exist
+  if (allPermissions.length > 0) {
+    let permissioned = false
+    for (const permission of allPermissions) {
       const result = await verifyPermissions(
-        typeof permissions === 'function' ? { permissions } : permissions,
+        typeof permission === 'function' ? { permission } : permission,
         allServices,
         data,
         session
       )
       if (result) {
         permissioned = true
-        break // At least one passed, we're good at this level
+        // Continue executing all permissions (don't break early)
       }
     }
     if (!permissioned) {
-      allServices.logger.debug('Permission denied - function tag permissions')
-      throw new ForbiddenError('Permission denied')
-    }
-  }
-
-  // 4. Function permissions - must pass if defined
-  if (funcPermissions) {
-    permissioned = await verifyPermissions(
-      funcPermissions,
-      allServices,
-      data,
-      session
-    )
-    if (!permissioned) {
-      allServices.logger.debug('Permission denied - function permissions')
+      allServices.logger.debug('Permission denied - combined permissions')
       throw new ForbiddenError('Permission denied')
     }
   }