@pikku/core 0.12.107 → 0.12.111

package/src/services/personas-service.ts

@@ -1,191 +0,0 @@
-import type {
-  ConverseOptions,
-  ActorFlowVerdict,
-} from '../wirings/actor-flow/actor-flow.types.js'
-import type { PersonaMeta } from '../wirings/persona/persona.types.js'
-
-/**
- * What the transport answered, for a step that treats the status as data.
- *
- * An HTTP response with its body already drained: the stream can only be read
- * once, and a step's return value crosses into the run record, so the response
- * object itself cannot travel. This is the shape every caller ends up with.
- */
-export interface ScenarioHttpResponse<T = unknown> {
-  status: number
-  ok: boolean
-  /**
-   * The parsed JSON body — or, when the body was not JSON, the raw text it was
-   * parsed from, so an HTML error page is still readable rather than lost.
-   * `undefined` for an empty response.
-   *
-   * `T` is a claim the caller makes, not one the transport checked: a step that
-   * knows the route's payload names it here instead of casting at every use.
-   */
-  body: T
-  /**
-   * The whole body as text, so an assertion can search it without knowing the
-   * payload's shape — and so an error body that is HTML rather than JSON still
-   * says what went wrong.
-   */
-  serialized: string
-}
-
-/**
- * Drain a response into the shape a step can carry: the parsed body (an empty
- * one counting as no body at all) alongside the text it was parsed from.
- *
- * `invokeRaw` returns this, and a step that has to reach past a persona — a
- * route with no RPC, an identity no persona can hold — reaches for this rather
- * than writing the same record by hand.
- *
- * @example snippet: scenarioPolling
- */
-export const readScenarioHttpResponse = async <T = unknown>(
-  res: Response
-): Promise<ScenarioHttpResponse<T>> => {
-  const text = res.status === 204 ? '' : await res.text().catch(() => '')
-  return {
-    status: res.status,
-    ok: res.ok,
-    body: (text ? parseJsonBody(text) : undefined) as T,
-    serialized: text,
-  }
-}
-
-const parseJsonBody = (text: string): unknown => {
-  try {
-    return JSON.parse(text)
-  } catch {
-    return text
-  }
-}
-
-/** How to send one JSON request, for `postScenarioJson`. */
-export interface ScenarioJsonRequest {
-  /** Serialised as the JSON body. Omit for a request that carries none. */
-  body?: unknown
-  /** Sent alongside `content-type: application/json`, and may override it. */
-  headers?: Record<string, string>
-  /** Defaults to `POST` — the method every scenario route here answers. */
-  method?: string
-  /**
-   * The `fetch` to send it with. Pass a `ScenarioCookieJar`'s to keep the
-   * session; the global `fetch` otherwise, which is what a step asserting on a
-   * sessionless call wants.
-   */
-  fetch?: typeof fetch
-}
-
-/**
- * POST JSON somewhere and report what came back, without throwing on a 4xx/5xx.
- *
- * Every scenario that reaches past a persona was writing this by hand — the same
- * `content-type`, the same `JSON.stringify`, the same drain — and the copies had
- * drifted: some returned `res.json()`, which loses the status and throws
- * outright when the target answers an empty body or an HTML error page. A
- * refusal is the expected outcome of a permissions scenario, so it has to
- * survive as data.
- *
- * @example snippet: scenarioHttpStep
- */
-export const postScenarioJson = async <T = unknown>(
-  url: string,
-  {
-    body,
-    headers,
-    method = 'POST',
-    fetch: send = fetch,
-  }: ScenarioJsonRequest = {}
-): Promise<ScenarioHttpResponse<T>> =>
-  readScenarioHttpResponse<T>(
-    await send(url, {
-      method,
-      headers: { 'content-type': 'application/json', ...headers },
-      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-    })
-  )
-
-/** Per-call transport options. */
-export interface ScenarioInvokeOptions {
-  /**
-   * Headers to send alongside the persona's own session. This is how a step
-   * expresses an identity no declared persona can — an impersonation header, or
-   * one of the header-shim principals a credential scenario invents.
-   */
-  headers?: Record<string, string>
-}
-
-/**
- * The RPC surface a persona can reach, as name → input/output. A project binds
- * its generated exposed RPC map here; the default leaves every name open, which
- * is what a persona built by hand (or by a third-party driver) gets.
- */
-export type ScenarioRpcMap = Record<string, { input: any; output: any }>
-
-/**
- * The persona a step's `actor` slot carries, for a project whose personas are
- * known. No declared personas keeps the open type rather than collapsing to
- * `never` — a project may still build one itself.
- */
-export type ScenarioPersonaOf<TPersonas> = [keyof TPersonas] extends [never]
-  ? ScenarioPersona
-  : TPersonas[keyof TPersonas]
-
-/**
- * A declared person, signed in and acting over the real transport.
- *
- * The runtime half of `definePersonas()`: sign-in materialises a user row
- * flagged `actor: true`, and everything a step or a virtual user does goes
- * through here.
- */
-export interface ScenarioPersona<
-  TAgentName extends string = string,
-  TRpcMap extends ScenarioRpcMap = ScenarioRpcMap,
-> {
-  /** The id it was declared under — what a step's `actor` slot names. */
-  readonly name: string
-  /** Their address, computed from the id. Flows use it for invites/lookups. */
-  readonly email: string
-  /** Invoke an exposed RPC as this person over the real transport. */
-  invoke<TName extends keyof TRpcMap & string>(
-    rpcName: TName,
-    data: TRpcMap[TName]['input']
-  ): Promise<TRpcMap[TName]['output']>
-  /**
-   * The same call, reporting what the transport answered rather than throwing.
-   * A refusal is the expected outcome of a permissions or scopes scenario, and
-   * `invoke`'s error truncates the body that names which scope was missing.
-   */
-  invokeRaw<TName extends keyof TRpcMap & string>(
-    rpcName: TName,
-    data: TRpcMap[TName]['input'],
-    options?: ScenarioInvokeOptions
-  ): Promise<ScenarioHttpResponse>
-  /** Converse with a Pikku AI agent in character and return its verdict. */
-  converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>
-  /**
-   * The roles this person actually holds on the stage, read back after signing
-   * in — what a run compares against the declaration before its first step.
-   *
-   * `null` when the target does not say. That is not the same as "no roles": a
-   * run that treats silence as an empty list refuses to start against every
-   * stage whose auth reports roles somewhere else, so the caller must decide
-   * whether it can verify at all.
-   */
-  sessionRoles(): Promise<string[] | null>
-}
-
-/**
- * A declared persona with its address filled in — what codegen writes and what
- * a seed, a scenario run and a virtual-user run all read.
- *
- * The address is not declared. It is derived from the persona's id and the
- * project's persona domain, so two people can never accidentally share one and
- * sign in as the same user row — which would silently collapse exactly the
- * isolation scenarios a second person exists for.
- */
-export type ResolvedPersona = PersonaMeta & { email: string }
-
-/** The injected `personas` service: persona id → persona. */
-export type ScenarioPersonas = Record<string, ScenarioPersona>

package/src/services/pikku-user-id.test.ts

@@ -1,62 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert'
-import { defaultPikkuUserIdResolver } from './pikku-user-id.js'
-import type { PikkuWire } from '../types/core.types.js'
-
-describe('defaultPikkuUserIdResolver', () => {
-  test('should return pikkuUserId from wire', () => {
-    const wire: PikkuWire = { pikkuUserId: 'user-1' }
-    assert.strictEqual(defaultPikkuUserIdResolver(wire), 'user-1')
-  })
-
-  test('should return userId from session', () => {
-    const wire: PikkuWire = { session: { userId: 'session-user' } as any }
-    assert.strictEqual(defaultPikkuUserIdResolver(wire), 'session-user')
-  })
-
-  test('should prefer pikkuUserId over session', () => {
-    const wire: PikkuWire = {
-      pikkuUserId: 'explicit',
-      session: { userId: 'session-user' } as any,
-    }
-    assert.strictEqual(defaultPikkuUserIdResolver(wire), 'explicit')
-  })
-
-  test('should return pikkuUserId from queue', () => {
-    const wire: PikkuWire = {
-      queue: {
-        queueName: 'test',
-        jobId: '1',
-        pikkuUserId: 'queue-user',
-        updateProgress: async () => {},
-        fail: async () => {},
-        discard: async () => {},
-      },
-    }
-    assert.strictEqual(defaultPikkuUserIdResolver(wire), 'queue-user')
-  })
-
-  test('should return pikkuUserId from workflow', () => {
-    const wire: PikkuWire = {
-      workflow: {
-        name: 'test',
-        runId: '1',
-        pikkuUserId: 'workflow-user',
-        getRun: async () => ({}) as any,
-        do: (() => {}) as any,
-        sleep: (() => {}) as any,
-      } as any,
-    }
-    assert.strictEqual(defaultPikkuUserIdResolver(wire), 'workflow-user')
-  })
-
-  test('should return undefined when no identity source', () => {
-    const wire: PikkuWire = {}
-    assert.strictEqual(defaultPikkuUserIdResolver(wire), undefined)
-  })
-
-  test('should ignore non-string session userId', () => {
-    const wire: PikkuWire = { session: { userId: 123 } as any }
-    assert.strictEqual(defaultPikkuUserIdResolver(wire), undefined)
-  })
-})

package/src/services/pikku-user-id.ts

@@ -1,13 +0,0 @@
-import type { PikkuRawWire } from '../types/core.types.js'
-
-export type PikkuUserIdResolver = (wire: PikkuRawWire) => string | undefined
-
-export const defaultPikkuUserIdResolver: PikkuUserIdResolver = (wire) => {
-  if (wire.pikkuUserId) return wire.pikkuUserId
-  const session = wire.session as Record<string, unknown> | undefined
-  if (session?.userId && typeof session.userId === 'string')
-    return session.userId
-  if (wire.queue?.pikkuUserId) return wire.queue.pikkuUserId
-  if (wire.workflow?.pikkuUserId) return wire.workflow.pikkuUserId
-  return undefined
-}

package/src/services/queue-webhook-service.test.ts

@@ -1,409 +0,0 @@
-import { describe, test, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-import { createHmac } from 'node:crypto'
-
-import {
-  QueueWebhookService,
-  pikkuWebhookWorkerFunc,
-} from './queue-webhook-service.js'
-import {
-  PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,
-  type WebhookJobData,
-} from './webhook-service.js'
-import { InMemoryQueueService } from './in-memory-queue-service.js'
-import { wireQueueWorker } from '../wirings/queue/queue-runner.js'
-import { resetPikkuState, pikkuState } from '../pikku-state.js'
-import type { JobOptions } from '../wirings/queue/queue.types.js'
-import { createSecretValue } from '../classification/secret-value.js'
-
-const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
-
-interface CapturedAdd {
-  queueName: string
-  data: WebhookJobData
-  options?: JobOptions
-}
-
-const setupServices = (overrides: Record<string, unknown> = {}) => {
-  const added: CapturedAdd[] = []
-  const queueService = {
-    supportsResults: false,
-    add: async (
-      queueName: string,
-      data: WebhookJobData,
-      options?: JobOptions
-    ) => {
-      added.push({ queueName, data, options })
-      return 'job-1'
-    },
-    getJob: async () => null,
-  }
-  pikkuState(null, 'package', 'singletonServices', {
-    logger: noopLogger,
-    config: {},
-    secrets: {
-      getSecret: async (key: string) => {
-        throw new Error(`Secret not found: ${key}`)
-      },
-    },
-    queueService,
-    ...overrides,
-  } as any)
-  return { added, queueService }
-}
-
-beforeEach(() => {
-  resetPikkuState()
-})
-
-describe('QueueWebhookService.send', () => {
-  test('enqueues with defaults: pikku-outgoing-webhooks queue, 3 retries, exponential backoff', async () => {
-    const { added, queueService } = setupServices()
-    const webhookService = new QueueWebhookService(queueService as any)
-
-    const result = await webhookService.send({
-      url: 'https://example.com/hook',
-      event: 'user.created',
-      data: { id: 'u1' },
-    })
-
-    assert.equal(result.jobId, 'job-1')
-    assert.equal(added.length, 1)
-    const { queueName, data, options } = added[0]!
-    assert.equal(queueName, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME)
-    assert.equal(queueName, 'pikku-outgoing-webhooks')
-    assert.equal(data.url, 'https://example.com/hook')
-    assert.equal(data.body, JSON.stringify({ id: 'u1' }))
-    assert.equal(data.headers['Content-Type'], 'application/json')
-    assert.equal(data.headers['X-Pikku-Event'], 'user.created')
-    assert.equal(options?.attempts, 4)
-    assert.equal(options?.backoff, 'exponential')
-  })
-
-  test('applies config defaults for retries and fixed retryDelay', async () => {
-    const { added, queueService } = setupServices({
-      config: { webhook: { retries: 1, retryDelay: '30s' } },
-    })
-    const webhookService = new QueueWebhookService(queueService as any)
-
-    await webhookService.send({ url: 'https://example.com/hook', data: {} })
-
-    const { options } = added[0]!
-    assert.equal(options?.attempts, 2)
-    assert.deepEqual(options?.backoff, { type: 'fixed', delay: 30000 })
-  })
-
-  test('per-call retries override config defaults', async () => {
-    const { added, queueService } = setupServices({
-      config: { webhook: { retries: 5 } },
-    })
-    const webhookService = new QueueWebhookService(queueService as any)
-
-    await webhookService.send({
-      url: 'https://example.com/hook',
-      data: {},
-      retries: 0,
-    })
-
-    const { options } = added[0]!
-    assert.equal(options?.attempts, 1)
-    assert.equal(options?.backoff, undefined)
-  })
-
-  test('per-call secret signs the body and never enters the job data', async () => {
-    const { added, queueService } = setupServices()
-    const webhookService = new QueueWebhookService(queueService as any)
-
-    await webhookService.send({
-      url: 'https://example.com/hook',
-      data: { id: 'u1' },
-      secret: 'shhh',
-    })
-
-    const { data } = added[0]!
-    const expected =
-      'sha256=' + createHmac('sha256', 'shhh').update(data.body).digest('hex')
-    assert.equal(data.headers['X-Pikku-Signature'], expected)
-    assert.ok(!JSON.stringify(data).includes('shhh'))
-  })
-
-  test('config secret is a secret NAME resolved through the secrets service', async () => {
-    const { added, queueService } = setupServices({
-      config: { webhook: { secret: 'WEBHOOK_SIGNING_KEY' } },
-      secrets: {
-        getSecret: async (key: string) => {
-          assert.equal(key, 'WEBHOOK_SIGNING_KEY')
-          return createSecretValue('resolved-key')
-        },
-      },
-    })
-    const webhookService = new QueueWebhookService(queueService as any)
-
-    await webhookService.send({ url: 'https://example.com/hook', data: {} })
-
-    const { data } = added[0]!
-    assert.ok(
-      webhookService.verify(
-        'resolved-key',
-        data.headers['X-Pikku-Signature']!,
-        data.body
-      )
-    )
-  })
-
-  test('config.webhook.signatureHeader overrides the default header', async () => {
-    const { added, queueService } = setupServices({
-      config: { webhook: { signatureHeader: 'X-Acme-Signature' } },
-    })
-    const webhookService = new QueueWebhookService(queueService as any)
-
-    await webhookService.send({
-      url: 'https://example.com/hook',
-      data: {},
-      secret: 'shhh',
-    })
-
-    const { data } = added[0]!
-    assert.ok(
-      webhookService.verify(
-        'shhh',
-        data.headers['X-Acme-Signature']!,
-        data.body
-      )
-    )
-    assert.equal(data.headers['X-Pikku-Signature'], undefined)
-  })
-
-  test('no secret anywhere means no signature header', async () => {
-    const { added, queueService } = setupServices()
-    const webhookService = new QueueWebhookService(queueService as any)
-
-    await webhookService.send({ url: 'https://example.com/hook', data: {} })
-
-    assert.equal(added[0]!.data.headers['X-Pikku-Signature'], undefined)
-  })
-})
-
-describe('WebhookService signing', () => {
-  test('sign/verify round-trips and rejects tampering', () => {
-    const { queueService } = setupServices()
-    // sign() is protected — reach it the way a subclass would.
-    const webhookService = new (class extends QueueWebhookService {
-      public signBody = (secret: string, body: string) =>
-        this.sign(secret, body)
-    })(queueService as any)
-
-    const signature = webhookService.signBody('key', '{"a":1}')
-
-    assert.ok(signature.startsWith('sha256='))
-    assert.equal(webhookService.verify('key', signature, '{"a":1}'), true)
-    assert.equal(webhookService.verify('key', signature, '{"a":2}'), false)
-    assert.equal(webhookService.verify('other', signature, '{"a":1}'), false)
-    assert.equal(webhookService.verify('key', 'sha256=nope', '{"a":1}'), false)
-  })
-})
-
-describe('pikkuWebhookWorkerFunc', () => {
-  const originalFetch = globalThis.fetch
-
-  const stubFetch = (
-    handler: (url: string, init: RequestInit) => { status: number }
-  ) => {
-    const requests: { url: string; init: RequestInit }[] = []
-    globalThis.fetch = (async (url: any, init: any) => {
-      requests.push({ url: String(url), init })
-      const { status } = handler(String(url), init)
-      return new Response(null, { status })
-    }) as typeof fetch
-    return requests
-  }
-
-  const restoreFetch = () => {
-    globalThis.fetch = originalFetch
-  }
-
-  test('POSTs the stored body and headers, resolves on 2xx', async (t) => {
-    t.after(restoreFetch)
-    const requests = stubFetch(() => ({ status: 204 }))
-
-    await pikkuWebhookWorkerFunc({} as any, {
-      url: 'https://example.com/hook',
-      body: '{"id":"u1"}',
-      headers: { 'Content-Type': 'application/json', 'X-Pikku-Event': 'e' },
-    })
-
-    assert.equal(requests.length, 1)
-    assert.equal(requests[0]!.url, 'https://example.com/hook')
-    assert.equal(requests[0]!.init.method, 'POST')
-    assert.equal(requests[0]!.init.body, '{"id":"u1"}')
-    assert.equal(
-      (requests[0]!.init.headers as Record<string, string>)['X-Pikku-Event'],
-      'e'
-    )
-  })
-
-  test('refuses to deliver to a private/internal host without fetching it (SSRF)', async (t) => {
-    t.after(restoreFetch)
-    const requests = stubFetch(() => ({ status: 200 }))
-
-    await assert.rejects(
-      pikkuWebhookWorkerFunc({} as any, {
-        url: 'http://169.254.169.254/latest/meta-data/',
-        body: '{}',
-        headers: {},
-      }),
-      /private\/internal host/
-    )
-    assert.equal(requests.length, 0, 'must never issue the request')
-  })
-
-  test('records a delivered attempt via the store when a deliveryId is present', async (t) => {
-    t.after(restoreFetch)
-    stubFetch(() => ({ status: 200 }))
-    const recorded: any[] = []
-    const services = {
-      logger: noopLogger,
-      webhookService: {
-        recordAttempt: async (id: string, result: any) =>
-          recorded.push({ id, result }),
-      },
-    }
-
-    await pikkuWebhookWorkerFunc(services as any, {
-      url: 'https://example.com/hook',
-      body: '{}',
-      headers: {},
-      deliveryId: 'del-1',
-    })
-
-    assert.equal(recorded.length, 1)
-    assert.equal(recorded[0].id, 'del-1')
-    assert.equal(recorded[0].result.delivered, true)
-    assert.equal(recorded[0].result.statusCode, 200)
-  })
-
-  test('records a failed attempt (with status) before throwing', async (t) => {
-    t.after(restoreFetch)
-    stubFetch(() => ({ status: 500 }))
-    const recorded: any[] = []
-    const services = {
-      logger: noopLogger,
-      webhookService: {
-        recordAttempt: async (id: string, result: any) =>
-          recorded.push({ id, result }),
-      },
-    }
-
-    await assert.rejects(
-      pikkuWebhookWorkerFunc(services as any, {
-        url: 'https://example.com/hook',
-        body: '{}',
-        headers: {},
-        deliveryId: 'del-2',
-      }),
-      /500/
-    )
-
-    assert.equal(recorded.length, 1)
-    assert.equal(recorded[0].result.delivered, false)
-    assert.equal(recorded[0].result.statusCode, 500)
-  })
-
-  test('skips the store when no deliveryId is present', async (t) => {
-    t.after(restoreFetch)
-    stubFetch(() => ({ status: 200 }))
-    let called = false
-    const services = {
-      logger: noopLogger,
-      webhookService: {
-        recordAttempt: async () => {
-          called = true
-        },
-      },
-    }
-
-    await pikkuWebhookWorkerFunc(services as any, {
-      url: 'https://example.com/hook',
-      body: '{}',
-      headers: {},
-    })
-
-    assert.equal(called, false)
-  })
-
-  test('throws on non-2xx statuses so the queue retries', async (t) => {
-    t.after(restoreFetch)
-
-    stubFetch(() => ({ status: 500 }))
-    await assert.rejects(
-      pikkuWebhookWorkerFunc({} as any, {
-        url: 'https://example.com/hook',
-        body: '{}',
-        headers: {},
-      }),
-      /500/
-    )
-
-    stubFetch(() => ({ status: 302 }))
-    await assert.rejects(
-      pikkuWebhookWorkerFunc({} as any, {
-        url: 'https://example.com/hook',
-        body: '{}',
-        headers: {},
-      }),
-      /302/
-    )
-  })
-
-  test('delivers through the in-memory queue with retries until success', async (t) => {
-    t.after(restoreFetch)
-    resetPikkuState()
-
-    let attempts = 0
-    stubFetch(() => {
-      attempts++
-      return { status: attempts <= 2 ? 500 : 200 }
-    })
-
-    const queueService = new InMemoryQueueService()
-    pikkuState(null, 'package', 'singletonServices', {
-      logger: noopLogger,
-      config: {},
-      queueService,
-    } as any)
-    pikkuState(null, 'package', 'factories', {
-      createWireServices: async () => ({}),
-    } as any)
-
-    const funcId = `queue_${PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME}`
-    pikkuState(null, 'queue', 'meta')[PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME] = {
-      pikkuFuncId: funcId,
-      name: PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,
-    }
-    pikkuState(null, 'function', 'meta')[funcId] = {
-      pikkuFuncId: funcId,
-      inputSchemaName: null,
-      outputSchemaName: null,
-      sessionless: true,
-    } as any
-    wireQueueWorker({
-      name: PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,
-      func: { auth: false, func: pikkuWebhookWorkerFunc },
-    } as any)
-
-    const webhookService = new QueueWebhookService(queueService)
-    await webhookService.send({
-      url: 'https://example.com/hook',
-      data: { id: 'u1' },
-      retries: 3,
-      retryDelay: 1,
-    })
-
-    const deadline = Date.now() + 2000
-    while (attempts < 3 && Date.now() < deadline) {
-      await new Promise((resolve) => setTimeout(resolve, 10))
-    }
-    await new Promise((resolve) => setTimeout(resolve, 150))
-    assert.equal(attempts, 3, 'should retry twice then stop after success')
-  })
-})