@pikku/core 0.12.143 → 0.12.144

package/knowledge/decisions/security/scaffold-features-are-authenticated-unless-opted-out.md

@@ -1,55 +0,0 @@
----
-type: decision
-title: A scaffolded surface is authenticated unless the config opts out in writing
-description: scaffold.<feature> became boolean | { auth, path }, where true means authenticated — going public requires typing { auth: false }, and the legacy 'auth' | 'no-auth' strings are refused rather than coerced
-tags: config, authorization, codegen, scaffold
----
-
-# A scaffolded surface is authenticated unless the config opts out in writing
-
-**Superseded by
-[[a-scaffold-flag-says-a-surface-exists-not-who-may-call-it]]**: the `auth`
-field is gone entirely, because the function runner already enforces each
-generated function's own auth. The reasoning below still explains why the
-legacy `'auth' | 'no-auth'` strings are refused rather than coerced.
-
-`scaffold.<feature>` was `'auth' | 'no-auth' | false`. Two things were wrong
-with it, and they compounded.
-
-The auth dimension asked the wrong question of some features and the right one
-of others. For `rpc` it is a blanket "no anonymous RPC in this app", set on a
-dispatcher that cannot know what it dispatches to — wrong the moment one
-legitimately public sessionless function exists. For `userAdmin` it was
-redundant: the generated functions are `pikkuFunc` with `scopes:
-['admin:users:list']`, gated twice over already. But for `agent`, `workflow`,
-`events` and `scenarios` it was the _only_ gate, because those generate real
-endpoints the app never authors and has nowhere else to declare a gate for.
-A uniform collapse to boolean would have silently opened four surfaces.
-
-And the value read like a preference. `"rpc": "no-auth"` looks like a
-starter-file setting; it was a live authorization decision, three directories
-from the functions it governed. That is the shape the console incident took.
-
-The type is now `boolean | { auth?: boolean; path?: string }`. `true` means
-enabled **and authenticated**; a surface becomes public only by writing
-`{ auth: false }`. Omitting a field can then never open anything — the failure
-mode of a forgotten flag is a locked door. Features with no auth dimension
-(`webhook`, `remoteRpc`, whose generator hardcodes `auth: false`) simply ignore
-it.
-
-The object form is also what makes the legacy strings safe to remove. An
-earlier design used `string` for the output path, under which `"no-auth"` would
-have parsed as _a file named `no-auth`_ — every unmigrated config silently
-producing nonsense instead of failing. With `boolean | object`, a string is
-never valid, so `resolveScaffoldFeature` refuses `'auth'` and `'no-auth'` by
-name and prints the replacement. Coercing them was rejected outright: the value
-it would coerce to is the one that caused the incident.
-
-Reading happens once, in `pikku-cli-config.ts`, so a legacy value fails at load
-with the migration named rather than downstream where it has already become
-something plausible.
-
-**What this rules out:** a bare `true` that means "public"; inferring a
-feature's auth posture from its default; using `string` for the output path
-while the legacy string values still exist in the wild; and collapsing the auth
-dimension uniformly across features that do not all have one.

package/knowledge/decisions/security/scenario-step-functions-are-never-externally-invocable.md

@@ -1,30 +0,0 @@
----
-type: decision
-title: Scenario-step functions are never externally invocable over RPC
-description: rpcExposed requires expose and rejects scenarioStep, so test steps stay reachable only from inside a scenario run
-tags: rpc
----
-
-# Scenario-step functions are never externally invocable over RPC
-
-`ContextAwareRPCService.rpcExposed` in
-`packages/core/src/wirings/rpc/rpc-runner.ts` is the entry point for RPCs that
-arrive from outside the process. It resolves the function's meta and throws
-`RPCNotFoundError` unless `functionMeta.expose` is set **and**
-`functionMeta.scenarioStep` is falsy — the same 404 an unknown name gets, so the
-existence of a hidden function is not disclosed.
-
-A scenario step is a piece of a test scenario: it may drive a browser, assert
-against fixtures, or reach for privileged setup helpers. Steps are dispatched by
-name from inside a scenario run through the internal `rpc` path, which does not
-consult `expose`. If a step were also reachable from the outside, any caller who
-guessed its name would get an unauthenticated handle on test tooling in whatever
-environment the scenario code shipped to.
-
-The two conditions are independent and both required: `expose` opts a function
-into the external surface, `scenarioStep` opts it back out regardless.
-
-**What this rules out:** collapsing the check to `!functionMeta.expose`,
-returning a distinct "forbidden" error that confirms the name exists, and routing
-external traffic through `rpc` instead of `rpcExposed` for convenience — `rpc`
-performs no exposure check at all.

package/knowledge/decisions/security/scope-resolution-happens-at-the-session-boundary-and-sync-never-deletes.md

@@ -1,28 +0,0 @@
----
-type: decision
-title: Scope resolution happens at the session boundary and scope sync never deletes
-description: ScopeService is called when a session is built, never by the function runner, and syncScopes only ever adds — revoking is an explicit operation
-tags: services
----
-
-# Scope resolution happens at the session boundary and scope sync never deletes
-
-Implementations of `ScopeService` (`packages/core/src/services/scope-service.ts`)
-are called at the session boundary — better-auth's `mapSession`, for instance —
-and never by the function runner. The runner reads `session.scopes` and performs
-no I/O of its own, which is what keeps it viable on Workers and Lambda. Because
-the session is rebuilt per request, a scope change takes effect on the next call:
-nothing is cached and there is nothing to invalidate.
-
-`syncScopes` is additive and never deletes. Scopes are declared in code, so a
-declaration removed in a deploy would otherwise revoke a live grant the moment
-the new build boots — silently, mid-rollout, for everyone holding it. Instead the
-row stays and goes inert: `listScopes` reports it as `declared: false`, no
-function can require it, `findStaleScopes` surfaces it for `pikku scopes audit`,
-and `pikku scopes prune` is the explicit act that removes it.
-
-**What this rules out:** having the function runner resolve scopes per call (it
-would put a store round-trip in every request path and break the Workers/Lambda
-story), caching resolved scopes anywhere, and making `syncScopes` reconcile —
-diffing declared against stored and deleting the difference. A deploy must never
-be able to revoke a grant as a side effect.

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

@@ -1,31 +0,0 @@
----
-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/self-authentication-is-declared-not-detected.md

@@ -1,34 +0,0 @@
----
-type: decision
-title: Self-authentication is declared, not detected
-description: A function that authorizes callers in its own body says so with selfAuthenticated; codegen never tries to infer it
-tags: permissions, codegen
----
-
-# Self-authentication is declared, not detected
-
-Some functions are genuinely closed while carrying no session, scope or
-permission: a webhook receiver that verifies a signature, a handler that
-redeems a signed invite, an exchange endpoint that validates a token before it
-does anything. Nothing in meta distinguishes those from a function nobody
-remembered to gate, so `validateExposedFunctionsGated` (PKU574) would warn about
-them on every build.
-
-The fix is a declaration — `selfAuthenticated: true` on the function config —
-not analysis of the body. Detection would have to recognise an open-ended set of
-authorization idioms, and it fails in the expensive direction: a body that
-_looks_ like it checks something silences the warning for a function that
-checks nothing. A declaration cannot be wrong by accident. Someone typed it,
-it is greppable, and it survives into meta where an audit reads it as what it
-is — a claim by a named author, not an inference.
-
-It carries no runtime effect and grants nothing. Its entire job is to move a
-gate that codegen cannot see into a place where a human can, and to keep PKU574
-worth reading: a warning that is usually wrong stops being read, which costs
-more than the warning ever saved.
-
-**What this rules out:** inferring self-authentication from the function body or
-from what it imports; giving `selfAuthenticated` any runtime meaning (it must
-never be a way to skip a check the runtime would otherwise run); and dropping
-the PKU574 warning instead, which was the alternative that would have left every
-genuinely ungated function silent too.

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

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

@@ -1,34 +0,0 @@
----
-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-content-urls-bind-the-request-path.md

@@ -1,37 +0,0 @@
----
-type: decision
-title: Signed content URLs bind the request path and verify fail-closed
-description: A signature that only carries timestamps authorizes every asset, and a verifier with no key must refuse rather than allow
-tags: content
----
-
-# Signed content URLs bind the request path and verify fail-closed
-
-`LocalContent` signs a payload containing the decoded request path, and the
-verifier in `pikku-node-http-server.ts` compares it against the path actually
-requested. `LocalContent` requires a `JWTService` and throws without one; a
-verifier with no key available rejects with 403 rather than allowing the
-request, logging once per process so an attacker-triggerable path cannot flood.
-
-A signature over `{signedAt, expiresAt, notBefore}` alone proves only _when_ a
-URL was issued, never _what_ it was issued for. Any valid token was a skeleton
-key: swap the pathname from a public thumbnail to a private document and the
-signature still verifies. Timestamps bound the window; only the path binds the
-asset.
-
-The path is the representation both signing entry points can produce and the
-verifier can reconstruct — it sees a request line, and cannot recover the
-bucket/key split from it. `signedContentPath` normalizes both sides identically
-(pathname only, origin and query dropped, `decodeURIComponent` falling back to
-the raw pathname on a malformed escape) so a difference in encoding cannot
-become a difference in verdict.
-
-`pikku serve` and `pikku dev` mint an ephemeral per-process signing key, so
-local content serving works with no configuration without shipping a fail-open
-path. URLs signed by one dev-server process are meaningless to the next, which
-is the correct lifetime for a dev secret.
-
-**What this rules out:** signing a URL without binding it to what it grants;
-returning "valid" from a verifier that could not check anything; normalizing the
-path differently on the two sides; and constructing `LocalContent` without a
-JWT service.

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

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

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

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

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

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

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

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

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

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

@@ -1,25 +0,0 @@
----
-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/virtual-user-conversation-missing-approval-decisions-default-to-denied.md

@@ -1,22 +0,0 @@
----
-type: decision
-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
----
-
-# A virtual user's missing approval decision defaults to denied
-
-`decideApprovals` in
-`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 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.
-
-**What this rules out:** building the decision list from the LLM's `decisions`
-array, and defaulting an unmatched call to `true` to keep a conversation moving.

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

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

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