@pikku/core 0.12.84 → 0.12.86

package/src/function/function-meta.types.ts

@@ -0,0 +1,151 @@
+import type { MiddlewareMetadata } from '../middleware/middleware.types.js'
+import type { AuditDurability } from '../services/audit-service.js'
+import type {
+  ScenarioStepKind,
+  ScenarioSurface,
+} from '../wirings/workflow/scenario-step.types.js'
+import type { CommonWireMeta } from '../types/core.types.js'
+
+export interface FunctionServicesMeta {
+  optimized: boolean
+  services: string[]
+}
+
+export interface FunctionWiresMeta {
+  optimized: boolean
+  wires: string[]
+}
+
+/**
+ * A reference to a permission function, resolved by name. Function-scoped
+ * only: there are no wire- or tag-level permission references.
+ */
+export type PermissionMetadata = {
+  type: 'wire'
+  name: string
+  inline?: boolean
+}
+
+export type FunctionRuntimeMeta = {
+  pikkuFuncId: string
+  inputSchemaName: string | null
+  outputSchemaName: string | null
+  /** Scopes the session must hold to run this function. All are required (AND). */
+  scopes?: string[]
+  expose?: boolean
+  /**
+   * A sessionless function's own `auth: true`. `sessionless` carries the
+   * baseline — a `pikkuFunc` always requires a session — and this carries the
+   * tightening a `pikkuSessionlessFunc` applies to itself. Both are needed to
+   * know whether a function is gated without running it.
+   */
+  auth?: boolean
+  /**
+   * The author's declaration that this function's permission check lives in its
+   * own body. Carries no runtime effect — it records a gate codegen cannot see,
+   * so an audit is not left to guess whether a sessionless function is open.
+   * Refused unless `allow.permissionsInBody` is set in `pikku.config.json`.
+   */
+  permissionsInBody?: boolean
+  remote?: boolean
+  /**
+   * A step RPC: invoked by name only from a scenario run and refused
+   * everywhere else, so it is never network-callable.
+   */
+  scenarioStep?: boolean
+  /**
+   * The body of a `pikkuScenario(...)`. Only ever run by `pikku scenario run`,
+   * so it is held back from the app bootstrap and from every deployed unit.
+   */
+  scenario?: boolean
+  mcp?: boolean
+  readonly?: boolean
+  deploy?: 'serverless' | 'server' | 'auto'
+  sessionless?: boolean
+  /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. */
+  workflowQueued?: boolean
+  /** Retry count when this function is used as a workflow step. */
+  workflowRetries?: number
+  /** Timeout when this function is used as a workflow step (e.g. '30s', '5m'). */
+  workflowTimeout?: string
+  /**
+   * Scenario steps only: which surfaces this step declares a binding for.
+   *
+   * The reporter derives coverage from this — a `then` with no binding for the
+   * surface the run targeted was never actually witnessed there, which is a gap
+   * worth counting rather than excusing.
+   */
+  scenarioStepSurfaces?: ScenarioSurface[]
+  /**
+   * Scenario steps only: this step runs as a persona, so every call site must
+   * pass one and the runner injects it as `wire.actor`.
+   *
+   * Declared by `actor: true`, or implied by a `browser` binding — a window is
+   * opened as somebody. Absent on a step with nobody to be: an assertion over
+   * what an earlier step returned, or one posting credentials precisely because
+   * it must not reuse an actor's session.
+   */
+  scenarioStepRequiresActor?: boolean
+  /**
+   * Scenario steps only: who acts. Absent means `persona` — the ordinary step,
+   * and the only kind that existed before the other two.
+   *
+   * A `platform` or `addon` step is the app or a third-party system acting, and
+   * it must never reach a virtual user's catalogue. That is not tidiness: a
+   * virtual user that can invoke "Stripe's webhook arrives" can forge its own
+   * payment success, and every finding downstream of that is worthless.
+   */
+  scenarioStepKind?: ScenarioStepKind
+  /** Addon steps only: the addon whose system acts — `wireAddon`'s `name`. */
+  scenarioStepAddon?: string
+  /** Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input. */
+  scenarioStepTemplate?: string
+  /**
+   * The function's `audit` config, resolved — `audit: true` reads as
+   * `{ durability: 'best-effort' }`. Absent means the function records nothing:
+   * `auditLog.write()` from an unmarked function is dropped with a warning, so
+   * this is the only place a reader can see which functions have a trail at all
+   * without running them.
+   *
+   * Informational. The runner resolves audit from the live function config, not
+   * from here, so meta and runtime cannot disagree about whether audit is on.
+   */
+  audit?: {
+    durability: AuditDurability
+  }
+  version?: number
+  approvalRequired?: boolean
+  approvalDescription?: string
+  implementationHash?: string
+  contractHash?: string
+  inputHash?: string
+  outputHash?: string
+}
+
+export type FunctionMeta = FunctionRuntimeMeta &
+  Partial<
+    {
+      name: string
+      /** `remote`: a contract with no local body, answered by a connected client. */
+      functionType: 'user' | 'inline' | 'helper' | 'remote'
+      funcWrapper: string
+      services: FunctionServicesMeta
+      wires: FunctionWiresMeta
+      inputs: string[] | null
+      outputs: string[] | null
+      middleware: MiddlewareMetadata[]
+      permissions: PermissionMetadata[]
+      isDirectFunction: boolean
+      sourceFile: string
+      exportedName: string
+      /** File containing the handler body when it differs from sourceFile (imported handlers) */
+      bodySourceFile?: string
+      /** 1-indexed first line of the handler body (verbose meta; coverage mapping) */
+      bodyStart: number
+      /** 1-indexed last line of the handler body (verbose meta; coverage mapping) */
+      bodyEnd: number
+    } & CommonWireMeta
+  >
+
+export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>
+export type FunctionsMeta = Record<string, FunctionMeta>

package/src/function/function-runner.test.ts

@@ -6,10 +6,12 @@ import {
   getFunctionNames,
   runPikkuFunc,
 } from './function-runner.js'
-import { addGlobalPermission, addTagMiddleware } from '../index.js'
+import { addGlobalPermission } from '../permissions.js'
+import { addTagMiddleware } from '../middleware-runner.js'
 import { addSchema } from '../schema.js'
 import { resetPikkuState, pikkuState } from '../pikku-state.js'
-import type { CoreServices, CorePikkuMiddleware } from '../types/core.types.js'
+import type { CoreServices } from '../types/core.types.js'
+import type { CorePikkuMiddleware } from '../middleware/middleware.types.js'
 import type { CorePermissionGroup } from './functions.types.js'
 import { PikkuSessionService } from '../services/user-session-service.js'
 import { MissingScopeError, ReadonlySessionError } from '../errors/errors.js'

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')
         }