@pikku/cli 0.12.124 → 0.12.126

package/dist/src/functions/db/postgres/postgres-introspector.js

@@ -1,5 +1,6 @@
 import { Pool } from 'pg';
 import { MIGRATION_TRACKING_TABLE } from '../db-migrator.js';
+import { parseCheckEnumValues } from '../check-enums.js';
 /** Table display name matching `listTables` (schema-qualified unless `public`). */
 function tableKey(schema, table) {
     return schema === 'public' ? table : `${schema}.${table}`;
@@ -85,6 +86,8 @@ export class PostgresIntrospector {
        FROM information_schema.columns c
        WHERE c.table_schema = $2 AND c.table_name = $1
        ORDER BY c.ordinal_position`, [tableName, schema]);
+        const checkEnums = (await this.getCheckEnums({ schema, name: tableName })).get(table) ??
+            new Map();
         return result.rows.map((r) => ({
             name: r.column_name,
             type: resolveColumnType(r.data_type, r.udt_name),
@@ -93,8 +96,51 @@ export class PostgresIntrospector {
             pk: Boolean(r.is_pk),
             defaultValue: r.column_default,
             generated: r.is_generated === 'ALWAYS',
+            enumValues: checkEnums.get(r.column_name),
         }));
     }
+    /**
+     * Columns constrained to a value list by a `CHECK (col IN (…))`, keyed like
+     * {@link getAllColumns} then by column name. Postgres has native enums, but
+     * a CHECK is the other half of how a schema says "one of these" — and the
+     * one an app written against SQLite as well ends up using, since SQLite has
+     * no enums at all. Left as plain `string`, every caller narrows it by hand.
+     *
+     * Only single-column constraints are read: `conkey` naming two columns means
+     * neither is restricted to the list on its own.
+     *
+     * `table` limits the sweep to one table; omitted, it covers the schema. Both
+     * are one round-trip — see {@link getAllColumns}.
+     */
+    async getCheckEnums(table) {
+        const result = await this.client.query(`SELECT n.nspname   AS table_schema,
+              cl.relname  AS table_name,
+              a.attname   AS column_name,
+              pg_get_constraintdef(co.oid) AS def
+       FROM pg_constraint co
+       JOIN pg_class cl     ON cl.oid = co.conrelid
+       JOIN pg_namespace n  ON n.oid = cl.relnamespace
+       JOIN pg_attribute a  ON a.attrelid = co.conrelid AND a.attnum = co.conkey[1]
+       WHERE co.contype = 'c'
+         AND array_length(co.conkey, 1) = 1
+         AND n.nspname NOT IN ('information_schema', 'pg_catalog', 'pg_toast')
+         AND n.nspname NOT LIKE 'pg_temp_%'
+         AND ($1::text IS NULL OR (n.nspname = $1 AND cl.relname = $2))`, [table?.schema ?? null, table?.name ?? null]);
+        const byTable = new Map();
+        for (const r of result.rows) {
+            const values = parseCheckEnumValues(r.def);
+            if (!values)
+                continue;
+            const key = tableKey(r.table_schema, r.table_name);
+            let cols = byTable.get(key);
+            if (!cols) {
+                cols = new Map();
+                byTable.set(key, cols);
+            }
+            cols.set(r.column_name, values);
+        }
+        return byTable;
+    }
     async getForeignKeys(table) {
         const dotIdx = table.indexOf('.');
         const schema = dotIdx >= 0 ? table.slice(0, dotIdx) : 'public';
@@ -153,6 +199,7 @@ export class PostgresIntrospector {
        WHERE c.table_schema NOT IN ('information_schema', 'pg_catalog', 'pg_toast')
          AND c.table_schema NOT LIKE 'pg_temp_%'
        ORDER BY c.table_schema, c.table_name, c.ordinal_position`);
+        const checkEnums = await this.getCheckEnums();
         const byTable = new Map();
         for (const r of result.rows) {
             if (isMigrationTracking(r.table_name))
@@ -171,6 +218,7 @@ export class PostgresIntrospector {
                 pk: Boolean(r.is_pk),
                 defaultValue: r.column_default,
                 generated: r.is_generated === 'ALWAYS',
+                enumValues: checkEnums.get(key)?.get(r.column_name),
             });
         }
         return byTable;

package/dist/src/functions/db/sqlite/sqlite-introspector.d.ts

@@ -7,10 +7,9 @@ export declare class SqliteIntrospector implements DbIntrospector {
     getColumns(table: string): Promise<ColumnInfo[]>;
     /**
      * SQLite has no native enums, but a `CHECK (col IN ('a','b',…))` constraint is
-     * an enum by another name. Parse the table's stored `CREATE TABLE` DDL and map
-     * each constrained column to its allowed values so codegen can type it as a
-     * union. Only the positive `col IN (…)` form is recognised (the convention);
-     * `NOT IN`, ranges, and boolean expressions are left as plain `string`.
+     * an enum by another name. Read back the table's stored `CREATE TABLE` DDL —
+     * which SQLite keeps verbatim, comments included — and map each constrained
+     * column to its allowed values so codegen can type it as a union.
      */
     private parseCheckEnums;
     getForeignKeys(table: string): Promise<ForeignKeyInfo[]>;

package/dist/src/functions/db/sqlite/sqlite-introspector.js

@@ -1,4 +1,5 @@
 import { MIGRATION_TRACKING_TABLE } from '../db-migrator.js';
+import { parseCheckEnumsFromDdl } from '../check-enums.js';
 const SKIP_TABLES = new Set(['sqlite_sequence', MIGRATION_TRACKING_TABLE]);
 export class SqliteIntrospector {
     db;
@@ -34,28 +35,15 @@ export class SqliteIntrospector {
     }
     /**
      * SQLite has no native enums, but a `CHECK (col IN ('a','b',…))` constraint is
-     * an enum by another name. Parse the table's stored `CREATE TABLE` DDL and map
-     * each constrained column to its allowed values so codegen can type it as a
-     * union. Only the positive `col IN (…)` form is recognised (the convention);
-     * `NOT IN`, ranges, and boolean expressions are left as plain `string`.
+     * an enum by another name. Read back the table's stored `CREATE TABLE` DDL —
+     * which SQLite keeps verbatim, comments included — and map each constrained
+     * column to its allowed values so codegen can type it as a union.
      */
     parseCheckEnums(table) {
-        const out = new Map();
         const row = this.db
             .prepare(`SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?`)
             .get(table);
-        const ddl = row?.sql;
-        if (!ddl)
-            return out;
-        const checkIn = /CHECK\s*\(\s*"?(\w+)"?\s+IN\s*\(([^)]*)\)/gi;
-        let m;
-        while ((m = checkIn.exec(ddl))) {
-            const column = m[1];
-            const values = [...m[2].matchAll(/'((?:[^']|'')*)'/g)].map((q) => q[1].replace(/''/g, "'"));
-            if (values.length > 0)
-                out.set(column, values);
-        }
-        return out;
+        return row?.sql ? parseCheckEnumsFromDdl(row.sql) : new Map();
     }
     async getForeignKeys(table) {
         const escaped = `"${table.replace(/"/g, '""')}"`;

package/dist/src/functions/wirings/virtual-user/serialize-virtual-user-functions.d.ts

@@ -12,12 +12,15 @@ export interface VirtualUserGenOutput {
  * `pikku persona run` does the same thing from a terminal; this is the same run
  * started over RPC, from CI or from a console, with the result kept.
  *
- * A virtual user is NOT a workflow and NOT a queued job. It explores, so no two
- * attempts take the same steps and there is nothing to replay; and the run
- * record already carries the progress a queue would only be holding on the way
- * here. So `runVirtualUser` writes the record, kicks the run off without
- * awaiting it, and returns the id. The one cost is stated on the record: a
- * restart mid-run strands it at `running`.
+ * A virtual user is still NOT a workflow: it explores, so no two attempts take
+ * the same steps and there is nothing to replay. What it does need is a
+ * trigger. `runVirtualUser` writes the record and returns the id; the run
+ * itself is dispatched onto `pikku-virtual-user-runs`, at one attempt, because
+ * a queue is the only dispatch that survives a deployment which puts each
+ * function in its own unit — there is no in-process promise to leave running
+ * there, and an RPC to a function nothing triggers has nowhere to land. A
+ * project with no queue service keeps the in-process dispatch, which is
+ * correct for the single process it runs in.
  *
  * Emitted as two files. The schemas are zod, and the inspector reads a zod
  * schema by importing the module that declares it — which it cannot do for the

package/dist/src/functions/wirings/virtual-user/serialize-virtual-user-functions.js

@@ -8,12 +8,15 @@
  * `pikku persona run` does the same thing from a terminal; this is the same run
  * started over RPC, from CI or from a console, with the result kept.
  *
- * A virtual user is NOT a workflow and NOT a queued job. It explores, so no two
- * attempts take the same steps and there is nothing to replay; and the run
- * record already carries the progress a queue would only be holding on the way
- * here. So `runVirtualUser` writes the record, kicks the run off without
- * awaiting it, and returns the id. The one cost is stated on the record: a
- * restart mid-run strands it at `running`.
+ * A virtual user is still NOT a workflow: it explores, so no two attempts take
+ * the same steps and there is nothing to replay. What it does need is a
+ * trigger. `runVirtualUser` writes the record and returns the id; the run
+ * itself is dispatched onto `pikku-virtual-user-runs`, at one attempt, because
+ * a queue is the only dispatch that survives a deployment which puts each
+ * function in its own unit — there is no in-process promise to leave running
+ * there, and an RPC to a function nothing triggers has nowhere to land. A
+ * project with no queue service keeps the in-process dispatch, which is
+ * correct for the single process it runs in.
  *
  * Emitted as two files. The schemas are zod, and the inspector reads a zod
  * schema by importing the module that declares it — which it cannot do for the
@@ -265,6 +268,7 @@ export const ExecuteVirtualUserRunOutput = z.object({
  */
 import { pikkuFunc, pikkuSessionlessFunc, type Session } from '${leaf('function')}'
 import { pikkuMiddleware } from '${leaf('middleware')}'
+import { wireQueueWorker } from '${leaf('queue')}'
 import { defineScope } from '${leaf('scopes')}'
 import {
   executeVirtualUserRun as executeRun,
@@ -278,7 +282,7 @@ import {
   virtualUserScheduleRunInput,
   writeVirtualUserSchedule,
 } from '@pikku/core/virtual-user'
-import { createPersonas, personaConfigs } from '${pathToPersonas}'
+import { createPersonas, personaConfigs, personaEnvironments } from '${pathToPersonas}'
 import {
   ExecuteVirtualUserRunInput,
   ExecuteVirtualUserRunOutput,
@@ -326,13 +330,20 @@ export const runVirtualUser = pikkuFunc({
   scopes: ['virtualUser:run'],
   input: RunVirtualUserInput,
   output: RunVirtualUserOutput,
-  func: async ({ virtualUserRunStore, config }, input, { session, rpc }) => {
+  func: async (
+    { virtualUserRunStore, config, queueService },
+    input,
+    { session, rpc }
+  ) => {
     const { runId, persona, disposition, goals, memory, seed } =
       await startVirtualUserRun({
         store: virtualUserRunStore,
         personas: personaConfigs,
-        // Cast because an application's Config is its own interface and need
-        // not declare nodeEnv at all.
+        // Which of the configured environments this process is decides whether
+        // a run is against production. \`config\` is only the fallback for a
+        // project that configures none, and is cast because an application's
+        // Config is its own interface and need not declare nodeEnv at all.
+        environments: personaEnvironments,
         config: config as { nodeEnv?: string } | undefined,
         persona: input.persona,
         disposition: input.disposition,
@@ -342,26 +353,35 @@ export const runVirtualUser = pikkuFunc({
         startedBy: session?.userId ?? null,
       })
 
-    // Deliberately not awaited: a run takes minutes, and a held-open request
-    // survives neither a rollout nor a proxy timeout. executeVirtualUserRun
-    // writes both outcomes to the record itself, so the only thing left to
-    // handle here is a rejection escaping the promise — without the catch it
-    // becomes an unhandled rejection and takes the process with it.
-    void rpc!
-      .invoke('executeVirtualUserRun', {
-        runId,
-        persona,
-        disposition,
-        goals,
-        memory,
-        seed,
-        budget: input.budget,
-        // Rides the dispatch and nothing else. The run record is deliberately
-        // not given it: a record outlives the run, and a credential in a row
-        // somebody can read back is a credential leak.
-        operatorToken: input.operatorToken,
+    const job = {
+      runId,
+      persona,
+      disposition,
+      goals,
+      memory,
+      seed,
+      budget: input.budget,
+      // Rides the dispatch and nothing else. The run record is deliberately
+      // not given it: a record outlives the run, and a credential in a row
+      // somebody can read back is a credential leak.
+      operatorToken: input.operatorToken,
+    }
+
+    if (queueService) {
+      // One attempt. A run is an exploration, so a redelivery is a second
+      // different outing writing into a record that already has an outcome.
+      await queueService.add('pikku-virtual-user-runs', job, {
+        attempts: 1,
+        pikkuUserId: session?.userId,
       })
-      .catch(() => {})
+    } else {
+      // Deliberately not awaited: a run takes minutes, and a held-open request
+      // survives neither a rollout nor a proxy timeout. executeVirtualUserRun
+      // writes both outcomes to the record itself, so the only thing left to
+      // handle here is a rejection escaping the promise — without the catch it
+      // becomes an unhandled rejection and takes the process with it.
+      void rpc!.invoke('executeVirtualUserRun', job).catch(() => {})
+    }
 
     return { runId }
   },
@@ -557,7 +577,8 @@ export const tickVirtualUserSchedules = pikkuSessionlessFunc<void, void>({
 
 /**
  * The run itself. Not exposed: it is dispatched by \`runVirtualUser\` and has no
- * caller of its own.
+ * caller of its own — but it is wired to a queue below, which is what gives it
+ * a unit of its own under a per-function deploy.
  */
 export const executeVirtualUserRun = pikkuSessionlessFunc({
   tags: ['pikku'],
@@ -578,6 +599,12 @@ export const executeVirtualUserRun = pikkuSessionlessFunc({
       ...input,
     }),
 })
+
+wireQueueWorker({
+  name: 'pikku-virtual-user-runs',
+  tags: ['pikku'],
+  func: executeVirtualUserRun,
+})
 `;
     return { schemas, functions };
 };

package/dist/src/server/actor-sign-in.d.ts

@@ -1,5 +1,28 @@
 import type { Logger } from '@pikku/core/services';
 export declare const ACTOR_SECRET_ENV = "SCENARIO_ACTOR_SECRET";
+/**
+ * Read as an alias for the root when a project set only this one, and then
+ * cleared: the root derives every persona's credential, so a bundle holding it
+ * holds all of them. What the browser switcher gets instead is
+ * {@link DEV_ACTOR_SECRETS_ENV}.
+ */
 export declare const VITE_ACTOR_SECRET_ENV = "VITE_SCENARIO_ACTOR_SECRET";
-export declare const enableDevActorSignIn: (logger: Logger) => void;
+/**
+ * The dev switcher's credentials, `{ email: secret }` as JSON — one capability
+ * per declared persona, each refused for any other address.
+ */
+export declare const DEV_ACTOR_SECRETS_ENV = "VITE_DEV_ACTOR_SECRETS";
+/** Just enough of a persona to mint their credential. */
+export interface DevActorIdentity {
+    id: string;
+    email: string;
+}
+/**
+ * Turn on passwordless actor sign-in for this `pikku dev` run and hand the
+ * frontend switcher one credential per declared persona.
+ *
+ * `personas` is a thunk because resolving them means reading inspector state,
+ * which is not worth doing for a project that declares none.
+ */
+export declare const enableDevActorSignIn: (logger: Logger, personas?: () => Promise<DevActorIdentity[]>) => Promise<void>;
 export declare const disableDevActorSignIn: (logger: Logger) => void;

package/dist/src/server/actor-sign-in.js

@@ -1,9 +1,28 @@
 import { randomBytes } from 'node:crypto';
 import { ACTOR_SIGN_IN_OPT_IN_ENV, DEV_ACTOR_SIGN_IN_ENV, } from '@pikku/better-auth';
+import { ACTOR_ROOT_SECRET_MIN_LENGTH, deriveActorSecret, } from '@pikku/core/services';
 export const ACTOR_SECRET_ENV = 'SCENARIO_ACTOR_SECRET';
+/**
+ * Read as an alias for the root when a project set only this one, and then
+ * cleared: the root derives every persona's credential, so a bundle holding it
+ * holds all of them. What the browser switcher gets instead is
+ * {@link DEV_ACTOR_SECRETS_ENV}.
+ */
 export const VITE_ACTOR_SECRET_ENV = 'VITE_SCENARIO_ACTOR_SECRET';
+/**
+ * The dev switcher's credentials, `{ email: secret }` as JSON — one capability
+ * per declared persona, each refused for any other address.
+ */
+export const DEV_ACTOR_SECRETS_ENV = 'VITE_DEV_ACTOR_SECRETS';
 const mintEphemeralSecret = () => randomBytes(32).toString('base64url');
-export const enableDevActorSignIn = (logger) => {
+/**
+ * Turn on passwordless actor sign-in for this `pikku dev` run and hand the
+ * frontend switcher one credential per declared persona.
+ *
+ * `personas` is a thunk because resolving them means reading inspector state,
+ * which is not worth doing for a project that declares none.
+ */
+export const enableDevActorSignIn = async (logger, personas) => {
     process.env[DEV_ACTOR_SIGN_IN_ENV] = 'true';
     const configured = process.env[ACTOR_SECRET_ENV] || undefined;
     const configuredForFrontend = process.env[VITE_ACTOR_SECRET_ENV] || undefined;
@@ -14,10 +33,34 @@ export const enableDevActorSignIn = (logger) => {
     }
     const secret = configured ?? configuredForFrontend ?? mintEphemeralSecret();
     process.env[ACTOR_SECRET_ENV] = secret;
-    process.env[VITE_ACTOR_SECRET_ENV] = secret;
+    delete process.env[VITE_ACTOR_SECRET_ENV];
     logger.info((configured ?? configuredForFrontend)
         ? `Actor quick login enabled, using the ${configured ? ACTOR_SECRET_ENV : VITE_ACTOR_SECRET_ENV} already in this environment`
         : 'Actor quick login enabled with a secret minted for this run — nothing to configure, and it is gone when the server stops');
+    if (secret.length < ACTOR_ROOT_SECRET_MIN_LENGTH) {
+        logger.warn(`${ACTOR_SECRET_ENV} is shorter than ${ACTOR_ROOT_SECRET_MIN_LENGTH} characters, so no persona credential can be derived from it and every actor sign-in will be refused. ` +
+            `Generate one with \`openssl rand -base64 32\`, or unset it and let this run mint its own.`);
+        return;
+    }
+    if (!personas) {
+        return;
+    }
+    try {
+        const declared = await personas();
+        if (declared.length === 0) {
+            return;
+        }
+        const credentials = {};
+        for (const persona of declared) {
+            credentials[persona.email] = await deriveActorSecret(secret, persona.email);
+        }
+        process.env[DEV_ACTOR_SECRETS_ENV] = JSON.stringify(credentials);
+        logger.info(`Minted ${declared.length} persona credential${declared.length === 1 ? '' : 's'} for the dev switcher — the root stays on the server`);
+    }
+    catch (cause) {
+        logger.warn(`Could not mint persona credentials for the dev switcher: ${cause instanceof Error ? cause.message : String(cause)}. ` +
+            `The switcher will render nothing; scenario runs are unaffected.`);
+    }
 };
 export const disableDevActorSignIn = (logger) => {
     if (process.env[DEV_ACTOR_SIGN_IN_ENV] !== undefined) {

package/dist/src/server/dev-server-runner.interface.d.ts

@@ -16,6 +16,15 @@ export interface DevServerInstance {
     start(): Promise<void>;
     /** Full teardown — closes the server and any owned WebSocket server. */
     stop(): Promise<void>;
+    /**
+     * The port the server actually bound, readable once `start()` has resolved.
+     *
+     * Diverges from the requested port whenever that was `0`, which is the only
+     * race-free way for a parent process to hand the server a port: anything the
+     * parent picks can be taken between its check and the server's bind. The
+     * ready line is built from this, so a parent learns the port by reading it.
+     */
+    readonly port: number;
 }
 /** Config shape both runtimes accept (Core config + host/port/content). */
 export type DevServerConfig = NodeHTTPServerConfig;

package/dist/src/server/node-server-runner.js

@@ -51,6 +51,9 @@ export class NodeServerRunner {
         return {
             init: () => server.init(),
             start: () => server.start(),
+            get port() {
+                return server.port;
+            },
             stop: async () => {
                 if (wss) {
                     await new Promise((resolve, reject) => wss.close((err) => (err ? reject(err) : resolve())));

package/dist/src/server/server-ready.d.ts

@@ -1,12 +1,9 @@
 /**
- * Printed once the server is listening AND the project's `afterStart`
- * lifecycle has resolved.
+ * The readiness handshake, owned by `@pikku/deploy` so the CLI and the
+ * standalone provider's generated server entry print and wait on the same
+ * string. Re-exported here because `--spawn` and the dev/serve commands have
+ * always imported it from this path.
  *
- * The runtime's own `listening on …` line is emitted inside `server.start()`,
- * which runs *before* `afterStart` — so anything a project seeds there (users,
- * scopes, fixtures) is still pending when it appears, and a parent process
- * that treats it as readiness races the seed. This marker is the point at
- * which the server is actually usable, and it is what `--spawn` waits for.
+ * @see {@link SERVER_READY_MARKER} for why `listening on …` is not readiness.
  */
-export declare const SERVER_READY_MARKER = "pikku: ready";
-export declare const serverReadyLine: (hostname: string, port: number) => string;
+export { SERVER_READY_MARKER, serverReadyLine } from '@pikku/deploy';

package/dist/src/server/server-ready.js

@@ -1,12 +1,9 @@
 /**
- * Printed once the server is listening AND the project's `afterStart`
- * lifecycle has resolved.
+ * The readiness handshake, owned by `@pikku/deploy` so the CLI and the
+ * standalone provider's generated server entry print and wait on the same
+ * string. Re-exported here because `--spawn` and the dev/serve commands have
+ * always imported it from this path.
  *
- * The runtime's own `listening on …` line is emitted inside `server.start()`,
- * which runs *before* `afterStart` — so anything a project seeds there (users,
- * scopes, fixtures) is still pending when it appears, and a parent process
- * that treats it as readiness races the seed. This marker is the point at
- * which the server is actually usable, and it is what `--spawn` waits for.
+ * @see {@link SERVER_READY_MARKER} for why `listening on …` is not readiness.
  */
-export const SERVER_READY_MARKER = 'pikku: ready';
-export const serverReadyLine = (hostname, port) => `${SERVER_READY_MARKER} on http://${hostname}:${port}`;
+export { SERVER_READY_MARKER, serverReadyLine } from '@pikku/deploy';

package/dist/src/utils/frontend.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Throw unless `dir` holds a built frontend.
+ *
+ * Both serving and deploying read a frontend's output rather than producing it,
+ * so an unbuilt directory is the one failure mode the config invites, and it is
+ * silent everywhere it is not caught: a server boots fine and answers every
+ * page with a 404, and a deploy ships a binary with nothing inside it.
+ */
+export declare function assertFrontendBuilt(dir: string): Promise<void>;

package/dist/src/utils/frontend.js

@@ -0,0 +1,18 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Throw unless `dir` holds a built frontend.
+ *
+ * Both serving and deploying read a frontend's output rather than producing it,
+ * so an unbuilt directory is the one failure mode the config invites, and it is
+ * silent everywhere it is not caught: a server boots fine and answers every
+ * page with a 404, and a deploy ships a binary with nothing inside it.
+ */
+export async function assertFrontendBuilt(dir) {
+    try {
+        await stat(join(dir, 'index.html'));
+    }
+    catch {
+        throw new Error(`No frontend build found at ${dir} — pikku serves your frontend's output and never builds it, so run the frontend's build first (or drop "frontend" from pikku.config.json).`);
+    }
+}

package/dist/src/utils/persona-credentials.d.ts

@@ -1,12 +1,33 @@
 import type { VariablesService } from '@pikku/core/services';
-import type { HttpPersonasConfig } from '@pikku/core/persona';
+import type { ActorSecretResolver, HttpPersonasConfig } from '@pikku/core/persona';
 /** A Fabric operator token, which is what a deployed stage accepts. */
 export declare const OPERATOR_TOKEN_VARIABLE = "FABRIC_OPERATOR_TOKEN";
-/** The actor plugin's passwordless secret, which only `pikku dev` serves. */
+/**
+ * The ROOT actor secret, which derives every persona's credential and so is
+ * entitled to all of them. Only `pikku dev` serves the endpoint it opens.
+ */
 export declare const ACTOR_SECRET_VARIABLE = "SCENARIO_ACTOR_SECRET";
+/**
+ * Already-derived per-persona credentials, `id=secret` comma-separated — what a
+ * run is given when it should be able to sign in as some personas and not the
+ * rest. Each value is bound to that persona's address by the target, so the
+ * list is the whole of what this run can be.
+ */
+export declare const PERSONA_SECRETS_VARIABLE = "PIKKU_PERSONA_SECRETS";
 /** Opt in to creating persona accounts the target does not already have. */
 export declare const CREATE_MISSING_VARIABLE = "PIKKU_PERSONA_CREATE_MISSING";
 export type PersonaCredentials = Pick<HttpPersonasConfig, 'secret' | 'operator'>;
+/**
+ * `id=secret,id=secret` into a lookup. A value containing `=` is kept whole —
+ * base64url never produces one, but a hand-written credential might.
+ */
+export declare const parsePersonaSecrets: (raw: string) => Record<string, string>;
+/**
+ * Refuses rather than falling through to the root: a run handed a narrow set of
+ * credentials asking for a persona outside it is a run doing something nobody
+ * authorised, and the useful answer names the persona.
+ */
+export declare const personaSecretResolver: (secrets: Record<string, string>) => ActorSecretResolver;
 /**
  * How the personas in this run will sign in, decided by which credential the
  * environment actually holds.

package/dist/src/utils/persona-credentials.js

@@ -1,9 +1,55 @@
 /** A Fabric operator token, which is what a deployed stage accepts. */
 export const OPERATOR_TOKEN_VARIABLE = 'FABRIC_OPERATOR_TOKEN';
-/** The actor plugin's passwordless secret, which only `pikku dev` serves. */
+/**
+ * The ROOT actor secret, which derives every persona's credential and so is
+ * entitled to all of them. Only `pikku dev` serves the endpoint it opens.
+ */
 export const ACTOR_SECRET_VARIABLE = 'SCENARIO_ACTOR_SECRET';
+/**
+ * Already-derived per-persona credentials, `id=secret` comma-separated — what a
+ * run is given when it should be able to sign in as some personas and not the
+ * rest. Each value is bound to that persona's address by the target, so the
+ * list is the whole of what this run can be.
+ */
+export const PERSONA_SECRETS_VARIABLE = 'PIKKU_PERSONA_SECRETS';
 /** Opt in to creating persona accounts the target does not already have. */
 export const CREATE_MISSING_VARIABLE = 'PIKKU_PERSONA_CREATE_MISSING';
+/**
+ * `id=secret,id=secret` into a lookup. A value containing `=` is kept whole —
+ * base64url never produces one, but a hand-written credential might.
+ */
+export const parsePersonaSecrets = (raw) => {
+    const secrets = {};
+    for (const entry of raw.split(',')) {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq <= 0) {
+            throw new Error(`${PERSONA_SECRETS_VARIABLE} entry '${trimmed}' is not 'personaId=secret'`);
+        }
+        secrets[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+    }
+    if (Object.keys(secrets).length === 0) {
+        throw new Error(`${PERSONA_SECRETS_VARIABLE} is set but lists no personas`);
+    }
+    return secrets;
+};
+/**
+ * Refuses rather than falling through to the root: a run handed a narrow set of
+ * credentials asking for a persona outside it is a run doing something nobody
+ * authorised, and the useful answer names the persona.
+ */
+export const personaSecretResolver = (secrets) => {
+    return (persona) => {
+        const secret = secrets[persona.id];
+        if (!secret) {
+            throw new Error(`No credential for persona '${persona.id}' — ${PERSONA_SECRETS_VARIABLE} carries ` +
+                `${Object.keys(secrets).sort().join(', ')}. Mint one with \`pikku persona secret ${persona.id}\`.`);
+        }
+        return secret;
+    };
+};
 /**
  * How the personas in this run will sign in, decided by which credential the
  * environment actually holds.
@@ -26,11 +72,18 @@ export const resolvePersonaCredentials = async (variables, what) => {
         const createMissing = String(await variables.get(CREATE_MISSING_VARIABLE)) === 'true';
         return { operator: { token, createMissing } };
     }
+    const personaSecrets = await variables.get(PERSONA_SECRETS_VARIABLE);
+    if (personaSecrets) {
+        return {
+            secret: personaSecretResolver(parsePersonaSecrets(String(personaSecrets))),
+        };
+    }
     const secret = await variables.get(ACTOR_SECRET_VARIABLE);
     if (secret) {
         return { secret };
     }
     throw new Error(`Neither ${OPERATOR_TOKEN_VARIABLE} nor ${ACTOR_SECRET_VARIABLE} is set — ${what} cannot sign in. ` +
         `Export ${ACTOR_SECRET_VARIABLE} against a local \`pikku dev\` target, or ` +
-        `${OPERATOR_TOKEN_VARIABLE} against a deployed one (never put either in pikku.config.json).`);
+        `${OPERATOR_TOKEN_VARIABLE} against a deployed one (never put either in pikku.config.json). ` +
+        `To hand this run only some personas, mint their credentials with \`pikku persona secret\` and set ${PERSONA_SECRETS_VARIABLE}.`);
 };