@pikku/core 0.12.141 → 0.12.142

package/knowledge/questions/should-a-wrong-bearer-token-be-anonymous-or-refused.md

@@ -0,0 +1,35 @@
+---
+type: question
+title: Should a Bearer token that does not verify be anonymous or refused?
+description: authBearer refuses a malformed scheme with InvalidSessionError but lets a well-formed wrong token through as anonymous, and no comment says why
+tags: core, auth, middleware
+---
+
+# Should a Bearer token that does not verify be anonymous or refused?
+
+In `authBearer` (`packages/core/src/middleware/auth-bearer.ts`) the code splits
+the header into scheme and token. A scheme other than `Bearer`, or an empty
+token, throws `InvalidSessionError`. A `Bearer` token that then fails the static
+constant-time compare, or decodes to nothing, does not throw. It calls `next()`
+with no session, and the function gate decides what happens next.
+
+Tests back both halves: "should throw InvalidSessionError when scheme is not
+Bearer" and "should not set session when static token does not match". Neither
+says why a malformed header is refused while a wrong credential is anonymous.
+
+The JWT branch is different. When no static token is configured and a `jwtService`
+is wired, `authBearer` calls `jwtService.decode(bearerToken)` with no try/catch
+(`auth-bearer.ts`, around line 72). Core ships only the `JWTService` interface
+(`packages/core/src/services/jwt-service.ts`). The implementation in this repo is
+`JoseJWTService` (`packages/services/jose/src/jose-jwt-service.ts`). Its `decode`
+calls `jose.jwtVerify` with HS256 only, so a bad signature or an expired token
+throws, and so does an unknown key id (`Missing secret for id`). A token with no
+key id is verified against the current secret. Because `authBearer` does not
+catch that throw, with this implementation a bad JWT is a request error, not an
+anonymous request. Other `JWTService` implementations are not in this repo, so
+they are not covered by this.
+
+What is asked: is an unverifiable Bearer token meant to be treated as no session,
+so that a public function still answers it, or should it be refused at the
+middleware the way a malformed header is? The two cases differ only in the
+credential being well-formed, and the code makes no stated choice about it.

package/knowledge/questions/should-an-empty-webhook-signing-secret-send-unsigned.md

@@ -0,0 +1,23 @@
+---
+type: question
+title: Should an outgoing webhook go out unsigned when its configured signing secret resolves empty?
+description: When config.webhook.secret names a secret that resolves to nothing, the delivery is logged as unsigned and enqueued without a signature
+tags: core, webhooks, signing
+---
+
+# Should an outgoing webhook go out unsigned when its configured signing secret resolves empty?
+
+`prepareDelivery` in `packages/core/src/services/queue-webhook-service.ts:52-66`
+reads the signing secret from `config.webhook.secret` when the caller passed none
+(`:53-55`). If that secret resolves to nothing, the code logs an error that says
+the outgoing webhooks "will be sent UNSIGNED" (`:56-60`) and carries on. The
+signature header is added only when a secret is present (`:62-66`), so the job
+is enqueued without one.
+
+The existing note `webhook-bodies-are-signed-before-they-are-enqueued.md` covers
+signing at enqueue time and the key staying out of the queue payload. It does not
+cover this fallback.
+
+**Question:** should a configured but empty signing secret send the delivery
+unsigned with a log line, or refuse to enqueue it? The code takes the first
+option. Nothing in the file records a reason, and the only signal is the log.

package/knowledge/questions/should-http-virtual-user-sessions-reset-between-scenarios-in-one-run.md

@@ -0,0 +1,27 @@
+---
+type: question
+title: Should HTTP virtual user sessions reset between scenarios in one CLI run?
+description: The CLI builds HTTP virtual users once and reuses them for every scenario, and only the browser side is reset between scenarios
+tags: core, cli, scenario, virtual-users
+---
+
+# Should HTTP virtual user sessions reset between scenarios in one CLI run?
+
+In `packages/cli/src/functions/commands/scenario.ts`, `createHttpVirtualUsers`
+runs once (around line 314), and that same `virtualUsers` object is passed to
+every `workflowService.startWorkflow` call for each scenario (around line 745).
+Each `HttpVirtualUser` holds its own cookie jar and its `signedIn` flag for the
+life of the process.
+
+Before each scenario the command calls `browserLifecycle.reset()` (around line
+723), which discards the browser's per-scenario state. Nothing resets the HTTP
+jars: `scenario.ts` never calls `clear` or `signOut`, and
+`PikkuScenarioService.detachRunContext` (`packages/core/src/wirings/workflow/pikku-scenario-service.ts`)
+drops the run's map entry but not the jars inside the shared object.
+
+So an HTTP virtual user that signed in during one scenario is still signed in for
+the next, unless a 401 forces a re-login. The browser side is reset to keep one
+scenario from leaving the next signed in as somebody else, as
+[Scenario sessions are isolated per virtual user and reset between scenarios](../decisions/security/workflow-scenario-sessions-are-isolated-per-virtual-user-and-per-scenario.md)
+records. What is asked: is the HTTP side meant to carry sessions across scenarios
+as a speed measure, or should it be reset the same way?

package/knowledge/questions/should-the-cookie-jar-scope-cookies-to-the-api-origin.md

@@ -0,0 +1,26 @@
+---
+type: question
+title: Should the scenario cookie jar scope cookies to the API origin?
+description: createCookieJar sends every held cookie to whatever URL it is given, keeps only name and value from Set-Cookie, and stamps the API origin on all calls
+tags: core, scenario, cookies
+---
+
+# Should the scenario cookie jar scope cookies to the API origin?
+
+`createCookieJar` in `packages/core/src/services/scenario-cookie-jar.ts`
+takes one `apiUrl` and reads its origin once. Its `fetch` ignores the host of
+`input`. It sets the `Origin` header to that origin on every call, and it adds
+every held cookie to every call whatever URL the call goes to.
+
+From `Set-Cookie` it keeps only the `name=value` pair. `Path`, `Domain`,
+`Secure`, `Max-Age` and `Expires` are discarded. A cookie is removed only when its
+value is empty, so `session=x; Max-Age=0` would be stored as a live cookie.
+
+The tests in `scenario-cookie-jar.test.ts` send every request to one local
+server, so none of this is exercised. The `Origin` stamp is tested on purpose
+("stamps the origin Better Auth checks on state-changing calls").
+
+What is asked: is the jar meant only to talk to its own API, in which case the
+cross-host behaviour does not matter, or should it honour cookie scope? The code
+does not say, and the browser-side equivalent in `packages/playwright/src/provider.ts`
+plants cookies on `appUrl` instead.

package/knowledge/questions/should-voice-input-fetch-audio-urls-without-a-host-allowlist.md

@@ -0,0 +1,20 @@
+---
+type: question
+title: Should voiceInput fetch audio URLs when no host allowlist is configured?
+description: With no allowedAudioHosts, the audio URL is fetched through safeFetch with no allowlist, so any public host is reachable
+tags: core, agent, voice, ssrf
+---
+
+# Should voiceInput fetch audio URLs when no host allowlist is configured?
+
+`fetchAsUint8Array` in `packages/core/src/wirings/agent/voice-input.ts:57-61` calls
+`safeFetch` with `{ allowedHosts: allowedAudioHosts }`. That value is optional.
+The caller passes `config.allowedAudioHosts` for a URL audio part (`:136-138`).
+
+In `packages/core/src/utils/safe-fetch.ts:269-273`, with no allowlist the only
+host check is the private-host refusal. So a URL that is not on a list, but is
+public, is fetched when no list is configured.
+
+**Question:** should `voiceInput` require `allowedAudioHosts` before it fetches a
+URL, or is the private-host block meant to be enough? The code takes the second
+option. No note or comment in the file says which is intended.

package/knowledge/questions/staging-impersonation-rules.md

@@ -0,0 +1,27 @@
+---
+type: question
+title: What rules govern impersonation on staging and live?
+description: Staged impersonation by a signed-in admin is wanted; the switch, read-only default, expiry and logging rules are proposed but not agreed
+tags: auth, services
+---
+
+# What rules govern impersonation on staging and live?
+
+Wanted: a signed-in admin on a deployed environment can impersonate a virtual user,
+using the header on the normal cookie session. The code already applies
+impersonation on that path (`auth-session.ts`, the human branch).
+
+Not yet agreed:
+
+- **Per-environment switch.** On for staging; off for production. The request
+  is that it is off unless turned on for that environment.
+- **Read-only by default.** Writes made while impersonating change real data.
+- **Expiry.** An impersonation ends after a short time.
+- **Logging.** Each impersonated request records the real admin and the target.
+  Today the impersonation line is `info` and does not record the admin against
+  each request.
+- **Banner.** The panel shows "viewing as X".
+
+Also unverified: the default impersonation gate reads the owner's scopes
+(`userHoldsScopes(result.user.id, …)`), not the scopes of the key or session that
+made the request.

package/knowledge/questions/virtual-user-keys-on-cloud-stages-are-pikku-studios-to-build.md

@@ -0,0 +1,34 @@
+---
+type: question
+title: Pikku Studio Cloud has to create, hold and deliver the stage virtual user keys
+description: This repo defines the variables and verifies statements; generating a pair per stage and signing for stage callers is Pikku Studio Cloud work that has not been done or checked
+tags: services
+---
+
+# Pikku Studio Cloud has to create, hold and deliver the stage virtual user keys
+
+The Pikku Studio Cloud repository is not on the machine this was built on, so none of the
+following is built or confirmed. Pikku Studio Cloud must:
+
+1. Generate one Ed25519 key pair per stage at creation and keep the private key in its
+   backend, never on the stage.
+2. Set the stage variable `VIRTUAL_USER_VERIFY_KEY` to the public key (SPKI DER,
+   base64), and accept that name, which starts with neither `PIKKU_` nor `PIKKUSTUDIO_`.
+3. Set `VIRTUAL_USER_API_URL` on every stage that runs virtual users, to the public
+   URL including any HTTP prefix.
+4. Replace the operator sign-in route and `PIKKUSTUDIO_OPERATOR_TOKEN` handling: sign
+   statements with the stage's private key for callers acting on a stage, or hand the
+   key to the CLI as `VIRTUAL_USER_SIGNING_KEY` through the channel it already uses
+   for stage credentials.
+5. Stop sending the operator token field in `runVirtualUser` requests; the field no longer
+   exists.
+6. For the stage switcher, sign a statement for the chosen virtual user and pass it to
+   `/sign-in/switch-virtual-user` as `statement`.
+
+Unverified: that Pikku Studio Cloud accepts an arbitrary unreserved variable per stage, that a
+Worker can fetch its own public hostname (the run needs this on Workers), and that the
+`audience` plugin option copes with a proxy that rewrites the origin. A run without a
+sign-in path reads roles from the `getMyScopes` RPC and falls back to
+`/auth/get-session`.
+
+**What would settle it:** Pikku Studio Cloud landing the six items, and one stage run end to end.

package/knowledge/questions/virtual-user-statement-replay-is-per-process.md

@@ -0,0 +1,20 @@
+---
+type: question
+title: A virtual user statement can be replayed once per instance
+description: The one-time id store is an in-memory map, so on several instances or Worker isolates each accepts a statement once
+tags: services
+---
+
+# A virtual user statement can be replayed once per instance
+
+`JoseVirtualUserStatementVerifier` remembers accepted `jti` values in a per-process
+map. On a single node that makes a statement single-use. On several instances, or
+Cloudflare Workers where isolates share nothing, a captured statement can be accepted
+once per instance within its few-minute life.
+
+The lifetime ceiling (300 seconds) and the signed audience bound the damage; neither
+removes it.
+
+**What would settle it:** a shared store — the Better Auth `verification` table is
+already there — behind the verifier, or a decision that the bound is acceptable for
+stages. Not built.

package/knowledge/questions/what-an-impersonated-session-carries.md

@@ -0,0 +1,22 @@
+---
+type: question
+title: What should an impersonated session carry?
+description: An impersonated session without a mapSession is just { userId }, dropping the orgId and virtualUser fields a normal session has; nobody has said whether that is intended
+tags: better-auth, impersonation, sessions
+---
+
+# What should an impersonated session carry?
+
+When impersonation resolves and the app has no `mapSession`,
+`resolveImpersonatedSession` returns `{ userId: target }`
+(`packages/services/better-auth/src/auth-session-impersonation.ts`). A normal
+session from the same middleware carries more: the `orgId` `defaultSession` reads
+from the active organization, the `virtualUser` flag `stampVirtualUserFlag` adds,
+and whatever `mapSession` adds.
+
+So an impersonated request can behave differently from the same user signing in
+directly. The code makes the choice; no comment or note defends it.
+
+Open: should the impersonated session copy the target's `orgId` and `virtualUser`
+stamp, or is a bare id intended? Answering it decides whether org-scoped reads
+work under impersonation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.141",
+  "version": "0.12.142",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -42,7 +42,7 @@
     "./scenario/coverage": "./dist/wirings/workflow/scenario-coverage.js",
     "./workflow/timeline": "./dist/wirings/workflow/run-timeline.js",
     "./workflow/types": "./dist/wirings/workflow/workflow.types.js",
-    "./actor-flow": "./dist/wirings/actor-flow/index.js",
+    "./virtual-user/conversation": "./dist/wirings/virtual-user/conversation/index.js",
     "./virtual-user": "./dist/wirings/virtual-user/index.js",
     "./channel/local": "./dist/wirings/channel/local/index.js",
     "./channel/serverless": "./dist/wirings/channel/serverless/index.js",
@@ -67,7 +67,6 @@
     "./credential": "./dist/wirings/credential/index.js",
     "./scope": "./dist/wirings/scope/index.js",
     "./role": "./dist/wirings/role/index.js",
-    "./persona": "./dist/wirings/persona/index.js",
     "./secret": "./dist/wirings/secret/index.js",
     "./variable": "./dist/wirings/variable/index.js",
     "./webhook": "./dist/wirings/webhook/index.js",

package/src/public-surface.json

@@ -84,12 +84,12 @@
   "./scenario": [
     "PikkuScenarioService",
     "SCENARIO_SURFACES",
-    "ScenarioActorRequired",
     "ScenarioBrowserUnavailable",
     "ScenarioHookError",
     "ScenarioNoSurfaceBinding",
     "ScenarioNoWitness",
     "ScenarioUnwitnessedAssertion",
+    "ScenarioVirtualUserRequired",
     "ScenarioWitnessDisagreement",
     "addFeature",
     "composeStepProse",
@@ -111,44 +111,64 @@
     "reconstructStateAt"
   ],
   "./workflow/types": [],
-  "./actor-flow": [
+  "./virtual-user/conversation": [
     "runConversation"
   ],
   "./virtual-user": [
+    "APP_SCOPE_ROOT",
     "DEFAULT_MAX_INTERVAL_MS",
     "DEFAULT_MIN_INTERVAL_MS",
     "DISPOSITIONS",
+    "HttpVirtualUser",
     "IntentStack",
     "PRODUCTION_DISPOSITION",
     "STALE_RUN_AFTER_MS",
     "VIRTUAL_USER_VARIABLES",
+    "appScopeId",
+    "authMount",
+    "buildAppScopeDefinition",
     "catalogueClassification",
     "catalogueLookup",
+    "createCookieJar",
+    "createHttpVirtualUsers",
+    "defineVirtualUsers",
     "deriveCatalogue",
     "deriveIntents",
     "dispositionProfile",
     "executeVirtualUserRun",
-    "intentsForPersona",
+    "inProcessSignIn",
+    "intentsForVirtualUser",
     "isDue",
     "isReadOnly",
+    "isRunnableVirtualUser",
     "logVirtualUserTick",
     "nextRunAt",
-    "personaScopes",
-    "personaVirtualUserTarget",
+    "postScenarioJson",
     "prepareVirtualUserRun",
     "reachableCatalogue",
+    "readScenarioHttpResponse",
     "requireVirtualUserRunStore",
     "requireVirtualUserScheduleStore",
+    "roleMismatchMessage",
     "runVirtualUser",
-    "runnablePersona",
+    "runnableVirtualUser",
+    "runnableVirtualUsers",
     "serializeVirtualUserRun",
     "serializeVirtualUserSchedule",
     "serializeVirtualUserSteps",
-    "signInPathFor",
     "startVirtualUserRun",
+    "statementSignIn",
     "tickVirtualUserSchedules",
     "unreachableCatalogue",
+    "validateAndBuildVirtualUsersMeta",
+    "verifyVirtualUserRoles",
+    "virtualUserEmail",
+    "virtualUserEmails",
+    "virtualUserEnvironmentErrors",
+    "virtualUserEnvironmentRefusal",
     "virtualUserScheduleRunInput",
+    "virtualUserScopes",
+    "virtualUserTarget",
     "writeVirtualUserSchedule"
   ],
   "./channel/local": [
@@ -352,36 +372,6 @@
     "flattenSystemRoleDefinitions",
     "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",
-    "personaEmails",
-    "personaEnvironmentErrors",
-    "personaEnvironmentRefusal",
-    "postScenarioJson",
-    "readScenarioHttpResponse",
-    "roleMismatchMessage",
-    "runnablePersonas",
-    "validateAndBuildPersonasMeta",
-    "verifyActorSecret",
-    "verifyPersonaRoles"
-  ],
   "./secret": [
     "defineSecret",
     "deriveOAuth2AppSecrets",
@@ -447,9 +437,6 @@
     "isExpectedError"
   ],
   "./services": [
-    "ACTOR_ROOT_SECRET_MIN_LENGTH",
-    "ACTOR_SECRET_INFO",
-    "ACTOR_SECRET_NAME",
     "ConsoleLogger",
     "DEFAULT_WEBHOOK_RETRIES",
     "InMemoryAgentRunStateService",
@@ -488,13 +475,18 @@
     "TypedCredentialService",
     "TypedSecretService",
     "TypedVariablesService",
+    "VIRTUAL_USER_IN_PROCESS_ENDPOINT",
+    "VIRTUAL_USER_SIGNING_KEY_VARIABLE",
+    "VIRTUAL_USER_STATEMENT_ALGORITHM",
+    "VIRTUAL_USER_STATEMENT_MAX_TTL_SECONDS",
+    "VIRTUAL_USER_STATEMENT_TTL_SECONDS",
+    "VIRTUAL_USER_VERIFY_KEY_VARIABLE",
+    "VirtualUserStatementError",
     "WebhookService",
-    "actorSecretSubject",
     "assertSecretAllowedForHost",
     "createInvocationAudit",
     "createMiddlewareSessionWireProps",
     "createStubProxy",
-    "deriveActorSecret",
     "getStubTracker",
     "holdLease",
     "isTestRun",
@@ -504,7 +496,6 @@
     "renderEmail",
     "spy",
     "stub",
-    "verifyActorSecret",
     "withoutSecrets"
   ],
   "./flag": [
@@ -545,15 +536,15 @@
     "createLocalContentRequestHandler",
     "verifySignedContentRequest"
   ],
+  "./services/temporary-file-service": [
+    "TemporaryFileInstance",
+    "TemporaryFileService"
+  ],
   "./services/file-scenario-run-store": [
     "FileScenarioRunStore",
     "scenarioArtifactContentType",
     "scenarioRunSummary"
   ],
-  "./services/temporary-file-service": [
-    "TemporaryFileInstance",
-    "TemporaryFileService"
-  ],
   "./crypto-utils": [
     "MIN_KEY_MATERIAL_LENGTH",
     "REMOTE_SESSION_INFO",

package/dist/services/persona-actor-secret.d.ts

@@ -1,38 +0,0 @@
-/** The name the root secret is held under, used only in error messages. */
-export declare 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 declare const ACTOR_SECRET_INFO = "pikku:actor-sign-in";
-/** The root must be strong: every persona's credential is derived from it. */
-export declare const ACTOR_ROOT_SECRET_MIN_LENGTH = 32;
-/**
- * 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 declare const actorSecretSubject: (email: string) => string;
-/**
- * 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 declare const deriveActorSecret: (rootSecret: string, email: string) => Promise<string>;
-/**
- * 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 declare const verifyActorSecret: (rootSecret: string, email: string, presented: string) => Promise<boolean>;

package/dist/services/persona-actor-secret.js

@@ -1,39 +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) => 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, email) => 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, email, presented) => verifyWithKeyMaterial(ACTOR_SECRET_NAME, rootSecret, ACTOR_SECRET_INFO, actorSecretSubject(email), presented);

package/dist/services/persona-sign-in.d.ts

@@ -1,117 +0,0 @@
-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 declare 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>;
-}
-/**
- * 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 declare class ActorSignIn implements PersonaSignIn {
-    private readonly apiUrl;
-    private readonly secret;
-    private readonly signInPath;
-    constructor(apiUrl: string, secret: string | ActorSecretResolver, signInPath: string);
-    login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>;
-    headers(): Record<string, string>;
-}
-/**
- * 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 declare const authMount: (signInPath?: string) => string | undefined;
-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 declare const establishOperatorSession: (fetchImpl: typeof fetch, apiUrl: string, persona: ResolvedPersona, options: OperatorSignInOptions, extraHeaders?: Record<string, string>) => Promise<OperatorSessionResult>;
-/**
- * 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 declare class OperatorSignIn implements PersonaSignIn {
-    private readonly apiUrl;
-    private readonly options;
-    private userId;
-    constructor(apiUrl: string, options: OperatorSignInOptions);
-    login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>;
-    headers(): Record<string, string>;
-}