@pikku/core 0.12.90 → 0.12.91

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## 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,107 @@
+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;
+    /** Admin endpoint prefix under apiUrl. Default `/auth/admin`. */
+    adminPath?: string;
+    /** 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,179 @@
+/**
+ * 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 }),
+    });
+    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`);
+    }
+    // The lookup runs on the session this handshake just established, and a
+    // plain `fetch` keeps no cookies — the browser path in particular hands the
+    // jar's contents to Playwright only after this returns. Forwarding them
+    // explicitly is what keeps the admin calls authenticated for every caller.
+    const session = setCookies
+        .map((raw) => raw.split(';')[0])
+        .filter((pair) => Boolean(pair))
+        .join('; ');
+    const userId = await resolveUserId(fetchImpl, apiUrl, persona, options, {
+        ...extraHeaders,
+        cookie: session,
+    });
+    return { setCookies, userId };
+};
+/**
+ * The target's own id for this persona's address, since impersonation names a
+ * user id and a persona only knows an email.
+ *
+ * Looked up before creating, so a persona that already exists is never
+ * duplicated and the run reads as "act as this person" rather than "make one".
+ */
+const resolveUserId = async (fetchImpl, apiUrl, persona, options, extraHeaders) => {
+    const adminPath = options.adminPath ?? '/auth/admin';
+    const query = new URLSearchParams({
+        filterField: 'email',
+        filterValue: persona.email,
+        filterOperator: 'eq',
+        limit: '1',
+    });
+    const found = await fetchImpl(`${apiUrl}${adminPath}/list-users?${query}`, {
+        headers: { accept: 'application/json', ...extraHeaders },
+    });
+    if (!found.ok) {
+        throw await failed('persona lookup', persona.id, found);
+    }
+    const listed = (await found.json().catch(() => null));
+    const existing = listed?.users?.find((u) => u.email === persona.email);
+    if (existing?.id) {
+        return String(existing.id);
+    }
+    if (!options.createMissing) {
+        throw new Error(`[scenario] no account on the target for persona '${persona.id}' (${persona.email}) — ` +
+            'provision it, or set createMissing on the operator credentials');
+    }
+    const created = await fetchImpl(`${apiUrl}${adminPath}/create-user`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...extraHeaders },
+        body: JSON.stringify({
+            email: persona.email,
+            name: persona.name,
+            // Never used and never returned: the run impersonates rather than signs
+            // in, so the account is reachable only by someone already holding an
+            // operator token. A derivable password would undo exactly that.
+            password: globalThis.crypto.randomUUID(),
+            ...(persona.roles[0] ? { role: persona.roles[0] } : {}),
+        }),
+    });
+    if (!created.ok) {
+        throw await failed('persona creation', persona.id, created);
+    }
+    const body = (await created.json().catch(() => null));
+    const id = body?.user?.id;
+    if (!id) {
+        throw new Error(`[scenario] creating persona '${persona.id}' returned no user id`);
+    }
+    return String(id);
+};
+/**
+ * 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.91",
   "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",