@pikku/core 0.12.90 → 0.12.92

package/CHANGELOG.md

@@ -1,3 +1,59 @@
+## 0.12.92
+
+### Patch Changes
+
+- b521f1b: Resolve the persona to impersonate during the fabric operator sign-in.
+
+  `POST /sign-in/fabric` now takes an optional
+  `actAs: { email, name?, create?, role? }`
+  and returns `actAs: { userId }` — the stage's own id for that address, looked up
+  before creating and created only when asked.
+
+  It has to happen there. Impersonation names a user id, a persona only knows an
+  email, and since better-auth's `admin()` plugin was dropped no HTTP endpoint
+  lists users — so the two calls the scenario runner made to resolve one
+  (`/auth/admin/list-users`, then `/auth/admin/create-user`) had nothing left to
+  reach and every deployed persona failed with `YOU_ARE_NOT_ALLOWED_TO_LIST_USERS`.
+  The adapter is already in hand on the sign-in request and the operator token has
+  already been verified, so the lookup is free and gated by the same check that
+  mints the session.
+
+  A created row gets a `role` only when the caller names one. pikku has no `role`
+  column of its own any more, but an app may still run better-auth's `admin()`
+  plugin and constrain that column, so the persona's first role is passed through
+  for those.
+
+  `OperatorSignInOptions.adminPath` is removed; nothing points at it any more.
+
+  A Fabric operator row now also satisfies the default impersonation gate.
+  `fabric()` grants the `admin` scope only when handed a `ScopeService`, and no
+  app template wires one — so the operator signed in holding nothing and every
+  impersonated request fell back to the operator's own session. The `fabric`
+  column is written by nothing but that sign-in, after an RS256 verification
+  against the stage's public key, so the row's existence is the authorization.
+  The scope half of the gate still fails closed.
+
+## 0.12.91
+
+### Patch Changes
+
+- 09aff02: Let personas run against a deployed stage.
+
+  A persona could only ever sign in through the actor plugin, which is
+  passwordless and therefore a local-development mechanism — so the scenario
+  suite had no way to reach staging or production, including the parts of it
+  that never assert anything about a logged-in user.
+
+  `HttpPersonasConfig` now takes `operator` as an alternative to `secret`. Given
+  Fabric operator credentials, a persona signs in at `/auth/sign-in/fabric` and
+  acts as its account through the `x-pikku-impersonate-user-id` header, which is
+  gated on the umbrella `admin` scope rather than `user.role`. Nothing on the
+  deployed side holds a test credential: the stage verifies operator tokens and
+  cannot mint them.
+
+  Provisioning stays opt-in (`createMissing`), so pointing a run at a live
+  environment never quietly writes user rows into it.
+
 ## 0.12.90
 
 ### Patch Changes

package/dist/services/http-personas.d.ts

@@ -1,5 +1,6 @@
 import type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, ScenarioInvokeOptions, ScenarioHttpResponse } from './personas-service.js';
 import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
+import { type OperatorSignInOptions } from './persona-sign-in.js';
 export interface HttpPersonasConfig {
     /**
      * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.
@@ -11,8 +12,19 @@ export interface HttpPersonasConfig {
     /**
      * The impersonation secret. Sign-in only ever works for user rows flagged
      * `actor: true` — knowing the secret never impersonates real users.
+     *
+     * The local-development credential. A deployed stage has none, and passes
+     * {@link HttpPersonasConfig.operator} instead.
+     */
+    secret?: string;
+    /**
+     * Fabric operator credentials, for signing personas into a DEPLOYED stage.
+     *
+     * Mutually exclusive with {@link HttpPersonasConfig.secret}: the operator
+     * path acts as the persona through an admin session rather than logging in as
+     * them, so no test credential has to exist on the target at all.
      */
-    secret: string;
+    operator?: OperatorSignInOptions;
     /** Persona id → the declaration with its address filled in. */
     personas: Record<string, ResolvedPersona>;
     /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
@@ -29,12 +41,13 @@ export interface HttpPersonasConfig {
     model?: string;
 }
 /**
- * Default HTTP-backed persona. Signs in lazily on first invoke via the Better
- * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
- * the plugin upserts the actor-flagged user row and mints a session whose
- * `actor` flag flows into audits/analytics). Holds the session cookies for
- * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
- * outlive a session).
+ * Default HTTP-backed persona. Signs in lazily on first invoke, holds the
+ * session cookies for its lifetime, and re-logs-in once on a 401 mid-run (long
+ * health-check runs can outlive a session).
+ *
+ * How it signs in depends on the target, and the two ways are not
+ * interchangeable — see {@link ActorSignIn} for local development and
+ * {@link OperatorSignIn} for a deployed stage.
  */
 export declare class HttpPersona implements ScenarioPersona {
     readonly name: string;
@@ -48,6 +61,7 @@ export declare class HttpPersona implements ScenarioPersona {
      * established.
      */
     private signedIn;
+    private signIn;
     constructor(name: string, persona: ResolvedPersona, config: HttpPersonasConfig);
     get email(): string;
     invoke(rpcName: string, data: unknown): Promise<unknown>;

package/dist/services/http-personas.js

@@ -1,15 +1,17 @@
 import { readScenarioHttpResponse } from './personas-service.js';
 import { runConversation } from '../wirings/actor-flow/run-conversation.js';
 import { createCookieJar, } from '../wirings/workflow/scenario-cookie-jar.js';
+import { ActorSignIn, OperatorSignIn, } from './persona-sign-in.js';
 import { getSingletonServices } from '../pikku-state.js';
 import { AIProviderNotConfiguredError } from '../errors/errors.js';
 /**
- * Default HTTP-backed persona. Signs in lazily on first invoke via the Better
- * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
- * the plugin upserts the actor-flagged user row and mints a session whose
- * `actor` flag flows into audits/analytics). Holds the session cookies for
- * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
- * outlive a session).
+ * Default HTTP-backed persona. Signs in lazily on first invoke, holds the
+ * session cookies for its lifetime, and re-logs-in once on a 401 mid-run (long
+ * health-check runs can outlive a session).
+ *
+ * How it signs in depends on the target, and the two ways are not
+ * interchangeable — see {@link ActorSignIn} for local development and
+ * {@link OperatorSignIn} for a deployed stage.
  */
 export class HttpPersona {
     name;
@@ -23,11 +25,21 @@ export class HttpPersona {
      * established.
      */
     signedIn = false;
+    signIn;
     constructor(name, persona, config) {
         this.name = name;
         this.persona = persona;
         this.config = config;
         this.jar = createCookieJar(config.apiUrl);
+        if (config.operator) {
+            this.signIn = new OperatorSignIn(config.apiUrl, config.operator);
+        }
+        else if (config.secret) {
+            this.signIn = new ActorSignIn(config.apiUrl, config.secret, config.signInPath ?? '/auth/sign-in/actor');
+        }
+        else {
+            throw new Error(`[scenario] persona '${name}' has no way to sign in — set 'secret' for a dev target or 'operator' for a deployed one`);
+        }
     }
     get email() {
         return this.persona.email;
@@ -101,7 +113,9 @@ export class HttpPersona {
             await this.login();
         }
         const sessionPath = this.config.sessionPath ?? '/auth/get-session';
-        const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`);
+        const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`, {
+            headers: this.signIn.headers(),
+        });
         if (!res.ok) {
             return null;
         }
@@ -154,7 +168,10 @@ export class HttpPersona {
         const url = `${this.config.apiUrl}${rpcPath}/${subPath}`;
         const send = () => this.jar.fetch(url, {
             method: 'POST',
-            headers: { 'content-type': 'application/json' },
+            headers: {
+                'content-type': 'application/json',
+                ...this.signIn.headers(),
+            },
             body: JSON.stringify(body),
         });
         let res = await send();
@@ -176,7 +193,11 @@ export class HttpPersona {
         const rpcPath = this.config.rpcPath ?? '/rpc';
         return this.jar.fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
             method: 'POST',
-            headers: { 'content-type': 'application/json', ...extraHeaders },
+            headers: {
+                'content-type': 'application/json',
+                ...this.signIn.headers(),
+                ...extraHeaders,
+            },
             body: JSON.stringify({ data }),
         });
     }
@@ -186,25 +207,7 @@ export class HttpPersona {
         this.signedIn = false;
     }
     async login() {
-        const signInPath = this.config.signInPath ?? '/auth/sign-in/actor';
-        const res = await this.jar.fetch(`${this.config.apiUrl}${signInPath}`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({
-                email: this.persona.email,
-                name: this.persona.name,
-                secret: this.config.secret,
-            }),
-        });
-        if (!res.ok) {
-            const body = (await res.text().catch(() => '')).slice(0, 300);
-            throw new Error(`[scenario] persona sign-in failed for '${this.name}' (${res.status}): ${body}`);
-        }
-        // What proves a session was established is this response setting a cookie,
-        // not the jar being non-empty — the target may have set one earlier.
-        if (res.headers.getSetCookie().length === 0) {
-            throw new Error(`[scenario] persona sign-in for '${this.name}' returned no session cookie`);
-        }
+        await this.signIn.login(this.jar, this.persona);
         this.signedIn = true;
     }
 }

package/dist/services/persona-sign-in.d.ts

@@ -0,0 +1,105 @@
+import type { ResolvedPersona } from './personas-service.js';
+import type { ScenarioCookieJar } from '../wirings/workflow/scenario-cookie-jar.js';
+/**
+ * The header `resolveImpersonatedSession` reads the target user id from.
+ *
+ * A wire value rather than a shared import: the reader lives in
+ * `@pikku/services-better-auth`, which depends on core, so core cannot import
+ * it back. The two agree by protocol, the way an HTTP header always does.
+ */
+export declare const IMPERSONATE_USER_ID_HEADER = "x-pikku-impersonate-user-id";
+/**
+ * How a persona obtains a session on the target, and what every later request
+ * needs to carry to keep acting as them.
+ *
+ * Two answers exist because the two environments have opposite trust models,
+ * not because one is a fallback for the other. See {@link ActorSignIn} and
+ * {@link OperatorSignIn}.
+ */
+export interface PersonaSignIn {
+    /**
+     * Establish a session in `jar`. Throws on failure with a message naming the
+     * persona, since a run that continues unauthenticated fails later and
+     * somewhere less informative.
+     */
+    login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>;
+    /** Headers every request after `login` must carry. */
+    headers(): Record<string, string>;
+}
+/**
+ * Sign a persona in through the Better Auth actor plugin — the local-development
+ * path.
+ *
+ * `POST /auth/sign-in/actor` upserts an `actor: true` row and mints a session
+ * for it. Passwordless by design and refused for any row not carrying that flag,
+ * so the secret can never reach a real user's account; the plugin still declines
+ * to serve the endpoint at all outside `pikku dev`.
+ */
+export declare class ActorSignIn implements PersonaSignIn {
+    private readonly apiUrl;
+    private readonly secret;
+    private readonly signInPath;
+    constructor(apiUrl: string, secret: string, signInPath: string);
+    login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>;
+    headers(): Record<string, string>;
+}
+export interface OperatorSignInOptions {
+    /**
+     * The short-lived RS256 operator token, or a function that mints one. Prefer
+     * the function: tokens expire, and a long run re-logs-in after a 401.
+     */
+    token: string | (() => string | Promise<string>);
+    /**
+     * Create the persona's user row when the target has no account for that
+     * address.
+     *
+     * Off by default, which is the whole point of the deployed path: a persona is
+     * meant to be a real account somebody provisioned, and a test run that
+     * silently writes users into a live database is a side effect nobody asked
+     * for. Turn it on for throwaway stages.
+     */
+    createMissing?: boolean;
+    /** Fabric operator sign-in path under apiUrl. Default `/auth/sign-in/fabric`. */
+    signInPath?: string;
+}
+/** What an operator handshake yields: the session, and who to act as. */
+export interface OperatorSessionResult {
+    /** `Set-Cookie` values the operator sign-in returned. */
+    setCookies: string[];
+    /** The target's own id for the persona, for the impersonation header. */
+    userId: string;
+}
+/**
+ * Establish a Fabric operator session against `apiUrl` and resolve the target's
+ * own id for `persona`, which is what the impersonation header names.
+ *
+ * Takes the fetch to use rather than making one, because the two callers need
+ * the cookies to land in different places: an HTTP persona keeps them in its
+ * jar, a browser run plants them on a Playwright context. Both need the same
+ * handshake, and it is the kind of sequence that quietly diverges once it is
+ * written twice.
+ */
+export declare const establishOperatorSession: (fetchImpl: typeof fetch, apiUrl: string, persona: ResolvedPersona, options: OperatorSignInOptions, extraHeaders?: Record<string, string>) => Promise<OperatorSessionResult>;
+/**
+ * Sign a persona in on a DEPLOYED stage, by having a Fabric operator act as
+ * them — the path that needs no test credential to exist anywhere.
+ *
+ * `POST /auth/sign-in/fabric` verifies an RS256 token against the stage's
+ * `FABRIC_AUTH_PUBLIC_KEY` and mints a session for a synthetic operator row
+ * granted the umbrella `admin` scope. Impersonation is then a header on each
+ * request rather than a second session, and its gate is that scope — not
+ * `user.role`, which is why this works without touching the app's roles.
+ *
+ * Asymmetric throughout: the stage can verify an operator token and never mint
+ * one, so nothing in a deployed environment is worth stealing. That is the
+ * property the actor secret cannot have, and the reason these are two classes
+ * instead of one with a flag.
+ */
+export declare class OperatorSignIn implements PersonaSignIn {
+    private readonly apiUrl;
+    private readonly options;
+    private userId;
+    constructor(apiUrl: string, options: OperatorSignInOptions);
+    login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>;
+    headers(): Record<string, string>;
+}

package/dist/services/persona-sign-in.js

@@ -0,0 +1,128 @@
+/**
+ * The header `resolveImpersonatedSession` reads the target user id from.
+ *
+ * A wire value rather than a shared import: the reader lives in
+ * `@pikku/services-better-auth`, which depends on core, so core cannot import
+ * it back. The two agree by protocol, the way an HTTP header always does.
+ */
+export const IMPERSONATE_USER_ID_HEADER = 'x-pikku-impersonate-user-id';
+const failed = async (what, personaId, res) => {
+    const body = (await res.text().catch(() => '')).slice(0, 300);
+    return new Error(`[scenario] ${what} failed for '${personaId}' (${res.status}): ${body}`);
+};
+/**
+ * Sign a persona in through the Better Auth actor plugin — the local-development
+ * path.
+ *
+ * `POST /auth/sign-in/actor` upserts an `actor: true` row and mints a session
+ * for it. Passwordless by design and refused for any row not carrying that flag,
+ * so the secret can never reach a real user's account; the plugin still declines
+ * to serve the endpoint at all outside `pikku dev`.
+ */
+export class ActorSignIn {
+    apiUrl;
+    secret;
+    signInPath;
+    constructor(apiUrl, secret, signInPath) {
+        this.apiUrl = apiUrl;
+        this.secret = secret;
+        this.signInPath = signInPath;
+    }
+    async login(jar, persona) {
+        const res = await jar.fetch(`${this.apiUrl}${this.signInPath}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                email: persona.email,
+                name: persona.name,
+                secret: this.secret,
+            }),
+        });
+        if (!res.ok) {
+            throw await failed('persona sign-in', persona.id, res);
+        }
+        // What proves a session was established is this response setting a cookie,
+        // not the jar being non-empty — the target may have set one earlier.
+        if (res.headers.getSetCookie().length === 0) {
+            throw new Error(`[scenario] persona sign-in for '${persona.id}' returned no session cookie`);
+        }
+    }
+    headers() {
+        return {};
+    }
+}
+/**
+ * Establish a Fabric operator session against `apiUrl` and resolve the target's
+ * own id for `persona`, which is what the impersonation header names.
+ *
+ * Takes the fetch to use rather than making one, because the two callers need
+ * the cookies to land in different places: an HTTP persona keeps them in its
+ * jar, a browser run plants them on a Playwright context. Both need the same
+ * handshake, and it is the kind of sequence that quietly diverges once it is
+ * written twice.
+ */
+export const establishOperatorSession = async (fetchImpl, apiUrl, persona, options, extraHeaders = {}) => {
+    const signInPath = options.signInPath ?? '/auth/sign-in/fabric';
+    const token = typeof options.token === 'function' ? await options.token() : options.token;
+    const res = await fetchImpl(`${apiUrl}${signInPath}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...extraHeaders },
+        body: JSON.stringify({
+            token,
+            actAs: {
+                email: persona.email,
+                name: persona.name,
+                create: options.createMissing ?? false,
+                ...(persona.roles[0] ? { role: persona.roles[0] } : {}),
+            },
+        }),
+    });
+    if (!res.ok) {
+        throw await failed('operator sign-in', persona.id, res);
+    }
+    const setCookies = res.headers.getSetCookie?.() ?? [];
+    if (setCookies.length === 0) {
+        throw new Error(`[scenario] operator sign-in for '${persona.id}' returned no session cookie`);
+    }
+    const body = (await res.json().catch(() => null));
+    const userId = body?.actAs?.userId;
+    if (!userId) {
+        throw new Error(`[scenario] operator sign-in for '${persona.id}' returned no user to act as — ` +
+            'the target is running a @pikku/better-auth too old to resolve one');
+    }
+    return { setCookies, userId: String(userId) };
+};
+/**
+ * Sign a persona in on a DEPLOYED stage, by having a Fabric operator act as
+ * them — the path that needs no test credential to exist anywhere.
+ *
+ * `POST /auth/sign-in/fabric` verifies an RS256 token against the stage's
+ * `FABRIC_AUTH_PUBLIC_KEY` and mints a session for a synthetic operator row
+ * granted the umbrella `admin` scope. Impersonation is then a header on each
+ * request rather than a second session, and its gate is that scope — not
+ * `user.role`, which is why this works without touching the app's roles.
+ *
+ * Asymmetric throughout: the stage can verify an operator token and never mint
+ * one, so nothing in a deployed environment is worth stealing. That is the
+ * property the actor secret cannot have, and the reason these are two classes
+ * instead of one with a flag.
+ */
+export class OperatorSignIn {
+    apiUrl;
+    options;
+    userId = null;
+    constructor(apiUrl, options) {
+        this.apiUrl = apiUrl;
+        this.options = options;
+    }
+    async login(jar, persona) {
+        const { userId } = await establishOperatorSession(jar.fetch, this.apiUrl, persona, this.options);
+        this.userId = userId;
+    }
+    headers() {
+        if (!this.userId) {
+            throw new Error('[scenario] operator session has no persona to act as — login() first');
+        }
+        return { [IMPERSONATE_USER_ID_HEADER]: this.userId };
+    }
+}

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

@@ -17,4 +17,5 @@ export type { CorePersona, CorePersonas, PersonaAccountMeta, PersonaDefinitions,
  * Lambda deploy would load outright.
  */
 export { HttpPersona, createHttpPersonas, type HttpPersonasConfig, } from '../../services/http-personas.js';
+export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, type PersonaSignIn, type OperatorSignInOptions, type OperatorSessionResult, } from '../../services/persona-sign-in.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';

package/dist/wirings/persona/index.js

@@ -13,4 +13,5 @@ export { personaEmail, personaEmails } from './persona-email.js';
  * Lambda deploy would load outright.
  */
 export { HttpPersona, createHttpPersonas, } from '../../services/http-personas.js';
+export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, } from '../../services/persona-sign-in.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';

package/dist/wirings/workflow/scenario-cookie-jar.js

@@ -5,8 +5,17 @@ export const createCookieJar = (apiUrl) => {
         fetch: async (input, init) => {
             const headers = new Headers(init?.headers);
             headers.set('origin', origin);
-            const held = [...jar].map(([name, value]) => `${name}=${value}`);
+            // The caller's own cookie header wins per name: a request that already
+            // carries a session is stating which one it means, and emitting the jar's
+            // copy alongside it sends the same name twice.
             const caller = headers.get('cookie');
+            const named = new Set((caller ?? '')
+                .split(';')
+                .map((pair) => pair.split('=')[0]?.trim())
+                .filter(Boolean));
+            const held = [...jar]
+                .filter(([name]) => !named.has(name))
+                .map(([name, value]) => `${name}=${value}`);
             if (held.length > 0 || caller) {
                 headers.set('cookie', [caller, ...held].filter(Boolean).join('; '));
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.90",
+  "version": "0.12.92",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/public-surface.json

@@ -272,9 +272,13 @@
     "validateAndBuildSystemRoleDefinitionsMeta"
   ],
   "./persona": [
+    "ActorSignIn",
     "HttpPersona",
+    "IMPERSONATE_USER_ID_HEADER",
+    "OperatorSignIn",
     "createHttpPersonas",
     "definePersonas",
+    "establishOperatorSession",
     "isRunnablePersona",
     "personaEmail",
     "personaEmails",

package/src/services/http-personas.ts

@@ -16,6 +16,12 @@ import {
   createCookieJar,
   type ScenarioCookieJar,
 } from '../wirings/workflow/scenario-cookie-jar.js'
+import {
+  ActorSignIn,
+  OperatorSignIn,
+  type OperatorSignInOptions,
+  type PersonaSignIn,
+} from './persona-sign-in.js'
 import { getSingletonServices } from '../pikku-state.js'
 import { AIProviderNotConfiguredError } from '../errors/errors.js'
 
@@ -30,8 +36,19 @@ export interface HttpPersonasConfig {
   /**
    * The impersonation secret. Sign-in only ever works for user rows flagged
    * `actor: true` — knowing the secret never impersonates real users.
+   *
+   * The local-development credential. A deployed stage has none, and passes
+   * {@link HttpPersonasConfig.operator} instead.
+   */
+  secret?: string
+  /**
+   * Fabric operator credentials, for signing personas into a DEPLOYED stage.
+   *
+   * Mutually exclusive with {@link HttpPersonasConfig.secret}: the operator
+   * path acts as the persona through an admin session rather than logging in as
+   * them, so no test credential has to exist on the target at all.
    */
-  secret: string
+  operator?: OperatorSignInOptions
   /** Persona id → the declaration with its address filled in. */
   personas: Record<string, ResolvedPersona>
   /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
@@ -49,12 +66,13 @@ export interface HttpPersonasConfig {
 }
 
 /**
- * Default HTTP-backed persona. Signs in lazily on first invoke via the Better
- * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
- * the plugin upserts the actor-flagged user row and mints a session whose
- * `actor` flag flows into audits/analytics). Holds the session cookies for
- * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
- * outlive a session).
+ * Default HTTP-backed persona. Signs in lazily on first invoke, holds the
+ * session cookies for its lifetime, and re-logs-in once on a 401 mid-run (long
+ * health-check runs can outlive a session).
+ *
+ * How it signs in depends on the target, and the two ways are not
+ * interchangeable — see {@link ActorSignIn} for local development and
+ * {@link OperatorSignIn} for a deployed stage.
  */
 export class HttpPersona implements ScenarioPersona {
   private jar: ScenarioCookieJar
@@ -65,6 +83,7 @@ export class HttpPersona implements ScenarioPersona {
    * established.
    */
   private signedIn = false
+  private signIn: PersonaSignIn
 
   constructor(
     readonly name: string,
@@ -72,6 +91,19 @@ export class HttpPersona implements ScenarioPersona {
     private config: HttpPersonasConfig
   ) {
     this.jar = createCookieJar(config.apiUrl)
+    if (config.operator) {
+      this.signIn = new OperatorSignIn(config.apiUrl, config.operator)
+    } else if (config.secret) {
+      this.signIn = new ActorSignIn(
+        config.apiUrl,
+        config.secret,
+        config.signInPath ?? '/auth/sign-in/actor'
+      )
+    } else {
+      throw new Error(
+        `[scenario] persona '${name}' has no way to sign in — set 'secret' for a dev target or 'operator' for a deployed one`
+      )
+    }
   }
 
   get email(): string {
@@ -161,7 +193,9 @@ export class HttpPersona implements ScenarioPersona {
       await this.login()
     }
     const sessionPath = this.config.sessionPath ?? '/auth/get-session'
-    const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`)
+    const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`, {
+      headers: this.signIn.headers(),
+    })
     if (!res.ok) {
       return null
     }
@@ -226,7 +260,10 @@ export class HttpPersona implements ScenarioPersona {
     const send = () =>
       this.jar.fetch(url, {
         method: 'POST',
-        headers: { 'content-type': 'application/json' },
+        headers: {
+          'content-type': 'application/json',
+          ...this.signIn.headers(),
+        },
         body: JSON.stringify(body),
       })
 
@@ -255,7 +292,11 @@ export class HttpPersona implements ScenarioPersona {
     const rpcPath = this.config.rpcPath ?? '/rpc'
     return this.jar.fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
       method: 'POST',
-      headers: { 'content-type': 'application/json', ...extraHeaders },
+      headers: {
+        'content-type': 'application/json',
+        ...this.signIn.headers(),
+        ...extraHeaders,
+      },
       body: JSON.stringify({ data }),
     })
   }
@@ -267,29 +308,7 @@ export class HttpPersona implements ScenarioPersona {
   }
 
   private async login(): Promise<void> {
-    const signInPath = this.config.signInPath ?? '/auth/sign-in/actor'
-    const res = await this.jar.fetch(`${this.config.apiUrl}${signInPath}`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        email: this.persona.email,
-        name: this.persona.name,
-        secret: this.config.secret,
-      }),
-    })
-    if (!res.ok) {
-      const body = (await res.text().catch(() => '')).slice(0, 300)
-      throw new Error(
-        `[scenario] persona sign-in failed for '${this.name}' (${res.status}): ${body}`
-      )
-    }
-    // What proves a session was established is this response setting a cookie,
-    // not the jar being non-empty — the target may have set one earlier.
-    if (res.headers.getSetCookie().length === 0) {
-      throw new Error(
-        `[scenario] persona sign-in for '${this.name}' returned no session cookie`
-      )
-    }
+    await this.signIn.login(this.jar, this.persona)
     this.signedIn = true
   }
 }