@pikku/core 0.12.107 → 0.12.112

package/src/permissions.ts

@@ -1,217 +0,0 @@
-import type {
-  CoreServices,
-  CoreUserSession,
-  PikkuWire,
-} from './types/core.types.js'
-import type { PikkuRPC } from './wirings/rpc/rpc-types.js'
-
-/**
- * The wire a permission function sees. `Out = never` denies it `channel.send`.
- *
- * knowledge: decisions/security/a-permission-gets-a-wire-it-cannot-reply-on.md
- */
-export type PermissionWire = PikkuWire<
-  any,
-  never,
-  false,
-  any,
-  PikkuRPC,
-  never,
-  never
->
-import type {
-  AuthBranded,
-  CorePermissionGroup,
-  CorePikkuPermission,
-} from './function/functions.types.js'
-import { pikkuState } from './pikku-state.js'
-import { ForbiddenError } from './errors/errors.js'
-
-const verifyPermissions = async (
-  permissions: CorePermissionGroup,
-  services: CoreServices,
-  data: any,
-  wire: PermissionWire
-): Promise<boolean> => {
-  if (!permissions) {
-    return true
-  }
-
-  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)) {
-        return true
-      }
-    } else {
-      if (await funcs(services, data, wire)) {
-        return true
-      }
-    }
-  }
-  return false
-}
-
-const globalPermissionsCache: Record<
-  string,
-  readonly (CorePermissionGroup | CorePikkuPermission)[]
-> = {}
-
-export const clearPermissionsCache = () => {
-  for (const key of Object.keys(globalPermissionsCache)) {
-    delete globalPermissionsCache[key]
-  }
-}
-
-export const addGlobalPermission = (
-  permissions: CorePermissionGroup | CorePikkuPermission[],
-  packageName: string | null = null
-): CorePermissionGroup | CorePikkuPermission[] => {
-  const state = pikkuState(packageName, 'permissions', 'global') as unknown as (
-    CorePermissionGroup | CorePikkuPermission
-  )[]
-  if (Array.isArray(permissions)) {
-    state.push(...(permissions as CorePikkuPermission[]))
-  } else {
-    state.push(permissions)
-  }
-  clearPermissionsCache()
-  return permissions
-}
-
-const bucket = (
-  packageName: string | null
-): (CorePermissionGroup | CorePikkuPermission)[] =>
-  (pikkuState(packageName, 'permissions', 'global') as unknown as (
-    CorePermissionGroup | CorePikkuPermission
-  )[]) ?? []
-
-/**
- * Global permissions in effect for a function, root ones first.
- *
- * A function that belongs to a package reads *both* buckets, not just its own.
- * The generated `addGlobalPermission` wrapper always registers under the root
- * (`null`) package — it takes no package argument — so resolving the package
- * bucket alone meant an application's "every request needs a signed-in user"
- * rule silently stopped at the addon boundary, and the bucket the addon's
- * functions did read was one no host could write to. Both directions of that
- * are wrong, and the safe union is to apply everything: globals are an AND
- * gate, so adding the root ones can only ever tighten.
- *
- * knowledge: decisions/security/global-permissions-and-function-permissions-are-independent-gates.md
- */
-const resolveGlobalPermissions = (
-  packageName: string | null
-): readonly (CorePermissionGroup | CorePikkuPermission)[] => {
-  const key = packageName ?? ''
-  const cached = globalPermissionsCache[key]
-  if (cached) {
-    return cached
-  }
-  const resolved = packageName
-    ? [...bucket(null), ...bucket(packageName)]
-    : [...bucket(null)]
-  globalPermissionsCache[key] = resolved
-  return resolved
-}
-
-const asGroup = (
-  entry: CorePermissionGroup | CorePikkuPermission
-): CorePermissionGroup =>
-  typeof entry === 'function' ? { permission: entry } : entry
-
-export const runPermissions = async ({
-  funcPermissions,
-  services,
-  wire,
-  data,
-  packageName = null,
-  label = 'function',
-}: {
-  funcPermissions?: CorePermissionGroup | CorePikkuPermission[]
-  services: CoreServices
-  wire: PermissionWire
-  data: any
-  packageName?: string | null
-  /** What the non-global gate is called in debug logs, e.g. 'function', 'agent'. */
-  label?: string
-}) => {
-  const globals = resolveGlobalPermissions(packageName)
-  for (const entry of globals) {
-    if (!(await verifyPermissions(asGroup(entry), services, data, wire))) {
-      services.logger.debug('Permission denied - global permission')
-      throw new ForbiddenError('Permission denied')
-    }
-  }
-
-  if (funcPermissions) {
-    const group = Array.isArray(funcPermissions)
-      ? { permissions: funcPermissions }
-      : funcPermissions
-    if (group && Object.keys(group).length > 0) {
-      if (!(await verifyPermissions(group, services, data, wire))) {
-        services.logger.debug(`Permission denied - ${label} permission`)
-        throw new ForbiddenError('Permission denied')
-      }
-    }
-  }
-}
-
-export const checkAuthPermissions = async (
-  /** Must be the live permission group from the func/agent config, never metadata. */
-  funcPermissions: CorePermissionGroup | undefined,
-  session: CoreUserSession,
-  services: CoreServices,
-  packageName: string | null = null
-): Promise<boolean> => {
-  const wire = { session } as unknown as PikkuWire<
-    any,
-    never,
-    any,
-    CoreUserSession,
-    never,
-    never
-  >
-
-  const authPerms: CorePikkuPermission<any, any, any>[] = []
-
-  const collect = (perm: CorePermissionGroup | CorePikkuPermission) => {
-    if (typeof perm === 'function') {
-      if ((perm as AuthBranded).__pikkuAuth) {
-        authPerms.push(perm)
-      }
-    } else if (perm && typeof perm === 'object') {
-      for (const funcs of Object.values(perm)) {
-        const arr = Array.isArray(funcs) ? funcs : [funcs]
-        for (const fn of arr) {
-          if (typeof fn === 'function' && (fn as AuthBranded).__pikkuAuth) {
-            authPerms.push(fn)
-          }
-        }
-      }
-    }
-  }
-
-  for (const entry of resolveGlobalPermissions(packageName)) {
-    collect(entry)
-  }
-
-  if (funcPermissions) {
-    collect(funcPermissions)
-  }
-
-  if (authPerms.length === 0) return true
-
-  for (const perm of authPerms) {
-    const result = await perm(services, null, wire)
-    if (result) return true
-  }
-  return false
-}

package/src/pikku-state.test.ts

@@ -1,198 +0,0 @@
-import { describe, test, beforeEach } from 'node:test'
-import assert from 'node:assert'
-import {
-  pikkuState,
-  resetPikkuState,
-  initializePikkuState,
-  getAllPackageStates,
-  getSingletonServices,
-  getCreateWireServices,
-  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('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)
-  })
-})

package/src/pikku-state.ts

@@ -1,206 +0,0 @@
-import type { PikkuPackageState } from './types/state.types.js'
-import type {
-  CoreSingletonServices,
-  CreateWireServices,
-} from './types/core.types.js'
-import type { HTTPWiringsMeta } from './wirings/http/http.types.js'
-import type {
-  MCPResourceMeta,
-  MCPToolMeta,
-  MCPPromptMeta,
-} from './wirings/mcp/mcp.types.js'
-import type { AgentsMeta } from './wirings/agent/agent.types.js'
-import type { ScorerMeta } from './wirings/agent-scorer/agent-scorer.types.js'
-import type { GatewaysMeta } from './wirings/gateway/gateway.types.js'
-import type { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
-import type { TriggerMeta } from './wirings/trigger/trigger.types.js'
-
-const PIKKU_STATE_KEY = Symbol.for('@pikku/core/state')
-
-/**
- * State is parked on `globalThis` under a registered symbol so separate copies
- * of @pikku/core in one process share it. Typed once here rather than at each
- * access.
- */
-const stateHost = globalThis as unknown as {
-  [key: symbol]: Map<string, PikkuPackageState> | undefined
-}
-
-export const getAllPackageStates = (): Map<string, PikkuPackageState> => {
-  let states = stateHost[PIKKU_STATE_KEY]
-  if (!states) {
-    states = new Map<string, PikkuPackageState>()
-    stateHost[PIKKU_STATE_KEY] = states
-  }
-  return states
-}
-
-export const pikkuState = <
-  Type extends keyof PikkuPackageState,
-  Content extends keyof PikkuPackageState[Type],
->(
-  packageName: string | null,
-  type: Type,
-  content: Content,
-  value?: PikkuPackageState[Type][Content]
-): PikkuPackageState[Type][Content] => {
-  const resolvedPackageName = packageName ?? '__main__'
-
-  if (!getAllPackageStates().has(resolvedPackageName)) {
-    initializePikkuState(resolvedPackageName)
-  }
-
-  const packageState = getAllPackageStates().get(resolvedPackageName)!
-
-  if (value !== undefined) {
-    packageState[type][content] = value
-  }
-
-  return packageState[type][content]
-}
-
-const createEmptyPackageState = (): PikkuPackageState => ({
-  function: {
-    meta: {},
-    functions: new Map(),
-  },
-  rpc: {
-    meta: {},
-    files: new Map(),
-  },
-  addons: {
-    packages: new Map(),
-  },
-  http: {
-    middleware: new Map(),
-    permissions: new Map(),
-    routes: new Map(),
-    meta: {
-      post: {},
-      get: {},
-      delete: {},
-      patch: {},
-      head: {},
-      put: {},
-      options: {},
-    } as HTTPWiringsMeta,
-  },
-  channel: {
-    channels: new Map(),
-    meta: {},
-  },
-  scheduler: {
-    tasks: new Map(),
-    meta: [] as unknown as ScheduledTasksMeta,
-  },
-  queue: {
-    registrations: new Map(),
-    meta: {},
-  },
-  workflows: {
-    registrations: new Map(),
-    features: new Map(),
-    meta: {},
-  },
-  trigger: {
-    functions: new Map(),
-    triggers: new Map(),
-    triggerSources: new Map(),
-    meta: {} as TriggerMeta,
-    sourceMeta: {},
-  },
-  mcp: {
-    resources: new Map(),
-    resourcesMeta: {} as MCPResourceMeta,
-    toolsMeta: {} as MCPToolMeta,
-    prompts: new Map(),
-    promptsMeta: {} as MCPPromptMeta,
-  },
-  agent: {
-    agents: new Map(),
-    agentsMeta: {} as AgentsMeta,
-    scorers: new Map(),
-    scorersMeta: {} as ScorerMeta,
-    modelAliases: {},
-  },
-  gateway: {
-    gateways: new Map(),
-    meta: {} as GatewaysMeta,
-  },
-  cli: {
-    meta: { programs: {}, renderers: {} },
-    programs: {},
-  },
-  middleware: {
-    tagGroup: {},
-    httpGroup: {},
-    global: [],
-  },
-  channelMiddleware: {
-    tagGroup: {},
-  },
-  permissions: {
-    global: [],
-  },
-  misc: {
-    errors: new Map(),
-    schemas: new Map(),
-    middleware: {},
-    channelMiddleware: {},
-    permissions: {},
-  },
-  package: {
-    factories: null,
-    singletonServices: null,
-    authFactory: null,
-    credentialsMeta: null,
-    requiredParentServices: null,
-    declaredSecrets: null,
-  },
-})
-
-export const initializePikkuState = (packageName: string): void => {
-  if (!getAllPackageStates().has(packageName)) {
-    getAllPackageStates().set(packageName, createEmptyPackageState())
-  }
-}
-
-export const resetPikkuState = () => {
-  // Error definitions come from module-import side effects that never re-run.
-  const existingErrors = getAllPackageStates().get('__main__')?.misc.errors
-
-  stateHost[PIKKU_STATE_KEY] = new Map<string, PikkuPackageState>()
-  initializePikkuState('__main__')
-
-  if (existingErrors) {
-    const mainState = getAllPackageStates().get('__main__')!
-    mainState.misc.errors = existingErrors
-  }
-}
-
-if (!getAllPackageStates().has('__main__')) {
-  resetPikkuState()
-}
-
-export const getSingletonServices = (): CoreSingletonServices => {
-  const services = pikkuState(null, 'package', 'singletonServices')
-  if (!services) throw new Error('Singleton services not initialized')
-  return services
-}
-
-export const setSingletonServices = (services: CoreSingletonServices): void => {
-  pikkuState(null, 'package', 'singletonServices', services)
-}
-
-export const getCreateWireServices = (): CreateWireServices | undefined => {
-  return pikkuState(null, 'package', 'factories')?.createWireServices
-}
-
-export const addPackageServiceFactories = (
-  packageName: string,
-  factories: NonNullable<PikkuPackageState['package']['factories']>
-): void => {
-  pikkuState(packageName, 'package', 'factories', factories)
-}
-
-export type { PikkuPackageState } from './types/state.types.js'