@pikku/core 0.12.107 → 0.12.111

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

@@ -1,230 +0,0 @@
-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

@@ -1,156 +0,0 @@
-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
-  /**
-   * A picture of this person, as any URL a browser can load: a file your app
-   * serves, an asset on a CDN, a Gravatar link.
-   *
-   * Optional because it is decoration. Omitted, the console draws a colour and
-   * an icon derived from the persona's id, which is stable, needs no network and
-   * is more legible than the identicon a synthetic address would resolve to —
-   * which is also why nothing is derived here.
-   */
-  avatarUrl?: 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
-  /**
-   * The app this person signs into, when the product is more than one frontend.
-   *
-   * A person uses one of them — staff their app, customers theirs — and that is
-   * what decides where a browser step navigates: `/dashboard` is a different
-   * page in each, so the actor settles which one without the scenario saying.
-   * The runner takes the base url per app (`--app-url <app>=<url>`, or
-   * `appUrls` on the environment) and each actor browses against its own.
-   *
-   * Omitted is the normal case: one app, one url, nothing to say.
-   */
-  app?: string
-}
-
-/** 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
-  avatarUrl?: 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
-  /** The app this person signs into; picks their base url on a browser run. */
-  app?: string
-  sourceFile?: string
-}
-
-export type PersonaDefinitions = PersonaMeta[]
-export type PersonasMeta = Record<string, PersonaMeta>

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

@@ -1,137 +0,0 @@
-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

@@ -1,29 +0,0 @@
-export type {
-  ConfigValidationResult,
-  CoreQueueWorker,
-  GroupConcurrencyConfig,
-  JobGroup,
-  JobOptions,
-  PikkuJobConfig,
-  PikkuWorkerConfig,
-  PikkuQueue,
-  QueueJob,
-  QueueJobStatus,
-  QueueService,
-  QueueWorkers,
-  QueueWorkersMeta,
-} from './queue.types.js'
-
-export {
-  wireQueueWorker,
-  runQueueJob,
-  QueueJobDiscardedError,
-  QueueJobFailedError,
-} from './queue-runner.js'
-export type { QueueIdentityBinding } from './queue-identity.js'
-
-export { SignedQueueService } from './signed-queue-service.js'
-export type { QueueConfigMapping } from './validate-worker-config.js'
-
-export { registerQueueWorkers } from './register-queue-helper.js'
-export type { QueueRegistrationCallback } from './register-queue-helper.js'