@pikku/core 0.12.46 → 0.12.49

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

@@ -12,6 +12,7 @@ import type { CoreServices, CorePikkuMiddleware } from '../types/core.types.js'
 import type { CorePermissionGroup } from './functions.types.js'
 import { PikkuSessionService } from '../services/user-session-service.js'
 import { ReadonlySessionError } from '../errors/errors.js'
+import { createInvocationAudit } from '../services/audit-service.js'
 
 beforeEach(() => {
   resetPikkuState()
@@ -1198,6 +1199,113 @@ describe('runPikkuFunc - Integration Tests', () => {
     assert.equal(childFunctionId, 'rpcChildAudited')
   })
 
+  test('should audit writes from an audited function invoked via exposed rpc (stale outer auditLog)', async () => {
+    // Repro of the exposed-RPC HTTP path: the generated rpcCaller has no
+    // audit config, and createWireServices builds auditLog on ITS wire —
+    // the audited inner function must not inherit that disabled instance.
+    const events: any[] = []
+    const singletonServices = {
+      ...mockSingletonServices,
+      audit: { audit: async (event: any) => events.push(event) },
+    }
+
+    addTestFunction('auditedInner', {
+      audit: true,
+      func: async (services: any) => {
+        await services.auditLog.write({ type: 'booking.update', source: 'explicit' })
+        return 'inner-ok'
+      },
+    })
+
+    addTestFunction('rpcCallerLike', {
+      func: async (_services: any, _data: any, wire: any) => {
+        return wire.rpc.invoke('auditedInner', {})
+      },
+    })
+
+    const result = await runPikkuFunc('http', 'exposed-rpc-route', 'rpcCallerLike', {
+      singletonServices,
+      data: () => ({}),
+      auth: false,
+      wire: {},
+      createWireServices: async (services: any, wire: any) => ({
+        auditLog: createInvocationAudit(services.audit, wire),
+      }),
+    })
+
+    assert.equal(result, 'inner-ok')
+    assert.equal(events.length, 1)
+    assert.equal(events[0].type, 'booking.update')
+    assert.equal(events[0].functionId, 'auditedInner')
+  })
+
+  test('should give an audited rpc sub-call its own audit buffer with child attribution', async () => {
+    const events: any[] = []
+    const singletonServices = {
+      ...mockSingletonServices,
+      audit: { audit: async (event: any) => events.push(event) },
+    }
+
+    addTestFunction('auditedChildWriter', {
+      audit: true,
+      func: async (services: any) => {
+        await services.auditLog.write({ type: 'child.event', source: 'explicit' })
+        return 'child-ok'
+      },
+    })
+
+    addTestFunction('auditedParentWriter', {
+      audit: true,
+      func: async (services: any, _data: any, wire: any) => {
+        await services.auditLog.write({ type: 'parent.event', source: 'explicit' })
+        return wire.rpc.invoke('auditedChildWriter', {})
+      },
+    })
+
+    const result = await runPikkuFunc('rpc', 'audited-parent-child', 'auditedParentWriter', {
+      singletonServices,
+      data: () => ({}),
+      auth: false,
+      wire: {},
+    })
+
+    assert.equal(result, 'child-ok')
+    const byType = Object.fromEntries(events.map((e) => [e.type, e.functionId]))
+    assert.equal(byType['parent.event'], 'auditedParentWriter')
+    assert.equal(byType['child.event'], 'auditedChildWriter')
+  })
+
+  test('should warn via the singleton logger when audit writes are dropped', async () => {
+    const warnings: any[] = []
+    const singletonServices = {
+      ...mockSingletonServices,
+      logger: { ...mockSingletonServices.logger, warn: (msg: any) => warnings.push(msg) },
+      audit: { audit: async () => {} },
+    }
+
+    addTestFunction('unauditedWriter', {
+      func: async (services: any) => {
+        await services.auditLog.write({ type: 'dropped.event', source: 'explicit' })
+        return 'ok'
+      },
+    })
+
+    const result = await runPikkuFunc('rpc', 'unaudited-writer', 'unauditedWriter', {
+      singletonServices,
+      data: () => ({}),
+      auth: false,
+      wire: {},
+      createWireServices: async (services: any, wire: any) => ({
+        auditLog: createInvocationAudit(services.audit, wire, services.logger),
+      }),
+    })
+
+    assert.equal(result, 'ok')
+    assert.equal(warnings.length, 1)
+    assert.match(String(warnings[0]), /dropped/)
+    assert.match(String(warnings[0]), /unauditedWriter/)
+  })
+
   test('should expose the resolved base function id after version fallback', async () => {
     let receivedFunctionId: any
 

package/src/function/function-runner.ts

@@ -33,7 +33,11 @@ import {
   createWireServicesCredentialWireProps,
 } from '../services/credential-wire-service.js'
 import { defaultPikkuUserIdResolver } from '../services/pikku-user-id.js'
-import { resolveAuditConfig } from '../services/audit-service.js'
+import {
+  createInvocationAudit,
+  resolveAuditConfig,
+  type AuditLog,
+} from '../services/audit-service.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { closeWireServices } from '../utils.js'
 
@@ -415,15 +419,35 @@ export const runPikkuFunc = async <In = any, Out = any>(
     }
 
     let wireServices: Record<string, unknown> | undefined
+    let invocationAuditLog: AuditLog | undefined
     try {
       wireServices = (await resolvedCreateWireServices?.(
         resolvedSingletonServices,
         invocationWire
       )) as Record<string, unknown> | undefined
-      const services =
+      let services =
         wireServices && Object.keys(wireServices).length > 0
           ? { ...resolvedSingletonServices, ...wireServices }
           : resolvedSingletonServices
+      // The audit gate is per-function, but the auditLog wire service is
+      // created per-transport-invocation — a nested/exposed-RPC call would
+      // otherwise inherit an auditLog constructed while the OUTER wire's
+      // audit was unset (e.g. the generated rpcCaller has no audit config),
+      // silently dropping every write. Re-gate here: if this function
+      // declares audit and the inherited auditLog wasn't built for this
+      // invocation (config identity check), bind a fresh one to this wire.
+      if (
+        resolvedAuditConfig &&
+        resolvedSingletonServices.audit &&
+        services.auditLog?.config !== resolvedAuditConfig
+      ) {
+        invocationAuditLog = createInvocationAudit(
+          resolvedSingletonServices.audit,
+          invocationWire,
+          resolvedSingletonServices.logger
+        )
+        services = { ...services, auditLog: invocationAuditLog }
+      }
       const callerPackageName = packageName
       Object.defineProperty(invocationWire, 'rpc', {
         get() {
@@ -446,6 +470,8 @@ export const runPikkuFunc = async <In = any, Out = any>(
       })
       return await funcConfig.func(services, actualData, invocationWire)
     } finally {
+      // Flush the runner-installed audit buffer before wire services close.
+      await invocationAuditLog?.close()
       if (wireServices && Object.keys(wireServices).length > 0) {
         await closeWireServices(resolvedSingletonServices.logger, wireServices)
       }

package/src/services/audit-service.ts

@@ -3,6 +3,7 @@ import type {
   PikkuWire,
   PikkuWiringTypes,
 } from '../types/core.types.js'
+import type { Logger } from './logger.js'
 
 export type AuditDurability = 'best-effort' | 'transactional'
 export type AuditOutcome = 'success' | 'failed' | 'denied'
@@ -68,14 +69,18 @@ class DisabledInvocationAudit implements AuditLog {
   private warned = false
 
   constructor(
-    private readonly wire: PikkuWire<any, any, any, CoreUserSession>
+    private readonly wire: PikkuWire<any, any, any, CoreUserSession>,
+    private readonly logger?: Logger
   ) {}
 
   async write(_event: AuditLogWriteInput): Promise<void> {
     if (!this.warned) {
       this.warned = true
-      ;(this.wire as any).logger?.warn?.(
-        'audit.write() called for an invocation without wire.audit enabled'
+      // Fall back to the singleton logger — wires rarely carry their own, and
+      // a dropped audit write must never be invisible.
+      const logger = (this.wire as any).logger ?? this.logger
+      logger?.warn?.(
+        `audit.write() dropped for '${this.wire.functionId ?? 'unknown function'}' — the function has no audit config (set audit: true on it)`
       )
     }
   }
@@ -91,7 +96,8 @@ class InvocationAuditLog implements AuditLog {
   constructor(
     public readonly config: ResolvedAuditConfig,
     private readonly service: AuditService,
-    private readonly wire: PikkuWire<any, any, any, CoreUserSession>
+    private readonly wire: PikkuWire<any, any, any, CoreUserSession>,
+    private readonly logger?: Logger
   ) {}
 
   async write(event: AuditLogWriteInput): Promise<void> {
@@ -129,10 +135,8 @@ class InvocationAuditLog implements AuditLog {
         await this.service.audit(event)
       }
     } catch (error) {
-      ;(this.wire as any).logger?.warn?.(
-        'best-effort audit flush failed',
-        error
-      )
+      const logger = (this.wire as any).logger ?? this.logger
+      logger?.warn?.('best-effort audit flush failed', error)
     }
   }
 
@@ -171,13 +175,14 @@ export const resolveAuditConfig = (
 
 export const createInvocationAudit = (
   service: AuditService,
-  wire: PikkuWire<any, any, any, CoreUserSession>
+  wire: PikkuWire<any, any, any, CoreUserSession>,
+  logger?: Logger
 ): AuditLog => {
   if (!wire.audit) {
-    return new DisabledInvocationAudit(wire)
+    return new DisabledInvocationAudit(wire, logger)
   }
 
-  return new InvocationAuditLog(wire.audit, service, wire)
+  return new InvocationAuditLog(wire.audit, service, wire, logger)
 }
 
 export const resolveAuditActorFromWire = (

package/src/services/http-user-flow-actors.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer, type Server } from 'node:http'
+
+import { createHttpUserFlowActors } from './http-user-flow-actors.js'
+
+// Minimal target app: actor sign-in endpoint + exposed RPC endpoint, session
+// via cookie. Mirrors the Better Auth actor plugin's contract.
+const startTarget = async () => {
+  let logins = 0
+  let expireNext = false
+  const server: Server = createServer((req, res) => {
+    const chunks: Buffer[] = []
+    req.on('data', (c) => chunks.push(c))
+    req.on('end', () => {
+      const body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) : {}
+      if (req.url === '/api/auth/sign-in/actor') {
+        if (body.secret !== 'impersonation-secret') {
+          res.writeHead(401).end(JSON.stringify({ message: 'bad actor secret' }))
+          return
+        }
+        logins++
+        res.setHeader('set-cookie', [
+          `session=s${logins}; Path=/; HttpOnly`,
+          `csrf=c${logins}; Path=/`,
+        ])
+        res.writeHead(200).end(JSON.stringify({ ok: true, email: body.email }))
+        return
+      }
+      if (req.url?.startsWith('/api/rpc/')) {
+        const cookie = req.headers.cookie ?? ''
+        if (!cookie.includes('session=') || expireNext) {
+          expireNext = false
+          res.writeHead(401).end()
+          return
+        }
+        res.writeHead(200, { 'content-type': 'application/json' }).end(
+          JSON.stringify({
+            rpcName: req.url.slice('/api/rpc/'.length),
+            echoed: body.data,
+            cookie,
+          })
+        )
+        return
+      }
+      res.writeHead(404).end()
+    })
+  })
+  await new Promise<void>((resolve) => server.listen(0, resolve))
+  const { port } = server.address() as { port: number }
+  return {
+    server,
+    apiUrl: `http://127.0.0.1:${port}/api`,
+    loginCount: () => logins,
+    expireSession: () => {
+      expireNext = true
+    },
+  }
+}
+
+describe('HttpUserFlowActor', async () => {
+  const target = await startTarget()
+  after(() => target.server.close())
+
+  const makeActors = (secret = 'impersonation-secret') =>
+    createHttpUserFlowActors({
+      apiUrl: target.apiUrl,
+      secret,
+      actors: {
+        customer: { email: 'customer@actors.local', jobTitle: 'Buyer' },
+        manager: { email: 'manager@actors.local' },
+      },
+    })
+
+  test('builds one lazy actor per config entry', () => {
+    const actors = makeActors()
+    assert.deepEqual(Object.keys(actors).sort(), ['customer', 'manager'])
+    assert.equal(actors.customer!.name, 'customer')
+    assert.equal(target.loginCount(), 0, 'no login until first invoke')
+  })
+
+  test('logs in lazily once and replays the session cookie on RPCs', async () => {
+    const actors = makeActors()
+
+    const first = (await actors.customer!.invoke('createTodo', { title: 'x' })) as any
+    const second = (await actors.customer!.invoke('listTodos', {})) as any
+
+    assert.equal(first.rpcName, 'createTodo')
+    assert.deepEqual(first.echoed, { title: 'x' })
+    assert.match(first.cookie, /session=s1/)
+    assert.match(first.cookie, /csrf=c1/)
+    assert.match(second.cookie, /session=s1/, 'session is cached, not re-minted')
+    assert.equal(target.loginCount(), 1)
+  })
+
+  test('re-logs-in once when the session expires mid-run', async () => {
+    const actors = makeActors()
+    await actors.manager!.invoke('ping', {})
+    const loginsBefore = target.loginCount()
+
+    target.expireSession()
+    const result = (await actors.manager!.invoke('ping', {})) as any
+
+    assert.equal(target.loginCount(), loginsBefore + 1, 'one re-login')
+    assert.match(result.cookie, new RegExp(`session=s${loginsBefore + 1}`))
+  })
+
+  test('a wrong impersonation secret surfaces status and body', async () => {
+    const actors = makeActors('wrong-secret')
+    await assert.rejects(
+      actors.customer!.invoke('ping', {}),
+      /actor sign-in failed for 'customer' \(401\).*bad actor secret/
+    )
+  })
+})

package/src/services/http-user-flow-actors.ts

@@ -0,0 +1,128 @@
+import type {
+  UserFlowActor,
+  UserFlowActorConfig,
+  UserFlowActors,
+} from './user-flow-actors-service.js'
+
+export interface HttpUserFlowActorsConfig {
+  /**
+   * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.
+   * `https://app.example.com/api` or `http://localhost:4000/api`. Actor
+   * sign-in is reached at `${apiUrl}${signInPath}` and exposed RPCs at
+   * `${apiUrl}${rpcPath}/:rpcName`.
+   */
+  apiUrl: string
+  /**
+   * The actor impersonation secret. Sign-in only ever works for user rows
+   * flagged `actor: true` — knowing the secret never impersonates real users.
+   */
+  secret: string
+  /** Actor name → config (usually from pikku.config.json's actor registry). */
+  actors: Record<string, UserFlowActorConfig>
+  /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
+  signInPath?: string
+  /** Exposed-RPC path prefix under apiUrl. Default `/rpc`. */
+  rpcPath?: string
+}
+
+/**
+ * Default HTTP-backed actor. Signs in lazily on first invoke via the Better
+ * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
+ * the plugin upserts the actor-flagged user row and mints a session whose
+ * `actor` flag flows into audits/analytics). Holds the session cookies for
+ * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
+ * outlive a session).
+ */
+export class HttpUserFlowActor implements UserFlowActor {
+  private cookie: string | null = null
+  private origin: string
+
+  constructor(
+    readonly name: string,
+    private actorConfig: UserFlowActorConfig,
+    private config: HttpUserFlowActorsConfig
+  ) {
+    this.origin = new URL(config.apiUrl).origin
+  }
+
+  async invoke(rpcName: string, data: unknown): Promise<unknown> {
+    const cookie = this.cookie ?? (await this.login())
+    const res = await this.postRpc(rpcName, data, cookie)
+    if (res.status === 401) {
+      // Session expired mid-run — re-login once and retry.
+      this.cookie = null
+      return this.readRpcResponse(rpcName, await this.postRpc(rpcName, data, await this.login()))
+    }
+    return this.readRpcResponse(rpcName, res)
+  }
+
+  private async postRpc(rpcName: string, data: unknown, cookie: string) {
+    const rpcPath = this.config.rpcPath ?? '/rpc'
+    return fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        origin: this.origin,
+        cookie,
+      },
+      body: JSON.stringify({ data }),
+    })
+  }
+
+  private async readRpcResponse(rpcName: string, res: Response) {
+    if (!res.ok) {
+      const body = (await res.text().catch(() => '')).slice(0, 300)
+      throw new Error(
+        `[user-flow] '${rpcName}' as '${this.name}' returned ${res.status}: ${body}`
+      )
+    }
+    if (res.status === 204) return undefined
+    const text = await res.text()
+    return text ? JSON.parse(text) : undefined
+  }
+
+  private async login(): Promise<string> {
+    const signInPath = this.config.signInPath ?? '/auth/sign-in/actor'
+    const res = await fetch(`${this.config.apiUrl}${signInPath}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', origin: this.origin },
+      body: JSON.stringify({
+        email: this.actorConfig.email,
+        name: this.actorConfig.name ?? this.name,
+        secret: this.config.secret,
+      }),
+    })
+    if (!res.ok) {
+      const body = (await res.text().catch(() => '')).slice(0, 300)
+      throw new Error(
+        `[user-flow] actor sign-in failed for '${this.name}' (${res.status}): ${body}`
+      )
+    }
+    const setCookies = res.headers.getSetCookie?.() ?? []
+    const cookie = setCookies
+      .map((c) => c.split(';')[0]!)
+      .filter(Boolean)
+      .join('; ')
+    if (!cookie) {
+      throw new Error(
+        `[user-flow] actor sign-in for '${this.name}' returned no session cookie`
+      )
+    }
+    this.cookie = cookie
+    return cookie
+  }
+}
+
+/**
+ * Build the injected `actors` service from the config registry: actor name →
+ * lazy HTTP actor. Wire the result as the `actors` singleton service.
+ */
+export function createHttpUserFlowActors(
+  config: HttpUserFlowActorsConfig
+): UserFlowActors {
+  const actors: UserFlowActors = {}
+  for (const [name, actorConfig] of Object.entries(config.actors)) {
+    actors[name] = new HttpUserFlowActor(name, actorConfig, config)
+  }
+  return actors
+}

package/src/services/index.ts

@@ -36,6 +36,16 @@ export type {
   WriteFileArgs,
   CopyFileArgs,
 } from './content-service.js'
+export type {
+  UserFlowActor,
+  UserFlowActorConfig,
+  UserFlowActors,
+} from './user-flow-actors-service.js'
+export {
+  HttpUserFlowActor,
+  createHttpUserFlowActors,
+  type HttpUserFlowActorsConfig,
+} from './http-user-flow-actors.js'
 export type { JWTService } from './jwt-service.js'
 export type {
   EmailService,

package/src/services/user-flow-actors-service.ts

@@ -0,0 +1,29 @@
+/**
+ * A user-flow actor: a synthetic user (a normal user row flagged `actor`) that
+ * workflow steps can run as. Passed to `workflow.do(step, rpc, data, { actor })`
+ * — the step then goes through the actor's authenticated client over the REAL
+ * transport (auth middleware, permissions, serialization all exercised),
+ * never through internal dispatch. Login is lazy: the first `invoke` signs the
+ * actor in and the session is cached for the actor's lifetime.
+ */
+export interface UserFlowActor {
+  /** Stable actor name (the key in pikku.config.json's actor registry). */
+  readonly name: string
+  /** Invoke an exposed RPC as this actor over the real transport. */
+  invoke(rpcName: string, data: unknown): Promise<unknown>
+}
+
+/**
+ * Display/config metadata for an actor (from pikku.config.json). The email
+ * identifies the actor's user row; personality/jobTitle exist for the console
+ * screen and for agent-driven flows (the agent plays the persona).
+ */
+export interface UserFlowActorConfig {
+  email: string
+  name?: string
+  jobTitle?: string
+  personality?: string
+}
+
+/** The injected `actors` service: actor name → actor. */
+export type UserFlowActors = Record<string, UserFlowActor>

package/src/types/core.types.ts

@@ -29,6 +29,7 @@ import type { DeploymentService } from '../services/deployment-service.js'
 import type { AIStorageService } from '../services/ai-storage-service.js'
 
 import type { ContentService } from '../services/content-service.js'
+import type { UserFlowActors } from '../services/user-flow-actors-service.js'
 import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js'
 import type { AIRunStateService } from '../services/ai-run-state-service.js'
 import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js'
@@ -243,6 +244,8 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
 export interface CoreUserSession {
   userId?: string
   orgId?: string
+  /** True when the session belongs to a synthetic user-flow actor — lets audits/analytics address synthetic traffic */
+  actor?: boolean
 }
 
 /**
@@ -336,6 +339,8 @@ export type PikkuWire<
   queue: PikkuQueue
   cli: PikkuCLI
   workflow: TypedWorkflow
+  /** User-flow actor registry (user-flow runs only) — pass into workflow.do as `{ actor: actors.x }` */
+  actors: UserFlowActors
   workflowStep: WorkflowStepWire
   graph: PikkuGraphWire
   trigger: PikkuTrigger<TriggerOutput>

package/src/wirings/workflow/dsl/workflow-dsl.types.ts

@@ -4,6 +4,7 @@
  */
 
 import type { WorkflowRun } from '../workflow.types.js'
+import type { UserFlowActor } from '../../../services/user-flow-actors-service.js'
 
 /**
  * Workflow step options
@@ -15,9 +16,27 @@ export interface WorkflowStepOptions {
   retries?: number
   /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
   retryDelay?: string | number
+  /**
+   * Run this step as an actor (user flows). The RPC is sent through the
+   * actor's authenticated client over the REAL transport — never dispatched
+   * internally — so auth middleware and permissions are exercised end-to-end.
+   * The step is recorded durably like any RPC step.
+   */
+  actor?: UserFlowActor
   // Future: timeout, failFast, priority
 }
 
+/**
+ * Options for workflow.expectEventually() — a durable polling step used by
+ * user flows to await async effects (a notification landing, a job finishing).
+ */
+export interface WorkflowExpectEventuallyOptions extends WorkflowStepOptions {
+  /** Give up after this long (e.g. '30s'). Default '30s'. */
+  within?: string | number
+  /** Poll interval (e.g. '1s'). Default '1s'. */
+  interval?: string | number
+}
+
 /**
  * Type signature for workflow.do() RPC form - used by inspector
  */
@@ -346,6 +365,18 @@ export interface PikkuWorkflowWire {
   /** Execute a workflow step (overloaded - RPC or inline form) */
   do: WorkflowWireDoRPC & WorkflowWireDoInline
 
+  /**
+   * Durable polling step (user flows): invoke `rpcName` (as an actor when
+   * `options.as` is set) until `predicate` passes or `options.within` elapses.
+   */
+  expectEventually: <TOutput = any, TInput = any>(
+    stepName: string,
+    rpcName: string,
+    data: TInput,
+    predicate: (output: TOutput) => boolean,
+    options?: WorkflowExpectEventuallyOptions
+  ) => Promise<TOutput>
+
   /** Sleep for a duration */
   sleep: WorkflowWireSleep