@pikku/core 0.12.2 → 0.12.4

package/src/permissions.ts

@@ -1,319 +0,0 @@
-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: {},
-}
-
-/**
- * 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

@@ -1,23 +0,0 @@
-/**
- * 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

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

package/src/pikku-state.test.ts

@@ -1,224 +0,0 @@
-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)
-  })
-})