@pikku/core 0.12.90 → 0.12.91

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
   }
 }

package/src/services/persona-sign-in.test.ts

@@ -0,0 +1,209 @@
+import { describe, test, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer, type Server } from 'node:http'
+
+import { createHttpPersonas } from './http-personas.js'
+import { establishOperatorSession } from './persona-sign-in.js'
+
+const OPERATOR_TOKEN = 'operator.jwt.token'
+
+/**
+ * Minimal deployed stage: the fabric plugin's sign-in, the admin plugin's
+ * user endpoints, and an RPC route that reports back who it was addressed as.
+ */
+const startStage = async (seeded: Array<{ id: string; email: string }>) => {
+  const users = [...seeded]
+  let created = 0
+  const server: Server = createServer((req, res) => {
+    const chunks: Buffer[] = []
+    req.on('data', (c) => chunks.push(c))
+    req.on('end', () => {
+      const body = chunks.length
+        ? JSON.parse(Buffer.concat(chunks).toString())
+        : {}
+      const url = new URL(req.url ?? '/', 'http://stage.invalid')
+
+      if (url.pathname === '/api/auth/sign-in/fabric') {
+        if (body.token !== OPERATOR_TOKEN) {
+          res.writeHead(401).end(JSON.stringify({ message: 'bad token' }))
+          return
+        }
+        res.setHeader('set-cookie', ['session=operator; Path=/; HttpOnly'])
+        res.writeHead(200).end(JSON.stringify({ token: 'operator' }))
+        return
+      }
+
+      // The admin plugin refuses an unauthenticated caller, and saying so here
+      // is the point: a handshake that dropped the operator session between
+      // sign-in and lookup would otherwise pass this stage happily.
+      if (url.pathname.startsWith('/api/auth/admin/')) {
+        if (!/(^|;\s*)session=operator(;|$)/.test(req.headers.cookie ?? '')) {
+          res.writeHead(401).end(JSON.stringify({ message: 'no session' }))
+          return
+        }
+      }
+
+      if (url.pathname === '/api/auth/admin/list-users') {
+        const wanted = url.searchParams.get('filterValue')
+        res
+          .writeHead(200, { 'content-type': 'application/json' })
+          .end(
+            JSON.stringify({ users: users.filter((u) => u.email === wanted) })
+          )
+        return
+      }
+
+      if (url.pathname === '/api/auth/admin/create-user') {
+        created++
+        const user = { id: `made-${created}`, email: body.email }
+        users.push(user)
+        res
+          .writeHead(200, { 'content-type': 'application/json' })
+          .end(JSON.stringify({ user, sawPassword: Boolean(body.password) }))
+        return
+      }
+
+      if (url.pathname.startsWith('/api/rpc/')) {
+        res.writeHead(200, { 'content-type': 'application/json' }).end(
+          JSON.stringify({
+            actingAs: req.headers['x-pikku-impersonate-user-id'] ?? null,
+            cookie: req.headers.cookie ?? '',
+          })
+        )
+        return
+      }
+
+      res.writeHead(404).end()
+    })
+  })
+  await new Promise<void>((resolve) => server.listen(0, resolve))
+  const port = (server.address() as { port: number }).port
+  return {
+    apiUrl: `http://127.0.0.1:${port}/api`,
+    server,
+    get createdCount() {
+      return created
+    },
+  }
+}
+
+const persona = (email: string) => ({
+  id: 'customer',
+  name: 'Customer',
+  email,
+  roles: ['client'],
+  goals: [],
+  tags: [],
+  runnable: true,
+})
+
+describe('operator persona sign-in', () => {
+  const servers: Server[] = []
+  after(() => servers.forEach((s) => s.close()))
+
+  test('acts as an existing account rather than signing in as it', async () => {
+    const stage = await startStage([
+      { id: 'user-7', email: 'customer@personas.invalid' },
+    ])
+    servers.push(stage.server)
+
+    const personas = createHttpPersonas({
+      apiUrl: stage.apiUrl,
+      operator: { token: OPERATOR_TOKEN },
+      personas: { customer: persona('customer@personas.invalid') },
+    })
+
+    const result = (await personas.customer!.invoke('whoami', {})) as {
+      actingAs: string | null
+      cookie: string
+    }
+    assert.equal(result.actingAs, 'user-7')
+    assert.match(result.cookie, /session=operator/)
+    assert.equal(stage.createdCount, 0)
+  })
+
+  test('refuses a persona the stage has no account for', async () => {
+    const stage = await startStage([])
+    servers.push(stage.server)
+
+    const personas = createHttpPersonas({
+      apiUrl: stage.apiUrl,
+      operator: { token: OPERATOR_TOKEN },
+      personas: { customer: persona('ghost@personas.invalid') },
+    })
+
+    await assert.rejects(
+      () => personas.customer!.invoke('whoami', {}),
+      /no account on the target for persona 'customer'/
+    )
+    assert.equal(stage.createdCount, 0)
+  })
+
+  test('provisions the account only when told to', async () => {
+    const stage = await startStage([])
+    servers.push(stage.server)
+
+    const personas = createHttpPersonas({
+      apiUrl: stage.apiUrl,
+      operator: { token: OPERATOR_TOKEN, createMissing: true },
+      personas: { customer: persona('fresh@personas.invalid') },
+    })
+
+    const result = (await personas.customer!.invoke('whoami', {})) as {
+      actingAs: string | null
+    }
+    assert.equal(result.actingAs, 'made-1')
+    assert.equal(stage.createdCount, 1)
+  })
+
+  test('mints the operator session from a token factory', async () => {
+    const stage = await startStage([
+      { id: 'user-9', email: 'lazy@personas.invalid' },
+    ])
+    servers.push(stage.server)
+
+    let minted = 0
+    const personas = createHttpPersonas({
+      apiUrl: stage.apiUrl,
+      operator: {
+        token: () => {
+          minted++
+          return OPERATOR_TOKEN
+        },
+      },
+      personas: { customer: persona('lazy@personas.invalid') },
+    })
+
+    await personas.customer!.invoke('whoami', {})
+    assert.equal(minted, 1)
+  })
+
+  test('carries the operator session into the admin lookup', async () => {
+    const stage = await startStage([{ id: 'user-9', email: 'susan@acme.test' }])
+    servers.push(stage.server)
+
+    // Plain fetch keeps no cookies, which is the browser provider's situation:
+    // it plants them on a Playwright context only once this has returned.
+    const { userId } = await establishOperatorSession(
+      fetch,
+      stage.apiUrl,
+      persona('susan@acme.test'),
+      { token: OPERATOR_TOKEN }
+    )
+    assert.equal(userId, 'user-9')
+  })
+
+  test('a persona with neither credential is refused at construction', async () => {
+    const stage = await startStage([])
+    servers.push(stage.server)
+
+    assert.throws(
+      () =>
+        createHttpPersonas({
+          apiUrl: stage.apiUrl,
+          personas: { customer: persona('nobody@personas.invalid') },
+        }),
+      /has no way to sign in/
+    )
+  })
+})

package/src/services/persona-sign-in.ts

@@ -0,0 +1,284 @@
+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 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>
+}
+
+const failed = async (
+  what: string,
+  personaId: string,
+  res: Response
+): Promise<Error> => {
+  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 implements PersonaSignIn {
+  constructor(
+    private readonly apiUrl: string,
+    private readonly secret: string,
+    private readonly signInPath: string
+  ) {}
+
+  async login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void> {
+    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(): Record<string, string> {
+    return {}
+  }
+}
+
+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
+}
+
+interface AdminUser {
+  id?: unknown
+  email?: unknown
+}
+
+/** 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 const establishOperatorSession = async (
+  fetchImpl: typeof fetch,
+  apiUrl: string,
+  persona: ResolvedPersona,
+  options: OperatorSignInOptions,
+  extraHeaders: Record<string, string> = {}
+): Promise<OperatorSessionResult> => {
+  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): pair is string => 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: typeof fetch,
+  apiUrl: string,
+  persona: ResolvedPersona,
+  options: OperatorSignInOptions,
+  extraHeaders: Record<string, string>
+): Promise<string> => {
+  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)) as {
+    users?: AdminUser[]
+  } | 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)) as {
+    user?: AdminUser
+  } | 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 implements PersonaSignIn {
+  private userId: string | null = null
+
+  constructor(
+    private readonly apiUrl: string,
+    private readonly options: OperatorSignInOptions
+  ) {}
+
+  async login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void> {
+    const { userId } = await establishOperatorSession(
+      jar.fetch,
+      this.apiUrl,
+      persona,
+      this.options
+    )
+    this.userId = userId
+  }
+
+  headers(): Record<string, string> {
+    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/src/wirings/persona/index.ts

@@ -45,6 +45,15 @@ export {
   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,

package/src/wirings/workflow/scenario-cookie-jar.ts

@@ -11,8 +11,19 @@ export const createCookieJar = (apiUrl: string): ScenarioCookieJar => {
     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('; '))
       }