@pikku/core 0.12.94 → 0.12.95

package/src/services/email-template.ts

@@ -0,0 +1,254 @@
+/**
+ * The renderer behind a generated `pikku-emails.gen.ts`.
+ *
+ * The generated module supplies the assets — theme, locale strings, partials and
+ * the templates themselves — and a typed wrapper over `renderEmail`. Everything
+ * here is the same for every application, which is why it lives in core rather
+ * than in the string the CLI writes: this is HTML escaping, and code inside a
+ * template literal is never compiled, never linted, and testable only by
+ * matching the text it emits.
+ */
+
+export interface EmailTemplateHashes {
+  contentHash: string
+  htmlHash: string
+  subjectHash: string
+  textHash: string
+}
+
+export interface EmailTemplateAssets {
+  html: string
+  subject: string
+  text: string
+  variables: ReadonlyArray<string>
+  hashes: Record<string, EmailTemplateHashes>
+}
+
+export interface EmailAssets {
+  theme: Record<string, unknown>
+  locales: Record<string, Record<string, unknown>>
+  partials: Record<string, string>
+  templates: Record<string, EmailTemplateAssets>
+}
+
+export interface RenderEmailRequest {
+  name: string
+  locale?: string
+  data?: Record<string, unknown>
+}
+
+export interface RenderedEmailResult {
+  locale: string
+  subject: string
+  html: string
+  text?: string
+  variables: ReadonlyArray<string>
+  hash: string
+}
+
+const HTML_ESCAPES: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+}
+
+const escapeHtml = (value: string): string =>
+  value.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char] ?? char)
+
+// Matches the raw {{{ value }}} form before the escaped {{ value }} form, so the
+// opt-in escape hatch is never mistaken for a normal substitution.
+const TEMPLATE_TOKEN = /\{\{\{\s*([^{}]+?)\s*\}\}\}|\{\{\s*([^}]+?)\s*\}\}/g
+
+const PARTIAL_TOKEN = /\{\{\s*>\s*([a-zA-Z0-9-_/.]+)\s*\}\}/g
+
+const MAX_TEMPLATE_DEPTH = 5
+
+// theme.json and the locale files ship with the templates, so they are treated as
+// template-author input: expanded before caller data and allowed to contain their
+// own placeholders. Everything else is caller-supplied.
+const TRUSTED_ROOTS = ['theme', 't']
+
+const isTrustedKey = (key: string): boolean =>
+  TRUSTED_ROOTS.includes(String(key.split('.')[0]))
+
+const getNestedValue = (
+  source: Record<string, unknown>,
+  path: string
+): string => {
+  const segments = path.split('.')
+  let current: unknown = source
+  for (const segment of segments) {
+    // `hasOwn`, not `in`: `in` walks the prototype chain, so a path is answered
+    // by what an object inherits rather than only by what it carries. Nothing
+    // inherited reaches the output today — every step past a prototype hit lands
+    // on a function, which is neither traversed nor written — so this closes the
+    // lookup rather than fixing a value that escapes through it.
+    if (
+      !current ||
+      typeof current !== 'object' ||
+      !Object.hasOwn(current, segment)
+    ) {
+      return ''
+    }
+    current = (current as Record<string, unknown>)[segment]
+  }
+  return typeof current === 'string' || typeof current === 'number'
+    ? String(current)
+    : ''
+}
+
+const readToken = (rawTriple: unknown, rawDouble: unknown) => {
+  const raw = typeof rawTriple === 'string'
+  return { raw, key: String(raw ? rawTriple : rawDouble).trim() }
+}
+
+const expandPartials = (
+  source: string,
+  partials: Record<string, string>,
+  depth = 0
+): string => {
+  if (depth >= MAX_TEMPLATE_DEPTH) return source
+  let found = false
+  const expanded = source.replace(PARTIAL_TOKEN, (_match, partialName) => {
+    found = true
+    const partial = partials[String(partialName).trim()]
+    return typeof partial === 'string' ? partial : ''
+  })
+  return found ? expandPartials(expanded, partials, depth + 1) : expanded
+}
+
+const expandTrusted = (
+  source: string,
+  context: Record<string, unknown>,
+  escape: boolean
+): string => {
+  let rendered = source
+  for (let i = 0; i < MAX_TEMPLATE_DEPTH; i += 1) {
+    let found = false
+    const next = rendered.replace(
+      TEMPLATE_TOKEN,
+      (match, rawTriple, rawDouble) => {
+        const { raw, key } = readToken(rawTriple, rawDouble)
+        if (!isTrustedKey(key)) return match
+        found = true
+        const value = getNestedValue(context, key)
+        return raw || !escape ? value : escapeHtml(value)
+      }
+    )
+    if (!found || next === rendered) break
+    rendered = next
+  }
+  return rendered
+}
+
+// A single substitution pass — the replacement text is never rescanned, so a
+// caller-supplied value can never be reinterpreted as a template.
+const substitute = (
+  source: string,
+  context: Record<string, unknown>,
+  escape: boolean,
+  slot?: string
+): string =>
+  source.replace(TEMPLATE_TOKEN, (_match, rawTriple, rawDouble) => {
+    const { raw, key } = readToken(rawTriple, rawDouble)
+    // `content` is the layout's slot for the body that was already rendered and
+    // escaped, so it is the one value written in raw. Only the layout gets it:
+    // honouring it everywhere would let a caller pass `data.content` into a
+    // template that happens to name it and have it emitted unescaped.
+    if (slot !== undefined && key === slot) {
+      return typeof context[slot] === 'string' ? (context[slot] as string) : ''
+    }
+    if (key.startsWith('>')) {
+      return ''
+    }
+    const value = getNestedValue(context, key)
+    return raw || !escape ? value : escapeHtml(value)
+  })
+
+const renderTemplate = (
+  source: string,
+  partials: Record<string, string>,
+  context: Record<string, unknown>,
+  escape: boolean,
+  slot?: string
+): string => {
+  const composed = expandTrusted(
+    expandPartials(source, partials),
+    context,
+    escape
+  )
+  return substitute(composed, context, escape, slot)
+}
+
+export const renderEmail = (
+  { theme, locales, partials, templates }: EmailAssets,
+  { name, locale: requestedLocale, data }: RenderEmailRequest
+): RenderedEmailResult => {
+  const locale = requestedLocale ?? 'en'
+  const template = templates[name]
+  if (!template) {
+    throw new Error(`Unknown email template: ${name}`)
+  }
+
+  const strings = locales[locale]
+  if (!strings) {
+    throw new Error(`Unknown email locale: ${locale}`)
+  }
+
+  const values = data ?? {}
+  const appName =
+    (typeof values.appName === 'string' && values.appName) ||
+    getNestedValue(theme, 'appName')
+
+  const baseContext = {
+    ...values,
+    locale,
+    theme,
+    t: strings,
+    appName,
+  }
+
+  const subject = renderTemplate(
+    template.subject,
+    partials,
+    baseContext,
+    false
+  ).trim()
+
+  const htmlBody = renderTemplate(
+    template.html,
+    partials,
+    { ...baseContext, subject },
+    true
+  )
+
+  const html = partials.layout
+    ? renderTemplate(
+        partials.layout,
+        partials,
+        { ...baseContext, subject, content: htmlBody },
+        true,
+        'content'
+      )
+    : htmlBody
+
+  const text = template.text
+    ? renderTemplate(
+        template.text,
+        partials,
+        { ...baseContext, subject },
+        false
+      ).trim()
+    : undefined
+
+  return {
+    locale,
+    subject,
+    html,
+    ...(text ? { text } : {}),
+    variables: template.variables,
+    hash: template.hashes[locale]?.contentHash ?? '',
+  }
+}

package/src/services/http-personas.ts

@@ -51,7 +51,12 @@ export interface HttpPersonasConfig {
   operator?: OperatorSignInOptions
   /** Persona id → the declaration with its address filled in. */
   personas: Record<string, ResolvedPersona>
-  /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
+  /**
+   * Sign-in path under apiUrl, for whichever of the two paths is in use — an
+   * app that mounts auth under `/api` moves both. Default: the actor plugin's
+   * `/auth/sign-in/actor`, or `/auth/sign-in/fabric` for an operator.
+   * {@link OperatorSignInOptions.signInPath} overrides it.
+   */
   signInPath?: string
   /** Where the session (and its roles) is read back. Default `/auth/get-session`. */
   sessionPath?: string
@@ -92,7 +97,10 @@ export class HttpPersona implements ScenarioPersona {
   ) {
     this.jar = createCookieJar(config.apiUrl)
     if (config.operator) {
-      this.signIn = new OperatorSignIn(config.apiUrl, config.operator)
+      this.signIn = new OperatorSignIn(config.apiUrl, {
+        ...config.operator,
+        signInPath: config.operator.signInPath ?? config.signInPath,
+      })
     } else if (config.secret) {
       this.signIn = new ActorSignIn(
         config.apiUrl,

package/src/services/index.ts

@@ -53,6 +53,14 @@ export type {
   SendTemplateEmailInput,
   SendTextEmailInput,
 } from './email-service.js'
+export {
+  renderEmail,
+  type EmailAssets,
+  type EmailTemplateAssets,
+  type EmailTemplateHashes,
+  type RenderEmailRequest,
+  type RenderedEmailResult,
+} from './email-template.js'
 export {
   DEFAULT_WEBHOOK_RETRIES,
   PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,

package/src/services/persona-sign-in.test.ts

@@ -115,6 +115,28 @@ describe('operator persona sign-in', () => {
     assert.equal(stage.createdCount, 0)
   })
 
+  // An app that mounts auth somewhere other than the root moves both sign-in
+  // paths together, and `SCENARIO_SIGN_IN_PATH` is the only place it can say so.
+  test('honours a moved sign-in path the same way the actor path does', async () => {
+    const stage = await startStage([
+      { id: 'user-7', email: 'customer@personas.invalid' },
+    ])
+    servers.push(stage.server)
+
+    const personas = createHttpPersonas({
+      apiUrl: stage.apiUrl.replace(/\/api$/, ''),
+      operator: { token: OPERATOR_TOKEN },
+      signInPath: '/api/auth/sign-in/fabric',
+      rpcPath: '/api/rpc',
+      personas: { customer: persona('customer@personas.invalid') },
+    })
+
+    const result = (await personas.customer!.invoke('whoami', {})) as {
+      actingAs: string | null
+    }
+    assert.equal(result.actingAs, 'user-7')
+  })
+
   test('refuses a persona the stage has no account for', async () => {
     const stage = await startStage([])
     servers.push(stage.server)

package/src/wirings/agent/agent-helpers.test.ts

@@ -6,6 +6,7 @@ import {
   agentResume,
   agentApprove,
 } from './agent-helpers.js'
+import { agentCallOptions } from './agent-prepare.js'
 
 describe('agent helpers', () => {
   describe('agent', () => {
@@ -150,3 +151,65 @@ describe('agent helpers', () => {
     })
   })
 })
+
+describe('agentCallOptions', () => {
+  // An explicit `undefined` overrides the agent's own declared default with
+  // nothing, so a request that names no model would silently unset the one the
+  // agent declares.
+  test('a field nobody supplied is left out rather than sent as undefined', () => {
+    const options = agentCallOptions({
+      message: 'hello',
+      threadId: 't1',
+      resourceId: 'r1',
+    })
+    assert.equal('model' in options, false)
+    assert.equal('temperature' in options, false)
+    assert.equal('context' in options, false)
+    assert.equal('attachments' in options, false)
+  })
+
+  test('what was supplied is carried through unchanged', () => {
+    const options = agentCallOptions({
+      message: 'hello',
+      threadId: 't1',
+      resourceId: 'user-1',
+      model: 'a-model',
+      temperature: 0.2,
+      context: 'some context',
+      attachments: [{ type: 'image' as const, url: 'a.png' }],
+    })
+    assert.deepEqual(options, {
+      message: 'hello',
+      threadId: 't1',
+      resourceId: 'user-1',
+      attachments: [{ type: 'image' as const, url: 'a.png' }],
+      model: 'a-model',
+      temperature: 0.2,
+      context: 'some context',
+    })
+  })
+
+  // Zero is a temperature a caller can mean, and the falsy check every other
+  // field uses would drop it.
+  test('a temperature of zero survives, unlike an empty string', () => {
+    assert.equal(
+      agentCallOptions({
+        message: 'x',
+        threadId: 't',
+        resourceId: 'r',
+        temperature: 0,
+      }).temperature,
+      0
+    )
+    assert.equal(
+      'context' in
+        agentCallOptions({
+          message: 'x',
+          threadId: 't',
+          resourceId: 'r',
+          context: '',
+        }),
+      false
+    )
+  })
+})

package/src/wirings/agent/agent-prepare.ts

@@ -149,6 +149,31 @@ export function canAccessThread(
   )
 }
 
+/**
+ * An agent call with the fields nobody supplied left out.
+ *
+ * Omitted rather than passed as `undefined`, because an explicit `undefined`
+ * overrides the agent's own declared default with nothing — a request that
+ * names no model would silently unset the one the agent declares.
+ *
+ * Shared by the scaffolded `run` and `stream` routes, which receive the same
+ * input and differ only in what they do with the reply. `agentName` is not part
+ * of it: both callers pass that separately, because `rpc.agent.run` and
+ * `rpc.agent.stream` take it as their first argument and type the rest
+ * against it.
+ */
+export const agentCallOptions = (input: AgentInput): AgentInput => ({
+  message: input.message,
+  threadId: input.threadId,
+  resourceId: input.resourceId,
+  ...(input.attachments ? { attachments: input.attachments } : {}),
+  ...(input.model ? { model: input.model } : {}),
+  ...(input.temperature !== undefined
+    ? { temperature: input.temperature }
+    : {}),
+  ...(input.context ? { context: input.context } : {}),
+})
+
 export type StreamAgentOptions = {
   requiresToolApproval?: 'all' | 'explicit' | false
   onRunCreated?: (runId: string) => void

package/src/wirings/agent/index.ts

@@ -33,6 +33,7 @@ export {
   type StreamAgentOptions,
   ToolApprovalRequired,
   ToolCredentialRequired,
+  agentCallOptions,
   canAccessThread,
   isOwnedByPrincipal,
   threadOwnerConstraint,

package/src/wirings/scheduler/scheduler-runner.test.ts

@@ -213,6 +213,97 @@ describe('runScheduledTask', () => {
     assert.deepEqual(receivedSession, session)
   })
 
+  test('a task middleware can set the session the task runs as', async () => {
+    let frozenSession: CoreUserSession | undefined
+    const machineSession: CoreUserSession = {
+      userId: 'cron:machine-session-task',
+    }
+
+    const mockTask: CoreScheduledTask = {
+      name: 'machine-session-task',
+      schedule: '0 0 * * *',
+      middleware: [
+        async (_services: any, wire: any, next: any) => {
+          wire.setSession(machineSession)
+          return next()
+        },
+      ] as any,
+      func: {
+        func: async (_services: any, _data: any, wire: any) => {
+          frozenSession = wire.session
+        },
+        auth: false,
+      },
+    }
+
+    pikkuState(null, 'scheduler', 'meta')['machine-session-task'] = {
+      pikkuFuncId: 'scheduler_machine-session-task',
+      name: 'machine-session-task',
+      schedule: '0 0 * * *',
+    }
+    pikkuState(null, 'function', 'meta')['scheduler_machine-session-task'] = {
+      pikkuFuncId: 'scheduler_machine-session-task',
+      inputSchemaName: null,
+      outputSchemaName: null,
+      sessionless: true,
+    }
+    wireScheduler(mockTask)
+
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: createMockLogger(),
+    } as any)
+
+    await runScheduledTask({ name: 'machine-session-task' })
+
+    assert.deepEqual(frozenSession, machineSession)
+  })
+
+  test('a session-taking task does not warn that auth was disabled', async () => {
+    const mockTask: CoreScheduledTask = {
+      name: 'identified-task',
+      schedule: '0 0 * * *',
+      middleware: [
+        async (_services: any, wire: any, next: any) => {
+          wire.setSession({ userId: 'cron:identified-task' })
+          return next()
+        },
+      ] as any,
+      func: {
+        func: async () => {},
+      },
+    }
+
+    pikkuState(null, 'scheduler', 'meta')['identified-task'] = {
+      pikkuFuncId: 'scheduler_identified-task',
+      name: 'identified-task',
+      schedule: '0 0 * * *',
+    }
+    pikkuState(null, 'function', 'meta')['scheduler_identified-task'] = {
+      pikkuFuncId: 'scheduler_identified-task',
+      inputSchemaName: null,
+      outputSchemaName: null,
+      sessionless: false,
+    }
+    wireScheduler(mockTask)
+
+    const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
+
+    await runScheduledTask({ name: 'identified-task' })
+
+    assert.deepEqual(
+      mockLogger
+        .getLogs()
+        .filter(
+          (log) =>
+            log.level === 'warn' && /auth was explicitly disabled/.test(log.message)
+        ),
+      []
+    )
+  })
+
   test('should throw ScheduledTaskNotFoundError when task not found', async () => {
     const mockLogger = createMockLogger()
     pikkuState(null, 'package', 'singletonServices', {
@@ -655,3 +746,90 @@ describe('getScheduledTasks', () => {
     assert.equal(tasks.size, 0)
   })
 })
+
+/**
+ * A cron has no caller to authenticate, so the only thing that can give it an
+ * identity is its own wiring. These cover the mechanism the virtual-user
+ * scaffold's `virtualUserPlatformSession` relies on: middleware on the task
+ * sets the session, and the scope gate on the function it drives is enforced
+ * against exactly that session — a tick with no identity, or one holding the
+ * wrong scope, is refused the same way a person would be.
+ */
+describe('a scheduled task authorizes on the session its own middleware sets', () => {
+  const wireGatedTask = (
+    name: string,
+    middleware?: Array<
+      (services: any, wire: any, next: any) => Promise<void> | void
+    >
+  ) => {
+    let seen: CoreUserSession | undefined
+    const task: CoreScheduledTask = {
+      name,
+      schedule: '0 * * * *',
+      func: {
+        func: async (_services: any, _data: any, wire: any) => {
+          seen = await wire.getSession()
+        },
+      } as any,
+      middleware,
+    }
+    pikkuState(null, 'scheduler', 'meta')[name] = {
+      pikkuFuncId: `scheduler_${name}`,
+      name,
+      schedule: '0 * * * *',
+    }
+    pikkuState(null, 'function', 'meta')[`scheduler_${name}`] = {
+      pikkuFuncId: `scheduler_${name}`,
+      inputSchemaName: null,
+      outputSchemaName: null,
+      sessionless: false,
+      scopes: ['virtualUser:run'],
+    }
+    wireScheduler(task)
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: createMockLogger(),
+    } as any)
+    return () => seen
+  }
+
+  const settingSession = (session: CoreUserSession) => [
+    async (_services: any, wire: any, next: any) => {
+      await wire.setSession(session)
+      return next()
+    },
+  ]
+
+  test('is refused outright when nothing gives the tick an identity', async () => {
+    wireGatedTask('unidentified-tick')
+    await assert.rejects(
+      runScheduledTask({ name: 'unidentified-tick' }),
+      /Authentication required/
+    )
+  })
+
+  test('is refused when the identity it sets holds the wrong scope', async () => {
+    wireGatedTask(
+      'misscoped-tick',
+      settingSession({
+        userId: 'pikku-platform',
+        scopes: ['admin'],
+      } as CoreUserSession)
+    )
+    await assert.rejects(
+      runScheduledTask({ name: 'misscoped-tick' }),
+      /virtualUser:run/
+    )
+  })
+
+  test('runs as the platform user its middleware set', async () => {
+    const seen = wireGatedTask(
+      'platform-tick',
+      settingSession({
+        userId: 'pikku-platform',
+        scopes: ['virtualUser:run'],
+      } as CoreUserSession)
+    )
+    await runScheduledTask({ name: 'platform-tick' })
+    assert.equal(seen()?.userId, 'pikku-platform')
+  })
+})

package/src/wirings/scheduler/scheduler-runner.ts

@@ -116,7 +116,6 @@ export async function runScheduledTask({
     await runPikkuFunc('scheduler', meta.name, meta.pikkuFuncId, {
       singletonServices,
       createWireServices,
-      auth: false,
       data: () => undefined,
       inheritedMiddleware: meta.middleware,
       wireMiddleware: task.middleware,

package/src/wirings/virtual-user/index.ts

@@ -85,3 +85,23 @@ export {
   personaVirtualUserTarget,
   type PersonaTargetOptions,
 } from './virtual-user-target.js'
+export {
+  executeVirtualUserRun,
+  logVirtualUserTick,
+  requireVirtualUserRunStore,
+  requireVirtualUserScheduleStore,
+  runnablePersona,
+  serializeVirtualUserRun,
+  serializeVirtualUserSchedule,
+  serializeVirtualUserSteps,
+  signInPathFor,
+  startVirtualUserRun,
+  VIRTUAL_USER_VARIABLES,
+  virtualUserScheduleRunInput,
+  writeVirtualUserSchedule,
+  type ExecuteVirtualUserRunParams,
+  type ScaffoldPersonas,
+  type StartedVirtualUserRun,
+  type StartVirtualUserRunParams,
+  type WriteVirtualUserScheduleParams,
+} from './virtual-user-scaffold.js'

package/src/wirings/virtual-user/virtual-user-derive.test.ts

@@ -396,3 +396,31 @@ describe('driving a virtual user through a signed-in actor', () => {
     assert.match(verdict.reasoning, /no assistant called 'concierge'/)
   })
 })
+
+// An adversarial run's transcript is working exploits against this same app,
+// and a schedule outlives the run that wrote it. Neither belongs in the hands
+// of the thing being run.
+test('a virtual user is never offered the machinery that runs virtual users', () => {
+  const catalogue = deriveCatalogue({
+    runVirtualUser: {
+      name: 'runVirtualUser',
+      expose: true,
+      scopes: ['virtualUser:run'],
+    },
+    getVirtualUserRunSteps: {
+      name: 'getVirtualUserRunSteps',
+      expose: true,
+      scopes: ['virtualUser:read'],
+    },
+    listBookings: {
+      name: 'listBookings',
+      expose: true,
+      scopes: ['bookings:read'],
+    },
+  } as any)
+
+  assert.deepEqual(
+    catalogue.map((entry) => entry.name),
+    ['listBookings']
+  )
+})