@pikku/core 0.12.63 → 0.12.66

package/src/function/function-runner.ts

@@ -13,21 +13,16 @@ import type {
   PikkuWire,
   PikkuRawWire,
   MiddlewareMetadata,
-  PermissionMetadata,
   CoreSingletonServices,
   CreateWireServices,
-  CoreConfig,
 } from '../types/core.types.js'
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js'
-import type {
-  CorePermissionGroup,
-  CorePikkuFunctionConfig,
-  CorePikkuPermission,
-} from './functions.types.js'
+import type { CorePikkuFunctionConfig } from './functions.types.js'
 import { parseVersionedId } from '../version.js'
 import type { SessionService } from '../services/user-session-service.js'
 import { PikkuSessionService } from '../services/user-session-service.js'
 import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js'
+import { verifyScopes } from '../scopes.js'
 import {
   PikkuCredentialWireService,
   createWireServicesCredentialWireProps,
@@ -39,6 +34,8 @@ import {
   type AuditLog,
 } from '../services/audit-service.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
+import { getOrCreatePackageSingletonServices } from '../wirings/rpc/addon-runner.js'
+import type { AddonInstance } from '../wirings/rpc/addon-runner.js'
 import { closeWireServices } from '../utils.js'
 
 async function resolveSession(
@@ -70,109 +67,6 @@ async function resolveSession(
   }
 }
 
-/**
- * Get or create singleton services for an addon package.
- * Services are cached in pikkuState to avoid recreation on each call.
- *
- * @param packageName - The addon package name
- * @param parentServices - The parent/caller's singleton services (used as base)
- * @returns The package's singleton services
- */
-/**
- * Find the consumer-defined namespace (from wireAddon) for a given addon package.
- * Returns null if the package isn't registered as an addon.
- */
-const findAddonNamespaceForPackage = (packageName: string): string | null => {
-  const addons = pikkuState(null, 'addons', 'packages')
-  if (!addons) return null
-  for (const [namespace, cfg] of addons.entries()) {
-    if (cfg?.package === packageName) return namespace
-  }
-  return null
-}
-
-/**
- * Wrap a workflow service so that bare workflow names passed from inside an
- * addon function are auto-prefixed with the addon's consumer-facing namespace.
- * Without this, `runToCompletion('myWorkflow')` from inside an addon misses
- * the workflow registered under the addon's package scope and throws
- * WorkflowNotFoundError — forcing addons to hardcode their consumer-defined
- * namespace, which couples the addon to its caller.
- *
- * Explicit `'ns:name'` and bare names that already exist in root meta are
- * unaffected; only bare names that would otherwise miss resolution get
- * prefixed.
- */
-const wrapWorkflowServiceForPackage = <T extends object>(
-  service: T,
-  packageName: string
-): T => {
-  return new Proxy(service, {
-    get(target, prop, receiver) {
-      if (prop === 'startWorkflow' || prop === 'runToCompletion') {
-        const original = Reflect.get(target, prop, receiver) as Function
-        return function (this: any, name: string, ...rest: any[]) {
-          if (typeof name === 'string' && !name.includes(':')) {
-            const namespace = findAddonNamespaceForPackage(packageName)
-            if (namespace) {
-              name = `${namespace}:${name}`
-            }
-          }
-          return original.call(this, name, ...rest)
-        }
-      }
-      return Reflect.get(target, prop, receiver)
-    },
-  })
-}
-
-const getOrCreatePackageSingletonServices = async (
-  packageName: string,
-  parentServices: CoreSingletonServices
-): Promise<CoreSingletonServices> => {
-  // Check if we already have cached singleton services for this package
-  const cachedServices = pikkuState(packageName, 'package', 'singletonServices')
-  if (cachedServices) {
-    return cachedServices
-  }
-
-  // Get the package's service factories
-  const factories = pikkuState(packageName, 'package', 'factories')
-  if (!factories || !factories.createSingletonServices) {
-    // No factories registered, use parent services
-    return parentServices
-  }
-
-  // Create config for the package (use parent config if no factory)
-  let config: CoreConfig = parentServices.config
-  if (factories.createConfig) {
-    config = await factories.createConfig(parentServices.variables)
-  }
-
-  // Create singleton services for the package, passing parent services as existing
-  const packageServices = await factories.createSingletonServices(
-    config,
-    parentServices
-  )
-
-  // Wrap workflowService so that bare names used inside the addon's functions
-  // resolve to workflows registered under the addon's package scope.
-  if (
-    packageServices.workflowService &&
-    typeof packageServices.workflowService === 'object'
-  ) {
-    packageServices.workflowService = wrapWorkflowServiceForPackage(
-      packageServices.workflowService as object,
-      packageName
-    ) as typeof packageServices.workflowService
-  }
-
-  // Cache the services
-  pikkuState(packageName, 'package', 'singletonServices', packageServices)
-
-  return packageServices
-}
-
 export const addFunction = (
   funcName: string,
   funcConfig: CorePikkuFunctionConfig<any, any>,
@@ -218,14 +112,12 @@ export const runPikkuFunc = async <In = any, Out = any>(
     wireMiddleware,
     inheritedChannelMiddleware,
     wireChannelMiddleware,
-    inheritedPermissions,
-    wirePermissions,
     coerceDataFromSchema,
-    tags = [],
     wire,
     sessionService,
     credentialWireService,
     packageName = null,
+    addonInstance,
   }: {
     singletonServices: CoreSingletonServices
     createWireServices?: CreateWireServices
@@ -235,14 +127,13 @@ export const runPikkuFunc = async <In = any, Out = any>(
     wireMiddleware?: CorePikkuMiddleware[]
     inheritedChannelMiddleware?: MiddlewareMetadata[]
     wireChannelMiddleware?: CorePikkuChannelMiddleware[]
-    inheritedPermissions?: PermissionMetadata[]
-    wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
     coerceDataFromSchema?: boolean
     tags?: string[]
     wire: PikkuRawWire
     sessionService?: SessionService<CoreUserSession>
     credentialWireService?: PikkuCredentialWireService
     packageName?: string | null
+    addonInstance?: AddonInstance
   }
 ): Promise<Out> => {
   wire.wireType ??= wireType
@@ -277,7 +168,11 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   // For addon packages, get or create their singleton services
   const resolvedSingletonServices = packageName
-    ? await getOrCreatePackageSingletonServices(packageName, singletonServices)
+    ? await getOrCreatePackageSingletonServices(
+        packageName,
+        singletonServices,
+        addonInstance
+      )
     : singletonServices
 
   // Get the package's createWireServices if available
@@ -305,8 +200,24 @@ export const runPikkuFunc = async <In = any, Out = any>(
       : wire
 
   // Set up credential wire service early so middleware can use setCredential.
-  // Skip if already set up (e.g. addon functions reuse the parent wire).
-  if (!resolvedWire.getCredentials) {
+  // An addon instance with credentialOverrides always gets a fresh alias-aware
+  // service so its logical credential names resolve to instance-specific ones,
+  // even when a parent credential service is already present on the wire.
+  // Otherwise skip if already set up (e.g. addon functions reuse the parent wire).
+  if (addonInstance?.credentialOverrides) {
+    // Credentials belong to the consuming project, so resolve them via the
+    // project's credentialService (the addon's own singletons may not carry it).
+    const aliasedCredentialWireService = new PikkuCredentialWireService(
+      singletonServices.credentialService ??
+        resolvedSingletonServices.credentialService,
+      resolvedWire,
+      addonInstance.credentialOverrides
+    )
+    Object.assign(
+      resolvedWire,
+      createWireServicesCredentialWireProps(aliasedCredentialWireService)
+    )
+  } else if (!resolvedWire.getCredentials) {
     const resolvedCredentialWireService =
       credentialWireService ??
       new PikkuCredentialWireService(
@@ -323,22 +234,17 @@ export const runPikkuFunc = async <In = any, Out = any>(
   const invocationWire = resolvedWire as PikkuWire
   const previousFunctionId = invocationWire.functionId
   const previousAudit = invocationWire.audit
+  const previousAddonNamespace = invocationWire.addonNamespace
   const previousRpcDescriptor = Object.getOwnPropertyDescriptor(
     invocationWire,
     'rpc'
   )
   invocationWire.functionId = resolvedFunctionId
   invocationWire.audit = resolvedAuditConfig
-
-  // Convert tags to PermissionMetadata and merge with inheritedPermissions
-  let mergedInheritedPermissions: PermissionMetadata[]
-  if (tags && tags.length > 0) {
-    mergedInheritedPermissions = [
-      ...(inheritedPermissions || []),
-      ...tags.map((tag) => ({ type: 'tag' as const, tag })),
-    ]
-  } else {
-    mergedInheritedPermissions = inheritedPermissions || []
+  // Track which addon instance is executing so intra-addon sibling calls
+  // resolve the same per-instance singleton services and overrides.
+  if (addonInstance) {
+    invocationWire.addonNamespace = addonInstance.namespace
   }
 
   // Helper function to run permissions and execute the function
@@ -380,6 +286,12 @@ export const runPikkuFunc = async <In = any, Out = any>(
       throw new ReadonlySessionError()
     }
 
+    // Scopes gate before the data is evaluated: they depend only on the
+    // session, so a denied request never pays to parse or validate its body.
+    // Scopes are an AND gate and stay separate from runPermissions, which
+    // evaluates the function's own OR-groups against request data.
+    verifyScopes(funcConfig.scopes ?? funcMeta.scopes, session)
+
     // Evaluate the data from the lazy function
     const actualData = await data()
 
@@ -400,23 +312,13 @@ export const runPikkuFunc = async <In = any, Out = any>(
       )
     }
 
-    if (
-      mergedInheritedPermissions.length > 0 ||
-      wirePermissions ||
-      funcMeta.permissions ||
-      funcConfig.permissions
-    ) {
-      await runPermissions(wireType, wireId, {
-        wireInheritedPermissions: mergedInheritedPermissions,
-        wirePermissions: wirePermissions,
-        funcInheritedPermissions: funcMeta.permissions,
-        funcPermissions: funcConfig.permissions,
-        services: resolvedSingletonServices,
-        wire: invocationWire as any,
-        data: actualData,
-        packageName,
-      })
-    }
+    await runPermissions({
+      funcPermissions: funcConfig.permissions,
+      services: resolvedSingletonServices,
+      wire: invocationWire as any,
+      data: actualData,
+      packageName,
+    })
 
     let wireServices: Record<string, unknown> | undefined
     let invocationAuditLog: AuditLog | undefined
@@ -508,6 +410,11 @@ export const runPikkuFunc = async <In = any, Out = any>(
       } else {
         invocationWire.audit = previousAudit
       }
+      if (previousAddonNamespace === undefined) {
+        delete (invocationWire as any).addonNamespace
+      } else {
+        invocationWire.addonNamespace = previousAddonNamespace
+      }
     }
   }
 

package/src/function/functions.types.ts

@@ -6,6 +6,7 @@ import type {
   PikkuWire,
   PickRequired,
 } from '../types/core.types.js'
+import type { PikkuRPC } from '../wirings/rpc/rpc-types.js'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { PikkuError } from '../errors/error-handler.js'
 import type { CoreNodeConfig } from '../wirings/node/node.types.js'
@@ -29,12 +30,8 @@ export type CorePikkuFunction<
   Out,
   Services extends CoreSingletonServices = CoreServices,
   Session extends CoreUserSession = CoreUserSession,
-  Wire extends PikkuWire<In, Out, true, Session> = PikkuWire<
-    In,
-    Out,
-    true,
-    Session
-  >,
+  Wire extends PikkuWire<In, Out, true, Session, PikkuRPC, null, string> =
+    PikkuWire<In, Out, true, Session>,
 > = (
   services: Services,
   data: In,
@@ -54,15 +51,8 @@ export type CorePikkuFunctionSessionless<
   Out,
   Services extends CoreSingletonServices = CoreServices,
   Session extends CoreUserSession = CoreUserSession,
-  Wire extends PikkuWire<In, Out, false, Session, any, any, any> = PikkuWire<
-    In,
-    Out,
-    false,
-    Session,
-    any,
-    any,
-    any
-  >,
+  Wire extends PikkuWire<In, Out, false, Session, PikkuRPC, null, string> =
+    PikkuWire<In, Out, false, Session>,
 > = (
   services: Services,
   data: In,
@@ -79,15 +69,8 @@ export type CorePikkuFunctionSessionless<
 export type CorePikkuPermission<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Wire extends PikkuWire<In, never, false, any, any, never, never> = PikkuWire<
-    In,
-    never,
-    false,
-    any,
-    never,
-    never,
-    never
-  >,
+  Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> =
+    PikkuWire<In, never, false, any, PikkuRPC, never, never>,
 > = (services: Services, data: In, wire: Wire) => Promise<boolean>
 
 /**
@@ -100,12 +83,8 @@ export type CorePikkuPermission<
 export type CorePikkuPermissionConfig<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Wire extends PikkuWire<In, never, false, any> = PikkuWire<
-    In,
-    never,
-    false,
-    any
-  >,
+  Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> =
+    PikkuWire<In, never, false, any, PikkuRPC, never, never>,
 > = {
   /** The permission function */
   func: CorePikkuPermission<In, Services, Wire>
@@ -143,8 +122,13 @@ export type CorePikkuPermissionConfig<
 export const pikkuPermission = <
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Wire extends PickRequired<PikkuWire<In, never, false, any>, 'session'> =
-    PickRequired<PikkuWire<In, never, false, any>, 'session'>,
+  Wire extends PickRequired<
+    PikkuWire<In, never, false, any, PikkuRPC, never, never>,
+    'session'
+  > = PickRequired<
+    PikkuWire<In, never, false, any, PikkuRPC, never, never>,
+    'session'
+  >,
 >(
   permission:
     | CorePikkuPermission<In, Services, Wire>
@@ -164,12 +148,8 @@ export const pikkuPermission = <
 export type CorePikkuPermissionFactory<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Wire extends PikkuWire<In, never, false, any> = PikkuWire<
-    In,
-    never,
-    false,
-    any
-  >,
+  Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> =
+    PikkuWire<In, never, false, any, PikkuRPC, never, never>,
 > = (input: In) => CorePikkuPermission<any, Services, Wire>
 
 /**
@@ -280,6 +260,7 @@ export type CorePikkuFunctionConfig<
   >,
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
+  Scope extends string = string,
 > = {
   /** Short human-readable name (e.g. "Create Todo") */
   title?: string
@@ -309,6 +290,15 @@ export type CorePikkuFunctionConfig<
   approvalDescription?: any
   func: PikkuFunction
   auth?: boolean
+  /**
+   * Scopes the session must hold to run this function. All of them are
+   * required (AND), and they are checked before `permissions` — unlike
+   * permissions, which OR together, a scope can only narrow access.
+   *
+   * Narrowed to the generated `ScopeId` union in a project's own
+   * `pikku-types.gen.ts`, so an undeclared scope is a compile error.
+   */
+  scopes?: Scope[]
   permissions?: CorePermissionGroup<PikkuPermission>
   middleware?: PikkuMiddleware[]
   input?: InputSchema

package/src/index.ts

@@ -169,6 +169,7 @@ export type {
   AITranscriptionParams,
   AITranscriptionResult,
 } from './services/ai-agent-runner-service.js'
+export type { AIEmbeddingService } from './services/ai-embedding-service.js'
 export type { AIRunStateService } from './services/ai-run-state-service.js'
 export type { AIStorageService } from './services/ai-storage-service.js'
 export type {
@@ -183,6 +184,11 @@ export type { GraphNodeConfig } from './wirings/workflow/graph/workflow-graph.ty
 export { createGraph } from './wirings/workflow/graph/graph-node.js'
 export { wireAddon } from './wirings/rpc/wire-addon.js'
 export type { WireAddonConfig } from './wirings/rpc/wire-addon.js'
+export { wireRemoteAddon } from './wirings/rpc/wire-remote-addon.js'
+export type {
+  WireRemoteAddonConfig,
+  RemoteAddonAuth,
+} from './wirings/rpc/wire-remote-addon.js'
 export type { PikkuPackageState } from './types/state.types.js'
 export {
   runMiddleware,
@@ -190,12 +196,8 @@ export {
   addTagMiddleware as addMiddleware,
   addGlobalMiddleware,
 } from './middleware-runner.js'
-export {
-  addTagPermission,
-  addTagPermission as addPermission,
-  addGlobalPermission,
-  checkAuthPermissions,
-} from './permissions.js'
+export { addGlobalPermission, checkAuthPermissions } from './permissions.js'
+export { verifyScopes } from './scopes.js'
 export {
   isSerializable,
   stopSingletonServices,

package/src/middleware/index.ts

@@ -10,8 +10,4 @@ export {
   addGlobalMiddleware,
   runMiddleware,
 } from '../middleware-runner.js'
-export {
-  addTagPermission,
-  addTagPermission as addPermission,
-  addGlobalPermission,
-} from '../permissions.js'
+export { addGlobalPermission, addTagPermission } from '../permissions.js'