@pikku/core 0.12.98 → 0.12.99

package/src/public-surface.json

@@ -289,15 +289,20 @@
     "validateAndBuildSystemRoleDefinitionsMeta"
   ],
   "./persona": [
+    "ACTOR_ROOT_SECRET_MIN_LENGTH",
+    "ACTOR_SECRET_INFO",
+    "ACTOR_SECRET_NAME",
     "APP_SCOPE_ROOT",
     "ActorSignIn",
     "HttpPersona",
     "IMPERSONATE_USER_ID_HEADER",
     "OperatorSignIn",
+    "actorSecretSubject",
     "appScopeId",
     "buildAppScopeDefinition",
     "createHttpPersonas",
     "definePersonas",
+    "deriveActorSecret",
     "establishOperatorSession",
     "isRunnablePersona",
     "personaEmail",
@@ -309,6 +314,7 @@
     "roleMismatchMessage",
     "runnablePersonas",
     "validateAndBuildPersonasMeta",
+    "verifyActorSecret",
     "verifyPersonaRoles"
   ],
   "./secret": ["defineSecret", "validateAndBuildSecretDefinitionsMeta"],
@@ -364,6 +370,9 @@
     "isExpectedError"
   ],
   "./services": [
+    "ACTOR_ROOT_SECRET_MIN_LENGTH",
+    "ACTOR_SECRET_INFO",
+    "ACTOR_SECRET_NAME",
     "ConsoleLogger",
     "DEFAULT_WEBHOOK_RETRIES",
     "FileScenarioRunStore",
@@ -394,10 +403,12 @@
     "TypedSecretService",
     "TypedVariablesService",
     "WebhookService",
+    "actorSecretSubject",
     "assertSecretAllowedForHost",
     "createInvocationAudit",
     "createMiddlewareSessionWireProps",
     "createStubProxy",
+    "deriveActorSecret",
     "getStubTracker",
     "isTestRun",
     "pikkuWebhookWorkerFunc",
@@ -406,6 +417,7 @@
     "scenarioRunSummary",
     "spy",
     "stub",
+    "verifyActorSecret",
     "withoutSecrets"
   ],
   "./services/local-meta": ["LocalMetaService"],

package/src/services/http-personas-converse.test.ts

@@ -161,7 +161,7 @@ describe('HttpPersona.converse', async () => {
 
     const actors = createHttpPersonas({
       apiUrl: target.apiUrl,
-      secret: 'impersonation-secret',
+      secret: 'impersonation-secret-impersonation',
       model: 'test/test-model',
       personas: {
         pm: {
@@ -204,7 +204,7 @@ describe('HttpPersona.converse', async () => {
 
     const actors = createHttpPersonas({
       apiUrl: target.apiUrl,
-      secret: 'impersonation-secret',
+      secret: 'impersonation-secret-impersonation',
       model: 'test/test-model',
       personas: {
         pm: {
@@ -243,7 +243,7 @@ describe('HttpPersona.converse', async () => {
 
     const actors = createHttpPersonas({
       apiUrl: target.apiUrl,
-      secret: 'impersonation-secret',
+      secret: 'impersonation-secret-impersonation',
       model: 'test/test-model',
       personas: {
         pm: {

package/src/services/http-personas.test.ts

@@ -3,6 +3,10 @@ import assert from 'node:assert/strict'
 import { createServer, type Server } from 'node:http'
 
 import { createHttpPersonas } from './http-personas.js'
+import { verifyActorSecret } from './persona-actor-secret.js'
+
+/** The root the personas derive from; the target verifies against the same one. */
+const ROOT = 'impersonation-secret-impersonation'
 
 // Minimal target app mirroring the Better Auth actor plugin's contract:
 // sign-in endpoint, exposed RPC endpoint, session by cookie.
@@ -12,12 +16,12 @@ const startTarget = async () => {
   const server: Server = createServer((req, res) => {
     const chunks: Buffer[] = []
     req.on('data', (c) => chunks.push(c))
-    req.on('end', () => {
+    req.on('end', async () => {
       const body = chunks.length
         ? JSON.parse(Buffer.concat(chunks).toString())
         : {}
       if (req.url === '/api/auth/sign-in/actor') {
-        if (body.secret !== 'impersonation-secret') {
+        if (!(await verifyActorSecret(ROOT, body.email, body.secret))) {
           res
             .writeHead(401)
             .end(JSON.stringify({ message: 'bad actor secret' }))
@@ -82,7 +86,9 @@ describe('HttpPersona', async () => {
   const target = await startTarget()
   after(() => target.server.close())
 
-  const makePersonas = (secret = 'impersonation-secret') =>
+  const makePersonas = (
+    secret: Parameters<typeof createHttpPersonas>[0]['secret'] = ROOT
+  ) =>
     createHttpPersonas({
       apiUrl: target.apiUrl,
       secret,
@@ -216,8 +222,10 @@ describe('HttpPersona', async () => {
     )
   })
 
-  test('a wrong impersonation secret surfaces status and body', async () => {
-    const actors = makePersonas('wrong-secret')
+  // A caller holding one persona's credential and asking for another gets the
+  // target's refusal, not a client-side guess about whether it would have worked.
+  test('a credential the target will not accept surfaces status and body', async () => {
+    const actors = makePersonas(() => 'not-this-personas-credential')
     await assert.rejects(
       actors.customer!.invoke('ping', {}),
       /persona sign-in failed for 'customer' \(401\).*bad actor secret/

package/src/services/http-personas.ts

@@ -18,6 +18,7 @@ import {
 } from '../wirings/workflow/scenario-cookie-jar.js'
 import {
   ActorSignIn,
+  type ActorSecretResolver,
   OperatorSignIn,
   type OperatorSignInOptions,
   type PersonaSignIn,
@@ -34,13 +35,19 @@ export interface HttpPersonasConfig {
    */
   apiUrl: string
   /**
-   * The impersonation secret. Sign-in only ever works for user rows flagged
-   * `actor: true` — knowing the secret never impersonates real users.
+   * The ROOT actor secret, from which each persona's own credential is derived
+   * and bound to their address. Sign-in only ever works for user rows flagged
+   * `actor: true`, and a derived credential only ever works for the one address
+   * it was derived for.
+   *
+   * Pass an {@link ActorSecretResolver} instead to drive personas whose
+   * credentials were minted elsewhere — a caller entitled to one persona then
+   * never holds the root.
    *
    * The local-development credential. A deployed stage has none, and passes
    * {@link HttpPersonasConfig.operator} instead.
    */
-  secret?: string
+  secret?: string | ActorSecretResolver
   /**
    * Fabric operator credentials, for signing personas into a DEPLOYED stage.
    *

package/src/services/index.ts

@@ -73,6 +73,14 @@ export {
   type WebhookJobData,
   type WebhookServiceConfig,
 } from './webhook-service.js'
+export {
+  ACTOR_ROOT_SECRET_MIN_LENGTH,
+  ACTOR_SECRET_INFO,
+  ACTOR_SECRET_NAME,
+  actorSecretSubject,
+  deriveActorSecret,
+  verifyActorSecret,
+} from './persona-actor-secret.js'
 export type { Logger } from './logger.js'
 export type { SecretService, SecretValues } from './secret-service.js'
 export type { VariablesService } from './variables-service.js'

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

@@ -0,0 +1,68 @@
+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

@@ -0,0 +1,70 @@
+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.ts

@@ -1,3 +1,4 @@
+import { deriveActorSecret } from './persona-actor-secret.js'
 import type { ResolvedPersona } from './personas-service.js'
 import type { ScenarioCookieJar } from '../wirings/workflow/scenario-cookie-jar.js'
 
@@ -40,6 +41,14 @@ const failed = async (
   )
 }
 
+/**
+ * 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.
@@ -48,22 +57,31 @@ const failed = async (
  * 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,
+    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: this.secret,
+        secret,
       }),
     })
     if (!res.ok) {

package/src/services/typed-secret-service.test.ts

@@ -137,7 +137,10 @@ describe('TypedSecretService', () => {
         optional: true,
       },
     })
-    assert.strictEqual(await service.getSecret('SCENARIO_ACTOR_SECRET'), undefined)
+    assert.strictEqual(
+      await service.getSecret('SCENARIO_ACTOR_SECRET'),
+      undefined
+    )
   })
 
   test('an optional secret that IS set resolves its value', async () => {
@@ -159,6 +162,28 @@ describe('TypedSecretService', () => {
     await assert.rejects(() => service.getSecret('STRIPE_KEY'))
   })
 
+  test('a resolved-absent optional secret still reports hasSecret false', async () => {
+    // The cache stores `undefined` to remember the absence, so a `has(key)`
+    // test on it answers "we have looked", not "there is a value". Reading an
+    // optional secret must not turn its own absence into a claim it is set.
+    const service = new TypedSecretService(createMockSecrets(), {
+      OPTIONAL: { name: 'opt', displayName: 'Optional', optional: true },
+    })
+    assert.strictEqual(await service.getSecret('OPTIONAL'), undefined)
+    assert.strictEqual(await service.hasSecret('OPTIONAL'), false)
+  })
+
+  test('an optional secret set after an absent read is picked up', async () => {
+    const store = new Map<string, string>()
+    const service = new TypedSecretService(createMockSecrets(store), {
+      OPTIONAL: { name: 'opt', displayName: 'Optional', optional: true },
+    })
+    assert.strictEqual(await service.getSecret('OPTIONAL'), undefined)
+    await service.setSecret('OPTIONAL', 'later')
+    assert.strictEqual(await service.hasSecret('OPTIONAL'), true)
+    assert.strictEqual(await service.getSecret('OPTIONAL'), 'later')
+  })
+
   test('an optional secret does not re-hit the store once resolved', async () => {
     let reads = 0
     const base = createMockSecrets()

package/src/services/typed-secret-service.ts

@@ -64,8 +64,11 @@ export class TypedSecretService<
   }
 
   async hasSecret(key: string): Promise<boolean> {
+    // `undefined` is cached for an optional secret that resolved absent, so a
+    // cache hit means "already looked", not "there is a value". Reporting true
+    // for it would let a read of an optional secret assert its own presence.
     if (this.cache.has(key)) {
-      return true
+      return this.cache.get(key) !== undefined
     }
     return this.secrets.hasSecret(key)
   }

package/src/wirings/agent-scorer/agent-scorer.ts

@@ -22,7 +22,9 @@ const assertSampleRate = (name: string, sampleRate: number | undefined) => {
  * @example snippet: agentScorer
  */
 export const pikkuAgentScorer = <Services = any>(config: {
+  /** Identifies the scorer in results and in the Console. Unique per project. */
   name: string
+  /** What this scorer grades, in one line, for whoever reads the score later. */
   description: string
   /** 0..1 fraction of live runs to grade. Defaults to all of them. */
   sampleRate?: number
@@ -31,6 +33,10 @@ export const pikkuAgentScorer = <Services = any>(config: {
    * traffic has no answer key, so the runtime never samples it.
    */
   requiresReference?: boolean
+  /**
+   * The grade itself: read the finished run and return `{ score, reason }`.
+   * Runs in-process, so it may use your own services.
+   */
   score: (
     input: ScorerInput,
     services: Services
@@ -55,7 +61,9 @@ export const pikkuAgentScorer = <Services = any>(config: {
  * @example snippet: agentJudge
  */
 export const pikkuAgentJudge = <Services = any>(config: {
+  /** Identifies the judge in results and in the Console. Unique per project. */
   name: string
+  /** What this judge grades, in one line, for whoever reads the score later. */
   description: string
   /** 0..1 fraction of live runs to grade. Defaults to all of them. */
   sampleRate?: number
@@ -64,7 +72,9 @@ export const pikkuAgentJudge = <Services = any>(config: {
    * traffic has no answer key, so the runtime never samples it.
    */
   requiresReference?: boolean
+  /** The model that grades, e.g. `'claude-sonnet-4-5'`. Not the model under test. */
   model: string
+  /** The rubric: what a good answer looks like, phrased as the goal it should meet. */
   goal: string
   /**
    * How much of the run's trajectory to disclose to the judge. Defaults to
@@ -72,6 +82,10 @@ export const pikkuAgentJudge = <Services = any>(config: {
    * sending a third-party model the rows the tools returned.
    */
   toolCalls?: JudgeToolCallDisclosure
+  /**
+   * Replaces the generated rubric prompt outright, for framing `goal` cannot
+   * express. The `{ score, reason }` response is still forced.
+   */
   prompt?: (input: ScorerInput) => string
 }): PikkuAgentScorer<Services> => ({
   name: config.name,

package/src/wirings/gateway/gateway.types.ts

@@ -24,9 +24,13 @@ export interface GatewayAttachment {
 export interface GatewayInboundMessage {
   /** Platform-specific: a phone number, a Slack user id, and so on. */
   senderId: string
+  /** What they said, as plain text, with the provider's markup stripped. */
   text: string
+  /** The provider's own event, untouched, for anything this shape drops. */
   raw: unknown
+  /** Files and media that came with the message. */
   attachments?: GatewayAttachment[]
+  /** Anything else the adapter wants to carry through to the wiring. */
   metadata?: Record<string, unknown>
 }
 
@@ -35,8 +39,11 @@ export interface GatewayInboundMessage {
  * own rich content.
  */
 export interface GatewayOutboundMessage {
+  /** The reply as plain text. Every provider can render this. */
   text?: string
+  /** The provider's own rich payload, e.g. Slack blocks. Passed through as-is. */
   richContent?: Record<string, unknown>
+  /** Files and media to send alongside. */
   attachments?: GatewayAttachment[]
 }
 
@@ -45,19 +52,31 @@ export interface GatewayOutboundMessage {
  * provider expects back, or not.
  */
 export type WebhookVerificationResult =
-  { verified: true; response: unknown } | { verified: false }
+  | {
+      /** True when the request really came from the provider. */
+      verified: true
+      /** What to echo back, e.g. Meta's hub.challenge. */
+      response: unknown
+    }
+  | {
+      /** False when the signature or challenge did not check out. */
+      verified: false
+    }
 
 /**
  * What a gateway integration implements: parse an incoming event into a
  * message, send one back, and open and close the connection.
  */
 export interface GatewayAdapter {
+  /** Identifies the gateway in wirings and logs, e.g. `'slack'`. */
   name: string
   /** Return null to ignore the event, e.g. a delivery receipt. */
   parse(data: unknown): GatewayInboundMessage | null
+  /** Deliver a reply back to the sender the message came from. */
   send(senderId: string, message: GatewayOutboundMessage): Promise<void>
   /** Called by GatewayService.start(); must call onMessage per incoming event. */
   init(onMessage: (data: unknown) => Promise<void>): Promise<void>
+  /** Called by GatewayService.stop(); release the connection init() opened. */
   close(): Promise<void>
   /** Receives the GET query params, or the POST body when called from the POST handler. */
   verifyWebhook?(

package/src/wirings/persona/index.ts

@@ -55,10 +55,19 @@ export {
   OperatorSignIn,
   establishOperatorSession,
   IMPERSONATE_USER_ID_HEADER,
+  type ActorSecretResolver,
   type PersonaSignIn,
   type OperatorSignInOptions,
   type OperatorSessionResult,
 } from '../../services/persona-sign-in.js'
+export {
+  ACTOR_ROOT_SECRET_MIN_LENGTH,
+  ACTOR_SECRET_INFO,
+  ACTOR_SECRET_NAME,
+  actorSecretSubject,
+  deriveActorSecret,
+  verifyActorSecret,
+} from '../../services/persona-actor-secret.js'
 export {
   postScenarioJson,
   readScenarioHttpResponse,

package/src/wirings/secret/secret.types.ts

@@ -1,8 +1,16 @@
 export type CoreSecret<T = unknown> = {
+  /** The key code reads it by: `secrets.getSecret('NAME')`. SCREAMING_SNAKE_CASE. */
   name: string
+  /** How the secret is labelled wherever a person is asked to supply it. */
   displayName: string
+  /** What this secret is for, shown beside the field someone has to fill in. */
   description?: string
+  /** The id under the backing store, which is where the value actually lives. */
   secretId: string
+  /**
+   * The shape of the value, as a schema. This is what types `getSecret`'s
+   * result — pass the schema itself, not an instance of it.
+   */
   schema: T
   /** Required by default: this says absence is a supported state, and `getSecret` resolves `undefined` rather than throwing. */
   optional?: boolean