@pikku/core 0.12.71 → 0.12.74

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

@@ -0,0 +1,138 @@
+import {
+  PRODUCTION_DISPOSITION,
+  type VirtualUserDisposition,
+} from '../virtual-user/virtual-user.types.js'
+
+/**
+ * Which environments a persona may run against, and the one rule on it.
+ *
+ * Two callers, deliberately sharing this file. The inspector checks the
+ * declaration at build time; sign-in re-checks against the environment actually
+ * resolved at run time. Neither is redundant — the build check trusts the file,
+ * and the run check does not trust which artifact got deployed.
+ */
+
+/** The part of an environment entry this rule cares about. */
+export interface PersonaEnvironment {
+  production?: boolean
+}
+
+/** What a persona needs to expose for the rule to be applied to it. */
+export interface PersonaEnvironmentSubject {
+  disposition?: VirtualUserDisposition
+  environments?: string[]
+}
+
+/**
+ * The environments a persona may target, resolved.
+ *
+ * An omitted `environments` means every configured environment **except** the
+ * production ones: production is opt-in for everybody, so nothing reaches it by
+ * being forgotten.
+ */
+export const resolvePersonaEnvironments = (
+  persona: PersonaEnvironmentSubject,
+  environments: Readonly<Record<string, PersonaEnvironment>>
+): string[] => {
+  if (persona.environments) {
+    return [...persona.environments]
+  }
+  return Object.entries(environments)
+    .filter(([, env]) => !env.production)
+    .map(([name]) => name)
+}
+
+/**
+ * The declaration check, as a list of messages. Empty means the persona's
+ * `environments` are coherent with the config and its disposition.
+ *
+ * An unknown environment name is an error rather than a shrug: a typo silently
+ * narrowing a persona to nothing is the same class of bug as the one this whole
+ * rule exists to prevent, only quieter.
+ */
+export const personaEnvironmentErrors = (
+  id: string,
+  persona: PersonaEnvironmentSubject,
+  environments: Readonly<Record<string, PersonaEnvironment>>
+): string[] => {
+  if (!persona.environments) {
+    return []
+  }
+
+  const errors: string[] = []
+  const known = Object.keys(environments)
+
+  for (const name of persona.environments) {
+    const env = environments[name]
+    if (!env) {
+      errors.push(
+        `Persona '${id}' names environment '${name}', which is not configured. ` +
+          (known.length
+            ? `Configured environments: ${known.join(', ')}.`
+            : `Declare it under 'environments' in pikku.config.json.`)
+      )
+      continue
+    }
+    if (env.production && persona.disposition !== PRODUCTION_DISPOSITION) {
+      errors.push(
+        `Persona '${id}' names production environment '${name}' with disposition ` +
+          `'${persona.disposition ?? 'realistic'}'. ` +
+          `Only '${PRODUCTION_DISPOSITION}' may run against production — every other ` +
+          `disposition exists to find out what the product does wrong, which is not a ` +
+          `thing to do to real data. Either give '${id}' disposition '${PRODUCTION_DISPOSITION}', ` +
+          `or drop '${name}' from its environments.`
+      )
+    }
+  }
+
+  return errors
+}
+
+/**
+ * The sign-in check: the message to refuse with, or `null` to let the run
+ * start.
+ *
+ * Fails closed on an environment it cannot find. An unresolved `PIKKU_ENV` is
+ * the case where the build check has already been passed by a *different*
+ * artifact than the one running, so treating "I don't know where I am" as
+ * permission is exactly backwards.
+ */
+export const personaEnvironmentRefusal = (
+  id: string,
+  persona: PersonaEnvironmentSubject,
+  environmentName: string | undefined,
+  environments: Readonly<Record<string, PersonaEnvironment>>
+): string | null => {
+  if (!environmentName) {
+    return (
+      `Refusing to sign in persona '${id}': no environment is resolved. ` +
+      `Set PIKKU_ENV to one of the configured environments (${Object.keys(environments).join(', ') || 'none are configured'}).`
+    )
+  }
+
+  const env = environments[environmentName]
+  if (!env) {
+    return (
+      `Refusing to sign in persona '${id}': environment '${environmentName}' is not configured. ` +
+      `Configured environments: ${Object.keys(environments).join(', ') || 'none'}.`
+    )
+  }
+
+  if (env.production && persona.disposition !== PRODUCTION_DISPOSITION) {
+    return (
+      `Refusing to sign in persona '${id}' against production environment '${environmentName}': ` +
+      `its disposition is '${persona.disposition ?? 'realistic'}', and only ` +
+      `'${PRODUCTION_DISPOSITION}' may act on real data.`
+    )
+  }
+
+  const allowed = resolvePersonaEnvironments(persona, environments)
+  if (!allowed.includes(environmentName)) {
+    return (
+      `Refusing to sign in persona '${id}' against '${environmentName}': ` +
+      `it declares environments ${allowed.join(', ') || 'none'}.`
+    )
+  }
+
+  return null
+}

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>