@pikku/core 0.12.107 → 0.12.111

package/src/services/persona-actor-secret.test.ts

@@ -1,68 +0,0 @@
-import assert from 'node:assert/strict'
-import { describe, test } from 'node:test'
-
-import {
-  ACTOR_ROOT_SECRET_MIN_LENGTH,
-  deriveActorSecret,
-  verifyActorSecret,
-} from './persona-actor-secret.js'
-
-const ROOT = 'root-secret-root-secret-root-secret'
-const OTHER_ROOT = 'other-secret-other-secret-other-sec'
-
-describe('actor credentials', () => {
-  test('a credential verifies for its own address', async () => {
-    const secret = await deriveActorSecret(ROOT, 'susan@actors.local')
-    assert.equal(
-      await verifyActorSecret(ROOT, 'susan@actors.local', secret),
-      true
-    )
-  })
-
-  test('and for no other address', async () => {
-    const secret = await deriveActorSecret(ROOT, 'susan@actors.local')
-    assert.equal(
-      await verifyActorSecret(ROOT, 'yasser@actors.local', secret),
-      false
-    )
-  })
-
-  test('the address is matched the way the row is looked up', async () => {
-    const secret = await deriveActorSecret(ROOT, ' Susan@Actors.Local ')
-    assert.equal(
-      await verifyActorSecret(ROOT, 'susan@actors.local', secret),
-      true
-    )
-  })
-
-  test('rotating the root invalidates every credential at once', async () => {
-    const secret = await deriveActorSecret(ROOT, 'susan@actors.local')
-    assert.equal(
-      await verifyActorSecret(OTHER_ROOT, 'susan@actors.local', secret),
-      false
-    )
-  })
-
-  test('the root is not a credential for anybody', async () => {
-    assert.equal(
-      await verifyActorSecret(ROOT, 'susan@actors.local', ROOT),
-      false
-    )
-  })
-
-  test('a malformed value is false rather than a throw', async () => {
-    assert.equal(await verifyActorSecret(ROOT, 'susan@actors.local', ''), false)
-    assert.equal(
-      await verifyActorSecret(ROOT, 'susan@actors.local', 'not base64url!!'),
-      false
-    )
-  })
-
-  test('key material shorter than the minimum is refused, not silently used', async () => {
-    await assert.rejects(
-      () => deriveActorSecret('short', 'susan@actors.local'),
-      /SCENARIO_ACTOR_SECRET/
-    )
-    assert.ok(ACTOR_ROOT_SECRET_MIN_LENGTH >= 32)
-  })
-})

package/src/services/persona-actor-secret.ts

@@ -1,70 +0,0 @@
-import {
-  MIN_KEY_MATERIAL_LENGTH,
-  signWithKeyMaterial,
-  verifyWithKeyMaterial,
-} from '../crypto-utils.js'
-
-/** The name the root secret is held under, used only in error messages. */
-export const ACTOR_SECRET_NAME = 'SCENARIO_ACTOR_SECRET'
-
-/**
- * Namespaces the derivation so the same root secret used for anything else
- * produces different values. See knowledge/crypto.md.
- */
-export const ACTOR_SECRET_INFO = 'pikku:actor-sign-in'
-
-/** The root must be strong: every persona's credential is derived from it. */
-export const ACTOR_ROOT_SECRET_MIN_LENGTH = MIN_KEY_MATERIAL_LENGTH
-
-/**
- * What the derivation is bound to. Lowercased because the sign-in endpoint
- * looks the user up by lowercased address, and a credential that verified
- * against a different string than the row it opens is a credential for nothing.
- */
-export const actorSecretSubject = (email: string): string =>
-  email.trim().toLowerCase()
-
-/**
- * One persona's actor credential: `HMAC-SHA256(root, email)`, base64url.
- *
- * The root secret is not itself a valid credential and never travels: what a
- * scenario run, a CI job or a virtual user is handed is the derived value for
- * the one address it is entitled to. Presenting it for any other address fails,
- * so a leaked credential is worth exactly one synthetic account rather than the
- * whole actor population.
- *
- * Deterministic, so nothing is stored and nothing is provisioned — the target
- * re-derives the expected value from the address being signed in as. Rotating
- * the root invalidates every derived credential at once, which is the property
- * a per-persona secret table would have to implement by hand.
- */
-export const deriveActorSecret = async (
-  rootSecret: string,
-  email: string
-): Promise<string> =>
-  signWithKeyMaterial(
-    ACTOR_SECRET_NAME,
-    rootSecret,
-    ACTOR_SECRET_INFO,
-    actorSecretSubject(email)
-  )
-
-/**
- * Whether `presented` is the credential for `email` under `rootSecret`.
- *
- * False — never throws — for a malformed, truncated or mismatched value, and
- * the comparison is WebCrypto's own HMAC verify, so it does not exit early on
- * the first differing byte.
- */
-export const verifyActorSecret = async (
-  rootSecret: string,
-  email: string,
-  presented: string
-): Promise<boolean> =>
-  verifyWithKeyMaterial(
-    ACTOR_SECRET_NAME,
-    rootSecret,
-    ACTOR_SECRET_INFO,
-    actorSecretSubject(email),
-    presented
-  )

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

@@ -1,219 +0,0 @@
-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]
-  const sentBodies: unknown[] = []
-  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) {
-          sentBodies.push(body.actAs)
-          const user = users.find((u) => u.email === body.actAs.email)
-          if (!user) {
-            res.writeHead(404).end(
-              JSON.stringify({
-                message: `No account on this stage for ${body.actAs.email}`,
-              })
-            )
-            return
-          }
-          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 sentBodies() {
-      return sentBodies
-    },
-  }
-}
-
-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/)
-  })
-
-  // An app that mounts auth somewhere other than the root moves both sign-in
-  // paths together, and `SCENARIO_SIGN_IN_PATH` is the only place it can say so.
-  test('honours a moved sign-in path the same way the actor path does', async () => {
-    const stage = await startStage([
-      { id: 'user-7', email: 'customer@personas.invalid' },
-    ])
-    servers.push(stage.server)
-
-    const personas = createHttpPersonas({
-      apiUrl: stage.apiUrl.replace(/\/api$/, ''),
-      operator: { token: OPERATOR_TOKEN },
-      signInPath: '/api/auth/sign-in/fabric',
-      rpcPath: '/api/rpc',
-      personas: { customer: persona('customer@personas.invalid') },
-    })
-
-    const result = (await personas.customer!.invoke('whoami', {})) as {
-      actingAs: string | null
-    }
-    assert.equal(result.actingAs, 'user-7')
-  })
-
-  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\)/
-    )
-  })
-
-  // Provisioning moved into the stage, so the handshake carries an address and
-  // nothing else. A `create` flag or a role list here would be the caller
-  // deciding what the stage holds, which is the arrangement this replaced.
-  test('asks only to act as an address', async () => {
-    const stage = await startStage([
-      { id: 'user-3', email: 'customer@personas.invalid' },
-    ])
-    servers.push(stage.server)
-
-    const personas = createHttpPersonas({
-      apiUrl: stage.apiUrl,
-      operator: { token: OPERATOR_TOKEN },
-      personas: { customer: persona('customer@personas.invalid') },
-    })
-
-    await personas.customer!.invoke('whoami', {})
-    assert.deepEqual(stage.sentBodies, [{ email: 'customer@personas.invalid' }])
-  })
-
-  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

@@ -1,238 +0,0 @@
-import { deriveActorSecret } from './persona-actor-secret.js'
-import { PikkuError } from '../errors/error-handler.js'
-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>
-}
-
-/**
- * A sign-in the target refused. `PikkuError`, not `Error`, so the CLI prints
- * this message alone: an expired token or a persona the stage has never seen is
- * something to go and fix, and a stack trace through the fetch internals only
- * buries the status and the body that say which one it is.
- */
-const failed = async (
-  what: string,
-  personaId: string,
-  res: Response
-): Promise<Error> => {
-  const body = (await res.text().catch(() => '')).slice(0, 300)
-  return new PikkuError(
-    `[scenario] ${what} failed for '${personaId}' (${res.status}): ${body}`
-  )
-}
-
-/**
- * Yields the credential for one persona, for a caller that holds that persona's
- * derived secret and not the root it came from.
- */
-export type ActorSecretResolver = (
-  persona: ResolvedPersona
-) => string | Promise<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`.
- *
- * What is presented is the persona's own credential, derived from the root and
- * bound to their address. A run driving many personas holds the root and
- * derives as it goes; a run entitled to one persona is handed that one value
- * through a resolver and can sign in as nobody else.
- */
-export class ActorSignIn implements PersonaSignIn {
-  constructor(
-    private readonly apiUrl: string,
-    private readonly secret: string | ActorSecretResolver,
-    private readonly signInPath: string
-  ) {}
-
-  async login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void> {
-    const secret =
-      typeof this.secret === 'function'
-        ? await this.secret(persona)
-        : await deriveActorSecret(this.secret, persona.email)
-    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,
-      }),
-    })
-    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 {}
-  }
-}
-
-/**
- * The auth mount a configured sign-in path sits under, or `undefined` when it
- * names nothing recognisable.
- *
- * better-auth serves sign-in, operator sign-in and `get-session` from one
- * prefix, so an app that mounts it at `/api/auth` moves all three together and
- * says so once through `signInPath`. Reading the other two from a hardcoded
- * `/auth` on such an app 404s — and for `get-session` a 404 reads as "this
- * stage does not report roles", which silently turns off the check that tells a
- * permissions finding from seed drift.
- */
-export const authMount = (signInPath?: string): string | undefined => {
-  const mount = signInPath ? signInPath.lastIndexOf('/sign-in/') : -1
-  return !signInPath || mount === -1 ? undefined : signInPath.slice(0, mount)
-}
-
-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>)
-  /** 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 },
-    }),
-  })
-  if (!res.ok) {
-    throw await failed('operator sign-in', persona.id, res)
-  }
-  const setCookies = res.headers.getSetCookie?.() ?? []
-  if (setCookies.length === 0) {
-    throw new PikkuError(
-      `[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 PikkuError(
-      `[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 }
-  }
-}