@pikku/core 0.12.141 → 0.12.143

package/knowledge/decisions/security/workflow-helper-functions-are-sessionless-by-declaration.md

@@ -0,0 +1,18 @@
+---
+type: decision
+title: Workflow helper functions are registered sessionless by declaration
+description: Queue-worker helpers and the workflow sleeper get meta with sessionless true, so the runner requires a session for them only where their own auth flag says so
+tags: core, workflow, queue, sessions
+---
+
+# Workflow helper functions are registered sessionless by declaration
+
+`helperFunctionMeta` in `packages/core/src/wirings/workflow/workflow-queue-wiring.ts` returns the function meta for internal workflow helpers. It sets `sessionless: true` and `functionType: 'helper'`, and sets no `expose` flag (`workflow-queue-wiring.ts:19-25`).
+
+It is applied to each queue worker function that has no meta yet (`workflow-queue-wiring.ts:66-68`), and to the built-in `pikkuWorkflowSleeper` (`workflow-queue-wiring.ts:122-129`).
+
+With `sessionless` set, the runner requires a session only when the wiring, the function config, or the addon says `auth: true` (`packages/core/src/function/function-runner.ts:385-395`). The helpers therefore run without a session unless one of those says otherwise.
+
+The helpers are internal. Their safety rests on the absence of `expose`, and on the scenario and workflow rules that keep such functions off the network surface ([scenario-step functions are never externally invocable](scenario-step-functions-are-never-externally-invocable.md)).
+
+**What this rules out:** declaring a function that acts on a user's behalf as a workflow helper to skip its session requirement, and exposing a helper over RPC by adding `expose` to its meta.

package/knowledge/decisions/security/{workflow-scenario-sessions-are-isolated-per-actor-and-per-scenario.md → workflow-scenario-sessions-are-isolated-per-virtual-user-and-per-scenario.md}

@@ -1,13 +1,13 @@
 ---
 type: decision
-title: Scenario sessions are isolated per actor and reset between scenarios
-description: One jar per actor keeps two personas from sharing a session; a browser reset keeps one scenario from leaving the next signed in as somebody else
+title: Scenario sessions are isolated per virtual user and reset between scenarios
+description: One jar per virtual user keeps two virtual users from sharing a session; a browser reset keeps one scenario from leaving the next signed in as somebody else
 tags: workflow
 ---
 
-# Scenario sessions are isolated per actor and reset between scenarios
+# Scenario sessions are isolated per virtual user and reset between scenarios
 
-`createCookieJar` in `scenario-cookie-jar.ts` holds its `Map` as a closure
+`createCookieJar` in `services/scenario-cookie-jar.ts` holds its `Map` as a closure
 local, so two jars can never share a session. That is precisely what lets one
 scenario sign in as several people without one of them inheriting another's
 session. Every response is read, not just the sign-in, so a cookie the target
@@ -22,11 +22,11 @@ without establishing a session. Anything needing to know whether a sign-in
 happened has to track the sign-in itself.
 
 The browser side has the same requirement. `ScenarioBrowserProvider.reset`
-discards every actor's per-scenario state — cookies, storage, open pages — while
+discards every virtual user's per-scenario state — cookies, storage, open pages — while
 keeping the browser, and is called between scenarios so one scenario cannot
 leave the next signed in as somebody else.
 
 **What this rules out:** hoisting the jar to a module-level or per-service map,
-sharing one jar across actors, reading `Set-Cookie` only from the sign-in
+sharing one jar across virtual users, reading `Set-Cookie` only from the sign-in
 response, treating `empty === false` as "signed in", or skipping `reset` between
 scenarios as an optimisation.

package/knowledge/decisions/security/workflow-scenario-steps-are-never-network-invocable.md

@@ -1,7 +1,7 @@
 ---
 type: decision
 title: A scenario step is never registered as a callable RPC and never dispatched on the queue
-description: A step drives a browser and holds an actor's session, so exposing it as an RPC would put that reach on the network
+description: A step drives a browser and holds a virtual user's session, so exposing it as an RPC would put that reach on the network
 tags: workflow
 ---
 
@@ -11,21 +11,21 @@ tags: workflow
 `RpcStepMeta` on purpose. A scenario step runs locally through `runPikkuFunc`
 and must never be treated as dispatchable on the queue or replay path, nor
 registered as a callable RPC — a browser-driving step must not be
-network-invocable. It executes with a browser handle and an actor's
+network-invocable. It executes with a browser handle and a virtual user's
 authenticated session in hand; exposed as an RPC it would hand a remote caller
 that reach.
 
 `PikkuScenarioService.scenarioStep` reflects this at runtime: it always runs
 through `engine.inlineStep` with `runPikkuFunc`, never through `rpcStep`, so no
 transport is involved. A step declaring `browser: true` is refused outright
-unless both a browser provider is registered and an actor was supplied, with an
+unless both a browser provider is registered and a virtual user was supplied, with an
 error saying which is missing.
 
 Scenario steps are also modelled as sessionless pikku functions (see
-`scenario-step.test.ts`) because a step is driven by an actor, not by a wire
+`scenario-step.test.ts`) because a step is driven by a virtual user, not by a wire
 session.
 
 **What this rules out:** collapsing `ScenarioStepMeta` into `RpcStepMeta`,
 registering step functions in the RPC map so they "can be tested directly",
 routing a scenario step through `rpcStep`/`dispatchStep`, or defaulting a
-`browser: true` step to run without an actor.
+`browser: true` step to run without a virtual user.

package/knowledge/decisions/security/{workflow-actor-steps-always-use-the-real-transport.md → workflow-virtual-user-steps-always-use-the-real-transport.md}

@@ -1,34 +1,34 @@
 ---
 type: decision
-title: A scenario actor step always goes over the real transport and never through internal dispatch
+title: A scenario virtual user step always goes over the real transport and never through internal dispatch
 description: Internal dispatch would bypass auth middleware and permissions, turning a scenario into a green health check that proves nothing
 tags: workflow
 ---
 
-# A scenario actor step always goes over the real transport and never through internal dispatch
+# A scenario virtual user step always goes over the real transport and never through internal dispatch
 
-When a workflow step carries `options.actor`, `rpcStep` in
-`pikku-workflow-service.ts` calls `actor.invoke(rpcName, data)` — the actor's
+When a workflow step carries `options.virtualUser`, `rpcStep` in
+`pikku-workflow-service.ts` calls `virtualUser.invoke(rpcName, data)` — the virtual user's
 authenticated client, over the real network transport — and never falls back to
 internal dispatch. Internal dispatch skips auth middleware and permission
 checks, so a scenario that "passed" that way would prove only that the function
-body runs, not that the persona is allowed to run it. That is a green health
+body runs, not that the virtual user is allowed to run it. That is a green health
 check for a system that may be wide open.
 
-For the same reason, actor steps never queue: `rpcStep` short-circuits
-`dispatchStep` to `false` whenever `options.actor` is set. An actor step is an
-outbound HTTP call made by the runner itself, and the actor's session lives in
+For the same reason, virtual user steps never queue: `rpcStep` short-circuits
+`dispatchStep` to `false` whenever `options.virtualUser` is set. A virtual user step is an
+outbound HTTP call made by the runner itself, and the virtual user's session lives in
 this process — a queued worker in another process would have no session to make
 it with. The step is still recorded durably like any RPC step, so replay and
 reporting are unaffected.
 
-Actor identity is process-local by nature. `PikkuScenarioService.runActors` maps
+Virtual user identity is process-local by nature. `PikkuScenarioService.runVirtualUsers` maps
 run id to live authenticated clients (cookie jars), and those ride that map
 only, never the persisted run wire — a serialized session on a durable run row
 would be a credential at rest.
 
 **What this rules out:** adding an "internal dispatch is faster" fast path for
-actor steps, routing an actor step through the queue, serializing actor sessions
-onto the run wire, or letting `actor.invoke` degrade to `rpcWithWire` when the
+virtual user steps, routing a virtual user step through the queue, serializing virtual user sessions
+onto the run wire, or letting `virtualUser.invoke` degrade to `rpcWithWire` when the
 transport is unavailable. Each turns an end-to-end authorization test into one
 that cannot fail.

package/knowledge/decisions/security/writing-a-virtual-user-schedule-is-gated-by-its-own-scope.md

@@ -0,0 +1,18 @@
+---
+type: decision
+title: Writing a virtual user schedule is gated by its own scope, separate from running one
+description: setVirtualUserSchedule carries virtualUser:schedule, because a schedule write spends money on every future tick while a run spends it once with a caller watching
+tags: core, cli, virtual-users, scopes, security
+---
+
+# Writing a virtual user schedule is gated by its own scope, separate from running one
+
+`packages/core/src/wirings/virtual-user/virtual-user-schedule-store.ts` defines the store that keeps a virtual user's cadence. Its SECURITY note says a written row "spends money on every future tick, without a caller present to see it happen", and that the scaffold therefore "gates writes behind a scope of their own" (`virtual-user-schedule-store.ts:60-63`). Reading findings is "a much smaller permission than deciding they should keep going" (`virtual-user-schedule-store.ts:62-63`).
+
+The gate is generated by the CLI. `packages/cli/src/functions/wirings/virtual-user/serialize-virtual-user-functions.ts` emits `setVirtualUserSchedule` with `scopes: ['virtualUser:schedule']` (line 456), with a comment saying a run "spends money once with a caller present to see it, while writing a schedule spends it repeatedly with nobody there". `listVirtualUserSchedules` needs only `virtualUser:read` (line 477). The tests assert the scope in `virtual-user-functions.test.ts:66`.
+
+A scheduled tick has no caller. It runs as the reserved `pikku-platform` principal, whose session carries only `virtualUser:run` (`packages/cli/src/functions/wirings/virtual-user/serialize-virtual-user-functions.ts:510-519`), so a tick can start a run and cannot write a schedule.
+
+The store's own design is related. `claim` is a compare-and-set on `nextRunAt`, so two processes on the same cron cannot both dispatch the same virtual user (`virtual-user-schedule-store.ts:78-91`). Its doc says a second dispatch would mean "the same user acting twice over, at twice the budget" (`virtual-user-schedule-store.ts:82-86`).
+
+**What this rules out:** letting a caller who can read runs also create or change a schedule, and treating a schedule write as the same permission as a run.

package/knowledge/index.md

@@ -19,8 +19,6 @@ meta files, the export surface. A note that repeats them is a copy that will
 drift.
 
 <!-- pikku:knowledge-index -->
-
 - [decisions](decisions/index.md) — a rule that was chosen, and what it rules out
 - [questions](questions/index.md) — something asked and not yet answered
-
 <!-- /pikku:knowledge-index -->

package/knowledge/questions/a-bearer-jwt-with-no-identity-becomes-a-session.md

@@ -0,0 +1,24 @@
+---
+type: question
+title: Does a bearer JWT with no identity claim count as a session?
+description: The cookie middleware refuses an identity-less JWT, but authBearer sets whatever decode returns, so the two paths disagree
+tags: core, auth, middleware
+---
+
+# Does a bearer JWT with no identity claim count as a session?
+
+`authCookie` (`packages/core/src/middleware/auth-cookie.ts`) only sets a session
+when `hasSessionIdentity` is true, meaning the decoded payload has a key that is
+not a registered JWT claim. Its test comment says a JWT of an absent session
+still decodes to a truthy `{ iat, exp }` that "the runner accepts", and it guards
+against that.
+
+`authBearer` (`packages/core/src/middleware/auth-bearer.ts`) has no such check.
+In JWT mode it calls `jwtService.decode(bearerToken)` and calls `setSession` on
+any truthy result. Its test only covers a `null` decode.
+
+What is asked: should a bearer token that decodes to `{ iat, exp }` alone be
+treated as anonymous, as the cookie path does, or as an authenticated session?
+Current behaviour: it becomes the request session. Whether a signed token of that
+shape can be minted is not checked in core, because the `JWTService`
+implementation is not in this package.

package/knowledge/questions/dev-quick-login-as-impersonation.md

@@ -0,0 +1,25 @@
+---
+type: question
+title: Can dev quick login become impersonation?
+description: Dev quick login signs in a fixed admin account; making it an impersonation step needs an existing admin session it does not have, so it would need a new bypass
+tags: auth, services
+---
+
+# Can dev quick login become impersonation?
+
+Today `/dev/quick-login` (`packages/services/better-auth/src/dev-quick-login.ts`)
+provisions a fixed `admin@pikku.dev` account with a fixed password and grants it
+the admin and console roots. It is refused outside loopback, behind a proxy, and
+in production.
+
+The proposal is that quick login should just be impersonation. Impersonation
+(`resolveImpersonatedSession`) only applies on top of an existing session, and
+the caller must hold `admin:impersonate`. Quick login has no session before it
+runs, so making it impersonation needs one of:
+
+- an unauthenticated dev-only route that accepts a user id, which is a new
+  bypass of the check that impersonation exists to keep, or
+- quick login keeps minting the dev admin session, and virtual users are
+  impersonated from there.
+
+The second keeps one mechanism for virtual users. Undecided.

package/knowledge/questions/does-a-delayed-rpc-run-as-the-session-it-was-scheduled-with.md

@@ -0,0 +1,26 @@
+---
+type: question
+title: Does a delayed RPC run as the session it was scheduled with?
+description: The in-memory scheduler stores the session it is given and returns it from getTask, but the delayed run invokes the RPC with no session
+tags: core, scheduler, sessions
+---
+
+# Does a delayed RPC run as the session it was scheduled with?
+
+The contract takes an optional session. `SchedulerService.scheduleRPC` in
+`packages/core/src/services/scheduler-service.ts:19-24` accepts `session`, and
+`ScheduledTaskInfo` exposes it (`:9-13`).
+
+The in-memory implementation in `packages/schedule/src/in-memory-scheduler-service.ts`
+accepts it (`:41-46`), stores it on the delayed task (`:85-92`), and returns it from
+`getTask` (`:107-118`). The timer callback runs `rpc.invoke(rpcName, data)` on a
+context built with an empty wire (`:69-75`). The session is not passed to that
+call, and the file does not read it on the run path.
+
+The comment at `:67-68` says the BullMQ and pg-boss schedulers enqueue
+`{ rpcName, data, session }` and invoke the RPC with it. This file does not do so.
+The caller in the workflow sleeper passes no session (`packages/core/src/wirings/workflow/pikku-workflow-service.ts:852-856`).
+
+**Question:** should a delayed RPC run under the session captured at scheduling
+time, as the comment describes for the other schedulers, or run with none? The
+code stores the session, reports it, and does not use it.

package/knowledge/questions/does-a-user-id-with-a-colon-read-another-users-credentials.md

@@ -0,0 +1,27 @@
+---
+type: question
+title: Can a user id containing a colon read another user's credentials?
+description: LocalCredentialService joins user id and name with a colon and matches users by prefix, so an id containing a colon may collide with another user's keys
+tags: core, credentials, local-dev, isolation
+---
+
+# Can a user id containing a colon read another user's credentials?
+
+`packages/core/src/services/local-credential-service.ts` stores each credential
+under the key `userId:name`, or just `name` when there is no user
+(`local-credential-service.ts:6-8`).
+
+`getAll(userId)` returns every key that starts with `${userId}:`, and strips that
+prefix to get the credential name (`local-credential-service.ts:31-39`). If one
+user's id contains a colon, its keys also start with the prefix of the id before
+the colon. For example, user `a` would list the key of user `a:b`, credential `c`
+(stored as `a:b:c`), under the name `b:c`.
+
+`getUsersWithCredential` (`local-credential-service.ts:42-51`) and `getAllUsers`
+(`local-credential-service.ts:53-62`) both split on the first colon, so they would
+report user `a:b` as `a`.
+
+Nothing in this file validates a user id. What is asked: can a user id contain a
+colon in practice? If it can, is a user with id `a` meant to see keys belonging
+to `a:b`? The code currently allows it, and no comment or test in this file says
+which is intended.

package/knowledge/questions/does-a-wirecli-command-need-a-session-by-default.md

@@ -0,0 +1,26 @@
+---
+type: question
+title: Does a wireCLI command need a session when it sets no auth?
+description: The channel default is documented as requiring a session, but a CLI command has no default of its own; its session need comes from whether the function is sessionless
+tags: core, cli, auth
+---
+
+# Does a wireCLI command need a session when it sets no auth?
+
+For channels, an absent `auth` requires a session. `packages/core/src/wirings/channel/channel.types.ts:67-76`
+and `packages/core/src/wirings/channel/channel-runner.ts:142` both say so.
+
+`wireCLI` in `packages/core/src/wirings/cli/cli-runner.ts` copies `auth` and
+`permissions` from the function (`:89-90`, `:105`). It merges a command-level
+`auth` onto the registration as `commandAuth ?? existing.auth` (`:176`, `:190`,
+`:201`). No default is set anywhere in that path.
+
+When the command runs, `runPikkuFunc` is called with `auth: false` (`:393-397`).
+In `packages/core/src/function/function-runner.ts:385-404`, a sessionless function
+requires a session only when the wiring or the function sets `auth: true` (`:386-392`).
+A function that is not sessionless always requires one and throws when there is none
+(`:401-403`). `auth: false` on such a function only logs a warning (`:396-400`).
+
+**Question:** should a CLI command with no `auth` require a session as a channel
+does? The code does not set that default for CLI commands. Whether a command needs
+one depends on whether the function is declared sessionless.

package/knowledge/questions/does-an-adversarial-in-scope-success-count-as-a-finding.md

@@ -0,0 +1,26 @@
+---
+type: question
+title: Does an adversarial user's in-scope success count as a finding?
+description: The disposition doc says a 2xx is a finding for an inverted oracle, but the engine only flags successes outside the virtual user's scopes, and in-scope 2xx depends on the app's classifier
+tags: core, virtual-user, authorization
+---
+
+# Does an adversarial user's in-scope success count as a finding?
+
+`dispositionProfile` in `packages/core/src/wirings/virtual-user/virtual-user-dispositions.ts`
+documents `invertedOracle` as meaning "a 2xx is a finding rather than a success".
+The comment on the field says the engine "flags the success and leaves ownership
+to the app's classifier".
+
+In `run-virtual-user.ts` the flag does one thing: at line 302 it drops the
+scope narrowing, so an adversarial user is offered the whole catalogue. The
+finding that fires on a 2xx is the `unexpected-success` check around lines
+627-645. It requires `response.ok` and a scope the virtual user does not hold. A
+2xx on an endpoint the virtual user is entitled to produces no engine finding. Only the
+app's `classify` hook can flag it, and that is the ownership check the comment
+describes.
+
+So the flag's name and doc describe a stronger oracle than the engine applies.
+What is asked: should `invertedOracle` make every 2xx a finding in the engine, as
+its doc says, or is the classifier meant to be the only place a 2xx becomes a
+finding, with the doc corrected?

package/knowledge/questions/does-approve-step-need-the-run-owners-session-or-the-gates-approvers.md

@@ -0,0 +1,34 @@
+---
+type: question
+title: Does approveStep need the run owner's session, as its doc says, or only what the gate's approvers policy allows?
+description: The WorkflowService doc says the session must belong to the run's owner, but the implementation judges the session against the gate's published policy, whose default is any
+tags: workflow, approvals, sessions, comment-vs-code
+---
+
+# Does approveStep need the run owner's session, as its doc says, or only what the gate's approvers policy allows?
+
+**The comment.** The doc on `approveStep` in `packages/core/src/services/workflow-service.ts` says: "The session
+must belong to the run's owner — see `assertWorkflowRunOwner`" (line 52). The method takes the session as
+optional (`session?: CoreUserSession`, lines 54-58).
+
+**The code.** `PikkuWorkflowService.approveStep` in `packages/core/src/wirings/workflow/pikku-workflow-service.ts`
+(lines 1804-1817) does not call `assertWorkflowRunOwner`. It passes `approvalDeciderFrom(session)` to
+`recordApprovalDecision`. That helper reduces the session to `{ userId, scopes }`, or `undefined` when there is
+no session (`packages/core/src/wirings/workflow/workflow-approval-policy.ts:21-24`).
+
+`recordApprovalDecision` (`packages/core/src/wirings/workflow/workflow-approval.ts:98-104`) judges the decider only
+when the gate has already published a policy (`workflow-approval.ts:125-141`). The policy check is
+`approvalPolicyRefusal`, which defaults `approvers` to `'any'` (`workflow-approval-policy.ts:46`, `:65-66`).
+Only `'owner'` compares the decider with the run's owner (`:47-54`), and it lets everyone through when the run
+has no recorded owner (`:48-50`). `'not-initiator'` refuses the owner (`:56-63`). A decision recorded before the
+gate publishes its policy is not judged at that point (`workflow-approval.ts:125`).
+
+The decision note
+[a workflow run is read by its owner, and answered by whoever its gate declares](../decisions/security/a-workflow-run-is-read-and-approved-by-its-owner.md)
+records the design as the gate's `approvers`. The comment at `workflow-service.ts:52` still describes the earlier
+rule that note says it replaced. The reference at `packages/core/src/wirings/workflow/workflow-run-ownership.ts:19`
+already points to `approvers`.
+
+**Question:** should the comment at `workflow-service.ts:52` be rewritten to describe the gate's policy, or is any
+caller meant to be held to the owner's session regardless of the policy? As the code stands, a gate with the
+default policy accepts an answer from no session at all.

package/knowledge/questions/does-cors-origin-true-reflect-any-origin-with-credentials.md

@@ -0,0 +1,20 @@
+---
+type: question
+title: Does cors origin: true reflect any origin when credentials are on?
+description: The credentials guard only refuses the wildcard origin, so origin: true with credentials reflects whichever origin asks
+tags: core, middleware, cors
+---
+
+# Does cors origin: true reflect any origin when credentials are on?
+
+In `packages/core/src/middleware/cors.ts:55-56`, `origin: true` sets the allowed
+origin to the request's `Origin` header, or to `*` when none is sent.
+
+The guard at `:36-40` throws only when the origin is the string `'*'` and
+`credentials` is true. `origin: true` is not that string, so the combination is
+accepted with no throw. The file does not check that the reflected origin is in a
+list.
+
+**Question:** is `origin: true` with `credentials: true` meant to reflect any caller
+origin, or should it be refused like the wildcard? The guard and its message cover
+only the wildcard. The `origin: true` option has no note in this folder.

package/knowledge/questions/does-skip-user-session-do-anything-on-a-channel.md

@@ -0,0 +1,24 @@
+---
+type: question
+title: Does skipUserSession do anything on a channel?
+description: The local channel runner accepts and forwards skipUserSession, but the channel open path never reads it, unlike the HTTP runner which refuses it on a session-requiring route
+tags: core, channel, http, sessions
+---
+
+# Does skipUserSession do anything on a channel?
+
+`runLocalChannel` in `packages/core/src/wirings/channel/local/local-channel-runner.ts`
+takes `skipUserSession = false` (`:66`) and passes it to `openChannel` (`:104`).
+
+`openChannel` in `packages/core/src/wirings/channel/channel-runner.ts:121-130` has
+`RunChannelOptions` in its parameter type, which includes `skipUserSession`
+(`channel.types.ts:31`). The function destructures only `route`,
+`coerceDataFromSchema` and `request`. A search of `packages/core/src` finds no
+read of the option in the channel code.
+
+The HTTP runner handles the same option differently. `packages/core/src/wirings/http/http-runner.ts:211-213`
+throws when `skipUserSession` is set on a route that requires a session.
+
+**Question:** on a channel that requires a session, is `skipUserSession: true`
+meant to be refused like the HTTP case, or is it intentionally ignored? The code
+accepts it and does nothing with it.

package/knowledge/questions/does-the-store-session-match-the-other-two.md

@@ -0,0 +1,19 @@
+---
+type: question
+title: Should betterAuthStoreSession warn about unhonoured impersonation?
+description: The cookie and stateless middlewares warn once when the impersonation header is ignored; the store middleware does not, and nothing says whether that is an omission
+tags: better-auth, impersonation, logging
+---
+
+# Should betterAuthStoreSession warn about unhonoured impersonation?
+
+`betterAuthSession` and `betterAuthStatelessSession` both call
+`warnImpersonationUnconfigured` when a request names a target and no
+`impersonation` option is set. `betterAuthStoreSession` does not.
+
+Without the warning, a store-backed app that forgets the option runs every
+scenario virtual user as the signed-in caller and fails only on assertions. The code gives
+no reason for the difference.
+
+Open: is the store middleware's silence an omission, or was it left out because
+it is used only for header-token traffic where impersonation is never wanted?

package/knowledge/questions/index.md

@@ -11,8 +11,31 @@ currently makes a choice that nobody has defended — the choice stays, the doub
 gets recorded.
 
 <!-- pikku:knowledge-index -->
-
+- [Does a bearer JWT with no identity claim count as a session?](a-bearer-jwt-with-no-identity-becomes-a-session.md) — The cookie middleware refuses an identity-less JWT, but authBearer sets whatever decode returns, so the two paths disagree
 - [A channel's middleware list accepts bare factories that nothing ever resolves](channel-middleware-accepts-bare-factories-that-nothing-resolves.md) — CoreChannel.channelMiddleware admits CorePikkuChannelMiddlewareFactory, but no runner calls one, so a bare factory would stall the chain
+- [Can dev quick login become impersonation?](dev-quick-login-as-impersonation.md) — Dev quick login signs in a fixed admin account; making it an impersonation step needs an existing admin session it does not have, so it would need a new bypass
+- [Does a delayed RPC run as the session it was scheduled with?](does-a-delayed-rpc-run-as-the-session-it-was-scheduled-with.md) — The in-memory scheduler stores the session it is given and returns it from getTask, but the delayed run invokes the RPC with no session
+- [Can a user id containing a colon read another user's credentials?](does-a-user-id-with-a-colon-read-another-users-credentials.md) — LocalCredentialService joins user id and name with a colon and matches users by prefix, so an id containing a colon may collide with another user's keys
+- [Does a wireCLI command need a session when it sets no auth?](does-a-wirecli-command-need-a-session-by-default.md) — The channel default is documented as requiring a session, but a CLI command has no default of its own; its session need comes from whether the function is sessionless
+- [Does an adversarial user's in-scope success count as a finding?](does-an-adversarial-in-scope-success-count-as-a-finding.md) — The disposition doc says a 2xx is a finding for an inverted oracle, but the engine only flags successes outside the virtual user's scopes, and in-scope 2xx depends on the app's classifier
+- [Does approveStep need the run owner's session, as its doc says, or only what the gate's approvers policy allows?](does-approve-step-need-the-run-owners-session-or-the-gates-approvers.md) — The WorkflowService doc says the session must belong to the run's owner, but the implementation judges the session against the gate's published policy, whose default is any
+- [Does cors origin: true reflect any origin when credentials are on?](does-cors-origin-true-reflect-any-origin-with-credentials.md) — The credentials guard only refuses the wildcard origin, so origin: true with credentials reflects whichever origin asks
+- [Does skipUserSession do anything on a channel?](does-skip-user-session-do-anything-on-a-channel.md) — The local channel runner accepts and forwards skipUserSession, but the channel open path never reads it, unlike the HTTP runner which refuses it on a session-requiring route
+- [Should betterAuthStoreSession warn about unhonoured impersonation?](does-the-store-session-match-the-other-two.md) — The cookie and stateless middlewares warn once when the impersonation header is ignored; the store middleware does not, and nothing says whether that is an omission
+- [Is the agent score worker reachable without a session?](is-the-agent-score-worker-reachable-without-a-session.md) — The score worker is registered as sessionless with the helper function type, and this file wires no route or expose for it
+- [May a scheduled test on live change data?](live-scheduled-tests-may-write.md) — Scheduled runs against a live app may only read, or may write with an explicit per-schedule approval; the choice is not made
+- [Who calls provisionVirtualUsers?](provision-virtual-users-has-no-caller-in-this-repo.md) — provisionVirtualUsers is additive and can ban orphans, but no caller exists in this repo outside tests and skill docs, and the route its doc comment names no longer exists
+- [Does a non-remote request need a remote token once the secret is set?](remote-secret-refuses-requests-without-a-remote-token-on-every-path.md) — With PIKKU_REMOTE_SECRET set, pikkuRemoteAuthMiddleware refuses any request lacking a Bearer header, not only /remote/rpc paths; the no-secret branch is path-scoped
+- [Should a session set by middleware be persisted and re-issued like a function's?](should-a-middleware-set-session-persist-to-the-store.md) — Middleware setSession calls setInitial, which marks no change and writes no store entry, while a function's setSession does both; the reason is not recorded
+- [Should a scoped secret view throw from hasSecret for a disallowed key?](should-a-scoped-secret-view-throw-from-has-secret-for-a-disallowed-key.md) — The SecretService contract says hasSecret answers for any key and must not throw, but the scoped view throws for keys outside its set
+- [Should a Bearer token that does not verify be anonymous or refused?](should-a-wrong-bearer-token-be-anonymous-or-refused.md) — authBearer refuses a malformed scheme with InvalidSessionError but lets a well-formed wrong token through as anonymous, and no comment says why
+- [Should an outgoing webhook go out unsigned when its configured signing secret resolves empty?](should-an-empty-webhook-signing-secret-send-unsigned.md) — When config.webhook.secret names a secret that resolves to nothing, the delivery is logged as unsigned and enqueued without a signature
+- [Should HTTP virtual user sessions reset between scenarios in one CLI run?](should-http-virtual-user-sessions-reset-between-scenarios-in-one-run.md) — The CLI builds HTTP virtual users once and reuses them for every scenario, and only the browser side is reset between scenarios
+- [Should the scenario cookie jar scope cookies to the API origin?](should-the-cookie-jar-scope-cookies-to-the-api-origin.md) — 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
+- [Should voiceInput fetch audio URLs when no host allowlist is configured?](should-voice-input-fetch-audio-urls-without-a-host-allowlist.md) — With no allowedAudioHosts, the audio URL is fetched through safeFetch with no allowlist, so any public host is reachable
+- [What rules govern impersonation on staging and live?](staging-impersonation-rules.md) — Staged impersonation by a signed-in admin is wanted; the switch, read-only default, expiry and logging rules are proposed but not agreed
 - [An unauthorized channel reply is sent outside the channel's declared Out type](unauthorized-channel-replies-escape-the-declared-out-type.md) — processMessageHandlers sends a bare string on auth failure, which no generated client type admits — nobody has decided what the typed shape should be
-
+- [Pikku Studio Cloud has to create, hold and deliver the stage virtual user keys](virtual-user-keys-on-cloud-stages-are-pikku-studios-to-build.md) — 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
+- [A virtual user statement can be replayed once per instance](virtual-user-statement-replay-is-per-process.md) — The one-time id store is an in-memory map, so on several instances or Worker isolates each accepts a statement once
+- [What should an impersonated session carry?](what-an-impersonated-session-carries.md) — 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
 <!-- /pikku:knowledge-index -->

package/knowledge/questions/is-the-agent-score-worker-reachable-without-a-session.md

@@ -0,0 +1,21 @@
+---
+type: question
+title: Is the agent score worker reachable without a session?
+description: The score worker is registered as sessionless with the helper function type, and this file wires no route or expose for it
+tags: core, agent, scorer, security
+---
+
+# Is the agent score worker reachable without a session?
+
+`packages/core/src/wirings/agent-scorer/agent-scorer-worker.ts:44-56` registers the
+worker `pikkuAgentScoreWorker` with `sessionless: true` and `functionType: 'helper'`.
+The file adds no HTTP or RPC wiring and no `expose` for it.
+
+Core's meta type lists `'helper'` as one of the function types (`packages/core/src/function/function-meta.types.ts:147`).
+The scenario coverage code skips non-user functions (`packages/core/src/wirings/workflow/scenario-coverage.ts:195`).
+I did not trace whether a helper is routed over RPC or HTTP, or what gates a
+sessionless function on those routes.
+
+**Question:** should the score worker be reachable from outside the process without
+a session, and is `helper` what keeps it off the public surface? That is not
+settled by this file.

package/knowledge/questions/live-scheduled-tests-may-write.md

@@ -0,0 +1,19 @@
+---
+type: question
+title: May a scheduled test on live change data?
+description: Scheduled runs against a live app may only read, or may write with an explicit per-schedule approval; the choice is not made
+tags: workflow, services
+---
+
+# May a scheduled test on live change data?
+
+A scheduled test runs in a live app as a test account that has the same access as
+a real role, so it can change real data. Options proposed, none chosen:
+- read-only by default, with writes allowed only by an explicit approval recorded
+  on each schedule;
+- writes allowed on schedules the admin marks as writing, with a warning shown
+  before saving;
+- no writes on live at all, with the same tests run only on staging.
+
+The answer also decides what the failure notice must say when a write test stops
+partway.

package/knowledge/questions/provision-virtual-users-has-no-caller-in-this-repo.md

@@ -0,0 +1,23 @@
+---
+type: question
+title: Who calls provisionVirtualUsers?
+description: provisionVirtualUsers is additive and can ban orphans, but no caller exists in this repo outside tests and skill docs, and the route its doc comment names no longer exists
+tags: better-auth, virtual-users, provisioning
+---
+
+# Who calls provisionVirtualUsers?
+
+`provisionVirtualUsers` (`packages/services/better-auth/src/provision-virtual-users.ts`)
+creates virtual user accounts, grants their roles, and handles orphans. Orphans
+are reported by default, or banned when `orphans: 'ban'` is set and the ban
+plugin exists. It never deletes or revokes.
+
+A search of this repo finds callers only in tests and skill documentation. Its
+doc comment says it is meant to be called by an operator sign-in route on a
+handshake that names an unknown address, but that operator sign-in was removed
+when virtual user callers moved to signed statements, so the comment names a
+caller that does not exist.
+
+Open: which deployment path runs it now, and when? Until that is known, the
+orphan policy and the refusal rules (a real, non-virtual-user account at a
+virtual user's email throws) are untested in production.

package/knowledge/questions/remote-secret-refuses-requests-without-a-remote-token-on-every-path.md

@@ -0,0 +1,32 @@
+---
+type: question
+title: Does a non-remote request need a remote token once the secret is set?
+description: With PIKKU_REMOTE_SECRET set, pikkuRemoteAuthMiddleware refuses any request lacking a Bearer header, not only /remote/rpc paths; the no-secret branch is path-scoped
+tags: core, auth, remote, middleware
+---
+
+# Does a non-remote request need a remote token once the secret is set?
+
+`pikkuRemoteAuthMiddleware` (`packages/core/src/middleware/remote-auth.ts`) has
+two branches. With no secret, only a path under `/remote/rpc/` is refused, and
+the test "requires authorization for a case-varied remote path when no secret is
+set" pins that. With the secret set, the code reaches
+`if (!authHeader) throw new UnauthorizedError()` for every path, because that
+check is not gated by `isRemoteRpcPath`.
+
+So once the secret is configured, a request to any route the middleware sees and
+that carries no Bearer header is refused. The tests in `remote-auth.test.ts`
+only use `/remote/rpc` paths with the secret set, so they do not show whether
+this is meant.
+
+Mounting, checked: in this repo nothing in a template or example mounts
+`pikkuRemoteAuthMiddleware`. The Pikku Studio Cloud app, which lives outside this
+repo, mounts it as wire middleware on one route only, `POST /remote/rpc/:rpcName`,
+not globally. So for that app the question above does not arise, because the
+middleware never sees its ordinary routes. The question stands for any app that mounts the middleware globally, which
+this repo does not show.
+
+What is asked: should a deployment that sets `PIKKU_REMOTE_SECRET` refuse its
+ordinary public routes as well, or should the secret branch be path-scoped the
+way the no-secret branch is? The code does not say which the app expects, and
+how the app mounts the middleware is outside this package.

package/knowledge/questions/should-a-middleware-set-session-persist-to-the-store.md

@@ -0,0 +1,25 @@
+---
+type: question
+title: Should a session set by middleware be persisted and re-issued like a function's?
+description: Middleware setSession calls setInitial, which marks no change and writes no store entry, while a function's setSession does both; the reason is not recorded
+tags: core, auth, session
+---
+
+# Should a session set by middleware be persisted and re-issued like a function's?
+
+Two wire helpers in `packages/core/src/services/user-session-service.ts` set the
+session differently. `createMiddlewareSessionWireProps` and the HTTP runner's
+middleware wire (`packages/core/src/wirings/http/http-runner.ts`) bind
+`setSession` to `setInitial`. That sets the session without marking
+`sessionChanged` and without calling the session store. `createFunctionSessionWireProps`
+binds `setSession` to `set`, which marks the change and writes the store.
+
+The effect is that a session established by `authBearer`, `authAPIKey` or
+`authCookie` is never written to the store and never triggers a cookie
+re-issue in `authCookie`, which checks `hasSessionChanged`. A function that calls
+`setSession` does both. The naming suggests the middleware path is meant to
+describe the request's starting session, but no comment, test or note says so.
+
+What is asked: is it intended that a middleware-authenticated session stays
+request-scoped, or should middleware-set sessions reach the store like function-set
+ones?

package/knowledge/questions/should-a-scoped-secret-view-throw-from-has-secret-for-a-disallowed-key.md

@@ -0,0 +1,23 @@
+---
+type: question
+title: Should a scoped secret view throw from hasSecret for a disallowed key?
+description: The SecretService contract says hasSecret answers for any key and must not throw, but the scoped view throws for keys outside its set
+tags: core, secrets, scoping
+---
+
+# Should a scoped secret view throw from hasSecret for a disallowed key?
+
+The `SecretService` interface in `packages/core/src/services/secret-service.ts:13-14`
+says `hasSecret` "answers for any key, including a disallowed one — it must not
+throw."
+
+`ScopedSecretService.hasSecret` in `packages/core/src/services/scoped-secret-service.ts:21-24`
+calls `assertAllowed` first, and that throws `Access denied to secret key` for a key
+outside the view's set (`:10-14`).
+
+The note `a-scoped-secret-view-reads-only-declared-keys-and-never-writes.md` records
+that the view's `hasSecret` throws, and treats that as intended.
+
+**Question:** which governs? The view's throw follows its read rule. The contract
+says an existence check must not throw for any key. The two cannot both hold for a
+disallowed key.