@pikku/core 0.12.90 → 0.12.92

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

@@ -0,0 +1,203 @@
+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, which resolves the
+ * account to act as in the same request, 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
+        }
+        let actAs: { userId: string } | undefined
+        if (body.actAs) {
+          let user = users.find((u) => u.email === body.actAs.email)
+          if (!user) {
+            if (!body.actAs.create) {
+              res
+                .writeHead(404)
+                .end(
+                  JSON.stringify({
+                    message: `No account on this stage for ${body.actAs.email}`,
+                  })
+                )
+              return
+            }
+            created++
+            user = { id: `made-${created}`, email: body.actAs.email }
+            users.push(user)
+          }
+          actAs = { userId: user.id }
+        }
+        res.setHeader('set-cookie', ['session=operator; Path=/; HttpOnly'])
+        res
+          .writeHead(200, { 'content-type': 'application/json' })
+          .end(JSON.stringify({ token: 'operator', actAs }))
+        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', {}),
+      /operator sign-in failed for 'customer' \(404\)/
+    )
+    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('resolves the account to act as without a second request', 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. The
+    // handshake must not need a session of its own to resolve the persona.
+    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,212 @@
+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
+  /** 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 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,
+      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)) as {
+    actAs?: { userId?: unknown }
+  } | 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 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('; '))
       }