@pikku/core 0.12.98 → 0.12.100

package/knowledge/decisions/security/actor-sign-in-only-works-for-actor-flagged-users.md

@@ -1,27 +1,31 @@
 ---
 type: decision
 title: Actor sign-in only works for actor-flagged users
-description: The scenario actor secret mints sessions for user rows flagged actor and nothing else, so holding it never impersonates a real user
+description: An actor credential mints sessions for user rows flagged actor and nothing else, so holding one never impersonates a real user
 tags: services
 ---
 
 # Actor sign-in only works for actor-flagged users
 
-`HttpScenarioActorsConfig.secret`
-(`packages/core/src/services/http-scenario-actors.ts`) is a shared impersonation
-secret: `HttpScenarioActor.login` POSTs `{ email, name, secret }` to
+`HttpPersonasConfig.secret` (`packages/core/src/services/http-personas.ts`) is
+what `ActorSignIn.login` presents: it POSTs `{ email, name, secret }` to
 `/auth/sign-in/actor` and gets back a session. That looks like a master key, and
-it deliberately is not one.
+it deliberately is not one — for two independent reasons.
 
-The Better Auth actor plugin on the other end upserts and signs in only user rows
-flagged `actor: true`. Presenting the secret with a real customer's email does not
-mint that customer's session — it is refused. The `actor` flag also flows into the
-minted session, so audits and analytics can tell scenario traffic from human
-traffic after the fact. The blast radius of a leaked actor secret is therefore the
-synthetic actor population, not the user table.
+The first is the flag. The Better Auth actor plugin on the other end upserts and
+signs in only user rows flagged `actor: true`. Presenting a credential with a
+real customer's email does not mint that customer's session — it is refused. The
+`actor` flag also flows into the minted session, so audits and analytics can tell
+scenario traffic from human traffic after the fact.
+
+The second is that a credential is not shared. What is presented is derived from
+the root `SCENARIO_ACTOR_SECRET` and the address it signs in as — see
+[an actor credential is derived per persona](an-actor-credential-is-derived-per-persona.md) —
+so the blast radius of a leaked credential is one synthetic account, not the
+synthetic actor population.
 
 **What this rules out:** widening the sign-in endpoint to accept any email "so
-scenarios can test as a real user", and treating the actor secret as equivalent to
-a session-signing key. It also rules out dropping the `actor` flag from the minted
-session — the audit trail's ability to separate synthetic from real activity
-depends on it.
+scenarios can test as a real user", and treating an actor credential as
+equivalent to a session-signing key. It also rules out dropping the `actor` flag
+from the minted session — the audit trail's ability to separate synthetic from
+real activity depends on it.

package/knowledge/decisions/security/an-actor-credential-is-derived-per-persona.md

@@ -0,0 +1,41 @@
+---
+type: decision
+title: An actor credential is derived per persona
+description: What a caller presents to the actor endpoint is HKDF-derived from the root secret and the address it signs in as, so one credential opens one persona
+tags: services
+---
+
+# An actor credential is derived per persona
+
+`SCENARIO_ACTOR_SECRET` is a root, not a password. What a caller presents to
+`/auth/sign-in/actor` is `deriveActorSecret(root, email)`
+(`packages/core/src/services/persona-actor-secret.ts`) — an HKDF-expanded
+HMAC-SHA256 over the lowercased address, on the same key-material primitives
+everything else in core signs with. The endpoint does not store or look anything
+up: it re-derives the expected value for whichever address is being signed in as
+and compares. A credential minted for one persona is refused for every other.
+
+The root itself is not accepted as a credential, and a root shorter than 32
+characters refuses the endpoint outright rather than deriving weak credentials
+from it. The server-side warning names the problem; what the client is told does
+not.
+
+Derivation rather than a per-persona secrets table because there is then nothing
+to store, provision, or keep in sync — the target already holds the root, and
+rotating it invalidates every credential at once.
+
+This is what lets a holder be handed less than everything:
+
+- The browser switcher gets `VITE_DEV_ACTOR_SECRETS`, one credential per
+  declared persona. The root stays on the dev server, so a bundle can no longer
+  hold the thing that is entitled to every persona.
+- A run can be given `PIKKU_PERSONA_SECRETS` (`id=secret,…`, minted with
+  `pikku persona secret`) instead of the root, and then it can sign in as those
+  personas and no others. Asking for one outside the list throws naming the
+  persona rather than falling back to the root.
+
+**What this rules out:** accepting the root as a credential at the endpoint,
+putting the root in any client bundle, and comparing a presented credential
+against a stored one. It also rules out per-persona secrets that are generated
+randomly and written down — the derivation is the reason there is nothing to
+provision.

package/knowledge/decisions/security/index.md

@@ -19,7 +19,8 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [A workflow run is read and approved by its owner](a-workflow-run-is-read-and-approved-by-its-owner.md) — A run started through a session records that user and only that user may read it or answer its approval gates; a run with no recorded owner has no ownership to enforce
 - [An actor's missing approval decision defaults to denied](actor-flow-missing-approval-decisions-default-to-denied.md) — Every pending tool call gets an explicit decision; an id the persona LLM omitted is denied, so a dropped field can never read as consent
 - [Actor sign-in is proven by Set-Cookie, not a non-empty jar](actor-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md) — HttpScenarioActor tracks its own signedIn flag and requires the sign-in response itself to set a cookie, because a populated jar proves nothing
-- [Actor sign-in only works for actor-flagged users](actor-sign-in-only-works-for-actor-flagged-users.md) — The scenario actor secret mints sessions for user rows flagged actor and nothing else, so holding it never impersonates a real user
+- [Actor sign-in only works for actor-flagged users](actor-sign-in-only-works-for-actor-flagged-users.md) — An actor credential mints sessions for user rows flagged actor and nothing else, so holding one never impersonates a real user
+- [An actor credential is derived per persona](an-actor-credential-is-derived-per-persona.md) — What a caller presents to the actor endpoint is HKDF-derived from the root secret and the address it signs in as, so one credential opens one persona
 - [Addon auth and tags only tighten, and resolve where the function runs](addon-auth-and-tags-only-tighten.md) — wireAddon auth and tags are applied in runPikkuFunc like scopes, but auth:false is ignored and tags resolve against the consuming app's tag groups rather than the addon package's
 - [Addon auth and tag gates apply wherever the function runs, including inside the addon](addon-config-gates-apply-only-at-the-namespaced-rpc-boundary.md) — wireAddon's auth and tags moved from the namespaced RPC boundary into runPikkuFunc, so they also apply to direct wirings and to bare intra-addon calls
 - [Addon scopes are resolved where the function runs](addon-scopes-are-resolved-where-the-function-runs.md) — wireAddon scopes are merged inside runPikkuFunc rather than at namespace resolution, because most wirings reach an addon function without ever resolving a namespace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.98",
+  "version": "0.12.100",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -18,12 +18,12 @@
   },
   "sideEffects": [
     "./dist/errors/errors.js",
-    "./dist/wirings/rpc/rpc-runner.js",
     "./dist/wirings/addon/remote-addon-auth.js",
+    "./dist/wirings/rpc/rpc-runner.js",
+    "./dist/wirings/workflow/pikku-scenario-service.js",
     "./dist/wirings/workflow/workflow-approval-policy.js",
     "./dist/wirings/workflow/workflow-errors.js",
-    "./dist/wirings/workflow/workflow-run-ownership.js",
-    "./dist/wirings/workflow/pikku-scenario-service.js"
+    "./dist/wirings/workflow/workflow-run-ownership.js"
   ],
   "exports": {
     ".": "./dist/bootstrap-compat/root.js",

package/src/public-surface.json

@@ -289,15 +289,21 @@
     "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",
+    "authMount",
     "buildAppScopeDefinition",
     "createHttpPersonas",
     "definePersonas",
+    "deriveActorSecret",
     "establishOperatorSession",
     "isRunnablePersona",
     "personaEmail",
@@ -309,6 +315,7 @@
     "roleMismatchMessage",
     "runnablePersonas",
     "validateAndBuildPersonasMeta",
+    "verifyActorSecret",
     "verifyPersonaRoles"
   ],
   "./secret": ["defineSecret", "validateAndBuildSecretDefinitionsMeta"],
@@ -364,6 +371,9 @@
     "isExpectedError"
   ],
   "./services": [
+    "ACTOR_ROOT_SECRET_MIN_LENGTH",
+    "ACTOR_SECRET_INFO",
+    "ACTOR_SECRET_NAME",
     "ConsoleLogger",
     "DEFAULT_WEBHOOK_RETRIES",
     "FileScenarioRunStore",
@@ -394,10 +404,12 @@
     "TypedSecretService",
     "TypedVariablesService",
     "WebhookService",
+    "actorSecretSubject",
     "assertSecretAllowedForHost",
     "createInvocationAudit",
     "createMiddlewareSessionWireProps",
     "createStubProxy",
+    "deriveActorSecret",
     "getStubTracker",
     "isTestRun",
     "pikkuWebhookWorkerFunc",
@@ -406,6 +418,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' }))
@@ -31,6 +35,29 @@ const startTarget = async () => {
         res.writeHead(200).end(JSON.stringify({ ok: true, email: body.email }))
         return
       }
+      if (req.url === '/api/auth/sign-in/fabric') {
+        if (body.token !== 'operator-token') {
+          res.writeHead(401).end(JSON.stringify({ message: 'bad operator' }))
+          return
+        }
+        logins++
+        res.setHeader('set-cookie', [`session=s${logins}; Path=/; HttpOnly`])
+        res
+          .writeHead(200)
+          .end(JSON.stringify({ actAs: { userId: `u-${body.actAs.email}` } }))
+        return
+      }
+      if (req.url === '/api/auth/get-session') {
+        const cookie = req.headers.cookie ?? ''
+        if (!cookie.includes('session=')) {
+          res.writeHead(200).end('null')
+          return
+        }
+        res
+          .writeHead(200, { 'content-type': 'application/json' })
+          .end(JSON.stringify({ user: { role: 'admin,support' } }))
+        return
+      }
       if (req.url?.startsWith('/api/rpc/')) {
         const cookie = req.headers.cookie ?? ''
         if (!cookie.includes('session=') || expireNext) {
@@ -59,6 +86,7 @@ const startTarget = async () => {
             echoed: body.data,
             cookie,
             userHeader: req.headers['x-user-id'] ?? null,
+            impersonated: req.headers['x-pikku-impersonate-user-id'] ?? null,
           })
         )
         return
@@ -70,6 +98,7 @@ const startTarget = async () => {
   const { port } = server.address() as { port: number }
   return {
     server,
+    origin: `http://127.0.0.1:${port}`,
     apiUrl: `http://127.0.0.1:${port}/api`,
     loginCount: () => logins,
     expireSession: () => {
@@ -82,7 +111,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,11 +247,67 @@ 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/
     )
   })
+
+  // An app whose auth is under `/api` but whose RPCs are not cannot put the
+  // mount in `apiUrl`, so it moves `signInPath` instead. The session read has
+  // to follow it: a 404 there reads as 'this stage does not report roles' and
+  // silently turns the role check off.
+  test('reads the session from the mount the sign-in path names', async () => {
+    const actors = createHttpPersonas({
+      apiUrl: target.origin,
+      secret: ROOT,
+      signInPath: '/api/auth/sign-in/actor',
+      rpcPath: '/api/rpc',
+      personas: {
+        manager: {
+          id: 'manager',
+          name: 'Manager',
+          email: 'manager@personas.invalid',
+          roles: ['admin'],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
+      },
+    })
+
+    assert.deepEqual(await actors.manager!.sessionRoles(), ['admin', 'support'])
+  })
+
+  // The operator handshake sits under the same mount and must be derived from
+  // it, not inherited verbatim: posting an operator token to the ACTOR path is
+  // a validation error about a missing email, which reads like a broken
+  // persona rather than a wrong URL.
+  test('derives the operator sign-in path from the same auth mount', async () => {
+    const actors = createHttpPersonas({
+      apiUrl: target.origin,
+      signInPath: '/api/auth/sign-in/actor',
+      rpcPath: '/api/rpc',
+      operator: { token: 'operator-token' },
+      personas: {
+        manager: {
+          id: 'manager',
+          name: 'Manager',
+          email: 'manager@personas.invalid',
+          roles: ['admin'],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
+      },
+    })
+
+    const result = (await actors.manager!.invoke('ping', {})) as any
+    assert.equal(result.rpcName, 'ping')
+    assert.equal(result.impersonated, 'u-manager@personas.invalid')
+  })
 })

package/src/services/http-personas.ts

@@ -18,9 +18,11 @@ import {
 } from '../wirings/workflow/scenario-cookie-jar.js'
 import {
   ActorSignIn,
+  type ActorSecretResolver,
   OperatorSignIn,
   type OperatorSignInOptions,
   type PersonaSignIn,
+  authMount,
 } from './persona-sign-in.js'
 import { getSingletonServices } from '../pikku-state.js'
 import { AIProviderNotConfiguredError } from '../errors/errors.js'
@@ -34,13 +36,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.
    *
@@ -58,7 +66,12 @@ export interface HttpPersonasConfig {
    * {@link OperatorSignInOptions.signInPath} overrides it.
    */
   signInPath?: string
-  /** Where the session (and its roles) is read back. Default `/auth/get-session`. */
+  /**
+   * Where the session (and its roles) is read back. Defaults to `get-session`
+   * under the same auth mount as {@link HttpPersonasConfig.signInPath}, so an
+   * app that moved auth under `/api` moves this with it and does not have to
+   * say so twice.
+   */
   sessionPath?: string
   /** Exposed-RPC path prefix under apiUrl. Default `/rpc`. */
   rpcPath?: string
@@ -99,7 +112,11 @@ export class HttpPersona implements ScenarioPersona {
     if (config.operator) {
       this.signIn = new OperatorSignIn(config.apiUrl, {
         ...config.operator,
-        signInPath: config.operator.signInPath ?? config.signInPath,
+        signInPath:
+          config.operator.signInPath ??
+          (authMount(config.signInPath)
+            ? `${authMount(config.signInPath)}/sign-in/fabric`
+            : undefined),
       })
     } else if (config.secret) {
       this.signIn = new ActorSignIn(
@@ -200,7 +217,11 @@ export class HttpPersona implements ScenarioPersona {
     if (!this.signedIn) {
       await this.login()
     }
-    const sessionPath = this.config.sessionPath ?? '/auth/get-session'
+    const mount = authMount(
+      this.config.operator?.signInPath ?? this.config.signInPath
+    )
+    const sessionPath =
+      this.config.sessionPath ?? `${mount ?? '/auth'}/get-session`
     const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`, {
       headers: this.signIn.headers(),
     })

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) {
@@ -83,6 +101,22 @@ export class ActorSignIn implements PersonaSignIn {
   }
 }
 
+/**
+ * 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