@pikku/core 0.12.71 → 0.12.74

package/dist/wirings/persona/index.js

@@ -0,0 +1,17 @@
+export { definePersonas } from './define-personas.js';
+export { isRunnablePersona, roleMismatchMessage, runnablePersonas, validateAndBuildPersonasMeta, verifyPersonaRoles, } from './validate-personas.js';
+export { personaEnvironmentErrors, personaEnvironmentRefusal, resolvePersonaEnvironments, } from './persona-environments.js';
+export { personaEmail, personaEmailLabel, personaEmails, } from './persona-email.js';
+export { allowedLinks, applyMailboxAllowlist, isAllowedSender, } from './persona-mailbox.js';
+/**
+ * Signing in as a persona and talking to a stage over HTTP.
+ *
+ * Deliberately reached through this entry point rather than `@pikku/core/services`.
+ * `HttpPersona` pulls in the actor-flow conversation runner and, through it, the
+ * agent runner — none of which a production server has any use for. Exporting it
+ * from the services barrel put that chain in the module graph of every app that
+ * imports services, which only a bundler could remove and an unbundled Node or
+ * Lambda deploy would load outright.
+ */
+export { HttpPersona, createHttpPersonas, } from '../../services/http-personas.js';
+export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';

package/dist/wirings/persona/persona-email.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare const personaEmailLabel: (personaId: string) => string;
+/**
+ * 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 declare const personaEmail: (personaId: string, domain: string, runId?: string) => string;
+/**
+ * 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 declare const personaEmails: (personaIds: readonly string[], domain: string, runId?: string) => Record<string, string>;

package/dist/wirings/persona/persona-email.js

@@ -0,0 +1,69 @@
+/**
+ * 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) => {
+    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, domain, runId) => {
+    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, domain, runId) => {
+    const emails = {};
+    const seen = new Map();
+    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/dist/wirings/persona/persona-environments.d.ts

@@ -0,0 +1,45 @@
+import { 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 declare const resolvePersonaEnvironments: (persona: PersonaEnvironmentSubject, environments: Readonly<Record<string, PersonaEnvironment>>) => string[];
+/**
+ * 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 declare const personaEnvironmentErrors: (id: string, persona: PersonaEnvironmentSubject, environments: Readonly<Record<string, PersonaEnvironment>>) => string[];
+/**
+ * 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 declare const personaEnvironmentRefusal: (id: string, persona: PersonaEnvironmentSubject, environmentName: string | undefined, environments: Readonly<Record<string, PersonaEnvironment>>) => string | null;

package/dist/wirings/persona/persona-environments.js

@@ -0,0 +1,81 @@
+import { PRODUCTION_DISPOSITION, } from '../virtual-user/virtual-user.types.js';
+/**
+ * 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, environments) => {
+    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, persona, environments) => {
+    if (!persona.environments) {
+        return [];
+    }
+    const errors = [];
+    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, persona, environmentName, environments) => {
+    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/dist/wirings/persona/persona-mailbox.d.ts

@@ -0,0 +1,101 @@
+/** 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[];
+}
+/** Whether an email may be shown to a run at all. */
+export declare const isAllowedSender: (from: string, allowlist: MailboxAllowlist) => boolean;
+/**
+ * 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 declare const allowedLinks: (links: readonly string[], allowlist: MailboxAllowlist) => string[];
+/**
+ * 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 declare const applyMailboxAllowlist: (emails: readonly ReceivedEmail[], allowlist: MailboxAllowlist) => ReceivedEmail[];

package/dist/wirings/persona/persona-mailbox.js

@@ -0,0 +1,53 @@
+const senderMatches = (from, entry) => {
+    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, allowlist) => 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, allowlist) => {
+    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, allowlist) => emails
+    .filter((email) => isAllowedSender(email.from, allowlist))
+    .map((email) => ({ ...email, links: allowedLinks(email.links, allowlist) }));

package/dist/wirings/persona/persona.types.d.ts

@@ -0,0 +1,125 @@
+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/dist/wirings/persona/persona.types.js

@@ -0,0 +1 @@
+export {};

package/dist/wirings/persona/validate-personas.d.ts

@@ -0,0 +1,53 @@
+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 declare const isRunnablePersona: (persona: {
+    runnable?: boolean;
+    account?: {
+        provider?: string;
+    };
+}) => boolean;
+/**
+ * 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 declare function validateAndBuildPersonasMeta(definitions: PersonaDefinitions): PersonasMeta;
+/** 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 declare const verifyPersonaRoles: (persona: string, expected: readonly string[], actual: readonly string[]) => RoleVerification;
+/** The message a run stops with, or `null` when the roles line up. */
+export declare const roleMismatchMessage: (verification: RoleVerification) => string | null;
+/** Convenience: the meta a run needs, with `runnable` already resolved. */
+export declare const runnablePersonas: (meta: PersonasMeta) => PersonaMeta[];