@pikku/core 0.12.83 → 0.12.86

package/src/function/function-runner.ts

@@ -14,14 +14,16 @@ import {
 } from '../schema.js'
 import type {
   CoreUserSession,
-  CorePikkuMiddleware,
   PikkuWiringTypes,
   PikkuWire,
   PikkuRawWire,
-  MiddlewareMetadata,
   CoreSingletonServices,
   CreateWireServices,
 } from '../types/core.types.js'
+import type {
+  CorePikkuMiddleware,
+  MiddlewareMetadata,
+} from '../middleware/middleware.types.js'
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js'
 import type { CorePikkuFunctionConfig } from './functions.types.js'
 import { parseVersionedId } from '../version.js'
@@ -40,13 +42,14 @@ 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 { getOrCreatePackageSingletonServices } from '../wirings/addon/addon-runner.js'
 import {
   resolveAddonAuth,
+  resolveAddonFunctionTarget,
   resolveAddonScopes,
   resolveAddonTagMiddleware,
-} from '../wirings/rpc/wire-addon.js'
-import type { AddonInstance } from '../wirings/rpc/addon-runner.js'
+} from '../wirings/addon/wire-addon.js'
+import type { AddonInstance } from '../wirings/addon/addon-runner.js'
 import { closeWireServices } from '../utils.js'
 
 async function resolveSession(
@@ -168,6 +171,32 @@ export const runPikkuFunc = async <In = any, Out = any>(
     }
   }
 
+  /**
+   * The package the *function* belongs to, which is the wire's own until a
+   * `ref()` resolves the target into an addon. The wiring stays the consuming
+   * app's — that is what keeps the app's middleware running rather than the
+   * addon's — but everything the function is declared with lives in the addon's
+   * package state, so its schemas, services and permissions are read from here.
+   */
+  let funcPackageName = packageName
+
+  if (!funcMeta) {
+    const addonTarget = resolveAddonFunctionTarget(funcName, packageName)
+    if (addonTarget) {
+      funcConfig =
+        funcConfig ||
+        pikkuState(addonTarget.packageName, 'function', 'functions').get(
+          addonTarget.localName
+        )
+      funcMeta = pikkuState(addonTarget.packageName, 'function', 'meta')[
+        addonTarget.localName
+      ]
+      if (funcMeta) {
+        funcPackageName = addonTarget.packageName
+      }
+    }
+  }
+
   if (!funcConfig) {
     throw new Error(`Function not found: ${funcName}`)
   }
@@ -177,17 +206,17 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   const resolvedFunctionId = funcMeta.pikkuFuncId ?? funcName
 
-  const resolvedSingletonServices = packageName
+  const resolvedSingletonServices = funcPackageName
     ? await getOrCreatePackageSingletonServices(
-        packageName,
+        funcPackageName,
         singletonServices,
         addonInstance
       )
     : singletonServices
 
   let resolvedCreateWireServices = createWireServices
-  if (packageName) {
-    const factories = pikkuState(packageName, 'package', 'factories')
+  if (funcPackageName) {
+    const factories = pikkuState(funcPackageName, 'package', 'factories')
     if (factories?.createWireServices) {
       resolvedCreateWireServices = factories.createWireServices
     }
@@ -345,17 +374,21 @@ export const runPikkuFunc = async <In = any, Out = any>(
       actualData = applyDefaultsFromSchema(
         inputSchemaName,
         actualData,
-        packageName
+        funcPackageName
       )
       if (coerceDataFromSchema) {
-        coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
+        coerceTopLevelDataFromSchema(
+          inputSchemaName,
+          actualData,
+          funcPackageName
+        )
       }
       await validateSchema(
         resolvedSingletonServices.logger,
         resolvedSingletonServices.schema,
         inputSchemaName,
         actualData,
-        packageName
+        funcPackageName
       )
     }
 
@@ -368,7 +401,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
       // knowledge: decisions/security/a-permission-gets-a-wire-it-cannot-reply-on.md
       wire: invocationWire as PermissionWire,
       data: actualData,
-      packageName,
+      packageName: funcPackageName,
     })
 
     let wireServices: Record<string, unknown> | undefined
@@ -395,7 +428,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         )
         services = { ...services, auditLog: invocationAuditLog }
       }
-      const callerPackageName = packageName
+      const callerPackageName = funcPackageName
       Object.defineProperty(invocationWire, 'rpc', {
         get() {
           const rpc = rpcService.getContextRPCService(

package/src/function/functions.types.ts

@@ -2,17 +2,17 @@ import type {
   CoreServices,
   CoreSecretlessSingletonServices,
   CoreUserSession,
-  CorePikkuMiddleware,
   PikkuWire,
-  PickRequired,
   SecretlessServices,
 } from '../types/core.types.js'
+import type { CorePikkuMiddleware } from '../middleware/middleware.types.js'
+import type { PickRequired } from '../utils.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'
 import type { ScenarioSurface } from '../wirings/workflow/scenario-step.types.js'
-import type { Safe } from '../secret-value.js'
+import type { Safe } from '../classification/secret-value.js'
 
 export type CorePikkuFunction<
   In,
@@ -149,8 +149,7 @@ export const pikkuAuth = <
   Session extends CoreUserSession = CoreUserSession,
 >(
   auth:
-    | CorePikkuAuth<Services, Session>
-    | CorePikkuAuthConfig<Services, Session>
+    CorePikkuAuth<Services, Session> | CorePikkuAuthConfig<Services, Session>
 ): CorePikkuPermission<any, Services, any> => {
   const fn = typeof auth === 'function' ? auth : auth.func
   const wrapper: CorePikkuPermission<any, Services, any> & AuthBranded = async (
@@ -167,8 +166,7 @@ export const pikkuAuth = <
 }
 
 export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
-  | Record<string, PikkuPermission | PikkuPermission[]>
-  | undefined
+  Record<string, PikkuPermission | PikkuPermission[]> | undefined
 
 /**
  * A lifecycle hook: same call signature as the function it hangs off, return
@@ -232,6 +230,12 @@ export type CorePikkuFunctionConfig<
    * and report how much of the flow each surface actually covers.
    */
   surfaces?: ScenarioSurface[]
+  /**
+   * Scenario steps only: this step is driven by a persona, so the runner injects
+   * `wire.actor` and refuses to dispatch it without one. Set by the definer from
+   * a `browser` binding or an explicit `actor: true`, never written by hand.
+   */
+  requiresActor?: boolean
   audit?:
     | boolean
     | {

package/src/function/index.ts

@@ -1,4 +1,8 @@
-export { addFunction, getAllFunctionNames } from './function-runner.js'
+export {
+  addFunction,
+  getAllFunctionNames,
+  runPikkuFunc,
+} from './function-runner.js'
 export {
   pikkuAuth,
   pikkuPermission,
@@ -14,8 +18,23 @@ export type {
   CorePikkuAuthConfig,
   CorePikkuPermission,
 } from './functions.types.js'
+export type { ListInput, ListOutput, Filter } from './list.types.js'
+export { AbandonedError } from './abort-scope.js'
+export type { AbortScope } from './abort-scope.js'
+export { checkAuthPermissions } from '../permissions.js'
+export type {
+  CorePermissionGroup,
+  CorePikkuApprovalDescription,
+  CorePikkuPermissionConfig,
+  CorePikkuPermissionFactory,
+} from './functions.types.js'
 export type {
-  ListInput,
-  ListOutput,
-  Filter,
-} from './list.types.js'
+  FunctionMeta,
+  FunctionRuntimeMeta,
+  FunctionServicesMeta,
+  FunctionWiresMeta,
+  FunctionsMeta,
+  FunctionsRuntimeMeta,
+  PermissionMetadata,
+} from './function-meta.types.js'
+export { PikkuRequest } from './pikku-request.js'

package/src/function/list.types.ts

@@ -66,6 +66,4 @@ export type LeafFilter<F extends Record<string, unknown>> = {
  * evaluation time; a single-key object is a leaf predicate.
  */
 export type Filter<F extends Record<string, unknown>> =
-  | LeafFilter<F>
-  | Filter<F>[]
-  | { [label: string]: Filter<F> }
+  LeafFilter<F> | Filter<F>[] | { [label: string]: Filter<F> }

package/src/middleware/auth-apikey.ts

@@ -1,5 +1,7 @@
-import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
-
+import {
+  pikkuMiddleware,
+  pikkuMiddlewareFactory,
+} from './middleware-factories.js'
 export const authAPIKey = pikkuMiddlewareFactory<{
   source: 'header' | 'query' | 'all'
 }>(({ source }) =>

package/src/middleware/auth-bearer.test.ts

@@ -8,7 +8,7 @@ import {
   createMiddlewareSessionWireProps,
 } from '../services/user-session-service.js'
 import { InvalidSessionError } from '../errors/errors.js'
-import { createSecretValue } from '../secret-value.js'
+import { createSecretValue } from '../classification/secret-value.js'
 
 beforeEach(() => {
   resetPikkuState()

package/src/middleware/auth-bearer.ts

@@ -1,7 +1,9 @@
 import { InvalidSessionError } from '../errors/errors.js'
 import type { CoreUserSession } from '../types/core.types.js'
-import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
-
+import {
+  pikkuMiddleware,
+  pikkuMiddlewareFactory,
+} from './middleware-factories.js'
 const constantTimeEqual = (a: string, b: string): boolean => {
   if (a.length !== b.length) return false
   let result = 0

package/src/middleware/auth-cookie.ts

@@ -1,5 +1,8 @@
 import type { SerializeOptions } from 'cookie'
-import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
+import {
+  pikkuMiddleware,
+  pikkuMiddlewareFactory,
+} from './middleware-factories.js'
 import type { RelativeTimeInput } from '../time-utils.js'
 import { getRelativeTimeOffsetFromNow } from '../time-utils.js'
 

package/src/middleware/cors.test.ts

@@ -15,6 +15,21 @@ const createMockRequest = (method = 'get', origin?: string) => ({
   },
 })
 
+const createMockServices = () => {
+  const debugMessages: string[] = []
+  return {
+    logger: {
+      debug: (message: string) => {
+        debugMessages.push(message)
+      },
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+    },
+    _debugMessages: debugMessages,
+  }
+}
+
 const createMockResponse = () => {
   const headers: Record<string, string> = {}
   let statusCode: number | undefined
@@ -125,30 +140,113 @@ describe('cors', () => {
       )
     })
 
-    test('should use first origin when request origin not in array', async () => {
+    test('should omit Access-Control-Allow-Origin when request origin not in array', async () => {
       const middleware = cors({ origin: ['https://a.com', 'https://b.com'] })
       const request = createMockRequest('get', 'https://unknown.com')
       const response = createMockResponse()
+      const services = createMockServices()
 
       await middleware(
-        {} as any,
+        services as any,
         { http: { request, response } } as any,
         async () => {}
       )
 
       assert.strictEqual(
         response._headers['Access-Control-Allow-Origin'],
-        'https://a.com'
+        undefined
       )
     })
 
-    test('should use first origin when no request origin header', async () => {
+    test('should log the rejected origin at debug level', async () => {
+      const middleware = cors({ origin: ['https://a.com', 'https://b.com'] })
+      const request = createMockRequest('get', 'https://unknown.com')
+      const response = createMockResponse()
+      const services = createMockServices()
+
+      await middleware(
+        services as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(services._debugMessages.length, 1)
+      assert.match(services._debugMessages[0]!, /https:\/\/unknown\.com/)
+    })
+
+    test('should omit Access-Control-Allow-Origin when no request origin header', async () => {
       const middleware = cors({ origin: ['https://a.com', 'https://b.com'] })
       const request = createMockRequest('get')
       const response = createMockResponse()
+      const services = createMockServices()
 
       await middleware(
-        {} as any,
+        services as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Origin'],
+        undefined
+      )
+      assert.strictEqual(services._debugMessages.length, 0)
+    })
+
+    test('should still call next for a disallowed origin', async () => {
+      const middleware = cors({ origin: ['https://a.com'] })
+      const request = createMockRequest('get', 'https://unknown.com')
+      const response = createMockResponse()
+      const services = createMockServices()
+      let nextCalled = false
+
+      await middleware(
+        services as any,
+        { http: { request, response } } as any,
+        async () => {
+          nextCalled = true
+        }
+      )
+
+      assert.strictEqual(nextCalled, true)
+    })
+
+    test('should omit Access-Control-Allow-Credentials for a disallowed origin', async () => {
+      const middleware = cors({
+        origin: ['https://a.com'],
+        credentials: true,
+      })
+      const request = createMockRequest('get', 'https://unknown.com')
+      const response = createMockResponse()
+      const services = createMockServices()
+
+      await middleware(
+        services as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Origin'],
+        undefined
+      )
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Credentials'],
+        undefined
+      )
+    })
+
+    test('should set credentials header for an allowed array origin', async () => {
+      const middleware = cors({
+        origin: ['https://a.com'],
+        credentials: true,
+      })
+      const request = createMockRequest('get', 'https://a.com')
+      const response = createMockResponse()
+      const services = createMockServices()
+
+      await middleware(
+        services as any,
         { http: { request, response } } as any,
         async () => {}
       )
@@ -157,6 +255,29 @@ describe('cors', () => {
         response._headers['Access-Control-Allow-Origin'],
         'https://a.com'
       )
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Credentials'],
+        'true'
+      )
+    })
+
+    test('should omit Access-Control-Allow-Origin on a disallowed preflight but still return 204', async () => {
+      const middleware = cors({ origin: ['https://a.com'] })
+      const request = createMockRequest('options', 'https://unknown.com')
+      const response = createMockResponse()
+      const services = createMockServices()
+
+      await middleware(
+        services as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Origin'],
+        undefined
+      )
+      assert.strictEqual(response._getStatus(), 204)
     })
 
     test('should set Vary: Origin header when origin is array', async () => {

package/src/middleware/cors.ts

@@ -1,9 +1,13 @@
-import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
-
+import {
+  pikkuMiddleware,
+  pikkuMiddlewareFactory,
+} from './middleware-factories.js'
 /**
  * Sets CORS headers on every response and short-circuits OPTIONS preflight
  * with a 204. `origin: true` reflects the request origin; an array reflects a
- * matching origin and otherwise falls back to its first entry.
+ * matching origin and otherwise sends no `Access-Control-Allow-Origin` at all,
+ * so the browser reports "origin not allowed" rather than an origin mismatch
+ * against whichever entry happened to be first.
  */
 export const cors = pikkuMiddlewareFactory<{
   origin?: string | string[] | true
@@ -29,7 +33,7 @@ export const cors = pikkuMiddlewareFactory<{
     return pikkuMiddleware({
       name: 'CORS',
       description: 'Handles cross-origin requests including OPTIONS preflight',
-      func: async (_services, wires, next) => {
+      func: async (services, wires, next) => {
         const request = wires.http?.request
         const response = wires.http?.response
 
@@ -39,19 +43,26 @@ export const cors = pikkuMiddlewareFactory<{
 
         const requestOrigin = request.header('origin')
 
-        let allowedOrigin: string
+        let allowedOrigin: string | undefined
         if (origin === true) {
           allowedOrigin = requestOrigin || '*'
         } else if (Array.isArray(origin)) {
           allowedOrigin =
             requestOrigin && origin.includes(requestOrigin)
               ? requestOrigin
-              : origin[0]
+              : undefined
+          if (requestOrigin && !allowedOrigin) {
+            services.logger.debug(
+              `CORS: origin '${requestOrigin}' is not in the allowed list, omitting Access-Control-Allow-Origin`
+            )
+          }
         } else {
           allowedOrigin = origin
         }
 
-        response.header('Access-Control-Allow-Origin', allowedOrigin)
+        if (allowedOrigin) {
+          response.header('Access-Control-Allow-Origin', allowedOrigin)
+        }
         response.header('Access-Control-Allow-Methods', methods.join(', '))
         response.header('Access-Control-Allow-Headers', headers.join(', '))
 
@@ -62,7 +73,7 @@ export const cors = pikkuMiddlewareFactory<{
           )
         }
 
-        if (credentials) {
+        if (credentials && allowedOrigin) {
           response.header('Access-Control-Allow-Credentials', 'true')
         }
 

package/src/middleware/index.ts

@@ -11,3 +11,19 @@ export {
   runMiddleware,
 } from '../middleware-runner.js'
 export { addGlobalPermission } from '../permissions.js'
+export type {
+  CorePikkuMiddleware,
+  CorePikkuMiddlewareConfig,
+  CorePikkuMiddlewareFactory,
+  CorePikkuMiddlewareGroup,
+  MiddlewareMetadata,
+  MiddlewarePriority,
+} from './middleware.types.js'
+export {
+  pikkuAgentMiddleware,
+  pikkuChannelMiddleware,
+  pikkuChannelMiddlewareFactory,
+  pikkuMiddleware,
+  pikkuMiddlewareFactory,
+} from './middleware-factories.js'
+export type { PikkuAgentMiddlewareHooks } from '../wirings/agent/agent.types.js'

package/src/middleware/middleware-factories.ts

@@ -0,0 +1,62 @@
+import type {
+  CoreSingletonServices,
+  CoreUserSession,
+} from '../types/core.types.js'
+import type {
+  CorePikkuChannelMiddleware,
+  CorePikkuChannelMiddlewareFactory,
+} from '../wirings/channel/channel.types.js'
+import type { PikkuAgentMiddlewareHooks } from '../wirings/agent/agent.types.js'
+import type {
+  CorePikkuMiddleware,
+  CorePikkuMiddlewareConfig,
+  CorePikkuMiddlewareFactory,
+  MiddlewarePriority,
+} from './middleware.types.js'
+
+export const pikkuMiddleware = <
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+>(
+  middleware:
+    | CorePikkuMiddleware<SingletonServices, UserSession>
+    | CorePikkuMiddlewareConfig<SingletonServices, UserSession>
+): CorePikkuMiddleware<SingletonServices, UserSession> => {
+  if (typeof middleware === 'function') return middleware
+  const func = middleware.func as CorePikkuMiddleware<
+    SingletonServices,
+    UserSession
+  > & { __priority?: MiddlewarePriority }
+  if (middleware.priority) {
+    func.__priority = middleware.priority
+  }
+  return func
+}
+
+export const pikkuMiddlewareFactory = <In = any>(
+  factory: CorePikkuMiddlewareFactory<In>
+): CorePikkuMiddlewareFactory<In> => {
+  return factory
+}
+
+export const pikkuChannelMiddleware = <
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  Event = unknown,
+>(
+  middleware: CorePikkuChannelMiddleware<SingletonServices, Event>
+): CorePikkuChannelMiddleware<SingletonServices, Event> => {
+  return middleware
+}
+
+export const pikkuChannelMiddlewareFactory = <In = any>(
+  factory: CorePikkuChannelMiddlewareFactory<In>
+): CorePikkuChannelMiddlewareFactory<In> => {
+  return factory
+}
+
+export const pikkuAgentMiddleware = <
+  State extends Record<string, unknown> = Record<string, unknown>,
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+>(
+  hooks: PikkuAgentMiddlewareHooks<State, SingletonServices>
+): PikkuAgentMiddlewareHooks<State, SingletonServices> => hooks

package/src/middleware/middleware.types.ts

@@ -0,0 +1,61 @@
+import type {
+  CoreSingletonServices,
+  CoreUserSession,
+  PikkuWire,
+} from '../types/core.types.js'
+
+export type CorePikkuMiddleware<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = (
+  services: SingletonServices,
+  wires: PikkuWire,
+  next: () => Promise<void>
+) => Promise<void>
+
+/**
+ * Execution order: `highest` runs first (outermost in the onion), `lowest`
+ * runs last, closest to the function.
+ */
+export type MiddlewarePriority =
+  'highest' | 'high' | 'medium' | 'low' | 'lowest'
+
+export type CorePikkuMiddlewareConfig<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = {
+  func: CorePikkuMiddleware<SingletonServices, UserSession>
+  name?: string
+  description?: string
+  /** Execution priority. Lower runs first (outermost). Defaults to 'medium'. */
+  priority?: MiddlewarePriority
+}
+
+export type CorePikkuMiddlewareFactory<
+  In = any,
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = (input: In) => CorePikkuMiddleware<SingletonServices, UserSession>
+
+export type CorePikkuMiddlewareGroup<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = Array<
+  | CorePikkuMiddleware<SingletonServices, UserSession>
+  | CorePikkuMiddlewareFactory<any, SingletonServices, UserSession>
+>
+
+export type MiddlewareMetadata =
+  | {
+      type: 'http'
+      route: string // Route pattern (e.g., '*' for all, '/api/*' for specific)
+    }
+  | {
+      type: 'tag'
+      tag: string
+    }
+  | {
+      type: 'wire'
+      name: string
+      inline?: boolean
+    }

package/src/middleware/remote-auth.test.ts

@@ -4,7 +4,7 @@ import { pikkuRemoteAuthMiddleware } from './remote-auth.js'
 import { UnauthorizedError } from '../errors/errors.js'
 import { resetPikkuState } from '../pikku-state.js'
 import { encryptWithKeyMaterial, REMOTE_SESSION_INFO } from '../crypto-utils.js'
-import { createSecretValue } from '../secret-value.js'
+import { createSecretValue } from '../classification/secret-value.js'
 
 beforeEach(() => {
   resetPikkuState()

package/src/middleware/remote-auth.ts

@@ -1,5 +1,5 @@
 import { UnauthorizedError } from '../errors/errors.js'
-import { pikkuMiddleware } from '../types/core.types.js'
+import { pikkuMiddleware } from './middleware-factories.js'
 import {
   assertStrongKeyMaterial,
   decryptWithKeyMaterial,