@pikku/core 0.12.141 → 0.12.143

package/knowledge/decisions/security/oss-auth-works-without-pikku-studio-cloud.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: Open-source auth works without Pikku Studio Cloud
+description: Every virtual-user sign-in path works in an app that runs no Pikku Studio Cloud code; the signing key is the project's own, never a cloud-issued credential
+tags: services, auth
+---
+
+# Open-source auth works without Pikku Studio Cloud
+
+Virtual users and staged impersonation must all work in an open-source app with
+no Pikku Studio Cloud service and no cloud-issued token. The cloud may add its
+own way in, but nothing in core, the CLI or the better-auth service may require
+it.
+
+The code holds to this. A virtual user signs in either in-process
+(`inProcessSignIn`, no credential at all) or with a signed statement
+(`statementSignIn`), both in `packages/core/src/services/virtual-user-sign-in.ts`.
+The statement is signed with an Ed25519 key the project owns:
+`packages/cli/src/utils/virtual-user-signer.ts` generates it for `pikku dev`, or
+reads `VIRTUAL_USER_SIGNING_KEY` from whoever deploys the stage. The app is given
+only the public half, as `VIRTUAL_USER_VERIFY_KEY`
+(`packages/services/better-auth/src/virtual-user-plugin.ts`).
+
+**What this rules out:** any design where Pikku Studio Cloud is the issuer of the
+credential a virtual user presents. A signer that only exists in the cloud cannot
+be the basis for an open-source feature.

package/knowledge/decisions/security/outbound-webhooks-use-an-allowlist-when-configured.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: Outbound webhooks use an allowlist when one is configured, and block private hosts otherwise
+description: The webhook delivery reads allowedHosts from config and passes it to safeFetch; without an allowlist safeFetch refuses private hosts, and an allowlist replaces that check
+tags: core, webhooks, ssrf, security
+---
+
+# Outbound webhooks use an allowlist when one is configured, and block private hosts otherwise
+
+`WebhookServiceConfig.allowedHosts` in `packages/core/src/services/webhook-service.ts:33-44`
+says that when it is set only those hostnames may be delivered to, and when it is
+omitted private and internal hosts are blocked.
+
+`queue-webhook-service.ts:104-110` reads it from `config.webhook`, and falls back
+to no allowlist if the singletons are not initialised. The value is passed to
+`safeFetch` (`:112-122`).
+
+In `packages/core/src/utils/safe-fetch.ts:265-273`, an allowlist makes the check an
+exact hostname match, and the private-host refusal is in the `else` branch that only
+runs without an allowlist. So with an allowlist, a listed host is not refused for
+being private.
+
+**What this rules out:** delivering to a host outside a configured allowlist, and
+delivering to a private host when no allowlist is configured.

package/knowledge/decisions/security/pikku-carries-virtual-user-scopes-as-data-and-the-app-grants-them.md

@@ -0,0 +1,35 @@
+---
+type: decision
+title: Core carries virtual user roles as data and provisioning grants them
+description: roles on a resolved virtual user are transported by core, never applied there — provisionVirtualUsers grants them in the running stage, through the scope service the app wired
+tags: services
+---
+
+# Core carries virtual user roles as data and provisioning grants them
+
+A virtual user's `roles` (and the `app` it signs into) are declared in
+`defineVirtualUsers` and carried on `ResolvedVirtualUser`
+(`packages/core/src/services/virtual-users-service.ts`) into the generated
+`virtualUserConfigs`. Nothing in core reads them to grant anything:
+`createHttpVirtualUsers` (`packages/core/src/services/http-virtual-users.ts`) only
+signs the virtual user in.
+
+The grant is performed by `provisionVirtualUsers`
+(`packages/services/better-auth/src/provision-virtual-users.ts`), which runs in the
+stage itself and calls `addUserToRole` / `addScopeToUser` on the `scopeService` the
+app passes in. Its doc comment says it is additive — it creates and grants, never
+deletes or revokes — and that it throws rather than grant a virtual user's roles to
+an address a real user already holds.
+
+Core cannot do the granting: which scope store exists, whether roles have been
+created, and what a role means are all the application's own. Worse, a framework
+that granted scopes from wherever it was handed a virtual user would be a framework
+that can escalate privileges as a side effect of signing in. Keeping the fields
+inert in core makes the grant an act performed deliberately, against a store the
+app wired.
+
+**What this rules out:** teaching `createHttpVirtualUsers` (or any core service)
+to call `ScopeService.addScopeToUser` / `addUserToRole` from these fields, and
+treating a role listed on a virtual user declaration as evidence that the account
+holds it. That evidence comes from reading the roles back
+([a virtual user whose roles drift from the declaration refuses to run](a-virtual-user-whose-roles-drift-from-the-declaration-refuses-to-run.md)).

package/knowledge/decisions/security/scoped-content-access-is-a-root-folder-with-longest-prefix-grants.md

@@ -0,0 +1,31 @@
+---
+type: decision
+title: Scoped content access is confined to a root folder, with longest-prefix grants outside it
+description: ScopedContentService keeps an addon inside its root folder, lets it reach the wider store only through read or write grants matched by longest prefix, and refuses signURL and copyFile
+tags: core, content, scoping, paths
+---
+
+# Scoped content access is confined to a root folder, with longest-prefix grants outside it
+
+`packages/core/src/services/scoped-content-service.ts` narrows a `ContentService`
+to one folder. The doc comment describes the rule (`scoped-content-service.ts:57-67`).
+
+Paths are normalised first (`scoped-content-service.ts:39-49`). Each value is
+decoded up to four times (`scoped-content-service.ts:16`, `25-35`). A null byte,
+a leading `/` or `\`, or a `.` or `..` segment in any pass is refused
+(`scoped-content-service.ts:40-46`).
+
+A bucket that does not start with `@` is placed under the root
+(`scoped-content-service.ts:105-109`). A bucket that starts with `@` names a path
+from the store root. It is allowed if it sits under the root
+(`scoped-content-service.ts:113`). Otherwise the grants are checked, sorted
+longest prefix first (`scoped-content-service.ts:79-88`), and the first match
+decides (`scoped-content-service.ts:114-117`). A write needs a `write` grant
+(`scoped-content-service.ts:115`).
+
+`signURL` and `copyFile` throw unconditionally (`scoped-content-service.ts:126-128`,
+`145-147`). The doc comment says both take a finished URL or a local path, "so
+neither can be narrowed to a folder" (`scoped-content-service.ts:64-66`).
+
+**What this rules out:** traversal, including encoded traversal, out of the root,
+signed URLs for content outside the root, and copies that name arbitrary paths.

package/knowledge/decisions/security/services-without-secrets-get-a-throwing-secrets-accessor.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: Contexts that must not hold secrets get a services bag whose secrets accessor throws
+description: withoutSecrets replaces the secrets entry with a non-enumerable getter that throws, so code outside the permitted contexts cannot reach the secret service
+tags: core, secrets, services
+---
+
+# Contexts that must not hold secrets get a services bag whose secrets accessor throws
+
+`packages/core/src/services/secretless.ts` exports `withoutSecrets`. If the
+services object has no `secrets` key, it is returned unchanged
+(`secretless.ts:17-19`). Otherwise a shallow copy is made, and `secrets` is
+redefined as a getter that throws `SecretAccessDeniedError`
+(`secretless.ts:20-27`). The property is non-enumerable and configurable
+(`secretless.ts:25-26`), so a spread of the object does not copy it.
+
+The error message says `secrets` is confined to `pikkuServices`,
+`pikkuWireServices`, addon service factories and middleware, and tells the caller
+to give the service the secret at construction time instead (`secretless.ts:6`).
+
+**What this rules out:** reading `services.secrets` from a context that is not on
+that list, and a secret leaking through a copy of the services object.

package/knowledge/decisions/security/shared-guards-refuse-to-mutate-or-shadow-a-system-role.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: Shared guards refuse to mutate or shadow a system role, in every store
+description: system-role-guard holds the guards every ScopeService must call before changing a role, and roleLockReason gives the console a reason to show for a locked role
+tags: core, roles, scopes, guards
+---
+
+# Shared guards refuse to mutate or shadow a system role, in every store
+
+`packages/core/src/services/system-role-guard.ts` is the shared guard that a
+`ScopeService` implementation must apply before it mutates a role. The doc
+comment says the rule is "a contract, not a policy", because a store that lets
+the console delete a declared role makes virtual user and scenario checks stop testing
+what they claim to (`system-role-guard.ts:7-15`).
+
+- `assertRoleIsMutable` throws `SystemRoleImmutableError` when the name is a
+  system role (`system-role-guard.ts:27-35`). The caller names the operation in
+  the message.
+- `assertRoleNameAvailable` throws `SystemRoleShadowedError` when a new custom
+  role would take a declared name (`system-role-guard.ts:40-47`).
+- `isSystemRole` is passed in, so an implementation can answer from a column, a
+  cache or a query (`system-role-guard.ts:17-18`, `20`).
+
+`roleLockReason` (`system-role-guard.ts:56-71`) returns a reason string for a
+system role, or `null` when it is editable. A role whose declaration was removed
+gets a message that says it is inert and points to `pikku roles prune`
+(`system-role-guard.ts:60-66`). The doc comment says a reason is shown "instead
+of a disabled button with no explanation" (`system-role-guard.ts:52-54`).
+
+Sibling note: [system roles are synced additively and cannot be deleted or
+rewritten](system-roles-are-additive-and-immutable.md).
+
+**What this rules out:** a store deleting, re-scoping or shadowing a declared
+role, and a locked role shown without a reason.

package/knowledge/decisions/security/signed-uploads-are-verified-by-the-same-check-as-signed-reads.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: Signed uploads are verified by the same check as signed reads
+description: The local content handler refuses an upload whose presigned URL does not verify, using the same exported verifier that signed reads use
+tags: core, content, security
+---
+
+# Signed uploads are verified by the same check as signed reads
+
+`verifySignedContentRequest` in
+`packages/core/src/services/local-content-request-handler.ts:60-72` is the one
+function that decides whether a signed read or a signed upload is genuine. It is
+exported so every runtime that serves content verifies the same way.
+
+The handler's `validateSignedAssetRequest` wraps it (`:146-149`).
+`handleUpload` calls that wrapper before writing anything and returns the failure
+response when the check does not pass (`:157-169`). The comment at `:162-165`
+gives the reason: without the check, an unauthenticated PUT could write to any
+key under the content root.
+
+The existing note `signed-content-urls-bind-the-request-path.md` covers the read
+side and the node server verifier; this note covers the upload path in the core
+handler.
+
+**What this rules out:** writing an upload key before its signed URL has verified,
+and a separate upload check that could drift from the read check.

package/knowledge/decisions/security/system-role-scopes-must-be-declared-with-define-scope.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: System role scopes must be declared with defineScope, or the build fails
+description: A system role may grant only scope ids that defineScope declares, and the bare wildcard is refused; both are critical inspector diagnostics, so a role cannot grant a scope no function checks
+tags: core, roles, scopes, inspector
+---
+
+# System role scopes must be declared with defineScope, or the build fails
+
+The type doc on `CoreSystemRole.scopes` says every id a role grants "must be declared with `defineScope` — the inspector fails the build otherwise, so a role cannot quietly grant a scope that no function checks" (`packages/core/src/wirings/role/role.types.ts:15-19`).
+
+The check is `validateSystemRoleScopes` in `packages/inspector/src/utils/post-process.ts:1745-1775`. It walks every `state.systemRoles.definitions` entry and each of its scopes:
+
+- The bare `*` is reported as critical and skipped (`post-process.ts:1757-1763`).
+- A trailing `:*` is stripped before the lookup (`post-process.ts:1765`), so `admin:*` needs `admin` to be declared.
+- Any other scope missing from the set built from `state.scopes.definitions` is reported as critical, with the list of available scopes (`post-process.ts:1766-1771`).
+
+It runs from the validation pass in `packages/inspector/src/inspector.ts:580-581`, straight after `applyDeclaredScopes` and `validateScopeReferences`.
+
+Critical diagnostics are what block the build by default. The `diagnostic` doc in `packages/inspector/src/types.ts:400-403` says `error` and `warn` block only under `--fail-on-error` / `--fail-on-warn`, with the default at critical only.
+
+The literal-array and unqualified-name rules for `defineSystemRole` are a separate check, covered in [System roles must declare literal, unqualified scopes](../../../../inspector/knowledge/decisions/system-roles-declare-literal-unqualified-scopes.md). The runtime side, where a synced role can only add grants, is in [System roles are synced additively and cannot be deleted or rewritten](system-roles-are-additive-and-immutable.md).
+
+**What this rules out:** a system role that grants a scope no `defineScope` declares, which no function would ever check. It also rules out a role granting bare `*`, which would hide what the role confers. Neither is a warning to tolerate; both stop the build.

package/knowledge/decisions/security/system-roles-are-additive-and-immutable.md

@@ -0,0 +1,16 @@
+---
+type: decision
+title: System roles are never deleted by a deploy, but their scope set follows the declaration, and the admin API cannot change them
+description: syncSystemRoles keeps a role row whose declaration has gone (marked declared false) but replaces a declared role's scope set; deleteRole and setRoleScopes refuse system roles
+tags: core, scopes, roles
+---
+
+# System roles are never deleted by a deploy, but their scope set follows the declaration, and the admin API cannot change them
+
+`syncSystemRoles` is documented in `packages/core/src/services/scope-service.ts:36-47`. It is additive for the **role row**: a role whose `defineSystemRole` declaration has gone is left in place and marked `declared: false`, so a rollback or a rolling deploy cannot strip everyone's grant.
+
+It is **not** additive for the role's **scopes**. The same comment says "A role's scope set *is* re-synced, because that is the declaration's whole content" (`scope-service.ts:41-43`). The Kysely implementation does this by deleting the role's `pikkuRoleScopes` rows and inserting the declared ones inside one transaction (`packages/services/kysely/src/kysely-scope-service.ts:136-145`). A deploy that stops declaring a scope therefore removes it from that role. Only system rows are marked stale (`kysely-scope-service.ts:148-160`).
+
+`deleteRole` and `setRoleScopes` throw `SystemRoleImmutableError` for a system role. Changing a system role's grants is therefore a code change plus a deploy, not an admin action at runtime. Scope sync itself (`syncScopes`) never deletes; see [scope resolution](scope-resolution-happens-at-the-session-boundary-and-sync-never-deletes.md).
+
+**What this rules out:** an admin editing or deleting a system role through the normal role API, and a deploy deleting a system role row. It does not rule out a deploy removing a scope from a declared role. That is how a role's meaning is changed.

package/knowledge/decisions/security/the-channel-rpc-does-not-send-the-callers-session.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: The channel RPC does not put the caller's session on the wire
+description: ChannelDeploymentService.invoke accepts a session only to satisfy the DeploymentService shape and never sends it, so the peer runs the capability as itself
+tags: core, channel, rpc, security
+---
+
+# The channel RPC does not put the caller's session on the wire
+
+The doc comment on `ChannelDeploymentService.invoke` in
+`packages/core/src/wirings/channel/channel-rpc-service.ts:55-60` says `session`
+is accepted to satisfy `DeploymentService` and is deliberately not sent. The peer
+runs the capability as itself, on its own machine, and a session on the wire
+would carry the caller's credentials while authorising nothing.
+
+The signature takes the value as `_session?: unknown` (`:61-65`). The request
+sent on the channel carries `action`, `id`, `funcName`, `data` and `traceId` (`:88-94`), and
+the file does not refer to the session elsewhere in `invoke`.
+
+**What this rules out:** forwarding the caller's session to a channel peer, and
+treating a session on this path as an authorisation the peer will honour.

package/knowledge/decisions/security/the-remote-jobs-inbox-fails-closed-without-a-secret.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: The remote jobs inbox rejects every caller when its secret is unset
+description: remoteJobsSecret refuses all requests when the dispatch secret variable is empty, and compares the header in constant time when it is set
+tags: core, remote-jobs, secrets, middleware
+---
+
+# The remote jobs inbox rejects every caller when its secret is unset
+
+`packages/core/src/middleware/remote-jobs-secret.ts` guards the remote job inbox.
+The doc comment says it "fails closed: an unset secret rejects every caller, so
+the routes are never open just because the deployment forgot to configure one"
+(`remote-jobs-secret.ts:18-21`).
+
+The check rejects when any of three things is true (`remote-jobs-secret.ts:26-31`):
+the expected value is empty, the provided header is not a string, or the two
+values differ. All three throw `UnauthorizedError` (`remote-jobs-secret.ts:31`).
+
+The comparison is `constantTimeEqual` (`remote-jobs-secret.ts:8-15`), which XORs
+each character code and accumulates the result. It returns early on a length
+mismatch (`remote-jobs-secret.ts:9`), so the length of the secret is not hidden.
+
+**What this rules out:** an open inbox on a deployment that has not set the
+secret, and a plain `===` comparison of the secret.

package/knowledge/decisions/security/the-remote-rpc-gate-fails-closed-and-binds-the-token-to-its-function.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: The remote RPC gate fails closed and binds a token to one function
+description: pikkuRemoteAuthMiddleware refuses a remote-RPC request unless the mesh token is audience pikku-remote, names the requested function, and carries a session that decrypts under the mesh secret
+tags: core, auth, remote
+---
+
+# The remote RPC gate fails closed and binds a token to one function
+
+`pikkuRemoteAuthMiddleware` (`packages/core/src/middleware/remote-auth.ts`)
+guards the receiving end of a mesh call, which `buildRemoteHeaders`
+(`packages/core/src/remote.ts`) signs from the caller side. Where the code and
+its tests state a rule:
+
+- With no `PIKKU_REMOTE_SECRET`, a request whose path is under `/remote/rpc/` is
+  refused. The path check is case-insensitive, and the test
+  "requires authorization for a case-varied remote path when no secret is set"
+  says why.
+- With the secret set but no JWT service, the middleware throws rather than
+  passing the request on.
+- A missing header, a scheme other than `Bearer`, a token that fails to decode,
+  or an audience other than `pikku-remote` is `UnauthorizedError`.
+- A token carrying `fn` is only accepted for the function it names on a remote
+  path. The test "should skip fn check for non-RPC paths even if fn in token"
+  confirms the binding is about the RPC surface.
+- The session claim is decrypted under `PIKKU_REMOTE_SECRET` with
+  `REMOTE_SESSION_INFO`, which `buildRemoteHeaders` encrypts. A decryption
+  failure is `UnauthorizedError`, so a session is never read as plain claims.
+
+**What this rules out:** accepting a mesh token with the wrong audience, reusing
+a token minted for one function on another RPC path, and reading the session
+claim without decrypting it. The gap for requests outside `/remote/rpc/` once the
+secret is set is recorded in
+[Does a non-remote request need a remote token once the secret is set?](../../questions/remote-secret-refuses-requests-without-a-remote-token-on-every-path.md).

package/knowledge/decisions/security/the-workflow-status-stream-rechecks-ownership-on-every-poll.md

@@ -0,0 +1,16 @@
+---
+type: decision
+title: The workflow status stream re-checks run ownership on every poll and closes when access is lost
+description: streamWorkflowRunStatus asserts the run owner on each poll rather than once when the stream opens, and closes the channel when that check throws
+tags: core, workflow, security, streaming
+---
+
+# The workflow status stream re-checks run ownership on every poll and closes when access is lost
+
+`streamWorkflowRunStatus` defines `poll`, which reads the run and calls `assertWorkflowRunOwner(run.wire, session)` on every read (`packages/core/src/wirings/workflow/workflow-status-stream.ts:63-72`). The comment says ownership is read from the run itself, so a stream that outlives its session should stop rather than keep reporting (`:69-71`).
+
+The polling loop runs inside a `try` (`:142`). A throw from any poll, including the ownership refusal, runs `channel.close()` and rethrows (`:159-161`). The comment at `:139-141` names this case.
+
+`assertWorkflowRunOwner` is in `packages/core/src/wirings/workflow/workflow-run-ownership.ts:26-36`. It returns when the run has no recorded owner, and throws `WorkflowRunForbiddenError` when the session's `userId` does not match the owner (`:26-35`).
+
+**What this rules out:** checking ownership only when the stream opens, and leaving a stream open after its ownership check throws.

package/knowledge/decisions/security/two-credentials-on-one-key-must-share-a-read-mode.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: Two credentials resolving to one key must agree on whether they are per-user or singleton
+description: buildCredentialResolutions throws when two credentials resolve to the same stored key but would be read in different modes, so one cannot silently serve the other's value
+tags: core, credentials, overrides, wire
+---
+
+# Two credentials resolving to one key must agree on whether they are per-user or singleton
+
+`packages/core/src/wirings/credential/credential-overrides.ts` decides, for each
+credential the package declares, where its value is read from.
+
+An override is either a string, which renames the credential, or an object with a
+`name` and a `mode` (`credential-overrides.ts:9-16`). The doc comment says the
+object form "decides where its value is read from", so one addon can serve a
+per-user product and a team account (`credential-overrides.ts:5-7`).
+
+For each name, the resolved key is the override's name or the name itself
+(`credential-overrides.ts:56-57`). The mode is the override's `mode`, or else the
+type the author declared (`credential-overrides.ts:59-63`). A credential with no
+override keeps its declared type (`credential-overrides.ts:38-40`).
+
+If a key is already claimed with a different mode, the function throws
+(`credential-overrides.ts:65-74`). The message says the loser "would silently read
+the other's value — a per-user credential served from the deployment's own account,
+or the reverse" (`credential-overrides.ts:70-72`).
+
+**What this rules out:** a per-user credential and a deployment credential sharing
+one stored key, with one quietly serving the other.

package/knowledge/decisions/security/verified-bearer-claims-are-pass-through-data-that-core-never-fills.md

@@ -0,0 +1,23 @@
+---
+type: decision
+title: Verified bearer claims are pass-through data that core never fills
+description: PikkuHTTP.authInfo is a typed slot for claims a host has already verified; core declares it and no core source assigns it from request headers
+tags: core, http, auth
+---
+
+# Verified bearer claims are pass-through data that core never fills
+
+The doc comment on `PikkuHTTPAuthInfo` in `packages/core/src/wirings/http/http.types.ts:67-74`
+says the claims are strictly pass-through: nothing in pikku derives them from a
+request's headers, because verifying a token is the host's job. The field carries
+what the raw `Authorization` header cannot: the scopes and client the token was
+issued for.
+
+The interface is at `http.types.ts:79-88`, and `authInfo?: PikkuHTTPAuthInfo` is on
+`PikkuHTTP` at `:94`. A search of `packages/core/src` finds only the type and its
+re-export (`packages/core/src/wirings/http/index.ts:23`). The comment at `:76-77`
+says the MCP SDK is the one caller that populates it, and that is outside this
+package.
+
+**What this rules out:** deriving `scopes`, `clientId` or `token` from the
+`Authorization` header inside core.

package/knowledge/decisions/security/virtual-user-catalogue-excludes-the-machinery-that-runs-virtual-users.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: The virtual user catalogue excludes any RPC scoped under virtualUser
+description: deriveCatalogue drops every function whose scope begins with virtualUser, so a virtual user holding those scopes cannot start runs, read findings or set schedules through the catalogue
+tags: core, virtual-users, catalogue, scopes
+---
+
+# The virtual user catalogue excludes any RPC scoped under virtualUser
+
+`packages/core/src/wirings/virtual-user/virtual-user-derive.ts` builds the catalogue of
+RPCs a virtual user could reach. It skips a function whose scope list contains any
+scope whose first segment is `virtualUser` (`virtual-user-derive.ts:38-46`, the
+test at line 44).
+
+The comment gives the reasons. A virtual user whose role carries `virtualUser:*` could
+otherwise start more runs, read every run's findings (an adversarial run's
+transcript is "working exploits against this same app"), and put a virtual user on a
+schedule "that outlives it" (`virtual-user-derive.ts:39-43`).
+
+The same function also skips scenario steps (`virtual-user-derive.ts:35`) and
+functions that are not exposed (`virtual-user-derive.ts:37`). Those rules are
+recorded in other notes.
+
+**What this rules out:** a virtual user reaching the run-control or schedule RPCs
+through its own catalogue, and an adversarial run reading its own findings.

package/knowledge/decisions/security/{actor-flow-missing-approval-decisions-default-to-denied.md → virtual-user-conversation-missing-approval-decisions-default-to-denied.md}

@@ -1,19 +1,19 @@
 ---
 type: decision
-title: An actor's missing approval decision defaults to denied
-description: 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
-tags: actor-flow
+title: A virtual user's missing approval decision defaults to denied
+description: Every pending tool call gets an explicit decision; an id the virtual user LLM omitted is denied, so a dropped field can never read as consent
+tags: virtual-user-conversation
 ---
 
-# An actor's missing approval decision defaults to denied
+# A virtual user's missing approval decision defaults to denied
 
 `decideApprovals` in
-`packages/core/src/wirings/actor-flow/run-conversation.ts` maps over the
-target agent's `pendingApprovals`, not over the decisions the persona LLM
+`packages/core/src/wirings/virtual-user/conversation/run-conversation.ts` maps over the
+target agent's `pendingApprovals`, not over the decisions the virtual user LLM
 returned. Any `toolCallId` the model omitted, hallucinated, or renamed resolves
 to `approved: false`.
 
-The persona's decision comes from a structured LLM call, and structured output
+The virtual user's decision comes from a structured LLM call, and structured output
 is not guaranteed to be complete. Iterating the model's array instead would make
 an omission indistinguishable from silence — and silence would let a scenario
 approve a destructive tool call nobody decided on, then pass.

package/knowledge/decisions/security/virtual-user-run-records-are-gated-behind-a-read-scope.md

@@ -0,0 +1,18 @@
+---
+type: decision
+title: Virtual user run records are privileged, and reads are gated behind their own scope
+description: The generated read RPCs carry virtualUser:read while starting a run carries virtualUser:run, because adversarial findings are working exploits with live ids
+tags: core, cli, virtual-users, scopes, security
+---
+
+# Virtual user run records are privileged, and reads sit behind a scope
+
+`packages/core/src/wirings/virtual-user/virtual-user-run-store.ts` defines where runs and their findings are kept. Its SECURITY note says findings from an `adversarial` run are "working exploits carrying live ids", so the store is "a privileged store". The scaffold "gates every read behind a scope for that reason", and a host that exposes these records more widely "is publishing its own exploits" (`virtual-user-run-store.ts:101-105`).
+
+The gate is generated by the CLI, not written in core. `packages/cli/src/functions/wirings/virtual-user/serialize-virtual-user-functions.ts` emits `scopes: ['virtualUser:read']` on `getVirtualUserRun` (line 393), `listVirtualUserRuns` (line 414), `getVirtualUserRunSteps` (line 435) and `listVirtualUserSchedules` (line 477). Starting a run is `scopes: ['virtualUser:run']` (line 328). The three scopes are declared by `defineScope` in the same file (lines 308-320), and `virtual-user-functions.test.ts` asserts each one (lines 53, 66, 149, 150).
+
+The disposition that makes findings sensitive is defined in `virtual-user.types.ts`, where `adversarial` "probes authorization and tenancy; a 2xx can be the finding" (`virtual-user.types.ts:15`).
+
+A virtual user cannot reach these RPCs through the catalogue, because the catalogue excludes any function whose scope starts with `virtualUser` (`virtual-user-derive.ts:38-46`).
+
+**What this rules out:** exposing run records, and their transcripts, to any caller who holds the virtual user's scopes but not `virtualUser:read`, and a virtual user starting or reading runs through its own catalogue.

package/knowledge/decisions/security/virtual-user-sign-in-does-not-exist-in-production.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: Virtual user sign-in endpoints do not exist in production
+description: The plugin registers the statement, in-process and switcher endpoints only when the sign-in gate is open at construction, and creating a row is dev-only
+tags: services
+---
+
+# Virtual user sign-in endpoints do not exist in production
+
+Virtual users never run in production, and the disposition and environment refusals
+enforce that at request time. On top of them, the plugin resolves
+`resolveVirtualUserSignIn()` once, at construction, and registers the statement
+endpoint, `signInVirtualUserInternal` and the switcher only when the gate is open —
+`pikku dev`, or the explicit stage opt-in. In production none of them is registered:
+there is no route to refuse and no handler to reach through `auth.api`.
+
+This replaces "always registered, refused per request" because a refusal is code that
+has to be right on every request, while an endpoint that was never built cannot be
+reached by a bug in it.
+
+Creating a row stays under `pikku dev`. A stage signs in only to virtual users
+provisioned at startup.
+
+**What this rules out:** deciding at request time whether the endpoint exists, and
+letting a stage create virtual user rows by signing in.

package/knowledge/decisions/security/virtual-user-sign-in-has-one-door.md

@@ -0,0 +1,42 @@
+---
+type: decision
+title: Virtual user sign-in has one door, reached two ways
+description: Only the app's virtual user sign-in handler creates a virtual user session; runs reach it in-process and everything else reaches it with a signed statement
+tags: services
+---
+
+# Virtual user sign-in has one door, reached two ways
+
+The `signIn` closure in the Better Auth virtual user plugin
+(`packages/services/better-auth/src/virtual-user-plugin.ts`) is the only thing that
+creates a virtual user session. It refuses any user row not flagged `virtualUser`,
+creates a row only under `pikku dev` (`mayProvision`), and sets the session cookie.
+Every route below ends in it; nothing else mints a session for a virtual user.
+
+**Runs go in-process.** A run — started by a person, or by the scheduled tick as
+`pikku-platform` holding only `virtualUser:run` — already executes inside the app, so
+it has nothing to prove to itself. It calls `auth.api.signInVirtualUserInternal`, an
+endpoint marked `metadata: { SERVER_ONLY: true }`: better-call leaves it out of the
+router, so `auth.handler` answers 404 for its path while `auth.api` can still call it.
+The seam is `services.auth`, which core already types structurally, so core imports
+nothing from Better Auth and a project without it gets an error that says so.
+
+**Everything outside the app presents a signed statement** — see
+[an external caller presents one signed statement](an-external-virtual-user-caller-presents-one-signed-statement.md).
+That covers the dev switcher, `pikku scenario run`, `pikku virtual-user run` and
+`rpc`, `pikku pages screenshot --as`, and the Playwright provider.
+
+Two choices fall out of this and are deliberate:
+
+- **Cookie, not bearer.** The run takes the `Set-Cookie` values from the in-process
+  call into the cookie jar core already has, then drives the app over HTTP with it.
+  Apps do not register Better Auth's bearer plugin and this does not make them.
+- **A public URL, not a service binding.** The run is a queue worker unit and the
+  existing bindings carry RPC, not HTTP. It reads `VIRTUAL_USER_API_URL` from
+  variables; `pikku dev` sets it once the port is bound, and a stage's deployer sets it
+  there. A missing value fails the run naming the variable. The same variable works on
+  a dev machine, a node box and a Worker.
+
+**What this rules out:** a second sign-in route with its own checks, a credential that
+is shared with, or derived for, a caller inside the app, and a bearer token handed
+back to a run.

package/knowledge/decisions/security/{actor-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md → virtual-user-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md}

@@ -1,23 +1,25 @@
 ---
 type: decision
-title: Actor sign-in is proven by Set-Cookie, not a non-empty jar
-description: HttpScenarioActor tracks its own signedIn flag and requires the sign-in response itself to set a cookie, because a populated jar proves nothing
+title: Virtual user sign-in is proven by Set-Cookie, not a non-empty jar
+description: HttpVirtualUser tracks its own signedIn flag and both VirtualUserSignIn implementations require the sign-in response itself to set a cookie, because a populated jar proves nothing
 tags: services
 ---
 
-# Actor sign-in is proven by Set-Cookie, not a non-empty jar
+# Virtual user sign-in is proven by Set-Cookie, not a non-empty jar
 
-`HttpScenarioActor` (`packages/core/src/services/http-scenario-actors.ts`) keeps
-a private `signedIn` boolean rather than inferring the session from its cookie
-jar, and `login()` throws when the sign-in response carries no `Set-Cookie`
-header even though the response was a 2xx.
+`HttpVirtualUser` (`packages/core/src/services/http-virtual-users.ts`) keeps a
+private `signedIn` boolean rather than inferring the session from its cookie
+jar. Both `VirtualUserSignIn` implementations in
+`packages/core/src/services/virtual-user-sign-in.ts` — `statementSignIn` and
+`inProcessSignIn` — throw when the sign-in response carries no `Set-Cookie`
+header, even though the response was a 2xx.
 
 A cookie jar cannot answer "did sign-in happen". A target app may set a cookie on
 any request — a CSRF token, an anonymous session, a locale — so a non-empty jar
 after a failed or skipped sign-in looks exactly like a successful one. What
 actually proves a session was established is _this_ response setting a cookie. A
 2xx alone is not enough either: an endpoint that returns 200 while quietly
-declining to issue a session would leave the actor running every subsequent
+declining to issue a session would leave the virtual user running every subsequent
 request unauthenticated, and the scenario would report the resulting refusals as
 genuine permission failures.
 

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

@@ -0,0 +1,29 @@
+---
+type: decision
+title: Virtual user sign-in only works for virtual-user-flagged users
+description: A virtual user statement mints sessions for user rows flagged virtual user and nothing else, so holding one never impersonates a real user
+tags: services
+---
+
+# Virtual user sign-in only works for virtual-user-flagged users
+
+A statement or an in-process call signs in only user rows flagged `virtualUser: true`
+(see [virtual user sign-in has one door](virtual-user-sign-in-has-one-door.md)). That
+could look like a master key, and it deliberately is not one — for two independent
+reasons.
+
+The first is the flag. The Better Auth virtual user plugin upserts and signs in only
+rows flagged `virtualUser: true`. A statement naming a real customer's address does not
+mint that customer's session — it is refused. The flag also flows into the minted
+session, so audits and analytics can tell scenario traffic from human traffic.
+
+The second is that a statement names one virtual user: `sub` must be a declared virtual
+user, and it expires and is accepted once — see
+[an external caller presents one signed statement](an-external-virtual-user-caller-presents-one-signed-statement.md).
+A leaked statement opens one synthetic account for a few minutes, not the population.
+
+**What this rules out:** widening the sign-in endpoint to accept any email "so
+scenarios can test as a real user", and treating a statement as
+equivalent to a session-signing key. It also rules out dropping the `virtualUser` flag
+from the minted session — the audit trail's ability to separate synthetic from
+real activity depends on it.