@pikku/core 0.12.107 → 0.12.112

package/src/wirings/persona/persona-app-scopes.test.ts

@@ -1,47 +0,0 @@
-import assert from 'node:assert/strict'
-import { describe, test } from 'node:test'
-import {
-  appScopeId,
-  buildAppScopeDefinition,
-  declaredApps,
-} from './persona-app-scopes.js'
-
-const persona = (id: string, app?: string) =>
-  ({ id, name: id, roles: [], goals: [], tags: [], runnable: true, app }) as any
-
-describe('declaredApps', () => {
-  test('deduplicates and sorts the apps the personas name', () => {
-    assert.deepEqual(
-      declaredApps([
-        persona('a', 'staff'),
-        persona('b', 'portal'),
-        persona('c', 'staff'),
-      ]),
-      ['portal', 'staff']
-    )
-  })
-
-  test('ignores personas that name no app', () => {
-    assert.deepEqual(declaredApps([persona('a'), persona('b', '')]), [])
-  })
-})
-
-describe('buildAppScopeDefinition', () => {
-  test('renders one grantable child per app under the app root', () => {
-    const definition = buildAppScopeDefinition([
-      persona('a', 'staff'),
-      persona('b', 'portal'),
-    ])
-
-    assert.equal(definition?.name, 'app')
-    assert.deepEqual(Object.keys(definition?.scopes ?? {}).sort(), [
-      'portal',
-      'staff',
-    ])
-    assert.equal(appScopeId('staff'), 'app:staff')
-  })
-
-  test('is null for a single-frontend product', () => {
-    assert.equal(buildAppScopeDefinition([persona('a')]), null)
-  })
-})

package/src/wirings/persona/persona-app-scopes.ts

@@ -1,74 +0,0 @@
-import type { ScopeDefinitionMeta, ScopeNodeMeta } from '../scope/scope.types.js'
-import type { PersonaMeta } from './persona.types.js'
-
-/**
- * The root every app grant hangs off. One segment, so a grant of `app` alone
- * means "may use all of them" under the same parent-grant rule the admin tree
- * relies on — which is what a support operator or an internal tool wants, and
- * what a per-app boolean column could never express.
- */
-export const APP_SCOPE_ROOT = 'app'
-
-/** `app:staff` for `staff`. */
-export const appScopeId = (app: string) => `${APP_SCOPE_ROOT}:${app}`
-
-/**
- * The apps named across the declared personas, sorted and deduplicated.
- *
- * The personas *are* the registry. There is no separate list of apps to keep in
- * step, because a frontend nobody signs into is not a thing the auth layer has
- * an opinion about — and the moment somebody does sign into it, they are a
- * persona and they name it.
- */
-export const declaredApps = (personas: PersonaMeta[]): string[] =>
-  [
-    ...new Set(
-      personas
-        .map((persona) => persona.app)
-        .filter((app): app is string => typeof app === 'string' && app !== '')
-    ),
-  ].sort()
-
-/**
- * The `app` scope tree, synthesised from the personas that name an app.
- *
- * Which frontend a person may sign into is a different question from what they
- * may do once inside it, but it is the same *kind* of question — a grant that
- * an admin can make and revoke at runtime, that resolves at the session
- * boundary, and that a restricted API key can decline to inherit. So it is
- * carried as a scope rather than a `can_access_<app>` column: no migration per
- * app, one query for "which apps may this user reach", and no second
- * authorization mechanism to keep honest.
- *
- * Synthesised rather than written by hand because the declaration already
- * exists. Asking an app to also spell out `defineScope({ app: { staff: {} } })`
- * beside its personas invites the two to drift, and the failure that produces —
- * a persona provisioned with a grant the vocabulary no longer declares — is one
- * `pikku scopes prune` away from silently revoking sign-in.
- *
- * Null when no persona names an app, which is the single-frontend case: nothing
- * to declare, and no empty root cluttering the console's grant list.
- */
-export const buildAppScopeDefinition = (
-  personas: PersonaMeta[]
-): ScopeDefinitionMeta | null => {
-  const apps = declaredApps(personas)
-  if (apps.length === 0) {
-    return null
-  }
-
-  const scopes: Record<string, ScopeNodeMeta> = {}
-  for (const app of apps) {
-    scopes[app] = {
-      displayName: app,
-      description: `May sign in to the ${app} app`,
-    }
-  }
-
-  return {
-    name: APP_SCOPE_ROOT,
-    displayName: 'Apps',
-    description: 'Which frontend a person may sign in to',
-    scopes,
-  }
-}

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

@@ -1,87 +0,0 @@
-/**
- * A persona's email address is computed, never declared.
- *
- * A persona that cannot read its own email cannot complete sign-up, magic
- * links, invites or password resets — which are most of the flows worth
- * exercising. So addresses are real and deliverable against a domain the stage
- * actually receives mail on, rather than a synthetic `.local` dead end.
- */
-
-const LABEL = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
-
-/**
- * Lower-cases and strips a persona id down to something an address can carry.
- *
- * Personas are declared as object keys, so they are already identifier-shaped;
- * this exists for the ones that are not (`'susan.buyer'`, `'Susan_2'`) rather
- * than to permit arbitrary input.
- */
-export const personaEmailLabel = (personaId: string): string => {
-  const label = personaId
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-  if (!LABEL.test(label)) {
-    throw new Error(
-      `Persona '${personaId}' has no usable email label. A persona id must contain at least one letter or digit.`
-    )
-  }
-  return label
-}
-
-/**
- * The address a persona reads mail at during a run.
- *
- * The `runId` suffix is not decoration. Without it two concurrent runs share an
- * inbox *and* a user row, and run B reads run A's magic link. Sub-addressing
- * also buys isolation for free: a different address is a different account in
- * the app, so two runs cannot collide on sign-up either.
- *
- * Omitting `runId` gives the bare form, which is what a seeded fixture that has
- * to stay stable across runs wants.
- */
-export const personaEmail = (
-  personaId: string,
-  domain: string,
-  runId?: string
-): string => {
-  const label = personaEmailLabel(personaId)
-  const cleanDomain = domain.trim().toLowerCase().replace(/^@/, '')
-  if (!cleanDomain || cleanDomain.includes('@') || !cleanDomain.includes('.')) {
-    throw new Error(
-      `Persona email domain '${domain}' is not a domain. Set it to a domain the stage actually receives mail on.`
-    )
-  }
-  const suffix = runId ? `+${personaEmailLabel(runId)}` : ''
-  return `${label}${suffix}@${cleanDomain}`
-}
-
-/**
- * Every address in a run, keyed by persona.
- *
- * All of a persona's logins share one address. That is not a simplification:
- * better-auth keeps `email` on the `user` and defaults `allowDifferentEmails`
- * to false, so giving a linked account its own address would have the library
- * under test refuse to link the very thing the persona declared as linked.
- */
-export const personaEmails = (
-  personaIds: readonly string[],
-  domain: string,
-  runId?: string
-): Record<string, string> => {
-  const emails: Record<string, string> = {}
-  const seen = new Map<string, string>()
-  for (const id of personaIds) {
-    const address = personaEmail(id, domain, runId)
-    const collidesWith = seen.get(address)
-    if (collidesWith !== undefined) {
-      throw new Error(
-        `Personas '${collidesWith}' and '${id}' both compute the address ${address}. ` +
-          `They would share a user row and read each other's email.`
-      )
-    }
-    seen.set(address, id)
-    emails[id] = address
-  }
-  return emails
-}

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

@@ -1,194 +0,0 @@
-import assert from 'node:assert/strict'
-import { describe, test } from 'node:test'
-import {
-  personaEnvironmentErrors,
-  personaEnvironmentRefusal,
-  resolvePersonaEnvironments,
-} from './persona-environments.js'
-
-const ENVIRONMENTS = {
-  local: {},
-  staging: {},
-  prod: { production: true },
-  'eu-prod': { production: true },
-}
-
-describe('resolvePersonaEnvironments', () => {
-  // The default that makes production opt-in: a persona nobody thought about
-  // runs everywhere it is harmless and nowhere it is not.
-  test('omitting environments means everywhere but production', () => {
-    assert.deepEqual(resolvePersonaEnvironments({}, ENVIRONMENTS), [
-      'local',
-      'staging',
-    ])
-  })
-
-  test('a declared list is taken verbatim, production included', () => {
-    assert.deepEqual(
-      resolvePersonaEnvironments(
-        { disposition: 'accountable', environments: ['staging', 'prod'] },
-        ENVIRONMENTS
-      ),
-      ['staging', 'prod']
-    )
-  })
-
-  test('more than one environment can be production', () => {
-    assert.deepEqual(
-      resolvePersonaEnvironments({}, { a: {}, b: { production: true } }),
-      ['a']
-    )
-  })
-})
-
-describe('personaEnvironmentErrors', () => {
-  test('a persona that declares nothing cannot be wrong', () => {
-    assert.deepEqual(
-      personaEnvironmentErrors(
-        'shopper',
-        { disposition: 'careless' },
-        ENVIRONMENTS
-      ),
-      []
-    )
-  })
-
-  test('an accountable persona may name production', () => {
-    assert.deepEqual(
-      personaEnvironmentErrors(
-        'robin',
-        { disposition: 'accountable', environments: ['staging', 'prod'] },
-        ENVIRONMENTS
-      ),
-      []
-    )
-  })
-
-  test('a testing disposition naming production is an error', () => {
-    const [error, ...rest] = personaEnvironmentErrors(
-      'shopper',
-      { disposition: 'careless', environments: ['prod'] },
-      ENVIRONMENTS
-    )
-    assert.deepEqual(rest, [])
-    assert.match(error!, /names production environment 'prod'/)
-    assert.match(error!, /'careless'/)
-    assert.match(error!, /disposition 'accountable'/)
-  })
-
-  // The default disposition is `realistic`, which is still a testing one. A
-  // persona that declares no disposition at all must not slip into production
-  // on the strength of having said nothing.
-  test('no disposition at all is reported as realistic, and refused', () => {
-    const [error] = personaEnvironmentErrors(
-      'quiet',
-      { environments: ['prod'] },
-      ENVIRONMENTS
-    )
-    assert.match(error!, /'realistic'/)
-  })
-
-  test('every offending environment is reported, not just the first', () => {
-    const errors = personaEnvironmentErrors(
-      'shopper',
-      { disposition: 'careless', environments: ['prod', 'eu-prod'] },
-      ENVIRONMENTS
-    )
-    assert.equal(errors.length, 2)
-  })
-
-  // A typo silently narrows the persona to nothing, which is the same class of
-  // bug the rule exists to prevent — only quieter.
-  test('an unknown environment names the ones that exist', () => {
-    const [error] = personaEnvironmentErrors(
-      'shopper',
-      { environments: ['stagng'] },
-      ENVIRONMENTS
-    )
-    assert.match(error!, /'stagng', which is not configured/)
-    assert.match(error!, /local, staging, prod, eu-prod/)
-  })
-
-  test('with nothing configured it says where environments go', () => {
-    const [error] = personaEnvironmentErrors(
-      'shopper',
-      { environments: ['x'] },
-      {}
-    )
-    assert.match(
-      error!,
-      /Declare it under 'environments' in pikku\.config\.json/
-    )
-  })
-})
-
-describe('personaEnvironmentRefusal', () => {
-  const accountable = {
-    disposition: 'accountable' as const,
-    environments: ['staging', 'prod'],
-  }
-
-  test('lets a declared environment through', () => {
-    assert.equal(
-      personaEnvironmentRefusal('robin', accountable, 'prod', ENVIRONMENTS),
-      null
-    )
-  })
-
-  // Fail closed. An unresolved PIKKU_ENV is precisely the case where the build
-  // check was passed by a different artifact than the one now running, so
-  // "I don't know where I am" must not read as permission.
-  test('an unresolved environment refuses everybody', () => {
-    const refusal = personaEnvironmentRefusal(
-      'robin',
-      accountable,
-      undefined,
-      ENVIRONMENTS
-    )
-    assert.match(refusal!, /no environment is resolved/)
-    assert.match(refusal!, /PIKKU_ENV/)
-  })
-
-  test('an unrecognised environment refuses rather than assuming staging', () => {
-    const refusal = personaEnvironmentRefusal(
-      'robin',
-      accountable,
-      'somewhere-else',
-      ENVIRONMENTS
-    )
-    assert.match(refusal!, /is not configured/)
-  })
-
-  // The check the deployed artifact cannot have been trusted on: whatever the
-  // file said, this persona is not allowed to act on real data.
-  test('production refuses a testing disposition whatever it declared', () => {
-    const refusal = personaEnvironmentRefusal(
-      'shopper',
-      { disposition: 'adversarial', environments: ['prod'] },
-      'prod',
-      ENVIRONMENTS
-    )
-    assert.match(refusal!, /only 'accountable' may act on real data/)
-  })
-
-  test('an environment outside the declared list is refused', () => {
-    const refusal = personaEnvironmentRefusal(
-      'robin',
-      accountable,
-      'local',
-      ENVIRONMENTS
-    )
-    assert.match(refusal!, /it declares environments staging, prod/)
-  })
-
-  test('a persona declaring nothing still runs everywhere but production', () => {
-    assert.equal(
-      personaEnvironmentRefusal('shopper', {}, 'staging', ENVIRONMENTS),
-      null
-    )
-    assert.match(
-      personaEnvironmentRefusal('shopper', {}, 'prod', ENVIRONMENTS)!,
-      /only 'accountable' may act on real data/
-    )
-  })
-})

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

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

@@ -1,156 +0,0 @@
-/** 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) }))