@pikku/core 0.12.72 → 0.12.74

package/src/wirings/persona/persona-mailbox.ts

@@ -0,0 +1,156 @@
+/** One email a persona received. */
+export interface ReceivedEmail {
+  to: string
+  from: string
+  subject: string
+  receivedAt: Date
+  /**
+   * Links found in the body, already extracted.
+   *
+   * Extracted rather than handed over as text on purpose — see
+   * {@link PersonaMailbox}. A magic link is the only part of most emails a
+   * virtual user needs, and it is checkable in a way prose is not.
+   */
+  links: string[]
+  /**
+   * Numeric codes found in the body: OTPs, verification codes.
+   *
+   * Separate from `links` because plenty of flows never send a URL at all, and
+   * a run that can only follow links cannot complete them.
+   */
+  codes: string[]
+  /**
+   * The raw body, if the implementation kept it.
+   *
+   * Deliberately optional and deliberately awkward to reach. Nothing in the
+   * engine puts this in a model's context: an email body is attacker-controlled
+   * text arriving through the front door, and a virtual user holds a real
+   * session.
+   */
+  body?: string
+}
+
+/**
+ * Where a persona reads its mail.
+ *
+ * Capturing inbound mail is platform-specific — on Cloudflare an Email Worker
+ * on the test domain, elsewhere whatever the stage can receive with — so pikku
+ * declares the interface and ships no default.
+ *
+ * Implementations **must** apply {@link MailboxAllowlist} before returning
+ * anything. That is the primary defence against prompt injection: a virtual
+ * user's address is real and deliverable, so anyone who learns it can send it
+ * instructions, and the run holds a live session against a real stage.
+ */
+export interface PersonaMailbox {
+  /**
+   * Wait for a matching email, or reject on timeout.
+   *
+   * The flows this exists for — sign-up, magic link, invite, reset — all block
+   * on one arriving, so waiting is the primary operation and polling is the
+   * fallback rather than the other way round.
+   */
+  waitFor(
+    address: string,
+    opts?: {
+      subject?: RegExp
+      from?: string
+      since?: Date
+      timeoutMs?: number
+    }
+  ): Promise<ReceivedEmail>
+
+  /** Everything currently held for an address. */
+  list(address: string): Promise<ReceivedEmail[]>
+
+  /**
+   * Empties an address.
+   *
+   * Called between runs. Without it a run reads the previous run's magic link,
+   * succeeds, and reports a passing sign-up flow that never ran.
+   */
+  clear(address: string): Promise<void>
+}
+
+/** Who a mailbox will accept mail from. */
+export interface MailboxAllowlist {
+  /**
+   * Sender addresses or domains the stage itself sends as, e.g.
+   * `['noreply@example.com', 'example.com']`.
+   */
+  senders: readonly string[]
+  /**
+   * Origins a link may point at, e.g. `['https://staging.example.com']`.
+   *
+   * A link that survives sender checking can still point anywhere; following
+   * one off-origin is how a session leaves the stage it was scoped to.
+   */
+  linkOrigins?: readonly string[]
+}
+
+const senderMatches = (from: string, entry: string): boolean => {
+  const sender = from.trim().toLowerCase()
+  const allowed = entry.trim().toLowerCase()
+  if (allowed.includes('@')) {
+    return sender === allowed
+  }
+  // A bare domain matches the domain part only — never a substring, or
+  // 'example.com' would admit 'example.com.attacker.net'.
+  const at = sender.lastIndexOf('@')
+  return at !== -1 && sender.slice(at + 1) === allowed
+}
+
+/** Whether an email may be shown to a run at all. */
+export const isAllowedSender = (
+  from: string,
+  allowlist: MailboxAllowlist
+): boolean => allowlist.senders.some((entry) => senderMatches(from, entry))
+
+/**
+ * Drops links pointing outside the permitted origins.
+ *
+ * Returns the surviving links rather than rejecting the whole email: a
+ * legitimate email from the stage may well carry an unsubscribe link to
+ * somewhere else, and refusing the email over it would break the flow this
+ * exists to test.
+ */
+export const allowedLinks = (
+  links: readonly string[],
+  allowlist: MailboxAllowlist
+): string[] => {
+  const origins = allowlist.linkOrigins
+  if (!origins?.length) {
+    return [...links]
+  }
+  const permitted = new Set(
+    origins.map((origin) => {
+      try {
+        return new URL(origin).origin
+      } catch {
+        return origin
+      }
+    })
+  )
+  return links.filter((link) => {
+    try {
+      return permitted.has(new URL(link).origin)
+    } catch {
+      return false
+    }
+  })
+}
+
+/**
+ * Applies the allowlist to a batch of received mail.
+ *
+ * Implementations call this rather than filtering themselves — a mailbox that
+ * forgets is not obviously broken, it just quietly becomes an injection
+ * channel, and nothing in a passing run would say so.
+ */
+export const applyMailboxAllowlist = (
+  emails: readonly ReceivedEmail[],
+  allowlist: MailboxAllowlist
+): ReceivedEmail[] =>
+  emails
+    .filter((email) => isAllowedSender(email.from, allowlist))
+    .map((email) => ({ ...email, links: allowedLinks(email.links, allowlist) }))

package/src/wirings/persona/persona.test.ts

@@ -0,0 +1,220 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { personaEmail, personaEmails } from './persona-email.js'
+import {
+  isRunnablePersona,
+  roleMismatchMessage,
+  verifyPersonaRoles,
+} from './validate-personas.js'
+import {
+  allowedLinks,
+  applyMailboxAllowlist,
+  isAllowedSender,
+} from './persona-mailbox.js'
+import type { ReceivedEmail } from './persona-mailbox.js'
+
+describe('computed addresses', () => {
+  test('a run gets its own sub-address', () => {
+    assert.equal(
+      personaEmail('susan', 'mail.example.com', 'r7'),
+      'susan+r7@mail.example.com'
+    )
+  })
+
+  test('without a run id the address is the stable, seedable form', () => {
+    assert.equal(personaEmail('susan', 'mail.example.com'), 'susan@mail.example.com')
+  })
+
+  test('an id that is not address-shaped is reduced to one', () => {
+    assert.equal(
+      personaEmail('Susan.Buyer_2', 'example.com'),
+      'susan-buyer-2@example.com'
+    )
+  })
+
+  test('an id with nothing usable in it is refused rather than guessed at', () => {
+    assert.throws(() => personaEmail('...', 'example.com'), /no usable email label/)
+  })
+
+  // A synthetic domain was rejected precisely because it makes every
+  // email-driven flow untestable; something that is not a domain at all should
+  // not slip through as one.
+  test('a domain that is not a domain is refused', () => {
+    assert.throws(() => personaEmail('susan', 'personas'), /is not a domain/)
+    assert.throws(() => personaEmail('susan', 'a@b.com'), /is not a domain/)
+  })
+
+  test('a leading @ on the domain is tolerated', () => {
+    assert.equal(personaEmail('susan', '@example.com'), 'susan@example.com')
+  })
+})
+
+describe('addresses across a run', () => {
+  test('every persona gets one', () => {
+    const emails = personaEmails(['susan', 'yasser'], 'example.com', 'r1')
+    assert.deepEqual(emails, {
+      susan: 'susan+r1@example.com',
+      yasser: 'yasser+r1@example.com',
+    })
+  })
+
+  // Two personas sharing an address share a user row and read each other's
+  // magic links — the run passes and means nothing.
+  test('two ids that reduce to the same label are refused', () => {
+    assert.throws(
+      () => personaEmails(['susan-buyer', 'Susan.Buyer'], 'example.com'),
+      /both compute the address/
+    )
+  })
+})
+
+describe('who can run', () => {
+  test('an email login runs', () => {
+    assert.equal(isRunnablePersona({ account: {} }), true)
+  })
+
+  test('a persona with no account block at all still runs', () => {
+    assert.equal(isRunnablePersona({}), true)
+  })
+
+  // Driving a consent screen needs a human, so this is a property of the
+  // account rather than a decision anyone should have to remember to record.
+  test('a provider login does not', () => {
+    assert.equal(isRunnablePersona({ account: { provider: 'google' } }), false)
+  })
+
+  test('an explicit refusal wins over an otherwise runnable account', () => {
+    assert.equal(isRunnablePersona({ account: {}, runnable: false }), false)
+  })
+})
+
+describe('verifying roles at sign-in', () => {
+  test('a match runs', () => {
+    const v = verifyPersonaRoles('susan', ['buyer'], ['buyer'])
+    assert.equal(v.ok, true)
+    assert.equal(roleMismatchMessage(v), null)
+  })
+
+  test('order and duplication are not drift', () => {
+    const v = verifyPersonaRoles('yasser', ['admin', 'buyer'], ['buyer', 'admin', 'buyer'])
+    assert.equal(v.ok, true)
+  })
+
+  // Under-granted: the 403s look like authorization findings but are seed drift.
+  test('a missing role stops the run and says which', () => {
+    const v = verifyPersonaRoles('susan', ['buyer'], [])
+    assert.equal(v.ok, false)
+    assert.deepEqual(v.missing, ['buyer'])
+    assert.match(roleMismatchMessage(v)!, /missing buyer/)
+  })
+
+  // Over-granted: nothing fails, the persona just stops testing its boundary.
+  test('an extra role stops the run too', () => {
+    const v = verifyPersonaRoles('susan', ['buyer'], ['buyer', 'admin'])
+    assert.equal(v.ok, false)
+    assert.deepEqual(v.extra, ['admin'])
+    assert.match(roleMismatchMessage(v)!, /unexpectedly holds admin/)
+  })
+
+  test('both directions are reported together', () => {
+    const message = roleMismatchMessage(
+      verifyPersonaRoles('susan', ['buyer'], ['admin'])
+    )!
+    assert.match(message, /missing buyer and unexpectedly holds admin/)
+  })
+})
+
+const email = (over: Partial<ReceivedEmail> = {}): ReceivedEmail => ({
+  to: 'susan+r1@example.com',
+  from: 'noreply@example.com',
+  subject: 'Verify',
+  receivedAt: new Date(),
+  links: [],
+  codes: [],
+  ...over,
+})
+
+describe('the sender allowlist', () => {
+  const allowlist = { senders: ['noreply@example.com', 'mail.example.com'] }
+
+  test('an exact sender is allowed', () => {
+    assert.equal(isAllowedSender('noreply@example.com', allowlist), true)
+  })
+
+  test('a bare domain entry allows any sender at it', () => {
+    assert.equal(isAllowedSender('bounces@mail.example.com', allowlist), true)
+  })
+
+  test('case does not decide it', () => {
+    assert.equal(isAllowedSender('NoReply@Example.COM', allowlist), true)
+  })
+
+  // The whole point: an address that is real and deliverable is an address
+  // anyone can send instructions to.
+  test('a stranger is dropped', () => {
+    assert.equal(isAllowedSender('attacker@evil.test', allowlist), false)
+  })
+
+  // 'example.com' must not admit 'example.com.attacker.net'.
+  test('a domain entry is not a substring match', () => {
+    assert.equal(
+      isAllowedSender('x@mail.example.com.attacker.net', allowlist),
+      false
+    )
+  })
+
+  test('filtering drops the stranger and keeps the rest', () => {
+    const kept = applyMailboxAllowlist(
+      [email(), email({ from: 'attacker@evil.test' })],
+      allowlist
+    )
+    assert.equal(kept.length, 1)
+    assert.equal(kept[0]!.from, 'noreply@example.com')
+  })
+})
+
+describe('link origins', () => {
+  const allowlist = {
+    senders: ['example.com'],
+    linkOrigins: ['https://staging.example.com'],
+  }
+
+  test('an on-origin link survives', () => {
+    assert.deepEqual(
+      allowedLinks(['https://staging.example.com/verify?t=1'], allowlist),
+      ['https://staging.example.com/verify?t=1']
+    )
+  })
+
+  test('an off-origin link is dropped', () => {
+    assert.deepEqual(allowedLinks(['https://evil.test/steal'], allowlist), [])
+  })
+
+  test('garbage is dropped rather than thrown on', () => {
+    assert.deepEqual(allowedLinks(['not a url'], allowlist), [])
+  })
+
+  // Dropping the link rather than the email: a legitimate stage email may
+  // carry an unsubscribe link elsewhere, and refusing it would break the flow
+  // this exists to test.
+  test('a mixed email keeps its good link and loses the bad one', () => {
+    const [kept] = applyMailboxAllowlist(
+      [
+        email({
+          from: 'noreply@example.com',
+          links: ['https://staging.example.com/verify', 'https://evil.test/x'],
+        }),
+      ],
+      allowlist
+    )
+    assert.deepEqual(kept!.links, ['https://staging.example.com/verify'])
+  })
+
+  test('no configured origins means no narrowing', () => {
+    assert.deepEqual(
+      allowedLinks(['https://anywhere.test/x'], { senders: [] }),
+      ['https://anywhere.test/x']
+    )
+  })
+})

package/src/wirings/persona/persona.types.ts

@@ -0,0 +1,131 @@
+import type { VirtualUserDisposition } from '../virtual-user/virtual-user.types.js'
+import type { VirtualUserTuning } from '../virtual-user/virtual-user-dispositions.js'
+
+/**
+ * One login belonging to a persona.
+ *
+ * Deliberately near-empty in the common case: the address is computed from the
+ * persona's name and the run id, and the password derives from
+ * `SCENARIO_ACTOR_SECRET`, so there is nothing left to write down. It fills up
+ * only for a provider login.
+ *
+ * Shaped after better-auth's `account` table, which is what most pikku apps are
+ * actually running: `providerId` plus the provider's own id, and no email
+ * column — the address belongs to the person, not the login.
+ */
+export type CorePersonaAccount = {
+  /**
+   * The identity provider, e.g. `'google'`. Omit for email and password.
+   *
+   * A provider account is declarable but not runnable: driving its consent
+   * screen needs a human, so `pikku persona run` refuses rather than failing
+   * somewhere inside a browser.
+   */
+  provider?: string
+}
+
+/**
+ * A person who uses your product: a name, a job, a temperament, and what they
+ * are trying to get done.
+ *
+ * This is Cooper's persona — "a fictional character created to represent a user
+ * type" — with the two things a synthetic user additionally needs: the roles
+ * that say what they may do, and the account they log in with. A persona while
+ * running is a virtual user; there is no second declaration for that.
+ */
+export type CorePersona = {
+  /** The person's name, as a person would give it. */
+  name: string
+  jobTitle?: string
+  description?: string
+  /**
+   * The roles this person holds. Only system roles may be named — a custom
+   * role can be deleted from the console, so a persona pinned to one silently
+   * stops testing what it claims to.
+   *
+   * These are granted, not merely recorded: the generated seed applies them,
+   * and a run verifies them at sign-in.
+   */
+  roles?: string[]
+  /**
+   * How they behave and talk, in prose. Temperament, not permissions — "reads
+   * other people's ids out of urls" belongs here; "can see reports and nothing
+   * else" is a role wearing a personality.
+   */
+  personality?: string
+  /**
+   * What they durably want. A run may append situational goals; it never
+   * replaces these, because a run that replaces Susan's goals is not Susan.
+   */
+  goals?: string[]
+  tags?: string[]
+  /** Default mechanical behaviour. A run may override it. */
+  disposition?: VirtualUserDisposition
+  /** Overrides for that disposition's dials. */
+  tuning?: VirtualUserTuning
+  /** Fixture paths this person may upload, relative to the project root. */
+  fixtures?: string[]
+  /** Their login. `{}` — email and password — is the normal case. */
+  account?: CorePersonaAccount
+  /**
+   * Further logins belonging to the same human, keyed by name.
+   *
+   * Rare, and shaped that way on purpose. All of them share the persona's one
+   * computed address: better-auth's `allowDifferentEmails` defaults to false,
+   * so distinct addresses would be refused linking by the library under test.
+   */
+  linkedAccounts?: Record<string, CorePersonaAccount>
+  /**
+   * The environments this person may run against, by config key.
+   *
+   * Omitted means every environment **except** the ones flagged
+   * `production: true`. Production is opt-in for everybody, so nothing reaches
+   * it by being forgotten — and naming one requires
+   * `disposition: 'accountable'`, which the inspector enforces and sign-in
+   * re-checks.
+   */
+  environments?: string[]
+  /**
+   * False for a person who is only ever acted *upon* — the account an admin
+   * bans, the colleague a document is shared with. Declared and seeded, never
+   * run. Defaults to true.
+   *
+   * An assertion, not something inferred from the absence of a disposition:
+   * `target` *must not* run, because a run signing in as her would race the
+   * scenario banning her. "Nobody has given this persona a disposition yet" is
+   * a different state, and collapsing the two turns a deliberate constraint
+   * into a flaky suite.
+   */
+  runnable?: boolean
+}
+
+/** Personas to declare, keyed by id. */
+export type CorePersonas = Record<string, CorePersona>
+
+export type PersonaAccountMeta = {
+  provider?: string
+}
+
+export type PersonaMeta = {
+  /** The key it was declared under. */
+  id: string
+  name: string
+  jobTitle?: string
+  description?: string
+  roles: string[]
+  personality?: string
+  goals: string[]
+  tags: string[]
+  disposition?: VirtualUserDisposition
+  tuning?: VirtualUserTuning
+  fixtures?: string[]
+  account?: PersonaAccountMeta
+  linkedAccounts?: Record<string, PersonaAccountMeta>
+  /** Absent means "everywhere but production", which is resolved, not stored. */
+  environments?: string[]
+  runnable: boolean
+  sourceFile?: string
+}
+
+export type PersonaDefinitions = PersonaMeta[]
+export type PersonasMeta = Record<string, PersonaMeta>

package/src/wirings/persona/validate-personas.ts

@@ -0,0 +1,133 @@
+import type { PersonaDefinitions, PersonaMeta, PersonasMeta } from './persona.types.js'
+
+/**
+ * Whether a persona can actually be driven by a virtual user.
+ *
+ * A provider login cannot: driving Google's or GitHub's consent screen needs a
+ * human, so the persona is seedable and assertable but not runnable. Derived
+ * rather than asked for, because it is a consequence of the account rather than
+ * a separate decision — and a flag someone must remember to set is a flag that
+ * ships wrong.
+ *
+ * An explicit `runnable: false` still wins: it marks the person who is only
+ * ever acted *upon*, which no account shape reveals.
+ */
+export const isRunnablePersona = (persona: {
+  runnable?: boolean
+  account?: { provider?: string }
+}): boolean => {
+  if (persona.runnable === false) {
+    return false
+  }
+  return persona.account?.provider === undefined
+}
+
+/**
+ * Validates declared personas and keys them by id.
+ *
+ * Definitions sharing an id must be identical; a conflicting redeclaration is a
+ * hard error naming both source files, on the same terms as scopes and roles.
+ */
+export function validateAndBuildPersonasMeta(
+  definitions: PersonaDefinitions
+): PersonasMeta {
+  const meta: PersonasMeta = {}
+
+  for (const persona of definitions) {
+    if (!persona.id) {
+      throw new Error('A persona is declared with an empty id.')
+    }
+    if (!persona.name) {
+      throw new Error(
+        `Persona '${persona.id}' has no name. A persona is a person; give them one.`
+      )
+    }
+
+    const existing = meta[persona.id]
+    if (existing) {
+      const same =
+        JSON.stringify({ ...existing, sourceFile: undefined }) ===
+        JSON.stringify({ ...persona, sourceFile: undefined })
+      if (!same) {
+        throw new Error(
+          `Persona '${persona.id}' is declared twice with different content.\n` +
+            `  First declaration: ${existing.sourceFile ?? 'unknown'}\n` +
+            `  Second declaration: ${persona.sourceFile ?? 'unknown'}`
+        )
+      }
+      continue
+    }
+
+    meta[persona.id] = persona
+  }
+
+  return meta
+}
+
+/** What a run compares against the store before its first step. */
+export interface RoleVerification {
+  persona: string
+  expected: string[]
+  actual: string[]
+  missing: string[]
+  extra: string[]
+  ok: boolean
+}
+
+/**
+ * Compares a persona's declared roles against what the stage actually granted.
+ *
+ * Run at sign-in, before the first step. The declaration is authoritative —
+ * the generated seed applies it — but pikku cannot guarantee the seed ran on a
+ * stage it did not deploy, and virtual users are meant to run against staging
+ * and production, so that case is the normal one.
+ *
+ * Both directions matter, for opposite reasons. An under-granted persona
+ * reports authorization bugs that are really seed drift. An over-granted one
+ * silently stops testing the boundary it was written to test — nothing fails,
+ * the findings just quietly stop being about anything.
+ */
+export const verifyPersonaRoles = (
+  persona: string,
+  expected: readonly string[],
+  actual: readonly string[]
+): RoleVerification => {
+  const expectedSet = new Set(expected)
+  const actualSet = new Set(actual)
+  const missing = [...expectedSet].filter((r) => !actualSet.has(r)).sort()
+  const extra = [...actualSet].filter((r) => !expectedSet.has(r)).sort()
+  return {
+    persona,
+    expected: [...expectedSet].sort(),
+    actual: [...actualSet].sort(),
+    missing,
+    extra,
+    ok: missing.length === 0 && extra.length === 0,
+  }
+}
+
+/** The message a run stops with, or `null` when the roles line up. */
+export const roleMismatchMessage = (
+  verification: RoleVerification
+): string | null => {
+  if (verification.ok) {
+    return null
+  }
+  const parts: string[] = []
+  if (verification.missing.length) {
+    parts.push(`missing ${verification.missing.join(', ')}`)
+  }
+  if (verification.extra.length) {
+    parts.push(`unexpectedly holds ${verification.extra.join(', ')}`)
+  }
+  return (
+    `Persona '${verification.persona}' ${parts.join(' and ')}. ` +
+    `Declared: ${verification.expected.join(', ') || 'none'}. ` +
+    `On the stage: ${verification.actual.join(', ') || 'none'}. ` +
+    `Refusing to run — findings from a persona whose roles have drifted are about the seed, not the product.`
+  )
+}
+
+/** Convenience: the meta a run needs, with `runnable` already resolved. */
+export const runnablePersonas = (meta: PersonasMeta): PersonaMeta[] =>
+  Object.values(meta).filter((persona) => persona.runnable)

package/src/wirings/queue/index.ts

@@ -14,7 +14,6 @@ export type {
   QueueWorkersMeta,
 } from './queue.types.js'
 
-// Queue processor management
 export {
   wireQueueWorker,
   runQueueJob,
@@ -24,10 +23,21 @@ export {
   QueueJobFailedError,
 } from './queue-runner.js'
 
-// Configuration validation
+export {
+  QUEUE_IDENTITY_CLAIM_VERSION,
+  QUEUE_IDENTITY_INFO,
+  QUEUE_IDENTITY_SECRET_NAME,
+  getQueueIdentitySecret,
+  resolveQueueJobIdentity,
+  signQueueIdentity,
+  verifyQueueIdentity,
+} from './queue-identity.js'
+export type { QueueIdentityBinding } from './queue-identity.js'
+
+export { SignedQueueService } from './signed-queue-service.js'
+
 export { validateWorkerConfig } from './validate-worker-config.js'
 export type { QueueConfigMapping } from './validate-worker-config.js'
 
-// Queue registration helper
 export { registerQueueWorkers } from './register-queue-helper.js'
 export type { QueueRegistrationCallback } from './register-queue-helper.js'