@pikku/core 0.12.4 → 0.12.6

package/src/permissions.ts

@@ -0,0 +1,327 @@
+import type {
+  CoreServices,
+  PikkuWiringTypes,
+  PermissionMetadata,
+  PikkuWire,
+} from './types/core.types.js'
+import type {
+  CorePermissionGroup,
+  CorePikkuPermission,
+} from './function/functions.types.js'
+import { pikkuState } from './pikku-state.js'
+import { ForbiddenError } from './errors/errors.js'
+import { freezeDedupe, getTagGroups } 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.
+ * @param services - The core services required for permission validation.
+ * @param data - The data to be used in the permission validation functions.
+ * @param wire - The wire object containing request/response context and session.
+ * @returns A promise that resolves to void.
+ */
+const verifyPermissions = async <Out = any>(
+  permissions: CorePermissionGroup,
+  services: CoreServices,
+  data: any,
+  wire: PikkuWire<any, never, any, never, never, never>
+): Promise<boolean> => {
+  if (!permissions) {
+    return true
+  }
+
+  let valid = false
+  const permissionGroups = Object.values(permissions)
+  if (permissionGroups.length === 0) {
+    return true
+  }
+
+  for (const funcs of permissionGroups) {
+    if (funcs instanceof Array) {
+      const permissioned = await Promise.all(
+        funcs.map((func) => func(services, data, wire))
+      )
+      if (permissioned.every((result) => result)) {
+        valid = true
+      }
+    } else {
+      valid = await funcs(services, data, wire as any)
+    }
+    if (valid) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * 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 (pikkuFuncId) of the permission function.
+ * @returns {CorePikkuPermission | undefined} The permission function, or undefined if not found.
+ *
+ * @internal
+ */
+const getPermissionByName = (name: string): CorePikkuPermission | undefined => {
+  const permissionStore = pikkuState(null, '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.
+ *
+ * @returns {CorePermissionGroup | CorePikkuPermission[]} The permissions (for chaining/wrapping).
+ *
+ * @example
+ * ```typescript
+ * // Recommended: tree-shakeable
+ * export const adminPermissions = () => addPermission('admin', [
+ *   adminPermission,
+ *   rolePermission({ role: 'admin' })
+ * ])
+ *
+ * // Also works: no tree-shaking
+ * export const apiPermissions = addPermission('api', [
+ *   readPermission
+ * ])
+ * ```
+ */
+export const addPermission = (
+  tag: string,
+  permissions: CorePermissionGroup | CorePikkuPermission[],
+  packageName: string | null = null
+): CorePermissionGroup | CorePikkuPermission[] => {
+  const tagGroups = pikkuState(packageName, 'permissions', 'tagGroup')
+  if (tagGroups[tag]) {
+    throw new Error(
+      `Permissions for tag '${tag}' already exist. Use a different tag or remove the existing permissions first.`
+    )
+  }
+  tagGroups[tag] = permissions
+  return permissions
+}
+
+const combinedPermissionsCache: Record<
+  PikkuWiringTypes,
+  Record<string, readonly (CorePermissionGroup | CorePikkuPermission)[]>
+> = {
+  http: {},
+  rpc: {},
+  channel: {},
+  queue: {},
+  scheduler: {},
+  trigger: {},
+  mcp: {},
+  agent: {},
+  cli: {},
+  workflow: {},
+  gateway: {},
+}
+
+export const clearPermissionsCache = () => {
+  for (const key of Object.keys(
+    combinedPermissionsCache
+  ) as PikkuWiringTypes[]) {
+    combinedPermissionsCache[key] = {}
+  }
+}
+
+/**
+ * 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
+ * })
+ * ```
+ */
+const combinePermissions = (
+  wireType: PikkuWiringTypes,
+  uid: string,
+  {
+    wireInheritedPermissions,
+    wirePermissions,
+    funcInheritedPermissions,
+    funcPermissions,
+    packageName = null,
+  }: {
+    wireInheritedPermissions?: PermissionMetadata[]
+    wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
+    funcInheritedPermissions?: PermissionMetadata[]
+    funcPermissions?: CorePermissionGroup | CorePikkuPermission[]
+    packageName?: string | null
+  } = {}
+): readonly (CorePermissionGroup | CorePikkuPermission)[] => {
+  if (combinedPermissionsCache[wireType][uid]) {
+    return combinedPermissionsCache[wireType][uid]
+  }
+
+  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(packageName, 'permissions', 'httpGroup')[
+          meta.route
+        ]
+        if (group) {
+          if (Array.isArray(group)) {
+            resolved.push(...group)
+          } else {
+            resolved.push(group)
+          }
+        }
+      } else if (meta.type === 'tag') {
+        const groups = getTagGroups(
+          pikkuState(packageName, 'permissions', 'tagGroup'),
+          meta.tag
+        )
+        for (const group of groups) {
+          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)
+        }
+      }
+    }
+  }
+
+  // 2. Add inline wire permissions
+  if (wirePermissions) {
+    if (Array.isArray(wirePermissions)) {
+      resolved.push(...wirePermissions)
+    } else {
+      resolved.push(wirePermissions)
+    }
+  }
+
+  // 3. Resolve function inherited permissions (only tags, wire permissions already handled)
+  if (funcInheritedPermissions) {
+    for (const meta of funcInheritedPermissions) {
+      if (meta.type === 'tag') {
+        const groups = getTagGroups(
+          pikkuState(packageName, 'permissions', 'tagGroup'),
+          meta.tag
+        )
+        for (const group of groups) {
+          if (Array.isArray(group)) {
+            resolved.push(...group)
+          } else {
+            resolved.push(group)
+          }
+        }
+      }
+      // Note: wire permissions are already handled in wireInheritedPermissions
+    }
+  }
+
+  // 4. Add inline function permissions
+  if (funcPermissions) {
+    if (Array.isArray(funcPermissions)) {
+      resolved.push(...funcPermissions)
+    } else {
+      resolved.push(funcPermissions)
+    }
+  }
+
+  // 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,
+    services,
+    wire,
+    data,
+    packageName = null,
+  }: {
+    wireInheritedPermissions?: PermissionMetadata[]
+    wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
+    funcInheritedPermissions?: PermissionMetadata[]
+    funcPermissions?: CorePermissionGroup | CorePikkuPermission[]
+    services: CoreServices
+    wire: PikkuWire<any, never, any, never, never, never>
+    data: any
+    packageName?: string | null
+  }
+) => {
+  // Combine all permissions: wireInheritedPermissions → wirePermissions → funcInheritedPermissions → funcPermissions
+  const allPermissions = combinePermissions(wireType, uid, {
+    wireInheritedPermissions,
+    wirePermissions,
+    funcInheritedPermissions,
+    funcPermissions,
+    packageName,
+  })
+
+  // Check all combined permissions - at least one must pass if any exist
+  if (allPermissions.length > 0) {
+    for (const permission of allPermissions) {
+      const result = await verifyPermissions(
+        typeof permission === 'function' ? { permission } : permission,
+        services,
+        data,
+        wire
+      )
+      if (result) {
+        return
+      }
+    }
+    services.logger.debug('Permission denied - combined permissions')
+    throw new ForbiddenError('Permission denied')
+  }
+}

package/src/pikku-request.ts

@@ -0,0 +1,23 @@
+/**
+ * Simplest class to represent a pikku request.
+ * @template In - The type of the request body.
+ * @group RequestResponse
+ */
+export abstract class PikkuRequest<In = any> {
+  #data: In | undefined
+
+  constructor(data: In) {
+    this.#data = data
+  }
+
+  /**
+   * Retrieves the data
+   * @returns A promise that resolves to an object containing the combined data.
+   */
+  public async data(): Promise<In> {
+    if (!this.#data) {
+      throw new Error('Data not found')
+    }
+    return this.#data
+  }
+}

package/src/pikku-response.ts

@@ -0,0 +1,5 @@
+/**
+ * Abstract class representing a pikku response.
+ * @group RequestResponse
+ */
+export abstract class PikkuResponse {}

package/src/pikku-state.test.ts

@@ -0,0 +1,224 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import {
+  pikkuState,
+  resetPikkuState,
+  initializePikkuState,
+  getAllPackageStates,
+  getSingletonServices,
+  getCreateWireServices,
+  getPikkuMetaDir,
+  addPackageServiceFactories,
+} from './pikku-state.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+describe('pikkuState', () => {
+  test('should get state for main package with null name', () => {
+    const functions = pikkuState(null, 'function', 'functions')
+    assert.ok(functions instanceof Map)
+  })
+
+  test('should get state for main package with __main__ name', () => {
+    const functions = pikkuState('__main__', 'function', 'functions')
+    assert.ok(functions instanceof Map)
+  })
+
+  test('should set and get state values', () => {
+    const testMeta = { key: 'value' }
+    pikkuState(null, 'function', 'meta', testMeta as any)
+    const result = pikkuState(null, 'function', 'meta')
+    assert.deepStrictEqual(result, testMeta)
+  })
+
+  test('should auto-initialize package state on first access', () => {
+    const states = getAllPackageStates()
+    assert.ok(!states.has('@test/package'))
+
+    pikkuState('@test/package', 'function', 'functions')
+
+    assert.ok(states.has('@test/package'))
+  })
+
+  test('should isolate state between packages', () => {
+    pikkuState(null, 'function', 'meta', { main: true } as any)
+    pikkuState('@addon/pkg', 'function', 'meta', { addon: true } as any)
+
+    assert.deepStrictEqual(pikkuState(null, 'function', 'meta'), { main: true })
+    assert.deepStrictEqual(pikkuState('@addon/pkg', 'function', 'meta'), {
+      addon: true,
+    })
+  })
+
+  test('should return correct state types', () => {
+    const httpRoutes = pikkuState(null, 'http', 'routes')
+    assert.ok(httpRoutes instanceof Map)
+
+    const schemas = pikkuState(null, 'misc', 'schemas')
+    assert.ok(schemas instanceof Map)
+
+    const errors = pikkuState(null, 'misc', 'errors')
+    assert.ok(errors instanceof Map)
+  })
+})
+
+describe('getAllPackageStates', () => {
+  test('should return a Map', () => {
+    const states = getAllPackageStates()
+    assert.ok(states instanceof Map)
+  })
+
+  test('should contain __main__ after reset', () => {
+    const states = getAllPackageStates()
+    assert.ok(states.has('__main__'))
+  })
+
+  test('should return same reference on multiple calls', () => {
+    const states1 = getAllPackageStates()
+    const states2 = getAllPackageStates()
+    assert.strictEqual(states1, states2)
+  })
+})
+
+describe('initializePikkuState', () => {
+  test('should create a new package state', () => {
+    const states = getAllPackageStates()
+    assert.ok(!states.has('@new/package'))
+
+    initializePikkuState('@new/package')
+
+    assert.ok(states.has('@new/package'))
+  })
+
+  test('should not overwrite existing package state', () => {
+    pikkuState('@existing/pkg', 'function', 'meta', { test: true } as any)
+
+    initializePikkuState('@existing/pkg')
+
+    const meta = pikkuState('@existing/pkg', 'function', 'meta')
+    assert.deepStrictEqual(meta, { test: true })
+  })
+})
+
+describe('resetPikkuState', () => {
+  test('should clear all package states', () => {
+    initializePikkuState('@addon/one')
+    initializePikkuState('@addon/two')
+    assert.ok(getAllPackageStates().has('@addon/one'))
+
+    resetPikkuState()
+
+    assert.ok(!getAllPackageStates().has('@addon/one'))
+    assert.ok(!getAllPackageStates().has('@addon/two'))
+  })
+
+  test('should preserve errors map from __main__', () => {
+    const errors = pikkuState(null, 'misc', 'errors')
+    errors.set('TestError', { status: 400, message: 'test' })
+
+    resetPikkuState()
+
+    const restoredErrors = pikkuState(null, 'misc', 'errors')
+    assert.strictEqual(restoredErrors.get('TestError')?.message, 'test')
+  })
+
+  test('should re-initialize __main__ package', () => {
+    resetPikkuState()
+
+    const states = getAllPackageStates()
+    assert.ok(states.has('__main__'))
+    assert.ok(pikkuState(null, 'function', 'functions') instanceof Map)
+  })
+
+  test('should create fresh state objects after reset', () => {
+    const functionsBefore = pikkuState(null, 'function', 'functions')
+    functionsBefore.set('testFunc', {} as any)
+
+    resetPikkuState()
+
+    const functionsAfter = pikkuState(null, 'function', 'functions')
+    assert.strictEqual(functionsAfter.size, 0)
+  })
+})
+
+describe('getSingletonServices', () => {
+  test('should throw when singleton services not initialized', () => {
+    assert.throws(() => getSingletonServices(), {
+      message: 'Singleton services not initialized',
+    })
+  })
+
+  test('should return services when initialized', () => {
+    const mockServices = { logger: { info: () => {} } }
+    pikkuState(null, 'package', 'singletonServices', mockServices as any)
+
+    const result = getSingletonServices()
+    assert.strictEqual(result, mockServices)
+  })
+})
+
+describe('getCreateWireServices', () => {
+  test('should return undefined when no factories set', () => {
+    const result = getCreateWireServices()
+    assert.strictEqual(result, undefined)
+  })
+
+  test('should return createWireServices when factories set', () => {
+    const mockCreateWire = async () => ({})
+    pikkuState(null, 'package', 'factories', {
+      createWireServices: mockCreateWire,
+    } as any)
+
+    const result = getCreateWireServices()
+    assert.strictEqual(result, mockCreateWire)
+  })
+})
+
+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 = {
+      createSingletonServices: async () => ({}),
+      createWireServices: async () => ({}),
+    }
+
+    addPackageServiceFactories('@addon/pkg', mockFactories as any)
+
+    const result = pikkuState('@addon/pkg', 'package', 'factories')
+    assert.strictEqual(result, mockFactories)
+  })
+
+  test('should not affect main package factories', () => {
+    const addonFactories = { createSingletonServices: async () => ({}) }
+    addPackageServiceFactories('@addon/pkg', addonFactories as any)
+
+    const mainFactories = pikkuState(null, 'package', 'factories')
+    assert.strictEqual(mainFactories, null)
+  })
+})